@fullstackhouse/cerber 0.3.0 → 0.6.0

package/dist/runner/inflight.js

@@ -0,0 +1,33 @@
+/**
+ * Which reviews this process is running right now.
+ *
+ * `cerber serve --daemon` starts reviews from a timer while the cockpit can
+ * start them from a click. Both write the same artifact file, so two runs for
+ * one PR would race and the loser's work would vanish. The daemon's `pool`
+ * only bounds its own concurrency; this is what the two paths share.
+ *
+ * In-process only: a `cerber review` in another terminal is invisible here.
+ * That's the pre-existing situation and the artifact write is atomic, so the
+ * cost is a wasted run, not a corrupt file.
+ */
+const running = new Set();
+export class ReviewInProgressError extends Error {
+    id;
+    constructor(id) {
+        super(`a review of ${id} is already running`);
+        this.id = id;
+        this.name = "ReviewInProgressError";
+    }
+}
+/** Claim the slot for an artifact id. Throws if it is already claimed. */
+export function beginReview(id) {
+    if (running.has(id))
+        throw new ReviewInProgressError(id);
+    running.add(id);
+}
+export function endReview(id) {
+    running.delete(id);
+}
+export function isReviewRunning(id) {
+    return running.has(id);
+}

package/dist/runner/prompt.js

@@ -8,12 +8,12 @@ export function buildReviewPrompt(pr, diff) {
 Respond with ONLY a JSON object (no markdown fences, no prose before or after) matching exactly this shape:
 
 {
-  "summary": "markdown — what this PR actually does and why, written top-down: problem first, then the solution, then notable technical details. 1-3 paragraphs.",
+  "summary": "markdown — what this PR actually does and why, written top-down: problem first in plain language, then the solution, then notable technical details. A reader should be able to stop after any paragraph with a correct, just less detailed, picture. 1-3 paragraphs.",
   "chapters": [
     {
       "id": "short-kebab-id",
       "title": "Human title of this logical group of changes",
-      "explanation": "markdown — what this group changes and why, what to pay attention to",
+      "explanation": "markdown — 2-3 plain sentences: what this group changes, why, and what to look at closely",
       "files": ["path/to/file.ts", "path/other.ts"]
     }
   ],
@@ -21,7 +21,7 @@ Respond with ONLY a JSON object (no markdown fences, no prose before or after) m
     {
       "path": "path/to/file.ts",
       "line": 42,
-      "body": "markdown — the review comment. Concrete, actionable, kind.",
+      "body": "markdown — the review comment. First sentence states the problem plainly; then the evidence or fix. Concrete, actionable, kind.",
       "chapterId": "short-kebab-id"
     }
   ],
@@ -32,6 +32,13 @@ Respond with ONLY a JSON object (no markdown fences, no prose before or after) m
   }
 }
 
+Writing style (applies to every markdown field):
+- Write like one human explaining to another: plain words, short sentences, no jargon. Someone who has NOT read the diff should follow every sentence.
+- Lead with the point. State the claim first, support it after. No hedging chains, no em-dash clause stacks.
+- Keep comments to ~3 sentences unless a code suggestion needs more. Length must buy clarity, not cover uncertainty — if you are unsure, say so in one plain sentence.
+- Do NOT imitate the PR description's writing style. Keep this plain register even when the PR itself is dense or writerly.
+- Describe the effect a person would see before the mechanism behind it. Not: "A stray closing code fence with prose on the same line left the block open, rendering the conditions below as code." But: "Also fixes a markdown typo: a code block was never closed, so everything after it displayed as code."
+
 Rules:
 - Group ALL changed files into chapters that tell the story of the PR (schema first, then logic, then tests, etc). Every changed file must appear in exactly one chapter.
 - "line" is the line number in the NEW version of the file (the "+" side of the diff). Use null for file-level comments. Only reference lines that appear in the diff.

package/dist/runner/review.js

@@ -1,8 +1,10 @@
 import { randomUUID } from "node:crypto";
 import { AiReviewSchema, SCHEMA_VERSION, artifactId, } from "../core/artifact.js";
 import { fetchPrDiff, fetchPrInfo } from "../core/gh.js";
+import { carryOverComments } from "../core/refresh.js";
 import { loadArtifact, saveArtifact } from "../core/state.js";
 import { extractJson, runClaude } from "./claude.js";
