[bpamiri]

Closes #4206.

Stacked on #4205. The base is #4205's branch, because both PRs edit the same packages() docblock lines. When #4205 squash-merges, GitHub retargets this PR to develop, and I'll merge develop in. Lifted into 4.2.0 (ready for review). The v4-2-0 guide pages get a separate docs-only PR.

Problem

The CLI said wheels packages install <name> is intercepted by LuCLI and installs nothing. On the current CLI it installs exactly like add; #4206 shows byte-identical vendor/ trees. The help also contradicted itself: the Options text already said "install is an alias".

Change

add stays the documented verb; install is described as its alias.

Where	Before	After
wheels help packages line	"(verb is add, not install)"	"Add (or install), update, search Wheels packages"
packages() hint	"(verb is add, not install)"	"(install is an alias of add)"
Usage annotation	← install verb	(alias: install)
wheels packages help	A six-line "NOT install… intercepted by LuCLI" note	"install is an alias of add, so wheels packages install <name> works the same way."
Unknown-subcommand error	"The install verb is add (not install)"	"To install a package: wheels packages add "
templates/app/plugins/README.md	"Note: the install verb is add, not install."	Removed; the README shows add.

Maintainer comments in Module.cfc and PackagesMainCli.cfc now describe the interception as older-runtime history (#2713) instead of current fact.

Unchanged on purpose:

• The guards that keep copy snippets and the wheels new templates on add (PackagesAddVerbAdvertisingSpec, CliTemplateInstallVerbSpec). add works on every CLI version, while the released 4.1.x CLIs (LuCLI 0.6.2.1) were not checked. Only their comments changed.
• wheels browser install has a similar note. It's out of scope here.

Tests

• PackagesCommandSpec: its help block has been xdescribed since WheelsTest: spec files that skip describe() or error during load fail silently in the runner #2829, because -h reaches the registry. So I added a block that runs: wheels packages help and wheels packages --help say install is an alias, and nothing says "not install" or "intercept"; the global help no longer says "not install". The skipped block's assertions are reworded too, so they hold if it's re-enabled.
• CommandHelpTextSpec (from fix(cli): print only user help text in wheels <command> --help #4205) and the core PackagesCommandHelpSpec follow the new text.
• RED: the base (fix(cli): print only user help text in wheels <command> --help #4205 head) plus only the spec changes:
  • CLI suite: 3 failures, the new alias checks and the packages hint check.
  • tools/test-local.sh cli: 1 failure, the unknown-subcommand text.
• GREEN, local:
  • CLI suite: 2139 / 0 / 0.
  • tools/test-local.sh cli: 235 passed.
  • tools/test-local.sh packages: 142 passed.
  • CLI complexity gate: PASS.

Merged #4205's branch for 4.2.0

#4205's branch now includes develop. The only conflict was PackagesCommandHelpSpec: this PR's test titles plus develop's $requireRepoPath guards. GREEN after the merge: CLI suite 2292 / 0 / 0, full core suite (Lucee 7) 6662 passed, CLI complexity gate PASS.

🤖 Generated with Claude Code

[bpamiri]

rev1-r3 review @ 592854b: APPROVE

Covers every #4206 item:

• Global help line.
• packages() hint and the (alias: install) Usage annotation.
• The case "install": comment.
• The unknown-subcommand error, which now points at add without warning against install.
• The $packagesHelp() note.
• The PackagesMainCli header and the install() comment.
• The template README line.

The behaviour is unchanged (install still falls through to add), and I reproduced the pass-through on 4.2.0-snapshot.2842. In a directory with a lucee.json, wheels packages install with no name reaches this module's add requires a name error.

Fits #4205's rules:

• The maintainer history stays in // comments outside the docblock, so --help and the MCP description don't pick it up.
• The new hint and help note have no #NNNN references.
• Moving the alias checks into a non-skipped describe is the right call. They read the module-owned help string, so they run everywhere, and the xdescribe block (WheelsTest: spec files that skip describe() or error during load fail silently in the runner #2829) would have hidden them.

Non-blocking leftovers. Nothing user-visible except the last one:

• vendor/wheels/tests/specs/cli/PackagesCommandHelpSpec.cfc still says install "is intercepted by LuCLI" as current fact: header lines 4–6, the failure messages at ~38 and ~62, and the it() title at ~68 ("not the intercepted Install verb").
• cli/lucli/tests/specs/commands/PackagesCommandSpec.cfc ~152: "the only place install ever no-ops is the LuCLI extension-installer intercept (which we cannot patch)".
• vendor/wheels/public/views/packagelist.cfm ~165: a CFML comment with the same claim. It isn't rendered.
• Out of scope: Module.cfc ~6076 makes the same claim for wheels browser install ("LuCLI intercepts install… The case branch here only fires if…"). If the runtime now passes install through for packages, that branch is probably reachable from the shell too. Worth a follow-up issue that checks it.

CI: the PR's CLI suite check finished in 2s on the stacked base, so I'm relying on your local GREEN (CLI 2139/0/0, packages 142). Re-check once #4205 merges and this rebases onto develop.

[bpamiri]

rev1-r3 review @ 21060fd: APPROVE

Delta 592854bd..21060fd6e: comments, spec header, it() titles and failure messages only. No assertion changed. I diffed all three files.

The first three leftovers from my last review are gone:

• PackagesCommandHelpSpec header, titles and messages.
• The PackagesCommandSpec ~152 comment.
• The packagelist.cfm CFML comment, which isn't rendered.

The header now puts the interception in the past ("On the CLIs of the time …"), which matches what we know. The browser install comment (~6076) moves to #4213, as agreed.

Same CI caveat as before: re-check the full suite once #4205 merges and this branch rebases onto develop.

[bpamiri]

rev1-r3 review @ ca77108: code re-APPROVE (final sign-off after orch1's matrix run on this head)

ca7710852 merges #4205's branch, which now includes develop. Against that base, this PR's own added and removed lines are identical to the content I approved at 21060fd6e: the same 10 files (Module.cfc, PackagesMainCli.cfc, the template README, packagelist.cfm comment, the CLI and core specs, the changelog fragment).

Two points from the merge:

• PackagesCommandHelpSpec conflict. Resolved as you describe: this PR's titles and messages, behind develop's $requireRepoPath() guards.
• CommandHelpTextSpec (from fix(cli): print only user help text in wheels <command> --help #4205) now expects the new packages hint, "install is an alias of add", in place of fix(cli): print only user help text in wheels <command> --help #4205's old verb is \add`, not `install``. So the two PRs agree, and the spec won't break when this rebases onto develop after fix(cli): print only user help text in wheels <command> --help #4205 merges.

The base is still peter/4168-help-maintainer-notes. Once #4205 merges, retarget this to develop and re-check CI there.

[bpamiri]

rev1-r3 review @ 9e34598: code re-APPROVE (final sign-off after matrix run 37263158622)

9e34598b7 merges develop after #4205's squash; the base is now develop. Checked:

• gh pr diff against develop is the same 10 files, and its added/removed lines hash identically (md5) to my approved range 05e6b6501..ca7710852. So the content didn't change.
• The two conflicts (the packages docblock and hint, and the CommandHelpTextSpec packages assertion) resolved to this PR's lines, which is the alias wording both PRs now agree on.

[github-actions]

Wheels Test Results

216 615 tests   212 491 ✅  1h 6m 47s ⏱️
 16 544 suites    4 124 💤
     32 files          0 ❌

Results for commit 9e34598.

[bpamiri]

rev1-r3 review @ 9e34598: APPROVE (final; matrix run 37263158622 read leg by leg)

• Matrix run 37263158622 is on this head, and all 32 legs plus rustcfml succeeded. From the junit artifact for each leg:
  • 6765–6782 tests per leg, with 0 failures and 0 errors on every leg.
  • The three core specs this PR touches ran and passed on every leg, none skipped: PackagesCommandHelpSpec 5/5, CliTemplateInstallVerbSpec 3/3 and PackagesAddVerbAdvertisingSpec 3/3. That includes all of Adobe 2023, Adobe 2025 and BoxLang.
• PR CI on this head: 21 checks pass and 2 are skipped, including the CLI suite.