feat: agent-first root discovery, curated help, and TTY-aware output (DEVEX-695)

[jpage-godaddy]

Addresses Rust-port review item #2 (PR #49 review) · DEVEX-695

Original concern (item 2): the TypeScript CLI root returned JSON discovery (command tree + environment/auth snapshot + next actions); the Rust port renders clap long-help text for the empty command path → an agent-first discovery regression.

How each part of that concern is handled here:

Review item #2 expectation	Status	Notes
Bare root returns JSON for agents (the regression)	✅ Addressed	Empty command path now emits a JSON discovery envelope in machine context (piped / CI / agent, or --output json).
next actions	✅ Addressed (superset)	Original three (auth status, env get, application list) + tree.
command tree inline	🔀 Pivot	Surfaced as a next_actions pointer to tree (godaddy tree --output json returns the full tree) instead of embedded — hypermedia model.
environment / auth snapshot inline	🔀 Pivot	Reachable via the env get / auth status pointers instead of embedded.
Always-JSON default	🔀 Pivot	TTY-aware default instead (human in a terminal, JSON when piped/CI/agent), with --output / ${APP_ID}_OUTPUT overrides. Whether to force always-JSON is left for the team.

Net: agent-first discovery is restored, in a leaner hypermedia form — the bare command returns pointers and the agent follows tree / auth status / env get for details, rather than one fat payload. Nothing from item 2 was dropped silently; each element is either restored or a deliberate pivot above.

Scope: this PR is the cli-engine capability. The godaddy CLI adopts it (calls with_root_next_actions(...) and rides the TTY-aware default) in a follow-up PR once this releases; that PR will be linked to DEVEX-695.

---

Summary

Makes the bare-invocation and help experience friendlier for humans without sacrificing machine-readable output for agents. Three related engine changes:

1. Root discovery (with_root_next_actions)

New opt-in CliConfig::with_root_next_actions hook. On bare invocation (no subcommand):

• human output appends a "Suggested next actions" section (cold-start guidance), and
• machine output emits a small discovery envelope — { data: { description, version }, next_actions }.

Actions are pointers to existing commands (e.g. auth status, env get, tree), not embedded snapshots — the agent follows only what it needs. With no hook configured, behavior is unchanged long-help (back-compat for existing consumers).

2. Curated root/group help

• A root help template suppresses clap's duplicate command list and the global-options wall (still shown on leaf commands, where they matter).
• Group pages keep their subcommand list but drop the options wall.
• Categories — and the commands within each — are sorted.
• The engine-injected auth command is filed under an admin category (CliConfig::with_admin_category, default "Admin") so it stays discoverable once the auto list is suppressed; any uncategorized top-level command falls under a generic "Commands" section, so nothing is ever lost.

3. TTY-aware default output format

Default output is now human on an interactive terminal, JSON otherwise (pipes, files, CI, most agents). Precedence:

1. explicit --output/--json/--toon/--human
2. ${APP_ID}_OUTPUT env (e.g. GODADDY_OUTPUT=json, GDX_OUTPUT=json)
3. TTY policy

Uses std::io::IsTerminal — no new dependency. Agents that capture output via pipes (the norm) keep getting JSON automatically; PTY-backed agents can force it via the env var or a flag.

Why

Restores agent-first discoverability for the bare command (the original TypeScript GoDaddy CLI returned JSON discovery on bare invocation; ref DEVEX-695) while making the human terminal experience pleasant — the engine is shared by the godaddy CLI and gdx.

Consumers

No consumer code change is required. There is, however, one runtime behavior change on dependency bump: with the TTY-aware default, interactive-terminal invocations now default to human output where they previously got JSON — across all commands, including the --search and --schema raw-bypass paths (previously hardcoded to JSON). Machine / piped / CI / agent output is unchanged (still JSON), so real-world breakage is low. Prior behavior is fully preserved via explicit --output/--json/--toon/--human or the ${APP_ID}_OUTPUT env (e.g. GODADDY_OUTPUT=json). Whether to instead force always-JSON is an open one-way-door decision for the team to settle before release.

The godaddy CLI adopts the with_root_next_actions hook (and rides the "Admin" default) in a follow-up PR once this releases; gdx is unaffected until it bumps the dependency (it would set with_admin_category("Administration")).

Testing

