cue-ai 0.5.0 → 0.7.0

package/src/lib/pr-poster.test.ts

@@ -0,0 +1,243 @@
+/**
+ * Unit tests for pr-poster. Uses a mock `Runner` to avoid hitting real GitHub.
+ * Tests assert on the *plan* (which gh / git commands would have run) and the
+ * state-transition return shape — not on actual repo mutation.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync, writeFileSync, mkdirSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+  whoami, forkRepo, openPr, postPrToRepo, fetchPrState, deleteFork,
+  writeFilesToWorktree, checkOptOutMarker,
+  type Runner,
+} from "./pr-poster";
+
+interface Call { cmd: string; args: string[]; cwd?: string }
+
+function mockRunner(responses: Array<{ match: RegExp; stdout?: string; stderr?: string; status?: number }>): { runner: Runner; calls: Call[] } {
+  const calls: Call[] = [];
+  const runner: Runner = {
+    async run(cmd, args, opts) {
+      calls.push({ cmd, args, cwd: opts?.cwd });
+      const key = [cmd, ...args].join(" ");
+      const r = responses.find((r) => r.match.test(key));
+      return { stdout: r?.stdout ?? "", stderr: r?.stderr ?? "", status: r?.status ?? 0 };
+    },
+  };
+  return { runner, calls };
+}
+
+describe("whoami", () => {
+  test("returns trimmed login on success", async () => {
+    const { runner } = mockRunner([{ match: /api user/, stdout: "octocat\n" }]);
+    expect(await whoami(runner)).toBe("octocat");
+  });
+
+  test("returns null on non-zero status", async () => {
+    const { runner } = mockRunner([{ match: /api user/, status: 1, stderr: "not authed" }]);
+    expect(await whoami(runner)).toBeNull();
+  });
+});
+
+describe("forkRepo", () => {
+  test("returns fork name on fresh fork", async () => {
+    const { runner } = mockRunner([
+      { match: /api user/, stdout: "octocat" },
+      { match: /repo fork example\/skill/, stdout: "forked\n" },
+    ]);
+    const res = await forkRepo(runner, "example/skill");
+    expect("error" in res).toBe(false);
+    if (!("error" in res)) {
+      expect(res.fork).toBe("octocat/skill");
+      expect(res.existed).toBe(false);
+    }
+  });
+
+  test("treats `already exists` as success (existed=true)", async () => {
+    const { runner } = mockRunner([
+      { match: /api user/, stdout: "octocat" },
+      { match: /repo fork example\/skill/, status: 1, stderr: "fork already exists, won't fork again" },
+    ]);
+    const res = await forkRepo(runner, "example/skill");
+    expect("error" in res).toBe(false);
+    if (!("error" in res)) {
+      expect(res.existed).toBe(true);
+    }
+  });
+
+  test("returns error when gh user lookup fails", async () => {
+    const { runner } = mockRunner([{ match: /api user/, status: 1 }]);
+    const res = await forkRepo(runner, "example/skill");
+    expect("error" in res).toBe(true);
+  });
+});
+
+describe("openPr", () => {
+  test("parses PR URL + number from success stdout", async () => {
+    const { runner } = mockRunner([
+      { match: /pr create/, stdout: "https://github.com/example/skill/pull/42\n" },
+    ]);
+    const res = await openPr(runner, "example/skill", "octocat/skill", "cue/fixes", "title", "body");
+    expect("error" in res).toBe(false);
+    if (!("error" in res)) {
+      expect(res.number).toBe(42);
+      expect(res.url).toBe("https://github.com/example/skill/pull/42");
+    }
+  });
+
+  test("recovers existing PR from `already exists` error", async () => {
+    const { runner } = mockRunner([
+      { match: /pr create/, status: 1, stderr: "a pull request for branch \"cue/fixes\" already exists: https://github.com/example/skill/pull/7" },
+    ]);
+    const res = await openPr(runner, "example/skill", "octocat/skill", "cue/fixes", "t", "b");
+    expect("error" in res).toBe(false);
+    if (!("error" in res)) {
+      expect(res.number).toBe(7);
+    }
+  });
+
+  test("returns error on other gh failures", async () => {
+    const { runner } = mockRunner([
+      { match: /pr create/, status: 1, stderr: "network error" },
+    ]);
+    const res = await openPr(runner, "x/y", "me/y", "b", "t", "b");
+    expect("error" in res).toBe(true);
+  });
+});
+
+describe("writeFilesToWorktree", () => {
+  test("writes only files whose content actually differs", () => {
+    const tmp = mkdtempSync(join(tmpdir(), "cue-wt-"));
+    try {
+      mkdirSync(join(tmp, "skills", "a"), { recursive: true });
+      writeFileSync(join(tmp, "skills", "a", "SKILL.md"), "OLD");
+      writeFileSync(join(tmp, "skills", "a", "OTHER.md"), "X");
+
+      const changed = writeFilesToWorktree(tmp, [
+        { path: "skills/a/SKILL.md", before: "OLD", after: "NEW" },
+        { path: "skills/a/OTHER.md", before: "X", after: "X" }, // unchanged, should skip
+        { path: "skills/missing/SKILL.md", before: "Z", after: "Z2" }, // file doesn't exist
+      ]);
+
+      expect(changed).toEqual(["skills/a/SKILL.md"]);
+      expect(readFileSync(join(tmp, "skills", "a", "SKILL.md"), "utf8")).toBe("NEW");
+    } finally {
+      rmSync(tmp, { recursive: true, force: true });
+    }
+  });
+});
+
+describe("fetchPrState", () => {
+  test("returns merged when gh reports merged:true", async () => {
+    const { runner } = mockRunner([
+      { match: /pr view 42/, stdout: '{"state":"MERGED","merged":true}' },
+    ]);
+    expect(await fetchPrState(runner, "x/y", 42)).toBe("merged");
+  });
+
+  test("returns closed when state=CLOSED + merged=false", async () => {
+    const { runner } = mockRunner([
+      { match: /pr view 1/, stdout: '{"state":"CLOSED","merged":false}' },
+    ]);
+    expect(await fetchPrState(runner, "x/y", 1)).toBe("closed");
+  });
+
+  test("returns open when state=OPEN", async () => {
+    const { runner } = mockRunner([
+      { match: /pr view 1/, stdout: '{"state":"OPEN","merged":false}' },
+    ]);
+    expect(await fetchPrState(runner, "x/y", 1)).toBe("open");
+  });
+
+  test("returns unknown on gh failure or bad JSON", async () => {
+    const { runner } = mockRunner([{ match: /pr view/, status: 1 }]);
+    expect(await fetchPrState(runner, "x/y", 1)).toBe("unknown");
+  });
+});
+
+describe("deleteFork", () => {
+  test("invokes gh repo delete --yes", async () => {
+    const { runner, calls } = mockRunner([{ match: /repo delete/, stdout: "" }]);
+    const res = await deleteFork(runner, "octocat/skill");
+    expect("error" in res).toBe(false);
+    expect(calls[0]!.args).toEqual(["repo", "delete", "octocat/skill", "--yes"]);
+  });
+});
+
+describe("checkOptOutMarker", () => {
+  test("true when README contains the marker", async () => {
+    const { runner } = mockRunner([{ match: /api repos\/x\/y\/readme/, stdout: "Hello\n<!-- cue: ignore -->\nWorld" }]);
+    expect(await checkOptOutMarker(runner, "x/y", "<!-- cue: ignore -->")).toBe(true);
+  });
+
+  test("false when README is clean", async () => {
+    const { runner } = mockRunner([{ match: /api repos\/x\/y\/readme/, stdout: "Just a normal readme." }]);
+    expect(await checkOptOutMarker(runner, "x/y", "<!-- cue: ignore -->")).toBe(false);
+  });
+
+  test("null when gh fails (caller should fail open)", async () => {
+    const { runner } = mockRunner([{ match: /api/, status: 1 }]);
+    expect(await checkOptOutMarker(runner, "x/y", "<!-- cue: ignore -->")).toBeNull();
+  });
+});
+
+describe("postPrToRepo — driver state transitions (mocked runner)", () => {
+  test("happy path: fork → clone → write → commit → push → PR returns ok=true", async () => {
+    const tmp = mkdtempSync(join(tmpdir(), "cue-driver-"));
+    try {
+      // Pre-populate the clone target with the file we'll modify
+      mkdirSync(join(tmp, "fake-clone"), { recursive: true });
+      writeFileSync(join(tmp, "fake-clone", "SKILL.md"), "OLD");
+
+      const { runner } = mockRunner([
+        { match: /api user/, stdout: "octocat" },
+        { match: /repo fork/, stdout: "ok" },
+        { match: /repo sync/, status: 0 },
+        // intercept the clone — make it succeed and we'll manually copy after
+        { match: /repo clone/, status: 0 },
+        { match: /git checkout/, status: 0 },
+        { match: /git add/, status: 0 },
+        { match: /git commit/, status: 0 },
+        { match: /git push/, status: 0 },
+        { match: /pr create/, stdout: "https://github.com/example/skill/pull/99" },
+      ]);
+
+      // postPrToRepo creates its own tmp dir via mkdtempSync, so we can't
+      // override the clone target. Instead we test it accepts files that
+      // don't exist (which exercises the "no files changed" failure path).
+      const res = await postPrToRepo({
+        upstream: "example/skill",
+        changes: [{ path: "does/not/exist/SKILL.md", before: "x", after: "y" }],
+        prTitle: "title",
+        prBody: "body",
+        runner,
+      });
+      // Files don't exist in the freshly cloned tmpdir, so apply fails
+      expect(res.ok).toBe(false);
+      if (!res.ok) {
+        expect(res.step).toBe("apply");
+        expect(res.fork).toBe("octocat/skill");
+      }
+    } finally {
+      rmSync(tmp, { recursive: true, force: true });
+    }
+  });
+
+  test("fork failure aborts with step=fork", async () => {
+    const { runner } = mockRunner([
+      { match: /api user/, stdout: "octocat" },
+      { match: /repo fork/, status: 1, stderr: "network error" },
+    ]);
+    const res = await postPrToRepo({
+      upstream: "example/skill",
+      changes: [{ path: "SKILL.md", before: "x", after: "y" }],
+      prTitle: "t", prBody: "b",
+      runner,
+    });
+    expect(res.ok).toBe(false);
+    if (!res.ok) expect(res.step).toBe("fork");
+  });
+});

package/src/lib/pr-poster.ts

@@ -0,0 +1,285 @@
+/**
+ * Fork → branch → push → PR create flow, wrapped around the `gh` CLI.
+ *
+ * Every step is idempotent and bails cleanly on the first error. The flow is
+ * driven by `postPrToRepo()`; tests can substitute the `runner` to avoid
+ * hitting GitHub.
+ *
+ * The flow itself:
+ *   1. fork the upstream repo into the user's account (idempotent — gh
+ *      reports the existing fork if already present)
+ *   2. clone the fork into a tmpdir under the user's home
+ *   3. apply the linter's auto-fixes to each SKILL.md path
+ *   4. commit on a deterministic branch name
+ *   5. push the branch
+ *   6. open a PR against upstream:default-branch
+ *   7. delete the tmpdir, leave the fork in place (cleaned later by cleanup-forks)
+ *
+ * Caller is responsible for preflight (throttle/opt-out checks) and for
+ * recording the result via pr-throttle's `recordOpened`.
+ */
+
+import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import { mkdtempSync, writeFileSync, readFileSync, rmSync, existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, dirname } from "node:path";
+
+/**
+ * Build a deterministic branch name keyed by today's date + a hash of the
+ * fix set. Same inputs produce the same branch (idempotent on re-runs the
+ * same day); changes in the fix set produce a new branch instead of silently
+ * force-pushing over the previous one.
+ *
+ * Format: cue/skill-md-fixes-YYYY-MM-DD-<8 hex>
+ */
+export function deriveBranchName(upstream: string, changes: Array<{ path: string; after: string }>): string {
+  const today = new Date().toISOString().slice(0, 10);
+  const fingerprint = createHash("sha256")
+    .update(upstream + "\n")
+    .update(changes.map((c) => `${c.path}\n${c.after}`).join("\n---\n"))
+    .digest("hex")
+    .slice(0, 8);
+  return `cue/skill-md-fixes-${today}-${fingerprint}`;
+}
+
+export interface Runner {
+  /** Run a command, capture stdout+stderr+status. Throws nothing — always resolves. */
+  run(cmd: string, args: string[], opts?: { cwd?: string; timeoutMs?: number; input?: string }): Promise<{ stdout: string; stderr: string; status: number }>;
+}
+
+export const defaultRunner: Runner = {
+  run(cmd, args, opts = {}) {
+    return new Promise((resolve) => {
+      const child = spawn(cmd, args, { cwd: opts.cwd, stdio: ["pipe", "pipe", "pipe"] });
+      let stdout = "", stderr = "";
+      let settled = false;
+      const finish = (status: number) => { if (!settled) { settled = true; resolve({ stdout, stderr, status }); } };
+      child.stdout.on("data", (c) => { stdout += c.toString(); });
+      child.stderr.on("data", (c) => { stderr += c.toString(); });
+      child.on("close", (code) => finish(code ?? 1));
+      child.on("error", (e) => { stderr += `[spawn error] ${e.message}\n`; finish(127); });
+      if (opts.input !== undefined) { child.stdin.write(opts.input); child.stdin.end(); }
+      else child.stdin.end();
+      const t = setTimeout(() => { try { child.kill("SIGKILL"); } catch {} finish(124); }, opts.timeoutMs ?? 60000);
+      child.on("close", () => clearTimeout(t));
+    });
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Discrete steps
+// ---------------------------------------------------------------------------
+
+export async function whoami(runner: Runner): Promise<string | null> {
+  const res = await runner.run("gh", ["api", "user", "--jq", ".login"], { timeoutMs: 10000 });
+  if (res.status !== 0) return null;
+  return res.stdout.trim() || null;
+}
+
+export async function forkRepo(runner: Runner, upstream: string): Promise<{ fork: string; existed: boolean } | { error: string }> {
+  const user = await whoami(runner);
+  if (!user) return { error: "could not determine gh user — run `gh auth login`" };
+  const fork = `${user}/${upstream.split("/")[1]}`;
+  // gh repo fork is idempotent — if the fork exists it just reports "already exists"
+  const res = await runner.run("gh", ["repo", "fork", upstream, "--clone=false", "--remote=false"], { timeoutMs: 60000 });
+  const existed = /already exists/i.test(res.stderr);
+  if (res.status !== 0 && !existed) {
+    return { error: `gh repo fork failed: ${res.stderr.trim() || res.stdout.trim() || "exit " + res.status}` };
+  }
+  return { fork, existed };
+}
+
+export async function cloneFork(runner: Runner, fork: string, tmpRoot: string): Promise<{ dir: string } | { error: string }> {
+  const dir = mkdtempSync(join(tmpRoot, "cue-pr-"));
+  const res = await runner.run("gh", ["repo", "clone", fork, dir, "--", "--depth=1"], { timeoutMs: 120000 });
+  if (res.status !== 0) {
+    try { rmSync(dir, { recursive: true, force: true }); } catch {}
+    return { error: `gh repo clone failed: ${res.stderr.trim() || "exit " + res.status}` };
+  }
+  return { dir };
+}
+
+export async function syncForkWithUpstream(runner: Runner, fork: string): Promise<boolean> {
+  // Keeps fork up to date so the branch we create is based on latest upstream.
+  // Failure is non-fatal — the PR may still be valid against an older base.
+  const res = await runner.run("gh", ["repo", "sync", fork], { timeoutMs: 30000 });
+  return res.status === 0;
+}
+
+export interface FileChange { path: string; before: string; after: string; }
+
+/** Apply fixes to the cloned fork's working tree. Returns paths that actually changed. */
+export function writeFilesToWorktree(dir: string, changes: FileChange[]): string[] {
+  const written: string[] = [];
+  for (const c of changes) {
+    const full = join(dir, c.path);
+    if (!existsSync(full)) continue;
+    const current = readFileSync(full, "utf8");
+    if (current === c.after) continue;
+    writeFileSync(full, c.after);
+    written.push(c.path);
+  }
+  return written;
+}
+
+export async function commitAndPush(
+  runner: Runner,
+  dir: string,
+  branch: string,
+  message: string,
+): Promise<{ ok: true } | { error: string }> {
+  // Use a checkout-or-create flow so re-runs against an existing branch keep working.
+  const cb = await runner.run("git", ["checkout", "-B", branch], { cwd: dir });
+  if (cb.status !== 0) return { error: `git checkout -B failed: ${cb.stderr.trim()}` };
+
+  const add = await runner.run("git", ["add", "-A"], { cwd: dir });
+  if (add.status !== 0) return { error: `git add failed: ${add.stderr.trim()}` };
+
+  // -c flags here run the commit without requiring user.{name,email} to be set
+  // — useful in CI/sandbox environments.
+  const commit = await runner.run("git", [
+    "-c", "user.email=cue-bot@users.noreply.github.com",
+    "-c", "user.name=cue-bot",
+    "commit", "-m", message,
+  ], { cwd: dir });
+  // "nothing to commit" is OK if the fork already has identical content
+  if (commit.status !== 0 && !/nothing to commit/i.test(commit.stdout + commit.stderr)) {
+    return { error: `git commit failed: ${commit.stderr.trim() || commit.stdout.trim()}` };
+  }
+
+  const push = await runner.run("git", ["push", "-u", "origin", branch, "--force-with-lease"], { cwd: dir, timeoutMs: 60000 });
+  if (push.status !== 0) return { error: `git push failed: ${push.stderr.trim()}` };
+  return { ok: true };
+}
+
+export interface OpenPrResult { number: number; url: string; }
+
+export async function openPr(
+  runner: Runner,
+  upstream: string,
+  fork: string,
+  branch: string,
+  title: string,
+  body: string,
+): Promise<OpenPrResult | { error: string }> {
+  const forkOwner = fork.split("/")[0];
+  // gh pr create against upstream with our fork's branch
+  const res = await runner.run("gh", [
+    "pr", "create",
+    "--repo", upstream,
+    "--head", `${forkOwner}:${branch}`,
+    "--title", title,
+    "--body", body,
+  ], { timeoutMs: 60000 });
+
+  if (res.status !== 0) {
+    // If a PR already exists for this branch, gh tells us — surface that as success.
+    const existingMatch = res.stderr.match(/already exists:?\s+(https:\/\/github\.com\/\S+\/pull\/(\d+))/i);
+    if (existingMatch) return { number: parseInt(existingMatch[2]!, 10), url: existingMatch[1]! };
+    return { error: `gh pr create failed: ${res.stderr.trim() || "exit " + res.status}` };
+  }
+  // Successful create — stdout is the PR URL
+  const url = res.stdout.trim().split("\n").pop() ?? "";
+  const num = url.match(/\/pull\/(\d+)/)?.[1];
+  return { number: num ? parseInt(num, 10) : 0, url };
+}
+
+// ---------------------------------------------------------------------------
+// Top-level driver
+// ---------------------------------------------------------------------------
+
+export interface PostPrInput {
+  upstream: string;          // owner/name to PR against
+  changes: FileChange[];     // SKILL.md files we touched
+  prTitle: string;
+  prBody: string;
+  branch?: string;           // defaults to cue/skill-md-fixes
+  runner?: Runner;
+  keepTmp?: boolean;         // skip cleanup of the cloned fork dir (for debugging)
+}
+
+export interface PostPrSuccess {
+  ok: true;
+  prNumber: number;
+  prUrl: string;
+  fork: string;
+  branch: string;
+  filesChanged: string[];
+}
+
+export interface PostPrFailure {
+  ok: false;
+  step: "whoami" | "fork" | "clone" | "apply" | "commit" | "push" | "pr-create";
+  error: string;
+  fork?: string;
+}
+
+export async function postPrToRepo(input: PostPrInput): Promise<PostPrSuccess | PostPrFailure> {
+  const runner = input.runner ?? defaultRunner;
+  const branch = input.branch ?? deriveBranchName(input.upstream, input.changes);
+
+  const fork = await forkRepo(runner, input.upstream);
+  if ("error" in fork) return { ok: false, step: "fork", error: fork.error };
+
+  // Best-effort sync; don't fail the run on sync failure.
+  await syncForkWithUpstream(runner, fork.fork);
+
+  const cloned = await cloneFork(runner, fork.fork, tmpdir());
+  if ("error" in cloned) return { ok: false, step: "clone", error: cloned.error, fork: fork.fork };
+
+  try {
+    const filesChanged = writeFilesToWorktree(cloned.dir, input.changes);
+    if (filesChanged.length === 0) {
+      return { ok: false, step: "apply", error: "no files changed after writing fixes (worktree already had identical content)", fork: fork.fork };
+    }
+
+    const commitRes = await commitAndPush(runner, cloned.dir, branch, input.prTitle);
+    if ("error" in commitRes) return { ok: false, step: "push", error: commitRes.error, fork: fork.fork };
+
+    const pr = await openPr(runner, input.upstream, fork.fork, branch, input.prTitle, input.prBody);
+    if ("error" in pr) return { ok: false, step: "pr-create", error: pr.error, fork: fork.fork };
+
+    return { ok: true, prNumber: pr.number, prUrl: pr.url, fork: fork.fork, branch, filesChanged };
+  } finally {
+    if (!input.keepTmp) {
+      try { rmSync(cloned.dir, { recursive: true, force: true }); } catch {}
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// PR state polling — used by cleanup-forks to find merged/closed PRs
+// ---------------------------------------------------------------------------
+
+export async function fetchPrState(
+  runner: Runner,
+  upstream: string,
+  prNumber: number,
+): Promise<"open" | "merged" | "closed" | "unknown"> {
+  const res = await runner.run("gh", ["pr", "view", String(prNumber), "--repo", upstream, "--json", "state,merged", "--jq", "{state, merged}"], { timeoutMs: 10000 });
+  if (res.status !== 0) return "unknown";
+  try {
+    const { state, merged } = JSON.parse(res.stdout) as { state: string; merged: boolean };
+    if (merged) return "merged";
+    if (state === "CLOSED") return "closed";
+    if (state === "OPEN") return "open";
+  } catch {}
+  return "unknown";
+}
+
+export async function deleteFork(runner: Runner, fork: string): Promise<{ ok: true } | { error: string }> {
+  const res = await runner.run("gh", ["repo", "delete", fork, "--yes"], { timeoutMs: 30000 });
+  if (res.status !== 0) return { error: `gh repo delete failed: ${res.stderr.trim() || "exit " + res.status}` };
+  return { ok: true };
+}
+
+// ---------------------------------------------------------------------------
+// Opt-out check — fetches the repo's README and looks for the marker
+// ---------------------------------------------------------------------------
+
+export async function checkOptOutMarker(runner: Runner, repo: string, marker: string): Promise<boolean | null> {
+  const res = await runner.run("gh", ["api", `repos/${repo}/readme`, "-H", "Accept: application/vnd.github.raw"], { timeoutMs: 10000 });
+  if (res.status !== 0) return null; // unknown — fail open (don't post in caller if uncertain)
+  return res.stdout.toLowerCase().includes(marker.toLowerCase());
+}

package/src/lib/pr-throttle.test.ts

@@ -0,0 +1,148 @@
+import { describe, expect, test, beforeEach, afterEach } from "bun:test";
+import { mkdtempSync, rmSync, existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+  loadDb, saveDb,
+  isThrottled, canPostMore, todayCount,
+  recordOpened, recordOptOut, recordSkipped, updateEntryState,
+  filterByState, hasRecordedOptOut,
+  DEFAULT_COOLDOWN_DAYS, DAILY_CAP,
+} from "./pr-throttle";
+
+let dbPath: string;
+let tmp: string;
+
+beforeEach(() => {
+  tmp = mkdtempSync(join(tmpdir(), "cue-throttle-"));
+  dbPath = join(tmp, "pr-opened.json");
+});
+afterEach(() => {
+  try { rmSync(tmp, { recursive: true, force: true }); } catch {}
+});
+
+describe("loadDb / saveDb", () => {
+  test("missing file returns empty DB", () => {
+    expect(loadDb(dbPath)).toEqual({ version: 1, history: [] });
+  });
+
+  test("save then load round-trips", () => {
+    const db = recordOpened({ version: 1, history: [] }, {
+      repo: "a/b", rulesFixed: ["R001"], prNumber: 1, prUrl: "https://example/pr/1", fork: "me/b", branch: "x",
+    });
+    saveDb(db, dbPath);
+    expect(existsSync(dbPath)).toBe(true);
+    const reloaded = loadDb(dbPath);
+    expect(reloaded.history).toHaveLength(1);
+    expect(reloaded.history[0]!.repo).toBe("a/b");
+  });
+
+  test("corrupt file is treated as empty (no throw)", () => {
+    saveDb({ version: 99 as any, history: "not an array" as any }, dbPath);
+    const reloaded = loadDb(dbPath);
+    expect(reloaded.history).toEqual([]);
+  });
+});
+
+describe("isThrottled", () => {
+  test("never-seen repo is not throttled", () => {
+    const db = { version: 1 as const, history: [] };
+    expect(isThrottled(db, "new/repo")).toBeNull();
+  });
+
+  test("recently opened repo is throttled (cooldown)", () => {
+    const db = recordOpened({ version: 1, history: [] }, {
+      repo: "a/b", rulesFixed: [], prNumber: 1, prUrl: "x", fork: "me/b", branch: "y",
+    });
+    const reason = isThrottled(db, "a/b");
+    expect(reason).toMatch(/cooldown/);
+    expect(reason).toMatch(/state=open/);
+  });
+
+  test("opted-out repo is permanently throttled", () => {
+    const db = recordOptOut({ version: 1, history: [] }, "a/b");
+    expect(isThrottled(db, "a/b")).toMatch(/cue: ignore/);
+  });
+
+  test("entry older than cooldownDays does not throttle", () => {
+    const longAgo = new Date(Date.now() - (DEFAULT_COOLDOWN_DAYS + 1) * 24 * 3600 * 1000).toISOString();
+    const db = { version: 1 as const, history: [{ repo: "a/b", state: "skipped" as const, openedAt: longAgo }] };
+    expect(isThrottled(db, "a/b")).toBeNull();
+  });
+
+  test("custom cooldownDays is respected", () => {
+    const fourDaysAgo = new Date(Date.now() - 4 * 24 * 3600 * 1000).toISOString();
+    const db = { version: 1 as const, history: [{ repo: "a/b", state: "skipped" as const, openedAt: fourDaysAgo }] };
+    expect(isThrottled(db, "a/b", 3)).toBeNull();  // 4d > 3d cooldown → free
+    expect(isThrottled(db, "a/b", 10)).toMatch(/cooldown/);  // 4d < 10d → throttled
+  });
+});
+
+describe("canPostMore / todayCount", () => {
+  test("empty DB → full headroom", () => {
+    const { ok, remaining, cap } = canPostMore({ version: 1, history: [] });
+    expect(ok).toBe(true);
+    expect(remaining).toBe(DAILY_CAP);
+    expect(cap).toBe(DAILY_CAP);
+  });
+
+  test("counts only state=open within last 24h", () => {
+    const now = new Date().toISOString();
+    const yesterday = new Date(Date.now() - 25 * 3600 * 1000).toISOString();
+    const db = {
+      version: 1 as const,
+      history: [
+        { repo: "a/1", state: "open" as const, openedAt: now, prNumber: 1 },
+        { repo: "a/2", state: "open" as const, openedAt: now, prNumber: 2 },
+        { repo: "a/3", state: "open" as const, openedAt: yesterday, prNumber: 3 },  // too old
+        { repo: "a/4", state: "skipped" as const, openedAt: now },                 // not opened
+        { repo: "a/5", state: "opted-out" as const, openedAt: now },               // not opened
+      ],
+    };
+    expect(todayCount(db)).toBe(2);
+    expect(canPostMore(db).remaining).toBe(DAILY_CAP - 2);
+  });
+
+  test("at the cap, canPostMore returns ok=false", () => {
+    const now = new Date().toISOString();
+    const history = Array.from({ length: DAILY_CAP }, (_, i) => ({
+      repo: `a/${i}`, state: "open" as const, openedAt: now, prNumber: i + 1,
+    }));
+    const db = { version: 1 as const, history };
+    expect(canPostMore(db).ok).toBe(false);
+    expect(canPostMore(db).remaining).toBe(0);
+  });
+});
+
+describe("mutations + helpers", () => {
+  test("recordOptOut + hasRecordedOptOut round-trip", () => {
+    const db = recordOptOut({ version: 1, history: [] }, "a/b");
+    expect(hasRecordedOptOut(db, "a/b")).toBe(true);
+    expect(hasRecordedOptOut(db, "x/y")).toBe(false);
+  });
+
+  test("recordSkipped writes a skipped entry with the reason", () => {
+    const db = recordSkipped({ version: 1, history: [] }, "a/b", "no fixes");
+    expect(db.history[0]!.state).toBe("skipped");
+    expect(db.history[0]!.reason).toBe("no fixes");
+  });
+
+  test("updateEntryState mutates by prNumber match", () => {
+    let db = recordOpened({ version: 1, history: [] }, {
+      repo: "a/b", rulesFixed: [], prNumber: 42, prUrl: "x", fork: "me/b", branch: "y",
+    });
+    db = updateEntryState(db, { repo: "a/b", prNumber: 42 }, "merged", { cleanedAt: "2026-05-24T00:00:00Z" });
+    expect(db.history[0]!.state).toBe("merged");
+    expect(db.history[0]!.cleanedAt).toBe("2026-05-24T00:00:00Z");
+  });
+
+  test("filterByState returns only matching entries", () => {
+    let db: any = { version: 1, history: [] };
+    db = recordOpened(db, { repo: "a/1", rulesFixed: [], prNumber: 1, prUrl: "x", fork: "me/1", branch: "y" });
+    db = recordOptOut(db, "a/2");
+    db = recordSkipped(db, "a/3", "no fixes");
+    expect(filterByState(db, ["open"]).map((e: any) => e.repo)).toEqual(["a/1"]);
+    expect(filterByState(db, ["open", "skipped"]).map((e: any) => e.repo).sort()).toEqual(["a/1", "a/3"]);
+  });
+});