fix(cli): normalize Windows drive-letter paths in wheels new (#2835)

* fix(cli): normalize Windows drive-letter paths to forward slashes in `wheels new`

`wheels new <name>` fails on a fresh Scoop install with:

    [ERROR] Error: lucee.runtime.exp.NativeException:
    there is no Resource provider available with the name [c],
    available resource providers are [ftp, zip, tar, tgz, http, https, ram, s3]

before any module output appears. Reported by Risto on Windows 11 via
Scoop after #2766 + the manifest fix landed (which unblocked `wheels new`
routing to the wheels module in the first place — see scoop-wheels
direct-push 30ea6e5 + 6cf06fc, 2026-05-28).

## Root cause

`Module.init()` receives `cwd` from LuCLI as the JVM's `user.dir`,
which on Windows is `C:\Users\<name>` with backslashes. The early
`wheels new` code path then constructs paths like:

    targetDir = variables.cwd & "/" & appName
              = "C:\Users\cy" & "/" & "blog"
              = "C:\Users\cy/blog"   # mixed slashes!

Lucee 7's `ResourceUtil` runs a URI scheme-detection regex
(`^[a-zA-Z][a-zA-Z0-9+.-]*:`) BEFORE its Windows drive-letter
special case in this code path. The regex matches `c:` from
`C:\Users\cy/blog`, extracts "c" as the scheme, looks for a
matching resource provider, finds none (only `ftp`, `zip`,
`tar`, `tgz`, `http`, `https`, `ram`, `s3` are registered),
and throws. The same call with pure backslashes (`C:\Users\cy\blog`)
works because Lucee's Windows path detection kicks in earlier;
the same call with pure forward slashes (`C:/Users/cy/blog`)
works for the same reason.

The other suspect site is `resolveProjectRoot()` /
`resolveFrameworkSource()`, where `java.io.File.getCanonicalPath()`
returns backslashes (Windows native) and we concat with
`/vendor/wheels`. Same mixed-slash pattern, same crash.

Mac/Linux are unaffected because paths never start with a
letter-colon prefix. The bug has been latent in the Scoop install
since day one but was masked by the `-Dlucli.binary.name=wheels`
omission (scoop-wheels 30ea6e5) — until that was fixed, no
Windows `wheels new` invocation reached the wheels module at all.

## Fix

Two-layer defense:

1. **Normalize all backslashes to forward slashes** before any
   path-existence check. `$normalizePath()` runs on `variables.cwd`
   in `init()` and on every `File.getCanonicalPath()` result in
   `resolveProjectRoot()` and `resolveFrameworkSource()`. Forward-
   slash-only paths bypass the URI scheme ambiguity because
   `C:/...` matches Lucee's Windows-path detection before its
   URI-scheme regex.

2. **`$safeDirExists()` / `$safeFileExists()` wrappers** with a
   `java.io.File`-based fallback. If anything still slips through
   normalization (a path the user provided via `WHEELS_FRAMEWORK_PATH`,
   a mapping, etc.), `directoryExists()` throws the same
   NativeException — we catch it and fall back to
   `new java.io.File(path).isDirectory()`, which is OS-native and
   has no concept of URI schemes.

