@go-to-k/cdkd 0.50.0 → 0.50.1

package/README.md

@@ -170,57 +170,7 @@ the full per-type table.
 | Attribute enrichment | ✅ | CloudFront OAI, DynamoDB StreamArn, API Gateway RootResourceId, Lambda FunctionUrl, Route53 HealthCheckId, ECR Repository Arn |
 | CC API null value stripping | ✅ | Removes null values before API calls |
 | Retry with HTTP status codes | ✅ | 429/503 + cause chain inspection |
-
-### Drift detection
-
-`cdkd drift <stack>` (state-driven; no synth) compares each resource
-between the AWS-current snapshot returned by `provider.readCurrentState`
-and the **deploy-time AWS snapshot** stored in
-`ResourceState.observedProperties`. The observedProperties baseline is
-populated automatically on every successful `cdkd deploy` /
-`cdkd import`, so console-side changes to keys you did NOT template
-(IAM policies attached out-of-band, S3 public-access-block toggled,
-etc.) surface as drift instead of being silently ignored.
-
-State schema `version: 3` (the layout that carries observedProperties)
-is auto-migrated on the next write — no user action needed for new
-deploys. **For stacks already deployed with an older binary**, the
-upgrade story is:
-
-1. `cdkd 0.46.x` (or earlier) deployed your stack — state.json is
-   `version: 2`, no observedProperties on any resource.
-2. Upgrade cdkd to `0.47.0+`. The new binary reads v2 state cleanly,
-   and `cdkd drift` falls back to comparing against the user-templated
-   `properties` field (= the pre-v3 behavior) for any resource that
-   hasn't been refreshed yet.
-3. **Populate observedProperties** for the existing stack — pick one:
-
-   ```bash
-   # Option A (recommended): explicit refresh, no redeploy.
-   cdkd state refresh-observed MyStack
-
-   # Option B: trigger an UPDATE on each affected resource via the
-   # next `cdkd deploy`. NO_CHANGE-skipped resources are NOT refreshed
-   # by deploy alone — only the ones whose template changed get a
-   # readCurrentState call. Use this only if you're already changing
-   # the template; for an upgrade-and-refresh-only flow prefer A.
-   cdkd deploy MyStack
-   ```
-4. Re-run `cdkd drift MyStack` — now observed-baseline drift detection
-   is fully enabled.
-
-`cdkd state refresh-observed --all` does the same for every stack in
-the state bucket; `--dry-run` prints the per-stack refresh count
-without touching state. Resolve any drift the comparator finds with
-`cdkd drift <stack> --accept` (state ← AWS) or `--revert` (AWS ← state).
-
-`cdkd deploy --no-capture-observed-state` (or
-`cdk.json context.cdkd.captureObservedState: false`) opts out of the
-capture entirely if you care more about deploy speed than rich drift
-detection — drift then falls back to comparing against `properties`,
-the pre-v3 behavior. Bench measurements show roughly +0–4% deploy
-time with the capture on (lambda integ within noise; bench-cdk-sample
-+3.4% median).
+| Drift detection | ✅ | `cdkd drift` — state vs AWS reality, including console-side changes to keys you didn't template. See [Drift detection](#drift-detection) below. |
 
 ## Prerequisites
 
@@ -287,6 +237,18 @@ That's it. cdkd reads `--app` from `cdk.json` and auto-resolves the state bucket
 
 ## Usage
 
+cdkd has two command families:
+
+- **Top-level commands** (`cdkd deploy` / `destroy` / `diff` / `synth` /
+  `list` / `import` / `orphan`) require a CDK app — they synthesize
+  a template to learn what they're operating on.
+- **`cdkd state ...` subcommands** (`state info` / `list` / `resources`
+  / `show` / `orphan` / `destroy` / `migrate` / `refresh-observed`)
+  operate on the S3 state bucket only and do NOT need the CDK app —
+  use them to inspect / clean up state when the source is gone or
+  you don't want to synth. `cdkd state destroy` is the CDK-app-free
+  counterpart of `cdkd destroy`.
+
 Options like `--app`, `--state-bucket`, and `--context` can be omitted if configured via `cdk.json` or environment variables (`CDKD_APP`, `CDKD_STATE_BUCKET`).
 
 ```bash
@@ -368,6 +330,12 @@ cdkd deploy --no-rollback
 # Deploy only the specified stack (skip dependency auto-inclusion)
 cdkd deploy -e MyStack
 
+# Skip the multi-minute wait on async resources (CloudFront, RDS, NAT GW, etc.)
+cdkd deploy --no-wait
+
+# Synth + build + publish assets only (no deploy) — typical CI split
+cdkd publish-assets
+
 # Destroy resources
 cdkd destroy MyStack
 cdkd destroy --all --force
@@ -429,183 +397,33 @@ cdkd state destroy --all -y           # every stack in the bucket
 cdkd state destroy MyStack --region us-east-1
 ```
 
