@go-to-k/cdkd 0.123.0 → 0.125.0

package/dist/cli.js

@@ -19,9 +19,9 @@ 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, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { cpSync, createWriteStream, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
 import * as path from "node:path";
-import { dirname, isAbsolute, resolve } from "node:path";
+import { dirname, isAbsolute, join, normalize, resolve } from "node:path";
 import { execFile, spawn } from "node:child_process";
 import { tmpdir } from "node:os";
 import { AssociateVPCWithHostedZoneCommand, ChangeResourceRecordSetsCommand, ChangeTagsForResourceCommand, CreateHostedZoneCommand, CreateQueryLoggingConfigCommand, DeleteHostedZoneCommand, DeleteQueryLoggingConfigCommand, DisassociateVPCFromHostedZoneCommand, GetHostedZoneCommand, ListHostedZonesByNameCommand, ListHostedZonesCommand, ListQueryLoggingConfigsCommand, ListResourceRecordSetsCommand, ListTagsForResourceCommand as ListTagsForResourceCommand$6, Route53Client, UpdateHostedZoneCommentCommand } from "@aws-sdk/client-route-53";
@@ -56,6 +56,10 @@ import { CreateVectorBucketCommand, DeleteIndexCommand, DeleteVectorBucketComman
 import { CreateNamespaceCommand, CreateTableBucketCommand, CreateTableCommand as CreateTableCommand$2, DeleteNamespaceCommand as DeleteNamespaceCommand$1, DeleteTableBucketCommand, DeleteTableCommand as DeleteTableCommand$2, GetTableBucketCommand, GetTableCommand as GetTableCommand$1, ListNamespacesCommand as ListNamespacesCommand$1, ListTableBucketsCommand, ListTablesCommand as ListTablesCommand$1, ListTagsForResourceCommand as ListTagsForResourceCommand$19, NotFoundException as NotFoundException$5, S3TablesClient } from "@aws-sdk/client-s3tables";
 import { AttachTrafficSourcesCommand, AutoScalingClient, CreateAutoScalingGroupCommand, DeleteAutoScalingGroupCommand, DeleteLifecycleHookCommand, DeleteNotificationConfigurationCommand, DescribeAutoScalingGroupsCommand, DescribeLifecycleHooksCommand, DescribeNotificationConfigurationsCommand, DescribeTrafficSourcesCommand, DetachTrafficSourcesCommand, DisableMetricsCollectionCommand, EnableMetricsCollectionCommand, PutLifecycleHookCommand, PutNotificationConfigurationCommand, UpdateAutoScalingGroupCommand } from "@aws-sdk/client-auto-scaling";
 import * as readline from "node:readline/promises";
+import { Document, Pair, Scalar, YAMLMap, YAMLSeq, parse as parse$1, stringify } from "yaml";
+import { mkdir, mkdtemp } from "node:fs/promises";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
 import { createServer } from "node:net";
 import { promisify } from "node:util";
 import { setTimeout as setTimeout$1 } from "node:timers/promises";
@@ -34744,6 +34748,307 @@ function createStateCommand() {
 	return cmd;
 }
 
+//#endregion
+//#region src/cli/yaml-cfn.ts
+/**
+* CloudFormation-aware YAML codec.
+*
+* Parses + serializes CFn templates while preserving every CFn shorthand
+* intrinsic tag (`!Ref`, `!GetAtt`, `!Sub`, `!Join`, ...) — generic YAML
+* libraries silently strip these tags on parse + re-emit, corrupting the
+* template. cdkd uses this codec on both directions of CFn migration:
+* `cdkd export` (cdkd → CFn IMPORT) and
+* `cdkd import --migrate-from-cloudformation` (CFn → cdkd state).
+*
+* Algorithm: each `!Foo` tag is registered as a YAML custom tag whose
+* resolver returns the long-form object shape `{Fn::Foo: <args>}` (or
+* `{Ref: <name>}` for the bare `!Ref`). On stringify, the same objects
+* are detected and emitted back to shorthand tag form. The internal
+* model cdkd carries between parse and stringify is the long-form object
+* shape — same shape JSON produces — so every downstream consumer
+* (`injectRetainPolicies`, `executeImportChangeSet`, etc.) reads one
+* representation.
+*
+* Each tag is registered three times (scalar / sequence / map) per the
+* `yaml` library's API contract — a single registration only matches one
+* collection shape. Nested intrinsics resolve recursively via
+* `node.toJSON()` (the yaml lib resolves child customTags before invoking
+* the parent resolver).
+*
+* Format detection sniffs the first non-whitespace byte: `{` or `[` →
+* JSON; anything else → YAML. Empty input rejected as JSON so the
+* caller's existing JSON-empty-input error path fires.
+*
+* Tag set supported (matches the AWS docs canonical list):
+*   `!Ref`, `!GetAtt`, `!Sub`, `!Join`, `!Select`, `!Split`,
+*   `!If`, `!Equals`, `!And`, `!Or`, `!Not`,
+*   `!FindInMap`, `!Base64`, `!Cidr`, `!GetAZs`, `!ImportValue`,
+*   `!Transform`, `!Condition` (used inside `Conditions:` references).
+*
+* `!GetAtt` accepts BOTH the scalar dot-delimited shape
+* (`!GetAtt LogicalId.Attribute.Path`) and the sequence shape
+* (`!GetAtt [LogicalId, Attribute]`); both round-trip back to the scalar
+* form when the attribute is a single string segment (the AWS-published
+* canonical shape), or to the sequence form when the attribute is itself
+* a sequence.
+*/
+/**
+* Tags whose long-form key uses the `Fn::` prefix. `!Ref`, `!Condition`,
+* and `!Transform` are special-cased separately because their long-form
+* key shape differs.
+*/
+const FN_TAGS = [
+	"GetAtt",
+	"Sub",
+	"Join",
+	"Select",
+	"Split",
+	"If",
+	"Equals",
+	"And",
+	"Or",
+	"Not",
+	"FindInMap",
+	"Base64",
+	"Cidr",
+	"GetAZs",
+	"ImportValue",
+	"Length",
+	"ToJsonString",
+	"ForEach"
+];
+function nodeJs(node) {
+	if (node === null || node === void 0) return null;
+	if (typeof node === "object" && node !== null && "toJSON" in node) return node.toJSON();
+	return node;
+}
+/**
+* Build the set of custom YAML tags cdkd registers. Each tag may need
+* up to 3 entries (scalar / seq / map) so every shape an AWS-published
+* template carries is accepted; un-templated shapes for a given tag
+* fall through to the lib's default tag resolution (which the lib
+* surfaces as a warning — never an error — by design).
+*
+* `identify: () => false` on every entry: we never want the lib to
+* auto-tag a parsed result on stringify. We build the YAML output via
+* our own `jsToYamlNode` walk that emits the tag explicitly.
+*/
+function buildCustomTags() {
+	const tags = [];
+	tags.push({
+		tag: "!Ref",
+		resolve(value) {
+			return { Ref: value };
+		},
+		identify: () => false
+	});
+	tags.push({
+		tag: "!Condition",
+		resolve(value) {
+			return { Condition: value };
+		},
+		identify: () => false
+	});
+	tags.push({
+		tag: "!Transform",
+		collection: "map",
+		resolve(node) {
+			return { "Fn::Transform": nodeJs(node) };
+		},
+		identify: () => false
+	});
+	tags.push({
+		tag: "!GetAtt",
+		resolve(value) {
+			const dot = value.indexOf(".");
+			if (dot < 0) throw new Error(`!GetAtt requires '<LogicalId>.<Attribute>'; got '${value}'`);
+			return { "Fn::GetAtt": [value.slice(0, dot), value.slice(dot + 1)] };
+		},
+		identify: () => false
+	});
+	tags.push({
+		tag: "!GetAtt",
+		collection: "seq",
+		resolve(node) {
+			return { "Fn::GetAtt": nodeJs(node) };
+		},
+		identify: () => false
+	});
+	for (const name of FN_TAGS) {
+		if (name === "GetAtt") continue;
+		const longKey = `Fn::${name}`;
+		tags.push({
+			tag: `!${name}`,
+			resolve(value) {
+				return { [longKey]: value };
+			},
+			identify: () => false
+		});
+		tags.push({
+			tag: `!${name}`,
+			collection: "seq",
+			resolve(node) {
+				return { [longKey]: nodeJs(node) };
+			},
+			identify: () => false
+		});
+		tags.push({
+			tag: `!${name}`,
+			collection: "map",
+			resolve(node) {
+				return { [longKey]: nodeJs(node) };
+			},
+			identify: () => false
+		});
+	}
+	return tags;
+}
+const CUSTOM_TAGS = buildCustomTags();
+/**
+* Parse a CFn template string. JSON or YAML, auto-detected.
+*
+* @throws Error with a clear message when the input is empty, malformed,
+*   or does not produce an object root.
+*/
+function parseCfnTemplate(text) {
+	const format = detectTemplateFormat(text);
+	const body = text.charCodeAt(0) === 65279 ? text.slice(1) : text;
+	let parsed;
+	if (format === "json") try {
+		parsed = JSON.parse(body);
+	} catch (err) {
+		throw new Error(`Template is not valid JSON. Cause: ${err instanceof Error ? err.message : String(err)}`);
+	}
+	else try {
+		parsed = parse$1(body, { customTags: CUSTOM_TAGS });
+	} catch (err) {
+		throw new Error(`Template is not valid YAML. Cause: ${err instanceof Error ? err.message : String(err)}`);
+	}
+	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error(`Template root is not an object.`);
+	return parsed;
+}
+/**
+* Serialize a CFn template back to JSON or YAML. The `format` parameter
+* controls the output shape; callers should pass the result of the
+* original `detectTemplateFormat` (or remembered from `parseCfnTemplate`)
+* so a YAML-authored template stays YAML on round-trip.
+*
+* YAML output emits CFn intrinsics back to shorthand tags (`!Ref`,
+* `!GetAtt`, etc.) by walking the JS object tree before passing it to
+* `yaml.stringify`. Long-form `{Fn::Foo: <args>}` objects are converted
+* to `Document` nodes carrying the appropriate `!Foo` tag.
+*
+* JSON output is two-space-indented to match cdkd's existing canonical
+* shape.
+*/
+function stringifyCfnTemplate(template, format) {
+	if (format === "json") return JSON.stringify(template, null, 2);
+	const doc = new Document();
+	doc.contents = jsToYamlNode(template, doc);
+	return stringify(doc, {
+		aliasDuplicateObjects: false,
+		lineWidth: 0
+	});
+}
+/**
+* Convert a plain JS value into a YAML node, detecting CFn intrinsics and
+* emitting them with their shorthand tag. Recursive — every sub-tree is
+* inspected.
+*/
+function jsToYamlNode(value, doc) {
+	if (value === null || value === void 0) return new Scalar(null);
+	if (typeof value !== "object") return doc.createNode(value);
+	if (Array.isArray(value)) {
+		const seq = new YAMLSeq();
+		for (const item of value) seq.items.push(jsToYamlNode(item, doc));
+		return seq;
+	}
+	const keys = Object.keys(value);
+	if (keys.length === 1) {
+		const k = keys[0];
+		const v = value[k];
+		const tag = intrinsicShorthandFor(k);
+		if (tag) return makeIntrinsicNode(tag, v, doc);
+	}
+	const map = new YAMLMap();
+	for (const [k, v] of Object.entries(value)) map.items.push(new Pair(doc.createNode(k), jsToYamlNode(v, doc)));
+	return map;
+}
+/**
+* Map a long-form intrinsic key (`Ref` / `Fn::Foo` / `Condition`) to its
+* shorthand tag (`!Ref` / `!Foo` / `!Condition`). Returns null when the
+* key is not a recognized intrinsic.
+*/
+function intrinsicShorthandFor(key) {
+	if (key === "Ref") return "!Ref";
+	if (key === "Condition") return "!Condition";
+	if (!key.startsWith("Fn::")) return null;
+	const name = key.slice(4);
+	if (name === "Transform") return "!Transform";
+	if (name === "GetAtt") return "!GetAtt";
+	if (FN_TAGS.includes(name)) return `!${name}`;
+	return null;
+}
+/**
+* Build a YAML node carrying a CFn shorthand tag. Tag-specific shapes:
+*   - `!Ref` / `!Condition` → scalar (the referenced name).
+*   - `!GetAtt` → scalar `LogicalId.Attribute` when the long-form arg
+*     is `[LogicalId, Attribute]` of strings; sequence form otherwise.
+*   - Everything else → whatever shape the long-form arg has
+*     (scalar / sequence / map).
+*/
+function makeIntrinsicNode(tag, value, doc) {
+	if (tag === "!Ref" || tag === "!Condition") {
+		const s = new Scalar(typeof value === "string" ? value : String(value));
+		s.tag = tag;
+		return s;
+	}
+	if (tag === "!GetAtt") {
+		if (Array.isArray(value) && value.length === 2 && typeof value[0] === "string" && typeof value[1] === "string") {
+			const s = new Scalar(`${value[0]}.${value[1]}`);
+			s.tag = tag;
+			return s;
+		}
+		const node = jsToYamlNode(value, doc);
+		node.tag = tag;
+		return node;
+	}
+	const node = jsToYamlNode(value, doc);
+	node.tag = tag;
+	return node;
+}
+/**
+* Sniff the input text and decide whether to parse it as JSON or YAML.
+*
+* Rule (matches AWS docs / CDK CLI): if the first non-whitespace byte is
+* `{` or `[`, parse as JSON; otherwise YAML. Empty input is treated as
+* JSON so the caller's existing JSON-empty-input error path fires.
+*
+* UTF-8 BOM (``) is stripped before the sniff — some editors /
+* scripts emit BOM-prefixed files, and the BOM is NOT whitespace under
+* `trimStart()`, so a BOM-prefixed JSON file would otherwise route to
+* the YAML parser and fail.
+*/
+function detectTemplateFormat(text) {
+	const trimmed = (text.charCodeAt(0) === 65279 ? text.slice(1) : text).trimStart();
+	if (trimmed.length === 0) return "json";
+	const first = trimmed.charCodeAt(0);
+	if (first === 123 || first === 91) return "json";
+	return "yaml";
+}
+/**
+* Parse a CFn template + return both the parsed object AND the source
+* format, so the caller can later re-emit in the same shape. Convenience
+* wrapper around `parseCfnTemplate` + `detectTemplateFormat`.
+*/
+function parseCfnTemplateWithFormat(text) {
+	const format = detectTemplateFormat(text);
+	return {
+		template: parseCfnTemplate(text),
+		format
+	};
+}
+
 //#endregion
 //#region src/cli/commands/retire-cfn-stack.ts
 /**
@@ -34823,7 +35128,7 @@ async function retireCloudFormationStack(options) {
 		TemplateStage: "Original"
 	}));
 	if (!tpl.TemplateBody) throw new Error(`GetTemplate returned no body for '${cfnStackName}'.`);
-	const { body: newBody, modified } = injectRetainPolicies(tpl.TemplateBody, cfnStackName);
+	const { body: newBody, modified, format } = injectRetainPolicies(tpl.TemplateBody, cfnStackName);
 	if (!yes) {
 		if (!await confirmPrompt$2(`Set DeletionPolicy=Retain and UpdateReplacePolicy=Retain on every resource in CloudFormation stack '${cfnStackName}', then delete the stack? AWS resources will NOT be deleted (cdkd state has been written).`)) {
 			logger.info("CloudFormation stack retirement cancelled. cdkd state is unaffected.");
@@ -34843,6 +35148,7 @@ async function retireCloudFormationStack(options) {
 				bucket: stateBucket,
 				body: newBody,
 				cfnStackName,
+				format,
 				...s3ClientOpts && { s3ClientOpts }
 			});
 			updateInput = { TemplateURL: uploaded.url };
@@ -34904,7 +35210,7 @@ async function retireCloudFormationStack(options) {
 * Exported for unit testing.
 */
 async function uploadTemplateForUpdateStack(args) {
-	const { bucket, body, cfnStackName, s3ClientOpts } = args;
+	const { bucket, body, cfnStackName, format, s3ClientOpts } = args;
 	const region = await resolveBucketRegion(bucket, {
 		...s3ClientOpts?.profile && { profile: s3ClientOpts.profile },
 		...s3ClientOpts?.credentials && { credentials: s3ClientOpts.credentials }
@@ -34914,13 +35220,15 @@ async function uploadTemplateForUpdateStack(args) {
 		...s3ClientOpts?.profile && { profile: s3ClientOpts.profile },
 		...s3ClientOpts?.credentials && { credentials: s3ClientOpts.credentials }
 	});
-	const key = `${MIGRATE_TMP_PREFIX}/${cfnStackName}/${Date.now()}.json`;
+	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: "application/json"
+			ContentType: contentType
 		}));
 	} catch (err) {
 		s3.destroy();
@@ -34943,33 +35251,32 @@ async function uploadTemplateForUpdateStack(args) {
 	};
 }
 /**
-* Parse a CloudFormation template body (JSON), set `DeletionPolicy: Retain`
-* and `UpdateReplacePolicy: Retain` on every resource that doesn't already
-* have those exact values, and re-serialize.
+* Parse a CloudFormation template body (JSON or YAML), set
+* `DeletionPolicy: Retain` and `UpdateReplacePolicy: Retain` on every
+* resource that doesn't already have those exact values, and re-serialize
+* in the SAME format as the input. Returns the resulting body, a
+* `modified` flag, and the detected source format so callers can stamp
+* the right content type / S3 key extension on follow-up uploads.
 *
-* JSON-only by design. The `--migrate-from-cloudformation` flow's primary
-* upstream is `cdk migrate` (which produces a CDK app whose synthesized
-* template is always JSON) followed by `cdk deploy` / `cdkd deploy` (also
-* JSON). Adding YAML support would require parsing CloudFormation
-* shorthand intrinsics (`!Ref`, `!Sub`, `!GetAtt`, …) which round-trip
-* incorrectly through generic YAML libraries — a generic YAML
-* unmarshal/remarshal silently strips the custom tags and corrupts the
-* template. Until a CFn-aware YAML codec is in scope, hand-written YAML
-* stacks are best retired with the manual 3-step procedure.
+* YAML templates are routed through cdkd's CFn-aware YAML codec
+* (`src/cli/yaml-cfn.ts`), which preserves every CFn shorthand intrinsic
+* (`!Ref`, `!GetAtt`, `!Sub`, etc.) on round-trip. JSON templates take
+* the canonical two-space-indented JSON path.
 *
 * Exported for unit testing (the AWS round-trips are mocked, but the
 * mutation logic itself is pure and worth exercising directly).
 */
 function injectRetainPolicies(templateBody, cfnStackName) {
+	const format = detectTemplateFormat(templateBody);
 	let parsed;
 	try {
-		parsed = JSON.parse(templateBody);
+		parsed = parseCfnTemplate(templateBody);
 	} catch (err) {
-		throw new Error(`Template for '${cfnStackName}' is not valid JSON. cdkd's --migrate-from-cloudformation flow only supports CDK-generated (JSON) templates. Cause: ${err instanceof Error ? err.message : String(err)}`);
+		throw new Error(`Template for '${cfnStackName}' is not a valid CloudFormation template. cdkd's --migrate-from-cloudformation flow supports both JSON and YAML templates (YAML via a CFn-aware codec that preserves !Ref / !GetAtt / !Sub shorthand). Cause: ${err instanceof Error ? err.message : String(err)}`);
 	}
-	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed) || !("Resources" in parsed) || typeof parsed.Resources !== "object" || parsed.Resources === null) throw new Error(`Template for '${cfnStackName}' has no Resources section — refusing to retire.`);
+	if (!("Resources" in parsed) || typeof parsed["Resources"] !== "object" || parsed["Resources"] === null || Array.isArray(parsed["Resources"])) throw new Error(`Template for '${cfnStackName}' has no Resources section — refusing to retire.`);
 	let modified = false;
