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

[bpamiri]

Summary

The trio of closed issues #2610 / #2706 / #2713 all describe the same problem: `wheels packages install ` is a silent no-op (intercepted by LuCLI's extension installer), the working verb is `add`, and `wheels packages --help` advertises `install` despite it not working.

All three are marked CLOSED with state "COMPLETED." But the behavior is still present in CLI 4.0.1 as of 2026-05-21.

Repro on 4.0.1

```bash
$ wheels --version
Wheels CLI 4.0.1

$ wheels packages --help | grep -E '^\s+(install|add)'
install [@] Install (latest compat or pinned)

Note: 'add' is NOT shown in --help (matching #2713 description)

$ wheels packages install wheels-basecoat
Reading lucee.json...
Resolving dependencies...
ℹ️ No git or extension dependencies to install
$ echo $?
0
$ ls vendor/wheels-basecoat 2>&1
ls: vendor/wheels-basecoat: No such file or directory

install reported success, installed nothing

$ wheels packages add wheels-basecoat

… this works — installs wheels-basecoat@3.0.0 to vendor/

$ ls vendor/wheels-basecoat
Basecoat.cfc README.md box.json …
```

Source code in 4.0.1 still documents the trap

`/opt/homebrew/Cellar/wheels/4.0.1/share/wheels/module/services/packages/PackagesMainCli.cfc` lines 13-19:

"`add` (not `install`!) is the install verb because LuCLI's built-in extension installer intercepts the literal subcommand `install` across all modules — same trap that bit `wheels browser install` (renamed to `wheels browser setup` in #2345). User input `wheels packages install ` never reaches Module.cfc; LuCLI runs its own dependency installer against `lucee.json` instead and prints "No git or extension dependencies to install"."

So the comment in the source explains why `install` doesn't work, but the actual user-facing `--help` text still advertises `install` as the install verb. The fix that closed #2610/#2706/#2713 either:

1. Didn't actually ship in 4.0.1 (maybe it's in a later snapshot that isn't tagged?), or
2. Was a docs-only fix elsewhere (https://guides.wheels.dev / https://packages.wheels.dev) that didn't update the CLI's built-in help text, or
3. Regressed between closure and 4.0.1 release.

In all three cases the result is the same: the user-facing problem documented in those three issues is still present for anyone on the current Homebrew-released CLI.

Impact

Surfaced AGAIN during dogfooding (DataPAI portal Phase 0 on Titan, 2026-05-21). The implementer subagent followed `wheels packages --help`, hit the no-op, then dug into the CLI source to find `add`. Lost ~10 minutes of execution time and required filing the workaround in project memory.

This is the second time the same problem has been surfaced from real usage AFTER three closed issues. The closed issues did not actually resolve the user-facing behavior.

Suggested fix

The simplest path is to alias `install` to `add` in the CLI's command dispatch — let LuCLI's intercept happen, then either re-dispatch or wrap. The trap that the source code comment describes is a known LuCLI behavior; the Wheels CLI just needs to either rename its own subcommand or work around the intercept.

Failing that, remove `install` from `wheels packages --help` and replace with `add`. The CLI help is the authoritative quick-reference; if it says `install` works and it doesn't, the broken behavior is shipping daily to every new user.

Related closed issues (re-surfacing)

• wheels packages install command does not install packages and conflicts with documentation #2610 (CLOSED 2026-05-12) — `wheels packages install` does not install
• wheels packages install <name> is a silent no-op — canonical install command in docs doesn't actually install #2706 (CLOSED 2026-05-15) — silent no-op
• wheels packages --help advertises 'install' but the working verb is 'add' — help text drift #2713 (CLOSED 2026-05-16) — `--help` advertises install but the working verb is `add`

cc @bpamiri

🤖 Found while dogfooding the DataPAI portal Phase 0 plan via Claude Code

[wheels-bot]

Wheels Bot — Triage

Classified as bug.

Suspected layer

cli — affects cli/lucli/Module.cfc (packages dispatch + $packagesHelp()) and the LuCLI intercept boundary above it. No .ai/wheels/cli/ doc exists; canonical patterns live in cli/CLAUDE.md and inline source comments at cli/lucli/services/packages/PackagesMainCli.cfc:13-19.

Fix sketch

Two related symptoms on the Homebrew-released 4.0.1: (a) wheels packages --help still advertises install <name>[@<version>] instead of add, and (b) wheels packages install <name> silently no-ops via LuCLI's built-in extension installer.

On the develop branch the help text in cli/lucli/Module.cfc:2145-2169 already reads add <name>[@<version>] [--force] (canonical) with a "verb is add, NOT install" note, and lines 2099-2112 add a case "install": redirect — but the inline comment explicitly admits this case is dead code on the CLI surface because LuCLI's extension installer intercepts the literal install verb before dispatch reaches Module.cfc (same trap that forced wheels browser install → wheels browser setup in #2345).

So the real fix is one of:

1. Release-side: cut a new tagged CLI release that ships the develop-branch help text (the user-visible part of wheels packages --help advertises 'install' but the working verb is 'add' — help text drift #2713's fix never reached 4.0.1's Homebrew bottle).
2. Code-side: if LuCLI's intercept genuinely can't be bypassed, delete the dead case "install": to stop misleading future maintainers and double down on the --help text being the contract. If LuCLI can be made to forward unknown subcommands to Module.cfc (e.g. via a hook or by registering install as a known verb at the LuCLI layer), do that and alias install → add in dispatch.

The closed trio #2610/#2706/#2713 needs to be verified — likely option 1 (fix never released) given the source already has the help text fix.

Confidence: medium

Reproduction is concrete and the layer is unambiguous, but the fix shape depends on whether LuCLI's intercept can be circumvented (option 2 above) — that's a design call, not a mechanical edit — and the trio of prior closed issues suggests release-process involvement, which propose-fix can't resolve in code alone.

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

[wheels-bot]

Wheels Bot — Fix proposed

Draft PR: #2786

Spec: cli/lucli/tests/specs/commands/PackagesCommandSpec.cfc — new describe("wheels packages install — alias for add", ...) block; failing against the pre-change dispatch (which returned "" silently) → passing once case "install": falls through to case "add":.

Implementation: cli/lucli/Module.cfc (lines 2092–2112) — both verbs now share a single fall-through case body so validation, error shape, and install behavior cannot drift apart.

Scope note: this only fixes the caller paths that reach Module.cfc (stdio MCP server, scripted clients, spec suite). The shell-facing wheels packages install <name> is still intercepted by LuCLI's built-in extension installer upstream of module dispatch and is documented as such in the module-owned --help text. The release-side half of the triage's recommendation — shipping the existing develop-branch help-text fix from #2729 to Homebrew bottle users on 4.0.1 — is a release process action and is left for human follow-up.

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.