+import { beginReview, endReview } from "./inflight.js";
 import { buildReviewPrompt, buildRetryPrompt } from "./prompt.js";
 /** Statuses that a fresh artifact can keep without a re-run. */
 const FRESH_STATUSES = new Set(["ready", "reviewed", "sent", "skipped"]);
@@ -11,12 +13,21 @@ const FRESH_STATUSES = new Set(["ready", "reviewed", "sent", "skipped"]);
  * Everything stays local — nothing is ever written to GitHub.
  */
 export async function reviewPr(ref, opts = {}) {
+    beginReview(artifactId(ref));
+    try {
+        return await runReview(ref, opts);
+    }
+    finally {
+        endReview(artifactId(ref));
+    }
+}
+async function runReview(ref, opts) {
     const log = opts.onProgress ?? (() => { });
     const now = () => new Date().toISOString();
     log(`Fetching ${ref.owner}/${ref.repo}#${ref.number}…`);
     const pr = await fetchPrInfo(ref);
+    const existing = await loadArtifact(artifactId(pr));
     if (!opts.force) {
-        const existing = await loadArtifact(artifactId(pr));
         if (existing &&
             FRESH_STATUSES.has(existing.status) &&
             existing.pr.headSha !== "" &&
@@ -30,7 +41,7 @@ export async function reviewPr(ref, opts = {}) {
         schemaVersion: SCHEMA_VERSION,
         id: artifactId(pr),
         status: "running",
-        createdAt: now(),
+        createdAt: existing?.createdAt ?? now(),
         updatedAt: now(),
         pr,
         diff,
@@ -40,6 +51,8 @@ export async function reviewPr(ref, opts = {}) {
         verdict: null,
         run: { model: opts.model ?? null, startedAt: now(), finishedAt: null, costUsd: null, error: null },
         sent: null,
+        refresh: null,
+        calibration: null,
     };
     await saveArtifact(artifact);
     const { prompt, truncated } = buildReviewPrompt(pr, diff);
@@ -70,6 +83,9 @@ export async function reviewPr(ref, opts = {}) {
                 chapterId: c.chapterId ?? null,
                 origin: "ai",
                 status: "draft",
+                editedByUser: false,
+                originalLine: null,
+                drifted: false,
             })),
             verdict: review.ai.verdict,
             run: {
@@ -80,6 +96,16 @@ export async function reviewPr(ref, opts = {}) {
                 error: null,
             },
         };
+        // A re-review regenerates the AI's comments, but the human's own comments
+        // and their rewrites of AI ones are work the run must not throw away.
+        if (existing) {
+            const { comments, carried, drifted } = carryOverComments(existing, artifact);
+            if (carried > 0) {
+                artifact = { ...artifact, comments };
+                log(`Carried over ${carried} comment(s) you wrote or edited` +
+                    (drifted > 0 ? `; ${drifted} no longer match the diff and will post in the body.` : "."));
+            }
+        }
     }
     catch (err) {
         artifact = {

package/dist/server/daemon.js

@@ -0,0 +1,142 @@
+import { artifactKey } from "../core/artifact.js";
+import { evaluateAutoSend } from "../core/autosend.js";
+import { searchAwaitingMe, submitReview } from "../core/gh.js";
+import { buildReviewPayload, computeCalibration } from "../core/send.js";
+import { appendAutoSendLog, updateArtifactByKey } from "../core/state.js";
+import { ReviewInProgressError } from "../runner/inflight.js";
+import { pool, reviewPr } from "../runner/review.js";
+/**
+ * Poll GitHub for PRs awaiting the user's review and keep their artifacts
+ * warm. Reviews are read-only; the daemon NEVER sends anything.
+ */
+export function startDaemon(opts) {
+    let timer = null;
+    let stopped = false;
+    const status = {
+        enabled: true,
+        polling: false,
+        repos: opts.repos,
+        intervalMs: opts.intervalMs,
+        polls: 0,
+        errors: 0,
+        lastPollAt: null,
+        nextPollAt: new Date(Date.now()).toISOString(),
+        lastSummary: null,
+        autoSend: opts.autoSend,
+        autoSendThreshold: opts.autoSendThreshold,
+        autoSent: 0,
+        autoSendCandidates: 0,
+    };
+    const log = (m) => console.log(`[daemon] ${m}`);
+    async function poll() {
+        if (status.polling)
+            return;
+        status.polling = true;
+        status.lastPollAt = new Date().toISOString();
+        try {
+            const filters = opts.repos.length > 0 ? opts.repos : [undefined];
+            const seen = new Set();
+            const refs = (await Promise.all(filters.map((repo) => searchAwaitingMe(repo))))
+                .flat()
+                .filter((r) => {
+                const id = `${r.owner}/${r.repo}#${r.number}`;
+                if (seen.has(id))
+                    return false;
+                seen.add(id);
+                return true;
+            });
+            let reviewed = 0;
+            let skipped = 0;
+            let failed = 0;
+            await pool(refs, opts.parallel, async (ref) => {
+                const label = `${ref.owner}/${ref.repo}#${ref.number}`;
+                try {
+                    const result = await reviewPr(ref, {
+                        model: opts.model,
+                        onProgress: (m) => log(`[${label}] ${m}`),
+                    });
+                    if (result.skipped)
+                        skipped++;
+                    else {
+                        reviewed++;
+                        await handleAutoSend(result.artifact);
+                    }
+                }
+                catch (err) {
+                    if (err instanceof ReviewInProgressError) {
+                        // The cockpit (or an earlier, slower poll) is already on it.
+                        skipped++;
+                        return;
+                    }
+                    failed++;
+                    status.errors++;
+                    log(`[${label}] failed: ${err instanceof Error ? err.message : err}`);
+                }
+            });
+            status.lastSummary = `${refs.length} awaiting; ${reviewed} reviewed, ${skipped} up to date${failed > 0 ? `, ${failed} failed` : ""}`;
+            log(status.lastSummary);
+        }
+        catch (err) {
+            status.errors++;
+            status.lastSummary = `poll failed: ${err instanceof Error ? err.message : err}`;
+            log(status.lastSummary);
+        }
+        finally {
+            status.polls++;
+            status.polling = false;
+            if (!stopped) {
+                status.nextPollAt = new Date(Date.now() + opts.intervalMs).toISOString();
+                timer = setTimeout(poll, opts.intervalMs);
+            }
+        }
+    }
+    async function handleAutoSend(artifact) {
+        const decision = evaluateAutoSend(artifact, opts.autoSendThreshold);
+        if (decision.eligible)
+            status.autoSendCandidates++;
+        const entryBase = {
+            at: new Date().toISOString(),
+            id: artifact.id,
+            recommendation: artifact.verdict?.recommendation ?? null,
+            confidence: artifact.verdict?.confidence ?? null,
+            mode: opts.autoSend,
+        };
+        if (!decision.eligible) {
+            await appendAutoSendLog({ ...entryBase, decision: decision.reason, sent: false });
+            return;
+        }
+        if (opts.autoSend === "shadow") {
+            log(`[${artifact.id}] WOULD auto-send: ${decision.reason} (shadow mode — nothing sent)`);
+            await appendAutoSendLog({ ...entryBase, decision: `would send: ${decision.reason}`, sent: false });
+            return;
+        }
+        try {
+            const payload = buildReviewPayload(artifact, "APPROVE");
+            const { url } = await submitReview({ owner: artifact.pr.owner, repo: artifact.pr.repo, number: artifact.pr.number }, { event: payload.event, body: payload.body, comments: payload.comments, commitId: payload.commitId });
+            await updateArtifactByKey(artifactKey(artifact.id), (a) => ({
+                ...a,
+                status: "sent",
+                sent: { at: new Date().toISOString(), event: "APPROVE", url, auto: true },
+                calibration: computeCalibration(a, "APPROVE"),
+            }));
+            status.autoSent++;
+            log(`[${artifact.id}] AUTO-SENT approve (${decision.reason})${url ? ` — ${url}` : ""}`);
+            await appendAutoSendLog({ ...entryBase, decision: `auto-sent: ${decision.reason}`, sent: true });
+        }
+        catch (err) {
+            status.errors++;
+            const message = err instanceof Error ? err.message : String(err);
+            log(`[${artifact.id}] auto-send failed: ${message}`);
+            await appendAutoSendLog({ ...entryBase, decision: `auto-send failed: ${message}`, sent: false });
+        }
+    }
+    void poll();
+    return {
+        status: () => ({ ...status }),
+        stop: () => {
+            stopped = true;
+            if (timer)
+                clearTimeout(timer);
+        },
+    };
+}

package/dist/server/index.js

@@ -1,18 +1,39 @@
 import { serve } from "@hono/node-server";
 import { serveStatic } from "@hono/node-server/serve-static";
 import { Hono } from "hono";
+import { getCookie, setCookie } from "hono/cookie";
 import { promises as fs } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { randomUUID } from "node:crypto";
 import { ArtifactStatusSchema, VerdictSchema, artifactKey } from "../core/artifact.js";
 import { toMarkdown } from "../core/export.js";
-import { submitReview } from "../core/gh.js";
-import { buildReviewPayload } from "../core/send.js";
-import { listArtifacts, loadArtifactByKey, updateArtifactByKey } from "../core/state.js";
+import { fetchPrDiff, fetchPrInfo, submitReview } from "../core/gh.js";
+import { refreshArtifact } from "../core/refresh.js";
+import { buildReviewPayload, computeCalibration } from "../core/send.js";
+import { listArtifacts, loadArtifactByKey, reconcileRunning, updateArtifactByKey, } from "../core/state.js";
+import { isReviewRunning } from "../runner/inflight.js";
+import { reviewPr } from "../runner/review.js";
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
-export async function startServer(opts) {
+export async function buildApp(opts) {
     const app = new Hono();
+    if (opts.token) {
+        const token = opts.token;
+        app.use("*", async (c, next) => {
+            const query = c.req.query("token");
+            const cookie = getCookie(c, "cerber_token");
+            const header = c.req.header("authorization");
+            if (query === token || cookie === token || header === `Bearer ${token}`) {
+                if (query === token && cookie !== token) {
+                    // First visit via ?token=… — set the cookie so the SPA's asset and API requests pass.
+                    setCookie(c, "cerber_token", token, { httpOnly: true, sameSite: "Strict", path: "/" });
+                }
+                return next();
+            }
+            return c.text("unauthorized — pass ?token=… or Authorization: Bearer …\n", 401);
+        });
+    }
+    app.get("/api/daemon", (c) => c.json(opts.daemon ? opts.daemon.status() : { enabled: false }));
     app.get("/api/reviews", async (c) => {
         const artifacts = await listArtifacts();
         return c.json(artifacts.map((a) => ({
@@ -74,6 +95,9 @@ export async function startServer(opts) {
                     ...(body.status !== undefined
                         ? { status: body.status }
                         : {}),
+                    ...(body.body !== undefined && body.body !== cm.body && cm.origin === "ai"
+                        ? { editedByUser: true }
+                        : {}),
                 }
                 : cm),
         }));
@@ -95,6 +119,9 @@ export async function startServer(opts) {
                     chapterId: body.chapterId ?? null,
                     origin: "user",
                     status: "draft",
+                    editedByUser: false,
+                    originalLine: null,
+                    drifted: false,
                 },
             ],
         }));
@@ -112,6 +139,76 @@ export async function startServer(opts) {
             return c.json({ error: "not found" }, 404);
         return c.json(updated);
     });
+    // ---- Freshness: pull a review forward onto the PR's current head ----
+    // Read-only against GitHub (pr view + pr diff); writes only the local artifact.
+    app.post("/api/reviews/:key/refresh", async (c) => {
+        const artifact = await loadArtifactByKey(c.req.param("key"));
+        if (!artifact)
+            return c.json({ error: "not found" }, 404);
+        const ref = { owner: artifact.pr.owner, repo: artifact.pr.repo, number: artifact.pr.number };
+        let pr;
+        try {
+            pr = await fetchPrInfo(ref);
+        }
+        catch (err) {
+            return c.json({ error: err instanceof Error ? err.message : String(err) }, 502);
+        }
+        const stale = artifact.pr.headSha !== "" && artifact.pr.headSha !== pr.headSha;
+        // A sent review is a record of what was posted — never rewrite it. A running
+        // one is mid-run and would be overwritten from under the runner.
+        if (!stale || artifact.sent || artifact.status === "running") {
+            return c.json({ stale, changed: false, prState: pr.state, artifact });
+        }
+        try {
+            const diff = await fetchPrDiff(ref);
+            const result = refreshArtifact(artifact, pr, diff);
+            const saved = await updateArtifactByKey(c.req.param("key"), () => result.artifact);
+            return c.json({
+                stale: true,
+                changed: result.changed,
+                prState: pr.state,
+                moved: result.moved,
+                drifted: result.drifted,
+                artifact: saved,
+            });
+        }
+        catch (err) {
+            return c.json({ error: err instanceof Error ? err.message : String(err) }, 502);
+        }
+    });
+    // ---- Re-review: start an AI run for a PR that has moved on ----
+    app.post("/api/reviews/:key/rerun", async (c) => {
+        const key = c.req.param("key");
+        const artifact = await loadArtifactByKey(key);
+        if (!artifact)
+            return c.json({ error: "not found" }, 404);
+        if (artifact.sent)
+            return c.json({ error: `already sent at ${artifact.sent.at}` }, 409);
+        if (isReviewRunning(artifact.id)) {
+            return c.json({ error: "a review of this PR is already running" }, 409);
+        }
+        const ref = { owner: artifact.pr.owner, repo: artifact.pr.repo, number: artifact.pr.number };
+        // Mark it running before responding, so the cockpit's next poll can't catch
+        // the old "ready" status and conclude the run already finished.
+        const running = await updateArtifactByKey(key, (a) => ({
+            ...a,
+            status: "running",
+            run: { model: null, startedAt: new Date().toISOString(), finishedAt: null, costUsd: null, error: null },
+        }));
+        // Minutes-long: run it detached and let the cockpit poll the artifact.
+        void reviewPr(ref, { force: true, onProgress: (m) => console.log(`[rerun ${artifact.id}] ${m}`) })
+            .catch(async (err) => {
+            const message = err instanceof Error ? err.message : String(err);
+            console.error(`[rerun ${artifact.id}] failed: ${message}`);
+            // The runner marks the artifact failed once it owns it; a failure before
+            // that (fetching the PR, or a run already in flight) would otherwise
+            // leave it stuck at "running" with nothing to clear it.
+            await updateArtifactByKey(key, (a) => a.status === "running"
+                ? { ...a, status: "failed", run: a.run ? { ...a.run, error: message } : null }
+                : a).catch(() => { });
+        });
+        return c.json(running, 202);
+    });
     // ---- Export (local file download) ----
     app.get("/api/reviews/:key/export", async (c) => {
         const artifact = await loadArtifactByKey(c.req.param("key"));
@@ -138,11 +235,12 @@ export async function startServer(opts) {
         }
         const payload = buildReviewPayload(artifact, event);
         try {
-            const { url } = await submitReview({ owner: artifact.pr.owner, repo: artifact.pr.repo, number: artifact.pr.number }, { event: payload.event, body: payload.body, comments: payload.comments });
+            const { url } = await submitReview({ owner: artifact.pr.owner, repo: artifact.pr.repo, number: artifact.pr.number }, { event: payload.event, body: payload.body, comments: payload.comments, commitId: payload.commitId });
             const updated = await updateArtifactByKey(c.req.param("key"), (a) => ({
                 ...a,
                 status: "sent",
-                sent: { at: new Date().toISOString(), event: payload.event, url },
+                sent: { at: new Date().toISOString(), event: payload.event, url, auto: false },
+                calibration: computeCalibration(a, payload.event),
             }));
             return c.json(updated);
         }
@@ -172,7 +270,18 @@ export async function startServer(opts) {
     else {
         app.get("/", (c) => c.text("cerber API is running, but the web cockpit is not built.\nRun `pnpm build` in the cerber repo, or use the API: GET /api/reviews\n"));
     }
+    return app;
+}
+export async function startServer(opts) {
+    const cleared = await reconcileRunning();
+    if (cleared > 0) {
+        console.log(`Cleared ${cleared} review(s) left mid-run by a previous process — re-review to retry.`);
+    }
+    const app = await buildApp(opts);
     serve({ fetch: app.fetch, port: opts.port, hostname: opts.host }, (info) => {
-        console.log(`cerber cockpit: http://${opts.host}:${info.port}`);
+        const tokenHint = opts.token ? `/?token=${opts.token}` : "";
+        console.log(`cerber cockpit: http://${opts.host}:${info.port}${tokenHint}`);
+        if (opts.daemon)
+            console.log("daemon: polling for PRs awaiting your review");
     });
 }

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@fullstackhouse/cerber",
-  "version": "0.3.0",
+  "version": "0.6.0",
   "description": "AI code-review cockpit: Claude reviews your PRs into local artifacts; nothing reaches GitHub until you say so.",
   "license": "MIT",
   "repository": "github:fullstackhouse/cerber",
   "type": "module",
+  "packageManager": "pnpm@10.33.2",
   "bin": {
     "cerber": "dist/cli/index.js"
   },
@@ -36,6 +37,8 @@
     "@types/react": "^19.0.4",
     "@types/react-dom": "^19.0.2",
     "@vitejs/plugin-react": "^4.3.4",
+    "dompurify": "^3.4.13",
+    "marked": "^18.0.10",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "tsx": "^4.19.2",