@luan.sh/pi-libtui 0.3.8

package/src/terminal/pty-host.ts

@@ -0,0 +1,263 @@
+import { randomUUID } from "node:crypto";
+import { spawn } from "node:child_process";
+import {
+	createTerminalBridgeClient,
+	parseTerminalBridgeReadResponse,
+	type TerminalBridgeClient,
+	type TerminalBridgeReadResponse,
+} from "./bridge-client.ts";
+import { terminalBridgeBinaryPath } from "../native-binary.ts";
+import { normalizeTerminalDimensions, TerminalProjection } from "./projection.ts";
+
+const PTY_HOST_KEY = Symbol.for("pi-libtui/pty-host/v2");
+const PTY_HOST_PROTOCOL = "pi-libtui/pty-host/v2" as const;
+const PTY_READ_IDLE_TIMEOUT_MS = 30_000;
+
+export interface PtyHost {
+	readonly protocol: typeof PTY_HOST_PROTOCOL;
+	readonly version: 2;
+	spawn(request: {
+		readonly command: string;
+		readonly cwd: string;
+		readonly columns?: number;
+		readonly rows?: number;
+	}): Promise<string>;
+	render(processId: string, rows: number, cursor: boolean): readonly string[];
+	resize(processId: string, columns: number, rows: number): Promise<boolean>;
+	sendInput(processId: string, data: string): Promise<boolean>;
+	terminate(processId: string): Promise<boolean>;
+	isRunning(processId: string): boolean;
+	acceptsFocusEvents(processId: string): boolean;
+	subscribe(processId: string, listener: () => void): () => void;
+	shutdown(): Promise<void>;
+}
+
+export interface PtyHostDependencies {
+	readonly bridge: TerminalBridgeClient;
+	readonly createProcessId: () => string;
+	readonly environment: Readonly<Record<string, string>>;
+}
+
+interface HostedProcess {
+	readonly terminal: TerminalProjection;
+	readonly listeners: Set<() => void>;
+	nextSeq: number;
+	running: boolean;
+	polling?: Promise<void>;
+	termination?: Promise<boolean>;
+}
+
+/** A process may exit before its PTY reader closes and drains the final bytes. */
+function closesProcess(response: TerminalBridgeReadResponse): boolean {
+	const failed = response.failure != null;
+	return (response.closed || failed) && response.more !== true;
+}
+
+// type-boundary: Symbol.for capabilities can be populated by another installed pi-libtui copy; this validator narrows it once.
+type UntrustedPtyHost = unknown;
+
+function isPtyHost(value: UntrustedPtyHost): value is PtyHost {
+	if (!value || typeof value !== "object") return false;
+	const candidate = value as Partial<PtyHost>;
+	return (
+		candidate.protocol === PTY_HOST_PROTOCOL &&
+		candidate.version === 2 &&
+		typeof candidate.spawn === "function" &&
+		typeof candidate.render === "function" &&
+		typeof candidate.resize === "function" &&
+		typeof candidate.sendInput === "function" &&
+		typeof candidate.terminate === "function" &&
+		typeof candidate.isRunning === "function" &&
+		typeof candidate.acceptsFocusEvents === "function" &&
+		typeof candidate.subscribe === "function" &&
+		typeof candidate.shutdown === "function"
+	);
+}
+
+/** Lazily claim the process host shared by every installed pi-libtui copy. */
+export function ensurePtyHost(scope: typeof globalThis = globalThis): PtyHost {
+	const slots = scope as Record<PropertyKey, UntrustedPtyHost>;
+	const existing = slots[PTY_HOST_KEY];
+	if (isPtyHost(existing)) return existing;
+	const host = createPtyHost({
+		bridge: createTerminalBridgeClient({
+			binaryPath: terminalBridgeBinaryPath,
+			spawnBridge: (binaryPath) => spawn(binaryPath, [], { stdio: "pipe", env: process.env }),
+		}),
+		createProcessId: () => `pi-libtui-${process.pid}-${randomUUID()}`,
+		environment: stringEnvironment(process.env),
+	});
+	slots[PTY_HOST_KEY] = host;
+	return host;
+}
+
+export async function shutdownPtyHost(scope: typeof globalThis = globalThis): Promise<void> {
+	const slots = scope as Record<PropertyKey, UntrustedPtyHost>;
+	const host = slots[PTY_HOST_KEY];
+	if (!isPtyHost(host)) return;
+	Reflect.deleteProperty(slots, PTY_HOST_KEY);
+	await host.shutdown();
+}
+
+export function createPtyHost({ bridge, createProcessId, environment }: PtyHostDependencies): PtyHost {
+	const processes = new Map<string, HostedProcess>();
+	let stopped = false;
+	let shutdownPromise: Promise<void> | undefined;
+
+	const emit = (process: HostedProcess): void => {
+		for (const listener of process.listeners) listener();
+	};
+
+	const poll = async (processId: string, process: HostedProcess): Promise<void> => {
+		while (!stopped && process.running && processes.get(processId) === process) {
+			let response: TerminalBridgeReadResponse;
+			try {
+				const result = await bridge.request<unknown>({
+					op: "read",
+					process_id: processId,
+					after_seq: Math.max(0, process.nextSeq - 1),
+					max_bytes: 1_048_576,
+					// Native output and lifecycle changes wake this read. The timeout only
+					// recovers a lost wake without generating steady idle bridge traffic.
+					wait_ms: PTY_READ_IDLE_TIMEOUT_MS,
+				});
+				const parsed = parseTerminalBridgeReadResponse(result, process.nextSeq);
+				if (!parsed) throw new Error("terminal bridge emitted an invalid read result");
+				response = parsed;
+			} catch {
+				// A later bridge failure must not discard bytes accepted by an earlier read.
+				await process.terminal.drain();
+				process.running = false;
+				if (!stopped) emit(process);
+				return;
+			}
+			process.nextSeq = response.nextSeq;
+			for (const chunk of response.chunks) {
+				process.terminal.write(chunk.bytes);
+			}
+			if (process.running && closesProcess(response)) {
+				// Do not expose terminal completion until every accepted byte is visible
+				// to consumers; otherwise onExit can dispose a pane with a queued tail.
+				await process.terminal.drain();
+				process.running = false;
+				if (!stopped && processes.get(processId) === process) emit(process);
+			}
+		}
+	};
+
+	return {
+		protocol: PTY_HOST_PROTOCOL,
+		version: 2,
+		async spawn(request) {
+			if (stopped) throw new Error("PTY host is shut down");
+			const processId = createProcessId();
+			const [columns, rows] = normalizeTerminalDimensions(request.columns ?? 80, request.rows ?? 24);
+			const listeners = new Set<() => void>();
+			const hosted: HostedProcess = {
+				terminal: new TerminalProjection({
+					requestRender: () => emit(hosted),
+					cols: columns,
+					rows,
+					repaintIntervalMs: 0,
+					scrollback: 0,
+				}),
+				listeners,
+				nextSeq: 1,
+				running: true,
+			};
+			processes.set(processId, hosted);
+			try {
+				await bridge.request({
+					op: "exec",
+					process_id: processId,
+					argv: ["/bin/sh", "-c", request.command],
+					cwd: request.cwd,
+					env: { ...environment, TERM: "xterm-256color", COLORTERM: "truecolor" },
+					tty: true,
+					pipe_stdin: true,
+					arg0: null,
+					rows,
+					cols: columns,
+				});
+			} catch (error) {
+				processes.delete(processId);
+				hosted.terminal.dispose();
+				throw error;
+			}
+			hosted.polling = poll(processId, hosted);
+			return processId;
+		},
+		render(processId, rows, cursor) {
+			return processes.get(processId)?.terminal.renderLines({ maxRows: rows, cursor }) ?? [];
+		},
+		async resize(processId, columns, rows) {
+			const process = processes.get(processId);
+			if (!process?.running) return false;
+			[columns, rows] = normalizeTerminalDimensions(columns, rows);
+			if (process.terminal.cols === columns && process.terminal.rows === rows) return true;
+			await bridge.request({ op: "resize", process_id: processId, rows, cols: columns });
+			process.terminal.resize(columns, rows);
+			return true;
+		},
+		async sendInput(processId, data) {
+			const process = processes.get(processId);
+			if (!process?.running) return false;
+			const response = await bridge.request<{ status: string }>({
+				op: "write",
+				process_id: processId,
+				chunk: data,
+			});
+			return response.status === "accepted";
+		},
+		terminate(processId) {
+			const process = processes.get(processId);
+			if (!process) return Promise.resolve(false);
+			if (process.termination) return process.termination;
+			process.termination = (async () => {
+				const terminated = await bridge
+					.request({ op: "terminate", process_id: processId })
+					.then(() => true)
+					.catch(() => false);
+				// Keep the poll alive through termination so it can drain the PTY tail and
+				// observe closure before the native process entry is reaped.
+				if (terminated) await process.polling;
+				process.running = false;
+				await bridge.request({ op: "reap", process_id: processId }).catch(() => undefined);
+				if (processes.get(processId) === process) {
+					processes.delete(processId);
+					process.terminal.dispose();
+					emit(process);
+					process.listeners.clear();
+				}
+				return terminated;
+			})();
+			return process.termination;
+		},
+		isRunning: (processId) => processes.get(processId)?.running ?? false,
+		acceptsFocusEvents: (processId) => processes.get(processId)?.terminal.acceptsFocusEvents ?? false,
+		subscribe(processId, listener) {
+			const listeners = processes.get(processId)?.listeners;
+			if (!listeners) return () => {};
+			listeners.add(listener);
+			return () => listeners.delete(listener);
+		},
+		shutdown() {
+			if (shutdownPromise) return shutdownPromise;
+			stopped = true;
+			for (const process of processes.values()) {
+				process.running = false;
+				process.terminal.dispose();
+				process.listeners.clear();
+			}
+			processes.clear();
+			shutdownPromise = bridge.shutdown();
+			return shutdownPromise;
+		},
+	};
+}
+
+function stringEnvironment(environment: NodeJS.ProcessEnv): Record<string, string> {
+	return Object.fromEntries(
+		Object.entries(environment).filter((entry): entry is [string, string] => entry[1] !== undefined),
+	);
+}

