@pablozaiden/terminatui 0.1.0

package/src/core/command.ts

@@ -0,0 +1,269 @@
+import type { ReactNode } from "react";
+import type { AppContext } from "./context.ts";
+import type { OptionSchema, OptionValues } from "../types/command.ts";
+
+/**
+ * Example for command help documentation.
+ */
+export interface CommandExample {
+  /** The command invocation */
+  command: string;
+  /** Description of what the example does */
+  description: string;
+}
+
+/**
+ * Result of command execution for TUI display.
+ */
+export interface CommandResult {
+  /** Whether the command succeeded */
+  success: boolean;
+  /** Result data to display */
+  data?: unknown;
+  /** Error message if failed */
+  error?: string;
+  /** Summary message */
+  message?: string;
+}
+
+/**
+ * Context passed to command execute methods.
+ * Includes the abort signal for cancellation support.
+ */
+export interface CommandExecutionContext {
+  /** Signal to check for cancellation */
+  signal: AbortSignal;
+}
+
+/**
+ * Error thrown when a command is aborted/cancelled.
+ */
+export class AbortError extends Error {
+  constructor(message = "Command was cancelled") {
+    super(message);
+    this.name = "AbortError";
+  }
+}
+
+/**
+ * Error thrown when configuration validation fails in buildConfig.
+ * This provides a structured way to report validation errors.
+ */
+export class ConfigValidationError extends Error {
+  constructor(
+    message: string,
+    public readonly field?: string,
+    public readonly details?: Record<string, unknown>
+  ) {
+    super(message);
+    this.name = "ConfigValidationError";
+  }
+}
+
+/**
+ * Type alias for any command regardless of its options or config types.
+ * Use this when storing commands in collections or passing them around
+ * without caring about the specific type parameters.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type AnyCommand = Command<any, any>;
+
+/**
+ * Abstract base class for commands.
+ * 
+ * Extend this class to create commands that can run in CLI mode, TUI mode, or both.
+ * The framework enforces that at least one execute method is implemented.
+ * 
+ * Commands can optionally implement `buildConfig` to transform and validate parsed
+ * options into a typed configuration object before execution.
+ * 
+ * @typeParam TOptions - The option schema type (defines what CLI flags are accepted)
+ * @typeParam TConfig - The configuration type passed to execute methods. Defaults to
+ *   OptionValues<TOptions> if buildConfig is not implemented.
+ * 
+ * @example
+ * ```typescript
+ * interface RunConfig {
+ *   repoPath: string;
+ *   iterations: number;
+ * }
+ * 
+ * class RunCommand extends Command<typeof runOptions, RunConfig> {
+ *   name = "run";
+ *   description = "Run the application";
+ *   options = runOptions;
+ * 
+ *   async buildConfig(ctx: AppContext, opts: OptionValues<typeof runOptions>): Promise<RunConfig> {
+ *     const repoPath = path.resolve(opts.repo);
+ *     if (!existsSync(repoPath)) {
+ *       throw new ConfigValidationError(`Repository not found: ${repoPath}`, "repo");
+ *     }
+ *     return { repoPath, iterations: parseInt(opts.iterations) };
+ *   }
+ * 
+ *   async execute(ctx: AppContext, config: RunConfig) {
+ *     // config is already validated
+ *     return { success: true, data: result };
+ *   }
+ * }
+ * ```
+ */
+export abstract class Command<
+  TOptions extends OptionSchema = OptionSchema,
+  TConfig = OptionValues<TOptions>
+> {
+  /** Command name used in CLI */
+  abstract readonly name: string;
+
+  /** Display name for TUI (human-readable, e.g., "Run Evaluation") */
+  displayName?: string;
+
+  /** Short description shown in help */
+  abstract readonly description: string;
+
+  /** Option schema defining accepted arguments */
+  abstract readonly options: TOptions;
+
+  /** Nested subcommands */
+  subCommands?: Command[];
+
+  /** Example usages for help text */
+  examples?: CommandExample[];
+
+  /** Extended description for detailed help */
+  longDescription?: string;
+
+  // TUI-specific properties
+
+  /** Label for the action button (e.g., "Run", "Generate", "Save") */
+  actionLabel?: string;
+
+  /** Whether this command runs immediately without config screen (like "check") */
+  immediateExecution?: boolean;
+
+  /**
+   * Build and validate a configuration object from parsed options.
+   * 
+   * Override this method to transform raw CLI options into a typed configuration
+   * object, and perform any validation that requires the parsed values (e.g.,
+   * checking that a directory exists, validating combinations of options).
+   * 
+   * If not overridden, the parsed options are passed directly to execute methods.
+   * 
+   * @throws ConfigValidationError if validation fails
+   * @returns The validated configuration object
+   */
+  buildConfig?(ctx: AppContext, 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;
+
+  /**
+   * 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;
+
+  /**
+   * Called after execute, even if execute threw an error.
+   * Use for cleanup, logging, etc.
+   * @param error The error thrown by beforeExecute, buildConfig, or execute, if any
+   */
+  afterExecute?(
+    ctx: AppContext,
+    opts: OptionValues<TOptions>,
+    error?: Error
+  ): Promise<void> | void;
+
+  /**
+   * Custom result renderer for TUI.
+   * If not provided, results are displayed as JSON.
+   */
+  renderResult?(result: CommandResult): ReactNode;
+
+  /**
+   * Get content to copy to clipboard.
+   * Called when user presses Ctrl+Y in results panel.
+   * Return undefined if nothing should be copied.
+   */
+  getClipboardContent?(result: CommandResult): string | undefined;
+
+  /**
+   * Called when a config value changes in the TUI.
+   * 
+   * Override this to update related fields when one field changes.
+   * For example, changing "agent" could automatically update "model"
+   * to the default model for that agent.
+   * 
+   * @param key - The key of the field that changed
+   * @param value - The new value
+   * @param allValues - All current config values (including the new value)
+   * @returns Updated values to merge, or undefined if no changes needed
+   * 
+   * @example
+   * ```typescript
+   * onConfigChange(key: string, value: unknown, allValues: Record<string, unknown>) {
+   *   if (key === "agent") {
+   *     return { model: getDefaultModelForAgent(value as string) };
+   *   }
+   *   return undefined;
+   * }
+   * ```
+   */
+  onConfigChange?(
+    key: string,
+    value: unknown,
+    allValues: Record<string, unknown>
+  ): Record<string, unknown> | undefined;
+
+  /**
+   * Check if this command supports CLI mode.
+   */
+  supportsCli(): boolean {
+    return true;
+  }
+
+  /**
+   * Check if this command supports TUI mode.
+   */
+  supportsTui(): boolean {
+    return true;
+  }
+
+  /**
+   * Check if this command implements buildConfig.
+   */
+  hasConfig(): boolean {
+    return typeof this.buildConfig === "function";
+  }
+
+  /**
+   * Validate the command.
+   * Called by the framework during registration.
+   */
+  validate(): void {
+    // No validation needed - execute is abstract and required
+  }
+
+  /**
+   * Get a subcommand by name.
+   */
+  getSubCommand(name: string): Command | undefined {
+    return this.subCommands?.find((cmd) => cmd.name === name);
+  }
+
+  /**
+   * Check if this command has subcommands.
+   */
+  hasSubCommands(): boolean {
+    return (this.subCommands?.length ?? 0) > 0;
+  }
+}

package/src/core/context.ts

@@ -0,0 +1,112 @@
+import { Logger, createLogger, type LoggerConfig } from "./logger.ts";
+
+/**
+ * Application configuration stored in context.
+ */
+export interface AppConfig {
+  /** Application name */
+  name: string;
+  /** Application version */
+  version: string;
+  /** Additional configuration values */
+  [key: string]: unknown;
+}
+
+/**
+ * AppContext is the central container for application-wide services and state.
+ * It holds the logger, configuration, and a generic service registry.
+ * 
+ * Access the current context via `AppContext.current` or receive it
+ * as a parameter in command execute methods.
+ */
+export class AppContext {
+  private static _current: AppContext | null = null;
+  private readonly services = new Map<string, unknown>();
+
+  /** The application logger */
+  public readonly logger: Logger;
+
+  /** The application configuration */
+  public readonly config: AppConfig;
+
+  constructor(config: AppConfig, loggerConfig?: LoggerConfig) {
+    this.config = config;
+    this.logger = createLogger(loggerConfig);
+  }
+
+  /**
+   * Get the current application context.
+   * Throws if no context has been set.
+   */
+  static get current(): AppContext {
+    if (!AppContext._current) {
+      throw new Error(
+        "AppContext.current accessed before initialization. " +
+        "Ensure Application.run() has been called."
+      );
+    }
+    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;
+  }
+
+  /**
+   * Clear the current context.
+   * Useful for testing.
+   */
+  static clearCurrent(): void {
+    AppContext._current = null;
+  }
+
+  /**
+   * Register a service in the context.
+   * @param name Unique service identifier
+   * @param service The service instance
+   */
+  setService<T>(name: string, service: T): void {
+    this.services.set(name, service);
+  }
+
+  /**
+   * Get a service from the context.
+   * @param name Service identifier
+   * @returns The service instance or undefined
+   */
+  getService<T>(name: string): T | undefined {
+    return this.services.get(name) as T | undefined;
+  }
+
+  /**
+   * Get a service, throwing if not found.
+   * @param name Service identifier
+   * @returns The service instance
+   */
+  requireService<T>(name: string): T {
+    const service = this.getService<T>(name);
+    if (service === undefined) {
+      throw new Error(`Service '${name}' not found in AppContext`);
+    }
+    return service;
+  }
+
+  /**
+   * Check if a service is registered.
+   * @param name Service identifier
+   */
+  hasService(name: string): boolean {
+    return this.services.has(name);
+  }
+}

package/src/core/help.ts

@@ -0,0 +1,214 @@
+import { type AnyCommand } from "./command.ts";
+import type { OptionDef } from "../types/command.ts";
+import { colors } from "../cli/output/colors.ts";
+
+/**
+ * Options for generating help text.
+ */
+export interface HelpOptions {
+  /** Application name (used in usage line) */
+  appName?: string;
+  /** Application version (shown in header) */
+  version?: string;
+  /** Command path leading to this command (e.g., ["app", "remote", "add"]) */
+  commandPath?: string[];
+}
+
+/**
+ * Format the usage line for a command.
+ */
+export function formatUsage(command: AnyCommand, options: HelpOptions = {}): string {
+  const { appName = "cli", commandPath = [] } = options;
+
+  const parts = [appName, ...commandPath];
+
+  // Add command name if not already in path
+  if (commandPath.length === 0 || commandPath[commandPath.length - 1] !== command.name) {
+    parts.push(command.name);
+  }
+
+  if (command.hasSubCommands()) {
+    parts.push("[command]");
+  }
+
+  if (command.options && Object.keys(command.options).length > 0) {
+    parts.push("[options]");
+  }
+
+  return parts.join(" ");
+}
+
+/**
+ * Format subcommands list.
+ */
+export function formatSubCommands(command: AnyCommand): string {
+  if (!command.subCommands?.length) return "";
+
+  const entries = command.subCommands.map((cmd) => {
+    const modes: string[] = [];
+    if (cmd.supportsCli()) modes.push("cli");
+    if (cmd.supportsTui()) modes.push("tui");
+    const modeHint = modes.length ? colors.dim(` [${modes.join("/")}]`) : "";
+
+    return `  ${colors.cyan(cmd.name)}${modeHint}  ${cmd.description}`;
+  });
+
+  if (entries.length === 0) return "";
+
+  return [colors.bold("Commands:"), ...entries].join("\n");
+}
+
+/**
+ * Format options list.
+ */
+export function formatOptions(command: AnyCommand): string {
+  if (!command.options || Object.keys(command.options).length === 0) return "";
+
+  const entries = Object.entries(command.options).map(([name, defUntyped]) => {
+    const def = defUntyped as OptionDef;
+    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}>`);
+
+    return `  ${colors.yellow(flag)}${typeHint}${required}\n      ${def.description}${enumVals}${defaultVal}`;
+  });
+
+  return [colors.bold("Options:"), ...entries].join("\n");
+}
+
+/**
+ * Format global options section (available on all commands).
+ */
+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");
+}
+
+/**
+ * Format examples list.
+ */
+export function formatExamples(command: AnyCommand): string {
+  if (!command.examples?.length) return "";
+
+  const entries = command.examples.map(
+    (ex) => `  ${colors.dim("$")} ${ex.command}\n      ${colors.dim(ex.description)}`
+  );
+
+  return [colors.bold("Examples:"), ...entries].join("\n");
+}
+
+/**
+ * Generate full help text for a command.
+ * 
+ * @param command The command to generate help for
+ * @param options Help generation options
+ * @returns Formatted help text
+ */
+export function generateCommandHelp(command: AnyCommand, options: HelpOptions = {}): string {
+  const { appName = "cli", version } = options;
+  const sections: string[] = [];
+
+  // Header with version
+  if (version) {
+    sections.push(`${colors.bold(appName)} ${colors.dim(`v${version}`)}\n`);
+  }
+
+  // Description
+  sections.push(command.description);
+
+  // Long description if available
+  if (command.longDescription) {
+    sections.push(`\n${command.longDescription}`);
+  }
+
+  // Execution modes
+  const modes: string[] = [];
+  if (command.supportsCli()) modes.push("CLI");
+  if (command.supportsTui()) modes.push("TUI");
+  if (modes.length > 0) {
+    sections.push(`\n${colors.dim(`Supports: ${modes.join(", ")}`)}`);
+  }
+
+  // Usage
+  sections.push(`\n${colors.bold("Usage:")}\n  ${formatUsage(command, options)}`);
+
+  // Subcommands
+  const subCommandsSection = formatSubCommands(command);
+  if (subCommandsSection) {
+    sections.push(`\n${subCommandsSection}`);
+  }
+
+  // Options
+  const optionsSection = formatOptions(command);
+  if (optionsSection) {
+    sections.push(`\n${optionsSection}`);
+  }
+
+  // Global options (available on all commands)
+  sections.push(`\n${formatGlobalOptions()}`);
+
+  // Examples
+  const examplesSection = formatExamples(command);
+  if (examplesSection) {
+    sections.push(`\n${examplesSection}`);
+  }
+
+  // Help hint
+  if (command.hasSubCommands()) {
+    sections.push(
+      `\n${colors.dim(`Run '${appName} ${command.name} <command> help' for more information on a command.`)}`
+    );
+  }
+
+  return sections.join("\n");
+}
+
+/**
+ * Generate help text for the application root (list of all commands).
+ * 
+ * @param commands List of top-level commands
+ * @param options Help generation options
+ * @returns Formatted help text
+ */
+export function generateAppHelp(commands: AnyCommand[], options: HelpOptions = {}): string {
+  const { appName = "cli", version } = options;
+  const sections: string[] = [];
+
+  // Header
+  if (version) {
+    sections.push(`${colors.bold(appName)} ${colors.dim(`v${version}`)}\n`);
+  }
+
+  // Usage
+  sections.push(`${colors.bold("Usage:")}\n  ${appName} [command] [options]\n`);
+
+  // Commands
+  if (commands.length > 0) {
+    const entries = commands.map((cmd) => {
+      const modes: string[] = [];
+      if (cmd.supportsCli()) modes.push("cli");
+      if (cmd.supportsTui()) modes.push("tui");
+      const modeHint = modes.length ? colors.dim(` [${modes.join("/")}]`) : "";
+
+      return `  ${colors.cyan(cmd.name)}${modeHint}  ${cmd.description}`;
+    });
+
+    sections.push([colors.bold("Commands:"), ...entries].join("\n"));
+  }
+
+  // Help hint
+  sections.push(
+    `\n${colors.dim(`Run '${appName} <command> help' for more information on a command.`)}`
+  );
+
+  return sections.join("\n");
+}

package/src/core/index.ts

@@ -0,0 +1,15 @@
+// Core exports
+export { Application, type ApplicationConfig, type ApplicationHooks, type GlobalOptions } from "./application.ts";
+export { AppContext, type AppConfig } from "./context.ts";
+export { Command, ConfigValidationError, AbortError, type AnyCommand, type CommandExample, type CommandResult, type CommandExecutionContext } from "./command.ts";
+export { CommandRegistry, type ResolveResult } from "./registry.ts";
+export { Logger, createLogger, LogLevel, type LoggerConfig, type LogEvent } from "./logger.ts";
+export {
+  generateCommandHelp,
+  generateAppHelp,
+  formatUsage,
+  formatSubCommands,
+  formatOptions,
+  formatExamples,
+  type HelpOptions,
+} from "./help.ts";