@go-to-k/cdkd 0.158.1 → 0.159.1

package/README.md

@@ -13,23 +13,6 @@ Drop-in CDK CLI for existing CDK apps — faster deploys via AWS SDK instead of
 > [!IMPORTANT]
 > cdkd is for dev/test workflows only — early in development, not yet production-ready.
 
-## Features
-
-- **Synthesis orchestration**: CDK app subprocess execution, Cloud Assembly parsing, context provider loop
-- **Asset handling**: Self-implemented asset publisher for S3 file assets (ZIP packaging) and Docker images (ECR)
-- **Context resolution**: Self-implemented context provider loop for Vpc.fromLookup(), AZ, SSM, HostedZone, etc.
-- **Hybrid provisioning**: SDK Providers for fast direct API calls, Cloud Control API fallback for broad resource coverage
-- **Diff calculation**: Self-implemented resource/property-level diff between desired template and current state
-- **S3-based state management**: No DynamoDB required, uses S3 conditional writes for locking
-- **DAG-based parallelization**: Analyze `Ref`/`Fn::GetAtt` dependencies and execute in parallel
-- **Rollback on failure**: When a deploy errors mid-stack, cdkd rolls back the resources it just created so the stack state stays consistent (CloudFormation parity — but cdkd does this without round-tripping through CFn). Pass `cdkd deploy --no-rollback` to skip rollback and keep the partial state for Terraform-style inspection / repair. See [Rollback behavior](#rollback-behavior).
-- **`--no-wait` for async resources**: Skip the multi-minute wait on CloudFront / RDS / ElastiCache / NAT Gateway and return as soon as the create call returns (CloudFormation always blocks)
-- **VPC route DependsOn relaxation (on by default)**: Drop CDK-injected defensive `DependsOn` edges from VPC Lambdas onto private-subnet routes so `CloudFront::Distribution` and `Lambda::Url` start their ~3-min propagation in parallel with NAT Gateway stabilization (~50% faster on VPC + Lambda + CloudFront stacks). Pass `--no-aggressive-vpc-parallel` to opt out.
-- **Local execution** (`cdkd local invoke` / `start-api` / `run-task` / `start-service`): run Lambdas, API Gateway routes, ECS tasks and long-running ECS services from your CDK code via Docker. All AWS Lambda runtimes, container Lambdas, REST v1 / HTTP v2 / Function URL routes, Service Connect / Cloud Map. Works for both `cdkd deploy`-managed (`--from-state`) AND `cdk deploy`-managed (`--from-cfn-stack`) stacks. See [Local execution](#local-execution).
-- **Bidirectional CloudFormation migration**: `cdkd import --migrate-from-cloudformation` adopts existing CFn stacks (including `cdk deploy`-managed) into cdkd state without re-creating resources; `cdkd export` hands a cdkd stack back to CloudFormation when production-ready. See [Importing](#importing-existing-resources) / [Exporting](#exporting-a-stack-back-to-cloudformation).
-
-> **Note**: Resource types not covered by either SDK Providers or Cloud Control API cannot be deployed with cdkd. Deployment fails with a clear error message naming the type + a 1-click issue link.
-
 ## Benchmark
 
 **cdkd deploys up to 15x faster than AWS CDK (CloudFormation)** on SDK-Provider-handled stacks; the per-stack speedup widens with size and parallelism, and drops to ~1.5-3x on stacks dominated by Cloud Control API fallback resources.
@@ -64,6 +47,23 @@ Stack: SSM Document × 3 + Athena WorkGroup × 2 (no SDK provider — CC API fal
 
 Reproduce the first two with `./tests/benchmark/run-benchmark.sh all`. See [tests/benchmark/README.md](tests/benchmark/README.md) for details.
 
+## Features
+
+- **Synthesis orchestration**: CDK app subprocess execution, Cloud Assembly parsing, context provider loop
+- **Asset handling**: Self-implemented asset publisher for S3 file assets (ZIP packaging) and Docker images (ECR)
+- **Context resolution**: Self-implemented context provider loop for Vpc.fromLookup(), AZ, SSM, HostedZone, etc.
+- **Hybrid provisioning**: SDK Providers for fast direct API calls, Cloud Control API fallback for broad resource coverage
+- **Diff calculation**: Self-implemented resource/property-level diff between desired template and current state
+- **S3-based state management**: No DynamoDB required, uses S3 conditional writes for locking
+- **DAG-based parallelization**: Analyze `Ref`/`Fn::GetAtt` dependencies and execute in parallel
+- **Rollback on failure**: When a deploy errors mid-stack, cdkd rolls back the resources it just created so the stack state stays consistent (CloudFormation parity — but cdkd does this without round-tripping through CFn). Pass `cdkd deploy --no-rollback` to skip rollback and keep the partial state for Terraform-style inspection / repair. See [Rollback behavior](#rollback-behavior).
+- **`--no-wait` for async resources**: Skip the multi-minute wait on CloudFront / RDS / ElastiCache / NAT Gateway and return as soon as the create call returns (CloudFormation always blocks)
+- **VPC route DependsOn relaxation (on by default)**: Drop CDK-injected defensive `DependsOn` edges from VPC Lambdas onto private-subnet routes so `CloudFront::Distribution` and `Lambda::Url` start their ~3-min propagation in parallel with NAT Gateway stabilization (~50% faster on VPC + Lambda + CloudFront stacks). Pass `--no-aggressive-vpc-parallel` to opt out.
+- **Local execution** (`cdkd local invoke` / `start-api` / `run-task` / `start-service`): run Lambdas, API Gateway routes, ECS tasks and long-running ECS services from your CDK code via Docker. All AWS Lambda runtimes, container Lambdas, REST v1 / HTTP v2 / Function URL routes, Service Connect / Cloud Map. Works for both `cdkd deploy`-managed (`--from-state`) AND `cdk deploy`-managed (`--from-cfn-stack`) stacks. See [Local execution](#local-execution).
+- **Bidirectional CloudFormation migration**: `cdkd import --migrate-from-cloudformation` adopts existing CFn stacks (including `cdk deploy`-managed) into cdkd state without re-creating resources; `cdkd export` hands a cdkd stack back to CloudFormation when production-ready. See [Importing](#importing-existing-resources) / [Exporting](#exporting-a-stack-back-to-cloudformation).
+
+> **Note**: Resource types not covered by either SDK Providers or Cloud Control API cannot be deployed with cdkd. Deployment fails with a clear error message naming the type + a 1-click issue link.
+
 ## How it works
 
 ```
@@ -159,229 +159,57 @@ cdkd has three command families:
   use them to inspect / clean up state when the source is gone or
   you don't want to synth. `cdkd state destroy` is the CDK-app-free
   counterpart of `cdkd destroy`.
-- **`cdkd local ...` subcommands** (`local invoke`, `local start-api`,
-  `local run-task`, `local start-service`) run synthesized workloads
-  locally inside Docker containers. The Lambda variants (`local invoke` /
-  `local start-api`) bundle the AWS Lambda Runtime Interface Emulator
-  (RIE); `local invoke` runs a single Lambda once, and `local start-api`
-  stands up a long-running HTTP server that maps API Gateway / HTTP API /
-  Function URL routes to local Lambda invocations. `local run-task` is
-  the ECS one-shot counterpart — it locates an
-  `AWS::ECS::TaskDefinition` from the synthesized template and stands
-  up every container in `dependsOn` order on a per-task docker network
-  with the AWS-published metadata endpoints sidecar, so containers see
-  `ECS_CONTAINER_METADATA_URI_V4` (and optionally task-role creds via
-  `--assume-task-role`) just like they would on Fargate / ECS.
-  `local start-service` is the long-running counterpart for
-  `AWS::ECS::Service`: it discovers the service, chains into the same
-  per-task machinery for each `DesiredCount` replica (clamped by
-  `--max-tasks`), and keeps every replica running until `^C` — failed
-  replicas restart per `--restart-policy on-failure|always|none`. It
-  also accepts multiple service targets in one invocation
-  (`cdkd local start-service Stack/Orders Stack/Frontend`); per-service
-  `AWS::ServiceDiscovery::PrivateDnsNamespace` / `Service` +
-  `ServiceConnectConfiguration` / `ServiceRegistries[]` blocks are
-  parsed and each booted replica's container IP is published to a
-  shared in-process Cloud Map registry, then injected into the next
-  service's containers via docker `--add-host <fqdn>:<ip>` so
-  `wget http://orders/` from inside the `frontend` container resolves
-  via `/etc/hosts` to the orders replica (boot targets in
-  producer-then-consumer order; see [docs/local-emulation.md](docs/local-emulation.md)
-  for v1 limitations — first-wins for multi-replica routing, no SRV
-  records, no Envoy L7). No AWS API calls beyond optional STS / Secrets
-  resolution, no state bucket needed. Local load-balancer emulation and
-  `--watch` hot-reload for `start-service` are deferred to follow-up
-  PRs.
+- **`cdkd local ...` subcommands** (`local invoke` / `start-api` /
+  `run-task` / `start-service`) run synthesized workloads locally
+  inside Docker containers — no AWS deploy needed. Modeled on
+  `sam local *` but reads CDK state directly via `--from-state`
+  (cdkd-managed) or `--from-cfn-stack` (CFn-managed). See
+  [Local execution](#local-execution).
 
 Options like `--app`, `--state-bucket`, and `--context` can be omitted if configured via `cdk.json` or environment variables (`CDKD_APP`, `CDKD_STATE_BUCKET`).
 
 ```bash
-# Bootstrap (create S3 bucket for state)
-cdkd bootstrap \
-  --state-bucket my-cdkd-state \
-  --region us-east-1
-
-# Synthesize only
-cdkd synth --app "node app.ts"
-
-# List all stacks in the CDK app (alias: ls)
-cdkd list
-cdkd ls
-cdkd list --long              # YAML records with id/name/environment
-cdkd list --long --json       # same, but JSON
-cdkd list --show-dependencies # id + dependency list per stack
-cdkd list 'MyStage/*'         # filter by display path (CDK CLI parity)
-
-# Deploy from a pre-synthesized cloud assembly directory
-cdkd deploy --app cdk.out
-
-# Deploy (single stack auto-detected, reads --app from cdk.json)
-cdkd deploy
-
-# Deploy specific stack(s)
-cdkd deploy MyStack
-cdkd deploy Stack1 Stack2
-
-# Deploy all stacks
+# Synth + deploy
+cdkd synth
+cdkd deploy                         # single-stack auto-detected
+cdkd deploy MyStack                 # by name (or 'MyStage/Api' display path)
 cdkd deploy --all
+cdkd deploy --dry-run               # plan only, no changes
+cdkd deploy --no-rollback           # Terraform-style: keep partial state on failure
+cdkd deploy --no-wait               # skip multi-minute waits (CloudFront / RDS / NAT)
 
-# Deploy with wildcard (matched against the physical CloudFormation stack name)
-cdkd deploy 'My*'
-
-# Deploy stacks under a CDK Stage using the hierarchical path (CDK CLI parity)
-# Patterns containing '/' are routed to the CDK display path; both forms work:
-cdkd deploy 'MyStage/*'        # all stacks under MyStage
-cdkd deploy MyStage/Api        # specific stack by display path
-cdkd deploy MyStage-Api        # same stack by physical CloudFormation name
-
-# Deploy with context values
-cdkd deploy -c env=staging -c featureFlag=true
-
-# Deploy with explicit options
-cdkd deploy MyStack \
-  --app "node app.ts" \
-  --state-bucket my-cdkd-state \
-  --verbose
-
-# Show diff (what would change)
+# Inspect what would change
 cdkd diff MyStack
-cdkd diff MyParent --recursive       # also diff every nested-stack child vs its own state (#555 A5)
-cdkd diff MyParent --recursive --json  # nested {stack, changes, children: [...]} JSON
-cdkd diff MyStack --fail             # exit 1 when any change is detected (CI gate; matches cdk diff --fail)
-
-# Detect drift between cdkd state and AWS reality (state-only; no synth)
-# Exits 0 with no drift, 1 when drift is detected, 2 on partial revert failure.
-cdkd drift MyStack
-cdkd drift --all --json
+cdkd diff MyStack --fail            # exit 1 on any change (CI gate)
 
-# Resolve drift: state ← AWS (catch up state with manual console changes)
-cdkd drift MyStack --accept --yes
+# Drift detection — compare state vs AWS reality (no synth)
+cdkd drift MyStack                  # exit 1 if drift
+cdkd drift MyStack --accept --yes   # state ← AWS
+cdkd drift MyStack --revert --yes   # AWS ← state
 
-# Resolve drift: AWS ← state (push state values back into AWS via provider.update)
-cdkd drift MyStack --revert --yes
-
-# Refresh the deploy-time AWS snapshot used as drift baseline.
-# Optional — `cdkd deploy` itself auto-refreshes on the first deploy after
-# upgrading from a pre-v3 cdkd binary (= state schema `version: 2`), in
-# parallel with the deploy at no critical-path cost. This command is the
-# manual / non-deploy path: run it when you want the baseline refreshed
-# without redeploying (e.g. for resources that won't change in any
-# near-future deploy). Idempotent on the same v3 state — see "Drift
-# detection" below for the full upgrade story.
-cdkd state refresh-observed MyStack
-
-# Dry run (plan only, no changes)
-cdkd deploy --dry-run
-
-# Deploy with no rollback on failure (Terraform-style)
-cdkd deploy --no-rollback
-
-# Deploy only the specified stack (skip dependency auto-inclusion)
-cdkd deploy -e MyStack
-
-# Skip the multi-minute wait on async resources (CloudFront, RDS, NAT GW, etc.)
-cdkd deploy --no-wait
-
-# Synth + build + publish assets only (no deploy) — typical CI split
-cdkd publish-assets
-
-# Destroy resources
+# Asset / destroy / unlock
+cdkd publish-assets                 # synth + upload only (typical CI split)
 cdkd destroy MyStack
-cdkd destroy --all --force
+cdkd force-unlock MyStack           # clear stale lock from an interrupted deploy
 
-# Force-unlock a stale lock from interrupted deploy
-cdkd force-unlock MyStack
-
-# Adopt already-deployed AWS resources into cdkd state.
-# See docs/import.md for the full guide (auto / selective / hybrid modes,
-# --resource overrides, --resource-mapping CDK CLI compatibility).
-cdkd import MyStack --dry-run
+# Adopt existing AWS resources into cdkd state
 cdkd import MyStack --yes
 
-# Inspect state-bucket info on demand (bucket name, region, source, schema version, stack count).
-# Routine commands (deploy / destroy / etc.) no longer print the bucket banner by default —
-# pass --verbose to surface it in their debug logs, or use this subcommand for an explicit answer.
-cdkd state info
-cdkd state info --json        # JSON output for tooling
-cdkd state info --state-bucket my-bucket  # explicit bucket; reports Source: --state-bucket flag
-
-# List stacks registered in the cdkd state bucket
-cdkd state list
-cdkd state ls --long          # include resource count, last-modified, lock status
-cdkd state list --json        # JSON output (alone, or combined with --long)
-cdkd state list --tree        # parent → child stack tree (nested stacks; #555 A3)
-cdkd state list --tree --json # tree as nested JSON
-
-# List resources of a single stack from state
-cdkd state resources MyStack          # aligned columns: LogicalID, Type, PhysicalID
-cdkd state resources MyStack --long   # per-resource block with dependencies and attributes
-cdkd state resources MyStack --json   # full JSON array
-
-# Show full state record for a stack (metadata, outputs, all resources incl. properties)
-cdkd state show MyStack
-cdkd state show MyStack --json              # raw {state, lock} JSON
-cdkd state show MyParent --show-nested      # recursively show every nested-stack child (#555 A4)
-cdkd state show MyParent --show-nested --json  # tree as nested {state, lock, children: [...]} JSON
-
-# Orphan one or more RESOURCES from cdkd's state (does NOT delete AWS resources).
-# Per-resource, mirrors aws-cdk-cli's `cdk orphan --unstable=orphan`.
-# Synth-driven — needs --app / cdk.json. Construct paths use CDK's L2-style form
-# (`<StackName>/<Path/To/Construct>`); the synthesized `/Resource` suffix is
-# matched implicitly. Passing an L2 wrapper that contains multiple CFn resources
-# orphans every child under it (matches upstream's prefix-match semantics).
-cdkd orphan MyStack/MyTable                    # confirmation prompt (y/N)
-cdkd orphan MyStack/MyTable --yes
-cdkd orphan MyStack/MyTable MyStack/MyBucket   # multiple resources, same stack
-cdkd orphan MyStack/MyTable --dry-run          # print rewrite audit, no save
-cdkd orphan MyStack/MyTable --force            # also fall back to cached
-                                               # attributes when live fetch fails
-
-# State-driven counterpart that orphans a WHOLE STACK's state record
-# (no CDK app needed — works against the bucket).
-cdkd state orphan MyStack             # confirmation prompt (y/N)
-cdkd state orphan MyStack --yes       # skip confirmation
-cdkd state orphan StackA StackB --force # also bypass the locked-stack refusal
-
-# Destroy a stack's AWS resources AND remove its state record, without
-# requiring the CDK app (no synth — works from any working directory).
-cdkd state destroy MyStack            # per-stack confirmation prompt
-cdkd state destroy MyStack OtherStack --yes
-cdkd state destroy --all -y           # every stack in the bucket
-cdkd state destroy MyStack --region us-east-1
+# State-bucket-only commands (no CDK app needed)
+cdkd state info                     # bucket name, region, schema version
+cdkd state list                     # one row per (stackName, region)
+cdkd state list --tree              # parent → child nested-stack tree
+cdkd state show MyStack             # full state record
+cdkd state resources MyStack        # logical id / type / physical id
+cdkd state destroy MyStack          # delete AWS resources + state, no CDK app
+cdkd state orphan MyStack           # remove state record only (AWS resources stay)
 ```
 
-## Compatibility
-
-cdkd supports the standard CloudFormation surface — intrinsic functions,
-pseudo parameters, parameters / conditions, cross-stack / cross-region
-references, asset publishing, custom resources, and so on. See
-**[docs/supported-features.md](docs/supported-features.md)** for the
-full reference. For per-resource-type provisioning support (SDK Providers
-vs Cloud Control API fallback), see
-**[docs/supported-resources.md](docs/supported-resources.md)**.
-
-**Property-level coverage is incremental.** SDK Providers wire most but not every CFn property of a supported type. cdkd fails fast at pre-flight when a template uses a not-yet-implemented property, with the property name + a 1-click issue link. `--allow-unsupported-properties <Type>:<Prop>,...` is the safety valve when this is too strict (e.g. mid-life update on an existing resource); avoid it on security-meaningful properties (encryption / IAM / TLS). See [docs/cli-reference.md](docs/cli-reference.md#--allow-unsupported-properties-deploy).
-
-## Rollback behavior
-
-When a deploy fails mid-stack (e.g. a resource hits a validation error
-or AWS rejects the request), cdkd by default **rolls back the
-already-completed resources in the same deploy** so the stack state
-stays consistent — every resource cdkd just created in this run is
-deleted in reverse dependency order, the state record is updated to
-match, and the CLI exits non-zero. Resources that existed before this
-deploy are NOT touched.
-
-Pass `cdkd deploy --no-rollback` to skip the rollback (Terraform-style:
-the partial state is preserved so you can `cdkd state show <stack>`,
-inspect what landed, fix the underlying issue, and re-run `cdkd deploy`
-to continue from the half-deployed state). Recommended only when you
-plan to manually inspect / repair; the default is safer for CI.
-
-Mid-deploy state is also saved per-resource as work completes, so even
-if cdkd itself crashes between the failure and the rollback, the state
-file accurately reflects what's on AWS and a follow-up `cdkd destroy`
-won't orphan anything.
+See **[docs/cli-reference.md](docs/cli-reference.md)** for the full flag
+matrix (`--concurrency`, `--no-aggressive-vpc-parallel`,
+`--allow-unsupported-properties`, `--role-arn`, etc.), per-command details
+including the synth-driven per-resource `cdkd orphan <constructPath>`
+variant, and stage / wildcard pattern matching.
 
 ## `--no-wait`: skip async-resource waits
 
@@ -397,20 +225,6 @@ See [docs/cli-reference.md](docs/cli-reference.md#--no-wait-skip-async-resource-
 for per-resource caveats (NAT egress, RDS final-snapshot timing,
 etc.).
 
-## VPC route DependsOn relaxation (on by default)
-
-CDK injects defensive `DependsOn` from VPC Lambdas onto private-subnet
-routes. The dependency is real at runtime but NOT required at deploy
-time. cdkd drops it by default so CloudFront + Lambda::Url propagation
-runs in parallel with NAT stabilization (~50% faster on VPC+Lambda+CloudFront
-stacks; bench-cdk-sample 398s → 181s). Pass
-`cdkd deploy --no-aggressive-vpc-parallel` to opt out (e.g. when a
-Custom Resource synchronously invokes a VPC Lambda outside cdkd's
-Lambda-ServiceToken Active wait).
-
-See [docs/cli-reference.md](docs/cli-reference.md) for the full
-type-pair allowlist and trade-off notes.
-
 ## Local execution
 
 The `cdkd local` family runs AWS workloads on the developer's machine
@@ -455,7 +269,8 @@ cdkd local start-api --from-state                    # OR --from-cfn-stack
 REST v1 + HTTP API v2 + Function URL with all integration kinds
 (AWS_PROXY / MOCK / HTTP_PROXY / HTTP / AWS Lambda non-proxy via
 hand-rolled VTL), authorizers (Lambda / Cognito / HTTP v2 JWT /
-REST v1 AWS_IAM SigV4), CORS, stage variables, `--watch` hot reload.
+AWS_IAM SigV4 on REST v1 + Function URL), CORS, stage variables,
+`--watch` hot reload.
 
 ### `local run-task`
 
@@ -484,6 +299,27 @@ full reference — runtimes, target resolution, every flag, integration
 and authorizer detail, route precedence, container pool, networking,
 `--from-cfn-stack` semantics, v1 scope.
 
+## Rollback behavior
+
+When a deploy fails mid-stack (e.g. a resource hits a validation error
+or AWS rejects the request), cdkd by default **rolls back the
+already-completed resources in the same deploy** so the stack state
+stays consistent — every resource cdkd just created in this run is
+deleted in reverse dependency order, the state record is updated to
+match, and the CLI exits non-zero. Resources that existed before this
+deploy are NOT touched.
+
+Pass `cdkd deploy --no-rollback` to skip the rollback (Terraform-style:
+the partial state is preserved so you can `cdkd state show <stack>`,
+inspect what landed, fix the underlying issue, and re-run `cdkd deploy`
+to continue from the half-deployed state). Recommended only when you
+plan to manually inspect / repair; the default is safer for CI.
+
+Mid-deploy state is also saved per-resource as work completes, so even
+if cdkd itself crashes between the failure and the rollback, the state
+file accurately reflects what's on AWS and a follow-up `cdkd destroy`
+won't orphan anything.
+
 ## Importing existing resources
 
 `cdkd import` adopts AWS resources that are already deployed (via
@@ -583,6 +419,20 @@ Two `orphan` variants at different granularities:
 Both `cdkd destroy` (synth-driven) and `cdkd state destroy`
 (state-driven, no synth) delete AWS resources + state.
 
+## VPC route DependsOn relaxation (on by default)
+
+CDK injects defensive `DependsOn` from VPC Lambdas onto private-subnet
+routes. The dependency is real at runtime but NOT required at deploy
+time. cdkd drops it by default so CloudFront + Lambda::Url propagation
+runs in parallel with NAT stabilization (~50% faster on VPC+Lambda+CloudFront
+stacks; bench-cdk-sample 398s → 181s). Pass
+`cdkd deploy --no-aggressive-vpc-parallel` to opt out (e.g. when a
+Custom Resource synchronously invokes a VPC Lambda outside cdkd's
+Lambda-ServiceToken Active wait).
+
+See [docs/cli-reference.md](docs/cli-reference.md) for the full
+type-pair allowlist and trade-off notes.
+
 ## `--remove-protection`: one-shot bypass for protected resources
 
 `cdkd destroy --remove-protection` (and `cdkd state destroy --remove-protection`)
@@ -632,6 +482,18 @@ cdkd publish-assets -a cdk.out       # skip synth, use pre-synthesized assembly
 See [docs/cli-reference.md](docs/cli-reference.md#publish-assets-synth--build--publish-no-deploy)
 for stack-selection rules and concurrency knobs.
 
+## Compatibility
+
+cdkd supports the standard CloudFormation surface — intrinsic functions,
+pseudo parameters, parameters / conditions, cross-stack / cross-region
+references, asset publishing, custom resources, and so on. See
+**[docs/supported-features.md](docs/supported-features.md)** for the
+full reference. For per-resource-type provisioning support (SDK Providers
+vs Cloud Control API fallback), see
+**[docs/supported-resources.md](docs/supported-resources.md)**.
+
+**Property-level coverage is incremental.** SDK Providers wire most but not every CFn property of a supported type. cdkd fails fast at pre-flight when a template uses a not-yet-implemented property, with the property name + a 1-click issue link. `--allow-unsupported-properties <Type>:<Prop>,...` is the safety valve when this is too strict (e.g. mid-life update on an existing resource); avoid it on security-meaningful properties (encryption / IAM / TLS). See [docs/cli-reference.md](docs/cli-reference.md#--allow-unsupported-properties-deploy).
+
 ## State Management
 
 State is stored in S3 with optimistic locking via S3 Conditional Writes

package/dist/cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { _ as withSkipPrefix, a as runDockerStreaming, c as getLogger, d as getLiveRenderer, f as PATTERN_B_NAME_PROPERTIES, g as generateResourceNameWithFallback, h as generateResourceName, i as runDockerForeground, n as formatDockerLoginError, p as PATTERN_B_RESOURCE_TYPES, r as getDockerCmd, u as runStackBuffered, v as withStackName } from "./docker-cmd-iDMcWcre.js";
-import { $ as CdkdError, A as shouldRetainResource, B as resolveSkipPrefix, C as IntrinsicFunctionResolver, D as TemplateParser, E as DagBuilder, F as Synthesizer, G as CFN_TEMPLATE_URL_LIMIT, H as resolveStateBucketWithDefaultAndSource, I as getDefaultStateBucketName, J as uploadCfnTemplate, K as MIGRATE_TMP_PREFIX, L as getLegacyStateBucketName, M as stringifyValue, N as WorkGraph, O as LockManager, P as buildDockerImage, R as resolveApp, S as assertRegionMatch, T as DiffCalculator, U as warnDeprecatedNoPrefixCliFlag, V as resolveStateBucketWithDefault, W as CFN_TEMPLATE_BODY_LIMIT, Y as AssemblyReader, Z as resolveBucketRegion, _ as matchesCdkPath, a as withRetry, b as ProviderRegistry, bt as withErrorHandling, c as bold, ct as PartialFailureError, d as green, dt as ResourceUpdateNotSupportedError, f as red, ft as RouteDiscoveryError, g as CDK_PATH_TAG, h as collectInlinePolicyNamesManagedBySiblings, i as withResourceDeadline, it as LocalStartServiceError, j as AssetPublisher, k as S3StateBackend, l as cyan, lt as ProvisioningError, m as IAMRoleProvider, mt as StackTerminationProtectionError, n as DEFAULT_RESOURCE_WARN_AFTER_MS, nt as LocalInvokeBuildError, o as IMPLICIT_DELETE_DEPENDENCIES, ot as MissingCdkCliError, p as yellow, pt as StackHasActiveImportsError, q as findLargeInlineResources, r as DeployEngine, rt as LocalMigrateError, s as formatResourceLine, st as NestedStackChildDirectDestroyError, t as DEFAULT_RESOURCE_TIMEOUT_MS, u as gray, ut as ResourceTimeoutError, v as normalizeAwsTagsToCfn, w as applyRoleArnIfSet, x as CloudControlProvider, y as resolveExplicitPhysicalId, yt as normalizeAwsError, z as resolveCaptureObservedState } from "./deploy-engine-CGmdz5WP.js";
+import { $ as CdkdError, A as shouldRetainResource, B as resolveSkipPrefix, C as IntrinsicFunctionResolver, D as TemplateParser, E as DagBuilder, F as Synthesizer, G as CFN_TEMPLATE_URL_LIMIT, H as resolveStateBucketWithDefaultAndSource, I as getDefaultStateBucketName, J as uploadCfnTemplate, K as MIGRATE_TMP_PREFIX, L as getLegacyStateBucketName, M as stringifyValue, N as WorkGraph, O as LockManager, P as buildDockerImage, R as resolveApp, S as assertRegionMatch, T as DiffCalculator, U as warnDeprecatedNoPrefixCliFlag, V as resolveStateBucketWithDefault, W as CFN_TEMPLATE_BODY_LIMIT, Y as AssemblyReader, Z as resolveBucketRegion, _ as matchesCdkPath, a as withRetry, b as ProviderRegistry, bt as withErrorHandling, c as bold, ct as PartialFailureError, d as green, dt as ResourceUpdateNotSupportedError, f as red, ft as RouteDiscoveryError, g as CDK_PATH_TAG, h as collectInlinePolicyNamesManagedBySiblings, i as withResourceDeadline, it as LocalStartServiceError, j as AssetPublisher, k as S3StateBackend, l as cyan, lt as ProvisioningError, m as IAMRoleProvider, mt as StackTerminationProtectionError, n as DEFAULT_RESOURCE_WARN_AFTER_MS, nt as LocalInvokeBuildError, o as IMPLICIT_DELETE_DEPENDENCIES, ot as MissingCdkCliError, p as yellow, pt as StackHasActiveImportsError, q as findLargeInlineResources, r as DeployEngine, rt as LocalMigrateError, s as formatResourceLine, st as NestedStackChildDirectDestroyError, t as DEFAULT_RESOURCE_TIMEOUT_MS, u as gray, ut as ResourceTimeoutError, v as normalizeAwsTagsToCfn, w as applyRoleArnIfSet, x as CloudControlProvider, y as resolveExplicitPhysicalId, yt as normalizeAwsError, z as resolveCaptureObservedState } from "./deploy-engine-BzrECC3i.js";
 import { a as setAwsClients, i as resetAwsClients, r as getAwsClients, t as AwsClients } from "./aws-clients-B15NAPbL.js";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { createHash, createHmac, createPublicKey, createVerify, randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
@@ -46754,9 +46754,14 @@ function classifyServiceIntegrationRoute(baseRoute, integrationProps, stackName,
 *     JSON prelude — `{statusCode, headers, cookies?}` — followed by 8
 *     NULL bytes and then the raw body chunks). The HTTP server pipes
 *     the chunks to the client with `Transfer-Encoding: chunked` (#467).
-*   - `AuthType !== 'NONE'` (e.g. `AWS_IAM`) → deferred-error
-*     unsupported. Boot proceeds; HTTP 501 + `reason` at request time.
-*     IAM auth would need SigV4 verification cdkd cannot emulate.
+*   - `AuthType === 'AWS_IAM'` → normal route. The `IamAuthorizer` is
+*     attached at the authorizer-resolver pass (`detectAuthorizer` in
+*     `authorizer-resolver.ts`) so the HTTP server runs the same SigV4
+*     verification it ships for REST v1 `AuthorizationType: 'AWS_IAM'`
+*     (PR #447). Signature verification only — no IAM policy emulation.
+*   - `AuthType` other than `'NONE'` / `'AWS_IAM'` (defensive — AWS docs
+*     only define those two values) → deferred-error unsupported. Boot
+*     proceeds; HTTP 501 + `reason` at request time.
 *
 * The Lambda Arn intrinsic resolution still **hard-errors** when it
 * cannot pin down a same-template Lambda — Function URLs have no other
@@ -46781,10 +46786,10 @@ function discoverFunctionUrl(logicalId, resource, template, stackName) {
 		declaredAt: `${stackName}/${logicalId}`
 	};
 	const authType = props["AuthType"];
-	if (authType !== "NONE") return [{
+	if (authType !== "NONE" && authType !== "AWS_IAM") return [{
 		...baseRoute,
 		lambdaLogicalId,
-		unsupported: { reason: `${stackName}/${logicalId}: AuthType '${String(authType)}' is not supported (only NONE — IAM auth requires SigV4 verification cdkd cannot emulate locally).` }
+		unsupported: { reason: `${stackName}/${logicalId}: AuthType ${shortJson$1(authType)} is not a recognized Function URL auth type (expected 'NONE' or 'AWS_IAM').` }
 	}];
 	const invokeModeRaw = props["InvokeMode"];
 	let invokeMode = "BUFFERED";
@@ -51087,6 +51092,28 @@ function detectAuthorizer(route, stack) {
 	if (!resource) return void 0;
 	if (resource.Type === "AWS::ApiGateway::Method") return detectRestV1Authorizer(resource, logicalId, stack);
 	if (resource.Type === "AWS::ApiGatewayV2::Route") return detectHttpApiAuthorizer(resource, logicalId, stack);
+	if (resource.Type === "AWS::Lambda::Url") return detectFunctionUrlAuthorizer(resource, logicalId, stack);
+}
+/**
+* Function URL (`AWS::Lambda::Url`) authorizer detection (issue #621).
+*
+* `AuthType: 'AWS_IAM'` uses the same SigV4 mechanism REST v1 ships
+* (PR #447), so we route through the same `IamAuthorizer` descriptor and
+* let the HTTP server's existing `if (authorizer.kind === 'iam')`
+* request-time branch run `verifySigV4`. Like REST v1 AWS_IAM, no IAM
+* policy emulation — signature verification only.
+*
+* `AuthType: 'NONE'` (and any non-AWS_IAM AuthType that
+* `route-discovery.ts` already flipped to `unsupported`) returns
+* `undefined` so the route runs without an authorizer pass.
+*/
+function detectFunctionUrlAuthorizer(urlResource, urlLogicalId, stack) {
+	if ((urlResource.Properties ?? {})["AuthType"] !== "AWS_IAM") return void 0;
+	return {
+		kind: "iam",
+		logicalId: "AWS_IAM",
+		declaredAt: `${stack.stackName}/${urlLogicalId}`
+	};
 }
 function detectRestV1Authorizer(methodResource, methodLogicalId, stack) {
 	const props = methodResource.Properties ?? {};
@@ -52548,15 +52575,15 @@ async function handleRequest(req, res, state, opts) {
 			outcome = await runAuthorizerPass(authorizer, snapshot, matchCtx, state, opts, baseEvent["requestContext"]);
 		} catch (err) {
 			logger.error(`Authorizer ${authorizer.logicalId} threw for ${match.route.declaredAt}: ${err instanceof Error ? err.message : String(err)}`);
-			writeAuthRejection(res, match.route.apiVersion, "policy-deny");
+			writeAuthRejection(res, match.route.apiVersion, "policy-deny", authorizer.kind);
 			return;
 		}
 		if (!outcome.result.allow) {
-			writeAuthRejection(res, match.route.apiVersion, outcome.denyKind ?? "policy-deny");
+			writeAuthRejection(res, match.route.apiVersion, outcome.denyKind ?? "policy-deny", authorizer.kind);
 			return;
 		}
 		authResult = outcome.result;
-		const overlay = buildOverlay(authorizer, authResult);
+		const overlay = buildOverlay(authorizer, authResult, match.route.apiVersion);
 		if (overlay) baseEvent = applyAuthorizerOverlay(baseEvent, overlay);
 	}
 	if (match.route.serviceIntegration) {
@@ -52967,7 +52994,7 @@ function pickSourceIp(apiVersion, requestContext, snapshot) {
 	}
 	return snapshot.sourceIp ?? "127.0.0.1";
 }
-function buildOverlay(authorizer, result) {
+function buildOverlay(authorizer, result, routeApiVersion) {
 	if (authorizer.kind === "lambda-token" || authorizer.kind === "lambda-request") return authorizer.kind === "lambda-request" && authorizer.apiVersion === "v2" ? {
 		kind: "lambda-http-v2",
 		...result.principalId !== void 0 && { principalId: result.principalId },
@@ -52981,10 +53008,13 @@ function buildOverlay(authorizer, result) {
 		kind: "cognito-rest-v1",
 		claims: result.context ?? {}
 	};
-	if (authorizer.kind === "iam") return {
-		kind: "lambda-rest-v1",
-		...result.principalId !== void 0 && { principalId: result.principalId }
-	};
+	if (authorizer.kind === "iam") {
+		if (routeApiVersion === "v2") return void 0;
+		return {
+			kind: "lambda-rest-v1",
+			...result.principalId !== void 0 && { principalId: result.principalId }
+		};
+	}
 	return {
 		kind: "jwt-http-v2",
 		claims: result.context ?? {}
@@ -52992,6 +53022,11 @@ function buildOverlay(authorizer, result) {
 }
 /**
 * Map the authorizer rejection to an HTTP status code and body.
+*   - REST v1 with AWS_IAM (issue #625) → 403 for both deny kinds (the
+*     deployed REST v1 SigV4 layer rejects unsigned requests with 403
+*     `{"message":"Missing Authentication Token"}` and signature/policy
+*     failures with 403 `{"message":"Forbidden"}` — lowercase `message`
+*     distinguishes the REST v1 shape from the Function URL shape below).
 *   - REST v1, missing identity → 401 `{"message":"Unauthorized"}`
 *     (matches deployed behavior; the route reaches the Method but no
 *     identity source is present so the authorizer never runs).
@@ -52999,8 +53034,25 @@ function buildOverlay(authorizer, result) {
 *     authorizer ran and denied; status mirrors AWS API Gateway).
 *   - HTTP v2, both kinds → 401 `{"message":"Unauthorized"}` (HTTP API
 *     collapses both into the same response).
-*/
-function writeAuthRejection(res, apiVersion, denyKind) {
+*   - Function URL with AWS_IAM (issue #621) → 403 `{"Message":"Forbidden"}`
+*     for both deny kinds (matches Lambda's deployed Function URL IAM
+*     behavior — the AWS SigV4 layer rejects with 403, not 401). Note the
+*     capital `Message` — distinct from REST v1 AWS_IAM's lowercase
+*     `message`.
+*/
+function writeAuthRejection(res, apiVersion, denyKind, authorizerKind) {
+	if (apiVersion === "v1" && authorizerKind === "iam") {
+		if (denyKind === "missing-identity") {
+			writeError(res, 403, "{\"message\":\"Missing Authentication Token\"}");
+			return;
+		}
+		writeError(res, 403, "{\"message\":\"Forbidden\"}");
+		return;
+	}
+	if (apiVersion === "v2" && authorizerKind === "iam") {
+		writeError(res, 403, "{\"Message\":\"Forbidden\"}");
+		return;
+	}
 	if (apiVersion === "v2") {
 		writeError(res, 401, "{\"message\":\"Unauthorized\"}");
 		return;
@@ -55097,7 +55149,7 @@ function resolveMtlsConfig(options) {
 * Builder for the `start-api` subcommand. Wired up by `local.ts`.
 */
 function createLocalStartApiCommand() {
-	const startApi = new Command("start-api").description("Run a long-running local HTTP server that maps API Gateway routes (REST v1, HTTP API, Function URL) to Lambda invocations against the AWS Lambda Runtime Interface Emulator (Docker required). Supports Lambda TOKEN/REQUEST authorizers, Cognito User Pool / HTTP v2 JWT authorizers, and REST v1 AWS_IAM (SigV4 signature verification only — IAM policy evaluation is NOT emulated; see docs/local-emulation.md). When JWKS is unreachable, JWT authorizers fall back to pass-through (every token accepted) with a warn line — local dev fallback. VPC-config Lambdas run locally and surface a warn line at startup; their containers do NOT get attached to the deployed VPC subnets, so calls to private RDS / ElastiCache will fail.").argument("[target]", "Optional API filter. Accepts the bare CDK logical id ('MyHttpApi'; single-stack apps only), stack-qualified logical id ('MyStack:MyHttpApi'), full CDK Construct path ('MyStack/MyHttpApi/Resource'), or an ancestor Construct path that prefix-matches ('MyStack/MyHttpApi'). When omitted, every discovered API gets its own server. Mirrors `cdkd local invoke` / `cdkd local run-task` target syntax.").addOption(new Option("--port <port>", "HTTP server port (default: auto-allocate)").default("0")).addOption(new Option("--host <host>", "Bind address").default("127.0.0.1")).addOption(new Option("--stack <name>", "Stack to start (single-stack apps auto-detect)")).addOption(new Option("--warm", "Pre-start one container per Lambda at server boot").default(false)).addOption(new Option("--per-lambda-concurrency <n>", "Pool size cap per Lambda (default 2, max 4)").default("2")).addOption(new Option("--no-pull", "Skip docker pull (cached image)")).addOption(new Option("--container-host <host>", "IP the host uses to bind/probe the RIE port (must be a numeric IP — `docker run -p <ip>:<port>:8080` rejects hostnames). Defaults to 127.0.0.1.").default("127.0.0.1")).addOption(new Option("--debug-port-base <port>", "Reserve a contiguous --debug-port range (one per Lambda)")).addOption(new Option("--env-vars <file>", "JSON env-var overrides (SAM-compatible: {\"LogicalId\":{\"KEY\":\"VALUE\"}, \"Parameters\": {...}})")).addOption(new Option("--assume-role <arn-or-pair>", "Assume the Lambda's execution role and forward STS-issued temp creds. Bare <arn> = global default; <LogicalId>=<arn> = per-Lambda override (repeatable). Per-Lambda > global > unset (developer creds passed through).").argParser((raw, prev) => parseAssumeRoleToken(raw, prev))).addOption(new Option("--watch", "Hot-reload: re-synth + re-discover routes when cdk.out/ or asset directories change. Off by default; the server keeps the previous version serving when synth fails mid-reload.").default(false)).addOption(new Option("--stage <name>", "Select an API Gateway Stage by its 'StageName'. Default: the first Stage attached to each API. Drives event.stageVariables for both REST v1 and HTTP API v2. NOTE: For HTTP API v2 routes, requestContext.stage is always '$default' regardless of this flag (AWS-side limitation — HTTP API only exposes one stage to the integration event); only event.stageVariables is affected for v2 routes. For REST v1 routes the selected StageName is also threaded into requestContext.stage.")).addOption(new Option("--api <id>", "DEPRECATED — use the positional <target> argument instead. Same accepted forms (bare logical id, stack-qualified, Construct path, ancestor prefix). Will be removed in a future major release.")).addOption(new Option("--layer-role-arn <arn>", "Role to sts:AssumeRole before calling lambda:GetLayerVersion on every literal-ARN entry in Properties.Layers (issue #448). Use only when the dev credentials cannot read the layer — typically cross-account layers. AWS-published public layers (e.g. Lambda Powertools) are readable from every account and need no role.")).addOption(new Option("--from-state", "Read cdkd S3 state for every routed stack and substitute Ref / Fn::GetAtt / Fn::Sub / Fn::Join (and AWS pseudo parameters) in Lambda env vars with the deployed physical IDs / attributes. Off by default — pre-PR warn-and-drop semantics are preserved. Turn on for stacks already deployed via cdkd deploy. Mirrors `cdkd local invoke --from-state` / `cdkd local run-task --from-state`. Re-runs against fresh state on every hot-reload firing (--watch).").default(false)).addOption(new Option("--from-cfn-stack [cfn-stack-name]", "Read a deployed CloudFormation stack via DescribeStackResources and substitute Ref / Fn::ImportValue in Lambda env vars with the deployed physical IDs / exports. Use for CDK apps deployed via the upstream CDK CLI (`cdk deploy`). Bare form uses the cdkd stack name per routed stack; pass an explicit value when a single CFn stack should serve every routed stack. Mutually exclusive with --from-state. Fn::GetAtt is warn-and-dropped in v1 (CFn DescribeStackResources does not return per-attribute values).")).addOption(new Option("--stack-region <region>", "Region of the state record to read. Used with --from-state when the same stack name has state in multiple regions, and with --from-cfn-stack as the CFn client region (cdkd does not have a separate --cfn-stack-region flag).")).addOption(new Option("--mtls-truststore <path>", "PEM-encoded CA bundle for client-certificate verification (mutual TLS). When set, the local server switches from HTTP to HTTPS and the TLS handshake rejects clients whose certificate doesn't chain to one of these CAs. Verified certs are surfaced on the Lambda event under requestContext.identity.clientCert (REST v1) / requestContext.authentication.clientCert (HTTP API v2). Must be set together with --mtls-cert + --mtls-key; partial flag sets are rejected. Generate a CA + server + client cert for local dev: openssl req -x509 -newkey rsa:2048 -nodes -keyout ca-key.pem -out ca.pem -subj \"/CN=cdkd-local-ca\" -days 365; openssl req -newkey rsa:2048 -nodes -keyout server-key.pem -out server-csr.pem -subj \"/CN=localhost\"; openssl x509 -req -in server-csr.pem -CA ca.pem -CAkey ca-key.pem -CAcreateserial -out server-cert.pem -days 365; openssl req -newkey rsa:2048 -nodes -keyout client-key.pem -out client-csr.pem -subj \"/CN=client\"; openssl x509 -req -in client-csr.pem -CA ca.pem -CAkey ca-key.pem -CAcreateserial -out client-cert.pem -days 365; curl --cacert ca.pem --cert client-cert.pem --key client-key.pem https://localhost:<port>/...")).addOption(new Option("--mtls-cert <path>", "PEM-encoded server certificate for mutual TLS. Self-signed is fine for local dev. Must be set together with --mtls-truststore + --mtls-key.")).addOption(new Option("--mtls-key <path>", "PEM-encoded server private key matching --mtls-cert. Must be set together with --mtls-truststore + --mtls-cert.")).addOption(new Option("--allow-unverified-sigv4", "Opt-in: allow AWS_IAM SigV4 requests that cannot be cryptographically verified (foreign access-key-id, OR no local AWS credentials configured) to pass through with a placeholder principalId. DEFAULT off — fail-closed so unauthenticated bypass is impossible against `event.requestContext.identity.accessKey`-trusting handler code. Use only in dev loops where you understand the risk.").default(false)).action(withErrorHandling(localStartApiCommand));
+	const startApi = new Command("start-api").description("Run a long-running local HTTP server that maps API Gateway routes (REST v1, HTTP API, Function URL) to Lambda invocations against the AWS Lambda Runtime Interface Emulator (Docker required). Supports Lambda TOKEN/REQUEST authorizers, Cognito User Pool / HTTP v2 JWT authorizers, and AWS_IAM auth (REST v1 `AuthorizationType: AWS_IAM` and Function URL `AuthType: AWS_IAM` — SigV4 signature verification only; IAM policy evaluation is NOT emulated; see docs/local-emulation.md). When JWKS is unreachable, JWT authorizers fall back to pass-through (every token accepted) with a warn line — local dev fallback. VPC-config Lambdas run locally and surface a warn line at startup; their containers do NOT get attached to the deployed VPC subnets, so calls to private RDS / ElastiCache will fail.").argument("[target]", "Optional API filter. Accepts the bare CDK logical id ('MyHttpApi'; single-stack apps only), stack-qualified logical id ('MyStack:MyHttpApi'), full CDK Construct path ('MyStack/MyHttpApi/Resource'), or an ancestor Construct path that prefix-matches ('MyStack/MyHttpApi'). When omitted, every discovered API gets its own server. Mirrors `cdkd local invoke` / `cdkd local run-task` target syntax.").addOption(new Option("--port <port>", "HTTP server port (default: auto-allocate)").default("0")).addOption(new Option("--host <host>", "Bind address").default("127.0.0.1")).addOption(new Option("--stack <name>", "Stack to start (single-stack apps auto-detect)")).addOption(new Option("--warm", "Pre-start one container per Lambda at server boot").default(false)).addOption(new Option("--per-lambda-concurrency <n>", "Pool size cap per Lambda (default 2, max 4)").default("2")).addOption(new Option("--no-pull", "Skip docker pull (cached image)")).addOption(new Option("--container-host <host>", "IP the host uses to bind/probe the RIE port (must be a numeric IP — `docker run -p <ip>:<port>:8080` rejects hostnames). Defaults to 127.0.0.1.").default("127.0.0.1")).addOption(new Option("--debug-port-base <port>", "Reserve a contiguous --debug-port range (one per Lambda)")).addOption(new Option("--env-vars <file>", "JSON env-var overrides (SAM-compatible: {\"LogicalId\":{\"KEY\":\"VALUE\"}, \"Parameters\": {...}})")).addOption(new Option("--assume-role <arn-or-pair>", "Assume the Lambda's execution role and forward STS-issued temp creds. Bare <arn> = global default; <LogicalId>=<arn> = per-Lambda override (repeatable). Per-Lambda > global > unset (developer creds passed through).").argParser((raw, prev) => parseAssumeRoleToken(raw, prev))).addOption(new Option("--watch", "Hot-reload: re-synth + re-discover routes when cdk.out/ or asset directories change. Off by default; the server keeps the previous version serving when synth fails mid-reload.").default(false)).addOption(new Option("--stage <name>", "Select an API Gateway Stage by its 'StageName'. Default: the first Stage attached to each API. Drives event.stageVariables for both REST v1 and HTTP API v2. NOTE: For HTTP API v2 routes, requestContext.stage is always '$default' regardless of this flag (AWS-side limitation — HTTP API only exposes one stage to the integration event); only event.stageVariables is affected for v2 routes. For REST v1 routes the selected StageName is also threaded into requestContext.stage.")).addOption(new Option("--api <id>", "DEPRECATED — use the positional <target> argument instead. Same accepted forms (bare logical id, stack-qualified, Construct path, ancestor prefix). Will be removed in a future major release.")).addOption(new Option("--layer-role-arn <arn>", "Role to sts:AssumeRole before calling lambda:GetLayerVersion on every literal-ARN entry in Properties.Layers (issue #448). Use only when the dev credentials cannot read the layer — typically cross-account layers. AWS-published public layers (e.g. Lambda Powertools) are readable from every account and need no role.")).addOption(new Option("--from-state", "Read cdkd S3 state for every routed stack and substitute Ref / Fn::GetAtt / Fn::Sub / Fn::Join (and AWS pseudo parameters) in Lambda env vars with the deployed physical IDs / attributes. Off by default — pre-PR warn-and-drop semantics are preserved. Turn on for stacks already deployed via cdkd deploy. Mirrors `cdkd local invoke --from-state` / `cdkd local run-task --from-state`. Re-runs against fresh state on every hot-reload firing (--watch).").default(false)).addOption(new Option("--from-cfn-stack [cfn-stack-name]", "Read a deployed CloudFormation stack via DescribeStackResources and substitute Ref / Fn::ImportValue in Lambda env vars with the deployed physical IDs / exports. Use for CDK apps deployed via the upstream CDK CLI (`cdk deploy`). Bare form uses the cdkd stack name per routed stack; pass an explicit value when a single CFn stack should serve every routed stack. Mutually exclusive with --from-state. Fn::GetAtt is warn-and-dropped in v1 (CFn DescribeStackResources does not return per-attribute values).")).addOption(new Option("--stack-region <region>", "Region of the state record to read. Used with --from-state when the same stack name has state in multiple regions, and with --from-cfn-stack as the CFn client region (cdkd does not have a separate --cfn-stack-region flag).")).addOption(new Option("--mtls-truststore <path>", "PEM-encoded CA bundle for client-certificate verification (mutual TLS). When set, the local server switches from HTTP to HTTPS and the TLS handshake rejects clients whose certificate doesn't chain to one of these CAs. Verified certs are surfaced on the Lambda event under requestContext.identity.clientCert (REST v1) / requestContext.authentication.clientCert (HTTP API v2). Must be set together with --mtls-cert + --mtls-key; partial flag sets are rejected. Generate a CA + server + client cert for local dev: openssl req -x509 -newkey rsa:2048 -nodes -keyout ca-key.pem -out ca.pem -subj \"/CN=cdkd-local-ca\" -days 365; openssl req -newkey rsa:2048 -nodes -keyout server-key.pem -out server-csr.pem -subj \"/CN=localhost\"; openssl x509 -req -in server-csr.pem -CA ca.pem -CAkey ca-key.pem -CAcreateserial -out server-cert.pem -days 365; openssl req -newkey rsa:2048 -nodes -keyout client-key.pem -out client-csr.pem -subj \"/CN=client\"; openssl x509 -req -in client-csr.pem -CA ca.pem -CAkey ca-key.pem -CAcreateserial -out client-cert.pem -days 365; curl --cacert ca.pem --cert client-cert.pem --key client-key.pem https://localhost:<port>/...")).addOption(new Option("--mtls-cert <path>", "PEM-encoded server certificate for mutual TLS. Self-signed is fine for local dev. Must be set together with --mtls-truststore + --mtls-key.")).addOption(new Option("--mtls-key <path>", "PEM-encoded server private key matching --mtls-cert. Must be set together with --mtls-truststore + --mtls-cert.")).addOption(new Option("--allow-unverified-sigv4", "Opt-in: allow AWS_IAM SigV4 requests that cannot be cryptographically verified (foreign access-key-id, OR no local AWS credentials configured) to pass through with a placeholder principalId. DEFAULT off — fail-closed so unauthenticated bypass is impossible against `event.requestContext.identity.accessKey`-trusting handler code. Use only in dev loops where you understand the risk.").default(false)).action(withErrorHandling(localStartApiCommand));
 	[
 		...commonOptions,
 		...appOptions,
@@ -59436,7 +59488,7 @@ function reorderArgs(argv) {
 */
 async function main() {
 	const program = new Command();
-	program.name("cdkd").description("CDK Direct - Deploy AWS CDK apps directly via SDK/Cloud Control API").version("0.158.1");
+	program.name("cdkd").description("CDK Direct - Deploy AWS CDK apps directly via SDK/Cloud Control API").version("0.159.1");
 	program.addCommand(createBootstrapCommand());
 	program.addCommand(createSynthCommand());
 	program.addCommand(createListCommand());