@go-to-k/cdkd 0.227.0 → 0.228.0

package/README.md

@@ -588,12 +588,15 @@ stream to S3 — cdkd's local equivalent of CloudFormation's
 cdkd events MyStack                 # list runs, newest first
 cdkd events MyStack --run <runId>   # one run's full event stream
 cdkd events MyStack --format json   # machine-readable (AI-agent hand-off)
+cdkd events prune MyStack --all     # purge event history (reclaim S3 space)
 ```
 
 Events are persisted as JSONL under a `deployments/` key family separate
 from `state.json` (no state schema bump), so a destroyed stack's failure
 history stays readable. Recording is best-effort and never blocks the
-run; events carry error + metadata only (never resource properties). See
+run; events carry error + metadata only (never resource properties). The
+store self-bounds to the last 20 runs, and `cdkd events prune` purges old
+history on demand (`--keep N` / `--older-than <dur>` / `--all`). See
 **[docs/deployment-events.md](docs/deployment-events.md)** for the full
 reference.
 

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { A as withErrorHandling, B as generateResourceNameWithFallback, C as StackHasActiveImportsError, F as getLiveRenderer, H as withStackName, I as PATTERN_B_NAME_PROPERTIES, L as PATTERN_B_RESOURCE_TYPES, M as getLogger, P as runStackBuffered, S as ResourceUpdateNotSupportedError, V as withSkipPrefix, _ as MissingCdkCliError, a as assertRegionMatch, b as ProvisioningError, f as LocalInvokeBuildError$1, i as resolveExplicitPhysicalId, k as normalizeAwsError, l as CdkdError, m as LocalStartServiceError, n as matchesCdkPath, o as disableInstanceApiTermination, p as LocalMigrateError, r as normalizeAwsTagsToCfn, s as isTerminationProtectionPropagationError, t as CDK_PATH_TAG, v as NestedStackChildDirectDestroyError, w as StackTerminationProtectionError, x as ResourceTimeoutError, y as PartialFailureError, z as generateResourceName } from "./import-helpers-wLipXr5g.js";
 import { a as setAwsClients, i as resetAwsClients, r as getAwsClients, t as AwsClients } from "./aws-clients-pjPwZz1r.js";
-import { $ as findLargeInlineResources, A as shouldRetainResource, B as getDockerImageBySourceHash, C as applyRoleArnIfSet, D as LockManager, E as TemplateParser, F as formatDockerLoginError, G as resolveCaptureObservedState, H as getDefaultStateBucketName, I as getDockerCmd, J as resolveStateBucketWithDefaultAndSource, K as resolveSkipPrefix, L as runDockerForeground, M as stringifyValue, N as WorkGraph, O as S3StateBackend, P as buildDockerImage, Q as MIGRATE_TMP_PREFIX, R as runDockerStreaming, S as IntrinsicFunctionResolver, T as DagBuilder, U as getLegacyStateBucketName, V as Synthesizer, W as resolveApp, X as CFN_TEMPLATE_BODY_LIMIT, Y as warnDeprecatedNoPrefixCliFlag, Z as CFN_TEMPLATE_URL_LIMIT, _ as IAMRoleProvider, a as withRetry, b as findActionableSilentDrops, c as computeImplicitDeleteEdges, d as bold, et as uploadCfnTemplate, f as cyan, g as yellow, h as red, i as withResourceDeadline, j as AssetPublisher, k as rebuildClientForBucketRegion, l as extractDeploymentEventError, m as green, n as DEFAULT_RESOURCE_WARN_AFTER_MS, o as isRetryableTransientError, p as gray, q as resolveStateBucketWithDefault, r as DeployEngine, rt as resolveBucketRegion, s as IMPLICIT_DELETE_DEPENDENCIES, t as DEFAULT_RESOURCE_TIMEOUT_MS, tt as AssemblyReader, u as formatResourceLine, v as collectInlinePolicyNamesManagedBySiblings, w as DiffCalculator, x as CloudControlProvider, y as ProviderRegistry, z as AssetManifestLoader } from "./deploy-engine-CBzCsd24.js";
+import { $ as findLargeInlineResources, A as shouldRetainResource, B as getDockerImageBySourceHash, C as applyRoleArnIfSet, D as LockManager, E as TemplateParser, F as formatDockerLoginError, G as resolveCaptureObservedState, H as getDefaultStateBucketName, I as getDockerCmd, J as resolveStateBucketWithDefaultAndSource, K as resolveSkipPrefix, L as runDockerForeground, M as stringifyValue, N as WorkGraph, O as S3StateBackend, P as buildDockerImage, Q as MIGRATE_TMP_PREFIX, R as runDockerStreaming, S as IntrinsicFunctionResolver, T as DagBuilder, U as getLegacyStateBucketName, V as Synthesizer, W as resolveApp, X as CFN_TEMPLATE_BODY_LIMIT, Y as warnDeprecatedNoPrefixCliFlag, Z as CFN_TEMPLATE_URL_LIMIT, _ as IAMRoleProvider, a as withRetry, b as findActionableSilentDrops, c as computeImplicitDeleteEdges, d as bold, et as uploadCfnTemplate, f as cyan, g as yellow, h as red, i as withResourceDeadline, j as AssetPublisher, k as rebuildClientForBucketRegion, l as extractDeploymentEventError, m as green, n as DEFAULT_RESOURCE_WARN_AFTER_MS, o as isRetryableTransientError, p as gray, q as resolveStateBucketWithDefault, r as DeployEngine, rt as resolveBucketRegion, s as IMPLICIT_DELETE_DEPENDENCIES, t as DEFAULT_RESOURCE_TIMEOUT_MS, tt as AssemblyReader, u as formatResourceLine, v as collectInlinePolicyNamesManagedBySiblings, w as DiffCalculator, x as CloudControlProvider, y as ProviderRegistry, z as AssetManifestLoader } from "./deploy-engine-BRZdKXDs.js";
 import { t as ASGProvider } from "./asg-provider-B_hrCxRx.js";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { randomBytes, randomUUID } from "node:crypto";
@@ -1543,6 +1543,10 @@ async function promptRecreateConfirm(input) {
 * - **Separate keys from state.json** — no state schema bump; event
 *   files survive `cdkd destroy` (state deletion does not touch
 *   `deployments/`), preserving post-mortem context.
+* - **Bounded growth** (issue #885): `finalize()` prunes `{runId}.jsonl`
+*   streams that fell out of the index window so the `deployments/`
+*   prefix stays bounded; `cdkd events prune` (via
+*   {@link DeploymentEventsReader.pruneRuns}) is the explicit purge.
 */
 /** Max runs retained in `deployments/index.json` (newest first). */
 const DEPLOYMENT_EVENTS_MAX_INDEX_RUNS = 20;
@@ -1552,7 +1556,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.227.0";
+	return "0.228.0";
 }
 /**
 * Generate a time-sortable unique run id, e.g.
@@ -1571,6 +1575,29 @@ function deploymentEventsKey(prefix, stackName, region, runId) {
 function deploymentEventsIndexKey(prefix, stackName, region) {
 	return `${prefix}/${stackName}/${region}/deployments/index.json`;
 }
+/** S3 key prefix under which a stack's `deployments/` artifacts live. */
+function deploymentsDirPrefix(prefix, stackName, region) {
+	return `${prefix}/${stackName}/${region}/deployments/`;
+}
+/**
+* Parse the wall-clock time encoded in a run id's leading timestamp
+* (e.g. `20260613T012345678Z-1a2b3c4d`) back to epoch milliseconds.
+* Returns `null` for any id that does not start with the canonical
+* compact-ISO prefix — the age-based pruner treats an unparseable id as
+* "do not delete on age grounds", which is the safe direction.
+*/
+function runIdTimestampMs(runId) {
+	const m = /^(\d{4})(\d{2})(\d{2})T(\d{2})(\d{2})(\d{2})(\d{3})Z/.exec(runId);
+	if (!m) return null;
+	const iso = `${m[1]}-${m[2]}-${m[3]}T${m[4]}:${m[5]}:${m[6]}.${m[7]}Z`;
+	const ms = Date.parse(iso);
+	return Number.isNaN(ms) ? null : ms;
+}
+/** Extract the `{runId}` from a `.../{runId}.jsonl` event-stream key. */
+function runIdFromJsonlKey(key, dirPrefix) {
+	if (!key.startsWith(dirPrefix) || !key.endsWith(".jsonl")) return null;
+	return key.slice(dirPrefix.length, -6);
+}
 /**
 * Buffering JSONL writer for one deployment run. Implements the
 * {@link DeploymentEventRecorder} seam the deploy engine / destroy
@@ -1634,7 +1661,8 @@ var DeploymentEventsStore = class {
 		if (this.events.length === 0) return;
 		await this.enqueueWrite(async () => {
 			await this.doFlush();
-			await this.updateIndex(result);
+			const keptRunIds = await this.updateIndex(result);
+			await this.pruneSupersededRunFiles(keptRunIds);
 		});
 	}
 	/** Await any in-flight async flushes (used by tests). */
@@ -1671,6 +1699,10 @@ var DeploymentEventsStore = class {
 	* the last {@link DEPLOYMENT_EVENTS_MAX_INDEX_RUNS} runs. Read-modify-
 	* write WITHOUT optimistic locking — last-writer-wins (documented
 	* trade-off; the per-run `.jsonl` files are the source of truth).
+	*
+	* Returns the run ids retained in the index (newest-first), which the
+	* caller feeds to {@link pruneSupersededRunFiles} so the `.jsonl` files
+	* stay bounded to the same window as the index.
 	*/
 	async updateIndex(result) {
 		const key = deploymentEventsIndexKey(this.backend.prefix, this.stackName, this.region);
@@ -1701,6 +1733,35 @@ var DeploymentEventsStore = class {
 			lastModified: Date.now()
 		};
 		await this.backend.putRawObject(key, JSON.stringify(file, null, 2));
+		return runs.map((r) => r.runId);
+	}
+	/**
+	* Self-bounding prune (issue #885): delete `{runId}.jsonl` streams that
+	* have fallen out of the index window so the `deployments/` prefix does
+	* not grow without bound. Best-effort — runs inside the same write-chain
+	* link as the flush + index write, so a failure here is caught + warned
+	* once by {@link enqueueWrite} and never blocks the deploy / destroy.
+	*
+	* Concurrency-tolerant by construction: the cutoff is the OLDEST retained
+	* run id, and only `.jsonl` files strictly below it are deleted. Run ids
+	* are time-sortable, so a concurrent NEWER run's id sorts ABOVE every
+	* retained id and is never touched. A concurrent run that STARTED earlier
+	* but is still writing could in theory fall below the cutoff if 20+ newer
+	* runs finalized while it ran — an extreme edge that self-heals anyway,
+	* since the whole JSONL body is re-PUT on that run's next flush / finalize
+	* (S3 has no append; each flush rewrites the full stream).
+	*/
+	async pruneSupersededRunFiles(keptRunIds) {
+		if (keptRunIds.length < 20) return;
+		const cutoff = keptRunIds.reduce((min, id) => id < min ? id : min, keptRunIds[0]);
+		const dirPrefix = deploymentsDirPrefix(this.backend.prefix, this.stackName, this.region);
+		const stale = (await this.backend.listRawKeys(dirPrefix)).filter((k) => {
+			const runId = runIdFromJsonlKey(k, dirPrefix);
+			return runId !== null && runId < cutoff;
+		});
+		if (stale.length === 0) return;
+		await this.backend.deleteRawObjects(stale);
+		this.logger.debug(`Pruned ${stale.length} superseded deployment-event stream(s) for ${this.stackName} (${this.region})`);
 	}
 	warnOnce(message) {
 		if (this.warnedOnce) {
@@ -1819,6 +1880,102 @@ var DeploymentEventsReader = class {
 		}
 		return events;
 	}
+	/**
+	* Prune a stack's recorded deployment-event runs (issue #885 — `cdkd
+	* events prune`). Deletes `{runId}.jsonl` streams beyond a retention
+	* window and rewrites (or removes) `index.json` to match.
+	*
+	* Retention semantics (see {@link DeploymentEventsPruneOptions}):
+	*   - `all`        — delete every run + the index (full purge).
+	*   - `keep N`     — retain the newest N runs, delete the rest.
+	*   - `olderThanMs`— delete runs whose run-id timestamp is older than the
+	*                    cutoff; a run id with no parseable timestamp is kept.
+	*   - `keep` + `olderThanMs` — a run is deleted only when it is BOTH
+	*                    beyond the newest-N window AND older than the cutoff
+	*                    (the most conservative combination).
+	*   - none of the above — defaults to `keep DEPLOYMENT_EVENTS_MAX_INDEX_RUNS`
+	*                    (matches the index window the writer self-bounds to).
+	*
+	* Unlike the writer's best-effort auto-prune, this is user-initiated and
+	* surfaces errors to the caller (the command reports / exits non-zero).
+	*/
+	async pruneRuns(stackName, region, opts = {}) {
+		const dirPrefix = deploymentsDirPrefix(this.backend.prefix, stackName, region);
+		const runIdsDesc = (await this.backend.listRawKeys(dirPrefix)).map((k) => runIdFromJsonlKey(k, dirPrefix)).filter((id) => id !== null).sort().reverse();
+		const indexKey = deploymentEventsIndexKey(this.backend.prefix, stackName, region);
+		if (opts.all === true) {
+			const toDelete = runIdsDesc.map((id) => deploymentEventsKey(this.backend.prefix, stackName, region, id));
+			await this.backend.deleteRawObjects([...toDelete, indexKey]);
+			return {
+				deletedRunIds: runIdsDesc,
+				remainingRunIds: [],
+				indexDeleted: true
+			};
+		}
+		const noGuards = opts.keep === void 0 && opts.olderThanMs === void 0;
+		const keep = opts.keep ?? (noGuards ? 20 : void 0);
+		const protectedByCount = keep === void 0 ? /* @__PURE__ */ new Set() : new Set(runIdsDesc.slice(0, keep));
+		let candidates = runIdsDesc.filter((id) => !protectedByCount.has(id));
+		if (opts.olderThanMs !== void 0) {
+			const cutoff = (opts.now ?? /* @__PURE__ */ new Date()).getTime() - opts.olderThanMs;
+			candidates = candidates.filter((id) => {
+				const t = runIdTimestampMs(id);
+				return t !== null && t < cutoff;
+			});
+		}
+		if (candidates.length === 0) return {
+			deletedRunIds: [],
+			remainingRunIds: runIdsDesc,
+			indexDeleted: false
+		};
+		const deletedSet = new Set(candidates);
+		const deleteKeys = candidates.map((id) => deploymentEventsKey(this.backend.prefix, stackName, region, id));
+		const remainingRunIds = runIdsDesc.filter((id) => !deletedSet.has(id));
+		const indexDeleted = await this.rewriteIndexAfterPrune(indexKey, stackName, region, deletedSet, remainingRunIds.length === 0);
+		await this.backend.deleteRawObjects(deleteKeys);
+		return {
+			deletedRunIds: candidates,
+			remainingRunIds,
+			indexDeleted
+		};
+	}
+	/**
+	* Drop the pruned run ids from `index.json`, or delete the index entirely
+	* when no `.jsonl` streams remain. A corrupt / unreadable index is left
+	* untouched (the `.jsonl` files are the source of truth; `cdkd events`
+	* falls back to key enumeration). Returns whether the index was deleted.
+	*/
+	async rewriteIndexAfterPrune(indexKey, stackName, region, deletedRunIds, noRunsRemain) {
+		if (noRunsRemain) {
+			await this.backend.deleteRawObjects([indexKey]);
+			return true;
+		}
+		let raw;
+		try {
+			raw = await this.backend.getRawObject(indexKey);
+		} catch {
+			return false;
+		}
+		if (raw === null) return false;
+		let parsed;
+		try {
+			parsed = JSON.parse(raw);
+		} catch {
+			return false;
+		}
+		if (!Array.isArray(parsed.runs)) return false;
+		const remaining = parsed.runs.filter((r) => !deletedRunIds.has(r.runId));
+		if (remaining.length === parsed.runs.length) return false;
+		const file = {
+			indexVersion: 1,
+			stackName,
+			region,
+			runs: remaining,
+			lastModified: Date.now()
+		};
+		await this.backend.putRawObject(indexKey, JSON.stringify(file, null, 2));
+		return false;
+	}
 };
 
 //#endregion
@@ -9757,6 +9914,7 @@ var DynamoDBTableProvider = class {
 					this.logger.debug(`Updated WarmThroughput on DynamoDB table ${physicalId}`);
 				}
 			}
+			if (JSON.stringify(properties["GlobalSecondaryIndexes"]) !== JSON.stringify(previousProperties["GlobalSecondaryIndexes"])) await this.applyGsiUpdates(physicalId, resourceType, logicalId, previousProperties["GlobalSecondaryIndexes"], properties["GlobalSecondaryIndexes"], properties["AttributeDefinitions"]);
 			if (JSON.stringify(properties["PointInTimeRecoverySpecification"]) !== JSON.stringify(previousProperties["PointInTimeRecoverySpecification"])) await this.applyPointInTimeRecovery(physicalId, properties["PointInTimeRecoverySpecification"], previousProperties["PointInTimeRecoverySpecification"]);
 			if (JSON.stringify(properties["TimeToLiveSpecification"]) !== JSON.stringify(previousProperties["TimeToLiveSpecification"])) await this.applyTimeToLive(physicalId, properties["TimeToLiveSpecification"], previousProperties["TimeToLiveSpecification"]);
 			if (JSON.stringify(properties["ResourcePolicy"]) !== JSON.stringify(previousProperties["ResourcePolicy"])) {
@@ -10082,6 +10240,79 @@ var DynamoDBTableProvider = class {
 		throw new Error(`Table ${tableName} did not reach ACTIVE status within ${maxAttempts} seconds after UpdateTable`);
 	}
 	/**
+	* Poll DescribeTable until the table is ACTIVE AND every Global Secondary
+	* Index is ACTIVE (not CREATING / UPDATING / DELETING / BACKFILLING). Used
+	* between GSI mutations because a freshly-created index keeps backfilling
+	* after the table itself returns to ACTIVE, and AWS rejects the next GSI op
+	* until the prior index settles.
+	*/
+	async waitForTableAndIndexesActive(tableName, maxAttempts = 1800) {
+		for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+			const table = (await this.dynamoDBClient.send(new DescribeTableCommand({ TableName: tableName }))).Table;
+			const tableActive = table?.TableStatus === "ACTIVE";
+			const indexesActive = (table?.GlobalSecondaryIndexes ?? []).every((gsi) => gsi.IndexStatus === "ACTIVE");
+			if (tableActive && indexesActive) return;
+			await new Promise((resolve) => setTimeout(resolve, 1e3));
+		}
+		throw new Error(`Table ${tableName} and its global secondary indexes did not reach ACTIVE within ${maxAttempts} seconds after UpdateTable`);
+	}
+	/**
+	* Apply Global Secondary Index add / remove / per-index throughput changes
+	* via UpdateTable's `GlobalSecondaryIndexUpdates`.
+	*
+	* AWS constraints mirrored here:
+	*  - At most ONE GSI Create or Delete per UpdateTable call; a second
+	*    mutation while the table / an index is still building is rejected. Each
+	*    op therefore runs in its own UpdateTable and waits for ACTIVE before the
+	*    next (creating GSIs also go through a BACKFILLING phase that ACTIVE
+	*    covers).
+	*  - A GSI `Create` must carry the AttributeDefinitions for the new index's
+	*    key attributes — the full desired AttributeDefinitions array is passed
+	*    so every newly-referenced attribute is defined.
+	*  - On an existing same-name index, only a PROVISIONED `ProvisionedThroughput`
+	*    (RCU/WCU) change is mutable in place and is issued as an `Update`. A
+	*    `KeySchema` / `Projection` change is immutable in place (AWS models it as
+	*    a delete + re-create); since the diff keys GSIs by name it would not emit
+	*    a remove-then-add pair, so this method throws on such a change rather than
+	*    silently dropping it.
+	*/
+	async applyGsiUpdates(physicalId, resourceType, logicalId, previousGsis, desiredGsis, desiredAttributeDefinitions) {
+		const prev = previousGsis ?? [];
+		const desired = desiredGsis ?? [];
+		const prevByName = new Map(prev.filter((g) => g.IndexName).map((g) => [g.IndexName, g]));
+		const desiredByName = new Map(desired.filter((g) => g.IndexName).map((g) => [g.IndexName, g]));
+		const ops = [];
+		for (const name of prevByName.keys()) if (!desiredByName.has(name)) ops.push({ Delete: { IndexName: name } });
+		for (const [name, gsi] of desiredByName) if (!prevByName.has(name)) {
+			if (!gsi.KeySchema) throw new ProvisioningError(`GlobalSecondaryIndex ${name} on DynamoDB table ${logicalId} is missing KeySchema`, resourceType, logicalId, physicalId);
+			ops.push({ Create: {
+				IndexName: name,
+				KeySchema: gsi.KeySchema,
+				Projection: gsi.Projection,
+				...gsi.ProvisionedThroughput ? { ProvisionedThroughput: gsi.ProvisionedThroughput } : {},
+				...gsi.OnDemandThroughput ? { OnDemandThroughput: gsi.OnDemandThroughput } : {}
+			} });
+		} else {
+			const before = prevByName.get(name);
+			if (JSON.stringify(before.KeySchema) !== JSON.stringify(gsi.KeySchema) || JSON.stringify(before.Projection) !== JSON.stringify(gsi.Projection)) throw new ProvisioningError(`GlobalSecondaryIndex ${name} on DynamoDB table ${logicalId} changed its KeySchema or Projection, which DynamoDB cannot modify in place. Rename the index (so it is dropped and re-created) or replace the table.`, resourceType, logicalId, physicalId);
+			if (gsi.ProvisionedThroughput && JSON.stringify(before.ProvisionedThroughput) !== JSON.stringify(gsi.ProvisionedThroughput)) ops.push({ Update: {
+				IndexName: name,
+				ProvisionedThroughput: gsi.ProvisionedThroughput
+			} });
+		}
+		for (const op of ops) {
+			const input = {
+				TableName: physicalId,
+				GlobalSecondaryIndexUpdates: [op]
+			};
+			if (op.Create && desiredAttributeDefinitions) input.AttributeDefinitions = desiredAttributeDefinitions;
+			await this.dynamoDBClient.send(new UpdateTableCommand(input));
+			await this.waitForTableAndIndexesActive(physicalId);
+			const verb = op.Create ? "created" : op.Delete ? "deleted" : "updated";
+			this.logger.debug(`${verb} GSI ${op.Create?.IndexName ?? op.Delete?.IndexName ?? op.Update?.IndexName} on DynamoDB table ${physicalId}`);
+		}
+	}
+	/**
 	* Resolve a single `Fn::GetAtt` attribute for an existing DynamoDB table.
 	*
 	* CloudFormation's `AWS::DynamoDB::Table` exposes `Arn`, `StreamArn`
@@ -37276,7 +37507,7 @@ async function retireCloudFormationStack(options) {
 		}
 	} else ({body: newBody, modified, format} = injectRetainPolicies(tpl.TemplateBody, cfnStackName));
 	if (!yes) {
-		if (!await confirmPrompt$5(`Set DeletionPolicy=Retain and UpdateReplacePolicy=Retain on every resource in CloudFormation stack '${cfnStackName}', then delete the stack? AWS resources will NOT be deleted (cdkd state has been written).`)) {
+		if (!await confirmPrompt$6(`Set DeletionPolicy=Retain and UpdateReplacePolicy=Retain on every resource in CloudFormation stack '${cfnStackName}', then delete the stack? AWS resources will NOT be deleted (cdkd state has been written).`)) {
 			logger.info("CloudFormation stack retirement cancelled. cdkd state is unaffected.");
 			for (const cleanup of nestedCleanups) try {
 				await cleanup();
@@ -37653,7 +37884,7 @@ async function walkCfnStackTree(stackName, physicalId, cfnClient) {
 		nested
 	};
 }
-async function confirmPrompt$5(prompt) {
+async function confirmPrompt$6(prompt) {
 	const rl = readline$1.createInterface({
 		input: process.stdin,
 		output: process.stdout
@@ -38822,7 +39053,7 @@ async function runAccept(reports, stateBackend, stateConfig, awsClients, options
 		return;
 	}
 	if (!options.yes) {
-		if (!await confirmPrompt$4(`Update cdkd state with the AWS-current values shown above?`)) {
+		if (!await confirmPrompt$5(`Update cdkd state with the AWS-current values shown above?`)) {
 			logger.info("Aborted.");
 			return;
 		}
@@ -38948,7 +39179,7 @@ async function runRevert(reports, providerRegistry, stateConfig, awsClients, opt
 		return;
 	}
 	if (!options.yes) {
-		if (!await confirmPrompt$4(`Push cdkd state values back into AWS for the resources shown above?`)) {
+		if (!await confirmPrompt$5(`Push cdkd state values back into AWS for the resources shown above?`)) {
 			logger.info("Aborted.");
 			return;
 		}
@@ -39056,7 +39287,7 @@ async function runWithConcurrency(tasks, concurrency) {
 	})());
 	await Promise.all(workers);
 }
-async function confirmPrompt$4(prompt) {
+async function confirmPrompt$5(prompt) {
 	const rl = readline$1.createInterface({
 		input: process.stdin,
 		output: process.stdout
@@ -39518,6 +39749,86 @@ async function resolveEventsRegion(reader, stackName, explicitRegion) {
 	if (regions.length > 1) throw new CdkdError(`Stack '${stackName}' has deployment-event history in multiple regions: ${regions.join(", ")}. Re-run with '--stack-region <region>' to disambiguate.`, "EVENTS_REGION_AMBIGUOUS");
 	return regions[0];
 }
+/**
+* `cdkd events prune <stack>` — reclaim S3 space by deleting old per-run
+* `{runId}.jsonl` event streams (issue #885). `cdkd destroy` deliberately
+* keeps event history as post-mortem context, so this is the explicit way
+* to purge it; the deploy/destroy writer also self-bounds to the last
+* {@link DEPLOYMENT_EVENTS_MAX_INDEX_RUNS} runs automatically.
+*
+* Retention selection:
+*   - `--all`              purge every run + the index.
+*   - `--keep <N>`         retain the newest N runs.
+*   - `--older-than <dur>` delete runs older than the duration.
+*   - both keep+older-than: delete runs that are BOTH beyond newest-N AND
+*                           older than the cutoff.
+*   - none of the above:   default to keeping the newest
+*                          {@link DEPLOYMENT_EVENTS_MAX_INDEX_RUNS}.
+*/
+async function eventsPruneCommand(stackName, options) {
+	const logger = getLogger();
+	if (options.verbose) logger.setLevel("debug");
+	warnIfDeprecatedRegion(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({
+		...options.region && { region: options.region },
+		...options.profile && { profile: options.profile }
+	});
+	setAwsClients(awsClients);
+	try {
+		const region = options.region || process.env["AWS_REGION"] || "us-east-1";
+		const bucket = await resolveStateBucketWithDefault(options.stateBucket, region);
+		const prefix = options.statePrefix ?? "cdkd";
+		const stateBackend = new S3StateBackend(awsClients.s3, {
+			bucket,
+			prefix
+		}, {
+			region,
+			...options.profile && { profile: options.profile }
+		});
+		await stateBackend.verifyBucketExists();
+		const reader = new DeploymentEventsReader(stateBackend);
+		const targetRegion = await resolveEventsRegion(reader, stackName, options.stackRegion);
+		const totalRuns = (await reader.listRuns(stackName, targetRegion)).length;
+		const scope = options.all ? `ALL ${totalRuns} run(s)` : options.keep !== void 0 && olderThanMs !== void 0 ? `runs beyond the newest ${options.keep} AND older than ${options.olderThan}` : options.keep !== void 0 ? `runs beyond the newest ${options.keep}` : olderThanMs !== void 0 ? `runs older than ${options.olderThan}` : `runs beyond the newest ${20}`;
+		if (options.yes !== true) {
+			if (!process.stdin.isTTY) {
+				logger.info(gray(`Refusing to prune deployment-event history for ${stackName} (${targetRegion}) without confirmation on a non-interactive terminal. Re-run with --yes to proceed.`));
+				return;
+			}
+			if (!await confirmPrompt$4(`Prune deployment-event history for ${cyan(stackName)} ${gray(`(${targetRegion})`)}: ${scope}?`)) {
+				logger.info(gray("Aborted; nothing was deleted."));
+				return;
+			}
+		}
+		const result = await reader.pruneRuns(stackName, targetRegion, {
+			...options.all === true && { all: true },
+			...options.keep !== void 0 && { keep: options.keep },
+			...olderThanMs !== void 0 && { olderThanMs }
+		});
+		if (result.deletedRunIds.length === 0) {
+			logger.info(gray(result.indexDeleted ? `Removed the empty deployment-event index for ${stackName} (${targetRegion}); no run streams to delete.` : `No runs matched the prune criteria for ${stackName} (${targetRegion}).`));
+			return;
+		}
+		logger.info(`${green("Pruned")} ${result.deletedRunIds.length} deployment-event run(s) for ${cyan(stackName)} ${gray(`(${targetRegion})`)}; ${result.remainingRunIds.length} retained` + (result.indexDeleted ? gray(" (index removed)") : "") + ".");
+	} finally {
+		awsClients.destroy();
+	}
+}
+/** Minimal `(y/N)` confirmation prompt. */
+async function confirmPrompt$4(prompt) {
+	const rl = readline$1.createInterface({
+		input: process.stdin,
+		output: process.stdout
+	});
+	try {
+		const ans = await rl.question(`${prompt} [y/N] `);
+		return /^y(es)?$/i.test(ans.trim());
+	} finally {
+		rl.close();
+	}
+}
 /** Human-readable run listing (newest first). */
 function printRunList(stackName, region, runs) {
 	const logger = getLogger();
@@ -39578,8 +39889,27 @@ function createEventsCommand() {
 	}));
 	[...commonOptions, ...stateOptions].forEach((opt) => cmd.addOption(opt));
 	cmd.addOption(deprecatedRegionOption);
+	cmd.addCommand(createEventsPruneCommand());
 	return cmd;
 }
+/**
+* Create the `cdkd events prune <stack>` subcommand (issue #885).
+*
+* Only the prune-SPECIFIC options (`--keep` / `--older-than` / `--all`) are
+* declared here. The shared option blocks (`commonOptions` + `stateOptions`
+* + the deprecated region option) and `--stack-region` are inherited from
+* the parent `events` command — declaring the same flag on BOTH parent and
+* child makes Commander route a post-subcommand flag (`events prune X --yes`)
+* to the PARENT's storage, leaving the child's value at its default. The
+* action therefore reads the merged view via `command.optsWithGlobals()`.
+*/
+function createEventsPruneCommand() {
+	return new Command("prune").description("Delete old per-run deployment-event streams to reclaim S3 space").argument("<stack>", "Stack name (physical CloudFormation name)").addOption(new Option("--keep <N>", "Retain only the newest N runs").argParser((v) => {
+		const n = parseInt(v, 10);
+		if (!Number.isInteger(n) || n < 0) throw new Error(`Invalid --keep value "${v}": expected a non-negative integer.`);
+		return n;
+	})).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/cdk-path.ts
@@ -54622,7 +54952,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.227.0");
+	program.name("cdkd").description("CDK Direct - Deploy AWS CDK apps directly via SDK/Cloud Control API").version("0.228.0");
 	program.addCommand(createBootstrapCommand());
 	program.addCommand(createSynthCommand());
 	program.addCommand(createListCommand());