@pablozaiden/terminatui 0.1.2 → 0.3.0-beta-1

package/guides/05-interactive-tui.md

@@ -1,4 +1,4 @@
-# Guide 5: Interactive TUI (Normal)
+# Guide 5: Interactive TUI
 
 Add an auto-generated Terminal User Interface to your CLI.
 
@@ -8,20 +8,34 @@ A task runner with both CLI and interactive TUI modes:
 
 ```bash
 # CLI mode
-taskr run --task build --env production
+taskr --mode cli run --task build --env production
 
-# TUI mode (interactive)
-taskr
+# 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
 ```
 
-When you run without arguments, an interactive form appears!
+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 AppContext, type OptionSchema, type CommandResult } from "@pablozaiden/terminatui";
+import {
+  Command,
+  type OptionSchema,
+  type CommandResult,
+  type CommandExecutionContext,
+} from "@pablozaiden/terminatui";
 
 const options = {
   task: {
@@ -70,11 +84,9 @@ export class RunCommand extends Command<typeof options, RunConfig> {
   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}`);
-    
+  async execute(config: RunConfig, _execCtx: CommandExecutionContext): Promise<CommandResult> {
     if (config.verbose) {
-      ctx.logger.debug(`Environment: ${config.env}`);
+      console.debug(`Environment: ${config.env}`);
     }
 
     // Simulate task execution
@@ -82,10 +94,10 @@ export class RunCommand extends Command<typeof options, RunConfig> {
     await new Promise((resolve) => setTimeout(resolve, 1000));
     console.log("Task completed!");
 
-    return { 
-      success: true, 
+    return {
+      success: true,
       data: { task: config.task, env: config.env },
-      message: `Task ${config.task} completed successfully`
+      message: `Task ${config.task} completed successfully`,
     };
   }
 }
@@ -100,13 +112,16 @@ 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
+      displayName: "🚀 Task Runner", // Shown in TUI header
       version: "1.0.0",
       commands: [new RunCommand()],
-      enableTui: true,  // Default: true
+      enableTui: true, // Default: true
     });
   }
 }
@@ -116,26 +131,26 @@ await new TaskRunnerApp().run();
 
 ## Step 3: Test Both Modes
 
-**CLI Mode** (with arguments):
+**CLI Mode** (forced):
 
 ```bash
-bun src/index.ts run --task build --env production
+bun src/index.ts --mode cli run --task build --env production
 # Running build in production...
 # Task completed!
 ```
 
-**TUI Mode** (no arguments):
+**TUI Mode** (forced):
 
 ```bash
-bun src/index.ts
+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
-- Press C to see the CLI command
 
 ## TUI Metadata Reference
 
@@ -145,13 +160,13 @@ Add these properties to your options for TUI customization:
 {
   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)
+  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)
 }
 ```
 
@@ -161,10 +176,10 @@ Add these properties to your options for TUI customization:
 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;
 }
@@ -175,9 +190,8 @@ class MyCommand extends Command {
 | Key | Action |
 |-----|--------|
 | ↑/↓ | Navigate fields |
-| Enter | Edit field / Run |
+| Enter | Edit field / Press button / Run |
 | Tab | Cycle focus |
-| C | Show CLI command |
 | L | Toggle logs |
 | Ctrl+Y | Copy to clipboard |
 | Esc | Back / Cancel |
@@ -185,6 +199,7 @@ class MyCommand extends Command {
 ## 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

package/guides/06-config-validation.md

@@ -16,11 +16,9 @@ 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 
@@ -84,10 +82,7 @@ export class DeployCommand extends Command<typeof options, DeployConfig> {
    * Transform and validate raw options into DeployConfig.
    * Runs before execute() - errors here show helpful messages.
    */
-  override buildConfig(
-    _ctx: AppContext, 
-    opts: OptionValues<typeof options>
-  ): DeployConfig {
+  override async buildConfig(opts: OptionValues<typeof options>): Promise<DeployConfig> {
     // 1. Validate app path exists
     const appRaw = opts["app"] as string | undefined;
     if (!appRaw) {
@@ -98,7 +93,7 @@ export class DeployCommand extends Command<typeof options, DeployConfig> {
     }
     
     const appPath = path.resolve(appRaw);
-    if (!existsSync(appPath)) {
+    if (!(await Bun.file(appPath).exists())) {
       throw new ConfigValidationError(
         `Application path does not exist: ${appPath}`,
         "app"
@@ -157,11 +152,8 @@ export class DeployCommand extends Command<typeof options, DeployConfig> {
    * 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}`);
