ralphblaster-agent 0.1.1

package/src/executor/error-handler.js

@@ -0,0 +1,65 @@
+const logger = require('../logger');
+
+/**
+ * Categorize error for user-friendly messaging
+ * @param {Error} error - The error object
+ * @param {string} stderr - Standard error output
+ * @param {number} exitCode - Process exit code
+ * @returns {Object} Object with category, userMessage, and technicalDetails
+ */
+function categorizeError(error, stderr = '', exitCode = null) {
+  let category = 'unknown';
+  let userMessage = error.message || String(error);
+  let technicalDetails = `Error: ${error.message}\nStderr: ${stderr}\nExit Code: ${exitCode}`;
+
+  // Check for Claude CLI not installed
+  if (error.code === 'ENOENT') {
+    category = 'claude_not_installed';
+    userMessage = 'Claude Code CLI is not installed or not found in PATH';
+  }
+  // Check for authentication issues
+  else if (stderr.match(/not authenticated/i) || stderr.match(/authentication failed/i) || stderr.match(/please log in/i)) {
+    category = 'not_authenticated';
+    userMessage = 'Claude CLI is not authenticated. Please run "claude auth"';
+  }
+  // Check for token limit exceeded
+  else if (stderr.match(/token limit exceeded/i) || stderr.match(/quota exceeded/i) || stderr.match(/insufficient credits/i)) {
+    category = 'out_of_tokens';
+    userMessage = 'Claude API token limit has been exceeded';
+  }
+  // Check for rate limiting
+  else if (stderr.match(/rate limit/i) || stderr.match(/too many requests/i) || stderr.match(/429/)) {
+    category = 'rate_limited';
+    userMessage = 'Claude API rate limit reached. Please wait before retrying';
+  }
+  // Check for permission denied
+  else if (stderr.match(/permission denied/i) || stderr.match(/EACCES/i) || error.code === 'EACCES') {
+    category = 'permission_denied';
+    userMessage = 'Permission denied accessing project files or directories';
+  }
+  // Check for timeout
+  else if (error.message && error.message.includes('timed out')) {
+    category = 'execution_timeout';
+    userMessage = 'Job execution exceeded the maximum timeout';
+  }
+  // Check for network errors
+  else if (error.code === 'ECONNREFUSED' || error.code === 'ENOTFOUND' || error.code === 'ETIMEDOUT') {
+    category = 'network_error';
+    userMessage = 'Network error connecting to Claude API';
+  }
+  // Check for non-zero exit code (execution error)
+  else if (exitCode !== null && exitCode !== 0) {
+    category = 'execution_error';
+    userMessage = `Claude CLI execution failed with exit code ${exitCode}`;
+  }
+
+  logger.debug(`Error categorized as: ${category}`);
+
+  return {
+    category,
+    userMessage,
+    technicalDetails
+  };
+}
+
+module.exports = { categorizeError };

package/src/executor/git-helper.js

