@go-to-k/cdkd 0.145.1 → 0.146.1

package/dist/cli.js

@@ -31721,6 +31721,18 @@ function getCurrentNestedStackContext() {
 //#endregion
 //#region src/provisioning/providers/nested-stack-provider.ts
 /**
+* Returns `true` when `p` is absolute on the current platform OR begins
+* with a forward slash. The `startsWith('/')` arm covers the cross-platform
+* leak where `path.isAbsolute('/abs/foo')` returns `true` on POSIX but
+* `false` on Windows (Windows absolute paths require a drive letter or
+* UNC root) — a POSIX-style absolute path embedded in a synth template
+* generated on Linux and consumed on a Windows host would slip past
+* `path.isAbsolute()` alone. Exported for unit testing.
+*/
+function isAbsoluteCrossPlatform(p) {
+	return path.isAbsolute(p) || p.startsWith("/");
+}
+/**
 * Provider for `AWS::CloudFormation::Stack` — cdkd's recursive nested-stack
 * adapter. Issue [#459](https://github.com/go-to-k/cdkd/issues/459); see
 * [docs/design/459-nested-stacks.md](../../../docs/design/459-nested-stacks.md)
@@ -31940,7 +31952,7 @@ var NestedStackProvider = class {
 			if (resource?.Type !== "AWS::CloudFormation::Stack") continue;
 			const assetPath = resource.Metadata?.["aws:asset:path"];
 			if (typeof assetPath !== "string" || assetPath.length === 0) continue;
-			if (path.isAbsolute(assetPath)) throw new Error(`NestedStackProvider: nested-stack '${grandLogicalId}' has Metadata['aws:asset:path']='${assetPath}' which is absolute. CDK emits relative asset paths for nested templates; an absolute path indicates the synth output was hand-modified or generated by a non-CDK toolchain. Refusing to load.`);
+			if (isAbsoluteCrossPlatform(assetPath)) throw new Error(`NestedStackProvider: nested-stack '${grandLogicalId}' has Metadata['aws:asset:path']='${assetPath}' which is absolute. CDK emits relative asset paths for nested templates; an absolute path indicates the synth output was hand-modified or generated by a non-CDK toolchain. Refusing to load.`);
 			result[grandLogicalId] = path.join(dir, assetPath);
 		}
 		return result;
@@ -36196,6 +36208,16 @@ function parseCfnTemplateWithFormat(text) {
 //#endregion
 //#region src/cli/commands/retire-cfn-stack.ts
 /**
+* Resource type for a CloudFormation nested-stack child. Hoisted as a
+* constant so the recursive walker, the Retain-injection skip rule, and
+* the import-side short-circuit all reference the same literal — a typo
+* in any one of them would otherwise silently break nested-stack support
+* (the offending row would either be missed by the tree walk or have
+* Retain injected on it, both of which would orphan the child stack
+* record on AWS at retire time).
+*/
+const NESTED_STACK_RESOURCE_TYPE = "AWS::CloudFormation::Stack";
+/**
 * UpdateStack TemplateBody hard limit (51,200 bytes). Templates larger than
 * this are uploaded to cdkd's state S3 bucket and submitted via `TemplateURL`
 * instead — see {@link uploadTemplateForUpdateStack}.
@@ -36242,7 +36264,8 @@ const TEMPLATE_URL_LIMIT = CFN_TEMPLATE_URL_LIMIT;
 */
 async function retireCloudFormationStack(options) {
 	const logger = getLogger();
-	const { cfnStackName, cfnClient, yes, stateBucket, s3ClientOpts } = options;
+	const { cfnStackName, cfnClient, yes, stateBucket, s3ClientOpts, resourceTree } = options;
+	if (resourceTree && resourceTree.stackName !== cfnStackName) throw new Error(`retireCloudFormationStack: caller-supplied resourceTree.stackName='${resourceTree.stackName}' does not match cfnStackName='${cfnStackName}'. The tree's root must be the stack being retired.`);
 	logger.info(`[1/4] Inspecting CloudFormation stack '${cfnStackName}'...`);
 	const stack = (await cfnClient.send(new DescribeStacksCommand({ StackName: cfnStackName }))).Stacks?.[0];
 	if (!stack) throw new Error(`CloudFormation stack '${cfnStackName}' not found.`);
@@ -36254,15 +36277,54 @@ async function retireCloudFormationStack(options) {
 		TemplateStage: "Original"
 	}));
 	if (!tpl.TemplateBody) throw new Error(`GetTemplate returned no body for '${cfnStackName}'.`);
