@pablozaiden/terminatui 0.1.0

package/guides/README.md

@@ -0,0 +1,74 @@
+# Terminatui Framework Guides
+
+Step-by-step tutorials for building CLI applications with the terminatui framework.
+
+## Guide Overview
+
+| # | Guide | Level | Topics |
+|---|-------|-------|--------|
+| 1 | [Hello World](01-hello-world.md) | Super Simple | Basic Command, Application |
+| 2 | [Adding Options](02-adding-options.md) | Super Simple | Option types, defaults, aliases |
+| 3 | [Multiple Commands](03-multiple-commands.md) | Basic | Multiple commands, project structure |
+| 4 | [Subcommands](04-subcommands.md) | Basic | Nested subcommands, hierarchies |
+| 5 | [Interactive TUI](05-interactive-tui.md) | Normal | TuiApplication, metadata, keyboard |
+| 6 | [Config Validation](06-config-validation.md) | Normal | buildConfig, ConfigValidationError |
+| 7 | [Async Cancellation](07-async-cancellation.md) | Complex | AbortSignal, cancellation, cleanup |
+| 8 | [Complete Application](08-complete-application.md) | Complex | Full app, services, best practices |
+
+## Learning Path
+
+### Beginners
+Start with guides 1-2 to understand the basics of commands and options.
+
+### Intermediate
+Continue with guides 3-4 to learn about organizing larger applications.
+
+### Advanced
+Work through guides 5-8 to master TUI features, validation, and production patterns.
+
+## Quick Start
+
+```bash
+# Create a new project
+mkdir my-cli && cd my-cli
+bun init -y
+bun add @pablozaiden/terminatui
+
+# Create your first command
+cat > src/index.ts << 'EOF'
+import { Command, Application, type AppContext, type OptionSchema } from "@pablozaiden/terminatui";
+
+const options = {
+  name: { type: "string", description: "Your name" },
+} satisfies OptionSchema;
+
+class HelloCommand extends Command<typeof options> {
+  readonly name = "hello";
+  readonly description = "Say hello";
+  readonly options = options;
+
+  async execute(ctx: AppContext, config: Record<string, unknown>) {
+    const name = config["name"] ?? "World";
+    console.log(`Hello, ${name}!`);
+    return { success: true };
+  }
+}
+
+class MyCLI extends Application {
+  constructor() {
+    super({ name: "my-cli", version: "1.0.0", commands: [new HelloCommand()] });
+  }
+}
+
+await new MyCLI().run();
+EOF
+
+# Run it
+bun src/index.ts hello --name "Developer"
+```
+
+## Prerequisites
+
+- [Bun](https://bun.sh) or Node.js 18+
+- Basic TypeScript knowledge
+- Terminal/command-line familiarity

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@pablozaiden/terminatui",
+  "version": "0.1.0",
+  "description": "Terminal UI and Command Line Application Framework",
+  "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",
+    "example": "bun run examples/tui-app/index.ts"
+  },
+  "dependencies": {
+    "@opentui/react": "0.1.68",
+    "tslog": "^4.9.3"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/react": "^19",
+    "typescript": "5.9.3"
+  },
+  "peerDependencies": {
+    "typescript": "5.9.3"
+  }
+}

package/src/__tests__/application.test.ts

