@go-to-k/cdkd 0.147.0 → 0.147.2

package/dist/cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { _ as withSkipPrefix, a as runDockerStreaming, c as getLogger, d as getLiveRenderer, f as PATTERN_B_NAME_PROPERTIES, g as generateResourceNameWithFallback, h as generateResourceName, i as runDockerForeground, n as formatDockerLoginError, p as PATTERN_B_RESOURCE_TYPES, r as getDockerCmd, u as runStackBuffered, v as withStackName } from "./docker-cmd-EtWSTAje.js";
-import { A as AssetPublisher, B as resolveStateBucketWithDefault, C as applyRoleArnIfSet, D as LockManager, E as TemplateParser, F as getDefaultStateBucketName, G as MIGRATE_TMP_PREFIX, H as warnDeprecatedNoPrefixCliFlag, I as getLegacyStateBucketName, J as AssemblyReader, K as findLargeInlineResources, L as resolveApp, M as WorkGraph, N as buildDockerImage, O as S3StateBackend, P as Synthesizer, Q as CdkdError, R as resolveCaptureObservedState, S as IntrinsicFunctionResolver, T as DagBuilder, U as CFN_TEMPLATE_BODY_LIMIT, V as resolveStateBucketWithDefaultAndSource, W as CFN_TEMPLATE_URL_LIMIT, X as resolveBucketRegion, _ as normalizeAwsTagsToCfn, _t as normalizeAwsError, a as withRetry, at as MissingCdkCliError, b as CloudControlProvider, c as cyan, ct as ResourceTimeoutError, d as red, dt as StackHasActiveImportsError, f as yellow, ft as StackTerminationProtectionError, g as matchesCdkPath, h as CDK_PATH_TAG, i as withResourceDeadline, j as stringifyValue, k as shouldRetainResource, l as gray, lt as ResourceUpdateNotSupportedError, m as collectInlinePolicyNamesManagedBySiblings, n as DEFAULT_RESOURCE_WARN_AFTER_MS, nt as LocalMigrateError, o as IMPLICIT_DELETE_DEPENDENCIES, ot as PartialFailureError, p as IAMRoleProvider, q as uploadCfnTemplate, r as DeployEngine, rt as LocalStartServiceError, s as bold, st as ProvisioningError, t as DEFAULT_RESOURCE_TIMEOUT_MS, tt as LocalInvokeBuildError, u as green, ut as RouteDiscoveryError, v as resolveExplicitPhysicalId, vt as withErrorHandling, w as DiffCalculator, x as assertRegionMatch, y as ProviderRegistry, z as resolveSkipPrefix } from "./deploy-engine-DjnWyAAc.js";
+import { A as AssetPublisher, B as resolveStateBucketWithDefault, C as applyRoleArnIfSet, D as LockManager, E as TemplateParser, F as getDefaultStateBucketName, G as MIGRATE_TMP_PREFIX, H as warnDeprecatedNoPrefixCliFlag, I as getLegacyStateBucketName, J as AssemblyReader, K as findLargeInlineResources, L as resolveApp, M as WorkGraph, N as buildDockerImage, O as S3StateBackend, P as Synthesizer, Q as CdkdError, R as resolveCaptureObservedState, S as IntrinsicFunctionResolver, T as DagBuilder, U as CFN_TEMPLATE_BODY_LIMIT, V as resolveStateBucketWithDefaultAndSource, W as CFN_TEMPLATE_URL_LIMIT, X as resolveBucketRegion, _ as normalizeAwsTagsToCfn, a as withRetry, at as MissingCdkCliError, b as CloudControlProvider, c as cyan, ct as ProvisioningError, d as red, dt as RouteDiscoveryError, f as yellow, ft as StackHasActiveImportsError, g as matchesCdkPath, h as CDK_PATH_TAG, i as withResourceDeadline, j as stringifyValue, k as shouldRetainResource, l as gray, lt as ResourceTimeoutError, m as collectInlinePolicyNamesManagedBySiblings, n as DEFAULT_RESOURCE_WARN_AFTER_MS, nt as LocalMigrateError, o as IMPLICIT_DELETE_DEPENDENCIES, ot as NestedStackChildDirectDestroyError, p as IAMRoleProvider, pt as StackTerminationProtectionError, q as uploadCfnTemplate, r as DeployEngine, rt as LocalStartServiceError, s as bold, st as PartialFailureError, t as DEFAULT_RESOURCE_TIMEOUT_MS, tt as LocalInvokeBuildError, u as green, ut as ResourceUpdateNotSupportedError, v as resolveExplicitPhysicalId, vt as normalizeAwsError, w as DiffCalculator, x as assertRegionMatch, y as ProviderRegistry, yt as withErrorHandling, z as resolveSkipPrefix } from "./deploy-engine-CRxNgcqJ.js";
 import { a as setAwsClients, i as resetAwsClients, r as getAwsClients, t as AwsClients } from "./aws-clients-BF03Alpe.js";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { createHash, createHmac, createPublicKey, createVerify, randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
@@ -33592,6 +33592,7 @@ async function destroyCommand(stackArgs, options) {
 			}
 		} else throw new Error("Could not determine which stacks belong to this app. Specify stack names explicitly, use --all, or ensure --app / cdk.json is configured.");
 		const stackPatterns = stackArgs.length > 0 ? stackArgs : options.stack ? [options.stack] : [];
