feat: BE release channel pipeline + wheels.json migration + Linux packages

[bpamiri]

Summary

Sets up the bleeding-edge release channel infrastructure ahead of v4.0.0 GA. Three independent things bundled into one PR because they share enough plumbing (release.yml, publish workflow, manifest reads) that splitting would require coordinated merges:

1. BE channel pipeline — develop snapshots auto-publish to wheels-dev/wheels-snapshots, brew tap auto-bumps, users brew install wheels-be for bleeding-edge.
2. box.json → wheels.json rename — drops the CommandBox/ForgeBox-shaped manifest in favor of a slim Wheels-native one. Dual-read fallback keeps legacy projects working.
3. Linux packages (.deb / .rpm) — Phase 1 ships them as GitHub Release attachments via nfpm. Phase 2 (apt.wheels.dev / yum.wheels.dev on CF Pages) documented as follow-up.

Related issues

Refs #2131 (GA tag plan for Wheels 4.0.0) — close after Tuesday's v4.0.0 tag push.
Refs #2383 (LuCLI Windows launcher leads to invalid setup) — close after Scoop bucket goes live and scoop install wheels is verified.

What's in the diff

Release channel classification

• cli/lucli/services/ReleaseChannel.cfc — pure-function helper. Maps version strings to stable / bleeding-edge / release-candidate / development. Recognizes both new (-snapshot.N) and legacy (-SNAPSHOT+N) snapshot formats.
• cli/lucli/tests/specs/services/ReleaseChannelSpec.cfc — 13 specs covering all classifications + edge cases.
• cli/lucli/Module.cfc — wheels --version now reports the channel suffix: wheels 4.0.1-snapshot.1742 (bleeding-edge).

SemVer separator fix

• release.yml + release-candidate.yml — snapshot versions use . (pre-release identifier) instead of + (build metadata, ignored in SemVer §10 precedence). Without this fix, adjacent-run snapshots would sort equal in brew/scoop comparators, silently breaking brew upgrade wheels-be.

box.json → wheels.json

• New manifest at root, vendor/wheels/, and tools/build/core/. Slim schema: drops type, slug, packageDirectory, dependencies-as-ForgeBox-slugs.
• Four readers updated with dual-read fallback (prefer wheels.json, fall back to box.json):
  • FrameworkInstaller.cfc::rewriteVersionPlaceholder (the wheels new scaffold path)
  • Module.cfc::runUpgradeCheck (the wheels upgrade command)
  • Global.cfc::\$buildReleaseZip (runtime release zip helper)
  • McpServer.cfc project-marker check
• Build pipeline (prepare-core.sh, generate-changelog.sh, release.yml, release-candidate.yml) reads from wheels.json.
• 3 new specs in FrameworkInstallerSpec.cfc cover wheels.json-preferred, both-exist precedence, pre-rename brew bottle fallback.

Snapshot publishing (integrates with existing snapshot.yml + release.yml)

After review, the original publish-snapshot.yml was found to duplicate work already done by snapshot.yml (which fires on develop push, runs the fast-test gate, and calls release.yml via workflow_call). The duplicate workflow is removed; instead, release.yml is now channel-aware:

• When called from develop (snapshot context): publishes to wheels-dev/wheels-snapshots using WHEELS_SNAPSHOTS_TOKEN (secret ✅ already configured).
• When triggered on main (stable context): publishes to wheels-dev/wheels (current behavior).
• Downstream dispatch step now includes a channel field (stable / bleeding-edge / release-candidate) derived from the version string, so the tap can route to the right formula.

snapshot.yml is updated to pass the new secret through and to read wheels.json.

Auto-bump after GA (new)

• .github/workflows/bump-develop-version.yml — fires on release publication on main. Opens an auto-bump PR against develop setting wheels.json's version to next-patch. Solves the "predict the next version" friction: snapshots baseline on next-patch but the actual GA scope (patch / minor / major) is decided at tag-cut time. Snapshot version strings sort strictly lower than any plausible next release.

Linux packages

• tools/distribution-drafts/linux-packages/nfpm-wheels.yaml + nfpm-wheels-be.yaml — nfpm configs for both channels.
• tools/distribution-drafts/linux-packages/build-linux-packages.sh — stages content + runs nfpm.
• Wired into release.yml (stable) and publish-snapshot.yml (BE) as a parallel artifact stream.
• Phase 1: .deb / .rpm ship as GitHub Release attachments.
• Phase 2: apt.wheels.dev / yum.wheels.dev on CF Pages — documented in tools/distribution-drafts/linux-packages/README.md.

