bottleship 0.1.0-prototype.1 → 0.1.0-prototype.2

package/dist/src/provider.js

@@ -0,0 +1,81 @@
+// A provider is a directory of bash scripts that run boxes somewhere. Docker ships with bottleship;
+// for any other sandbox an agent writes the same scripts into ~/.bottleship/providers/<name>/.
+//
+//   create <id> <dockerfile> <image>   build the box from the Dockerfile (cache it as <image>), start it, exit once it runs commands
+//   exec <id> <script>                 run `bash -c <script>` in the box as its user, stdin passed through
+//   status <id>                        print running or gone
+//   destroy <id>                       remove the box and everything in it
+//   url <id> <port>                    (optional) print a URL on this machine for a port the box exposes
+//   list                               (optional) print the boxes bottleship made, one per line: <id> [<created, ISO 8601>]
+import { existsSync, mkdtempSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { HOME, ROOT } from "./paths.js";
+import { BsError } from "./config.js";
+import { run, spawnStream } from "./util.js";
+const SCRIPTS = ["create", "exec", "status", "destroy"];
+const dirs = () => [join(HOME, "providers"), join(ROOT, "presets/providers")];
+// user providers first, so a user can replace the builtin docker scripts
+export function providerNames() {
+    const names = dirs().flatMap((d) => (existsSync(d) ? readdirSync(d).filter((n) => existsSync(join(d, n, "create"))) : []));
+    return [...new Set(names)];
+}
+export function getProvider(name) {
+    const dir = dirs().map((d) => join(d, name)).find((d) => existsSync(d));
+    if (!dir)
+        throw new BsError("unknown_provider", `no provider "${name}"`, `known: ${providerNames().join(", ")}. A provider is a directory of scripts in ${join(HOME, "providers")}, see "Providers" in ${join(ROOT, "README.md")}`);
+    const missing = SCRIPTS.filter((s) => !existsSync(join(dir, s)));
+    if (missing.length)
+        throw new BsError("bad_provider", `provider "${name}" (${dir}) has no ${missing.join(", ")} script`, `add them, see "Providers" in ${join(ROOT, "README.md")}`);
+    const script = (s) => join(dir, s);
+    const call = (s, args, stdin) => run("bash", [script(s), ...args], { stdin, check: false });
+    const failed = (s, r) => new Error(`${name}/${s} exited ${r.code}: ${(r.stderr || r.stdout).trim().slice(-2000)}`);
+    return {
+        name,
+        async create(id, dockerfile, image) {
+            // the Dockerfile goes in a file, since providers build it with their own tools
+            const tmp = mkdtempSync(join(tmpdir(), "bs-df-"));
+            try {
+                writeFileSync(join(tmp, "Dockerfile"), dockerfile);
+                const r = await call("create", [id, join(tmp, "Dockerfile"), image]);
+                if (r.code !== 0)
+                    throw failed("create", r);
+            }
+            finally {
+                rmSync(tmp, { recursive: true, force: true });
+            }
+        },
+        exec: (id, s, stdin) => call("exec", [id, s], stdin),
+        stream: (id, s) => spawnStream("bash", [script("exec"), id, s]),
+        async status(id) {
+            const r = await call("status", [id]);
+            if (r.code !== 0)
+                throw failed("status", r);
+            return r.stdout.trim() === "running" ? "running" : "gone";
+        },
+        async destroy(id) {
+            const r = await call("destroy", [id]);
+            if (r.code !== 0)
+                throw failed("destroy", r);
+        },
+        ...(existsSync(script("url")) && {
+            async url(id, port) {
+                const r = await call("url", [id, String(port)]);
+                if (r.code !== 0)
+                    throw failed("url", r);
+                return r.stdout.trim();
+            },
+        }),
+        ...(existsSync(script("list")) && {
+            async list() {
+                const r = await call("list", []);
+                if (r.code !== 0)
+                    throw failed("list", r);
+                return r.stdout.split("\n").filter(Boolean).map((l) => {
+                    const [box, created] = l.trim().split(/\s+/);
+                    return { box, ...(created && { created }) };
+                });
+            },
+        }),
+    };
+}

package/dist/src/repo.d.ts

@@ -0,0 +1,21 @@
+export interface Repo {
+    url: string;
+    label: string;
+}
+export interface RepoEnv {
+    dockerfile?: string;
+    ports: number[];
+}
+export declare const git: (cwd: string, ...args: string[]) => string;
+export declare function toRepo(s: string): Repo;
+export declare function checkout(cwd: string): {
+    root: string;
+    origin?: Repo;
+    remote?: string;
+} | undefined;
+export declare function dotenvFiles(root: string): Record<string, string>;
+export declare function readRepoEnv(root: string): RepoEnv | undefined;
+export declare function readEnvFiles(root: string): Record<string, string> | undefined;
+export declare function parseRepoEnv(dockerfile: string | undefined): RepoEnv;
+export declare function workingTree(root: string): Promise<Buffer>;
+export declare function tarFiles(root: string, files: string[]): Promise<Buffer>;

package/dist/src/repo.js

@@ -0,0 +1,75 @@
+// The user's local checkout: its origin, its .env files, its working tree, and its box environment in .bottleship/.
+import { execFileSync, spawn } from "node:child_process";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { BsError } from "./config.js";
+import { run } from "./util.js";
+export const git = (cwd, ...args) => {
+    try {
+        return execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+    }
+    catch {
+        return "";
+    }
+};
+// owner/name or a GitHub URL becomes an https clone URL, so the GH_TOKEN helper applies; anything else is cloned as is
+export function toRepo(s) {
+    const gh = s.match(/^([\w.-]+\/[\w.-]+?)(?:\.git)?$/) ?? s.match(/github\.com[:/]([^/]+\/[^/]+?)(?:\.git)?$/);
+    return gh ? { url: `https://github.com/${gh[1]}.git`, label: gh[1] } : { url: s, label: s };
+}
+// the checkout around cwd, if any
+// remote: the origin URL as git has it
+export function checkout(cwd) {
+    const root = git(cwd, "rev-parse", "--show-toplevel");
+    if (!root)
+        return undefined;
+    const origin = git(root, "remote", "get-url", "origin");
+    return { root, ...(origin && { origin: toRepo(origin), remote: origin }) };
+}
+// .env files at the repo root, minus templates like .env.example
+export function dotenvFiles(root) {
+    const names = readdirSync(root).filter((f) => /^\.env/.test(f) && !/\.(example|sample|template)$/.test(f) && statSync(join(root, f)).isFile());
+    return Object.fromEntries(names.map((f) => [f, readFileSync(join(root, f), "utf8")]));
+}
+// undefined when the repo has no .bottleship/ yet
+export function readRepoEnv(root) {
+    const files = readEnvFiles(root);
+    return files && parseRepoEnv(files.Dockerfile);
+}
+// every file in the checkout's .bottleship/, by name
+export function readEnvFiles(root) {
+    const dir = join(root, ".bottleship");
+    if (!existsSync(dir))
+        return undefined;
+    const names = readdirSync(dir).filter((f) => statSync(join(dir, f)).isFile());
+    return Object.fromEntries(names.map((f) => [f, readFileSync(join(dir, f), "utf8")]));
+}
+// the image lines from .bottleship/Dockerfile and the ports it EXPOSEs
+export function parseRepoEnv(dockerfile) {
+    if (dockerfile === undefined)
+        return { ports: [] };
+    if (/^\s*FROM\s/im.test(dockerfile))
+        throw new BsError("bad_dockerfile", ".bottleship/Dockerfile has a FROM line", "drop it: the lines are appended to bottleship's base image, see \"Repo environment\" in the README");
+    const ports = [...dockerfile.matchAll(/^\s*EXPOSE\s+(.+)$/gim)].flatMap((m) => m[1].trim().split(/\s+/)).map((p) => Number(p.replace(/\/tcp$/, ""))).filter((p) => Number.isInteger(p) && p > 0);
+    return { dockerfile, ports };
+}
+// ponytail: tracked and untracked files minus .gitignore'd ones, without .git; send .git too if setup scripts turn out to need history
+export async function workingTree(root) {
+    const listed = (await run("git", ["ls-files", "-z", "-co", "--exclude-standard"], { cwd: root })).stdout;
+    // ls-files still lists files deleted from the working tree but not from the index
+    return tarFiles(root, listed.split("\0").filter((f) => f && existsSync(join(root, f))));
+}
+// a tar of these files, relative to root
+export function tarFiles(root, files) {
+    return new Promise((resolve, reject) => {
+        // COPYFILE_DISABLE keeps macOS tar from adding ._ files
+        const tar = spawn("tar", ["-c", "--no-xattrs", "--null", "-T", "-"], { cwd: root, env: { ...process.env, COPYFILE_DISABLE: "1" }, stdio: ["pipe", "pipe", "pipe"] });
+        const chunks = [];
+        let stderr = "";
+        tar.stdout.on("data", (d) => chunks.push(d));
+        tar.stderr.on("data", (d) => (stderr += d));
+        tar.on("error", reject);
+        tar.on("close", (code) => (code === 0 ? resolve(Buffer.concat(chunks)) : reject(new Error(`tar exited ${code}: ${stderr.trim()}`))));
+        tar.stdin.end(files.join("\0"));
+    });
+}

package/dist/src/review/comments.d.ts

@@ -0,0 +1,66 @@
+import { type GhRepo } from "./github.ts";
+import type { CommentInput, Quote, ReviewComment, Verdict } from "./contract.ts";
+export interface PrTarget {
+    repo: GhRepo;
+    number: number;
+    head?: string;
+}
+export type Asked = "started" | "running" | "failed";
+export interface Request {
+    id: string;
+    where: string;
+    body: string;
+    quotes?: Quote[];
+    thread: {
+        by: string;
+        body: string;
+    }[];
+}
+export interface Waited {
+    comments: Request[];
+    done?: {
+        note?: string;
+    };
+}
+type Fail = {
+    ok: false;
+    code: number;
+    errors: string[];
+};
+type Result<T> = {
+    ok: true;
+    value: T;
+} | Fail;
+export interface StoreOptions {
+    file: string;
+    pr: () => PrTarget | undefined;
+    ask?: (message: string) => Promise<Asked>;
+    running?: () => Promise<boolean>;
+    watchMs?: number;
+    url: () => string;
+    changed: (comments: ReviewComment[]) => void;
+    listening: (on: boolean) => void;
+}
+export declare function commentStore(o: StoreOptions): {
+    list: () => ReviewComment[];
+    listening: () => boolean;
+    create(input: CommentInput, by?: {
+        agent: true;
+    }): Promise<Result<ReviewComment>>;
+    edit(id: string, body: string): Promise<Result<ReviewComment>>;
+    drop(id: string): Promise<Result<null>>;
+    retry(id: string): Result<ReviewComment>;
+    answer(id: string, a: {
+        body: string;
+        commit?: string;
+    }): Result<ReviewComment>;
+    finish(note?: string): void;
+    wait(ms: number): Promise<Waited>;
+    submit(v: Verdict): Promise<Result<{
+        url: string;
+    }>>;
+    sync(): Promise<void>;
+};
+export type CommentStore = ReturnType<typeof commentStore>;
+export declare function boxMessage(requests: Request[], url: string, number: number): string;
+export {};

package/dist/src/review/comments.js

@@ -0,0 +1,344 @@
+// The comments in a review and where they go. To GitHub: each one lands in the reviewer's pending review (or posts
+// at once as a single comment) as it is written, so the tour and github.com always agree. To an agent: requests it
+// answers, handed to the box agent as they come in a PR review, or collected for the developer's own agent in a
+// local one, which picks them up with `bottleship agent review next`. Persisted to comments.json.
+import { readFileSync, renameSync, writeFileSync } from "node:fs";
+import { addReviewReply, addReviewThread, commentStates, deleteGhComment, editGhComment, pendingReview, postSingle, postSingleReply, reviewThreads, startPendingReview, submitReview } from "./github.js";
+const fail = (code, ...errors) => ({ ok: false, code, errors });
+// enough for any real review, and a bound on what the box keeps
+const MAX_COMMENTS = 1000;
+// a wait that ended this recently still counts as an agent listening: it is about to wait again
+const LISTEN_GRACE = 15_000;
+const RETRY = 5_000;
+// how often a PR review checks that the box agent still runs while it has comments
+const WATCH = 4_000;
+export function commentStore(o) {
+    let comments = [];
+    try {
+        const v = JSON.parse(readFileSync(o.file, "utf8"));
+        // drafts from before comments had a recipient were meant for GitHub; sync posts them to the pending review
+        // a single quote came before quotes
+        if (Array.isArray(v))
+            comments = v.map(({ quote, ...c }) => ({ by: "reviewer", to: "github", ...c, ...(quote && { quotes: [{ ...quote, kind: "selection" }] }) }));
+    }
+    catch { }
+    let next = comments.reduce((n, c) => Math.max(n, Number(c.id.replace(/^c/, "")) || 0), 0) + 1;
+    let done;
+    const waiters = [];
+    let lastWait = 0;
+    let heard = false;
+    let dispatching = false;
+    let retry;
+    let watching;
+    const save = () => {
+        writeFileSync(o.file + ".tmp", JSON.stringify(comments, null, 2));
+        renameSync(o.file + ".tmp", o.file);
+        o.changed(comments);
+    };
+    const byId = (id) => comments.find((c) => c.id === id);
+    const add = (c) => {
+        const full = { ...c, id: `c${next++}`, at: new Date().toISOString() };
+        comments.push(full);
+        return full;
+    };
+    const lineOf = (c) => ({ path: c.path, side: c.side, line: c.line, ...(c.startLine && { startLine: c.startLine, startSide: c.startSide }) });
+    const github = async (f) => {
+        try {
+            return { ok: true, value: await f() };
+        }
+        catch (e) {
+            return fail(502, e.message);
+        }
+    };
+    // the comment a thread here starts from
+    const rootOf = (c) => {
+        let r = c;
+        for (let i = 0; r.replyTo && i < MAX_COMMENTS; i++)
+            r = byId(r.replyTo) ?? r;
+        return r;
+    };
+    const where = (c) => {
+        const r = rootOf(c);
+        // a chat message says which page the reviewer was on when they wrote it
+        if (c.topic?.chat)
+            return c.topic.label;
+        if (r.topic)
+            return r.topic.label;
+        const lines = r.startLine && r.startLine !== r.line ? `lines ${r.startLine} to ${r.line}` : `line ${r.line}`;
+        return `${r.path}, ${lines} of the ${r.side === "LEFT" ? "old" : "new"} file${r.inReplyTo ? `, in the GitHub thread on comment ${r.inReplyTo} (src/data/review-comments.json)` : ""}`;
+    };
+    const request = (c) => {
+        const root = rootOf(c);
+        const thread = comments.filter((x) => x !== c && x.at <= c.at && rootOf(x) === root).map((x) => ({ by: x.by === "agent" ? "agent" : "reviewer", body: x.body }));
+        return { id: c.id, where: where(c), body: c.body, ...(c.quotes?.length && { quotes: c.quotes }), thread };
+    };
+    const isListening = () => waiters.length > 0 || Date.now() - lastWait < LISTEN_GRACE;
+    const tellListening = () => {
+        const on = isListening();
+        if (on !== heard)
+            o.listening((heard = on));
+    };
+    // the developer's agent picks up what was sent, and hears when the reviewer is done
+    function take() {
+        const sent = comments.filter((c) => c.to === "agent" && c.by === "reviewer" && c.status === "sent");
+        sent.forEach((c) => (c.status = "working"));
+        if (sent.length)
+            save();
+        const out = { comments: sent.map(request), ...(done && { done }) };
+        done = undefined;
+        return out;
+    }
+    function wake() {
+        if (!waiters.length)
+            return;
+        const w = waiters.shift();
+        clearTimeout(w.timer);
+        w.give(take());
+        tellListening();
+    }
+    // a box agent whose run ends without answering has stopped on those comments; the reviewer can send them again
+    const inFlight = () => comments.filter((c) => c.to === "agent" && c.by === "reviewer" && c.status === "working");
+    function watch() {
+        if (watching || !o.running || !o.pr())
+            return;
+        watching = setInterval(async () => {
+            if (!inFlight().length)
+                return void (clearInterval(watching), (watching = undefined));
+            if (await o.running())
+                return;
+            // an answer may have landed just before the run ended
+            const left = inFlight();
+            if (!left.length)
+                return;
+            left.forEach((c) => (c.status = "stopped"));
+            save();
+        }, o.watchMs ?? WATCH);
+        watching.unref();
+    }
+    // the box agent gets every comment sent to it so far in one follow-up, once it is free
+    async function dispatch() {
+        if (!o.ask || dispatching)
+            return;
+        const sent = comments.filter((c) => c.to === "agent" && c.by === "reviewer" && c.status === "sent");
+        if (!sent.length)
+            return;
+        dispatching = true;
+        try {
+            const r = await o.ask(boxMessage(sent.map(request), o.url(), o.pr()?.number ?? 0));
+            if (r === "started") {
+                sent.forEach((c) => (c.status = "working"));
+                save();
+                watch();
+            }
+            else {
+                clearTimeout(retry);
+                retry = setTimeout(() => void dispatch(), RETRY);
+                retry.unref();
+            }
+        }
+        finally {
+            dispatching = false;
+        }
+    }
+    // comments left working when the server last stopped are checked too
+    watch();
+    return {
+        list: () => comments,
+        listening: isListening,
+        // agent: the agent writes it because the reviewer asked; it is GitHub's and the reviewer's like any other
+        async create(input, by) {
+            if (comments.length >= MAX_COMMENTS)
+                return fail(409, `at most ${MAX_COMMENTS} comments`);
+            const pr = o.pr();
+            const { mode, ...c } = input;
+            if (c.replyTo && !byId(c.replyTo))
+                return fail(400, `replyTo: no comment ${c.replyTo}`);
+            if (c.to === "agent") {
+                const made = add({ ...c, by: "reviewer", status: "sent" });
+                save();
+                if (pr)
+                    void dispatch();
+                else
+                    wake();
+                return { ok: true, value: made };
+            }
+            if (!pr)
+                return fail(409, "these are local changes with no PR: comments go to your agent");
+            const at = lineOf(c);
+            const r = await github(async () => {
+                const p = await pendingReview(pr.repo, pr.number);
+                if (mode === "single") {
+                    if (p.review)
+                        throw new Error("you have a review in progress on GitHub: add the comment to it");
+                    if (c.inReplyTo)
+                        return { state: "posted", ...(await postSingleReply(pr.repo, pr.number, c.inReplyTo, c.body)) };
+                    if (!pr.head)
+                        throw new Error("the PR's head commit is unknown");
+                    return { state: "posted", ...(await postSingle(pr.repo, pr.number, pr.head, at, c.body)) };
+                }
+                const review = p.review?.id ?? (await startPendingReview(pr.repo, p.pr, pr.head)).id;
+                if (c.inReplyTo) {
+                    const thread = comments.find((x) => x.github?.id === c.inReplyTo)?.github?.thread ?? (await reviewThreads(pr.repo, pr.number)).find((t) => t.root === c.inReplyTo)?.id;
+                    if (!thread)
+                        throw new Error("the thread it replies to is gone");
+                    return { state: "pending", ...(await addReviewReply(pr.repo, review, thread, c.body)) };
+                }
+                return { state: "pending", ...(await addReviewThread(pr.repo, review, at, c.body)) };
+            });
+            if (!r.ok)
+                return r;
+            const made = add({ ...c, by: "reviewer", ...(by?.agent && { agent: true }), github: r.value });
+            save();
+            return { ok: true, value: made };
+        },
+        async edit(id, body) {
+            const c = byId(id);
+            if (!c || c.by !== "reviewer")
+                return fail(404, `no comment ${id} of yours`);
+            if (c.to === "agent" && c.status !== "sent" && c.status !== "stopped")
+                return fail(409, "the agent is already working on it");
+            const pr = o.pr();
+            if (c.github && pr) {
+                const r = await github(() => editGhComment(pr.repo, c.github.node, body));
+                if (!r.ok)
+                    return r;
+            }
+            c.body = body;
+            save();
+            return { ok: true, value: c };
+        },
+        async drop(id) {
+            const c = byId(id);
+            if (!c || c.by !== "reviewer")
+                return fail(404, `no comment ${id} of yours`);
+            if (c.to === "agent" && c.status !== "sent" && c.status !== "stopped")
+                return fail(409, "the agent is already working on it");
+            const pr = o.pr();
+            if (c.github && pr) {
+                const r = await github(() => deleteGhComment(pr.repo, c.github.node));
+                if (!r.ok)
+                    return r;
+            }
+            comments = comments.filter((x) => x !== c);
+            save();
+            return { ok: true, value: null };
+        },
+        // sends a comment the agent stopped on again
+        retry(id) {
+            const c = byId(id);
+            if (!c || c.to !== "agent" || c.by !== "reviewer" || c.status !== "stopped")
+                return fail(409, `${id} is not a comment the agent stopped on`);
+            c.status = "sent";
+            save();
+            void dispatch();
+            return { ok: true, value: c };
+        },
+        // an agent's answer to a comment sent to it, with the commit it made
+        answer(id, a) {
+            const c = byId(id);
+            if (!c || c.to !== "agent" || c.by !== "reviewer")
+                return fail(404, `no comment ${id} sent to the agent`);
+            c.status = "done";
+            const made = add({ by: "agent", to: "agent", replyTo: id, body: a.body, ...(a.commit && { commit: a.commit }) });
+            save();
+            return { ok: true, value: made };
+        },
+        // local reviews: the reviewer is done, with a last word for the agent
+        finish(note) {
+            done = { ...(note?.trim() && { note: note.trim() }) };
+            wake();
+        },
+        // what was sent since the last call, or what arrives within ms
+        wait(ms) {
+            lastWait = Date.now();
+            if (done || comments.some((c) => c.to === "agent" && c.status === "sent")) {
+                tellListening();
+                return Promise.resolve(take());
+            }
+            return new Promise((give) => {
+                const w = {
+                    give,
+                    timer: setTimeout(() => {
+                        waiters.splice(waiters.indexOf(w), 1);
+                        lastWait = Date.now();
+                        give({ comments: [] });
+                        setTimeout(tellListening, LISTEN_GRACE + 100).unref();
+                    }, ms),
+                };
+                waiters.push(w);
+                tellListening();
+            });
+        },
+        // submits the reviewer's pending review with the verdict; the comments in it are posted now
+        async submit(v) {
+            const pr = o.pr();
+            if (!pr)
+                return fail(409, "this review has no PR to submit to");
+            if (!v.event)
+                return fail(400, "choose a verdict before submitting");
+            const r = await github(async () => {
+                const p = await pendingReview(pr.repo, pr.number);
+                return submitReview(pr.repo, { pr: p.pr, review: p.review?.id, head: pr.head, event: v.event, body: v.body?.trim() || undefined });
+            });
+            if (!r.ok)
+                return r;
+            comments.forEach((c) => c.github?.state === "pending" && (c.github.state = "posted"));
+            save();
+            return { ok: true, value: { url: r.value } };
+        },
+        // brings the store in line with GitHub: pending comments changed, added, deleted or submitted on github.com
+        async sync() {
+            const pr = o.pr();
+            if (!pr)
+                return;
+            const before = JSON.stringify(comments);
+            const p = await pendingReview(pr.repo, pr.number);
+            const there = new Map((p.review?.comments ?? []).map((c) => [c.node, c]));
+            const gone = comments.filter((c) => c.github?.state === "pending" && !there.has(c.github.node));
+            const states = await commentStates(pr.repo, gone.map((c) => c.github.node));
+            comments = comments.filter((c) => !(c.github && gone.includes(c) && states[c.github.node] === null));
+            for (const c of gone)
+                if (states[c.github.node] === "SUBMITTED")
+                    c.github.state = "posted";
+            const mine = new Set(comments.map((c) => c.github?.node));
+            for (const c of comments) {
+                const g = c.github && there.get(c.github.node);
+                if (g)
+                    c.body = g.body;
+            }
+            for (const g of there.values()) {
+                if (mine.has(g.node) || !g.line)
+                    continue;
+                add({ by: "reviewer", to: "github", body: g.body, path: g.path, side: g.side, line: g.line, ...(g.startLine && { startLine: g.startLine, startSide: g.startSide ?? g.side }), ...(g.replyTo && { inReplyTo: g.replyTo }), github: { state: "pending", node: g.node, id: g.id, ...(g.url && { url: g.url }) } });
+            }
+            // drafts from an older box that never reached GitHub go into the pending review now
+            for (const c of comments.filter((x) => x.to === "github" && !x.github)) {
+                const { id: _id, at: _at, by: _by, github: _g, ...rest } = c;
+                const made = await this.create({ ...rest, mode: "review" });
+                if (made.ok)
+                    comments = comments.filter((x) => x !== c);
+            }
+            if (JSON.stringify(comments) !== before)
+                save();
+        },
+    };
+}
+// the follow-up the box agent gets in a PR review, with everything it needs to act on it
+export function boxMessage(requests, url, number) {
+    const one = (r) => [
+        `${r.id}, from ${r.where}:`,
+        ...r.thread.map((t) => `  earlier, ${t.by}: ${t.body.replace(/\n/g, "\n    ")}`),
+        ...(r.quotes ?? []).flatMap((q) => [`  quoting ${q.kind === "comment" ? (q.where ?? "a comment") : `what they selected${q.where ? ` in ${q.where}` : ""}`}:`, ...q.text.split("\n").map((l) => `  > ${l}`)]),
+        `  ${r.body.replace(/\n/g, "\n  ")}`,
+    ].join("\n");
+    return `The reviewer wrote to you in the tour's chat:
+
+${requests.map(one).join("\n\n")}
+
+- Answer what they ask, checking in the box what you need to. When the answer is a change to lines in the diff, you may include it as a \`\`\`suggestion block that replaces exactly those lines.
+- Change code only when they ask you to: change it in ~/workspace, check it in the running app, commit, and push to the PR's branch (gh pr view ${number} --json headRepository,headRepositoryOwner,headRefName says where; a fork takes it only if its author lets maintainers edit).
+- Write your answers as ~/review/app/WRITING.md says: the answer first, then the evidence, short enough to read in under a minute.
+- Answer every message, even when you change nothing: curl -s -X POST -H 'content-type: application/json' -d '{"body":"<what you did, or why not>","commit":"<the sha, if you committed>"}' ${url}/api/comments/<id>/answer
+- If you pushed, refresh the tour without rebuilding it: gh pr diff ${number} > ~/review/app/src/data/pr.diff, update headRefOid and files in pr.json (gh pr view ${number} --json headRefOid,files), restart head if needed, fix the groups' line ranges and whatever in review.tsx is now wrong, rerun the steps the change affects, npm run check. Then note the update with one sentence on what changed: curl -s -X POST -H 'content-type: application/json' -d '{"note":"<what changed>"}' ${url}/api/updates
+- Never comment on GitHub on your own. Only when the reviewer explicitly asks you to leave a comment, add it to their pending review, where only they see it until they submit: curl -s -X POST -H 'content-type: application/json' -d '{"path":"<file>","side":"RIGHT","line":<last line>,"startSide":"RIGHT","startLine":<first line, for a range>,"body":"<the comment>"}' ${url}/api/comments/agent ("side":"LEFT" for lines of the old file; "inReplyTo":<id of a thread's first comment> to reply in a GitHub thread). Add "mode":"single" only if they asked for it to be posted right away. Never review or approve: the reviewer submits their own review.`;
+}

package/dist/src/review/contract.d.ts

@@ -0,0 +1,82 @@
+export type Status = "ok" | "fail" | "neutral";
+export interface ReviewEvent {
+    instance: string;
+    kind: "request" | "hook" | "ok" | "fail";
+    text: string;
+    at?: string;
+    step?: string;
+    flow?: {
+        id: string;
+        edge?: [string, string];
+        node?: string;
+        status?: Status;
+        label?: string;
+    };
+    overlay?: {
+        title: string;
+        body?: string;
+        status: Status;
+    };
+}
+type Errors = string[];
+export declare function validateEvent(v: unknown): Errors;
+export type Side = "LEFT" | "RIGHT";
+export interface ReviewComment {
+    id: string;
+    at: string;
+    by: "reviewer" | "agent";
+    to: "github" | "agent";
+    body: string;
+    path?: string;
+    side?: Side;
+    line?: number;
+    startSide?: Side;
+    startLine?: number;
+    topic?: {
+        chapter?: string;
+        chat?: boolean;
+        label: string;
+    };
+    quotes?: Quote[];
+    inReplyTo?: number;
+    replyTo?: string;
+    agent?: true;
+    github?: {
+        state: "pending" | "posted";
+        node: string;
+        id: number;
+        url?: string;
+        thread?: string;
+    };
+    status?: "sent" | "working" | "done" | "stopped";
+    commit?: string;
+}
+export interface Quote {
+    text: string;
+    where?: string;
+    kind?: "selection" | "comment";
+}
+export type CommentInput = Pick<ReviewComment, "to" | "body" | "path" | "side" | "line" | "startSide" | "startLine" | "topic" | "quotes" | "inReplyTo" | "replyTo"> & {
+    mode?: "single" | "review";
+};
+export declare const MAX_COMMENT = 65536;
+export declare function validateComment(v: unknown): Errors;
+export declare function validateAnswer(v: unknown): Errors;
+export declare const EVENTS: readonly ["COMMENT", "APPROVE", "REQUEST_CHANGES"];
+export interface Verdict {
+    event?: (typeof EVENTS)[number];
+    body?: string;
+}
+export declare function validateVerdict(v: unknown): Errors;
+export declare const STAGES: {
+    readonly read: "Reading the change";
+    readonly instances: "Starting base and head";
+    readonly hooks: "Adding review hooks";
+    readonly steps: "Writing the steps";
+    readonly shots: "Taking screenshots";
+    readonly tour: "Writing the tour";
+    readonly check: "Checking every page";
+};
+export type Stage = keyof typeof STAGES;
+export declare function validateProgress(v: unknown): Errors;
+export {};