@pablozaiden/terminatui 0.1.0

package/examples/tui-app/commands/status.ts

@@ -0,0 +1,75 @@
+import { 
+    Command, 
+    type AppContext, 
+    type OptionSchema, 
+    type OptionValues,
+    type CommandResult 
+} from "../../../src/index.ts";
+
+const statusOptions = {
+    detailed: {
+        type: "boolean",
+        description: "Show detailed status",
+        default: false,
+        label: "Detailed",
+        order: 1,
+    },
+} as const satisfies OptionSchema;
+
+export class StatusCommand extends Command<typeof statusOptions> {
+    readonly name = "status";
+    readonly description = "Show application status";
+    readonly options = statusOptions;
+
+    override readonly actionLabel = "Check Status";
+    override readonly immediateExecution = true; // No required fields
+
+    override async execute(ctx: AppContext, opts: OptionValues<typeof statusOptions>): Promise<CommandResult> {
+        const result = await this.getStatus(opts);
+        ctx.logger.info(result.message || "Status check complete");
+        return result;
+    }
+
+    override renderResult(result: CommandResult): string {
+        if (!result.success) return "❌ Status check failed";
+        const data = result.data as { uptime: string; memory: string; platform: string; version: string };
+        return [
+            "✓ Application Status",
+            "",
+            `  Uptime:   ${data.uptime}`,
+            `  Memory:   ${data.memory}`,
+            `  Platform: ${data.platform}`,
+            `  Node:     ${data.version}`,
+        ].join("\n");
+    }
+
+    private async getStatus(opts: OptionValues<typeof statusOptions>): Promise<CommandResult> {
+        const detailed = opts.detailed as boolean;
+        
+        // Simulate some async work
+        await new Promise((resolve) => setTimeout(resolve, 500));
+
+        const memMB = Math.round(process.memoryUsage().heapUsed / 1024 / 1024);
+        const uptimeSec = Math.round(process.uptime());
+
+        const data: Record<string, unknown> = {
+            uptime: `${uptimeSec} seconds`,
+            memory: `${memMB} MB`,
+            platform: process.platform,
+            version: Bun.version,
+        };
+
+        if (detailed) {
+            Object.assign(data, {
+                cwd: process.cwd(),
+                pid: process.pid,
+            });
+        }
+
+        return {
+            success: true,
+            data,
+            message: "All systems operational",
+        };
+    }
+}

package/examples/tui-app/index.ts

@@ -0,0 +1,34 @@
+#!/usr/bin/env bun
+/**
+ * Example TUI Application
+ * 
+ * Demonstrates how to use TuiApplication to build a CLI/TUI app
+ * with minimal effort. Just run:
+ * 
+ *   bun examples/tui-app/index.ts
+ * 
+ * Or in CLI mode:
+ * 
+ *   bun examples/tui-app/index.ts greet --name "World" --loud
+ */
+
+import { TuiApplication } from "../../src/index.ts";
+import { GreetCommand, MathCommand, StatusCommand } from "./commands/index.ts";
+
+class ExampleApp extends TuiApplication {
+    constructor() {
+        super({
+            name: "example",
+            version: "1.0.0",
+            commands: [
+                new GreetCommand(),
+                new MathCommand(),
+                new StatusCommand(),
+            ],
+            enableTui: true,
+        });
+    }
+}
+
+// Run the app
+await new ExampleApp().run(Bun.argv.slice(2));

package/guides/01-hello-world.md

