feat: align the python starter kit with the typescript one

[dannysteenman]

Summary

The TypeScript starter kit has been where new features land, and this kit drifted behind it. This closes the gap: same project structure, same deployment model, same CI.

Stacked on #19 and targeting that branch, so this diff shows only the realignment. It retargets to main automatically once #19 merges.

What changed

Structure

	Before	After
Stacks	BaseStack, GitHubOIDCStack	StarterStack, FoundationStack
Constructs	BaseConstruct, NetworkConstruct	plus GitHubActionsOidcConstruct
Aspects	none	permission boundary, S3 encryption, S3 public access, VPC CIDR

FoundationStack holds the account-level plumbing: the deploy role plus a CDK toolkit cleaner, which is what stops the staging bucket growing with every deployment. The OIDC role moved out of the stack into its own construct, matching the TS layout.

The constructs folder keeps the name custom_constructs. A src/constructs package would shadow the constructs pip package that every CDK module imports.

Deployments

EnvironmentConfig replaces the target_accounts dict, with test (branch deploys on) and production. List order is deployment order: cdk-deploy-production chains onto cdk-deploy-test completing, and only runs when it succeeded.

Branch deployments work like the TS kit. GIT_BRANCH_REF names stacks after the branch, so several developers share one account without collisions:

$ ENVIRONMENT=test uv run cdk ls
FoundationStack-test
StarterStack-test

$ ENVIRONMENT=test GIT_BRANCH_REF=feature/add-api uv run cdk ls
StarterStack-add-api

FoundationStack drops out of branch deployments on purpose: a feature branch has no business recreating the role its own pipeline assumes. Test-environment branch deploys and destroys use CDK express mode, and deleting the branch triggers the destroy workflow.

Tasks gain the :all / :stack split, ls, and a branch-only deploy:hotswap.

CI

Nothing ran tests in CI before, which is how the broken pytest setup in #19 went unnoticed. Now:

• build.yml runs ruff, ty, pytest and synth on every PR, with projen's self-mutation push so a stale generated file can't merge. ruff and ty are wired into the projen test task, so they run locally too.
• cdk-diff-pr-comment posts a diff against production on pull requests.
• release.yml tags and publishes a GitHub release when the project version changes.
• The CDK CLI now comes from the pinned aws-cdk-cli PyPI package instead of npm install -g aws-cdk, so cdk_cli_version actually pins something and no workflow needs Node.js set up.

Two places a literal port would have broken

BucketPublicAccessAspect cannot read its own property. jsii can't deserialize a struct set from the TypeScript side, so node.public_access_block_configuration raises ValueError: Unknown interface on any bucket built through the Bucket L2 construct. The TS aspect reads it directly. Ported as-is, this crashes synthesis on the most common case: a bucket that correctly blocks public access. The aspect catches it and leaves those buckets alone; the case it exists to catch, a bucket with no configuration, reads cleanly as None and is still corrected. test_aspects.py covers both.

GitHub ignores a branches filter on delete events. The TS destroy workflow emits one, and projen's Python DeleteOptions rejects the argument outright. The exclusions moved into the job condition, generated from the same BRANCH_EXCLUSIONS list:

if: github.event_name == 'workflow_dispatch' || (github.event.ref_type == 'branch' && github.event_name == 'delete' && github.event.ref != 'main' && !startsWith(github.event.ref, 'hotfix/') && ...)

Breaking changes

Both hit anyone who already deployed this kit.

1. The deploy role is renamed from GitHubDeployRole to GitHubActionsServiceRole, matching the TS kit and GITHUB_DEPLOY_ROLE. Redeploy FoundationStack before the workflows can assume it.
2. Environments changed from dev + test to test + production. The dev:* tasks and cdk-deploy-dev workflow are gone.

The trust policy also gains an environment: segment, so a deploy job must declare a matching GitHub environment. The generated workflows already do.

Where it still differs from the TypeScript kit

• Release: projen's release component derives the next version from conventional commits and has no Python equivalent. This uses the version in .projenrc.py as the trigger instead: bump it, merge, and the workflow tags and publishes with generated notes.
• Dependency upgrades: Dependabot, already configured with auto-approve and auto-merge, rather than projen's upgrade-main. Adding both would open competing PRs.
• VPC CIDR aspect: stdlib ipaddress instead of the netmask package, so no new dependency.

Diagram

flowchart TD
  PR["Pull request"] --> Build["build.yml: ruff, ty, pytest, synth"]
  PR --> Diff["cdk-diff-pr-comment"]
  Push["Push to main"] --> Test["cdk-deploy-test"]
  Test -->|"workflow_run success"| Prod["cdk-deploy-production"]
  Push --> Release["release.yml: tag on version change"]
  Branch["Push a feature branch"] --> BranchDeploy["cdk-deploy-test-branch (express mode)"]
  Delete["Delete the branch"] --> Destroy["cdk-destroy-test-branch"]
  BranchDeploy --> Stacks["StarterStack-<branch>"]
  Test --> Shared["FoundationStack-test + StarterStack-test"]

Loading

Validation

• uv run projen build: 62 tests pass, ruff and ty clean
• cdk ls verified for both the shared and branch cases, output above
• New tests: test_aspects.py (14), test_env_helper.py (21), test_foundation_stack.py rewritten for the new stack
• Docs updated: root README structure and branch-deploy section, src/stacks/README.md, src/custom_constructs/README.md, new src/aspects/README.md