@go-to-k/cdkd 0.98.2 → 0.99.1

package/README.md

@@ -448,13 +448,15 @@ 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
+cdkd local start-api --from-state                 # substitute deployed env vars in Lambda Environment
 ```
 
 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`.
+preflight; hot reload via `--watch`; deploy-state-backed env var
+substitution via `--from-state`.
 
 ### `local run-task`
 

package/dist/cli.js

@@ -4217,23 +4217,83 @@ var S3BucketPolicyProvider = class {
 	/**
 	* Adopt an existing S3 bucket policy into cdkd state.
 	*
-	* **Explicit override only.** An `S3::BucketPolicy` is a policy document
-	* attached to a bucket via `PutBucketPolicy` — it has no standalone
-	* identity and is not independently taggable. There is no `aws:cdk:path`
-	* tag to look up by; only the bucket itself is taggable.
+	* The operational identifier for an `S3::BucketPolicy` is the **bucket
+	* name** — every AWS SDK call (`PutBucketPolicy` / `GetBucketPolicy` /
+	* `DeleteBucketPolicy`) takes the bucket name via the `Bucket`
+	* parameter, and cdkd's `create()` records `properties.Bucket` as the
+	* resource's `physicalId` so subsequent `update()` / `delete()` /
+	* `readCurrentState()` calls hit the right bucket. A `BucketPolicy`
+	* has no standalone identity, no taggable ARN, and no `aws:cdk:path`
+	* lookup — only the bucket itself is taggable.
+	*
+	* Resolution order (closes [#356](https://github.com/go-to-k/cdkd/issues/356)):
+	*
+	* 1. **`knownPhysicalId` if it matches an S3 bucket name shape.**
+	*    Preserves the `cdkd import --resource <logicalId>=<bucketName>`
+	*    path that has always worked.
+	* 2. **`properties.Bucket` if it is a literal bucket name.** Closes
+	*    the `--migrate-from-cloudformation` case: AWS CloudFormation's
+	*    `DescribeStackResources` returns the CFn-generated policy NAME
+	*    for `AWS::S3::BucketPolicy` (e.g.
+	*    `MyStack-MyBucketPolicy-XXXXXXXXXX`), which is NOT a valid S3
+	*    bucket name. The first time cdkd touches the imported state with
+	*    that name, `readCurrentState` → `GetBucketPolicy` rejects it.
+	* 3. **Hard error** when neither path resolves a bucket name. This
+	*    covers (a) `--migrate-from-cloudformation` against a CFn stack
+	*    whose template carries `Bucket: {Ref: <MyBucket>}` (the typical
+	*    CDK shape) when the referenced bucket is NOT in the importable
+	*    set (or hasn't been imported yet in the current run), and (b)
+	*    explicit `--resource <logicalId>=<non-bucket-name>` typos.
+	*    Pointing the user at `--resource <logicalId>=<bucketName>` is
+	*    the recovery path that always works.
 	*
-	* Users adopting an existing bucket policy should pass
-	* `--resource <logicalId>=<bucketName>` (matching the physical id
-	* format returned by `create()`).
+	* Intrinsic-valued `Bucket` (e.g. `{Ref: <MyBucket>}`) falls into
+	* branch 3 here even when the referenced sibling has been imported in
+	* the same run — `import()` is called BEFORE
+	* `resolveImportedProperties` runs the synth template's Properties
+	* through the intrinsic resolver, so the raw intrinsic object is what
+	* we see. The recovery message names `--resource` as the explicit
+	* escape hatch.
 	*/
 	async import(input) {
-		if (input.knownPhysicalId) return {
+		if (input.knownPhysicalId && isS3BucketName(input.knownPhysicalId)) return {
 			physicalId: input.knownPhysicalId,
 			attributes: {}
 		};
-		return null;
+		const bucket = input.properties["Bucket"];
+		if (typeof bucket === "string" && isS3BucketName(bucket)) return {
+			physicalId: bucket,
+			attributes: {}
+		};
+		const knownNote = input.knownPhysicalId ? ` Got knownPhysicalId='${input.knownPhysicalId}' (not a valid S3 bucket name; CloudFormation returns the policy resource NAME for AWS::S3::BucketPolicy, which is not the operational identifier).` : "";
+		const bucketNote = bucket !== void 0 ? ` Properties.Bucket=${JSON.stringify(bucket)} did not resolve to a literal bucket name (intrinsic-valued entries like {Ref: <Bucket>} are not resolved at import time).` : " Properties.Bucket is missing.";
+		throw new Error(`Cannot determine bucket name for ${input.resourceType} '${input.logicalId}'.${knownNote}${bucketNote} Re-run with --resource ${input.logicalId}=<bucketName> (e.g. my-bucket-12345) to point cdkd at the bucket this policy is attached to.`);
 	}
 };
+/**
+* Recognize an S3 bucket name. AWS rules
+* (https://docs.aws.amazon.com/AmazonS3/latest/userguide/bucketnamingrules.html):
+*   - 3-63 characters
+*   - lowercase letters, digits, hyphens, and dots
+*   - must start and end with a letter or digit
+*   - no consecutive dots
+*   - no `xn--` prefix (reserved for IDN bucket names)
+*   - no `-s3alias` suffix (reserved for S3 Access Point aliases)
+*   - no `--ol-s3` suffix (reserved for S3 on Outposts)
+*
+* A practical pattern that excludes the obvious CFn-generated names like
+* `MyStack-MyBucketPolicy-XXXXXXXXXX` (which contain uppercase letters
+* and exceed 63 chars in common cases) while accepting every normal CDK
+* auto-generated and user-declared bucket name.
+*/
+function isS3BucketName(value) {
+	if (value.length < 3 || value.length > 63) return false;
+	if (!/^[a-z0-9][a-z0-9.-]*[a-z0-9]$/.test(value)) return false;
+	if (value.includes("..")) return false;
+	if (value.startsWith("xn--")) return false;
+	if (value.endsWith("-s3alias") || value.endsWith("--ol-s3")) return false;
+	return true;
+}
 
 //#endregion
 //#region src/provisioning/providers/sqs-queue-provider.ts
@@ -5593,22 +5653,60 @@ var SNSTopicPolicyProvider = class {
 	/**
 	* Adopt an existing SNS topic policy into cdkd state.
 	*
-	* **Explicit override only.** A `TopicPolicy` is an attachment to one or
-	* more SNS topics applied via `SetTopicAttributes(AttributeName=Policy)` —
-	* it has no standalone identity and is not independently taggable. There
-	* is no `aws:cdk:path` tag to look up by, and the policy has no name/ARN
-	* of its own.
+	* The operational identifier for a `TopicPolicy` is the **comma-joined
+	* list of SNS topic ARNs** the policy is attached to — every AWS SDK
+	* call (`SetTopicAttributes` / `GetTopicAttributes`) takes a topic ARN
+	* via the `TopicArn` parameter, and cdkd's `create()` records
+	* `topics.join(',')` as the resource's `physicalId` so subsequent
+	* `update()` / `delete()` / `readCurrentState()` calls hit the right
+	* topic(s). A `TopicPolicy` has no standalone identity, no taggable
+	* ARN, and no `aws:cdk:path` lookup — only the parent topics are
+	* taggable.
+	*
+	* Resolution order (closes [#356](https://github.com/go-to-k/cdkd/issues/356)):
+	*
+	* 1. **`knownPhysicalId` if it is a comma-joined list of SNS topic ARNs.**
+	*    Preserves the `cdkd import --resource <logicalId>=<topic-arns>`
+	*    path that has always worked.
+	* 2. **`properties.Topics.join(',')` if every entry is a literal topic
+	*    ARN.** Closes the `--migrate-from-cloudformation` case: AWS
+	*    CloudFormation's `DescribeStackResources` returns the CFn-generated
+	*    policy NAME for `AWS::SNS::TopicPolicy` (e.g.
+	*    `MyStack-MyTopicPolicy-XXXXXXXXXX`), which is NOT a valid topic
+	*    ARN. The first time cdkd touches the imported state with that
+	*    name, `readCurrentState` → `GetTopicAttributes` rejects it.
+	* 3. **Hard error** when neither path resolves a topic-ARN list. This
+	*    covers (a) `--migrate-from-cloudformation` against a CFn stack
+	*    whose template carries `Topics: [{Ref: <MyTopic>}]` (the typical
+	*    CDK shape) when the referenced topic is NOT in the importable
+	*    set (or hasn't been imported yet in the current run), and (b)
+	*    explicit `--resource <logicalId>=<non-arn>` typos. Pointing the
+	*    user at `--resource <logicalId>=<topic-arns>` is the recovery
+	*    path that always works.
 	*
-	* Users adopting an existing topic policy should pass
-	* `--resource <logicalId>=<comma-joined-topic-ARNs>` (matching the
-	* physical id format returned by `create()`).
+	* Intrinsic-valued `Topics` entries (e.g. `{Ref: <MyTopic>}`) fall into
+	* branch 3 here even when the referenced sibling has been imported in
+	* the same run — `import()` is called BEFORE
+	* `resolveImportedProperties` runs the synth template's Properties
+	* through the intrinsic resolver, so the raw intrinsic object is what
+	* we see. The recovery message names `--resource` as the explicit
+	* escape hatch.
 	*/
 	async import(input) {
-		if (input.knownPhysicalId) return {
+		if (input.knownPhysicalId && isSnsTopicArnList(input.knownPhysicalId)) return {
 			physicalId: input.knownPhysicalId,
 			attributes: {}
 		};
-		return null;
+		const topics = input.properties["Topics"];
+		if (Array.isArray(topics) && topics.length > 0) {
+			if (topics.every((t) => typeof t === "string" && isSnsTopicArn(t))) return {
+				physicalId: topics.join(","),
+				attributes: {}
+			};
+		}
+		const knownNote = input.knownPhysicalId ? ` Got knownPhysicalId='${input.knownPhysicalId}' (not a comma-joined list of SNS topic ARNs; CloudFormation returns the policy resource NAME for AWS::SNS::TopicPolicy, which is not the operational identifier).` : "";
+		const topicsNote = Array.isArray(topics) && topics.length > 0 ? ` Properties.Topics=${JSON.stringify(topics)} did not resolve to a list of literal topic ARNs (intrinsic-valued entries like {Ref: <Topic>} are not resolved at import time).` : " Properties.Topics is missing or empty.";
+		throw new Error(`Cannot determine topic ARNs for ${input.resourceType} '${input.logicalId}'.${knownNote}${topicsNote} Re-run with --resource ${input.logicalId}=<comma-joined-topic-ARNs> (e.g. arn:aws:sns:${input.region}:<account>:<topic-name>) to point cdkd at the topic(s) this policy is attached to.`);
 	}
 	/**
 	* Set the policy on a single SNS topic
@@ -5621,6 +5719,31 @@ var SNSTopicPolicyProvider = class {
 		}));
 	}
 };
+/**
+* Recognize a single SNS topic ARN. AWS standard form is
+* `arn:<partition>:sns:<region>:<account>:<name>`; FIFO topics end in
+* `.fifo`. Accepts every partition (`aws` / `aws-cn` / `aws-us-gov` /
+* `aws-iso` / etc.) via the broader `arn:<partition>:sns:` prefix shape.
+*/
+function isSnsTopicArn(value) {
+	return /^arn:[a-z0-9-]+:sns:[a-z0-9-]+:\d{12}:[\w.-]+$/.test(value);
+}
+/**
+* Recognize a comma-joined list of SNS topic ARNs. cdkd's `create()`
+* records `topics.join(',')` as the `physicalId`, so a single ARN
+* (`arn:aws:sns:us-east-1:123456789012:my-topic`) is also accepted.
+* Every comma-separated segment must be a valid SNS topic ARN — a CFn
+* generated name like `MyStack-MyTopicPolicy-XXX` is correctly rejected
+* because it does not match the ARN prefix, and a partially-valid
+* mixture (one literal ARN + one CFn name) is also rejected so we fall
+* back to the properties-based resolution rather than baking a half-bad
+* list into state.
+*/
+function isSnsTopicArnList(value) {
+	const segments = value.split(",");
+	if (segments.length === 0) return false;
+	return segments.every((s) => isSnsTopicArn(s));
+}
 
 //#endregion
 //#region src/provisioning/providers/lambda-function-provider.ts
@@ -38841,6 +38964,7 @@ async function localStartApiCommand(target, options) {
 			const m = buildCorsConfigByApiId(stack.template);
 			for (const [k, v] of m) corsConfigByApiId.set(k, v);
 		}
+		const stateByStack = options.fromState ? await loadStateForRoutedStacks(targetStacks, routes, routesWithAuth, options) : /* @__PURE__ */ new Map();
 		const lambdaIds = uniqueLambdaIds(routes, routesWithAuth);
 		const specs = /* @__PURE__ */ new Map();
 		for (let i = 0; i < lambdaIds.length; i++) {
@@ -38854,7 +38978,8 @@ async function localStartApiCommand(target, options) {
 				...debugPortBase !== void 0 && { debugPort: debugPortBase + i },
 				stsRegion: options.region ?? process.env["AWS_REGION"] ?? process.env["AWS_DEFAULT_REGION"],
 				inlineTmpDirs,
-				layerTmpDirs
+				layerTmpDirs,
+				stateByStack
 			});
 			specs.set(logicalId, spec);
 		}
@@ -39133,12 +39258,27 @@ function warnVpcConfigLambdas(routesWithAuth, stacks) {
 * missing, runtime not supported).
 */
 async function buildContainerSpec(args) {
-	const { logicalId, stacks, overrides, assumeRole, containerHost, debugPort, stsRegion, inlineTmpDirs, layerTmpDirs } = args;
+	const { logicalId, stacks, overrides, assumeRole, containerHost, debugPort, stsRegion, inlineTmpDirs, layerTmpDirs, stateByStack } = args;
 	const lambda = resolveLambdaByLogicalId(logicalId, stacks);
 	const codeDir = lambda.codePath ?? materializeInlineCode$1(lambda.handler, lambda.inlineCode ?? "", resolveRuntimeFileExtension(lambda.runtime), inlineTmpDirs);
 	const optDir = materializeLambdaLayers$1(lambda.layers, layerTmpDirs);
-	const envResult = resolveEnvVars(logicalId, getTemplateEnv$1(lambda.resource), overrides);
-	for (const key of envResult.unresolved) getLogger().warn(`Lambda ${logicalId}: env var ${key} contains a CloudFormation intrinsic and was dropped. Override it with --env-vars (e.g. {"${logicalId}":{"${key}":"<literal>"}}) to surface a literal value.`);
+	let templateEnv = getTemplateEnv$1(lambda.resource);
+	const stateBundle = stateByStack.get(lambda.stack.stackName);
+	let stateAudit;
+	if (stateBundle) {
+		const context = { resources: stateBundle.state.resources };
+		if (stateBundle.pseudoParameters) context.pseudoParameters = stateBundle.pseudoParameters;
+		const { env, audit } = substituteEnvVarsFromState(templateEnv, context);
+		templateEnv = env;
+		stateAudit = audit;
+		for (const key of audit.resolvedKeys) getLogger().debug(`Lambda ${logicalId}: --from-state substituted env var ${key}`);
+		for (const { key, reason } of audit.unresolved) getLogger().warn(`Lambda ${logicalId}: --from-state could not substitute env var ${key} (${reason}). Override it via --env-vars or it will be dropped.`);
+	}
+	const envResult = resolveEnvVars(logicalId, templateEnv, overrides);
+	for (const key of envResult.unresolved) {
+		if (stateAudit && stateAudit.unresolved.some((u) => u.key === key)) continue;
+		getLogger().warn(`Lambda ${logicalId}: env var ${key} contains a CloudFormation intrinsic and was dropped. Override it with --env-vars (e.g. {"${logicalId}":{"${key}":"<literal>"}}) or pass --from-state to recover deployed values.`);
+	}
 	const dockerEnv = {
 		AWS_LAMBDA_FUNCTION_NAME: logicalId,
 		AWS_LAMBDA_FUNCTION_MEMORY_SIZE: String(lambda.memoryMb),
@@ -39446,6 +39586,117 @@ async function reloadAllServers(args) {
 	if (watcher) watcher.update([output, ...lastAssetPaths.value]);
 	printPerServerRouteTables(servers);
 }
+/**
+* Returns true when any value in the function's template env map is a
+* CFn intrinsic (non-primitive). Used to gate the pseudo-parameter STS
+* hop inside the `--from-state` flow: literal-only env maps don't need
+* the pseudo-parameter bag and shouldn't pay for an STS call. Mirrors
+* the same gating in `local-invoke.ts` (`envHasIntrinsicValue`) and
+* `ecs-task-resolver.ts` (`containerHasIntrinsicEnvOrSecret`).
+*/
+function envHasIntrinsicValue$1(templateEnv) {
+	if (!templateEnv) return false;
+	for (const v of Object.values(templateEnv)) {
+		if (v === void 0 || v === null) continue;
+		if (typeof v === "string" || typeof v === "number" || typeof v === "boolean") continue;
+		return true;
+	}
+	return false;
+}
+/**
+* Load cdkd's S3 state for every stack that owns a routed Lambda. Once
+* per `synthesizeAndBuild` pass (initial boot + every reload), so a
+* Lambda's per-spec build does not pay one round-trip per Lambda. Per-
+* stack failures (no state, ambiguous region, bucket resolution error)
+* degrade to warn-and-fall-back via {@link loadStateForStack} — the
+* affected stack's reachable Lambdas behave as if `--from-state` were
+* not set, while sibling stacks with loadable state still substitute.
+*
+* Pseudo parameters are resolved per stack and only when at least one
+* reachable Lambda in that stack has an intrinsic-valued env entry
+* (gated via {@link envHasIntrinsicValue}). STS failures degrade to
+* warn and leave `pseudoParameters: undefined` — substitution still
+* runs for non-`AWS::*` refs.
+*/
+async function loadStateForRoutedStacks(stacks, routes, routesWithAuth, options) {
+	const logger = getLogger();
+	const out = /* @__PURE__ */ new Map();
+	const lambdaIds = uniqueLambdaIds(routes, routesWithAuth);
+	const reachableStackNames = /* @__PURE__ */ new Set();
+	for (const logicalId of lambdaIds) for (const stack of stacks) {
+		const resource = stack.template.Resources?.[logicalId];
+		if (resource && resource.Type === "AWS::Lambda::Function") {
+			reachableStackNames.add(stack.stackName);
+			break;
+		}
+	}
+	const stackHasIntrinsicEnv = (stackName) => {
+		for (const logicalId of lambdaIds) for (const stack of stacks) {
+			if (stack.stackName !== stackName) continue;
+			const resource = stack.template.Resources?.[logicalId];
+			if (!resource || resource.Type !== "AWS::Lambda::Function") continue;
+			if (envHasIntrinsicValue$1(getTemplateEnv$1(resource))) return true;
+		}
+		return false;
+	};
+	for (const stackName of reachableStackNames) {
+		const stack = stacks.find((s) => s.stackName === stackName);
+		if (!stack) continue;
+		const loaded = await loadStateForStack(stack.stackName, stack.region, {
+			...options.stackRegion !== void 0 && { stackRegion: options.stackRegion },
+			...options.stateBucket !== void 0 && { stateBucket: options.stateBucket },
+			statePrefix: options.statePrefix,
+			...options.region !== void 0 && { region: options.region },
+			...options.profile !== void 0 && { profile: options.profile }
+		});
+		if (!loaded) continue;
+		const bundle = { state: loaded.state };
+		if (stackHasIntrinsicEnv(stackName)) {
+			const pseudo = await resolvePseudoParametersForStartApi(loaded.region, options);
+			if (pseudo) bundle.pseudoParameters = pseudo;
+		}
+		out.set(stackName, bundle);
+		logger.debug(`--from-state: loaded state for ${stackName} (${loaded.region})`);
+	}
+	return out;
+}
+/**
+* Build the AWS pseudo-parameter bag for `--from-state` env-var
+* substitution. Mirrors `resolvePseudoParametersForInvoke` in
+* `local-invoke.ts` byte-for-byte — kept inlined here rather than
+* extracted into a shared helper because the two call sites differ in
+* region precedence (this one is per-stack so the resolved state
+* region takes priority).
+*
+* Region precedence: `--region` > `AWS_REGION` > `AWS_DEFAULT_REGION` >
+* the state record's region (returned by `loadStateForStack`).
+*/
+async function resolvePseudoParametersForStartApi(stateRegion, options) {
+	const logger = getLogger();
+	const region = options.region ?? process.env["AWS_REGION"] ?? process.env["AWS_DEFAULT_REGION"] ?? stateRegion;
+	let accountId;
+	try {
+		const { STSClient, GetCallerIdentityCommand } = await import("@aws-sdk/client-sts");
+		const sts = new STSClient({ ...region && { region } });
+		try {
+			accountId = (await sts.send(new GetCallerIdentityCommand({}))).Account;
+		} finally {
+			sts.destroy();
+		}
+	} catch (err) {
+		logger.warn(`--from-state: resolver needs \${AWS::AccountId} but STS GetCallerIdentity failed: ${err instanceof Error ? err.message : String(err)}. Substitution will be skipped for AWS::AccountId; affected env entries will be dropped with per-key warnings.`);
+	}
+	const partitionAndSuffix = region ? derivePartitionAndUrlSuffix(region) : void 0;
+	const bag = {
+		...accountId !== void 0 && { accountId },
+		...region !== void 0 && { region },
+		...partitionAndSuffix && {
+			partition: partitionAndSuffix.partition,
+			urlSuffix: partitionAndSuffix.urlSuffix
+		}
+	};
+	return Object.keys(bag).length === 0 ? void 0 : bag;
+}
 /** Validate `--debug-port-base`. */
 function parseDebugPort(raw) {
 	const parsed = parseInt(raw, 10);
@@ -39456,11 +39707,12 @@ 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.").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));
+	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.")).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("--stack-region <region>", "Region of the cdkd state record to read (used with --from-state when the same stack name has state in multiple regions).")).action(withErrorHandling(localStartApiCommand));
 	[
 		...commonOptions,
 		...appOptions,
-		...contextOptions
+		...contextOptions,
+		...stateOptions
 	].forEach((opt) => startApi.addOption(opt));
 	startApi.addOption(deprecatedRegionOption);
 	return startApi;
@@ -42295,7 +42547,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.98.1");
+	program.name("cdkd").description("CDK Direct - Deploy AWS CDK apps directly via SDK/Cloud Control API").version("0.99.0");
 	program.addCommand(createBootstrapCommand());
 	program.addCommand(createSynthCommand());
 	program.addCommand(createListCommand());