agileflow 3.4.2 → 4.0.0-alpha.1

package/lib/git-operations.js

@@ -1,266 +0,0 @@
-/**
- * git-operations.js - Git command execution and phase detection
- *
- * Provides cached git operations and session phase detection for Kanban visualization.
- */
-
-const { spawnSync, spawn } = require('child_process');
-const fs = require('fs');
-
-const { getProjectRoot } = require('./paths');
-const { git } = require('./process-executor');
-
-const ROOT = getProjectRoot();
-
-// Git command cache (10 second TTL to avoid stale data)
-const gitCache = {
-  data: new Map(),
-  ttlMs: 10000,
-  get(key) {
-    const entry = this.data.get(key);
-    if (entry && Date.now() - entry.timestamp < this.ttlMs) {
-      return entry.value;
-    }
-    this.data.delete(key);
-    return null;
-  },
-  set(key, value) {
-    this.data.set(key, { value, timestamp: Date.now() });
-  },
-  invalidate(key) {
-    if (key) {
-      this.data.delete(key);
-    } else {
-      this.data.clear();
-    }
-  },
-};
-
-/**
- * Execute git command asynchronously (Promise-based, non-blocking)
- * @param {string[]} args - Git command arguments
- * @param {string} cwd - Working directory
- * @returns {Promise<{stdout: string, stderr: string, code: number}>}
- */
-function execGitAsync(args, cwd) {
-  return new Promise((resolve, reject) => {
-    const proc = spawn('git', args, {
-      cwd,
-      encoding: 'utf8',
-      stdio: ['pipe', 'pipe', 'pipe'],
-    });
-
-    let stdout = '';
-    let stderr = '';
-
-    proc.stdout.on('data', data => {
-      stdout += data;
-    });
-    proc.stderr.on('data', data => {
-      stderr += data;
-    });
-
-    proc.on('error', err => {
-      reject(err);
-    });
-
-    proc.on('close', code => {
-      resolve({ stdout: stdout.trim(), stderr: stderr.trim(), code });
-    });
-  });
-}
-
-/**
- * Get current git branch (cached for performance)
- * @param {string} [cwd=ROOT] - Working directory
- * @returns {string} Current branch name
- */
-function getCurrentBranch(cwd = ROOT) {
-  const cacheKey = `branch:${cwd}`;
-  const cached = gitCache.get(cacheKey);
-  if (cached !== null) return cached;
-
-  const result = git(['branch', '--show-current'], { cwd, fallback: 'unknown' });
-  const branch = result.data;
-  gitCache.set(cacheKey, branch);
-  return branch;
-}
-
-/**
- * Get main branch name (main or master) - cached since it rarely changes
- * @param {string} [cwd=ROOT] - Working directory
- * @returns {string} Main branch name ('main' or 'master')
- */
-function getMainBranch(cwd = ROOT) {
-  const cacheKey = `mainBranch:${cwd}`;
-  const cached = gitCache.get(cacheKey);
-  if (cached !== null) return cached;
-
-  const checkMain = spawnSync('git', ['show-ref', '--verify', '--quiet', 'refs/heads/main'], {
-    cwd,
-    encoding: 'utf8',
-  });
-
-  if (checkMain.status === 0) {
-    gitCache.set(cacheKey, 'main');
-    return 'main';
-  }
-
-  const checkMaster = spawnSync('git', ['show-ref', '--verify', '--quiet', 'refs/heads/master'], {
-    cwd,
-    encoding: 'utf8',
-  });
-
-  if (checkMaster.status === 0) {
-    gitCache.set(cacheKey, 'master');
-    return 'master';
-  }
-
-  gitCache.set(cacheKey, 'main');
-  return 'main'; // Default fallback
-}
-
-// Session phases for Kanban-style visualization
-const SESSION_PHASES = {
-  TODO: 'todo',
-  CODING: 'coding',
-  REVIEW: 'review',
-  MERGED: 'merged',
-};
-
-/**
- * Determine phase from git state (commits and status)
- * @param {number} commits - Number of commits ahead of main
- * @param {boolean} hasUncommittedChanges - Whether there are uncommitted changes
- * @returns {string} Phase constant
- */
-function determinePhaseFromGitState(commits, hasUncommittedChanges) {
-  if (commits === 0) {
-    return SESSION_PHASES.TODO;
-  }
-  // Has commits - check for uncommitted changes
-  return hasUncommittedChanges ? SESSION_PHASES.CODING : SESSION_PHASES.REVIEW;
-}
-
-/**
- * Check early-exit conditions for session phase
- * Returns phase if early exit, null if git state check needed
- * @param {Object} session - Session object
- * @returns {string|null} Phase if determinable without git, null otherwise
- */
-function getSessionPhaseEarlyExit(session) {
-  if (session.merged_at || session.is_main) {
-    return SESSION_PHASES.MERGED;
-  }
-  if (!fs.existsSync(session.path)) {
-    return SESSION_PHASES.TODO;
-  }
-  return null;
-}
-
-/**
- * Get session phase synchronously (with caching)
- * @param {Object} session - Session object
- * @returns {string} Phase constant
- */
-function getSessionPhase(session) {
-  // Early exit checks
-  const earlyExit = getSessionPhaseEarlyExit(session);
-  if (earlyExit) return earlyExit;
-
-  const sessionPath = session.path;
-  const cacheKey = `phase:${sessionPath}`;
-  const cached = gitCache.get(cacheKey);
-  if (cached !== null) return cached;
-
-  try {
-    const mainBranch = getMainBranch(sessionPath);
-    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);
-    return phase;
-  } catch (e) {
-    return SESSION_PHASES.CODING;
-  }
-}
-
-/**
- * Detect session phase asynchronously (non-blocking git calls)
- * @param {Object} session - Session object
- * @returns {Promise<string>} Phase constant
- */
-async function getSessionPhaseAsync(session) {
-  // Early exit checks (shared with sync version)
-  const earlyExit = getSessionPhaseEarlyExit(session);
-  if (earlyExit) return earlyExit;
-
-  const sessionPath = session.path;
-  const cacheKey = `phase:${sessionPath}`;
-  const cached = gitCache.get(cacheKey);
-  if (cached !== null) return cached;
-
-  try {
-    const mainBranch = getMainBranch(sessionPath);
-    const commitResult = await execGitAsync(
-      ['rev-list', '--count', `${mainBranch}..HEAD`],
-      sessionPath
-    );
-    const commits = parseInt(commitResult.stdout || '0', 10);
-
-    const statusResult = await execGitAsync(['status', '--porcelain'], sessionPath);
-
-    const phase = determinePhaseFromGitState(commits, statusResult.stdout !== '');
-    gitCache.set(cacheKey, phase);
-    return phase;
-  } catch (e) {
-    return SESSION_PHASES.CODING;
-  }
-}
-
-/**
- * Get phases for multiple sessions in parallel (Promise.all batching)
- * @param {Object[]} sessions - Array of session objects
- * @returns {Promise<Object[]>} Sessions with phase property added
- */
-async function getSessionPhasesAsync(sessions) {
-  const phasePromises = sessions.map(async session => {
-    const phase = await getSessionPhaseAsync(session);
-    return { session, phase };
-  });
-
-  const results = await Promise.all(phasePromises);
-
-  // Return as array with phase included
-  return results.map(({ session, phase }) => ({
-    ...session,
-    phase,
-  }));
-}
-
-module.exports = {
-  // Git cache
-  gitCache,
-  // Git command execution
-  execGitAsync,
-  // Branch operations
-  getCurrentBranch,
-  getMainBranch,
-  // Phase detection
-  SESSION_PHASES,
-  determinePhaseFromGitState,
-  getSessionPhaseEarlyExit,
-  getSessionPhase,
-  getSessionPhaseAsync,
-  getSessionPhasesAsync,
-};

