@go-to-k/cdkd 0.194.0 → 0.195.0

package/README.md

@@ -242,6 +242,7 @@ maintain, no `cdk synth | sam ...` round-trip.
 | `cdkd local run-task <target>` | ECS RunTask — every container in a task definition started on a per-task docker network |
 | `cdkd local start-service <target>` | Long-running ECS Service emulator — `DesiredCount` replicas with restart-on-exit (no local load balancer in v1) |
 | `cdkd local invoke-agentcore <target>` | One-shot Bedrock AgentCore Runtime invoke (HTTP `/invocations` / MCP `/mcp` / A2A `/a2a` / AGUI / WebSocket `--ws`) |
+| `cdkd local start-alb <targets...>` | Long-running local ALB front-door (HTTP + HTTPS listeners, path / host / header / weighted / redirect / fixed-response routing, authenticate-cognito / authenticate-oidc) for ECS / Lambda backing services |
 
 Requires Docker. Pass `--from-state` (cdkd-deployed) or
 `--from-cfn-stack` (cdk-deployed / CFn-managed) to substitute deployed
@@ -302,6 +303,21 @@ restart-on-exit, cross-service Service Connect / Cloud Map DNS
 discovery (peer containers reach each other by `<discoveryName>.<namespace>`).
 No local load-balancer in v1.
 
+### `local start-alb`
+
+```bash
+cdkd local start-alb MyStack/MyAlb --lb-port 80=8080 # remap privileged listener port
+cdkd local start-alb MyStack/MyAlb --from-state      # OR --from-cfn-stack
+```
+
+Long-running local ALB front-door: names an `AWS::ElasticLoadBalancingV2::LoadBalancer`,
+boots every ECS service behind its listeners, and stands up a local
+HTTP / HTTPS front-door on each listener port that round-robins across
+the running replicas and routes its listener rules across the backing
+services. Forward / redirect / fixed-response actions; ECS or Lambda
+targets; authenticate-cognito / authenticate-oidc via a local Bearer-JWT
+check.
+
 See **[docs/local-emulation.md](docs/local-emulation.md)** for the
 full reference — runtimes, target resolution, every flag, integration
 and authorizer detail, route precedence, container pool, networking,

package/dist/cli.js

