bmad-method 5.1.3 → 6.0.0-alpha.0

package/tools/cli/lib/platform-codes.js

@@ -0,0 +1,116 @@
+const fs = require('fs-extra');
+const path = require('node:path');
+const yaml = require('js-yaml');
+const { getProjectRoot } = require('./project-root');
+
+/**
+ * Platform Codes Manager
+ * Loads and provides access to the centralized platform codes configuration
+ */
+class PlatformCodes {
+  constructor() {
+    this.configPath = path.join(getProjectRoot(), 'tools', 'platform-codes.yaml');
+    this.loadConfig();
+  }
+
+  /**
+   * Load the platform codes configuration
+   */
+  loadConfig() {
+    try {
+      if (fs.existsSync(this.configPath)) {
+        const content = fs.readFileSync(this.configPath, 'utf8');
+        this.config = yaml.load(content);
+      } else {
+        console.warn(`Platform codes config not found at ${this.configPath}`);
+        this.config = { platforms: {} };
+      }
+    } catch (error) {
+      console.error(`Error loading platform codes: ${error.message}`);
+      this.config = { platforms: {} };
+    }
+  }
+
+  /**
+   * Get all platform codes
+   * @returns {Object} All platform configurations
+   */
+  getAllPlatforms() {
+    return this.config.platforms || {};
+  }
+
+  /**
+   * Get a specific platform configuration
+   * @param {string} code - Platform code
+   * @returns {Object|null} Platform configuration or null if not found
+   */
+  getPlatform(code) {
+    return this.config.platforms[code] || null;
+  }
+
+  /**
+   * Check if a platform code is valid
+   * @param {string} code - Platform code to validate
+   * @returns {boolean} True if valid
+   */
+  isValidPlatform(code) {
+    return code in this.config.platforms;
+  }
+
+  /**
+   * Get all preferred platforms
+   * @returns {Array} Array of preferred platform codes
+   */
+  getPreferredPlatforms() {
+    return Object.entries(this.config.platforms)
+      .filter(([, config]) => config.preferred)
+      .map(([code]) => code);
+  }
+
+  /**
+   * Get platforms by category
+   * @param {string} category - Category to filter by
+   * @returns {Array} Array of platform codes in the category
+   */
+  getPlatformsByCategory(category) {
+    return Object.entries(this.config.platforms)
+      .filter(([, config]) => config.category === category)
+      .map(([code]) => code);
+  }
+
+  /**
+   * Get platform display name
+   * @param {string} code - Platform code
+   * @returns {string} Display name or code if not found
+   */
+  getDisplayName(code) {
+    const platform = this.getPlatform(code);
+    return platform ? platform.name : code;
+  }
+
+  /**
+   * Validate platform code format
+   * @param {string} code - Platform code to validate
+   * @returns {boolean} True if format is valid
+   */
+  isValidFormat(code) {
+    const conventions = this.config.conventions || {};
+    const pattern = conventions.allowed_characters || 'a-z0-9-';
+    const maxLength = conventions.max_code_length || 20;
+
+    const regex = new RegExp(`^[${pattern}]+$`);
+    return regex.test(code) && code.length <= maxLength;
+  }
+
+  /**
+   * Get all platform codes as array
+   * @returns {Array} Array of platform codes
+   */
+  getCodes() {
+    return Object.keys(this.config.platforms);
+  }
+  config = null;
+}
+
+// Export singleton instance
+module.exports = new PlatformCodes();

package/tools/cli/lib/project-root.js

@@ -0,0 +1,71 @@
+const path = require('node:path');
+const fs = require('fs-extra');
+
+/**
+ * Find the BMAD project root directory by looking for package.json
+ * or specific BMAD markers
+ */
+function findProjectRoot(startPath = __dirname) {
+  let currentPath = path.resolve(startPath);
+
+  // Keep going up until we find package.json with bmad-method
+  while (currentPath !== path.dirname(currentPath)) {
+    const packagePath = path.join(currentPath, 'package.json');
+
+    if (fs.existsSync(packagePath)) {
+      try {
+        const pkg = fs.readJsonSync(packagePath);
+        // Check if this is the BMAD project
+        if (pkg.name === 'bmad-method' || fs.existsSync(path.join(currentPath, 'src', 'core'))) {
+          return currentPath;
+        }
+      } catch {
+        // Continue searching
+      }
+    }
+
+    // Also check for src/core as a marker
+    if (fs.existsSync(path.join(currentPath, 'src', 'core', 'agents'))) {
+      return currentPath;
+    }
+
+    currentPath = path.dirname(currentPath);
+  }
+
+  // If we can't find it, use process.cwd() as fallback
+  return process.cwd();
+}
+
+// Cache the project root after first calculation
+let cachedRoot = null;
+
+function getProjectRoot() {
+  if (!cachedRoot) {
+    cachedRoot = findProjectRoot();
+  }
+  return cachedRoot;
+}
+
+/**
+ * Get path to source directory
+ */
+function getSourcePath(...segments) {
+  return path.join(getProjectRoot(), 'src', ...segments);
+}
+
+/**
+ * Get path to a module's directory
+ */
+function getModulePath(moduleName, ...segments) {
+  if (moduleName === 'core') {
+    return getSourcePath('core', ...segments);
+  }
+  return getSourcePath('modules', moduleName, ...segments);
+}
+
+module.exports = {
+  getProjectRoot,
+  getSourcePath,
+  getModulePath,
+  findProjectRoot,
+};

