block / block/buzz

Feature request: add a non-mutating `buzz doctor` command

Open
#3,926 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Rust
Stars
32.7k
Forks
4.3k
Avg merge
1d 13h
Merged PRs (30d)
253

Description

**Motivation**

The CLI has comprehensive command help, but `--help` cannot answer whether a Buzz environment is actually ready to use. Today, troubleshooting usually means running a real command and interpreting the first error it returns.

A single safe preflight would help humans, agents, automation, and support reports answer:

- Is the local configuration present and parseable?
- Which public identity will sign requests?
- Is the relay reachable and does it return valid NIP-11 metadata?
- Is authentication accepted?
- Is the identity a member of the selected community?

Buzz Desktop has a Doctor surface for managed ACP runtimes, but that has a different scope and is unavailable in headless environments, containers, and servers.

**Proposed solution**

Add a root-level `buzz doctor` command that runs independent checks, aggregates the results rather than failing at the first problem, and never publishes events or changes local or remote state.

A useful first slice could include:

Local checks, available even with `--offline`:

- CLI version/build information
- relay URL presence, syntax, and canonicalization
- `BUZZ_PRIVATE_KEY` presence and parseability, reporting only the derived public identity
- `BUZZ_AUTH_TAG` syntax and basic consistency, without ever printing the tag

Read-only remote checks:

- DNS/TLS/network reachability
- NIP-11 retrieval and basic compatibility
- authenticated read access
- community membership and available role/scope information
- WebSocket connection or subscription readiness, without publishing an event

The command should use the existing global relay, key, auth-tag, and output-format options. Default structured output could follow the existing CLI convention, for example:

```json
{
"status": "warning",
"checks": [
{
"id": "identity",
"status": "ok",
"message": "Signing identity is available"
},
{
"id": "relay",
"status": "error",
"message": "Relay is unreachable",
"remediation": "Check the relay URL and network connectivity"
}
]
}
```

Required behavior:

- Running with missing or invalid credentials reports those as check results instead of failing during CLI argument parsing.
- `--offline` runs only local checks and clearly marks remote checks as skipped.
- Remote probes are read-only.
- All applicable checks run so one invocation can reveal multiple problems.
- Output and error messages never expose private keys, auth tags, bearer values, or signed request material.
- Check identifiers and structured fields are stable enough for automation.
- Exit behavior distinguishes a failed required check from warnings while preserving structured output. I would welcome maintainer guidance on whether warnings should still exit zero and how this should map onto the existing exit-code categories.

Suggested coverage:

- unit tests for aggregation, redaction, skipped checks, and exit precedence
- mocked relay tests for unreachable, malformed NIP-11, unauthenticated, and non-member cases
- a CLI-definition test proving `doctor --help` remains available without credentials

For the initial version, local configuration plus NIP-11, read-only authentication, and membership checks may be enough; WebSocket readiness could follow separately if it adds too much scope.

**Alternatives considered**

- Run a harmless existing read command such as `channels list`: this fails fast, does not cover local configuration, and can blur network, authentication, and membership failures.
- Use the Desktop Doctor: it diagnoses managed agent runtimes rather than CLI-to-community readiness and is not available headlessly.
- Use shell scripts and `curl`: these duplicate Buzz signing/authentication behavior and make secret handling less reliable.
- Improve individual error messages only: useful, but it does not provide proactive, aggregated readiness information.

**Additional context**

- The prior Doctor issue, #76, was specifically for the Desktop ACP setup surface and was completed by #80.
- PR #2933 proposes `buzz users me` with a `whoami` alias. A doctor command should reuse the same local identity derivation if that lands, not introduce a competing identity command.
- I searched open and closed issues and PRs for `doctor`, `diagnostic`, `health check`, `preflight`, and `troubleshoot`; I found no existing CLI diagnostics proposal.
- A local audit of current `main` found that `--help` succeeds across all exposed CLI command paths, so this proposal is about runtime readiness rather than help coverage.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.