agileflow 2.90.7 → 2.92.0

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(),
     };
   }
 

package/lib/paths.js

@@ -2,11 +2,43 @@
  * AgileFlow CLI - Shared Path Utilities
  *
  * Centralized path resolution functions used across scripts.
+ *
+ * NOTE: This module delegates to PathResolver for the implementation.
+ * Functions accept optional rootDir for backwards compatibility, but
+ * if not provided, use PathResolver's manifest-aware auto-detection.
+ *
+ * For new code, prefer using PathResolver directly:
+ *   const { PathResolver, getDefaultResolver } = require('./path-resolver');
+ *   const resolver = getDefaultResolver();
+ *   const statusPath = resolver.getStatusPath();
  */
 
-const fs = require('fs');
+const { PathResolver, getDefaultResolver } = require('./path-resolver');
 const path = require('path');
 
+// Cache for resolvers by rootDir
+const resolverCache = new Map();
+
+/**
+ * Get a PathResolver for the given rootDir.
+ * Uses singleton for default (no rootDir) case, caches others.
+ *
+ * @param {string} [rootDir] - Project root (auto-detected if not provided)
+ * @returns {PathResolver}
+ * @private
+ */
+function getResolver(rootDir) {
+  if (!rootDir) {
+    return getDefaultResolver();
+  }
+
+  // Cache resolvers by rootDir to avoid repeated construction
+  if (!resolverCache.has(rootDir)) {
+    resolverCache.set(rootDir, new PathResolver(rootDir, { autoDetect: false }));
+  }
+  return resolverCache.get(rootDir);
+}
+
 /**
  * Find the project root by looking for .agileflow directory.
  * Walks up from current directory until .agileflow is found.
@@ -15,11 +47,8 @@ const path = require('path');
  * @returns {string} Project root path, or startDir if not found
  */
 function getProjectRoot(startDir = process.cwd()) {
-  let dir = startDir;
-  while (!fs.existsSync(path.join(dir, '.agileflow')) && dir !== '/') {
-    dir = path.dirname(dir);
-  }
-  return dir !== '/' ? dir : startDir;
+  const resolver = new PathResolver(startDir, { autoDetect: true });
+  return resolver.getProjectRoot();
 }
 
 /**
@@ -29,8 +58,7 @@ function getProjectRoot(startDir = process.cwd()) {
  * @returns {string} Path to .agileflow directory
  */
 function getAgileflowDir(rootDir) {
-  const root = rootDir || getProjectRoot();
-  return path.join(root, '.agileflow');
+  return getResolver(rootDir).getAgileflowDir();
 }
 
 /**
@@ -40,8 +68,7 @@ function getAgileflowDir(rootDir) {
  * @returns {string} Path to .claude directory
  */
 function getClaudeDir(rootDir) {
-  const root = rootDir || getProjectRoot();
-  return path.join(root, '.claude');
+  return getResolver(rootDir).getClaudeDir();
 }
 
 /**
@@ -51,8 +78,7 @@ function getClaudeDir(rootDir) {
  * @returns {string} Path to docs directory
  */
 function getDocsDir(rootDir) {
-  const root = rootDir || getProjectRoot();
-  return path.join(root, 'docs');
+  return getResolver(rootDir).getDocsDir();
 }
 
 /**
@@ -62,8 +88,7 @@ function getDocsDir(rootDir) {
  * @returns {string} Path to status.json
  */
 function getStatusPath(rootDir) {
-  const root = rootDir || getProjectRoot();
-  return path.join(root, 'docs', '09-agents', 'status.json');
+  return getResolver(rootDir).getStatusPath();
 }
 
 /**
@@ -73,27 +98,194 @@ function getStatusPath(rootDir) {
  * @returns {string} Path to session-state.json
  */
 function getSessionStatePath(rootDir) {
-  const root = rootDir || getProjectRoot();
-  return path.join(root, 'docs', '09-agents', 'session-state.json');
+  return getResolver(rootDir).getSessionStatePath();
+}
+
+/**
+ * Get the agileflow-metadata.json path.
+ *
+ * @param {string} [rootDir] - Project root (auto-detected if not provided)
+ * @returns {string} Path to agileflow-metadata.json
+ */
+function getMetadataPath(rootDir) {
+  return getResolver(rootDir).getMetadataPath();
+}
+
+/**
+ * Get the message bus log path.
+ *
+ * @param {string} [rootDir] - Project root (auto-detected if not provided)
+ * @returns {string} Path to bus/log.jsonl
+ */
+function getBusLogPath(rootDir) {
+  return getResolver(rootDir).getBusLogPath();
+}
+
+/**
+ * Get the epics directory path.
+ *
+ * @param {string} [rootDir] - Project root (auto-detected if not provided)
+ * @returns {string} Path to epics directory
+ */
+function getEpicsDir(rootDir) {
+  return getResolver(rootDir).getEpicsDir();
+}
+
+/**
+ * Get the stories directory path.
+ *
+ * @param {string} [rootDir] - Project root (auto-detected if not provided)
+ * @returns {string} Path to stories directory
+ */
+function getStoriesDir(rootDir) {
+  return getResolver(rootDir).getStoriesDir();
+}
+
+/**
+ * Get the archive directory path for completed stories.
+ *
+ * @param {string} [rootDir] - Project root (auto-detected if not provided)
+ * @returns {string} Path to archive directory
+ */
+function getArchiveDir(rootDir) {
+  return getResolver(rootDir).getArchiveDir();
+}
+
+/**
+ * Get the agents directory path (docs/09-agents).
+ *
+ * @param {string} [rootDir] - Project root (auto-detected if not provided)
+ * @returns {string} Path to agents directory (docs/09-agents)
+ */
+function getAgentsDir(rootDir) {
+  return getResolver(rootDir).getDocsAgentsDir();
+}
+
+/**
+ * Get the decisions (ADR) directory path.
+ *
+ * @param {string} [rootDir] - Project root (auto-detected if not provided)
+ * @returns {string} Path to decisions directory
+ */
+function getDecisionsDir(rootDir) {
+  return getResolver(rootDir).getDecisionsDir();
+}
+
+/**
+ * Get the research directory path.
+ *
+ * @param {string} [rootDir] - Project root (auto-detected if not provided)
+ * @returns {string} Path to research directory
+ */
+function getResearchDir(rootDir) {
+  return getResolver(rootDir).getResearchDir();
 }
 
 /**
  * Check if we're in an AgileFlow project.
+ * Walks up from dir to find .agileflow directory.
  *
- * @param {string} [dir=process.cwd()] - Directory to check
- * @returns {boolean} True if .agileflow directory exists
+ * @param {string} [dir=process.cwd()] - Directory to check from
+ * @returns {boolean} True if .agileflow directory exists in dir or any parent
  */
 function isAgileflowProject(dir = process.cwd()) {
-  const root = getProjectRoot(dir);
-  return fs.existsSync(path.join(root, '.agileflow'));
+  // Use auto-detection to walk up and find project root
+  const resolver = new PathResolver(dir, { autoDetect: true });
+  return resolver.isAgileflowProject();
+}
+
+// ============================================================================
+// New functions (added in ConfigResolver consolidation)
+// ============================================================================
+
+/**
+ * Get the .claude/settings.json path.
+ *
+ * @param {string} [rootDir] - Project root (auto-detected if not provided)
+ * @returns {string} Path to settings.json
+ */
+function getSettingsPath(rootDir) {
+  return getResolver(rootDir).getSettingsPath();
+}
+
+/**
+ * Get the .claude/settings.local.json path.
+ *
+ * @param {string} [rootDir] - Project root (auto-detected if not provided)
+ * @returns {string} Path to settings.local.json
+ */
+function getSettingsLocalPath(rootDir) {
+  return getResolver(rootDir).getSettingsLocalPath();
+}
+
+/**
+ * Get the skills directory path.
+ *
+ * @param {string} [rootDir] - Project root (auto-detected if not provided)
+ * @returns {string} Path to skills directory
+ */
+function getSkillsDir(rootDir) {
+  return getResolver(rootDir).getSkillsDir();
+}
+
+/**
+ * Get the scripts directory path.
+ *
+ * @param {string} [rootDir] - Project root (auto-detected if not provided)
+ * @returns {string} Path to scripts directory
+ */
+function getScriptsDir(rootDir) {
+  return getResolver(rootDir).getScriptsDir();
+}
+
+/**
+ * Get the commands directory path.
+ *
+ * @param {string} [rootDir] - Project root (auto-detected if not provided)
+ * @returns {string} Path to commands directory
+ */
+function getCommandsDir(rootDir) {
+  return getResolver(rootDir).getCommandsDir();
+}
+
+/**
+ * Clear the resolver cache (useful for testing or after config changes).
+ */
+function clearResolverCache() {
+  resolverCache.clear();
 }
 
 module.exports = {
+  // Root and base directories
   getProjectRoot,
   getAgileflowDir,
   getClaudeDir,
   getDocsDir,
+
+  // Status and session files
   getStatusPath,
   getSessionStatePath,
+  getMetadataPath,
+  getBusLogPath,
+
+  // Documentation directories
+  getEpicsDir,
+  getStoriesDir,
+  getArchiveDir,
+  getAgentsDir,
+  getDecisionsDir,
+  getResearchDir,
+
+  // Configuration files (new in ConfigResolver consolidation)
+  getSettingsPath,
+  getSettingsLocalPath,
+
+  // AgileFlow subdirectories (new in ConfigResolver consolidation)
+  getSkillsDir,
+  getScriptsDir,
+  getCommandsDir,
+
+  // Utilities
   isAgileflowProject,
+  clearResolverCache,
 };