@pablozaiden/terminatui 0.1.0

package/src/tui/hooks/useLogStream.ts

@@ -0,0 +1,96 @@
+import { useState, useEffect, useCallback } from "react";
+
+/**
+ * Log levels for display styling.
+ */
+export enum LogLevel {
+    Silly = "silly",
+    Trace = "trace",
+    Debug = "debug",
+    Info = "info",
+    Warn = "warn",
+    Error = "error",
+    Fatal = "fatal",
+}
+
+/**
+ * Log entry for display.
+ */
+export interface LogEntry {
+    timestamp: Date;
+    level: LogLevel;
+    message: string;
+}
+
+/**
+ * Log event emitted by the log source.
+ */
+export interface LogEvent {
+    level: LogLevel;
+    message: string;
+}
+
+/**
+ * Log source that can be subscribed to.
+ */
+export interface LogSource {
+    /** Subscribe to log events, returns unsubscribe function */
+    subscribe: (callback: (event: LogEvent) => void) => () => void;
+}
+
+export interface UseLogStreamResult {
+    /** All collected log entries */
+    logs: LogEntry[];
+    /** Clear all logs */
+    clearLogs: () => void;
+    /** Add a log entry manually */
+    addLog: (level: LogLevel, message: string) => void;
+}
+
+/**
+ * Hook for subscribing to a log stream.
+ * 
+ * @param source - Optional log source to subscribe to
+ * @returns Log stream state and functions
+ * 
+ * @example
+ * ```tsx
+ * const { logs, clearLogs } = useLogStream(myLogSource);
+ * ```
+ */
+export function useLogStream(source?: LogSource): UseLogStreamResult {
+    const [logs, setLogs] = useState<LogEntry[]>([]);
+
+    // Subscribe to log source
+    useEffect(() => {
+        if (!source) return;
+
+        const unsubscribe = source.subscribe((event: LogEvent) => {
+            setLogs((prev) => {
+                const newEntry: LogEntry = {
+                    timestamp: new Date(),
+                    level: event.level,
+                    message: event.message,
+                };
+                return [...prev, newEntry];
+            });
+        });
+
+        return () => {
+            unsubscribe?.();
+        };
+    }, [source]);
+
+    const clearLogs = useCallback(() => {
+        setLogs([]);
+    }, []);
+
+    const addLog = useCallback((level: LogLevel, message: string) => {
+        setLogs((prev) => [
+            ...prev,
+            { timestamp: new Date(), level, message },
+        ]);
+    }, []);
+
+    return { logs, clearLogs, addLog };
+}

package/src/tui/hooks/useSpinner.ts

@@ -0,0 +1,46 @@
+import { useState, useEffect, useMemo } from "react";
+
+const SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+const SPINNER_INTERVAL = 80;
+
+export interface UseSpinnerResult {
+    /** Current frame index */
+    frameIndex: number;
+    /** Current spinner character */
+    frame: string;
+}
+
+/**
+ * Hook for animated spinner.
+ * 
+ * @param active - Whether the spinner is active
+ * @returns Spinner state with current frame
+ */
+export function useSpinner(active: boolean): UseSpinnerResult {
+    const [frameIndex, setFrameIndex] = useState(0);
+
+    useEffect(() => {
+        if (!active) {
+            setFrameIndex(0);
+            return;
+        }
+
+        const interval = setInterval(() => {
+            setFrameIndex((prev) => {
+                // Reset to avoid overflow
+                if (prev >= Number.MAX_SAFE_INTEGER / 2) {
+                    return 0;
+                }
+                return prev + 1;
+            });
+        }, SPINNER_INTERVAL);
+
+        return () => clearInterval(interval);
+    }, [active]);
+
+    const frame = useMemo(() => {
+        return SPINNER_FRAMES[frameIndex % SPINNER_FRAMES.length]!;
+    }, [frameIndex]);
+
+    return { frameIndex, frame };
+}

package/src/tui/index.ts