package/src/terminal/pty-pane.ts

@@ -0,0 +1,308 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { type Component, type Focusable, ScrollView, type TUI } from "@earendil-works/pi-tui";
+import type { TuiMouseEvent } from "../mouse.ts";
+import { ensurePtyHost, type PtyHost } from "./pty-host.ts";
+
+export interface PtyProcessOptions {
+	readonly label: string;
+	readonly command: string;
+	readonly context: Pick<ExtensionContext, "cwd" | "ui">;
+	readonly onExit: () => void;
+	readonly scope: typeof globalThis;
+}
+
+interface PtySize {
+	readonly columns: number;
+	readonly rows: number;
+}
+
+function samePtySize(left: PtySize | undefined, right: PtySize): boolean {
+	return left?.columns === right.columns && left.rows === right.rows;
+}
+
+/** One reusable PTY lifecycle independent from its side-panel or overlay presentation. */
+export class PtyProcess {
+	private host: PtyHost | undefined;
+	private processId: string | undefined;
+	private starting: Promise<void> | undefined;
+	private unsubscribe: (() => void) | undefined;
+	private readonly renderListeners = new Set<(interactive: boolean) => void>();
+	private pendingInput = "";
+	private pendingSize: PtySize | undefined;
+	private appliedSize: PtySize | undefined;
+	private pumping = false;
+	private interactiveRenderPending = false;
+	private visible = false;
+	private reportedVisible: boolean | undefined;
+	private exitReported = false;
+	private disposed = false;
+	private onExit: (() => void) | undefined;
+	constructor(private readonly options: PtyProcessOptions) {
+		this.onExit = options.onExit;
+	}
+
+	/** Transfer exit ownership when a presentation host is reloaded. */
+	setOnExit(listener: (() => void) | undefined): void {
+		this.onExit = listener;
+		if (listener && this.exitReported) queueMicrotask(listener);
+	}
+
+	subscribeRender(listener: (interactive: boolean) => void): () => void {
+		this.renderListeners.add(listener);
+		return () => this.renderListeners.delete(listener);
+	}
+
+	private start(): void {
+		if (this.disposed || this.exitReported) return;
+		this.host ??= ensurePtyHost(this.options.scope);
+		const host = this.host;
+		if ((this.processId !== undefined && host.isRunning(this.processId)) || this.starting) return;
+		const initialSize = this.pendingSize;
+		this.starting = host
+			.spawn({
+				command: this.options.command,
+				cwd: this.options.context.cwd,
+				...(initialSize ? { columns: initialSize.columns, rows: initialSize.rows } : {}),
+			})
+			.then((processId) => {
+				if (this.disposed) return void host.terminate(processId).catch(() => undefined);
+				this.processId = processId;
+				if (initialSize) {
+					this.appliedSize = initialSize;
+					if (samePtySize(this.pendingSize, initialSize)) this.pendingSize = undefined;
+				}
+				this.unsubscribe = host.subscribe(processId, () => this.hostUpdated());
+				this.hostUpdated();
+				this.schedulePump();
+			})
+			.catch((error) => this.fail(error))
+			.finally(() => {
+				this.starting = undefined;
+			});
+	}
+
+	render(columns: number, rows: number, cursor: boolean): readonly string[] {
+		this.queueResize({ columns, rows });
+		if (this.processId === undefined) {
+			void this.start();
+			return [`Starting ${this.options.label}…`];
+		}
+		return this.host?.render(this.processId, rows, cursor) ?? [];
+	}
+
+	sendInput(data: string): void {
+		if (!data || this.disposed) return;
+		this.pendingInput += data;
+		this.schedulePump();
+	}
+
+	setVisible(visible: boolean): void {
+		if (this.visible === visible) return;
+		this.visible = visible;
+		this.syncVisibility();
+	}
+
+	dispose(): void {
+		if (this.disposed) return;
+		this.disposed = true;
+		this.pendingInput = "";
+		this.pendingSize = undefined;
+		this.unsubscribe?.();
+		this.unsubscribe = undefined;
+		const processId = this.processId;
+		this.processId = undefined;
+		if (processId !== undefined) void this.host?.terminate(processId).catch(() => undefined);
+	}
+
+	private hostUpdated(): void {
+		this.syncVisibility();
+		const interactive = this.interactiveRenderPending;
+		this.interactiveRenderPending = false;
+		this.notifyRender(interactive);
+		const host = this.host;
+		if (!host) return;
+		if (!this.disposed && this.processId !== undefined && !host.isRunning(this.processId)) this.reportExit();
+	}
+
+	private notifyRender(interactive = false): void {
+		for (const listener of this.renderListeners) listener(interactive);
+	}
+
+	private syncVisibility(): void {
+		if (this.reportedVisible === this.visible || this.processId === undefined || this.disposed) return;
+		const host = this.host;
+		if (!host) return;
+		if (!host.acceptsFocusEvents(this.processId)) return;
+		this.reportedVisible = this.visible;
+		this.sendInput(this.visible ? "\x1b[I" : "\x1b[O");
+	}
+
+	private queueResize(size: PtySize): void {
+		if (samePtySize(this.pendingSize ?? this.appliedSize, size)) return;
+		this.pendingSize = size;
+		this.schedulePump();
+	}
+
+	private schedulePump(): void {
+		if (this.pumping || (!this.pendingSize && !this.pendingInput) || this.processId === undefined || this.disposed)
+			return;
+		this.pumping = true;
+		queueMicrotask(() => void this.pump());
+	}
+
+	private async pump(): Promise<void> {
+		try {
+			while ((this.pendingSize || this.pendingInput) && !this.disposed) {
+				const host = this.host;
+				if (this.processId === undefined) return;
+				if (!host) return;
+				const size = this.pendingSize;
+				this.pendingSize = undefined;
+				if (size && (await host.resize(this.processId, size.columns, size.rows))) this.appliedSize = size;
+				const data = this.pendingInput;
+				this.pendingInput = "";
+				if (data) {
+					// Mark latency-sensitive output only once the bytes are actually crossing
+					// the bridge; unrelated animation output must not consume this priority.
+					this.interactiveRenderPending = true;
+					await host.sendInput(this.processId, data);
+				}
+			}
+		} catch (error) {
+			this.notify(error);
+		} finally {
+			this.pumping = false;
+			this.schedulePump();
+		}
+	}
+
+	private fail(error: unknown): void {
+		if (this.disposed) return;
+		this.notify(error);
+		this.reportExit();
+	}
+
+	private reportExit(): void {
+		if (this.exitReported) return;
+		this.exitReported = true;
+		this.onExit?.();
+	}
+
+	private notify(error: unknown): void {
+		this.options.context.ui.notify(error instanceof Error ? error.message : String(error), "error");
+	}
+}
+
+export interface PtyPaneOptions {
+	readonly tui: TUI;
+	readonly rows: () => number;
+	readonly requestRender: () => void;
+}
+
+class ProjectedPtyScreen implements Component {
+	constructor(
+		private readonly process: PtyProcess,
+		private readonly cursor: () => boolean,
+		private readonly rows: () => number,
+	) {}
+
+	render(width: number): string[] {
+		const rows = Math.max(1, this.rows());
+		const projected = this.process.render(width, rows, this.cursor());
+		if (projected.length >= rows) return projected.slice(-rows);
+		return [...Array.from({ length: rows - projected.length }, () => ""), ...projected];
+	}
+
+	invalidate(): void {}
+}
+
+/** Complete cursor, keyboard, pointer, and terminal projection for one PTY process. */
+export class PtyPane extends ScrollView implements Focusable {
+	private _focused = false;
+	private previousHardwareCursor: boolean | undefined;
+	private readonly unsubscribe: () => void;
+	private readonly focusState: { value: boolean };
+
+	constructor(
+		private readonly process: PtyProcess,
+		private readonly options: PtyPaneOptions,
+	) {
+		const focusState = { value: false };
+		const screen = new ProjectedPtyScreen(process, () => focusState.value, options.rows);
+		super(screen, {
+			follow: "end",
+			overscroll: "contain",
+			scrollbar: "hidden",
+		});
+		this.focusState = focusState;
+		this.unsubscribe = process.subscribeRender((interactive) => {
+			if (interactive && requestImmediateRender(options.tui)) return;
+			options.requestRender();
+		});
+		process.setVisible(true);
+	}
+
+	get focused(): boolean {
+		return this._focused;
+	}
+
+	set focused(value: boolean) {
+		this._focused = value;
+		this.focusState.value = value;
+		if (value) {
+			this.previousHardwareCursor ??= this.options.tui.getShowHardwareCursor();
+			this.options.tui.setShowHardwareCursor(true);
+			return;
+		}
+		if (this.previousHardwareCursor === undefined) return;
+		this.options.tui.setShowHardwareCursor(this.previousHardwareCursor);
+		this.previousHardwareCursor = undefined;
+	}
+
+	handleInput(data: string): void {
+		this.process.sendInput(data);
+	}
+
+	defersInputRender(): boolean {
+		return true;
+	}
+
+	onMouse(event: TuiMouseEvent): boolean {
+		const input = encodePointer(event);
+		if (!input) return false;
+		this.process.sendInput(input);
+		return true;
+	}
+
+	dispose(): void {
+		this.focused = false;
+		this.unsubscribe();
+		this.process.setVisible(false);
+	}
+}
+
+// type-boundary: Pi's TUI currently keeps its latency-sensitive render path private;
+// the PTY surface uses it only for the first child frame caused by keyboard input.
+type InteractiveTui = TUI & { requestImmediateRender?: () => void };
+
+function requestImmediateRender(tui: TUI): boolean {
+	const render = (tui as InteractiveTui).requestImmediateRender;
+	if (typeof render !== "function") return false;
+	render.call(tui);
+	return true;
+}
+
+function encodePointer(event: TuiMouseEvent): string | undefined {
+	const modifiers = Number(event.shift) * 4 + Number(event.alt) * 8 + Number(event.ctrl) * 16;
+	if (event.type === "wheel" && event.wheel !== undefined) {
+		const button = event.wheel > 0 ? 65 : 64;
+		return `\x1b[<${button + modifiers};${event.col + 1};${event.row + 1}M`.repeat(Math.abs(event.wheel));
+	}
+	if (event.type === "press" && event.button !== undefined)
+		return `\x1b[<${event.button + modifiers};${event.col + 1};${event.row + 1}M`;
+	if (event.type === "drag" && event.button !== undefined)
+		return `\x1b[<${32 + event.button + modifiers};${event.col + 1};${event.row + 1}M`;
+	if (event.type === "release") return `\x1b[<${(event.button ?? 0) + modifiers};${event.col + 1};${event.row + 1}m`;
+	if (event.type === "move") return `\x1b[<${35 + modifiers};${event.col + 1};${event.row + 1}M`;
+	return undefined;
+}