@pablozaiden/terminatui 0.1.0

package/src/tui/TuiApplication.tsx

@@ -0,0 +1,230 @@
+import { createCliRenderer } from "@opentui/core";
+import { createRoot } from "@opentui/react";
+import { Application, type ApplicationConfig } from "../core/application.ts";
+import type { AnyCommand } from "../core/command.ts";
+import { TuiApp } from "./TuiApp.tsx";
+import { Theme } from "./theme.ts";
+import type { LogSource, LogEvent } from "./hooks/index.ts";
+import { LogLevel as TuiLogLevel } from "./hooks/index.ts";
+import { LogLevel as CoreLogLevel, type LogEvent as CoreLogEvent } from "../core/logger.ts";
+import type { FieldConfig } from "./components/types.ts";
+import { createSettingsCommand } from "../builtins/settings.ts";
+import { loadPersistedParameters } from "./utils/parameterPersistence.ts";
+
+/**
+ * Custom field configuration for TUI forms.
+ * Allows adding application-specific fields that aren't part of command options.
+ */
+export interface CustomField extends FieldConfig {
+    /** Default value for the field */
+    default?: unknown;
+    /** Called when the field value changes */
+    onChange?: (value: unknown, allValues: Record<string, unknown>) => void;
+}
+
+/**
+ * Extended configuration for TUI-enabled applications.
+ */
+export interface TuiApplicationConfig extends ApplicationConfig {
+    /** Enable interactive TUI mode */
+    enableTui?: boolean;
+    /** Log source for TUI log panel */
+    logSource?: LogSource;
+    /** Custom fields to add to the TUI form */
+    customFields?: CustomField[];
+}
+
+/**
+ * Application class with built-in TUI support.
+ * 
+ * Extends the base Application to provide automatic TUI rendering
+ * when running interactively or with the --interactive flag.
+ * 
+ * @example
+ * ```typescript
+ * class MyApp extends TuiApplication {
+ *   constructor() {
+ *     super({
+ *       name: "myapp",
+ *       version: "1.0.0",
+ *       commands: [new RunCommand(), new ConfigCommand()],
+ *       enableTui: true,
+ *     });
+ *   }
+ * }
+ * 
+ * await new MyApp().run(process.argv.slice(2));
+ * ```
+ */
+export class TuiApplication extends Application {
+    private readonly enableTui: boolean;
+    private readonly logSource?: LogSource;
+    private readonly customFields?: CustomField[];
+
+    constructor(config: TuiApplicationConfig) {
+        super(config);
+        this.enableTui = config.enableTui ?? true;
+        this.logSource = config.logSource;
+        this.customFields = config.customFields;
+    }
+
+    /**
+     * Run the application.
+     * 
+     * If no arguments are provided and TUI is enabled, launches the TUI.
+     * Otherwise, runs in CLI mode.
+     */
+    override async run(argv: string[] = process.argv.slice(2)): Promise<void> {
+        // Check for --interactive or -i flag
+        const hasInteractiveFlag = argv.includes("--interactive") || argv.includes("-i");
+        const filteredArgs = argv.filter((arg) => arg !== "--interactive" && arg !== "-i");
+
+        // Launch TUI if:
+        // 1. Explicit --interactive flag, or
+        // 2. No args and TUI is enabled
+        if (hasInteractiveFlag || (filteredArgs.length === 0 && this.enableTui)) {
+            await this.runTui();
+            return;
+        }
+
+        // Otherwise run CLI mode
+        await super.run(filteredArgs);
+    }
+
+    /**
+     * Launch the interactive TUI.
+     */
+    async runTui(): Promise<void> {
+        // Get all commands that support TUI or have options
+        const commands = this.getExecutableCommands();
+
+        // Load and apply persisted settings (log-level, detailed-logs)
+        this.loadPersistedSettings();
+
+        // Enable TUI mode on the logger so logs go to the event emitter
+        // instead of stderr (which would corrupt the TUI display)
+        this.context.logger.setTuiMode(true);
+
+        // Create a log source from the logger if one wasn't provided
+        const logSource = this.logSource ?? this.createLogSourceFromLogger();
+
+        const renderer = await createCliRenderer({
+            useAlternateScreen: true,
+            useConsole: false,
+            exitOnCtrlC: true,
+            backgroundColor: Theme.background,
+            useMouse: true,
+            enableMouseMovement: true,
+            openConsoleOnError: false,
+        });
+
+        return new Promise<void>((resolve) => {
+            const handleExit = () => {
+                // Restore CLI mode on exit
+                this.context.logger.setTuiMode(false);
+                renderer.destroy();
+                resolve();
+            };
+
+            const root = createRoot(renderer);
+            root.render(
+                <TuiApp
+                    name={this.name}
+                    displayName={this.displayName}
+                    version={this.version}
+                    commands={commands}
+                    context={this.context}
+                    logSource={logSource}
+                    customFields={this.customFields}
+                    onExit={handleExit}
+                />
+            );
+
+            renderer.start();
+        });
+    }
+
+    /**
+     * Create a LogSource adapter from the application logger.
+     */
+    private createLogSourceFromLogger(): LogSource {
+        const logger = this.context.logger;
+        
+        // Map core log levels to TUI log levels
+        const mapLogLevel = (level: CoreLogLevel): TuiLogLevel => {
+            switch (level) {
+                case CoreLogLevel.Silly: return TuiLogLevel.Silly;
+                case CoreLogLevel.Trace: return TuiLogLevel.Trace;
+                case CoreLogLevel.Debug: return TuiLogLevel.Debug;
+                case CoreLogLevel.Info: return TuiLogLevel.Info;
+                case CoreLogLevel.Warn: return TuiLogLevel.Warn;
+                case CoreLogLevel.Error: return TuiLogLevel.Error;
+                case CoreLogLevel.Fatal: return TuiLogLevel.Fatal;
+                default: return TuiLogLevel.Info;
+            }
+        };
+
+        return {
+            subscribe: (callback: (event: LogEvent) => void) => {
+                return logger.onLogEvent((coreEvent: CoreLogEvent) => {
+                    callback({
+                        level: mapLogLevel(coreEvent.level),
+                        message: coreEvent.message,
+                    });
+                });
+            },
+        };
+    }
+
+    /**
+     * Load persisted settings and apply them to the logger.
+     * Settings are saved when the user uses the Settings command.
+     */
+    private loadPersistedSettings(): void {
+        try {
+            const settings = loadPersistedParameters(this.name, "settings");
+            
+            // Apply log-level if set
+            if (settings["log-level"]) {
+                const levelStr = String(settings["log-level"]).toLowerCase();
+                const level = Object.entries(CoreLogLevel).find(
+                    ([key, val]) => typeof val === "number" && key.toLowerCase() === levelStr
+                )?.[1] as CoreLogLevel | undefined;
+                if (level !== undefined) {
+                    this.context.logger.setMinLevel(level);
+                }
+            }
+            
+            // Apply detailed-logs if set
+            if (settings["detailed-logs"] !== undefined) {
+                this.context.logger.setDetailed(Boolean(settings["detailed-logs"]));
+            }
+        } catch {
+            // Silently ignore errors loading settings
+        }
+    }
+
+    /**
+     * Get commands that can be used in TUI.
+     * Filters out internal commands like version/help, and adds built-in settings.
+     */
+    private getExecutableCommands(): AnyCommand[] {
+        const userCommands = this.registry
+            .list()
+            .filter((cmd) => {
+                // Exclude version and help from main menu
+                if (cmd.name === "version" || cmd.name === "help") {
+                    return false;
+                }
+                // Exclude settings if already defined by user (they shouldn't)
+                if (cmd.name === "settings") {
+                    return false;
+                }
+                // Include commands that have options or execute methods
+                return true;
+            });
+
+        // Add built-in settings command at the end
+        return [...userCommands, createSettingsCommand()];
+    }
+}

