cdk-local 0.53.0 → 0.55.0

package/README.md

@@ -4,7 +4,8 @@
 [![CI](https://github.com/go-to-k/cdk-local/actions/workflows/ci.yml/badge.svg)](https://github.com/go-to-k/cdk-local/actions/workflows/ci.yml)
 [![License: Apache-2.0](https://img.shields.io/npm/l/cdk-local.svg)](./LICENSE)
 
-Run your CDK app's Lambda functions, API Gateway APIs, ECS tasks / services / ALB-fronted services, and Bedrock AgentCore agents on your own machine — with **no AWS account**, or bound to your **deployed stack to hit real AWS resources and data**. A native, CDK-first alternative to `sam local`.
+**Run your CDK app locally — no SAM template, no AWS account. Or bind to your deployed stack and hit its real data.**
+A CDK-native alternative to `sam local`, covering Lambda, API Gateway, ECS, ALB-fronted services, and Bedrock AgentCore.
 
 ![cdkl start-api serving a local CDK app's HTTP API; curl in the right pane reaches the local Lambda](assets/cdkl-start-api.gif)
 
@@ -31,8 +32,10 @@ cdkl invoke MyStack/Fn --from-cfn-stack    # one Lambda against real DynamoDB /
 
 - **Zero-friction local execution** — no AWS account, no IAM access, no deploy; just Docker and your CDK app. Onboard new engineers, review a PR by actually running its code, or work on an OSS CDK sample without owning the maintainer's account.
 - **Iterate against your real deployed stack — including its data.** `--from-cfn-stack` keeps you on the real DynamoDB rows, S3 objects, Cognito users, and Secret values your IAM credentials reach, instead of paying to seed and anonymize a local emulator.
-
-It also picks up where `sam local` leaves off: **CDK-native** (point at `cdk.json`, no SAM templates), **wider coverage** (Lambda, API Gateway, ECS run-task / service / ALB front-door, Bedrock AgentCore), and **real container images** (the Lambda RIE base image; ECS as real Docker — the only dependency is Docker).
+- **Picks up where `sam local` leaves off:**
+  - **CDK-native** — point at `cdk.json`; no SAM template to maintain.
+  - **Wider coverage** — Lambda, API Gateway, ECS run-task / service / ALB front-door, and Bedrock AgentCore.
+  - **Real container images** — the Lambda RIE base image; ECS as real Docker. The only dependency is Docker itself.
 
 ## What runs locally
 
@@ -58,54 +61,27 @@ cdkl list                                      # every runnable target, grouped
 
 - **`start-api`** serves one HTTP server per API; a bare `start-api` in a multi-stack app needs `--all-stacks` or `--stack <name>`. Add **`--watch`** to re-synth and hot-reload on CDK source changes ([details](docs/local-emulation.md#hot-reload---watch)).
 - **`run-task`** / single-replica **`start-service`** publish declared container ports on the host and log `Reach it at 127.0.0.1:<port>` (`--host-port <container>=<host>` remaps; handy for privileged ports on macOS).
-- **`invoke-agentcore`** runs the agent (a container, or a `fromCodeAsset` / `fromS3` managed-runtime bundle — Python 3.10-3.14 / Node 22 — built from source), waits for `GET /ping`, POSTs your `--event` to `POST /invocations`, and streams an SSE response live. `--ws` streams over the agent's bidirectional `/ws` WebSocket endpoint instead. A `customJwtAuthorizer` is enforced locally — pass `--bearer-token <jwt>` (verified against the runtime's OIDC discovery URL). MCP-protocol runtimes (`ProtocolConfiguration = MCP`) are also served — the `POST /mcp` Streamable-HTTP contract on 8000, with one JSON-RPC request (`tools/list` by default, or `--event`'s `{"method":...,"params":...}`).
+- **`start-alb`** stands up the ECS service(s) behind an ALB plus a host-side front-door on each listener port, honoring all six listener-rule conditions, weighted forwards, redirect / fixed-response actions, and mixed ECS + Lambda targets ([details](docs/cli-reference.md#cdkl-start-alb-run-an-alb-fronted-service-locally)).
+- **`invoke-agentcore`** invokes a Bedrock AgentCore Runtime agent locally — container or `fromCodeAsset` / `fromS3` managed runtime, HTTP / SSE / WebSocket / MCP protocols, with `customJwtAuthorizer` and `--sigv4` enforcement ([details](docs/cli-reference.md#cdkl-invoke-agentcore-run-bedrock-agentcore-runtime-agents-locally)).
 - Non-TTY (CI / pipes): every command except a bare `start-api` needs an explicit target.
 
 Full flags, precedence, and `--from-cfn-stack` resolution: [docs/cli-reference.md](docs/cli-reference.md) and [docs/local-emulation.md](docs/local-emulation.md).
 
-## start-service vs start-alb — which one?
-
-`start-service` and `start-alb` mirror `run-task` / `invoke` (the compute alone) vs `start-api` (the routed entry in front of the compute):
-
-| Command | You name | What runs | Use when |
-| --- | --- | --- | --- |
-| `cdkl start-service <Service>` | the ECS **service** | just the service's replicas (no load balancer) | workers / queue consumers / Service-Connect-only services, or to hit the containers directly |
-| `cdkl start-alb <Alb>` | the **ALB** | the ECS service(s) behind it **plus** a local **front-door** on each listener port | an `ApplicationLoadBalancedFargateService`-style service you want to reach the way external traffic does |
-
-`start-alb` discovers the ECS service(s) behind the ALB's HTTP listeners, boots their replicas, and stands up a host-side front-door on each listener port that round-robins across the replicas — one stable host endpoint, like behind a real load balancer. It honors **every ALB listener-rule condition** — `path-pattern`, `host-header`, `http-header`, `http-request-method`, `query-string`, and `source-ip` — plus **weighted** forwards and **`redirect` / `fixed-response`** actions, so a listener routing `/api/*` (or `api.example.com`, or `X-Tenant: acme`, or `POST` writes, or `?version=2`, or `10.0.0.0/8`) to one service and everything else to another — or returning a redirect / canned response — is reproduced locally. A **`TargetType: lambda`** target group is served by invoking the backing Lambda locally (the request is translated to the ALB `requestContext.elb` event and run through the Lambda RIE), so a forward can mix ECS and Lambda targets.
-
-```bash
-cdkl start-alb MyStack/WebAlb --lb-port 80=8080   # remap the privileged listener port 80 (macOS)
-curl http://127.0.0.1:8080/        # default action -> the default service (round-robin)
-curl http://127.0.0.1:8080/api/x   # path-pattern rule /api/* -> the api service
-```
-
-Resolution model + scope (HTTP listeners, all six ALB rule-condition fields, weighted forwards, `redirect` / `fixed-response`, ECS **and** Lambda targets): [docs/cli-reference.md](docs/cli-reference.md#cdkl-start-alb-run-an-alb-fronted-service-locally).
-
-## Override env vars without a state source
-
-When env-var values in your template are CloudFormation intrinsics (`Ref`, `Fn::GetAtt`, `Fn::ImportValue`) and you have no state source, inject literals with `--env-vars <file>` (the SAM-compatible `sam local invoke --env-vars` shape, so an existing file works unchanged). It composes with `--from-cfn-stack` — the state source resolves first, then `--env-vars` overrides only the keys you list.
-
-```bash
-cdkl invoke MyStack/Fn --event ./event.json --env-vars ./env.json
-```
+### start-service vs start-alb — which one?
 
-Format + full precedence: [docs/cli-reference.md](docs/cli-reference.md).
+`start-service` runs just the ECS service's replicas (workers, queue consumers, Service-Connect-only). `start-alb` boots the ECS service(s) behind an ALB **plus** a host-side front-door on each listener port — HTTP and HTTPS (TLS terminated locally with `--tls-cert` / `--tls-key` or an auto-generated self-signed cert) — so external traffic reaches them the way it does in the cloud. Full resolution model: [docs/cli-reference.md](docs/cli-reference.md#cdkl-start-alb-run-an-alb-fronted-service-locally).
 
 ## Supported resources
 
-| Resource | Local execution support |
-|----------|------------------------|
-| `AWS::Lambda::Function` (ZIP) | ✓ |
-| `AWS::Lambda::Function` (container image) | ✓ |
-| `AWS::Lambda::Url` | ✓ |
-| `AWS::ApiGateway::*` (REST v1) | ✓ |
-| `AWS::ApiGatewayV2::*` (HTTP API + WebSocket) | ✓ |
-| `AWS::ECS::TaskDefinition` (run-task) | ✓ |
-| `AWS::ECS::Service` (start-service) | ✓ |
-| `AWS::ServiceDiscovery::*` (Cloud Map / Service Connect) | ✓ |
-| `AWS::ElasticLoadBalancingV2::*` (start-alb: ALB front-door; all six listener-rule condition fields, weighted forward, redirect / fixed-response; ECS + Lambda targets) | ✓ |
-| `AWS::BedrockAgentCore::Runtime` (invoke-agentcore, container + fromCodeAsset/fromS3 artifacts, HTTP + MCP) | ✓ |
+| Resource | Local execution |
+|----------|-----------------|
+| Lambda functions (ZIP, container image, Function URLs) | `invoke` — every current Lambda runtime |
+| API Gateway (REST v1, HTTP v2, WebSocket) + Lambda Function URLs | `start-api` |
+| ECS task definitions | `run-task` |
+| ECS services | `start-service` |
+| Cloud Map / Service Connect registry | service discovery between local replicas |
+| ALB-fronted ECS / Lambda services | `start-alb` — HTTP / HTTPS listeners, all six listener-rule conditions, weighted forwards, redirect / fixed-response, mixed ECS + Lambda targets |
+| Bedrock AgentCore Runtime agents | `invoke-agentcore` — container + `fromCodeAsset` / `fromS3` artifacts, HTTP + MCP |
 
 Lambda runs on every current AWS Lambda runtime — Node.js (18/20/22/24), Python (3.11–3.14), Ruby (3.2/3.3), Java (8.al2/11/17/21), .NET (6/8), and the OS-only `provided.al2` / `provided.al2023`. The retired `go1.x` runtime is rejected with a pointer to migrate to `provided.al2023`.
 

package/dist/cli.js

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
 import { a as createLocalStartApiCommand } from "./cloud-map-resolver-CbSdXQjx.js";
-import { a as createLocalRunTaskCommand, i as createLocalStartServiceCommand, o as createLocalInvokeAgentCoreCommand, r as createLocalStartAlbCommand, s as createLocalInvokeCommand, t as createLocalListCommand } from "./local-list-B1RsKINr.js";
+import { a as createLocalRunTaskCommand, i as createLocalStartServiceCommand, o as createLocalInvokeAgentCoreCommand, r as createLocalStartAlbCommand, s as createLocalInvokeCommand, t as createLocalListCommand } from "./local-list-DT8qRbKy.js";
 import { Command } from "commander";
 
 //#region src/cli/index.ts
 const program = new Command();
-program.name("cdkl").description("Run AWS CDK stacks locally with Docker.").version("0.53.0");
+program.name("cdkl").description("Run AWS CDK stacks locally with Docker.").version("0.55.0");
 program.addCommand(createLocalInvokeCommand());
 program.addCommand(createLocalInvokeAgentCoreCommand());
 program.addCommand(createLocalStartApiCommand());

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../src/cli/commands/local-invoke.ts","../src/cli/commands/local-invoke-agentcore.ts","../src/cli/commands/local-run-task.ts","../src/local/target-lister.ts","../src/cli/commands/local-start-service.ts","../src/cli/commands/local-start-alb.ts","../src/cli/commands/local-list.ts","../src/local/cfn-local-state-provider.ts"],"mappings":";;;;;UA6IiB,+BAAA;EACf,mBAAA,GAAsB,mBAAA;EAEtB,WAAA,GAAc,mBAAA;AAAA;AAAA,iBAi6BA,wBAAA,CAAyB,IAAA,GAAM,+BAAA,GAAuC,OAAA;;;UC/4BrE,wCAAA;EACf,mBAAA,GAAsB,mBAAA;EAEtB,WAAA,GAAc,mBAAA;AAAA;AAAA,iBAiqCA,iCAAA,CACd,IAAA,GAAM,wCAAA,GACL,OAAA;;;UC7tCc,gCAAA;EACf,mBAAA,GAAsB,mBAAA;EAEtB,WAAA,GAAc,mBAAA;AAAA;AAAA,iBAmhBA,yBAAA,CAA0B,IAAA,GAAM,gCAAA,GAAwC,OAAA;;;UCjnBvE,WAAA;EAEf,SAAA;EAEA,SAAA;EAKA,WAAA;EAMA,WAAA;EAOA,IAAA;AAAA;AAAA,UAOe,aAAA;EAEf,OAAA,EAAS,WAAA;EAMT,IAAA,EAAM,WAAA;EAEN,WAAA,EAAa,WAAA;EAEb,kBAAA,EAAoB,WAAA;EAEpB,iBAAA,EAAmB,WAAA;EAEnB,aAAA,EAAe,WAAA;AAAA;AAAA,iBAkID,WAAA,CAAY,MAAA,WAAiB,SAAA,KAAc,aAAA;AAAA,iBAsC3C,YAAA,CAAa,OAAA,EAAS,aAAA;;;UC3MrB,qCAAA;EACf,mBAAA,GAAsB,mBAAA;EAEtB,WAAA,GAAc,mBAAA;AAAA;AAAA,iBAmCA,8BAAA,CACd,IAAA,GAAM,qCAAA,GACL,OAAA;;;UChCc,iCAAA;EACf,mBAAA,GAAsB,mBAAA;EAEtB,WAAA,GAAc,mBAAA;AAAA;AAAA,iBA0QA,0BAAA,CAA2B,IAAA,GAAM,iCAAA,GAAyC,OAAA;;;UCtQzE,6BAAA;EAEf,WAAA,GAAc,mBAAA;AAAA;AAAA,UAuCC,0BAAA;EAOf,IAAA;AAAA;AAAA,iBAYc,mBAAA,CACd,OAAA,EAAS,aAAA,EACT,OAAA,UACA,OAAA,GAAS,0BAAA;AAAA,iBAuEK,sBAAA,CAAuB,IAAA,GAAM,6BAAA,GAAqC,OAAA;;;UC/FjE,4BAAA;EAOf,YAAA;EAKA,MAAA;EAiBA,OAAA;AAAA;AAAA,cAGW,qBAAA,YAAiC,kBAAA;EAAA,SAG5B,KAAA;EAAA,iBACC,YAAA;EAAA,iBACA,MAAA;EAAA,QAKT,MAAA;EAAA,QAKA,YAAA;EAAA,QAKA,SAAA;EAAA,iBACS,aAAA;EAAA,QAQT,QAAA;cAEI,IAAA,EAAM,4BAAA;EAAA,QAOV,SAAA;EAAA,QAmBA,eAAA;EAAA,QAaA,YAAA;EA6BK,4BAAA,CACX,QAAA,EAAU,sBAAA,GACT,OAAA,CAAQ,qBAAA;EAsBE,0BAAA,CACX,kBAAA,WACC,OAAA,CAAQ,MAAA;EAmCE,IAAA,CACX,UAAA,UACA,YAAA,uBACC,OAAA,CAAQ,gBAAA;EA2DE,uBAAA,CACX,eAAA,WACC,OAAA,CAAQ,kBAAA;EA8DJ,OAAA,CAAA;AAAA"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/cli/commands/local-invoke.ts","../src/cli/commands/local-invoke-agentcore.ts","../src/cli/commands/local-run-task.ts","../src/local/target-lister.ts","../src/cli/commands/local-start-service.ts","../src/cli/commands/local-start-alb.ts","../src/cli/commands/local-list.ts","../src/local/cfn-local-state-provider.ts"],"mappings":";;;;;UA6IiB,+BAAA;EACf,mBAAA,GAAsB,mBAAA;EAEtB,WAAA,GAAc,mBAAA;AAAA;AAAA,iBAi6BA,wBAAA,CAAyB,IAAA,GAAM,+BAAA,GAAuC,OAAA;;;UCz3BrE,wCAAA;EACf,mBAAA,GAAsB,mBAAA;EAEtB,WAAA,GAAc,mBAAA;AAAA;AAAA,iBAmqCA,iCAAA,CACd,IAAA,GAAM,wCAAA,GACL,OAAA;;;UCrvCc,gCAAA;EACf,mBAAA,GAAsB,mBAAA;EAEtB,WAAA,GAAc,mBAAA;AAAA;AAAA,iBAmhBA,yBAAA,CAA0B,IAAA,GAAM,gCAAA,GAAwC,OAAA;;;UCjnBvE,WAAA;EAEf,SAAA;EAEA,SAAA;EAKA,WAAA;EAMA,WAAA;EAOA,IAAA;AAAA;AAAA,UAOe,aAAA;EAEf,OAAA,EAAS,WAAA;EAMT,IAAA,EAAM,WAAA;EAEN,WAAA,EAAa,WAAA;EAEb,kBAAA,EAAoB,WAAA;EAEpB,iBAAA,EAAmB,WAAA;EAEnB,aAAA,EAAe,WAAA;AAAA;AAAA,iBAkID,WAAA,CAAY,MAAA,WAAiB,SAAA,KAAc,aAAA;AAAA,iBAsC3C,YAAA,CAAa,OAAA,EAAS,aAAA;;;UC3MrB,qCAAA;EACf,mBAAA,GAAsB,mBAAA;EAEtB,WAAA,GAAc,mBAAA;AAAA;AAAA,iBAmCA,8BAAA,CACd,IAAA,GAAM,qCAAA,GACL,OAAA;;;UChCc,iCAAA;EACf,mBAAA,GAAsB,mBAAA;EAEtB,WAAA,GAAc,mBAAA;AAAA;AAAA,iBA2QA,0BAAA,CAA2B,IAAA,GAAM,iCAAA,GAAyC,OAAA;;;UCvQzE,6BAAA;EAEf,WAAA,GAAc,mBAAA;AAAA;AAAA,UAuCC,0BAAA;EAOf,IAAA;AAAA;AAAA,iBAYc,mBAAA,CACd,OAAA,EAAS,aAAA,EACT,OAAA,UACA,OAAA,GAAS,0BAAA;AAAA,iBAuEK,sBAAA,CAAuB,IAAA,GAAM,6BAAA,GAAqC,OAAA;;;UC/FjE,4BAAA;EAOf,YAAA;EAKA,MAAA;EAiBA,OAAA;AAAA;AAAA,cAGW,qBAAA,YAAiC,kBAAA;EAAA,SAG5B,KAAA;EAAA,iBACC,YAAA;EAAA,iBACA,MAAA;EAAA,QAKT,MAAA;EAAA,QAKA,YAAA;EAAA,QAKA,SAAA;EAAA,iBACS,aAAA;EAAA,QAQT,QAAA;cAEI,IAAA,EAAM,4BAAA;EAAA,QAOV,SAAA;EAAA,QAmBA,eAAA;EAAA,QAaA,YAAA;EA6BK,4BAAA,CACX,QAAA,EAAU,sBAAA,GACT,OAAA,CAAQ,qBAAA;EAsBE,0BAAA,CACX,kBAAA,WACC,OAAA,CAAQ,MAAA;EAmCE,IAAA,CACX,UAAA,UACA,YAAA,uBACC,OAAA,CAAQ,gBAAA;EA2DE,uBAAA,CACX,eAAA,WACC,OAAA,CAAQ,kBAAA;EA8DJ,OAAA,CAAA;AAAA"}

package/dist/index.js

@@ -1,5 +1,5 @@
 import { c as getEmbedConfig, l as resetEmbedConfig, u as setEmbedConfig } from "./docker-cmd-voNPrcRh.js";
 import { Cn as listTargets, Sn as countTargets, a as createLocalStartApiCommand, cn as createLocalStateProvider, dn as resolveCfnFallbackRegion, fn as resolveCfnRegion, gn as resolveSsmParameters, hn as collectSsmParameterRefs, in as substituteEnvVarsFromStateAsync, ln as isCfnFlagPresent, mn as CfnLocalStateProvider, nn as substituteAgainstStateAsync, pn as resolveCfnStackName, rn as substituteEnvVarsFromState, sn as LocalStateSourceError, tn as substituteAgainstState, un as rejectExplicitCfnStackWithMultipleStacks } from "./cloud-map-resolver-CbSdXQjx.js";
-import { a as createLocalRunTaskCommand, i as createLocalStartServiceCommand, n as formatTargetListing, o as createLocalInvokeAgentCoreCommand, r as createLocalStartAlbCommand, s as createLocalInvokeCommand, t as createLocalListCommand } from "./local-list-B1RsKINr.js";
+import { a as createLocalRunTaskCommand, i as createLocalStartServiceCommand, n as formatTargetListing, o as createLocalInvokeAgentCoreCommand, r as createLocalStartAlbCommand, s as createLocalInvokeCommand, t as createLocalListCommand } from "./local-list-DT8qRbKy.js";
 
 export { CfnLocalStateProvider, LocalStateSourceError, collectSsmParameterRefs, countTargets, createLocalInvokeAgentCoreCommand, createLocalInvokeCommand, createLocalListCommand, createLocalRunTaskCommand, createLocalStartAlbCommand, createLocalStartApiCommand, createLocalStartServiceCommand, createLocalStateProvider, formatTargetListing, getEmbedConfig, isCfnFlagPresent, listTargets, rejectExplicitCfnStackWithMultipleStacks, resetEmbedConfig, resolveCfnFallbackRegion, resolveCfnRegion, resolveCfnStackName, resolveSsmParameters, setEmbedConfig, substituteAgainstState, substituteAgainstStateAsync, substituteEnvVarsFromState, substituteEnvVarsFromStateAsync };