Distribution drafts (reference copies for other repos)

• tools/distribution-drafts/homebrew/ — wheels-be.rb formula + wheels-be-bump.yml auto-bump workflow → wheels-dev/homebrew-wheels
• tools/distribution-drafts/scoop/ — wheels.json + wheels-be.json manifests → new wheels-dev/scoop-wheels
• tools/distribution-drafts/snapshots-repo/ — README + cleanup workflow → wheels-dev/wheels-snapshots (✅ already pushed there)

Operational docs

• .github/RELEASE_PLAYBOOK.md — daily flow, GA cut, rollback, RC, common failures.

Validation

Run locally on a fresh server rooted in this worktree:

• CLI suite: 518 pass / 5 unrelated pre-existing fails (TestRunnerSpec infra-fragile)
• Framework core suite: 3429 pass / 0 fail
• FrameworkInstallerSpec: 13/13 pass (including 3 new specs for the rename)
• ReleaseChannelSpec: 13/13 pass

Manual follow-ups still needed (not blocking this PR)

• Brew tap setup at wheels-dev/homebrew-wheels:
  • Push tools/distribution-drafts/homebrew/wheels-be.rb to Formula/wheels-be.rb
  • Push tools/distribution-drafts/homebrew/bleeding-edge-update.yml to .github/workflows/bleeding-edge-update.yml
  • Apply the small patch in tools/distribution-drafts/homebrew/auto-update-channel-patch.md to existing auto-update.yml (channel filter so it skips non-stable dispatches)
• Create wheels-dev/scoop-wheels repo, push manifest files
• Eventually: WinGet manifest PR to microsoft/winget-pkgs
• Phase 2 Linux: mint GPG key, create wheels-dev/apt-wheels-dev + wheels-dev/yum-wheels-dev CF Pages repos
• Docs overhaul: channels page, install instructions, drop CommandBox references
• Cleanup: drop wheels-base-template, wheels-starter-app, publish-to-forgebox.sh, legacy cli/src/

Test plan

