bmad-method 6.0.0-alpha.19 → 6.0.0-alpha.20

package/tools/cli/installers/install-messages.yaml

@@ -0,0 +1,52 @@
+# BMAD Installer Messages
+# These messages are displayed during installation
+# Edit this file to change what users see during the install process
+
+# Display at the START of installation (after logo, before prompts)
+startMessage: |
+  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  🎉🎉 Happy Holidays and New Year 🍾🍾
+
+  IMPORTANT Changes with Version Alpha.20 - PLEASE READ THIS if upgrading from earlier Alpha Versions:
+
+  1. The BMad Core default output folder has changed from docs to `_bmad-output`. `docs` is meant for long-term artifacts, which you can always decide to move content to.
+
+  2. If utilizing the BMad Method Module (BMM) please be aware of the following important recent changes:
+
+  - Phases 1-3 (Analysis, Planning, Solutioning) will now default output to _bmad-output/planning-artifacts
+  - Phase 4 (Implementation) will now default output to _bmad-output/implementation-artifacts
+  - Long term project knowledge (research, docs, references, document-project output) will now default to docs/
+
+  IT IS STRONGLY SUGGESTED to align with these folder conventions instead of dumping all to docs/ - if you are upgrading from a prior
+  version where all output was going to docs or docs/sprint-artifacts, it is suggested to reset configs to these new values.
+
+  If you have anything in progress, you can move what was in sprint-artifacts to _bmad-output/implementation-artifacts, and if you had brainstorming
+  content, a PRD, UX or Architecture, you can move the content to _bmad-output/planning-artifacts.
+
+  Read the latest updates before continuing:
+  https://github.com/bmad-code-org/BMAD-METHOD/blob/main/CHANGELOG.md
+
+  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+# Display at the END of installation (after all setup completes)
+endMessage: |
+  ════════════════════════════════════════════════════════════════════════════════
+
+  ✨ BMAD IS READY TO USE!
+
+  ONE FINAL NOTE WITH VERSION Alpha.20: Phase 4 (Implementation) is still in the process of being migrated to the improved workflow progressive disclosure system.
+  Along with this, the full conversion to the new path locations for content being searched may possibly be incomplete. If you run a workflow that relies on finding input documents automatically, and you notice they are not being found / looking in the wrong location, either:
+  1. Manually specify the correct input location when prompted
+  2. Open an issue on GitHub so we can address the problem quickly if you think its a bug.
+  3. Ensure your content is in the new locations for best results:
+     - Planning Artifacts (Phases 1-3): _bmad-output/planning-artifacts
+     - Implementation Artifacts (Phase 4): _bmad-output/implementation-artifacts
+     - Long Term Project Knowledge (docs, research, references): docs/
+
+  Thank you for helping test the early release version of the new BMad Core and BMad Method!
+  Stable Beta coming soon - please read the full README.md and linked documentation to get started.
+
+  And again, here is the Change Log with all the details of recent updates: https://github.com/bmad-code-org/BMAD-METHOD/blob/main/CHANGELOG.md
+
+  ════════════════════════════════════════════════════════════════════════════════

package/tools/cli/installers/lib/core/config-collector.js

@@ -318,11 +318,11 @@ class ConfigCollector {
           this.allAnswers[`${moduleName}_user_name`] = this.getDefaultUsername();
         }
       }
-    }
 
-    // Show "no config" message for modules with no new questions (that have config keys)
-    console.log(chalk.dim(`  ✓ ${moduleName.toUpperCase()} module already up to date`));
-    return false; // No new fields
+      // Show "no config" message for modules with no new questions (that have config keys)
+      console.log(chalk.dim(`  ✓ ${moduleName.toUpperCase()} module already up to date`));
+      return false; // No new fields
+    }
 
     // If we have new fields (interactive or static), process them
     if (newKeys.length > 0 || newStaticKeys.length > 0) {
@@ -363,6 +363,13 @@ class ConfigCollector {
       Object.assign(this.allAnswers, allAnswers);
 
       // 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] };
+      } else {
+        this.collectedConfig[moduleName] = {};
+      }
+
       for (const key of Object.keys(allAnswers)) {
         const originalKey = key.replace(`${moduleName}_`, '');
         const item = moduleConfig[originalKey];
@@ -377,9 +384,7 @@ class ConfigCollector {
           result = value;
         }
 
-        if (!this.collectedConfig[moduleName]) {
-          this.collectedConfig[moduleName] = {};
-        }
+        // Update the collected config with new/updated values
         this.collectedConfig[moduleName][originalKey] = result;
       }
     }
