@pablozaiden/terminatui 0.2.0 → 0.3.0

package/README.md

@@ -12,7 +12,7 @@ A type-safe, class-based framework for building CLI and TUI applications in Type
 - **Nested subcommands** - Hierarchical command structures with path resolution
 - **Lifecycle hooks** - `beforeExecute()` and `afterExecute()` hooks on commands
 - **Service container** - `AppContext` provides dependency injection for services
-- **Integrated logging** - Logger with TUI-aware output handling
+- **Integrated logging** - Logger with TUI-aware output handling (live log modal with global copy shortcut)
 - **Cancellation support** - AbortSignal-based cancellation for long-running commands
 - **Config validation** - `buildConfig()` hook for transforming and validating options
 
@@ -27,7 +27,12 @@ bun add @pablozaiden/terminatui
 ### 1. Define a Command
 
 ```typescript
-import { Command, type AppContext, type OptionSchema, type CommandResult } from "@pablozaiden/terminatui";
+import {
+  Command,
+  type OptionSchema,
+  type CommandResult,
+  type CommandExecutionContext,
+} from "@pablozaiden/terminatui";
 
 const greetOptions = {
   name: {
@@ -48,7 +53,10 @@ class GreetCommand extends Command<typeof greetOptions> {
   readonly description = "Greet someone";
   readonly options = greetOptions;
 
-  override execute(ctx: AppContext, config: { name: string; loud: boolean }): CommandResult {
+  override execute(
+    config: { name: string; loud: boolean },
+    _execCtx: CommandExecutionContext
+  ): CommandResult {
     const message = `Hello, ${config.name}!`;
     console.log(config.loud ? message.toUpperCase() : message);
     return { success: true, message };
@@ -77,7 +85,11 @@ class MyApp extends Application {
 
 ```typescript
 // index.ts
+// Recommended: let Terminatui read `Bun.argv.slice(2)`
 await new MyApp().run();
+
+// For tests or programmatic invocation:
+// await new MyApp().runFromArgs(["greet", "--name", "World"]);
 ```
 
 ```bash
@@ -121,9 +133,8 @@ abstract class Command<TOptions extends OptionSchema = OptionSchema, TConfig = u
   
   // Required: Main execution method
   abstract execute(
-    ctx: AppContext, 
     config: TConfig,
-    execCtx?: CommandExecutionContext
+    execCtx: CommandExecutionContext
   ): Promise<CommandResult | void> | CommandResult | void;
   
   // Optional: Transform/validate options before execute
@@ -170,10 +181,15 @@ The `Application` class manages command registration and execution:
 ```typescript
 class Application {
   constructor(config: ApplicationConfig);
-  
-  run(args?: string[]): Promise<void>;
+
+  // Recommended entrypoint (reads `Bun.argv.slice(2)`)
+  run(): Promise<void>;
+
+  // Useful for tests or programmatic invocation
+  runFromArgs(argv: string[]): Promise<void>;
+
   getContext(): AppContext;
-  
+
   // Lifecycle hooks (override in subclass)
   onBeforeRun?(command: Command, options: Record<string, unknown>): void;
   onAfterRun?(command: Command, result: unknown): void;
@@ -196,6 +212,8 @@ Access application-wide services and configuration:
 
 ```typescript
 import { AppContext } from "@pablozaiden/terminatui";
+import type { CommandExecutionContext } from "@pablozaiden/terminatui";
+import { AbortError } from "@pablozaiden/terminatui";
 
 // Get the current context (set during Application.run())
 const ctx = AppContext.current;
@@ -234,7 +252,7 @@ interface OptionDef {
   tuiHidden?: boolean;       // Hide from TUI form
 }
 
-type OptionSchema = Record<string, OptionDef>;
+type OptionSchema = Record<string, OptionDef>; // See library types
 ```
 
 ## Config Validation with buildConfig
@@ -242,7 +260,7 @@ type OptionSchema = Record<string, OptionDef>;
 Use `buildConfig()` to transform and validate options before execution:
 
 ```typescript
