@gavin-hu/my-pi-agent 0.14.0 → 0.15.1

package/extensions/bytefly/panel/settings-runtime.ts

@@ -18,7 +18,7 @@ import {
 	readJson,
 	SHARED_CONFIG_FILE,
 	unsetConfigValueAt,
-	writeConfigValueAt,
+	writeConfigValuesAt,
 } from "../../../lib/config.ts";
 import type { SettingsStore, WriteScope } from "../picker/types.ts";
 import {
@@ -31,6 +31,7 @@ import {
 	settingViews,
 	storedValue,
 	textError,
+	UNTRUSTED_SETTINGS_NOTE,
 } from "./settings.ts";
 
 /** Host seams for the Settings runtime. */
@@ -42,6 +43,8 @@ export interface SettingsRuntimeDeps {
 	trusted: boolean;
 	/** Report a refused or failed write to the screen. */
 	onError?: (message: string) => void;
+	/** Theme names for the Theme row, already narrowed to this package's palettes; empty outside the TUI. */
+	themes?: readonly string[];
 }
 
 /** What the panel needs from the runtime. */
@@ -74,6 +77,7 @@ function readSnapshot(deps: SettingsRuntimeDeps): SettingsSnapshot {
 		app: deps.stores.global.globalSettings(),
 		global: readJson(configPath("global", deps.cwd, deps.agentDir)) ?? {},
 		project: deps.trusted ? (readJson(configPath("project", deps.cwd, deps.agentDir)) ?? {}) : {},
+		themes: deps.themes ?? [],
 	};
 }
 
@@ -90,6 +94,9 @@ function applyAppSetting(store: SettingsStore, row: SettingDescriptor, raw: stri
 		case "showHardwareCursor":
 			store.setShowHardwareCursor(value as boolean);
 			return;
+		case "theme":
+			store.setTheme(value as string);
+			return;
 		default:
 			throw new Error(`Unknown app setting ${row.id}`);
 	}
@@ -98,7 +105,7 @@ function applyAppSetting(store: SettingsStore, row: SettingDescriptor, raw: stri
 /** Why `row` cannot be written in `scope`, or `undefined` when it can. */
 function refusal(row: SettingDescriptor, scope: WriteScope, trusted: boolean): string | undefined {
 	if (scope === "project" && !trusted) {
-		return "Project is not trusted; settings can only be changed in Global scope.";
+		return UNTRUSTED_SETTINGS_NOTE;
 	}
 	if (row.source === "app" && scope !== "global") return `${row.label} is a Global setting.`;
 	return undefined;
@@ -130,8 +137,12 @@ export function createSettingsRuntime(deps: SettingsRuntimeDeps): SettingsRuntim
 		const config = row.config;
 		if (!config) throw new Error(`Setting ${row.id} has no config section`);
 		const path = configPath(scope, deps.cwd, deps.agentDir);
-		writeConfigValueAt(path, config.section, config.path, storedValue(row, raw));
-		for (const leaf of row.also?.(raw) ?? []) writeConfigValueAt(path, leaf.section, leaf.path, leaf.value);
+		// One document pass for the row and every companion leaf it declares, so a
+		// failure cannot leave the row written and its companion not.
+		writeConfigValuesAt(path, [
+			{ section: config.section, path: config.path, value: storedValue(row, raw) },
+			...(row.also?.(raw) ?? []),
+		]);
 	};
 
 	/** Take a completed write: re-read the snapshot, mark it dirty, repaint. */
@@ -159,7 +170,9 @@ export function createSettingsRuntime(deps: SettingsRuntimeDeps): SettingsRuntim
 			}
 			const current = settingViews(snapshot, scope).find((entry) => entry.id === id);
 			if (!current) return;
