@herbertgao/pi-extensions 2026.8.1 → 2026.8.3

package/node_modules/@narumitw/pi-btw/src/fullscreen-ui.ts

@@ -0,0 +1,339 @@
+import { spawn } from "node:child_process";
+import type {
+	ExtensionCommandContext,
+	KeybindingsManager,
+	Theme,
+} from "@earendil-works/pi-coding-agent";
+import {
+	type Component,
+	type OverlayHandle,
+	type TUI,
+	TuiAltScreen,
+	truncateToWidth,
+} from "@earendil-works/pi-tui";
+import { sanitizeSingleLine } from "./text.js";
+
+type BtwCustomOptions = Parameters<ExtensionCommandContext["ui"]["custom"]>[1];
+type BtwCustomFactory<T> = (
+	tui: TUI,
+	theme: Theme,
+	keybindings: KeybindingsManager,
+	done: (result: T) => void,
+) => (Component & { dispose?(): void }) | Promise<Component & { dispose?(): void }>;
+
+type BtwFullscreenTui = TUI & { flash?: (message: string, durationMs?: number) => void };
+
+export type BtwFullscreenTuiFactory = (parent: TUI) => BtwFullscreenTui;
+
+export interface BtwFullscreenDependencies {
+	createTui?: BtwFullscreenTuiFactory;
+	openUrl?: (url: string) => void;
+}
+
+export type RunBtwFullscreen = <T>(
+	ctx: ExtensionCommandContext,
+	run: (ctx: ExtensionCommandContext) => Promise<T>,
+) => Promise<T>;
+
+type FullscreenOutcome<T> = { kind: "completed"; value: T } | { kind: "failed"; error: unknown };
+
+class FullscreenUiDisposedError extends Error {
+	constructor() {
+		super("The dedicated pi-btw UI was disposed.");
+		this.name = "FullscreenUiDisposedError";
+	}
+}
+
+export async function runBtwFullscreen<T>(
+	ctx: ExtensionCommandContext,
+	run: (ctx: ExtensionCommandContext) => Promise<T>,
+	dependencies: BtwFullscreenDependencies = {},
+): Promise<T> {
+	const createTui =
+		dependencies.createTui ??
+		((parent: TUI) => createBtwFullscreenTui(parent, dependencies.openUrl ?? openUrlInBrowser));
+	let liveEditorText = ctx.ui.getEditorText();
+	let restoreEditor = false;
+	const outcome = await ctx.ui.custom<FullscreenOutcome<T>>(
+		(parent, theme, keybindings, done) =>
+			new BtwFullscreenHost(
+				parent,
+				theme,
+				keybindings,
+				ctx,
+				run,
+				(value) => {
+					try {
+						liveEditorText = ctx.ui.getEditorText();
+						restoreEditor = true;
+					} catch {
+						// A replaced session owns a different editor and must not receive stale text.
+					}
+					done(value);
+				},
+				createTui,
+			),
+	);
+	if (restoreEditor) {
+		try {
+			if (ctx.ui.getEditorText() !== liveEditorText) ctx.ui.setEditorText(liveEditorText);
+		} catch {
+			// A replaced session owns a different editor and must not receive stale restoration.
+		}
+	}
+	if (outcome.kind === "failed") throw outcome.error;
+	return outcome.value;
+}
+
+function createBtwFullscreenTui(parent: TUI, openUrl: (url: string) => void): BtwFullscreenTui {
+	return new TuiAltScreen(parent.terminal, parent.getShowHardwareCursor(), undefined, {
+		mouse: true,
+		openUrl,
+	});
+}
+
+// Pi does not export its browser opener, so mirror its shell-free launcher for this isolated TUI.
+function openUrlInBrowser(target: string): void {
+	const [command, args] =
+		process.platform === "darwin"
+			? ["open", [target]]
+			: process.platform === "win32"
+				? ["rundll32", ["url.dll,FileProtocolHandler", target]]
+				: ["xdg-open", [target]];
+	spawn(command, args, { stdio: "ignore", detached: true })
+		.on("error", () => {})
+		.unref();
+}
+
+class BtwFullscreenHost<T> implements Component {
+	private fullscreen: BtwFullscreenTui | undefined;
+	private cancelActiveCustom: (() => void) | undefined;
+	private started = false;
+	private disposed = false;
+	private finished = false;
+
+	constructor(
+		private readonly parent: TUI,
+		private readonly theme: Theme,
+		private readonly keybindings: KeybindingsManager,
+		private readonly ctx: ExtensionCommandContext,
+		private readonly run: (ctx: ExtensionCommandContext) => Promise<T>,
+		private readonly done: (outcome: FullscreenOutcome<T>) => void,
+		private readonly createTui: BtwFullscreenTuiFactory,
+	) {
+		queueMicrotask(() => void this.start());
+	}
+
+	render(width: number): string[] {
+		return [truncateToWidth(this.theme.fg("muted", "Opening btw side thread…"), width)];
+	}
+
+	invalidate(): void {}
+
+	dispose(): void {
+		if (this.disposed || this.finished) return;
+		this.disposed = true;
+		this.cancelActiveCustom?.();
+	}
+
+	private async start(): Promise<void> {
+		if (this.started || this.finished) return;
+		this.started = true;
+		let outcome: FullscreenOutcome<T>;
+		let parentStopped = false;
+		let fullscreenCreated = false;
+		try {
+			if (this.disposed) throw new FullscreenUiDisposedError();
+			this.parent.stop({ preserveScreen: true });
+			parentStopped = true;
+			if (this.disposed) throw new FullscreenUiDisposedError();
+			this.fullscreen = this.createTui(this.parent);
+			fullscreenCreated = true;
+			this.fullscreen.start();
+			outcome = { kind: "completed", value: await this.run(this.createContext()) };
+		} catch (error) {
+			outcome = { kind: "failed", error };
+		}
+
+		let cleanupError: unknown;
+		try {
+			this.cancelActiveCustom?.();
+		} catch (error) {
+			cleanupError = error;
+		}
+		if (fullscreenCreated) {
+			try {
+				this.fullscreen?.stop({ preserveScreen: true });
+			} catch (error) {
+				cleanupError ??= error;
+			}
+		}
+		if (parentStopped) {
+			try {
+				this.parent.start();
+				this.parent.renderNow(false);
+			} catch (error) {
+				cleanupError ??= error;
+			}
+		}
+		if (cleanupError !== undefined) outcome = { kind: "failed", error: cleanupError };
+		this.finished = true;
+		this.done(outcome);
+	}
+
+	private createContext(): ExtensionCommandContext {
+		const ui = new Proxy(this.ctx.ui, {
+			get: (target, property) => {
+				if (property === "custom") {
+					return <Value>(factory: BtwCustomFactory<Value>, options?: BtwCustomOptions) =>
+						this.showCustom(factory, options);
+				}
+				if (property === "notify") {
+					return (
+						message: string,
+						level?: Parameters<ExtensionCommandContext["ui"]["notify"]>[1],
+					) => {
+						target.notify(message, level);
+						const display = sanitizeSingleLine(message);
+						if (display) this.fullscreen?.flash?.(display);
+					};
+				}
+				const value = Reflect.get(target, property, target) as unknown;
+				return typeof value === "function" ? value.bind(target) : value;
+			},
+		});
+		return new Proxy(this.ctx, {
+			get: (target, property) => (property === "ui" ? ui : Reflect.get(target, property, target)),
+		});
+	}
+
+	private showCustom<Value>(
+		factory: BtwCustomFactory<Value>,
+		options?: BtwCustomOptions,
+	): Promise<Value> {
+		const fullscreen = this.fullscreen;
+		if (!fullscreen || this.disposed || this.finished) {
+			return Promise.reject(new FullscreenUiDisposedError());
+		}
+		if (this.cancelActiveCustom) {
+			return Promise.reject(new Error("pi-btw attempted to open overlapping custom UI."));
+		}
+
+		return new Promise<Value>((resolve, reject) => {
+			let component: (Component & { dispose?(): void }) | undefined;
+			let overlay: OverlayHandle | undefined;
+			let mounted = false;
+			let factorySettled = false;
+			let closed = false;
+			let promiseSettled = false;
+			let componentDisposed = false;
+			let pendingValue: Value | undefined;
+			let hasPendingValue = false;
+
+			const disposeComponent = () => {
+				if (!component || componentDisposed) return;
+				componentDisposed = true;
+				try {
+					component.dispose?.();
+				} catch {
+					// Cleanup must continue so terminal ownership is restored.
+				}
+			};
+			const unmount = () => {
+				let cleanupError: unknown;
+				try {
+					if (overlay) overlay.hide();
+					else if (mounted && component) fullscreen.removeChild(component);
+				} catch (error) {
+					cleanupError = error;
+				}
+				if (overlay || mounted) {
+					try {
+						fullscreen.setFocus(null);
+						fullscreen.requestRender();
+					} catch (error) {
+						cleanupError ??= error;
+					}
+				}
+				disposeComponent();
+				if (cleanupError !== undefined) throw cleanupError;
+			};
+			const complete = () => {
+				if (promiseSettled || !hasPendingValue) return;
+				promiseSettled = true;
+				this.cancelActiveCustom = undefined;
+				if (!factorySettled) {
+					resolve(pendingValue as Value);
+					return;
+				}
+				try {
+					unmount();
+					resolve(pendingValue as Value);
+				} catch (error) {
+					reject(error);
+				}
+			};
+			const close = (value: Value) => {
+				if (closed || promiseSettled) return;
+				closed = true;
+				pendingValue = value;
+				hasPendingValue = true;
+				complete();
+			};
+			const fail = (error: unknown) => {
+				if (promiseSettled) return;
+				closed = true;
+				promiseSettled = true;
+				this.cancelActiveCustom = undefined;
+				try {
+					unmount();
+					reject(error);
+				} catch (cleanupError) {
+					reject(cleanupError);
+				}
+			};
+			this.cancelActiveCustom = () => {
+				if (promiseSettled) return;
+				disposeComponent();
+				if (!promiseSettled) fail(new FullscreenUiDisposedError());
+			};
+
+			let created: ReturnType<BtwCustomFactory<Value>>;
+			try {
+				created = factory(fullscreen, this.theme, this.keybindings, close);
+			} catch (error) {
+				factorySettled = true;
+				fail(error);
+				return;
+			}
+			Promise.resolve(created)
+				.then((value) => {
+					component = value;
+					factorySettled = true;
+					if (promiseSettled) {
+						disposeComponent();
+						return;
+					}
+					if (closed) {
+						complete();
+						return;
+					}
+					if (options?.overlay) {
+						const overlayOptions =
+							typeof options.overlayOptions === "function"
+								? options.overlayOptions()
+								: options.overlayOptions;
+						overlay = fullscreen.showOverlay(component, overlayOptions);
+						options.onHandle?.(overlay);
+					} else {
+						fullscreen.clear();
+						fullscreen.addChild(component);
+						mounted = true;
+						fullscreen.setFocus(component);
+						fullscreen.requestRender();
+					}
+				})
+				.catch(fail);
+		});
+	}
+}

