@pablozaiden/terminatui 0.2.0 → 0.3.0

package/src/core/command.ts

@@ -1,5 +1,4 @@
 import type { ReactNode } from "react";
-import type { AppContext } from "./context.ts";
 import type { OptionSchema, OptionValues } from "../types/command.ts";
 
 /**
@@ -93,7 +92,7 @@ export type AnyCommand = Command<any, any>;
  *   description = "Run the application";
  *   options = runOptions;
  * 
- *   async buildConfig(ctx: AppContext, opts: OptionValues<typeof runOptions>): Promise<RunConfig> {
+ *   async buildConfig(opts: OptionValues<typeof runOptions>): Promise<RunConfig> {
  *     const repoPath = path.resolve(opts.repo);
  *     if (!existsSync(repoPath)) {
  *       throw new ConfigValidationError(`Repository not found: ${repoPath}`, "repo");
@@ -101,7 +100,7 @@ export type AnyCommand = Command<any, any>;
  *     return { repoPath, iterations: parseInt(opts.iterations) };
  *   }
  * 
- *   async execute(ctx: AppContext, config: RunConfig) {
+ *   async execute(config: RunConfig) {
  *     // config is already validated
  *     return { success: true, data: result };
  *   }
@@ -141,6 +140,9 @@ export abstract class Command<
   /** Whether this command runs immediately without config screen (like "check") */
   immediateExecution?: boolean;
 
+  /** If true, this command should not appear in the TUI command list. */
+  tuiHidden?: boolean;
+
   /**
    * Build and validate a configuration object from parsed options.
    * 
@@ -153,24 +155,23 @@ export abstract class Command<
    * @throws ConfigValidationError if validation fails
    * @returns The validated configuration object
    */
-  buildConfig?(ctx: AppContext, opts: OptionValues<TOptions>): Promise<TConfig> | TConfig;
+  buildConfig?(opts: OptionValues<TOptions>): Promise<TConfig> | TConfig;
 
   /**
    * Execute the command.
    * The framework will call this method for both CLI and TUI modes.
    * 
-   * @param ctx - Application context
    * @param config - The configuration object (from buildConfig, or raw options if buildConfig is not implemented)
    * @param execCtx - Execution context with abort signal for cancellation support
    * @returns Optional result for display in TUI results panel
    */
-  abstract execute(ctx: AppContext, config: TConfig, execCtx?: CommandExecutionContext): Promise<CommandResult | void> | CommandResult | void;
+  abstract execute(config: TConfig, execCtx?: CommandExecutionContext): Promise<CommandResult | void> | CommandResult | void;
 
   /**
    * Called before buildConfig. Use for early validation, resource acquisition, etc.
    * If this throws, buildConfig and execute will not be called but afterExecute will still run.
    */
-  beforeExecute?(ctx: AppContext, opts: OptionValues<TOptions>): Promise<void> | void;
+  beforeExecute?(opts: OptionValues<TOptions>): Promise<void> | void;
 
   /**
    * Called after execute, even if execute threw an error.
@@ -178,7 +179,6 @@ export abstract class Command<
    * @param error The error thrown by beforeExecute, buildConfig, or execute, if any
    */
   afterExecute?(
-    ctx: AppContext,
     opts: OptionValues<TOptions>,
     error?: Error
   ): Promise<void> | void;