@@ -0,0 +1,65 @@
+// Main TUI components
+export { TuiApp } from "./TuiApp.tsx";
+export { TuiApplication, type TuiApplicationConfig, type CustomField } from "./TuiApplication.tsx";
+
+// Theme
+export { Theme, type ThemeColors } from "./theme.ts";
+
+// Context
+export {
+    KeyboardProvider,
+    useKeyboardContext,
+    KeyboardPriority,
+    type KeyboardEvent,
+    type KeyboardHandler,
+} from "./context/index.ts";
+
+// Hooks
+export {
+    useKeyboardHandler,
+    useClipboard,
+    useSpinner,
+    useConfigState,
+    useCommandExecutor,
+    useLogStream,
+    LogLevel,
+    type UseClipboardResult,
+    type UseSpinnerResult,
+    type UseConfigStateOptions,
+    type UseConfigStateResult,
+    type UseCommandExecutorResult,
+    type LogEntry,
+    type LogEvent,
+    type LogSource,
+    type UseLogStreamResult,
+} from "./hooks/index.ts";
+
+// Components
+export {
+    FieldRow,
+    ActionButton,
+    Header,
+    StatusBar,
+    LogsPanel,
+    ResultsPanel,
+    ConfigForm,
+    EditorModal,
+    CliModal,
+    CommandSelector,
+    JsonHighlight,
+    type FieldType,
+    type FieldOption,
+    type FieldConfig,
+    type JsonHighlightProps,
+} from "./components/index.ts";
+
+// Utilities
+export {
+    schemaToFieldConfigs,
+    groupFieldConfigs,
+    getFieldDisplayValue,
+    buildCliCommand,
+} from "./utils/index.ts";
+
+// Legacy export for backward compatibility
+export * from "./app.ts";

package/src/tui/theme.ts

@@ -0,0 +1,21 @@
+/**
+ * Default TUI theme colors.
+ */
+export const Theme = {
+    background: "#0b0c10",
+    border: "#2c2f36",
+    borderFocused: "#5da9e9",
+    borderSelected: "#61afef",
+    label: "#c0cad6",
+    value: "#98c379",
+    actionButton: "#a0e8af",
+    header: "#a8b3c1",
+    statusText: "#d6dde6",
+    overlay: "#0e1117",
+    overlayTitle: "#e5c07b",
+    error: "#f78888",
+    success: "#98c379",
+    warning: "#f5c542",
+} as const;
+
+export type ThemeColors = typeof Theme;

package/src/tui/utils/buildCliCommand.ts

@@ -0,0 +1,90 @@
+import type { OptionSchema, OptionDef, OptionValues } from "../../types/command.ts";
+
+/**
+ * Escape a shell argument if it contains special characters.
+ */
+function escapeArg(arg: string): string {
+    if (/[^a-zA-Z0-9_\-./=]/.test(arg)) {
+        return `"${arg.replace(/"/g, '\\"')}"`;
+    }
+    return arg;
+}
+
+/**
+ * Build a CLI command string from values and schema.
+ * 
+ * @param appName - The application name (e.g., "myapp")
+ * @param commandPath - The command path (e.g., ["run"], ["db", "migrate"])
+ * @param schema - The option schema
+ * @param values - The current option values
+ * @returns CLI command string
+ * 
+ * @example
+ * ```typescript
+ * const cmd = buildCliCommand("myapp", ["run"], runOptions, config);
+ * // Returns: "myapp run --agent opencode --fixture test.json"
+ * ```
+ */
+export function buildCliCommand<T extends OptionSchema>(
+    appName: string,
+    commandPath: string[],
+    schema: T,
+    values: OptionValues<T>
+): string {
+    const parts: string[] = [appName, ...commandPath];
+
+    for (const [key, def] of Object.entries(schema) as [keyof T & string, OptionDef][]) {
+        const value = values[key];
+        const defaultValue = def.default;
+
+        // Skip if value equals default (no need to include)
+        if (value === defaultValue) {
+            continue;
+        }
+
+        // Skip undefined/null values
+        if (value === undefined || value === null) {
+            continue;
+        }
+
+        const optionName = toKebabCase(key);
+
+        switch (def.type) {
+            case "boolean":
+                if (value === true) {
+                    parts.push(`--${optionName}`);
+                } else if (value === false && defaultValue === true) {
+                    parts.push(`--no-${optionName}`);
+                }
+                break;
+
+            case "array":
+                if (Array.isArray(value) && value.length > 0) {
+                    for (const item of value) {
+                        parts.push(`--${optionName}`, escapeArg(String(item)));
+                    }
+                }
+                break;
+
+            case "number":
+                parts.push(`--${optionName}`, String(value));
+                break;
+
+            case "string":
+            default:
+                if (String(value).trim() !== "") {
+                    parts.push(`--${optionName}`, escapeArg(String(value)));
+                }
+                break;
+        }
+    }
+
+    return parts.join(" ");
+}
+
+/**
+ * Convert camelCase to kebab-case.
+ */
+function toKebabCase(str: string): string {
+    return str.replace(/([a-z])([A-Z])/g, "$1-$2").toLowerCase();
+}

