@go-to-k/cdkd 0.168.0 → 0.169.0

package/README.md

@@ -190,10 +190,12 @@ cdkd drift MyStack --revert --yes   # AWS ← state
 # Asset / destroy / unlock
 cdkd publish-assets                 # synth + upload only (typical CI split)
 cdkd destroy MyStack
+cdkd orphan MyStack/MyBucket        # drop one resource from state (AWS resource stays)
 cdkd force-unlock MyStack           # clear stale lock from an interrupted deploy
 
-# Adopt existing AWS resources into cdkd state
-cdkd import MyStack --yes
+# Migrate between cdkd and CloudFormation
+cdkd import MyStack --yes           # adopt existing AWS resources into cdkd state
+cdkd export MyStack                 # hand a cdkd-managed stack back to CloudFormation
 
 # State-bucket-only commands (no CDK app needed)
 cdkd state info                     # bucket name, region, schema version
@@ -264,6 +266,11 @@ bind-mounted at `/opt`.
 cdkd local start-api                                 # one HTTP server per discovered API
 cdkd local start-api MyStack/MyHttpApi --watch       # filter + hot reload
 cdkd local start-api --from-state                    # OR --from-cfn-stack
+
+# Typical shape — the bare `--from-cfn-stack` flag auto-resolves to the
+# routed stack's name (here `MyStack`). Pass an explicit value only when
+# the deployed CFn stack name differs from the CDK stack name.
+cdkd local start-api MyStack/MyHttpApi --from-cfn-stack
 ```
 
 REST v1 + HTTP API v2 + Function URL with all integration kinds

package/dist/cli.js

@@ -36475,6 +36475,21 @@ function readCdkPath(resource) {
 	return typeof v === "string" ? v : "";
 }
 /**
+* Same lookup as `readCdkPath`, but returns `undefined` instead of an
+* empty string when no `aws:cdk:path` metadata is present.
+*
+* Use this variant when the caller passes the value into APIs whose
+* contract distinguishes "no path known" from "empty path". For example,
+* `resolveEnvVars(logicalId, displayPath, ...)` short-circuits the
+* display-path lookup when `displayPath` is `undefined`, but an empty
+* string `''` would still hit the loop and could spuriously match a
+* malformed override key.
+*/
+function readCdkPathOrUndefined(resource) {
+	const path = readCdkPath(resource);
+	return path === "" ? void 0 : path;
+}
+/**
 * Build a `Map<cdkPath, logicalId>` from a synthesized template.
 *
 * Used by `cdkd orphan <constructPath>` to translate user-supplied
@@ -43668,21 +43683,37 @@ function looksLikeAccessDenied(err) {
 * @param logicalId         The function's CloudFormation logical ID. Used
 *                          to look up function-specific overrides in the
 *                          `--env-vars` file.
+* @param displayPath       The function's CDK display path
+*                          (`Metadata['aws:cdk:path']`, e.g.
+*                          `"MyStack/MyHandler"`), or `undefined` when
+*                          the resource has no path metadata. Display-path
+*                          keys in the override file are matched against
+*                          this value in addition to `logicalId`. Pass
+*                          `undefined` rather than the logical ID when no
+*                          path is known, so the override lookup does not
+*                          accidentally double-match the same key.
 * @param templateEnv       The function's `Properties.Environment.Variables`
 *                          object from the synthesized template, or
 *                          `undefined` when the function has no env vars.
 * @param overrides         Parsed `--env-vars` file contents, or
 *                          `undefined` when the flag was not passed.
 */
-function resolveEnvVars(logicalId, templateEnv, overrides) {
+function resolveEnvVars(logicalId, displayPath, templateEnv, overrides) {
 	const resolved = {};
 	const unresolved = [];
 	if (templateEnv) for (const [key, value] of Object.entries(templateEnv)) if (isLiteralEnvValue(value)) resolved[key] = String(value);
 	else unresolved.push(key);
 	if (overrides) {
 		applyOverrideMap$1(resolved, overrides.Parameters);
-		const fnOverrides = overrides[logicalId];
-		if (fnOverrides && typeof fnOverrides === "object") applyOverrideMap$1(resolved, fnOverrides);
+		for (const [key, val] of Object.entries(overrides)) {
+			if (key === "Parameters") continue;
+			if (!val || typeof val !== "object") continue;
+			if (key === logicalId) {
+				applyOverrideMap$1(resolved, val);
+				continue;
+			}
+			if (displayPath && (displayPath === key || displayPath.startsWith(`${key}/`))) applyOverrideMap$1(resolved, val);
+		}
 	}
 	return {
 		resolved,
@@ -55108,6 +55139,7 @@ async function localStartApiCommand(target, options) {
 	const jwksWarnedUrls = /* @__PURE__ */ new Set();
 	let sigV4CredentialsLoader;
 	const sigV4WarnedForeignIds = /* @__PURE__ */ new Set();
+	const fromCfnTipEmitted = { value: false };
 	/**
 	* One synth + discover + build pass. Returns the next-state
 	* material. Reused on initial boot AND every hot-reload firing.
@@ -55133,8 +55165,14 @@ async function localStartApiCommand(target, options) {
 			...options.profile && { macroExpandS3ClientOpts: { profile: options.profile } }
 		};
 		const { stacks } = await synthesizer.synthesize(synthOpts);
-		const targetStacks = pickTargetStacks(stacks, options.stack);
-		if (targetStacks.length === 0) throw new Error("No stacks matched. Pass --stack <name> or run from a single-stack app.");
+		const cfnStackFallback = typeof options.fromCfnStack === "string" ? options.fromCfnStack : void 0;
+		const targetStackPrefix = target?.includes("/") === true ? target.slice(0, target.indexOf("/")) : void 0;
+		const targetStacks = pickTargetStacks(stacks, options.stack, cfnStackFallback, targetStackPrefix);
+		if (targetStacks.length === 0) throw new Error("No stacks matched. Pass --stack <name> (or --from-cfn-stack <name>) or run from a single-stack app.");
+		const routedStackNames = targetStacks.map((s) => s.stackName);
+		tryEmitFromCfnRedundancyTipOnce(options.fromCfnStack, routedStackNames, fromCfnTipEmitted, (routedStackName) => {
+			logger.info(`tip: --from-cfn-stack value matches the routed stack name (${routedStackName}); you can omit the value: \`cdkd local start-api ... --from-cfn-stack\` (bare flag) resolves to the same value.`);
+		});
 		const routes = discoverRoutes(targetStacks);
 		const wsDiscovery = discoverWebSocketApis(targetStacks);
 		if (wsDiscovery.errors.length > 0) for (const e of wsDiscovery.errors) logger.warn(`WebSocket discovery: ${e}`);
