@plannotator/pi-extension 0.28.48 → 0.28.49

package/server/code-nav-runtime.ts

@@ -0,0 +1,47 @@
+/**
+ * Code navigation's node runtime for Pi (the Bun one is packages/server/code-nav.ts):
+ * the review server's /api/code-nav/* and Shape's code routes (serverShape.ts).
+ */
+import { spawn } from "node:child_process";
+import { resolve as resolvePath } from "node:path";
+import { type CodeNavRuntime, CODE_NAV_MAX_FILE_BYTES } from "../generated/code-nav.ts";
+import { readFileCapped } from "../generated/repo-file.ts";
+
+export const piCodeNavRuntime: CodeNavRuntime = {
+	runCommand(command, args, options) {
+		return new Promise((resolve) => {
+			const proc = spawn(command, args, {
+				cwd: options?.cwd,
+				stdio: ["ignore", "pipe", "pipe"],
+			});
+			let timer: ReturnType<typeof setTimeout> | undefined;
+			if (options?.timeoutMs) {
+				timer = setTimeout(() => proc.kill(), options.timeoutMs);
+			}
+			const stdoutChunks: Buffer[] = [];
+			const stderrChunks: Buffer[] = [];
+			proc.stdout!.on("data", (chunk: Buffer) => stdoutChunks.push(chunk));
+			proc.stderr!.on("data", (chunk: Buffer) => stderrChunks.push(chunk));
+			proc.on("close", (code: number | null) => {
+				if (timer) clearTimeout(timer);
+				resolve({
+					stdout: Buffer.concat(stdoutChunks).toString("utf-8"),
+					stderr: Buffer.concat(stderrChunks).toString("utf-8"),
+					exitCode: code ?? 1,
+				});
+			});
+			proc.on("error", () => {
+				if (timer) clearTimeout(timer);
+				resolve({ stdout: "", stderr: "command not found", exitCode: 1 });
+			});
+		});
+	},
+
+	async readFile(path, options) {
+		// Capped at what rg searches, non-blocking (repo-file.ts).
+		const read = await readFileCapped(options?.cwd ? resolvePath(options.cwd, path) : path, {
+			maxBytes: CODE_NAV_MAX_FILE_BYTES,
+		});
+		return read.ok ? read.content : null;
+	},
+};

package/server/serverReview.ts

@@ -3,7 +3,6 @@ import { schedulePiDailyPing } from "./daily-ping.ts";
 import { createPackageChangesService, MAX_PACKAGE_FILE_BYTES, PACKAGE_CHECKOUT_WAIT_MS, prSettingsSource, REMOTE_PACKAGE_READS, waitAtMost } from "../generated/package-changes-service.ts";
 import { parseDiffToFiles } from "../generated/diff-files.ts";
 import { isSameOriginOrNoOrigin } from "../generated/request-origin.ts";
