bmad-fh 6.0.0-alpha.23

package/tools/cli/lib/agent/template-engine.js

@@ -0,0 +1,152 @@
+/**
+ * Template Engine for BMAD Agent Install Configuration
+ * Processes {{variable}}, {{#if}}, {{#unless}}, and {{/if}} blocks
+ */
+
+/**
+ * Process all template syntax in a string
+ * @param {string} content - Content with template syntax
+ * @param {Object} variables - Key-value pairs from install_config answers
+ * @returns {string} Processed content
+ */
+function processTemplate(content, variables = {}) {
+  let result = content;
+
+  // Process conditionals first (they may contain variables)
+  result = processConditionals(result, variables);
+
+  // Then process simple variable replacements
+  result = processVariables(result, variables);
+
+  // Clean up any empty lines left by removed conditionals
+  result = cleanupEmptyLines(result);
+
+  return result;
+}
+
+/**
+ * Process {{#if}}, {{#unless}}, {{/if}}, {{/unless}} blocks
+ */
+function processConditionals(content, variables) {
+  let result = content;
+
+  // Process {{#if variable == "value"}} blocks
+  // Handle both regular quotes and JSON-escaped quotes (\")
+  const ifEqualsPattern = /\{\{#if\s+(\w+)\s*==\s*\\?"([^"\\]+)\\?"\s*\}\}([\s\S]*?)\{\{\/if\}\}/g;
+  result = result.replaceAll(ifEqualsPattern, (match, varName, value, block) => {
+    return variables[varName] === value ? block : '';
+  });
+
+  // Process {{#if variable}} blocks (boolean or truthy check)
+  const ifBoolPattern = /\{\{#if\s+(\w+)\s*\}\}([\s\S]*?)\{\{\/if\}\}/g;
+  result = result.replaceAll(ifBoolPattern, (match, varName, block) => {
+    const val = variables[varName];
+    // Treat as truthy: true, non-empty string, non-zero number
+    const isTruthy = val === true || (typeof val === 'string' && val.length > 0) || (typeof val === 'number' && val !== 0);
+    return isTruthy ? block : '';
+  });
+
+  // Process {{#unless variable}} blocks (inverse of if)
+  const unlessPattern = /\{\{#unless\s+(\w+)\s*\}\}([\s\S]*?)\{\{\/unless\}\}/g;
+  result = result.replaceAll(unlessPattern, (match, varName, block) => {
+    const val = variables[varName];
+    const isFalsy = val === false || val === '' || val === null || val === undefined || val === 0;
+    return isFalsy ? block : '';
+  });
+
+  return result;
+}
+
+/**
+ * Process {{variable}} replacements
+ */
+function processVariables(content, variables) {
+  let result = content;
+
+  // Replace {{variable}} with value
+  const varPattern = /\{\{(\w+)\}\}/g;
+  result = result.replaceAll(varPattern, (match, varName) => {
+    if (Object.hasOwn(variables, varName)) {
+      return String(variables[varName]);
+    }
+    // If variable not found, leave as-is (might be runtime variable like {user_name})
+    return match;
+  });
+
+  return result;
+}
+
+/**
+ * Clean up excessive empty lines left after removing conditional blocks
+ */
+function cleanupEmptyLines(content) {
+  // Replace 3+ consecutive newlines with 2
+  return content.replaceAll(/\n{3,}/g, '\n\n');
+}
+
+/**
+ * Extract install_config from agent YAML object
+ * @param {Object} agentYaml - Parsed agent YAML
+ * @returns {Object|null} install_config section or null
+ */
+function extractInstallConfig(agentYaml) {
+  return agentYaml?.agent?.install_config || null;
+}
+
+/**
+ * Remove install_config from agent YAML (after processing)
+ * @param {Object} agentYaml - Parsed agent YAML
+ * @returns {Object} Agent YAML without install_config
+ */
+function stripInstallConfig(agentYaml) {
+  const result = structuredClone(agentYaml);
+  if (result.agent) {
+    delete result.agent.install_config;
+  }
+  return result;
+}
+
+/**
+ * Process entire agent YAML object with template variables
+ * @param {Object} agentYaml - Parsed agent YAML
+ * @param {Object} variables - Answers from install_config questions
+ * @returns {Object} Processed agent YAML
+ */
+function processAgentYaml(agentYaml, variables) {
+  // Convert to JSON string, process templates, parse back
+  const jsonString = JSON.stringify(agentYaml, null, 2);
+  const processed = processTemplate(jsonString, variables);
+  return JSON.parse(processed);
+}
+
+/**
+ * Get default values from install_config questions
+ * @param {Object} installConfig - install_config section
+ * @returns {Object} Default values keyed by variable name
+ */
+function getDefaultValues(installConfig) {
+  const defaults = {};
+
+  if (!installConfig?.questions) {
+    return defaults;
+  }
+
+  for (const question of installConfig.questions) {
+    if (question.var && question.default !== undefined) {
+      defaults[question.var] = question.default;
+    }
+  }
+
+  return defaults;
+}
+
+module.exports = {
+  processTemplate,
+  processConditionals,
+  processVariables,
+  extractInstallConfig,
+  stripInstallConfig,
+  processAgentYaml,
+  getDefaultValues,
+  cleanupEmptyLines,
+};

package/tools/cli/lib/agent-analyzer.js

@@ -0,0 +1,109 @@
+const yaml = require('yaml');
+const fs = require('fs-extra');
+
+/**
+ * Analyzes agent YAML files to detect which handlers are needed
+ */
+class AgentAnalyzer {
+  /**
+   * Analyze an agent YAML structure to determine which handlers it needs
+   * @param {Object} agentYaml - Parsed agent YAML object
+   * @returns {Object} Profile of needed handlers
+   */
+  analyzeAgentObject(agentYaml) {
+    const profile = {
+      usedAttributes: new Set(),
+      hasPrompts: false,
+      menuItems: [],
+    };
+
+    // Check if agent has prompts section
+    if (agentYaml.agent && agentYaml.agent.prompts) {
+      profile.hasPrompts = true;
+    }
+
+    // Analyze menu items (support both 'menu' and legacy 'commands')
+    const menuItems = agentYaml.agent?.menu || agentYaml.agent?.commands || [];
+
+    for (const item of menuItems) {
+      // Track the menu item
+      profile.menuItems.push(item);
+
+      // Check for multi format items
+      if (item.multi && item.triggers) {
+        profile.usedAttributes.add('multi');
+
+        // Also check attributes in nested handlers
+        for (const triggerGroup of item.triggers) {
+          for (const [triggerName, execArray] of Object.entries(triggerGroup)) {
+            if (Array.isArray(execArray)) {
+              for (const exec of execArray) {
+                if (exec.route) {
+                  // Check if route is a workflow or exec
+                  if (exec.route.endsWith('.yaml') || exec.route.endsWith('.yml')) {
+                    profile.usedAttributes.add('workflow');
+                  } else {
+                    profile.usedAttributes.add('exec');
+                  }
+                }
+                if (exec.workflow) profile.usedAttributes.add('workflow');
+                if (exec.action) profile.usedAttributes.add('action');
+                if (exec.type && ['exec', 'action', 'workflow'].includes(exec.type)) {
+                  profile.usedAttributes.add(exec.type);
+                }
+              }
+            }
+          }
+        }
+      } else {
+        // Check for each possible attribute in legacy items
+        if (item.workflow) {
+          profile.usedAttributes.add('workflow');
+        }
+        if (item['validate-workflow']) {
+          profile.usedAttributes.add('validate-workflow');
+        }
+        if (item.exec) {
+          profile.usedAttributes.add('exec');
+        }
+        if (item.tmpl) {
+          profile.usedAttributes.add('tmpl');
+        }
+        if (item.data) {
+          profile.usedAttributes.add('data');
+        }
+        if (item.action) {
+          profile.usedAttributes.add('action');
+        }
+      }
+    }
+
+    // Convert Set to Array for easier use
+    profile.usedAttributes = [...profile.usedAttributes];
+
+    return profile;
+  }
+
+  /**
+   * Analyze an agent YAML file
+   * @param {string} filePath - Path to agent YAML file
+   * @returns {Object} Profile of needed handlers
+   */
+  async analyzeAgentFile(filePath) {
+    const content = await fs.readFile(filePath, 'utf8');
+    const agentYaml = yaml.parse(content);
+    return this.analyzeAgentObject(agentYaml);
+  }
+
+  /**
+   * Check if an agent needs a specific handler
+   * @param {Object} profile - Agent profile from analyze
+   * @param {string} handlerType - Handler type to check
+   * @returns {boolean} True if handler is needed
+   */
+  needsHandler(profile, handlerType) {
+    return profile.usedAttributes.includes(handlerType);
+  }
+}
+
+module.exports = { AgentAnalyzer };

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

@@ -0,0 +1,194 @@
+const path = require('node:path');
+const fs = require('fs-extra');
+const { escapeXml } = require('../../lib/xml-utils');
+
+const AgentPartyGenerator = {
+  /**
+   * Generate agent-manifest.csv 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/_config/agent-manifest.csv" 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>${escapeXml(agent.role || '')}</role>
+      <identity>${escapeXml(agent.identity || '')}</identity>
+      <communication_style>${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] : '';
+  },
+
+  /**
+   * 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-manifest.csv 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 };

package/tools/cli/lib/cli-utils.js

@@ -0,0 +1,227 @@
+const chalk = require('chalk');
+const boxen = require('boxen');
+const wrapAnsi = require('wrap-ansi');
+const figlet = require('figlet');
+const path = require('node:path');
+const os = require('node:os');
+
+const CLIUtils = {
+  /**
+   * Get version from package.json
+   */
+  getVersion() {
+    try {
+      const packageJson = require(path.join(__dirname, '..', '..', '..', 'package.json'));
+      return packageJson.version || 'Unknown';
+    } catch {
+      return 'Unknown';
+    }
+  },
+
+  /**
+   * Display BMAD logo
+   * @param {boolean} clearScreen - Whether to clear the screen first (default: true for initial display only)
+   */
+  displayLogo(clearScreen = true) {
+    if (clearScreen) {
+      console.clear();
+    }
+
+    const version = this.getVersion();
+
+    // ASCII art logo
+    const logo = `
+    ██████╗ ███╗   ███╗ █████╗ ██████╗ ™
+    ██╔══██╗████╗ ████║██╔══██╗██╔══██╗
+    ██████╔╝██╔████╔██║███████║██║  ██║
+    ██╔══██╗██║╚██╔╝██║██╔══██║██║  ██║
+    ██████╔╝██║ ╚═╝ ██║██║  ██║██████╔╝
+    ╚═════╝ ╚═╝     ╚═╝╚═╝  ╚═╝╚═════╝`;
+
+    console.log(chalk.cyan(logo));
+    console.log(chalk.dim(`    Build More, Architect Dreams`) + chalk.cyan.bold(` v${version}`) + '\n');
+  },
+
+  /**
+   * Display section header
+   * @param {string} title - Section title
+   * @param {string} subtitle - Optional subtitle
+   */
+  displaySection(title, subtitle = null) {
+    console.log('\n' + chalk.cyan('═'.repeat(80)));
+    console.log(chalk.cyan.bold(` ${title}`));
+    if (subtitle) {
+      console.log(chalk.dim(` ${subtitle}`));
+    }
+    console.log(chalk.cyan('═'.repeat(80)) + '\n');
+  },
+
+  /**
+   * Display info box
+   * @param {string|Array} content - Content to display
+   * @param {Object} options - Box options
+   */
+  displayBox(content, options = {}) {
+    const defaultOptions = {
+      padding: 1,
+      margin: 1,
+      borderStyle: 'round',
+      borderColor: 'cyan',
+      ...options,
+    };
+
+    // Handle array content
+    let text = content;
+    if (Array.isArray(content)) {
+      text = content.join('\n\n');
+    }
+
+    // Wrap text to prevent overflow
+    const wrapped = wrapAnsi(text, 76, { hard: true, wordWrap: true });
+
+    console.log(boxen(wrapped, defaultOptions));
+  },
+
+  /**
+   * Display module configuration header
+   * @param {string} moduleName - Module name (fallback if no custom header)
+   * @param {string} header - Custom header from module.yaml
+   * @param {string} subheader - Custom subheader from module.yaml
+   */
+  displayModuleConfigHeader(moduleName, header = null, subheader = null) {
+    // Simple blue banner with custom header/subheader if provided
+    console.log('\n' + chalk.cyan('─'.repeat(80)));
+    console.log(chalk.cyan(header || `Configuring ${moduleName.toUpperCase()} Module`));
+    if (subheader) {
+      console.log(chalk.dim(`${subheader}`));
+    }
+    console.log(chalk.cyan('─'.repeat(80)) + '\n');
+  },
+
+  /**
+   * Display module with no custom configuration
+   * @param {string} moduleName - Module name (fallback if no custom header)
+   * @param {string} header - Custom header from module.yaml
+   * @param {string} subheader - Custom subheader from module.yaml
+   */
+  displayModuleNoConfig(moduleName, header = null, subheader = null) {
+    // Show full banner with header/subheader, just like modules with config
+    console.log('\n' + chalk.cyan('─'.repeat(80)));
+    console.log(chalk.cyan(header || `${moduleName.toUpperCase()} Module - No Custom Configuration`));
+    if (subheader) {
+      console.log(chalk.dim(`${subheader}`));
+    }
+    console.log(chalk.cyan('─'.repeat(80)) + '\n');
+  },
+
+  /**
+   * Display step indicator
+   * @param {number} current - Current step
+   * @param {number} total - Total steps
+   * @param {string} description - Step description
+   */
+  displayStep(current, total, description) {
+    const progress = `[${current}/${total}]`;
+    console.log('\n' + chalk.cyan(progress) + ' ' + chalk.bold(description));
+    console.log(chalk.dim('─'.repeat(80 - progress.length - 1)) + '\n');
+  },
+
+  /**
+   * Display completion message
+   * @param {string} message - Completion message
+   */
+  displayComplete(message) {
+    console.log(
+      '\n' +
+        boxen(chalk.green('✨ ' + message), {
+          padding: 1,
+          margin: 1,
+          borderStyle: 'round',
+          borderColor: 'green',
+        }),
+    );
+  },
+
+  /**
+   * Display error message
+   * @param {string} message - Error message
+   */
+  displayError(message) {
+    console.log(
+      '\n' +
+        boxen(chalk.red('✗ ' + message), {
+          padding: 1,
+          margin: 1,
+          borderStyle: 'round',
+          borderColor: 'red',
+        }),
+    );
+  },
+
+  /**
+   * Format list for display
+   * @param {Array} items - Items to display
+   * @param {string} prefix - Item prefix
+   */
+  formatList(items, prefix = '•') {
+    return items.map((item) => `  ${prefix} ${item}`).join('\n');
+  },
+
+  /**
+   * Clear previous lines
+   * @param {number} lines - Number of lines to clear
+   */
+  clearLines(lines) {
+    for (let i = 0; i < lines; i++) {
+      process.stdout.moveCursor(0, -1);
+      process.stdout.clearLine(1);
+    }
+  },
+
+  /**
+   * Display table
+   * @param {Array} data - Table data
+   * @param {Object} options - Table options
+   */
+  displayTable(data, options = {}) {
+    const Table = require('cli-table3');
+    const table = new Table({
+      style: {
+        head: ['cyan'],
+        border: ['dim'],
+      },
+      ...options,
+    });
+
+    for (const row of data) table.push(row);
+    console.log(table.toString());
+  },
+
+  /**
+   * Display module completion message
+   * @param {string} moduleName - Name of the completed module
+   * @param {boolean} clearScreen - Whether to clear the screen first (deprecated, always false now)
+   */
+  displayModuleComplete(moduleName, clearScreen = false) {
+    // No longer clear screen or show boxes - just a simple completion message
+    // This is deprecated but kept for backwards compatibility
+  },
+
+  /**
+   * Expand path with ~ expansion
+   * @param {string} inputPath - Path to expand
+   * @returns {string} Expanded path
+   */
+  expandPath(inputPath) {
+    if (!inputPath) return inputPath;
+
+    // Expand ~ to home directory
+    if (inputPath.startsWith('~')) {
+      return path.join(os.homedir(), inputPath.slice(1));
+    }
+
+    return inputPath;
+  },
+};
+
+module.exports = { CLIUtils };