block / block/buzz

Docs: two setup-path instructions that don't exist in the binaries (messages search --kinds, buzz-admin mint-token)

Open Beginner friendly
#5,663 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

## Summary

Two contributor-facing docs instruct you to run things the binaries do not have. Both fail at argv parsing, so nothing is silently wrong — but both are on the setup path, where a new contributor (or an agent following `AGENTS.md`) has no way to tell a broken instruction from a broken environment.

## 1. `AGENTS.md` says `messages search` needs `--kinds`. There is no such flag.

`AGENTS.md` § Common Gotchas, item 3:

> **`messages search` must include `--kinds`** — an open-ended search (no kinds) hits the relay p-gate and returns 403. Pass at least `--kinds 9,45001,45003` to scope the query.

`MessagesCmd::Search` (`crates/buzz-cli/src/lib.rs:502-516`) takes only `--query`, `--author`, `--since`, `--limit`. Following the gotcha gets you:

```console
$ buzz messages search --query foo --kinds 9,45001,45003
error: unexpected argument '--kinds' found
```

The advice is also unnecessary: `cmd_search_messages` sets its own kind filter, so an open-ended search never trips the p-gate in the first place —

```rust
// crates/buzz-cli/src/commands/messages.rs:451
"kinds": [9, 40002, 45001, 45003],
```

The gotcha inverts the actual situation. `messages get --channel --kinds 9` (`lib.rs:466-482`) is the subcommand that takes kinds — worth naming, because "did event X land in this channel with kind Y" is exactly the question that sends people to `search` first.

## 2. `crates/buzz-cli/TESTING.md` § 4 tells you to mint a token with a subcommand that doesn't exist.

`TESTING.md:66`:

```bash
cargo run -p buzz-admin -- mint-token \
--name "cli-test" \
--scopes "messages:read,messages:write,…,admin:channels"
```

`buzz-admin`'s `Command` enum (`crates/buzz-admin/src/main.rs:42-97`) is `add-member`, `remove-member`, `list-members`, `generate-key`, `migrate`, `product-feedback`, `reconcile-channels`. No `mint-token`. It is the first credential step in the CLI testing runbook, so it blocks the whole document.

Nor is there another way to get one. Scoped API tokens exist in the schema and the data layer (`crates/buzz-db/src/api_token.rs`, `create_api_token` at `:15`), but `grep -rn create_api_token --include='*.rs' crates/ | grep -v crates/buzz-db/` returns **nothing** — no relay route and no admin command calls it. So the "Scope reference" table below it, which promises nine self-mintable scopes, describes a credential no stock deployment can issue.

What actually authorizes a CLI identity is pubkey plus membership role: the relay authenticates the event's key (NIP-42 over WebSocket, NIP-98 over HTTP) and authorizes against the relay-membership and per-channel role. The working setup is `generate-key` → `add-member` → export `BUZZ_PRIVATE_KEY`. Without that key every relay command exits **3** (`CliError::Auth` → `3`, `crates/buzz-cli/src/error.rs:101`).

## Fix

I have both corrections written and verified locally against the tree (AGENTS.md gotcha rewritten; TESTING.md § 4 replaced with the identity + membership flow, and the scope table replaced with what genuinely needs owner/admin standing). I don't have push access to this repo, so I can't open the PR from a branch here — happy to send it however maintainers prefer.

Contributor guide

Open the contributing guide

Research direction

Start with the cited sections of AGENTS.md and crates/buzz-cli/TESTING.md, then compare their commands with MessagesCmd in crates/buzz-cli/src/lib.rs, cmd_search_messages in crates/buzz-cli/src/commands/messages.rs, and Command in crates/buzz-admin/src/main.rs. Done means both setup paths use commands and credential steps present in the repository, with the scope guidance matching what a stock deployment can issue.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
cli, documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
76/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.