-	const { body: newBody, modified, format } = injectRetainPolicies(tpl.TemplateBody, cfnStackName);
+	const nestedCleanups = [];
+	const hasNestedChildren = templateContainsNestedStackRows(tpl.TemplateBody);
+	let newBody;
+	let modified;
+	let format;
+	if (hasNestedChildren) {
+		const tree = resourceTree ?? await getCloudFormationResourceTree(cfnStackName, cfnClient);
+		try {
+			const recursive = await injectRetainPoliciesRecursive(tpl.TemplateBody, cfnStackName, tree, {
+				cfnClient,
+				stateBucket,
+				...s3ClientOpts && { s3ClientOpts }
+			});
+			newBody = recursive.body;
+			modified = recursive.modified;
+			format = recursive.format;
+			nestedCleanups.push(...recursive.cleanups);
+		} catch (err) {
+			if (err instanceof RecursiveRetainInjectionError) for (const cleanup of err.cleanups) try {
+				await cleanup();
+			} catch (cleanupErr) {
+				const msg = cleanupErr instanceof Error ? cleanupErr.message : String(cleanupErr);
+				logger.warn(`Failed to delete partial nested-template upload from '${stateBucket}' during error recovery. Clean up manually under prefix '${MIGRATE_TMP_PREFIX}/'. Cause: ${msg}`);
+			}
+			throw err;
+		}
+	} else ({body: newBody, modified, format} = injectRetainPolicies(tpl.TemplateBody, cfnStackName));
 	if (!yes) {
 		if (!await confirmPrompt$2(`Set DeletionPolicy=Retain and UpdateReplacePolicy=Retain on every resource in CloudFormation stack '${cfnStackName}', then delete the stack? AWS resources will NOT be deleted (cdkd state has been written).`)) {
 			logger.info("CloudFormation stack retirement cancelled. cdkd state is unaffected.");
+			for (const cleanup of nestedCleanups) try {
+				await cleanup();
+			} catch (cleanupErr) {
+				const msg = cleanupErr instanceof Error ? cleanupErr.message : String(cleanupErr);
+				logger.warn(`Failed to delete temporary nested-template upload from '${stateBucket}' during cancel cleanup. Clean up manually under prefix '${MIGRATE_TMP_PREFIX}/'. Cause: ${msg}`);
+			}
 			return { outcome: "cancelled" };
 		}
 	}
