@pablozaiden/terminatui 0.2.0 → 0.3.0

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 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)

package/guides/05-interactive-tui.md

@@ -1,194 +0,0 @@
-# Guide 5: Interactive TUI (Normal)
-
-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 run --task build --env production
-
-# TUI mode (interactive)
-taskr
-```
-
-When you run without arguments, an interactive form appears!
-
-## Step 1: Create the Command with TUI Metadata
-
-Create `src/commands/run.ts`:
-
-```typescript
-import { Command, type AppContext, type OptionSchema, type CommandResult } 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(ctx: AppContext, config: RunConfig): Promise<CommandResult> {
-    ctx.logger.info(`Starting task: ${config.task}`);
-    
-    if (config.verbose) {
-      ctx.logger.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 {
-  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** (with arguments):
-
-```bash
-bun src/index.ts run --task build --env production
-# Running build in production...
-# Task completed!
-```
-
-**TUI Mode** (no arguments):
-
-```bash
-bun src/index.ts
-```
-
-This opens an interactive interface:
-- Use ↑/↓ to navigate fields
-- Press Enter to edit a field
-- Press Enter on "Start Task" to run
-- Press Esc to go back
-- Press C to see the CLI command
-
-## 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 / Run |
-| Tab | Cycle focus |
-| C | Show CLI command |
-| L | Toggle logs |
-| Ctrl+Y | Copy to clipboard |
-| Esc | Back / Cancel |
-
-## What You Learned
-
-- Use `TuiApplication` instead of `Application`
-- 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)

package/guides/06-config-validation.md

@@ -1,264 +0,0 @@
-# Guide 6: Config Validation (Normal)
-
-Transform and validate options before execution with `buildConfig`.
-
-## What You'll Build
-
-A deploy CLI that validates paths, resolves environment configs, and provides helpful error messages:
-
-```bash
-deploy --app ./myapp --env production --replicas 3
-```
-
-## Step 1: Define Options and Config Types
-
-Create `src/commands/deploy.ts`:
-
-```typescript
-import path from "node:path";
-import { existsSync } from "node:fs";
-import { 
-  Command, 
-  ConfigValidationError,
-  type AppContext, 
-  type OptionSchema, 
-  type OptionValues,
-  type CommandResult 
-} from "@pablozaiden/terminatui";
-
-// Raw CLI options
-const options = {
-  app: {
-    type: "string",
-    description: "Path to application",
-    required: true,
-  },
-  env: {
-    type: "string",
-    description: "Deployment environment",
-    required: true,
-    enum: ["development", "staging", "production"],
-  },
-  replicas: {
-    type: "string",  // CLI args are strings
-    description: "Number of replicas",
-    default: "1",
-  },
-  "dry-run": {
-    type: "boolean",
-    description: "Preview without deploying",
-    default: false,
-  },
-} satisfies OptionSchema;
-
-// Validated config type
-interface DeployConfig {
-  appPath: string;        // Resolved absolute path
-  appName: string;        // Extracted from path
-  environment: string;
-  replicas: number;       // Parsed to number
-  dryRun: boolean;
-  envConfig: {            // Environment-specific settings
-    url: string;
-    timeout: number;
-  };
-}
-```
-
-## Step 2: Implement buildConfig
-
-```typescript
-// Environment-specific configurations
-const ENV_CONFIGS = {
-  development: { url: "http://localhost:3000", timeout: 5000 },
-  staging: { url: "https://staging.example.com", timeout: 10000 },
-  production: { url: "https://example.com", timeout: 30000 },
-};
-
-export class DeployCommand extends Command<typeof options, DeployConfig> {
-  readonly name = "deploy";
-  readonly description = "Deploy an application";
-  readonly options = options;
-
-  /**
-   * Transform and validate raw options into DeployConfig.
-   * Runs before execute() - errors here show helpful messages.
-   */
-  override buildConfig(
-    _ctx: AppContext, 
-    opts: OptionValues<typeof options>
-  ): DeployConfig {
-    // 1. Validate app path exists
-    const appRaw = opts["app"] as string | undefined;
-    if (!appRaw) {
-      throw new ConfigValidationError(
-        "Missing required option: app",
-        "app"  // Field to highlight in TUI
-      );
-    }
-    
-    const appPath = path.resolve(appRaw);
-    if (!existsSync(appPath)) {
-      throw new ConfigValidationError(
-        `Application path does not exist: ${appPath}`,
-        "app"
-      );
-    }
-
-    // 2. Extract app name from path
-    const appName = path.basename(appPath);
-
-    // 3. Validate environment
-    const environment = opts["env"] as string;
-    if (!environment) {
-      throw new ConfigValidationError(
-        "Missing required option: env",
-        "env"
-      );
-    }
-
-    // 4. Parse and validate replicas
-    const replicasStr = opts["replicas"] as string ?? "1";
-    const replicas = parseInt(replicasStr, 10);
-    
-    if (isNaN(replicas)) {
-      throw new ConfigValidationError(
-        `Replicas must be a number, got: ${replicasStr}`,
-        "replicas"
-      );
-    }
-    
-    if (replicas < 1 || replicas > 10) {
-      throw new ConfigValidationError(
-        "Replicas must be between 1 and 10",
-        "replicas"
-      );
-    }
-
-    // 5. Get environment-specific config
-    const envConfig = ENV_CONFIGS[environment as keyof typeof ENV_CONFIGS];
-
-    // 6. Return validated config
-    return {
-      appPath,
-      appName,
-      environment,
-      replicas,
-      dryRun: opts["dry-run"] as boolean ?? false,
-      envConfig,
-    };
-  }
-```
-
-## Step 3: Implement execute with clean config
-
-```typescript
-  /**
-   * Execute with fully validated DeployConfig.
-   * No need to validate here - buildConfig already did it!
-   */
-  async execute(ctx: AppContext, config: DeployConfig): Promise<CommandResult> {
-    ctx.logger.info(`Deploying ${config.appName} to ${config.environment}`);
-    ctx.logger.debug(`Path: ${config.appPath}`);
-    ctx.logger.debug(`Replicas: ${config.replicas}`);
-    ctx.logger.debug(`URL: ${config.envConfig.url}`);
-
-    if (config.dryRun) {
-      console.log("DRY RUN - Would deploy:");
-      console.log(`  App: ${config.appName}`);
-      console.log(`  Environment: ${config.environment}`);
-      console.log(`  Replicas: ${config.replicas}`);
-      console.log(`  Target: ${config.envConfig.url}`);
-      return { success: true, message: "Dry run completed" };
-    }
-
-    console.log(`Deploying ${config.appName}...`);
-    console.log(`  Creating ${config.replicas} replicas...`);
-    console.log(`  Targeting ${config.envConfig.url}...`);
-    
-    // Simulate deployment
-    await new Promise((resolve) => setTimeout(resolve, 2000));
-    
-    console.log("Deployment successful!");
-
-    return { 
-      success: true,
-      data: {
-        app: config.appName,
-        environment: config.environment,
-        replicas: config.replicas,
-        url: config.envConfig.url,
-      },
-      message: `Deployed ${config.appName} to ${config.environment}`
-    };
-  }
-}
-```
-
-## Step 4: Create the Application
-
-Create `src/index.ts`:
-
-```typescript
-import { TuiApplication } from "@pablozaiden/terminatui";
-import { DeployCommand } from "./commands/deploy";
-
-class DeployCLI extends TuiApplication {
-  constructor() {
-    super({
-      name: "deploy",
-      version: "1.0.0",
-      commands: [new DeployCommand()],
-    });
-  }
-}
-
-await new DeployCLI().run();
-```
-
-## Step 5: Test Validation
-
-```bash
-# Missing required option
-bun src/index.ts deploy --env production
-# Error: Missing required option: app
-
-# Invalid path
-bun src/index.ts deploy --app ./nonexistent --env staging
-# Error: Application path does not exist: /path/to/nonexistent
-
-# Invalid replicas
-bun src/index.ts deploy --app . --env production --replicas abc
-# Error: Replicas must be a number, got: abc
-
-# Out of range replicas
-bun src/index.ts deploy --app . --env production --replicas 100
-# Error: Replicas must be between 1 and 10
-
-# Dry run (valid)
-bun src/index.ts deploy --app . --env production --replicas 3 --dry-run
-# DRY RUN - Would deploy: ...
-
-# Full deploy
-bun src/index.ts deploy --app . --env staging --replicas 2
-# Deploying myapp...
-```
-
-## Benefits of buildConfig
-
-1. **Separation of concerns** - Validation separate from logic
-2. **Type safety** - `execute()` receives validated `DeployConfig`
-3. **Better errors** - `ConfigValidationError` highlights fields in TUI
-4. **Reusable** - Works for both CLI and TUI modes
-5. **Testable** - Easy to unit test validation logic
-
-## What You Learned
-
-- Use `buildConfig` to transform and validate options
-- Throw `ConfigValidationError` with field name for TUI highlighting
-- Parse strings to numbers and resolve paths
-- Keep `execute()` clean with pre-validated config
-
-## Next Steps
-
-→ [Guide 7: Async Commands with Cancellation](07-async-cancellation.md)