bmad-method 6.2.3-next.25 → 6.2.3-next.26

package/tools/installer/core/custom-module-cache.js

@@ -1,260 +0,0 @@
-/**
- * Custom Module Source Cache
- * Caches custom module sources under _config/custom/ to ensure they're never lost
- * and can be checked into source control
- */
-
-const fs = require('fs-extra');
-const path = require('node:path');
-const crypto = require('node:crypto');
-const prompts = require('../prompts');
-
-class CustomModuleCache {
-  constructor(bmadDir) {
-    this.bmadDir = bmadDir;
-    this.customCacheDir = path.join(bmadDir, '_config', 'custom');
-    this.manifestPath = path.join(this.customCacheDir, 'cache-manifest.yaml');
-  }
-
-  /**
-   * Ensure the custom cache directory exists
-   */
-  async ensureCacheDir() {
-    await fs.ensureDir(this.customCacheDir);
-  }
-
-  /**
-   * Get cache manifest
-   */
-  async getCacheManifest() {
-    if (!(await fs.pathExists(this.manifestPath))) {
-      return {};
-    }
-
-    const content = await fs.readFile(this.manifestPath, 'utf8');
-    const yaml = require('yaml');
-    return yaml.parse(content) || {};
-  }
-
-  /**
-   * Update cache manifest
-   */
-  async updateCacheManifest(manifest) {
-    const yaml = require('yaml');
-    // Clean the manifest to remove any non-serializable values
-    const cleanManifest = structuredClone(manifest);
-
-    const content = yaml.stringify(cleanManifest, {
-      indent: 2,
-      lineWidth: 0,
-      sortKeys: false,
-    });
-
-    await fs.writeFile(this.manifestPath, content);
-  }
-
-  /**
-   * Stream a file into the hash to avoid loading entire file into memory
-   */
-  async hashFileStream(filePath, hash) {
-    return new Promise((resolve, reject) => {
-      const stream = require('node:fs').createReadStream(filePath);
-      stream.on('data', (chunk) => hash.update(chunk));
-      stream.on('end', resolve);
-      stream.on('error', reject);
-    });
-  }
-
-  /**
-   * Calculate hash of a file or directory using streaming to minimize memory usage
-   */
-  async calculateHash(sourcePath) {
-    const hash = crypto.createHash('sha256');
-
-    const isDir = (await fs.stat(sourcePath)).isDirectory();
-
-    if (isDir) {
-      // For directories, hash all files
-      const files = [];
-      async function collectFiles(dir) {
-        const entries = await fs.readdir(dir, { withFileTypes: true });
-        for (const entry of entries) {
-          if (entry.isFile()) {
-            files.push(path.join(dir, entry.name));
-          } else if (entry.isDirectory() && !entry.name.startsWith('.')) {
-            await collectFiles(path.join(dir, entry.name));
-          }
-        }
-      }
-
-      await collectFiles(sourcePath);
-      files.sort(); // Ensure consistent order
-
-      for (const file of files) {
-        const relativePath = path.relative(sourcePath, file);
-        // Hash the path first, then stream file contents
-        hash.update(relativePath + '|');
-        await this.hashFileStream(file, hash);
-      }
-    } else {
-      // For single files, stream directly into hash
-      await this.hashFileStream(sourcePath, hash);
-    }
-
-    return hash.digest('hex');
-  }
-
-  /**
-   * Cache a custom module source
-   * @param {string} moduleId - Module ID
-   * @param {string} sourcePath - Original source path
-   * @param {Object} metadata - Additional metadata to store
-   * @returns {Object} Cached module info
-   */
-  async cacheModule(moduleId, sourcePath, metadata = {}) {
-    await this.ensureCacheDir();
-
-    const cacheDir = path.join(this.customCacheDir, moduleId);
-    const cacheManifest = await this.getCacheManifest();
-
-    // Check if already cached and unchanged
-    if (cacheManifest[moduleId]) {
-      const cached = cacheManifest[moduleId];
-      if (cached.originalHash && cached.originalHash === (await this.calculateHash(sourcePath))) {
-        // Source unchanged, return existing cache info
-        return {
-          moduleId,
-          cachePath: cacheDir,
-          ...cached,
-        };
-      }
-    }
-
-    // Remove existing cache if it exists
-    if (await fs.pathExists(cacheDir)) {
-      await fs.remove(cacheDir);
-    }
-
-    // Copy module to cache
-    await fs.copy(sourcePath, cacheDir, {
-      filter: (src) => {
-        const relative = path.relative(sourcePath, src);
-        // Skip node_modules, .git, and other common ignore patterns
-        return !relative.includes('node_modules') && !relative.startsWith('.git') && !relative.startsWith('.DS_Store');
-      },
-    });
-
-    // Calculate hash of the source
-    const sourceHash = await this.calculateHash(sourcePath);
-    const cacheHash = await this.calculateHash(cacheDir);
-
-    // Update manifest - don't store absolute paths for portability
-    // Clean metadata to remove absolute paths
-    const cleanMetadata = { ...metadata };
-    if (cleanMetadata.sourcePath) {
-      delete cleanMetadata.sourcePath;
-    }
-
-    cacheManifest[moduleId] = {
-      originalHash: sourceHash,
-      cacheHash: cacheHash,
-      cachedAt: new Date().toISOString(),
-      ...cleanMetadata,
-    };
-
-    await this.updateCacheManifest(cacheManifest);
-
-    return {
-      moduleId,
-      cachePath: cacheDir,
-      ...cacheManifest[moduleId],
-    };
-  }
-
-  /**
-   * Get cached module info
-   * @param {string} moduleId - Module ID
-   * @returns {Object|null} Cached module info or null
-   */
-  async getCachedModule(moduleId) {
-    const cacheManifest = await this.getCacheManifest();
-    const cached = cacheManifest[moduleId];
-
-    if (!cached) {
-      return null;
-    }
-
-    const cacheDir = path.join(this.customCacheDir, moduleId);
-
-    if (!(await fs.pathExists(cacheDir))) {
-      // Cache dir missing, remove from manifest
-      delete cacheManifest[moduleId];
-      await this.updateCacheManifest(cacheManifest);
-      return null;
-    }
-
-    // Verify cache integrity
-    const currentCacheHash = await this.calculateHash(cacheDir);
-    if (currentCacheHash !== cached.cacheHash) {
-      await prompts.log.warn(`Cache integrity check failed for ${moduleId}`);
-    }
-
-    return {
-      moduleId,
-      cachePath: cacheDir,
-      ...cached,
-    };
-  }
-
-  /**
-   * Get all cached modules
-   * @returns {Array} Array of cached module info
-   */
-  async getAllCachedModules() {
-    const cacheManifest = await this.getCacheManifest();
-    const cached = [];
-
-    for (const [moduleId, info] of Object.entries(cacheManifest)) {
-      const cachedModule = await this.getCachedModule(moduleId);
-      if (cachedModule) {
-        cached.push(cachedModule);
-      }
-    }
-
-    return cached;
-  }
-
-  /**
-   * Remove a cached module
-   * @param {string} moduleId - Module ID to remove
-   */
-  async removeCachedModule(moduleId) {
-    const cacheManifest = await this.getCacheManifest();
-    const cacheDir = path.join(this.customCacheDir, moduleId);
-
-    // Remove cache directory
-    if (await fs.pathExists(cacheDir)) {
-      await fs.remove(cacheDir);
-    }
-
-    // Remove from manifest
-    delete cacheManifest[moduleId];
-    await this.updateCacheManifest(cacheManifest);
-  }
-
-  /**
-   * Sync cached modules with a list of module IDs
-   * @param {Array<string>} moduleIds - Module IDs to keep
-   */
-  async syncCache(moduleIds) {
-    const cached = await this.getAllCachedModules();
-
-    for (const cachedModule of cached) {
-      if (!moduleIds.includes(cachedModule.moduleId)) {
-        await this.removeCachedModule(cachedModule.moduleId);
-      }
-    }
-  }
-}
-
-module.exports = { CustomModuleCache };

