@pablozaiden/terminatui 0.1.0

package/src/builtins/help.ts

@@ -0,0 +1,85 @@
+import { Command, type AnyCommand } from "../core/command.ts";
+import type { AppContext } from "../core/context.ts";
+import { generateCommandHelp, generateAppHelp } from "../core/help.ts";
+import type { OptionSchema } from "../types/command.ts";
+
+/**
+ * Built-in help command that is auto-injected as a subcommand into all commands.
+ * When invoked, it displays help for the parent command.
+ * 
+ * This command is created internally by the Application class and should not
+ * be instantiated directly.
+ */
+export class HelpCommand extends Command<OptionSchema> {
+  readonly name = "help";
+  readonly description = "Show help for this command";
+  readonly options = {} as const;
+
+  private parentCommand: AnyCommand | null = null;
+  private allCommands: AnyCommand[] = [];
+  private appName: string;
+  private appVersion: string;
+
+  constructor(config: {
+    parentCommand?: AnyCommand;
+    allCommands?: AnyCommand[];
+    appName: string;
+    appVersion: string;
+  }) {
+    super();
+    this.parentCommand = config.parentCommand ?? null;
+    this.allCommands = config.allCommands ?? [];
+    this.appName = config.appName;
+    this.appVersion = config.appVersion;
+  }
+
+  override async execute(_ctx: AppContext): Promise<void> {
+    let helpText: string;
+
+    if (this.parentCommand) {
+      // Show help for the parent command
+      helpText = generateCommandHelp(this.parentCommand, {
+        appName: this.appName,
+        version: this.appVersion,
+      });
+    } else {
+      // Show help for the entire application
+      helpText = generateAppHelp(this.allCommands, {
+        appName: this.appName,
+        version: this.appVersion,
+      });
+    }
+
+    console.log(helpText);
+  }
+}
+
+/**
+ * Create a help command for a specific parent command.
+ */
+export function createHelpCommandForParent(
+  parentCommand: AnyCommand,
+  appName: string,
+  appVersion: string
+): HelpCommand {
+  return new HelpCommand({
+    parentCommand,
+    appName,
+    appVersion,
+  });
+}
+
+/**
+ * Create a help command for the application root.
+ */
+export function createRootHelpCommand(
+  allCommands: AnyCommand[],
+  appName: string,
+  appVersion: string
+): HelpCommand {
+  return new HelpCommand({
+    allCommands,
+    appName,
+    appVersion,
+  });
+}

package/src/builtins/index.ts

@@ -0,0 +1,4 @@
+export { HelpCommand, createHelpCommandForParent, createRootHelpCommand } from "./help.ts";
+export { VersionCommand, createVersionCommand, formatVersion } from "./version.ts";
+export { SettingsCommand, createSettingsCommand } from "./settings.ts";
+export type { VersionConfig } from "./version.ts";

package/src/builtins/settings.ts

