fix(cli): guide Stage users to a working pattern in stack-selection error

[lemon0333]

Fixes #1451

When an app has more than one stack and no selector is given, cdk deploy prints:

Since this app includes more than a single stack, specify which stacks to use (wildcards are supported) or specify --all

When the stacks live inside a Stage, this message is unhelpful: their ids are namespaced like StageName/StackName, and neither a bare stack name nor --all is the obvious way to target them, so users are left guessing (see #1451).

This change detects stacks that are nested inside a Stage (i.e. stacks that are not top-level stacks) and additionally points the user at a wildcard pattern that selects them, e.g.:

Some of these stacks are nested inside a Stage. To select the stacks in a Stage, use a pattern that matches their full path, e.g. 'StageName/*'

The hint is only appended when staged stacks are actually present, so flat apps are unaffected. The Stage detection is structural (stacks present recursively but not at the top level) rather than string-based, so a top-level stack whose display name happens to contain / is not misclassified. The same message is shared by the CLI stack-selection path (cloud-assembly.ts) and the toolkit-lib selectStacksV2 path, so both are updated for consistency.

Unit tests were added on both selector/error paths (Stage guidance present when nested, absent for flat apps, and stage patterns de-duplicated across multiple stages).

Checklist

• This change contains a major version upgrade for a dependency and I confirm all breaking changes are addressed
  • Release notes for the new version:

---

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

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 90.44%. Comparing base (88f6ad1) to head (dd1cea6).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1847      +/-   ##
==========================================
+ Coverage   90.31%   90.44%   +0.12%     
==========================================
  Files          80       80              
  Lines       12159    12188      +29     
  Branches     1725     1737      +12     
==========================================
+ Hits        10982    11024      +42     
+ Misses       1143     1130      -13     
  Partials       34       34              

Flag	Coverage Δ
suite.unit	90.44% <100.00%> (+0.12%)	⬆️

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

☔ View full report in Codecov by Harness.
📢 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]

Nice! Can you please add test cases to the CLI packages that logs io snpashots? See https://github.com/aws/aws-cdk-cli/tree/main/packages/aws-cdk/test/commands and https://github.com/aws/aws-cdk-cli/tree/main/packages/aws-cdk/test/commands/__io_snapshots__/deploy

[lemon0333]

Thanks for the review, @mrgrain! I've added command-level tests that go through the io-snapshot harness.

In packages/aws-cdk/test/commands/deploy.test.ts (multi-stack selection block) there are now two tests that drive cdk deploy with no selector:

• Stage-nested app (no top-level stacks, stacks live under MyStage) — asserts the error guides the user to the Stage wildcard pattern, e.g. 'MyStage/*'.
• Flat multi-stack app — asserts the error does not mention Stages.

Each records an entry under packages/aws-cdk/test/commands/__io_snapshots__/deploy/ via the same IoHostRecorder/matchSnapshot() afterEach the other deploy tests use.

One thing worth flagging: the guidance itself is raised as a thrown ToolkitError (the deploy path aborts at stack selection, and the message is rendered at the CLI top level by prettyPrintError), so it never crosses the IoHost notify/requestResponse boundary the recorder observes. The committed snapshots therefore capture the IO stream up to the point deploy aborts (synthesis, then stop) — protecting that no stray user-facing IO is emitted on this path — while the guidance text is asserted directly on the rejected error. This mirrors the existing deploy failures test, which also asserts on the thrown error's message rather than an IO line.

If you'd prefer the guidance to also be emitted through the IoHost (so the message text lands in the snapshot as well), I'm happy to add that — just let me know, since it's a small behavioral change to how the error is surfaced.