@fullstackhouse/cerber 0.23.0 → 0.24.0

package/README.md

@@ -41,9 +41,9 @@ npx @fullstackhouse/cerber serve        # → http://127.0.0.1:4820
 
 `serve` does the whole loop by default: discover → draft → wait for you.
 Sending stays a human click. Tame it with `--no-auto-review` (list awaiting
-PRs, review on click) or `--no-poll` (no GitHub polling at all) — or flip the
-same two switches in the cockpit's Settings, which persist in
-`~/.cerber/config.json` and apply on the next poll. The queue only lists what
+PRs, review on click) or `--no-poll` (no GitHub polling at all) — or flip those
+switches in the cockpit's Settings, which persist in `~/.cerber/config.json`
+and apply on the next poll. The queue only lists what
 still wants you: anything you have settled moves to the filed tabs right of
 the thin rule in the filter row — reviews you sent, ones you marked reviewed
 or skipped, merged and closed PRs — each tab appearing only while it holds
@@ -88,15 +88,28 @@ who did is the one mistake worth designing against.
 
 ### It taps you on the shoulder
 
-The cockpit is a background tab most of the day, so it tells you when the queue
-grows: a desktop notification naming the PR that arrived — click it to open the
-review — folded into one popup when several land at once. It stays quiet while
-you're looking straight at cerber, and no browser announces the same PR twice.
-Only the browser can grant this, and only off a click, so the bell in the top
-bar is one: click it to be asked, click it again to stop. Both the switch and
-the record of what has been announced are per-browser, kept in that browser
-rather than in `~/.cerber/config.json` — the permission they gate is the
-browser's, so a second browser starts its own record.
+When a PR lands in the queue you get a desktop notification naming it, folded
+into one popup when several arrive at once. The tap comes from the poll that
+found the PR, so it reaches you with the cockpit closed, in another Space, or
+after a browser restart — `cerber serve` is the only thing that has to be
+running. It goes to whatever this machine already has (Notification Centre on
+macOS, `notify-send` on Linux) and stays quiet where there is neither. Off with
+`daemon.notify` in `~/.cerber/config.json`, or the checkbox in Settings.
+
+The cockpit has a bell of its own, and it is the better one where it can ring:
+its notification **opens that review when you click it**. But it is a page
+notification — it needs a tab that is open, alive and permitted, which is
+exactly what you don't have on the afternoons this feature is for. So it stands
+down while the machine's own tap is on, rather than making one PR two popups,
+and the bell in the top bar says so. Untick the machine one and this browser
+takes over: click the bell, grant the permission, and click it again to stop.
+The switch and the record of what has been announced are per-browser — the
+permission they gate is the browser's, so a second browser starts its own
+record — and it stays quiet while you're looking straight at cerber.
+
+A cockpit served from somewhere else (`cerber serve -H 0.0.0.0 --token` on a
+VPS) keeps its bell either way: the machine's tap would land on the VPS, where
+nobody is looking.
 
 The tab itself says it too, without asking anyone: while the inbox holds
 anything, the favicon wears a red dot, and it goes away when the last review is

package/dist/cli/index.js

@@ -313,6 +313,7 @@ program
     .option("-t, --token <token>", "require this token on every request (env: CERBER_TOKEN)")
     .option("--no-poll", "don't poll GitHub for PRs awaiting your review (also disables auto-review)")
     .option("--no-auto-review", "list awaiting PRs but don't review them until you click review")
+    .option("--no-notify", "don't notify this machine when a PR lands in the queue")
     .option("-d, --daemon", "(deprecated no-op — polling and auto-review are now the default)")
     .option("-i, --interval <minutes>", "poll interval (default: config daemon.intervalMinutes, 5)")
     .option("-R, --repo <owner/repo>", "repo(s) to watch (repeatable; default: config daemon.repos, all)", collect, [])
@@ -361,6 +362,7 @@ program
             withSource: opts.source,
             trust: opts.trust ? undefined : false,
             autoReview: opts.autoReview,
+            notify: opts.notify,
             autoSend: opts.autoSend ? "on" : "shadow",
             autoSendThreshold: threshold,
         })

package/dist/core/config.js

