agileflow 2.91.0 → 2.92.0

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

package/lib/placeholder-registry.js

@@ -39,6 +39,29 @@ const {
  * @property {string} [source='builtin'] - Source: 'builtin' | 'plugin'
  */
 
+/**
+ * Schema version for serialization compatibility
+ * Increment when making breaking changes to serialized format
+ *
+ * Version history:
+ * - 1: Initial schema with name, type, description, secure, cacheable, source
+ * - 2: Added validator serialization support, context metadata
+ */
+const SCHEMA_VERSION = 2;
+
+/**
+ * Schema migrations for upgrading old configurations
+ */
+const SCHEMA_MIGRATIONS = {
+  // Migrate from v1 to v2
+  1: config => ({
+    ...config,
+    schemaVersion: 2,
+    contextMetadata: config.contextMetadata || {},
+    validatorName: config.validatorName || null,
+  }),
+};
+
 /**
  * Default resolver types with their sanitization rules
  */
@@ -470,6 +493,186 @@ class PlaceholderRegistry extends EventEmitter {
     // Could be extended to include context hash
     return name;
   }
+
+  // ===========================================================================
+  // Schema Versioning and Serialization
+  // ===========================================================================
+
+  /**
+   * Get current schema version
+   * @returns {number}
+   */
+  static getSchemaVersion() {
+    return SCHEMA_VERSION;
+  }
+
+  /**
+   * Serialize registry configuration for persistence
+   * @returns {Object} Serializable configuration
+   */
+  serialize() {
+    const configs = {};
+
+    for (const [name, config] of this._resolvers) {
+      configs[name] = {
+        schemaVersion: SCHEMA_VERSION,
+        name: config.name,
+        description: config.description,
+        type: config.type,
+        secure: config.secure,
+        cacheable: config.cacheable,
+        source: config.source,
+        contextMetadata: config.contextMetadata || {},
+        validatorName: config.validatorName || null,
+        // Note: resolver function cannot be serialized - must be re-registered
+      };
+    }
+
+    return {
+      schemaVersion: SCHEMA_VERSION,
+      registryOptions: {
+        cacheEnabled: this.cacheEnabled,
+        strictMode: this.strictMode,
+        secureByDefault: this.secureByDefault,
+      },
+      placeholders: configs,
+      plugins: Array.from(this._plugins.keys()),
+    };
+  }
+
+  /**
+   * Export configuration as JSON string
+   * @param {number} [spaces=2] - JSON indentation
+   * @returns {string}
+   */
+  toJSON(spaces = 2) {
+    return JSON.stringify(this.serialize(), null, spaces);
+  }
+
+  /**
+   * Migrate configuration to current schema version
+   * @param {Object} config - Configuration to migrate
+   * @returns {Object} Migrated configuration
+   */
+  static migrateConfig(config) {
+    let migrated = { ...config };
+    let version = config.schemaVersion || 1;
+
+    // Apply migrations sequentially
+    while (version < SCHEMA_VERSION) {
+      const migration = SCHEMA_MIGRATIONS[version];
+      if (migration) {
+        migrated = migration(migrated);
+      }
+      version++;
+    }
+
+    return migrated;
+  }
+
+  /**
+   * Validate configuration against current schema
+   * @param {Object} config - Configuration to validate
+   * @returns {{valid: boolean, errors: string[]}}
+   */
+  static validateConfig(config) {
+    const errors = [];
+
+    if (!config || typeof config !== 'object') {
+      return { valid: false, errors: ['Configuration must be an object'] };
+    }
+
+    // Check schema version
+    if (config.schemaVersion && config.schemaVersion > SCHEMA_VERSION) {
+      errors.push(
+        `Configuration schema version ${config.schemaVersion} is newer than supported ${SCHEMA_VERSION}`
+      );
+    }
+
+    // Validate required fields for placeholder configs
+    if (config.placeholders) {
+      for (const [name, placeholder] of Object.entries(config.placeholders)) {
+        if (!placeholder.name) {
+          errors.push(`Placeholder "${name}" missing required field: name`);
+        }
+        if (!placeholder.type) {
+          errors.push(`Placeholder "${name}" missing required field: type`);
+        }
+        if (placeholder.type && !RESOLVER_TYPES[placeholder.type]) {
+          errors.push(`Placeholder "${name}" has invalid type: ${placeholder.type}`);
+        }
+      }
+    }
+
+    return { valid: errors.length === 0, errors };
+  }
+
+  /**
+   * Load configuration from serialized data
+   * Note: Only loads metadata - resolvers must be re-registered
+   * @param {Object} data - Serialized configuration
+   * @param {Object} [resolvers={}] - Map of resolver functions by name
+   * @returns {PlaceholderRegistry} New registry instance
+   */
+  static deserialize(data, resolvers = {}) {
+    // Validate
+    const validation = PlaceholderRegistry.validateConfig(data);
+    if (!validation.valid) {
+      throw new Error(`Invalid configuration: ${validation.errors.join(', ')}`);
+    }
+
+    // Migrate if needed
+    const migrated = PlaceholderRegistry.migrateConfig(data);
+
+    // Create registry with options
+    const options = migrated.registryOptions || {};
+    const registry = new PlaceholderRegistry({
+      cache: options.cacheEnabled,
+      strict: options.strictMode,
+      secure: options.secureByDefault,
+    });
+
+    // Register placeholders with provided resolvers
+    if (migrated.placeholders) {
+      for (const [name, config] of Object.entries(migrated.placeholders)) {
+        const resolver = resolvers[name];
+        if (resolver) {
+          registry.register(name, resolver, {
+            description: config.description,
+            type: config.type,
+            secure: config.secure,
+            cacheable: config.cacheable,
+            source: config.source,
+            contextMetadata: config.contextMetadata,
+            validatorName: config.validatorName,
+          });
+        }
+      }
+    }
+
+    return registry;
+  }
+
+  /**
+   * Parse JSON configuration and create registry
+   * @param {string} json - JSON string
+   * @param {Object} [resolvers={}] - Map of resolver functions by name
+   * @returns {PlaceholderRegistry}
+   */
+  static fromJSON(json, resolvers = {}) {
+    const data = JSON.parse(json);
+    return PlaceholderRegistry.deserialize(data, resolvers);
+  }
+
+  /**
+   * Check if configuration needs migration
+   * @param {Object} config - Configuration to check
+   * @returns {boolean}
+   */
+  static needsMigration(config) {
+    const version = config.schemaVersion || 1;
+    return version < SCHEMA_VERSION;
+  }
 }
 
 // =============================================================================
@@ -608,6 +811,8 @@ function resetRegistry() {
 module.exports = {
   PlaceholderRegistry,
   RESOLVER_TYPES,
+  SCHEMA_VERSION,
+  SCHEMA_MIGRATIONS,
   createCountResolver,
   createListResolver,
   createStaticResolver,