@@ -250,7 +250,24 @@ export abstract class Command<
    * Called by the framework during registration.
    */
   validate(): void {
-    // No validation needed - execute is abstract and required
+    this.validateSubCommands();
+  }
+
+  private validateSubCommands(): void {
+    if (!this.subCommands || this.subCommands.length === 0) {
+      return;
+    }
+
+    const names = new Set<string>();
+    for (const subCommand of this.subCommands) {
+      if (names.has(subCommand.name)) {
+        throw new Error(
+          `Duplicate subcommand '${subCommand.name}' under '${this.name}'`
+        );
+      }
+      names.add(subCommand.name);
+      subCommand.validate();
+    }
   }
 
   /**

package/src/core/context.ts

@@ -1,4 +1,5 @@
-import { Logger, createLogger, type LoggerConfig } from "./logger.ts";
+import { type Logger, createLogger, type LoggerConfig, type LogEvent } from "./logger.ts";
+import { appendFileSync } from "fs";
 
 /**
  * Application configuration stored in context.
@@ -8,10 +9,14 @@ export interface AppConfig {
   name: string;
   /** Application version */
   version: string;
+  /** Log target */
+  logTarget?: LogTarget[];
   /** Additional configuration values */
   [key: string]: unknown;
 }
 
+export type LogTarget = "memory" | "file" | "none";
+
 /**
  * AppContext is the central container for application-wide services and state.
  * It holds the logger, configuration, and a generic service registry.
@@ -22,6 +27,7 @@ export interface AppConfig {
 export class AppContext {
   private static _current: AppContext | null = null;
   private readonly services = new Map<string, unknown>();
+  private readonly startTime = Date.now();
 
   /** The application logger */
   public readonly logger: Logger;
@@ -29,9 +35,27 @@ export class AppContext {
   /** The application configuration */
   public readonly config: AppConfig;
 
+  public logTarget: LogTarget[] = [];
+
+  public readonly logHistory: LogEvent[] = [];
+
   constructor(config: AppConfig, loggerConfig?: LoggerConfig) {
     this.config = config;
     this.logger = createLogger(loggerConfig);
+    this.logTarget = config.logTarget ?? ["none"];
+
+    this.logger.onLogEvent((event) => {
+      if (this.logTarget.includes("memory")) {
+        this.logHistory.push(event);
+      }
+
+      if (this.logTarget.includes("file")) {
+        const logFileName = `${this.config.name}-${this.startTime}.log`;
+        const logLine = event.message + "\n";
+
+        appendFileSync(logFileName, logLine);
+      }
+    });
   }
 
   /**
@@ -40,35 +64,22 @@ export class AppContext {
    */
   static get current(): AppContext {
     if (!AppContext._current) {
-      throw new Error(
-        "AppContext.current accessed before initialization. " +
-        "Ensure Application.run() has been called."
-      );
+      // return a fake context to avoid optional chaining everywhere
+      return new AppContext({ name: "unknown", version: "0.0.0" });
     }
     return AppContext._current;
   }
 
-  /**
-   * Check if a current context exists.
-   */
-  static hasCurrent(): boolean {
-    return AppContext._current !== null;
-  }
-
   /**
    * Set the current application context.
    * Called internally by Application.
    */
   static setCurrent(context: AppContext): void {
-    AppContext._current = context;
-  }
+    if (!context) {
+      throw new Error("Cannot set null or undefined context");
+    }
 
-  /**
-   * Clear the current context.
-   * Useful for testing.
-   */
-  static clearCurrent(): void {
-    AppContext._current = null;
+    AppContext._current = context;
   }
 
   /**

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/index.ts

@@ -1,137 +1,22 @@
-// 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";
+export * from "./builtins/help.ts";
+export * from "./builtins/settings.ts";
+export * from "./builtins/version.ts";
+
+export * from "./cli/parser.ts";
+export * from "./cli/output/colors.ts";
+
+export * from "./core/application.ts";
+export * from "./core/command.ts";
+export * from "./core/context.ts";
+export * from "./core/help.ts";
+export * from "./core/knownCommands.ts";
+export * from "./core/logger.ts";
+export * from "./core/registry.ts";
+
+export * from "./tui/TuiApplication.tsx";
+export * from "./tui/TuiRoot.tsx";
+export * from "./tui/registry.ts";
+export * from "./tui/theme.ts";
+export * from "./types/command.ts";
+
+export * from "./tui/components/JsonHighlight.tsx";