58 lines
3 KiB
Markdown
58 lines
3 KiB
Markdown
# 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`.
|