package/src/tui/app.ts

@@ -0,0 +1,29 @@
+/**
+ * App configuration
+ */
+export interface AppConfig {
+  name: string;
+  version?: string;
+  description?: string;
+}
+
+/**
+ * App state
+ */
+export interface AppState {
+  currentView: string;
+  isLoading: boolean;
+  error?: Error;
+}
+
+/**
+ * Create a TUI application
+ */
+export function createApp(_config: AppConfig) {
+  return {
+    run: async () => {
+      // Placeholder for TUI app runner
+      console.log("TUI app started");
+    },
+  };
+}

package/src/tui/components/ActionButton.tsx

@@ -0,0 +1,36 @@
+import { Theme } from "../theme.ts";
+
+interface ActionButtonProps {
+    /** Button label */
+    label: string;
+    /** Whether this button is selected */
+    isSelected: boolean;
+    /** Optional spinner frame for loading state */
+    spinnerFrame?: string;
+}
+
+/**
+ * Action button displayed at the bottom of a config form.
+ */
+export function ActionButton({ label, isSelected, spinnerFrame }: ActionButtonProps) {
+    const prefix = isSelected ? "► " : "  ";
+    const displayLabel = spinnerFrame ? `${spinnerFrame} ${label}...` : `[ ${label} ]`;
+    
+    if (isSelected) {
+        return (
+            <box marginTop={1}>
+                <text fg="#000000" bg={Theme.actionButton}>
+                    {prefix}{displayLabel}
+                </text>
+            </box>
+        );
+    }
+
+    return (
+        <box marginTop={1}>
+            <text fg={Theme.actionButton}>
+                {prefix}{displayLabel}
+            </text>
+        </box>
+    );
+}

