@gavin-hu/my-pi-agent 0.15.0 → 0.16.0

package/extensions/file-browse/live.ts

@@ -0,0 +1,256 @@
+/**
+ * Live status for the browse pages.
+ *
+ * A page that stays open holds one event stream; this module builds the snapshot
+ * it is sent, the frame that carries it, and the channel that fans it out on a
+ * tick. The git and diff providers already memoize, so a tick re-reads at most
+ * one `git status`, and every read failure degrades to `null`: a status feed
+ * must never be able to fail a page or the server that serves it.
+ *
+ * The channel opens no socket of its own — the caller hands it a `write`/`end`
+ * pair — so the whole feed is tested without one.
+ */
+
+import { defaultInterval, defaultTimer } from "../../lib/timer.ts";
+import { changeDirs } from "./diff.ts";
+import type { DiffList, GitDiffProvider, GitStatus, GitStatusProvider } from "./git.ts";
+
+/**
+ * The changed-path index the pages render from: the totals the changes chip
+ * prints and the paths the tree and listing mark.
+ */
+export interface ChangeIndex {
+	/** Changed paths in the scope. */
+	count: number;
+	/** Added lines in the scope. */
+	insertions: number;
+	/** Removed lines in the scope. */
+	deletions: number;
+	/** Changed files, root-relative. */
+	files: ReadonlySet<string>;
+	/** Directories that contain a changed file. */
+	dirs: ReadonlySet<string>;
+}
+
+/** The marker/totals index a change list yields. */
+export function changeIndexOf(list: DiffList): ChangeIndex {
+	return {
+		count: list.files.length,
+		insertions: list.insertions,
+		deletions: list.deletions,
+		files: new Set(list.files.map((file) => file.rel)),
+		dirs: changeDirs(list.files),
+	};
+}
+
+/** A change index as it goes over the wire: sets become ordered lists. */
+export interface LiveChanges {
+	count: number;
+	insertions: number;
+	deletions: number;
+	files: string[];
+	dirs: string[];
+}
+
+/** One status frame's payload. */
+export interface LiveSnapshot {
+	/** Server wall clock when the snapshot was taken, in ms. */
+	at: number;
+	/** How long the server has been listening, in ms. */
+	uptimeMs: number;
+	/** Requests the server has answered so far, this one included. */
+	requests: number;
+	/** Branch or detached head, or `null` outside a repository. */
+	git: GitStatus | null;
+	/** Uncommitted changes against `HEAD`, or `null` when unavailable. */
+	changes: LiveChanges | null;
+}
+
+/** The snapshot a streamed frame is built from. */
+export interface LiveStatusSource {
+	snapshot(): Promise<LiveSnapshot>;
+}
+
+export interface LiveStatusOptions {
+	/** Read-only git context; omitted when the page has none. */
+	git?: GitStatusProvider;
+	/** Read-only diff provider; omitted when the diff view is off. */
+	diff?: GitDiffProvider;
+	/** When the server started listening, in ms. */
+	startedAt: number;
+	/** Requests answered so far, read per snapshot. */
+	requests: () => number;
+	/** Wall-clock seam; defaults to the real clock. */
+	now?: () => number;
+}
+
+/** Read a provider, turning a rejection or an absent value into `null`. */
+async function settled<T>(read: () => Promise<T | undefined>): Promise<T | null> {
+	try {
+		return (await read()) ?? null;
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Build the status source for one server. `snapshot` never rejects: a
+ * non-repository, a failed git call, or a timeout simply leaves that field
+ * `null`, and the page keeps whatever it last showed.
+ */
+export function createLiveStatus(options: LiveStatusOptions): LiveStatusSource {
+	const now = options.now ?? (() => Date.now());
+	const diff = options.diff;
+	return {
+		async snapshot() {
+			const at = now();
+			const git = options.git ? await settled(options.git) : null;
+			const list = diff ? await settled(() => diff.list("head")) : null;
+			const index = list ? changeIndexOf(list) : null;
+			return {
+				at,
+				uptimeMs: Math.max(0, at - options.startedAt),
+				requests: options.requests(),
+				git,
+				changes: index
+					? {
+							count: index.count,
+							insertions: index.insertions,
+							deletions: index.deletions,
+							files: [...index.files].sort(),
+							dirs: [...index.dirs].sort(),
+						}
+					: null,
+			};
+		},
+	};
+}
+
+/** One server-sent event carrying a snapshot. */
+export function frameOf(snapshot: LiveSnapshot): string {
+	return `event: status\ndata: ${JSON.stringify(snapshot)}\n\n`;
+}
+
+/** A connected page: the two things a server can do to its stream. */
+export interface LiveClient {
+	/** Write one frame. */
+	write(frame: string): void;
+	/** End the stream. */
+	end(): void;
+}
+
+/** Starts a repeating tick and returns its cancel. */
+export type LiveTimer = (tick: () => void, intervalMs: number) => () => void;
+
+/** Starts a one-shot delay and returns its cancel. */
+export type LiveTimeout = (run: () => void, delayMs: number) => () => void;
+
+/** The default ticker: a repeating timer that cannot hold the process open. */
+const defaultTicker: LiveTimer = (tick, intervalMs) => defaultInterval(intervalMs, tick);
+
+/** The default grace timer: one shot, and it cannot hold the process open either. */
+const defaultTimeout: LiveTimeout = (run, delayMs) => defaultTimer(delayMs, run);
+
+export interface LiveChannelOptions {
+	/** What each frame carries. */
+	status: LiveStatusSource;
+	/** How far apart the frames are, in ms. */
+	intervalMs: number;
+	/** How long the last page's departure is held before `onIdle` is called, in ms. */
+	idleMs: number;
+	/** Called once the last page has been gone for `idleMs`; omitted, the channel only idles. */
+	onIdle?: () => void;
+	/** Timer seam; defaults to an unref'd interval. */
+	timer?: LiveTimer;
+	/** Grace seam; defaults to an unref'd timeout. */
+	timeout?: LiveTimeout;
+}
+
+/** The fan-out for one server: pages attach, ticks publish, close ends them. */
+export interface LiveChannel {
+	/** Add a connected page, send it the current status, and return its detach. */
+	attach(client: LiveClient): () => void;
+	/** End every connected page, stop the ticker, and drop a pending idle stop. */
+	close(): void;
+}
+
+/**
+ * Build a channel for one server. The ticker runs only while at least one page
+ * is attached, so an idle server does no status work at all; the idle stop is one
+ * timer armed when the last page leaves and cancelled by the next page, so a
+ * reload keeps the server and a closed window releases it.
+ */
+export function createLiveChannel(options: LiveChannelOptions): LiveChannel {
+	const timer = options.timer ?? defaultTicker;
+	const timeout = options.timeout ?? defaultTimeout;
+	const clients = new Set<LiveClient>();
+	let cancel: (() => void) | undefined;
+	let cancelIdle: (() => void) | undefined;
+	let inFlight = false;
+
+	const stop = (): void => {
+		cancel?.();
+		cancel = undefined;
+	};
+
+	const cancelIdleStop = (): void => {
+		cancelIdle?.();
+		cancelIdle = undefined;
+	};
+
+	const armIdleStop = (): void => {
+		if (!options.onIdle || cancelIdle) return;
+		cancelIdle = timeout(() => {
+			cancelIdle = undefined;
+			options.onIdle?.();
+		}, options.idleMs);
+	};
+
+	/** Nobody is reading a frame any more: park the ticker and start the grace. */
+	const pageLeft = (): void => {
+		stop();
+		armIdleStop();
+	};
+
+	const send = (frame: string): void => {
+		for (const client of clients) {
+			try {
+				client.write(frame);
+			} catch {
+				clients.delete(client);
+			}
+		}
+		if (clients.size === 0) pageLeft();
+	};
+
+	// One snapshot serves every attached page, so a tick is one git read and one
+	// serialization however many tabs are open.
+	const publish = async (): Promise<void> => {
+		if (inFlight) return;
+		inFlight = true;
+		try {
+			send(frameOf(await options.status.snapshot()));
+		} finally {
+			inFlight = false;
+		}
+	};
+
+	return {
+		attach(client) {
+			cancelIdleStop();
+			clients.add(client);
+			cancel ??= timer(() => void publish(), options.intervalMs);
+			void publish();
+			return () => {
+				if (!clients.delete(client)) return;
+				if (clients.size === 0) pageLeft();
+			};
+		},
+		close() {
+			cancelIdleStop();
+			stop();
+			for (const client of clients) client.end();
+			clients.clear();
+		},
+	};
+}

package/extensions/file-browse/markdown.ts

@@ -25,7 +25,7 @@
  * policy and raw HTML do not.
  */
 
-import { escapeHtml } from "../../lib/escape.ts";
+import { decodeCodePoint, escapeHtml } from "../../lib/escape.ts";
 import { fenceLanguage, highlightLines } from "../../lib/highlight.ts";
 import {
 	closesSuppressed,
@@ -739,13 +739,6 @@ interface Entity {
 	length: number;
 }
 
-/** A code point, or U+FFFD when the reference is a surrogate or out of range. */
-function codePoint(value: number): string {
-	if (!Number.isFinite(value) || value <= 0 || value > 0x10ffff || (value >= 0xd800 && value <= 0xdfff))
-		return "\uFFFD";
-	return String.fromCodePoint(value);
-}
-
 /**
  * Match a numeric or named character reference at `start`. Decoding happens in
  * the inline scanner rather than a pre-pass so an entity cannot become Markdown
@@ -755,8 +748,8 @@ function matchEntity(text: string, start: number): Entity | undefined {
 	const match = /^&(?:#([0-9]{1,7})|#[xX]([0-9a-fA-F]{1,6})|([a-zA-Z][a-zA-Z0-9]{1,31}));/.exec(text.slice(start));
 	if (!match) return undefined;
 	let value: string | undefined;
-	if (match[1] !== undefined) value = codePoint(Number(match[1]));
-	else if (match[2] !== undefined) value = codePoint(Number.parseInt(match[2], 16));
+	if (match[1] !== undefined) value = decodeCodePoint(Number(match[1]));
+	else if (match[2] !== undefined) value = decodeCodePoint(Number.parseInt(match[2], 16));
 	else if (match[3] !== undefined && Object.hasOwn(NAMED_ENTITIES, match[3])) value = NAMED_ENTITIES[match[3]];
 	if (value === undefined) return undefined;
 	return { value, length: match[0].length };

package/extensions/file-browse/raw-html.ts

@@ -25,7 +25,7 @@
  * how `<details>` wraps Markdown.
  */
 
-import { escapeHtml } from "../../lib/escape.ts";
+import { decodeCodePoint, escapeHtml } from "../../lib/escape.ts";
 import { resolveImage, resolveLink } from "./urls.ts";
 
 /** Elements re-emitted with sanitized attributes. */
@@ -353,21 +353,14 @@ function decodeAttribute(value: string): string {
 	return value.replace(
 		ATTRIBUTE_ENTITY,
 		(match, decimal: string | undefined, hex: string | undefined, named: string | undefined) => {
-			if (decimal !== undefined) return codePoint(Number(decimal));
-			if (hex !== undefined) return codePoint(Number.parseInt(hex, 16));
+			if (decimal !== undefined) return decodeCodePoint(Number(decimal));
+			if (hex !== undefined) return decodeCodePoint(Number.parseInt(hex, 16));
 			if (named !== undefined && Object.hasOwn(ATTRIBUTE_ENTITIES, named)) return ATTRIBUTE_ENTITIES[named];
 			return match;
 		},
 	);
 }
 
-/** A code point, or U+FFFD when the reference is a surrogate or out of range. */
-function codePoint(value: number): string {
-	if (!Number.isFinite(value) || value <= 0 || value > 0x10ffff || (value >= 0xd800 && value <= 0xdfff))
-		return "\uFFFD";
-	return String.fromCodePoint(value);
-}
-
 /** The first value for `name`, decoded, so a duplicate attribute cannot override it. */
 function attribute(tag: RawTag, name: string): string | undefined {
 	const found = tag.attrs.find((candidate) => candidate.name === name);

package/extensions/file-browse/router.ts

@@ -10,6 +10,7 @@
 import type { Stats } from "node:fs";
 import { stat } from "node:fs/promises";
 import {
+	eventHeaders,
 	htmlResponse,
 	isLocalHostHeader,
 	jsonError,
@@ -22,12 +23,14 @@ import {
 import { THEME_JS } from "../../lib/web/index.ts";
 import { CLIENT_JS } from "./client.ts";
 import type { ServeConfig } from "./config.ts";
-import { changeDirs, isDiffMode, type DiffMode } from "./diff.ts";
+import { isDiffMode, type DiffMode } from "./diff.ts";
 import type { DiffList, GitDiffProvider, GitStatus, GitStatusProvider } from "./git.ts";
+import { changeIndexOf, type LiveStatusSource } from "./live.ts";
 import {
 	buildFileIndex,
 	buildTree,
 	contentTypeFor,
+	directoryView,
 	isImageName,
 	listDirectory,
 	readFileView,
@@ -50,6 +53,8 @@ export interface ServeContext {
 	diff?: GitDiffProvider;
 	/** Cached quick-open file index; built on demand when omitted. */
 	index?: FileIndexProvider;
+	/** Snapshot source for the live status channel; omitted when live status is off. */
+	live?: LiveStatusSource;
 }
 
 /** Most palette rows the client will render for one query. */
@@ -93,15 +98,21 @@ async function diffFor(ctx: ServeContext, mode: DiffMode) {
 
 /** The marker/totals index derived from a change list. */
 function summaryOf(list: DiffList): ChangeSummary {
+	const index = changeIndexOf(list);
 	return {
-		count: list.files.length,
-		insertions: list.insertions,
-		deletions: list.deletions,
-		files: new Set(list.files.map((file) => file.rel)),
-		dirs: changeDirs(list.files),
+		count: index.count,
+		insertions: index.insertions,
+		deletions: index.deletions,
+		files: index.files,
+		dirs: index.dirs,
 	};
 }
 
+/** The live chrome a page renders, or `undefined` when live status is off. */
+function liveOf(ctx: ServeContext): { intervalMs: number } | undefined {
+	return ctx.config.live && ctx.live ? { intervalMs: ctx.config.liveIntervalMs } : undefined;
+}
+
 /** The `head` change summary, for the header chip, tree markers, and file action. */
 async function changed(ctx: ServeContext): Promise<ChangeSummary | undefined> {
 	const list = await diffFor(ctx, "head");
@@ -135,6 +146,7 @@ async function errorPage(
 		message,
 		tree,
 		git: await gitFor(ctx),
+		live: liveOf(ctx),
 	});
 	return htmlResponse(status, body, extra);
 }
@@ -158,8 +170,7 @@ async function view(ctx: ServeContext, rawRel: string, raw: boolean): Promise<Se
 }
 
 async function directoryResponse(ctx: ServeContext, rel: string): Promise<ServeResponse> {
-	const listing = await listDirectory(ctx.root, rel, ctx.config.maxDirEntries);
-	const tree = await treeFor(ctx, rel);
+	const { listing, tree } = await directoryView(ctx.root, rel, ctx.config.maxDirEntries);
 	const git = await gitFor(ctx);
 	const changes = await changed(ctx);
 	return htmlResponse(
@@ -173,6 +184,7 @@ async function directoryResponse(ctx: ServeContext, rel: string): Promise<ServeR
 			maxThumbBytes: ctx.config.maxThumbBytes,
 			git,
 			summary: changes,
+			live: liveOf(ctx),
 		}),
 	);
 }
@@ -195,6 +207,7 @@ async function fileResponse(ctx: ServeContext, rel: string, raw: boolean): Promi
 			markdownHtml: ctx.config.markdownHtml,
 			changed: changes?.files.has(rel),
 			summary: changes,
+			live: liveOf(ctx),
 		}),
 	);
 }
