Merge pull request #2769 from wheels-dev/release/v4.0.1-to-main

Release 4.0.1 — merge develop into main

Author: bpamiri

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

@@ -0,0 +1,92 @@
+# Deploy Reference
+
+`wheels deploy` ships a Dockerized Wheels app to production Linux servers via SSH. Ported from Basecamp Kamal's developer CLI — same `config/deploy.yml` schema, same on-server conventions (container names, labels, network, lock path), invokes the same `kamal-proxy` Go binary for zero-downtime rollover. No Ruby runtime required.
+
+## Commands
+
+```
+wheels deploy init                     # scaffold config/deploy.yml + .kamal/secrets
+wheels deploy setup                    # one-time server bootstrap + first deploy
+wheels deploy                          # rolling deploy
+wheels deploy --dry-run                # print commands without executing
+wheels deploy rollback v1              # roll back to a previous version
+wheels deploy config                   # print resolved config as YAML
+wheels deploy version                  # show Kamal version this port mirrors
+```
+
+## Subcommands
+
+```
+wheels deploy app <verb>         # boot/start/stop/details/containers/images/logs/live/maintenance/remove
+wheels deploy proxy <verb>       # boot/reboot/start/stop/restart/details/logs/remove
+wheels deploy accessory <verb>   # boot/reboot/start/stop/restart/details/logs/remove (sidecars: db/redis/search)
+wheels deploy build <verb>       # deliver/push/pull/create/remove/details/dev
+wheels deploy registry <verb>    # setup/login/logout/remove
+wheels deploy bootstrap          # install Docker on every host (flat alias — preferred)
+wheels deploy exec "<cmd>"       # run a command on every host (flat alias — preferred)
+wheels deploy server <verb>      # exec/bootstrap (legacy nested form — see #2677)
+wheels deploy prune <verb>       # all/images/containers [--keep=N]
+wheels deploy lock <verb>        # acquire/release/status (manual — normal deploys auto-lock)
+wheels deploy fetch-secrets ...  # resolve KEY=VALUE lines from an adapter (flat alias — preferred)
+wheels deploy extract-secrets    # pull one key from a KEY=VALUE block (flat alias — preferred)
+wheels deploy print-secrets      # print resolved .kamal/secrets (flat alias — preferred)
+wheels deploy secrets <verb>     # fetch/extract/print (legacy nested form — see #2697)
+wheels deploy audit              # tail /tmp/kamal-audit.log on each server
+wheels deploy details            # aggregate app + proxy + accessory status
+wheels deploy remove --confirm   # teardown all app/proxy/accessory containers
+wheels deploy docs [section]     # in-terminal config reference
+```
+
+## On-server parity contract (byte-compatible with Ruby Kamal)
+
+- Container names: `<service>-<role>-<version>`
+- Labels: `service=`, `role=`, `destination=`, `version=`
+- Docker network: `kamal`
+- Lock file: `/tmp/kamal_deploy_lock_<service>`
+- Proxy config: `/home/<user>/.config/kamal-proxy/`
+- Hook env prefix: `KAMAL_*` (never `WHEELS_*` — user hooks migrate unchanged)
+
+A server managed by Ruby Kamal can be taken over by `wheels deploy` without cleanup.
+
+## Architecture
+
+```
+cli/lucli/services/deploy/
+├── cli/*.cfc             DeployMainCli + Deploy<App|Proxy|Accessory|Build|Registry|Server|Prune|Lock|Secrets>Cli
+├── commands/*.cfc        Base + Docker/App/Proxy/Builder/Registry/Auditor/Lock/Hook/Accessory/PruneCommands
+├── config/*.cfc          Config + Role/Env/Builder/Proxy/Registry/Ssh/Accessory/Validator/ConfigLoader
+├── lib/*.cfc             JarLoader/Mustache/Yaml/SshClient/SshPool/FakeSshPool/Output/SecretResolver
+└── secrets/*.cfc         BaseAdapter + OnePassword/Bitwarden/AwsSecrets/LastPass/Doppler adapters
+
+cli/lucli/lib/deploy/*.jar  jmustache, snakeyaml, sshj + BouncyCastle transitives (URLClassLoader-isolated)
+cli/lucli/templates/deploy/ Mustache templates for `wheels deploy init` output
+```
+
+Commands-are-strings invariant: every `*Commands.cfc` method returns a shell-command string; only `*Cli.cfc` and the orchestrator execute them. That's why `--dry-run` is trivial and unit tests run without network.
+
+## Critical gotchas
+
+1. **Kamal-compatible schema, ONE divergence.** ERB in `deploy.yml` is NOT supported (rendering it would require embedding a Ruby runtime). Kamal's native `${VAR}` env-var interpolation is preserved unchanged — uppercase-snake tokens resolve via `envOverride → .kamal/secrets → System.getenv → ""` (see `ConfigLoader.$interpolate`). Mustache (`{{...}}`) is used only by `wheels deploy init` to scaffold a fresh `deploy.yml`/`secrets`; it is NOT applied to `deploy.yml` at runtime. Everything else in `config/deploy.yml` is byte-identical to Kamal 2.4.0.
+2. **Hook env prefix is `KAMAL_`, not `WHEELS_`.** Deliberate — Ruby Kamal users' existing `.kamal/hooks/` scripts work unchanged.
+3. **`app live` / `app maintenance` use a marker file** (`/tmp/kamal-maintenance-<svc>`) rather than kamal-proxy native maintenance mode. Phase 2 simplification; Phase 3 follow-up will align with Kamal's proxy-native semantics.
+4. **`wheels deploy remove` is destructive and requires `--confirm`.** Bare `wheels deploy remove` throws without touching anything.
+5. **Lucee reserved scope names in subagent-authored deploy code.** `client`, `session`, `application` — use `ssh`/`sc`, `sess`, `app` instead. Bit us multiple times during the port.
+6. **No `--dry-run` flag in Ruby Kamal 2.4.0.** The `tools/deploy-config-diff.sh` harness compares config-layer output only. Byte-identical command-string parity is aspirational; see `tools/deploy-dry-run-diff.sh` for the plan.
+7. **`wheels deploy server <verb>` collides with LuCLI's top-level `server` command.** LuCLI (the picocli runtime under the wheels brand) registers `server` for Lucee dev-server lifecycle, so picocli grabs the `server` token before it can reach the deploy dispatcher. The wheels module exposes flat aliases `wheels deploy bootstrap` and `wheels deploy exec` that sidestep the collision — these are the canonical CLI form. The nested `server <verb>` branch is retained in `Module.cfc::deploy()` for MCP/programmatic callers. See [#2677](https://github.com/wheels-dev/wheels/issues/2677).
+8. **`wheels deploy secrets <verb>` collides with LuCLI's top-level `secrets` command.** Same shape as #2677 — LuCLI registers `secrets` for its own credential store (init/set/list/rm/get/provider). The wheels module exposes flat aliases `wheels deploy fetch-secrets`, `wheels deploy extract-secrets`, and `wheels deploy print-secrets` that sidestep the collision — these are the canonical CLI form. The nested `secrets <verb>` branch is retained for MCP/programmatic callers. See [#2697](https://github.com/wheels-dev/wheels/issues/2697).
+
+## Testing
+
+`cli/lucli/tests/specs/deploy/` extends `wheels.wheelstest.system.BaseSpec`. Run with:
+
+    bash tools/test-cli-local.sh
+
+Fixtures at `cli/lucli/tests/_fixtures/deploy/configs/` (`minimal.yml`, `full.yml`, `with-accessories.yml`, `invalid/*.yml`). `FakeSshPool.cfc` records every command for offline assertions; no sshd needed for unit tests. `SshClientSpec` + `SshPoolSpec` exercise real SSH via the fixture at `cli/lucli/tests/_fixtures/deploy/sshd/` (brought up by `tools/deploy-sshd-up.sh`).
+
+## 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)
+- In-source CLI docs: `cli/lucli/services/deploy/cli/docs/` (per-verb)
+- Design spec: [docs/superpowers/specs/2026-04-20-wheels-deploy-kamal-port-design.md](../../docs/superpowers/specs/2026-04-20-wheels-deploy-kamal-port-design.md)
+- Implementation plan: [docs/superpowers/plans/2026-04-20-wheels-deploy-kamal-port.md](../../docs/superpowers/plans/2026-04-20-wheels-deploy-kamal-port.md)
+- Retrospective: [docs/superpowers/plans/2026-04-21-phase1-retrospective.md](../../docs/superpowers/plans/2026-04-21-phase1-retrospective.md)

