pi-cockpit 0.1.0

package/src/settings-view.ts

@@ -0,0 +1,129 @@
+// Pure model for the /cockpit settings panel.
+//
+// The old panel was a flat list of blind letter accelerators: no cursor, no
+// focused row, no indication of what a key would cycle to, and every keystroke
+// wrote to disk while failures were swallowed. This module owns the row model and
+// the cursor/cycle logic so the behaviour is unit-testable; index.ts only paints
+// it and performs the actual save.
+
+import type { CockpitConfig, IconMode, ViewMode } from "./types.ts";
+
+export type SaveState =
+	| { kind: "idle" }
+	| { kind: "saving" }
+	| { kind: "saved" }
+	| { kind: "failed"; message: string };
+
+export interface SettingsRow {
+	key: string;
+	/** Single-letter accelerator, kept as a secondary path alongside the cursor. */
+	accel: string;
+	label: string;
+	value: string;
+	/** What pressing Enter/Space/accel switches to — shown so the cycle is visible. */
+	next: string;
+}
+
+const VIEW_MODES: ViewMode[] = ["list", "compact"];
+const ICON_MODES: IconMode[] = ["auto", "nerd", "ascii"];
+
+function cycle<T>(values: readonly T[], current: T): T {
+	const index = values.indexOf(current);
+	return values[(index + 1) % values.length];
+}
+
+// Empty means cockpit has not set a theme, so whatever /settings holds is live.
+// It is deliberately not called "default": pi's setting is the authority here,
+// and cockpit only ever nudges it.
+const NO_THEME_LABEL = "(pi settings)";
+
+function themeLabel(theme: string): string {
+	return theme === "" ? NO_THEME_LABEL : theme;
+}
+
+export function buildRows(config: CockpitConfig): SettingsRow[] {
+	return [
+		{
+			key: "enabled",
+			accel: "e",
+			label: "enabled",
+			value: config.enabled ? "on" : "off",
+			next: config.enabled ? "off" : "on",
+		},
+		{
+			key: "agentsMode",
+			accel: "a",
+			label: "agents",
+			value: config.agentsMode,
+			next: cycle(VIEW_MODES, config.agentsMode),
+		},
+		{
+			key: "todoMode",
+			accel: "t",
+			label: "todo",
+			value: config.todoMode,
+			next: cycle(VIEW_MODES, config.todoMode),
+		},
+		{
+			key: "todoExpanded",
+			accel: "x",
+			label: "todo expand",
+			value: config.todoExpanded ? "yes" : "no",
+			next: config.todoExpanded ? "no" : "yes",
+		},
+		{
+			key: "hideNativeAgents",
+			accel: "n",
+			label: "hide native",
+			value: config.hideNativeAgents ? "yes" : "no",
+			next: config.hideNativeAgents ? "no" : "yes",
+		},
+		{
+			key: "icons",
+			accel: "i",
+			label: "icons",
+			value: config.icons.mode,
+			next: cycle(ICON_MODES, config.icons.mode),
+		},
+		{
+			key: "theme",
+			accel: "h",
+			label: "theme",
+			value: themeLabel(config.theme),
+			// Not a cycle: this row opens the /theme picker, which previews live and
+			// reverts on Esc. Blind-cycling a name list could not do either.
+			//
+			// Worded as an affordance, not as a command to go type: every other row's
+			// `next` is the value Enter produces, and "open /theme" read as "leave this
+			// panel and run something else" when Enter opens it right here. The ellipsis
+			// is the usual terminal signal for "this one opens a dialog".
+			next: "picker…",
+		},
+	];
+}
+
+/** Apply the row's cycle to the config, returning a new config object. */
+export function applyRow(config: CockpitConfig, key: string): CockpitConfig {
+	switch (key) {
+		case "enabled":
+			return { ...config, enabled: !config.enabled };
+		case "agentsMode":
+			return { ...config, agentsMode: cycle(VIEW_MODES, config.agentsMode) };
+		case "todoMode":
+			return { ...config, todoMode: cycle(VIEW_MODES, config.todoMode) };
+		case "todoExpanded":
+			return { ...config, todoExpanded: !config.todoExpanded };
+		case "hideNativeAgents":
+			return { ...config, hideNativeAgents: !config.hideNativeAgents };
+		case "icons":
+			return { ...config, icons: { mode: cycle(ICON_MODES, config.icons.mode) } };
+		// "theme" is intentionally absent: the row hands off to the /theme picker,
+		// which owns both the preview and the write-through to pi's settings.
+		default:
+			return config;
+	}
+}
+
+export function rowKeyForAccel(rows: readonly SettingsRow[], accel: string): string | undefined {
+	return rows.find((row) => row.accel === accel)?.key;
+}

