@fullstackhouse/cerber 0.29.1 → 0.31.0

package/dist/core/preflight.js

@@ -0,0 +1,82 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+export function isBlocking(check) {
+    return check.status !== "ok";
+}
+async function run(bin, args) {
+    try {
+        const { stdout, stderr } = await execFileAsync(bin, args);
+        return { ok: true, out: (stdout || stderr).trim() };
+    }
+    catch (err) {
+        const e = err;
+        // ENOENT is "not installed"; a non-zero exit is the tool answering "no".
+        if (e.code === "ENOENT")
+            return { ok: false, out: "ENOENT" };
+        return { ok: false, out: (e.stderr || e.stdout || e.message || "").trim() };
+    }
+}
+export async function checkGh() {
+    const version = await run("gh", ["--version"]);
+    if (!version.ok && version.out === "ENOENT") {
+        return {
+            name: "gh (GitHub CLI)",
+            status: "missing",
+            fix: "Install it: https://cli.github.com — then run `gh auth login`.",
+        };
+    }
+    // `gh auth status` exits non-zero when no account is logged in, which is the
+    // case that otherwise surfaces as an empty cockpit.
+    const auth = await run("gh", ["auth", "status"]);
+    if (!auth.ok) {
+        return {
+            name: "gh (GitHub CLI)",
+            status: "unauthenticated",
+            fix: "Run `gh auth login` — cerber reads PRs as you, and sends as you.",
+        };
+    }
+    return { name: "gh (GitHub CLI)", status: "ok", detail: version.out.split("\n")[0] };
+}
+export async function checkClaude() {
+    const version = await run("claude", ["--version"]);
+    if (!version.ok && version.out === "ENOENT") {
+        return {
+            name: "claude (Claude Code)",
+            status: "missing",
+            fix: "Install it: https://claude.com/claude-code — cerber rides your login, there is no API-key path.",
+        };
+    }
+    if (!version.ok) {
+        return {
+            name: "claude (Claude Code)",
+            status: "unauthenticated",
+            fix: "Run `claude` once and log in — a review is drafted through your Claude Code session.",
+        };
+    }
+    return { name: "claude (Claude Code)", status: "ok", detail: version.out.split("\n")[0] };
+}
+export async function checkGit() {
+    const version = await run("git", ["--version"]);
+    if (!version.ok) {
+        return {
+            name: "git",
+            status: "missing",
+            fix: "Install git — cerber fetches each PR head into ~/.cerber/src to review the code, not just the diff.",
+        };
+    }
+    return { name: "git", status: "ok", detail: version.out.split("\n")[0] };
+}
+/** Everything cerber shells out to, checked in parallel. */
+export async function preflight() {
+    return Promise.all([checkGh(), checkClaude(), checkGit()]);
+}
+/** The blocking checks, formatted as the message printed instead of failing later. */
+export function formatBlockers(checks) {
+    const bad = checks.filter(isBlocking);
+    const lines = bad.map((c) => {
+        const what = c.status === "missing" ? "not installed" : "not logged in";
+        return `  ✗ ${c.name} — ${what}\n    ${c.fix ?? ""}`.trimEnd();
+    });
+    return `cerber needs these before it can do anything:\n\n${lines.join("\n")}\n\nRun \`cerber doctor\` to re-check.`;
+}

package/dist/core/refresh.js