-> **`destroy` vs `orphan`** (matches aws-cdk-cli's new `cdk orphan`):
-> `destroy` deletes the AWS resources AND the state record. `orphan` deletes
-> ONLY the state record — AWS resources remain intact, just no longer
-> tracked by cdkd.
->
-> The two `orphan` variants now operate at different granularities:
->
-> - `cdkd orphan <constructPath>...` — synth-driven, **per-resource**.
->   Removes specific resources from a stack's state file and rewrites every
->   sibling reference (Ref / Fn::GetAtt / Fn::Sub / dependencies) so the
->   next deploy doesn't re-create the orphan or fail on a stale reference.
->   Mirrors `cdk orphan --unstable=orphan`.
-> - `cdkd state orphan <stack>...` — state-driven, **whole-stack**. Removes
->   the entire state record for a stack from the bucket. Works without the
->   CDK app.
->
-> `cdkd destroy` (synth-driven, deletes AWS resources + state) and
-> `cdkd state destroy` (state-driven, same effect) round out the matrix.
-
-## `publish-assets`: synth + build + publish, no deploy
-
-`cdkd publish-assets` runs the asset half of the deploy pipeline only —
-synthesize the CDK app, build any Docker images, upload file assets to
-S3, push images to ECR — and stops. No state writes, no provisioning,
-no lock acquisition. This is the typical CI split where one runner
-builds and uploads assets and a separate runner deploys.
-
-```bash
-cdkd publish-assets                          # synth + publish all stacks (or auto-detect single stack)
-cdkd publish-assets MyStack                  # synth + publish a specific stack
-cdkd publish-assets --all                    # synth + publish every stack in the app
-cdkd publish-assets 'MyStage/*'              # wildcard (CDK display path)
-cdkd publish-assets -a cdk.out               # skip synth — use a pre-synthesized cloud assembly
-```
-
-Stack selection follows the same rules as `deploy` / `diff` / `destroy`
-(positional > `--stack` > `--all` > auto-detect). Concurrency knobs
-are `--asset-publish-concurrency` and `--image-build-concurrency`.
-`-a/--app` accepts either a shell command (`"npx ts-node app.ts"`) or
-a path to an already-synthesized cloud assembly directory; pointing at
-`cdk.out` skips synthesis. See [docs/cli-reference.md](docs/cli-reference.md#publish-assets-synth--build--publish-no-deploy)
-for details.
-
 ## `--no-wait`: skip async-resource waits
 
-CloudFront Distributions, RDS Clusters/Instances, ElastiCache, and
-NAT Gateways typically take 1–15 minutes for AWS to fully provision.
-By default cdkd waits for them to reach a ready state — the same
-behavior as CloudFormation. Pass `--no-wait` to return as soon as the
-create call returns:
-
-```bash
-cdkd deploy --no-wait
-```
+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).
 
-The resource is fully functional once AWS finishes the async
-deployment in the background. CloudFormation has no equivalent — once
-you submit a stack, you wait for everything.
-
-NAT Gateway is included as of v0.31. Provisioning typically takes
-1–2 minutes and is the dominant cost in many VPC stacks; with
-`cdkd deploy --no-wait`, `CreateNatGateway` returns the `NatGatewayId`
-immediately and dependent Routes that only reference the ID can
-proceed against a still-`pending` gateway. AWS continues NAT
-provisioning asynchronously after the deploy returns. Use this only
-when nothing in the deploy flow needs actual NAT-routed egress (e.g.
-no Lambda invoked during deploy that hits the internet).
-
-`--no-wait` is **deploy-only**. `cdkd destroy` always waits for NAT
-Gateway to reach `deleted` state — while the gateway is in
-`deleting` AWS keeps the ENI / EIP / route-table associations
-attached, so any concurrent `DeleteSubnet` / `DeleteInternetGateway`
-/ `DeleteVpc` returns `DependencyViolation` and the destroy enters a
-retry storm. Other `--no-wait` resources (CloudFront / RDS /
-ElastiCache) don't apply to destroy either — their providers are
-already non-blocking on delete because they're leaves in the destroy
-DAG.
+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.).
 
 ## VPC route DependsOn relaxation (on by default)
 
