import assert from "node:assert/strict"; import { mkdirSync, mkdtempSync, readFileSync, rmSync, symlinkSync, writeFileSync, } from "node:fs"; import { request } from "node:http"; import { tmpdir } from "node:os"; import path from "node:path"; import { afterEach, describe, it, vi } from "vitest"; import { type BookRenderer, type BookServer, boardSignature, startBookServer, } from "../book-server.ts"; import * as editor from "../open-editor.ts"; import { planStatusSource } from "../plan-status.ts"; const roots: string[] = []; const servers: BookServer[] = []; interface BoardStateResponse { items: Record; revision: string; problem?: string; } afterEach(() => { vi.restoreAllMocks(); for (const server of servers.splice(0)) server.close(); for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true }); }); describe("board signature", () => { it("separates document changes from board state changes", () => { const root = fixture(); const initial = boardSignature(root); write(root, ".system/board.json", boardJson({})); const afterBoard = boardSignature(root); assert.equal(afterBoard.documents, initial.documents); assert.notEqual(afterBoard.board, initial.board); write( root, ".system/specs/PX-SPEC-SPEC0001-contract/index.md", `${spec()}\nmore\n`, ); const afterDocument = boardSignature(root); assert.notEqual(afterDocument.documents, afterBoard.documents); assert.equal(afterDocument.board, afterBoard.board); }); }); describe("plan status source", () => { it("rewrites exactly one status line and preserves the body", () => { const updated = planStatusSource(plan("draft"), "approved"); assert.equal(updated, plan("approved")); }); it("preserves CRLF frontmatter", () => { const source = plan("draft").replaceAll("\n", "\r\n"); assert.equal( planStatusSource(source, "approved"), plan("approved").replaceAll("\n", "\r\n"), ); }); it("rejects documents without a single status line", () => { assert.throws( () => planStatusSource("# Plan\n", "approved"), /frontmatter/, ); assert.throws( () => planStatusSource( plan("draft").replace( "status: draft", "status: draft\nstatus: draft", ), "approved", ), /exactly one status line/, ); }); }); describe("book server", () => { it("keeps the last good site on refresh failure and recovers after a correction", async () => { const root = fixture(); let fail = false; const client = await open(root, (...args) => { if (fail) throw new Error("Cannot render changed project"); return stubRenderer(...args); }); const before = await client.json("/api/state"); fail = true; const source = ".system/specs/PX-SPEC-SPEC0001-contract/index.md"; write(root, source, spec() + "\nchanged\n"); const failed = await client.json("/api/state"); assert.equal(failed.revision, before.revision); assert.match(failed.problem ?? "", /Cannot render/); assert.match(await client.text("/"), new RegExp(before.revision)); fail = false; const recovered = await client.json("/api/state"); assert.notEqual(recovered.revision, before.revision); assert.equal(recovered.problem, undefined); }); it("redirects document previews through the last good route map when config becomes invalid", async () => { const root = fixture(); const client = await open(root); write(root, ".system/config.json", "{"); const response = await client.raw( "/.system/specs/PX-SPEC-SPEC0001-contract/index.html", { redirect: "manual" }, ); assert.equal(response.status, 303); assert.equal(response.headers.get("location"), "/#PX-SPEC-SPEC0001"); assert.match((await client.json("/api/state")).problem ?? "", /JSON/); }); it("serves htm previews as HTML", async () => { const root = fixture(); const server = await startBookServer(root, new Map(), (...args) => { const output = stubRenderer(...args); writeFileSync( path.join(output.directory, "preview.htm"), "

preview

", ); return output; }); servers.push(server); const handshake = await fetch(server.url, { redirect: "manual" }); const cookie = (handshake.headers.get("set-cookie") ?? "").split(";")[0]; const response = await fetch(new URL("/preview.htm", server.url), { headers: { cookie: cookie ?? "" }, }); assert.equal( response.headers.get("content-type"), "text/html; charset=utf-8", ); }); it("cancels queued mutations after close without rendering or writing", async () => { const root = fixture(); let release: (() => void) | undefined; let entered: (() => void) | undefined; const held = new Promise((resolve) => { release = resolve; }); const started = new Promise((resolve) => { entered = resolve; }); let renders = 0; const client = await open( root, (...args) => { renders += 1; return stubRenderer(...args); }, async () => { entered?.(); await held; }, ); const running = client.response("/api/exec", { id: "PX-SPEC-SPEC0001" }); await started; const queued = client.response("/api/status", { id: "PX-PLAN-PLAN0001", status: "approved", }); servers.pop()?.close(); release?.(); await Promise.allSettled([running, queued]); assert.equal( read(root, ".system/plans/PX-PLAN-PLAN0001-build/index.md"), plan("draft"), ); assert.equal(renders, 1); }); it("confines files and rejects missing origin, forged hosts, and token-only POSTs", async () => { const root = fixture(); const server = await startBookServer(root, new Map(), (...args) => { const output = stubRenderer(...args); symlinkSync( path.join(root, ".system/config.json"), path.join(output.directory, "secret.json"), ); symlinkSync( path.join(root, ".system"), path.join(output.directory, "linked"), ); return output; }); servers.push(server); const origin = new URL(server.url).origin; const handshake = await fetch(server.url, { redirect: "manual" }); const cookie = (handshake.headers.get("set-cookie") ?? "").split(";")[0] ?? ""; for (const route of [ "/api/state", "/api/status", "/api/edit", "/api/exec", "/api/proposal", ]) { const response = await fetch(origin + route, { method: "POST", headers: { cookie }, body: "{}", }); assert.equal(response.status, 403, route); } assert.equal( ( await fetch(server.url, { method: "POST", headers: { origin }, body: "{}", }) ).status, 403, ); assert.equal( await new Promise((resolve, reject) => { const req = request( origin, { headers: { cookie, host: "attacker.invalid" } }, (response) => { response.resume(); resolve(response.statusCode); }, ); req.on("error", reject); req.end(); }), 403, ); assert.equal( ( await fetch( origin + "//attacker.invalid/?k=" + new URL(server.url).searchParams.get("k"), { headers: { cookie }, redirect: "manual" }, ) ).status, 403, ); for (const route of [ "/secret.json", "/linked/config.json", "/%2e%2e%2fconfig.json", ]) { assert.equal( (await fetch(origin + route, { headers: { cookie } })).status, 404, route, ); } }); it("serializes duplicate proposal accepts and consumes proposal once", async () => { const root = fixture(); const proposals = new Map([ [ "PX-PLAN-PLAN0001", { id: "PX-PLAN-PLAN0001", state: "done" as const, rationale: "Verified", }, ], ]); const client = await open(root, stubRenderer, undefined, proposals); const responses = await Promise.all([ client.response("/api/proposal", { id: "PX-PLAN-PLAN0001", state: "done", }), client.response("/api/proposal", { id: "PX-PLAN-PLAN0001", state: "done", }), ]); assert.equal( responses.filter((result) => result.status === 200).length, 1, JSON.stringify(responses), ); assert.equal(responses.filter((result) => result.status === 400).length, 1); assert.equal(proposals.size, 0); assert.equal( JSON.parse(readFileSync(path.join(root, ".system/board.json"), "utf8")) .items["PX-PLAN-PLAN0001"].state, "done", ); }); it("re-renders stale pages and serves live board state", async () => { const root = fixture(); let renders = 0; const client = await open(root, (_index, board, _proposals, revision) => { renders += 1; const directory = mkdtempSync(path.join(tmpdir(), "board-site-")); roots.push(directory); writeFileSync( path.join(directory, "index.html"), ``, "utf8", ); return { directory }; }); assert.equal(renders, 1); assert.match(await client.text("/"), /data-renders="1"/); assert.match(await client.text("/"), /data-renders="1"/); const before = await client.json("/api/state"); assert.deepEqual(before.items, {}); assert.equal(typeof before.revision, "string"); const applied = await client.post("/api/state", { id: "PX-PLAN-PLAN0001", state: "done", }); assert.equal(applied.items["PX-PLAN-PLAN0001"]!.state, "done"); const after = await client.json("/api/state"); assert.equal(after.items["PX-PLAN-PLAN0001"]!.state, "done"); assert.equal(after.revision, before.revision); const reloaded = await client.text("/"); assert.match(reloaded, /data-renders="2"/); assert.match(reloaded, /data-items="1"/); write( root, ".system/issues/PX-ISSUE-ISSUE002-later/index.md", "---\nid: PX-ISSUE-ISSUE002\ntype: issue\ntitle: Later\nspecs: [PX-SPEC-SPEC0001]\n---\n\n# Later\n", ); const changed = await client.json("/api/state"); assert.notEqual(changed.revision, before.revision); assert.match(await client.text("/"), /data-renders="3"/); const late = await client.post("/api/state", { id: "PX-ISSUE-ISSUE002", state: "done", }); assert.equal(late.items["PX-ISSUE-ISSUE002"]!.state, "done"); }); it("rejects unauthenticated and cross-origin board mutations", async () => { const root = fixture(); const server = await startBookServer(root, new Map(), stubRenderer); servers.push(server); const url = new URL(server.url); const origin = url.origin; const unauthenticated = await fetch(`${origin}/api/state`, { method: "POST", headers: { "content-type": "application/json", origin }, body: JSON.stringify({ id: "PX-PLAN-PLAN0001", state: "done" }), }); assert.equal(unauthenticated.status, 403); const unauthenticatedExec = await fetch(`${origin}/api/exec`, { method: "POST", headers: { "content-type": "application/json", origin }, body: JSON.stringify({ id: "PX-SPEC-SPEC0001" }), }); assert.equal(unauthenticatedExec.status, 403); const handshake = await fetch(server.url, { redirect: "manual" }); const cookie = (handshake.headers.get("set-cookie") ?? "").split(";")[0]; assert.ok(cookie); const crossOrigin = await fetch(`${origin}/api/state`, { method: "POST", headers: { "content-type": "application/json", cookie, origin: "https://untrusted.example", }, body: JSON.stringify({ id: "PX-PLAN-PLAN0001", state: "done" }), }); assert.equal(crossOrigin.status, 403); const crossOriginExec = await fetch(`${origin}/api/exec`, { method: "POST", headers: { "content-type": "application/json", cookie, origin: "https://untrusted.example", }, body: JSON.stringify({ id: "PX-SPEC-SPEC0001" }), }); assert.equal(crossOriginExec.status, 403); assert.deepEqual(readBoardState(root), { schemaVersion: 0, items: {} }); }); it("executes only existing board document IDs through the supplied callback", async () => { const root = fixture(); const executed: string[] = []; const client = await open(root, stubRenderer, async (id) => { executed.push(id); }); assert.deepEqual( await client.post("/api/exec", { id: "PX-SPEC-SPEC0001" }), { id: "PX-SPEC-SPEC0001", }, ); assert.deepEqual(executed, ["PX-SPEC-SPEC0001"]); assert.match( (await client.failing("/api/exec", { id: "PX-PHASE-PHASE001" })).error, /Only specs, plans, and issues support board actions/, ); assert.match( (await client.failing("/api/exec", { id: "PX-SPEC-MISSING" })).error, /No System document/, ); assert.match( ( await client.failing("/api/exec", { id: "PX-SPEC-SPEC0001", extra: true, }) ).error, /Expected board action with id/, ); }); it("opens only indexed board documents in the editor and reports launch failure", async () => { const root = fixture(); write( root, ".system/issues/PX-ISSUE-ISSUE001-bug/index.md", "---\nid: PX-ISSUE-ISSUE001\ntype: issue\ntitle: Bug\nspecs: [PX-SPEC-SPEC0001]\n---\n\n# Bug\n", ); const launch = vi.spyOn(editor, "openEditableFile").mockResolvedValue({ ok: true, file: "", command: "editor", }); const client = await open(root); for (const id of [ "PX-SPEC-SPEC0001", "PX-PLAN-PLAN0001", "PX-ISSUE-ISSUE001", ]) { assert.deepEqual(await client.post("/api/edit", { id }), { id }); } assert.deepEqual( launch.mock.calls.map(([file]) => path.relative(root, file).split(path.sep).join("/"), ), [ ".system/specs/PX-SPEC-SPEC0001-contract/index.md", ".system/plans/PX-PLAN-PLAN0001-build/index.md", ".system/issues/PX-ISSUE-ISSUE001-bug/index.md", ], ); for (const input of [ { id: "../../outside.md" }, { id: "PX-PHASE-PHASE001" }, { id: "PX-SPEC-SPEC0001", path: "../../outside.md" }, ]) { await client.failing("/api/edit", input); } assert.equal(launch.mock.calls.length, 3); launch.mockResolvedValueOnce({ ok: false, file: "", error: "No editor opener found", }); assert.match( (await client.failing("/api/edit", { id: "PX-SPEC-SPEC0001" })).error, /Cannot open editor: No editor opener found/, ); }); it("rejects unauthenticated and cross-origin editor requests without launching an editor", async () => { const launch = vi.spyOn(editor, "openEditableFile"); const server = await startBookServer(fixture(), new Map(), stubRenderer); servers.push(server); const origin = new URL(server.url).origin; const input = { method: "POST", headers: { origin, "content-type": "application/json" }, body: JSON.stringify({ id: "PX-SPEC-SPEC0001" }), }; assert.equal((await fetch(origin + "/api/edit", input)).status, 403); const handshake = await fetch(server.url, { redirect: "manual" }); const cookie = handshake.headers.get("set-cookie")!.split(";")[0]!; assert.equal( ( await fetch(origin + "/api/edit", { ...input, headers: { ...input.headers, cookie, origin: "https://untrusted.invalid", }, }) ).status, 403, ); assert.equal(launch.mock.calls.length, 0); }); it("blocks completed and dropped documents until reopened", async () => { const executed: string[] = []; const root = fixture(); write( root, ".system/issues/PX-ISSUE-ISSUE001-failure/index.md", "---\nid: PX-ISSUE-ISSUE001\ntype: issue\ntitle: Failure\nspecs: [PX-SPEC-SPEC0001]\n---\n\n# Failure\n", ); const client = await open(root, stubRenderer, (id) => { executed.push(id); }); for (const id of [ "PX-PLAN-PLAN0001", "PX-ISSUE-ISSUE001", "PX-SPEC-SPEC0001", ]) { for (const state of ["done", "dropped"]) { await client.post("/api/state", { id, state }); assert.match( (await client.failing("/api/exec", { id })).error, /Cannot execute/, ); assert.equal(executed.length, 0); } } await client.post("/api/state", { id: "PX-PLAN-PLAN0001", state: "todo" }); await client.post("/api/exec", { id: "PX-PLAN-PLAN0001" }); assert.deepEqual(executed, ["PX-PLAN-PLAN0001"]); }); it("reports when board execution is unavailable", async () => { const client = await open(fixture()); assert.match( (await client.failing("/api/exec", { id: "PX-SPEC-SPEC0001" })).error, /execution is unavailable/, ); }); it("persists reversible drops without changing approval or child state", async () => { const root = fixture(); const client = await open(root); const dropped = await client.post("/api/state", { id: "PX-PLAN-PLAN0001", state: "dropped", }); assert.equal(dropped.items["PX-PLAN-PLAN0001"]!.state, "dropped"); await client.post("/api/state", { id: "PX-SPEC-SPEC0001", state: "done" }); const restored = await client.post("/api/state", { id: "PX-PLAN-PLAN0001", state: "todo", }); assert.equal(restored.items["PX-SPEC-SPEC0001"]!.state, "todo"); const specDrop = await client.post("/api/state", { id: "PX-SPEC-SPEC0001", state: "dropped", }); assert.equal(specDrop.items["PX-PLAN-PLAN0001"]!.state, "todo"); assert.equal( (await client.json("/api/state")).items["PX-SPEC-SPEC0001"]!.state, "dropped", ); assert.equal( read(root, ".system/plans/PX-PLAN-PLAN0001-build/index.md"), plan("draft"), ); assert.match( ( await client.failing("/api/state", { id: "PX-PHASE-PHASE001", state: "dropped", }) ).error, /Invalid phase board state/, ); }); it("toggles plan status on disk and refreshes static output", async () => { const root = fixture(); let renders = 0; const client = await open(root, (index, _board, _proposals, revision) => { renders += 1; const directory = mkdtempSync(path.join(tmpdir(), "board-site-")); roots.push(directory); const plan = index.documents.find( (document) => document.metadata.id === "PX-PLAN-PLAN0001", ); const status = plan?.metadata.type === "plan" ? plan.metadata.status : "missing"; writeFileSync( path.join(directory, "index.html"), ``, "utf8", ); return { directory }; }); const planPath = ".system/plans/PX-PLAN-PLAN0001-build/index.md"; const result = await client.post("/api/status", { id: "PX-PLAN-PLAN0001", status: "approved", }); assert.deepEqual(result, { id: "PX-PLAN-PLAN0001", status: "approved" }); assert.match(read(root, planPath), /^status: approved$/m); assert.equal(renders, 2); assert.match(await client.text("/"), /data-status="approved"/); await client.post("/api/status", { id: "PX-PLAN-PLAN0001", status: "draft", }); assert.equal(read(root, planPath), plan("draft")); assert.match( ( await client.failing("/api/status", { id: "PX-SPEC-SPEC0001", status: "approved", }) ).error, /Only plans carry a status/, ); assert.match( ( await client.failing("/api/status", { id: "PX-PLAN-PLAN0001", status: "shipped", }) ).error, /Expected plan update with id and status/, ); }); }); const stubRenderer: BookRenderer = (_index, _board, _proposals, revision) => { const directory = mkdtempSync(path.join(tmpdir(), "board-site-")); roots.push(directory); writeFileSync( path.join(directory, "index.html"), ``, "utf8", ); return { directory }; }; async function open( root: string, render: BookRenderer = stubRenderer, onExec?: (id: string) => void | Promise, proposals = new Map(), ) { const server = await startBookServer(root, proposals, render, onExec); servers.push(server); const url = new URL(server.url); const handshake = await fetch(server.url, { redirect: "manual" }); const cookie = (handshake.headers.get("set-cookie") ?? "").split(";")[0]; assert.equal(handshake.status, 303); assert.ok(cookie); const origin = `${url.protocol}//${url.host}`; const request = (target: string, init?: RequestInit) => fetch(`${origin}${target}`, { ...init, headers: { ...(init?.headers ?? {}), cookie: cookie ?? "" }, }); const send = (target: string, payload: unknown) => request(target, { method: "POST", headers: { "content-type": "application/json", origin }, body: JSON.stringify(payload), }); return { async text(target: string) { const response = await request(target); assert.equal(response.status, 200); return response.text(); }, async json(target: string) { const response = await request(target); assert.equal(response.status, 200); return (await response.json()) as BoardStateResponse; }, async post(target: string, payload: unknown) { const response = await send(target, payload); assert.equal(response.status, 200); return (await response.json()) as BoardStateResponse; }, async response(target: string, payload: unknown) { const response = await send(target, payload); return { status: response.status, body: await response.json() }; }, async failing(target: string, payload: unknown) { const response = await send(target, payload); assert.equal(response.status, 400); return (await response.json()) as { error: string }; }, raw: request, }; } const boardJson = (items: Record) => `${JSON.stringify({ schemaVersion: 0, items }, null, "\t")}\n`; const spec = () => "---\nid: PX-SPEC-SPEC0001\ntype: spec\ntitle: Contract\n---\n\n# Contract\n"; const plan = (status: string) => `---\nid: PX-PLAN-PLAN0001\ntype: plan\ntitle: Build\nspec: PX-SPEC-SPEC0001\nstatus: ${status}\n---\n\n# Build\n`; function fixture(): string { const root = mkdtempSync(path.join(tmpdir(), "book-server-")); roots.push(root); for (const directory of ["specs", "phases", "plans", "issues", "research"]) mkdirSync(path.join(root, ".system", directory), { recursive: true }); write(root, ".system/config.json", '{"prefix":"PX","schemaVersion":0}'); write(root, ".system/board.json", '{"schemaVersion":0,"items":{}}'); write(root, ".system/SYSTEM.md", "# SYSTEM\n"); write( root, ".system/phases/PX-PHASE-PHASE001-current/index.md", "---\nid: PX-PHASE-PHASE001\ntype: phase\ntitle: Current\nlabel: current\n---\n\n# Current\n", ); write(root, ".system/specs/PX-SPEC-SPEC0001-contract/index.md", spec()); write(root, ".system/plans/PX-PLAN-PLAN0001-build/index.md", plan("draft")); return root; } function write(root: string, relative: string, content: string) { const target = path.join(root, relative); mkdirSync(path.dirname(target), { recursive: true }); writeFileSync(target, content, "utf8"); } const read = (root: string, relative: string) => readFileSync(path.join(root, relative), "utf8"); const readBoardState = (root: string) => JSON.parse(read(root, ".system/board.json")) as unknown;