@gavin-hu/my-pi-agent 0.20.0 → 0.22.0

package/extensions/plan/web-router.ts

@@ -1,10 +1,11 @@
 /**
  * The request router for browser plan review.
  *
- * A request is validated (method, `Host`, origin, token), matched to a route,
- * and answered with a plain {@link ServeResponse}, so every route can be tested
- * without a socket. The `/events` route is a marker: the node server in `web.ts`
- * keeps that response open as a Server-Sent Events stream.
+ * A request is validated (method, `Host`, origin, token, and — on a route that
+ * reads a body — that the body is JSON), matched to a route, and answered with a
+ * plain {@link ServeResponse}, so every route can be tested without a socket. The
+ * `/events` route is a marker: the node server in `web.ts` keeps that response open
+ * as a Server-Sent Events stream.
  *
  * The token is a per-session secret carried in the page URL, and on a shared
  * review it is the only credential a reviewer has: it names the caller — the
@@ -20,6 +21,7 @@ import {
 	pageHeaders,
 	parseRequestUrl,
 	postOnly,
+	requireJsonBody,
 	scriptHeaders,
 	type ServeResponse,
 } from "../../lib/http/index.ts";
@@ -40,7 +42,7 @@ export interface ReviewContext {
 	caller: (token: string) => ReviewCaller | undefined;
 	/** The host names this server answers to now, so a rebound page is refused. */
 	hosts: () => readonly string[];
-	/** Whether the browser may approve the plan (only the `exit_plan_mode` flow). */
+	/** Whether the browser may approve the plan (only the `plan` tool's `exit` flow). */
 	canApprove: boolean;
 	/** Build the page data for the caller (recomputed per request). */
 	page: (caller: ReviewCaller) => Promise<ReviewPageData>;