Layer 1 prevents the throw in the first place; layer 2 prevents the
crash if layer 1 is incomplete. Both layers are no-ops on Mac/Linux
(no backslashes to normalize; `directoryExists` doesn't throw).

## Scope

Limited to the early `wheels new` path: `init()`,
`resolveProjectRoot()`, `scaffoldNewApp()`'s first `directoryExists`,
and `resolveFrameworkSource()`'s three `directoryExists` calls. Once
the framework source is located and we enter the recursive
`copyTemplateDir()` loop, paths are constructed from the (already
normalized) `targetDir` so they inherit forward slashes — no
additional changes needed there.

## Verification

- Smoke-tested on macOS by overwriting `~/.wheels/modules/wheels/Module.cfc`
  with the patched version: `wheels new test-patched` scaffolded
  successfully with identical output to unpatched.
- Windows verification pending — patched Module.cfc to be hand-delivered
  to Risto for drop-in test against his Scoop install before this PR
  merges.

Refs scoop-wheels manifest update 30ea6e5 (binary.name fix that
unmasked this bug).

Signed-off-by: Peter Amiri <peter@alurium.com>

* refactor(cli): drop unused $safeFileExists, document #2835 in CHANGELOG

Address wheels-bot review on #2835:

- $safeFileExists was added beside $safeDirExists but never wired to a
  call site; the Windows path fix only checks directories. Remove the
  dead helper; re-add with its java.io.File fallback if a file-existence
  check ever needs it.
- Add an [Unreleased] "### Fixed" CHANGELOG entry for the drive-letter
  URI misparse fix.

$safeDirExists and its 8 call sites are unchanged.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Signed-off-by: Peter Amiri <peter@alurium.com>

---------

Signed-off-by: Peter Amiri <peter@alurium.com>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: bpamiri

CHANGELOG.md

@@ -32,6 +32,7 @@ All historical references to "CFWheels" in this changelog have been preserved fo
 
 ### Fixed
 
+- `wheels new <name>` no longer crashes on a fresh Windows (Scoop) install with `lucee.runtime.exp.NativeException: there is no Resource provider available with the name [c]` before any module output appears. LuCLI hands `Module.init()` a `cwd` of the JVM's `user.dir` (e.g. `C:\Users\cy`, backslashes), and the early scaffold path concatenated `cwd & "/" & appName` into a mixed-slash string like `C:\Users\cy/blog`. Lucee 7's `ResourceUtil` runs a URI scheme-detection regex (`^[a-zA-Z][a-zA-Z0-9+.-]*:`) ahead of its Windows drive-letter special case on this code path, matches `c:`, extracts `c` as a resource-provider scheme, finds none (only `ftp` / `zip` / `tar` / `tgz` / `http` / `https` / `ram` / `s3`), and throws — pure-backslash and pure-forward-slash paths both work, only the mixed form fails. A new `$normalizePath()` replaces backslashes with forward slashes on `variables.cwd` in `init()` and on every `java.io.File.getCanonicalPath()` result in `resolveProjectRoot()` / `resolveFrameworkSource()`, so `C:/Users/cy/blog` matches Lucee's Windows-path detection before the URI regex ever runs; a `$safeDirExists()` wrapper adds a `java.io.File.isDirectory()` fallback for any path that still reaches a `directoryExists()` check with a drive-letter prefix (a user-supplied `WHEELS_FRAMEWORK_PATH`, a CFML mapping). Both no-op on macOS/Linux, where paths carry no `<letter>:` prefix. Latent since the Scoop install first shipped, but masked until the `-Dlucli.binary.name=wheels` routing fix (`wheels-dev/scoop-wheels@30ea6e5`) let `wheels new` actually reach this code (#2835)
 - Running the `wheels` CLI with no arguments no longer errors out with `Component [modules.wheels.Module] has no function with name [main]`. LuCLI dispatches a bare `wheels` invocation to a `main()` subcommand on the module; previously `cli/lucli/Module.cfc` only defined `showHelp()`, so picocli's routing surfaced the missing-method exception. `Module.cfc` now defines `main()` as a thin delegate to `showHelp()` (and the function is added to `mcpHiddenTools()` so it doesn't appear as an MCP tool), restoring the expected behavior of printing the help banner when no subcommand is supplied (#2840)
 - `wheels new` no longer commits a reload-password secret to source control. The scaffold hard-coded the generated random password as a literal in `config/settings.cfm` (a tracked file) and repeated it in a comment, and wrote it to `.env` as `RELOAD_PASSWORD` while the deployment guides and the `wheels deploy` secrets contract used `WHEELS_RELOAD_PASSWORD` — so pasting the documented `env()` snippet into a fresh app silently resolved to `""` and tripped the "reloadPassword is empty" boot warning. Generated `config/settings.cfm` (and both `app/snippets/*.txt`) now read `set(reloadPassword=env("WHEELS_RELOAD_PASSWORD", ""))`, so the random value the generator creates lives only in the git-ignored `.env`; the scaffold `.env` and the `examples/starter-app` reference now emit `WHEELS_RELOAD_PASSWORD` (the starter-app previously committed a guessable `reloadPassword="changeme"`). The CLI's `detectReloadPassword()` accepts both the prefixed and legacy unprefixed key, so apps generated before the rename keep working, and the configuration + deployment guides are reconciled on the bare `env()` accessor and the `WHEELS_RELOAD_PASSWORD` name (replacing an insecure docker example that used `Server.System.getEnv("RELOAD_PASSWORD") ?: "changeme"`). The scaffolded `lucee.json` also stops embedding the literal — its Lucee Server Admin password reads `#env:WHEELS_LUCEE_ADMIN_PASSWORD#` (a distinct generated secret written to `.env`, separate from the reload password), which LuCLI resolves from `.env` at server start via its native `#env:VAR#` interpolation, so no committed file carries it. **Heads-up for existing apps:** the CFML `env()` lookup is exact-match (only the CLI carries the back-compat alias), so if you adopt the new `config/settings.cfm` form or a guide snippet, rename your `.env` key from `RELOAD_PASSWORD` to `WHEELS_RELOAD_PASSWORD` (#2857)
 - Auto-derived model property names now preserve the database's reported column casing again, instead of being force-lowercased on every engine. When a model declares no `property()` mappings, Wheels infers its properties from the database column metadata; a change in the 3.0 line (`Model.cfc`, intended to normalize Oracle's fixed-case identifiers) began calling `lCase()` on every derived property name unconditionally, so an `isHidden` column surfaced as the property `ishidden` on SQL Server, MySQL, SQLite, etc. — silently breaking case-sensitive consumers of serialized model output (`returnAs="structs"`, `renderWith()`, `serializeJSON()`) for anyone upgrading from CFWheels 2.x (the same code preserved case in 2.5 on the same engine + database). Casing is now preserved by default and only lowercased on adapters whose database folds unquoted identifiers to a non-meaningful UPPERCASE default, gated by a new `$lowerCaseColumnNames()` capability on the database adapter (`Base` default `false`; `OracleModel` and `H2Model` override to `true`). So SQL Server / MySQL / SQLite preserve the declared case, PostgreSQL / CockroachDB use the database's own lowercase-folded name, and Oracle / H2 keep the lowercased behavior they have today. Models that explicitly declare `property(name="isHidden", column="isHidden")` were always unaffected and remain so. **Reverse-migration heads-up:** apps that adopted Wheels 3.x/4.x and adapted to the force-lowercased property names — e.g. JSON consumers, view templates, or client-side code that expects `{"ishidden": 1}` — will see that output revert to the originally declared casing (`{"isHidden": 1}`) after applying this patch on SQL Server / MySQL / SQLite. Review any serialized model output consumers before upgrading (#2852)