@@ -215,6 +228,7 @@ async function diffOverview(ctx: ServeContext, mode: DiffMode): Promise<ServeRes
 			tree,
 			git,
 			summary: list ? summaryOf(list) : undefined,
+			live: liveOf(ctx),
 		}),
 	);
 }
@@ -246,6 +260,7 @@ async function diffFile(ctx: ServeContext, rawRel: string, mode: DiffMode): Prom
 			tree,
 			git,
 			summary: changes,
+			live: liveOf(ctx),
 		}),
 	);
 }
@@ -304,6 +319,15 @@ async function filesApi(ctx: ServeContext, query: string): Promise<ServeResponse
 	return jsonResponse(200, { query, total: index.files.length, truncated: index.truncated, results });
 }
 
+/**
+ * The live status stream: a marker response the server in `server.ts` keeps open
+ * and feeds from the same source.
+ */
+function liveEvents(ctx: ServeContext): ServeResponse {
+	if (!ctx.config.live || !ctx.live) throw new HttpError(404, "Live status is not available.");
+	return { status: 200, headers: eventHeaders(), stream: true };
+}
+
 /**
  * Handle one request. `method` and `headers` are the raw HTTP values; `rawUrl`
  * is the request target (path plus optional query).
@@ -332,6 +356,7 @@ export async function handleRequest(
 		if (pathname === "/favicon.ico") return { status: 204, headers: pageHeaders(), body: "" };
 		if (pathname === "/api/tree") return await treeApi(ctx, search.get("path") ?? "");
 		if (pathname === "/api/files") return await filesApi(ctx, search.get("q") ?? "");
+		if (pathname === "/events") return liveEvents(ctx);
 		const rawMode = search.get("mode");
 		if (rawMode !== null && !isDiffMode(rawMode)) return errorPage(ctx, 400, "Unknown diff mode.");
 		const mode: DiffMode = isDiffMode(rawMode) ? rawMode : "head";

package/extensions/file-browse/server.ts

@@ -2,21 +2,30 @@
  * The HTTP server for the browse extension.
  *
  * Wraps `node:http` around the pure `handleRequest`: it resolves the root once,
- * binds `127.0.0.1`, streams `/raw` responses from disk, and exposes an
- * idempotent `close()`. The request handler is injectable so tests can avoid a
- * socket when they only need routing.
+ * binds `127.0.0.1`, streams `/raw` responses from disk, 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.
  *
- * The bind, the response writer, and the close come from `lib/http`, which `plan`
- * shares; what stays here is this server's own request handler and the catch that
- * turns a thrown handler into a plain-text 500.
+ * The bind, the response writer, the event-stream head, and the close come from
+ * `lib/http`, which `plan` shares; what stays here is this server's own request
+ * handler, its request count, and the catch that turns a thrown handler into a
+ * plain-text 500.
  */
 
 import { realpathSync } from "node:fs";
 import { createServer } from "node:http";