@@ -157,7 +159,9 @@ export async function handleReviewRequest(
 	}
 	if (pathname === "/api/share/revoke") {
 		const refusal =
-			postOnly(method, "revoke a link") ?? roleOnly(caller, ["owner"], "Only the plan owner can revoke a link.");
+			postOnly(method, "revoke a link") ??
+			requireJsonBody(headers["content-type"]) ??
+			roleOnly(caller, ["owner"], "Only the plan owner can revoke a link.");
 		if (refusal) return refusal;
 		const id = linkIdOf(body);
 		if (id === undefined) return jsonError(400, "The request body must name the link's id.");
@@ -169,7 +173,9 @@ export async function handleReviewRequest(
 		// A reviewer's whole surface: persist the comments they wrote and end
 		// nothing. Only the owner's own save decides the review.
 		const refusal =
-			postOnly(method, "post comments") ?? roleOnly(caller, ["reviewer"], "Only a shared reviewer posts comments.");
+			postOnly(method, "post comments") ??
+			requireJsonBody(headers["content-type"]) ??
+			roleOnly(caller, ["reviewer"], "Only a shared reviewer posts comments.");
 		if (refusal) return refusal;
 		const annotations = parseAnnotations(body);
 		if (isResponse(annotations)) return annotations;
@@ -182,6 +188,7 @@ export async function handleReviewRequest(
 		// `/api/comment`, so this route can never settle a shared review.
 		const refusal =
 			postOnly(method, "save feedback") ??
+			requireJsonBody(headers["content-type"]) ??
 			roleOnly(caller, ["owner"], "Only the plan owner saves this review; a reviewer posts comments.");
 		if (refusal) return refusal;
 		const annotations = parseAnnotations(body);
@@ -192,10 +199,12 @@ export async function handleReviewRequest(
 		return jsonResponse(200, { ok: true });
 	}
 	if (pathname === "/api/approve") {
-		// Only the owner's own page approves, and only the exit_plan_mode flow owns
+		// Only the owner's own page approves, and only the `exit` flow owns
 		// the side effects: a reviewer token is refused whatever it posts.
 		const refusal =
-			postOnly(method, "approve") ?? roleOnly(caller, ["owner"], "A shared review cannot approve the plan.");
+			postOnly(method, "approve") ??
+			requireJsonBody(headers["content-type"]) ??
+			roleOnly(caller, ["owner"], "A shared review cannot approve the plan.");
 		if (refusal) return refusal;
 		if (!ctx.canApprove) return jsonError(403, "This review cannot be approved from the browser.");
 		const annotations = parseAnnotations(body);

package/extensions/plan/web-settle.ts

@@ -15,10 +15,12 @@
 export interface SettleDeps {
 	/** The path a write goes to, without its query string. */
 	token(): string;
+	/** The review's mount on the session's server, e.g. `/plan/3f9c21aa`. */
+	base(): string;
 	role(): string;
 	/** The comments this writer may write: her own when she is a reviewer, all when owner. */
-	mine(): readonly unknown[];
-	annotations(): readonly unknown[];
+	mine(): readonly { author?: string }[];
+	annotations(): readonly { author?: string }[];
 	/** Whether the review has already ended, by any of the three routes. */
 	settled(): boolean;
 	setStatus(text: string, kind?: string): void;
@@ -82,9 +84,14 @@ export function submitAnnotations(
 				if (onOk) onOk();
 				deps.updateState();
 				// The server binds a reviewer's name to her link on the first post, so a
-				// second tab of the same link posts under the same name.
+				// second tab of the same link posts under the same name — and it may normalise
+				// what she typed (`@alice` is stored as `alice`). The comments she just posted
+				// are in the file under the bound name, so the page's copy has to say that too:
+				// otherwise they stop being hers to edit, and her next post would replace
+				// markers it never sent.
 				const body = result.body as { author?: unknown } | null;
 				if (deps.role() === "reviewer" && body && typeof body.author === "string" && body.author) {
+					for (const annotation of payload) if (annotation.author !== undefined) annotation.author = body.author;
 					deps.adoptName(body.author);
 				}
 				return { outcome: "ok" as const };
@@ -117,7 +124,7 @@ export function saveReview(deps: SettleDeps): Promise<SettleResult> | null {
 	deps.setStatus("Saving\u2026");
 	return submitAnnotations(
 		deps,
-		"/api/feedback",
+		deps.base() + "/api/feedback",
 		"Saved \u2014 return to Pi to continue.",
 		"Could not save: ",
 		function () {
@@ -140,7 +147,7 @@ export function postReviewComments(deps: SettleDeps): Promise<SettleResult> | nu
 	deps.setStatus("Posting\u2026");
 	return submitAnnotations(
 		deps,
-		"/api/comment",
+		deps.base() + "/api/comment",
 		"Comments posted \u2014 the owner sees them now.",
 		"Could not post: ",
 		null,
@@ -153,7 +160,7 @@ export function approveReview(deps: SettleDeps): Promise<SettleResult> | null {
 	deps.setStatus("Approving\u2026");
 	return submitAnnotations(
 		deps,
-		"/api/approve",
+		deps.base() + "/api/approve",
 		"Approved \u2014 return to Pi to continue.",
 		"Could not approve: ",
 		function () {
@@ -180,7 +187,7 @@ export function cancelReview(deps: SettleDeps): Promise<void> | null {
 	deps.setStatus("Closing\u2026");
 	deps.updateState();
 	return deps
-		.send("/api/cancel?token=" + encodeURIComponent(deps.token()))
+		.send(deps.base() + "/api/cancel?token=" + encodeURIComponent(deps.token()))
 		.catch(function () {})
 		.then(function () {
 			deps.setStatus("Closed \u2014 return to Pi.");

package/extensions/plan/web-share-session.ts

@@ -8,31 +8,25 @@
  * hooks, and the frame hooks, so it never reaches into the session's maps.
  */
 
-import { LOOPBACK_HOSTS, type LoopbackHandler, type LoopbackServer, serveLoopback } from "../../lib/http/index.ts";
+import { type HttpMount, LOOPBACK_HOSTS, type SharedListener } from "../../lib/http/index.ts";
 import { qrSvg } from "../../lib/qr.ts";
 import type { ReviewFrame, ReviewRole } from "./types.ts";
 import {
 	AT_CAP_REASON,
 	createLinkTable,
-	lanAddresses,
 	NO_SHARE_REASON,
 	shareUrl,
 	type LinkTable,
-	type NetworkInterfaces,
 	type ShareResult,
 	type ShareState,
 } from "./web-share.ts";
 
 /** What the share listener needs from the review session it belongs to. */
 export interface ShareSessionDeps {
-	/** The one request handler: a loopback page and a shared page are the same page. */
-	handleRequest: LoopbackHandler;
-	/** The body cap both listeners read under, so a shared page is not read differently. */
-	maxBodyBytes: number;
-	/** The owner's bound port, reused for the link when it is free. */
-	ownerPort: () => number;
-	/** The machine's interfaces, or a snapshot a test injected. */
-	networkInterfaces: () => NetworkInterfaces;
+	/** The review's mount on the session's server; sharing borrows its LAN listener. */
+	mount: HttpMount;
+	/** The mount's prefix, so a reviewer's link names the same page the owner has. */
+	base: string;
 	/** Add a reviewer token to the session's role map. */
 	mintReviewer: () => string;
 	/** Remove a reviewer token from the session's role map. */
@@ -64,16 +58,14 @@ export interface ShareSession {
 }
 
 export function createShareSession(deps: ShareSessionDeps): ShareSession {
-	let address = "";
-	let port = 0;
-	let server: LoopbackServer | undefined;
+	let shared: SharedListener | undefined;
 	const links: LinkTable = createLinkTable({
 		mint: deps.mintReviewer,
 		revoke: deps.revokeReviewer,
 		nameOf: deps.nameOf,
 	});
 	let reason: string | undefined;
-	const hosts = (): readonly string[] => (address ? [...LOOPBACK_HOSTS, address] : [...LOOPBACK_HOSTS]);
+	const hosts = (): readonly string[] => (shared ? [...LOOPBACK_HOSTS, shared.address] : [...LOOPBACK_HOSTS]);
 
 	/**
 	 * The share surface as it is now, read rather than cached: a link's bound name
@@ -81,42 +73,22 @@ export function createShareSession(deps: ShareSessionDeps): ShareSession {
 	 * another share action.
 	 */
 	const snapshot = (): ShareState => {
-		const base: ShareState = server === undefined ? { sharing: false, port: 0, links: [] } : links.state(port, address);
-		return reason === undefined ? base : { ...base, reason };
-	};
-
-	/** Bind the shared listener on `chosen`, reusing the owner's port when it is free. */
-	const bind = async (chosen: string): Promise<void> => {
-		try {
-			const bound = await serveLoopback({
-				host: chosen,
-				ports: [deps.ownerPort(), 0],
-				maxBodyBytes: deps.maxBodyBytes,
-				handler: deps.handleRequest,
-			});
-			server = bound;
-			address = chosen;
-			port = bound.port;
-		} catch {
-			// Neither the owner's port nor a free one answered: the caller reports it.
-			server = undefined;
-		}
+		const state: ShareState =
+			shared === undefined
+				? { sharing: false, origin: "", links: [] }
+				: links.state(deps.base, shared.origin, shared.address);
+		return reason === undefined ? state : { ...state, reason };
 	};
 
 	/**
-	 * Bind the one shared listener the first time a link needs it, or report why
-	 * there is nothing to bind to. Every link answers on this same listener, so this
-	 * runs once per share and the rest is bookkeeping.
+	 * Ask the session's server for the LAN listener the first time a link needs it, or
+	 * report why there is nothing to bind to. Every link answers on this same listener, so
+	 * this runs once per share and the rest is bookkeeping.
 	 */
 	const ensureListener = async (): Promise<boolean> => {
-		if (server !== undefined) return true;
-		const chosen = lanAddresses(deps.networkInterfaces())[0];
-		if (chosen === undefined) {
-			reason = NO_SHARE_REASON;
-			return false;
-		}
-		await bind(chosen);
-		if (server === undefined) {
+		if (shared !== undefined) return true;
+		shared = await deps.mount.share();
+		if (shared === undefined) {
 			reason = NO_SHARE_REASON;
 			return false;
 		}
@@ -129,7 +101,7 @@ export function createShareSession(deps: ShareSessionDeps): ShareSession {
 		deps.broadcast("share", "owner");
 		const state = snapshot();
 		if (minted === undefined) return { state };
-		return { state, svg: await qrSvg(shareUrl(address, port, minted)) };
+		return { state, svg: await qrSvg(shareUrl(deps.base, shared?.origin ?? "", minted)) };
 	};
 
 	const share = async (): Promise<ShareResult> => {
@@ -172,19 +144,16 @@ export function createShareSession(deps: ShareSessionDeps): ShareSession {
 		// The reviewers are told before their listener goes away; the review itself
 		// stays open for its owner.
 		deps.endStreams("revoked", { role: "reviewer" });
-		const closer = server;
-		server = undefined;
-		address = "";
-		port = 0;
+		shared = undefined;
 		reason = undefined;
-		if (closer) await closer.close();
+		await deps.mount.unshare();
 		return settle();
 	};
 
 	const close = async (): Promise<void> => {
-		const closer = server;
-		server = undefined;
-		if (closer) await closer.close();
+		if (shared === undefined) return;
+		shared = undefined;
+		await deps.mount.unshare();
 	};
 
 	return { share, invite, revoke, stop, state: snapshot, hosts, close };

package/extensions/plan/web-share.ts

@@ -12,10 +12,12 @@
  * failed. Everything else would print a link that cannot work.
  */
 
-import type { NetworkInterfaceInfo } from "node:os";
+import { lanAddresses, type NetworkInterfaces } from "../../lib/http/index.ts";
 
-/** The interfaces a review may be shared to, by name. */
-export type NetworkInterfaces = Record<string, NetworkInterfaceInfo[] | undefined>;
+/** The interfaces a review may be shared to, by name; `lib/http` owns the rule. */
+export type { NetworkInterfaces };
+
+export { lanAddresses };
 
 /** One address a reviewer can open the review at. */
 export interface ShareLink {
@@ -33,8 +35,12 @@ export interface ShareLink {
 export interface ShareState {
 	/** True while reviewer tokens exist and an address is bound. */
 	sharing: boolean;
-	/** The port reviewers connect to. */
-	port: number;
+	/**
+	 * The origin reviewers connect to, `http://192.168.1.24:4780`, or `""` when nothing is
+	 * shared. The port is the listener's own, which is why it is reported with its address
+	 * rather than as a number the review could have guessed.
+	 */
+	origin: string;
 	/** Every shared link, oldest first. */
 	links: ShareLink[];
 	/** Why sharing is unavailable, when it is. */
@@ -53,35 +59,11 @@ export const NO_SHARE_REASON =
 	"This machine has no network address to share on. Reviewers can still use a loopback link on this computer.";
 
 /**
- * IPv4 addresses another machine on this network can reach, deduplicated and
- * sorted, so the same machine prints the same link every time.
+ * The tokenized link for one reviewer: the origin the page answers on, its mount inside
+ * that origin, and the token the link carries.
  */
-export function lanAddresses(interfaces: NetworkInterfaces): string[] {
-	const addresses = new Set<string>();
-	for (const entries of Object.values(interfaces)) {
-		for (const entry of entries ?? []) {
-			if (entry.family !== "IPv4" || entry.internal) continue;
-			if (entry.address === "0.0.0.0" || entry.address.startsWith("169.254.")) continue;
-			addresses.add(entry.address);
-		}
-	}
-	return [...addresses].sort(byAddress);
-}
-
-/** Numeric IPv4 comparison, so `…1.9` sorts before `…1.24`. */
-function byAddress(a: string, b: string): number {
-	const left = a.split(".").map(Number);
-	const right = b.split(".").map(Number);
-	for (let index = 0; index < 4; index++) {
-		const difference = (left[index] ?? 0) - (right[index] ?? 0);
-		if (difference !== 0) return difference;
-	}
-	return 0;
-}
-
-/** The tokenized link for one address. */
-export function shareUrl(address: string, port: number, token: string): string {
-	return `http://${address}:${port}/?token=${token}`;
+export function shareUrl(base: string, origin: string, token: string): string {
+	return `${origin}${base}/?token=${token}`;
 }
 
 /**
@@ -129,7 +111,7 @@ export interface LinkTable {
 	/** The links currently shared, oldest first. */
 	list(): readonly SharedLink[];
 	/** The state the owner's page and the terminal read. */
-	state(port: number, address: string): ShareState;
+	state(base: string, origin: string, address: string): ShareState;
 }
 
 export function createLinkTable(deps: LinkTableDeps): LinkTable {
@@ -152,15 +134,15 @@ export function createLinkTable(deps: LinkTableDeps): LinkTable {
 			return true;
 		},
 		list: () => [...links],
-		state: (port, address) => ({
+		state: (base, origin, address) => ({
 			sharing: links.length > 0,
-			port,
+			origin,
 			links: links.map((link) => {
 				const name = deps.nameOf(link.token);
 				return {
 					id: link.id,
 					address,
-					url: shareUrl(address, port, link.token),
+					url: shareUrl(base, origin, link.token),
 					...(name === undefined ? {} : { name }),
 				};
 			}),

package/extensions/plan/web-write.ts

@@ -0,0 +1,112 @@
+/**
+ * The review's two write paths, over the plan store.
+ *
+ * An owner's save decides the review and returns to Pi; a reviewer's post only writes,
+ * under the name its link has bound. Both write markers through the one codec
+ * (`feedback.ts`), both refuse a file that changed under the page, and neither touches
+ * another writer's markers — the store replaces exactly the writer it is handed.
+ *
+ * Splitting them out of `web.ts` is what leaves that module the session and its sockets:
+ * every request that writes the plan comes through here, so a change to the marker
+ * grammar or to the refusal wording has one file to land in.
+ */
+
+import { claimAuthor, normalizeAuthor, stripFeedback, type PlanAnnotation } from "./feedback.ts";
+import type { PlanStore, StoredPlan } from "./plans.ts";
+import type { ReviewCaller } from "./types.ts";
+import type { SaveResult } from "./web-router.ts";
+
+/** What a write path reads: the store, and the anchor a save is validated against. */
+export interface WriteDeps {
+	/** The plan store the markers are written through. */
+	store: PlanStore;
+	/** The directory the store resolves its paths against. */
+	cwd: string;
+	/** The plan's path, as the store knows it. */
+	path: string;
+	/**
+	 * The stripped text the page rendered. A file whose body no longer matches is a
+	 * `409`: the comments would otherwise land beside text nobody read.
+	 */
+	pageText(): string;
+}
+
+/** An owner's save: the plan as it was written, or why it was refused. */
+export type OwnerWrite = { ok: true; plan: StoredPlan } | { ok: false; status: number; message: string };
+
+/** Every refusal both paths share, before anyone's markers are touched. */
+const GONE = { ok: false, status: 404, message: "The plan file is gone." } as const;
+const MOVED = {
+	ok: false,
+	status: 409,
+	message: "The plan changed on disk; reload the page and review again.",
+} as const;
+
+/** The file as it is now, when it still matches what the page rendered. */
+async function verified(
+	deps: WriteDeps,
+): Promise<{ ok: true; plan: StoredPlan } | { ok: false; status: number; message: string }> {
+	const current = await deps.store.read(deps.cwd, deps.path);
+	if (!current) return GONE;
+	if (stripFeedback(current.content) !== deps.pageText()) return MOVED;
+	return { ok: true, plan: current };
+}
+
+/**
+ * Save the owner's comments and report the plan they were written into.
+ *
+ * The caller decides what a save means (it ends the review); this path only writes, so
+ * the decision and the write cannot disagree about which file was saved.
+ */
+export async function saveOwnerAnnotations(
+	deps: WriteDeps,
+	annotations: readonly PlanAnnotation[],
+): Promise<OwnerWrite> {
+	const check = await verified(deps);
+	if (!check.ok) return check;
+	try {
+		const plan = await deps.store.saveFeedback(deps.cwd, deps.path, [...annotations]);
+		return { ok: true, plan };
+	} catch (error) {
+		return { ok: false, status: 500, message: error instanceof Error ? error.message : String(error) };
+	}
+}
+
+/** What a reviewer's post additionally needs: who posted, and which names are taken. */
+export interface ReviewerWriteDeps extends WriteDeps {
+	/** The caller the link names; its `name` is the one the link has bound, if any. */
+	caller: ReviewCaller;
+	/** Names other live links hold, so a first post cannot claim one of them. */
+	taken: readonly string[];
+}
+
+/** A reviewer's post: the name it stored under, so a page can adopt it. */
+export type ReviewerWrite = { save: SaveResult; count: number };
+
+/**
+ * Write one reviewer's comments, signed and scoped to that link.
+ *
+ * The link, not the payload, decides whose markers this replaces: a page that signs
+ * another name is a stale or foreign tab, and re-signing it would move markers that
+ * belong to whoever picked that name. Only that writer's annotations are written, so a
+ * post cannot disturb the owner's notes or a second reviewer's.
+ */
+export async function postReviewerAnnotations(
+	deps: ReviewerWriteDeps,
+	annotations: readonly PlanAnnotation[],
+): Promise<ReviewerWrite> {
+	const check = await verified(deps);
+	if (!check.ok) return { save: check, count: 0 };
+	const claim = claimAuthor({ bound: deps.caller.name, taken: deps.taken }, annotations);
+	if (!("name" in claim)) return { save: { ok: false, status: claim.status, message: claim.message }, count: 0 };
+	const own = annotations.filter((annotation) => normalizeAuthor(annotation.author) === claim.name);
+	try {
+		await deps.store.saveFeedback(deps.cwd, deps.path, own, { author: claim.name });
+		return { save: { ok: true, author: claim.name }, count: own.length };
+	} catch (error) {
+		return {
+			save: { ok: false, status: 500, message: error instanceof Error ? error.message : String(error) },
+			count: 0,
+		};
+	}
+}