bottleship 0.1.0-prototype.0 → 0.1.0-prototype.2

package/dist/src/review/server.js

@@ -0,0 +1,484 @@
+// The review server that runs in the box next to the app: serves the review app the agent builds in <dir>/app,
+// files under <dir>, takes events from review hooks and streams them to the app, and runs step scripts on request.
+//
+//   GET  /, /assets/...        the built review app (<dir>/app/dist), or a page saying it is being set up
+//   GET  /api/status           { app, progress }: whether the review app is built, and the stages the agent reported so far
+//   POST /api/progress         { stage }: the agent is at this stage (see STAGES in contract.ts)
+//   GET  /api/urls             { "<box port>": "<URL on the reviewer's machine>" }
+//   GET  /api/events           server-sent events: state, every event so far, ready, then live event, step and reset
+//   POST /api/events           an event from a hook or step script; 400 { errors } when it is malformed
+//   POST /api/steps/:id/run    runs <dir>/steps/<id>.sh; 404 without one, 409 while another step runs
+//   POST /api/reset            forgets events and step results, e.g. before running everything again
+//   GET  /files/<path>         files under <dir>, e.g. screenshots in shots/
+//   GET  /api/comments         { comments }: every comment in the review (see comments.ts), kept in <dir>/comments.json
+//   POST /api/comments         a comment for GitHub (into the pending review, or single) or a chat message for the agent; 201 with it,
+//                              400 { errors } when it is malformed, 502 when GitHub refuses it
+//   PATCH /api/comments/:id    { body }: rewrites one of the reviewer's comments, on GitHub too
+//   DELETE /api/comments/:id   deletes one, on GitHub too
+//   POST /api/comments/:id/answer  { body, commit? }: the agent's answer to a comment sent to it
+//   POST /api/comments/:id/retry   sends a comment the box agent stopped on again
+//   POST /api/comments/agent   { path, side, line, ..., body, mode? }: a comment the agent writes because the reviewer asked;
+//                              it goes into the reviewer's pending review unless mode is single
+//   POST /api/finish           { note? }: local reviews: the reviewer is done
+//   POST /api/wait             { ms? }: local reviews: the chat messages for the developer's agent, or { comments: [] } after ms; done once finished
+//   GET  /api/verdict          { event?, body? }: how the reviewer means to finish, kept in <dir>/verdict.json
+//   POST /api/verdict          replaces it
+//   POST /api/submit           submits the reviewer's pending review on GitHub with the verdict; { url }
+//   GET  /api/pr               the PR as it stands on GitHub: state, checks and action runs, reviews, whether it can merge
+//   POST /api/pr/merge         { method }: merges it, only at the head the tour shows; 409 when someone pushed since
+//   POST /api/updates          { note }: the change was updated and the tour refreshed for it, or is being; { n }
+//   POST /api/updates/:n/refreshed  the tour is refreshed for update n
+// Every POST, PATCH and DELETE must be application/json. Changes stream as comments, verdict, agent and updates events.
+import { spawn } from "node:child_process";
+import { existsSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { createServer } from "node:http";
+import { extname, join, resolve, sep } from "node:path";
+import { mergePr, parsePrUrl, prStatus } from "./github.js";
+import { settingUpPage } from "./setting-up.js";
+import { commentStore } from "./comments.js";
+import { MAX_COMMENT, STAGES, validateAnswer, validateComment, validateEvent, validateProgress, validateVerdict } from "./contract.js";
+const TYPES = {
+    ".html": "text/html; charset=utf-8",
+    ".js": "text/javascript; charset=utf-8",
+    ".mjs": "text/javascript; charset=utf-8",
+    ".css": "text/css; charset=utf-8",
+    ".json": "application/json; charset=utf-8",
+    ".svg": "image/svg+xml",
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+    ".mp4": "video/mp4",
+    ".webm": "video/webm",
+    ".woff2": "font/woff2",
+    ".txt": "text/plain; charset=utf-8",
+};
+const MAX_BODY = 4 * MAX_COMMENT;
+// how long a wait for comments may hold its request
+const MAX_WAIT = 60_000;
+// GitHub is asked again for the reviewer's pending review at most this often, when a page connects
+const SYNC_EVERY = 15_000;
+// and for the PR's status at most this often, while its page polls
+const STATUS_EVERY = 10_000;
+const METHODS = ["MERGE", "SQUASH", "REBASE"];
+const STEP_ID = /^[A-Za-z0-9][\w.-]*$/;
+// a failed step's output, enough for the reviewer to see why
+const tail = (s) => (s.length > 4000 ? "…" + s.slice(-4000) : s);
+function readBody(req) {
+    return new Promise((res, rej) => {
+        let body = "";
+        req.on("data", (c) => {
+            body += c;
+            if (body.length > MAX_BODY)
+                req.destroy(new Error("body too large"));
+        });
+        req.on("end", () => res(body));
+        req.on("error", rej);
+    });
+}
+const json = (res, code, body) => res.writeHead(code, { "content-type": TYPES[".json"] }).end(JSON.stringify(body));
+// the whole file, or the byte range asked for, which video players need to play and loop a clip
+function sendFile(res, file, range) {
+    let body;
+    try {
+        if (!statSync(file).isFile())
+            throw new Error("not a file");
+        body = readFileSync(file);
+    }
+    catch {
+        return res.writeHead(404).end();
+    }
+    const head = { "content-type": TYPES[extname(file)] ?? "application/octet-stream", "cache-control": "no-store", "accept-ranges": "bytes" };
+    const m = range?.match(/^bytes=(\d*)-(\d*)$/);
+    if (!m || (!m[1] && !m[2]))
+        return res.writeHead(200, head).end(body);
+    // bytes=a-b, bytes=a- (to the end), bytes=-n (the last n)
+    const start = m[1] ? Number(m[1]) : Math.max(0, body.length - Number(m[2]));
+    const end = m[1] && m[2] ? Math.min(Number(m[2]), body.length - 1) : body.length - 1;
+    if (start >= body.length || start > end)
+        return res.writeHead(416, { "content-range": `bytes */${body.length}` }).end();
+    res.writeHead(206, { ...head, "content-range": `bytes ${start}-${end}/${body.length}` }).end(body.subarray(start, end + 1));
+}
+// a request path inside root, decoded and resolved before the check so neither ../ nor %2e%2e%2f leaves it
+function inside(root, rel) {
+    let decoded;
+    try {
+        decoded = decodeURIComponent(rel);
+    }
+    catch {
+        return undefined;
+    }
+    const file = resolve(root, "." + sep + decoded);
+    return file.startsWith(root + sep) ? file : undefined;
+}
+export async function startReviewServer({ dir: rawDir, port = 7777, host = "127.0.0.1", urls, ask, state, watchMs }) {
+    const dir = resolve(rawDir);
+    const dist = join(dir, "app", "dist");
+    let events = [];
+    let steps = {};
+    let running;
+    let submitting = false;
+    const progress = [];
+    // the PR the page is about, from the data the review app gets; nothing when it cannot be read
+    const subject = () => {
+        try {
+            const pr = JSON.parse(readFileSync(join(dir, "app", "src", "data", "pr.json"), "utf8"));
+            const repo = String(pr.repo ?? String(pr.url).replace(/^https?:\/\/[^/]+\/[^/]+\/([^/]+)\/pull\/.*$/, "$1")).split("/").pop();
+            return { ref: pr.number ? `${repo} #${pr.number}` : `${repo}, local changes`, title: String(pr.title ?? "") };
+        }
+        catch {
+            return undefined;
+        }
+    };
+    const clients = new Set();
+    let url = "";
+    const verdictFile = join(dir, "verdict.json");
+    const updatesFile = join(dir, "updates.json");
+    const load = (file, ok, empty) => {
+        try {
+            const v = JSON.parse(readFileSync(file, "utf8"));
+            return ok(v) ? v : empty;
+        }
+        catch {
+            return empty;
+        }
+    };
+    let verdict = load(verdictFile, (v) => validateVerdict(v).length === 0, {});
+    const updates = load(updatesFile, Array.isArray, []);
+    // written whole and renamed into place, so a crash never leaves half a file
+    const save = (file, v) => {
+        writeFileSync(file + ".tmp", JSON.stringify(v, null, 2));
+        renameSync(file + ".tmp", file);
+    };
+    // the PR the review is of, from the data the review app gets; none for local changes
+    const prTarget = () => {
+        try {
+            const pr = JSON.parse(readFileSync(join(dir, "app", "src", "data", "pr.json"), "utf8"));
+            const at = parsePrUrl(String(pr.url));
+            return at && { ...at, head: typeof pr.headRefOid === "string" ? pr.headRefOid : undefined };
+        }
+        catch {
+            return undefined;
+        }
+    };
+    const askAgent = (message) => new Promise((ok) => {
+        if (!ask)
+            return ok("failed");
+        const child = spawn("bash", [ask], { stdio: ["pipe", "pipe", "ignore"] });
+        let o = "";
+        child.stdout.on("data", (d) => (o += d));
+        child.on("close", () => ok(o.trim() === "started" ? "started" : o.trim() === "running" ? "running" : "failed"));
+        child.on("error", () => ok("failed"));
+        child.stdin.end(message);
+    });
+    const agentRunning = () => new Promise((ok) => {
+        if (!state)
+            return ok(true);
+        const child = spawn("bash", [state], { stdio: ["ignore", "pipe", "ignore"] });
+        let o = "";
+        child.stdout.on("data", (d) => (o += d));
+        child.on("close", () => ok(o.trim() !== "idle"));
+        child.on("error", () => ok(true));
+    });
+    const agentState = () => ({ local: !prTarget(), listening: store.listening() });
+    const store = commentStore({
+        file: join(dir, "comments.json"),
+        pr: prTarget,
+        ask: askAgent,
+        running: agentRunning,
+        watchMs,
+        url: () => url,
+        changed: (comments) => broadcast("comments", { comments }),
+        listening: () => broadcast("agent", agentState()),
+    });
+    let status;
+    let merging = false;
+    const freshStatus = async (pr) => {
+        status = { at: Date.now(), value: await prStatus(pr.repo, pr.number) };
+        return status.value;
+    };
+    let synced = 0;
+    const sync = () => {
+        if (Date.now() - synced < SYNC_EVERY)
+            return;
+        synced = Date.now();
+        store.sync().catch(() => { });
+    };
+    sync();
+    const send = (res, event, data) => res.write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`);
+    const broadcast = (event, data) => clients.forEach((c) => send(c, event, data));
+    const setStep = (s) => {
+        steps[s.id] = s;
+        broadcast("step", s);
+    };
+    function runStep(id, script) {
+        running = id;
+        setStep({ id, status: "running" });
+        let output = "";
+        const child = spawn("bash", [script], { cwd: dir, env: { ...process.env, BOTTLESHIP_REVIEW_URL: url, BOTTLESHIP_REVIEW_STEP: id }, stdio: ["ignore", "pipe", "pipe"] });
+        child.stdout.on("data", (d) => (output += d));
+        child.stderr.on("data", (d) => (output += d));
+        const finish = (ok) => {
+            if (running !== id)
+                return;
+            running = undefined;
+            setStep(ok ? { id, status: "done" } : { id, status: "failed", output: tail(output) });
+        };
+        child.on("error", (e) => ((output += e.message), finish(false)));
+        child.on("close", (code) => finish(code === 0));
+    }
+    async function handle(req, res) {
+        const u = new URL(req.url ?? "/", "http://review");
+        const path = u.pathname;
+        // a JSON content type makes a browser preflight cross-origin requests, which this server never allows, so other pages cannot run steps
+        if (req.method !== "GET" && req.method !== "HEAD" && !(req.headers["content-type"] ?? "").startsWith("application/json"))
+            return json(res, 415, { errors: ["send content-type: application/json"] });
+        if (req.method === "GET" && path === "/api/status")
+            return json(res, 200, { app: existsSync(join(dist, "index.html")), progress: progress.map((s) => STAGES[s]) });
+        if (req.method === "POST" && path === "/api/progress") {
+            let body;
+            try {
+                body = JSON.parse(await readBody(req));
+            }
+            catch {
+                return json(res, 400, { errors: ["progress: expected JSON"] });
+            }
+            const problems = validateProgress(body);
+            if (problems.length)
+                return json(res, 400, { errors: problems });
+            const stage = body.stage;
+            if (progress.at(-1) !== stage)
+                progress.push(stage);
+            return res.writeHead(204).end();
+        }
+        if (req.method === "GET" && path === "/api/urls") {
+            try {
+                return json(res, 200, urls ? JSON.parse(readFileSync(urls, "utf8")) : {});
+            }
+            catch {
+                return json(res, 200, {});
+            }
+        }
+        if (req.method === "GET" && path === "/api/events") {
+            res.writeHead(200, { "content-type": "text/event-stream", "cache-control": "no-store", connection: "keep-alive" });
+            send(res, "state", { steps });
+            send(res, "comments", { comments: store.list() });
+            send(res, "verdict", verdict);
+            send(res, "agent", agentState());
+            send(res, "updates", { updates });
+            events.forEach((e) => send(res, "event", e));
+            send(res, "ready", {});
+            clients.add(res);
+            req.on("close", () => clients.delete(res));
+            sync();
+            return;
+        }
+        if (req.method === "POST" && path === "/api/events") {
+            let body;
+            try {
+                body = JSON.parse(await readBody(req));
+            }
+            catch {
+                return json(res, 400, { errors: ["event: expected JSON"] });
+            }
+            const problems = validateEvent(body);
+            if (problems.length)
+                return json(res, 400, { errors: problems });
+            const ev = { ...body, ...(running && { step: running }), seq: events.length + 1 };
+            events.push(ev);
+            broadcast("event", ev);
+            return json(res, 201, { seq: ev.seq });
+        }
+        const run = req.method === "POST" && path.match(/^\/api\/steps\/([^/]+)\/run$/);
+        if (run) {
+            const id = decodeURIComponent(run[1]);
+            const script = join(dir, "steps", `${id}.sh`);
+            if (!STEP_ID.test(id) || !existsSync(script))
+                return json(res, 404, { errors: [`no step "${id}": write ~/review/steps/${id}.sh`] });
+            if (running)
+                return json(res, 409, { errors: [`step "${running}" is still running`] });
+            runStep(id, script);
+            return json(res, 202, { id, status: "running" });
+        }
+        if (req.method === "POST" && path === "/api/reset") {
+            if (running)
+                return json(res, 409, { errors: [`step "${running}" is still running`] });
+            events = [];
+            steps = {};
+            broadcast("reset", {});
+            return res.writeHead(204).end();
+        }
+        if (path === "/api/comments" && req.method === "GET")
+            return json(res, 200, { comments: store.list() });
+        if (path === "/api/pr" && req.method === "GET") {
+            const pr = prTarget();
+            if (!pr)
+                return json(res, 409, { errors: ["these are local changes with no PR"] });
+            try {
+                return json(res, 200, status && Date.now() - status.at < STATUS_EVERY ? status.value : await freshStatus(pr));
+            }
+            catch (e) {
+                return json(res, 502, { errors: [e.message] });
+            }
+        }
+        if (path === "/api/verdict" && req.method === "GET")
+            return json(res, 200, verdict);
+        if (req.method === "GET" || req.method === "HEAD") {
+            // everything below takes a JSON body
+        }
+        else {
+            let body;
+            try {
+                body = JSON.parse((await readBody(req)) || "{}");
+            }
+            catch {
+                return json(res, 400, { errors: ["expected a JSON body"] });
+            }
+            const reply = (r, code = 200) => (r.ok ? (r.value === null ? res.writeHead(204).end() : json(res, code, r.value)) : json(res, r.code, { errors: r.errors }));
+            if (path === "/api/verdict" && req.method === "POST") {
+                const problems = validateVerdict(body);
+                if (problems.length)
+                    return json(res, 400, { errors: problems });
+                verdict = body;
+                save(verdictFile, verdict);
+                broadcast("verdict", verdict);
+                return json(res, 200, verdict);
+            }
+            if (path === "/api/comments/agent" && req.method === "POST") {
+                const input = { to: "github", mode: "review", ...(body ?? {}) };
+                const problems = validateComment(input);
+                if (problems.length)
+                    return json(res, 400, { errors: problems });
+                return reply(await store.create(input, { agent: true }), 201);
+            }
+            if (path === "/api/comments" && req.method === "POST") {
+                const problems = validateComment(body);
+                if (problems.length)
+                    return json(res, 400, { errors: problems });
+                return reply(await store.create(body), 201);
+            }
+            const one = path.match(/^\/api\/comments\/(c\d+)(\/answer)?$/);
+            if (one && one[2] && req.method === "POST") {
+                const problems = validateAnswer(body);
+                if (problems.length)
+                    return json(res, 400, { errors: problems });
+                return reply(store.answer(one[1], body), 201);
+            }
+            const retry = path.match(/^\/api\/comments\/(c\d+)\/retry$/);
+            if (retry && req.method === "POST")
+                return reply(store.retry(retry[1]));
+            if (one && !one[2] && req.method === "DELETE")
+                return reply(await store.drop(one[1]));
+            if (one && !one[2] && req.method === "PATCH") {
+                const problems = [...(typeof body?.body === "string" && body.body.trim() && body.body.length <= MAX_COMMENT ? [] : ["body: expected a non-empty string"]), ...Object.keys(body ?? {}).filter((k) => k !== "body").map((k) => `${k}: only body can change`)];
+                if (problems.length)
+                    return json(res, 400, { errors: problems });
+                return reply(await store.edit(one[1], body.body));
+            }
+            if (path === "/api/finish" && req.method === "POST") {
+                if (body?.note !== undefined && (typeof body.note !== "string" || body.note.length > MAX_COMMENT))
+                    return json(res, 400, { errors: ["note: expected a string"] });
+                store.finish(body?.note);
+                return res.writeHead(204).end();
+            }
+            if (path === "/api/wait" && req.method === "POST") {
+                const ms = Math.min(MAX_WAIT, Math.max(0, Number(body?.ms ?? 25_000) || 0));
+                return json(res, 200, await store.wait(ms));
+            }
+            if (path === "/api/submit" && req.method === "POST") {
+                if (submitting)
+                    return json(res, 409, { errors: ["already submitting"] });
+                submitting = true;
+                try {
+                    const r = await store.submit(verdict);
+                    if (r.ok) {
+                        verdict = {};
+                        save(verdictFile, verdict);
+                        broadcast("verdict", verdict);
+                    }
+                    return reply(r);
+                }
+                finally {
+                    submitting = false;
+                }
+            }
+            if (path === "/api/pr/merge" && req.method === "POST") {
+                const pr = prTarget();
+                if (!pr)
+                    return json(res, 409, { errors: ["these are local changes with no PR"] });
+                if (!METHODS.includes(body?.method))
+                    return json(res, 400, { errors: [`method: expected one of ${METHODS.join(", ")}`] });
+                if (merging)
+                    return json(res, 409, { errors: ["already merging"] });
+                merging = true;
+                try {
+                    const now = await freshStatus(pr);
+                    if (!now.canMerge)
+                        return json(res, 403, { errors: ["your GitHub account cannot merge this PR"] });
+                    if (!now.methods.includes(body.method))
+                        return json(res, 400, { errors: [`the repo does not allow ${body.method.toLowerCase()} merges`] });
+                    // the commit the reviewer saw, so nothing pushed since goes in unseen
+                    if (pr.head && now.head.oid !== pr.head)
+                        return json(res, 409, { errors: ["someone pushed to the PR since this tour was built: review the new commits before merging"] });
+                    await mergePr(pr.repo, { id: now.id, method: body.method, head: now.head.oid });
+                    return json(res, 200, await freshStatus(pr));
+                }
+                catch (e) {
+                    return json(res, 502, { errors: [e.message] });
+                }
+                finally {
+                    merging = false;
+                }
+            }
+            if (path === "/api/updates" && req.method === "POST") {
+                if (typeof body?.note !== "string" || !body.note.trim() || body.note.length > 2000)
+                    return json(res, 400, { errors: ["note: expected a sentence on what changed"] });
+                const u = { n: updates.length + 1, at: new Date().toISOString(), note: body.note.trim(), ...(body.refreshed !== false && { refreshed: new Date().toISOString() }) };
+                updates.push(u);
+                save(updatesFile, updates);
+                broadcast("updates", { updates });
+                return json(res, 201, u);
+            }
+            const refreshed = path.match(/^\/api\/updates\/(\d+)\/refreshed$/);
+            if (refreshed && req.method === "POST") {
+                const u = updates.find((x) => x.n === Number(refreshed[1]));
+                if (!u)
+                    return json(res, 404, { errors: [`no update ${refreshed[1]}`] });
+                u.refreshed = new Date().toISOString();
+                save(updatesFile, updates);
+                broadcast("updates", { updates });
+                return json(res, 200, u);
+            }
+        }
+        if (req.method === "GET" && path.startsWith("/files/")) {
+            const file = inside(dir, path.slice("/files/".length));
+            return file ? sendFile(res, file, req.headers.range) : res.writeHead(404).end();
+        }
+        if (req.method === "GET") {
+            if (!existsSync(join(dist, "index.html")))
+                return path === "/" ? res.writeHead(200, { "content-type": TYPES[".html"], "cache-control": "no-store" }).end(settingUpPage(subject())) : res.writeHead(404).end();
+            const file = path === "/" ? join(dist, "index.html") : inside(dist, path.slice(1));
+            return file ? sendFile(res, file) : res.writeHead(404).end();
+        }
+        res.writeHead(404).end();
+    }
+    const server = createServer((req, res) => {
+        handle(req, res).catch((e) => {
+            if (!res.headersSent)
+                json(res, 500, { errors: [e.message] });
+        });
+    });
+    await new Promise((ok, fail) => server.once("error", fail).listen(port, host, () => ok()));
+    const addr = server.address();
+    // a server on every interface is still reached locally at 127.0.0.1, which is what step scripts get
+    url = `http://${host === "0.0.0.0" ? "127.0.0.1" : host}:${typeof addr === "object" && addr ? addr.port : port}`;
+    return {
+        url,
+        close: () => new Promise((ok) => {
+            clients.forEach((c) => c.end());
+            server.closeAllConnections();
+            server.close(() => ok());
+        }),
+    };
+}

package/dist/src/review/setting-up.d.ts

@@ -0,0 +1,4 @@
+export declare function settingUpPage(pr?: {
+    ref: string;
+    title: string;
+}): string;

package/dist/src/review/setting-up.js

@@ -0,0 +1,74 @@
+// The page the review link shows until the agent has built the tour: the PR in the corner where the tour's rail will
+// put it, the agent's boat riding the waves, and the stages the agent has reported, sliding up as they come.
+// It opens the tour as soon as /api/status says it is built.
+const esc = (s) => s.replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`);
+// the review kit's tokens, so the page and the tour feel like one thing
+const STYLE = `
+:root { --bg: #f4f4f5; --hover: rgba(0,0,0,.035); --text: #1b1b1f; --text-2: #67676f; --text-3: #a1a1a9; --ease: cubic-bezier(.23,1,.32,1); color-scheme: light; }
+:root[data-theme="dark"] { --bg: #0c0c0d; --hover: rgba(255,255,255,.035); --text: #e8e8eb; --text-2: #96969d; --text-3: #5f5f66; color-scheme: dark; }
+* { box-sizing: border-box; }
+html, body { margin: 0; height: 100%; }
+body { background: var(--bg); color: var(--text); font: 400 14px/1.5 "Inter", -apple-system, BlinkMacSystemFont, sans-serif; letter-spacing: -0.006em; -webkit-font-smoothing: antialiased; display: grid; place-items: center; }
+.corner { position: fixed; top: 20px; left: 20px; max-width: 260px; font-size: 13px; }
+.corner .r { color: var(--text-3); display: flex; align-items: center; gap: 6px; }
+.corner b { display: block; margin-top: 6px; font-weight: 500; line-height: 1.35; }
+svg.i { width: 14px; height: 14px; flex: none; stroke: currentColor; fill: none; stroke-width: 1.5; stroke-linecap: round; stroke-linejoin: round; }
+.icon-btn { all: unset; position: fixed; top: 16px; right: 16px; width: 28px; height: 28px; border-radius: 6px; display: inline-flex; align-items: center; justify-content: center; color: var(--text-3); cursor: pointer; transition: background-color 120ms ease-out, color 120ms ease-out; }
+.icon-btn:hover { background: var(--hover); color: var(--text); }
+.icon-btn:active { transform: scale(.94); }
+.icon-btn:focus-visible { outline: 2px solid var(--text-3); outline-offset: 2px; }
+main { display: flex; flex-direction: column; align-items: center; gap: 24px; animation: rise 260ms var(--ease); }
+/* the boat the agent's chat shows while it works, in the page's stronger tones: a sail riding two waves */
+.sailing { display: block; overflow: hidden; border-radius: 10px; --water: var(--text); }
+.sailing .sea { fill: color-mix(in srgb, var(--water) 62%, var(--bg)); }
+.sailing .sea.back { fill: color-mix(in srgb, var(--water) 32%, var(--bg)); }
+.sailing .boat { fill: var(--text); transform-origin: 15px 14px; animation: ride 2.4s ease-in-out infinite; }
+.sailing .wave { animation: roll 3.2s linear infinite; }
+.sailing .wave.slow { animation-duration: 5.6s; }
+.trail { --row: 24px; width: 320px; height: calc(var(--row) * 3); overflow: hidden; text-align: center; }
+.track { display: flex; flex-direction: column; transition: transform 420ms var(--ease); }
+.track span { height: var(--row); line-height: var(--row); font-size: 13px; color: var(--text-3); opacity: 0; white-space: nowrap; transition: opacity 420ms var(--ease), color 420ms var(--ease); }
+.track .d2 { opacity: .45; }
+.track .d1 { opacity: 1; }
+.track .now { opacity: 1; color: var(--text); }
+@keyframes rise { from { opacity: 0; transform: translateY(6px); } }
+@keyframes roll { to { transform: translateX(-16px); } }
+@keyframes ride { 0%, 100% { transform: translateY(-1px) rotate(-5deg); } 50% { transform: translateY(1px) rotate(5deg); } }
+@media (prefers-reduced-motion: reduce) { *, *::before, *::after { animation: none !important; transition: none !important; } }
+`;
+// one wave is a crest and a trough, 16 units; long enough to still fill the view after rolling a full wave
+const WAVE = "q4-2.5 8 0t8 0 8 0 8 0 8 0 8 0 8 0 8 0 8 0 8 0";
+// the chat's boat, drawn larger: the same shapes and motion, so building the tour and the agent at work look alike
+const BOAT = `<svg class="sailing" width="96" height="67" viewBox="0 -3 30 21" aria-hidden="true">
+<path class="sea back wave slow" d="M-8 12.5${WAVE}V18H-8Z"/><path class="boat" d="M13 3v11h7.5Z"/><path class="sea wave" d="M0 14${WAVE}V18H0Z"/>
+</svg>`;
+const PR_ICON = `<svg class="i" viewBox="0 0 16 16"><circle cx="4" cy="3.5" r="1.5"/><circle cx="4" cy="12.5" r="1.5"/><circle cx="12" cy="12.5" r="1.5"/><path d="M4 5v6M12 11V6.5A2 2 0 0 0 10 4.5H7.5M9 3l-1.5 1.5L9 6"/></svg>`;
+// polls the server: the tour when it is built, else each newly reported stage slides in at the bottom of the trail
+const SCRIPT = `
+var SUN = '<svg class="i" viewBox="0 0 16 16"><circle cx="8" cy="8" r="2.75"/><path d="M8 1.5v1.5M8 13v1.5M1.5 8H3M13 8h1.5M3.4 3.4l1.06 1.06M11.54 11.54l1.06 1.06M3.4 12.6l1.06-1.06M11.54 4.46l1.06-1.06"/></svg>';
+var MOON = '<svg class="i" viewBox="0 0 16 16"><path d="M13.5 9.6A5.5 5.5 0 0 1 6.4 2.5a5.5 5.5 0 1 0 7.1 7.1Z"/></svg>';
+var root = document.documentElement, btn = document.getElementById("theme");
+function paint() { var dark = root.dataset.theme === "dark"; btn.innerHTML = dark ? SUN : MOON; btn.title = dark ? "Light theme" : "Dark theme"; btn.setAttribute("aria-label", btn.title); }
+btn.onclick = function () { root.dataset.theme = root.dataset.theme === "dark" ? "light" : "dark"; try { localStorage.setItem("review-theme", root.dataset.theme); } catch (e) {} paint(); };
+paint();
+var track = document.getElementById("track"), shown = [];
+function render(stages) {
+  if (stages.length === shown.length) return;
+  for (var i = shown.length; i < stages.length; i++) { var s = document.createElement("span"); s.textContent = stages[i]; track.appendChild(s); }
+  shown = stages.slice();
+  var at = shown.length - 1;
+  [].forEach.call(track.children, function (el, i) { el.className = i === at ? "now" : i === at - 1 ? "d1" : i === at - 2 ? "d2" : ""; });
+  track.style.transform = "translateY(calc(var(--row) * " + -Math.max(0, at - 2) + "))";
+}
+function tick() { fetch("api/status").then(function (r) { return r.json(); }).then(function (s) { if (s.app) return location.reload(); render(["Starting the agent"].concat(s.progress || [])); }, function () {}); }
+render(["Starting the agent"]); tick(); setInterval(tick, 2000);
+`;
+export function settingUpPage(pr) {
+    return `<!doctype html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>Review</title>
+<script>try{var t=localStorage.getItem("review-theme")}catch(e){}document.documentElement.dataset.theme=t==="light"||t==="dark"?t:matchMedia("(prefers-color-scheme: dark)").matches?"dark":"light"</script>
+<style>${STYLE}</style></head><body>
+${pr ? `<div class="corner"><span class="r">${PR_ICON} ${esc(pr.ref)}</span><b>${esc(pr.title)}</b></div>` : ""}
+<button class="icon-btn" id="theme"></button>
+<main>${BOAT}<div class="trail" role="status" aria-live="polite"><div class="track" id="track"></div></div></main>
+<script>${SCRIPT}</script></body></html>`;
+}

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

@@ -0,0 +1,32 @@
+import { type Box } from "../boxes.ts";
+import type { PrRepo } from "./target.ts";
+import type { Config } from "../types.ts";
+export declare const REVIEW_PORT: number;
+export declare const INSTANCE_PORTS: number[];
+export interface ReviewStarted {
+    box: Box;
+    url: string;
+    pr: string;
+    title: string;
+    env: "pr" | "local" | "none";
+}
+export type ReviewSource = {
+    pr: {
+        repo: PrRepo;
+        number: number;
+    };
+} | {
+    changes: {
+        root: string;
+        base?: string;
+        note?: string;
+        repo?: string;
+    };
+};
+export declare function startReview(cfg: Config, opts: {
+    source: ReviewSource;
+    local?: string;
+    provider: string;
+    agent: string;
+    onPhase?: (text: string) => void;
+}): Promise<ReviewStarted>;