@go-to-k/cdkd 0.231.11 → 0.232.0

package/README.md

@@ -14,6 +14,8 @@ Drop-in CDK CLI for existing CDK apps — faster deploys via AWS SDK instead of
 
 **cdkd complements the AWS CDK CLI rather than replacing it.** Use cdkd in dev/test for rapid iteration and SAM-style local execution; use the AWS CDK CLI in production for full CloudFormation tooling. Install cdkd alongside an existing `cdk deploy` workflow — no migration needed, `cdkd local *` reads deployed state directly via `--from-cfn-stack`. Bidirectional migration is also supported — [import](#importing-existing-resources) into cdkd or [export](#exporting-a-stack-back-to-cloudformation) back to CloudFormation when ready.
 
+**A natural fit for AI-driven development.** AI coding agents iterate in tight spin-up / tear-down loops — and cdkd keeps each turn short, with fast deploys and an equally fast `cdkd destroy` that deletes via direct SDK calls instead of polling a CloudFormation stack-delete.
+
 > [!IMPORTANT]
 > cdkd is for dev/test workflows only — early in development, not yet production-ready.
 
@@ -109,10 +111,16 @@ Reproduce the first two with `./tests/benchmark/run-benchmark.sh all`. See [test
          │
          ▼
 ┌─────────────────┐
+│ Asset Build &   │  S3 ZIP upload / ECR image build & push
+│   Publish       │
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
 │ cdkd Engine     │
 │ - DAG Analysis  │  Dependency graph construction
 │ - Diff Calc     │  Compare with existing resources
-│ - Parallel Exec │  Event-driven dispatch
+│ - Parallel Exec │  Dispatch on deps complete (no level barrier)
 └────────┬────────┘
          │
     ┌────┴────┐
@@ -131,7 +139,7 @@ parsing → synthesis → asset publishing → per-stack deploy), see
 ## Prerequisites
 
 - **Node.js** >= 20.0.0
-- **AWS CDK Bootstrap**: You must run `cdk bootstrap` before using cdkd. cdkd uses CDK's bootstrap bucket (`cdk-hnb659fds-assets-*`) for asset uploads (Lambda code, Docker images). Custom bootstrap qualifiers are supported — CDK embeds the correct bucket/repo names in the asset manifest during synthesis.
+- **AWS CDK Bootstrap**: You must run `cdk bootstrap` before using cdkd. cdkd uses CDK's bootstrap bucket (`cdk-hnb659fds-assets-*`) for asset uploads (Lambda code, Docker images). Custom bootstrap qualifiers are supported — CDK embeds the correct bucket/repo names in the asset manifest during synthesis. Note: `cdk gc` cannot see cdkd-deployed stacks (no CloudFormation stack to scan) and may garbage-collect cdkd-published assets from the CDK bootstrap storage — `cdkd bootstrap` therefore also creates cdkd-owned asset storage that asset publishing is moving onto (issue [#1002](https://github.com/go-to-k/cdkd/issues/1002); design in [docs/design/1002-cdkd-asset-storage.md](docs/design/1002-cdkd-asset-storage.md); the publish redirection ships in a follow-up release).
 - **AWS credentials with admin-equivalent permissions** for the resources being deployed. cdkd does NOT route through CloudFormation, so CDK CLI's `cdk-hnb659fds-deploy-role-*` is NOT sufficient — see [`--role-arn`](docs/cli-reference.md).
 
 ## Installation
@@ -148,12 +156,16 @@ The installed binary is `cdkd`.
 > **First-time setup**: cdkd requires a one-time `cdkd bootstrap` per AWS
 > account before any other command will work — it creates the S3 state
 > bucket (`cdkd-state-{accountId}`) that cdkd uses to track deployed
-> resources. This is separate from `cdk bootstrap` (which sets up the
+> resources, plus cdkd-owned asset storage for the region
+> (`cdkd-assets-{accountId}-{region}` bucket +
+> `cdkd-container-assets-{accountId}-{region}` ECR repo — skip with
+> `--no-assets`; see [`cdkd bootstrap`](docs/cli-reference.md#cdkd-bootstrap)).
+> This is separate from `cdk bootstrap` (which sets up the
 > CDK asset bucket / ECR repo and is also required — see
 > [Prerequisites](#prerequisites)).
 
 ```bash
-# Bootstrap (creates S3 state bucket — one-time setup, once per AWS account)
+# Bootstrap (creates S3 state bucket + asset storage — one-time setup per AWS account)
 cdkd bootstrap
 
 # List stacks in the CDK app

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { A as withErrorHandling, B as generateResourceName, C as StackHasActiveImportsError, F as getLiveRenderer, H as withSkipPrefix, I as PATTERN_B_NAME_OPTIONS, L as PATTERN_B_NAME_PROPERTIES, M as getLogger, P as runStackBuffered, R as PATTERN_B_RESOURCE_TYPES, S as ResourceUpdateNotSupportedError, U as withStackName, V as generateResourceNameWithFallback, _ as MissingCdkCliError, a as normalizeAwsTagsToCfn, b as ProvisioningError, f as LocalInvokeBuildError$1, i as matchesCdkPath, k as normalizeAwsError, l as CdkdError, m as LocalStartServiceError, n as isTerminationProtectionPropagationError, o as resolveExplicitPhysicalId, p as LocalMigrateError, r as CDK_PATH_TAG, s as assertRegionMatch, t as disableInstanceApiTermination, v as NestedStackChildDirectDestroyError, w as StackTerminationProtectionError, x as ResourceTimeoutError, y as PartialFailureError } from "./ec2-termination-protection-uvVnteGl.js";
 import { a as setAwsClients, i as resetAwsClients, r as getAwsClients, t as AwsClients } from "./aws-clients-pjPwZz1r.js";
-import { $ as resolveSkipPrefix, A as DiffCalculator, B as buildDockerImage, C as findActionableSilentDrops, D as refStateLookupFromResource, E as cfnRefValueFromPhysicalId, F as rebuildClientForBucketRegion, G as AssetManifestLoader, H as getDockerCmd, I as shouldRetainResource, J as synthesisStatusMessage, K as getDockerImageBySourceHash, L as AssetPublisher, M as TemplateParser, N as LockManager, O as WAFv2WebACLProvider, P as S3StateBackend, Q as resolveCaptureObservedState, R as stringifyValue, S as ProviderRegistry, T as IntrinsicFunctionResolver, U as runDockerForeground, V as formatDockerLoginError, W as runDockerStreaming, X as getLegacyStateBucketName, Y as getDefaultStateBucketName, Z as resolveApp, _ as green, a as withRetry, at as MIGRATE_TMP_PREFIX, b as IAMRoleProvider, c as computeImplicitDeleteEdges, ct as AssemblyReader, d as isStatefulRecreateTargetSync, et as resolveStateBucketWithDefault, f as renderStatefulReason, g as gray, h as cyan, i as withResourceDeadline, it as CFN_TEMPLATE_URL_LIMIT, j as DagBuilder, k as applyRoleArnIfSet, l as extractDeploymentEventError, m as bold, n as DEFAULT_RESOURCE_WARN_AFTER_MS, nt as warnDeprecatedNoPrefixCliFlag, o as isRetryableTransientError, ot as findLargeInlineResources, p as formatResourceLine, q as Synthesizer, r as DeployEngine, rt as CFN_TEMPLATE_BODY_LIMIT, s as IMPLICIT_DELETE_DEPENDENCIES, st as uploadCfnTemplate, t as DEFAULT_RESOURCE_TIMEOUT_MS, tt as resolveStateBucketWithDefaultAndSource, u as MULTI_REGION_RECREATE_BLOCKED_TYPES, ut as resolveBucketRegion, v as red, w as CloudControlProvider, x as collectInlinePolicyNamesManagedBySiblings, y as yellow, z as WorkGraph } from "./deploy-engine-CINi8mJy.js";
+import { $ as resolveSkipPrefix, A as DiffCalculator, B as buildDockerImage, C as findActionableSilentDrops, D as refStateLookupFromResource, E as cfnRefValueFromPhysicalId, F as rebuildClientForBucketRegion, G as AssetManifestLoader, H as getDockerCmd, I as shouldRetainResource, J as synthesisStatusMessage, K as getDockerImageBySourceHash, L as AssetPublisher, M as TemplateParser, N as LockManager, O as WAFv2WebACLProvider, P as S3StateBackend, Q as resolveCaptureObservedState, R as stringifyValue, S as ProviderRegistry, T as IntrinsicFunctionResolver, U as runDockerForeground, V as formatDockerLoginError, W as runDockerStreaming, X as getLegacyStateBucketName, Y as getDefaultStateBucketName, Z as resolveApp, _ as green, a as withRetry, at as MIGRATE_TMP_PREFIX, b as IAMRoleProvider, c as computeImplicitDeleteEdges, ct as AssemblyReader, d as isStatefulRecreateTargetSync, et as resolveStateBucketWithDefault, f as renderStatefulReason, g as gray, h as cyan, i as withResourceDeadline, it as CFN_TEMPLATE_URL_LIMIT, j as DagBuilder, k as applyRoleArnIfSet, l as extractDeploymentEventError, m as bold, n as DEFAULT_RESOURCE_WARN_AFTER_MS, nt as warnDeprecatedNoPrefixCliFlag, o as isRetryableTransientError, ot as findLargeInlineResources, p as formatResourceLine, q as Synthesizer, r as DeployEngine, rt as CFN_TEMPLATE_BODY_LIMIT, s as IMPLICIT_DELETE_DEPENDENCIES, st as uploadCfnTemplate, t as DEFAULT_RESOURCE_TIMEOUT_MS, tt as resolveStateBucketWithDefaultAndSource, u as MULTI_REGION_RECREATE_BLOCKED_TYPES, ut as resolveBucketRegion, v as red, w as CloudControlProvider, x as collectInlinePolicyNamesManagedBySiblings, y as yellow, z as WorkGraph } from "./deploy-engine-BkPZar1R.js";
 import { t as ASGProvider } from "./asg-provider-Dd9Xze-T.js";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { createHash, randomBytes, randomUUID } from "node:crypto";
@@ -598,12 +598,320 @@ const destroyOptions = [
 	allowUnsupportedTypesOption
 ];
 
+//#endregion
+//#region src/assets/asset-storage.ts
+/**
+* cdkd-owned asset storage — naming, bootstrap marker, and deploy-time
+* asset-mode detection (issue #1002, design at
+* docs/design/1002-cdkd-asset-storage.md).
+*
+* Why this exists: cdkd publishes assets to the CDK bootstrap bucket / ECR
+* repo, but `cdk gc` decides "in use" by scanning CloudFormation stack
+* templates — cdkd-deployed stacks have no CFn stack, so every cdkd-published
+* asset looks isolated and gets deleted. The fix is cdkd-owned asset storage
+* created by `cdkd bootstrap` (structurally out of `cdk gc`'s reach because
+* gc only discovers storage from the CDK bootstrap stack's outputs).
+*
+* The upgrade is strictly transparent: deploys behave byte-identically to
+* before until the user re-runs `cdkd bootstrap` for a region, which writes a
+* per-region marker object into the state bucket. Deploy reads the marker to
+* pick the mode; PR 2 of the phasing wires the actual publish redirection +
+* template rewrite onto the `cdkd-assets` mode resolved here.
+*/
+/** Marker schema version, bumped if the marker shape ever changes. */
+const ASSET_SUPPORT_VERSION = 1;
+/**
+* S3 key prefix for bootstrap markers in the state bucket. Deliberately
+* outside the `cdkd/` state prefix so `state list` key-listing never mistakes
+* a marker for a stack, and concurrent bootstraps in two regions cannot race
+* last-writer-wins on a shared object (design §12.1).
+*/
+const BOOTSTRAP_MARKER_PREFIX = "cdkd-bootstrap/";
+/**
+* Name of the cdkd-owned asset bucket for an (account, region) pair.
+* Per-region because Lambda requires the code bucket to be in the function's
+* region — the same reason CDK's asset bucket is per-region (design §3).
+*/
+function getCdkdAssetBucketName(accountId, region) {
+	return `cdkd-assets-${accountId}-${region}`;
+}
+/**
+* Name of the cdkd-owned container-asset ECR repository for an
+* (account, region) pair. ECR repos are account+region scoped by ARN, so the
+* suffix is not strictly needed — the CDK-parallel shape keeps the future
+* template rewrite uniform and the names self-describing (design §3).
+*/
+function getCdkdContainerRepoName(accountId, region) {
+	return `cdkd-container-assets-${accountId}-${region}`;
+}
+/**
+* State-bucket key of the bootstrap marker for a region.
+*/
+function getBootstrapMarkerKey(region) {
+	return `${BOOTSTRAP_MARKER_PREFIX}${region}.json`;
+}
+/**
+* Parse and validate a bootstrap marker body.
+*
+* Throws on malformed JSON or missing required fields — a corrupt marker is
+* treated like the marker-present-but-resources-missing case (hard error,
+* never a silent legacy fallback that would flip-flop stack properties
+* between deploys — design §4.1).
+*/
+function parseBootstrapMarker(body, markerKey) {
+	let parsed;
+	try {
+		parsed = JSON.parse(body);
+	} catch (error) {
+		throw new CdkdError(`Bootstrap marker '${markerKey}' in the state bucket is not valid JSON. Re-run 'cdkd bootstrap' for this region to rewrite it.`, "INVALID_BOOTSTRAP_MARKER", error);
+	}
+	const marker = parsed;
+	if (typeof marker.assetBucket !== "string" || marker.assetBucket.length === 0 || typeof marker.containerRepo !== "string" || marker.containerRepo.length === 0 || typeof marker.assetSupportVersion !== "number") throw new CdkdError(`Bootstrap marker '${markerKey}' in the state bucket is malformed (missing assetBucket / containerRepo / assetSupportVersion). Re-run 'cdkd bootstrap' for this region to rewrite it.`, "INVALID_BOOTSTRAP_MARKER");
+	if (marker.assetSupportVersion > 1) throw new CdkdError(`Bootstrap marker '${markerKey}' has assetSupportVersion ${marker.assetSupportVersion}, but this cdkd only understands up to ${1}. Upgrade cdkd to deploy in this region.`, "UNSUPPORTED_BOOTSTRAP_MARKER_VERSION");
+	return {
+		assetBucket: marker.assetBucket,
+		containerRepo: marker.containerRepo,
+		assetSupportVersion: marker.assetSupportVersion,
+		createdAt: typeof marker.createdAt === "string" ? marker.createdAt : ""
+	};
+}
+/**
+* Verify that the asset bucket + ECR repo named by a marker actually exist.
+*
+* Called when a marker is present: the user opted the region in, so missing
+* resources (user deleted them) are a hard error naming the missing resource
+* and the `cdkd bootstrap` fix — never a silent fallback to CDK bootstrap
+* storage (design §4.1).
+*
+* Every S3 call passes `ExpectedBucketOwner` so a marker pointing at a
+* since-recreated foreign bucket can never leak assets cross-account
+* (bucket-squatting defense, design §5).
+*/
+async function verifyAssetStorageExists(marker, accountId, region, opts = {}) {
+	const rebootstrapHint = `Run 'cdkd bootstrap --region ${region}' to recreate it. cdkd never silently falls back to CDK bootstrap asset storage once a region is opted in.`;
+	const clientOpts = {
+		region,
+		...opts.profile && { profile: opts.profile }
+	};
+	const s3Client = new S3Client(clientOpts);
+	const ecrClient = new ECRClient(clientOpts);
+	try {
+		try {
+			await s3Client.send(new HeadBucketCommand({
+				Bucket: marker.assetBucket,
+				ExpectedBucketOwner: accountId
+			}));
+		} catch (error) {
+			const err = error;
+			if (err.name === "NotFound" || err.name === "NoSuchBucket") throw new CdkdError(`cdkd asset storage is bootstrapped for region '${region}' but the asset bucket '${marker.assetBucket}' is missing. ${rebootstrapHint}`, "ASSET_STORAGE_MISSING");
+			if (err.$metadata?.httpStatusCode === 403) throw new CdkdError(`Asset bucket '${marker.assetBucket}' exists but is not owned by account ${accountId} (or access is denied). Refusing to use it. ${rebootstrapHint}`, "ASSET_STORAGE_FOREIGN_BUCKET", error);
+			throw error;
+		}
+		try {
+			await ecrClient.send(new DescribeRepositoriesCommand({ repositoryNames: [marker.containerRepo] }));
+		} catch (error) {
+			if (error.name === "RepositoryNotFoundException") throw new CdkdError(`cdkd asset storage is bootstrapped for region '${region}' but the container-asset ECR repository '${marker.containerRepo}' is missing. ${rebootstrapHint}`, "ASSET_STORAGE_MISSING");
+			throw error;
+		}
+	} finally {
+		s3Client.destroy();
+		ecrClient.destroy();
+	}
+}
+/**
+* Create (or adopt, when already owned by this account) the cdkd asset
+* bucket + container-asset ECR repo for a region, then write the bootstrap
+* marker. Called by `cdkd bootstrap` unless `--no-assets` is passed.
+*
+* Idempotent like the state-bucket path: existing resources are left as-is
+* unless `force` re-applies their configuration. The marker is written LAST,
+* only after both resources exist (design §5) — a crash mid-bootstrap leaves
+* no marker, so deploys stay in legacy mode.
+*
+* Bucket-squatting defense: the bucket name is predictable (same weakness as
+* CDK's bootstrap bucket), so this refuses to adopt a bucket this account
+* does not own, and the `HeadBucket` probe passes `ExpectedBucketOwner`.
+*/
+async function ensureAssetStorage(options) {
+	const logger = getLogger();
+	const { s3Client, ecrClient, stateBackend, accountId, region, force } = options;
+	const assetBucket = getCdkdAssetBucketName(accountId, region);
+	const containerRepo = getCdkdContainerRepoName(accountId, region);
+	let bucketExists = false;
+	try {
+		await s3Client.send(new HeadBucketCommand({
+			Bucket: assetBucket,
+			ExpectedBucketOwner: accountId
+		}));
+		bucketExists = true;
+		logger.info(`Asset bucket ${assetBucket} already exists`);
+	} catch (error) {
+		const err = error;
+		if (err.name === "NotFound" || err.name === "NoSuchBucket") {} else if (err.$metadata?.httpStatusCode === 403) throw new CdkdError(`Asset bucket name '${assetBucket}' is already taken by a bucket this account does not own (or access is denied). Refusing to adopt it — resolve the naming conflict before re-running 'cdkd bootstrap'.`, "ASSET_STORAGE_FOREIGN_BUCKET", error);
+		else throw normalizeAwsError(error, {
+			bucket: assetBucket,
+			operation: "HeadBucket"
+		});
+	}
+	if (!bucketExists) {
+		logger.info(`Creating asset bucket: ${assetBucket} in region ${region}`);
+		try {
+			await s3Client.send(new CreateBucketCommand({
+				Bucket: assetBucket,
+				...region !== "us-east-1" && { CreateBucketConfiguration: { LocationConstraint: region } }
+			}));
+			logger.info(`✓ Created asset bucket: ${assetBucket}`);
+		} catch (error) {
+			const err = error;
+			if (err.name === "BucketAlreadyOwnedByYou") logger.info(`Asset bucket ${assetBucket} already exists`);
+			else if (err.name === "BucketAlreadyExists") throw new CdkdError(`Asset bucket name '${assetBucket}' is already taken by another AWS account. Refusing to adopt it — resolve the naming conflict before re-running 'cdkd bootstrap'.`, "ASSET_STORAGE_FOREIGN_BUCKET", error);
+			else throw normalizeAwsError(error, {
+				bucket: assetBucket,
+				operation: "CreateBucket"
+			});
+		}
+	}
+	if (!bucketExists || force) {
+		await s3Client.send(new PutBucketEncryptionCommand({
+			Bucket: assetBucket,
+			ExpectedBucketOwner: accountId,
+			ServerSideEncryptionConfiguration: { Rules: [{
+				ApplyServerSideEncryptionByDefault: { SSEAlgorithm: "AES256" },
+				BucketKeyEnabled: true
+			}] }
+		}));
+		await s3Client.send(new PutPublicAccessBlockCommand({
+			Bucket: assetBucket,
+			ExpectedBucketOwner: accountId,
+			PublicAccessBlockConfiguration: {
+				BlockPublicAcls: true,
+				BlockPublicPolicy: true,
+				IgnorePublicAcls: true,
+				RestrictPublicBuckets: true
+			}
+		}));
+		await s3Client.send(new PutBucketPolicyCommand({
+			Bucket: assetBucket,
+			ExpectedBucketOwner: accountId,
+			Policy: JSON.stringify({
+				Version: "2012-10-17",
+				Statement: [{
+					Sid: "DenyExternalAccess",
+					Effect: "Deny",
+					Principal: "*",
+					Action: "s3:*",
+					Resource: [`arn:aws:s3:::${assetBucket}`, `arn:aws:s3:::${assetBucket}/*`],
+					Condition: { StringNotEquals: { "aws:PrincipalAccount": accountId } }
+				}]
+			})
+		}));
+		logger.info("✓ Configured asset bucket (AES-256 encryption, public access block, deny external access)");
+	}
+	let repoExists = false;
+	try {
+		await ecrClient.send(new DescribeRepositoriesCommand({ repositoryNames: [containerRepo] }));
+		repoExists = true;
+		logger.info(`Container-asset repository ${containerRepo} already exists`);
+	} catch (error) {
+		if (error.name !== "RepositoryNotFoundException") throw error;
+	}
+	if (!repoExists) {
+		logger.info(`Creating container-asset ECR repository: ${containerRepo}`);
+		try {
+			await ecrClient.send(new CreateRepositoryCommand({
+				repositoryName: containerRepo,
+				imageTagMutability: "IMMUTABLE"
+			}));
+			logger.info(`✓ Created container-asset ECR repository: ${containerRepo}`);
+		} catch (error) {
+			if (error.name === "RepositoryAlreadyExistsException") logger.info(`Container-asset repository ${containerRepo} already exists`);
+			else throw error;
+		}
+	} else if (force) {
+		await ecrClient.send(new PutImageTagMutabilityCommand({
+			repositoryName: containerRepo,
+			imageTagMutability: "IMMUTABLE"
+		}));
+		logger.info("✓ Configured container-asset repository (immutable tags)");
+	}
+	const marker = {
+		assetBucket,
+		containerRepo,
+		assetSupportVersion: 1,
+		createdAt: (/* @__PURE__ */ new Date()).toISOString()
+	};
+	await stateBackend.putRawObject(getBootstrapMarkerKey(region), JSON.stringify(marker, null, 2));
+	logger.info(`✓ Wrote bootstrap marker (${getBootstrapMarkerKey(region)})`);
+	return {
+		assetBucket,
+		containerRepo
+	};
+}
+/**
+* Deploy-time asset-mode resolver. One instance per CLI invocation; results
+* are cached per region for the process lifetime (the marker read is one
+* GetObject against a bucket every deploy already reads — design §4.1).
+*
+* In legacy mode, one `logger.info` line per invocation mentions the
+* `cdk gc` hazard and the `cdkd bootstrap` opt-in (info, not warn — existing
+* users are not doing anything wrong; design §12.2).
+*/
+var AssetModeResolver = class {
+	logger = getLogger().child("AssetMode");
+	cache = /* @__PURE__ */ new Map();
+	legacyNoticeShown = false;
+	stateBackend;
+	accountId;
+	profile;
+	constructor(stateBackend, accountId, opts = {}) {
+		this.stateBackend = stateBackend;
+		this.accountId = accountId;
+		this.profile = opts.profile;
+	}
+	/**
+	* Resolve the asset mode for a deploy region. Concurrent callers for the
+	* same region share one in-flight resolution.
+	*/
+	resolve(region) {
+		const cached = this.cache.get(region);
+		if (cached) return cached;
+		const inFlight = this.doResolve(region).catch((error) => {
+			this.cache.delete(region);
+			throw error;
+		});
+		this.cache.set(region, inFlight);
+		return inFlight;
+	}
+	async doResolve(region) {
+		const markerKey = getBootstrapMarkerKey(region);
+		const body = await this.stateBackend.getRawObject(markerKey);
+		if (body === null) {
+			if (!this.legacyNoticeShown) {
+				this.legacyNoticeShown = true;
+				this.logger.info("Assets are published to the CDK bootstrap bucket/repo, which 'cdk gc' may garbage-collect (cdkd-deployed stacks have no CloudFormation stack for gc to scan). Run 'cdkd bootstrap' to create cdkd-owned asset storage that 'cdk gc' never touches.");
+			}
+			return { mode: "legacy" };
+		}
+		const marker = parseBootstrapMarker(body, markerKey);
+		await verifyAssetStorageExists(marker, this.accountId, region, { ...this.profile && { profile: this.profile } });
+		this.logger.debug(`cdkd asset storage active for region '${region}': ${marker.assetBucket} / ${marker.containerRepo}`);
+		return {
+			mode: "cdkd-assets",
+			marker
+		};
+	}
+};
+
 //#endregion
 //#region src/cli/commands/bootstrap.ts
 /**
 * Bootstrap command implementation
 *
-* Creates S3 bucket for state management
+* Creates the S3 bucket for state management and (unless --no-assets) the
+* cdkd-owned asset storage for the region: asset bucket + container-asset
+* ECR repo + the per-region bootstrap marker that flips deploys in this
+* region from legacy (CDK bootstrap destinations) to cdkd-assets mode
+* (issue #1002, design at docs/design/1002-cdkd-asset-storage.md).
 */
 async function bootstrapCommand(options) {
 	const logger = getLogger();
@@ -646,54 +954,96 @@ async function bootstrapCommand(options) {
 				operation: "HeadBucket"
 			});
 		}
-		if (bucketExists) {
-			if (!options.force) {
+		let skipStateBucketConfig = false;
+		if (bucketExists) if (!options.force) {
+			if (!options.assets) {
 				logger.warn(`Bucket ${bucketName} already exists. Use --force to reconfigure (this will not delete existing state)`);
 				return;
 			}
-			logger.info("--force specified, continuing with existing bucket");
-		} else {
+			logger.info(`State bucket ${bucketName} already exists — skipping reconfiguration (use --force to reconfigure)`);
+			skipStateBucketConfig = true;
+		} else logger.info("--force specified, continuing with existing bucket");
+		else {
 			logger.info(`Creating S3 bucket: ${bucketName} in region ${region}`);
 			const createBucketParams = { Bucket: bucketName };
 			if (region !== "us-east-1") createBucketParams.CreateBucketConfiguration = { LocationConstraint: region };
 			await s3Client.send(new CreateBucketCommand(createBucketParams));
 			logger.info(`✓ Created S3 bucket: ${bucketName}`);
 		}
-		logger.debug("Enabling bucket versioning...");
-		await s3Client.send(new PutBucketVersioningCommand({
-			Bucket: bucketName,
-			VersioningConfiguration: { Status: "Enabled" }
-		}));
-		logger.info("✓ Enabled bucket versioning");
-		logger.debug("Enabling bucket encryption...");
-		await s3Client.send(new PutBucketEncryptionCommand({
-			Bucket: bucketName,
-			ServerSideEncryptionConfiguration: { Rules: [{
-				ApplyServerSideEncryptionByDefault: { SSEAlgorithm: "AES256" },
-				BucketKeyEnabled: true
-			}] }
-		}));
-		logger.info("✓ Enabled bucket encryption (AES-256)");
-		logger.debug("Setting bucket policy...");
-		const bucketPolicy = {
-			Version: "2012-10-17",
-			Statement: [{
-				Sid: "DenyExternalAccess",
-				Effect: "Deny",
-				Principal: "*",
-				Action: "s3:*",
-				Resource: [`arn:aws:s3:::${bucketName}`, `arn:aws:s3:::${bucketName}/*`],
-				Condition: { StringNotEquals: { "aws:PrincipalAccount": accountId } }
-			}]
-		};
-		await s3Client.send(new PutBucketPolicyCommand({
-			Bucket: bucketName,
-			Policy: JSON.stringify(bucketPolicy)
-		}));
-		logger.info("✓ Set bucket policy (deny external access)");
+		if (!skipStateBucketConfig) {
+			logger.debug("Enabling bucket versioning...");
+			await s3Client.send(new PutBucketVersioningCommand({
+				Bucket: bucketName,
+				VersioningConfiguration: { Status: "Enabled" }
+			}));
+			logger.info("✓ Enabled bucket versioning");
+			logger.debug("Enabling bucket encryption...");
+			await s3Client.send(new PutBucketEncryptionCommand({
+				Bucket: bucketName,
+				ServerSideEncryptionConfiguration: { Rules: [{
+					ApplyServerSideEncryptionByDefault: { SSEAlgorithm: "AES256" },
+					BucketKeyEnabled: true
+				}] }
+			}));
+			logger.info("✓ Enabled bucket encryption (AES-256)");
+			logger.debug("Setting bucket policy...");
+			const bucketPolicy = {
+				Version: "2012-10-17",
+				Statement: [{
+					Sid: "DenyExternalAccess",
+					Effect: "Deny",
+					Principal: "*",
+					Action: "s3:*",
+					Resource: [`arn:aws:s3:::${bucketName}`, `arn:aws:s3:::${bucketName}/*`],
+					Condition: { StringNotEquals: { "aws:PrincipalAccount": accountId } }
+				}]
+			};
+			await s3Client.send(new PutBucketPolicyCommand({
+				Bucket: bucketName,
+				Policy: JSON.stringify(bucketPolicy)
+			}));
+			logger.info("✓ Set bucket policy (deny external access)");
+		}
+		let assetStorage;
+		if (options.assets) {
+			logger.info("\nSetting up cdkd asset storage...");
+			const ecrClient = new ECRClient({
+				region,
+				...options.profile && { profile: options.profile }
+			});
+			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 }
+			});
+			try {
+				assetStorage = await ensureAssetStorage({
+					s3Client,
+					ecrClient,
+					stateBackend,
+					accountId,
+					region,
+					force: options.force
+				});
+			} finally {
+				ecrClient.destroy();
+				markerS3Client.destroy();
+			}
+		} else logger.info("\n--no-assets specified — skipping cdkd asset storage. Deploys in this region keep publishing assets to the CDK bootstrap bucket/repo.");
 		logger.info("\n✓ Bootstrap completed successfully");
 		logger.info(`\nState bucket: ${bucketName}`);
+		if (assetStorage) {
+			logger.info(`Asset bucket: ${assetStorage.assetBucket}`);
+			logger.info(`Container-asset repository: ${assetStorage.containerRepo}`);
+		}
 		logger.info(`Region: ${region}`);
+		if (assetStorage) logger.info(`\ncdkd asset storage is now ON for region ${region}: deploys in this region publish assets to the cdkd-owned bucket/repo (out of 'cdk gc' reach) instead of the CDK bootstrap storage. The first deploy of each existing stack with assets will show a one-time UPDATE re-pointing asset references — content is identical, no replacement.`);
 		logger.info("\nYou can now use cdkd deploy with:");
 		logger.info(`  --state-bucket ${bucketName}`);
 		logger.info(`  --region ${region}`);
@@ -705,7 +1055,7 @@ async function bootstrapCommand(options) {
 * Create bootstrap command
 */
 function createBootstrapCommand() {
-	const cmd = new Command("bootstrap").description("Bootstrap cdkd by creating required S3 bucket for state management").option("--state-bucket <bucket>", "Name of S3 bucket to create for state storage (default: cdkd-state-{accountId})").option("--force", "Force reconfiguration of existing bucket", 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(bootstrapCommand));
+	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").option("--state-bucket <bucket>", "Name of S3 bucket to create for state storage (default: cdkd-state-{accountId})").option("--force", "Force reconfiguration of existing bucket", false).option("--no-assets", "Skip cdkd asset storage (asset bucket / ECR repo / marker) — deploys keep publishing assets to the CDK bootstrap bucket/repo").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(bootstrapCommand));
 	commonOptions.forEach((opt) => cmd.addOption(opt));
 	return cmd;
 }
@@ -1445,7 +1795,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.231.11";
+	return "0.232.0";
 }
 /**
 * Generate a time-sortable unique run id, e.g.
@@ -37644,6 +37994,7 @@ async function deployCommand(stacks, options) {
 		const accountId = (await stsClient.send(new GetCallerIdentityCommand({}))).Account;
 		stsClient.destroy();
 		const assetPublisher = new AssetPublisher();
+		const assetModeResolver = new AssetModeResolver(preflightStateBackend, accountId, { ...options.profile && { profile: options.profile } });
 		const stateConfig = {
 			bucket: stateBucket,
 			prefix: options.statePrefix
@@ -37660,17 +38011,24 @@ async function deployCommand(stacks, options) {
 		for (const stack of targetStacks) {
 			const stackNodeId = `stack:${stack.stackName}`;
 			const stackDeps = /* @__PURE__ */ new Set();
-			if (!options.skipAssets && stack.assetManifestPath) try {
+			if (!options.skipAssets && stack.assetManifestPath) {
 				const assetRegion = stack.region || baseRegion;
-				const nodeIds = assetPublisher.addAssetsToGraph(workGraph, stack.assetManifestPath, {
-					accountId,
-					region: assetRegion,
-					...options.profile && { profile: options.profile },
-					nodePrefix: `${stack.stackName}:`
-				});
+				let nodeIds = [];
+				try {
+					nodeIds = assetPublisher.addAssetsToGraph(workGraph, stack.assetManifestPath, {
+						accountId,
+						region: assetRegion,
+						...options.profile && { profile: options.profile },
+						nodePrefix: `${stack.stackName}:`
+					});
+				} catch (error) {
+					if (error.code !== "ENOENT") throw error;
+				}
+				if (nodeIds.length > 0) {
+					const assetMode = await assetModeResolver.resolve(assetRegion);
+					logger.debug(`Asset mode for region ${assetRegion}: ${assetMode.mode} (stack ${stack.stackName})`);
+				}
 				for (const id of nodeIds) stackDeps.add(id);
-			} catch (error) {
-				if (error.code !== "ENOENT") throw error;
 			}
 			for (const depName of effectiveStackDeps(stack.stackName, stack.dependencyNames)) if (stackMap.has(depName)) stackDeps.add(`stack:${depName}`);
 			workGraph.addNode({
@@ -45188,6 +45546,45 @@ async function readSchemaVersion(awsClients, bucket, keys) {
 	}
 }
 /**
+* List every region's bootstrap marker under `cdkd-bootstrap/` in the state
+* bucket. Malformed markers are skipped with a warning — `state info` is a
+* cosmetic command and should not crash on an unexpected payload (deploy
+* hard-errors on the same marker instead).
+*/
+async function listAssetStorageMarkers(awsClients, bucket) {
+	const logger = getLogger();
+	const entries = [];
+	let continuationToken;
+	const keys = [];
+	do {
+		const resp = await awsClients.s3.send(new ListObjectsV2Command({
+			Bucket: bucket,
+			Prefix: BOOTSTRAP_MARKER_PREFIX,
+			...continuationToken && { ContinuationToken: continuationToken }
+		}));
+		for (const obj of resp.Contents ?? []) if (typeof obj.Key === "string" && obj.Key.startsWith("cdkd-bootstrap/") && obj.Key.endsWith(".json")) keys.push(obj.Key);
+		continuationToken = resp.NextContinuationToken;
+	} while (continuationToken);
+	for (const key of keys) {
+		const region = key.slice(BOOTSTRAP_MARKER_PREFIX.length, -5);
+		try {
+			const marker = parseBootstrapMarker(await (await awsClients.s3.send(new GetObjectCommand({
+				Bucket: bucket,
+				Key: key
+			}))).Body?.transformToString() ?? "", key);
+			entries.push({
+				region,
+				assetBucket: marker.assetBucket,
+				containerRepo: marker.containerRepo,
+				createdAt: marker.createdAt
+			});
+		} catch (error) {
+			logger.warn(`Skipping malformed/unreadable bootstrap marker '${key}': ${error.message}`);
+		}
+	}
+	return entries.sort((a, b) => a.region.localeCompare(b.region));
+}
+/**
 * `cdkd state info` command implementation.
 *
 * Prints the state-bucket information that used to appear as a banner on
@@ -45229,6 +45626,7 @@ async function stateInfoCommand(options) {
 		const detectedRegion = await detectBucketRegion(awsClients, bucket);
 		const stateFileKeys = await listStateFileKeys(awsClients, bucket, prefix);
 		const schemaVersion = await readSchemaVersion(awsClients, bucket, stateFileKeys);
+		const assetStorage = await listAssetStorageMarkers(awsClients, bucket);
 		if (options.json) {
 			const json = {
 				bucket,
@@ -45236,7 +45634,8 @@ async function stateInfoCommand(options) {
 				regionSource: detectedRegion ? "auto-detected" : "unknown",
 				bucketSource: resolved.source,
 				schemaVersion,
-				stackCount: stateFileKeys.length
+				stackCount: stateFileKeys.length,
+				assetStorage
 			};
 			process.stdout.write(`${JSON.stringify(json, null, 2)}\n`);
 			return;
@@ -45248,6 +45647,11 @@ async function stateInfoCommand(options) {
 		lines.push(`Source:          ${formatBucketSource(resolved.source)}`);
 		lines.push(`Schema version:  ${schemaVersion}`);
 		lines.push(`Stacks:          ${stateFileKeys.length}`);
+		if (assetStorage.length === 0) lines.push("Asset storage:   legacy (CDK bootstrap) — run cdkd bootstrap to opt in");
+		else {
+			lines.push(`Asset storage:   cdkd-assets mode in ${assetStorage.length} region(s)`);
+			for (const entry of assetStorage) lines.push(`  ${entry.region}: ${entry.assetBucket} / ${entry.containerRepo}`);
+		}
 		process.stdout.write(`${lines.join("\n")}\n`);
 	} finally {
 		awsClients.destroy();
@@ -55779,7 +56183,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.231.11");
+	program.name("cdkd").description("CDK Direct - Deploy AWS CDK apps directly via SDK/Cloud Control API").version("0.232.0");
 	program.addCommand(createBootstrapCommand());
 	program.addCommand(createSynthCommand());
 	program.addCommand(createListCommand());