bmad-method 5.1.3 → 6.0.0-alpha.0

package/tools/cli/installers/lib/modules/manager.js

@@ -0,0 +1,452 @@
+const path = require('node:path');
+const fs = require('fs-extra');
+const yaml = require('js-yaml');
+const chalk = require('chalk');
+const { XmlHandler } = require('../../../lib/xml-handler');
+const { getProjectRoot, getSourcePath, getModulePath } = require('../../../lib/project-root');
+
+/**
+ * Manages the installation, updating, and removal of BMAD modules.
+ * Handles module discovery, dependency resolution, configuration processing,
+ * and agent file management including XML activation block injection.
+ *
+ * @class ModuleManager
+ * @requires fs-extra
+ * @requires js-yaml
+ * @requires chalk
+ * @requires XmlHandler
+ *
+ * @example
+ * const manager = new ModuleManager();
+ * const modules = await manager.listAvailable();
+ * await manager.install('core-module', '/path/to/bmad');
+ */
+class ModuleManager {
+  constructor() {
+    // Path to source modules directory
+    this.modulesSourcePath = getSourcePath('modules');
+    this.xmlHandler = new XmlHandler();
+  }
+
+  /**
+   * List all available modules
+   * @returns {Array} List of available modules with metadata
+   */
+  async listAvailable() {
+    const modules = [];
+
+    if (!(await fs.pathExists(this.modulesSourcePath))) {
+      console.warn(chalk.yellow('Warning: src/modules directory not found'));
+      return modules;
+    }
+
+    const entries = await fs.readdir(this.modulesSourcePath, { withFileTypes: true });
+
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        const modulePath = path.join(this.modulesSourcePath, entry.name);
+        // Check for new structure first
+        const installerConfigPath = path.join(modulePath, '_module-installer', 'install-menu-config.yaml');
+        // Fallback to old structure
+        const configPath = path.join(modulePath, 'config.yaml');
+
+        const moduleInfo = {
+          id: entry.name,
+          path: modulePath,
+          name: entry.name.toUpperCase(),
+          description: 'BMAD Module',
+          version: '5.0.0',
+        };
+
+        // Try to read module config for metadata (prefer new location)
+        const configToRead = (await fs.pathExists(installerConfigPath)) ? installerConfigPath : configPath;
+        if (await fs.pathExists(configToRead)) {
+          try {
+            const configContent = await fs.readFile(configToRead, 'utf8');
+            const config = yaml.load(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) {
+            console.warn(`Failed to read config for ${entry.name}:`, error.message);
+          }
+        }
+
+        modules.push(moduleInfo);
+      }
+    }
+
+    return modules;
+  }
+
+  /**
+   * Install a module
+   * @param {string} moduleName - Name of the module to install
+   * @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 = path.join(this.modulesSourcePath, moduleName);
+    const targetPath = path.join(bmadDir, moduleName);
+
+    // Check if source module exists
+    if (!(await fs.pathExists(sourcePath))) {
+      throw new Error(`Module '${moduleName}' not found in ${this.modulesSourcePath}`);
+    }
+
+    // Check if already installed
+    if (await fs.pathExists(targetPath)) {
+      console.log(chalk.yellow(`Module '${moduleName}' already installed, updating...`));
+      await fs.remove(targetPath);
+    }
+
+    // Copy module files with filtering
+    await this.copyModuleWithFiltering(sourcePath, targetPath, fileTrackingCallback);
+
+    // Process agent files to inject activation block
+    await this.processAgentFiles(targetPath, moduleName);
+
+    // Call module-specific installer if it exists (unless explicitly skipped)
+    if (!options.skipModuleInstaller) {
+      await this.runModuleInstaller(moduleName, bmadDir, options);
+    }
+
+    return {
+      success: true,
+      module: moduleName,
+      path: targetPath,
+    };
+  }
+
+  /**
+   * Update an existing module
+   * @param {string} moduleName - Name of the module to update
+   * @param {string} bmadDir - Target bmad directory
+   * @param {boolean} force - Force update (overwrite modifications)
+   */
+  async update(moduleName, bmadDir, force = false) {
+    const sourcePath = path.join(this.modulesSourcePath, moduleName);
+    const targetPath = path.join(bmadDir, moduleName);
+
+    // Check if source module exists
+    if (!(await fs.pathExists(sourcePath))) {
+      throw new Error(`Module '${moduleName}' not found in source`);
+    }
+
+    // Check if module is installed
+    if (!(await fs.pathExists(targetPath))) {
+      throw new Error(`Module '${moduleName}' is not installed`);
+    }
+
+    if (force) {
+      // Force update - remove and reinstall
+      await fs.remove(targetPath);
+      return await this.install(moduleName, bmadDir);
+    } else {
+      // Selective update - preserve user modifications
+      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.load(configContent);
+        Object.assign(moduleInfo, config);
+      } catch (error) {
+        console.warn(`Failed to read installed module config:`, error.message);
+      }
+    }
+
+    return moduleInfo;
+  }
+
+  /**
+   * Copy module with filtering for localskip agents
+   * @param {string} sourcePath - Source module path
+   * @param {string} targetPath - Target module path
+   */
+  async copyModuleWithFiltering(sourcePath, targetPath, fileTrackingCallback = null) {
+    // 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 _module-installer directory - it's only needed at install time
+      if (file.startsWith('_module-installer/')) {
+        continue;
+      }
+
+      // Skip config.yaml templates - we'll generate clean ones with actual values
+      if (file === 'config.yaml' || file.endsWith('/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) {
+          console.log(chalk.dim(`  Skipping web-only agent: ${path.basename(file)}`));
+          continue; // Skip this agent
+        }
+      }
+
+      // Copy the file
+      await fs.ensureDir(path.dirname(targetFile));
+      await fs.copy(sourceFile, targetFile, { overwrite: true });
+
+      // Track the file if callback provided
+      if (fileTrackingCallback) {
+        fileTrackingCallback(targetFile);
+      }
+    }
+  }
+
+  /**
+   * Process agent files to inject activation block
+   * @param {string} modulePath - Path to installed module
+   * @param {string} moduleName - Module name
+   */
+  async processAgentFiles(modulePath, moduleName) {
+    const agentsPath = path.join(modulePath, 'agents');
+
+    // Check if agents directory exists
+    if (!(await fs.pathExists(agentsPath))) {
+      return; // No agents to process
+    }
+
+    // Get all agent files
+    const agentFiles = await fs.readdir(agentsPath);
+
+    for (const agentFile of agentFiles) {
+      if (!agentFile.endsWith('.md')) continue;
+
+      const agentPath = path.join(agentsPath, agentFile);
+      let content = await fs.readFile(agentPath, 'utf8');
+
+      // Check if content has agent XML and no activation block
+      if (content.includes('<agent') && !content.includes('<activation')) {
+        // Inject the activation block using XML handler
+        content = this.xmlHandler.injectActivationSimple(content);
+        await fs.writeFile(agentPath, content, 'utf8');
+      }
+    }
+  }
+
+  /**
+   * Run module-specific installer if it exists
+   * @param {string} moduleName - Name of the module
+   * @param {string} bmadDir - Target bmad directory
+   * @param {Object} options - Installation options
+   */
+  async runModuleInstaller(moduleName, bmadDir, options = {}) {
+    // Special handling for core module - it's in src/core not src/modules
+    let sourcePath;
+    if (moduleName === 'core') {
+      sourcePath = getSourcePath('core');
+    } else {
+      sourcePath = path.join(this.modulesSourcePath, moduleName);
+    }
+
+    const installerPath = path.join(sourcePath, '_module-installer', 'installer.js');
+
+    // Check if module has a custom installer
+    if (!(await fs.pathExists(installerPath))) {
+      return; // No custom installer
+    }
+
+    try {
+      // Load the module installer
+      const moduleInstaller = require(installerPath);
+
+      if (typeof moduleInstaller.install === 'function') {
+        // Get project root (parent of bmad directory)
+        const projectRoot = path.dirname(bmadDir);
+
+        // Prepare logger (use console if not provided)
+        const logger = options.logger || {
+          log: console.log,
+          error: console.error,
+          warn: console.warn,
+        };
+
+        // Call the module installer
+        const result = await moduleInstaller.install({
+          projectRoot,
+          config: options.moduleConfig || {},
+          installedIDEs: options.installedIDEs || [],
+          logger,
+        });
+
+        if (!result) {
+          console.warn(chalk.yellow(`Module installer for ${moduleName} returned false`));
+        }
+      }
+    } catch (error) {
+      console.error(chalk.red(`Error running module installer for ${moduleName}: ${error.message}`));
+    }
+  }
+
+  /**
+   * 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) {
+        console.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
+      await fs.ensureDir(path.dirname(targetFile));
+      await fs.copy(sourceFile, targetFile, { overwrite: true });
+    }
+  }
+
+  /**
+   * 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()) {
+        // Skip _module-installer directories
+        if (entry.name === '_module-installer') {
+          continue;
+        }
+        const subFiles = await this.getFileList(fullPath, baseDir);
+        files.push(...subFiles);
+      } else {
+        files.push(path.relative(baseDir, fullPath));
+      }
+    }
+
+    return files;
+  }
+}
+
+module.exports = { ModuleManager };

package/tools/cli/lib/agent-party-generator.js

@@ -0,0 +1,206 @@
+const path = require('node:path');
+const fs = require('fs-extra');
+
+const AgentPartyGenerator = {
+  /**
+   * Generate agent-party.xml content
+   * @param {Array} agentDetails - Array of agent details
+   * @param {Object} options - Generation options
+   * @returns {string} XML content
+   */
+  generateAgentParty(agentDetails, options = {}) {
+    const { forWeb = false } = options;
+
+    // Group agents by module
+    const agentsByModule = {
+      bmm: [],
+      cis: [],
+      core: [],
+      custom: [],
+    };
+
+    for (const agent of agentDetails) {
+      const moduleKey = agentsByModule[agent.module] ? agent.module : 'custom';
+      agentsByModule[moduleKey].push(agent);
+    }
+
+    // Build XML content
+    let xmlContent = `<!-- Powered by BMAD-CORE™ -->
+<!-- Agent Manifest - Generated during BMAD ${forWeb ? 'bundling' : 'installation'} -->
+<!-- This file contains a summary of all ${forWeb ? 'bundled' : 'installed'} agents for quick reference -->
+<manifest id="bmad/_cfg/agent-party.xml" version="1.0" generated="${new Date().toISOString()}">
+  <description>
+    Complete roster of ${forWeb ? 'bundled' : 'installed'} BMAD agents with summarized personas for efficient multi-agent orchestration.
+    Used by party-mode and other multi-agent coordination features.
+  </description>
+`;
+
+    // Add agents by module
+    for (const [module, agents] of Object.entries(agentsByModule)) {
+      if (agents.length === 0) continue;
+
+      const moduleTitle =
+        module === 'bmm' ? 'BMM Module' : module === 'cis' ? 'CIS Module' : module === 'core' ? 'Core Module' : 'Custom Module';
+
+      xmlContent += `\n  <!-- ${moduleTitle} Agents -->\n`;
+
+      for (const agent of agents) {
+        xmlContent += `  <agent id="${agent.id}" name="${agent.name}" title="${agent.title || ''}" icon="${agent.icon || ''}">
+    <persona>
+      <role>${this.escapeXml(agent.role || '')}</role>
+      <identity>${this.escapeXml(agent.identity || '')}</identity>
+      <communication_style>${this.escapeXml(agent.communicationStyle || '')}</communication_style>
+      <principles>${agent.principles || ''}</principles>
+    </persona>
+  </agent>\n`;
+      }
+    }
+
+    // Add statistics
+    const totalAgents = agentDetails.length;
+    const moduleList = Object.keys(agentsByModule)
+      .filter((m) => agentsByModule[m].length > 0)
+      .join(', ');
+
+    xmlContent += `\n  <statistics>
+    <total_agents>${totalAgents}</total_agents>
+    <modules>${moduleList}</modules>
+    <last_updated>${new Date().toISOString()}</last_updated>
+  </statistics>
+</manifest>`;
+
+    return xmlContent;
+  },
+
+  /**
+   * Extract agent details from XML content
+   * @param {string} content - Full agent file content (markdown with XML)
+   * @param {string} moduleName - Module name
+   * @param {string} agentName - Agent name
+   * @returns {Object} Agent details
+   */
+  extractAgentDetails(content, moduleName, agentName) {
+    try {
+      // Extract agent XML block
+      const agentMatch = content.match(/<agent[^>]*>([\s\S]*?)<\/agent>/);
+      if (!agentMatch) return null;
+
+      const agentXml = agentMatch[0];
+
+      // Extract attributes from opening tag
+      const nameMatch = agentXml.match(/name="([^"]*)"/);
+      const titleMatch = agentXml.match(/title="([^"]*)"/);
+      const iconMatch = agentXml.match(/icon="([^"]*)"/);
+
+      // Extract persona elements - now we just copy them as-is
+      const roleMatch = agentXml.match(/<role>([\s\S]*?)<\/role>/);
+      const identityMatch = agentXml.match(/<identity>([\s\S]*?)<\/identity>/);
+      const styleMatch = agentXml.match(/<communication_style>([\s\S]*?)<\/communication_style>/);
+      const principlesMatch = agentXml.match(/<principles>([\s\S]*?)<\/principles>/);
+
+      return {
+        id: `bmad/${moduleName}/agents/${agentName}.md`,
+        name: nameMatch ? nameMatch[1] : agentName,
+        title: titleMatch ? titleMatch[1] : 'Agent',
+        icon: iconMatch ? iconMatch[1] : '🤖',
+        module: moduleName,
+        role: roleMatch ? roleMatch[1].trim() : '',
+        identity: identityMatch ? identityMatch[1].trim() : '',
+        communicationStyle: styleMatch ? styleMatch[1].trim() : '',
+        principles: principlesMatch ? principlesMatch[1].trim() : '',
+      };
+    } catch (error) {
+      console.error(`Error extracting details for agent ${agentName}:`, error);
+      return null;
+    }
+  },
+
+  /**
+   * Extract attribute from XML tag
+   */
+  extractAttribute(xml, tagName, attrName) {
+    const regex = new RegExp(`<${tagName}[^>]*\\s${attrName}="([^"]*)"`, 'i');
+    const match = xml.match(regex);
+    return match ? match[1] : '';
+  },
+
+  /**
+   * Escape XML special characters
+   */
+  escapeXml(text) {
+    if (!text) return '';
+    return text
+      .replaceAll('&', '&amp;')
+      .replaceAll('<', '&lt;')
+      .replaceAll('>', '&gt;')
+      .replaceAll('"', '&quot;')
+      .replaceAll("'", '&apos;');
+  },
+
+  /**
+   * Apply config overrides to agent details
+   * @param {Object} details - Original agent details
+   * @param {string} configContent - Config file content
+   * @returns {Object} Agent details with overrides applied
+   */
+  applyConfigOverrides(details, configContent) {
+    try {
+      // Extract agent-config XML block
+      const configMatch = configContent.match(/<agent-config>([\s\S]*?)<\/agent-config>/);
+      if (!configMatch) return details;
+
+      const configXml = configMatch[0];
+
+      // Extract override values
+      const nameMatch = configXml.match(/<name>([\s\S]*?)<\/name>/);
+      const titleMatch = configXml.match(/<title>([\s\S]*?)<\/title>/);
+      const roleMatch = configXml.match(/<role>([\s\S]*?)<\/role>/);
+      const identityMatch = configXml.match(/<identity>([\s\S]*?)<\/identity>/);
+      const styleMatch = configXml.match(/<communication_style>([\s\S]*?)<\/communication_style>/);
+      const principlesMatch = configXml.match(/<principles>([\s\S]*?)<\/principles>/);
+
+      // Apply overrides only if values are non-empty
+      if (nameMatch && nameMatch[1].trim()) {
+        details.name = nameMatch[1].trim();
+      }
+
+      if (titleMatch && titleMatch[1].trim()) {
+        details.title = titleMatch[1].trim();
+      }
+
+      if (roleMatch && roleMatch[1].trim()) {
+        details.role = roleMatch[1].trim();
+      }
+
+      if (identityMatch && identityMatch[1].trim()) {
+        details.identity = identityMatch[1].trim();
+      }
+
+      if (styleMatch && styleMatch[1].trim()) {
+        details.communicationStyle = styleMatch[1].trim();
+      }
+
+      if (principlesMatch && principlesMatch[1].trim()) {
+        // Principles are now just copied as-is (narrative paragraph)
+        details.principles = principlesMatch[1].trim();
+      }
+
+      return details;
+    } catch (error) {
+      console.error(`Error applying config overrides:`, error);
+      return details;
+    }
+  },
+
+  /**
+   * Write agent-party.xml to file
+   */
+  async writeAgentParty(filePath, agentDetails, options = {}) {
+    const content = this.generateAgentParty(agentDetails, options);
+    await fs.ensureDir(path.dirname(filePath));
+    await fs.writeFile(filePath, content, 'utf8');
+    return content;
+  },
+};
+
+module.exports = { AgentPartyGenerator };