@@ -0,0 +1,196 @@
+const { spawn } = require('child_process');
+const fs = require('fs');
+const logger = require('../logger');
+
+/**
+ * GitHelper - Handles git operations for worktrees
+ * Extracted from Executor class to improve modularity and testability
+ */
+class GitHelper {
+  /**
+   * Helper to run git commands in worktree
+   * @param {string} cwd - Working directory
+   * @param {Array<string>} args - Git command arguments
+   * @returns {Promise<string>} Command output
+   */
+  async runGitCommand(cwd, args) {
+    return new Promise((resolve, reject) => {
+      const git = spawn('git', args, { cwd });
+      let output = '';
+
+      git.stdout.on('data', (data) => {
+        output += data.toString();
+      });
+
+      git.on('close', (code) => {
+        if (code === 0) {
+          resolve(output);
+        } else {
+          reject(new Error(`Git command failed with code ${code}`));
+        }
+      });
+
+      git.on('error', reject);
+    });
+  }
+
+  /**
+   * Get current branch name from worktree
+   * @param {string} worktreePath - Path to worktree
+   * @returns {Promise<string>} Branch name
+   */
+  async getCurrentBranch(worktreePath) {
+    try {
+      const branch = await this.runGitCommand(
+        worktreePath,
+        ['rev-parse', '--abbrev-ref', 'HEAD']
+      );
+      return branch.trim();
+    } catch (error) {
+      throw error;
+    }
+  }
+
+  /**
+   * Log comprehensive git activity summary for a job
+   * @param {string} worktreePath - Path to worktree
+   * @param {string} branchName - Name of the branch
+   * @param {string} jobId - Job identifier
+   * @param {Function} onProgress - Optional progress callback
+   * @returns {Promise<Object>} Git activity summary object
+   */
+  async logGitActivity(worktreePath, branchName, jobId, onProgress = null) {
+    if (!worktreePath || !fs.existsSync(worktreePath)) {
+      logger.warn(`Worktree not found for git activity logging: ${worktreePath}`);
+      return;
+    }
+
+    try {
+      // Get commit count on this branch (new commits only, not in origin/main)
+      const commitCount = await new Promise((resolve) => {
+        const gitLog = spawn('git', ['rev-list', '--count', 'HEAD', `^origin/main`], {
+          cwd: worktreePath,
+          stdio: ['ignore', 'pipe', 'pipe']
+        });
+
+        let stdout = '';
+        gitLog.stdout.on('data', (data) => stdout += data.toString());
+        gitLog.on('close', () => resolve(parseInt(stdout.trim()) || 0));
+        gitLog.on('error', () => resolve(0));
+      });
+
+      // Also check for uncommitted changes
+      const hasUncommittedChanges = await new Promise((resolve) => {
+        const gitStatus = spawn('git', ['status', '--porcelain'], {
+          cwd: worktreePath,
+          stdio: ['ignore', 'pipe', 'pipe']
+        });
+
+        let stdout = '';
+        gitStatus.stdout.on('data', (data) => stdout += data.toString());
+        gitStatus.on('close', () => resolve(stdout.trim().length > 0));
+        gitStatus.on('error', () => resolve(false));
+      });
+
+      // Get last commit message and hash if commits exist
+      let lastCommitInfo = 'No commits yet';
+      if (commitCount > 0) {
+        lastCommitInfo = await new Promise((resolve) => {
+          const gitLog = spawn('git', ['log', '-1', '--pretty=format:%h - %s'], {
+            cwd: worktreePath,
+            stdio: ['ignore', 'pipe', 'pipe']
+          });
+
+          let stdout = '';
+          gitLog.stdout.on('data', (data) => stdout += data.toString());
+          gitLog.on('close', () => resolve(stdout.trim() || 'No commit info'));
+          gitLog.on('error', () => resolve('Failed to get commit info'));
+        });
+      }
+
+      // Check if branch was pushed to remote
+      const wasPushed = await new Promise((resolve) => {
+        const gitBranch = spawn('git', ['branch', '-r', '--contains', 'HEAD'], {
+          cwd: worktreePath,
+          stdio: ['ignore', 'pipe', 'pipe']
+        });
+
+        let stdout = '';
+        gitBranch.stdout.on('data', (data) => stdout += data.toString());
+        gitBranch.on('close', () => {
+          const remoteBranches = stdout.trim();
+          resolve(remoteBranches.includes(`origin/${branchName}`));
+        });
+        gitBranch.on('error', () => resolve(false));
+      });
+
+      // Get file change stats
+      const changeStats = await new Promise((resolve) => {
+        const gitDiff = spawn('git', ['diff', '--shortstat', 'origin/main...HEAD'], {
+          cwd: worktreePath,
+          stdio: ['ignore', 'pipe', 'pipe']
+        });
+
+        let stdout = '';
+        gitDiff.stdout.on('data', (data) => stdout += data.toString());
+        gitDiff.on('close', () => resolve(stdout.trim() || 'No changes'));
+        gitDiff.on('error', () => resolve('Failed to get change stats'));
+      });
+
+      // Build comprehensive git activity summary
+      const summaryLines = [];
+      summaryLines.push('');
+      summaryLines.push('═══════════════════════════════════════════════════════════');
+      summaryLines.push(`Git Activity Summary for Job #${jobId}`);
+      summaryLines.push('═══════════════════════════════════════════════════════════');
+      summaryLines.push(`Branch: ${branchName}`);
+      summaryLines.push(`New commits: ${commitCount}`);
+
+      if (commitCount > 0) {
+        summaryLines.push(`Latest commit: ${lastCommitInfo}`);
+        summaryLines.push(`Changes: ${changeStats}`);
+        summaryLines.push(`Pushed to remote: ${wasPushed ? 'YES ✓' : 'NO (local only)'}`);
+      } else {
+        summaryLines.push('⚠️  NO COMMITS MADE - Ralph did not create any commits');
+        if (hasUncommittedChanges) {
+          summaryLines.push('⚠️  Uncommitted changes detected - work was done but not committed!');
+        } else {
+          summaryLines.push('⚠️  No file changes detected - Ralph may have failed or had nothing to do');
+        }
+      }
+      summaryLines.push('═══════════════════════════════════════════════════════════');
+      summaryLines.push('');
+
+      const summaryText = summaryLines.join('\n');
+
+      // Log to console
+      logger.info(summaryText);
+
+      // Send to server if progress callback provided
+      if (onProgress) {
+        onProgress(summaryText);
+      }
+
+      // Return structured summary object
+      return {
+        branchName,
+        commitCount,
+        lastCommitInfo: commitCount > 0 ? lastCommitInfo : null,
+        changeStats: commitCount > 0 ? changeStats : null,
+        wasPushed,
+        hasUncommittedChanges,
+        summaryText
+      };
+    } catch (error) {
+      logger.warn(`Failed to log git activity: ${error.message}`);
+      return {
+        branchName,
+        commitCount: 0,
+        error: error.message,
+        summaryText: `Failed to gather git activity: ${error.message}`
+      };
+    }
+  }
+}
+
+module.exports = GitHelper;

