@shiyuphan/follow-me 0.1.0 → 0.2.0

package/dist/src/server.js

@@ -1,104 +1,106 @@
-import { spawn } from "node:child_process";
-import { randomBytes } from "node:crypto";
+import { createHash, randomBytes } from "node:crypto";
 import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
 import { createServer } from "node:http";
-import { join } from "node:path";
+import { homedir } from "node:os";
+import { basename, isAbsolute, join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { isReplyId, parseComment, parseDraft, parseNewDecision, parseNewReply, } from "./comments.js";
+import { isConcernId, isPlanVersion } from "./plan.js";
+import { renderReport } from "./prompt.js";
+import { isLockToken } from "./session.js";
+/** The requested port is taken; host.ts decides whether that is our server or a stranger. */
+export class PortInUseError extends Error {
+    name = "PortInUseError";
+    port;
+    constructor(port) {
+        super(`port ${port} is in use`);
+        this.port = port;
+    }
+}
+/** A session the server cannot host, with the reason the CLI shows. */
+export class RegistrationError extends Error {
+    name = "RegistrationError";
+}
+/** GET /api/health answers with this, so a CLI can tell our server from another program. */
+export const HEALTH_APP = "follow-me";
 const UI_DIR = new URL("../ui/", import.meta.url);
-const STATIC_FILES = new Map([
-    ["/", { file: "index.html", type: "text/html; charset=utf-8" }],
-    ["/app.js", { file: "app.js", type: "text/javascript; charset=utf-8" }],
-    ["/playback.js", { file: "playback.js", type: "text/javascript; charset=utf-8" }],
-    ["/style.css", { file: "style.css", type: "text/css; charset=utf-8" }],
+/** Every module and the stylesheet in ui/ is served flat, so a new module needs no route. */
+const STATIC_FILE = /^\/([a-z][a-z-]*\.(?:js|css))$/;
+const STATIC_TYPES = new Map([
+    ["js", "text/javascript; charset=utf-8"],
+    ["css", "text/css; charset=utf-8"],
 ]);
+/** Mermaid's ESM entry imports its chunks by relative path, so they are served beside it. */
+const MERMAID_ENTRY = new URL(import.meta.resolve("mermaid/dist/mermaid.esm.min.mjs"));
+const MERMAID_CHUNK = /^\/vendor\/chunks\/mermaid\.esm\.min\/([\w-]+\.mjs)$/;
+/** Prism is a plain script per component, loaded one at a time by the page as languages need. */
+const PRISM_CORE = new URL(import.meta.resolve("prismjs/components/prism-core.min.js"));
+const PRISM_PATH = /^\/vendor\/prism\/([a-z][a-z-]*)\.js$/;
 const MAX_BODY_BYTES = 1_000_000;
 const BASE32 = "abcdefghijklmnopqrstuvwxyz234567";
 const COMMENT_ID = /^c_[a-z2-7]{6}$/;
-const UNIT_ID = /^[hfm]_[0-9a-f]{12}(~\d+)?$/;
+const SESSION_ID = /^[0-9a-f]{12}$/;
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function isCommentId(value) {
     return typeof value === "string" && COMMENT_ID.test(value);
 }
-function isUnitId(value) {
-    return typeof value === "string" && UNIT_ID.test(value);
-}
-function isRepoPath(value) {
-    return typeof value === "string" && value.length > 0;
+export function isSessionId(value) {
+    return typeof value === "string" && SESSION_ID.test(value);
 }
-function isIndex(value) {
-    return typeof value === "number" && Number.isInteger(value) && value >= 0;
+/** Derived from the session directory, so registering one session twice yields one id. */
+export function sessionIdOf(dir) {
+    const id = createHash("sha256").update(dir).digest("hex").slice(0, 12);
+    if (!isSessionId(id))
+        throw new Error(`sha256 produced ${id}`);
+    return id;
 }
-function parseAnchor(raw) {
-    if (!isRecord(raw))
-        return null;
-    const commit = raw["commit"];
-    switch (raw["kind"]) {
-        case "plan":
-            return { kind: "plan" };
-        case "message":
-            return isIndex(commit) ? { kind: "message", commit } : null;
-        case "position":
-            return isIndex(commit) ? { kind: "position", commit } : null;
-        case "hunk": {
-            const unit = raw["unit"];
-            const changes = raw["changes"];
-            if (!isIndex(commit) || !isUnitId(unit))
-                return null;
-            if (changes === null)
-                return { kind: "hunk", unit, commit, changes: null };
-            if (!Array.isArray(changes) || !changes.every(isIndex))
-                return null;
-            return { kind: "hunk", unit, commit, changes };
-        }
-        default:
-            return null;
-    }
+export function sessionPath(id) {
+    return `/s/${id}/`;
 }
-/** The one place untrusted JSON becomes a Comment. Returns null when any field is wrong. */
-export function parseComment(raw) {
+/** The one place untrusted JSON becomes a Registration. */
+export function parseRegistration(raw) {
     if (!isRecord(raw))
         return null;
-    const { id, body, createdAt } = raw;
-    const context = raw["context"];
-    const anchor = parseAnchor(raw["anchor"]);
-    if (!isCommentId(id) || !anchor || !isRecord(context))
+    const { dir, mode, version, hash, lockToken } = raw;
+    if (typeof dir !== "string" || !isAbsolute(dir))
         return null;
-    const { commitMessage, path } = context;
-    if (typeof commitMessage !== "string" || typeof body !== "string")
+    if (mode !== "split" && mode !== "walk")
         return null;
-    if (typeof createdAt !== "string")
+    if (!isPlanVersion(version) || typeof hash !== "string" || hash === "")
         return null;
-    if (path !== null && !isRepoPath(path))
+    if (lockToken !== null && !isLockToken(lockToken))
         return null;
-    return { id, anchor, context: { commitMessage, path }, body, createdAt };
+    return { dir, mode, version, hash, lockToken };
 }
 function draftPath(reviewsDir, version) {
     return join(reviewsDir, `v${version}.draft.json`);
 }
-/** Comments autosaved by an unfinished review of this version, or none. */
-export async function loadDraftComments(reviewsDir, version) {
+/** What an unfinished review of this version autosaved, or nothing. */
+export async function loadDraft(reviewsDir, version) {
     let text;
     try {
         text = await readFile(draftPath(reviewsDir, version), "utf8");
     }
     catch (error) {
-        if (isRecord(error) && error["code"] === "ENOENT")
-            return [];
+        if (isRecord(error) && error["code"] === "ENOENT") {
+            return { comments: [], concerns: [], resolved: [] };
+        }
         throw error;
     }
-    const raw = JSON.parse(text);
-    const list = isRecord(raw) ? raw["comments"] : null;
-    if (!Array.isArray(list))
+    const draft = parseDraft(JSON.parse(text));
+    if (typeof draft === "string")
         throw new Error(`malformed review draft for v${version}`);
-    return list.flatMap((item) => {
-        const comment = parseComment(item);
-        return comment ? [comment] : [];
-    });
+    return draft;
+}
+/** Comments autosaved by an unfinished review of this version, or none. */
+export async function loadDraftComments(reviewsDir, version) {
+    return (await loadDraft(reviewsDir, version)).comments;
 }
 async function writeAtomic(path, text) {
-    const temp = `${path}.${randomBytes(4).toString("hex")}.tmp`;
+    // The pid lets `follow-me clean` tell an abandoned temp file from one being written.
+    const temp = `${path}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;
     await writeFile(temp, text);
     await rename(temp, path);
 }
@@ -139,134 +141,682 @@ function sendJson(res, status, body) {
     res.writeHead(status, { "content-type": "application/json; charset=utf-8" });
     res.end(JSON.stringify(body));
 }
-function openBrowser(url) {
-    const command = process.platform === "darwin" ? "open" : "xdg-open";
-    const child = spawn(command, [url], { stdio: "ignore", detached: true });
-    child.on("error", (error) => console.error(`could not open a browser: ${error.message}`));
-    child.unref();
+/** An integer query parameter within [min, max], else the default when absent; bad is a 400. */
+function queryInt(url, name, min, max, fallback) {
+    const raw = url.searchParams.get(name);
+    if (raw === null)
+        return fallback;
+    const n = Number(raw);
+    if (raw === "" || !Number.isInteger(n) || n < min) {
+        throw new HttpError(400, `${name} must be an integer of at least ${min}`);
+    }
+    return Math.min(n, max);
 }
-export function serveReview(state, opts) {
-    const { reviewsDir } = opts;
-    const comments = new Map(state.comments.map((c) => [c.id, c]));
-    const unitIds = new Set(state.units.map((u) => u.id));
-    const draftFile = draftPath(reviewsDir, state.version);
-    const reviewFile = join(reviewsDir, `v${state.version}.json`);
-    let boundPort = 0;
+function sendHtml(res, status, html) {
+    res.writeHead(status, {
+        "content-type": "text/html; charset=utf-8",
+        "cache-control": "no-store",
+    });
+    res.end(html);
+}
+function escapeHtml(text) {
+    return text.replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`);
+}
+/** "just now", "5 min ago", "2 h ago" or "3 days ago". */
+export function ago(ms) {
+    const minutes = Math.floor(ms / 60_000);
+    if (minutes < 1)
+        return "just now";
+    if (minutes < 60)
+        return `${minutes} min ago`;
+    const hours = Math.floor(minutes / 60);
+    if (hours < 24)
+        return `${hours} h ago`;
+    const days = Math.floor(hours / 24);
+    return `${days} day${days === 1 ? "" : "s"} ago`;
+}
+function tildePath(path) {
+    const home = homedir();
+    return path === home || path.startsWith(`${home}/`) ? `~${path.slice(home.length)}` : path;
+}
+function indexPage(rows, now) {
+    const items = rows.map(({ summary: s, openedAt }) => {
+        const mode = s.mode === "walk"
+            ? '<span class="mode walk">code review</span>'
+            : `<span class="mode split">plan review v${s.version}</span>`;
+        const count = `${s.comments} comment${s.comments === 1 ? "" : "s"}`;
+        const repo = escapeHtml(basename(s.repo));
+        return `      <li>
+        <a class="session" href="${s.url}"><span class="repo">${repo}</span> <span class="branch">${escapeHtml(s.branch)}</span></a>
+        ${mode}
+        <span class="muted">${count} · opened ${ago(now - openedAt)}</span>
+        <span class="path muted">${escapeHtml(tildePath(s.repo))}</span>
+      </li>`;
+    });
+    const body = items.length === 0
+        ? `    <section class="empty">
+      <h1>No sessions yet</h1>
+      <p>Run <code>follow-me review</code> to review a plan, or <code>follow-me walk</code> to read a branch someone else wrote. Each one opens here.</p>
+      <p><a href="https://github.com/phanshiyu/follow-me#readme">How follow-me works</a></p>
+    </section>`
+        : `    <h1>Sessions</h1>
+    <ul class="session-index">
+${items.join("\n")}
+    </ul>`;
+    return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <meta name="color-scheme" content="light dark" />
+    <title>follow-me sessions</title>
+    <link rel="stylesheet" href="/style.css" />
+  </head>
+  <body class="index">
+    <header class="topbar"><strong>follow-me</strong></header>
+    <main class="index-main">
+${body}
+    </main>
+  </body>
+</html>
+`;
+}
+/** The file behind a /vendor/ path, or null. Chunk names are checked, so no path escapes. */
+function vendorFile(path) {
+    const part = PRISM_PATH.exec(path)?.[1];
+    if (part !== undefined) {
+        return part === "core" ? PRISM_CORE : new URL(`prism-${part}.min.js`, PRISM_CORE);
+    }
+    if (path === "/vendor/mermaid.mjs")
+        return MERMAID_ENTRY;
+    const chunk = MERMAID_CHUNK.exec(path)?.[1];
+    return chunk === undefined ? null : new URL(`chunks/mermaid.esm.min/${chunk}`, MERMAID_ENTRY);
+}
+async function readUi(name) {
+    try {
+        return await readFile(fileURLToPath(new URL(name, UI_DIR)));
+    }
+    catch (error) {
+        if (isRecord(error) && error["code"] === "ENOENT")
+            throw new HttpError(404, "not found");
+        throw error;
+    }
+}
+async function sendVendor(res, file) {
+    let bytes;
+    try {
+        bytes = await readFile(fileURLToPath(file));
+    }
+    catch (error) {
+        if (isRecord(error) && error["code"] === "ENOENT")
+            throw new HttpError(404, "not found");
+        throw error;
+    }
+    // The bundle only changes with the installed package, and it is several megabytes.
+    res.writeHead(200, {
+        "content-type": "text/javascript; charset=utf-8",
+        "cache-control": "max-age=86400",
+    });
+    res.end(bytes);
+}
+function viewOf(registration, loaded, draft) {
+    const { state, reviewsDir } = loaded;
+    return {
+        registration,
+        loaded,
+        comments: new Map(state.comments.map((c) => [c.id, c])),
+        decisions: new Map(draft.concerns.map((d) => [d.concern, d])),
+        resolved: new Set(draft.resolved),
+        unitIds: new Set(state.units.map((u) => u.id)),
+        concernIds: new Set(state.commits.flatMap((c) => (c.concerns ?? []).map((k) => k.id))),
+        draftFile: draftPath(reviewsDir, state.version),
+        reviewFile: join(reviewsDir, `v${state.version}.json`),
+    };
+}
+function withReplies(comment, replies) {
+    const { replies: _dropped, ...rest } = comment;
+    return replies === undefined || replies.length === 0 ? rest : { ...rest, replies };
+}
+function mintReplyId(taken) {
+    for (;;) {
+        let id = "r_";
+        for (const byte of randomBytes(6))
+            id += BASE32.charAt(byte % 32);
+        if (isReplyId(id) && !taken.has(id))
+            return id;
+    }
+}
+const DEFAULT_POLL_MS = 25_000;
+const MAX_POLL_MS = 60_000;
+const STREAM_PING_MS = 15_000;
+/** One hosted review: its comments, its event log, its autosave chain, and how it ends. */
+function hostSession(id, registration, loaded, draft, load) {
+    const openedAt = Date.now();
+    let view = viewOf(registration, loaded, draft);
+    let finish = () => { };
+    const done = new Promise((resolve) => {
+        finish = resolve;
+    });
+    // The append-only log a watcher long-polls. seq is the position, counted from 1.
+    const events = [];
+    const waiters = new Set();
+    const listeners = new Set();
+    const emit = (body) => {
+        events.push({ ...body, seq: events.length + 1 });
+        for (const wake of [...waiters])
+            wake();
+        for (const listener of [...listeners])
+            listener();
+    };
+    const waitForEvents = (since, timeoutMs, signal) => new Promise((resolve) => {
+        const answer = () => resolve({ seq: events.length, events: events.slice(since) });
+        if (events.length > since || timeoutMs === 0 || signal.aborted)
+            return answer();
+        const wake = () => {
+            clearTimeout(timer);
+            waiters.delete(wake);
+            signal.removeEventListener("abort", wake);
+            answer();
+        };
+        const timer = setTimeout(wake, timeoutMs);
+        waiters.add(wake);
+        signal.addEventListener("abort", wake);
+    });
+    let ending = false;
+    let swapping = false;
+    const open = () => {
+        if (ending)
+            throw new HttpError(409, "this review is already ending");
+        if (swapping)
+            throw new HttpError(409, "the session is switching plan versions; try again");
+    };
     // Writes are chained so two rapid edits never race on the same file.
     let writes = Promise.resolve();
     const saveDraft = () => {
+        const { state } = view.loaded;
+        const file = view.draftFile;
+        const concerns = [...view.decisions.values()];
+        const resolved = [...view.resolved];
         const snapshot = JSON.stringify({
             schema: "follow-me/review-draft@1",
             planVersion: state.version,
-            comments: [...comments.values()],
+            comments: [...view.comments.values()],
+            ...(concerns.length === 0 ? {} : { concerns }),
+            ...(resolved.length === 0 ? {} : { resolved }),
         }, null, 2);
+        const dir = view.loaded.reviewsDir;
         writes = writes.then(async () => {
-            await mkdir(reviewsDir, { recursive: true });
-            await writeAtomic(draftFile, `${snapshot}\n`);
+            await mkdir(dir, { recursive: true });
+            await writeAtomic(file, `${snapshot}\n`);
         });
         return writes;
     };
-    const accept = (comment) => {
-        if (!comment)
-            throw new HttpError(400, "malformed comment");
-        const { anchor } = comment;
-        if (anchor.kind !== "plan" && anchor.commit >= state.commits.length) {
+    const accept = (parsed) => {
+        if (typeof parsed === "string")
+            throw new HttpError(400, `malformed comment: ${parsed}`);
+        if (!COMMENT_ID.test(parsed.id))
+            throw new HttpError(400, "malformed comment: bad id");
+        const { anchor } = parsed;
+        if (anchor.kind !== "plan" && anchor.commit >= view.loaded.state.commits.length) {
             throw new HttpError(400, "anchor commit out of range");
         }
-        if (anchor.kind === "hunk" && !unitIds.has(anchor.unit)) {
+        if (anchor.kind === "hunk" && !view.unitIds.has(anchor.unit)) {
             throw new HttpError(400, "anchor names an unknown unit");
         }
-        return comment;
+        return parsed;
     };
-    return new Promise((resolve, reject) => {
-        const server = createServer((req, res) => {
-            route(req, res).catch((error) => {
-                if (error instanceof HttpError)
-                    return sendJson(res, error.status, { error: error.message });
-                console.error(error);
-                sendJson(res, 500, { error: "internal error" });
-            });
+    const review = () => {
+        const concerns = [...view.decisions.values()];
+        const resolved = [...view.resolved];
+        return {
+            schema: "follow-me/review@1",
+            mode: view.loaded.state.mode,
+            planVersion: view.loaded.state.version,
+            planHash: view.loaded.state.planHash,
+            endedAt: new Date().toISOString(),
+            comments: [...view.comments.values()],
+            ...(concerns.length === 0 ? {} : { concerns }),
+            ...(resolved.length === 0 ? {} : { resolved }),
+        };
+    };
+    const report = (finished) => {
+        const { state } = view.loaded;
+        const units = new Map(state.units.map((u) => [u.id, u]));
+        return renderReport(finished, state.commits, units, {
+            branch: state.anchor.branch,
+            responses: [],
         });
-        async function route(req, res) {
-            const host = req.headers.host ?? "";
-            // Blocks DNS rebinding and cross-site writes: only our own origin may talk to the API.
-            if (host !== `127.0.0.1:${boundPort}` && host !== `localhost:${boundPort}`) {
-                throw new HttpError(403, "unexpected host");
+    };
+    /** Writes reviews/vN.json and its report once, and removes the autosave. */
+    const writeReview = async (finished) => {
+        await writes;
+        await mkdir(view.loaded.reviewsDir, { recursive: true });
+        await writeAtomic(view.reviewFile, `${JSON.stringify(finished, null, 2)}\n`);
+        await writeAtomic(view.reviewFile.replace(/\.json$/, ".md"), report(finished));
+        await rm(view.draftFile, { force: true });
+        return view.reviewFile;
+    };
+    const hasWork = () => view.comments.size > 0 || view.decisions.size > 0;
+    return {
+        id,
+        done,
+        openedAt,
+        get registration() {
+            return view.registration;
+        },
+        summary: () => ({
+            id,
+            url: sessionPath(id),
+            repo: view.loaded.repo,
+            branch: view.loaded.state.anchor.branch,
+            mode: view.loaded.state.mode,
+            version: view.loaded.state.version,
+            comments: view.comments.size,
+        }),
+        snapshot: () => ({
+            ...view.loaded.state,
+            comments: [...view.comments.values()],
+            concerns: [...view.decisions.values()],
+            resolved: [...view.resolved],
+            seq: events.length,
+            previous: view.loaded.previous,
+        }),
+        /** Events after `since`, now and as they happen, until unfollowed or the review ends. */
+        latest: () => events.length,
+        follow: (since, send, stop) => {
+            if (since > events.length) {
+                throw new HttpError(409, `since ${since} is ahead of this session's log (${events.length})`);
             }
-            const origin = req.headers.origin;
-            if (origin !== undefined && origin !== `http://${host}`)
-                throw new HttpError(403, "bad origin");
-            const method = req.method ?? "GET";
-            const path = new URL(req.url ?? "/", "http://localhost").pathname;
-            const asset = method === "GET" ? STATIC_FILES.get(path) : undefined;
-            if (asset) {
-                const bytes = await readFile(fileURLToPath(new URL(asset.file, UI_DIR)));
-                res.writeHead(200, { "content-type": asset.type, "cache-control": "no-store" });
-                res.end(bytes);
-                return;
+            let last = since;
+            const flush = () => {
+                for (const event of events.slice(last)) {
+                    send(event);
+                    last = event.seq;
+                    if (event.type === "ended") {
+                        listeners.delete(flush);
+                        stop();
+                        return;
+                    }
+                }
+            };
+            listeners.add(flush);
+            flush();
+            return () => listeners.delete(flush);
+        },
+        poll: (since, timeoutMs, signal) => {
+            if (since > events.length) {
+                throw new HttpError(409, `since ${since} is ahead of this session's log (${events.length})`);
             }
-            if (method === "GET" && path === "/api/state") {
-                return sendJson(res, 200, { ...state, comments: [...comments.values()] });
+            return waitForEvents(since, timeoutMs, signal);
+        },
+        report: () => report(review()),
+        add: async (raw) => {
+            open();
+            if (!isRecord(raw))
+                throw new HttpError(400, "malformed comment");
+            const commentId = mintCommentId(new Set(view.comments.keys()));
+            const comment = withReplies(accept(parseComment({ ...raw, id: commentId, createdAt: new Date().toISOString() })), undefined);
+            view.comments.set(commentId, comment);
+            emit({ type: "comment", comment });
+            await saveDraft();
+            return commentId;
+        },
+        put: async (target, raw) => {
+            open();
+            const parsed = withReplies(accept(parseComment(raw)), undefined);
+            if (parsed.id !== target)
+                throw new HttpError(400, "comment id does not match the URL");
+            // Replies belong to the conversation, not to the page's copy of the comment.
+            const comment = withReplies(parsed, view.comments.get(target)?.replies);
+            view.comments.set(comment.id, comment);
+            emit({ type: "comment-updated", comment });
+            await saveDraft();
+            return comment;
+        },
+        remove: async (target) => {
+            open();
+            const gone = view.comments.get(target);
+            if (gone === undefined)
+                throw new HttpError(404, "no such comment");
+            view.comments.delete(target);
+            emit({ type: "comment-deleted", id: gone.id });
+            await saveDraft();
+        },
+        reply: async (target, raw) => {
+            open();
+            const comment = view.comments.get(target);
+            if (comment === undefined)
+                throw new HttpError(404, "no such comment");
+            const parsed = parseNewReply(raw);
+            if (typeof parsed === "string")
+                throw new HttpError(400, `malformed reply: ${parsed}`);
+            const taken = new Set([...view.comments.values()].flatMap((c) => c.replies ?? []).map((r) => r.id));
+            const reply = {
+                id: mintReplyId(taken),
+                ...parsed,
+                createdAt: new Date().toISOString(),
+            };
+            view.comments.set(comment.id, { ...comment, replies: [...(comment.replies ?? []), reply] });
+            emit({ type: "reply", commentId: comment.id, reply });
+            await saveDraft();
+            return reply.id;
+        },
+        decide: async (target, raw) => {
+            open();
+            if (!isConcernId(target) || !view.concernIds.has(target)) {
+                throw new HttpError(404, "no such concern in this plan");
             }
-            if (method === "POST" && path === "/api/comments") {
-                const raw = await readJson(req);
-                if (!isRecord(raw))
-                    throw new HttpError(400, "malformed comment");
-                const id = mintCommentId(new Set(comments.keys()));
-                const comment = accept(parseComment({ ...raw, id, createdAt: new Date().toISOString() }));
-                comments.set(id, comment);
-                await saveDraft();
-                return sendJson(res, 201, { id });
+            const decision = parseNewDecision(target, raw);
+            if (typeof decision === "string")
+                throw new HttpError(400, `malformed decision: ${decision}`);
+            view.decisions.set(target, decision);
+            const { concern: concernId, ...rest } = decision;
+            emit({ type: "concern", concernId, ...rest });
+            await saveDraft();
+            return decision;
+        },
+        resolve: async (raw) => {
+            open();
+            const body = isRecord(raw) ? raw : {};
+            const target = body["comment"];
+            const asked = view.loaded.previous?.comments.find((c) => c.id === target);
+            if (asked === undefined || typeof body["resolved"] !== "boolean") {
+                throw new HttpError(400, "expected { comment: <id of a question of the previous version>, resolved }");
             }
-            const target = /^\/api\/comments\/([^/]+)$/.exec(path)?.[1];
-            if (target !== undefined && method === "PUT") {
-                const comment = accept(parseComment(await readJson(req)));
-                if (comment.id !== target)
-                    throw new HttpError(400, "comment id does not match the URL");
-                comments.set(comment.id, comment);
-                await saveDraft();
-                return sendJson(res, 200, comment);
+            if (body["resolved"])
+                view.resolved.add(asked.id);
+            else
+                view.resolved.delete(asked.id);
+            emit({ type: "resolved", commentId: asked.id, resolved: body["resolved"] });
+            await saveDraft();
+            return [...view.resolved];
+        },
+        /**
+         * Moves the session to a newer frozen plan under the same id and URL. The new version loads
+         * first, so a plan that no longer fits leaves the old one untouched; then the old version's
+         * review is finalized if anything was said, and the comment set starts fresh.
+         */
+        swap: async (version, hash) => {
+            open();
+            const { state } = view.loaded;
+            if (version === state.version) {
+                if (hash === state.planHash)
+                    return;
+                throw new HttpError(409, `plan v${version} is already open with another hash`);
             }
-            if (target !== undefined && method === "DELETE") {
-                if (!comments.delete(target))
-                    throw new HttpError(404, "no such comment");
-                await saveDraft();
-                return sendJson(res, 200, { deleted: target });
+            if (version < state.version) {
+                throw new HttpError(409, `plan v${version} is older than the open v${state.version}`);
             }
-            if (method === "POST" && path === "/api/end") {
+            swapping = true;
+            try {
                 await writes;
-                const review = {
-                    schema: "follow-me/review@1",
-                    mode: state.mode,
-                    planVersion: state.version,
-                    planHash: state.planHash,
-                    endedAt: new Date().toISOString(),
-                    comments: [...comments.values()],
-                };
-                await mkdir(reviewsDir, { recursive: true });
-                await writeAtomic(reviewFile, `${JSON.stringify(review, null, 2)}\n`);
-                await rm(draftFile, { force: true });
-                sendJson(res, 200, { saved: reviewFile });
-                res.on("close", () => {
-                    server.close(() => resolve(review));
-                    server.closeAllConnections();
-                });
-                return;
+                const next = await load({ ...view.registration, version, hash, lockToken: null }, view.loaded.release);
+                if (hasWork())
+                    await writeReview(review());
+                else
+                    await rm(view.draftFile, { force: true });
+                view = viewOf({ ...view.registration, version, hash }, next, await loadDraft(next.reviewsDir, version));
+                emit({ type: "version", version, hash });
+            }
+            finally {
+                swapping = false;
+            }
+        },
+        /** Writes reviews/vN.json and vN.md exactly once and releases the session's lock. */
+        end: async () => {
+            open();
+            ending = true;
+            const finished = review();
+            const file = await writeReview(finished);
+            view.loaded.release();
+            emit({ type: "ended", review: file });
+            return { review: finished, file };
+        },
+        finish: (finished) => finish(finished),
+        abandon: () => {
+            view.loaded.release();
+            finish(null);
+        },
+    };
+}
+function sameRegistration(a, b) {
+    return a.dir === b.dir && a.mode === b.mode && a.version === b.version && a.hash === b.hash;
+}
+/**
+ * Starts the server that hosts every review of this user. Sessions live in a registry keyed by
+ * SessionId; each one is served at /s/<id>/ with its API under /s/<id>/api/. The server stops
+ * itself once it has had no session for idleMs.
+ */
+export function startServer(opts) {
+    const registry = new Map();
+    const pending = new Map();
+    let boundPort = 0;
+    let idleTimer;
+    let stopped = false;
+    let markClosed = () => { };
+    const closed = new Promise((resolve) => {
+        markClosed = resolve;
+    });
+    const server = createServer((req, res) => {
+        route(req, res).catch((error) => {
+            if (error instanceof HttpError)
+                return sendJson(res, error.status, { error: error.message });
+            if (error instanceof RegistrationError)
+                return sendJson(res, 409, { error: error.message });
+            console.error(error);
+            sendJson(res, 500, { error: "internal error" });
+        });
+    });
+    const close = () => {
+        if (!stopped) {
+            stopped = true;
+            clearTimeout(idleTimer);
+            for (const session of registry.values())
+                session.abandon();
+            registry.clear();
+            server.close(() => markClosed());
+            server.closeAllConnections();
+        }
+        return closed;
+    };
+    const settle = () => {
+        clearTimeout(idleTimer);
+        if (stopped || registry.size > 0 || pending.size > 0)
+            return;
+        idleTimer = setTimeout(() => void close(), opts.idleMs);
+    };
+    const sessions = () => [...registry.values()].map((s) => s.summary());
+    const register = async (registration) => {
+        if (stopped)
+            throw new RegistrationError("the server is stopping");
+        const id = sessionIdOf(registration.dir);
+        const existing = registry.get(id) ?? (await pending.get(id));
+        if (existing) {
+            if (!sameRegistration(existing.registration, registration)) {
+                const { mode, version } = existing.registration;
+                throw new RegistrationError(`this session is already open as a ${mode === "walk" ? "walk" : "review"} of plan v${version}; end it first`);
             }
+            return { summary: existing.summary(), done: existing.done };
+        }
+        clearTimeout(idleTimer);
+        const loading = opts
+            .load(registration, null)
+            .then(async (loaded) => hostSession(id, registration, loaded, await loadDraft(loaded.reviewsDir, loaded.state.version), opts.load));
+        pending.set(id, loading);
+        try {
+            const session = await loading;
+            registry.set(id, session);
+            return { summary: session.summary(), done: session.done };
+        }
+        finally {
+            pending.delete(id);
+            settle();
+        }
+    };
+    const hosted = (raw) => {
+        const session = isSessionId(raw) ? registry.get(raw) : undefined;
+        if (!session)
+            throw new HttpError(404, "no such session; it ended or never existed");
+        return session;
+    };
+    async function route(req, res) {
+        const host = req.headers.host ?? "";
+        // Blocks DNS rebinding and cross-site writes: only our own origin may talk to the API.
+        if (host !== `127.0.0.1:${boundPort}` && host !== `localhost:${boundPort}`) {
+            throw new HttpError(403, "unexpected host");
+        }
+        const origin = req.headers.origin;
+        if (origin !== undefined && origin !== `http://${host}`)
+            throw new HttpError(403, "bad origin");
+        const method = req.method ?? "GET";
+        const url = new URL(req.url ?? "/", "http://localhost");
+        const path = url.pathname;
+        const asset = method === "GET" ? STATIC_FILE.exec(path)?.[1] : undefined;
+        if (asset !== undefined) {
+            const bytes = await readUi(asset);
+            const type = STATIC_TYPES.get(asset.slice(asset.lastIndexOf(".") + 1));
+            res.writeHead(200, { "content-type": type ?? "text/plain", "cache-control": "no-store" });
+            res.end(bytes);
+            return;
+        }
+        const vendor = method === "GET" ? vendorFile(path) : null;
+        if (vendor)
+            return sendVendor(res, vendor);
+        if (method === "GET" && path === "/") {
+            const rows = [...registry.values()].map((h) => ({
+                summary: h.summary(),
+                openedAt: h.openedAt,
+            }));
+            return sendHtml(res, 200, indexPage(rows, Date.now()));
+        }
+        if (method === "GET" && path === "/api/health") {
+            return sendJson(res, 200, { app: HEALTH_APP, pid: process.pid });
+        }
+        if (method === "GET" && path === "/api/sessions")
+            return sendJson(res, 200, sessions());
+        if (method === "POST" && path === "/api/sessions") {
+            const registration = parseRegistration(await readJson(req));
+            if (!registration)
+                throw new HttpError(400, "malformed registration");
+            const before = registry.has(sessionIdOf(registration.dir));
+            const { summary } = await register(registration);
+            return sendJson(res, before ? 200 : 201, summary);
+        }
+        const match = /^\/s\/([^/]+)(\/.*)?$/.exec(path);
+        if (match === null)
             throw new HttpError(404, "not found");
+        const [, rawId = "", rest] = match;
+        if (rest === undefined && method === "GET") {
+            res.writeHead(308, { location: `/s/${encodeURIComponent(rawId)}/` });
+            res.end();
+            return;
+        }
+        if (method === "GET" && rest === "/") {
+            if (!isSessionId(rawId) || !registry.has(rawId)) {
+                return sendHtml(res, 404, '<!doctype html><html lang="en"><head><meta charset="utf-8" /><meta name="color-scheme" content="light dark" /><title>follow-me</title><link rel="stylesheet" href="/style.css" /></head><body class="index"><header class="topbar"><strong>follow-me</strong></header><main class="index-main"><section class="empty"><h1>This session has ended</h1><p>It finished, or it never existed. <a href="/">All sessions</a></p></section></main></body></html>\n');
+            }
+            return sendHtml(res, 200, await readFile(fileURLToPath(new URL("index.html", UI_DIR)), "utf8"));
+        }
+        const session = hosted(rawId);
+        if (method === "GET" && rest === "/api/state")
+            return sendJson(res, 200, session.snapshot());
+        if (method === "GET" && rest === "/api/events/stream") {
+            const header = Number(req.headers["last-event-id"]);
+            const resume = Number.isInteger(header) && header > 0 ? header : 0;
+            const since = Math.max(queryInt(url, "since", 0, Number.MAX_SAFE_INTEGER, 0), resume);
+            if (since > session.latest())
+                throw new HttpError(409, "since is ahead of this session's log");
+            res.writeHead(200, {
+                "content-type": "text/event-stream; charset=utf-8",
+                "cache-control": "no-cache",
+                connection: "keep-alive",
+            });
+            res.write(": follow-me\n\n");
+            const ping = setInterval(() => res.write(": ping\n\n"), STREAM_PING_MS);
+            const unfollow = session.follow(since, (event) => res.write(`id: ${event.seq}\ndata: ${JSON.stringify(event)}\n\n`), () => res.end());
+            res.on("close", () => {
+                clearInterval(ping);
+                unfollow();
+            });
+            return;
+        }
+        if (method === "GET" && rest === "/api/events") {
+            const abort = new AbortController();
+            res.on("close", () => abort.abort());
+            const since = queryInt(url, "since", 0, Number.MAX_SAFE_INTEGER, 0);
+            const timeout = queryInt(url, "timeout", 0, MAX_POLL_MS, DEFAULT_POLL_MS);
+            return sendJson(res, 200, await session.poll(since, timeout, abort.signal));
+        }
+        if (method === "GET" && rest === "/api/report") {
+            res.writeHead(200, { "content-type": "text/markdown; charset=utf-8" });
+            res.end(session.report());
+            return;
+        }
+        if (method === "POST" && rest === "/api/version") {
+            const body = await readJson(req);
+            const version = isRecord(body) ? body["version"] : undefined;
+            const hash = isRecord(body) ? body["hash"] : undefined;
+            if (!isPlanVersion(version) || typeof hash !== "string" || hash === "") {
+                throw new HttpError(400, "expected { version, hash }");
+            }
+            await session.swap(version, hash);
+            return sendJson(res, 200, session.summary());
+        }
+        if (method === "POST" && rest === "/api/resolved") {
+            return sendJson(res, 200, { resolved: await session.resolve(await readJson(req)) });
+        }
+        const replies = /^\/api\/comments\/([^/]+)\/replies$/.exec(rest ?? "")?.[1];
+        if (replies !== undefined && method === "POST") {
+            return sendJson(res, 201, { id: await session.reply(replies, await readJson(req)) });
+        }
+        const concern = /^\/api\/concerns\/([^/]+)$/.exec(rest ?? "")?.[1];
+        if (concern !== undefined && method === "POST") {
+            return sendJson(res, 200, await session.decide(concern, await readJson(req)));
+        }
+        if (method === "POST" && rest === "/api/comments") {
+            return sendJson(res, 201, { id: await session.add(await readJson(req)) });
+        }
+        const target = /^\/api\/comments\/([^/]+)$/.exec(rest ?? "")?.[1];
+        if (target !== undefined && method === "PUT") {
+            return sendJson(res, 200, await session.put(target, await readJson(req)));
+        }
+        if (target !== undefined && method === "DELETE") {
+            await session.remove(target);
+            return sendJson(res, 200, { deleted: target });
         }
-        server.on("error", reject);
-        server.listen(opts.port ?? 0, "127.0.0.1", () => {
+        if (method === "POST" && rest === "/api/end") {
+            const { review, file } = await session.end();
+            registry.delete(session.id);
+            sendJson(res, 200, { saved: file });
+            res.on("close", () => {
+                session.finish(review);
+                settle();
+            });
+            return;
+        }
+        throw new HttpError(404, "not found");
+    }
+    return new Promise((resolve, reject) => {
+        server.once("error", (error) => {
+            if (isRecord(error) && error["code"] === "EADDRINUSE")
+                reject(new PortInUseError(opts.port));
+            else
+                reject(error);
+        });
+        server.listen(opts.port, "127.0.0.1", () => {
             const address = server.address();
             if (!address || typeof address === "string")
                 return reject(new Error("server has no port"));
             boundPort = address.port;
-            const url = `http://127.0.0.1:${boundPort}/`;
-            const label = state.mode === "walk" ? "code review" : "review";
-            process.stdout.write(`follow-me ${label}: ${url}\n`);
-            opts.onListen?.(url);
-            if (opts.open)
-                openBrowser(url);
+            settle();
+            resolve({
+                port: boundPort,
+                url: `http://127.0.0.1:${boundPort}/`,
+                register,
+                sessions,
+                close,
+                closed,
+            });
         });
     });
 }