wheels-dev
diff --git a/‎cli/lucli/Module.cfc‎
Lines changed: 113 additions & 0 deletions b/‎cli/lucli/Module.cfc‎
Lines changed: 113 additions & 0 deletions
diff --git a/‎cli/lucli/resources/extensions/sqlite/org.xerial.sqlite-jdbc-3.49.1.0.jar‎
13.6 MB b/‎cli/lucli/resources/extensions/sqlite/org.xerial.sqlite-jdbc-3.49.1.0.jar‎
13.6 MB
diff --git a/‎cli/lucli/services/BundleStager.cfc‎
Lines changed: 92 additions & 0 deletions b/‎cli/lucli/services/BundleStager.cfc‎
Lines changed: 92 additions & 0 deletions
diff --git a/‎cli/lucli/tests/specs/services/BundleStagerSpec.cfc‎
Lines changed: 169 additions & 0 deletions b/‎cli/lucli/tests/specs/services/BundleStagerSpec.cfc‎
Lines changed: 169 additions & 0 deletions
@@ -360,13 +360,32 @@ component extends="modules.BaseModule" {
 
 		out("Starting Wheels server...", "cyan");
 
+		// Stage required JDBC drivers into the Lucee Express lib/ext/ before
+		// LuCLI provisions/boots Lucee. Without this, fresh `wheels new` apps
+		// with the SQLite-by-default datasource hit a class-load failure on
+		// the first request because the Lucee Express distribution doesn't
+		// ship the SQLite driver and not every install path (chocolatey,
+		// dev checkout, manual) drops the JAR via a wrapper script. See
+		// GH #2326 (F8). Pre-stage (this call) covers the first-start case
+		// where the express dir already exists; post-stage (after server
+		// start, below) covers the case where express was extracted by this
+		// very LuCLI invocation.
+		$ensureWheelsBundles();
+
 		// Delegate to LuCLI's server start command
 		var cmdArgs = ["start"];
 
 		// Pass through any extra args (--port, --version, etc.)
 		cmdArgs.append(args, true);
 
 		executeCommand("server", cmdArgs, variables.projectRoot);
+
+		// Post-stage. If the express dir didn't exist at pre-stage time
+		// (very first LuCLI run on a fresh VM), the start command above just
+		// extracted it. Seed the JAR now so the *next* `wheels start` works
+		// zero-config without the user knowing the difference.
+		$ensureWheelsBundles();
+
 		return "";
 	}
 
@@ -3672,6 +3691,100 @@ component extends="modules.BaseModule" {
 		printCreated(appName & "/vendor/wheels/");
 	}
 
