chore: release 4.2.0

.ai/wheels/cross-engine-compatibility.md

@@ -100,6 +100,36 @@ var fn = obj["dynamicMethod"];
 var result = fn();
 ```
 
+### Quoted Named Argument in a Direct Call (Adobe CF 2023)
+
+A named argument whose *name* is a quoted string literal — `obj.method("name" = value)` — is a **compile error on Adobe CF 2023 only** (`MissingNameException: Invalid construct: Either argument or name is missing` / "each parameter must have a name"). Lucee 6/7, BoxLang, **and Adobe CF 2025** all accept it. This is the inverse footprint of the related invariants: the parenthesized-`new` receiver (invariant 16a) fails on both Adobe engines, the zero-arg `application`-scope call (16b/16b-ext) is Adobe 2025 only, and this one is the lone **Adobe 2023-only** shape — so an Adobe 2025 smoke, or Lucee-only local verification, does **not** cover it.
+
+**Context-independent (unlike the closure-sensitive 16b-ext).** Probe-verified on adobe2023/62023, the quoted named-arg call fails identically in every call context tested — a single-expression arrow (`(x) => obj.method("n" = x)`), a block-bodied arrow, a regular `function()` closure, and a plain statement in a non-closure method body all throw the same `MissingNameException`. There is no "safe" context; only changing the call shape (below) helps.
+
+You only reach for a quoted argument name when the name is otherwise illegal as a bare token — a `$`-prefixed or hyphenated argument. Measured boundaries that compile on adobe2023 (do **not** "fix" these):
+- an *unquoted* named argument, `obj.method(name = value)`, compiles on every engine;
+- a quoted key in a *struct literal*, `{"$x" = 1}`, compiles everywhere — it is a struct key, not a function-argument name;
+- passing the same `$`-prefixed value via `argumentCollection` compiles everywhere.
+
+Adobe misattributes the error to the enclosing `describe(...)` / `function` line, and because the core suite compiles via `directory="wheels.tests.specs"`, a single occurrence zeroes the **entire adobe2023 leg** (`tests="0"` on every database) while Lucee/BoxLang/Adobe 2025 stay green.
+
+```cfm
+// WRONG — MissingNameException on adobe2023 (compiles on Lucee/BoxLang/adobe2025)
+var out = c.URLFor(controller = "posts", action = "index", "$argsResolved" = true);
+
+// RIGHT — the $-prefixed name lives on a struct key, not an argument name
+var args = {controller = "posts", action = "index"};
+args["$argsResolved"] = true;
+var out = c.URLFor(argumentCollection = args);
+```
+
+**Reference**: `vendor/wheels/tests/specs/view/linkToUrlForDifferentialSpec.cfc` ([#4192](https://github.com/wheels-dev/wheels/pull/4192)). It was pre-existing and only the adobe2023 matrix legs caught it. Bisect against a running container (~13s vs ~19min), using the Adobe 2023 port `62023`:
+
+```bash
+curl -s "http://localhost:62023/wheels/core/tests?db=sqlite&format=json&cli=true" | \
+  python3 -c "import json,sys; d=json.load(sys.stdin); print(d.get('totalPass','COMPILE FAIL'), d.get('RootCause',{}).get('snippet',''))"
+```
+
 ### Method Reference Extraction Loses Receiver (BoxLang)
 
 BoxLang implements method dispatch with JavaScript-style semantics: pulling a method off an object into a local variable produces a bare function reference with no bound receiver. Calling that local then runs the function in an empty context, and any in-component call inside (helpers prefixed with `$`, `this.x()`, etc.) fails to resolve. The lookup-and-call **must** stay in a single expression for BoxLang to bind the receiver.
@@ -230,6 +260,58 @@ try {
 
 **Reference example**: `$restoreEmailViewVariables()` in [`vendor/wheels/controller/miscellaneous.cfc`](../../vendor/wheels/controller/miscellaneous.cfc) — the `sendEmail` variables-scope restore runs from `finally` via a `public` `$`-prefixed helper (mixin invariant: helpers must be public). Found while addressing review on [#2922](https://github.com/wheels-dev/wheels/pull/2922).
 
+### `continue` and `break` in One `try`/`catch` Inside a Loop: `continue` Exits the Loop (Lucee 6/7)
+
+Inside a loop, a `try`/`catch` that contains **both** a `continue` and a `break` makes the `continue` leave the loop, as if it were a `break`. The `break` doesn't have to run: an `if (false) break;` in the `catch` is enough. Where the two keywords sit doesn't matter either: `continue` in the `try` and `break` in the `catch`, or both in the `catch`.
+
+```cfm
+// WRONG: on Lucee 6/7 this returns "first", not "first,second,third"
+local.trace = "";
+for (local.item in ["first", "second", "third"]) {
+    local.trace = ListAppend(local.trace, local.item);
+    try {
+        if (true) {
+            continue;
+        }
+    } catch (any e) {
+        break;
+    }
+}
+
+// RIGHT: no continue; let if/else carry control to the end of the iteration
+for (local.item in local.items) {
+    try {
+        if (skip(local.item)) {
+            recordSkip(local.item);
+        } else {
+            process(local.item);
+        }
+    } catch (any e) {
+        if (stopOnError) break;
+    }
+}
+```
+
+**Measured** with the same probe spec (compat-matrix dispatch, SQLite):
+
+| Engine (build) | `continue` + `break` in one `try`/`catch` inside a loop |
+|---|---|
+| Lucee 6.2.5.48 | **`continue` exits the loop** |
+| Lucee 7.0.1.100 (the CI pin) | **`continue` exits the loop** |
+| Lucee 7.0.0.395 (local) | **`continue` exits the loop** |
+| Adobe CF 2023.0.11, 2025.0.06 | correct |
+| BoxLang 1.11.0+52 | correct |
+
+The RustCFML v0.693.0 lane reported no failures in the same run; its per-spec result wasn't checked individually.
+
+**Measured as correct on every engine above:**
+- the same `try`/`catch` with a `continue` but no `break`;
+- a loop **inside** a `try` that uses both `continue` and `break` for that loop. This covers a `for`-in loop that continues and then breaks, a `while` with `break` around a nested `for` with `continue`, and one loop with both.
+
+The failing shape reproduces with `for`-in and index loops, with or without an outer `try`/`finally`.
+
+**Where it bit:** `TenantMigrator.migrateAll()`. A `continue` in the inner `try` (after recording a failed tenant), next to `if (arguments.stopOnError) break;` in its `catch`, recorded only the first failed tenant with `stopOnError = false`. The fix uses `if`/`else` ([#4169](https://github.com/wheels-dev/wheels/pull/4169)). A source sweep of `vendor/wheels/` when this was found turned up no other occurrence of the failing shape.
+
 ### `DirectoryCreate()` Second Argument Is Lucee-Only
 
 Lucee accepts `DirectoryCreate(path, createPath, mode)` and recurses parent directories when `createPath=true`. Adobe CF's signature varies by version and at least some Adobe builds reject any second argument with `"The function takes 1 parameter"` (issue #2567).

.ai/wheels/deploy.md

@@ -85,5 +85,5 @@ Fixtures at `cli/lucli/tests/_fixtures/deploy/configs/` (`minimal.yml`, `full.ym
 
 ## Reference docs
 
