@dungle-scrubs/tallow 0.8.21 → 0.8.23

package/packages/tallow-tui/src/terminal.ts

@@ -0,0 +1,350 @@
+import * as fs from "node:fs";
+import { setKittyProtocolActive } from "./keys.js";
+import { StdinBuffer } from "./stdin-buffer.js";
+
+/**
+ * Minimal terminal interface for TUI
+ */
+export interface Terminal {
+	// Start the terminal with input and resize handlers
+	start(onInput: (data: string) => void, onResize: () => void): void;
+
+	// Stop the terminal and restore state
+	stop(): void;
+
+	/**
+	 * Drain stdin before exiting to prevent Kitty key release events from
+	 * leaking to the parent shell over slow SSH connections.
+	 * @param maxMs - Maximum time to drain (default: 1000ms)
+	 * @param idleMs - Exit early if no input arrives within this time (default: 50ms)
+	 */
+	drainInput(maxMs?: number, idleMs?: number): Promise<void>;
+
+	// Write output to terminal
+	write(data: string): void;
+
+	// Get terminal dimensions
+	get columns(): number;
+	get rows(): number;
+
+	// Whether Kitty keyboard protocol is active
+	get kittyProtocolActive(): boolean;
+
+	// Cursor positioning (relative to current position)
+	moveBy(lines: number): void; // Move cursor up (negative) or down (positive) by N lines
+
+	// Cursor visibility
+	hideCursor(): void; // Hide the cursor
+	showCursor(): void; // Show the cursor
+
+	// Clear operations
+	clearLine(): void; // Clear current line
+	clearFromCursor(): void; // Clear from cursor to end of screen
+	clearScreen(): void; // Clear entire screen and move cursor to (0,0)
+
+	// Screen buffer mode
+	enterAlternateScreen(): void; // Switch to alternate screen buffer (no scrollback)
+	leaveAlternateScreen(): void; // Restore normal screen buffer and scrollback
+
+	// Title operations
+	setTitle(title: string): void; // Set terminal window title
+
+	/** Set terminal progress bar via OSC 9;4. Supported by Windows Terminal, iTerm2, ConEmu. */
+	setProgress(percent: number): void;
+	/** Clear terminal progress bar via OSC 9;4. */
+	clearProgress(): void;
+}
+
+/**
+ * Real terminal using process.stdin/stdout
+ */
+export class ProcessTerminal implements Terminal {
+	private wasRaw = false;
+	private inputHandler?: (data: string) => void;
+	private resizeHandler?: () => void;
+	private _kittyProtocolActive = false;
+	private stdinBuffer?: StdinBuffer;
+	private stdinDataHandler?: (data: string) => void;
+	private writeLogPath = process.env.PI_TUI_WRITE_LOG || "";
+	private alternateScreenActive = false;
+
+	get kittyProtocolActive(): boolean {
+		return this._kittyProtocolActive;
+	}
+
+	start(onInput: (data: string) => void, onResize: () => void): void {
+		this.inputHandler = onInput;
+		this.resizeHandler = onResize;
+		this.alternateScreenActive = false;
+
+		// Save previous state and enable raw mode
+		this.wasRaw = process.stdin.isRaw || false;
+		if (process.stdin.setRawMode) {
+			process.stdin.setRawMode(true);
+		}
+		process.stdin.setEncoding("utf8");
+		process.stdin.resume();
+
+		// Enable bracketed paste mode - terminal will wrap pastes in \x1b[200~ ... \x1b[201~
+		process.stdout.write("\x1b[?2004h");
+
+		// Set up resize handler immediately
+		process.stdout.on("resize", this.resizeHandler);
+
+		// Refresh terminal dimensions - they may be stale after suspend/resume
+		// (SIGWINCH is lost while process is stopped). Unix only.
+		if (process.platform !== "win32") {
+			process.kill(process.pid, "SIGWINCH");
+		}
+
+		// Query and enable Kitty keyboard protocol
+		// The query handler intercepts input temporarily, then installs the user's handler
+		// See: https://sw.kovidgoyal.net/kitty/keyboard-protocol/
+		this.queryAndEnableKittyProtocol();
+	}
+
+	/**
+	 * Set up StdinBuffer to split batched input into individual sequences.
+	 * This ensures components receive single events, making matchesKey/isKeyRelease work correctly.
+	 *
+	 * Also watches for Kitty protocol response and enables it when detected.
+	 * This is done here (after stdinBuffer parsing) rather than on raw stdin
+	 * to handle the case where the response arrives split across multiple events.
+	 */
+	private setupStdinBuffer(): void {
+		this.stdinBuffer = new StdinBuffer({ timeout: 10 });
+
+		// Kitty protocol response pattern: \x1b[?<flags>u
+		const kittyResponsePattern = /^\x1b\[\?(\d+)u$/;
+
+		// Forward individual sequences to the input handler
+		this.stdinBuffer.on("data", (sequence) => {
+			// Check for Kitty protocol response (only if not already enabled)
+			if (!this._kittyProtocolActive) {
+				const match = sequence.match(kittyResponsePattern);
+				if (match) {
+					this._kittyProtocolActive = true;
+					setKittyProtocolActive(true);
+
+					// Enable Kitty keyboard protocol (push flags)
+					// Flag 1 = disambiguate escape codes
+					// Flag 2 = report event types (press/repeat/release)
+					// Flag 4 = report alternate keys (shifted key, base layout key)
+					// Base layout key enables shortcuts to work with non-Latin keyboard layouts
+					process.stdout.write("\x1b[>7u");
+					return; // Don't forward protocol response to TUI
+				}
+			}
+
+			if (this.inputHandler) {
+				this.inputHandler(sequence);
+			}
+		});
+
+		// Re-wrap paste content with bracketed paste markers for existing editor handling
+		this.stdinBuffer.on("paste", (content) => {
+			if (this.inputHandler) {
+				this.inputHandler(`\x1b[200~${content}\x1b[201~`);
+			}
+		});
+
+		// Handler that pipes stdin data through the buffer
+		this.stdinDataHandler = (data: string) => {
+			this.stdinBuffer?.process(data);
+		};
+	}
+
+	/**
+	 * Query terminal for Kitty keyboard protocol support and enable if available.
+	 *
+	 * Sends CSI ? u to query current flags. If terminal responds with CSI ? <flags> u,
+	 * it supports the protocol and we enable it with CSI > 1 u.
+	 *
+	 * The response is detected in setupStdinBuffer's data handler, which properly
+	 * handles the case where the response arrives split across multiple stdin events.
+	 */
+	private queryAndEnableKittyProtocol(): void {
+		this.setupStdinBuffer();
+		process.stdin.on("data", this.stdinDataHandler!);
+		process.stdout.write("\x1b[?u");
+	}
+
+	async drainInput(maxMs = 1000, idleMs = 50): Promise<void> {
+		if (this._kittyProtocolActive) {
+			// Disable Kitty keyboard protocol first so any late key releases
+			// do not generate new Kitty escape sequences.
+			process.stdout.write("\x1b[<u");
+			this._kittyProtocolActive = false;
+			setKittyProtocolActive(false);
+		}
+
+		const previousHandler = this.inputHandler;
+		this.inputHandler = undefined;
+
+		let lastDataTime = Date.now();
+		const onData = () => {
+			lastDataTime = Date.now();
+		};
+
+		process.stdin.on("data", onData);
+		const endTime = Date.now() + maxMs;
+
+		try {
+			while (true) {
+				const now = Date.now();
+				const timeLeft = endTime - now;
+				if (timeLeft <= 0) break;
+				if (now - lastDataTime >= idleMs) break;
+				await new Promise((resolve) => setTimeout(resolve, Math.min(idleMs, timeLeft)));
+			}
+		} finally {
+			process.stdin.removeListener("data", onData);
+			this.inputHandler = previousHandler;
+		}
+	}
+
+	stop(): void {
+		// Always restore normal screen buffer before exiting.
+		if (this.alternateScreenActive) {
+			this.leaveAlternateScreen();
+		}
+
+		// Disable bracketed paste mode
+		process.stdout.write("\x1b[?2004l");
+
+		// Disable Kitty keyboard protocol if not already done by drainInput()
+		if (this._kittyProtocolActive) {
+			process.stdout.write("\x1b[<u");
+			this._kittyProtocolActive = false;
+			setKittyProtocolActive(false);
+		}
+
+		// Clean up StdinBuffer
+		if (this.stdinBuffer) {
+			this.stdinBuffer.destroy();
+			this.stdinBuffer = undefined;
+		}
+
+		// Remove event handlers
+		if (this.stdinDataHandler) {
+			process.stdin.removeListener("data", this.stdinDataHandler);
+			this.stdinDataHandler = undefined;
+		}
+		this.inputHandler = undefined;
+		if (this.resizeHandler) {
+			process.stdout.removeListener("resize", this.resizeHandler);
+			this.resizeHandler = undefined;
+		}
+
+		// Pause stdin to prevent any buffered input (e.g., Ctrl+D) from being
+		// re-interpreted after raw mode is disabled. This fixes a race condition
+		// where Ctrl+D could close the parent shell over SSH.
+		process.stdin.pause();
+
+		// Restore raw mode state
+		if (process.stdin.setRawMode) {
+			process.stdin.setRawMode(this.wasRaw);
+		}
+	}
+
+	write(data: string): void {
+		process.stdout.write(data);
+		if (this.writeLogPath) {
+			try {
+				fs.appendFileSync(this.writeLogPath, data, { encoding: "utf8" });
+			} catch {
+				// Ignore logging errors
+			}
+		}
+	}
+
+	get columns(): number {
+		return process.stdout.columns || 80;
+	}
+
+	get rows(): number {
+		return process.stdout.rows || 24;
+	}
+
+	moveBy(lines: number): void {
+		if (lines > 0) {
+			// Move down
+			process.stdout.write(`\x1b[${lines}B`);
+		} else if (lines < 0) {
+			// Move up
+			process.stdout.write(`\x1b[${-lines}A`);
+		}
+		// lines === 0: no movement
+	}
+
+	hideCursor(): void {
+		process.stdout.write("\x1b[?25l");
+	}
+
+	showCursor(): void {
+		process.stdout.write("\x1b[?25h");
+	}
+
+	clearLine(): void {
+		process.stdout.write("\x1b[K");
+	}
+
+	clearFromCursor(): void {
+		process.stdout.write("\x1b[J");
+	}
+
+	clearScreen(): void {
+		process.stdout.write("\x1b[2J\x1b[H"); // Clear screen and move to home (1,1)
+	}
+
+	/**
+	 * Switch to alternate screen buffer and clear it.
+	 * @returns void
+	 */
+	enterAlternateScreen(): void {
+		if (this.alternateScreenActive) return;
+		process.stdout.write("\x1b[?1049h");
+		this.alternateScreenActive = true;
+	}
+
+	/**
+	 * Restore normal screen buffer and previous scrollback.
+	 * @returns void
+	 */
+	leaveAlternateScreen(): void {
+		if (!this.alternateScreenActive) return;
+		process.stdout.write("\x1b[?1049l");
+		this.alternateScreenActive = false;
+	}
+
+	setTitle(title: string): void {
+		// OSC 0;title BEL - set terminal window title
+		process.stdout.write(`\x1b]0;${title}\x07`);
+	}
+
+	private lastProgressWrite = 0;
+
+	/**
+	 * Set terminal progress bar via OSC 9;4.
+	 * Throttled to max 1 update per 100ms (percent=100 always passes through).
+	 * Supported by Windows Terminal (tab indicator), iTerm2 (title bar), ConEmu (taskbar).
+	 * Unsupported terminals gracefully ignore these sequences.
+	 * @param percent - Progress percentage, clamped to 0-100
+	 */
+	setProgress(percent: number): void {
+		const clamped = Math.max(0, Math.min(100, Math.round(percent)));
+		const now = Date.now();
+		if (clamped !== 100 && now - this.lastProgressWrite < 100) return;
+		this.lastProgressWrite = now;
+		process.stdout.write(`\x1b]9;4;1;${clamped}\x07`);
+	}
+
+	/**
+	 * Clear terminal progress bar via OSC 9;4.
+	 * Resets the throttle timestamp so a subsequent setProgress fires immediately.
+	 */
+	clearProgress(): void {
+		this.lastProgressWrite = 0;
+		process.stdout.write("\x1b]9;4;0;0\x07");
+	}
+}

package/packages/tallow-tui/src/test-utils/capability-env.ts

@@ -0,0 +1,56 @@
+import { resetCapabilitiesCache } from "../terminal-image.js";
+
+const CAPABILITY_ENV_KEYS = [
+	"COLORTERM",
+	"GHOSTTY_RESOURCES_DIR",
+	"ITERM_SESSION_ID",
+	"KITTY_WINDOW_ID",
+	"TERM",
+	"TERM_PROGRAM",
+	"WEZTERM_PANE",
+] as const;
+
+type CapabilityEnvOverrides = Readonly<Record<string, string | undefined>>;
+
+/**
+ * Run a callback with controlled terminal capability environment variables.
+ *
+ * Resets the terminal capability cache before and after the callback so test
+ * assertions always reflect the requested environment.
+ *
+ * @param overrides - Temporary environment variable overrides
+ * @param run - Callback executed with overrides applied
+ * @returns Callback return value
+ */
+export function withCapabilityEnv<T>(overrides: CapabilityEnvOverrides, run: () => T): T {
+	const previous: Partial<Record<(typeof CAPABILITY_ENV_KEYS)[number], string | undefined>> = {};
+
+	for (const key of CAPABILITY_ENV_KEYS) {
+		previous[key] = process.env[key];
+		if (Object.hasOwn(overrides, key)) {
+			const value = overrides[key];
+			if (value === undefined) {
+				delete process.env[key];
+			} else {
+				process.env[key] = value;
+			}
+		} else {
+			delete process.env[key];
+		}
+	}
+
+	resetCapabilitiesCache();
+	try {
+		return run();
+	} finally {
+		for (const key of CAPABILITY_ENV_KEYS) {
+			const value = previous[key];
+			if (value === undefined) {
+				delete process.env[key];
+			} else {
+				process.env[key] = value;
+			}
+		}
+		resetCapabilitiesCache();
+	}
+}