@go-to-k/cdkd 0.134.0 → 0.135.0

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-EtWSTAje.js";
-import { $ as PartialFailureError, A as AssetPublisher, B as resolveStateBucketWithDefault, C as applyRoleArnIfSet, D as LockManager, E as TemplateParser, F as getDefaultStateBucketName, G as resolveBucketRegion, H as warnDeprecatedNoPrefixCliFlag, I as getLegacyStateBucketName, L as resolveApp, M as WorkGraph, N as buildDockerImage, O as S3StateBackend, P as Synthesizer, R as resolveCaptureObservedState, S as IntrinsicFunctionResolver, T as DagBuilder, U as AssemblyReader, V as resolveStateBucketWithDefaultAndSource, X as LocalInvokeBuildError, Z as LocalStartServiceError, _ as normalizeAwsTagsToCfn, a as withRetry, at as StackTerminationProtectionError, b as CloudControlProvider, c as cyan, d as red, dt as withErrorHandling, et as ProvisioningError, f as yellow, g as matchesCdkPath, h as CDK_PATH_TAG, i as withResourceDeadline, it as StackHasActiveImportsError, j as stringifyValue, k as shouldRetainResource, l as gray, m as collectInlinePolicyNamesManagedBySiblings, n as DEFAULT_RESOURCE_WARN_AFTER_MS, nt as ResourceUpdateNotSupportedError, o as IMPLICIT_DELETE_DEPENDENCIES, p as IAMRoleProvider, q as CdkdError, r as DeployEngine, rt as RouteDiscoveryError, s as bold, t as DEFAULT_RESOURCE_TIMEOUT_MS, tt as ResourceTimeoutError, u as green, ut as normalizeAwsError, v as resolveExplicitPhysicalId, w as DiffCalculator, x as assertRegionMatch, y as ProviderRegistry, z as resolveSkipPrefix } from "./deploy-engine-Dn7oV5rA.js";
+import { A as AssetPublisher, B as resolveStateBucketWithDefault, C as applyRoleArnIfSet, D as LockManager, E as TemplateParser, F as getDefaultStateBucketName, G as resolveBucketRegion, H as warnDeprecatedNoPrefixCliFlag, I as getLegacyStateBucketName, L as resolveApp, M as WorkGraph, N as buildDockerImage, O as S3StateBackend, P as Synthesizer, Q as LocalStartServiceError, R as resolveCaptureObservedState, S as IntrinsicFunctionResolver, T as DagBuilder, U as AssemblyReader, V as resolveStateBucketWithDefaultAndSource, X as LocalInvokeBuildError, Z as LocalMigrateError, _ as normalizeAwsTagsToCfn, a as withRetry, at as RouteDiscoveryError, b as CloudControlProvider, c as cyan, d as red, et as MissingCdkCliError, f as yellow, ft as normalizeAwsError, g as matchesCdkPath, h as CDK_PATH_TAG, i as withResourceDeadline, it as ResourceUpdateNotSupportedError, j as stringifyValue, k as shouldRetainResource, l as gray, m as collectInlinePolicyNamesManagedBySiblings, n as DEFAULT_RESOURCE_WARN_AFTER_MS, nt as ProvisioningError, o as IMPLICIT_DELETE_DEPENDENCIES, ot as StackHasActiveImportsError, p as IAMRoleProvider, pt as withErrorHandling, q as CdkdError, r as DeployEngine, rt as ResourceTimeoutError, s as bold, st as StackTerminationProtectionError, t as DEFAULT_RESOURCE_TIMEOUT_MS, tt as PartialFailureError, u as green, v as resolveExplicitPhysicalId, w as DiffCalculator, x as assertRegionMatch, y as ProviderRegistry, z as resolveSkipPrefix } from "./deploy-engine-CX1x5ug1.js";
 import { a as setAwsClients, i as resetAwsClients, r as getAwsClients, t as AwsClients } from "./aws-clients-BF03Alpe.js";
 import { createHash, createHmac, createPublicKey, createVerify, randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
 import { CopyObjectCommand, CreateBucketCommand, DeleteBucketAnalyticsConfigurationCommand, DeleteBucketCommand, DeleteBucketCorsCommand, DeleteBucketIntelligentTieringConfigurationCommand, DeleteBucketInventoryConfigurationCommand, DeleteBucketLifecycleCommand, DeleteBucketMetricsConfigurationCommand, DeleteBucketPolicyCommand, DeleteBucketReplicationCommand, DeleteBucketTaggingCommand, DeleteBucketWebsiteCommand, DeleteObjectCommand, DeleteObjectsCommand, GetBucketAccelerateConfigurationCommand, GetBucketCorsCommand, GetBucketEncryptionCommand, GetBucketLifecycleConfigurationCommand, GetBucketLocationCommand, GetBucketLoggingCommand, GetBucketNotificationConfigurationCommand, GetBucketPolicyCommand, GetBucketReplicationCommand, GetBucketTaggingCommand, GetBucketVersioningCommand, GetBucketWebsiteCommand, GetObjectCommand, GetObjectLockConfigurationCommand, GetPublicAccessBlockCommand, HeadBucketCommand, ListBucketAnalyticsConfigurationsCommand, ListBucketIntelligentTieringConfigurationsCommand, ListBucketInventoryConfigurationsCommand, ListBucketMetricsConfigurationsCommand, ListBucketsCommand, ListDirectoryBucketsCommand, ListObjectVersionsCommand, ListObjectsV2Command, NoSuchBucket, PutBucketAccelerateConfigurationCommand, PutBucketAnalyticsConfigurationCommand, PutBucketCorsCommand, PutBucketEncryptionCommand, PutBucketIntelligentTieringConfigurationCommand, PutBucketInventoryConfigurationCommand, PutBucketLifecycleConfigurationCommand, PutBucketLoggingCommand, PutBucketMetricsConfigurationCommand, PutBucketNotificationConfigurationCommand, PutBucketOwnershipControlsCommand, PutBucketPolicyCommand, PutBucketReplicationCommand, PutBucketTaggingCommand, PutBucketVersioningCommand, PutBucketWebsiteCommand, PutObjectCommand, PutObjectLockConfigurationCommand, PutPublicAccessBlockCommand, S3Client, S3ServiceException } from "@aws-sdk/client-s3";
@@ -20,7 +20,7 @@ import { CloudFrontClient, CreateCloudFrontOriginAccessIdentityCommand, CreateDi
 import { CloudWatchClient, DeleteAlarmsCommand, DescribeAlarmsCommand, ListTagsForResourceCommand as ListTagsForResourceCommand$4, PutMetricAlarmCommand, TagResourceCommand as TagResourceCommand$6, UntagResourceCommand as UntagResourceCommand$6 } from "@aws-sdk/client-cloudwatch";
 import { CloudWatchLogsClient, CreateLogGroupCommand, DeleteDataProtectionPolicyCommand, DeleteIndexPolicyCommand, DeleteLogGroupCommand, DeleteRetentionPolicyCommand, DescribeIndexPoliciesCommand, DescribeLogGroupsCommand, GetDataProtectionPolicyCommand, ListTagsForResourceCommand as ListTagsForResourceCommand$5, PutBearerTokenAuthenticationCommand, PutDataProtectionPolicyCommand, PutIndexPolicyCommand, PutLogGroupDeletionProtectionCommand, PutRetentionPolicyCommand, ResourceAlreadyExistsException, ResourceNotFoundException as ResourceNotFoundException$4, TagResourceCommand as TagResourceCommand$7, UntagResourceCommand as UntagResourceCommand$7 } from "@aws-sdk/client-cloudwatch-logs";
 import { BedrockAgentCoreControlClient, CreateAgentRuntimeCommand, DeleteAgentRuntimeCommand, GetAgentRuntimeCommand, ResourceNotFoundException as ResourceNotFoundException$5, UpdateAgentRuntimeCommand } from "@aws-sdk/client-bedrock-agentcore-control";
-import { cpSync, createWriteStream, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { cpSync, createWriteStream, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
 import * as path from "node:path";
 import { dirname, isAbsolute, join, normalize, resolve } from "node:path";
 import { execFile, spawn } from "node:child_process";
@@ -35304,10 +35304,15 @@ async function retireCloudFormationStack(options) {
 			logger.info(`[3/4] Updating CloudFormation stack with Retain policies...`);
 			let updateRan = false;
 			try {
+				const previousParameters = (stack.Parameters ?? []).map((p) => ({
+					ParameterKey: p.ParameterKey,
+					UsePreviousValue: true
+				}));
 				await cfnClient.send(new UpdateStackCommand({
 					StackName: cfnStackName,
 					...updateInput,
-					Capabilities: capabilities
+					Capabilities: capabilities,
+					...previousParameters.length > 0 && { Parameters: previousParameters }
 				}));
 				updateRan = true;
 			} catch (err) {
@@ -35448,6 +35453,9 @@ async function confirmPrompt$2(prompt) {
 
 //#endregion
 //#region src/cli/commands/import.ts
+async function runImport(stackArg, options) {
+	return importCommand(stackArg, options);
+}
 async function importCommand(stackArg, options) {
 	const logger = getLogger();
 	if (options.verbose) {
@@ -38761,7 +38769,7 @@ function resolveRuntimeCodeMountPath(runtime) {
 
 //#endregion
 //#region src/local/docker-runner.ts
-const execFileAsync$2 = promisify(execFile);
+const execFileAsync$3 = promisify(execFile);
 /**
 * Wraps `docker pull` / `docker run` / `docker rm` for `cdkd local invoke`.
 *
@@ -38853,7 +38861,7 @@ async function runDetached(opts) {
 	args.push(opts.image, ...entryPointTail, ...opts.cmd);
 	getLogger().child("docker").debug(`${getDockerCmd()} ${redactAwsCredentialsInArgs(args).join(" ")}`);
 	try {
-		const { stdout } = await execFileAsync$2(getDockerCmd(), args, { maxBuffer: 10 * 1024 * 1024 });
+		const { stdout } = await execFileAsync$3(getDockerCmd(), args, { maxBuffer: 10 * 1024 * 1024 });
 		return stdout.trim();
 	} catch (error) {
 		const err = error;
@@ -38890,7 +38898,7 @@ async function removeContainer(containerId) {
 	if (!containerId) return;
 	const logger = getLogger().child("docker");
 	try {
-		await execFileAsync$2(getDockerCmd(), [
+		await execFileAsync$3(getDockerCmd(), [
 			"rm",
 			"-f",
 			containerId
@@ -38909,7 +38917,7 @@ async function removeContainer(containerId) {
 async function ensureDockerAvailable() {
 	const cmd = getDockerCmd();
 	try {
-		await execFileAsync$2(cmd, [
+		await execFileAsync$3(cmd, [
 			"version",
 			"--format",
 			"{{.Server.Version}}"
@@ -48052,7 +48060,7 @@ function createLocalStartApiCommand() {
 
 //#endregion
 //#region src/local/ecs-network.ts
-const execFileAsync$1 = promisify(execFile);
+const execFileAsync$2 = promisify(execFile);
 /**
 * Docker network + AWS-published metadata-endpoints sidecar lifecycle for
 * `cdkd local run-task`. The sidecar (a small Go binary maintained by
@@ -48115,7 +48123,7 @@ async function createTaskNetwork(options = {}) {
 	await pullImage(METADATA_ENDPOINT_IMAGE, options.skipPull ?? false);
 	logger.info(`Creating docker network ${networkName} (subnet ${cidr})...`);
 	try {
-		await execFileAsync$1(getDockerCmd(), [
+		await execFileAsync$2(getDockerCmd(), [
 			"network",
 			"create",
 			"--driver",
@@ -48151,7 +48159,7 @@ async function createTaskNetwork(options = {}) {
 	logger.info(`Starting ECS local-container-endpoints sidecar at ${sidecarIp}...`);
 	let sidecarContainerId;
 	try {
-		const { stdout } = await execFileAsync$1(getDockerCmd(), sidecarArgs, { maxBuffer: 10 * 1024 * 1024 });
+		const { stdout } = await execFileAsync$2(getDockerCmd(), sidecarArgs, { maxBuffer: 10 * 1024 * 1024 });
 		sidecarContainerId = stdout.trim();
 	} catch (err) {
 		await destroyNetworkOnly(networkName);
@@ -48199,7 +48207,7 @@ async function destroyNetworkOnly(networkName) {
 	if (!networkName) return;
 	const logger = getLogger().child("ecs-network");
 	try {
-		await execFileAsync$1(getDockerCmd(), [
+		await execFileAsync$2(getDockerCmd(), [
 			"network",
 			"rm",
 			networkName
@@ -48332,7 +48340,7 @@ async function resolveSsm(entry, shape, client) {
 
 //#endregion
 //#region src/local/ecs-task-runner.ts
-const execFileAsync = promisify(execFile);
+const execFileAsync$1 = promisify(execFile);
 /**
 * Top-level orchestrator for `cdkd local run-task`. Coordinates image
 * preparation, secret resolution, docker-network bring-up, container
@@ -48392,7 +48400,7 @@ async function cleanupEcsRun(state, options) {
 	await destroyTaskNetwork(state.network);
 	state.network = void 0;
 	for (const v of state.dockerVolumeNames) try {
-		await execFileAsync(getDockerCmd(), [
+		await execFileAsync$1(getDockerCmd(), [
 			"volume",
 			"rm",
 			v
@@ -48458,7 +48466,7 @@ async function runEcsTask(task, options, state) {
 		logger.info(`Starting container '${container.name}' (image=${imagePlan.get(container.name)})`);
 		let id;
 		try {
-			const { stdout } = await execFileAsync(getDockerCmd(), args, { maxBuffer: 10 * 1024 * 1024 });
+			const { stdout } = await execFileAsync$1(getDockerCmd(), args, { maxBuffer: 10 * 1024 * 1024 });
 			id = stdout.trim();
 		} catch (err) {
 			const e = err;
@@ -48567,7 +48575,7 @@ async function waitForContainerHealthy(containerId, displayName) {
 	let lastStatus = "";
 	while (Date.now() < deadline) {
 		try {
-			const { stdout } = await execFileAsync(getDockerCmd(), [
+			const { stdout } = await execFileAsync$1(getDockerCmd(), [
 				"inspect",
 				"--format",
 				"{{.State.Health.Status}}",
@@ -48590,7 +48598,7 @@ async function waitForContainerHealthy(containerId, displayName) {
 }
 async function waitForContainerExit(containerId) {
 	try {
-		const { stdout } = await execFileAsync(getDockerCmd(), ["wait", containerId], { maxBuffer: 1024 * 1024 });
+		const { stdout } = await execFileAsync$1(getDockerCmd(), ["wait", containerId], { maxBuffer: 1024 * 1024 });
 		const code = Number.parseInt(stdout.trim(), 10);
 		return Number.isFinite(code) ? code : 1;
 	} catch (err) {
@@ -48600,7 +48608,7 @@ async function waitForContainerExit(containerId) {
 }
 async function stopContainer(containerId, graceSeconds) {
 	try {
-		await execFileAsync(getDockerCmd(), [
+		await execFileAsync$1(getDockerCmd(), [
 			"stop",
 			"-t",
 			String(graceSeconds),
@@ -48725,7 +48733,7 @@ async function realizeDockerVolumes(volumes, state) {
 		const dockerVolumeName = `cdkd-local-${v.name}-${randHex(4)}`;
 		args.push(dockerVolumeName);
 		try {
-			await execFileAsync(getDockerCmd(), args);
+			await execFileAsync$1(getDockerCmd(), args);
 			state.dockerVolumeNames.push(dockerVolumeName);
 			logger.debug(`Created docker volume ${dockerVolumeName} for task volume '${v.name}'`);
 		} catch (err) {
@@ -51859,6 +51867,1069 @@ function createExportCommand() {
 	return cmd;
 }
 
+//#endregion
+//#region src/cli/commands/migrate/cdk-cli-check.ts
+const execFileAsync = promisify(execFile);
+/**
+* Minimum aws-cdk CLI version where `cdk migrate --from-stack` is
+* considered stable (per the design doc at docs/design/465-cfn-migrate.md
+* §4 — "Version requirement"). Below this we WARN but do not block,
+* because users may have a working older release and a hard rejection
+* would be more disruptive than a warning.
+*/
+const RECOMMENDED_MIN_VERSION = "2.124.0";
+/**
+* Verify that the upstream `cdk` CLI is available on PATH (or at the
+* override path passed via `--cdk-bin`) and report its version.
+*
+* Hard-errors with {@link MissingCdkCliError} when `cdk` cannot be
+* spawned (ENOENT, permission denied, etc.). Emits a `warn` field on
+* the result when the version string is below the recommended minimum
+* — the caller decides how to surface it.
+*
+* `cdk --version` output format empirically (verified 2026-05-22
+* against cdk@2.1112.0): `<MAJOR.MINOR.PATCH> (build <id>)`. The
+* version is the first whitespace-separated token; the trailing
+* `(build <id>)` is informational and ignored.
+*
+* @param cdkBinPath - Path to the `cdk` binary. Defaults to `'cdk'`
+*   which uses the system PATH for resolution.
+*/
+async function verifyCdkCliAvailable(cdkBinPath = "cdk") {
+	let stdout;
+	try {
+		stdout = (await execFileAsync(cdkBinPath, ["--version"])).stdout ?? "";
+	} catch (err) {
+		throw new MissingCdkCliError(`Failed to run '${cdkBinPath} --version': ${err instanceof Error ? err.message : String(err)}`, err instanceof Error ? err : void 0);
+	}
+	const version = parseCdkVersion(stdout);
+	if (!version) throw new MissingCdkCliError(`'${cdkBinPath} --version' produced unexpected output: ${JSON.stringify(stdout.trim())}`);
+	if (compareSemver(version, RECOMMENDED_MIN_VERSION) < 0) return {
+		version,
+		warn: `cdk CLI version ${version} is older than the recommended minimum ${RECOMMENDED_MIN_VERSION}. 'cdkd migrate' relies on the stabilized 'cdk migrate --from-stack' flag; upgrade with 'npm install -g aws-cdk@latest' if you hit codegen issues.`
+	};
+	return { version };
+}
+/**
+* Parse the first semver-shaped token (`<MAJOR>.<MINOR>.<PATCH>`) out of
+* `cdk --version` stdout. Tolerates a trailing `(build <id>)` suffix.
+*
+* Returns `undefined` when no semver-shaped token is present so the
+* caller can surface the raw stdout in the error message.
+*/
+function parseCdkVersion(stdout) {
+	const match = stdout.match(/(\d+)\.(\d+)\.(\d+)/);
+	if (!match) return void 0;
+	return `${match[1]}.${match[2]}.${match[3]}`;
+}
+/**
+* Compare two semver strings (`MAJOR.MINOR.PATCH`). Returns a negative
+* number when `a < b`, zero when `a === b`, positive when `a > b`.
+*
+* Strictly numeric comparison per component — no pre-release / build
+* suffix handling needed for this use case (`cdk --version` always
+* emits a stable `X.Y.Z` triple).
+*/
+function compareSemver(a, b) {
+	const aParts = a.split(".").map((n) => Number.parseInt(n, 10));
+	const bParts = b.split(".").map((n) => Number.parseInt(n, 10));
+	for (let i = 0; i < 3; i++) {
+		const aN = aParts[i] ?? 0;
+		const bN = bParts[i] ?? 0;
+		if (aN !== bN) return aN - bN;
+	}
+	return 0;
+}
+
+//#endregion
+//#region src/cli/commands/migrate/cfn-stack-prefetch.ts
+/**
+* Resource types that `cdkd migrate` refuses to adopt under any
+* circumstances. The rationale per type:
+*
+*  - `AWS::CloudFormation::CustomResource` — Lambda-backed Custom
+*    Resources whose response protocol (cfn-response over a
+*    pre-signed S3 URL) is incompatible with cdkd's import flow. The
+*    backing Lambda's onCreate handler would need to be re-invoked
+*    for a cdkd-side adoption to make sense, and that's structurally
+*    different from the metadata-transfer migration this command
+*    provides.
+*
+*  - `AWS::CloudFormation::Stack` — nested stacks. cdkd has no
+*    provider for this type, and the matching `cdk migrate` output
+*    flattens nested stacks into separate generated apps in a way
+*    that doesn't round-trip cleanly. Out of scope for #465.
+*
+*  - `Custom::*` — any user-defined Custom Resource type prefix.
+*    Same rationale as `AWS::CloudFormation::CustomResource`.
+*/
+const HARD_REJECT_RESOURCE_TYPES = new Set(["AWS::CloudFormation::CustomResource", "AWS::CloudFormation::Stack"]);
+/**
+* Fetch the source CFn stack's current state + resources + transform
+* info. Issues 3 read-only AWS API calls (`DescribeStacks`,
+* `DescribeStackResources`, `GetTemplate(Stage=Original)`); none of
+* them mutate AWS state. The result is fed into
+* {@link validatePrefetchResult} for the hard-reject check and
+* surfaced to {@link runMigrateLibrary}'s caller (PR B) as part of
+* `RunMigrateLibraryResult`.
+*
+* `DescribeStackResources` is preferred over `ListStackResources`
+* because the response is unpaginated up to 500 resources (CFn's hard
+* stack cap) — no pagination loop needed for the migration use case.
+*/
+async function prefetchCfnStack(stackName, cfnClient) {
+	const stack = (await cfnClient.send(new DescribeStacksCommand({ StackName: stackName }))).Stacks?.[0];
+	if (!stack) throw new LocalMigrateError(`CloudFormation stack '${stackName}' not found.`);
+	const stackStatus = stack.StackStatus ?? "";
+	const resourcesResp = await cfnClient.send(new DescribeStackResourcesCommand({ StackName: stackName }));
+	const resources = [];
+	for (const r of resourcesResp.StackResources ?? []) {
+		if (!r.LogicalResourceId || !r.PhysicalResourceId || !r.ResourceType) continue;
+		resources.push({
+			LogicalResourceId: r.LogicalResourceId,
+			PhysicalResourceId: r.PhysicalResourceId,
+			ResourceType: r.ResourceType
+		});
+	}
+	let transformInfo = {
+		hasSamTransform: false,
+		hasIncludeTransform: false
+	};
+	let sourceCfnTemplate = null;
+	try {
+		const tplResp = await cfnClient.send(new GetTemplateCommand({
+			StackName: stackName,
+			TemplateStage: "Original"
+		}));
+		if (tplResp.TemplateBody) {
+			try {
+				sourceCfnTemplate = parseCfnTemplate(tplResp.TemplateBody);
+			} catch {
+				sourceCfnTemplate = null;
+			}
+			transformInfo = detectTransformsFromParsed(sourceCfnTemplate);
+		}
+	} catch (err) {
+		const detail = err instanceof Error ? err.message : String(err);
+		getLogger().warn(`[migrate] GetTemplate failed for '${stackName}': ${detail}. Skipping transform detection.`);
+	}
+	return {
+		stackStatus,
+		resources,
+		transformInfo,
+		sourceCfnTemplate
+	};
+}
+/**
+* Pre-flight reject when the source CFn stack contains any
+* un-migratable resource type OR is in a non-terminal state. Surfaces
+* SAM / Include transforms via the result's `transformInfo` instead —
+* the caller is responsible for emitting INFO logs.
+*
+* Per #465 Q2 (parent-session decision): every hard-reject case
+* routes the user to the standalone `cdk migrate --from-stack <name>
+* --output-dir ./tmp` flow so they can manually inspect the generated
+* code and decide how to proceed (e.g. delete the Custom Resource
+* from the source CFn stack before re-running cdkd migrate).
+*/
+function validatePrefetchResult(result) {
+	if (!STABLE_TERMINAL_STATUSES.has(result.stackStatus)) throw new LocalMigrateError(`CloudFormation stack is in status '${result.stackStatus}', which is not a stable terminal state. Wait for the stack to settle (or roll back) before running 'cdkd migrate'.`);
+	const offenders = [];
+	for (const r of result.resources) if (isHardRejectType(r.ResourceType)) offenders.push({
+		LogicalResourceId: r.LogicalResourceId,
+		ResourceType: r.ResourceType
+	});
+	if (offenders.length === 0) return;
+	throw new LocalMigrateError(`Source CloudFormation stack contains resource types that 'cdkd migrate' cannot adopt:\n${offenders.map((o) => `  - ${o.LogicalResourceId} (${o.ResourceType})`).join("\n")}\n\nLambda-backed Custom Resources and nested CloudFormation stacks are out of scope for #465.\nTo migrate the rest of the stack, either:\n  1. Delete the unsupported resources from the source CFn stack first, OR\n  2. Run upstream 'cdk migrate' standalone to inspect the generated code:\n       cdk migrate --from-stack --stack-name <source-stack> --output-path ./tmp\n     then hand-author CDK constructs to replace the Custom Resource semantics.`);
+}
+/**
+* Whether the given resource type is in the hard-reject set. Matches
+* literal types from {@link HARD_REJECT_RESOURCE_TYPES} AND the
+* `Custom::*` prefix pattern (user-defined Custom Resource types).
+*/
+function isHardRejectType(resourceType) {
+	if (HARD_REJECT_RESOURCE_TYPES.has(resourceType)) return true;
+	if (resourceType.startsWith("Custom::")) return true;
+	return false;
+}
+/**
+* Scan an already-parsed CFn template object for stack-level
+* Transform blocks. Accepts both the scalar form (`Transform:
+* AWS::Serverless-2016-10-31`) and the array form (`Transform:
+* [AWS::Serverless-2016-10-31, ...]`).
+*
+* The caller is responsible for parsing the raw template body via the
+* CFn-aware codec; this helper operates on the parsed object so the
+* `GetTemplate` response can be parsed once and reused.
+*/
+function detectTransformsFromParsed(parsed) {
+	if (!parsed || typeof parsed !== "object") return {
+		hasSamTransform: false,
+		hasIncludeTransform: false
+	};
+	const transformRaw = parsed["Transform"];
+	const transforms = Array.isArray(transformRaw) ? transformRaw.map((t) => String(t)) : typeof transformRaw === "string" ? [transformRaw] : [];
+	return {
+		hasSamTransform: transforms.some((t) => t.startsWith("AWS::Serverless")),
+		hasIncludeTransform: transforms.some((t) => t === "AWS::Include" || t.startsWith("AWS::Include"))
+	};
+}
+
+//#endregion
+//#region src/cli/commands/migrate/output-dir-guard.ts
+/**
+* Refuse to run `cdkd migrate` when the upstream `cdk migrate` would
+* write its output into an existing non-empty directory. `cdk migrate`
+* itself silently overwrites in that case; cdkd surfaces the collision
+* up-front with the exact recovery command so the user is not left
+* with a half-overwritten CDK app.
+*
+* Behavior matrix (`outputPath = <user-supplied dir>`, `stackName =
+* <CFn stack name>`; cdk writes to `<outputPath>/<stackName>`):
+*  - target dir does not exist                      → OK
+*  - target dir exists but is empty                 → OK (treated as fresh)
+*  - target path is a file, not a directory         → typed error
+*  - target dir exists and contains entries         → typed error with
+*                                                    the canonical
+*                                                    `rm -rf` recovery
+*                                                    command in the
+*                                                    message
+*
+* The parent `outputPath` is NOT checked — `cdk migrate` creates
+* `<outputPath>` itself if missing, so a non-existent parent is fine.
+*/
+function assertOutputDirAvailable(outputPath, stackName) {
+	const targetDir = resolve(outputPath, stackName);
+	if (!existsSync(targetDir)) return;
+	if (!statSync(targetDir).isDirectory()) throw new LocalMigrateError(`Output path '${targetDir}' exists but is not a directory. Remove it (or pass --output-dir <NEW_PATH>) and retry:\n  rm -f ${targetDir} && cdkd migrate --from-cfn-stack ${stackName}`);
+	const entries = readdirSync(targetDir);
+	if (entries.length === 0) return;
+	throw new LocalMigrateError(`Output dir '${targetDir}' already exists and is non-empty (e.g. '${join(targetDir, entries[0])}'); remove it or pass --output-dir <NEW_PATH>:\n  rm -rf ${targetDir} && cdkd migrate --from-cfn-stack ${stackName}`);
+}
+
+//#endregion
+//#region src/cli/commands/migrate/cdk-migrate-spawn.ts
+/**
+* Spawn `cdk migrate --from-stack` as a subprocess and stream its
+* output through cdkd's logger.
+*
+* Why subprocess (not Node module import): the upstream `cdk` CLI is
+* a bundled CommonJS app with no stable public API; pinning a
+* runtime-injected `aws-cdk-lib` from cdkd is impractical. Subprocess
+* isolation also gives us a clean failure boundary — non-zero exit
+* surfaces as {@link LocalMigrateError} with the captured streams
+* folded into the error message.
+*
+* Streaming is preferred over a buffered `execFile` because `cdk
+* migrate` emits progress lines (downloading the resource schema,
+* synthesizing the L1 code for each resource) that users expect to
+* see in real time. Captured streams are still returned for caller
+* inspection.
+*/
+async function spawnCdkMigrate(opts) {
+	const logger = getLogger();
+	const cdkBin = opts.cdkBinPath ?? "cdk";
+	const language = opts.language ?? "typescript";
+	const outputDir = resolve(opts.outputPath, opts.stackName);
+	const args = [
+		"migrate",
+		"--from-stack",
+		"--stack-name",
+		opts.fromStackName,
+		"--output-path",
+		opts.outputPath,
+		"--language",
+		language
+	];
+	if (opts.region) args.push("--region", opts.region);
+	if (opts.account) args.push("--account", opts.account);
+	if (opts.profile) args.push("--profile", opts.profile);
+	for (const filter of opts.filters ?? []) args.push("--filter", filter);
+	const env = {
+		...process.env,
+		...opts.extraEnv ?? {}
+	};
+	logger.info(`[cdk-migrate] ${cdkBin} ${args.join(" ")}`);
+	return await new Promise((resolvePromise, rejectPromise) => {
+		let stdout = "";
+		let stderr = "";
+		let child;
+		try {
+			child = spawn(cdkBin, args, {
+				env,
+				stdio: [
+					"ignore",
+					"pipe",
+					"pipe"
+				]
+			});
+		} catch (err) {
+			rejectPromise(new LocalMigrateError(`Failed to spawn '${cdkBin} migrate': ${err instanceof Error ? err.message : String(err)}`, err instanceof Error ? err : void 0));
+			return;
+		}
+		child.stdout?.on("data", (chunk) => {
+			const text = chunk.toString("utf-8");
+			stdout += text;
+			const trimmed = text.replace(/\n$/, "");
+			if (trimmed) logger.info(`[cdk-migrate] ${trimmed}`);
+		});
+		child.stderr?.on("data", (chunk) => {
+			const text = chunk.toString("utf-8");
+			stderr += text;
+			const trimmed = text.replace(/\n$/, "");
+			if (trimmed) logger.warn(`[cdk-migrate] ${trimmed}`);
+		});
+		child.on("error", (err) => {
+			rejectPromise(new LocalMigrateError(`'${cdkBin} migrate' subprocess error: ${err.message}`, err));
+		});
+		child.on("close", (code, signal) => {
+			if (code === 0) {
+				resolvePromise({
+					outputDir,
+					stdout,
+					stderr
+				});
+				return;
+			}
+			rejectPromise(new LocalMigrateError(`'${cdkBin} migrate' ${signal !== null ? `killed by signal ${signal}` : code !== null ? `exited with code ${code}` : "process closed without a code or signal"}.\n--- stdout ---\n${stdout || "(empty)"}\n--- stderr ---\n${stderr || "(empty)"}\n`));
+		});
+	});
+}
+
+//#endregion
+//#region src/cli/commands/migrate/synth-after-migrate.ts
+/**
+* Run `npm install` inside the generated CDK app directory so the
+* `cdk synth` step (which dynamically loads `aws-cdk-lib`) has its
+* dependencies in place.
+*
+* Skippable via `skipInstall: true` — CI users with a pre-populated
+* node_modules cache can save the ~30s `npm install` round-trip.
+*
+* Streams stdout / stderr through cdkd's logger so users see progress
+* for the often-slow npm step. Non-zero exit surfaces as a typed
+* {@link LocalMigrateError} with the captured streams folded into
+* the error message.
+*/
+async function installGeneratedAppDeps(outputDir, opts) {
+	const logger = getLogger();
+	if (opts.skipInstall) {
+		logger.info(`[cdk-migrate] Skipping 'npm install' (--skip-install).`);
+		return;
+	}
+	const absDir = resolve(outputDir);
+	if (!existsSync(absDir)) throw new LocalMigrateError(`Generated app directory '${absDir}' does not exist; cannot run 'npm install'.`);
+	logger.info(`[cdk-migrate] Running 'npm install' in ${absDir}...`);
+	await runStreamingCommand("npm", ["install"], absDir, opts.extraEnv ? {
+		...process.env,
+		...opts.extraEnv
+	} : void 0, "npm install");
+}
+/**
+* Run `cdk synth --quiet` inside the generated CDK app directory and
+* return both the assembly dir path and the parsed root-stack
+* template.
+*
+* `--quiet` suppresses the noisy template echo that `cdk synth`
+* defaults to on stdout — we read the template from disk
+* (`cdk.out/<StackName>.template.json`) instead.
+*
+* Skippable via `skipSynth: true` — useful when PR B's orchestrator
+* needs the codegen output without running synth (e.g. preview /
+* dry-run modes).
+*/
+async function synthGeneratedApp(outputDir, opts) {
+	const logger = getLogger();
+	const absDir = resolve(outputDir);
+	const assemblyDir = join(absDir, "cdk.out");
+	if (opts.skipSynth) {
+		logger.info(`[cdk-migrate] Skipping 'cdk synth' (--skip-synth).`);
+		return {
+			assemblyDir,
+			templateBody: null
+		};
+	}
+	if (!existsSync(absDir)) throw new LocalMigrateError(`Generated app directory '${absDir}' does not exist; cannot run 'cdk synth'.`);
+	const cdkBin = opts.cdkBinPath ?? "cdk";
+	const env = {
+		...process.env,
+		...opts.extraEnv ?? {}
+	};
+	logger.info(`[cdk-migrate] Running '${cdkBin} synth --quiet' in ${absDir}...`);
+	await runStreamingCommand(cdkBin, ["synth", "--quiet"], absDir, env, `${cdkBin} synth`);
+	if (!existsSync(assemblyDir)) throw new LocalMigrateError(`'cdk synth' completed but produced no '${assemblyDir}' directory.`);
+	const templates = readdirSync(assemblyDir).filter((f) => f.endsWith(".template.json"));
+	if (templates.length === 0) return {
+		assemblyDir,
+		templateBody: null
+	};
+	const templatePath = join(assemblyDir, templates[0]);
+	let templateBody;
+	try {
+		const raw = readFileSync(templatePath, "utf-8");
+		templateBody = JSON.parse(raw);
+	} catch (err) {
+		throw new LocalMigrateError(`Failed to parse generated template '${templatePath}': ${err instanceof Error ? err.message : String(err)}`, err instanceof Error ? err : void 0);
+	}
+	return {
+		assemblyDir,
+		templateBody
+	};
+}
+/**
+* Helper — spawn a subprocess in the given working directory, stream
+* its output through cdkd's logger, and reject with a typed
+* {@link LocalMigrateError} on non-zero exit.
+*
+* Factored out so the `npm install` and `cdk synth` call sites use the
+* same shape; both expose progress to the user and surface failures
+* with the captured streams.
+*/
+async function runStreamingCommand(bin, args, cwd, env, label) {
+	const logger = getLogger();
+	return await new Promise((resolvePromise, rejectPromise) => {
+		let stdout = "";
+		let stderr = "";
+		let child;
+		try {
+			child = spawn(bin, args, {
+				cwd,
+				env: env ?? process.env,
+				stdio: [
+					"ignore",
+					"pipe",
+					"pipe"
+				]
+			});
+		} catch (err) {
+			rejectPromise(new LocalMigrateError(`Failed to spawn ${label}: ${err instanceof Error ? err.message : String(err)}`, err instanceof Error ? err : void 0));
+			return;
+		}
+		child.stdout?.on("data", (chunk) => {
+			const text = chunk.toString("utf-8");
+			stdout += text;
+			const trimmed = text.replace(/\n$/, "");
+			if (trimmed) logger.info(`[${label}] ${trimmed}`);
+		});
+		child.stderr?.on("data", (chunk) => {
+			const text = chunk.toString("utf-8");
+			stderr += text;
+			const trimmed = text.replace(/\n$/, "");
+			if (trimmed) logger.warn(`[${label}] ${trimmed}`);
+		});
+		child.on("error", (err) => {
+			rejectPromise(new LocalMigrateError(`${label} subprocess error: ${err.message}`, err));
+		});
+		child.on("close", (code, signal) => {
+			if (code === 0) {
+				resolvePromise();
+				return;
+			}
+			rejectPromise(new LocalMigrateError(`${label} ${signal !== null ? `killed by signal ${signal}` : code !== null ? `exited with code ${code}` : "process closed without a code or signal"}.\n--- stdout ---\n${stdout || "(empty)"}\n--- stderr ---\n${stderr || "(empty)"}\n`));
+		});
+	});
+}
+
+//#endregion
+//#region src/cli/commands/migrate/index.ts
+/**
+* Build an extra-env bag for subprocesses (`npm install`, `cdk synth`)
+* so they inherit the AWS profile the caller selected via `--profile`.
+*
+* Without this, `cdk synth` falls back to the SDK default credential
+* chain (or no credentials at all) when the user runs cdkd under a
+* non-default profile — which silently produces a template synthesized
+* against the wrong account / region context.
+*/
+function buildAwsEnv(opts) {
+	return opts.profile ? { AWS_PROFILE: opts.profile } : {};
+}
+/**
+* PR A library entry point — orchestrates the codegen + synth half of
+* `cdkd migrate --from-cfn-stack` without writing cdkd state, running
+* import, or touching the source CFn stack.
+*
+* Flow:
+*   1. `verifyCdkCliAvailable` — hard-fail if `cdk` is missing.
+*   2. `prefetchCfnStack` — read source stack state + resources +
+*      transform info.
+*   3. `validatePrefetchResult` — reject CR / nested-stack / non-
+*      terminal state; INFO log SAM / Include transforms.
+*   4. `assertOutputDirAvailable` — refuse pre-existing non-empty
+*      output dir.
+*   5. `spawnCdkMigrate` — run `cdk migrate --from-stack` subprocess.
+*   6. `installGeneratedAppDeps` (gated by `skipInstall`).
+*   7. `synthGeneratedApp` (gated by `skipSynth`).
+*   8. Return every artifact PR B will consume.
+*
+* Per #465 Q4 (parent-session decision): PR A is library-only. The CLI
+* command (`cdkd migrate`), state writes, retire flow, and resource-
+* mapping algorithm all live in PR B.
+*/
+async function runMigrateLibrary(opts) {
+	const logger = getLogger();
+	const stackName = opts.fromCfnStack;
+	const outputPath = opts.outputDir ?? resolve(process.cwd(), stackName);
+	logger.info(`[migrate] Verifying upstream 'cdk' CLI...`);
+	const cliCheck = await verifyCdkCliAvailable(opts.cdkBinPath);
+	logger.info(`[migrate] Using cdk CLI v${cliCheck.version}`);
+	if (cliCheck.warn) logger.warn(`[migrate] ${cliCheck.warn}`);
+	logger.info(`[migrate] Pre-fetching CloudFormation stack '${stackName}'...`);
+	const cfnClient = buildCfnClient(opts);
+	let prefetch;
+	try {
+		prefetch = await prefetchCfnStack(stackName, cfnClient);
+	} finally {
+		cfnClient.destroy?.();
+	}
+	validatePrefetchResult(prefetch);
+	if (prefetch.transformInfo.hasSamTransform) logger.info("[migrate] INFO: source CFn stack uses 'AWS::Serverless' transform; cdk migrate will expand it client-side and the generated CDK code will use plain Lambda + API Gateway L1 constructs (not SAM).");
+	if (prefetch.transformInfo.hasIncludeTransform) logger.info("[migrate] INFO: source CFn stack uses 'AWS::Include' transform; cdk migrate will expand it client-side and the generated CDK code will inline the included template content.");
+	assertOutputDirAvailable(outputPath, stackName);
+	const spawnResult = await spawnCdkMigrate({
+		stackName,
+		fromStackName: stackName,
+		outputPath,
+		...opts.language && { language: opts.language },
+		...opts.region && { region: opts.region },
+		...opts.account && { account: opts.account },
+		...opts.filters && { filters: opts.filters },
+		...opts.profile && { profile: opts.profile },
+		...opts.cdkBinPath && { cdkBinPath: opts.cdkBinPath }
+	});
+	await installGeneratedAppDeps(spawnResult.outputDir, {
+		skipInstall: opts.skipInstall ?? false,
+		extraEnv: buildAwsEnv(opts)
+	});
+	const synthResult = await synthGeneratedApp(spawnResult.outputDir, {
+		skipSynth: opts.skipSynth ?? false,
+		...opts.cdkBinPath && { cdkBinPath: opts.cdkBinPath },
+		extraEnv: buildAwsEnv(opts)
+	});
+	if (prefetch.sourceCfnTemplate === null) throw new LocalMigrateError(`Could not read the source CloudFormation template for '${stackName}' (GetTemplate failed during pre-flight). Re-run after granting cloudformation:GetTemplate on the stack, or check the earlier warning for details.`);
+	return {
+		outputDir: spawnResult.outputDir,
+		assemblyDir: synthResult.assemblyDir,
+		templateBody: synthResult.templateBody,
+		sourceCfnTemplate: prefetch.sourceCfnTemplate,
+		sourceResources: prefetch.resources
+	};
+}
+/**
+* Build a CloudFormation client using cdkd's shared {@link AwsClients}
+* factory so the credential chain matches every other cdkd command.
+*
+* Keeping the construction in one place makes the per-command CFn-
+* client recipe a single readable hook for future plumbing (e.g.
+* threading PR B's `--role-arn` STS-assume).
+*/
+function buildCfnClient(opts) {
+	const config = {};
+	if (opts.region) config.region = opts.region;
+	if (opts.profile) config.profile = opts.profile;
+	return new AwsClients(config).getCloudFormationClient();
+}
+
+//#endregion
+//#region src/cli/commands/migrate/resource-mapper.ts
+/**
+* Run the 2-pass mapping algorithm against `(sourceCfnTemplate,
+* synthTemplate, sourceResources)` and return the resolved mapping plus
+* any unmatched entries.
+*
+* Pure-functional: no AWS calls, no I/O, no mutation of inputs. Safe to
+* call repeatedly in tests against shared fixtures.
+*
+* Throws when an override references a synth id that does not exist —
+* this is a user error in the hand-edited mapping JSON and surfacing
+* the available synth ids in the message is the path back to a working
+* config.
+*/
+function buildResourceMapping(opts) {
+	const sourceEntries = extractSourceResources(opts.sourceCfnTemplate);
+	const synthEntries = extractSynthResources(opts.synthTemplate);
+	const physicalIdByLogicalId = /* @__PURE__ */ new Map();
+	for (const r of opts.sourceResources) physicalIdByLogicalId.set(r.LogicalResourceId, r.PhysicalResourceId);
+	const overrides = opts.overrides ?? {};
+	const synthLogicalIds = new Set(synthEntries.map((s) => s.logicalId));
+	for (const [srcId, synthId] of Object.entries(overrides)) if (!synthLogicalIds.has(synthId)) throw new Error(`Resource-mapping override targets synth logical id '${synthId}' (for source id '${srcId}'), but that id is not in the synthesized template. Available synth ids: ${[...synthLogicalIds].sort().join(", ")}`);
+	const missingPhysicalIds = [];
+	for (const src of sourceEntries) if (!physicalIdByLogicalId.has(src.logicalId)) missingPhysicalIds.push(`  - ${src.logicalId} (${src.type})`);
+	if (missingPhysicalIds.length > 0) throw new Error(`Source CFn resource(s) not returned by DescribeStackResources — cannot migrate:\n${missingPhysicalIds.join("\n")}\n\nThe stack may have been mid-operation; wait for it to settle (CREATE_COMPLETE / UPDATE_COMPLETE / etc.) and retry.`);
+	const synthByLastPathSegment = indexSynthByLastPathSegment(synthEntries);
+	const synthByLogicalId = new Map(synthEntries.map((s) => [s.logicalId, s]));
+	const claimedSynthIds = /* @__PURE__ */ new Set();
+	const pairs = [];
+	const unmatched = [];
+	const sourcesHandledByOverride = /* @__PURE__ */ new Set();
+	for (const [srcId, synthId] of Object.entries(overrides)) {
+		const src = sourceEntries.find((e) => e.logicalId === srcId);
+		if (!src) {
+			const availableSrc = sourceEntries.map((e) => e.logicalId).sort();
+			throw new Error(`Resource-mapping override references source logical id '${srcId}', but no resource with that id exists in the source CloudFormation template. Available source ids: ${availableSrc.join(", ")}`);
+		}
+		const synth = synthByLogicalId.get(synthId);
+		if (!synth) continue;
+		const physicalId = physicalIdByLogicalId.get(src.logicalId);
+		pairs.push({
+			sourceLogicalId: src.logicalId,
+			synthLogicalId: synth.logicalId,
+			physicalId,
+			resourceType: src.type
+		});
+		claimedSynthIds.add(synth.logicalId);
+		sourcesHandledByOverride.add(src.logicalId);
+	}
+	const passOnePending = [];
+	for (const src of sourceEntries) {
+		if (sourcesHandledByOverride.has(src.logicalId)) continue;
+		const candidatesForLastSegment = synthByLastPathSegment.get(src.logicalId) ?? [];
+		const rawCandidateCount = candidatesForLastSegment.length;
+		const availableCandidates = candidatesForLastSegment.filter((c) => !claimedSynthIds.has(c.logicalId));
+		if (rawCandidateCount === 1 && availableCandidates.length === 1) {
+			const synth = availableCandidates[0];
+			pairs.push({
+				sourceLogicalId: src.logicalId,
+				synthLogicalId: synth.logicalId,
+				physicalId: physicalIdByLogicalId.get(src.logicalId),
+				resourceType: src.type
+			});
+			claimedSynthIds.add(synth.logicalId);
+		} else passOnePending.push(src);
+	}
+	for (const src of passOnePending) {
+		const candidatesSameType = synthEntries.filter((s) => s.type === src.type && !claimedSynthIds.has(s.logicalId));
+		const propertyMatches = candidatesSameType.filter((s) => deepEqualIgnoreNoValue(src.properties, s.properties));
+		if (propertyMatches.length === 1) {
+			const synth = propertyMatches[0];
+			pairs.push({
+				sourceLogicalId: src.logicalId,
+				synthLogicalId: synth.logicalId,
+				physicalId: physicalIdByLogicalId.get(src.logicalId),
+				resourceType: src.type
+			});
+			claimedSynthIds.add(synth.logicalId);
+		} else {
+			const isCollision = (synthByLastPathSegment.get(src.logicalId) ?? []).length >= 2;
+			unmatched.push({
+				sourceLogicalId: src.logicalId,
+				resourceType: src.type,
+				candidates: candidatesSameType.map((c) => c.logicalId).sort(),
+				reason: isCollision ? "logical-id-collision" : "no-match"
+			});
+		}
+	}
+	const mapping = {};
+	for (const p of pairs) mapping[p.sourceLogicalId] = p.synthLogicalId;
+	return {
+		mapping,
+		pairs,
+		unmatched
+	};
+}
+/**
+* Walk a parsed CFn template's `Resources` and return one entry per
+* resource. `Type` defaults to `''` and `Properties` to `{}` when the
+* template omits them (CFn allows resources with only `DeletionPolicy`
+* + `Type`); the mapper's downstream deep-equal handles `{}` cleanly.
+*
+* Top-level keys other than `Resources` (Conditions / Parameters /
+* Rules / Outputs / Mappings / Metadata) are NOT walked — the mapping
+* is resource-to-resource only, and §5.5 of the design doc spells out
+* the four CDK-synth injections that live in those sibling keys.
+*/
+function extractSourceResources(template) {
+	if (!template || typeof template !== "object") return [];
+	const resources = template["Resources"];
+	if (!resources || typeof resources !== "object") return [];
+	const out = [];
+	for (const [logicalId, raw] of Object.entries(resources)) {
+		if (!raw || typeof raw !== "object") continue;
+		const r = raw;
+		const type = typeof r["Type"] === "string" ? r["Type"] : "";
+		const props = r["Properties"] && typeof r["Properties"] === "object" ? r["Properties"] : {};
+		out.push({
+			logicalId,
+			type,
+			properties: props
+		});
+	}
+	return out;
+}
+/**
+* Walk the synth template's `Resources` and return one entry per
+* resource, EXCLUDING `AWS::CDK::Metadata` (synth-only sentinel that has
+* no source counterpart). Captures `Metadata['aws:cdk:path']` so Pass 1
+* can match against the last `/`-separated segment.
+*
+* The four other CDK-synth injections (CDKMetadataAvailable Condition,
+* BootstrapVersion Parameter, CheckBootstrapVersion Rule) live outside
+* `Resources` and are structurally excluded by this function.
+*/
+function extractSynthResources(template) {
+	if (!template || typeof template !== "object") return [];
+	const resources = template["Resources"];
+	if (!resources || typeof resources !== "object") return [];
+	const out = [];
+	for (const [logicalId, raw] of Object.entries(resources)) {
+		if (!raw || typeof raw !== "object") continue;
+		const r = raw;
+		const type = typeof r["Type"] === "string" ? r["Type"] : "";
+		if (type === "AWS::CDK::Metadata") continue;
+		const props = r["Properties"] && typeof r["Properties"] === "object" ? r["Properties"] : {};
+		const meta = r["Metadata"] && typeof r["Metadata"] === "object" ? r["Metadata"] : {};
+		const path = typeof meta["aws:cdk:path"] === "string" ? meta["aws:cdk:path"] : "";
+		out.push({
+			logicalId,
+			type,
+			properties: props,
+			awsCdkPath: path
+		});
+	}
+	return out;
+}
+/**
+* Group synth entries by the LAST `/`-separated segment of their
+* `aws:cdk:path` metadata so Pass 1 can look up the source logical id
+* directly. Per [docs/design/465-cfn-migrate.md](../../../../docs/design/465-cfn-migrate.md) §5.5:
+* `cdk migrate` emits `<StackName>/<LogicalId>` as the metadata value,
+* so the last segment IS the source logical id in the typical case.
+*
+* Entries without an `aws:cdk:path` are silently skipped — they cannot
+* be addressed by source logical id and will only be reachable via
+* Pass 2's Properties match.
+*/
+function indexSynthByLastPathSegment(entries) {
+	const out = /* @__PURE__ */ new Map();
+	for (const e of entries) {
+		if (!e.awsCdkPath) continue;
+		const lastSegment = e.awsCdkPath.split("/").pop() ?? "";
+		if (!lastSegment) continue;
+		const bucket = out.get(lastSegment);
+		if (bucket) bucket.push(e);
+		else out.set(lastSegment, [e]);
+	}
+	return out;
+}
+/**
+* Recursive deep equality between two values, with two CFn-specific
+* accommodations:
+*
+*  1. Object key order is NOT significant — `JSON.stringify` would
+*     diverge on the canonical-source-vs-synth-alphabetized case
+*     (verified by PR A's empirical run, §5.5 point 3) so we walk the
+*     keys explicitly.
+*  2. `AWS::NoValue` placeholder values are stripped before compare —
+*     `cdk migrate`'s codegen sometimes emits the placeholder for a
+*     property the source template simply omitted, and the structural
+*     intent matches. Source side never has the placeholder; synth side
+*     can on either side of a nested object.
+*
+* Arrays are compared positionally (order IS significant — Tags arrays
+* and similar carry ordering semantics).
+*/
+function deepEqualIgnoreNoValue(a, b) {
+	if (a === b) return true;
+	if (isAwsNoValue(a) !== isAwsNoValue(b)) return false;
+	if (isAwsNoValue(a) && isAwsNoValue(b)) return true;
+	if (typeof a !== typeof b) return false;
+	if (a === null || b === null) return a === b;
+	if (typeof a !== "object") return a === b;
+	if (Array.isArray(a) !== Array.isArray(b)) return false;
+	if (Array.isArray(a) && Array.isArray(b)) {
+		if (a.length !== b.length) return false;
+		for (let i = 0; i < a.length; i++) if (!deepEqualIgnoreNoValue(a[i], b[i])) return false;
+		return true;
+	}
+	const aObj = a;
+	const bObj = b;
+	const aKeys = Object.keys(aObj).filter((k) => !isAwsNoValue(aObj[k]) && aObj[k] !== void 0);
+	const bKeys = Object.keys(bObj).filter((k) => !isAwsNoValue(bObj[k]) && bObj[k] !== void 0);
+	if (aKeys.length !== bKeys.length) return false;
+	const aKeySet = new Set(aKeys);
+	for (const k of bKeys) {
+		if (!aKeySet.has(k)) return false;
+		if (!deepEqualIgnoreNoValue(aObj[k], bObj[k])) return false;
+	}
+	return true;
+}
+/**
+* True when the value is the CFn `AWS::NoValue` placeholder
+* (`{Ref: 'AWS::NoValue'}`). `cdk migrate`'s codegen emits this for
+* conditional properties the source template omitted; the structural
+* intent matches and deep-equal must treat them as absent.
+*/
+function isAwsNoValue(v) {
+	if (!v || typeof v !== "object") return false;
+	const obj = v;
+	const keys = Object.keys(obj);
+	return keys.length === 1 && keys[0] === "Ref" && obj["Ref"] === "AWS::NoValue";
+}
+
+//#endregion
+//#region src/cli/commands/migrate/resource-mapping-file.ts
+/** Conventional filename inside the migrate output dir. */
+const RESOURCE_MAPPING_FILENAME = "cdkd-resource-mapping.json";
+/**
+* Build the on-disk file shape from a {@link ResourceMappingResult} +
+* the source / output stack names, then write it to
+* `<outputDir>/cdkd-resource-mapping.json` (overwriting any prior file
+* on the same path — same idempotency contract as `cdk migrate`'s own
+* codegen, and the user expects a re-run to refresh stale data).
+*
+* Returns the absolute on-disk path so the orchestrator can name it in
+* the error message when the mapping is incomplete.
+*/
+function writeMappingFile(outputDir, args) {
+	const path = join(outputDir, RESOURCE_MAPPING_FILENAME);
+	const file = {
+		version: 1,
+		generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+		sourceStack: args.sourceStack,
+		outputStack: args.outputStack,
+		mapping: args.result.mapping
+	};
+	if (args.result.unmatched.length > 0) file._unmatched = args.result.unmatched;
+	writeFileSync(path, JSON.stringify(file, null, 2) + "\n", "utf-8");
+	return path;
+}
+/**
+* Read a user-supplied resource-mapping file from disk and return the
+* `{<srcLogicalId>: <synthLogicalId>}` overrides for the mapper.
+*
+* Tolerates `_unmatched` on input (a user that re-runs against a
+* partial-failure file without editing should hit the same failure on
+* the resolution side — not a parse error here). Hard-errors on
+* structurally invalid input (missing `mapping`, non-object root,
+* non-string values, wrong `version`).
+*
+* Surfaces every shape error as `LocalMigrateError` (exit code 2) so
+* the CLI handler routes it through the normal error path.
+*/
+function readMappingFile(path) {
+	if (!existsSync(path)) throw new LocalMigrateError(`Resource-mapping file not found: ${path}. Drop the --resource-mapping flag or supply a valid path.`);
+	let raw;
+	try {
+		raw = JSON.parse(readFileSync(path, "utf-8"));
+	} catch (err) {
+		throw new LocalMigrateError(`Resource-mapping file '${path}' is not valid JSON: ${err instanceof Error ? err.message : String(err)}`);
+	}
+	if (!raw || typeof raw !== "object" || Array.isArray(raw)) throw new LocalMigrateError(`Resource-mapping file '${path}' must contain a JSON object at the top level.`);
+	const obj = raw;
+	if (obj["version"] !== 1) throw new LocalMigrateError(`Resource-mapping file '${path}' has unsupported version '${String(obj["version"])}'. Expected version 1.`);
+	if (typeof obj["sourceStack"] !== "string" || obj["sourceStack"].length === 0) throw new LocalMigrateError(`Resource-mapping file '${path}' is missing the required 'sourceStack' field.`);
+	if (typeof obj["outputStack"] !== "string" || obj["outputStack"].length === 0) throw new LocalMigrateError(`Resource-mapping file '${path}' is missing the required 'outputStack' field.`);
+	if (typeof obj["generatedAt"] !== "string") throw new LocalMigrateError(`Resource-mapping file '${path}' is missing the required 'generatedAt' field.`);
+	const mappingRaw = obj["mapping"];
+	if (!mappingRaw || typeof mappingRaw !== "object" || Array.isArray(mappingRaw)) throw new LocalMigrateError(`Resource-mapping file '${path}' is missing the required 'mapping' object.`);
+	const mapping = {};
+	for (const [k, v] of Object.entries(mappingRaw)) {
+		if (typeof v !== "string") throw new LocalMigrateError(`Resource-mapping file '${path}' has a non-string value for key '${k}'.`);
+		mapping[k] = v;
+	}
+	const result = {
+		version: 1,
+		generatedAt: obj["generatedAt"],
+		sourceStack: obj["sourceStack"],
+		outputStack: obj["outputStack"],
+		mapping
+	};
+	if (Array.isArray(obj["_unmatched"])) {
+		const cleaned = [];
+		for (const entry of obj["_unmatched"]) {
+			if (!entry || typeof entry !== "object") continue;
+			const e = entry;
+			if (typeof e["sourceLogicalId"] !== "string" || typeof e["resourceType"] !== "string" || !Array.isArray(e["candidates"]) || e["reason"] !== "no-match" && e["reason"] !== "logical-id-collision") continue;
+			cleaned.push({
+				sourceLogicalId: e["sourceLogicalId"],
+				resourceType: e["resourceType"],
+				candidates: e["candidates"].filter((c) => typeof c === "string"),
+				reason: e["reason"]
+			});
+		}
+		if (cleaned.length > 0) result._unmatched = cleaned;
+	}
+	return result;
+}
+
+//#endregion
+//#region src/cli/commands/migrate-command.ts
+/**
+* `cdkd migrate --from-cfn-stack <name>` end-to-end orchestrator.
+*
+* Closes the CLI half of [#465](https://github.com/go-to-k/cdkd/issues/465).
+* Reads the source CFn stack, runs upstream `cdk migrate` via the PR A
+* library, builds the source → synth logical-ID mapping with the 2-pass
+* algorithm, writes a `cdkd-resource-mapping.json` audit file, prompts
+* for confirmation, invokes `cdkd import` to write state under the
+* synth logical IDs, and (when `--retire-cfn-stack` is set) finally
+* retires the source CFn stack so management responsibility transfers
+* fully to cdkd.
+*
+* AWS resources are never modified — the migration is a metadata
+* transfer only. See [docs/design/465-cfn-migrate.md](../../../docs/design/465-cfn-migrate.md) §7
+* for the post-migration state matrix.
+*/
+async function migrateCommandAction(positionalStack, options) {
+	const logger = getLogger();
+	if (options.verbose) {
+		logger.setLevel("debug");
+		process.env["CDKD_NO_LIVE"] = "1";
+	}
+	const sourceCfnStackName = options.fromCfnStack ?? positionalStack;
+	if (!sourceCfnStackName) throw new LocalMigrateError("Missing required argument: --from-cfn-stack <name> (or pass the stack name positionally).");
+	if (options.retireCfnStack && options.skipSynth) throw new LocalMigrateError("--retire-cfn-stack is incompatible with --skip-synth: the post-state-write retirement (UpdateStack + DeleteStack) cannot run without a synthesized template + cdkd state.");
+	if (options.retireCfnStack && options.dryRun) throw new LocalMigrateError("--retire-cfn-stack is incompatible with --dry-run: retirement issues real AWS calls (UpdateStack injects Retain policies, then DeleteStack).");
+	if (options.retireCfnStack && options.filter && options.filter.length > 0) throw new LocalMigrateError("--retire-cfn-stack is incompatible with --filter: a partial migration that retires the whole source CFn stack would strand the un-migrated resources. Drop one of the flags or migrate the rest of the stack first.");
+	await applyRoleArnIfSet({
+		roleArn: options.roleArn,
+		region: options.region
+	});
+	const region = options.region || process.env["AWS_REGION"] || "us-east-1";
+	const outputDir = resolve(options.outputDir ?? sourceCfnStackName);
+	logger.info(`[migrate] Source CFn stack: ${sourceCfnStackName}`);
+	logger.info(`[migrate] Output directory: ${outputDir}`);
+	const libResult = await runMigrateLibrary({
+		fromCfnStack: sourceCfnStackName,
+		outputDir,
+		language: options.language ?? "typescript",
+		...options.region && { region: options.region },
+		...options.account && { account: options.account },
+		...options.filter && options.filter.length > 0 && { filters: options.filter },
+		...options.profile && { profile: options.profile },
+		...options.cdkBin && { cdkBinPath: options.cdkBin },
+		skipInstall: options.skipInstall ?? false,
+		skipSynth: options.skipSynth ?? false
+	});
+	if (options.skipSynth || !libResult.templateBody) {
+		logger.info(`[migrate] --skip-synth: generated CDK app at ${libResult.outputDir}. Re-run without --skip-synth to write cdkd state.`);
+		return;
+	}
+	let overrides;
+	if (options.resourceMapping) {
+		const mappingPath = resolve(options.resourceMapping);
+		logger.info(`[migrate] Loading user-supplied resource mapping from ${mappingPath}`);
+		overrides = readMappingFile(mappingPath).mapping;
+	}
+	let mappingResult;
+	try {
+		mappingResult = buildResourceMapping({
+			sourceCfnTemplate: libResult.sourceCfnTemplate,
+			synthTemplate: libResult.templateBody,
+			sourceResources: libResult.sourceResources,
+			...overrides && { overrides }
+		});
+	} catch (err) {
+		throw new LocalMigrateError(err instanceof Error ? err.message : String(err));
+	}
+	const outputStack = sourceCfnStackName;
+	const mappingFilePath = writeMappingFile(libResult.outputDir, {
+		sourceStack: sourceCfnStackName,
+		outputStack,
+		result: mappingResult
+	});
+	logger.info(`[migrate] Resource mapping written to ${mappingFilePath}`);
+	if (mappingResult.unmatched.length > 0) {
+		const lines = mappingResult.unmatched.map((u) => {
+			const candidatesStr = u.candidates.length > 0 ? ` (synth candidates of same Type: ${u.candidates.join(", ")})` : " (no synth resource has the same Type)";
+			return `  - ${u.sourceLogicalId} (${u.resourceType}) [${u.reason}]${candidatesStr}`;
+		});
+		throw new LocalMigrateError(`Could not auto-map ${mappingResult.unmatched.length} of ${mappingResult.unmatched.length + mappingResult.pairs.length} source resource(s) to the synthesized CDK template:\n${lines.join("\n")}\n\nEdit '${mappingFilePath}'\nto add the correct '<sourceLogicalId>: <synthLogicalId>' pairs under "mapping", then re-run:\n  cdkd migrate --from-cfn-stack ${sourceCfnStackName} --resource-mapping ${mappingFilePath} --output-dir ${libResult.outputDir}\n(The --output-dir override re-uses the already-generated CDK code; drop it if you let the default location be used.)`);
+	}
+	printMappingTable(mappingResult, sourceCfnStackName, outputStack);
+	if (options.dryRun) {
+		logger.info(`[migrate] --dry-run: would import ${mappingResult.pairs.length} resource(s) into cdkd state under stack '${outputStack}' (region '${region}'). State NOT written.`);
+		return;
+	}
+	if (!options.yes) {
+		if (!await promptConfirm(`Import ${mappingResult.pairs.length} resource(s) into cdkd state for stack '${outputStack}' (${region})?`)) {
+			logger.info("[migrate] Cancelled by user. No state written.");
+			return;
+		}
+	}
+	const importMapping = {};
+	for (const p of mappingResult.pairs) importMapping[p.synthLogicalId] = p.physicalId;
+	const resolvedStateBucket = await resolveStateBucketWithDefault(options.stateBucket, region);
+	await runImport(outputStack, {
+		app: libResult.assemblyDir,
+		statePrefix: options.statePrefix ?? "cdkd",
+		resourceMappingInline: JSON.stringify(importMapping),
+		auto: false,
+		dryRun: false,
+		yes: true,
+		force: false,
+		verbose: options.verbose ?? false,
+		stateBucket: resolvedStateBucket,
+		...options.region && { region: options.region },
+		...options.profile && { profile: options.profile },
+		...options.roleArn && { roleArn: options.roleArn }
+	});
+	if (options.retireCfnStack) {
+		logger.info(`[migrate] Retiring source CloudFormation stack '${sourceCfnStackName}'...`);
+		const cfnConfig = {};
+		if (options.region) cfnConfig.region = options.region;
+		if (options.profile) cfnConfig.profile = options.profile;
+		const awsClients = new AwsClients(cfnConfig);
+		const cfnClient = awsClients.cloudFormation;
+		try {
+			await retireCloudFormationStack({
+				cfnStackName: sourceCfnStackName,
+				cfnClient,
+				yes: options.yes ?? false,
+				stateBucket: resolvedStateBucket,
+				...options.profile && { s3ClientOpts: { profile: options.profile } }
+			});
+		} finally {
+			awsClients.destroy();
+		}
+	}
+	logger.info(`[migrate] Migrated ${mappingResult.pairs.length} resource(s) from CloudFormation stack '${sourceCfnStackName}' to cdkd state for stack '${outputStack}'.`);
+	logger.info(`[migrate] Generated CDK app at ${libResult.outputDir}`);
+	if (!options.retireCfnStack) logger.info(`[migrate] Source CloudFormation stack '${sourceCfnStackName}' is unchanged. Re-run with --retire-cfn-stack to retire it (or do so manually later).`);
+}
+/**
+* Print a tabular `(sourceLogicalId → synthLogicalId  physicalId)`
+* summary so users can see what's about to be imported before the
+* confirmation prompt. Matches the visual shape of `cdkd import`'s
+* summary table for consistency.
+*/
+function printMappingTable(result, sourceStack, outputStack) {
+	const logger = getLogger();
+	logger.info("");
+	logger.info(`[migrate] Resolved mapping (${sourceStack} → ${outputStack}):`);
+	for (const p of result.pairs) logger.info(`  ${p.sourceLogicalId} → ${p.synthLogicalId}  [${p.resourceType}]  ${p.physicalId}`);
+	logger.info("");
+}
+/**
+* Minimal `(y/N)` confirmation prompt using `node:readline`. Mirrors
+* the shape of [src/cli/commands/import.ts](import.ts)'s `confirmPrompt`
+* so the user UX is consistent across the import + migrate surfaces.
+* Non-TTY callers (CI) should pass `--yes` to skip this entirely.
+*/
+async function promptConfirm(message) {
+	if (!process.stdin.isTTY) throw new LocalMigrateError(`Non-interactive shell detected and --yes was not supplied. Re-run with --yes to confirm: "${message}"`);
+	const rl = (await import("node:readline/promises")).createInterface({
+		input: process.stdin,
+		output: process.stdout
+	});
+	try {
+		const v = (await rl.question(`${message} (y/N) `)).trim().toLowerCase();
+		return v === "y" || v === "yes";
+	} finally {
+		rl.close();
+	}
+}
+/**
+* Commander factory for `cdkd migrate`. Registered in `src/cli/index.ts`
+* alongside the existing top-level commands. Matches the design doc §3
+* flag set; the action handler routes through {@link migrateCommandAction}
+* via `withErrorHandling` so library callers see exceptions but CLI
+* callers get the standard exit-code-2 routing.
+*/
+function createMigrateCommand() {
+	return new Command("migrate").description("Adopt a plain (non-CDK) CloudFormation stack into a cdkd-managed CDK app. Generates new CDK code via upstream `cdk migrate`, builds a logical-ID mapping between the source CFn template and the synth template, writes cdkd state, and (optionally) retires the source CFn stack. AWS resources are never modified.").argument("[stack]", "Source CFn stack name. Alias for --from-cfn-stack.").addOption(new Option("--from-cfn-stack <name>", "Source CloudFormation stack name to adopt. Required (or pass positionally).")).addOption(new Option("--output-dir <dir>", "Directory to write the generated CDK app to. Defaults to <cwd>/<CfnStackName>.")).addOption(new Option("--language <choice>", "Generated code language. v1: typescript only.").choices(["typescript"]).default("typescript")).addOption(new Option("--region <region>", "AWS region. Defaults to AWS_REGION env / profile.")).addOption(new Option("--account <id>", "AWS account ID. Auto-detected via STS when omitted.")).addOption(new Option("--retire-cfn-stack", "After cdkd state is written, inject DeletionPolicy=Retain on every resource in the source CFn stack and DeleteStack. AWS resources stay; the CFn stack record is gone. Off by default.").default(false)).addOption(new Option("--filter <key=value>", "Pass-through to `cdk migrate --filter` for resource subsetting. Repeatable.").argParser((value, previous) => [...previous ?? [], value]).default([])).addOption(new Option("--skip-install", "Skip `npm install` after codegen.").default(false)).addOption(new Option("--skip-synth", "Skip `cdk synth` (does NOT write cdkd state). Mutually exclusive with --retire-cfn-stack.").default(false)).addOption(new Option("--dry-run", "Print the import plan without writing state or retiring the CFn stack. Mutually exclusive with --retire-cfn-stack.").default(false)).addOption(new Option("-y, --yes", "Auto-confirm the import + retirement prompts.").default(false)).addOption(new Option("--cdk-bin <path>", "Override the `cdk` binary path.")).addOption(new Option("--resource-mapping <file>", `Path to a JSON file of {sourceLogicalId: synthLogicalId} overrides. Same shape as the auto-written ${RESOURCE_MAPPING_FILENAME}.`)).addOption(new Option("--state-bucket <name>", "cdkd state bucket. Defaults to cdkd-state-<accountId>.")).addOption(new Option("--state-prefix <prefix>", "cdkd state prefix inside the bucket.").default("cdkd")).addOption(new Option("--profile <name>", "AWS profile name.")).addOption(new Option("--role-arn <arn>", "IAM role to assume before any AWS call.")).addOption(new Option("--verbose", "Enable debug-level logging.").default(false)).action(withErrorHandling(migrateCommandAction));
+}
+
 //#endregion
 //#region src/cli/index.ts
 const SUBCOMMANDS = new Set([
@@ -51876,7 +52947,8 @@ const SUBCOMMANDS = new Set([
 	"publish-assets",
 	"force-unlock",
 	"state",
-	"local"
+	"local",
+	"migrate"
 ]);
 /**
 * Reorder args so options before the subcommand are moved after it.
@@ -51900,7 +52972,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.134.0");
+	program.name("cdkd").description("CDK Direct - Deploy AWS CDK apps directly via SDK/Cloud Control API").version("0.135.0");
 	program.addCommand(createBootstrapCommand());
 	program.addCommand(createSynthCommand());
 	program.addCommand(createListCommand());
@@ -51915,6 +52987,7 @@ async function main() {
 	program.addCommand(createStateCommand());
 	program.addCommand(createLocalCommand());
 	program.addCommand(createExportCommand());
+	program.addCommand(createMigrateCommand());
 	const args = reorderArgs(process.argv);
 	await program.parseAsync(args);
 }