@nghyane/arcane-tui 0.1.0

package/src/terminal.ts

@@ -0,0 +1,467 @@
+import { dlopen, FFIType, ptr } from "bun:ffi";
+import * as fs from "node:fs";
+import { $env, logger } from "@nghyane/arcane-utils";
+import { setKittyProtocolActive } from "./keys";
+import { StdinBuffer } from "./stdin-buffer";
+
+export type MouseEventType = "press" | "drag" | "release" | "scroll";
+
+export interface MouseEvent {
+	type: MouseEventType;
+	button: number;
+	col: number;
+	row: number;
+}
+
+// Internal scroll sequences emitted by mouse wheel events
+export const SCROLL_UP = "\x1b[<64~";
+export const SCROLL_DOWN = "\x1b[<65~";
+
+/**
+ * Minimal terminal interface for TUI
+ */
+
+// Track active terminal for emergency cleanup on crash
+let activeTerminal: ProcessTerminal | null = null;
+// Track if a terminal was ever started (for emergency restore logic)
+let terminalEverStarted = false;
+
+const STD_INPUT_HANDLE = -10;
+const ENABLE_VIRTUAL_TERMINAL_INPUT = 0x0200;
+/**
+ * Emergency terminal restore - call this from signal/crash handlers
+ * Resets terminal state without requiring access to the ProcessTerminal instance
+ */
+export function emergencyTerminalRestore(): void {
+	try {
+		const terminal = activeTerminal;
+		if (terminal) {
+			terminal.stop();
+			terminal.showCursor();
+		} else if (terminalEverStarted) {
+			// Blind restore only if we know a terminal was started but lost track of it
+			// This avoids writing escape sequences for non-TUI commands (grep, commit, etc.)
+			process.stdout.write(
+				"\x1b[?2004l" + // Disable bracketed paste
+					"\x1b[?1006l\x1b[?1002l" + // Disable mouse tracking
+					"\x1b[<u" + // Pop kitty keyboard protocol
+					"\x1b[?1049l" + // Leave alternate screen buffer
+					"\x1b[?25h", // Show cursor
+			);
+			if (process.stdin.setRawMode) {
+				process.stdin.setRawMode(false);
+			}
+		}
+	} catch {
+		// Terminal may already be dead during crash cleanup - ignore errors
+	}
+}
+export interface Terminal {
+	// Start the terminal with input and resize handlers
+	start(onInput: (data: string) => void, onResize: () => void): void;
+
+	// Set mouse event handler
+	onMouse(handler: (event: MouseEvent) => 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)
+
+	// Title operations
+	setTitle(title: string): void; // Set terminal window title
+}
+
+/**
+ * Real terminal using process.stdin/stdout
+ */
+export class ProcessTerminal implements Terminal {
+	#wasRaw = false;
+	#inputHandler?: (data: string) => void;
+	#resizeHandler?: () => void;
+	#mouseHandler?: (event: MouseEvent) => void;
+	#kittyProtocolActive = false;
+	#stdinBuffer?: StdinBuffer;
+	#stdinDataHandler?: (data: string) => void;
+	#dead = false;
+	#writeLogPath = $env.ARCANE_TUI_WRITE_LOG || "";
+	#windowsVTInputRestore?: () => void;
+
+	get kittyProtocolActive(): boolean {
+		return this.#kittyProtocolActive;
+	}
+
+	onMouse(handler: (event: MouseEvent) => void): void {
+		this.#mouseHandler = handler;
+	}
+
+	start(onInput: (data: string) => void, onResize: () => void): void {
+		this.#inputHandler = onInput;
+		this.#resizeHandler = onResize;
+
+		// Register for emergency cleanup
+		activeTerminal = this;
+		terminalEverStarted = true;
+
+		// 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();
+
+		// Enter alternate screen buffer — keeps TUI output out of scrollback
+		this.#safeWrite("\x1b[?1049h");
+
+		// Enable mouse tracking (button-motion + SGR encoding) for scroll and selection
+		this.#safeWrite("\x1b[?1002h\x1b[?1006h");
+
+		// Enable bracketed paste mode - terminal will wrap pastes in \x1b[200~ ... \x1b[201~
+		this.#safeWrite("\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");
+		}
+
+		// On Windows, enable ENABLE_VIRTUAL_TERMINAL_INPUT so the console sends
+		// VT escape sequences (e.g. \x1b[Z for Shift+Tab) instead of raw console
+		// events that lose modifier information. Must run after setRawMode(true)
+		// since that resets console mode flags.
+		this.#enableWindowsVTInput();
+		// 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();
+	}
+
+	/**
+	 * On Windows, add ENABLE_VIRTUAL_TERMINAL_INPUT to the stdin console mode
+	 * so modified keys (for example Shift+Tab) arrive as VT escape sequences.
+	 */
+	#enableWindowsVTInput(): void {
+		if (process.platform !== "win32") return;
+		this.#restoreWindowsVTInput();
+		try {
+			const kernel32 = dlopen("kernel32.dll", {
+				GetStdHandle: { args: [FFIType.i32], returns: FFIType.ptr },
+				GetConsoleMode: { args: [FFIType.ptr, FFIType.ptr], returns: FFIType.bool },
+				SetConsoleMode: { args: [FFIType.ptr, FFIType.u32], returns: FFIType.bool },
+			});
+			const handle = kernel32.symbols.GetStdHandle(STD_INPUT_HANDLE);
+			const mode = new Uint32Array(1);
+			const modePtr = ptr(mode);
+			if (!modePtr || !kernel32.symbols.GetConsoleMode(handle, modePtr)) {
+				kernel32.close();
+				return;
+			}
+			const originalMode = mode[0]!;
+			const vtMode = originalMode | ENABLE_VIRTUAL_TERMINAL_INPUT;
+			if (vtMode !== originalMode && !kernel32.symbols.SetConsoleMode(handle, vtMode)) {
+				kernel32.close();
+				return;
+			}
+			this.#windowsVTInputRestore = () => {
+				try {
+					kernel32.symbols.SetConsoleMode(handle, originalMode);
+				} finally {
+					kernel32.close();
+				}
+			};
+		} catch {
+			// bun:ffi unavailable or console API unsupported; keep startup non-fatal.
+		}
+	}
+
+	#restoreWindowsVTInput(): void {
+		if (process.platform !== "win32") return;
+		const restore = this.#windowsVTInputRestore;
+		this.#windowsVTInputRestore = undefined;
+		if (!restore) return;
+		try {
+			restore();
+		} catch {
+			// Ignore restore errors during terminal teardown.
+		}
+	}
+
+	/**
+	 * 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.
+	 */
+	#setupStdinBuffer(): void {
+		this.#stdinBuffer = new StdinBuffer({ timeout: 10 });
+
+		// Kitty protocol response pattern: \x1b[?<flags>u
+		const kittyResponsePattern = /^\x1b\[\?(\d+)u$/;
+
+		// SGR mouse sequence pattern: \x1b[<button;col;rowM or \x1b[<button;col;rowm
+		const sgrMousePattern = /^\x1b\[<(\d+);(\d+);(\d+)([Mm])$/;
+
+		// Forward individual sequences to the input handler
+		this.#stdinBuffer.on("data", (sequence: string) => {
+			// 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
+					this.#safeWrite("\x1b[>7u");
+					return; // Don't forward protocol response to TUI
+				}
+			}
+
+			// Handle mouse events
+			const sgrMatch = sequence.match(sgrMousePattern);
+			if (sgrMatch) {
+				const rawButton = Number.parseInt(sgrMatch[1], 10);
+				const col = Number.parseInt(sgrMatch[2], 10);
+				const row = Number.parseInt(sgrMatch[3], 10);
+				const isRelease = sgrMatch[4] === "m";
+
+				// Scroll wheel: button 64 = up, 65 = down
+				if ((rawButton === 64 || rawButton === 65) && this.#inputHandler) {
+					this.#inputHandler(rawButton === 64 ? SCROLL_UP : SCROLL_DOWN);
+					return;
+				}
+
+				// Emit structured mouse event
+				if (this.#mouseHandler) {
+					const button = rawButton & 0x03; // low 2 bits = button number
+					const isDrag = (rawButton & 0x20) !== 0; // bit 5 = motion
+					const type: MouseEventType = isRelease ? "release" : isDrag ? "drag" : "press";
+					this.#mouseHandler({ type, button, col, row });
+				}
+				return; // Don't forward mouse events as keyboard input
+			}
+			// Drop legacy X10 mouse sequences
+			if (sequence.startsWith("\x1b[M") && sequence.length === 6) {
+				return;
+			}
+
+			if (this.#inputHandler) {
+				this.#inputHandler(sequence);
+			}
+		});
+
+		// Re-wrap paste content with bracketed paste markers for existing editor handling
+		this.#stdinBuffer.on("paste", (content: string) => {
+			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.
+	 */
+	#queryAndEnableKittyProtocol(): void {
+		this.#setupStdinBuffer();
+		process.stdin.on("data", this.#stdinDataHandler!);
+		this.#safeWrite("\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.
+			this.#safeWrite("\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 {
+		// Unregister from emergency cleanup
+		if (activeTerminal === this) {
+			activeTerminal = null;
+		}
+
+		// Disable bracketed paste mode
+		this.#safeWrite("\x1b[?2004l");
+
+		// Disable mouse tracking
+		this.#safeWrite("\x1b[?1006l\x1b[?1002l");
+
+		// Disable Kitty keyboard protocol if not already done by drainInput()
+		if (this.#kittyProtocolActive) {
+			this.#safeWrite("\x1b[<u");
+			this.#kittyProtocolActive = false;
+			setKittyProtocolActive(false);
+		}
+
+		this.#restoreWindowsVTInput();
+		// 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);
+		}
+
+		// Leave alternate screen buffer and show cursor (must be last — restores normal screen)
+		this.#safeWrite("\x1b[?1049l\x1b[?25h");
+	}
+
+	write(data: string): void {
+		this.#safeWrite(data);
+		if (this.#writeLogPath) {
+			try {
+				fs.appendFileSync(this.#writeLogPath, data, { encoding: "utf8" });
+			} catch {
+				// Ignore logging errors
+			}
+		}
+	}
+
+	#safeWrite(data: string): void {
+		if (this.#dead) return;
+		try {
+			process.stdout.write(data);
+		} catch (err) {
+			// Any write failure means terminal is dead - no recovery possible
+			this.#dead = true;
+			logger.warn("terminal is dead - no recovery possible", { error: err, data });
+		}
+	}
+
+	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
+			this.#safeWrite(`\x1b[${lines}B`);
+		} else if (lines < 0) {
+			// Move up
+			this.#safeWrite(`\x1b[${-lines}A`);
+		}
+		// lines === 0: no movement
+	}
+
+	hideCursor(): void {
+		this.#safeWrite("\x1b[?25l");
+	}
+
+	showCursor(): void {
+		this.#safeWrite("\x1b[?25h");
+	}
+
+	clearLine(): void {
+		this.#safeWrite("\x1b[K");
+	}
+
+	clearFromCursor(): void {
+		this.#safeWrite("\x1b[J");
+	}
+
+	clearScreen(): void {
+		this.#safeWrite("\x1b[2J\x1b[H"); // Clear screen and move to home (1,1)
+	}
+
+	setTitle(title: string): void {
+		// OSC 0;title BEL - set terminal window title
+		this.#safeWrite(`\x1b]0;${title}\x07`);
+	}
+}

