@go-to-k/cdkd 0.25.0 → 0.26.0

package/README.md

@@ -455,13 +455,19 @@ cdkd state resources MyStack --json   # full JSON array
 cdkd state show MyStack
 cdkd state show MyStack --json        # raw {state, lock} JSON
 
-# Orphan a stack from cdkd's state (does NOT delete AWS resources).
-# Synth-driven — needs --app / cdk.json — same stack-pattern routing as deploy.
-cdkd orphan MyStack                   # confirmation prompt (y/N)
-cdkd orphan MyStack --yes
-cdkd orphan 'MyStage/*' --yes         # display-path wildcard
-
-# State-driven counterpart (no CDK app needed — works against the bucket).
+# Orphan one or more RESOURCES from cdkd's state (does NOT delete AWS resources).
+# Per-resource, mirrors aws-cdk-cli's `cdk orphan --unstable=orphan`.
+# Synth-driven — needs --app / cdk.json. Construct paths look like the CDK
+# `aws:cdk:path` tag (`<StackName>/<Path/To/Resource>`).
+cdkd orphan MyStack/MyTable                    # confirmation prompt (y/N)
+cdkd orphan MyStack/MyTable --yes
+cdkd orphan MyStack/MyTable MyStack/MyBucket   # multiple resources, same stack
+cdkd orphan MyStack/MyTable --dry-run          # print rewrite audit, no save
+cdkd orphan MyStack/MyTable --force            # also fall back to cached
+                                               # attributes when live fetch fails
+
+# State-driven counterpart that orphans a WHOLE STACK's state record
+# (no CDK app needed — works against the bucket).
 cdkd state orphan MyStack             # confirmation prompt (y/N)
 cdkd state orphan MyStack --yes       # skip confirmation
 cdkd state orphan StackA StackB --force # also bypass the locked-stack refusal
@@ -477,9 +483,21 @@ 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. Each has a synth-driven form (`cdkd destroy` / `cdkd
-> orphan`, needs the CDK app) and a state-driven form (`cdkd state destroy`
-> / `cdkd state orphan`, works on the bucket alone).
+> 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.
 
 ### Concurrency Options
 
@@ -508,17 +526,30 @@ Both `cdkd deploy` and `cdkd destroy` (including `cdkd state destroy`) enforce a
 
 | Option | Default | Description |
 | --- | --- | --- |
-| `--resource-warn-after <duration>` | `5m` | Warn when a single resource operation has been running longer than this. The live progress line is suffixed with `[taking longer than expected, Nm+]` and a `WARN` log line is emitted (printed above the live area in TTY mode, plain stderr otherwise). |
-| `--resource-timeout <duration>` | `30m` | Abort a single resource operation that exceeds this. The deploy / destroy fails with `ResourceTimeoutError` (wrapped in `ProvisioningError`) and the existing rollback / state-preservation path runs. |
+| `--resource-warn-after <duration_or_type=duration>` | `5m` | Warn when a single resource operation has been running longer than this. The live progress line is suffixed with `[taking longer than expected, Nm+]` and a `WARN` log line is emitted (printed above the live area in TTY mode, plain stderr otherwise). Repeatable. |
+| `--resource-timeout <duration_or_type=duration>` | `30m` | Abort a single resource operation that exceeds this. The deploy / destroy fails with `ResourceTimeoutError` (wrapped in `ProvisioningError`) and the existing rollback / state-preservation path runs. Repeatable. |
 
 Durations are written as `<number>s`, `<number>m`, or `<number>h` (e.g. `30s`, `90s`, `5m`, `1.5h`). Zero, negative, missing-unit, and unknown-unit values are rejected at parse time.
 
+Both flags accept either form on each invocation:
+
+- **Bare duration** (`30m`) sets the global default. The last bare value wins.
+- **`TYPE=DURATION`** (`AWS::CloudFront::Distribution=1h`) adds a per-resource-type override that supersedes the global default for that type only.
+
+`TYPE` must look like `AWS::Service::Resource`; malformed types are rejected at parse time. `warn < timeout` is enforced both globally and per-type — so `--resource-warn-after AWS::X=10m --resource-timeout AWS::X=5m` is a parse-time error.
+
 ```bash
 # Bump the per-resource budget to one hour (matches the Custom Resource provider's polling cap)
 cdkd deploy --resource-timeout 1h
 
 # Surface "still running" warnings sooner on a fast-feedback dev loop
 cdkd deploy --resource-warn-after 90s --resource-timeout 10m
+
+# Keep the global default tight, raise it only for resources known to take longer
+cdkd deploy \
+  --resource-timeout 30m \
+  --resource-timeout AWS::CloudFront::Distribution=1h \
+  --resource-timeout AWS::RDS::DBCluster=1h30m
 ```
 
 ### Why the default is 30m, not 1h