-			const next = nextValue(row, current.value);
+			// Use the view's options: the Theme row's list comes from the host, not
+			// from the static descriptor.
+			const next = nextValue(current, current.value);
 			try {
 				await write(scope, row, next.value);
 			} catch (error) {
@@ -212,7 +225,14 @@ export function createSettingsRuntime(deps: SettingsRuntimeDeps): SettingsRuntim
 			if (!config) return false;
 			const document = scope === "global" ? snapshot.global : snapshot.project;
 			if (configValueAt(configSection(document, config.section), config.path) === undefined) {
-				deps.onError?.(`${row.label} is already at its default.`);
+				const inherited =
+					scope === "project" &&
+					configValueAt(configSection(snapshot.global, config.section), config.path) !== undefined;
+				deps.onError?.(
+					inherited
+						? `${row.label} is inherited from Global; there is nothing to reset in Project.`
+						: `${row.label} is already at its default.`,
+				);
 				return false;
 			}
 			try {

package/extensions/bytefly/panel/settings.ts

@@ -135,6 +135,8 @@ export interface SettingsSnapshot {
 	app: Settings;
 	global: Record<string, unknown>;
 	project: Record<string, unknown>;
+	/** Theme names the Theme row offers, narrowed to this package's palettes by the caller. */
+	themes: readonly string[];
 }
 
 /** One rendered group: its heading and the rows under it. */
@@ -436,6 +438,18 @@ export const SETTING_ROWS: readonly SettingDescriptor[] = [
 			{ value: "1", label: "1" },
 		],
 	},
+	{
+		id: "theme",
+		group: "terminal",
+		label: "Theme",
+		description:
+			"Pi's color theme, chosen from the palettes this package ships; `system` follows the terminal's colors. Takes effect after reload.",
+		source: "app",
+		kind: "enum",
+		fallback: "system",
+		// The host supplies this package's theme names in the snapshot; the static list stays empty.
+		options: [],
+	},
 	{
 		id: "showHardwareCursor",
 		group: "terminal",
@@ -519,7 +533,7 @@ export const SETTING_ROWS: readonly SettingDescriptor[] = [
 		id: "rewind.max",
 		group: "snapshots",
 		label: "Snapshots kept",
-		description: "Snapshots kept per repository before the oldest are pruned; 0 keeps none.",
+		description: "Snapshot refs kept per repository, including pre-restore safety snapshots; 0 keeps none.",
 		source: "bytefly",
 		kind: "text",
 		fallback: "20",
@@ -590,6 +604,9 @@ export const SETTING_ROWS: readonly SettingDescriptor[] = [
 	},
 ];
 
+/** The one refusal for a Project write while the project is untrusted. */
+export const UNTRUSTED_SETTINGS_NOTE = "Project is not trusted; settings can only be changed in Global scope.";
+
 /** The rows a scope can write: app rows are personal-file only. */
 export function rowsForScope(scope: WriteScope): readonly SettingDescriptor[] {
 	return scope === "global" ? SETTING_ROWS : SETTING_ROWS.filter((row) => row.source === "bytefly");
@@ -612,9 +629,18 @@ export function textError(row: SettingDescriptor, raw: string): string | undefin
 	return rule.validate?.(raw);
 }
 
+/** The Theme row's values: `system` first, then the names the caller offers. */
+function themeOptions(themes: readonly string[]): readonly SettingOption[] {
+	const names = ["system", ...new Set(themes.filter((name) => name !== "" && name !== "system"))];
+	return names.map((name) => ({ value: name, label: name }));
+}
+
 /** The display label for `raw`, or the raw value when it is a valid custom one. */
 function labelFor(row: SettingDescriptor, raw: string): string {
-	return row.options.find((option) => option.value === raw)?.label ?? raw;
+	const option = row.options.find((entry) => entry.value === raw);
+	if (option) return option.label;
+	// A stored light/dark pair is Pi's automatic mode, not a missing theme.
+	return row.id === "theme" && raw.includes("/") ? `${raw} (automatic)` : raw;
 }
 
 /** Read an app preference and where it came from. */
@@ -634,6 +660,11 @@ function appValue(snapshot: SettingsSnapshot, row: SettingDescriptor): { value:
 				value: snapshot.app.showHardwareCursor === true ? "true" : row.fallback,
 				origin: snapshot.app.showHardwareCursor === undefined ? "default" : "global",
 			};
+		case "theme": {
+			const theme = snapshot.app.theme;
+			const set = typeof theme === "string" && theme !== "";
+			return { value: set ? theme : row.fallback, origin: set ? "global" : "default" };
+		}
 		default:
 			throw new Error(`Unknown app setting ${row.id}`);
 	}
@@ -646,7 +677,11 @@ function statesConfig(config: SettingConfig, document: Record<string, unknown>):
 
 /** Where the effective value came from: the project file, the personal one, or nothing. */
 function originFor(config: SettingConfig, snapshot: SettingsSnapshot, scope: WriteScope): SettingOrigin {
-	if (scope === "project") return statesConfig(config, snapshot.project) ? "project" : "inherited";
+	if (scope === "project") {
+		if (statesConfig(config, snapshot.project)) return "project";
+		if (statesConfig(config, snapshot.global)) return "inherited";
+		return "default";
+	}
 	return statesConfig(config, snapshot.global) ? "global" : "default";
 }
 
@@ -711,8 +746,10 @@ function byteflyValue(
 /** Build the rows for `scope` from a snapshot. */
 export function settingViews(snapshot: SettingsSnapshot, scope: WriteScope): SettingView[] {
 	return rowsForScope(scope).map((row) => {
+		const options = row.id === "theme" ? themeOptions(snapshot.themes) : row.options;
 		const { value, origin } = row.source === "app" ? appValue(snapshot, row) : byteflyValue(snapshot, row, scope);
-		return { ...row, value, valueLabel: labelFor(row, value), origin };
+		const view = { ...row, options, value };
+		return { ...view, valueLabel: labelFor(view, value), origin };
 	});
 }
 

package/extensions/bytefly/panel/themes.ts

@@ -0,0 +1,32 @@
+/**
+ * Which themes the Settings **Theme** row offers: this package's own two, not
+ * every theme in play.
+ *
+ * The host resolves Pi's built-ins, this package's palettes, and any user or
+ * project theme into one list, but the row writes Pi's single `theme`
+ * preference from a bytefly screen, so it offers only the palettes this package
+ * ships and can vouch for. The file's directory identifies a shipped theme, not
+ * its name: `themes/` is the manifest's own resource glob, so a renamed palette
+ * or a look-alike name cannot drift the list away from what the package loads.
+ */
+
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/** This package's `themes/` directory. */
+export const SHIPPED_THEMES_DIR = resolve(fileURLToPath(new URL("../../../themes", import.meta.url)));
+
+/** One theme as the host reports it. */
+export interface HostTheme {
+	name: string;
+	path?: string;
+}
+
+/** The shipped theme names in the host's order; a pathless or foreign theme is dropped. */
+export function shippedThemeNames(themes: readonly HostTheme[]): string[] {
+	return themes.filter(isShipped).map((theme) => theme.name);
+}
+
+function isShipped(theme: HostTheme): boolean {
+	return theme.path !== undefined && dirname(resolve(theme.path)) === SHIPPED_THEMES_DIR;
+}

package/extensions/bytefly/panel/tui/editing.ts

@@ -0,0 +1,77 @@
+/**
+ * The panel's text-editing state machine.
+ *
+ * One key in, the next editing state out; the component owns the settings write,
+ * the write chain, and the repaint. Esc cancels the edit instead of closing the
+ * screen, Enter asks the caller to commit, and everything else the screen binds
+ * is inert until the editor closes.
+ */
+
+import { Key, matchesKey } from "@earendil-works/pi-tui";
+import { isCloseKey } from "../../../../lib/tui/cursor.ts";
+
+/** Bracketed-paste markers a terminal wraps around pasted text. */
+const PASTE_START = "\x1b[200~";
+const PASTE_END = "\x1b[201~";
+
+/** The text row being edited: its id, the buffer, and the caret offset. */
+export interface EditingState {
+	id: string;
+	buffer: string;
+	caret: number;
+}
+
+/** What one editing key asked for. */
+export type EditAction =
+	| { kind: "cancel" }
+	| { kind: "commit" }
+	| { kind: "update"; state: EditingState; changed: boolean };
+
+/**
+ * Apply one key to the editing state.
+ *
+ * `maxLength` comes from the setting's text rule; an undefined limit means the
+ * row has no text rule, so typed characters are refused rather than stored
+ * unvalidated. A key that changes nothing (Backspace at the start, a refused
+ * character) reports `changed: false`, so the caller does not ask for a frame.
+ */
+export function applyEditKey(data: string, state: EditingState, maxLength: number | undefined): EditAction {
+	if (isCloseKey(data)) return { kind: "cancel" };
+	if (matchesKey(data, Key.enter)) return { kind: "commit" };
+
+	const { buffer, caret } = state;
+	let next = state;
+	if (matchesKey(data, Key.backspace)) {
+		if (caret > 0) next = { ...state, buffer: buffer.slice(0, caret - 1) + buffer.slice(caret), caret: caret - 1 };
+	} else if (matchesKey(data, Key.delete)) {
+		if (caret < buffer.length) next = { ...state, buffer: buffer.slice(0, caret) + buffer.slice(caret + 1) };
+	} else if (matchesKey(data, Key.left)) {
+		next = { ...state, caret: Math.max(0, caret - 1) };
+	} else if (matchesKey(data, Key.right)) {
+		next = { ...state, caret: Math.min(buffer.length, caret + 1) };
+		// `Ctrl+A`/`Ctrl+E` are the emacs spellings of Home/End, which pi-tui's
+		// `Key.home`/`Key.end` do not match; both are offered because a terminal
+		// may send either.
+	} else if (matchesKey(data, Key.home) || matchesKey(data, "ctrl+a")) {
+		next = { ...state, caret: 0 };
+	} else if (matchesKey(data, Key.end) || matchesKey(data, "ctrl+e")) {
+		next = { ...state, caret: buffer.length };
+	} else if (matchesKey(data, "ctrl+u")) {
+		next = { ...state, buffer: "", caret: 0 };
+	} else {
+		// A pasted chunk arrives wrapped in bracketed-paste markers. Its ESC is
+		// dropped by the filter below, which would leave `[200~` in the value, so
+		// strip the markers first, the way Pi's own Input and Editor do.
+		const text = data.replaceAll(PASTE_START, "").replaceAll(PASTE_END, "");
+		// Anything else must be printable; control sequences are not text.
+		const typed = [...text].filter((char) => char >= " " && char !== "\u007f").join("");
+		if (typed && maxLength !== undefined && buffer.length + typed.length <= maxLength) {
+			next = {
+				...state,
+				buffer: buffer.slice(0, caret) + typed + buffer.slice(caret),
+				caret: caret + typed.length,
+			};
+		}
+	}
+	return { kind: "update", state: next, changed: next.buffer !== buffer || next.caret !== caret };
+}

package/extensions/bytefly/panel/tui/entries.ts

@@ -27,6 +27,30 @@ export function isSelectable(entry: PanelEntry | undefined): boolean {
 	return entryKey(entry) !== undefined;
 }
 
+/**
+ * One display window as ordinals over the selectable rows it contains.
+ *
+ * The range row counts rows, not entries: a list of twenty-nine settings in ten
+ * groups spans thirty-nine entries, but `showing 3–5 of 29` is what the user can
+ * focus. `formatRange` prints `start + 1` through `end`, so the ordinals here are
+ * zero-based and `end` is exclusive.
+ */
+export function selectableRange(
+	entries: readonly PanelEntry[],
+	window: { start: number; end: number },
+): { start: number; end: number; total: number } {
+	let before = 0;
+	let shown = 0;
+	let total = 0;
+	for (let index = 0; index < entries.length; index += 1) {
+		if (!isSelectable(entries[index])) continue;
+		total += 1;
+		if (index < window.start) before += 1;
+		else if (index < window.end) shown += 1;
+	}
+	return { start: before, end: before + shown, total };
+}
+
 /** The next selectable entry from `from` in `direction`, or `undefined`. */
 export function nextRow(entries: PanelEntry[], from: number, direction: -1 | 1): number | undefined {
 	for (let index = from + direction; index >= 0 && index < entries.length; index += direction) {

package/extensions/bytefly/panel/tui/extensions-view.ts

@@ -7,6 +7,7 @@
  */
 
 import type { Theme } from "@earendil-works/pi-coding-agent";
+import type { ScreenHint } from "../../../../lib/tui/chrome.ts";
 import { sanitizeLine } from "../../../../lib/format.ts";
 import { clip } from "../../../../lib/tui/columns.ts";
 import { checkbox, listRow } from "../../../../lib/tui/rows.ts";
@@ -46,7 +47,7 @@ export function extensionRow(theme: Theme, width: number, row: PanelRow, selecte
 	});
 }
 
-/** The focused extension's label, findings, and the pending-changes note. */
+/** The focused extension's findings and the pending-changes note. */
 export function extensionDetail(
 	theme: Theme,
 	width: number,
@@ -57,10 +58,10 @@ export function extensionDetail(
 ): string[] {
 	const lines: string[] = [];
 	const badge = row ? rowBadge(row) : undefined;
-	if (row && badge?.text !== undefined) {
-		const head = `${paint(theme, "meta", sanitizeLine(row.label))} ${paint(theme, "faint", "—")} ${paint(theme, badge.role, badge.text)}`;
-		lines.push(clip(`  ${head}`, width));
-	} else if (row?.item) {
+	// The focused row directly above already carries the entry's name and verdict,
+	// so the pane starts with what the row cannot say: the findings, or the
+	// resource path when nothing was reported.
+	if (badge?.text === undefined && row?.item) {
 		lines.push(clip(`  ${paint(theme, "meta", sanitizeLine(row.item.path))}`, width));
 	}
 	if (row?.report && budget > 0) {
@@ -71,12 +72,16 @@ export function extensionDetail(
 }
 
 /** The section's key hints, in the order they drop as the width runs out. */
-export function extensionHints(options: { expanded: boolean; refreshing: boolean; projectScope: boolean }): string[] {
+export function extensionHints(options: {
+	expanded: boolean;
+	refreshing: boolean;
+	projectScope: boolean;
+}): ScreenHint[] {
 	return [
 		"Esc close",
 		"←/→",
-		"Space toggle",
-		options.expanded ? "Enter collapse" : "Enter detail",
+		{ text: "Space toggle", color: "accent" },
+		{ text: options.expanded ? "Enter collapse" : "Enter detail", color: "accent" },
 		"Tab scope",
 		// Only Project scope can hold an override, so the key is not offered elsewhere.
 		...(options.projectScope ? ["x inherit"] : []),

package/extensions/bytefly/panel/tui/frame.ts

@@ -1,6 +1,7 @@
 /**
  * The chrome around the panel's body: the layout constants, the section bar with
- * its counts, a group heading, and the hint row that a transient notice replaces.
+ * its counts, a group heading, the hint row that a transient notice replaces, and
+ * the frame the two sections share.
  *
  * Every section draws its body through these, so the two views cannot drift on
  * spacing, roles, or the width arithmetic.
@@ -8,12 +9,20 @@
 
 import type { Theme } from "@earendil-works/pi-coding-agent";
 import { sanitizeLine } from "../../../../lib/format.ts";
-import { screenHint } from "../../../../lib/tui/chrome.ts";
+import {
+	detailBlockRows,
+	dockListFrame,
+	screenHint,
+	type ScreenHint,
+	type ViewportRowsSource,
+} from "../../../../lib/tui/chrome.ts";
 import { clip, fitCells, splitRow } from "../../../../lib/tui/columns.ts";
+import { fitRows, formatRange, type ListCursor } from "../../../../lib/tui/cursor.ts";
 import { BODY_INDENT } from "../../../../lib/tui/indent.ts";
 import { paint } from "../../../../lib/tui/tokens.ts";
 import { sectionSegments, type SummarySegment } from "../format.ts";
 import type { PanelSection } from "../types.ts";
+import { selectableRange, type PanelEntry } from "./entries.ts";
 
 /** Body rows when the terminal height is unknown. */
 export const SCREEN_DEFAULT_ROWS = 16;
@@ -54,8 +63,8 @@ export function groupLine(theme: Theme, width: number, entry: { label: string; c
 	return clip(`  ${label} ${count}`, width);
 }
 
-/** The key-hint row. */
-export function hintLine(theme: Theme, width: number, hints: string[]): string {
+/** The key-hint row, or a section's notice that replaces it. */
+export function hintLine(theme: Theme, width: number, hints: ScreenHint[]): string {
 	return screenHint(theme, width, hints);
 }
 
@@ -69,3 +78,111 @@ export function savedLine(theme: Theme, width: number, dirty: boolean): string[]
 	if (!dirty) return [];
 	return [clip(`${INDENT}${paint(theme, "warn", "Saved · reload to apply")}`, width)];
 }
+
+/** Terminal rows, or `undefined` when the height is unknown. */
+export function totalRows(source: ViewportRowsSource | undefined): number | undefined {
+	const rows = typeof source === "function" ? source() : source;
+	return rows !== undefined && Number.isFinite(rows) && rows > 0 ? rows : undefined;
+}
+
+/**
+ * Detail rows the focused row gets: the fixed pane, or the free height when
+ * expanded. Zero when there is no free row for a pane at all, so a short
+ * terminal keeps its body; the caller then drops optional rows if needed.
+ */
+export function detailRows(expanded: boolean, viewportRows: ViewportRowsSource | undefined): number {
+	const total = totalRows(viewportRows);
+	if (total === undefined) return expanded ? EXPANDED_DETAIL_FALLBACK : DETAIL_ROWS;
+	// One row pays for the blank line the frame puts above the pane.
+	const available = total - FRAME_ROWS - MIN_BODY_ROWS - 1;
+	if (available < 1) return 0;
+	return expanded ? available : Math.min(DETAIL_ROWS, available);
+}
+
+/**
+ * Drop optional rows until the frame fits the viewport: the range row first,
+ * then the project note, then the blank above the detail pane, then the pane.
+ * The header, summary, one body row, and the hint always survive; a terminal
+ * shorter than those is left to the host.
+ */
+export function fitOptionalLines(options: {
+	viewportRows: ViewportRowsSource | undefined;
+	body: string[];
+	note: string | undefined;
+	range: string | undefined;
+	detail: string[];
+}): { body: string[]; range: string | undefined; detail: string[]; noteShown: boolean; detailBlank: boolean } {
+	const total = totalRows(options.viewportRows);
+	let { body, range, detail } = options;
+	let noteShown = options.note !== undefined && body[0] === options.note;
+	if (total === undefined) return { body, range, detail, noteShown, detailBlank: true };
+	const fits = (blank: boolean): boolean =>
+		FRAME_ROWS + body.length + (range === undefined ? 0 : 1) + detailBlockRows(detail, blank) <= total;
+	if (!fits(true)) range = undefined;
+	if (!fits(true) && noteShown) {
+		body = body.slice(1);
+		noteShown = false;
+	}
+	// The separator goes before the pane does: the focused row's findings are
+	// worth more than the blank above them.
+	const detailBlank = fits(true) || !fits(false);
+	if (!fits(false)) detail = [];
+	return { body, range, detail, noteShown, detailBlank };
+}
+
+/** What {@link panelFrame} draws: the window, the body, and the chrome around it. */
+export interface PanelFrameInput {
+	theme: Theme;
+	viewportRows: ViewportRowsSource | undefined;
+	cursor: ListCursor;
+	width: number;
+	header: string;
+	summary: string;
+	entries: readonly PanelEntry[];
+	note?: string;
+	detail: string[];
+	hint: string;
+	draw: (entry: PanelEntry, index: number) => string | undefined;
+}
+
+/**
+ * The frame both sections share: the cursor window, the visible body rows, the
+ * range row, the optional rows that give way on a short terminal, and the
+ * chrome around them. Each section supplies its summary, its detail pane, its
+ * hint row, and how one entry is drawn.
+ */
+export function panelFrame(input: PanelFrameInput): { lines: string[]; noteShown: boolean } {
+	const { theme, viewportRows, cursor, width, entries, note, detail, hint, draw } = input;
+	cursor.visible = fitRows(
+		viewportRows,
+		entries.length,
+		FRAME_ROWS + detailBlockRows(detail) + (note ? 1 : 0),
+		SCREEN_DEFAULT_ROWS,
+	);
+	cursor.sync(entries.length);
+	const { start, end } = cursor.window(entries.length);
+
+	const body: string[] = [];
+	if (note) body.push(note);
+	for (let index = start; index < end; index += 1) {
+		const line = draw(entries[index], index);
+		if (line !== undefined) body.push(line);
+	}
+
+	const range = cursor.clipped(entries.length)
+		? formatRange(theme, width, selectableRange(entries, { start, end }))
+		: undefined;
+	const fitted = fitOptionalLines({ viewportRows, body, note, range, detail });
+	return {
+		lines: dockListFrame({
+			header: input.header,
+			summary: input.summary,
+			body: fitted.body,
+			range: fitted.range,
+			detail: fitted.detail.length > 0 ? fitted.detail : undefined,
+			detailBlank: fitted.detailBlank,
+			hint,
+		}),
+		noteShown: fitted.noteShown,
+	};
+}