• New unit tests for the output-format resolver and env-var derivation (pure, no real TTY needed).
• New consumer/foundation tests for bare-root human + JSON paths, group/leaf help shaping, and auth categorization (default + override).
• Full suite green; clippy -D warnings clean; cargo fmt applied.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR improves the “bare invocation” and help UX while preserving agent-friendly machine output by adding (1) an opt-in root discovery hook with next-action suggestions, (2) curated/sorted root & group help templates that suppress clap’s noisy sections, and (3) a TTY-aware default output-format resolver with an ${APP_ID}_OUTPUT override.

Changes:

• Add CliConfig::with_root_next_actions and render bare-root output as either human help + “Suggested next actions” or a JSON discovery envelope (when explicitly machine output / non-TTY default).
• Introduce curated help templates for root and group commands; sort categories and commands; ensure the built-in auth command is listed under an admin category.
• Implement default output format resolution with env + TTY policy; update public exports and adjust tests for the new flag-resolution APIs.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
src/cli.rs	Adds root next-actions hook, curated help behavior, admin categorization for auth, and bare-root discovery rendering.
src/cli/help.rs	Adds root/group help templates, sorts help categories/entries, and renders human “Suggested next actions”.
src/flags.rs	Adds TTY/env-based default output resolver + env var derivation; adjusts flag extraction APIs and adds unit tests.
src/lib.rs	Re-exports new public APIs/types related to root actions and output-format resolution.
tests/consumer_cli.rs	Adds contract tests for bare-root discovery (human + JSON), group/leaf help shaping, and next-actions behavior.
tests/foundation.rs	Updates raw-arg output-format extraction tests and adds tests for auth help categorization (default + override).
tests/exhaustive_public_api.rs	Updates tests for the new global_flags_from_matches(..., default_format) signature.
tests/exhaustive_cli_contract.rs	Updates tests for the new global_flags_from_matches(..., default_format) signature.

---

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

[Copilot]

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated 1 comment.

[jgowdy-godaddy]

Did a deep review pass. Pushed two changes directly to the branch:

• 01f7dab — render_root was parsing the output format via the infallible OutputFormat::from_str, so an unrecognized explicit --output yaml on the bare-root discovery path silently coerced to JSON instead of erroring like normal commands do (Middleware::render_envelope → InvalidOutputFormat). Added up-front validation + a regression test.
• 494b027 — deterministic, TTY/env-independent tests for the resolved-default wiring (global_flags_from_matches / extract_output_format fall through to the supplied default when no explicit format is given; explicit --output/--json/--toon/--human still wins), using a non-json default so they guard the value_source == CommandLine gate against regression.

fmt/clippy/full suite/doc-tests/missing-docs all green locally.

One non-blocking item I'd rather discuss than just change:

Back-compat wording vs. the always-JSON decision. The default output format change is TTY-aware for every consumer on dependency bump, and it also now applies to the --search and --schema raw-bypass paths (previously hardcoded JSON). So "No consumer change required to keep current behavior" isn't quite accurate for interactive-terminal usage — a human in a TTY now gets human output where they previously got JSON. Machine/piped/CI/agent paths are unaffected (still JSON), so real-world breakage is low, but I'd reword the back-compat note to be explicit about the interactive-terminal change. This also ties into the open question the PR itself raises ("whether to force always-JSON is left for the team") — worth nailing that down before release since it's a one-way door on the human UX contract.

Everything else looked sound: the value_source == CommandLine gate is the right way to keep --output's default_value("json") from clobbering the TTY policy, the explicit --json arm fixes a latent bug where it was previously ignored, and auth categorization is correctly idempotent across post-construction register_auth_provider.

[jgowdy-godaddy]

Approved with comments for consideration

[jpage-godaddy]

Reworded the back-compat note in the description: it now states explicitly that interactive-terminal invocations switch from JSON to human on dependency bump (including the --search/--schema bypass paths), while machine/piped/CI/agent output stays JSON, with --output/--json/${APP_ID}_OUTPUT preserving prior behavior.

Your two commits look correct. render_root was relying on a dead Err arm (OutputFormat::from_str is infallible, so an explicit --output yaml silently coerced to JSON) — validating up front against is_valid_output_format is right and matches Middleware::render_envelope. The TTY/env-independent default fall-through tests are a good guard on the value_source == CommandLine gate.

On the always-JSON one-way-door: agreed it should be settled before release. That's a product call for the CLI owner rather than something to decide in this PR — taking it back to them and will follow up here with the decision.