Release 4.0.6

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

@@ -36,6 +36,38 @@ plugin.onPluginLoad(context);
 
 **Why**: Adobe's application scope is implemented differently from a regular CFML struct. Function members get lost or throw errors during serialization.
 
+### Application Scope Unreliable During onApplicationEnd() Teardown (Adobe CF 2023)
+
+On Adobe CF 2023, `onApplicationEnd()` fires synchronously during `applicationStop()` teardown (triggered by a `?reload` restart or idle-timeout reclaim). Inside that teardown the live `application` scope is no longer reliable — bare `application.wo` can resolve against a stale/torn-down scope and land on a Java `String[]`, throwing `Element wo is undefined in a Java object of type class [Ljava.lang.String;` and erroring the whole site until a CF service restart.
+
+The only dependable reference at shutdown is the passed-in `arguments.applicationScope` (already used by the `$wheelsBrowserLauncher` cleanup in the same handler). Route all `onApplicationEnd()` calls through it and guard with `StructKeyExists` so a partially reclaimed scope degrades to a no-op instead of a hard error. Lucee 6/7 and BoxLang are unaffected; this only manifests on Adobe CF during real teardown (issue #3379).
+
+```cfm
+// WRONG — bare application.wo breaks during Adobe CF applicationStop() teardown
+public void function onApplicationEnd(struct ApplicationScope) {
+    application.wo.$include(
+        template = "../../#arguments.applicationScope.wheels.eventPath#/onapplicationend.cfm",
+        argumentCollection = arguments
+    );
+}
+
+// RIGHT — use the passed-in scope, the only reliable reference at shutdown
+public void function onApplicationEnd(struct ApplicationScope) {
+    if (
+        StructKeyExists(arguments.applicationScope, "wo")
+        && StructKeyExists(arguments.applicationScope, "wheels")
+        && StructKeyExists(arguments.applicationScope.wheels, "eventPath")
+    ) {
+        arguments.applicationScope.wo.$include(
+            template = "../../#arguments.applicationScope.wheels.eventPath#/onapplicationend.cfm",
+            argumentCollection = arguments
+        );
+    }
+}
+```
+
+**Existing apps**: apply this same change to `public/Application.cfc` — the CLI template (`wheels new`) and the demo app were fixed in Wheels 4.x (#3380).
+
 ### Closure `this` Captures Declaring Scope
 
 CFML closures bind `this` to the component where they are DEFINED, not where they are ASSIGNED. This trips up test code that dynamically adds methods.
@@ -347,6 +379,42 @@ public void function $myTagWrapper() {
 
 **Reference fix**: [#2756](https://github.com/wheels-dev/wheels/pull/2756) — adds `$responseCommitted()` and applies the defensive shape to `$header()` and `$content()`.
 
+### A Parameter Named `request` Makes the Bare `request` Token Ambiguous (Adobe CF 2025)
+
+In a function that declares a parameter named `request`, Adobe CF 2025 does **not** resolve the bare `request` token consistently across expression positions. Passed as a function argument it can resolve to the built-in `request` scope, while a `request.x` member-access expression in the same function resolves to `arguments.request`. A guard written in one position therefore cannot protect an access written in the other — the guard passes and the access throws.
+
+```cfm
+public string function handle(required struct request, required any next) {
+
+    // WRONG — the two `request` tokens can resolve to different things on Adobe 2025.
+    // StructKeyExists sees the key on the built-in scope and returns true; the
+    // member-access expression then resolves to arguments.request, which has no
+    // `wheels` key, and throws `Element WHEELS is undefined in REQUEST`.
+    if (StructKeyExists(request, "wheels")) {
+        StructDelete(request.wheels, "tenant");
+    }
+
+    // RIGHT (a) — IsDefined string-resolves the whole dotted path in a single
+    // evaluation, so the guard and the access cannot disagree.
+    if (IsDefined("request.wheels.tenant")) {
+        StructDelete(request.wheels, "tenant");
+    }
+
+    // RIGHT (b) — assign before use, so the key exists on that path regardless
+    // of how the token resolved.
+    if (!StructKeyExists(request, "wheels")) {
+        request.wheels = {};
+    }
+    request.wheels.tenant = local.tenant;
+}
+```
+
+**Why**: `wheels.middleware.MiddlewareInterface` fixes the signature `handle(required struct request, required any next)`, so *every* middleware component has a parameter named `request` and is exposed to this. Lucee 6/7, BoxLang and Adobe CF 2023 all resolve the bare token to the built-in scope in both positions, so **a green local Lucee run and green Adobe 2023 smokes do NOT cover this** — only the Adobe 2025 matrix legs catch it.
+
+Note the interaction with anti-pattern 11 (reserved scope names shadowing parameters): that entry says never *name* a parameter after a reserved scope. Middleware can't follow that rule — the interface mandates it — so middleware must instead follow the two safe patterns above and never mix them with a bare-token guard.
+
+**Reference fix**: [#3338](https://github.com/wheels-dev/wheels/pull/3338) — the tenant-context hardening for [#3336](https://github.com/wheels-dev/wheels/issues/3336) added a `StructKeyExists(request, "wheels")` guard to `TenantResolver.handle()`; it errored on all five Adobe 2025 database legs (8 specs each) while every other engine stayed green, and was switched to the `IsDefined()` form already used by the same function's `finally` block.
+
 ## Database-Specific Gotchas
 
 ### H2 Database (Test Default)

.ai/wheels/snippets/model-snippets.md

@@ -151,10 +151,17 @@ function recent(days=30) {
 ## Calculated Properties
 ```cfm
 function config() {
-    // SQL-based calculated property
+    // SQL-based calculated property — included in every SELECT by default
     property(name="orderTotal", sql="(SELECT SUM(amount) FROM order_items WHERE order_id = orders.id)");
+
+    // Keep off the hot path with select=false; opt in per-call with includeCalculated
+    property(name="fullName", sql="firstName || ' ' || lastName", select=false);
 }
 
+// Opt a select=false property back into one finder (additive — base columns still selected)
+user = model("User").findOne(includeCalculated="fullName");
+order = model("Order").findAll(includeCalculated="orderTotal,shippingCost");
+
 // Method-based calculated property
 function displayName() {
     if (Len(this.nickName)) {

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

@@ -65,5 +65,6 @@ bash tools/test-local.sh                    # skips browser specs if JARs missin
 - **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.
+- **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.

.claude/workflows/triage-discussions.js

@@ -0,0 +1,179 @@
+export const meta = {
+  name: 'triage-discussions',
+  description: 'Fetch recent GitHub Discussions, triage each thread, and adversarially verify which ones actually need a code fix, doc update, or new issue',
+  whenToUse: 'Periodic (e.g. monthly) sweep of community GitHub Discussions to surface genuinely actionable items — without filing duplicates or acting on reports that are already fixed/answered. Read-only: produces a verified findings report, posts nothing.',
+  phases: [
+    { title: 'Fetch', detail: 'pull + filter recent discussions (drop Announcements and bot reports)' },
+    { title: 'Triage', detail: 'read each discussion thread, classify, propose action', model: 'sonnet' },
+    { title: 'Verify', detail: 'adversarially check each proposed action against current code + open issues' },
+  ],
+}
+
+// ---------------------------------------------------------------------------
+// args (all optional). Accepts an object, a JSON string, or a bare date string:
+//   { repo: "owner/name", since: "YYYY-MM-DD", max: 40 }
+//   "2026-01-01"   -> treated as { since }
+// Defaults: repo=wheels-dev/wheels, since=2025-01-01, max=40
+// ---------------------------------------------------------------------------
+const opts = (() => {
+  if (args == null) return {}
+  if (typeof args === 'string') {
+    const s = args.trim()
+    if (s.startsWith('{')) { try { return JSON.parse(s) } catch (e) { return {} } }
+    return s ? { since: s } : {}
+  }
+  return args
+})()
+const REPO = opts.repo || 'wheels-dev/wheels'
+const SINCE = opts.since || '2025-01-01'
+const MAX = opts.max || 40
+const [OWNER, NAME] = REPO.split('/')
+
+const CANDIDATES_SCHEMA = {
+  type: 'object',
+  additionalProperties: false,
+  properties: {
+    candidates: {
+      type: 'array',
+      items: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          number: { type: 'integer' },
+          title: { type: 'string' },
+          category: { type: 'string' },
+          comments: { type: 'integer' },
+          isAnswered: { type: 'boolean' },
+          updatedAt: { type: 'string' },
+          author: { type: 'string' },
+        },
+        required: ['number', 'title', 'category', 'comments', 'isAnswered', 'updatedAt', 'author'],
+      },
+    },
+  },
+  required: ['candidates'],
+}
+
+const TRIAGE_SCHEMA = {
+  type: 'object',
+  additionalProperties: false,
+  properties: {
+    number: { type: 'integer' },
+    classification: { type: 'string', enum: ['bug', 'feature-idea', 'doc-gap', 'question-unanswered', 'question-answered', 'onboarding-friction', 'infra', 'noise'] },
+    summary: { type: 'string' },
+    resolvedInThread: { type: 'boolean' },
+    proposedAction: { type: 'string', enum: ['code-fix', 'doc-update', 'file-issue', 'reply', 'close-stale', 'none'] },
+    actionDetail: { type: 'string' },
+    severity: { type: 'string', enum: ['high', 'medium', 'low'] },
+    needsVerification: { type: 'boolean' },
+  },
+  required: ['number', 'classification', 'summary', 'resolvedInThread', 'proposedAction', 'actionDetail', 'severity', 'needsVerification'],
+}
+
+const VERDICT_SCHEMA = {
+  type: 'object',
+  additionalProperties: false,
+  properties: {
+    number: { type: 'integer' },
+    verdict: { type: 'string', enum: ['confirmed-needs-action', 'already-fixed', 'already-tracked', 'wont-act', 'insufficient-evidence'] },
+    evidence: { type: 'string' },
+    existingIssue: { type: 'string' },
+    recommendedAction: { type: 'string' },
+    confidence: { type: 'string', enum: ['high', 'medium', 'low'] },
+  },
+  required: ['number', 'verdict', 'evidence', 'existingIssue', 'recommendedAction', 'confidence'],
+}
+
+function fetchCmd(num) {
+  return `gh api graphql -f query='query($num: Int!) { repository(owner:"${OWNER}", name:"${NAME}") { discussion(number:$num) { title url createdAt updatedAt category{name} answer{ body author{login} } body comments(first:50){ nodes{ author{login} createdAt body replies(first:20){ nodes{ author{login} body } } } } } } }' -F num=${num}`
+}
+
+const fetchPrompt = [
+  `Build the candidate list of GitHub Discussions to triage for repo ${REPO}.`,
+  ``,
+  `Run this in Bash (the API returns the 100 most-recently-updated; that is enough for a recency sweep):`,
+  `gh api graphql -f query='query { repository(owner:"${OWNER}", name:"${NAME}") { discussions(first:100, orderBy:{field:UPDATED_AT, direction:DESC}) { nodes { number title url createdAt updatedAt isAnswered category{name} comments{totalCount} author{login} } } } }'`,
+  ``,
+  `Filter the nodes:`,
+  `- EXCLUDE category == "Announcements" (maintainer marketing / release posts — not actionable).`,
+  `- EXCLUDE author login "github-actions" (automated monthly metrics reports).`,
+  `- KEEP only discussions whose updatedAt >= ${SINCE}.`,
+  `Sort the kept set by updatedAt descending and return at most ${MAX}.`,
+  ``,
+  `For each kept discussion emit: number, title, category (name), comments (the comments.totalCount integer), isAnswered (use false when the GraphQL value is null), updatedAt (date only, "YYYY-MM-DD"), author (login).`,
+  `Return ONLY the structured object {candidates: [...]}.`,
+].join('\n')
+
+function triagePrompt(c) {
+  return [
+    `You are triaging a GitHub Discussion in the Wheels CFML framework repo (${REPO}). Wheels is on the develop branch; many older threads reference 3.x.`,
+    `Discussion #${c.number}: "${c.title}" — category=${c.category}, comments=${c.comments}, updated=${c.updatedAt}, author=${c.author}.`,
+    ``,
+    `STEP 1 — Read the FULL thread. Run this in Bash:`,
+    fetchCmd(c.number),
+    ``,
+    `STEP 2 — Understand what the user reports or asks, and whether the thread already resolved it (accepted answer, "thanks that worked", maintainer fix linked, etc).`,
+    ``,
+    `STEP 3 — Classify and decide whether the maintainer needs to DO something NOW.`,
+    `- classification: bug | feature-idea | doc-gap | question-unanswered | question-answered | onboarding-friction | infra | noise`,
+    `- proposedAction: code-fix | doc-update | file-issue | reply | close-stale | none`,
+    `- needsVerification: TRUE when the proposed action depends on the current state of the codebase or on whether an issue already exists (any code-fix / file-issue / doc-update claim a downstream verifier must confirm against HEAD). FALSE for pure social replies, clear no-ops, or answered questions that revealed nothing latent.`,
+    ``,
+    `Be conservative: an answered Q&A with an accepted answer usually needs no action UNLESS it exposes a real doc gap or a latent bug. A "broken"/"doesn't work" title is a CLAIM, not a confirmed bug — flag it for verification rather than asserting it.`,
+    `summary: 1-2 sentences. actionDetail: the concrete next step (or "none"). severity: high|medium|low (impact on users).`,
+    `Return ONLY the structured object.`,
+  ].join('\n')
+}
+
+function verifyPrompt(t, c) {
+  return [
+    `You are an ADVERSARIAL verifier for the Wheels CFML framework (${REPO}); working tree is the develop branch. DEFAULT TO SKEPTICAL — assume the proposed action is unnecessary until evidence proves otherwise.`,
+    `A triage agent reviewed Discussion #${c.number} ("${c.title}") and proposed: ${t.proposedAction} — "${t.actionDetail}" (classification: ${t.classification}, severity: ${t.severity}).`,
+    `Thread summary: ${t.summary}`,
+    ``,
+    `Verify against reality, citing evidence:`,
+    `1. ALREADY FIXED? Search the codebase (Grep/Glob/Read) and recent history (git log --oneline -40). The reported behavior may already be patched. Re-read the thread if useful: ${fetchCmd(c.number)}`,
+    `2. ALREADY TRACKED? Run: gh issue list --repo ${REPO} --state all --search "<relevant keywords>" --limit 15  (try a couple of keyword sets).`,
+    `3. Only if it is a REAL, untracked, unfixed problem -> confirmed-needs-action.`,
+    ``,
+    `verdict: confirmed-needs-action | already-fixed | already-tracked | wont-act | insufficient-evidence`,
+    `evidence: cite a file:line, commit SHA, or issue number that justifies the verdict (be specific). existingIssue: issue number if already-tracked, else "".`,
+    `recommendedAction: the crisp final recommendation for the maintainer. confidence: high|medium|low.`,
+    `READ-ONLY: do NOT post anything to GitHub, do NOT edit files. Return ONLY the structured object.`,
+  ].join('\n')
+}
+
+phase('Fetch')
+const fetched = await agent(fetchPrompt, { label: 'fetch-discussions', phase: 'Fetch', schema: CANDIDATES_SCHEMA, effort: 'low' })
+const candidates = (fetched && fetched.candidates) || []
+log(`Fetched ${candidates.length} candidate discussions (updated since ${SINCE}, excluding Announcements + bots).`)
+if (!candidates.length) return { reviewed: 0, confirmedCount: 0, findings: [] }
+
+phase('Triage')
+const results = await pipeline(
+  candidates,
+  (c) => agent(triagePrompt(c), { label: `triage:#${c.number}`, phase: 'Triage', schema: TRIAGE_SCHEMA, model: 'sonnet', effort: 'medium' }),
+  (t, c) => {
+    if (!t) return { number: c.number, candidate: c, triage: null, verdict: null }
+    const actionable = t.needsVerification && t.proposedAction !== 'none' && t.classification !== 'noise'
+    if (!actionable) {
+      return {
+        number: c.number, candidate: c, triage: t,
+        verdict: {
+          number: c.number, verdict: 'wont-act',
+          evidence: 'triage: no codebase/issue verification needed',
+          existingIssue: '',
+          recommendedAction: t.proposedAction === 'none' ? 'No action needed' : t.actionDetail,
+          confidence: 'medium', skippedVerify: true,
+        },
+      }
+    }
+    return agent(verifyPrompt(t, c), { label: `verify:#${c.number}`, phase: 'Verify', effort: 'high', schema: VERDICT_SCHEMA })
+      .then(v => ({ number: c.number, candidate: c, triage: t, verdict: v }))
+  }
+)
+
+const findings = results.filter(Boolean)
+const confirmed = findings.filter(f => f.verdict && f.verdict.verdict === 'confirmed-needs-action')
+log(`Done: ${findings.length} reviewed, ${confirmed.length} confirmed as needing action.`)
+return { reviewed: candidates.length, confirmedCount: confirmed.length, findings }

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

@@ -19,7 +19,7 @@ inputs:
   lucli-version:
     description: 'LuCLI release version'
     required: false
-    default: '0.3.7'
+    default: '0.6.1'
   install-playwright:
     description: 'Install Playwright + Chromium (set "false" to skip if no browser tests run)'
     required: false