@plannotator/pi-extension 0.27.5 → 0.27.6

package/server/serverAnnotate-live.test.ts

@@ -0,0 +1,273 @@
+/**
+ * Annotate server (Pi/Node): live app mode (annotate-app)
+ *
+ * Node mirror of packages/server/annotate.test.ts's "live app mode" describe
+ * block — the same session contract (live /api/plan payload, composed bridge
+ * served by the loopback proxy, per-target draft identity, no version
+ * history, guarded shutdown) over apps/pi-extension/server/serverAnnotate.ts
+ * and the vendored Node live-proxy transport, plus the remote hard-off that
+ * Pi enforces server-side.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, readdirSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { startAnnotateServer } from "./serverAnnotate.ts";
+import { liveAppDraftIdentity } from "../generated/live-proxy-core.ts";
+
+const MINIMAL_HTML = "<html><body>editor</body></html>";
+
+describe("pi annotate server: live app mode (annotate-app)", () => {
+	let savedPort: string | undefined;
+	let savedRemote: string | undefined;
+
+	beforeEach(() => {
+		savedPort = process.env.PLANNOTATOR_PORT;
+		savedRemote = process.env.PLANNOTATOR_REMOTE;
+		delete process.env.PLANNOTATOR_PORT;
+		process.env.PLANNOTATOR_REMOTE = "0";
+	});
+
+	afterEach(() => {
+		if (savedPort === undefined) delete process.env.PLANNOTATOR_PORT;
+		else process.env.PLANNOTATOR_PORT = savedPort;
+		if (savedRemote === undefined) delete process.env.PLANNOTATOR_REMOTE;
+		else process.env.PLANNOTATOR_REMOTE = savedRemote;
+	});
+
+	function startFakeApp() {
+		return Bun.serve({
+			hostname: "127.0.0.1",
+			port: 0,
+			fetch: () =>
+				new Response("<html><head><title>app</title></head><body>app</body></html>", {
+					headers: { "Content-Type": "text/html" },
+				}),
+		});
+	}
+
+	async function startLiveServer(targetUrl: string) {
+		return startAnnotateServer({
+			markdown: "",
+			filePath: targetUrl,
+			htmlContent: MINIMAL_HTML,
+			mode: "annotate-app",
+			sourceInfo: targetUrl,
+			sharingEnabled: false,
+			liveApp: {
+				targetUrl,
+				bridgeScript: "/* bridge body */",
+				bridgeBootstrap: "/* bootstrap body */",
+				annotationCss: ".pn-live {}",
+			},
+		});
+	}
+
+	test("/api/plan returns the live payload and the proxy serves the composed bridge", async () => {
+		const app = startFakeApp();
+		const targetUrl = `http://127.0.0.1:${app.port}`;
+		const server = await startLiveServer(targetUrl);
+
+		try {
+			const plan = (await (await fetch(`${server.url}/api/plan`)).json()) as Record<string, unknown>;
+			expect(plan.mode).toBe("annotate-app");
+			expect(plan.origin).toBe("pi");
+			expect(plan.filePath).toBe(targetUrl);
+			expect(plan.targetUrl).toBe(targetUrl);
+			expect(plan.liveToken).toMatch(/^[0-9a-f]{32}$/);
+			expect(plan.sharingEnabled).toBe(false);
+			expect(plan.convertHtml).toBe(false);
+			// appUrl is the live loopback proxy under its LOCALHOST spelling (so
+			// the framed app is same-site with the editor and shares the dev
+			// app's host-only localhost cookies), never an advertised-host URL.
+			expect(plan.appUrl).toMatch(/^http:\/\/localhost:\d+\/$/);
+			// No srcdoc payloads, no version fields.
+			expect(plan.rawHtml).toBeUndefined();
+			expect(plan.renderAs).toBeUndefined();
+			expect(plan.previousPlan).toBeUndefined();
+			expect(plan.versionInfo).toBeUndefined();
+			expect(plan.diffCurrent).toBeUndefined();
+			// Agent terminal stays unavailable for live sessions.
+			expect((plan.agentTerminal as { enabled: boolean }).enabled).toBe(false);
+
+			// The proxy serves the composed bridge body: config prelude with the
+			// session token and both editor origin forms (localhost first), then
+			// bootstrap, then bridge.
+			const appUrl = plan.appUrl as string;
+			const bridge = await (await fetch(`${appUrl}__plannotator__/bridge.js`)).text();
+			expect(bridge).toContain(String(plan.liveToken));
+			const localhostAt = bridge.indexOf(`http://localhost:${server.port}`);
+			const loopbackAt = bridge.indexOf(`http://127.0.0.1:${server.port}`);
+			expect(localhostAt).toBeGreaterThanOrEqual(0);
+			expect(loopbackAt).toBeGreaterThan(localhostAt);
+			expect(bridge).toContain(".pn-live {}");
+			expect(bridge.indexOf("/* bootstrap body */")).toBeLessThan(bridge.indexOf("/* bridge body */"));
+
+			// The proxied page carries the injected bridge script tag.
+			const page = await (await fetch(appUrl)).text();
+			expect(page).toContain('<script src="/__plannotator__/bridge.js"></script>');
+		} finally {
+			server.stop();
+			app.stop(true);
+		}
+	});
+
+	test("a pathful target URL keeps its path and query in appUrl", async () => {
+		// Annotating http://localhost:5173/admin/settings must open that page,
+		// not the app root.
+		const app = startFakeApp();
+		const targetUrl = `http://127.0.0.1:${app.port}/admin/settings?tab=2`;
+		const server = await startLiveServer(targetUrl);
+		try {
+			const plan = (await (await fetch(`${server.url}/api/plan`)).json()) as { appUrl: string };
+			expect(plan.appUrl).toMatch(/^http:\/\/localhost:\d+\/admin\/settings\?tab=2$/);
+			// The advertised page is reachable through the proxy under the
+			// localhost Host spelling.
+			const res = await fetch(plan.appUrl);
+			expect(res.status).toBe(200);
+		} finally {
+			server.stop();
+			app.stop(true);
+		}
+	});
+
+	test("version endpoints report no history for live sessions", async () => {
+		const app = startFakeApp();
+		const server = await startLiveServer(`http://127.0.0.1:${app.port}`);
+		try {
+			const versions = (await (await fetch(`${server.url}/api/plan/versions`)).json()) as {
+				slug: string | null;
+				versions: unknown[];
+			};
+			expect(versions.slug).toBeNull();
+			expect(versions.versions).toEqual([]);
+			const version = await fetch(`${server.url}/api/plan/version?v=1`);
+			expect(version.status).toBe(404);
+		} finally {
+			server.stop();
+			app.stop(true);
+		}
+	});
+
+	test("stop() closes the proxy port with the server", async () => {
+		const app = startFakeApp();
+		const server = await startLiveServer(`http://127.0.0.1:${app.port}`);
+		const plan = (await (await fetch(`${server.url}/api/plan`)).json()) as { appUrl: string };
+		// Reachable while running.
+		expect((await fetch(plan.appUrl)).status).toBe(200);
+		server.stop();
+		await Bun.sleep(50);
+		let closed = false;
+		try {
+			await fetch(plan.appUrl, { signal: AbortSignal.timeout(1000) });
+		} catch {
+			closed = true;
+		}
+		expect(closed).toBe(true);
+		app.stop(true);
+	});
+
+	test("remote sessions refuse live app mode outright", async () => {
+		// Defense in depth behind the command-side check: a live proxy relays
+		// the user's authenticated dev app, and a remote Pi session is
+		// reachable beyond loopback. No override env var exists on purpose.
+		const app = startFakeApp();
+		process.env.PLANNOTATOR_REMOTE = "1";
+		try {
+			await expect(startLiveServer(`http://127.0.0.1:${app.port}`)).rejects.toThrow(
+				"Live app annotation is unavailable in remote mode",
+			);
+		} finally {
+			process.env.PLANNOTATOR_REMOTE = "0";
+			app.stop(true);
+		}
+	});
+
+	describe("draft isolation between live sessions", () => {
+		// A live session holds no document text (markdown is "" by
+		// construction), so keying its draft by content would give every live
+		// session on the machine the one hash of the empty string. The target
+		// is the identity, shared with the Bun server via liveAppDraftIdentity.
+		const savedDataDir = process.env.PLANNOTATOR_DATA_DIR;
+		let draftDataDir: string;
+
+		beforeEach(() => {
+			draftDataDir = mkdtempSync(join(tmpdir(), "plannotator-pi-live-draft-"));
+			process.env.PLANNOTATOR_DATA_DIR = draftDataDir;
+		});
+
+		afterEach(() => {
+			if (savedDataDir === undefined) delete process.env.PLANNOTATOR_DATA_DIR;
+			else process.env.PLANNOTATOR_DATA_DIR = savedDataDir;
+			rmSync(draftDataDir, { recursive: true, force: true });
+		});
+
+		async function saveDraft(server: { url: string }, feedback: string): Promise<void> {
+			const res = await fetch(`${server.url}/api/draft`, {
+				method: "POST",
+				headers: { "Content-Type": "application/json" },
+				body: JSON.stringify({ feedback, annotations: [] }),
+			});
+			expect(res.status).toBe(200);
+		}
+
+		async function loadDraft(server: { url: string }): Promise<{ feedback?: string } | null> {
+			const res = await fetch(`${server.url}/api/draft`);
+			if (res.status === 404) return null;
+			expect(res.status).toBe(200);
+			return (await res.json()) as { feedback?: string };
+		}
+
+		test("two live sessions on different targets keep independent drafts", async () => {
+			const appX = startFakeApp();
+			const appY = startFakeApp();
+			const serverX = await startLiveServer(`http://127.0.0.1:${appX.port}`);
+			const serverY = await startLiveServer(`http://127.0.0.1:${appY.port}`);
+			try {
+				await saveDraft(serverX, "notes for X");
+				await saveDraft(serverY, "notes for Y");
+
+				// Neither session sees the other's text, in either direction.
+				expect((await loadDraft(serverX))?.feedback).toBe("notes for X");
+				expect((await loadDraft(serverY))?.feedback).toBe("notes for Y");
+				expect(readdirSync(join(draftDataDir, "drafts")).length).toBe(2);
+			} finally {
+				serverX.stop();
+				serverY.stop();
+				appX.stop(true);
+				appY.stop(true);
+			}
+		});
+
+		test("the same target recovers its draft after a restart", async () => {
+			const app = startFakeApp();
+			const targetUrl = `http://127.0.0.1:${app.port}`;
+			const first = await startLiveServer(targetUrl);
+			try {
+				await saveDraft(first, "survives the crash");
+			} finally {
+				first.stop();
+			}
+			// Same target, spelled with a trailing slash the way a browser would
+			// hand it back: the draft is the point of the key, so it must survive.
+			const second = await startLiveServer(`${targetUrl}/`);
+			try {
+				expect((await loadDraft(second))?.feedback).toBe("survives the crash");
+			} finally {
+				second.stop();
+				app.stop(true);
+			}
+		});
+
+		test("the vendored identity matches the Bun server's normalization", () => {
+			const a = liveAppDraftIdentity("http://127.0.0.1:5173");
+			expect(liveAppDraftIdentity("http://127.0.0.1:5173/")).toBe(a);
+			expect(liveAppDraftIdentity("http://127.0.0.1:5174")).not.toBe(a);
+			expect(liveAppDraftIdentity("http://127.0.0.1:5173/admin/")).toBe(
+				liveAppDraftIdentity("http://127.0.0.1:5173/admin"),
+			);
+			expect(liveAppDraftIdentity("not a url")).toBe("not a url");
+		});
+	});
+});

