fix(cli): close 0.0.0-dev version display gap on installed Wheels apps (#2348)

* feat(cli): add Wheels SQLite Lucee extension (.lex) for fresh-VM bundle gap

Build, install, and ship a Lucee CFML extension that packages the xerial
sqlite-jdbc OSGi bundle so Lucee 7 can resolve `org.sqlite.JDBC` for
`wheels new` SQLite-by-default datasources without manual JAR drops.

This addresses fresh-VM onboarding finding F8 — the SQLite class-load
cliff that blocks every fresh `wheels migrate latest` because Lucee 7
ships drivers for MySQL/MSSQL/PostgreSQL/HSQLDB but not SQLite.

What's in tools/lucee-extensions/sqlite/:

- src/build.properties + src/SQLite.cfc + src/sqlite-jdbc-3.49.1.0.jar
  (vendored from Maven Central) — extension source.
- build.sh produces dist/org.xerial.sqlite-jdbc-3.49.1.0.lex (~14 MB).
  Mirrors the layout/manifest of lucee/extension-jdbc-postgresql and
  lucee/extension-jdbc-duckdb but uses bash+zip instead of Ant.
- install.sh drops the patched bundle straight into a Lucee server's
  lucee-server/bundles/ directory — deterministic on Lucee 7 and the
  recommended path until the deploy/ auto-install quirk is solved.
- README documents three install paths (bundle/.lex/admin UI), the
  upstream upgrade plan, and the OSGi manifest patch.

The non-obvious fix: xerial's JAR is a valid OSGi bundle, but it
declares `Require-Capability: osgi.ee;version=1.8` (exact match in some
resolvers). Felix on Java 21 cannot satisfy that, so the bundle is
silently rejected. build.sh patches the JAR's MANIFEST.MF to
`(version>=1.8)` (matching PostgreSQL's filter) and drops the
`;singleton:=true` directive on Bundle-SymbolicName. Original JAR in
src/ is untouched — the patch is applied during build.

Verified end-to-end on macOS arm64 + Lucee 7.0.0.395:

  BEFORE install.sh: dbtest -> FAIL "org.xerial.sqlite-jdbc not available locally"
  AFTER  install.sh: dbtest -> OK datasource=sqliteapp result=1
  AFTER  install.sh: wheels migrate latest creates tables in db/development.sqlite

Follow-ups (separate PRs):
1. Wire `wheels new` (or first `wheels start`) to auto-run install.sh
   against the freshly-created server so SQLite-by-default works
   zero-config on fresh VMs.
2. Debug Lucee 7's deploy/ -> failed-to-deploy/ silent quarantine so
   the canonical deploy/ install path works without falling back to
   the bundle drop.
3. File upstream PR as lucee/extension-jdbc-sqlite once stable so the
   Lucee community gets it via the standard update server, and a
   separate issue with xerial/sqlite-jdbc to relax their OSGi
   Require-Capability filter.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(cli): close 0.0.0-dev version display gap on installed Wheels apps

Two compounding bugs caused the dev toolbar / /wheels/info to report
"Wheels Version: 0.0.0-dev" on installed (brew/chocolatey) apps even
though every release artifact already carries the precise SNAPSHOT
build version. Both are fixed here.

## Bug 1 — wheels-module tarball never substitutes module.json

release.yml's "Build Wheels Module Tarball" step tars cli/lucli/
directly with no version substitution, while wheels-core/wheels-base
(which run through prepare-*.sh) get @build.version@ properly replaced.
As a result every wheels-module-*.tar.gz on the GitHub releases page
ships with module.json's hardcoded "version": "4.0.0" — even though
the tag itself is "v4.0.0-SNAPSHOT+1625".

That hardcoded value is then read by BaseModule.version() at runtime
and fed into FrameworkInstaller.rewriteVersionPlaceholder as the
cliVersion fallback (added in #2343 / #2333), so on installs whose
vendor/wheels/box.json went through that fallback path, the framework
"version" is the imprecise "4.0.0" instead of the build's
"4.0.0-SNAPSHOT+1625".

Fix: change cli/lucli/module.json to use "version": "@build.version@"
(matching every other manifest in the repo), and add the same find +
sed substitution release.yml's other build steps already do, in the
"Build Wheels Module Tarball" step before tar/zip. Uses an env: block
to satisfy our workflow injection lint and avoids inlining the version
into shell commands.

## Bug 2 — runtime fallback only recognizes the monorepo's box.json

When vendor/wheels/box.json's @build.version@ leaks through scaffold-
time substitution (e.g. user's CLI is pre-#2343, or any other gap in
the install pipeline), Global.cfc:$readFrameworkVersion's fallback
walks two levels up looking for the wheels-dev/wheels monorepo's
box.json — and only synthesizes "<rootversion>-dev" when slug=="wheels"
or name=="Wheels.fw". An installed app's app-root box.json comes from
wheels-base-template (slug=wheels-base-template), which carries the
precise framework SNAPSHOT version stamped at release time — but the
fallback rejects it because the monorepo signal is absent. Fall-through
returns the bare "0.0.0-dev" sentinel.

Fix: extend the fallback so when the monorepo signal is missing AND
the parent's box.json self-identifies as wheels-base-template (slug or
name match), use its version verbatim (no -dev suffix — that version is
the actual installed framework version, not an upcoming dev build).
The monorepo signal still wins when both could match; both signals are
ignored if their version is itself the unreplaced placeholder.

Three new specs in frameworkVersionSpec.cfc cover the new path,
including the precedence ordering and the placeholder guard. Existing
specs (including the regression for #2291) still pass.

## Verification

- Framework suite: 3333 passed (no regressions).
- CLI suite: 452 pass, 3 fail — pre-existing DoctorSpec issues (#2260),
  unrelated.
- Local dry-run of the release.yml sed substitution: cli/lucli/module.json
  picks up MODULE_VERSION, no other false positives in cli/lucli/.

Closes #2326.

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: bpamiri

.github/workflows/release.yml

@@ -203,16 +203,26 @@ jobs:
           ./tools/build/scripts/build-starterApp.sh "${{ env.WHEELS_VERSION }}"
 
       - name: Build Wheels Module Tarball
+        env:
+          MODULE_VERSION: ${{ env.WHEELS_VERSION }}
         run: |
-          mkdir -p artifacts/wheels/${{ env.WHEELS_VERSION }}
+          mkdir -p "artifacts/wheels/${MODULE_VERSION}"
           # Bundle codegen templates into the module so Templates.cfc::resolveTemplateDir()
           # finds them at moduleRoot/templates/codegen/ in installed distributions.
           # Without this, every template-driven generator (model, controller, view,
           # scaffold, helper, api-resource) fails or emits empty output. See #1944.
           mkdir -p cli/lucli/templates/codegen
           cp -R cli/src/templates/. cli/lucli/templates/codegen/
-          tar czf artifacts/wheels/${{ env.WHEELS_VERSION }}/wheels-module-${{ env.WHEELS_VERSION }}.tar.gz -C cli/lucli .
-          cd cli/lucli && zip -r ../../artifacts/wheels/${{ env.WHEELS_VERSION }}/wheels-module-${{ env.WHEELS_VERSION }}.zip . && cd ../..
+          # Substitute @build.version@ placeholders in the LuCLI module before
+          # tarring. Without this, module.json ships with the literal placeholder
+          # (or a stale hardcoded version), causing BaseModule.version() to return
+          # the wrong value at runtime and the dev toolbar / `wheels --help` to
+          # report a stale version. Mirrors the substitution prepare-cli.sh does
+          # for the wheels-cli ForgeBox artifact. See #2326.
+          find cli/lucli -type f \( -name "*.json" -o -name "*.md" -o -name "*.cfm" -o -name "*.cfc" \) -exec sed -i.bak "s/@build\.version@/${MODULE_VERSION}/g" {} \;
+          find cli/lucli -name "*.bak" -delete
+          tar czf "artifacts/wheels/${MODULE_VERSION}/wheels-module-${MODULE_VERSION}.tar.gz" -C cli/lucli .
+          cd cli/lucli && zip -r "../../artifacts/wheels/${MODULE_VERSION}/wheels-module-${MODULE_VERSION}.zip" . && cd ../..
           cd artifacts/wheels/${{ env.WHEELS_VERSION }}
           md5sum wheels-module-${{ env.WHEELS_VERSION }}.tar.gz > wheels-module-${{ env.WHEELS_VERSION }}.tar.gz.md5 || md5 -r wheels-module-${{ env.WHEELS_VERSION }}.tar.gz > wheels-module-${{ env.WHEELS_VERSION }}.tar.gz.md5
           sha512sum wheels-module-${{ env.WHEELS_VERSION }}.tar.gz > wheels-module-${{ env.WHEELS_VERSION }}.tar.gz.sha512 || shasum -a 512 wheels-module-${{ env.WHEELS_VERSION }}.tar.gz > wheels-module-${{ env.WHEELS_VERSION }}.tar.gz.sha512

cli/lucli/module.json

@@ -1,6 +1,6 @@
 {
   "name": "wheels",
-  "version": "4.0.0",
+  "version": "@build.version@",
   "description": "Wheels CLI - Code generation, migrations, testing, and server management for Wheels",
   "author": "Wheels Team",
   "license": "Apache-2.0",

vendor/wheels/Global.cfc

@@ -2782,28 +2782,38 @@ return local.$wheels;
 			);
 		}
 		if (local.box.version == "@build.version@") {
-			// Dev checkout. Try to synthesize a more useful version by reading the
-			// enclosing repo's root box.json — when that box.json identifies itself as
-			// the wheels-dev/wheels monorepo, report "<rootversion>-dev" so the
-			// homepage shows the upcoming version rather than a blank placeholder.
+			// The framework's own box.json was shipped with the placeholder
+			// unsubstituted (dev checkout, or release-pipeline gap). Try, in
+			// order: (1) the enclosing repo's root box.json — for a wheels-dev/
+			// wheels monorepo dev checkout, that resolves to a `<rootversion>-dev`
+			// version reflecting the upcoming release; (2) the app's own box.json
+			// — for an installed app scaffolded from `wheels-base-template`, that
+			// box.json carries the precise framework SNAPSHOT version stamped in
+			// at release time, so we use it verbatim. Without this second probe,
+			// the runtime returns a misleading "0.0.0-dev" on installed apps when
+			// the framework's box.json substitution slipped through (see GH #2326).
 			local.rootPath = Len(arguments.rootBoxJsonPath)
 				? arguments.rootBoxJsonPath
 				: GetDirectoryFromPath(GetCurrentTemplatePath()) & "../../box.json";
 			try {
 				if (FileExists(local.rootPath)) {
 					local.rootBox = DeserializeJSON(FileRead(local.rootPath));
-					local.isWheelsRepo = IsStruct(local.rootBox)
-						&& (
-							(StructKeyExists(local.rootBox, "slug") && local.rootBox.slug == "wheels")
-							|| (StructKeyExists(local.rootBox, "name") && local.rootBox.name == "Wheels.fw")
-						);
-					if (
-						local.isWheelsRepo
-						&& StructKeyExists(local.rootBox, "version")
-						&& Len(local.rootBox.version)
-						&& local.rootBox.version != "@build.version@"
-					) {
-						return local.rootBox.version & "-dev";
+					if (IsStruct(local.rootBox) && StructKeyExists(local.rootBox, "version") && Len(local.rootBox.version) && local.rootBox.version != "@build.version@") {
+						local.isWheelsRepo = (StructKeyExists(local.rootBox, "slug") && local.rootBox.slug == "wheels")
+							|| (StructKeyExists(local.rootBox, "name") && local.rootBox.name == "Wheels.fw");
+						if (local.isWheelsRepo) {
+							return local.rootBox.version & "-dev";
+						}
+						// 2. Installed app: the parent's box.json is the user's
+						//    scaffolded app.box.json, which `wheels-base-template`
+						//    fills with the precise framework version at release
+						//    time. Recognize the template by slug so we don't pick
+						//    up a hand-rolled box.json with an unrelated version.
+						local.isBaseTemplate = (StructKeyExists(local.rootBox, "slug") && local.rootBox.slug == "wheels-base-template")
+							|| (StructKeyExists(local.rootBox, "name") && local.rootBox.name == "Wheels Base Template");
+						if (local.isBaseTemplate) {
+							return local.rootBox.version;
+						}
 					}
 				}
 			} catch (any e) {

vendor/wheels/tests/specs/events/frameworkVersionSpec.cfc

@@ -61,6 +61,54 @@ component extends="wheels.WheelsTest" {
 				}
 			});
 
+			it("$readFrameworkVersion uses wheels-base-template's version verbatim when the framework's own box.json placeholder slipped through (##2326)", () => {
+				// Installed-app path: the user's `wheels new`-scaffolded app has a
+				// box.json at the app root populated from `wheels-base-template`
+				// (slug=wheels-base-template), and that box.json carries the
+				// precise framework SNAPSHOT version stamped at release time. If
+				// the framework's own box.json substitution slipped through, we
+				// still surface the correct version instead of "0.0.0-dev".
+				var fwTmp = getTempDirectory() & "wheels-version-fw-#CreateUUID()#.json";
+				var rootTmp = getTempDirectory() & "wheels-version-root-#CreateUUID()#.json";
+				fileWrite(fwTmp, '{"version":"@build.version@"}');
+				fileWrite(rootTmp, '{"name":"Wheels Base Template","slug":"wheels-base-template","version":"4.0.0-SNAPSHOT+1625"}');
+				try {
+					expect(g.$readFrameworkVersion(fwTmp, rootTmp)).toBe("4.0.0-SNAPSHOT+1625");
+				} finally {
+					fileDelete(fwTmp);
+					fileDelete(rootTmp);
+				}
+			});
+
+			it("$readFrameworkVersion ignores wheels-base-template when its own version is also the unreplaced placeholder (##2326)", () => {
+				var fwTmp = getTempDirectory() & "wheels-version-fw-#CreateUUID()#.json";
+				var rootTmp = getTempDirectory() & "wheels-version-root-#CreateUUID()#.json";
+				fileWrite(fwTmp, '{"version":"@build.version@"}');
+				fileWrite(rootTmp, '{"name":"Wheels Base Template","slug":"wheels-base-template","version":"@build.version@"}');
+				try {
+					expect(g.$readFrameworkVersion(fwTmp, rootTmp)).toBe("0.0.0-dev");
+				} finally {
+					fileDelete(fwTmp);
+					fileDelete(rootTmp);
+				}
+			});
+
+			it("$readFrameworkVersion prefers the monorepo signal over the base-template signal when both could match (##2326)", () => {
+				// Defensive: if both the monorepo and base-template markers somehow
+				// coexist at the same path, the monorepo signal (a dev checkout)
+				// is the authoritative one and the suffix should be "-dev".
+				var fwTmp = getTempDirectory() & "wheels-version-fw-#CreateUUID()#.json";
+				var rootTmp = getTempDirectory() & "wheels-version-root-#CreateUUID()#.json";
+				fileWrite(fwTmp, '{"version":"@build.version@"}');
+				fileWrite(rootTmp, '{"name":"Wheels.fw","slug":"wheels","version":"4.0.0"}');
+				try {
+					expect(g.$readFrameworkVersion(fwTmp, rootTmp)).toBe("4.0.0-dev");
+				} finally {
+					fileDelete(fwTmp);
+					fileDelete(rootTmp);
+				}
+			});
+
 			it("$readFrameworkVersion falls back to 0.0.0-dev when the enclosing box.json is also unreplaced", () => {
 				var fwTmp = getTempDirectory() & "wheels-version-fw-#CreateUUID()#.json";
 				var rootTmp = getTempDirectory() & "wheels-version-root-#CreateUUID()#.json";