build(cli): mark published wheels-cli ForgeBox metadata as deprecated

[wheels-bot]

The legacy CommandBox wheels-cli module is published to ForgeBox on every stable release, yet its registry-visible metadata read as the supported CLI — box.json carried "Command Line Interface for Wheels framework providing code generation, database migrations, testing, and development tools" and README.md opened with "The official Command Line Interface for the wheels framework." A ForgeBox browser saw no deprecation signal before running box install wheels-cli, even though the module is deprecated in favour of the standalone wheels binary and slated for removal in v5.0 (#2227, #2634). This PR rewrites tools/build/cli/box.json and tools/build/cli/README.md so every registry-visible field leads with the deprecation, names the v5.0 removal, and points at the supported CLI (brew install wheels-dev/wheels/wheels) plus the v4 install guide. A guard spec pins the posture so the metadata cannot drift back.

This is the agreed, low-risk half of the issue. The genuine maintainer strategy call — freezing/decoupling the published CLI version from the framework release in tools/build/scripts/prepare-cli.sh — is intentionally deferred to a human (the research flagged the pipeline-freeze posture for human review), so this PR ships only the registry-metadata change. Because it does not close the issue's full scope, it uses Refs rather than Fixes.

Recommended path from research: #3184 (comment)

Refs #3184

Why ForgeBox metadata, not a CFML API

ForgeBox/CommandBox has no first-class soft-deprecate flag (the npm deprecate / Composer abandoned / Hex retire analogue). Per the cross-framework research, that puts Wheels in the RubyGems situation: the only pre-install, registry-visible lever is the box.json description/instructions/short-description text plus the README. forgebox unpublish is off the table — it would break box install wheels-cli for existing automation (~9.8k installs). So the deliverable is release-artifact metadata, not a vendor/wheels/** component.

TDD

• Spec: vendor/wheels/tests/specs/cli/ForgeBoxCliDeprecationMetadataSpec.cfc — a structural guard (mirrors buildArtifactLicenseSpec.cfc / LegacyUpgradeDeprecationSpec.cfc) that reads the two committed templates and asserts each registry-visible field leads with the deprecation and points to the successor.
• Red → green: against the pre-fix files the deprecation assertions fail (no DEPRECATED/successor-pointer text anywhere in tools/build/cli/, and the README still advertises the "official CLI"); after the rewrite all assertions hold.

Test-harness note: the server-based TestBox harness (bash tools/test-local.sh) could not run in this sandboxed bot environment — the wheels CLI binary is not installed here (nohup: failed to run command 'wheels') and the sandbox blocks access outside the working tree, so no Lucee server can be started. The spec is pure file-read string/regex assertions; red→green was verified deterministically against the exact field values and file contents (every DEPRECATED / brew install wheels-dev/wheels/wheels / install-guide token present after the fix; both "official CLI" and feature-parity strings gone). The authoritative TestBox run executes in bot CI, which has the runtime.

Implementation

• tools/build/cli/box.json — name, shortDescription, description, instructions lead with DEPRECATED; documentation repointed to the v4 install guide; deprecated keyword added.
• tools/build/cli/README.md — opens with a > **DEPRECATED …** blockquote banner, drops the "official CLI" framing, and routes readers to brew install wheels-dev/wheels/wheels + the install/upgrade guides.

Checklist

• Tests — ForgeBoxCliDeprecationMetadataSpec.cfc (failing → passing; see test-harness note for how red→green was verified in this environment)
• Framework Docs — handled separately by bot-update-docs.yml
• AI Reference Docs — handled separately by bot-update-docs.yml
• CLAUDE.md — handled separately by bot-update-docs.yml
• CHANGELOG.md — changelog.d/3184-wheels-cli-forgebox-deprecation-metadata.changed.md
• Test runner passes — registry-metadata assertions verified deterministically (red on pre-fix files, green after); authoritative TestBox run defers to bot CI (local wheels binary unavailable in this sandbox)

[wheels-bot]

Wheels Bot — No doc updates

Reviewed this PR's diff and found no docs that need updating (purely a build-artifact metadata change — the ForgeBox registry fields in tools/build/cli/box.json and tools/build/cli/README.md were updated to lead with deprecation notices; the upgrade guide already documents the CommandBox wheels-cli deprecation, the install guide already directs users to the wheels binary, and no framework convention or .ai/wheels/ pattern changed).

[wheels-bot]

Wheels Bot — Reviewer

TL;DR: This PR rewrites the ForgeBox-visible metadata for the deprecated CommandBox wheels-cli module (tools/build/cli/box.json + tools/build/cli/README.md) so every registry field leads with the deprecation, names the v5.0 removal, and points at the supported standalone wheels binary — and adds a structural guard spec pinning that posture. Verdict: approve (submitted as a comment: GitHub rejects the bot approving its own PR — a maintainer should treat this as a clean review). Every claim in the PR body checks out against the repo, the spec follows established guard-spec prior art exactly, and there are no correctness, cross-engine, convention, or security findings.

What was verified

Spec assertions vs. committed files — I evaluated every assertion in vendor/wheels/tests/specs/cli/ForgeBoxCliDeprecationMetadataSpec.cfc by hand against the committed templates; all pass:

• box.json name = "Wheels CLI Commands (DEPRECATED)"; shortDescription and instructions both lead with DEPRECATED; description contains the deprecation, 5.0 removal, brew install wheels-dev/wheels/wheels, and the install-guide URL; the pre-fix feature-parity blurb (providing code generation, database migrations, testing, and development tools) is gone (tools/build/cli/box.json:17-19).
• README.md opens with > **DEPRECATED — do not use for new projects.** (matches the spec's (?m)^>\s*\*\*DEPRECATED regex), and the old The official Command Line Interface for the wheels framework framing is removed (tools/build/cli/README.md:3).

The spec guards the real published artifact — tools/build/scripts/prepare-cli.sh:31-32 copies exactly these two files into the release artifact (cp tools/build/cli/box.json … / cp tools/build/cli/README.md …), so this isn't a guard on dead templates.

Cross-engine — the spec mirrors sibling guard specs precisely: shared-ctx-struct for closure state, expandPath("/wheels/../..") repo-root resolution (prior art: buildArtifactLicenseSpec.cfc and five existing tests/specs/cli/ guard specs), (?m) inline regex flag (prior art: LegacyUpgradeDeprecationSpec.cfc, RateLimiterMemoryStoreSpec.cfc), arrow-function it() bodies (prior art throughout the suite). The ##3184 in describe() string literals is correctly escaped — an unescaped # there would crash the whole core suite, and there isn't one.

Non-breaking posture — ForgeBox package identity is the slug (wheels-cli, unchanged); only the display name gained the (DEPRECATED) suffix, so existing box install wheels-cli automation is unaffected, consistent with the PR's stated goal.

Pointer consistency — brew install wheels-dev/wheels/wheels matches the existing in-CLI banner at cli/src/commands/wheels/upgrade.cfc:42, and both linked guide pages exist in the repo (web/sites/guides/src/content/docs/v4-0-0/command-line-tools/installation.mdx, web/sites/guides/src/content/docs/v4-0-0/upgrading/3x-to-4x.mdx).

Commits & changelog — build(cli): mark published wheels-cli ForgeBox metadata as deprecated is a valid conventional-commit header (66 chars, allowed type, not ALL-CAPS) with a matching DCO sign-off, and the body explains the why (including the deliberate deferral of the version-freeze half to a human). Changelog uses a fragment (changelog.d/3184-wheels-cli-forgebox-deprecation-metadata.changed.md) with a valid type, not a direct CHANGELOG.md edit.

Scope discipline — using Refs #3184 rather than Fixes is correct, since the prepare-cli.sh version-freeze decision is intentionally left to a maintainer.

No findings under Correctness, Conventions, Cross-engine, Tests, Docs, Commits, or Security.

[bpamiri]

Superseded by #3197 (merged): a propose-fix draft that raced the ForgeBox path-repair campaign for the same issue; the campaign PR landed first and closed the underlying issue. Closing the duplicate.