agileflow 2.99.7 → 3.0.0

package/lib/errors.js

@@ -538,6 +538,23 @@ function wrapSafeAsync(fn, operationName = 'operation', options = {}) {
   };
 }
 
+/**
+ * Execute a function and return its result, or undefined if it throws.
+ * Logs suppressed errors when AGILEFLOW_DEBUG=1.
+ *
+ * @param {Function} fn - Function to execute
+ * @param {string} [label] - Optional label for debug logging
+ * @returns {*} Function result on success, undefined on error
+ */
+function tryOptional(fn, label) {
+  try {
+    return fn();
+  } catch (err) {
+    debugLog('tryOptional', { label: label || 'anonymous', error: err.message });
+    return undefined;
+  }
+}
+
 /**
  * Safely parse JSON string with optional field validation
  * @param {string} content - JSON string to parse
@@ -646,6 +663,7 @@ module.exports = {
   // Utility wrappers
   wrapSafe,
   wrapSafeAsync,
+  tryOptional,
 
   // Debug helper
   debugLog,

package/lib/file-cache.js

@@ -153,7 +153,7 @@ class LRUCache {
 // Global cache instance (persists across requires in same process)
 const fileCache = new LRUCache({
   maxSize: 50,
-  ttlMs: 30000, // 30 seconds
+  ttlMs: 15000, // 15 seconds
 });
 
 /**

package/lib/flag-detection.js

@@ -11,7 +11,7 @@
  */
 
 const fs = require('fs');
-const { execFileSync } = require('child_process');
+const { executeCommandSync } = require('./process-executor');
 
 /**
  * Known Claude flags that should be propagated to child sessions
@@ -218,15 +218,11 @@ function detectFromPs() {
 
       // Get command line for this PID
       let cmdline;
-      try {
-        cmdline = execFileSync('ps', ['-p', String(pid), '-o', 'args='], {
-          encoding: 'utf8',
-          stdio: ['pipe', 'pipe', 'pipe'],
-          timeout: 1000,
-        }).trim();
-      } catch {
-        break;
-      }
+      const cmdResult = executeCommandSync('ps', ['-p', String(pid), '-o', 'args='], {
+        timeout: 1000, fallback: null,
+      });
+      if (!cmdResult.ok || cmdResult.data === null) break;
+      cmdline = cmdResult.data;
 
       if (!cmdline) break;
 
@@ -242,16 +238,11 @@ function detectFromPs() {
       }
 
       // Get parent PID
-      try {
-        const ppidStr = execFileSync('ps', ['-p', String(pid), '-o', 'ppid='], {
-          encoding: 'utf8',
-          stdio: ['pipe', 'pipe', 'pipe'],
-          timeout: 1000,
-        }).trim();
-        pid = parseInt(ppidStr, 10);
-      } catch {
-        break;
-      }
+      const ppidResult = executeCommandSync('ps', ['-p', String(pid), '-o', 'ppid='], {
+        timeout: 1000, fallback: null,
+      });
+      if (!ppidResult.ok || ppidResult.data === null) break;
+      pid = parseInt(ppidResult.data, 10);
     }
   } catch (e) {
     // ps command failed - ignore

package/lib/git-operations.js

@@ -4,10 +4,11 @@
  * Provides cached git operations and session phase detection for Kanban visualization.
  */
 
-const { execFileSync, spawnSync, spawn } = require('child_process');
+const { spawnSync, spawn } = require('child_process');
 const fs = require('fs');
 
 const { getProjectRoot } = require('./paths');
+const { git } = require('./process-executor');
 
 const ROOT = getProjectRoot();
 
