Add support for the new meta.public flag - #10

Fixes #9.

WordPress 7.1 introduces meta.public as the high-level client exposure setting, with channel-specific flags taking precedence. Core resolves the cascade at registration, so show_in_rest already reports effective REST exposure — but meta.public itself was invisible, and there was no way to tell whether REST exposure came from the high-level flag or the channel flag.

What changed

• public is an optional field on list and a default field on get, ordered before show_in_rest.
• --public / --no-public filter on list.
• meta is an optional field on get, rendering raw metadata as JSON.
• Inline docs updated on the class docblock, list, and get — these generate the command reference pages, so they land here.

Nothing reimplements the precedence rules, and list still reports every registered ability regardless of exposure. WP-CLI runs with full trust; these are display and filter concerns, not access control.

Design decisions

public renders 1/0, not tri-state

Open question 1 asked whether public should render 1/0/empty the way readonly and friends do through format_annotation(). It can't, and shouldn't pretend to. WP_Ability::prepare_properties() always materializes the flag:

$args['meta']['show_in_rest'] = $args['meta']['show_in_rest'] ?? $args['meta']['public'] ?? self::DEFAULT_SHOW_IN_REST;
$args['meta']['public']       = $args['meta']['public'] ?? self::DEFAULT_PUBLIC;   // false

Core's own tests pin this down — test_meta_public_defaults_to_false_when_unset asserts the key is always present in get_meta(), test_meta_public_null_is_treated_as_unset collapses explicit null to false, and anything non-boolean throws. "Never declared" and "declared false" are indistinguishable by the time the command sees the ability, so an empty rendering could only ever mean "old WordPress", which is misleading.

The REST controller draws the same line: annotations are typed array( 'boolean', 'null' ), public is typed 'boolean'. format_annotation() exists because $default_annotations are null; public isn't in that category. It uses the same one-liner show_in_rest already does, which also keeps 6.9/7.0 sane where meta is unvalidated free-form.

Documentation only for the 6.9/7.0 gap — no runtime note

Open question 2 asked whether a WP_CLI::debug() note is worth it on versions where the flag is inert. It isn't. The ## AVAILABLE FIELDS docs on both list and get state that public has no effect before 7.1 and may therefore disagree with show_in_rest, and that is where someone puzzled by the output actually looks — --debug is not a flag you reach for before you know something is wrong.

An earlier revision of this PR added a once-per-run debug note; it was removed in 49800b1. It could only ever fire on 6.9 and 7.0, so it was dead code by construction, and cost a version check plus a pass over the displayed items on every run to say something the docs already say.

meta is optional on get, not default

Open question 3 proposed mirroring wp ability category get, where meta is a default field. This diverges deliberately: on 7.1 ability meta is {annotations, show_in_rest, public} plus channel keys, so a default column would duplicate five fields already rendered as their own rows, every call, on top of two JSON schema blobs. Category meta is default because a category has three other fields and meta is its only extensibility surface.

Optional still keeps the escape hatch — meta.mcp.public and friends have no field of their own, and Core treats nested channel meta as first-class (_wp_get_abilities_match_meta() matches nested arrays; array( 'mcp' => array( 'public' => true ) ) is the documented example). Worth noting mcp is not a Core-defined channel, which argues for a generic raw dump over any channel-specific field. Rendering matches Ability_Category_Command::format_category_for_get() exactly. Not added to list, where a JSON blob per row would wreck table output.

The exposure filters are plain flags

[--public] and [--show-in-rest] are declared as boolean flags rather than =<bool> params. Utils\get_flag_value() returns true for --public, false for --no-public, and null when absent, so each filter is a direct boolean comparison — no parsing, no validation code, no options block.

Earlier revisions of this PR tried a hand-rolled parse_bool_filter() (621cd5c, dc3d2db) and then declarative options: true/false (2db8a66). Both are gone as of d2a444b; the flag form is how WP-CLI models booleans and needs none of it.

Behavior change

--show-in-rest previously took a value: --show-in-rest=true / =false. It is now a flag, so those forms become --show-in-rest / --no-show-in-rest. Since flag-type params do not validate their values, an old-style --show-in-rest=true is accepted and then matches nothing rather than erroring — worth knowing if the released form is considered load-bearing.

That also fixes a latent bug in the old parsing: filter_var() with FILTER_NULL_ON_FAILURE returned null for an unparseable value and the guard then skipped the comparison entirely, so --show-in-rest=bogus silently became a no-op and listed every registered ability.

Notes

• The issue's background is slightly off. It says an ability written against 7.1 "produces identical CLI output on every supported version". For the current command it's the opposite: an ability declaring only meta.public => true renders show_in_rest 1 on 7.1 and show_in_rest 0 on 6.9/7.0, so output already tracked reachability. Adding the public field is what creates the divergent-looking output, which the field documentation now covers.
• wp_get_abilities( $args ) is deliberately not used. 7.1 added declarative filtering and array( 'meta' => array( 'public' => true ) ) looks like the obvious implementation. It's a trap: on 6.9/7.0 the function takes no parameters, PHP silently discards extra args to userland functions, and the command would return the entire unfiltered registry while claiming to have filtered. Filtering stays in the command loop.
• README.md is untouched — regenerate-readme.yml handles it on merge to main.
• These fields serialize as strings in JSON ("public":"1"), matching the existing readonly/show_in_rest convention rather than fixing it here.

Testing

Three scenarios added to features/ability.feature: public seeding show_in_rest, explicit show_in_rest => false winning over public => true, --public / --no-public filtering, and raw meta showing an mcp channel key while staying out of default output. The exposure scenarios are tagged @require-wp-7.1; the meta one works on 6.9 and is tagged accordingly. The existing show_in_rest filter scenario switches to the flag form.

No other existing scenario changes behavior — every table and JSON assertion in the file is containment-style, and every exact STDOUT should be: is a single --field= value.