@howlil/ez-agents 3.5.0 → 4.0.0

package/bin/lib/retry.cjs

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+
+/**
+ * EZ Retry — Retry utility with exponential backoff
+ * 
+ * Features:
+ * - Configurable max retries, base delay, max delay
+ * - Jitter to prevent thundering herd
+ * - Error classification (retryable vs non-retryable)
+ * 
+ * Usage:
+ *   const { retry, isRetryableError } = require('./retry.cjs');
+ *   const result = await retry(() => fetch(url), { maxRetries: 3 });
+ */
+
+const Logger = require('./logger.cjs');
+const logger = new Logger();
+
+/**
+ * Retry an operation with exponential backoff
+ * @param {Function} operation - Async function to retry
+ * @param {Object} options - Retry options
+ * @returns {Promise<any>} - Result of operation
+ */
+async function retry(operation, options = {}) {
+  const {
+    maxRetries = 3,
+    baseDelay = 1000,
+    maxDelay = 30000,
+    jitter = true,
+    shouldRetry = isRetryableError
+  } = options;
+
+  let lastError;
+  let lastAttempt = null;
+
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      lastAttempt = attempt;
+      return await operation();
+    } catch (err) {
+      lastError = err;
+      
+      // Don't retry if error is not retryable or max retries reached
+      if (attempt === maxRetries || !shouldRetry(err)) {
+        logger.error('Operation failed after retries', { 
+          attempts: attempt + 1, 
+          error: err.message 
+        });
+        break;
+      }
+
+      // Calculate delay with exponential backoff and jitter
+      const delay = Math.min(
+        baseDelay * Math.pow(2, attempt),
+        maxDelay
+      );
+      const jitteredDelay = jitter ? delay * (0.5 + Math.random()) : delay;
+
+      logger.warn('Retrying operation', { 
+        attempt: attempt + 1, 
+        maxRetries, 
+        delay: Math.round(jitteredDelay),
+        error: err.message 
+      });
+
+      await new Promise(resolve => setTimeout(resolve, jitteredDelay));
+    }
+  }
+
+  const error = new Error(`Operation failed after ${lastAttempt + 1} attempts: ${lastError.message}`);
+  error.cause = lastError;
+  throw error;
+}
+
+/**
+ * Check if error is retryable
+ * @param {Error} err - Error to check
+ * @returns {boolean} - True if retryable
+ */
+function isRetryableError(err) {
+  const retryableCodes = ['ECONNRESET', 'ETIMEDOUT', 'EAI_AGAIN', 'ENOTFOUND'];
+  const retryableStatus = [429, 500, 502, 503, 504];
+
+  if (err.code && retryableCodes.includes(err.code)) return true;
+  if (err.status && retryableStatus.includes(err.status)) return true;
+  if (err.message?.includes('rate limit')) return true;
+  if (err.message?.includes('timeout')) return true;
+  if (err.message?.includes('network')) return true;
+
+  return false;
+}
+
+/**
+ * Classify error type
+ * @param {Error} err - Error to classify
+ * @returns {string} - Error classification
+ */
+function classifyError(err) {
+  if (isRetryableError(err)) {
+    return 'retryable';
+  }
+  
+  if (err.code === 'ENOENT' || err.code === 'EPERM') {
+    return 'filesystem';
+  }
+  
+  if (err.message?.includes('parse') || err.message?.includes('invalid')) {
+    return 'validation';
+  }
+  
+  return 'unknown';
+}
+
+module.exports = {
+  retry,
+  isRetryableError,
+  classifyError
+};

package/bin/lib/roadmap.cjs