-import { Command, ConfigValidationError, type AppContext, type OptionValues } from "@pablozaiden/terminatui";
+import { Command, ConfigValidationError, type OptionValues } from "@pablozaiden/terminatui";
 
 interface MyConfig {
   resolvedPath: string;
@@ -254,7 +272,7 @@ class MyCommand extends Command<typeof myOptions, MyConfig> {
   readonly description = "Do something";
   readonly options = myOptions;
 
-  override buildConfig(ctx: AppContext, opts: OptionValues<typeof myOptions>): MyConfig {
+  override buildConfig(opts: OptionValues<typeof myOptions>): MyConfig {
     const pathRaw = opts["path"] as string | undefined;
     if (!pathRaw) {
       throw new ConfigValidationError("Missing required option: path", "path");
@@ -271,9 +289,16 @@ class MyCommand extends Command<typeof myOptions, MyConfig> {
     };
   }
 
-  override async execute(ctx: AppContext, config: MyConfig): Promise<CommandResult> {
+  override async execute(
+    config: MyConfig,
+    execCtx: CommandExecutionContext
+  ): Promise<CommandResult> {
     // config is now typed as MyConfig
-    ctx.logger.info(`Processing ${config.count} items from ${config.resolvedPath}`);
+    if (execCtx.signal.aborted) {
+      throw new AbortError("Command was cancelled");
+    }
+
+    AppContext.current.logger.info(`Processing ${config.count} items from ${config.resolvedPath}`);
     return { success: true };
   }
 }
@@ -288,19 +313,18 @@ class LongRunningCommand extends Command<typeof options> {
   // ...
 
   override async execute(
-    ctx: AppContext, 
     config: Config,
-    execCtx?: CommandExecutionContext
+    execCtx: CommandExecutionContext
   ): Promise<CommandResult> {
     for (const item of items) {
       // Check for cancellation
-      if (execCtx?.signal.aborted) {
+      if (execCtx.signal.aborted) {
         throw new AbortError("Command was cancelled");
       }
-      
-      await processItem(item, execCtx?.signal);
+
+      await processItem(item, execCtx.signal);
     }
-    
+
     return { success: true };
   }
 }
@@ -350,6 +374,9 @@ Extend `TuiApplication` instead of `Application` to get automatic TUI support:
 import { TuiApplication, Command } from "@pablozaiden/terminatui";
 
 class MyApp extends TuiApplication {
+  // Each app decides what "default" means.
+  protected override defaultRenderer = "opentui" as const;
+
   constructor() {
     super({
       name: "myapp",
@@ -362,11 +389,13 @@ class MyApp extends TuiApplication {
 }
 ```
 
-When run with no arguments, the app launches an interactive TUI instead of showing help:
+Execution mode is controlled only by the selected mode (`--mode`) or the app’s configured default mode.
 
 ```bash
-myapp              # Launches TUI
-myapp run --verbose # Runs in CLI mode
+myapp                           # Uses app default mode
+myapp --mode opentui            # Forces TUI (OpenTUI)
+myapp --mode ink                # Forces TUI (Ink)
+myapp --mode cli run --verbose  # Forces CLI
 ```
 
 ### TUI Metadata
@@ -412,14 +441,15 @@ class RunCommand extends Command<typeof runOptions, RunConfig> {
   override readonly immediateExecution = false;     // Run immediately on selection
 
   // Return structured results for display
-  override async execute(ctx: AppContext, config: RunConfig): Promise<CommandResult> {
-    const result = await runTask(config);
-    return { 
-      success: true, 
-      data: result,
-      message: "Task completed"
-    };
-  }
+   override async execute(config: RunConfig, _execCtx: CommandExecutionContext): Promise<CommandResult> {
+     const result = await runTask(config);
+     return {
+       success: true,
+       data: result,
+       message: "Task completed",
+     };
+   }
+
 
   // Custom result rendering (React/TSX)
   override renderResult(result: CommandResult): ReactNode {
@@ -452,7 +482,7 @@ The built-in TUI provides:
 - **Command Selector** - Navigate and select commands with arrow keys
 - **Config Form** - Auto-generated forms from option schemas with field groups
 - **Field Editor** - Edit field values (text, number, boolean, enum)
-- **CLI Modal** - View equivalent CLI command (press `C`)
+- **CLI Args Button** - View equivalent CLI command from the config form
 - **Results Panel** - Display command results with custom rendering
 - **Logs Panel** - View application logs in real-time
 - **Clipboard Support** - Centralized copy with Ctrl+Y
@@ -464,9 +494,8 @@ The built-in TUI provides:
 | Key | Action |
 |-----|--------|
 | ↑/↓ | Navigate fields/commands |
-| Enter | Edit field / Execute command |
+| Enter | Edit field / Execute command / Press button |
 | Tab | Cycle focus between panels |
-| C | Show CLI command modal |
 | L | Toggle logs panel |
 | Ctrl+Y | Copy current content to clipboard |
 | Esc | Back / Cancel running command |
@@ -486,7 +515,7 @@ import {
   useKeyboardHandler,    // Register keyboard handlers with priority
   useClipboard,          // Clipboard operations with OSC 52
   useLogStream,          // Stream logs from logger
-  useSpinner,            // Animated spinner
+  // (renderer-specific) Spinner UI lives in adapters
   useCommandExecutor,    // Execute commands with cancellation
   
   // Context
@@ -494,7 +523,6 @@ import {
   KeyboardPriority,      // Global < Focused < Modal
   
   // Components
-  Theme,                 // TUI color theme
   JsonHighlight,         // Syntax-highlighted JSON display
 } from "@pablozaiden/terminatui";
 ```
@@ -504,19 +532,12 @@ import {
 Terminatui includes utilities for formatted CLI output:
 
 ```typescript
-import { colors, table, bulletList, keyValueList } from "@pablozaiden/terminatui";
+import { colors } from "@pablozaiden/terminatui";
 
 // Colors
 console.log(colors.red("Error!"));
 console.log(colors.success("Done!"));  // ✓ Done!
 console.log(colors.bold(colors.blue("Title")));
-
-// Tables
-console.log(table(data, ["name", "value", "status"]));
-
-// Lists
-console.log(bulletList(["Item 1", "Item 2", "Item 3"]));
-console.log(keyValueList({ name: "Test", count: 42 }));
 ```
 
 ## License

package/package.json

@@ -1,19 +1,19 @@
 {
   "name": "@pablozaiden/terminatui",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Terminal UI and Command Line Application Framework",
   "repository": {
     "url": "https://github.com/PabloZaiden/terminatui"
   },
   "type": "module",
-  "main": "src/index.ts",
-  "types": "src/index.ts",
+  "files": [
+    "src/**/*"
+  ],
   "exports": {
-    ".": "./src/index.ts",
-    "./cli": "./src/cli/index.ts",
-    "./tui": "./src/tui/index.ts",
-    "./components": "./src/components/index.ts",
-    "./hooks": "./src/hooks/index.ts"
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
   },
   "scripts": {
     "build": "bunx tsc --noEmit",
@@ -22,6 +22,9 @@
   },
   "dependencies": {
     "@opentui/react": "0.1.68",
+    "ink": "^6.6.0",
+    "ink-select-input": "^6.2.0",
+    "ink-text-input": "^6.0.0",
     "tslog": "^4.9.3"
   },
   "devDependencies": {

package/src/__tests__/application.test.ts

@@ -1,8 +1,10 @@
-import { describe, test, expect, afterEach } from "bun:test";
+import { describe, test, expect } from "bun:test";
 import { Application } from "../core/application.ts";
 import { Command } from "../core/command.ts";
-import { AppContext } from "../core/context.ts";
 import type { OptionSchema, OptionValues, OptionDef } from "../types/command.ts";
+import { AppContext } from "../core/context.ts";
+import { LogLevel } from "../core/logger.ts";
+import { KNOWN_COMMANDS } from "../core/knownCommands.ts";
 
 // Define a proper option schema
 const testOptions = {
@@ -21,7 +23,6 @@ class TestCommand extends Command<typeof testOptions> {
   executedWith: Record<string, unknown> | null = null;
 
   override async execute(
-    _ctx: AppContext,
     opts: OptionValues<typeof testOptions>
   ): Promise<void> {
     this.executedWith = opts as Record<string, unknown>;
@@ -35,17 +36,57 @@ class TuiCommand extends Command<OptionSchema> {
 
   executed = false;
 
-  override async execute(_ctx: AppContext): Promise<void> {
+  override async execute(): Promise<void> {
     this.executed = true;
   }
 }
 
 describe("Application", () => {
-  afterEach(() => {
-    AppContext.clearCurrent();
-  });
-
   describe("constructor", () => {
+    test("rejects reserved help command definitions", () => {
+      class ReservedCommand extends Command<OptionSchema> {
+        readonly name = KNOWN_COMMANDS.help;
+        readonly description = "tries to override built-in";
+        readonly options = {};
+
+        override async execute(): Promise<void> {}
+      }
+
+      expect(() => {
+        new Application({
+          name: "test-app",
+          version: "1.0.0",
+          commands: [new ReservedCommand()],
+        });
+      }).toThrow(/reserved/i);
+
+      class SubCommand extends Command<OptionSchema> {
+        readonly name = KNOWN_COMMANDS.help;
+        readonly description = "user help";
+        readonly options = {};
+
+        override async execute(): Promise<void> {}
+      }
+
+      class ParentCommand extends Command<OptionSchema> {
+        readonly name = "parent";
+        readonly description = "parent";
+        readonly options = {};
+
+        override subCommands = [new SubCommand()];
+
+        override async execute(): Promise<void> {}
+      }
+
+      expect(() => {
+        new Application({
+          name: "test-app",
+          version: "1.0.0",
+          commands: [new ParentCommand()],
+        });
+      }).toThrow(/automatically injected/i);
+    });
+
     test("creates application with name and version", () => {
       const app = new Application({
         name: "test-app",
@@ -56,14 +97,16 @@ describe("Application", () => {
       expect(app.version).toBe("1.0.0");
     });
 
-    test("creates context and sets as current", () => {
-      const app = new Application({
+    test("creates context as side effect of creating application", () => {
+      // side effect of creating an application is setting the current context
+      new Application({
         name: "test-app",
         version: "1.0.0",
         commands: [],
       });
-      expect(AppContext.hasCurrent()).toBe(true);
-      expect(app.context).toBe(AppContext.current);
+      
+      expect(AppContext.current.config.name).toBe("test-app");
+      expect(AppContext.current.config.version).toBe("1.0.0");
     });
 
     test("registers provided commands", () => {
@@ -91,7 +134,7 @@ describe("Application", () => {
         version: "1.0.0",
         commands: [],
       });
-      expect(app.registry.has("help")).toBe(true);
+      expect(app.registry.has(KNOWN_COMMANDS.help)).toBe(true);
     });
 
     test("injects help subcommand into commands", () => {
@@ -103,32 +146,11 @@ describe("Application", () => {
         commands: [cmd],
       });
       expect(cmd.subCommands).toBeDefined();
-      expect(cmd.subCommands?.some((c) => c.name === "help")).toBe(true);
-    });
-  });
-
-  describe("getContext", () => {
-    test("returns the application context", () => {
-      const app = new Application({
-        name: "test-app",
-        version: "1.0.0",
-        commands: [],
-      });
-      expect(app.getContext()).toBe(app.context);
+      expect(cmd.subCommands?.some((c) => c.name === KNOWN_COMMANDS.help)).toBe(true);
     });
   });
 
   describe("run", () => {
-    test("shows help when no args and no default command", async () => {
-      const app = new Application({
-        name: "test-app",
-        version: "1.0.0",
-        commands: [new TestCommand()],
-      });
-      // Should not throw
-      await app.run([]);
-    });
-
     test("runs default command when no args", async () => {
       const cmd = new TuiCommand();
       const app = new Application({
@@ -137,31 +159,30 @@ describe("Application", () => {
         commands: [cmd],
         defaultCommand: "tui-cmd",
       });
-      await app.run([]);
+      await app.runFromArgs([]);
       expect(cmd.executed).toBe(true);
     });
 
-    test("runs specified command", async () => {
+    test("runs specified command and passes options", async () => {
       const cmd = new TestCommand();
       const app = new Application({
         name: "test-app",
         version: "1.0.0",
         commands: [cmd],
       });
-      await app.run(["test"]);
-      expect(cmd.executedWith).not.toBeNull();
+
+      await app.runFromArgs(["test", "--value", "hello"]);
+      expect(cmd.executedWith?.["value"]).toBe("hello");
     });
 
-    test("passes options to command", async () => {
-      const cmd = new TestCommand();
+    test("with no args and no default, prints help (no throw)", async () => {
       const app = new Application({
         name: "test-app",
         version: "1.0.0",
-        commands: [cmd],
+        commands: [new TestCommand()],
       });
-      await app.run(["test", "--value", "hello"]);
-      expect(cmd.executedWith).not.toBeNull();
-      expect(cmd.executedWith?.["value"]).toBe("hello");
+
+      await app.runFromArgs([]);
     });
   });
 
@@ -179,7 +200,7 @@ describe("Application", () => {
           called = true;
         },
       });
-      await app.run(["test"]);
+      await app.runFromArgs(["test"]);
       expect(called).toBe(true);
     });
 
@@ -196,7 +217,7 @@ describe("Application", () => {
           called = true;
         },
       });
-      await app.run(["test"]);
+      await app.runFromArgs(["test"]);
       expect(called).toBe(true);
     });
 
@@ -219,11 +240,11 @@ describe("Application", () => {
         commands: [new ErrorCommand()],
       });
       app.setHooks({
-        onError: async (_ctx, error) => {
+        onError: async (error) => {
           errorCaught = error;
         },
       });
-      await app.run(["error-cmd"]);
+      await app.runFromArgs(["error-cmd"]);
       expect(errorCaught?.message).toBe("Test error");
     });
   });
@@ -250,7 +271,6 @@ describe("Application", () => {
         readonly options = configOptions;
 
         override buildConfig(
-          _ctx: AppContext,
           opts: OptionValues<typeof configOptions>
         ): ParsedConfig {
           buildConfigCalled = true;
@@ -260,7 +280,7 @@ describe("Application", () => {
           };
         }
 
-        override async execute(_ctx: AppContext, config: ParsedConfig): Promise<void> {
+        override async execute(config: ParsedConfig): Promise<void> {
           receivedConfig = config;
         }
       }
@@ -271,7 +291,7 @@ describe("Application", () => {
         commands: [new ConfigCommand()],
       });
 
-      await app.run(["config-cmd", "--value", "test", "--count", "42"]);
+      await app.runFromArgs(["config-cmd", "--value", "test", "--count", "42"]);
       
       expect(buildConfigCalled).toBe(true);
       expect(receivedConfig).toEqual({ value: "test", count: 42 });
@@ -286,7 +306,6 @@ describe("Application", () => {
         readonly options = testOptions;
 
         override async execute(
-          _ctx: AppContext,
           opts: OptionValues<typeof testOptions>
         ): Promise<void> {
           receivedOpts = opts as Record<string, unknown>;
@@ -299,7 +318,7 @@ describe("Application", () => {
         commands: [new NoConfigCommand()],
       });
 
-      await app.run(["no-config-cmd", "--value", "hello"]);
+      await app.runFromArgs(["no-config-cmd", "--value", "hello"]);
       
       expect(receivedOpts).toEqual({ value: "hello" });
     });
@@ -328,12 +347,12 @@ describe("Application", () => {
       });
       
       app.setHooks({
-        onError: async (_ctx, error) => {
+        onError: async (error) => {
           errorCaught = error;
         },
       });
 
-      await app.run(["fail-config", "--value", "test"]);
+      await app.runFromArgs(["fail-config", "--value", "test"]);
       
       expect(errorCaught?.message).toBe("Config validation failed");
     });
@@ -349,7 +368,7 @@ describe("Application", () => {
       });
       
       // Should not throw - global option should be parsed and removed
-      await app.run(["--log-level", "debug", "test", "--value", "hello"]);
+      await app.runFromArgs(["--log-level", "debug", "test", "--value", "hello"]);
       expect(cmd.executedWith?.["value"]).toBe("hello");
     });
 
@@ -361,7 +380,7 @@ describe("Application", () => {
         commands: [cmd],
       });
       
-      await app.run(["test", "--log-level", "debug", "--value", "hello"]);
+      await app.runFromArgs(["test", "--log-level", "debug", "--value", "hello"]);
       expect(cmd.executedWith?.["value"]).toBe("hello");
     });
 
@@ -374,14 +393,14 @@ describe("Application", () => {
       });
       
       // All of these should work (case-insensitive)
-      await app.run(["--log-level", "debug", "test"]);
-      expect(app.context.logger.getMinLevel()).toBe(2); // Debug = 2
+      await app.runFromArgs(["--log-level", "debug", "test"]);
+      expect(AppContext.current.logger.getMinLevel()).toBe(LogLevel.debug);
       
-      await app.run(["--log-level", "Debug", "test"]);
-      expect(app.context.logger.getMinLevel()).toBe(2);
+      await app.runFromArgs(["--log-level", "Debug", "test"]);
+      expect(AppContext.current.logger.getMinLevel()).toBe(LogLevel.debug);
       
-      await app.run(["--log-level", "DEBUG", "test"]);
-      expect(app.context.logger.getMinLevel()).toBe(2);
+      await app.runFromArgs(["--log-level", "DEBUG", "test"]);
+      expect(AppContext.current.logger.getMinLevel()).toBe(LogLevel.debug);
     });
 
     test("parses --detailed-logs flag", async () => {
@@ -392,7 +411,7 @@ describe("Application", () => {
         commands: [cmd],
       });
       
-      await app.run(["--detailed-logs", "test"]);
+      await app.runFromArgs(["--detailed-logs", "test"]);
       // Should not throw - flag is recognized
       expect(cmd.executedWith).not.toBeNull();
     });
@@ -405,7 +424,7 @@ describe("Application", () => {
         commands: [cmd],
       });
       
-      await app.run(["--no-detailed-logs", "test"]);
+      await app.runFromArgs(["--no-detailed-logs", "test"]);
       // Should not throw - flag is recognized
       expect(cmd.executedWith).not.toBeNull();
     });
@@ -418,8 +437,8 @@ describe("Application", () => {
         commands: [cmd],
       });
       
-      await app.run(["--log-level=warn", "test"]);
-      expect(app.context.logger.getMinLevel()).toBe(4); // Warn = 4
+      await app.runFromArgs(["--log-level=warn", "test"]);
+      expect(AppContext.current.logger.getMinLevel()).toBe(LogLevel.warn);
     });
   });
 });