Point Composer users to package-command when wp package is missing

[swissspidy]

Problem

Since #846 moved wp-cli/package-command to require-dev, it still ships in the Phar but is absent from Composer-based installations of the bundle. Installing the bundle via Composer is an anti-pattern, but people do it — and today they hit a dead end:

Error: 'package' is not a registered wp command. See 'wp help' for available commands.

Nothing tells them the command exists, that their install method is why it is missing, or that composer require wp-cli/package-command brings it back. The suggest entry added in #846 only surfaces at install time, long before anyone types wp package.

Changes

Declares the guidance as metadata, using the extra.command-hints mechanism proposed in wp-cli/wp-cli#6386:

"extra": {
  "command-hints": {
    "package": "The 'package' command is bundled with the WP-CLI Phar, but is an optional dependency of Composer-based installations. Run `composer require wp-cli/package-command` to add it, or manage WP-CLI packages as regular Composer dependencies of your project instead."
  }
}

Metadata rather than code because this package has no autoload section — composer.json is the only channel it has.

composer.lock's content-hash is updated in the same commit, since extra feeds into it and the lock would otherwise be reported as stale.

Result

Composer users get:

Error: 'package' is not a registered wp command. See 'wp help' for available commands.
The 'package' command is bundled with the WP-CLI Phar, but is an optional dependency
of Composer-based installations. Run `composer require wp-cli/package-command` to add
it, or manage WP-CLI packages as regular Composer dependencies of your project instead.

Phar users see no change — the hint only fires when the command is genuinely unregistered, and in the Phar wp package is registered. The single package entry also covers every subcommand, since wp package install foo fails on the top-level package lookup.

Testing

A package-command-guidance job in testing.yml installs the bundle with --no-dev — the state Composer-based users end up in — and asserts wp package fails with the hint rather than a bare "not a registered wp command". Metadata that nothing reads is easy to break silently, so this guards against the entry being dropped or misnested, and against the framework renaming the extra key.

Two honest caveats:

• The job exercises the root-package read path, not the installed.json path. With --no-dev in this repo, the bundle is the root package, and the framework reads hints from the root composer.json as well as from vendor/composer/installed.json. Real users hit the latter, since for them the bundle is a dependency. Covering that path properly needs the bundle installed as a dependency of a scratch project, and wp-cli-tests currently offers no step for that — Given a dependency on current wp-cli hardcodes wp-cli/wp-cli, and {SRC_DIR} points at wp-cli-tests itself rather than the repo under test. An end-to-end Behat scenario here would need a wp-cli-tests change first. The installed.json path is worth covering directly in Add hints for commands that are not registered wp-cli#6386 instead.
• This job will be red until Add hints for commands that are not registered wp-cli#6386 lands, since the framework has no CommandHints on dev-main yet. That is the dependency showing up honestly in CI rather than being asserted only in prose.

Neither the job nor the hint text has been executed locally — the authoring environment could not complete a dependency install for this repo. The hint text itself was verified end to end against a simulated Composer project built from this composer.json, producing the output above, and composer validate passes with the regenerated lock hash.

Dependency

Requires wp-cli/wp-cli#6386 for the metadata to be read. Until that lands the metadata is inert but harmless — an unrecognized extra key that Composer ignores.

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 88959383-a7f6-4224-9ef3-b44cb3cc20b8

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!