@go-to-k/cdkd 0.149.0 → 0.150.0

package/dist/cli.js

@@ -36057,6 +36057,7 @@ async function exportCommand(stackArg, options) {
 		let synthedRegion;
 		let templateFormat = "json";
 		let allSynthStacks = [];
+		let rootNestedTemplatePaths = {};
 		if (options.template) {
 			if (!stackArg) throw new Error("--template requires a stack name as a positional argument to identify the cdkd state record.");
 			const parsed = parseTemplateFile(options.template);
@@ -36085,6 +36086,7 @@ async function exportCommand(stackArg, options) {
 			template = stackInfo.template;
 			resolvedStackName = stackInfo.stackName;
 			synthedRegion = stackInfo.region;
+			rootNestedTemplatePaths = stackInfo.nestedTemplates ?? {};
 			allSynthStacks = result.stacks.map((s) => ({
 				stackName: s.stackName,
 				template: s.template
@@ -36109,16 +36111,55 @@ async function exportCommand(stackArg, options) {
 				throw new Error(`${blocked.length} resource(s) block migration. Either destroy them first (cdkd destroy / cdkd state destroy cherry-picked), or remove them from the CDK app and re-synthesize.`);
 			}
 			if (nestedStackRows.length > 0) {
-				const leafFirst = flattenCdkdStateTreeLeafFirst(await buildCdkdStateStackTree(resolvedStackName, targetRegion, stateBackend, state));
-				logger.info(`Stack '${resolvedStackName}' contains ${nestedStackRows.length} top-level nested stack row(s); cdkd state tree spans ${leafFirst.length} stack(s) total (leaf-first migration order):`);
-				for (const node of leafFirst) logger.info(`  - cdkd/${node.stackName}/${node.region}/state.json`);
-				const deferralMessage = `cdkd export does not yet submit nested-stack trees to CloudFormation (${nestedStackRows.length} top-level nested-stack row(s) detected; ${leafFirst.length} cdkd state record(s) in the tree). Recursive --include-nested-stacks IMPORT changeset submission is tracked under issue #464 PR B2. Workarounds until PR B2 ships:\n  - Keep the stack on cdkd (recommended — nested-stack deploy / destroy / drift already work via the SDK provider path).\n  - OR destroy the nested children first via 'cdkd state destroy <child>' (leaf-first), then re-run 'cdkd export <parent>' against the flattened parent.`;
-				if (options.dryRun) {
-					logger.warn(deferralMessage);
-					logger.info("--dry-run: no CloudFormation changeset will be created.");
-					return;
+				const nestedStackTree = await buildCdkdStateStackTree(resolvedStackName, targetRegion, stateBackend, state);
+				reportDriftBaselineGaps(state, logger);
+				if (allSynthStacks.length > 0) {
+					const crossRefs = scanCrossStackReferences(allSynthStacks, resolvedStackName);
+					if (crossRefs.length > 0) {
+						const lines = crossRefs.map((r) => `  ${r.consumerStackName} → ${resolvedStackName}.${r.outputName} at ${r.location}`);
+						if (options.strictCrossStack) throw new Error(`Refusing to export: ${crossRefs.length} cross-stack reference(s) to ${resolvedStackName} found in sibling stacks. After migration, those references will break (cdkd's Fn::GetStackOutput reads cdkd state; the migrated stack's outputs live in CFn). Migrate consumers first, or remove the references, or drop --strict-cross-stack to proceed with a warning:\n` + lines.join("\n"));
+						logger.warn(`${crossRefs.length} cross-stack reference(s) to '${resolvedStackName}' from sibling stacks. These will break the next time those stacks deploy via cdkd (cdkd's Fn::GetStackOutput resolver reads cdkd state; the migrated stack's outputs are now in CFn). Plan multi-stack migrations from the leaves up.`);
+						for (const line of lines) logger.warn(line);
+					}
 				}
-				throw new Error(deferralMessage);
+				const userParametersNested = parseParameterOverrides(options.parameter);
+				const { parameters: rootParametersForNested, missing: missingNested } = resolveTemplateParameters(template, userParametersNested);
+				if (missingNested.length > 0) throw new Error(`Template requires parameter(s) without defaults: ${missingNested.join(", ")}. Pass each one as --parameter Key=Value (or set a Default in the CDK code).`);
+				const childOverrides = parseCfnChildStackNameOverrides(options.cfnChildStackName);
+				if ((await runPerStackImportLoop({
+					rootStackName: resolvedStackName,
+					rootRegion: targetRegion,
+					rootStackInfoNestedTemplates: rootNestedTemplatePaths,
+					rootTemplateFormat: templateFormat,
+					tree: nestedStackTree,
+					rootTemplate: template,
+					cfnStackNameOverrides: {
+						root: options.cfnStackName,
+						childMap: childOverrides
+					},
+					rootParameters: rootParametersForNested,
+					deps: {
+						cfnClient: awsClients.cloudFormation,
+						stateBackend,
+						lockManager,
+						uploadOpts: {
+							stateBucket,
+							...options.profile && { s3ClientOpts: { profile: options.profile } }
+						},
+						lockOwner: owner
+					},
+					options: {
+						dryRun: options.dryRun,
+						yes: options.yes,
+						includeNonImportable: options.includeNonImportable,
+						recreateImportUnsupported: options.recreateImportUnsupported
+					}
+				})).outcome === "success") printNextSteps({
+					cfnStackName: options.cfnStackName ?? cdkd2cfnStackName(resolvedStackName),
+					cdkStackName: resolvedStackName,
+					contextOverrides: options.context ?? []
+				});
+				return;
 			}
 			if (phase1Imports.length === 0 && phase2Creates.length === 0 && recreateBeforePhase2.length === 0) {
 				logger.warn("No resources to migrate — cdkd state is empty.");
@@ -36378,6 +36419,152 @@ function flattenCdkdStateTreeLeafFirst(tree) {
 	}
 }
 /**
+* Map a cdkd stack name to a CloudFormation-compatible stack name.
+*
+* Required because the cdkd v6 state-key form `<parent>~<childLogicalId>`
+* contains `~`, which CFn rejects in stack names (CFn accepts
+* `[a-zA-Z][-a-zA-Z0-9]*` only). The substitution chooses `-` to mirror
+* CFn's own auto-naming convention for nested stacks
+* (`<Parent>-<ChildLogicalId>-<RandomSuffix>` minus the suffix).
+*
+* Top-level cdkd stack names that already conform to CFn's character set
+* are passed through unchanged — `cdkd2cfnStackName('MyApp') === 'MyApp'`.
+*
+* Issue #464 design §9 Q8.
+*/
+function cdkd2cfnStackName(cdkdStackName) {
+	return cdkdStackName.replace(/~/g, "-");
+}
+/**
+* Parse the repeatable `--cfn-child-stack-name <cdkdName>=<cfnName>` CLI
+* flag into a lookup map. Each entry maps a cdkd stack name (v6 form,
+* e.g. `MyApp~Database`) to the desired CFn stack name.
+*
+* Throws on a malformed entry (no `=`, empty cdkdName, empty cfnName, or
+* a CFn name that violates the CFn naming constraint) so the user sees
+* the problem before any AWS-side mutation. Duplicate cdkdName keys are
+* rejected to avoid silent last-wins behavior.
+*
+* Exported for unit testing.
+*/
+function parseCfnChildStackNameOverrides(values) {
+	const out = /* @__PURE__ */ new Map();
+	if (!values || values.length === 0) return out;
+	for (const raw of values) {
+		const eq = raw.indexOf("=");
+		if (eq < 0) throw new Error(`--cfn-child-stack-name '${raw}' is not in <cdkdName>=<cfnName> form. Example: --cfn-child-stack-name 'MyApp~Database=my-app-database'.`);
+		const cdkdName = raw.slice(0, eq).trim();
+		const cfnName = raw.slice(eq + 1).trim();
+		if (!cdkdName) throw new Error(`--cfn-child-stack-name '${raw}' has an empty cdkd stack name.`);
+		if (!cfnName) throw new Error(`--cfn-child-stack-name '${raw}' has an empty CFn stack name.`);
+		if (!/^[a-zA-Z][-a-zA-Z0-9]*$/.test(cfnName)) throw new Error(`--cfn-child-stack-name '${raw}': CFn stack name '${cfnName}' must match [a-zA-Z][-a-zA-Z0-9]* (no '~', no '/', no '_', no '.').`);
+		if (out.has(cdkdName)) throw new Error(`--cfn-child-stack-name: duplicate override for cdkd stack '${cdkdName}'. Pass it once with the final CFn name.`);
+		out.set(cdkdName, cfnName);
+	}
+	return out;
+}
+/**
+* Read + parse a nested-stack child template from the synth cloud assembly.
+* The path is the absolute filesystem path AssemblyReader populated from
+* the parent template's `Metadata['aws:asset:path']` on each
+* `AWS::CloudFormation::Stack` resource.
+*
+* Format-aware: CDK 2.x always synthesizes JSON for nested templates, but
+* the codec recognizes both JSON and YAML so the helper is forward-compatible
+* with any synth output (and matches `parseTemplateFile` for `--template`).
+*
+* Sibling of `readNestedChildTemplate` in `import.ts`. Kept separate so
+* `export.ts` does not depend on `import.ts` internals and the return
+* shape (`Record<string, unknown>` + `TemplateFormat`) matches what
+* `executeImportChangeSet` / `executeUpdateChangeSet` consume. Consolidate
+* into a shared `nested-template-fs.ts` module if a third caller appears.
+*/
+function readNestedChildTemplateFile(templatePath, childLogicalId) {
+	let raw;
+	try {
+		raw = readFileSync(templatePath, "utf-8");
+	} catch (err) {
+		throw new Error(`cdkd export: failed to read nested-stack template for '${childLogicalId}' at '${templatePath}': ${err instanceof Error ? err.message : String(err)}`);
+	}
+	try {
+		return parseCfnTemplateWithFormat(raw);
+	} catch (err) {
+		throw new Error(`cdkd export: failed to parse nested-stack template for '${childLogicalId}' at '${templatePath}': ${err instanceof Error ? err.message : String(err)}`);
+	}
+}
+/**
+* Index every `AWS::CloudFormation::Stack` row in `template` by its
+* `Metadata['aws:asset:path']`, returning `{logicalId: <absolute-path>}`.
+* Mirrors `AssemblyReader.extractStackInfo`'s nested-template indexing
+* (line ~277 of `assembly-reader.ts`) so the same logic applies to
+* arbitrary depth — grandchild templates are siblings of their parent
+* child template in the same cdk.out subdirectory.
+*
+* Refuses absolute `aws:asset:path` values (CDK emits relative paths
+* only; an absolute path indicates hand-modified synth output or a
+* non-CDK toolchain — `path.join(dir, '/abs/foo')` would silently bypass
+* the `dir` argument).
+*
+* Sibling of `indexGrandchildTemplatePaths` in `import.ts`. Same rationale
+* for separate definitions as `readNestedChildTemplateFile` above.
+*/
+function indexNestedTemplatePaths(template, templateDir) {
+	const result = {};
+	const resources = template["Resources"];
+	if (!resources || typeof resources !== "object" || Array.isArray(resources)) return result;
+	for (const [logicalId, resource] of Object.entries(resources)) {
+		if (!resource || typeof resource !== "object" || Array.isArray(resource)) continue;
+		const r = resource;
+		if (r.Type !== "AWS::CloudFormation::Stack") continue;
+		const assetPath = r.Metadata?.["aws:asset:path"];
+		if (typeof assetPath !== "string" || assetPath.length === 0) continue;
+		if (path.isAbsolute(assetPath)) throw new Error(`cdkd export: nested-stack '${logicalId}' has Metadata['aws:asset:path']='${assetPath}' which is absolute. CDK emits relative asset paths for nested templates.`);
+		result[logicalId] = path.join(templateDir, assetPath);
+	}
+	return result;
+}
+/**
+* Walk the cdkd state tree alongside the synth output's nested-template
+* file paths, materializing each node's parsed template + format. The
+* walker indexes children's paths from the parent template's
+* `Metadata['aws:asset:path']` (same mechanism `AssemblyReader` uses for
+* the root parent), so grandchildren and deeper levels are loaded
+* recursively without any caller-side index plumbing.
+*
+* Throws if any tree node has a child whose template path is missing from
+* the parent template's nested-template index — that mismatch indicates
+* a torn synth output (the child state file exists but the parent CDK
+* code no longer references it) and the run cannot proceed safely.
+*
+* Returns a map keyed by cdkd stack name (matching tree node names) so
+* {@link runPerStackImportLoop} can look each node's template up by name
+* without re-traversing the tree.
+*
+* Exported so the recursion shape is unit-testable independently of the
+* orchestrator.
+*/
+function buildPerStackImportNodes(rootStackName, rootTemplate, rootNestedTemplatePaths, rootTemplateFormat, tree) {
+	if (tree.stackName !== rootStackName) throw new Error(`buildPerStackImportNodes: tree root '${tree.stackName}' does not match expected root stack name '${rootStackName}'.`);
+	const out = /* @__PURE__ */ new Map();
+	walk(tree, rootTemplate, rootNestedTemplatePaths, rootTemplateFormat);
+	return out;
+	function walk(node, nodeTemplate, nodeNestedTemplatePaths, nodeFormat) {
+		out.set(node.stackName, {
+			cdkdStackName: node.stackName,
+			region: node.region,
+			state: node.state,
+			template: nodeTemplate,
+			templateFormat: nodeFormat
+		});
+		for (const [childLogicalId, childNode] of node.nestedChildren) {
+			const childTemplatePath = nodeNestedTemplatePaths[childLogicalId];
+			if (!childTemplatePath) throw new Error(`cdkd export: nested-stack child '${childLogicalId}' under parent '${node.stackName}' has cdkd state but no Metadata['aws:asset:path'] in the parent template's '${childLogicalId}' row. The synth output and the cdkd state tree are out of sync — re-deploy the parent stack to refresh, or remove the cdkd state for the orphaned child via 'cdkd state orphan ${childNode.stackName}'.`);
+			const { template: childTemplate, format: childFormat } = readNestedChildTemplateFile(childTemplatePath, childLogicalId);
+			walk(childNode, childTemplate, indexNestedTemplatePaths(childTemplate, path.dirname(childTemplatePath)), childFormat);
+		}
+	}
+}
+/**
 * Build the import plan from cdkd state + the synthesized template.
 *
 * Classifies every template resource into one of:
@@ -36998,15 +37185,33 @@ async function runTemplateUploadCleanup(cleanup, bucket) {
 	}
 }
 async function executeImportChangeSet(cfnClient, stackName, template, plan, parameters, templateFormat = "json", uploadOpts) {
-	const logger = getLogger();
-	const changeSetName = `cdkd-migrate-${Date.now()}`;
-	const templateBody = stringifyCfnTemplate(template, templateFormat);
-	const resourcesToImport = plan.map((entry) => ({
+	await submitImportChangeSet(cfnClient, stackName, template, plan.map((entry) => ({
 		ResourceType: entry.resourceType,
 		LogicalResourceId: entry.logicalId,
 		ResourceIdentifier: entry.resourceIdentifier
-	}));
-	logger.info(`Creating IMPORT changeset '${changeSetName}' for stack '${stackName}' (${plan.length} resource(s), ${templateBody.length} bytes)...`);
+	})), parameters, templateFormat, uploadOpts);
+}
+/**
+* Submit one CloudFormation IMPORT changeset for `stackName`, awaiting
+* both `CreateChangeSet` and `ExecuteChangeSet` to completion. Accepts a
+* pre-built `resourcesToImport` array (caller-controlled) so non-leaf
+* parents in the per-stack IMPORT loop (issue #464 PR B2) can pass a
+* mixed list of leaf resources AND `AWS::CloudFormation::Stack` adoption
+* entries (with `ResourceIdentifier: { StackId: <child-CFn-arn> }`).
+*
+* Extracted from {@link executeImportChangeSet} so the leaf-only callers
+* (top-level export, single-stack flow) and the non-leaf-parent caller
+* (nested per-stack loop) share the exact same submit + wait + cleanup
+* code path — no risk of divergence on retry shape, changeset cleanup
+* on failure, or transient-upload reaping.
+*
+* Exported for unit testing.
+*/
+async function submitImportChangeSet(cfnClient, stackName, template, resourcesToImport, parameters, templateFormat = "json", uploadOpts) {
+	const logger = getLogger();
+	const changeSetName = `cdkd-migrate-${Date.now()}`;
+	const templateBody = stringifyCfnTemplate(template, templateFormat);
+	logger.info(`Creating IMPORT changeset '${changeSetName}' for stack '${stackName}' (${resourcesToImport.length} resource(s), ${templateBody.length} bytes)...`);
 	const source = await selectChangeSetTemplateSource(template, templateBody, uploadOpts, stackName, "Filtered phase-1 IMPORT", templateFormat);
 	try {
 		try {
@@ -37105,6 +37310,462 @@ async function collectImportFailureSummary(cfnClient, stackName) {
 	return failures.map((f) => `  - ${f.logicalId} (${f.type}): ${f.reason}`).join("\n");
 }
 /**
+* Flip a CFn stack's status from `IMPORT_COMPLETE` to `UPDATE_COMPLETE`
+* via a no-op `UpdateStack` with a stack-level tag-only change. Used
+* after each non-root stack's Phase 1A IMPORT (and after each non-leaf
+* parent's Phase 1B IMPORT) so the stack can be referenced as a nested
+* member by its own parent's later Phase 1B adoption.
+*
+* Why this is needed: AWS's "Nest an existing stack" IMPORT changeset
+* validation rejects child stacks in `IMPORT_COMPLETE` status with
+* `Stack <arn> is not in an importable status, current stack status is
+* IMPORT_COMPLETE`. The accepted statuses for nesting are
+* `CREATE_COMPLETE` and `UPDATE_COMPLETE`. A no-op tag-only `UpdateStack`
+* with `UsePreviousTemplate: true` flips the status without mutating any
+* resources: the existing template is re-applied verbatim, only the
+* stack-level Tags collection changes (the timestamp-bearing
+* `cdkd:nested-export-flip` tag is the only delta). This is the canonical
+* AWS workaround for the IMPORT_COMPLETE → UPDATE_COMPLETE transition.
+*
+* Idempotency: each invocation uses a fresh ISO 8601 timestamp value so
+* AWS never returns "No updates are to be performed" (which would leave
+* the stack stuck in `IMPORT_COMPLETE`). The tag accumulates across
+* retries — harmless and easy to reap manually under the `cdkd:` prefix.
+*
+* Exported for unit testing.
+*/
+async function flipStackToUpdateComplete(cfnClient, cfnStackName) {
+	await cfnClient.send(new UpdateStackCommand({
+		StackName: cfnStackName,
+		UsePreviousTemplate: true,
+		Tags: [{
+			Key: "cdkd:nested-export-flip",
+			Value: (/* @__PURE__ */ new Date()).toISOString()
+		}],
+		Capabilities: [
+			"CAPABILITY_IAM",
+			"CAPABILITY_NAMED_IAM",
+			"CAPABILITY_AUTO_EXPAND"
+		]
+	}));
+	await waitUntilStackUpdateComplete({
+		client: cfnClient,
+		maxWaitTime: 1800
+	}, { StackName: cfnStackName });
+}
+/**
+* Fetch a CFn stack's CURRENT template body via the CFn `GetTemplate`
+* `Processed` stage. Used by the non-leaf-parent branch of
+* {@link runPerStackImportLoop} to satisfy the AWS-docs "Nest an existing
+* stack" template-match requirement: the parent's
+* `AWS::CloudFormation::Stack.Properties.TemplateURL` must point at the
+* child stack's actual current template for the IMPORT changeset to
+* validate. Reading via `GetTemplate` (vs. the local cdk.out file) is
+* the only way to guarantee the AWS-side stored template byte-shape —
+* AWS may have normalized whitespace, parameter defaults, or intrinsic
+* shapes during the just-completed leaf IMPORT.
+*
+* `Processed` stage returns the template AWS has on file post-IMPORT
+* (with any macro / serverless-transform expansion already applied),
+* which is exactly what the parent's nested-stack row must reference.
+*
+* Exported for unit testing.
+*/
+async function fetchCfnStackTemplate(cfnClient, cfnStackName) {
+	const resp = await cfnClient.send(new GetTemplateCommand({
+		StackName: cfnStackName,
+		TemplateStage: "Processed"
+	}));
+	if (!resp.TemplateBody) throw new Error(`CFn GetTemplate returned no body for stack '${cfnStackName}'. The just-IMPORTed child stack may be in an unexpected state; check the CloudFormation console.`);
+	return resp.TemplateBody;
+}
+/**
+* Extract a child-IMPORT Parameter map from the parent template's
+* `Resources[<childLogicalId>].Properties.Parameters` block.
+*
+* CDK nested stacks pass parent → child Parameter values via the parent's
+* `AWS::CloudFormation::Stack.Properties.Parameters` map. For the LEAF
+* child IMPORT (which submits the child as a fresh standalone CFn stack),
+* cdkd must forward those values — otherwise the child template's
+* `Parameters` block goes unresolved and CFn rejects the changeset.
+*
+* Only literal-string Parameter values are forwarded today. Intrinsic
+* values (`{Ref: ...}` / `{Fn::GetAtt: ...}` referencing the parent's
+* own resources) are skipped with a `logger.warn`; if the child Parameter
+* has no `Default`, CFn will reject the IMPORT with a clear error. The
+* intrinsic-resolution path is a deferred follow-up (tracked under #464
+* post-PR-B2 backlog) because resolving parent-side intrinsics at
+* leaf-IMPORT time requires the deploy engine's full
+* `IntrinsicFunctionResolver` against the parent's own (yet-to-be-IMPORTed)
+* state — not in PR B2's scope.
+*
+* Exported for unit testing.
+*/
+function extractChildImportParameters(parentTemplate, childLogicalId) {
+	const resources = parentTemplate["Resources"];
+	if (!resources || typeof resources !== "object" || Array.isArray(resources)) return {
+		params: [],
+		intrinsicSkipped: []
+	};
+	const row = resources[childLogicalId];
+	if (!row || typeof row !== "object" || Array.isArray(row)) return {
+		params: [],
+		intrinsicSkipped: []
+	};
+	const props = row.Properties;
+	if (!props || typeof props !== "object" || Array.isArray(props)) return {
+		params: [],
+		intrinsicSkipped: []
+	};
+	const rawParams = props.Parameters;
+	if (!rawParams || typeof rawParams !== "object" || Array.isArray(rawParams)) return {
+		params: [],
+		intrinsicSkipped: []
+	};
+	const out = [];
+	const intrinsicSkipped = [];
+	for (const [k, v] of Object.entries(rawParams)) if (typeof v === "string") out.push({
+		ParameterKey: k,
+		ParameterValue: v
+	});
+	else if (typeof v === "number" || typeof v === "boolean") out.push({
+		ParameterKey: k,
+		ParameterValue: String(v)
+	});
+	else intrinsicSkipped.push(k);
+	return {
+		params: out,
+		intrinsicSkipped
+	};
+}
+/**
+* Per-stack IMPORT loop driving `cdkd export` for nested-stack trees
+* (issue #464 PR B2). Submits one IMPORT changeset per cdkd-managed stack
+* in leaf-first order. For non-leaf parents, each `AWS::CloudFormation::Stack`
+* row in the parent's template is adopted as a nested reference via the
+* AWS-docs "Nest an existing stack" pattern: `DeletionPolicy: Retain` is
+* injected, the row's `TemplateURL` is rewritten to point at the just-IMPORTed
+* child stack's current template (fetched via `GetTemplate`), and the
+* row is added to `ResourcesToImport[]` with
+* `{ ResourceIdentifier: { StackId: <child-CFn-arn> } }`.
+*
+* The original "one atomic `--include-nested-stacks` IMPORT changeset"
+* design (#464 design doc §4.3 original) was empirically rejected by AWS:
+* `IncludeNestedStacks is not supported for changeSet type: IMPORT`. See
+* §4.0 of the design doc for the spike findings + per-stack loop rationale.
+*
+* Algorithm:
+*   1. Pre-flight (before any AWS mutation):
+*      - Build per-stack import plans from the tree.
+*      - Reject if any stack has blocked resources OR phase-2 non-importable
+*        resources without `--include-non-importable`.
+*      - Verify no CFn stack already exists under the resolved CFn name
+*        for any tree node.
+*      - Print the per-stack plan summary.
+*      - In `--dry-run`: return without acquiring locks or submitting
+*        changesets.
+*      - Prompt the user once for the whole tree migration (unless `--yes`).
+*      - Acquire per-non-root-child locks (root's lock is already held by
+*        `exportCommand`'s outer scope).
+*   2. Main loop, leaf-first across the tree. Per stack:
+*      - Build the filtered phase-1 template + `ResourcesToImport[]` array.
+*      - For non-leaf parents: per nested-stack row, fetch the child's
+*        current template via `GetTemplate`, upload to S3 (cleanup
+*        accumulated for the outer `finally`), inject Retain + rewrite
+*        TemplateURL, append to `ResourcesToImport[]` with
+*        `{ StackId: <child-arn> }`.
+*      - Submit IMPORT changeset via {@link submitImportChangeSet}.
+*      - Capture the resulting CFn stack ARN via `DescribeStacks` for
+*        the next parent iteration's reference.
+*      - Per-stack phase-2: pre-delete IMPORT-unsupported resources, then
+*        UPDATE changeset for Custom Resources (same shape as the
+*        flat-stack code path, just scoped to this stack).
+*   3. After all stacks IMPORTed: delete cdkd state leaf-first.
+*   4. Always (success AND failure paths):
+*      - Release per-non-root-child locks in reverse order.
+*      - Drain transient template uploads.
+*
+* Failure semantics: each per-stack IMPORT is independent. If leaf A
+* succeeds but parent B fails, A is a standalone CFn stack with A's cdkd
+* state DELETED, while B's cdkd state is PRESERVED. The error message
+* names which stacks moved + which remain. Re-running `cdkd export
+* <parent>` after the failure cause is fixed adopts A as a nested
+* reference (since A is now an existing CFn stack) — the per-stack loop
+* is idempotent in that direction.
+*
+* Exported for unit testing.
+*/
+async function runPerStackImportLoop(args) {
+	const logger = getLogger();
+	const { rootStackName, rootRegion, rootStackInfoNestedTemplates, rootTemplateFormat, tree, rootTemplate, cfnStackNameOverrides, rootParameters, deps, options } = args;
+	const cfnStackNameOf = (cdkdName) => {
+		if (cdkdName === rootStackName) return cfnStackNameOverrides.root ?? cdkd2cfnStackName(cdkdName);
+		return cfnStackNameOverrides.childMap.get(cdkdName) ?? cdkd2cfnStackName(cdkdName);
+	};
+	const nodesByCdkdName = buildPerStackImportNodes(rootStackName, rootTemplate, rootStackInfoNestedTemplates, rootTemplateFormat, tree);
+	const leafFirst = flattenCdkdStateTreeLeafFirst(tree);
+	for (const n of leafFirst) if (!nodesByCdkdName.has(n.stackName)) throw new Error(`runPerStackImportLoop: missing per-stack template for '${n.stackName}' — tree node has cdkd state but no synth template was loaded. This is a cdkd bug.`);
+	const perStackPlans = [];
+	for (const node of leafFirst) {
+		const meta = nodesByCdkdName.get(node.stackName);
+		const plan = await buildImportPlan(meta.state, meta.template, deps.cfnClient, meta.cdkdStackName, { recreateImportUnsupported: options.recreateImportUnsupported });
+		if (plan.blocked.length > 0) {
+			const lines = plan.blocked.map((b) => `  - ${b.logicalId} (${b.resourceType}): ${b.reason}`);
+			throw new Error(`Stack '${meta.cdkdStackName}' has ${plan.blocked.length} resource(s) that block migration:\n${lines.join("\n")}`);
+		}
+		perStackPlans.push({
+			cdkdName: meta.cdkdStackName,
+			cfnName: cfnStackNameOf(meta.cdkdStackName),
+			region: meta.region,
+			template: meta.template,
+			templateFormat: meta.templateFormat,
+			state: meta.state,
+			phase1Imports: plan.phase1Imports,
+			phase2Creates: plan.phase2Creates,
+			recreateBeforePhase2: plan.recreateBeforePhase2,
+			nestedStackRows: plan.nestedStackRows
+		});
+	}
+	const totalPhase2Creates = perStackPlans.reduce((acc, p) => acc + p.phase2Creates.length, 0);
+	const totalRecreate = perStackPlans.reduce((acc, p) => acc + p.recreateBeforePhase2.length, 0);
+	logger.info("");
+	logger.info(`Migrating cdkd nested-stack tree rooted at '${rootStackName}' → CloudFormation (${perStackPlans.length} stack(s), leaf-first):`);
+	for (const plan of perStackPlans) logger.info(`  [${plan.cdkdName}] → CFn stack '${plan.cfnName}': ${plan.phase1Imports.length} leaf import(s)` + (plan.nestedStackRows.length > 0 ? `, ${plan.nestedStackRows.length} nested-child adoption(s)` : "") + (plan.phase2Creates.length > 0 ? `, ${plan.phase2Creates.length} phase-2 CREATE(s)` : "") + (plan.recreateBeforePhase2.length > 0 ? `, ${plan.recreateBeforePhase2.length} pre-delete + re-CREATE` : ""));
+	logger.info("");
+	if (totalPhase2Creates > 0 && !options.includeNonImportable) {
+		if (options.dryRun) {
+			logger.warn(`${totalPhase2Creates} non-importable resource(s) (Custom::*) across the tree. A real run would require --include-non-importable for phase-2 CFn CREATE (re-invokes each Custom Resource's backing Lambda onCreate handler — ensure idempotent).`);
+			logger.info("--dry-run: no CloudFormation changesets will be created.");
+			return {
+				outcome: "dry-run",
+				importedStacks: []
+			};
+		}
+		throw new Error(`${totalPhase2Creates} non-importable resource(s) (Custom::*) across the cdkd nested-stack tree. Pass --include-non-importable to run a per-stack 2-phase migration (phase 1 imports the importable resources for each stack; phase 2 CFn-CREATEs the non-importable ones per stack, which re-invokes each Custom Resource's onCreate handler — make sure those are idempotent). Or destroy the Custom Resources first.`);
+	}
+	for (const plan of perStackPlans) await assertCfnStackAbsent(deps.cfnClient, plan.cfnName);
+	if (options.dryRun) {
+		logger.info("--dry-run: no CloudFormation changesets will be created.");
+		return {
+			outcome: "dry-run",
+			importedStacks: []
+		};
+	}
+	if (!options.yes) {
+		const phase2Note = totalPhase2Creates > 0 ? ` Phase 2 will CREATE ${totalPhase2Creates} non-importable resource(s) across the tree.` : "";
+		const recreateNote = totalRecreate > 0 ? ` cdkd will also pre-DELETE + re-CREATE ${totalRecreate} IMPORT-unsupported resource(s) (brief unavailability window per resource).` : "";
+		if (!await confirmPrompt$1(`Create ${perStackPlans.length} CloudFormation stack(s) by importing the cdkd nested-stack tree rooted at '${rootStackName}' (${rootRegion}) — leaf-first, per-stack IMPORT loop (#464 design §4.3).` + phase2Note + recreateNote + " AWS resources are unchanged. cdkd state for every adopted stack will be deleted on success.")) {
+			logger.info("Migration cancelled. cdkd state and CloudFormation are unchanged.");
+			return {
+				outcome: "cancelled",
+				importedStacks: []
+			};
+		}
+	}
+	const acquiredChildLocks = [];
+	try {
+		for (const node of leafFirst) {
+			if (node.stackName === rootStackName) continue;
+			if (!await deps.lockManager.acquireLock(node.stackName, node.region, deps.lockOwner, "export")) throw new Error(`Could not acquire lock for nested-stack child '${node.stackName}' (${node.region}) — another cdkd process holds it. Wait for it to finish, or run 'cdkd force-unlock ${node.stackName}' if you are certain no other process is active. No CloudFormation changeset has been submitted; cdkd state is unchanged.`);
+			acquiredChildLocks.push({
+				stackName: node.stackName,
+				region: node.region
+			});
+		}
+		const cfnArnByCdkdName = /* @__PURE__ */ new Map();
+		const uploadCleanups = [];
+		const importedStacks = [];
+		try {
+			for (let i = 0; i < perStackPlans.length; i++) {
+				const plan = perStackPlans[i];
+				logger.info(`[${i + 1}/${perStackPlans.length}] Importing cdkd stack '${plan.cdkdName}' → CFn stack '${plan.cfnName}' (${plan.phase1Imports.length} leaf, ${plan.nestedStackRows.length} nested-child adoption)`);
+				let stackParameters;
+				if (plan.cdkdName === rootStackName) stackParameters = rootParameters;
+				else {
+					const parentLogicalId = plan.state.parentLogicalId;
+					const parentStackName = plan.state.parentStack;
+					if (!parentLogicalId || !parentStackName) throw new Error(`runPerStackImportLoop: child '${plan.cdkdName}' state is missing parentLogicalId / parentStack (v6 fields). Re-deploy or re-import the parent stack to refresh.`);
+					const parentPlan = perStackPlans.find((p) => p.cdkdName === parentStackName);
+					if (!parentPlan) throw new Error(`runPerStackImportLoop: child '${plan.cdkdName}' references parent '${parentStackName}' which is not in the per-stack plan list — tree shape is inconsistent.`);
+					const extracted = extractChildImportParameters(parentPlan.template, parentLogicalId);
+					if (extracted.intrinsicSkipped.length > 0) logger.warn(`  Child '${plan.cdkdName}': skipping intrinsic-valued Parameter(s) ${extracted.intrinsicSkipped.join(", ")} (intrinsic-resolution at leaf-IMPORT time is a deferred follow-up). The child template's Parameter Default values must cover these — otherwise CFn will reject the IMPORT.`);
+					stackParameters = extracted.params;
+				}
+				const phase1ATemplate = filterTemplateForImport(plan.template, plan.phase1Imports);
+				const phase1AResources = plan.phase1Imports.map((entry) => ({
+					ResourceType: entry.resourceType,
+					LogicalResourceId: entry.logicalId,
+					ResourceIdentifier: entry.resourceIdentifier
+				}));
+				const injectedDeletion = injectDeletionPolicyForImport(phase1ATemplate);
+				if (injectedDeletion > 0) logger.info(`  Injected DeletionPolicy: Delete on ${injectedDeletion} resource(s) in '${plan.cdkdName}' (required by CFn IMPORT; matches CDK/CFn default).`);
+				try {
+					await submitImportChangeSet(deps.cfnClient, plan.cfnName, phase1ATemplate, phase1AResources, stackParameters, plan.templateFormat, deps.uploadOpts);
+				} catch (err) {
+					const importedSummary = importedStacks.length > 0 ? importedStacks.map((s) => `${s.cdkdStackName} → ${s.cfnStackName}`).join(", ") : "(none)";
+					const remainingSummary = perStackPlans.slice(i).map((p) => p.cdkdName).join(", ");
+					throw new Error(`Phase 1A IMPORT changeset failed for cdkd stack '${plan.cdkdName}' (CFn name '${plan.cfnName}'). Stacks imported successfully so far: ${importedSummary}. Stacks not yet imported (cdkd state preserved): ${remainingSummary}. After resolving the underlying cause, re-run 'cdkd export ${rootStackName}' — already-imported children will be adopted as nested references on retry. Cause: ${err instanceof Error ? err.message : String(err)}`, { cause: err instanceof Error ? err : void 0 });
+				}
+				const cfnArn = (await deps.cfnClient.send(new DescribeStacksCommand({ StackName: plan.cfnName }))).Stacks?.[0]?.StackId;
+				if (!cfnArn) throw new Error(`runPerStackImportLoop: DescribeStacks returned no StackId for '${plan.cfnName}' immediately after Phase 1A IMPORT — AWS may be in an unexpected state.`);
+				cfnArnByCdkdName.set(plan.cdkdName, cfnArn);
+				importedStacks.push({
+					cdkdStackName: plan.cdkdName,
+					cfnStackName: plan.cfnName,
+					cfnStackArn: cfnArn
+				});
+				logger.info(`  ✓ Phase 1A: CFn stack '${plan.cfnName}' created via IMPORT (${plan.phase1Imports.length} leaf resource(s)).`);
+				if (plan.cdkdName !== rootStackName) {
+					logger.info(`  Flipping '${plan.cfnName}' to UPDATE_COMPLETE so it can be adopted as a nested member by its parent's Phase 1B...`);
+					await flipStackToUpdateComplete(deps.cfnClient, plan.cfnName);
+				}
+				const rewrittenNestedRows = /* @__PURE__ */ new Map();
+				if (plan.nestedStackRows.length > 0) {
+					const phase1BTemplate = filterTemplateForImport(plan.template, plan.phase1Imports);
+					injectDeletionPolicyForImport(phase1BTemplate);
+					const phase1BResources = [];
+					for (const row of plan.nestedStackRows) {
+						const childArn = cfnArnByCdkdName.get(row.childStackName);
+						if (!childArn) throw new Error(`runPerStackImportLoop: nested-stack child '${row.childStackName}' has no recorded CFn ARN when processing parent '${plan.cdkdName}'. Leaf-first iteration order should have IMPORTed the child first — this is a cdkd bug.`);
+						const childCfnName = cfnStackNameOf(row.childStackName);
+						const childTemplateBody = await fetchCfnStackTemplate(deps.cfnClient, childCfnName);
+						const uploaded = await uploadCfnTemplate({
+							bucket: deps.uploadOpts.stateBucket,
+							body: childTemplateBody,
+							stackName: `${plan.cdkdName}__nested__${row.logicalId}`,
+							format: "json",
+							...deps.uploadOpts.s3ClientOpts && { s3ClientOpts: deps.uploadOpts.s3ClientOpts }
+						});
+						uploadCleanups.push(uploaded.cleanup);
+						const childActualTags = (await deps.cfnClient.send(new DescribeStacksCommand({ StackName: childCfnName }))).Stacks?.[0]?.Tags ?? [];
+						const originalRow = getResourceFromTemplate(plan.template, row.logicalId);
+						if (!originalRow) throw new Error(`runPerStackImportLoop: parent template for '${plan.cdkdName}' has no resource '${row.logicalId}'. State and template are out of sync.`);
+						const rewrittenRow = injectRetainAndRewriteTemplateUrl(originalRow, uploaded.url, childActualTags);
+						phase1BTemplate["Resources"][row.logicalId] = rewrittenRow;
+						rewrittenNestedRows.set(row.logicalId, rewrittenRow);
+						phase1BResources.push({
+							ResourceType: NESTED_STACK_RESOURCE_TYPE,
+							LogicalResourceId: row.logicalId,
+							ResourceIdentifier: { StackId: childArn }
+						});
+					}
+					try {
+						await submitImportChangeSet(deps.cfnClient, plan.cfnName, phase1BTemplate, phase1BResources, stackParameters, plan.templateFormat, deps.uploadOpts);
+					} catch (err) {
+						const importedSummary = importedStacks.length > 0 ? importedStacks.map((s) => `${s.cdkdStackName} → ${s.cfnStackName}`).join(", ") : "(none)";
+						throw new Error(`Phase 1B (nested-child adoption) IMPORT changeset failed for parent '${plan.cdkdName}' (CFn name '${plan.cfnName}'). The parent CFn stack exists with its ${plan.phase1Imports.length} leaf resource(s); ${plan.nestedStackRows.length} nested-child adoption(s) did NOT complete. Stacks IMPORTed so far (each is a standalone CFn stack): ${importedSummary}. cdkd state for every stack in the tree is preserved. To recover: (1) fix the underlying cause (typically a template-match validation error per AWS-docs "Nested stack import validation"); (2) clear cdkd state for the migrated stacks via 'cdkd state orphan <stack>' (do NOT 'cdkd destroy' — that would tear down the live AWS resources); (3) re-attempt the parent-side nested adoption manually via the AWS console or CLI per the AWS docs procedure. Cause: ${err instanceof Error ? err.message : String(err)}`, { cause: err instanceof Error ? err : void 0 });
+					}
+					logger.info(`  ✓ Phase 1B: parent '${plan.cfnName}' adopted ${plan.nestedStackRows.length} nested child(ren) via UPDATE-IMPORT.`);
+					if (plan.cdkdName !== rootStackName) {
+						logger.info(`  Flipping '${plan.cfnName}' back to UPDATE_COMPLETE so its own parent's Phase 1B can adopt it...`);
+						await flipStackToUpdateComplete(deps.cfnClient, plan.cfnName);
+					}
+				}
+				if (plan.recreateBeforePhase2.length > 0) for (const entry of plan.recreateBeforePhase2) {
+					const handler = PRE_DELETE_HANDLERS[entry.resourceType];
+					if (!handler) throw new Error(`No pre-delete handler registered for ${entry.resourceType} (${entry.logicalId}) in stack '${plan.cdkdName}'. This is a cdkd bug — the resource is in IMPORT_UNSUPPORTED_RECREATABLE_TYPES but lacks a PRE_DELETE_HANDLERS entry.`);
+					logger.info(`  Pre-deleting AWS resource for ${entry.logicalId} (${entry.resourceType}) so CFn can re-CREATE in phase 2...`);
+					await handler(entry);
+					logger.info(`    ✓ deleted ${entry.physicalId}`);
+				}
+				if (plan.phase2Creates.length + plan.recreateBeforePhase2.length > 0) {
+					const phase2Template = applyImportOverlayForPhase2(plan.template, plan.phase1Imports);
+					for (const row of plan.nestedStackRows) {
+						const overlaidResources = phase2Template["Resources"];
+						const rewrittenRow = rewrittenNestedRows.get(row.logicalId);
+						if (rewrittenRow !== void 0) overlaidResources[row.logicalId] = rewrittenRow;
+					}
+					await executeUpdateChangeSet(deps.cfnClient, plan.cfnName, phase2Template, stackParameters, plan.templateFormat, deps.uploadOpts);
+					logger.info(`  ✓ Phase 2: stack '${plan.cfnName}' updated (${plan.phase2Creates.length} non-importable CREATE, ${plan.recreateBeforePhase2.length} re-CREATE).`);
+				}
+			}
+			const stateDeletionFailures = [];
+			for (const node of leafFirst) try {
+				await deps.stateBackend.deleteState(node.stackName, node.region);
+				logger.info(`cdkd state for '${node.stackName}' (${node.region}) removed.`);
+			} catch (err) {
+				stateDeletionFailures.push({
+					stackName: node.stackName,
+					region: node.region,
+					reason: err instanceof Error ? err.message : String(err)
+				});
+				logger.warn(`Failed to delete cdkd state for '${node.stackName}' (${node.region}): ${err instanceof Error ? err.message : String(err)}. The stack IS CFn-managed; clean up with 'cdkd state orphan ${node.stackName}'.`);
+			}
+			if (stateDeletionFailures.length > 0) {
+				const lines = stateDeletionFailures.map((f) => `  - cdkd/${f.stackName}/${f.region}/state.json: ${f.reason}`).join("\n");
+				throw new Error(`${stateDeletionFailures.length} cdkd state record(s) could not be deleted after a successful per-stack IMPORT loop. Every stack in the tree IS CFn-managed (the migration succeeded AWS-side); orphan state remains under:\n${lines}\nRecover with 'cdkd state orphan <stack>' per record.`);
+			}
+			return {
+				outcome: "success",
+				importedStacks
+			};
+		} finally {
+			for (const cleanup of uploadCleanups) await runTemplateUploadCleanup(cleanup, deps.uploadOpts.stateBucket);
+		}
+	} finally {
+		for (let i = acquiredChildLocks.length - 1; i >= 0; i--) {
+			const lock = acquiredChildLocks[i];
+			await deps.lockManager.releaseLock(lock.stackName, lock.region).catch((err) => {
+				logger.warn(`Failed to release lock for '${lock.stackName}' (${lock.region}): ${err instanceof Error ? err.message : String(err)}`);
+			});
+		}
+	}
+}
+/**
+* Helper for {@link runPerStackImportLoop}: pull a single resource out of
+* a template's Resources block by logical id, returning `undefined` if
+* the template is malformed or the resource is absent.
+*/
+function getResourceFromTemplate(template, logicalId) {
+	const resources = template["Resources"];
+	if (!resources || typeof resources !== "object" || Array.isArray(resources)) return void 0;
+	const r = resources[logicalId];
+	if (!r || typeof r !== "object" || Array.isArray(r)) return void 0;
+	return r;
+}
+/**
+* Helper for {@link runPerStackImportLoop}'s non-leaf-parent branch:
+* mutate-clone a nested-stack resource row to (a) inject `DeletionPolicy:
+* Retain` (AWS-docs "Nest an existing stack" requirement so a parent-side
+* rollback does NOT cascade-delete the just-imported child stack), (b)
+* overwrite `Properties.TemplateURL` to the uploaded child template's S3
+* URL, and (c) overwrite `Properties.Tags` with the child stack's actual
+* current tags. The Tags overwrite is required by AWS's "Nested stack
+* import validation": "The tags for the nested AWS::CloudFormation::Stack
+* definition in the parent stack template match the tags for the actual
+* nested stack resource." Without the overwrite, the parent's IMPORT
+* changeset fails with `Tags of resource [<id>] defined in the template
+* don't match with the actual tags of <arn>` — most commonly when
+* {@link flipStackToUpdateComplete} added a `cdkd:nested-export-flip`
+* tag to the child to escape the IMPORT_COMPLETE status. All other
+* Properties (Parameters, NotificationARNs) are preserved from the
+* original row.
+*
+* `childActualTags` is the result of `DescribeStacks(<child>).Stacks[0].Tags`
+* (empty array if the child has no tags). When the child has no actual
+* tags AND the original row has no Tags Properties either, the
+* Properties.Tags key is omitted from the output so the parent template
+* stays minimal (matches the CDK-synth shape for tag-free stacks).
+*
+* Exported for unit testing.
+*/
+function injectRetainAndRewriteTemplateUrl(originalRow, newTemplateUrl, childActualTags) {
+	const cloned = { ...originalRow };
+	cloned["DeletionPolicy"] = "Retain";
+	const existingProps = cloned["Properties"];
+	const properties = existingProps && typeof existingProps === "object" && !Array.isArray(existingProps) ? { ...existingProps } : {};
+	properties["TemplateURL"] = newTemplateUrl;
+	if (childActualTags && childActualTags.length > 0) {
+		const forwardable = childActualTags.filter((t) => t.Key !== void 0 && t.Value !== void 0 && !t.Key.startsWith("aws:"));
+		if (forwardable.length > 0) properties["Tags"] = forwardable.map((t) => ({
+			Key: t.Key,
+			Value: t.Value
+		}));
+	}
+	cloned["Properties"] = properties;
+	return cloned;
+}
+/**
 * Phase 2 of the 2-phase migration: a CFn UPDATE changeset that ADDs the
 * non-importable resources (`Custom::*`) to the just-created stack. CFn
 * diffs against the phase-1 stack state, sees the new resources, and
@@ -37248,7 +37909,7 @@ async function confirmPrompt$1(prompt) {
 	}
 }
 function createExportCommand() {
-	const cmd = new Command("export").description("Hand a cdkd-managed stack over to CloudFormation via CFn IMPORT (changeset). AWS resources are unchanged; cdkd state for the stack is deleted on success. Mirror of `cdkd import` (AWS → cdkd) in the reverse direction (cdkd → CFn). Accepts JSON and YAML templates (YAML via a CFn-aware codec that preserves !Ref / !GetAtt / !Sub shorthand). Aborts if any resource is not CFn-importable.").argument("[stack]", "Stack name to export (auto-detected for single-stack apps)").option("--cfn-stack-name <name>", "Name of the destination CloudFormation stack. Defaults to the cdkd stack name.").option("--template <path>", "Path to a pre-rendered CloudFormation template (JSON or YAML — format auto-detected). Skips synth.").option("--stack-region <region>", "Region of the cdkd state record to operate on. Required when the same stack name has state in multiple regions.").option("--dry-run", "Print the import plan without creating a changeset.", false).option("--accept-transient-context", "Allow CLI -c key=value overrides at export time even though they are not persisted to cdk.json / cdk.context.json (default: refuse). When set, the user is responsible for passing the same -c flags to every future cdk deploy.", false).option("--include-non-importable", "Run a 2-phase migration when the stack contains non-importable resources (Custom::*). Phase 1 imports the importable resources; phase 2 CFn-CREATEs the non-importable ones, which re-invokes each Custom Resource's onCreate handler. Make sure onCreate is idempotent before enabling.", false).option("--parameter <key=value...>", "CFn template Parameter override, repeatable. Required when the synthesized template has Parameters without Default values; otherwise overrides the template's default value. Format: --parameter Key=Value.").option("--strict-cross-stack", "Refuse to export when sibling cdkd stacks in the same CDK app reference the exporting stack via Fn::GetStackOutput. Without the flag, cdkd warns but proceeds — the user is expected to migrate the consumer stacks in a follow-up.", false).option("--no-recreate-import-unsupported", "Block instead of auto-handling resource types AWS does NOT support in IMPORT changesets (currently only AWS::ApiGatewayV2::Stage, emitted by CDK HttpApi). Default behavior: cdkd skips these from phase 1, deletes the AWS-side resource between phases, and lets CFn re-CREATE in phase 2 (brief unavailability window). With this flag, the export aborts with a clear error instead.").action(withErrorHandling(exportCommand));
+	const cmd = new Command("export").description("Hand a cdkd-managed stack over to CloudFormation via CFn IMPORT (changeset). AWS resources are unchanged; cdkd state for the stack is deleted on success. Mirror of `cdkd import` (AWS → cdkd) in the reverse direction (cdkd → CFn). Accepts JSON and YAML templates (YAML via a CFn-aware codec that preserves !Ref / !GetAtt / !Sub shorthand). Aborts if any resource is not CFn-importable.").argument("[stack]", "Stack name to export (auto-detected for single-stack apps)").option("--cfn-stack-name <name>", "Name of the destination CloudFormation stack for the root stack. Defaults to the cdkd stack name (or the cdkd2cfnStackName mapping when the name contains '~'). For per-nested-child overrides, use --cfn-child-stack-name.").option("--cfn-child-stack-name <pair...>", "Per-nested-child CFn stack-name override. Repeatable. Format: '<cdkdName>=<cfnName>' (e.g. --cfn-child-stack-name 'MyApp~Database=my-app-db'). The cdkd stack name for a nested child is '<parent>~<childLogicalId>' (v6 state-key form). Without an override the CFn name is derived by replacing '~' with '-'. Only consulted when the exported stack tree contains nested children; ignored for flat stacks.").option("--template <path>", "Path to a pre-rendered CloudFormation template (JSON or YAML — format auto-detected). Skips synth.").option("--stack-region <region>", "Region of the cdkd state record to operate on. Required when the same stack name has state in multiple regions.").option("--dry-run", "Print the import plan without creating a changeset.", false).option("--accept-transient-context", "Allow CLI -c key=value overrides at export time even though they are not persisted to cdk.json / cdk.context.json (default: refuse). When set, the user is responsible for passing the same -c flags to every future cdk deploy.", false).option("--include-non-importable", "Run a 2-phase migration when the stack contains non-importable resources (Custom::*). Phase 1 imports the importable resources; phase 2 CFn-CREATEs the non-importable ones, which re-invokes each Custom Resource's onCreate handler. Make sure onCreate is idempotent before enabling.", false).option("--parameter <key=value...>", "CFn template Parameter override, repeatable. Required when the synthesized template has Parameters without Default values; otherwise overrides the template's default value. Format: --parameter Key=Value.").option("--strict-cross-stack", "Refuse to export when sibling cdkd stacks in the same CDK app reference the exporting stack via Fn::GetStackOutput. Without the flag, cdkd warns but proceeds — the user is expected to migrate the consumer stacks in a follow-up.", false).option("--no-recreate-import-unsupported", "Block instead of auto-handling resource types AWS does NOT support in IMPORT changesets (currently only AWS::ApiGatewayV2::Stage, emitted by CDK HttpApi). Default behavior: cdkd skips these from phase 1, deletes the AWS-side resource between phases, and lets CFn re-CREATE in phase 2 (brief unavailability window). With this flag, the export aborts with a clear error instead.").action(withErrorHandling(exportCommand));
 	[
 		...commonOptions,
 		...appOptions,
@@ -56924,7 +57585,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.149.0");
+	program.name("cdkd").description("CDK Direct - Deploy AWS CDK apps directly via SDK/Cloud Control API").version("0.150.0");
 	program.addCommand(createBootstrapCommand());
 	program.addCommand(createSynthCommand());
 	program.addCommand(createListCommand());