@pablozaiden/terminatui 0.1.2 → 0.3.0-beta-1

package/src/core/help.ts

@@ -12,6 +12,8 @@ export interface HelpOptions {
   version?: string;
   /** Command path leading to this command (e.g., ["app", "remote", "add"]) */
   commandPath?: string[];
+  /** Global options schema for this app */
+  globalOptionsSchema?: Record<string, OptionDef>;
 }
 
 /**
@@ -59,38 +61,34 @@ export function formatSubCommands(command: AnyCommand): string {
 }
 
 /**
- * Format options list.
+ * Format an options schema into a help section.
  */
-export function formatOptions(command: AnyCommand): string {
-  if (!command.options || Object.keys(command.options).length === 0) return "";
+export function formatOptionSchema(title: string, schema: Record<string, OptionDef>): string {
+  if (Object.keys(schema).length === 0) return "";
 
-  const entries = Object.entries(command.options).map(([name, defUntyped]) => {
-    const def = defUntyped as OptionDef;
+  const entries = Object.entries(schema).map(([name, def]) => {
     const alias = def.alias ? `-${def.alias}, ` : "    ";
-    const flag = `${alias}--${name}`;
     const required = def.required ? colors.red(" (required)") : "";
     const defaultVal =
       def.default !== undefined ? colors.dim(` [default: ${def.default}]`) : "";
     const enumVals = def.enum ? colors.dim(` [${def.enum.join(" | ")}]`) : "";
-    const typeHint = colors.dim(` <${def.type}>`);
+
+    const noVariant = def.type === "boolean" ? `, --no-${name}` : "";
+    const flag = `${alias}--${name}${noVariant}`;
+    const typeHint = def.type === "boolean" ? "" : colors.dim(` <${def.type}>`);
 
     return `  ${colors.yellow(flag)}${typeHint}${required}\n      ${def.description}${enumVals}${defaultVal}`;
   });
 
-  return [colors.bold("Options:"), ...entries].join("\n");
+  return [colors.bold(title + ":"), ...entries].join("\n");
 }
 
 /**
- * Format global options section (available on all commands).
+ * Format options list.
  */
-export function formatGlobalOptions(): string {
-  const entries = [
-    `  ${colors.yellow("    --log-level")}${colors.dim(" <string>")}\n      Set minimum log level${colors.dim(" [silly | trace | debug | info | warn | error | fatal]")}`,
-    `  ${colors.yellow("    --detailed-logs")}\n      Include timestamp and level prefix in log output`,
-    `  ${colors.yellow("    --no-detailed-logs")}\n      Disable detailed log format`,
-  ];
-
-  return [colors.bold("Global Options:"), ...entries].join("\n");
+export function formatOptions(command: AnyCommand): string {
+  if (!command.options || Object.keys(command.options).length === 0) return "";
+  return formatOptionSchema("Options", command.options as Record<string, OptionDef>);
 }
 
 /**
@@ -154,7 +152,9 @@ export function generateCommandHelp(command: AnyCommand, options: HelpOptions =
   }
 
   // Global options (available on all commands)
-  sections.push(`\n${formatGlobalOptions()}`);
+  if (options.globalOptionsSchema && Object.keys(options.globalOptionsSchema).length > 0) {
+    sections.push(`\n${formatOptionSchema("Global Options", options.globalOptionsSchema)}`);
+  }
 
   // Examples
   const examplesSection = formatExamples(command);
@@ -191,6 +191,12 @@ export function generateAppHelp(commands: AnyCommand[], options: HelpOptions = {
   // Usage
   sections.push(`${colors.bold("Usage:")}\n  ${appName} [command] [options]\n`);
 
+  // Global options
+  if (options.globalOptionsSchema && Object.keys(options.globalOptionsSchema).length > 0) {
+    sections.push(formatOptionSchema("Global Options", options.globalOptionsSchema));
+    sections.push("");
+  }
+
   // Commands
   if (commands.length > 0) {
     const entries = commands.map((cmd) => {

package/src/core/knownCommands.ts

@@ -0,0 +1,13 @@
+export const KNOWN_COMMANDS = {
+  help: "help",
+  settings: "settings",
+  version: "version",
+} as const;
+
+export type KnownCommandName = (typeof KNOWN_COMMANDS)[keyof typeof KNOWN_COMMANDS];
+
+export const RESERVED_TOP_LEVEL_COMMAND_NAMES = new Set<KnownCommandName>([
+  KNOWN_COMMANDS.help,
+  KNOWN_COMMANDS.settings,
+  KNOWN_COMMANDS.version,
+]);

package/src/core/logger.ts

@@ -1,23 +1,24 @@
 import { EventEmitter } from "events";
-import { Logger as TsLogger } from "tslog";
+import { Logger as TsLogger, type IMeta } 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,
+  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 {
+  rawMessage: string;
   message: string;
   level: LogLevel;
   timestamp: Date;
@@ -42,14 +43,12 @@ export interface LoggerConfig {
 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.minLevel = config.minLevel ?? LogLevel.info;
 
     this.tsLogger = this.createTsLogger(this.minLevel);
   }
@@ -63,27 +62,19 @@ export class Logger {
           logMetaMarkup: string,
           logArgs: unknown[],
           logErrors: string[],
-          logMeta: unknown
+          logMeta?: IMeta
         ) => {
           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 level = logMeta?.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");
-          }
+          this.eventEmitter.emit("log", {
+            message: output,
+            rawMessage: simpleLine,
+            level: level,
+            timestamp: new Date(),
+          } satisfies LogEvent);
         },
       },
     });
@@ -97,13 +88,6 @@ export class Logger {
     return () => this.eventEmitter.off("log", listener);
   }
 
-  /**
-   * Enable or disable TUI mode.
-   */
-  setTuiMode(enabled: boolean): void {
-    this.tuiMode = enabled;
-  }
-
   /**
    * Enable or disable detailed log format.
    */
@@ -127,35 +111,48 @@ export class Logger {
   }
 
   // Logging methods
-  silly(...args: unknown[]): void {
-    this.tsLogger.silly(...args);
+    silly(...args: unknown[]): void {
+    this.tsLogger.silly(...asStringArray(args));
   }
 
   trace(...args: unknown[]): void {
-    this.tsLogger.trace(...args);
+    this.tsLogger.trace(...asStringArray(args));
   }
 
   debug(...args: unknown[]): void {
-    this.tsLogger.debug(...args);
+    this.tsLogger.debug(...asStringArray(args));
   }
 
   info(...args: unknown[]): void {
-    this.tsLogger.info(...args);
+    this.tsLogger.info(...asStringArray(args));
   }
 
   warn(...args: unknown[]): void {
-    this.tsLogger.warn(...args);
+    this.tsLogger.warn(...asStringArray(args));
   }
 
   error(...args: unknown[]): void {
-    this.tsLogger.error(...args);
+    this.tsLogger.error(...asStringArray(args));
   }
 
   fatal(...args: unknown[]): void {
-    this.tsLogger.fatal(...args);
+    this.tsLogger.fatal(...asStringArray(args));
   }
 }
 
+function asStringArray(args: unknown[]): string[] {
+  return args.map(arg => {
+    if (typeof arg === "string") {
+      return arg;
+    }
+    try {
+      return JSON.stringify(arg);
+    } catch {
+      return String(arg);
+    }
+  });
+}
+
 /**
  * Create a new logger instance with the given configuration.
  */

package/src/core/registry.ts

@@ -72,7 +72,11 @@ export class CommandRegistry {
    * @param path Array of command names forming the path
    * @returns Object with resolved command, remaining path, and full path
    */
-  resolve(path: string[]): ResolveResult {
+  resolve(path: string[]): {
+    command: AnyCommand | undefined;
+    remainingPath: string[];
+    resolvedPath: string[];
+  } {
     if (path.length === 0) {
       return { command: undefined, remainingPath: [], resolvedPath: [] };
     }
@@ -127,14 +131,3 @@ export class CommandRegistry {
   }
 }
 
-/**
- * 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/tui/TuiApplication.tsx

@@ -1,44 +1,28 @@
-import { createCliRenderer } from "@opentui/core";
-import { createRoot } from "@opentui/react";
-import { Application, type ApplicationConfig } from "../core/application.ts";
+import { createRenderer } from "./adapters/factory.ts";
+import { RendererProvider } from "./context/RendererContext.tsx";
+import { Application, type ModeOptions, type ApplicationConfig, type TuiModeOptions } 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 { TuiRoot } from "./TuiRoot.tsx";
+import { LogLevel } from "../core/logger.ts";
 import { createSettingsCommand } from "../builtins/settings.ts";
+import { KNOWN_COMMANDS } from "../core/knownCommands.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;
-}
+import { AppContext } from "../core/context.ts";
+import { registerAllModals, registerAllScreens } from "./registry.ts";
 
 /**
  * Extended configuration for TUI-enabled applications.
  */
 export interface TuiApplicationConfig extends ApplicationConfig {
-    /** Enable interactive TUI mode */
+    /** Enable TUI mode (when renderer is opentui/ink/default) */
     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.
+ * when running with `--renderer` set to a TUI renderer (or default).
  * 
  * @example
  * ```typescript
@@ -53,19 +37,15 @@ export interface TuiApplicationConfig extends ApplicationConfig {
  *   }
  * }
  * 
- * await new MyApp().run(process.argv.slice(2));
+ * await new MyApp().run();
  * ```
  */
 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;
     }
 
     /**
@@ -74,130 +54,92 @@ export class TuiApplication extends 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();
+    override async run(): Promise<void> {
+        return this.runFromArgs(Bun.argv.slice(2));
+    }
+
+    override async runFromArgs(argv: string[]): Promise<void> {
+        const { globalOptions } = this.parseGlobalOptions(argv);
+
+        const mode = globalOptions["mode"] as ModeOptions ?? "default";
+        const resolvedMode = mode === "default" ? this.defaultMode : mode;
+
+        if (resolvedMode === "cli") {
+            await super.runFromArgs(argv);
+            return;
+        }
+
+        if (!this.enableTui) {
+            throw new Error("TUI mode is disabled for this application");
+        }
+
+        if (resolvedMode === "opentui" || resolvedMode === "ink") {
+            this.applyGlobalOptions(globalOptions);
+
+            await this.runTui(resolvedMode);
             return;
         }
 
-        // Otherwise run CLI mode
-        await super.run(filteredArgs);
+        throw new Error(`Unknown mode '${resolvedMode}'`);
     }
 
     /**
-     * Launch the interactive TUI.
+     * Launch the TUI.
      */
-    async runTui(): Promise<void> {
+    async runTui(rendererType: TuiModeOptions): Promise<void> {
+        await registerAllScreens();
+        await registerAllModals();
+        
         // 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({
+        const renderer = await createRenderer(rendererType, {
             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.render(
+                <RendererProvider renderer={renderer}>
+                    <TuiRoot
+                        name={this.name}
+                        displayName={this.displayName}
+                        version={this.version}
+                        commands={commands}
+                        onExit={handleExit}
+                    />
+                </RendererProvider>
             );
-
-            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");
-            
+            const settings = loadPersistedParameters(this.name, KNOWN_COMMANDS.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;
+                const level = LogLevel[levelStr as keyof typeof LogLevel];
                 if (level !== undefined) {
-                    this.context.logger.setMinLevel(level);
+                    AppContext.current.logger.setMinLevel(level);
                 }
             }
-            
+
             // Apply detailed-logs if set
             if (settings["detailed-logs"] !== undefined) {
-                this.context.logger.setDetailed(Boolean(settings["detailed-logs"]));
+                AppContext.current.logger.setDetailed(Boolean(settings["detailed-logs"]));
             }
         } catch {
             // Silently ignore errors loading settings
@@ -212,15 +154,16 @@ export class TuiApplication extends Application {
         const userCommands = this.registry
             .list()
             .filter((cmd) => {
-                // Exclude version and help from main menu
-                if (cmd.name === "version" || cmd.name === "help") {
+                // Exclude internal/built-in commands from the TUI main menu
+                if (cmd.tuiHidden) {
                     return false;
                 }
-                // Exclude settings if already defined by user (they shouldn't)
-                if (cmd.name === "settings") {
+
+                // Extra safety: keep known internal command names out
+                if (cmd.name === KNOWN_COMMANDS.help || cmd.name === KNOWN_COMMANDS.version || cmd.name === KNOWN_COMMANDS.settings) {
                     return false;
                 }
-                // Include commands that have options or execute methods
+
                 return true;
             });