Merge pull request #3387 from wheels-dev/release/4.0.6-to-main

Release 4.0.6

Merge pull request #3228 from wheels-dev/release/4.0.5-to-main

Release 4.0.5

Merge pull request #3220 from wheels-dev/release/4.0.4-to-main

Release 4.0.4

Merge pull request #2892 from wheels-dev/release/4.0.3-to-main

Release 4.0.3

ci(release): force Node 24 for JS actions + add workflow_dispatch (#2820

)

The 4.0.2 release push (#2819) failed before any step ran: the pre-hooks of
Wandalen/wretry.action@v3 -- the lone Node 20 action in the job, wrapping
softprops/action-gh-release -- threw "Argument list too long" spawning the
node20 binary. Root cause is GitHub's forced Node 20 -> 24 runner migration
(forced default 2026-06-02), not workflow config: run #2769 (4.0.1) passed
7 days earlier with the identical setup, and the develop snapshot path (same
action) succeeded 16 min before on a pre-migration runner.

- Set FORCE_JAVASCRIPT_ACTIONS_TO_NODE24=true at workflow level so all JS
  actions (including wretry@v3) run on Node 24, bypassing the broken node20
  launch path. This is GitHub's documented remedy for the transition.
- Add a workflow_dispatch trigger so a stuck/failed release can be re-fired
  from the Actions tab without a fresh push. Channel selection keys on
  GITHUB_REF: dispatch against main -> stable, develop -> snapshot.

Merging to main re-fires release.yml and completes the v4.0.2 release; prior
failed attempts created no tag/release, so there is no double-publish risk.

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

chore(release): prep CHANGELOG for v4.0.1 GA (#2768)

Promote `## [Unreleased]` to `# [4.0.1] => 2026-05-20` so `release.yml`'s
release-checklist step (which refuses to publish on `=> TBD`) and its
`awk '/^# \[VERSION\]/,/^---$/'` release-notes extraction both pick up
the section.

Change the section terminator from `----` (4 dashes) to `---` (3 dashes)
— mirrors the same fix shipped in #2606 for the 4.0.0 cut. The awk range
in `release.yml` matches only `^---$`, so a 4-dash terminator would let
the extraction bleed into 4.0.0's notes.

`wheels.json` is already at `4.0.1` (auto-bumped by
`bump-develop-version.yml` after the 4.0.0 GA), so no version bump is
needed here.

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

chore: prep CHANGELOG for v4.0.0 GA (#2606)

* chore: prep CHANGELOG for v4.0.0 GA

- Promote [Unreleased] heading to # [4.0.0] with GitHub release link and
  date 2026-05-11 (replace `=> TBD` so release.yml validation passes).
- Update PR count (185 → 260+) and contributor list (+ @MukundaKatta) to
  match docs/releases/wheels-4.0-audit.md.
- Add new "Distribution" subsection under Added — captures the four
  install channels (Homebrew, Scoop, .deb/.rpm, WinGet drafts) that
  landed in 4.0 but weren't itemized in the changelog.
- Fix the section terminator after 4.0.0's notes from `----` (4 dashes)
  to `---` (3 dashes) so release.yml's release-notes awk extraction
  (`awk '/^# \[VERSION\]/,/^---$/'`) terminates at the right boundary
  instead of running into the 3.0.0 entry.

wheels.json is already at "4.0.0" (no snapshot suffix), so the
release.yml clean-source-version check passes. First-party packages all
declare wheelsVersion >=4.0 so no coordination updates are needed.

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

* docs(changelog): add Fixed entry for #2603 Scoop pre_install fix

Captures the user-visible impact ("scoop install fails with Can't shim
wheels.cmd") and the actual fix (move launcher emit from post_install to
pre_install, where Scoop's install order requires it). Already merged on
develop as commit e7445bc; this just makes sure the GA changelog
reflects it under v4.0.0's Fixed section.

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

* docs(changelog): address Reviewer A/B consensus findings (round 1)

- Fix Homebrew tap link text from `wheels-dev/wheels` to
  `wheels-dev/homebrew-wheels` so the visible repo name matches the
  URL target (CHANGELOG.md:104).
- Bump the 4.0.0 release date marker from `2026-05-11` to
  `2026-05-12` so it reflects today's tag day (CHANGELOG.md:21).

Not addressed in this commit:
- Missing `Signed-off-by:` trailers on `bff31f981` and `d971cde8e`.
  Adding them requires `git commit --amend -s` (or interactive
  rebase) plus a force-push, both of which the wheels-bot rails
  forbid. Flagged to the human in the address-review comment so a
  maintainer can amend the trailer chain before the FF-merge to main.

Signed-off-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>
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 Opus 4.7 (1M context) <noreply@anthropic.com>
Co-authored-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>

docs: rename user-facing lucli references to wheels in CLAUDE.md, tes…

…t-local, guides (#2544)

Wheels is built on the LuCLI runtime, but the rebranded `wheels` binary
is the only thing end users install. The codebase still has historical
mentions of `lucli` as the user-facing command — left over from the
period when the project was migrating off CommandBox onto LuCLI. The
mismatch confused at least one Claude Code session: a recent agent
followed `tools/test-local.sh`'s "brew install lucli" docstring instead
of using the `wheels` command that was actually on PATH, then concluded
LuCLI was uninstallable and gave up running the test suite locally.

Surgical scope, not a blanket find-and-replace:
- CLAUDE.md gets an explicit "wheels IS the CLI" callout in the testing
  section so future sessions don't repeat the mistake. Updated install
  instructions to recommend `brew install wheels`, `wheels server run`,
  `~/.wheels/express`.
- tools/test-local.sh switches `lucli` → `wheels` for command
  invocations and prerequisites; falls back to scanning both
  `~/.wheels/express` and `~/.lucli/express` for the JDBC lib so the
  script keeps working through the rename for older installs.
- web/sites/guides/.../testing/browser-tests.mdx and
  running-tests-locally.mdx fix the user-facing "brew install lucli"
  and `lucli server run` directions.
- CHANGELOG entry under [Unreleased] / Changed.

References to LuCLI as the upstream runtime project (installation docs
that explain how the rebrand works, runtime-specific env vars like
`LUCLI_HOME`, dotted CFC paths like `cli.lucli.services.X`, filesystem
paths under `cli/lucli/`, framework-dev tooling that genuinely tests
the LuCLI module distribution flow) are intentionally retained — they
are accurate context, not user instructions.

Closes the loose end from PR #2543's review thread.

fix: ship registry reader with framework so Tools→Packages works in f…

…resh apps (#2543)

* fix: ship registry reader with framework so Tools→Packages works in fresh apps

The debug bar's Tools→Packages link (and the standalone packagelist
page it opens) silently rendered an empty registry list in apps
generated with `wheels new`. Public.$loadRegistryPackages gated on
FileExists("/cli/lucli/services/packages/Registry.cfc") — that path
only exists in the framework dev repo. User apps ship vendor/wheels/
without cli/, so the gate always returned an empty array.

Move the registry reader into the framework at
vendor/wheels/services/packages/{Registry,HttpClient,ManifestCache}.cfc
so it ships with every generated app. Public.cfc now instantiates the
bundled component directly and the file-existence gate is gone.

Keep the registry list scoped to the standalone Tools→Packages page —
the inline Environment > Packages section now shows installed packages
only, so the debug bar stays compact and we don't trigger a registry
walk on every dev-mode page load. The CLI keeps its own copies under
cli/lucli/services/packages/; both contexts have their own classpath
mappings (modules.wheels.* vs wheels.*) and dedup is left for a
follow-up.

Issue #2530.

* fix: validate versions array in Registry.fetchManifest before listAll() reads it

Address PR #2543 reviewer A. listAll() reads
local.m.versions[ArrayLen(local.m.versions)] without first checking
that the .versions key exists, is an array, and is non-empty. The
existing manifest validation only checked for .name. A registry entry
that passed the .name check but lacked .versions would crash with an
Expression-level "element VERSIONS is undefined" error — bypassing
both the per-package RegistryMalformed skip in listAll() and the
three typed catches in Public.$loadRegistryPackages, surfacing as an
unhandled stack trace on the Tools → Packages page.

Validate the .versions invariant in fetchManifest so cached and
fresh manifests share one guard, and the per-package skip
catches a typed throw. Mirrored into the CLI's Registry.cfc to
keep both copies in sync per the in-file note.

New RegistryFetchManifestSpec exercises the framework Registry with
a fake HttpClient — covers missing key, non-array, empty array, and
the listAll() end-to-end skip path. Adds wheels.tests._assets.packages.FakeHttpClient
trimmed to the framework HttpClient surface (no download()).

CHANGELOG entry for #2530 also rewritten to match the final UX
(registry list scoped to the standalone Tools → Packages page only)
and a new entry added for the validation fix.

* fix: validate cached manifests on read so stale on-disk entries can't crash listAll

Address PR #2543 reviewer B follow-up. The previous fix only validated
manifests on the fresh-fetch path before writing to cache. The
cache-hit path in fetchManifest returned the on-disk entry without
revalidating, so a manifest written by an older Registry version that
didn't enforce the versions invariant could still crash listAll() with
an Expression-level error.

Extract the manifest contract assertion into $validateManifest() and
call it from both the cache-hit and fresh-fetch paths. Mirrored into
the CLI's Registry.cfc to keep both copies in sync.

New spec case writes a stale-bad manifest to the cache directly, marks
it fresh, then verifies fetchManifest re-validates on read instead of
returning the stale entry.

docs(web/guides): clarify box CLI vs wheels CLI in v4 active docs (#2542

)

* docs(web/guides): clarify box CLI vs wheels CLI in v4 active docs

Add Aside to BoxLang section of cfml-engines guide explaining that
`wheels start` boots the bundled Lucee Express and CommandBox is
required for BoxLang server management. Update vm-deployment tip to
remove confusing CI/Docker reference and explicitly distinguish
CommandBox server management from the `wheels` dev CLI.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs(web/guides): align BoxLang aside with Adobe CF aside in cfml-engines

Address Reviewer A/B consensus findings (round 1):

- Expand the BoxLang <Aside> in v4-0-0-snapshot/start-here/cfml-engines.mdx
  to match the Adobe CF aside's coverage. Now lists all four affected
  commands (wheels start, stop, reload, test) and includes the
  ?reload=true&password=... URL workaround, matching the Adobe CF section
  that the PR body promised to mirror.

---------

Co-authored-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>