@@ -76,6 +76,8 @@ export function mergeRunResult(fresh, current) {
         // the stamp away with the status.
         settledAt: userOwnsStatus(current) ? current.settledAt : fresh.settledAt,
         sent: current.sent,
+        // Disk wins: the ledger is the poll's, and the run knows nothing about it.
+        notified: current.notified,
         calibration: current.calibration,
         filed: current.filed,
         chat: current.chat,

package/dist/core/revise.js

@@ -63,6 +63,9 @@ export function mergeConcurrentEdits(before, after, current) {
         // A turn never writes a send body, so one written while it ran is the
         // user's and stands — as does clearing one.
         bodyOverride: current.bodyOverride,
+        // Nor does a turn announce anything: the ledger is the poll's, and a turn
+        // takes minutes, which is long enough for a poll to have stamped it.
+        notified: current.notified,
     };
 }
 export function applyRevisions(artifact, revisions, opts = {}) {

package/dist/runner/review.js

@@ -162,6 +162,13 @@ async function performReview(ref, pr, existing, opts, log) {
         status: "running",
         createdAt: existing?.createdAt ?? now(),
         updatedAt: now(),
+        // The announcement ledger belongs to the row, not to the run: a PR the poll
+        // found and has not told you about yet is still owed that tap when this
+        // draft lands (`notified` in artifact.ts). Seeded from the row this run
+        // starts on, and re-read from disk on the way out of both writes below —
+        // `existing` was loaded minutes ago, and a poll may have announced the row
+        // since.
+        notified: existing?.notified,
         pr,
         diff,
         summary: "",
@@ -196,7 +203,30 @@ async function performReview(ref, pr, existing, opts, log) {
         preChat: null,
         pendingChat: null,
     };
-    await saveArtifact(artifact);
+    // Not a plain save. The fetch and checkout above take minutes, and the row on
+    // disk may have moved twice over in that window:
+    //
+    //   - a poll may have announced it, writing a ledger entry `existing` cannot
+    //     know about. Writing the stale one back would spend the tap twice.
+    //   - the user may have settled or sent it, which is a decision this run does
+    //     not get to overwrite by marking the row `running`. The run goes on and
+    //     folds its draft underneath at the end (`mergeRunResult`) — the same
+    //     line that function already holds, now held by the claim as well.
+    //
+    // Which settle it is matters, and `existing` is what tells them apart: a row
+    // already settled when this run *started* is one you took back deliberately
+    // (the guard above only lets a forced re-review that far), and claiming it is
+    // how the reopen happens at all. A settle that appeared since is the one this
+    // must not touch.
+    const decided = existing ? userOwnsStatus(existing) : false;
+    const claimed = await updateArtifactByKey(artifactKey(artifact.id), (current) => !decided && userOwnsStatus(current) ? current : { ...artifact, notified: current.notified });
+    const held = claimed !== null && !decided && userOwnsStatus(claimed);
+    if (!held) {
+        if (claimed)
+            artifact = claimed;
+        else
+            await saveArtifact(artifact);
+    }
     const { prompt, truncated } = buildReviewPrompt(pr, diff, { source: source !== null, trusted });
     if (truncated)
         log("Warning: diff exceeds the context budget and was truncated.");

package/dist/server/daemon.js

@@ -3,7 +3,7 @@ import { evaluateAutoSend } from "../core/autosend.js";
 import { loadConfig } from "../core/config.js";
 import { classifyReply, currentLogin, fetchConversation, fetchLastReviewRequest, fetchOwnReview, fetchPrInfo, fetchReviewRequests, lastMentionOfYou, lastWordOfYours, searchAwaitingMe, stillRequested, submitReview, } from "../core/gh.js";
 import { withWriter } from "../core/history.js";
-import { notice, notify } from "../core/notify.js";
+import { pendingNews, notice, notify } from "../core/notify.js";
 import { buildReviewPayload, computeCalibration } from "../core/send.js";
 import { appendAutoSendLog, deleteArtifact, listArtifacts, loadArtifact, noteHistory, saveArtifact, updateArtifactByKey, } from "../core/state.js";
 import { ReviewInProgressError } from "../runner/inflight.js";
@@ -48,6 +48,9 @@ export function stubArtifact(ref) {
         refresh: null,
         filed: null,
         settledAt: null,
+        // Null, not absent: the poll found this PR, so it owes the machine a tap
+        // for it — once there is something to tap you about (§9.8).
+        notified: null,
         calibration: null,
         chat: [],
         preChat: null,
@@ -553,20 +556,48 @@ export function startDaemon(opts) {
      */
     let notifierWorks = null;
     /**
-     * Tap this machine when a PR lands in the queue.
+     * Tap this machine about every row that has become worth walking back to,
+     * once each.
      *
-     * An artifact is the ledger this rides on: a PR is announced on the poll that
-     * first writes a stub for it, so a restart re-announces nothing, and a PR
-     * that arrived while `serve` was down is still news the next time it runs.
-     * The cockpit's bell announces the same arrival, off the same stub — which is
-     * why it stands down when this is on and both are on one machine.
+     * `notified` on the artifact is the ledger this rides on: the poll writes it
+     * null when it first stubs a PR ("owed a tap"), and stamps it here. So a
+     * restart re-announces nothing, a PR that arrived while `serve` was down is
+     * still news the next time it runs — and, unlike announcing straight off the
+     * discovery, a tap the daemon is holding back survives the wait. The cockpit's
+     * bell works off the same rule (`isNews`), which is why it stands down when
+     * this is on and both are on one machine.
+     *
+     * Stamped whether or not the notifier worked, and whether or not it was even
+     * asked (`tell` is the notify toggle). A machine with no notifier would
+     * otherwise re-try every row every poll, and a toggle switched on after a
+     * quiet week would announce that whole week at once — the same reason the
+     * browser bell records what it stays quiet about.
      */
-    async function announce(arrivals) {
-        const n = notice(arrivals, cockpitUrl);
+    async function announce(autoReview, tell) {
+        const owed = (await listArtifacts()).flatMap((a) => {
+            const news = pendingNews(a, autoReview);
+            return news ? [{ id: a.id, news }] : [];
+        });
+        // `cockpitUrl` is where a click lands, and it is read here rather than
+        // captured: `serve` hands it over once its port is bound, which can be
+        // after the first poll has already started.
+        const n = notice(owed.map((o) => o.news), cockpitUrl);
         if (!n)
             return;
-        notifierWorks = await notify(n);
-        if (notifierWorks)
+        if (tell)
+            notifierWorks = await notify(n);
+        const at = new Date().toISOString();
+        // Stamped after the tap, not before: a crash in between costs a repeated
+        // notification, and the other order costs the only one there was going
+        // to be. What was said is stamped along with it, because "told you it
+        // failed" and "told you about the draft" are different news.
+        for (const { id, news } of owed) {
+            await updateArtifactByKey(artifactKey(id), (current) => 
+            // Absent means the row was replaced mid-poll by one nobody meant to
+            // announce (a hand-pulled review) — don't re-open a ledger for it.
+            current.notified === undefined ? current : { ...current, notified: { at, drafted: Boolean(news.draft) } });
+        }
+        if (!tell || notifierWorks)
             return;
         if (notifierMissing)
             return;
@@ -601,6 +632,49 @@ export function startDaemon(opts) {
             }
         });
     }
+    /**
+     * Write a run's failure onto the row when the runner never got far enough to
+     * do it itself.
+     *
+     * A review that falls over before it owns the artifact — the PR read, the
+     * diff fetch — leaves the row sitting at `awaiting`, which reads as "a draft
+     * is coming" to everything downstream: the tap waits for one that will never
+     * be written, and the cockpit's own bell, which has only the row to go on,
+     * waits forever. Recording it is what keeps the two halves telling one story;
+     * the alternative, a set of ids the poll passes to its own notifier, is a
+     * fact the daemon knows and nobody else can see.
+     *
+     * Only a row still sitting at `awaiting` with nothing in flight on it is
+     * rewritten. A settle that landed while the run worked is a decision, and a
+     * failure is no reason to overrule it — the same line `mergeRunResult` holds.
+     * The run test is "not in flight" rather than "absent" because a row that was
+     * settled and then reopened keeps the run it had (`reopenedStatus`): reading
+     * that leftover as a live run would refuse to record the new failure, and the
+     * row would sit at `awaiting` forever waiting on a draft nobody is writing —
+     * the exact silence this function exists to break.
+     */
+    async function recordEarlyFailure(id, error) {
+        await updateArtifactByKey(artifactKey(id), (a) => a.status === "awaiting" && (a.run === null || a.run.finishedAt !== null)
+            ? {
+                ...a,
+                status: "failed",
+                run: {
+                    model: opts.model ?? null,
+                    startedAt: new Date().toISOString(),
+                    finishedAt: new Date().toISOString(),
+                    costUsd: null,
+                    error,
+                    withSource: opts.withSource !== false,
+                    trusted: false,
+                    sessionId: null,
+                    trigger: "daemon",
+                    reviewedSha: null,
+                },
+            }
+            : a).catch(() => {
+            // Book-keeping: a row we could not write is one the next poll retries.
+        });
+    }
     async function reviewAll(refs) {
         let reviewed = 0;
         let skipped = 0;
@@ -630,7 +704,9 @@ export function startDaemon(opts) {
                 }
                 failed++;
                 status.errors++;
-                log(`[${label}] failed: ${err instanceof Error ? err.message : err}`);
+                const message = err instanceof Error ? err.message : String(err);
+                await recordEarlyFailure(label, message);
+                log(`[${label}] failed: ${message}`);
             }
         });
         return { reviewed, skipped, failed };
@@ -679,16 +755,6 @@ export function startDaemon(opts) {
             // A failed poll leaves the last good list up; lastPollError says so.
             status.awaiting = await classifyAll(refs);
             const { discovered } = await syncQueue(refs);
-            // Before the reviews, not after: the arrival is the news, and drafting it
-            // takes minutes. This is the same moment the cockpit's bell would ring.
-            if (notifyOn && discovered.length > 0) {
-                await announce(discovered);
-                // Recomputed on the spot rather than left to the next poll: that is
-                // minutes away, and the cockpit would spend them deferring to a tap
-                // that never came. Recomputed rather than only cleared, so a machine
-                // whose notifier comes back takes the job back with it.
-                status.notify = announcing();
-            }
             if (autoReview) {
                 const { reviewed, skipped, failed } = await reviewAll(refs);
                 status.lastSummary =
@@ -698,6 +764,19 @@ export function startDaemon(opts) {
             else {
                 status.lastSummary = `${refs.length} awaiting${discovered.length > 0 ? `, ${discovered.length} new` : ""} (auto-review off)`;
             }
+            // After the drafting, not before it. The arrival is not the news when
+            // cerber is about to write the review itself: a tap that lands on "no run
+            // yet" makes the walk back to the cockpit for nothing, and by the time
+            // there *is* something to read the PR is no longer new. So the tap waits
+            // for the draft — and for a PR nobody is drafting (auto-review off, or a
+            // run that failed) it goes out here all the same. `isNews` is the rule,
+            // and the cockpit's bell reads the same one.
+            await announce(autoReview, notifyOn);
+            // Recomputed on the spot rather than left to the next poll: that is
+            // minutes away, and the cockpit would spend them deferring to a tap that
+            // never came. Recomputed rather than only cleared, so a machine whose
+            // notifier comes back takes the job back with it.
+            status.notify = announcing();
             log(status.lastSummary);
         }
         catch (err) {

package/dist/server/index.js

@@ -12,7 +12,7 @@ import { toMarkdown } from "../core/export.js";
 import { fetchPrDiff, fetchPrInfo, parsePrRef, submitReview } from "../core/gh.js";
 import { z } from "zod";
 import { DaemonConfigSchema, configPath, loadConfig, saveConfig } from "../core/config.js";
-import { refreshArtifact } from "../core/refresh.js";
+import { refreshArtifact, userOwnsStatus } from "../core/refresh.js";
 import { withWriter } from "../core/history.js";
 import { TrustRuleError, describeRule, explainRule, parseTrustRule } from "../core/trust.js";
 import { buildReviewPayload, computeCalibration } from "../core/send.js";
@@ -180,6 +180,12 @@ export async function buildApp(opts) {
             blockerCount: a.comments.filter((cm) => cm.status !== "dropped" && cm.severity === "blocker")
                 .length,
             gradedCount: a.comments.filter((cm) => cm.severity != null).length,
+            // Whether the machine ever meant to announce this row (§9.8's ledger:
+            // absent means nobody did — a review pulled in by hand). The browser
+            // bell has only the list to go on, so without this it would announce
+            // rows the daemon deliberately stays silent about, and the two bells
+            // would stop telling one story.
+            announceable: a.notified !== undefined,
             costUsd: a.run?.costUsd ?? null,
             withSource: a.run?.withSource ?? null,
             trusted: a.run?.trusted ?? null,
@@ -255,6 +261,12 @@ export async function buildApp(opts) {
             status: "running",
             createdAt: now,
             updatedAt: now,
+            // Kept from the stub this replaces, when there is one: the poll found
+            // that PR and owes the machine a tap for it once the draft lands. Absent
+            // on a PR pasted into the cockpit — nobody asked to be told about that
+            // one, and it is on screen already. Re-read from disk at the write below,
+            // since `fetchPrInfo` gave a poll time to announce the stub.
+            notified: existing?.notified,
             pr,
             diff: "",
             summary: "",
@@ -283,7 +295,19 @@ export async function buildApp(opts) {
             preChat: null,
             pendingChat: null,
         };
-        await saveArtifact(artifact);
+        // A settle or a send that landed while `fetchPrInfo` was in flight is a
+        // decision, and claiming the row for a run would erase it — the detached
+        // run below folds its draft under whatever the row says instead
+        // (`mergeRunResult`), which is the same line every other writer holds.
+        const claimed = await updateArtifactByKey(artifactKey(artifact.id), (current) => userOwnsStatus(current) ? current : { ...artifact, notified: current.notified });
+        // Declining the claim is only half the job: the run below forces, and a
+        // forced run reopens a settled row on purpose. So the decision ends the
+        // request — hand it back and start nothing.
+        if (claimed && userOwnsStatus(claimed)) {
+            return c.json({ ...claimed, key: artifactKey(claimed.id) }, 200);
+        }
+        if (!claimed)
+            await saveArtifact(artifact);
         void reviewPr(ref, {
             force: true,
             withSource,
@@ -438,13 +462,32 @@ export async function buildApp(opts) {
         try {
             const diff = await fetchPrDiff(ref);
             const result = refreshArtifact(artifact, pr, diff);
-            const saved = await updateArtifactByKey(c.req.param("key"), () => result.artifact);
+            // `result` was built from a snapshot taken before the PR read and the
+            // diff fetch, so it is written back only onto a row that is still the one
+            // it describes. The guard above asked the same question minutes ago; a
+            // settle, a send or a run that started since would be undone by writing
+            // this over them, and the ledger is the poll's in either case.
+            // Taken over, in any of the three ways that matter: a decision was made,
+            // a run owns the row now, or it simply is not the row this refresh was
+            // computed from any more. The last test is what catches a run that both
+            // started *and* finished inside this handler's own fetches — it leaves
+            // `ready`, which neither of the other two tests would refuse, and writing
+            // the pre-fetch snapshot over it would drop a whole finished draft.
+            // `updatedAt` is the version: every write through the store bumps it.
+            const taken = (a) => userOwnsStatus(a) || a.status === "running" || a.updatedAt !== artifact.updatedAt;
+            // Read inside the mutation rather than from its result: the store stamps
+            // `updatedAt` on the way out, so the saved row always looks "moved".
+            let applied = false;
+            const saved = await updateArtifactByKey(c.req.param("key"), (current) => {
+                applied = !taken(current);
+                return applied ? { ...result.artifact, notified: current.notified } : current;
+            });
             return c.json({
                 stale: true,
-                changed: result.changed,
+                changed: applied && result.changed,
                 prState: pr.state,
-                moved: result.moved,
-                drifted: result.drifted,
+                moved: applied ? result.moved : 0,
+                drifted: applied ? result.drifted : 0,
                 artifact: saved,
             });
         }

package/package.json

@@ -1,8 +1,20 @@
 {
   "name": "@fullstackhouse/cerber",
-  "version": "0.29.1",
+  "version": "0.31.0",
   "description": "AI code-review cockpit: Claude reviews your PRs into local artifacts; nothing reaches GitHub until you say so.",
   "license": "MIT",
+  "keywords": [
+    "code-review",
+    "pull-request",
+    "ai",
+    "claude",
+    "claude-code",
+    "github",
+    "cli",
+    "local-first",
+    "developer-tools",
+    "human-in-the-loop"
+  ],
   "author": "Full Stack House (https://fullstack.house)",
   "repository": "github:fullstackhouse/cerber",
   "type": "module",