-import { bindLoopback, createCloser, respond, textResponse, type ServeResponse } from "../../lib/http/index.ts";
-import type { ServeConfig } from "./config.ts";
+import {
+	bindLoopback,
+	createCloser,
+	openEventStream,
+	respond,
+	textResponse,
+	type ServeResponse,
+} from "../../lib/http/index.ts";
+import { IDLE_STOP_MS, type ServeConfig } from "./config.ts";
 import { createFileIndex } from "./files.ts";
 import type { GitDiffProvider, GitStatusProvider } from "./git.ts";
+import { createLiveChannel, createLiveStatus } from "./live.ts";
 import { handleRequest, type ServeContext } from "./router.ts";
 
 export interface FileServer {
@@ -37,6 +46,10 @@ export interface FileServerOptions {
 	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()`. */
+	onIdle?: () => void;
+	/** Grace before `onIdle`, in ms; defaults to `IDLE_STOP_MS`. */
+	idleStopMs?: number;
 	/** Override the request handler (tests). */
 	handler?: typeof handleRequest;
 }
@@ -44,16 +57,38 @@ export interface FileServerOptions {
 /** Start a read-only server rooted at `options.root` on 127.0.0.1. */
 export async function createFileServer(options: FileServerOptions): Promise<FileServer> {
 	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
+	// many requests it has answered. Both are read per frame, never cached.
+	let requests = 0;
+	const status = config.live
+		? createLiveStatus({
+				git: options.git,
+				diff: config.gitDiff ? options.diff : undefined,
+				startedAt: Date.now(),
+				requests: () => requests,
+			})
+		: undefined;
+	const live = status
+		? createLiveChannel({
+				status,
+				intervalMs: config.liveIntervalMs,
+				idleMs: options.idleStopMs ?? IDLE_STOP_MS,
+				onIdle: options.onIdle,
+			})
+		: undefined;
 	const context: ServeContext = {
 		root,
-		config: options.config,
+		config,
 		git: options.git,
 		diff: options.diff,
-		index: createFileIndex(root, options.config.maxIndexEntries),
+		index: createFileIndex(root, config.maxIndexEntries),
+		live: status,
 	};
 	const handler = options.handler ?? handleRequest;
 
 	const server = createServer((request, response) => {
+		requests += 1;
 		const answer = async (): Promise<ServeResponse> => {
 			try {
 				return await handler(context, request.method ?? "GET", request.url ?? "/", request.headers);
@@ -61,9 +96,39 @@ export async function createFileServer(options: FileServerOptions): Promise<File
 				return textResponse(500, "Internal error");
 			}
 		};
-		void answer().then((result) => respond(request, response, result));
+		void answer().then((result) => {
+			// A HEAD of the stream is answered as a plain response: there is no body to
+			// hold open, and the client would otherwise wait on frames it asked not to get.
+			if (!result.stream || !live || (request.method ?? "GET").toUpperCase() === "HEAD") {
+				respond(request, response, result);
+				return;
+			}
+			openEventStream(response, result);
+			const detach = live.attach({
+				write: (frame) => {
+					response.write(frame);
+				},
+				end: () => {
+					if (!response.writableEnded) response.end();
+				},
+			});
+			request.on("close", () => {
+				detach();
+				if (!response.writableEnded) response.end();
+			});
+		});
 	});
 
-	const port = await bindLoopback(server, options.config.port);
-	return { url: `http://127.0.0.1:${port}/`, port, root, close: createCloser(server) };
+	const port = await bindLoopback(server, config.port);
+	const closeServer = createCloser(server);
+	return {
+		url: `http://127.0.0.1:${port}/`,
+		port,
+		root,
+		close: async () => {
+			// End the streams first, so a connected page does not hold the close open.
+			live?.close();
+			await closeServer();
+		},
+	};
 }