agileflow 2.94.1 → 2.95.1

package/lib/generator-factory.js

@@ -0,0 +1,333 @@
+/**
+ * GeneratorFactory - Dependency Injection for Content Generators
+ *
+ * Provides a centralized factory for creating content generators with:
+ * - Shared PlaceholderRegistry built once
+ * - Dependency injection for testability
+ * - Generator registration pattern
+ *
+ * Usage:
+ *   const factory = new GeneratorFactory();
+ *   factory.registerGenerator('help', HelpGenerator);
+ *   factory.registerGenerator('readme', ReadmeGenerator);
+ *
+ *   // Build registry once, pass to all generators
+ *   const context = await factory.buildContext();
+ *   await factory.runAll(context);
+ */
+
+'use strict';
+
+const { PlaceholderRegistry, createDefaultRegistry } = require('./placeholder-registry');
+const { createContainer, createScannerFactory } = require('./registry-di');
+
+/**
+ * Generator interface
+ * @typedef {Object} IGenerator
+ * @property {string} name - Generator name
+ * @property {Function} register - Register placeholders: (registry) => void
+ * @property {Function} generate - Generate content: (context) => Promise<void>
+ */
+
+/**
+ * GeneratorFactory - Factory for creating and running generators
+ */
+class GeneratorFactory {
+  /**
+   * Create a new GeneratorFactory
+   * @param {Object} options - Factory options
+   * @param {Object} [options.container] - DI container (from registry-di.js)
+   * @param {PlaceholderRegistry} [options.registry] - Pre-built registry
+   * @param {Object} [options.paths] - Path configuration
+   */
+  constructor(options = {}) {
+    this._generators = new Map();
+    this._container = options.container || createContainer();
+    this._registry = options.registry || null;
+    this._paths = options.paths || {};
+    this._built = false;
+    this._context = null;
+  }
+
+  /**
+   * Register a generator with the factory
+   * @param {string} name - Generator name
+   * @param {IGenerator|Function} generator - Generator instance or class
+   * @returns {GeneratorFactory} this for chaining
+   */
+  registerGenerator(name, generator) {
+    if (!name || typeof name !== 'string') {
+      throw new Error('Generator name must be a non-empty string');
+    }
+
+    // Support both instances and classes
+    const instance = typeof generator === 'function' ? new generator() : generator;
+
+    if (!instance.register || typeof instance.register !== 'function') {
+      throw new Error(`Generator "${name}" must have a register(registry) method`);
+    }
+
+    if (!instance.generate || typeof instance.generate !== 'function') {
+      throw new Error(`Generator "${name}" must have a generate(context) method`);
+    }
+
+    this._generators.set(name, instance);
+
+    // Reset built state when new generator is added
+    this._built = false;
+    this._context = null;
+
+    return this;
+  }
+
+  /**
+   * Unregister a generator
+   * @param {string} name - Generator name
+   * @returns {boolean} True if removed
+   */
+  unregisterGenerator(name) {
+    const result = this._generators.delete(name);
+    if (result) {
+      this._built = false;
+      this._context = null;
+    }
+    return result;
+  }
+
+  /**
+   * Get list of registered generator names
+   * @returns {string[]}
+   */
+  getGeneratorNames() {
+    return Array.from(this._generators.keys());
+  }
+
+  /**
+   * Check if a generator is registered
+   * @param {string} name - Generator name
+   * @returns {boolean}
+   */
+  hasGenerator(name) {
+    return this._generators.has(name);
+  }
+
+  /**
+   * Get the shared registry instance
+   * @returns {PlaceholderRegistry}
+   */
+  getRegistry() {
+    if (!this._registry) {
+      this._registry = createDefaultRegistry();
+    }
+    return this._registry;
+  }
+
+  /**
+   * Build context by registering all generator placeholders
+   * Registry is built once and shared across all generators
+   * @param {Object} [baseContext={}] - Base context to merge
+   * @returns {Object} Built context
+   */
+  buildContext(baseContext = {}) {
+    if (this._built && this._context) {
+      return { ...this._context, ...baseContext };
+    }
+
+    const registry = this.getRegistry();
+
+    // Let each generator register its placeholders
+    for (const [name, generator] of this._generators) {
+      try {
+        generator.register(registry);
+      } catch (error) {
+        console.error(`Failed to register placeholders for "${name}":`, error.message);
+      }
+    }
+
+    // Build context with resolved values
+    this._context = {
+      registry,
+      container: this._container,
+      paths: this._paths,
+      scanner: createScannerFactory(this._container),
+      ...baseContext,
+    };
+
+    this._built = true;
+
+    return this._context;
+  }
+
+  /**
+   * Run a specific generator
+   * @param {string} name - Generator name
+   * @param {Object} [context] - Context override
+   * @returns {Promise<{success: boolean, error?: Error}>}
+   */
+  async runGenerator(name, context) {
+    const generator = this._generators.get(name);
+
+    if (!generator) {
+      return { success: false, error: new Error(`Generator not found: ${name}`) };
+    }
+
+    const ctx = context || this.buildContext();
+
+    try {
+      await generator.generate(ctx);
+      return { success: true };
+    } catch (error) {
+      return { success: false, error };
+    }
+  }
+
+  /**
+   * Run all registered generators
+   * @param {Object} [context] - Context override
+   * @returns {Promise<Map<string, {success: boolean, error?: Error}>>}
+   */
+  async runAll(context) {
+    const ctx = context || this.buildContext();
+    const results = new Map();
+
+    for (const name of this._generators.keys()) {
+      results.set(name, await this.runGenerator(name, ctx));
+    }
+
+    return results;
+  }
+
+  /**
+   * Run generators in parallel
+   * @param {Object} [context] - Context override
+   * @returns {Promise<Map<string, {success: boolean, error?: Error}>>}
+   */
+  async runParallel(context) {
+    const ctx = context || this.buildContext();
+    const results = new Map();
+
+    const promises = Array.from(this._generators.keys()).map(async name => {
+      const result = await this.runGenerator(name, ctx);
+      return { name, result };
+    });
+
+    const settled = await Promise.allSettled(promises);
+
+    for (const item of settled) {
+      if (item.status === 'fulfilled') {
+        results.set(item.value.name, item.value.result);
+      } else {
+        // Shouldn't happen since runGenerator catches errors
+        const name = 'unknown';
+        results.set(name, { success: false, error: item.reason });
+      }
+    }
+
+    return results;
+  }
+
+  /**
+   * Reset the factory state
+   */
+  reset() {
+    this._built = false;
+    this._context = null;
+    this._registry = null;
+  }
+
+  /**
+   * Get container (for testing)
+   * @returns {Object}
+   */
+  getContainer() {
+    return this._container;
+  }
+}
+
+/**
+ * Base generator class with common utilities
+ */
+class BaseGenerator {
+  constructor(options = {}) {
+    this.name = options.name || this.constructor.name;
+    this.placeholders = [];
+  }
+
+  /**
+   * Register placeholders - override in subclass
+   * @param {PlaceholderRegistry} registry
+   */
+  register(registry) {
+    // Subclasses should override this method
+    for (const placeholder of this.placeholders) {
+      registry.register(placeholder.name, placeholder.resolver, placeholder.config);
+    }
+  }
+
+  /**
+   * Generate content - override in subclass
+   * @param {Object} context
+   * @returns {Promise<void>}
+   */
+  async generate(context) {
+    throw new Error('Subclass must implement generate(context)');
+  }
+
+  /**
+   * Helper to add a placeholder definition
+   * @param {string} name - Placeholder name
+   * @param {Function} resolver - Resolver function
+   * @param {Object} [config] - Configuration
+   */
+  addPlaceholder(name, resolver, config = {}) {
+    this.placeholders.push({ name, resolver, config });
+  }
+}
+
+/**
+ * Create a factory with standard generators
+ * @param {Object} options - Factory options
+ * @returns {GeneratorFactory}
+ */
+function createGeneratorFactory(options = {}) {
+  const factory = new GeneratorFactory(options);
+
+  // Register standard generators if provided
+  if (options.generators) {
+    for (const [name, generator] of Object.entries(options.generators)) {
+      factory.registerGenerator(name, generator);
+    }
+  }
+
+  return factory;
+}
+
+// Singleton instance
+let _factoryInstance = null;
+
+/**
+ * Get singleton factory instance
+ * @param {Object} [options] - Factory options
+ * @returns {GeneratorFactory}
+ */
+function getGeneratorFactory(options = {}) {
+  if (!_factoryInstance || options.forceNew) {
+    _factoryInstance = createGeneratorFactory(options);
+  }
+  return _factoryInstance;
+}
+
+/**
+ * Reset singleton (for testing)
+ */
+function resetGeneratorFactory() {
+  _factoryInstance = null;
+}
+
+module.exports = {
+  GeneratorFactory,
+  BaseGenerator,
+  createGeneratorFactory,
+  getGeneratorFactory,
+  resetGeneratorFactory,
+};

