rpm packaging: v4.0.0 ships legacy wheels-cli module, missing .version / .channel files (titan cutover regression)

[bpamiri]

Describe the bug

The v4.0.0 rpm distribution diverges from the brew/Scoop distributions in two ways that block production deployment of wheels start on Rocky Linux. Surfaced during the titan production cutover on 2026-05-13 (see paiindustries/titan cutover run log).

1. Wrong module ships in /opt/wheels/modules/

The rpm installs the legacy CommandBox-style wheels-cli module (~558 KB, expects box install-shaped contents) instead of the new lucli-native wheels-module (~24 MB, with Module.cfc at top). This makes wheels start fail with Unknown command: 'start'. The brew formula ships the correct wheels-module.

2. Missing /opt/wheels/.version and /opt/wheels/.channel

The wrapper script reads these files to report version info. Without them, wheels --version returns unknown (stable). The brew formula writes both files during install.

3. Wrapper does not prepend module name when invoking lucli

The rpm's /usr/bin/wheels wrapper passes args directly to lucli without prepending the module name, so wheels start becomes lucli start (Unknown command). The brew wrapper renames the binary to wheels and routes via argv[0]. The rpm wrapper needs equivalent routing — either an argv[0] rename or an explicit lucli modules run wheels <args> invocation.

To Reproduce

On a fresh Rocky Linux 10 minimal cloud image:

dnf install tar  # rpm omits this dep — see note below
dnf install wheels-4.0.0-1.el10.x86_64.rpm
wheels --version            # → "unknown (stable)"
wheels start                # → "Unknown command: 'start'"
ls /opt/wheels/modules/     # → wheels-cli/ (legacy), not wheels-module/

Expected behavior

• wheels --version returns the installed version + channel.
• wheels start launches the Lucee server.
• /opt/wheels/modules/ contains wheels-module (lucli-native), not wheels-cli (CommandBox-legacy).

Workaround currently in production (paiindustries/titan)

The titan Ansible wheels-cli role overlays the correct module after rpm install, writes .version + .channel, and uses wheels modules run wheels start in the systemd unit. See ansible/roles/wheels-cli/ and commits 867d1f906 + 9dc45da6b + 3a3c1dbe5.

This workaround should not be necessary — every titan VM has to apply it independently.

Additional notes

• The rpm should explicitly declare tar as a dependency. Rocky Linux 10 minimal cloud images do not ship tar, and the rpm's post-install (or any role unpacking the module) fails silently without it.
• The rpm wrapper's invocation strategy could mirror the brew approach (argv[0] rename) or use explicit module-routed lucli calls. Either is fine — they just need to match each other across distributions.

Desktop:

• OS: Rocky Linux 10 (minimal cloud image, Proxmox)
• Wheels: 4.0.0 (rpm)
• Java: OpenJDK 21

[wheels-bot]

Wheels Bot — Triage

Classified as bug.

Suspected layer

cli — Linux packaging in tools/distribution-drafts/linux-packages/.

Fix sketch

All three sub-bugs originate in the rpm/deb staging pipeline, which diverges from the brew formula in three independent ways:

1. Wrong module artifact. tools/distribution-drafts/linux-packages/build-linux-packages.sh:51 unzips wheels-cli-${VERSION}.zip (the legacy CommandBox-shaped artifact) into build/module/. It should consume wheels-module-${VERSION}.tar.gz instead — that is the lucli-native module the brew formula installs.
2. Missing .version / .channel. The build script writes both files into build/ (lines 135-136), but nfpm-wheels.yaml / nfpm-wheels-be.yaml never declare them under contents:, so they are dropped on the floor. Adding two entries pointing at /opt/wheels/.version and /opt/wheels/.channel ships them.
3. Wrapper invocation. The generated wrapper ends with exec /opt/wheels/lucli "$@" (line 131). lucli without a module prefix cannot resolve start, so this needs to route through the module — either rename the binary to wheels and rely on argv[0] (the brew approach) or call lucli modules run wheels "$@" explicitly.

Plus the additional tar runtime dep: add tar to nfpm-wheels*.yaml overrides.rpm.depends (Rocky 10 minimal cloud images do not ship it). Both nfpm yamls need symmetrical fixes so the bleeding-edge wheels-be rpm does not regress alongside.

Confidence: medium

Report is exceptionally precise (three numbered failures, reproduction steps, working production workaround) and the fix locations are unambiguous, but the change spans four coordinated edits across build-linux-packages.sh + both nfpm yamls and includes a small design choice on the wrapper invocation strategy.

<!-- wheels-bot:triage:2700 -->
<!-- wheels-bot:triage-class:bug -->
<!-- wheels-bot:triage-confidence:medium -->

[wheels-bot]

Wheels Bot — Fix proposed

Draft PR: #2701

Spec: vendor/wheels/tests/specs/cli/LinuxPackageStagingSpec.cfc — failing → passing (8 specs, all 4 sub-fixes covered)
Implementation:

• tools/distribution-drafts/linux-packages/build-linux-packages.sh — consume wheels-module-${WHEELS_VERSION}.tar.gz, stage LuCLI as /opt/wheels/wheels, update wrapper to exec /opt/wheels/wheels "$@"
• tools/distribution-drafts/linux-packages/nfpm-wheels.yaml — declare /opt/wheels/.version, /opt/wheels/.channel, and tar rpm+deb dep
• tools/distribution-drafts/linux-packages/nfpm-wheels-be.yaml — same fixes for the bleeding-edge channel

Local test runner: 42 pass, 0 fail on the cli layer (was 34 pass, 8 fail before the implementation, where the 8 fails were the new specs). Full core suite: 3553 pass, 0 fail, 0 error, 16 skipped — no regressions.

A human review is required before merge. Reviewer A and Reviewer B will weigh in shortly. Doc updates (MDX guides, .ai/wheels/, CLAUDE.md) are handled separately by bot-update-docs.yml.

End-to-end validation (Rocky 10 VM install + wheels start) is out of scope for the structural-test pattern used here; the next snapshot rpm built by release.yml should be re-run against the titan cutover sequence to confirm the regression is gone for real.