bmad-method 6.2.2 → 6.2.3-next.1

package/tools/{cli/installers/lib/core/config-collector.js → installer/modules/official-modules.js}

@@ -1,30 +1,701 @@
 const path = require('node:path');
 const fs = require('fs-extra');
 const yaml = require('yaml');
-const { getProjectRoot, getModulePath } = require('../../../lib/project-root');
-const { CLIUtils } = require('../../../lib/cli-utils');
-const prompts = require('../../../lib/prompts');
-
-class ConfigCollector {
-  constructor() {
+const prompts = require('../prompts');
+const { getProjectRoot, getSourcePath, getModulePath } = require('../project-root');
+const { CLIUtils } = require('../cli-utils');
+const { ExternalModuleManager } = require('./external-manager');
+
+class OfficialModules {
+  constructor(options = {}) {
+    this.externalModuleManager = new ExternalModuleManager();
+    // Config collection state (merged from ConfigCollector)
     this.collectedConfig = {};
-    this.existingConfig = null;
+    this._existingConfig = null;
     this.currentProjectDir = null;
-    this._moduleManagerInstance = null;
   }
 
   /**
-   * Get or create a cached ModuleManager instance (lazy initialization)
-   * @returns {Object} ModuleManager instance
+   * Module configurations collected during install.
+   */
+  get moduleConfigs() {
+    return this.collectedConfig;
+  }
+
+  /**
+   * Existing module configurations read from a previous installation.
+   */
+  get existingConfig() {
+    return this._existingConfig;
+  }
+
+  /**
+   * Build a configured OfficialModules instance from install config.
+   * @param {Object} config - Clean install config (from Config.build)
+   * @param {Object} paths - InstallPaths instance
+   * @returns {OfficialModules}
+   */
+  static async build(config, paths) {
+    const instance = new OfficialModules();
+
+    // Pre-collected by UI or quickUpdate — store and load existing for path-change detection
+    if (config.moduleConfigs) {
+      instance.collectedConfig = config.moduleConfigs;
+      await instance.loadExistingConfig(paths.projectRoot);
+      return instance;
+    }
+
+    // Headless collection (--yes flag from CLI without UI, tests)
+    if (config.hasCoreConfig()) {
+      instance.collectedConfig.core = config.coreConfig;
+      instance.allAnswers = {};
+      for (const [key, value] of Object.entries(config.coreConfig)) {
+        instance.allAnswers[`core_${key}`] = value;
+      }
+    }
+
+    const toCollect = config.hasCoreConfig() ? config.modules.filter((m) => m !== 'core') : [...config.modules];
+
+    await instance.collectAllConfigurations(toCollect, paths.projectRoot, {
+      skipPrompts: config.skipPrompts,
+    });
+
+    return instance;
+  }
+
+  /**
+   * Copy a file to the target location
+   * @param {string} sourcePath - Source file path
+   * @param {string} targetPath - Target file path
+   * @param {boolean} overwrite - Whether to overwrite existing files (default: true)
+   */
+  async copyFile(sourcePath, targetPath, overwrite = true) {
+    await fs.copy(sourcePath, targetPath, { overwrite });
+  }
+
+  /**
+   * Copy a directory recursively
+   * @param {string} sourceDir - Source directory path
+   * @param {string} targetDir - Target directory path
+   * @param {boolean} overwrite - Whether to overwrite existing files (default: true)
+   */
+  async copyDirectory(sourceDir, targetDir, overwrite = true) {
+    await fs.ensureDir(targetDir);
+    const entries = await fs.readdir(sourceDir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      const sourcePath = path.join(sourceDir, entry.name);
+      const targetPath = path.join(targetDir, entry.name);
+
+      if (entry.isDirectory()) {
+        await this.copyDirectory(sourcePath, targetPath, overwrite);
+      } else {
+        await this.copyFile(sourcePath, targetPath, overwrite);
+      }
+    }
+  }
+
+  /**
+   * List all available built-in modules (core and bmm).
+   * All other modules come from external-official-modules.yaml
+   * @returns {Object} Object with modules array and customModules array
+   */
+  async listAvailable() {
+    const modules = [];
+    const customModules = [];
+
+    // Add built-in core module (directly under src/core-skills)
+    const corePath = getSourcePath('core-skills');
+    if (await fs.pathExists(corePath)) {
+      const coreInfo = await this.getModuleInfo(corePath, 'core', 'src/core-skills');
+      if (coreInfo) {
+        modules.push(coreInfo);
+      }
+    }
+
+    // Add built-in bmm module (directly under src/bmm-skills)
+    const bmmPath = getSourcePath('bmm-skills');
+    if (await fs.pathExists(bmmPath)) {
+      const bmmInfo = await this.getModuleInfo(bmmPath, 'bmm', 'src/bmm-skills');
+      if (bmmInfo) {
+        modules.push(bmmInfo);
+      }
+    }
+
+    return { modules, customModules };
+  }
+
+  /**
+   * Get module information from a module path
+   * @param {string} modulePath - Path to the module directory
+   * @param {string} defaultName - Default name for the module
+   * @param {string} sourceDescription - Description of where the module was found
+   * @returns {Object|null} Module info or null if not a valid module
+   */
+  async getModuleInfo(modulePath, defaultName, sourceDescription) {
+    // Check for module structure (module.yaml OR custom.yaml)
+    const moduleConfigPath = path.join(modulePath, 'module.yaml');
+    const rootCustomConfigPath = path.join(modulePath, 'custom.yaml');
+    let configPath = null;
+
+    if (await fs.pathExists(moduleConfigPath)) {
+      configPath = moduleConfigPath;
+    } else if (await fs.pathExists(rootCustomConfigPath)) {
+      configPath = rootCustomConfigPath;
+    }
+
+    // Skip if this doesn't look like a module
+    if (!configPath) {
+      return null;
+    }
+
+    // Mark as custom if it's using custom.yaml OR if it's outside src/bmm or src/core
+    const isCustomSource =
+      sourceDescription !== 'src/bmm-skills' && sourceDescription !== 'src/core-skills' && sourceDescription !== 'src/modules';
+    const moduleInfo = {
+      id: defaultName,
+      path: modulePath,
+      name: defaultName
+        .split('-')
+        .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+        .join(' '),
+      description: 'BMAD Module',
+      version: '5.0.0',
+      source: sourceDescription,
+      isCustom: configPath === rootCustomConfigPath || isCustomSource,
+    };
+
+    // Read module config for metadata
+    try {
+      const configContent = await fs.readFile(configPath, 'utf8');
+      const config = yaml.parse(configContent);
+
+      // Use the code property as the id if available
+      if (config.code) {
+        moduleInfo.id = config.code;
+      }
+
+      moduleInfo.name = config.name || moduleInfo.name;
+      moduleInfo.description = config.description || moduleInfo.description;
+      moduleInfo.version = config.version || moduleInfo.version;
+      moduleInfo.dependencies = config.dependencies || [];
+      moduleInfo.defaultSelected = config.default_selected === undefined ? false : config.default_selected;
+    } catch (error) {
+      await prompts.log.warn(`Failed to read config for ${defaultName}: ${error.message}`);
+    }
+
+    return moduleInfo;
+  }
+
+  /**
+   * Find the source path for a module by searching all possible locations
+   * @param {string} moduleCode - Code of the module to find (from module.yaml)
+   * @returns {string|null} Path to the module source or null if not found
+   */
+  async findModuleSource(moduleCode, options = {}) {
+    const projectRoot = getProjectRoot();
+
+    // Check for core module (directly under src/core-skills)
+    if (moduleCode === 'core') {
+      const corePath = getSourcePath('core-skills');
+      if (await fs.pathExists(corePath)) {
+        return corePath;
+      }
+    }
+
+    // Check for built-in bmm module (directly under src/bmm-skills)
+    if (moduleCode === 'bmm') {
+      const bmmPath = getSourcePath('bmm-skills');
+      if (await fs.pathExists(bmmPath)) {
+        return bmmPath;
+      }
+    }
+
+    // Check external official modules
+    const externalSource = await this.externalModuleManager.findExternalModuleSource(moduleCode, options);
+    if (externalSource) {
+      return externalSource;
+    }
+
+    return null;
+  }
+
+  /**
+   * Install a module
+   * @param {string} moduleName - Code of the module to install (from module.yaml)
+   * @param {string} bmadDir - Target bmad directory
+   * @param {Function} fileTrackingCallback - Optional callback to track installed files
+   * @param {Object} options - Additional installation options
+   * @param {Array<string>} options.installedIDEs - Array of IDE codes that were installed
+   * @param {Object} options.moduleConfig - Module configuration from config collector
+   * @param {Object} options.logger - Logger instance for output
+   */
+  async install(moduleName, bmadDir, fileTrackingCallback = null, options = {}) {
+    const sourcePath = await this.findModuleSource(moduleName, { silent: options.silent });
+    const targetPath = path.join(bmadDir, moduleName);
+
+    if (!sourcePath) {
+      throw new Error(
+        `Source for module '${moduleName}' is not available. It will be retained but cannot be updated without its source files.`,
+      );
+    }
+
+    if (await fs.pathExists(targetPath)) {
+      await fs.remove(targetPath);
+    }
+
+    await this.copyModuleWithFiltering(sourcePath, targetPath, fileTrackingCallback, options.moduleConfig);
+
+    if (!options.skipModuleInstaller) {
+      await this.createModuleDirectories(moduleName, bmadDir, options);
+    }
+
+    const { Manifest } = require('../core/manifest');
+    const manifestObj = new Manifest();
+    const versionInfo = await manifestObj.getModuleVersionInfo(moduleName, bmadDir, sourcePath);
+
+    await manifestObj.addModule(bmadDir, moduleName, {
+      version: versionInfo.version,
+      source: versionInfo.source,
+      npmPackage: versionInfo.npmPackage,
+      repoUrl: versionInfo.repoUrl,
+    });
+
+    return { success: true, module: moduleName, path: targetPath, versionInfo };
+  }
+
+  /**
+   * Update an existing module
+   * @param {string} moduleName - Name of the module to update
+   * @param {string} bmadDir - Target bmad directory
    */
-  _getModuleManager() {
-    if (!this._moduleManagerInstance) {
-      const { ModuleManager } = require('../modules/manager');
-      this._moduleManagerInstance = new ModuleManager();
+  async update(moduleName, bmadDir) {
+    const sourcePath = await this.findModuleSource(moduleName);
+    const targetPath = path.join(bmadDir, moduleName);
+
+    if (!sourcePath) {
+      throw new Error(`Module '${moduleName}' not found in any source location`);
+    }
+
+    if (!(await fs.pathExists(targetPath))) {
+      throw new Error(`Module '${moduleName}' is not installed`);
     }
-    return this._moduleManagerInstance;
+
+    await this.syncModule(sourcePath, targetPath);
+
+    return {
+      success: true,
+      module: moduleName,
+      path: targetPath,
+    };
   }
 
+  /**
+   * Remove a module
+   * @param {string} moduleName - Name of the module to remove
+   * @param {string} bmadDir - Target bmad directory
+   */
+  async remove(moduleName, bmadDir) {
+    const targetPath = path.join(bmadDir, moduleName);
+
+    if (!(await fs.pathExists(targetPath))) {
+      throw new Error(`Module '${moduleName}' is not installed`);
+    }
+
+    await fs.remove(targetPath);
+
+    return {
+      success: true,
+      module: moduleName,
+    };
+  }
+
+  /**
+   * Check if a module is installed
+   * @param {string} moduleName - Name of the module
+   * @param {string} bmadDir - Target bmad directory
+   * @returns {boolean} True if module is installed
+   */
+  async isInstalled(moduleName, bmadDir) {
+    const targetPath = path.join(bmadDir, moduleName);
+    return await fs.pathExists(targetPath);
+  }
+
+  /**
+   * Get installed module info
+   * @param {string} moduleName - Name of the module
+   * @param {string} bmadDir - Target bmad directory
+   * @returns {Object|null} Module info or null if not installed
+   */
+  async getInstalledInfo(moduleName, bmadDir) {
+    const targetPath = path.join(bmadDir, moduleName);
+
+    if (!(await fs.pathExists(targetPath))) {
+      return null;
+    }
+
+    const configPath = path.join(targetPath, 'config.yaml');
+    const moduleInfo = {
+      id: moduleName,
+      path: targetPath,
+      installed: true,
+    };
+
+    if (await fs.pathExists(configPath)) {
+      try {
+        const configContent = await fs.readFile(configPath, 'utf8');
+        const config = yaml.parse(configContent);
+        Object.assign(moduleInfo, config);
+      } catch (error) {
+        await prompts.log.warn(`Failed to read installed module config: ${error.message}`);
+      }
+    }
+
+    return moduleInfo;
+  }
+
+  /**
+   * Copy module with filtering for localskip agents and conditional content
+   * @param {string} sourcePath - Source module path
+   * @param {string} targetPath - Target module path
+   * @param {Function} fileTrackingCallback - Optional callback to track installed files
+   * @param {Object} moduleConfig - Module configuration with conditional flags
+   */
+  async copyModuleWithFiltering(sourcePath, targetPath, fileTrackingCallback = null, moduleConfig = {}) {
+    // Get all files in source
+    const sourceFiles = await this.getFileList(sourcePath);
+
+    for (const file of sourceFiles) {
+      // Skip sub-modules directory - these are IDE-specific and handled separately
+      if (file.startsWith('sub-modules/')) {
+        continue;
+      }
+
+      // Skip sidecar directories - these contain agent-specific assets not needed at install time
+      const isInSidecarDirectory = path
+        .dirname(file)
+        .split('/')
+        .some((dir) => dir.toLowerCase().endsWith('-sidecar'));
+
+      if (isInSidecarDirectory) {
+        continue;
+      }
+
+      // Skip module.yaml at root - it's only needed at install time
+      if (file === 'module.yaml') {
+        continue;
+      }
+
+      // Skip module root config.yaml only - generated by config collector with actual values
+      // Workflow-level config.yaml (e.g. workflows/orchestrate-story/config.yaml) must be copied
+      // for custom modules that use workflow-specific configuration
+      if (file === 'config.yaml') {
+        continue;
+      }
+
+      const sourceFile = path.join(sourcePath, file);
+      const targetFile = path.join(targetPath, file);
+
+      // Check if this is an agent file
+      if (file.startsWith('agents/') && file.endsWith('.md')) {
+        // Read the file to check for localskip
+        const content = await fs.readFile(sourceFile, 'utf8');
+
+        // Check for localskip="true" in the agent tag
+        const agentMatch = content.match(/<agent[^>]*\slocalskip="true"[^>]*>/);
+        if (agentMatch) {
+          await prompts.log.message(`  Skipping web-only agent: ${path.basename(file)}`);
+          continue; // Skip this agent
+        }
+      }
+
+      // Copy the file with placeholder replacement
+      await this.copyFile(sourceFile, targetFile);
+
+      // Track the file if callback provided
+      if (fileTrackingCallback) {
+        fileTrackingCallback(targetFile);
+      }
+    }
+  }
+
+  /**
+   * Find all .md agent files recursively in a directory
+   * @param {string} dir - Directory to search
+   * @returns {Array} List of .md agent file paths
+   */
+  async findAgentMdFiles(dir) {
+    const agentFiles = [];
+
+    async function searchDirectory(searchDir) {
+      const entries = await fs.readdir(searchDir, { withFileTypes: true });
+
+      for (const entry of entries) {
+        const fullPath = path.join(searchDir, entry.name);
+
+        if (entry.isFile() && entry.name.endsWith('.md')) {
+          agentFiles.push(fullPath);
+        } else if (entry.isDirectory()) {
+          await searchDirectory(fullPath);
+        }
+      }
+    }
+
+    await searchDirectory(dir);
+    return agentFiles;
+  }
+
+  /**
+   * Create directories declared in module.yaml's `directories` key
+   * This replaces the security-risky module installer pattern with declarative config
+   * During updates, if a directory path changed, moves the old directory to the new path
+   * @param {string} moduleName - Name of the module
+   * @param {string} bmadDir - Target bmad directory
+   * @param {Object} options - Installation options
+   * @param {Object} options.moduleConfig - Module configuration from config collector
+   * @param {Object} options.existingModuleConfig - Previous module config (for detecting path changes during updates)
+   * @param {Object} options.coreConfig - Core configuration
+   * @returns {Promise<{createdDirs: string[], movedDirs: string[], createdWdsFolders: string[]}>} Created directories info
+   */
+  async createModuleDirectories(moduleName, bmadDir, options = {}) {
+    const moduleConfig = options.moduleConfig || {};
+    const existingModuleConfig = options.existingModuleConfig || {};
+    const projectRoot = path.dirname(bmadDir);
+    const emptyResult = { createdDirs: [], movedDirs: [], createdWdsFolders: [] };
+
+    // Special handling for core module - it's in src/core-skills not src/modules
+    let sourcePath;
+    if (moduleName === 'core') {
+      sourcePath = getSourcePath('core-skills');
+    } else {
+      sourcePath = await this.findModuleSource(moduleName, { silent: true });
+      if (!sourcePath) {
+        return emptyResult; // No source found, skip
+      }
+    }
+
+    // Read module.yaml to find the `directories` key
+    const moduleYamlPath = path.join(sourcePath, 'module.yaml');
+    if (!(await fs.pathExists(moduleYamlPath))) {
+      return emptyResult; // No module.yaml, skip
+    }
+
+    let moduleYaml;
+    try {
+      const yamlContent = await fs.readFile(moduleYamlPath, 'utf8');
+      moduleYaml = yaml.parse(yamlContent);
+    } catch (error) {
+      await prompts.log.warn(`Invalid module.yaml for ${moduleName}: ${error.message}`);
+      return emptyResult;
+    }
+
+    if (!moduleYaml || !moduleYaml.directories) {
+      return emptyResult; // No directories declared, skip
+    }
+
+    const directories = moduleYaml.directories;
+    const wdsFolders = moduleYaml.wds_folders || [];
+    const createdDirs = [];
+    const movedDirs = [];
+    const createdWdsFolders = [];
+
+    for (const dirRef of directories) {
+      // Parse variable reference like "{design_artifacts}"
+      const varMatch = dirRef.match(/^\{([^}]+)\}$/);
+      if (!varMatch) {
+        // Not a variable reference, skip
+        continue;
+      }
+
+      const configKey = varMatch[1];
+      const dirValue = moduleConfig[configKey];
+      if (!dirValue || typeof dirValue !== 'string') {
+        continue; // No value or not a string, skip
+      }
+
+      // Strip {project-root}/ prefix if present
+      let dirPath = dirValue.replace(/^\{project-root\}\/?/, '');
+
+      // Handle remaining {project-root} anywhere in the path
+      dirPath = dirPath.replaceAll('{project-root}', '');
+
+      // Resolve to absolute path
+      const fullPath = path.join(projectRoot, dirPath);
+
+      // Validate path is within project root (prevent directory traversal)
+      const normalizedPath = path.normalize(fullPath);
+      const normalizedRoot = path.normalize(projectRoot);
+      if (!normalizedPath.startsWith(normalizedRoot + path.sep) && normalizedPath !== normalizedRoot) {
+        const color = await prompts.getColor();
+        await prompts.log.warn(color.yellow(`${configKey} path escapes project root, skipping: ${dirPath}`));
+        continue;
+      }
+
+      // Check if directory path changed from previous config (update/modify scenario)
+      const oldDirValue = existingModuleConfig[configKey];
+      let oldFullPath = null;
+      let oldDirPath = null;
+      if (oldDirValue && typeof oldDirValue === 'string') {
+        // F3: Normalize both values before comparing to avoid false negatives
+        // from trailing slashes, separator differences, or prefix format variations
+        let normalizedOld = oldDirValue.replace(/^\{project-root\}\/?/, '');
+        normalizedOld = path.normalize(normalizedOld.replaceAll('{project-root}', ''));
+        const normalizedNew = path.normalize(dirPath);
+
+        if (normalizedOld !== normalizedNew) {
+          oldDirPath = normalizedOld;
+          oldFullPath = path.join(projectRoot, oldDirPath);
+          const normalizedOldAbsolute = path.normalize(oldFullPath);
+          if (!normalizedOldAbsolute.startsWith(normalizedRoot + path.sep) && normalizedOldAbsolute !== normalizedRoot) {
+            oldFullPath = null; // Old path escapes project root, ignore it
+          }
+
+          // F13: Prevent parent/child move (e.g. docs/planning → docs/planning/v2)
+          if (oldFullPath) {
+            const normalizedNewAbsolute = path.normalize(fullPath);
+            if (
+              normalizedOldAbsolute.startsWith(normalizedNewAbsolute + path.sep) ||
+              normalizedNewAbsolute.startsWith(normalizedOldAbsolute + path.sep)
+            ) {
+              const color = await prompts.getColor();
+              await prompts.log.warn(
+                color.yellow(
+                  `${configKey}: cannot move between parent/child paths (${oldDirPath} / ${dirPath}), creating new directory instead`,
+                ),
+              );
+              oldFullPath = null;
+            }
+          }
+        }
+      }
+
+      const dirName = configKey.replaceAll('_', ' ');
+
+      if (oldFullPath && (await fs.pathExists(oldFullPath)) && !(await fs.pathExists(fullPath))) {
+        // Path changed and old dir exists → move old to new location
+        // F1: Use fs.move() instead of fs.rename() for cross-device/volume support
+        // F2: Wrap in try/catch — fallback to creating new dir on failure
+        try {
+          await fs.ensureDir(path.dirname(fullPath));
+          await fs.move(oldFullPath, fullPath);
+          movedDirs.push(`${dirName}: ${oldDirPath} → ${dirPath}`);
+        } catch (moveError) {
+          const color = await prompts.getColor();
+          await prompts.log.warn(
+            color.yellow(
+              `Failed to move ${oldDirPath} → ${dirPath}: ${moveError.message}\n  Creating new directory instead. Please move contents from the old directory manually.`,
+            ),
+          );
+          await fs.ensureDir(fullPath);
+          createdDirs.push(`${dirName}: ${dirPath}`);
+        }
+      } else if (oldFullPath && (await fs.pathExists(oldFullPath)) && (await fs.pathExists(fullPath))) {
+        // F5: Both old and new directories exist — warn user about potential orphaned documents
+        const color = await prompts.getColor();
+        await prompts.log.warn(
+          color.yellow(
+            `${dirName}: path changed but both directories exist:\n  Old: ${oldDirPath}\n  New: ${dirPath}\n  Old directory may contain orphaned documents — please review and merge manually.`,
+          ),
+        );
+      } else if (!(await fs.pathExists(fullPath))) {
+        // New directory doesn't exist yet → create it
+        createdDirs.push(`${dirName}: ${dirPath}`);
+        await fs.ensureDir(fullPath);
+      }
+
+      // Create WDS subfolders if this is the design_artifacts directory
+      if (configKey === 'design_artifacts' && wdsFolders.length > 0) {
+        for (const subfolder of wdsFolders) {
+          const subPath = path.join(fullPath, subfolder);
+          if (!(await fs.pathExists(subPath))) {
+            await fs.ensureDir(subPath);
+            createdWdsFolders.push(subfolder);
+          }
+        }
+      }
+    }
+
+    return { createdDirs, movedDirs, createdWdsFolders };
+  }
+
+  /**
+   * Private: Process module configuration
+   * @param {string} modulePath - Path to installed module
+   * @param {string} moduleName - Module name
+   */
+  async processModuleConfig(modulePath, moduleName) {
+    const configPath = path.join(modulePath, 'config.yaml');
+
+    if (await fs.pathExists(configPath)) {
+      try {
+        let configContent = await fs.readFile(configPath, 'utf8');
+
+        // Replace path placeholders
+        configContent = configContent.replaceAll('{project-root}', `bmad/${moduleName}`);
+        configContent = configContent.replaceAll('{module}', moduleName);
+
+        await fs.writeFile(configPath, configContent, 'utf8');
+      } catch (error) {
+        await prompts.log.warn(`Failed to process module config: ${error.message}`);
+      }
+    }
+  }
+
+  /**
+   * Private: Sync module files (preserving user modifications)
+   * @param {string} sourcePath - Source module path
+   * @param {string} targetPath - Target module path
+   */
+  async syncModule(sourcePath, targetPath) {
+    // Get list of all source files
+    const sourceFiles = await this.getFileList(sourcePath);
+
+    for (const file of sourceFiles) {
+      const sourceFile = path.join(sourcePath, file);
+      const targetFile = path.join(targetPath, file);
+
+      // Check if target file exists and has been modified
+      if (await fs.pathExists(targetFile)) {
+        const sourceStats = await fs.stat(sourceFile);
+        const targetStats = await fs.stat(targetFile);
+
+        // Skip if target is newer (user modified)
+        if (targetStats.mtime > sourceStats.mtime) {
+          continue;
+        }
+      }
+
+      // Copy file with placeholder replacement
+      await this.copyFile(sourceFile, targetFile);
+    }
+  }
+
+  /**
+   * Private: Get list of all files in a directory
+   * @param {string} dir - Directory path
+   * @param {string} baseDir - Base directory for relative paths
+   * @returns {Array} List of relative file paths
+   */
+  async getFileList(dir, baseDir = dir) {
+    const files = [];
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      const fullPath = path.join(dir, entry.name);
+
+      if (entry.isDirectory()) {
+        const subFiles = await this.getFileList(fullPath, baseDir);
+        files.push(...subFiles);
+      } else {
+        files.push(path.relative(baseDir, fullPath));
+      }
+    }
+
+    return files;
+  }
+
+  // ─── Config collection methods (merged from ConfigCollector) ───
+
   /**
    * Find the bmad installation directory in a project
    * V6+ installations can use ANY folder name but ALWAYS have _config/manifest.yaml
@@ -95,7 +766,7 @@ class ConfigCollector {
    * @param {string} projectDir - Target project directory
    */
   async loadExistingConfig(projectDir) {
-    this.existingConfig = {};
+    this._existingConfig = {};
 
     // Check if project directory exists first
     if (!(await fs.pathExists(projectDir))) {
@@ -129,7 +800,7 @@ class ConfigCollector {
             const content = await fs.readFile(moduleConfigPath, 'utf8');
             const moduleConfig = yaml.parse(content);
             if (moduleConfig) {
-              this.existingConfig[entry.name] = moduleConfig;
+              this._existingConfig[entry.name] = moduleConfig;
               foundAny = true;
             }
           } catch {
@@ -153,7 +824,7 @@ class ConfigCollector {
     const results = [];
 
     for (const moduleName of modules) {
-      // Resolve module.yaml path - custom paths first, then standard location, then ModuleManager search
+      // Resolve module.yaml path - custom paths first, then standard location, then OfficialModules search
       let moduleConfigPath = null;
       const customPath = this.customModulePaths?.get(moduleName);
       if (customPath) {
@@ -163,7 +834,7 @@ class ConfigCollector {
         if (await fs.pathExists(standardPath)) {
           moduleConfigPath = standardPath;
         } else {
-          const moduleSourcePath = await this._getModuleManager().findModuleSource(moduleName, { silent: true });
+          const moduleSourcePath = await this.findModuleSource(moduleName, { silent: true });
           if (moduleSourcePath) {
             moduleConfigPath = path.join(moduleSourcePath, 'module.yaml');
           }
@@ -349,7 +1020,7 @@ class ConfigCollector {
     this.currentProjectDir = projectDir;
 
     // Load existing config if not already loaded
-    if (!this.existingConfig) {
+    if (!this._existingConfig) {
       await this.loadExistingConfig(projectDir);
     }
 
@@ -364,7 +1035,7 @@ class ConfigCollector {
 
     // If not found in src/modules, we need to find it by searching the project
     if (!(await fs.pathExists(moduleConfigPath))) {
-      const moduleSourcePath = await this._getModuleManager().findModuleSource(moduleName, { silent: true });
+      const moduleSourcePath = await this.findModuleSource(moduleName, { silent: true });
 
       if (moduleSourcePath) {
         moduleConfigPath = path.join(moduleSourcePath, 'module.yaml');
@@ -378,7 +1049,7 @@ class ConfigCollector {
       configPath = moduleConfigPath;
     } else {
       // Check if this is a custom module with custom.yaml
-      const moduleSourcePath = await this._getModuleManager().findModuleSource(moduleName, { silent: true });
+      const moduleSourcePath = await this.findModuleSource(moduleName, { silent: true });
 
       if (moduleSourcePath) {
         const rootCustomConfigPath = path.join(moduleSourcePath, 'custom.yaml');
@@ -391,11 +1062,11 @@ class ConfigCollector {
       }
 
       // No config schema for this module - use existing values
-      if (this.existingConfig && this.existingConfig[moduleName]) {
+      if (this._existingConfig && this._existingConfig[moduleName]) {
         if (!this.collectedConfig[moduleName]) {
           this.collectedConfig[moduleName] = {};
         }
-        this.collectedConfig[moduleName] = { ...this.existingConfig[moduleName] };
+        this.collectedConfig[moduleName] = { ...this._existingConfig[moduleName] };
       }
       return false;
     }
@@ -409,7 +1080,7 @@ class ConfigCollector {
 
     // Compare schema with existing config to find new/missing fields
     const configKeys = Object.keys(moduleConfig).filter((key) => key !== 'prompt');
-    const existingKeys = this.existingConfig && this.existingConfig[moduleName] ? Object.keys(this.existingConfig[moduleName]) : [];
+    const existingKeys = this._existingConfig && this._existingConfig[moduleName] ? Object.keys(this._existingConfig[moduleName]) : [];
 
     // Check if this module has no configuration keys at all (like CIS)
     // Filter out metadata fields and only count actual config objects
@@ -440,11 +1111,11 @@ class ConfigCollector {
 
     // If in silent mode and no new keys (neither interactive nor static), use existing config and skip prompts
     if (silentMode && newKeys.length === 0 && newStaticKeys.length === 0) {
-      if (this.existingConfig && this.existingConfig[moduleName]) {
+      if (this._existingConfig && this._existingConfig[moduleName]) {
         if (!this.collectedConfig[moduleName]) {
           this.collectedConfig[moduleName] = {};
         }
-        this.collectedConfig[moduleName] = { ...this.existingConfig[moduleName] };
+        this.collectedConfig[moduleName] = { ...this._existingConfig[moduleName] };
 
         // Special handling for user_name: ensure it has a value
         if (
@@ -455,7 +1126,7 @@ class ConfigCollector {
         }
 
         // Also populate allAnswers for cross-referencing
-        for (const [key, value] of Object.entries(this.existingConfig[moduleName])) {
+        for (const [key, value] of Object.entries(this._existingConfig[moduleName])) {
           // Ensure user_name is properly set in allAnswers too
           let finalValue = value;
           if (moduleName === 'core' && key === 'user_name' && (!value || value === '[USER_NAME]')) {
@@ -519,8 +1190,8 @@ class ConfigCollector {
 
       // Process all answers (both static and prompted)
       // First, copy existing config to preserve values that aren't being updated
-      if (this.existingConfig && this.existingConfig[moduleName]) {
-        this.collectedConfig[moduleName] = { ...this.existingConfig[moduleName] };
+      if (this._existingConfig && this._existingConfig[moduleName]) {
+        this.collectedConfig[moduleName] = { ...this._existingConfig[moduleName] };
       } else {
         this.collectedConfig[moduleName] = {};
       }
@@ -545,11 +1216,11 @@ class ConfigCollector {
     }
 
     // Copy over existing values for fields that weren't prompted
-    if (this.existingConfig && this.existingConfig[moduleName]) {
+    if (this._existingConfig && this._existingConfig[moduleName]) {
       if (!this.collectedConfig[moduleName]) {
         this.collectedConfig[moduleName] = {};
       }
-      for (const [key, value] of Object.entries(this.existingConfig[moduleName])) {
+      for (const [key, value] of Object.entries(this._existingConfig[moduleName])) {
         if (!this.collectedConfig[moduleName][key]) {
           this.collectedConfig[moduleName][key] = value;
           this.allAnswers[`${moduleName}_${key}`] = value;
@@ -652,7 +1323,7 @@ class ConfigCollector {
   async collectModuleConfig(moduleName, projectDir, skipLoadExisting = false, skipCompletion = false) {
     this.currentProjectDir = projectDir;
     // Load existing config if needed and not already loaded
-    if (!skipLoadExisting && !this.existingConfig) {
+    if (!skipLoadExisting && !this._existingConfig) {
       await this.loadExistingConfig(projectDir);
     }
 
@@ -674,7 +1345,7 @@ class ConfigCollector {
 
     // If not found in src/modules or custom paths, search the project
     if (!(await fs.pathExists(moduleConfigPath))) {
-      const moduleSourcePath = await this._getModuleManager().findModuleSource(moduleName, { silent: true });
+      const moduleSourcePath = await this.findModuleSource(moduleName, { silent: true });
 
       if (moduleSourcePath) {
         moduleConfigPath = path.join(moduleSourcePath, 'module.yaml');
@@ -994,8 +1665,8 @@ class ConfigCollector {
     }
 
     // Prefer the current module's persisted value when re-prompting an existing install
-    if (!configValue && currentModule && this.existingConfig?.[currentModule]?.[configKey] !== undefined) {
-      configValue = this.existingConfig[currentModule][configKey];
+    if (!configValue && currentModule && this._existingConfig?.[currentModule]?.[configKey] !== undefined) {
+      configValue = this._existingConfig[currentModule][configKey];
     }
 
     // Check in already collected config
@@ -1009,10 +1680,10 @@ class ConfigCollector {
     }
 
     // Fall back to other existing module config values
-    if (!configValue && this.existingConfig) {
-      for (const mod of Object.keys(this.existingConfig)) {
-        if (mod !== '_meta' && this.existingConfig[mod] && this.existingConfig[mod][configKey]) {
-          configValue = this.existingConfig[mod][configKey];
+    if (!configValue && this._existingConfig) {
+      for (const mod of Object.keys(this._existingConfig)) {
+        if (mod !== '_meta' && this._existingConfig[mod] && this._existingConfig[mod][configKey]) {
+          configValue = this._existingConfig[mod][configKey];
           break;
         }
       }
@@ -1083,8 +1754,8 @@ class ConfigCollector {
 
     // Check for existing value
     let existingValue = null;
-    if (this.existingConfig && this.existingConfig[moduleName]) {
-      existingValue = this.existingConfig[moduleName][key];
+    if (this._existingConfig && this._existingConfig[moduleName]) {
+      existingValue = this._existingConfig[moduleName][key];
       existingValue = this.normalizeExistingValueForPrompt(existingValue, moduleName, item, moduleConfig);
     }
 
@@ -1369,4 +2040,4 @@ class ConfigCollector {
   }
 }
 
-module.exports = { ConfigCollector };
+module.exports = { OfficialModules };