+	// ─────────────────────────────────────────────────
+	//  Datasource bundle staging — fresh-VM F8 fix
+	// ─────────────────────────────────────────────────
+
+	/**
+	 * Stage required JDBC drivers into every Lucee Express install's
+	 * `lib/ext/` (Tomcat classpath) so Lucee can resolve datasource driver
+	 * classes at boot time without hitting class-load failures. Lucee 7's
+	 * stock Express distribution ships drivers for MySQL/MSSQL/PostgreSQL/
+	 * HSQLDB but not SQLite — yet `wheels new` writes SQLite as the zero-
+	 * config default datasource. Without this stage, every fresh app fails
+	 * on first request with `ClassException: org.sqlite.JDBC`.
+	 *
+	 * Idempotent: if the JAR already exists in lib/ext/, skip. Best-effort:
+	 * any I/O error is swallowed because we'd rather defer to LuCLI's normal
+	 * server start error reporting than block on bundle staging.
+	 *
+	 * The bundled JAR at cli/lucli/resources/extensions/sqlite/ is the
+	 * upstream xerial sqlite-jdbc with a relaxed `Require-Capability` header
+	 * (Felix on Java 21 fails on upstream's strict `osgi.ee;version=1.8`
+	 * exact-match). See tools/lucee-extensions/sqlite/build.sh for the
+	 * patch logic. The JAR works equally well in lib/ext/ (Tomcat classpath)
+	 * and lucee-server/bundles/ (OSGi); we target lib/ext/ here to mirror
+	 * the brew formula's drop strategy and avoid the per-server `--force`
+	 * wipe that bundles/ is subject to.
+	 */
+	private void function $ensureWheelsBundles() {
+		try {
+			var stager = new services.BundleStager();
+			if (!stager.projectUsesSqliteDatasource(variables.projectRoot)) return;
+
+			var bundleSrc = variables.moduleRoot & "resources/extensions/sqlite/org.xerial.sqlite-jdbc-3.49.1.0.jar";
+			if (!fileExists(bundleSrc)) {
+				// Dev checkout without the bundle baked in. Skip silently —
+				// release tarballs always include it.
+				return;
+			}
+
+			var lucliHome = $resolveLucliHome();
+			if (!len(lucliHome)) return;
+
+			// Stage into every Lucee Express install's lib/ext/ — that's the
+			// Tomcat classpath, where Lucee 7 finds JDBC drivers when the
+			// datasource config doesn't carry an OSGi `bundleName` hint
+			// (current `wheels new`-generated app.cfm omits the hint per
+			// GH #2304). Mirrors the brew/chocolatey wrapper's drop strategy
+			// so dev-checkout, manual-install, and any other path that skips
+			// the package wrapper still gets a working zero-config SQLite.
+			stager.stageIntoLibExt(
+				bundleSrc = bundleSrc,
+				expressRoot = lucliHome & "/express",
+				jarFileName = "sqlite-jdbc-3.49.1.0.jar"
+			);
+		} catch (any e) {
+			// Stay out of the way — let LuCLI's server start surface the real
+			// error if the bundle was actually needed and we couldn't stage.
+		}
+	}
+
+	/**
+	 * Resolve the LuCLI home root. Order of resolution:
+	 *   1. $LUCLI_HOME if set (e.g. brew wrapper exports $HOME/.wheels).
+	 *   2. $HOME/.<lucli.binary.name> — LuCLI auto-roots to ~/.<binary> when
+	 *      invoked under a symlinked binary name. `wheels` resolves to
+	 *      ~/.wheels/, bare `lucli` resolves to ~/.lucli/.
+	 *   3. $HOME/.lucli — final fallback.
+	 */
+	private string function $resolveLucliHome() {
+		var javaSystem = createObject("java", "java.lang.System");
+		// 1. Explicit override.
+		try {
+			var override = javaSystem.getenv("LUCLI_HOME");
+			if (!isNull(override) && len(override)) return override;
+		} catch (any e) {}
+		// 2. Per-binary-name default. LuCLI's bootstrap exports
+		//    -Dlucli.binary.name=<name> based on how it was invoked, and
+		//    home defaults to ~/.<binary-name>/. So `wheels` invocations
+		//    resolve to ~/.wheels/ and bare `lucli` invocations to ~/.lucli/.
+		//    Match that resolution exactly so we stage into the same tree
+		//    LuCLI itself uses (catalina.base / catalina.home).
+		try {
+			var userHome = javaSystem.getProperty("user.home");
+			if (isNull(userHome) || !len(userHome)) return "";
+			try {
+				var binaryName = javaSystem.getProperty("lucli.binary.name");
+				if (!isNull(binaryName) && len(binaryName)) {
+					return userHome & "/." & binaryName;
+				}
+			} catch (any e) {}
+			return userHome & "/.lucli";
+		} catch (any e) {}
+		return "";
+	}
+
 	/**
 	 * Resolve the path to a vendor/wheels framework source directory, checking
 	 * (in order): the WHEELS_FRAMEWORK_PATH env var, the resolved project
 
@@ -0,0 +1,92 @@
+/**
+ * Datasource-bundle staging helpers for `wheels start`.
+ *
+ * Lucee 7's stock Express distribution ships JDBC drivers for MySQL, MSSQL,
+ * PostgreSQL, and HSQLDB but not SQLite — yet `wheels new` writes SQLite as
+ * the zero-config default datasource. Without a JAR somewhere Lucee can find
+ * (Tomcat classpath via lib/ext/, or an OSGi bundle), every fresh app fails
+ * on first request with `ClassException: org.sqlite.JDBC`. See GH #2326 (F8).
+ *
+ * Isolated from Module.cfc so tests can exercise the behavior without
+ * instantiating the full LuCLI module (which depends on a `modules.BaseModule`
+ * mapping that only exists when LuCLI is hosting the runtime).
+ */
+component {
+
+	public function init() {
+		return this;
+	}
+
+	/**
+	 * True if the project's `config/app.cfm` declares any kind of SQLite
+	 * datasource. Detection covers both the legacy app.cfm format that
+	 * carried `bundleName: "org.xerial.sqlite-jdbc"` and the current format
+	 * (post-#2304) that omits the bundleName hint and relies on classpath
+	 * resolution of `org.sqlite.JDBC`.
+	 *
+	 * @projectRoot Absolute path to the project root (where config/app.cfm
+	 *              lives). Empty / missing path → returns false.
+	 */
+	public boolean function projectUsesSqliteDatasource(required string projectRoot) {
+		if (!len(arguments.projectRoot)) return false;
+		var appCfm = arguments.projectRoot & "/config/app.cfm";
+		if (!fileExists(appCfm)) return false;
+		var content = fileRead(appCfm);
+		return findNoCase("jdbc:sqlite:", content) > 0
+			|| findNoCase("org.sqlite.JDBC", content) > 0
+			|| findNoCase("org.xerial.sqlite-jdbc", content) > 0;
+	}
+
+	/**
+	 * Copy the given JAR into every Lucee Express install's `lib/ext/`
+	 * directory beneath `expressRoot`. Idempotent — skips destinations that
+	 * already have the JAR. Best-effort — silently swallows per-version
+	 * copy failures so a permission issue on one Lucee version doesn't
+	 * block staging for others.
+	 *
+	 * Returns a struct documenting what happened, useful for tests and
+	 * future logging:
+	 *   { staged: [list of dest paths written],
+	 *     skipped: [list of dest paths that already existed],
+	 *     failed:  [list of dest paths we couldn't write] }
+	 *
+	 * @bundleSrc   Absolute path to the source JAR (e.g. inside the
+	 *              wheels-module distribution at
+	 *              cli/lucli/resources/extensions/sqlite/<jar>.jar).
+	 * @expressRoot Absolute path to LUCLI_HOME/express/ — staging looks at
+	 *              every immediate child directory and treats it as a Lucee
+	 *              version.
+	 * @jarFileName Filename to use at the destination (typically the
+	 *              upstream Maven artifact name, e.g.
+	 *              `sqlite-jdbc-3.49.1.0.jar`, since Tomcat's classpath
+	 *              loader doesn't care about OSGi symbolic-name renaming).
+	 */
+	public struct function stageIntoLibExt(
+		required string bundleSrc,
+		required string expressRoot,
+		required string jarFileName
+	) {
+		var result = { staged: [], skipped: [], failed: [] };
+		if (!fileExists(arguments.bundleSrc)) return result;
+		if (!directoryExists(arguments.expressRoot)) return result;
+
+		var versions = directoryList(arguments.expressRoot, false, "name");
+		for (var v in versions) {
+			var libExt = arguments.expressRoot & "/" & v & "/lib/ext";
+			if (!directoryExists(libExt)) continue;
+			var dest = libExt & "/" & arguments.jarFileName;
+			if (fileExists(dest)) {
+				arrayAppend(result.skipped, dest);
+				continue;
+			}
+			try {
+				fileCopy(arguments.bundleSrc, dest);
+				arrayAppend(result.staged, dest);
+			} catch (any e) {
+				arrayAppend(result.failed, dest);
+			}
+		}
+		return result;
+	}
+
+}
@@ -0,0 +1,169 @@
+/**
+ * Regression coverage for GH #2326 (F8) — fresh `wheels new` apps fail to
+ * resolve `org.sqlite.JDBC` because Lucee 7's stock Express distribution
+ * doesn't ship the SQLite driver. BundleStager is what `wheels start`
+ * delegates to before booting Lucee; it stages the patched JAR into every
+ * Lucee Express install's lib/ext/ so the Tomcat classpath can resolve it.
+ */
+component extends="wheels.wheelstest.system.BaseSpec" {
+
+	function beforeAll() {
+		variables.stager = new cli.lucli.services.BundleStager();
+	}
+
+	private string function makeTempProject(required string appCfmContent) {
+		var root = getTempDirectory() & "wheels-bundlestager-#createUUID()#";
+		directoryCreate(root, true);
+		directoryCreate(root & "/config", true);
+		fileWrite(root & "/config/app.cfm", arguments.appCfmContent);
+		return root;
+	}
+
+	private string function makeTempBundleJar() {
+		var jar = getTempDirectory() & "wheels-bundle-src-#createUUID()#.jar";
+		fileWrite(jar, "fake jar content");
+		return jar;
+	}
+
+	private string function makeTempExpressRoot(required array versions) {
+		var root = getTempDirectory() & "wheels-express-#createUUID()#";
+		directoryCreate(root, true);
+		for (var v in arguments.versions) {
+			directoryCreate(root & "/" & v & "/lib/ext", true);
+		}
+		return root;
+	}
+
+	function run() {
+		describe("BundleStager.projectUsesSqliteDatasource", () => {
+
+			it("returns true when app.cfm references the jdbc:sqlite: URL prefix (current format, post-##2304)", () => {
+				var p = makeTempProject('<cfscript>
+					this.datasources["app"] = {
+						class: "org.sqlite.JDBC",
+						connectionString: "jdbc:sqlite:" & expandPath("../db/app.sqlite")
+					};
+				</cfscript>');
+				try {
+					expect(variables.stager.projectUsesSqliteDatasource(p)).toBeTrue();
+				} finally {
+					directoryDelete(p, true);
+				}
+			});
+
+			it("returns true when app.cfm references the OSGi bundleName hint (legacy format)", () => {
+				var p = makeTempProject('<cfscript>
+					this.datasources["app"] = {
+						class: "org.sqlite.JDBC",
+						bundleName: "org.xerial.sqlite-jdbc",
+						connectionString: "jdbc:sqlite:" & expandPath("../db/app.sqlite")
+					};
+				</cfscript>');
+				try {
+					expect(variables.stager.projectUsesSqliteDatasource(p)).toBeTrue();
+				} finally {
+					directoryDelete(p, true);
+				}
+			});
+
+			it("returns false for non-SQLite datasources (regression — don't stage for postgres/mysql apps)", () => {
+				var p = makeTempProject('<cfscript>
+					this.datasources["app"] = {
+						class: "org.postgresql.Driver",
+						connectionString: "jdbc:postgresql://localhost:5432/app"
+					};
+				</cfscript>');
+				try {
+					expect(variables.stager.projectUsesSqliteDatasource(p)).toBeFalse();
+				} finally {
+					directoryDelete(p, true);
+				}
+			});
+
+			it("returns false when projectRoot is empty", () => {
+				expect(variables.stager.projectUsesSqliteDatasource("")).toBeFalse();
+			});
+
+			it("returns false when config/app.cfm is missing", () => {
+				var root = getTempDirectory() & "wheels-bundlestager-empty-#createUUID()#";
+				directoryCreate(root, true);
+				try {
+					expect(variables.stager.projectUsesSqliteDatasource(root)).toBeFalse();
+				} finally {
+					directoryDelete(root, true);
+				}
+			});
+		});
+
+		describe("BundleStager.stageIntoLibExt", () => {
+
+			it("copies the bundle JAR into every Lucee version's lib/ext/", () => {
+				var jar = makeTempBundleJar();
+				var express = makeTempExpressRoot(["7.0.0.395", "6.2.2.91"]);
+				try {
+					var r = variables.stager.stageIntoLibExt(jar, express, "sqlite-jdbc-3.49.1.0.jar");
+					expect(arrayLen(r.staged)).toBe(2);
+					expect(arrayLen(r.skipped)).toBe(0);
+					expect(arrayLen(r.failed)).toBe(0);
+					expect(fileExists(express & "/7.0.0.395/lib/ext/sqlite-jdbc-3.49.1.0.jar")).toBeTrue();
+					expect(fileExists(express & "/6.2.2.91/lib/ext/sqlite-jdbc-3.49.1.0.jar")).toBeTrue();
+				} finally {
+					fileDelete(jar);
+					directoryDelete(express, true);
+				}
+			});
+
+			it("is idempotent — already-staged JARs report as 'skipped' (no overwrite)", () => {
+				var jar = makeTempBundleJar();
+				var express = makeTempExpressRoot(["7.0.0.395"]);
+				try {
+					variables.stager.stageIntoLibExt(jar, express, "sqlite-jdbc-3.49.1.0.jar");
+					var r2 = variables.stager.stageIntoLibExt(jar, express, "sqlite-jdbc-3.49.1.0.jar");
+					expect(arrayLen(r2.staged)).toBe(0);
+					expect(arrayLen(r2.skipped)).toBe(1);
+					expect(arrayLen(r2.failed)).toBe(0);
+				} finally {
+					fileDelete(jar);
+					directoryDelete(express, true);
+				}
+			});
+
+			it("returns empty result when expressRoot is missing (no Lucee installed yet)", () => {
+				var jar = makeTempBundleJar();
+				try {
+					var r = variables.stager.stageIntoLibExt(jar, "/nonexistent/path", "sqlite-jdbc-3.49.1.0.jar");
+					expect(arrayLen(r.staged)).toBe(0);
+				} finally {
+					fileDelete(jar);
+				}
+			});
+
+			it("returns empty result when bundleSrc is missing (dev checkout without baked-in JAR)", () => {
+				var express = makeTempExpressRoot(["7.0.0.395"]);
+				try {
+					var r = variables.stager.stageIntoLibExt("/nonexistent.jar", express, "sqlite-jdbc-3.49.1.0.jar");
+					expect(arrayLen(r.staged)).toBe(0);
+					expect(arrayLen(r.skipped)).toBe(0);
+				} finally {
+					directoryDelete(express, true);
+				}
+			});
+
+			it("skips Express versions that don't have a lib/ext/ directory", () => {
+				var jar = makeTempBundleJar();
+				var express = getTempDirectory() & "wheels-express-partial-#createUUID()#";
+				directoryCreate(express, true);
+				directoryCreate(express & "/7.0.0.395/lib/ext", true);
+				directoryCreate(express & "/broken-version", true); // no lib/ext
+				try {
+					var r = variables.stager.stageIntoLibExt(jar, express, "sqlite-jdbc-3.49.1.0.jar");
+					expect(arrayLen(r.staged)).toBe(1);
+					expect(fileExists(express & "/7.0.0.395/lib/ext/sqlite-jdbc-3.49.1.0.jar")).toBeTrue();
+				} finally {
+					fileDelete(jar);
+					directoryDelete(express, true);
+				}
+			});
+		});
+	}
+}