@go-to-k/cdkd 0.126.0 → 0.128.0

package/dist/cli.js

@@ -34749,6 +34749,143 @@ function createStateCommand() {
 	return cmd;
 }
 
+//#endregion
+//#region src/cli/upload-cfn-template.ts
+/**
+* CloudFormation `TemplateBody` hard limit (51,200 bytes). Templates larger
+* than this cannot be submitted inline and must be uploaded to S3 and
+* referenced via `TemplateURL` instead — see {@link uploadCfnTemplate}.
+*/
+const CFN_TEMPLATE_BODY_LIMIT = 51200;
+/**
+* CloudFormation `TemplateURL` hard limit (1 MB / 1,048,576 bytes).
+* Templates larger than this are structurally unsubmittable through any
+* CloudFormation API — no S3 indirection helps. The caller surfaces a
+* pre-flight error pointing the user at template-splitting (nested stacks)
+* or shrinking inline asset payloads (`lambda.Code.fromAsset`).
+*/
+const CFN_TEMPLATE_URL_LIMIT = 1048576;
+/**
+* Shared S3 key prefix for transient CFn templates uploaded by `cdkd import
+* --migrate-from-cloudformation` and `cdkd export`. Kept distinct from
+* cdkd's `cdkd/` state prefix so `state list` / `state info` never conflate
+* transient migration artifacts with persisted stack state. The prefix is
+* intentionally human-grep-able — leftovers (if cleanup fails) point
+* straight at the offending stack name.
+*
+* Re-used by both commands so operator-facing audit trails (CloudTrail
+* records of the migrate-tmp uploads) stay consistent across the two
+* flows.
+*/
+const MIGRATE_TMP_PREFIX = "cdkd-migrate-tmp";
+/**
+* Upload a CFn template body to the cdkd state bucket and return both a
+* virtual-hosted-style HTTPS URL CloudFormation can fetch via
+* `TemplateURL` and a `cleanup` callback that deletes the object (and
+* destroys the S3 client).
+*
+* The state bucket's actual region is resolved via `GetBucketLocation`
+* (cached per-process) so the upload client and the URL match the
+* bucket's region — the calling CLI's profile region is irrelevant here.
+*
+* Cleanup is the caller's responsibility: invoke `cleanup` in a `finally`
+* around the CFn call. CloudFormation copies the template into its own
+* internal storage during the synchronous `CreateChangeSet` /
+* `UpdateStack` API call, so the S3 object is no longer needed after that
+* call returns (success or failure).
+*
+* Shared between `cdkd import --migrate-from-cloudformation` (via
+* `retire-cfn-stack.ts`) and `cdkd export` (via `commands/export.ts`) so
+* the upload + cleanup contract is single-sourced.
+*/
+async function uploadCfnTemplate(args) {
+	const { bucket, body, stackName, format, s3ClientOpts } = args;
+	const region = await resolveBucketRegion(bucket, {
+		...s3ClientOpts?.profile && { profile: s3ClientOpts.profile },
+		...s3ClientOpts?.credentials && { credentials: s3ClientOpts.credentials }
+	});
+	const s3 = new S3Client({
+		region,
+		...s3ClientOpts?.profile && { profile: s3ClientOpts.profile },
+		...s3ClientOpts?.credentials && { credentials: s3ClientOpts.credentials }
+	});
+	const ext = format === "yaml" ? "yaml" : "json";
+	const contentType = format === "yaml" ? "application/x-yaml" : "application/json";
+	const key = `${MIGRATE_TMP_PREFIX}/${stackName}/${Date.now()}.${ext}`;
+	try {
+		await s3.send(new PutObjectCommand({
+			Bucket: bucket,
+			Key: key,
+			Body: body,
+			ContentType: contentType
+		}));
+	} catch (err) {
+		s3.destroy();
+		throw err;
+	}
+	const url = `https://${bucket}.s3.${region}.amazonaws.com/${key}`;
+	const cleanup = async () => {
+		try {
+			await s3.send(new DeleteObjectCommand({
+				Bucket: bucket,
+				Key: key
+			}));
+		} finally {
+			s3.destroy();
+		}
+	};
+	return {
+		url,
+		cleanup
+	};
+}
+/**
+* Threshold (in bytes) above which a single resource's serialized
+* `Properties` block is considered an "inline payload" worth surfacing as
+* a contributor to a template that exceeds the 1 MB CFn `TemplateURL`
+* ceiling. 4 KB matches the typical inline `Code.ZipFile` Lambda payload
+* that pushes a multi-resource CDK app over the wire-format limit.
+*/
+const LARGE_INLINE_RESOURCE_THRESHOLD = 4096;
+/**
+* Walk a CFn template and surface every resource whose serialized
+* `Properties` block exceeds {@link LARGE_INLINE_RESOURCE_THRESHOLD}.
+* Used to build the actionable "offending resources" list in the
+* pre-flight error when a template exceeds the 1 MB `TemplateURL`
+* ceiling — typical culprits are inline `Code.ZipFile` Lambdas, inline
+* StepFunctions definitions, or large `AWS::CloudFormation::Stack`
+* bodies.
+*
+* Returns entries sorted by `approxBytes` descending so the user sees
+* the biggest contributor first. A non-CFn-template input (no
+* `Resources` object) returns an empty array.
+*/
+function findLargeInlineResources(template, threshold = LARGE_INLINE_RESOURCE_THRESHOLD) {
+	const result = [];
+	const resources = template["Resources"];
+	if (!resources || typeof resources !== "object" || Array.isArray(resources)) return result;
+	for (const [logicalId, resource] of Object.entries(resources)) {
+		if (!resource || typeof resource !== "object" || Array.isArray(resource)) continue;
+		const r = resource;
+		const resourceType = typeof r["Type"] === "string" ? r["Type"] : "<unknown>";
+		const properties = r["Properties"];
+		if (properties === void 0 || properties === null) continue;
+		let approxBytes;
+		try {
+			approxBytes = JSON.stringify(properties).length;
+		} catch {
+			continue;
+		}
+		if (approxBytes >= threshold) result.push({
+			logicalId,
+			resourceType,
+			approxBytes
+		});
+	}
+	result.sort((a, b) => b.approxBytes - a.approxBytes);
+	return result;
+}
+
 //#endregion
 //#region src/cli/yaml-cfn.ts
 /**
@@ -35068,22 +35205,16 @@ const STABLE_TERMINAL_STATUSES = new Set([
 * 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}.
+*
+* Re-exported from `upload-cfn-template.ts` as the shared source of truth.
 */
