@pablozaiden/terminatui 0.1.0

package/src/core/logger.ts

@@ -0,0 +1,164 @@
+import { EventEmitter } from "events";
+import { Logger as TsLogger } from "tslog";
+
+/**
+ * Log levels from least to most severe.
+ */
+export enum LogLevel {
+  Silly = 0,
+  Trace = 1,
+  Debug = 2,
+  Info = 3,
+  Warn = 4,
+  Error = 5,
+  Fatal = 6,
+}
+
+/**
+ * Event emitted when a log message is written.
+ */
+export interface LogEvent {
+  message: string;
+  level: LogLevel;
+  timestamp: Date;
+}
+
+/**
+ * Logger configuration options.
+ */
+export interface LoggerConfig {
+  /** Minimum log level to output */
+  minLevel?: LogLevel;
+  /** Whether to use detailed format (with timestamp/level) */
+  detailed?: boolean;
+  /** Whether to route logs to TUI event emitter instead of stderr */
+  tuiMode?: boolean;
+}
+
+/**
+ * Logger class that wraps tslog and supports TUI mode.
+ * Can be instantiated multiple times for different contexts.
+ */
+export class Logger {
+  private tsLogger: TsLogger<unknown>;
+  private readonly eventEmitter = new EventEmitter();
+  private tuiMode: boolean;
+  private detailed: boolean;
+  private minLevel: LogLevel;
+
+  constructor(config: LoggerConfig = {}) {
+    this.tuiMode = config.tuiMode ?? false;
+    this.detailed = config.detailed ?? false;
+    this.minLevel = config.minLevel ?? LogLevel.Info;
+
+    this.tsLogger = this.createTsLogger(this.minLevel);
+  }
+
+  private createTsLogger(minLevel: LogLevel): TsLogger<unknown> {
+    return new TsLogger({
+      type: "pretty",
+      minLevel,
+      overwrite: {
+        transportFormatted: (
+          logMetaMarkup: string,
+          logArgs: unknown[],
+          logErrors: string[],
+          logMeta: unknown
+        ) => {
+          const baseLine = `${logMetaMarkup}${(logArgs as string[]).join(" ")}${logErrors.join("")}`;
+          const simpleLine = `${(logArgs as string[]).join(" ")}${logErrors.join("")}`;
+          const meta = logMeta as Record<string, unknown>;
+          const levelFromMeta =
+            typeof meta?.["logLevelId"] === "number"
+              ? (meta["logLevelId"] as LogLevel)
+              : LogLevel.Info;
+
+          const output = this.detailed ? baseLine : simpleLine;
+
+          if (this.tuiMode) {
+            this.eventEmitter.emit("log", {
+              message: output,
+              level: levelFromMeta,
+              timestamp: new Date(),
+            } satisfies LogEvent);
+          } else {
+            process.stderr.write(output + "\n");
+          }
+        },
+      },
+    });
+  }
+
+  /**
+   * Subscribe to log events (for TUI mode).
+   */
+  onLogEvent(listener: (event: LogEvent) => void): () => void {
+    this.eventEmitter.on("log", listener);
+    return () => this.eventEmitter.off("log", listener);
+  }
+
+  /**
+   * Enable or disable TUI mode.
+   */
+  setTuiMode(enabled: boolean): void {
+    this.tuiMode = enabled;
+  }
+
+  /**
+   * Enable or disable detailed log format.
+   */
+  setDetailed(enabled: boolean): void {
+    this.detailed = enabled;
+  }
+
+  /**
+   * Set the minimum log level.
+   */
+  setMinLevel(level: LogLevel): void {
+    this.minLevel = level;
+    this.tsLogger = this.createTsLogger(level);
+  }
+
+  /**
+   * Get the current minimum log level.
+   */
+  getMinLevel(): LogLevel {
+    return this.minLevel;
+  }
+
+  // Logging methods
+  silly(...args: unknown[]): void {
+    this.tsLogger.silly(...args);
+  }
+
+  trace(...args: unknown[]): void {
+    this.tsLogger.trace(...args);
+  }
+
+  debug(...args: unknown[]): void {
+    this.tsLogger.debug(...args);
+  }
+
+  info(...args: unknown[]): void {
+    this.tsLogger.info(...args);
+  }
+
+  warn(...args: unknown[]): void {
+    this.tsLogger.warn(...args);
+  }
+
+  error(...args: unknown[]): void {
+    this.tsLogger.error(...args);
+  }
+
+  fatal(...args: unknown[]): void {
+    this.tsLogger.fatal(...args);
+  }
+}
+
+/**
+ * Create a new logger instance with the given configuration.
+ */
+export function createLogger(config: LoggerConfig = {}): Logger {
+  return new Logger(config);
+}

