@bytesbrains/pi-ci-gate 1.1.1

package/AGENTS.md

@@ -0,0 +1,123 @@
+# CI Gate — Agent Usage Guide
+
+> You are an AI agent. Use ci-gate tools to observe CI workflows, diagnose failures, and re-trigger runs.
+
+## Golden Rules
+
+> **⚠️ Always check CI after submitting a PR.** Use `ci_list_runs()` to find the run for your branch before asking for reviews.
+
+> **⚠️ Read logs before re-running.** Blindly re-running a failing workflow wastes compute. Use `ci_get_logs()` to diagnose first.
+
+> **⚠️ Never skip confirm=true.** The `ci_rerun` and `ci_cancel` tools require explicit confirmation — this is intentional.
+
+## Workflow
+
+```
+ci_list_runs(status="failure", branch="feat/my-branch")
+  │
+  ▼
+ci_get_run(run_index="42")           ← see all jobs, find the failing one
+  │
+  ▼
+ci_get_logs(run_index="42")          ← read failure logs for all jobs
+  │   (or: run_index="42", job_index="512" for one job)
+  ▼
+[understand the error, fix the code]
+  │
+  ▼
+contrib_propose(message="fix: resolve CI failure in build step")
+  │
+  ▼
+contrib_submit(...)                  ← push the fix (triggers new CI run)
+  │
+  ▼
+ci_list_runs(status="failure", branch="feat/my-branch")
+                                       ← verify the fix passes
+```
+
+## Common Patterns
+
+### Find a failing CI run for your PR
+
+```
+ci_list_runs(status="failure", branch="feat/my-feature", limit=5)
+```
+
+### Inspect a specific run
+
+```
+ci_get_run(run_index="42")
+```
+
+### See which job failed
+
+```
+ci_list_jobs(run_index="42")
+```
+
+### Read the failure logs (specific job)
+
+```
+ci_get_logs(run_index="42", job_index="512")
+```
+> 💡 Job IDs are numeric and come from `ci_list_jobs` or `ci_get_run` output — not an arbitrary index.
+
+### Read all logs for a run (all jobs)
+
+```
+ci_get_logs(run_index="42")
+```
+
+### Re-run after fixing
+
+```
+ci_rerun(run_index="42", confirm=true)
+```
+
+### Cancel a stuck run
+
+```
+ci_cancel(run_index="42", confirm=true)
+```
+
+### List available workflows
+
+```
+ci_list_workflows()
+```
+
+### Filter runs by workflow and event
+
+```
+ci_list_runs(workflow="ci.yml", event="push", branch="main", limit=10)
+```
+> 💡 The `workflow` filter matches against the workflow file path (e.g., `.gitea/workflows/ci.yml`). A substring like `ci.yml` is enough.
+
+## Log Truncation
+
+Logs are truncated to `maxLogLines` (default: 200) per job. You'll see the first ~40% (setup) and last ~60% (failures/results). A marker shows how many lines were omitted. This keeps context manageable while surfacing the key information.
+
+## Status Icons
+
+| Icon | Meaning |
+|---|---|
+| 🔄 | Running |
+| ⏳ | Waiting / Blocked |
+| ✅ | Success |
+| ❌ | Failure |
+| 🚫 | Cancelled |
+| ⏭️ | Skipped |
+| ⚪ | Unknown / Other |
+
+## When Things Go Wrong
+
+| Problem | Solution |
+|---|---|
+| `ci_rerun` blocked without confirm | Pass `confirm=true` — this is a safety gate |
+| `ci_rerun` blocked by feature flag | `.circ.yml` has `allowRerun: false` — ask a human |
+| Logs are truncated | Increase `maxLogLines` in `.circ.yml`, or fetch a specific job with `job_index` |
+| No workflows found | The repo may not have Gitea Actions configured |
+| 404 on run ID | The run may have been deleted or the ID is wrong — use `ci_list_runs()` to find it |
+| Rate limited | Wait for the cooldown (60s) before retrying a destructive action |
+| `ci_get_logs` returns "no logs available" for a job | The job may not have produced logs (e.g., skipped or still queued). Check its status first with `ci_list_jobs` |
+| Need to rerun only failed jobs | Use `ci_rerun(run_index="42", confirm=true, failed_only=true)` |

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nandal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,103 @@
+# CI Gate for Pi
+
+[![npm version](https://img.shields.io/npm/v/pi-ci-gate)](https://www.npmjs.com/package/pi-ci-gate)
+[![license](https://img.shields.io/npm/l/pi-ci-gate)](./LICENSE)
+
+> CI observability gate for AI agents — view workflow runs, job statuses, and logs from Gitea Actions with safety controls. **Agents self-diagnose CI failures instead of asking humans.**
+
+## Philosophy
+
+`pi-contrib-gate` handles the *contribution* side (branch → commit → PR).  
+`pi-review-gate` handles the *review* side (check → approve → merge).  
+`pi-project-gate` handles the *project* side (issue → plan → release).  
+`pi-ci-gate` handles the *CI* side (observe → diagnose → re-trigger).
+
+## Install
+
+```bash
+pi install npm:pi-ci-gate
+```
+
+## Tools
+
+| Tool | Safety | What it does |
+|---|---|---|
+| `ci_list_workflows()` | ✅ Read-only | List registered workflows in the repo |
+| `ci_list_runs(workflow?, status?, branch?, limit?)` | ✅ Read-only | List workflow runs with filters |
+| `ci_get_run(run_index)` | ✅ Read-only | Get full run details (status, timing, trigger) |
+| `ci_list_jobs(run_index)` | ✅ Read-only | List jobs for a run with statuses |
+| `ci_get_logs(run_index, job_index?)` | ✅ Read-only | Get job logs (truncated to safe limits) |
+| `ci_rerun(run_index, confirm)` | ⚠️ Destructive | Re-run a failed/cancelled workflow |
+| `ci_cancel(run_index, confirm)` | ⚠️ Destructive | Cancel a running workflow |
+
+## Safety Harness
+
+The destructive tools (`ci_rerun`, `ci_cancel`) have a triple safety gate:
+
+```
+🛡️ Gate 1: Feature flag
+   └─ .circ.yml: allowRerun: false / allowCancel: false → tool blocked entirely
+
+🛡️ Gate 2: Explicit confirmation
+   └─ Must pass confirm=true — prevents accidental triggers
+
+🛡️ Gate 3: Rate limiting
+   └─ 60s cooldown between destructive actions on the same run
+```
+
+Log output is also truncated: shows the head (setup) and tail (failures), keeping agents from drowning in logs while still surfacing what matters.
+
+## Configuration
+
+Create `.circ.yml`:
+
+```yaml
+# Max log lines returned per job (head + tail split)
+maxLogLines: 200
+
+# Enable/disable destructive tools
+allowRerun: true
+allowCancel: true
+
+# Default limit for listing runs
+defaultLimit: 20
+```
+
+## Workflow
+
+```
+ci_list_runs(status="failure")   ← find failed runs
+  │
+  ▼
+ci_get_run(42)                  ← inspect a specific run
+  │
+  ▼
+ci_list_jobs(42)               ← see which jobs failed
+  │
+  ▼
+ci_get_logs(42, job_index=1)   ← read the failure logs
+  │
+  ▼
+[fix the code]
+  │
+  ▼
+ci_rerun(42, confirm=true)     ← re-trigger the workflow
+  │
+  ▼
+ci_get_run(42)                 ← verify it passed ✅
+```
+
+## Integration
+
+Install all four gates for full agent governance:
+
+```bash
+pi install npm:pi-contrib-gate
+pi install npm:pi-review-gate
+pi install npm:pi-project-gate
+pi install npm:pi-ci-gate
+```
+
+## License
+
+MIT © [nandal](https://github.com/nandal)

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@bytesbrains/pi-ci-gate",
+  "version": "1.1.1",
+  "description": "CI observability gate for AI agents — view workflow runs, job statuses, and logs from Gitea Actions with safety controls.",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "ci",
+    "workflow",
+    "gitea-actions",
+    "observability"
+  ],
+  "author": "nandal <nandal@users.noreply.github.com>",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nandal/pi-ext",
+    "directory": "ci-gate"
+  },
+  "homepage": "https://github.com/nandal/pi-ext/tree/main/ci-gate",
+  "bugs": {
+    "url": "https://github.com/nandal/pi-ext/issues"
+  },
+  "license": "MIT",
+  "main": "./src/index.ts",
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "src/",
+    "README.md",
+    "AGENTS.md",
+    "LICENSE"
+  ],
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "devDependencies": {
+    "vitest": "^2.1.9"
+  }
+}

package/src/__tests__/ci-gate.test.ts

@@ -0,0 +1,210 @@
+import { describe, it, expect } from "vitest";
+import { loadConfig, DEFAULT_CONFIG } from "../config";
+import { truncateLogs, checkRateLimit } from "../helpers";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+
+// ═══════════════════════════════════════
+// Config
+// ═══════════════════════════════════════
+describe("CiConfig", () => {
+  it("returns defaults when no config file", () => {
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "ci-test-"));
+    const config = loadConfig(tmp);
+    expect(config.maxLogLines).toBe(200);
+    expect(config.allowRerun).toBe(true);
+    expect(config.allowCancel).toBe(true);
+    expect(config.defaultLimit).toBe(20);
+    fs.rmSync(tmp, { recursive: true, force: true });
+  });
+
+  it("parses .circ.yml", () => {
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "ci-test-"));
+    fs.writeFileSync(
+      path.join(tmp, ".circ.yml"),
+      ["maxLogLines: 100", "allowRerun: false", "allowCancel: false", "defaultLimit: 10"].join("\n"),
+    );
+    const config = loadConfig(tmp);
+    expect(config.maxLogLines).toBe(100);
+    expect(config.allowRerun).toBe(false);
+    expect(config.allowCancel).toBe(false);
+    expect(config.defaultLimit).toBe(10);
+    fs.rmSync(tmp, { recursive: true, force: true });
+  });
+
+  it("parses quoted string values", () => {
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "ci-test-"));
+    fs.writeFileSync(path.join(tmp, ".circ.yml"), 'maxLogLines: "256"');
+    const config = loadConfig(tmp);
+    expect(config.maxLogLines).toBe(256);
+    fs.rmSync(tmp, { recursive: true, force: true });
+  });
+
+  it("handles partial config with defaults for missing keys", () => {
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "ci-test-"));
+    fs.writeFileSync(path.join(tmp, ".circ.yml"), "maxLogLines: 50");
+    const config = loadConfig(tmp);
+    expect(config.maxLogLines).toBe(50);
+    expect(config.allowRerun).toBe(DEFAULT_CONFIG.allowRerun);
+    expect(config.allowCancel).toBe(DEFAULT_CONFIG.allowCancel);
+    expect(config.defaultLimit).toBe(DEFAULT_CONFIG.defaultLimit);
+    fs.rmSync(tmp, { recursive: true, force: true });
+  });
+
+  it("handles invalid YAML gracefully", () => {
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "ci-test-"));
+    fs.writeFileSync(path.join(tmp, ".circ.yml"), "::: invalid :::");
+    const config = loadConfig(tmp);
+    expect(config).toEqual(DEFAULT_CONFIG);
+    fs.rmSync(tmp, { recursive: true, force: true });
+  });
+});
+
+// ═══════════════════════════════════════
+// Log Truncation
+// ═══════════════════════════════════════
+describe("truncateLogs", () => {
+  it("returns full text when under limit", () => {
+    const text = "line 1\nline 2\nline 3";
+    const result = truncateLogs(text, 10);
+    expect(result.truncated).toBe(false);
+    expect(result.text).toBe(text);
+    expect(result.totalLines).toBe(3);
+  });
+
+  it("returns full text when exactly at limit", () => {
+    const text = "a\nb\nc\nd\ne";
+    const result = truncateLogs(text, 5);
+    expect(result.truncated).toBe(false);
+    expect(result.totalLines).toBe(5);
+  });
+
+  it("truncates when over limit, keeping head and tail", () => {
+    const lines = Array.from({ length: 100 }, (_, i) => `line ${i + 1}`);
+    const text = lines.join("\n");
+    const result = truncateLogs(text, 20);
+    expect(result.truncated).toBe(true);
+    expect(result.totalLines).toBe(100);
+    // Should contain a truncation marker
+    expect(result.text).toContain("lines truncated");
+    // Head portion should have first lines
+    expect(result.text).toContain("line 1");
+    // Tail portion should have last lines
+    expect(result.text).toContain("line 100");
+    // Should not exceed the limit significantly
+    const outputLines = result.text.split("\n");
+    expect(outputLines.length).toBeLessThanOrEqual(24); // 20 + marker lines
+  });
+
+  it("handles empty string", () => {
+    const result = truncateLogs("", 100);
+    expect(result.truncated).toBe(false);
+    expect(result.totalLines).toBe(1); // empty string split gives [""]
+    expect(result.text).toBe("");
+  });
+});
+
+// ═══════════════════════════════════════
+// Rate Limiter
+// ═══════════════════════════════════════
+describe("checkRateLimit", () => {
+  it("allows first call", () => {
+    const result = checkRateLimit("test-key-1", 10);
+    expect(result.allowed).toBe(true);
+    expect(result.retryAfter).toBe(0);
+  });
+
+  it("blocks second call within cooldown", () => {
+    const key = "test-key-2";
+    checkRateLimit(key, 10); // first call
+    const result = checkRateLimit(key, 10); // second call immediately
+    expect(result.allowed).toBe(false);
+    expect(result.retryAfter).toBeGreaterThan(0);
+  });
+
+  it("different keys don't interfere", () => {
+    checkRateLimit("key-a", 10);
+    const result = checkRateLimit("key-b", 10);
+    expect(result.allowed).toBe(true);
+  });
+
+  it("retryAfter is a positive integer", () => {
+    const key = "test-key-3";
+    checkRateLimit(key, 60);
+    const result = checkRateLimit(key, 60);
+    expect(result.allowed).toBe(false);
+    expect(Number.isInteger(result.retryAfter)).toBe(true);
+    expect(result.retryAfter).toBeGreaterThan(0);
+  });
+});
+
+// ═══════════════════════════════════════
+// Tool definitions
+// ═══════════════════════════════════════
+import {
+  listWorkflowsTool,
+  listRunsTool,
+  getRunTool,
+  listJobsTool,
+  getLogsTool,
+  rerunTool,
+  cancelTool,
+} from "../tools/ci";
+
+describe("ci tool definitions", () => {
+  it("listWorkflowsTool has proper metadata", () => {
+    expect(listWorkflowsTool.name).toBe("ci_list_workflows");
+    expect(listWorkflowsTool.label).toBe("List Workflows");
+    expect(listWorkflowsTool.description).toContain("registered CI workflows");
+  });
+
+  it("listRunsTool has filter parameters", () => {
+    expect(listRunsTool.name).toBe("ci_list_runs");
+    const props = (listRunsTool.parameters as any)?.properties;
+    expect(props["workflow"]).toBeDefined();
+    expect(props["status"]).toBeDefined();
+    expect(props["branch"]).toBeDefined();
+    expect(props["event"]).toBeDefined();
+    expect(props["limit"]).toBeDefined();
+  });
+
+  it("getRunTool requires run_index", () => {
+    expect(getRunTool.name).toBe("ci_get_run");
+    const props = (getRunTool.parameters as any)?.properties;
+    expect(props["run_index"]).toBeDefined();
+  });
+
+  it("listJobsTool requires run_index", () => {
+    expect(listJobsTool.name).toBe("ci_list_jobs");
+    const props = (listJobsTool.parameters as any)?.properties;
+    expect(props["run_index"]).toBeDefined();
+  });
+
+  it("getLogsTool has run_index and optional job_index", () => {
+    expect(getLogsTool.name).toBe("ci_get_logs");
+    const props = (getLogsTool.parameters as any)?.properties;
+    expect(props["run_index"]).toBeDefined();
+    expect(props["job_index"]).toBeDefined();
+  });
+
+  it("rerunTool requires confirm=true and accepts optional failed_only", () => {
+    expect(rerunTool.name).toBe("ci_rerun");
+    const props = (rerunTool.parameters as any)?.properties;
+    expect(props["run_index"]).toBeDefined();
+    expect(props["confirm"]).toBeDefined();
+    expect(props["failed_only"]).toBeDefined();
+    // confirm is required (not optional)
+    const required = (rerunTool.parameters as any)?.required || [];
+    expect(required).toContain("confirm");
+  });
+
+  it("cancelTool requires confirm=true", () => {
+    expect(cancelTool.name).toBe("ci_cancel");
+    const props = (cancelTool.parameters as any)?.properties;
+    expect(props["run_index"]).toBeDefined();
+    expect(props["confirm"]).toBeDefined();
+    const required = (cancelTool.parameters as any)?.required || [];
+    expect(required).toContain("confirm");
+  });
+});