package/lib/path-utils.js

@@ -0,0 +1,49 @@
+/**
+ * path-utils.js - Unified Path Utilities Module
+ *
+ * This module consolidates all path-related utilities for AgileFlow CLI.
+ * It re-exports from validate-paths.js for backwards compatibility and
+ * discoverability, while adding path resolution helpers from path-resolver.js.
+ *
+ * US-0194: Consolidate Path Matching and Validation Logic
+ *
+ * Features:
+ * - Path traversal prevention (validatePath, hasUnsafePathPatterns)
+ * - Symlink chain validation (checkSymlinkChainDepth)
+ * - Filename sanitization (sanitizeFilename)
+ * - Path resolution with project root detection (PathResolver)
+ *
+ * Usage:
+ *   const { validatePath, PathResolver } = require('./path-utils');
+ *
+ *   // Validate a path is safe and within base directory
+ *   const result = validatePath('./config.yaml', '/project/root', { allowSymlinks: false });
+ *
+ *   // Use PathResolver for project-aware path operations
+ *   const resolver = new PathResolver('/project/root');
+ *   const docsPath = resolver.getDocsDir();
+ */
+
+// Re-export all path validation utilities from validate-paths.js
+const validatePaths = require('./validate-paths');
+
+// Re-export PathResolver for convenient access
+const { PathResolver, getDefaultResolver, getAllPaths } = require('./path-resolver');
+
+module.exports = {
+  // Path validation (from validate-paths.js)
+  PathValidationError: validatePaths.PathValidationError,
+  checkSymlinkChainDepth: validatePaths.checkSymlinkChainDepth,
+  validatePath: validatePaths.validatePath,
+  validatePathSync: validatePaths.validatePathSync,
+  hasUnsafePathPatterns: validatePaths.hasUnsafePathPatterns,
+  sanitizeFilename: validatePaths.sanitizeFilename,
+
+  // Path resolution (from path-resolver.js)
+  PathResolver,
+  getDefaultResolver,
+  getAllPaths,
+
+  // Convenience: full module access for advanced usage
+  paths: validatePaths,
+};

