bmad-method 6.0.0-alpha.12 → 6.0.0-alpha.14

package/tools/cli/lib/ui.js

@@ -1,3 +1,23 @@
+/**
+ * File: tools/cli/lib/ui.js
+ *
+ * BMAD Method - Business Model Agile Development Method
+ * Repository: https://github.com/paulpreibisch/BMAD-METHOD
+ *
+ * Copyright (c) 2025 Paul Preibisch
+ * Licensed under the Apache License, Version 2.0
+ *
+ * ---
+ *
+ * @fileoverview Interactive installation prompts and user input collection for BMAD CLI
+ * @context Guides users through installation configuration including core settings, modules, IDEs, and optional AgentVibes TTS
+ * @architecture Facade pattern - presents unified installation flow, delegates to Detector/ConfigCollector/IdeManager for specifics
+ * @dependencies inquirer (prompts), chalk (formatting), detector.js (existing installation detection)
+ * @entrypoints Called by install.js command via ui.promptInstall(), returns complete configuration object
+ * @patterns Progressive disclosure (prompts in order), early IDE selection (Windows compat), AgentVibes auto-detection
+ * @related installer.js (consumes config), AgentVibes#34 (TTS integration), promptAgentVibes()
+ */
+
 const chalk = require('chalk');
 const inquirer = require('inquirer');
 const path = require('node:path');
@@ -96,8 +116,21 @@ class UI {
 
     const { installedModuleIds } = await this.getExistingInstallation(confirmedDirectory);
     const coreConfig = await this.collectCoreConfig(confirmedDirectory);
-    const moduleChoices = await this.getModuleChoices(installedModuleIds);
-    const selectedModules = await this.selectModules(moduleChoices);
+
+    // Skip module selection during update/reinstall - keep existing modules
+    let selectedModules;
+    if (actionType === 'update' || actionType === 'reinstall') {
+      // Keep all existing installed modules during update/reinstall
+      selectedModules = [...installedModuleIds];
+      console.log(chalk.cyan('\n📦 Keeping existing modules: ') + selectedModules.join(', '));
+    } else {
+      // Only show module selection for new installs
+      const moduleChoices = await this.getModuleChoices(installedModuleIds);
+      selectedModules = await this.selectModules(moduleChoices);
+    }
+
+    // Prompt for AgentVibes TTS integration
+    const agentVibesConfig = await this.promptAgentVibes(confirmedDirectory);
 
     // Collect IDE tool selection AFTER configuration prompts (fixes Windows/PowerShell hang)
     // This allows text-based prompts to complete before the checkbox prompt
@@ -114,6 +147,8 @@ class UI {
       ides: toolSelection.ides,
       skipIde: toolSelection.skipIde,
       coreConfig: coreConfig, // Pass collected core config to installer
+      enableAgentVibes: agentVibesConfig.enabled, // AgentVibes TTS integration
+      agentVibesInstalled: agentVibesConfig.alreadyInstalled,
     };
   }
 
