@howaboua/pi-agent-board 0.0.0-stage → 0.0.1

package/src/viewer/config.ts

@@ -0,0 +1,111 @@
+import { randomBytes } from "node:crypto";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export interface ViewerConfig {
+	host: string;
+	port: number;
+	publicUrl: string;
+	openCommand: string[] | null;
+}
+
+export function stateDirectory(): string {
+	return join(
+		process.env["PI_CODING_AGENT_DIR"] || join(homedir(), ".pi", "agent"),
+		"board-viewer",
+	);
+}
+
+function configPath(): string {
+	return join(stateDirectory(), "config.json");
+}
+
+export async function loadConfig(): Promise<ViewerConfig> {
+	let value: unknown;
+	try {
+		value = JSON.parse(await readFile(configPath(), "utf8"));
+	} catch (error) {
+		if (!(error instanceof Error && "code" in error && error.code === "ENOENT"))
+			throw error;
+		value = {};
+	}
+	if (!value || typeof value !== "object" || Array.isArray(value))
+		throw new Error("Viewer config must be an object");
+	const config = value as Record<string, unknown>;
+	const host = config["host"] ?? "127.0.0.1";
+	const port = config["port"] ?? 47984;
+	if (typeof host !== "string" || !["127.0.0.1", "0.0.0.0"].includes(host))
+		throw new Error("Viewer host must be 127.0.0.1 or 0.0.0.0");
+	if (
+		typeof port !== "number" ||
+		!Number.isInteger(port) ||
+		port < 1024 ||
+		port > 65535
+	)
+		throw new Error("Viewer port must be an integer from 1024 to 65535");
+	const publicUrl = config["publicUrl"] ?? `http://127.0.0.1:${port}`;
+	if (typeof publicUrl !== "string")
+		throw new Error("Viewer publicUrl must be an HTTP or HTTPS origin");
+	const url = new URL(publicUrl);
+	if (
+		!["http:", "https:"].includes(url.protocol) ||
+		url.username ||
+		url.password ||
+		url.pathname !== "/" ||
+		url.search ||
+		url.hash
+	)
+		throw new Error(
+			"Viewer publicUrl must be an HTTP or HTTPS origin without a path",
+		);
+	const command = config["openCommand"];
+	if (
+		command !== undefined &&
+		command !== null &&
+		(!Array.isArray(command) ||
+			!command.length ||
+			!command.every((part) => typeof part === "string" && part.length > 0))
+	)
+		throw new Error(
+			"Viewer openCommand must be an argument array, or null for link only",
+		);
+	const defaultCommand =
+		process.platform === "darwin"
+			? ["open"]
+			: process.platform === "win32"
+				? ["rundll32", "url.dll,FileProtocolHandler"]
+				: ["xdg-open"];
+	return {
+		host,
+		port,
+		publicUrl: url.origin,
+		openCommand:
+			command === null
+				? null
+				: command === undefined
+					? defaultCommand
+					: (command as string[]),
+	};
+}
+
+export async function accessKey(): Promise<string> {
+	const directory = stateDirectory();
+	await mkdir(directory, { recursive: true, mode: 0o700 });
+	const path = join(directory, "access-key");
+	try {
+		await writeFile(path, randomBytes(32).toString("hex"), {
+			flag: "wx",
+			mode: 0o600,
+		});
+	} catch (error) {
+		if (!(error instanceof Error && "code" in error && error.code === "EEXIST"))
+			throw error;
+	}
+	const key = (await readFile(path, "utf8")).trim();
+	if (!/^[a-f0-9]{64}$/.test(key))
+		throw new Error(
+			"Invalid viewer access key; remove the access-key file and restart the viewer",
+		);
+	return key;
+}

package/src/viewer/contracts.ts