.ai/wheels/deploy.md

@@ -0,0 +1,68 @@
+# Browser Testing
+
+Shipped in v4.0 across PRs #2113, #2115, #2116. Specs extend `wheels.wheelstest.BrowserTest` and drive a real Chromium through `this.browser` — a fluent DSL wrapping Playwright Java.
+
+## Example
+
+```cfm
+// vendor/wheels/tests/specs/browser/LoginBrowserSpec.cfc
+component extends="wheels.wheelstest.BrowserTest" {
+
+    this.browserEngine = "chromium";   // chromium only in PR 1
+
+    function run() {
+        // browserDescribe() wraps describe() with beforeEach/afterEach that
+        // create a fresh Page per `it`. WheelsTest's BDD lifecycle only treats
+        // beforeAll/afterAll as class-level, so we register per-it hooks
+        // 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");
+            });
+        });
+    }
+}
+```
+
+## Installation
+
+Install Playwright locally before first run (~370MB download: JARs + Chromium):
+
+```bash
+wheels browser setup              # downloads JARs + Chromium
+```
+
+Then run browser specs via the normal test suite:
+
+```bash
+bash tools/test-local.sh                    # skips browser specs if JARs missing
+```
+
+## Implemented DSL methods
+
+- **Navigation:** visit, visitUrl, back, forward, refresh, visitRoute
+- **Interaction:** click, press, fill, type, clear, select, check, uncheck, attach, dragAndDrop
+- **Keyboard:** keys, pressEnter, pressTab, pressEscape
+- **Waiting:** waitFor, waitForText, waitForUrl
+- **Scoping:** within(selector, callback)
+- **Cookies:** setCookie, deleteCookie, cookie, clearCookies
+- **Auth:** loginAs, logout
+- **Dialogs:** acceptDialog, dismissDialog, dialogMessage (Lucee-only via createDynamicProxy)
+- **Viewport:** resize, resizeToMobile, resizeToTablet, resizeToDesktop
+- **Script:** script (returns `page.evaluate` result), pause
+- **Assertions (text/vis/presence):** assertSee, assertDontSee, assertSeeIn, assertVisible, assertMissing, assertPresent, assertNotPresent
+- **Assertions (URL/title/query):** assertUrlIs, assertUrlContains, assertTitleContains, assertQueryStringHas, assertQueryStringMissing, assertRouteIs
+- **Assertions (form):** assertInputValue, assertChecked, assertHasClass
+- **Terminals:** currentUrl, title, pageSource, text, value, screenshot
+
+## Key gotchas
+
+- **`##` 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.
+- **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.
+- **Dialogs are Lucee-only** — `acceptDialog`, `dismissDialog`, `dialogMessage` use `createDynamicProxy` which is Lucee-specific. Specs skip gracefully on other engines.

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

