@pablozaiden/terminatui 0.1.0

package/src/tui/context/KeyboardContext.tsx

@@ -0,0 +1,118 @@
+import {
+    createContext,
+    useContext,
+    useCallback,
+    useRef,
+    type ReactNode,
+} from "react";
+import { useKeyboard } from "@opentui/react";
+import type { KeyEvent } from "@opentui/core";
+
+/**
+ * Priority levels for keyboard event handlers.
+ * Higher priority handlers are called first.
+ */
+export enum KeyboardPriority {
+    /** Modal/overlay handlers - highest priority, intercept first */
+    Modal = 100,
+    /** Focused section handlers - handle section-specific keys */
+    Focused = 50,
+    /** Global handlers - app-wide shortcuts, lowest priority */
+    Global = 0,
+}
+
+/**
+ * Extended keyboard event with custom stop propagation.
+ * Use `stopPropagation()` to prevent lower-priority handlers from receiving the event.
+ * Use `key.preventDefault()` only when you want to also block OpenTUI primitives.
+ */
+export interface KeyboardEvent {
+    /** The underlying OpenTUI KeyEvent */
+    key: KeyEvent;
+    /** Stop propagation to lower-priority handlers in our system */
+    stopPropagation: () => void;
+    /** Whether propagation was stopped */
+    stopped: boolean;
+}
+
+export type KeyboardHandler = (event: KeyboardEvent) => void;
+
+interface RegisteredHandler {
+    id: string;
+    handler: KeyboardHandler;
+    priority: KeyboardPriority;
+}
+
+interface KeyboardContextValue {
+    register: (id: string, handler: KeyboardHandler, priority: KeyboardPriority) => void;
+    unregister: (id: string) => void;
+}
+
+const KeyboardContext = createContext<KeyboardContextValue | null>(null);
+
+interface KeyboardProviderProps {
+    children: ReactNode;
+}
+
+/**
+ * Provider that coordinates all keyboard handlers via a single useKeyboard call.
+ * Handlers are invoked in descending priority order (highest first).
+ * Propagation stops when a handler calls `stopPropagation()`.
+ */
+export function KeyboardProvider({ children }: KeyboardProviderProps) {
+    const handlersRef = useRef<RegisteredHandler[]>([]);
+
+    const register = useCallback(
+        (id: string, handler: KeyboardHandler, priority: KeyboardPriority) => {
+            // Remove existing handler with same id (if any)
+            handlersRef.current = handlersRef.current.filter((h) => h.id !== id);
+            // Add new handler
+            handlersRef.current.push({ id, handler, priority });
+            // Sort by priority descending (highest first)
+            handlersRef.current.sort((a, b) => b.priority - a.priority);
+        },
+        []
+    );
+
+    const unregister = useCallback((id: string) => {
+        handlersRef.current = handlersRef.current.filter((h) => h.id !== id);
+    }, []);
+
+    // Single useKeyboard call that dispatches to all registered handlers
+    useKeyboard((key: KeyEvent) => {
+        // Create our wrapper event with custom stop propagation
+        const event: KeyboardEvent = {
+            key,
+            stopped: false,
+            stopPropagation() {
+                this.stopped = true;
+            },
+        };
+
+        for (const { handler } of handlersRef.current) {
+            // Stop if our propagation was stopped or if preventDefault was called
+            if (event.stopped || key.defaultPrevented) {
+                break;
+            }
+            handler(event);
+        }
+    });
+
+    return (
+        <KeyboardContext.Provider value={{ register, unregister }}>
+            {children}
+        </KeyboardContext.Provider>
+    );
+}
+
+/**
+ * Access the keyboard context for handler registration.
+ * @throws Error if used outside of KeyboardProvider
+ */
+export function useKeyboardContext(): KeyboardContextValue {
+    const context = useContext(KeyboardContext);
+    if (!context) {
+        throw new Error("useKeyboardContext must be used within a KeyboardProvider");
+    }
+    return context;
+}

package/src/tui/context/index.ts

