@pablozaiden/terminatui 0.3.0-beta-1 → 0.3.0

package/guides/06-config-validation.md

@@ -1,256 +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 { 
-  Command, 
-  ConfigValidationError,
-  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 async buildConfig(opts: OptionValues<typeof options>): Promise<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 (!(await Bun.file(appPath).exists())) {
-      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(config: DeployConfig): Promise<CommandResult> {
-    console.log(`Deploying ${config.appName} to ${config.environment}`);
-
-    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)

package/guides/07-async-cancellation.md

@@ -1,334 +0,0 @@
-# Guide 7: Async Commands with Cancellation (Complex)
-
-Build commands that support cancellation with proper cleanup for long-running operations.
-
-## What You'll Build
-
-A download manager that:
-- Downloads files asynchronously
-- Shows progress updates
-- Supports cancellation (Ctrl+C in CLI, Esc in TUI)
-- Cleans up partial downloads when cancelled
-
-```bash
-download https://example.com/large-file.zip --output ./downloads/
-```
-
-## Step 1: Define the Command
-
-Create `src/commands/download.ts`:
-
-```typescript
-import path from "node:path";
-import { 
-  Command, 
-  ConfigValidationError,
-  type OptionSchema, 
-  type OptionValues,
-  type CommandResult,
-  type CommandExecutionContext 
-} from "@pablozaiden/terminatui";
-
-const options = {
-  url: {
-    type: "string",
-    description: "URL to download",
-    required: true,
-    label: "Download URL",
-  },
-  output: {
-    type: "string",
-    description: "Output directory",
-    default: "./downloads",
-    label: "Output Directory",
-  },
-  "chunk-size": {
-    type: "string",
-    description: "Download chunk size in KB",
-    default: "1024",
-    label: "Chunk Size (KB)",
-  },
-} satisfies OptionSchema;
-
-interface DownloadConfig {
-  url: URL;
-  outputDir: string;
-  fileName: string;
-  chunkSize: number;
-}
-```
-
-## Step 2: Implement buildConfig
-
-```typescript
-export class DownloadCommand extends Command<typeof options, DownloadConfig> {
-  readonly name = "download";
-  readonly description = "Download a file from URL";
-  readonly options = options;
-  readonly displayName = "File Downloader";
-  readonly actionLabel = "Download";
-
-  override buildConfig(opts: OptionValues<typeof options>): DownloadConfig {
-    // Validate URL
-    const urlStr = opts["url"] as string;
-    if (!urlStr) {
-      throw new ConfigValidationError("URL is required", "url");
-    }
-
-    let url: URL;
-    try {
-      url = new URL(urlStr);
-    } catch {
-      throw new ConfigValidationError("Invalid URL format", "url");
-    }
-
-    // Validate output directory
-    const outputDir = path.resolve(opts["output"] as string ?? "./downloads");
-
-    // Extract filename from URL
-    const fileName = path.basename(url.pathname) || "download";
-
-    // Parse chunk size
-    const chunkSizeStr = opts["chunk-size"] as string ?? "1024";
-    const chunkSize = parseInt(chunkSizeStr, 10) * 1024; // Convert KB to bytes
-    if (isNaN(chunkSize) || chunkSize <= 0) {
-      throw new ConfigValidationError("Chunk size must be a positive number", "chunk-size");
-    }
-
-    return { url, outputDir, fileName, chunkSize };
-  }
-```
-
-## Step 3: Implement Cancellable Download
-
-```typescript
-  async execute(
-    config: DownloadConfig,
-    execCtx: CommandExecutionContext
-  ): Promise<CommandResult> {
-    const { url, outputDir, fileName, chunkSize } = config;
-    const outputPath = path.join(outputDir, fileName);
-    const signal = execCtx.signal;
-
-    console.log(`Starting download: ${url}`);
-    console.log(`Output: ${outputPath}`);
-
-    // Create output directory
-    await Bun.write(path.join(outputDir, ".keep"), "");
-
-    // Track download state for cleanup
-    let downloadedBytes = 0;
-    let totalBytes = 0;
-    let partialFile: Bun.FileSink | null = null;
-
-    try {
-      // Check for cancellation before starting
-       if (signal.aborted) {
-
-        return { success: false, message: "Download cancelled before start" };
-      }
-
-      // Fetch with AbortSignal
-      const response = await fetch(url.toString(), { signal });
-      
-      if (!response.ok) {
-        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
-      }
-
-      totalBytes = parseInt(response.headers.get("content-length") ?? "0", 10);
-      const reader = response.body?.getReader();
-      
-      if (!reader) {
-        throw new Error("No response body");
-      }
-
-      // Open file for writing
-      partialFile = Bun.file(outputPath).writer();
-
-      console.log(`Downloading ${fileName}...`);
-      if (totalBytes > 0) {
-        console.log(`Total size: ${(totalBytes / 1024 / 1024).toFixed(2)} MB`);
-      }
-
-      // Read chunks with cancellation checks
-      while (true) {
-        // Check for cancellation between chunks
-      if (signal.aborted) {
-
-          console.warn("Download cancelled by user");
-          throw new Error("AbortError");
-        }
-
-        const { done, value } = await reader.read();
-        
-        if (done) {
-          break;
-        }
-
-        // Write chunk
-        partialFile.write(value);
-        downloadedBytes += value.byteLength;
-
-        // Log progress
-        if (totalBytes > 0) {
-          const percent = ((downloadedBytes / totalBytes) * 100).toFixed(1);
-          const mbDownloaded = (downloadedBytes / 1024 / 1024).toFixed(2);
-          const mbTotal = (totalBytes / 1024 / 1024).toFixed(2);
-          Bun.write(Bun.stdout, `\rProgress: ${percent}% (${mbDownloaded}/${mbTotal} MB)`);
-        } else {
-          const mbDownloaded = (downloadedBytes / 1024 / 1024).toFixed(2);
-          Bun.write(Bun.stdout, `\rDownloaded: ${mbDownloaded} MB`);
-        }
-      }
-
-      // Finalize file
-      await partialFile.end();
-      console.log("\nDownload complete!");
-
-      return {
-        success: true,
-        data: {
-          file: outputPath,
-          size: downloadedBytes,
-          url: url.toString(),
-        },
-        message: `Downloaded ${fileName} (${(downloadedBytes / 1024 / 1024).toFixed(2)} MB)`,
-      };
-
-    } catch (error) {
-      // Handle cancellation
-       if (signal.aborted || (error as Error).name === "AbortError") {
-
-        console.log("\nDownload cancelled.");
-        
-        // Cleanup partial file
-        await this.cleanup(outputPath, partialFile);
-        
-        return { 
-          success: false, 
-          message: "Download cancelled by user",
-          data: { 
-            downloadedBytes,
-            cancelled: true,
-          },
-        };
-      }
-
-      // Handle other errors
-      await this.cleanup(outputPath, partialFile);
-      throw error;
-    }
-  }
-
-  private async cleanup(
-    outputPath: string, 
-    sink: Bun.FileSink | null
-  ): Promise<void> {
-    try {
-      // Close file handle
-      if (sink) {
-        await sink.end();
-      }
-      
-      // Remove partial file
-      const file = Bun.file(outputPath);
-      if (await file.exists()) {
-        await Bun.write(outputPath, ""); // Clear file
-        // In production: fs.unlinkSync(outputPath);
-        console.log("Cleaned up partial download.");
-      }
-    } catch (e) {
-      // Ignore cleanup errors
-    }
-  }
-}
-```
-
-## Step 4: Create the Application
-
-Create `src/index.ts`:
-
-```typescript
-import { TuiApplication } from "@pablozaiden/terminatui";
-import { DownloadCommand } from "./commands/download";
-
-class DownloadManager extends TuiApplication {
-  constructor() {
-    super({
-      name: "download-manager",
-      version: "1.0.0",
-      commands: [new DownloadCommand()],
-    });
-  }
-}
-
-await new DownloadManager().run();
-```
-
-## Step 6: Test Cancellation
-
-```bash
-# Start a large download
-bun src/index.ts download https://speed.hetzner.de/100MB.bin --output ./test-downloads
-
-# While downloading, press Ctrl+C
-# Should see: "Download cancelled. Cleaned up partial download."
-
-# Run TUI mode
-bun src/index.ts --tui
-
-# Start download, then press Esc to cancel
-# Same cancellation behavior with cleanup
-```
-
-## Cancellation Patterns
-
-### 1. Check Signal Before Long Operations
-
-```typescript
-if (signal?.aborted) {
-  return { success: false, message: "Cancelled" };
-}
-```
-
-### 2. Pass Signal to fetch/APIs
-
-```typescript
-await fetch(url, { signal });
-await someAsyncApi({ signal });
-```
-
-### 3. Check Between Iterations
-
-```typescript
-for (const item of items) {
-  if (signal?.aborted) break;
-  await processItem(item);
-}
-```
-
-### 4. Always Cleanup
-
-```typescript
-try {
-  // ... cancellable work ...
-} catch (error) {
-  if (signal?.aborted) {
-    await cleanup();
-    return { success: false, message: "Cancelled" };
-  }
-  throw error;
-}
-```
-
-## What You Learned
-
-- Accept `CommandExecutionContext` with `AbortSignal`
-- Check `signal.aborted` between operations
-- Pass signal to `fetch` and other async APIs
-- Clean up resources on cancellation
-- Return meaningful results for cancelled operations
-
-## Next Steps
-
-→ [Guide 8: Building a Complete Application](08-complete-application.md)