@@ -22,6 +22,12 @@ export const DaemonConfigSchema = z.object({
     poll: z.boolean().default(true),
     /** Draft an AI review for whatever lands in the queue. Never sends. */
     autoReview: z.boolean().default(true),
+    /**
+     * Tap this machine's notification centre when a PR lands in the queue. The
+     * cockpit's bell needs a tab open and permitted; this one only needs `serve`
+     * running, which is the point of it.
+     */
+    notify: z.boolean().default(true),
     intervalMinutes: z.number().int().positive().default(5),
     parallel: z.number().int().positive().default(3),
     /** Repos to watch (owner/repo). Empty = everything your gh account can see. */

package/dist/core/notify.js

@@ -0,0 +1,105 @@
+// The machine's own shoulder-tap, for the hours the cockpit isn't open.
+//
+// The cockpit has a bell of its own (`web/src/notify.ts`), and it is the better
+// one when it can ring: it names the PR and opens that review when you click
+// it. But it is a page notification, so it needs a tab that is open, alive and
+// permitted — which is exactly what you don't have while you're in an editor
+// all afternoon. This half rides the poll that discovers the PR instead, so the
+// tap survives a closed cockpit, a denied permission and a browser restart.
+//
+// Everything here shells out to whatever the OS already has. No dependency, no
+// daemon of its own, and a machine with no notifier is a machine cerber stays
+// quiet on rather than one it fails on.
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+/**
+ * How long a notifier gets before the poll stops waiting for it.
+ *
+ * A notification is instant or it is broken, and the thing on the other end of
+ * this is somebody else's daemon: a wedged Notification Centre or a DBus that
+ * never answers would otherwise hang `execFile` forever. The poll awaits this
+ * call, and the daemon refuses to start a poll while one is running — so an
+ * unbounded wait here doesn't cost one notification, it stops cerber
+ * discovering PRs at all. Timing out is caught like any other failure.
+ */
+export const NOTIFY_TIMEOUT_MS = 5_000;
+const slug = (a) => `${a.repo}#${a.number}`;
+/**
+ * One popup for one poll's arrivals — a batch is one interruption, not five.
+ * Deliberately the same shape and wording the cockpit's bell uses, so the two
+ * channels never read as two different pieces of news about one PR.
+ */
+export function notice(arrived) {
+    if (arrived.length === 0)
+        return null;
+    if (arrived.length === 1) {
+        const a = arrived[0];
+        return { title: `${slug(a)} awaits your review`, body: `${a.title} — ${a.author}` };
+    }
+    const named = arrived.slice(0, 3).map(slug);
+    const rest = arrived.length - named.length;
+    return {
+        title: `${arrived.length} PRs await your review`,
+        body: rest > 0 ? `${named.join(", ")} and ${rest} more` : named.join(", "),
+    };
+}
+/**
+ * A PR title, as an AppleScript string literal.
+ *
+ * osascript takes a script, not an argument list, so the title has to go into
+ * the source — and a PR title is text somebody else wrote. Escaping the two
+ * characters a literal cannot hold, a backslash and a quote, is what stops a
+ * title from closing the string and being read as script. Control characters
+ * can't appear in a literal at all, so they collapse to a space.
+ */
+export function appleScriptLiteral(value) {
+    const flat = value.replace(/[\u0000-\u001f\u007f]+/g, " ");
+    return `"${flat.replace(/[\\"]/g, (c) => `\\${c}`)}"`;
+}
+/**
+ * The command that taps this machine's notification centre, or null where there
+ * is nothing to tap. macOS and the freedesktop notifiers cover what cerber runs
+ * on; anywhere else it stays quiet rather than pretending.
+ */
+export function notifyCommand(n, platform = process.platform) {
+    if (platform === "darwin") {
+        return {
+            file: "osascript",
+            args: [
+                "-e",
+                `display notification ${appleScriptLiteral(n.body)} with title ${appleScriptLiteral(n.title)}`,
+            ],
+        };
+    }
+    if (platform === "linux") {
+        // `--` first, because notify-send parses options before positionals. The
+        // PR's own title reaches this as the notice *body* (`notice()` builds the
+        // summary itself), so the body is the argument carrying somebody else's
+        // text — a PR titled "--help me" would be read as a flag and cost the
+        // notification. The marker ends option parsing ahead of both arguments, so
+        // neither the summary nor the body can be read as anything but text.
+        return { file: "notify-send", args: ["--app-name=cerber", "--", n.title, n.body] };
+    }
+    return null;
+}
+/**
+ * Show it, and say whether it was shown. False is an ordinary answer here —
+ * an unsupported platform, no `notify-send` installed, a headless box, a
+ * notifier that took too long — and the caller reports it once rather than
+ * every poll. Never throws and never hangs: a notification is the least
+ * important thing a poll does, so it is also the last thing allowed to stop
+ * one.
+ */
+export async function notify(n) {
+    const cmd = notifyCommand(n);
+    if (!cmd)
+        return false;
+    try {
+        await execFileAsync(cmd.file, cmd.args, { timeout: NOTIFY_TIMEOUT_MS });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/server/daemon.js

@@ -2,6 +2,7 @@ import { SCHEMA_VERSION, artifactId, artifactKey } from "../core/artifact.js";
 import { evaluateAutoSend } from "../core/autosend.js";
 import { loadConfig } from "../core/config.js";
 import { classifyReply, currentLogin, fetchConversation, fetchOwnReview, fetchPrInfo, fetchReviewRequests, lastWordOfYours, searchAwaitingMe, stillRequested, submitReview, } from "../core/gh.js";
+import { notice, notify } from "../core/notify.js";
 import { buildReviewPayload, computeCalibration } from "../core/send.js";
 import { appendAutoSendLog, deleteArtifact, listArtifacts, loadArtifact, saveArtifact, updateArtifactByKey, } from "../core/state.js";
 import { ReviewInProgressError } from "../runner/inflight.js";
@@ -140,6 +141,9 @@ export function startDaemon(opts) {
         repos: opts.repos,
         intervalMs: opts.intervalMs,
         pollEnabled: true,
+        // Claims nothing until a poll has read the config, so the cockpit's bell
+        // keeps its own counsel for the few seconds that takes.
+        notify: false,
         autoReview: opts.autoReview,
         trustedRuns: false,
         polls: 0,
@@ -178,7 +182,7 @@ export function startDaemon(opts) {
      * search results lag GitHub by minutes and never override them.
      */
     async function syncQueue(refs) {
-        let discovered = 0;
+        const discovered = [];
         for (const ref of refs) {
             const existing = await loadArtifact(artifactId(ref));
             if (existing) {
@@ -195,7 +199,7 @@ export function startDaemon(opts) {
                 continue;
             }
             await saveArtifact(stubArtifact(ref));
-            discovered++;
+            discovered.push(ref);
         }
         // Asked once per pass, and only if a row actually reaches the check that
         // needs it. Undefined is "not asked yet"; null is "gh could not say", which
@@ -333,6 +337,41 @@ export function startDaemon(opts) {
         }
         return { discovered };
     }
+    /** Said once, not every poll: a machine with no notifier will never grow one. */
+    let notifierMissing = false;
+    /**
+     * What the last attempt to tap this machine actually did, or null before one
+     * has been made.
+     *
+     * `status.notify` is a promise to the cockpit — it stands its own bell down
+     * on the strength of it — so it has to mean "this machine gets told", not
+     * "this machine was asked to tell". A box with no `notify-send` would
+     * otherwise go on claiming the job while the browser politely declined it,
+     * and one PR would be announced by nobody at all. Untried counts as working:
+     * the alternative is both bells ringing everywhere until the first PR lands.
+     */
+    let notifierWorks = null;
+    /**
+     * Tap this machine when a PR lands in the queue.
+     *
+     * 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.
+     */
+    async function announce(arrivals) {
+        const n = notice(arrivals);
+        if (!n)
+            return;
+        notifierWorks = await notify(n);
+        if (notifierWorks)
+            return;
+        if (notifierMissing)
+            return;
+        notifierMissing = true;
+        log("no desktop notifier here — arrivals will only show in the cockpit");
+    }
     /**
      * Whose move it is on each awaiting PR, one conversation read apiece.
      *
@@ -410,6 +449,14 @@ export function startDaemon(opts) {
             const knobs = config.daemon;
             const autoReview = opts.autoReview && knobs.autoReview;
             status.pollEnabled = knobs.poll;
+            // What the cockpit's bell defers to: a loop that isn't polling announces
+            // nothing, whatever the notify toggle says.
+            const notifyOn = opts.notify && knobs.notify;
+            // Only true while all three hold, and the third is only knowable by
+            // having tried: a notifier that isn't there is not a bell the cockpit
+            // should be standing down for.
+            const announcing = () => knobs.poll && notifyOn && notifierWorks !== false;
+            status.notify = announcing();
             status.autoReview = autoReview;
             // Recomputed too, so a trust rule added mid-run shows up in the strip.
             status.trustedRuns = autoReview && opts.trust !== false && config.trust.length > 0;
@@ -428,6 +475,16 @@ 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 =
@@ -435,7 +492,7 @@ export function startDaemon(opts) {
                         `${failed > 0 ? `, ${failed} failed` : ""}`;
             }
             else {
-                status.lastSummary = `${refs.length} awaiting${discovered > 0 ? `, ${discovered} new` : ""} (auto-review off)`;
+                status.lastSummary = `${refs.length} awaiting${discovered.length > 0 ? `, ${discovered.length} new` : ""} (auto-review off)`;
             }
             log(status.lastSummary);
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fullstackhouse/cerber",
-  "version": "0.23.0",
+  "version": "0.24.0",
   "description": "AI code-review cockpit: Claude reviews your PRs into local artifacts; nothing reaches GitHub until you say so.",
   "license": "MIT",
   "author": "Full Stack House (https://fullstack.house)",