import { createHash, randomUUID } from "node:crypto"; import { createReadStream, type Dirent, lstatSync, readdirSync, readFileSync, realpathSync, rmSync, } from "node:fs"; import { createServer, type IncomingMessage, type Server, type ServerResponse, } from "node:http"; import path from "node:path"; import { withFileMutationQueue } from "@earendil-works/pi-coding-agent"; import { BOARD_PATH, type BoardItemState, type BoardProposal, type BoardState, boardStateFor, readBoardState, updateBoardState, writeBoardState, } from "./board-state.ts"; import { openEditableFile } from "./open-editor.ts"; import { writePlanStatus } from "./plan-status.ts"; import { loadProjectIndex, type ProjectIndex } from "./project-index.ts"; const BODY_LIMIT = 64 * 1024; const SIGNATURE_BYTE_LIMIT = 1024 * 1024; const COOKIE = "the_system_board"; const STATES = ["todo", "done", "open", "dropped"] as const; const STATUSES = ["draft", "approved"] as const; export type BookServer = Readonly<{ url: string; close(): void }>; export type BoardSignature = Readonly<{ documents: string; board: string }>; export type BookRenderer = ( index: ProjectIndex, board: BoardState, proposals: readonly BoardProposal[], revision: string, ) => Readonly<{ directory: string }>; export type BoardExec = (id: string) => void | Promise; export function boardSignature(root: string): BoardSignature { const documents = createHash("sha256"); const board = createHash("sha256"); const systemRoot = path.join(root, ".system"); for (const file of governedFiles(systemRoot)) { const relative = path.relative(systemRoot, file).split(path.sep).join("/"); const digest = relative === "board.json" ? board : documents; digest.update(`${relative}\u0000`); const stats = lstatSync(file, { throwIfNoEntry: false }); if (!stats?.isFile()) continue; if (stats.size > SIGNATURE_BYTE_LIMIT) { digest.update(`${stats.size}:${stats.mtimeMs}`); continue; } digest.update(readFileSync(file)); } return { documents: documents.digest("hex"), board: board.digest("hex") }; } function governedFiles(directory: string): readonly string[] { let entries: Dirent[]; try { entries = readdirSync(directory, { withFileTypes: true }); } catch { return []; } return entries .sort((left, right) => left.name.localeCompare(right.name)) .flatMap((entry) => { const target = path.join(directory, entry.name); if (entry.isSymbolicLink()) return []; if (entry.isDirectory()) return governedFiles(target); return entry.isFile() ? [target] : []; }); } type BookSite = Readonly<{ signature: BoardSignature; directory: string; board: BoardState; proposals: string; routes: ReadonlyMap; }>; const proposalSignature = (proposals: Map) => JSON.stringify([...proposals.values()]); export async function startBookServer( root: string, proposals: Map, render: BookRenderer, onExec?: BoardExec, ): Promise { const token = `${randomUUID()}-${randomUUID()}`; const cookieName = `${COOKIE}_${token.slice(0, 8)}`; const stale = new Set(); let open = true; const assertOpen = () => { if (!open) throw new Error("System book server is closed"); }; let site = renderSite(root, proposals, render); let renderError: string | undefined; const ensureSite = (): BookSite => { assertOpen(); const signature = boardSignature(root); if ( signature.documents === site.signature.documents && signature.board === site.signature.board && proposalSignature(proposals) === site.proposals ) { renderError = undefined; return site; } const previous = site; try { site = renderSite(root, proposals, render, signature); renderError = undefined; } catch (error) { renderError = error instanceof Error ? error.message : String(error); return previous; } discard(previous.directory, stale); return site; }; let mutation = Promise.resolve(); const enqueue = (work: () => T | Promise): Promise => { const run = () => { assertOpen(); return work(); }; const result = mutation.then(run, run); mutation = result.then( () => undefined, () => undefined, ); return result; }; const server: Server = createServer((request, response) => { void dispatch(request, response, { root, proposals, token, cookieName, enqueue, ensureSite, currentSite: () => site, renderProblem: () => renderError, assertOpen, ...(onExec ? { onExec } : {}), }); }); try { await new Promise((resolve, reject) => { server.once("error", reject); server.listen(0, "127.0.0.1", () => { server.off("error", reject); resolve(); }); }); } catch (error) { discard(site.directory, stale); throw error; } const address = server.address(); if (!address || typeof address === "string") throw new Error("Failed to bind System board server"); return { url: `http://127.0.0.1:${address.port}/?k=${token}`, close() { open = false; server.closeAllConnections(); server.close(); discard(site.directory, stale); for (const directory of [...stale]) discard(directory, stale); }, }; } function renderSite( root: string, proposals: Map, render: BookRenderer, signature = boardSignature(root), ): BookSite { const index = loadProjectIndex(root); const board = readBoardState(index.root, index.prefix); const output = render( index, board, [...proposals.values()].sort((left, right) => left.id.localeCompare(right.id), ), signature.documents, ); return { signature, directory: output.directory, board, proposals: proposalSignature(proposals), routes: new Map([ ...index.documents.map( (document) => [document.path, document.metadata.id] as const, ), ...["SYSTEM", "MISSION", "RULES"].map( (name) => [`.system/${name}.md`, `CORE-${name}`] as const, ), ]), }; } function discard(directory: string, stale: Set): void { try { rmSync(directory, { recursive: true, force: true }); stale.delete(directory); } catch { stale.add(directory); } } type DispatchState = Readonly<{ root: string; proposals: Map; token: string; cookieName: string; enqueue(work: () => T | Promise): Promise; ensureSite(): BookSite; assertOpen(): void; currentSite(): BookSite; renderProblem(): string | undefined; onExec?: BoardExec; }>; async function dispatch( request: IncomingMessage, response: ServerResponse, state: DispatchState, ): Promise { try { const origin = `http://127.0.0.1:${request.socket.localPort}`; if (`http://${request.headers.host}` !== origin) { respondJson(response, 403, { error: "Invalid System host" }); return; } const url = new URL(request.url ?? "/", origin); if (url.origin !== origin || url.pathname.startsWith("//")) { respondJson(response, 403, { error: "Invalid System URL" }); return; } const queryToken = url.searchParams.get("k"); const cookieToken = cookie(request.headers.cookie ?? "", state.cookieName); if (queryToken === state.token && request.method === "GET") { response.statusCode = 303; url.searchParams.delete("k"); response.setHeader("Location", `${url.pathname}${url.search}`); response.setHeader( "Set-Cookie", `${state.cookieName}=${state.token}; HttpOnly; SameSite=Strict; Path=/`, ); response.end(); return; } if (cookieToken !== state.token) { respondJson(response, 403, { error: "Forbidden" }); return; } if (request.method === "POST" && request.headers.origin !== origin) { respondJson(response, 403, { error: "Invalid board origin" }); return; } if (request.method === "POST" && url.pathname === "/api/state") { const input = await readJsonBody(request); const result = await state.enqueue(() => applyState(state.root, input, "manual", state.assertOpen), ); respondJson(response, 200, result); return; } if (request.method === "POST" && url.pathname === "/api/status") { const input = await readJsonBody(request); const result = await state.enqueue(() => { state.assertOpen(); const updated = applyStatus(state.root, input); state.assertOpen(); state.ensureSite(); return updated; }); respondJson(response, 200, result); return; } if (request.method === "POST" && url.pathname === "/api/exec") { const input = await readJsonBody(request); const result = await state.enqueue(async () => { state.assertOpen(); const document = boardDocument(state.root, input); const id = document.metadata.id; const board = readBoardState( state.root, loadProjectIndex(state.root).prefix, ); const itemState = boardStateFor(board, document.metadata); if (itemState === "done" || itemState === "dropped") throw new Error( `Cannot execute ${itemState} document ${id}; reopen it first`, ); if (!state.onExec) throw new Error("System board execution is unavailable"); await state.onExec(id); state.assertOpen(); return { id }; }); respondJson(response, 200, result); return; } if (request.method === "POST" && url.pathname === "/api/edit") { const document = boardDocument(state.root, await readJsonBody(request)); const opened = await openEditableFile( path.join(state.root, document.path), ); if (!opened.ok) throw new Error(`Cannot open editor: ${opened.error}`); respondJson(response, 200, { id: document.metadata.id }); return; } if (request.method === "POST" && url.pathname === "/api/proposal") { const input = await readJsonBody(request); const result = await state.enqueue(() => withFileMutationQueue( path.resolve(state.root, BOARD_PATH), async () => { state.assertOpen(); if ( typeof input["id"] !== "string" || typeof input["state"] !== "string" ) throw new Error("Expected assessment proposal with id and state"); const proposal = state.proposals.get(input["id"]); if (!proposal || proposal.state !== input["state"]) throw new Error( `No matching assessment proposal: ${input["id"]}`, ); const applied = applyStateUnlocked(state.root, input, "assess"); state.proposals.delete(input["id"]); return { ...applied, proposals: proposalSignature(state.proposals), }; }, ), ); respondJson(response, 200, result); return; } if (request.method !== "GET") { respondJson(response, 405, { error: "Method not allowed" }); return; } if (url.pathname === "/api/state") { respondJson(response, 200, snapshot(state)); return; } if ( url.pathname.startsWith("/.system/") && /\.html?$/i.test(url.pathname) ) { const source = decodeURIComponent(url.pathname.slice(1)).replace( /\.html?$/i, ".md", ); const id = state.ensureSite().routes.get(source); if (id) { response.statusCode = 303; response.setHeader("Location", `/#${id}`); response.end(); return; } } const site = isDocument(url.pathname) ? state.ensureSite() : state.currentSite(); serveFile(response, site.directory, url.pathname); } catch (error) { respondJson(response, 400, { error: error instanceof Error ? error.message : String(error), }); } } const isDocument = (pathname: string) => pathname === "/" || pathname.endsWith(".html"); function snapshot(state: DispatchState) { const site = state.ensureSite(); const board = site.board; const problem = state.renderProblem(); return { revision: site.signature.documents, proposals: site.proposals, items: board.items, ...(problem ? { problem } : {}), }; } async function applyState( root: string, input: Record, source: "manual" | "assess", assertOpen: () => void, ) { if ( Object.keys(input).some((key) => key !== "id" && key !== "state") || typeof input["id"] !== "string" || typeof input["state"] !== "string" || !STATES.includes(input["state"] as (typeof STATES)[number]) ) throw new Error("Expected board update with id and state"); return withFileMutationQueue(path.resolve(root, BOARD_PATH), async () => { assertOpen(); return applyStateUnlocked(root, input, source); }); } function applyStateUnlocked( root: string, input: Record, source: "manual" | "assess", ) { const index = loadProjectIndex(root); const current = readBoardState(index.root, index.prefix); const updated = updateBoardState( current, index.documents, input["id"] as string, input["state"] as BoardItemState, source, ); writeBoardState(index.root, updated); return { items: updated.items }; } function applyStatus(root: string, input: Record) { if ( Object.keys(input).some((key) => key !== "id" && key !== "status") || typeof input["id"] !== "string" || typeof input["status"] !== "string" || !STATUSES.includes(input["status"] as (typeof STATUSES)[number]) ) throw new Error("Expected plan update with id and status"); const index = loadProjectIndex(root); writePlanStatus( index, input["id"], input["status"] as (typeof STATUSES)[number], ); return { id: input["id"], status: input["status"] }; } function boardDocument(root: string, input: Record) { if ( Object.keys(input).some((key) => key !== "id") || typeof input["id"] !== "string" ) throw new Error("Expected board action with id"); const document = loadProjectIndex(root).documents.find( (candidate) => candidate.metadata.id === input["id"], ); if (!document) throw new Error(`No System document: ${input["id"]}`); if ( document.metadata.type !== "spec" && document.metadata.type !== "plan" && document.metadata.type !== "issue" ) throw new Error( `Only specs, plans, and issues support board actions: ${input["id"]}`, ); return document; } function readJsonBody( request: IncomingMessage, ): Promise> { return new Promise((resolve, reject) => { let source = ""; request.setEncoding("utf8"); request.on("data", (chunk: string) => { source += chunk; if (Buffer.byteLength(source) > BODY_LIMIT) { request.destroy(); reject(new Error("Board request body is too large")); } }); request.on("end", () => { try { const parsed = JSON.parse(source); if ( typeof parsed !== "object" || parsed === null || Array.isArray(parsed) ) throw new Error("Board request body must be an object"); resolve(parsed as Record); } catch (error) { reject(error); } }); request.on("error", reject); }); } function serveFile( response: ServerResponse, directory: string, pathname: string, ): void { const relative = decodeURIComponent( pathname === "/" ? "index.html" : pathname.slice(1), ); const target = path.resolve(directory, relative); const inside = path.relative(directory, target); if ( inside === ".." || inside.startsWith(`..${path.sep}`) || path.isAbsolute(inside) ) { respondJson(response, 404, { error: "Not found" }); return; } const stats = lstatSync(target, { throwIfNoEntry: false }); if (!stats?.isFile() || stats.isSymbolicLink()) { respondJson(response, 404, { error: "Not found" }); return; } const realRoot = realpathSync(directory); const realTarget = realpathSync(target); const realInside = path.relative(realRoot, realTarget); if ( realInside === ".." || realInside.startsWith(`..${path.sep}`) || path.isAbsolute(realInside) ) { respondJson(response, 404, { error: "Not found" }); return; } response.statusCode = 200; response.setHeader("Content-Type", contentType(target)); response.setHeader("Cache-Control", "no-store"); const stream = createReadStream(target); stream.on("error", () => { if (response.headersSent) response.destroy(); else respondJson(response, 404, { error: "Not found" }); }); response.on("close", () => stream.destroy()); stream.pipe(response); } function contentType(file: string): string { switch (path.extname(file).toLowerCase()) { case ".html": case ".htm": return "text/html; charset=utf-8"; case ".js": return "text/javascript; charset=utf-8"; case ".css": return "text/css; charset=utf-8"; case ".svg": return "image/svg+xml"; case ".png": return "image/png"; case ".jpg": case ".jpeg": return "image/jpeg"; case ".gif": return "image/gif"; case ".webp": return "image/webp"; case ".avif": return "image/avif"; case ".mp4": return "video/mp4"; case ".webm": return "video/webm"; case ".md": return "text/markdown; charset=utf-8"; default: return "application/octet-stream"; } } function respondJson( response: ServerResponse, status: number, value: unknown, ): void { if (response.headersSent) return; response.statusCode = status; response.setHeader("Content-Type", "application/json; charset=utf-8"); response.setHeader("Cache-Control", "no-store"); response.end(JSON.stringify(value)); } function cookie(source: string, name: string): string | undefined { for (const part of source.split(";")) { const [key, ...value] = part.trim().split("="); if (key === name) return value.join("="); } return undefined; }