package/tools/installer/custom-handler.js

@@ -1,112 +0,0 @@
-const path = require('node:path');
-const fs = require('fs-extra');
-const yaml = require('yaml');
-const prompts = require('./prompts');
-/**
- * Handler for custom content (custom.yaml)
- * Discovers custom agents and workflows in the project
- */
-class CustomHandler {
-  /**
-   * Find all custom.yaml files in the project
-   * @param {string} projectRoot - Project root directory
-   * @returns {Array} List of custom content paths
-   */
-  async findCustomContent(projectRoot) {
-    const customPaths = [];
-
-    // Helper function to recursively scan directories
-    async function scanDirectory(dir, excludePaths = []) {
-      try {
-        const entries = await fs.readdir(dir, { withFileTypes: true });
-
-        for (const entry of entries) {
-          const fullPath = path.join(dir, entry.name);
-
-          // Skip hidden directories and common exclusions
-          if (
-            entry.name.startsWith('.') ||
-            entry.name === 'node_modules' ||
-            entry.name === 'dist' ||
-            entry.name === 'build' ||
-            entry.name === '.git' ||
-            entry.name === 'bmad'
-          ) {
-            continue;
-          }
-
-          // Skip excluded paths
-          if (excludePaths.some((exclude) => fullPath.startsWith(exclude))) {
-            continue;
-          }
-
-          if (entry.isDirectory()) {
-            // Recursively scan subdirectories
-            await scanDirectory(fullPath, excludePaths);
-          } else if (entry.name === 'custom.yaml') {
-            // Found a custom.yaml file
-            customPaths.push(fullPath);
-          } else if (
-            entry.name === 'module.yaml' && // Check if this is a custom module (in root directory)
-            // Skip if it's in src/modules (those are standard modules)
-            !fullPath.includes(path.join('src', 'modules'))
-          ) {
-            customPaths.push(fullPath);
-          }
-        }
-      } catch {
-        // Ignore errors (e.g., permission denied)
-      }
-    }
-
-    // Scan the entire project, but exclude source directories
-    await scanDirectory(projectRoot, [path.join(projectRoot, 'src'), path.join(projectRoot, 'tools'), path.join(projectRoot, 'test')]);
-
-    return customPaths;
-  }
-
-  /**
-   * Get custom content info from a custom.yaml or module.yaml file
-   * @param {string} configPath - Path to config file
-   * @param {string} projectRoot - Project root directory for calculating relative paths
-   * @returns {Object|null} Custom content info
-   */
-  async getCustomInfo(configPath, projectRoot = null) {
-    try {
-      const configContent = await fs.readFile(configPath, 'utf8');
-
-      // Try to parse YAML with error handling
-      let config;
-      try {
-        config = yaml.parse(configContent);
-      } catch (parseError) {
-        await prompts.log.warn('YAML parse error in ' + configPath + ': ' + parseError.message);
-        return null;
-      }
-
-      // Check if this is an module.yaml (module) or custom.yaml (custom content)
-      const isInstallConfig = configPath.endsWith('module.yaml');
-      const configDir = path.dirname(configPath);
-
-      // Use provided projectRoot or fall back to process.cwd()
-      const basePath = projectRoot || process.cwd();
-      const relativePath = path.relative(basePath, configDir);
-
-      return {
-        id: config.code || 'unknown-code',
-        name: config.name,
-        description: config.description || '',
-        path: configDir,
-        relativePath: relativePath,
-        defaultSelected: config.default_selected === true,
-        config: config,
-        isInstallConfig: isInstallConfig, // Track which type this is
-      };
-    } catch (error) {
-      await prompts.log.warn('Failed to read ' + configPath + ': ' + error.message);
-      return null;
-    }
-  }
-}
-
-module.exports = { CustomHandler };

