@go-to-k/cdkd 0.237.0 → 0.238.0

package/README.md

@@ -243,6 +243,7 @@ cdkd publish-assets                 # synth + upload only (typical CI split)
 cdkd destroy MyStack
 cdkd orphan MyStack/MyBucket        # drop one resource from state (AWS resource stays)
 cdkd force-unlock MyStack           # clear stale lock from an interrupted deploy
+cdkd gc --dry-run                   # reclaim unreferenced cdkd-owned assets (S3 + ECR)
 
 # Migrate between cdkd and CloudFormation
 cdkd import MyStack --yes           # adopt existing AWS resources into cdkd state

package/dist/cli.js

@@ -35,7 +35,7 @@ import { AssociateVPCWithHostedZoneCommand, ChangeResourceRecordSetsCommand, Cha
 import { AddTagsCommand, CreateListenerCommand, CreateLoadBalancerCommand, CreateTargetGroupCommand, DeleteListenerCommand, DeleteLoadBalancerCommand, DeleteTargetGroupCommand, DescribeListenerAttributesCommand, DescribeListenersCommand, DescribeLoadBalancerAttributesCommand, DescribeLoadBalancersCommand, DescribeTagsCommand, DescribeTargetGroupsCommand, ElasticLoadBalancingV2Client, ModifyListenerAttributesCommand, ModifyListenerCommand, ModifyLoadBalancerAttributesCommand, ModifyTargetGroupCommand, RemoveTagsCommand, SetIpAddressTypeCommand, SetSecurityGroupsCommand, SetSubnetsCommand } from "@aws-sdk/client-elastic-load-balancing-v2";
 import { CreateAliasCommand, CreateKeyCommand, DeleteAliasCommand, DescribeKeyCommand, DisableKeyCommand, DisableKeyRotationCommand, EnableKeyCommand, EnableKeyRotationCommand, GetKeyPolicyCommand, GetKeyRotationStatusCommand, KMSClient, ListAliasesCommand, ListKeysCommand, ListResourceTagsCommand, NotFoundException as NotFoundException$2, PutKeyPolicyCommand, ScheduleKeyDeletionCommand, TagResourceCommand as TagResourceCommand$9, UntagResourceCommand as UntagResourceCommand$9, UpdateAliasCommand, UpdateKeyDescriptionCommand } from "@aws-sdk/client-kms";
 import { join as join$1 } from "path";
-import { CreateRepositoryCommand, DeleteLifecyclePolicyCommand, DeleteRepositoryCommand, DeleteRepositoryPolicyCommand, DescribeRepositoriesCommand, ECRClient, GetAuthorizationTokenCommand, GetLifecyclePolicyCommand, LifecyclePolicyNotFoundException, ListTagsForResourceCommand as ListTagsForResourceCommand$7, PutImageScanningConfigurationCommand, PutImageTagMutabilityCommand, PutLifecyclePolicyCommand, RepositoryNotFoundException, SetRepositoryPolicyCommand, TagResourceCommand as TagResourceCommand$10, UntagResourceCommand as UntagResourceCommand$10 } from "@aws-sdk/client-ecr";
+import { BatchDeleteImageCommand, CreateRepositoryCommand, DeleteLifecyclePolicyCommand, DeleteRepositoryCommand, DeleteRepositoryPolicyCommand, DescribeImagesCommand as DescribeImagesCommand$1, DescribeRepositoriesCommand, ECRClient, GetAuthorizationTokenCommand, GetLifecyclePolicyCommand, LifecyclePolicyNotFoundException, ListTagsForResourceCommand as ListTagsForResourceCommand$7, PutImageScanningConfigurationCommand, PutImageTagMutabilityCommand, PutLifecyclePolicyCommand, RepositoryNotFoundException, SetRepositoryPolicyCommand, TagResourceCommand as TagResourceCommand$10, UntagResourceCommand as UntagResourceCommand$10 } from "@aws-sdk/client-ecr";
 import graphlib from "graphlib";
 import { AddTagsToResourceCommand as AddTagsToResourceCommand$1, CreateDBClusterCommand, CreateDBInstanceCommand, CreateDBProxyCommand, CreateDBProxyEndpointCommand, CreateDBSubnetGroupCommand, DBProxyEndpointNotFoundFault, DBProxyNotFoundFault, DBProxyTargetGroupNotFoundFault, DBProxyTargetNotFoundFault, DeleteDBClusterCommand, DeleteDBInstanceCommand, DeleteDBProxyCommand, DeleteDBProxyEndpointCommand, DeleteDBSubnetGroupCommand, DeregisterDBProxyTargetsCommand, DescribeDBClustersCommand, DescribeDBInstancesCommand, DescribeDBProxiesCommand, DescribeDBProxyEndpointsCommand, DescribeDBProxyTargetGroupsCommand, DescribeDBProxyTargetsCommand, DescribeDBSubnetGroupsCommand, ListTagsForResourceCommand as ListTagsForResourceCommand$8, ModifyDBClusterCommand, ModifyDBInstanceCommand, ModifyDBProxyCommand, ModifyDBProxyEndpointCommand, ModifyDBProxyTargetGroupCommand, ModifyDBSubnetGroupCommand, RDSClient, RegisterDBProxyTargetsCommand, RemoveTagsFromResourceCommand as RemoveTagsFromResourceCommand$1 } from "@aws-sdk/client-rds";
 import { AddTagsToResourceCommand as AddTagsToResourceCommand$2, CreateCacheClusterCommand, CreateCacheSubnetGroupCommand, DeleteCacheClusterCommand, DeleteCacheSubnetGroupCommand, DescribeCacheClustersCommand, DescribeCacheSubnetGroupsCommand, ElastiCacheClient, ListTagsForResourceCommand as ListTagsForResourceCommand$9, ModifyCacheClusterCommand, ModifyCacheSubnetGroupCommand, RemoveTagsFromResourceCommand as RemoveTagsFromResourceCommand$2 } from "@aws-sdk/client-elasticache";
@@ -610,6 +610,63 @@ const destroyOptions = [
 	allowUnsupportedTypesOption
 ];
 
+//#endregion
+//#region src/cli/commands/state-file-keys.ts
+/**
+* Shared helpers for enumerating and describing cdkd state-bucket keys.
+*
+* Extracted from `bootstrap-destroy.ts` (issue #1010) so that `cdkd gc`
+* (issue #1012) reuses the exact same whole-bucket state-file discovery
+* instead of duplicating it — the "scan the WHOLE bucket, not just the
+* default `cdkd/` prefix" rule was a review blocker once already (PR #1018)
+* and must not drift between the two commands.
+*/
+/**
+* Every cdkd state file ends with this suffix, regardless of the
+* `--state-prefix` it was deployed under (`{prefix}/{stack}/{region}/state.json`,
+* or legacy `{prefix}/{stack}/state.json`).
+*/
+const STATE_FILE_SUFFIX = "/state.json";
+/**
+* Every cdkd stack lock ends with this suffix — the lock lives next to the
+* state file (`{prefix}/{stack}/{region}/lock.json`).
+*/
+const LOCK_FILE_SUFFIX = "/lock.json";
+/** `us-east-1` / `ap-northeast-1` / `us-gov-west-1` — a region-shaped segment. */
+const REGION_SEGMENT = /^[a-z]{2}(-[a-z]+)+-\d+$/;
+/**
+* List every state file in the bucket — the WHOLE bucket, not just the
+* default `cdkd/` prefix. Other commands accept `--state-prefix`, so live
+* stack state may exist under ANY prefix in this bucket; scoping this
+* listing to the default prefix would let reference scans and teardown
+* guards silently miss those stacks and delete live data.
+*/
+async function listAllStateKeys(stateBackend) {
+	return (await stateBackend.listRawKeys("")).filter((k) => k.endsWith(STATE_FILE_SUFFIX));
+}
+/**
+* List every stack lock file in the bucket — same whole-bucket rule as
+* {@link listAllStateKeys}. A lock under ANY prefix means a deploy /
+* destroy may be in flight for that stack.
+*/
+async function listAllLockKeys(stateBackend) {
+	return (await stateBackend.listRawKeys("")).filter((k) => k.endsWith(LOCK_FILE_SUFFIX));
+}
+/**
+* `{prefix}/{stack}/{region}/state.json` → `stack (region)`; legacy
+* `{prefix}/{stack}/state.json` → `stack`. The prefix is arbitrary (custom
+* `--state-prefix` values included), so the stack/region pair is derived
+* from the key's TAIL: the last segment is treated as a region only when
+* it is region-shaped. Pass {@link LOCK_FILE_SUFFIX} to describe lock keys.
+*/
+function describeStateKey(key, suffix = STATE_FILE_SUFFIX) {
+	const segments = key.slice(0, -suffix.length).split("/");
+	const last = segments[segments.length - 1] ?? key;
+	const secondLast = segments[segments.length - 2];
+	if (secondLast !== void 0 && REGION_SEGMENT.test(last)) return `${secondLast} (${last})`;
+	return last;
+}
+
 //#endregion
 //#region src/cli/commands/bootstrap-destroy.ts
 /**
@@ -638,25 +695,6 @@ const destroyOptions = [
 /** S3 key prefix for state files — same fixed value the create side uses. */
 const STATE_PREFIX = "cdkd";
 /**
-* Every cdkd state file ends with this suffix, regardless of the
-* `--state-prefix` it was deployed under (`{prefix}/{stack}/{region}/state.json`,
-* or legacy `{prefix}/{stack}/state.json`).
-*/
-const STATE_FILE_SUFFIX = "/state.json";
-/** `us-east-1` / `ap-northeast-1` / `us-gov-west-1` — a region-shaped segment. */
-const REGION_SEGMENT = /^[a-z]{2}(-[a-z]+)+-\d+$/;
-/**
-* List every state file in the bucket — the WHOLE bucket, not just the
-* default `cdkd/` prefix. Other commands accept `--state-prefix`, so live
-* stack state may exist under ANY prefix in this bucket; scoping this
-* listing to the default prefix would let the reference scan and the
-* `--include-state-bucket` guard silently miss those stacks and delete
-* live state.
-*/
-async function listAllStateKeys(stateBackend) {
-	return (await stateBackend.listRawKeys("")).filter((k) => k.endsWith(STATE_FILE_SUFFIX));
-}
-/**
 * Interactive confirmation for the teardown. Follows the repo's
 * destructive-prompt convention (see `recreate-confirm-prompt.ts`, the
 * same pattern family as `confirm-prompt.ts`): print the deletion plan as
@@ -709,20 +747,6 @@ async function scanStateReferences(stateBackend, names) {
 	return referencing;
 }
 /**
-* `{prefix}/{stack}/{region}/state.json` → `stack (region)`; legacy
-* `{prefix}/{stack}/state.json` → `stack`. The prefix is arbitrary (custom
-* `--state-prefix` values included), so the stack/region pair is derived
-* from the key's TAIL: the last segment is treated as a region only when
-* it is region-shaped.
-*/
-function describeStateKey(key) {
-	const segments = key.slice(0, -11).split("/");
-	const last = segments[segments.length - 1] ?? key;
-	const secondLast = segments[segments.length - 2];
-	if (secondLast !== void 0 && REGION_SEGMENT.test(last)) return `${secondLast} (${last})`;
-	return last;
-}
-/**
 * Empty (all versions + delete markers) and delete an S3 bucket, with
 * `ExpectedBucketOwner` pinned on every call — deleting a foreign bucket
 * that squatted the predictable name would be catastrophic, so the same
@@ -1861,7 +1885,7 @@ const FLUSH_INTERVAL_MS = 2e3;
 const FLUSH_EVENT_THRESHOLD = 50;
 /** Build-time cdkd version, with a dev fallback for non-built contexts. */
 function getCdkdVersion() {
-	return "0.237.0";
+	return "0.238.0";
 }
 /**
 * Generate a time-sortable unique run id, e.g.
@@ -41215,6 +41239,495 @@ function createEventsPruneCommand() {
 	})).option("--older-than <duration>", "Delete runs older than this duration (e.g. 24h, 90m)").option("--all", "Delete every recorded run and the index (full purge)", false).action(withErrorHandling((stack, _options, command) => eventsPruneCommand(stack, command.optsWithGlobals())));
 }
 
+//#endregion
+//#region src/cli/commands/gc.ts
+/**
+* `cdkd gc` — garbage-collect unreferenced objects / images from the
+* cdkd-owned asset storage of ONE region (issue #1012).
+*
+* cdkd-owned asset storage (issue #1002) is content-addressed and never
+* deleted on `cdkd destroy` (another stack or a future rollback may
+* reference the same hash), so the asset bucket / container-asset ECR repo
+* grow without bound — and `cdk gc` cannot reach them by design. cdkd can
+* gc them PRECISELY because its state files record exactly which assets
+* are in use.
+*
+* Safety posture (this command DELETES user data — every ambiguity is
+* biased toward NOT deleting):
+*
+* - Names come from the region's bootstrap marker, never recomputed from
+*   the naming convention (custom-name compatibility, issue #1011). No
+*   marker → the region is not opted in; friendly no-op. CDK bootstrap
+*   storage (`cdk-hnb659fds-*`) is never touched — that stays `cdk gc`'s
+*   job.
+* - The reference scan lists EVERY state file in the WHOLE state bucket
+*   (any `--state-prefix`), and a state file that fails to JSON-parse
+*   aborts the whole run — deleting on partial knowledge is how a live
+*   asset gets deleted.
+* - Any stack lock in the bucket aborts the run: a deploy in flight may
+*   have published assets whose state write has not landed yet.
+* - `--older-than` (default 30d) age-guards every deletion: an object /
+*   image newer than the cutoff is kept even when unreferenced (protects
+*   in-flight publishes and recent rollback targets). Missing timestamps
+*   are treated as "new" (kept).
+* - Every S3 call pins `ExpectedBucketOwner`; a 403 on the asset bucket is
+*   a foreign-bucket refusal like the create / teardown sides.
+*/
+/** Default `--older-than` when the flag is not passed. */
+const DEFAULT_OLDER_THAN_MS = 720 * 60 * 60 * 1e3;
+/** S3 `DeleteObjects` accepts at most 1,000 keys per call. */
+const S3_DELETE_BATCH_SIZE = 1e3;
+/** ECR `BatchDeleteImage` accepts at most 100 image ids per call. */
+const ECR_DELETE_BATCH_SIZE = 100;
+/**
+* Parse the `--older-than` age guard: `<n>d` (days) or `<n>h` (hours),
+* decimals allowed (`1.5d`). Zero, negative, missing-unit, and
+* unknown-unit values are rejected at parse time — a zero / negative age
+* guard would disable the in-flight-publish protection entirely.
+*
+* Kept local (rather than extending `parseDuration` in `options.ts`):
+* the deploy-side duration grammar is seconds/minutes/hours for
+* per-resource deadlines, while gc ages are naturally days — mixing `30s`
+* into an age guard invites typos that all but disable it.
+*/
+function parseOlderThan(value) {
+	const match = /^(\d+(?:\.\d+)?)([dh])$/.exec(value.trim());
+	if (!match) throw new Error(`Invalid --older-than "${value}": expected <number>d or <number>h (e.g. 30d, 12h)`);
+	const num = Number(match[1]);
+	if (!Number.isFinite(num) || num <= 0) throw new Error(`Invalid --older-than "${value}": must be greater than zero`);
+	const multiplier = match[2] === "d" ? 1440 * 60 * 1e3 : 3600 * 1e3;
+	return Math.round(num * multiplier);
+}
+/** Escape a literal string for embedding in a RegExp. */
+function escapeRegExp(value) {
+	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+* Characters that terminate an S3 key extracted from a URL-shaped string.
+* Whitespace / quotes never appear in cdkd's content-addressed asset keys
+* (`<sha256>.zip` etc.); `?` strips query strings (pre-signed URLs).
+*/
+const KEY_TERMINATORS = "[^\\s\"'?]";
+/**
+* cdkd's publishers write content-addressed keys (`<sha256>.<ext>`). A
+* second, name-independent pass collects every such token from every
+* scanned string — belt-and-braces against URL captures that ran through
+* an embedded separator (e.g. two `s3://` URIs joined by a comma yield ONE
+* over-long capture, leaving both real keys unprotected). Over-collection
+* only ever KEEPS more.
+*/
+const CONTENT_HASH_KEY_RE = /\b[0-9a-f]{64}\.[A-Za-z0-9]+\b/g;
+/**
+* Try to decode a base64-looking string (e.g. `Fn::Base64`-resolved EC2 /
+* ASG UserData stored in state) so references INSIDE it are collected too —
+* an `aws s3 cp s3://<assetBucket>/<key>` in UserData is a long-lived
+* reference (every future scale-out fetches it at boot). Returns null for
+* strings that are not plausibly base64-encoded text; a binary decode is
+* rejected by the control-character check. Hex strings (valid base64
+* alphabet) decode to binary and are rejected the same way.
+*/
+function tryDecodeBase64Text(value) {
+	if (value.length < 24 || value.length % 4 !== 0) return null;
+	if (!/^[A-Za-z0-9+/]+={0,2}$/.test(value)) return null;
+	try {
+		const decoded = Buffer.from(value, "base64").toString("utf8");
+		if (/[\x00-\x08\x0e-\x1f\ufffd]/.test(decoded)) return null;
+		return decoded;
+	} catch {
+		return null;
+	}
+}
+/**
+* Per-(bucket, repo) reference extractors. Built once per run.
+*
+* Matched shapes (all carry the bucket / repo name verbatim):
+* - (bucket, key) location OBJECTS — any object carrying the asset bucket
+*   name as a value (`{S3Bucket, S3Key}` Lambda Code, `{Bucket, Key}`
+*   ApiGateway BodyS3Location / SFN DefinitionS3Location, ...) — handled
+*   in the walk itself; every sibling string value is collected.
+* - `s3://<assetBucket>/<key>` URIs.
+* - `https://<assetBucket>.s3[.<region>].amazonaws.com/<key>`
+*   (virtual-hosted style, region / dualstack variants included).
+* - `https://s3[.<region>].amazonaws.com/<assetBucket>/<key>` (path style).
+* - `<acct>.dkr.ecr.<region>.amazonaws.com/<containerRepo>:<tag>` and/or
+*   `...@sha256:<digest>` image URIs. Account / region are matched
+*   loosely on purpose: collecting a reference from another account's or
+*   region's URI can only over-protect (keep more), never delete more.
+*/
+function buildReferenceExtractors(marker) {
+	const bucket = escapeRegExp(marker.assetBucket);
+	const repo = escapeRegExp(marker.containerRepo);
+	const s3UriRe = new RegExp(`s3://${bucket}/(${KEY_TERMINATORS}+)`, "g");
+	const virtualHostedRe = new RegExp(`https://${bucket}\\.s3[^/\\s]*\\.amazonaws\\.com/(${KEY_TERMINATORS}+)`, "g");
+	const pathStyleRe = new RegExp(`https://s3[^/\\s]*\\.amazonaws\\.com/${bucket}/(${KEY_TERMINATORS}+)`, "g");
+	const ecrRe = new RegExp(`\\d{12}\\.dkr\\.ecr\\.[a-z0-9-]+\\.amazonaws\\.com/${repo}(?::([A-Za-z0-9_][A-Za-z0-9._-]{0,127}))?(?:@(sha256:[0-9a-f]{64}))?`, "g");
+	const extractOnce = (value, refs) => {
+		for (const re of [
+			s3UriRe,
+			virtualHostedRe,
+			pathStyleRe
+		]) for (const match of value.matchAll(re)) if (match[1]) refs.s3Keys.add(match[1]);
+		for (const match of value.matchAll(ecrRe)) {
+			if (match[1]) refs.imageTags.add(match[1]);
+			if (match[2]) refs.imageDigests.add(match[2]);
+		}
+		for (const match of value.matchAll(CONTENT_HASH_KEY_RE)) refs.s3Keys.add(match[0]);
+	};
+	return { extractFromString(value, refs) {
+		extractOnce(value, refs);
+		const decoded = tryDecodeBase64Text(value);
+		if (decoded !== null) extractOnce(decoded, refs);
+	} };
+}
+/**
+* Deep-walk a parsed state file and collect every reference to the target
+* region's asset bucket / container repo into `refs`.
+*
+* The walk covers the ENTIRE state document — a superset of the spec'd
+* `properties` / `observedProperties` / `attributes` / `outputs` fields —
+* because over-collection can only KEEP more (safe direction) and a future
+* state field carrying an asset reference is then protected automatically.
+* Unexpected value types are walked defensively (arrays / objects
+* recursed, non-strings ignored).
+*/
+function collectAssetReferences(stateDocument, marker, refs) {
+	const { extractFromString } = buildReferenceExtractors(marker);
+	const walk = (value) => {
+		if (typeof value === "string") {
+			extractFromString(value, refs);
+			return;
+		}
+		if (Array.isArray(value)) {
+			for (const item of value) walk(item);
+			return;
+		}
+		if (value !== null && typeof value === "object") {
+			const values = Object.values(value);
+			if (values.some((v) => v === marker.assetBucket)) {
+				for (const v of values) if (typeof v === "string" && v !== marker.assetBucket) refs.s3Keys.add(v);
+			}
+			for (const item of values) walk(item);
+		}
+	};
+	walk(stateDocument);
+}
+/**
+* Scan every state file in the state bucket and collect the referenced
+* asset keys / image tags / digests for the marker's bucket + repo.
+*
+* Fail safe: a state file that fails to JSON-parse aborts the whole run —
+* a reference we could not read is a reference we would otherwise delete.
+* A state key that disappeared between the listing and the read (destroy
+* completed concurrently) is skipped: its references are legitimately gone.
+*/
+async function scanReferencedAssets(stateBackend, marker, logger) {
+	const refs = {
+		s3Keys: /* @__PURE__ */ new Set(),
+		imageTags: /* @__PURE__ */ new Set(),
+		imageDigests: /* @__PURE__ */ new Set()
+	};
+	const stateKeys = await listAllStateKeys(stateBackend);
+	logger.info(`Scanning ${stateKeys.length} state file(s) for asset references...`);
+	for (const key of stateKeys) {
+		const body = await stateBackend.getRawObject(key);
+		if (body === null) {
+			logger.debug(`State file ${key} disappeared during the scan — skipping`);
+			continue;
+		}
+		let parsed;
+		try {
+			parsed = JSON.parse(body);
+		} catch (error) {
+			const described = describeStateKey(key);
+			const regionMatch = /^(\S+) \((\S+)\)$/.exec(described);
+			throw new CdkdError(`State file '${key}' is not valid JSON — aborting: gc must know every referenced asset before deleting anything, and this file's references are unreadable. Repair or remove the corrupt state file ('${regionMatch ? `cdkd state show ${regionMatch[1]} --stack-region ${regionMatch[2]}` : `cdkd state show ${described}`}' to inspect), then re-run.`, "GC_STATE_UNREADABLE", error);
+		}
+		collectAssetReferences(parsed, marker, refs);
+	}
+	logger.debug(`Referenced: ${refs.s3Keys.size} S3 key(s), ${refs.imageTags.size} image tag(s), ${refs.imageDigests.size} image digest(s)`);
+	return refs;
+}
+/**
+* List the asset bucket (paginated, `ExpectedBucketOwner`) and pick the
+* deletion candidates: keys NOT referenced AND strictly older than the
+* cutoff. Objects with no `LastModified` are kept (treated as new).
+*
+* A missing bucket is an idempotent skip (nothing to gc there); a 403 is
+* a foreign-bucket refusal, mirroring the create / teardown sides.
+*/
+async function listS3Candidates(s3Client, bucket, accountId, refs, cutoffMs, logger) {
+	const candidates = [];
+	let continuationToken;
+	try {
+		do {
+			const response = await s3Client.send(new ListObjectsV2Command({
+				Bucket: bucket,
+				ExpectedBucketOwner: accountId,
+				...continuationToken && { ContinuationToken: continuationToken }
+			}));
+			for (const obj of response.Contents ?? []) {
+				if (!obj.Key) continue;
+				if (refs.s3Keys.has(obj.Key)) continue;
+				if (!obj.LastModified || obj.LastModified.getTime() >= cutoffMs) continue;
+				candidates.push({
+					key: obj.Key,
+					size: obj.Size ?? 0,
+					lastModified: obj.LastModified
+				});
+			}
+			continuationToken = response.IsTruncated ? response.NextContinuationToken : void 0;
+		} while (continuationToken);
+	} catch (error) {
+		const err = error;
+		if (err.name === "NoSuchBucket" || err.name === "NotFound") {
+			logger.info(`Asset bucket ${bucket} does not exist — skipping`);
+			return [];
+		}
+		if (err.$metadata?.httpStatusCode === 403) throw new CdkdError(`Asset bucket '${bucket}' exists but is not owned by account ${accountId} (or access is denied). Refusing to touch it.`, "ASSET_STORAGE_FOREIGN_BUCKET", error);
+		throw normalizeAwsError(error, {
+			bucket,
+			operation: "ListObjectsV2"
+		});
+	}
+	return candidates;
+}
+/**
+* Describe the container repo's images (paginated) and pick the deletion
+* candidates: an image is REFERENCED when any of its tags OR its digest is
+* in the referenced set; candidates are unreferenced AND strictly older
+* than the cutoff. Images with no `imagePushedAt` are kept (treated as
+* new). A missing repo is an idempotent skip.
+*/
+async function listEcrCandidates(ecrClient, repositoryName, refs, cutoffMs, logger) {
+	const candidates = [];
+	let nextToken;
+	try {
+		do {
+			const response = await ecrClient.send(new DescribeImagesCommand$1({
+				repositoryName,
+				...nextToken && { nextToken }
+			}));
+			for (const image of response.imageDetails ?? []) {
+				if (!image.imageDigest) continue;
+				const tags = image.imageTags ?? [];
+				if (refs.imageDigests.has(image.imageDigest) || tags.some((t) => refs.imageTags.has(t))) continue;
+				if (!image.imagePushedAt || image.imagePushedAt.getTime() >= cutoffMs) continue;
+				candidates.push({
+					digest: image.imageDigest,
+					tags,
+					size: image.imageSizeInBytes ?? 0,
+					pushedAt: image.imagePushedAt
+				});
+			}
+			nextToken = response.nextToken;
+		} while (nextToken);
+	} catch (error) {
+		if (error.name === "RepositoryNotFoundException") {
+			logger.info(`Container-asset repository ${repositoryName} does not exist — skipping`);
+			return [];
+		}
+		throw normalizeAwsError(error, { operation: "DescribeImages" });
+	}
+	return candidates;
+}
+/** `12345678` → `11.8 MiB` — human-readable byte count for the plan. */
+function formatBytes(bytes) {
+	if (bytes < 1024) return `${bytes} B`;
+	const units = [
+		"KiB",
+		"MiB",
+		"GiB",
+		"TiB"
+	];
+	let value = bytes;
+	let unit = "B";
+	for (const u of units) {
+		if (value < 1024) break;
+		value /= 1024;
+		unit = u;
+	}
+	return `${value.toFixed(1)} ${unit}`;
+}
+/** Age of a timestamp relative to now, in whole days (or hours under 1d). */
+function formatAge(date) {
+	const ageMs = Date.now() - date.getTime();
+	const days = Math.floor(ageMs / (1440 * 60 * 1e3));
+	if (days >= 1) return `${days}d old`;
+	return `${Math.max(0, Math.floor(ageMs / (3600 * 1e3)))}h old`;
+}
+/**
+* Interactive confirmation for the deletion. Follows the repo's
+* destructive-prompt convention (same pattern family as
+* `promptBootstrapDestroyConfirm`): print the plan as a WARN block,
+* `--yes` skips, a non-TTY stdin without `--yes` is a hard error (never
+* hang / never silently decline in CI), and the prompt defaults to NO.
+*/
+async function promptGcConfirm(input) {
+	const logger = getLogger();
+	logger.warn("");
+	logger.warn("cdkd gc will delete the following unreferenced assets:");
+	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");
+	const rl = readline.createInterface({
+		input: process.stdin,
+		output: process.stdout
+	});
+	try {
+		const trimmed = (await rl.question("\nContinue? (y/N): ")).trim().toLowerCase();
+		return trimmed === "y" || trimmed === "yes";
+	} finally {
+		rl.close();
+	}
+}
+/**
+* Delete the S3 candidates via chunked `DeleteObjects` (1,000 keys per
+* call, `ExpectedBucketOwner`). Per-key `Errors` are surfaced as a hard
+* error so gc never reports success while objects remain.
+*/
+async function deleteS3Candidates(s3Client, bucket, accountId, candidates) {
+	const failures = [];
+	for (let i = 0; i < candidates.length; i += S3_DELETE_BATCH_SIZE) {
+		const chunk = candidates.slice(i, i + S3_DELETE_BATCH_SIZE);
+		const response = await s3Client.send(new DeleteObjectsCommand({
+			Bucket: bucket,
+			ExpectedBucketOwner: accountId,
+			Delete: {
+				Objects: chunk.map((c) => ({ Key: c.key })),
+				Quiet: true
+			}
+		}));
+		for (const err of response.Errors ?? []) failures.push(`${err.Key ?? "<unknown>"} (${err.Code ?? "Error"}: ${err.Message ?? ""})`);
+	}
+	if (failures.length > 0) throw new CdkdError(`Failed to delete ${failures.length} object(s) from asset bucket '${bucket}': ` + failures.join("; "), "GC_DELETE_FAILED");
+}
+/**
+* Delete the ECR candidates via chunked `BatchDeleteImage` (100 image ids
+* per call), addressed by digest so every tag of the image goes with it.
+* Per-image `failures` are surfaced as a hard error.
+*/
+async function deleteEcrCandidates(ecrClient, repositoryName, candidates) {
+	const failures = [];
+	for (let i = 0; i < candidates.length; i += ECR_DELETE_BATCH_SIZE) {
+		const chunk = candidates.slice(i, i + ECR_DELETE_BATCH_SIZE);
+		const response = await ecrClient.send(new BatchDeleteImageCommand({
+			repositoryName,
+			imageIds: chunk.map((c) => ({ imageDigest: c.digest }))
+		}));
+		for (const failure of response.failures ?? []) failures.push(`${failure.imageId?.imageDigest ?? "<unknown>"} (${failure.failureCode ?? "Error"}: ${failure.failureReason ?? ""})`);
+	}
+	if (failures.length > 0) throw new CdkdError(`Failed to delete ${failures.length} image(s) from repository '${repositoryName}': ` + failures.join("; "), "GC_DELETE_FAILED");
+}
+/**
+* `cdkd gc` implementation. See the module JSDoc for the safety posture.
+*/
+async function gcCommand(options) {
+	const logger = getLogger();
+	if (options.verbose) logger.setLevel("debug");
+	logger.info("Starting cdkd gc...");
+	logger.debug("Options:", options);
+	await applyRoleArnIfSet({
+		roleArn: options.roleArn,
+		region: options.region
+	});
+	const region = options.region || process.env["AWS_REGION"] || "us-east-1";
+	const awsClients = new AwsClients({
+		region,
+		...options.profile && { profile: options.profile }
+	});
+	setAwsClients(awsClients);
+	const accountId = (await awsClients.sts.send(new GetCallerIdentityCommand({}))).Account;
+	const bucketName = options.stateBucket ?? getDefaultStateBucketName(accountId);
+	const markerS3Client = new S3Client({
+		region,
+		...options.profile && { profile: options.profile }
+	});
+	const stateBackend = new S3StateBackend(markerS3Client, {
+		bucket: bucketName,
+		prefix: "cdkd"
+	}, {
+		region,
+		...options.profile && { profile: options.profile }
+	});
+	const ecrClient = new ECRClient({
+		region,
+		...options.profile && { profile: options.profile }
+	});
+	try {
+		const markerKey = getBootstrapMarkerKey(region);
+		let markerBody;
+		try {
+			markerBody = await stateBackend.getRawObject(markerKey);
+		} catch (error) {
+			if (error.name === "NoSuchBucket") {
+				logger.info(`State bucket '${bucketName}' does not exist — this account was never bootstrapped; nothing to garbage-collect.`);
+				return;
+			}
+			throw error;
+		}
+		if (markerBody === null) {
+			logger.info(`No bootstrap marker for region '${region}' (${markerKey}) — the region is not opted in to cdkd asset storage; nothing to garbage-collect. (CDK bootstrap storage is 'cdk gc' territory.)`);
+			return;
+		}
+		const marker = parseBootstrapMarker(markerBody, markerKey);
+		const lockKeys = await listAllLockKeys(stateBackend);
+		if (lockKeys.length > 0) {
+			const listing = lockKeys.map((k) => `  - ${describeStateKey(k, LOCK_FILE_SUFFIX)}  [${k}]`).join("\n");
+			throw new CdkdError(`Refusing to gc while ${lockKeys.length} stack(s) hold an active lock (a deploy in flight may have published assets whose state write has not landed yet):\n${listing}\nWait for the operation(s) to finish — or clear a stale lock with 'cdkd force-unlock <stack>' — then re-run 'cdkd gc'.`, "GC_LOCKED");
+		}
+		const refs = await scanReferencedAssets(stateBackend, marker, logger);
+		const cutoffMs = Date.now() - options.olderThan;
+		const s3Candidates = await listS3Candidates(awsClients.s3, marker.assetBucket, accountId, refs, cutoffMs, logger);
+		const ecrCandidates = await listEcrCandidates(ecrClient, marker.containerRepo, refs, cutoffMs, logger);
+		if (s3Candidates.length === 0 && ecrCandidates.length === 0) {
+			logger.info(`Nothing to garbage-collect in region '${region}': every object in ${marker.assetBucket} / image in ${marker.containerRepo} is either referenced by a deployed stack or newer than the --older-than cutoff.`);
+			return;
+		}
+		const s3Bytes = s3Candidates.reduce((sum, c) => sum + c.size, 0);
+		const ecrBytes = ecrCandidates.reduce((sum, c) => sum + c.size, 0);
+		const planLines = [...s3Candidates.map((c) => `s3://${marker.assetBucket}/${c.key} (${formatBytes(c.size)}, ${formatAge(c.lastModified)})`), ...ecrCandidates.map((c) => `${marker.containerRepo}${c.tags.length > 0 ? `:${c.tags.join(",")}` : ""}@${c.digest} (${formatBytes(c.size)}, ${formatAge(c.pushedAt)})`)];
+		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:");
+			for (const line of planLines) logger.info(`  - ${line}`);
+			logger.info(totals);
+			logger.info("Dry run: nothing deleted. Re-run without --dry-run to delete.");
+			return;
+		}
+		if (!await promptGcConfirm({
+			planLines: [...planLines, totals],
+			yes: options.yes
+		})) {
+			logger.info("gc cancelled — nothing deleted.");
+			return;
+		}
+		if (s3Candidates.length > 0) {
+			await deleteS3Candidates(awsClients.s3, marker.assetBucket, accountId, s3Candidates);
+			logger.info(`✓ Deleted ${s3Candidates.length} object(s) (${formatBytes(s3Bytes)}) from ${marker.assetBucket}`);
+		}
+		if (ecrCandidates.length > 0) {
+			await deleteEcrCandidates(ecrClient, marker.containerRepo, ecrCandidates);
+			logger.info(`✓ Deleted ${ecrCandidates.length} image(s) (${formatBytes(ecrBytes)}) from ${marker.containerRepo}`);
+		}
+		logger.info(`\n✓ gc completed: ${formatBytes(s3Bytes + ecrBytes)} reclaimed`);
+	} finally {
+		ecrClient.destroy();
+		markerS3Client.destroy();
+		awsClients.destroy();
+	}
+}
+/**
+* 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) => {
+		await gcCommand(options);
+	}));
+	commonOptions.forEach((opt) => cmd.addOption(opt));
+	return cmd;
+}
+
 //#endregion
 //#region src/cli/cdk-path.ts
 /**
@@ -56378,6 +56891,7 @@ const SUBCOMMANDS = new Set([
 	"diff",
 	"drift",
 	"destroy",
+	"gc",
 	"orphan",
 	"import",
 	"export",
@@ -56410,7 +56924,7 @@ function reorderArgs(argv) {
 async function main() {
 	installPipeCloseHandler();
 	const program = new Command();
-	program.name("cdkd").description("CDK Direct - Deploy AWS CDK apps directly via SDK/Cloud Control API").version("0.237.0");
+	program.name("cdkd").description("CDK Direct - Deploy AWS CDK apps directly via SDK/Cloud Control API").version("0.238.0");
 	program.addCommand(createBootstrapCommand());
 	program.addCommand(createSynthCommand());
 	program.addCommand(createListCommand());
@@ -56419,6 +56933,7 @@ async function main() {
 	program.addCommand(createDriftCommand());
 	program.addCommand(createDestroyCommand());
 	program.addCommand(createEventsCommand());
+	program.addCommand(createGcCommand());
 	program.addCommand(createOrphanCommand());
 	program.addCommand(createImportCommand());
 	program.addCommand(createPublishAssetsCommand());