package/src/executor/index.js

@@ -0,0 +1,296 @@
+const path = require('path');
+const logger = require('../logger');
+const { validatePrompt } = require('./prompt-validator');
+const { categorizeError } = require('./error-handler');
+const GitHelper = require('./git-helper');
+const ClaudeRunner = require('./claude-runner');
+const PathHelper = require('./path-helper');
+const PrdGenerationHandler = require('./job-handlers/prd-generation');
+const CodeExecutionHandler = require('./job-handlers/code-execution');
+const ClarifyingQuestionsHandler = require('./job-handlers/clarifying-questions');
+
+// Timeout constants
+const TIMEOUTS = {
+  PROCESS_KILL_GRACE_PERIOD_MS: 2000, // 2 seconds grace period for process termination
+};
+
+class Executor {
+  constructor(apiClient = null) {
+    this.apiClient = apiClient; // Optional API client for metadata updates
+    this.gitHelper = new GitHelper(); // Git operations helper
+
+    // Create ClaudeRunner with dependencies
+    const errorHandler = { categorizeError };
+    this.claudeRunner = new ClaudeRunner(errorHandler, this.gitHelper);
+    this.claudeRunner.setApiClient(apiClient);
+
+    // Create shared validators and helpers
+    const promptValidator = { validatePrompt };
+    const pathValidator = { validateAndSanitizePath: this.validateAndSanitizePath.bind(this) };
+    const pathHelper = new PathHelper(pathValidator);
+
+    // Create PrdGenerationHandler with dependencies
+    this.prdGenerationHandler = new PrdGenerationHandler(
+      promptValidator,
+      pathHelper,
+      this.claudeRunner,
+      apiClient
+    );
+
+    // Create CodeExecutionHandler with dependencies
+    this.codeExecutionHandler = new CodeExecutionHandler(
+      promptValidator,
+      pathHelper,
+      this.claudeRunner,
+      this.gitHelper,
+      apiClient
+    );
+
+    // Create ClarifyingQuestionsHandler with dependencies
+    this.clarifyingQuestionsHandler = new ClarifyingQuestionsHandler(
+      promptValidator,
+      pathHelper,
+      this.claudeRunner,
+      apiClient
+    );
+  }
+
+  /**
+   * Getter for currentProcess (delegates to claudeRunner for backward compatibility)
+   */
+  get currentProcess() {
+    return this.claudeRunner.currentProcess;
+  }
+
+  /**
+   * Setter for currentProcess (delegates to claudeRunner for backward compatibility)
+   */
+  set currentProcess(value) {
+    this.claudeRunner.currentProcess = value;
+  }
+
+  /**
+   * Get sanitized environment variables (delegates to claudeRunner for backward compatibility)
+   * @returns {Object} Sanitized environment object
+   */
+  getSanitizedEnv() {
+    return this.claudeRunner.getSanitizedEnv();
+  }
+
+  /**
+   * Execute a job using Claude CLI
+   * @param {Object} job - Job object from API
+   * @param {Function} onProgress - Callback for progress updates
+   * @returns {Promise<Object>} Execution result
+   */
+  async execute(job, onProgress) {
+    const startTime = Date.now();
+
+    // Store job ID for progress tracking
+    this.currentJobId = job.id;
+
+    // Set job ID in ClaudeRunner for progress tracking
+    this.claudeRunner.setJobId(job.id);
+
+    // Display human-friendly job description
+    const jobDescription = job.job_type === 'plan_generation'
+      ? `${job.prd_mode === 'plan' ? 'plan' : 'PRD'} generation`
+      : job.job_type;
+
+    logger.info(`Executing ${jobDescription} job #${job.id}`);
+
+    // Route to appropriate handler based on job type
+    if (job.job_type === 'plan_generation') {
+      return await this.executePrdGeneration(job, onProgress, startTime);
+    } else if (job.job_type === 'code_execution') {
+      return await this.executeCodeImplementation(job, onProgress, startTime);
+    } else if (job.job_type === 'clarifying_questions') {
+      return await this.executeClarifyingQuestions(job, onProgress, startTime);
+    } else {
+      throw new Error(`Unknown job type: ${job.job_type}`);
+    }
+  }
+
+
+  /**
+   * Execute PRD/Plan generation using Claude
+   * @param {Object} job - Job object from API
+   * @param {Function} onProgress - Callback for progress updates
+   * @param {number} startTime - Start timestamp
+   * @returns {Promise<Object>} Execution result
+   */
+  async executePrdGeneration(job, onProgress, startTime) {
+    // Determine content type from prd_mode field
+    const contentType = job.prd_mode === 'plan' ? 'Plan' : 'PRD';
+    logger.info(`Generating ${contentType} for: ${job.task_title}`);
+
+    // Delegate to PrdGenerationHandler based on mode
+    if (job.prd_mode === 'plan') {
+      return await this.prdGenerationHandler.executePlanGeneration(job, onProgress, startTime);
+    } else {
+      return await this.prdGenerationHandler.executeStandardPrd(job, onProgress, startTime);
+    }
+  }
+
+
+  /**
+   * Execute code implementation using Claude
+   * Delegates to CodeExecutionHandler
+   * @param {Object} job - Job object from API
+   * @param {Function} onProgress - Callback for progress updates
+   * @param {number} startTime - Start timestamp
+   * @returns {Promise<Object>} Execution result
+   */
+  async executeCodeImplementation(job, onProgress, startTime) {
+    return await this.codeExecutionHandler.executeCodeImplementation(job, onProgress, startTime);
+  }
+
+  /**
+   * Execute clarifying questions generation using Claude
+   * Delegates to ClarifyingQuestionsHandler
+   * @param {Object} job - Job object from API
+   * @param {Function} onProgress - Callback for progress updates
+   * @param {number} startTime - Start timestamp
+   * @returns {Promise<Object>} Execution result with JSON output
+   */
+  async executeClarifyingQuestions(job, onProgress, startTime) {
+    logger.info(`Generating clarifying questions for: ${job.task_title}`);
+    return await this.clarifyingQuestionsHandler.executeClarifyingQuestions(job, onProgress, startTime);
+  }
+
+
+  /**
+   * Kill the current running process if any
+   * Used during shutdown to prevent orphaned processes
+   * @returns {Promise<void>} Resolves when process is killed or grace period expires
+   */
+  async killCurrentProcess() {
+    // Capture process reference to avoid race condition where a new process
+    // is assigned to this.currentProcess between SIGTERM and SIGKILL
+    const processToKill = this.currentProcess;
+
+    if (processToKill && !processToKill.killed) {
+      logger.warn('Killing current Claude process due to shutdown');
+      try {
+        processToKill.kill('SIGTERM');
+
+        // Wait for grace period, then force kill if still alive
+        await new Promise((resolve) => {
+          setTimeout(() => {
+            // Check the captured process reference, not this.currentProcess
+            if (processToKill && !processToKill.killed) {
+              logger.warn('Force killing Claude process with SIGKILL');
+              try {
+                processToKill.kill('SIGKILL');
+              } catch (killError) {
+                logger.error('Error force killing process', killError.message);
+              }
+            }
+            resolve();
+          }, TIMEOUTS.PROCESS_KILL_GRACE_PERIOD_MS);
+        });
+      } catch (error) {
+        logger.error('Error killing Claude process', error.message);
+      }
+    }
+  }
+
+  /**
+   * Validate and sanitize file system path to prevent directory traversal attacks
+   * @param {string} userPath - Path provided by user/API
+   * @returns {string|null} Sanitized absolute path or null if invalid
+   */
+  validateAndSanitizePath(userPath) {
+    if (!userPath || typeof userPath !== 'string') {
+      logger.warn('Path is empty or not a string');
+      return null;
+    }
+
+    try {
+      // Resolve to absolute path and normalize (removes .., ., etc.)
+      const resolvedPath = path.resolve(userPath);
+
+      // Check for null bytes (path traversal attack vector)
+      if (resolvedPath.includes('\0')) {
+        logger.error('Path contains null bytes (potential attack)');
+        return null;
+      }
+
+      // Comprehensive blacklist of protected system directories
+      const dangerousPaths = [
+        '/etc', '/bin', '/sbin', '/usr/bin', '/usr/sbin',  // Core system dirs
+        '/System', '/Library', '/private',                   // macOS system dirs
+        '/Windows', '/Program Files', '/Program Files (x86)', // Windows system dirs
+        '/root', '/boot', '/dev', '/proc', '/sys'            // Linux/Unix system dirs
+      ];
+
+      for (const dangerousPath of dangerousPaths) {
+        if (resolvedPath === dangerousPath || resolvedPath.startsWith(dangerousPath + '/')) {
+          logger.error(`Path points to protected system directory: ${resolvedPath}`);
+          return null;
+        }
+      }
+
+      // Block access to sensitive subdirectories even within user directories
+      const sensitiveSubdirectories = [
+        '.ssh',                    // SSH keys
+        '.aws',                    // AWS credentials
+        '.config/gcloud',          // Google Cloud credentials
+        '.azure',                  // Azure credentials
+        '.kube',                   // Kubernetes configs
+        '.docker',                 // Docker credentials
+        '.gnupg',                  // GPG keys
+        'Library/Keychains',       // macOS keychains
+        'AppData/Roaming',         // Windows credential storage
+        '.password-store',         // pass password manager
+        '.config/1Password',       // 1Password
+        '.config/Bitwarden'        // Bitwarden
+      ];
+
+      for (const sensitiveDir of sensitiveSubdirectories) {
+        const normalizedDir = sensitiveDir.replace(/\//g, path.sep);
+        if (resolvedPath.includes(path.sep + normalizedDir + path.sep) ||
+            resolvedPath.endsWith(path.sep + normalizedDir)) {
+          logger.error(`Path contains sensitive directory: ${sensitiveDir}`);
+          return null;
+        }
+      }
+
+      // Check if path is within allowed base paths (if configured)
+      const allowedBasePathsEnv = process.env.RALPHBLASTER_ALLOWED_PATHS;
+      const allowedBasePaths = allowedBasePathsEnv
+        ? allowedBasePathsEnv.split(':')
+        : null;
+
+      if (allowedBasePaths && allowedBasePaths.length > 0) {
+        const isAllowed = allowedBasePaths.some(basePath => {
+          const resolvedBase = path.resolve(basePath);
+          return resolvedPath === resolvedBase || resolvedPath.startsWith(resolvedBase + path.sep);
+        });
+
+        if (!isAllowed) {
+          logger.error(`Path is outside allowed base paths: ${resolvedPath}`);
+          return null;
+        }
+      } else {
+        // If no whitelist is configured, warn if path is outside typical user directories
+        const isUserPath = resolvedPath.startsWith('/Users/') ||    // macOS
+                          resolvedPath.startsWith('/home/') ||      // Linux
+                          /^[A-Z]:\\Users\\/i.test(resolvedPath);   // Windows
+
+        if (!isUserPath) {
+          logger.warn(`Path is outside typical user directories: ${resolvedPath}`);
+          // Don't reject, just warn - some valid projects might be elsewhere
+        }
+      }
+
+      logger.debug(`Path sanitized: ${userPath} -> ${resolvedPath}`);
+      return resolvedPath;
+    } catch (error) {
+      logger.error('Error sanitizing path', error.message);
+      return null;
+    }
+  }
+}
+
+module.exports = Executor;