-- User guides: `web/sites/guides/src/content/docs/v4-0-0/deployment/` (first-deploy, production-config, accessories, secrets, hooks, migrating-from-kamal, security-hardening, docker-deployment)
+- User guides: `web/sites/guides/src/content/docs/v4-2-0/deployment/` (first-deploy, production-config, accessories, secrets, hooks, migrating-from-kamal, security-hardening, docker-deployment)
 - In-source CLI docs: `cli/lucli/services/deploy/cli/docs/` (per-verb)

.ai/wheels/testing/browser-testing.md

@@ -17,7 +17,6 @@ component extends="wheels.wheelstest.BrowserTest" {
         // from inside the suite body via this helper.
         browserDescribe("Login flow", () => {
             it("can load a page and read its title", () => {
-                if (this.browserTestSkipped) return;
                 this.browser.visitUrl("data:text/html,<title>Hi</title><h1>x</h1>")
                             .assertTitleContains("Hi");
             });
@@ -63,8 +62,9 @@ bash tools/test-local.sh                    # skips browser specs if JARs missin
 - **`##` in selectors** — CFML requires `##` to emit literal `#`. `"##email"` → `"#email"` at runtime.
 - **`client` is a Lucee reserved scope.** `var client = ...` in a closure throws "client scope is not enabled". Use `var c = ...` or `var bc = ...`. (Generalized rule: see CLAUDE.md anti-pattern #11.)
 - **Data URLs work for most tests** — no server needed for ~95% of DSL coverage. Full HTTP integration (cookies, form submits, redirects) needs a running fixture app; that wiring is the same as Wheels Web app bootstrap (separate server + baseUrl).
-- **`this.browserTestSkipped`** — when Playwright JARs aren't installed (fresh CI, clean machine), `beforeAll` sets this flag and `browserDescribe`'s hooks short-circuit. All `it`s should check `if (this.browserTestSkipped) return;` to stay green on CI.
-- **CI runs browser tests** — `pr.yml` and `snapshot.yml` install Playwright JARs + Chromium (cached via `browser-manifest.json` hash). Browser specs run as part of the normal test suite. `WHEELS_BROWSER_TEST_BASE_URL=http://localhost:60007` is set automatically. The base URL is resolved at instance time through a layered lookup (`this.baseUrl` → Wheels setting → JVM property `wheels.browserTest.baseUrl` → env var → CGI auto-detect → `http://localhost:8080`); per-spec `this.baseUrl` takes priority over the env var. Set `this.baseUrl` in the component pseudo-constructor (outside any function), not inside `beforeAll()` — `super.beforeAll()` calls `$resolveBaseUrl()` and caches the result, so a `this.baseUrl =` assignment that runs after `super.beforeAll()` is silently ignored.
+- **`this.browserTestSkipped`** — when Playwright JARs aren't installed (fresh CI, clean machine), `beforeAll` sets this flag and `browserDescribe`'s hooks short-circuit: each spec is reported as **Skipped** with `this.browserTestSkipReason` (never as a pass). `it`s in a plain `describe()` call `browserSpecGuard();` first (skip with reason, or Error on a launch failure); a bare `if (this.browserTestSkipped) return;` reads as a pass.
+- **`this.browserLaunchError`** — Playwright installed but the browser could not start (missing system libraries, broken driver): `browserDescribe` reports each spec as an **error** with this message. `WHEELS_BROWSER_SKIP_LAUNCH_FAILURES=true` turns that into a skip. The decision is `$browserSpecGate()`.
+- **CI runs browser tests** — `pr.yml` and `snapshot.yml` install Playwright JARs + Chromium (cached via `browser-manifest.json` hash). Browser specs run as part of the normal test suite. `WHEELS_BROWSER_TEST_BASE_URL=http://localhost:30007` is set automatically. The base URL is resolved at instance time through a layered lookup (`this.baseUrl` → Wheels setting → JVM property `wheels.browserTest.baseUrl` → env var → CGI auto-detect → `http://localhost:8080`); per-spec `this.baseUrl` takes priority over the env var. Set `this.baseUrl` in the component pseudo-constructor (outside any function), not inside `beforeAll()` — `super.beforeAll()` calls `$resolveBaseUrl()` and caches the result, so a `this.baseUrl =` assignment that runs after `super.beforeAll()` is silently ignored.
 - **Isolated application context (#3374)** — `BrowserTest.$startBrowserContext()` sends `X-Wheels-Test-Context` (Playwright `extraHTTPHeaders`) plus a `WHEELS_TEST_CONTEXT` cookie so fixture HTTP binds `<this.name>_wheelsTest`, not the live app. `Application.cfc` must include `vendor/wheels/events/testcontext.cfm` after `config/app.cfm` (ships in `wheels new`). Without that snippet, browser tests still work via the #3373 live-scope swap.
 - **Fixture routes** — `/_browser/login-as` and `/_browser/logout` are mounted automatically in test mode. They must come before `.wildcard()` in routes.cfm. In the Routes UI (`/wheels/routes`) all `/_browser/*` routes appear under the **Internal** tab, not Application. The `/_browser/login-as` handler is configurable: `set(browserLoginAsHandler = "AuthFixture##loginAs")` in `config/settings.cfm` substitutes that `Controller##action` at route-registration time (default is `BrowserTestLogin##create`). Env-gating is handled by `wheels.middleware.BrowserTestFixtureGuard` on the whole `/_browser` scope — custom handlers do not need to re-implement the guard. Empty string or absent setting falls back to the default. (#2830)
 - **Dialogs are Lucee-only** — `acceptDialog`, `dismissDialog`, `dialogMessage` use `createDynamicProxy` which is Lucee-specific. Specs skip gracefully on other engines.

.editorconfig

@@ -16,3 +16,10 @@ indent_style = space
 
 [{index.cfm,rewrite.cfm,root.cfm,wheels/index.cfm}]
 insert_final_newline = false
+
+# Per-request/lifecycle event templates emit zero output: they are $include'd into
+# the response buffer, so a trailing newline after </cfsilent> leaks as whitespace
+# before renderText output and breaks XML. Keep them newline-free (demo app/events
+# and the CLI generator templates). See #3882.
+[**/events/{onabort,onapplicationend,onapplicationstart,onrequestend,onrequeststart,onsessionend,onsessionstart}.cfm]
+insert_final_newline = false

.env

@@ -2,7 +2,3 @@ LUCEE_EXTENSIONS=465E1E35-2425-4F4E-8B3FAB638BD7280A;name=H2;version=1.3.172
 cfconfig_adminPassword=commandbox
 WHEELS_ENV=development
 BASE_URL=http://127.0.0.1:8080
-
-# Consumed by wheels.tests.specs.global.EnvFileParsingSpec: a .env value of
-# numeric 1 must survive parsing as a VALUE, not become the boolean true.
-WHEELS_SPEC_NUMERIC_ONE=1.0

.github/RELEASE_PLAYBOOK.md

@@ -236,6 +236,7 @@ If any pin to `<X.Y.Z`, open issues on those repos to widen the constraint.
 | `release.yml` fails: "CHANGELOG contains TBD" | Forgot to update changelog | Add release date to `# [X.Y.Z]` line, push, re-run workflow |
 | `release.yml` fails: "release-notes range … bleeds into a later version section" | Separator below the target version is `----` (4 dashes), not `---` — the awk extraction overruns into the previous version | Change that separator line to exactly `---`, push, re-run |
 | `release.yml` fails: "version contains -SNAPSHOT" | `wheels.json` has a `-snapshot` suffix on main | Strip the suffix in `wheels.json`, push (release.yml asserts clean main versions) |
+| `release.yml` fails: "Release vX.Y.Z is already published" or "Tag vX.Y.Z already points at …" | `wheels.json` on main still names a released version (e.g. a fix merged to main after the release). A published version's assets never change (#4221) | Bump the version in `wheels.json` (a patch release) and push. If the release is a partial upload from a run that failed mid-upload, delete that release (and its tag, if it points at an older commit) by hand, then re-run |
 | brew tap PR doesn't open after release | `DOWNSTREAM_DISPATCH_TOKEN` expired or unset | Rotate token in repo secrets; re-run `release.yml` workflow_dispatch |
 | develop-bump PR doesn't open after GA | `DOWNSTREAM_DISPATCH_TOKEN` expired/unset, OR the `bump-develop` dispatch step warned and exited 0 | Fire it manually: Actions → "Bump Develop Version" → "Run workflow" → enter the just-released version (e.g. `4.0.0`). The workflow has a `workflow_dispatch` fallback for exactly this case. |
 | `brew install wheels` post-release fails | Formula sha256 mismatch | Re-run the tap bump workflow with `workflow_dispatch` to recompute |

.github/actions/setup-lucli/action.yml

@@ -30,7 +30,7 @@ runs:
         mkdir -p "$install_dir"
         # Installed as plain `lucli`: a versioned file name would be taken
         # for a module alias.
-        curl --fail --location --retry 3 \
+        curl --fail --location --retry 3 --retry-delay 2 --retry-all-errors \
           "https://github.com/${LUCLI_REPO}/releases/download/v${LUCLI_VERSION}/lucli-${LUCLI_VERSION}-${suffix}" \
           --output "$install_dir/lucli"
         if command -v sha256sum >/dev/null 2>&1; then

.github/actions/setup-wheels-test-env/action.yml

@@ -15,7 +15,7 @@ inputs:
   port:
     description: 'Port to bind Lucee to'
     required: false
-    default: '60007'
+    default: '30007'
   install-playwright:
     description: 'Install Playwright + Chromium (set "false" to skip if no browser tests run)'
     required: false
@@ -65,7 +65,7 @@ runs:
           SHA=$(echo "$row" | jq -r '.sha256')
 
           echo "Downloading ${FILE}..."
-          curl -sL "$URL" -o ~/.wheels/browser/lib/"$FILE"
+          curl -sL --retry 3 --retry-delay 2 --retry-all-errors "$URL" -o ~/.wheels/browser/lib/"$FILE"
 
           ACTUAL=$(sha256sum ~/.wheels/browser/lib/"$FILE" | cut -d' ' -f1)
           if [ "$ACTUAL" != "$SHA" ]; then
@@ -81,7 +81,7 @@ runs:
     - name: Download SQLite JDBC driver
       shell: bash
       run: |
-        curl -sL "https://repo1.maven.org/maven2/org/xerial/sqlite-jdbc/3.50.3.0/sqlite-jdbc-3.50.3.0.jar" \
+        curl -sL --retry 3 --retry-delay 2 --retry-all-errors "https://repo1.maven.org/maven2/org/xerial/sqlite-jdbc/3.50.3.0/sqlite-jdbc-3.50.3.0.jar" \
           -o /tmp/sqlite-jdbc.jar
 
     - name: Start Lucee server

.github/scripts/blog-announce-on-publish.sh

@@ -10,8 +10,9 @@
 #      `announcement:` block still lacks a `discussionUrl` (backfill).
 # 2. Run web/scripts/blog-announce-discussion.mjs over the candidates. The
 #    dedupe already lives in that script: before creating a discussion it
-#    searches existing Announcements by exact title and/or the post's blog URL,
-#    and on a hit writes that URL back instead of creating a duplicate.
+#    lists the Announcements category and matches the post's slug marker,
+#    exact title or blog URL, and on a hit writes that URL back instead of
+#    creating a duplicate.
 # 3. If the frontmatter gained a discussionUrl, commit it on
 #    docs/bot-blog-announce-<shortsha> and open a tiny PR to develop (same
 #    pattern as the publish workflow — never push to develop directly).

.github/workflows/ajp-integration.yml

@@ -0,0 +1,42 @@
+name: TestClient works behind an AJP front end
+
+# Optional, manual regression check (#4210): runs the internal TestClient specs through Apache
+# httpd -> mod_proxy_ajp -> Lucee 7's AJP connector, the shape of IIS+BonCode / mod_jk
+# deployments, and asserts they pass. See tools/ci/ajp/run.sh for what the servlet reports there.
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  ajp:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 45
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v5
+
+      - name: Build the Lucee 7 image
+        run: |
+          MAX_ATTEMPTS=3
+          ATTEMPT=1
+          until docker compose build lucee7; do
+            if [ "$ATTEMPT" -ge "$MAX_ATTEMPTS" ]; then
+              echo "::error::docker compose build failed after ${MAX_ATTEMPTS} attempts"
+              exit 1
+            fi
+            ATTEMPT=$((ATTEMPT + 1))
+            sleep 15
+          done
+
+      - name: Run the TestClient specs through httpd and AJP
+        run: AJP_HTTPD_PORT=9590 AJP_RESULT_JSON=ajp-result.json bash tools/ci/ajp/run.sh wheels-ajp
+
+      - name: Upload the result
+        if: always()
+        uses: actions/upload-artifact@v6
+        with:
+          name: ajp-result
+          path: ajp-result.json
+          if-no-files-found: ignore

.github/workflows/blog-announce-on-publish.yml

@@ -11,8 +11,9 @@ name: Blog — Announce on Publish
 # the Discussion already existed but the publish never landed, so the next
 # day's run re-announced and duplicated the thread. Announcing only on
 # push-to-develop means a post is durable before any announcement is made,
-# and the dedupe in web/scripts/blog-announce-discussion.mjs (exact title /
-# blog-URL search before create) is a second line of defence.
+# and the dedupe in web/scripts/blog-announce-discussion.mjs (before create it
+# lists the category and matches the post's slug marker, title or blog URL) is
+# a second line of defence.
 
 on:
   push:
@@ -32,7 +33,7 @@ concurrency:
 jobs:
   announce:
     name: Announce published posts
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     timeout-minutes: 15
     steps:
       - name: Generate App token
@@ -57,6 +58,10 @@ jobs:
         with:
           node-version: 22
 
+      # Fail closed: never announce with a dedupe that doesn't pass its own tests.
+      - name: Test the announcement helper
+        run: node --test web/scripts/blog-announce-discussion.test.mjs
+
       - name: Announce and write back discussion URLs
         env:
           GH_TOKEN: ${{ steps.app-token.outputs.token }}

.github/workflows/blog-publish-scheduled.yml

@@ -27,7 +27,7 @@ concurrency:
 jobs:
   publish:
     name: Publish posts scheduled for today
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     timeout-minutes: 10
     steps:
       - name: Generate App token