agileflow 3.4.2 → 4.0.0-alpha.1

package/lib/registry-di.js

@@ -1,358 +0,0 @@
-/**
- * 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

@@ -1,363 +0,0 @@
-/**
- * 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,
-};