package/lib/lazy-require.js

@@ -1,59 +0,0 @@
-/**
- * lazy-require.js - Reusable Lazy-Loading Utility
- *
- * AgileFlow scripts are copied to user projects (.agileflow/scripts/) and run
- * as hooks. When these scripts eagerly require() npm dependencies at module
- * load time, they crash if the dependency isn't resolvable from the user's
- * project directory. This utility standardizes the lazy-loading pattern used
- * ad-hoc in yaml-utils.js and dashboard-server.js.
- *
- * Usage:
- *   const { lazyRequire } = require('./lazy-require');
- *
- *   // Returns a getter function; require() is deferred until first call
- *   const getChalk = lazyRequire('chalk');
- *
- *   // With fallback resolution paths
- *   const getYaml = lazyRequire('js-yaml',
- *     path.join(__dirname, '..', 'node_modules', 'js-yaml')
- *   );
- *
- *   // Later, when actually needed:
- *   const chalk = getChalk();
- */
-
-'use strict';
-
-/**
- * Create a lazy-loading getter for an npm module.
- *
- * The returned function defers require() until first invocation, then caches
- * the result. Multiple resolution paths are tried in order, so the module can
- * be found from the user's node_modules, AgileFlow's own node_modules, or any
- * other location.
- *
- * @param {string} name - Primary module name (passed to require())
- * @param {...string} fallbackPaths - Additional paths to try if primary fails
- * @returns {function(): any} Getter that returns the loaded module
- */
-function lazyRequire(name, ...fallbackPaths) {
-  let cached = null;
-  return () => {
-    if (cached) return cached;
-    const paths = [name, ...fallbackPaths];
-    for (const p of paths) {
-      try {
-        cached = require(p);
-        return cached;
-      } catch (_e) {
-        // Continue to next path
-      }
-    }
-    throw new Error(
-      `${name} not found. Run: npm install ${name}\n` +
-        'Or reinstall AgileFlow: npx agileflow setup --force'
-    );
-  };
-}
-
-module.exports = { lazyRequire };

