@go-to-k/cdkd 0.284.20 → 0.284.21

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
-import { $ as isTerminationProtectionPropagationError, $n as PartialFailureError, $t as getBootstrapMarkerKey, A as renderStatefulReason, An as expectedOwnerParam, At as applyRoleArnIfSet, B as exportAliasCollisionScrubWarning, Bn as resetAwsClients, Bt as shouldRetainResource, C as isFinalSnapshotError, Cn as stateBucketExistenceConfirmed, Ct as redactSecretsForState, D as extractDeploymentEventError, Dn as MIGRATE_TMP_PREFIX, Dt as s3BucketDualStackDomainName, E as makeCanonicalizePropertiesFn, En as CFN_TEMPLATE_URL_LIMIT, Et as s3BucketDomainName, F as green, Fn as processStackMessages, Ft as DagBuilder, G as collectInlinePolicyNamesManagedBySiblings, Gt as createAssetRedirectResolver, H as secretBearingStateKeyWarning, Ht as stringifyValue, I as red, It as TemplateParser, J as findActionableSilentDrops, Jn as LocalMigrateError, Jt as escapeRegExp, K as clearOnUpdateRemoval, Kn as DeployCancelledError, Kt as loadPublishableAssetManifest, L as yellow, Ln as resolveBucketRegion, Lt as LockManager, M as bold, Mn as canonicalizeRegion, Mt as INTRINSIC_KEYS, N as cyan, Nn as derivePartitionAndUrlSuffix, Nt as describeTypeWithThrottleRetry, O as MULTI_REGION_RECREATE_BLOCKED_TYPES, On as findLargeInlineResources, Ot as s3BucketRegionalDomainName, P as gray, Pn as AssemblyReader, Pt as withRetry, Q as disableInstanceApiTermination, Qn as NestedStackChildDirectDestroyError, Qt as ensureAssetStorage, R as collectDeclaredOutputNames, Rn as AwsClients, Rt as S3StateBackend, S as createPreDeleteFinalSnapshot, Sn as resolveUseCdkBootstrapAssets, St as maskSecretsInText, T as unsupportedFinalSnapshotError, Tn as CFN_TEMPLATE_BODY_LIMIT, Tt as s3BucketArn, U as stateKeySecretExposure, Un as CdkdError, Ut as WorkGraph, V as isExportAliasCollision, Vn as setAwsClients, Vt as AssetPublisher, W as IAMRoleProvider, Wt as buildAssetRedirectMap, X as CloudControlProvider, Xt as AssetModeResolver, Y as findSilentDropProperties, Yn as LocalStartServiceError, Yt as stripControlChars, Z as slowCcOperationTimeoutMs, Zn as MissingCdkCliError, Zt as BOOTSTRAP_MARKER_PREFIX, _ as computeImplicitDeleteEdges, _n as resolveAutoAssetStorage, _t as STATE_SOURCED_READBACK_RULES, a as DeploymentEventsStore, an as buildDockerImage, at as normalizeAwsTagsToCfn, b as buildFinalSnapshotIdentifier, bn as resolveStateBucketWithDefault, bt as dynamicReferenceTokens, c as replayFailedOperations, cn as runDockerForeground, ct as coerceCfnBoolean, d as updatePartialReason, dn as getDockerImageBySourceHash, dr as isMarkedNonRetryable, dt as readConfigString, en as parseBootstrapMarker, er as ProvisioningError, et as IntrinsicFunctionResolver, f as UNSPECIFIED_SKIP_REASON, fn as Synthesizer, fr as isRetryableTransientError, ft as replayWarn, g as IMPLICIT_DELETE_DEPENDENCIES, gn as resolveApp, gt as STATE_SOURCED_CROSS_GENERATION_RULES, h as maskingRetryLogger, hn as getLegacyStateBucketName, ht as requireConfigString, i as DeploymentEventsReader, in as buildDenyExternalAccessPolicy, ir as StackTerminationProtectionError, it as WAFv2WebACLProvider, j as formatResourceLine, jn as PARTITION_TABLE, jt as DiffCalculator, k as isStatefulRecreateTargetSync, kn as uploadCfnTemplate, kt as s3BucketWebsiteUrl, l as replayRollback, ln as runDockerStreaming, lr as normalizeAwsError, lt as configBooleanRefusal, m as withResourceDeadline, mn as getDefaultStateBucketName, mr as markNonRetryable, mt as requireConfigObject, n as DEFAULT_RESOURCE_WARN_AFTER_MS, nn as validateAssetBucketName, nr as ResourceUpdateNotSupportedError, nt as getAccountInfo, o as planFailedOps, on as formatDockerLoginError, ot as resolveExplicitPhysicalId, p as deleteSkipReason, pn as synthesisStatusMessage, pr as isThrottlingError, pt as requireConfigArray, q as ProviderRegistry, qn as LocalInvokeBuildError$1, qt as rewriteTemplateAssetReferences, r as DeployEngine, rn as validateContainerRepoName, rr as StackHasActiveImportsError, rt as refStateLookupFromResource, s as planRollback, sn as getDockerCmd, st as assertRegionMatch, t as DEFAULT_RESOURCE_TIMEOUT_MS, tn as readBootstrapMarkerBody, tr as ResourceTimeoutError, tt as cfnRefValueFromPhysicalId, u as updatePartialMessage, un as AssetManifestLoader, ur as withErrorHandling, ut as configStringRefusal, v as ATOMIC_FINAL_SNAPSHOT_TYPES, vn as resolveCaptureObservedState, vt as TEMPLATE_SOURCED_RULES, w as refusesFinalSnapshot, wn as warnDeprecatedNoPrefixCliFlag, wt as scrubResourceRecord, x as ccRoutedFinalSnapshotError, xn as resolveStateBucketWithDefaultAndSource, xt as isSingleDynamicReferenceToken, y as PRE_DELETE_SNAPSHOT_TYPES, yn as resolveSkipPrefix, yt as createSecretMasker, z as collectPublishedOutputNames, zn as getAwsClients, zt as rebuildClientForBucketRegion } from "./deploy-engine-C6gt7NcL.js";
+import { $ as isTerminationProtectionPropagationError, $n as PartialFailureError, $t as getBootstrapMarkerKey, A as renderStatefulReason, An as expectedOwnerParam, At as applyRoleArnIfSet, B as exportAliasCollisionScrubWarning, Bn as resetAwsClients, Bt as shouldRetainResource, C as isFinalSnapshotError, Cn as stateBucketExistenceConfirmed, Ct as redactSecretsForState, D as extractDeploymentEventError, Dn as MIGRATE_TMP_PREFIX, Dt as s3BucketDualStackDomainName, E as makeCanonicalizePropertiesFn, En as CFN_TEMPLATE_URL_LIMIT, Et as s3BucketDomainName, F as green, Fn as processStackMessages, Ft as DagBuilder, G as collectInlinePolicyNamesManagedBySiblings, Gt as createAssetRedirectResolver, H as secretBearingStateKeyWarning, Ht as stringifyValue, I as red, It as TemplateParser, J as findActionableSilentDrops, Jn as LocalMigrateError, Jt as escapeRegExp, K as clearOnUpdateRemoval, Kn as DeployCancelledError, Kt as loadPublishableAssetManifest, L as yellow, Ln as resolveBucketRegion, Lt as LockManager, M as bold, Mn as canonicalizeRegion, Mt as INTRINSIC_KEYS, N as cyan, Nn as derivePartitionAndUrlSuffix, Nt as describeTypeWithThrottleRetry, O as MULTI_REGION_RECREATE_BLOCKED_TYPES, On as findLargeInlineResources, Ot as s3BucketRegionalDomainName, P as gray, Pn as AssemblyReader, Pt as withRetry, Q as disableInstanceApiTermination, Qn as NestedStackChildDirectDestroyError, Qt as ensureAssetStorage, R as collectDeclaredOutputNames, Rn as AwsClients, Rt as S3StateBackend, S as createPreDeleteFinalSnapshot, Sn as resolveUseCdkBootstrapAssets, St as maskSecretsInText, T as unsupportedFinalSnapshotError, Tn as CFN_TEMPLATE_BODY_LIMIT, Tt as s3BucketArn, U as stateKeySecretExposure, Un as CdkdError, Ut as WorkGraph, V as isExportAliasCollision, Vn as setAwsClients, Vt as AssetPublisher, W as IAMRoleProvider, Wt as buildAssetRedirectMap, X as CloudControlProvider, Xt as AssetModeResolver, Y as findSilentDropProperties, Yn as LocalStartServiceError, Yt as stripControlChars, Z as slowCcOperationTimeoutMs, Zn as MissingCdkCliError, Zt as BOOTSTRAP_MARKER_PREFIX, _ as computeImplicitDeleteEdges, _n as resolveAutoAssetStorage, _t as STATE_SOURCED_READBACK_RULES, a as DeploymentEventsStore, an as buildDockerImage, at as normalizeAwsTagsToCfn, b as buildFinalSnapshotIdentifier, bn as resolveStateBucketWithDefault, bt as dynamicReferenceTokens, c as replayFailedOperations, cn as runDockerForeground, ct as coerceCfnBoolean, d as updatePartialReason, dn as getDockerImageBySourceHash, dr as isMarkedNonRetryable, dt as readConfigString, en as parseBootstrapMarker, er as ProvisioningError, et as IntrinsicFunctionResolver, f as UNSPECIFIED_SKIP_REASON, fn as Synthesizer, fr as isRetryableTransientError, ft as replayWarn, g as IMPLICIT_DELETE_DEPENDENCIES, gn as resolveApp, gt as STATE_SOURCED_CROSS_GENERATION_RULES, h as maskingRetryLogger, hn as getLegacyStateBucketName, ht as requireConfigString, i as DeploymentEventsReader, in as buildDenyExternalAccessPolicy, ir as StackTerminationProtectionError, it as WAFv2WebACLProvider, j as formatResourceLine, jn as PARTITION_TABLE, jt as DiffCalculator, k as isStatefulRecreateTargetSync, kn as uploadCfnTemplate, kt as s3BucketWebsiteUrl, l as replayRollback, ln as runDockerStreaming, lr as normalizeAwsError, lt as configBooleanRefusal, m as withResourceDeadline, mn as getDefaultStateBucketName, mr as markNonRetryable, mt as requireConfigObject, n as DEFAULT_RESOURCE_WARN_AFTER_MS, nn as validateAssetBucketName, nr as ResourceUpdateNotSupportedError, nt as getAccountInfo, o as planFailedOps, on as formatDockerLoginError, ot as resolveExplicitPhysicalId, p as deleteSkipReason, pn as synthesisStatusMessage, pr as isThrottlingError, pt as requireConfigArray, q as ProviderRegistry, qn as LocalInvokeBuildError$1, qt as rewriteTemplateAssetReferences, r as DeployEngine, rn as validateContainerRepoName, rr as StackHasActiveImportsError, rt as refStateLookupFromResource, s as planRollback, sn as getDockerCmd, st as assertRegionMatch, t as DEFAULT_RESOURCE_TIMEOUT_MS, tn as readBootstrapMarkerBody, tr as ResourceTimeoutError, tt as cfnRefValueFromPhysicalId, u as updatePartialMessage, un as AssetManifestLoader, ur as withErrorHandling, ut as configStringRefusal, v as ATOMIC_FINAL_SNAPSHOT_TYPES, vn as resolveCaptureObservedState, vt as TEMPLATE_SOURCED_RULES, w as refusesFinalSnapshot, wn as warnDeprecatedNoPrefixCliFlag, wt as scrubResourceRecord, x as ccRoutedFinalSnapshotError, xn as resolveStateBucketWithDefaultAndSource, xt as isSingleDynamicReferenceToken, y as PRE_DELETE_SNAPSHOT_TYPES, yn as resolveSkipPrefix, yt as createSecretMasker, z as collectPublishedOutputNames, zn as getAwsClients, zt as rebuildClientForBucketRegion } from "./deploy-engine--N_xnvjI.js";
 import { a as getLiveRenderer, c as PATTERN_B_RESOURCE_TYPES, d as generateResourceNameWithFallback, f as getCurrentStackName, h as withStackName, i as runStackBuffered, m as withSkipPrefix, n as getLogger, o as PATTERN_B_NAME_OPTIONS, s as PATTERN_B_NAME_PROPERTIES, u as generateResourceName } from "./logger-zRrlbaQt.js";
