@gavin-hu/my-pi-agent 0.18.0 → 0.19.0

package/lib/board/store.ts

@@ -0,0 +1,310 @@
+/**
+ * The board store: one directory of card files per repository, and the only code
+ * that writes one.
+ *
+ * A board is a directory — `<agentDir>/board/<repo-key>/cards/0004.json` — so a
+ * reader needs no index, no daemon, and no dependency; the listing *is* the
+ * index. The key comes from `lib/repo-key.ts`, so every worktree of one repository
+ * shares one board, and a directory outside git keys on itself.
+ *
+ * Two writes race safely without a lock. **Create** hard-links a temporary file
+ * onto the target name, which fails when the name is taken, so two adds cannot
+ * share an id and the loser simply retries with the next one. **Update** re-reads,
+ * re-checks the operation's preconditions, and renames over the old file, so a
+ * card that changed underneath is re-evaluated rather than overwritten: an
+ * operation says "apply when this holds", never "force this state".
+ *
+ * A write reads the whole board once, because `rules.ts` needs another card to answer
+ * three of its questions: is this dependency finished, would this link close a loop,
+ * and does anything wait on the card being dropped. The listing is the index here —
+ * a board is tens of files, so the read is cheaper than the second source of truth a
+ * cached index would be.
+ *
+ * Nothing prunes. A `done` card is history, the page shows the store's size, and
+ * `drop` is the only deletion.
+ */
+
+import { link, mkdir, readFile, readdir, rename, rm, stat, unlink, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { getAgentDir, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { resolveEffectiveCwd } from "../env.ts";
+import { hasErrorCode, messageOf } from "../errors.ts";
+import { shortenPath } from "../format.ts";
+import { repoKeyFor } from "../repo-key.ts";
+import { type Card, CARD_STATUSES, cardRef, isCard, type Priority, priorityRank } from "./card.ts";
+import { indexOf } from "./links.ts";
+import { type Actor, applyOp, type CardOp, createCard } from "./rules.ts";
+
+/** The directory under the agent directory that holds every board. */
+export const BOARD_DIR_NAME = "board";
+
+/** The subdirectory one board's cards live in. */
+export const CARDS_DIR_NAME = "cards";
+
+/** Card files are the user's work; only their owner reads them. */
+const FILE_MODE = 0o600;
+
+/** A board directory is one session's private state. */
+const DIR_MODE = 0o700;
+
+/** An in-flight temp file older than this was left by a process that died. */
+const TEMP_STALE_MS = 60 * 60 * 1_000;
+
+/** How many times an id collision or a changed card is retried before giving up. */
+const ATTEMPTS = 4;
+
+/** A card to add. The fields are already normalized by `card.ts`. */
+export interface CreateInput {
+	title: string;
+	paths: string[];
+	note?: string;
+	/** Absent is `normal`, so an add that says nothing about urgency says the ordinary thing. */
+	priority?: Priority;
+}
+
+/** What a mutation did, or why it was refused. */
+export type MutateResult =
+	| { ok: true; card: Card; changed: boolean; dropped: boolean }
+	| { ok: false; error: string; card?: Card };
+
+/** One repository's board, as the runtime, the router, and the tool use it. */
+export interface BoardStore {
+	/** The board's own directory, for `where` and for a refusal that names it. */
+	readonly dir: string;
+	/** Create the directories and sweep a temp file a dead process left. */
+	ensure(): Promise<void>;
+	/** Every card, in lane order: todo, doing, blocked, done. */
+	list(): Promise<Card[]>;
+	/** One card by its unpadded id, or undefined when it is not there. */
+	read(id: string): Promise<Card | undefined>;
+	/** Add a card, allocating the next id. */
+	create(input: CreateInput, actor: Actor, now: number): Promise<Card>;
+	/** Apply one operation, re-checking it if the card changed while it was read. */
+	mutate(id: string, op: CardOp, actor: Actor, now: number): Promise<MutateResult>;
+	/** Bytes the store occupies on disk. */
+	bytes(): Promise<number>;
+	/** A short, user-facing name for the directory. */
+	where(): string;
+}
+
+/** Where one repository's board lives. */
+export function boardDirFor(agentDir: string, key: string): string {
+	return join(agentDir, BOARD_DIR_NAME, key);
+}
+
+/** The board for `cwd`'s repository. The one construction point. */
+export async function openBoard(
+	pi: Pick<ExtensionAPI, "exec">,
+	cwd: string,
+	options: { agentDir?: string } = {},
+): Promise<BoardStore> {
+	const agentDir = options.agentDir ?? getAgentDir();
+	// A tool receives the session's cwd, not the worktree the user entered; the
+	// environment carries the active root, so the two are reconciled before the
+	// repository lookup — the same path `plan` and `session-bus` take.
+	const repo = await repoKeyFor(pi, resolveEffectiveCwd(cwd));
+	return createStore(boardDirFor(agentDir, repo.key));
+}
+
+/** Build a store over one directory. Exported for tests and for a second backend. */
+export function createStore(dir: string): BoardStore {
+	const cardsDir = join(dir, CARDS_DIR_NAME);
+
+	const ensure = async (): Promise<void> => {
+		await mkdir(cardsDir, { recursive: true, mode: DIR_MODE });
+		await sweepTemps(cardsDir);
+	};
+
+	const list = async (): Promise<Card[]> => {
+		const entries = await readdirSafe(cardsDir);
+		const cards: Card[] = [];
+		for (const entry of entries) {
+			const card = await readCardFile(cardsDir, entry);
+			if (card) cards.push(card);
+		}
+		return sortForLane(cards);
+	};
+
+	const read = async (id: string): Promise<Card | undefined> => {
+		return readCardFile(cardsDir, fileNameFor(id));
+	};
+
+	const create = async (input: CreateInput, actor: Actor, now: number): Promise<Card> => {
+		await ensure();
+		let lastError: unknown;
+		for (let attempt = 0; attempt < ATTEMPTS; attempt++) {
+			const id = await nextCardId(cardsDir);
+			const card = createCard(id, input, actor, now);
+			const temp = tempPath(cardsDir);
+			await writeFile(temp, serialize(card), { mode: FILE_MODE });
+			try {
+				// The exclusive create: two adds cannot produce one card, and the
+				// loser retries with the id it just learned was taken.
+				await link(temp, join(cardsDir, fileNameFor(id)));
+				return card;
+			} catch (error) {
+				lastError = error;
+				if (!hasErrorCode(error, "EEXIST")) throw error;
+			} finally {
+				await rm(temp, { force: true });
+			}
+		}
+		throw new Error(`The board could not allocate a card id (${messageOf(lastError)}).`);
+	};
+
+	const mutate = async (id: string, op: CardOp, actor: Actor, now: number): Promise<MutateResult> => {
+		let changedUnderneath = false;
+		for (let attempt = 0; attempt < ATTEMPTS; attempt++) {
+			const card = await read(id);
+			if (!card) {
+				return {
+					ok: false,
+					error: changedUnderneath ? `${cardRef(id)} was dropped.` : `${cardRef(id)} does not exist.`,
+				};
+			}
+			// The preconditions are checked against the card as it is *now*, and against the
+			// board as it is now, so an operation re-applied to a card that changed is refused
+			// rather than forced.
+			const result = applyOp(card, op, actor, now, indexOf(await list()));
+			if (!result.ok) return { ok: false, error: result.error, card };
+			if (!result.changed) return { ok: true, card: result.card, changed: false, dropped: false };
+			if (op.kind === "drop") {
+				await rm(join(cardsDir, fileNameFor(id)), { force: true });
+				return { ok: true, card: result.card, changed: true, dropped: true };
+			}
+			// Last look before the rename: a writer that landed in between is the
+			// re-read the next pass applies against.
+			const current = await read(id);
+			if (!current || current.rev !== card.rev) {
+				changedUnderneath = true;
+				continue;
+			}
+			await writeCardFile(cardsDir, id, result.card);
+			return { ok: true, card: result.card, changed: true, dropped: false };
+		}
+		return {
+			ok: false,
+			error: `${cardRef(id)} kept changing while it was written; read it again.`,
+			card: await read(id),
+		};
+	};
+
+	const bytes = async (): Promise<number> => {
+		const entries = await readdirSafe(cardsDir);
+		let total = 0;
+		for (const entry of entries) {
+			if (!CARD_FILE.test(entry)) continue;
+			const info = await stat(join(cardsDir, entry)).catch(() => undefined);
+			if (info) total += info.size;
+		}
+		return total;
+	};
+
+	return { dir, ensure, list, read, create, mutate, bytes, where: () => shortenPath(dir) };
+}
+
+/** `<id>.json`, zero-padded to four digits so a directory lists in card order. */
+function fileNameFor(id: string): string {
+	return `${id.padStart(4, "0")}.json`;
+}
+
+/** The card files the reader accepts. */
+const CARD_FILE = /^(\d{4,})\.json$/;
+
+/** One card file, or undefined when it is not a card this build trusts. */
+async function readCardFile(cardsDir: string, entry: string): Promise<Card | undefined> {
+	const match = CARD_FILE.exec(entry);
+	if (!match) return undefined;
+	const text = await readFile(join(cardsDir, entry), "utf-8").catch(() => undefined);
+	if (text === undefined) return undefined;
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(text);
+	} catch {
+		return undefined;
+	}
+	if (!isCard(parsed)) return undefined;
+	// The file name is the id's canonical spelling: a padded id inside the record
+	// (or a record moved under another name) is a disagreement, not a card.
+	if (parsed.id !== String(Number(match[1]))) return undefined;
+	return parsed;
+}
+
+/** `1`, `2`, `3` … as the highest existing id plus one. */
+async function nextCardId(cardsDir: string): Promise<string> {
+	const entries = await readdirSafe(cardsDir);
+	let highest = 0;
+	for (const entry of entries) {
+		const match = CARD_FILE.exec(entry);
+		if (match) highest = Math.max(highest, Number(match[1]));
+	}
+	return String(highest + 1);
+}
+
+/** Write one card: a temp file in the same directory, then a rename over the old one. */
+async function writeCardFile(cardsDir: string, id: string, card: Card): Promise<void> {
+	const temp = tempPath(cardsDir);
+	await writeFile(temp, serialize(card), { mode: FILE_MODE });
+	const target = join(cardsDir, fileNameFor(id));
+	try {
+		await rename(temp, target);
+	} catch (error) {
+		// Windows refuses a rename onto an open file; removing first is the fallback
+		// the platform needs, and the read above still bounds what can be lost.
+		if (!hasErrorCode(error, "EPERM") && !hasErrorCode(error, "EACCES") && !hasErrorCode(error, "EEXIST")) {
+			await rm(temp, { force: true });
+			throw error;
+		}
+		await rm(target, { force: true });
+		await rename(temp, target);
+	}
+}
+
+/** One card's bytes, ending in a newline so the file reads well in an editor. */
+function serialize(card: Card): string {
+	return `${JSON.stringify(card, null, "\t")}\n`;
+}
+
+/** A temp path in the cards directory: never matched by the reader's own pattern. */
+function tempPath(cardsDir: string): string {
+	return join(cardsDir, `.tmp-${process.pid}-${Math.random().toString(16).slice(2, 10)}`);
+}
+
+/** Remove a temp file a process that died mid-write left behind. */
+async function sweepTemps(cardsDir: string): Promise<void> {
+	const entries = await readdirSafe(cardsDir);
+	const cutoff = Date.now() - TEMP_STALE_MS;
+	for (const entry of entries) {
+		if (!entry.startsWith(".tmp-")) continue;
+		const path = join(cardsDir, entry);
+		const info = await stat(path).catch(() => undefined);
+		if (info && info.mtimeMs < cutoff) await unlink(path).catch(() => undefined);
+	}
+}
+
+async function readdirSafe(dir: string): Promise<string[]> {
+	return readdir(dir).catch((error: unknown) => {
+		if (hasErrorCode(error, "ENOENT")) return [];
+		throw error;
+	});
+}
+
+/**
+ * Lane order, then the lead's order inside it, then oldest first, with the id as the
+ * tie-break.
+ *
+ * Priority sorts inside a lane rather than beside it: a `high` card in Done is still
+ * history, and a lane that mixed the two would have to say so in its head.
+ */
+function sortForLane(cards: Card[]): Card[] {
+	const lane = (card: Card): number => CARD_STATUSES.indexOf(card.status);
+	return cards.sort((a, b) => {
+		const byLane = lane(a) - lane(b);
+		if (byLane !== 0) return byLane;
+		const byPriority = priorityRank(a) - priorityRank(b);
+		if (byPriority !== 0) return byPriority;
+		const byAge = a.updatedAt - b.updatedAt;
+		if (byAge !== 0) return byAge;
+		return Number(a.id) - Number(b.id);
+	});
+}

package/lib/board/view.ts

@@ -0,0 +1,150 @@
+/**
+ * The snapshot: the one shape the page knows, built on the server.
+ *
+ * The browser is a dumb renderer over this record, so the lanes, the counts, the
+ * rollup, and the store's size are decided in one place and a client cannot invent
+ * a state the model surface would not report. `sig` is what makes a push cheap:
+ * the page is re-sent only when a card's revision moved.
+ *
+ * `where` is the store's own path, shortened, so a reader can tell which directory
+ * a shared board is filed under — and so nothing here needs a "remote" variant that
+ * no backend produces.
+ *
+ * Pure: the caller supplies the cards, the clock, and the sizes it read.
+ */
+
+import { type RosterSession, rosterStateOf } from "../session-roster.ts";
+import { type Card, CARD_STATUSES, type CardStatus, signatureOf } from "./card.ts";
+import type { Actor } from "./rules.ts";
+import { buildRound, type RoundSummary } from "./round.ts";
+
+/** One session on the repository's bus, as the Team tab lists it. */
+export interface ViewTeammate {
+	label: string;
+	/** `live` while its heartbeat holds, `quiet` once the record has aged out. */
+	state: "live" | "quiet";
+	/** When it last proved it was there. */
+	seen: number;
+	/** Messages waiting in its inbox. */
+	mail: number;
+	/** Whether it is listening for mail; absent means its record does not say so. */
+	listening?: boolean;
+	/** Whether this is the session the page writes as. */
+	you: boolean;
+}
+
+/** One lane and the cards in it, in the order the page draws them. */
+export interface ViewLane {
+	status: CardStatus;
+	cards: Card[];
+}
+
+/** The per-lane tallies the toolbar shows. */
+export interface ViewCounts {
+	total: number;
+	todo: number;
+	doing: number;
+	blocked: number;
+	done: number;
+}
+
+/** Everything the page is allowed to know. */
+export interface BoardView {
+	/** The session a page write is made as — the page's seat, never the browser. */
+	me: { id?: string; label: string };
+	/** The session the page is served from, when the page knows it: who is reading. */
+	session?: { id?: string; label: string };
+	lanes: ViewLane[];
+	counts: ViewCounts;
+	round: RoundSummary;
+	/**
+	 * The sessions on this repository's bus, or absent when there is no bus here.
+	 *
+	 * Absent is not empty: a page with no roster cannot say who is around, while an
+	 * empty one can say nobody is — and the tab draws those two answers differently.
+	 */
+	teammates?: ViewTeammate[];
+	/** Bytes the store occupies, so a board that is never pruned says so. */
+	bytes: number;
+	/** Changes when a card's revision, a teammate's state, or its mail does. */
+	sig: string;
+	/** The store's directory, shortened. */
+	where: string;
+}
+
+/** What the server read before building one snapshot. */
+export interface ViewInput {
+	me: Actor;
+	/**
+	 * The session the page is served from, when it has one.
+	 *
+	 * The page writes as its seat — a fixed name — so the reader's own row on the Team
+	 * tab is marked from the session, not from `me`: the seat is what a card records,
+	 * and the session is who is looking.
+	 */
+	session?: Actor;
+	cards: readonly Card[];
+	now: number;
+	bytes: number;
+	where: string;
+	/** The bus's records, when the page could read them at all. */
+	roster?: readonly RosterSession[];
+}
+
+/** Build the page's snapshot. */
+export function buildView(input: ViewInput): BoardView {
+	const lanes = CARD_STATUSES.map((status) => ({
+		status,
+		cards: input.cards.filter((card) => card.status === status),
+	}));
+	const reader = input.session ?? input.me;
+	const teammates = input.roster === undefined ? undefined : teammatesOf(input.roster, reader.label, input.now);
+	return {
+		me: input.me.id === undefined ? { label: input.me.label } : { id: input.me.id, label: input.me.label },
+		...(input.session === undefined ? {} : { session: input.session }),
+		lanes,
+		counts: countOf(lanes),
+		round: buildRound(input.cards, input.now),
+		...(teammates === undefined ? {} : { teammates }),
+		bytes: input.bytes,
+		// The roster enters the signature at its coarse facts only: a heartbeat every ten
+		// seconds is not news, while a join, a quiet and a letter are.
+		sig: signatureOf(input.cards) + rosterSignature(teammates),
+		where: input.where,
+	};
+}
+
+/** The roster as the page shows it, ordered so a repaint never reorders it. */
+function teammatesOf(roster: readonly RosterSession[], meLabel: string, now: number): ViewTeammate[] {
+	return roster
+		.map((session) => ({
+			label: session.label,
+			state: rosterStateOf(session, now),
+			seen: session.lastSeen,
+			mail: session.mail,
+			// A record that does not say is not a promise either way, so the fact is left out
+			// rather than drawn as "not listening".
+			...(session.watching === undefined ? {} : { listening: session.watching.armed }),
+			you: session.label.toLowerCase() === meLabel.toLowerCase(),
+		}))
+		.sort((a, b) => a.label.localeCompare(b.label));
+}
+
+/** What a frame must know about the roster; `seen` is left out on purpose. */
+function rosterSignature(teammates: readonly ViewTeammate[] | undefined): string {
+	if (teammates === undefined) return "";
+	return (
+		"|" +
+		teammates.map((teammate) => `${teammate.label}:${teammate.state}:${teammate.mail}:${teammate.listening}`).join(",")
+	);
+}
+
+/** The tallies, summed from the lanes so the two can never disagree. */
+function countOf(lanes: readonly ViewLane[]): ViewCounts {
+	const counts: ViewCounts = { total: 0, todo: 0, doing: 0, blocked: 0, done: 0 };
+	for (const lane of lanes) {
+		counts[lane.status] = lane.cards.length;
+		counts.total += lane.cards.length;
+	}
+	return counts;
+}

package/lib/errors.ts

@@ -1,12 +1,20 @@
 /**
- * One error-to-line helper for an unknown thrown value.
+ * Two helpers for an unknown thrown value: what to say about it, and whether it is the
+ * failure a caller was waiting for.
  *
- * Extensions report a rejected promise, a failed child process, and a parser
- * error the same way: an `Error` yields its message, and anything else is
- * stringified. Kept value-only so every extension has one definition.
+ * Extensions report a rejected promise, a failed child process, and a parser error the
+ * same way: an `Error` yields its message, and anything else is stringified. A `code` —
+ * `EEXIST`, `EPERM` — is what a filesystem write branches on, and reading it off an
+ * unknown value is the same boundary, so it lives here too. Kept value-only so every
+ * caller has one definition.
  */
 
 /** A user-facing message for an unknown thrown value. */
 export function messageOf(error: unknown): string {
 	return error instanceof Error ? error.message : String(error);
 }
+
+/** Whether an unknown thrown value carries one errno code, such as `EEXIST`. */
+export function hasErrorCode(error: unknown, code: string): boolean {
+	return typeof error === "object" && error !== null && (error as { code?: unknown }).code === code;
+}

package/lib/format.ts

@@ -166,3 +166,16 @@ export function shortenPath(path: string, home: string = homedir()): string {
 	if (normalized === root) return "~";
 	return normalized.startsWith(`${root}/`) ? `~${normalized.slice(root.length)}` : normalized;
 }
+
+/** A compact byte size for a listing or a report: `68 B`, `12.4 kB`, `1.5 MB`. */
+export function formatSize(bytes: number): string {
+	if (bytes < 1024) return `${bytes} B`;
+	const units = ["kB", "MB", "GB", "TB"];
+	let value = bytes;
+	let index = -1;
+	do {
+		value /= 1024;
+		index++;
+	} while (value >= 1024 && index < units.length - 1);
+	return `${value < 10 ? value.toFixed(1) : Math.round(value)} ${units[index]}`;
+}

package/lib/http/guard.ts

@@ -0,0 +1,112 @@
+/**
+ * The request guards both loopback servers apply before a route runs: the method
+ * allowlist, the `Host` allowlist, the cross-origin refusal, and — for a server
+ * that takes JSON — the content-type check.
+ *
+ * These were the `plan` review server's own three helpers until a second
+ * mutating page needed them. A guard is a policy, and two copies of a policy are
+ * how a `Host` rule or an origin rule drifts apart, so the sentences the client
+ * reads and the order they are checked in live here once.
+ *
+ * Each guard answers `undefined` when the request may proceed and the response to
+ * send instead when it may not, so a router reads as a chain of refusals.
+ */
+
+import { jsonHeaders } from "./headers.ts";
+import { hostHeaderName, isAllowedHostHeader } from "./router.ts";
+import { jsonError, type ServeResponse } from "./response.ts";
+
+/** The methods a loopback server answers unless it says otherwise. */
+export const PAGE_METHODS: readonly string[] = ["GET", "HEAD", "POST"];
+
+/** The 405 for a route that only accepts POST, or nothing when the method is right. */
+export function postOnly(method: string, what: string): ServeResponse | undefined {
+	if (method.toUpperCase() === "POST") return undefined;
+	return jsonError(405, `Use POST to ${what}.`);
+}
+
+/**
+ * The 403 for a state-changing request another site made, or nothing when the
+ * caller may proceed.
+ *
+ * A browser sends `Origin` on every state-changing request and `Sec-Fetch-Site`
+ * with its own classification; a request with neither is a script or a test,
+ * which has no ambient credential to abuse. A present `Origin` must name the host
+ * the request was addressed to, so a page served by another site cannot drive
+ * this one through a victim's browser.
+ */
+export function checkOrigin(headers: Record<string, string | string[] | undefined>): ServeResponse | undefined {
+	const site = headers["sec-fetch-site"];
+	if (typeof site === "string" && site !== "" && site !== "same-origin" && site !== "none") {
+		return jsonError(403, "Cross-origin request refused.");
+	}
+	const origin = headers.origin;
+	if (origin === undefined) return undefined;
+	if (typeof origin !== "string" || origin === "") return jsonError(403, "Unexpected Origin header.");
+	let parsed: URL;
+	try {
+		parsed = new URL(origin);
+	} catch {
+		return jsonError(403, "Unexpected Origin header.");
+	}
+	const host = headers.host;
+	if (typeof host !== "string" || hostHeaderName(parsed.host) !== hostHeaderName(host)) {
+		return jsonError(403, "Cross-origin request refused.");
+	}
+	return undefined;
+}
+
+/**
+ * The 415 for a state-changing body that is not JSON, or nothing when it is.
+ *
+ * A server that only reads JSON refuses anything else early: an HTML form post
+ * and a `text/plain` body cannot reach the parser, so the request cannot be
+ * mounted cross-origin by a form or a `<script>` tag.
+ */
+export function requireJsonBody(contentType: string | string[] | undefined): ServeResponse | undefined {
+	const value = Array.isArray(contentType) ? contentType[0] : contentType;
+	if (typeof value === "string" && /^application\/json\s*(;|$)/i.test(value.trim())) return undefined;
+	return jsonError(415, "The request body must be JSON.");
+}
+
+/** What a server answers, and to which host names. */
+export interface EnvelopeOptions {
+	/** The raw request method. */
+	method: string;
+	/** The raw request headers. */
+	headers: Record<string, string | string[] | undefined>;
+	/** The host names this server answers to now. */
+	hosts: readonly string[];
+	/** The methods it serves; `PAGE_METHODS` unless a route set needs more. */
+	allowed?: readonly string[];
+}
+
+/**
+ * The 405 or 403 a request deserves before any route runs, or nothing when the
+ * envelope is acceptable.
+ *
+ * `Host` fails closed: a missing or non-string header is refused too, not just a
+ * foreign one, so the DNS-rebinding guard cannot be skipped by omitting it. Every
+ * method that is not a read is also checked for a foreign origin.
+ */
+export function envelopeRefusal(options: EnvelopeOptions): ServeResponse | undefined {
+	const allowed = options.allowed ?? PAGE_METHODS;
+	const upper = options.method.toUpperCase();
+	if (!allowed.includes(upper)) {
+		return {
+			...jsonError(405, `Only ${joinMethods(allowed)} are served.`),
+			headers: { ...jsonHeaders(), Allow: allowed.join(", ") },
+		};
+	}
+	if (!isAllowedHostHeader(options.headers, { hosts: options.hosts, required: true })) {
+		return jsonError(403, "Unexpected Host header.");
+	}
+	const reads = upper === "GET" || upper === "HEAD";
+	return reads ? undefined : checkOrigin(options.headers);
+}
+
+/** `GET, HEAD, and POST` — the list as a sentence a person reads. */
+function joinMethods(methods: readonly string[]): string {
+	if (methods.length <= 1) return methods.join("");
+	return `${methods.slice(0, -1).join(", ")}, and ${methods.at(-1)}`;
+}

package/lib/http/index.ts

@@ -1,13 +1,24 @@
 /**
- * The loopback HTTP layer shared by `file-browse` and `plan`: the response
- * shape, the header policy, the request-envelope helpers, and the socket seam.
+ * The loopback HTTP layer shared by `file-browse`, `plan`, and `board`: the
+ * response shape, the header policy, the request-envelope helpers and the
+ * guards built on them, the one server entry, and the socket seam behind it.
+ *
+ * Import from here rather than a leaf module, so the layer reads as one kit. An
+ * extension imports {@link serveLoopback} and never `./server.ts`: a hand-built
+ * `node:http` server beside this one is how the close path and the idle grace
+ * start to differ again. The same rule covers the guards: `plan` and `board` both
+ * serve a page that can write, so the `Host`, origin, and JSON rules are
+ * {@link envelopeRefusal} and {@link requireJsonBody} rather than two copies, and
+ * the credential a page carries is {@link mintToken} / {@link tokenMatches}.
  *
- * Import from here rather than a leaf module, so the layer reads as one kit.
  * Value-only, like the rest of `lib/`: the only state is what a returned closure
- * carries (`createCloser`).
+ * carries (`createCloser`, `serveLoopback`).
  */
 
+export * from "./guard.ts";
 export * from "./headers.ts";
 export * from "./response.ts";
 export * from "./router.ts";
-export * from "./server.ts";
+export * from "./serve.ts";
+export * from "./sink.ts";
+export * from "./token.ts";