@go-to-k/cdkd 0.94.14 → 0.95.0

package/README.md

@@ -160,12 +160,20 @@ 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`)
-  run synthesized Lambda functions locally inside Docker containers that
-  bundle the AWS Lambda Runtime Interface Emulator (RIE). `local invoke`
-  runs a single Lambda once; `local start-api` stands up a long-running
-  HTTP server that maps API Gateway / HTTP API / Function URL routes to
-  local Lambda invocations. No AWS API calls, no state bucket needed.
+- **`cdkd local ...` subcommands** (`local invoke`, `local start-api`,
+  `local run-task`) 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
+  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. No AWS API calls beyond optional STS /
+  Secrets resolution, no state bucket needed.
 
 Options like `--app`, `--state-bucket`, and `--context` can be omitted if configured via `cdk.json` or environment variables (`CDKD_APP`, `CDKD_STATE_BUCKET`).
 
@@ -376,6 +384,71 @@ 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
+via Docker — Lambda functions, API Gateway routes, and ECS tasks —
+without an AWS deploy. Modeled on `sam local *` but reuses cdkd's
+synthesis / asset / construct-path plumbing — no `template.yaml` to
+maintain, no `cdk synth | sam ...` round-trip.
+
+| Subcommand | Emulates |
+| --- | --- |
+| `cdkd local invoke <target>` | One-shot Lambda invoke via the AWS Lambda Runtime Interface Emulator (RIE) |
+| `cdkd local start-api` | Long-running HTTP server for REST v1 / HTTP API / Function URL routes |
+| `cdkd local run-task <target>` | ECS RunTask — every container in a task definition started on a per-task docker network |
+
+Requires Docker. Pass `--from-state` to substitute deployed physical
+IDs into intrinsic-valued properties; without it, intrinsic values are
+dropped with a per-key warning (matches `sam local *` semantics).
+
+### `local invoke`
+
+```bash
+cdkd local invoke MyStack/MyApi/Handler           # one-shot invoke
+cdkd local invoke MyStack/Handler --event events/get.json
+cdkd local invoke MyStack/Handler --from-state    # recover deployed env vars
+```
+
+Supports every current AWS Lambda runtime (Node.js / Python / Ruby /
+Java / .NET / `provided.al2023`), container Lambdas
+(`DockerImageFunction` / `Code.ImageUri`) via local-build or ECR pull,
+and same-stack Lambda Layers bind-mounted at `/opt`.
+
+### `local start-api`
+
+```bash
+cdkd local start-api                              # one HTTP server per discovered API
+cdkd local start-api --port 3000                  # pin the first server's port
+cdkd local start-api --api MyHttpApi              # filter by logical id
+cdkd local start-api --api MyStack/MyHttpApi      # OR: CDK Construct path
+cdkd local start-api --warm --watch               # pre-start + hot reload
+```
+
+One server per discovered API — authorizers, CORS configs, and stage
+variables stay scoped to the owning API. Supports REST v1 + HTTP API +
+Function URL with AWS_PROXY integrations; Lambda TOKEN / REQUEST,
+Cognito User Pool, and HTTP v2 JWT authorizers (JWKS-verified); CORS
+preflight; hot reload via `--watch`.
+
+### `local run-task`
+
+```bash
+cdkd local run-task MyStack/MyService/TaskDef
+cdkd local run-task MyTaskDef --from-state        # resolve deployed secrets / env intrinsics
+```
+
+Starts every container in the task definition on a per-task docker
+network with the AWS-published ECS metadata sidecar
+(`amazon/amazon-ecs-local-container-endpoints`). `DependsOn` /
+`Secrets` / `Volumes` (Host / Docker) are honored; `Secrets[].ValueFrom`
+is resolved from SecretsManager / SSM at startup.
+
+See [docs/local-emulation.md](docs/local-emulation.md) for the full
+reference — supported runtimes, target resolution, every flag, exit
+codes, route precedence, container-pool semantics, networking model,
+v1 scope notes.
+
 ## Importing existing resources
 
 `cdkd import` adopts AWS resources that are already deployed (via
@@ -456,85 +529,6 @@ Two `orphan` variants at different granularities:
 Both `cdkd destroy` (synth-driven) and `cdkd state destroy`
 (state-driven, no synth) delete AWS resources + state.
 
-## Stack-name prefix on physical names
-
-By default cdkd creates AWS resources with the **exact name you
-declared** in CDK code: `new iam.Role(this, 'CRRole', { roleName:
-'my-role' })` in stack `MyStack` produces an AWS resource named
-`my-role`. Consistent across every resource type. This is the
-default since **v0.94.0** (closes [#299](https://github.com/go-to-k/cdkd/issues/299)).
-
-Pre-v0.94.0 cdkd prepended the stack name to user-declared physical
-names on a subset of types only (Pattern B providers: IAM Role /
-User / Group / InstanceProfile / ELBv2 LoadBalancer / TargetGroup),
-while Pattern A providers (Lambda, S3, SNS, SQS, DynamoDB, etc.) used
-the user's name as-is. The inconsistency was opaque to users and
-surfaced as failures in `cdkd export` (CFn IMPORT identifier
-mismatch). Flipping the default brings every resource type into line
-out of the box.
-
-`cdkd deploy --prefix-user-supplied-names` opts BACK in to the
-legacy prefixing on Pattern B providers (matching pre-v0.94.0 cdkd).
-Useful when migrating an existing stack that was originally deployed
-under the legacy default and you don't want to take a one-time
-replacement on every Pattern B resource.
-
-| | Default (no flag) | `--prefix-user-supplied-names` |
-| --- | --- | --- |
-| `new iam.Role({ roleName: 'my-role' })` | `my-role` | `MyStack-my-role` (legacy) |
-| `new s3.Bucket({ bucketName: 'my-bucket' })` | `my-bucket` (always — Pattern A) | `my-bucket` (unchanged) |
-| `new iam.Role(...)` (no `roleName`) | `MyStack-CRRole-<hash>` (auto-generated; prefix kept for uniqueness) | `MyStack-CRRole-<hash>` (unchanged) |
-
-Resolution chain (highest wins): `--prefix-user-supplied-names`
-CLI flag → `CDKD_PREFIX_USER_SUPPLIED_NAMES=true` env var →
-`cdk.json` `context.cdkd.prefixUserSuppliedNames: true` → default
-`false` (skip prefix).
-
-The deprecated `--no-prefix-user-supplied-names` flag (plus the
-`CDKD_NO_PREFIX_USER_SUPPLIED_NAMES` env var and `cdk.json
-context.cdkd.noPrefixUserSuppliedNames`) is still accepted but now
-matches the default; setting it emits a deprecation warning and is a
-no-op. Remove it from your CLI invocations and config.
-
-### Migration from pre-v0.94.0
-
-This is a **breaking change**: upgrading from a pre-v0.94.0 cdkd to
-v0.94.0+ flips the AWS-resource name cdkd produces on Pattern B
-providers (IAM Role / User / Group / InstanceProfile / ELBv2 LB / TG)
-with user-supplied physical names. The next `cdkd deploy` against an
-existing stack will propose REPLACEMENT on every such resource —
-the AWS resource has the prefixed name; the new template intent has
-the un-prefixed name.
-
-Pick one of:
-
-1. **Accept the one-time replacement** (simplest; only safe when the
-   types involved tolerate replacement — IAM Roles get fresh ARNs,
-   ELBv2 LBs get fresh DNS names).
-2. **Pin legacy prefixing**: pass `--prefix-user-supplied-names`,
-   set `CDKD_PREFIX_USER_SUPPLIED_NAMES=true`, or add
-   `"prefixUserSuppliedNames": true` under `cdk.json` `context.cdkd`.
-3. **Drop the explicit physical name** in CDK code where you don't
-   actually need a stable name — `new iam.Role(...)` without
-   `roleName` always uses the auto-generated `MyStack-CRRole-<hash>`
-   form regardless of this flag.
-
-A migration helper (`cdkd state rename-strip-prefix <stack>`) that
-would let an existing stack adopt the new default without replacement
-is tracked separately in [#300](https://github.com/go-to-k/cdkd/issues/300).
-
-### Effect on `cdkd export`
-
-[PR #285 `cdkd export`](https://github.com/go-to-k/cdkd/pull/285)
-surfaced the pre-v0.94.0 inconsistency: the CFn IMPORT changeset's
-identifier check would fail on a synth `RoleName: 'my-role'` vs the
-AWS-deployed `MyStack-my-role`, so the export command overlays
-`ResourceIdentifier` onto `Properties` to bridge the gap. The
-overlay is still needed for stacks deployed under the legacy default
-(or with `--prefix-user-supplied-names`); a fresh stack deployed
-under the v0.94.0 default has matching names and the overlay is a
-no-op for it.
-
 ## `--remove-protection`: one-shot bypass for protected resources
 
 CDK's `new Stack(app, 'X', { terminationProtection: true })` is honored
@@ -594,182 +588,6 @@ 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.
 
-## `local invoke`: run Lambda functions locally
-
-`cdkd local invoke <target>` runs a Lambda function from a CDK app on the
-developer's machine, inside a Docker container that bundles the AWS
-Lambda Runtime Interface Emulator (RIE). Modeled on `sam local invoke`
-but reusing cdkd's synthesis / asset / construct-path plumbing — no
-`template.yaml` to maintain, no `cdk synth | sam ...` round-trip.
-
-Requires Docker. Supports every current AWS Lambda runtime
-(`nodejs18.x` / `nodejs20.x` / `nodejs22.x` / `nodejs24.x` / `python3.11` /
-`python3.12` / `python3.13` / `python3.14` / `ruby3.2` / `ruby3.3` /
-`java8.al2` / `java11` / `java17` / `java21` / `dotnet6` / `dotnet8` /
-`provided.al2` / `provided.al2023`). The deprecated `go1.x` runtime is
-rejected with a migration pointer to `provided.al2023`. Java, .NET, and
-`provided.*` Lambdas are **asset-backed only** — the Handler shape names
-a compiled artifact (`package.Class::method` for Java's JVM class;
-`Assembly::Namespace.Class::Method` for .NET's CLR assembly; an
-arbitrary `bootstrap` binary for the OS-only `provided.*` runtimes), so
-use `lambda.Code.fromAsset(<dir>)` with a directory containing the
-compiled output (`.class` hierarchy / `.jar` / `.dll` / native binary);
-inline `Code.ZipFile` is rejected with a clear routing message.
-
-**Container Lambdas** — `lambda.DockerImageFunction(...)` /
-`Code.ImageUri` is supported alongside ZIP Lambdas. cdkd reads the
-function's local `Dockerfile` from `cdk.out` and runs `docker build`
-locally before invoking. When no asset matches (typically: invoking a
-stack deployed elsewhere), cdkd falls back to `docker pull` from
-ECR — same-account / same-region only in v1; cross-account /
-cross-region is not yet supported. `Architectures: [x86_64]` /
-`[arm64]` are honored via `--platform` so an arm64 host running an
-x86_64 Lambda doesn't hit emulation.
-
-```bash
-# Invoke by CDK display path (single-stack apps may omit the prefix)
-cdkd local invoke MyStack/MyApi/Handler
-cdkd local invoke MyStack:MyApiHandler1234ABCD       # logical-id form
-
-# Pass an event payload
-cdkd local invoke MyStack/Handler --event events/get.json
-echo '{"path":"/"}' | cdkd local invoke MyStack/Handler --event-stdin
-
-# Override env vars (SAM-compatible shape: {"LogicalId":{"KEY":"VALUE"}}
-# plus an optional top-level "Parameters" block applied to every invoke)
-cdkd local invoke MyStack/Handler --env-vars env.json
-
-# Skip docker pull when iterating
-cdkd local invoke MyStack/Handler --no-pull
-
-# Skip the local docker build for container Lambdas (Code.ImageUri).
-# Reuses the deterministic cdkd-local-invoke-<hash> tag from a prior
-# build. Errors clearly when the tag is missing.
-cdkd local invoke MyStack/ContainerHandler --no-build
-
-# Run with the deployed function's narrow execution role (otherwise the
-# developer's shell credentials are forwarded — SAM-compatible default)
-cdkd local invoke MyStack/Handler --assume-role arn:aws:iam::123456789012:role/MyApi-handler-role
-
-# Attach a Node debugger
-cdkd local invoke MyStack/Handler --debug-port 9229
-
-# After `cdkd deploy`, recover intrinsic-valued env vars (Ref / Fn::GetAtt
-# / Fn::Sub) from cdkd's S3 state instead of dropping them. Off by default
-# — keeps the local-only / unscoped flow safe; opt in when you want the
-# handler to see the deployed physical IDs (S3 bucket names, DDB table
-# names, IAM role ARNs, ...). Disambiguate with `--stack-region <region>`
-# when the same stack name has state in multiple regions.
-cdkd local invoke MyStack/Handler --from-state
-```
-
-**Lambda Layers** — same-stack
-`AWS::Lambda::LayerVersion` references in `Properties.Layers` are
-resolved automatically and bind-mounted at `/opt` (read-only) inside
-the container. Each layer's unzipped asset directory under `cdk.out/`
-becomes one `-v <layerAssetPath>:/opt:ro` mount; multiple layers
-stack via Docker overlay layering, and AWS's "last layer wins on
-file collision" rule is preserved by keeping the template's input
-order. Cross-stack / cross-account / cross-region layer ARNs (literal
-ARN strings in `Properties.Layers`) are out of scope for v1 — cdkd
-hard-errors with a clear pointer at the offending entry. Container
-Lambdas (`Code.ImageUri`) silently ignore `Layers` (matches AWS:
-container images bake layers at build time).
-
-See [docs/cli-reference.md](docs/cli-reference.md#local-invoke-run-lambda-functions-locally)
-for the full surface, target-resolution rules, and v1 scope notes.
-
-## `local start-api`: long-running local API server
-
-`cdkd local start-api` stands up a long-running local HTTP server that
-maps the synthesized API Gateway routes (REST v1, HTTP API, Function
-URL) to local Lambda invocations against the same RIE-backed Docker
-containers `cdkd local invoke` uses. Modeled on `sam local start-api`
-but reusing cdkd's synthesis / route-discovery plumbing.
-
-```bash
-# Auto-allocate one port PER discovered API (printed at startup)
-cdkd local start-api
-
-# Pin the FIRST server to port 3000; subsequent APIs get 3001, 3002, ...
-cdkd local start-api --port 3000
-
-# Restrict to a single API by its CDK logical id (HTTP API / REST API logical
-# id, or the backing Lambda's logical id for Function URLs)
-cdkd local start-api --api MyAdminApi
-
-# Pre-warm one container per Lambda at server boot — eliminates first-request cold start
-cdkd local start-api --warm
-
-# Override env vars per-Lambda (SAM-shape file)
-cdkd local start-api --env-vars env.json
-
-# Pin the deployed execution role per Lambda (or globally with a bare ARN)
-cdkd local start-api --assume-role MyApiHandler=arn:aws:iam::123:role/handler-role
-
-# Hot reload — re-synth + re-discover routes when cdk.out/ or asset dirs change
-cdkd local start-api --watch
-
-# Select a specific API Gateway Stage (default: the first attached)
-cdkd local start-api --stage prod
-```
-
-**One server per API** (since v0.81): every discovered API surface gets its
-own HTTP server on its own port, so authorizers, CORS configs, and stage
-variables stay scoped to the owning API and never bleed across APIs that
-happen to share a path. `cdkd local start-api` prints one
-`Server listening on http://<host>:<port>  (<API> (<kind>))` line per
-server at startup; pass `--api <id>` to launch only one of them.
-
-Scope: REST v1 + HTTP API + Function URL with AWS_PROXY integrations.
-Authorizers (Lambda TOKEN/REQUEST + Cognito User Pool + HTTP v2 JWT),
-VPC-config Lambda warnings, CORS preflight, hot reload, and stage
-variables are supported. WebSocket APIs are not.
-
-**Authorizers**: `Authorization: Bearer <token>`-protected
-routes are gated on the authorizer Lambda's response (TOKEN / REQUEST
-authorizers, IAM-policy or HTTP v2 simple shape) or on a JWKS-based JWT
-verification (Cognito User Pool authorizers, HTTP v2 JWT authorizers).
-When the JWKS endpoint is unreachable from the dev machine, cdkd falls
-back to **pass-through mode** (every JWT accepted, with a warn line at
-startup) — local-dev-only fallback so a corporate proxy doesn't block
-iteration. **Do NOT rely on this in any shared environment.**
-
-**VPC-config Lambdas**: handlers with `Properties.VpcConfig`
-still run locally, but the local container is NOT attached to the
-deployed VPC's subnets — calls to private RDS / ElastiCache will fail.
-cdkd warns at startup naming each affected Lambda; AWS SDK calls still
-reach public AWS endpoints via the dev's network as usual.
-
-**Hot reload (`--watch`)**: re-runs the synth → discover → spec-build
-pipeline whenever `cdk.out/` or any of the routed Lambdas' asset
-directories change. Routes added / removed / changed swap in
-atomically without restarting the HTTP server; in-flight requests
-complete against the old container pool while the new pool warms.
-Synth failures are non-fatal — the previous version keeps serving and
-a warn line names the failure. Off by default; pass `--watch` to
-enable.
-
-**CORS preflight**: HTTP API v2 OPTIONS preflight requests are
-intercepted when the API has a `CorsConfiguration` block. The server
-matches the request's `Origin` / `Access-Control-Request-Method` /
-`Access-Control-Request-Headers` against the configured allowlist and
-returns a `204 No Content` with the canonical `Access-Control-Allow-*`
-headers. Preflight handling is skipped when the user has registered
-an explicit OPTIONS method (their Lambda owns it). REST v1 CORS (Mock
-OPTIONS method) is not auto-handled and stays out of scope; use the
-deployed API for that case.
-
-**Stage variables**: `event.stageVariables` is populated from the
-selected Stage's `Variables` (REST v1) / `StageVariables` (HTTP API
-v2) map. Default selection is the first Stage attached to each API;
-pass `--stage <name>` to pick a Stage by `StageName`. Function URL
-routes don't have a Stage — `event.stageVariables` stays `null`.
-
-See [docs/cli-reference.md](docs/cli-reference.md#local-start-api-long-running-local-api-server)
-for the full route-discovery rules, container-pool semantics, exit
-codes, and per-authorizer-kind detection / response-shape details.
-
 ## State Management
 
 State is stored in S3 with optimistic locking via S3 Conditional Writes

package/dist/cli.js

@@ -35003,7 +35003,7 @@ function discoverRoutes(stacks) {
 					routes.push(...discoverHttpApiRoute(logicalId, resource, template, stack.stackName));
 					break;
 				case "AWS::Lambda::Url":
-					routes.push(...discoverFunctionUrl(logicalId, resource, stack.stackName));
+					routes.push(...discoverFunctionUrl(logicalId, resource, template, stack.stackName));
 					break;
 				default: break;
 			}
@@ -35040,14 +35040,19 @@ function discoverRestV1Method(logicalId, resource, template, stackName) {
 	if (!restApiLogicalId) throw new Error(`${stackName}/${logicalId} (AWS::ApiGateway::Method): RestApiId must be a { Ref: '...' } reference (got ${shortJson$1(restApiId)}).`);
 	const resourceId = props["ResourceId"];
 	const path = buildRestV1Path(resourceId, restApiLogicalId, template, stackName, logicalId);
+	const httpMethod = stringifyValue(props["HttpMethod"] ?? "ANY");
+	const stage = pickRestV1Stage(restApiLogicalId, template);
+	const restApiCdkPath = readApiCdkPath(restApiLogicalId, template);
 	return [{
-		method: stringifyValue(props["HttpMethod"] ?? "ANY"),
+		method: httpMethod,
 		pathPattern: path,
 		lambdaLogicalId,
 		source: "rest-v1",
 		apiVersion: "v1",
-		stage: pickRestV1Stage(restApiLogicalId, template),
+		stage,
 		apiLogicalId: restApiLogicalId,
+		apiStackName: stackName,
+		...restApiCdkPath !== void 0 && { apiCdkPath: restApiCdkPath },
 		declaredAt: `${stackName}/${logicalId}`
 	}];
 }
@@ -35139,6 +35144,7 @@ function discoverHttpApiRoute(logicalId, resource, template, stackName) {
 	if (integrationProps["IntegrationSubtype"] !== void 0) throw new Error(`${stackName}/${logicalId} (AWS::ApiGatewayV2::Route): IntegrationSubtype '${stringifyValue(integrationProps["IntegrationSubtype"])}' is not supported (ApiGatewayV2 service integrations like SQS/EventBridge cannot run locally).`);
 	const lambdaLogicalId = resolveLambdaArnIntrinsic(integrationProps["IntegrationUri"], `${stackName}/${integrationLogicalId}.IntegrationUri`);
 	const { method, pathPattern } = parseRouteKey(routeKey);
+	const apiCdkPath = readApiCdkPath(apiLogicalId, template);
 	return [{
 		method,
 		pathPattern,
@@ -35147,6 +35153,8 @@ function discoverHttpApiRoute(logicalId, resource, template, stackName) {
 		apiVersion: "v2",
 		stage: "$default",
 		apiLogicalId,
+		apiStackName: stackName,
+		...apiCdkPath !== void 0 && { apiCdkPath },
 		declaredAt: `${stackName}/${logicalId}`
 	}];
 }
@@ -35159,23 +35167,38 @@ function discoverHttpApiRoute(logicalId, resource, template, stackName) {
 * we cannot do locally, and RESPONSE_STREAM uses a streaming response shape
 * (`InvokeWithResponseStream`) the RIE container does not implement.
 */
-function discoverFunctionUrl(logicalId, resource, stackName) {
+function discoverFunctionUrl(logicalId, resource, template, stackName) {
 	const props = resource.Properties ?? {};
 	const authType = props["AuthType"];
 	if (authType !== "NONE") throw new Error(`${stackName}/${logicalId} (AWS::Lambda::Url): AuthType '${String(authType)}' is not supported (only NONE — IAM auth requires SigV4 verification cdkd cannot emulate locally; deferred follow-up PR).`);
 	if (props["InvokeMode"] === "RESPONSE_STREAM") throw new Error(`${stackName}/${logicalId} (AWS::Lambda::Url): InvokeMode RESPONSE_STREAM is not supported (deferred follow-up PR).`);
 	const targetArn = props["TargetFunctionArn"];
+	const lambdaLogicalId = resolveLambdaArnIntrinsic(targetArn, `${stackName}/${logicalId}.TargetFunctionArn`);
+	const lambdaCdkPath = readApiCdkPath(lambdaLogicalId, template);
 	return [{
 		method: "ANY",
 		pathPattern: "/{proxy+}",
-		lambdaLogicalId: resolveLambdaArnIntrinsic(targetArn, `${stackName}/${logicalId}.TargetFunctionArn`),
+		lambdaLogicalId,
 		source: "function-url",
 		apiVersion: "v2",
 		stage: "$default",
+		apiStackName: stackName,
+		...lambdaCdkPath !== void 0 && { apiCdkPath: lambdaCdkPath },
 		declaredAt: `${stackName}/${logicalId}`
 	}];
 }
 /**
+* Read the `aws:cdk:path` metadata of the resource at `logicalId`,
+* returning the empty string when the resource is missing or the
+* metadata isn't set. Hides the "may be missing for a hand-rolled
+* `cfn.Resource`" branch from every call site.
+*/
+function readApiCdkPath(logicalId, template) {
+	const resource = template.Resources?.[logicalId];
+	if (!resource) return void 0;
+	return readCdkPath(resource) || void 0;
+}
+/**
 * Local intrinsic resolver for `IntegrationUri` (and the equivalent
 * `Uri` field on REST v1 Method.Integration). Delegates to the shared
 * `resolveLambdaArnIntrinsic` in `intrinsic-lambda-arn.ts` (extracted in
@@ -37901,39 +37924,74 @@ function groupRoutesByServer(routes) {
 /**
 * Filter the route list to a single API by user-supplied identifier.
 *
-* Matches against both the parent API logical id (HTTP API / REST v1)
-* AND the Function URL's backing-Lambda logical id, so users can pass
-* any of:
-*
-*   - The HTTP API logical id (e.g. `MyHttpApi`)
-*   - The REST API logical id (e.g. `MyRestApi`)
-*   - The Lambda logical id backing a Function URL (e.g. `GoHandler`)
+* Accepts four input forms — matches the rest of the `cdkd local *`
+* target-resolution family (`local invoke <target>` /
+* `local run-task <target>`) for consistency:
+*
+*   1. **Bare logical id** (`MyHttpApi`) — exact match on the parent
+*      API's logical id, or on the backing Lambda's logical id for
+*      Function URLs.
+*   2. **Stack-qualified logical id** (`MyStack:MyHttpApi`) — exact
+*      match on `<stackName>:<logicalId>`. Useful in multi-stack apps
+*      where the same bare logical id appears in two stacks.
+*   3. **CDK Construct path / display path** (`MyStack/MyHttpApi`) —
+*      exact match on the resource's `aws:cdk:path` metadata.
+*   4. **CDK Construct path prefix** — when the input is a strict
+*      ancestor of the resource's `aws:cdk:path` (i.e.
+*      `cdkPath.startsWith(input + '/')`). Mirrors the prefix rule
+*      `cdkd orphan` uses so an L2 wrapper path resolves to its L1
+*      child (`MyStack/MyHttpApi` matches `MyStack/MyHttpApi/Resource`).
+*
+* Routes discovered before this field set was added (or routes where
+* the synthesized template doesn't carry `aws:cdk:path` metadata —
+* e.g. hand-rolled `cfn.Resource` defs) silently fall through to the
+* bare-logical-id-only path so the change is non-breaking.
 *
 * Returns an empty array when no route matches — the caller is
 * responsible for surfacing a "no API matched" error with the list of
 * available identifiers (see {@link availableApiIdentifiers}).
 */
 function filterRoutesByApiIdentifier(routes, identifier) {
-	return routes.filter((rwa) => {
-		const r = rwa.route;
-		if (r.source === "function-url") return r.lambdaLogicalId === identifier;
-		return r.apiLogicalId === identifier;
-	});
+	return routes.filter((rwa) => routeMatchesIdentifier(rwa.route, identifier));
+}
+/**
+* Predicate behind {@link filterRoutesByApiIdentifier} and
+* {@link availableApiIdentifiers}'s primary-form selection. Exported
+* for test coverage only — the production code path goes through
+* `filterRoutesByApiIdentifier`.
+*/
+function routeMatchesIdentifier(route, identifier) {
+	const bareId = route.source === "function-url" ? route.lambdaLogicalId : route.apiLogicalId;
+	if (bareId && bareId === identifier) return true;
+	if (route.apiStackName) {
+		if (bareId && identifier === `${route.apiStackName}:${bareId}`) return true;
+	}
+	if (route.apiCdkPath) {
+		if (identifier === route.apiCdkPath) return true;
+		if (route.apiCdkPath.startsWith(`${identifier}/`)) return true;
+	}
+	return false;
 }
 /**
 * Enumerate every distinct API identifier in the route list, in the
 * order they were discovered. Useful for the "available APIs" error
 * message when `--api <id>` doesn't match.
+*
+* Returns the **primary form** per API (CDK Construct path when
+* available, else bare logical id) — the "available identifiers" hint
+* stays compact while pointing users at the form most likely to round-
+* trip across rename refactors.
 */
 function availableApiIdentifiers(routes) {
 	const seen = /* @__PURE__ */ new Set();
 	const out = [];
 	for (const rwa of routes) {
 		const r = rwa.route;
-		const id = r.source === "function-url" ? r.lambdaLogicalId : r.apiLogicalId ?? "<unknown>";
-		if (!seen.has(id)) {
-			seen.add(id);
-			out.push(id);
+		const bareId = r.source === "function-url" ? r.lambdaLogicalId : r.apiLogicalId ?? "<unknown>";
+		const primary = r.apiCdkPath ?? bareId;
+		if (!seen.has(primary)) {
+			seen.add(primary);
+			out.push(primary);
 		}
 	}
 	return out;
@@ -38932,7 +38990,7 @@ function parseDebugPort(raw) {
 * 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 and Cognito User Pool / HTTP v2 JWT authorizers; 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.").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>", "Restrict to a single API surface by its logical id (HTTP API / REST API logical id, or the backing Lambda's logical id for Function URLs). When unset, every discovered API gets its own server on its own port (basePort, basePort+1, ... when --port is set; auto-allocated otherwise).")).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 and Cognito User Pool / HTTP v2 JWT authorizers; 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.").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>", "Restrict to a single API surface. Accepts the bare CDK logical id (e.g. 'MyHttpApi'), the stack-qualified logical id ('MyStack:MyHttpApi'), the full CDK Construct path ('MyStack/MyHttpApi/Resource'), or an ancestor Construct path that prefix-matches ('MyStack/MyHttpApi'). For Function URLs, the path forms reference the backing Lambda's aws:cdk:path. When unset, every discovered API gets its own server on its own port (basePort, basePort+1, ... when --port is set; auto-allocated otherwise).")).action(withErrorHandling(localStartApiCommand));
 	[
 		...commonOptions,
 		...appOptions,
@@ -41771,7 +41829,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.94.13");
+	program.name("cdkd").description("CDK Direct - Deploy AWS CDK apps directly via SDK/Cloud Control API").version("0.94.15");
 	program.addCommand(createBootstrapCommand());
 	program.addCommand(createSynthCommand());
 	program.addCommand(createListCommand());