wheels upgrade: apply mode — swap the app's vendored framework from the CLI bundle

[bpamiri]

Problem

Today wheels upgrade is check-only. The bare verb prints usage, wheels upgrade check scans the app for breaking changes (read-only, #2941/#2963/#2967 added exit-code gating, --strict, and --format=json), and the actual framework swap is left to the user: the upgrade guides document downloading a zip and manually replacing vendor/wheels/, and the CLI's own hint — brew upgrade wheels — only upgrades the CLI binary, never the app's vendored framework copy. There is no supported one-command path from "CLI updated" to "app framework updated".

Proposal (PR1 — this issue)

Give wheels upgrade an apply mode that swaps the app's vendor/wheels/ with the framework bundled inside the installed CLI:

• Bare wheels upgrade applies the swap. Source = the CLI's bundled vendor/wheels/ (resolved via WHEELS_FRAMEWORK_PATH override first, else walking up from the module's own install location — mirroring resolveFrameworkSource(), minus the project-root candidate, which is the swap target).
• Backup first. The existing vendor/wheels/ is renamed to vendor/wheels.bak-<yyyymmdd>-<HHmmss> (collision counter on rapid re-runs) via an atomic Java renameTo, with a hard error if the rename fails — recovery is a single mv. --nobackup opts out.
• Safety rails before any destructive step: both source and target must sniff as a Wheels framework dir (wheels.json/box.json present); refuse when run outside a Wheels app (no vendor/wheels/); refuse when source and target resolve to the same directory (e.g. running inside the wheels repo checkout itself); --to=<version> must exactly match the bundled framework version or the command hard-errors.
• Report old → new version and the backup path on success.
• wheels upgrade check keeps its current read-only behavior unchanged, including --strict, --format=json, and the Wheels.UpgradeCheckFailed exit-code contract.

This unlocks the bleeding-edge flow: brew uninstall wheels && brew install wheels-be && wheels upgrade puts the BE framework into an existing app, with the stable copy parked in vendor/wheels.bak-*.

Follow-up (PR2 — not in scope here)

Network download of arbitrary --to=<version> targets (resolved via ReleaseChannel), so apply mode can install versions the CLI doesn't bundle.

🤖 Generated with Claude Code

[wheels-bot]

Wheels Bot — Triage

Classified as framework-design (API/feature design question).
Cross-framework research will follow shortly — Rails, Laravel, Django,
and other modern frameworks will be consulted before any path forward
is proposed.

<!-- wheels-bot:triage:3035 -->
<!-- wheels-bot:triage-class:framework-design -->

[wheels-bot]

Wheels Bot — Cross-Framework Research

Question

PR1 proposes an apply mode for wheels upgrade (today check-only): bare wheels upgrade swaps the app's vendored vendor/wheels/ for the framework bundled in the installed CLI, backing the old copy up to vendor/wheels.bak-<ts> via an atomic Java renameTo first, with safety rails (both dirs must sniff as a Wheels framework; refuse outside an app; refuse when source==target; --to must match the bundled version) and an old→new report. How do mature frameworks let an app adopt a newer framework version — swap, backup/rollback, version-match safety, preview — and what should Wheels borrow?

How other frameworks handle this

Framework	Naming	Surface	Trade-offs	Edge cases
Rails	bin/rails app:update; bundle update rails	Bump Gemfile, Bundler rewrites Gemfile.lock; app:update regenerates framework files with per-file 3-way merge [Ynaqdh]	Pkg-mgr source of truth, no backup dir; surgical merge; non-atomic, generated files only	Rollback = restore lock from VCS; defaults staged via new_framework_defaults_X_Y.rb
Laravel	composer update laravel/framework	Edit caret in composer.json, composer.lock pins exact; Shift (paid) PRs the guide	Zero tooling; lock = trivial rollback; swaps code only, never breaking-change edits	No version precheck (platform constraints abort); rollback = git checkout composer.lock && composer install
Django	pip install -U Django	Pin Django==X.Y.Z; venv isolates; python -Wa manage.py test surfaces deprecations before swap	Universal pip+venv+VCS; deprecation contract = fwd-compat; no atomic backup/rollback cmd	One release at a time; clear cache post-swap; rollback = re-pin old
Phoenix	mix deps.update phoenix	mix.exs constraint, mix.lock; framework files never overwritten — diff by hand via phoenixdiff.org	Declarative + deterministic lock; never clobbers user code; framework-file edits 100% manual	--all gate stops world-upgrade; rollback = revert mix.exs+lock; no deps.rollback
Spring Boot	OpenRewrite rewrite:run/rewrite:dryRun; UpgradeSpringBoot_3_x	Bump parent/BOM (Maven/Gradle fan out swap); recipe rewrites deprecated APIs + property keys	dryRun→inspect patch→run is gold-standard safety; no backup (VCS only)	dryRun = git-applicable patch (CI drift guard); rollback = git reset; clean tree assumed
Expo (+1)	npx expo install --fix; npx expo-doctor	CLI owns the SDK version: npm i expo@^N then --fix re-pins every SDK-managed dep; expo-doctor preflight	Closest analog: a CLI bundling+applying a framework version. One flag re-pins; no diff/preview, no backup — relies on git	RN CLI upgrade = git apply 3-way merge + requires git; one SDK at a time

