fix(cli): hard-fail invalid WHEELS_FRAMEWORK_PATH instead of silent fallback (#2215) (#2222)

When WHEELS_FRAMEWORK_PATH was set but pointed at a non-existent
directory, resolveFrameworkSource() appended the path to the search
list and fell through to tier 2/3 auto-discovery. The user's explicit
override was silently ignored — a typo or stale path could resolve to
a surprising framework version instead of failing loudly.

Throw Wheels.FrameworkPathInvalid when the override is set but
directoryExists() is false. Picocli maps this to exit code 1 (same
mechanism as #2216). Error message echoes the bad path and suggests
both remedies (unset or point at a valid source).

Moved the `override` var out of the try so the throw isn't swallowed
by the catch-all that guards getenv() availability.

Extended test-new-exit-codes.sh with a GH #2215 section: invalid path
must exit non-zero, error must echo the bad path, no partial scaffold.
Verified RED pre-fix (exit 0, silent fallback) and GREEN post-fix.

Author: bpamiri

cli/lucli/Module.cfc

@@ -3484,17 +3484,30 @@ component extends="modules.BaseModule" {
 		variables.frameworkSearchPaths = [];
 
 		// 1. Explicit override via environment variable — highest priority.
+		//    When the user sets WHEELS_FRAMEWORK_PATH they are giving an
+		//    imperative "use this" — if the path doesn't exist, hard-fail
+		//    rather than silently falling through to auto-discovery (a stale
+		//    or typo'd path could otherwise resolve to a surprising framework
+		//    version). See GH #2215.
+		var override = "";
 		try {
 			var javaSystem = createObject("java", "java.lang.System");
-			var override = javaSystem.getenv("WHEELS_FRAMEWORK_PATH");
-			if (!isNull(override) && len(trim(override))) {
-				arrayAppend(variables.frameworkSearchPaths, override & "  (from $WHEELS_FRAMEWORK_PATH)");
-				if (directoryExists(override)) {
-					return override;
-				}
+			var envValue = javaSystem.getenv("WHEELS_FRAMEWORK_PATH");
+			if (!isNull(envValue)) {
+				override = envValue;
 			}
 		} catch (any e) {
-			// Ignore — env var not accessible in this runtime.
+			// Env var not accessible in this runtime — treat as unset.
+		}
+		if (len(trim(override))) {
+			arrayAppend(variables.frameworkSearchPaths, override & "  (from $WHEELS_FRAMEWORK_PATH)");
+			if (directoryExists(override)) {
+				return override;
+			}
+			throw(
+				type="Wheels.FrameworkPathInvalid",
+				message="WHEELS_FRAMEWORK_PATH is set to '#override#' but that directory does not exist. Unset the variable to fall back to auto-discovery, or point it at a valid vendor/wheels/ source."
+			);
 		}
 
 		// 2. Project root (e.g. user ran `wheels new` from inside an existing

cli/lucli/tests/test-new-exit-codes.sh

@@ -1,11 +1,12 @@
 #!/usr/bin/env bash
-# Regression test for GH #2211 and GH #2214: `wheels new` must exit
-# non-zero on every user-facing error path, not silently succeed.
+# Regression tests for wheels new exit-code contracts.
 #
-# Coverage:
-#   - #2211: framework source not found
-#   - #2214: target directory already exists
-#   - #2214: app name missing (args supplied but none parsed as appname)
+#   GH #2211 — framework source not found anywhere must exit non-zero
+#   GH #2215 — explicit WHEELS_FRAMEWORK_PATH pointing at a non-existent
+#              directory must hard-fail (not silently fall through to
+#              auto-discovery)
+#   GH #2214 — target directory already exists must exit non-zero
+#   GH #2214 — app name missing (args supplied but none parsed) must exit non-zero
 #
 # Prerequisites:
 #   - wheels binary on PATH
@@ -68,6 +69,46 @@ else
     fail "partial fixture/ directory left behind"
 fi
 
+echo ""
+echo "=== GH #2215: invalid WHEELS_FRAMEWORK_PATH must hard-fail ==="
+echo ""
+
+# Fresh subdir so a leftover fixture/ from case #2211 doesn't poison the check.
+SUBDIR="$TMPDIR/case-2215"
+mkdir -p "$SUBDIR"
+cd "$SUBDIR"
+
+BAD_PATH="$SUBDIR/does-not-exist/vendor/wheels"
+export WHEELS_FRAMEWORK_PATH="$BAD_PATH"
+
+OUT=$(wheels new fixture --no-open-browser 2>&1)
+CODE=$?
+
+echo "--- output (last 8 lines) ---"
+echo "$OUT" | tail -8
+echo "--- exit code: $CODE ---"
+echo ""
+
+if [ "$CODE" -ne 0 ]; then
+    pass "wheels new exits non-zero when WHEELS_FRAMEWORK_PATH is invalid"
+else
+    fail "wheels new exited 0 despite invalid WHEELS_FRAMEWORK_PATH (GH #2215)"
+fi
+
+if echo "$OUT" | grep -qF "$BAD_PATH"; then
+    pass "error message echoes the invalid path"
+else
+    fail "error message does not mention the invalid path"
+fi
+
+if [ ! -d "$SUBDIR/fixture" ]; then
+    pass "no partial fixture/ directory left behind (case 2215)"
+else
+    fail "partial fixture/ directory left behind (case 2215)"
+fi
+
+unset WHEELS_FRAMEWORK_PATH
+
 echo ""
 echo "=== GH #2214: wheels new target-directory-exists regression ==="