@go-to-k/cdkd 0.147.1 → 0.148.0

package/README.md

@@ -306,6 +306,8 @@ cdkd state info --state-bucket my-bucket  # explicit bucket; reports Source: --s
 cdkd state list
 cdkd state ls --long          # include resource count, last-modified, lock status
 cdkd state list --json        # JSON output (alone, or combined with --long)
+cdkd state list --tree        # parent → child stack tree (nested stacks; #555 A3)
+cdkd state list --tree --json # tree as nested JSON
 
 # List resources of a single stack from state
 cdkd state resources MyStack          # aligned columns: LogicalID, Type, PhysicalID

package/dist/cli.js

@@ -34897,6 +34897,95 @@ function createStateMigrateCommand() {
 	return cmd;
 }
 
+//#endregion
+//#region src/cli/commands/state-list-tree.ts
+/**
+* Build a parent → child tree from the flat list of state records.
+*
+* Children are linked to their parent by `(parentStack, parentRegion)`
+* matching another entry's `(stackName, region)`. Children whose parent
+* isn't present in the input (orphans — parent state was hand-deleted,
+* or destroyed out-of-band) are reported at the root level so they stay
+* visible to `cdkd state list` rather than vanishing silently.
+*
+* A self-link (parent equals self) is treated as a missing parent — the
+* node lands at the root rather than building an infinite tree.
+*
+* The roots and every child list are sorted alphabetically by `stackName`,
+* then by `region` (legacy `undefined` last), so output is stable across
+* runs.
+*/
+function buildStackTree(entries) {
+	const refKey = (stackName, region) => `${stackName}\0${region ?? ""}`;
+	const byKey = /* @__PURE__ */ new Map();
+	for (const entry of entries) byKey.set(refKey(entry.stackName, entry.region), {
+		...entry,
+		children: []
+	});
+	const roots = [];
+	for (const node of byKey.values()) {
+		if (node.parentStack !== void 0) {
+			const parent = byKey.get(refKey(node.parentStack, node.parentRegion));
+			if (parent && parent !== node) {
+				parent.children.push(node);
+				continue;
+			}
+		}
+		roots.push(node);
+	}
+	const cmp = (a, b) => {
+		if (a.stackName < b.stackName) return -1;
+		if (a.stackName > b.stackName) return 1;
+		const ar = a.region ?? "￿";
+		const br = b.region ?? "￿";
+		if (ar < br) return -1;
+		if (ar > br) return 1;
+		return 0;
+	};
+	const sortRecursive = (list) => {
+		list.sort(cmp);
+		for (const node of list) sortRecursive(node.children);
+	};
+	sortRecursive(roots);
+	return roots;
+}
+/**
+* Render the tree using `tree(1)`-style box-drawing prefixes.
+*
+* Each line is built by `formatLine(node)`. The caller picks the
+* human-readable shape (e.g. `Stack (region)`); this helper only owns the
+* indentation.
+*/
+function renderStackTreeAscii(roots, formatLine) {
+	const lines = [];
+	for (const root of roots) {
+		lines.push(formatLine(root));
+		renderChildren(root.children, "", lines, formatLine);
+	}
+	return lines.join("\n");
+}
+function renderChildren(children, prefix, out, formatLine) {
+	const lastIdx = children.length - 1;
+	for (let i = 0; i < children.length; i++) {
+		const child = children[i];
+		const isLast = i === lastIdx;
+		const branch = isLast ? "└── " : "├── ";
+		const childPrefix = isLast ? "    " : "│   ";
+		out.push(`${prefix}${branch}${formatLine(child)}`);
+		renderChildren(child.children, prefix + childPrefix, out, formatLine);
+	}
+}
+function stackTreeToJson(roots) {
+	return roots.map((node) => ({
+		stackName: node.stackName,
+		region: node.region ?? null,
+		parentStack: node.parentStack ?? null,
+		parentLogicalId: node.parentLogicalId ?? null,
+		parentRegion: node.parentRegion ?? null,
+		children: stackTreeToJson(node.children)
+	}));
+}
+
 //#endregion
 //#region src/cli/commands/state.ts
 /**
@@ -35001,6 +35090,10 @@ function sortRefs(refs) {
 *   `version: 1` records (no region) appear as plain `Stack` rows.
 * - `--long`/`-l`: include resource count, last-modified time, and lock status.
 * - `--json`: emit a JSON array (alongside or instead of the long form).
+* - `--tree`: render parent → child stack tree (issue #555 A3). Loads each
+*   state record to read the v6 `parentStack` / `parentRegion` fields, then
+*   reconstructs the hierarchy. Flat default is preserved so tooling that
+*   greps the existing one-per-line shape keeps working.
 */
 async function stateListCommand(options) {
 	const logger = getLogger();
@@ -35008,6 +35101,10 @@ async function stateListCommand(options) {
 	const setup = await setupStateBackend(options);
 	try {
 		const refs = sortRefs(await setup.stateBackend.listStacks());
+		if (options.tree) {
+			await renderTreeMode(refs, setup.stateBackend, options.json);
+			return;
+		}
 		if (!options.long && !options.json) {
 			for (const ref of refs) process.stdout.write(`${formatStackRef(ref)}\n`);
 			return;
@@ -35057,10 +35154,56 @@ async function stateListCommand(options) {
 	}
 }
 /**
+* Render the parent → child stack tree for `cdkd state list --tree`.
+*
+* Loads each state record in parallel to read the v6 `parentStack` /
+* `parentLogicalId` / `parentRegion` fields, then hands the enriched flat
+* list to {@link buildStackTree}. A missing state record (NoSuchKey returns
+* `null` from getState) OR an unreadable one (transient S3 503 / throttle /
+* per-stack IAM hiccup throws) degrades to a top-level entry (no parent
+* link) — the row still appears in the tree at the root level rather than
+* vanishing, and one bad record never kills the whole view.
+*
+* `tree --json` emits the nested {@link import('./state-list-tree.js').StackTreeJson}
+* shape; plain `tree` renders `tree(1)`-style box-drawing.
+*/
+async function renderTreeMode(refs, stateBackend, asJson) {
+	const roots = buildStackTree(await Promise.all(refs.map(async (ref) => {
+		if (!ref.region) return { stackName: ref.stackName };
+		let state;
+		try {
+			state = (await stateBackend.getState(ref.stackName, ref.region))?.state;
+		} catch {
+			return {
+				stackName: ref.stackName,
+				region: ref.region
+			};
+		}
+		return {
+			stackName: ref.stackName,
+			region: ref.region,
+			...state?.parentStack !== void 0 && { parentStack: state.parentStack },
+			...state?.parentLogicalId !== void 0 && { parentLogicalId: state.parentLogicalId },
+			...state?.parentRegion !== void 0 && { parentRegion: state.parentRegion }
+		};
+	})));
+	if (asJson) {
+		process.stdout.write(`${JSON.stringify(stackTreeToJson(roots), null, 2)}\n`);
+		return;
+	}
+	if (roots.length === 0) return;
+	const rendered = renderStackTreeAscii(roots, (node) => formatStackRef({
+		stackName: node.stackName,
+		...node.region ? { region: node.region } : {}
+	}));
+	process.stdout.write(`${rendered}\n`);
+}
+/**
 * Create the `state list` subcommand.
 */
 function createStateListCommand() {
-	const cmd = new Command("list").alias("ls").description("List stacks registered in the cdkd state bucket").option("-l, --long", "Show resource count, last-modified time, and lock status", false).option("--json", "Output as JSON", false).action(withErrorHandling(stateListCommand));
+	const treeOption = new Option("--tree", "Render parent → child stack tree (loads each state record to read the v6 parent link)").default(false).conflicts("long");
+	const cmd = new Command("list").alias("ls").description("List stacks registered in the cdkd state bucket").option("-l, --long", "Show resource count, last-modified time, and lock status", false).option("--json", "Output as JSON", false).addOption(treeOption).action(withErrorHandling(stateListCommand));
 	[...commonOptions, ...stateOptions].forEach((opt) => cmd.addOption(opt));
 	cmd.addOption(deprecatedRegionOption);
 	return cmd;
@@ -36647,9 +36790,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.
 *
@@ -39498,6 +39646,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);
@@ -52066,7 +52215,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;
@@ -52139,8 +52288,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) {
@@ -52148,7 +52305,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];
@@ -52329,6 +52489,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.
 */
@@ -52507,7 +52699,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 } : {}
 	};
@@ -52709,8 +52901,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();
 	/**
@@ -52746,8 +52943,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`).
@@ -52757,6 +52959,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);
 	}
 	/**
@@ -53002,6 +53210,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,
@@ -53058,7 +53267,7 @@ async function localStartServiceCommand(targets, options) {
 		try {
 			sharedNetwork = await createSharedSvcNetwork({
 				prefix: options.cluster,
-				skipPull: options.pull === false,
+				skipPull,
 				cluster: options.cluster
 			});
 		} catch (err) {
@@ -53080,7 +53289,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()));
@@ -53098,7 +53307,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);
@@ -53141,7 +53350,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
 	};
@@ -53277,22 +53486,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) {
@@ -53300,7 +53513,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,
@@ -56614,7 +56827,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.1");
+	program.name("cdkd").description("CDK Direct - Deploy AWS CDK apps directly via SDK/Cloud Control API").version("0.148.0");
 	program.addCommand(createBootstrapCommand());
 	program.addCommand(createSynthCommand());
 	program.addCommand(createListCommand());