agileflow 2.91.0 → 2.92.0

package/lib/file-cache.js

@@ -336,6 +336,180 @@ function readProjectFiles(rootDir, options = {}) {
   };
 }
 
+// =============================================================================
+// Command Caching (for git and other shell commands)
+// =============================================================================
+
+const { execSync } = require('child_process');
+
+// Separate cache for command output with shorter TTL
+const commandCache = new LRUCache({
+  maxSize: 50,
+  ttlMs: 30000, // 30 seconds default
+});
+
+/**
+ * Execute and cache a shell command
+ * @param {string} command - Shell command to execute
+ * @param {Object} [options]
+ * @param {string} [options.cwd] - Working directory
+ * @param {boolean} [options.force=false] - Skip cache and force execution
+ * @param {number} [options.ttlMs] - Custom TTL for this command
+ * @param {string} [options.cacheKey] - Custom cache key (default: auto-generated)
+ * @returns {{ ok: boolean, data?: string, error?: string, cached?: boolean }}
+ */
+function execCached(command, options = {}) {
+  const { cwd = process.cwd(), force = false, ttlMs, cacheKey } = options;
+  const key = cacheKey || `cmd:${command}:${cwd}`;
+
+  // Check cache first (unless force)
+  if (!force) {
+    const cached = commandCache.get(key);
+    if (cached !== undefined) {
+      return { ok: true, data: cached, cached: true };
+    }
+  }
+
+  // Execute command
+  try {
+    const output = execSync(command, {
+      cwd,
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+      timeout: 10000, // 10 second timeout
+    }).trim();
+
+    // Cache the result
+    commandCache.set(key, output, ttlMs);
+
+    return { ok: true, data: output, cached: false };
+  } catch (error) {
+    // Cache errors briefly to avoid repeated failures
+    const errMsg = error.message || 'Command failed';
+    return { ok: false, error: errMsg, cached: false };
+  }
+}
+
+/**
+ * Execute and cache a git command
+ * Helper with git-specific cache key format
+ * @param {string} gitCommand - Git subcommand (e.g., 'status --short')
+ * @param {Object} [options]
+ * @param {string} [options.cwd] - Working directory
+ * @param {boolean} [options.force=false] - Skip cache
+ * @param {number} [options.ttlMs=30000] - TTL (default 30s)
+ * @returns {{ ok: boolean, data?: string, error?: string, cached?: boolean }}
+ */
+function gitCached(gitCommand, options = {}) {
+  const { cwd = process.cwd(), ttlMs = 30000, force = false } = options;
+  const command = `git ${gitCommand}`;
+  const cacheKey = `git:${gitCommand}:${cwd}`;
+
+  return execCached(command, {
+    cwd,
+    force,
+    ttlMs,
+    cacheKey,
+  });
+}
+
+/**
+ * Common git commands with caching
+ */
+const gitCommands = {
+  /**
+   * Get current branch name (cached)
+   * @param {string} [cwd] - Working directory
+   * @param {Object} [options]
+   * @returns {{ ok: boolean, data?: string, cached?: boolean }}
+   */
+  branch(cwd, options = {}) {
+    return gitCached('branch --show-current', { cwd, ...options });
+  },
+
+  /**
+   * Get short status (cached)
+   * @param {string} [cwd] - Working directory
+   * @param {Object} [options]
+   * @returns {{ ok: boolean, data?: string, cached?: boolean }}
+   */
+  status(cwd, options = {}) {
+    return gitCached('status --short', { cwd, ...options });
+  },
+
+  /**
+   * Get recent commits (cached)
+   * @param {string} [cwd] - Working directory
+   * @param {Object} [options]
+   * @param {number} [options.count=5] - Number of commits
+   * @returns {{ ok: boolean, data?: string, cached?: boolean }}
+   */
+  log(cwd, options = {}) {
+    const { count = 5, ...rest } = options;
+    return gitCached(`log -${count} --oneline`, { cwd, ...rest });
+  },
+
+  /**
+   * Get diff summary (cached with shorter TTL)
+   * @param {string} [cwd] - Working directory
+   * @param {Object} [options]
+   * @returns {{ ok: boolean, data?: string, cached?: boolean }}
+   */
+  diff(cwd, options = {}) {
+    return gitCached('diff --stat', { cwd, ttlMs: 15000, ...options });
+  },
+
+  /**
+   * Get last commit short hash (cached)
+   * @param {string} [cwd] - Working directory
+   * @param {Object} [options]
+   * @returns {{ ok: boolean, data?: string, cached?: boolean }}
+   */
+  commitHash(cwd, options = {}) {
+    return gitCached('log -1 --format="%h"', { cwd, ...options });
+  },
+
+  /**
+   * Get last commit message (cached)
+   * @param {string} [cwd] - Working directory
+   * @param {Object} [options]
+   * @returns {{ ok: boolean, data?: string, cached?: boolean }}
+   */
+  commitMessage(cwd, options = {}) {
+    return gitCached('log -1 --format="%s"', { cwd, ...options });
+  },
+};
+
+/**
+ * Invalidate all git caches for a directory
+ * Call this after git operations that modify state
+ * @param {string} [cwd] - Working directory
+ */
+function invalidateGitCache(cwd = process.cwd()) {
+  const prefix = `git:`;
+  const suffix = `:${cwd}`;
+  for (const key of commandCache.cache.keys()) {
+    if (key.startsWith(prefix) && key.endsWith(suffix)) {
+      commandCache.delete(key);
+    }
+  }
+}
+
+/**
+ * Get command cache statistics
+ * @returns {Object} Cache stats
+ */
+function getCommandCacheStats() {
+  return commandCache.getStats();
+}
+
+/**
+ * Clear command cache
+ */
+function clearCommandCache() {
+  commandCache.clear();
+}
+
 module.exports = {
   // Core LRU Cache class (for custom usage)
   LRUCache,
@@ -356,4 +530,12 @@ module.exports = {
   readMetadata,
   readRegistry,
   readProjectFiles,
+
+  // Command caching
+  execCached,
+  gitCached,
+  gitCommands,
+  invalidateGitCache,
+  getCommandCacheStats,
+  clearCommandCache,
 };

package/lib/format-error.js

@@ -0,0 +1,156 @@
+/**
+ * format-error.js - Standalone error formatting helpers
+ *
+ * Extracted from ErrorHandler for use without class instantiation.
+ * Provides consistent error/warning formatting with actionable guidance.
+ *
+ * Format: "X <problem> | Action: <what to do> | Run: <command>"
+ *
+ * Usage:
+ *   const { formatError, formatWarning, formatSuccess, formatInfo } = require('./format-error');
+ *   console.error(formatError('File not found', 'Check the path', 'ls -la'));
+ */
+
+const { c } = require('./colors');
+
+// Unicode symbols
+const SYMBOLS = {
+  error: '\u2716', // ✖
+  warning: '\u26A0', // ⚠
+  success: '\u2714', // ✔
+  info: '\u2139', // ℹ
+};
+
+/**
+ * Format a message with optional action and command hints
+ *
+ * @param {string} symbol - Unicode symbol to use
+ * @param {string} symbolColor - Color for the symbol
+ * @param {string} message - The message to display
+ * @param {Object} [options={}] - Formatting options
+ * @param {string} [options.action] - Action text (what user should do)
+ * @param {string} [options.command] - Command to run
+ * @param {string} [options.detail] - Additional detail line
+ * @returns {string} Formatted message string
+ */
+function formatMessage(symbol, symbolColor, message, options = {}) {
+  const { action, command, detail } = options;
+
+  let output = `${symbolColor}${symbol}${c.reset} ${message}`;
+
+  if (action) {
+    output += ` ${c.dim}|${c.reset} ${c.cyan}Action:${c.reset} ${action}`;
+  }
+
+  if (command) {
+    output += ` ${c.dim}|${c.reset} ${c.green}Run:${c.reset} ${c.bold}${command}${c.reset}`;
+  }
+
+  if (detail) {
+    output += `\n  ${c.dim}${detail}${c.reset}`;
+  }
+
+  return output;
+}
+
+/**
+ * Format an error message (red X)
+ *
+ * @param {string} message - Error message
+ * @param {string} [action] - What user should do
+ * @param {string} [command] - Command to run
+ * @returns {string} Formatted error string
+ *
+ * @example
+ * formatError('Config not found', 'Create config file', 'npx agileflow setup')
+ * // Output: ✖ Config not found | Action: Create config file | Run: npx agileflow setup
+ */
+function formatError(message, action, command) {
+  return formatMessage(SYMBOLS.error, c.red, message, { action, command });
+}
+
+/**
+ * Format a warning message (yellow warning sign)
+ *
+ * @param {string} message - Warning message
+ * @param {string} [action] - What user should do
+ * @param {string} [command] - Command to run
+ * @returns {string} Formatted warning string
+ */
+function formatWarning(message, action, command) {
+  return formatMessage(SYMBOLS.warning, c.yellow, message, { action, command });
+}
+
+/**
+ * Format a success message (green checkmark)
+ *
+ * @param {string} message - Success message
+ * @param {string} [detail] - Additional detail
+ * @returns {string} Formatted success string
+ */
+function formatSuccess(message, detail) {
+  return formatMessage(SYMBOLS.success, c.green, message, { detail });
+}
+
+/**
+ * Format an info message (blue info symbol)
+ *
+ * @param {string} message - Info message
+ * @param {string} [detail] - Additional detail
+ * @returns {string} Formatted info string
+ */
+function formatInfo(message, detail) {
+  return formatMessage(SYMBOLS.info, c.blue, message, { detail });
+}
+
+/**
+ * Format multiple issues for display
+ *
+ * @param {Array<{type: 'error'|'warning'|'success'|'info', message: string, action?: string, command?: string}>} issues
+ * @returns {string[]} Array of formatted strings
+ */
+function formatIssues(issues) {
+  return issues.map(issue => {
+    switch (issue.type) {
+      case 'error':
+        return formatError(issue.message, issue.action, issue.command);
+      case 'warning':
+        return formatWarning(issue.message, issue.action, issue.command);
+      case 'success':
+        return formatSuccess(issue.message, issue.detail);
+      case 'info':
+        return formatInfo(issue.message, issue.detail);
+      default:
+        return formatInfo(issue.message);
+    }
+  });
+}
+
+/**
+ * Format error with stack trace (for DEBUG mode)
+ *
+ * @param {string} message - Error message
+ * @param {Error} error - Error object with stack
+ * @param {Object} [options={}] - Formatting options
+ * @returns {string} Formatted error with optional stack trace
+ */
+function formatErrorWithStack(message, error, options = {}) {
+  const base = formatError(message, options.action, options.command);
+
+  if (process.env.DEBUG === '1' && error?.stack) {
+    return `${base}\n\n${c.dim}Stack trace:${c.reset}\n${c.dim}${error.stack}${c.reset}`;
+  }
+
+  return base;
+}
+
+module.exports = {
+  formatError,
+  formatWarning,
+  formatSuccess,
+  formatInfo,
+  formatIssues,
+  formatErrorWithStack,
+  formatMessage,
+  SYMBOLS,
+};

package/lib/path-resolver.js

@@ -48,11 +48,17 @@ class PathResolver {
     this._defaultDocsFolder = docsFolder;
 
     // Find project root
-    if (projectRoot) {
+    if (projectRoot && autoDetect) {
+      // Auto-detect from provided starting directory
+      this._projectRoot = this._findProjectRoot(projectRoot);
+    } else if (projectRoot) {
+      // Use provided directory directly (no auto-detection)
       this._projectRoot = projectRoot;
     } else if (autoDetect) {
+      // Auto-detect from current working directory
       this._projectRoot = this._findProjectRoot(process.cwd());
     } else {
+      // Use current working directory directly
       this._projectRoot = process.cwd();
     }
 
@@ -256,31 +262,173 @@ class PathResolver {
   }
 
   /**
-   * Get the agents directory path
+   * Get the agents directory path (.agileflow/agents)
    * @returns {string}
    */
   getAgentsDir() {
     return path.join(this.getAgileflowDir(), 'agents');
   }
 
+  /**
+   * Get the skills directory path
+   * @returns {string}
+   */
+  getSkillsDir() {
+    return path.join(this.getAgileflowDir(), 'skills');
+  }
+
+  /**
+   * Get the _cfg directory path
+   * @returns {string}
+   */
+  getCfgDir() {
+    return path.join(this.getAgileflowDir(), '_cfg');
+  }
+
+  // ============================================================================
+  // Claude Settings Paths (new in ConfigResolver pattern)
+  // ============================================================================
+
+  /**
+   * Get the .claude/settings.json path
+   * @returns {string}
+   */
+  getSettingsPath() {
+    return path.join(this.getClaudeDir(), 'settings.json');
+  }
+
+  /**
+   * Get the .claude/settings.local.json path
+   * @returns {string}
+   */
+  getSettingsLocalPath() {
+    return path.join(this.getClaudeDir(), 'settings.local.json');
+  }
+
+  /**
+   * Get the .claude/settings.local.example.json path
+   * @returns {string}
+   */
+  getSettingsLocalExamplePath() {
+    return path.join(this.getClaudeDir(), 'settings.local.example.json');
+  }
+
+  // ============================================================================
+  // Docs Subdirectory Paths (new in ConfigResolver pattern)
+  // ============================================================================
+
+  /**
+   * Get the docs/09-agents directory path
+   * @returns {string}
+   */
+  getDocsAgentsDir() {
+    return path.join(this.getDocsDir(), '09-agents');
+  }
+
+  /**
+   * Get the bus log path (docs/09-agents/bus/log.jsonl)
+   * @returns {string}
+   */
+  getBusLogPath() {
+    return path.join(this.getDocsAgentsDir(), 'bus', 'log.jsonl');
+  }
+
+  /**
+   * Get the archive directory path (docs/09-agents/archive)
+   * @returns {string}
+   */
+  getArchiveDir() {
+    return path.join(this.getDocsAgentsDir(), 'archive');
+  }
+
+  /**
+   * Get the epics directory path (docs/05-epics)
+   * @returns {string}
+   */
+  getEpicsDir() {
+    return path.join(this.getDocsDir(), '05-epics');
+  }
+
+  /**
+   * Get the stories directory path (docs/06-stories)
+   * @returns {string}
+   */
+  getStoriesDir() {
+    return path.join(this.getDocsDir(), '06-stories');
+  }
+
+  /**
+   * Get the decisions (ADR) directory path (docs/03-decisions)
+   * @returns {string}
+   */
+  getDecisionsDir() {
+    return path.join(this.getDocsDir(), '03-decisions');
+  }
+
+  /**
+   * Get the research directory path (docs/10-research)
+   * @returns {string}
+   */
+  getResearchDir() {
+    return path.join(this.getDocsDir(), '10-research');
+  }
+
+  /**
+   * Get the testing directory path (docs/07-testing)
+   * @returns {string}
+   */
+  getTestingDir() {
+    return path.join(this.getDocsDir(), '07-testing');
+  }
+
+  /**
+   * Get the architecture directory path (docs/04-architecture)
+   * @returns {string}
+   */
+  getArchitectureDir() {
+    return path.join(this.getDocsDir(), '04-architecture');
+  }
+
   /**
    * Get all paths at once
    * @returns {Object} Object with all path values
    */
   getAllPaths() {
     return {
+      // Project root and main directories
       projectRoot: this.getProjectRoot(),
       agileflowDir: this.getAgileflowDir(),
       docsDir: this.getDocsDir(),
       claudeDir: this.getClaudeDir(),
-      statusPath: this.getStatusPath(),
-      sessionStatePath: this.getSessionStatePath(),
-      metadataPath: this.getMetadataPath(),
-      configPath: this.getConfigPath(),
-      manifestPath: this.getManifestPath(),
+
+      // AgileFlow subdirectories
       scriptsDir: this.getScriptsDir(),
       commandsDir: this.getCommandsDir(),
       agentsDir: this.getAgentsDir(),
+      skillsDir: this.getSkillsDir(),
+      cfgDir: this.getCfgDir(),
+
+      // Configuration files
+      configPath: this.getConfigPath(),
+      manifestPath: this.getManifestPath(),
+      settingsPath: this.getSettingsPath(),
+      settingsLocalPath: this.getSettingsLocalPath(),
+
+      // Status and state files
+      statusPath: this.getStatusPath(),
+      sessionStatePath: this.getSessionStatePath(),
+      metadataPath: this.getMetadataPath(),
+      busLogPath: this.getBusLogPath(),
+
+      // Docs subdirectories
+      docsAgentsDir: this.getDocsAgentsDir(),
+      archiveDir: this.getArchiveDir(),
+      epicsDir: this.getEpicsDir(),
+      storiesDir: this.getStoriesDir(),
+      decisionsDir: this.getDecisionsDir(),
+      researchDir: this.getResearchDir(),
+      testingDir: this.getTestingDir(),
+      architectureDir: this.getArchitectureDir(),
     };
   }