@pablozaiden/terminatui 0.3.0-beta-1 → 0.3.0

package/guides/03-multiple-commands.md

@@ -1,161 +0,0 @@
-# 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 { Command, 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;
-
-  async execute(config: { dir: string }): Promise<CommandResult> {
-    try {
-      const files = await Array.fromAsync(new Bun.Glob("*").scan({ cwd: config.dir, onlyFiles: false }));
-      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 { Command, 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;
-
-  async execute(config: { dir: string; ext?: string }): Promise<CommandResult> {
-    try {
-      let files = await Array.fromAsync(new Bun.Glob("*").scan({ cwd: config.dir, onlyFiles: false }));
-      
-      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

@@ -1,206 +0,0 @@
-# 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 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(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 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(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 CommandResult } from "@pablozaiden/terminatui";
-
-export class StatusCommand extends Command {
-  readonly name = "status";
-  readonly description = "Show database status";
-  readonly options = {};
-
-  execute(): 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 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(): 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)

package/guides/05-interactive-tui.md

@@ -1,209 +0,0 @@
-# Guide 5: Interactive TUI
-
-Add an auto-generated Terminal User Interface to your CLI.
-
-## What You'll Build
-
-A task runner with both CLI and interactive TUI modes:
-
-```bash
-# CLI mode
-taskr --mode cli run --task build --env production
-
-# TUI mode
-# (if your app's default mode is a TUI mode)
- taskr
-
-# Force TUI mode
- taskr --mode opentui
- # or
- taskr --mode ink
-
-# Force CLI mode
- taskr --mode cli
-```
-
-Only the selected mode (`--mode`) or your app's default mode controls whether the app runs in CLI or TUI.
-
-## Step 1: Create the Command with TUI Metadata
-
-Create `src/commands/run.ts`:
-
-```typescript
-import {
-  Command,
-  type OptionSchema,
-  type CommandResult,
-  type CommandExecutionContext,
-} from "@pablozaiden/terminatui";
-
-const options = {
-  task: {
-    type: "string",
-    description: "Task to run",
-    required: true,
-    enum: ["build", "test", "lint", "deploy"],
-    // TUI metadata
-    label: "Task",
-    order: 1,
-    group: "Required",
-  },
-  env: {
-    type: "string",
-    description: "Environment",
-    default: "development",
-    enum: ["development", "staging", "production"],
-    // TUI metadata
-    label: "Environment",
-    order: 2,
-    group: "Configuration",
-  },
-  verbose: {
-    type: "boolean",
-    description: "Verbose output",
-    default: false,
-    // TUI metadata
-    label: "Verbose Mode",
-    order: 10,
-    group: "Options",
-  },
-} satisfies OptionSchema;
-
-interface RunConfig {
-  task: string;
-  env: string;
-  verbose: boolean;
-}
-
-export class RunCommand extends Command<typeof options, RunConfig> {
-  readonly name = "run";
-  readonly description = "Run a task";
-  readonly options = options;
-
-  // TUI customization
-  override readonly displayName = "Run Task";
-  override readonly actionLabel = "Start Task";
-
-  async execute(config: RunConfig, _execCtx: CommandExecutionContext): Promise<CommandResult> {
-    if (config.verbose) {
-      console.debug(`Environment: ${config.env}`);
-    }
-
-    // Simulate task execution
-    console.log(`Running ${config.task} in ${config.env}...`);
-    await new Promise((resolve) => setTimeout(resolve, 1000));
-    console.log("Task completed!");
-
-    return {
-      success: true,
-      data: { task: config.task, env: config.env },
-      message: `Task ${config.task} completed successfully`,
-    };
-  }
-}
-```
-
-## Step 2: Create the TUI Application
-
-Create `src/index.ts`:
-
-```typescript
-import { TuiApplication } from "@pablozaiden/terminatui";
-import { RunCommand } from "./commands/run";
-
-class TaskRunnerApp extends TuiApplication {
-  // Default is CLI; each app decides.
-  protected override defaultMode = "opentui" as const;
-
-  constructor() {
-    super({
-      name: "taskr",
-      displayName: "🚀 Task Runner", // Shown in TUI header
-      version: "1.0.0",
-      commands: [new RunCommand()],
-      enableTui: true, // Default: true
-    });
-  }
-}
-
-await new TaskRunnerApp().run();
-```
-
-## Step 3: Test Both Modes
-
-**CLI Mode** (forced):
-
-```bash
-bun src/index.ts --mode cli run --task build --env production
-# Running build in production...
-# Task completed!
-```
-
-**TUI Mode** (forced):
-
-```bash
-bun src/index.ts --mode opentui
-```
-
-This opens an interactive interface:
-- Use ↑/↓ to navigate fields
-- Press Enter to edit a field
-- Navigate to "CLI Command" button and press Enter to see the CLI command
-- Press Enter on "Start Task" to run
-- Press Esc to go back
-
-## TUI Metadata Reference
-
-Add these properties to your options for TUI customization:
-
-```typescript
-{
-  type: "string",
-  description: "...",
-
-  // TUI-specific
-  label: "Display Label", // Custom field label
-  order: 1, // Field sort order
-  group: "Settings", // Group heading
-  placeholder: "Enter...", // Placeholder text
-  tuiHidden: false, // Hide from TUI (still in CLI)
-}
-```
-
-## Command TUI Properties
-
-```typescript
-class MyCommand extends Command {
-  // Display name in command selector
-  override readonly displayName = "My Command";
-
-  // Button text (default: "Run")
-  override readonly actionLabel = "Execute";
-
-  // Skip config screen, run immediately
-  override readonly immediateExecution = false;
-}
-```
-
-## Keyboard Shortcuts
-
-| Key | Action |
-|-----|--------|
-| ↑/↓ | Navigate fields |
-| Enter | Edit field / Press button / Run |
-| Tab | Cycle focus |
-| L | Toggle logs |
-| Ctrl+Y | Copy to clipboard |
-| Esc | Back / Cancel |
-
-## What You Learned
-
-- Use `TuiApplication` instead of `Application`
-- Use `--mode` (or app default mode) to control CLI vs TUI
-- Add TUI metadata to options (label, order, group)
-- Customize with `displayName` and `actionLabel`
-- Both CLI and TUI work with the same command
-
-## Next Steps
-
-→ [Guide 6: Config Validation](06-config-validation.md)