feat(cli)!: tidy --help output and make search a real command

[jpage-godaddy]

Summary

• --fields now shows its native clap default (like --dry-run's [default: false]) instead of a hardcoded fallback; the per-command Output fields: table moved from the command description into --fields's own help text, with each default field marked (default).
• --filter/--expr carry contextual usage examples on their own flags instead of a disconnected "Filter examples:"/"Expr examples:" section.
• --json/--toon/--human shorthand flags are hidden from --help (still fully functional) and documented on --output instead, whose displayed default now reflects the actual TTY-based choice rather than a hardcoded json.
• --dry-run is hidden from --help on commands that don't mutate, where it's a no-op.
• Command-specific flags render before global flags in --help, in declaration order, and global flags render in the engine's own declared order — fixes clap's colliding per-Command auto display-order counters, which previously interleaved the two. This also covers the conditionally-registered --env flag (added directly in Cli::new when CliConfig.environments is set), which Copilot's review caught was missing the same fix (refined during review).
• BREAKING CHANGE: --search is now a real search <query...> [--scope <path>] command instead of a raw-argv pre-parse bypass flag that silently discarded whatever command it was attached to (some-command --search x used to return empty results instead of running some-command or erroring). Removed the now-dead GlobalFlags.search, Middleware.search, and the public extract_search_query function.

Test plan

• cargo fmt --all --check
• cargo clippy --all-targets -- -D warnings
• RUSTDOCFLAGS='-D warnings' cargo doc --no-deps
• cargo rustdoc --lib -- -W missing-docs (zero)
• cargo test --all-targets
• cargo test --doc
• Verified against a real consumer CLI binary patched to this branch (help output, search/--scope, hidden-flag behavior, TTY-aware --output default)
• Regression test for the --env display-order fix, confirmed to fail against the pre-fix code

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR refines cli-engine’s help/UX around global flags and command help text, and turns legacy --search behavior into a first-class search <query...> [--scope <path>] built-in command (removing the pre-parse bypass and related public APIs).

Changes:

• Reworked help rendering: per-command output-fields table moved onto --fields, contextual examples moved onto --filter/--expr, and output-format shorthands are hidden and documented via --output.
• Fixed --help flag ordering by introducing explicit display-ordering for engine globals and enforcing declaration-order for command-specific flags.
• Replaced --search bypass with a real search built-in command, updating docs and tests and removing GlobalFlags.search, Middleware.search, and extract_search_query.

Reviewed changes

Copilot reviewed 15 out of 15 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
tests/foundation.rs	Updates/expands tests for help text, flag ordering, hidden shorthands, default fields marking, and new search command behavior.
tests/exhaustive_public_api.rs	Removes --search/search coverage from global flags parsing expectations.
tests/consumer_cli.rs	Updates consumer-style test to use search ... --scope ... instead of legacy --search.
tests/argv0_dispatch.rs	Updates argv0 dispatch test to invoke the search command.
src/output/schema.rs	Extends help-section formatting to mark default fields and removes standalone filter/expr examples section.
src/middleware.rs	Removes the legacy search field from middleware state.
src/lib.rs	Stops re-exporting removed extract_search_query API.
src/flags.rs	Adds explicit display-ordering for global flags; hides output shorthands; updates output help/default behavior; removes search flag and extraction helper.
src/command.rs	Forces command-specific arg ordering via explicit display_order in declaration order.
src/cli/help.rs	Updates root help “Find Commands” section to show search <keyword> as a command and improves alignment.
src/cli/builtins.rs	Introduces the search built-in command and args parsing.
src/cli.rs	Wires search into built-ins, removes search bypass, resolves --scope canonically, hides certain globals per-command, and filters hidden args out of search indexing.
docs/design.md	Updates documentation from --search bypass to search built-in command.
docs/concepts.md	Updates concepts documentation to the new search command and scope semantics.
docs/argv0-dispatch.md	Updates argv0 dispatch docs to reference the search command instead of --search.

Comments suppressed due to low confidence (1)

src/cli.rs:903

• The new explicit display_order scheme for global flags relies on every global arg having a high, non-colliding order. The conditional --env flag (registered when CliConfig.environments is set) is global(true) but has no display_order, so clap will assign it an implicit low order (likely 0) and it can interleave with command-specific args again, undermining the help-ordering fix for env-enabled CLIs.

            .subcommand(search_command());
        if let Some(register_flags) = &config.register_flags {
            root = register_flags(root);
        }
        // `--reason` is only meaningful when something actually consumes it —

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 15 out of 15 changed files in this pull request and generated no new comments.

[jpage-godaddy]

Here's a before and after for reference.

Before:

List the domains registered to your account. Shows domain, status, expiry, and auto-renew by default; use --fields to pick columns. Hides domains that are cancelled or otherwise not visible unless --show-hidden is passed; use --status to filter to specific status values (repeatable, overrides the default filter).

Output fields:
  authCode                string  (optional)
  contactAdmin            object  (optional)
  contactBilling          object  (optional)
  contactRegistrant       object  (optional)
  contactTech             object  (optional)
  createdAt               string  (optional)
  deletedAt               string  (optional)
  domain                  string  (optional)
  domainId                float  (optional)
  expirationProtected     bool  (optional)
  expires                 string  (optional)
  exposeWhois             bool  (optional)
  holdRegistrar           bool  (optional)
  locked                  bool  (optional)
  nameServers             []string  (optional)
  privacy                 bool  (optional)
  registrarCreatedAt      string  (optional)
  renewAuto               bool  (optional)
  renewDeadline           string  (optional)
  renewable               bool  (optional)
  status                  string  (optional)
  transferAwayEligibleAt  string  (optional)
  transferProtected       bool  (optional)

Filter examples:
  --filter "contains(authCode, 'example')"
  --filter 'expirationProtected'

Expr examples:
  --expr 'length(@)'
  --expr '[].authCode'


Usage: gddy domain list [OPTIONS]

Options:
  -h, --help
          Print help

      --status <STATUS>
          Only domains with this status, e.g. ACTIVE (repeatable)

  -o, --output <FORMAT>
          Output format: toon|json|human

          [default: json]

      --show-hidden
          Include domains hidden by default, e.g. cancelled or confiscated

      --verbose [<FIELDS>]
          Include metadata in output (all, or comma-separated: system,duration,args,env,identity,command,effective_args,timestamp)

      --dry-run[=<dry-run>]
          Preview mutations without executing

          [default: false]

      --fields <FIELDS>
          Comma-separated fields to include in output (use 'all' or '*' for everything)

      --filter <EXPR>
          Per-item JMESPath predicate for list data

      --expr <EXPR>
          JMESPath query applied to the whole result

      --limit <limit>
          Max items to return (client-side, 0=all)

          [default: 0]

      --offset <offset>
          Skip N items before applying limit

          [default: 0]

      --schema[=<schema>]
          Dump output field metadata instead of running the command

          [default: false]

      --timeout <DURATION>
          Overall command timeout (e.g. 60s, 5m); default 0s = no timeout

          [default: 0s]

      --debug [<PATTERN>]
          Enable debug logging (comma-separated component patterns, e.g. *, transport, *,-auth)

      --search <KEYWORD>
          Search commands and guides by keyword

      --credential-store <MODE>
          Credential storage: auto|keyring|file (overrides env and config)

      --json
          Shorthand for --output json

      --toon
          Shorthand for --output toon

      --human
          Shorthand for --output human

      --env <ENV>
          Override the active environment (see: env list)

After:

List the domains registered to your account. Shows domain, status, expiry, and auto-renew by default; use --fields to pick columns. Hides domains that are cancelled or otherwise not visible unless --show-hidden is passed; use --status to filter to specific status values (repeatable, overrides the default filter).

Usage: gddy domain list [OPTIONS]

Options:
      --status <STATUS>
          Only domains with this status, e.g. ACTIVE (repeatable)

      --show-hidden
          Include domains hidden by default, e.g. cancelled or confiscated

      --env <ENV>
          Override the active environment (see: env list)

  -h, --help
          Print help

  -o, --output <FORMAT>
          Output format: toon|json|human (shorthand: --json, --toon, --human); defaults to human in an interactive terminal, json otherwise

          [default: human]

      --verbose [<FIELDS>]
          Include metadata in output (all, or comma-separated: system,duration,args,env,identity,command,effective_args,timestamp)

      --fields <FIELDS>
          Comma-separated fields to include in output (use 'all' or '*' for everything)

          Output fields:
            authCode                string  (optional)
            contactAdmin            object  (optional)
            contactBilling          object  (optional)
            contactRegistrant       object  (optional)
            contactTech             object  (optional)
            createdAt               string  (optional)
            deletedAt               string  (optional)
            domain                  string  (optional)  (default)
            domainId                float  (optional)
            expirationProtected     bool  (optional)
            expires                 string  (optional)  (default)
            exposeWhois             bool  (optional)
            holdRegistrar           bool  (optional)
            locked                  bool  (optional)
            nameServers             []string  (optional)
            privacy                 bool  (optional)
            registrarCreatedAt      string  (optional)
            renewAuto               bool  (optional)  (default)
            renewDeadline           string  (optional)
            renewable               bool  (optional)
            status                  string  (optional)  (default)
            transferAwayEligibleAt  string  (optional)
            transferProtected       bool  (optional)

          [default: domain,status,expires,renewAuto]

      --filter <EXPR>
          Per-item JMESPath predicate for list data
          e.g. --filter "contains(authCode, 'example')"
          e.g. --filter 'expirationProtected'

      --expr <EXPR>
          JMESPath query applied to the whole result
          e.g. --expr 'length(@)'
          e.g. --expr '[].authCode'

      --limit <limit>
          Max items to return (client-side, 0=all)

          [default: 0]

      --offset <offset>
          Skip N items before applying limit

          [default: 0]

      --schema[=<schema>]
          Dump output field metadata instead of running the command

          [default: false]

      --timeout <DURATION>
          Overall command timeout (e.g. 60s, 5m); default 0s = no timeout

          [default: 0s]

      --debug [<PATTERN>]
          Enable debug logging (comma-separated component patterns, e.g. *, transport, *,-auth)

      --credential-store <MODE>
          Credential storage: auto|keyring|file (overrides env and config)