wheels upgrade --help advertises --to and --dry-run flags that the command doesn't support

[bpamiri]

Describe the bug

Running wheels upgrade --help:

Usage: wheels upgrade [--to=<version>] [--dry-run]

Upgrade the Wheels framework version in your project (vendor/wheels/).

Options:
  --to=<version>    Target version (default: latest stable)
  --dry-run         Print what would change without applying

Then running wheels upgrade --dry-run (or wheels upgrade --to=4.0.0):

Usage: wheels upgrade check [--to=<version>]

Scans your app for breaking changes between versions.
Does not perform the upgrade — use 'brew upgrade wheels' for that.

The two outputs disagree on:

• The subcommand surface (--help says no subcommand needed; reality requires check)
• The flag set (--help advertises --to and --dry-run; reality only honors --to after check)
• What the command does (--help says "upgrade"; reality says "scan only, use brew for upgrade")

To Reproduce

wheels upgrade --help            # documents an "upgrade" command with --to and --dry-run
wheels upgrade --dry-run         # actually says "Usage: wheels upgrade check [--to=<version>]"
wheels upgrade --to=4.0.0        # same

Expected behavior

--help output matches the actual command behavior. Either:

1. Rewrite --help to describe the check subcommand and tell users to brew upgrade wheels for the install side, OR
2. Implement the upgrade flow that --help already describes — --to=<version> to bump vendor/wheels/, --dry-run to preview, etc.

Source

cli/lucli/Module.cfc — the upgrade() function around line 2357. The --help doc-comment block and the runtime dispatcher disagree.

Environment

• Wheels CLI: 4.0.0-SNAPSHOT+1779

🤖 Filed by Claude Code while assisting with a 4.0 upgrade testbed

[wheels-bot]

Wheels Bot — Triage

Classified as bug.

Suspected layer

cli — see .ai/wheels/cli/ for canonical patterns. The defect is in the Wheels CLI dispatcher, not the framework runtime.

Fix sketch

The bug lives in cli/lucli/Module.cfc in the upgrade() function (around line 2357). The doc-comment hint: block (which feeds wheels upgrade --help) is out of sync with the runtime dispatcher: the dispatcher only honors wheels upgrade check [--to=<version>], while --help advertises a bare wheels upgrade [--to=<version>] [--dry-run] surface that doesn't exist. Two plausible shapes (the reporter listed both): (a) rewrite the hint: / --help block to document the check subcommand and point users at brew upgrade wheels for the install side — mechanical, one file; or (b) implement the upgrade flow the help text already promises (--to=<version> to bump vendor/wheels/, --dry-run to preview) — much larger, touches version-pinning and vendor-tree rewriting. Propose-fix should pick (a) unless there's a clear product signal to build (b).

Confidence: medium

The bug and target file are unambiguous, but the fix has a design trade-off between aligning --help with reality vs. implementing the advertised flow — propose-fix needs to make that call.

<!-- wheels-bot:triage:2629 -->
<!-- wheels-bot:triage-class:bug -->
<!-- wheels-bot:triage-confidence:medium -->

[wheels-bot]

Wheels Bot — Fix proposed

Draft PR: #2642

Spec: vendor/wheels/tests/specs/cli/UpgradeCommandHelpSpec.cfc — failing → passing (2 of 7 assertions red on the existing source, all 12 specs green after the fix).
Implementation: cli/lucli/Module.cfc — showHelp() summary line for upgrade, the upgrade() docblock hint, and the in-function usage block all describe the command as a read-only scanner. --to=<version> is documented as the only flag, --dry-run is called out as not supported, and a Did you mean: wheels upgrade check ... nudge fires when the user passes --dry-run or --to= without check.

Per the triage, this is option (a) — align the help with reality. Implementing the real upgrader (option (b)) would touch version pinning and vendor-tree rewriting and is left for a separate proposal.

A human review is required before merge. Reviewer A and Reviewer B will weigh in shortly. Doc updates (MDX guides, .ai/wheels/, CLAUDE.md) are handled separately by bot-update-docs.yml.