@@ -0,0 +1,425 @@
+import { describe, test, expect, afterEach } 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";
+
+// Define a proper option schema
+const testOptions = {
+  value: { 
+    type: "string" as const, 
+    description: "Test value" 
+  } satisfies OptionDef
+} as const satisfies OptionSchema;
+
+// Test command implementations
+class TestCommand extends Command<typeof testOptions> {
+  readonly name = "test";
+  readonly description = "A test command";
+  readonly options = 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>;
+  }
+}
+
+class TuiCommand extends Command<OptionSchema> {
+  readonly name = "tui-cmd";
+  readonly description = "A TUI command";
+  readonly options = {};
+
+  executed = false;
+
+  override async execute(_ctx: AppContext): Promise<void> {
+    this.executed = true;
+  }
+}
+
+describe("Application", () => {
+  afterEach(() => {
+    AppContext.clearCurrent();
+  });
+
+  describe("constructor", () => {
+    test("creates application with name and version", () => {
+      const app = new Application({
+        name: "test-app",
+        version: "1.0.0",
+        commands: [],
+      });
+      expect(app.name).toBe("test-app");
+      expect(app.version).toBe("1.0.0");
+    });
+
+    test("creates context and sets as current", () => {
+      const app = new Application({
+        name: "test-app",
+        version: "1.0.0",
+        commands: [],
+      });
+      expect(AppContext.hasCurrent()).toBe(true);
+      expect(app.context).toBe(AppContext.current);
+    });
+
+    test("registers provided commands", () => {
+      const cmd = new TestCommand();
+      const app = new Application({
+        name: "test-app",
+        version: "1.0.0",
+        commands: [cmd],
+      });
+      expect(app.registry.has("test")).toBe(true);
+    });
+
+    test("auto-registers version command", () => {
+      const app = new Application({
+        name: "test-app",
+        version: "1.0.0",
+        commands: [],
+      });
+      expect(app.registry.has("version")).toBe(true);
+    });
+
+    test("auto-registers help command", () => {
+      const app = new Application({
+        name: "test-app",
+        version: "1.0.0",
+        commands: [],
+      });
+      expect(app.registry.has("help")).toBe(true);
+    });
+
+    test("injects help subcommand into commands", () => {
+      const cmd = new TestCommand();
+      // Creating the Application injects help into commands
+      new Application({
+        name: "test-app",
+        version: "1.0.0",
+        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);
+    });
+  });
+
+  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({
+        name: "test-app",
+        version: "1.0.0",
+        commands: [cmd],
+        defaultCommand: "tui-cmd",
+      });
+      await app.run([]);
+      expect(cmd.executed).toBe(true);
+    });
+
+    test("runs specified command", 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();
+    });
+
+    test("passes options to command", async () => {
+      const cmd = new TestCommand();
+      const app = new Application({
+        name: "test-app",
+        version: "1.0.0",
+        commands: [cmd],
+      });
+      await app.run(["test", "--value", "hello"]);
+      expect(cmd.executedWith).not.toBeNull();
+      expect(cmd.executedWith?.["value"]).toBe("hello");
+    });
+  });
+
+  describe("lifecycle hooks", () => {
+    test("calls onBeforeRun", async () => {
+      let called = false;
+      const cmd = new TestCommand();
+      const app = new Application({
+        name: "test-app",
+        version: "1.0.0",
+        commands: [cmd],
+      });
+      app.setHooks({
+        onBeforeRun: async () => {
+          called = true;
+        },
+      });
+      await app.run(["test"]);
+      expect(called).toBe(true);
+    });
+
+    test("calls onAfterRun", async () => {
+      let called = false;
+      const cmd = new TestCommand();
+      const app = new Application({
+        name: "test-app",
+        version: "1.0.0",
+        commands: [cmd],
+      });
+      app.setHooks({
+        onAfterRun: async () => {
+          called = true;
+        },
+      });
+      await app.run(["test"]);
+      expect(called).toBe(true);
+    });
+
+    test("calls onError on exception", async () => {
+      let errorCaught: Error | undefined;
+
+      class ErrorCommand extends Command<OptionSchema> {
+        readonly name = "error-cmd";
+        readonly description = "A command that throws";
+        readonly options = {};
+
+        override async execute(): Promise<void> {
+          throw new Error("Test error");
+        }
+      }
+
+      const app = new Application({
+        name: "test-app",
+        version: "1.0.0",
+        commands: [new ErrorCommand()],
+      });
+      app.setHooks({
+        onError: async (_ctx, error) => {
+          errorCaught = error;
+        },
+      });
+      await app.run(["error-cmd"]);
+      expect(errorCaught?.message).toBe("Test error");
+    });
+  });
+
+  describe("buildConfig", () => {
+    // Config type for testing
+    interface ParsedConfig {
+      value: string;
+      count: number;
+    }
+
+    const configOptions = {
+      value: { type: "string" as const, description: "A value" },
+      count: { type: "string" as const, description: "A count" },
+    } as const satisfies OptionSchema;
+
+    test("calls buildConfig before execute", async () => {
+      let buildConfigCalled = false;
+      let receivedConfig: ParsedConfig | null = null as ParsedConfig | null;
+
+      class ConfigCommand extends Command<typeof configOptions, ParsedConfig> {
+        readonly name = "config-cmd";
+        readonly description = "A command with buildConfig";
+        readonly options = configOptions;
+
+        override buildConfig(
+          _ctx: AppContext,
+          opts: OptionValues<typeof configOptions>
+        ): ParsedConfig {
+          buildConfigCalled = true;
+          return {
+            value: opts.value as string,
+            count: parseInt(opts.count as string, 10),
+          };
+        }
+
+        override async execute(_ctx: AppContext, config: ParsedConfig): Promise<void> {
+          receivedConfig = config;
+        }
+      }
+
+      const app = new Application({
+        name: "test-app",
+        version: "1.0.0",
+        commands: [new ConfigCommand()],
+      });
+
+      await app.run(["config-cmd", "--value", "test", "--count", "42"]);
+      
+      expect(buildConfigCalled).toBe(true);
+      expect(receivedConfig).toEqual({ value: "test", count: 42 });
+    });
+
+    test("passes raw options when buildConfig is not defined", async () => {
+      let receivedOpts: Record<string, unknown> | null = null as Record<string, unknown> | null;
+
+      class NoConfigCommand extends Command<typeof testOptions> {
+        readonly name = "no-config-cmd";
+        readonly description = "A command without buildConfig";
+        readonly options = testOptions;
+
+        override async execute(
+          _ctx: AppContext,
+          opts: OptionValues<typeof testOptions>
+        ): Promise<void> {
+          receivedOpts = opts as Record<string, unknown>;
+        }
+      }
+
+      const app = new Application({
+        name: "test-app",
+        version: "1.0.0",
+        commands: [new NoConfigCommand()],
+      });
+
+      await app.run(["no-config-cmd", "--value", "hello"]);
+      
+      expect(receivedOpts).toEqual({ value: "hello" });
+    });
+
+    test("buildConfig errors are caught and handled", async () => {
+      let errorCaught: Error | undefined;
+
+      class FailConfigCommand extends Command<typeof testOptions, never> {
+        readonly name = "fail-config";
+        readonly description = "A command that fails buildConfig";
+        readonly options = testOptions;
+
+        override buildConfig(): never {
+          throw new Error("Config validation failed");
+        }
+
+        override async execute(): Promise<void> {
+          // Should never be called
+        }
+      }
+
+      const app = new Application({
+        name: "test-app",
+        version: "1.0.0",
+        commands: [new FailConfigCommand()],
+      });
+      
+      app.setHooks({
+        onError: async (_ctx, error) => {
+          errorCaught = error;
+        },
+      });
+
+      await app.run(["fail-config", "--value", "test"]);
+      
+      expect(errorCaught?.message).toBe("Config validation failed");
+    });
+  });
+
+  describe("global options", () => {
+    test("parses --log-level before command", async () => {
+      const cmd = new TestCommand();
+      const app = new Application({
+        name: "test-app",
+        version: "1.0.0",
+        commands: [cmd],
+      });
+      
+      // Should not throw - global option should be parsed and removed
+      await app.run(["--log-level", "debug", "test", "--value", "hello"]);
+      expect(cmd.executedWith?.["value"]).toBe("hello");
+    });
+
+    test("parses --log-level after command", async () => {
+      const cmd = new TestCommand();
+      const app = new Application({
+        name: "test-app",
+        version: "1.0.0",
+        commands: [cmd],
+      });
+      
+      await app.run(["test", "--log-level", "debug", "--value", "hello"]);
+      expect(cmd.executedWith?.["value"]).toBe("hello");
+    });
+
+    test("applies log-level case-insensitively", async () => {
+      const cmd = new TestCommand();
+      const app = new Application({
+        name: "test-app",
+        version: "1.0.0",
+        commands: [cmd],
+      });
+      
+      // 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.run(["--log-level", "Debug", "test"]);
+      expect(app.context.logger.getMinLevel()).toBe(2);
+      
+      await app.run(["--log-level", "DEBUG", "test"]);
+      expect(app.context.logger.getMinLevel()).toBe(2);
+    });
+
+    test("parses --detailed-logs flag", async () => {
+      const cmd = new TestCommand();
+      const app = new Application({
+        name: "test-app",
+        version: "1.0.0",
+        commands: [cmd],
+      });
+      
+      await app.run(["--detailed-logs", "test"]);
+      // Should not throw - flag is recognized
+      expect(cmd.executedWith).not.toBeNull();
+    });
+
+    test("parses --no-detailed-logs flag", async () => {
+      const cmd = new TestCommand();
+      const app = new Application({
+        name: "test-app",
+        version: "1.0.0",
+        commands: [cmd],
+      });
+      
+      await app.run(["--no-detailed-logs", "test"]);
+      // Should not throw - flag is recognized
+      expect(cmd.executedWith).not.toBeNull();
+    });
+
+    test("parses --log-level=value format", async () => {
+      const cmd = new TestCommand();
+      const app = new Application({
+        name: "test-app",
+        version: "1.0.0",
+        commands: [cmd],
+      });
+      
+      await app.run(["--log-level=warn", "test"]);
+      expect(app.context.logger.getMinLevel()).toBe(4); // Warn = 4
+    });
+  });
+});