cli/lucli/Module.cfc

@@ -24,18 +24,62 @@ component extends="modules.BaseModule" {
 	) {
 		super.init(argumentCollection = arguments);
 
+		// Normalize cwd to forward slashes. Lucee 7 on Windows fails to
+		// distinguish a drive-letter path (e.g. `C:\Users\cy/blog`, where
+		// the backslash came from `user.dir` and the forward slash from
+		// `cwd & "/" & appName`) from a URI like `http:/...`. The mixed-
+		// slash form trips ResourceUtil's scheme-detection regex, which
+		// extracts "c" as the scheme and throws "no Resource provider
+		// available with the name [c]" before any module code runs. All-
+		// forward-slash paths are accepted by both Lucee and the JDK on
+		// every platform, so we normalize once here and again on every
+		// canonical-path concatenation downstream.
+		variables.cwd = $normalizePath(variables.cwd);
+
 		// Resolve project root (where lucee.json / vendor/wheels lives)
-		variables.projectRoot = resolveProjectRoot(arguments.cwd);
+		variables.projectRoot = resolveProjectRoot(variables.cwd);
 
 		// Module root for template resolution
-		variables.moduleRoot = getDirectoryFromPath(getCurrentTemplatePath());
+		variables.moduleRoot = $normalizePath(getDirectoryFromPath(getCurrentTemplatePath()));
 
 		// Lazy-init service instances
 		variables.services = {};
 
 		return this;
 	}
 
