@go-to-k/cdkd 0.135.1 → 0.136.0

package/dist/{deploy-engine-CX1x5ug1.js → deploy-engine-DZYchTh6.js}

@@ -1,5 +1,6 @@
 import { a as runDockerStreaming, c as getLogger, d as getLiveRenderer, g as generateResourceNameWithFallback, m as applyDefaultNameForFallback, n as formatDockerLoginError, o as spawnStreaming, r as getDockerCmd, v as withStackName } from "./docker-cmd-EtWSTAje.js";
 import { r as getAwsClients } from "./aws-clients-BF03Alpe.js";
+import { randomUUID } from "node:crypto";
 import { DeleteObjectCommand, GetBucketLocationCommand, GetObjectCommand, HeadBucketCommand, HeadObjectCommand, ListObjectsV2Command, NoSuchKey, PutObjectCommand, S3Client, S3ServiceException } from "@aws-sdk/client-s3";
 import { CloudControlClient, CreateResourceCommand, DeleteResourceCommand, GetResourceCommand, GetResourceRequestStatusCommand, ListResourcesCommand, UpdateResourceCommand } from "@aws-sdk/client-cloudcontrol";
 import { AttachRolePolicyCommand, CreateRoleCommand, DeleteRoleCommand, DeleteRolePermissionsBoundaryCommand, DeleteRolePolicyCommand, DetachRolePolicyCommand, GetRoleCommand, GetRolePolicyCommand, IAMClient, ListAttachedRolePoliciesCommand, ListInstanceProfilesForRoleCommand, ListRolePoliciesCommand, ListRoleTagsCommand, ListRolesCommand, NoSuchEntityException, PutRolePermissionsBoundaryCommand, PutRolePolicyCommand, RemoveRoleFromInstanceProfileCommand, TagRoleCommand, UntagRoleCommand, UpdateAssumeRolePolicyCommand, UpdateRoleCommand } from "@aws-sdk/client-iam";