package/src/config.ts

@@ -0,0 +1,56 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+export interface CiConfig {
+  /** Max log lines returned per job (prevents context overflow) */
+  maxLogLines: number;
+  /** Enable/disable the rerun tool */
+  allowRerun: boolean;
+  /** Enable/disable the cancel tool */
+  allowCancel: boolean;
+  /** Default limit for listing runs */
+  defaultLimit: number;
+}
+
+export const DEFAULT_CONFIG: CiConfig = {
+  maxLogLines: 200,
+  allowRerun: true,
+  allowCancel: true,
+  defaultLimit: 20,
+};
+
+export function loadConfig(cwd: string): CiConfig {
+  const configPath = path.join(cwd, ".circ.yml");
+  if (!fs.existsSync(configPath)) return { ...DEFAULT_CONFIG };
+  try {
+    const content = fs.readFileSync(configPath, "utf-8");
+    const result: Record<string, unknown> = {};
+    for (const line of content.split("\n")) {
+      const m = line.match(/^\s*([\w][\w.]*):\s*(.+)$/);
+      if (m) {
+        let val = m[2].trim();
+        if (
+          (val.startsWith('"') && val.endsWith('"')) ||
+          (val.startsWith("'") && val.endsWith("'"))
+        )
+          val = val.slice(1, -1);
+        result[m[1]] = val;
+      }
+    }
+    return {
+      maxLogLines: parseInt(result["maxLogLines"] as string) || DEFAULT_CONFIG.maxLogLines,
+      allowRerun:
+        result["allowRerun"] !== undefined
+          ? result["allowRerun"] === "true"
+          : DEFAULT_CONFIG.allowRerun,
+      allowCancel:
+        result["allowCancel"] !== undefined
+          ? result["allowCancel"] === "true"
+          : DEFAULT_CONFIG.allowCancel,
+      defaultLimit:
+        parseInt(result["defaultLimit"] as string) || DEFAULT_CONFIG.defaultLimit,
+    };
+  } catch {
+    return { ...DEFAULT_CONFIG };
+  }
+}