package/tools/installer/modules/custom-modules.js

@@ -1,302 +0,0 @@
-const path = require('node:path');
-const fs = require('fs-extra');
-const yaml = require('yaml');
-const { CustomHandler } = require('../custom-handler');
-const { Manifest } = require('../core/manifest');
-const prompts = require('../prompts');
-
-class CustomModules {
-  constructor() {
-    this.paths = new Map();
-  }
-
-  has(moduleCode) {
-    return this.paths.has(moduleCode);
-  }
-
-  get(moduleCode) {
-    return this.paths.get(moduleCode);
-  }
-
-  set(moduleId, sourcePath) {
-    this.paths.set(moduleId, sourcePath);
-  }
-
-  /**
-   * Install a custom module from its source path.
-   * @param {string} moduleName - Module identifier
-   * @param {string} bmadDir - Target bmad directory
-   * @param {Function} fileTrackingCallback - Optional callback to track installed files
-   * @param {Object} options - Install options
-   * @param {Object} options.moduleConfig - Pre-collected module configuration
-   * @returns {Object} Install result
-   */
-  async install(moduleName, bmadDir, fileTrackingCallback = null, options = {}) {
-    const sourcePath = this.paths.get(moduleName);
-    if (!sourcePath) {
-      throw new Error(`No source path for custom module '${moduleName}'`);
-    }
-
-    if (!(await fs.pathExists(sourcePath))) {
-      throw new Error(`Source for custom module '${moduleName}' not found at: ${sourcePath}`);
-    }
-
-    const targetPath = path.join(bmadDir, moduleName);
-
-    // Read custom.yaml and merge into module config
-    let moduleConfig = options.moduleConfig ? { ...options.moduleConfig } : {};
-    const customConfigPath = path.join(sourcePath, 'custom.yaml');
-    if (await fs.pathExists(customConfigPath)) {
-      try {
-        const content = await fs.readFile(customConfigPath, 'utf8');
-        const customConfig = yaml.parse(content);
-        if (customConfig) {
-          moduleConfig = { ...moduleConfig, ...customConfig };
-        }
-      } catch (error) {
-        await prompts.log.warn(`Failed to read custom.yaml for ${moduleName}: ${error.message}`);
-      }
-    }
-
-    // Remove existing installation
-    if (await fs.pathExists(targetPath)) {
-      await fs.remove(targetPath);
-    }
-
-    // Copy files with filtering
-    await this._copyWithFiltering(sourcePath, targetPath, fileTrackingCallback);
-
-    // Add to manifest
-    const manifest = new Manifest();
-    const versionInfo = await manifest.getModuleVersionInfo(moduleName, bmadDir, sourcePath);
-    await manifest.addModule(bmadDir, moduleName, {
-      version: versionInfo.version,
-      source: versionInfo.source,
-      npmPackage: versionInfo.npmPackage,
-      repoUrl: versionInfo.repoUrl,
-    });
-
-    return { success: true, module: moduleName, path: targetPath, moduleConfig };
-  }
-
-  /**
-   * Copy module files, filtering out install-time-only artifacts.
-   * @param {string} sourcePath - Source module directory
-   * @param {string} targetPath - Target module directory
-   * @param {Function} fileTrackingCallback - Optional callback to track installed files
-   */
-  async _copyWithFiltering(sourcePath, targetPath, fileTrackingCallback = null) {
-    const files = await this._getFileList(sourcePath);
-
-    for (const file of files) {
-      if (file.startsWith('sub-modules/')) continue;
-
-      const isInSidecar = path
-        .dirname(file)
-        .split('/')
-        .some((dir) => dir.toLowerCase().endsWith('-sidecar'));
-      if (isInSidecar) continue;
-
-      if (file === 'module.yaml') continue;
-      if (file === 'config.yaml') continue;
-
-      const sourceFile = path.join(sourcePath, file);
-      const targetFile = path.join(targetPath, file);
-
-      // Skip web-only agents
-      if (file.startsWith('agents/') && file.endsWith('.md')) {
-        const content = await fs.readFile(sourceFile, 'utf8');
-        if (/<agent[^>]*\slocalskip="true"[^>]*>/.test(content)) {
-          continue;
-        }
-      }
-
-      await fs.ensureDir(path.dirname(targetFile));
-      await fs.copy(sourceFile, targetFile, { overwrite: true });
-
-      if (fileTrackingCallback) {
-        fileTrackingCallback(targetFile);
-      }
-    }
-  }
-
-  /**
-   * Recursively list all files in a directory.
-   * @param {string} dir - Directory to scan
-   * @param {string} baseDir - Base directory for relative paths
-   * @returns {string[]} 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()) {
-        files.push(...(await this._getFileList(fullPath, baseDir)));
-      } else {
-        files.push(path.relative(baseDir, fullPath));
-      }
-    }
-
-    return files;
-  }
-
-  /**
-   * Discover custom module source paths from all available sources.
-   * @param {Object} config - Installation configuration
-   * @param {Object} paths - InstallPaths instance
-   * @returns {Map<string, string>} Map of module ID to source path
-   */
-  async discoverPaths(config, paths) {
-    this.paths = new Map();
-
-    if (config._quickUpdate) {
-      if (config._customModuleSources) {
-        for (const [moduleId, customInfo] of config._customModuleSources) {
-          this.paths.set(moduleId, customInfo.sourcePath);
-        }
-      }
-      return this.paths;
-    }
-
-    // From UI: selectedFiles
-    if (config.customContent && config.customContent.selected && config.customContent.selectedFiles) {
-      const customHandler = new CustomHandler();
-      for (const customFile of config.customContent.selectedFiles) {
-        const customInfo = await customHandler.getCustomInfo(customFile, paths.projectRoot);
-        if (customInfo && customInfo.id) {
-          this.paths.set(customInfo.id, customInfo.path);
-        }
-      }
-    }
-
-    // From UI: sources
-    if (config.customContent && config.customContent.sources) {
-      for (const source of config.customContent.sources) {
-        this.paths.set(source.id, source.path);
-      }
-    }
-
-    // From UI: cachedModules
-    if (config.customContent && config.customContent.cachedModules) {
-      const selectedCachedIds = config.customContent.selectedCachedModules || [];
-      const shouldIncludeAll = selectedCachedIds.length === 0 && config.customContent.selected;
-
-      for (const cachedModule of config.customContent.cachedModules) {
-        if (cachedModule.id && cachedModule.cachePath && (shouldIncludeAll || selectedCachedIds.includes(cachedModule.id))) {
-          this.paths.set(cachedModule.id, cachedModule.cachePath);
-        }
-      }
-    }
-
-    return this.paths;
-  }
-
-  /**
-   * Assemble quick-update source candidates before install() hands them to discoverPaths().
-   * This exists because discoverPaths() consumes already-prepared quick-update sources,
-   * while quickUpdate() still has to build that source map from manifest, explicit inputs,
-   * and cache conventions.
-   * Precedence: manifest-backed paths, explicit sources override them, then cached modules.
-   * @param {Object} config - Quick update configuration
-   * @param {Object} existingInstall - Existing installation snapshot
-   * @param {string} bmadDir - BMAD directory
-   * @param {Object} externalModuleManager - External module manager
-   * @returns {Promise<Map<string, Object>>} Map of custom module ID to source info
-   */
-  async assembleQuickUpdateSources(config, existingInstall, bmadDir, externalModuleManager) {
-    const projectRoot = path.dirname(bmadDir);
-    const customModuleSources = new Map();
-
-    if (existingInstall.customModules) {
-      for (const customModule of existingInstall.customModules) {
-        // Skip if no ID - can't reliably track or re-cache without it
-        if (!customModule?.id) continue;
-
-        let sourcePath = customModule.sourcePath;
-        if (sourcePath && sourcePath.startsWith('_config')) {
-          // Paths are relative to BMAD dir, but we want absolute paths for install
-          sourcePath = path.join(bmadDir, sourcePath);
-        } else if (!sourcePath && customModule.relativePath) {
-          // Fall back to relativePath
-          sourcePath = path.resolve(projectRoot, customModule.relativePath);
-        } else if (sourcePath && !path.isAbsolute(sourcePath)) {
-          // If we have a sourcePath but it's not absolute, resolve it relative to project root
-          sourcePath = path.resolve(projectRoot, sourcePath);
-        }
-
-        // If we still don't have a valid source path, skip this module
-        if (!sourcePath || !(await fs.pathExists(sourcePath))) {
-          continue;
-        }
-
-        customModuleSources.set(customModule.id, {
-          id: customModule.id,
-          name: customModule.name || customModule.id,
-          sourcePath,
-          relativePath: customModule.relativePath,
-          cached: false,
-        });
-      }
-    }
-
-    if (config.customContent?.sources?.length > 0) {
-      for (const source of config.customContent.sources) {
-        if (source.id && source.path) {
-          customModuleSources.set(source.id, {
-            id: source.id,
-            name: source.name || source.id,
-            sourcePath: source.path,
-            cached: false, // From CLI, will be re-cached
-          });
-        }
-      }
-    }
-
-    const cacheDir = path.join(bmadDir, '_config', 'custom');
-    if (!(await fs.pathExists(cacheDir))) {
-      return customModuleSources;
-    }
-
-    const cachedModules = await fs.readdir(cacheDir, { withFileTypes: true });
-    for (const cachedModule of cachedModules) {
-      const moduleId = cachedModule.name;
-      const cachedPath = path.join(cacheDir, moduleId);
-
-      // Skip if path doesn't exist (broken symlink, deleted dir) - avoids lstat ENOENT
-      if (!(await fs.pathExists(cachedPath))) {
-        continue;
-      }
-      if (!cachedModule.isDirectory()) {
-        continue;
-      }
-
-      // Skip if we already have this module from manifest
-      if (customModuleSources.has(moduleId)) {
-        continue;
-      }
-
-      // Check if this is an external official module - skip cache for those
-      const isExternal = await externalModuleManager.hasModule(moduleId);
-      if (isExternal) {
-        continue;
-      }
-
-      // Check if this is actually a custom module (has module.yaml)
-      const moduleYamlPath = path.join(cachedPath, 'module.yaml');
-      if (await fs.pathExists(moduleYamlPath)) {
-        customModuleSources.set(moduleId, {
-          id: moduleId,
-          name: moduleId,
-          sourcePath: cachedPath,
-          cached: true,
-        });
-      }
-    }
-
-    return customModuleSources;
-  }
-}
-
-module.exports = { CustomModules };