package/src/tui/utils/index.ts

@@ -0,0 +1,13 @@
+export {
+    schemaToFieldConfigs,
+    groupFieldConfigs,
+    getFieldDisplayValue,
+} from "./schemaToFields.ts";
+
+export { buildCliCommand } from "./buildCliCommand.ts";
+
+export {
+    loadPersistedParameters,
+    savePersistedParameters,
+    clearPersistedParameters,
+} from "./parameterPersistence.ts";

package/src/tui/utils/parameterPersistence.ts

@@ -0,0 +1,96 @@
+import { homedir } from "os";
+import { join } from "path";
+import { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync } from "fs";
+
+/**
+ * Get the directory path for storing app configuration.
+ * Creates the directory if it doesn't exist.
+ * 
+ * @param appName - The application name
+ * @returns The path to the app config directory
+ */
+function getAppConfigDir(appName: string): string {
+    const configDir = join(homedir(), `.${appName}`);
+    if (!existsSync(configDir)) {
+        mkdirSync(configDir, { recursive: true });
+    }
+    return configDir;
+}
+
+/**
+ * Get the file path for storing command parameters.
+ * 
+ * @param appName - The application name
+ * @param commandName - The command name
+ * @returns The path to the parameters file
+ */
+function getParametersFilePath(appName: string, commandName: string): string {
+    const configDir = getAppConfigDir(appName);
+    return join(configDir, `${commandName}.parameters.json`);
+}
+
+/**
+ * Load persisted parameters for a command.
+ * 
+ * @param appName - The application name
+ * @param commandName - The command name
+ * @returns The persisted parameters, or an empty object if none exist
+ */
+export function loadPersistedParameters(
+    appName: string,
+    commandName: string
+): Record<string, unknown> {
+    try {
+        const filePath = getParametersFilePath(appName, commandName);
+        if (existsSync(filePath)) {
+            const content = readFileSync(filePath, "utf-8");
+            return JSON.parse(content) as Record<string, unknown>;
+        }
+    } catch (error) {
+        // Silently ignore errors - just return empty object
+        console.error(`Failed to load persisted parameters: ${error}`);
+    }
+    return {};
+}
+
+/**
+ * Save parameters for a command.
+ * 
+ * @param appName - The application name
+ * @param commandName - The command name
+ * @param parameters - The parameters to persist
+ */
+export function savePersistedParameters(
+    appName: string,
+    commandName: string,
+    parameters: Record<string, unknown>
+): void {
+    try {
+        const filePath = getParametersFilePath(appName, commandName);
+        writeFileSync(filePath, JSON.stringify(parameters, null, 2), "utf-8");
+    } catch (error) {
+        // Silently ignore errors
+        console.error(`Failed to save persisted parameters: ${error}`);
+    }
+}
+
+/**
+ * Clear persisted parameters for a command.
+ * 
+ * @param appName - The application name
+ * @param commandName - The command name
+ */
+export function clearPersistedParameters(
+    appName: string,
+    commandName: string
+): void {
+    try {
+        const filePath = getParametersFilePath(appName, commandName);
+        if (existsSync(filePath)) {
+            unlinkSync(filePath);
+        }
+    } catch (error) {
+        // Silently ignore errors
+        console.error(`Failed to clear persisted parameters: ${error}`);
+    }
+}