@@ -63,7 +63,7 @@ import { CreateNamespaceCommand, CreateTableBucketCommand, CreateTableCommand as
 import { AttachLoadBalancerTargetGroupsCommand, AttachLoadBalancersCommand, AttachTrafficSourcesCommand, AutoScalingClient, CreateAutoScalingGroupCommand, CreateOrUpdateTagsCommand, DeleteAutoScalingGroupCommand, DeleteLifecycleHookCommand, DeleteNotificationConfigurationCommand, DeleteTagsCommand as DeleteTagsCommand$1, DescribeAutoScalingGroupsCommand, DescribeLifecycleHooksCommand, DescribeNotificationConfigurationsCommand, DescribeTrafficSourcesCommand, DetachLoadBalancerTargetGroupsCommand, DetachLoadBalancersCommand, DetachTrafficSourcesCommand, DisableMetricsCollectionCommand, EnableMetricsCollectionCommand, PutLifecycleHookCommand, PutNotificationConfigurationCommand, UpdateAutoScalingGroupCommand } from "@aws-sdk/client-auto-scaling";
 import { Document, Pair, Scalar, YAMLMap, YAMLSeq, parse as parse$1, stringify } from "yaml";
 import { createLocalStateProvider, getEmbedConfig, isCfnFlagPresent, listTargets, rejectExplicitCfnStackWithMultipleStacks, resolveCfnFallbackRegion, setEmbedConfig, substituteAgainstState, substituteAgainstStateAsync, substituteEnvVarsFromState, substituteEnvVarsFromStateAsync } from "cdk-local";
-import { A2A_CONTAINER_PORT, A2A_PATH, AGENTCORE_A2A_PROTOCOL, AGENTCORE_AGUI_PROTOCOL, AGENTCORE_MCP_PROTOCOL, CloudMapRegistry, ConnectionRegistry, EcsTaskResolutionError, HOST_GATEWAY_MIN_VERSION, LocalInvokeBuildError, MCP_CONTAINER_PORT, MCP_PATH, a2aInvokeOnce, architectureToPlatform, attachAuthorizers, attachStageContext, availableApiIdentifiers, bufferToBody, buildAgentCoreCodeImage, buildCloudMapIndex, buildCognitoJwksUrl, buildConnectEvent, buildContainerImage, buildCorsConfigByApiId, buildCorsConfigFromCloudFrontChain, buildDisconnectEvent, buildJwksUrlFromIssuer, buildMessageEvent, buildMgmtEndpointEnvUrl, buildStageMap, createAuthorizerCache, createFileWatcher, createJwksCache, createWatchPredicates, defaultCredentialsLoader, derivePseudoParametersFromRegion, discoverRoutes, discoverWebSocketApis, downloadAndExtractS3Bundle, filterRoutesByApiIdentifier, getContainerNetworkIp, groupRoutesByServer, handleConnectionsRequest, invokeAgentCore, invokeAgentCoreWs, materializeLayerFromArn, mcpInvokeOnce, parseConnectionsPath, parseSelectionExpressionPath, pickAgentCoreCandidateStack, probeHostGatewaySupport, readMtlsMaterialsFromDisk, resolveAgentCoreTarget, resolveEnvVars, resolveRuntimeCodeMountPath, resolveRuntimeFileExtension, resolveRuntimeImage, resolveSingleTarget, resolveWatchConfig, signAgentCoreInvocation, startApiServer, substituteImagePlaceholders, tryResolveImageFnJoin, verifyJwtViaDiscovery, waitForAgentCorePing } from "cdk-local/internal";
+import { A2A_CONTAINER_PORT, A2A_PATH, AGENTCORE_A2A_PROTOCOL, AGENTCORE_AGUI_PROTOCOL, AGENTCORE_MCP_PROTOCOL, CloudMapRegistry, ConnectionRegistry, EcsTaskResolutionError, HOST_GATEWAY_MIN_VERSION, LocalInvokeBuildError, MCP_CONTAINER_PORT, MCP_PATH, a2aInvokeOnce, addCommonEcsServiceOptions, architectureToPlatform, attachAuthorizers, attachStageContext, availableApiIdentifiers, bufferToBody, buildAgentCoreCodeImage, buildCloudMapIndex, buildCognitoJwksUrl, buildConnectEvent, buildContainerImage, buildCorsConfigByApiId, buildCorsConfigFromCloudFrontChain, buildDisconnectEvent, buildJwksUrlFromIssuer, buildMessageEvent, buildMgmtEndpointEnvUrl, buildStageMap, createAuthorizerCache, createFileWatcher, createJwksCache, createWatchPredicates, defaultCredentialsLoader, derivePseudoParametersFromRegion, discoverRoutes, discoverWebSocketApis, downloadAndExtractS3Bundle, filterRoutesByApiIdentifier, getContainerNetworkIp, groupRoutesByServer, handleConnectionsRequest, invokeAgentCore, invokeAgentCoreWs, isApplicationLoadBalancer, materializeLayerFromArn, mcpInvokeOnce, parseConnectionsPath, parseSelectionExpressionPath, pickAgentCoreCandidateStack, probeHostGatewaySupport, readMtlsMaterialsFromDisk, resolveAgentCoreTarget, resolveAlbFrontDoor, resolveEnvVars, resolveRuntimeCodeMountPath, resolveRuntimeFileExtension, resolveRuntimeImage, resolveSingleTarget, resolveWatchConfig, runEcsServiceEmulator, signAgentCoreInvocation, startApiServer, substituteImagePlaceholders, tryResolveImageFnJoin, verifyJwtViaDiscovery, waitForAgentCorePing } from "cdk-local/internal";
 import { createServer } from "node:net";
 import { promisify } from "node:util";
 import { setTimeout as setTimeout$1 } from "node:timers/promises";
@@ -43048,6 +43048,14 @@ const fromStateFactory = (options) => {
 	});
 };
 /**
+* Cdkd's `extraStateProviders` map for cdk-local's engine entry points
+* (e.g. `runEcsServiceEmulator`) that accept a state-source factory
+* registry directly instead of going through `createLocalStateProvider`.
+* The engine calls `createLocalStateProvider` internally with this map,
+* so cdkd's `--from-state` flow is wired in transparently.
+*/
+const cdkdExtraStateProviders = { fromState: fromStateFactory };
+/**
 * Pick and construct the right `LocalStateProvider` for the supplied
 * flag set. Delegates to cdk-local's dispatcher with cdkd's
 * `--from-state` factory wired in. Returns `undefined` when neither
@@ -43066,7 +43074,7 @@ const fromStateFactory = (options) => {
 * per-stack loop — see that helper's docstring for the rationale.
 */
 function createLocalStateProvider$1(options, cdkdStackName, synthRegion) {
-	return createLocalStateProvider(options, cdkdStackName, synthRegion, { fromState: fromStateFactory });
+	return createLocalStateProvider(options, cdkdStackName, synthRegion, cdkdExtraStateProviders);
 }
 
 //#endregion