package/node_modules/@narumitw/pi-btw/src/index.ts

@@ -0,0 +1 @@
+export { default } from "./btw.js";

package/node_modules/@narumitw/pi-btw/src/menu.ts

@@ -0,0 +1,296 @@
+import type {
+	ExtensionCommandContext,
+	KeybindingsManager,
+	Theme,
+} from "@earendil-works/pi-coding-agent";
+import type { Component, TUI } from "@earendil-works/pi-tui";
+import type { MenuContext, RunMenuResult } from "@narumitw/pi-tui-kit";
+import {
+	type BtwSettings,
+	btwSettingsPath,
+	effectiveRememberThinkingLevelChanges,
+	readBtwSettings,
+	type UpdateBtwSettingsOptions,
+	updateBtwSettings,
+} from "./settings.js";
+import { BTW_THINKING_LEVELS, type BtwThinkingLevel } from "./side-thread.js";
+import { sanitizeSingleLine } from "./text.js";
+
+interface BtwMenuState {
+	kind: "valid" | "invalid";
+	settings: BtwSettings;
+	reason?: string;
+}
+
+export interface BtwResumeThreadSummary {
+	id: string;
+	title: string;
+	questionCount: number;
+}
+
+export interface ShowBtwCommandMenuOptions {
+	currentThinkingLevel: BtwThinkingLevel;
+	availableThinkingLevels: readonly BtwThinkingLevel[];
+	resumeThreads?: readonly BtwResumeThreadSummary[];
+	settingsPath?: string;
+	readSettings?: typeof readBtwSettings;
+	updateSettings?: (
+		patch: Partial<Pick<BtwSettings, "thinkingLevel" | "rememberThinkingLevelChanges">>,
+		options: UpdateBtwSettingsOptions,
+	) => Promise<BtwSettings>;
+}
+
+export type BtwCommandMenuResult = "start" | "closed" | { kind: "resume"; threadId: string };
+
+type BtwMenuScreen = "main" | "resume" | "settings" | "invalid";
+type BtwMenuAction = "start" | "resume" | "set-thinking" | "set-remember";
+type BtwCustomOptions = Parameters<ExtensionCommandContext["ui"]["custom"]>[1];
+
+type BtwCustomFactory<T> = (
+	tui: TUI,
+	theme: Theme,
+	keybindings: KeybindingsManager,
+	done: (result: T) => void,
+) => Component;
+
+export async function showBtwCommandMenu(
+	ctx: ExtensionCommandContext,
+	options: ShowBtwCommandMenuOptions,
+): Promise<BtwCommandMenuResult> {
+	if (ctx.mode !== "tui") return "closed";
+	const { defineMenu, runMenu } = await import("@narumitw/pi-tui-kit");
+	if (ctx.signal?.aborted) return "closed";
+	const settingsPath = options.settingsPath ?? btwSettingsPath();
+	const readSettings = options.readSettings ?? readBtwSettings;
+	const updateSettings = options.updateSettings ?? updateBtwSettings;
+	const levels =
+		options.availableThinkingLevels.length > 0
+			? [...options.availableThinkingLevels]
+			: (["off"] satisfies BtwThinkingLevel[]);
+	const displaySettingsPath = sanitizeSingleLine(settingsPath);
+	const resumeThreads = options.resumeThreads ?? [];
+	let startSelected = false;
+	let resumedThreadId: string | undefined;
+
+	const loadState = async (): Promise<BtwMenuState> => {
+		const loaded = await readSettings(settingsPath);
+		if (loaded.kind === "invalid") {
+			return { kind: "invalid", settings: {}, reason: loaded.reason };
+		}
+		return { kind: "valid", settings: loaded.kind === "loaded" ? loaded.settings : {} };
+	};
+	const displayThinkingLevel = (settings: BtwSettings): BtwThinkingLevel =>
+		clampToAvailableThinkingLevel(settings.thinkingLevel ?? options.currentThinkingLevel, levels);
+
+	const menu = defineMenu<BtwMenuState, BtwMenuScreen, BtwMenuAction, MenuContext>({
+		start: "main",
+		screens: {
+			main: ({ state }) => ({
+				kind: "actions",
+				title: "Pi BTW",
+				lines: [
+					`Thinking: ${displayThinkingLevel(state.settings)} · Remember changes: ${effectiveRememberThinkingLevelChanges(state.settings) ? "On" : "Off"}`,
+				],
+				items: [
+					{
+						id: "start",
+						label: "Start side thread",
+						description: "Open an empty side thread",
+						action: "start",
+					},
+					...(resumeThreads.length > 0
+						? [
+								{
+									id: "resume" as const,
+									label: "Resume side thread",
+									description: "Continue an in-memory side thread",
+									to: "resume" as const,
+								},
+							]
+						: []),
+					{
+						id: "settings",
+						label: "Settings",
+						description: "Choose pi-btw thinking and whether shortcut changes are remembered",
+						to: state.kind === "invalid" ? "invalid" : "settings",
+					},
+				],
+				hint: "close",
+			}),
+			resume: () => ({
+				kind: "choice",
+				title: "Resume BTW side thread",
+				items: resumeThreads.map((thread) => ({
+					id: thread.id,
+					label: thread.title,
+					description: `${thread.questionCount} ${thread.questionCount === 1 ? "question" : "questions"}`,
+				})),
+				action: "resume",
+				viewportSize: 10,
+				hint: "back",
+			}),
+			settings: ({ state }) => ({
+				kind: "settings",
+				title: "Pi BTW Settings",
+				lines: [`User settings · ${displaySettingsPath}`],
+				items: [
+					{
+						id: "thinkingLevel",
+						label: "Thinking level",
+						description: "Set the starting level for future pi-btw side threads.",
+						currentValue: displayThinkingLevel(state.settings),
+						values: levels,
+						action: "set-thinking",
+					},
+					{
+						id: "rememberThinkingLevelChanges",
+						label: "Remember thinking level changes",
+						description: "Save side-thread shortcut changes to pi-btw.json for next time.",
+						currentValue: effectiveRememberThinkingLevelChanges(state.settings) ? "On" : "Off",
+						values: ["On", "Off"],
+						action: "set-remember",
+					},
+				],
+			}),
+			invalid: ({ state }) => ({
+				kind: "detail",
+				title: "Pi BTW Settings · Read only",
+				lines: [
+					`Invalid settings file. Fix ${displaySettingsPath} before saving.`,
+					sanitizeSingleLine(state.reason ?? "The settings file is invalid."),
+				],
+				hint: "back",
+			}),
+		},
+		actions: {
+			start: async () => {
+				startSelected = true;
+				return { kind: "close" };
+			},
+			resume: async ({ itemId }: { itemId: string }) => {
+				if (!resumeThreads.some((thread) => thread.id === itemId)) {
+					return { kind: "rejected" } as const;
+				}
+				resumedThreadId = itemId;
+				return { kind: "close" } as const;
+			},
+			"set-thinking": async ({ value, signal }) => {
+				if (!value || !levels.includes(value as BtwThinkingLevel)) return { kind: "rejected" };
+				try {
+					await updateSettings(
+						{ thinkingLevel: value as BtwThinkingLevel },
+						{ settingsPath, signal },
+					);
+					if (signal.aborted) return { kind: "rejected" };
+					notifySafely(ctx, `Pi BTW thinking level: ${value}.`, "info");
+					return { kind: "stay" };
+				} catch (error) {
+					if (!signal.aborted) notifySaveFailure(ctx, error);
+					return { kind: "rejected" };
+				}
+			},
+			"set-remember": async ({ value, signal }) => {
+				if (value !== "On" && value !== "Off") return { kind: "rejected" };
+				try {
+					await updateSettings(
+						{ rememberThinkingLevelChanges: value === "On" },
+						{ settingsPath, signal },
+					);
+					if (signal.aborted) return { kind: "rejected" };
+					notifySafely(ctx, `Remember thinking level changes: ${value}.`, "info");
+					return { kind: "stay" };
+				} catch (error) {
+					if (!signal.aborted) notifySaveFailure(ctx, error);
+					return { kind: "rejected" };
+				}
+			},
+		},
+	});
+
+	const result = await runBtwMenuPreservingEditor(ctx, (menuContext) =>
+		runMenu(menuContext, menu, { getState: loadState }),
+	);
+	if (result.kind !== "closed" || result.reason !== "close") return "closed";
+	if (resumedThreadId) return { kind: "resume", threadId: resumedThreadId };
+	return startSelected ? "start" : "closed";
+}
+
+export async function runBtwMenuPreservingEditor(
+	ctx: ExtensionCommandContext,
+	run: (menuContext: MenuContext) => Promise<RunMenuResult>,
+): Promise<RunMenuResult> {
+	let liveEditorText = ctx.ui.getEditorText();
+	let completed = false;
+	const ui = new Proxy(ctx.ui, {
+		get(target, property) {
+			if (property === "custom") {
+				return <Value>(factory: BtwCustomFactory<Value>, customOptions?: BtwCustomOptions) =>
+					target.custom<Value>(
+						(tui, theme, keybindings, done) =>
+							factory(tui, theme, keybindings, (value) => {
+								try {
+									liveEditorText = target.getEditorText();
+								} catch {
+									// Keep completion finite if session replacement invalidates the editor context.
+								}
+								completed = true;
+								done(value);
+							}),
+						customOptions,
+					);
+			}
+			const value = Reflect.get(target, property, target) as unknown;
+			return typeof value === "function" ? value.bind(target) : value;
+		},
+	});
+	const result = await run({ mode: ctx.mode, hasUI: ctx.hasUI, ui });
+	if (result.kind !== "stale" && completed) {
+		try {
+			if (ctx.ui.getEditorText() !== liveEditorText) ctx.ui.setEditorText(liveEditorText);
+		} catch {
+			// A replaced context owns a different editor and must not receive stale restoration.
+		}
+	}
+	return result;
+}
+
+function clampToAvailableThinkingLevel(
+	requested: BtwThinkingLevel,
+	available: readonly BtwThinkingLevel[],
+): BtwThinkingLevel {
+	if (available.includes(requested)) return requested;
+	const requestedIndex = BTW_THINKING_LEVELS.indexOf(requested);
+	for (let index = requestedIndex; index < BTW_THINKING_LEVELS.length; index += 1) {
+		const candidate = BTW_THINKING_LEVELS[index];
+		if (candidate && available.includes(candidate)) return candidate;
+	}
+	for (let index = requestedIndex - 1; index >= 0; index -= 1) {
+		const candidate = BTW_THINKING_LEVELS[index];
+		if (candidate && available.includes(candidate)) return candidate;
+	}
+	return available[0] ?? "off";
+}
+
+function notifySaveFailure(ctx: ExtensionCommandContext, error: unknown): void {
+	notifySafely(
+		ctx,
+		`Pi BTW settings were not saved; the previous value remains active: ${formatError(error)}`,
+		"error",
+	);
+}
+
+function notifySafely(
+	ctx: ExtensionCommandContext,
+	message: string,
+	level: Parameters<ExtensionCommandContext["ui"]["notify"]>[1],
+): void {
+	try {
+		ctx.ui.notify(sanitizeSingleLine(message), level);
+	} catch {
+		// A completed save remains valid if its command context was replaced before notification.
+	}
+}
+
+function formatError(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}