package/src/tui/utils/schemaToFields.ts

@@ -0,0 +1,144 @@
+import type { OptionSchema, OptionDef } from "../../types/command.ts";
+import type { FieldConfig, FieldType, FieldOption } from "../components/types.ts";
+
+/**
+ * Convert an option type to a field type.
+ */
+function optionTypeToFieldType(def: OptionDef): FieldType {
+    // If it has enum values, it's an enum type
+    if (def.enum && def.enum.length > 0) {
+        return "enum";
+    }
+
+    switch (def.type) {
+        case "string":
+            return "text";
+        case "number":
+            return "number";
+        case "boolean":
+            return "boolean";
+        case "array":
+            return "text"; // Arrays are edited as comma-separated text
+        default:
+            return "text";
+    }
+}
+
+/**
+ * Create field options from enum values.
+ */
+function createFieldOptions(def: OptionDef): FieldOption[] | undefined {
+    if (!def.enum || def.enum.length === 0) {
+        return undefined;
+    }
+
+    return def.enum.map((value) => ({
+        name: String(value),
+        value,
+    }));
+}
+
+/**
+ * Create a label from a key name.
+ * Converts camelCase to Title Case.
+ */
+function keyToLabel(key: string): string {
+    return key
+        .replace(/([A-Z])/g, " $1")
+        .replace(/^./, (str) => str.toUpperCase())
+        .trim();
+}
+
+/**
+ * Convert an option schema to field configs for TUI forms.
+ * 
+ * @param schema - The option schema to convert
+ * @returns Array of field configs sorted by order
+ * 
+ * @example
+ * ```typescript
+ * const fields = schemaToFieldConfigs(myOptions);
+ * // Returns FieldConfig[] ready for ConfigForm
+ * ```
+ */
+export function schemaToFieldConfigs(schema: OptionSchema): FieldConfig[] {
+    const fields: FieldConfig[] = [];
+
+    for (const [key, def] of Object.entries(schema)) {
+        // Skip hidden fields
+        if (def.tuiHidden) {
+            continue;
+        }
+
+        const fieldConfig: FieldConfig = {
+            key,
+            label: def.label ?? keyToLabel(key),
+            type: optionTypeToFieldType(def),
+            options: createFieldOptions(def),
+            placeholder: def.placeholder,
+            group: def.group,
+        };
+
+        fields.push(fieldConfig);
+    }
+
+    // Sort by order if specified, otherwise preserve insertion order
+    fields.sort((a, b) => {
+        const orderA = schema[a.key]?.order ?? Number.MAX_SAFE_INTEGER;
+        const orderB = schema[b.key]?.order ?? Number.MAX_SAFE_INTEGER;
+        return orderA - orderB;
+    });
+
+    return fields;
+}
+
+/**
+ * Group field configs by their group property.
+ * 
+ * @param fields - Field configs to group
+ * @returns Map of group name to field configs
+ */
+export function groupFieldConfigs(
+    fields: FieldConfig[]
+): Map<string | undefined, FieldConfig[]> {
+    const groups = new Map<string | undefined, FieldConfig[]>();
+
+    for (const field of fields) {
+        const group = field.group;
+        if (!groups.has(group)) {
+            groups.set(group, []);
+        }
+        groups.get(group)!.push(field);
+    }
+
+    return groups;
+}
+
+/**
+ * Get display value for a field.
+ * 
+ * @param value - The field value
+ * @param fieldConfig - The field configuration
+ * @returns Formatted display string
+ */
+export function getFieldDisplayValue(
+    value: unknown,
+    fieldConfig: FieldConfig
+): string {
+    if (fieldConfig.type === "boolean") {
+        return value ? "True" : "False";
+    }
+
+    if (fieldConfig.type === "enum" && fieldConfig.options) {
+        const option = fieldConfig.options.find((o) => o.value === value);
+        return option?.name ?? String(value);
+    }
+
+    const strValue = String(value ?? "");
+    if (strValue === "") {
+        return "(empty)";
+    }
+
+    // Truncate long values
+    return strValue.length > 60 ? strValue.substring(0, 57) + "..." : strValue;
+}