@@ -0,0 +1,96 @@
+# Guide 1: Hello World CLI (Super Simple)
+
+Create your first CLI app with Terminatui in under 5 minutes.
+
+## What You'll Build
+
+A simple CLI that greets the user by name.
+
+```bash
+myapp greet --name Alice
+# Output: Hello, Alice!
+```
+
+## Prerequisites
+
+- Bun installed (`curl -fsSL https://bun.sh/install | bash`)
+
+## Step 1: Create Project
+
+```bash
+mkdir hello-cli && cd hello-cli
+bun init -y
+bun add @pablozaiden/terminatui
+```
+
+## Step 2: Create the Command
+
+Create `src/greet.ts`:
+
+```typescript
+import { Command, type AppContext, type OptionSchema, type CommandResult } from "@pablozaiden/terminatui";
+
+const options = {
+  name: {
+    type: "string",
+    description: "Name to greet",
+    required: true,
+  },
+} satisfies OptionSchema;
+
+export class GreetCommand extends Command<typeof options> {
+  readonly name = "greet";
+  readonly description = "Greet someone";
+  readonly options = options;
+
+  execute(_ctx: AppContext, config: { name: string }): CommandResult {
+    console.log(`Hello, ${config.name}!`);
+    return { success: true };
+  }
+}
+```
+
+## Step 3: Create the App
+
+Create `src/index.ts`:
+
+```typescript
+import { Application } from "@pablozaiden/terminatui";
+import { GreetCommand } from "./greet";
+
+class MyApp extends Application {
+  constructor() {
+    super({
+      name: "myapp",
+      version: "1.0.0",
+      commands: [new GreetCommand()],
+    });
+  }
+}
+
+await new MyApp().run();
+```
+
+## Step 4: Run It
+
+```bash
+bun src/index.ts greet --name Alice
+# Output: Hello, Alice!
+
+bun src/index.ts help
+# Shows available commands
+
+bun src/index.ts greet help
+# Shows greet options
+```
+
+## What You Learned
+
+- Commands extend the `Command` class
+- Options are defined with `OptionSchema`
+- The `execute()` method handles the logic
+- `Application` ties everything together
+
+## Next Steps
+
+→ [Guide 2: Adding Options](02-adding-options.md)

package/guides/02-adding-options.md

@@ -0,0 +1,103 @@
+# Guide 2: Adding Options (Super Simple)
+
+Add boolean and string options to make your CLI more flexible.
+
+## What You'll Build
+
+Extend the greeting command with a `--loud` flag:
+
+```bash
+myapp greet --name Alice
+# Output: Hello, Alice!
+
+myapp greet --name Alice --loud
+# Output: HELLO, ALICE!
+```
+
+## Step 1: Add the Option
+
+Update `src/greet.ts`:
+
+```typescript
+import { Command, type AppContext, type OptionSchema, type CommandResult } from "@pablozaiden/terminatui";
+
+const options = {
+  name: {
+    type: "string",
+    description: "Name to greet",
+    required: true,
+  },
+  loud: {
+    type: "boolean",
+    description: "Shout the greeting",
+    alias: "l",        // Short flag: -l
+    default: false,
+  },
+} satisfies OptionSchema;
+
+export class GreetCommand extends Command<typeof options> {
+  readonly name = "greet";
+  readonly description = "Greet someone";
+  readonly options = options;
+
+  execute(_ctx: AppContext, config: { name: string; loud: boolean }): CommandResult {
+    const message = `Hello, ${config.name}!`;
+    console.log(config.loud ? message.toUpperCase() : message);
+    return { success: true };
+  }
+}
+```
+
+## Step 2: Test It
+
+```bash
+# Normal greeting
+bun src/index.ts greet --name Alice
+# Hello, Alice!
+
+# Loud greeting with long flag
+bun src/index.ts greet --name Bob --loud
+# HELLO, BOB!
+
+# Loud greeting with short flag
+bun src/index.ts greet --name Charlie -l
+# HELLO, CHARLIE!
+
+# View help to see options
+bun src/index.ts greet help
+```
+
+## Key Concepts
+
+### Option Types
+
+| Type | Description | Example |
+|------|-------------|---------|
+| `string` | Text value | `--name Alice` |
+| `boolean` | Flag (true/false) | `--loud` or `--no-loud` |
+| `number` | Numeric value | `--count 5` |
+| `array` | Multiple values | `--tags a --tags b` |
+
+### Option Properties
+
+```typescript
+{
+  type: "string",
+  description: "Help text",   // Required
+  required: true,             // Must be provided
+  default: "value",           // Default if not provided
+  alias: "n",                 // Short flag (-n)
+  enum: ["a", "b", "c"],      // Restrict to values
+}
+```
+
+## What You Learned
+
+- Add options with different types
+- Use `alias` for short flags (-l instead of --loud)
+- Use `default` for optional values
+- Boolean flags can be negated with `--no-` prefix
+
+## Next Steps
+
+→ [Guide 3: Multiple Commands](03-multiple-commands.md)

package/guides/03-multiple-commands.md

