@pablozaiden/terminatui 0.2.0 → 0.3.0-beta-1

package/guides/07-async-cancellation.md

@@ -23,7 +23,6 @@ import path from "node:path";
 import { 
   Command, 
   ConfigValidationError,
-  type AppContext, 
   type OptionSchema, 
   type OptionValues,
   type CommandResult,
@@ -69,10 +68,7 @@ export class DownloadCommand extends Command<typeof options, DownloadConfig> {
   readonly displayName = "File Downloader";
   readonly actionLabel = "Download";
 
-  override buildConfig(
-    _ctx: AppContext,
-    opts: OptionValues<typeof options>
-  ): DownloadConfig {
+  override buildConfig(opts: OptionValues<typeof options>): DownloadConfig {
     // Validate URL
     const urlStr = opts["url"] as string;
     if (!urlStr) {
@@ -107,16 +103,15 @@ export class DownloadCommand extends Command<typeof options, DownloadConfig> {
 
 ```typescript
   async execute(
-    ctx: AppContext,
     config: DownloadConfig,
-    execCtx?: CommandExecutionContext
+    execCtx: CommandExecutionContext
   ): Promise<CommandResult> {
     const { url, outputDir, fileName, chunkSize } = config;
     const outputPath = path.join(outputDir, fileName);
-    const signal = execCtx?.signal;
+    const signal = execCtx.signal;
 
-    ctx.logger.info(`Starting download: ${url}`);
-    ctx.logger.info(`Output: ${outputPath}`);
+    console.log(`Starting download: ${url}`);
+    console.log(`Output: ${outputPath}`);
 
     // Create output directory
     await Bun.write(path.join(outputDir, ".keep"), "");
@@ -128,7 +123,8 @@ export class DownloadCommand extends Command<typeof options, DownloadConfig> {
 
     try {
       // Check for cancellation before starting
-      if (signal?.aborted) {
+       if (signal.aborted) {
+
         return { success: false, message: "Download cancelled before start" };
       }
 
@@ -157,8 +153,9 @@ export class DownloadCommand extends Command<typeof options, DownloadConfig> {
       // Read chunks with cancellation checks
       while (true) {
         // Check for cancellation between chunks
-        if (signal?.aborted) {
-          ctx.logger.warn("Download cancelled by user");
+      if (signal.aborted) {
+
+          console.warn("Download cancelled by user");
           throw new Error("AbortError");
         }
 
@@ -177,10 +174,10 @@ export class DownloadCommand extends Command<typeof options, DownloadConfig> {
           const percent = ((downloadedBytes / totalBytes) * 100).toFixed(1);
           const mbDownloaded = (downloadedBytes / 1024 / 1024).toFixed(2);
           const mbTotal = (totalBytes / 1024 / 1024).toFixed(2);
-          process.stdout.write(`\rProgress: ${percent}% (${mbDownloaded}/${mbTotal} MB)`);
+          Bun.write(Bun.stdout, `\rProgress: ${percent}% (${mbDownloaded}/${mbTotal} MB)`);
         } else {
           const mbDownloaded = (downloadedBytes / 1024 / 1024).toFixed(2);
-          process.stdout.write(`\rDownloaded: ${mbDownloaded} MB`);
+          Bun.write(Bun.stdout, `\rDownloaded: ${mbDownloaded} MB`);
         }
       }
 
@@ -200,7 +197,8 @@ export class DownloadCommand extends Command<typeof options, DownloadConfig> {
 
     } catch (error) {
       // Handle cancellation
-      if (signal?.aborted || (error as Error).name === "AbortError") {
+       if (signal.aborted || (error as Error).name === "AbortError") {
+
         console.log("\nDownload cancelled.");
         
         // Cleanup partial file

package/guides/08-complete-application.md

@@ -152,7 +152,6 @@ Create `src/commands/add.ts`:
 import {
   Command,
   ConfigValidationError,
-  type AppContext,
   type OptionSchema,
   type OptionValues,
   type CommandResult,
@@ -190,15 +189,10 @@ export class AddCommand extends Command<typeof options, AddConfig> {
   readonly options = options;
   readonly displayName = "Add Task";
   readonly actionLabel = "Create Task";
-  readonly group = "Tasks";
-  readonly order = 1;
 
   private db = new Database();
 
-  override buildConfig(
-    _ctx: AppContext,
-    opts: OptionValues<typeof options>
-  ): AddConfig {
+  override buildConfig(opts: OptionValues<typeof options>): AddConfig {
     const title = (opts["title"] as string)?.trim();
     if (!title) {
       throw new ConfigValidationError("Task title cannot be empty", "title");
@@ -215,13 +209,11 @@ export class AddCommand extends Command<typeof options, AddConfig> {
     return { title, priority };
   }
 
-  async execute(ctx: AppContext, config: AddConfig): Promise<CommandResult> {
-    ctx.logger.debug(`Creating task: ${config.title}`);
-
+  async execute(config: AddConfig): Promise<CommandResult> {
     const task = await this.db.addTask(config.title, config.priority);
-    
-    const notifications = new NotificationService(ctx.logger);
-    notifications.taskAdded(task);
+
+    // (Example) optional: log to console or your own logger
+    console.log(`Created task: ${task.title}`);
 
     return {
       success: true,
@@ -237,7 +229,6 @@ Create `src/commands/list.ts`:
 ```typescript
 import {
   Command,
-  type AppContext,
   type OptionSchema,
   type OptionValues,
   type CommandResult,
@@ -272,27 +263,20 @@ export class ListCommand extends Command<typeof options, ListConfig> {
   readonly options = options;
   readonly displayName = "List Tasks";
   readonly actionLabel = "Show Tasks";
-  readonly group = "Tasks";
-  readonly order = 2;
 
   // Execute immediately when selected in TUI
   readonly immediateExecution = true;
 
   private db = new Database();
 
-  override buildConfig(
-    _ctx: AppContext,
-    opts: OptionValues<typeof options>
-  ): ListConfig {
+  override buildConfig(opts: OptionValues<typeof options>): ListConfig {
     return {
       filter: (opts["filter"] as ListConfig["filter"]) ?? "all",
       priority: opts["priority"] as Task["priority"] | undefined,
     };
   }
 
-  async execute(ctx: AppContext, config: ListConfig): Promise<CommandResult> {
-    ctx.logger.debug(`Listing tasks: filter=${config.filter}`);
-
+  async execute(config: ListConfig): Promise<CommandResult> {
     let tasks = await this.db.listTasks(config.filter);
 
     if (config.priority) {
@@ -314,7 +298,6 @@ Create `src/commands/complete.ts`:
 import {
   Command,
   ConfigValidationError,
-  type AppContext,
   type OptionSchema,
   type OptionValues,
   type CommandResult,
@@ -342,15 +325,10 @@ export class CompleteCommand extends Command<typeof options, CompleteConfig> {
   readonly options = options;
   readonly displayName = "Complete Task";
   readonly actionLabel = "Mark Complete";
-  readonly group = "Tasks";
-  readonly order = 3;
 
   private db = new Database();
 
-  override buildConfig(
-    _ctx: AppContext,
-    opts: OptionValues<typeof options>
-  ): CompleteConfig {
+  override buildConfig(opts: OptionValues<typeof options>): CompleteConfig {
     const id = opts["id"] as string;
     if (!id?.trim()) {
       throw new ConfigValidationError("Task ID is required", "id");
@@ -358,11 +336,9 @@ export class CompleteCommand extends Command<typeof options, CompleteConfig> {
     return { id: id.trim() };
   }
 
-  async execute(ctx: AppContext, config: CompleteConfig): Promise<CommandResult> {
-    ctx.logger.debug(`Completing task: ${config.id}`);
-
+  async execute(config: CompleteConfig): Promise<CommandResult> {
     const task = await this.db.completeTask(config.id);
-    
+
     if (!task) {
       return {
         success: false,
@@ -370,8 +346,7 @@ export class CompleteCommand extends Command<typeof options, CompleteConfig> {
       };
     }
 
-    const notifications = new NotificationService(ctx.logger);
-    notifications.taskCompleted(task);
+    console.log(`Completed task: ${task.title}`);
 
     return {
       success: true,
@@ -387,7 +362,6 @@ Create `src/commands/stats.ts`:
 ```typescript
 import {
   Command,
-  type AppContext,
   type OptionSchema,
   type CommandResult,
 } from "@pablozaiden/terminatui";
@@ -402,15 +376,11 @@ export class StatsCommand extends Command<typeof options> {
   readonly options = options;
   readonly displayName = "Statistics";
   readonly actionLabel = "Show Stats";
-  readonly group = "Analytics";
-  readonly order = 1;
   readonly immediateExecution = true;
 
   private db = new Database();
 
-  async execute(ctx: AppContext): Promise<CommandResult> {
-    ctx.logger.debug("Fetching statistics");
-
+  async execute(): Promise<CommandResult> {
     const stats = await this.db.getStats();
 
     return {

package/guides/README.md

@@ -36,7 +36,7 @@ bun add @pablozaiden/terminatui
 
 # Create your first command
 cat > src/index.ts << 'EOF'
-import { Command, Application, type AppContext, type OptionSchema } from "@pablozaiden/terminatui";
+import { Command, Application, type OptionSchema } from "@pablozaiden/terminatui";
 
 const options = {
   name: { type: "string", description: "Your name" },
@@ -47,7 +47,7 @@ class HelloCommand extends Command<typeof options> {
   readonly description = "Say hello";
   readonly options = options;
 
-  async execute(ctx: AppContext, config: Record<string, unknown>) {
+  async execute(config: Record<string, unknown>) {
     const name = config["name"] ?? "World";
     console.log(`Hello, ${name}!`);
     return { success: true };
@@ -60,7 +60,11 @@ class MyCLI extends Application {
   }
 }
 
+// Recommended: let Terminatui read `Bun.argv.slice(2)`
 await new MyCLI().run();
+
+// For tests or programmatic invocation:
+// await new MyCLI().runFromArgs(["hello", "--name", "Developer"]);
 EOF
 
 # Run it
@@ -69,6 +73,6 @@ bun src/index.ts hello --name "Developer"
 
 ## Prerequisites
 
-- [Bun](https://bun.sh) or Node.js 18+
+- [Bun](https://bun.sh)
 - Basic TypeScript knowledge
 - Terminal/command-line familiarity

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pablozaiden/terminatui",
-  "version": "0.2.0",
+  "version": "0.3.0-beta-1",
   "description": "Terminal UI and Command Line Application Framework",
   "repository": {
     "url": "https://github.com/PabloZaiden/terminatui"
@@ -8,13 +8,6 @@
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",
-  "exports": {
-    ".": "./src/index.ts",
-    "./cli": "./src/cli/index.ts",
-    "./tui": "./src/tui/index.ts",
-    "./components": "./src/components/index.ts",
-    "./hooks": "./src/hooks/index.ts"
-  },
   "scripts": {
     "build": "bunx tsc --noEmit",
     "test": "bun test",
@@ -22,6 +15,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);
     });
   });
 });