@gavin-hu/my-pi-agent 0.19.0 → 0.21.0

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,
+		};
+	}
+}

package/extensions/plan/web.ts

@@ -10,37 +10,26 @@
  * the socket, and it takes injected seams so tests can run one on `127.0.0.1:0`.
  */
 
-import { networkInterfaces } from "node:os";
-import { basename } from "node:path";
 import { openInBrowser } from "../../lib/browser.ts";
 import {
+	type HttpMount,
 	jsonHeaders,
 	type LoopbackRequest,
 	type LoopbackReply,
-	type LoopbackServer,
+	type MountOutcome,
+	type MountSource,
 	parseRequestUrl,
-	serveLoopback,
 	type ServeResponse,
 } from "../../lib/http/index.ts";
-import { fenceLanguage, highlightLines } from "../../lib/highlight.ts";
 import { type ArmTimer, defaultInterval, defaultTimer, type RepeatTimer } from "../../lib/timer.ts";
-import { codeBody, fenceInfo } from "./blocks.ts";
-import {
-	claimAuthor,
-	MAX_ANNOTATIONS,
-	MAX_COMMENT_LENGTH,
-	MAX_QUOTE_LENGTH,
-	normalizeAuthor,
-	readFeedback,
-	stripFeedback,
-	type PlanAnnotation,
-} from "./feedback.ts";
-import { planTitle, type PlanStore, type StoredPlan } from "./plans.ts";
-import { changedSections, planDigest, type SectionDigest } from "./plan-text.ts";
-import { extractPlanSteps } from "./steps.ts";
+import { mintToken } from "../../lib/http/index.ts";
+import { stripFeedback, type PlanAnnotation } from "./feedback.ts";
+import type { PlanStore, StoredPlan } from "./plans.ts";
+import type { SectionDigest } from "./plan-text.ts";
 import type { ReviewCaller } from "./types.ts";
 import { handleReviewRequest, type ReviewContext, type SaveResult } from "./web-router.ts";
-import type { ReviewPageData } from "./web-page.ts";
+import { reviewPageData, type ReviewPageData } from "./web-payload.ts";
+import { postReviewerAnnotations, saveOwnerAnnotations } from "./web-write.ts";
 import { createShareSession, type ShareSession } from "./web-share-session.ts";
 import { createStreams } from "./web-streams.ts";
 import { createTokens } from "./web-tokens.ts";
