@go-to-k/cdkd 0.98.1 → 0.99.0

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

@@ -4754,23 +4754,75 @@ var SQSQueuePolicyProvider = class {
 	/**
 	* Adopt an existing SQS queue policy into cdkd state.
 	*
-	* **Explicit override only.** A `QueuePolicy` is an attachment applied to
-	* a queue via `SetQueueAttributes(Policy=...)` — it has no standalone
-	* identity and is not independently taggable. There is no `aws:cdk:path`
-	* tag to look up by; only the queue itself is taggable.
-	*
-	* Users adopting an existing queue policy should pass
-	* `--resource <logicalId>=<queueUrl>` (matching the physical id format
-	* returned by `create()`, which uses the first queue URL).
+	* The operational identifier for a `QueuePolicy` is the **queue URL**
+	* (`https://sqs.<region>.amazonaws.com/<account>/<name>`) — every AWS
+	* SDK call (`SetQueueAttributes` / `GetQueueAttributes`) takes a queue
+	* URL via the `QueueUrl` parameter, and cdkd's `create()` records the
+	* first `Queues` entry as the resource's `physicalId` so subsequent
+	* `update()` / `delete()` / `readCurrentState()` calls hit the right
+	* queue. A `QueuePolicy` has no standalone identity, no taggable ARN,
+	* and no `aws:cdk:path` lookup — only the parent queue is taggable.
+	*
+	* Resolution order (closes [#351](https://github.com/go-to-k/cdkd/issues/351)):
+	*
+	* 1. **`knownPhysicalId` if it is a valid queue URL.** Preserves the
+	*    `cdkd import --resource <logicalId>=<queueUrl>` path that has
+	*    always worked.
+	* 2. **First entry of `properties.Queues` if it is a literal queue URL.**
+	*    Closes the `--migrate-from-cloudformation` case: AWS CloudFormation's
+	*    `DescribeStackResources` returns the CFn-generated policy NAME for
+	*    `AWS::SQS::QueuePolicy` (e.g. `MyStack-MyQueuePolicy-XXXXXXXXXX`),
+	*    which is NOT a valid `QueueUrl` and crashes the AWS SDK
+	*    `queueUrlMiddleware` with `TypeError: Invalid URL` the first time
+	*    cdkd touches it (typically `captureObservedForImportedResources` →
+	*    `readCurrentState` → `GetQueueAttributes`). The user can also
+	*    point `--migrate-from-cloudformation` at a stack whose QueuePolicy
+	*    is templated as `Queues: ['https://sqs...']` (rare but valid) —
+	*    that literal form falls into this branch.
+	* 3. **Hard error** when neither path resolves a queue URL. This
+	*    covers (a) `--migrate-from-cloudformation` against a CFn stack
+	*    whose template carries `Queues: [{Ref: <MyQueue>}]` (the typical
+	*    CDK shape) when the referenced queue is NOT in the importable
+	*    set (or hasn't been imported yet in the current run), and (b)
+	*    explicit `--resource <logicalId>=<non-url>` typos. Pointing the
+	*    user at `--resource <logicalId>=<queueUrl>` is the recovery path
+	*    that always works.
+	*
+	* Intrinsic-valued `Queues[0]` (e.g. `{Ref: <MyQueue>}`) 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 && isSqsQueueUrl(input.knownPhysicalId)) return {
 			physicalId: input.knownPhysicalId,
 			attributes: {}
 		};
-		return null;
+		const queues = input.properties["Queues"];
+		if (Array.isArray(queues) && queues.length > 0) {
+			const first = queues[0];
+			if (typeof first === "string" && isSqsQueueUrl(first)) return {
+				physicalId: first,
+				attributes: {}
+			};
+		}
+		const knownNote = input.knownPhysicalId ? ` Got knownPhysicalId='${input.knownPhysicalId}' (not a queue URL; CloudFormation returns the policy resource NAME for AWS::SQS::QueuePolicy, which is not the operational identifier).` : "";
+		const queuesNote = Array.isArray(queues) && queues.length > 0 ? ` Properties.Queues[0]=${JSON.stringify(queues[0])} did not resolve to a literal queue URL (intrinsic-valued entries like {Ref: <Queue>} are not resolved at import time).` : " Properties.Queues is missing or empty.";
+		throw new Error(`Cannot determine queue URL for ${input.resourceType} '${input.logicalId}'.${knownNote}${queuesNote} Re-run with --resource ${input.logicalId}=<queueUrl> (e.g. https://sqs.${input.region}.amazonaws.com/<account>/<queue-name>) to point cdkd at the queue this policy is attached to.`);
 	}
 };
+/**
+* Recognize an SQS queue URL. AWS standard form is
+* `https://sqs.<region>.amazonaws.com/<account>/<name>`; FIFO queues end
+* in `.fifo`. Non-standard partitions (`amazonaws.com.cn` /
+* `c2s.ic.gov` / etc.) are accepted via the broader prefix check.
+*/
+function isSqsQueueUrl(value) {
+	return value.startsWith("https://sqs.") && value.includes("/");
+}
 
 //#endregion
 //#region src/provisioning/providers/sns-topic-provider.ts
@@ -38789,6 +38841,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++) {
@@ -38802,7 +38855,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);
 		}
@@ -39081,12 +39135,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),
@@ -39394,6 +39463,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);
@@ -39404,11 +39584,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;
@@ -42243,7 +42424,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.0");
+	program.name("cdkd").description("CDK Direct - Deploy AWS CDK apps directly via SDK/Cloud Control API").version("0.98.2");
 	program.addCommand(createBootstrapCommand());
 	program.addCommand(createSynthCommand());
 	program.addCommand(createListCommand());