@@ -0,0 +1,34 @@
+# Wheels Bot
+
+`wheels-bot[bot]` is a custom GitHub App that runs Claude-powered automation on issues and PRs in `wheels-dev/wheels`. Five stages, all opt-out via the `[skip-claude]` label or repo variable `WHEELS_BOT_ENABLED=false`. Slash-command prompts live in `.claude/commands/`; workflows in `.github/workflows/bot-*.yml`. Full user-facing docs: [`docs/contributing/wheels-bot.md`](../../docs/contributing/wheels-bot.md).
+
+## Stages
+
+| Stage | Trigger | Model | Output |
+|---|---|---|---|
+| Triage | issue opened/reopened | Opus | Comment classifying as `bug` / `framework-design` / `other` (+ confidence on `bug` path). Reads code with the allowlisted tools to resolve uncertainty before rating. |
+| Research | bot triage emits `framework-design` marker | Opus | Comment comparing Rails / Laravel / Django / Phoenix / Spring Boot / +1 and recommending a Wheels-idiomatic path (+ confidence). |
+| Propose Fix | bot triage emits `triage-confidence:high\|medium` OR research emits `research-confidence:high\|medium` (or `workflow_dispatch`) | Opus | TDD-mandatory draft PR on branch `fix/bot-<issue>-<slug>`. Spec-then-implementation, both required by `bot-tdd-gate.yml`. |
+| Reviewer A | PR opened / synchronized / ready_for_review | Sonnet | Single PR review with line comments, verdict, and `wheels-bot:review-a:<pr>:<sha>` marker. |
+| Reviewer B | Reviewer A submits a review | Sonnet | PR comment critiquing A for sycophancy, false positives, and missed issues. Loop cap = 3 rounds. |
+
+## Marker conventions (HTML comments, used for idempotency)
+
+- `<!-- wheels-bot:triage:<issue> -->` + `<!-- wheels-bot:triage-class:<bug|framework-design|other> -->` (+ optional `<!-- wheels-bot:triage-confidence:high|medium -->` — either fires propose-fix; low omitted)
+- `<!-- wheels-bot:research:<issue> -->` (+ optional `<!-- wheels-bot:research-confidence:high|medium -->` — either fires propose-fix; low omitted)
+- `<!-- wheels-bot:fix:<issue> -->` / `<!-- wheels-bot:fix-held:<issue> -->`
+- `<!-- wheels-bot:review-a:<pr>:<sha> -->`
+- `<!-- wheels-bot:review-b:<pr>:<sha>:<round> -->`
+- `<!-- wheels-bot:auto-close:<issue> -->`
+
+## Allow-listed scopes per stage
+
+Every bot-authored commit must conform to the `commitlint.config.js` allowlist (see CLAUDE.md § Commit Message Conventions). The bot's prompt (`.claude/commands/_shared-rails.md`) re-states the allowlist verbatim.
+
+## Kill switch
+
+Flip the repo variable `WHEELS_BOT_ENABLED` to `false` to halt every bot workflow without code changes. Add the `[skip-claude]` label (or `[skip-claude]` in the title) to halt activity on a single issue/PR.
+
+## Auto-fire safety net
+
+The bot is permitted to chain stages (triage → research → propose-fix), and handoff fires on `*-confidence:high` OR `*-confidence:medium`. Low stays manual. Sensitive areas (security, middleware, migrations, deploy, DI, cross-engine) are caught by the propose-fix prompt's own step-4 safety net, which posts a `fix-held` marker instead of opening a PR. Reviewer A and B then critique whatever propose-fix produces, escalating to the Senior Advisor on deadlock. All bot PRs land as `--draft` and require a human approving review on `develop`.