-CDK synth eagerly injects `DependsOn` from VPC Lambdas (and adjacent
-IAM Role / Policy / Lambda::Url / EventSourceMapping resources) onto
-the private subnet's `DefaultRoute` / `RouteTableAssociation` so that
-nothing tries to invoke the Lambda before its egress path to the
-internet is up. The dependency is real at *runtime* (a Lambda code
-call to a third-party API can't reach the internet without a NAT
-route), but it is NOT required at *deploy time* — `CreateFunction` /
-`CreateFunctionUrlConfig` / `AddPermission` /
-`CreateEventSourceMapping` all accept a function in `Pending` state.
-
-For VPC + Lambda + CloudFront stacks the strict-CDK-ordering chain is serial:
-
-```text
-NAT GW (~2-3 min) → DefaultRoute → Lambda → Lambda::Url → Distribution propagation (~3 min)
-```
-
-cdkd drops the route DependsOn by default so Distribution + Lambda::Url
-dispatch right after IAM Role / Subnet are ready and propagate in
-parallel with NAT stabilization:
-
-| Mode | Critical path | Total |
-| --- | --- | --- |
-| `--no-aggressive-vpc-parallel` (opt-out) | NAT → Lambda → CF (serial) | ~6 min |
-| **default** | max(NAT, CF) | **~3 min** |
-
-Measured **−54.6%** on `tests/integration/bench-cdk-sample` (398.59s
-with `--no-aggressive-vpc-parallel` → 181.03s default).
-
-To opt out (e.g. for a stack with a Custom Resource that synchronously
-invokes a VPC Lambda outside cdkd's Lambda-ServiceToken Active wait):
-
-```bash
-cdkd deploy --no-aggressive-vpc-parallel
-```
-
-Deploy-only — the relaxation has no effect on destroy ordering (the
-route DependsOn doesn't constrain delete-time correctness; Lambda
-hyperplane ENI release is the actual destroy bottleneck and is handled
-separately by `lambda-vpc-deps.ts`).
+CDK injects defensive `DependsOn` from VPC Lambdas onto private-subnet
+routes. The dependency is real at runtime but NOT required at deploy
+time. cdkd drops it by default so CloudFront + Lambda::Url propagation
+runs in parallel with NAT stabilization (~50% faster on VPC+Lambda+CloudFront
+stacks; bench-cdk-sample 398s → 181s). Pass
+`cdkd deploy --no-aggressive-vpc-parallel` to opt out (e.g. when a
+Custom Resource synchronously invokes a VPC Lambda outside cdkd's
+Lambda-ServiceToken Active wait).
 
 See [docs/cli-reference.md](docs/cli-reference.md) for the full
-type-pair allowlist, implementation pointers, and trade-off notes.
-
-## Other CLI flags
-
-For concurrency knobs (`--concurrency`, `--stack-concurrency`,
-`--asset-publish-concurrency`, `--image-build-concurrency`) and
-per-resource timeout flags (`--resource-warn-after`,
-`--resource-timeout` — including the per-resource-type override syntax
-and the rationale for the 30m default), see
-**[docs/cli-reference.md](docs/cli-reference.md)**.
-
-## Exit codes
-
-cdkd commands distinguish three outcomes via the process exit code so
-CI / bench scripts can react without grepping log output:
-
-| Exit | Meaning |
-|------|---------|
-| `0` | Success — command completed and no resources are in an error state |
-| `1` | Command-level failure — auth error, bad arguments, synth crash, unhandled exception |
-| `2` | **Partial failure** — work completed but one or more resources failed (state.json is preserved, re-running typically resolves it) |
-
-Exit `2` is currently emitted by `cdkd destroy` and `cdkd state
-destroy` when one or more per-resource deletes fail. The summary line
-also switches from `✓ Stack X destroyed` to `⚠ Stack X partially
-destroyed (...). State preserved — re-run 'cdkd destroy' / 'cdkd
-state destroy' to clean up.` so the visual marker matches the exit
-code.
-
-## Example
-
-```typescript
-const table = new dynamodb.Table(stack, 'Table', {
-  partitionKey: { name: 'id', type: dynamodb.AttributeType.STRING },
-});
-const fn = new lambda.Function(stack, 'Handler', {
-  runtime: lambda.Runtime.NODEJS_20_X,
-  handler: 'index.handler',
-  code: lambda.Code.fromAsset('lambda'),
-  environment: { TABLE_NAME: table.tableName },
-});
-table.grantReadWriteData(fn);
-```
-
-```bash
-$ cdkd deploy
-LambdaStack
-  ServiceRole     CREATE  AWS::IAM::Role             ✓  (2.1s)
-  Table           CREATE  AWS::DynamoDB::Table        ✓  (1.8s)
-  DefaultPolicy   CREATE  AWS::IAM::Policy            ✓  (1.5s)
-  Handler         CREATE  AWS::Lambda::Function       ✓  (3.4s)
-
-✓ Deployed LambdaStack (4 resources, 7.2s)
-```
-
-Resources are dispatched as soon as their own dependencies complete (event-driven DAG). ServiceRole and Table run in parallel; DefaultPolicy starts the moment ServiceRole is done — without waiting for Table — and Handler starts the moment DefaultPolicy is done.
+type-pair allowlist and trade-off notes.
 
 ## Importing existing resources
 
@@ -629,6 +447,61 @@ modes (auto / selective / hybrid), `--resource-mapping` CDK CLI
 compatibility, CloudFormation migration flow, provider coverage, and the
 parity matrix vs upstream `cdk import`.
 
+## Drift detection
+
+`cdkd drift` (state-driven; no synth) compares each managed resource
+against AWS reality and reports divergence — including console-side
+changes to keys you did NOT template (S3 public-access-block, IAM Role
+tags, Lambda env keys, etc.).
+
+```bash
+cdkd drift                       # auto-detect single stack, exit 1 if drift
+cdkd drift MyStack --json        # machine-readable, for CI gating
+cdkd drift MyStack --accept --yes   # state ← AWS (catch up after a console edit)
+cdkd drift MyStack --revert --yes   # AWS ← state (undo a console edit)
+cdkd state refresh-observed MyStack # populate the drift baseline without redeploying
+```
+
+See **[docs/cli-reference.md `cdkd drift`](docs/cli-reference.md#cdkd-drift)**
+for the full reference: `--no-capture-observed-state` deploy opt-out
+(per-command vs per-project, mid-flight reversibility), v2→v3 state
+upgrade flow, exit codes, and what changes when capture is off.
+
+## Orphan vs destroy
+
+`destroy` deletes the AWS resources **and** the state record;
+`orphan` deletes **only** the state record (AWS resources stay
+intact, just no longer tracked by cdkd). Mirrors aws-cdk-cli's
+`cdk orphan`.
+
+Two `orphan` variants at different granularities:
+
+- `cdkd orphan <constructPath>...` — synth-driven, **per-resource**.
+  Rewrites every sibling reference (Ref / Fn::GetAtt / Fn::Sub /
+  dependencies) so the next deploy doesn't re-create the orphan.
+- `cdkd state orphan <stack>...` — state-driven, **whole-stack**.
+  Removes the entire state record. Works without the CDK app.
+
+Both `cdkd destroy` (synth-driven) and `cdkd state destroy`
+(state-driven, no synth) delete AWS resources + state.
+
+## `publish-assets`: synth + build + publish, no deploy
+
+`cdkd publish-assets` runs the asset half of the deploy pipeline
+only — synthesize, build Docker images, upload file assets to S3,
+push images to ECR — and stops. No state writes, no provisioning.
+Typical CI split where one runner builds + uploads assets and a
+separate runner deploys.
+
+```bash
+cdkd publish-assets                  # all stacks (or auto-detect single stack)
+cdkd publish-assets MyStack          # specific stack
+cdkd publish-assets -a cdk.out       # skip synth, use pre-synthesized assembly
+```
+
+See [docs/cli-reference.md](docs/cli-reference.md#publish-assets-synth--build--publish-no-deploy)
+for stack-selection rules and concurrency knobs.
+
 ## State Management
 
 State is stored in S3 with optimistic locking via S3 Conditional Writes
@@ -678,6 +551,24 @@ After deployment, outputs are resolved and saved to the S3 state file:
 - cdkd: Outputs saved in S3 state file (e.g., `s3://bucket/cdkd/MyStack/us-east-1/state.json`)
 - Both resolve intrinsic functions (Ref, Fn::GetAtt, etc.) to actual values
 
+## Exit codes
+
+cdkd commands distinguish three outcomes via the process exit code so
+CI / bench scripts can react without grepping log output:
+
+| Exit | Meaning |
+|------|---------|
+| `0` | Success — command completed and no resources are in an error state |
+| `1` | Command-level failure — auth error, bad arguments, synth crash, unhandled exception |
+| `2` | **Partial failure** — work completed but one or more resources failed (state.json is preserved, re-running typically resolves it) |
+
+Exit `2` is currently emitted by `cdkd destroy` and `cdkd state
+destroy` when one or more per-resource deletes fail. The summary line
+also switches from `✓ Stack X destroyed` to `⚠ Stack X partially
+destroyed (...). State preserved — re-run 'cdkd destroy' / 'cdkd
+state destroy' to clean up.` so the visual marker matches the exit
+code.
+
 ## License
 
 Apache 2.0