package/server/serverAnnotate.ts

@@ -2,7 +2,16 @@ import { createServer } from "node:http";
 import type { IncomingMessage } from "node:http";
 import { dirname, resolve as resolvePath } from "node:path";
 import { existsSync, readFileSync, statSync } from "node:fs";
-import { randomUUID } from "node:crypto";
+import { randomBytes, randomUUID } from "node:crypto";
+
+import {
+	buildLiveAppUrl,
+	buildLiveEditorOrigins,
+	composeLiveBridgeJs,
+	liveAppDraftIdentity,
+} from "../generated/live-proxy-core.ts";
+import { startLiveAppProxyNode } from "../generated/live-proxy-node.ts";
+import type { LiveAppProxy } from "../generated/live-proxy-core.ts";
 
 import { contentHash, deleteDraft } from "../generated/draft.ts";
 import { getPlanVersion, getVersionCount, listVersions } from "../generated/storage.ts";
@@ -224,7 +233,28 @@ export async function startAnnotateServer(options: {
 	agentCwd?: string;
 	/** Project name for keying per-file version history (powers the annotate version diff). */
 	project?: string;
+	/**
+	 * Live local app annotation (mode "annotate-app"): the server starts a
+	 * loopback reverse proxy (node:http transport over the shared core)
+	 * mirroring targetUrl and serves the composed bridge body from it. The
+	 * caller supplies the bridge sources; the server owns the per-session
+	 * token. Refused outright in remote mode.
+	 */
+	liveApp?: {
+		targetUrl: string;
+		bridgeScript: string;
+		bridgeBootstrap: string;
+		annotationCss: string;
+	};
 }): Promise<AnnotateServerResult> {
+	// Remote hard-off, defense in depth behind the command-side check: a live
+	// proxy relays the user's authenticated dev app, so it must never coexist
+	// with a beyond-loopback annotate bind. No override env var exists on
+	// purpose (mirrors packages/server/annotate.ts).
+	if (options.liveApp && isRemoteSession()) {
+		throw new Error("Live app annotation is unavailable in remote mode");
+	}
+
 	const gitUser = detectGitUser();
 	const sharingEnabled =
 		options.sharingEnabled ?? resolveSharingEnabled(loadConfig());
@@ -275,11 +305,19 @@ export async function startAnnotateServer(options: {
 		{ graceMs: clientLeaseGraceMs },
 	);
 
-	// Folder annotation has no stable markdown body, so key drafts by folder path instead.
+	// Draft identity. Content-derived for the modes that HAVE content, and
+	// path-derived for the modes that do not: a live app session resolves
+	// `markdown` to "" by construction (the page lives behind the proxy), so
+	// its target is its identity — hashing the empty body would give every
+	// live session on the machine one shared draft slot. Folder sessions key
+	// by folder path for the same reason. liveAppDraftIdentity is the shared
+	// normalization, so Bun and Pi sessions key the same target identically.
 	const draftSource =
-		options.mode === "annotate-folder" && options.folderPath
-			? `folder:${resolvePath(options.folderPath)}`
-			: options.renderHtml && options.rawHtml ? options.rawHtml : options.markdown;
+		options.mode === "annotate-app" && options.liveApp
+			? `annotate-app\0${liveAppDraftIdentity(options.liveApp.targetUrl)}`
+			: options.mode === "annotate-folder" && options.folderPath
+				? `folder:${resolvePath(options.folderPath)}`
+				: options.renderHtml && options.rawHtml ? options.rawHtml : options.markdown;
 	const draftKey = contentHash(draftSource);
 
 	// Per-file version history → powers the native version diff in annotate mode.
@@ -290,10 +328,13 @@ export async function startAnnotateServer(options: {
 	const annotateProjectName = options.project ?? "_unknown";
 	const annotateHistoryEnabled = resolveAnnotateHistory(loadConfig());
 	// Single local file sessions are the only ones this eager gate covers.
-	// URL and agent-message sessions never write session content to the data
-	// dir. Folder sessions do participate in per-file version history, but
-	// lazily through /api/doc (see computeFolderAnnotateHistory below), not
-	// here. The durable submit records stay single-local-file only.
+	// URL, agent-message, and live-app sessions never write session content to
+	// the data dir. Folder sessions do participate in per-file version history,
+	// but lazily through /api/doc (see computeFolderAnnotateHistory below), not
+	// here. The durable submit records stay single-local-file only. The
+	// mode === "annotate" check is deliberate and explicit: "annotate-app"
+	// (whose filePath is URL-shaped anyway) must never become history-eligible
+	// by accident.
 	const singleFileLocalAnnotate =
 		(options.mode || "annotate") === "annotate" && !/^https?:\/\//i.test(options.filePath);
 	let annotateHistory: AnnotateHistoryResult | null = null;
@@ -499,6 +540,13 @@ export async function startAnnotateServer(options: {
 		initialSingleFileSourcePath,
 	});
 
+	// Live app session state, populated after the annotate port is known (the
+	// editor origins carry the port) and before the URL is returned to the
+	// caller for advertisement.
+	let liveProxy: LiveAppProxy | null = null;
+	let liveSessionToken = "";
+	let liveAppUrl = "";
+
 	const server = createServer(async (req, res) => {
 		const url = requestUrl(req);
 
@@ -541,7 +589,41 @@ export async function startAnnotateServer(options: {
 			return;
 		}
 
-		if (url.pathname === "/api/plan" && req.method === "GET") {
+		if (url.pathname === "/api/plan" && req.method === "GET" && options.mode === "annotate-app" && options.liveApp) {
+			// Live app session: no rawHtml, no renderAs, no version fields,
+			// sharing off. The client frames appUrl (the loopback proxy) and
+			// authenticates the bridge with liveToken. Mirrors the Bun
+			// server's annotate-app payload (packages/server/annotate.ts).
+			json(res, {
+				plan: "",
+				origin: options.origin ?? "pi",
+				mode: options.mode,
+				filePath: options.filePath,
+				sourceInfo: options.sourceInfo ?? options.liveApp.targetUrl,
+				appUrl: liveAppUrl,
+				targetUrl: options.liveApp.targetUrl,
+				liveToken: liveSessionToken,
+				gate: options.gate ?? false,
+				approvalNotesSupported: options.approvalNotesSupported ?? false,
+				clientLease: options.clientLeaseSupported
+					? { enabled: true as const, reconnectGraceMs: clientLeaseGraceMs }
+					: { enabled: false as const },
+				sharingEnabled: false,
+				convertHtml: false,
+				repoInfo,
+				projectRoot: process.cwd(),
+				serverConfig: getServerConfig(gitUser),
+				agentTerminal: agentTerminalCapability,
+				feedbackTemplates: {
+					fileFeedback: getAnnotateFileFeedbackTemplate(
+						(options.origin ?? "pi") as PromptRuntime,
+					),
+					messageFeedback: getAnnotateMessageFeedbackTemplate(
+						(options.origin ?? "pi") as PromptRuntime,
+					),
+				},
+			});
+		} else if (url.pathname === "/api/plan" && req.method === "GET") {
 			const displayRawHtml = options.renderHtml && options.rawHtml
 				? htmlAssets.rewriteHtml(options.rawHtml, options.filePath)
 				: undefined;
@@ -928,6 +1010,55 @@ export async function startAnnotateServer(options: {
 
 	const { port, portSource } = await listenOnPort(server);
 
+	if (options.liveApp) {
+		// Compose the proxy-served bridge body via the shared assembly (config
+		// prelude with the token this server owns, both editor origin forms
+		// with the localhost one first to match the advertised URL, then the
+		// bootstrap that installs the CSS, then the bridge itself). A proxy
+		// startup failure must not leave the annotate listener hanging.
+		try {
+			liveSessionToken = randomBytes(16).toString("hex");
+			const editorOrigins = buildLiveEditorOrigins(port);
+			liveProxy = await startLiveAppProxyNode({
+				targetUrl: options.liveApp.targetUrl,
+				editorOrigins,
+				bridgeJs: composeLiveBridgeJs({
+					token: liveSessionToken,
+					editorOrigins,
+					annotationCss: options.liveApp.annotationCss,
+					bridgeBootstrap: options.liveApp.bridgeBootstrap,
+					bridgeScript: options.liveApp.bridgeScript,
+				}),
+			});
+			// Advertise the proxy under the LOCALHOST spelling, carrying the
+			// target URL's own path and query (see buildLiveAppUrl in the
+			// shared core for the same-site/cookie rationale).
+			// PLANNOTATOR_URL_HOST is never applied here.
+			liveAppUrl = buildLiveAppUrl(liveProxy.port, options.liveApp.targetUrl);
+		} catch (error) {
+			// Same disposal set the normal stop() runs, each step guarded so
+			// the original startup error is what propagates.
+			for (const dispose of [
+				() => closeAllFileBrowserWatchers(),
+				() => {
+					clientLease.cancel();
+					clientLease.closeSessions();
+				},
+				() => aiRuntime?.dispose(),
+				() => agentTerminal.dispose(),
+			]) {
+				try {
+					dispose();
+				} catch {
+					// startup failure cleanup: best effort
+				}
+			}
+			server.close();
+			(server as { closeAllConnections?: () => void }).closeAllConnections?.();
+			throw error;
+		}
+	}
+
 	// Mirror the Bun server: bind first, then warm through the async shared walk.
 	void warmFileListCache(process.cwd(), "code");
 
@@ -954,6 +1085,11 @@ export async function startAnnotateServer(options: {
 				}],
 				["AI runtime", () => aiRuntime?.dispose()],
 				["agent terminal", () => agentTerminal.dispose()],
+				// Live proxy last, mirroring the Bun server's guarded order: a
+				// throw in the historically fragile agent-terminal teardown
+				// (#1314) must never orphan the proxy's listener or its
+				// upstream sockets.
+				["live proxy", () => liveProxy?.stop()],
 			];
 			try {
 				for (const [name, dispose] of disposals) {