@gavin-hu/my-pi-agent 0.7.0 → 0.8.0

package/extensions/bytefly/panel/join.ts

@@ -0,0 +1,103 @@
+/**
+ * The merge behind the unified panel: one row per extension resource, joining
+ * the picker's resolved items to the doctor's reports.
+ *
+ * The join key is the extension directory (`basename(dirname(path))`), not the
+ * display name: a subfolder resource is shown as `web-access/index.ts` but its
+ * report is named `web-access`. A directory name is only usable when it maps to
+ * exactly one unique resource path — two unrelated extensions can share a
+ * directory name (a user `plan` beside the package's `plan`) and every flat file
+ * has the shared directory `extensions`, so a colliding name claims no report.
+ * The report then falls through to the trailing `Not resolved` group rather than
+ * lending one resource another's health.
+ *
+ * Row keys are the unique resource identity (`source:path`, or `report:<name>`
+ * for a report with no item) so the cursor survives a rebuild even when two
+ * rows share a directory name. Items keep the picker's grouping and order, and
+ * a row never invents health: an item without a report carries no glyph and no
+ * summary.
+ */
+
+import { basename, dirname } from "node:path";
+import type { ExtensionReport } from "../../../lib/requirements.ts";
+import { buildEntries } from "../picker/resources.ts";
+import type { ResourceItem } from "../picker/types.ts";
+import type { PanelGroup, PanelModel, PanelRow } from "./types.ts";
+
+/** The extension directory name that joins a resolved item to its report. */
+export function extensionName(path: string): string {
+	return basename(dirname(path));
+}
+
+/** Unique identity of a resolved resource, independent of the directory name. */
+export function resourceKey(item: ResourceItem): string {
+	return `${item.metadata.source}:${item.path}`;
+}
+
+/** Row key for a report that has no resolved extension item. */
+function reportKey(name: string): string {
+	return `report:${name}`;
+}
+
+/** Group key and label for reports with no resolved extension item. */
+export const REPORT_ONLY_GROUP = "reported-only";
+export const REPORT_ONLY_LABEL = "Not resolved";
+
+export interface PanelJoinOptions {
+	items: readonly ResourceItem[];
+	reports: readonly ExtensionReport[];
+	agentDir: string;
+	/** Narrow to one extension directory or report name, or `undefined` for the full list. */
+	filter?: string;
+}
+
+/** Build the merged model for the current items and reports. */
+export function buildPanelModel(options: PanelJoinOptions): PanelModel {
+	const { items, reports, agentDir, filter } = options;
+	const byName = new Map(reports.map((report) => [report.extension, report]));
+
+	// A directory name may claim a report only when exactly one unique resource
+	// path uses it. A name shared by two resources is ambiguous, so no row claims
+	// the report and it stays available to the trailing `Not resolved` group.
+	const pathsByName = new Map<string, Set<string>>();
+	for (const item of items) {
+		const name = extensionName(item.path);
+		const paths = pathsByName.get(name) ?? new Set<string>();
+		paths.add(resourceKey(item));
+		pathsByName.set(name, paths);
+	}
+	const unambiguous = (name: string): boolean => pathsByName.get(name)?.size === 1;
+
+	const claimed = new Set<string>();
+	const groups: PanelGroup[] = [];
+	const rows: PanelRow[] = [];
+	let current: PanelGroup | undefined;
+
+	for (const entry of buildEntries([...items], agentDir)) {
+		if (entry.kind === "group") {
+			current = { key: entry.key, label: entry.label, count: 0 };
+			groups.push(current);
+			continue;
+		}
+		const item = entry.item;
+		const name = extensionName(item.path);
+		const report = unambiguous(name) ? byName.get(name) : undefined;
+		if (report) claimed.add(name);
+		if (filter !== undefined && name !== filter) continue;
+		rows.push({ key: resourceKey(item), item, report, label: entry.label, group: current?.key ?? "" });
+		if (current) current.count += 1;
+	}
+
+	const extras = reports.filter(
+		(report) => !claimed.has(report.extension) && (filter === undefined || report.extension === filter),
+	);
+	if (extras.length > 0) {
+		const group: PanelGroup = { key: REPORT_ONLY_GROUP, label: REPORT_ONLY_LABEL, count: extras.length };
+		groups.push(group);
+		for (const report of extras) {
+			rows.push({ key: reportKey(report.extension), report, label: report.extension, group: group.key });
+		}
+	}
+
+	return { groups: groups.filter((group) => group.count > 0), rows };
+}

