aiwcli 0.9.0

package/dist/lib/template-merger.js

@@ -0,0 +1,173 @@
+import { promises as fs } from 'node:fs';
+import { join } from 'node:path';
+/**
+ * Content folder types that should be recursively merged rather than skipped.
+ * These are the canonical folder names used in templates for organizing content.
+ */
+export const CONTENT_FOLDER_TYPES = ['agents', 'commands', 'workflows', 'tasks'];
+/**
+ * Check if a path exists
+ */
+async function pathExists(path) {
+    try {
+        await fs.access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Recursively find folders matching the method name within a directory tree.
+ * This finds folders like `.claude/commands/bmad/` when methodName is 'bmad'.
+ *
+ * @param dir - Directory to search
+ * @param methodName - Method name to look for (e.g., 'bmad', 'gsd')
+ * @returns Array of paths to matching folders
+ */
+export async function findMethodFolders(dir, methodName) {
+    const results = [];
+    async function scan(currentDir) {
+        try {
+            const entries = await fs.readdir(currentDir, { withFileTypes: true });
+            const directories = entries.filter((entry) => entry.isDirectory());
+            // Process all directories in parallel
+            await Promise.all(directories.map(async (entry) => {
+                const entryPath = join(currentDir, entry.name);
+                if (entry.name === methodName) {
+                    results.push(entryPath);
+                }
+                // Recursively scan subdirectories
+                await scan(entryPath);
+            }));
+        }
+        catch {
+            // Ignore errors (permission issues, etc.)
+        }
+    }
+    await scan(dir);
+    return results;
+}
+/**
+ * Recursively merge a source directory into a target directory.
+ * Only copies files that don't already exist in the target.
+ * Creates directories as needed.
+ *
+ * @param srcDir - Source directory to copy from
+ * @param destDir - Destination directory to copy to
+ * @param result - Accumulator for merge results
+ */
+async function mergeDirectory(srcDir, destDir, result) {
+    // Create destination directory if it doesn't exist
+    if (!(await pathExists(destDir))) {
+        await fs.mkdir(destDir, { recursive: true });
+        result.createdDirs.push(destDir);
+    }
+    const entries = await fs.readdir(srcDir, { withFileTypes: true });
+    // Process all entries in parallel
+    await Promise.all(entries.map(async (entry) => {
+        const srcPath = join(srcDir, entry.name);
+        const destPath = join(destDir, entry.name);
+        if (entry.isDirectory()) {
+            // Recursively merge subdirectories
+            await mergeDirectory(srcPath, destPath, result);
+            return;
+        }
+        // Copy file if it doesn't exist
+        const exists = await pathExists(destPath);
+        if (exists) {
+            result.skippedFiles.push(destPath);
+        }
+        else {
+            await fs.copyFile(srcPath, destPath);
+            result.copiedFiles.push(destPath);
+        }
+    }));
+}
+/**
+ * Merge template content into an existing IDE folder.
+ * Recursively finds folders matching the method name and merges their content.
+ *
+ * This enables adding new agents, commands, workflows, and tasks from a template
+ * even when the IDE folder (e.g., .claude) already exists.
+ *
+ * @param templateIdePath - Path to the template's IDE folder (e.g., template/.claude)
+ * @param targetIdePath - Path to the target's IDE folder (e.g., project/.claude)
+ * @param methodName - Method name to look for (e.g., 'bmad', 'gsd')
+ * @returns Merge results
+ */
+export async function mergeTemplateContent(templateIdePath, targetIdePath, methodName) {
+    const result = {
+        copiedFiles: [],
+        createdDirs: [],
+        skippedFiles: [],
+    };
+    // First, copy root-level files from the template IDE folder (e.g., settings.json)
+    // These are files directly in .claude/ that aren't in method-specific subfolders
+    try {
+        const entries = await fs.readdir(templateIdePath, { withFileTypes: true });
+        const rootFiles = entries.filter((entry) => entry.isFile());
+        await Promise.all(rootFiles.map(async (file) => {
+            const srcPath = join(templateIdePath, file.name);
+            const destPath = join(targetIdePath, file.name);
+            // Only copy if it doesn't exist (skip existing behavior)
+            const exists = await pathExists(destPath);
+            if (exists) {
+                result.skippedFiles.push(destPath);
+            }
+            else {
+                await fs.copyFile(srcPath, destPath);
+                result.copiedFiles.push(destPath);
+            }
+        }));
+    }
+    catch {
+        // Ignore errors (permission issues, missing directory, etc.)
+    }
+    // Find all folders matching the method name in the template
+    const methodFolders = await findMethodFolders(templateIdePath, methodName);
+    // Merge all method folders in parallel
+    await Promise.all(methodFolders.map(async (srcMethodFolder) => {
+        // Calculate the relative path from the template IDE folder
+        const relativePath = srcMethodFolder.slice(templateIdePath.length);
+        const destMethodFolder = join(targetIdePath, relativePath);
+        // Merge this method folder into the target
+        await mergeDirectory(srcMethodFolder, destMethodFolder, result);
+    }));
+    return result;
+}
+/**
+ * Merge content type folders (agents, commands, workflows, tasks) from template to target.
+ * This is an alternative approach that looks for specific folder types rather than method names.
+ *
+ * @param templateIdePath - Path to the template's IDE folder
+ * @param targetIdePath - Path to the target's IDE folder
+ * @returns Merge results
+ */
+export async function mergeContentTypeFolders(templateIdePath, targetIdePath) {
+    const result = {
+        copiedFiles: [],
+        createdDirs: [],
+        skippedFiles: [],
+    };
+    async function scanAndMerge(srcDir, destDir) {
+        try {
+            const entries = await fs.readdir(srcDir, { withFileTypes: true });
+            const directories = entries.filter((entry) => entry.isDirectory());
+            // Process all directories in parallel
+            await Promise.all(directories.map(async (entry) => {
+                const srcPath = join(srcDir, entry.name);
+                const destPath = join(destDir, entry.name);
+                // Check if this is a content type folder
+                const isContentType = CONTENT_FOLDER_TYPES.includes(entry.name);
+                // Merge content folders, recursively scan other directories
+                await (isContentType ? mergeDirectory(srcPath, destPath, result) : scanAndMerge(srcPath, destPath));
+            }));
+        }
+        catch {
+            // Ignore errors
+        }
+    }
+    await scanAndMerge(templateIdePath, targetIdePath);
+    return result;
+}

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

@@ -0,0 +1,20 @@
+/**
+ * Resolve the absolute path to a bundled template root.
+ * Works in both development (src/) and production (dist/) contexts.
+ *
+ * Resolution logic:
+ * - In development: src/lib/template-resolver.ts → src/templates/<templateName>/
+ * - In production: dist/lib/template-resolver.js → dist/templates/<templateName>/
+ *
+ * @param templateName - Name of the template to resolve (e.g., 'bmad')
+ * @returns Absolute path to the template directory
+ * @throws Error if template directory doesn't exist or templateName is invalid
+ */
+export declare function getTemplatePath(templateName: string): Promise<string>;
+/**
+ * Get list of available template names by scanning the templates directory.
+ *
+ * @returns Array of template names (e.g., ['bmad', 'gsr'])
+ * @throws Error if templates directory cannot be read (indicates corrupted installation)
+ */
+export declare function getAvailableTemplates(): Promise<string[]>;

package/dist/lib/template-resolver.js

@@ -0,0 +1,60 @@
+import { promises as fs } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/**
+ * Resolve the absolute path to a bundled template root.
+ * Works in both development (src/) and production (dist/) contexts.
+ *
+ * Resolution logic:
+ * - In development: src/lib/template-resolver.ts → src/templates/<templateName>/
+ * - In production: dist/lib/template-resolver.js → dist/templates/<templateName>/
+ *
+ * @param templateName - Name of the template to resolve (e.g., 'bmad')
+ * @returns Absolute path to the template directory
+ * @throws Error if template directory doesn't exist or templateName is invalid
+ */
+export async function getTemplatePath(templateName) {
+    // Security: Prevent path traversal attacks
+    if (!templateName || templateName.includes('..') || templateName.includes('/') || templateName.includes('\\')) {
+        throw new Error(`Invalid template name: '${templateName}'. Template names must not contain path separators or traversal sequences.`);
+    }
+    // Get the directory of this file
+    // In dev: .../aiwcli/src/lib/
+    // In prod: .../aiwcli/dist/lib/
+    const currentFileUrl = import.meta.url;
+    const currentFilePath = fileURLToPath(currentFileUrl);
+    const currentDir = dirname(currentFilePath);
+    // Go up one level and into templates/<templateName>
+    // src/lib/ → src/templates/<templateName>/
+    // dist/lib/ → dist/templates/<templateName>/
+    const templatePath = join(currentDir, '..', 'templates', templateName);
+    // Validate template exists
+    try {
+        await fs.access(templatePath);
+    }
+    catch {
+        throw new Error(`Template '${templateName}' not found at ${templatePath}`);
+    }
+    return templatePath;
+}
+/**
+ * Get list of available template names by scanning the templates directory.
+ *
+ * @returns Array of template names (e.g., ['bmad', 'gsr'])
+ * @throws Error if templates directory cannot be read (indicates corrupted installation)
+ */
+export async function getAvailableTemplates() {
+    const currentFileUrl = import.meta.url;
+    const currentFilePath = fileURLToPath(currentFileUrl);
+    const currentDir = dirname(currentFilePath);
+    const templatesDir = join(currentDir, '..', 'templates');
+    try {
+        const entries = await fs.readdir(templatesDir, { withFileTypes: true });
+        return entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name);
+    }
+    catch (error) {
+        const err = error;
+        throw new Error(`Failed to read templates directory at ${templatesDir}: ${err.message}. ` +
+            `This indicates a corrupted installation. Please reinstall aiwcli.`);
+    }
+}

package/dist/lib/terminal.d.ts

@@ -0,0 +1,102 @@
+/**
+ * @file Cross-platform terminal launching utilities.
+ *
+ * This module provides utilities for launching new terminal windows with commands
+ * across Windows, macOS, and Linux platforms.
+ *
+ * ## Supported Platforms
+ * - **Windows**: Windows Terminal (wt.exe) with PowerShell 7 (pwsh) fallback to PowerShell 5.1
+ * - **macOS**: Terminal.app via AppleScript
+ * - **Linux**: gnome-terminal, konsole, xterm, x-terminal-emulator (in order of preference)
+ *
+ * ## Usage
+ * ```typescript
+ * import { launchTerminal } from '../lib/terminal.js'
+ *
+ * const result = await launchTerminal({
+ *   cwd: '/path/to/project',
+ *   command: 'aiw launch',
+ *   debugLog: (msg) => console.debug(msg),
+ * })
+ *
+ * if (!result.success) {
+ *   console.error(result.error)
+ * }
+ * ```
+ *
+ * @module lib/terminal
+ */
+/**
+ * Options for launching a new terminal window.
+ */
+export interface TerminalLaunchOptions {
+    /**
+     * Command to execute in the new terminal.
+     */
+    command: string;
+    /**
+     * Working directory where the terminal should open.
+     */
+    cwd: string;
+    /**
+     * Optional debug logging function.
+     * If provided, debug messages will be passed to this function.
+     */
+    debugLog?: (message: string) => void;
+}
+/**
+ * Result of a terminal launch operation.
+ */
+export interface TerminalLaunchResult {
+    /**
+     * Error message if launch failed.
+     */
+    error?: string;
+    /**
+     * Whether the terminal was successfully launched.
+     */
+    success: boolean;
+}
+/**
+ * Escape a shell argument for safe execution.
+ * Wraps path in double quotes and escapes internal quotes.
+ *
+ * @param arg - Argument to escape
+ * @returns Escaped argument safe for shell execution
+ */
+declare function escapeShellArg(arg: string): string;
+/**
+ * Launch a new terminal window with the specified command.
+ *
+ * This function automatically detects the platform and uses the appropriate
+ * terminal emulator:
+ * - **Windows**: Windows Terminal (wt.exe) with PowerShell, falls back to PowerShell directly
+ * - **macOS**: Terminal.app via AppleScript
+ * - **Linux**: Tries gnome-terminal, konsole, xterm, x-terminal-emulator in order
+ *
+ * The terminal is launched in detached mode, allowing the parent process to exit
+ * without affecting the new terminal.
+ *
+ * @param options - Terminal launch options
+ * @returns Promise resolving to launch result
+ *
+ * @example
+ * ```typescript
+ * // Launch aiw in a new terminal
+ * const result = await launchTerminal({
+ *   cwd: '/path/to/project',
+ *   command: 'aiw launch',
+ * })
+ *
+ * if (result.success) {
+ *   console.log('Terminal launched successfully')
+ * } else {
+ *   console.error(`Failed: ${result.error}`)
+ * }
+ * ```
+ */
+export declare function launchTerminal(options: TerminalLaunchOptions): Promise<TerminalLaunchResult>;
+/**
+ * Escape shell argument utility - exported for use in command construction.
+ */
+export { escapeShellArg };

package/dist/lib/terminal.js

@@ -0,0 +1,245 @@
+/**
+ * @file Cross-platform terminal launching utilities.
+ *
+ * This module provides utilities for launching new terminal windows with commands
+ * across Windows, macOS, and Linux platforms.
+ *
+ * ## Supported Platforms
+ * - **Windows**: Windows Terminal (wt.exe) with PowerShell 7 (pwsh) fallback to PowerShell 5.1
+ * - **macOS**: Terminal.app via AppleScript
+ * - **Linux**: gnome-terminal, konsole, xterm, x-terminal-emulator (in order of preference)
+ *
+ * ## Usage
+ * ```typescript
+ * import { launchTerminal } from '../lib/terminal.js'
+ *
+ * const result = await launchTerminal({
+ *   cwd: '/path/to/project',
+ *   command: 'aiw launch',
+ *   debugLog: (msg) => console.debug(msg),
+ * })
+ *
+ * if (!result.success) {
+ *   console.error(result.error)
+ * }
+ * ```
+ *
+ * @module lib/terminal
+ */
+import { execSync, spawn } from 'node:child_process';
+/**
+ * Escape a shell argument for safe execution.
+ * Wraps path in double quotes and escapes internal quotes.
+ *
+ * @param arg - Argument to escape
+ * @returns Escaped argument safe for shell execution
+ */
+function escapeShellArg(arg) {
+    return `"${arg.replaceAll('\\', '\\\\').replaceAll('"', String.raw `\"`)}"`;
+}
+/**
+ * Detect which PowerShell is available on Windows.
+ * Prefers PowerShell 7 (pwsh) over legacy PowerShell.
+ *
+ * @returns 'pwsh' if PowerShell 7 is available, 'powershell' otherwise
+ */
+function detectPowerShell() {
+    try {
+        execSync('where pwsh', { stdio: 'ignore' });
+        return 'pwsh';
+    }
+    catch {
+        return 'powershell';
+    }
+}
+/**
+ * Launch PowerShell fallback when Windows Terminal is not available.
+ *
+ * @param cwd - Working directory
+ * @param command - Command to execute
+ * @param powershellCmd - PowerShell command to use (pwsh or powershell)
+ * @param debugLog - Optional debug logging function
+ */
+async function launchPowerShellFallback(cwd, command, powershellCmd, debugLog) {
+    return new Promise((resolve) => {
+        const escapedPath = cwd.replaceAll("'", "''");
+        const psCommand = `Start-Process ${powershellCmd} -ArgumentList '-NoExit','-Command',"cd '${escapedPath}'; ${command}"`;
+        debugLog?.(`Launching PowerShell fallback with command: ${psCommand}`);
+        const terminal = spawn(powershellCmd, ['-Command', psCommand], {
+            detached: true,
+            stdio: 'ignore',
+        });
+        terminal.on('error', (err) => {
+            resolve({ success: false, error: `Failed to launch PowerShell: ${err.message}` });
+        });
+        terminal.unref();
+        resolve({ success: true });
+    });
+}
+/**
+ * Launch Windows Terminal or PowerShell fallback.
+ *
+ * @param cwd - Working directory
+ * @param command - Command to execute
+ * @param debugLog - Optional debug logging function
+ */
+async function launchWindowsTerminal(cwd, command, debugLog) {
+    const powershellCmd = detectPowerShell();
+    debugLog?.(`Detected PowerShell: ${powershellCmd}`);
+    return new Promise((resolve) => {
+        const terminal = spawn('wt', ['-d', cwd, powershellCmd, '-NoExit', '-Command', command], {
+            detached: true,
+            stdio: 'ignore',
+        });
+        terminal.on('error', (err) => {
+            // If wt.exe not found, try fallback to Start-Process
+            if (err.message.includes('ENOENT')) {
+                debugLog?.('Windows Terminal not found, using PowerShell fallback');
+                launchPowerShellFallback(cwd, command, powershellCmd, debugLog)
+                    .then(resolve)
+                    .catch(() => resolve({ success: false, error: 'Failed to launch PowerShell fallback' }));
+            }
+            else {
+                resolve({ success: false, error: `Failed to launch terminal: ${err.message}` });
+            }
+        });
+        terminal.unref();
+        resolve({ success: true });
+    });
+}
+/**
+ * Launch macOS Terminal.app with command.
+ *
+ * @param cwd - Working directory
+ * @param command - Command to execute
+ * @param debugLog - Optional debug logging function
+ */
+async function launchMacTerminal(cwd, command, debugLog) {
+    return new Promise((resolve) => {
+        // Escape single quotes for bash context
+        const escapedPath = cwd.replaceAll("'", String.raw `'\''`);
+        const fullCommand = `cd '${escapedPath}' && ${command}`;
+        // Escape double quotes and backslashes for AppleScript context
+        const escapedCommand = fullCommand.replaceAll('\\', '\\\\').replaceAll('"', String.raw `\"`);
+        debugLog?.(`Launching macOS Terminal with command: ${fullCommand}`);
+        const terminal = spawn('osascript', ['-e', `tell application "Terminal" to do script "${escapedCommand}"`], {
+            detached: true,
+            stdio: 'ignore',
+        });
+        terminal.on('error', (err) => {
+            resolve({ success: false, error: `Failed to launch Terminal.app: ${err.message}` });
+        });
+        terminal.unref();
+        resolve({ success: true });
+    });
+}
+/**
+ * Linux terminal emulator configurations.
+ */
+const LINUX_TERMINALS = [
+    { cmd: 'gnome-terminal', getArgs: (command) => ['--', 'bash', '-c', `${command}; exec bash`] },
+    { cmd: 'konsole', getArgs: (command) => ['-e', `bash -c "${command}; exec bash"`] },
+    { cmd: 'xterm', getArgs: (command) => ['-e', `bash -c "${command}; exec bash"`] },
+    { cmd: 'x-terminal-emulator', getArgs: (command) => ['-e', `bash -c "${command}; exec bash"`] },
+];
+/**
+ * Find the first available Linux terminal emulator.
+ * Checks gnome-terminal, konsole, xterm, x-terminal-emulator in order.
+ *
+ * @returns Terminal configuration if found, null otherwise
+ */
+function findAvailableLinuxTerminal() {
+    for (const terminal of LINUX_TERMINALS) {
+        try {
+            execSync(`which ${terminal.cmd}`, { stdio: 'ignore' });
+            return terminal;
+        }
+        catch {
+            // Terminal not found, try next
+            continue;
+        }
+    }
+    return null;
+}
+/**
+ * Launch Linux terminal emulator with command.
+ * Tries gnome-terminal, konsole, xterm, x-terminal-emulator in order.
+ *
+ * @param cwd - Working directory
+ * @param command - Command to execute
+ * @param debugLog - Optional debug logging function
+ */
+async function launchLinuxTerminal(cwd, command, debugLog) {
+    // Find available terminal first (synchronous)
+    const terminal = findAvailableLinuxTerminal();
+    if (!terminal) {
+        return {
+            error: 'No supported terminal emulator found. Please install gnome-terminal, konsole, or xterm.',
+            success: false,
+        };
+    }
+    // Escape single quotes for bash shell
+    const escapedPath = cwd.replaceAll("'", String.raw `'\''`);
+    const fullCommand = `cd '${escapedPath}' && ${command}`;
+    debugLog?.(`Launching ${terminal.cmd} with command: ${fullCommand}`);
+    // Launch terminal (single async operation)
+    return new Promise((resolve) => {
+        const proc = spawn(terminal.cmd, terminal.getArgs(fullCommand), {
+            detached: true,
+            stdio: 'ignore',
+        });
+        proc.on('error', (err) => {
+            resolve({ error: `Failed to launch ${terminal.cmd}: ${err.message}`, success: false });
+        });
+        proc.unref();
+        resolve({ success: true });
+    });
+}
+/**
+ * Launch a new terminal window with the specified command.
+ *
+ * This function automatically detects the platform and uses the appropriate
+ * terminal emulator:
+ * - **Windows**: Windows Terminal (wt.exe) with PowerShell, falls back to PowerShell directly
+ * - **macOS**: Terminal.app via AppleScript
+ * - **Linux**: Tries gnome-terminal, konsole, xterm, x-terminal-emulator in order
+ *
+ * The terminal is launched in detached mode, allowing the parent process to exit
+ * without affecting the new terminal.
+ *
+ * @param options - Terminal launch options
+ * @returns Promise resolving to launch result
+ *
+ * @example
+ * ```typescript
+ * // Launch aiw in a new terminal
+ * const result = await launchTerminal({
+ *   cwd: '/path/to/project',
+ *   command: 'aiw launch',
+ * })
+ *
+ * if (result.success) {
+ *   console.log('Terminal launched successfully')
+ * } else {
+ *   console.error(`Failed: ${result.error}`)
+ * }
+ * ```
+ */
+export async function launchTerminal(options) {
+    const { cwd, command, debugLog } = options;
+    const { platform } = process;
+    debugLog?.(`Launching terminal in ${cwd} with command: ${command}`);
+    debugLog?.(`Platform: ${platform}`);
+    if (platform === 'win32') {
+        return launchWindowsTerminal(cwd, command, debugLog);
+    }
+    if (platform === 'darwin') {
+        return launchMacTerminal(cwd, command, debugLog);
+    }
+    // Linux/Unix
+    return launchLinuxTerminal(cwd, command, debugLog);
+}
+/**
+ * Escape shell argument utility - exported for use in command construction.
+ */
+export { escapeShellArg };

