feat(cli): introduce 'cdk resources' command for listing stack resources

[lousydropout]

This PR adds cdk resources, a new CLI command that lets users quickly see which resources their stacks define without digging through cdk.out/ or deploying. It supports summary, detailed, and JSON modes, along with filtering and wildcard stack selection.

Reason for this change

CDK users currently have no built-in way to inspect the synthesized CloudFormation resources in their stacks without:

• opening raw cdk.out templates
• deploying the stack
• writing custom tooling
• or depending on external CloudFormation inspection tools

A feature I, and I suspect others as well, have often wanted is a simple CLI command that answers:

“What resources belong to this stack?”

This PR introduces a first-class solution: cdk resources.

---

Description of changes

This PR adds a new CLI command, cdk resources, which lists CloudFormation resources from one or more synthesized stacks. It supports summary output, long-form detailed output, type filtering, wildcard stack selection, JSON mode, and resource explanation. This makes it significantly easier for developers to understand infrastructure generated by CDK apps.

---

How it works

Command Usage:

cdk resources                         # All stacks (summary mode)
cdk resources --long                  # Long/detail mode
cdk resources --json                  # JSON output

cdk resources MyStack                 # Summary mode for stack MyStack
cdk resources --long Stack1 Stack2    # Long/detail mode for multiple stacks

cdk resources 'Prod*'                 # Wildcard pattern (quote recommended)
cdk resources '*'                     # Must be quoted — unquoted * will expand to local filenames
cdk resources --ignore-case 'prod*'   # Case-insensitive wildcard matching

cdk resources --type lambda           # Filter by resource type (case-insensitive)
cdk resources -t lambda               # Same as above

Key behaviors:

• Supports wildcard stack name selection (via minimatch)

• Summary mode shows resource counts grouped by type

• Long/detail mode (--long or -l) shows full logical IDs under each type

• JSON mode (--json or -j) returns machine-readable ResourceDetails[]

• --type <pattern> (or -t <pattern>) filters resources by type (case-insensitive)

• --all shows normally hidden resource types (e.g., Lambda::Permission)

• --explain <LogicalId> produces deep, structured resource detail (single-stack only)

• Automatically handles:

  • normalized DependsOn arrays
  • import extraction (Fn::ImportValue)
  • construct path derivation from metadata
  • DeletionPolicy → removalPolicy mapping
  • missing metadata gracefully

• Case-insensitive matching supported with --ignore-case (or -i)

---

Files changed

Implementation:

• cli-config.ts — command definition and option parsing
• cli.ts — dispatch to toolkit
• cdk-toolkit.ts — new CdkToolkit.resources() method
• commands/list-resources.ts — core logic (listResources, explainResource)
• @aws-cdk/toolkit-lib/.../resource-details.ts — shared type definitions

Auto-generated (via yarn pre-compile):

• cli-type-registry.json
• parse-command-line-arguments.ts
• convert-to-user-input.ts
• user-input.ts

Tests:

• test/commands/list-resources.test.ts — 17 unit tests
• test/cli/cdk-toolkit.test.ts — 10 integration tests

---

Describe any new or updated permissions being added

N/A — No new AWS permissions required.
This command operates purely on synthesized CloudFormation templates already present in the local Cloud Assembly.

---

Description of how you validated changes

• 17 unit tests covering resource extraction, filtering, metadata handling, hidden resources, import detection, removalPolicy mapping, sorting, explain mode, and wildcard matching

• 10 integration tests covering summary mode, long/detail mode, JSON output, explain mode, filtering, and CLI behavior

• Manual testing against real CDK apps to validate:

  • wildcard stack selection
  • JSON correctness
  • resource hiding behavior
  • explain mode
  • case-insensitive matching

• Verified parser regeneration with yarn pre-compile

• CI: yarn build and full Jest suite pass

---

Usage Example

Summary (default):

WebhookDeliveryStack: 110 resources

ApiGateway::Method ...................... 46
ApiGateway::Resource .................... 23
Lambda::Function ........................ 5
...

Long mode:

WebhookDeliveryStack: 110 resources

Lambda::Function (5)
  ApiLambda                       ApiLambda
  WorkerLambda                    WorkerLambda

JSON mode:

[
  {
    "stackId": "WebhookDeliveryStack",
    "resources": [
      {
        "logicalId": "ApiLambda",
        "type": "AWS::Lambda::Function",
        "constructPath": "ApiLambda",
        "dependsOn": [],
        "imports": [],
        "removalPolicy": "destroy"
      }
    ]
  }
]

Explain mode:

cdk resources MyStack --explain MyBucket

{
  "stackId": "MyStack",
  "logicalId": "MyBucket",
  "type": "AWS::S3::Bucket",
  "constructPath": "MyBucket",
  "dependsOn": [],
  "imports": [],
  "removalPolicy": "retain",
  "condition": "CreateBucket"
}

---

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