@@ -0,0 +1,82 @@
+interface ViewContext {
+	sessionId: string;
+	sessionName: string | null;
+	boardId: string;
+	folder: string;
+}
+
+export interface ViewSource extends ViewContext {
+	databasePath: string;
+}
+
+export interface BoardSummary {
+	id: string;
+	rootSessionId: string;
+	createdAt: string | null;
+	lastActivity: string | null;
+	channels: number;
+	posts: number;
+	agents: number;
+}
+
+export interface BoardIndex {
+	context: ViewContext;
+	boards: BoardSummary[];
+}
+
+interface Channel {
+	name: string;
+	author: string;
+	createdAt: string;
+	posts: number;
+	threads: number;
+	lastActivity: string | null;
+}
+
+interface Agent {
+	name: string;
+	posts: number;
+	lastActivity: string;
+}
+
+interface Subscription {
+	target: string;
+	agent: string;
+	enabled: boolean;
+}
+
+export interface BoardDetail {
+	board: BoardSummary;
+	channels: Channel[];
+	agents: Agent[];
+	subscriptions: Subscription[];
+}
+
+interface ThreadSummary {
+	id: string;
+	channel: string;
+	author: string;
+	preview: string;
+	createdAt: string;
+	lastActivity: string;
+	replies: number;
+}
+
+export interface ThreadPage {
+	threads: ThreadSummary[];
+	nextCursor: string | null;
+}
+
+export interface Post {
+	id: string;
+	channel: string;
+	author: string;
+	createdAt: string;
+	text: string;
+}
+
+export interface ThreadDetail {
+	root: Post;
+	replies: Post[];
+	nextCursor: string | null;
+}

package/src/viewer/index.ts