package/extensions/bytefly/panel/tui.ts

@@ -0,0 +1,416 @@
+/**
+ * The unified bytefly panel: one docked screen listing every extension with its
+ * enable checkbox and its health.
+ *
+ * The component is derived: it rebuilds the merged model from the picker
+ * runtime and the current reports on every render, keeps the focused row's key
+ * across rebuilds, and requests a repaint only after an input changes state.
+ * Screen chrome and scroll math come from `lib/tui.ts` and `lib/list-cursor.ts`.
+ * A row without a report renders no glyph and no summary, never a false `ok`.
+ */
+
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import {
+	Key,
+	matchesKey,
+	truncateToWidth,
+	visibleWidth,
+	type Component,
+	type TuiMouseEvent,
+	type TuiMouseEventResult,
+} from "@earendil-works/pi-tui";
+import { sanitizeLine } from "../../../lib/format.ts";
+import {
+	fitRows,
+	formatRange,
+	isCloseKey,
+	ListCursor,
+	navIntent,
+	selectionMarker,
+	wheelDelta,
+} from "../../../lib/list-cursor.ts";
+import type { ExtensionReport } from "../../../lib/requirements.ts";
+import { dockListFrame, screenHint, type ViewportRowsSource } from "../../../lib/tui.ts";
+import { detailLines as reportDetailLines, reportSeverity, reportSummary, severityGlyph } from "../doctor/format.ts";
+import type { ExtensionsPickerRuntime } from "../picker/runtime.ts";
+import { summarySegments } from "./format.ts";
+import { buildPanelModel } from "./join.ts";
+import type { PanelModel, PanelRow } from "./types.ts";
+
+/** Body rows when the terminal height is unknown. */
+const SCREEN_DEFAULT_ROWS = 16;
+/** Fixed rows around the body: header, summary, blank, blank, hint, blank. */
+const FRAME_ROWS = 6;
+/** Detail rows reserved for the focused extension's findings. */
+const DETAIL_ROWS = 4;
+/** Body rows that must survive before the detail pane collapses to its title. */
+const MIN_BODY_ROWS = 3;
+
+/** A flat display entry: a group header or a selectable row. */
+type PanelEntry = { kind: "group"; key: string; label: string; count: number } | { kind: "row"; row: PanelRow };
+
+/** The next row from `from` in `direction`, or `undefined` when there is none. */
+function nextRow(entries: PanelEntry[], from: number, direction: -1 | 1): number | undefined {
+	for (let index = from + direction; index >= 0 && index < entries.length; index += direction) {
+		if (entries[index].kind === "row") return index;
+	}
+	return undefined;
+}
+
+/** Interleave the model's groups and rows into one display list. */
+function entriesOf(model: PanelModel): PanelEntry[] {
+	const entries: PanelEntry[] = [];
+	for (const group of model.groups) {
+		entries.push({ kind: "group", key: group.key, label: group.label, count: group.count });
+		for (const row of model.rows) {
+			if (row.group === group.key) entries.push({ kind: "row", row });
+		}
+	}
+	return entries;
+}
+
+/** Terminal rows, or `undefined` when the height is unknown. */
+function totalRows(source: ViewportRowsSource | undefined): number | undefined {
+	const rows = typeof source === "function" ? source() : source;
+	return rows !== undefined && Number.isFinite(rows) && rows > 0 ? rows : undefined;
+}
+
+/** Host seams for the panel screen, injected by the command runner. */
+export interface PanelComponentOptions {
+	/** The session's picker runtime: items, scope, toggles, dirty flag. */
+	runtime: ExtensionsPickerRuntime;
+	/** Current reports; read on every render so a refresh is picked up. */
+	reports: () => readonly ExtensionReport[];
+	/** Narrow to one extension directory, when the command named one. */
+	filter?: string;
+	theme: Theme;
+	agentDir: string;
+	/** Live terminal height, for the row budget. */
+	viewportRows?: ViewportRowsSource;
+	requestRender: () => void;
+	/** Re-probe with refresh; awaited before the busy state clears. */
+	refresh: () => void | Promise<void>;
+	onClose: () => void;
+	onNotice?: (message: string) => void;
+}
+
+/** The docked bytefly panel. */
+export class PanelComponent implements Component {
+	private readonly cursor: ListCursor;
+	/** Serialises toggles so a rapid double press toggles twice, not once. */
+	private chain: Promise<void> = Promise.resolve();
+	/** Key of the focused row, so it survives a rebuild that reorders rows. */
+	private focusedKey: string | undefined;
+	/** Whether the detail pane shows every check or only problems. */
+	private showDetail = false;
+	/** True while a re-probe is in flight, so `r` does not stack probes. */
+	private refreshing = false;
+
+	constructor(private readonly options: PanelComponentOptions) {
+		this.cursor = new ListCursor(() => this.options.requestRender());
+	}
+
+	/** The active theme, read live on every render. */
+	private get theme(): Theme {
+		return this.options.theme;
+	}
+
+	invalidate(): void {
+		// Everything is rebuilt from live state on each render.
+	}
+
+	/** The merged model for the current items and reports. */
+	private model(): PanelModel {
+		return buildPanelModel({
+			items: this.options.runtime.items(),
+			reports: this.options.reports(),
+			agentDir: this.options.agentDir,
+			filter: this.options.filter,
+		});
+	}
+
+	private entries(): PanelEntry[] {
+		return entriesOf(this.model());
+	}
+
+	/** Keep the focus on the same row key when the list shape changes. */
+	private retainFocus(entries: PanelEntry[]): void {
+		const entry = entries[this.cursor.selected];
+		if (entry?.kind === "row") {
+			this.focusedKey = entry.row.key;
+			return;
+		}
+		if (this.focusedKey === undefined) return;
+		const index = entries.findIndex((candidate) => candidate.kind === "row" && candidate.row.key === this.focusedKey);
+		if (index >= 0) this.cursor.selected = index;
+	}
+
+	/** Move onto the first row when the focus is not already on one. */
+	private clampSelection(entries: PanelEntry[]): void {
+		if (entries[this.cursor.selected]?.kind === "row") return;
+		const first = entries.findIndex((entry) => entry.kind === "row");
+		if (first >= 0) this.cursor.selected = first;
+	}
+
+	private firstRow(): number | undefined {
+		const index = this.entries().findIndex((entry) => entry.kind === "row");
+		return index >= 0 ? index : undefined;
+	}
+
+	private lastRow(): number | undefined {
+		const entries = this.entries();
+		for (let index = entries.length - 1; index >= 0; index -= 1) {
+			if (entries[index].kind === "row") return index;
+		}
+		return undefined;
+	}
+
+	private select(index: number | undefined): void {
+		if (index === undefined) return;
+		this.cursor.set(index, this.entries().length);
+	}
+
+	/** Move `delta` rows, skipping group headers. */
+	private move(delta: number): void {
+		if (delta === 0) return;
+		this.clampSelection(this.entries());
+		const entries = this.entries();
+		const direction = delta < 0 ? -1 : 1;
+		let index = this.cursor.selected;
+		let remaining = Math.abs(delta);
+		while (remaining > 0) {
+			const next = nextRow(entries, index, direction);
+			if (next === undefined) break;
+			index = next;
+			remaining -= 1;
+		}
+		this.select(index);
+	}
+
+	private switchScope(): void {
+		const next = this.options.runtime.scope() === "global" ? "project" : "global";
+		if (next === "project" && !this.options.runtime.projectAvailable()) {
+			this.options.onNotice?.("Project is not trusted; manage extensions in Global scope only.");
+			return;
+		}
+		this.options.runtime.setScope(next);
+		this.options.requestRender();
+	}
+
+	private toggle(): void {
+		const entry = this.entries()[this.cursor.selected];
+		if (entry?.kind !== "row" || !entry.row.item) return;
+		const item = entry.row.item;
+		this.chain = this.chain
+			.then(() => this.options.runtime.toggle(item))
+			.catch(() => undefined)
+			.then(() => this.options.requestRender());
+	}
+
+	/** Re-probe once; a second request while one is in flight is ignored. */
+	async refresh(): Promise<void> {
+		if (this.refreshing) return;
+		this.refreshing = true;
+		this.options.requestRender();
+		try {
+			await this.options.refresh();
+		} catch (error) {
+			this.options.onNotice?.(`Could not refresh: ${error instanceof Error ? error.message : String(error)}`);
+		} finally {
+			this.refreshing = false;
+			this.options.requestRender();
+		}
+	}
+
+	handleInput(data: string): void {
+		if (isCloseKey(data)) {
+			this.options.onClose();
+			return;
+		}
+		// An input can arrive before the first render; put the focus on a row.
+		this.clampSelection(this.entries());
+		if (matchesKey(data, Key.space)) {
+			this.toggle();
+			return;
+		}
+		if (matchesKey(data, Key.enter)) {
+			this.showDetail = !this.showDetail;
+			this.options.requestRender();
+			return;
+		}
+		if (matchesKey(data, Key.tab)) {
+			this.switchScope();
+			return;
+		}
+		if (matchesKey(data, "r")) {
+			void this.refresh();
+			return;
+		}
+		if (data === "g") {
+			this.select(this.firstRow());
+			return;
+		}
+		if (data === "G") {
+			this.select(this.lastRow());
+			return;
+		}
+		switch (navIntent(data)) {
+			case "up":
+				this.move(-1);
+				return;
+			case "down":
+				this.move(1);
+				return;
+			case "pageUp":
+				this.move(-Math.max(1, this.cursor.visible));
+				return;
+			case "pageDown":
+				this.move(Math.max(1, this.cursor.visible));
+				return;
+			case "home":
+				this.select(this.firstRow());
+				return;
+			case "end":
+				this.select(this.lastRow());
+				return;
+		}
+	}
+
+	handleMouse(event: TuiMouseEvent): TuiMouseEventResult | undefined {
+		const delta = wheelDelta(event);
+		if (delta === undefined) return undefined;
+		this.move(delta);
+		return { handled: true };
+	}
+
+	private summary(width: number, model: PanelModel): string {
+		const segments = summarySegments(model, this.options.runtime.scope(), {
+			filter: this.options.filter,
+			compact: width < 72,
+		});
+		const separator = this.theme.fg("dim", " · ");
+		const kept: string[] = [];
+		for (const segment of segments) {
+			const styled = this.theme.fg(segment.color, segment.text);
+			if (kept.length > 0 && visibleWidth(`  ${[...kept, styled].join(separator)}`) > width) break;
+			kept.push(styled);
+		}
+		return truncateToWidth(`  ${kept.join(separator)}`, width, "…");
+	}
+
+	private groupLine(entry: Extract<PanelEntry, { kind: "group" }>, width: number): string {
+		const label = this.theme.fg("muted", sanitizeLine(entry.label));
+		const count = this.theme.fg("dim", `(${entry.count})`);
+		return truncateToWidth(`  ${label} ${count}`, width, "…");
+	}
+
+	private rowLine(row: PanelRow, selected: boolean, width: number): string {
+		const checkbox = row.item
+			? row.item.enabled
+				? this.theme.fg("success", "[x]")
+				: this.theme.fg("dim", "[ ]")
+			: this.theme.fg("dim", "   ");
+		const severity = row.report ? reportSeverity(row.report) : undefined;
+		const glyph = severity ? severityGlyph(severity, this.theme) : " ";
+		const label = sanitizeLine(row.label);
+		const styled = selected
+			? this.theme.fg("accent", label)
+			: row.item && !row.item.enabled
+				? this.theme.fg("dim", label)
+				: label;
+		const summary = row.report ? reportSummary(row.report) : "";
+		const head = `${selectionMarker(this.theme, selected)}${checkbox} ${glyph} `;
+		if (!summary) return truncateToWidth(`${head}${styled}`, width, "…");
+
+		const available = Math.max(1, width - visibleWidth(head) - visibleWidth(summary) - 1);
+		const name = truncateToWidth(styled, available, "…");
+		const pad = " ".repeat(Math.max(0, available - visibleWidth(name)));
+		const tone = severity === "missing" ? "error" : severity === "degraded" ? "warning" : "dim";
+		return truncateToWidth(`${head}${name}${pad} ${this.theme.fg(tone, summary)}`, width, "…");
+	}
+
+	/** The focused row's label, findings, and the pending-changes note. */
+	private detail(row: PanelRow | undefined, width: number, budget: number): string[] {
+		const lines: string[] = [];
+		if (row?.report) {
+			const tail = reportSummary(row.report);
+			lines.push(
+				truncateToWidth(
+					`  ${this.theme.fg("muted", sanitizeLine(row.label))} ${this.theme.fg("dim", "—")} ${this.theme.fg(row.report.enabled ? "muted" : "warning", tail)}`,
+					width,
+					"…",
+				),
+			);
+			if (budget > 0) lines.push(...reportDetailLines(row.report, this.theme, width, budget, this.showDetail));
+		} else if (row?.item) {
+			lines.push(truncateToWidth(`  ${this.theme.fg("muted", sanitizeLine(row.item.path))}`, width, "…"));
+		}
+		if (this.options.runtime.isDirty()) {
+			lines.push(truncateToWidth(`  ${this.theme.fg("warning", "Saved · reload to apply")}`, width, "…"));
+		}
+		return lines;
+	}
+
+	render(width: number): string[] {
+		const w = Math.max(1, width);
+		const model = this.model();
+		const entries = entriesOf(model);
+		const summary = this.summary(w, model);
+
+		if (entries.length === 0) {
+			return dockListFrame({
+				theme: this.theme,
+				width: w,
+				title: "bytefly",
+				summary,
+				body: [truncateToWidth(`  ${this.theme.fg("dim", "No extensions found.")}`, w)],
+				hint: screenHint(this.theme, w, ["Esc close"]),
+			});
+		}
+
+		this.retainFocus(entries);
+		this.clampSelection(entries);
+
+		const focusedEntry = entries[this.cursor.selected];
+		const focused = focusedEntry?.kind === "row" ? focusedEntry.row : undefined;
+		const total = totalRows(this.options.viewportRows);
+		const detailBudget = total !== undefined && total < FRAME_ROWS + 1 + MIN_BODY_ROWS + DETAIL_ROWS ? 0 : DETAIL_ROWS;
+		const detail = this.detail(focused, w, detailBudget);
+
+		this.cursor.visible = fitRows(
+			this.options.viewportRows,
+			entries.length,
+			FRAME_ROWS + detail.length,
+			SCREEN_DEFAULT_ROWS,
+		);
+		this.cursor.sync(entries.length);
+		const { start, end } = this.cursor.window(entries.length);
+
+		const body: string[] = [];
+		for (let index = start; index < end; index += 1) {
+			const entry = entries[index];
+			if (entry.kind === "group") body.push(this.groupLine(entry, w));
+			else body.push(this.rowLine(entry.row, index === this.cursor.selected, w));
+		}
+
+		return dockListFrame({
+			theme: this.theme,
+			width: w,
+			title: "bytefly",
+			summary,
+			body,
+			range: this.cursor.clipped(entries.length)
+				? formatRange(this.theme, w, { start, end, total: entries.length })
+				: undefined,
+			detail: detail.length > 0 ? detail : undefined,
+			hint: screenHint(this.theme, w, [
+				"Esc close",
+				"Space toggle",
+				"Enter detail",
+				"Tab scope",
+				this.refreshing ? "refreshing…" : "r refresh",
+				"↑/↓ select",
+			]),
+		});
+	}
+}