@@ -201,15 +236,51 @@ class UI {
 
     CLIUtils.displaySection('Tool Integration', 'Select AI coding assistants and IDEs to configure');
 
-    const answers = await inquirer.prompt([
-      {
-        type: 'checkbox',
-        name: 'ides',
-        message: 'Select tools to configure:',
-        choices: ideChoices,
-        pageSize: 15,
-      },
-    ]);
+    let answers;
+    let userConfirmedNoTools = false;
+
+    // Loop until user selects at least one tool OR explicitly confirms no tools
+    while (!userConfirmedNoTools) {
+      answers = await inquirer.prompt([
+        {
+          type: 'checkbox',
+          name: 'ides',
+          message: 'Select tools to configure:',
+          choices: ideChoices,
+          pageSize: 15,
+        },
+      ]);
+
+      // If tools were selected, we're done
+      if (answers.ides && answers.ides.length > 0) {
+        break;
+      }
+
+      // Warn that no tools were selected - users often miss the spacebar requirement
+      console.log();
+      console.log(chalk.red.bold('⚠️  WARNING: No tools were selected!'));
+      console.log(chalk.red('   You must press SPACEBAR to select items, then ENTER to confirm.'));
+      console.log(chalk.red('   Simply highlighting an item does NOT select it.'));
+      console.log();
+
+      const { goBack } = await inquirer.prompt([
+        {
+          type: 'confirm',
+          name: 'goBack',
+          message: chalk.yellow('Would you like to go back and select at least one tool?'),
+          default: true,
+        },
+      ]);
+
+      if (goBack) {
+        // Re-display the section header before looping back
+        console.log();
+        CLIUtils.displaySection('Tool Integration', 'Select AI coding assistants and IDEs to configure');
+      } else {
+        // User explicitly chose to proceed without tools
+        userConfirmedNoTools = true;
+      }
+    }
 
     return {
       ides: answers.ides || [],
@@ -302,11 +373,60 @@ class UI {
       `🔧 Tools Configured: ${result.ides?.length > 0 ? result.ides.join(', ') : 'none'}`,
     ];
 
+    // Add AgentVibes TTS info if enabled
+    if (result.agentVibesEnabled) {
+      summary.push(`🎤 AgentVibes TTS: Enabled`);
+    }
+
     CLIUtils.displayBox(summary.join('\n\n'), {
       borderColor: 'green',
       borderStyle: 'round',
     });
 
+    // Display TTS injection details if present
+    if (result.ttsInjectedFiles && result.ttsInjectedFiles.length > 0) {
+      console.log('\n' + chalk.cyan.bold('═══════════════════════════════════════════════════'));
+      console.log(chalk.cyan.bold('            AgentVibes TTS Injection Summary'));
+      console.log(chalk.cyan.bold('═══════════════════════════════════════════════════\n'));
+
+      // Explain what TTS injection is
+      console.log(chalk.white.bold('What is TTS Injection?\n'));
+      console.log(chalk.dim('  TTS (Text-to-Speech) injection adds voice instructions to BMAD agents,'));
+      console.log(chalk.dim('  enabling them to speak their responses aloud using AgentVibes.\n'));
+      console.log(chalk.dim('  Example: When you activate the PM agent, it will greet you with'));
+      console.log(chalk.dim('  spoken audio like "Hey! I\'m your Project Manager. How can I help?"\n'));
+
+      console.log(chalk.green(`✅ TTS injection applied to ${result.ttsInjectedFiles.length} file(s):\n`));
+
+      // Group by type
+      const partyModeFiles = result.ttsInjectedFiles.filter((f) => f.type === 'party-mode');
+      const agentTTSFiles = result.ttsInjectedFiles.filter((f) => f.type === 'agent-tts');
+
+      if (partyModeFiles.length > 0) {
+        console.log(chalk.yellow('  Party Mode (multi-agent conversations):'));
+        for (const file of partyModeFiles) {
+          console.log(chalk.dim(`    • ${file.path}`));
+        }
+      }
+
+      if (agentTTSFiles.length > 0) {
+        console.log(chalk.yellow('  Agent TTS (individual agent voices):'));
+        for (const file of agentTTSFiles) {
+          console.log(chalk.dim(`    • ${file.path}`));
+        }
+      }
+
+      // Show backup info and restore command
+      console.log('\n' + chalk.white.bold('Backups & Recovery:\n'));
+      console.log(chalk.dim('  Pre-injection backups are stored in:'));
+      console.log(chalk.cyan('    ~/.bmad-tts-backups/\n'));
+      console.log(chalk.dim('  To restore original files (removes TTS instructions):'));
+      console.log(chalk.cyan(`    bmad-tts-injector.sh --restore ${result.path}\n`));
+
+      console.log(chalk.cyan('💡 BMAD agents will now speak when activated!'));
+      console.log(chalk.dim('   Ensure AgentVibes is installed: https://agentvibes.org'));
+    }
+
     console.log('\n' + chalk.green.bold('✨ BMAD is ready to use!'));
   }
 
@@ -371,11 +491,13 @@ class UI {
     const availableModules = await moduleManager.listAvailable();
 
     const isNewInstallation = installedModuleIds.size === 0;
-    return availableModules.map((mod) => ({
-      name: mod.name,
+    const moduleChoices = availableModules.map((mod) => ({
+      name: mod.isCustom ? `${mod.name} ${chalk.red('(Custom)')}` : mod.name,
       value: mod.id,
       checked: isNewInstallation ? mod.defaultSelected || false : installedModuleIds.has(mod.id),
     }));
+
+    return moduleChoices;
   }
 
   /**
@@ -603,6 +725,140 @@ class UI {
     // Resolve to the absolute path relative to the current working directory
     return path.resolve(expanded);
   }
+
+  /**
+   * @function promptAgentVibes
+   * @intent Ask user if they want AgentVibes TTS integration during BMAD installation
+   * @why Enables optional voice features without forcing TTS on users who don't want it
+   * @param {string} projectDir - Absolute path to user's project directory
+   * @returns {Promise<Object>} Configuration object: { enabled: boolean, alreadyInstalled: boolean }
+   * @sideeffects None - pure user input collection, no files written
+   * @edgecases Shows warning if user enables TTS but AgentVibes not detected
+   * @calledby promptInstall() during installation flow, after core config, before IDE selection
+   * @calls checkAgentVibesInstalled(), inquirer.prompt(), chalk.green/yellow/dim()
+   *
+   * AI NOTE: This prompt is strategically positioned in installation flow:
+   * - AFTER core config (bmad_folder, user_name, etc)
+   * - BEFORE IDE selection (which can hang on Windows/PowerShell)
+   *
+   * Flow Logic:
+   * 1. Auto-detect if AgentVibes already installed (checks for hook files)
+   * 2. Show detection status to user (green checkmark or gray "not detected")
+   * 3. Prompt: "Enable AgentVibes TTS?" (defaults to true if detected)
+   * 4. If user says YES but AgentVibes NOT installed:
+   *    → Show warning with installation link (graceful degradation)
+   * 5. Return config to promptInstall(), which passes to installer.install()
+   *
+   * State Flow:
+   * promptAgentVibes() → { enabled, alreadyInstalled }
+   *                    ↓
+   * promptInstall() → config.enableAgentVibes
+   *                    ↓
+   * installer.install() → this.enableAgentVibes
+   *                    ↓
+   * processTTSInjectionPoints() → injects OR strips markers
+   *
+   * RELATED:
+   * ========
+   * - Detection: checkAgentVibesInstalled() - looks for bmad-speak.sh and play-tts.sh
+   * - Processing: installer.js::processTTSInjectionPoints()
+   * - Markers: src/core/workflows/party-mode/instructions.md:101, src/modules/bmm/agents/*.md
+   * - GitHub Issue: paulpreibisch/AgentVibes#36
+   */
+  async promptAgentVibes(projectDir) {
+    CLIUtils.displaySection('🎤 Voice Features', 'Enable TTS for multi-agent conversations');
+
+    // Check if AgentVibes is already installed
+    const agentVibesInstalled = await this.checkAgentVibesInstalled(projectDir);
+
+    if (agentVibesInstalled) {
+      console.log(chalk.green('  ✓ AgentVibes detected'));
+    } else {
+      console.log(chalk.dim('  AgentVibes not detected'));
+    }
+
+    const answers = await inquirer.prompt([
+      {
+        type: 'confirm',
+        name: 'enableTts',
+        message: 'Enable Agents to Speak Out loud (powered by Agent Vibes? Claude Code only currently)',
+        default: false, // Default to yes - recommended for best experience
+      },
+    ]);
+
+    if (answers.enableTts && !agentVibesInstalled) {
+      console.log(chalk.yellow('\n  ⚠️  AgentVibes not installed'));
+      console.log(chalk.dim('  Install AgentVibes separately to enable TTS:'));
+      console.log(chalk.dim('  https://github.com/paulpreibisch/AgentVibes\n'));
+    }
+
+    return {
+      enabled: answers.enableTts,
+      alreadyInstalled: agentVibesInstalled,
+    };
+  }
+
+  /**
+   * @function checkAgentVibesInstalled
+   * @intent Detect if AgentVibes TTS hooks are present in user's project
+   * @why Allows auto-enabling TTS and showing helpful installation guidance
+   * @param {string} projectDir - Absolute path to user's project directory
+   * @returns {Promise<boolean>} true if both required AgentVibes hooks exist, false otherwise
+   * @sideeffects None - read-only file existence checks
+   * @edgecases Returns false if either hook missing (both required for functional TTS)
+   * @calledby promptAgentVibes() to determine default value and show detection status
+   * @calls fs.pathExists() twice (bmad-speak.sh, play-tts.sh)
+   *
+   * AI NOTE: This checks for the MINIMUM viable AgentVibes installation.
+   *
+   * Required Files:
+   * ===============
+   * 1. .claude/hooks/bmad-speak.sh
+   *    - Maps agent display names → agent IDs → voice profiles
+   *    - Calls play-tts.sh with agent's assigned voice
+   *    - Created by AgentVibes installer
+   *
+   * 2. .claude/hooks/play-tts.sh
+   *    - Core TTS router (ElevenLabs or Piper)
+   *    - Provider-agnostic interface
+   *    - Required by bmad-speak.sh
+   *
+   * Why Both Required:
+   * ==================
+   * - bmad-speak.sh alone: No TTS backend
+   * - play-tts.sh alone: No BMAD agent voice mapping
+   * - Both together: Full party mode TTS integration
+   *
+   * Detection Strategy:
+   * ===================
+   * We use simple file existence (not version checks) because:
+   * - Fast and reliable
+   * - Works across all AgentVibes versions
+   * - User will discover version issues when TTS runs (fail-fast)
+   *
+   * PATTERN: Adding New Detection Criteria
+   * =======================================
+   * If future AgentVibes features require additional files:
+   * 1. Add new pathExists check to this function
+   * 2. Update documentation in promptAgentVibes()
+   * 3. Consider: should missing file prevent detection or just log warning?
+   *
+   * RELATED:
+   * ========
+   * - AgentVibes Installer: creates these hooks
+   * - bmad-speak.sh: calls play-tts.sh with agent voices
+   * - Party Mode: uses bmad-speak.sh for agent dialogue
+   */
+  async checkAgentVibesInstalled(projectDir) {
+    const fs = require('fs-extra');
+    const path = require('node:path');
+
+    // Check for AgentVibes hook files
+    const hookPath = path.join(projectDir, '.claude', 'hooks', 'bmad-speak.sh');
+    const playTtsPath = path.join(projectDir, '.claude', 'hooks', 'play-tts.sh');
+
+    return (await fs.pathExists(hookPath)) && (await fs.pathExists(playTtsPath));
+  }
 }
 
 module.exports = { UI };

package/tools/cli/lib/yaml-xml-builder.js

@@ -232,21 +232,6 @@ class YamlXmlBuilder {
     return xml;
   }
 
-  /**
-   * Build metadata comment
-   */
-  buildMetadataComment(metadata) {
-    const lines = ['<!-- BUILD-META', `  source: ${metadata.sourceFile || 'unknown'} (hash: ${metadata.sourceHash || 'unknown'})`];
-
-    if (metadata.customizeFile) {
-      lines.push(`  customize: ${metadata.customizeFile} (hash: ${metadata.customizeHash || 'unknown'})`);
-    }
-
-    lines.push(`  built: ${new Date().toISOString()}`, `  builder-version: ${metadata.builderVersion || '1.0.0'}`, '-->\n');
-
-    return lines.join('\n');
-  }
-
   /**
    * Build persona XML section
    */
@@ -342,14 +327,15 @@ class YamlXmlBuilder {
   /**
    * Build menu XML section (renamed from commands for clarity)
    * Auto-injects *help and *exit, adds * prefix to all triggers
+   * Supports both legacy format and new multi format with nested handlers
    * @param {Array} menuItems - Menu items from YAML
    * @param {boolean} forWebBundle - Whether building for web bundle
    */
   buildCommandsXml(menuItems, forWebBundle = false) {
     let xml = '  <menu>\n';
 
-    // Always inject *help first
-    xml += `    <item cmd="*help">Show numbered menu</item>\n`;
+    // Always inject menu display option first
+    xml += `    <item cmd="*menu">[M] Redisplay Menu Options</item>\n`;
 
     // Add user-defined menu items with * prefix
     if (menuItems && menuItems.length > 0) {
@@ -362,42 +348,140 @@ class YamlXmlBuilder {
         if (!forWebBundle && item['web-only'] === true) {
           continue;
         }
-        // Build command attributes - add * prefix if not present
-        let trigger = item.trigger || '';
-        if (!trigger.startsWith('*')) {
-          trigger = '*' + trigger;
+
+        // Handle multi format menu items with nested handlers
+        if (item.multi && item.triggers && Array.isArray(item.triggers)) {
+          xml += `    <item type="multi">${this.escapeXml(item.multi)}\n`;
+          xml += this.buildNestedHandlers(item.triggers);
+          xml += `    </item>\n`;
         }
+        // Handle legacy format menu items
+        else if (item.trigger) {
+          // For legacy items, keep using cmd with *<trigger> format
+          let trigger = item.trigger || '';
+          if (!trigger.startsWith('*')) {
+            trigger = '*' + trigger;
+          }
 
-        const attrs = [`cmd="${trigger}"`];
+          const attrs = [`cmd="${trigger}"`];
 
-        // Add handler attributes
-        // If workflow-install exists, use its value for workflow attribute (vendoring)
-        // workflow-install is build-time metadata - tells installer where to copy workflows
-        // The final XML should only have workflow pointing to the install location
-        if (item['workflow-install']) {
-          attrs.push(`workflow="${item['workflow-install']}"`);
-        } else if (item.workflow) {
-          attrs.push(`workflow="${item.workflow}"`);
-        }
+          // Add handler attributes
+          // If workflow-install exists, use its value for workflow attribute (vendoring)
+          // workflow-install is build-time metadata - tells installer where to copy workflows
+          // The final XML should only have workflow pointing to the install location
+          if (item['workflow-install']) {
+            attrs.push(`workflow="${item['workflow-install']}"`);
+          } else if (item.workflow) {
+            attrs.push(`workflow="${item.workflow}"`);
+          }
 
-        if (item['validate-workflow']) attrs.push(`validate-workflow="${item['validate-workflow']}"`);
-        if (item.exec) attrs.push(`exec="${item.exec}"`);
-        if (item.tmpl) attrs.push(`tmpl="${item.tmpl}"`);
-        if (item.data) attrs.push(`data="${item.data}"`);
-        if (item.action) attrs.push(`action="${item.action}"`);
+          if (item['validate-workflow']) attrs.push(`validate-workflow="${item['validate-workflow']}"`);
+          if (item.exec) attrs.push(`exec="${item.exec}"`);
+          if (item.tmpl) attrs.push(`tmpl="${item.tmpl}"`);
+          if (item.data) attrs.push(`data="${item.data}"`);
+          if (item.action) attrs.push(`action="${item.action}"`);
 
-        xml += `    <item ${attrs.join(' ')}>${this.escapeXml(item.description || '')}</item>\n`;
+          xml += `    <item ${attrs.join(' ')}>${this.escapeXml(item.description || '')}</item>\n`;
+        }
       }
     }
 
-    // Always inject *exit last
-    xml += `    <item cmd="*exit">Exit with confirmation</item>\n`;
+    // Always inject dismiss last
+    xml += `    <item cmd="*dismiss">[D] Dismiss Agent</item>\n`;
 
     xml += '  </menu>\n';
 
     return xml;
   }
 
+  /**
+   * Build nested handlers for multi format menu items
+   * @param {Array} triggers - Triggers array from multi format
+   * @returns {string} Handler XML
+   */
+  buildNestedHandlers(triggers) {
+    let xml = '';
+
+    for (const triggerGroup of triggers) {
+      for (const [triggerName, execArray] of Object.entries(triggerGroup)) {
+        // Build trigger with * prefix
+        let trigger = triggerName.startsWith('*') ? triggerName : '*' + triggerName;
+
+        // Extract the relevant execution data
+        const execData = this.processExecArray(execArray);
+
+        // For nested handlers in multi items, we don't need cmd attribute
+        // The match attribute will handle fuzzy matching
+        const attrs = [`match="${this.escapeXml(execData.description || '')}"`];
+
+        // Add handler attributes based on exec data
+        if (execData.route) attrs.push(`exec="${execData.route}"`);
+        if (execData.workflow) attrs.push(`workflow="${execData.workflow}"`);
+        if (execData['validate-workflow']) attrs.push(`validate-workflow="${execData['validate-workflow']}"`);
+        if (execData.action) attrs.push(`action="${execData.action}"`);
+        if (execData.data) attrs.push(`data="${execData.data}"`);
+        if (execData.tmpl) attrs.push(`tmpl="${execData.tmpl}"`);
+        // Only add type if it's not 'exec' (exec is already implied by the exec attribute)
+        if (execData.type && execData.type !== 'exec') attrs.push(`type="${execData.type}"`);
+
+        xml += `      <handler ${attrs.join(' ')}></handler>\n`;
+      }
+    }
+
+    return xml;
+  }
+
+  /**
+   * Process the execution array from multi format triggers
+   * Extracts relevant data for XML attributes
+   * @param {Array} execArray - Array of execution objects
+   * @returns {Object} Processed execution data
+   */
+  processExecArray(execArray) {
+    const result = {
+      description: '',
+      route: null,
+      workflow: null,
+      data: null,
+      action: null,
+      type: null,
+    };
+
+    if (!Array.isArray(execArray)) {
+      return result;
+    }
+
+    for (const exec of execArray) {
+      if (exec.input) {
+        // Use input as description if no explicit description is provided
+        result.description = exec.input;
+      }
+
+      if (exec.route) {
+        // Determine if it's a workflow or exec based on file extension or context
+        if (exec.route.endsWith('.yaml') || exec.route.endsWith('.yml')) {
+          result.workflow = exec.route;
+        } else {
+          result.route = exec.route;
+        }
+      }
+
+      if (exec.data !== null && exec.data !== undefined) {
+        result.data = exec.data;
+      }
+
+      if (exec.action) {
+        result.action = exec.action;
+      }
+
+      if (exec.type) {
+        result.type = exec.type;
+      }
+    }
+
+    return result;
+  }
+
   /**
    * Escape XML special characters
    */

package/tools/platform-codes.yaml

@@ -55,6 +55,12 @@ platforms:
     category: ide
     description: "Enhanced Cline fork"
 
+  rovo:
+    name: "Rovo Dev"
+    preferred: false
+    category: ide
+    description: "Atlassian's AI coding assistant"
+
   github-copilot:
     name: "GitHub Copilot"
     preferred: false
@@ -97,6 +103,12 @@ platforms:
     category: ide
     description: "AI development assistant"
 
+  antigravity:
+    name: "Google Antigravity"
+    preferred: false
+    category: ide
+    description: "Google's AI development environment"
+
   trae:
     name: "Trae"
     preferred: false