@@ -0,0 +1,163 @@
+# Guide 3: Multiple Commands (Basic)
+
+Build a CLI with multiple commands that share common functionality.
+
+## What You'll Build
+
+A file utility CLI with `list` and `count` commands:
+
+```bash
+fileutil list --dir ./src
+# Lists files in directory
+
+fileutil count --dir ./src --ext .ts
+# Counts files with extension
+```
+
+## Step 1: Create the List Command
+
+Create `src/commands/list.ts`:
+
+```typescript
+import { readdirSync } from "fs";
+import { Command, type AppContext, type OptionSchema, type CommandResult } from "@pablozaiden/terminatui";
+
+const options = {
+  dir: {
+    type: "string",
+    description: "Directory to list",
+    required: true,
+    alias: "d",
+  },
+} satisfies OptionSchema;
+
+export class ListCommand extends Command<typeof options> {
+  readonly name = "list";
+  readonly description = "List files in a directory";
+  readonly options = options;
+
+  execute(_ctx: AppContext, config: { dir: string }): CommandResult {
+    try {
+      const files = readdirSync(config.dir);
+      console.log(`Files in ${config.dir}:`);
+      files.forEach((file) => console.log(`  ${file}`));
+      return { success: true, message: `Found ${files.length} files` };
+    } catch (error) {
+      return { success: false, error: String(error) };
+    }
+  }
+}
+```
+
+## Step 2: Create the Count Command
+
+Create `src/commands/count.ts`:
+
+```typescript
+import { readdirSync } from "fs";
+import { Command, type AppContext, type OptionSchema, type CommandResult } from "@pablozaiden/terminatui";
+
+const options = {
+  dir: {
+    type: "string",
+    description: "Directory to search",
+    required: true,
+    alias: "d",
+  },
+  ext: {
+    type: "string",
+    description: "File extension to count (e.g., .ts)",
+    alias: "e",
+  },
+} satisfies OptionSchema;
+
+export class CountCommand extends Command<typeof options> {
+  readonly name = "count";
+  readonly description = "Count files in a directory";
+  readonly options = options;
+
+  execute(_ctx: AppContext, config: { dir: string; ext?: string }): CommandResult {
+    try {
+      let files = readdirSync(config.dir);
+      
+      if (config.ext) {
+        files = files.filter((f) => f.endsWith(config.ext!));
+      }
+      
+      console.log(`Found ${files.length} files${config.ext ? ` with ${config.ext}` : ""}`);
+      return { success: true, data: { count: files.length } };
+    } catch (error) {
+      return { success: false, error: String(error) };
+    }
+  }
+}
+```
+
+## Step 3: Create the Application
+
+Create `src/index.ts`:
+
+```typescript
+import { Application } from "@pablozaiden/terminatui";
+import { ListCommand } from "./commands/list";
+import { CountCommand } from "./commands/count";
+
+class FileUtilApp extends Application {
+  constructor() {
+    super({
+      name: "fileutil",
+      version: "1.0.0",
+      description: "File utility commands",
+      commands: [
+        new ListCommand(),
+        new CountCommand(),
+      ],
+    });
+  }
+}
+
+await new FileUtilApp().run();
+```
+
+## Step 4: Test It
+
+```bash
+# List files
+bun src/index.ts list --dir ./src
+# Files in ./src:
+#   commands
+#   index.ts
+
+# Count all files
+bun src/index.ts count -d ./src
+# Found 2 files
+
+# Count only .ts files
+bun src/index.ts count -d ./src -e .ts
+# Found 1 files with .ts
+
+# Show help
+bun src/index.ts help
+# Lists: list, count, version, help
+```
+
+## Project Structure
+
+```
+src/
+├── index.ts           # App entry point
+└── commands/
+    ├── list.ts        # List command
+    └── count.ts       # Count command
+```
+
+## What You Learned
+
+- Create multiple commands in separate files
+- Return structured `CommandResult` with data
+- Handle errors gracefully
+- Use consistent option patterns across commands
+
+## Next Steps
+
+→ [Guide 4: Subcommands](04-subcommands.md)

package/guides/04-subcommands.md