@@ -0,0 +1,106 @@
+import { Command } from "../core/command.ts";
+import type { AppContext } from "../core/context.ts";
+import { LogLevel } from "../core/logger.ts";
+import type { OptionSchema, OptionValues } from "../types/command.ts";
+import type { CommandResult } from "../core/command.ts";
+
+/**
+ * Options schema for the settings command.
+ */
+const settingsOptions = {
+  "log-level": {
+    type: "string",
+    description: "Minimum log level to emit",
+    default: "info",
+    enum: ["silly", "trace", "debug", "info", "warn", "error", "fatal"],
+    label: "Log Level",
+    order: 1,
+  },
+  "detailed-logs": {
+    type: "boolean",
+    description: "Include timestamp and level in log output",
+    default: false,
+    label: "Detailed Logs",
+    order: 2,
+  },
+} as const satisfies OptionSchema;
+
+type SettingsOptions = OptionValues<typeof settingsOptions>;
+
+/**
+ * Parsed settings configuration.
+ */
+interface SettingsConfig {
+  logLevel: LogLevel;
+  detailedLogs: boolean;
+}
+
+/**
+ * Map of string log level names to LogLevel enum values.
+ */
+const logLevelMap: Record<string, LogLevel> = {
+  silly: LogLevel.Silly,
+  trace: LogLevel.Trace,
+  debug: LogLevel.Debug,
+  info: LogLevel.Info,
+  warn: LogLevel.Warn,
+  error: LogLevel.Error,
+  fatal: LogLevel.Fatal,
+};
+
+/**
+ * Parse a string log level to the LogLevel enum.
+ */
+function parseLogLevel(value?: string): LogLevel {
+  if (!value) return LogLevel.Info;
+  const level = logLevelMap[value.toLowerCase()];
+  return level ?? LogLevel.Info;
+}
+
+/**
+ * Built-in settings command for configuring logging.
+ * 
+ * This command allows users to configure the log level and detailed logging
+ * format at runtime. It's automatically registered by TuiApplication.
+ * 
+ * In CLI mode, these settings are typically passed as global options:
+ * --log-level <level> and --detailed-logs
+ * 
+ * In TUI mode, this command provides a UI for configuring these settings.
+ */
+export class SettingsCommand extends Command<typeof settingsOptions, SettingsConfig> {
+  readonly name = "settings";
+  override readonly displayName = "Settings";
+  readonly description = "Configure logging level and output format";
+  readonly options = settingsOptions;
+
+  override readonly actionLabel = "Save Settings";
+  override readonly immediateExecution = false;
+
+  override buildConfig(_ctx: AppContext, opts: SettingsOptions): SettingsConfig {
+    const logLevel = parseLogLevel(opts["log-level"] as string | undefined);
+    const detailedLogs = Boolean(opts["detailed-logs"]);
+
+    return { logLevel, detailedLogs };
+  }
+
+  override async execute(ctx: AppContext, config: SettingsConfig): Promise<CommandResult> {
+    this.applySettings(ctx, config);
+    return {
+      success: true,
+      message: `Logging set to ${LogLevel[config.logLevel]}${config.detailedLogs ? " with detailed format" : ""}`,
+    };
+  }
+
+  private applySettings(ctx: AppContext, config: SettingsConfig): void {
+    ctx.logger.setMinLevel(config.logLevel);
+    ctx.logger.setDetailed(config.detailedLogs);
+  }
+}
+
+/**
+ * Create the built-in settings command.
+ */
+export function createSettingsCommand(): SettingsCommand {
+  return new SettingsCommand();
+}

package/src/builtins/version.ts

@@ -0,0 +1,72 @@
+import { Command } from "../core/command.ts";
+import type { AppContext } from "../core/context.ts";
+import { colors } from "../cli/output/colors.ts";
+import type { OptionSchema } from "../types/command.ts";
+
+/**
+ * Configuration for version command.
+ */
+export interface VersionConfig {
+  /** Application name */
+  appName: string;
+  /** Application version (e.g., "1.0.0") */
+  appVersion: string;
+  /** Optional commit hash for version display */
+  commitHash?: string;
+}
+
+/**
+ * Format version string with optional commit hash.
+ * If commitHash is empty or undefined, shows "(dev)".
+ */
+export function formatVersion(version: string, commitHash?: string): string {
+  const hashPart = commitHash && commitHash.length > 0 
+    ? commitHash.substring(0, 7) 
+    : "(dev)";
+  return `${version} - ${hashPart}`;
+}
+
+/**
+ * Built-in version command that displays the application version.
+ * Automatically registered at the top level by the Application class.
+ */
+export class VersionCommand extends Command<OptionSchema> {
+  readonly name = "version";
+  readonly description = "Show version information";
+  readonly options = {} as const;
+  readonly aliases = ["--version", "-v"];
+
+  private appName: string;
+  private appVersion: string;
+  private commitHash?: string;
+
+  constructor(config: VersionConfig) {
+    super();
+    this.appName = config.appName;
+    this.appVersion = config.appVersion;
+    this.commitHash = config.commitHash;
+  }
+
+  /**
+   * Get the formatted version string.
+   */
+  getFormattedVersion(): string {
+    return formatVersion(this.appVersion, this.commitHash);
+  }
+
+  override async execute(_ctx: AppContext): Promise<void> {
+    const versionDisplay = this.getFormattedVersion();
+    console.log(`${colors.bold(this.appName)} ${colors.dim(`v${versionDisplay}`)}`);
+  }
+}
+
+/**
+ * Create a version command for the application.
+ */
+export function createVersionCommand(
+  appName: string,
+  appVersion: string,
+  commitHash?: string
+): VersionCommand {
+  return new VersionCommand({ appName, appVersion, commitHash });
+}