package/lib/lock-file.js

@@ -1,144 +0,0 @@
-/**
- * lock-file.js - Lock file operations for session management
- *
- * Manages session lock files for PID-based liveness detection.
- * Lock files use a simple key-value format: pid=12345\nstarted=1706825600
- */
-
-const fs = require('fs');
-const path = require('path');
-
-/**
- * Parse lock file content into an object
- * @param {string} content - Raw lock file content
- * @returns {Object} Parsed key-value pairs
- */
-function parseLockContent(content) {
-  const lock = {};
-  content.split('\n').forEach(line => {
-    const [key, value] = line.split('=');
-    if (key && value) {
-      lock[key.trim()] = value.trim();
-    }
-  });
-  return lock;
-}
-
-/**
- * Get lock file path for a session
- * @param {string} sessionsDir - Sessions directory path
- * @param {string} sessionId - Session identifier
- * @returns {string} Full path to lock file
- */
-function getLockPath(sessionsDir, sessionId) {
-  return path.join(sessionsDir, `${sessionId}.lock`);
-}
-
-/**
- * Read lock file synchronously
- * @param {string} sessionsDir - Sessions directory path
- * @param {string} sessionId - Session identifier
- * @returns {Object|null} Parsed lock data or null if not found
- */
-function readLock(sessionsDir, sessionId) {
-  const lockPath = getLockPath(sessionsDir, sessionId);
-  if (!fs.existsSync(lockPath)) return null;
-
-  try {
-    const content = fs.readFileSync(lockPath, 'utf8');
-    return parseLockContent(content);
-  } catch (e) {
-    return null;
-  }
-}
-
-/**
- * Read lock file asynchronously
- * @param {string} sessionsDir - Sessions directory path
- * @param {string} sessionId - Session identifier
- * @returns {Promise<Object|null>} Parsed lock data or null if not found
- */
-async function readLockAsync(sessionsDir, sessionId) {
-  const lockPath = getLockPath(sessionsDir, sessionId);
-  try {
-    const content = await fs.promises.readFile(lockPath, 'utf8');
-    return parseLockContent(content);
-  } catch (e) {
-    return null;
-  }
-}
-
-/**
- * Write lock file for a session
- * @param {string} sessionsDir - Sessions directory path
- * @param {string} sessionId - Session identifier
- * @param {number} pid - Process ID to record
- */
-function writeLock(sessionsDir, sessionId, pid) {
-  const lockPath = getLockPath(sessionsDir, sessionId);
-  const content = `pid=${pid}\nstarted=${Math.floor(Date.now() / 1000)}\n`;
-  fs.writeFileSync(lockPath, content);
-}
-
-/**
- * Remove lock file for a session
- * @param {string} sessionsDir - Sessions directory path
- * @param {string} sessionId - Session identifier
- */
-function removeLock(sessionsDir, sessionId) {
-  const lockPath = getLockPath(sessionsDir, sessionId);
-  if (fs.existsSync(lockPath)) {
-    fs.unlinkSync(lockPath);
-  }
-}
-
-/**
- * Check if a PID is alive
- * @param {number} pid - Process ID to check
- * @returns {boolean} True if process is alive
- */
-function isPidAlive(pid) {
-  if (!pid) return false;
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch (e) {
-    return false;
-  }
-}
-
-/**
- * Check if session is active (has lock with alive PID)
- * @param {string} sessionsDir - Sessions directory path
- * @param {string} sessionId - Session identifier
- * @returns {boolean} True if session is active
- */
-function isSessionActive(sessionsDir, sessionId) {
-  const lock = readLock(sessionsDir, sessionId);
-  if (!lock || !lock.pid) return false;
-  return isPidAlive(parseInt(lock.pid, 10));
-}
-
-/**
- * Check if session is active asynchronously
- * @param {string} sessionsDir - Sessions directory path
- * @param {string} sessionId - Session identifier
- * @returns {Promise<boolean>} True if session is active
- */
-async function isSessionActiveAsync(sessionsDir, sessionId) {
-  const lock = await readLockAsync(sessionsDir, sessionId);
-  if (!lock || !lock.pid) return false;
-  return isPidAlive(parseInt(lock.pid, 10));
-}
-
-module.exports = {
-  parseLockContent,
-  getLockPath,
-  readLock,
-  readLockAsync,
-  writeLock,
-  removeLock,
-  isPidAlive,
-  isSessionActive,
-  isSessionActiveAsync,
-};