Why Expo as +1: every other framework treats its core as a package-manager dependency, so "upgrade" = edit a constraint + let the resolver swap the vendor tree. Wheels has no dependency edge — the framework is vendored in-tree and the CLI bundles what it installs. That is structurally identical to Expo (the expo CLI owns the SDK version; install --fix materializes it into the app) — the only mainstream analog to "the CLI carries the framework and stamps it onto an existing app."

Dominant pattern

Five of six converge on declarative version pin + package-manager swap + VCS/lockfile rollback — none keeps a backup directory, because the lockfile is the rollback artifact and the package manager is the version-match gate. They diverge on framework-managed files: Rails auto-merges, Spring rewrites via OpenRewrite, Laravel/Django/Phoenix leave source edits manual. The two safety primitives all agree on: (a) a dry-run/preview before any destructive write and (b) a clean-git / preflight-diagnostic precondition (expo-doctor, RN's mandatory git, Django -Wa). Wheels' vendored architecture means the package-manager swap doesn't apply — so the issue's backup-dir approach (closest to Expo, plus a real backup VCS-less users get for free) is the right adaptation; the gap vs consensus is the missing preview and clean-tree affordances.

Recommended path for Wheels

Ship the apply mode as specified — the backup-dir swap is the correct Wheels translation of "CLI owns the framework version" (Expo model), and atomic renameTo + collision counter + version-match --to are sound. Graft three consensus lessons: a --dry-run that resolves source/target and prints old→new + planned backup path without swapping; a preflight wheels upgrade check auto-run (opt out --skip-check) so breaking changes surface before the swap; and a clean-tree advisory — warn (don't refuse) when vendor/wheels is dirty. Keep wheels upgrade check read-only. Verb shape mirrors migrate (bare verb acts, sub-verb refines).

// cli/lucli/Module.cfc — extend the existing upgrade() dispatch (currently :2874).
public string function upgrade() {
    var opts = parseUpgradeArgs(structuredArgs(arguments));        // + dryRun/noBackup/skipCheck flags
    if (opts.isCheck) return runUpgradeCheck(opts.targetVersion, opts.format, opts.strict); // unchanged
    return runUpgradeApply(opts);                                  // new: the swap
}
// New service: cli/lucli/services/FrameworkSwap.cfc — named args, dollar-prefixed internals.
private string function runUpgradeApply(required struct opts) {
    var plan = new services.FrameworkSwap().plan(                  // pure; also powers --dry-run
        target = variables.projectRoot & "/vendor/wheels",
        source = resolveBundledFrameworkSource(),                  // resolveFrameworkSource() minus project-root candidate
        requestedTo = arguments.opts.targetVersion);               // "" = accept bundled
    // plan = {ok, reason, fromVersion, toVersion, sourcePath, targetPath, backupPath, sameDir, dirty}
    if (!plan.ok) throw(type="Wheels.UpgradeApplyRefused", message=plan.reason); // outside-app/same-dir/version mismatch
    if (plan.dirty) out("Warning: vendor/wheels has uncommitted changes; backup dir is your rollback.", "yellow");
    if (arguments.opts.dryRun) { out("Would upgrade #plan.fromVersion# -> #plan.toVersion# (backup #plan.backupPath#)", "green"); return "dry-run"; }
    if (!arguments.opts.skipCheck) runUpgradeCheck(plan.toVersion, "text", false); // preflight; advisory
    var r = new services.FrameworkSwap().apply(plan=plan, backup=!arguments.opts.noBackup); // atomic renameTo, hard-error
    out("Upgraded Wheels #r.fromVersion# -> #r.toVersion#  (backup: #r.backupPath#)", "green");
    return "ok";
}

wheels upgrade            # apply: backup + swap to the CLI's bundled framework
wheels upgrade --dry-run  # preview from->to + backup path, no writes
wheels upgrade --to=4.1.0 # hard-errors unless 4.1.0 == bundled version
wheels upgrade --nobackup # skip the backup rename
wheels upgrade check --strict # UNCHANGED read-only scanner

Lives in: cli/lucli/Module.cfc + new cli/lucli/services/FrameworkSwap.cfc (plan()/apply()). Composes with existing resolveFrameworkSource() (Module.cfc:5876, project-root-excluded so source can't resolve to target), WHEELS_FRAMEWORK_PATH, runUpgradeCheck() as preflight, and ReleaseChannel/SemVer for --to.

Cross-engine notes

Low concern — CLI code runs only on the CLI's bundled Lucee, not the framework's Lucee/Adobe/BoxLang matrix. Two cautions: (1) java.io.File.renameTo() returns false (doesn't throw) on cross-filesystem moves — check the boolean and hard-error; same-volume backup keeps it atomic. (2) Version sniffing of wheels.json/box.json must not use (.+) regexes spanning newlines — use [^\r\n]+. No reserved-scope or struct.map() traps.

Open questions

• Rollback verb? None of the six ship one (all lean on VCS/lock), but the backup dir uniquely enables wheels upgrade rollback (restore newest .bak-*) — now or fast-follow? A real edge over Rails/Laravel.
• Backup pruning. Rapid re-runs accumulate full-copy .bak-* dirs — prune oldest beyond N, or leave to the user?
• Preflight default. Auto-run check before apply, or opt-in?
• .gitignore. Should wheels new add vendor/wheels.bak-* to the template?

Confidence: medium

The consensus (package-manager swap + lockfile/VCS rollback, no backup dir) doesn't map onto Wheels' vendored-in-tree architecture, so I adapted toward the one structural analog (Expo) and grafted on the consensus safety primitives rather than adopt any framework's mechanism wholesale — the "+1 framework differs, non-trivial trade-off" auto-downgrade rule. The proposal is concrete and well-scoped, keeping it above low.

Sources

• https://guides.rubyonrails.org/upgrading_ruby_on_rails.html
• https://laravel.com/docs/12.x/upgrade · https://laravelshift.com/faq
• https://docs.djangoproject.com/en/6.0/howto/upgrade-version/ · https://docs.djangoproject.com/en/dev/internals/release-process/
• https://hexdocs.pm/phoenix · https://www.phoenixdiff.org/
• https://docs.openrewrite.org/recipes/java/spring/boot3/upgradespringboot_3_3 · https://docs.openrewrite.org/running-recipes/popular-recipe-guides/migrate-to-spring-3
• https://docs.expo.dev/workflow/upgrading-expo-sdk-walkthrough/ · https://docs.expo.dev/develop/tools/ · https://reactnative.dev/docs/upgrading

[wheels-bot]

Wheels Bot — Fix proposed

Draft PR: #3040

Spec: cli/lucli/tests/specs/services/FrameworkSwapSpec.cfc — failing → passing
Implementation: cli/lucli/services/FrameworkSwap.cfc (new plan()/apply() service) + cli/lucli/Module.cfc (upgrade() apply-mode dispatch, runUpgradeApply(), resolveBundledFrameworkSource())

This is PR1 of the issue — bare wheels upgrade now backs up and swaps the app's vendored vendor/wheels/ for the CLI's bundled framework, with --dry-run, --nobackup, --skip-check, and a --to version-match gate; wheels upgrade check is unchanged. Network download of arbitrary --to targets (PR2) is out of scope, so the PR uses Refs #3035 rather than Closes to avoid auto-closing the tracking issue.

The PR follows the cross-framework research's recommended path (Expo-style "CLI owns the framework version" backup-dir swap + the consensus --dry-run / preflight-check safety grafts).

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

[bpamiri]

Contract change from the #3039 pre-merge review: the swap now requires the explicit verb — wheels upgrade apply. Bare wheels upgrade prints usage and exits 0 (pre-apply-mode behavior), so MCP clients calling wheels_upgrade with {} can never mutate vendor/wheels/.

Follow-ups (not in PR1)

• Cap the bundled-source walk-up from the module root (currently 6 levels unconditionally) so a stray vendor/wheels/ in an ancestor dir can't be picked up as the swap source.
• Cosmetic: in a repo checkout the bundled manifest reports @build.version@ — substitute something friendlier (e.g. "dev checkout") in apply-mode output.
• PR2: download arbitrary --to= targets via ReleaseChannel.
• Guides refresh: command-line-tools/wheels-commands/upgrade/ + upgrading guides still describe the check-only command and the manual zip swap.