@go-to-k/cdkd 0.94.15 → 0.96.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 MyHttpApi                    # filter to one API (logical id, single-stack apps)
+cdkd local start-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
@@ -37859,19 +37882,20 @@ function groupRoutesByServer(routes) {
 		let kind;
 		let identifier;
 		let displayName;
+		const stackPrefix = r.apiStackName ? `${r.apiStackName}:` : "";
 		if (r.source === "function-url") {
 			identifier = r.lambdaLogicalId;
-			serverKey = `function-url:${identifier}`;
+			serverKey = `function-url:${stackPrefix}${identifier}`;
 			kind = "function-url";
 			displayName = `${identifier} (Function URL)`;
 		} else if (r.source === "http-api") {
 			identifier = r.apiLogicalId ?? "<unknown>";
-			serverKey = `http-api:${identifier}`;
+			serverKey = `http-api:${stackPrefix}${identifier}`;
 			kind = "http-api";
 			displayName = `${identifier} (HTTP API v2)`;
 		} else {
 			identifier = r.apiLogicalId ?? "<unknown>";
-			serverKey = `rest-v1:${identifier}`;
+			serverKey = `rest-v1:${stackPrefix}${identifier}`;
 			kind = "rest-v1";
 			displayName = `${identifier} (REST API v1)`;
 		}
@@ -37901,39 +37925,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;
@@ -38242,9 +38301,15 @@ function createAuthorizerCache(opts = {}) {
 * See [docs/cli-reference.md](../../../docs/cli-reference.md) for the
 * full surface and out-of-scope items.
 */
-async function localStartApiCommand(options) {
+async function localStartApiCommand(target, options) {
 	const logger = getLogger();
 	if (options.verbose) logger.setLevel("debug");
+	let apiFilter = target;
+	if (options.api !== void 0) {
+		if (target !== void 0) throw new Error(`Cannot specify both positional target ('${target}') and --api flag ('${options.api}'). Use one or the other. The positional form is preferred — '--api' is a deprecated alias.`);
+		logger.warn("[deprecated] --api <id> will be removed in a future major release. Use the positional argument instead: 'cdkd local start-api <id>'.");
+		apiFilter = options.api;
+	}
 	warnIfDeprecatedRegion(options);
 	await applyRoleArnIfSet({
 		roleArn: options.roleArn,
@@ -38304,11 +38369,12 @@ async function localStartApiCommand(options) {
 		}
 		attachStageContext(routes, stageMap);
 		let routesWithAuth = attachAuthorizers(targetStacks, routes);
-		if (options.api) {
-			const filtered = filterRoutesByApiIdentifier(routesWithAuth, options.api);
+		if (apiFilter !== void 0) {
+			if (!apiFilter.includes(":") && !apiFilter.includes("/") && targetStacks.length > 1) throw new Error(`Multiple stacks in app, target '${apiFilter}' is missing a stack prefix. Use 'StackName:${apiFilter}' or 'StackName/${apiFilter}' (Construct path form). Available stacks: ${targetStacks.map((s) => s.stackName).join(", ")}.`);
+			const filtered = filterRoutesByApiIdentifier(routesWithAuth, apiFilter);
 			if (filtered.length === 0) {
 				const available = availableApiIdentifiers(routesWithAuth).join(", ") || "(none)";
-				throw new Error(`--api '${options.api}' did not match any discovered API. Available identifiers: ${available}.`);
+				throw new Error(`Target '${apiFilter}' did not match any discovered API. Available identifiers: ${available}.`);
 			}
 			routesWithAuth = filtered;
 		}
@@ -38932,7 +38998,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.").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.")).action(withErrorHandling(localStartApiCommand));
 	[
 		...commonOptions,
 		...appOptions,
@@ -41771,7 +41837,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.95.0");
 	program.addCommand(createBootstrapCommand());
 	program.addCommand(createSynthCommand());
 	program.addCommand(createListCommand());