bmad-method 6.2.3-next.26 → 6.2.3-next.28

package/tools/installer/modules/custom-module-manager.js

@@ -0,0 +1,308 @@
+const fs = require('fs-extra');
+const os = require('node:os');
+const path = require('node:path');
+const { execSync } = require('node:child_process');
+const prompts = require('../prompts');
+const { RegistryClient } = require('./registry-client');
+
+/**
+ * Manages custom modules installed from user-provided GitHub URLs.
+ * Validates URLs, fetches .claude-plugin/marketplace.json, clones repos.
+ */
+class CustomModuleManager {
+  constructor() {
+    this._client = new RegistryClient();
+  }
+
+  // ─── URL Validation ───────────────────────────────────────────────────────
+
+  /**
+   * Parse and validate a GitHub repository URL.
+   * Supports HTTPS and SSH formats.
+   * @param {string} url - GitHub URL to validate
+   * @returns {Object} { owner, repo, isValid, error }
+   */
+  validateGitHubUrl(url) {
+    if (!url || typeof url !== 'string') {
+      return { owner: null, repo: null, isValid: false, error: 'URL is required' };
+    }
+
+    const trimmed = url.trim();
+
+    // HTTPS format: https://github.com/owner/repo[.git]
+    const httpsMatch = trimmed.match(/^https?:\/\/github\.com\/([^/]+)\/([^/.]+?)(?:\.git)?$/);
+    if (httpsMatch) {
+      return { owner: httpsMatch[1], repo: httpsMatch[2], isValid: true, error: null };
+    }
+
+    // SSH format: git@github.com:owner/repo.git
+    const sshMatch = trimmed.match(/^git@github\.com:([^/]+)\/([^/.]+?)(?:\.git)?$/);
+    if (sshMatch) {
+      return { owner: sshMatch[1], repo: sshMatch[2], isValid: true, error: null };
+    }
+
+    return { owner: null, repo: null, isValid: false, error: 'Not a valid GitHub URL (expected https://github.com/owner/repo)' };
+  }
+
+  // ─── Discovery ────────────────────────────────────────────────────────────
+
+  /**
+   * Fetch .claude-plugin/marketplace.json from a GitHub repository.
+   * @param {string} repoUrl - GitHub repository URL
+   * @returns {Object} Parsed marketplace.json content
+   */
+  async fetchMarketplaceJson(repoUrl) {
+    const { owner, repo, isValid, error } = this.validateGitHubUrl(repoUrl);
+    if (!isValid) throw new Error(error);
+
+    const rawUrl = `https://raw.githubusercontent.com/${owner}/${repo}/HEAD/.claude-plugin/marketplace.json`;
+
+    try {
+      return await this._client.fetchJson(rawUrl);
+    } catch (error_) {
+      if (error_.message.includes('404')) {
+        throw new Error(`No .claude-plugin/marketplace.json found in ${owner}/${repo}. This repository may not be a BMad module.`);
+      }
+      if (error_.message.includes('403')) {
+        throw new Error(`Repository ${owner}/${repo} is not accessible. Make sure it is public.`);
+      }
+      throw new Error(`Failed to fetch marketplace.json from ${owner}/${repo}: ${error_.message}`);
+    }
+  }
+
+  /**
+   * Discover modules from a GitHub repository's marketplace.json.
+   * @param {string} repoUrl - GitHub repository URL
+   * @returns {Array<Object>} Normalized plugin list
+   */
+  async discoverModules(repoUrl) {
+    const data = await this.fetchMarketplaceJson(repoUrl);
+    const plugins = data?.plugins;
+
+    if (!Array.isArray(plugins) || plugins.length === 0) {
+      throw new Error('marketplace.json contains no plugins');
+    }
+
+    return plugins.map((plugin) => this._normalizeCustomModule(plugin, repoUrl, data));
+  }
+
+  // ─── Clone ────────────────────────────────────────────────────────────────
+
+  /**
+   * Get the cache directory for custom modules.
+   * @returns {string} Path to the custom modules cache directory
+   */
+  getCacheDir() {
+    return path.join(os.homedir(), '.bmad', 'cache', 'custom-modules');
+  }
+
+  /**
+   * Clone a custom module repository to cache.
+   * @param {string} repoUrl - GitHub repository URL
+   * @param {Object} [options] - Clone options
+   * @param {boolean} [options.silent] - Suppress spinner output
+   * @returns {string} Path to the cloned repository
+   */
+  async cloneRepo(repoUrl, options = {}) {
+    const { owner, repo, isValid, error } = this.validateGitHubUrl(repoUrl);
+    if (!isValid) throw new Error(error);
+
+    const cacheDir = this.getCacheDir();
+    const repoCacheDir = path.join(cacheDir, owner, repo);
+    const silent = options.silent || false;
+
+    await fs.ensureDir(path.join(cacheDir, owner));
+
+    const createSpinner = async () => {
+      if (silent) {
+        return { start() {}, stop() {}, error() {} };
+      }
+      return await prompts.spinner();
+    };
+
+    if (await fs.pathExists(repoCacheDir)) {
+      // Update existing clone
+      const fetchSpinner = await createSpinner();
+      fetchSpinner.start(`Updating ${owner}/${repo}...`);
+      try {
+        execSync('git fetch origin --depth 1', {
+          cwd: repoCacheDir,
+          stdio: ['ignore', 'pipe', 'pipe'],
+          env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+        });
+        execSync('git reset --hard origin/HEAD', {
+          cwd: repoCacheDir,
+          stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        fetchSpinner.stop(`Updated ${owner}/${repo}`);
+      } catch {
+        fetchSpinner.error(`Update failed, re-downloading ${owner}/${repo}`);
+        await fs.remove(repoCacheDir);
+      }
+    }
+
+    if (!(await fs.pathExists(repoCacheDir))) {
+      const fetchSpinner = await createSpinner();
+      fetchSpinner.start(`Cloning ${owner}/${repo}...`);
+      try {
+        execSync(`git clone --depth 1 "${repoUrl}" "${repoCacheDir}"`, {
+          stdio: ['ignore', 'pipe', 'pipe'],
+          env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+        });
+        fetchSpinner.stop(`Cloned ${owner}/${repo}`);
+      } catch (error_) {
+        fetchSpinner.error(`Failed to clone ${owner}/${repo}`);
+        throw new Error(`Failed to clone ${repoUrl}: ${error_.message}`);
+      }
+    }
+
+    // Install dependencies if package.json exists
+    const packageJsonPath = path.join(repoCacheDir, 'package.json');
+    if (await fs.pathExists(packageJsonPath)) {
+      const installSpinner = await createSpinner();
+      installSpinner.start(`Installing dependencies for ${owner}/${repo}...`);
+      try {
+        execSync('npm install --omit=dev --no-audit --no-fund --no-progress --legacy-peer-deps', {
+          cwd: repoCacheDir,
+          stdio: ['ignore', 'pipe', 'pipe'],
+          timeout: 120_000,
+        });
+        installSpinner.stop(`Installed dependencies for ${owner}/${repo}`);
+      } catch (error_) {
+        installSpinner.error(`Failed to install dependencies for ${owner}/${repo}`);
+        if (!silent) await prompts.log.warn(`  ${error_.message}`);
+      }
+    }
+
+    return repoCacheDir;
+  }
+
+  // ─── Source Finding ───────────────────────────────────────────────────────
+
+  /**
+   * Find the module source path within a cloned custom repo.
+   * @param {string} repoUrl - GitHub repository URL (for cache location)
+   * @param {string} [pluginSource] - Plugin source path from marketplace.json
+   * @returns {string|null} Path to directory containing module.yaml
+   */
+  async findModuleSource(repoUrl, pluginSource) {
+    const { owner, repo } = this.validateGitHubUrl(repoUrl);
+    const repoCacheDir = path.join(this.getCacheDir(), owner, repo);
+
+    if (!(await fs.pathExists(repoCacheDir))) return null;
+
+    // Try plugin source path first (e.g., "./src/pro-skills")
+    if (pluginSource) {
+      const sourcePath = path.join(repoCacheDir, pluginSource);
+      const moduleYaml = path.join(sourcePath, 'module.yaml');
+      if (await fs.pathExists(moduleYaml)) {
+        return sourcePath;
+      }
+    }
+
+    // Fallback: search skills/ and src/ directories
+    for (const dir of ['skills', 'src']) {
+      const rootCandidate = path.join(repoCacheDir, dir, 'module.yaml');
+      if (await fs.pathExists(rootCandidate)) {
+        return path.dirname(rootCandidate);
+      }
+      const dirPath = path.join(repoCacheDir, dir);
+      if (await fs.pathExists(dirPath)) {
+        const entries = await fs.readdir(dirPath, { withFileTypes: true });
+        for (const entry of entries) {
+          if (entry.isDirectory()) {
+            const subCandidate = path.join(dirPath, entry.name, 'module.yaml');
+            if (await fs.pathExists(subCandidate)) {
+              return path.dirname(subCandidate);
+            }
+          }
+        }
+      }
+    }
+
+    // Check repo root
+    const rootCandidate = path.join(repoCacheDir, 'module.yaml');
+    if (await fs.pathExists(rootCandidate)) {
+      return repoCacheDir;
+    }
+
+    return null;
+  }
+
+  /**
+   * Find module source by module code, searching the custom cache.
+   * @param {string} moduleCode - Module code to search for
+   * @param {Object} [options] - Options
+   * @returns {string|null} Path to the module source or null
+   */
+  async findModuleSourceByCode(moduleCode, options = {}) {
+    const cacheDir = this.getCacheDir();
+    if (!(await fs.pathExists(cacheDir))) return null;
+
+    // Search through all custom repo caches
+    try {
+      const owners = await fs.readdir(cacheDir, { withFileTypes: true });
+      for (const ownerEntry of owners) {
+        if (!ownerEntry.isDirectory()) continue;
+        const ownerPath = path.join(cacheDir, ownerEntry.name);
+        const repos = await fs.readdir(ownerPath, { withFileTypes: true });
+        for (const repoEntry of repos) {
+          if (!repoEntry.isDirectory()) continue;
+          const repoPath = path.join(ownerPath, repoEntry.name);
+
+          // Check marketplace.json for matching module code
+          const marketplacePath = path.join(repoPath, '.claude-plugin', 'marketplace.json');
+          if (await fs.pathExists(marketplacePath)) {
+            try {
+              const data = JSON.parse(await fs.readFile(marketplacePath, 'utf8'));
+              for (const plugin of data.plugins || []) {
+                if (plugin.name === moduleCode) {
+                  // Found the module - find its source
+                  const sourcePath = plugin.source ? path.join(repoPath, plugin.source) : repoPath;
+                  const moduleYaml = path.join(sourcePath, 'module.yaml');
+                  if (await fs.pathExists(moduleYaml)) {
+                    return sourcePath;
+                  }
+                }
+              }
+            } catch {
+              // Skip malformed marketplace.json
+            }
+          }
+        }
+      }
+    } catch {
+      // Cache doesn't exist or is inaccessible
+    }
+
+    return null;
+  }
+
+  // ─── Normalization ────────────────────────────────────────────────────────
+
+  /**
+   * Normalize a plugin from marketplace.json to a consistent shape.
+   * @param {Object} plugin - Plugin object from marketplace.json
+   * @param {string} repoUrl - Source repository URL
+   * @param {Object} data - Full marketplace.json data
+   * @returns {Object} Normalized module info
+   */
+  _normalizeCustomModule(plugin, repoUrl, data) {
+    return {
+      code: plugin.name,
+      name: plugin.name,
+      displayName: plugin.name,
+      description: plugin.description || '',
+      version: plugin.version || null,
+      author: plugin.author || data.owner || '',
+      url: repoUrl,
+      source: plugin.source || null,
+      type: 'custom',
+      trustTier: 'unverified',
+      builtIn: false,
+      isExternal: true,
+    };
+  }
+}
+
+module.exports = { CustomModuleManager };

package/tools/installer/modules/external-manager.js

@@ -4,64 +4,98 @@ const path = require('node:path');
 const { execSync } = require('node:child_process');
 const yaml = require('yaml');
 const prompts = require('../prompts');
+const { RegistryClient } = require('./registry-client');
+
+const REGISTRY_RAW_URL = 'https://raw.githubusercontent.com/bmad-code-org/bmad-plugins-marketplace/main/registry/official.yaml';
+const FALLBACK_CONFIG_PATH = path.join(__dirname, 'registry-fallback.yaml');
 
 /**
- * Manages external official modules defined in external-official-modules.yaml
- * These are modules hosted in external repositories that can be installed
+ * Manages official modules from the remote BMad marketplace registry.
+ * Fetches registry/official.yaml from GitHub; falls back to the bundled
+ * external-official-modules.yaml when the network is unavailable.
  *
  * @class ExternalModuleManager
  */
 class ExternalModuleManager {
   constructor() {
-    this.externalModulesConfigPath = path.join(__dirname, '../external-official-modules.yaml');
-    this.cachedModules = null;
+    this._client = new RegistryClient();
   }
 
   /**
-   * Load and parse the external-official-modules.yaml file
-   * @returns {Object} Parsed YAML content with modules object
+   * Load the official modules registry from GitHub, falling back to the
+   * bundled YAML file if the fetch fails.
+   * @returns {Object} Parsed YAML content with modules array
    */
   async loadExternalModulesConfig() {
     if (this.cachedModules) {
       return this.cachedModules;
     }
 
+    // Try remote registry first
+    try {
+      const content = await this._client.fetch(REGISTRY_RAW_URL);
+      const config = yaml.parse(content);
+      if (config?.modules?.length) {
+        this.cachedModules = config;
+        return config;
+      }
+    } catch {
+      // Fall through to local fallback
+    }
+
+    // Fallback to bundled file
     try {
-      const content = await fs.readFile(this.externalModulesConfigPath, 'utf8');
+      const content = await fs.readFile(FALLBACK_CONFIG_PATH, 'utf8');
       const config = yaml.parse(content);
       this.cachedModules = config;
+      await prompts.log.warn('Could not reach BMad registry; using bundled module list.');
       return config;
     } catch (error) {
-      await prompts.log.warn(`Failed to load external modules config: ${error.message}`);
-      return { modules: {} };
+      await prompts.log.warn(`Failed to load modules config: ${error.message}`);
+      return { modules: [] };
     }
   }
 
   /**
-   * Get list of available external modules
+   * Normalize a module entry from either the remote registry format
+   * (snake_case, array) or the legacy bundled format (kebab-case, object map).
+   * @param {Object} mod - Raw module config from YAML
+   * @param {string} [key] - Key name (only for legacy map format)
+   * @returns {Object} Normalized module info
+   */
+  _normalizeModule(mod, key) {
+    return {
+      key: key || mod.name,
+      url: mod.repository || mod.url,
+      moduleDefinition: mod.module_definition || mod['module-definition'],
+      code: mod.code,
+      name: mod.display_name || mod.name,
+      description: mod.description || '',
+      defaultSelected: mod.default_selected === true || mod.defaultSelected === true,
+      type: mod.type || 'bmad-org',
+      npmPackage: mod.npm_package || mod.npmPackage || null,
+      builtIn: mod.built_in === true,
+      isExternal: mod.built_in !== true,
+    };
+  }
+
+  /**
+   * Get list of available modules from the registry
    * @returns {Array<Object>} Array of module info objects
    */
   async listAvailable() {
     const config = await this.loadExternalModulesConfig();
-    const modules = [];
 
-    for (const [key, moduleConfig] of Object.entries(config.modules || {})) {
-      modules.push({
-        key,
-        url: moduleConfig.url,
-        moduleDefinition: moduleConfig['module-definition'],
-        code: moduleConfig.code,
-        name: moduleConfig.name,
-        header: moduleConfig.header,
-        subheader: moduleConfig.subheader,
-        description: moduleConfig.description || '',
-        defaultSelected: moduleConfig.defaultSelected === true,
-        type: moduleConfig.type || 'community', // bmad-org or community
-        npmPackage: moduleConfig.npmPackage || null, // Include npm package name
-        isExternal: true,
-      });
+    // Remote format: modules is an array
+    if (Array.isArray(config.modules)) {
+      return config.modules.map((mod) => this._normalizeModule(mod));
     }
 
+    // Legacy bundled format: modules is an object map
+    const modules = [];
+    for (const [key, mod] of Object.entries(config.modules || {})) {
+      modules.push(this._normalizeModule(mod, key));
+    }
     return modules;
   }
 
@@ -81,27 +115,8 @@ class ExternalModuleManager {
    * @returns {Object|null} Module info or null if not found
    */
   async getModuleByKey(key) {
-    const config = await this.loadExternalModulesConfig();
-    const moduleConfig = config.modules?.[key];
-
-    if (!moduleConfig) {
-      return null;
-    }
-
-    return {
-      key,
-      url: moduleConfig.url,
-      moduleDefinition: moduleConfig['module-definition'],
-      code: moduleConfig.code,
-      name: moduleConfig.name,
-      header: moduleConfig.header,
-      subheader: moduleConfig.subheader,
-      description: moduleConfig.description || '',
-      defaultSelected: moduleConfig.defaultSelected === true,
-      type: moduleConfig.type || 'community', // bmad-org or community
-      npmPackage: moduleConfig.npmPackage || null, // Include npm package name
-      isExternal: true,
-    };
+    const modules = await this.listAvailable();
+    return modules.find((m) => m.key === key) || null;
   }
 
   /**
@@ -154,7 +169,7 @@ class ExternalModuleManager {
     const moduleInfo = await this.getModuleByCode(moduleCode);
 
     if (!moduleInfo) {
-      throw new Error(`External module '${moduleCode}' not found in external-official-modules.yaml`);
+      throw new Error(`External module '${moduleCode}' not found in the BMad registry`);
     }
 
     const cacheDir = this.getExternalCacheDir();
@@ -304,7 +319,7 @@ class ExternalModuleManager {
   async findExternalModuleSource(moduleCode, options = {}) {
     const moduleInfo = await this.getModuleByCode(moduleCode);
 
-    if (!moduleInfo) {
+    if (!moduleInfo || moduleInfo.builtIn) {
       return null;
     }
 
@@ -349,6 +364,7 @@ class ExternalModuleManager {
     // Nothing found: return configured path (preserves old behavior for error messaging)
     return path.dirname(configuredPath);
   }
+  cachedModules = null;
 }
 
 module.exports = { ExternalModuleManager };

package/tools/installer/modules/official-modules.js

@@ -202,6 +202,22 @@ class OfficialModules {
       return externalSource;
     }
 
+    // Check community modules
+    const { CommunityModuleManager } = require('./community-manager');
+    const communityMgr = new CommunityModuleManager();
+    const communitySource = await communityMgr.findModuleSource(moduleCode, options);
+    if (communitySource) {
+      return communitySource;
+    }
+
+    // Check custom modules (from user-provided URLs, already cloned to cache)
+    const { CustomModuleManager } = require('./custom-module-manager');
+    const customMgr = new CustomModuleManager();
+    const customSource = await customMgr.findModuleSourceByCode(moduleCode, options);
+    if (customSource) {
+      return customSource;
+    }
+
     return null;
   }
 
@@ -1131,7 +1147,13 @@ class OfficialModules {
       // Collect all answers (static + prompted)
       let allAnswers = { ...staticAnswers };
 
-      if (questions.length > 0) {
+      if (questions.length > 0 && silentMode) {
+        // In silent mode (quick update), use defaults for new fields instead of prompting
+        for (const q of questions) {
+          allAnswers[q.name] = typeof q.default === 'function' ? q.default({}) : q.default;
+        }
+        await prompts.log.message(`  \u2713 ${moduleName.toUpperCase()} module configured with defaults`);
+      } else if (questions.length > 0) {
         // Only show header if we actually have questions
         await CLIUtils.displayModuleConfigHeader(moduleName, moduleConfig.header, moduleConfig.subheader);
         await prompts.log.message('');

package/tools/installer/modules/registry-client.js

@@ -0,0 +1,66 @@
+const https = require('node:https');
+const yaml = require('yaml');
+
+/**
+ * Shared HTTP client for fetching registry data from GitHub.
+ * Used by ExternalModuleManager, CommunityModuleManager, and CustomModuleManager.
+ */
+class RegistryClient {
+  constructor(options = {}) {
+    this.timeout = options.timeout || 10_000;
+  }
+
+  /**
+   * Fetch a URL and return the response body as a string.
+   * Follows one redirect (GitHub sometimes 301s).
+   * @param {string} url - URL to fetch
+   * @param {number} [timeout] - Timeout in ms (overrides default)
+   * @returns {Promise<string>} Response body
+   */
+  fetch(url, timeout) {
+    const timeoutMs = timeout || this.timeout;
+    return new Promise((resolve, reject) => {
+      const req = https
+        .get(url, { timeout: timeoutMs }, (res) => {
+          if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+            return this.fetch(res.headers.location, timeoutMs).then(resolve, reject);
+          }
+          if (res.statusCode !== 200) {
+            return reject(new Error(`HTTP ${res.statusCode}`));
+          }
+          let data = '';
+          res.on('data', (chunk) => (data += chunk));
+          res.on('end', () => resolve(data));
+        })
+        .on('error', reject)
+        .on('timeout', () => {
+          req.destroy();
+          reject(new Error('Request timed out'));
+        });
+    });
+  }
+
+  /**
+   * Fetch a URL and parse the response as YAML.
+   * @param {string} url - URL to fetch
+   * @param {number} [timeout] - Timeout in ms
+   * @returns {Promise<Object>} Parsed YAML content
+   */
+  async fetchYaml(url, timeout) {
+    const content = await this.fetch(url, timeout);
+    return yaml.parse(content);
+  }
+
+  /**
+   * Fetch a URL and parse the response as JSON.
+   * @param {string} url - URL to fetch
+   * @param {number} [timeout] - Timeout in ms
+   * @returns {Promise<Object>} Parsed JSON content
+   */
+  async fetchJson(url, timeout) {
+    const content = await this.fetch(url, timeout);
+    return JSON.parse(content);
+  }
+}
+
+module.exports = { RegistryClient };

package/tools/installer/{external-official-modules.yaml → modules/registry-fallback.yaml}

@@ -1,5 +1,6 @@
-# This file allows these modules under bmad-code-org to also be installed with the bmad method installer, while
-# allowing us to keep the source of these projects in separate repos.
+# Fallback module registry — used only when the BMad Marketplace repo
+# (bmad-code-org/bmad-plugins-marketplace) is unreachable.
+# The remote registry/official.yaml is the source of truth.
 
 modules:
   bmad-builder:
@@ -41,13 +42,3 @@ modules:
     defaultSelected: false
     type: bmad-org
     npmPackage: bmad-method-test-architecture-enterprise
-
-  whiteport-design-studio:
-    url: https://github.com/bmad-code-org/bmad-method-wds-expansion
-    module-definition: src/module.yaml
-    code: wds
-    name: "Whiteport Design Studio (For UX Professionals)"
-    description: "Whiteport Design Studio (For UX Professionals)"
-    defaultSelected: false
-    type: community
-    npmPackage: bmad-method-wds-expansion