feat(cli): cdk orphan command detaches resources from a stack, allowing resource type upgrades (behind --unstable)

[LeeroyHannigan]

ref: #1324

Adds a new cdk orphan command (behind --unstable=orphan) that safely detaches resources from a CloudFormation stack without deleting them. This enables resource type migrations (e.g., DynamoDB Table → TableV2) with zero downtime or data loss.

Usage

# Orphan a single resource
$ cdk orphan --unstable=orphan MyStack/MyTable

# Orphan multiple resources
$ cdk orphan --unstable=orphan MyStack/MyTable MyStack/MyBucket

How it works

The command performs three sequential CloudFormation deployments:

1. Resolve references — Injects temporary stack Outputs to resolve {Ref}, {Fn::GetAtt}, and {Fn::Sub} values for the targeted resources via DescribeStacks
2. Isolate resources — Sets DeletionPolicy: Retain, replaces all cross-resource references with resolved literal values, and removes DependsOn entries
3. Remove resources — Deletes the resources from the CloudFormation template (they continue to exist in the AWS account)

After orphaning, the command outputs a cdk import --resource-mapping-inline command with the resource mapping, so users can immediately re-import the resource under a new construct type.

Changes

New: cdk orphan command

• packages/@aws-cdk/toolkit-lib/lib/api/orphan/ — Core ResourceOrphaner class and reference resolution helpers
• packages/aws-cdk/lib/cli/ — CLI wiring: command definition, argument parsing, user input types
• packages/aws-cdk/README.md — Documentation with usage examples and a DynamoDB migration walkthrough

Enhanced: cdk import inline resource mapping

• packages/@aws-cdk/toolkit-lib/lib/api/resource-import/importer.ts — Added loadResourceIdentifiers() accepting a JSON string or object (in addition to the existing file-based loadResourceIdentifiersFromFile())

Tests

• packages/@aws-cdk/toolkit-lib/test/api/orphan/orphan.test.ts — Unit tests for the orphaner (394 lines)
• packages/@aws-cdk-testing/cli-integ/tests/cli-integ-tests/orphan/ — Integration test: deploys a DynamoDB table + Lambda consumer, orphans the table, verifies template changes and data integrity

Depends-On: #1403

---

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license

[rix0rrr]

The build is failing, and needs AppSec involvement because of the bootstrap stack change. Other than that I am good with this!

[codecov-commenter]

Codecov Report

❌ Patch coverage is 53.33333% with 28 lines in your changes missing coverage. Please review.
✅ Project coverage is 87.98%. Comparing base (9ac077d) to head (c6a6891).

Files with missing lines	Patch %	Lines
packages/aws-cdk/lib/cli/cdk-toolkit.ts	50.00%	16 Missing ⚠️
packages/aws-cdk/lib/cli/cli.ts	7.69%	12 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1399      +/-   ##
==========================================
- Coverage   88.13%   87.98%   -0.15%     
==========================================
  Files          74       74              
  Lines       10481    10535      +54     
  Branches     1433     1433              
==========================================
+ Hits         9237     9269      +32     
- Misses       1217     1239      +22     
  Partials       27       27              

Flag	Coverage Δ
suite.unit	87.98% <53.33%> (-0.15%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[mrgrain]

approved in principle. we need the additional PR #1403 merged first.