@@ -43111,7 +43119,7 @@ function parseTarget(target) {
 function resolveLambdaTarget(target, stacks) {
 	if (stacks.length === 0) throw new LocalInvokeResolutionError("No stacks found in the synthesized assembly.");
 	const parsed = parseTarget(target);
-	const stack = pickStack$2(parsed, stacks);
+	const stack = pickStack$3(parsed, stacks);
 	const template = stack.template;
 	const resources = template.Resources ?? {};
 	let match;
@@ -43145,7 +43153,7 @@ function resolveLambdaTarget(target, stacks) {
 * user may omit the stack prefix. Otherwise an explicit stack pattern is
 * required.
 */
-function pickStack$2(parsed, stacks) {
+function pickStack$3(parsed, stacks) {
 	if (parsed.stackPattern === null) {
 		if (stacks.length === 1) return stacks[0];
 		throw new LocalInvokeResolutionError(`Multiple stacks in app, target '${parsed.pathOrId}' is missing a stack prefix. Use 'StackName:${parsed.pathOrId}' or 'StackName/...' (path form). Available stacks: ${stacks.map((s) => s.stackName).join(", ")}.`);
@@ -43768,7 +43776,7 @@ function parseEcsTarget(target) {
 function resolveEcsTaskTarget(target, stacks, context) {
 	if (stacks.length === 0) throw new EcsTaskResolutionError("No stacks found in the synthesized assembly.");
 	const parsed = parseEcsTarget(target);
-	const stack = pickStack$1(parsed, stacks);
+	const stack = pickStack$2(parsed, stacks);
 	const resources = stack.template.Resources ?? {};
 	let logicalId;
 	let resource;
@@ -43789,7 +43797,7 @@ function resolveEcsTaskTarget(target, stacks, context) {
 	if (resource.Type !== "AWS::ECS::TaskDefinition") throw new EcsTaskResolutionError(`Resource '${logicalId}' in ${stack.stackName} is ${resource.Type}, not an AWS::ECS::TaskDefinition.`);
 	return extractTaskDefinitionProperties(stack, logicalId, resource, context);
 }
-function pickStack$1(parsed, stacks) {
+function pickStack$2(parsed, stacks) {
 	if (parsed.stackPattern === null) {
 		if (stacks.length === 1) return stacks[0];
 		throw new EcsTaskResolutionError(`Multiple stacks in app, target '${parsed.pathOrId}' is missing a stack prefix. Use 'StackName:${parsed.pathOrId}' or 'StackName/...' (path form). Available stacks: ${stacks.map((s) => s.stackName).join(", ")}.`);
@@ -48531,7 +48539,7 @@ async function localRunTaskCommand(target, options) {
 		const { stacks } = await synthesizer.synthesize(synthOpts);
 		const candidate = pickCandidateStack$1(parseEcsTarget(target).stackPattern, stacks);
 		stateProvider = createLocalStateProvider$1(options, candidate?.stackName ?? "", candidate?.region);
-		const imageContext = await buildEcsImageResolutionContext$1(candidate, stateProvider, options);
+		const imageContext = await buildEcsImageResolutionContext$2(candidate, stateProvider, options);
 		const task = resolveEcsTaskTarget(target, stacks, imageContext);
 		logger.info(`Target: ${task.stack.stackName}/${task.taskDefinitionLogicalId} (family=${task.family}, containers=${task.containers.length})`);
 		const taskNeeds = detectEcsImageResolutionNeeds(stacks.find((s) => s.stackName === task.stack.stackName) ?? task.stack);
@@ -48655,7 +48663,7 @@ async function assumeTaskRole$1(roleArn, region) {
 * `--from-state` and `--from-cfn-stack` produce the same downstream
 * context shape (issue #606).
 */
-async function buildEcsImageResolutionContext$1(candidate, stateProvider, options) {
+async function buildEcsImageResolutionContext$2(candidate, stateProvider, options) {
 	const logger = getLogger();
 	if (!candidate) return void 0;
 	const needs = detectEcsImageResolutionNeeds(candidate);
@@ -48783,7 +48791,7 @@ function createLocalRunTaskCommand() {
 function resolveEcsServiceTarget(target, stacks, context) {
 	if (stacks.length === 0) throw new EcsTaskResolutionError("No stacks found in the synthesized assembly.");
 	const parsed = parseEcsTarget(target);
-	const stack = pickStack(parsed, stacks);
+	const stack = pickStack$1(parsed, stacks);
 	const resources = stack.template.Resources ?? {};
 	let serviceLogicalId;
 	let serviceResource;
@@ -48985,7 +48993,7 @@ function parseServiceName(raw, serviceLogicalId) {
 * service-specific extensions (e.g. cross-stack service-to-task refs)
 * can diverge without breaking the run-task code path.
 */
-function pickStack(parsed, stacks) {
+function pickStack$1(parsed, stacks) {
 	if (parsed.stackPattern === null) {
 		if (stacks.length === 1) return stacks[0];
 		throw new EcsTaskResolutionError(`Target has no stack prefix, and the assembly contains ${stacks.length} stacks: ${stacks.map((s) => s.stackName).join(", ")}. Pass the target as 'Stack/Path' or 'Stack:LogicalId'.`);
@@ -49539,7 +49547,7 @@ async function localStartServiceCommand(targets, options) {
 			for (const w of index.warnings) logger.warn(w);
 		}
 		const registry = new CloudMapRegistry();
-		const sidecarCredentials = await resolveSharedSidecarCredentials(options);
+		const sidecarCredentials = await resolveSharedSidecarCredentials$1(options);
 		try {
 			sharedNetwork = await createSharedSvcNetwork({
 				prefix: options.cluster,
@@ -49596,7 +49604,7 @@ async function bootOneTarget(target, runState, stacks, options, discovery, skipP
 }
 async function runOneTarget(target, runState, stacks, options, discovery, skipPull, stateProvider, profileCredsFile) {
 	const logger = getLogger();
-	const imageContext = await buildEcsImageResolutionContext(target, stacks, options, stateProvider);
+	const imageContext = await buildEcsImageResolutionContext$1(target, stacks, options, stateProvider);
 	const service = resolveEcsServiceTarget(target, stacks, imageContext);
 	logger.info(`Target: ${service.stack.stackName}/${service.serviceLogicalId} (service=${service.serviceName}, desiredCount=${service.desiredCount}, task=${service.task.taskDefinitionLogicalId})`);
 	for (const w of service.warnings) logger.warn(w);
@@ -49689,7 +49697,7 @@ async function assumeTaskRole(roleArn, region) {
 * the candidate stack picker differs because services and tasks share
 * the same stack-pattern grammar.
 */
-async function buildEcsImageResolutionContext(target, stacks, options, stateProvider) {
+async function buildEcsImageResolutionContext$1(target, stacks, options, stateProvider) {
 	const logger = getLogger();
 	const candidate = pickCandidateStack(parseEcsTarget(target).stackPattern, stacks);
 	if (!candidate) return void 0;
@@ -49781,13 +49789,13 @@ function parsePositiveInt(raw, flagName) {
 * Raising this requires extending the allocator to walk a different
 * IP range.
 */
-const MAX_TASKS_SUBNET_RANGE_CAP = 83;
-function parseMaxTasks(raw) {
+const MAX_TASKS_SUBNET_RANGE_CAP$1 = 83;
+function parseMaxTasks$1(raw) {
 	const parsed = parsePositiveInt(raw, "--max-tasks");
 	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) {
+function parseRestartPolicy$1(raw) {
 	if (raw === "on-failure" || raw === "always" || raw === "none") return raw;
 	throw new LocalStartServiceError(`--restart-policy must be one of 'on-failure', 'always', or 'none' (got '${raw}').`);
 }
@@ -49816,11 +49824,11 @@ function parseRestartPolicy(raw) {
 * branches without having to mock the full Synth + Docker + AWS
 * pipeline (the strategy PR #655 used for the Lambda container path).
 */
-async function resolveSharedSidecarCredentials(options) {
+async function resolveSharedSidecarCredentials$1(options) {
 	if (options.profile) return resolveProfileCredentials(options.profile);
 }
 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 ${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("--from-cfn-stack [cfn-stack-name]", "Read a deployed CloudFormation stack via DescribeStackResources and substitute Ref / Fn::ImportValue in container env vars / secrets / image URIs with the deployed physical IDs / exports. Use for CDK apps deployed via the upstream CDK CLI (`cdk deploy`). Bare form uses the cdkd stack name; pass an explicit value when the CFn stack name differs. Mutually exclusive with --from-state. Fn::GetAtt is warn-and-dropped in v1 (CFn DescribeStackResources does not return per-attribute values).")).addOption(new Option("--stack-region <region>", "Region of the state record to read. Used with --from-state when the same stack name has state in multiple regions, and with --from-cfn-stack as the CFn client region (cdkd does not have a separate --cfn-stack-region flag).")).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$1)).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$1)).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("--from-cfn-stack [cfn-stack-name]", "Read a deployed CloudFormation stack via DescribeStackResources and substitute Ref / Fn::ImportValue in container env vars / secrets / image URIs with the deployed physical IDs / exports. Use for CDK apps deployed via the upstream CDK CLI (`cdk deploy`). Bare form uses the cdkd stack name; pass an explicit value when the CFn stack name differs. Mutually exclusive with --from-state. Fn::GetAtt is warn-and-dropped in v1 (CFn DescribeStackResources does not return per-attribute values).")).addOption(new Option("--stack-region <region>", "Region of the state record to read. Used with --from-state when the same stack name has state in multiple regions, and with --from-cfn-stack as the CFn client region (cdkd does not have a separate --cfn-stack-region flag).")).action(withErrorHandling(localStartServiceCommand));
 	[
 		...commonOptions,
 		...appOptions,
@@ -50637,6 +50645,189 @@ function createLocalInvokeAgentCoreCommand() {
 	return cmd;
 }
 
+//#endregion
+//#region src/cli/commands/local-start-alb.ts
+/**
+* Issue #86 v1 — parse `--lb-port <listenerPort>=<hostPort>` overrides into a
+* `listenerPort -> hostPort` map. The local ALB front-door binds the listener
+* port on the host by default, but a privileged listener port (e.g. 80 / 443)
+* fails to bind as non-root on macOS, so the user opts in to a non-privileged
+* host port (e.g. `--lb-port 80=8080`). Repeatable; each value is
+* `<listenerPort>=<hostPort>` with both in 1-65535.
+*/
+function parseLbPortOverrides(values) {
+	const out = {};
+	for (const raw of values ?? []) {
+		const m = /^(\d+)=(\d+)$/.exec(raw.trim());
+		if (!m) throw new LocalStartServiceError(`Invalid --lb-port '${raw}'. Expected <listenerPort>=<hostPort> (e.g. 80=8080).`);
+		const listenerPort = Number(m[1]);
+		const hostPort = Number(m[2]);
+		for (const [label, p] of [["listener", listenerPort], ["host", hostPort]]) if (p < 1 || p > 65535) throw new LocalStartServiceError(`Invalid --lb-port '${raw}': ${label} port must be 1-65535.`);
+		out[listenerPort] = hostPort;
+	}
+	return out;
+}
+/**
+* Resolve an ALB target string (`Stack/Path` display path or `Stack:LogicalId`)
+* to its stack + `AWS::ElasticLoadBalancingV2::LoadBalancer` logical id. Mirrors
+* the ECS service resolver's target grammar.
+*/
+function resolveAlbTarget(target, stacks) {
+	if (stacks.length === 0) throw new LocalStartServiceError("No stacks found in the synthesized assembly.");
+	const parsed = parseEcsTarget(target);
+	const stack = pickStack(parsed.stackPattern, stacks, target);
+	const resources = stack.template.Resources ?? {};
+	if (parsed.isPath) {
+		const index = buildCdkPathIndex(stack.template);
+		const albs = resolveCdkPathToLogicalIds(parsed.pathOrId, index).filter(({ logicalId }) => {
+			const r = resources[logicalId];
+			return r !== void 0 && isApplicationLoadBalancer(r);
+		});
+		if (albs.length === 0) throw notFound(target, stack, resources);
+		if (albs.length > 1) throw new LocalStartServiceError(`Target '${target}' matches ${albs.length} load balancers in ${stack.stackName}: ${albs.map((a) => a.logicalId).join(", ")}. Refine the path or use the stack:LogicalId form.`);
+		return {
+			stack,
+			albLogicalId: albs[0].logicalId
+		};
+	}
+	const res = resources[parsed.pathOrId];
+	if (!res || !isApplicationLoadBalancer(res)) throw notFound(target, stack, resources);
+	return {
+		stack,
+		albLogicalId: parsed.pathOrId
+	};
+}
+function pickStack(stackPattern, stacks, target) {
+	if (stackPattern === null) {
+		if (stacks.length === 1) return stacks[0];
+		throw new LocalStartServiceError(`Target '${target}' has no stack prefix, and the assembly contains ${stacks.length} stacks: ${stacks.map((s) => s.stackName).join(", ")}. Pass it as 'Stack/Path' or 'Stack:LogicalId'.`);
+	}
+	const matched = matchStacks(stacks, [stackPattern]);
+	if (matched.length === 0) throw new LocalStartServiceError(`No stack matches '${stackPattern}'. Available stacks: ${stacks.map((s) => s.stackName).join(", ")}.`);
+	if (matched.length > 1) throw new LocalStartServiceError(`Multiple stacks match '${stackPattern}': ${matched.map((s) => s.stackName).join(", ")}. Refine the pattern.`);
+	return matched[0];
+}
+function notFound(target, stack, resources) {
+	const albs = Object.entries(resources).filter(([, r]) => r.Type === "AWS::ElasticLoadBalancingV2::LoadBalancer").map(([logicalId]) => logicalId);
+	const available = albs.length > 0 ? ` Available load balancers in ${stack.stackName}: ${albs.join(", ")}.` : ` ${stack.stackName} declares no AWS::ElasticLoadBalancingV2::LoadBalancer resources.`;
+	return new LocalStartServiceError(`Target '${target}' did not match an application Load Balancer in ${stack.stackName}.${available}`);
+}
+/**
+* `cdkl start-alb` strategy — name the ALB, boot the ECS service(s) behind it,
+* and expose each listener via a local front-door. Mirrors how `start-api`
+* names the API and serves its backing Lambdas.
+*/
+function albStrategy(options) {
+	const lbPortOverrides = parseLbPortOverrides(options.lbPort);
+	return {
+		pickEntries: (stacks) => listTargets(stacks).loadBalancers,
+		pickerMessage: "Select one or more Application Load Balancers to run",
+		pickerNoun: "Application Load Balancers",
+		onMissing: () => new LocalStartServiceError(`${getEmbedConfig().cliName} start-alb requires at least one <target>. Pass one or more ALB paths like 'Stack/MyAlb', or run it in a TTY to pick interactively.`),
+		resolveBoots: (stacks, chosenTargets) => {
+			const warnings = [];
+			const serviceTargets = /* @__PURE__ */ new Set();
+			const listeners = [];
+			const claimedHostPorts = /* @__PURE__ */ new Map();
+			for (const albTarget of chosenTargets) {
+				const { stack, albLogicalId } = resolveAlbTarget(albTarget, stacks);
+				const resolution = resolveAlbFrontDoor(stack, albLogicalId);
+				warnings.push(...resolution.warnings);
+				const qualifyTarget = (t) => {
+					if (t.kind === "lambda") return {
+						kind: "lambda",
+						lambda: resolveLambdaTarget(`${stack.stackName}:${t.lambdaLogicalId}`, stacks),
+						targetGroupArn: `${stack.stackName}:${t.targetGroupLogicalId}`,
+						multiValueHeaders: t.multiValueHeaders,
+						weight: t.weight
+					};
+					const serviceTarget = `${stack.stackName}:${t.serviceLogicalId}`;
+					serviceTargets.add(serviceTarget);
+					return {
+						kind: "ecs",
+						serviceTarget,
+						targetContainerName: t.targetContainerName,
+						targetContainerPort: t.targetContainerPort,
+						weight: t.weight
+					};
+				};
+				const qualify = (action) => {
+					if (action.kind === "forward") return {
+						kind: "forward",
+						targets: action.targets.map(qualifyTarget)
+					};
+					if (action.kind === "redirect") return {
+						kind: "redirect",
+						statusCode: action.statusCode,
+						...action.protocol !== void 0 && { protocol: action.protocol },
+						...action.host !== void 0 && { host: action.host },
+						...action.port !== void 0 && { port: action.port },
+						...action.path !== void 0 && { path: action.path },
+						...action.query !== void 0 && { query: action.query }
+					};
+					return {
+						kind: "fixed-response",
+						statusCode: action.statusCode,
+						...action.contentType !== void 0 && { contentType: action.contentType },
+						...action.messageBody !== void 0 && { messageBody: action.messageBody }
+					};
+				};
+				for (const listener of resolution.listeners) {
+					const hostPort = lbPortOverrides[listener.listenerPort] ?? listener.listenerPort;
+					const claimedBy = claimedHostPorts.get(hostPort);
+					if (claimedBy !== void 0) {
+						warnings.push(`Listener port ${listener.listenerPort} would bind host port ${hostPort}, already claimed by listener port ${claimedBy}; the local front-door fronts only the first. Use --lb-port to remap one of them.`);
+						continue;
+					}
+					claimedHostPorts.set(hostPort, listener.listenerPort);
+					listeners.push({
+						listenerPort: listener.listenerPort,
+						hostPort,
+						protocol: listener.listenerProtocol,
+						...listener.defaultAction ? { defaultAction: qualify(listener.defaultAction) } : {},
+						...listener.defaultAuthGuard ? { defaultAuthGuard: listener.defaultAuthGuard } : {},
+						rules: listener.rules.map((r) => ({
+							priority: r.priority,
+							pathPatterns: r.pathPatterns,
+							hostPatterns: r.hostPatterns,
+							httpHeaderConditions: r.httpHeaderConditions,
+							httpRequestMethods: r.httpRequestMethods,
+							queryStringConditions: r.queryStringConditions,
+							sourceIpCidrs: r.sourceIpCidrs,
+							action: qualify(r.action),
+							...r.authGuard ? { authGuard: r.authGuard } : {}
+						}))
+					});
+				}
+			}
+			const boots = [...serviceTargets].map((target) => ({ target }));
+			const resolvedPorts = new Set(listeners.map((l) => l.listenerPort));
+			for (const portStr of Object.keys(lbPortOverrides)) {
+				const port = Number(portStr);
+				if (!resolvedPorts.has(port)) warnings.push(`--lb-port override for listener port ${port} matched no ALB listener resolved for the named target(s); it was ignored.`);
+			}
+			return {
+				boots,
+				...listeners.length > 0 ? { frontDoor: { listeners } } : {},
+				warnings
+			};
+		},
+		lbPortOverrides
+	};
+}
+/**
+* `cdkl start-alb <Stack/Alb>` — Issue #86 v1. Names an
+* `AWS::ElasticLoadBalancingV2::LoadBalancer`, discovers the ECS service(s)
+* behind its HTTP `forward` listeners, boots their replicas, and stands up a
+* local front-door on each listener port that round-robins across the replicas.
+* The symmetric ALB counterpart of `start-api`.
+*/
+function createLocalStartAlbCommand() {
+	return addCommonEcsServiceOptions(new Command("start-alb").description("Run an Application Load Balancer locally: name the ALB, and cdk-local boots the ECS service(s) behind its listeners and stands up a local front-door on each listener port that round-robins across the running replicas and routes its listener rules across the backing services — a stable host endpoint, like behind a real load balancer. The symmetric ALB counterpart of `start-api`. Each <target> accepts a CDK display path (MyStack/MyAlb) or stack-qualified logical ID; single-stack apps may omit the stack prefix. Supports HTTP and HTTPS listeners (TLS terminated locally with --tls-cert/--tls-key or an auto-generated self-signed cert); all six ALB rule-condition fields (path-pattern / host-header / http-header / http-request-method / query-string / source-ip); forward (single and weighted), redirect, and fixed-response actions; and ECS or Lambda targets (a Lambda target group is invoked locally via the Lambda RIE). authenticate-cognito / authenticate-oidc actions enforce a local Bearer-JWT check (or AWSELBAuthSessionCookie pass-through) against the same JWKS / OIDC discovery URL the deployed ALB would; use --bearer-token <jwt> to inject a default token or --no-verify-auth to disable the guard. Omit <targets> in an interactive terminal to multi-select the load balancers from a list.").argument("[targets...]", "One or more CDK display paths or stack-qualified logical IDs of the AWS::ElasticLoadBalancingV2::LoadBalancer resources to run (omit to multi-select interactively in a TTY)").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-cert <path>", "PEM-encoded server certificate for HTTPS front-door listeners. Must be set together with --tls-key. Omit both flags 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. 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("--from-state", "Read cdkd's S3 state for the target stack and substitute Ref / Fn::GetAtt / Fn::Sub / Fn::ImportValue / Fn::GetStackOutput intrinsics in container images, environment variables, secrets, role ARNs, and volumes of the ECS services behind the ALB. Mutually exclusive with --from-cfn-stack.").default(false)).addOption(new Option("--state-bucket <bucket>", "S3 bucket for --from-state. Falls back to CDKD_STATE_BUCKET env or cdk.json context.cdkd.stateBucket.")).addOption(new Option("--state-prefix <prefix>", "S3 key prefix for --from-state state files.").default("cdkd")).action(withErrorHandling(async (targets, options) => {
+		await runEcsServiceEmulator(targets, options, albStrategy(options), cdkdExtraStateProviders);
+	})));
+}
+
 //#endregion
 //#region src/cli/commands/local-invoke.ts
 /**
@@ -51440,6 +51631,7 @@ function createLocalCommand() {
 	local.addCommand(createLocalRunTaskCommand());
 	local.addCommand(createLocalStartServiceCommand());
 	local.addCommand(createLocalInvokeAgentCoreCommand());
+	local.addCommand(createLocalStartAlbCommand());
 	return local;
 }
 
@@ -52552,7 +52744,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.194.0");
+	program.name("cdkd").description("CDK Direct - Deploy AWS CDK apps directly via SDK/Cloud Control API").version("0.195.0");
 	program.addCommand(createBootstrapCommand());
 	program.addCommand(createSynthCommand());
 	program.addCommand(createListCommand());