agileflow 2.91.0 → 2.92.0

package/lib/registry-di.js

@@ -0,0 +1,358 @@
+/**
+ * Registry Dependency Injection Module
+ *
+ * Provides dependency injection patterns for registry classes to enable:
+ * - Easier testing with mock dependencies
+ * - Configuration without modifying code
+ * - Clear separation of concerns
+ *
+ * Usage:
+ *   const { createContainer, createPlaceholderRegistry } = require('./registry-di');
+ *
+ *   // Create a container with custom dependencies
+ *   const container = createContainer({
+ *     sanitizer: mockSanitizer,
+ *     fs: mockFs,
+ *   });
+ *
+ *   // Create registry using container
+ *   const registry = createPlaceholderRegistry(container);
+ */
+
+'use strict';
+
+// Default dependencies
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * @typedef {Object} IDependencyContainer
+ * @property {Object} fs - File system module
+ * @property {Object} path - Path module
+ * @property {Object} sanitizer - Content sanitizer module
+ * @property {Object} [logger] - Optional logger interface
+ */
+
+/**
+ * @typedef {Object} ISanitizer
+ * @property {Function} sanitize.count - Sanitize count values
+ * @property {Function} sanitize.description - Sanitize description strings
+ * @property {Function} sanitize.date - Sanitize date values
+ * @property {Function} sanitize.version - Sanitize version strings
+ * @property {Function} sanitize.folderName - Sanitize folder names
+ * @property {Function} validatePlaceholderValue - Validate placeholder values
+ * @property {Function} detectInjectionAttempt - Detect injection attempts
+ * @property {Function} escapeMarkdown - Escape markdown characters
+ */
+
+/**
+ * @typedef {Object} ILogger
+ * @property {Function} debug - Debug level logging
+ * @property {Function} info - Info level logging
+ * @property {Function} warn - Warning level logging
+ * @property {Function} error - Error level logging
+ */
+
+/**
+ * Default no-op logger
+ */
+const noopLogger = {
+  debug: () => {},
+  info: () => {},
+  warn: () => {},
+  error: () => {},
+};
+
+/**
+ * Console logger adapter
+ */
+const consoleLogger = {
+  debug: (...args) => console.debug('[Registry]', ...args),
+  info: (...args) => console.log('[Registry]', ...args),
+  warn: (...args) => console.warn('[Registry]', ...args),
+  error: (...args) => console.error('[Registry]', ...args),
+};
+
+/**
+ * Load default sanitizer module
+ * @returns {ISanitizer}
+ */
+function loadDefaultSanitizer() {
+  try {
+    return require('./content-sanitizer');
+  } catch (e) {
+    // Return stub sanitizer if module not found
+    return {
+      sanitize: {
+        count: v => (typeof v === 'number' ? Math.max(0, Math.floor(v)) : 0),
+        description: v => String(v || ''),
+        date: v => (v instanceof Date ? v.toISOString().split('T')[0] : String(v || '')),
+        version: v => String(v || 'unknown'),
+        folderName: v => String(v || '.agileflow'),
+      },
+      validatePlaceholderValue: () => ({ valid: true }),
+      detectInjectionAttempt: () => ({ safe: true }),
+      escapeMarkdown: v => String(v || ''),
+    };
+  }
+}
+
+/**
+ * Create a dependency container with defaults
+ * @param {Partial<IDependencyContainer>} [overrides={}] - Override specific dependencies
+ * @returns {IDependencyContainer}
+ */
+function createContainer(overrides = {}) {
+  const defaultSanitizer = loadDefaultSanitizer();
+
+  return {
+    fs: overrides.fs || fs,
+    path: overrides.path || path,
+    sanitizer: overrides.sanitizer || defaultSanitizer,
+    logger: overrides.logger || noopLogger,
+  };
+}
+
+/**
+ * Create a test container with mock-friendly defaults
+ * @param {Partial<IDependencyContainer>} [overrides={}] - Override specific dependencies
+ * @returns {IDependencyContainer}
+ */
+function createTestContainer(overrides = {}) {
+  const mockFs = {
+    readdirSync: () => [],
+    readFileSync: () => '',
+    existsSync: () => false,
+    writeFileSync: () => {},
+    mkdirSync: () => {},
+    ...overrides.fs,
+  };
+
+  const mockSanitizer = {
+    sanitize: {
+      count: v => v,
+      description: v => v,
+      date: v => v,
+      version: v => v,
+      folderName: v => v,
+    },
+    validatePlaceholderValue: () => ({ valid: true }),
+    detectInjectionAttempt: () => ({ safe: true }),
+    escapeMarkdown: v => v,
+    ...overrides.sanitizer,
+  };
+
+  return createContainer({
+    fs: mockFs,
+    sanitizer: mockSanitizer,
+    logger: overrides.logger || noopLogger,
+    ...overrides,
+  });
+}
+
+/**
+ * Registry factory configuration
+ * @typedef {Object} RegistryFactoryConfig
+ * @property {Object} [options] - Registry options
+ * @property {IDependencyContainer} [container] - Dependency container
+ */
+
+/**
+ * Create PlaceholderRegistry with injected dependencies
+ * @param {IDependencyContainer} container - Dependency container
+ * @param {Object} [options={}] - Registry options
+ * @returns {PlaceholderRegistry}
+ */
+function createPlaceholderRegistry(container, options = {}) {
+  const { PlaceholderRegistry } = require('./placeholder-registry');
+
+  // Create registry with injected container
+  const registry = new PlaceholderRegistry({
+    ...options,
+    // Inject dependencies via context
+    _container: container,
+  });
+
+  return registry;
+}
+
+/**
+ * Scan registry factory - creates scanner functions with injected dependencies
+ * @param {IDependencyContainer} container - Dependency container
+ * @returns {Object} Scanner functions
+ */
+function createScannerFactory(container) {
+  const { fs: fsModule, path: pathModule, logger } = container;
+
+  /**
+   * Generic file scanner
+   * @param {string} directory - Directory to scan
+   * @param {string} extension - File extension (e.g., '.md')
+   * @param {Function} parser - Frontmatter parser function
+   * @returns {Array} Parsed items
+   */
+  function scanDirectory(directory, extension, parser) {
+    logger.debug(`Scanning directory: ${directory}`);
+
+    if (!fsModule.existsSync(directory)) {
+      logger.warn(`Directory not found: ${directory}`);
+      return [];
+    }
+
+    let files;
+    try {
+      files = fsModule.readdirSync(directory);
+    } catch (err) {
+      logger.error(`Failed to read directory: ${err.message}`);
+      return [];
+    }
+
+    const items = [];
+
+    for (const file of files) {
+      if (!file.endsWith(extension)) {
+        continue;
+      }
+
+      const filePath = pathModule.join(directory, file);
+
+      try {
+        const content = fsModule.readFileSync(filePath, 'utf8');
+        const parsed = parser(content, file, filePath);
+
+        if (parsed) {
+          items.push(parsed);
+        }
+      } catch (err) {
+        logger.warn(`Failed to parse ${file}: ${err.message}`);
+      }
+    }
+
+    logger.debug(`Found ${items.length} items`);
+    return items;
+  }
+
+  return {
+    scanDirectory,
+
+    /**
+     * Scan for command files
+     * @param {string} commandsDir - Commands directory path
+     * @param {Function} extractFrontmatter - Frontmatter extractor
+     * @returns {Array} Command metadata
+     */
+    scanCommands(commandsDir, extractFrontmatter) {
+      return scanDirectory(commandsDir, '.md', (content, file, filePath) => {
+        const frontmatter = extractFrontmatter(filePath);
+        if (Object.keys(frontmatter).length === 0) {
+          return null;
+        }
+
+        const name = file.replace('.md', '');
+        return {
+          name,
+          file,
+          path: filePath,
+          description: frontmatter.description || '',
+          argumentHint: frontmatter['argument-hint'] || '',
+        };
+      });
+    },
+
+    /**
+     * Scan for agent files
+     * @param {string} agentsDir - Agents directory path
+     * @param {Function} extractFrontmatter - Frontmatter extractor
+     * @param {Function} normalizeTools - Tools normalizer
+     * @returns {Array} Agent metadata
+     */
+    scanAgents(agentsDir, extractFrontmatter, normalizeTools) {
+      return scanDirectory(agentsDir, '.md', (content, file, filePath) => {
+        const frontmatter = extractFrontmatter(filePath);
+        if (Object.keys(frontmatter).length === 0) {
+          return null;
+        }
+
+        const name = file.replace('.md', '');
+        const tools = normalizeTools ? normalizeTools(frontmatter.tools) : frontmatter.tools || [];
+
+        return {
+          name,
+          file,
+          path: filePath,
+          displayName: frontmatter.name || name,
+          description: frontmatter.description || '',
+          tools,
+          model: frontmatter.model || 'haiku',
+          color: frontmatter.color || 'blue',
+        };
+      });
+    },
+  };
+}
+
+/**
+ * Resolve paths factory - creates path resolver with injected dependencies
+ * @param {IDependencyContainer} container - Dependency container
+ * @param {string} [baseDir] - Base directory for relative paths
+ * @returns {Object} Path resolver functions
+ */
+function createPathResolver(container, baseDir) {
+  const { path: pathModule, fs: fsModule } = container;
+  const resolvedBaseDir = baseDir || process.cwd();
+
+  return {
+    /**
+     * Resolve path relative to base directory
+     * @param {...string} segments - Path segments
+     * @returns {string} Resolved path
+     */
+    resolve(...segments) {
+      return pathModule.resolve(resolvedBaseDir, ...segments);
+    },
+
+    /**
+     * Join path segments
+     * @param {...string} segments - Path segments
+     * @returns {string} Joined path
+     */
+    join(...segments) {
+      return pathModule.join(...segments);
+    },
+
+    /**
+     * Check if path exists
+     * @param {string} targetPath - Path to check
+     * @returns {boolean}
+     */
+    exists(targetPath) {
+      return fsModule.existsSync(targetPath);
+    },
+
+    /**
+     * Get base directory
+     * @returns {string}
+     */
+    getBaseDir() {
+      return resolvedBaseDir;
+    },
+  };
+}
+
+module.exports = {
+  // Container factories
+  createContainer,
+  createTestContainer,
+
+  // Registry factories
+  createPlaceholderRegistry,
+  createScannerFactory,
+  createPathResolver,
+
+  // Loggers
+  noopLogger,
+  consoleLogger,
+
+  // Utilities
+  loadDefaultSanitizer,
+};

