Merge remote-tracking branch 'origin/develop' into claude/pedantic-mirzakhani-27b839

# Conflicts:
#	CHANGELOG.md

Author: bpamiri

CHANGELOG.md

@@ -104,6 +104,7 @@ All historical references to "CFWheels" in this changelog have been preserved fo
 ### Changed
 
 - **Breaking:** CORS middleware default changed from wildcard `*` to deny-all. Apps must explicitly configure `allowOrigins` or set an explicit wildcard. (#2039)
+- **Breaking:** `viteStrictManifest` defaults to `true` — a missing Vite manifest entry now throws `Wheels.ViteAssetNotFound` in production instead of silently falling back (3.x behavior). Rebuild Vite assets during the upgrade window; to retain 3.x silent behavior, `set(viteStrictManifest=false)`. (#2133)
 - **Breaking:** `allowEnvironmentSwitchViaUrl` defaults to `false` in production (#2076)
 - **Breaking:** Reload password must be non-empty for environment switching in production (#2082)
 - **Breaking:** HSTS header defaults on in production (#2081)
@@ -130,6 +131,7 @@ All historical references to "CFWheels" in this changelog have been preserved fo
 - RocketUnit test style for new tests — BDD syntax (via WheelsTest) is required going forward. Existing RocketUnit specs continue to run. (#1925)
 - `wheels.Test` test base class — extend `wheels.WheelsTest` instead (#1889)
 - In-dev-server HTTP MCP endpoint at `/wheels/mcp` — superseded by the LuCLI stdio MCP server (`wheels mcp wheels`). Emits a deprecation warning to the `wheels_mcp` log on first request and advertises `deprecated: true` in the `serverInfo` handshake. Scheduled for removal in a future release. Migrate existing projects with `wheels mcp setup --force`.
+- Legacy CommandBox `wheels-cli` module (`wheels g app`, `wheels new` via the CommandBox wizard) — superseded by LuCLI's canonical `wheels new`. Emits a deprecation banner on every invocation. Scheduled for removal in v5.0. (#2227)
 
 ### Removed
 
@@ -142,6 +144,7 @@ All historical references to "CFWheels" in this changelog have been preserved fo
 ### Fixed
 
 - `wheels routes`, `reload`, `test`, `console`, `migrate`, `seed`, `db status`, `db version`, and `generate admin` now exit non-zero when no Wheels dev server is running. Previously these commands printed a red diagnostic but returned `""`, producing exit 0 — MCP clients and shell automation couldn't distinguish "succeeded with no output" from "server down, nothing ran". A shared `$requireRunningServer()` helper now throws a typed `Wheels.ServerNotRunning` exception that LuCLI's `ExecutionExceptionHandler` maps to exit 1. (#2229)
+- Legacy CommandBox `wheels g app` now scaffolds a 4.0 app by default — the `wheels-base-template` default was pinned at `@^3.1.0`, so `box install wheels-cli && wheels g app myapp` produced a 3.x scaffold at 4.0 GA. Updated default (and the `WheelsBaseTemplate` shortcut + wizard default selection) to `@^4.0.0`, fixed the stale "Default is Bleeding Edge" docstring, and added a deprecation banner pointing users at LuCLI's `wheels new`. (#2227)
 - `changeColumn` on SQLite now works by implementing the SQLite-standard recreate-table pattern in `SQLiteMigrator`. Previously, SQLite migrations inherited MySQL's `ALTER TABLE ... CHANGE` syntax from `Abstract.cfc` and failed with `near "CHANGE": syntax error`. The migrator's `$execute` now accepts an array of statements so adapters can return multi-step DDL. v1 limitations: foreign-key constraints declared inline on `CREATE TABLE` and triggers are not preserved across the recreate. (#2207)
 - Framework-internal browser-test fixture controllers, views, and the `/_browser/*` routes no longer leak into application-level files. Moved from `app/controllers/BrowserTest*.cfc`, `app/views/browsertest*/`, and `config/routes.cfm` into `vendor/wheels/public/browser-fixtures/`, auto-mounted by `$lockedLoadRoutes` when environment is `testing` or `development` and the new opt-in setting `loadBrowserTestFixtures=true` is set. Apps upgrading from a 4.0 snapshot that had custom `/_browser/*` routes must opt in explicitly or re-declare them in `config/routes.cfm`. (#2135, #2138)
 - Stray `app/mailers/UserNotificationsMailer.cfc` demo removed from the framework repo root (byte-identical copies remain in the example apps under `examples/tweet/` and `examples/starter-app/`). (#2138)

cli/src/commands/wheels/generate/app-wizard.cfc

@@ -156,7 +156,7 @@ component aliases="wheels g app-wizard, wheels new" extends="../base" {
 
     var template = multiselect( 'Which Wheels Template shall we use? ' )
       .options( [
-        {value: 'wheels-base-template@^3.1.0', display: '3.1 - Wheels Base Template - Stable', selected: true},
+        {value: 'wheels-base-template@^4.0.0', display: '4.0 - Wheels Base Template - Stable', selected: true},
         {value: 'wheels-base-template@BE', display: 'Bleeding Edge - Wheels Base Template'},
         {value: 'wheels-template-htmx-alpine-simple', display: 'Wheels Template - HTMX - Alpine.js - Simple.css'},
         {value: 'wheels-starter-app', display: 'Wheels Starter App'},

cli/src/commands/wheels/generate/app.cfc

@@ -14,7 +14,7 @@
  *  {code}
  *
  *  Here are the basic templates that are available for you that come from ForgeBox
- *  - Wheels Base Template - 3.0 Stable (default)
+ *  - Wheels Base Template - 4.0 Stable (default)
  *  - Wheels Base Template - Bleeding Edge
  *  - Wheels Template - HelloWorld
  *  - Wheels Template - HelloDynamic
@@ -43,7 +43,7 @@ component aliases="wheels g app" extends="../base" {
 
     // Map these shortcut names to the actual ForgeBox slugs
     variables.templateMap = {
-      'WheelsBaseTemplate'        : 'wheels-base-template@^3.1.0',
+      'WheelsBaseTemplate'        : 'wheels-base-template@^4.0.0',
       'BleedingEdge'              : 'wheels-base-template@BE',
       'WheelsTemplateHTMX'        : 'wheels-template-htmx-alpine-simple',
       'WheelsStarterApp'          : 'wheels-starter-app',
@@ -55,7 +55,7 @@ component aliases="wheels g app" extends="../base" {
 
   /**
    * @name           The name of the app you want to create
-   * @template       The name of the app template to generate (or an endpoint ID like a forgebox slug). Default is Bleeding Edge
+   * @template       The name of the app template to generate (or an endpoint ID like a forgebox slug). Default is the stable Wheels Base Template (4.0).
    * @directory      The directory to create the app in
    * @reloadPassword The reload passwrod to set for the app
    * @datasourceName The datasource name to set for the app
@@ -68,7 +68,7 @@ component aliases="wheels g app" extends="../base" {
    **/
   function run(
     name     = 'MyApp',
-    template = 'wheels-base-template@^3.1.0',
+    template = 'wheels-base-template@^4.0.0',
     directory,
     reloadPassword = '',
     datasourceName,
@@ -86,6 +86,14 @@ component aliases="wheels g app" extends="../base" {
     // Initialize detail service
     var details = application.wirebox.getInstance("DetailOutputService@wheels-cli");
 
+    // Deprecation notice — legacy CommandBox surface is scheduled for removal in Wheels v5.0.
+    // Canonical 4.0+ CLI is LuCLI's `wheels new` (https://github.com/bpamiri/LuCLI).
+    details.getPrint().yellowBoldLine( "[DEPRECATED] 'wheels g app' (CommandBox wheels-cli) is deprecated." );
+    details.getPrint().yellowLine( "             Use LuCLI 'wheels new' instead — the canonical Wheels 4.0+ CLI." );
+    details.getPrint().yellowLine( "             Install: brew install lucli  (or see https://github.com/bpamiri/LuCLI)" );
+    details.getPrint().yellowLine( "             This command will be removed in Wheels v5.0." );
+    details.line();
+
     // set defaults based on app name
     if ( !len( arguments.directory ) ) {
       arguments.directory = '#getCWD()##arguments.name#';

web/sites/guides/src/content/docs/v4-0-0-snapshot/upgrading/3x-to-4x.mdx

@@ -8,7 +8,7 @@ sidebar:
 
 import { Aside, CardGrid, LinkCard, Steps } from '@astrojs/starlight/components';
 
-This guide walks every breaking change between Wheels 3.x and 4.0, with before/after code for each. Most 3.x apps upgrade in an afternoon. The pressure points are CORS defaults, the test base class rename, the `plugins/` → `packages/` split, and the `wheels` CLI command renames. Everything else is either additive or continues to work with a deprecation warning.
+This guide walks every breaking change between Wheels 3.x and 4.0, with before/after code for each. Most 3.x apps upgrade in an afternoon. The pressure points are CORS defaults, the test base class rename, the `plugins/` → `packages/` split, the `wheels` CLI command renames, and Vite manifest strictness (production now throws on missing entries — rebuild assets during the upgrade window). Everything else is either additive or continues to work with a deprecation warning.
 
 **You'll learn:**
 
@@ -37,7 +37,7 @@ This guide walks every breaking change between Wheels 3.x and 4.0, with before/a
 
 </Steps>
 
-## The ten breaking changes
+## The eleven breaking changes
 
 Each item cites its `CHANGELOG.md` "Changed" or "Removed" entry. Where the skeleton blog post calls out a two-path upgrade, Path A (fix directly) is documented here; Path B (the Legacy Compatibility Adapter, #2015) is covered at the end.
 
@@ -169,6 +169,28 @@ var svc = service("emailService");
 
 `service()` is the new global helper (#1933); prefer it over reaching into the container.
 
+### 11. Vite manifest strictness — missing entries throw in production
+
+**CHANGELOG:** `Breaking: viteStrictManifest defaults to true` (#2133).
+
+In 3.x, a missing entry in `public/assets/.vite/manifest.json` silently fell back to the raw source path. In 4.0, the default flips: `viteScriptTag()`, `viteStyleTag()`, and `vitePreloadTag()` throw `Wheels.ViteAssetNotFound` in production when the manifest doesn't contain the requested entrypoint. This catches stale-build deploys at first request instead of letting them ship broken `<script>` tags to the browser.
+
+The most common failure mode is a deploy that pushes new CFML code without rebuilding the Vite bundle — the manifest on the server is older than the entrypoint referenced in a view.
+
+**Recommended fix — rebuild assets as part of the deploy:**
+
+```bash title="your shell (or CI/CD deploy step)"
+npm run build   # produces public/assets/.vite/manifest.json
+```
+
+**Escape hatch — restore 3.x silent-fallback behavior:**
+
+```cfm {test:compile} title="config/settings.cfm"
+set(viteStrictManifest = false);
+```
+
+Use the escape hatch only if you can't rebuild assets during the upgrade window — then flip it back on once your deploy pipeline emits the manifest reliably.
+
 ## Deprecations you should plan to address
 
 ### Plugins → packages
@@ -270,7 +292,7 @@ The `/_browser/home`, `/_browser/login`, `/_browser/dashboard`, `/_browser/login
 
 **CHANGELOG:** `Legacy compatibility adapter for 3.x → 4.0 migration soft-landing` (#2015), shipped as `packages/legacyadapter/`.
 
-When you can't fix all ten breaking items in one sprint, activate the adapter, ship the upgrade, and modernize incrementally:
+When you can't fix all eleven breaking items in one sprint, activate the adapter, ship the upgrade, and modernize incrementally:
 
 ```bash title="your shell"
 cp -r packages/legacyadapter vendor/legacyadapter
@@ -322,6 +344,7 @@ These are additive in 4.0 and worth adopting during the upgrade window:
 - **Test runner can't find specs.** Check for `tests/specs/functions/` — rename to `functional/`. See #1872.
 - **Plugin warning at startup.** Port to `packages/` (see above) or accept the warning until you do.
 - **JWT tokens reject as invalid after upgrade.** Algorithm validation is on. Confirm your issuer sets `alg` to a supported value and the signature verification path uses constant-time comparison. See #2079, #2086.
+- **`Wheels.ViteAssetNotFound` thrown on first request after deploy.** The deploy shipped code referencing a Vite entrypoint that isn't in the manifest. Rebuild Vite assets (`npm run build`) before deploy, or temporarily `set(viteStrictManifest=false)` to restore 3.x silent fallback. See #2133.
 
 ## Related guides