Legacy CommandBox wheels upgrade command (cli/src/) maxes out at v3.1.0 and silently misses 4.0

[bpamiri]

Describe the bug

The legacy CommandBox-based box wheels upgrade command at cli/src/commands/wheels/upgrade.cfc:

• getAvailableVersions() (line 173) returns a hardcoded static list maxing at "3.1.0". A user on 3.0.0 running box wheels upgrade will not be offered 4.0 — the command will report "You are already on the latest version" instead.
• getPostUpgradeRecommendations() (line 320) recommends https://wheels.dev/guides/introduction/upgrading — wrong URL for 4.0. Canonical is https://guides.wheels.dev/v4-0-0/upgrading/3x-to-4x/.
• checkBreakingChanges() has no entries for 3.x → 4.x — only handles 1.x → 2.x and 2.x → 3.x.
• The whole flow uses box install wheels-core@^X machinery, which is no longer the distribution channel for 4.0 (the new path is brew install wheels-dev/wheels/wheels + Homebrew/Scoop/.deb/.rpm).

Why this matters

A 3.x user trying box wheels upgrade to get to 4.0 will see "You are already on the latest version" and be told their app is up to date — when in fact 4.0 has been out for some time and they're missing it. This is the opposite of helpful at exactly the moment the user is reaching for the tool.

The legacy CommandBox wheels-cli module is already deprecated per the 4.0 CHANGELOG (scheduled for removal in v5.0), but it still ships and still runs, so it should fail gracefully rather than silently report success.

Suggested fixes (one of)

1. Add a deprecation banner at the top of the command. Print, immediately on invocation:

   ⚠️  The CommandBox `box wheels upgrade` command is deprecated and does not know about Wheels 4.0+.
       Install the new CLI: brew install wheels-dev/wheels/wheels
       Then run: wheels upgrade check
       Then: brew upgrade wheels
   

   …and short-circuit before the static ForgeBox list lookup.

2. Update getAvailableVersions() to actually query ForgeBox or GitHub Releases (the existing function comment says "in a real implementation" — it's a stub). Add 3.x → 4.x entries to checkBreakingChanges() matching the canonical 11-breaker list.

3. Delete the command entirely. The CommandBox wheels-cli module is already deprecated for v5.0 removal per the CHANGELOG — removing the stale upgrade command early would be consistent with that direction.

If the command is kept around, fix the recommendation URL to https://guides.wheels.dev/v4-0-0/upgrading/3x-to-4x/.

Source

cli/src/commands/wheels/upgrade.cfc

🤖 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. Note this is the legacy CommandBox-based CLI under cli/src/commands/wheels/ (separate from the current Wheels CLI at cli/lucli/).

Fix sketch

The defect lives entirely in cli/src/commands/wheels/upgrade.cfc. Three concrete bugs verified at the cited locations: hardcoded getAvailableVersions() list maxing at "3.1.0" (line 173), wrong upgrade-guide URL in getPostUpgradeRecommendations() (line 320), and missing 3.x → 4.x entries in checkBreakingChanges(). The cleanest fix is option 1 from the issue: print a deprecation banner directing users to the new brew install wheels-dev/wheels/wheels CLI and short-circuit before the stale ForgeBox lookup. That keeps the command honest with the 4.0 CHANGELOG's "deprecated, removal in v5.0" stance without putting work into a code path scheduled for deletion.

Confidence: medium

Report is precise (file path, function names, line numbers all check out), but the fix involves picking among three offered approaches (deprecation banner vs full update vs delete) — a small design choice that propose-fix should weigh against the 4.0 deprecation strategy.

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

[wheels-bot]

Wheels Bot — Fix proposed

Draft PR: #2639

Spec: vendor/wheels/tests/specs/cli/LegacyUpgradeDeprecationSpec.cfc — failing → passing
Implementation: cli/src/commands/wheels/upgrade.cfc

The fix prints a deprecation banner at the top of run() directing users at
the new Wheels CLI (brew install wheels-dev/wheels/wheels → wheels upgrade check
→ brew upgrade wheels) and short-circuits before the stale hardcoded
version-list lookup, matching option 1 from the issue description and the
triage's recommended path. The unreachable post-upgrade-recommendations URL
is updated to the canonical v4.0 guide for internal consistency.

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.