cdk-local 0.71.2 → 0.72.0

package/dist/{local-list-BS463YYd.js → local-list-BOmsOq0r.js}

@@ -6,7 +6,7 @@ import path, { dirname, isAbsolute, join, normalize, resolve, sep } from "node:p
 import { Command, Option } from "commander";
 import { AssumeRoleCommand, GetCallerIdentityCommand, STSClient } from "@aws-sdk/client-sts";
 import { MultiSelectPrompt } from "@clack/core";
-import { S_BAR, S_BAR_END, S_BAR_START, S_CHECKBOX_ACTIVE, S_CHECKBOX_INACTIVE, S_CHECKBOX_SELECTED, confirm, isCancel, select } from "@clack/prompts";
+import { S_BAR, S_BAR_END, S_BAR_START, S_CHECKBOX_ACTIVE, S_CHECKBOX_INACTIVE, S_CHECKBOX_SELECTED, confirm, isCancel, multiselect, select, text } from "@clack/prompts";
 import { AssetManifestArtifact } from "@aws-cdk/cloud-assembly-api";
 import { BaseCredentials, CdkAppMultiContext, NonInteractiveIoHost, Toolkit } from "@aws-cdk/toolkit-lib";
 import { CloudFormationClient, DescribeStacksCommand, ListExportsCommand, ListStackResourcesCommand } from "@aws-sdk/client-cloudformation";