@@ -0,0 +1,206 @@
+# Guide 4: Subcommands (Basic)
+
+Organize related commands under a parent command for cleaner CLI structure.
+
+## What You'll Build
+
+A database CLI with nested subcommands:
+
+```bash
+dbctl db migrate --target latest
+dbctl db seed --file data.json
+dbctl db status
+```
+
+## Step 1: Create the Subcommands
+
+Create `src/commands/db/migrate.ts`:
+
+```typescript
+import { Command, type AppContext, type OptionSchema, type CommandResult } from "@pablozaiden/terminatui";
+
+const options = {
+  target: {
+    type: "string",
+    description: "Migration target version",
+    default: "latest",
+  },
+  dry: {
+    type: "boolean",
+    description: "Dry run without applying",
+    default: false,
+  },
+} satisfies OptionSchema;
+
+export class MigrateCommand extends Command<typeof options> {
+  readonly name = "migrate";
+  readonly description = "Run database migrations";
+  readonly options = options;
+
+  execute(ctx: AppContext, config: { target: string; dry: boolean }): CommandResult {
+    ctx.logger.info(`Migrating to: ${config.target}`);
+    
+    if (config.dry) {
+      console.log("DRY RUN: Would migrate to", config.target);
+    } else {
+      console.log("Migrating to", config.target, "...");
+      console.log("Migration complete!");
+    }
+    
+    return { success: true };
+  }
+}
+```
+
+Create `src/commands/db/seed.ts`:
+
+```typescript
+import { Command, type AppContext, type OptionSchema, type CommandResult } from "@pablozaiden/terminatui";
+
+const options = {
+  file: {
+    type: "string",
+    description: "Seed data file",
+    required: true,
+    alias: "f",
+  },
+} satisfies OptionSchema;
+
+export class SeedCommand extends Command<typeof options> {
+  readonly name = "seed";
+  readonly description = "Seed the database with data";
+  readonly options = options;
+
+  execute(ctx: AppContext, config: { file: string }): CommandResult {
+    ctx.logger.info(`Seeding from: ${config.file}`);
+    console.log(`Loading seed data from ${config.file}...`);
+    console.log("Database seeded successfully!");
+    return { success: true };
+  }
+}
+```
+
+Create `src/commands/db/status.ts`:
+
+```typescript
+import { Command, type AppContext, type CommandResult } from "@pablozaiden/terminatui";
+
+export class StatusCommand extends Command {
+  readonly name = "status";
+  readonly description = "Show database status";
+  readonly options = {};
+
+  execute(_ctx: AppContext): CommandResult {
+    console.log("Database Status:");
+    console.log("  Connected: Yes");
+    console.log("  Version: 1.2.3");
+    console.log("  Migrations: 5 applied");
+    return { success: true };
+  }
+}
+```
+
+## Step 2: Create the Parent Command
+
+Create `src/commands/db/index.ts`:
+
+```typescript
+import { Command, type AppContext, type CommandResult } from "@pablozaiden/terminatui";
+import { MigrateCommand } from "./migrate";
+import { SeedCommand } from "./seed";
+import { StatusCommand } from "./status";
+
+export class DbCommand extends Command {
+  readonly name = "db";
+  readonly description = "Database operations";
+  readonly options = {};
+  
+  // Subcommands are nested here
+  override readonly subCommands = [
+    new MigrateCommand(),
+    new SeedCommand(),
+    new StatusCommand(),
+  ];
+
+  // Parent command can have its own execute (optional)
+  execute(_ctx: AppContext): CommandResult {
+    console.log("Use 'dbctl db <command>' for database operations.");
+    console.log("Available: migrate, seed, status");
+    return { success: true };
+  }
+}
+```
+
+## Step 3: Create the Application
+
+Create `src/index.ts`:
+
+```typescript
+import { Application } from "@pablozaiden/terminatui";
+import { DbCommand } from "./commands/db";
+
+class DbCtlApp extends Application {
+  constructor() {
+    super({
+      name: "dbctl",
+      version: "1.0.0",
+      description: "Database control CLI",
+      commands: [new DbCommand()],
+    });
+  }
+}
+
+await new DbCtlApp().run();
+```
+
+## Step 4: Test It
+
+```bash
+# Show db command help
+bun src/index.ts db help
+# Shows: migrate, seed, status
+
+# Run migration
+bun src/index.ts db migrate
+# Migrating to latest...
+
+# Dry run migration
+bun src/index.ts db migrate --target v2 --dry
+# DRY RUN: Would migrate to v2
+
+# Seed database
+bun src/index.ts db seed -f data.json
+# Loading seed data from data.json...
+
+# Check status
+bun src/index.ts db status
+# Database Status: ...
+
+# Get help for subcommand
+bun src/index.ts db migrate help
+# Shows migrate options
+```
+
+## Project Structure
+
+```
+src/
+├── index.ts
+└── commands/
+    └── db/
+        ├── index.ts    # Parent command
+        ├── migrate.ts  # Subcommand
+        ├── seed.ts     # Subcommand
+        └── status.ts   # Subcommand
+```
+
+## What You Learned
+
+- Group related commands under a parent
+- Define subcommands with `subCommands` property
+- Each subcommand has its own options
+- Help is automatically nested (`db help`, `db migrate help`)
+
+## Next Steps
+
+→ [Guide 5: Interactive TUI](05-interactive-tui.md)