aiwcli 0.9.0

package/dist/lib/spawn.js

@@ -0,0 +1,157 @@
+/**
+ * @file Process spawning utilities for AI Workflow CLI.
+ *
+ * This module provides utilities for spawning external processes (e.g., Claude Code)
+ * with proper error handling, stdio configuration, and debug logging.
+ *
+ * ## Key Features
+ * - Spawn external processes with configurable stdio (inherit, pipe)
+ * - Exit code capture and error handling
+ * - Detached mode for parallel sessions
+ * - Debug logging integration
+ * - Cross-platform compatibility
+ *
+ * ## Usage Examples
+ *
+ * ### Basic Spawn (Interactive)
+ * ```typescript
+ * import {spawnProcess} from '../lib/spawn.js'
+ *
+ * const exitCode = await spawnProcess('claude', ['--dangerously-skip-permissions'])
+ * if (exitCode !== 0) {
+ *   console.error('Claude Code exited with error')
+ * }
+ * ```
+ *
+ * ### Parallel Sessions (Detached Mode)
+ * ```typescript
+ * // Launch multiple Claude Code sessions concurrently
+ * const session1 = spawnProcess('claude', ['--dangerously-skip-permissions'], {detached: true})
+ * const session2 = spawnProcess('claude', ['--dangerously-skip-permissions'], {detached: true})
+ * await Promise.all([session1, session2])
+ * ```
+ *
+ * ### Custom Working Directory
+ * ```typescript
+ * await spawnProcess('npm', ['install'], {cwd: '/path/to/project'})
+ * ```
+ *
+ * @module lib/spawn
+ */
+import { execSync, spawn as nodeSpawn } from 'node:child_process';
+import { debug, debugSpawn } from './debug.js';
+import { ProcessSpawnError } from './errors.js';
+/**
+ * Spawn an external process and return its exit code.
+ *
+ * This function wraps Node.js child_process.spawn with AIW-specific
+ * error handling, debug logging, and parallel session support.
+ *
+ * ## Exit Code Mapping
+ * - 0: Success
+ * - Non-zero: Error (actual code from child process)
+ * - null code: Defaults to 1
+ *
+ * ## Error Handling
+ * - ENOENT: Command not found → ProcessSpawnError with install instructions
+ * - EACCES: Permission denied → ProcessSpawnError with permission fix
+ * - Other errors: ProcessSpawnError with error details
+ *
+ * ## Parallel Sessions
+ * Use `detached: true` to spawn independent processes that don't block parent.
+ * Multiple calls can run concurrently without conflicts.
+ *
+ * @param command - Command to execute (e.g., 'claude', 'npm', 'git')
+ * @param args - Arguments array (e.g., ['--dangerously-skip-permissions'])
+ * @param options - Spawn configuration options
+ * @returns Promise<number> - Exit code (0 = success, non-zero = error)
+ * @throws ProcessSpawnError - When spawn fails (command not found, permissions, etc.)
+ *
+ * @example
+ * // Launch Claude Code with sandbox disabled
+ * const exitCode = await spawnProcess('claude', ['--dangerously-skip-permissions'])
+ *
+ * @example
+ * // Parallel session with detached mode
+ * const session1 = spawnProcess('claude', ['--dangerously-skip-permissions'], {detached: true})
+ * const session2 = spawnProcess('claude', ['--dangerously-skip-permissions'], {detached: true})
+ * await Promise.all([session1, session2])
+ *
+ * @example
+ * // Custom working directory
+ * await spawnProcess('npm', ['test'], {cwd: '/path/to/project'})
+ */
+export async function spawnProcess(command, args = [], options = {}) {
+    const { cwd, stdio = 'inherit', detached = false } = options;
+    // Log spawn details in debug mode
+    debugSpawn(command, args);
+    // Windows hybrid approach: try without shell first, fallback to .cmd if ENOENT
+    // This preserves error detection while supporting .cmd files from npm
+    if (process.platform === 'win32') {
+        try {
+            return await attemptSpawn(command, args, { cwd, stdio, detached, shell: false });
+        }
+        catch (error) {
+            // If command not found and .cmd file exists, use cmd.exe wrapper
+            // This avoids DEP0190 deprecation warning while supporting npm-installed commands
+            if (error instanceof ProcessSpawnError && error.code === 'ENOENT' && commandExistsInPath(`${command}.cmd`)) {
+                // Use cmd.exe /c to execute .cmd file without shell mode or deprecation warning
+                return attemptSpawn('cmd.exe', ['/c', command, ...args], { cwd, stdio, detached, shell: false });
+            }
+            throw error;
+        }
+    }
+    // Unix: always use shell: false for security
+    return attemptSpawn(command, args, { cwd, stdio, detached, shell: false });
+}
+/**
+ * Check if a command exists in PATH (Windows only).
+ * Uses 'where' command to check if file exists in PATH.
+ */
+function commandExistsInPath(command) {
+    try {
+        execSync(`where ${command}`, { stdio: 'ignore', windowsHide: true });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Internal helper to attempt process spawn with given options.
+ */
+function attemptSpawn(command, args, spawnOptions) {
+    return new Promise((resolve, reject) => {
+        try {
+            const childProcess = nodeSpawn(command, args, spawnOptions);
+            // Handle spawn errors (ENOENT, EACCES, etc.)
+            childProcess.on('error', (error) => {
+                if (error.code === 'ENOENT') {
+                    reject(new ProcessSpawnError(`Command not found: ${command}. Install Claude Code from https://claude.ai/download.`, 'ENOENT'));
+                }
+                else if (error.code === 'EACCES') {
+                    reject(new ProcessSpawnError(`Permission denied: ${command}. Check file permissions.`, 'EACCES'));
+                }
+                else {
+                    reject(new ProcessSpawnError(`Failed to spawn ${command}: ${error.message}. Check that the command exists and is executable.`, error.code));
+                }
+            });
+            // Capture exit code on process close
+            childProcess.on('close', (code, signal) => {
+                const exitCode = code ?? 1; // Default to error if no code
+                if (signal) {
+                    debug(`Process terminated by signal: ${signal}`);
+                }
+                debug(`Process exited with code: ${exitCode}`);
+                resolve(exitCode);
+            });
+            // Unref detached processes to allow parent to exit
+            if (spawnOptions.detached && childProcess.unref) {
+                childProcess.unref();
+            }
+        }
+        catch (error) {
+            reject(new ProcessSpawnError(`Spawn error: ${error instanceof Error ? error.message : String(error)}`));
+        }
+    });
+}

package/dist/lib/spinner.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Spinner Utilities
+ *
+ * Provides TTY-aware spinner wrapper using ora library.
+ * Spinners automatically disable in non-TTY contexts (piped, redirected, CI).
+ */
+import { type Ora } from 'ora';
+/**
+ * Create a TTY-aware spinner.
+ * Automatically disables in non-TTY contexts (piped, redirected, CI, quiet mode).
+ */
+export declare function createSpinner(text: string, flags?: {
+    quiet?: boolean;
+}): Ora;
+/**
+ * Helper for common "loading" operations with spinner.
+ * Automatically handles success/failure and cleanup.
+ */
+export declare function withSpinner<T>(text: string, operation: () => Promise<T>): Promise<T>;

package/dist/lib/spinner.js

@@ -0,0 +1,34 @@
+/**
+ * Spinner Utilities
+ *
+ * Provides TTY-aware spinner wrapper using ora library.
+ * Spinners automatically disable in non-TTY contexts (piped, redirected, CI).
+ */
+import ora from 'ora';
+import { shouldShowSpinners } from './tty-detection.js';
+/**
+ * Create a TTY-aware spinner.
+ * Automatically disables in non-TTY contexts (piped, redirected, CI, quiet mode).
+ */
+export function createSpinner(text, flags) {
+    return ora({
+        isEnabled: shouldShowSpinners(flags),
+        text,
+    });
+}
+/**
+ * Helper for common "loading" operations with spinner.
+ * Automatically handles success/failure and cleanup.
+ */
+export async function withSpinner(text, operation) {
+    const spinner = createSpinner(text).start();
+    try {
+        const result = await operation();
+        spinner.succeed();
+        return result;
+    }
+    catch (error) {
+        spinner.fail();
+        throw error;
+    }
+}

package/dist/lib/stdin.d.ts

@@ -0,0 +1,48 @@
+/**
+ * stdin Detection and Reading Utilities
+ *
+ * Provides utilities for detecting and reading piped input from stdin.
+ * Used by commands that need to accept piped data from other commands.
+ *
+ * @example Basic stdin detection
+ * ```typescript
+ * if (hasStdin()) {
+ *   const input = await readStdin()
+ *   // Process piped input
+ * } else {
+ *   // Interactive mode - prompt user
+ * }
+ * ```
+ */
+/**
+ * Check if stdin has piped data available.
+ * Returns true when data is piped into the command, false in interactive terminals.
+ *
+ * @returns True if stdin is piped (not a TTY), false if interactive terminal
+ *
+ * @example
+ * ```typescript
+ * // echo "data" | pai process
+ * hasStdin() // Returns true
+ *
+ * // pai process (no pipe)
+ * hasStdin() // Returns false
+ * ```
+ */
+export declare function hasStdin(): boolean;
+/**
+ * Read all data from stdin.
+ * Reads piped input data and returns as UTF-8 string.
+ * Returns empty string if no stdin available.
+ *
+ * @returns Promise resolving to stdin content as string, or empty string if no stdin
+ *
+ * @example
+ * ```typescript
+ * const input = await readStdin()
+ * if (input) {
+ *   console.log(`Received: ${input}`)
+ * }
+ * ```
+ */
+export declare function readStdin(): Promise<string>;

package/dist/lib/stdin.js

@@ -0,0 +1,60 @@
+/**
+ * stdin Detection and Reading Utilities
+ *
+ * Provides utilities for detecting and reading piped input from stdin.
+ * Used by commands that need to accept piped data from other commands.
+ *
+ * @example Basic stdin detection
+ * ```typescript
+ * if (hasStdin()) {
+ *   const input = await readStdin()
+ *   // Process piped input
+ * } else {
+ *   // Interactive mode - prompt user
+ * }
+ * ```
+ */
+import { stdin } from 'node:process';
+/**
+ * Check if stdin has piped data available.
+ * Returns true when data is piped into the command, false in interactive terminals.
+ *
+ * @returns True if stdin is piped (not a TTY), false if interactive terminal
+ *
+ * @example
+ * ```typescript
+ * // echo "data" | pai process
+ * hasStdin() // Returns true
+ *
+ * // pai process (no pipe)
+ * hasStdin() // Returns false
+ * ```
+ */
+export function hasStdin() {
+    return stdin.isTTY !== true;
+}
+/**
+ * Read all data from stdin.
+ * Reads piped input data and returns as UTF-8 string.
+ * Returns empty string if no stdin available.
+ *
+ * @returns Promise resolving to stdin content as string, or empty string if no stdin
+ *
+ * @example
+ * ```typescript
+ * const input = await readStdin()
+ * if (input) {
+ *   console.log(`Received: ${input}`)
+ * }
+ * ```
+ */
+export async function readStdin() {
+    if (!hasStdin()) {
+        return '';
+    }
+    const chunks = [];
+    for await (const chunk of stdin) {
+        chunks.push(chunk);
+    }
+    return Buffer.concat(chunks).toString('utf8');
+}

package/dist/lib/template-installer.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Configuration for template installation
+ */
+export interface TemplateInstallConfig {
+    /** List of IDE names to install (e.g., ['claude', 'windsurf']) */
+    ides: string[];
+    /** Project name for configuration generation */
+    projectName: string;
+    /** Target directory where template will be installed */
+    targetDir: string;
+    /** Name of the template to install (e.g., 'bmad') */
+    templateName: string;
+    /** Absolute path to the template directory */
+    templatePath: string;
+    /** Username for configuration generation */
+    username: string;
+}
+/**
+ * Status of a single template item (file or folder)
+ */
+export interface TemplateItemStatus {
+    /** Whether the item exists in target directory */
+    exists: boolean;
+    /** Whether the item is a directory */
+    isDirectory: boolean;
+    /** The item name */
+    name: string;
+}
+/**
+ * Result of checking template installation status
+ */
+export interface TemplateInstallationStatus {
+    /** Items that already exist in target directory */
+    existing: TemplateItemStatus[];
+    /** Items that are missing from target directory */
+    missing: TemplateItemStatus[];
+    /** The method-specific workflow folder name (e.g., '_gsd', '_bmad') */
+    workflowFolder: null | string;
+    /** Whether the workflow folder exists */
+    workflowFolderExists: boolean;
+}
+/**
+ * Result of template installation
+ */
+export interface InstallationResult {
+    /** List of folder names that were installed (for gitignore) */
+    installedFolders: string[];
+    /** Number of files that were merged into existing folders */
+    mergedFileCount: number;
+    /** List of folder names that had content merged */
+    mergedFolders: string[];
+    /** Whether shared settings were merged into IDE settings */
+    sharedSettingsMerged: boolean;
+    /** List of folder names that were skipped (already exist) */
+    skippedFolders: string[];
+    /** Absolute path to the template that was installed */
+    templatePath: string;
+}
+/**
+ * Check template installation status for a method.
+ * Returns which items exist and which are missing.
+ *
+ * @param templatePath - Path to the template directory
+ * @param targetDir - Target directory to check
+ * @param ides - List of IDEs to check (for dot folders)
+ * @param templateName - Name of the template (for identifying workflow folder)
+ * @returns Status of template items
+ */
+export declare function checkTemplateStatus(templatePath: string, targetDir: string, ides: string[], templateName: string): Promise<TemplateInstallationStatus>;
+/**
+ * Copy directory recursively with proper error handling.
+ * Excludes test files, cache directories, and output folders.
+ *
+ * @param src - Source directory path
+ * @param dest - Destination directory path
+ * @param excludeIdeFolders - If true, exclude IDE config folders (.claude, .windsurf, etc.)
+ */
+export declare function copyDir(src: string, dest: string, excludeIdeFolders?: boolean): Promise<void>;
+/**
+ * Install template with IDE-specific folder selection.
+ * Supports selective installation - only installs items that don't already exist.
+ *
+ * Template structure:
+ * - Non-dot folders (e.g., _bmad/, GSR/) are installed if not already present
+ * - Dot folders (e.g., .claude/, .windsurf/) are installed only if matching IDE flag and not already present
+ *
+ * @param config - Installation configuration
+ * @param skipExisting - If true, skip items that already exist (default: true for regeneration support)
+ * @returns Installation result with list of installed and skipped folders
+ * @throws Error if template doesn't exist or requested IDE folder not found
+ */
+export declare function installTemplate(config: TemplateInstallConfig, skipExisting?: boolean): Promise<InstallationResult>;