+		let totalErrors = 0;
 		let stackNames;
 		if (options.all) stackNames = candidateStacks.map((s) => s.stackName);
 		else if (stackPatterns.length > 0) stackNames = matchStacks(candidateStacks, stackPatterns).map((s) => s.stackName);
@@ -33601,6 +33602,21 @@ async function destroyCommand(stackArgs, options) {
 			return;
 		} else throw new Error(`Multiple stacks found: ${candidateStacks.map(describeStack).join(", ")}. Specify stack name(s) or use --all`);
 		if (stackNames.length === 0) {
+			if (stackPatterns.length > 0) {
+				const allStateNamesSet = new Set(allStateRefs.map((r) => r.stackName));
+				for (const pattern of stackPatterns) {
+					if (pattern.includes("*") || pattern.includes("?") || pattern.includes("/")) continue;
+					if (!allStateNamesSet.has(pattern)) continue;
+					const refRegion = allStateRefs.find((r) => r.stackName === pattern)?.region ?? region;
+					const stateOnlyResult = await stateBackend.getState(pattern, refRegion);
+					if (stateOnlyResult?.state.parentStack) {
+						const err = new NestedStackChildDirectDestroyError(pattern, stateOnlyResult.state.parentStack, stateOnlyResult.state.parentLogicalId);
+						logger.error(`  ✗ ${err.message}`);
+						totalErrors++;
+					}
+				}
+				if (totalErrors > 0) throw new PartialFailureError(`Destroy completed with ${totalErrors} resource error(s). State preserved — inspect 'cdkd state show <stack>' and re-run 'cdkd destroy' to retry.`);
+			}
 			logger.info("No matching stacks found in state");
 			return;
 		}
@@ -33612,7 +33628,6 @@ async function destroyCommand(stackArgs, options) {
 			arr.push(ref);
 			stateRefsByName.set(ref.stackName, arr);
 		}
