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

When invoked as `wheels`, LuCLI loads modules from ~/.wheels/modules/wheels/.
If that path is a real directory holding a pre-install copy of Module.cfc,
edits a contributor makes under cli/lucli/ in a source checkout silently do
not take effect — surfaced during #2222, where the merged #2216 fix kept
exit-0'ing locally because the installed module was a pre-fix copy.

`wheels doctor` now detects this when run from a wheels source checkout
(projectRoot contains cli/lucli/Module.cfc + vendor/wheels/). The installed
Module.cfc is inspected three ways:

- symlink to the checkout → pass
- real file, bytes match → pass (stale but harmless this moment)
- real file, bytes diverge → warn, with a `rm -rf && ln -s` remediation
  command in the recommendations section

The check is a no-op outside source checkouts and when the installed path
is the checkout's own cli/lucli/ (dev-symlinked install). Symlink detection
and byte comparison go through java.nio.file.Files for cross-engine parity.

Closes #2223.

Author: bpamiri

CHANGELOG.md

@@ -85,6 +85,7 @@ All historical references to "CFWheels" in this changelog have been preserved fo
 - Legacy compatibility adapter for 3.x → 4.0 migration soft-landing (#2015)
 
 **CLI & LuCLI**
+- `wheels doctor` now detects a stale installed CLI module at `~/.wheels/modules/wheels/` that shadows a source checkout and warns with a remediation command (symlink). Previously, contributors running `wheels` from a checkout could silently execute a pre-install Module.cfc, making merged fixes appear not to take effect. (#2223)
 - LuCLI Phase 2: zero-Docker local testing via `tools/test-local.sh` (#2063)
 - LuCLI Phase 2: service layer, generators, MCP annotations (#1941)
 - LuCLI Phase 3–4: scaffold, seed, in-process services (#2065)

cli/lucli/Module.cfc

@@ -3877,7 +3877,8 @@ component extends="modules.BaseModule" {
 					break;
 				case "doctor":
 					variables.services.doctor = new services.Doctor(
-						projectRoot = variables.projectRoot
+						projectRoot = variables.projectRoot,
+						installedModuleRoot = variables.moduleRoot
 					);
 					break;
 				case "stats":

cli/lucli/services/Doctor.cfc

@@ -1,15 +1,17 @@
 /**
  * Health check service for diagnosing Wheels application issues.
  *
- * Performs 7 categories of checks: required dirs, recommended dirs,
+ * Performs 8 categories of checks: required dirs, recommended dirs,
  * required files, config validation, write permissions, database config,
- * and test coverage. All checks are local file operations — no running
- * server required.
+ * test coverage, and — when running from a source checkout — CLI install
+ * freshness. All checks are local file operations — no running server
+ * required.
  */
 component {
 
-	public function init(required string projectRoot) {
+	public function init(required string projectRoot, string installedModuleRoot = "") {
 		variables.projectRoot = arguments.projectRoot;
+		variables.installedModuleRoot = arguments.installedModuleRoot;
 		return this;
 	}
 
@@ -26,6 +28,7 @@ component {
 		checkWritePermissions(results);
 		checkDatabaseConfig(results);
 		checkTestCoverage(results);
+		checkCliInstallFreshness(results);
 
 		// Determine overall status
 		if (arrayLen(results.issues)) {
@@ -188,6 +191,89 @@ component {
 		}
 	}
 
+	/**
+	 * Detect a stale installed CLI module that shadows the source checkout.
+	 *
+	 * When invoked as `wheels`, LuCLI loads modules from ~/.wheels/modules/.
+	 * If ~/.wheels/modules/wheels/ is a real directory holding a pre-install
+	 * copy of Module.cfc, edits a contributor makes in cli/lucli/ of their
+	 * checkout silently do not take effect — exit-0 behavior persists even
+	 * after a fix is merged. See issue #2223.
+	 *
+	 * This check runs only when all three signals are present:
+	 *   - installedModuleRoot was supplied (we know where LuCLI loaded us from)
+	 *   - projectRoot looks like a wheels source checkout (has cli/lucli/Module.cfc
+	 *     and vendor/wheels/)
+	 *   - the installed module is NOT the checkout's cli/lucli/ directory
+	 *     (i.e., not a dev-install pointing directly at the checkout)
+	 */
+	private void function checkCliInstallFreshness(required struct results) {
+		if (!len(variables.installedModuleRoot)) return;
+
+		var checkoutModulePath = variables.projectRoot & "/cli/lucli/Module.cfc";
+		var vendorWheelsPath = variables.projectRoot & "/vendor/wheels";
+		if (!fileExists(checkoutModulePath) || !directoryExists(vendorWheelsPath)) return;
+
+		var installedDir = $normalizePath(variables.installedModuleRoot);
+		var checkoutDir = $normalizePath(variables.projectRoot & "/cli/lucli");
+		if (installedDir == checkoutDir) return;
+
+		var installedModulePath = variables.installedModuleRoot & "/Module.cfc";
+		if (!fileExists(installedModulePath)) return;
+
+		if ($isSymbolicLink(installedModulePath) || $isSymbolicLink(variables.installedModuleRoot)) {
+			arrayAppend(arguments.results.passed, "Installed CLI module is a symlink (source changes take effect immediately)");
+			return;
+		}
+
+		if ($filesBytesEqual(installedModulePath, checkoutModulePath)) {
+			arrayAppend(arguments.results.passed, "Installed CLI module matches source checkout");
+			return;
+		}
+
+		arrayAppend(
+			arguments.results.warnings,
+			"Installed CLI module at #variables.installedModuleRoot# diverges from this source checkout. "
+			& "Edits under cli/lucli/ will not take effect until you reinstall or replace the installed copy with a symlink."
+		);
+	}
+
+	// ── Path helpers ─────────────────────────────────────────
+
+	private string function $normalizePath(required string path) {
+		var p = replace(arguments.path, "\", "/", "all");
+		while (len(p) > 1 && right(p, 1) == "/") {
+			p = left(p, len(p) - 1);
+		}
+		return p;
+	}
+
+	private boolean function $isSymbolicLink(required string path) {
+		try {
+			var Paths = createObject("java", "java.nio.file.Paths");
+			var Files = createObject("java", "java.nio.file.Files");
+			var javaPath = Paths.get(javacast("string", arguments.path), javacast("string[]", []));
+			return Files.isSymbolicLink(javaPath);
+		} catch (any e) {
+			return false;
+		}
+	}
+
+	private boolean function $filesBytesEqual(required string a, required string b) {
+		try {
+			var Paths = createObject("java", "java.nio.file.Paths");
+			var Files = createObject("java", "java.nio.file.Files");
+			var pa = Paths.get(javacast("string", arguments.a), javacast("string[]", []));
+			var pb = Paths.get(javacast("string", arguments.b), javacast("string[]", []));
+			if (Files.size(pa) != Files.size(pb)) return false;
+			var bytesA = Files.readAllBytes(pa);
+			var bytesB = Files.readAllBytes(pb);
+			return createObject("java", "java.util.Arrays").equals(bytesA, bytesB);
+		} catch (any e) {
+			return false;
+		}
+	}
+
 	// ── Recommendations ──────────────────────────────────────
 
 	private array function buildRecommendations(required struct results) {
@@ -209,6 +295,14 @@ component {
 		if (findNoCase("Missing required directory", combined)) {
 			arrayAppend(recs, "Run 'wheels new' to scaffold a complete project structure");
 		}
+		if (findNoCase("Installed CLI module", combined) && findNoCase("diverges", combined)) {
+			arrayAppend(
+				recs,
+				"Replace the stale installed module with a symlink to your checkout: "
+				& "rm -rf #variables.installedModuleRoot# && "
+				& "ln -s #variables.projectRoot#/cli/lucli #variables.installedModuleRoot#"
+			);
+		}
 
 		return recs;
 	}

cli/lucli/tests/specs/services/DoctorSpec.cfc

@@ -116,8 +116,153 @@ component extends="wheels.wheelstest.system.BaseSpec" {
 				expect(passedText).toInclude("Write permission");
 			});
 
+			describe("CLI install freshness (##2223)", () => {
+
+				it("is silent when no installedModuleRoot is provided", () => {
+					var doctor = new cli.lucli.services.Doctor(projectRoot = tempRoot);
+					var results = doctor.runChecks();
+					var combined = arrayToList(results.warnings, " ") & " " & arrayToList(results.passed, " ");
+					expect(combined).notToInclude("Installed CLI module");
+				});
+
+				it("is silent when projectRoot is not a wheels source checkout", () => {
+					// tempRoot has no cli/lucli/Module.cfc — should not trigger the check
+					var fakeInstalled = getTempDirectory() & "wheels-install-" & createUUID();
+					directoryCreate(fakeInstalled, true);
+					fileWrite(fakeInstalled & "/Module.cfc", "component { }");
+
+					var doctor = new cli.lucli.services.Doctor(
+						projectRoot = tempRoot,
+						installedModuleRoot = fakeInstalled
+					);
+					var results = doctor.runChecks();
+					var combined = arrayToList(results.warnings, " ") & " " & arrayToList(results.passed, " ");
+					expect(combined).notToInclude("Installed CLI module");
+
+					directoryDelete(fakeInstalled, true);
+				});
+
+				it("warns when installed Module.cfc diverges from checkout", () => {
+					var checkout = makeFakeCheckout("component { /* checkout version */ }");
+					var installed = getTempDirectory() & "wheels-install-" & createUUID();
+					directoryCreate(installed, true);
+					fileWrite(installed & "/Module.cfc", "component { /* stale installed version */ }");
+
+					var doctor = new cli.lucli.services.Doctor(
+						projectRoot = checkout,
+						installedModuleRoot = installed
+					);
+					var results = doctor.runChecks();
+
+					var warningText = arrayToList(results.warnings, " ");
+					expect(warningText).toInclude("Installed CLI module");
+					expect(warningText).toInclude("diverges");
+
+					var recText = arrayToList(results.recommendations, " ");
+					expect(recText).toInclude("ln -s");
+
+					directoryDelete(checkout, true);
+					directoryDelete(installed, true);
+				});
+
+				it("passes when installed Module.cfc matches checkout bytes", () => {
+					var src = "component { /* identical bytes */ }";
+					var checkout = makeFakeCheckout(src);
+					var installed = getTempDirectory() & "wheels-install-" & createUUID();
+					directoryCreate(installed, true);
+					fileWrite(installed & "/Module.cfc", src);
+
+					var doctor = new cli.lucli.services.Doctor(
+						projectRoot = checkout,
+						installedModuleRoot = installed
+					);
+					var results = doctor.runChecks();
+
+					var warningText = arrayToList(results.warnings, " ");
+					expect(warningText).notToInclude("Installed CLI module");
+
+					var passedText = arrayToList(results.passed, " ");
+					expect(passedText).toInclude("matches source checkout");
+
+					directoryDelete(checkout, true);
+					directoryDelete(installed, true);
+				});
+
+				it("skips when installedModuleRoot is the checkout's own cli/lucli/", () => {
+					var checkout = makeFakeCheckout("component { }");
+					var selfInstalled = checkout & "/cli/lucli";
+
+					var doctor = new cli.lucli.services.Doctor(
+						projectRoot = checkout,
+						installedModuleRoot = selfInstalled
+					);
+					var results = doctor.runChecks();
+
+					var combined = arrayToList(results.warnings, " ") & " " & arrayToList(results.passed, " ");
+					expect(combined).notToInclude("Installed CLI module");
+
+					directoryDelete(checkout, true);
+				});
+
+				it("passes when installed module is a symlink", () => {
+					var checkout = makeFakeCheckout("component { /* target */ }");
+					var installedParent = getTempDirectory() & "wheels-install-" & createUUID();
+					directoryCreate(installedParent, true);
+					var installed = installedParent & "/wheels";
+
+					var linkCreated = tryCreateSymlink(installed, checkout & "/cli/lucli");
+					if (!linkCreated) {
+						// Symlink unsupported on this FS — skip the assertion
+						directoryDelete(checkout, true);
+						directoryDelete(installedParent, true);
+						return;
+					}
+
+					var doctor = new cli.lucli.services.Doctor(
+						projectRoot = checkout,
+						installedModuleRoot = installed
+					);
+					var results = doctor.runChecks();
+
+					var warningText = arrayToList(results.warnings, " ");
+					expect(warningText).notToInclude("Installed CLI module");
+
+					var passedText = arrayToList(results.passed, " ");
+					expect(passedText).toInclude("symlink");
+
+					// Delete symlink first, then dirs
+					try { fileDelete(installed); } catch (any e) {}
+					directoryDelete(installedParent, true);
+					directoryDelete(checkout, true);
+				});
+
+			});
+
 		});
 
 	}
 
+	// ── Spec helpers ─────────────────────────────────────────
+
+	private string function makeFakeCheckout(required string moduleContent) {
+		var root = getTempDirectory() & "wheels-checkout-" & createUUID();
+		directoryCreate(root & "/cli/lucli", true);
+		directoryCreate(root & "/vendor/wheels", true);
+		fileWrite(root & "/cli/lucli/Module.cfc", arguments.moduleContent);
+		return root;
+	}
+
+	private boolean function tryCreateSymlink(required string link, required string target) {
+		try {
+			var Paths = createObject("java", "java.nio.file.Paths");
+			var Files = createObject("java", "java.nio.file.Files");
+			var linkPath = Paths.get(javacast("string", arguments.link), javacast("string[]", []));
+			var targetPath = Paths.get(javacast("string", arguments.target), javacast("string[]", []));
+			Files.createSymbolicLink(linkPath, targetPath, javacast("java.nio.file.attribute.FileAttribute[]", []));
+			return true;
+		} catch (any e) {
+			return false;
+		}
+	}
+
 }