@hyperdrive.bot/bmad-workflow 1.0.2

package/dist/services/agents/gemini-agent-runner.js

@@ -0,0 +1,350 @@
+/**
+ * GeminiAgentRunner Service
+ *
+ * Encapsulates Gemini CLI process spawning with comprehensive error handling,
+ * logging, and timeout management for reliable AI agent execution.
+ *
+ * Key difference from Claude: Gemini CLI doesn't support @file references natively,
+ * so this runner preprocesses prompts to inline file content before execution.
+ */
+import { exec } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { promisify } from 'node:util';
+const execAsync = promisify(exec);
+import { PROVIDER_CONFIGS } from '../../models/provider.js';
+/**
+ * Track active child processes for cleanup on SIGINT
+ */
+const activeProcesses = new Set();
+/**
+ * Track if SIGINT handler has been registered
+ */
+let sigintHandlerRegistered = false;
+/**
+ * Register SIGINT handler for graceful process cleanup
+ */
+const registerSigintHandler = (logger) => {
+    if (sigintHandlerRegistered)
+        return;
+    process.on('SIGINT', () => {
+        logger.info({
+            activeProcessCount: activeProcesses.size,
+        }, 'Received SIGINT, cleaning up active Gemini processes');
+        // Kill all active child processes
+        for (const childProcess of activeProcesses) {
+            try {
+                childProcess.kill('SIGTERM');
+            }
+            catch (error) {
+                logger.error({
+                    error: error.message,
+                }, 'Error killing child process');
+            }
+        }
+        // Clear the set
+        activeProcesses.clear();
+        // Exit the main process
+        process.exit(130); // 130 = 128 + SIGINT signal number (2)
+    });
+    sigintHandlerRegistered = true;
+};
+/**
+ * Regex to match @file references in prompts
+ * Matches: @path/to/file.md, @./relative/path.ts, @../parent/file.yaml
+ */
+const FILE_REFERENCE_REGEX = /@(\.{0,2}[\w./-]+\.\w+)/g;
+/**
+ * GeminiAgentRunner service for executing Gemini AI agents
+ *
+ * Spawns Gemini CLI processes to execute AI agents with specified prompts.
+ * Preprocesses @file references to inline file content since Gemini CLI
+ * doesn't support native file references like Claude.
+ *
+ * @example
+ * ```typescript
+ * const logger = createLogger({ namespace: 'agent-runner' })
+ * const runner = new GeminiAgentRunner(logger)
+ * const result = await runner.runAgent({
+ *   prompt: '@.bmad-core/agents/architect.md Create epic for user auth',
+ *   agentType: 'architect',
+ *   timeout: 300000
+ * })
+ * ```
+ */
+export class GeminiAgentRunner {
+    provider = 'gemini';
+    config = PROVIDER_CONFIGS.gemini;
+    logger;
+    /**
+     * Create a new GeminiAgentRunner instance
+     *
+     * @param logger - Logger instance for structured logging
+     */
+    constructor(logger) {
+        this.logger = logger;
+        registerSigintHandler(logger);
+    }
+    /**
+     * Get the count of active processes
+     * (Useful for testing and monitoring purposes)
+     *
+     * @returns Number of currently active child processes
+     */
+    getActiveProcessCount() {
+        return activeProcesses.size;
+    }
+    /**
+     * Execute a Gemini AI agent with the specified prompt and options
+     *
+     * This method spawns a Gemini CLI process, captures output, handles errors,
+     * and enforces timeouts. It preprocesses @file references to inline content
+     * since Gemini CLI doesn't support native file references.
+     *
+     * @param prompt - The prompt to execute with the agent
+     * @param options - Agent execution options (without prompt)
+     * @returns AgentResult with success status, output, errors, and metadata
+     */
+    async runAgent(prompt, options) {
+        const startTime = Date.now();
+        const timeout = options.timeout ?? 1_800_000; // Default 30 minutes
+        // Input validation
+        if (!prompt || prompt.trim().length === 0) {
+            return this.returnWithCallback({
+                agentType: options.agentType,
+                duration: Date.now() - startTime,
+                errors: 'Prompt is required and cannot be empty',
+                exitCode: -1,
+                output: '',
+                success: false,
+            }, options.onResponse);
+        }
+        // Preprocess prompt to inline @file references
+        const processedPrompt = this.preprocessPrompt(prompt);
+        // Log execution start with metadata
+        this.logger.info({
+            agentType: options.agentType,
+            originalPromptLength: prompt.length,
+            processedPromptLength: processedPrompt.length,
+            references: options.references?.length ?? 0,
+            timeout,
+        }, 'Executing Gemini agent');
+        // Invoke onPrompt callback if provided
+        if (options.onPrompt) {
+            try {
+                // Create options object without callbacks for the callback
+                // eslint-disable-next-line @typescript-eslint/no-unused-vars
+                const { onPrompt, onResponse, ...callbackOptions } = options;
+                await onPrompt(processedPrompt, callbackOptions);
+            }
+            catch (error) {
+                this.logger.warn({ error: error.message }, 'Error in onPrompt callback');
+            }
+        }
+        // Build full command string
+        // Escape double quotes and backticks in the prompt
+        const escapedPrompt = processedPrompt
+            .replaceAll('\\', String.raw `\\`)
+            .replaceAll('"', String.raw `\"`)
+            .replaceAll('`', String.raw `\``)
+            .replaceAll('$', String.raw `\$`);
+        // Build command with provider config flags
+        // Gemini uses -p flag which expects the prompt as the next argument
+        const command = `${this.config.command} -p "${escapedPrompt}" --yolo < /dev/null`;
+        // Log the command being executed (truncated for readability)
+        this.logger.info({
+            commandLength: command.length,
+            promptLength: processedPrompt.length,
+        }, 'Executing Gemini command');
+        let stdoutData = '';
+        let stderrData = '';
+        try {
+            // Use exec instead of spawn for better shell compatibility
+            const { stderr, stdout } = await execAsync(command, {
+                env: process.env,
+                maxBuffer: 10 * 1024 * 1024, // 10MB buffer
+                shell: process.env.SHELL || '/bin/bash',
+                timeout,
+            });
+            stdoutData = stdout;
+            stderrData = stderr;
+            const duration = Date.now() - startTime;
+            this.logger.info({
+                duration,
+                stderrLength: stderrData.length,
+                stdoutLength: stdoutData.length,
+            }, 'Gemini CLI process completed successfully');
+            const result = {
+                agentType: options.agentType,
+                duration,
+                errors: stderrData,
+                exitCode: 0,
+                output: stdoutData,
+                success: true,
+            };
+            return this.returnWithCallback(result, options.onResponse);
+        }
+        catch (error) {
+            // Handle exec errors (includes timeout, non-zero exit, etc.)
+            const duration = Date.now() - startTime;
+            // Extract stdout/stderr from exec error if available
+            const execError = error;
+            if (execError.stdout)
+                stdoutData = execError.stdout;
+            if (execError.stderr)
+                stderrData = execError.stderr;
+            const exitCode = execError.code ?? -1;
+            const isTimeout = execError.killed === true && execError.signal === 'SIGTERM';
+            const wasKilled = execError.killed === true;
+            const signal = execError.signal ?? null;
+            // Build detailed error context for debugging
+            const errorContext = this.buildErrorContext({
+                cmd: execError.cmd,
+                duration,
+                exitCode,
+                isTimeout,
+                signal,
+                stderrData,
+                stdoutData,
+                wasKilled,
+            });
+            this.logger.error({
+                cmd: execError.cmd,
+                duration,
+                error: execError.message,
+                exitCode,
+                isTimeout,
+                signal,
+                stderrLength: stderrData.length,
+                stdoutLength: stdoutData.length,
+                wasKilled,
+            }, isTimeout ? 'Gemini CLI process timeout' : 'Gemini CLI process error');
+            return this.returnWithCallback({
+                agentType: options.agentType,
+                duration,
+                errors: errorContext,
+                exitCode: isTimeout ? 124 : exitCode,
+                output: stdoutData,
+                success: false,
+            }, options.onResponse);
+        }
+    }
+    /**
+     * Build detailed error context for debugging process failures
+     * @private
+     */
+    buildErrorContext(info) {
+        const lines = [];
+        // Determine the type of failure
+        if (info.isTimeout) {
+            lines.push(`Process timeout after ${info.duration}ms`);
+        }
+        else if (info.wasKilled) {
+            lines.push('Process was killed externally');
+            // Explain common exit codes
+            switch (info.exitCode) {
+                case 130: {
+                    lines.push('Exit code 130 = SIGINT (user interrupt, Ctrl+C)');
+                    break;
+                }
+                case 137: {
+                    lines.push('Exit code 137 = SIGKILL (process forcefully killed)', 'Possible causes:', '  - System OOM killer', '  - Exceeded memory limits', '  - Docker/container killed the process');
+                    break;
+                }
+                case 143: {
+                    lines.push('Exit code 143 = SIGTERM (process terminated)', 'Possible causes:', '  - System OOM killer terminated the process', '  - Another process sent SIGTERM', '  - Parent process cleanup', '  - Docker/container resource limits');
+                    break;
+                }
+                // No default
+            }
+            if (info.signal) {
+                lines.push(`Signal received: ${info.signal}`);
+            }
+            else {
+                lines.push('No signal information available (signal: null)');
+            }
+        }
+        else {
+            lines.push(`Process exited with code ${info.exitCode}`);
+        }
+        // Add duration context
+        lines.push(`Duration: ${(info.duration / 1000).toFixed(2)}s`);
+        // Add output context
+        if (info.stdoutData.length > 0) {
+            lines.push(`Stdout (${info.stdoutData.length} chars):`);
+            // Truncate if too long, show last 500 chars which are often most relevant
+            const truncatedStdout = info.stdoutData.length > 500 ? `...[truncated]...\n${info.stdoutData.slice(-500)}` : info.stdoutData;
+            lines.push(truncatedStdout);
+        }
+        else {
+            lines.push('Stdout: (empty - no output captured)');
+        }
+        if (info.stderrData.length > 0) {
+            lines.push(`Stderr (${info.stderrData.length} chars):`);
+            const truncatedStderr = info.stderrData.length > 500 ? `...[truncated]...\n${info.stderrData.slice(-500)}` : info.stderrData;
+            lines.push(truncatedStderr);
+        }
+        else {
+            lines.push('Stderr: (empty - no error output)');
+        }
+        // Add command for reference (truncated if too long)
+        if (info.cmd) {
+            const truncatedCmd = info.cmd.length > 200 ? `${info.cmd.slice(0, 200)}...[truncated]` : info.cmd;
+            lines.push(`Command: ${truncatedCmd}`);
+        }
+        // Add troubleshooting suggestions for empty output
+        if (info.stdoutData.length === 0 && info.stderrData.length === 0) {
+            lines.push('', 'Troubleshooting (no output captured):', '  1. Check system resources (memory, CPU)', '  2. Verify Gemini CLI is properly installed: `gemini --version`', '  3. Check for Gemini API issues', '  4. Review system logs: `dmesg | tail -50` (for OOM killer)', '  5. Try running the command manually to see output');
+        }
+        return lines.join('\n');
+    }
+    /**
+     * Preprocess prompt to inline @file references
+     *
+     * Since Gemini CLI doesn't support @file syntax natively, this method
+     * finds all @file references and replaces them with the actual file content.
+     *
+     * @param prompt - The original prompt with @file references
+     * @param basePath - Base path for resolving relative file paths
+     * @returns Preprocessed prompt with inlined file content
+     */
+    preprocessPrompt(prompt, basePath = process.cwd()) {
+        const inlinedFiles = [];
+        const processedPrompt = prompt.replaceAll(FILE_REFERENCE_REGEX, (match, filePath) => {
+            const absolutePath = resolve(basePath, filePath);
+            if (!existsSync(absolutePath)) {
+                this.logger.warn({ absolutePath, filePath }, 'File reference not found, keeping original reference');
+                return match; // Keep original @file reference if file doesn't exist
+            }
+            try {
+                const content = readFileSync(absolutePath, 'utf8');
+                inlinedFiles.push(filePath);
+                // Return the file content wrapped in a clear delimiter
+                return `\n--- BEGIN FILE: ${filePath} ---\n${content}\n--- END FILE: ${filePath} ---\n`;
+            }
+            catch (error) {
+                this.logger.error({ absolutePath, error: error.message, filePath }, 'Error reading file for inlining');
+                return match; // Keep original reference on error
+            }
+        });
+        if (inlinedFiles.length > 0) {
+            this.logger.info({ fileCount: inlinedFiles.length, files: inlinedFiles }, 'Inlined file references for Gemini CLI');
+        }
+        return processedPrompt;
+    }
+    /**
+     * Invoke onResponse callback and return result
+     * @private
+     */
+    async returnWithCallback(result, onResponse) {
+        if (onResponse) {
+            try {
+                await onResponse(result);
+            }
+            catch (error) {
+                this.logger.warn({ error: error.message }, 'Error in onResponse callback');
+            }
+        }
+        return result;
+    }
+}