package/lib/result-schema.js

@@ -0,0 +1,363 @@
+/**
+ * result-schema.js - Unified Result<T> type for consistent return values
+ *
+ * Provides standardized Result type with metadata for:
+ * - Consistent success/failure handling
+ * - Error code integration
+ * - Severity and category tracking
+ * - Automatic recovery suggestions
+ *
+ * Usage:
+ *   const { success, failure, createResult, isSuccess } = require('./result-schema');
+ *
+ *   // Success case
+ *   return success(data);
+ *
+ *   // Failure case
+ *   return failure('ENOENT', 'File not found');
+ *
+ *   // Check result
+ *   if (isSuccess(result)) {
+ *     console.log(result.data);
+ *   } else {
+ *     console.error(result.error);
+ *   }
+ */
+
+const { ErrorCodes, Severity, Category, getErrorCode } = require('./error-codes');
+
+/**
+ * @typedef {Object} ResultSuccess<T>
+ * @property {true} ok - Indicates success
+ * @property {T} data - The success data
+ * @property {undefined} error - No error on success
+ * @property {undefined} errorCode - No error code on success
+ */
+
+/**
+ * @typedef {Object} ResultFailure
+ * @property {false} ok - Indicates failure
+ * @property {undefined} data - No data on failure
+ * @property {string} error - Human-readable error message
+ * @property {string} errorCode - Machine-readable error code
+ * @property {string} severity - Error severity (critical, high, medium, low)
+ * @property {string} category - Error category (filesystem, permission, etc.)
+ * @property {boolean} recoverable - Whether the error can be recovered from
+ * @property {string} [suggestedFix] - Suggested fix for the error
+ * @property {string} [autoFix] - Auto-fix action name if available
+ * @property {Object} [context] - Additional context about the error
+ */
+
+/**
+ * @typedef {ResultSuccess<T> | ResultFailure} Result<T>
+ */
+
+/**
+ * Create a success result
+ * @template T
+ * @param {T} data - The success data
+ * @param {Object} [meta] - Optional metadata
+ * @returns {ResultSuccess<T>}
+ */
+function success(data, meta = {}) {
+  return {
+    ok: true,
+    data,
+    ...meta,
+  };
+}
+
+/**
+ * Create a failure result with error code metadata
+ * @param {string} errorCode - Error code (e.g., 'ENOENT', 'ECONFIG')
+ * @param {string} [message] - Optional custom error message
+ * @param {Object} [options] - Additional options
+ * @param {Object} [options.context] - Additional context about the error
+ * @param {Error} [options.cause] - Original error that caused this failure
+ * @returns {ResultFailure}
+ */
+function failure(errorCode, message, options = {}) {
+  const codeData = getErrorCode(errorCode) || ErrorCodes.EUNKNOWN;
+
+  return {
+    ok: false,
+    error: message || codeData.message,
+    errorCode: codeData.code,
+    severity: codeData.severity,
+    category: codeData.category,
+    recoverable: codeData.recoverable,
+    suggestedFix: codeData.suggestedFix,
+    autoFix: codeData.autoFix || null,
+    context: options.context,
+    cause: options.cause,
+  };
+}
+
+/**
+ * Create a failure result from an existing Error object
+ * @param {Error} error - The error object
+ * @param {string} [defaultCode='EUNKNOWN'] - Default error code if none detected
+ * @param {Object} [options] - Additional options
+ * @param {Object} [options.context] - Additional context about the error
+ * @returns {ResultFailure}
+ */
+function failureFromError(error, defaultCode = 'EUNKNOWN', options = {}) {
+  const { getErrorCodeFromError } = require('./error-codes');
+  const codeData = getErrorCodeFromError(error);
+
+  // Use detected code or default
+  const code = codeData.code !== 'EUNKNOWN' ? codeData.code : defaultCode;
+  const finalCodeData = ErrorCodes[code] || ErrorCodes.EUNKNOWN;
+
+  return {
+    ok: false,
+    error: error.message || finalCodeData.message,
+    errorCode: finalCodeData.code,
+    severity: finalCodeData.severity,
+    category: finalCodeData.category,
+    recoverable: finalCodeData.recoverable,
+    suggestedFix: finalCodeData.suggestedFix,
+    autoFix: finalCodeData.autoFix || null,
+    context: options.context,
+    cause: error,
+  };
+}
+
+/**
+ * Create a result from a boolean condition
+ * @template T
+ * @param {boolean} condition - Condition to check
+ * @param {T} data - Data to return on success
+ * @param {string} errorCode - Error code on failure
+ * @param {string} [errorMessage] - Error message on failure
+ * @returns {Result<T>}
+ */
+function fromCondition(condition, data, errorCode, errorMessage) {
+  if (condition) {
+    return success(data);
+  }
+  return failure(errorCode, errorMessage);
+}
+
+/**
+ * Create a result from a Promise
+ * @template T
+ * @param {Promise<T>} promise - Promise to wrap
+ * @param {string} [defaultCode='EUNKNOWN'] - Default error code on rejection
+ * @returns {Promise<Result<T>>}
+ */
+async function fromPromise(promise, defaultCode = 'EUNKNOWN') {
+  try {
+    const data = await promise;
+    return success(data);
+  } catch (error) {
+    return failureFromError(error, defaultCode);
+  }
+}
+
+/**
+ * Create a result from a sync function call
+ * @template T
+ * @param {() => T} fn - Function to execute
+ * @param {string} [defaultCode='EUNKNOWN'] - Default error code on throw
+ * @returns {Result<T>}
+ */
+function fromTry(fn, defaultCode = 'EUNKNOWN') {
+  try {
+    const data = fn();
+    return success(data);
+  } catch (error) {
+    return failureFromError(error, defaultCode);
+  }
+}
+
+/**
+ * Check if a result is successful
+ * @template T
+ * @param {Result<T>} result - Result to check
+ * @returns {boolean}
+ */
+function isSuccess(result) {
+  return result != null && result.ok === true;
+}
+
+/**
+ * Check if a result is a failure
+ * @template T
+ * @param {Result<T>} result - Result to check
+ * @returns {boolean}
+ */
+function isFailure(result) {
+  return result != null && result.ok === false;
+}
+
+/**
+ * Get data from result or throw if failure
+ * @template T
+ * @param {Result<T>} result - Result to unwrap
+ * @param {string} [context] - Context for error message
+ * @returns {T}
+ * @throws {Error} If result is a failure
+ */
+function unwrap(result, context) {
+  if (isSuccess(result)) {
+    return result.data;
+  }
+
+  const prefix = context ? `${context}: ` : '';
+  const error = new Error(`${prefix}${result.error}`);
+  error.errorCode = result.errorCode;
+  error.severity = result.severity;
+  error.category = result.category;
+  error.recoverable = result.recoverable;
+  error.suggestedFix = result.suggestedFix;
+  throw error;
+}
+
+/**
+ * Get data from result or return default value on failure
+ * @template T
+ * @param {Result<T>} result - Result to unwrap
+ * @param {T} defaultValue - Default value on failure
+ * @returns {T}
+ */
+function unwrapOr(result, defaultValue) {
+  if (isSuccess(result)) {
+    return result.data;
+  }
+  return defaultValue;
+}
+
+/**
+ * Transform successful result data
+ * @template T, U
+ * @param {Result<T>} result - Result to transform
+ * @param {(data: T) => U} fn - Transform function
+ * @returns {Result<U>}
+ */
+function map(result, fn) {
+  if (isSuccess(result)) {
+    return success(fn(result.data));
+  }
+  return result;
+}
+
+/**
+ * Chain result-returning operations
+ * @template T, U
+ * @param {Result<T>} result - Result to chain from
+ * @param {(data: T) => Result<U>} fn - Function returning Result
+ * @returns {Result<U>}
+ */
+function flatMap(result, fn) {
+  if (isSuccess(result)) {
+    return fn(result.data);
+  }
+  return result;
+}
+
+/**
+ * Combine multiple results into one
+ * @template T
+ * @param {Result<T>[]} results - Results to combine
+ * @returns {Result<T[]>} Combined result with array of data or first failure
+ */
+function all(results) {
+  const data = [];
+
+  for (const result of results) {
+    if (isFailure(result)) {
+      return result;
+    }
+    data.push(result.data);
+  }
+
+  return success(data);
+}
+
+/**
+ * Get first successful result or last failure
+ * @template T
+ * @param {Result<T>[]} results - Results to check
+ * @returns {Result<T>} First success or last failure
+ */
+function any(results) {
+  let lastFailure = null;
+
+  for (const result of results) {
+    if (isSuccess(result)) {
+      return result;
+    }
+    lastFailure = result;
+  }
+
+  return lastFailure || failure('EUNKNOWN', 'No results provided');
+}
+
+/**
+ * Format a result for logging/display
+ * @template T
+ * @param {Result<T>} result - Result to format
+ * @param {Object} [options] - Format options
+ * @param {boolean} [options.includeData=false] - Include data in output
+ * @param {boolean} [options.includeSuggestion=true] - Include suggested fix
+ * @returns {string}
+ */
+function format(result, options = {}) {
+  const { includeData = false, includeSuggestion = true } = options;
+
+  if (isSuccess(result)) {
+    if (includeData) {
+      return `[OK] ${JSON.stringify(result.data)}`;
+    }
+    return '[OK]';
+  }
+
+  const lines = [`[${result.errorCode}] ${result.error}`];
+  lines.push(`  Severity: ${result.severity} | Category: ${result.category}`);
+
+  if (includeSuggestion && result.suggestedFix) {
+    lines.push(`  Fix: ${result.suggestedFix}`);
+  }
+
+  if (result.autoFix) {
+    lines.push(`  Auto-fix available: npx agileflow doctor --fix`);
+  }
+
+  return lines.join('\n');
+}
+
+module.exports = {
+  // Constructors
+  success,
+  failure,
+  failureFromError,
+
+  // From helpers
+  fromCondition,
+  fromPromise,
+  fromTry,
+
+  // Type guards
+  isSuccess,
+  isFailure,
+
+  // Extractors
+  unwrap,
+  unwrapOr,
+
+  // Transformers
+  map,
+  flatMap,
+
+  // Combinators
+  all,
+  any,
+
+  // Utilities
+  format,
+
+  // Re-export enums for convenience
+  Severity,
+  Category,
+};