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

package/extensions/file-browse/files/list.ts

@@ -0,0 +1,261 @@
+/**
+ * Directory listings and single-file reads: what a folder holds, capped and sorted, and
+ * what one file's bytes are.
+ *
+ * The filesystem reads are injected (`DirectoryFs`) so a test can count them: the property
+ * worth holding is that a directory is read once per entry, not once per row drawn.
+ */
+
+import { join } from "node:path";
+import { lstat, readdir, readFile, stat } from "node:fs/promises";
+import type { Stats } from "node:fs";
+import { mapConcurrent } from "../../../lib/pool.ts";
+import { HttpError } from "./paths.ts";
+import {
+	classifyByName,
+	contentTypeFor,
+	type EntryKind,
+	isImageName,
+	isMarkdownName,
+	isProbablyText,
+} from "./classify.ts";
+
+export interface DirEntry {
+	name: string;
+	/** Root-relative posix path. */
+	rel: string;
+	isDir: boolean;
+	isSymlink: boolean;
+	broken: boolean;
+	size: number;
+	mtimeMs: number;
+	kind: EntryKind;
+	isImage: boolean;
+}
+
+export interface Listing {
+	entries: DirEntry[];
+	total: number;
+	truncated: boolean;
+}
+
+export interface FileMeta {
+	size: number;
+	mtimeMs: number;
+	mime: string;
+}
+
+export type FileView =
+	| (FileMeta & { kind: "text"; lines: string[]; truncated: boolean; totalLines: number })
+	| (FileMeta & { kind: "markdown"; lines: string[]; truncated: boolean; totalLines: number })
+	| (FileMeta & { kind: "image" })
+	| (FileMeta & { kind: "binary" })
+	| (FileMeta & { kind: "tooLarge" });
+
+/** Whether the name has an image extension. */
+export function toAbs(root: string, rel: string): string {
+	return rel ? join(root, ...rel.split("/")) : root;
+}
+
+/** The `Dirent` fields a listing reads; a test's fake need not be a real `Dirent`. */
+export interface DirectoryEntryInfo {
+	name: string;
+	isDirectory(): boolean;
+	isSymbolicLink(): boolean;
+}
+
+/** The `Stats` fields a listing reads. */
+export interface DirectoryStats {
+	size: number;
+	mtimeMs: number;
+	isDirectory(): boolean;
+}
+
+/**
+ * The three filesystem reads a listing makes.
+ *
+ * Injected so a test can observe them: the interesting property — a directory is
+ * read once per entry, not once per entry *and* once per row drawn — is a count,
+ * not a value, and a wall-clock assertion would be flaky on a loaded machine.
+ */
+export interface DirectoryFs {
+	readdir(path: string): Promise<DirectoryEntryInfo[]>;
+	lstat(path: string): Promise<DirectoryStats>;
+	stat(path: string): Promise<DirectoryStats>;
+}
+
+/** Production reads; a symlink's size and kind come from the target. */
+const NODE_DIRECTORY_FS: DirectoryFs = {
+	readdir: (path) => readdir(path, { withFileTypes: true }),
+	lstat: (path) => lstat(path),
+	stat: (path) => stat(path),
+};
+
+/** Reads in flight per listing: enough to hide latency, bounded against a burst. */
+const LISTING_CONCURRENCY = 32;
+
+/** A row while it is still missing its metadata. */
+interface Row {
+	name: string;
+	rel: string;
+	isDir: boolean;
+	isSymlink: boolean;
+	broken: boolean;
+	size: number;
+	mtimeMs: number;
+}
+
+/**
+ * Resolve one symlink: the link's own stat, then the target's.
+ *
+ * A symlink's directory-ness is the target's, so this cannot wait until after
+ * the sort; it is also the only entry whose classification needs a read.
+ */
+async function resolveSymlink(fs: DirectoryFs, absDir: string, row: Row): Promise<void> {
+	const abs = join(absDir, row.name);
+	try {
+		const info = await fs.lstat(abs);
+		row.size = info.size;
+		row.mtimeMs = info.mtimeMs;
+	} catch {
+		// Vanished between readdir and lstat: the target read decides below.
+	}
+	try {
+		const target = await fs.stat(abs);
+		row.isDir = target.isDirectory();
+		row.size = target.size;
+		row.mtimeMs = target.mtimeMs;
+	} catch {
+		row.broken = true;
+	}
+}
+
+/**
+ * List a directory, sorted (directories first, then case-insensitive name).
+ *
+ * A listing is latency per entry, not work per entry, so it is read in three
+ * passes instead of one entry at a time:
+ *
+ * 1. `readdir`, whose dirents already say whether each name is a directory;
+ * 2. the symlinks only, resolved through the pool, because their kind is the
+ *    target's and the sort needs it;
+ * 3. the kept rows only, `stat`ed through the pool — so a directory of three
+ *    thousand names pays for the two thousand it draws, not for every name, and
+ *    pays them concurrently instead of in turn.
+ *
+ * `total` is still the directory's full entry count and `truncated` its `> limit`
+ * flip, so the page can say how many were dropped. Ties keep `readdir` order:
+ * `sort` is stable and the rows arrive unsorted.
+ */
+export async function listDirectory(
+	root: string,
+	relDir: string,
+	limit: number,
+	fs: DirectoryFs = NODE_DIRECTORY_FS,
+): Promise<Listing> {
+	const absDir = toAbs(root, relDir);
+	let dirents: DirectoryEntryInfo[];
+	try {
+		dirents = await fs.readdir(absDir);
+	} catch {
+		throw new HttpError(404, "That folder could not be read.");
+	}
+
+	const links: Row[] = [];
+	const rows: Row[] = dirents.map((dirent) => {
+		const row: Row = {
+			name: dirent.name,
+			rel: relDir ? `${relDir}/${dirent.name}` : dirent.name,
+			isDir: dirent.isDirectory(),
+			isSymlink: dirent.isSymbolicLink(),
+			broken: false,
+			size: 0,
+			mtimeMs: 0,
+		};
+		if (row.isSymlink) links.push(row);
+		return row;
+	});
+
+	await mapConcurrent(links, LISTING_CONCURRENCY, (row) => resolveSymlink(fs, absDir, row));
+
+	// Directories first, then case-insensitive name. The sort runs before the cap,
+	// so the rows that survive it are the rows that would have been drawn.
+	rows.sort((a, b) => {
+		if (a.isDir !== b.isDir) return a.isDir ? -1 : 1;
+		return a.name.toLowerCase().localeCompare(b.name.toLowerCase());
+	});
+
+	const total = rows.length;
+	const truncated = total > limit;
+	const kept = truncated ? rows.slice(0, limit) : rows;
+
+	await mapConcurrent(
+		kept.filter((row) => !row.isSymlink),
+		LISTING_CONCURRENCY,
+		async (row) => {
+			try {
+				const info = await fs.stat(join(absDir, row.name));
+				row.size = info.size;
+				row.mtimeMs = info.mtimeMs;
+			} catch {
+				// Directory entry vanished between readdir and stat.
+			}
+		},
+	);
+
+	const entries: DirEntry[] = kept.map((row) => {
+		const kind: EntryKind = row.isDir ? "directory" : classifyByName(row.name);
+		return {
+			name: row.name,
+			rel: row.rel,
+			isDir: row.isDir,
+			isSymlink: row.isSymlink,
+			broken: row.broken,
+			size: row.size,
+			mtimeMs: row.mtimeMs,
+			kind,
+			isImage: !row.isDir && kind === "image",
+		};
+	});
+
+	return { entries, total, truncated };
+}
+
+/** Read a file into a renderable view, honouring the size and line caps. */
+export async function readFileView(
+	root: string,
+	rel: string,
+	maxFileBytes: number,
+	maxTextLines: number,
+	markdownEnabled = true,
+): Promise<FileView> {
+	const abs = toAbs(root, rel);
+	let info: Stats;
+	try {
+		info = await stat(abs);
+	} catch {
+		throw new HttpError(404, "That file could not be read.");
+	}
+	if (info.isDirectory()) throw new HttpError(404, "That path is a folder.");
+
+	const meta: FileMeta = { size: info.size, mtimeMs: info.mtimeMs, mime: contentTypeFor(rel) };
+	if (isImageName(rel)) return { kind: "image", ...meta };
+	if (info.size > maxFileBytes) return { kind: "tooLarge", ...meta };
+
+	let buffer: Buffer;
+	try {
+		buffer = await readFile(abs);
+	} catch {
+		throw new HttpError(404, "That file could not be read.");
+	}
+	if (!isProbablyText(buffer)) return { kind: "binary", ...meta };
+
+	const allLines = buffer.toString("utf-8").split(/\r\n|\r|\n/);
+	const truncated = allLines.length > maxTextLines;
+	const lines = truncated ? allLines.slice(0, maxTextLines) : allLines;
+	const kind = markdownEnabled && isMarkdownName(rel) ? "markdown" : "text";
+	if (kind === "markdown") {
+		return { kind: "markdown", ...meta, lines, truncated, totalLines: allLines.length };
+	}
+	return { kind: "text", ...meta, lines, truncated, totalLines: allLines.length };
+}

