@armanckeser/downstream 0.0.0-stage → 0.1.0

package/dist/server/publish.js

@@ -0,0 +1,136 @@
+// Turning the review you and the agent arrived at into what the PR author sees.
+// The conversation stays private; only threads marked to go out are sent, in
+// the words drafted for the author, after the user presses Send.
+import { severityLabel } from "../domain/model.js";
+import { git } from "./analyze/git.js";
+import { gh } from "./gh.js";
+/** Which threads go out by default: open findings. Anything else only when someone marks it. */
+export function goesOut(n) {
+    if (n.outgoing)
+        return n.outgoing.include;
+    return n.kind === "finding" && n.status === "open";
+}
+/** The comment as the PR author reads it. Written in the agent's draft if there is one. */
+export function commentBody(n) {
+    if (n.outgoing?.body.trim())
+        return n.outgoing.body.trim();
+    const parts = [];
+    const label = n.kind === "finding" && n.severity ? `**${capitalize(severityLabel[n.severity])}:** ` : "";
+    parts.push(`${label}${n.title}`);
+    if (n.body)
+        parts.push(n.body);
+    if (n.fix)
+        parts.push(`**Fix:** ${n.fix}`);
+    if (n.suggestion && n.lines && n.suggestion.lines.start === n.lines.start && n.suggestion.lines.end === n.lines.end) {
+        parts.push("```suggestion\n" + n.suggestion.code.replace(/\n$/, "") + "\n```");
+    }
+    else if (n.suggestion) {
+        parts.push("```\n" + n.suggestion.code.replace(/\n$/, "") + "\n```");
+    }
+    if (n.impact)
+        parts.push(`**If we skip it:** ${n.impact}`);
+    return parts.join("\n\n");
+}
+const capitalize = (s) => s[0].toUpperCase() + s.slice(1);
+function diffLines(root, review, path) {
+    const right = new Set();
+    const left = new Set();
+    if (!review.baseSha)
+        return { right, left };
+    const range = review.head === "WORKTREE" ? [review.baseSha] : [review.baseSha, review.head];
+    let patch = "";
+    try {
+        patch = git(root, ["diff", "-U3", ...range, "--", path]);
+    }
+    catch {
+        return { right, left };
+    }
+    for (const m of patch.matchAll(/^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/gm)) {
+        const [os, ol, ns, nl] = [Number(m[1]), m[2] === undefined ? 1 : Number(m[2]), Number(m[3]), m[4] === undefined ? 1 : Number(m[4])];
+        for (let i = 0; i < nl; i++)
+            right.add(ns + i);
+        for (let i = 0; i < ol; i++)
+            left.add(os + i);
+    }
+    return { right, left };
+}
+export function draft(root, state, overrides = {}) {
+    const { review } = state;
+    const cache = new Map();
+    const comments = [];
+    for (const n of [...state.notes].sort((a, b) => a.number - b.number)) {
+        if (!goesOut(n) || !n.file)
+            continue;
+        const line = n.lines?.end ?? state.symbols.find((s) => s.id === n.symbolId)?.range?.start ?? null;
+        if (line == null)
+            continue;
+        const side = n.side === "old" ? "LEFT" : "RIGHT";
+        if (!cache.has(n.file))
+            cache.set(n.file, diffLines(root, review, n.file));
+        const lines = cache.get(n.file);
+        const pool = side === "RIGHT" ? lines.right : lines.left;
+        const startLine = n.lines && n.lines.start !== n.lines.end ? n.lines.start : null;
+        const inline = review.mode === "diff" && pool.has(line) && (startLine === null || pool.has(startLine));
+        comments.push({ noteId: n.id, number: n.number, path: n.file, line, startLine, side, body: commentBody(n), inline });
+    }
+    const verdict = review.verdicts.find((v) => v.by === "user") ?? review.verdicts.find((v) => v.by === "agent");
+    const event = overrides.event ?? (verdict?.value === "approve" ? "APPROVE" : verdict?.value === "changes" ? "REQUEST_CHANGES" : "COMMENT");
+    let body = (overrides.body ?? review.outgoingBody).trim();
+    if (!body)
+        body = defaultBody(state, comments);
+    const outside = comments.filter((c) => !c.inline);
+    if (outside.length) {
+        body += "\n\n" + outside.map((c) => `**${c.path}:${c.startLine ? `${c.startLine}-` : ""}${c.line}**\n\n${c.body}`).join("\n\n---\n\n");
+    }
+    const repo = review.pr ? review.repo : null;
+    const markdown = [body, ...comments.filter((c) => c.inline).map((c) => `**${c.path}:${c.startLine ? `${c.startLine}-` : ""}${c.line}**\n\n${c.body}`)].join("\n\n---\n\n");
+    return { event, body, comments, target: review.pr ? { pr: review.pr, repo } : null, markdown };
+}
+function defaultBody(state, comments) {
+    const findings = state.notes.filter((n) => goesOut(n) && n.kind === "finding");
+    const must = findings.filter((n) => n.severity === "blocker").map((n) => n.title.replace(/\.$/, "").toLowerCase());
+    const lines = [];
+    const first = state.review.summary.split(/\n\s*\n/)[0]?.trim();
+    if (first)
+        lines.push(first);
+    if (!comments.length)
+        lines.push("Looks good. Ship.");
+    // No "#n" here: on GitHub that links to an issue. Name the findings instead.
+    else if (must.length)
+        lines.push(`Before merging: ${must.join("; ")}. The rest can follow.`);
+    else
+        lines.push(`${comments.length} comment${comments.length === 1 ? "" : "s"} inline, none blocking.`);
+    return lines.join("\n\n");
+}
+/** The PR moved on after the review was opened: its comments would sit on code that has been replaced. */
+export class HeadMoved extends Error {
+    reviewed;
+    current;
+    constructor(reviewed, current, pr) {
+        super(`#${pr} changed since you opened this review (${reviewed.slice(0, 7)} → ${current.slice(0, 7)}), so these comments would land on replaced code. Re-open it with \`downstream open --pr ${pr}\` to review what's there now, or send anyway.`);
+        this.reviewed = reviewed;
+        this.current = current;
+    }
+}
+/** Sends the review. Refuses when the PR's head moved since it was opened, unless `force`. */
+export function publish(state, d, opts = {}) {
+    const { review } = state;
+    if (!review.pr || !d.target?.repo)
+        throw new Error("Only pull request reviews can be sent. Open with `downstream open --pr <n>`, or copy the markdown.");
+    if (!opts.force) {
+        const current = gh(["pr", "view", String(review.pr), "--repo", d.target.repo, "--json", "headRefOid", "--jq", ".headRefOid"], { account: review.account }).trim();
+        if (current && current !== review.head)
+            throw new HeadMoved(review.head, current, review.pr);
+    }
+    const payload = {
+        commit_id: review.head,
+        event: d.event,
+        body: d.body,
+        comments: d.comments
+            .filter((c) => c.inline)
+            .map((c) => ({ path: c.path, line: c.line, side: c.side, ...(c.startLine ? { start_line: c.startLine, start_side: c.side } : {}), body: c.body })),
+    };
+    const out = gh(["api", "-X", "POST", `repos/${d.target.repo}/pulls/${review.pr}/reviews`, "--input", "-"], { account: review.account, input: JSON.stringify(payload) });
+    const res = JSON.parse(out);
+    return { url: res.html_url, comments: payload.comments.length };
+}