package/src/helpers.ts

@@ -0,0 +1,99 @@
+import * as cp from "node:child_process";
+
+export function exec(
+  cmd: string,
+  cwd?: string,
+): { ok: boolean; stdout: string; stderr: string } {
+  try {
+    const r = cp.execSync(cmd, { cwd, encoding: "utf-8", timeout: 30000 });
+    return { ok: true, stdout: r.trim(), stderr: "" };
+  } catch (e: any) {
+    return {
+      ok: false,
+      stdout: e.stdout?.trim() || "",
+      stderr: e.stderr?.trim() || e.message,
+    };
+  }
+}
+
+export function resolveGitea(cwd: string): { repo: string; token: string } {
+  const remote = exec(
+    "git remote get-url gitea 2>/dev/null || git remote get-url origin",
+    cwd,
+  );
+  const url = remote.stdout || "";
+  const match = url.match(/[/:]([^/]+)\/([^/]+?)(?:\.git)?$/);
+  const repo = match ? `${match[1]}/${match[2]}` : "factory/wrok.in";
+  const credMatch = url.match(/:\/\/([^:]+):([^@]+)@/);
+  return { repo, token: credMatch ? credMatch[2] : (process.env.GITEA_TOKEN || "") };
+}
+
+export async function giteaApi(
+  path: string,
+  method: string,
+  body: Record<string, unknown> | null,
+  opts: { repo: string; token?: string },
+  _cwd: string,
+): Promise<{ ok: boolean; data: unknown; error?: string; statusCode?: number }> {
+  const base = `http://127.0.0.1:3001/api/v1/repos/${opts.repo}`;
+  const url = `${base}${path}`;
+  const headers: Record<string, string> = { "Content-Type": "application/json" };
+  if (opts.token) headers["Authorization"] = `token ${opts.token}`;
+
+  try {
+    const res = await fetch(url, {
+      method,
+      headers,
+      body: body ? JSON.stringify(body) : undefined,
+    });
+    const text = await res.text();
+    const statusCode = res.status;
+    if (!res.ok) {
+      return { ok: false, data: null, statusCode, error: text || `HTTP ${statusCode}` };
+    }
+    try {
+      return { ok: true, data: JSON.parse(text), statusCode };
+    } catch {
+      return { ok: true, data: text, statusCode };
+    }
+  } catch (e: any) {
+    return { ok: false, data: null, error: e.message || "Network error" };
+  }
+}
+
+/** Truncate logs to maxLines, keeping head + tail so agents see setup and failures. */
+export function truncateLogs(
+  raw: string,
+  maxLines: number,
+): { text: string; truncated: boolean; totalLines: number } {
+  const allLines = raw.split("\n");
+  const totalLines = allLines.length;
+  if (totalLines <= maxLines) {
+    return { text: raw, truncated: false, totalLines };
+  }
+  const head = Math.floor(maxLines * 0.4);
+  const tail = maxLines - head;
+  const headText = allLines.slice(0, head).join("\n");
+  const tailText = allLines.slice(-tail).join("\n");
+  return {
+    text: `${headText}\n\n... [${totalLines - maxLines} lines truncated] ...\n\n${tailText}`,
+    truncated: true,
+    totalLines,
+  };
+}
+
+/** In-memory rate limiter for destructive actions. */
+const rateLimitMap = new Map<string, number>();
+export function checkRateLimit(
+  key: string,
+  cooldownSeconds: number,
+): { allowed: boolean; retryAfter: number } {
+  const last = rateLimitMap.get(key) || 0;
+  const now = Date.now();
+  const elapsed = (now - last) / 1000;
+  if (elapsed < cooldownSeconds) {
+    return { allowed: false, retryAfter: Math.ceil(cooldownSeconds - elapsed) };
+  }
+  rateLimitMap.set(key, now);
+  return { allowed: true, retryAfter: 0 };
+}