-	if (!modified) logger.info(`[2/4] Template already has Retain on every resource — skipping UpdateStack.`);
-	else {
+	if (!modified) {
+		logger.info(`[2/4] Template already has Retain on every resource — skipping UpdateStack.`);
+		if (nestedCleanups.length > 0) for (const cleanup of nestedCleanups) try {
+			await cleanup();
+		} catch (cleanupErr) {
+			const msg = cleanupErr instanceof Error ? cleanupErr.message : String(cleanupErr);
+			logger.warn(`Failed to delete temporary nested-template upload from '${stateBucket}'. Clean up manually under prefix '${MIGRATE_TMP_PREFIX}/'. Cause: ${msg}`);
+		}
+	} else {
 		logger.info(`[2/4] Injected DeletionPolicy=Retain and UpdateReplacePolicy=Retain.`);
 		if (newBody.length > TEMPLATE_URL_LIMIT) throw new Error(`Modified template is ${newBody.length} bytes, exceeds the CloudFormation UpdateStack TemplateURL limit (${TEMPLATE_URL_LIMIT}). cdkd state has already been written; retire the stack manually with (1) shrink the template, then (2) UpdateStack with Retain policies, (3) DeleteStack — or split the stack and retry.`);
 		let updateInput;
@@ -36305,8 +36367,9 @@ async function retireCloudFormationStack(options) {
 				maxWaitTime: 1800
 			}, { StackName: cfnStackName });
 		} finally {
-			if (s3Cleanup) try {
-				await s3Cleanup();
+			const allCleanups = [...s3Cleanup ? [s3Cleanup] : [], ...nestedCleanups];
+			for (const cleanup of allCleanups) try {
+				await cleanup();
 			} catch (cleanupErr) {
 				const msg = cleanupErr instanceof Error ? cleanupErr.message : String(cleanupErr);
 				logger.warn(`Failed to delete temporary template upload from '${stateBucket}'. Clean up manually under prefix '${MIGRATE_TMP_PREFIX}/'. Cause: ${msg}`);
@@ -36374,11 +36437,66 @@ function injectRetainPolicies(templateBody, cfnStackName) {
 		throw new Error(`Template for '${cfnStackName}' is not a valid CloudFormation template. cdkd's --migrate-from-cloudformation flow supports both JSON and YAML templates (YAML via a CFn-aware codec that preserves !Ref / !GetAtt / !Sub shorthand). Cause: ${err instanceof Error ? err.message : String(err)}`);
 	}
 	if (!("Resources" in parsed) || typeof parsed["Resources"] !== "object" || parsed["Resources"] === null || Array.isArray(parsed["Resources"])) throw new Error(`Template for '${cfnStackName}' has no Resources section — refusing to retire.`);
-	let modified = false;
+	const modified = injectRetainPoliciesOnParsedResources(parsed["Resources"]);
+	return {
+		body: stringifyCfnTemplate(parsed, format),
+		modified,
+		format
+	};
+}
+/**
+* Cheap sniff: does the template body contain any `AWS::CloudFormation::Stack`
+* resource rows? Parses + walks `Resources` once (no recursive descent),
+* tolerating parse failures by returning `false` (the caller's downstream
+* parse step will surface the same error with a richer message). Used by
+* {@link retireCloudFormationStack} to decide whether to lazily build the
+* recursive {@link CfnStackResourceTree} — non-nested templates skip the
+* extra `DescribeStackResources` round-trip entirely.
+*/
+function templateContainsNestedStackRows(templateBody) {
+	let parsed;
+	try {
+		parsed = parseCfnTemplate(templateBody);
+	} catch {
+		return false;
+	}
 	const resources = parsed["Resources"];
+	if (!resources || typeof resources !== "object" || Array.isArray(resources)) return false;
+	for (const resource of Object.values(resources)) {
+		if (!resource || typeof resource !== "object" || Array.isArray(resource)) continue;
+		if (resource["Type"] === "AWS::CloudFormation::Stack") return true;
+	}
+	return false;
+}
+/**
+* Mutate an already-parsed `Resources` map in place: set `DeletionPolicy: Retain`
+* and `UpdateReplacePolicy: Retain` on every leaf resource that doesn't
+* already have them. Returns the `modified` flag so the caller can decide
+* whether the round-trip is worth a `stringifyCfnTemplate` re-serialization
+* (and whether `UpdateStack` is needed at all).
+*
+* `AWS::CloudFormation::Stack` resources are **intentionally skipped** — see
+* issue [#464](https://github.com/go-to-k/cdkd/issues/464) and the design at
+* [docs/design/464-nested-stacks-export-import.md](../../../docs/design/464-nested-stacks-export-import.md)
+* §3.4. Retain on a nested-stack row tells AWS CFn's parent-side `DeleteStack`
+* to NOT cascade-delete the child stack record at all, which would leave a
+* stranded child stack record on AWS that the user has to clean up manually.
+* We want the cascade to descend (so child stack records get deleted as the
+* tree unwinds) while every child's own leaf resources stay because THEIR
+* Retain was injected on the previous recursion level — the recursive
+* Retain injection in {@link injectRetainPoliciesRecursive} relies on this
+* skip rule to behave correctly.
+*
+* Shared between the single-template path ({@link injectRetainPolicies}) and
+* the per-level walk inside {@link injectRetainPoliciesRecursive} so both
+* sites apply the exact same skip rule with no risk of drift.
+*/
+function injectRetainPoliciesOnParsedResources(resources) {
+	let modified = false;
 	for (const [, resource] of Object.entries(resources)) {
 		if (!resource || typeof resource !== "object" || Array.isArray(resource)) continue;
 		const r = resource;
+		if (r["Type"] === "AWS::CloudFormation::Stack") continue;
 		if (r["DeletionPolicy"] !== "Retain") {
 			r["DeletionPolicy"] = "Retain";
 			modified = true;
@@ -36388,6 +36506,119 @@ function injectRetainPolicies(templateBody, cfnStackName) {
 			modified = true;
 		}
 	}
+	return modified;
+}
+/**
+* Recursive variant of {@link injectRetainPolicies} that handles a parent
+* template containing one or more `AWS::CloudFormation::Stack` rows. Issue
+* [#464](https://github.com/go-to-k/cdkd/issues/464); see
+* [docs/design/464-nested-stacks-export-import.md](../../../docs/design/464-nested-stacks-export-import.md)
+* §3.4 for the design rationale.
+*
+* For each nested-stack row in the parent template:
+*   1. `GetTemplate` Original-stage on the corresponding child stack ARN (read
+*      from the supplied {@link CfnStackResourceTree}, populated up front by
+*      {@link getCloudFormationResourceTree}).
+*   2. Recursively process the child template — Retain injection on its
+*      leaves AND further recursion into any grandchildren.
+*   3. If the recursion produced a modified child body, upload the modified
+*      body to the cdkd state bucket via the shared {@link uploadCfnTemplate}
+*      helper and rewrite the parent's `Properties.TemplateURL` for that
+*      row to the uploaded URL — so the parent's eventual `UpdateStack`
+*      cascades into the child with the Retain-bearing template.
+*
+* After all nested-stack rows are processed, the parent's own leaf
+* resources get Retain injected via {@link injectRetainPoliciesOnParsedResources}
+* — the SAME helper the single-template path uses, applying the same
+* "skip `AWS::CloudFormation::Stack` rows" rule (those rows must NOT have
+* Retain or cascade-delete won't descend — see the helper's doc-comment).
+*
+* The returned `cleanups` array carries one S3 delete callback per
+* transient child-template upload made anywhere in the recursive walk.
+* The caller drains it in a `finally` block around the parent
+* `UpdateStack` call — CFn fetches each child template synchronously
+* during `UpdateStack`, so the transient objects can be reaped as soon
+* as that call returns (success OR failure). When the helper itself
+* throws mid-walk, the partial uploads accumulated so far are returned
+* via a thrown {@link RecursiveRetainInjectionError} so the outer
+* `finally` can still reap them — losing the throw stack vs. the
+* cleanups would have leaked transient S3 objects.
+*
+* Exported so the recursive call can be unit-tested end-to-end (the AWS
+* round-trips are mocked at the SDK boundary, but the recursion shape
+* itself is the load-bearing piece).
+*/
+async function injectRetainPoliciesRecursive(rootTemplateBody, rootCfnStackName, rootTree, deps) {
+	const cleanups = [];
+	try {
+		return {
+			...await injectRetainPoliciesRecursiveInternal(rootTemplateBody, rootCfnStackName, rootTree, deps, cleanups),
+			cleanups
+		};
+	} catch (err) {
+		throw new RecursiveRetainInjectionError(err instanceof Error ? err.message : String(err), cleanups, err instanceof Error ? err : void 0);
+	}
+}
+/**
+* Thrown by {@link injectRetainPoliciesRecursive} when the recursive walk
+* fails partway through. Carries the array of cleanup callbacks for every
+* successful transient S3 upload made BEFORE the failure so the outer
+* `finally` in `retireCloudFormationStack` can still reap them.
+*
+* Without this, a mid-walk error would lose every accumulated cleanup —
+* the error path would skip the parent's `finally` block that drains
+* `nestedCleanups`, leaking N transient S3 objects per failed retire.
+*/
+var RecursiveRetainInjectionError = class extends Error {
+	cleanups;
+	cause;
+	constructor(message, cleanups, cause) {
+		super(message);
+		this.name = "RecursiveRetainInjectionError";
+		this.cleanups = cleanups;
+		if (cause) this.cause = cause;
+	}
+};
+async function injectRetainPoliciesRecursiveInternal(templateBody, cfnStackName, tree, deps, cleanups) {
+	const format = detectTemplateFormat(templateBody);
+	let parsed;
+	try {
+		parsed = parseCfnTemplate(templateBody);
+	} catch (err) {
+		throw new Error(`Template for '${cfnStackName}' is not a valid CloudFormation template. cdkd's --migrate-from-cloudformation flow supports both JSON and YAML templates (YAML via a CFn-aware codec that preserves !Ref / !GetAtt / !Sub shorthand). Cause: ${err instanceof Error ? err.message : String(err)}`);
+	}
+	if (!("Resources" in parsed) || typeof parsed["Resources"] !== "object" || parsed["Resources"] === null || Array.isArray(parsed["Resources"])) throw new Error(`Template for '${cfnStackName}' has no Resources section — refusing to retire.`);
+	const resources = parsed["Resources"];
+	let modified = false;
+	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 childNode = tree.nested.get(logicalId);
+		if (!childNode) throw new Error(`Template for '${cfnStackName}' has nested-stack '${logicalId}' (Type: ${NESTED_STACK_RESOURCE_TYPE}) but the CloudFormation resource tree has no matching child entry. AWS may have removed the child since DescribeStackResources ran, or the template was hand-edited mid-flight — re-run \`cdkd import --migrate-from-cloudformation\` to refresh.`);
+		const childTpl = await deps.cfnClient.send(new GetTemplateCommand({
+			StackName: childNode.physicalId,
+			TemplateStage: "Original"
+		}));
+		if (!childTpl.TemplateBody) throw new Error(`GetTemplate returned no body for nested stack '${logicalId}' (physicalId='${childNode.physicalId}', parent='${cfnStackName}').`);
+		const childResult = await injectRetainPoliciesRecursiveInternal(childTpl.TemplateBody, childNode.stackName, childNode, deps, cleanups);
+		if (childResult.modified) {
+			if (childResult.body.length > TEMPLATE_URL_LIMIT) throw new Error(`Modified nested-stack template for '${logicalId}' is ${childResult.body.length} bytes, exceeds the CloudFormation TemplateURL limit (${TEMPLATE_URL_LIMIT}). cdkd state has already been written for the root parent; retire the stack manually with (1) shrink the child template, then (2) UpdateStack with Retain policies on the parent and each child, (3) DeleteStack on the parent.`);
+			const uploaded = await uploadCfnTemplate({
+				bucket: deps.stateBucket,
+				body: childResult.body,
+				stackName: `${cfnStackName}__nested__${logicalId}`,
+				format: childResult.format,
+				...deps.s3ClientOpts && { s3ClientOpts: deps.s3ClientOpts }
+			});
+			cleanups.push(uploaded.cleanup);
+			const propsRaw = r["Properties"];
+			const props = propsRaw && typeof propsRaw === "object" && !Array.isArray(propsRaw) ? propsRaw : r["Properties"] = {};
+			props["TemplateURL"] = uploaded.url;
+			modified = true;
+		}
+	}
+	if (injectRetainPoliciesOnParsedResources(resources)) modified = true;
 	return {
 		body: stringifyCfnTemplate(parsed, format),
 		modified,
@@ -36395,28 +36626,56 @@ function injectRetainPolicies(templateBody, cfnStackName) {
 	};
 }
 /**
-* Ask CloudFormation directly which physical id corresponds to each logical
-* id in the named stack. Used by `cdkd import --migrate-from-cloudformation`
-* to side-step cdkd's tag-based auto-lookup (which can't find resources
-* deployed by upstream `cdk deploy` — that flow doesn't propagate
-* `aws:cdk:path` as an AWS tag, and AWS reserves the `aws:` tag prefix so
-* we can't add it ourselves either).
+* Recursive variant of {@link getCloudFormationResourceMapping} that returns
+* the full nested-stack tree rooted at `rootStackName`. For each
+* `AWS::CloudFormation::Stack` row in the root's resources, recursively
+* calls `DescribeStackResources(<child ARN>)` (AWS accepts the ARN as
+* `StackName`) to populate the child node, and so on to arbitrary depth.
 *
-* Pulls the entire stack with `DescribeStackResources` (one round-trip,
-* unbounded result by spec — CFn caps stacks at 500 resources). Resources
-* whose `PhysicalResourceId` is missing (rare; typically an import-failed
-* resource or `AWS::CDK::Metadata`) are skipped silently — the caller
-* already iterates the synthesized template separately and will surface
-* those as `skipped-no-impl` / `skipped-not-found`.
+* Issue [#464](https://github.com/go-to-k/cdkd/issues/464): the recursive
+* `cdkd import --migrate-from-cloudformation` flow uses this once at the
+* top of the import command to drive BOTH (a) per-child state writes
+* under the v6 state-key shape `cdkd/<parent>~<child>/<region>/state.json`
+* AND (b) the recursive `injectRetainPoliciesRecursive` walk that retires
+* the whole tree on AWS without orphaning any resources.
+*
+* Children at every level are fetched in parallel via `Promise.all` so an
+* N-stack-wide tree only takes log(depth) round-trips of wall-clock time
+* instead of N — load-bearing when a CDK app spreads micro-services across
+* many nested children.
+*
+* Tree node `physicalId` is the AWS-side identifier accepted by every
+* CFn API call (`DescribeStackResources` / `GetTemplate`). For the root,
+* that's the user-supplied stack name; for nested children, the child
+* stack ARN.
 */
-async function getCloudFormationResourceMapping(cfnStackName, cfnClient) {
-	const resp = await cfnClient.send(new DescribeStackResourcesCommand({ StackName: cfnStackName }));
-	const map = /* @__PURE__ */ new Map();
+async function getCloudFormationResourceTree(rootStackName, cfnClient) {
+	return walkCfnStackTree(rootStackName, rootStackName, cfnClient);
+}
+async function walkCfnStackTree(stackName, physicalId, cfnClient) {
+	const resp = await cfnClient.send(new DescribeStackResourcesCommand({ StackName: physicalId }));
+	const resources = /* @__PURE__ */ new Map();
+	const nestedChildren = [];
 	for (const r of resp.StackResources ?? []) {
 		if (!r.LogicalResourceId || !r.PhysicalResourceId) continue;
-		map.set(r.LogicalResourceId, r.PhysicalResourceId);
+		resources.set(r.LogicalResourceId, r.PhysicalResourceId);
+		if (r.ResourceType === "AWS::CloudFormation::Stack") nestedChildren.push({
+			logicalId: r.LogicalResourceId,
+			childArn: r.PhysicalResourceId
+		});
 	}
-	return map;
+	const childPairs = await Promise.all(nestedChildren.map(async ({ logicalId, childArn }) => ({
+		logicalId,
+		node: await walkCfnStackTree(childArn, childArn, cfnClient)
+	})));
+	const nested = /* @__PURE__ */ new Map();
+	for (const { logicalId, node } of childPairs) nested.set(logicalId, node);
+	return {
+		stackName,
+		physicalId,
+		resources,
+		nested
+	};
 }
 async function confirmPrompt$2(prompt) {
 	const rl = readline.createInterface({
@@ -36499,26 +36758,42 @@ async function importCommand(stackArg, options) {
 		const resources = collectImportableResources(template);
 		const templateLogicalIds = new Set(resources.map((r) => r.logicalId));
 		logger.info(`Found ${resources.length} resource(s) in template`);
+		let migrationTree;
 		if (migrationCfnStackName) {
-			logger.info(`Resolving physical IDs from CloudFormation stack '${migrationCfnStackName}'...`);
-			const cfnMapping = await getCloudFormationResourceMapping(migrationCfnStackName, awsClients.cloudFormation);
+			logger.info(`Resolving physical IDs from CloudFormation stack '${migrationCfnStackName}' (recursive)...`);
+			migrationTree = await getCloudFormationResourceTree(migrationCfnStackName, awsClients.cloudFormation);
+			const cfnMapping = migrationTree.resources;
 			let derived = 0;
 			let skippedNonImportable = 0;
+			let skippedNestedStackRow = 0;
 			for (const [logicalId, physicalId] of cfnMapping) {
 				if (!templateLogicalIds.has(logicalId)) {
 					skippedNonImportable++;
 					continue;
 				}
+				if (template.Resources[logicalId]?.Type === "AWS::CloudFormation::Stack") {
+					skippedNestedStackRow++;
+					continue;
+				}
 				if (!overrides.has(logicalId)) {
 					overrides.set(logicalId, physicalId);
 					derived++;
 				}
 			}
-			const overriddenByUser = cfnMapping.size - derived - skippedNonImportable;
+			const overriddenByUser = cfnMapping.size - derived - skippedNonImportable - skippedNestedStackRow;
 			const detail = [];
 			if (overriddenByUser > 0) detail.push(`${overriddenByUser} already overridden by --resource`);
 			if (skippedNonImportable > 0) detail.push(`${skippedNonImportable} non-importable (e.g. CDKMetadata)`);
+			if (skippedNestedStackRow > 0) detail.push(`${skippedNestedStackRow} nested-stack row(s) handled separately`);
 			logger.info(`Resolved ${derived} physical ID(s) from CloudFormation` + (detail.length > 0 ? ` (${detail.join(", ")})` : ""));
+			validateNestedStackShape(template, migrationTree, stackInfo.stackName, stackInfo.nestedTemplates ?? {});
+		}
+		let accountIdForNestedSynth;
+		if (migrationTree && migrationTree.nested.size > 0) {
+			const { GetCallerIdentityCommand } = await import("@aws-sdk/client-sts");
+			const identity = await awsClients.sts.send(new GetCallerIdentityCommand({}));
+			if (!identity.Account) throw new Error("STS GetCallerIdentity returned no Account — cdkd needs the account ID to synthesize cdkd-local ARNs for nested-stack rows. Verify the active AWS credentials are valid (e.g. `aws sts get-caller-identity`).");
+			accountIdForNestedSynth = identity.Account;
 		}
 		const selectiveMode = overrides.size > 0 && !options.auto && !options.migrateFromCloudformation;
 		if (selectiveMode) logger.info(`Selective mode: only importing the ${overrides.size} resource(s) you listed (${[...overrides.keys()].join(", ")}). Pass --auto to also tag-import the rest.`);
@@ -36549,6 +36824,15 @@ async function importCommand(stackArg, options) {
 					});
 					continue;
 				}
+				if (resource.Type === "AWS::CloudFormation::Stack" && migrationTree && migrationTree.nested.has(logicalId) && accountIdForNestedSynth) {
+					rows.push({
+						logicalId,
+						resourceType: resource.Type,
+						outcome: "imported",
+						physicalId: synthesizeNestedStackArn(targetRegion, accountIdForNestedSynth, stackInfo.stackName, logicalId)
+					});
+					continue;
+				}
 				const outcome = await importOne({
 					logicalId,
 					resource,
@@ -36590,6 +36874,19 @@ async function importCommand(stackArg, options) {
 			await stateBackend.saveState(stackInfo.stackName, targetRegion, stackState, saveOptions);
 			logger.info(`✓ State written: ${stackInfo.stackName} (${targetRegion})`);
 			logger.info(`  ${importedRows.length} resource(s) imported. Run 'cdkd diff' to see how the imported state lines up with the template.`);
+			if (migrationCfnStackName && migrationTree && accountIdForNestedSynth) await importNestedStackChildrenRecursive({
+				parentStackName: stackInfo.stackName,
+				parentRegion: targetRegion,
+				parentNestedTemplates: stackInfo.nestedTemplates ?? {},
+				parentTree: migrationTree,
+				stateBackend,
+				lockManager,
+				providerRegistry,
+				templateParser,
+				lockOwner: owner,
+				accountId: accountIdForNestedSynth,
+				logger
+			});
 			if (migrationCfnStackName) {
 				const orphaned = resources.length - importedRows.length;
 				if (orphaned > 0) logger.warn(`--migrate-from-cloudformation: ${orphaned} of ${resources.length} template resource(s) were NOT imported into cdkd. After the CloudFormation stack is retired, those resources remain in AWS but are unmanaged by both CloudFormation and cdkd.`);
@@ -36598,7 +36895,8 @@ async function importCommand(stackArg, options) {
 					cfnClient: awsClients.cloudFormation,
 					yes: options.yes,
 					stateBucket,
-					...options.profile && { s3ClientOpts: { profile: options.profile } }
+					...options.profile && { s3ClientOpts: { profile: options.profile } },
+					...migrationTree && { resourceTree: migrationTree }
 				});
 			}
 		} finally {
@@ -37047,6 +37345,205 @@ async function captureObservedForImportedResources(stackState, providerRegistry,
 		}
 	}));
 }
+/**
+* Synthesize the cdkd-local ARN that `NestedStackProvider.create` would write
+* for a nested-stack resource (design [docs/design/459-nested-stacks.md](../../../docs/design/459-nested-stacks.md)
+* §3, issue [#464](https://github.com/go-to-k/cdkd/issues/464) §6). Partition
+* `cdkd-local` is load-bearing — any consumer that misuses this value as a
+* real AWS ARN fails loudly with "Invalid ARN partition: cdkd-local" rather
+* than silently using a non-ARN string. The format MUST match
+* `NestedStackProvider.synthesizeArn` so an import-then-deploy cycle does
+* not surface phantom property changes on the nested-stack row.
+*/
+function synthesizeNestedStackArn(region, accountId, parentStackName, logicalId) {
+	return `arn:cdkd-local:${region}:${accountId}:nested-stack/${parentStackName}/${logicalId}`;
+}
+/**
+* Validate the parent template ↔ AWS CFn tree shape consistency before any
+* destructive walk begins. Three failure modes are surfaced up front so
+* the user gets one clear error instead of a partial-success state file
+* graveyard:
+*
+*   1. Synth template has `AWS::CloudFormation::Stack` row at logical id X
+*      but AWS tree has no child at X — likely the user added a new
+*      nested child to the CDK code without running `cdk deploy` first.
+*   2. AWS tree has child at logical id Y but synth template has no
+*      matching row — the user removed a nested child from the CDK code
+*      but the live CFn stack still has it (or AWS removed it
+*      mid-flight).
+*   3. Synth's `nestedTemplates` index is missing a path for some nested
+*      row — usually means CDK 2.x didn't emit `Metadata['aws:asset:path']`
+*      on the row (older CDK versions, or a hand-edited template). Without
+*      the local template file we can't enumerate the child's resources
+*      for the per-child state write.
+*
+* Mirrors the upstream `cdk import` mismatch UX — "import refuses on a
+* shape mismatch, fix the shape and re-run."
+*/
+function validateNestedStackShape(template, tree, parentStackName, nestedTemplates) {
+	const templateNestedIds = /* @__PURE__ */ new Set();
+	for (const [logicalId, resource] of Object.entries(template.Resources)) if (resource.Type === "AWS::CloudFormation::Stack") templateNestedIds.add(logicalId);
+	const treeNestedIds = new Set(tree.nested.keys());
+	const inTemplateMissingFromAws = [];
+	for (const id of templateNestedIds) if (!treeNestedIds.has(id)) inTemplateMissingFromAws.push(id);
+	const inAwsMissingFromTemplate = [];
+	for (const id of treeNestedIds) if (!templateNestedIds.has(id)) inAwsMissingFromTemplate.push(id);
+	const inTemplateMissingNestedTemplatePath = [];
+	for (const id of templateNestedIds) if (!nestedTemplates[id]) inTemplateMissingNestedTemplatePath.push(id);
+	const problems = [];
+	if (inTemplateMissingFromAws.length > 0) problems.push(`template has nested-stack row(s) not present in CloudFormation: [${inTemplateMissingFromAws.join(", ")}] — run \`cdk deploy\` first so the AWS-side stack matches the synth template`);
+	if (inAwsMissingFromTemplate.length > 0) problems.push(`CloudFormation has nested-child stack(s) not present in the synth template: [${inAwsMissingFromTemplate.join(", ")}] — the CDK code was edited to remove these children, but the live CFn stack still has them. Run \`cdk deploy\` to apply the removal, or revert the CDK edit`);
+	if (inTemplateMissingNestedTemplatePath.length > 0) problems.push(`synth cloud assembly is missing nested-template asset paths for row(s) [${inTemplateMissingNestedTemplatePath.join(", ")}] — verify CDK 2.x \`cdk.NestedStack\` emits Metadata['aws:asset:path'] (default behavior)`);
+	if (problems.length > 0) throw new Error(`cdkd import --migrate-from-cloudformation: parent stack '${parentStackName}' template ↔ CloudFormation shape mismatch:\n  - ${problems.join("\n  - ")}`);
+}
+/**
+* After the root parent stack's cdkd state is written, walk the
+* `migrationTree.nested` map and adopt every nested child into its own
+* v6-keyed state file (`cdkd/<parent>~<childLogicalId>/<region>/state.json`).
+* Recurses into grandchildren via the same walker.
+*
+* Per child:
+*   1. Acquire the child's lock. Order across the full tree is
+*      **parent-first acquire, leaves-first release** (each level's
+*      `finally` releases its child lock before sibling iteration
+*      continues, and the root lock is the outermost — held by
+*      `runImport`'s `try` / `finally`). This is the conventional
+*      hierarchical lock pattern: parent-first acquire prevents a
+*      second cdkd import from racing past the root lock; leaves-first
+*      release on success/failure means a mid-walk error never strands
+*      a child lock past its scope. Design §3.3 wording ("leaves first,
+*      parent last") is preserved as the RELEASE order; the acquire
+*      order is parent-first to keep the lock graph deadlock-free.
+*   2. Read the child template body from the synth cloud assembly via
+*      `parentNestedTemplates[<childLogicalId>]` (populated by
+*      AssemblyReader at synth time — see {@link AssemblyReader.parseStack}).
+*   3. Enumerate the child's importable resources (same filter as the
+*      root's `collectImportableResources` — drop `AWS::CDK::Metadata`,
+*      short-circuit `AWS::CloudFormation::Stack` rows to synth ARNs).
+*   4. For each child resource: dispatch through `importOne` with the
+*      child's `(logicalId → physicalId)` overrides from `childTree.resources`.
+*   5. Build the child's `StackState` with `parentStack` / `parentLogicalId`
+*      / `parentRegion` populated per state schema v6.
+*   6. Save state via `stateBackend.saveState('<parent>~<childLogicalId>', ...)`.
+*   7. Recurse into grandchildren.
+*
+* Lock release happens in REVERSE acquisition order in the outer
+* `finally` of each child — leaves-first acquire / parent-last release on
+* success, AND parent-last release on failure. Per memory rule
+* `feedback_destructive_state_test_coverage.md`, the lock-release order
+* is verified by unit test.
+*/
+async function importNestedStackChildrenRecursive(args) {
+	const { parentStackName, parentRegion, parentNestedTemplates, parentTree, stateBackend, lockManager, providerRegistry, templateParser, lockOwner, accountId, logger } = args;
+	for (const [childLogicalId, childTreeNode] of parentTree.nested) {
+		const childStackName = `${parentStackName}~${childLogicalId}`;
+		const childRegion = parentRegion;
+		const childTemplatePath = parentNestedTemplates[childLogicalId];
+		if (!childTemplatePath) throw new Error(`cdkd import --migrate-from-cloudformation: missing nested-template path for '${childLogicalId}' under parent '${parentStackName}' — validateNestedStackShape should have rejected this; please file a bug.`);
+		logger.info(`Adopting nested stack '${childLogicalId}' as cdkd stack '${childStackName}' (${childRegion})...`);
+		const childTemplate = readNestedChildTemplate(childTemplatePath, childLogicalId);
+		await lockManager.acquireLock(childStackName, childRegion, lockOwner, "import");
+		try {
+			const childResources = collectImportableResources(childTemplate);
+			const childTemplateLogicalIds = new Set(childResources.map((r) => r.logicalId));
+			const childOverrides = /* @__PURE__ */ new Map();
+			for (const [logicalId, physicalId] of childTreeNode.resources) {
+				if (!childTemplateLogicalIds.has(logicalId)) continue;
+				if (childTemplate.Resources[logicalId]?.Type === "AWS::CloudFormation::Stack") continue;
+				childOverrides.set(logicalId, physicalId);
+			}
+			const rows = [];
+			for (const { logicalId, resource } of childResources) {
+				if (resource.Type === "AWS::CloudFormation::Stack" && childTreeNode.nested.has(logicalId)) {
+					rows.push({
+						logicalId,
+						resourceType: resource.Type,
+						outcome: "imported",
+						physicalId: synthesizeNestedStackArn(childRegion, accountId, childStackName, logicalId)
+					});
+					continue;
+				}
+				const outcome = await importOne({
+					logicalId,
+					resource,
+					stackName: childStackName,
+					region: childRegion,
+					providerRegistry,
+					override: childOverrides.get(logicalId),
+					overrides: childOverrides
+				});
+				rows.push(outcome);
+			}
+			const childStackState = buildStackState(childStackName, childRegion, rows, templateParser, childTemplate, null, false);
+			childStackState.parentStack = parentStackName;
+			childStackState.parentLogicalId = childLogicalId;
+			childStackState.parentRegion = parentRegion;
+			await resolveImportedProperties(childStackState, childTemplate, childRegion, stateBackend, logger);
+			await captureObservedForImportedResources(childStackState, providerRegistry, logger);
+			await stateBackend.saveState(childStackName, childRegion, childStackState);
+			logger.info(`✓ Nested stack state written: ${childStackName} (${childRegion}) — ${rows.filter((r) => r.outcome === "imported").length} resource(s) imported.`);
+			if (childTreeNode.nested.size > 0) await importNestedStackChildrenRecursive({
+				parentStackName: childStackName,
+				parentRegion: childRegion,
+				parentNestedTemplates: indexGrandchildTemplatePaths(childTemplate, childTemplatePath),
+				parentTree: childTreeNode,
+				stateBackend,
+				lockManager,
+				providerRegistry,
+				templateParser,
+				lockOwner,
+				accountId,
+				logger
+			});
+		} finally {
+			await lockManager.releaseLock(childStackName, childRegion).catch((err) => {
+				logger.warn(`Failed to release lock for nested stack '${childStackName}' (${childRegion}): ${err instanceof Error ? err.message : String(err)}`);
+			});
+		}
+	}
+}
+/**
+* Read a nested child's template body from the synth cloud assembly's
+* sibling file (the path AssemblyReader populates from
+* `Metadata['aws:asset:path']`). Wraps the I/O + JSON parse failures with
+* an actionable error that names the offending child logical id.
+*/
+function readNestedChildTemplate(templatePath, childLogicalId) {
+	let raw;
+	try {
+		raw = readFileSync(templatePath, "utf-8");
+	} catch (err) {
+		throw new Error(`Failed to read nested-stack template for '${childLogicalId}' at ${templatePath}: ${err instanceof Error ? err.message : String(err)}`);
+	}
+	try {
+		return JSON.parse(raw);
+	} catch (err) {
+		throw new Error(`Failed to parse nested-stack template for '${childLogicalId}' at ${templatePath}: ${err instanceof Error ? err.message : String(err)}`);
+	}
+}
+/**
+* Index a child template's `AWS::CloudFormation::Stack` rows by their
+* `aws:asset:path` Metadata, mirroring what {@link AssemblyReader.parseStack}
+* does for the root parent. Grandchild template files are sibling .nested
+* files of the child template file in the same cdk.out subdirectory.
+*
+* Refuses absolute paths for the same reason `NestedStackProvider.indexGrandchildTemplates`
+* does: an absolute path indicates the synth output was hand-modified or
+* generated by a non-CDK toolchain — `path.join(dir, '/abs/foo')` would
+* silently bypass our `dir` resolution and point outside cdk.out.
+*/
+function indexGrandchildTemplatePaths(childTemplate, childTemplatePath) {
+	const dir = path.dirname(childTemplatePath);
+	const result = {};
+	for (const [grandLogicalId, resource] of Object.entries(childTemplate.Resources)) {
+		if (resource.Type !== "AWS::CloudFormation::Stack") continue;
+		const assetPath = resource.Metadata?.["aws:asset:path"];
+		if (typeof assetPath !== "string" || assetPath.length === 0) continue;
+		if (path.isAbsolute(assetPath)) throw new Error(`cdkd import --migrate-from-cloudformation: grandchild nested-stack '${grandLogicalId}' has Metadata['aws:asset:path']='${assetPath}' which is absolute. CDK emits relative asset paths for nested templates.`);
+		result[grandLogicalId] = path.join(dir, assetPath);
+	}
+	return result;
+}
 
 //#endregion
 //#region src/cli/commands/local-state-loader.ts
@@ -55975,7 +56472,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.145.1");
+	program.name("cdkd").description("CDK Direct - Deploy AWS CDK apps directly via SDK/Cloud Control API").version("0.146.1");
 	program.addCommand(createBootstrapCommand());
 	program.addCommand(createSynthCommand());
 	program.addCommand(createListCommand());