feat(cli): wheels doctor detects stale installed module shadowing source checkout (#2223)

[bpamiri]

Summary

• wheels doctor now detects when ~/.wheels/modules/wheels/Module.cfc diverges from the source checkout under cli/lucli/ and warns with a ready-to-paste rm -rf && ln -s remediation.
• Closes the wheels doctor: detect stale ~/.wheels/modules/wheels/ install that shadows source checkout #2223 footgun discovered while debugging fix(cli): hard-fail invalid WHEELS_FRAMEWORK_PATH instead of silent fallback (#2215) #2222: a merged fix could appear not to take effect locally because the installed CLI module was a pre-fix copy.
• Check is silent outside source checkouts and when the installed path is the checkout's own cli/lucli/ (dev-symlinked install), so normal users see no new output.

Behavior

When invoked from a wheels source checkout (projectRoot contains cli/lucli/Module.cfc + vendor/wheels/) the installed Module.cfc is inspected three ways:

State	Outcome
symlink to the checkout	pass: "Installed CLI module is a symlink (source changes take effect immediately)"
real file, bytes match	pass: "Installed CLI module matches source checkout"
real file, bytes diverge	warn + recommendation with exact rm -rf <installed> && ln -s <checkout>/cli/lucli <installed> command

Symlink detection and byte comparison go through java.nio.file.Files for cross-engine parity (Lucee / Adobe CF / BoxLang).

Scope decisions (from issue's open questions)

• Kept the check inside Doctor.cfc rather than a new wheels install status command. Zero cost outside source checkouts, preserves the single-entry-point UX. Muddies the service slightly in exchange for discoverability.
• Byte-compare scoped to Module.cfc per the issue's proposal. A broader tree-compare under cli/lucli/ is a reasonable follow-up if edits to service files (not Module.cfc) become a recurring footgun — deferred.
• Auto-symlink on install (issue's other open question) not addressed here — it's an lucli module install concern, separate PR.

Files changed

• cli/lucli/services/Doctor.cfc — new checkCliInstallFreshness() + path/NIO helpers + remediation recommendation
• cli/lucli/Module.cfc — pass variables.moduleRoot into Doctor service factory
• cli/lucli/tests/specs/services/DoctorSpec.cfc — 6 new specs covering: no-context silent, not-a-checkout silent, divergent warns, bytes-match passes, self-install skips, symlink passes (with graceful skip if FS rejects symlink creation)
• CHANGELOG.md — entry under [Unreleased] → Added → CLI & LuCLI

Test plan

• CLI suite via bash tools/test-cli-local.sh: 371 pass / 0 fail / 0 error (includes 6 new specs, all passing)
• Core framework suite via LuCLI (SQLite): 3251 pass / 0 fail / 0 error
• Live end-to-end simulation against the exact wheels doctor: detect stale ~/.wheels/modules/wheels/ install that shadows source checkout #2223 scenario (divergent bytes between checkout's cli/lucli/Module.cfc and a separate installed dir) — warning fires with the expected text, and the recommendation contains a ready-to-paste remediation command
• Verify full CI matrix (Lucee 5/6/7 + Adobe 2018/2021/2023/2025 + BoxLang) passes on PR

Related

• wheels new: explicit WHEELS_FRAMEWORK_PATH should hard-fail when it doesn't exist #2215 / fix(cli): hard-fail invalid WHEELS_FRAMEWORK_PATH instead of silent fallback (#2215) #2222 — the debugging session that surfaced this footgun
• fix(cli): wheels new exits non-zero on framework-not-found (#2211) #2216 — merged fix that was masked locally by the stale install