@go-to-k/cdkd 0.94.15 → 0.95.0

package/README.md

@@ -420,6 +420,8 @@ and same-stack Lambda Layers bind-mounted at `/opt`.
 ```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
 ```
 

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.14");
+	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());