package/src/core/registry.ts

@@ -0,0 +1,140 @@
+import { type AnyCommand } from "./command.ts";
+
+/**
+ * Registry for managing commands.
+ * Provides registration, lookup, and resolution of command paths.
+ */
+export class CommandRegistry {
+  private readonly commands = new Map<string, AnyCommand>();
+
+  /**
+   * Register a command.
+   * @param command The command to register
+   * @throws If a command with the same name is already registered
+   */
+  register(command: AnyCommand): void {
+    command.validate();
+
+    if (this.commands.has(command.name)) {
+      throw new Error(`Command '${command.name}' is already registered`);
+    }
+
+    this.commands.set(command.name, command);
+  }
+
+  /**
+   * Register multiple commands.
+   * @param commands Array of commands to register
+   */
+  registerAll(commands: AnyCommand[]): void {
+    for (const command of commands) {
+      this.register(command);
+    }
+  }
+
+  /**
+   * Get a command by name.
+   * @param name Command name
+   * @returns The command or undefined if not found
+   */
+  get(name: string): AnyCommand | undefined {
+    return this.commands.get(name);
+  }
+
+  /**
+   * Check if a command is registered.
+   * @param name Command name
+   */
+  has(name: string): boolean {
+    return this.commands.has(name);
+  }
+
+  /**
+   * Get all registered commands.
+   * @returns Array of all commands
+   */
+  list(): AnyCommand[] {
+    return Array.from(this.commands.values());
+  }
+
+  /**
+   * Get command names.
+   * @returns Array of command names
+   */
+  names(): string[] {
+    return Array.from(this.commands.keys());
+  }
+
+  /**
+   * Resolve a command path to a command.
+   * Supports nested subcommands like ["run", "check", "help"].
+   * 
+   * @param path Array of command names forming the path
+   * @returns Object with resolved command, remaining path, and full path
+   */
+  resolve(path: string[]): ResolveResult {
+    if (path.length === 0) {
+      return { command: undefined, remainingPath: [], resolvedPath: [] };
+    }
+
+    const [first, ...rest] = path;
+    if (!first) {
+      return { command: undefined, remainingPath: path, resolvedPath: [] };
+    }
+
+    const command = this.get(first);
+
+    if (!command) {
+      return { command: undefined, remainingPath: path, resolvedPath: [] };
+    }
+
+    // Resolve nested subcommands
+    let current = command;
+    const resolvedPath: string[] = [first];
+    let remainingPath: string[] = rest;
+
+    while (remainingPath.length > 0) {
+      const nextName = remainingPath[0];
+      if (!nextName) break;
+
+      const subCommand = current.getSubCommand(nextName);
+
+      if (!subCommand) {
+        break;
+      }
+
+      current = subCommand;
+      resolvedPath.push(nextName);
+      remainingPath = remainingPath.slice(1);
+    }
+
+    return { command: current, remainingPath, resolvedPath };
+  }
+
+  /**
+   * Clear all registered commands.
+   * Useful for testing.
+   */
+  clear(): void {
+    this.commands.clear();
+  }
+
+  /**
+   * Get the number of registered commands.
+   */
+  get size(): number {
+    return this.commands.size;
+  }
+}
+
+/**
+ * Result of resolving a command path.
+ */
+export interface ResolveResult {
+  /** The resolved command, or undefined if not found */
+  command: AnyCommand | undefined;
+  /** Path elements that couldn't be resolved (remaining after last matched command) */
+  remainingPath: string[];
+  /** Path elements that were successfully resolved */
+  resolvedPath: string[];
+}

package/src/hooks/index.ts