package/lib/session-registry.js

@@ -32,6 +32,7 @@ const EventEmitter = require('events');
 const fs = require('fs');
 const path = require('path');
 const SmartJsonFile = require('./smart-json-file');
+const { success, failure, failureFromError } = require('./result-schema');
 
 /**
  * Session Registry Event Bus
@@ -286,13 +287,13 @@ class SessionRegistry extends EventEmitter {
   /**
    * Unregister a session
    * @param {number|string} sessionId - Session ID
-   * @returns {Promise<{ok: boolean, found: boolean, error?: Error}>}
+   * @returns {Promise<Result<{found: boolean}>>}
    */
   async unregisterSession(sessionId) {
     const registry = await this.load(true);
 
     if (!registry.sessions || !registry.sessions[sessionId]) {
-      return { ok: true, found: false };
+      return success({ found: false });
     }
 
     delete registry.sessions[sessionId];
@@ -301,23 +302,25 @@ class SessionRegistry extends EventEmitter {
     if (result.ok) {
       this._auditLog('unregister', { sessionId });
       this.emit('unregistered', { sessionId });
-      return { ok: true, found: true };
+      return success({ found: true });
     }
 
-    return { ...result, found: true };
+    return failure('EUNKNOWN', result.error || 'Failed to save registry', {
+      context: { found: true },
+    });
   }
 
   /**
    * Update a session
    * @param {number|string} sessionId - Session ID
    * @param {Object} updates - Fields to update
-   * @returns {Promise<{ok: boolean, found: boolean, error?: Error}>}
+   * @returns {Promise<Result<{found: boolean}>>}
    */
   async updateSession(sessionId, updates) {
     const registry = await this.load(true);
 
     if (!registry.sessions || !registry.sessions[sessionId]) {
-      return { ok: false, found: false, error: new Error(`Session ${sessionId} not found`) };
+      return failure('ENOENT', `Session ${sessionId} not found`, { context: { found: false } });
     }
 
     registry.sessions[sessionId] = {
@@ -331,10 +334,12 @@ class SessionRegistry extends EventEmitter {
     if (result.ok) {
       this._auditLog('update', { sessionId, updates });
       this.emit('updated', { sessionId, changes: updates });
-      return { ok: true, found: true };
+      return success({ found: true });
     }
 
-    return { ...result, found: true };
+    return failure('EUNKNOWN', result.error || 'Failed to save registry', {
+      context: { found: true },
+    });
   }
 
   /**
@@ -359,11 +364,11 @@ class SessionRegistry extends EventEmitter {
 
   /**
    * Commit all batched changes in one write
-   * @returns {Promise<{ok: boolean, applied: number, error?: Error}>}
+   * @returns {Promise<Result<{applied: number}>>}
    */
   async commitBatch() {
     if (!this._batchMode) {
-      return { ok: false, applied: 0, error: new Error('Not in batch mode') };
+      return failure('EINVAL', 'Not in batch mode', { context: { applied: 0 } });
     }
 
     const registry = await this.load(true);
@@ -415,10 +420,10 @@ class SessionRegistry extends EventEmitter {
 
     if (result.ok) {
       this._auditLog('batch', { applied });
-      return { ok: true, applied };
+      return success({ applied });
     }
 
-    return { ...result, applied };
+    return failure('EUNKNOWN', result.error || 'Failed to save registry', { context: { applied } });
   }
 
   /**
@@ -447,7 +452,7 @@ class SessionRegistry extends EventEmitter {
   /**
    * Clean up stale sessions
    * @param {Function} isAlive - Function to check if session is alive (sessionId) => boolean
-   * @returns {Promise<{ok: boolean, cleaned: number}>}
+   * @returns {Promise<Result<{cleaned: number}>>}
    */
   async cleanupStaleSessions(isAlive) {
     const registry = await this.load(true);
@@ -464,10 +469,15 @@ class SessionRegistry extends EventEmitter {
 
     if (cleaned > 0) {
       const result = await this.save(registry);
-      return { ok: result.ok, cleaned };
+      if (!result.ok) {
+        return failure('EUNKNOWN', result.error || 'Failed to save registry', {
+          context: { cleaned },
+        });
+      }
+      return success({ cleaned });
     }
 
-    return { ok: true, cleaned: 0 };
+    return success({ cleaned: 0 });
   }
 }