-import { t as ASGProvider } from "./asg-provider-Cq-oDB62.js";
+import { t as ASGProvider } from "./asg-provider-D5G53CUp.js";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { createHash, randomBytes, randomUUID } from "node:crypto";
 import { CopyObjectCommand, CreateBucketCommand, DeleteBucketAnalyticsConfigurationCommand, DeleteBucketCommand, DeleteBucketCorsCommand, DeleteBucketEncryptionCommand, DeleteBucketIntelligentTieringConfigurationCommand, DeleteBucketInventoryConfigurationCommand, DeleteBucketLifecycleCommand, DeleteBucketMetricsConfigurationCommand, DeleteBucketOwnershipControlsCommand, DeleteBucketPolicyCommand, DeleteBucketReplicationCommand, DeleteBucketTaggingCommand, DeleteBucketWebsiteCommand, DeleteObjectsCommand, GetBucketAccelerateConfigurationCommand, GetBucketCorsCommand, GetBucketEncryptionCommand, GetBucketLifecycleConfigurationCommand, GetBucketLocationCommand, GetBucketLoggingCommand, GetBucketNotificationConfigurationCommand, GetBucketOwnershipControlsCommand, GetBucketPolicyCommand, GetBucketReplicationCommand, GetBucketTaggingCommand, GetBucketVersioningCommand, GetBucketWebsiteCommand, GetObjectCommand, GetObjectLockConfigurationCommand, GetPublicAccessBlockCommand, HeadBucketCommand, ListBucketAnalyticsConfigurationsCommand, ListBucketIntelligentTieringConfigurationsCommand, ListBucketInventoryConfigurationsCommand, ListBucketMetricsConfigurationsCommand, ListObjectVersionsCommand, ListObjectsV2Command, NoSuchBucket, PutBucketAccelerateConfigurationCommand, PutBucketAnalyticsConfigurationCommand, PutBucketCorsCommand, PutBucketEncryptionCommand, PutBucketIntelligentTieringConfigurationCommand, PutBucketInventoryConfigurationCommand, PutBucketLifecycleConfigurationCommand, PutBucketLoggingCommand, PutBucketMetricsConfigurationCommand, PutBucketNotificationConfigurationCommand, PutBucketOwnershipControlsCommand, PutBucketPolicyCommand, PutBucketReplicationCommand, PutBucketTaggingCommand, PutBucketVersioningCommand, PutBucketWebsiteCommand, PutObjectCommand, PutObjectLockConfigurationCommand, PutPublicAccessBlockCommand, S3Client, S3ServiceException } from "@aws-sdk/client-s3";