@@ -619,6 +650,13 @@ cdkd import MyStack --resource-mapping mapping.json
 
 # CDK CLI compat: inline JSON (handy for non-TTY CI scripts).
 cdkd import MyStack --resource-mapping-inline '{"MyBucket":"my-bucket-name"}'
+
+# Capture cdkd's resolved logicalId→physicalId mapping for re-use.
+# Combine with --auto (or no flags) to record the tag-based lookups.
+cdkd import MyStack --record-resource-mapping ./mapping.json
+# mapping.json after the run: { "MyBucket": "my-bucket-name", ... }
+# Replay non-interactively in CI:
+cdkd import MyStack --resource-mapping ./mapping.json --yes
 ```
 
 When at least one `--resource` flag (or a `--resource-mapping` /
@@ -695,8 +733,8 @@ table to predict behavior when migrating from `cdk import`.
 | Failure mode | Failed import rolls the changeset back; the stack is left unchanged. | Per-resource: `imported` / `skipped-not-found` / `skipped-no-impl` / `skipped-out-of-scope` / `failed` rows are summarized. State is written for whatever succeeded — but only after a confirmation prompt (or `--yes`), so a partial run is opt-in. To roll a partial import back, use `cdkd state orphan <stack>` (drops the state record only). |
 | Selective mode (`--resource-mapping <file>`) | Supported. Listed resources are imported; unlisted resources cause the changeset to fail. | Supported. Listed resources are imported; unlisted resources are reported as `out of scope` and left out of state (next `cdkd deploy` will CREATE them). |
 | Selective mode (`--resource <id>=<physical>` repeatable) | Not supported (upstream uses interactive prompts or a mapping file). | Supported as cdkd's CLI-friendly equivalent. |
-| `--resource-mapping-inline '<json>'` | Supported (use in non-TTY environments). | **Not supported.** Use `--resource <id>=<physical>` (repeatable) or `--resource-mapping <file>` instead. |
-| `--record-resource-mapping <file>` | Supported (writes the mapping the user typed at the prompt to a file for re-use). | **Not supported.** cdkd has no interactive prompt to record. |
+| `--resource-mapping-inline '<json>'` | Supported (use in non-TTY environments). | Supported. Same shape as `--resource-mapping <file>` but supplied as a string — useful for non-TTY CI scripts that do not want a separate file. Mutually exclusive with `--resource-mapping`. |
+| `--record-resource-mapping <file>` | Supported (writes the mapping the user typed at the prompt to a file for re-use). | Supported. Writes the resolved `{logicalId: physicalId}` map (covers explicit overrides AND cdkd's tag-based auto-lookup) to the file before the confirmation prompt. The file is produced even if the user says "no" or under `--dry-run`, so the resolved data is never thrown away. |
 | Interactive prompt for missing IDs | Default in TTY — prompts for every resource not covered by a mapping file. | **Not supported.** cdkd is non-interactive: missing logical IDs are looked up by `aws:cdk:path` tag in `auto` / `hybrid` modes, or skipped as `out of scope` in selective mode. The only prompt is the final "write state?" confirmation, which `--yes` skips. |
 | Typo'd logical ID | Aborts with a clear error before any AWS calls. | Aborts with a clear error before any AWS calls — checked against the synthesized template. |
 | Whole-stack tag-based import | **Not supported.** | **cdkd-specific.** With no flags, cdkd looks every resource up by its `aws:cdk:path` tag — the typical case for adopting a stack previously deployed by `cdk deploy`. |
@@ -712,8 +750,13 @@ table to predict behavior when migrating from `cdk import`.
 
 - If you script around `--resource-mapping <file>`: behavior matches.
   The file format (`{"LogicalId": "physical-id"}`) is the same.
-- If you script around `--resource-mapping-inline`: rewrite as
-  repeated `--resource <id>=<physical>` flags, or write a temp file.
+- If you script around `--resource-mapping-inline`: behavior matches.
+  The JSON shape is the same as `--resource-mapping <file>`.
+- If you script around `--record-resource-mapping <file>`: behavior
+  matches. cdkd writes the resolved `{logicalId: physicalId}` map to
+  the file before the confirmation prompt — and even if the user says
+  "no" or under `--dry-run` — so you can capture cdkd's tag-based
+  auto-lookup result and replay it via `--resource-mapping` in CI.
 - If your workflow relies on the interactive prompt: rewrite as
   `--resource-mapping <file>`. cdkd will not prompt.
 - If you rely on atomic rollback: cdkd cannot offer that — its