@@ -55509,12 +55547,60 @@ async function localStartApiCommand(target, options) {
 * Match the `--stack` pattern (or single-stack auto-detect) to a list
 * of stacks the route-discovery walks. Mirrors the deploy/diff matcher
 * routing rules.
+*
+* @internal exported for unit tests.
 */
-function pickTargetStacks(stacks, pattern) {
-	if (pattern) return matchStacks(stacks, [pattern]);
+function pickTargetStacks(stacks, pattern, cfnStackFallback, targetFallback) {
+	const effective = pattern ?? cfnStackFallback ?? targetFallback;
+	if (effective) return matchStacks(stacks, [effective]);
 	if (stacks.length === 1) return stacks;
 	if (stacks.length === 0) return [];
-	throw new Error(`Multi-stack app: pass --stack <name> to pick a target. Available stacks: ${stacks.map((s) => s.stackName).join(", ")}.`);
+	throw new Error(`Multi-stack app: pass --stack <name>, --from-cfn-stack <name>, or a stack-qualified target like "<StackName>/<construct>" to pick a target. Available stacks: ${stacks.map((s) => s.stackName).join(", ")}.`);
+}
+/**
+* Decide whether the `--from-cfn-stack <name>` redundancy tip should
+* fire for the current invocation. Fires only when:
+*  - `fromCfnStack` is a non-empty STRING (explicit value, not bare `true`)
+*  - exactly ONE stack is routed
+*  - the explicit value equals the routed stack's `stackName`
+*
+* Extracted as a pure function so it can be unit-tested without booting
+* the full server. See improvement A in the start-api UX PR.
+*
+* @internal exported for unit tests.
+*/
+function shouldEmitFromCfnRedundancyTip(fromCfnStack, routedStackNames) {
+	if (typeof fromCfnStack !== "string") return false;
+	if (fromCfnStack.length === 0) return false;
+	if (routedStackNames.length !== 1) return false;
+	return fromCfnStack === routedStackNames[0];
+}
+/**
+* One-shot wrapper around `shouldEmitFromCfnRedundancyTip` for the
+* `--watch` hot-reload path. `synthesizeAndBuild` re-runs on every
+* reload firing, so without a gate the tip would re-emit on every
+* reload — noisy. This helper consults the caller-supplied ref:
+*  - If the predicate fires AND the ref is still `false`, calls `emit`
+*    and flips the ref to `true`.
+*  - On subsequent invocations the ref is `true` and the helper is a
+*    no-op for the rest of the ref's lifetime.
+*  - When the predicate does NOT fire (no `--from-cfn-stack` value /
+*    intentionally-different value / multi-stack run), the ref stays
+*    `false` so a future reload whose synthesized stacks change in a
+*    way that DOES make the value redundant still emits the tip once.
+*
+* The ref is owned by `localStartApiCommand` (one per server boot), so
+* independent server invocations get independent flags.
+*
+* @internal exported for unit tests.
+*/
+function tryEmitFromCfnRedundancyTipOnce(fromCfnStack, routedStackNames, emittedRef, emit) {
+	if (emittedRef.value) return;
+	if (!shouldEmitFromCfnRedundancyTip(fromCfnStack, routedStackNames)) return;
+	const routedStackName = routedStackNames[0];
+	if (routedStackName === void 0) return;
+	emit(routedStackName);
+	emittedRef.value = true;
 }
 /**
 * Distinct, stable list of Lambda logical IDs reachable through any
@@ -55656,10 +55742,12 @@ async function buildContainerSpec(args) {
 		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);
+	const lambdaCdkPath = readCdkPathOrUndefined(lambda.resource);
+	const envResult = resolveEnvVars(logicalId, lambdaCdkPath, 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 overrideKeyExample = lambdaCdkPath?.replace(/\/Resource$/, "") ?? logicalId;
+		getLogger().warn(`Lambda ${logicalId}: env var ${key} contains a CloudFormation intrinsic and was dropped. Override it with --env-vars (e.g. {"${overrideKeyExample}":{"${key}":"<literal>"}}) or pass --from-state to recover deployed values.`);
 	}
 	const dockerEnv = {
 		AWS_LAMBDA_FUNCTION_NAME: logicalId,
@@ -59180,10 +59268,12 @@ async function localInvokeCommand(target, options) {
 			stateProvider.dispose();
 		}
 		const overrides = readEnvOverridesFile(options.envVars);
-		const envResult = resolveEnvVars(lambda.logicalId, templateEnv, overrides);
+		const lambdaCdkPath = readCdkPathOrUndefined(lambda.resource);
+		const envResult = resolveEnvVars(lambda.logicalId, lambdaCdkPath, templateEnv, overrides);
 		for (const key of envResult.unresolved) {
 			if (stateAudit && stateAudit.unresolved.some((u) => u.key === key)) continue;
-			logger.warn(`Environment variable ${key} contains a CloudFormation intrinsic and was dropped. Override it with --env-vars (e.g. {"${lambda.logicalId}":{"${key}":"<literal>"}}), or pass --from-state (cdkd-deployed) / --from-cfn-stack (cdk-deployed) to recover deployed values.`);
+			const overrideKeyExample = lambdaCdkPath?.replace(/\/Resource$/, "") ?? lambda.logicalId;
+			logger.warn(`Environment variable ${key} contains a CloudFormation intrinsic and was dropped. Override it with --env-vars (e.g. {"${overrideKeyExample}":{"${key}":"<literal>"}}), or pass --from-state (cdkd-deployed) / --from-cfn-stack (cdk-deployed) to recover deployed values.`);
 		}
 		let resolvedAssumeRoleArn;
 		if (typeof options.assumeRole === "string") resolvedAssumeRoleArn = options.assumeRole;
@@ -60927,7 +61017,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.168.0");
+	program.name("cdkd").description("CDK Direct - Deploy AWS CDK apps directly via SDK/Cloud Control API").version("0.169.0");
 	program.addCommand(createBootstrapCommand());
 	program.addCommand(createSynthCommand());
 	program.addCommand(createListCommand());