@@ -112,7 +112,11 @@ const commonOptions = [
 * Kept (rather than fully removed) so that scripts or muscle memory passing
 * `--region` do not break. The value IS still honored — every non-bootstrap
 * command consumes `options.region` as the highest-precedence region source
-* (`options.region || AWS_REGION || 'us-east-1'`): it sets the region of the
+* (`--region` -> `AWS_REGION` -> `us-east-1`, except `cdkd gc` and `cdkd
+* bootstrap --destroy`, which resolve the profile region and REFUSE rather
+* than falling back to a literal, because they delete — issue #2029; the
+* value is folded to its canonical spelling at each handler's entry, issue
+* #2065): it sets the region of the
 * provisioning / state-bucket SDK clients, the `applyRoleArnIfSet` STS hop,
 * and (for `deploy` / `destroy` / `import` / `export` / `orphan`) the
 * `AWS_REGION` env var inherited by the CDK synth subprocess. The flag is
@@ -776,6 +780,92 @@ const destroyOptions = [
 */
 const skipFinalSnapshotOption = new Option("--skip-final-snapshot", "Delete resources whose DeletionPolicy (or, on replacements, UpdateReplacePolicy) is 'Snapshot' WITHOUT creating the final snapshot the policy promises (DATA LOSS — explicit opt-out of CloudFormation parity). By default cdkd creates the final snapshot for every CloudFormation-supported type (RDS DBInstance / DBCluster, Neptune / DocDB clusters, ElastiCache CacheCluster / ReplicationGroup, Redshift Cluster, EC2 Volume) and refuses the delete when it cannot — e.g. a resource managed via the Cloud Control API route, whose delete has no final-snapshot parameter. On 'cdkd rollback' the flag governs the rolled-back CREATE's DeletionPolicy; a reverse-replacement delete of the NEW resource keeps its own bounded UpdateReplacePolicy behavior and is unaffected.").default(false);
 
+//#endregion
+//#region src/cli/region-options.ts
+/**
+* ONE region-normalization point for the CLI's command handlers.
+*
+* Issue [#1795](https://github.com/go-to-k/cdkd/issues/1795) folded `--region`
+* at the boundary of the four `cdkd local *` commands, for a reason that was
+* never specific to them: AWS SDK endpoint resolution, SigV4's credential
+* scope, this repo's own `PARTITION_TABLE` prefix walk and every ARN segment
+* built from the value are ALL case-sensitive, so a raw spelling is wrong at
+* each of them. Issue
+* [#2065](https://github.com/go-to-k/cdkd/issues/2065) measured what that costs
+* the commands the fix skipped — `cdkd deploy --region US-EAST-1` dies at the
+* state-bucket preflight before it does anything:
+*
+* ```text
+* FAIL S3  ListObjectsV2  region=US-EAST-1  AuthorizationHeaderMalformed:
+*          the region 'US-EAST-1' is wrong; expecting 'us-east-1'
+* ```
+*
+* The fold lives here rather than at each consumer because a command reads
+* `options.region` in many places — `applyRoleArnIfSet`, the
+* `process.env.AWS_REGION` copy, several `new AwsClients({ region })` spreads —
+* and folding per consumer is the shape that has needed a follow-up every time
+* a new consumer was added. Double-folding is a no-op, which is what makes a
+* second fold further down (`derivePartitionAndUrlSuffix`, `AwsClients`) safe
+* rather than redundant.
+*/
+/**
+* Fold `--region` to its canonical spelling in place, at the handler's entry.
+*
+* Call this BEFORE the first consumer of `options.region` — in practice before
+* `applyRoleArnIfSet`, which is the first AWS-touching call in most handlers.
+*
+* A handler that ALSO needs the user's exact spelling must capture it first.
+* The one consumer with that need is the bootstrap-marker read, whose second
+* probe exists precisely to find a key an unfolded `cdkd bootstrap` wrote
+* (see `readBootstrapMarkerBody` in `src/assets/asset-storage.ts`); the
+* `--stack-region` fold in `local-invoke.ts` keeps a `rawStackRegion` for the
+* same class of reason.
+*/
+function foldRegionOption(options) {
+	if (options.region !== void 0) options.region = canonicalizeRegion(options.region);
+	for (const key of ["AWS_REGION", "AWS_DEFAULT_REGION"]) {
+		const value = process.env[key];
+		if (value) process.env[key] = canonicalizeRegion(value);
+	}
+}
+/**
+* The region the user NAMED — `--region` first, then `AWS_REGION` — canonical,
+* or `undefined` when they named NEITHER.
+*
+* `undefined` is a distinct answer from any region string, and the distinction
+* is the whole point of this helper. Issue
+* [#2029](https://github.com/go-to-k/cdkd/issues/2029): materializing a
+* `|| 'us-east-1'` literal collapses "the user named no region" into "the user
+* named us-east-1", and the literal then wins over the profile region the AWS
+* SDK's own chain would have resolved from `~/.aws/config`. For `cdkd gc` that
+* meant evaluating — and deleting in — a region the user never mentioned, with
+* no error, because `us-east-1` is a perfectly valid region.
+*
+* So a caller that builds an SDK client spreads this CONDITIONALLY
+* (`...(named !== undefined && { region: named })`) and lets an absent region
+* stay absent. A caller that needs a region as a VALUE — a state key, a bucket
+* name, a marker key — must resolve one rather than pin a literal, and must
+* resolve the SAME one its clients use or the two silently disagree.
+*
+* Deliberately reads `AWS_REGION` only, not `AWS_DEFAULT_REGION`: that is the
+* precedence every one of these handlers already had, and widening it is a
+* behavior change with no defect behind it.
+*/
+function namedCliRegion(optionRegion) {
+	return canonicalizeRegion(optionRegion || process.env["AWS_REGION"]) || void 0;
+}
+/**
+* The user's EXACT `--region` / `AWS_REGION` spelling, unfolded.
+*
+* Only the bootstrap-marker read wants this — it probes the canonical key
+* first and this spelling second, so that a marker written by a pre-fold
+* `cdkd bootstrap` is still found. Every other consumer wants
+* {@link namedCliRegion}.
+*/
+function rawCliRegion(optionRegion) {
+	return optionRegion || process.env["AWS_REGION"] || void 0;
+}
+
 //#endregion
 //#region src/cli/commands/state-file-keys.ts
 /**
@@ -1067,13 +1157,12 @@ async function bootstrapDestroyCommand(options) {
 	logger.debug("Options:", options);
 	await applyRoleArnIfSet({
 		roleArn: options.roleArn,
-		region: canonicalizeRegion(options.region)
+		region: namedCliRegion(options.region)
 	});
-	const rawRegion = options.region || process.env["AWS_REGION"] || "us-east-1";
-	const region = canonicalizeRegion(rawRegion);
-	const clientRegion = canonicalizeRegion(options.region || process.env["AWS_REGION"]) || void 0;
+	const region = namedCliRegion(options.region) ?? "us-east-1";
+	const rawRegion = rawCliRegion(options.region) ?? region;
 	const awsClients = new AwsClients({
-		...clientRegion !== void 0 && { region: clientRegion },
+		region,
 		...options.profile && { profile: options.profile }
 	});
 	setAwsClients(awsClients);
@@ -1202,6 +1291,8 @@ async function bootstrapCommand(options) {
 	if (options.verbose) logger.setLevel("debug");
 	logger.info("Starting cdkd bootstrap...");
 	logger.debug("Options:", options);
+	const rawRegion = rawCliRegion(options.region) ?? "us-east-1";
+	foldRegionOption(options);
 	await applyRoleArnIfSet({
 		roleArn: options.roleArn,
 		region: options.region
@@ -1212,7 +1303,7 @@ async function bootstrapCommand(options) {
 	});
 	setAwsClients(awsClients);
 	const s3Client = awsClients.s3;
-	const region = options.region || process.env["AWS_REGION"] || "us-east-1";
+	const region = namedCliRegion(options.region) ?? "us-east-1";
 	let bucketName;
 	let accountId;
 	if (options.stateBucket) {
@@ -1310,7 +1401,7 @@ async function bootstrapCommand(options) {
 					ecrClient,
 					stateBackend,
 					accountId,
-					region,
+					region: rawRegion,
 					force: options.force,
 					...options.assetBucket && { assetBucketName: options.assetBucket },
 					...options.containerRepo && { containerRepoName: options.containerRepo }
@@ -1340,7 +1431,7 @@ async function bootstrapCommand(options) {
 * Create bootstrap command
 */
 function createBootstrapCommand() {
-	const cmd = new Command("bootstrap").description("Bootstrap cdkd by creating the S3 state bucket plus cdkd-owned asset storage (asset bucket + container-asset ECR repo) for the region. With --destroy, tear down the region's asset storage instead (issue #1010).").option("--state-bucket <bucket>", "Name of S3 bucket to create for state storage (default: cdkd-state-{accountId})").option("--force", "Create: force reconfiguration of an existing bucket. Destroy: delete the asset storage even when deployed stacks still reference it", false).option("--no-assets", "Skip cdkd asset storage (asset bucket / ECR repo / marker) — deploys keep publishing assets to the CDK bootstrap bucket/repo").option("--asset-bucket <name>", "Custom name for the cdkd asset bucket (default: cdkd-assets-{accountId}-{region}). Written into the bootstrap marker; re-bootstrapping a region with a different name is refused").option("--container-repo <name>", "Custom name for the container-asset ECR repository (default: cdkd-container-assets-{accountId}-{region}). Written into the bootstrap marker; re-bootstrapping a region with a different name is refused").option("--destroy", "Tear down the region's cdkd asset storage (empty + delete the asset bucket, force-delete the container-asset ECR repo, then delete the bootstrap marker last). The state bucket is kept unless --include-state-bucket is also passed", false).option("--include-state-bucket", "With --destroy: also delete the S3 state bucket. Refused while any stack state exists or any other region is still opted in to asset storage", false).addOption(new Option("--region <region>", "AWS region in which to create the state bucket (defaults to AWS_REGION env or us-east-1)")).action(withErrorHandling(async (options) => {
+	const cmd = new Command("bootstrap").description("Bootstrap cdkd by creating the S3 state bucket plus cdkd-owned asset storage (asset bucket + container-asset ECR repo) for the region. With --destroy, tear down the region's asset storage instead (issue #1010).").option("--state-bucket <bucket>", "Name of S3 bucket to create for state storage (default: cdkd-state-{accountId})").option("--force", "Create: force reconfiguration of an existing bucket. Destroy: delete the asset storage even when deployed stacks still reference it", false).option("--no-assets", "Skip cdkd asset storage (asset bucket / ECR repo / marker) — deploys keep publishing assets to the CDK bootstrap bucket/repo").option("--asset-bucket <name>", "Custom name for the cdkd asset bucket (default: cdkd-assets-{accountId}-{region}). Written into the bootstrap marker; re-bootstrapping a region with a different name is refused").option("--container-repo <name>", "Custom name for the container-asset ECR repository (default: cdkd-container-assets-{accountId}-{region}). Written into the bootstrap marker; re-bootstrapping a region with a different name is refused").option("--destroy", "Tear down the region's cdkd asset storage (empty + delete the asset bucket, force-delete the container-asset ECR repo, then delete the bootstrap marker last). The state bucket is kept unless --include-state-bucket is also passed", false).option("--include-state-bucket", "With --destroy: also delete the S3 state bucket. Refused while any stack state exists or any other region is still opted in to asset storage", false).addOption(new Option("--region <region>", "AWS region to bootstrap, or to tear down with --destroy (defaults to AWS_REGION env, else us-east-1)")).action(withErrorHandling(async (options) => {
 		if (options.destroy) {
 			if (options.assetBucket !== void 0 || options.containerRepo !== void 0) throw new CdkdError("--asset-bucket / --container-repo cannot be combined with --destroy. The teardown reads the region's asset storage names from the bootstrap marker.", "INVALID_OPTIONS");
 			if (!options.assets) throw new CdkdError("--no-assets cannot be combined with --destroy. The teardown scope is the asset storage itself; use --include-state-bucket to also delete the state bucket.", "INVALID_OPTIONS");
@@ -1431,6 +1522,7 @@ async function synthCommand(options) {
 	const logger = getLogger();
 	if (options.verbose) logger.setLevel("debug");
 	warnIfDeprecatedRegion(options);
+	foldRegionOption(options);
 	await applyRoleArnIfSet({
 		roleArn: options.roleArn,
 		region: options.region
@@ -1568,6 +1660,7 @@ async function listCommand(patterns, options) {
 	const logger = getLogger();
 	if (options.verbose) logger.setLevel("debug");
 	warnIfDeprecatedRegion(options);
+	foldRegionOption(options);
 	await applyRoleArnIfSet({
 		roleArn: options.roleArn,
 		region: options.region
@@ -59271,6 +59364,8 @@ async function deployCommand(stacks, options) {
 	validateResourceTimeouts(options);
 	setResolvedResourceTimeouts(options.resourceTimeout);
 	applyWaitFlagEnv(options);
+	const rawBaseRegion = rawCliRegion(options.region) ?? "us-east-1";
+	foldRegionOption(options);
 	await applyRoleArnIfSet({
 		roleArn: options.roleArn,
 		region: options.region
@@ -59282,7 +59377,7 @@ async function deployCommand(stacks, options) {
 	const app = resolveApp(options.app);
 	if (!app) throw new Error("No app command specified. Use --app, set CDKD_APP env var, or add \"app\" to cdk.json");
 	options.app = app;
-	const region = options.region || process.env["AWS_REGION"] || "us-east-1";
+	const region = namedCliRegion(options.region) ?? "us-east-1";
 	logger.debug("Starting deployment...");
 	logger.debug("Options:", options);
 	if (options.region) {
@@ -59383,7 +59478,7 @@ async function deployCommand(stacks, options) {
 		});
 		await synthesizer.expandMacrosForStacks(targetStacks, synthOptions);
 		const { STSClient, GetCallerIdentityCommand } = await import("@aws-sdk/client-sts");
-		const stsClient = new STSClient({ region: options.region || process.env["AWS_REGION"] || "us-east-1" });
+		const stsClient = new STSClient({ region: namedCliRegion(options.region) ?? "us-east-1" });
 		const accountId = (await stsClient.send(new GetCallerIdentityCommand({}))).Account;
 		stsClient.destroy();
 		const assetPublisher = new AssetPublisher();
@@ -59407,7 +59502,7 @@ async function deployCommand(stacks, options) {
 		};
 		const dagBuilder = new DagBuilder({ relaxCdkVpcDefensiveDeps: !!options.aggressiveVpcParallel });
 		const diffCalculator = new DiffCalculator();
-		const baseRegion = options.region || process.env["AWS_REGION"] || "us-east-1";
+		const baseRegion = namedCliRegion(options.region) ?? "us-east-1";
 		const switchRegion = (region) => {
 			process.env["AWS_REGION"] = region;
 			process.env["AWS_DEFAULT_REGION"] = region;
@@ -59422,7 +59517,7 @@ async function deployCommand(stacks, options) {
 				const assetRegion = stack.region || baseRegion;
 				const manifest = loadPublishableAssetManifest(stack.assetManifestPath);
 				if (manifest) {
-					const assetMode = await assetModeResolver.resolve(assetRegion);
+					const assetMode = await assetModeResolver.resolve(stack.region || rawBaseRegion);
 					logger.debug(`Asset mode for region ${assetRegion}: ${assetMode.mode} (stack ${stack.stackName})`);
 					let redirect;
 					if (assetMode.mode === "cdkd-assets") {
@@ -61582,6 +61677,7 @@ async function diffCommand(stacks, options) {
 	if (options.json) logger.setLevel("warn");
 	else if (options.verbose) logger.setLevel("debug");
 	warnIfDeprecatedRegion(options);
+	foldRegionOption(options);
 	await applyRoleArnIfSet({
 		roleArn: options.roleArn,
 		region: options.region
@@ -61589,7 +61685,7 @@ async function diffCommand(stacks, options) {
 	const app = resolveApp(options.app);
 	if (!app) throw new Error("No app command specified. Use --app, set CDKD_APP env var, or add \"app\" to cdk.json");
 	options.app = app;
-	const region = options.region || process.env["AWS_REGION"] || "us-east-1";
+	const region = namedCliRegion(options.region) ?? "us-east-1";
 	const stateBucket = await resolveStateBucketWithDefault(options.stateBucket, region);
 	logger.info("Calculating diff...");
 	logger.debug("Options:", options);
@@ -61783,13 +61879,14 @@ async function scrubCommand(stacks, options) {
 	const logger = getLogger();
 	if (options.verbose) logger.setLevel("debug");
 	warnIfDeprecatedRegion(options);
+	foldRegionOption(options);
 	await applyRoleArnIfSet({
 		roleArn: options.roleArn,
 		region: options.region
 	});
 	const app = resolveApp(options.app);
 	if (!app) throw new Error("CDK app is required (scrub needs the template to identify secret references). Pass --app, set CDKD_APP, or add \"app\" to cdk.json.");
-	const region = options.region || process.env["AWS_REGION"] || "us-east-1";
+	const region = namedCliRegion(options.region) ?? "us-east-1";
 	const stateBucket = await resolveStateBucketWithDefault(options.stateBucket, region);
 	setAwsClients(new AwsClients({
 		...options.region && { region: options.region },
@@ -63178,6 +63275,7 @@ async function driftCommand(stacks, options) {
 	if (options.verbose) logger.setLevel("debug");
 	warnIfDeprecatedRegion(options);
 	if (options.accept && options.revert) throw new Error("--accept and --revert are mutually exclusive. Use --accept to update cdkd state from AWS, or --revert to push cdkd state values back into AWS.");
+	foldRegionOption(options);
 	await applyRoleArnIfSet({
 		roleArn: options.roleArn,
 		region: options.region
@@ -63188,7 +63286,7 @@ async function driftCommand(stacks, options) {
 	});
 	setAwsClients(awsClients);
 	try {
-		const region = options.region || process.env["AWS_REGION"] || "us-east-1";
+		const region = namedCliRegion(options.region) ?? "us-east-1";
 		const bucket = await resolveStateBucketWithDefault(options.stateBucket, region);
 		const stateConfig = {
 			bucket,
@@ -64858,11 +64956,12 @@ async function destroyCommand(stackArgs, options) {
 	warnIfDeprecatedRegion(options);
 	validateResourceTimeouts(options);
 	setResolvedResourceTimeouts(options.resourceTimeout);
+	foldRegionOption(options);
 	await applyRoleArnIfSet({
 		roleArn: options.roleArn,
 		region: options.region
 	});
-	const region = options.region || process.env["AWS_REGION"] || "us-east-1";
+	const region = namedCliRegion(options.region) ?? "us-east-1";
 	const stateBucket = await resolveStateBucketWithDefault(options.stateBucket, region);
 	logger.info("Starting stack destruction...");
 	logger.debug("Options:", options);
@@ -65137,11 +65236,12 @@ function createDestroyCommand() {
 async function stateMigrateCommand(options) {
 	const logger = getLogger();
 	if (options.verbose) logger.setLevel("debug");
+	foldRegionOption(options);
 	await applyRoleArnIfSet({
 		roleArn: options.roleArn,
 		region: options.region
 	});
-	const region = options.region || process.env["AWS_REGION"] || "us-east-1";
+	const region = namedCliRegion(options.region) ?? "us-east-1";
 	const awsClients = new AwsClients({
 		region,
 		...options.profile && { profile: options.profile }
@@ -66597,11 +66697,12 @@ async function exportCommand(stackArg, options) {
 	}
 	warnIfDeprecatedRegion(options);
 	refuseTransientContextIfUnsafe(options);
+	foldRegionOption(options);
 	await applyRoleArnIfSet({
 		roleArn: options.roleArn,
 		region: options.region
 	});
-	const region = options.region || process.env["AWS_REGION"] || "us-east-1";
+	const region = namedCliRegion(options.region) ?? "us-east-1";
 	const stateBucket = await resolveStateBucketWithDefault(options.stateBucket, region);
 	if (options.region) {
 		process.env["AWS_REGION"] = options.region;
@@ -69017,6 +69118,7 @@ function resolveSingleRegion(stackName, refs, requestedRegion) {
 */
 async function setupStateBackend(options) {
 	warnIfDeprecatedRegion(options);
+	foldRegionOption(options);
 	await applyRoleArnIfSet({
 		roleArn: options.roleArn,
 		region: options.region
@@ -69026,7 +69128,7 @@ async function setupStateBackend(options) {
 		...options.profile && { profile: options.profile }
 	});
 	setAwsClients(awsClients);
-	const region = options.region || process.env["AWS_REGION"] || "us-east-1";
+	const region = namedCliRegion(options.region) ?? "us-east-1";
 	const bucket = await resolveStateBucketWithDefault(options.stateBucket, region);
 	const prefix = options.statePrefix;
 	const stateConfig = {
@@ -69917,6 +70019,7 @@ async function listAssetStorageMarkers(s3, bucket) {
 async function stateInfoCommand(options) {
 	const logger = getLogger();
 	if (options.verbose) logger.setLevel("debug");
+	foldRegionOption(options);
 	await applyRoleArnIfSet({
 		roleArn: options.roleArn,
 		region: options.region
@@ -69928,7 +70031,7 @@ async function stateInfoCommand(options) {
 	setAwsClients(awsClients);
 	let regionCorrectedS3 = null;
 	try {
-		const region = options.region || process.env["AWS_REGION"] || "us-east-1";
+		const region = namedCliRegion(options.region) ?? "us-east-1";
 		const resolved = await resolveStateBucketWithDefaultAndSource(options.stateBucket, region);
 		const bucket = resolved.bucket;
 		const prefix = options.statePrefix;
@@ -70663,6 +70766,7 @@ async function eventsCommand(stackName, options) {
 	const logger = getLogger();
 	if (options.verbose) logger.setLevel("debug");
 	warnIfDeprecatedRegion(options);
+	foldRegionOption(options);
 	const asJson = options.json === true;
 	const awsClients = new AwsClients({
 		...options.region && { region: options.region },
@@ -70670,7 +70774,7 @@ async function eventsCommand(stackName, options) {
 	});
 	setAwsClients(awsClients);
 	try {
-		const region = options.region || process.env["AWS_REGION"] || "us-east-1";
+		const region = namedCliRegion(options.region) ?? "us-east-1";
 		const bucket = await resolveStateBucketWithDefault(options.stateBucket, region);
 		const prefix = options.statePrefix ?? "cdkd";
 		const stateBackend = new S3StateBackend(awsClients.s3, {
@@ -70740,6 +70844,7 @@ async function eventsPruneCommand(stackName, options) {
 	const logger = getLogger();
 	if (options.verbose) logger.setLevel("debug");
 	warnIfDeprecatedRegion(options);
+	foldRegionOption(options);
 	if (options.all === true && (options.keep !== void 0 || options.olderThan !== void 0)) throw new CdkdError("'--all' purges every run and cannot be combined with '--keep' / '--older-than'.", "EVENTS_PRUNE_BAD_FLAGS");
 	const olderThanMs = options.olderThan !== void 0 ? parseDuration(options.olderThan) : void 0;
 	const awsClients = new AwsClients({
@@ -70748,7 +70853,7 @@ async function eventsPruneCommand(stackName, options) {
 	});
 	setAwsClients(awsClients);
 	try {
-		const region = options.region || process.env["AWS_REGION"] || "us-east-1";
+		const region = namedCliRegion(options.region) ?? "us-east-1";
 		const bucket = await resolveStateBucketWithDefault(options.stateBucket, region);
 		const prefix = options.statePrefix ?? "cdkd";
 		const stateBackend = new S3StateBackend(awsClients.s3, {
@@ -71800,7 +71905,7 @@ function formatAge(date) {
 async function promptGcConfirm(input) {
 	const logger = getLogger();
 	logger.warn("");
-	logger.warn("cdkd gc will delete the following unreferenced assets:");
+	logger.warn(`cdkd gc will delete the following unreferenced assets in ${input.region}:`);
 	for (const line of input.planLines) logger.warn(`  - ${line}`);
 	if (input.yes) return true;
 	if (process.stdin.isTTY !== true) throw new CdkdError("The gc confirmation prompt cannot run in a non-interactive environment. Pass --yes / -y to confirm the deletion, or run the command from a real terminal.", "NON_INTERACTIVE_CONFIRM");
@@ -71863,10 +71968,10 @@ async function gcCommand(options) {
 	logger.debug("Options:", options);
 	await applyRoleArnIfSet({
 		roleArn: options.roleArn,
-		region: canonicalizeRegion(options.region)
+		region: namedCliRegion(options.region)
 	});
-	const rawRegion = options.region || process.env["AWS_REGION"] || "us-east-1";
-	const region = canonicalizeRegion(rawRegion);
+	const region = namedCliRegion(options.region) ?? "us-east-1";
+	const rawRegion = rawCliRegion(options.region) ?? region;
 	const awsClients = new AwsClients({
 		region,
 		...options.profile && { profile: options.profile }
@@ -71930,7 +72035,7 @@ async function gcCommand(options) {
 		const totals = `Total: ${s3Candidates.length} S3 object(s) (${formatBytes(s3Bytes)}) + ${ecrCandidates.length} ECR image(s) (${formatBytes(ecrBytes)}) = ${formatBytes(s3Bytes + ecrBytes)} reclaimable`;
 		if (options.dryRun) {
 			logger.info("");
-			logger.info("Dry run — the following unreferenced assets would be deleted:");
+			logger.info(`Dry run — the following unreferenced assets in ${region} would be deleted:`);
 			for (const line of planLines) logger.info(`  - ${line}`);
 			logger.info(totals);
 			logger.info("Dry run: nothing deleted. Re-run without --dry-run to delete.");
@@ -71938,7 +72043,8 @@ async function gcCommand(options) {
 		}
 		if (!await promptGcConfirm({
 			planLines: [...planLines, totals],
-			yes: options.yes
+			yes: options.yes,
+			region
 		})) {
 			logger.info("gc cancelled — nothing deleted.");
 			return;
@@ -71962,7 +72068,7 @@ async function gcCommand(options) {
 * Create the `cdkd gc` command (upstream `cdk gc` parity naming).
 */
 function createGcCommand() {
-	const cmd = new Command("gc").description("Garbage-collect unreferenced objects / images from ONE region's cdkd-owned asset storage (asset bucket + container-asset ECR repo). References are collected from every cdkd state file; CDK bootstrap storage is never touched (use cdk gc for that).").option("--state-bucket <bucket>", "S3 bucket holding cdkd state (default: cdkd-state-{accountId})").addOption(new Option("--older-than <duration>", "Never delete an object / image newer than this age, even when unreferenced (protects in-flight publishes and recent rollback targets). Accepts <n>d / <n>h.").default(DEFAULT_OLDER_THAN_MS, "30d").argParser(parseOlderThan)).option("--dry-run", "Print the reclaim plan (per-item list + totals) without deleting", false).addOption(new Option("--region <region>", "Region whose cdkd asset storage to garbage-collect (defaults to AWS_REGION env or us-east-1)")).action(withErrorHandling(async (options) => {
+	const cmd = new Command("gc").description("Garbage-collect unreferenced objects / images from ONE region's cdkd-owned asset storage (asset bucket + container-asset ECR repo). References are collected from every cdkd state file; CDK bootstrap storage is never touched (use cdk gc for that).").option("--state-bucket <bucket>", "S3 bucket holding cdkd state (default: cdkd-state-{accountId})").addOption(new Option("--older-than <duration>", "Never delete an object / image newer than this age, even when unreferenced (protects in-flight publishes and recent rollback targets). Accepts <n>d / <n>h.").default(DEFAULT_OLDER_THAN_MS, "30d").argParser(parseOlderThan)).option("--dry-run", "Print the reclaim plan (per-item list + totals) without deleting", false).addOption(new Option("--region <region>", "Region whose cdkd asset storage to garbage-collect (defaults to AWS_REGION / AWS_DEFAULT_REGION, else the profile region; refuses if none is configured)")).action(withErrorHandling(async (options) => {
 		await gcCommand(options);
 	}));
 	commonOptions.forEach((opt) => cmd.addOption(opt));
@@ -72462,13 +72568,14 @@ async function orphanCommand(pathArgs, options) {
 	const logger = getLogger();
 	if (options.verbose) logger.setLevel("debug");
 	warnIfDeprecatedRegion(options);
+	foldRegionOption(options);
 	await applyRoleArnIfSet({
 		roleArn: options.roleArn,
 		region: options.region
 	});
 	if (pathArgs.length === 0) throw new Error("'cdkd orphan' requires at least one construct path, e.g. 'cdkd orphan MyStack/MyTable'.\n       To remove a stack's state record (the previous behavior), use:\n         cdkd state orphan MyStack");
 	for (const p of pathArgs) if (!p.includes("/")) throw new Error(`'cdkd orphan' now expects a construct path like 'MyStack/MyTable'.\n       Got: '${p}'\n       To remove a stack's state record (the previous behavior), use:\n         cdkd state orphan ${p}`);
-	const region = options.region || process.env["AWS_REGION"] || "us-east-1";
+	const region = namedCliRegion(options.region) ?? "us-east-1";
 	const stateBucket = await resolveStateBucketWithDefault(options.stateBucket, region);
 	if (options.region) {
 		process.env["AWS_REGION"] = options.region;
@@ -72705,6 +72812,8 @@ async function publishAssetsCommand(stacks, options) {
 	const logger = getLogger();
 	if (options.verbose) logger.setLevel("debug");
 	warnIfDeprecatedRegion(options);
+	const rawBaseRegion = rawCliRegion(options.region) ?? "us-east-1";
+	foldRegionOption(options);
 	await applyRoleArnIfSet({
 		roleArn: options.roleArn,
 		region: options.region
@@ -72730,7 +72839,7 @@ async function publishAssetsCommand(stacks, options) {
 	else if (allStacks.length === 1) targetStacks = allStacks;
 	else throw new Error(`Multiple stacks found: ${allStacks.map(describeStack).join(", ")}. Specify stack name(s) or use --all`);
 	if (targetStacks.length === 0) throw new Error(stackPatterns.length > 0 ? `No stacks matching ${stackPatterns.join(", ")} found in assembly. Available: ${allStacks.map(describeStack).join(", ")}` : "No stacks found in assembly");
-	const baseRegion = options.region || process.env["AWS_REGION"] || "us-east-1";
+	const baseRegion = namedCliRegion(options.region) ?? "us-east-1";
 	const { STSClient, GetCallerIdentityCommand } = await import("@aws-sdk/client-sts");
 	const stsClient = new STSClient({ region: baseRegion });
 	const accountId = (await stsClient.send(new GetCallerIdentityCommand({}))).Account;
@@ -72790,7 +72899,7 @@ async function publishAssetsCommand(stacks, options) {
 						const modeResolver = await getModeResolver();
 						if (modeResolver) {
 							const stackRegion = stack.region || baseRegion;
-							const assetMode = await modeResolver.resolve(stackRegion);
+							const assetMode = await modeResolver.resolve(stack.region || rawBaseRegion);
 							if (assetMode.mode === "cdkd-assets") {
 								const map = buildAssetRedirectMap(manifest, assetMode.marker, accountId, stackRegion);
 								if (map.entries.length > 0) redirect = map;
@@ -72898,6 +73007,7 @@ async function forceUnlockCommand(stackArgs, options) {
 	const logger = getLogger();
 	if (options.verbose) logger.setLevel("debug");
 	warnIfDeprecatedRegion(options);
+	foldRegionOption(options);
 	await applyRoleArnIfSet({
 		roleArn: options.roleArn,
 		region: options.region
@@ -72909,7 +73019,7 @@ async function forceUnlockCommand(stackArgs, options) {
 		...options.profile && { profile: options.profile }
 	});
 	setAwsClients(awsClients);
-	const region = options.region || process.env["AWS_REGION"] || "us-east-1";
+	const region = namedCliRegion(options.region) ?? "us-east-1";
 	const stateBucket = await resolveStateBucketWithDefault(options.stateBucket, region);
 	try {
 		const stateConfig = {
@@ -72968,11 +73078,12 @@ async function importCommand(stackArg, options) {
 		logger.setLevel("debug");
 		process.env["CDKD_NO_LIVE"] = "1";
 	}
+	foldRegionOption(options);
 	await applyRoleArnIfSet({
 		roleArn: options.roleArn,
 		region: options.region
 	});
-	const region = options.region || process.env["AWS_REGION"] || "us-east-1";
+	const region = namedCliRegion(options.region) ?? "us-east-1";
 	const stateBucket = await resolveStateBucketWithDefault(options.stateBucket, region);
 	if (options.region) {
 		process.env["AWS_REGION"] = options.region;
@@ -83562,11 +83673,12 @@ async function migrateCommandAction(positionalStack, options) {
 	if (options.retireCfnStack && options.skipSynth) throw new LocalMigrateError("--retire-cfn-stack is incompatible with --skip-synth: the post-state-write retirement (UpdateStack + DeleteStack) cannot run without a synthesized template + cdkd state.");
 	if (options.retireCfnStack && options.dryRun) throw new LocalMigrateError("--retire-cfn-stack is incompatible with --dry-run: retirement issues real AWS calls (UpdateStack injects Retain policies, then DeleteStack).");
 	if (options.retireCfnStack && options.filter && options.filter.length > 0) throw new LocalMigrateError("--retire-cfn-stack is incompatible with --filter: a partial migration that retires the whole source CFn stack would strand the un-migrated resources. Drop one of the flags or migrate the rest of the stack first.");
+	foldRegionOption(options);
 	await applyRoleArnIfSet({
 		roleArn: options.roleArn,
 		region: options.region
 	});
-	const region = options.region || process.env["AWS_REGION"] || "us-east-1";
+	const region = namedCliRegion(options.region) ?? "us-east-1";
 	const outputDir = resolve(options.outputDir ?? sourceCfnStackName);
 	logger.info(`[migrate] Source CFn stack: ${sourceCfnStackName}`);
 	logger.info(`[migrate] Output directory: ${outputDir}`);
@@ -83731,7 +83843,7 @@ function createMigrateCommand() {
 */
 function buildProgram() {
 	const program = new Command();
-	program.name("cdkd").description("CDK Direct - Deploy AWS CDK apps directly via SDK/Cloud Control API").version("0.284.20");
+	program.name("cdkd").description("CDK Direct - Deploy AWS CDK apps directly via SDK/Cloud Control API").version("0.284.21");
 	program.hook("preAction", (_thisCommand, actionCommand) => {
 		const { profile } = actionCommand.optsWithGlobals();
 		if (profile !== void 0) process.env["AWS_PROFILE"] = profile;