fix(cdk)!: rename DotStack.env to envName for aws-cdk-lib >=2.234.0 compat

[hyuntony]

This PR contains a:

• bugfix
• feature
• refactor
• documentation
• other

Are tests included?

• yes
• no

Breaking Changes?

• yes
• no

Description

In aws-cdk-lib 2.234.0 (released 2026-01-08, via aws/aws-cdk#36599), the parent Stack.env was changed from a writable property to a getter that returns the resolved AWS Environment object ({ account, region }). DotStack's constructor does this.env = env; (where env is the deploy-environment string 'prod'/'dev'/etc.), which now throws:

TypeError: Cannot set property env of [object Object] which has only a getter.

This collision has existed conceptually for a while — DotStack repurposed the parent's env name to mean "deploy-env string" rather than "AWS environment object" — but the runtime didn't surface it until aws-cdk-lib hardened the property descriptor.

Resolution

Rename the deploy-environment string field on DotStack from env to envName, leaving the parent's Stack.env getter unshadowed. After this change:

• stack.envName returns the deploy-environment string ('prod', 'dev', etc.).
• stack.env returns the inherited aws-cdk-lib getter ({ account, region }).

All internal call sites that read scope.env as a string have been updated to scope.envName (amplify.ts, dynamo.ts, fargate.ts, function.ts, node-function.ts, signing.ts, ws.ts). This includes two destructured-access patterns (const { env } = scope) in fargate.ts and node-function.ts that would silently break otherwise.

The node.setContext('env', this.envName) call preserves the context key 'env' for backwards compatibility — consumer code reading node.tryGetContext('env') continues to work.

Adjacent dep alignment

Tightened a couple of pre-existing dep mismatches with the new aws-cdk-lib floor while we're here:

• peerDependencies.aws-cdk-lib: added at ^2.234.0 (was previously dependencies-only; now correctly dedupes with the consumer's CDK install).
• dependencies.aws-cdk-lib: bumped from ^2.185.0 to ^2.234.0.
• engines.node: >=18 → >=20 (matches aws-cdk-lib@2.251.0's engine requirement).
• constructs: ^10.4.2 → ^10.5.0 (matches aws-cdk-lib@2.251.0's peer requirement).

Happy to split those out if you'd prefer the PR scope to stay strictly on the env rename.

Verification

• ✅ pnpm --filter @dot/cdk build passes (TypeScript compile).
• ✅ pnpm lint clean (one pre-existing warning in security.ts, unrelated).
• ✅ Smoke-tested: instantiating new DotStack(app, { name: 'smoke' }) with DEPLOY_ENV=prod now succeeds (no TypeError); stack.envName === 'prod'; stack.env returns the parent getter's { account, region }.
• ✅ grep -rn "scope\\.env\\b\\|this\\.env\\b" packages/cdk/src/ empty — no straggling string-env reads.

Migration

A "Migrating from v4 to v5" section has been added to packages/cdk/README.md summarizing the rename and flagging the destructured / template-literal cases that consumers might miss.

BREAKING CHANGES: DotStack.env is renamed to DotStack.envName. Consumer code reading stack.env as a deploy-environment string should be updated to stack.envName. The node.tryGetContext('env') context key is unchanged.

[shellscape]

Suggested change

	"version": "5.0.0",
	"version": "4.2.1",

This is automatic with release tooling.

[shellscape]

Suggested change

	"node": ">=20"
	"node": ">=22"

Node 20 is end of life in 3 days

[hyuntony]

Happy to make this change, I was matching the aws-cdk-lib's engine requirements here

[shellscape]

Suggested change

"aws-cdk-lib": "^2.234.0",

It's already a direct dependency