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

package/extensions/file-browse/index.ts

@@ -14,21 +14,15 @@ import { realpathSync } from "node:fs";
 import { stat } from "node:fs/promises";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { isExtensionEnabled, resolveEffectiveCwd } from "../../lib/env.ts";
-import { GLYPHS, STATUS_KEYS } from "../../lib/tui/glyphs.ts";
-import { paint } from "../../lib/tui/tokens.ts";
-import { loadConfig, randomPort } from "./config/config.ts";
-import { createGitDiff, createGitStatus } from "./git/git.ts";
-import { openInBrowser } from "../../lib/browser.ts";
-import { HttpError, resolveRequestPath } from "./files/paths.ts";
-import { createFileServer, type FileServer } from "./transport/server.ts";
+import type { openInBrowser } from "../../lib/browser.ts";
+import type { ServeConfig } from "./config/config.ts";
+import type { FileServer } from "./transport/server.ts";
 
 export interface FileBrowserDeps {
 	/** Override the server factory (tests). */
-	createServer?: typeof createFileServer;
+	createServer?: typeof import("./transport/server.ts").createFileServer;
 	/** Override the browser opener (tests). */
 	open?: typeof openInBrowser;
-	/** Override session-port selection (tests). */
-	pickPort?: () => number;
 }
 
 interface RunningServer {
@@ -40,94 +34,76 @@ interface RunningServer {
 export default function fileBrowser(pi: ExtensionAPI, deps: FileBrowserDeps = {}): void {
 	if (!isExtensionEnabled("file-browse")) return;
 	let running: RunningServer | undefined;
-	/** Random port fixed for the session after the first successful start. */
-	let sessionPort: number | undefined;
+	/** The session this page serves as; the mount lands on its one server. */
+	let sessionId = "";
 
-	/** Publish the browse chip, or clear it with `undefined`; best-effort UI. */
-	const setBrowseStatus = (ctx: ExtensionContext, port: number | undefined): void => {
-		try {
-			const value =
-				port === undefined
-					? undefined
-					: `${paint(ctx.ui.theme, "ok", GLYPHS.browse)} ${paint(ctx.ui.theme, "accent", String(port))}`;
-			ctx.ui.setStatus(STATUS_KEYS.browse, value);
-		} catch {
-			// A UI without a theme or setStatus must not break the command.
-		}
-	};
-
-	const stop = async (ctx?: ExtensionContext): Promise<boolean> => {
+	const stop = async (): Promise<boolean> => {
 		const current = running;
 		if (!current) return false;
 		running = undefined;
 		await current.server.close();
-		if (ctx) setBrowseStatus(ctx, undefined);
 		return true;
 	};
 
 	/**
-	 * Close the server once the page that was its only reader has gone: nothing is
-	 * left to serve, and the chip would otherwise advertise a port that answers no
-	 * one. `/browse` starts it again on the same session port.
+	 * Give the prefix back once the page that was its only reader has gone: nothing is
+	 * left to serve. `/browse` starts it again on the session's port.
 	 */
 	const stopWhenPageLeft = async (): Promise<void> => {
 		const current = running;
 		if (!current) return;
-		if (await stop(current.ctx)) current.ctx.ui.notify("browse: stopped — the last page was closed", "info");
+		if (await stop()) current.ctx.ui.notify("browse: stopped — the last page was closed", "info");
 	};
 
-	const start = async (args: string, ctx: ExtensionContext): Promise<void> => {
-		const target = args.trim();
-		if (target === "status") {
-			ctx.ui.notify(
-				running ? `browse: ${running.server.root} at ${running.server.url}` : "browse: not running",
-				"info",
-			);
-			return;
-		}
-		if (target === "stop") {
-			ctx.ui.notify((await stop(ctx)) ? "browse: stopped" : "browse: not running", "info");
-			return;
-		}
+	type ResolvedRoot = { root: string; config: ServeConfig };
 
-		const cwd = resolveEffectiveCwd(ctx.cwd);
+	/** The folder `/browse [path]` names, or undefined after telling the user why. */
+	const resolveRoot = async (target: string, cwd: string, ctx: ExtensionContext): Promise<ResolvedRoot | undefined> => {
+		const { loadConfig } = await import("./config/config.ts");
 		const config = loadConfig(cwd);
-		// A pinned config port wins; otherwise one random port is fixed for the session.
-		const unpinned = config.port <= 0;
-		const port = unpinned ? (sessionPort ?? (deps.pickPort ?? randomPort)()) : config.port;
 		let root = cwd;
 		if (target) {
+			const { HttpError, resolveRequestPath } = await import("./files/paths.ts");
 			try {
 				root = await resolveRequestPath(cwd, target);
 			} catch (error) {
 				const message = error instanceof HttpError ? error.message : String(error);
 				ctx.ui.notify(`browse: ${message}`, "error");
-				return;
+				return undefined;
 			}
 			const info = await stat(root).catch(() => undefined);
 			if (!info?.isDirectory()) {
 				ctx.ui.notify(`browse: ${target} is not a folder inside the working directory`, "error");
-				return;
+				return undefined;
 			}
 		}
+		return { root, config };
+	};
 
-		let realRoot = root;
-		try {
-			realRoot = realpathSync.native(root);
-		} catch {
-			// Keep the unresolved root; the server factory reports a real failure.
-		}
-		if (running && running.server.root === realRoot && running.server.port === port) {
-			ctx.ui.notify(`browse: ${running.server.url} (already running)`, "info");
-			return;
-		}
+	/**
+	 * Put the page in front of the user, unless the project asked to stay headless.
+	 *
+	 * Every `/browse` opens it, including one that finds the page already served: the
+	 * command's job is showing the page, and a URL printed over a running server leaves
+	 * the user to paste it.
+	 */
+	const openPage = async (url: string, config: ServeConfig): Promise<void> => {
+		if (!config.autoOpen) return;
+		const open = deps.open ?? (await import("../../lib/browser.ts")).openInBrowser;
+		open(url);
+	};
 
-		await stop(ctx);
-		const create = deps.createServer ?? createFileServer;
+	/** Open the page's server; the server, git, HTTP, and browser modules live here. */
+	const openServer = async (root: string, config: ServeConfig, ctx: ExtensionContext): Promise<void> => {
+		const create = deps.createServer ?? (await import("./transport/server.ts")).createFileServer;
+		const { createGitDiff, createGitStatus } = await import("./git/git.ts");
+		const { requestMount } = await import("../../lib/http/index.ts");
 		try {
-			const server = await create({
+			const outcome = await create({
 				root,
-				config: { ...config, port },
+				config,
+				mount: (spec) => requestMount(pi, spec),
+				session: sessionId,
 				git: createGitStatus(pi, root),
 				diff: createGitDiff(pi, root, {
 					context: config.diffContext,
@@ -137,22 +113,53 @@ export default function fileBrowser(pi: ExtensionAPI, deps: FileBrowserDeps = {}
 				}),
 				onIdle: () => void stopWhenPageLeft(),
 			});
-			if (unpinned) sessionPort = port;
+			if (outcome.kind === "refused") {
+				ctx.ui.notify(`browse: ${outcome.reason}`, "error");
+				return;
+			}
+			const server = outcome.server;
 			running = { server, ctx };
-			setBrowseStatus(ctx, server.port);
 			ctx.ui.notify(`browse: ${server.root} at ${server.url}`, "info");
-			if (config.autoOpen) (deps.open ?? openInBrowser)(server.url);
+			await openPage(server.url, config);
 		} catch (error) {
-			const code = (error as NodeJS.ErrnoException | undefined)?.code;
-			if (code === "EADDRINUSE") {
-				ctx.ui.notify(
-					`browse: port ${port} is in use; run /browse again to try another or set "port" in the bytefly.json file-browse section`,
-					"error",
-				);
-			} else {
-				ctx.ui.notify(`browse: ${error instanceof Error ? error.message : String(error)}`, "error");
-			}
+			ctx.ui.notify(`browse: ${error instanceof Error ? error.message : String(error)}`, "error");
+		}
+	};
+
+	const start = async (args: string, ctx: ExtensionContext): Promise<void> => {
+		const target = args.trim();
+		if (target === "status") {
+			ctx.ui.notify(
+				running ? `browse: ${running.server.root} at ${running.server.url}` : "browse: not running",
+				"info",
+			);
+			return;
+		}
+		if (target === "stop") {
+			ctx.ui.notify((await stop()) ? "browse: stopped" : "browse: not running", "info");
+			return;
+		}
+
+		const cwd = resolveEffectiveCwd(ctx.cwd);
+		const resolved = await resolveRoot(target, cwd, ctx);
+		if (resolved === undefined) return;
+		const { root, config } = resolved;
+
+		let realRoot = root;
+		try {
+			realRoot = realpathSync.native(root);
+		} catch {
+			// Keep the unresolved root; the server factory reports a real failure.
+		}
+		if (running && running.server.root === realRoot) {
+			ctx.ui.notify(`browse: ${running.server.url} (already running)`, "info");
+			// The page is already served, so this is an open and not a restart.
+			await openPage(running.server.url, config);
+			return;
 		}
+
+		await stop();
+		await openServer(root, config, ctx);
 	};
 
 	pi.registerCommand("browse", {
@@ -168,8 +175,11 @@ export default function fileBrowser(pi: ExtensionAPI, deps: FileBrowserDeps = {}
 		},
 	});
 
-	pi.on("session_shutdown", async (_event, ctx) => {
-		await stop(ctx);
-		sessionPort = undefined;
+	pi.on("session_start", async (_event, ctx) => {
+		sessionId = ctx.sessionManager.getSessionId();
+	});
+
+	pi.on("session_shutdown", async () => {
+		await stop();
 	});
 }

package/extensions/file-browse/live/live.ts

@@ -174,7 +174,7 @@ export interface LiveChannel {
  * attached, so an idle server does no status work at all; the last page leaving
  * parks it and the next page starts it again. What happens to a server nobody is
  * reading — the idle grace and the close it leads to — is the server's policy, so
- * the caller hands it to `lib/http`'s `serveLoopback` instead of configuring it
+ * the caller hands it to its own mount instead of configuring it
  * here.
  */
 export function createLiveChannel(options: LiveChannelOptions): LiveChannel {

package/extensions/file-browse/transport/router.ts

@@ -46,13 +46,16 @@ import {
 	renderErrorPage,
 	renderFileDiffPage,
 	renderFilePage,
+	hrefFor,
 } from "../view/html.ts";
 import type { ChangeSummary } from "../view/html.ts";
-import { encodePath, HttpError, relativePath, resolveDecodedPath, resolveRequestPath } from "../files/paths.ts";
+import { HttpError, relativePath, resolveDecodedPath, resolveRequestPath } from "../files/paths.ts";
 import { listingRevision } from "../live/rev.ts";
 
 export interface ServeContext {
 	root: string;
+	/** The prefix this page answers under, e.g. `/files`; `""` for the origin's root. */
+	base: string;
 	config: ServeConfig;
 	/** Read-only git context for the page header; omitted when unavailable. */
 	git?: GitStatusProvider;
@@ -152,6 +155,7 @@ async function errorPage(
 		// Keep the minimal tree.
 	}
 	const body = renderErrorPage({
+		base: ctx.base,
 		rootLabel: ctx.root,
 		status,
 		message,
@@ -187,6 +191,7 @@ async function directoryResponse(ctx: ServeContext, rel: string): Promise<ServeR
 	return htmlResponse(
 		200,
 		renderDirectoryPage({
+			base: ctx.base,
 			rootLabel: ctx.root,
 			rel,
 			listing,
@@ -211,6 +216,7 @@ async function fileResponse(ctx: ServeContext, rel: string, raw: boolean): Promi
 	return htmlResponse(
 		200,
 		renderFilePage({
+			base: ctx.base,
 			rootLabel: ctx.root,
 			rel,
 			file,
@@ -235,6 +241,7 @@ async function diffOverview(ctx: ServeContext, mode: DiffMode): Promise<ServeRes
 	return htmlResponse(
 		200,
 		renderDiffPage({
+			base: ctx.base,
 			rootLabel: ctx.root,
 			mode,
 			files: list?.files ?? [],
@@ -267,6 +274,7 @@ async function diffFile(ctx: ServeContext, rawRel: string, mode: DiffMode): Prom
 	return htmlResponse(
 		200,
 		renderFileDiffPage({
+			base: ctx.base,
 			rootLabel: ctx.root,
 			rel,
 			mode,
@@ -303,12 +311,12 @@ async function raw(ctx: ServeContext, rawRel: string): Promise<ServeResponse> {
 	};
 }
 
-function treeApiEntry(entry: DirEntry): Record<string, unknown> {
+function treeApiEntry(entry: DirEntry, base: string): Record<string, unknown> {
 	const spec = entry.isDir ? FOLDER_ICON : languageOf(entry.name);
 	return {
 		name: entry.name,
 		path: entry.rel,
-		href: entry.isDir ? `/browse/${encodePath(entry.rel)}` : `/view/${encodePath(entry.rel)}`,
+		href: hrefFor(entry, base),
 		isDir: entry.isDir,
 		broken: entry.broken,
 		iconHref: iconHref(spec.icon),
@@ -323,7 +331,7 @@ async function treeApi(ctx: ServeContext, decodedPath: string): Promise<ServeRes
 	const info = await stat(abs).catch(() => undefined);
 	if (info && !info.isDirectory()) throw new HttpError(400, "That path is not a folder.");
 	const listing = await listDirectory(ctx.root, rel, ctx.config.maxDirEntries);
-	return jsonResponse(200, { path: rel, entries: listing.entries.map(treeApiEntry) });
+	return jsonResponse(200, { path: rel, entries: listing.entries.map((entry) => treeApiEntry(entry, ctx.base)) });
 }
 
 /** The revision of one folder's listing: what a page's reload control compares against. */

package/extensions/file-browse/transport/server.ts

@@ -1,44 +1,69 @@
 /**
- * The HTTP server for the browse extension.
+ * The browse page's mount: the prefix it holds on the session's one server, plus the
+ * live status channel it feeds.
  *
- * Wraps the pure `handleRequest` in `lib/http`'s loopback server: it resolves the
- * root once, feeds the live status channel, and exposes an idempotent `close()`.
- * The request handler is injectable so tests can avoid a socket when they only
- * need routing.
+ * `lib/http` owns the socket and `serve` owns the session's port, so this module owns
+ * only this page's own policy: the request handler, its request count, the cap that
+ * refuses a page rather than opening a stream for it, and how long a page with nobody
+ * reading it is worth keeping.
  *
- * What stays here is this extension's own policy: the request handler, its
- * request count, the catch that turns a thrown handler into a plain-text 500, the
- * cap that refuses a page rather than opening a stream for it, and how long a
- * server with nobody reading it is worth keeping.
+ * The page takes the namespace `/files`, beside `/board` and `/plan/<id>`: every URL it
+ * emits is built from that `base` — the links, the scripts, the destinations it rewrites
+ * out of Markdown, and the client's own fetches — so one prefix is all it needs, and the
+ * origin's root stays free. `BROWSE_BASE` is that claim, named where the mount and its
+ * suite can see it.
  */
 
 import { realpathSync } from "node:fs";
-import { type ServeResponse, serveLoopback, textResponse } from "../../../lib/http/index.ts";
+import {
+	type HttpMount,
+	type MountOutcome,
+	type MountSource,
+	type ServeResponse,
+	textResponse,
+} from "../../../lib/http/index.ts";
 import { IDLE_STOP_MS, type ServeConfig } from "../config/config.ts";
 import { createFileIndex } from "../files/files.ts";
 import type { GitDiffProvider, GitStatusProvider } from "../git/git.ts";
 import { createLiveChannel, createLiveStatus } from "../live/live.ts";
 import { handleRequest, type ServeContext } from "./router.ts";
 
+/**
+ * The prefix this page answers under: its own namespace on the session's origin.
+ *
+ * Route names inside the page (`/`, `/browse`, `/view`, `/raw`, `/diff`, `/api/*`,
+ * `/events`) are unchanged and relative to this prefix, so the same page is served under
+ * `/files` and nowhere else, and the origin's root answers nothing at all.
+ */
+export const BROWSE_BASE = "/files";
+
+/** A mounted page. */
 export interface FileServer {
-	/** Origin URL, e.g. `http://127.0.0.1:49152/`. */
+	/** The page's URL, e.g. `http://127.0.0.1:4780/files/`. */
 	url: string;
-	/** The bound port. */
+	/** The port the session's server bound. */
 	port: number;
 	/** Resolved absolute root that is actually served. */
 	root: string;
-	/** Stop listening. Safe to call more than once or before `listen` settles. */
+	/** Give the prefix back. Safe to call more than once. */
 	close(): Promise<void>;
 }
 
+/** The page, or the reason the session's server has no place for it. */
+export type FileServerResult = { kind: "served"; server: FileServer } | { kind: "refused"; reason: string };
+
 export interface FileServerOptions {
 	root: string;
 	config: ServeConfig;
+	/** Where the 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;
 	/** Read-only git context for the page header; omitted when unavailable. */
 	git?: GitStatusProvider;
 	/** Read-only diff provider for the change and diff views; omitted when unavailable. */
 	diff?: GitDiffProvider;
-	/** Called once the last page has been gone for `idleStopMs`; omitted, the server waits for `close()`. */
+	/** Called once the last page has been gone for `idleStopMs`; omitted, the mount waits for `close()`. */
 	onIdle?: () => void;
 	/** Grace before `onIdle`, in ms; defaults to `IDLE_STOP_MS`. */
 	idleStopMs?: number;
@@ -46,8 +71,8 @@ export interface FileServerOptions {
 	handler?: typeof handleRequest;
 }
 
-/** Start a read-only server rooted at `options.root` on 127.0.0.1. */
-export async function createFileServer(options: FileServerOptions): Promise<FileServer> {
+/** Mount a read-only page rooted at `options.root` on the session's server. */
+export async function createFileServer(options: FileServerOptions): Promise<FileServerResult> {
 	const root = realpathSync.native(options.root);
 	const { config } = options;
 	// The status feed's two server-owned facts: how long it has been up, and how
@@ -64,6 +89,7 @@ export async function createFileServer(options: FileServerOptions): Promise<File
 	const live = status ? createLiveChannel({ status, intervalMs: config.liveIntervalMs }) : undefined;
 	const context: ServeContext = {
 		root,
+		base: BROWSE_BASE,
 		config,
 		git: options.git,
 		diff: options.diff,
@@ -72,10 +98,13 @@ export async function createFileServer(options: FileServerOptions): Promise<File
 	};
 	const handler = options.handler ?? handleRequest;
 
-	const server = await serveLoopback({
-		ports: [config.port],
-		idle: options.onIdle === undefined ? undefined : { ms: options.idleStopMs ?? IDLE_STOP_MS, onIdle: options.onIdle },
-		handler: async (request) => {
+	const outcome: MountOutcome = await options.mount({
+		session: options.session,
+		prefix: BROWSE_BASE,
+		...(options.onIdle === undefined
+			? {}
+			: { idle: { ms: options.idleStopMs ?? IDLE_STOP_MS, onIdle: options.onIdle } }),
+		async handler(request) {
 			requests += 1;
 			let result: ServeResponse;
 			try {
@@ -96,15 +125,19 @@ export async function createFileServer(options: FileServerOptions): Promise<File
 			};
 		},
 	});
-
+	if (outcome.kind === "refused") return { kind: "refused", reason: outcome.reason };
+	const mount: HttpMount = outcome.mount;
 	return {
-		url: `${server.origin}/`,
-		port: server.port,
-		root,
-		close: async () => {
-			// End the streams first, so a connected page does not hold the close open.
-			live?.close();
-			await server.close();
+		kind: "served",
+		server: {
+			url: `${mount.origin}${mount.base}/`,
+			port: mount.port,
+			root,
+			close: async () => {
+				// End the streams first, so a connected page does not hold the mount open.
+				live?.close();
+				await mount.release();
+			},
 		},
 	};
 }

package/extensions/file-browse/view/chrome.ts

@@ -46,7 +46,7 @@ export function renderLiveChrome(live: LivePage | undefined): string {
 	if (!live) return "";
 	const rev =
 		live.rev === undefined ? "" : ` data-dir="${escapeHtml(live.dir ?? "")}" data-rev="${escapeHtml(live.rev)}"`;
-	const chip = `<span class="bf-chip bf-chip--accent browse-live" id="live-state" title="Live status from the browse server" data-interval="${live.intervalMs}"${rev} hidden><span class="browse-live__glyph" aria-hidden="true">${escapeHtml(GLYPHS.browse)}</span><span class="browse-live__text">connecting</span></span>`;
+	const chip = `<span class="bf-chip bf-chip--accent browse-live" id="live-state" title="Live status from the browse server" data-interval="${live.intervalMs}"${rev} hidden><span class="browse-live__glyph" aria-hidden="true">◉</span><span class="browse-live__text">connecting</span></span>`;
 	if (live.rev === undefined) return chip;
 	return `${chip}<button type="button" class="bf-chip bf-chip--warn browse-reload" id="reload-hint" title="This folder changed on disk" hidden>⟳ reload</button>`;
 }
@@ -64,11 +64,11 @@ export function renderLiveStatus(): string {
  * a hidden shell is always rendered so the chip can appear and disappear as the
  * working tree changes, without the client inserting elements into the header.
  */
-export function renderChanges(summary: ChangeIndex | undefined, live: LivePage | undefined): string {
+export function renderChanges(summary: ChangeIndex | undefined, live: LivePage | undefined, base: string): string {
 	const count = summary?.count ?? 0;
 	if (count <= 0) {
 		return live
-			? `<a class="bf-chip browse-diff" id="browse-changes" href="/diff" title="View uncommitted changes" hidden></a>`
+			? `<a class="bf-chip browse-diff" id="browse-changes" href="${base}/diff" title="View uncommitted changes" hidden></a>`
 			: "";
 	}
 	const label = `${count} change${count === 1 ? "" : "s"}`;
@@ -79,5 +79,5 @@ export function renderChanges(summary: ChangeIndex | undefined, live: LivePage |
 			? ` <span class="browse-diff-totals"><span class="browse-diff-add">+${insertions}</span> <span class="browse-diff-del">−${deletions}</span></span>`
 			: "";
 	const aria = `${label} against HEAD${insertions + deletions > 0 ? `, ${insertions} insertions and ${deletions} deletions` : ""}`;
-	return `<a class="bf-chip browse-diff" id="browse-changes" href="/diff" title="View uncommitted changes" aria-label="${escapeHtml(aria)}"><span class="browse-diff__dot" aria-hidden="true">●</span>${escapeHtml(label)}${totals}</a>`;
+	return `<a class="bf-chip browse-diff" id="browse-changes" href="${base}/diff" title="View uncommitted changes" aria-label="${escapeHtml(aria)}"><span class="browse-diff__dot" aria-hidden="true">●</span>${escapeHtml(label)}${totals}</a>`;
 }

package/extensions/file-browse/view/client.ts

@@ -12,13 +12,15 @@
  * and `bun build --no-bundle` needs no separate asset.
  */
 
-import { keysDialogScript, THEME_TOGGLE_JS } from "../../../lib/web/index.ts";
+import { CLIENT_BASE_JS, keysDialogScript, THEME_TOGGLE_JS } from "../../../lib/web/index.ts";
 import { LIVE_CLIENT_JS } from "./live-client.ts";
 import { PALETTE_CLIENT_JS } from "./palette.ts";
 import { TREE_CLIENT_JS } from "./tree.ts";
 
 export const CLIENT_JS = `(function () {
 	"use strict";
+	/* Spliced at the outermost scope: every fragment below builds its URLs from it. */
+${CLIENT_BASE_JS}
 	var rows = Array.prototype.slice.call(document.querySelectorAll("table.bf-table tbody tr"));
 ${TREE_CLIENT_JS}
 	Array.prototype.forEach.call(document.querySelectorAll("img.bf-table__thumb"), function (img) {