@@ -0,0 +1,131 @@
+import { useState, useCallback } from "react";
+import type { Command, OptionSchema, OptionValues } from "../types/command.ts";
+
+/**
+ * Hook for command execution
+ */
+export function useCommand<T extends OptionSchema>(command: Command<T>) {
+  const [isExecuting, setIsExecuting] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const execute = useCallback(
+    async (options: OptionValues<T>) => {
+      setIsExecuting(true);
+      setError(null);
+
+      try {
+        await command.execute({
+          options,
+          args: [],
+          commandPath: [command.name],
+        });
+      } catch (err) {
+        setError(err instanceof Error ? err : new Error(String(err)));
+      } finally {
+        setIsExecuting(false);
+      }
+    },
+    [command]
+  );
+
+  return { execute, isExecuting, error };
+}
+
+/**
+ * Hook for managing options state
+ */
+export function useOptions<T extends OptionSchema>(
+  schema: T,
+  initialValues?: Partial<OptionValues<T>>
+) {
+  const [values, setValues] = useState<OptionValues<T>>(() => {
+    const defaults: Record<string, unknown> = {};
+    for (const [key, def] of Object.entries(schema)) {
+      defaults[key] = initialValues?.[key as keyof T] ?? def.default;
+    }
+    return defaults as OptionValues<T>;
+  });
+
+  const setValue = useCallback(
+    <K extends keyof T>(key: K, value: OptionValues<T>[K]) => {
+      setValues((prev) => ({ ...prev, [key]: value }));
+    },
+    []
+  );
+
+  const reset = useCallback(() => {
+    const defaults: Record<string, unknown> = {};
+    for (const [key, def] of Object.entries(schema)) {
+      defaults[key] = def.default;
+    }
+    setValues(defaults as OptionValues<T>);
+  }, [schema]);
+
+  return { values, setValue, setValues, reset };
+}
+
+/**
+ * Hook for navigation between views
+ */
+export function useNavigation(views: string[], initialView?: string) {
+  const [currentView, setCurrentView] = useState(initialView ?? views[0] ?? "");
+  const [history, setHistory] = useState<string[]>([]);
+
+  const navigate = useCallback((view: string) => {
+    setHistory((prev) => [...prev, currentView]);
+    setCurrentView(view);
+  }, [currentView]);
+
+  const goBack = useCallback(() => {
+    const prev = history[history.length - 1];
+    if (prev) {
+      setHistory((h) => h.slice(0, -1));
+      setCurrentView(prev);
+    }
+  }, [history]);
+
+  const canGoBack = history.length > 0;
+
+  return { currentView, navigate, goBack, canGoBack };
+}
+
+/**
+ * Hook for modal state
+ */
+export function useModal(initialOpen = false) {
+  const [isOpen, setIsOpen] = useState(initialOpen);
+
+  const open = useCallback(() => setIsOpen(true), []);
+  const close = useCallback(() => setIsOpen(false), []);
+  const toggle = useCallback(() => setIsOpen((prev) => !prev), []);
+
+  return { isOpen, open, close, toggle };
+}
+
+/**
+ * Hook for async operations
+ */
+export function useAsync<T>(asyncFn: () => Promise<T>) {
+  const [data, setData] = useState<T | null>(null);
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const execute = useCallback(async () => {
+    setIsLoading(true);
+    setError(null);
+
+    try {
+      const result = await asyncFn();
+      setData(result);
+      return result;
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error(String(err));
+      setError(error);
+      throw error;
+    } finally {
+      setIsLoading(false);
+    }
+  }, [asyncFn]);
+
+  return { data, isLoading, error, execute };
+}

package/src/index.ts