package/src/types/command.ts

@@ -0,0 +1,103 @@
+/**
+ * Option definition for command-line arguments
+ */
+export interface OptionDef {
+  type: "string" | "number" | "boolean" | "array";
+  description: string;
+  alias?: string;
+  default?: unknown;
+  required?: boolean;
+  env?: string;
+  enum?: readonly string[];
+  min?: number;
+  max?: number;
+
+  // TUI-specific properties
+  /** Display label in TUI form (defaults to key name) */
+  label?: string;
+  /** Display order in TUI form (lower = first) */
+  order?: number;
+  /** Group name for organizing fields in TUI */
+  group?: string;
+  /** Placeholder text for input fields */
+  placeholder?: string;
+  /** Hide this field from TUI (still available in CLI) */
+  tuiHidden?: boolean;
+}
+
+/**
+ * Schema defining all options for a command
+ */
+export type OptionSchema = Record<string, OptionDef>;
+
+/**
+ * Inferred option values from a schema
+ */
+export type OptionValues<T extends OptionSchema> = {
+  [K in keyof T]: T[K]["type"] extends "string" ? string
+  : T[K]["type"] extends "number" ? number
+  : T[K]["type"] extends "boolean" ? boolean
+  : T[K]["type"] extends "array" ? string[]
+  : unknown;
+};
+
+/**
+ * Context passed to command executors
+ */
+export interface CommandContext<T extends OptionSchema = OptionSchema> {
+  options: OptionValues<T>;
+  args: string[];
+  commandPath: string[];
+}
+
+/**
+ * Command executor function
+ */
+export type CommandExecutor<T extends OptionSchema = OptionSchema> = (
+  ctx: CommandContext<T>
+) => void | Promise<void>;
+
+/**
+ * Command definition
+ */
+export interface Command<
+  T extends OptionSchema = OptionSchema,
+  R = void,
+> {
+  name: string;
+  description: string;
+  aliases?: string[];
+  hidden?: boolean;
+  options?: T;
+  subcommands?: Record<string, Command>;
+  examples?: Array<{ command: string; description: string }>;
+  execute: (ctx: CommandContext<T>) => R | Promise<R>;
+  beforeExecute?: (ctx: CommandContext<T>) => void | Promise<void>;
+  afterExecute?: (ctx: CommandContext<T>) => void | Promise<void>;
+}
+
+/**
+ * TUI command with a render function
+ */
+export interface TuiCommand<T extends OptionSchema = OptionSchema>
+  extends Omit<Command<T>, "execute"> {
+  render: (ctx: CommandContext<T>) => React.ReactNode;
+}
+
+/**
+ * Define a CLI command
+ */
+export function defineCommand<T extends OptionSchema = OptionSchema>(
+  config: Command<T>
+): Command<T> {
+  return config;
+}
+
+/**
+ * Define a TUI command
+ */
+export function defineTuiCommand<T extends OptionSchema = OptionSchema>(
+  config: TuiCommand<T>
+): TuiCommand<T> {
+  return config;
+}

package/src/types/execution.ts

@@ -0,0 +1,11 @@
+/**
+ * Execution mode determines how a command runs.
+ * - Cli: Command-line mode with arguments, executes and exits
+ * - Tui: Terminal UI mode with interactive rendering
+ */
+export enum ExecutionMode {
+  /** Command-line mode: parse args, execute, exit */
+  Cli = "cli",
+  /** Terminal UI mode: interactive render loop */
+  Tui = "tui",
+}

package/src/types/index.ts

@@ -0,0 +1 @@
+export * from "./command.ts";