package/dist/services/agents/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Agent Services Exports
+ */
+export * from './agent-runner-factory.js';
+export * from './agent-runner.js';
+export * from './claude-agent-runner.js';
+export * from './gemini-agent-runner.js';

package/dist/services/agents/index.js

@@ -0,0 +1,7 @@
+/**
+ * Agent Services Exports
+ */
+export * from './agent-runner-factory.js';
+export * from './agent-runner.js';
+export * from './claude-agent-runner.js';
+export * from './gemini-agent-runner.js';

package/dist/services/file-system/file-manager.d.ts

@@ -0,0 +1,110 @@
+/**
+ * FileManager Service
+ *
+ * Provides safe file system operations with error handling and logging.
+ * All file operations throughout the CLI should use this service for consistency and testability.
+ */
+import type pino from 'pino';
+/**
+ * FileManager service for all file system operations
+ *
+ * Abstracts file system operations behind a consistent interface with
+ * comprehensive error handling and logging. All methods use async/await
+ * for consistency.
+ */
+export declare class FileManager {
+    /**
+     * Logger instance for file operations
+     */
+    private readonly logger;
+    /**
+     * Create a new FileManager instance
+     *
+     * @param logger - Pino logger instance for logging file operations
+     * @example
+     * const logger = createLogger({ namespace: 'services:file-system' })
+     * const fileManager = new FileManager(logger)
+     */
+    constructor(logger: pino.Logger);
+    /**
+     * Create a directory (and parent directories if needed)
+     *
+     * Uses ensureDir which is idempotent - safe to call if directory already exists.
+     *
+     * @param path - Path to the directory to create
+     * @throws {FileSystemError} If directory cannot be created (permission denied, invalid path, etc.)
+     * @example
+     * await fileManager.createDirectory('docs/epics')
+     */
+    createDirectory(path: string): Promise<void>;
+    /**
+     * Check if a file or directory exists
+     *
+     * @param path - Path to check for existence
+     * @returns True if path exists, false otherwise
+     * @example
+     * const exists = await fileManager.fileExists('docs/prd.md')
+     * if (!exists) {
+     *   throw new Error('PRD not found')
+     * }
+     */
+    fileExists(path: string): Promise<boolean>;
+    /**
+     * List files in a directory matching an optional pattern
+     *
+     * @param directory - Directory to list files from
+     * @param pattern - Optional glob pattern to filter files (e.g., '*.md', 'STORY-*.md')
+     * @returns Array of file paths matching the pattern
+     * @throws {FileSystemError} If directory cannot be read
+     * @example
+     * const storyFiles = await fileManager.listFiles('docs/stories', 'STORY-*.md')
+     */
+    listFiles(directory: string, pattern?: string): Promise<string[]>;
+    /**
+     * Move a file from source to destination
+     *
+     * Creates destination directory if it doesn't exist.
+     * Overwrites destination file if it exists.
+     *
+     * @param source - Source file path
+     * @param dest - Destination file path
+     * @throws {FileSystemError} If file cannot be moved (source not found, permission denied, etc.)
+     * @example
+     * await fileManager.moveFile('docs/stories/1.1-story.md', 'docs/qa/stories/1.1-story.md')
+     */
+    moveFile(source: string, dest: string): Promise<void>;
+    /**
+     * Read file contents as UTF-8 string
+     *
+     * @param path - Path to the file to read
+     * @returns File content as string
+     * @throws {FileSystemError} If file cannot be read (not found, permission denied, etc.)
+     * @example
+     * const content = await fileManager.readFile('docs/prd.md')
+     */
+    readFile(path: string): Promise<string>;
+    /**
+     * Write content to file as UTF-8
+     *
+     * Creates parent directories if they don't exist.
+     * Overwrites existing file if present.
+     *
+     * @param path - Path to the file to write
+     * @param content - Content to write to file
+     * @throws {FileSystemError} If file cannot be written (permission denied, invalid path, etc.)
+     * @example
+     * await fileManager.writeFile('docs/epics/epic-1.md', epicContent)
+     */
+    writeFile(path: string, content: string): Promise<void>;
+    /**
+     * Match a file name against a simple glob pattern
+     *
+     * Supports * wildcard only (e.g., 'STORY-*.md', '*.txt')
+     *
+     * @param fileName - File name to check
+     * @param pattern - Glob pattern with * wildcards
+     * @returns True if file matches pattern
+     * @private
+     */
+    private matchesPattern;
+}