hyperhive/hive-forge

hive-forge

Typed CLI wrapper around the in-cluster Forgejo's REST API. Replaces the prior bash script (hive-forge-tools.nix) so that agents and operators get the same error handling, exit codes, and JSON shapes regardless of how the bash mood was that day — this is the only supported path to the forge from inside an agent container; never curl it directly.

Single binary, one verb subcommand per forge operation (issues, PRs, comments, labels, reviews, CI status, attachments, triage). Reads credentials from the environment: HIVE_FORGE_URL (base URL), HIVE_FORGE_REPO (default repo), HYPERHIVE_STATE_DIR (state dir — forge-token lives here). The global -f/--forge <label> flag retargets a dashboard-provisioned external forge account instead, reading forge-<label>-token + forge-<label>.json from the state dir rather than the internal-forge pair.

When to use it

Reach for this crate when you're adding a new forge verb or changing how an existing one behaves — it's the single place issue/PR/comment/ CI logic lives for every agent and hivectl. If you're instead adding a tool an agent's claude session calls, that's hive-agent-mcp wrapping a shellout to this binary, not new logic here.

Shape

• verbs/ — one module per subcommand, each exposing a clap-derived Args struct and a run(&Client, Args) -> Result<()> fn. Splitting one verb per module keeps each handler small and avoids the bash script's monolithic case statement. Notable ones:
  • lint.rs — lint <subcommand> triage queries (unassigned, no-reviewer, stale-branches, assignments), always JSON-able via the global --json flag.
  • pr_status.rs — the merge-readiness verdict command (pr-status --pr <n> / --sha <commit>); its exit code IS the verdict, not just a report.
  • comment.rs / comments.rs — post (refuses on unread thread activity) / read (marks forge's own notification read as a side effect) — see notify.rs for why that's safe to rely on.
• client.rs — the app-level Forgejo client wrapper. Identity is the per-agent token under ${HYPERHIVE_STATE_DIR}/forge-token. REST calls go through the typed forgejo_api::sync::Forgejo client (Client::api); a minimal raw reqwest client remains for the few web-router routes Forgejo doesn't serve under /api/v1/ (attachment downloads, Actions artifact/log routes).
• notify.rs — the read-before-comment guard, backed by forge's own notification read-state rather than a local mirror (which would drift across container restarts). "Is there unread activity here?" is just "does forge still have an unread notification for this thread?" — forge is the single source of truth.
• body.rs — body-input resolution shared by every verb that posts a body: exactly one source between --body, --body-file, and piped stdin (matches the old bash resolve_body helper); passing both --body and --body-file is a clear error.

Full verb reference (with worked examples): docs/tools/forge.md.