package/extensions/file-browse/{paths.ts → files/paths.ts}

@@ -9,7 +9,7 @@
 
 import { realpathSync } from "node:fs";
 import { basename, dirname, isAbsolute, relative, resolve, sep } from "node:path";
-import { isInside } from "../../lib/path.ts";
+import { isInside } from "../../../lib/path.ts";
 
 /** An HTTP-shaped failure the router turns into a status page. */
 export class HttpError extends Error {

package/extensions/file-browse/files/tree.ts

@@ -0,0 +1,101 @@
+/**
+ * The sidebar tree: the current path's ancestors expanded, siblings collapsed.
+ *
+ * Its rows are the same `DirEntry` a listing produces, so the tree and the listing cannot
+ * disagree about what one name is.
+ */
+
+import { basename } from "node:path";
+import type { EntryKind } from "./classify.ts";
+import { type Listing, listDirectory } from "./list.ts";
+
+export interface TreeNode {
+	name: string;
+	rel: string;
+	isDir: boolean;
+	isImage: boolean;
+	/** True for a symlink whose target cannot be resolved. */
+	broken: boolean;
+	kind: EntryKind;
+	children: TreeNode[];
+}
+
+/**
+ * Build the sidebar tree: the current path's ancestors are expanded so the
+ * active item is always visible, and siblings are shown collapsed.
+ */
+export async function buildTree(root: string, currentRel: string, limit: number): Promise<TreeNode> {
+	return buildNode(root, "", currentRel, basename(root) || root, limit);
+}
+
+/** A directory page's two views of one directory. */
+export interface DirectoryView {
+	/** The current directory's own rows, for the page's listing. */
+	listing: Listing;
+	/** The sidebar tree, with the current path expanded. */
+	tree: TreeNode;
+}
+
+/**
+ * One walk for a directory page: the listing it draws, and the tree that shows
+ * where it sits.
+ *
+ * `listDirectory` is what decides whether the directory can be read at all, so it
+ * runs first and its 404 is the page's error. The walk then reuses that listing
+ * for the same directory instead of reading it a second time; the ancestors are
+ * still read once each, which is what the tree needs.
+ */
+export async function directoryView(root: string, currentRel: string, limit: number): Promise<DirectoryView> {
+	const listing = await listDirectory(root, currentRel, limit);
+	const tree = await buildNode(root, "", currentRel, basename(root) || root, limit, { rel: currentRel, listing });
+	return { listing, tree };
+}
+
+async function buildNode(
+	root: string,
+	relDir: string,
+	currentRel: string,
+	label: string,
+	limit: number,
+	/** A listing the caller already read for this directory, so it is not re-read. */
+	known?: { rel: string; listing: Listing },
+): Promise<TreeNode> {
+	const node: TreeNode = {
+		name: label,
+		rel: relDir,
+		isDir: true,
+		isImage: false,
+		broken: false,
+		kind: "directory",
+		children: [],
+	};
+	let listing: Listing;
+	if (known && known.rel === relDir) {
+		listing = known.listing;
+	} else {
+		try {
+			listing = await listDirectory(root, relDir, limit);
+		} catch {
+			return node;
+		}
+	}
+	for (const entry of listing.entries) {
+		const child: TreeNode = {
+			name: entry.name,
+			rel: entry.rel,
+			isDir: entry.isDir,
+			isImage: entry.isImage,
+			broken: entry.broken,
+			kind: entry.kind,
+			children: [],
+		};
+		if (entry.isDir) {
+			const onPath = currentRel === entry.rel || currentRel.startsWith(`${entry.rel}/`);
+			if (onPath) {
+				child.children = (await buildNode(root, entry.rel, currentRel, entry.name, limit, known)).children;
+			}
+		}
+		node.children.push(child);
+	}
+	return node;
+}

package/extensions/file-browse/{git.ts → git/git.ts}

@@ -9,7 +9,14 @@
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { createExecRunner, currentBranch, hasCommits, repoRoot, revParse, type RunGit } from "../../lib/git/index.ts";
+import {
+	createExecRunner,
+	currentBranch,
+	hasCommits,
+	repoRoot,
+	revParse,
+	type RunGit,
+} from "../../../lib/git/index.ts";
 import {
 	diffArgs,
 	inMode,
@@ -18,8 +25,8 @@ import {
 	type ChangedFile,
 	type DiffLine,
 	type DiffMode,
-} from "./diff.ts";
-import { readFileView } from "./files.ts";
+} from "../text/diff.ts";
+import { readFileView } from "../files/files.ts";
 
 export interface GitStatus {
 	/** Checked-out branch, when HEAD is attached. */

package/extensions/file-browse/index.ts

@@ -16,11 +16,11 @@ import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-a
 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.ts";
-import { createGitDiff, createGitStatus } from "./git.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 "./paths.ts";
-import { createFileServer, type FileServer } from "./server.ts";
+import { HttpError, resolveRequestPath } from "./files/paths.ts";
+import { createFileServer, type FileServer } from "./transport/server.ts";
 
 export interface FileBrowserDeps {
 	/** Override the server factory (tests). */

package/extensions/file-browse/{live.ts → live/live.ts}

@@ -12,10 +12,11 @@
  * pair — so the whole feed is tested without one.
  */
 
-import { defaultInterval, defaultTimer } from "../../lib/timer.ts";
-import { LIVE_MAX_CLIENTS } from "./config.ts";
-import { changeDirs } from "./diff.ts";
-import type { DiffList, GitDiffProvider, GitStatus, GitStatusProvider } from "./git.ts";
+import type { EventSink } from "../../../lib/http/index.ts";
+import { defaultInterval, type RepeatTimer } from "../../../lib/timer.ts";
+import { LIVE_MAX_CLIENTS } from "../config/config.ts";
+import { changeDirs } from "../text/diff.ts";
+import type { DiffList, GitDiffProvider, GitStatus, GitStatusProvider } from "../git/git.ts";
 import { changeRevision } from "./rev.ts";
 
 /**
@@ -141,48 +142,25 @@ 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);
+/** A connected page, as the channel writes it: the sink's two verbs. */
+export type LiveClient = EventSink;
 
 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;
 	/** How many pages may attach at once; defaults to `LIVE_MAX_CLIENTS`. */
 	maxClients?: 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;
+	timer?: RepeatTimer;
 }
 
 /** 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. */
+	/** End every connected page, and stop the ticker. */
 	close(): void;
 	/**
 	 * Whether another page must be refused. The caller asks before it opens the
@@ -192,18 +170,18 @@ export interface LiveChannel {
 }
 
 /**
- * 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.
+ * 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 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
+ * here.
  */
 export function createLiveChannel(options: LiveChannelOptions): LiveChannel {
-	const timer = options.timer ?? defaultTicker;
-	const timeout = options.timeout ?? defaultTimeout;
+	const timer = options.timer ?? defaultInterval;
 	const maxClients = options.maxClients ?? LIVE_MAX_CLIENTS;
 	const clients = new Set<LiveClient>();
 	let cancel: (() => void) | undefined;
-	let cancelIdle: (() => void) | undefined;
 	let inFlight = false;
 
 	const stop = (): void => {
@@ -211,34 +189,9 @@ export function createLiveChannel(options: LiveChannelOptions): LiveChannel {
 		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();
+		for (const client of clients) client.write(frame);
+		if (clients.size === 0) stop();
 	};
 
 	// One snapshot serves every attached page, so a tick is one git read and one
@@ -255,17 +208,15 @@ export function createLiveChannel(options: LiveChannelOptions): LiveChannel {
 
 	return {
 		attach(client) {
-			cancelIdleStop();
 			clients.add(client);
-			cancel ??= timer(() => void publish(), options.intervalMs);
+			cancel ??= timer(options.intervalMs, () => void publish());
 			void publish();
 			return () => {
 				if (!clients.delete(client)) return;
-				if (clients.size === 0) pageLeft();
+				if (clients.size === 0) stop();
 			};
 		},
 		close() {
-			cancelIdleStop();
 			stop();
 			for (const client of clients) client.end();
 			clients.clear();

package/extensions/file-browse/{router.ts → transport/router.ts}

@@ -15,18 +15,17 @@ import {
 	isLocalHostHeader,
 	jsonError,
 	jsonResponse,
-	pageHeaders,
 	parseRequestUrl,
 	scriptHeaders,
 	type ServeResponse,
-} from "../../lib/http/index.ts";
-import { THEME_JS, THEME_JS_PATH } from "../../lib/web/index.ts";
-import { CLIENT_JS } from "./client.ts";
-import type { LivePage } from "./chrome.ts";
-import type { ServeConfig } from "./config.ts";
-import { isDiffMode, type DiffMode } from "./diff.ts";
-import type { DiffList, GitDiffProvider, GitStatus, GitStatusProvider } from "./git.ts";
-import { changeIndexOf, type LiveStatusSource } from "./live.ts";
+} from "../../../lib/http/index.ts";
+import { THEME_JS, THEME_JS_PATH } from "../../../lib/web/index.ts";
+import { CLIENT_JS } from "../view/client.ts";
+import type { LivePage } from "../view/chrome.ts";
+import type { ServeConfig } from "../config/config.ts";
+import { isDiffMode, type DiffMode } from "../text/diff.ts";
+import type { DiffList, GitDiffProvider, GitStatus, GitStatusProvider } from "../git/git.ts";
+import { changeIndexOf, type LiveStatusSource } from "../live/live.ts";
 import {
 	buildFileIndex,
 	buildTree,
@@ -38,13 +37,19 @@ import {
 	type DirEntry,
 	type FileIndexProvider,
 	type TreeNode,
-} from "./files.ts";
-import { FOLDER_ICON, iconHref, languageOf } from "./icons.ts";
-import { fuzzySearch } from "./fuzzy.ts";
-import { renderDirectoryPage, renderDiffPage, renderErrorPage, renderFileDiffPage, renderFilePage } from "./html.ts";
-import type { ChangeSummary } from "./html.ts";
-import { encodePath, HttpError, relativePath, resolveDecodedPath, resolveRequestPath } from "./paths.ts";
-import { listingRevision } from "./rev.ts";
+} from "../files/files.ts";
+import { FOLDER_ICON, iconHref, languageOf } from "../view/icons.ts";
+import { fuzzySearch } from "../text/fuzzy.ts";
+import {
+	renderDirectoryPage,
+	renderDiffPage,
+	renderErrorPage,
+	renderFileDiffPage,
+	renderFilePage,
+} from "../view/html.ts";
+import type { ChangeSummary } from "../view/html.ts";
+import { encodePath, HttpError, relativePath, resolveDecodedPath, resolveRequestPath } from "../files/paths.ts";
+import { listingRevision } from "../live/rev.ts";
 
 export interface ServeContext {
 	root: string;
@@ -373,7 +378,6 @@ export async function handleRequest(
 	try {
 		if (pathname === "/app.js") return { status: 200, headers: scriptHeaders(), body: CLIENT_JS };
 		if (pathname === THEME_JS_PATH) return { status: 200, headers: scriptHeaders(), body: THEME_JS };
-		if (pathname === "/favicon.ico") return { status: 204, headers: pageHeaders(), body: "" };
 		if (pathname === "/api/tree") return await treeApi(ctx, search.get("path") ?? "");
 		if (pathname === "/api/dir-rev") return await dirRevApi(ctx, search.get("path") ?? "");
 		if (pathname === "/api/files") return await filesApi(ctx, search.get("q") ?? "");