@@ -100,8 +89,10 @@ export interface PlanWebReviewDeps {
 	open?: (url: string) => void;
 	/** Override the session token (tests). */
 	token?: () => string;
-	/** Override the bind port; the default `0` lets the OS pick. */
-	port?: number;
+	/** Where the review's prefix comes from: the session's server, or a suite's own. */
+	mount: MountSource;
+	/** The Pi session asking, so the prefix lands on this session's socket. */
+	session: () => string;
 	/** Override the closed-tab grace; the default leaves a reload time to reconnect. */
 	dropGraceMs?: number;
 	/**
@@ -140,14 +131,22 @@ const DROP_GRACE_MS = 1500;
  */
 const PLAN_POLL_MS = 1000;
 
-export function createPlanWebReview(store: PlanStore, deps: PlanWebReviewDeps = {}): PlanWebReview {
+/**
+ * The deps a caller that injects its own review leaves out.
+ *
+ * A review needs a place on the session's server, so a caller with no wiring says so
+ * rather than binding a socket of its own: the start is refused with a sentence.
+ */
+export const NO_SERVER_DEPS: PlanWebReviewDeps = {
+	mount: async () => ({ kind: "refused", reason: "this review has no server wired" }),
+	session: () => "",
+};
+
+export function createPlanWebReview(store: PlanStore, deps: PlanWebReviewDeps): PlanWebReview {
 	const sessions = new Set<PlanReviewSession>();
 	// What each running review can do about sharing; the session itself stays the
 	// four things a caller awaits and closes.
 	const shares = new Map<PlanReviewSession, ShareSession>();
-	// Last bound port per plan path, so the same plan keeps one origin across
-	// review turns (and its saved browser theme with it).
-	const ports = new Map<string, number>();
 
 	const start = async (
 		cwd: string,
@@ -164,8 +163,8 @@ export function createPlanWebReview(store: PlanStore, deps: PlanWebReviewDeps =
 		// the name each link has bound.
 		const tokens = createTokens(deps.token);
 		const token = tokens.mint("owner");
-		// The owner's bound port, so a shared listener can reuse it for the same URL shape.
-		let currentPort = 0;
+		// The review's own path segment: short, opaque, and stable for this review's life.
+		const id = mintToken().slice(0, 8);
 		let settled = false;
 		let resolveDone!: (result: PlanReviewResult) => void;
 		const done = new Promise<PlanReviewResult>((resolve) => {
@@ -239,65 +238,21 @@ export function createPlanWebReview(store: PlanStore, deps: PlanWebReviewDeps =
 			if (!current) return;
 			if (stripFeedback(current.content) !== pageText) notifyPlanChange();
 		};
-		stopTicker = (deps.tick ?? defaultInterval)(deps.pollMs ?? PLAN_POLL_MS, () => void checkPlanFile());
 
 		const page = async (caller: ReviewCaller): Promise<ReviewPageData> => {
-			const { role } = caller;
 			const stored = await refreshPageText();
-			// The body, its blocks, and the comments out of one read of the file: an
-			// anchor names a block from this same parse, so the island cannot mark a
-			// comment onto a line the page never rendered.
-			const read = readFeedback(stored.content);
-			const current = read.body;
-			const blocks = read.blocks;
-			// Per-section change marks, each carrying its own section: the same shape the
-			// terminal review renders, so a heading and its mark cannot be paired wrongly.
-			const marks = changedSections(options.baseline, current);
-			const outline = marks.flatMap(({ section, changed }) =>
-				section.title === ""
-					? []
-					: [
-							{
-								id: `s-${section.line}`,
-								line: section.line,
-								level: section.level,
-								text: section.title,
-								...(changed ? { changed: true } : {}),
-							},
-						],
-			);
-			// The same step list approval seeds and set_plan_steps indexes, so the page's
-			// progress cannot disagree with the todo list.
-			const stepList = extractPlanSteps(current);
-			// Highlight code blocks once, at the boundary: the client copies only the
-			// tok-* spans out of the server-escaped HTML.
-			const code: Record<string, string[]> = {};
-			for (const block of blocks) {
-				if (block.kind !== "code") continue;
-				const language = fenceLanguage(fenceInfo(block.lines[0] ?? ""));
-				if (language) code[String(block.start)] = highlightLines(codeBody(block), language);
-			}
-			return {
-				// The document's own H1 reads better than the file-name slug, and the
-				// slug is still the fallback for a plan that starts with something else.
-				title: marks.find((mark) => mark.section.level === 1)?.section.title || planTitle(basename(plan.path)),
-				blocks,
-				annotations: read.annotations,
-				outline,
-				steps: {
-					done: stepList.filter((step) => step.status === "completed").length,
-					total: stepList.length,
-				},
-				code,
-				limits: { comments: MAX_ANNOTATIONS, comment: MAX_COMMENT_LENGTH, quote: MAX_QUOTE_LENGTH },
+			// The island is one function of what the page renders: the text, the baseline
+			// the previous review left, and who is asking.
+			return reviewPageData({
+				base,
+				path: plan.path,
+				content: stored.content,
+				baseline: options.baseline,
+				caller,
 				token,
-				role,
-				// What the page keys this tab's unsaved draft on: same plan text, same draft.
-				rev: planDigest(current),
-				...(caller.name === undefined ? {} : { author: caller.name }),
-				canApprove: role === "owner" && canApprove,
-				share: role === "owner" ? shareSession.state() : undefined,
-			};
+				canApprove,
+				share: () => shareSession.state(),
+			});
 		};
 
 		/**
@@ -309,43 +264,48 @@ export function createPlanWebReview(store: PlanStore, deps: PlanWebReviewDeps =
 		 */
 		const save = async (annotations: PlanAnnotation[], caller: ReviewCaller): Promise<SaveResult> => {
 			const { role } = caller;
-			const current = await store.read(cwd, plan.path);
-			if (!current) return { ok: false, status: 404, message: "The plan file is gone." };
-			if (stripFeedback(current.content) !== pageText) {
-				return { ok: false, status: 409, message: "The plan changed on disk; reload the page and review again." };
-			}
-			try {
-				if (role === "owner") {
-					savedPlan = await store.saveFeedback(cwd, plan.path, annotations);
-					streams.broadcast("comment");
-					return { ok: true };
-				}
-				// The link, not the payload, decides whose markers this post replaces: the name
-				// is bound to the token on its first write, and a page that signs another one
-				// is a stale tab rather than an authorized writer.
-				const claim = claimAuthor({ bound: caller.name, taken: tokens.namesExcept(caller) }, annotations);
-				if (!("name" in claim)) return { ok: false, status: claim.status, message: claim.message };
-				const own = annotations.filter((annotation) => normalizeAuthor(annotation.author) === claim.name);
-				// The saved plan is deliberately not recorded here: a post is not a result
-				// the session can return, so there is nothing for a later flush to resolve.
-				await store.saveFeedback(cwd, plan.path, own, { author: claim.name });
-				caller.name ??= claim.name;
+			const write = { store, cwd, path: plan.path, pageText: () => pageText };
+			if (role === "owner") {
+				const saved = await saveOwnerAnnotations(write, annotations);
+				if (!saved.ok) return saved;
+				savedPlan = saved.plan;
 				streams.broadcast("comment");
-				if (own.length > 0) options.onReviewerComment?.(claim.name, own.length);
-				return { ok: true, author: claim.name };
-			} catch (error) {
-				return { ok: false, status: 500, message: error instanceof Error ? error.message : String(error) };
+				return { ok: true };
 			}
+			// The saved plan is deliberately not recorded for a reviewer: a post is not a
+			// result the session can return, so there is nothing for a later flush to resolve.
+			const posted = await postReviewerAnnotations(
+				{ ...write, caller, taken: tokens.namesExcept(caller) },
+				annotations,
+			);
+			if (!posted.save.ok) return posted.save;
+			caller.name ??= posted.save.author;
+			streams.broadcast("comment");
+			// The page is told the name its link stored, and the terminal is told a peer wrote.
+			if (posted.count > 0) options.onReviewerComment?.(posted.save.author ?? "", posted.count);
+			return posted.save;
 		};
 
+		// One review, one prefix on the session's server: the id is the review's, so two
+		// reviews of two plans (or one plan twice) never share a namespace, and the origin
+		// is the session's single port.
+		const base = `/plan/${id}`;
+		const outcome: MountOutcome = await deps.mount({
+			session: deps.session(),
+			prefix: base,
+			maxBodyBytes: bodyLimit,
+			handler: handleRequest,
+		});
+		if (outcome.kind === "refused") return undefined;
+		const mount: HttpMount = outcome.mount;
+		const port = mount.port;
+
 		// The second listener, its reviewer token, and the state the page and
 		// `/plan share` read. It is handed the request handler, the role map, and the
 		// frame hooks, so sharing stays one concern instead of five fields here.
 		const shareSession = createShareSession({
-			handleRequest,
-			maxBodyBytes: bodyLimit,
-			ownerPort: () => currentPort,
-			networkInterfaces: deps.networkInterfaces ?? networkInterfaces,
+			mount,
+			base,
 			mintReviewer: () => tokens.mint("reviewer"),
 			revokeReviewer: (value) => tokens.revoke(value),
 			nameOf: (value) => tokens.get(value)?.name,
@@ -412,24 +372,11 @@ export function createPlanWebReview(store: PlanStore, deps: PlanWebReviewDeps =
 			};
 		}
 
-		const preferred = deps.port ?? ports.get(plan.path) ?? 0;
-		let server: LoopbackServer;
-		try {
-			server = await serveLoopback({
-				ports: preferred === 0 ? [0] : [preferred, 0],
-				maxBodyBytes: bodyLimit,
-				handler: handleRequest,
-			});
-		} catch {
-			// The remembered port may have been taken between turns; the fallback above
-			// covers that, so reaching here means neither port answered.
-			return undefined;
-		}
-		const port = server.port;
-		ports.set(plan.path, port);
-		currentPort = port;
+		// Armed only now: a review whose listener never bound has no page to keep current,
+		// and an interval started for it would outlive the session that failed to start.
+		stopTicker = (deps.tick ?? defaultInterval)(deps.pollMs ?? PLAN_POLL_MS, () => void checkPlanFile());
 
-		const url = `http://127.0.0.1:${port}/?token=${token}`;
+		const url = `${mount.origin}${base}/?token=${token}`;
 		let closed = false;
 		let abortHandler: (() => void) | undefined;
 		const close = async (): Promise<void> => {
@@ -444,7 +391,7 @@ export function createPlanWebReview(store: PlanStore, deps: PlanWebReviewDeps =
 			stopTicker();
 			streams.clear();
 			await shareSession.close();
-			await server.close();
+			await mount.release();
 		};
 
 		const session: PlanReviewSession = { url, port, done, close };

package/extensions/rewind/commands/review.ts

@@ -12,6 +12,7 @@
 import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import { messageOf } from "../../../lib/errors.ts";
 import { sanitizeLine } from "../../../lib/format.ts";
+import { planModeRefusal } from "../../../lib/plan-entry.ts";
 import { isPlanModeEnabled } from "../../../lib/plan-state.ts";
 import { withRailsSuppressed } from "../../../lib/rails.ts";
 import {
@@ -75,7 +76,7 @@ async function loadReview(runtime: RewindRuntime, ctx: ExtensionCommandContext):
 		return {
 			ok: false,
 			kind: "warning",
-			message: "Plan mode is read-only. Approve the plan before reviewing and reverting its changes.",
+			message: planModeRefusal("reviewing and reverting its changes"),
 		};
 	}
 

package/extensions/serve/config.ts

@@ -0,0 +1,37 @@
+/**
+ * The session's one port: the `serve` section of the shared `bytefly.json` (global
+ * then project, project wins).
+ *
+ * `0` — the default — takes one free port for the session and remembers it, which
+ * is what a session that never bookmarks wants. A positive value pins the session's
+ * server, so every page it serves keeps the address a bookmark already points at.
+ * A pinned port that is taken fails the start rather than moving the pages out from
+ * under the bookmark.
+ *
+ * Pin it in the project document when more than one repository runs pages on the
+ * machine: a global value is one port for every session.
+ */
+
+import { clampInteger, loadConfigSection } from "../../lib/config.ts";
+
+/** The `serve` section. */
+export interface ServeConfig {
+	/** TCP port on `127.0.0.1`; `0` picks one for the session, a positive value pins it. */
+	port: number;
+}
+
+export const DEFAULT_SERVE_CONFIG: ServeConfig = { port: 0 };
+
+/** Validate and clamp a raw config object over the defaults. */
+export function normalizeServeConfig(
+	raw: Record<string, unknown> | undefined,
+	base: ServeConfig = DEFAULT_SERVE_CONFIG,
+): ServeConfig {
+	if (!raw) return base;
+	return { port: clampInteger(raw.port, base.port, 0, 65_535) };
+}
+
+/** Load the effective config for a working directory. */
+export function loadServeConfig(cwd: string): ServeConfig {
+	return loadConfigSection(cwd, "serve", DEFAULT_SERVE_CONFIG, normalizeServeConfig);
+}

package/extensions/serve/index.ts

@@ -0,0 +1,71 @@
+/**
+ * serve — the one loopback server a session serves its pages on.
+ *
+ * It registers one bus listener and closes what it opened; it draws no page of its
+ * own. `plan`, `board`, and `file-browse` ask for a path prefix on
+ * {@link HTTP_MOUNT_CHANNEL} and the registry answers with the session's origin, so
+ * a session has one port, one close path, and one chip instead of one socket per
+ * extension. Binding happens on the first page that asks, never in the factory.
+ *
+ * Load with:  pi --extension ./extensions/serve
+ */
+
+import { networkInterfaces } from "node:os";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { isExtensionEnabled } from "../../lib/env.ts";
+import { HTTP_MOUNT_CHANNEL, type MountRequest } from "../../lib/http/index.ts";
+import { GLYPHS, STATUS_KEYS } from "../../lib/tui/glyphs.ts";
+import { paint } from "../../lib/tui/tokens.ts";
+import { loadServeConfig } from "./config.ts";
+import { createServeRegistry } from "./registry.ts";
+
+export default function serve(pi: ExtensionAPI): void {
+	if (!isExtensionEnabled("serve")) return;
+	/** Each session's working directory, so its pin is read from its own config. */
+	const cwds = new Map<string, string>();
+	/** Each session's context, which is where the port chip is drawn. */
+	const contexts = new Map<string, ExtensionContext>();
+
+	/**
+	 * Publish the session's port, or clear the chip with `undefined`. The chip belongs
+	 * to the server, not to a page: one number, shown while anything is served on it.
+	 */
+	const setChip = (session: string, port: number | undefined): void => {
+		const ctx = contexts.get(session);
+		if (ctx === undefined) return;
+		try {
+			const value =
+				port === undefined
+					? undefined
+					: `${paint(ctx.ui.theme, "ok", GLYPHS.http)} ${paint(ctx.ui.theme, "accent", String(port))}`;
+			ctx.ui.setStatus(STATUS_KEYS.http, value);
+		} catch {
+			// A host without a status line is not a reason to keep a page from starting.
+		}
+	};
+
+	const registry = createServeRegistry({
+		portFor: (session) => loadServeConfig(cwds.get(session) ?? process.cwd()).port,
+		interfaces: () => networkInterfaces(),
+		onPort: setChip,
+	});
+
+	pi.events.on(HTTP_MOUNT_CHANNEL, (data) => {
+		const request = data as Partial<MountRequest> | undefined;
+		if (request?.spec === undefined) return;
+		registry.handle(request as MountRequest);
+	});
+
+	pi.on("session_start", async (_event, ctx) => {
+		const id = ctx.sessionManager.getSessionId();
+		cwds.set(id, ctx.cwd);
+		contexts.set(id, ctx);
+	});
+
+	pi.on("session_shutdown", async (_event, ctx) => {
+		const id = ctx.sessionManager.getSessionId();
+		await registry.closeSession(id);
+		cwds.delete(id);
+		contexts.delete(id);
+	});
+}