-		let totalErrors = 0;
 		for (const stackName of stackNames) {
 			logger.info(`\nPreparing to destroy stack: ${stackName}`);
 			const refs = stateRefsByName.get(stackName) ?? [];
@@ -33643,6 +33658,12 @@ async function destroyCommand(stackArgs, options) {
 				logger.warn(`No state found for stack ${stackName}, skipping`);
 				continue;
 			}
+			if (stateResult.state.parentStack) {
+				const err = new NestedStackChildDirectDestroyError(stackName, stateResult.state.parentStack, stateResult.state.parentLogicalId);
+				logger.error(`  ✗ ${err.message}`);
+				totalErrors++;
+				continue;
+			}
 			const result = await withNestedStackContext({
 				stateBackend,
 				lockManager,
@@ -36626,9 +36647,14 @@ async function injectRetainPoliciesRecursiveInternal(templateBody, cfnStackName,
 	};
 }
 /**
-* Recursive variant of {@link getCloudFormationResourceMapping} that returns
-* the full nested-stack tree rooted at `rootStackName`. For each
-* `AWS::CloudFormation::Stack` row in the root's resources, recursively
+* Walk a CloudFormation stack and every nested child recursively, returning
+* the full {@link CfnStackResourceTree} rooted at `rootStackName`. Used by
+* `cdkd import --migrate-from-cloudformation` to drive BOTH per-child state
+* writes AND the recursive `injectRetainPoliciesRecursive` walk — both
+* consumers share this single `DescribeStackResources` tree so an
+* arbitrarily-deep nesting only costs one round-trip per stack.
+*
+* For each `AWS::CloudFormation::Stack` row in the root's resources, recursively
 * calls `DescribeStackResources(<child ARN>)` (AWS accepts the ARN as
 * `StackName`) to populate the child node, and so on to arbitrary depth.
 *
@@ -39477,6 +39503,7 @@ function extractTaskDefinitionProperties(stack, logicalId, resource, context) {
 	if (rawNetworkMode === "bridge" || rawNetworkMode === "awsvpc" || rawNetworkMode === "host" || rawNetworkMode === "none") networkMode = rawNetworkMode;
 	else throw new EcsTaskResolutionError(`Task definition '${logicalId}' has unsupported NetworkMode '${rawNetworkMode}'. Supported values: bridge / awsvpc / host / none.`);
 	if (networkMode === "awsvpc") warnings.push(`NetworkMode 'awsvpc' on '${logicalId}' is mapped to docker bridge locally — docker cannot emulate ENI-per-task. AWS SDK calls still reach public endpoints via the developer network.`);
+	if (props["ProxyConfiguration"]) warnings.push(`Task definition '${logicalId}' declares 'ProxyConfiguration' (custom Envoy / App Mesh bootstrap), which is NOT honored by 'cdkd local start-service' / 'cdkd local run-task' in v1. Local execution will run without the configured proxy. See design doc § 2 for the rationale.`);
 	const resources = stack.template.Resources ?? {};
 	const subContext = buildSubstitutionContextFromImageContext(context);
 	const taskRoleArn = resolveRoleArn(props["TaskRoleArn"], resources, subContext);
@@ -52045,7 +52072,7 @@ function extractServiceProperties(stack, serviceLogicalId, resource, stacks, con
 		desiredCount,
 		healthCheckGracePeriodSeconds,
 		task,
-		serviceRegistries: extractServiceRegistries(props["ServiceRegistries"]),
+		serviceRegistries: extractServiceRegistries(props["ServiceRegistries"], serviceLogicalId, warnings),
 		warnings
 	};
 	if (serviceConnect) out.serviceConnect = serviceConnect;
@@ -52118,8 +52145,16 @@ function extractServiceConnect(raw, task) {
 * canonical `Fn::GetAtt: [<CloudMapServiceLogicalId>, 'Arn']` shape;
 * cdkd surfaces the logical id (the AWS-side ARN is irrelevant
 * locally — the registry is in-process).
+*
+* Issue #544 — entries with a literal-string `RegistryArn` (rare
+* locally — would imply the user bound to an existing Cloud Map
+* service deployed out-of-band) are skipped with a warning, since the
+* in-process registry cannot resolve an external Cloud Map service
+* back to its `(namespace, name)` pair. Pre-fix this was a silent
+* `continue` and the user got no feedback about why the registration
+* didn't show up.
 */
-function extractServiceRegistries(raw) {
+function extractServiceRegistries(raw, serviceLogicalId, warnings) {
 	if (!Array.isArray(raw)) return [];
 	const out = [];
 	for (const entry of raw) {
@@ -52127,7 +52162,10 @@ function extractServiceRegistries(raw) {
 		const e = entry;
 		const registryArn = e["RegistryArn"];
 		let cloudMapServiceLogicalId;
-		if (typeof registryArn === "string") continue;
+		if (typeof registryArn === "string") {
+			warnings.push(`ECS Service '${serviceLogicalId}' ServiceRegistries[] entry has a literal-string RegistryArn ('${registryArn}'); cdkd cannot resolve external Cloud Map services locally. Skipping this registration; peer services will not discover this endpoint through the in-process registry. Use Fn::GetAtt: [<CloudMapServiceLogicalId>, "Arn"] instead so cdkd can resolve the namespace + service name from the synthesized template.`);
+			continue;
+		}
 		if (registryArn && typeof registryArn === "object" && !Array.isArray(registryArn)) {
 			const getAtt = registryArn["Fn::GetAtt"];
 			if (Array.isArray(getAtt) && typeof getAtt[0] === "string") cloudMapServiceLogicalId = getAtt[0];
@@ -52308,6 +52346,38 @@ function backoffDelayMs(restartCount) {
 	return Math.min(1e3 * Math.pow(2, Math.min(restartCount, 10)), 3e4);
 }
 /**
+* Maximum number of replica indices the per-replica subnet allocator
+* can serve without modulo-wrap collision. The allocator below walks
+* the link-local /24 range `169.254.170.0..169.254.253.0` (84 octets)
+* and **skips 171** because that octet is owned by the shared-service
+* network in design § 5 Option A (see `SHARED_SVC_SUBNET_OCTET`), so
+* the usable count is 83. The CLI's `--max-tasks` parser enforces this
+* cap before any boot work fires.
+*/
+const SUBNET_ALLOCATOR_RANGE = 83;
+/**
+* Defensive per-replica subnet octet allocator (Issue #544). Only used
+* when callers bypass the CLI's `sharedNetwork` construction — i.e.
+* test paths that hand-build `ServiceRunnerOptions.discovery` without
+* `sharedNetwork`, or the bare `cdkd local run-task`-shaped path that
+* runs one network per task. Production `cdkd local start-service`
+* runs always go through the shared network (design § 5 Option A) so
+* this allocator is unreachable in the standard path.
+*
+* Returns the second-from-last octet of the per-replica /24 (170 →
+* `169.254.170.0/24`). Walks the 83-slot output range
+* `[170, 172, 173, ..., 253]` — 171 is intentionally **skipped**
+* because it's reserved for the shared-service network sidecar
+* (`SHARED_SVC_SUBNET_OCTET`), and assigning a per-replica network
+* the same /24 would have docker reject the duplicate-subnet
+* `network create` with the cryptic "Pool overlaps with other one on
+* this address space" error.
+*/
+function pickSubnetOctet(index) {
+	const candidate = 170 + (index % 83 + 83) % 83;
+	return candidate < 171 ? candidate : candidate + 1;
+}
+/**
 * Decide whether a replica that just exited should restart. Pure-
 * functional so the watcher loop's policy is easy to unit-test.
 */
@@ -52486,7 +52556,7 @@ async function bootReplica(service, options, instance) {
 		...options.taskOptions,
 		cluster: perReplicaCluster,
 		detach: true,
-		...sharedNetwork ? { existingNetwork: sharedNetwork } : { subnetOctet: 170 + instance.index % 84 },
+		...sharedNetwork ? { existingNetwork: sharedNetwork } : { subnetOctet: pickSubnetOctet(instance.index) },
 		...addHostFlags.length > 0 ? { addHostFlags } : {},
 		...networkAliasesByContainer.size > 0 ? { networkAliasesByContainer } : {}
 	};
@@ -52688,8 +52758,13 @@ var CloudMapRegistry = class {
 	/**
 	* Map<alias, fqdn> — secondary index for ClientAlias short forms.
 	* Multiple aliases can point at the same fqdn; one alias only points
-	* at one fqdn (last write wins, with a warn surfaced by the resolver
-	* when a cross-namespace collision is detected — see design §O6).
+	* at one fqdn. **First-wins on collision** — consistent with design
+	* §O6's namespace-level first-wins rule for `PrivateDnsNamespace`. A
+	* collision (two services declaring the same `ClientAlias.DnsName`)
+	* emits a `logger.warn` so users can debug "why does
+	* `wget http://api/` reach service B instead of service A" without
+	* silently shadowing the prior binding. Idempotent re-register of
+	* the same `(alias, targetFqdn)` pair is a no-op and does NOT warn.
 	*/
 	aliasIndex = /* @__PURE__ */ new Map();
 	/**
@@ -52725,8 +52800,13 @@ var CloudMapRegistry = class {
 	* suffix). Cloud Map / Service Connect does NOT auto-create such
 	* aliases — they're populated by `ClientAliases[].DnsName` entries in
 	* the consumer service's `ServiceConnectConfiguration`. Aliases are
-	* scoped per-CLI-invocation and last-write-wins on collision (the
-	* resolver surfaces a `warn` when this happens — see §O6).
+	* scoped per-CLI-invocation and **first-wins on collision** —
+	* consistent with design §O6's namespace-level first-wins rule. The
+	* first registration sticks; later attempts to bind the same alias
+	* to a different fqdn are ignored and a `logger.warn` is emitted so
+	* users can debug "why does `wget http://api/` reach service B
+	* instead of service A". Re-registering the same `(alias,
+	* targetFqdn)` pair is idempotent and does NOT warn.
 	*
 	* @param alias The bare discovery name (e.g. `orders` for an alias to
 	*              `orders.cdkd-local.local`).
@@ -52736,6 +52816,12 @@ var CloudMapRegistry = class {
 	registerAlias(alias, targetFqdn) {
 		if (!alias) throw new Error("CloudMapRegistry.registerAlias: alias must be a non-empty string.");
 		if (!targetFqdn) throw new Error("CloudMapRegistry.registerAlias: targetFqdn must be a non-empty string.");
+		const existing = this.aliasIndex.get(alias);
+		if (existing !== void 0) {
+			if (existing === targetFqdn) return;
+			getLogger().child("cloud-map-registry").warn(`ClientAlias DnsName collision: '${alias}' was already mapped to '${existing}'; keeping first-wins binding and ignoring new mapping to '${targetFqdn}'. Likely cause: two Service Connect services declared the same ClientAlias.DnsName.`);
+			return;
+		}
 		this.aliasIndex.set(alias, targetFqdn);
 	}
 	/**
@@ -52981,6 +53067,7 @@ async function localStartServiceCommand(targets, options) {
 	const logger = getLogger();
 	if (options.verbose) logger.setLevel("debug");
 	warnIfDeprecatedRegion(options);
+	const skipPull = options.pull === false;
 	if (!targets || targets.length === 0) throw new LocalStartServiceError("cdkd local start-service requires at least one <target>. Pass one or more service paths like 'Stack/Orders' 'Stack/Frontend'.");
 	const perTarget = targets.map((t) => ({
 		target: t,
@@ -53037,7 +53124,7 @@ async function localStartServiceCommand(targets, options) {
 		try {
 			sharedNetwork = await createSharedSvcNetwork({
 				prefix: options.cluster,
-				skipPull: options.pull === false,
+				skipPull,
 				cluster: options.cluster
 			});
 		} catch (err) {
@@ -53059,7 +53146,7 @@ async function localStartServiceCommand(targets, options) {
 		};
 		process.on("SIGINT", sigintHandler);
 		process.on("SIGTERM", sigintHandler);
-		for (const pt of perTarget) pt.controller = await bootOneTarget(pt.target, pt.runState, stacks, options, discovery);
+		for (const pt of perTarget) pt.controller = await bootOneTarget(pt.target, pt.runState, stacks, options, discovery, skipPull);
 		const summary = perTarget.map((pt) => `${pt.controller.service.serviceName} (${pt.controller.activeReplicaCount()} replica(s))`).join(", ");
 		logger.info(`Service(s) running: ${summary}. Press ^C to shut down.`);
 		await Promise.all(perTarget.map((pt) => pt.controller.waitForShutdown()));
@@ -53077,7 +53164,7 @@ async function localStartServiceCommand(targets, options) {
 * options) is scoped locally. Returns the started controller for the
 * outer code to wait + tear down.
 */
-async function bootOneTarget(target, runState, stacks, options, discovery) {
+async function bootOneTarget(target, runState, stacks, options, discovery, skipPull) {
 	const logger = getLogger();
 	const imageContext = await buildEcsImageResolutionContext(target, stacks, options);
 	const service = resolveEcsServiceTarget(target, stacks, imageContext);
@@ -53120,7 +53207,7 @@ async function bootOneTarget(target, runState, stacks, options, discovery) {
 	const taskOpts = {
 		cluster: options.cluster,
 		containerHost: options.containerHost,
-		skipPull: options.pull === false,
+		skipPull,
 		keepRunning: false,
 		detach: true
 	};
@@ -53256,22 +53343,26 @@ function parsePositiveInt(raw, flagName) {
 }
 /**
 * Hard cap on `--max-tasks` driven by the per-replica subnet allocator
-* in `ecs-service-runner.ts:bootReplica` (`170 + (index % 84)`). The
-* `% 84` modulo wraps at index 84, collapsing replica 84's `/24` onto
-* replica 0's allocation. Docker rejects the duplicate-subnet network
-* creation with a cryptic "Pool overlaps with other one on this address
-* space" error 30s into the boot — by which time some early replicas
-* may have spent docker-run budget. Reject at parse time so the user
+* in `ecs-service-runner.ts:pickSubnetOctet`. The allocator walks the
+* link-local /24 range `169.254.170.0..169.254.253.0` and **skips 171**
+* because that octet is owned by the shared-service network
+* (`SHARED_SVC_SUBNET_OCTET`) — assigning a per-replica network the
+* same /24 would have docker reject the duplicate-subnet `network
+* create`. The usable count is therefore 83 (Issue #544); beyond
+* that, the modulo-wrap collapses replica N's `/24` onto replica 0's
+* allocation and docker rejects the duplicate-subnet network creation
+* with a cryptic "Pool overlaps with other one on this address space"
+* error 30s into the boot — by which time some early replicas may
+* have spent docker-run budget. Reject at parse time so the user
 * gets an actionable error before any boot work fires.
 *
-* 84 is the count of usable link-local /24 octets in the range
-* `169.254.170.0..169.254.253.0` (255 reserved for broadcast). Raising
-* this requires extending the allocator to walk a different IP range.
+* Raising this requires extending the allocator to walk a different
+* IP range.
 */
-const MAX_TASKS_SUBNET_RANGE_CAP = 84;
+const MAX_TASKS_SUBNET_RANGE_CAP = 83;
 function parseMaxTasks(raw) {
 	const parsed = parsePositiveInt(raw, "--max-tasks");
-	if (parsed > 84) throw new LocalStartServiceError(`--max-tasks ${parsed} exceeds the per-replica link-local /24 subnet allocator's range (${84}). The allocator in ecs-service-runner.ts assigns each replica its own 169.254.x.0/24 from the range 169.254.170.0..169.254.253.0; replica indices >= ${84} would collide with earlier replicas via modulo wrap. Lower --max-tasks to <= ${84}, or accept reduced local concurrency for high-DesiredCount services.`);
+	if (parsed > 83) throw new LocalStartServiceError(`--max-tasks ${parsed} exceeds the per-replica link-local /24 subnet allocator's range (${83}). The allocator in ecs-service-runner.ts assigns each replica its own 169.254.x.0/24 from the range 169.254.170.0..169.254.253.0; replica indices >= ${83} would collide with earlier replicas via modulo wrap. Lower --max-tasks to <= ${83}, or accept reduced local concurrency for high-DesiredCount services.`);
 	return parsed;
 }
 function parseRestartPolicy(raw) {
@@ -53279,7 +53370,7 @@ function parseRestartPolicy(raw) {
 	throw new LocalStartServiceError(`--restart-policy must be one of 'on-failure', 'always', or 'none' (got '${raw}').`);
 }
 function createLocalStartServiceCommand() {
-	const cmd = new Command("start-service").description("Run one or more AWS::ECS::Service resources locally as a long-running emulator. Spins up DesiredCount task replicas per service (clamped by --max-tasks) using the same per-task docker network + metadata sidecar pattern as `cdkd local run-task`, then keeps each replica running and restarts it on exit per --restart-policy. ^C tears every replica + sidecar + network down. Each <target> accepts a CDK display path (MyStack/MyService) or stack-qualified logical ID (MyStack:MyServiceXYZ); single-stack apps may omit the stack prefix. When two or more <target>s are supplied, every service is booted into a shared Cloud Map / Service Connect registry so peer services discover each other via docker --add-host overlay (Issue #460).").argument("<targets...>", "One or more CDK display paths or stack-qualified logical IDs of the AWS::ECS::Service resources to run").addOption(new Option("--cluster <name>", "Cluster name surfaced to ECS_CONTAINER_METADATA_URI_V4 and used as the docker network prefix").default("cdkd-local")).addOption(new Option("--env-vars <file>", "JSON env-var overrides (SAM-compatible: {\"ContainerName\":{\"KEY\":\"VALUE\"}, \"Parameters\":{}})")).addOption(new Option("--container-host <ip>", "Host IP to bind published container ports to. Must be a numeric IP (Docker rejects hostnames here)").default("127.0.0.1")).addOption(new Option("--assume-task-role [arn]", "Assume the task definition's TaskRoleArn (or the supplied ARN) and forward STS-issued temp credentials via the metadata sidecar so containers run with the deployed task role. Bare flag uses the template's TaskRoleArn; pass an explicit ARN to override.")).addOption(new Option("--no-pull", "Skip docker pull for every container image and the metadata sidecar")).addOption(new Option("--ecr-role-arn <arn>", "Role ARN to assume before authenticating against ECR for cross-account / centralized registries.")).addOption(new Option("--platform <platform>", "Force docker --platform (linux/amd64 or linux/arm64). Default: inferred from task RuntimePlatform.CpuArchitecture")).addOption(new Option("--max-tasks <n>", `Hard cap on local replica count. Caps the template DesiredCount so local dev machines don't run an unbounded number of containers. Cannot exceed ${84} due to the per-replica link-local /24 subnet allocator's range.`).default(3).argParser(parseMaxTasks)).addOption(new Option("--restart-policy <policy>", "How to react when an essential container exits. 'on-failure' (default) restarts only on non-zero exit; 'always' restarts on every exit; 'none' shuts the replica down and runs the service degraded.").default("on-failure").argParser(parseRestartPolicy)).addOption(new Option("--from-state", "Read cdkd S3 state for the target stack and substitute Fn::Sub / Fn::GetAtt / Fn::ImportValue / Fn::GetStackOutput intrinsics in container images, environment variables, secrets, role ARNs, and volumes.").default(false)).addOption(new Option("--stack-region <region>", "Region of the cdkd state record to read (used with --from-state when the same stack name has state in multiple regions).")).action(withErrorHandling(localStartServiceCommand));
+	const cmd = new Command("start-service").description("Run one or more AWS::ECS::Service resources locally as a long-running emulator. Spins up DesiredCount task replicas per service (clamped by --max-tasks) using the same per-task docker network + metadata sidecar pattern as `cdkd local run-task`, then keeps each replica running and restarts it on exit per --restart-policy. ^C tears every replica + sidecar + network down. Each <target> accepts a CDK display path (MyStack/MyService) or stack-qualified logical ID (MyStack:MyServiceXYZ); single-stack apps may omit the stack prefix. When two or more <target>s are supplied, every service is booted into a shared Cloud Map / Service Connect registry so peer services discover each other via docker --add-host overlay (Issue #460).").argument("<targets...>", "One or more CDK display paths or stack-qualified logical IDs of the AWS::ECS::Service resources to run").addOption(new Option("--cluster <name>", "Cluster name surfaced to ECS_CONTAINER_METADATA_URI_V4 and used as the docker network prefix").default("cdkd-local")).addOption(new Option("--env-vars <file>", "JSON env-var overrides (SAM-compatible: {\"ContainerName\":{\"KEY\":\"VALUE\"}, \"Parameters\":{}})")).addOption(new Option("--container-host <ip>", "Host IP to bind published container ports to. Must be a numeric IP (Docker rejects hostnames here)").default("127.0.0.1")).addOption(new Option("--assume-task-role [arn]", "Assume the task definition's TaskRoleArn (or the supplied ARN) and forward STS-issued temp credentials via the metadata sidecar so containers run with the deployed task role. Bare flag uses the template's TaskRoleArn; pass an explicit ARN to override.")).addOption(new Option("--no-pull", "Skip docker pull for every container image and the metadata sidecar")).addOption(new Option("--ecr-role-arn <arn>", "Role ARN to assume before authenticating against ECR for cross-account / centralized registries.")).addOption(new Option("--platform <platform>", "Force docker --platform (linux/amd64 or linux/arm64). Default: inferred from task RuntimePlatform.CpuArchitecture")).addOption(new Option("--max-tasks <n>", `Hard cap on local replica count. Caps the template DesiredCount so local dev machines don't run an unbounded number of containers. Cannot exceed ${83} due to the per-replica link-local /24 subnet allocator's range.`).default(3).argParser(parseMaxTasks)).addOption(new Option("--restart-policy <policy>", "How to react when an essential container exits. 'on-failure' (default) restarts only on non-zero exit; 'always' restarts on every exit; 'none' shuts the replica down and runs the service degraded.").default("on-failure").argParser(parseRestartPolicy)).addOption(new Option("--from-state", "Read cdkd S3 state for the target stack and substitute Fn::Sub / Fn::GetAtt / Fn::ImportValue / Fn::GetStackOutput intrinsics in container images, environment variables, secrets, role ARNs, and volumes.").default(false)).addOption(new Option("--stack-region <region>", "Region of the cdkd state record to read (used with --from-state when the same stack name has state in multiple regions).")).action(withErrorHandling(localStartServiceCommand));
 	[
 		...commonOptions,
 		...appOptions,
@@ -56593,7 +56684,7 @@ function reorderArgs(argv) {
 */
 async function main() {
 	const program = new Command();
-	program.name("cdkd").description("CDK Direct - Deploy AWS CDK apps directly via SDK/Cloud Control API").version("0.147.0");
+	program.name("cdkd").description("CDK Direct - Deploy AWS CDK apps directly via SDK/Cloud Control API").version("0.147.2");
 	program.addCommand(createBootstrapCommand());
 	program.addCommand(createSynthCommand());
 	program.addCommand(createListCommand());