Skip to content

fix(cli): make wheels packages install a real alias for add in dispatch - #2786

Merged
bpamiri merged 5 commits into
developfrom
fix/bot-2785-wheels-packages-install-still-no-ops-in-cli-4-0-1
May 22, 2026
Merged

bpamiri merged 5 commits into
developfrom
fix/bot-2785-wheels-packages-install-still-no-ops-in-cli-4-0-1

Conversation

@wheels-bot

@wheels-bot wheels-bot Bot commented May 21, 2026

Copy link
Copy Markdown
Contributor

Summary

The case "install": branch in cli/lucli/Module.cfc::packages() previously printed a warning to stdout and returned "" instead of installing — a dead-code "redirect" that the prior fix (#2729) acknowledged was unreachable from the shell because LuCLI's built-in extension installer intercepts the literal install verb upstream of module dispatch. But that intercept only fires on the user-facing CLI path. Every other caller that reaches Module.cfc — the stdio MCP server (wheels mcp wheels), scripted in-process clients, and the bundle's own spec suite — was silently no-op'd for install <name> even though PackagesMainCli.install() itself has been a transparent alias for add() since #2729. The dispatch layer was the only place where the alias broke.

This change makes case "install": fall through to case "add": so both verbs share a single validation, error, and install path. The shell-facing form is still intercepted by LuCLI and remains broken on that path (documented in the module-owned --help text); this PR only fixes the paths LuCLI does NOT intercept.

The "release-side" half of the triage's recommendation — cutting a new tagged release that ships the develop-branch help text to Homebrew bottle users on 4.0.1 — is a release-process action, not a code change, and is left for human follow-up.

Fixes #2785

Related Issue

Closes #2785

Type of Change

  • Bug fix
  • New feature
  • Enhancement to existing feature
  • Documentation update
  • Refactoring

Feature Completeness Checklist

  • DCO sign-off — Signed-off-by: trailer present on the single commit
  • Tests — cli/lucli/tests/specs/commands/PackagesCommandSpec.cfc gains a new describe("wheels packages install — alias for add", ...) block. The first assertion (install with no name now throws the same BadInput that add throws) fails against the pre-change dispatch (which returned "" silently). The second asserts both verbs reach the same code path by capturing the throw type for a bogus package name from each verb — neither short-circuits with a warning before instantiation.
  • Framework Docs — left to bot-update-docs.yml
  • AI Reference Docs — left to bot-update-docs.yml
  • CLAUDE.md — left to bot-update-docs.yml
  • CHANGELOG.md — entry under [Unreleased] / ### Fixed explaining the dispatch-vs-PackagesMainCli divergence and what the alias does (and does not) cover
  • Test runner passes — the local wheels/cli/tests runner could not bootstrap PackagesCommandSpec in this environment because the running Lucee server lacks the LuCLI-provided modules.BaseModule mapping that cli.lucli.Module extends — the same pre-existing bundle-level globalException shows in the baseline (without my changes), so it's an environment limitation, not a regression. CI runs the spec via tools/test-cli-local.sh which sets up LuCLI's mapping properly, and the TDD-gate will verify spec + implementation diff shape.

Test Plan

  • CI's tools/test-cli-local.sh run executes PackagesCommandSpec against a properly-bootstrapped LuCLI server and the new describe("wheels packages install — alias for add") block reports green
  • Verify by hand from an MCP client: invoking wheels_packages with arg1="install", arg2="wheels-basecoat" against a dev install installs into vendor/wheels-basecoat/ (was: returned an empty success string with no install)
  • Confirm wheels packages add wheels-basecoat is unchanged on the shell path (LuCLI dispatch reaches the same fall-through body via case "add":)
  • Confirm the shell-facing wheels packages install <name> still hits LuCLI's intercept and silently no-ops — that's outside this PR's scope and the help text already documents it

…spatch

The `case "install":` branch in `Module.cfc::packages()` previously printed
a warning to stdout and returned an empty string instead of installing
anything. That was wrong for every caller path that actually reaches
module dispatch — the stdio MCP server, scripted in-process clients, and
the spec suite — because `PackagesMainCli.install()` itself has been a
transparent alias for `add()` since #2729. The dispatch layer was the
only place where the alias broke.

The shell-facing `wheels packages install <name>` is still intercepted
by LuCLI's built-in extension installer upstream of module dispatch and
remains broken on that path (documented in the module-owned `--help`
text). This change only fixes the paths that LuCLI does NOT intercept.

Both verbs now share a single fall-through case body so validation,
error shape, and install behavior cannot drift apart again.

Fixes #2785

Signed-off-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>
…ection

Signed-off-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>
@wheels-bot

wheels-bot Bot commented May 21, 2026

Copy link
Copy Markdown
Contributor Author

Wheels Bot — Docs updated

Added a doc commit to this PR:

  • web/sites/guides/src/content/docs/v4-0-1-snapshot/digging-deeper/packages.mdx — clarified that install is a transparent alias for add on MCP/programmatic paths; shell CLI still intercepts it
  • web/sites/guides/src/content/docs/v4-0-0/digging-deeper/packages.mdx — same note applied to the v4-0-0 snapshot

The previous wording implied install never works at all; the PR fix makes it a real alias on every path that reaches Module.cfc (stdio MCP server, scripted clients, spec suite), so the doc now distinguishes shell from programmatic callers.

@wheels-bot wheels-bot Bot left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.


Wheels Bot — Reviewer A

TL;DR — Straightforward dispatch-layer alias fix: moving case "install": to a fall-through label above case "add": in the packages() switch is the right implementation, the commit is clean, and the tests cover the two failure modes that mattered (silent no-op and error-shape divergence). Two minor nits only; no blocking issues. Verdict: comment.


Correctness

The CFScript switch fall-through is correct — an empty case body (comments are not executable statements) falls through to the next case label on every supported engine (Lucee 5/6/7, Adobe 2018-2025, BoxLang). The implementation is a one-way door: once the label list is ordered "install" -> "add", the two verbs can never diverge again at the dispatch layer. That satisfies the invariant the PR is trying to establish.

Minor nit — second test's equivalence assertion is incomplete

cli/lucli/tests/specs/commands/PackagesCommandSpec.cfc, new second it block:

expect(addResult.flag).toBeTrue();
expect(installResult.flag).toBeTrue();
// Both must throw, and both must throw with a non-empty type
expect(installResult.type).notToBe("");

The comment says "proving they reached the same registry-lookup code path", but the assertion only checks that installResult.type is non-empty — it does not assert that it equals addResult.type. A future regression where install throws a different exception type (e.g. an argument-validation error introduced before the registry call) would still pass this test. Adding one line makes the intent explicit:

expect(installResult.type).toBe(addResult.type);

Tests

Test structure is correct:

  • Extends wheels.wheelstest.system.BaseSpec (BDD, not legacy RocketUnit). ✓
  • Closure uses variables.tempRoot (CFC variables scope, not local) — accessible from inside a closure. ✓
  • threw.flag = true / threw.type = e.type inside catch body mutate a pre-existing struct field, not a bare local.X assignment — BoxLang-safe per cross-engine invariant 11. ✓
  • captureThrow is hoisted to a variable before being called, not passed as an inline constructor argument — avoids Adobe CF ArrayStoreException: ASTcffunction trap (cross-engine invariant 5). ✓

Docs

Minor nit — CHANGELOG entry missing terminal period

CHANGELOG.md, new [Unreleased] / ### Fixed entry ends without a period. All surrounding entries end with one. Add it.


Commits

Single commit fix(cli): make wheels packages install a real alias for add in dispatch — type fix, scope cli, subject 73 chars, not ALL-CAPS. DCO Signed-off-by: trailer present and matches the configured git author. ✓

@wheels-bot

wheels-bot Bot commented May 21, 2026

Copy link
Copy Markdown
Contributor Author

Wheels Bot — Reviewer B (round 1)

A's review is technically accurate, well-scoped, and free of sycophancy. Both nits are verified against the actual diff. I'm aligned on the comment verdict — two small fixes are warranted before marking ready.

Sycophancy

None detected. A did not say LGTM without evidence; A identified two concrete, verifiable issues.

False positives

None detected.

  • Test nit (incomplete equivalence assertion): A claims expect(installResult.type).notToBe("") doesn't prove install threw the same exception type as add. Verified in diff — the assertion is:

    expect(installResult.type).notToBe("");

    The comment above it says "proving they reached the same registry-lookup code path", which the assertion doesn't actually prove. A's suggestion to add expect(installResult.type).toBe(addResult.type) is correct and actionable.

  • CHANGELOG terminal period: Verified. The new entry in CHANGELOG.md ends with "cannot drift apart again" — no period. Surrounding entries all end with periods. A's nit is accurate.

Missed issues

One minor item worth noting: A's review marker embeds SHA eb2b134f (the fix commit), but the review's commit_id is 82632b7 (the docs commit that is the current head). This means A was triggered against the first commit and didn't explicitly address the web/guides docs diff (v4-0-0/digging-deeper/packages.mdx and the v4-0-1-snapshot twin). I reviewed those changes: the new wording accurately distinguishes shell-path interception from MCP/in-process behavior, and no corrections are needed. Not a blocker, but A's coverage of the docs commit is implicit rather than stated.

No cross-engine issues missed. A correctly verified invariants 5 and 11 against the test closure structure. The CFScript fall-through behavior (empty case "install": body falls through to case "add":) is valid across all supported engines.

Verdict alignment

A's comment verdict is consistent with two open minor findings; approve would also be defensible here, but comment is not wrong given the test assertion gap.

Convergence

Aligned. Both findings are real, addressable in a single pass: (1) add expect(installResult.type).toBe(addResult.type) after the existing .notToBe("") call in PackagesCommandSpec.cfc, and (2) add a terminal period to the new CHANGELOG.md entry. Neither is structural — the implementation and test coverage are otherwise correct.

@wheels-bot wheels-bot Bot left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Wheels Bot — Reviewer A

TL;DR — The previous review covered the fix commit; this round covers the new docs(web/guides) commit pushed after that review. The v4-0-1-snapshot/ docs update is correct. The v4-0-0/ update is premature — it describes v4.0.1 behavior to users who are still on v4.0.0. One carry-over test nit from the prior review remains open. No blocking code issues. Verdict: comment.


Correctness

No issues in the implementation layer. The CFScript case "install": fall-through is correct on every supported engine (Lucee 5/6/7, Adobe 2018–2025, BoxLang) and is now in the right order (above case "add":).


Tests

Open nit — second test's equivalence assertion is still incomplete

cli/lucli/tests/specs/commands/PackagesCommandSpec.cfc, line 135:

expect(installResult.type).notToBe("");

The comment on lines 132–134 says "both must throw the SAME way for both verbs", but the assertion only checks that installResult.type is non-empty. A future regression where install is intercepted early and throws a BadInput before the registry lookup (while add throws a RegistryError) would still pass. The intent is one line away:

expect(installResult.type).toBe(addResult.type);

This was flagged in the prior review and was not addressed in the docs commit.


Docs

Concern — v4-0-0/ docs updated with v4.0.1 behavior

web/sites/guides/src/content/docs/v4-0-0/digging-deeper/packages.mdx, changed line:

Via the stdio MCP server (`wheels_packages`) and in-process callers, `install` is a
transparent alias for `add` — both verbs share the same validation, error shape, and
install behavior.

This fix targets develop (v4.0.1). A user on v4.0.0 who reads the v4.0.0 docs and calls wheels_packages with arg1="install" via MCP will get the old silent-no-op, contradicting what the docs now say.

The v4-0-1-snapshot/ update is correct and should stay. The v4-0-0/ file should either revert to its pre-PR wording or add an explicit version callout (e.g. "as of v4.0.1") to avoid misleading users still on the released build.

v4-0-1-snapshot/ update — accurate. ✓


Commits

  • fix(cli): make wheels packages install a real alias for add in dispatch — type fix, scope cli, 73 chars, DCO trailer present. ✓
  • docs(web/guides): clarify install-as-alias behavior in packages CLI section — type docs, scope web/guides, 74 chars, not ALL-CAPS. ✓

- PackagesCommandSpec: add `expect(installResult.type).toBe(addResult.type)`
  after the existing `.notToBe("")` assertion so the equivalence claim in
  the surrounding comment is actually enforced. A regression where
  `install` throws at argument validation (before the registry call)
  would have satisfied `.notToBe("")` but diverged from `add`'s shape;
  the new assertion pins it.
- CHANGELOG: terminal period on the new `[Unreleased] / ### Fixed`
  entry for consistency with surrounding entries.

Signed-off-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>
@wheels-bot

wheels-bot Bot commented May 21, 2026

Copy link
Copy Markdown
Contributor Author

Wheels Bot — Address Review (round 1)

Applied consensus findings from Reviewer A and Reviewer B's convergence (round 1):

  • Test equivalence assertion (cli/lucli/tests/specs/commands/PackagesCommandSpec.cfc:136) — added expect(installResult.type).toBe(addResult.type) directly after the existing .notToBe("") line so the surrounding comment's "proving they reached the same registry-lookup code path" claim is actually enforced. A future regression where install throws at argument-validation (before the registry call) would have passed .notToBe("") but diverged from add's exception shape; the equivalence check now pins it.
  • CHANGELOG terminal period (CHANGELOG.md:25) — added the missing period to the new [Unreleased] / ### Fixed entry so it matches the surrounding entries' punctuation.

No findings skipped — both consensus items were in scope and addressed in the same commit.

Local test verification: the spec layer's tools/test-cli-local.sh runner requires a LuCLI-provided modules.BaseModule mapping that isn't bootstrapped in this environment (same pre-existing limitation the PR body documents on the original commit). CI's tools/test-cli-local.sh job runs the spec against a properly-bootstrapped LuCLI server and will gate the assertion change. The diff is a pure-addition single-line BDD assertion against two struct fields that were already being populated — no flow change.

The new commit will trigger a fresh Reviewer A run on the updated SHA. Convergence loop continues until reviewers align on `approve` or the outer-loop cap (5 rounds) is reached.

@wheels-bot wheels-bot Bot left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Wheels Bot — Reviewer A

TL;DR — The round-1 fix commit (e35a864) is clean: both nits from the prior round-2 review (the missing equivalence assertion in the spec and the trailing period in CHANGELOG) are fully addressed. One item from round 2 remains open: v4-0-0/digging-deeper/packages.mdx now describes the install-as-alias behavior that is only true on v4.0.1+, not on the released v4.0.0 build. No blocking code or cross-engine issues. Verdict: comment.


Correctness

Round-1 fix is correct on all counts:

  • expect(installResult.type).toBe(addResult.type) is now present at cli/lucli/tests/specs/commands/PackagesCommandSpec.cfc line 140 and pins the equivalence claim the surrounding comment already made. ✓
  • CHANGELOG terminal period present. ✓
  • DCO Signed-off-by: trailer on all three commits (eb2b134, 82632b7, e35a864). ✓

Docs

Open nit from round 2 — v4-0-0/ still claims the install alias is transparent on MCP/in-process paths

web/sites/guides/src/content/docs/v4-0-0/digging-deeper/packages.mdx, line 320 (added in 82632b7, not touched by e35a864):

Via the stdio MCP server (`wheels_packages`) and in-process callers, `install` is a
transparent alias for `add` — both verbs share the same validation, error shape, and
install behavior.

This describes the fix introduced in this PR (targeting v4.0.1). A user pinned to v4.0.0 who reads the v4.0.0 docs and calls wheels_packages with arg1="install" via MCP will get the silent-empty-string no-op from the old case "install": branch — contradicting what the versioned docs now say.

The v4-0-1-snapshot/ update (same line, same text) is correct and should stay.

Suggested fix for v4-0-0/ only — revert to the pre-PR wording or add an explicit callout, for example:

The canonical verb is `add`. On the shell surface, `wheels packages install foo` is
intercepted by LuCLI's built-in extension installer before it reaches the Wheels package
handler, so it silently no-ops (the same trap that renamed `wheels browser install` to
`wheels browser setup`). `add` is the canonical verb across the docs; MCP callers
should use `add` for compatibility across all 4.x releases.

Or, if preserving the alias note, scope it to the version where it became true:

Via the stdio MCP server (`wheels_packages`) and in-process callers, `install` is a
transparent alias for `add` as of v4.0.1 — see the v4.0.1 snapshot docs.

Commits

  • fix(cli): make wheels packages install a real alias for add in dispatch — type fix, scope cli, 73 chars, DCO present. ✓
  • docs(web/guides): clarify install-as-alias behavior in packages CLI section — type docs, scope web/guides, 74 chars, DCO present. ✓
  • fix(cli): address Reviewer A/B consensus findings (round 1) — type fix, scope cli, 58 chars, DCO present. ✓

@wheels-bot

wheels-bot Bot commented May 21, 2026

Copy link
Copy Markdown
Contributor Author

Wheels Bot --- Reviewer B (round 1)

A's review on SHA e35a864 is accurate and actionable. The one remaining open item --- the v4-0-0 versioned docs describing install-as-alias behavior that only landed in this PR (v4.0.1) --- is a real issue I verified against the diff. Aligned on comment with a concrete fix; emitting converged-changes.

Sycophancy: None detected. A confirmed two prior-round nits with specific file+line evidence before moving on; did not approve without basis.

False positives: None detected.

  • A's claim that commit e35a864 adds expect(installResult.type).toBe(addResult.type) at PackagesCommandSpec.cfc line 140 is verified against prior diff and address-review comment.
  • A's claim that the v4-0-0 docs now describe install-as-alias behavior is correct. The diff shows both v4-0-0/digging-deeper/packages.mdx and v4-0-1-snapshot/digging-deeper/packages.mdx received identical text: "Via the stdio MCP server and in-process callers, install is a transparent alias for add." That is true as of v4.0.1 (this PR). A user on v4.0.0 who reads the v4.0.0 versioned docs and calls wheels_packages with arg1=install via MCP will get the silent-empty-string no-op from the pre-patch case "install": branch. The docs contradict the shipped code. A's flag is accurate.
  • A's commit-lint review of all three commits is correct (types, scopes, lengths, DCO trailers all pass).

Missed issues: None detected. A's "round 2" label in the review body is A's own internal round numbering (this is A's second review on this PR, the first having been on 82632b7) and does not indicate an error. The docs change spans only two files, both examined. No cross-engine concerns introduced by the single-line assertion addition in the spec.

Verdict alignment: A's comment verdict is consistent with one concrete, scoped, actionable finding --- no code or logic defect, just a versioned-docs accuracy issue. comment rather than request-changes is appropriate for a docs-only concern.

Convergence: Aligned. A's sole open finding is specific and fixable: revert v4-0-0/digging-deeper/packages.mdx to wording that does not claim install works as an alias on MCP/in-process paths (since it did not in v4.0.0), or scope the note to "as of v4.0.1." The v4-0-1-snapshot copy is correct and should stay. One file, one sentence, no code change needed. Emitting converged-changes.

- web/sites/guides/src/content/docs/v4-0-0/digging-deeper/packages.mdx
  (line 320) — scope the install-as-alias note to v4.0.1+. The previous
  wording asserted the alias was transparent on MCP / in-process paths,
  but that's only true after this PR (which targets v4.0.1). On v4.0.0
  itself, MCP also no-ops; the versioned v4.0.0 docs now say so
  explicitly and point readers to the v4.0.1 snapshot for the alias
  behavior. The v4-0-1-snapshot/ copy was already correct and is
  untouched.

Signed-off-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>
@wheels-bot

wheels-bot Bot commented May 21, 2026

Copy link
Copy Markdown
Contributor Author

Wheels Bot — Address Review (round 2)

Applied the single consensus finding from Reviewer A's round-3 review and Reviewer B's round-1 alignment on e35a864:

  • web/sites/guides/src/content/docs/v4-0-0/digging-deeper/packages.mdx:320 — scoped the install-as-alias note to v4.0.1+. The previous wording (introduced in 82632b7) claimed the alias was transparent on MCP / in-process paths in the v4.0.0 versioned docs, but that's only true after this PR lands. The revised sentence states that on v4.0.0 itself MCP also no-ops and points readers to the v4.0.1 snapshot for the alias behavior; it also recommends add for cross-4.x compatibility. The v4-0-1-snapshot/ copy was already correct and is intentionally untouched.

No findings skipped — A's round-3 review explicitly confirmed the round-1 fixes (PackagesCommandSpec equivalence assertion and CHANGELOG terminal period) are in place, leaving this docs note as the sole open item. Both A and B aligned on this exact finding (B's converged-changes comment recommended either revert or version-scope; the v4.0.1+ callout is A's second-suggested wording).

Test verification: docs-only change to a single .mdx content file under web/sites/guides/. No CFML, no test specs, no framework code touched. tools/test-local.sh covers vendor/wheels/tests/specs/, not the static-site content — there's no affected spec layer to re-run. The diff is a pure prose edit; no behavior change anywhere in the framework or CLI.

The new commit will trigger a fresh Reviewer A run on the updated SHA. Convergence loop continues until reviewers align on approve or the outer-loop cap (5 rounds) is reached.

@wheels-bot wheels-bot Bot left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Wheels Bot — Reviewer A

TL;DR — This is the fourth and final review pass against head f7858b3d9. All three open items from the previous rounds are fully resolved: the test equivalence assertion is present, the CHANGELOG has its terminal period, and the v4-0-0/ docs now correctly scope the alias behavior to v4.0.1+. The implementation is clean, the tests are cross-engine safe, and the commits are all convention-compliant with DCO sign-offs. No blocking issues remain. Verdict: approve (submitted as comment — GitHub disallows self-approval).


Correctness

All three prior-round open items are closed:

  1. Test equivalence assertion — cli/lucli/tests/specs/commands/PackagesCommandSpec.cfc, lines 135–140: expect(installResult.type).notToBe("") is now followed by expect(installResult.type).toBe(addResult.type). The equivalence claim in the surrounding comment is fully enforced. Fixed in e35a864. ✓

  2. CHANGELOG terminal period — CHANGELOG.md, new [Unreleased] / ### Fixed entry ends with ...cannot drift apart again. — period present. Fixed in e35a864. ✓

  3. v4-0-0/ docs versioning — web/sites/guides/src/content/docs/v4-0-0/digging-deeper/packages.mdx, line 320 now reads:

    On v4.0.0 the same install argument also no-ops via the stdio MCP server (wheels_packages) and other in-process callers; the transparent install → add alias on MCP / in-process paths landed in v4.0.1 — see the v4.0.1 snapshot docs. Use add for compatibility across all 4.x releases.

    The round-2 concern (v4.0.0 docs describing v4.0.1-only behavior) is resolved. Fixed in f7858b3d9. ✓

  4. v4-0-1-snapshot/ docs — correctly describes install as a transparent alias on MCP / in-process callers. Unchanged and accurate. ✓


Cross-engine

The spec's catch blocks use threw.flag = true / threw.type = e.type — struct-field mutation, not bare local.X = ... inside catch — BoxLang-safe per cross-engine invariant 11. ✓

The captureThrow closure is hoisted to a variable before use; it is not passed as an inline constructor named argument. Avoids Adobe CF ArrayStoreException: ASTcffunction trap (cross-engine invariant 5). ✓


Tests

Both new it blocks are present and structurally sound:

  • Missing-name path: install with no argument throws the same BadInput as add, and the error message includes "add". ✓
  • Same-path dispatch: bogus package name causes both verbs to throw the same exception type (expect(installResult.type).toBe(addResult.type)). ✓

Commits

SHA Subject DCO
eb2b134 fix(cli): make wheels packages install a real alias for add in dispatch ✓
82632b7 docs(web/guides): clarify install-as-alias behavior in packages CLI section ✓
e35a864 fix(cli): address Reviewer A/B consensus findings (round 1) ✓
f7858b3 fix(web/guides): address Reviewer A/B consensus findings (round 2) ✓

All subjects ≤ 100 chars, types from allowlist, not ALL-CAPS, Signed-off-by: trailers present on every commit. ✓

@wheels-bot

wheels-bot Bot commented May 21, 2026

Copy link
Copy Markdown
Contributor Author

Wheels Bot — Reviewer B (round 1)

A's review on SHA f7858b3d9 is accurate, thorough, and reaches the right verdict. All three prior-round findings are verified closed against the actual diff. No sycophancy, no false positives, no missed issues. Aligned on approve.

Sycophancy: None detected. A cited specific file paths, line numbers, and invariant numbers for every closed item before concluding approve.

False positives: None detected. Each claim was verified against the diff: test equivalence assertion present in sequence (notToBe then toBe); CHANGELOG entry ends with a period; v4-0-0 docs correctly scope the MCP alias to v4.0.1+; cross-engine invariant 11 respected (struct field mutation in catch, not bare local.X); cross-engine invariant 5 respected (captureThrow hoisted before use, not inline named-arg); CFScript fall-through valid across all supported engines; all four commit subjects and DCO trailers match the git log.

Missed issues: None detected. Diff is small and self-contained. Re-scanned for mixed arg styles, reserved scope shadowing, arguments-scope-as-attributeCollection (invariant 10), and arrow-function cross-engine support — all clear.

Verdict alignment: A's approve is consistent with zero remaining open findings across four review passes.

Convergence: Aligned. No changes needed. All prior-round findings are resolved and A's approve verdict is correct.

@bpamiri
bpamiri marked this pull request as ready for review May 22, 2026 12:46
…l-no-ops-in-cli-4-0-1

Resolve conflict in CHANGELOG.md [Unreleased] Fixed section by keeping all three entries — PR #2786's wheels packages install alias entry on top, followed by the two BrowserTest entries (#2782 NotWired, #2783 base URL layered lookup) that landed on develop after this PR branched.

Signed-off-by: Peter Amiri <peter@alurium.com>

@wheels-bot wheels-bot Bot left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Wheels Bot — Reviewer A

TL;DR — This round covers only the develop-sync merge commit (094285270) authored by Peter Amiri, pushed after the prior round-4 approve. The PR's implementation files (Module.cfc, PackagesCommandSpec.cfc, the two packages.mdx docs) are unchanged. All four prior-round findings remain closed. The CHANGELOG conflict resolution is correct. No blocking issues. Verdict: comment (approve-intent; GitHub blocks self-approval since wheels-bot is the PR author).


Correctness

The merge commit's only substantive action was resolving a CHANGELOG conflict. The resolution keeps all three [Unreleased] / ### Fixed entries in order: the PR's wheels packages install alias entry first, followed by the two BrowserTest entries (#2782 NotWired guard, #2783 layered base-URL lookup) that landed on develop after this branch diverged. The three entries are logically independent and do not interfere with each other. ✓

No other files touched by the merge overlap with the PR's changed files — the develop-side additions (vendor/wheels/wheelstest/BrowserTest.cfc, UnwiredBrowserGuard.cfc, the two new BrowserTest specs, the browser-tests guide pages, and the release/distribution tooling files) are all orthogonal to the packages dispatch fix.


Commits

SHA Subject Author DCO
eb2b134 fix(cli): make wheels packages install a real alias for add in dispatch wheels-bot ✓
82632b7 docs(web/guides): clarify install-as-alias behavior in packages CLI section wheels-bot ✓
e35a864 fix(cli): address Reviewer A/B consensus findings (round 1) wheels-bot ✓
f7858b3 fix(web/guides): address Reviewer A/B consensus findings (round 2) wheels-bot ✓
094285270 Merge branch 'develop' into fix/bot-2785-... Peter Amiri ✓

Merge commits are exempt from conventional-commit linting by standard commitlint configuration. Signed-off-by: Peter Amiri <peter@alurium.com> is present. ✓


@wheels-bot

wheels-bot Bot commented May 22, 2026

Copy link
Copy Markdown
Contributor Author

Wheels Bot — Reviewer B (round 1)

A's review of the merge commit is accurate and appropriately scoped. The one imprecision — undercounting CHANGELOG entries — does not affect the correctness of A's conclusion, and the comment verdict (forced by GitHub's self-approval restriction, not by any open finding) is correct. Aligned on approve.

Sycophancy

None detected. A did not say LGTM without evidence. A explicitly verified the CHANGELOG conflict resolution, enumerated all five commits, checked conventional-commit compliance, and noted the self-approval constraint before issuing the approve-intent verdict.

False positives

None detected. A's claims are accurate:

  • The merge commit's only substantive change is CHANGELOG conflict resolution — confirmed by the diff, which shows no changes to Module.cfc, PackagesCommandSpec.cfc, or either packages.mdx file.
  • All four prior-round findings (test equivalence assertion, CHANGELOG terminal period, v4-0-0 docs version-scoping, and the implicit cross-engine checks) are correctly declared closed — verified against the cumulative PR diff.
  • The merge commit's DCO trailer (Signed-off-by: Peter Amiri <peter@alurium.com>) is present — no dispute.

One imprecision worth noting (not a false positive, but an inaccuracy in A's description): A states the CHANGELOG resolution "keeps all three [Unreleased] / ### Fixed entries in order" and names "two BrowserTest entries (#2782, #2783) that landed on develop." The actual diff shows four entries under ### Fixed after the merge — the new wheels packages install alias entry plus three develop-side entries: BrowserTest NotWired guard (#2782), BrowserTest base URL resolution (#2783), and the Linux .deb/.rpm double-nesting fix (#2773). A omitted the Linux packages entry from the accounting. The conflict resolution itself is still valid (no entry was dropped or reordered), so this is a description imprecision, not a correctness flaw.

Missed issues

None detected. The 1f9cf4c8e commit that appears in the local git log after the merge (message: "fix(web/guides): address Reviewer A/B consensus findings (round 2)") is a develop-side commit that arrived via the merge — not a feature-branch commit A needed to audit. This is confirmed by the prior Reviewer B approval on SHA f7858b3d9 as head before the merge was added; the feature branch had exactly four bot commits at that point, matching A's table. A was correct to scope the commit table to the five PR commits (four feature-branch + one merge).

No cross-engine issues introduced. The merge commit touched no CFML source.

Verdict alignment

A's comment verdict is consistent with zero open findings; the non-approve state is a GitHub platform constraint (self-approval blocked), not a code concern. Functionally equivalent to approve.

Convergence

Aligned. No changes needed. All prior-round findings are resolved and present in the diff; A's approve-intent is correct. The CHANGELOG entry count imprecision does not require a follow-up commit.

@bpamiri
bpamiri merged commit 6789c13 into develop May 22, 2026
14 checks passed
@bpamiri
bpamiri deleted the fix/bot-2785-wheels-packages-install-still-no-ops-in-cli-4-0-1 branch May 22, 2026 13:48
bpamiri added a commit that referenced this pull request May 22, 2026
Resolves CHANGELOG.md conflict in the [Unreleased] Fixed section by
keeping this PR's column-quoting entry alongside develop's three
entries that landed while the PR was open (#2782, #2783, #2786).

No code conflicts -- the model SQL changes in vendor/wheels/model/
{sql.cfc,read.cfc} were untouched by the develop commits, and the
BrowserTest / packages-install changes pulled in from develop are
unrelated to the column-quoting fix.

Signed-off-by: Peter Amiri <peter@alurium.com>
bpamiri added a commit that referenced this pull request May 22, 2026
Resolves merge conflict in CHANGELOG.md [Unreleased] / ### Fixed by
combining the PR's tools/test-local.sh entry with the entries added on
develop since the PR was opened (#2791, #2790, model SELECT $quoteIdentifier,
#2786, #2779, #2792). Newest-first ordering preserved; (#2796) suffix
added to the PR's entry to match the recent-entry convention.

No code changes — only CHANGELOG ordering.

Signed-off-by: Peter Amiri <peter@alurium.com>
bpamiri added a commit that referenced this pull request May 27, 2026
* chore: bump develop snapshot target to 4.0.2 (#2770)

Manual bump after the v4.0.1 GA — `bump-develop-version.yml` fired via
`repository_dispatch` (the #2609 fix worked) but failed in 12s on a
second issue: `peter-evans/create-pull-request@v6` hit
`remote: Duplicate header: "Authorization"` because the `actions/checkout`
step left credentials persisted that conflict with the action's own token.
See run 26173817714 for the failed log.

Setting `wheels.json` to `4.0.2` so subsequent develop snapshots are
tagged `4.0.2-snapshot.<run>`. This is a baseline, not a commitment —
the next GA's scope decision is made at tag-cut time.

Follow-up issue tracks the workflow fix (add `persist-credentials: false`
to the checkout step).

Signed-off-by: Peter Amiri <peter@alurium.com>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* ci(release): fix bump-develop-version.yml duplicate Authorization header (#2771)

`actions/checkout@v6` defaults to `persist-credentials: true`, which
writes `http.https://github.com/.extraheader = AUTHORIZATION: basic <GITHUB_TOKEN>`
to the local `.git/config`. `peter-evans/create-pull-request@v6` then
sets its own `extraheader` for the dispatch token, and the next git
operation sends both Authorization headers — GitHub returns HTTP 400
with `remote: Duplicate header: "Authorization"`.

First observed on the v4.0.1 GA (2026-05-20, run 26173817714); manual
workaround was #2770. Setting `persist-credentials: false` keeps
peter-evans/create-pull-request as the sole Authorization authority.

This is a documented peter-evans/create-pull-request gotcha when the
caller uses a non-default token.

Signed-off-by: Peter Amiri <peter@alurium.com>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs(web/blog): Wheels 4.0.1: Adobe CF hardening, Windows Scoop fixes, and the post-GA shakeout (#2772)

Walks through the ~100 PRs that landed between 4.0.0 and 4.0.1: Adobe CF
2023/2025 attributeCollection + onError + env() + Vite asset-walk chain,
the Windows Scoop wheels.cmd cmd.exe pre-parser fix, paginationNav()
viewStyle presets, whereIn([]) short-circuit, CORS preflight/Vary/multi-
origin fixes, plural mappings, Oracle bulk-insert + CockroachDB advisory
locks, BoxLang adapter fixes, deploy CLI hardening, and Rocky Linux RPM
fixes from the titan production cutover.

Signed-off-by: Peter Amiri <peter@alurium.com>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(cli): guard application.wo in onError so init failures don't cascade (#2774)

* fix(cli): guard application.wo in onError so init failures don't cascade

When the Wheels Injector fails to load during onApplicationStart (a stale
/wheels mapping under Lucee Express 7 is the symptom users hit on the
"Your First 15 Minutes" tutorial), application.wo is never assigned. The
existing recovery try/catch inside onError swallows a second failure
silently and then unconditionally calls application.wo.$getRequestTimeout(),
which throws "The key [WO] does not exist." and replaces the real
diagnostic with a cryptic cascade.

Add a StructKeyExists(application, "wo") guard right after the recovery
try/catch in cli/lucli/templates/app/public/Application.cfc (the template
behind `wheels new`) and the demo public/Application.cfc. When the global
isn't there, render a minimal HTML error page and return — the user sees
"Wheels failed to initialize" plus the original exception message instead
of the cascade.

Fixes #2773

Signed-off-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>

* docs(web/guides): note application error fallback and init failure in troubleshooting docs

Signed-off-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>

* fix(cli): address Reviewer A/B consensus findings (round 1)

- Set HTTP 500 status code in the onError fallback in both
  cli/lucli/templates/app/public/Application.cfc and public/Application.cfc
  so monitoring tools and CDNs don't cache the Wheels-init failure as
  a successful response. Uses a plain struct for cfheader's
  attributeCollection per CLAUDE.md cross-engine invariant #10
  (Adobe CF 2023/2025 reject the arguments scope on built-in tags).
- Document the no-nested-braces assumption behind catchClosePattern in
  vendor/wheels/tests/specs/cli/OnErrorFallbackGuardSpec.cfc so a future
  edit that adds nested braces inside the outer catch knows why the
  silent fallback to scanFrom=1 is the safety net.
- Fix the contradictory recovery steps in the first-15-minutes guide
  (wheels reload requires a running server) at
  web/sites/guides/src/content/docs/v4-0-1-snapshot/start-here/first-15-minutes.mdx.
- Replace the speculative "pre-4.0.2" wording in
  .ai/wheels/troubleshooting/common-errors.md with "4.0.1 or earlier"
  since the fix is still in [Unreleased].

Signed-off-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>

* chore(web): refresh visual baseline(s) (all)

Manually triggered baseline refresh via
.github/workflows/refresh-visual-baselines.yml
on branch fix/bot-2773-first-15-minutes-tutorial-fails-the-key-wo-does-no.

Run when an intentional content/layout change makes the visual-regression
check fail. The new PNG(s) under web/tests/visual-baselines/ are now the
expected rendering; re-run the failing visual-regression job to flip the
check green.

---------

Signed-off-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>
Co-authored-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

* fix(ci): stop double-nesting framework inside Linux .deb/.rpm packages (#2776)

* fix(ci): stop double-nesting framework inside Linux .deb/.rpm packages

The nfpm contents rule pointed `src` at `./build/framework/` for the
framework staging step. `wheels-core-VER.zip` carries a top-level
`wheels/` directory that `unzip` preserves, so the resulting tree was
`./build/framework/wheels/...`. nfpm `type: tree` copies *contents* of
src into dst, which meant the inner `wheels/` wrapper itself landed at
the destination — producing
`/opt/wheels/module/vendor/wheels/wheels/Injector.cfc` instead of
`/opt/wheels/module/vendor/wheels/Injector.cfc`.

After the user-side wrapper sync (`/opt/wheels/module/*` →
`~/.wheels/modules/wheels/*`) and `wheels new <app>` copy, every fresh
Linux install ended up with the framework one directory level too deep.
Lucee's `/wheels` mapping pointed at the (empty) outer directory, so
`new wheels.Injector("wheels.Bindings")` in the generated
`public/Application.cfc` threw `could not find component or class with
name [wheels.Injector]` on the first request. The existing onError
handler then dereferenced `application.wo` (which was never assigned
because Injector init failed), surfacing only the cryptic cascade
`The key [WO] does not exist.` — issue #2773.

The brew formula handles this correctly by re-introducing the wheels/
wrapper at stage time
(`(share/"wheels/framework/wheels").install Dir["*"]`). Both Linux nfpm
configs now pin `src` at `./build/framework/wheels/` so the contents
flatten into `/opt/wheels/module/vendor/wheels/` as intended.

The published 4.0.1 .deb / .rpm artifacts ship the broken layout (1
.deb download, 0 .rpm at time of fix). A re-released 4.0.2 will be
needed to deliver the fix to users — the change here is to the build
config only, not to any framework or CLI code.

Tests: `vendor/wheels/tests/specs/cli/LinuxPackageStagingSpec.cfc`
gains a per-channel `it()` that asserts `src: ./build/framework/wheels/`
+ `dst: /opt/wheels/module/vendor/wheels/` are paired in each nfpm
yaml. Structural assertion follows the existing #2700 pattern (the
file already pins four other packaging invariants the same way).

Note on local verification: the structural spec was sanity-checked via
equivalent grep / perl POSIX patterns over the YAMLs (positive match
for the fixed form, zero matches for the buggy form). Running the
spec through the CFML runner locally was blocked by a port-8081
collision with two stale wheels server processes from prior dev
sessions — CI compat-matrix will run the spec across every engine ×
DB on this PR.

Closes #2773

Signed-off-by: Peter Amiri <peter@alurium.com>

* test(ci): add negative guard for buggy framework src in nfpm yamls

Reviewer A on PR #2776 (wheels-bot) flagged that the new framework-src
spec only asserted the *fixed* form was present, without a matching
`toBeFalse` for the buggy `./build/framework/` form. The file's existing
wrapper-routing checks (lines 60-68 / 81-106) already use a dual-
assertion pattern; the new spec was a one-sided outlier.

Add the negative guard: if a future copy-paste leaves both the bare
`src: ./build/framework/` and the fixed `src: ./build/framework/wheels/`
in the same yaml, nfpm would stage both — the bare one reintroduces
the double-nesting and breaks every fresh Linux install. The spec now
fails loudly in that scenario instead of silently passing on the
presence of the fixed entry.

The two regexes are mutually exclusive by construction: the positive
matches `framework/wheels/` followed by whitespace + `dst:`; the
negative matches `framework/` followed *immediately* by whitespace +
`dst:`. Since `wheels` isn't whitespace, `[[:space:]]+` can't bridge
across it, so the negative regex cannot false-positive on the fixed
form. Confirmed via perl POSIX equivalent against both nfpm yamls
plus a synthetic buggy fixture.

Also adds an inline comment to the positive assertion documenting why
`[[:space:]]+` works across the YAML line break (POSIX `[[:space:]]`
resolves to Java's `\s` in both Lucee and Adobe CF, which includes
`\n`) — addresses Reviewer A's Nit 2 observation that the cross-line
match hadn't been locally verified.

Signed-off-by: Peter Amiri <peter@alurium.com>

---------

Signed-off-by: Peter Amiri <peter@alurium.com>

* docs(web/guides): correct Linux bleeding-edge install URLs to wheels-be_* (#2777)

* docs(web/guides): correct Linux bleeding-edge install URLs to wheels-be_*

PR #2759 (2026-05-18) renamed the snapshot Linux artifacts from `wheels_*`
to `wheels-be_*` (debs) and `wheels-be-*.x86_64.rpm` (rpms) so the package
name itself differentiates the channel. The install guides were not
updated alongside that rename, so every documented `curl -fsSLO ...`
command for Linux bleeding-edge install resolves to a 404 against the
actual snapshot release assets.

Verified against v4.0.2-snapshot.1923 (published 2026-05-20):

  Guide says:    .../wheels_4.0.2.snapshot.1923_amd64.deb   → 404
  Actual asset:  .../wheels-be_4.0.2.snapshot.1923_amd64.deb

Fix all six pages where the snippets / prose examples appear (three
unique pages mirrored across v4-0-0 and v4-0-1-snapshot doc versions):

  start-here/installing.mdx                 — "Want bleeding-edge?" aside
  start-here/release-channels.mdx           — main BE install snippets +
                                              "Switching channels" snippets
                                              + tilde-mangling prose
  command-line-tools/installation.mdx       — bleeding-edge install snippets

The substitutions are scoped to bleeding-edge contexts (snippets using
`${SNAP_FILENAME_VER}` and prose `wheels_4.0.0.snapshot.*` filename
examples). Stable-channel snippets, which use `${WHEELS_VERSION}` and
fetch from `wheels-dev/wheels` (not `wheels-snapshots`), are unchanged —
they correctly retain the bare `wheels_` / `wheels-` prefixes because
the stable package name on Linux is still just `wheels`.

Without this fix, users cannot install or test bleeding-edge / develop
snapshots on Linux via the documented flow. This blocks user-side
verification of develop-only fixes before they ship in the next stable
patch — including PR #2776 (Linux .deb framework nesting fix) and
PR #2774 (defensive onError guard), both of which close issue #2773.

Signed-off-by: Peter Amiri <peter@alurium.com>

* docs(web/guides): fix release-channels.mdx — missed BE Tab URLs + Linux switching semantics

Round-1 reviewer findings on PR #2777:

A's Nit 1 — primary install Tabs at lines 104-105 (Debian/Ubuntu BE)
and 112 (Fedora/RHEL BE) of `release-channels.mdx` still resolved to
404. My initial verification sweep grep'd for `${SNAP_FILENAME_VER}`,
but these snippets bind the tag to `${WHEELS_FILENAME_VER}` (a
different bash var name). The fix is the same — point at the
`wheels-be_` / `wheels-be-` artifacts.

A's Nit 2 + B's catch — the "Switching channels" section had three
related staleness bugs after #2759 renamed the BE package:

  1. Line 129 prose claimed "only a single package name (`wheels`)
     is published per channel today" — false post-rename.

  2. Lines 142-143 inline comment ("upgrades in place — no uninstall
     step needed") was true when both channels shared the `wheels`
     name, but the new world depends on the actual nfpm-declared
     `Replaces:` / `Conflicts:` metadata. B caught the contradiction
     between A's proposed line-129 prose and the existing line-142
     comment.

  3. Lines 158-172 (Linux BE → stable, both Debian and Fedora) had
     the *same* conceptual bug as 142-143: they prescribed
     `--allow-downgrades` (apt) / `dnf downgrade`, both of which
     assume same-package-name version transitions. With different
     names, both would fail with a `/usr/bin/wheels` file conflict
     because the stable `wheels` package doesn't declare
     `Replaces:`/`Obsoletes: wheels-be`. Reviewers didn't explicitly
     flag this set, but it's the same root cause and listing them
     inconsistently would have left readers worse off.

Verified the actual nfpm metadata before rewriting (so the prose
matches what the packages really declare):

  wheels-be deb:  Replaces: wheels  +  Conflicts: wheels
  wheels-be rpm:  Conflicts: wheels  (no Obsoletes)
  wheels    deb:  no Replaces/Conflicts against wheels-be
  wheels    rpm:  no Conflicts/Obsoletes against wheels-be

The new prose at line 129 explains the asymmetry up front; each
snippet now carries a short comment naming the specific metadata
that drives its action (or the lack of metadata that requires the
explicit `apt remove` / `dnf remove`).

Stable-channel snippets and stable install Tabs are unchanged.

Signed-off-by: Peter Amiri <peter@alurium.com>

* docs(web/guides): name the actual Conflicts declaration in BE→stable comments

Reviewer A round-2 nit on PR #2777: the BE → stable (Debian) snippet's
comment said apt "would fail with a /usr/bin/wheels file conflict",
framing the failure mode as a dpkg-level file-ownership conflict. The
actual blocker is the package-level `Conflicts: wheels` declaration in
wheels-be's deb metadata — apt refuses the install with a package
conflict error before dpkg ever attempts to unpack files. An advanced
user debugging the actual error message would be confused by the
file-conflict framing.

Rewrite the Debian comment per A's suggestion, naming the actual
mechanism: `wheels-be declares Conflicts: wheels`. Kept the secondary
note about the missing `Replaces: wheels-be` in stable since it
explains why apt also wouldn't auto-remove (relevant context if a
reader wonders whether a single command could swap them).

Updated the Fedora BE → stable comment to use parallel framing for
consistency — same root cause (`wheels-be` declares `Conflicts:
wheels`, applies bidirectionally on rpm too). Reviewer A only flagged
the Debian site explicitly, but leaving the two comments inconsistent
would have invited the same "two sites must agree" finding that
caught round 1's line-142 / line-129 contradiction.

Signed-off-by: Peter Amiri <peter@alurium.com>

---------

Signed-off-by: Peter Amiri <peter@alurium.com>

* fix(test): BrowserTest reports unwired this.browser with browserDescribe() hint (#2782)

* fix(test): BrowserTest reports unwired this.browser with browserDescribe() hint

Plain describe() blocks inside BrowserTest subclasses left this.browser
as an empty string, so the first DSL call surfaced as
"function [visitUrl] does not exist in the String" — a misleading error
that hits every newcomer on iteration 1. Install an UnwiredBrowserGuard
sentinel at this.browser before browserDescribe() wires a real
BrowserClient (and after $endBrowserContext tears it down) so any method
call throws Wheels.BrowserTest.NotWired with a message naming
browserDescribe() as the fix.

Fixes #2778

Signed-off-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>

* docs(web/guides): note Wheels.BrowserTest.NotWired when describe() used instead of browserDescribe()

Signed-off-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>

---------

Signed-off-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>
Co-authored-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>

* chore: rename Phase 2 bucket repos to apt-wheels / yum-wheels for naming consistency (#2788)

Phase 2 Linux native-repo templates and dispatch wiring referenced
`wheels-dev/apt-wheels-dev` and `wheels-dev/yum-wheels-dev`. The `-dev`
suffix appeared to mirror the DNS form (`apt.wheels.dev`
→ `apt-wheels-dev`) but reads as a redundant org echo inside the
`wheels-dev` org and breaks the established `<package-manager>-wheels`
naming used by the other sister repos (`homebrew-wheels`,
`scoop-wheels`, `chocolatey-wheels`).

Rename everywhere to drop the `-dev` suffix:

- wheels-dev/apt-wheels-dev → wheels-dev/apt-wheels
- wheels-dev/yum-wheels-dev → wheels-dev/yum-wheels

The actual bucket repos were just created under the new names today
(2026-05-21 ~20:15 UTC), so this PR brings the templates / docs /
release-workflow dispatch in sync with the on-GitHub reality before
the first end-to-end dispatch fires. No live infrastructure references
the old names yet — Cloudflare Pages, DNS, and the bucket-side CI
secrets all post-date this rename.

Mechanical substitution across 9 files (27 references). Stable `wheels`
package name (the bare `wheels` in nfpm configs and `apt install
wheels` snippets) is untouched — only the org-namespaced repo names
change.

Signed-off-by: Peter Amiri <peter@alurium.com>

* fix(test): resolve BrowserTest base URL through layered lookup at instance time (#2783)

* fix(test): resolve BrowserTest base URL through layered lookup at instance time

Specs running against a non-default port (Titan on 60050, scaffolds on
60080) previously had to compare getBaseUrl() against a sentinel string
and override it manually because $resolveBaseUrl() returned
http://localhost:8080 unconditionally and the only escape hatch
(WHEELS_BROWSER_TEST_BASE_URL) is cached by the JVM at process start.

$resolveBaseUrl() now consults, in order: this.baseUrl per-spec override,
get("browserTestBaseUrl") Wheels setting, -Dwheels.browserTest.baseUrl
JVM property, WHEELS_BROWSER_TEST_BASE_URL env, $detectBaseUrlFromCgi()
auto-detect (the test runner reaches the suite over HTTP, so cgi already
names the right host:port), then the localhost:8080 default. The CGI
auto-detect skips when port==8080 so existing default-port runs are
unchanged.

Fixes #2779

Signed-off-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>

* docs(web/guides): document BrowserTest layered base-URL resolution (#2779)

Signed-off-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>

* fix(test): address Reviewer A/B consensus findings (round 1)

- Strip canonical ports (http:80, https:443) in $detectBaseUrlFromCgi to
  match URL conventions; update the https:443 spec expectation and add a
  dedicated http:80 case (vendor/wheels/wheelstest/BrowserTest.cfc:297-299,
  vendor/wheels/tests/specs/wheelstest/BrowserTestBaseUrlResolutionSpec.cfc:51-61).
- Document why the "falls back through layers" assertion is intentionally
  weak — JVM env vars are read-only from CFML and the Wheels get() setting
  needs a live framework context, so layer isolation isn't fully testable
  at that level (vendor/wheels/tests/specs/wheelstest/BrowserTestBaseUrlResolutionSpec.cfc:28-43).
- Update browser-test guides (v4-0-0 + v4-0-1-snapshot L319) to recommend
  setting this.baseUrl in the component pseudo-constructor instead of
  beforeAll — super.beforeAll() calls $resolveBaseUrl() before a
  beforeAll-override can take effect, silently inheriting layer 2-6 results.
- Mirror the same ordering note in .ai/wheels/testing/browser-testing.md.

Signed-off-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>

---------

Signed-off-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>
Signed-off-by: Peter Amiri <peter@alurium.com>
Co-authored-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>
Co-authored-by: Peter Amiri <peter@alurium.com>

* fix(cli): make `wheels packages install` a real alias for `add` in dispatch (#2786)

* fix(cli): make `wheels packages install` a real alias for `add` in dispatch

The `case "install":` branch in `Module.cfc::packages()` previously printed
a warning to stdout and returned an empty string instead of installing
anything. That was wrong for every caller path that actually reaches
module dispatch — the stdio MCP server, scripted in-process clients, and
the spec suite — because `PackagesMainCli.install()` itself has been a
transparent alias for `add()` since #2729. The dispatch layer was the
only place where the alias broke.

The shell-facing `wheels packages install <name>` is still intercepted
by LuCLI's built-in extension installer upstream of module dispatch and
remains broken on that path (documented in the module-owned `--help`
text). This change only fixes the paths that LuCLI does NOT intercept.

Both verbs now share a single fall-through case body so validation,
error shape, and install behavior cannot drift apart again.

Fixes #2785

Signed-off-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>

* docs(web/guides): clarify install-as-alias behavior in packages CLI section

Signed-off-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>

* fix(cli): address Reviewer A/B consensus findings (round 1)

- PackagesCommandSpec: add `expect(installResult.type).toBe(addResult.type)`
  after the existing `.notToBe("")` assertion so the equivalence claim in
  the surrounding comment is actually enforced. A regression where
  `install` throws at argument validation (before the registry call)
  would have satisfied `.notToBe("")` but diverged from `add`'s shape;
  the new assertion pins it.
- CHANGELOG: terminal period on the new `[Unreleased] / ### Fixed`
  entry for consistency with surrounding entries.

Signed-off-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>

* fix(web/guides): address Reviewer A/B consensus findings (round 2)

- web/sites/guides/src/content/docs/v4-0-0/digging-deeper/packages.mdx
  (line 320) — scope the install-as-alias note to v4.0.1+. The previous
  wording asserted the alias was transparent on MCP / in-process paths,
  but that's only true after this PR (which targets v4.0.1). On v4.0.0
  itself, MCP also no-ops; the versioned v4.0.0 docs now say so
  explicitly and point readers to the v4.0.1 snapshot for the alias
  behavior. The v4-0-1-snapshot/ copy was already correct and is
  untouched.

Signed-off-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>

---------

Signed-off-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>
Signed-off-by: Peter Amiri <peter@alurium.com>
Co-authored-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>
Co-authored-by: Peter Amiri <peter@alurium.com>

* fix(model): quote column identifiers in SELECT clause builder (#2787)

* fix(model): quote column identifiers in SELECT clause builder

The WHERE and ORDER BY clause builders already routed column names
through the adapter's $quoteIdentifier, but $createSQLFieldList — the
SELECT/GROUP BY engine — appended the column part raw. Models backed
by tables with reserved-word column names (e.g. `key`, `order`,
`group`) blew up on `findAll`/`findOne`/dynamic finders with cryptic
SQL syntax errors as soon as the SELECT list mentioned the column.

Also strips quote chars from the property extracted by the
duplicate-column rename loop so the alias replacement still matches
the unquoted ` AS <alias>` form, and updates the empty-pagination
columnList extraction in read.cfc to strip identifier quotes before
stripping the table prefix.

Fixes #2784

Signed-off-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>

* docs(web/guides): note reserved-word column support via property alias in models guide

Signed-off-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>

* fix(model): address Reviewer A/B consensus findings (round 1)

- Condense 4-line block comments at vendor/wheels/model/read.cfc:217
  and vendor/wheels/model/sql.cfc:634 to single-line comments
  (CLAUDE.md: "Never write multi-paragraph docstrings or multi-line
  comment blocks — one short line max").
- Stop using $quoteColumn() for the table-name argument in
  vendor/wheels/tests/specs/model/reservedColumnQuotingSpec.cfc;
  switch to the model's public $quotedTableName() helper so the spec
  names match what each helper actually quotes.
- Add a zero-row paginated findAll spec to
  reservedColumnQuotingSpec.cfc that exercises the QueryNew branch in
  vendor/wheels/model/read.cfc:225 with an aliased column, covering
  the path the original spec did not reach.
- Mention ORDER BY alongside SELECT and GROUP BY in
  web/sites/guides/src/content/docs/v4-0-1-snapshot/basics/models-and-the-orm.mdx
  so readers do not infer ORDER BY is unsafe with reserved-word
  columns (ORDER BY already routes through $quoteIdentifier).

Signed-off-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>

* fix(model): address Reviewer A/B consensus findings (round 2)

Condense the remaining multi-line comment blocks in reservedColumnQuotingSpec.cfc
to single lines per CLAUDE.md ("Never write multi-paragraph docstrings or
multi-line comment blocks — one short line max"):

- vendor/wheels/tests/specs/model/reservedColumnQuotingSpec.cfc:10 — 3-line
  block about City's id -> countyid alias condensed.
- vendor/wheels/tests/specs/model/reservedColumnQuotingSpec.cfc:18 — 3-line
  block about Author.firstName (property == column) condensed.
- vendor/wheels/tests/specs/model/reservedColumnQuotingSpec.cfc:40 — 6-line
  block added in round 1 inside the zero-row pagination it() condensed to
  the single-line form Reviewer A supplied.

The line-30 GROUP BY comment was already single-line; A's "30-32" citation
was off-by-one for that one. No production code changed; pure comment-style
fix. Test totals unchanged at 4 pass / 0 fail in the spec; full model suite
remains 839 pass / 0 fail / 0 error / 11 skipped across 35 bundles.

Signed-off-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>

---------

Signed-off-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>
Signed-off-by: Peter Amiri <peter@alurium.com>
Co-authored-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>
Co-authored-by: Peter Amiri <peter@alurium.com>

* fix(test): auto-bind include-injected globals into WheelsTest spec scope (#2793)

* fix(test): auto-bind include-injected globals into WheelsTest spec scope

`WheelsTest`'s pseudo-constructor used `getMetaData(application.wo).functions`
to discover which Wheels globals to copy into a spec's `variables`/`this`
scope. That metadata enumerates only methods declared on the CFC body and
silently skips symbols merged in via `cfinclude` — which is how
`vendor/wheels/Global.cfc` pulls user helpers from `app/global/functions.cfm`.
Apps with custom helpers (`can()`, `hasRole()`, etc.) had to manually rebind
each one in `beforeAll()`.

The loop now iterates `application.wo` as a struct and binds every UDF
detected by `isCustomFunction()`, while preserving the existing
public-only filter for metadata-declared methods and the don't-clobber
guard for scope members the spec (or its base class) already provides.

Fixes #2790

Signed-off-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>

* fix(test): address Reviewer A/B consensus findings (round 1)

- Promote include-injected UDFs from `variables` to `this` in
  `vendor/wheels/Global.cfc` after `include "/app/global/functions.cfm"`,
  so the auto-bind loop in `vendor/wheels/WheelsTest.cfc` discovers them
  uniformly across Lucee, Adobe CF, and BoxLang. Lucee's struct-iteration
  over a CFC instance surfaces both `this` and `variables` scopes, but
  Adobe CF only reliably exposes `this`-scope members — without the
  promotion, the original bug (#2790) would silently persist on Adobe CF
  even with the new iteration path in WheelsTest.cfc.

- Fix the misleading header comment in
  `vendor/wheels/tests/specs/wheelstest/WheelsTestAutoBindIncludesSpec.cfc`.
  Bracket-notation assignment from outside writes to `this` scope, not
  `variables` — so the probe simulates the post-promotion shape, not the
  raw include shape. Comment now spells this out explicitly.

- Add a new `it` case that asserts the probe key is enumerated by
  `for (key in application.wo)`. Guards the iteration mechanism the
  auto-bind loop depends on, so failures on any engine where struct-
  iteration is narrower than expected would fail this spec rather than
  silently pass-but-not-test downstream.

Addresses Reviewer A's cross-engine concern (Adobe CF struct-iteration
contract) and Reviewer B's joint recommendation option (b): promote
include-injected helpers to `this` so the iteration path is uniform.
The accompanying spec correction handles A's "spec injects via wrong
scope" finding and B's "misleading header comment" note.

Signed-off-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>

* fix(test): seed `local` scope before pseudo-constructor for-iterator

The promotion loop added in round 1 of the consensus fixup crashed
Lucee 7 with `variable [local] doesn't exist` at Global.cfc:3861 —
the test runner couldn't even reach a spec before bailing out.

In a CFC pseudo-constructor (component body, not inside a function),
the `local` scope is not auto-created. Direct assignment to
`local.X = ...` will seed it, but `for (local.X in Y)` tries to read
`local` first as the iterator's target parent and fails. WheelsTest.cfc
gets away with the same loop shape only because it does
`local.metaIndex = {}` earlier in its own pseudo-constructor; Global.cfc
had no such seeding line.

Add the minimum seeding statement (`local.varKey = "";`) directly above
the loop and document the cross-engine reason inline. The loop's
filter logic is unchanged.

The original review couldn't catch this — the round-1 address-review
sandbox lacked a working test runner so the fix went out unverified.

Signed-off-by: Peter Amiri <peter@alurium.com>

---------

Signed-off-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>
Signed-off-by: Peter Amiri <peter@alurium.com>
Co-authored-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>
Co-authored-by: Peter Amiri <peter@alurium.com>

* fix(mapper): reject redundant namespace prefix in to= and controller= (#2794)

* fix(mapper): reject redundant namespace prefix in to= and controller=

Inside `.namespace("foo")` (or equivalent `.scope()` / `.package()`),
writing `to="foo/dashboard##index"` instead of `to="dashboard##index"`
silently produced a `foo.foo/dashboard` controller path that downstream
got flattened to a `Foodashboard`-style class lookup with an opaque
`Wheels.ViewNotFound` error — leaving users to chase the symptom rather
than the route definition.

`$match()` now detects when the parsed controller starts with the scope's
package converted to slash form and throws `Wheels.MapperArgumentInvalid`
at registration time. The error names the namespace and the offending
value and points at the correct shorter form.

Fixes #2791

Signed-off-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>

* fix(mapper): address Reviewer A/B consensus findings (round 1)

- Snapshot `local.fromTo` / `local.originalTo` before the `to=` parse
  block so the error detail can distinguish `to=` vs direct `controller=`
  callers (Reviewer A nit).
- Add `Len(arguments.package) > 0` to the guard's outer condition so an
  empty package does not yield `prefix = "/"` and spuriously reject
  controllers whose path starts with a slash (Reviewer A response,
  Reviewer B round-1 missed-issue).
- Collapse multi-line block comments above the guard in `matching.cfc`
  and above the new `it()` group in `MatchingSpec.cfc` to one-liners
  to comply with CLAUDE.md style (both reviewers).
- Add a spec asserting `$match()` with `package = ""` and a controller
  starting with `/` is not falsely rejected.

Signed-off-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>

* fix(mapper): address Reviewer A/B consensus findings (round 2)

- vendor/wheels/mapper/matching.cfc:328 — change local.hh = "##" to
  local.hh = "####" so the error-suggestion detail renders as
  to="dashboard##index" (source-correct CFML), not to="dashboard#index"
  (Reviewer A finding, Reviewer B verified).
- vendor/wheels/tests/specs/mapper/MatchingSpec.cfc:241–242 — collapse
  the 2-line comment inside the "Allows controllers..." spec body to a
  single line per CLAUDE.md "one short line max" rule (both reviewers).

Signed-off-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>

---------

Signed-off-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>
Signed-off-by: Peter Amiri <peter@alurium.com>
Co-authored-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>
Co-authored-by: Peter Amiri <peter@alurium.com>

* fix(events): re-include app/global/*.cfm on bare ?reload=true when files change (#2795)

* fix(events): re-include app/global/*.cfm on bare ?reload=true when files change

Adding a helper to `app/global/functions.cfm` (or anything it `<cfinclude>`s)
used to require the password-gated `?reload=true&password=...` path. Bare
`?reload=true` re-ran config and routes but left `application.wo` (the
`Global.cfc` instance) intact, so the symbols merged into its variables scope
at construction time stayed frozen — the page rendered without error and the
new helper was silently undefined.

The fix follows the Rails/Phoenix per-request mtime-check pattern recommended
by the research comment: snapshot `app/global/*.cfm` mtimes on application
start, and on bare `?reload=true` in development re-evaluate the include if
any tracked file has been added, removed, or touched. The password-gated
`applicationStop()` path still does a full re-init unchanged — this just
makes the muscle-memory path actually work.

Three new helpers on `wheels.Global`:

- `$snapshotGlobalIncludes(directory)` — struct of `path → dateLastModified`
- `$globalIncludesChanged(snapshot, directory)` — diff against current state
- `$reincludeGlobals(file)` — re-evaluate the include against the live
  Global instance

New setting `reloadOnGlobalChange` defaults to `true` in development and
`false` everywhere else; opt out with `set(reloadOnGlobalChange=false)`.

Fixes #2792

Signed-off-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>

* docs(web/guides): document reloadOnGlobalChange setting and bare reload behavior

Signed-off-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>

* fix(events): address Reviewer A/B consensus findings (round 1)

- Replace `DirectoryCreate(baseDir, true)` with `java.io.File.mkdirs()`
  in `reloadGlobalsSpec` — the createPath flag is Lucee-only and the
  call lives in beforeEach, so every spec in the group fails on Adobe CI.
- Assert `IsDefined("application.wo.fxReinclude")` after each
  `$reincludeGlobals` call so the contract (re-included helpers must
  remain callable on application.wo) is guarded against silent no-ops.
- Lift include-declared functions from local/variables onto this in
  `$reincludeGlobals` so the contract holds across engines: include
  inside a method body would otherwise leave declarations in scopes
  that aren't reachable via `application.wo.helper()`.
- Wrap the bare ?reload=true re-include in a double-checked
  `lock name="wheels_reload_globals"` to eliminate the race between
  two concurrent ?reload=true hits.
- Document the development-only environment guard as intentional so a
  future maintainer doesn't try to enable `reloadOnGlobalChange` in
  staging and debug a silent no-op.
- Add docblocks to `$globalIncludesChanged` and `$reincludeGlobals` so
  all three new global-includes helpers carry consistent documentation.

Signed-off-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>

* fix(events): address Reviewer A/B consensus findings (round 2)

- vendor/wheels/Global.cfc:$reincludeGlobals — drop the
  !ArrayFind(beforeVars, key) snapshot-diff guard from the second loop.
  On Adobe CF the include updates variables[key] in place across calls,
  so the guard silently skipped re-binding the updated function onto
  `this` on the second ?reload=true. Re-lifting is idempotent and the
  path is development-only.
- vendor/wheels/tests/specs/global/reloadGlobalsSpec.cfc:88 — replace
  the second IsDefined assertion with a return-value check so a stale
  Adobe-CF binding cannot slip past CI (expect(...fxReinclude()).toBe("second")).

Local verification on Lucee 7 + SQLite after server reload:
core suite 3698 pass / 0 fail / 0 error; global suite 113 pass / 0 fail
/ 0 error (the 7 reloadGlobals specs all green).

Signed-off-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>

* fix(test): address Reviewer A/B consensus findings (round 3)

- vendor/wheels/tests/specs/global/reloadGlobalsSpec.cfc — hoist
  `g` and `baseDir` out of the `describe()` arrow-function callback
  and into `run()` as a shared `ctx` struct, then update every
  beforeEach / afterEach / it closure to reference `ctx.g` and
  `ctx.baseDir`. On Adobe CF 2023/2025 CFML closures cannot reach
  an enclosing function's `local` scope (CLAUDE.md cross-engine
  invariant ##3); the prior layout silently relied on Lucee 7's
  lexical capture and would have thrown "variable baseDir is
  undefined" inside every nested closure on Adobe CI, crashing all
  seven specs.

Local verification on Lucee 7 + SQLite (existing test server,
forced ?reload=true&password=wheels first):
  global directory (wheels.tests.specs.global): 113 pass / 0 fail / 0 error
  full core suite:                              3698 pass / 0 fail / 0 error

Lucee was already green before this fix because it captures the
enclosing arrow-function `local`; the change is to make the Adobe
CI legs match. Adobe verification is left to CI as the local
harness cannot run Adobe.

Signed-off-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>

* fix: address Reviewer A/B consensus findings (round 4)

- web/sites/guides/src/content/docs/v4-0-0/command-line-tools/wheels-commands/dev-server.mdx — tighten the bare `?reload=true` note so it mentions `app/global/functions.cfm` (and any files it `<cfinclude>`s) instead of the looser `app/global/*.cfm`. `$globalIncludesChanged` watches every `*.cfm` under `app/global/` but `$reincludeGlobals` re-evaluates only `functions.cfm` and the files it transitively includes; the previous wording implied a developer could drop a standalone helper file directly and have it bind, which isn't true. Matches the more accurate wording already in `core-concepts/environments-and-configuration.mdx`.
- web/sites/guides/src/content/docs/v4-0-1-snapshot/command-line-tools/wheels-commands/dev-server.mdx — same wording change for the v4-0-1 snapshot copy, keeping the two doc trees in sync.
- vendor/wheels/tests/specs/global/reloadGlobalsSpec.cfc — drop the dead `mappingPath` local variable; it was only used to compute `absPath`, and the `$reincludeGlobals` calls inside the `notThrows` closures already repeat the path literally (closures can't reach the enclosing `local.mappingPath` on Adobe CF anyway). Inlines the string into `ExpandPath()` directly.

Local verification on Lucee 7 + SQLite:
  global directory (wheels.tests.specs.global): 113 pass / 0 fail / 0 error
  reloadGlobalsSpec only:                       7 pass / 0 fail / 0 error

Signed-off-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>

* fix(events): address Reviewer A/B consensus findings (round 5)

- vendor/wheels/tests/specs/global/reloadGlobalsSpec.cfc — add a test
  for the DateCompare != 0 branch in $globalIncludesChanged, the
  "developer edited an existing helper" path the PR is designed to
  serve. Uses the backdated-snapshot approach from Reviewer A's
  response (DateAdd seconds -60 on the snapshot entry) rather than
  Sleep(1100), so the test is deterministic across filesystems with
  different mtime granularities.
- vendor/wheels/events/EventMethods.cfc — append application name to
  the wheels_reload_globals lock so concurrent ?reload=true hits from
  different apps on a shared Adobe CF server no longer serialize on a
  single global lock. Development-only and uncommon in practice, but
  the fix is a one-liner.

Signed-off-by: Peter Amiri <peter@alurium.com>

* docs: tighten CHANGELOG entry to distinguish detection from re-evaluation scope

- CHANGELOG.md — round-5 Reviewer A nit. Opening clause said "re-includes
  app/global/*.cfm" which overstates the re-evaluation scope: detection
  is broad (every *.cfm under app/global/) but $reincludeGlobals only
  re-evaluates functions.cfm and the files it transitively <cfinclude>s.
  Rewording matches the round-4 dev-server.mdx tightening.

Signed-off-by: Peter Amiri <peter@alurium.com>

---------

Signed-off-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>
Signed-off-by: Peter Amiri <peter@alurium.com>
Co-authored-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>
Co-authored-by: Peter Amiri <peter@alurium.com>

* fix(test): keep test-local.sh from silently dying on missing ~/.lucli/express (#2796)

Under `set -euo pipefail`, `find ~/.wheels/express ~/.lucli/express ...`
exits non-zero whenever any path arg is missing (stderr suppressed via
`2>/dev/null`, but the exit status survives), `pipefail` propagates it
through `head -1`, and the command-substitution assignment trips `set -e`.
The cleanup trap then fires with no server to clean up, so the user sees
"Starting Wheels CLI server on port 8080..." with EXIT=1 and no
`/tmp/wheels-test-server.log` produced — broken for every install since
the lucli→wheels rebrand window closed and `~/.lucli/express/` stopped
being created.

Drop the now-dead `~/.lucli/express` fallback (the rename landed in 3.0
and recent CLI releases extract Lucee Express to `~/.wheels/express/`
only) and add `|| true` for defense in depth so a truly fresh install
(before `wheels start` has ever run) leaves `LUCEE_LIB` empty and the
downstream `[ -n "\$LUCEE_LIB" ]` guard skips the JDBC pre-install
cleanly.

Verified: `bash tools/test-local.sh wheels.tests.specs.wheelstest` now
runs the server, produces `/tmp/wheels-test-server.log`, and passes all
137 specs across 38 suites in ~17s.

Signed-off-by: Peter Amiri <peter@alurium.com>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* ci: allow-list APPROVED + CHANGES_REQUESTED in Reviewer A guard (#2797)

* fix(ci): skip COMMENTED reviews in Reviewer A guard

The post-submission guard in bot-review-a.yml scans for "bogus" wheels-bot
reviews on the head SHA and dismisses any with a body shorter than 200
chars or missing the canonical `wheels-bot:review-a` marker. GitHub's
dismiss API only accepts APPROVED or CHANGES_REQUESTED reviews; passing a
COMMENTED review id returns HTTP 422 ("Can not dismiss a commented pull
request review") and crashes the step, red-X'ing the Reviewer A check
even when A's real substantive review landed cleanly seconds earlier.

wheels-bot itself occasionally posts placeholder COMMENTED reviews mid-
cycle as it probes the `gh pr review` CLI before issuing the real one
(observed bodies: "placeholder test - ignore", "placeholder2 - updating",
"test with dollar sign: see \$reincludeGlobals function"). Those leak out
as public COMMENTED reviews, which is what the guard is meant to clean
up — but it can't dismiss them via this API, so it has to skip them.

Add `select(.state != "COMMENTED")` to the jq pipeline that selects
actionable reviews. COMMENTED reviews don't gate merging anyway — only
APPROVED and CHANGES_REQUESTED do — so leaving them in PR history is
acceptable noise. The guard now only acts on what it can actually
dismiss.

Observed on PR #2795 commit 0db188a5a5d27cd80b58939df5e0c8dd7464a00b,
job run 26296842347.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Signed-off-by: Peter Amiri <peter@alurium.com>

* ci: allow-list APPROVED + CHANGES_REQUESTED in Reviewer A guard

Tighten the previous COMMENTED-state filter to an explicit allow-list:
APPROVED and CHANGES_REQUESTED are the only review states that (a)
GitHub's dismiss API accepts and (b) gate merging. Switching from
"!= DISMISSED && != COMMENTED" to "state IN (APPROVED, CHANGES_REQUESTED)"
also covers PENDING reviews, which return the same HTTP 422 from the
dismiss endpoint if they ever land on a head SHA.

Follow-up to bd76e53de4 per Reviewer A's allow-list suggestion on #2797.
Reviewer B confirmed PENDING is reachable and the closed-set form is
strictly safer than the deny-list. No behavioral change for the
COMMENTED case fixed in bd76e53de4 — that state is still excluded.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Signed-off-by: Peter Amiri <peter@alurium.com>

---------

Signed-off-by: Peter Amiri <peter@alurium.com>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(migrator): handle orphan versions in shared dev databases (#2780) (#2798)

* fix(migrator): handle orphan versions in shared dev databases (#2780)

When wheels_migrator_versions records a version whose migration file is
not in the current checkout (shared dev DB / peer applied a migration
whose file isn't yet in this branch), wheels migrate latest no longer
takes a misleading "down" branch and silently no-ops.

Changes:

* Migrator.$getOrphanVersions() — diffs the tracking table against on-
  disk files and returns versions with no matching file, sorted ascending.

* Migrator.migrateTo() — branches on "orphan-at-top" before the existing
  direction check. When every DB version above target is an orphan: emits
  a warning naming the orphans, then either applies pending local files
  (up branch) or prints a clear "Nothing to do" naming current vs target.
  When SOME above-target versions are legitimate down candidates and
  SOME are orphans, emits the warning but lets the existing down loop
  handle the rest (orphan rows skip naturally because the loop iterates
  files only).

* Migrator.\$buildInfoOutput() — extracted info rendering so it is unit-
  testable without the HTTP dispatcher. Orphan rows render with a [?]
  marker and the literal "********** NO FILE **********" (Rails-style),
  with a footer explaining the cause.

* public/views/cli.cfm info handler — delegates to \$buildInfoOutput().

* New spec OrphanDetectionSpec covers \$getOrphanVersions + the
  directional fix across five scenarios (clean state, single orphan,
  multiple orphans, nothing-to-do path, legitimate down still works).

* New spec MigratorInfoSpec covers \$buildInfoOutput rendering.

* Docs: new guides page at basics/shared-development-databases.mdx
  walks through what an orphan is, three resolution paths, and the
  recommendation to avoid shared dev DBs. AI-side reference at
  .ai/wheels/troubleshooting/shared-dev-databases.md.

Note on local verification: a leaked JVM from another worktree is
holding Tomcat's shutdown port (8081), blocking new wheels server
starts on this machine. Tests are queued for CI to run across the full
engine + DB matrix. Local TDD will run on next machine restart.

Refs #2780

Signed-off-by: Peter Amiri <peter@alurium.com>

* fix(migrator): address Reviewer A/B consensus findings (round 1)

- Reword "Your latest local migration" to "Your target version" in the
  orphan nothing-to-do message. arguments.version is the target, not
  necessarily the latest local file (Migrator.cfc).
- Add mixed-case OrphanDetectionSpec covering orphan + legitimate down
  candidate above target: warning names the orphan, down branch still
  runs, c_o_r_e_dropbears is dropped after rollback.
- Drop docs/superpowers/plans/2026-05-22-orphan-migration-detection.md
  (1053-line agentic plan duplicated in PR body / commit message).
- Add CHANGELOG entry under [Unreleased] Fixed describing the orphan
  detection, three migrateTo branches, and the [?] info row.

Non-blocking items left for follow-up: double getVersionsPreviouslyMigrated()
fetch in migrateTo() (B disputed scope but underlying concern is valid),
and the deferred local test-local.sh migrator run (sandbox lacks the
wheels CLI binary; compat-matrix CI will validate on the new SHA).

Refs #2780, #2798

Signed-off-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>

* docs(migrator): fix stale plan reference in shared-dev-databases.md

The 1053-line agentic plan file at
docs/superpowers/plans/2026-05-22-orphan-migration-detection.md was
deleted in commit ddac9690 per Reviewer A/B convergence, but the
AI-side reference doc still pointed to it.

Replaced the dead link with a PR reference and tightened the
follow-up section to describe the work in prose instead of pointing
at plan files that may or may not exist.

Round-2 Reviewer A nit.

Refs #2780, #2798

Signed-off-by: Peter Amiri <peter@alurium.com>

---------

Signed-off-by: Peter Amiri <peter@alurium.com>
Signed-off-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>
Co-authored-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>

* feat(migrator): doctor/forget/pretend reconciliation commands (#2780) (#2799)

* feat(migrator): doctor/forget/pretend reconciliation commands (#2780)

Follow-up to #2798. Adds three new `wheels migrate` subcommands for
manual reconciliation against the tracking table — the Flyway
`validate` / `repair` / `SkipExecutingMigrations` analogues for
Wheels.

* `wheels migrate doctor` — single-command health report. Lists
  orphans, pending local migrations, and applied count. Pure read;
  never mutates. Built on Plan 1's `$getOrphanVersions()`.

* `wheels migrate forget <version> --yes` — removes a single row
  from `wheels_migrator_versions` without running `down()`. Refuses
  if the version has a matching local file (use `migrate down`
  instead) or if the version isn't in the table. Idempotent.

* `wheels migrate pretend <version> --yes` — inserts a row into
  `wheels_migrator_versions` without running `up()`. Refuses if
  already applied or if no local file matches.

Both `forget` and `pretend` require explicit `--yes` to mutate;
without it they print what would happen and exit. The CLI side wires
through a new `runForgetOrPretend()` helper that handles the gating;
the HTTP dispatcher in `cli.cfm` reads the version from
`request.wheels.params.version`.

New spec `MigratorReconciliationSpec.cfc` covers ~12 scenarios
across the three methods: clean state, unhealthy with orphans,
unhealthy with pending, refusal paths, and the no-mutation guarantee
for invalid inputs.

Docs: extended `basics/shared-development-databases.mdx` with the
new commands (Option 2 reworked, Option 2b added, "Comprehensive
diagnostic" section added). AI-side reference and CHANGELOG entry
follow the same shape.

Note on local verification: a leaked JVM from another worktree
continues to hold Tomcat's shutdown port (8081); CI compat-matrix
will validate across the full engine + DB matrix.

Refs #2780, #2798

Signed-off-by: Peter Amiri <peter@alurium.com>

* fix(migrator): address Reviewer A round-1 findings on #2799

- forgetVersion() now delegates to the existing private
  $removeVersionAsMigrated() helper instead of running an inline
  DELETE. The helper wraps the DELETE in the same request.$wheelsDebugSQL
  guard that $setVersionAsMigrated() uses, so forgetVersion() and
  pretendVersion() are now symmetric: both are no-ops in debug-mode
  request contexts instead of silently corrupting the tracking table.

- runForgetOrPretend() now wraps the version argument with
  URLEncodedFormat() when building the reconcile URL. $sanitiseVersion()
  on the server side strips non-digits before SQL use (no SQL injection
  path), but raw URL-special characters (&, =, %) in the CLI argument
  could inject spurious query parameters before the sanitiser ran.

Both items were flagged by Reviewer A on commit b7817459b. No new tests
needed: existing MigratorReconciliationSpec covers the success and
refusal paths for forgetVersion(), and the URL-encoding fix is on the
CLI client side which is not exercised by core unit tests.

Refs #2780, #2799

Signed-off-by: Peter Amiri <peter@alurium.com>

* fix(cli): doctor output prints yellow when migrator is unhealthy

Reviewer A flagged that runMigration("doctor") always printed in green
regardless of the report's healthy flag. Green on an unhealthy result
(orphans or pending migrations present) reads as "everything is fine"
when actually attention is needed.

The fix switches color to yellow when:
  - action == "doctor"
  - response includes a `healthy` key
  - healthy is false

Other actions (latest/up/down/info) stay green on success — they
either succeed or throw, so the binary mapping holds. Only `doctor`
returns a structural "succeeded but unhealthy" state.

Non-blocking per A's COMMENTED verdict, but a real UX improvement.

Refs #2780, #2799

Signed-off-by: Peter Amiri <peter@alurium.com>

* docs: cross-reference doctor/forget/pretend in main migration docs

The cumulative state of #2798 (merged) and #2799 (this PR) added
three new migrate subcommands plus the [?] orphan display in
`migrate info`. PR-scope docs already covered the deep-dive page
at basics/shared-development-databases.mdx, but the main migrations
reference still said "four subcommands". Catching up:

- basics/migrations.mdx now lists seven subcommands and points to
  shared-development-databases for the reconciliation deep dive.
  The `info` description mentions the [?] orphan row format.

- CLAUDE.md's MCP/CLI table row now lists `doctor` under
  wheels_migrate and adds a separate "Migrator reconciliation"
  row for forget/pretend.

- CLAUDE.md's Migrations & Seeding section gains a "Shared Dev
  DB Reconciliation" subsection summarising the new commands and
  pointing at the deep-dive docs.

- CLAUDE.md's Reference Docs section adds the
  .ai/wheels/troubleshooting/shared-dev-databases.md link.

Refs #2780, #2798, #2799

Signed-off-by: Peter Amiri <peter@alurium.com>

* docs: replace stale schema_migrations references with wheels_migrator_versions

Three carryover Rails table-name references in basics/migrations.mdx
(lines 28, 36, 59) predate the c_o_r_e_* → wheels_* rename and don't
match any code in vendor/wheels/, cli/, or app/. Reviewer A flagged
them on PR 2799 round-4 review (f663b5a55) as worth fixing since the
file was already being touched; the surrounding edits in this PR
already use the correct `wheels_migrator_versions` name (line 46).

Other stale references in basics/seeding.mdx and the
v4-0-1-snapshot/ copies are out of scope for this PR; left for a
follow-up cleanup.

Refs #2780, #2799

Signed-off-by: Peter Amiri <peter@alurium.com>

---------

Signed-off-by: Peter Amiri <peter@alurium.com>

* feat(migrator): enrich wheels_migrator_versions with name + applied_at (#2780) (#2800)

* feat(migrator): enrich wheels_migrator_versions with name + applied_at (#2780)

Final follow-up to #2798 + #2799. Adds two nullable columns to the
tracking table so `wheels migrate info` and `wheels migrate doctor`
can show *what* a peer applied and *when* — even for orphan rows
whose migration file isn't in the local checkout.

## Schema change

- `wheels_migrator_versions.name VARCHAR(255) NULL` — migration name
  derived from filename (e.g. `create_users`)
- `wheels_migrator_versions.applied_at TIMESTAMP NULL DEFAULT
  CURRENT_TIMESTAMP` — when the migration was applied. SQLite gets
  TEXT with CFML-side `Now()` injection on insert because SQLite
  can't DEFAULT a column on ADD COLUMN.

Both nullable, additive, backward compatible. Existing rows
(pre-enrichment) stay NULL and display version-only in the info
output. Going-forward-only — no backfill.

## Bootstrap

`Migrator.$ensureTrackingColumns()` probes via `$dbinfo` and ALTERs
the table per-engine when columns are missing. Idempotent (skip
when already present). Per-engine SQL covers MySQL, PostgreSQL,
SQLite, MSSQL, Oracle, H2, and CockroachDB — same pattern as the
existing `renameSystemTables()` machinery at Migrator.cfc:932.

Wrapped by `$maybeEnsureTrackingColumns(appKey)` which caches on
`application[appKey].$trackingColumnsEnsured` so the ALTER runs
once per app process, not on every migrator call. Non-fatal: if
the ALTER fails (locked table, weird permissions), the flag stays
unset and the legacy schema continues to work.

Called from `$getVersionsPreviouslyMigrated()` after both the
existing-table happy path and the bootstrap-creates-table path.

## Population

`$setVersionAsMigrated(version, migrationName)` gains an optional
`migrationName` arg. When non-empty AND the enriched-columns flag
is set, includes `name` (and on SQLite, `applied_at`) in the
INSERT. Other engines rely on the column's CURRENT_TIMESTAMP
default for `applied_at`.

Callers updated to pass the name: both up-loops in `migrateTo()`,
`migrateIndividual()`, and `pretendVersion()` (captures the
migration's name from `getAvailableMigrations()` during the
local-file existence check).

## Display

`$getOrphanVersionsWithMeta()` — new public helper. Returns
`{version, name, appliedAt}` structs for each orphan. Falls back
to bare structs when columns aren't ensured or the SELECT fails.

`$buildInfoOutput()` and `cli.cfm`'s `doctor` case now render
`[?] <version> <name> (applied <timestamp>)` when populated, with
the legacy `[?] <version> ********** NO FILE **********` fallback
for legacy NULL orphans.

`doctor()` adds `orphansWithMeta` to its result struct alongside
the existing `orphans: array of strings` (kept for
backward-compat with `migrateTo()`'s direction logic).

## Docs

- `web/sites/guides/.../basics/shared-development-databases.mdx`:
  updated `info` sample output to show the enriched format + a
  note explaining the legacy fallback.
- `.ai/wheels/troubleshooting/shared-dev-databases.md`: new
  "Schema enrichment" section documenting the helpers and behavior.
- `CLAUDE.md`: updated the `info` format line and added the
  tracking-table schema summary in the Shared Dev DB Reconciliation
  subsection.
- `CHANGELOG.md`: entry under `[Unreleased] Changed`.

## Tests

`SchemaEnrichmentSpec.cfc` covers three scenarios:
- $ensureTrackingColumns adds both columns on first call
- Idempotent re-run (added=[])
- Name column populated for newly applied migrations

Existing specs (migratorSpec, OrphanDetectionSpec, MigratorInfoSpec,
MigratorReconciliationSpec) all preserve backward compat — the new
name column is opt-in (only written when caller passes it), and
the new display logic falls back to legacy rendering for NULL
metadata.

## Known follow-ups (non-blocking, separate PRs)

- Double `$getVersionsPreviouslyMigrated()` fetch carry-over from
  reviewer notes on #2798 and #2799 — still pending. This PR
  doesn't worsen the situation; the cached `$trackingColumnsEnsured`
  flag means `$ensureTrackingColumns` only probes columns once per
  process.

Refs #2780, #2798, #2799

Signed-off-by: Peter Amiri <peter@alurium.com>

* fix(migrator): don't call \$dbinfo inside $setVersionAsMigrated transaction

CI on Lucee 7 + SQLite revealed two correctness bugs in #2800:

1. \$setVersionAsMigrated called \$dbinfo(type="version") to detect
   SQLite-vs-other-engines before deciding whether to include applied_at
   in the INSERT. But \$setVersionAsMigrated runs INSIDE migrateTo's
   open JDBC transaction, and SQLite (and possibly other engines under
   concurrent load) can't service JDBC metadata calls inside an open
   transaction. Result: [SQLITE_ERROR] SQL error or missing database,
   the migration's transaction rolled back, and every test that
   applied a migration with the enriched schema active failed.

   Fix: cache the engine type on application[appKey].\$migratorDbType
   in \$ensureTrackingColumns() (which always runs outside transactions),
   then read it from the cache in \$setVersionAsMigrated(). No more
   \$dbinfo calls during inserts.

2. \$maybeEnsureTrackingColumns set the \$trackingColumnsEnsured cache
   flag whenever \$ensureTrackingColumns() didn't throw — even when
   the column probe failed (e.g. table didn't exist yet) and no
   ALTERs ran. Subsequent \$setVersionAsMigrated calls then saw the
   flag set and tried to INSERT with a `name` column that didn't
   actually exist on the table → SQL error → rolled back transaction.

   Fix: only set the cache flag when BOTH rv.hasName and rv.hasAppliedAt
   are true after \$ensureTrackingColumns() returns. Failures, missing
   tables, or partial-ALTER states leave the flag unset so subsequent
   calls retry.

Together these failures broke six specs across migratorSpec,
OrphanDetectionSpec, and SchemaEnrichmentSpec — all symptoms of the
same two root causes. With the fix in place, \$setVersionAsMigrated
is back to a single $query call with no metadata interrogation, and
the enriched-INSERT path only fires when the schema is genuinely
confirmed.

Refs #2780, #2798, #2799, #2800

Signed-off-by: Peter Amiri <peter@alurium.com>

* fix(migrator): address Reviewer A round-1 findings on #2800

C1 (correctness): The shared-dev-databases guide example showed
"(applied ...)" timestamps on [x] rows, but the code in
$buildInfoOutput only populates appliedAt for orphan rows (the
DB isn't re-queried for applied_at on local-file rows). Aligning
the guide example with what the code outputs — keep the timestamp
display on the [?] orphan row where the schema enrichment actually
shows through, drop it from the [x] rows. Surrounding prose already
correctly scopes the enrichment to orphans.

T1 (test quality): SchemaEnrichmentSpec's "populates the name column"
test used expect(Len(rows.name) > 0).toBeTrue() which collapses to
a boolean before the matcher sees it — on failure the error message
is just "Expected [false] to be [true]" with no hint of the actual
value. Replaced with expect(rows.name).notToBeEmpty() so failures
include the actual name (or absence of one).

T2 (coverage): Added a new "populates applied_at for newly applied
migrations" spec that queries the applied_at value and asserts it
parses as a date. Covers both code paths: the column-DEFAULT
CURRENT_TIMESTAMP that fires on MySQL/Postgres/MSSQL/Oracle/H2 AND
the CFML-side Now() that SQLite needs because it can't DEFAULT a
TIMESTAMP on ADD COLUMN.

T3 (lint): Added a comment block above the describe block
explaining why CockroachDB is skipped — mirrors the existing
pattern in migratorSpec, OrphanDetectionSpec, and MigratorInfoSpec
(numeric-version test fixtures don't run cleanly against CockroachDB;
compat-matrix.yml treats CockroachDB as soft-fail). The guard is
intentional, not vestigial.

Also clearing the new $migratorDbType app-scope cache in the
beforeEach/afterEach alongside the existing $trackingColumnsEnsured
cleanup, so each test starts from a clean state.

A's performance note about $dbinfo in $setVersionAsMigrated is
already addressed in commit bb4bd761b (caches the engine type on
$migratorDbType to avoid the per-insert metadata round-trip). A
was reviewing 695f8300c and hadn't seen that commit yet.

Refs #2780, #2800

Signed-off-by: Peter Amiri <peter@alurium.com>

* docs: correct stale [x] timestamp claim in .ai schema-enrichment ref

Reviewer B's round-1 convergence on #2800 caught a missed-by-A
follow-on of the C1 finding: the .ai/wheels/troubleshooting/
shared-dev-databases.md doc's first display bullet read

  - `[x] <version> <name> (applied <timestamp>)` when populated

but the code only renders the (applied ...) suffix on orphan rows.
The MDX guide example was corrected in fdbbedc35; this commit
brings the .ai-side reference in line and adds a sentence explaining
why $buildInfoOutput doesn't show applied_at for [x] rows (it would
require re-querying the tracking table for every getAvailableMigrations
result, which is a bigger change than this PR is taking on).

Refs #2780, #2800

Signed-off-by: Peter Amiri <peter@alurium.com>

* fix(migrator): populate \$migratorDbType cache before early-return (#2800 C2)

Reviewer A round-2 caught a latent bug in \$ensureTrackingColumns:
the early-return when both enriched columns are already present
fired BEFORE the \$migratorDbType cache was populated. The cache is
on application scope, so it gets cleared on every app restart /
?reload=true. On the second app start onward, the early-return
fired, \$migratorDbType stayed empty, and \$setVersionAsMigrated's
SQLite branch (which writes an explicit applied_at via CFML Now()
becau…
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

wheels packages install still no-ops in CLI 4.0.1 — fix from #2610/#2706/#2713 didn't land or regressed

1 participant