@@ -0,0 +1,137 @@
+// Core - New OOP Architecture
+export {
+  Application,
+  AppContext,
+  Command,
+  CommandRegistry,
+  ConfigValidationError,
+  AbortError,
+  Logger,
+  createLogger,
+  LogLevel,
+  generateCommandHelp,
+  generateAppHelp,
+} from "./core/index.ts";
+export type {
+  ApplicationConfig,
+  ApplicationHooks,
+  GlobalOptions,
+  AppConfig,
+  AnyCommand,
+  CommandExample,
+  CommandResult,
+  CommandExecutionContext,
+  ResolveResult,
+  LoggerConfig,
+  LogEvent,
+  HelpOptions,
+} from "./core/index.ts";
+
+// Execution Mode
+export { ExecutionMode } from "./types/execution.ts";
+
+// Built-in Commands (new)
+export { HelpCommand, VersionCommand, SettingsCommand, formatVersion } from "./builtins/index.ts";
+export type { VersionConfig } from "./builtins/index.ts";
+
+// TUI Framework (new)
+export {
+  TuiApp,
+  TuiApplication,
+  Theme,
+  KeyboardProvider,
+  KeyboardPriority,
+  useKeyboardHandler,
+  useClipboard,
+  useSpinner,
+  useConfigState,
+  useCommandExecutor,
+  useLogStream,
+  LogLevel as TuiLogLevel,
+  FieldRow,
+  ActionButton,
+  Header,
+  StatusBar,
+  LogsPanel,
+  ResultsPanel,
+  ConfigForm,
+  EditorModal,
+  CliModal,
+  CommandSelector,
+  JsonHighlight,
+  schemaToFieldConfigs,
+  groupFieldConfigs,
+  getFieldDisplayValue,
+  buildCliCommand,
+} from "./tui/index.ts";
+export type {
+  TuiApplicationConfig,
+  ThemeColors,
+  KeyboardEvent as TuiKeyboardEvent,
+  KeyboardHandler,
+  UseClipboardResult,
+  UseSpinnerResult,
+  UseConfigStateOptions,
+  UseConfigStateResult,
+  UseCommandExecutorResult,
+  LogEntry,
+  LogEvent as TuiLogEvent,
+  LogSource,
+  UseLogStreamResult,
+  FieldType,
+  FieldOption,
+  FieldConfig,
+} from "./tui/index.ts";
+
+// Types (legacy, for backwards compatibility)
+export { defineCommand, defineTuiCommand } from "./types/command.ts";
+export type {
+  Command as LegacyCommand,
+  TuiCommand,
+  OptionDef,
+  OptionSchema,
+  OptionValues,
+  CommandContext,
+  CommandExecutor,
+} from "./types/command.ts";
+
+// CLI Parser
+export {
+  parseCliArgs,
+  extractCommandChain,
+  schemaToParseArgsOptions,
+  parseOptionValues,
+  validateOptions,
+} from "./cli/parser.ts";
+export type { ParseResult, ParseError } from "./cli/parser.ts";
+
+// Registry (legacy)
+export { createCommandRegistry } from "./registry/commandRegistry.ts";
+export type { CommandRegistry as LegacyCommandRegistry } from "./registry/commandRegistry.ts";
+
+// Built-in Commands (legacy)
+export { createHelpCommand } from "./commands/help.ts";
+
+// CLI Output
+export { colors, supportsColors } from "./cli/output/colors.ts";
+export { table, keyValueList, bulletList, numberedList } from "./cli/output/table.ts";
+
+// Help Generation (legacy)
+export {
+  generateHelp,
+  formatCommands,
+  formatOptions as formatOptionsLegacy,
+  formatUsage as formatUsageLegacy,
+  formatExamples as formatExamplesLegacy,
+  getCommandSummary,
+} from "./cli/help.ts";
+
+// TUI
+export { createApp } from "./tui/app.ts";
+export type { AppConfig as TuiAppConfig, AppState } from "./tui/app.ts";
+
+// Components
+export { Box, Text, Input, Select, Button, Modal, Spinner } from "./components/index.ts";
+
+// Hooks
+export { useCommand, useOptions, useNavigation, useModal, useAsync } from "./hooks/index.ts";

package/src/registry/commandRegistry.ts

@@ -0,0 +1,77 @@
+import type { Command, OptionSchema } from "../types/command.ts";
+
+/**
+ * Command registry for managing commands
+ */
+export interface CommandRegistry<T extends OptionSchema = OptionSchema> {
+  register(command: Command<T>): void;
+  get(name: string): Command<T> | undefined;
+  resolve(nameOrAlias: string): Command<T> | undefined;
+  has(nameOrAlias: string): boolean;
+  list(): Command<T>[];
+  getNames(): string[];
+  getCommandMap(): Record<string, Command<T>>;
+}
+
+/**
+ * Create a command registry
+ */
+export function createCommandRegistry<
+  T extends OptionSchema = OptionSchema,
+>(): CommandRegistry<T> {
+  const commands = new Map<string, Command<T>>();
+  const aliases = new Map<string, string>();
+
+  return {
+    register(command: Command<T>): void {
+      if (commands.has(command.name)) {
+        throw new Error(`Command "${command.name}" is already registered`);
+      }
+
+      commands.set(command.name, command);
+
+      if (command.aliases) {
+        for (const alias of command.aliases) {
+          if (aliases.has(alias) || commands.has(alias)) {
+            throw new Error(`Alias "${alias}" conflicts with existing command or alias`);
+          }
+          aliases.set(alias, command.name);
+        }
+      }
+    },
+
+    get(name: string): Command<T> | undefined {
+      return commands.get(name);
+    },
+
+    resolve(nameOrAlias: string): Command<T> | undefined {
+      // Try direct name first
+      const cmd = commands.get(nameOrAlias);
+      if (cmd) return cmd;
+
+      // Try alias
+      const resolvedName = aliases.get(nameOrAlias);
+      if (resolvedName) {
+        return commands.get(resolvedName);
+      }
+
+      return undefined;
+    },
+
+    has(nameOrAlias: string): boolean {
+      return commands.has(nameOrAlias) || aliases.has(nameOrAlias);
+    },
+
+    list(): Command<T>[] {
+      return Array.from(commands.values());
+    },
+
+    getNames(): string[] {
+      return Array.from(commands.keys());
+    },
+
+    getCommandMap(): Record<string, Command<T>> {
+      return Object.fromEntries(commands);
+    },
+  };
+}

package/src/registry/index.ts

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