package/dist/server/repos.js

@@ -0,0 +1,164 @@
+// The repositories one Downstream server serves. Each keeps its own review
+// database in `<repo>/.downstream/`; the server finds a repo's clone from its
+// GitHub name, and clones it when you have none.
+import { createHash } from "node:crypto";
+import { EventEmitter } from "node:events";
+import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+import { Store } from "./store.js";
+import { Workspace } from "./workspace.js";
+import { ActionError } from "./actions.js";
+import { downstreamHome } from "./home-store.js";
+import { ghAsync } from "./gh.js";
+export class RepoContext {
+    store;
+    workspaces = new Map();
+    id;
+    root;
+    nameWithOwner;
+    constructor(id, root, nameWithOwner) {
+        this.id = id;
+        this.root = root;
+        this.nameWithOwner = nameWithOwner;
+        const dir = path.join(root, ".downstream");
+        mkdirSync(dir, { recursive: true });
+        excludeFromGit(root);
+        this.store = new Store(path.join(dir, "review.db"));
+    }
+    workspace(reviewId) {
+        let ws = this.workspaces.get(reviewId);
+        if (!ws) {
+            const review = this.store.review(reviewId);
+            if (!review)
+                throw new ActionError(`No review ${reviewId}`, 404);
+            ws = new Workspace(this.store.reviewRoot(reviewId) || this.root, review);
+            this.workspaces.set(reviewId, ws);
+        }
+        return ws;
+    }
+    dropWorkspace(reviewId) {
+        this.workspaces.delete(reviewId);
+    }
+}
+/** Short, readable and stable: `downstream-1a2b3c`. The URL of a repo's reviews. */
+export function repoId(root) {
+    const slug = path.basename(root).toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "") || "repo";
+    return `${slug}-${createHash("sha1").update(path.resolve(root)).digest("hex").slice(0, 6)}`;
+}
+/** `owner/name` from the origin remote, read from .git/config so a scan of many repos runs no git processes. */
+export function originOf(root) {
+    const config = path.join(root, ".git", "config");
+    if (!existsSync(config))
+        return null;
+    const text = readFileSync(config, "utf8");
+    const origin = text.match(/\[remote "origin"\][^[]*?url\s*=\s*(\S+)/);
+    const m = origin?.[1]?.match(/github\.com[:/]([^/\s]+)\/([^/\s]+?)(?:\.git)?\/?$/);
+    return m ? `${m[1]}/${m[2]}` : null;
+}
+const SKIP = new Set(["node_modules", "Library", "Applications", "dist", "build", "vendor", "target"]);
+const SCAN_DEPTH = 4;
+const RESCAN_AFTER_MS = 5 * 60_000;
+export class RepoRegistry {
+    loaded = new Map();
+    scannedAt = 0;
+    /** Every repo's review events, as ("event", repo, reviewId, event): the home page and agent sessions follow them. */
+    bus = new EventEmitter();
+    home;
+    constructor(home) {
+        this.home = home;
+        this.bus.setMaxListeners(100);
+    }
+    /** A repository the CLI is running in, or one the home page needs. Idempotent. */
+    register(root) {
+        const abs = path.resolve(root);
+        const id = repoId(abs);
+        const existing = this.loaded.get(id);
+        if (existing)
+            return existing;
+        const ctx = new RepoContext(id, abs, originOf(abs));
+        this.home.putRepo({ id, root: abs, nameWithOwner: ctx.nameWithOwner });
+        this.loaded.set(id, ctx);
+        ctx.store.bus.on("event", (reviewId, e) => this.bus.emit("event", ctx, reviewId, e));
+        return ctx;
+    }
+    get(id) {
+        const loaded = this.loaded.get(id);
+        if (loaded)
+            return loaded;
+        const row = this.home.repos().find((r) => r.id === id);
+        return row && existsSync(row.root) ? this.register(row.root) : null;
+    }
+    /** Every repository with reviews, for the home page. */
+    withReviews() {
+        return this.home
+            .repos()
+            .filter((r) => existsSync(path.join(r.root, ".downstream", "review.db")))
+            .map((r) => this.register(r.root));
+    }
+    /** Where `owner/name` is cloned on this machine, looking in the usual places once in a while. */
+    find(nameWithOwner) {
+        const known = this.home.rootFor(nameWithOwner);
+        if (known && existsSync(known))
+            return known;
+        if (Date.now() - this.scannedAt < RESCAN_AFTER_MS)
+            return null;
+        this.scannedAt = Date.now();
+        for (const { dir, depth } of searchRoots())
+            scan(dir, depth, (root, origin) => this.home.putRepo({ id: repoId(root), root, nameWithOwner: origin }));
+        const found = this.home.rootFor(nameWithOwner);
+        return found && existsSync(found) ? found : null;
+    }
+    /** A partial clone (no file contents until needed) under Downstream's home, for repos you don't have. */
+    async clone(nameWithOwner, account) {
+        const dest = path.join(downstreamHome(), "repos", ...nameWithOwner.split("/"));
+        if (!existsSync(path.join(dest, ".git"))) {
+            mkdirSync(path.dirname(dest), { recursive: true });
+            await ghAsync(["repo", "clone", nameWithOwner, dest, "--", "--filter=blob:none"], { account });
+        }
+        this.register(dest);
+        return dest;
+    }
+}
+/** Code folders are searched deep; the home directory itself only one level, for `~/myrepo`. */
+function searchRoots() {
+    const env = process.env.DOWNSTREAM_REPO_ROOTS;
+    if (env)
+        return env.split(path.delimiter).filter(Boolean).map((dir) => ({ dir, depth: SCAN_DEPTH }));
+    const home = homedir();
+    const deep = ["projects", "code", "src", "dev"].map((d) => ({ dir: path.join(home, d), depth: SCAN_DEPTH }));
+    return [...deep, { dir: home, depth: 1 }].filter((r) => existsSync(r.dir));
+}
+function scan(dir, depth, found) {
+    let entries;
+    try {
+        entries = readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    if (entries.some((e) => e.name === ".git" && e.isDirectory())) {
+        const origin = originOf(dir);
+        if (origin)
+            found(dir, origin);
+        return;
+    }
+    if (depth === 0)
+        return;
+    for (const e of entries) {
+        if (!e.isDirectory() || e.name.startsWith(".") || SKIP.has(e.name))
+            continue;
+        scan(path.join(dir, e.name), depth - 1, found);
+    }
+}
+function excludeFromGit(root) {
+    const exclude = path.join(root, ".git", "info", "exclude");
+    try {
+        const text = existsSync(exclude) ? readFileSync(exclude, "utf8") : "";
+        if (!text.split("\n").includes(".downstream/"))
+            appendFileSync(exclude, `${text.endsWith("\n") || !text ? "" : "\n"}.downstream/\n`);
+    }
+    catch {
+        /* worktrees keep info/ elsewhere; not worth failing over */
+    }
+}

package/dist/server/stale.js

@@ -0,0 +1,50 @@
+// Deciding a stale pull request: each decision does exactly what its label in
+// the sweep says, on GitHub and here, and nothing else.
+import { z } from "zod";
+import { staleChoices } from "../domain/inbox.js";
+import { ghAsync } from "./gh.js";
+export const StaleDecision = z.discriminatedUnion("kind", [
+    z.object({ kind: z.literal("remove-request") }),
+    z.object({ kind: z.literal("comment"), body: z.string().trim().min(1) }),
+    z.object({ kind: z.literal("close"), reason: z.string().trim().min(1) }),
+    z.object({ kind: z.literal("hide") }),
+]);
+/** The decision isn't one this PR offers (closing someone else's PR, removing a request nobody made). */
+export class NotOffered extends Error {
+}
+/** GitHub (through gh) said no; its first lines say why. */
+export class GitHubRefused extends Error {
+}
+async function write(args, account) {
+    try {
+        await ghAsync(args, { account });
+    }
+    catch (e) {
+        const err = e;
+        throw new GitHubRefused((err.stderr?.toString().trim() || err.message).split("\n").slice(0, 2).join(" "));
+    }
+}
+/**
+ * Carry out `decision` on `item` as `account`. GitHub first: if it refuses,
+ * nothing is hidden. Hiding comes after, so the PR's own update from the write
+ * is older than the hide and doesn't bring it straight back.
+ */
+export async function decide(account, item, decision, hide) {
+    const offered = staleChoices(item).some((c) => c.kind === decision.kind);
+    if (!offered)
+        throw new NotOffered(`#${item.lead.number} doesn't offer "${decision.kind}".`);
+    const { repo, number } = item.lead;
+    switch (decision.kind) {
+        case "remove-request":
+            await write(["api", "-X", "DELETE", `repos/${repo}/pulls/${number}/requested_reviewers`, "-f", `reviewers[]=${account}`], account);
+            return hide();
+        case "comment":
+            await write(["api", "-X", "POST", `repos/${repo}/issues/${number}/comments`, "-f", `body=${decision.body}`], account);
+            return hide();
+        case "close":
+            await write(["pr", "close", String(number), "--repo", repo, "--comment", decision.reason], account);
+            return;
+        case "hide":
+            return hide();
+    }
+}

package/dist/server/store.js

@@ -0,0 +1,269 @@
+// SQLite is the source of truth for a review. The browser and the agent both
+// write through actions (server/actions.ts); the agent may read with plain SQL
+// through a read-only connection (`downstream sql`), which cannot write.
+import { DatabaseSync } from "node:sqlite";
+import { EventEmitter } from "node:events";
+const SCHEMA = `
+CREATE TABLE IF NOT EXISTS meta (key TEXT PRIMARY KEY, value TEXT NOT NULL);
+CREATE TABLE IF NOT EXISTS reviews (id TEXT PRIMARY KEY, data TEXT NOT NULL, root TEXT NOT NULL, created_at TEXT NOT NULL);
+CREATE TABLE IF NOT EXISTS files (review_id TEXT NOT NULL, path TEXT NOT NULL, data TEXT NOT NULL, PRIMARY KEY (review_id, path));
+CREATE TABLE IF NOT EXISTS symbols (review_id TEXT NOT NULL, id TEXT NOT NULL, data TEXT NOT NULL, manual INTEGER NOT NULL DEFAULT 0, PRIMARY KEY (review_id, id));
+CREATE TABLE IF NOT EXISTS edges (review_id TEXT NOT NULL, id TEXT NOT NULL, data TEXT NOT NULL, manual INTEGER NOT NULL DEFAULT 0, PRIMARY KEY (review_id, id));
+CREATE TABLE IF NOT EXISTS steps (review_id TEXT NOT NULL, id TEXT NOT NULL, ord INTEGER NOT NULL, data TEXT NOT NULL, PRIMARY KEY (review_id, id));
+CREATE TABLE IF NOT EXISTS notes (review_id TEXT NOT NULL, id TEXT NOT NULL, data TEXT NOT NULL, created_at TEXT NOT NULL, PRIMARY KEY (review_id, id));
+CREATE TABLE IF NOT EXISTS replies (review_id TEXT NOT NULL, id TEXT NOT NULL, note_id TEXT NOT NULL, data TEXT NOT NULL, created_at TEXT NOT NULL, PRIMARY KEY (review_id, id));
+CREATE TABLE IF NOT EXISTS app_state (review_id TEXT NOT NULL, key TEXT NOT NULL, value TEXT NOT NULL, updated_at TEXT NOT NULL, PRIMARY KEY (review_id, key));
+CREATE TABLE IF NOT EXISTS events (id INTEGER PRIMARY KEY AUTOINCREMENT, review_id TEXT NOT NULL, type TEXT NOT NULL, actor TEXT NOT NULL, payload TEXT NOT NULL, at TEXT NOT NULL);
+
+-- Flat views for ad-hoc agent queries: downstream sql "select * from v_notes where status = 'open'"
+CREATE VIEW IF NOT EXISTS v_symbols AS SELECT review_id, id, json_extract(data,'$.name') AS name, json_extract(data,'$.kind') AS kind,
+  json_extract(data,'$.file') AS file, json_extract(data,'$.status') AS status, json_extract(data,'$.entry') AS entry,
+  json_extract(data,'$.range.start') AS start_line, json_extract(data,'$.range.end') AS end_line, json_extract(data,'$.summary') AS summary FROM symbols;
+CREATE VIEW IF NOT EXISTS v_edges AS SELECT review_id, id, json_extract(data,'$.from') AS from_id, json_extract(data,'$.to') AS to_id,
+  json_extract(data,'$.kind') AS kind, json_extract(data,'$.change') AS change, json_extract(data,'$.line') AS line FROM edges;
+CREATE VIEW IF NOT EXISTS v_notes AS SELECT review_id, id, json_extract(data,'$.kind') AS kind, json_extract(data,'$.severity') AS severity,
+  json_extract(data,'$.status') AS status, json_extract(data,'$.author') AS author, json_extract(data,'$.title') AS title,
+  json_extract(data,'$.symbolId') AS symbol_id, json_extract(data,'$.body') AS body, created_at FROM notes;
+CREATE VIEW IF NOT EXISTS v_replies AS SELECT review_id, id, note_id, json_extract(data,'$.author') AS author, json_extract(data,'$.body') AS body, created_at FROM replies;
+`;
+const NOTE_DEFAULTS = { number: 0, category: null, fix: "", impact: "", outgoing: null };
+export const now = () => new Date().toISOString();
+export const newId = (prefix) => `${prefix}_${Math.random().toString(36).slice(2, 8)}${Date.now().toString(36).slice(-3)}`;
+export class Store {
+    db;
+    bus = new EventEmitter();
+    waiters = 0;
+    lastAgentActivity = null;
+    constructor(file) {
+        this.db = new DatabaseSync(file);
+        this.db.exec("PRAGMA journal_mode = WAL; PRAGMA foreign_keys = ON;");
+        this.db.exec(SCHEMA);
+        this.bus.setMaxListeners(100);
+    }
+    // -- reviews --------------------------------------------------------------
+    currentReviewId() {
+        const row = this.db.prepare("SELECT value FROM meta WHERE key = 'current'").get();
+        return row?.value ?? null;
+    }
+    setCurrent(id) {
+        this.db.prepare("INSERT INTO meta (key, value) VALUES ('current', ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value").run(id);
+    }
+    listReviews() {
+        return this.db.prepare("SELECT data FROM reviews ORDER BY created_at DESC").all().map((r) => JSON.parse(r.data));
+    }
+    review(id) {
+        const row = this.db.prepare("SELECT data FROM reviews WHERE id = ?").get(id);
+        return row ? { outgoingBody: "", published: null, ...JSON.parse(row.data) } : null;
+    }
+    reviewRoot(id) {
+        const row = this.db.prepare("SELECT root FROM reviews WHERE id = ?").get(id);
+        return row?.root ?? null;
+    }
+    saveReview(review, root) {
+        const existing = this.reviewRoot(review.id);
+        this.db
+            .prepare("INSERT INTO reviews (id, data, root, created_at) VALUES (?, ?, ?, ?) ON CONFLICT(id) DO UPDATE SET data = excluded.data")
+            .run(review.id, JSON.stringify(review), root ?? existing ?? "", review.createdAt);
+    }
+    // -- analysis ---------------------------------------------------------------
+    /**
+     * Replace the analyzed part of a review, keeping what people wrote: symbol
+     * summaries and entry flags survive a re-analysis, as do manual symbols/edges.
+     */
+    replaceAnalysis(reviewId, files, symbols, edges) {
+        const prior = new Map(this.symbols(reviewId).map((s) => [s.id, s]));
+        this.tx(() => {
+            this.db.prepare("DELETE FROM files WHERE review_id = ?").run(reviewId);
+            this.db.prepare("DELETE FROM symbols WHERE review_id = ? AND manual = 0").run(reviewId);
+            this.db.prepare("DELETE FROM edges WHERE review_id = ? AND manual = 0").run(reviewId);
+            const insFile = this.db.prepare("INSERT INTO files (review_id, path, data) VALUES (?, ?, ?)");
+            for (const f of files)
+                insFile.run(reviewId, f.path, JSON.stringify(f));
+            const insSym = this.db.prepare("INSERT OR IGNORE INTO symbols (review_id, id, data, manual) VALUES (?, ?, ?, 0)");
+            for (const s of symbols) {
+                const before = prior.get(s.id);
+                if (before) {
+                    s.summary = before.summary ?? s.summary;
+                    if (before.entry !== s.entry && this.entryWasSetByHand(reviewId, s.id))
+                        s.entry = before.entry;
+                }
+                insSym.run(reviewId, s.id, JSON.stringify(s));
+            }
+            const insEdge = this.db.prepare("INSERT OR IGNORE INTO edges (review_id, id, data, manual) VALUES (?, ?, ?, 0)");
+            for (const e of edges)
+                insEdge.run(reviewId, e.id, JSON.stringify(e));
+        });
+    }
+    entryWasSetByHand(reviewId, symbolId) {
+        const row = this.db
+            .prepare("SELECT 1 FROM events WHERE review_id = ? AND type = 'symbol.annotated' AND json_extract(payload, '$.id') = ? AND json_extract(payload, '$.entry') IS NOT NULL LIMIT 1")
+            .get(reviewId, symbolId);
+        return !!row;
+    }
+    files(reviewId) {
+        return this.db.prepare("SELECT data FROM files WHERE review_id = ? ORDER BY path").all(reviewId).map((r) => JSON.parse(r.data));
+    }
+    symbols(reviewId) {
+        return this.db.prepare("SELECT data FROM symbols WHERE review_id = ?").all(reviewId).map((r) => JSON.parse(r.data));
+    }
+    symbol(reviewId, id) {
+        const row = this.db.prepare("SELECT data FROM symbols WHERE review_id = ? AND id = ?").get(reviewId, id);
+        return row ? JSON.parse(row.data) : null;
+    }
+    putSymbol(reviewId, s, manual = false) {
+        this.db
+            .prepare("INSERT INTO symbols (review_id, id, data, manual) VALUES (?, ?, ?, ?) ON CONFLICT(review_id, id) DO UPDATE SET data = excluded.data, manual = MAX(symbols.manual, excluded.manual)")
+            .run(reviewId, s.id, JSON.stringify(s), manual ? 1 : 0);
+    }
+    deleteSymbol(reviewId, id) {
+        this.db.prepare("DELETE FROM symbols WHERE review_id = ? AND id = ?").run(reviewId, id);
+        this.db.prepare("DELETE FROM edges WHERE review_id = ? AND (json_extract(data,'$.from') = ? OR json_extract(data,'$.to') = ?)").run(reviewId, id, id);
+    }
+    edges(reviewId) {
+        return this.db.prepare("SELECT data FROM edges WHERE review_id = ?").all(reviewId).map((r) => JSON.parse(r.data));
+    }
+    putEdge(reviewId, e, manual = false) {
+        this.db
+            .prepare("INSERT INTO edges (review_id, id, data, manual) VALUES (?, ?, ?, ?) ON CONFLICT(review_id, id) DO UPDATE SET data = excluded.data")
+            .run(reviewId, e.id, JSON.stringify(e), manual ? 1 : 0);
+    }
+    deleteEdge(reviewId, id) {
+        this.db.prepare("DELETE FROM edges WHERE review_id = ? AND id = ?").run(reviewId, id);
+    }
+    // -- walkthrough --------------------------------------------------------------
+    steps(reviewId) {
+        return this.db.prepare("SELECT data FROM steps WHERE review_id = ? ORDER BY ord").all(reviewId).map((r) => JSON.parse(r.data));
+    }
+    replaceSteps(reviewId, steps) {
+        this.tx(() => {
+            this.db.prepare("DELETE FROM steps WHERE review_id = ?").run(reviewId);
+            const ins = this.db.prepare("INSERT INTO steps (review_id, id, ord, data) VALUES (?, ?, ?, ?)");
+            for (const s of steps)
+                ins.run(reviewId, s.id, s.order, JSON.stringify(s));
+        });
+    }
+    // -- threads --------------------------------------------------------------------
+    notes(reviewId) {
+        const notes = this.db.prepare("SELECT data FROM notes WHERE review_id = ? ORDER BY created_at").all(reviewId).map((r) => JSON.parse(r.data));
+        const replies = this.db.prepare("SELECT data FROM replies WHERE review_id = ? ORDER BY created_at").all(reviewId).map((r) => JSON.parse(r.data));
+        const byNote = Map.groupBy(replies, (r) => r.noteId);
+        // Reviews from before numbering get numbers in creation order.
+        let next = Math.max(0, ...notes.map((n) => n.number ?? 0));
+        return notes.map((n) => ({ ...NOTE_DEFAULTS, ...n, number: n.number || ++next, replies: byNote.get(n.id) ?? [] }));
+    }
+    nextNoteNumber(reviewId) {
+        return Math.max(0, ...this.notes(reviewId).map((n) => n.number)) + 1;
+    }
+    note(reviewId, id) {
+        const row = this.db.prepare("SELECT data FROM notes WHERE review_id = ? AND id = ?").get(reviewId, id);
+        if (!row)
+            return null;
+        const note = { ...NOTE_DEFAULTS, ...JSON.parse(row.data) };
+        const replies = this.db.prepare("SELECT data FROM replies WHERE review_id = ? AND note_id = ? ORDER BY created_at").all(reviewId, id).map((r) => JSON.parse(r.data));
+        return { ...note, replies };
+    }
+    putNote(reviewId, note) {
+        const { replies: _replies, ...rest } = note;
+        this.db
+            .prepare("INSERT INTO notes (review_id, id, data, created_at) VALUES (?, ?, ?, ?) ON CONFLICT(review_id, id) DO UPDATE SET data = excluded.data")
+            .run(reviewId, note.id, JSON.stringify({ ...rest, replies: [] }), note.createdAt);
+    }
+    addReply(reviewId, reply) {
+        this.db.prepare("INSERT INTO replies (review_id, id, note_id, data, created_at) VALUES (?, ?, ?, ?, ?)").run(reviewId, reply.id, reply.noteId, JSON.stringify(reply), reply.createdAt);
+    }
+    // -- application state -------------------------------------------------------------
+    getAppState(reviewId, key) {
+        const row = this.db.prepare("SELECT value FROM app_state WHERE review_id = ? AND key = ?").get(reviewId, key);
+        return row ? JSON.parse(row.value) : null;
+    }
+    setAppState(reviewId, key, value) {
+        this.db
+            .prepare("INSERT INTO app_state (review_id, key, value, updated_at) VALUES (?, ?, ?, ?) ON CONFLICT(review_id, key) DO UPDATE SET value = excluded.value, updated_at = excluded.updated_at")
+            .run(reviewId, key, JSON.stringify(value), now());
+    }
+    // -- events --------------------------------------------------------------------------
+    emit(reviewId, type, actor, payload = {}) {
+        const at = now();
+        const res = this.db.prepare("INSERT INTO events (review_id, type, actor, payload, at) VALUES (?, ?, ?, ?, ?)").run(reviewId, type, actor, JSON.stringify(payload), at);
+        const event = { id: Number(res.lastInsertRowid), type, actor, payload, at };
+        if (actor === "agent")
+            this.touchAgent();
+        this.bus.emit("event", reviewId, event);
+        return event;
+    }
+    events(reviewId, after, actor) {
+        const rows = (actor
+            ? this.db.prepare("SELECT * FROM events WHERE review_id = ? AND id > ? AND actor = ? ORDER BY id").all(reviewId, after, actor)
+            : this.db.prepare("SELECT * FROM events WHERE review_id = ? AND id > ? ORDER BY id").all(reviewId, after));
+        return rows.map((r) => ({ id: r.id, type: r.type, actor: r.actor, payload: JSON.parse(r.payload), at: r.at }));
+    }
+    cursor(reviewId) {
+        const row = this.db.prepare("SELECT MAX(id) AS id FROM events WHERE review_id = ?").get(reviewId);
+        return row.id ?? 0;
+    }
+    // -- presence ----------------------------------------------------------------------------
+    touchAgent() {
+        this.lastAgentActivity = now();
+    }
+    waiterJoined() {
+        this.waiters++;
+        this.touchAgent();
+        this.bus.emit("presence");
+    }
+    waiterLeft() {
+        this.waiters = Math.max(0, this.waiters - 1);
+        this.touchAgent();
+        this.bus.emit("presence");
+    }
+    /** Record that the agent was handed these user events. Kept as an event so the browser hears it live and it survives restarts. */
+    markRead(reviewId, events) {
+        if (events.length === 0)
+            return;
+        const through = events.reduce((latest, e) => (e.at > latest ? e.at : latest), events[0].at);
+        this.emit(reviewId, "agent.read", "system", { through });
+        // A wait that returns at once never joined as a waiter, so nothing else marks the agent as here.
+        this.touchAgent();
+    }
+    readThrough(reviewId) {
+        const row = this.db
+            .prepare("SELECT json_extract(payload, '$.through') AS through FROM events WHERE review_id = ? AND type = 'agent.read' ORDER BY id DESC LIMIT 1")
+            .get(reviewId);
+        return row?.through ?? null;
+    }
+    presence() {
+        const recent = this.lastAgentActivity && Date.now() - Date.parse(this.lastAgentActivity) < 90_000;
+        return { agent: this.waiters > 0 ? "listening" : recent ? "working" : "away", lastAgentActivity: this.lastAgentActivity };
+    }
+    state(reviewId) {
+        const review = this.review(reviewId);
+        if (!review)
+            return null;
+        return {
+            review,
+            files: this.files(reviewId),
+            symbols: this.symbols(reviewId),
+            edges: this.edges(reviewId),
+            steps: this.steps(reviewId),
+            notes: this.notes(reviewId),
+            presence: this.presence(),
+            cursor: this.cursor(reviewId),
+            readThrough: this.readThrough(reviewId),
+            visited: this.getAppState(reviewId, "visited") ?? [],
+        };
+    }
+    tx(fn) {
+        this.db.exec("BEGIN");
+        try {
+            fn();
+            this.db.exec("COMMIT");
+        }
+        catch (e) {
+            this.db.exec("ROLLBACK");
+            throw e;
+        }
+    }
+}
+/** A connection that structurally cannot write. Backs `downstream sql`. */
+export function readOnly(file) {
+    return new DatabaseSync(file, { readOnly: true });
+}