package/src/cli/help.ts

@@ -0,0 +1,174 @@
+import type { Command, OptionDef } from "../types/command.ts";
+import { colors } from "./output/colors.ts";
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type AnyCommand = Command<any, any>;
+
+/**
+ * Format usage line for a command
+ */
+export function formatUsage(
+  command: AnyCommand,
+  appName = "cli"
+): string {
+  const parts = [appName, command.name];
+
+  if (command.subcommands && Object.keys(command.subcommands).length > 0) {
+    parts.push("[command]");
+  }
+
+  if (command.options && Object.keys(command.options).length > 0) {
+    parts.push("[options]");
+  }
+
+  return parts.join(" ");
+}
+
+/**
+ * Format subcommands list
+ */
+export function formatCommands(command: AnyCommand): string {
+  if (!command.subcommands) return "";
+
+  const entries = Object.entries(command.subcommands)
+    .filter(([, cmd]) => !cmd.hidden)
+    .map(([name, cmd]) => {
+      const aliases = cmd.aliases?.length ? ` (${cmd.aliases.join(", ")})` : "";
+      return `  ${colors.cyan(name)}${aliases}  ${cmd.description}`;
+    });
+
+  if (entries.length === 0) return "";
+
+  return ["Commands:", ...entries].join("\n");
+}
+
+/**
+ * Format options list
+ */
+export function formatOptions(command: AnyCommand): string {
+  if (!command.options) 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("*") : "";
+    const defaultVal = def.default !== undefined ? ` (default: ${def.default})` : "";
+    const enumVals = def.enum ? ` [${def.enum.join("|")}]` : "";
+
+    return `  ${colors.yellow(flag)}${required}  ${def.description}${enumVals}${defaultVal}`;
+  });
+
+  if (entries.length === 0) return "";
+
+  return ["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 ["Examples:", ...entries].join("\n");
+}
+
+/**
+ * Format global options (log-level, detailed-logs)
+ */
+export function formatGlobalOptions(): string {
+  const entries = [
+    `  ${colors.yellow("--log-level")} <level>  Set log level [silly|trace|debug|info|warn|error|fatal]`,
+    `  ${colors.yellow("--detailed-logs")}      Enable detailed log output`,
+    `  ${colors.yellow("--no-detailed-logs")}   Disable detailed log output`,
+  ];
+
+  return ["Global Options:", ...entries].join("\n");
+}
+
+/**
+ * Get command summary line
+ */
+export function getCommandSummary(command: AnyCommand): string {
+  const aliases = command.aliases?.length ? ` (${command.aliases.join(", ")})` : "";
+  return `${command.name}${aliases}: ${command.description}`;
+}
+
+/**
+ * Generate full help text for a command
+ */
+export function generateHelp(
+  command: AnyCommand,
+  options: { appName?: string; version?: string } = {}
+): string {
+  const { appName = "cli", version } = options;
+  const sections: string[] = [];
+
+  // Header
+  if (version) {
+    sections.push(`${colors.bold(appName)} ${colors.dim(`v${version}`)}`);
+  }
+
+  // Description
+  sections.push(command.description);
+
+  // Usage
+  sections.push(`\n${colors.bold("Usage:")}\n  ${formatUsage(command, appName)}`);
+
+  // Commands
+  const commandsSection = formatCommands(command);
+  if (commandsSection) {
+    sections.push(`\n${commandsSection}`);
+  }
+
+  // Options
+  const optionsSection = formatOptions(command);
+  if (optionsSection) {
+    sections.push(`\n${optionsSection}`);
+  }
+
+  // Examples
+  const examplesSection = formatExamples(command);
+  if (examplesSection) {
+    sections.push(`\n${examplesSection}`);
+  }
+
+  return sections.join("\n");
+}
+
+/**
+ * Generate help text for a specific command (includes global options)
+ */
+export function generateCommandHelp(
+  command: AnyCommand,
+  appName = "cli"
+): string {
+  const sections: string[] = [];
+
+  // Description
+  sections.push(command.description);
+
+  // Usage
+  sections.push(`\n${colors.bold("Usage:")}\n  ${formatUsage(command, appName)}`);
+
+  // Options
+  const optionsSection = formatOptions(command);
+  if (optionsSection) {
+    sections.push(`\n${optionsSection}`);
+  }
+
+  // Global Options
+  sections.push(`\n${formatGlobalOptions()}`);
+
+  // Examples
+  const examplesSection = formatExamples(command);
+  if (examplesSection) {
+    sections.push(`\n${examplesSection}`);
+  }
+
+  return sections.join("\n");
+}