• CI green (full compat matrix + CLI tests + commitlint)
• After merge: verify publish-snapshot.yml fires on the merge commit and creates a release in wheels-dev/wheels-snapshots
• After first snapshot publishes: verify repository_dispatch reaches wheels-dev/homebrew-wheels (will no-op until brew tap setup is done — that's expected)
• After Tuesday GA: verify bump-develop-version.yml fires and opens the next-patch bump PR

[wheels-bot]

Wheels Bot — Reviewer A

TL;DR: PR #2545 ships the bleeding-edge channel pipeline, wheels.json rename, and Linux package tooling — all well-motivated and tested at the CFML layer. One correctness bug in the new Linux package build script will silently produce artifacts in the wrong directory, causing the release upload to miss them. Two stale doc references and a harmless dead-code block round out the findings. Requesting changes on the correctness issue.

---

Correctness

build-linux-packages.sh — packages land in the wrong directory and won't be uploaded

The script does cd "${BUILD_DIR}" (which is ${repo_root}/.linux-pkg-build) before computing NFPM_OUT:

# tools/distribution-drafts/linux-packages/build-linux-packages.sh  (lines 2168–2190)
cd "${BUILD_DIR}"
mkdir -p "${OUT_DIR}"
NFPM_OUT="$(pwd)/${OUT_DIR}"   # ← $(pwd) is now BUILD_DIR, not repo root

When called from release.yml with OUT_DIR: artifacts/wheels/${{ env.WHEELS_VERSION }} (a relative path), NFPM_OUT resolves to:

${GITHUB_WORKSPACE}/.linux-pkg-build/artifacts/wheels/<ver>/

But the upload step globs:

# .github/workflows/release.yml (both stable and snapshot upload blocks)
artifacts/wheels/${{ env.WHEELS_VERSION }}/wheels_*_amd64.deb
artifacts/wheels/${{ env.WHEELS_VERSION }}/wheels-*.x86_64.rpm

which GitHub Actions resolves against $GITHUB_WORKSPACE, i.e.:

${GITHUB_WORKSPACE}/artifacts/wheels/<ver>/

The nfpm pkg step exits 0 and prints "── Done ──" with a listing of the newly-created files, so CI looks green. The upload step either errors or silently skips the packages depending on the ncipollo/release-action version's glob-no-match behavior. Either way, the .deb/.rpm files are absent from the release.

Fix: capture the repo root before cd, or resolve OUT_DIR to an absolute path before entering BUILD_DIR:

REPO_ROOT="$(pwd)"
BUILD_DIR="${REPO_ROOT}/.linux-pkg-build"
...
cd "${BUILD_DIR}"
mkdir -p "${REPO_ROOT}/${OUT_DIR}"
NFPM_OUT="${REPO_ROOT}/${OUT_DIR}"

---

Docs

.github/RELEASE_PLAYBOOK.md — stale box.json reference

# line 43
3. **Verify `box.json` version** matches what you want to release.

box.json was deleted in this same PR. Should read wheels.json.

---

tools/distribution-drafts/snapshots-repo/README.md — references a removed workflow

# line ~8
see [`publish-snapshot.yml`](https://github.com/wheels-dev/wheels/blob/develop/.github/workflows/publish-snapshot.yml)

The PR description explicitly states publish-snapshot.yml was consolidated into snapshot.yml + release.yml. The link is broken (that file no longer exists on develop). Should reference snapshot.yml.

---

Minor

build-linux-packages.sh — dead cat >> that silently fails

# lines ~2159–2165
cat >> "${NFPM_CONFIG}" <<NFPM_EXTRA_EOF || true
# Channel/version stamps — appended by build-linux-packages.sh
NFPM_EXTRA_EOF

After cd "${BUILD_DIR}", NFPM_CONFIG (a path relative to the repo root) no longer resolves. The || true swallows the error. The surrounding comment acknowledges this is a no-op ("we won't actually mutate the YAML here"). These four lines should be removed; they add confusion without effect.

---

tools/distribution-drafts/snapshots-repo/cleanup-old-snapshots.yml — counter scoping bug

DELETED=0
KEPT=0
...
echo "${BATCH}" | jq -c '.[]' | while read -r release; do
    DELETED=$((DELETED + 1))   # ← runs in a subshell; not visible to parent
    KEPT=$((KEPT + 1))
done
echo "Cleanup complete. Deleted: ${DELETED}, kept: ${KEPT}"  # always "0, 0"

Bash pipelines run in a subshell; DELETED and KEPT increments don't escape. The cleanups happen correctly but the summary is always 0, 0. Fix: use a process-substitution redirect so the loop runs in the current shell:

while read -r release; do
    ...
done < <(echo "${BATCH}" | jq -c '.[]')

---

[wheels-bot]

Wheels Bot — Reviewer B (round 1)

A correctly identified the nfpm output-directory bug and two minor issues. One finding has a wrong stated reason (but the conclusion holds), and A missed several stale documentation references that were introduced by this same PR. Not converging — A should surface the additional misses before address-review picks this up.

Note: the PR was merged before this review cycle completed. The issues below are still worth a follow-up PR.

Sycophancy

None detected. A requested changes rather than approving, and the correctness finding is substantiated.

False positives

build-linux-packages.sh — dead cat >> explanation is wrong

A claims the cat >> silently fails because "after cd "${BUILD_DIR}", NFPM_CONFIG (a path relative to the repo root) no longer resolves." This is incorrect. Looking at the diff:

# line ~2160 — cat >> runs HERE (before cd)
cat >> "${NFPM_CONFIG}" <<NFPM_EXTRA_EOF || true
# Channel/version stamps — appended by build-linux-packages.sh
NFPM_EXTRA_EOF

# line ~2168 — cd happens AFTER
cd "${BUILD_DIR}"

The cat >> runs while the working directory is still the repo root, so NFPM_CONFIG resolves correctly. The || true is redundant. The code does execute; it just appends a YAML comment (harmless, no-op). The conclusion — confusing dead code worth removing — is still valid, but A's stated reason is wrong and would mislead anyone reading the review.

Missed issues

RELEASE_PLAYBOOK.md — two additional stale box.json references A did not flag

A flagged the one at line 3 of the pre-flight checklist (Verify box.json version). Two more stale references exist in the same file:

• The release-day section describes bump-develop-version.yml as "opens a PR against develop bumping box.json to next-patch." The workflow (also added in this PR) bumps wheels.json, not box.json.
• The "Common failure modes" table says: box.json has -SNAPSHOT suffix on main. The updated release.yml reads from wheels.json and its error message says wheels.json contains snapshot suffix. A user following that table row would look at the wrong file.

Both are in the same newly-added .github/RELEASE_PLAYBOOK.md that A already reviewed.

Five additional stale publish-snapshot.yml references A missed

A caught one reference in tools/distribution-drafts/snapshots-repo/README.md. Five more stale references to the removed workflow appear in other newly-added files:

File	Stale line
tools/distribution-drafts/snapshots-repo/README.md	Step 2 of the Lifecycle section: "publish-snapshot.yml builds artifacts, opens a release here" — same file A reviewed, second occurrence
tools/distribution-drafts/README.md	"matching CI workflow changes (publish-snapshot.yml, etc.) in this repo"
tools/distribution-drafts/homebrew/ README	"the publish-snapshot.yml workflow fires them"
tools/distribution-drafts/linux-packages/README.md	"wired into release.yml and publish-snapshot.yml as a parallel artifact stream"
tools/distribution-drafts/scoop/README.md	"repository_dispatch from publish-snapshot.yml → tap workflow opens PR"

The PR description explicitly states publish-snapshot.yml was removed and consolidated into snapshot.yml + release.yml. The snapshots-repo README was already pushed to wheels-dev/wheels-snapshots (per the PR summary), so at least two of these broken links are already live in an external repo.

Verdict alignment

A's CHANGES_REQUESTED verdict is consistent with the nfpm correctness finding. Appropriate.

Convergence

Not aligned. A's review covers the critical nfpm bug and two minor issues, but misses two additional stale box.json references in RELEASE_PLAYBOOK.md and five stale publish-snapshot.yml references across the distribution-drafts READMEs (six total, A found one). These are doc bugs, not runtime bugs, but they ship misinformation about the release pipeline into both this repo and the already-pushed wheels-dev/wheels-snapshots README. A should acknowledge these in a response before convergence, so that address-review has a complete change list.

[wheels-bot]

Wheels Bot — Reviewer A response (round 1)

B's critique is well-founded across the board. I'm conceding the wrong reasoning on the cat >> finding, and all seven additional stale doc references B surfaced. None of B's points warrant pushback — the diff evidence is clear. My verdict stays CHANGES_REQUESTED, but the remediation scope is materially wider than my initial review described: address-review should now have a complete list.

Conceded points

• cat >> reasoning was wrong. The diff shows cat >> "${NFPM_CONFIG}" at diff line 2159 and cd "${BUILD_DIR}" at diff line 2168. The heredoc runs while the working directory is still the repo root, so NFPM_CONFIG resolves correctly. The || true is redundant, not hiding a failure. My stated reason — "after cd, NFPM_CONFIG no longer resolves" — was incorrect. The conclusion (confusing dead code that should be removed) still holds, but for the right reason: the code is a no-op comment append that serves no purpose, not a silently swallowed error.

• Two additional stale box.json references in RELEASE_PLAYBOOK.md. Confirmed at diff lines 59 and 149:

  • Line 59: Release-day section says bump-develop-version.yml "opens a PR against develop bumping box.json to next-patch". The workflow (also introduced in this PR) bumps wheels.json, not box.json.
  • Line 149: "Common failure modes" table row says `box.json` has `-SNAPSHOT` suffix on main. The updated release.yml reads from wheels.json and its error message names wheels.json. A user following the table would look at the wrong file.

• Five additional stale publish-snapshot.yml references across distribution-drafts READMEs. All confirmed in the diff:

  • tools/distribution-drafts/README.md (diff line 1370): "matching CI workflow changes (publish-snapshot.yml, etc.) in this repo"
  • tools/distribution-drafts/homebrew/ README (diff line 1772): "the publish-snapshot.yml workflow fires them"
  • tools/distribution-drafts/linux-packages/README.md (diff line 1918): "wired into release.yml and publish-snapshot.yml as a parallel artifact stream"
  • tools/distribution-drafts/scoop/README.md (diff line 2383): "repository_dispatch from publish-snapshot.yml → tap workflow opens PR"
  • tools/distribution-drafts/snapshots-repo/README.md (diff line 2625): Lifecycle Step 2 — "publish-snapshot.yml builds artifacts, opens a release here" — second occurrence in the same file I partially reviewed

  Combined with the one I flagged in my initial review (the link reference at diff line 2591), there are six stale references to the removed workflow, not one.

Defended points

None. B's critique is accurate on every point.

Updated verdict

Still CHANGES_REQUESTED. The nfpm output-directory bug is the blocking correctness issue. The doc findings (three stale box.json references, six stale publish-snapshot.yml references) are non-blocking but should ship in the same fix pass since two of the snapshots-repo README entries are already live in the external wheels-dev/wheels-snapshots repo. Address-review has a complete change list.