package/tools/cli/lib/replace-project-root.js

@@ -0,0 +1,239 @@
+/**
+ * Utility function to replace {project-root} placeholders with actual installation target
+ * Used during BMAD installation to set correct paths in agent and task files
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+/**
+ * Replace {project-root} and {output_folder}/ placeholders in a single file
+ * @param {string} filePath - Path to the file to process
+ * @param {string} projectRoot - The actual project root path to substitute (must include trailing slash)
+ * @param {string} docOut - The document output path (with leading slash)
+ * @param {boolean} removeCompletely - If true, removes placeholders entirely instead of replacing
+ * @returns {boolean} - True if replacements were made, false otherwise
+ */
+function replacePlaceholdersInFile(filePath, projectRoot, docOut = '/docs', removeCompletely = false) {
+  try {
+    let content = fs.readFileSync(filePath, 'utf8');
+    const originalContent = content;
+
+    if (removeCompletely) {
+      // Remove placeholders entirely (for bundling)
+      content = content.replaceAll('{project-root}', '');
+      content = content.replaceAll('{output_folder}/', '');
+    } else {
+      // Handle the combined pattern first to avoid double slashes
+      if (projectRoot && docOut) {
+        // Replace {project-root}{output_folder}/ combinations first
+        // Remove leading slash from docOut since projectRoot has trailing slash
+        // Add trailing slash to docOut
+        const docOutNoLeadingSlash = docOut.replace(/^\//, '');
+        const docOutWithTrailingSlash = docOutNoLeadingSlash.endsWith('/') ? docOutNoLeadingSlash : docOutNoLeadingSlash + '/';
+        content = content.replaceAll('{project-root}{output_folder}/', projectRoot + docOutWithTrailingSlash);
+      }
+
+      // Then replace remaining individual placeholders
+      if (projectRoot) {
+        content = content.replaceAll('{project-root}', projectRoot);
+      }
+
+      if (docOut) {
+        // For standalone {output_folder}/, keep the leading slash and add trailing slash
+        const docOutWithTrailingSlash = docOut.endsWith('/') ? docOut : docOut + '/';
+        content = content.replaceAll('{output_folder}/', docOutWithTrailingSlash);
+      }
+    }
+
+    if (content !== originalContent) {
+      fs.writeFileSync(filePath, content, 'utf8');
+      return true;
+    }
+
+    return false;
+  } catch (error) {
+    console.error(`Error processing file ${filePath}:`, error.message);
+    return false;
+  }
+}
+
+/**
+ * Legacy function name for backward compatibility
+ */
+function replaceProjectRootInFile(filePath, projectRoot, removeCompletely = false) {
+  return replacePlaceholdersInFile(filePath, projectRoot, '/docs', removeCompletely);
+}
+
+/**
+ * Recursively replace {project-root} and {output_folder}/ in all files in a directory
+ * @param {string} dirPath - Directory to process
+ * @param {string} projectRoot - The actual project root path to substitute (or null to remove)
+ * @param {string} docOut - The document output path (with leading slash)
+ * @param {Array<string>} extensions - File extensions to process (default: ['.md', '.xml', '.yaml'])
+ * @param {boolean} removeCompletely - If true, removes placeholders entirely instead of replacing
+ * @param {boolean} verbose - If true, show detailed output for each file
+ * @returns {Object} - Stats object with counts of files processed and modified
+ */
+function replacePlaceholdersInDirectory(
+  dirPath,
+  projectRoot,
+  docOut = '/docs',
+  extensions = ['.md', '.xml', '.yaml'],
+  removeCompletely = false,
+  verbose = false,
+) {
+  const stats = {
+    processed: 0,
+    modified: 0,
+    errors: 0,
+  };
+
+  function processDirectory(currentPath) {
+    try {
+      const items = fs.readdirSync(currentPath, { withFileTypes: true });
+
+      for (const item of items) {
+        const fullPath = path.join(currentPath, item.name);
+
+        if (item.isDirectory()) {
+          // Skip node_modules and .git directories
+          if (item.name !== 'node_modules' && item.name !== '.git') {
+            processDirectory(fullPath);
+          }
+        } else if (item.isFile()) {
+          // Check if file has one of the target extensions
+          const ext = path.extname(item.name).toLowerCase();
+          if (extensions.includes(ext)) {
+            stats.processed++;
+            if (replacePlaceholdersInFile(fullPath, projectRoot, docOut, removeCompletely)) {
+              stats.modified++;
+              if (verbose) {
+                console.log(`✓ Updated: ${fullPath}`);
+              }
+            }
+          }
+        }
+      }
+    } catch (error) {
+      console.error(`Error processing directory ${currentPath}:`, error.message);
+      stats.errors++;
+    }
+  }
+
+  processDirectory(dirPath);
+  return stats;
+}
+
+/**
+ * Legacy function for backward compatibility
+ */
+function replaceProjectRootInDirectory(dirPath, projectRoot, extensions = ['.md', '.xml'], removeCompletely = false) {
+  return replacePlaceholdersInDirectory(dirPath, projectRoot, '/docs', extensions, removeCompletely);
+}
+
+/**
+ * Replace placeholders in a list of specific files
+ * @param {Array<string>} filePaths - Array of file paths to process
+ * @param {string} projectRoot - The actual project root path to substitute (or null to remove)
+ * @param {string} docOut - The document output path (with leading slash)
+ * @param {boolean} removeCompletely - If true, removes placeholders entirely instead of replacing
+ * @returns {Object} - Stats object with counts of files processed and modified
+ */
+function replacePlaceholdersInFiles(filePaths, projectRoot, docOut = '/docs', removeCompletely = false) {
+  const stats = {
+    processed: 0,
+    modified: 0,
+    errors: 0,
+  };
+
+  for (const filePath of filePaths) {
+    stats.processed++;
+    try {
+      if (replacePlaceholdersInFile(filePath, projectRoot, docOut, removeCompletely)) {
+        stats.modified++;
+        console.log(`✓ Updated: ${filePath}`);
+      }
+    } catch (error) {
+      console.error(`Error processing file ${filePath}:`, error.message);
+      stats.errors++;
+    }
+  }
+
+  return stats;
+}
+
+/**
+ * Legacy function for backward compatibility
+ */
+function replaceProjectRootInFiles(filePaths, projectRoot, removeCompletely = false) {
+  return replacePlaceholdersInFiles(filePaths, projectRoot, '/docs', removeCompletely);
+}
+
+/**
+ * Main installation helper - replaces {project-root} and {output_folder}/ during BMAD installation
+ * @param {string} installPath - Path where BMAD is being installed
+ * @param {string} targetProjectRoot - The project root to set in the files (slash will be added)
+ * @param {string} docsOutputPath - The documentation output path (relative to project root)
+ * @param {boolean} verbose - If true, show detailed output
+ * @returns {Object} - Installation stats
+ */
+function processInstallation(installPath, targetProjectRoot, docsOutputPath = 'docs', verbose = false) {
+  // Ensure project root has trailing slash since usage is like {project-root}/bmad
+  const projectRootWithSlash = targetProjectRoot.endsWith('/') ? targetProjectRoot : targetProjectRoot + '/';
+
+  // Ensure docs path has leading slash (for internal use) but will add trailing slash during replacement
+  const normalizedDocsPath = docsOutputPath.replaceAll(/^\/+|\/+$/g, '');
+  const docOutPath = normalizedDocsPath ? `/${normalizedDocsPath}` : '/docs';
+
+  if (verbose) {
+    console.log(`\nReplacing {project-root} with: ${projectRootWithSlash}`);
+    console.log(`Replacing {output_folder}/ with: ${docOutPath}/`);
+    console.log(`Processing files in: ${installPath}\n`);
+  }
+
+  const stats = replacePlaceholdersInDirectory(installPath, projectRootWithSlash, docOutPath, ['.md', '.xml', '.yaml'], false, verbose);
+
+  if (verbose) {
+    console.log('\n--- Installation Processing Complete ---');
+  }
+  console.log(`Files processed: ${stats.processed}`);
+  console.log(`Files modified: ${stats.modified}`);
+  if (stats.errors > 0) {
+    console.log(`Errors encountered: ${stats.errors}`);
+  }
+
+  return stats;
+}
+
+/**
+ * Bundle helper - removes {project-root}/ references for web bundling
+ * @param {string} bundlePath - Path where files are being bundled
+ * @returns {Object} - Bundle stats
+ */
+function processBundleRemoval(bundlePath) {
+  console.log(`\nRemoving {project-root}/ references for bundling`);
+  console.log(`Processing files in: ${bundlePath}\n`);
+
+  const stats = replaceProjectRootInDirectory(bundlePath, null, ['.md', '.xml'], true);
+
+  console.log('\n--- Bundle Processing Complete ---');
+  console.log(`Files processed: ${stats.processed}`);
+  console.log(`Files modified: ${stats.modified}`);
+  if (stats.errors > 0) {
+    console.log(`Errors encountered: ${stats.errors}`);
+  }
+
+  return stats;
+}
+
+module.exports = {
+  replacePlaceholdersInFile,
+  replacePlaceholdersInDirectory,
+  replacePlaceholdersInFiles,
+  replaceProjectRootInFile,
+  replaceProjectRootInDirectory,
+  replaceProjectRootInFiles,
+  processInstallation,
+  processBundleRemoval,
+};