.ai/wheels/wheels-bot.md

@@ -166,7 +166,13 @@ Read `.claude/commands/_shared-rails.md` first. Highlights for this command:
 
    Where `<CONFIDENCE_MARKER>` is:
    - `<!-- wheels-bot:research-confidence:high -->` if confidence is high
-   - omitted otherwise
+   - `<!-- wheels-bot:research-confidence:medium -->` if confidence is medium
+   - omitted if confidence is low
+
+   Both `high` and `medium` markers trigger auto-fire of
+   `bot-propose-fix.yml`. Low stays manual — material framework
+   disagreement or new-infrastructure proposals warrant a human discussion
+   before any code is written.
 
 7. **Self-check before posting.**
    - Have you cited at least one URL per framework?

.claude/commands/research-frameworks.md

@@ -102,15 +102,18 @@ below. Highlights for this command:
      existing structure under
      `web/sites/guides/src/content/docs/v4-0-0-snapshot/`, the work is
      mostly translation-of-code (not requiring deep design decisions).
-     High-confidence docs-requests trigger the auto-fire write-docs
-     workflow.
    - **`medium`**: the gap is real but the right page/path is ambiguous,
      OR a new top-level section is needed (a structural design decision),
      OR the docs require significant code investigation to write
      accurately.
    - **`low`**: the gap is vague, the scope is large (e.g. "rewrite the X
      chapter"), or it's not clear what concretely needs to exist.
 
+   **Auto-fire threshold:** both `high` and `medium` docs-requests trigger
+   the auto-fire write-docs workflow. Write-docs has its own safety net
+   for structural docs-architecture decisions (posts a `docs-held` marker
+   instead of opening a PR). Only `low` stays manual.
+
    Post the triage comment:
 
    ```
@@ -133,8 +136,11 @@ below. Highlights for this command:
 
    Where `<CONFIDENCE_MARKER>` is:
    - `<!-- wheels-bot:docs-confidence:high -->` if confidence is high
-     (triggers auto-fire of `bot-write-docs.yml`)
-   - omitted otherwise (medium/low confidence does not auto-trigger)
+   - `<!-- wheels-bot:docs-confidence:medium -->` if confidence is medium
+   - omitted if confidence is low (low does not auto-trigger)
+
+   Both `high` and `medium` markers trigger auto-fire of
+   `bot-write-docs.yml`.
 
    Then exit.
 
@@ -155,16 +161,25 @@ below. Highlights for this command:
 
    - **`high`**: the report has a clear "what happened / what I expected"
      description; the suspected layer is unambiguous; the fix sketch is
-     mechanical (one file, no design decisions). High-confidence bugs
-     trigger the auto-fire fix-PR workflow.
+     mechanical (one file, no design decisions).
    - **`medium`**: the report is clear but the fix has design trade-offs,
      OR cross-engine concerns may exist, OR more than one layer is
      plausibly involved.
    - **`low`**: the report is ambiguous; reproduction steps are vague;
      environment-specific symptoms are suspected; the fix shape isn't
      obvious from the issue body alone.
 
-   **Auto-downgrade rules** (force at least one level lower):
+   **Auto-fire threshold:** both `high` and `medium` bugs trigger the
+   auto-fire propose-fix workflow. Propose-fix has its own step-4 safety
+   net for sensitive areas (security / middleware / migrations / deploy /
+   DI / cross-engine) — it posts a `fix-held` marker instead of opening a
+   PR. Reviewer A and B will critique whatever propose-fix produces. Only
+   `low` stays manual.
+
+   **Auto-downgrade rules** (force at least one level lower — these
+   downgrades are still informative for humans skimming the comment;
+   `medium` ratings still auto-fire, but propose-fix's safety net will
+   catch the sensitive-area cases):
    - The fix would touch `vendor/wheels/security/**`, auth flows, or any
      `vendor/wheels/middleware/**` → at most `medium`
    - Cross-engine concern detected (Lucee vs Adobe vs BoxLang behavior
@@ -199,7 +214,11 @@ below. Highlights for this command:
 
    Where `<CONFIDENCE_MARKER>` is:
    - `<!-- wheels-bot:triage-confidence:high -->` if confidence is high
-   - omitted otherwise (medium/low confidence does not auto-trigger fix-PR)
+   - `<!-- wheels-bot:triage-confidence:medium -->` if confidence is medium
+   - omitted if confidence is low (low does not auto-trigger fix-PR)
+
+   Both `high` and `medium` markers trigger auto-fire of
+   `bot-propose-fix.yml`.
 
 8. **Self-check before posting.**
    - Is the classification justified by quoted text from the issue?