repositories / pi-ext
pi-ext
bugabingas pi extensions
owned by admin
extensions/the-system/__tests__/book-server.test.ts
Rawimport 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<string, { state: string }>;
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"),
"<p>preview</p>",
);
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<void>((resolve) => {
release = resolve;
});
const started = new Promise<void>((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<number | undefined>((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"),
`<body data-revision="${revision}" data-renders="${renders}" data-items="${
Object.keys(board.items).length
}">`,
"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"),
`<body data-revision="${revision}" data-status="${status}">`,
"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"),
`<body data-revision="${revision}">`,
"utf8",
);
return { directory };
};
async function open(
root: string,
render: BookRenderer = stubRenderer,
onExec?: (id: string) => void | Promise<void>,
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<string, unknown>) =>
`${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;