package/dist/lib/tty-detection.d.ts

@@ -0,0 +1,62 @@
+/**
+ * TTY Detection Utilities
+ *
+ * Provides cross-platform TTY detection for controlling color output and spinners.
+ * Respects NO_COLOR and FORCE_COLOR environment variables per standard conventions.
+ */
+/**
+ * Minimal interface for process-like objects used in TTY detection.
+ * Allows dependency injection for testing without mutating Node's process global.
+ */
+export interface ProcessLike {
+    env?: NodeJS.ProcessEnv;
+    stderr?: {
+        isTTY?: boolean | undefined;
+    };
+    stdout: {
+        isTTY?: boolean | undefined;
+    };
+}
+/**
+ * Check if stdout is a TTY (terminal).
+ * Returns true for interactive terminal, false for piped/redirected output.
+ * @param proc - Optional process-like object for testing (defaults to global process)
+ */
+export declare function isTTY(proc?: ProcessLike): boolean;
+/**
+ * Check if stderr is a TTY (terminal).
+ * Useful for determining if error output should use colors.
+ * @param proc - Optional process-like object for testing (defaults to global process)
+ */
+export declare function isStderrTTY(proc?: ProcessLike): boolean;
+/**
+ * Determine if colors should be used in output.
+ * Respects NO_COLOR and FORCE_COLOR environment variables.
+ *
+ * Priority:
+ * 1. NO_COLOR (if set, always disable)
+ * 2. FORCE_COLOR (if set, use level 0-3)
+ * 3. TTY detection (colors only in TTY)
+ *
+ * @param proc - Optional process-like object for testing (defaults to global process)
+ */
+export declare function shouldUseColors(proc?: ProcessLike): boolean;
+/**
+ * Check if quiet mode is enabled from flags.
+ * Quiet mode suppresses informational output (errors still shown).
+ * @param flags - Optional flags object
+ * @param flags.quiet - Quiet mode flag
+ */
+export declare function isQuietMode(flags?: {
+    quiet?: boolean;
+}): boolean;
+/**
+ * Determine if progress spinners should be shown.
+ * Spinners only make sense in interactive terminals.
+ * Automatically disabled in CI environments and quiet mode.
+ * @param flags - Optional flags object with quiet mode
+ * @param proc - Optional process-like object for testing (defaults to global process)
+ */
+export declare function shouldShowSpinners(flags?: {
+    quiet?: boolean;
+}, proc?: ProcessLike): boolean;