-	const resources = parsed.Resources;
+	const resources = parsed["Resources"];
 	for (const [, resource] of Object.entries(resources)) {
 		if (!resource || typeof resource !== "object" || Array.isArray(resource)) continue;
 		const r = resource;
@@ -34983,8 +35290,9 @@ function injectRetainPolicies(templateBody, cfnStackName) {
 		}
 	}
 	return {
-		body: JSON.stringify(parsed, null, 2),
-		modified
+		body: stringifyCfnTemplate(parsed, format),
+		modified,
+		format
 	};
 }
 /**
@@ -36382,16 +36690,23 @@ function resolveAssetCodePath$1(stack, logicalId, resource) {
 * bind mounts at the same target so cdkd cannot rely on overlay
 * layering.
 *
-* **Out of scope (hard-errors)**:
+* **Same-stack handling** (`{Ref: <Id>}` / `{Fn::GetAtt: [<Id>, 'Ref']}`):
+*
+*   - Refs that don't point at an `AWS::Lambda::LayerVersion` resource
+*     hard-error — almost always a typo'd logical ID.
+*   - Refs to a `LayerVersion` whose `Metadata['aws:asset:path']` is
+*     missing hard-error — the layer's content is `S3Bucket` / `S3Key`
+*     from outside cdk.out and there's no local directory to bind-mount.
 *
-*   - Literal ARN strings (`arn:aws:lambda:...`) — these are external /
-*     pre-existing layers (no asset on disk to mount) including
-*     cross-account / cross-region.
-*   - Same-stack refs that don't point at an `AWS::Lambda::LayerVersion`
-*     resource — almost always a typo'd logical ID.
-*   - Same-stack refs to a `LayerVersion` whose `Metadata['aws:asset:path']`
-*     is missing — the layer's content is `S3Bucket` / `S3Key` from
-*     outside cdk.out and there's no local directory to bind-mount.
+* **Literal-ARN handling** (issue #448): entries shaped like the string
+* `arn:aws:lambda:<region>:<account>:layer:<name>:<version>` are parsed
+* into a `{kind: 'arn', ...}` resolved layer. The actual
+* `lambda:GetLayerVersion` + presigned-URL download + unzip happens
+* later in the CLI (`materializeLayerFromArn(...)`), which can optionally
+* `sts:AssumeRole` into the layer's account when the dev's default
+* credentials cannot read it. Covers AWS-published public layers (Lambda
+* Powertools, Datadog Extension, etc.) and cross-account / cross-region
+* shared layers.
 */
 function resolveLambdaLayers(stack, logicalId, props) {
 	const layers = props["Layers"];
@@ -36402,13 +36717,24 @@ function resolveLambdaLayers(stack, logicalId, props) {
 	const out = [];
 	for (let i = 0; i < layers.length; i++) {
 		const entry = layers[i];
+		if (typeof entry === "string") {
+			const parsed = parseLayerVersionArn(entry);
+			if (!parsed) throw new LocalInvokeResolutionError(`Lambda '${logicalId}' has a Layers entry [${i}] cdkd cannot resolve locally: literal string '${entry}'. Expected a same-stack Ref / Fn::GetAtt to an AWS::Lambda::LayerVersion OR a literal layer-version ARN of the form arn:aws:lambda:<region>:<account>:layer:<name>:<version>.`);
+			out.push({
+				kind: "arn",
+				logicalId: parsed.arn,
+				...parsed
+			});
+			continue;
+		}
 		const layerLogicalId = pickLayerLogicalId(entry);
-		if (!layerLogicalId) throw new LocalInvokeResolutionError(`Lambda '${logicalId}' has a Layers entry [${i}] cdkd cannot resolve locally: ${describeLayerEntry(entry)}. Only same-stack Ref / Fn::GetAtt to an AWS::Lambda::LayerVersion are supported in v1; cross-account / cross-region / pre-existing-ARN layers are deferred to a follow-up PR.`);
+		if (!layerLogicalId) throw new LocalInvokeResolutionError(`Lambda '${logicalId}' has a Layers entry [${i}] cdkd cannot resolve locally: ${describeLayerEntry(entry)}. Expected a same-stack Ref / Fn::GetAtt to an AWS::Lambda::LayerVersion OR a literal layer-version ARN of the form arn:aws:lambda:<region>:<account>:layer:<name>:<version>.`);
 		const layerResource = resources[layerLogicalId];
 		if (!layerResource) throw new LocalInvokeResolutionError(`Lambda '${logicalId}' Layers entry [${i}] references '${layerLogicalId}', but no resource with that logical ID exists in stack '${stack.stackName}'.`);
 		if (layerResource.Type !== "AWS::Lambda::LayerVersion") throw new LocalInvokeResolutionError(`Lambda '${logicalId}' Layers entry [${i}] references '${layerLogicalId}' (${layerResource.Type}), which is not an AWS::Lambda::LayerVersion.`);
 		const assetPath = resolveAssetCodePath$1(stack, layerLogicalId, layerResource);
 		out.push({
+			kind: "asset",
 			logicalId: layerLogicalId,
 			assetPath
 		});
@@ -36416,6 +36742,29 @@ function resolveLambdaLayers(stack, logicalId, props) {
 	return out;
 }
 /**
+* Parse a Lambda layer-version ARN string into its segments.
+*
+* Returns `undefined` for anything that does not match the strict
+* `arn:aws:lambda:<region>:<account>:layer:<name>:<version>` shape so
+* the caller can produce a clearer error than a silent
+* misinterpretation of hand-edited templates. The partition segment
+* accepts `aws` / `aws-cn` / `aws-us-gov` so GovCloud / China-region
+* ARNs work without code changes.
+*
+* Exported for unit testing.
+*/
+function parseLayerVersionArn(input) {
+	const m = /^arn:(aws|aws-cn|aws-us-gov):lambda:([a-z]{2}-(?:[a-z]+-){1,2}\d+):(\d{12}):layer:([A-Za-z0-9_-]+):(\d+)$/.exec(input);
+	if (!m) return void 0;
+	return {
+		arn: input,
+		region: m[2],
+		accountId: m[3],
+		name: m[4],
+		version: m[5]
+	};
+}
+/**
 * Walk a single Layers-array entry and return the referenced layer's
 * logical ID — or `undefined` for shapes we don't try to resolve in v1.
 *
@@ -36484,6 +36833,195 @@ function notFoundError$1(target, stack, resources) {
 	return new LocalInvokeResolutionError(msg.trimEnd());
 }
 
+//#endregion
+//#region src/local/layer-arn-materializer.ts
+var LayerMaterializationError = class LayerMaterializationError extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "LayerMaterializationError";
+		Object.setPrototypeOf(this, LayerMaterializationError.prototype);
+	}
+};
+async function materializeLayerFromArn(layer, options = {}) {
+	const logger = getLogger();
+	let credentials;
+	if (options.roleArn) try {
+		credentials = await assumeRoleForLayer(options.roleArn, layer.region, options);
+		logger.debug(`Layer ${layer.arn}: assumed role ${options.roleArn} for GetLayerVersion`);
+	} catch (err) {
+		throw new LayerMaterializationError(`Layer ${layer.arn}: STS AssumeRole(${options.roleArn}) failed: ${errMsg(err)}. Check the role trust policy permits your principal and sts:AssumeRole is allowed.`);
+	}
+	let presignedUrl;
+	try {
+		presignedUrl = await fetchLayerContentUrl(layer, credentials, options);
+	} catch (err) {
+		const hint = looksLikeAccessDenied(err) ? " GetLayerVersion access denied; check the credentials / role can read the layer (grant lambda:GetLayerVersion on the layer ARN, or pass --layer-role-arn <arn> to assume a role in the layer account)." : "";
+		throw new LayerMaterializationError(`Layer ${layer.arn}: GetLayerVersion failed in region ${layer.region}: ${errMsg(err)}.${hint}`);
+	}
+	let zipBytes;
+	try {
+		zipBytes = await downloadPresignedZip(presignedUrl, options);
+	} catch (err) {
+		throw new LayerMaterializationError(`Layer ${layer.arn}: failed to download layer ZIP from the presigned URL: ${errMsg(err)}.`);
+	}
+	const dir = await mkdtemp(join(tmpdir(), `cdkd-local-arn-layer-${layer.name}-${layer.version}-`));
+	try {
+		await unzipBufferToDirectory(zipBytes, dir);
+	} catch (err) {
+		try {
+			rmSync(dir, {
+				recursive: true,
+				force: true
+			});
+		} catch {}
+		throw new LayerMaterializationError(`Layer ${layer.arn}: failed to unzip layer contents into '${dir}': ${errMsg(err)}.`);
+	}
+	return dir;
+}
+async function fetchLayerContentUrl(layer, credentials, options) {
+	const client = (options.lambdaClientFactory ?? await defaultLambdaClientFactory())(layer.region, credentials);
+	try {
+		const command = await buildGetLayerVersionCommand(`arn:aws:lambda:${layer.region}:${layer.accountId}:layer:${layer.name}`, Number(layer.version));
+		const url = (await client.send(command))?.Content?.Location;
+		if (!url || typeof url !== "string") throw new Error("GetLayerVersion response did not include Content.Location (presigned ZIP URL)");
+		return url;
+	} finally {
+		client.destroy?.();
+	}
+}
+async function assumeRoleForLayer(roleArn, region, options) {
+	const client = (options.stsClientFactory ?? await defaultStsClientFactory())(region);
+	try {
+		const command = await buildAssumeRoleCommand(roleArn);
+		const creds = (await client.send(command))?.Credentials;
+		if (!creds?.AccessKeyId || !creds.SecretAccessKey) throw new Error("AssumeRole returned no Credentials");
+		return {
+			accessKeyId: creds.AccessKeyId,
+			secretAccessKey: creds.SecretAccessKey,
+			...creds.SessionToken !== void 0 && { sessionToken: creds.SessionToken }
+		};
+	} finally {
+		client.destroy?.();
+	}
+}
+async function defaultLambdaClientFactory() {
+	const { LambdaClient } = await import("@aws-sdk/client-lambda");
+	return (region, credentials) => new LambdaClient({
+		region,
+		...credentials && { credentials: {
+			accessKeyId: credentials.accessKeyId,
+			secretAccessKey: credentials.secretAccessKey,
+			...credentials.sessionToken !== void 0 && { sessionToken: credentials.sessionToken }
+		} }
+	});
+}
+async function defaultStsClientFactory() {
+	const { STSClient } = await import("@aws-sdk/client-sts");
+	return (region) => new STSClient({ region });
+}
+async function buildGetLayerVersionCommand(layerArn, versionNumber) {
+	const { GetLayerVersionCommand } = await import("@aws-sdk/client-lambda");
+	return new GetLayerVersionCommand({
+		LayerName: layerArn,
+		VersionNumber: versionNumber
+	});
+}
+async function buildAssumeRoleCommand(roleArn) {
+	const { AssumeRoleCommand } = await import("@aws-sdk/client-sts");
+	return new AssumeRoleCommand({
+		RoleArn: roleArn,
+		RoleSessionName: `cdkd-local-layer-${Date.now()}`,
+		DurationSeconds: 3600
+	});
+}
+async function downloadPresignedZip(presignedUrl, options) {
+	if (options.fetchZip) return options.fetchZip(presignedUrl);
+	const response = await fetch(presignedUrl);
+	if (!response.ok) throw new Error(`HTTP ${response.status} ${response.statusText} from layer Content.Location URL`);
+	const buf = await response.arrayBuffer();
+	return new Uint8Array(buf);
+}
+/**
+* Minimal ZIP unzipper that handles the subset of the ZIP format Lambda
+* layer ZIPs ever use (DEFLATE compression method 8, STORE method 0).
+* Avoids bringing in a heavyweight dep for a 50-line task.
+*
+* Path-traversal guard: every entry's relative path is `normalize()`d
+* and rejected if the resulting absolute path escapes `destDir` (the
+* "Zip Slip" CVE class). Symlinks inside the ZIP are also rejected for
+* the same reason — they could point at arbitrary host paths.
+*/
+async function unzipBufferToDirectory(zipBytes, destDir) {
+	const view = new DataView(zipBytes.buffer, zipBytes.byteOffset, zipBytes.byteLength);
+	const eocdSig = 101010256;
+	const minScan = Math.max(0, zipBytes.byteLength - 65535 - 22);
+	let eocdOffset = -1;
+	for (let i = zipBytes.byteLength - 22; i >= minScan; i--) if (view.getUint32(i, true) === eocdSig) {
+		eocdOffset = i;
+		break;
+	}
+	if (eocdOffset < 0) throw new Error("Not a ZIP file (no End of Central Directory record found)");
+	const totalEntries = view.getUint16(eocdOffset + 10, true);
+	const cdSize = view.getUint32(eocdOffset + 12, true);
+	const cdOffset = view.getUint32(eocdOffset + 16, true);
+	const destAbsolute = resolve(destDir);
+	let cursor = cdOffset;
+	const cdEnd = cdOffset + cdSize;
+	let parsed = 0;
+	while (cursor < cdEnd && parsed < totalEntries) {
+		if (view.getUint32(cursor, true) !== 33639248) throw new Error(`Corrupt ZIP: missing Central Directory header at offset ${cursor}`);
+		const compressionMethod = view.getUint16(cursor + 10, true);
+		const compressedSize = view.getUint32(cursor + 20, true);
+		const uncompressedSize = view.getUint32(cursor + 24, true);
+		const fileNameLength = view.getUint16(cursor + 28, true);
+		const extraFieldLength = view.getUint16(cursor + 30, true);
+		const fileCommentLength = view.getUint16(cursor + 32, true);
+		const externalAttrs = view.getUint32(cursor + 38, true);
+		const localHeaderOffset = view.getUint32(cursor + 42, true);
+		const fileName = new TextDecoder("utf-8").decode(zipBytes.subarray(cursor + 46, cursor + 46 + fileNameLength));
+		cursor += 46 + fileNameLength + extraFieldLength + fileCommentLength;
+		parsed++;
+		const targetPath = resolve(destAbsolute, normalize(fileName));
+		if (!targetPath.startsWith(destAbsolute + (destAbsolute.endsWith("/") ? "" : "/"))) throw new Error(`Refusing to extract entry '${fileName}' — path escapes the destination directory`);
+		if ((externalAttrs >>> 16 & 61440) === 40960) throw new Error(`Refusing to extract symlink entry '${fileName}' from layer ZIP (security)`);
+		if (fileName.endsWith("/")) {
+			await mkdir(targetPath, { recursive: true });
+			continue;
+		}
+		await mkdir(dirname(targetPath), { recursive: true });
+		if (view.getUint32(localHeaderOffset, true) !== 67324752) throw new Error(`Corrupt ZIP: missing Local File Header for '${fileName}'`);
+		const lfhFileNameLength = view.getUint16(localHeaderOffset + 26, true);
+		const lfhExtraFieldLength = view.getUint16(localHeaderOffset + 28, true);
+		const dataOffset = localHeaderOffset + 30 + lfhFileNameLength + lfhExtraFieldLength;
+		const compressedData = zipBytes.subarray(dataOffset, dataOffset + compressedSize);
+		let payload;
+		if (compressionMethod === 0) payload = compressedData;
+		else if (compressionMethod === 8) payload = await inflateRaw(compressedData);
+		else throw new Error(`Unsupported ZIP compression method ${compressionMethod} for entry '${fileName}' (only STORE and DEFLATE supported)`);
+		if (payload.length !== uncompressedSize && compressionMethod !== 0) throw new Error(`ZIP entry '${fileName}': inflate produced ${payload.length} bytes, expected ${uncompressedSize}`);
+		await pipeline(Readable.from(payload), createWriteStream(targetPath));
+	}
+}
+async function inflateRaw(data) {
+	const { inflateRaw: inflate } = await import("node:zlib");
+	return new Promise((resolveP, rejectP) => {
+		inflate(data, (err, out) => {
+			if (err) rejectP(err);
+			else resolveP(out);
+		});
+	});
+}
+function errMsg(err) {
+	return err instanceof Error ? err.message : String(err);
+}
+function looksLikeAccessDenied(err) {
+	if (!(err instanceof Error)) return false;
+	const name = err.name ?? "";
+	const code = err.Code ?? "";
+	const message = err.message ?? "";
+	return name === "AccessDeniedException" || code === "AccessDeniedException" || /access denied/i.test(message) || /not authorized/i.test(message);
+}
+
 //#endregion
 //#region src/local/env-resolver.ts
 /**
@@ -43362,7 +43900,8 @@ async function localStartApiCommand(target, options) {
 				stsRegion: options.region ?? process.env["AWS_REGION"] ?? process.env["AWS_DEFAULT_REGION"],
 				inlineTmpDirs,
 				layerTmpDirs,
-				stateByStack
+				stateByStack,
+				...options.layerRoleArn !== void 0 && { layerRoleArn: options.layerRoleArn }
 			});
 			specs.set(logicalId, spec);
 		}
@@ -43672,10 +44211,10 @@ function warnIamRoutes(routesWithAuth) {
 * missing, runtime not supported).
 */
 async function buildContainerSpec(args) {
-	const { logicalId, stacks, overrides, assumeRole, containerHost, debugPort, stsRegion, inlineTmpDirs, layerTmpDirs, stateByStack } = args;
+	const { logicalId, stacks, overrides, assumeRole, containerHost, debugPort, stsRegion, inlineTmpDirs, layerTmpDirs, stateByStack, layerRoleArn } = args;
 	const lambda = resolveLambdaByLogicalId(logicalId, stacks);
 	const codeDir = lambda.codePath ?? materializeInlineCode$1(lambda.handler, lambda.inlineCode ?? "", resolveRuntimeFileExtension(lambda.runtime), inlineTmpDirs);
-	const optDir = materializeLambdaLayers$1(lambda.layers, layerTmpDirs);
+	const optDir = await materializeLambdaLayers$1(lambda.layers, layerTmpDirs, layerRoleArn);
 	let templateEnv = getTemplateEnv$1(lambda.resource);
 	const stateBundle = stateByStack.get(lambda.stack.stackName);
 	let stateAudit;
@@ -43734,22 +44273,46 @@ async function buildContainerSpec(args) {
 *
 * Three branches:
 *   - 0 layers → `undefined` (no `/opt` mount).
-*   - 1 layer → bind-mount the layer's asset dir directly (no copy).
+*   - 1 layer → bind-mount the layer's asset dir directly (no copy)
+*     when the entry is a same-stack asset. Literal-ARN entries always
+*     pre-materialize first.
 *   - 2+ layers → copy each into a fresh tmpdir IN ORDER (later
 *     layers overwrite earlier files via `cpSync({force: true})`),
 *     bind-mount the tmpdir at `/opt`. Records the tmpdir in
 *     `layerTmpDirs` so `shutdown(...)` removes it.
 *
+* Issue #448: literal-ARN entries (`{kind: 'arn', ...}`) are downloaded
+* + unzipped via `lambda:GetLayerVersion` BEFORE the cpSync-merge
+* branches run. Every per-ARN tmpdir is also recorded in `layerTmpDirs`
+* so the same shutdown path cleans it up — even for the single-layer
+* fast path that bind-mounts the dir directly.
+*
 * AWS Lambda's actual runtime extracts every layer ZIP into `/opt`
 * in template order — the merge mirrors that. Docker rejects multiple
 * `-v ...:/opt:ro` entries at the same target, so cdkd can't rely on
 * overlay layering and must produce a single merged dir on the host.
 */
-function materializeLambdaLayers$1(layers, layerTmpDirs) {
+async function materializeLambdaLayers$1(layers, layerTmpDirs, layerRoleArn) {
 	if (layers.length === 0) return void 0;
-	if (layers.length === 1) return layers[0].assetPath;
+	const flat = [];
+	for (const layer of layers) {
+		if (layer.kind === "asset") {
+			flat.push({
+				logicalId: layer.logicalId,
+				assetPath: layer.assetPath
+			});
+			continue;
+		}
+		const dir = await materializeLayerFromArn(layer, { ...layerRoleArn !== void 0 && { roleArn: layerRoleArn } });
+		layerTmpDirs.add(dir);
+		flat.push({
+			logicalId: layer.arn,
+			assetPath: dir
+		});
+	}
+	if (flat.length === 1) return flat[0].assetPath;
 	const dir = mkdtempSync(path.join(tmpdir(), "cdkd-local-start-api-layers-"));
-	for (const layer of layers) cpSync(layer.assetPath, dir, {
+	for (const layer of flat) cpSync(layer.assetPath, dir, {
 		recursive: true,
 		force: true
 	});
@@ -44154,7 +44717,7 @@ function parseDebugPort(raw) {
 * Builder for the `start-api` subcommand. Wired up by `local.ts`.
 */
 function createLocalStartApiCommand() {
-	const startApi = new Command("start-api").description("Run a long-running local HTTP server that maps API Gateway routes (REST v1, HTTP API, Function URL) to Lambda invocations against the AWS Lambda Runtime Interface Emulator (Docker required). Supports Lambda TOKEN/REQUEST authorizers, Cognito User Pool / HTTP v2 JWT authorizers, and REST v1 AWS_IAM (SigV4 signature verification only — IAM policy evaluation is NOT emulated; see docs/local-emulation.md). When JWKS is unreachable, JWT authorizers fall back to pass-through (every token accepted) with a warn line — local dev fallback. VPC-config Lambdas run locally and surface a warn line at startup; their containers do NOT get attached to the deployed VPC subnets, so calls to private RDS / ElastiCache will fail.").argument("[target]", "Optional API filter. Accepts the bare CDK logical id ('MyHttpApi'; single-stack apps only), stack-qualified logical id ('MyStack:MyHttpApi'), full CDK Construct path ('MyStack/MyHttpApi/Resource'), or an ancestor Construct path that prefix-matches ('MyStack/MyHttpApi'). When omitted, every discovered API gets its own server. Mirrors `cdkd local invoke` / `cdkd local run-task` target syntax.").addOption(new Option("--port <port>", "HTTP server port (default: auto-allocate)").default("0")).addOption(new Option("--host <host>", "Bind address").default("127.0.0.1")).addOption(new Option("--stack <name>", "Stack to start (single-stack apps auto-detect)")).addOption(new Option("--warm", "Pre-start one container per Lambda at server boot").default(false)).addOption(new Option("--per-lambda-concurrency <n>", "Pool size cap per Lambda (default 2, max 4)").default("2")).addOption(new Option("--no-pull", "Skip docker pull (cached image)")).addOption(new Option("--container-host <host>", "IP the host uses to bind/probe the RIE port (must be a numeric IP — `docker run -p <ip>:<port>:8080` rejects hostnames). Defaults to 127.0.0.1.").default("127.0.0.1")).addOption(new Option("--debug-port-base <port>", "Reserve a contiguous --debug-port range (one per Lambda)")).addOption(new Option("--env-vars <file>", "JSON env-var overrides (SAM-compatible: {\"LogicalId\":{\"KEY\":\"VALUE\"}, \"Parameters\": {...}})")).addOption(new Option("--assume-role <arn-or-pair>", "Assume the Lambda's execution role and forward STS-issued temp creds. Bare <arn> = global default; <LogicalId>=<arn> = per-Lambda override (repeatable). Per-Lambda > global > unset (developer creds passed through).").argParser((raw, prev) => parseAssumeRoleToken(raw, prev))).addOption(new Option("--watch", "Hot-reload: re-synth + re-discover routes when cdk.out/ or asset directories change. Off by default; the server keeps the previous version serving when synth fails mid-reload.").default(false)).addOption(new Option("--stage <name>", "Select an API Gateway Stage by its 'StageName'. Default: the first Stage attached to each API. Drives event.stageVariables for both REST v1 and HTTP API v2. NOTE: For HTTP API v2 routes, requestContext.stage is always '$default' regardless of this flag (AWS-side limitation — HTTP API only exposes one stage to the integration event); only event.stageVariables is affected for v2 routes. For REST v1 routes the selected StageName is also threaded into requestContext.stage.")).addOption(new Option("--api <id>", "DEPRECATED — use the positional <target> argument instead. Same accepted forms (bare logical id, stack-qualified, Construct path, ancestor prefix). Will be removed in a future major release.")).addOption(new Option("--from-state", "Read cdkd S3 state for every routed stack and substitute Ref / Fn::GetAtt / Fn::Sub / Fn::Join (and AWS pseudo parameters) in Lambda env vars with the deployed physical IDs / attributes. Off by default — pre-PR warn-and-drop semantics are preserved. Turn on for stacks already deployed via cdkd deploy. Mirrors `cdkd local invoke --from-state` / `cdkd local run-task --from-state`. Re-runs against fresh state on every hot-reload firing (--watch).").default(false)).addOption(new Option("--stack-region <region>", "Region of the cdkd state record to read (used with --from-state when the same stack name has state in multiple regions).")).addOption(new Option("--allow-unverified-sigv4", "Opt-in: allow AWS_IAM SigV4 requests that cannot be cryptographically verified (foreign access-key-id, OR no local AWS credentials configured) to pass through with a placeholder principalId. DEFAULT off — fail-closed so unauthenticated bypass is impossible against `event.requestContext.identity.accessKey`-trusting handler code. Use only in dev loops where you understand the risk.").default(false)).action(withErrorHandling(localStartApiCommand));
+	const startApi = new Command("start-api").description("Run a long-running local HTTP server that maps API Gateway routes (REST v1, HTTP API, Function URL) to Lambda invocations against the AWS Lambda Runtime Interface Emulator (Docker required). Supports Lambda TOKEN/REQUEST authorizers, Cognito User Pool / HTTP v2 JWT authorizers, and REST v1 AWS_IAM (SigV4 signature verification only — IAM policy evaluation is NOT emulated; see docs/local-emulation.md). When JWKS is unreachable, JWT authorizers fall back to pass-through (every token accepted) with a warn line — local dev fallback. VPC-config Lambdas run locally and surface a warn line at startup; their containers do NOT get attached to the deployed VPC subnets, so calls to private RDS / ElastiCache will fail.").argument("[target]", "Optional API filter. Accepts the bare CDK logical id ('MyHttpApi'; single-stack apps only), stack-qualified logical id ('MyStack:MyHttpApi'), full CDK Construct path ('MyStack/MyHttpApi/Resource'), or an ancestor Construct path that prefix-matches ('MyStack/MyHttpApi'). When omitted, every discovered API gets its own server. Mirrors `cdkd local invoke` / `cdkd local run-task` target syntax.").addOption(new Option("--port <port>", "HTTP server port (default: auto-allocate)").default("0")).addOption(new Option("--host <host>", "Bind address").default("127.0.0.1")).addOption(new Option("--stack <name>", "Stack to start (single-stack apps auto-detect)")).addOption(new Option("--warm", "Pre-start one container per Lambda at server boot").default(false)).addOption(new Option("--per-lambda-concurrency <n>", "Pool size cap per Lambda (default 2, max 4)").default("2")).addOption(new Option("--no-pull", "Skip docker pull (cached image)")).addOption(new Option("--container-host <host>", "IP the host uses to bind/probe the RIE port (must be a numeric IP — `docker run -p <ip>:<port>:8080` rejects hostnames). Defaults to 127.0.0.1.").default("127.0.0.1")).addOption(new Option("--debug-port-base <port>", "Reserve a contiguous --debug-port range (one per Lambda)")).addOption(new Option("--env-vars <file>", "JSON env-var overrides (SAM-compatible: {\"LogicalId\":{\"KEY\":\"VALUE\"}, \"Parameters\": {...}})")).addOption(new Option("--assume-role <arn-or-pair>", "Assume the Lambda's execution role and forward STS-issued temp creds. Bare <arn> = global default; <LogicalId>=<arn> = per-Lambda override (repeatable). Per-Lambda > global > unset (developer creds passed through).").argParser((raw, prev) => parseAssumeRoleToken(raw, prev))).addOption(new Option("--watch", "Hot-reload: re-synth + re-discover routes when cdk.out/ or asset directories change. Off by default; the server keeps the previous version serving when synth fails mid-reload.").default(false)).addOption(new Option("--stage <name>", "Select an API Gateway Stage by its 'StageName'. Default: the first Stage attached to each API. Drives event.stageVariables for both REST v1 and HTTP API v2. NOTE: For HTTP API v2 routes, requestContext.stage is always '$default' regardless of this flag (AWS-side limitation — HTTP API only exposes one stage to the integration event); only event.stageVariables is affected for v2 routes. For REST v1 routes the selected StageName is also threaded into requestContext.stage.")).addOption(new Option("--api <id>", "DEPRECATED — use the positional <target> argument instead. Same accepted forms (bare logical id, stack-qualified, Construct path, ancestor prefix). Will be removed in a future major release.")).addOption(new Option("--layer-role-arn <arn>", "Role to sts:AssumeRole before calling lambda:GetLayerVersion on every literal-ARN entry in Properties.Layers (issue #448). Use only when the dev credentials cannot read the layer — typically cross-account layers. AWS-published public layers (e.g. Lambda Powertools) are readable from every account and need no role.")).addOption(new Option("--from-state", "Read cdkd S3 state for every routed stack and substitute Ref / Fn::GetAtt / Fn::Sub / Fn::Join (and AWS pseudo parameters) in Lambda env vars with the deployed physical IDs / attributes. Off by default — pre-PR warn-and-drop semantics are preserved. Turn on for stacks already deployed via cdkd deploy. Mirrors `cdkd local invoke --from-state` / `cdkd local run-task --from-state`. Re-runs against fresh state on every hot-reload firing (--watch).").default(false)).addOption(new Option("--stack-region <region>", "Region of the cdkd state record to read (used with --from-state when the same stack name has state in multiple regions).")).addOption(new Option("--allow-unverified-sigv4", "Opt-in: allow AWS_IAM SigV4 requests that cannot be cryptographically verified (foreign access-key-id, OR no local AWS credentials configured) to pass through with a placeholder principalId. DEFAULT off — fail-closed so unauthenticated bypass is impossible against `event.requestContext.identity.accessKey`-trusting handler code. Use only in dev loops where you understand the risk.").default(false)).action(withErrorHandling(localStartApiCommand));
 	[
 		...commonOptions,
 		...appOptions,
@@ -45257,6 +45820,14 @@ async function localInvokeCommand(target, options) {
 		} catch (err) {
 			getLogger().debug(`Failed to remove merged-layers tmpdir ${imagePlan.layersTmpDir}: ${err instanceof Error ? err.message : String(err)}`);
 		}
+		if (imagePlan?.layerArnTmpDirs) for (const dir of imagePlan.layerArnTmpDirs) try {
+			rmSync(dir, {
+				recursive: true,
+				force: true
+			});
+		} catch (err) {
+			getLogger().debug(`Failed to remove ARN-layer tmpdir ${dir}: ${err instanceof Error ? err.message : String(err)}`);
+		}
 	}, (err) => {
 		getLogger().debug(`cleanup failed: ${err instanceof Error ? err.message : String(err)}`);
 	});
@@ -45442,7 +46013,7 @@ async function resolveZipImagePlan(lambda, options) {
 	}
 	const image = resolveRuntimeImage(lambda.runtime);
 	await pullImage(image, options.pull === false);
-	const layerPlan = materializeLambdaLayers(lambda.layers);
+	const layerPlan = await materializeLambdaLayersIncludingArns(lambda.layers, options);
 	const containerCodePath = resolveRuntimeCodeMountPath(lambda.runtime);
 	const tmpfs = resolveTmpfsForLambda(lambda);
 	return {
@@ -45456,10 +46027,48 @@ async function resolveZipImagePlan(lambda, options) {
 		cmd: [lambda.handler],
 		...inlineTmpDir !== void 0 && { inlineTmpDir },
 		...layerPlan.tmpDir !== void 0 && { layersTmpDir: layerPlan.tmpDir },
+		...layerPlan.extraTmpDirs.length > 0 && { layerArnTmpDirs: layerPlan.extraTmpDirs },
 		...tmpfs !== void 0 && { tmpfs }
 	};
 }
 /**
+* Two-stage layer materialization (issue #448).
+*
+*   - Stage 1: every `{kind: 'arn'}` entry is downloaded + unzipped
+*     into its own tmpdir via `materializeLayerFromArn`. The per-ARN
+*     tmpdirs are tracked in `extraTmpDirs` so the outer cleanup can
+*     remove them.
+*   - Stage 2: the resulting `{logicalId, assetPath}[]` list (in
+*     template order — ARN entries surface their `arn` as the
+*     `logicalId` for log lines) is handed to the existing
+*     `materializeLambdaLayers` `cpSync`-merge path. AWS's "last layer
+*     wins" file-collision semantic is preserved across both layer
+*     kinds because the merge step is unchanged.
+*/
+async function materializeLambdaLayersIncludingArns(layers, options) {
+	const extraTmpDirs = [];
+	const flat = [];
+	for (const layer of layers) {
+		if (layer.kind === "asset") {
+			flat.push({
+				logicalId: layer.logicalId,
+				assetPath: layer.assetPath
+			});
+			continue;
+		}
+		const dir = await materializeLayerFromArn(layer, { ...options.layerRoleArn !== void 0 && { roleArn: options.layerRoleArn } });
+		extraTmpDirs.push(dir);
+		flat.push({
+			logicalId: layer.arn,
+			assetPath: dir
+		});
+	}
+	return {
+		...materializeLambdaLayers(flat),
+		extraTmpDirs
+	};
+}
+/**
 * Build the `--tmpfs /tmp:rw,size=<N>m` plan for a Lambda (issue #440).
 *
 * The shape is identical for ZIP and IMAGE Lambdas — `--tmpfs` overlays
@@ -45867,7 +46476,7 @@ function pickReferencedLogicalId(intrinsic) {
 */
 function createLocalCommand() {
 	const local = new Command("local").description("Local execution of Lambda functions (RIE) and ECS task definitions (Docker required)");
-	const invoke = new Command("invoke").description("Run a Lambda function locally in a Docker container (RIE-backed). Target accepts a CDK display path (MyStack/MyApi/Handler) or stack-qualified logical ID (MyStack:MyApiHandler1234ABCD). Single-stack apps may omit the stack prefix.").argument("<target>", "CDK display path or stack-qualified logical ID of the Lambda to invoke").addOption(new Option("-e, --event <file>", "JSON event payload file (default: {})")).addOption(new Option("--event-stdin", "Read event JSON from stdin").default(false)).addOption(new Option("--env-vars <file>", "JSON env-var overrides (SAM-compatible: {\"LogicalId\":{\"KEY\":\"VALUE\"}})")).addOption(new Option("--no-pull", "Skip docker pull (use cached image) — no-op for IMAGE local-build path; `docker build` does not pull base layers by default")).addOption(new Option("--no-build", "Skip docker build on the IMAGE local-build path (use the previously-built tag). Requires the deterministic tag to already be in the local registry; errors with an actionable message when missing. No-op for ZIP Lambdas and the IMAGE ECR-pull path. Compatible with --no-pull.")).addOption(new Option("--debug-port <port>", "Node --inspect-brk port (default: off)")).addOption(new Option("--container-host <host>", "Host to bind the RIE port to").default("127.0.0.1")).addOption(new Option("--assume-role [arn]", "Assume the Lambda's deployed execution role and forward STS-issued temp credentials to the container so the handler runs with the deployed function's narrow permissions (closes the \"developer admin / function narrow\" skew). Three forms: (1) `--assume-role <arn>` assumes the explicit ARN; (2) `--assume-role` (bare) auto-resolves the function's execution role ARN from cdkd state (requires --from-state); (3) `--no-assume-role` explicitly opts out (forces dev creds even with --from-state). Off by default — when omitted, the developer's shell credentials are forwarded unchanged (SAM-compatible default). STS failures degrade to a warn + dev-creds fallback.")).addOption(new Option("--ecr-role-arn <arn>", "Role ARN to assume before authenticating against ECR for cross-account / centralized registries (#455). Issues sts:AssumeRole via the default credential chain and uses the temporary credentials for ecr:GetAuthorizationToken + docker pull. Required when the caller does not have direct cross-account access to the target repository. Same-account / same-region pulls do not need this flag.")).addOption(new Option("--from-state", "Read cdkd S3 state for the target stack and substitute Ref / Fn::GetAtt / Fn::Sub in env vars with the deployed physical IDs / attributes. Off by default — keep PR 1 warn-and-drop semantics; turn on for stacks already deployed via cdkd deploy.").default(false)).addOption(new Option("--stack-region <region>", "Region of the cdkd state record to read (used with --from-state when the same stack name has state in multiple regions).")).action(withErrorHandling(localInvokeCommand));
+	const invoke = new Command("invoke").description("Run a Lambda function locally in a Docker container (RIE-backed). Target accepts a CDK display path (MyStack/MyApi/Handler) or stack-qualified logical ID (MyStack:MyApiHandler1234ABCD). Single-stack apps may omit the stack prefix.").argument("<target>", "CDK display path or stack-qualified logical ID of the Lambda to invoke").addOption(new Option("-e, --event <file>", "JSON event payload file (default: {})")).addOption(new Option("--event-stdin", "Read event JSON from stdin").default(false)).addOption(new Option("--env-vars <file>", "JSON env-var overrides (SAM-compatible: {\"LogicalId\":{\"KEY\":\"VALUE\"}})")).addOption(new Option("--no-pull", "Skip docker pull (use cached image) — no-op for IMAGE local-build path; `docker build` does not pull base layers by default")).addOption(new Option("--no-build", "Skip docker build on the IMAGE local-build path (use the previously-built tag). Requires the deterministic tag to already be in the local registry; errors with an actionable message when missing. No-op for ZIP Lambdas and the IMAGE ECR-pull path. Compatible with --no-pull.")).addOption(new Option("--debug-port <port>", "Node --inspect-brk port (default: off)")).addOption(new Option("--container-host <host>", "Host to bind the RIE port to").default("127.0.0.1")).addOption(new Option("--assume-role [arn]", "Assume the Lambda's deployed execution role and forward STS-issued temp credentials to the container so the handler runs with the deployed function's narrow permissions (closes the \"developer admin / function narrow\" skew). Three forms: (1) `--assume-role <arn>` assumes the explicit ARN; (2) `--assume-role` (bare) auto-resolves the function's execution role ARN from cdkd state (requires --from-state); (3) `--no-assume-role` explicitly opts out (forces dev creds even with --from-state). Off by default — when omitted, the developer's shell credentials are forwarded unchanged (SAM-compatible default). STS failures degrade to a warn + dev-creds fallback.")).addOption(new Option("--layer-role-arn <arn>", "Role to sts:AssumeRole before calling lambda:GetLayerVersion on every literal-ARN entry in Properties.Layers (issue #448). Use only when the dev credentials cannot read the layer — typically cross-account layers. AWS-published public layers (e.g. Lambda Powertools) are readable from every account and need no role.")).addOption(new Option("--ecr-role-arn <arn>", "Role ARN to assume before authenticating against ECR for cross-account / centralized registries (#455). Issues sts:AssumeRole via the default credential chain and uses the temporary credentials for ecr:GetAuthorizationToken + docker pull. Required when the caller does not have direct cross-account access to the target repository. Same-account / same-region pulls do not need this flag.")).addOption(new Option("--from-state", "Read cdkd S3 state for the target stack and substitute Ref / Fn::GetAtt / Fn::Sub in env vars with the deployed physical IDs / attributes. Off by default — keep PR 1 warn-and-drop semantics; turn on for stacks already deployed via cdkd deploy.").default(false)).addOption(new Option("--stack-region <region>", "Region of the cdkd state record to read (used with --from-state when the same stack name has state in multiple regions).")).action(withErrorHandling(localInvokeCommand));
 	[
 		...commonOptions,
 		...appOptions,
@@ -46128,10 +46737,13 @@ async function exportCommand(stackArg, options) {
 		let template;
 		let resolvedStackName;
 		let synthedRegion;
+		let templateFormat = "json";
 		let allSynthStacks = [];
 		if (options.template) {
 			if (!stackArg) throw new Error("--template requires a stack name as a positional argument to identify the cdkd state record.");
-			template = parseTemplateFile(options.template);
+			const parsed = parseTemplateFile(options.template);
+			template = parsed.template;
+			templateFormat = parsed.format;
 			resolvedStackName = stackArg;
 		} else {
 			const appCmd = options.app || resolveApp();
@@ -46228,7 +46840,7 @@ 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);
+			await executeImportChangeSet(awsClients.cloudFormation, cfnStackName, phase1Template, phase1Imports, cfnParameters, templateFormat);
 			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];
@@ -46245,7 +46857,7 @@ 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);
+				await executeUpdateChangeSet(awsClients.cloudFormation, cfnStackName, phase2Template, cfnParameters, templateFormat);
 				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`);
@@ -46305,14 +46917,15 @@ function parseTemplateFile(path) {
 	} catch (err) {
 		throw new Error(`Failed to read template file '${path}': ` + (err instanceof Error ? err.message : String(err)));
 	}
-	let parsed;
 	try {
-		parsed = JSON.parse(raw);
+		const { template, format } = parseCfnTemplateWithFormat(raw);
+		return {
+			template,
+			format
+		};
 	} catch (err) {
-		throw new Error(`Template file '${path}' is not valid JSON. cdkd export only supports JSON templates (CDK-generated). Cause: ` + (err instanceof Error ? err.message : String(err)));
+		throw new Error(`Template file '${path}' is not a valid CloudFormation template. cdkd export accepts JSON and YAML (YAML via a CFn-aware codec that preserves !Ref / !GetAtt / !Sub shorthand). Cause: ` + (err instanceof Error ? err.message : String(err)));
 	}
-	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error(`Template file '${path}' is not a JSON object.`);
-	return parsed;
 }
 async function assertCfnStackAbsent(cfnClient, stackName) {
 	try {
@@ -46860,10 +47473,10 @@ function printPlan(plan, cfnStackName) {
 	}
 	logger.info("");
 }
-async function executeImportChangeSet(cfnClient, stackName, template, plan, parameters) {
+async function executeImportChangeSet(cfnClient, stackName, template, plan, parameters, templateFormat = "json") {
 	const logger = getLogger();
 	const changeSetName = `cdkd-migrate-${Date.now()}`;
-	const templateBody = JSON.stringify(template, null, 2);
+	const templateBody = stringifyCfnTemplate(template, templateFormat);
 	const resourcesToImport = plan.map((entry) => ({
 		ResourceType: entry.resourceType,
 		LogicalResourceId: entry.logicalId,
@@ -46974,10 +47587,10 @@ 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) {
+async function executeUpdateChangeSet(cfnClient, stackName, template, parameters, templateFormat = "json") {
 	const logger = getLogger();
 	const changeSetName = `cdkd-phase2-${Date.now()}`;
-	const templateBody = JSON.stringify(template, null, 2);
+	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)...`);
 	try {
@@ -47103,7 +47716,7 @@ async function confirmPrompt(prompt) {
 	}
 }
 function createExportCommand() {
-	const cmd = new Command("export").description("Hand a cdkd-managed stack over to CloudFormation via CFn IMPORT (changeset). AWS resources are unchanged; cdkd state for the stack is deleted on success. Mirror of `cdkd import` (AWS → cdkd) in the reverse direction (cdkd → CFn). JSON templates only. Aborts if any resource is not CFn-importable.").argument("[stack]", "Stack name to export (auto-detected for single-stack apps)").option("--cfn-stack-name <name>", "Name of the destination CloudFormation stack. Defaults to the cdkd stack name.").option("--template <path>", "Path to a pre-rendered CloudFormation template (JSON). Skips synth.").option("--stack-region <region>", "Region of the cdkd state record to operate on. Required when the same stack name has state in multiple regions.").option("--dry-run", "Print the import plan without creating a changeset.", false).option("--accept-transient-context", "Allow CLI -c key=value overrides at export time even though they are not persisted to cdk.json / cdk.context.json (default: refuse). When set, the user is responsible for passing the same -c flags to every future cdk deploy.", false).option("--include-non-importable", "Run a 2-phase migration when the stack contains non-importable resources (Custom::*). Phase 1 imports the importable resources; phase 2 CFn-CREATEs the non-importable ones, which re-invokes each Custom Resource's onCreate handler. Make sure onCreate is idempotent before enabling.", false).option("--parameter <key=value...>", "CFn template Parameter override, repeatable. Required when the synthesized template has Parameters without Default values; otherwise overrides the template's default value. Format: --parameter Key=Value.").option("--strict-cross-stack", "Refuse to export when sibling cdkd stacks in the same CDK app reference the exporting stack via Fn::GetStackOutput. Without the flag, cdkd warns but proceeds — the user is expected to migrate the consumer stacks in a follow-up.", false).option("--no-recreate-import-unsupported", "Block instead of auto-handling resource types AWS does NOT support in IMPORT changesets (currently only AWS::ApiGatewayV2::Stage, emitted by CDK HttpApi). Default behavior: cdkd skips these from phase 1, deletes the AWS-side resource between phases, and lets CFn re-CREATE in phase 2 (brief unavailability window). With this flag, the export aborts with a clear error instead.").action(withErrorHandling(exportCommand));
+	const cmd = new Command("export").description("Hand a cdkd-managed stack over to CloudFormation via CFn IMPORT (changeset). AWS resources are unchanged; cdkd state for the stack is deleted on success. Mirror of `cdkd import` (AWS → cdkd) in the reverse direction (cdkd → CFn). Accepts JSON and YAML templates (YAML via a CFn-aware codec that preserves !Ref / !GetAtt / !Sub shorthand). Aborts if any resource is not CFn-importable.").argument("[stack]", "Stack name to export (auto-detected for single-stack apps)").option("--cfn-stack-name <name>", "Name of the destination CloudFormation stack. Defaults to the cdkd stack name.").option("--template <path>", "Path to a pre-rendered CloudFormation template (JSON or YAML — format auto-detected). Skips synth.").option("--stack-region <region>", "Region of the cdkd state record to operate on. Required when the same stack name has state in multiple regions.").option("--dry-run", "Print the import plan without creating a changeset.", false).option("--accept-transient-context", "Allow CLI -c key=value overrides at export time even though they are not persisted to cdk.json / cdk.context.json (default: refuse). When set, the user is responsible for passing the same -c flags to every future cdk deploy.", false).option("--include-non-importable", "Run a 2-phase migration when the stack contains non-importable resources (Custom::*). Phase 1 imports the importable resources; phase 2 CFn-CREATEs the non-importable ones, which re-invokes each Custom Resource's onCreate handler. Make sure onCreate is idempotent before enabling.", false).option("--parameter <key=value...>", "CFn template Parameter override, repeatable. Required when the synthesized template has Parameters without Default values; otherwise overrides the template's default value. Format: --parameter Key=Value.").option("--strict-cross-stack", "Refuse to export when sibling cdkd stacks in the same CDK app reference the exporting stack via Fn::GetStackOutput. Without the flag, cdkd warns but proceeds — the user is expected to migrate the consumer stacks in a follow-up.", false).option("--no-recreate-import-unsupported", "Block instead of auto-handling resource types AWS does NOT support in IMPORT changesets (currently only AWS::ApiGatewayV2::Stage, emitted by CDK HttpApi). Default behavior: cdkd skips these from phase 1, deletes the AWS-side resource between phases, and lets CFn re-CREATE in phase 2 (brief unavailability window). With this flag, the export aborts with a clear error instead.").action(withErrorHandling(exportCommand));
 	[
 		...commonOptions,
 		...appOptions,
@@ -47155,7 +47768,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.123.0");
+	program.name("cdkd").description("CDK Direct - Deploy AWS CDK apps directly via SDK/Cloud Control API").version("0.125.0");
 	program.addCommand(createBootstrapCommand());
 	program.addCommand(createSynthCommand());
 	program.addCommand(createListCommand());