@@ -0,0 +1,7 @@
+export {
+    KeyboardProvider,
+    useKeyboardContext,
+    KeyboardPriority,
+    type KeyboardEvent,
+    type KeyboardHandler,
+} from "./KeyboardContext.tsx";

package/src/tui/hooks/index.ts

@@ -0,0 +1,35 @@
+export {
+    useKeyboardHandler,
+    KeyboardPriority,
+    type KeyboardEvent,
+} from "./useKeyboardHandler.ts";
+
+export {
+    useClipboard,
+    type UseClipboardResult,
+} from "./useClipboard.ts";
+
+export {
+    useSpinner,
+    type UseSpinnerResult,
+} from "./useSpinner.ts";
+
+export {
+    useConfigState,
+    type UseConfigStateOptions,
+    type UseConfigStateResult,
+} from "./useConfigState.ts";
+
+export {
+    useCommandExecutor,
+    type UseCommandExecutorResult,
+} from "./useCommandExecutor.ts";
+
+export {
+    useLogStream,
+    LogLevel,
+    type LogEntry,
+    type LogEvent,
+    type LogSource,
+    type UseLogStreamResult,
+} from "./useLogStream.ts";

package/src/tui/hooks/useClipboard.ts

@@ -0,0 +1,66 @@
+import { useCallback, useState } from "react";
+import * as fs from "fs";
+
+/**
+ * Copy text to clipboard using OSC 52 escape sequence.
+ * Write directly to /dev/tty to bypass any stdout interception.
+ */
+function copyWithOsc52(text: string): boolean {
+    try {
+        // Strip ANSI codes if Bun is available, otherwise use as-is
+        const cleanText = typeof Bun !== "undefined" 
+            ? Bun.stripANSI(text) 
+            : text.replace(/\x1B\[[0-9;]*[a-zA-Z]/g, "");
+        const base64 = Buffer.from(cleanText).toString("base64");
+        // OSC 52 sequence: ESC ] 52 ; c ; <base64> BEL
+        const osc52 = `\x1b]52;c;${base64}\x07`;
+        
+        // Try to write directly to the TTY to bypass OpenTUI's stdout capture
+        try {
+            const fd = fs.openSync('/dev/tty', 'w');
+            fs.writeSync(fd, osc52);
+            fs.closeSync(fd);
+        } catch {
+            // Fallback to stdout if /dev/tty is not available
+            process.stdout.write(osc52);
+        }
+        
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+export interface UseClipboardResult {
+    /** Copy text to clipboard */
+    copy: (text: string) => boolean;
+    /** Last action message for status display */
+    lastAction: string;
+    /** Set the last action message */
+    setLastAction: (action: string) => void;
+    /** Copy and set a success message */
+    copyWithMessage: (text: string, label: string) => void;
+}
+
+/**
+ * Hook for clipboard operations using OSC 52.
+ * Works in most modern terminal emulators.
+ */
+export function useClipboard(): UseClipboardResult {
+    const [lastAction, setLastAction] = useState("");
+    
+    const copy = useCallback((text: string): boolean => {
+        return copyWithOsc52(text);
+    }, []);
+
+    const copyWithMessage = useCallback((text: string, label: string) => {
+        const success = copyWithOsc52(text);
+        if (success) {
+            setLastAction(`✓ ${label} copied to clipboard`);
+            // Clear message after 2 seconds
+            setTimeout(() => setLastAction(""), 2000);
+        }
+    }, []);
+
+    return { copy, lastAction, setLastAction, copyWithMessage };
+}

package/src/tui/hooks/useCommandExecutor.ts

@@ -0,0 +1,131 @@
+import { useState, useCallback, useRef } from "react";
+import type { CommandResult } from "../../core/command.ts";
+import { AbortError } from "../../core/command.ts";
+
+/**
+ * Outcome of command execution.
+ */
+export interface ExecutionOutcome<TResult = CommandResult> {
+    success: boolean;
+    result?: TResult;
+    error?: Error;
+    /** Whether the command was cancelled */
+    cancelled?: boolean;
+}
+
+export interface UseCommandExecutorResult<TResult = CommandResult> {
+    /** Whether the command is currently executing */
+    isExecuting: boolean;
+    /** The result from the last execution */
+    result: TResult | null;
+    /** Error from the last execution, if any */
+    error: Error | null;
+    /** Whether the last execution was cancelled */
+    wasCancelled: boolean;
+    /** Execute the command - returns outcome when complete */
+    execute: (...args: unknown[]) => Promise<ExecutionOutcome<TResult>>;
+    /** Cancel the currently running command */
+    cancel: () => void;
+    /** Reset the state */
+    reset: () => void;
+}
+
+/**
+ * Hook for executing commands with loading/error/result state and cancellation support.
+ * 
+ * @param executeFn - The async function to execute. Receives an AbortSignal as the last argument.
+ * @returns Executor state and functions
+ * 
+ * @example
+ * ```tsx
+ * const { isExecuting, result, error, execute, cancel } = useCommandExecutor(
+ *     async (config, signal) => {
+ *         return await runCommand(config, signal);
+ *     }
+ * );
+ * 
+ * const outcome = await execute(config);
+ * if (outcome.cancelled) { ... }
+ * if (outcome.success) { ... }
+ * ```
+ */
+export function useCommandExecutor<TResult = CommandResult>(
+    executeFn: (...args: unknown[]) => Promise<TResult | void>
+): UseCommandExecutorResult<TResult> {
+    const [isExecuting, setIsExecuting] = useState(false);
+    const [result, setResult] = useState<TResult | null>(null);
+    const [error, setError] = useState<Error | null>(null);
+    const [wasCancelled, setWasCancelled] = useState(false);
+    
+    // Keep track of the current AbortController
+    const abortControllerRef = useRef<AbortController | null>(null);
+
+    const execute = useCallback(async (...args: unknown[]): Promise<ExecutionOutcome<TResult>> => {
+        // Cancel any previous execution
+        if (abortControllerRef.current) {
+            abortControllerRef.current.abort();
+        }
+        
+        // Create a new AbortController for this execution
+        const abortController = new AbortController();
+        abortControllerRef.current = abortController;
+        
+        setIsExecuting(true);
+        setError(null);
+        setResult(null);
+        setWasCancelled(false);
+
+        try {
+            // Pass the signal as the last argument
+            const res = await executeFn(...args, abortController.signal);
+            
+            // Check if we were aborted
+            if (abortController.signal.aborted) {
+                setWasCancelled(true);
+                return { success: false, cancelled: true };
+            }
+            
+            if (res !== undefined) {
+                setResult(res);
+                return { success: true, result: res };
+            }
+            return { success: true };
+        } catch (e) {
+            // Check if this was a cancellation
+            if (abortController.signal.aborted || e instanceof AbortError || (e instanceof Error && e.name === "AbortError")) {
+                setWasCancelled(true);
+                return { success: false, cancelled: true };
+            }
+            
+            const err = e instanceof Error ? e : new Error(String(e));
+            setError(err);
+            return { success: false, error: err };
+        } finally {
+            setIsExecuting(false);
+            if (abortControllerRef.current === abortController) {
+                abortControllerRef.current = null;
+            }
+        }
+    }, [executeFn]);
+
+    const cancel = useCallback(() => {
+        if (abortControllerRef.current) {
+            abortControllerRef.current.abort();
+            abortControllerRef.current = null;
+        }
+    }, []);
+
+    const reset = useCallback(() => {
+        // Cancel any running execution
+        if (abortControllerRef.current) {
+            abortControllerRef.current.abort();
+            abortControllerRef.current = null;
+        }
+        setIsExecuting(false);
+        setResult(null);
+        setError(null);
+        setWasCancelled(false);
+    }, []);
+
+    return { isExecuting, result, error, wasCancelled, execute, cancel, reset };
+}

package/src/tui/hooks/useConfigState.ts

@@ -0,0 +1,171 @@
+import { useState, useCallback, useRef } from "react";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import type { OptionSchema, OptionValues } from "../../types/command.ts";
+
+export interface UseConfigStateOptions<T extends OptionSchema> {
+    /** Path to persist config (e.g., ~/.myapp/config.json) */
+    persistPath?: string;
+    /** Whether to auto-save on changes */
+    autoSave?: boolean;
+    /** Callback when a value changes */
+    onChange?: (key: keyof OptionValues<T>, value: unknown, values: OptionValues<T>) => void;
+}
+
+export interface UseConfigStateResult<T extends OptionSchema> {
+    /** Current config values */
+    values: OptionValues<T>;
+    /** Update a single value */
+    updateValue: <K extends keyof OptionValues<T>>(key: K, value: OptionValues<T>[K]) => void;
+    /** Reset all values to defaults */
+    resetToDefaults: () => void;
+    /** Save current values to disk (if persistPath is set) */
+    save: () => void;
+    /** Whether the config has been modified from defaults */
+    isDirty: boolean;
+}
+
+/**
+ * Extract default values from an option schema.
+ */
+function getDefaultsFromSchema<T extends OptionSchema>(schema: T): OptionValues<T> {
+    const defaults: Record<string, unknown> = {};
+    
+    for (const [key, def] of Object.entries(schema)) {
+        if (def.default !== undefined) {
+            defaults[key] = def.default;
+        } else {
+            // Provide type-appropriate defaults
+            switch (def.type) {
+                case "string":
+                    defaults[key] = def.enum?.[0] ?? "";
+                    break;
+                case "number":
+                    defaults[key] = def.min ?? 0;
+                    break;
+                case "boolean":
+                    defaults[key] = false;
+                    break;
+                case "array":
+                    defaults[key] = [];
+                    break;
+            }
+        }
+    }
+    
+    return defaults as OptionValues<T>;
+}
+
+/**
+ * Load config from disk.
+ */
+function loadFromDisk<T extends OptionSchema>(
+    path: string,
+    schema: T
+): OptionValues<T> | null {
+    try {
+        if (existsSync(path)) {
+            const content = readFileSync(path, "utf-8");
+            const saved = JSON.parse(content) as Partial<OptionValues<T>>;
+            const defaults = getDefaultsFromSchema(schema);
+            return { ...defaults, ...saved };
+        }
+    } catch {
+        // Ignore errors, return null to use defaults
+    }
+    return null;
+}
+
+/**
+ * Save config to disk.
+ */
+function saveToDisk<T extends OptionSchema>(
+    path: string,
+    values: OptionValues<T>
+): boolean {
+    try {
+        const dir = dirname(path);
+        if (!existsSync(dir)) {
+            mkdirSync(dir, { recursive: true });
+        }
+        writeFileSync(path, JSON.stringify(values, null, 2), "utf-8");
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * Hook for managing config state with optional persistence.
+ * 
+ * @param schema - Option schema defining the config structure
+ * @param options - Configuration options
+ * @returns Config state and update functions
+ * 
+ * @example
+ * ```tsx
+ * const { values, updateValue } = useConfigState(myOptions, {
+ *     persistPath: join(homedir(), ".myapp/config.json"),
+ *     autoSave: true,
+ * });
+ * ```
+ */
+export function useConfigState<T extends OptionSchema>(
+    schema: T,
+    options: UseConfigStateOptions<T> = {}
+): UseConfigStateResult<T> {
+    const { persistPath, autoSave = true, onChange } = options;
+    const schemaRef = useRef(schema);
+    
+    // Initialize state
+    const [values, setValues] = useState<OptionValues<T>>(() => {
+        if (persistPath) {
+            const loaded = loadFromDisk(persistPath, schema);
+            if (loaded) return loaded;
+        }
+        return getDefaultsFromSchema(schema);
+    });
+    
+    const [isDirty, setIsDirty] = useState(false);
+
+    // Update a single value
+    const updateValue = useCallback(<K extends keyof OptionValues<T>>(
+        key: K,
+        value: OptionValues<T>[K]
+    ) => {
+        setValues((prev) => {
+            const updated = { ...prev, [key]: value };
+            
+            // Call onChange callback
+            onChange?.(key, value, updated);
+            
+            // Auto-save if enabled
+            if (autoSave && persistPath) {
+                saveToDisk(persistPath, updated);
+            }
+            
+            return updated;
+        });
+        setIsDirty(true);
+    }, [autoSave, persistPath, onChange]);
+
+    // Reset to defaults
+    const resetToDefaults = useCallback(() => {
+        const defaults = getDefaultsFromSchema(schemaRef.current);
+        setValues(defaults);
+        setIsDirty(false);
+        
+        if (autoSave && persistPath) {
+            saveToDisk(persistPath, defaults);
+        }
+    }, [autoSave, persistPath]);
+
+    // Manual save
+    const save = useCallback(() => {
+        if (persistPath) {
+            saveToDisk(persistPath, values);
+        }
+    }, [persistPath, values]);
+
+    return { values, updateValue, resetToDefaults, save, isDirty };
+}

package/src/tui/hooks/useKeyboardHandler.ts

@@ -0,0 +1,91 @@
+import { useEffect, useId, useRef } from "react";
+import {
+    useKeyboardContext,
+    KeyboardPriority,
+    type KeyboardHandler,
+    type KeyboardEvent,
+} from "../context/KeyboardContext.tsx";
+
+interface UseKeyboardHandlerOptions {
+    /**
+     * Whether the handler is currently enabled.
+     * When false, the handler is unregistered.
+     * Useful for conditionally handling keys only when focused.
+     * @default true
+     */
+    enabled?: boolean;
+
+    /**
+     * When true, automatically calls stopPropagation() after the handler runs,
+     * blocking keys from reaching lower-priority handlers.
+     * Does NOT block OpenTUI primitives (input/select) from receiving keys.
+     * Use this for modal dialogs that should capture keyboard focus.
+     * @default false
+     */
+    modal?: boolean;
+}
+
+/**
+ * Register a keyboard handler with the KeyboardProvider.
+ *
+ * @param handler - Callback invoked on keyboard events.
+ *   - Call `event.stopPropagation()` to stop our handlers from receiving the event.
+ *   - Call `event.key.preventDefault()` to also block OpenTUI primitives.
+ * @param priority - Handler priority level. Higher priorities are called first.
+ * @param options - Optional configuration (e.g., enabled flag, modal behavior).
+ *
+ * @example
+ * ```tsx
+ * // Modal handler - blocks lower-priority handlers but lets OpenTUI primitives work
+ * useKeyboardHandler(
+ *     (event) => {
+ *         if (event.key.name === "escape") {
+ *             onClose();
+ *         }
+ *         // Other keys pass through to <input>/<select> but not to ConfigForm
+ *     },
+ *     KeyboardPriority.Modal,
+ *     { enabled: isVisible, modal: true }
+ * );
+ * ```
+ */
+export function useKeyboardHandler(
+    handler: KeyboardHandler,
+    priority: KeyboardPriority,
+    options: UseKeyboardHandlerOptions = {}
+): void {
+    const { enabled = true, modal = false } = options;
+    const { register, unregister } = useKeyboardContext();
+    const id = useId();
+    
+    // Keep handler ref stable to avoid re-registrations on every render
+    const handlerRef = useRef(handler);
+    handlerRef.current = handler;
+
+    // Keep modal ref stable
+    const modalRef = useRef(modal);
+    modalRef.current = modal;
+
+    useEffect(() => {
+        if (!enabled) {
+            unregister(id);
+            return;
+        }
+
+        // Register with a stable wrapper that calls the current handler
+        register(id, (event: KeyboardEvent) => {
+            handlerRef.current(event);
+            // For modals, always stop propagation to our handlers (but not OpenTUI primitives)
+            if (modalRef.current) {
+                event.stopPropagation();
+            }
+        }, priority);
+
+        return () => {
+            unregister(id);
+        };
+    }, [id, priority, enabled, register, unregister]);
+}
+
+export { KeyboardPriority };
+export type { KeyboardEvent };