package/lib/logger.js

@@ -1,106 +0,0 @@
-/**
- * logger.js - Centralized logger with level control
- *
- * Provides structured logging with configurable levels, colored output,
- * and automatic secret redaction on debug messages.
- *
- * Log Levels (ordered): debug < info < warn < error < silent
- *
- * Environment Variables:
- *   AGILEFLOW_LOG_LEVEL - Set minimum level (debug/info/warn/error/silent). Default: info
- *   AGILEFLOW_VERBOSE   - When 1/true, sets level to debug (shorthand)
- *   AGILEFLOW_DEBUG     - When 1, sets level to debug (backward compat with errors.js)
- *
- * Usage:
- *   const { createLogger } = require('../lib/logger');
- *   const log = createLogger('welcome');
- *
- *   log.debug('Loading model...');   // [DEBUG] [welcome] Loading model...
- *   log.info('Server started');      // [INFO] [welcome] Server started
- *   log.warn('Deprecated API');      // [WARN] [welcome] Deprecated API
- *   log.error('Connection failed');  // [ERROR] [welcome] Connection failed
- */
-
-const { c } = require('./colors');
-const { sanitizeDebugOutput } = require('./errors');
-
-const LEVELS = {
-  debug: 0,
-  info: 1,
-  warn: 2,
-  error: 3,
-  silent: 4,
-};
-
-/**
- * Resolve the effective log level from environment variables.
- * Priority: AGILEFLOW_LOG_LEVEL > AGILEFLOW_VERBOSE > AGILEFLOW_DEBUG > default (info)
- */
-function resolveLevel() {
-  const explicit = process.env.AGILEFLOW_LOG_LEVEL;
-  if (explicit && LEVELS[explicit] !== undefined) {
-    return explicit;
-  }
-
-  const verbose = process.env.AGILEFLOW_VERBOSE;
-  if (verbose === '1' || verbose === 'true') {
-    return 'debug';
-  }
-
-  if (process.env.AGILEFLOW_DEBUG === '1') {
-    return 'debug';
-  }
-
-  return 'info';
-}
-
-/**
- * Create a logger instance with an optional module name.
- *
- * @param {string} [moduleName] - Module name for log prefix (e.g. 'welcome', 'context-loader')
- * @param {object} [options] - Logger options
- * @param {string} [options.level] - Override log level (ignores env vars)
- * @param {boolean} [options.timestamps] - Include ISO timestamps in output (default: false)
- * @returns {{ debug: Function, info: Function, warn: Function, error: Function }}
- */
-function createLogger(moduleName, options = {}) {
-  const levelName = options.level || resolveLevel();
-  const minLevel = LEVELS[levelName] !== undefined ? LEVELS[levelName] : LEVELS.info;
-  const timestamps = options.timestamps || false;
-
-  function formatPrefix(label, color) {
-    const ts = timestamps ? `${new Date().toISOString()} ` : '';
-    const mod = moduleName ? ` ${c.dim}[${moduleName}]${c.reset}` : '';
-    return `${ts}${color}[${label}]${c.reset}${mod}`;
-  }
-
-  return {
-    debug(...args) {
-      if (minLevel > LEVELS.debug) return;
-      const prefix = formatPrefix('DEBUG', c.dim);
-      // Sanitize all args to prevent secret leakage in debug output
-      const sanitized = args.map(arg => sanitizeDebugOutput(arg).sanitized);
-      process.stderr.write(`${prefix} ${sanitized.join(' ')}\n`);
-    },
-
-    info(...args) {
-      if (minLevel > LEVELS.info) return;
-      const prefix = formatPrefix('INFO', c.cyan);
-      process.stderr.write(`${prefix} ${args.join(' ')}\n`);
-    },
-
-    warn(...args) {
-      if (minLevel > LEVELS.warn) return;
-      const prefix = formatPrefix('WARN', c.yellow);
-      process.stderr.write(`${prefix} ${args.join(' ')}\n`);
-    },
-
-    error(...args) {
-      if (minLevel > LEVELS.error) return;
-      const prefix = formatPrefix('ERROR', c.red);
-      process.stderr.write(`${prefix} ${args.join(' ')}\n`);
-    },
-  };
-}
-
-module.exports = { createLogger, LEVELS };