-import { spawn } from "node:child_process";
 import { likelyAppHtmlEncoding, prewarmAppHtml } from "../generated/app-html.ts";
 import { openPackedApp } from "../generated/packed-app.ts";
 import {
@@ -232,14 +231,13 @@ import {
 import { resolveWorkspaceFilePath } from "../generated/review-workspace-node.ts";
 import {
 	type CodeNavRequest,
-	type CodeNavRuntime,
-	CODE_NAV_MAX_FILE_BYTES,
 	resolveCodeNav,
 	resolveCodeNavHover,
 	validateCodeNavRequest,
 	extractChangedFiles,
 } from "../generated/code-nav.ts";
-import { readFileCapped, readRepoFile, repoFileErrorBody, REPO_FILE_ERROR_STATUS } from "../generated/repo-file.ts";
+import { readRepoFile, repoFileErrorBody, REPO_FILE_ERROR_STATUS } from "../generated/repo-file.ts";
+import { piCodeNavRuntime } from "./code-nav-runtime.ts";
 import { readRepoWorkingTreeFile } from "../generated/repo-files-node.ts";
 import {
 	createDefaultSemanticDiffRuntime,
@@ -282,44 +280,6 @@ import {
 	vcsSupportsSnapshot,
 } from "./vcs.ts";
 
-const piCodeNavRuntime: CodeNavRuntime = {
-	runCommand(command, args, options) {
-		return new Promise((resolve) => {
-			const proc = spawn(command, args, {
-				cwd: options?.cwd,
-				stdio: ["ignore", "pipe", "pipe"],
-			});
-			let timer: ReturnType<typeof setTimeout> | undefined;
-			if (options?.timeoutMs) {
-				timer = setTimeout(() => proc.kill(), options.timeoutMs);
-			}
-			const stdoutChunks: Buffer[] = [];
-			const stderrChunks: Buffer[] = [];
-			proc.stdout!.on("data", (chunk: Buffer) => stdoutChunks.push(chunk));
-			proc.stderr!.on("data", (chunk: Buffer) => stderrChunks.push(chunk));
-			proc.on("close", (code: number | null) => {
-				if (timer) clearTimeout(timer);
-				resolve({
-					stdout: Buffer.concat(stdoutChunks).toString("utf-8"),
-					stderr: Buffer.concat(stderrChunks).toString("utf-8"),
-					exitCode: code ?? 1,
-				});
-			});
-			proc.on("error", () => {
-				if (timer) clearTimeout(timer);
-				resolve({ stdout: "", stderr: "command not found", exitCode: 1 });
-			});
-		});
-	},
-
-	async readFile(path, options) {
-		// Capped at what rg searches, non-blocking (repo-file.ts).
-		const read = await readFileCapped(options?.cwd ? resolvePath(options.cwd, path) : path, {
-			maxBytes: CODE_NAV_MAX_FILE_BYTES,
-		});
-		return read.ok ? read.content : null;
-	},
-};
 
 // Review ingestion completion semantics (REVIEW_OUTPUT_FAILED,
 // markJobReviewFailed) now live in the shared agent-jobs module.

package/server/serverShape.test.ts

@@ -0,0 +1,147 @@
+/**
+ * Shape's routes on both runtimes: the same requests on the same store answer
+ * the same on Pi (node:http, serverShape.ts) and on Bun
+ * (packages/server/shape-routes.ts), so the mirror cannot drift. Also: a
+ * cross-site read is refused, an image is served with a sandbox, and the event
+ * feed names a shape when an agent picks up its waiting change.
+ */
+import { afterEach, expect, test } from "bun:test";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { createServer, type Server } from "node:http";
+import type { AddressInfo } from "node:net";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createBunShapeRoutes } from "../../../packages/server/shape-routes.ts";
+import { createShapeStore } from "../../../packages/shared/shape/store.ts";
+import { createPiShapeRoutes } from "./serverShape.ts";
+
+const cleanups: (() => void)[] = [];
+afterEach(() => {
+	for (const done of cleanups.splice(0)) done();
+});
+
+function scratch(): string {
+	const dir = mkdtempSync(join(tmpdir(), "shape-pi-"));
+	cleanups.push(() => rmSync(dir, { recursive: true, force: true }));
+	return dir;
+}
+
+async function startPi(dataDir: string): Promise<string> {
+	const routes = createPiShapeRoutes({ dataDir, watchMs: 20 });
+	const server: Server = createServer((req, res) => {
+		const url = new URL(req.url ?? "/", "http://127.0.0.1");
+		void routes.handle(req, res, url).then((done) => {
+			if (!done) {
+				res.writeHead(404);
+				res.end();
+			}
+		});
+	});
+	await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
+	cleanups.push(() => {
+		server.closeAllConnections();
+		server.close();
+	});
+	return `http://127.0.0.1:${(server.address() as AddressInfo).port}`;
+}
+
+function startBun(dataDir: string): string {
+	const routes = createBunShapeRoutes({ dataDir, watchMs: 20 });
+	const server = Bun.serve({ hostname: "127.0.0.1", port: 0, idleTimeout: 0, fetch: async (req) => (await routes.route(req, new URL(req.url))) ?? new Response("", { status: 404 }) });
+	cleanups.push(() => server.stop(true));
+	return `http://127.0.0.1:${server.port}`;
+}
+
+function seed(dataDir: string) {
+	const store = createShapeStore({ dataDir });
+	const source = scratch();
+	writeFileSync(join(source, "shot.png"), Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]));
+	const made = store.update({
+		board: {
+			title: "The kettle whistles once",
+			claim: "Built.",
+			views: { picture: { html: '<p data-mark="p-a">once</p>' } },
+			refs: [{ n: 1, kind: "image", title: "Shot", target: "shot.png" }],
+		},
+		project: { name: "kettle", root: source },
+		sourceDir: source,
+	});
+	if (!made.ok) throw new Error(JSON.stringify(made));
+	return { store, id: made.id, file: store.read(made.id)!.refs![0]!.target.replace(/^files\//, "") };
+}
+
+/** Status and JSON (ids and times blanked: the two stores write their own notes). */
+async function call(base: string, method: string, path: string, body?: unknown, headers: Record<string, string> = {}) {
+	const res = await fetch(base + path, { method, headers: { "Content-Type": "application/json", ...headers }, body: body === undefined ? undefined : JSON.stringify(body) });
+	const type = res.headers.get("content-type") ?? "";
+	const text = type.includes("json") ? JSON.stringify(await res.json()).replace(/(shp_|shn_)[0-9A-HJKMNP-TV-Z]{26}/g, "$1ID").replace(/"root":"[^"]*"/g, '"root":"R"').replace(/"\d{4}-\d\d-\d\dT[^"]+"/g, '"AT"') : `${type}:${(await res.arrayBuffer()).byteLength}:${res.headers.get("content-security-policy")}`;
+	return `${res.status} ${text}`;
+}
+
+test("Pi answers every Shape route as Bun does", async () => {
+	const answers: string[][] = [];
+	for (const start of [startPi, async (d: string) => startBun(d)]) {
+		const dataDir = scratch();
+		const { id, file } = seed(dataDir);
+		const base = await start(dataDir);
+		const out: string[] = [];
+		out.push(await call(base, "GET", "/api/shapes"));
+		out.push(await call(base, "GET", `/api/shapes/${id}`));
+		out.push(await call(base, "GET", `/api/shapes/${id}/versions`));
+		out.push(await call(base, "GET", `/api/shapes/${id}?n=7`));
+		out.push(await call(base, "POST", `/api/shapes/${id}/notes`, { kind: "change", v: 1, view: "picture", part: "p-a", text: "Twice" }));
+		out.push(await call(base, "POST", `/api/shapes/${id}/notes`, { kind: "nope" }));
+		out.push(await call(base, "POST", `/api/shapes/${id}/seen`, { n: 1 }));
+		out.push(await call(base, "POST", `/api/shapes/${id}/state`, { state: "finished" }));
+		out.push(await call(base, "GET", `/api/shapes/${id}/files/${file}`));
+		out.push(await call(base, "GET", `/api/shapes/${id}/files/..%2Fshape.json`));
+		out.push(await call(base, "GET", `/api/shapes/${id}/code/file?path=../../etc/passwd`));
+		out.push(await call(base, "GET", `/api/shapes/${id}/code/file?path=shot.png`));
+		answers.push(out);
+	}
+	expect(answers[0]).toEqual(answers[1]!);
+	// The answers themselves (so "both equally wrong" fails too).
+	const [pi] = answers;
+	expect(pi![4]).toStartWith("200 ");
+	expect(pi![5]).toStartWith("400 ");
+	expect(pi![8]).toBe("200 image/png:8:sandbox");
+	expect(pi![9]).toStartWith("404 ");
+	expect(pi![10]).toStartWith("400 ");
+});
+
+test("Pi refuses another site's read and write", async () => {
+	const dataDir = scratch();
+	const { id } = seed(dataDir);
+	const base = await startPi(dataDir);
+	const other = { Origin: "https://evil.invalid", "Sec-Fetch-Site": "cross-site" };
+	expect(await call(base, "GET", `/api/shapes/${id}`, undefined, other)).toStartWith("403 ");
+	expect(await call(base, "POST", `/api/shapes/${id}/seen`, { n: 1 }, other)).toStartWith("403 ");
+});
+
+test("both feeds name the shape when an agent picks up its waiting change", async () => {
+	for (const start of [startPi, async (d: string) => startBun(d)]) {
+		const dataDir = scratch();
+		const { store, id } = seed(dataDir);
+		store.addNote(id, { kind: "change", v: 1, text: "Twice" });
+		const base = await start(dataDir);
+		const controller = new AbortController();
+		const res = await fetch(`${base}/api/shapes/events`, { signal: controller.signal });
+		const reader = res.body!.getReader();
+		let text = "";
+		const read = (async () => {
+			for (;;) {
+				const { value, done } = await reader.read();
+				if (done) break;
+				text += new TextDecoder().decode(value);
+				if (text.includes("event: shapes")) break;
+			}
+		})();
+		await Bun.sleep(60);
+		// The agent's `shape read --notes`: another process on the same folder.
+		const agent = createShapeStore({ dataDir });
+		agent.markDelivered(id, agent.waiting(id).map((n) => n.id));
+		await Promise.race([read, Bun.sleep(1500)]);
+		controller.abort();
+		expect(text).toContain(`event: shapes\ndata: {"ids":["${id}"]}`);
+	}
+});

package/server/serverShape.ts

@@ -0,0 +1,118 @@
+/**
+ * Shape's routes on node:http, for Pi (the Bun mirror is
+ * packages/server/shape-routes.ts; the route core is
+ * packages/shared/shape/routes.ts, vendored to generated/shape/). Same paths,
+ * same answers, same event feed: `GET /api/shapes/events` sends
+ * `event: shapes` `{ ids }` when a board changes, including when an agent's
+ * `plannotator shape read --notes` picks up a waiting change.
+ *
+ * Mount it like the other Pi routes: after the Host allowlist and the
+ * cross-origin write guard (request-origin-guard.ts). A cross-site read is
+ * refused here too, because a board names files and folders.
+ */
+import { createReadStream } from "node:fs";
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { isSameOriginOrNoOrigin } from "../generated/request-origin.ts";
+import { readRepoFile, repoFileErrorBody, REPO_FILE_ERROR_STATUS } from "../generated/repo-file.ts";
+import { resolveCodeNavHover, validateCodeNavRequest, type CodeNavRequest } from "../generated/code-nav.ts";
+import { createShapeStore, type ShapeStore } from "../generated/shape/store.ts";
+import { createShapeWatch, handleShapeRoute, SHAPE_EVENTS_PATH, shapeEventFrame, type ShapeRouteDeps } from "../generated/shape/routes.ts";
+import { piCodeNavRuntime } from "./code-nav-runtime.ts";
+import { readBody } from "./helpers.ts";
+
+const NO_STORE = { "Cache-Control": "no-store", "X-Content-Type-Options": "nosniff" } as const;
+
+const piShapeCode: NonNullable<ShapeRouteDeps["code"]> = {
+	async file(root, path) {
+		const read = await readRepoFile(root, path);
+		return read.ok ? { status: 200, body: { content: read.content } } : { status: REPO_FILE_ERROR_STATUS[read.reason], body: repoFileErrorBody(read) };
+	},
+	async hover(root, body) {
+		const error = validateCodeNavRequest(body);
+		if (error) return { status: 400, body: { error } };
+		try {
+			return { status: 200, body: await resolveCodeNavHover(piCodeNavRuntime, body as CodeNavRequest, root, []) };
+		} catch (err) {
+			return { status: 500, body: { error: err instanceof Error ? err.message : "Code navigation failed" } };
+		}
+	},
+};
+
+/**
+ * NOT MOUNTED, and must not be until it has what the Bun Inbox has around it: Pi has no Shape switch (the Inbox's
+ * Settings → Capabilities → Shape, config `inboxShape`: off answers 404), no owner check (a tailnet guest is
+ * refused there) and no `serverSession` check on writes (409 for a page of a restarted server). Whoever mounts
+ * this adds all three first.
+ */
+export function createPiShapeRoutes(options: { dataDir: string; heartbeatMs?: number; watchMs?: number; sessionOf?: ShapeRouteDeps["sessionOf"] }) {
+	const store: ShapeStore = createShapeStore({ dataDir: options.dataDir });
+	const watch = createShapeWatch(store, { intervalMs: options.watchMs });
+	const deps: ShapeRouteDeps = { store, sessionOf: options.sessionOf, changed: () => watch.poke(), code: piShapeCode };
+
+	const sendJson = (res: ServerResponse, status: number, body: unknown) => {
+		res.writeHead(status, { "Content-Type": "application/json", ...NO_STORE });
+		res.end(JSON.stringify(body));
+	};
+
+	function events(req: IncomingMessage, res: ServerResponse) {
+		res.writeHead(200, { "Content-Type": "text/event-stream", Connection: "keep-alive", ...NO_STORE });
+		res.write("retry: 2000\nevent: hello\ndata: {}\n\n");
+		const unsubscribe = watch.subscribe((ids) => res.write(shapeEventFrame(ids)));
+		const beat = setInterval(() => res.write(": ping\n\n"), options.heartbeatMs ?? 25_000);
+		const stop = () => {
+			clearInterval(beat);
+			unsubscribe();
+		};
+		req.on("close", stop);
+		res.on("close", stop);
+	}
+
+	return {
+		store,
+		watch,
+		/** Answers a Shape path and returns true; false when the path is not Shape's. */
+		async handle(req: IncomingMessage, res: ServerResponse, url: URL): Promise<boolean> {
+			if (url.pathname !== "/api/shapes" && !url.pathname.startsWith("/api/shapes/")) return false;
+			const origin = typeof req.headers.origin === "string" ? req.headers.origin : null;
+			if (!isSameOriginOrNoOrigin(origin, req.headers.host ?? "", req.headers["sec-fetch-site"])) {
+				sendJson(res, 403, { error: "Cross-origin requests are not accepted.", code: "cross_origin" });
+				return true;
+			}
+			if (url.pathname === SHAPE_EVENTS_PATH) {
+				if (req.method !== "GET") sendJson(res, 405, { error: "method not allowed" });
+				else events(req, res);
+				return true;
+			}
+			let text: string | null = null;
+			const answer = await handleShapeRoute(
+				{
+					method: req.method ?? "GET",
+					pathname: url.pathname,
+					params: url.searchParams,
+					json: async () => JSON.parse((text ??= await readBody(req))),
+				},
+				deps,
+			);
+			if (!answer) {
+				sendJson(res, 404, { error: "Not found", code: "not_found" });
+				return true;
+			}
+			if ("file" in answer) {
+				// Opened before the head is written: a file gone between the check and the read is a 404, and an error
+				// mid-read ends the response instead of an unhandled 'error' event taking the process down.
+				const file = createReadStream(answer.file.path);
+				file.on("error", () => {
+					if (!res.headersSent) sendJson(res, 404, { error: "Not found", code: "not_found" });
+					else res.destroy();
+				});
+				file.once("open", () => {
+					res.writeHead(200, { "Content-Type": answer.file.contentType, "Cross-Origin-Resource-Policy": "same-origin", "Content-Security-Policy": "sandbox", ...NO_STORE });
+					file.pipe(res);
+				});
+				return true;
+			}
+			sendJson(res, answer.status, answer.body);
+			return true;
+		},
+	};
+}

package/skills/plannotator/SKILL.md

@@ -190,6 +190,15 @@ The Plannotator Inbox is one local window per machine where you leave the person
 - Never run `plannotator inbox` just to send: calls start a stopped Inbox in the background, and bare `plannotator inbox` opens the window for the person. `--tailscale` is the person's choice; never add it. `plannotator inbox status` only reads; never run `plannotator inbox stop` or `restart` unless the person asks.
 - When the person asks where their Inbox is, or to open it (a closed tab), run `plannotator inbox --open`: it opens the window in their browser (starting the Inbox in the background if needed), prints its address on stdout and returns at once. Tell them the address.
 
+## plannotator t3
+
+```bash
+plannotator t3 login --url <T3 MCP URL>
+plannotator t3 logout --url <T3 MCP URL>
+```
+
+If the person uses T3 Code, set it up once so their Inbox replies reach Claude threads in T3 as new turns: run `plannotator t3 --help` and follow its two steps. The person approves T3's sign-in page themselves.
+
 ## plannotator card
 
 ```bash