package/src/ttyid.ts

@@ -0,0 +1,66 @@
+import { CString, dlopen, FFIType } from "bun:ffi";
+import * as fs from "node:fs";
+import * as os from "node:os";
+
+/** Resolve the TTY device path for stdin (fd 0) via POSIX `ttyname(3)`. */
+export function getTtyPath(): string | null {
+	if (os.platform() === "linux") {
+		// Linux: /proc/self/fd/0 is a symlink to /dev/pts/N
+		try {
+			const ttyPath = fs.readlinkSync("/proc/self/fd/0");
+			if (ttyPath.startsWith("/dev/")) {
+				return ttyPath;
+			}
+		} catch {
+			return null;
+		}
+	} else if (os.platform() !== "win32") {
+		try {
+			const libName = os.platform() === "darwin" ? "libSystem.B.dylib" : "libc.so.6";
+			const lib = dlopen(libName, {
+				ttyname: { args: [FFIType.i32], returns: FFIType.ptr },
+			});
+			try {
+				const result = lib.symbols.ttyname(0);
+				return result ? new CString(result).toString() : null;
+			} finally {
+				lib.close();
+			}
+		} catch {
+			return null;
+		}
+	}
+	return null;
+}
+/**
+ * Get a stable identifier for the current terminal.
+ * Uses the TTY device path (e.g., /dev/pts/3), falling back to environment
+ * variables for terminal multiplexers or terminal emulators.
+ * Returns null if no terminal can be identified (e.g., piped input).
+ */
+export function getTerminalId(): string | null {
+	// TTY device path — most reliable, unique per terminal tab
+	if (process.stdin.isTTY) {
+		try {
+			const ttyPath = getTtyPath();
+			if (ttyPath?.startsWith("/dev/")) {
+				return ttyPath.slice(5).replace(/\//g, "-"); // /dev/pts/3 -> pts-3
+			}
+		} catch {}
+	}
+
+	// Fallback to terminal-specific env vars
+	const kittyId = process.env.KITTY_WINDOW_ID;
+	if (kittyId) return `kitty-${kittyId}`;
+
+	const tmuxPane = process.env.TMUX_PANE;
+	if (tmuxPane) return `tmux-${tmuxPane}`;
+
+	const terminalSessionId = process.env.TERM_SESSION_ID; // macOS Terminal.app
+	if (terminalSessionId) return `apple-${terminalSessionId}`;
+
+	const wtSession = process.env.WT_SESSION; // Windows Terminal
+	if (wtSession) return `wt-${wtSession}`;
+
+	return null;
+}