package/src/tui/components/CliModal.tsx

@@ -0,0 +1,81 @@
+import { Theme } from "../theme.ts";
+import { useKeyboardHandler, KeyboardPriority } from "../hooks/useKeyboardHandler.ts";
+
+interface CliModalProps {
+    /** CLI command to display */
+    command: string;
+    /** Whether the modal is visible */
+    visible: boolean;
+    /** Called when the modal should close */
+    onClose: () => void;
+    /** Called when the command should be copied */
+    onCopy?: (content: string, label: string) => void;
+}
+
+/**
+ * Modal displaying the CLI command equivalent of the current config.
+ */
+export function CliModal({
+    command,
+    visible,
+    onClose,
+    onCopy,
+}: CliModalProps) {
+    // Modal keyboard handler
+    useKeyboardHandler(
+        (event) => {
+            const { key } = event;
+            
+            if (key.name === "escape" || key.name === "return" || key.name === "enter") {
+                onClose();
+                event.stopPropagation();
+                return;
+            }
+
+            // Y to copy
+            if (key.name === "y") {
+                onCopy?.(command, "CLI command");
+                event.stopPropagation();
+                return;
+            }
+        },
+        KeyboardPriority.Modal,
+        { enabled: visible, modal: true }
+    );
+
+    if (!visible) {
+        return null;
+    }
+
+    return (
+        <box
+            position="absolute"
+            top={4}
+            left={4}
+            width="80%"
+            height={10}
+            backgroundColor={Theme.overlay}
+            border={true}
+            borderStyle="rounded"
+            borderColor={Theme.overlayTitle}
+            padding={1}
+            flexDirection="column"
+            gap={1}
+            zIndex={20}
+        >
+            <text fg={Theme.overlayTitle}>
+                <strong>CLI Command</strong>
+            </text>
+
+            <scrollbox scrollX={true} height={3}>
+                <text fg={Theme.value}>
+                    {command}
+                </text>
+            </scrollbox>
+
+            <text fg={Theme.statusText}>
+                Ctrl+Y to copy • Enter or Esc to close
+            </text>
+        </box>
+    );
+}

package/src/tui/components/CommandSelector.tsx

