@go-to-k/cdkd 0.167.3 → 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

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { _ as withSkipPrefix, a as runDockerStreaming, c as getLogger, d as getLiveRenderer, f as PATTERN_B_NAME_PROPERTIES, g as generateResourceNameWithFallback, h as generateResourceName, i as runDockerForeground, n as formatDockerLoginError, p as PATTERN_B_RESOURCE_TYPES, r as getDockerCmd, u as runStackBuffered, v as withStackName } from "./docker-cmd-iDMcWcre.js";
-import { A as S3StateBackend, B as resolveCaptureObservedState, C as assertRegionMatch, D as DagBuilder, E as DiffCalculator, F as buildDockerImage, G as CFN_TEMPLATE_BODY_LIMIT, H as resolveStateBucketWithDefault, I as Synthesizer, J as findLargeInlineResources, K as CFN_TEMPLATE_URL_LIMIT, L as getDefaultStateBucketName, M as AssetPublisher, N as stringifyValue, O as TemplateParser, P as WorkGraph, Q as resolveBucketRegion, R as getLegacyStateBucketName, S as CloudControlProvider, T as applyRoleArnIfSet, U as resolveStateBucketWithDefaultAndSource, V as resolveSkipPrefix, W as warnDeprecatedNoPrefixCliFlag, X as AssemblyReader, Y as uploadCfnTemplate, _ as matchesCdkPath, a as withRetry, at as LocalStartServiceError, b as ProviderRegistry, bt as normalizeAwsError, c as bold, ct as NestedStackChildDirectDestroyError, d as green, dt as ResourceTimeoutError, et as CdkdError, f as red, ft as ResourceUpdateNotSupportedError, g as CDK_PATH_TAG, h as collectInlinePolicyNamesManagedBySiblings, ht as StackTerminationProtectionError, i as withResourceDeadline, it as LocalMigrateError, j as shouldRetainResource, k as LockManager, l as cyan, lt as PartialFailureError, m as IAMRoleProvider, mt as StackHasActiveImportsError, n as DEFAULT_RESOURCE_WARN_AFTER_MS, o as IMPLICIT_DELETE_DEPENDENCIES, p as yellow, pt as RouteDiscoveryError, q as MIGRATE_TMP_PREFIX, r as DeployEngine, rt as LocalInvokeBuildError, s as formatResourceLine, st as MissingCdkCliError, t as DEFAULT_RESOURCE_TIMEOUT_MS, u as gray, ut as ProvisioningError, v as normalizeAwsTagsToCfn, w as IntrinsicFunctionResolver, x as findActionableSilentDrops, xt as withErrorHandling, y as resolveExplicitPhysicalId, z as resolveApp } from "./deploy-engine-BQkk03hJ.js";
+import { A as S3StateBackend, B as resolveCaptureObservedState, C as assertRegionMatch, D as DagBuilder, E as DiffCalculator, F as buildDockerImage, G as CFN_TEMPLATE_BODY_LIMIT, H as resolveStateBucketWithDefault, I as Synthesizer, J as findLargeInlineResources, K as CFN_TEMPLATE_URL_LIMIT, L as getDefaultStateBucketName, M as AssetPublisher, N as stringifyValue, O as TemplateParser, P as WorkGraph, Q as resolveBucketRegion, R as getLegacyStateBucketName, S as CloudControlProvider, T as applyRoleArnIfSet, U as resolveStateBucketWithDefaultAndSource, V as resolveSkipPrefix, W as warnDeprecatedNoPrefixCliFlag, X as AssemblyReader, Y as uploadCfnTemplate, _ as matchesCdkPath, a as withRetry, at as LocalStartServiceError, b as ProviderRegistry, bt as normalizeAwsError, c as bold, ct as NestedStackChildDirectDestroyError, d as green, dt as ResourceTimeoutError, et as CdkdError, f as red, ft as ResourceUpdateNotSupportedError, g as CDK_PATH_TAG, h as collectInlinePolicyNamesManagedBySiblings, ht as StackTerminationProtectionError, i as withResourceDeadline, it as LocalMigrateError, j as shouldRetainResource, k as LockManager, l as cyan, lt as PartialFailureError, m as IAMRoleProvider, mt as StackHasActiveImportsError, n as DEFAULT_RESOURCE_WARN_AFTER_MS, o as IMPLICIT_DELETE_DEPENDENCIES, p as yellow, pt as RouteDiscoveryError, q as MIGRATE_TMP_PREFIX, r as DeployEngine, rt as LocalInvokeBuildError, s as formatResourceLine, st as MissingCdkCliError, t as DEFAULT_RESOURCE_TIMEOUT_MS, u as gray, ut as ProvisioningError, v as normalizeAwsTagsToCfn, w as IntrinsicFunctionResolver, x as findActionableSilentDrops, xt as withErrorHandling, y as resolveExplicitPhysicalId, z as resolveApp } from "./deploy-engine-Cux0aKqI.js";
 import { a as setAwsClients, i as resetAwsClients, r as getAwsClients, t as AwsClients } from "./aws-clients-B15NAPbL.js";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { createHash, createHmac, createPublicKey, createVerify, randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
@@ -1369,16 +1369,28 @@ async function findDownstreamConsumers(input) {
 		const region = ref.region ?? input.baseRegion;
 		if (ref.stackName === input.producerStack && region === input.producerRegion) return null;
 		try {
-			const imports = (await input.stateBackend.getState(ref.stackName, region))?.state.imports;
-			if (!imports || imports.length === 0) return null;
-			const matches = imports.filter((entry) => entry.sourceStack === input.producerStack && entry.sourceRegion === input.producerRegion);
-			if (matches.length === 0) return null;
-			return matches.map((entry) => ({
-				consumerStack: ref.stackName,
-				consumerRegion: region,
-				exportName: entry.exportName,
-				intrinsic: "ImportValue"
-			}));
+			const got = await input.stateBackend.getState(ref.stackName, region);
+			if (!got) return null;
+			const out = [];
+			const imports = got.state.imports;
+			if (imports && imports.length > 0) {
+				for (const entry of imports) if (entry.sourceStack === input.producerStack && entry.sourceRegion === input.producerRegion) out.push({
+					consumerStack: ref.stackName,
+					consumerRegion: region,
+					exportName: entry.exportName,
+					intrinsic: "ImportValue"
+				});
+			}
+			const outputReads = got.state.outputReads;
+			if (outputReads && outputReads.length > 0) {
+				for (const entry of outputReads) if (entry.sourceStack === input.producerStack && entry.sourceRegion === input.producerRegion) out.push({
+					consumerStack: ref.stackName,
+					consumerRegion: region,
+					exportName: entry.outputName,
+					intrinsic: "GetStackOutput"
+				});
+			}
+			return out.length > 0 ? out : null;
 		} catch (err) {
 			logger.debug(`findDownstreamConsumers: skip ${ref.stackName} (${region}); ${err instanceof Error ? err.message : String(err)}`);
 			return null;
@@ -33933,7 +33945,7 @@ async function deployCommand(stacks, options) {
 						validation: validateRecreateTargets({
 							template: stackInfo.template,
 							state: stateForRecreateCheck?.state ?? {
-								version: 7,
+								version: 8,
 								stackName: stackInfo.stackName,
 								region: stackRegion,
 								resources: {},
@@ -34940,7 +34952,7 @@ async function loadStateOrEmpty(stackName, region, stateBackend) {
 		region,
 		resources: {},
 		outputs: {},
-		version: 7,
+		version: 8,
 		lastModified: Date.now()
 	};
 }
@@ -36463,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
@@ -41656,7 +41683,7 @@ function buildStackState(stackName, region, rows, templateParser, template, exis
 		};
 	}
 	return {
-		version: 7,
+		version: 8,
 		stackName,
 		region,
 		resources,
@@ -43656,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,
@@ -55096,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.
@@ -55121,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}`);
@@ -55497,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
@@ -55644,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,
@@ -59168,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;
@@ -60915,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.167.3");
+	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());