package/src/index.ts

@@ -0,0 +1,27 @@
+/**
+ * pi-ci-gate — CI Observability Gate
+ *
+ * Tools: ci_list_workflows, ci_list_runs, ci_get_run, ci_list_jobs,
+ *        ci_get_logs, ci_rerun, ci_cancel
+ * Config: .circ.yml
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import {
+  listWorkflowsTool,
+  listRunsTool,
+  getRunTool,
+  listJobsTool,
+  getLogsTool,
+  rerunTool,
+  cancelTool,
+} from "./tools/ci";
+
+export default function (pi: ExtensionAPI) {
+  pi.registerTool(listWorkflowsTool);
+  pi.registerTool(listRunsTool);
+  pi.registerTool(getRunTool);
+  pi.registerTool(listJobsTool);
+  pi.registerTool(getLogsTool);
+  pi.registerTool(rerunTool);
+  pi.registerTool(cancelTool);
+}

package/src/tools/ci.ts

@@ -0,0 +1,515 @@
+import { Type } from "typebox";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { loadConfig } from "../config";
+import { resolveGitea, giteaApi, truncateLogs, checkRateLimit } from "../helpers";
+
+// ─── Types ──────────────────────────────────────────────────────────────────────
+
+interface GiteaRun {
+  id: number;
+  run_number: number;
+  display_title: string;
+  path: string; // workflow file path, e.g. ".gitea/workflows/ci.yml"
+  event: string;
+  head_branch: string;
+  head_sha: string;
+  status: string; // pending, queued, in_progress
+  conclusion: string | null; // failure, success, skipped, cancelled
+  started_at: string;
+  completed_at: string | null;
+  html_url: string;
+  url: string;
+  run_attempt: number;
+}
+
+interface GiteaJob {
+  id: number;
+  run_id: number;
+  name: string;
+  status: string;
+  conclusion: string | null;
+  started_at: string;
+  completed_at: string | null;
+  head_branch: string;
+  head_sha: string;
+}
+
+// ─── Helpers ────────────────────────────────────────────────────────────────────
+
+function opts(ctx: ExtensionContext) {
+  return resolveGitea(ctx.cwd);
+}
+
+function guard(
+  enabled: boolean,
+  name: string,
+): null | { content: { type: "text"; text: string }[]; isError: true; details: {} } {
+  if (!enabled) {
+    return {
+      content: [{ type: "text", text: `⛔ "${name}" is disabled via .circ.yml (allowRerun/allowCancel: false).` }],
+      isError: true,
+      details: {},
+    };
+  }
+  return null;
+}
+
+function confirm(
+  confirmed: boolean,
+  action: string,
+): null | { content: { type: "text"; text: string }[]; isError: true; details: {} } {
+  if (!confirmed) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: `⚠️ Destructive action: ${action}\nPass confirm=true to proceed.`,
+        },
+      ],
+      isError: true,
+      details: {},
+    };
+  }
+  return null;
+}
+
+function rateLimit(
+  key: string,
+  seconds: number,
+): null | { content: { type: "text"; text: string }[]; isError: true; details: {} } {
+  const rl = checkRateLimit(key, seconds);
+  if (!rl.allowed) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: `⏳ Rate limited. Try again in ${rl.retryAfter}s.`,
+        },
+      ],
+      isError: true,
+      details: { retryAfter: rl.retryAfter },
+    };
+  }
+  return null;
+}
+
+// ─── List Workflows ─────────────────────────────────────────────────────────────
+
+export const listWorkflowsTool = {
+  name: "ci_list_workflows" as const,
+  label: "List Workflows",
+  description:
+    "List registered CI workflows in the repository. Returns workflow ID, name, path, and state.",
+  parameters: Type.Object({}),
+  async execute(_id: string, _p: any, _s: any, _u: any, ctx: ExtensionContext) {
+    const r = await giteaApi("/actions/workflows", "GET", null, opts(ctx), ctx.cwd);
+    if (!r.ok || !r.data) {
+      return {
+        content: [{ type: "text", text: `❌ Failed to list workflows: ${r.error || "unknown"}` }],
+        isError: true,
+        details: {},
+      };
+    }
+    const workflows = (r.data as any)?.workflows ?? [];
+    if (workflows.length === 0) {
+      return { content: [{ type: "text", text: "No workflows registered." }], details: { count: 0 } };
+    }
+    const lines = [`🔧 Workflows (${workflows.length})`, ""];
+    for (const w of workflows) {
+      const badge = w.state === "active" ? "🟢" : w.state === "disabled" ? "🔴" : "⚪";
+      lines.push(`   ${badge} #${w.id} ${w.name}`);
+      lines.push(`        path: ${w.path}`);
+    }
+    return { content: [{ type: "text", text: lines.join("\n") }], details: { count: workflows.length } };
+  },
+};
+
+// ─── List Runs ──────────────────────────────────────────────────────────────────
+
+export const listRunsTool = {
+  name: "ci_list_runs" as const,
+  label: "List Workflow Runs",
+  description:
+    "List workflow runs with optional filters: workflow path, status, branch, event. Returns run ID, status, and timing.",
+  parameters: Type.Object({
+    workflow: Type.Optional(Type.String({ description: "Workflow path or ID to filter by (e.g., '.gitea/workflows/ci.yml' or 'ci.yml')" })),
+    status: Type.Optional(
+      Type.String({ description: "Filter by status: pending, queued, in_progress, failure, success, skipped" }),
+    ),
+    branch: Type.Optional(Type.String({ description: "Filter by branch name" })),
+    event: Type.Optional(Type.String({ description: "Filter by trigger event: push, pull_request, schedule" })),
+    limit: Type.Optional(Type.Number({ description: "Max runs to return (default: 20, max: 50)" })),
+  }),
+  async execute(_id: string, params: any, _s: any, _u: any, ctx: ExtensionContext) {
+    const config = loadConfig(ctx.cwd);
+    const limit = Math.min(params.limit || config.defaultLimit, 50);
+
+    // Build query string with server-side filters (Gitea supports: event, branch, status)
+    const qs = [`limit=${limit}`, "page=1"];
+    if (params.event) qs.push(`event=${encodeURIComponent(params.event)}`);
+    if (params.branch) qs.push(`branch=${encodeURIComponent(params.branch)}`);
+    if (params.status) qs.push(`status=${encodeURIComponent(params.status)}`);
+
+    const r = await giteaApi(`/actions/runs?${qs.join("&")}`, "GET", null, opts(ctx), ctx.cwd);
+    if (!r.ok) {
+      return {
+        content: [{ type: "text", text: `❌ Failed to list runs: ${r.error || "unknown"}` }],
+        isError: true,
+        details: {},
+      };
+    }
+    let runs: GiteaRun[] = (r.data as any)?.workflow_runs ?? [];
+
+    // Client-side workflow filter (Gitea doesn't support server-side workflow filter on /runs)
+    if (params.workflow) {
+      const wf = params.workflow.toLowerCase();
+      runs = runs.filter((run: GiteaRun) => {
+        const path = (run.path || "").toLowerCase();
+        return path.includes(wf) || String(run.id) === wf;
+      });
+    }
+
+    if (runs.length === 0) {
+      return { content: [{ type: "text", text: "No workflow runs found." }], details: { count: 0 } };
+    }
+
+    const lines = [`🏃 Workflow Runs (${runs.length})`, ""];
+    for (const run of runs) {
+      const icon = statusIcon(run.status, run.conclusion);
+      const duration = run.started_at && run.completed_at
+        ? formatDuration(run.started_at, run.completed_at)
+        : run.started_at
+          ? "running..."
+          : "";
+      lines.push(`   ${icon} id=${run.id}  run#${run.run_number}  ${run.display_title || "(untitled)"}`);
+      lines.push(`        status: ${run.conclusion || run.status}  |  ${duration}`);
+      lines.push(`        branch: ${run.head_branch}  |  event: ${run.event}  |  workflow: ${run.path}`);
+      lines.push(`        commit: ${(run.head_sha || "?").slice(0, 8)}`);
+    }
+    return {
+      content: [{ type: "text", text: lines.join("\n") }],
+      details: { count: runs.length, totalCount: (r.data as any)?.total_count },
+    };
+  },
+};
+
+// ─── Get Run ────────────────────────────────────────────────────────────────────
+
+export const getRunTool = {
+  name: "ci_get_run" as const,
+  label: "Get Run Details",
+  description:
+    "Get a specific workflow run by ID. Also fetches its jobs so you can see all job statuses at a glance.",
+  parameters: Type.Object({
+    run_index: Type.String({ description: "Workflow run ID (numeric, e.g. '42'). Use ci_list_runs to find IDs." }),
+  }),
+  async execute(_id: string, params: any, _s: any, _u: any, ctx: ExtensionContext) {
+    const runId = parseInt(params.run_index, 10);
+    if (isNaN(runId)) {
+      return {
+        content: [{ type: "text", text: `❌ Invalid run_index: "${params.run_index}" — must be a numeric run ID.` }],
+        isError: true,
+        details: {},
+      };
+    }
+
+    // Fetch the run directly
+    const runR = await giteaApi(`/actions/runs/${runId}`, "GET", null, opts(ctx), ctx.cwd);
+    if (!runR.ok) {
+      return {
+        content: [{ type: "text", text: `❌ Run #${runId} not found: ${runR.error || "unknown"}` }],
+        isError: true,
+        details: {},
+      };
+    }
+    const run: GiteaRun = (runR.data as any) || {};
+
+    // Also fetch jobs for this run
+    const jobs: GiteaJob[] = [];
+    const jobsR = await giteaApi(`/actions/runs/${runId}/jobs?limit=100&page=1`, "GET", null, opts(ctx), ctx.cwd);
+    if (jobsR.ok) {
+      jobs.push(...((jobsR.data as any)?.jobs ?? []));
+    }
+
+    const created = (run.started_at || "?").slice(0, 19).replace("T", " ");
+    const sha = (run.head_sha || "?").slice(0, 8);
+
+    const lines = [
+      `🏃 Run #${run.run_number} (id=${run.id})`,
+      `   Title:    ${run.display_title || "(untitled)"}`,
+      `   Branch:   ${run.head_branch}  |  Event: ${run.event}`,
+      `   Commit:   ${sha}  |  Workflow: ${run.path}`,
+      `   Started:  ${created}`,
+      `   URL:      ${run.html_url || "—"}`,
+      `   Status:   ${run.conclusion || run.status}  |  Attempt: ${run.run_attempt || 1}`,
+      "",
+    ];
+
+    if (jobs.length > 0) {
+      lines.push(`   Jobs (${jobs.length}):`);
+      for (const j of jobs) {
+        const icon = statusIcon(j.status, j.conclusion);
+        lines.push(`   ${icon} id=${j.id}  ${j.name}  →  ${j.conclusion || j.status}`);
+      }
+    } else {
+      lines.push(`   Jobs: (could not fetch — Gitea may not support /runs/{id}/jobs on this version)`);
+    }
+
+    return {
+      content: [{ type: "text", text: lines.join("\n") }],
+      details: { runId, runNumber: run.run_number, jobCount: jobs.length, workflow: run.path },
+    };
+  },
+};
+
+// ─── List Jobs ──────────────────────────────────────────────────────────────────
+
+export const listJobsTool = {
+  name: "ci_list_jobs" as const,
+  label: "List Run Jobs",
+  description:
+    "List jobs for a specific workflow run by run ID. Returns job ID, name, status, and duration.",
+  parameters: Type.Object({
+    run_index: Type.String({ description: "Workflow run ID (numeric, e.g. '42'). Use ci_list_runs to find IDs." }),
+  }),
+  async execute(_id: string, params: any, _s: any, _u: any, ctx: ExtensionContext) {
+    const runId = parseInt(params.run_index, 10);
+    if (isNaN(runId)) {
+      return {
+        content: [{ type: "text", text: `❌ Invalid run_index: "${params.run_index}" — must be a numeric run ID.` }],
+        isError: true,
+        details: {},
+      };
+    }
+
+    const r = await giteaApi(`/actions/runs/${runId}/jobs?limit=100&page=1`, "GET", null, opts(ctx), ctx.cwd);
+    if (!r.ok) {
+      return {
+        content: [{ type: "text", text: `❌ Failed to fetch jobs for run #${runId}: ${r.error || "unknown"}` }],
+        isError: true,
+        details: {},
+      };
+    }
+    const jobs: GiteaJob[] = (r.data as any)?.jobs ?? [];
+
+    if (jobs.length === 0) {
+      return { content: [{ type: "text", text: `No jobs found for run #${runId}.` }], details: { count: 0 } };
+    }
+
+    const lines = [`📋 Jobs for Run #${runId} (${jobs.length})`, ""];
+    for (const j of jobs) {
+      const icon = statusIcon(j.status, j.conclusion);
+      const duration = j.started_at && j.completed_at
+        ? formatDuration(j.started_at, j.completed_at)
+        : j.started_at
+          ? "running..."
+          : "";
+      lines.push(`   ${icon} id=${j.id}  ${j.name}`);
+      lines.push(`        status: ${j.conclusion || j.status}  |  ${duration}`);
+      if (j.head_branch) {
+        lines.push(`        branch: ${j.head_branch}  |  commit: ${(j.head_sha || "?").slice(0, 8)}`);
+      }
+    }
+    return {
+      content: [{ type: "text", text: lines.join("\n") }],
+      details: { runId, count: jobs.length },
+    };
+  },
+};
+
+// ─── Get Logs ───────────────────────────────────────────────────────────────────
+
+export const getLogsTool = {
+  name: "ci_get_logs" as const,
+  label: "Get Job Logs",
+  description:
+    "Get logs for a job by job ID, or all jobs in a run by run ID. Logs are truncated to the configured max lines, showing the head and tail.",
+  parameters: Type.Object({
+    run_index: Type.String({ description: "Workflow run ID (numeric). If job_index is omitted, fetches logs for all jobs in this run." }),
+    job_index: Type.Optional(Type.String({ description: "Job ID (numeric, e.g. '512'). If provided, fetches just that job's logs directly." })),
+  }),
+  async execute(_id: string, params: any, _s: any, _u: any, ctx: ExtensionContext) {
+    const config = loadConfig(ctx.cwd);
+
+    // Path A: direct job ID — fetch that specific job's logs
+    if (params.job_index) {
+      const jobId = params.job_index;
+      const r = await giteaApi(`/actions/jobs/${jobId}/logs`, "GET", null, opts(ctx), ctx.cwd);
+      if (!r.ok) {
+        return {
+          content: [{ type: "text", text: `❌ Failed to get logs for job #${jobId}: ${r.error || "no logs available"}` }],
+          isError: true,
+          details: {},
+        };
+      }
+      const raw = typeof r.data === "string" ? r.data : JSON.stringify(r.data);
+      const { text, truncated, totalLines } = truncateLogs(raw, config.maxLogLines);
+      const header = truncated
+        ? `📜 Job #${jobId} logs (${totalLines} lines, showing ${config.maxLogLines} — truncated)\n\n`
+        : `📜 Job #${jobId} logs (${totalLines} lines)\n\n`;
+      return {
+        content: [{ type: "text", text: header + text }],
+        details: { jobId, totalLines, truncated },
+      };
+    }
+
+    // Path B: run ID — discover jobs via /runs/{id}/jobs, then fetch each job's logs
+    const runId = parseInt(params.run_index, 10);
+    if (isNaN(runId)) {
+      return {
+        content: [{ type: "text", text: `❌ Invalid run_index: "${params.run_index}" — must be a numeric run ID.` }],
+        isError: true,
+        details: {},
+      };
+    }
+
+    const jobsR = await giteaApi(`/actions/runs/${runId}/jobs?limit=100&page=1`, "GET", null, opts(ctx), ctx.cwd);
+    if (!jobsR.ok) {
+      return {
+        content: [{ type: "text", text: `❌ Failed to fetch jobs for run #${runId}: ${jobsR.error || "unknown"}` }],
+        isError: true,
+        details: {},
+      };
+    }
+    const jobs: GiteaJob[] = (jobsR.data as any)?.jobs ?? [];
+    if (jobs.length === 0) {
+      return { content: [{ type: "text", text: `No jobs found for run #${runId}.` }], details: {} };
+    }
+
+    // Fetch logs for each job using its real job ID
+    const parts: string[] = [`📜 Logs for Run #${runId} (${jobs.length} jobs)`, ""];
+    for (const j of jobs) {
+      const logR = await giteaApi(`/actions/jobs/${j.id}/logs`, "GET", null, opts(ctx), ctx.cwd);
+      const icon = statusIcon(j.status, j.conclusion);
+      if (logR.ok && typeof logR.data === "string") {
+        const { text, truncated, totalLines } = truncateLogs(logR.data, config.maxLogLines);
+        parts.push(`─── ${icon} Job id=${j.id} (${j.name}) ───`);
+        if (truncated) parts.push(`   (${totalLines} lines total, showing ${config.maxLogLines} — head + tail)`);
+        parts.push(text, "");
+      } else {
+        parts.push(`─── ${icon} Job id=${j.id} (${j.name}) — no logs available`);
+        parts.push(`   (status: ${j.conclusion || j.status}, error: ${logR.error || "none"})`);
+        parts.push("");
+      }
+    }
+    return {
+      content: [{ type: "text", text: parts.join("\n") }],
+      details: { runId, jobCount: jobs.length },
+    };
+  },
+};
+
+// ─── Rerun ──────────────────────────────────────────────────────────────────────
+
+export const rerunTool = {
+  name: "ci_rerun" as const,
+  label: "Re-run Workflow",
+  description:
+    "Re-run a workflow run (all jobs or just failed jobs). Uses Gitea's native rerun endpoint.",
+  parameters: Type.Object({
+    run_index: Type.String({ description: "Workflow run ID (numeric). Use ci_list_runs to find IDs." }),
+    confirm: Type.Boolean({ description: "Must be true to confirm" }),
+    failed_only: Type.Optional(Type.Boolean({ description: "If true, rerun only failed jobs (default: false, reruns all jobs)" })),
+  }),
+  async execute(_id: string, params: any, _s: any, _u: any, ctx: ExtensionContext) {
+    const config = loadConfig(ctx.cwd);
+
+    // Safety gate 1: feature flag
+    const flag = guard(config.allowRerun, "ci_rerun");
+    if (flag) return flag;
+
+    // Safety gate 2: explicit confirmation
+    const action = params.failed_only ? "rerun failed jobs" : "rerun entire run";
+    const conf = confirm(params.confirm === true, `${action} (run #${params.run_index})`);
+    if (conf) return conf;
+
+    // Safety gate 3: rate limit
+    const rl = rateLimit(`rerun:${params.run_index}`, 60);
+    if (rl) return rl;
+
+    const runId = parseInt(params.run_index, 10);
+    if (isNaN(runId)) {
+      return {
+        content: [{ type: "text", text: `❌ Invalid run_index: "${params.run_index}" — must be a numeric run ID.` }],
+        isError: true,
+        details: {},
+      };
+    }
+
+    // Use Gitea's native rerun endpoint
+    const endpoint = params.failed_only
+      ? `/actions/runs/${runId}/rerun-failed-jobs`
+      : `/actions/runs/${runId}/rerun`;
+
+    const dispatchR = await giteaApi(endpoint, "POST", null, opts(ctx), ctx.cwd);
+    if (!dispatchR.ok) {
+      return {
+        content: [{ type: "text", text: `❌ Failed to rerun run #${runId}: ${dispatchR.error || "unknown"}` }],
+        isError: true,
+        details: {},
+      };
+    }
+    return {
+      content: [{ type: "text", text: `🔄 Re-running run #${runId}${params.failed_only ? " (failed jobs only)" : ""}. Check ci_list_runs for the new run.` }],
+      details: { runId, failedOnly: !!params.failed_only },
+    };
+  },
+};
+
+// ─── Cancel (NOT SUPPORTED by Gitea) ───────────────────────────────────────────
+
+export const cancelTool = {
+  name: "ci_cancel" as const,
+  label: "Cancel Workflow Run",
+  description:
+    "Cancel a running workflow run. ⚠️ Gitea does not expose a cancel endpoint; this will return an error.",
+  parameters: Type.Object({
+    run_index: Type.String({ description: "Workflow run ID to cancel" }),
+    confirm: Type.Boolean({ description: "Must be true to confirm cancellation" }),
+  }),
+  async execute(_id: string, params: any, _s: any, _u: any, ctx: ExtensionContext) {
+    const config = loadConfig(ctx.cwd);
+
+    const flag = guard(config.allowCancel, "ci_cancel");
+    if (flag) return flag;
+
+    const conf = confirm(params.confirm === true, `cancel workflow run #${params.run_index}`);
+    if (conf) return conf;
+
+    const rl = rateLimit(`cancel:${params.run_index}`, 60);
+    if (rl) return rl;
+
+    return {
+      content: [{
+        type: "text",
+        text: `❌ Cancel not available: Gitea's Actions API does not expose a cancel endpoint for workflow runs.`,
+      }],
+      isError: true,
+      details: {},
+    };
+  },
+};
+
+// ─── Formatting helpers ─────────────────────────────────────────────────────────
+
+function statusIcon(status: string, conclusion: string | null): string {
+  const s = conclusion || status;
+  if (s === "in_progress" || s === "running") return "🔄";
+  if (s === "pending" || s === "queued" || s === "waiting" || s === "blocked") return "⏳";
+  if (s === "cancelled") return "🚫";
+  if (s === "success") return "✅";
+  if (s === "failure") return "❌";
+  if (s === "skipped") return "⏭️";
+  return "⚪";
+}
+
+function formatDuration(start: string, end: string): string {
+  const ms = new Date(end).getTime() - new Date(start).getTime();
+  if (ms < 0) return "";
+  const s = Math.floor(ms / 1000);
+  if (s < 60) return `${s}s`;
+  const m = Math.floor(s / 60);
+  if (m < 60) return `${m}m ${s % 60}s`;
+  const h = Math.floor(m / 60);
+  return `${h}h ${m % 60}m`;
+}