+	/**
+	 * Normalize a filesystem path for safe handoff to Lucee file APIs on
+	 * Windows. Replaces all backslashes with forward slashes — Lucee
+	 * accepts both on Windows, but mixed-slash strings can trip
+	 * ResourceUtil's URI scheme detection (see init() comment).
+	 *
+	 * No-op on a path that already uses forward slashes (Mac/Linux,
+	 * already-normalized Windows paths).
+	 */
+	private string function $normalizePath(required string p) {
+		return replace(arguments.p, "\", "/", "all");
+	}
+
+	/**
+	 * Java-backed directoryExists() — bypasses Lucee's path resolver so
+	 * paths starting with a Windows drive letter (`C:\…`) never reach
+	 * ResourceUtil's scheme detection. The defensive `try/catch` honors
+	 * Lucee's built-in first (in case mappings or symlinks matter) and
+	 * only falls back to `java.io.File.isDirectory()` when Lucee throws.
+	 *
+	 * Use this in any path-existence check that runs early in `wheels
+	 * new` (before the framework source is located) or in any code that
+	 * constructs paths from `variables.cwd` / `File.getCanonicalPath()`.
+	 */
+	private boolean function $safeDirExists(required string p) {
+		try {
+			return directoryExists(arguments.p);
+		} catch (any e) {
+			return createObject("java", "java.io.File").init(arguments.p).isDirectory();
+		}
+	}
+
 	/**
 	 * Extract positional arguments from LuCLI's argCollection or __arguments.
 	 *
@@ -4505,9 +4549,12 @@ component extends="modules.BaseModule" {
 	// ── New App Scaffolding ──────────────────────────
 
 	private string function scaffoldNewApp(required string appName, struct options = {}) {
+		// variables.cwd is already forward-slash-normalized by init(); the
+		// concat below stays clean on Windows. $safeDirExists is a final
+		// safety net against any cwd that bypasses normalization.
 		var targetDir = variables.cwd & "/" & appName;
 
-		if (directoryExists(targetDir)) {
+		if ($safeDirExists(targetDir)) {
 			out("Directory already exists: #appName#", "red");
 			// Throw so LuCLI exits non-zero instead of silently succeeding and
 			// fooling automation (GH #2214). Done before any files are written.
@@ -5225,8 +5272,8 @@ component extends="modules.BaseModule" {
 		}
 		if (len(trim(override))) {
 			arrayAppend(variables.frameworkSearchPaths, override & "  (from $WHEELS_FRAMEWORK_PATH)");
-			if (directoryExists(override)) {
-				return override;
+			if ($safeDirExists(override)) {
+				return $normalizePath(override);
 			}
 			throw(
 				type="Wheels.FrameworkPathInvalid",
@@ -5239,21 +5286,24 @@ component extends="modules.BaseModule" {
 		if (len(variables.projectRoot)) {
 			var projectCandidate = variables.projectRoot & "/vendor/wheels";
 			arrayAppend(variables.frameworkSearchPaths, projectCandidate);
-			if (directoryExists(projectCandidate)) {
+			if ($safeDirExists(projectCandidate)) {
 				return projectCandidate;
 			}
 		}
 
 		// 3. Module root — if the LuCLI module itself lives inside a wheels
 		//    repo checkout (cli/lucli/), walk up to find vendor/wheels/.
+		//    Normalize each canonical path (Windows: backslashes) to
+		//    forward slashes so concatenation with "/vendor/wheels" stays
+		//    URI-safe — see init().
 		if (len(variables.moduleRoot)) {
 			var File = createObject("java", "java.io.File");
 			var dir = variables.moduleRoot;
 			for (var i = 0; i < 6; i++) {
-				var candidate = File.init(dir).getCanonicalPath();
+				var candidate = $normalizePath(File.init(dir).getCanonicalPath());
 				var frameworkCandidate = candidate & "/vendor/wheels";
 				arrayAppend(variables.frameworkSearchPaths, frameworkCandidate);
-				if (directoryExists(frameworkCandidate)) {
+				if ($safeDirExists(frameworkCandidate)) {
 					return frameworkCandidate;
 				}
 				var parent = File.init(candidate).getParent();
@@ -5444,10 +5494,13 @@ component extends="modules.BaseModule" {
 		var dir = len(trim(cwd)) ? cwd : ".";
 		var File = createObject("java", "java.io.File");
 
-		// Walk up at most 5 levels
+		// Walk up at most 5 levels. Normalize each canonical path to
+		// forward slashes before concatenation — see init() for why mixed
+		// slashes break Lucee 7 on Windows. $safeDirExists guards against
+		// any path that still slips through with a drive-letter scheme.
 		for (var i = 0; i < 5; i++) {
-			var candidate = File.init(dir).getCanonicalPath();
-			if (directoryExists(candidate & "/vendor/wheels")) {
+			var candidate = $normalizePath(File.init(dir).getCanonicalPath());
+			if ($safeDirExists(candidate & "/vendor/wheels")) {
 				return candidate;
 			}
 			// Go up one level
@@ -5457,7 +5510,9 @@ component extends="modules.BaseModule" {
 		}
 
 		// Fallback: use cwd as-is
-		return len(trim(cwd)) ? File.init(cwd).getCanonicalPath() : File.init(".").getCanonicalPath();
+		return $normalizePath(
+			len(trim(cwd)) ? File.init(cwd).getCanonicalPath() : File.init(".").getCanonicalPath()
+		);
 	}
 
 	/**