@go-to-k/cdkd 0.95.0 → 0.96.1

package/README.md

@@ -420,8 +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 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
 ```
 
@@ -455,6 +455,16 @@ v1 scope notes.
 `cdk deploy`, manual creation, or another tool) into cdkd state so the
 next `cdkd deploy` updates them in-place instead of CREATEing duplicates.
 
+`cdkd import --migrate-from-cloudformation` extends this to migrate a
+**whole CloudFormation stack** off CFn in a single command: cdkd reads
+the source CFn stack's `(logicalId, physicalId)` mappings, adopts every
+resource into cdkd state, then retires the source CFn stack (injects
+`DeletionPolicy: Retain` + `UpdateReplacePolicy: Retain` on every
+resource → `UpdateStack` → `DeleteStack`) so the AWS resources stay
+intact but are no longer tracked by CFn. After the command finishes,
+the stack is managed by `cdkd deploy`. This is the reverse direction
+of `cdkd export` (see below).
+
 ```bash
 # Adopt a whole stack previously deployed by cdk deploy (tag-based auto-lookup).
 cdkd import MyStack --yes
@@ -479,17 +489,28 @@ AWS resources are unchanged across the migration; cdkd state for the
 exported stack is deleted on success. From then on the stack is managed
 by `cdk deploy` / `aws cloudformation`.
 
+Lambda-backed Custom Resources (`Custom::*` and
+`AWS::CloudFormation::CustomResource`) are NOT directly CFn-importable.
+`cdkd export --include-non-importable` opts into a 2-phase migration
+to handle them: phase 1 IMPORT changeset adopts every importable
+resource, then phase 2 UPDATE changeset re-CREATEs the Custom Resources
+through CFn — which re-invokes each backing Lambda's onCreate handler.
+The Custom Resource Lambda must be idempotent AND must POST to
+`event.ResponseURL` per the cfn-response protocol. Without the flag,
+the command refuses to proceed and the user is expected to destroy
+the offending resources (or accept abandoning them) first. Nested
+`AWS::CloudFormation::Stack` references always block (CFn can neither
+adopt nor recreate them).
+
 ```bash
 cdkd export MyStack                           # confirmation prompt; CFn stack name = cdkd stack name
 cdkd export MyStack --cfn-stack-name MyStack-CFn
 cdkd export MyStack --dry-run                 # print the import plan, do not call CFn
 cdkd export MyStack --template path.json      # skip synth, use a pre-rendered JSON template
+cdkd export MyStack --include-non-importable  # 2-phase: IMPORT importable + CFn-CREATE Custom Resources
 ```
 
-MVP scope: JSON templates only (CDK-generated). The command refuses to
-proceed if any resource is not CFn-importable (Lambda-backed Custom
-Resources, nested `AWS::CloudFormation::Stack` references); destroy or
-accept abandoning those resources first.
+MVP scope: JSON templates only (CDK-generated).
 
 ## Drift detection
 

package/dist/cli.js

@@ -37882,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)`;
 		}
@@ -38300,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,
@@ -38362,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;
 		}
@@ -38990,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. 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));
+	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,
@@ -41829,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.15");
+	program.name("cdkd").description("CDK Direct - Deploy AWS CDK apps directly via SDK/Cloud Control API").version("0.96.0");
 	program.addCommand(createBootstrapCommand());
 	program.addCommand(createSynthCommand());
 	program.addCommand(createListCommand());