package/src/cli/index.ts

@@ -0,0 +1,3 @@
+export * from "./parser.ts";
+export * from "./help.ts";
+export * from "./output/index.ts";

package/src/cli/output/colors.ts

@@ -0,0 +1,74 @@
+// ANSI escape codes
+const RESET = "\x1b[0m";
+const BOLD = "\x1b[1m";
+const DIM = "\x1b[2m";
+const ITALIC = "\x1b[3m";
+const UNDERLINE = "\x1b[4m";
+const STRIKETHROUGH = "\x1b[9m";
+
+const RED = "\x1b[31m";
+const GREEN = "\x1b[32m";
+const YELLOW = "\x1b[33m";
+const BLUE = "\x1b[34m";
+const MAGENTA = "\x1b[35m";
+const CYAN = "\x1b[36m";
+const WHITE = "\x1b[37m";
+const GRAY = "\x1b[90m";
+
+const BG_RED = "\x1b[41m";
+const BG_GREEN = "\x1b[42m";
+const BG_YELLOW = "\x1b[43m";
+const BG_BLUE = "\x1b[44m";
+
+/**
+ * Check if terminal supports colors
+ */
+export function supportsColors(): boolean {
+  if (typeof process === "undefined") return false;
+  if (process.env["NO_COLOR"]) return false;
+  if (process.env["FORCE_COLOR"]) return true;
+  if (process.stdout?.isTTY) return true;
+  return false;
+}
+
+function wrap(code: string, text: string): string {
+  if (!supportsColors()) return text;
+  return `${code}${text}${RESET}`;
+}
+
+/**
+ * Color utilities for terminal output
+ */
+export const colors = {
+  // Basic colors
+  red: (text: string) => wrap(RED, text),
+  green: (text: string) => wrap(GREEN, text),
+  yellow: (text: string) => wrap(YELLOW, text),
+  blue: (text: string) => wrap(BLUE, text),
+  magenta: (text: string) => wrap(MAGENTA, text),
+  cyan: (text: string) => wrap(CYAN, text),
+  white: (text: string) => wrap(WHITE, text),
+  gray: (text: string) => wrap(GRAY, text),
+
+  // Styles
+  bold: (text: string) => wrap(BOLD, text),
+  dim: (text: string) => wrap(DIM, text),
+  italic: (text: string) => wrap(ITALIC, text),
+  underline: (text: string) => wrap(UNDERLINE, text),
+  strikethrough: (text: string) => wrap(STRIKETHROUGH, text),
+
+  // Background colors
+  bgRed: (text: string) => wrap(BG_RED, text),
+  bgGreen: (text: string) => wrap(BG_GREEN, text),
+  bgYellow: (text: string) => wrap(BG_YELLOW, text),
+  bgBlue: (text: string) => wrap(BG_BLUE, text),
+
+  // Semantic colors
+  success: (text: string) => wrap(GREEN, `✓ ${text}`),
+  error: (text: string) => wrap(RED, `✗ ${text}`),
+  warning: (text: string) => wrap(YELLOW, `⚠ ${text}`),
+  info: (text: string) => wrap(BLUE, `ℹ ${text}`),
+
+  // Reset
+  reset: RESET,
+};

package/src/cli/output/index.ts

