Add hints for commands that are not registered - #6386

Problem

'x' is not a registered wp command says nothing about why a command is missing or how to get it. That is fine for typos, where the "Did you mean" suggestion carries the weight, but not for commands that exist and are simply unavailable in the installation at hand.

The motivating case is wp package. Since wp-cli/wp-cli-bundle#846 moved wp-cli/package-command to require-dev, it ships in the Phar but is absent from Composer-based installations. Those users currently get:

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

…with no indication that the command exists, that their install method is the reason, or that composer require wp-cli/package-command fixes it.

Approach

Packages can declare guidance for commands they know about through an extra.command-hints section in their composer.json:

"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 is deliberate: wp-cli-bundle has no autoload section of its own, so declaring this in composer.json is the only way it can speak. It also follows the existing extra.commands convention, and keeps the framework free of any hardcoded knowledge about which package provides what.

Changes

• WP_CLI\CommandHints collects hints from vendor/composer/installed.json and the root composer.json, with the root taking precedence. Malformed entries (non-string keys or values, blank strings) are skipped.
• Runner::find_command_to_run() appends a matching hint to the error, on both the top-level and subcommand branches. wp package install foo fails on the top-level package lookup, so a single hint covers every subcommand.
• unregistered_command_hint filter (2 args) lets a project supply or override guidance at runtime without Composer metadata.

Disk is only touched on the failure path, and hints are cached per process. A hint never displaces the existing "Did you mean" suggestion, and never appears for a command that is registered — so Phar users see no change at all.

Companion PR that declares the actual metadata: wp-cli/wp-cli-bundle (branch claude/wp-cli-package-composer-guidance-rve6ct). That one is inert without this change; this one is a no-op without a package that declares hints, so they can land in either order.

Result

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.

Testing

tests/CommandHintsTest.php covers collection, root-package precedence, and rejection of malformed entries, against fixtures in tests/data/command-hints/. A Behat scenario in features/command.feature covers the filter end to end on both error branches, and asserts no hint leaks onto an unrelated unknown command.

⚠️ composer test has not been run. The environment this was authored in has GitHub access scoped to two repos, so dist downloads for phpcs, phpstan, phpunit and wp-cli-tests all failed authentication and left their vendor directories empty. What was verified: php -l on every changed file, plus a standalone harness driving CommandHints against a simulated Composer project built from the real bundle composer.json — that confirmed the output above, root-package precedence, malformed-entry rejection, and the filter override. The PHPUnit assertions mirror that harness exactly but have not been executed, and neither PHPCS nor PHPStan (level 9) has seen the new code. Worth a close look at CI.

Generated by Claude Code