+  async execute(config: DeployConfig): Promise<CommandResult> {
+    console.log(`Deploying ${config.appName} to ${config.environment}`);
 
     if (config.dryRun) {
       console.log("DRY RUN - Would deploy:");

package/guides/07-async-cancellation.md

@@ -23,7 +23,6 @@ import path from "node:path";
 import { 
   Command, 
   ConfigValidationError,
-  type AppContext, 
   type OptionSchema, 
   type OptionValues,
   type CommandResult,
@@ -69,10 +68,7 @@ export class DownloadCommand extends Command<typeof options, DownloadConfig> {
   readonly displayName = "File Downloader";
   readonly actionLabel = "Download";
 
-  override buildConfig(
-    _ctx: AppContext,
-    opts: OptionValues<typeof options>
-  ): DownloadConfig {
+  override buildConfig(opts: OptionValues<typeof options>): DownloadConfig {
     // Validate URL
     const urlStr = opts["url"] as string;
     if (!urlStr) {
@@ -107,16 +103,15 @@ export class DownloadCommand extends Command<typeof options, DownloadConfig> {
 
 ```typescript
   async execute(
-    ctx: AppContext,
     config: DownloadConfig,
-    execCtx?: CommandExecutionContext
+    execCtx: CommandExecutionContext
   ): Promise<CommandResult> {
     const { url, outputDir, fileName, chunkSize } = config;
     const outputPath = path.join(outputDir, fileName);
-    const signal = execCtx?.signal;
+    const signal = execCtx.signal;
 
-    ctx.logger.info(`Starting download: ${url}`);
-    ctx.logger.info(`Output: ${outputPath}`);
+    console.log(`Starting download: ${url}`);
+    console.log(`Output: ${outputPath}`);
 
     // Create output directory
     await Bun.write(path.join(outputDir, ".keep"), "");
@@ -128,7 +123,8 @@ export class DownloadCommand extends Command<typeof options, DownloadConfig> {
 
     try {
       // Check for cancellation before starting
-      if (signal?.aborted) {
+       if (signal.aborted) {
+
         return { success: false, message: "Download cancelled before start" };
       }
 
@@ -157,8 +153,9 @@ export class DownloadCommand extends Command<typeof options, DownloadConfig> {
       // Read chunks with cancellation checks
       while (true) {
         // Check for cancellation between chunks
-        if (signal?.aborted) {
-          ctx.logger.warn("Download cancelled by user");
+      if (signal.aborted) {
+
+          console.warn("Download cancelled by user");
           throw new Error("AbortError");
         }
 
@@ -177,10 +174,10 @@ export class DownloadCommand extends Command<typeof options, DownloadConfig> {
           const percent = ((downloadedBytes / totalBytes) * 100).toFixed(1);
           const mbDownloaded = (downloadedBytes / 1024 / 1024).toFixed(2);
           const mbTotal = (totalBytes / 1024 / 1024).toFixed(2);
-          process.stdout.write(`\rProgress: ${percent}% (${mbDownloaded}/${mbTotal} MB)`);
+          Bun.write(Bun.stdout, `\rProgress: ${percent}% (${mbDownloaded}/${mbTotal} MB)`);
         } else {
           const mbDownloaded = (downloadedBytes / 1024 / 1024).toFixed(2);
-          process.stdout.write(`\rDownloaded: ${mbDownloaded} MB`);
+          Bun.write(Bun.stdout, `\rDownloaded: ${mbDownloaded} MB`);
         }
       }
 
@@ -200,7 +197,8 @@ export class DownloadCommand extends Command<typeof options, DownloadConfig> {
 
     } catch (error) {
       // Handle cancellation
-      if (signal?.aborted || (error as Error).name === "AbortError") {
+       if (signal.aborted || (error as Error).name === "AbortError") {
+
         console.log("\nDownload cancelled.");
         
         // Cleanup partial file
@@ -246,58 +244,7 @@ export class DownloadCommand extends Command<typeof options, DownloadConfig> {
 }
 ```
 
-## Step 4: Add Result Rendering
-
-```typescript
-import React from "react";
-import { Text, Box } from "ink";
-
-export class DownloadCommand extends Command<typeof options, DownloadConfig> {
-  // ... previous code ...
-
-  /**
-   * Custom TUI result display
-   */
-  override renderResult(result: CommandResult): React.ReactNode {
-    if (!result.success && result.data?.cancelled) {
-      return (
-        <Box flexDirection="column">
-          <Text color="yellow">⚠ Download Cancelled</Text>
-          {result.data?.downloadedBytes > 0 && (
-            <Text dimColor>
-              Partial: {(result.data.downloadedBytes / 1024 / 1024).toFixed(2)} MB
-            </Text>
-          )}
-        </Box>
-      );
-    }
-
-    if (!result.success) {
-      return <Text color="red">✗ {result.message}</Text>;
-    }
-
-    return (
-      <Box flexDirection="column">
-        <Text color="green">✓ Download Complete</Text>
-        <Text>File: {result.data?.file}</Text>
-        <Text>Size: {(result.data?.size / 1024 / 1024).toFixed(2)} MB</Text>
-      </Box>
-    );
-  }
-
-  /**
-   * Copy file path to clipboard
-   */
-  override getClipboardContent(result: CommandResult): string | undefined {
-    if (result.success && result.data?.file) {
-      return result.data.file;
-    }
-    return undefined;
-  }
-}
-```
-
-## Step 5: Create the Application
+## Step 4: Create the Application
 
 Create `src/index.ts`:
 
@@ -381,7 +328,6 @@ try {
 - Pass signal to `fetch` and other async APIs
 - Clean up resources on cancellation
 - Return meaningful results for cancelled operations
-- Render different UI for cancelled vs success vs error
 
 ## Next Steps