@@ -0,0 +1,159 @@
+import { Theme } from "../theme.ts";
+import { useKeyboardHandler, KeyboardPriority } from "../hooks/useKeyboardHandler.ts";
+import type { Command } from "../../core/command.ts";
+
+interface CommandItem {
+    /** The command object */
+    command: Command;
+    /** Display label (defaults to command name) */
+    label?: string;
+    /** Description (defaults to command description) */
+    description?: string;
+}
+
+interface CommandSelectorProps {
+    /** Commands to display */
+    commands: CommandItem[];
+    /** Currently selected index */
+    selectedIndex: number;
+    /** Called when selection changes */
+    onSelectionChange: (index: number) => void;
+    /** Called when a command is selected */
+    onSelect: (command: Command) => void;
+    /** Called when user wants to exit */
+    onExit: () => void;
+    /** Breadcrumb path for nested commands */
+    breadcrumb?: string[];
+}
+
+/**
+ * Command selection menu.
+ */
+export function CommandSelector({
+    commands,
+    selectedIndex,
+    onSelectionChange,
+    onSelect,
+    onExit,
+    breadcrumb,
+}: CommandSelectorProps) {
+    // Keyboard handler for navigation
+    useKeyboardHandler(
+        (event) => {
+            const { key } = event;
+
+            // Arrow key navigation
+            if (key.name === "down") {
+                const newIndex = Math.min(selectedIndex + 1, commands.length - 1);
+                onSelectionChange(newIndex);
+                event.stopPropagation();
+                return;
+            }
+
+            if (key.name === "up") {
+                const newIndex = Math.max(selectedIndex - 1, 0);
+                onSelectionChange(newIndex);
+                event.stopPropagation();
+                return;
+            }
+
+            // Enter to select command
+            if (key.name === "return" || key.name === "enter") {
+                const selected = commands[selectedIndex];
+                if (selected) {
+                    onSelect(selected.command);
+                }
+                event.stopPropagation();
+                return;
+            }
+
+            // Escape to exit or go back
+            if (key.name === "escape") {
+                onExit();
+                event.stopPropagation();
+                return;
+            }
+        },
+        KeyboardPriority.Focused
+    );
+
+    const title = breadcrumb?.length 
+        ? `Select Command (${breadcrumb.join(" › ")})`
+        : "Select Command";
+
+    return (
+        <box
+            flexDirection="column"
+            flexGrow={1}
+            justifyContent="center"
+            alignItems="center"
+            gap={1}
+        >
+            <box
+                flexDirection="column"
+                border={true}
+                borderStyle="rounded"
+                borderColor={Theme.borderFocused}
+                title={title}
+                paddingLeft={3}
+                paddingRight={3}
+                paddingTop={1}
+                paddingBottom={1}
+                minWidth={60}
+            >
+                <box flexDirection="column" gap={1}>
+                    {commands.map((item, idx) => {
+                        const isSelected = idx === selectedIndex;
+                        const prefix = isSelected ? "► " : "  ";
+                        const label = item.label ?? item.command.displayName ?? item.command.name;
+                        const description = item.description ?? item.command.description;
+
+                        // Show mode indicators
+                        const modeIndicator = getModeIndicator(item.command);
+
+                        if (isSelected) {
+                            return (
+                                <box key={item.command.name} flexDirection="column">
+                                    <text fg="#000000" bg="cyan">
+                                        {prefix}{label} {modeIndicator}
+                                    </text>
+                                    <text fg={Theme.label}>
+                                        {"    "}{description}
+                                    </text>
+                                </box>
+                            );
+                        }
+
+                        return (
+                            <box key={item.command.name} flexDirection="column">
+                                <text fg={Theme.value}>
+                                    {prefix}{label} {modeIndicator}
+                                </text>
+                                <text fg={Theme.border}>
+                                    {"    "}{description}
+                                </text>
+                            </box>
+                        );
+                    })}
+                </box>
+            </box>
+
+            <text fg={Theme.label}>
+                ↑↓ Navigate • Enter Select • Esc {breadcrumb?.length ? "Back" : "Exit"}
+            </text>
+        </box>
+    );
+}
+
+/**
+ * Get mode indicator for a command (e.g., "[cli]", "[tui]", "[cli/tui]").
+ */
+function getModeIndicator(command: Command): string {
+    const cli = command.supportsCli();
+    const tui = command.supportsTui();
+    
+    if (cli && tui) return "";
+    if (cli) return "[cli]";
+    if (tui) return "[tui]";
+    return "";
+}

package/src/tui/components/ConfigForm.tsx

