From 6eb43ba2c51d691f7910eff8ce380e6659c2a303 Mon Sep 17 00:00:00 2001 From: iris Date: Sat, 15 Aug 2026 12:17:32 +0200 Subject: [PATCH] docs(forge): fix ci-log source ordering and binary path claim --- docs/tools/forge.md | 31 +++++++++++++++++-------------- 1 file changed, 17 insertions(+), 14 deletions(-) diff --git a/docs/tools/forge.md b/docs/tools/forge.md index ce3ef548..e9228a0a 100644 --- a/docs/tools/forge.md +++ b/docs/tools/forge.md @@ -1,8 +1,8 @@ # hive-forge CLI `hive-forge` is the Forgejo API wrapper available in every agent -container (installed via `nix/agent-modules/forge.nix`; lives in `/hive-forge` -as a proper Rust binary). Use it instead of ad-hoc curl pipelines. +container (installed via `nix/agent-modules/forge.nix`, on `PATH` as a +proper Rust binary). Use it instead of ad-hoc curl pipelines. ## Credentials and repo defaults @@ -253,18 +253,21 @@ to discover valid label names before triaging or to audit the label set. - `ci-log --run [--job i] [--step i] [--attempt n]` prints a CI run's job step logs. `` is the run number from the run-page URL (same value `artifact-get` takes; `pr-status` surfaces it as a CI - context's target_url). Two log sources are tried in order: first the - web run-view **streamer** the run page polls (rich per-step framing, - honors `--step`) — but that reads the live `act_runner` task record, - which Forgejo prunes once a run completes; then, when the streamer is - pruned (500 / no lines), the **durable persisted-log download** the - run page's "view raw logs" link uses - (`…/runs//jobs//attempt//logs`), a flat whole-job log that - survives the prune (`--step` is not honored on this path). So quick / - older runs that the streamer can no longer serve still print instead - of erroring. `--job` selects the job (0-based, default 0); `--attempt` - picks the run attempt for the durable path (default 1; re-runs - increment it). `--json` wraps the output. + context's target_url). Two log sources, tried in **completeness + order**: the **durable persisted-log download** the run page's "view + raw logs" link uses (`…/runs//jobs//attempt//logs`, a flat + whole-job log) is tried first — complete once it exists, which covers + any run that has already finished; it's only absent while the job is + still running, in which case the verb falls back to the web run-view + **streamer** the run page polls (rich per-step framing, but only a + snapshot of the live `act_runner` task record, so a still-buffering + multi-minute phase can come back thin). Passing `--step` reverses + that order — only the streamer honors per-step framing (the persisted + log is flat), so `--step` goes straight to the streamer and an + out-of-range index surfaces as a hard error instead of silently + falling back. `--job` selects the job (0-based, default 0); + `--attempt` picks the run attempt for the durable path (default 1; + re-runs increment it). `--json` wraps the output. - `ci-rerun` re-runs CI without pushing an empty commit (the old retrigger path, which littered PR history). Forgejo has no token-usable REST endpoint to re-run an _existing_ run (the run-page rerun buttons