@@ -8,6 +9,7 @@ import { GetFunctionUrlConfigCommand, InvokeCommand, LambdaClient, waitUntilFunc
 import { AssumeRoleCommand, GetCallerIdentityCommand, STSClient } from "@aws-sdk/client-sts";
 import { DescribeAvailabilityZonesCommand, DescribeImagesCommand, DescribeLaunchTemplatesCommand, DescribeRouteTablesCommand, DescribeSecurityGroupsCommand, DescribeSubnetsCommand, DescribeVpcsCommand, DescribeVpnGatewaysCommand, EC2Client } from "@aws-sdk/client-ec2";
 import { DescribeTableCommand } from "@aws-sdk/client-dynamodb";
+import { CloudFormationClient, CreateChangeSetCommand, DeleteStackCommand, DescribeChangeSetCommand, GetTemplateCommand, waitUntilChangeSetCreateComplete } from "@aws-sdk/client-cloudformation";
 import { GetRestApiCommand } from "@aws-sdk/client-api-gateway";
 import { GetSecretValueCommand } from "@aws-sdk/client-secrets-manager";
 import { GetParameterCommand, SSMClient } from "@aws-sdk/client-ssm";
@@ -388,6 +390,42 @@ var LocalMigrateError = class LocalMigrateError extends CdkdError {
 	}
 };
 /**
+* CloudFormation macro / `Fn::Transform` expansion failure (#463).
+*
+* cdkd hands templates that declare `Transform: [...]` (or carry
+* `Fn::Transform: {...}` snippets) to CloudFormation server-side via a
+* transient `CreateChangeSet --change-set-type CREATE` against a
+* `cdkd-macro-expand-<id>` stack name. This error wraps every failure
+* mode of that round-trip:
+*
+*   - `CreateChangeSet` rejection (bad template, missing macro IAM
+*     permission, custom macro not found in the account).
+*   - Changeset settles in `FAILED` (`StatusReason` from CFn is
+*     surfaced verbatim — typically a custom macro Lambda error).
+*   - Waiter timeout (the macro Lambda is stuck or oversized).
+*   - `GetTemplate --template-stage Processed` returns no body (would
+*     indicate a CFn-side regression — fail loud rather than silently
+*     proceed with the un-expanded template).
+*   - Multi-stage detection: the expanded template still contains
+*     macros, which cdkd v1 does not support (the design intentionally
+*     rejects this so a second round-trip is not silently triggered).
+*
+* The error surfaces at exit code 2 (partial-failure family) — the
+* cleanup `finally` in the expander always runs `DeleteChangeSet` +
+* `DeleteStack` regardless of this error firing, so a failed
+* expansion never leaves a transient CFn stack behind in a routine
+* case. The user can re-run `cdkd deploy` once the upstream cause is
+* fixed.
+*/
+var MacroExpansionError = class MacroExpansionError extends CdkdError {
+	exitCode = 2;
+	constructor(message, cause) {
+		super(message, "MACRO_EXPANSION_ERROR", cause);
+		this.name = "MacroExpansionError";
+		Object.setPrototypeOf(this, MacroExpansionError.prototype);
+	}
+};
+/**
 * Check if error is a cdkd error
 */
 function isCdkdError(error) {
@@ -421,7 +459,8 @@ function handleError(error) {
 	const logger = getLogger();
 	if (!(error instanceof CdkdError && error.silent)) logger.error(formatError(error));
 	if (error instanceof Error && error.stack) logger.debug("Stack trace:", error.stack);
-	const exitCode = error instanceof PartialFailureError ? error.exitCode : 1;
+	const customExitCode = error instanceof CdkdError ? error.exitCode : void 0;
+	const exitCode = typeof customExitCode === "number" ? customExitCode : 1;
 	process.exit(exitCode);
 }
 /**
@@ -1593,6 +1632,567 @@ var ContextProviderRegistry = class {
 	}
 };
 
+//#endregion
+//#region src/synthesis/macro-detector.ts
+/**
+* CloudFormation macro detection (Issue #463 Phase 1).
+*
+* Pure-functional helpers that determine whether a synth template uses
+* any CloudFormation transform (top-level `Transform: [...]` or
+* snippet-level `Fn::Transform: {...}` blocks). cdkd's analyzer /
+* provisioner pipeline does NOT understand `Fn::Transform` — the
+* resolver has no handler and the DAG builder cannot extract refs
+* buried inside an unexpanded macro snippet — so a template that
+* triggers `containsMacro` must be handed to CloudFormation for
+* server-side expansion via {@link import('./macro-expander.js')}
+* before the rest of the pipeline can safely consume it.
+*
+* Design: [docs/design/463-cfn-macros.md](../../docs/design/463-cfn-macros.md).
+*/
+/**
+* Returns true when the given template uses any CloudFormation
+* transform. Tolerates malformed inputs (null / non-object / missing
+* `Resources`) by returning `false` so the rest of the synthesis
+* pipeline surfaces the malformed-template error rather than the
+* detector silently throwing.
+*
+* Detection rule:
+* - `template.Transform` is set (string OR array form).
+* - OR a recursive walk over `Resources` / `Outputs` / `Mappings` /
+*   `Conditions` / `Rules` finds any `{Fn::Transform: {...}}` key.
+*
+* The walk does NOT descend into `Metadata` blocks: CloudFormation
+* does not expand transforms inside metadata (the field is preserved
+* verbatim to AWS), so a `Fn::Transform` literally appearing under
+* `Metadata` is not a real macro reference and we must not surface it
+* as such.
+*/
+function containsMacro(template) {
+	if (!template || typeof template !== "object" || Array.isArray(template)) return false;
+	const t = template;
+	if (hasTopLevelTransform(t)) return true;
+	for (const section of [
+		"Resources",
+		"Outputs",
+		"Mappings",
+		"Conditions",
+		"Rules"
+	]) {
+		const sub = t[section];
+		if (sub && typeof sub === "object" && hasFnTransformDeep(sub)) return true;
+	}
+	return false;
+}
+/**
+* Returns every transform name declared in `Transform` plus the names
+* referenced via `Fn::Transform`, deduplicated and in encounter order.
+* Used for telemetry / UX (e.g. logging which transforms are about to
+* be expanded). Malformed entries (non-string Transform names, missing
+* `Name` field on Fn::Transform) are skipped silently — they would be
+* surfaced as a clear error by CloudFormation at expansion time.
+*
+* The walk follows the same rules as {@link containsMacro}: it descends
+* into `Resources` / `Outputs` / `Mappings` / `Conditions` / `Rules`
+* but NOT into `Metadata`.
+*/
+function enumerateMacros(template) {
+	if (!template || typeof template !== "object" || Array.isArray(template)) return [];
+	const t = template;
+	const seen = /* @__PURE__ */ new Set();
+	const result = [];
+	const top = t["Transform"];
+	if (typeof top === "string") pushName(top, seen, result);
+	else if (Array.isArray(top)) {
+		for (const entry of top) if (typeof entry === "string") pushName(entry, seen, result);
+		else if (entry && typeof entry === "object" && !Array.isArray(entry)) {
+			const name = entry["Name"];
+			if (typeof name === "string") pushName(name, seen, result);
+		}
+	} else if (top && typeof top === "object" && !Array.isArray(top)) {
+		const name = top["Name"];
+		if (typeof name === "string") pushName(name, seen, result);
+	}
+	for (const section of [
+		"Resources",
+		"Outputs",
+		"Mappings",
+		"Conditions",
+		"Rules"
+	]) {
+		const sub = t[section];
+		if (sub && typeof sub === "object") collectFnTransformNames(sub, seen, result);
+	}
+	return result;
+}
+function pushName(name, seen, out) {
+	if (seen.has(name)) return;
+	seen.add(name);
+	out.push(name);
+}
+function hasTopLevelTransform(t) {
+	const top = t["Transform"];
+	if (top === void 0 || top === null) return false;
+	if (Array.isArray(top) && top.length === 0) return false;
+	return true;
+}
+/**
+* Recursively walk the given value and return true if any nested
+* object carries a `Fn::Transform` key (with a non-null value — a
+* literal `Fn::Transform: null` is not a real macro reference).
+*
+* Does NOT descend into `Metadata` keys at any depth (CFn does not
+* expand transforms inside metadata blocks, so a `Fn::Transform`
+* literally appearing there must not trigger expansion). The
+* `Metadata` exclusion mirrors the same rule applied at the
+* top-level section walk in {@link containsMacro}.
+*/
+function hasFnTransformDeep(value) {
+	if (!value || typeof value !== "object") return false;
+	if (Array.isArray(value)) {
+		for (const item of value) if (hasFnTransformDeep(item)) return true;
+		return false;
+	}
+	const obj = value;
+	if (obj["Fn::Transform"] !== void 0 && obj["Fn::Transform"] !== null) return true;
+	for (const [key, sub] of Object.entries(obj)) {
+		if (key === "Metadata") continue;
+		if (hasFnTransformDeep(sub)) return true;
+	}
+	return false;
+}
+/**
+* Recursively walk and collect every `Fn::Transform.Name` value into
+* the provided dedup set / order-preserving array. Sibling to
+* {@link hasFnTransformDeep}; same `Metadata` exclusion.
+*/
+function collectFnTransformNames(value, seen, out) {
+	if (!value || typeof value !== "object") return;
+	if (Array.isArray(value)) {
+		for (const item of value) collectFnTransformNames(item, seen, out);
+		return;
+	}
+	const obj = value;
+	const fnT = obj["Fn::Transform"];
+	if (fnT && typeof fnT === "object" && !Array.isArray(fnT)) {
+		const name = fnT["Name"];
+		if (typeof name === "string") pushName(name, seen, out);
+	}
+	for (const [key, sub] of Object.entries(obj)) {
+		if (key === "Metadata") continue;
+		collectFnTransformNames(sub, seen, out);
+	}
+}
+
+//#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/synthesis/macro-expander.ts
+/** 600 seconds = 10 minutes. SDK waiter's `maxWaitTime` is in seconds. */
+const WAITER_MAX_WAIT_SECONDS = 600;
+const PARAMETER_PLACEHOLDER = "cdkd-macro-expand-placeholder";
+/**
+* Capabilities sent on every `CreateChangeSet` call:
+*
+* - `CAPABILITY_AUTO_EXPAND` is the load-bearing one — required for CFn
+*   to actually run macro / `Transform` expansion (without it, CFn
+*   rejects the changeset on any template that declares a Transform).
+* - `CAPABILITY_NAMED_IAM` / `CAPABILITY_IAM` are defense-in-depth: SAM
+*   transforms (`AWS::Serverless-2016-10-31`) emit Lambda execution
+*   roles, and user-authored macros may emit arbitrary IAM resources
+*   too. Sending them unconditionally avoids a second round-trip when
+*   the expanded template carries IAM resources cdkd's deploy pipeline
+*   would otherwise complain about.
+*/
+const CAPABILITIES = [
+	"CAPABILITY_AUTO_EXPAND",
+	"CAPABILITY_NAMED_IAM",
+	"CAPABILITY_IAM"
+];
+/**
+* Per-Type placeholder values used when a template Parameter has no
+* `Default`. CFn validates Parameter `Type` BEFORE the macro Lambda
+* runs, so a single bare-string placeholder rejects `CreateChangeSet`
+* on `Number` / `List<*>` / `AWS::EC2::*::Id` typed parameters
+* (`Parameter '<X>' must be a number`, etc.). The actual values do NOT
+* leak into the Processed-stage template (CFn preserves
+* `Ref: <param>` intact through expansion — see {@link
+* EMPIRICAL_FINDINGS_VERIFIED_2026_05_23} Q4), so any type-valid value
+* is sufficient. AWS-published Parameter Types list:
+* <https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/parameters-section-structure.html#parameters-section-structure-properties>
+*/
+const PARAMETER_TYPE_PLACEHOLDERS = {
+	String: PARAMETER_PLACEHOLDER,
+	Number: "0",
+	"List<Number>": "0",
+	CommaDelimitedList: "",
+	"List<String>": "",
+	"AWS::EC2::AvailabilityZone::Name": "us-east-1a",
+	"AWS::EC2::Image::Id": "ami-00000000",
+	"AWS::EC2::Instance::Id": "i-00000000",
+	"AWS::EC2::KeyPair::KeyName": "placeholder-key",
+	"AWS::EC2::SecurityGroup::GroupName": "placeholder-sg",
+	"AWS::EC2::SecurityGroup::Id": "sg-00000000",
+	"AWS::EC2::Subnet::Id": "subnet-00000000",
+	"AWS::EC2::Volume::Id": "vol-00000000",
+	"AWS::EC2::VPC::Id": "vpc-00000000",
+	"AWS::Route53::HostedZone::Id": "Z00000000000000000000",
+	"AWS::SSM::Parameter::Name": "placeholder",
+	"List<AWS::EC2::AvailabilityZone::Name>": "us-east-1a",
+	"List<AWS::EC2::Image::Id>": "ami-00000000",
+	"List<AWS::EC2::Instance::Id>": "i-00000000",
+	"List<AWS::EC2::SecurityGroup::GroupName>": "placeholder-sg",
+	"List<AWS::EC2::SecurityGroup::Id>": "sg-00000000",
+	"List<AWS::EC2::Subnet::Id>": "subnet-00000000",
+	"List<AWS::EC2::Volume::Id>": "vol-00000000",
+	"List<AWS::EC2::VPC::Id>": "vpc-00000000",
+	"List<AWS::Route53::HostedZone::Id>": "Z00000000000000000000"
+};
+/**
+* Expand CloudFormation macros / `Fn::Transform` blocks in a synth
+* template via a transient CloudFormation changeset round-trip.
+*
+* The flow (per design §3 Approach A):
+*
+*  1. Mint a unique transient stack name (`cdkd-macro-expand-<id>`).
+*  2. Build parameter values for every declared template Parameter
+*     (template Default if present; synthetic placeholder otherwise).
+*     CFn does NOT substitute these into the Processed-stage
+*     template, but it requires them for the changeset to be valid.
+*  3. `CreateChangeSet --change-set-type CREATE` with
+*     `Capabilities: ['CAPABILITY_AUTO_EXPAND','CAPABILITY_NAMED_IAM',
+*     'CAPABILITY_IAM']`. Use inline `TemplateBody` when <= 51,200
+*     bytes; upload to the cdkd state bucket and pass `TemplateURL`
+*     when between 51,200 bytes and 1 MB; refuse outright when > 1 MB
+*     (CFn `TemplateURL` ceiling).
+*  4. Wait for `ChangeSetStatus: CREATE_COMPLETE`. On `FAILED`, surface
+*     the `StatusReason` verbatim — typically the macro Lambda's error
+*     message, or "no transforms found" for a template with an empty
+*     `Transform` array.
+*  5. `GetTemplate --template-stage Processed` returns the
+*     post-expansion template.
+*  6. Cleanup in `finally`: `DeleteChangeSet` + `DeleteStack`
+*     (idempotent — both tolerate `*NotFound` errors). The transient
+*     S3 upload (if any) is cleaned up too.
+*  7. Re-check `containsMacro(expanded)` and reject the multi-stage
+*     case — cdkd v1 does not support templates whose expansion emits
+*     ANOTHER macro reference. CFn handles single-step expansion
+*     natively; second-round expansion is intentionally out of scope.
+*
+* Returns the expanded template as a parsed `CloudFormationTemplate`.
+* Throws {@link MacroExpansionError} on any failure mode. Cleanup
+* failures during the `finally` block log at WARN but do not mask the
+* outer success / error.
+*/
+async function expandMacros(template, opts) {
+	const logger = getLogger().child("MacroExpander");
+	if (!containsMacro(template)) return template;
+	const macros = enumerateMacros(template);
+	logger.debug(`Macro expansion: detected transforms [${macros.join(", ")}], starting CFn round-trip...`);
+	const transientStackName = `cdkd-macro-expand-${randomUUID().slice(0, 16)}`;
+	const changeSetName = `${transientStackName}-changeset`;
+	const region = opts.region;
+	const stateBucket = opts.stateBucket;
+	const waiterMaxWaitSeconds = opts.waiterMaxWaitSeconds ?? WAITER_MAX_WAIT_SECONDS;
+	let cfn;
+	let ownsClient = false;
+	let s3Cleanup;
+	try {
+		const serialized = JSON.stringify(template);
+		const parameters = buildParameterValues(template, logger);
+		ownsClient = opts.cfnClient === void 0;
+		cfn = opts.cfnClient ?? new CloudFormationClient({ region });
+		let templateInput;
+		if (serialized.length > 1048576) throw new MacroExpansionError(`Template is ${serialized.length} bytes, which exceeds CloudFormation's ${CFN_TEMPLATE_URL_LIMIT}-byte TemplateURL ceiling for macro expansion. Shrink inline payloads (move inline lambda.Code.ZipFile to lambda.Code.fromAsset, etc.) or split the stack before retrying.`);
+		if (serialized.length <= 51200) templateInput = { TemplateBody: serialized };
+		else {
+			if (!stateBucket) throw new MacroExpansionError(`Template is ${serialized.length} bytes (over ${CFN_TEMPLATE_BODY_LIMIT} inline limit) — cdkd needs a state bucket to upload the transient template for CloudFormation's TemplateURL parameter. Pass --state-bucket <name> or ensure STS GetCallerIdentity can resolve a default bucket (cdkd-state-<accountId>).`);
+			logger.debug(`Macro expansion: template is ${serialized.length} bytes (over ${CFN_TEMPLATE_BODY_LIMIT} inline limit) — uploading to state bucket '${stateBucket}' for TemplateURL.`);
+			const uploaded = await uploadCfnTemplate({
+				bucket: stateBucket,
+				body: serialized,
+				stackName: transientStackName,
+				format: "json",
+				...opts.s3ClientOpts && { s3ClientOpts: opts.s3ClientOpts }
+			});
+			templateInput = { TemplateURL: uploaded.url };
+			s3Cleanup = uploaded.cleanup;
+		}
+		try {
+			await cfn.send(new CreateChangeSetCommand({
+				StackName: transientStackName,
+				ChangeSetName: changeSetName,
+				ChangeSetType: "CREATE",
+				...templateInput,
+				Capabilities: CAPABILITIES,
+				...parameters.length > 0 && { Parameters: parameters }
+			}));
+		} catch (err) {
+			throw new MacroExpansionError(`CloudFormation rejected the macro-expansion changeset: ${err instanceof Error ? err.message : String(err)}`, err instanceof Error ? err : void 0);
+		}
+		let waiterFailed = false;
+		let waiterError;
+		try {
+			await waitUntilChangeSetCreateComplete({
+				client: cfn,
+				maxWaitTime: waiterMaxWaitSeconds
+			}, {
+				StackName: transientStackName,
+				ChangeSetName: changeSetName
+			});
+		} catch (waiterErr) {
+			waiterFailed = true;
+			waiterError = waiterErr;
+		}
+		if (waiterFailed) {
+			const desc = await cfn.send(new DescribeChangeSetCommand({
+				StackName: transientStackName,
+				ChangeSetName: changeSetName
+			})).catch(() => void 0);
+			const reason = desc?.StatusReason ?? "unknown (DescribeChangeSet failed)";
+			throw new MacroExpansionError(`CloudFormation macro expansion failed (status=${desc?.Status ?? "UNKNOWN"}): ${reason}`, waiterError instanceof Error ? waiterError : void 0);
+		}
+		const tpl = await cfn.send(new GetTemplateCommand({
+			StackName: transientStackName,
+			ChangeSetName: changeSetName,
+			TemplateStage: "Processed"
+		}));
+		if (tpl.TemplateBody === void 0 || tpl.TemplateBody === null) throw new MacroExpansionError(`CloudFormation returned no Processed-stage template body for the macro-expansion changeset. This typically indicates a CFn-side regression — re-run, and if the failure persists open an issue with the transforms involved: [${macros.join(", ")}].`);
+		const expanded = parseTemplateBody(tpl.TemplateBody);
+		if (containsMacro(expanded)) throw new MacroExpansionError(`Macro expansion produced a template that still contains macros [${enumerateMacros(expanded).join(", ")}]. Multi-stage macros (a macro whose expansion emits another macro reference) are intentionally out of scope in cdkd v1 — see https://github.com/go-to-k/cdkd/issues/463. If you need this pattern, manually pre-expand the template and deploy the result.`);
+		logger.debug(`Macro expansion: success — ${Object.keys(expanded.Resources ?? {}).length} resources after expansion.`);
+		return expanded;
+	} finally {
+		if (cfn !== void 0) try {
+			await cfn.send(new DeleteStackCommand({ StackName: transientStackName }));
+		} catch (cleanupErr) {
+			logger.warn(`Failed to delete transient macro-expand stack '${transientStackName}': ${formatErr(cleanupErr)}. Clean up manually via 'aws cloudformation delete-stack --stack-name ${transientStackName}'.`);
+		}
+		if (s3Cleanup) try {
+			await s3Cleanup();
+		} catch (cleanupErr) {
+			logger.warn(`Failed to delete transient macro-expand template upload from state bucket '${stateBucket}' (key prefix 'cdkd-migrate-tmp/${transientStackName}/'): ${formatErr(cleanupErr)}. Sweep manually via 'aws s3 rm s3://${stateBucket}/cdkd-migrate-tmp/${transientStackName}/ --recursive'.`);
+		}
+		if (ownsClient && cfn !== void 0) cfn.destroy();
+	}
+}
+/**
+* Build the `Parameters` list passed to `CreateChangeSet`. CFn requires
+* a value for every declared parameter; we fall back to a Type-aware
+* synthetic placeholder when the template has no Default. Per the
+* empirical verification above, these values do NOT leak into the
+* Processed template (CFn keeps `Ref: <param>` intact for cdkd's own
+* resolver to substitute later with the real values).
+*/
+function buildParameterValues(template, logger) {
+	if (!template || typeof template !== "object" || Array.isArray(template)) return [];
+	const params = template["Parameters"];
+	if (!params || typeof params !== "object" || Array.isArray(params)) return [];
+	const out = [];
+	for (const [key, def] of Object.entries(params)) {
+		if (!def || typeof def !== "object" || Array.isArray(def)) continue;
+		const defObj = def;
+		const defDefault = defObj["Default"];
+		const defType = typeof defObj["Type"] === "string" ? defObj["Type"] : void 0;
+		out.push({
+			ParameterKey: key,
+			ParameterValue: stringifyParamDefault(defDefault, defType, key, logger)
+		});
+	}
+	return out;
+}
+/**
+* Coerce a CFn Parameter `Default` (or build a synthetic placeholder
+* when the Default is absent) into the string `CreateChangeSet`
+* requires. Strings / numbers / booleans pass through verbatim;
+* object-shaped Defaults (rare — array-typed Defaults that haven't
+* been comma-joined) are JSON-stringified. When no Default is present,
+* routes through {@link PARAMETER_TYPE_PLACEHOLDERS} so a `Number` /
+* `List<Number>` / `AWS::EC2::*::Id` Parameter sees a value CFn's
+* pre-macro Type validator accepts. The actual value does NOT leak
+* into the Processed-stage template (CFn preserves `Ref: <param>`
+* intact through expansion — see empirical findings).
+*/
+function stringifyParamDefault(value, type, paramKey, logger) {
+	if (value !== void 0 && value !== null) {
+		if (typeof value === "string") return value;
+		if (typeof value === "number" || typeof value === "boolean") return String(value);
+		try {
+			return JSON.stringify(value);
+		} catch {}
+	}
+	if (type !== void 0) {
+		const known = PARAMETER_TYPE_PLACEHOLDERS[type];
+		if (known !== void 0) return known;
+		if (type.startsWith("AWS::SSM::Parameter::Value<")) {
+			const inner = type.slice(27, -1);
+			if (inner.startsWith("List<") || inner === "CommaDelimitedList") return "placeholder,placeholder";
+			return "placeholder";
+		}
+		logger.warn(`Parameter '${paramKey}' has unrecognized CFn Type '${type}'; using a generic string placeholder for the transient macro-expansion changeset. If CFn rejects the changeset with a type error, file an issue with the offending Type.`);
+		return PARAMETER_PLACEHOLDER;
+	}
+	return PARAMETER_PLACEHOLDER;
+}
+/**
+* Parse the `TemplateBody` field returned by `GetTemplate`. The SDK
+* types it as `string | undefined`, but empirical observation shows
+* the wire shape may be either a string (for YAML or some pre-parsed
+* cases) or a parsed object (for JSON templates against
+* `--template-stage Processed`). Handle both.
+*/
+function parseTemplateBody(body) {
+	let parsed;
+	if (typeof body === "string") try {
+		parsed = JSON.parse(body);
+	} catch (err) {
+		throw new MacroExpansionError(`CloudFormation returned a non-JSON Processed-stage template body. cdkd's macro-expansion path only supports JSON-shaped synth templates (CDK apps emit JSON by default). Cause: ${err instanceof Error ? err.message : String(err)}`, err instanceof Error ? err : void 0);
+	}
+	else if (body && typeof body === "object" && !Array.isArray(body)) parsed = body;
+	else throw new MacroExpansionError(`CloudFormation returned an unexpected TemplateBody shape (${typeof body}). Expected a JSON string or parsed object.`);
+	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new MacroExpansionError(`CloudFormation returned a malformed Processed-stage template body — expected a JSON object at the top level, got ${Array.isArray(parsed) ? "array" : typeof parsed}.`);
+	const resources = parsed["Resources"];
+	if (resources !== void 0 && (typeof resources !== "object" || resources === null || Array.isArray(resources))) throw new MacroExpansionError(`CloudFormation returned a malformed Processed-stage template body — 'Resources' must be an object map, got ${resources === null ? "null" : Array.isArray(resources) ? "array" : typeof resources}.`);
+	return parsed;
+}
+function formatErr(err) {
+	return err instanceof Error ? err.message : String(err);
+}
+
 //#endregion
 //#region src/cli/config-loader.ts
 /**
@@ -1903,6 +2503,19 @@ var Synthesizer = class {
 			this.logger.debug(`Using pre-synthesized cloud assembly at ${appPath}`);
 			const manifest = this.assemblyReader.readManifest(appPath);
 			const stacks = this.assemblyReader.getAllStacks(appPath, manifest);
+			const presynthRegion = options.region || process.env["AWS_REGION"] || process.env["AWS_DEFAULT_REGION"];
+			let presynthAccountId;
+			try {
+				const stsClient = new STSClient({ ...presynthRegion && { region: presynthRegion } });
+				presynthAccountId = (await stsClient.send(new GetCallerIdentityCommand({}))).Account;
+				stsClient.destroy();
+			} catch {
+				this.logger.debug("Could not resolve AWS account ID via STS (pre-synth branch)");
+			}
+			await this.expandMacrosForStacks(stacks, options, {
+				region: presynthRegion,
+				...presynthAccountId && { accountId: presynthAccountId }
+			});
 			this.logger.debug(`Loaded ${stacks.length} stack(s) from pre-synthesized assembly`);
 			return {
 				manifest,
@@ -1955,6 +2568,10 @@ var Synthesizer = class {
 			const manifest = this.assemblyReader.readManifest(outputDir);
 			if (!manifest.missing || manifest.missing.length === 0) {
 				const stacks = this.assemblyReader.getAllStacks(outputDir, manifest);
+				await this.expandMacrosForStacks(stacks, options, {
+					region,
+					...accountId && { accountId }
+				});
 				this.logger.debug(`Synthesis complete: ${stacks.length} stack(s)`);
 				return {
 					manifest,
@@ -1978,6 +2595,49 @@ var Synthesizer = class {
 	async listStacks(options) {
 		return (await this.synthesize(options)).stacks.map((s) => s.stackName);
 	}
+	/**
+	* Per-stack macro-expansion pass (Issue #463). Mutates each stack's
+	* `template` in place when {@link containsMacro} flags it. Runs
+	* AFTER the context-provider loop has settled and BEFORE the
+	* analyzer / provisioner pipeline consumes the templates, so every
+	* downstream stage sees the post-expansion shape.
+	*
+	* Skipped silently when no stack carries a macro — pure no-op cost.
+	* When a macro IS detected and the caller did NOT thread a
+	* region into the synthesizer, falls back to resolving region from
+	* the synthesized stack's environment (set by `cdk.Stack.region`).
+	* Throws `SynthesisError` when no region can be resolved (the
+	* upstream caller treats it as a synth failure) and propagates
+	* `MacroExpansionError` (from {@link expandMacros}) on any CFn-side
+	* failure during the round-trip.
+	*/
+	async expandMacrosForStacks(stacks, options, resolved) {
+		const stacksWithMacros = stacks.filter((s) => containsMacro(s.template));
+		if (stacksWithMacros.length === 0) return;
+		const region = resolved?.region || options.region || process.env["AWS_REGION"] || process.env["AWS_DEFAULT_REGION"] || stacksWithMacros[0]?.region;
+		if (!region) throw new SynthesisError(`Stack(s) [${stacksWithMacros.map((s) => s.stackName).join(", ")}] use CloudFormation macros (Transform / Fn::Transform) but cdkd could not resolve an AWS region for the expansion round-trip. Set AWS_REGION, pass --region <r>, or set env: { region: '<r>' } in your CDK Stack constructor.`);
+		let stateBucket;
+		if (options.stateBucket) stateBucket = options.stateBucket;
+		else if (resolved?.accountId) stateBucket = `cdkd-state-${resolved.accountId}`;
+		else {
+			const oversize = stacksWithMacros.find((s) => JSON.stringify(s.template).length > 51200);
+			if (oversize) throw new SynthesisError(`Stack '${oversize.stackName}' uses CloudFormation macros AND its serialized template exceeds the 51,200-byte inline TemplateBody limit, so cdkd must upload the template to S3 for the transient expansion changeset. cdkd could not resolve a state bucket: STS GetCallerIdentity failed AND --state-bucket was not provided. Pass --state-bucket <name> (cdkd uses the same bucket as cdkd deploy state storage; typically 'cdkd-state-<accountId>').`);
+			stateBucket = void 0;
+		}
+		for (const stack of stacksWithMacros) {
+			const macros = enumerateMacros(stack.template);
+			this.logger.info(`[macros] Expanding CloudFormation macros for stack '${stack.stackName}' via CFn round-trip (transforms: ${macros.join(", ")}; may take 30-60s)...`);
+			const before = Date.now();
+			const expanded = await expandMacros(stack.template, {
+				region,
+				...stateBucket !== void 0 && { stateBucket },
+				...options.macroExpandS3ClientOpts && { s3ClientOpts: options.macroExpandS3ClientOpts }
+			});
+			stack.template = expanded;
+			const elapsedSec = Math.round((Date.now() - before) / 1e3);
+			this.logger.info(`[macros]   ... done in ${elapsedSec}s (${Object.keys(expanded.Resources ?? {}).length} resources after expansion).`);
+		}
+	}
 };
 /**
 * Check if two sets contain the same elements
@@ -9238,5 +9898,5 @@ var DeployEngine = class {
 };
 
 //#endregion
-export { LockError as $, AssetPublisher as A, resolveStateBucketWithDefault as B, applyRoleArnIfSet as C, LockManager as D, TemplateParser as E, getDefaultStateBucketName as F, resolveBucketRegion as G, warnDeprecatedNoPrefixCliFlag as H, getLegacyStateBucketName as I, ConfigError as J, AssetError as K, resolveApp as L, WorkGraph as M, buildDockerImage as N, S3StateBackend as O, Synthesizer as P, LocalStartServiceError as Q, resolveCaptureObservedState as R, IntrinsicFunctionResolver as S, DagBuilder as T, AssemblyReader as U, resolveStateBucketWithDefaultAndSource as V, clearBucketRegionCache as W, LocalInvokeBuildError as X, DependencyError as Y, LocalMigrateError as Z, normalizeAwsTagsToCfn as _, withRetry as a, RouteDiscoveryError as at, CloudControlProvider as b, cyan as c, StateError as ct, red as d, isCdkdError as dt, MissingCdkCliError as et, yellow as f, normalizeAwsError as ft, matchesCdkPath as g, CDK_PATH_TAG as h, withResourceDeadline as i, ResourceUpdateNotSupportedError as it, stringifyValue as j, shouldRetainResource as k, gray as l, SynthesisError as lt, collectInlinePolicyNamesManagedBySiblings as m, DEFAULT_RESOURCE_WARN_AFTER_MS as n, ProvisioningError as nt, IMPLICIT_DELETE_DEPENDENCIES as o, StackHasActiveImportsError as ot, IAMRoleProvider as p, withErrorHandling as pt, CdkdError as q, DeployEngine as r, ResourceTimeoutError as rt, bold as s, StackTerminationProtectionError as st, DEFAULT_RESOURCE_TIMEOUT_MS as t, PartialFailureError as tt, green as u, formatError as ut, resolveExplicitPhysicalId as v, DiffCalculator as w, assertRegionMatch as x, ProviderRegistry as y, resolveSkipPrefix as z };
-//# sourceMappingURL=deploy-engine-CX1x5ug1.js.map
+export { ConfigError as $, AssetPublisher as A, resolveStateBucketWithDefault as B, applyRoleArnIfSet as C, LockManager as D, TemplateParser as E, getDefaultStateBucketName as F, MIGRATE_TMP_PREFIX as G, warnDeprecatedNoPrefixCliFlag as H, getLegacyStateBucketName as I, AssemblyReader as J, findLargeInlineResources as K, resolveApp as L, WorkGraph as M, buildDockerImage as N, S3StateBackend as O, Synthesizer as P, CdkdError as Q, resolveCaptureObservedState as R, IntrinsicFunctionResolver as S, DagBuilder as T, CFN_TEMPLATE_BODY_LIMIT as U, resolveStateBucketWithDefaultAndSource as V, CFN_TEMPLATE_URL_LIMIT as W, resolveBucketRegion as X, clearBucketRegionCache as Y, AssetError as Z, normalizeAwsTagsToCfn as _, normalizeAwsError as _t, withRetry as a, MissingCdkCliError as at, CloudControlProvider as b, cyan as c, ResourceTimeoutError as ct, red as d, StackHasActiveImportsError as dt, DependencyError as et, yellow as f, StackTerminationProtectionError as ft, matchesCdkPath as g, isCdkdError as gt, CDK_PATH_TAG as h, formatError as ht, withResourceDeadline as i, LockError as it, stringifyValue as j, shouldRetainResource as k, gray as l, ResourceUpdateNotSupportedError as lt, collectInlinePolicyNamesManagedBySiblings as m, SynthesisError as mt, DEFAULT_RESOURCE_WARN_AFTER_MS as n, LocalMigrateError as nt, IMPLICIT_DELETE_DEPENDENCIES as o, PartialFailureError as ot, IAMRoleProvider as p, StateError as pt, uploadCfnTemplate as q, DeployEngine as r, LocalStartServiceError as rt, bold as s, ProvisioningError as st, DEFAULT_RESOURCE_TIMEOUT_MS as t, LocalInvokeBuildError as tt, green as u, RouteDiscoveryError as ut, resolveExplicitPhysicalId as v, withErrorHandling as vt, DiffCalculator as w, assertRegionMatch as x, ProviderRegistry as y, resolveSkipPrefix as z };
+//# sourceMappingURL=deploy-engine-DZYchTh6.js.map