@@ -0,0 +1,148 @@
+import { useRef, useEffect, type ReactNode } from "react";
+import type { ScrollBoxRenderable } from "@opentui/core";
+import { Theme } from "../theme.ts";
+import { FieldRow } from "./FieldRow.tsx";
+import { useKeyboardHandler, KeyboardPriority } from "../hooks/useKeyboardHandler.ts";
+import type { FieldConfig } from "./types.ts";
+
+interface ConfigFormProps {
+    /** Title for the form border */
+    title: string;
+    /** Field configurations */
+    fieldConfigs: FieldConfig[];
+    /** Current values */
+    values: Record<string, unknown>;
+    /** Currently selected index */
+    selectedIndex: number;
+    /** Whether the form is focused */
+    focused: boolean;
+    /** Called when selection changes */
+    onSelectionChange: (index: number) => void;
+    /** Called when a field should be edited */
+    onEditField: (fieldKey: string) => void;
+    /** Called when the action button is pressed */
+    onAction: () => void;
+    /** Function to get display value for a field */
+    getDisplayValue?: (key: string, value: unknown, type: string) => string;
+    /** The action button component */
+    actionButton: ReactNode;
+}
+
+/**
+ * Default display value formatter.
+ */
+function defaultGetDisplayValue(_key: string, value: unknown, type: string): string {
+    if (type === "boolean") {
+        return value ? "True" : "False";
+    }
+    const strValue = String(value ?? "");
+    if (strValue === "") {
+        return "(empty)";
+    }
+    return strValue.length > 60 ? strValue.substring(0, 57) + "..." : strValue;
+}
+
+/**
+ * Generic config form that renders fields from a schema.
+ */
+export function ConfigForm({
+    title,
+    fieldConfigs,
+    values,
+    selectedIndex,
+    focused,
+    onSelectionChange,
+    onEditField,
+    onAction,
+    getDisplayValue = defaultGetDisplayValue,
+    actionButton,
+}: ConfigFormProps) {
+    const borderColor = focused ? Theme.borderFocused : Theme.border;
+    const scrollboxRef = useRef<ScrollBoxRenderable>(null);
+    const totalFields = fieldConfigs.length + 1; // +1 for action button
+
+    // Auto-scroll to keep selected item visible
+    useEffect(() => {
+        if (scrollboxRef.current) {
+            scrollboxRef.current.scrollTo(selectedIndex);
+        }
+    }, [selectedIndex]);
+
+    // Handle keyboard events at Focused priority (only when focused)
+    useKeyboardHandler(
+        (event) => {
+            const { key } = event;
+
+            // Arrow key navigation
+            if (key.name === "down") {
+                const newIndex = Math.min(selectedIndex + 1, totalFields - 1);
+                onSelectionChange(newIndex);
+                event.stopPropagation();
+                return;
+            }
+
+            if (key.name === "up") {
+                const newIndex = Math.max(selectedIndex - 1, 0);
+                onSelectionChange(newIndex);
+                event.stopPropagation();
+                return;
+            }
+
+            // Enter to edit field or run action
+            if (key.name === "return" || key.name === "enter") {
+                if (selectedIndex === fieldConfigs.length) {
+                    onAction();
+                } else {
+                    const fieldConfig = fieldConfigs[selectedIndex];
+                    if (fieldConfig) {
+                        onEditField(fieldConfig.key);
+                    }
+                }
+                event.stopPropagation();
+                return;
+            }
+        },
+        KeyboardPriority.Focused,
+        { enabled: focused }
+    );
+
+    return (
+        <box
+            flexDirection="column"
+            border={true}
+            borderStyle="rounded"
+            borderColor={borderColor}
+            title={title}
+            flexGrow={1}
+            padding={1}
+        >
+            <scrollbox
+                ref={scrollboxRef}
+                scrollY={true}
+                flexGrow={1}
+            >
+                <box flexDirection="column" gap={0}>
+                    {fieldConfigs.map((field, idx) => {
+                        const isSelected = idx === selectedIndex;
+                        const displayValue = getDisplayValue(
+                            field.key,
+                            values[field.key],
+                            field.type
+                        );
+
+                        return (
+                            <FieldRow
+                                key={field.key}
+                                label={field.label}
+                                value={displayValue}
+                                isSelected={isSelected}
+                            />
+                        );
+                    })}
+
+                    {actionButton}
+                </box>
+            </scrollbox>
+        </box>
+    );
+}