-const TEMPLATE_BODY_LIMIT = 51200;
+const TEMPLATE_BODY_LIMIT = CFN_TEMPLATE_BODY_LIMIT;
 /**
 * UpdateStack TemplateURL hard limit (1 MB / 1,048,576 bytes). Templates
 * larger than this cannot be submitted at all and require manual
 * intervention.
 */
-const TEMPLATE_URL_LIMIT = 1048576;
-/**
-* S3 key prefix for the transient Retain-injected template uploaded by the
-* `--migrate-from-cloudformation` flow when the template exceeds the inline
-* 51,200-byte limit. Kept distinct from cdkd's `cdkd/` state prefix so
-* `state list` / `state info` never conflate transient migration artifacts
-* with persisted state.
-*/
-const MIGRATE_TMP_PREFIX = "cdkd-migrate-tmp";
+const TEMPLATE_URL_LIMIT = CFN_TEMPLATE_URL_LIMIT;
 /**
 * Retire a CloudFormation stack whose resources have just been adopted into
 * cdkd state. The 4-step procedure is the one AWS recommends for handing
@@ -35211,45 +35342,13 @@ async function retireCloudFormationStack(options) {
 * Exported for unit testing.
 */
 async function uploadTemplateForUpdateStack(args) {
-	const { bucket, body, cfnStackName, format, s3ClientOpts } = args;
-	const region = await resolveBucketRegion(bucket, {
-		...s3ClientOpts?.profile && { profile: s3ClientOpts.profile },
-		...s3ClientOpts?.credentials && { credentials: s3ClientOpts.credentials }
+	return uploadCfnTemplate({
+		bucket: args.bucket,
+		body: args.body,
+		stackName: args.cfnStackName,
+		...args.format && { format: args.format },
+		...args.s3ClientOpts && { s3ClientOpts: args.s3ClientOpts }
 	});
-	const s3 = new S3Client({
-		region,
-		...s3ClientOpts?.profile && { profile: s3ClientOpts.profile },
-		...s3ClientOpts?.credentials && { credentials: s3ClientOpts.credentials }
-	});
-	const ext = format === "yaml" ? "yaml" : "json";
-	const contentType = format === "yaml" ? "application/x-yaml" : "application/json";
-	const key = `${MIGRATE_TMP_PREFIX}/${cfnStackName}/${Date.now()}.${ext}`;
-	try {
-		await s3.send(new PutObjectCommand({
-			Bucket: bucket,
-			Key: key,
-			Body: body,
-			ContentType: contentType
-		}));
-	} catch (err) {
-		s3.destroy();
-		throw err;
-	}
-	const url = `https://${bucket}.s3.${region}.amazonaws.com/${key}`;
-	const cleanup = async () => {
-		try {
-			await s3.send(new DeleteObjectCommand({
-				Bucket: bucket,
-				Key: key
-			}));
-		} finally {
-			s3.destroy();
-		}
-	};
-	return {
-		url,
-		cleanup
-	};
 }
 /**
 * Parse a CloudFormation template body (JSON or YAML), set
@@ -36503,7 +36602,7 @@ function extractLambdaProperties(stack, logicalId, resource, resources) {
 	const timeoutSec = typeof props["Timeout"] === "number" ? props["Timeout"] : 3;
 	const ephemeralStorageMb = extractEphemeralStorageMb(props, logicalId);
 	const code = props["Code"] ?? {};
-	const imageUri = extractImageUri(code["ImageUri"], logicalId, stack.stackName, resources);
+	const imageUri = extractImageUri$1(code["ImageUri"], logicalId, stack.stackName, resources);
 	if (imageUri !== void 0) return extractImageLambdaProperties({
 		stack,
 		logicalId,
@@ -36600,7 +36699,7 @@ function extractEphemeralStorageMb(props, logicalId) {
 * for genuinely unrecognized shapes so the caller's downstream ZIP-vs-
 * IMAGE branching can route to its existing error path.
 */
-function extractImageUri(value, logicalId, stackName, resources) {
+function extractImageUri$1(value, logicalId, stackName, resources) {
 	if (typeof value === "string" && value.length > 0) return value;
 	if (value && typeof value === "object" && !Array.isArray(value)) {
 		const obj = value;
@@ -40248,31 +40347,56 @@ function createContainerPool(specs, options) {
 	/**
 	* Spin up one new container for the given Lambda spec. Returns a
 	* handle the caller can write into the entry's data structures.
+	*
+	* Branches on `spec.kind`:
+	*   - `'zip'`: bind-mount the function's local code dir at
+	*     `/var/task` (or `/var/runtime` for `provided.*` runtimes),
+	*     base image from `public.ecr.aws/lambda/<lang>:<v>`, CMD =
+	*     `[<Handler>]`.
+	*   - `'image'`: no code bind-mount (image already includes the
+	*     code), base image is the pre-built local tag, CMD =
+	*     `ImageConfig.Command` (may be empty), optional EntryPoint /
+	*     WorkingDirectory / --platform applied verbatim.
 	*/
 	async function startOne(spec) {
-		const image = resolveRuntimeImage(spec.lambda.runtime);
 		const hostPort = await pickFreePort();
 		const name = `cdkd-local-${spec.lambda.logicalId}-${process.pid}-${Math.floor(Math.random() * 1e6)}`;
-		logger.debug(`Starting container ${name} for ${spec.lambda.logicalId} on ${spec.containerHost}:${hostPort}`);
-		const optMount = spec.optDir ? [{
-			hostPath: spec.optDir,
-			containerPath: "/opt",
-			readOnly: true
-		}] : [];
-		const containerCodePath = resolveRuntimeCodeMountPath(spec.lambda.runtime);
-		const containerId = await runDetached({
-			image,
-			mounts: [{
-				hostPath: spec.codeDir,
-				containerPath: containerCodePath,
+		logger.debug(`Starting container ${name} for ${spec.lambda.logicalId} (kind=${spec.kind}) on ${spec.containerHost}:${hostPort}`);
+		let containerId;
+		if (spec.kind === "zip") {
+			const optMount = spec.optDir ? [{
+				hostPath: spec.optDir,
+				containerPath: "/opt",
 				readOnly: true
-			}],
-			extraMounts: optMount,
+			}] : [];
+			const containerCodePath = resolveRuntimeCodeMountPath(spec.lambda.runtime);
+			containerId = await runDetached({
+				image: resolveRuntimeImage(spec.lambda.runtime),
+				mounts: [{
+					hostPath: spec.codeDir,
+					containerPath: containerCodePath,
+					readOnly: true
+				}],
+				extraMounts: optMount,
+				env: spec.env,
+				cmd: [spec.lambda.handler],
+				hostPort,
+				host: spec.containerHost,
+				name,
+				...spec.debugPort !== void 0 && { debugPort: spec.debugPort },
+				...spec.tmpfs !== void 0 && { tmpfs: spec.tmpfs }
+			});
+		} else containerId = await runDetached({
+			image: spec.image,
+			mounts: [],
 			env: spec.env,
-			cmd: [spec.lambda.handler],
+			cmd: spec.command,
 			hostPort,
 			host: spec.containerHost,
 			name,
+			platform: spec.platform,
+			...spec.entryPoint !== void 0 && { entryPoint: spec.entryPoint },
+			...spec.workingDir !== void 0 && { workingDir: spec.workingDir },
 			...spec.debugPort !== void 0 && { debugPort: spec.debugPort },
 			...spec.tmpfs !== void 0 && { tmpfs: spec.tmpfs }
 		});
@@ -44043,12 +44167,13 @@ async function localStartApiCommand(target, options) {
 				inlineTmpDirs,
 				layerTmpDirs,
 				stateByStack,
+				skipPull: options.pull === false,
 				...options.layerRoleArn !== void 0 && { layerRoleArn: options.layerRoleArn }
 			});
 			specs.set(logicalId, spec);
 		}
 		const distinctImages = /* @__PURE__ */ new Set();
-		for (const spec of specs.values()) distinctImages.add(resolveRuntimeImage(spec.lambda.runtime));
+		for (const spec of specs.values()) if (spec.kind === "zip") distinctImages.add(resolveRuntimeImage(spec.lambda.runtime));
 		for (const image of distinctImages) await pullImage(image, options.pull === false);
 		return {
 			routes: routesWithAuth,
@@ -44077,13 +44202,23 @@ async function localStartApiCommand(target, options) {
 	/**
 	* Compute the watched-asset list from a spec map. Pure helper —
 	* keeps the side-effect (`lastAssetPaths.value = ...`) confined to
-	* the post-swap call sites (initial boot + post-reload). `codeDir`
-	* is either the unzipped asset directory or the inline-code tmpdir;
-	* both are watch-worthy.
+	* the post-swap call sites (initial boot + post-reload). For ZIP
+	* Lambdas `codeDir` is either the unzipped asset directory or the
+	* inline-code tmpdir; both are watch-worthy. IMAGE Lambdas
+	* (`kind: 'image'`) don't have a host-side bind-mount source — the
+	* code is baked into the docker image at build time. Their build
+	* context (Dockerfile + source directory) is rebuilt on every
+	* reload via `synthesizeAndBuild` → `buildContainerSpec` →
+	* `resolveContainerImageForStartApi`, so a source edit DOES trigger
+	* rebuild AND the deterministic `image` tag changes — but watching
+	* the build-context dir explicitly here is deferred to a follow-up
+	* (the watched-asset list is currently sourced from `cdk.out/`
+	* which transitively covers most container-Lambda asset dirs since
+	* `cdk synth` re-stages them on every synth call).
 	*/
 	const computeAssetPaths = (specs) => {
 		const assetPaths = /* @__PURE__ */ new Set();
-		for (const spec of specs.values()) assetPaths.add(spec.codeDir);
+		for (const spec of specs.values()) if (spec.kind === "zip") assetPaths.add(spec.codeDir);
 		return [...assetPaths];
 	};
 	const initialMaterial = await synthesizeAndBuild();
@@ -44356,10 +44491,19 @@ function warnIamRoutes(routesWithAuth) {
 * missing, runtime not supported).
 */
 async function buildContainerSpec(args) {
-	const { logicalId, stacks, overrides, assumeRole, containerHost, debugPort, stsRegion, inlineTmpDirs, layerTmpDirs, stateByStack, layerRoleArn } = args;
+	const { logicalId, stacks, overrides, assumeRole, containerHost, debugPort, stsRegion, inlineTmpDirs, layerTmpDirs, stateByStack, skipPull, layerRoleArn } = args;
 	const lambda = resolveLambdaByLogicalId(logicalId, stacks);
-	const codeDir = lambda.codePath ?? materializeInlineCode$1(lambda.handler, lambda.inlineCode ?? "", resolveRuntimeFileExtension(lambda.runtime), inlineTmpDirs);
-	const optDir = await materializeLambdaLayers$1(lambda.layers, layerTmpDirs, layerRoleArn);
+	let codeDir;
+	let optDir;
+	let imageRef;
+	let platform;
+	if (lambda.kind === "zip") {
+		codeDir = lambda.codePath ?? materializeInlineCode$1(lambda.handler, lambda.inlineCode ?? "", resolveRuntimeFileExtension(lambda.runtime), inlineTmpDirs);
+		optDir = await materializeLambdaLayers$1(lambda.layers, layerTmpDirs, layerRoleArn);
+	} else {
+		imageRef = (await resolveContainerImageForStartApi(lambda, skipPull)).imageRef;
+		platform = architectureToPlatform(lambda.architecture);
+	}
 	let templateEnv = getTemplateEnv$1(lambda.resource);
 	const stateBundle = stateByStack.get(lambda.stack.stackName);
 	let stateAudit;
@@ -44399,7 +44543,8 @@ async function buildContainerSpec(args) {
 		target: "/tmp",
 		sizeMb: lambda.ephemeralStorageMb
 	} : void 0;
-	return {
+	if (lambda.kind === "zip") return {
+		kind: "zip",
 		lambda,
 		codeDir,
 		env: dockerEnv,
@@ -44408,6 +44553,60 @@ async function buildContainerSpec(args) {
 		...debugPort !== void 0 && { debugPort },
 		...tmpfs !== void 0 && { tmpfs }
 	};
+	return {
+		kind: "image",
+		lambda,
+		image: imageRef,
+		platform,
+		command: lambda.imageConfig.command ?? [],
+		...lambda.imageConfig.entryPoint !== void 0 && lambda.imageConfig.entryPoint.length > 0 && { entryPoint: lambda.imageConfig.entryPoint },
+		...lambda.imageConfig.workingDirectory !== void 0 && { workingDir: lambda.imageConfig.workingDirectory },
+		env: dockerEnv,
+		containerHost,
+		...debugPort !== void 0 && { debugPort },
+		...tmpfs !== void 0 && { tmpfs }
+	};
+}
+/**
+* Resolve a container Lambda's local docker image — local build from
+* `cdk.out` asset manifest first, ECR-pull fallback when the asset
+* manifest has no matching entry. Mirrors `cdkd local invoke`'s
+* `resolveContainerImagePlan` shape; the start-api server doesn't
+* need the no-build flag (deterministic-tag cache reuse is automatic
+* across reloads because the per-Lambda tag is content-addressed).
+*
+* Same-account / same-region only on the ECR-pull path (matches the
+* `cdkd local invoke` PR 5 of #224 boundary). Cross-account /
+* cross-region ECR pull is the W2-1 deferred follow-up.
+*/
+async function resolveContainerImageForStartApi(lambda, skipPull) {
+	const logger = getLogger();
+	const localBuild = await resolveLocalBuildPlan$1(lambda);
+	if (localBuild) return { imageRef: await buildContainerImage(localBuild.asset, localBuild.cdkOutDir, { architecture: lambda.architecture }) };
+	if (!parseEcrUri(lambda.imageUri)) throw new Error(`Container Lambda '${lambda.logicalId}' has no matching asset in cdk.out, and Code.ImageUri '${lambda.imageUri}' is not an ECR URI cdkd can authenticate against. Re-synthesize the CDK app (so cdk.out includes the build context) or deploy the image to ECR first.`);
+	logger.info(`No matching cdk.out asset for ${lambda.imageUri}; falling back to ECR pull (same-acct/region only)...`);
+	return { imageRef: await pullEcrImage(lambda.imageUri, { skipPull }) };
+}
+/**
+* Look up the docker image asset that backs a container Lambda.
+* Returns `undefined` when the asset manifest has no matching entry —
+* the caller falls back to the ECR-pull path.
+*
+* Mirrors `local-invoke.ts:resolveLocalBuildPlan`; kept separate so
+* the two commands evolve their asset-lookup heuristics independently.
+*/
+async function resolveLocalBuildPlan$1(lambda) {
+	const manifestPath = lambda.stack.assetManifestPath;
+	if (!manifestPath) return void 0;
+	const cdkOutDir = path.dirname(manifestPath);
+	const manifest = await new AssetManifestLoader().loadManifest(cdkOutDir, lambda.stack.stackName);
+	if (!manifest) return void 0;
+	const entry = getDockerImageBySourceHash(manifest, lambda.imageUri);
+	if (!entry) return void 0;
+	return {
+		asset: entry.asset,
+		cdkOutDir
+	};
 }
 /**
 * Build the `/opt` bind-mount source for a Lambda's layers. Mirrors
@@ -44469,15 +44668,23 @@ function resolveLambdaByLogicalId(logicalId, stacks) {
 		const resource = stack.template.Resources?.[logicalId];
 		if (!resource || resource.Type !== "AWS::Lambda::Function") continue;
 		const props = resource.Properties ?? {};
-		const runtime = typeof props["Runtime"] === "string" ? props["Runtime"] : "";
-		const handler = typeof props["Handler"] === "string" ? props["Handler"] : "";
 		const memoryMb = typeof props["MemorySize"] === "number" ? props["MemorySize"] : 128;
 		const timeoutSec = typeof props["Timeout"] === "number" ? props["Timeout"] : 3;
-		if (!runtime) throw new Error(`Lambda '${logicalId}' has no Runtime property. Container-image Lambdas (Code.ImageUri) are not supported in cdkd local start-api v1.`);
-		if (!handler) throw new Error(`Lambda '${logicalId}' has no Handler property.`);
 		const code = props["Code"] ?? {};
-		const imageUri = code["ImageUri"];
-		if (typeof imageUri === "string" || typeof imageUri === "object" && imageUri !== null && "Fn::Sub" in imageUri) throw new Error(`Lambda '${logicalId}' uses Code.ImageUri (container-image Lambda). 'cdkd local start-api' v1 supports ZIP Lambdas only — container-image support is deferred to a follow-up PR. Use 'cdkd local invoke' to exercise this function locally.`);
+		const imageUri = extractImageUri(code["ImageUri"]);
+		if (imageUri !== void 0) return resolveImageLambda({
+			stack,
+			logicalId,
+			resource,
+			props,
+			memoryMb,
+			timeoutSec,
+			imageUri
+		});
+		const runtime = typeof props["Runtime"] === "string" ? props["Runtime"] : "";
+		const handler = typeof props["Handler"] === "string" ? props["Handler"] : "";
+		if (!runtime) throw new Error(`Lambda '${logicalId}' has no Runtime property and no Code.ImageUri. cdkd local start-api cannot tell if this is a ZIP or a container Lambda.`);
+		if (!handler) throw new Error(`Lambda '${logicalId}' has no Handler property.`);
 		const inlineCode = typeof code["ZipFile"] === "string" ? code["ZipFile"] : void 0;
 		let codePath = null;
 		if (!inlineCode) codePath = resolveAssetCodePath(stack, logicalId, resource);
@@ -44501,6 +44708,66 @@ function resolveLambdaByLogicalId(logicalId, stacks) {
 	throw new Error(`No AWS::Lambda::Function resource named '${logicalId}' found in target stacks. This is likely a synthesis bug — the route-discovery phase resolved a route to this logical ID.`);
 }
 /**
+* Extract `Code.ImageUri` across the shapes CDK actually synthesizes.
+* Mirrors the simpler subset of `lambda-resolver.ts:extractImageUri`
+* scoped to the shapes `cdkd local start-api` consumes — flat string
+* and `Fn::Sub` (the canonical asset shape for
+* `lambda.DockerImageCode.fromImageAsset`). `Fn::Join` shapes for
+* `lambda.DockerImageCode.fromEcr` are deferred to a follow-up: the
+* start-api boot flow doesn't yet load cdkd state up front, and the
+* `Fn::Join` resolver needs it to recover same-stack ECR repository
+* URIs. When the user hits the unsupported shape, the downstream
+* resolveLocalBuildPlan / pullEcrImage path surfaces a clear error.
+*
+* Returns `undefined` when the field is absent or non-recognized,
+* which routes the caller to the ZIP branch (with its existing
+* "no Runtime / no Handler" validations).
+*/
+function extractImageUri(value) {
+	if (typeof value === "string" && value.length > 0) return value;
+	if (value && typeof value === "object" && !Array.isArray(value)) {
+		const sub = value["Fn::Sub"];
+		if (typeof sub === "string" && sub.length > 0) return sub;
+		if (Array.isArray(sub) && typeof sub[0] === "string") return sub[0];
+	}
+}
+/**
+* Build the IMAGE-variant `ResolvedStartApiLambda` from a Lambda
+* template entry with `Code.ImageUri`. Mirrors
+* `lambda-resolver.ts:extractImageLambdaProperties` but trimmed to the
+* fields `cdkd local start-api` actually consumes.
+*/
+function resolveImageLambda(args) {
+	const { stack, logicalId, resource, props, memoryMb, timeoutSec, imageUri } = args;
+	const rawImageConfig = props["ImageConfig"] ?? {};
+	const imageConfig = {};
+	if (Array.isArray(rawImageConfig["Command"])) imageConfig.command = rawImageConfig["Command"].filter((s) => typeof s === "string");
+	if (Array.isArray(rawImageConfig["EntryPoint"])) imageConfig.entryPoint = rawImageConfig["EntryPoint"].filter((s) => typeof s === "string");
+	if (typeof rawImageConfig["WorkingDirectory"] === "string") imageConfig.workingDirectory = rawImageConfig["WorkingDirectory"];
+	const arches = props["Architectures"];
+	let architecture = "x86_64";
+	if (Array.isArray(arches) && arches.length > 0) {
+		const first = arches[0];
+		if (first === "arm64") architecture = "arm64";
+		else if (first === "x86_64") architecture = "x86_64";
+		else throw new Error(`Lambda '${logicalId}' has unsupported Architectures value '${String(first)}'. cdkd local start-api supports x86_64 and arm64.`);
+	}
+	const ephemeralStorageMb = extractEphemeralStorageMb(props, logicalId);
+	return {
+		kind: "image",
+		stack,
+		logicalId,
+		resource,
+		memoryMb,
+		timeoutSec,
+		imageUri,
+		imageConfig,
+		architecture,
+		layers: [],
+		...ephemeralStorageMb !== void 0 && { ephemeralStorageMb }
+	};
+}
+/**
 * Locate the Lambda's local code directory using the CDK-blessed
 * `Metadata['aws:asset:path']` hint. Bind-mounted directly at
 * `/var/task` (read-only) by the docker-runner.
@@ -47011,7 +47278,10 @@ async function exportCommand(stackArg, options) {
 			const phase1Template = filterTemplateForImport(template, phase1Imports);
 			const injectedCount = injectDeletionPolicyForImport(phase1Template);
 			if (injectedCount > 0) logger.info(`Injected DeletionPolicy: Delete on ${injectedCount} resource(s) without an explicit DeletionPolicy (required by CFn IMPORT — matches the CDK/CFn default for resources without RemovalPolicy).`);
-			await executeImportChangeSet(awsClients.cloudFormation, cfnStackName, phase1Template, phase1Imports, cfnParameters, templateFormat);
+			await executeImportChangeSet(awsClients.cloudFormation, cfnStackName, phase1Template, phase1Imports, cfnParameters, templateFormat, {
+				stateBucket,
+				...options.profile && { s3ClientOpts: { profile: options.profile } }
+			});
 			logger.info(`✓ Phase 1: CloudFormation stack '${cfnStackName}' created via IMPORT. ${phase1Imports.length} resource(s) imported.`);
 			if (recreateBeforePhase2.length > 0) for (const entry of recreateBeforePhase2) {
 				const handler = PRE_DELETE_HANDLERS[entry.resourceType];
@@ -47028,7 +47298,10 @@ async function exportCommand(stackArg, options) {
 			const phase2Count = phase2Creates.length + recreateBeforePhase2.length;
 			if (phase2Count > 0) try {
 				const phase2Template = applyImportOverlayForPhase2(template, phase1Imports);
-				await executeUpdateChangeSet(awsClients.cloudFormation, cfnStackName, phase2Template, cfnParameters, templateFormat);
+				await executeUpdateChangeSet(awsClients.cloudFormation, cfnStackName, phase2Template, cfnParameters, templateFormat, {
+					stateBucket,
+					...options.profile && { s3ClientOpts: { profile: options.profile } }
+				});
 				const parts = [];
 				if (phase2Creates.length > 0) parts.push(`${phase2Creates.length} non-importable resource(s) CREATEd`);
 				if (recreateBeforePhase2.length > 0) parts.push(`${recreateBeforePhase2.length} IMPORT-unsupported resource(s) re-CREATEd`);
@@ -47644,7 +47917,84 @@ function printPlan(plan, cfnStackName) {
 	}
 	logger.info("");
 }
-async function executeImportChangeSet(cfnClient, stackName, template, plan, parameters, templateFormat = "json") {
+/**
+* Decide whether to submit a CFn changeset's template inline via
+* `TemplateBody` or upload it to the cdkd state bucket and submit via
+* `TemplateURL`. Returns a discriminated outcome:
+*
+*   - `kind: 'inline'`  — payload <= 51,200 bytes; pass `TemplateBody`
+*     directly. No S3 round-trip; the caller's `finally` cleanup is a
+*     no-op.
+*   - `kind: 'url'`     — payload in (51,200, 1,048,576] bytes; helper
+*     uploaded to `cdkd-migrate-tmp/<stackName>/<ts>.{json,yaml}`. The
+*     caller MUST invoke the returned `cleanup` in a `finally` so the
+*     transient object is deleted regardless of CFn success / failure.
+*
+* Payloads > 1,048,576 bytes throw pre-flight (the 1 MB ceiling applies
+* to every CFn API surface; no S3 indirection helps). The error names the
+* top inline-payload contributors so the user knows what to shrink.
+*
+* `phaseLabel` is interpolated into the pre-flight error so the user
+* sees which phase tripped the ceiling ("phase-1 IMPORT" vs "phase-2
+* UPDATE").
+*
+* When `uploadOpts` is undefined (e.g. unit tests that exercise only the
+* inline path), templates over the inline limit throw with a clear
+* "no upload bucket configured" error rather than silently failing on a
+* downstream CFn rejection.
+*
+* `templateFormat` (default `'json'`) drives the transient S3 object's
+* key suffix + Content-Type so YAML-authored templates stay YAML on the
+* wire (`.yaml` / `application/x-yaml`).
+*/
+async function selectChangeSetTemplateSource(template, templateBody, uploadOpts, stackName, phaseLabel, templateFormat = "json") {
+	const logger = getLogger();
+	if (templateBody.length <= 51200) return {
+		kind: "inline",
+		templateBody,
+		cleanup: async () => void 0
+	};
+	if (templateBody.length > 1048576) {
+		const offenders = findLargeInlineResources(template);
+		let detail = "";
+		if (offenders.length > 0) {
+			detail = `\nLargest inline payloads (move these to lambda.Code.fromAsset or split into nested stacks):\n${offenders.slice(0, 10).map((o) => `  - ${o.logicalId} (${o.resourceType}): ~${o.approxBytes} bytes`).join("\n")}`;
+			if (offenders.length > 10) detail += `\n  (and ${offenders.length - 10} more above the 4096-byte threshold)`;
+		}
+		throw new Error(`${phaseLabel} template is ${templateBody.length} bytes, over the ${CFN_TEMPLATE_URL_LIMIT}-byte CloudFormation TemplateURL limit. Templates that large cannot be submitted to CloudFormation — shrink inline payloads (e.g. inline Lambda Code.ZipFile larger than ~4 KB → switch to lambda.Code.fromAsset) or split the stack into nested AWS::CloudFormation::Stack resources.${detail}`);
+	}
+	if (!uploadOpts) throw new Error(`${phaseLabel} template is ${templateBody.length} bytes, over the inline ${CFN_TEMPLATE_BODY_LIMIT}-byte TemplateBody limit, but no upload bucket was provided to selectChangeSetTemplateSource — pass uploadOpts to enable the TemplateURL upload path.`);
+	logger.info(`  Template is ${templateBody.length} bytes (over ${CFN_TEMPLATE_BODY_LIMIT} inline limit) — uploading to state bucket '${uploadOpts.stateBucket}'.`);
+	const uploaded = await uploadCfnTemplate({
+		bucket: uploadOpts.stateBucket,
+		body: templateBody,
+		stackName,
+		format: templateFormat,
+		...uploadOpts.s3ClientOpts && { s3ClientOpts: uploadOpts.s3ClientOpts }
+	});
+	return {
+		kind: "url",
+		templateUrl: uploaded.url,
+		cleanup: uploaded.cleanup
+	};
+}
+/**
+* Best-effort wrapper around the `cleanup` callback returned by
+* {@link selectChangeSetTemplateSource}. Mirrors the warn-on-failure
+* pattern from `retireCloudFormationStack` so a stranded `cdkd-migrate-tmp/`
+* object never blocks the calling command — it lives under an obviously
+* named prefix and can be reaped manually.
+*/
+async function runTemplateUploadCleanup(cleanup, bucket) {
+	const logger = getLogger();
+	try {
+		await cleanup();
+	} catch (cleanupErr) {
+		const msg = cleanupErr instanceof Error ? cleanupErr.message : String(cleanupErr);
+		logger.warn(`Failed to delete temporary template upload from '${bucket}'. Clean up manually under prefix 'cdkd-migrate-tmp/'. Cause: ${msg}`);
+	}
+}
+async function executeImportChangeSet(cfnClient, stackName, template, plan, parameters, templateFormat = "json", uploadOpts) {
 	const logger = getLogger();
 	const changeSetName = `cdkd-migrate-${Date.now()}`;
 	const templateBody = stringifyCfnTemplate(template, templateFormat);
@@ -47654,67 +48004,71 @@ async function executeImportChangeSet(cfnClient, stackName, template, plan, para
 		ResourceIdentifier: entry.resourceIdentifier
 	}));
 	logger.info(`Creating IMPORT changeset '${changeSetName}' for stack '${stackName}' (${plan.length} resource(s), ${templateBody.length} bytes)...`);
-	if (templateBody.length > 51200) throw new Error(`Filtered template is ${templateBody.length} bytes, over the 51,200-byte inline TemplateBody limit. Templates that large require TemplateURL upload (not yet implemented for cdkd export; please file an issue if you hit this).`);
+	const source = await selectChangeSetTemplateSource(template, templateBody, uploadOpts, stackName, "Filtered phase-1 IMPORT", templateFormat);
 	try {
-		await cfnClient.send(new CreateChangeSetCommand({
-			StackName: stackName,
-			ChangeSetName: changeSetName,
-			ChangeSetType: "IMPORT",
-			TemplateBody: templateBody,
-			ResourcesToImport: resourcesToImport,
-			...parameters.length > 0 && { Parameters: parameters },
-			Capabilities: [
-				"CAPABILITY_IAM",
-				"CAPABILITY_NAMED_IAM",
-				"CAPABILITY_AUTO_EXPAND"
-			]
-		}));
-	} catch (err) {
-		const msg = err instanceof Error ? err.message : String(err);
-		throw new Error(`Failed to create IMPORT changeset: ${msg}`);
-	}
-	try {
-		await waitUntilChangeSetCreateComplete({
-			client: cfnClient,
-			maxWaitTime: 600
-		}, {
-			StackName: stackName,
-			ChangeSetName: changeSetName
-		});
-	} catch (err) {
 		try {
-			const reason = (await cfnClient.send(new DescribeChangeSetCommand({
+			await cfnClient.send(new CreateChangeSetCommand({
+				StackName: stackName,
+				ChangeSetName: changeSetName,
+				ChangeSetType: "IMPORT",
+				...source.kind === "inline" ? { TemplateBody: source.templateBody } : { TemplateURL: source.templateUrl },
+				ResourcesToImport: resourcesToImport,
+				...parameters.length > 0 && { Parameters: parameters },
+				Capabilities: [
+					"CAPABILITY_IAM",
+					"CAPABILITY_NAMED_IAM",
+					"CAPABILITY_AUTO_EXPAND"
+				]
+			}));
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			throw new Error(`Failed to create IMPORT changeset: ${msg}`);
+		}
+		try {
+			await waitUntilChangeSetCreateComplete({
+				client: cfnClient,
+				maxWaitTime: 600
+			}, {
 				StackName: stackName,
 				ChangeSetName: changeSetName
-			}))).StatusReason ?? "unknown";
+			});
+		} catch (err) {
+			try {
+				const reason = (await cfnClient.send(new DescribeChangeSetCommand({
+					StackName: stackName,
+					ChangeSetName: changeSetName
+				}))).StatusReason ?? "unknown";
+				await cfnClient.send(new DeleteChangeSetCommand({
+					StackName: stackName,
+					ChangeSetName: changeSetName
+				})).catch(() => {});
+				throw new Error(`IMPORT changeset FAILED: ${reason}`);
+			} catch (innerErr) {
+				if (innerErr instanceof Error && innerErr.message.startsWith("IMPORT changeset FAILED")) throw innerErr;
+				throw err;
+			}
+		}
+		logger.info(`Executing IMPORT changeset...`);
+		try {
+			await cfnClient.send(new ExecuteChangeSetCommand({
+				StackName: stackName,
+				ChangeSetName: changeSetName
+			}));
+			await waitUntilStackImportComplete({
+				client: cfnClient,
+				maxWaitTime: 3600
+			}, { StackName: stackName });
+		} catch (err) {
+			const failureSummary = await collectImportFailureSummary(cfnClient, stackName).catch(() => "");
 			await cfnClient.send(new DeleteChangeSetCommand({
 				StackName: stackName,
 				ChangeSetName: changeSetName
 			})).catch(() => {});
-			throw new Error(`IMPORT changeset FAILED: ${reason}`);
-		} catch (innerErr) {
-			if (innerErr instanceof Error && innerErr.message.startsWith("IMPORT changeset FAILED")) throw innerErr;
+			if (failureSummary) throw new Error(`IMPORT changeset failed:\n${failureSummary}`, { cause: err });
 			throw err;
 		}
-	}
-	logger.info(`Executing IMPORT changeset...`);
-	try {
-		await cfnClient.send(new ExecuteChangeSetCommand({
-			StackName: stackName,
-			ChangeSetName: changeSetName
-		}));
-		await waitUntilStackImportComplete({
-			client: cfnClient,
-			maxWaitTime: 3600
-		}, { StackName: stackName });
-	} catch (err) {
-		const failureSummary = await collectImportFailureSummary(cfnClient, stackName).catch(() => "");
-		await cfnClient.send(new DeleteChangeSetCommand({
-			StackName: stackName,
-			ChangeSetName: changeSetName
-		})).catch(() => {});
-		if (failureSummary) throw new Error(`IMPORT changeset failed:\n${failureSummary}`, { cause: err });
-		throw err;
+	} finally {
+		await runTemplateUploadCleanup(source.cleanup, uploadOpts?.stateBucket ?? "");
 	}
 }
 /**
@@ -47758,69 +48112,73 @@ async function collectImportFailureSummary(cfnClient, stackName) {
 * (cdkd state is intentionally NOT deleted between phases, so a phase-2
 * failure leaves a recoverable state).
 */
-async function executeUpdateChangeSet(cfnClient, stackName, template, parameters, templateFormat = "json") {
+async function executeUpdateChangeSet(cfnClient, stackName, template, parameters, templateFormat = "json", uploadOpts) {
 	const logger = getLogger();
 	const changeSetName = `cdkd-phase2-${Date.now()}`;
 	const templateBody = stringifyCfnTemplate(template, templateFormat);
-	if (templateBody.length > 51200) throw new Error(`Full template is ${templateBody.length} bytes, over the 51,200-byte inline TemplateBody limit for phase-2 UPDATE. TemplateURL upload is not yet implemented.`);
 	logger.info(`Creating UPDATE changeset '${changeSetName}' for phase 2 (${templateBody.length} bytes)...`);
+	const source = await selectChangeSetTemplateSource(template, templateBody, uploadOpts, stackName, "Phase-2 UPDATE", templateFormat);
 	try {
-		await cfnClient.send(new CreateChangeSetCommand({
-			StackName: stackName,
-			ChangeSetName: changeSetName,
-			ChangeSetType: "UPDATE",
-			TemplateBody: templateBody,
-			...parameters.length > 0 && { Parameters: parameters },
-			Capabilities: [
-				"CAPABILITY_IAM",
-				"CAPABILITY_NAMED_IAM",
-				"CAPABILITY_AUTO_EXPAND"
-			]
-		}));
-	} catch (err) {
-		const msg = err instanceof Error ? err.message : String(err);
-		throw new Error(`Failed to create UPDATE changeset: ${msg}`);
-	}
-	try {
-		await waitUntilChangeSetCreateComplete({
-			client: cfnClient,
-			maxWaitTime: 600
-		}, {
-			StackName: stackName,
-			ChangeSetName: changeSetName
-		});
-	} catch (err) {
 		try {
-			const reason = (await cfnClient.send(new DescribeChangeSetCommand({
+			await cfnClient.send(new CreateChangeSetCommand({
+				StackName: stackName,
+				ChangeSetName: changeSetName,
+				ChangeSetType: "UPDATE",
+				...source.kind === "inline" ? { TemplateBody: source.templateBody } : { TemplateURL: source.templateUrl },
+				...parameters.length > 0 && { Parameters: parameters },
+				Capabilities: [
+					"CAPABILITY_IAM",
+					"CAPABILITY_NAMED_IAM",
+					"CAPABILITY_AUTO_EXPAND"
+				]
+			}));
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			throw new Error(`Failed to create UPDATE changeset: ${msg}`);
+		}
+		try {
+			await waitUntilChangeSetCreateComplete({
+				client: cfnClient,
+				maxWaitTime: 600
+			}, {
 				StackName: stackName,
 				ChangeSetName: changeSetName
-			}))).StatusReason ?? "unknown";
+			});
+		} catch (err) {
+			try {
+				const reason = (await cfnClient.send(new DescribeChangeSetCommand({
+					StackName: stackName,
+					ChangeSetName: changeSetName
+				}))).StatusReason ?? "unknown";
+				await cfnClient.send(new DeleteChangeSetCommand({
+					StackName: stackName,
+					ChangeSetName: changeSetName
+				})).catch(() => {});
+				throw new Error(`UPDATE changeset FAILED: ${reason}`);
+			} catch (innerErr) {
+				if (innerErr instanceof Error && innerErr.message.startsWith("UPDATE changeset FAILED")) throw innerErr;
+				throw err;
+			}
+		}
+		logger.info(`Executing UPDATE changeset...`);
+		try {
+			await cfnClient.send(new ExecuteChangeSetCommand({
+				StackName: stackName,
+				ChangeSetName: changeSetName
+			}));
+			await waitUntilStackUpdateComplete({
+				client: cfnClient,
+				maxWaitTime: 3600
+			}, { StackName: stackName });
+		} catch (err) {
 			await cfnClient.send(new DeleteChangeSetCommand({
 				StackName: stackName,
 				ChangeSetName: changeSetName
 			})).catch(() => {});
-			throw new Error(`UPDATE changeset FAILED: ${reason}`);
-		} catch (innerErr) {
-			if (innerErr instanceof Error && innerErr.message.startsWith("UPDATE changeset FAILED")) throw innerErr;
 			throw err;
 		}
-	}
-	logger.info(`Executing UPDATE changeset...`);
-	try {
-		await cfnClient.send(new ExecuteChangeSetCommand({
-			StackName: stackName,
-			ChangeSetName: changeSetName
-		}));
-		await waitUntilStackUpdateComplete({
-			client: cfnClient,
-			maxWaitTime: 3600
-		}, { StackName: stackName });
-	} catch (err) {
-		await cfnClient.send(new DeleteChangeSetCommand({
-			StackName: stackName,
-			ChangeSetName: changeSetName
-		})).catch(() => {});
-		throw err;
+	} finally {
+		await runTemplateUploadCleanup(source.cleanup, uploadOpts?.stateBucket ?? "");
 	}
 }
 /**
@@ -47939,7 +48297,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.126.0");
+	program.name("cdkd").description("CDK Direct - Deploy AWS CDK apps directly via SDK/Cloud Control API").version("0.128.0");
 	program.addCommand(createBootstrapCommand());
 	program.addCommand(createSynthCommand());
 	program.addCommand(createListCommand());