package/extensions/bytefly/panel/types.ts

@@ -0,0 +1,44 @@
+/**
+ * Types for the unified bytefly panel: the merged row model the formatter and
+ * the screen both read.
+ *
+ * A row is the union of one picker item and its doctor report, joined on the
+ * extension directory name. Either side may be absent: an item without a report
+ * renders no health, and a report without an item has no checkbox.
+ */
+
+import type { ExtensionReport } from "../../../lib/requirements.ts";
+import type { ResourceItem } from "../picker/types.ts";
+
+/** One group header in the merged model. */
+export interface PanelGroup {
+	/** Group key from the picker's `buildEntries`. */
+	key: string;
+	/** Group label, e.g. `npm:pkg (user)`. */
+	label: string;
+	/** Number of rows under this group. */
+	count: number;
+}
+
+/** One extension row: a picker item, a doctor report, or both. */
+export interface PanelRow {
+	/**
+	 * Unique row identity: `source:path` for an item, `report:<name>` for a
+	 * report-only row. Never the directory name, which two rows can share.
+	 */
+	key: string;
+	/** The resolved extension item, when the picker has one. */
+	item?: ResourceItem;
+	/** The doctor report, when one exists for this directory. */
+	report?: ExtensionReport;
+	/** Picker display name (`folder/file.ts`), or the report name when no item. */
+	label: string;
+	/** Key of the group this row belongs to. */
+	group: string;
+}
+
+/** The merged model: group headers and rows, both in display order. */
+export interface PanelModel {
+	groups: PanelGroup[];
+	rows: PanelRow[];
+}

