#111 - Tracking: Forgejo Actions tooling — read-only runs/jobs/logs tools - david/pi-extensions-and-skills

david commented

2026-08-29 03:27:29 +00:00

Owner

Summary

Tracking issue for the Forgejo extension's Phases 7–8 work: five read-only Forgejo Actions tools (list/search runs and jobs; download job and run logs) with a deterministic on-disk cache, plus the final documentation pass. Every step-issue in milestones M6 and M7 belongs to this feature.

Background

The forgejo pi extension (extensions/forgejo/) already replaces the fj CLI's issue/PR functionality by calling the Forgejo REST API directly (Phases 0–6 complete: src/issues.ts, src/pulls.ts, src/milestones.ts, src/api.ts, src/git.ts, src/forgejo.ts; 31 tools registered in src/index.ts). This revision adds read-only Actions tooling to debug CI pipeline failures. API surface is verified against Forgejo v16 source (routers/api/v1/repo/action.go) and the v16 swagger.

Design references: extensions/forgejo/docs/DESIGN.md and extensions/forgejo/docs/IMPLEMENTATION_PLAN.md (Phases 7–8). All issues in this set are fully self-contained; this issue is the umbrella.

Scope (this feature)

5 new tools: forgejo_action_runs, forgejo_action_run_view, forgejo_action_jobs, forgejo_action_job_log, forgejo_action_run_logs.
New src/actionsCache.ts (deterministic cache paths + cache-first read/write) and src/actions.ts (API functions).
New zip-extraction dependency (adm-zip or yauzl) — Node has no built-in unzip.
Baseline: Forgejo v16 for the runs/jobs/logs endpoints. Token scope: read:repository only — nothing is written to Forgejo.
Job details + ?step= / ?q= / ?format=ndjson are v17+ future work — NOT in scope.
Docs (README.md, DESIGN.md) land last, then the PR.

Branch & commit conventions (AGENTS.md)

Branch: feature/issue-111/forgejo-actions-tools.
Commits: issue-111: <summary>.
PR (final step, in M7): title issue-111: add forgejo actions tools, body Closes #111; merge decision left to the repo owner.

Rollout order

M6 (8 issues): zip dependency → cache module → metadata queries → job-log download → run-logs ZIP → tool registration → tests.
M7 (4 issues): README, DESIGN, final review, PR.
Validation gates: npm run check + npm test green; manual validation on a Forgejo v16+ instance — the current git.excelera.net runs v10.0.3 / Gitea 1.22 and does not expose the actions runs/jobs/logs endpoints.

Acceptance Criteria

All 5 tools registered, discoverable, and callable end-to-end; cache behavior verified.
npm run check + npm test green with the new suite.
README.md and DESIGN.md updated to match shipped behavior.
PR opened with Closes #111; merge left to the repo owner.

Test Plan

Manual validation checklist (post-implementation, on a Forgejo v16+ instance):

forgejo_action_runs with status[]=failure → pick a failed run.
forgejo_action_run_view run_id=... → run details.
forgejo_action_jobs run_id=... → jobs of the run.
forgejo_action_job_log run_id=... job_id=... → verify returned path, sizeBytes, lineCount, cached: false.
Same call again → cached: true (no network).
forgejo_action_run_logs run_id=... → verify run.zip + per-job logs land in the cache dir.
After a workflow re-run, pass refresh: true → re-download confirmed.

### Summary Tracking issue for the Forgejo extension's Phases 7–8 work: five **read-only Forgejo Actions** tools (list/search runs and jobs; download job and run logs) with a deterministic on-disk cache, plus the final documentation pass. Every step-issue in milestones **M6** and **M7** belongs to this feature. ### Background The `forgejo` pi extension (`extensions/forgejo/`) already replaces the `fj` CLI's issue/PR functionality by calling the Forgejo REST API directly (Phases 0–6 complete: `src/issues.ts`, `src/pulls.ts`, `src/milestones.ts`, `src/api.ts`, `src/git.ts`, `src/forgejo.ts`; 31 tools registered in `src/index.ts`). This revision adds read-only Actions tooling to debug CI pipeline failures. API surface is verified against Forgejo v16 source (`routers/api/v1/repo/action.go`) and the v16 swagger. Design references: `extensions/forgejo/docs/DESIGN.md` and `extensions/forgejo/docs/IMPLEMENTATION_PLAN.md` (Phases 7–8). All issues in this set are fully self-contained; this issue is the umbrella. ### Scope (this feature) - 5 new tools: `forgejo_action_runs`, `forgejo_action_run_view`, `forgejo_action_jobs`, `forgejo_action_job_log`, `forgejo_action_run_logs`. - New `src/actionsCache.ts` (deterministic cache paths + cache-first read/write) and `src/actions.ts` (API functions). - New zip-extraction dependency (adm-zip or yauzl) — Node has no built-in unzip. - Baseline: **Forgejo v16** for the runs/jobs/logs endpoints. Token scope: `read:repository` only — nothing is written to Forgejo. - Job details + `?step=` / `?q=` / `?format=ndjson` are **v17+ future work** — NOT in scope. - Docs (README.md, DESIGN.md) land last, then the PR. ### Branch & commit conventions (AGENTS.md) - Branch: `feature/issue-111/forgejo-actions-tools`. - Commits: `issue-111: <summary>`. - PR (final step, in M7): title `issue-111: add forgejo actions tools`, body `Closes #111`; **merge decision left to the repo owner**. ### Rollout order 1. **M6** (8 issues): zip dependency → cache module → metadata queries → job-log download → run-logs ZIP → tool registration → tests. 2. **M7** (4 issues): README, DESIGN, final review, PR. 3. Validation gates: `npm run check` + `npm test` green; manual validation on a **Forgejo v16+** instance — the current `git.excelera.net` runs v10.0.3 / Gitea 1.22 and does **not** expose the actions runs/jobs/logs endpoints. ### Acceptance Criteria - [ ] All 5 tools registered, discoverable, and callable end-to-end; cache behavior verified. - [ ] `npm run check` + `npm test` green with the new suite. - [ ] README.md and DESIGN.md updated to match shipped behavior. - [ ] PR opened with `Closes #111`; merge left to the repo owner. ### Test Plan Manual validation checklist (post-implementation, on a Forgejo v16+ instance): 1. `forgejo_action_runs` with `status[]=failure` → pick a failed run. 2. `forgejo_action_run_view run_id=...` → run details. 3. `forgejo_action_jobs run_id=...` → jobs of the run. 4. `forgejo_action_job_log run_id=... job_id=...` → verify returned `path`, `sizeBytes`, `lineCount`, `cached: false`. 5. Same call again → `cached: true` (no network). 6. `forgejo_action_run_logs run_id=...` → verify `run.zip` + per-job logs land in the cache dir. 7. After a workflow re-run, pass `refresh: true` → re-download confirmed.

david added this to the M6 - Actions tooling (runs/jobs/logs + cache) milestone

2026-08-29 03:27:29 +00:00

david added the

feature

label

2026-08-29 03:27:29 +00:00

david referenced this issue

2026-08-29 03:27:51 +00:00

Add zip-extraction dependency (adm-zip vs yauzl) #112

david referenced this issue

2026-08-29 03:28:03 +00:00

src/actionsCache.ts — cache paths + cache-first read/write #113