@@ -0,0 +1,158 @@
+import { spawn } from "node:child_process";
+import { closeSync, openSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import type {
+	ExtensionAPI,
+	ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import {
+	accessKey,
+	loadConfig,
+	stateDirectory,
+	type ViewerConfig,
+} from "./config.ts";
+import type { ViewSource } from "./contracts.ts";
+import { parseSource } from "./source.ts";
+
+export type ViewerSource = (
+	ctx: ExtensionContext,
+	sessionName: string | undefined,
+) => ViewSource | Promise<ViewSource>;
+
+const PROTOCOL = "pi-board-viewer/1";
+async function available(
+	origin: string,
+	config: ViewerConfig,
+): Promise<boolean> {
+	let response: Response;
+	try {
+		response = await fetch(`${origin}/api/health`, {
+			signal: AbortSignal.timeout(700),
+		});
+	} catch {
+		return false;
+	}
+	let value: unknown;
+	try {
+		value = await response.json();
+	} catch {
+		throw new Error(
+			"The viewer port is occupied by another application; change the viewer port",
+		);
+	}
+	if (
+		!response.ok ||
+		!value ||
+		typeof value !== "object" ||
+		!("protocol" in value) ||
+		value.protocol !== PROTOCOL
+	)
+		throw new Error(
+			"The viewer port is occupied by another application or viewer version",
+		);
+	if (
+		!("host" in value) ||
+		value.host !== config.host ||
+		!("publicUrl" in value) ||
+		value.publicUrl !== config.publicUrl
+	) {
+		const process =
+			"pid" in value && typeof value.pid === "number"
+				? ` process ${value.pid}`
+				: " server";
+		throw new Error(
+			`Viewer configuration changed. Restart the viewer${process}, then run /board again`,
+		);
+	}
+	return true;
+}
+
+async function ensureServer(config: ViewerConfig): Promise<string> {
+	const origin = `http://127.0.0.1:${config.port}`;
+	if (await available(origin, config)) return origin;
+	const log = openSync(join(stateDirectory(), "server.log"), "a", 0o600);
+	let failure: Error | undefined;
+	try {
+		const child = spawn(
+			process.execPath,
+			[fileURLToPath(new URL("../../dist/viewer/server.js", import.meta.url))],
+			{ detached: true, stdio: ["ignore", log, log], windowsHide: true },
+		);
+		child.once("error", (error) => {
+			failure = error;
+		});
+		child.unref();
+	} finally {
+		closeSync(log);
+	}
+	for (let attempt = 0; attempt < 30; attempt++) {
+		if (failure) throw failure;
+		if (await available(origin, config)) return origin;
+		await new Promise((resolve) => setTimeout(resolve, 100));
+	}
+	throw new Error(
+		`Board viewer did not start. Check ${join(stateDirectory(), "server.log")}`,
+	);
+}
+
+export async function openBoardViewer(
+	pi: ExtensionAPI,
+	ctx: ExtensionContext,
+	source: ViewerSource,
+): Promise<void> {
+	try {
+		const view = parseSource(await source(ctx, pi.getSessionName()));
+		const config = await loadConfig();
+		const key = await accessKey();
+		const origin = await ensureServer(config);
+		const response = await fetch(`${origin}/api/open`, {
+			method: "POST",
+			headers: {
+				Authorization: `Bearer ${key}`,
+				"Content-Type": "application/json",
+			},
+			body: JSON.stringify(view),
+			signal: AbortSignal.timeout(10_000),
+		});
+		const value: unknown = await response.json();
+		if (
+			!response.ok ||
+			!value ||
+			typeof value !== "object" ||
+			!("url" in value) ||
+			typeof value.url !== "string"
+		) {
+			throw new Error(
+				value &&
+					typeof value === "object" &&
+					"error" in value &&
+					typeof value.error === "string"
+					? value.error
+					: "Could not open the board viewer",
+			);
+		}
+		const url = value.url;
+		ctx.ui.notify(url, "info");
+		if (config.openCommand) {
+			const [command, ...commandArgs] = config.openCommand;
+			if (!command) return;
+			try {
+				const result = await pi.exec(command, [...commandArgs, url], {
+					timeout: 5_000,
+				});
+				if (result.code !== 0) throw new Error("Browser opener failed");
+			} catch {
+				ctx.ui.notify(
+					"The viewer is ready, but the browser did not open. Open the link above.",
+					"warning",
+				);
+			}
+		}
+	} catch (error) {
+		ctx.ui.notify(
+			`Board viewer: ${error instanceof Error ? error.message : String(error)}`,
+			"error",
+		);
+	}
+}

package/src/viewer/server.ts

@@ -0,0 +1,199 @@
+import { randomBytes, timingSafeEqual } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import {
+	createServer,
+	type IncomingMessage,
+	type ServerResponse,
+} from "node:http";
+import { pathToFileURL } from "node:url";
+import { Archive } from "./archive.ts";
+import { accessKey, loadConfig, type ViewerConfig } from "./config.ts";
+import type { ViewSource } from "./contracts.ts";
+import { parseSource } from "./source.ts";
+
+export const PROTOCOL = "pi-board-viewer/1";
+const assets = new Map<string, readonly [string, string]>([
+	["/", ["web/index.html", "text/html; charset=utf-8"]],
+	["/app.js", ["web/app.js", "text/javascript; charset=utf-8"]],
+	["/style.css", ["web/style.css", "text/css; charset=utf-8"]],
+	[
+		"/vendor/marked.js",
+		[import.meta.resolve("marked"), "text/javascript; charset=utf-8"],
+	],
+	[
+		"/vendor/purify.js",
+		[import.meta.resolve("dompurify"), "text/javascript; charset=utf-8"],
+	],
+] as const);
+
+function authenticated(req: IncomingMessage, secret: string): boolean {
+	const value = req.headers.authorization;
+	if (!value?.startsWith("Bearer ")) return false;
+	const provided = Buffer.from(value.slice(7));
+	const expected = Buffer.from(secret);
+	return (
+		provided.length === expected.length && timingSafeEqual(provided, expected)
+	);
+}
+
+async function body(req: IncomingMessage): Promise<unknown> {
+	const chunks: Buffer[] = [];
+	let length = 0;
+	for await (const chunk of req) {
+		const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+		length += bytes.length;
+		if (length > 16_384) throw new Error("Viewer request is too large");
+		chunks.push(bytes);
+	}
+	return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+}
+
+function json(res: ServerResponse, status: number, value: unknown): void {
+	res.writeHead(status, { "Content-Type": "application/json; charset=utf-8" });
+	res.end(JSON.stringify(value));
+}
+
+export async function startServer(config: ViewerConfig, key: string) {
+	const views = new Map<string, ViewSource>();
+	const registered = new Map<string, string>();
+	const server = createServer((req, res) => {
+		res.setHeader("Cache-Control", "no-store");
+		res.setHeader("Referrer-Policy", "no-referrer");
+		res.setHeader("X-Content-Type-Options", "nosniff");
+		res.setHeader(
+			"Content-Security-Policy",
+			"default-src 'none'; script-src 'self'; style-src 'self'; connect-src 'self'; img-src 'self' data:; font-src 'self'; base-uri 'none'; frame-ancestors 'none'; form-action 'none'",
+		);
+		void handle(req, res).catch((error: unknown) => {
+			if (res.headersSent) {
+				res.destroy();
+				return;
+			}
+			json(res, 400, {
+				error: error instanceof Error ? error.message : "Viewer request failed",
+			});
+		});
+	});
+	server.headersTimeout = 10_000;
+	server.requestTimeout = 10_000;
+	server.maxHeadersCount = 50;
+
+	async function handle(
+		req: IncomingMessage,
+		res: ServerResponse,
+	): Promise<void> {
+		const url = new URL(req.url ?? "/", "http://localhost");
+		if (req.method === "GET" && url.pathname === "/api/health") {
+			json(res, 200, {
+				protocol: PROTOCOL,
+				host: config.host,
+				publicUrl: config.publicUrl,
+				pid: process.pid,
+			});
+			return;
+		}
+		if (req.method === "POST" && url.pathname === "/api/open") {
+			// Only the local extension may register filesystem sources. View links cannot.
+			if (
+				req.socket.remoteAddress !== "127.0.0.1" ||
+				!authenticated(req, key)
+			) {
+				json(res, 403, {
+					error: "Only the local Pi extension can open a board archive",
+				});
+				return;
+			}
+			const source = parseSource(await body(req));
+			const archive = new Archive(source);
+			try {
+				archive.index();
+			} finally {
+				archive.close();
+			}
+			const identity = JSON.stringify(source);
+			const token = registered.get(identity) ?? randomBytes(32).toString("hex");
+			registered.set(identity, token);
+			views.set(token, source);
+			json(res, 200, { url: `${config.publicUrl}/#view=${token}` });
+			return;
+		}
+		if (req.method !== "GET") {
+			json(res, 405, { error: "The board viewer is read-only" });
+			return;
+		}
+		if (url.pathname.startsWith("/api/")) {
+			const token = req.headers.authorization?.replace(/^Bearer /, "") ?? "";
+			const source = views.get(token);
+			if (!source) {
+				json(res, 401, {
+					error:
+						"This viewer link has expired. Run /board in Pi for a new link.",
+				});
+				return;
+			}
+			const archive = new Archive(source);
+			try {
+				const board = url.searchParams.get("boardId") ?? source.boardId;
+				let result: unknown;
+				switch (url.pathname) {
+					case "/api/boards":
+						result = archive.index();
+						break;
+					case "/api/board":
+						result = archive.detail(board);
+						break;
+					case "/api/threads":
+						result = archive.threads(board, url.searchParams);
+						break;
+					case "/api/thread":
+						result = archive.thread(
+							board,
+							url.searchParams.get("id") ?? "",
+							url.searchParams,
+						);
+						break;
+					default:
+						json(res, 404, { error: "Unknown viewer request" });
+						return;
+				}
+				json(res, 200, result);
+			} finally {
+				archive.close();
+			}
+			return;
+		}
+		const asset = assets.get(url.pathname);
+		if (!asset) {
+			json(res, 404, { error: "Page not found" });
+			return;
+		}
+		const content = await readFile(new URL(asset[0], import.meta.url));
+		res.writeHead(200, { "Content-Type": asset[1] });
+		res.end(content);
+	}
+	await new Promise<void>((resolve, reject) => {
+		server.once("error", reject);
+		server.listen(config.port, config.host, () => {
+			server.removeListener("error", reject);
+			resolve();
+		});
+	});
+	return server;
+}
+
+if (
+	process.argv[1] &&
+	import.meta.url === pathToFileURL(process.argv[1]).href
+) {
+	const config = await loadConfig();
+	const server = await startServer(config, await accessKey());
+	console.log(
+		`Board viewer listening on ${config.host}:${config.port} (PID ${process.pid})`,
+	);
+	const stop = () => {
+		server.close();
+		server.closeAllConnections();
+	};
+	process.once("SIGTERM", stop);
+	process.once("SIGINT", stop);
+}

package/src/viewer/source.ts

@@ -0,0 +1,33 @@
+import { isAbsolute } from "node:path";
+import type { ViewSource } from "./contracts.ts";
+
+export function parseSource(value: unknown): ViewSource {
+	if (!value || typeof value !== "object" || Array.isArray(value))
+		throw new Error("Invalid viewer source");
+	const fields = value as Record<string, unknown>;
+	const required = (key: string) => {
+		const field = fields[key];
+		if (
+			typeof field !== "string" ||
+			!field.length ||
+			field.length > 4096 ||
+			field.includes("\0")
+		)
+			throw new Error(`Invalid viewer ${key}`);
+		return field;
+	};
+	const folder = required("folder");
+	const databasePath = required("databasePath");
+	if (!isAbsolute(folder) || !isAbsolute(databasePath))
+		throw new Error("Viewer source paths must be absolute");
+	const sessionName = fields["sessionName"];
+	if (sessionName !== null && typeof sessionName !== "string")
+		throw new Error("Invalid viewer session name");
+	return {
+		sessionId: required("sessionId"),
+		boardId: required("boardId"),
+		sessionName,
+		folder,
+		databasePath,
+	};
+}