feat(cli): add non-mutating buzz doctor command (#3926)

[iroiro147]

feat(cli): add non-mutating buzz doctor command (#3926)

Closes #3926.

What

Adds a root-level buzz doctor subcommand that runs independent local + remote readiness checks and aggregates them into a single structured JSON report, so users / agents / automation / support flows can answer "is my Buzz environment ready to use?" without --help trivia and without failing at the first problem.

Why

• Today troubleshooting means running a real command and interpreting the first error — a miss between local config, identity, reachability, auth, and membership all blur.
• Buzz Desktop has a Doctor surface for managed ACP runtimes, but that's a different scope and unavailable headlessly.
• A dedicated preflight fills the gap; this is the smallest useful slice per the issue's "first version" guidance.

How

Command

buzz doctor [--offline]

The subcommand is added directly to the top-level Cmd enum (not nested under a group), matching the existing architecture.

Dispatch order

run() in crates/buzz-cli/src/lib.rs is reshaped so doctor dispatches before the credential gate. Every other command still requires BUZZ_PRIVATE_KEY; doctor must remain usable when the broken environment is the one being debugged, so missing/malformed credentials surface as a check result (status error), not as an argument-time failure.

Checks (all independent, all run; one invocation reveals multiple problems)

Local, always-on:

• relay_url — presence, syntax, canonicalization via the same normalize_relay_url the rest of the CLI uses.
• identity — BUZZ_PRIVATE_KEY parseability. Key material is never printed; only the derived public identity (hex) is reported on success.
• auth_tag — BUZZ_AUTH_TAG parse + verification against the signing identity via buzz_sdk::nip_oa::parse_auth_tag / verify_auth_tag. The tag is never printed. When set but the identity is invalid, we degrade to warning.
• version — env!("CARGO_PKG_VERSION").

Remote (skipped when --offline):

• relay_reachable — an unauthenticated GET / with Accept: application/nostr+json, just to prove DNS/TLS/reachability.
• nip11 — fetches and parses the NIP-11 information document end-to-end. Done with a bare reqwest::Client so doctor works even when the identity is broken.
• auth_read — bounded authenticated read (single query_paginated call with limit=1) against kinds:[39002] #p=self. This doubles as the membership probe input.
• membership — interprets the previous call: zero events → warning ("not a member of any channel visible to this relay"), ≥1 events → ok.

--offline marks the four remote probes skipped and they do not affect the outcome.

Output

Single JSON document on stdout:

{
  "status": "ok" | "warning" | "error",
  "checks": [
    {
      "id": "relay_url" | "identity" | "auth_tag" | "version" | "relay_reachable" | "nip11" | "auth_read" | "membership",
      "status": "ok" | "warning" | "error" | "skipped",
      "message": "…",
      "remediation": "…" | null
    }
  ]
}

Field identifiers are stable for automation.

Exit behavior

• 0 when every applicable check is ok (warnings allowed; skipped never affects).
• 3 when any identity / auth_tag / auth_read check is error (auth-shaped).
• 2 when the only errors are relay_reachable / nip11 (transport-shaped), via CliError::Relay { status: 0, .. }.

This matches the existing 0=ok 1=bad input 2=relay 3=auth 4=other 5=conflict convention.

Never exposes

• Private key bytes, hex, bech32 — only the derived public identity.
• Auth tag JSON, owner pubkey embedded inside the tag, or any signed request material.

Testing

• 8 new unit tests in commands/doctor.rs covering:
  • all-ok → Ok(()), indico exit 0
  • warning-only → Ok(()), exit 0
  • identity error → CliError::Auth → exit 3
  • auth_read error → CliError::Auth → exit 3
  • relay_reachable error → CliError::Relay{0,..} → exit 2
  • mixed errors → auth wins
  • skipped never affects outcome
  • JSON shape has status + checks array with expected keys
• Updated command_inventory_is_stable to include doctor (22 groups).
• Full cargo test -p buzz-cli --lib: 279 passed, 0 failed.
• cargo clippy -p buzz-cli --all-targets -- -D warnings: clean.
• Smoke-tested: buzz doctor --help and buzz doctor --offline print the expected shapes; the latter exits 3 cleanly when BUZZ_PRIVATE_KEY is unset.

Out of scope (per the issue's own staging)

• WebSocket readiness probe (flagged in the issue as possibly-too-big for v1).
• Deeper runtime diagnostics (per-channel permission probes, ACP runtime health — Desktop's Doctor surface already owns ACP).
• Integration test against a real relay (would need a fixture relay; matches how other read-only commands are covered today).

Notes for reviewers

• The command is intentionally bind-mounted ahead of the credential gate; that's the load-bearing design decision, called out in code comments and module docs.
• relay_reachable and nip11 share an HTTP request path (both GET / with the metadata accept header); currently issued as two probes for clarity, easy to fuse if a reviewer prefers.
• The existing buzz users me / whoami work in feat(cli): add buzz users me for external-agent identity #2933 (when it lands) is complementary — it would give doctor a clean way to also report the resolved user profile, but isn't required for v1.

[iroiro147]

Added a follow-up commit d576d88a that tightens the exit-code classification. The first cut treated every authed-read failure as auth (exit 3), which was wrong for unreachable relays — on a DNS/connect failure the doctor should exit 2 and report the transport problem, not blame credentials. The new commit distinguishes true auth rejections (Auth variant or relay 401/403) from transport errors, and avoids double-reporting the reachability failure when both the public and authed probes go down. All 279 buzz-cli tests still pass; clippy clean.