@@ -0,0 +1,309 @@
+/**
+ * Roadmap — Roadmap parsing and update operations
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { escapeRegex, normalizePhaseName, output, error, findPhaseInternal } = require('./core.cjs');
+const { safePlanningWriteSync } = require('./planning-write.cjs');
+
+function cmdRoadmapGetPhase(cwd, phaseNum, raw) {
+  const roadmapPath = path.join(cwd, '.planning', 'ROADMAP.md');
+
+  if (!fs.existsSync(roadmapPath)) {
+    output({ found: false, error: 'ROADMAP.md not found' }, raw, '');
+    return;
+  }
+
+  try {
+    const content = fs.readFileSync(roadmapPath, 'utf-8');
+
+    // Escape special regex chars in phase number, handle decimal
+    const escapedPhase = escapeRegex(phaseNum);
+
+    // Match "## Phase X:", "### Phase X:", or "#### Phase X:" with optional name
+    const phasePattern = new RegExp(
+      `#{2,4}\\s*Phase\\s+${escapedPhase}:\\s*([^\\n]+)`,
+      'i'
+    );
+    const headerMatch = content.match(phasePattern);
+
+    if (!headerMatch) {
+      // Fallback: check if phase exists in summary list but missing detail section
+      const checklistPattern = new RegExp(
+        `-\\s*\\[[ x]\\]\\s*\\*\\*Phase\\s+${escapedPhase}:\\s*([^*]+)\\*\\*`,
+        'i'
+      );
+      const checklistMatch = content.match(checklistPattern);
+
+      if (checklistMatch) {
+        // Phase exists in summary but missing detail section - malformed ROADMAP
+        output({
+          found: false,
+          phase_number: phaseNum,
+          phase_name: checklistMatch[1].trim(),
+          error: 'malformed_roadmap',
+          message: `Phase ${phaseNum} exists in summary list but missing "### Phase ${phaseNum}:" detail section. ROADMAP.md needs both formats.`
+        }, raw, '');
+        return;
+      }
+
+      output({ found: false, phase_number: phaseNum }, raw, '');
+      return;
+    }
+
+    const phaseName = headerMatch[1].trim();
+    const headerIndex = headerMatch.index;
+
+    // Find the end of this section (next ## or ### phase header, or end of file)
+    const restOfContent = content.slice(headerIndex);
+    const nextHeaderMatch = restOfContent.match(/\n#{2,4}\s+Phase\s+\d/i);
+    const sectionEnd = nextHeaderMatch
+      ? headerIndex + nextHeaderMatch.index
+      : content.length;
+
+    const section = content.slice(headerIndex, sectionEnd).trim();
+
+    // Extract goal if present (supports both **Goal:** and **Goal**: formats)
+    const goalMatch = section.match(/\*\*Goal(?::\*\*|\*\*:)\s*([^\n]+)/i);
+    const goal = goalMatch ? goalMatch[1].trim() : null;
+
+    // Extract success criteria as structured array
+    const criteriaMatch = section.match(/\*\*Success Criteria\*\*[^\n]*:\s*\n((?:\s*\d+\.\s*[^\n]+\n?)+)/i);
+    const success_criteria = criteriaMatch
+      ? criteriaMatch[1].trim().split('\n').map(line => line.replace(/^\s*\d+\.\s*/, '').trim()).filter(Boolean)
+      : [];
+
+    output(
+      {
+        found: true,
+        phase_number: phaseNum,
+        phase_name: phaseName,
+        goal,
+        success_criteria,
+        section,
+      },
+      raw,
+      section
+    );
+  } catch (e) {
+    error('Failed to read ROADMAP.md: ' + e.message);
+  }
+}
+
+function cmdRoadmapAnalyze(cwd, raw) {
+  const roadmapPath = path.join(cwd, '.planning', 'ROADMAP.md');
+
+  if (!fs.existsSync(roadmapPath)) {
+    output({ error: 'ROADMAP.md not found', milestones: [], phases: [], current_phase: null }, raw);
+    return;
+  }
+
+  const content = fs.readFileSync(roadmapPath, 'utf-8');
+  const phasesDir = path.join(cwd, '.planning', 'phases');
+
+  // Extract all phase headings: ## Phase N: Name or ### Phase N: Name
+  const phasePattern = /#{2,4}\s*Phase\s+(\d+[A-Z]?(?:\.\d+)*)\s*:\s*([^\n]+)/gi;
+  const phases = [];
+  let match;
+
+  while ((match = phasePattern.exec(content)) !== null) {
+    const phaseNum = match[1];
+    const phaseName = match[2].replace(/\(INSERTED\)/i, '').trim();
+
+    // Extract goal from the section
+    const sectionStart = match.index;
+    const restOfContent = content.slice(sectionStart);
+    const nextHeader = restOfContent.match(/\n#{2,4}\s+Phase\s+\d/i);
+    const sectionEnd = nextHeader ? sectionStart + nextHeader.index : content.length;
+    const section = content.slice(sectionStart, sectionEnd);
+
+    const goalMatch = section.match(/\*\*Goal(?::\*\*|\*\*:)\s*([^\n]+)/i);
+    const goal = goalMatch ? goalMatch[1].trim() : null;
+
+    const dependsMatch = section.match(/\*\*Depends on(?::\*\*|\*\*:)\s*([^\n]+)/i);
+    const depends_on = dependsMatch ? dependsMatch[1].trim() : null;
+
+    // Check completion on disk
+    const normalized = normalizePhaseName(phaseNum);
+    let diskStatus = 'no_directory';
+    let planCount = 0;
+    let summaryCount = 0;
+    let hasContext = false;
+    let hasResearch = false;
+
+    try {
+      const entries = fs.readdirSync(phasesDir, { withFileTypes: true });
+      const dirs = entries.filter(e => e.isDirectory()).map(e => e.name);
+      const dirMatch = dirs.find(d => d.startsWith(normalized + '-') || d === normalized);
+
+      if (dirMatch) {
+        const phaseFiles = fs.readdirSync(path.join(phasesDir, dirMatch));
+        planCount = phaseFiles.filter(f => f.endsWith('-PLAN.md') || f === 'PLAN.md').length;
+        summaryCount = phaseFiles.filter(f => f.endsWith('-SUMMARY.md') || f === 'SUMMARY.md').length;
+        hasContext = phaseFiles.some(f => f.endsWith('-CONTEXT.md') || f === 'CONTEXT.md');
+        hasResearch = phaseFiles.some(f => f.endsWith('-RESEARCH.md') || f === 'RESEARCH.md');
+
+        if (summaryCount >= planCount && planCount > 0) diskStatus = 'complete';
+        else if (summaryCount > 0) diskStatus = 'partial';
+        else if (planCount > 0) diskStatus = 'planned';
+        else if (hasResearch) diskStatus = 'researched';
+        else if (hasContext) diskStatus = 'discussed';
+        else diskStatus = 'empty';
+      }
+    } catch (err) {
+      const { defaultLogger: logger } = require('./logger.cjs');
+      logger.warn('Failed to scan phase directory', { phase: phaseNum, dirMatch, error: err.message });
+    }
+
+    // Check ROADMAP checkbox status
+    const checkboxPattern = new RegExp(`-\\s*\\[(x| )\\]\\s*.*Phase\\s+${escapeRegex(phaseNum)}`, 'i');
+    const checkboxMatch = content.match(checkboxPattern);
+    const roadmapComplete = checkboxMatch ? checkboxMatch[1] === 'x' : false;
+
+    // If roadmap marks phase complete, trust that over disk file structure.
+    // Phases completed before EZ tracking (or via external tools) may lack
+    // the standard PLAN/SUMMARY pairs but are still done.
+    if (roadmapComplete && diskStatus !== 'complete') {
+      diskStatus = 'complete';
+    }
+
+    phases.push({
+      number: phaseNum,
+      name: phaseName,
+      goal,
+      depends_on,
+      plan_count: planCount,
+      summary_count: summaryCount,
+      has_context: hasContext,
+      has_research: hasResearch,
+      disk_status: diskStatus,
+      roadmap_complete: roadmapComplete,
+    });
+  }
+
+  // Extract milestone info
+  const milestones = [];
+  const milestonePattern = /##\s*(.*v(\d+\.\d+)[^(\n]*)/gi;
+  let mMatch;
+  while ((mMatch = milestonePattern.exec(content)) !== null) {
+    milestones.push({
+      heading: mMatch[1].trim(),
+      version: 'v' + mMatch[2],
+    });
+  }
+
+  // Find current and next phase
+  const currentPhase = phases.find(p => p.disk_status === 'planned' || p.disk_status === 'partial') || null;
+  const nextPhase = phases.find(p => p.disk_status === 'empty' || p.disk_status === 'no_directory' || p.disk_status === 'discussed' || p.disk_status === 'researched') || null;
+
+  // Aggregated stats
+  const totalPlans = phases.reduce((sum, p) => sum + p.plan_count, 0);
+  const totalSummaries = phases.reduce((sum, p) => sum + p.summary_count, 0);
+  const completedPhases = phases.filter(p => p.disk_status === 'complete').length;
+
+  // Detect phases in summary list without detail sections (malformed ROADMAP)
+  const checklistPattern = /-\s*\[[ x]\]\s*\*\*Phase\s+(\d+[A-Z]?(?:\.\d+)*)/gi;
+  const checklistPhases = new Set();
+  let checklistMatch;
+  while ((checklistMatch = checklistPattern.exec(content)) !== null) {
+    checklistPhases.add(checklistMatch[1]);
+  }
+  const detailPhases = new Set(phases.map(p => p.number));
+  const missingDetails = [...checklistPhases].filter(p => !detailPhases.has(p));
+
+  const result = {
+    milestones,
+    phases,
+    phase_count: phases.length,
+    completed_phases: completedPhases,
+    total_plans: totalPlans,
+    total_summaries: totalSummaries,
+    progress_percent: totalPlans > 0 ? Math.min(100, Math.round((totalSummaries / totalPlans) * 100)) : 0,
+    current_phase: currentPhase ? currentPhase.number : null,
+    next_phase: nextPhase ? nextPhase.number : null,
+    missing_phase_details: missingDetails.length > 0 ? missingDetails : null,
+  };
+
+  output(result, raw);
+}
+
+function cmdRoadmapUpdatePlanProgress(cwd, phaseNum, raw) {
+  if (!phaseNum) {
+    error('phase number required for roadmap update-plan-progress');
+  }
+
+  const roadmapPath = path.join(cwd, '.planning', 'ROADMAP.md');
+
+  const phaseInfo = findPhaseInternal(cwd, phaseNum);
+  if (!phaseInfo) {
+    error(`Phase ${phaseNum} not found`);
+  }
+
+  const planCount = phaseInfo.plans.length;
+  const summaryCount = phaseInfo.summaries.length;
+
+  if (planCount === 0) {
+    output({ updated: false, reason: 'No plans found', plan_count: 0, summary_count: 0 }, raw, 'no plans');
+    return;
+  }
+
+  const isComplete = summaryCount >= planCount;
+  const status = isComplete ? 'Complete' : summaryCount > 0 ? 'In Progress' : 'Planned';
+  const today = new Date().toISOString().split('T')[0];
+
+  if (!fs.existsSync(roadmapPath)) {
+    output({ updated: false, reason: 'ROADMAP.md not found', plan_count: planCount, summary_count: summaryCount }, raw, 'no roadmap');
+    return;
+  }
+
+  let roadmapContent = fs.readFileSync(roadmapPath, 'utf-8');
+  const phaseEscaped = escapeRegex(phaseNum);
+
+  // Progress table row: update Plans column (summaries/plans) and Status column
+  const tablePattern = new RegExp(
+    `(\\|\\s*${phaseEscaped}\\.?\\s[^|]*\\|)[^|]*(\\|)\\s*[^|]*(\\|)\\s*[^|]*(\\|)`,
+    'i'
+  );
+  const dateField = isComplete ? ` ${today} ` : '  ';
+  roadmapContent = roadmapContent.replace(
+    tablePattern,
+    `$1 ${summaryCount}/${planCount} $2 ${status.padEnd(11)}$3${dateField}$4`
+  );
+
+  // Update plan count in phase detail section
+  const planCountPattern = new RegExp(
+    `(#{2,4}\\s*Phase\\s+${phaseEscaped}[\\s\\S]*?\\*\\*Plans:\\*\\*\\s*)[^\\n]+`,
+    'i'
+  );
+  const planCountText = isComplete
+    ? `${summaryCount}/${planCount} plans complete`
+    : `${summaryCount}/${planCount} plans executed`;
+  roadmapContent = roadmapContent.replace(planCountPattern, `$1${planCountText}`);
+
+  // If complete: check checkbox
+  if (isComplete) {
+    const checkboxPattern = new RegExp(
+      `(-\\s*\\[)[ ](\\]\\s*.*Phase\\s+${phaseEscaped}[:\\s][^\\n]*)`,
+      'i'
+    );
+    roadmapContent = roadmapContent.replace(checkboxPattern, `$1x$2 (completed ${today})`);
+  }
+
+  safePlanningWriteSync(roadmapPath, roadmapContent);
+
+  output({
+    updated: true,
+    phase: phaseNum,
+    plan_count: planCount,
+    summary_count: summaryCount,
+    status,
+    complete: isComplete,
+  }, raw, `${summaryCount}/${planCount} ${status}`);
+}
+
+module.exports = {
+  cmdRoadmapGetPhase,
+  cmdRoadmapAnalyze,
+  cmdRoadmapUpdatePlanProgress,
+};

package/bin/lib/safe-exec.cjs

@@ -0,0 +1,173 @@
+#!/usr/bin/env node
+
+/**
+ * EZ Safe Exec — Secure command execution with allowlist and validation
+ * 
+ * Prevents command injection by:
+ * - Using execFile instead of execSync with string concatenation
+ * - Validating commands against allowlist
+ * - Blocking dangerous shell metacharacters in arguments
+ * - Logging all commands for audit
+ * 
+ * Usage:
+ *   const { safeExec, safeExecJSON } = require('./safe-exec.cjs');
+ *   const result = await safeExec('git', ['status']);
+ */
+
+const { execFile } = require('child_process');
+const { promisify } = require('util');
+const execFileAsync = promisify(execFile);
+const Logger = require('./logger.cjs');
+const logger = new Logger();
+
+// Allowlist of safe commands (expanded for common development operations)
+const ALLOWED_COMMANDS = new Set([
+  // Version control
+  'git',
+  // Node.js ecosystem
+  'node', 'npm', 'npx', 'yarn', 'pnpm',
+  // File operations
+  'find', 'grep', 'head', 'tail', 'wc', 'cat', 'ls', 'dir', 'pwd',
+  // Directory operations
+  'mkdir', 'cp', 'mv', 'rm', 'touch', 'chmod', 'chown',
+  // Archive operations
+  'tar', 'zip', 'unzip', 'gzip', 'gunzip',
+  // Text processing
+  'diff', 'patch', 'sort', 'uniq', 'cut', 'tr', 'sed', 'awk',
+  // JSON processing
+  'jq',
+  // System info
+  'type', 'where', 'which', 'uname', 'whoami', 'hostname',
+  // Network (read-only)
+  'curl', 'wget',
+  // Testing
+  'vitest', 'jest', 'mocha', 'pytest',
+  // Build tools
+  'make', 'cmake',
+  // Containerization (read-only operations)
+  'docker', 'docker-compose',
+  // Database CLI (read-only operations)
+  'psql', 'mysql', 'sqlite3',
+  // CD
+  'cd'
+]);
+
+// Dangerous shell metacharacters that could enable injection
+const DANGEROUS_PATTERN = /[;&|`$(){}\\<>]/;
+
+// Path traversal patterns (Unix and Windows)
+const PATH_TRAVERSAL_PATTERN = /\.\.[/\\]/;
+
+// Null byte injection pattern
+const NULL_BYTE_PATTERN = /\0/;
+
+// Hidden file access pattern (potential security risk)
+const HIDDEN_FILE_PATTERN = /\/\.[^/]/;
+
+/**
+ * Validate command is in allowlist
+ * @param {string} cmd - Command to validate
+ * @throws {Error} If command not allowed
+ */
+function validateCommand(cmd) {
+  const baseCmd = cmd.split(' ')[0].toLowerCase();
+  if (!ALLOWED_COMMANDS.has(baseCmd)) {
+    throw new Error(`Command not allowed: ${cmd}. Allowed: ${Array.from(ALLOWED_COMMANDS).join(', ')}`);
+  }
+}
+
+/**
+ * Validate arguments don't contain injection patterns
+ * @param {string[]} args - Arguments to validate
+ * @throws {Error} If dangerous pattern found
+ */
+function validateArgs(args) {
+  for (const arg of args) {
+    // Check for shell injection patterns
+    if (DANGEROUS_PATTERN.test(arg)) {
+      throw new Error(`Dangerous argument rejected (shell metacharacter): ${arg}`);
+    }
+    
+    // Check for path traversal
+    if (PATH_TRAVERSAL_PATTERN.test(arg)) {
+      throw new Error(`Dangerous argument rejected (path traversal): ${arg}`);
+    }
+    
+    // Check for null byte injection
+    if (NULL_BYTE_PATTERN.test(arg)) {
+      throw new Error(`Dangerous argument rejected (null byte injection): ${arg}`);
+    }
+  }
+}
+
+/**
+ * Execute command safely with validation and logging
+ * @param {string} cmd - Command to execute
+ * @param {string[]} args - Command arguments
+ * @param {Object} options - Execution options
+ * @returns {Promise<string>} - Command stdout
+ */
+async function safeExec(cmd, args = [], options = {}) {
+  const { timeout = 30000, log = true, maxBuffer = 1 * 1024 * 1024 } = options;
+
+  // Validate command and arguments
+  validateCommand(cmd);
+  validateArgs(args);
+
+  const startTime = Date.now();
+
+  try {
+    if (log) {
+      logger.info('Executing command', {
+        cmd,
+        args,
+        timestamp: new Date().toISOString()
+      });
+    }
+
+    const result = await execFileAsync(cmd, args, {
+      timeout,
+      maxBuffer // Default 1MB, configurable per command type
+    });
+
+    const duration = Date.now() - startTime;
+    if (log) {
+      logger.debug('Command completed', {
+        cmd,
+        duration,
+        stdout_length: result.stdout?.length || 0
+      });
+    }
+
+    return result.stdout.trim();
+  } catch (err) {
+    const duration = Date.now() - startTime;
+    logger.error('Command failed', {
+      cmd,
+      args,
+      error: err.message,
+      duration,
+      code: err.code,
+      signal: err.signal
+    });
+    throw err;
+  }
+}
+
+/**
+ * Execute command and return JSON parsed output
+ * @param {string} cmd - Command to execute
+ * @param {string[]} args - Command arguments
+ * @returns {Promise<Object>} - Parsed JSON output
+ */
+async function safeExecJSON(cmd, args = []) {
+  const output = await safeExec(cmd, args);
+  try {
+    return JSON.parse(output);
+  } catch (err) {
+    logger.error('Failed to parse JSON output', { cmd, output });
+    throw new Error(`Invalid JSON from ${cmd}: ${err.message}`);
+  }
+}
+
+module.exports = { safeExec, safeExecJSON, ALLOWED_COMMANDS };