@@ -0,0 +1,2 @@
+export * from "./colors.ts";
+export * from "./table.ts";

package/src/cli/output/table.ts

@@ -0,0 +1,141 @@
+/**
+ * Column configuration for tables
+ */
+export interface ColumnConfig {
+  key: string;
+  header?: string;
+  width?: number;
+  align?: "left" | "right" | "center";
+  formatter?: (value: unknown) => string;
+}
+
+export interface TableOptions {
+  columns?: (string | ColumnConfig)[];
+  showHeaders?: boolean;
+  border?: boolean;
+}
+
+/**
+ * Create a formatted table string
+ */
+export function table<T extends Record<string, unknown>>(
+  data: T[],
+  options: TableOptions = {}
+): string {
+  if (data.length === 0) return "";
+
+  const { showHeaders = true } = options;
+
+  // Determine columns
+  const columns: ColumnConfig[] = options.columns
+    ? options.columns.map((col) =>
+        typeof col === "string" ? { key: col, header: col } : col
+      )
+    : Object.keys(data[0] ?? {}).map((key) => ({ key, header: key }));
+
+  // Calculate column widths
+  const widths = columns.map((col) => {
+    const headerWidth = (col.header ?? col.key).length;
+    const maxDataWidth = Math.max(
+      ...data.map((row) => {
+        const value = row[col.key];
+        const formatted = col.formatter ? col.formatter(value) : String(value ?? "");
+        return formatted.length;
+      })
+    );
+    return col.width ?? Math.max(headerWidth, maxDataWidth);
+  });
+
+  // Format a row
+  const formatRow = (values: string[]): string => {
+    return values
+      .map((val, i) => {
+        const width = widths[i] ?? 10;
+        const col = columns[i];
+        const align = col?.align ?? "left";
+
+        if (align === "right") {
+          return val.padStart(width);
+        } else if (align === "center") {
+          const leftPad = Math.floor((width - val.length) / 2);
+          return val.padStart(leftPad + val.length).padEnd(width);
+        }
+        return val.padEnd(width);
+      })
+      .join("  ");
+  };
+
+  const rows: string[] = [];
+
+  // Add header
+  if (showHeaders) {
+    const headers = columns.map((col) => col.header ?? col.key);
+    rows.push(formatRow(headers));
+    rows.push(widths.map((w) => "-".repeat(w)).join("  "));
+  }
+
+  // Add data rows
+  for (const row of data) {
+    const values = columns.map((col) => {
+      const value = row[col.key];
+      return col.formatter ? col.formatter(value) : String(value ?? "");
+    });
+    rows.push(formatRow(values));
+  }
+
+  return rows.join("\n");
+}
+
+/**
+ * Create a key-value list
+ */
+export function keyValueList(
+  data: Record<string, unknown>,
+  options: { separator?: string } = {}
+): string {
+  const { separator = ":" } = options;
+
+  const entries = Object.entries(data);
+  if (entries.length === 0) return "";
+
+  const maxKeyLength = Math.max(...entries.map(([key]) => key.length));
+
+  return entries
+    .map(([key, value]) => `${key.padEnd(maxKeyLength)}${separator} ${value}`)
+    .join("\n");
+}
+
+/**
+ * Create a bullet list
+ */
+export function bulletList(
+  items: string[],
+  options: { bullet?: string; indent?: number } = {}
+): string {
+  const { bullet = "•", indent = 0 } = options;
+
+  if (items.length === 0) return "";
+
+  const prefix = " ".repeat(indent);
+  return items.map((item) => `${prefix}${bullet} ${item}`).join("\n");
+}
+
+/**
+ * Create a numbered list
+ */
+export function numberedList(
+  items: string[],
+  options: { start?: number; indent?: number } = {}
+): string {
+  const { start = 1, indent = 0 } = options;
+
+  if (items.length === 0) return "";
+
+  const prefix = " ".repeat(indent);
+  const maxNum = start + items.length - 1;
+  const numWidth = String(maxNum).length;
+
+  return items
+    .map((item, i) => `${prefix}${String(start + i).padStart(numWidth)}. ${item}`)
+    .join("\n");
+}