package/src/__tests__/buildCliCommand.test.ts

@@ -0,0 +1,125 @@
+import { describe, test, expect } from "bun:test";
+import { buildCliCommand } from "../tui/utils/buildCliCommand.ts";
+import type { OptionSchema } from "../types/command.ts";
+
+describe("buildCliCommand", () => {
+    test("builds command with no options", () => {
+        const result = buildCliCommand("myapp", ["run"], {}, {});
+        expect(result).toBe("myapp run");
+    });
+
+    test("includes string options", () => {
+        const schema: OptionSchema = {
+            name: { type: "string", description: "Name" },
+        };
+        const values = { name: "John" };
+        
+        const result = buildCliCommand("myapp", ["greet"], schema, values);
+        expect(result).toBe("myapp greet --name John");
+    });
+
+    test("quotes string values with spaces", () => {
+        const schema: OptionSchema = {
+            name: { type: "string", description: "Name" },
+        };
+        const values = { name: "John Doe" };
+        
+        const result = buildCliCommand("myapp", ["greet"], schema, values);
+        expect(result).toBe("myapp greet --name \"John Doe\"");
+    });
+
+    test("excludes empty string values", () => {
+        const schema: OptionSchema = {
+            name: { type: "string", description: "Name" },
+        };
+        const values = { name: "" };
+        
+        const result = buildCliCommand("myapp", ["greet"], schema, values);
+        expect(result).toBe("myapp greet");
+    });
+
+    test("includes boolean flags only when true", () => {
+        const schema: OptionSchema = {
+            verbose: { type: "boolean", description: "Verbose" },
+            quiet: { type: "boolean", description: "Quiet" },
+        };
+        const values = { verbose: true, quiet: false };
+        
+        const result = buildCliCommand("myapp", ["run"], schema, values);
+        expect(result).toBe("myapp run --verbose");
+    });
+
+    test("includes number values", () => {
+        const schema: OptionSchema = {
+            count: { type: "number", description: "Count" },
+        };
+        const values = { count: 42 };
+        
+        const result = buildCliCommand("myapp", ["process"], schema, values);
+        expect(result).toBe("myapp process --count 42");
+    });
+
+    test("excludes undefined and null values", () => {
+        const schema: OptionSchema = {
+            name: { type: "string", description: "Name" },
+            count: { type: "number", description: "Count" },
+        };
+        const values = { name: undefined, count: null };
+        
+        const result = buildCliCommand("myapp", ["run"], schema, values);
+        expect(result).toBe("myapp run");
+    });
+
+    test("handles array values", () => {
+        const schema: OptionSchema = {
+            files: { type: "array", description: "Files" },
+        };
+        const values = { files: ["a.txt", "b.txt"] };
+        
+        const result = buildCliCommand("myapp", ["process"], schema, values);
+        expect(result).toBe("myapp process --files a.txt --files b.txt");
+    });
+
+    test("handles nested command path", () => {
+        const schema: OptionSchema = {
+            force: { type: "boolean", description: "Force" },
+        };
+        const values = { force: true };
+        
+        const result = buildCliCommand("myapp", ["db", "migrate"], schema, values);
+        expect(result).toBe("myapp db migrate --force");
+    });
+
+    test("converts camelCase to kebab-case", () => {
+        const schema: OptionSchema = {
+            outputDir: { type: "string", description: "Output directory" },
+            maxRetries: { type: "number", description: "Max retries" },
+        };
+        const values = { outputDir: "/tmp", maxRetries: 3 };
+        
+        const result = buildCliCommand("myapp", ["build"], schema, values);
+        expect(result).toContain("--output-dir /tmp");
+        expect(result).toContain("--max-retries 3");
+    });
+
+    test("skips values that match defaults", () => {
+        const schema: OptionSchema = {
+            verbose: { type: "boolean", description: "Verbose", default: false },
+            count: { type: "number", description: "Count", default: 10 },
+        };
+        const values = { verbose: false, count: 10 };
+        
+        const result = buildCliCommand("myapp", ["run"], schema, values);
+        expect(result).toBe("myapp run");
+    });
+
+    test("uses --no-flag for false when default is true", () => {
+        const schema: OptionSchema = {
+            color: { type: "boolean", description: "Color output", default: true },
+        };
+        const values = { color: false };
+        
+        const result = buildCliCommand("myapp", ["run"], schema, values);
+        expect(result).toBe("myapp run --no-color");
+    });
+});