@go-to-k/cdkd 0.267.16 → 0.267.18

package/README.md

@@ -6,8 +6,9 @@
 
 Drop-in CDK CLI for existing CDK apps — up to 15x faster deploys via direct AWS SDK calls instead of CloudFormation.
 
-- **Drop-in CDK compatible**: your existing CDK app code runs as-is.
+- **Drop-in CDK compatible**: your existing CDK app code runs as-is; just replace `cdk deploy` with `cdkd deploy`.
 - **Up to 15x faster deploys**: direct SDK calls, aggressive parallelization, and `--no-wait` to skip slow stabilization waits.
+- **Faster than Terraform and CloudFormation Express mode**: wins or ties every benchmarked scenario against Terraform, and beats CloudFormation's own fast-deploy option on nearly every stack, by up to 9x (see [Benchmark](#benchmark)).
 
 ![cdk deploy vs cdkd deploy — side-by-side, 35s recording, real AWS deploy. cdkd finishes while cdk is still creating its CloudFormation changeset.](assets/cdk-vs-cdkd.gif)
 
@@ -20,11 +21,11 @@ Drop-in CDK CLI for existing CDK apps — up to 15x faster deploys via direct AW
 
 ## Benchmark
 
-**cdkd deploys up to 15x faster than AWS CDK (CloudFormation)** on SDK-Provider-handled stacks; the per-stack speedup widens with size and parallelism, and drops to ~1.5-3x on stacks dominated by Cloud Control API fallback resources.
+**cdkd deploys up to 15x faster than AWS CDK (CloudFormation)** on SDK-Provider-handled stacks; the per-stack speedup widens with size and parallelism.
 
 Numbers below are deploy-phase only (CDK app synthesis is identical between cdkd and AWS CDK — both run the same user code through `aws-cdk-lib`'s synthesizer — so synth time is excluded from the speedup calculation).
 
-### vs CloudFormation Express mode — faster than CloudFormation's own fast-deploy option
+### vs CloudFormation Express mode: up to 9x faster
 
 CloudFormation's [Express mode](https://aws.amazon.com/about-aws/whats-new/2026/06/aws-cloudformation-cdk/) is a fast-deploy option that skips resource stabilization waits, similar in spirit to cdkd's `--no-wait`. Even so, cdkd is faster than Express on nearly every stack, and with `--no-wait` it pulls dramatically ahead on stacks dominated by async resources.
 
@@ -45,49 +46,84 @@ Best of 3 runs, deploy-phase only, seconds, `us-west-2`. The `VPC + Lambda + SQS
 - **Async-heavy stacks are where the gap explodes.** On the VPC + CloudFront stack, `cdkd --no-wait` finishes in 40s vs Express's 366s (~9x) — cdkd returns as soon as each create call returns, leaving CloudFront propagation and NAT Gateway stabilization to complete in the background.
 - **S3 is the one case where Express edges cdkd's default** (22s vs 23s). On a near-instant single-resource stack there is little left to parallelize, and `--no-wait` makes no difference there.
 
-### SDK Provider path — **5.5x faster** (17.0s vs 94.4s)
+### vs Terraform: cdkd wins or ties every scenario
 
-Stack: S3 Bucket, DynamoDB Table, SQS Queue, SNS Topic, SSM Parameter (5 independent resources, fully parallelized by cdkd's DAG scheduler).
+We also raced cdkd against Terraform: the same logical stacks expressed both as CDK apps and as Terraform HCL, deployed by all engines against real AWS.
 
-| | AWS CDK (CFn) | cdkd | Speedup |
-| --- | ---: | ---: | ---: |
-| Deploy | **94.4s** | **17.0s** | **5.5x** |
+| Scenario | Stack | cdkd | cdkd `--no-wait` | Terraform | CloudFormation |
+| --- | --- | ---: | ---: | ---: | ---: |
+| wide | 48 independent resources (S3 / DynamoDB / SQS / SNS / SSM / Logs, 8 each) | **25.4** | 25.3 | 50.4 | 85.9 |
+| serverless | Lambda ×3 + HTTP API + DynamoDB + SNS / SQS + EventBridge | **31.4** | 31.8 | 57.9 | 124.2 |
+| webapp | VPC + NAT + subnets + DynamoDB + SQS + S3 + Lambda ×2 + HTTP API | 127.0 | **32.4** | 127.8 | 161.9 |
+| cloudfront | S3 origin + CloudFront + OAC | **171.2** | **17.8** | 191.1 | 208.1 |
 
-### VPC + CloudFront + Lambda stack — **15x faster with `--no-wait`** (40s vs 599s)
+Cold end-to-end wall clock (unlike the deploy-phase-only tables above, these numbers include synth / plan), median of 3 runs, seconds, `us-east-1`. On wide, parallel stacks cdkd is ~2x faster than Terraform; where a single slow resource dominates (NAT Gateway, CloudFront propagation), physical provisioning time sets a common floor and only `--no-wait` gets below it. Full methodology, parity notes, and reproduction scripts live in [cdkd-bench-terraform](https://github.com/go-to-k/cdkd-bench-terraform).
 
-Real-world stack: 1 VPC (2 AZs, NAT Gateway, public + private subnets) + Lambda Function (with `VpcConfig`) + Lambda Function URL (AWS_IAM) + CloudFront Distribution (OAC, caching disabled) + SQS Queue + EventSourceMapping + Consumer Lambda.
+### More benchmarks
 
-| | AWS CDK (CFn) | cdkd | cdkd `--no-wait` |
-| --- | ---: | ---: | ---: |
-| Deploy | **599s** | 197s (3.0x) | **40s (15.0x)** |
+The full benchmark suite lives in [docs/benchmarks.md](docs/benchmarks.md): the SDK Provider path (**5.5x**, 17.0s vs 94.4s), the VPC + CloudFront + Lambda stack behind the headline **15x** (40s vs 599s with `--no-wait`), the Cloud Control API fallback path (**1.6x**), and the Terraform comparison in full detail. Reproduction scripts: [tests/benchmark](tests/benchmark/README.md).
 
-The 15x figure requires `cdkd deploy --no-wait`, which returns as soon as each Create call returns and lets AWS finish CloudFront's ~5min propagation + NAT Gateway stabilization in the background. cdkd's default scheduler already parallelizes `CloudFront::Distribution` / `Lambda::Url` / VPC Lambda with NAT Gateway propagation (pass `--no-aggressive-vpc-parallel` to opt out); on this stack the default gives ~3x. `--no-wait` adds the rest of the gap by skipping the propagation waits entirely.
+## Prerequisites
 
-### Cloud Control API fallback path — **1.6x faster** (40.9s vs 64.9s)
+- **Node.js** >= 20.0.0
+- **AWS credentials with admin-equivalent permissions** for the resources being deployed. cdkd does NOT route through CloudFormation, so CDK CLI's `cdk-hnb659fds-deploy-role-*` is NOT sufficient — see [`--role-arn`](docs/cli-reference.md).
 
-Stack: SSM Document × 3 + Athena WorkGroup × 2 (no SDK provider — CC API fallback).
+AWS CDK's `cdk bootstrap` is not required. Instead, run `cdkd bootstrap` once per
+account: it creates everything cdkd needs, and per-region asset storage is added
+automatically on the first `cdkd deploy` into each region. Existing setups,
+legacy-mode opt-outs, and how this relates to `cdk bootstrap`: see
+[Upgrading from an earlier cdkd version](#upgrading-from-an-earlier-cdkd-version).
 
-| | AWS CDK (CFn) | cdkd | Speedup |
-| --- | ---: | ---: | ---: |
-| Deploy | **64.9s** | **40.9s** | **1.6x** |
+## Installation
 
-Reproduce the first two with `./tests/benchmark/run-benchmark.sh all`. See [tests/benchmark/README.md](tests/benchmark/README.md) for details.
+```bash
+npm i -g @go-to-k/cdkd          # latest release
+npm i -g @go-to-k/cdkd@0.0.2    # pin to a specific version
+```
 
-### Reference point: Terraform
+The installed binary is `cdkd`.
 
-"Faster than CloudFormation" is a low bar, so we also raced cdkd against Terraform: the same logical stacks expressed both as CDK apps and as Terraform HCL, deployed by all engines against real AWS. Full methodology, parity notes, and reproduction scripts live in [cdkd-bench-terraform](https://github.com/go-to-k/cdkd-bench-terraform).
+## Quick Start
 
-| Scenario | Stack | cdkd | cdkd `--no-wait` | Terraform | CloudFormation |
-| --- | --- | ---: | ---: | ---: | ---: |
-| wide | 48 independent resources (S3 / DynamoDB / SQS / SNS / SSM / Logs, 8 each) | **25.4** | 25.3 | 50.4 | 85.9 |
-| serverless | Lambda ×3 + HTTP API + DynamoDB + SNS / SQS + EventBridge | **31.4** | 31.8 | 57.9 | 124.2 |
-| webapp | VPC + NAT + subnets + DynamoDB + SQS + S3 + Lambda ×2 + HTTP API | 127.0 | **32.4** | 127.8 | 161.9 |
-| cloudfront | S3 origin + CloudFront + OAC | **171.2** | 17.8 | 191.1 | 208.1 |
+> **First-time setup**: cdkd requires a one-time `cdkd bootstrap` per AWS
+> account before any other command will work — it creates the S3 state
+> bucket (`cdkd-state-{accountId}`) that cdkd uses to track deployed
+> resources, plus cdkd-owned asset storage for the region
+> (by default a `cdkd-assets-{accountId}-{region}` bucket +
+> `cdkd-container-assets-{accountId}-{region}` ECR repo — custom names via
+> `--asset-bucket` / `--container-repo`, skip with `--no-assets`; see
+> [`cdkd bootstrap`](docs/cli-reference.md#cdkd-bootstrap)).
+> This replaces `cdk bootstrap`, which cdkd does not require — see
+> [Prerequisites](#prerequisites).
+
+```bash
+# Bootstrap (creates S3 state bucket + asset storage — one-time setup per AWS account)
+cdkd bootstrap
+
+# List stacks in the CDK app
+cdkd list
+
+# Deploy your CDK app
+cdkd deploy
+
+# Check what would change
+cdkd diff
 
-Cold end-to-end wall clock, median of 3 runs, seconds, `us-east-1`, cdkd v0.260.10. Unlike the tables above, these numbers include synth (cdkd / CDK) and plan (Terraform); one-time setup (`npm install` / `cdk bootstrap` / `terraform init`) is excluded for all tools. For parity, CDK-only extras (the `restrictDefaultSecurityGroup` custom resource and CDK-managed log groups) were disabled so cdkd / CloudFormation don't carry resources the Terraform config doesn't have.
+# Tear down
+cdkd destroy
+```
+
+That's it. cdkd reads `--app` from `cdk.json` and auto-resolves the state bucket from your AWS account ID (`cdkd-state-{accountId}`). If you bootstrapped under a previous cdkd version, the legacy region-suffixed name (`cdkd-state-{accountId}-{region}`) is still picked up automatically with a deprecation warning.
+
+### Upgrading from an earlier cdkd version
 
-- **The winner depends on the stack's shape.** On wide, parallel stacks (wide, serverless) cdkd is ~2x faster than Terraform. Where a single slow resource dominates (webapp's NAT Gateway, cloudfront's propagation), physical provisioning time sets a common floor: webapp is a true tie (0.8s apart), and only `--no-wait` gets below the floor.
-- **This benchmark also made cdkd faster.** Chasing the initial webapp / cloudfront losses surfaced four real deploy-speed bugs (longest-pole scheduling, a missing EIP SDK provider, NAT Gateway and CloudFront polling intervals), fixed in [#1175](https://github.com/go-to-k/cdkd/pull/1175) and [#1177](https://github.com/go-to-k/cdkd/pull/1177). The numbers above are from the fixed version.
+**No breaking change, no manual step: just deploy.** The first `cdkd deploy` into
+each region auto-creates the cdkd-owned asset storage (interactive runs are asked
+once per region, `--yes` / CI runs create it automatically) and shows a one-time
+in-place UPDATE repointing asset references — content identical, no replacement.
+Downgrading is safe too (older binaries ignore the marker). Explicit pre-provisioning
+(`cdkd bootstrap --region <r>`), legacy-mode opt-outs, and how this relates to
+`cdk bootstrap`: see [`cdkd bootstrap`](docs/cli-reference.md#cdkd-bootstrap).
 
 ## Features
 
@@ -99,7 +135,7 @@ Cold end-to-end wall clock, median of 3 runs, seconds, `us-east-1`, cdkd v0.260.
 - **S3-based state management**: No DynamoDB required, uses S3 conditional writes for locking
 - **DAG-based parallelization**: Analyze `Ref`/`Fn::GetAtt` dependencies and execute in parallel
 - **Rollback on failure**: When a deploy errors mid-stack, cdkd rolls back the resources it just created so the stack state stays consistent (CloudFormation parity — but cdkd does this without round-tripping through CFn). Pass `cdkd deploy --no-rollback` to skip rollback and keep the partial state for Terraform-style inspection / repair — then either fix forward with another `cdkd deploy`, revert with the standalone `cdkd rollback`, or `cdkd destroy` to clean up. See [Rollback behavior](#rollback-behavior).
-- **`--no-wait` for async resources**: Skip the multi-minute wait on CloudFront / RDS / ElastiCache / NAT Gateway / Lambda MicroVM Image and return as soon as the create call returns (CloudFormation always blocks)
+- **`--no-wait` / `--full-wait` for async resources**: `--no-wait` skips the multi-minute wait on CloudFront / RDS / ElastiCache / NAT Gateway / EC2 Instance / ELBv2 LoadBalancer / Lambda MicroVM Image and returns as soon as the create call returns (CloudFormation always blocks); `--full-wait` goes the other way and also waits where only CloudFormation does (ECS Service steady state)
 - **VPC route DependsOn relaxation (on by default)**: Drop CDK-injected defensive `DependsOn` edges from VPC Lambdas onto private-subnet routes so `CloudFront::Distribution` and `Lambda::Url` start their ~3-min propagation in parallel with NAT Gateway stabilization (~50% faster on VPC + Lambda + CloudFront stacks). Pass `--no-aggressive-vpc-parallel` to opt out.
 - **Local execution** (`cdkd local invoke` / `start-api` / `run-task` / `start-service` / `start-alb` / `start-cloudfront` / `invoke-agentcore` / `start-agentcore`): run Lambdas, API Gateway routes, ECS tasks, long-running ECS services, CloudFront distributions, and Bedrock AgentCore Runtimes from your CDK code. All AWS Lambda runtimes, container Lambdas, REST v1 / HTTP v2 / Function URL routes, Service Connect / Cloud Map, AgentCore HTTP / MCP / A2A / AGUI / WebSocket protocols (one-shot `invoke-agentcore` and long-running warm serve via `start-agentcore`, which serves the native contract — `POST /invocations` + `GET /ping`, MCP `/mcp`, A2A `/` — plus the `/ws` bridge for HTTP / AGUI). The Docker-backed commands work for both `cdkd deploy`-managed (`--from-state`) AND `cdk deploy`-managed (`--from-cfn-stack`) stacks; `start-cloudfront` serves the viewer-request -> S3 / Lambda Function URL origin -> viewer-response pipeline (CloudFront-Functions + S3-only distributions run in-process with no Docker). See [Local execution](#local-execution).
 - **Bidirectional CloudFormation migration**: `cdkd import --migrate-from-cloudformation` adopts existing CFn stacks (including `cdk deploy`-managed) into cdkd state without re-creating resources; `cdkd export` hands a cdkd stack back to CloudFormation when production-ready. See [Importing](#importing-existing-resources) / [Exporting](#exporting-a-stack-back-to-cloudformation).
@@ -151,68 +187,6 @@ For a step-by-step walkthrough of the full `cdkd deploy` pipeline (CLI
 parsing → synthesis → asset publishing → per-stack deploy), see
 [docs/architecture.md](docs/architecture.md#5-end-to-end-pipeline-walkthrough-cdkd-deploy).
 
-## Prerequisites
-
-- **Node.js** >= 20.0.0
-- **AWS credentials with admin-equivalent permissions** for the resources being deployed. cdkd does NOT route through CloudFormation, so CDK CLI's `cdk-hnb659fds-deploy-role-*` is NOT sufficient — see [`--role-arn`](docs/cli-reference.md).
-
-AWS CDK's `cdk bootstrap` is not required. Instead, run `cdkd bootstrap` once per
-account: it creates everything cdkd needs, and per-region asset storage is added
-automatically on the first `cdkd deploy` into each region. Existing setups,
-legacy-mode opt-outs, and how this relates to `cdk bootstrap`: see
-[Upgrading from an earlier cdkd version](#upgrading-from-an-earlier-cdkd-version).
-
-## Installation
-
-```bash
-npm i -g @go-to-k/cdkd          # latest release
-npm i -g @go-to-k/cdkd@0.0.2    # pin to a specific version
-```
-
-The installed binary is `cdkd`.
-
-## Quick Start
-
-> **First-time setup**: cdkd requires a one-time `cdkd bootstrap` per AWS
-> account before any other command will work — it creates the S3 state
-> bucket (`cdkd-state-{accountId}`) that cdkd uses to track deployed
-> resources, plus cdkd-owned asset storage for the region
-> (by default a `cdkd-assets-{accountId}-{region}` bucket +
-> `cdkd-container-assets-{accountId}-{region}` ECR repo — custom names via
-> `--asset-bucket` / `--container-repo`, skip with `--no-assets`; see
-> [`cdkd bootstrap`](docs/cli-reference.md#cdkd-bootstrap)).
-> This replaces `cdk bootstrap`, which cdkd does not require — see
-> [Prerequisites](#prerequisites).
-
-```bash
-# Bootstrap (creates S3 state bucket + asset storage — one-time setup per AWS account)
-cdkd bootstrap
-
-# List stacks in the CDK app
-cdkd list
-
-# Deploy your CDK app
-cdkd deploy
-
-# Check what would change
-cdkd diff
-
-# Tear down
-cdkd destroy
-```
-
-That's it. cdkd reads `--app` from `cdk.json` and auto-resolves the state bucket from your AWS account ID (`cdkd-state-{accountId}`). If you bootstrapped under a previous cdkd version, the legacy region-suffixed name (`cdkd-state-{accountId}-{region}`) is still picked up automatically with a deprecation warning.
-
-### Upgrading from an earlier cdkd version
-
-**No breaking change, no manual step: just deploy.** The first `cdkd deploy` into
-each region auto-creates the cdkd-owned asset storage (interactive runs are asked
-once per region, `--yes` / CI runs create it automatically) and shows a one-time
-in-place UPDATE repointing asset references — content identical, no replacement.
-Downgrading is safe too (older binaries ignore the marker). Explicit pre-provisioning
-(`cdkd bootstrap --region <r>`), legacy-mode opt-outs, and how this relates to
-`cdk bootstrap`: see [`cdkd bootstrap`](docs/cli-reference.md#cdkd-bootstrap).
-
 ## Usage
 
 cdkd has three command families:
@@ -245,6 +219,7 @@ cdkd deploy --dry-run               # plan only, no changes
 cdkd deploy --no-rollback           # Terraform-style: keep partial state on failure
 cdkd rollback MyStack               # revert a failed --no-rollback / interrupted deploy
 cdkd deploy --no-wait               # skip multi-minute waits (CloudFront / RDS / NAT)
+cdkd deploy --full-wait             # also wait where only CFn does (ECS Service steady state)
 
 # Inspect what would change
 cdkd diff MyStack
@@ -282,19 +257,32 @@ matrix (`--concurrency`, `--no-aggressive-vpc-parallel`,
 including the synth-driven per-resource `cdkd orphan <constructPath>`
 variant, and stage / wildcard pattern matching.
 
-## `--no-wait`: skip async-resource waits
+## `--no-wait` / `--full-wait`: choose what "done" means
+
+CloudFront / RDS / ElastiCache / NAT Gateway / EC2 Instance / ELBv2
+LoadBalancer typically take 1–15 minutes to fully provision. Three
+modes, least to most waiting:
+
+- **`--no-wait`** returns as soon as the create call returns and lets
+  AWS finish in the background.
+- **default** waits where CloudFormation and Terraform agree on what
+  "done" means.
+- **`--full-wait`** additionally waits where only CloudFormation waits
+  (today: ECS Service steady state).
+
+Pick by whether anything downstream needs the resource to actually be
+serving, not by where the deploy runs — cutting billed CI minutes is a
+perfectly good reason to use `--no-wait` in CI, and a local smoke test
+is a good reason to use `--full-wait` on a laptop. The two flags are
+opposite ends of one axis and cannot be combined.
 
-CloudFront / RDS / ElastiCache / NAT Gateway typically take 1–15
-minutes to fully provision. By default cdkd waits (matching CFn).
-`cdkd deploy --no-wait` returns as soon as the create call returns
-and lets AWS finish in the background — handy for CI where nothing
-in the deploy flow needs the resource fully active. **Deploy-only**:
-`cdkd destroy` always waits (NAT in `deleting` state holds ENIs and
-would `DependencyViolation` sibling deletes).
+**Deploy-only**: `cdkd destroy` always waits (NAT in `deleting` state
+holds ENIs and would `DependencyViolation` sibling deletes).
 
-See [docs/cli-reference.md](docs/cli-reference.md#--no-wait-skip-async-resource-waits)
-for per-resource caveats (NAT egress, RDS final-snapshot timing,
-etc.).
+See [docs/cli-reference.md](docs/cli-reference.md#wait-semantics) for
+the per-resource table (what each mode does, next to what
+CloudFormation and Terraform do) and caveats (NAT egress, RDS
+final-snapshot timing, etc.).
 
 ## Local execution
 

package/dist/{asg-provider-Ge0MCN5U.js → asg-provider-C6uxCStq.js}

@@ -1,4 +1,4 @@
-import { E as clearOnUpdateRemoval, L as normalizeAwsTagsToCfn, fn as __exportAll, j as disableInstanceApiTermination, rn as ResourceUpdateNotSupportedError, tn as ProvisioningError, z as assertRegionMatch } from "./deploy-engine-BjGr3po1.js";
+import { E as clearOnUpdateRemoval, L as normalizeAwsTagsToCfn, fn as __exportAll, j as disableInstanceApiTermination, rn as ResourceUpdateNotSupportedError, tn as ProvisioningError, z as assertRegionMatch } from "./deploy-engine-D_KHeGjJ.js";
 import { n as getLogger, u as generateResourceName } from "./logger-BYMEE-BS.js";
 import { EC2Client } from "@aws-sdk/client-ec2";
 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";
@@ -810,4 +810,4 @@ function mapNotificationsToCfn(configurations) {
 
 //#endregion
 export { asg_provider_exports as n, ASGProvider as t };
-//# sourceMappingURL=asg-provider-Ge0MCN5U.js.map
+//# sourceMappingURL=asg-provider-C6uxCStq.js.map