@@ -79,16 +80,10 @@ function getCurrentBranch(cwd = ROOT) {
   const cached = gitCache.get(cacheKey);
   if (cached !== null) return cached;
 
-  try {
-    const branch = execFileSync('git', ['branch', '--show-current'], {
-      cwd,
-      encoding: 'utf8',
-    }).trim();
-    gitCache.set(cacheKey, branch);
-    return branch;
-  } catch (e) {
-    return 'unknown';
-  }
+  const result = git(['branch', '--show-current'], { cwd, fallback: 'unknown' });
+  const branch = result.data;
+  gitCache.set(cacheKey, branch);
+  return branch;
 }
 
 /**
@@ -180,28 +175,15 @@ function getSessionPhase(session) {
 
   try {
     const mainBranch = getMainBranch(sessionPath);
-    let commitCount;
-    try {
-      commitCount = execFileSync('git', ['rev-list', '--count', `${mainBranch}..HEAD`], {
-        cwd: sessionPath,
-        encoding: 'utf8',
-        stdio: ['pipe', 'pipe', 'pipe'],
-      }).trim();
-    } catch {
-      commitCount = '0';
-    }
-    const commits = parseInt(commitCount, 10);
-
-    let status = '';
-    try {
-      status = execFileSync('git', ['status', '--porcelain'], {
-        cwd: sessionPath,
-        encoding: 'utf8',
-        stdio: ['pipe', 'pipe', 'pipe'],
-      }).trim();
-    } catch {
-      // git status failed, treat as no changes
-    }
+    const commitResult = git(['rev-list', '--count', `${mainBranch}..HEAD`], {
+      cwd: sessionPath, fallback: '0',
+    });
+    const commits = parseInt(commitResult.data, 10);
+
+    const statusResult = git(['status', '--porcelain'], {
+      cwd: sessionPath, fallback: '',
+    });
+    const status = statusResult.data;
 
     const phase = determinePhaseFromGitState(commits, status !== '');
     gitCache.set(cacheKey, phase);

package/lib/merge-operations.js

@@ -62,7 +62,9 @@ function checkMergeability(sessionId, loadRegistry) {
     }
   );
 
-  const [behind, ahead] = (aheadBehind.stdout || '0\t0').trim().split('\t').map(Number);
+  const parts = (aheadBehind.stdout || '0\t0').trim().split('\t').map(Number);
+  const behind = isNaN(parts[0]) ? 0 : parts[0];
+  const ahead = isNaN(parts[1]) ? 0 : parts[1];
 
   if (ahead === 0) {
     return {
@@ -79,46 +81,50 @@ function checkMergeability(sessionId, loadRegistry) {
 
   // Try merge --no-commit --no-ff to check for conflicts (dry run)
   const currentBranch = getCurrentBranch();
+  let checkedOutMain = false;
 
-  // Checkout main in ROOT for the test merge
-  const checkoutMain = spawnSync('git', ['checkout', mainBranch], {
-    cwd: ROOT,
-    encoding: 'utf8',
-  });
+  try {
+    // Checkout main in ROOT for the test merge
+    const checkoutMain = spawnSync('git', ['checkout', mainBranch], {
+      cwd: ROOT,
+      encoding: 'utf8',
+    });
 
-  if (checkoutMain.status !== 0) {
-    return {
-      success: false,
-      error: `Failed to checkout ${mainBranch}: ${checkoutMain.stderr}`,
-    };
-  }
+    if (checkoutMain.status !== 0) {
+      return {
+        success: false,
+        error: `Failed to checkout ${mainBranch}: ${checkoutMain.stderr}`,
+      };
+    }
+    checkedOutMain = true;
 
-  // Try the merge
-  const testMerge = spawnSync('git', ['merge', '--no-commit', '--no-ff', branchName], {
-    cwd: ROOT,
-    encoding: 'utf8',
-  });
+    // Try the merge
+    const testMerge = spawnSync('git', ['merge', '--no-commit', '--no-ff', branchName], {
+      cwd: ROOT,
+      encoding: 'utf8',
+    });
 
-  const hasConflicts = testMerge.status !== 0;
+    const hasConflicts = testMerge.status !== 0;
 
-  // Abort the test merge
-  spawnSync('git', ['merge', '--abort'], { cwd: ROOT, encoding: 'utf8' });
+    // Abort the test merge
+    spawnSync('git', ['merge', '--abort'], { cwd: ROOT, encoding: 'utf8' });
 
-  // Go back to original branch if different
-  if (currentBranch && currentBranch !== mainBranch) {
-    spawnSync('git', ['checkout', currentBranch], { cwd: ROOT, encoding: 'utf8' });
+    return {
+      success: true,
+      mergeable: !hasConflicts,
+      branchName,
+      mainBranch,
+      commitsAhead: ahead,
+      commitsBehind: behind,
+      hasConflicts,
+      conflictDetails: hasConflicts ? testMerge.stderr : null,
+    };
+  } finally {
+    // Always restore original branch
+    if (checkedOutMain && currentBranch && currentBranch !== mainBranch) {
+      spawnSync('git', ['checkout', currentBranch], { cwd: ROOT, encoding: 'utf8' });
+    }
   }
-
-  return {
-    success: true,
-    mergeable: !hasConflicts,
-    branchName,
-    mainBranch,
-    commitsAhead: ahead,
-    commitsBehind: behind,
-    hasConflicts,
-    conflictDetails: hasConflicts ? testMerge.stderr : null,
-  };
 }
 
 /**

package/lib/process-executor.js

@@ -0,0 +1,199 @@
+/**
+ * process-executor.js - Unified shell execution module (US-0310)
+ *
+ * Centralizes child_process usage with security-by-default:
+ * - Uses execFileSync/spawn (no shell) as standard pattern (US-0297)
+ * - Consistent Result pattern: { ok, data?, error?, exitCode?, stderr? }
+ * - Git shortcuts for the 76% of call sites that are git commands
+ *
+ * This module coexists with errors.js safeExec() which serves a different
+ * purpose (shell command strings via bash -c).
+ */
+
+const { execFileSync, spawn: nodeSpawn } = require('child_process');
+
+/**
+ * Execute a command synchronously without a shell.
+ * Uses execFileSync internally - shell metacharacters are literal, not interpreted.
+ *
+ * @param {string} cmd - Executable name (e.g., 'git', 'ps', 'node')
+ * @param {string[]} args - Arguments array
+ * @param {Object} [opts] - Options
+ * @param {string} [opts.cwd] - Working directory (default: process.cwd())
+ * @param {number} [opts.timeout] - Timeout in ms (default: 30000)
+ * @param {string} [opts.encoding] - Output encoding (default: 'utf8')
+ * @param {boolean} [opts.trim] - Trim stdout (default: true)
+ * @param {boolean} [opts.captureStderr] - Include stderr in result (default: false)
+ * @param {*} [opts.fallback] - Value to return as data on failure (makes errors non-fatal)
+ * @returns {{ ok: boolean, data?: string, error?: string, exitCode?: number, stderr?: string }}
+ */
+function executeCommandSync(cmd, args = [], opts = {}) {
+  const {
+    cwd = process.cwd(),
+    timeout = 30000,
+    encoding = 'utf8',
+    trim = true,
+    captureStderr = false,
+    fallback,
+  } = opts;
+
+  try {
+    const result = execFileSync(cmd, args, {
+      cwd,
+      encoding,
+      timeout,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+
+    const data = trim ? result.trim() : result;
+    return { ok: true, data };
+  } catch (err) {
+    if (fallback !== undefined) {
+      return { ok: true, data: fallback };
+    }
+
+    const exitCode = err.status || 1;
+    const stderr = err.stderr ? (trim ? err.stderr.trim() : err.stderr) : undefined;
+    const error = `Command failed: ${cmd} ${args.join(' ')} (exit ${exitCode})`;
+    const result = { ok: false, error, exitCode };
+    if (captureStderr && stderr) {
+      result.stderr = stderr;
+    }
+    return result;
+  }
+}
+
+/**
+ * Execute a command asynchronously without a shell.
+ * Uses spawn internally. The returned Promise always resolves (never rejects).
+ *
+ * @param {string} cmd - Executable name
+ * @param {string[]} args - Arguments array
+ * @param {Object} [opts] - Options (same as executeCommandSync)
+ * @returns {Promise<{ ok: boolean, data?: string, error?: string, exitCode?: number, stderr?: string }>}
+ */
+function executeCommand(cmd, args = [], opts = {}) {
+  const {
+    cwd = process.cwd(),
+    timeout = 30000,
+    trim = true,
+    captureStderr = false,
+    fallback,
+  } = opts;
+
+  return new Promise(resolve => {
+    const proc = nodeSpawn(cmd, args, {
+      cwd,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+
+    let stdout = '';
+    let stderr = '';
+    let timedOut = false;
+
+    const timer = timeout > 0 ? setTimeout(() => {
+      timedOut = true;
+      proc.kill('SIGTERM');
+    }, timeout) : null;
+
+    proc.stdout.on('data', chunk => { stdout += chunk; });
+    proc.stderr.on('data', chunk => { stderr += chunk; });
+
+    proc.on('error', err => {
+      if (timer) clearTimeout(timer);
+      if (fallback !== undefined) {
+        resolve({ ok: true, data: fallback });
+      } else {
+        resolve({ ok: false, error: `Spawn error: ${err.message}`, exitCode: null });
+      }
+    });
+
+    proc.on('close', code => {
+      if (timer) clearTimeout(timer);
+
+      if (timedOut) {
+        if (fallback !== undefined) {
+          resolve({ ok: true, data: fallback });
+        } else {
+          resolve({ ok: false, error: `Command timed out after ${timeout}ms: ${cmd}`, exitCode: null });
+        }
+        return;
+      }
+
+      if (code !== 0) {
+        if (fallback !== undefined) {
+          resolve({ ok: true, data: fallback });
+        } else {
+          const result = { ok: false, error: `Command failed: ${cmd} ${args.join(' ')} (exit ${code})`, exitCode: code };
+          if (captureStderr) {
+            result.stderr = trim ? stderr.trim() : stderr;
+          }
+          resolve(result);
+        }
+        return;
+      }
+
+      const data = trim ? stdout.trim() : stdout;
+      resolve({ ok: true, data });
+    });
+  });
+}
+
+/**
+ * Spawn a background (detached, fire-and-forget) process.
+ *
+ * @param {string} cmd - Executable name
+ * @param {string[]} args - Arguments array
+ * @param {Object} [opts] - Options
+ * @param {string} [opts.cwd] - Working directory
+ * @returns {{ ok: boolean, pid?: number, error?: string }}
+ */
+function spawnBackground(cmd, args = [], opts = {}) {
+  const { cwd = process.cwd() } = opts;
+
+  try {
+    const child = nodeSpawn(cmd, args, {
+      cwd,
+      detached: true,
+      stdio: 'ignore',
+    });
+    // Suppress unhandled error events (e.g., ENOENT for missing commands)
+    child.on('error', () => {});
+    child.unref();
+    return { ok: true, pid: child.pid };
+  } catch (err) {
+    return { ok: false, error: `Failed to spawn: ${err.message}` };
+  }
+}
+
+/**
+ * Execute a git command synchronously.
+ * Shortcut for executeCommandSync('git', args, opts).
+ *
+ * @param {string[]} args - Git arguments (e.g., ['branch', '--show-current'])
+ * @param {Object} [opts] - Same options as executeCommandSync
+ * @returns {{ ok: boolean, data?: string, error?: string, exitCode?: number, stderr?: string }}
+ */
+function git(args, opts = {}) {
+  return executeCommandSync('git', args, opts);
+}
+
+/**
+ * Execute a git command asynchronously.
+ * Shortcut for executeCommand('git', args, opts).
+ *
+ * @param {string[]} args - Git arguments
+ * @param {Object} [opts] - Same options as executeCommand
+ * @returns {Promise<{ ok: boolean, data?: string, error?: string, exitCode?: number, stderr?: string }>}
+ */
+function gitAsync(args, opts = {}) {
+  return executeCommand('git', args, opts);
+}
+
+module.exports = {
+  executeCommandSync,
+  executeCommand,
+  spawnBackground,
+  git,
+  gitAsync,
+};

package/lib/registry-cache.js

@@ -1,52 +1,30 @@
 'use strict';
 
-const fs = require('fs');
+const { MtimeCache } = require('./cache-provider');
 
 /**
  * Registry scanning cache
  * Caches directory scan results keyed by path + mtime.
  * TTL-based expiration (default 60s).
+ *
+ * Uses MtimeCache from cache-provider for unified caching with
+ * automatic mtime invalidation.
  */
 
-const _cache = new Map();
 const DEFAULT_TTL_MS = 60 * 1000;
 
+const _cache = new MtimeCache({ maxSize: 50, ttlMs: DEFAULT_TTL_MS });
+
 /**
  * Get cached scan result for a directory
  * @param {string} dirPath - Directory path
  * @param {Object} [options]
- * @param {number} [options.ttlMs] - TTL in milliseconds (default 60000)
  * @param {boolean} [options.noCache] - Bypass cache entirely
  * @returns {*|null} Cached result or null if miss/expired
  */
 function getCached(dirPath, options = {}) {
-  const { ttlMs = DEFAULT_TTL_MS, noCache = false } = options;
-
-  if (noCache) return null;
-
-  const entry = _cache.get(dirPath);
-  if (!entry) return null;
-
-  // Check TTL
-  if (Date.now() - entry.cachedAt > ttlMs) {
-    _cache.delete(dirPath);
-    return null;
-  }
-
-  // Check directory mtime hasn't changed
-  try {
-    const stat = fs.statSync(dirPath);
-    const currentMtime = stat.mtimeMs;
-    if (currentMtime !== entry.mtimeMs) {
-      _cache.delete(dirPath);
-      return null;
-    }
-  } catch {
-    _cache.delete(dirPath);
-    return null;
-  }
-
-  return entry.data;
+  if (options.noCache) return null;
+  return _cache.get(dirPath) ?? null;
 }
 
 /**
@@ -55,16 +33,7 @@ function getCached(dirPath, options = {}) {
  * @param {*} data - Data to cache
  */
 function setCached(dirPath, data) {
-  try {
-    const stat = fs.statSync(dirPath);
-    _cache.set(dirPath, {
-      data,
-      mtimeMs: stat.mtimeMs,
-      cachedAt: Date.now(),
-    });
-  } catch {
-    // Can't stat directory, don't cache
-  }
+  _cache.set(dirPath, data);
 }
 
 /**
@@ -76,26 +45,23 @@ function clearCache() {
 
 /**
  * Get cache stats
- * @returns {{ size: number, keys: string[] }}
+ * @returns {{ size: number, hits: number, misses: number, hitRate: string }}
  */
 function getCacheStats() {
-  return {
-    size: _cache.size,
-    keys: Array.from(_cache.keys()),
-  };
+  return _cache.getStats();
 }
 
 /**
  * Wrap a scan function with caching
  * @param {Function} scanFn - Function that takes (dirPath, ...args) and returns results
  * @param {Object} [options]
- * @param {number} [options.ttlMs] - TTL in ms
+ * @param {boolean} [options.noCache] - Bypass cache
  * @returns {Function} Cached version of scanFn
  */
 function withCache(scanFn, options = {}) {
   return function cachedScan(dirPath, ...args) {
     const noCache = process.argv.includes('--no-cache') || options.noCache;
-    const cached = getCached(dirPath, { ...options, noCache });
+    const cached = getCached(dirPath, { noCache });
     if (cached !== null) return cached;
 
     const result = scanFn(dirPath, ...args);