From e907a8a39a4d08d63db2753608227060d6fb6ca8 Mon Sep 17 00:00:00 2001 From: jewoos2921 <40465417+jewoos2921@users.noreply.github.com> Date: Wed, 29 Jul 2026 14:06:03 +0900 Subject: [PATCH] docs: enable missing_docs + document public APIs in 4 crates Add #![warn(missing_docs)] and crate-level //! docs to buzz-cli, buzz-acp, buzz-dev-mcp, and buzz-ws-client, clearing all missing_docs warnings. Core crates (buzz-core, buzz-auth, buzz-db, etc.) already enforce missing_docs; this extends the same standard to the auxiliary crates that were missing it, improving rustdoc output and API discoverability. Changes per crate: - buzz-ws-client: crate doc + 3 module docs - buzz-acp: crate doc + run() function doc - buzz-dev-mcp: crate doc + run() function doc - buzz-cli: crate doc + ~70 items (enums, variants, struct fields, functions across lib.rs, agent_management.rs, main.rs) All changes are doc-comment-only (132 insertions, 0 deletions). --- crates/buzz-acp/src/lib.rs | 15 +++++++ crates/buzz-cli/src/agent_management.rs | 29 ++++++++++++ crates/buzz-cli/src/lib.rs | 59 +++++++++++++++++++++++++ crates/buzz-cli/src/main.rs | 5 +++ crates/buzz-dev-mcp/src/lib.rs | 14 ++++++ crates/buzz-ws-client/src/lib.rs | 10 +++++ 6 files changed, 132 insertions(+) diff --git a/crates/buzz-acp/src/lib.rs b/crates/buzz-acp/src/lib.rs index d63f720c65..e1de4c8049 100644 --- a/crates/buzz-acp/src/lib.rs +++ b/crates/buzz-acp/src/lib.rs @@ -1,4 +1,13 @@ #![deny(unsafe_code)] +#![warn(missing_docs)] +//! ACP (Agent Communication Protocol) harness that bridges Buzz relay events +//! to AI agent subprocesses. +//! +//! The harness subscribes to a Buzz relay, routes incoming messages (mentions, +//! reminders, workflow approvals) to managed agent processes via ACP, and +//! publishes their responses back to the relay. It manages the full agent +//! lifecycle: process pooling, turn queuing per channel, rate limiting, +//! observer telemetry, and usage tracking. mod acp; mod config; @@ -1228,6 +1237,12 @@ impl Drop for RespawnGuard { // sync entry point — `std::env::set_var` is only safe before tokio spawns // worker threads (Rust 2024 edition safety requirement). +/// Entry point for the ACP harness binary. +/// +/// Propagates legacy environment variables synchronously (before the tokio +/// runtime starts), then hands off to the async main loop which connects to +/// the relay, subscribes to agent-relevant events, and manages agent +/// subprocesses. pub fn run() -> Result<()> { config::propagate_legacy_env_vars(); tokio_main() diff --git a/crates/buzz-cli/src/agent_management.rs b/crates/buzz-cli/src/agent_management.rs index ce4059f821..fe6cfe48cc 100644 --- a/crates/buzz-cli/src/agent_management.rs +++ b/crates/buzz-cli/src/agent_management.rs @@ -10,29 +10,44 @@ const REQUEST_KIND: &str = "agent_management_request"; const MAX_NAME_CHARS: usize = 120; const MAX_PROMPT_CHARS: usize = 20_000; +/// Owner-reviewed request to create a new personal agent. #[derive(Debug, Clone, Serialize)] #[serde(rename_all = "camelCase")] pub struct CreateAgentDraft { + /// UUID of the channel the agent will be added to. pub channel_id: String, + /// Proposed display name for the agent. pub display_name: String, + /// Proposed system prompt / instructions for the agent. pub system_prompt: String, } +/// Owner-reviewed request to update an existing personal agent. +/// +/// At least one optional field must be set; an all-`None` request is rejected. #[derive(Debug, Clone, Serialize)] #[serde(rename_all = "camelCase")] pub struct UpdateAgentDraft { + /// UUID of the channel the agent belongs to. pub channel_id: String, + /// Current name of the personal agent to update. pub agent_name: String, + /// New display name, if changing it. #[serde(skip_serializing_if = "Option::is_none")] pub display_name: Option, + /// Replacement system prompt, if changing it. #[serde(skip_serializing_if = "Option::is_none")] pub system_prompt: Option, + /// New runtime identifier, if changing it. #[serde(skip_serializing_if = "Option::is_none")] pub runtime: Option, + /// New model provider identifier, if changing it. #[serde(skip_serializing_if = "Option::is_none")] pub provider: Option, + /// New model identifier, if changing it. #[serde(skip_serializing_if = "Option::is_none")] pub model: Option, + /// Who the agent may respond to (`owner-only` or `anyone`), if changing it. #[serde(skip_serializing_if = "Option::is_none")] pub respond_to: Option, } @@ -60,10 +75,15 @@ struct ObserverEvent { payload: ManagementRequest, } +/// A signed agent-management observer frame ready to publish, plus the +/// identifiers needed to correlate the relay response with the request. #[derive(Debug)] pub struct BuiltDraftRequest { + /// The signed Nostr observer frame event carrying the encrypted request. pub event: Event, + /// UUID of this draft request, for correlating the owner's response. pub request_id: String, + /// The request action: `create` or `update`. pub action: &'static str, } @@ -125,6 +145,10 @@ fn build( }) } +/// Build and sign an owner-reviewed agent-creation draft request. +/// +/// Validates the channel UUID, display name, and system prompt length, then +/// encrypts the request to the owner and wraps it in a signed observer frame. pub fn build_create( keys: &Keys, owner: &PublicKey, @@ -141,6 +165,11 @@ pub fn build_create( build(keys, owner, channel_id, "create", request) } +/// Build and sign an owner-reviewed agent-update draft request. +/// +/// Validates the channel UUID and each supplied field, requires at least one +/// field to change, then encrypts the request to the owner and wraps it in a +/// signed observer frame. pub fn build_update( keys: &Keys, owner: &PublicKey, diff --git a/crates/buzz-cli/src/lib.rs b/crates/buzz-cli/src/lib.rs index 0b46734584..e0d484a8b7 100644 --- a/crates/buzz-cli/src/lib.rs +++ b/crates/buzz-cli/src/lib.rs @@ -1,3 +1,12 @@ +//! Agent-first CLI for the Buzz relay. +//! +//! `buzz` is the command-line interface for interacting with a Buzz relay: +//! sending and reading messages, managing channels and users, working with +//! git-backed patches/issues/PRs (NIP-34), and driving agent draft requests. +//! Auth is keypair-based — `BUZZ_PRIVATE_KEY` is the identity — with an +//! optional NIP-OA `BUZZ_AUTH_TAG` attestation injected by the ACP harness. +#![warn(missing_docs)] + pub mod agent_management; mod client; mod commands; @@ -97,10 +106,13 @@ struct Cli { command: Cmd, } +/// Channel topology: linear stream or threaded forum. #[derive(Clone, clap::ValueEnum)] pub enum ChannelType { + /// Linear, chat-style channel. #[value(name = "stream")] Stream, + /// Threaded, post-style forum channel. #[value(name = "forum")] Forum, } @@ -114,10 +126,13 @@ impl std::fmt::Display for ChannelType { } } +/// Channel membership visibility. #[derive(Clone, clap::ValueEnum)] pub enum ChannelVisibility { + /// Anyone can discover and join the channel. #[value(name = "open")] Open, + /// Membership is invite-only. #[value(name = "private")] Private, } @@ -131,20 +146,27 @@ impl std::fmt::Display for ChannelVisibility { } } +/// User presence status reported via NIP-38. #[derive(Clone, clap::ValueEnum)] pub enum PresenceStatus { + /// Actively available. #[value(name = "online")] Online, + /// Available but idle. #[value(name = "away")] Away, + /// Not available. #[value(name = "offline")] Offline, } +/// Which custom-emoji set to operate on. #[derive(Clone, clap::ValueEnum)] pub enum EmojiScope { + /// Only the current identity's own emoji set. #[value(name = "own")] Own, + /// The full workspace palette (union of all members' sets). #[value(name = "workspace")] Workspace, } @@ -238,10 +260,13 @@ enum Cmd { Moderation(ModerationCmd), } +/// Who a personal agent may respond to. #[derive(Clone, Copy, clap::ValueEnum)] pub enum RespondToArg { + /// Only the owner may invoke the agent. #[value(name = "owner-only")] OwnerOnly, + /// Any channel member may invoke the agent. #[value(name = "anyone")] Anyone, } @@ -256,6 +281,7 @@ impl RespondToArg { } } +/// `buzz agents` subcommands. #[derive(Subcommand)] pub enum AgentsCmd { /// Open a prefilled create-agent form in the owner's Buzz Desktop @@ -278,17 +304,22 @@ pub enum AgentsCmd { /// Current name of the personal agent to update #[arg(long)] agent_name: String, + /// Proposed display name #[arg(long)] display_name: Option, /// Replacement instructions; use '-' to read from stdin #[arg(long)] system_prompt: Option, + /// Agent runtime identifier #[arg(long)] runtime: Option, + /// Model provider identifier #[arg(long)] provider: Option, + /// Model identifier #[arg(long)] model: Option, + /// Who the agent may respond to #[arg(long, value_enum)] respond_to: Option, }, @@ -344,6 +375,7 @@ buzz agents archived" Archived, } +/// `buzz messages` subcommands. #[derive(Subcommand)] pub enum MessagesCmd { /// Send a message to a channel @@ -498,6 +530,7 @@ pub enum MessagesCmd { }, } +/// `buzz channels` subcommands. #[derive(Subcommand)] pub enum ChannelsCmd { /// List channels visible to the current identity @@ -675,6 +708,7 @@ pub enum ChannelsCmd { }, } +/// `buzz canvas` subcommands. #[derive(Subcommand)] pub enum CanvasCmd { /// Get the canvas document for a channel @@ -694,6 +728,7 @@ pub enum CanvasCmd { }, } +/// `buzz reactions` subcommands. #[derive(Subcommand)] pub enum ReactionsCmd { /// Add an emoji reaction to a message @@ -725,6 +760,7 @@ pub enum ReactionsCmd { }, } +/// `buzz emoji` subcommands. #[derive(Subcommand)] pub enum EmojiCmd { /// List the workspace custom emoji palette (union of every member's set) @@ -767,6 +803,7 @@ pub enum EmojiCmd { }, } +/// `buzz dms` subcommands. #[derive(Subcommand)] pub enum DmsCmd { /// List direct message conversations @@ -798,6 +835,7 @@ pub enum DmsCmd { }, } +/// `buzz users` subcommands. #[derive(Subcommand)] pub enum UsersCmd { /// Look up user profiles by pubkey or name @@ -853,6 +891,7 @@ pub enum UsersCmd { }, } +/// `buzz workflows` subcommands. #[derive(Subcommand)] pub enum WorkflowsCmd { /// List workflows in a channel @@ -932,6 +971,7 @@ pub enum WorkflowsCmd { }, } +/// `buzz feed` subcommands. #[derive(Subcommand)] pub enum FeedCmd { /// Get recent activity feed entries @@ -948,6 +988,7 @@ pub enum FeedCmd { }, } +/// `buzz social` subcommands. #[derive(Subcommand)] pub enum SocialCmd { /// Publish a text note (NIP-01 kind:1) @@ -1025,6 +1066,7 @@ pub enum SocialCmd { }, } +/// `buzz notes` subcommands. #[derive(Subcommand)] pub enum NotesCmd { /// Create or update a note. Idempotent upsert keyed by `(me, --name)`. @@ -1104,6 +1146,7 @@ pub enum NotesCmd { }, } +/// `buzz repos` subcommands. #[derive(Subcommand)] pub enum ReposCmd { /// Announce a git repository (NIP-34) @@ -1202,6 +1245,7 @@ pub enum RepoPushRole { Member, } +/// `buzz patches` subcommands. #[derive(Subcommand)] pub enum PatchesCmd { /// Send a git patch (NIP-34 kind:1617) @@ -1308,6 +1352,7 @@ pub enum PatchesCmd { }, } +/// `buzz pr` subcommands. #[derive(Subcommand)] pub enum PrCmd { /// Open a git pull request (NIP-34 kind:1618) @@ -1452,6 +1497,7 @@ pub enum PrCmd { }, } +/// `buzz issues` subcommands. #[derive(Subcommand)] pub enum IssuesCmd { /// Create a git issue (NIP-34 kind:1621) @@ -1527,6 +1573,7 @@ pub enum IssuesCmd { }, } +/// `buzz upload` subcommands. #[derive(Subcommand)] pub enum UploadCmd { /// Upload a file to the relay's Blossom store @@ -1537,6 +1584,7 @@ pub enum UploadCmd { }, } +/// `buzz media` subcommands. #[derive(Subcommand)] pub enum MediaCmd { /// Download relay media with Blossom get auth @@ -1566,7 +1614,9 @@ pub enum MemCmd { }, /// Print the value of a slug to stdout (no trailing newline) Get { + /// Slug of the memory entry to read. slug: String, + /// Owner pubkey (hex). Overrides BUZZ_AUTH_TAG. #[arg(long)] owner: Option, /// Agent pubkey (hex) to read as this key's owner. @@ -1575,7 +1625,9 @@ pub enum MemCmd { }, /// Print sha256(value) in hex (use as `--base-hash` for `mem patch`). Hash { + /// Slug whose value to hash. slug: String, + /// Owner pubkey (hex). Overrides BUZZ_AUTH_TAG. #[arg(long)] owner: Option, /// Agent pubkey (hex) to read as this key's owner. @@ -1584,8 +1636,11 @@ pub enum MemCmd { }, /// Set a slug's value. Pass `-` to read the value from stdin. Set { + /// Slug of the memory entry to write. slug: String, + /// New value, or `-` to read from stdin. value: String, + /// Owner pubkey (hex). Overrides BUZZ_AUTH_TAG. #[arg(long)] owner: Option, /// Allow committing an empty value. Without this, a zero-byte stdin @@ -1600,6 +1655,7 @@ pub enum MemCmd { /// slug has changed since `--base-hash` was captured, and refuses /// hunks whose context doesn't match the current value verbatim. Patch { + /// Slug of the memory entry to patch. slug: String, /// Read the patch from a file instead of stdin. #[arg(long)] @@ -1621,12 +1677,15 @@ pub enum MemCmd { /// Allow committing an empty result. #[arg(long, default_value_t = false)] allow_empty: bool, + /// Owner pubkey (hex). Overrides BUZZ_AUTH_TAG. #[arg(long)] owner: Option, }, /// Publish a tombstone for a slug (cannot be used on `core`). Rm { + /// Slug of the memory entry to tombstone. slug: String, + /// Owner pubkey (hex). Overrides BUZZ_AUTH_TAG. #[arg(long)] owner: Option, }, diff --git a/crates/buzz-cli/src/main.rs b/crates/buzz-cli/src/main.rs index ff337776b3..6d743a13aa 100644 --- a/crates/buzz-cli/src/main.rs +++ b/crates/buzz-cli/src/main.rs @@ -1,3 +1,8 @@ +//! Binary entry point for the `buzz` CLI. +//! +//! Parses `std::env::args()` via [`buzz_cli::run_from_args`] and exits with the +//! returned process code. + #[tokio::main] async fn main() { std::process::exit(buzz_cli::run_from_args(std::env::args()).await); diff --git a/crates/buzz-dev-mcp/src/lib.rs b/crates/buzz-dev-mcp/src/lib.rs index 9b98974802..d22e14511b 100644 --- a/crates/buzz-dev-mcp/src/lib.rs +++ b/crates/buzz-dev-mcp/src/lib.rs @@ -1,5 +1,13 @@ #![cfg_attr(not(windows), forbid(unsafe_code))] #![cfg_attr(windows, deny(unsafe_code))] +#![warn(missing_docs)] +//! Developer MCP (Model Context Protocol) server providing shell, file-edit, +//! and search tools for `buzz-agent`. +//! +//! Exposes tools over stdio for agent-driven development workflows: shell +//! command execution, file reading/editing, ripgrep search, directory trees, +//! todo management, and image viewing. Supports multicall dispatch so a single +//! binary can serve as `rg`, `tree`, or other tool personalities. use rmcp::{ handler::server::{router::tool::ToolRouter, wrapper::Parameters}, model::{CallToolResult, ServerCapabilities, ServerInfo}, @@ -135,6 +143,12 @@ impl ServerHandler for DevMcp { } } +/// Entry point for the dev-mcp binary. +/// +/// Dispatches to the appropriate tool personality based on the binary name +/// (argv[0]): `rg` for ripgrep, `tree` for directory listing, or the full MCP +/// server for the default `buzz-dev-mcp` name. Multicall personalities exit +/// synchronously before any async runtime is started. pub fn run() -> Result<(), Box> { let argv0 = std::env::args().next().unwrap_or_default(); let cmd = Path::new(&argv0) diff --git a/crates/buzz-ws-client/src/lib.rs b/crates/buzz-ws-client/src/lib.rs index 02c7d4b1b2..c9b2a6e76f 100644 --- a/crates/buzz-ws-client/src/lib.rs +++ b/crates/buzz-ws-client/src/lib.rs @@ -1,7 +1,17 @@ #![deny(unsafe_code)] +#![warn(missing_docs)] +//! Shared NIP-42 WebSocket client used by `buzz-cli` and other tools that need +//! to connect to a Buzz relay, perform the AUTH handshake, and publish events. +//! +//! This crate wraps the low-level WebSocket transport with the relay-specific +//! protocol: NIP-42 challenge/response authentication, event submission with +//! OK confirmation, and relay message parsing. +/// WebSocket connection management — connect, authenticate (NIP-42), publish. pub mod connection; +/// Error types for WebSocket client operations. pub mod error; +/// Relay message types and event builders. pub mod message; pub use connection::{publish_event, NostrWsConnection};