package/src/stack-widget.ts

@@ -0,0 +1,121 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import type { TUI } from "@earendil-works/pi-tui";
+import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import { renderAgents, renderTodos, type PaintTheme, type WidthUtils } from "./render.ts";
+import { renderBashBgSummary } from "./bash-bg-widget.ts";
+import { fitLineByPriority, type PrioritizedSegment } from "./layout.ts";
+import { resolveGlyphs, spinFrame } from "./icons.ts";
+import { panelRows } from "./viewport.ts";
+import type { AgentRow, BashBgJob, CockpitConfig, TodoItem } from "./types.ts";
+
+export interface TodoWidgetDeps {
+	getTodos: () => TodoItem[];
+	getConfig: () => CockpitConfig;
+	/** False when no redraw loop is running, so spinners must not freeze mid-cycle. */
+	isAnimating?: () => boolean;
+}
+
+export interface AgentWidgetDeps {
+	getAgents: () => AgentRow[];
+	getBashBgJobs: () => BashBgJob[];
+	getConfig: () => CockpitConfig;
+	isRunning: () => boolean;
+	isAnimating?: () => boolean;
+}
+
+const UTILS: WidthUtils = { measure: visibleWidth, clip: truncateToWidth };
+
+// The TUI exposes the live terminal size, but a widget must never fail to render
+// because a host handed it a stub without one.
+export function terminalRows(tui: TUI): number | undefined {
+	try {
+		const rows = tui.terminal?.rows;
+		return typeof rows === "number" && rows > 0 ? rows : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+// Todo widget: pinned above the editor (setWidget "cockpit-stack", aboveEditor).
+export function makeTodoWidget(deps: TodoWidgetDeps) {
+	return (tui: TUI, theme: Theme) => {
+		const paint: PaintTheme = theme;
+		return {
+			render(width: number): string[] {
+				const cfg = deps.getConfig();
+				const todos = deps.getTodos();
+				if (todos.length === 0) return [];
+				const g = resolveGlyphs(cfg.icons.mode);
+				const now = Date.now();
+				const spin = spinFrame(g, now, deps.isAnimating?.() ?? true);
+				const opts = {
+					glyphs: g,
+					spin,
+					now,
+					expanded: cfg.todoExpanded,
+					maxRows: panelRows(terminalRows(tui)),
+				};
+				return renderTodos(todos, cfg.todoExpanded ? "list" : cfg.todoMode, width, paint, UTILS, opts);
+			},
+			invalidate(): void {},
+			dispose(): void {},
+		};
+	};
+}
+
+// Agent widget: pinned below the editor, near the input box (setWidget "cockpit-agents", belowEditor).
+export function makeAgentWidget(deps: AgentWidgetDeps) {
+	return (tui: TUI, theme: Theme) => {
+		const paint: PaintTheme = theme;
+		return {
+			render(width: number): string[] {
+				const cfg = deps.getConfig();
+				const agents = deps.getAgents();
+				const bashBgJobs = deps.getBashBgJobs();
+				const g = resolveGlyphs(cfg.icons.mode);
+				const now = Date.now();
+				const animating = deps.isAnimating?.() ?? true;
+				const spin = spinFrame(g, now, animating);
+				const bashBgLines = renderBashBgSummary(bashBgJobs, width, paint, UTILS, {
+					glyphs: g,
+					spin,
+					now,
+				});
+				if (agents.length === 0) return bashBgLines;
+				const running = deps.isRunning();
+				// The panel budget covers everything this widget prints, so the header
+				// and the background strip are charged to it before the roster is.
+				const panel = panelRows(terminalRows(tui));
+				const rosterRows = panel === undefined
+					? undefined
+					: Math.max(1, panel - 1 - bashBgLines.length);
+				const opts = { glyphs: g, spin, now, maxRows: rosterRows };
+				const dot = theme.fg(running ? "success" : "muted", running ? g.dotRunning : g.dotIdle);
+				const failedCount = agents.filter((a) => a.status === "failed").length;
+				const runCount = agents.filter((a) => a.status === "running" || a.status === "retrying").length;
+				const pendingCount = agents.filter((a) => a.status === "pending").length;
+				const sleepingCount = agents.filter((a) => a.status === "sleeping").length;
+				// This header owns the roster summary, so compact mode must not print
+				// its own count line right underneath saying the same thing.
+				const headerSegs: PrioritizedSegment[] = [
+					{ text: dot, priority: 100, clippable: false },
+					{ text: theme.fg("muted", "Agents"), priority: 90, clippable: false },
+				];
+				if (failedCount) {
+					headerSegs.push({ text: theme.fg("error", `${failedCount} failed`), priority: 95, clippable: false });
+				}
+				if (runCount) headerSegs.push({ text: theme.fg("dim", `${runCount} running`), priority: 80, clippable: false });
+				if (pendingCount) headerSegs.push({ text: theme.fg("dim", `${pendingCount} pending`), priority: 60, clippable: false });
+				if (sleepingCount) headerSegs.push({ text: theme.fg("dim", `${sleepingCount} sleeping`), priority: 50, clippable: false });
+				const lines: string[] = [];
+				// Was the one line in the package pushed without any width clipping.
+				lines.push(fitLineByPriority(headerSegs, width, UTILS, theme.fg("dim", g.separator), g.ellipsis));
+				lines.push(...renderAgents(agents, cfg.agentsMode, width, paint, UTILS, { ...opts, withHead: false }));
+				lines.push(...bashBgLines);
+				return lines;
+			},
+			invalidate(): void {},
+			dispose(): void {},
+		};
+	};
+}

package/src/theme-picker.ts

@@ -0,0 +1,255 @@
+// The /theme picker.
+//
+// pi has no /theme command — themes live behind /settings → Theme. That built-in
+// submenu is good (live preview, cancel restores, automatic light/dark pairing),
+// so this exists to give the same quality one keystroke away, not to replace it.
+//
+// The whole design turns on one asymmetry in the host API:
+//
+//   setTheme("nord")        -> setThemeName    -> ALSO writes settings (persists)
+//   setTheme(themeInstance) -> setThemeInstance -> in-memory only (does NOT persist)
+//
+// So previewing by *instance* is free: the user's stored setting is untouched no
+// matter how many themes they scroll past, and cancelling restores the instance
+// that was live when the picker opened. Only Enter commits, and only Enter takes
+// the string path that writes through to pi's settings.
+
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import type { Component } from "@earendil-works/pi-tui";
+import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import { sanitizeExtensionStatusText } from "./extension-status.ts";
+import type { IconGlyphs } from "./icons.ts";
+import { fitLineByPriority, visibleStart, type PrioritizedSegment, type WidthUtils } from "./layout.ts";
+import { overlayListRows } from "./viewport.ts";
+
+const UTILS: WidthUtils = { measure: visibleWidth, clip: truncateToWidth };
+
+// Border, title, separator, two footer hints.
+const CARD_CHROME_ROWS = 6;
+
+export interface ThemePickerParams {
+	/** Theme names the host knows about, in host order. */
+	themes: readonly string[];
+	/** Name to park the cursor on — the active theme where the host reveals it. */
+	initial: string;
+	/**
+	 * A **real** Theme instance captured when the picker opened — the cancel target.
+	 *
+	 * MUST NOT be the host's exported `theme`: that is a Proxy which forwards every
+	 * property read to `globalThis[THEME_KEY]`, i.e. to whatever is current. Handing
+	 * it back to setThemeInstance stores the proxy inside the slot the proxy reads
+	 * from, and the next colour lookup recurses until the stack blows.
+	 *
+	 * `undefined` when the host would not name its active theme, in which case there
+	 * is no safe way to put it back and the picker refuses to preview at all.
+	 */
+	original: Theme | undefined;
+	loadTheme: (name: string) => Theme | undefined;
+	/** In-memory apply. Must not persist. */
+	previewTheme: (theme: Theme) => void;
+	/** Persisting apply by name. */
+	commitTheme: (name: string) => { success: boolean; error?: string };
+	close: () => void;
+	requestRender: () => void;
+	getTerminalRows: () => number | undefined;
+	theme: Theme;
+	glyphs: IconGlyphs;
+}
+
+/**
+ * Name of the theme that is actually live, or undefined if the host won't say.
+ *
+ * The Theme a component is handed is pi's exported `theme`, which is a Proxy
+ * forwarding every read to the current global theme — so reading `.name` off it
+ * is a *live* reading, and the closest thing the extension API has to a reader
+ * for the current theme. It still does not expose the stored setting, which under
+ * Automatic mode is a "light/dark" pair rather than a single name.
+ *
+ * Being a Proxy is also why the caller must resolve a real instance from this
+ * name before using it as a cancel target: handing the Proxy itself back to
+ * setThemeInstance stores it in the slot it reads from, and the next colour
+ * lookup recurses until the stack blows.
+ */
+export function activeThemeName(theme: Theme): string | undefined {
+	try {
+		const name = (theme as { name?: unknown }).name;
+		return typeof name === "string" && name !== "" ? name : undefined;
+	} catch {
+		// The Proxy throws outright when no theme has been initialised.
+		return undefined;
+	}
+}
+
+/** Cursor position for a name that may be absent from the list. */
+export function initialIndex(themes: readonly string[], initial: string): number {
+	const found = themes.indexOf(initial);
+	return found === -1 ? 0 : found;
+}
+
+export class ThemePicker implements Component {
+	private selected: number;
+	private previewed = false;
+	private error: string | undefined;
+
+	/**
+	 * Display names, stripped of control characters.
+	 *
+	 * Theme names come from theme files on disk, so they are third-party text
+	 * reaching a box-drawn card. A newline in one would break the card open, and
+	 * no width assertion would notice — a newline measures zero columns.
+	 * `params.themes` stays authoritative for the value handed back to the host.
+	 */
+	private readonly labels: readonly string[];
+
+	constructor(private readonly params: ThemePickerParams) {
+		this.labels = params.themes.map((name) => sanitizeExtensionStatusText(name));
+		this.selected = initialIndex(params.themes, params.initial);
+		// Show the highlighted theme immediately, so the picker opens already
+		// demonstrating what it does rather than waiting for a keypress.
+		this.preview();
+	}
+
+	invalidate(): void {}
+	dispose(): void {}
+
+	/** True when there is no instance to put back, so previewing would be one-way. */
+	private get previewBlocked(): boolean {
+		return this.params.original === undefined;
+	}
+
+	private preview(): void {
+		// Never preview what cannot be undone. Without a real original instance the
+		// only way back would be the persisting string form, which is the one thing
+		// scrolling a list must never do.
+		if (this.previewBlocked) return;
+		const name = this.params.themes[this.selected];
+		if (!name) return;
+		const instance = this.params.loadTheme(name);
+		if (!instance) {
+			this.error = `${this.labels[this.selected]} could not be loaded`;
+			return;
+		}
+		this.error = undefined;
+		this.previewed = true;
+		this.params.previewTheme(instance);
+	}
+
+	private cancel(): void {
+		// Restore by instance: nothing was persisted, so pi's stored setting — a
+		// single name or an automatic "light/dark" pair — is exactly as it was.
+		const { original } = this.params;
+		if (this.previewed && original) this.params.previewTheme(original);
+		this.params.close();
+	}
+
+	private commit(): void {
+		const name = this.params.themes[this.selected];
+		if (!name) {
+			this.cancel();
+			return;
+		}
+		const result = this.params.commitTheme(name);
+		if (!result.success) {
+			this.error = sanitizeExtensionStatusText(
+				result.error ?? `could not apply ${this.labels[this.selected]}`,
+			);
+			this.params.requestRender();
+			return;
+		}
+		this.params.close();
+	}
+
+	handleInput(data: string): void {
+		if (data === "\x1b") {
+			this.cancel();
+			return;
+		}
+		if (data === "\r" || data === "\n") {
+			this.commit();
+			return;
+		}
+		const count = this.params.themes.length;
+		if (count === 0) return;
+		// Arrows only. Plain letters stay inert here, per the terminal rule that
+		// reserves them until an explicit filter mode is entered; `/theme <name>`
+		// already covers the "I know what I want" path.
+		if (data === "\x1b[A") this.move(-1);
+		else if (data === "\x1b[B") this.move(1);
+		else if (data === "\x1b[5~") this.move(-this.pageSize());
+		else if (data === "\x1b[6~") this.move(this.pageSize());
+		else if (data === "\x1b[H") this.jump(0);
+		else if (data === "\x1b[F") this.jump(count - 1);
+	}
+
+	private move(delta: number): void {
+		const count = this.params.themes.length;
+		this.selected = (this.selected + delta % count + count) % count;
+		this.preview();
+		this.params.requestRender();
+	}
+
+	private jump(index: number): void {
+		this.selected = index;
+		this.preview();
+		this.params.requestRender();
+	}
+
+	private pageSize(): number {
+		return overlayListRows(this.params.getTerminalRows(), CARD_CHROME_ROWS);
+	}
+
+	render(width: number): string[] {
+		const { theme: t, glyphs: g, themes } = this.params;
+		const w = Math.max(1, Math.min(width, 60));
+		const lines = [
+			t.fg("text", "theme"),
+			t.fg("borderMuted", "─".repeat(w)),
+		];
+
+		if (themes.length === 0) {
+			lines.push(t.fg("muted", "no themes registered"));
+		} else {
+			const page = this.pageSize();
+			const start = visibleStart(this.selected, themes.length, page);
+			for (let index = start; index < Math.min(themes.length, start + page); index++) {
+				const active = index === this.selected;
+				const marker = active ? t.fg("accent", g.selectMarker) : " ";
+				const name = t.fg(active ? "text" : "muted", this.labels[index]);
+				lines.push(truncateToWidth(`${marker} ${name}`, w, "…"));
+			}
+			const hiddenAbove = start;
+			const hiddenBelow = Math.max(0, themes.length - (start + page));
+			if (hiddenAbove || hiddenBelow) {
+				lines.push(t.fg("dim", `  ${g.upDown} ${this.selected + 1}/${themes.length}`));
+			}
+		}
+
+		if (this.previewBlocked) {
+			lines.push(t.fg("warning", `${g.blocked} pi did not name its active theme — no preview`));
+		}
+		if (this.error) lines.push(t.fg("error", `${g.cross} ${this.error}`));
+
+		// Enter is the only key that touches the stored setting, so the footer says
+		// which key persists rather than leaving the user to find out. When preview
+		// is off the wording changes with it — promising a revert we cannot perform
+		// would be worse than the missing feature.
+		const hints: PrioritizedSegment[] = this.previewBlocked
+			? [
+				{ text: t.fg("dim", `${g.upDown} move`), priority: 90, clippable: false },
+				{ text: t.fg("dim", "Enter apply"), priority: 100, clippable: false },
+				{ text: t.fg("dim", "Esc close"), priority: 95, clippable: false },
+			]
+			: [
+				{ text: t.fg("dim", `${g.upDown} preview`), priority: 90, clippable: false },
+				{ text: t.fg("dim", "Enter save"), priority: 100, clippable: false },
+				{ text: t.fg("dim", "Esc revert"), priority: 95, clippable: false },
+			];
+		lines.push(fitLineByPriority(hints, w, UTILS, t.fg("dim", " · "), g.ellipsis));
+		lines.push(truncateToWidth(
+			t.fg("dim", "/settings pairs a light and a dark theme"),
+			w,
+			"…",
+		));
+		return lines.map((line) => truncateToWidth(line, width, "…"));
+	}
+}

package/src/todo-store.ts

@@ -0,0 +1,123 @@
+import { sanitizeExtensionStatusText } from "./extension-status.ts";
+import type { TodoActor, TodoItem, TodoSkill, TodoState } from "./types.ts";
+import { TODO_STATE_ENTRY_TYPE } from "./types.ts";
+
+// The todo snapshot is LLM-authored. A subject carrying a raw newline or an ANSI
+// escape measures zero columns, so it slips past every width guard and then splits
+// or repaints the terminal. Strip control characters where the data enters.
+function clean(raw: string): string {
+	return sanitizeExtensionStatusText(raw);
+}
+
+// Minimal structural view of a session entry — matches the shape todo.ts reads back
+// (type:"custom" + customType + data), without importing core session types.
+interface RawEntry {
+	readonly type?: string;
+	readonly customType?: string;
+	readonly data?: unknown;
+}
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+	return value && typeof value === "object" && !Array.isArray(value)
+		? (value as Record<string, unknown>)
+		: undefined;
+}
+
+function asStringArray(value: unknown): string[] {
+	if (!Array.isArray(value)) return [];
+	return [...new Set(value.filter((item): item is string => typeof item === "string" && item.length > 0))];
+}
+
+function asActor(value: unknown): TodoActor | undefined {
+	const actor = asRecord(value);
+	if (typeof actor?.id !== "string" || typeof actor.label !== "string") return undefined;
+	return { id: clean(actor.id), label: clean(actor.label) };
+}
+
+function asSkills(value: unknown): TodoSkill[] {
+	if (!Array.isArray(value)) return [];
+	const skills: TodoSkill[] = [];
+	for (const raw of value) {
+		const skill = asRecord(raw);
+		if (typeof skill?.name !== "string" || skill.name.length === 0) continue;
+		skills.push({
+			name: clean(skill.name),
+			...(typeof skill.role === "string" ? { role: clean(skill.role) } : {}),
+		});
+	}
+	return skills;
+}
+
+// Map the todo tool's status strings onto our four display states.
+// "deleted" is returned verbatim so the caller can drop the task.
+export function mapStatus(raw: unknown): TodoState | "deleted" {
+	switch (raw) {
+		case "in_progress":
+		case "in-progress":
+			return "in_progress";
+		case "completed":
+		case "complete":
+			return "completed";
+		case "blocked":
+			return "blocked";
+		case "deleted":
+			return "deleted";
+		case "pending":
+		default:
+			return "pending";
+	}
+}
+
+// Rebuilt from the durable todo-state snapshot the todo tool persists after every
+// mutation (tools/todo.ts:1091). We do NOT parse tool args: create-args carry no
+// assigned ids, so an incremental rebuild could never match later updates by id.
+// The snapshot is authoritative for both cold start and live refresh.
+export class TodoStore {
+	private items = new Map<string, TodoItem>();
+
+	hydrateFromEntries(entries: readonly RawEntry[]): void {
+		let entry: RawEntry | undefined;
+		for (let i = entries.length - 1; i >= 0; i--) {
+			const e = entries[i];
+			if (e && e.type === "custom" && e.customType === TODO_STATE_ENTRY_TYPE) {
+				entry = e;
+				break;
+			}
+		}
+		const rawTasks = asRecord(asRecord(entry?.data)?.tasks);
+		const next = new Map<string, TodoItem>();
+		if (rawTasks) {
+			for (const [id, raw] of Object.entries(rawTasks)) {
+				const r = asRecord(raw);
+				const status = mapStatus(r?.status);
+				if (status === "deleted") continue;
+				const item: TodoItem = {
+					id,
+					subject: typeof r?.subject === "string" ? clean(r.subject) : "",
+					status,
+					blockedBy: asStringArray(r?.blockedBy),
+					skills: asSkills(r?.skills),
+				};
+				const createdBy = asActor(r?.createdBy);
+				const assignee = asActor(r?.assignee);
+				if (createdBy) item.createdBy = createdBy;
+				if (assignee) item.assignee = assignee;
+				if (typeof r?.updatedAt === "number") item.updatedAt = r.updatedAt;
+				next.set(id, item);
+			}
+		}
+		this.items = next;
+	}
+
+	snapshot(): TodoItem[] {
+		return [...this.items.values()];
+	}
+
+	get size(): number {
+		return this.items.size;
+	}
+
+	clear(): void {
+		this.items.clear();
+	}
+}