@@ -577,26 +582,23 @@ class ConfigCollector {
 
     // If there are questions to ask, prompt for accepting defaults vs customizing
     if (questions.length > 0) {
-      // Get friendly module name from config or use uppercase module name
       const moduleDisplayName = moduleConfig.header || `${moduleName.toUpperCase()} Module`;
-
-      // Add blank line for better readability
       console.log();
-
-      // Display the module name in color first
       console.log(chalk.cyan('?') + ' ' + chalk.magenta(moduleDisplayName));
+      let customize = true;
+      if (moduleName !== 'core') {
+        const customizeAnswer = await inquirer.prompt([
+          {
+            type: 'confirm',
+            name: 'customize',
+            message: 'Accept Defaults (no to customize)?',
+            default: true,
+          },
+        ]);
+        customize = customizeAnswer.customize;
+      }
 
-      // Ask user if they want to accept defaults or customize on the next line
-      const { customize } = await inquirer.prompt([
-        {
-          type: 'confirm',
-          name: 'customize',
-          message: 'Accept Defaults (no to customize)?',
-          default: true,
-        },
-      ]);
-
-      if (customize) {
+      if (customize && moduleName !== 'core') {
         // Accept defaults - only ask questions that have NO default value
         const questionsWithoutDefaults = questions.filter((q) => q.default === undefined || q.default === null || q.default === '');
 
@@ -616,8 +618,6 @@ class ConfigCollector {
           allAnswers[question.name] = question.default;
         }
       } else {
-        // Customize - ask all questions
-        console.log(chalk.dim(`\n  Configuring ${moduleName.toUpperCase()}...`));
         const promptedAnswers = await inquirer.prompt(questions);
         Object.assign(allAnswers, promptedAnswers);
       }
@@ -642,8 +642,6 @@ class ConfigCollector {
 
         // For arrays (multi-select), handle differently
         if (Array.isArray(value)) {
-          // If there's a result template and it's a string, don't use it for arrays
-          // Just use the array value directly
           result = value;
         } else if (item.result) {
           result = item.result;
@@ -658,11 +656,9 @@ class ConfigCollector {
               if (result === '{value}') {
                 result = value;
               } else {
-                // Otherwise replace in the string
                 result = result.replace('{value}', value);
               }
             } else {
-              // For non-string values, use directly
               result = value;
             }
 
@@ -714,7 +710,6 @@ class ConfigCollector {
             }
           }
         } else {
-          // No result template, use value directly
           result = value;
         }
 

package/tools/cli/installers/lib/message-loader.js

@@ -0,0 +1,85 @@
+const fs = require('fs-extra');
+const path = require('node:path');
+const yaml = require('yaml');
+const chalk = require('chalk');
+
+/**
+ * Load and display installer messages from messages.yaml
+ */
+class MessageLoader {
+  constructor() {}
+
+  /**
+   * Load messages from the YAML file
+   * @returns {Object|null} Messages object or null if not found
+   */
+  load() {
+    if (this.messages) {
+      return this.messages;
+    }
+
+    const messagesPath = path.join(__dirname, '..', 'install-messages.yaml');
+
+    try {
+      const content = fs.readFileSync(messagesPath, 'utf8');
+      this.messages = yaml.parse(content);
+      return this.messages;
+    } catch {
+      // File doesn't exist or is invalid - return null
+      return null;
+    }
+  }
+
+  /**
+   * Get the start message for display
+   * @returns {string|null} Start message or null
+   */
+  getStartMessage() {
+    const messages = this.load();
+    return messages?.startMessage || null;
+  }
+
+  /**
+   * Get the end message for display
+   * @returns {string|null} End message or null
+   */
+  getEndMessage() {
+    const messages = this.load();
+    return messages?.endMessage || null;
+  }
+
+  /**
+   * Display the start message (after logo, before prompts)
+   */
+  displayStartMessage() {
+    const message = this.getStartMessage();
+    if (message) {
+      console.log(chalk.cyan(message));
+      console.log();
+    }
+  }
+
+  /**
+   * Display the end message (after installation completes)
+   */
+  displayEndMessage() {
+    const message = this.getEndMessage();
+    if (message) {
+      console.log();
+      console.log(chalk.cyan(message));
+    }
+  }
+
+  /**
+   * Check if messages exist for the current version
+   * @param {string} currentVersion - Current package version
+   * @returns {boolean} True if messages match current version
+   */
+  isCurrent(currentVersion) {
+    const messages = this.load();
+    return messages && messages.version === currentVersion;
+  }
+  messages = null;
+}
+
+module.exports = { MessageLoader };

package/tools/cli/lib/ui.js

@@ -17,8 +17,10 @@ class UI {
   async promptInstall() {
     CLIUtils.displayLogo();
 
-    // Display changelog link
-    console.log(chalk.cyan('\n📋 Read the latest updates: https://github.com/bmad-code-org/BMAD-METHOD/blob/main/CHANGELOG.md\n'));
+    // Display version-specific start message from install-messages.yaml
+    const { MessageLoader } = require('../installers/lib/message-loader');
+    const messageLoader = new MessageLoader();
+    messageLoader.displayStartMessage();
 
     const confirmedDirectory = await this.getConfirmedDirectory();
 
@@ -43,7 +45,7 @@ class UI {
     if (await fs.pathExists(confirmedDirectory)) {
       const entries = await fs.readdir(confirmedDirectory, { withFileTypes: true });
       for (const entry of entries) {
-        if (entry.isDirectory() && entry.name === '.bmad') {
+        if (entry.isDirectory() && (entry.name === '.bmad' || entry.name === 'bmad')) {
           hasLegacyBmadFolder = true;
           legacyBmadPath = path.join(confirmedDirectory, '.bmad');
           bmadDir = legacyBmadPath;
@@ -58,53 +60,85 @@ class UI {
       }
     }
 
-    // If no .bmad found, check for current installations
+    // If no .bmad or bmad found, check for current installations _bmad
     if (!hasLegacyBmadFolder) {
       const bmadResult = await installer.findBmadDir(confirmedDirectory);
       bmadDir = bmadResult.bmadDir;
       hasLegacyCfg = bmadResult.hasLegacyCfg;
     }
 
+    // Handle legacy .bmad or _cfg folder - these are very old (more than 2 versions behind)
+    // Show version warning instead of offering conversion
     if (hasLegacyBmadFolder || hasLegacyCfg) {
-      console.log(chalk.yellow('\n⚠️  Legacy folder structure detected'));
-
-      let message = 'The following folders need to be renamed:\n';
-      if (hasLegacyBmadFolder) {
-        message += chalk.dim(`  • ".bmad" → "_bmad"\n`);
-      }
-      if (hasLegacyCfg) {
-        message += chalk.dim(`  • "_cfg" → "_config"\n`);
-      }
-      console.log(message);
+      console.log('');
+      console.log(chalk.yellow.bold('⚠️  LEGACY INSTALLATION DETECTED'));
+      console.log(chalk.yellow('─'.repeat(80)));
+      console.log(
+        chalk.yellow(
+          'Found a ".bmad"/"bmad" folder, or a legacy "_cfg" folder under the bmad folder - this is from a old BMAD version that is out of date for automatic upgrade, manual intervention required.',
+        ),
+      );
+      console.log(chalk.yellow('This version is more than 2 alpha versions behind current.'));
+      console.log('');
+      console.log(chalk.dim('For stability, we only support updates from the previous 2 alpha versions.'));
+      console.log(chalk.dim('Legacy installations may have compatibility issues.'));
+      console.log('');
+      console.log(chalk.dim('For the best experience, we strongly recommend:'));
+      console.log(chalk.dim('  1. Delete your current BMAD installation folder (.bmad or bmad)'));
+      console.log(
+        chalk.dim(
+          '  2. Run a fresh installation\n\nIf you do not want to start fresh, you can attempt to proceed beyond this point IF you have ensured the bmad folder is named _bmad, and under it there is a _config folder. If you have a folder under your bmad folder named _cfg, you would need to rename it _config, and then restart the installer.',
+        ),
+      );
+      console.log('');
+      console.log(chalk.dim('Benefits of a fresh install:'));
+      console.log(chalk.dim('  • Cleaner configuration without legacy artifacts'));
+      console.log(chalk.dim('  • All new features properly configured'));
+      console.log(chalk.dim('  • Fewer potential conflicts'));
+      console.log(chalk.dim(''));
+      console.log(
+        chalk.dim(
+          'If you have already produced output from an earlier alpha version, you can still retain those artifacts. After installation, ensure you configured during install the proper file locations for artifacts depending on the module you are using, or move the files to the proper locations.',
+        ),
+      );
+      console.log(chalk.yellow('─'.repeat(80)));
+      console.log('');
 
-      const { shouldRename } = await inquirer.prompt([
+      const { proceed } = await inquirer.prompt([
         {
-          type: 'confirm',
-          name: 'shouldRename',
-          message: 'Would you like the installer to rename these folders for you?',
-          default: true,
+          type: 'list',
+          name: 'proceed',
+          message: 'What would you like to do?',
+          choices: [
+            {
+              name: 'Cancel and do a fresh install (recommended)',
+              value: 'cancel',
+              short: 'Cancel installation',
+            },
+            {
+              name: 'Proceed anyway (will attempt update, potentially may fail or have unstable behavior)',
+              value: 'proceed',
+              short: 'Proceed with update',
+            },
+          ],
+          default: 'cancel',
         },
       ]);
 
-      if (!shouldRename) {
-        console.log(chalk.red('\n❌ Installation cancelled'));
-        console.log(chalk.dim('You must manually rename the folders before proceeding:'));
-        if (hasLegacyBmadFolder) {
-          console.log(chalk.dim(`  • Rename ".bmad" to "_bmad"`));
-        }
-        if (hasLegacyCfg) {
-          console.log(chalk.dim(`  • Rename "_cfg" to "_config"`));
-        }
+      if (proceed === 'cancel') {
+        console.log('');
+        console.log(chalk.cyan('To do a fresh install:'));
+        console.log(chalk.dim('  1. Delete the existing bmad folder in your project'));
+        console.log(chalk.dim("  2. Run 'bmad install' again"));
+        console.log('');
         process.exit(0);
         return;
       }
 
-      // Perform the renames
       const ora = require('ora');
       const spinner = ora('Updating folder structure...').start();
-
       try {
-        // First rename .bmad to _bmad if needed
+        // Handle .bmad folder
         if (hasLegacyBmadFolder) {
           const newBmadPath = path.join(confirmedDirectory, '_bmad');
           await fs.move(legacyBmadPath, newBmadPath);
@@ -112,16 +146,14 @@ class UI {
           spinner.succeed('Renamed ".bmad" to "_bmad"');
         }
 
-        // Then rename _cfg to _config if needed
-        if (hasLegacyCfg) {
+        // Handle _cfg folder (either from .bmad or standalone)
+        const cfgPath = path.join(bmadDir, '_cfg');
+        if (await fs.pathExists(cfgPath)) {
           spinner.start('Renaming configuration folder...');
-          const oldCfgPath = path.join(bmadDir, '_cfg');
           const newCfgPath = path.join(bmadDir, '_config');
-          await fs.move(oldCfgPath, newCfgPath);
+          await fs.move(cfgPath, newCfgPath);
           spinner.succeed('Renamed "_cfg" to "_config"');
         }
-
-        spinner.succeed('Folder structure updated successfully');
       } catch (error) {
         spinner.fail('Failed to update folder structure');
         console.error(chalk.red(`Error: ${error.message}`));
@@ -173,11 +205,20 @@ class UI {
     // Only show action menu if there's an existing installation
     if (hasExistingInstall) {
       // Get version information
-      const { existingInstall } = await this.getExistingInstallation(confirmedDirectory);
+      const { existingInstall, bmadDir } = await this.getExistingInstallation(confirmedDirectory);
       const packageJsonPath = path.join(__dirname, '../../../package.json');
       const currentVersion = require(packageJsonPath).version;
       const installedVersion = existingInstall.version || 'unknown';
 
+      // Check if version is too old and warn user
+      const shouldProceed = await this.showOldAlphaVersionWarning(installedVersion, currentVersion, path.basename(bmadDir));
+
+      // If user chose to cancel, exit the installer
+      if (!shouldProceed) {
+        process.exit(0);
+        return;
+      }
+
       // Build menu choices dynamically
       const choices = [];
 
@@ -662,7 +703,7 @@ class UI {
   /**
    * Get existing installation info and installed modules
    * @param {string} directory - Installation directory
-   * @returns {Object} Object with existingInstall and installedModuleIds
+   * @returns {Object} Object with existingInstall, installedModuleIds, and bmadDir
    */
   async getExistingInstallation(directory) {
     const { Detector } = require('../installers/lib/core/detector');
@@ -670,10 +711,11 @@ class UI {
     const detector = new Detector();
     const installer = new Installer();
     const bmadDirResult = await installer.findBmadDir(directory);
-    const existingInstall = await detector.detect(bmadDirResult.bmadDir);
+    const bmadDir = bmadDirResult.bmadDir;
+    const existingInstall = await detector.detect(bmadDir);
     const installedModuleIds = new Set(existingInstall.modules.map((mod) => mod.id));
 
-    return { existingInstall, installedModuleIds };
+    return { existingInstall, installedModuleIds, bmadDir };
   }
 
   /**
@@ -1457,6 +1499,144 @@ class UI {
 
     return result;
   }
+
+  /**
+   * Parse alpha version string (e.g., "6.0.0-Alpha.20")
+   * @param {string} version - Version string
+   * @returns {Object|null} Object with alphaNumber and fullVersion, or null if invalid
+   */
+  parseAlphaVersion(version) {
+    if (!version || version === 'unknown') {
+      return null;
+    }
+
+    // Remove 'v' prefix if present
+    const cleanVersion = version.toString().replace(/^v/i, '');
+
+    // Match alpha version pattern: X.Y.Z-Alpha.N (case-insensitive)
+    const match = cleanVersion.match(/[\d.]+-Alpha\.(\d+)/i);
+
+    if (!match) {
+      return null;
+    }
+
+    return {
+      alphaNumber: parseInt(match[1], 10),
+      fullVersion: cleanVersion,
+    };
+  }
+
+  /**
+   * Check if installed version is more than 2 alpha versions behind current
+   * @param {string} installedVersion - The installed version
+   * @param {string} currentVersion - The current version
+   * @returns {Object} Object with { isOldVersion, versionDiff, shouldWarn, installed, current }
+   */
+  checkAlphaVersionAge(installedVersion, currentVersion) {
+    const installed = this.parseAlphaVersion(installedVersion);
+    const current = this.parseAlphaVersion(currentVersion);
+
+    // If we can't parse either version, don't warn
+    if (!installed || !current) {
+      return { isOldVersion: false, versionDiff: 0, shouldWarn: false };
+    }
+
+    // Calculate alpha version difference
+    const versionDiff = current.alphaNumber - installed.alphaNumber;
+
+    // Consider it old if more than 2 versions behind
+    const isOldVersion = versionDiff > 2;
+
+    return {
+      isOldVersion,
+      versionDiff,
+      shouldWarn: isOldVersion,
+      installed: installed.fullVersion,
+      current: current.fullVersion,
+      installedAlpha: installed.alphaNumber,
+      currentAlpha: current.alphaNumber,
+    };
+  }
+
+  /**
+   * Show warning for old alpha version and ask if user wants to proceed
+   * @param {string} installedVersion - The installed version
+   * @param {string} currentVersion - The current version
+   * @param {string} bmadFolderName - Name of the BMAD folder
+   * @returns {Promise<boolean>} True if user wants to proceed, false if they cancel
+   */
+  async showOldAlphaVersionWarning(installedVersion, currentVersion, bmadFolderName) {
+    const versionInfo = this.checkAlphaVersionAge(installedVersion, currentVersion);
+
+    // Also warn if version is unknown or can't be parsed (legacy/unsupported)
+    const isUnknownVersion = installedVersion === 'unknown' || !versionInfo.installed;
+
+    if (!versionInfo.shouldWarn && !isUnknownVersion) {
+      return true; // Not old, proceed
+    }
+
+    console.log('');
+    console.log(chalk.yellow.bold('⚠️  VERSION WARNING'));
+    console.log(chalk.yellow('─'.repeat(80)));
+
+    if (isUnknownVersion) {
+      console.log(chalk.yellow('Unable to detect your installed BMAD version.'));
+      console.log(chalk.yellow('This appears to be a legacy or unsupported installation.'));
+      console.log('');
+      console.log(chalk.dim('For stability, we only support updates from the previous 2 alpha versions.'));
+      console.log(chalk.dim('Legacy installations may have compatibility issues.'));
+    } else {
+      console.log(chalk.yellow(`You are updating from ${versionInfo.installed} to ${versionInfo.current}.`));
+      console.log(chalk.yellow(`This is ${versionInfo.versionDiff} alpha versions behind.`));
+      console.log('');
+      console.log(chalk.dim(`For stability, we only support updates from the previous 2 alpha versions`));
+      console.log(chalk.dim(`(Alpha.${versionInfo.currentAlpha - 2} through Alpha.${versionInfo.currentAlpha - 1}).`));
+    }
+
+    console.log('');
+    console.log(chalk.dim('For the best experience, we recommend:'));
+    console.log(chalk.dim('  1. Delete your current BMAD installation folder'));
+    console.log(chalk.dim(`     (the "${bmadFolderName}/" folder in your project)`));
+    console.log(chalk.dim('  2. Run a fresh installation'));
+    console.log('');
+    console.log(chalk.dim('Benefits of a fresh install:'));
+    console.log(chalk.dim('  • Cleaner configuration without legacy artifacts'));
+    console.log(chalk.dim('  • All new features properly configured'));
+    console.log(chalk.dim('  • Fewer potential conflicts'));
+    console.log(chalk.yellow('─'.repeat(80)));
+    console.log('');
+
+    const { proceed } = await inquirer.prompt([
+      {
+        type: 'list',
+        name: 'proceed',
+        message: 'What would you like to do?',
+        choices: [
+          {
+            name: 'Proceed with update anyway (may have issues)',
+            value: 'proceed',
+            short: 'Proceed with update',
+          },
+          {
+            name: 'Cancel (recommended - do a fresh install instead)',
+            value: 'cancel',
+            short: 'Cancel installation',
+          },
+        ],
+        default: 'cancel',
+      },
+    ]);
+
+    if (proceed === 'cancel') {
+      console.log('');
+      console.log(chalk.cyan('To do a fresh install:'));
+      console.log(chalk.dim(`  1. Delete the "${bmadFolderName}/" folder in your project`));
+      console.log(chalk.dim("  2. Run 'bmad install' again"));
+      console.log('');
+    }
+
+    return proceed === 'proceed';
+  }
 }
 
 module.exports = { UI };