@@ -20055,6 +20055,12 @@ function sleep$1(ms) {
 async function prepareImages(task, out, options) {
 	const logger = getLogger().child("ecs-runner");
 	for (const container of task.containers) {
+		const overrideTag = options.imageOverrideByContainer?.get(container.name);
+		if (overrideTag !== void 0) {
+			out.set(container.name, overrideTag);
+			logger.debug(`Container '${container.name}' image=${overrideTag} (--image-override)`);
+			continue;
+		}
 		const image = await prepareOneImage(task, container, options);
 		out.set(container.name, image);
 		logger.debug(`Container '${container.name}' image=${image}`);
@@ -24243,6 +24249,282 @@ function describePinnedImageUri(service) {
 	return image.uri;
 }
 
+//#endregion
+//#region src/local/image-override-engine.ts
+/**
+* Errors surfaced by the engine. Used so the emulator can render a
+* consistent error class to the user (the global error handler maps
+* `CdkLocalError` subclasses to a clean stack-trace-free message).
+*/
+var ImageOverrideError = class ImageOverrideError extends CdkLocalError {
+	constructor(message, cause) {
+		super(message, "IMAGE_OVERRIDE_ERROR", cause);
+		this.name = "ImageOverrideError";
+		Object.setPrototypeOf(this, ImageOverrideError.prototype);
+	}
+};
+/**
+* Parse the raw `--image-override` / `--image-build-arg` /
+* `--image-build-secret` / `--image-target` flag arrays Commander
+* surfaces into the structured {@link RawImageOverrideFlags} shape.
+* Pure (no docker / filesystem calls); throws
+* {@link ImageOverrideError} on a malformed token so the emulator can
+* surface a clean error before any container is touched.
+*
+* - `--image-override <svc>=<dockerfile>` -> `explicit.set(svc, dockerfile)`
+* - `--image-override <dockerfile>` (no `=`) -> `pickerPaths.push(...)`
+* - `--image-build-arg KEY=VAL` -> `globals.buildArgs.set('KEY', 'VAL')`
+* - `--image-build-secret id=src` -> `globals.buildSecrets.set('id', 'src')`
+* - `--image-target <stage>` -> `globals.targetStage = '<stage>'`
+*
+* Collision detection: a service target named more than once in
+* `--image-override <svc>=...` is an error (last-write-wins would
+* silently drop the earlier mapping; explicit error is clearer).
+*/
+function parseImageOverrideFlags(input) {
+	const explicit = /* @__PURE__ */ new Map();
+	const pickerPaths = [];
+	for (const raw of input.imageOverride ?? []) {
+		const eq = raw.indexOf("=");
+		if (eq < 0) {
+			if (!raw) throw new ImageOverrideError("Invalid --image-override value: empty string. Pass <service>=<dockerfile> or just <dockerfile>.");
+			pickerPaths.push(raw);
+			continue;
+		}
+		const svc = raw.slice(0, eq).trim();
+		const dockerfile = raw.slice(eq + 1).trim();
+		if (!svc) throw new ImageOverrideError(`Invalid --image-override value "${raw}": left side (service target) is empty.`);
+		if (!dockerfile) throw new ImageOverrideError(`Invalid --image-override value "${raw}": right side (Dockerfile path) is empty.`);
+		if (explicit.has(svc)) throw new ImageOverrideError(`Duplicate --image-override for service '${svc}': already mapped to '${explicit.get(svc)}'. Pass each service target at most once in explicit form.`);
+		explicit.set(svc, dockerfile);
+	}
+	const buildArgs = /* @__PURE__ */ new Map();
+	for (const raw of input.imageBuildArg ?? []) {
+		const eq = raw.indexOf("=");
+		if (eq <= 0) throw new ImageOverrideError(`Invalid --image-build-arg value "${raw}": expected KEY=VAL.`);
+		const key = raw.slice(0, eq).trim();
+		const value = raw.slice(eq + 1);
+		if (!key) throw new ImageOverrideError(`Invalid --image-build-arg value "${raw}": empty key.`);
+		buildArgs.set(key, value);
+	}
+	const buildSecrets = /* @__PURE__ */ new Map();
+	for (const raw of input.imageBuildSecret ?? []) {
+		const eq = raw.indexOf("=");
+		if (eq <= 0) throw new ImageOverrideError(`Invalid --image-build-secret value "${raw}": expected id=src (e.g. npmrc=./.npmrc).`);
+		const id = raw.slice(0, eq).trim();
+		const src = raw.slice(eq + 1).trim();
+		if (!id || !src) throw new ImageOverrideError(`Invalid --image-build-secret value "${raw}": id and src must both be non-empty.`);
+		const absSrc = isAbsolute(src) ? src : resolve(process.cwd(), src);
+		buildSecrets.set(id, absSrc);
+	}
+	const globals = {
+		buildArgs,
+		buildSecrets
+	};
+	if (input.imageTarget !== void 0) {
+		if (!input.imageTarget) throw new ImageOverrideError("Invalid --image-target value: empty string.");
+		globals.targetStage = input.imageTarget;
+	}
+	return {
+		explicit,
+		pickerPaths,
+		globals
+	};
+}
+/**
+* Resolve `--image-override` flag inputs (raw) + a list of pinned
+* service targets into the final {@link ImageOverrideMap}. Walks four
+* stages:
+*
+*   1. Apply every explicit `<svc>=<dockerfile>` mapping. A service in
+*      `explicit` but NOT in `pinnedTargets` is a no-op warning
+*      (logged at warn) — the user named a non-pinned target, which
+*      probably indicates a typo or a CDK app change; we don't fail.
+*   2. For each picker-form Dockerfile path, fire a multi-select against
+*      the still-uncovered pinned targets. A single picker-form path
+*      may bind to multiple targets (one Dockerfile shared across N
+*      services); already-bound targets are excluded from later pickers.
+*      Skipped when not in a TTY OR `noInteractive` is true — those
+*      contexts emit a warning and skip the picker path (treated as
+*      "no override for any target").
+*   3. Optional boot prompt: when `interactiveBootPrompt` is true AND
+*      we're in a TTY, walk each remaining uncovered pinned target
+*      and ask "Override with a local build? [path / N]" via clack's
+*      `text` prompt. A non-empty answer is treated as an additional
+*      explicit mapping; `N` / empty / Esc skips the target.
+*
+* Returns the resolved override map. Throws
+* {@link ImageOverrideError} on a malformed picker response or a
+* Dockerfile path that doesn't exist (caught up-front before any
+* docker build runs).
+*/
+async function resolveImageOverrides(args) {
+	const logger = getLogger();
+	const { rawFlags, pinnedTargets, noInteractive } = args;
+	const cwd = args.cwd ?? process.cwd();
+	const pinnedSet = new Set(pinnedTargets);
+	const labels = args.pinnedLabels ?? /* @__PURE__ */ new Map();
+	const out = /* @__PURE__ */ new Map();
+	for (const [svc, dockerfileRaw] of rawFlags.explicit.entries()) {
+		if (!pinnedSet.has(svc)) {
+			logger.warn(`--image-override: service '${svc}' is not in the pinned-target set (no deployed-registry pin detected for it). Mapping ignored.`);
+			continue;
+		}
+		out.set(svc, makeEntryFromPath(dockerfileRaw, rawFlags.globals, cwd));
+	}
+	if (rawFlags.pickerPaths.length > 0) if (!(isInteractive() && noInteractive !== true)) logger.warn("--image-override <dockerfile> (picker form) requires an interactive TTY and --no-interactive-overrides not to be set. Skipping picker-form mapping(s).");
+	else for (const dockerfileRaw of rawFlags.pickerPaths) {
+		const uncovered = pinnedTargets.filter((t) => !out.has(t));
+		if (uncovered.length === 0) {
+			logger.warn(`--image-override ${dockerfileRaw}: no uncovered pinned targets left to bind to. Skipped.`);
+			continue;
+		}
+		const options = uncovered.map((t) => ({
+			value: t,
+			label: t,
+			...labels.get(t) ? { hint: labels.get(t) } : {}
+		}));
+		const picked = await multiselect({
+			message: `Pick the pinned target(s) to bind to '${dockerfileRaw}' (space to toggle, enter to confirm; empty cancels):`,
+			options,
+			required: false
+		});
+		if (isCancel(picked)) throw new ImageOverrideError("Image-override picker cancelled. Re-run without picker-form or with --no-interactive-overrides.");
+		const chosen = picked ?? [];
+		if (chosen.length === 0) {
+			logger.warn(`--image-override ${dockerfileRaw}: empty selection. Skipped.`);
+			continue;
+		}
+		const entry = makeEntryFromPath(dockerfileRaw, rawFlags.globals, cwd);
+		for (const t of chosen) out.set(t, entry);
+	}
+	if (args.interactiveBootPrompt === true && isInteractive() && noInteractive !== true) for (const target of pinnedTargets) {
+		if (out.has(target)) continue;
+		const label = labels.get(target);
+		const answer = await text({
+			message: `Detected pinned image on '${target}'` + (label ? ` (${label})` : "") + ". Override with a local build? [path / N]:",
+			placeholder: ""
+		});
+		if (isCancel(answer)) throw new ImageOverrideError("Image-override boot prompt cancelled. Re-run with --no-interactive-overrides to suppress, or pass --image-override explicitly.");
+		const value = (answer ?? "").trim();
+		if (!value) continue;
+		const lower = value.toLowerCase();
+		if (lower === "n" || lower === "no") continue;
+		out.set(target, makeEntryFromPath(value, rawFlags.globals, cwd));
+	}
+	return out;
+}
+/**
+* Promote a per-target Dockerfile path + globals into a full
+* {@link ImageOverrideEntry}. Resolves the path against `cwd`, asserts
+* the Dockerfile exists and is a regular file (so the user sees
+* "file not found" up-front rather than mid-`docker build`), and
+* derives the build context as the Dockerfile's parent directory
+* (the v1 simplification — custom contexts are tracked separately).
+*/
+function makeEntryFromPath(raw, globals, cwd) {
+	const abs = isAbsolute(raw) ? raw : resolve(cwd, raw);
+	if (!existsSync(abs)) throw new ImageOverrideError(`--image-override: Dockerfile '${raw}' does not exist (resolved to '${abs}').`);
+	if (!statSync(abs).isFile()) throw new ImageOverrideError(`--image-override: '${raw}' is not a regular file (resolved to '${abs}').`);
+	return {
+		dockerfile: abs,
+		contextDir: dirname(abs),
+		buildArgs: globals.buildArgs,
+		buildSecrets: globals.buildSecrets,
+		...globals.targetStage !== void 0 && { targetStage: globals.targetStage }
+	};
+}
+/**
+* Deterministic local-only image tag for one override entry. Fingerprints
+* the Dockerfile path + its CONTENTS (sha256 of the bytes) + service
+* target + build args / secrets / stage. Including the Dockerfile bytes
+* means an edit to the Dockerfile flips the tag — the rebuild rolling
+* primitive then boots a new container under the bumped tag instead of
+* reusing the old build's cached layers under a stale tag. Two
+* back-to-back runs against an unchanged Dockerfile + flags still hit
+* the same tag so docker's layer cache works.
+*
+* Tag shape: `<resourceNamePrefix>-override-<svcSlug>-<hash>:local`.
+* `:local` is intentionally NOT `:latest` so a `docker pull` on it fails
+* fast (these images are local-build-only by design).
+*
+* Throws on a missing Dockerfile — the caller has already asserted
+* existence in {@link makeEntryFromPath}, so a throw here is a
+* programming error (or the Dockerfile vanished between resolve and
+* build, which is a race the user wants to know about).
+*/
+function buildImageOverrideTag(serviceTarget, entry) {
+	const hash = createHash("sha256");
+	hash.update("dockerfile=");
+	hash.update(entry.dockerfile);
+	hash.update("\0dockerfile-bytes-sha256=");
+	const dockerfileBytesDigest = createHash("sha256").update(readFileSync(entry.dockerfile)).digest("hex");
+	hash.update(dockerfileBytesDigest);
+	hash.update("\0target=");
+	hash.update(serviceTarget);
+	hash.update("\0stage=");
+	hash.update(entry.targetStage ?? "");
+	hash.update("\0args={");
+	for (const [k, v] of entry.buildArgs.entries()) {
+		hash.update(k);
+		hash.update("=");
+		hash.update(v);
+		hash.update(";");
+	}
+	hash.update("}\0secrets={");
+	for (const [k, v] of entry.buildSecrets.entries()) {
+		hash.update(k);
+		hash.update("=");
+		hash.update(v);
+		hash.update(";");
+	}
+	hash.update("}");
+	const svcSlug = serviceTarget.replace(/[^A-Za-z0-9]+/g, "-").slice(0, 24).toLowerCase();
+	return `${getEmbedConfig().resourceNamePrefix}-override-${svcSlug}-${hash.digest("hex").slice(0, 16)}:local`;
+}
+/**
+* Build every overridden image via `docker build`. Returns a per-target
+* `serviceTarget -> localTag` map the emulator threads into each
+* runner's `imageOverrideByContainer` (mutating the resolved service's
+* representative container's image to this tag).
+*
+* Each build runs sequentially (parallelism is left to docker's own
+* BuildKit cache — most overrides share a base image, so a sequential
+* order maximizes cache reuse). On any failure the function rejects
+* with {@link ImageOverrideError}; the emulator surfaces this before
+* any container is started.
+*/
+async function runImageOverrideBuilds(overrides) {
+	const logger = getLogger();
+	const out = /* @__PURE__ */ new Map();
+	for (const [target, entry] of overrides.entries()) {
+		const tag = buildImageOverrideTag(target, entry);
+		const args = [
+			"build",
+			"--tag",
+			tag,
+			"--file",
+			entry.dockerfile
+		];
+		for (const [k, v] of entry.buildArgs.entries()) args.push("--build-arg", `${k}=${v}`);
+		for (const [id, src] of entry.buildSecrets.entries()) args.push("--secret", `id=${id},src=${src}`);
+		if (entry.targetStage !== void 0) args.push("--target", entry.targetStage);
+		args.push(".");
+		logger.info(`Building override image for '${target}' from '${entry.dockerfile}' (tag=${tag})...`);
+		try {
+			await runDockerStreaming(args, {
+				cwd: entry.contextDir,
+				env: { BUILDX_NO_DEFAULT_ATTESTATIONS: "1" }
+			});
+		} catch (err) {
+			const e = err;
+			throw new ImageOverrideError(`docker build failed for --image-override '${target}' (Dockerfile=${entry.dockerfile}): ` + (e.stderr?.trim() || e.message || String(err)));
+		}
+		out.set(target, tag);
+	}
+	return out;
+}
+
 //#endregion
 //#region src/cli/commands/ecs-service-emulator.ts
 /**
@@ -24379,23 +24661,33 @@ async function runEcsServiceEmulator(targets, options, strategy, extraStateProvi
 		};
 		process.on("SIGINT", sigintHandler);
 		process.on("SIGTERM", sigintHandler);
-		for (const pt of perTarget) pt.controller = await bootOneTarget(pt.boot, pt.runState, stacks, options, discovery, skipPull, extraStateProviders, profileCredsFile, frontDoorByService.get(pt.boot.target), strategy.suppressLoadBalancerWarning === true);
+		const imageOverrideTags = await resolveAndBuildImageOverrides({
+			perTarget: perTarget.map((pt) => pt.boot.target),
+			stacks,
+			options,
+			extraStateProviders,
+			logger
+		});
+		for (const pt of perTarget) pt.controller = await bootOneTarget(pt.boot, pt.runState, stacks, options, discovery, skipPull, extraStateProviders, profileCredsFile, frontDoorByService.get(pt.boot.target), strategy.suppressLoadBalancerWarning === true, imageOverrideTags.get(pt.boot.target));
 		if (perTarget.length > 0) {
 			const summary = perTarget.map((pt) => `${pt.controller.service.serviceName} (${pt.controller.activeReplicaCount()} replica(s))`).join(", ");
 			logger.info(`Service(s) running: ${summary}.`);
 		} else logger.info(`Service(s) running: ${frontDoorLambdaRunners.length} Lambda target(s) behind the ALB front-door.`);
 		logEndpointsBanner(perTarget, frontDoorServers, logger);
 		logger.info("Press ^C to shut down.");
-		const watchActive = options.watch === true && strategy.supportsWatch === true;
-		if (watchActive) for (const pt of perTarget) {
+		const uncoveredPinnedTargets = [];
+		for (const pt of perTarget) {
 			const service = pt.controller?.service;
 			if (!service) continue;
 			if (isLocalCdkAssetImage(service)) continue;
+			if (imageOverrideTags.has(pt.boot.target)) continue;
 			const pinnedUri = describePinnedImageUri(service);
 			const uriDisplay = pinnedUri ? `\`${pinnedUri}\`` : "a deployed registry";
-			logger.warn(`'${pt.boot.target}': \`--watch\` will not pick up local source changes — running image is pinned to a deployed registry (${uriDisplay}). To iterate on local source, drop \`--from-cfn-stack\` and switch the CDK app to \`ContainerImage.fromAsset(...)\`.`);
+			logger.warn(`'${pt.boot.target}': running image is pinned to a deployed registry (${uriDisplay}). To iterate on local source, either pass \`--image-override <dockerfile>\` (or \`<service>=<dockerfile>\`) to substitute a local build, or drop \`--from-cfn-stack\` and switch the CDK app to \`ContainerImage.fromAsset(...)\`.`);
+			uncoveredPinnedTargets.push(pt.boot.target);
 		}
-		if (watchActive) {
+		enforceStrictOverrides(options.strictOverrides === true, uncoveredPinnedTargets);
+		if (options.watch === true && strategy.supportsWatch === true) {
 			const watchRoot = process.cwd();
 			const { ignored, shouldTrigger, excludePatterns } = createWatchPredicates({
 				watchRoot,
@@ -24422,6 +24714,7 @@ async function runEcsServiceEmulator(targets, options, strategy, extraStateProvi
 						profileCredsFile,
 						frontDoorByService,
 						changedPaths,
+						imageOverrideTags,
 						logger
 					})).catch((err) => {
 						logger.error(`reloadAllServices threw: ${err instanceof Error ? err.message : String(err)}`);
@@ -24490,7 +24783,7 @@ async function runEcsServiceEmulator(targets, options, strategy, extraStateProvi
 * via the logger so the user can fix the source + save again.
 */
 async function reloadAllServices(args) {
-	const { perTarget, synthesizer, synthOpts, strategy, resolvedTargets, cloudMapIndexByStack, options, discovery, skipPull, extraStateProviders, profileCredsFile, frontDoorByService, changedPaths, logger } = args;
+	const { perTarget, synthesizer, synthOpts, strategy, resolvedTargets, cloudMapIndexByStack, options, discovery, skipPull, extraStateProviders, profileCredsFile, frontDoorByService, changedPaths, imageOverrideTags, logger } = args;
 	let stacks;
 	try {
 		({stacks} = await synthesizer.synthesize(synthOpts));
@@ -24541,7 +24834,7 @@ async function reloadAllServices(args) {
 				reason: "classifier context unavailable; falling back to rebuild"
 			};
 		}
-		if (verdict.kind === "rebuild" && verdict.reason === "target image is not a CDK docker-image asset" && !isLocalCdkAssetImage(controller.service)) {
+		if (verdict.kind === "rebuild" && verdict.reason === "target image is not a CDK docker-image asset" && !isLocalCdkAssetImage(controller.service) && !imageOverrideTags.has(newBoot.target)) {
 			logger.info(`Reload skipped for '${newBoot.target}' (no-op): image pinned to deployed registry; no local rebuild possible.`);
 			continue;
 		}
@@ -24557,6 +24850,7 @@ async function reloadAllServices(args) {
 			frontDoorPools: frontDoorByService.get(newBoot.target),
 			suppressLoadBalancerWarning: strategy.suppressLoadBalancerWarning === true,
 			verdict,
+			...imageOverrideTags.get(newBoot.target) !== void 0 && { imageOverrideTag: imageOverrideTags.get(newBoot.target) },
 			logger
 		});
 	}
@@ -24633,13 +24927,16 @@ async function loadAssetContextForTarget(args) {
 * even when the resolve / roll throws.
 */
 async function rollOneTarget(args) {
-	const { controller, newBoot, stacks, options, discovery, skipPull, extraStateProviders, profileCredsFile, frontDoorPools, suppressLoadBalancerWarning, verdict, logger } = args;
+	const { controller, newBoot, stacks, options, discovery, skipPull, extraStateProviders, profileCredsFile, frontDoorPools, suppressLoadBalancerWarning, verdict, imageOverrideTag, logger } = args;
 	const candidate = pickCandidateStack(parseEcsTarget(newBoot.target).stackPattern, stacks);
 	const stateProvider = createLocalStateProvider(options, candidate?.stackName ?? "", await resolveCfnFallbackRegion(options, candidate?.region), extraStateProviders);
 	try {
 		let resolved;
 		try {
-			resolved = await resolveServiceAndRunnerOpts(newBoot, stacks, options, discovery, skipPull, stateProvider, profileCredsFile, frontDoorPools, suppressLoadBalancerWarning, { quiet: true });
+			resolved = await resolveServiceAndRunnerOpts(newBoot, stacks, options, discovery, skipPull, stateProvider, profileCredsFile, frontDoorPools, suppressLoadBalancerWarning, {
+				quiet: true,
+				...imageOverrideTag !== void 0 && { imageOverrideTag }
+			});
 		} catch (err) {
 			const reason = err instanceof Error ? err.message : String(err);
 			logger.error(`Reload of '${newBoot.target}' was rejected: ${reason}. Existing replica(s) keep serving.`);
@@ -24682,17 +24979,17 @@ async function rollOneTarget(args) {
 		if (stateProvider) stateProvider.dispose();
 	}
 }
-async function bootOneTarget(boot, runState, stacks, options, discovery, skipPull, extraStateProviders, profileCredsFile, frontDoorPools, suppressLoadBalancerWarning) {
+async function bootOneTarget(boot, runState, stacks, options, discovery, skipPull, extraStateProviders, profileCredsFile, frontDoorPools, suppressLoadBalancerWarning, imageOverrideTag) {
 	const candidate = pickCandidateStack(parseEcsTarget(boot.target).stackPattern, stacks);
 	const stateProvider = createLocalStateProvider(options, candidate?.stackName ?? "", await resolveCfnFallbackRegion(options, candidate?.region), extraStateProviders);
 	try {
-		return await runOneTarget(boot, runState, stacks, options, discovery, skipPull, stateProvider, profileCredsFile, frontDoorPools, suppressLoadBalancerWarning);
+		return await runOneTarget(boot, runState, stacks, options, discovery, skipPull, stateProvider, profileCredsFile, frontDoorPools, suppressLoadBalancerWarning, imageOverrideTag);
 	} finally {
 		if (stateProvider) stateProvider.dispose();
 	}
 }
-async function runOneTarget(boot, runState, stacks, options, discovery, skipPull, stateProvider, profileCredsFile, frontDoorPools, suppressLoadBalancerWarning) {
-	const { service, runnerOpts } = await resolveServiceAndRunnerOpts(boot, stacks, options, discovery, skipPull, stateProvider, profileCredsFile, frontDoorPools, suppressLoadBalancerWarning);
+async function runOneTarget(boot, runState, stacks, options, discovery, skipPull, stateProvider, profileCredsFile, frontDoorPools, suppressLoadBalancerWarning, imageOverrideTag) {
+	const { service, runnerOpts } = await resolveServiceAndRunnerOpts(boot, stacks, options, discovery, skipPull, stateProvider, profileCredsFile, frontDoorPools, suppressLoadBalancerWarning, imageOverrideTag !== void 0 ? { imageOverrideTag } : {});
 	return startEcsService(service, runnerOpts, runState);
 }
 /**
@@ -24775,6 +25072,10 @@ async function resolveServiceAndRunnerOpts(boot, stacks, options, discovery, ski
 		containerPath: profileCredsFile.containerPath,
 		profileName: profileCredsFile.profileName
 	};
+	if (opts.imageOverrideTag !== void 0) {
+		const essential = service.task.containers.find((c) => c.essential) ?? service.task.containers[0];
+		if (essential) taskOpts.imageOverrideByContainer = new Map([[essential.name, opts.imageOverrideTag]]);
+	}
 	return {
 		service,
 		runnerOpts: {
@@ -25230,6 +25531,82 @@ async function resolveSharedSidecarCredentials(options) {
 	if (options.profile) return resolveProfileCredentials(options.profile);
 }
 /**
+* Issue #238 — boot-time `--image-override` resolution + build pass.
+* Walks every booted service target's representative container image
+* to identify the pinned set (ECR / public-registry pin — the same
+* anchor `isLocalCdkAssetImage` uses), feeds the pinned set + raw
+* `--image-override` / `--image-build-arg` / `--image-build-secret` /
+* `--image-target` / `--no-interactive-overrides` flag values into
+* the engine ({@link resolveImageOverrides}), then `docker build`s
+* every covered Dockerfile via {@link runImageOverrideBuilds} and
+* returns the per-target local-tag map the boot path threads into
+* each runner.
+*
+* Sequential by design — most overrides share a base image, and the
+* engine's deterministic tag plus BuildKit's layer cache make
+* sequential builds nearly as fast as a parallel fan-out while
+* keeping the build log readable. Throws on a parser / picker /
+* build failure; the outer try/finally tears down what was set up.
+*
+* The boot prompt is fired only when STDIN+STDOUT are TTYs AND
+* `--no-interactive-overrides` is unset; non-TTY contexts silently
+* skip the prompt and rely on whatever the explicit flags resolved.
+*/
+async function resolveAndBuildImageOverrides(args) {
+	const { perTarget, stacks, options, extraStateProviders, logger } = args;
+	const pinnedTargets = [];
+	const pinnedLabels = /* @__PURE__ */ new Map();
+	for (const target of perTarget) {
+		const candidate = pickCandidateStack(parseEcsTarget(target).stackPattern, stacks);
+		const stateProvider = createLocalStateProvider(options, candidate?.stackName ?? "", await resolveCfnFallbackRegion(options, candidate?.region), extraStateProviders);
+		let imageContext;
+		let service;
+		try {
+			imageContext = await buildEcsImageResolutionContext(target, stacks, options, stateProvider);
+			service = resolveEcsServiceTarget(target, stacks, imageContext, { suppressLoadBalancerWarning: true });
+		} catch (err) {
+			logger.debug(`--image-override peek failed for '${target}': ${err instanceof Error ? err.message : String(err)}.`);
+			continue;
+		} finally {
+			if (stateProvider) stateProvider.dispose();
+		}
+		if (!service) continue;
+		if (isLocalCdkAssetImage(service)) continue;
+		pinnedTargets.push(target);
+		const uri = describePinnedImageUri(service);
+		if (uri) pinnedLabels.set(target, uri);
+	}
+	const rawFlags = parseImageOverrideFlags({
+		...options.imageOverride && { imageOverride: options.imageOverride },
+		...options.imageBuildArg && { imageBuildArg: options.imageBuildArg },
+		...options.imageBuildSecret && { imageBuildSecret: options.imageBuildSecret },
+		...options.imageTarget && { imageTarget: options.imageTarget }
+	});
+	if (pinnedTargets.length === 0 && rawFlags.explicit.size === 0 && rawFlags.pickerPaths.length === 0) return /* @__PURE__ */ new Map();
+	const overrides = await resolveImageOverrides({
+		rawFlags,
+		pinnedTargets,
+		pinnedLabels,
+		interactiveBootPrompt: true,
+		noInteractive: options.interactiveOverrides === false
+	});
+	if (overrides.size === 0) return /* @__PURE__ */ new Map();
+	return runImageOverrideBuilds(overrides);
+}
+/**
+* Issue #238 — `--strict-overrides` guard. Extracted so the boot path's
+* fail-fast behavior can be exercised under a unit test without booting
+* the full emulator. Throws {@link LocalStartServiceError} when `strict`
+* is true AND at least one pinned target remains uncovered; otherwise a
+* no-op. The error message names every uncovered target so the user can
+* pass the corresponding `--image-override` mapping.
+*/
+function enforceStrictOverrides(strict, uncoveredPinnedTargets) {
+	if (!strict) return;
+	if (uncoveredPinnedTargets.length === 0) return;
+	throw new LocalStartServiceError(`--strict-overrides set, but ${uncoveredPinnedTargets.length} pinned target(s) remain uncovered: ${uncoveredPinnedTargets.join(", ")}. Pass --image-override <service>=<dockerfile> for each, drop --strict-overrides, or drop --from-cfn-stack to iterate on local CDK assets.`);
+}
+/**
 * Add the CLI options shared by both ECS-service commands (`start-service` and
 * `start-alb`) to a command. The command-specific argument / description and
 * the one unique option (`--host-port` vs `--lb-port`) are added by each
@@ -25245,6 +25622,25 @@ function addCommonEcsServiceOptions(cmd) {
 	cmd.addOption(deprecatedRegionOption);
 	return cmd;
 }
+/**
+* Issue #238 — register the `--image-override` flag family shared by
+* `cdkl start-service` and `cdkl start-alb`. Both commands accept the
+* same six flags; this helper keeps the wording in one place so a
+* future copy edit lands in both surfaces simultaneously.
+*
+* `--image-override` is repeatable (accumulator); `--image-build-arg`
+* and `--image-build-secret` are repeatable too; `--image-target` is a
+* single string (the global multi-stage target); `--no-interactive-overrides`
+* and `--strict-overrides` are booleans. The engine in
+* {@link runEcsServiceEmulator}'s boot path consumes them.
+*
+* Shared between `cdkl start-service` and `cdkl start-alb` and exposed
+* via `cdk-local/internal` so host CLIs (e.g. cdkd) that wrap the same
+* factories inherit the flag set without duplication.
+*/
+function addImageOverrideOptions(cmd) {
+	return cmd.addOption(new Option("--image-override <service=dockerfile or dockerfile...>", "Replace a service target's deployed-registry image with a local `docker build` of the supplied Dockerfile (repeatable). Two forms: <service>=<dockerfile> binds the service explicitly; a bare <dockerfile> opens a multi-select picker against the still-uncovered pinned targets (one Dockerfile across N services). Mix freely. Lets `--from-cfn-stack` still reach real AWS state while you iterate locally on the application container.")).addOption(new Option("--image-build-arg <KEY=VAL...>", "Global `docker build --build-arg KEY=VAL` pair applied to every --image-override build (repeatable). Lets a CDK Dockerfile that branches on an ARG (env target, base image tag, package mirror) honor that ARG locally without editing the Dockerfile.")).addOption(new Option("--image-build-secret <id=src...>", "Global `docker build --secret id=<id>,src=<src>` entry applied to every --image-override build (repeatable). Enables `RUN --mount=type=secret,id=<id>` in the Dockerfile — the standard private-registry / npm-token recipe (e.g. `--image-build-secret npmrc=./.npmrc`).")).addOption(new Option("--image-target <stage>", "Global `docker build --target=<stage>` forwarded to every --image-override build. Useful when the Dockerfile is multi-stage and you want to stop at a specific intermediate stage.")).addOption(new Option("--no-interactive-overrides", "Suppress the interactive boot prompt that walks each pinned target asking for a Dockerfile path, and the multi-select prompt fired by `--image-override <dockerfile>` (picker form). Useful for CI / scripted invocations.")).addOption(new Option("--strict-overrides", "Fail fast at boot when any pinned target remains uncovered after `--image-override` + the boot prompt resolve. Off by default; the boot WARN per uncovered pinned target still fires regardless.").default(false));
+}
 
 //#endregion
 //#region src/cli/commands/local-start-service.ts
@@ -25315,6 +25711,7 @@ function createLocalStartServiceCommand(opts = {}) {
 * for that contract to live.
 */
 function addStartServiceSpecificOptions(cmd) {
+	addImageOverrideOptions(cmd);
 	return cmd.addOption(new Option("--host-port <containerPort=hostPort...>", "Publish a container port on a specific host port (e.g. 80=8080); repeatable. Default: host port == container port. Use this on macOS to map a privileged container port (< 1024) to a non-privileged host port and avoid the Docker Desktop admin-password prompt. (Single-replica services only — multi-replica services do not publish host ports.)")).addOption(new Option("--watch", "Hot-reload: re-synth + per-replica reload when the CDK source changes (honors cdk.json watch.include/exclude; cdk.out, node_modules, .git are always excluded). A per-firing classifier picks the per-replica primitive: source-only edits on interpreted-language handlers (Node/Python/Ruby/shell) take a bind-mount FAST PATH (`docker cp` the new source into each replica + `docker restart`; no rebuild). Dockerfile / dependency manifest / compiled-language source / ambiguous edits fall through to the rebuild rolling primitive — boot a shadow under a bumped generation suffix, wait for its container port to accept a TCP connection, atomically swap Service-Connect / Cloud Map registrations, then retire the old container. Either path rolls one replica at a time, so peer services see zero connection refusals across the reload even on multi-replica services. Off by default; existing replica(s) keep serving when synth fails mid-reload.").default(false));
 }
 
@@ -26168,6 +26565,7 @@ function createLocalStartAlbCommand(opts = {}) {
 * clusters. Chainable: returns `cmd`.
 */
 function addAlbSpecificOptions(cmd) {
+	addImageOverrideOptions(cmd);
 	return cmd.addOption(new Option("--lb-port <listenerPort=hostPort...>", "Bind the local front-door on a specific host port (e.g. 80=8080); repeatable. Default: host port == ALB listener port. Use this on macOS to remap a privileged listener port (< 1024) to a non-privileged host port.")).addOption(new Option("--tls", "Terminate TLS locally for cloud-HTTPS listeners. Default: a cloud-HTTPS listener is served over plain HTTP locally (X-Forwarded-Proto: https is preserved so the upstream app still sees the deployed listener protocol). Implied by --tls-cert / --tls-key. Use this when local-dev cookies need Secure / SameSite=None, when the upstream app inspects TLS metadata, or for mTLS / SNI testing — otherwise plain HTTP is friendlier (no self-signed cert warnings in curl / browser).")).addOption(new Option("--tls-cert <path>", "PEM-encoded server certificate for HTTPS front-door listeners. Implies --tls. Must be set together with --tls-key. Pass --tls alone (without --tls-cert / --tls-key) to auto-generate a self-signed cert (cached under $XDG_CACHE_HOME/cdk-local/alb-https/, default ~/.cache/cdk-local/alb-https/); requires openssl on PATH. The deployed Listener Certificates[] are NOT fetched (ACM private keys are not retrievable by design). The auto-generated cert lists DNS:localhost,IP:127.0.0.1 as SubjectAltName, so a client validating a non-loopback --container-host will fail the SAN check — pass --tls-cert / --tls-key with a SAN covering that host instead.")).addOption(new Option("--tls-key <path>", "PEM-encoded server private key matching --tls-cert. Implies --tls. Must be set together with --tls-cert.")).addOption(new Option("--no-verify-auth", "Disable local enforcement of authenticate-cognito / authenticate-oidc actions. Every request is served as if the auth check passed. Useful for local dev where you do not want to mint a Bearer token at all.")).addOption(new Option("--bearer-token <jwt>", "Default Bearer JWT injected as Authorization: Bearer <jwt> when the inbound request has none. Verified against the same JWKS / OIDC discovery URL the deployed ALB would (signature + iss + aud + exp). Local-dev convenience; cookie pass-through (AWSELBAuthSessionCookie-*) also works.")).addOption(new Option("--watch", "Hot-reload: re-synth + per-replica reload of every ECS service behind the ALB when the CDK source changes (honors cdk.json watch.include/exclude; cdk.out, node_modules, .git are always excluded). A per-firing classifier picks the per-replica primitive: source-only edits on interpreted-language handlers (Node/Python/Ruby/shell) take a bind-mount FAST PATH (`docker cp` the new source into each replica + `docker restart`; no rebuild, front-door pool entry unchanged since the IP/port are preserved). Dockerfile / dependency manifest / compiled-language source / ambiguous edits fall through to the rebuild rolling primitive — boot a shadow under a bumped generation suffix, wait for its container port to accept a TCP connection, atomically register it in the front-door pool, then drop the old entry and retire the old container. Either path rolls one replica at a time, so a continuous external request stream against the listener port sees zero connection refusals across the reload. The host front-door (TLS, JWKS cache, Lambda-target containers, listener sockets) stays up across the reload. Lambda target groups behind the ALB are a no-op on reload (the warm RIE container keeps its boot-time image). Off by default; existing replica(s) keep serving when synth fails mid-reload.").default(false));
 }
 
@@ -26264,5 +26662,5 @@ function addListSpecificOptions(cmd) {
 }
 
 //#endregion
-export { invokeRequestAuthorizer as $, addInvokeSpecificOptions as $t, attachContainerLogStreamer as A, discoverRoutes as An, buildCorsConfigFromCloudFrontChain as At, buildStageMap as B, resolveAgentCoreTarget as Bn, mcpInvokeOnce as Bt, buildCloudMapIndex as C, resolveWatchConfig as Cn, createJwksCache as Ct, getContainerNetworkIp as D, discoverWebSocketApis as Dn, attachAuthorizers as Dt, SOFT_RELOAD_COMPLETION_LOG_SUFFIX as E, listTargets as En, verifyJwtViaDiscovery as Et, createWatchPredicates as F, AGENTCORE_HTTP_PROTOCOL as Fn, A2A_PATH as Ft, readMtlsMaterialsFromDisk as G, LocalInvokeBuildError as Gn, invokeAgentCore as Gt, filterRoutesByApiIdentifier as H, formatStateRemedy as Hn, AGENTCORE_SIGV4_SERVICE as Ht, resolveApiTargetSubset as I, AGENTCORE_MCP_PROTOCOL as In, a2aInvokeOnce as It, resolveServiceIntegrationParameters as J, SUPPORTED_CODE_RUNTIMES as Jt, startApiServer as K, waitForAgentCorePing as Kt, createAuthorizerCache as L, AGENTCORE_RUNTIME_TYPE as Ln, MCP_CONTAINER_PORT as Lt, createLocalInvokeAgentCoreCommand as M, resolveLambdaArnIntrinsic as Mn, matchPreflight as Mt, addStartApiSpecificOptions as N, AGENTCORE_A2A_PROTOCOL as Nn, invokeAgentCoreWs as Nt, addRunTaskSpecificOptions as O, discoverWebSocketApisOrThrow as On, applyCorsResponseHeaders as Ot, createLocalStartApiCommand as P, AGENTCORE_AGUI_PROTOCOL as Pn, A2A_CONTAINER_PORT as Pt, evaluateCachedLambdaPolicy as Q, toCmdArgv as Qt, createFileWatcher as R, AgentCoreResolutionError as Rn, MCP_PATH as Rt, isLocalCdkAssetImage as S, resolveSsmParameters as Sn, buildJwksUrlFromIssuer as St, classifySourceChange as T, countTargets as Tn, verifyJwtAuthorizer as Tt, filterRoutesByApiIdentifiers as U, substituteImagePlaceholders as Un, signAgentCoreInvocation as Ut, availableApiIdentifiers as V, derivePseudoParametersFromRegion as Vn, parseSseForJsonRpc as Vt, groupRoutesByServer as W, tryResolveImageFnJoin as Wn, AGENTCORE_SESSION_ID_HEADER as Wt, buildMethodArn as X, computeCodeImageTag as Xt, defaultCredentialsLoader as Y, buildAgentCoreCodeImage as Yt, computeRequestIdentityHash as Z, renderCodeDockerfile as Zt, parseMaxTasks as _, resolveCfnFallbackRegion as _n, parseConnectionsPath as _t, albStrategy as a, resolveRuntimeImage as an, buildRestV1Event as at, runEcsServiceEmulator as b, CfnLocalStateProvider as bn, buildMessageEvent as bt, resolveAlbTarget as c, substituteAgainstStateAsync as cn, selectIntegrationResponse as ct, addStartServiceSpecificOptions as d, resolveEnvVars as dn, HOST_GATEWAY_MIN_VERSION as dt, createLocalInvokeCommand as en, invokeTokenAuthorizer as et, createLocalStartServiceCommand as f, materializeLayerFromArn as fn, probeHostGatewaySupport as ft, buildEcsImageResolutionContext as g, rejectExplicitCfnStackWithMultipleStacks as gn, handleConnectionsRequest as gt, addCommonEcsServiceOptions as h, isCfnFlagPresent as hn, buildMgmtEndpointEnvUrl as ht, addAlbSpecificOptions as i, resolveRuntimeFileExtension as in, buildHttpApiV2Event as it, addInvokeAgentCoreSpecificOptions as j, pickRefLogicalId as jn, isFunctionUrlOacFronted as jt, createLocalRunTaskCommand as k, parseSelectionExpressionPath as kn, buildCorsConfigByApiId as kt, isApplicationLoadBalancer as l, substituteEnvVarsFromState as ln, tryParseStatus as lt, MAX_TASKS_SUBNET_RANGE_CAP as m, createLocalStateProvider as mn, ConnectionRegistry as mt, createLocalListCommand as n, buildContainerImage as nn, translateLambdaResponse as nt, createLocalStartAlbCommand as o, EcsTaskResolutionError as on, evaluateResponseParameters as ot, serviceStrategy as p, LocalStateSourceError as pn, bufferToBody as pt, resolveSelectionExpression as q, downloadAndExtractS3Bundle as qt, formatTargetListing as r, resolveRuntimeCodeMountPath as rn, applyAuthorizerOverlay as rt, parseLbPortOverrides as s, substituteAgainstState as sn, pickResponseTemplate as st, addListSpecificOptions as t, architectureToPlatform as tn, matchRoute as tt, resolveAlbFrontDoor as u, substituteEnvVarsFromStateAsync as un, VtlEvaluationError as ut, parseRestartPolicy as v, resolveCfnRegion as vn, buildConnectEvent as vt, CloudMapRegistry as w, resolveSingleTarget as wn, verifyCognitoJwt as wt, describePinnedImageUri as x, collectSsmParameterRefs as xn, buildCognitoJwksUrl as xt, resolveSharedSidecarCredentials as y, resolveCfnStackName as yn, buildDisconnectEvent as yt, attachStageContext as z, pickAgentCoreCandidateStack as zn, MCP_PROTOCOL_VERSION as zt };
-//# sourceMappingURL=local-list-BS463YYd.js.map
+export { resolveSelectionExpression as $, downloadAndExtractS3Bundle as $t, CloudMapRegistry as A, resolveSingleTarget as An, verifyCognitoJwt as At, createLocalStartApiCommand as B, AGENTCORE_AGUI_PROTOCOL as Bn, A2A_CONTAINER_PORT as Bt, buildImageOverrideTag as C, resolveCfnFallbackRegion as Cn, parseConnectionsPath as Ct, describePinnedImageUri as D, collectSsmParameterRefs as Dn, buildCognitoJwksUrl as Dt, runImageOverrideBuilds as E, CfnLocalStateProvider as En, buildMessageEvent as Et, createLocalRunTaskCommand as F, parseSelectionExpressionPath as Fn, buildCorsConfigByApiId as Ft, attachStageContext as G, pickAgentCoreCandidateStack as Gn, MCP_PROTOCOL_VERSION as Gt, resolveApiTargetSubset as H, AGENTCORE_MCP_PROTOCOL as Hn, a2aInvokeOnce as Ht, attachContainerLogStreamer as I, discoverRoutes as In, buildCorsConfigFromCloudFrontChain as It, filterRoutesByApiIdentifier as J, formatStateRemedy as Jn, AGENTCORE_SIGV4_SERVICE as Jt, buildStageMap as K, resolveAgentCoreTarget as Kn, mcpInvokeOnce as Kt, addInvokeAgentCoreSpecificOptions as L, pickRefLogicalId as Ln, isFunctionUrlOacFronted as Lt, SOFT_RELOAD_COMPLETION_LOG_SUFFIX as M, listTargets as Mn, verifyJwtViaDiscovery as Mt, getContainerNetworkIp as N, discoverWebSocketApis as Nn, attachAuthorizers as Nt, isLocalCdkAssetImage as O, resolveSsmParameters as On, buildJwksUrlFromIssuer as Ot, addRunTaskSpecificOptions as P, discoverWebSocketApisOrThrow as Pn, applyCorsResponseHeaders as Pt, startApiServer as Q, waitForAgentCorePing as Qt, createLocalInvokeAgentCoreCommand as R, resolveLambdaArnIntrinsic as Rn, matchPreflight as Rt, ImageOverrideError as S, rejectExplicitCfnStackWithMultipleStacks as Sn, handleConnectionsRequest as St, resolveImageOverrides as T, resolveCfnStackName as Tn, buildDisconnectEvent as Tt, createAuthorizerCache as U, AGENTCORE_RUNTIME_TYPE as Un, MCP_CONTAINER_PORT as Ut, createWatchPredicates as V, AGENTCORE_HTTP_PROTOCOL as Vn, A2A_PATH as Vt, createFileWatcher as W, AgentCoreResolutionError as Wn, MCP_PATH as Wt, groupRoutesByServer as X, tryResolveImageFnJoin as Xn, AGENTCORE_SESSION_ID_HEADER as Xt, filterRoutesByApiIdentifiers as Y, substituteImagePlaceholders as Yn, signAgentCoreInvocation as Yt, readMtlsMaterialsFromDisk as Z, LocalInvokeBuildError as Zn, invokeAgentCore as Zt, buildEcsImageResolutionContext as _, resolveEnvVars as _n, HOST_GATEWAY_MIN_VERSION as _t, albStrategy as a, addInvokeSpecificOptions as an, invokeRequestAuthorizer as at, resolveSharedSidecarCredentials as b, createLocalStateProvider as bn, ConnectionRegistry as bt, resolveAlbTarget as c, buildContainerImage as cn, translateLambdaResponse as ct, addStartServiceSpecificOptions as d, resolveRuntimeImage as dn, buildRestV1Event as dt, SUPPORTED_CODE_RUNTIMES as en, resolveServiceIntegrationParameters as et, createLocalStartServiceCommand as f, EcsTaskResolutionError as fn, evaluateResponseParameters as ft, addImageOverrideOptions as g, substituteEnvVarsFromStateAsync as gn, VtlEvaluationError as gt, addCommonEcsServiceOptions as h, substituteEnvVarsFromState as hn, tryParseStatus as ht, addAlbSpecificOptions as i, toCmdArgv as in, evaluateCachedLambdaPolicy as it, classifySourceChange as j, countTargets as jn, verifyJwtAuthorizer as jt, buildCloudMapIndex as k, resolveWatchConfig as kn, createJwksCache as kt, isApplicationLoadBalancer as l, resolveRuntimeCodeMountPath as ln, applyAuthorizerOverlay as lt, MAX_TASKS_SUBNET_RANGE_CAP as m, substituteAgainstStateAsync as mn, selectIntegrationResponse as mt, createLocalListCommand as n, computeCodeImageTag as nn, buildMethodArn as nt, createLocalStartAlbCommand as o, createLocalInvokeCommand as on, invokeTokenAuthorizer as ot, serviceStrategy as p, substituteAgainstState as pn, pickResponseTemplate as pt, availableApiIdentifiers as q, derivePseudoParametersFromRegion as qn, parseSseForJsonRpc as qt, formatTargetListing as r, renderCodeDockerfile as rn, computeRequestIdentityHash as rt, parseLbPortOverrides as s, architectureToPlatform as sn, matchRoute as st, addListSpecificOptions as t, buildAgentCoreCodeImage as tn, defaultCredentialsLoader as tt, resolveAlbFrontDoor as u, resolveRuntimeFileExtension as un, buildHttpApiV2Event as ut, parseMaxTasks as v, materializeLayerFromArn as vn, probeHostGatewaySupport as vt, parseImageOverrideFlags as w, resolveCfnRegion as wn, buildConnectEvent as wt, runEcsServiceEmulator as x, isCfnFlagPresent as xn, buildMgmtEndpointEnvUrl as xt, parseRestartPolicy as y, LocalStateSourceError as yn, bufferToBody as yt, addStartApiSpecificOptions as z, AGENTCORE_A2A_PROTOCOL as zn, invokeAgentCoreWs as zt };
+//# sourceMappingURL=local-list-BOmsOq0r.js.map