package/extensions/bytefly/picker/resources.ts

@@ -213,14 +213,3 @@ export function firstSelectable(entries: Entry[], from = 0): number | undefined
 	}
 	return undefined;
 }
-
-/** Plain-text listing used outside TUI mode. */
-export function formatListing(items: ResourceItem[], agentDir: string): string {
-	if (items.length === 0) return "No extensions found.";
-	const lines: string[] = [];
-	for (const entry of buildEntries(items, agentDir)) {
-		if (entry.kind === "group") lines.push(`${entry.label} (${entry.count})`);
-		else lines.push(`  [${entry.item.enabled ? "x" : " "}] ${entry.label}`);
-	}
-	return lines.join("\n");
-}

package/extensions/file-browse/README.md

@@ -8,6 +8,8 @@ highlighted code, per-language icons, and a fuzzy quick-open palette. It is
 bound to `127.0.0.1`
 and ships no dependencies — `node:http` plus one small vanilla script.
 
+<img src="../../assets/file-browse.png" alt="The loopback file browser, showing the path filter, the file tree, and a rendered Markdown preview" width="100%">
+
 ```bash
 pi --extension ./extensions/file-browse   # load just this extension
 pi -e .                                    # load the whole @gavin-hu/my-pi-agent package
@@ -31,10 +33,12 @@ pi -e .                                    # load the whole @gavin-hu/my-pi-agen
   Python (`py`, `pyw`, `pyi`), Java, YAML (`yaml`, `yml`), and SQL. Other text
   types stay plain.
 - **Rendered Markdown.** `.md`/`.markdown` files render as headings, lists,
-  tables, code, links, and images, with a one-click **raw** view (`?raw=1`).
-  Fenced code blocks are syntax-highlighted when the fence names a supported
-  language. Raw HTML in the source is escaped, never executed, and external
-  images are shown as links rather than fetched.
+  tables, code, inline and reference links, and images, with a one-click
+  **raw** view (`?raw=1`). Tables size their columns to the content and scroll
+  when wide, and named and numeric character references are decoded. Fenced code
+  blocks are syntax-highlighted when the fence names a supported language. Raw
+  HTML in the source is escaped, never executed, and external images are shown
+  as links rather than fetched.
 - **Sortable listings.** The Name / Size / Modified headers sort the current
   directory, directories first, and the choice is remembered per browser.
 - **Copy and wrap.** Copy a file's root-relative path or its contents, and
@@ -201,7 +205,10 @@ document and the project document (project wins):
   tag set, escapes every literal character, allowlists URL schemes (dropping
   `javascript:`/`data:`), rewrites local links and images to `/view`/`/raw`, and
   renders an external image as a link instead of loading it (the page CSP is
-  `img-src 'self' data:`). The Rendered/Raw switch is a server-side `?raw=1`
+  `img-src 'self' data:`). Link reference definitions (`[id]: url`), including
+  the full `[text][id]`, collapsed `[text][]`, and shortcut `[text]` forms, and
+  numeric and common named character references are resolved. The Rendered/Raw
+  switch is a server-side `?raw=1`
   link, so it works without JavaScript. Set `markdown: false` to fall back to
   the plain-text view. A fenced code block whose info string names a supported
   language is highlighted through `lib/highlight.ts` (either an extension or a