bmad-method 6.3.1-next.1 → 6.3.1-next.11

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

@@ -1,6 +1,37 @@
 const https = require('node:https');
 const yaml = require('yaml');
 
+/**
+ * Build a rich Error from a non-2xx response. Includes the URL, the GitHub
+ * JSON error message (or a truncated body snippet), rate-limit reset time,
+ * and Retry-After — anything present that would help a user recover.
+ */
+function buildHttpError(url, res, body) {
+  const parts = [`HTTP ${res.statusCode} ${url}`];
+
+  if (body) {
+    try {
+      const parsed = JSON.parse(body);
+      if (parsed.message) parts.push(parsed.message);
+      if (parsed.documentation_url) parts.push(`(see ${parsed.documentation_url})`);
+    } catch {
+      const snippet = body.slice(0, 200).trim();
+      if (snippet) parts.push(snippet);
+    }
+  }
+
+  const remaining = res.headers['x-ratelimit-remaining'];
+  const reset = res.headers['x-ratelimit-reset'];
+  if (remaining === '0' && reset) {
+    parts.push(`rate limit exhausted; resets at ${new Date(Number(reset) * 1000).toISOString()}`);
+  }
+
+  const retryAfter = res.headers['retry-after'];
+  if (retryAfter) parts.push(`retry after ${retryAfter}`);
+
+  return new Error(parts.join(' — '));
+}
+
 /**
  * Shared HTTP client for fetching registry data from GitHub.
  * Used by ExternalModuleManager, CommunityModuleManager, and CustomModuleManager.
@@ -12,25 +43,31 @@ class RegistryClient {
 
   /**
    * Fetch a URL and return the response body as a string.
-   * Follows one redirect (GitHub sometimes 301s).
+   * Follows up to 3 redirects (GitHub sometimes 301s).
    * @param {string} url - URL to fetch
    * @param {number} [timeout] - Timeout in ms (overrides default)
+   * @param {number} [maxRedirects=3] - Maximum redirects to follow
    * @returns {Promise<string>} Response body
    */
-  fetch(url, timeout) {
+  fetch(url, timeout, maxRedirects = 3) {
     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}`));
+            if (maxRedirects <= 0) {
+              return reject(new Error('Too many redirects'));
+            }
+            return this.fetch(res.headers.location, timeoutMs, maxRedirects - 1).then(resolve, reject);
           }
           let data = '';
           res.on('data', (chunk) => (data += chunk));
-          res.on('end', () => resolve(data));
+          res.on('end', () => {
+            if (res.statusCode !== 200) {
+              return reject(buildHttpError(url, res, data));
+            }
+            resolve(data);
+          });
         })
         .on('error', reject)
         .on('timeout', () => {
@@ -52,14 +89,98 @@ class RegistryClient {
   }
 
   /**
-   * Fetch a URL and parse the response as JSON.
+   * Fetch a file from a GitHub repo using the Contents API first,
+   * falling back to raw.githubusercontent.com if the API fails.
+   *
+   * The API endpoint (`api.github.com`) is tried first because corporate
+   * proxies commonly block `raw.githubusercontent.com` while allowing
+   * `api.github.com` under the "Software Development" category.
+   *
+   * @param {string} owner - Repository owner (e.g., 'bmad-code-org')
+   * @param {string} repo  - Repository name (e.g., 'bmad-plugins-marketplace')
+   * @param {string} filePath - Path within the repo (e.g., 'registry/official.yaml')
+   * @param {string} ref   - Git ref (branch, tag, or SHA; e.g., 'main')
+   * @param {number} [timeout] - Timeout in ms (overrides default)
+   * @returns {Promise<string>} Raw file content
+   */
+  async fetchGitHubFile(owner, repo, filePath, ref, timeout) {
+    const apiUrl = `https://api.github.com/repos/${owner}/${repo}/contents/${filePath}?ref=${ref}`;
+    const rawUrl = `https://raw.githubusercontent.com/${owner}/${repo}/${ref}/${filePath}`;
+
+    // Try GitHub Contents API first (with raw content accept header)
+    try {
+      return await this._fetchWithHeaders(apiUrl, { Accept: 'application/vnd.github.raw+json' }, timeout);
+    } catch (apiError) {
+      // API failed — fall back to raw CDN
+      try {
+        return await this.fetch(rawUrl, timeout);
+      } catch (cdnError) {
+        throw new AggregateError([apiError, cdnError], `Both GitHub API and raw CDN failed for ${filePath}`);
+      }
+    }
+  }
+
+  /**
+   * Fetch a file from GitHub and parse as YAML.
+   * @param {string} owner - Repository owner
+   * @param {string} repo  - Repository name
+   * @param {string} filePath - Path within the repo
+   * @param {string} ref   - Git ref
+   * @param {number} [timeout] - Timeout in ms
+   * @returns {Promise<Object>} Parsed YAML content
+   */
+  async fetchGitHubYaml(owner, repo, filePath, ref, timeout) {
+    const content = await this.fetchGitHubFile(owner, repo, filePath, ref, timeout);
+    return yaml.parse(content);
+  }
+
+  /**
+   * Fetch a URL with custom headers. Used for GitHub API requests.
+   * Follows up to 3 redirects.
    * @param {string} url - URL to fetch
+   * @param {Object} headers - Request headers
    * @param {number} [timeout] - Timeout in ms
-   * @returns {Promise<Object>} Parsed JSON content
+   * @param {number} [maxRedirects=3] - Maximum redirects to follow
+   * @returns {Promise<string>} Response body
+   * @private
    */
-  async fetchJson(url, timeout) {
-    const content = await this.fetch(url, timeout);
-    return JSON.parse(content);
+  _fetchWithHeaders(url, headers, timeout, maxRedirects = 3) {
+    const timeoutMs = timeout || this.timeout;
+    const parsed = new URL(url);
+    const options = {
+      hostname: parsed.hostname,
+      path: parsed.pathname + parsed.search,
+      timeout: timeoutMs,
+      headers: {
+        'User-Agent': 'bmad-installer',
+        ...headers,
+      },
+    };
+
+    return new Promise((resolve, reject) => {
+      const req = https
+        .get(options, (res) => {
+          if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+            if (maxRedirects <= 0) {
+              return reject(new Error('Too many redirects'));
+            }
+            return this._fetchWithHeaders(res.headers.location, headers, timeoutMs, maxRedirects - 1).then(resolve, reject);
+          }
+          let data = '';
+          res.on('data', (chunk) => (data += chunk));
+          res.on('end', () => {
+            if (res.statusCode !== 200) {
+              return reject(buildHttpError(url, res, data));
+            }
+            resolve(data);
+          });
+        })
+        .on('error', reject)
+        .on('timeout', () => {
+          req.destroy();
+          reject(new Error('Request timed out'));
+        });
+    });
   }
 }
 

package/tools/installer/project-root.js

@@ -1,5 +1,5 @@
 const path = require('node:path');
-const fs = require('fs-extra');
+const fs = require('./fs-native');
 
 /**
  * Find the BMAD project root directory by looking for package.json

package/tools/installer/prompts.js

@@ -498,26 +498,6 @@ async function password(options) {
   return result;
 }
 
-/**
- * Group multiple prompts together
- * @param {Object} prompts - Object of prompt functions
- * @param {Object} [options] - Group options
- * @returns {Promise<Object>} Object with all answers
- */
-async function group(prompts, options = {}) {
-  const clack = await getClack();
-
-  const result = await clack.group(prompts, {
-    onCancel: () => {
-      clack.cancel('Operation cancelled');
-      process.exit(0);
-    },
-    ...options,
-  });
-
-  return result;
-}
-
 /**
  * Run tasks with spinner feedback
  * @param {Array} tasks - Array of task objects [{title, task, enabled?}]
@@ -578,42 +558,6 @@ async function box(content, title, options) {
   clack.box(content, title, options);
 }
 
-/**
- * Create a progress bar for visualizing task completion
- * @param {Object} [options] - Progress options (max, style, etc.)
- * @returns {Promise<Object>} Progress controller with start, advance, stop methods
- */
-async function progress(options) {
-  const clack = await getClack();
-  return clack.progress(options);
-}
-
-/**
- * Create a task log for displaying scrolling subprocess output
- * @param {Object} options - TaskLog options (title, limit, retainLog)
- * @returns {Promise<Object>} TaskLog controller with message, success, error methods
- */
-async function taskLog(options) {
-  const clack = await getClack();
-  return clack.taskLog(options);
-}
-
-/**
- * File system path prompt with autocomplete
- * @param {Object} options - Path options
- * @param {string} options.message - The prompt message
- * @param {string} [options.initialValue] - Initial path value
- * @param {boolean} [options.directory=false] - Only allow directories
- * @param {Function} [options.validate] - Validation function
- * @returns {Promise<string>} Selected path
- */
-async function pathPrompt(options) {
-  const clack = await getClack();
-  const result = await clack.path(options);
-  await handleCancel(result);
-  return result;
-}
-
 /**
  * Autocomplete single-select prompt with type-ahead filtering
  * @param {Object} options - Autocomplete options
@@ -631,50 +575,6 @@ async function autocomplete(options) {
   return result;
 }
 
-/**
- * Key-based instant selection prompt
- * @param {Object} options - SelectKey options
- * @param {string} options.message - The prompt message
- * @param {Array} options.options - Array of choices [{value, label, hint?}]
- * @returns {Promise<any>} Selected value
- */
-async function selectKey(options) {
-  const clack = await getClack();
-  const result = await clack.selectKey(options);
-  await handleCancel(result);
-  return result;
-}
-
-/**
- * Stream messages with dynamic content (for LLMs, generators, etc.)
- */
-const stream = {
-  async info(generator) {
-    const clack = await getClack();
-    return clack.stream.info(generator);
-  },
-  async success(generator) {
-    const clack = await getClack();
-    return clack.stream.success(generator);
-  },
-  async step(generator) {
-    const clack = await getClack();
-    return clack.stream.step(generator);
-  },
-  async warn(generator) {
-    const clack = await getClack();
-    return clack.stream.warn(generator);
-  },
-  async error(generator) {
-    const clack = await getClack();
-    return clack.stream.error(generator);
-  },
-  async message(generator, options) {
-    const clack = await getClack();
-    return clack.stream.message(generator, options);
-  },
-};
-
 /**
  * Get the color utility (picocolors instance from @clack/prompts)
  * @returns {Promise<Object>} The color utility (picocolors)
@@ -790,20 +690,14 @@ module.exports = {
   note,
   box,
   spinner,
-  progress,
-  taskLog,
   select,
   multiselect,
   autocompleteMultiselect,
   autocomplete,
-  selectKey,
   confirm,
   text,
-  path: pathPrompt,
   password,
-  group,
   tasks,
   log,
-  stream,
   prompt,
 };

package/tools/installer/ui.js

@@ -1,6 +1,6 @@
 const path = require('node:path');
 const os = require('node:os');
-const fs = require('fs-extra');
+const fs = require('./fs-native');
 const { CLIUtils } = require('./cli-utils');
 const { ExternalModuleManager } = require('./modules/external-manager');
 const { getProjectRoot } = require('./project-root');
@@ -598,7 +598,7 @@ class UI {
     const officialCodes = new Set(officialSelected);
     const externalManager = new ExternalModuleManager();
     const registryModules = await externalManager.listAvailable();
-    const officialRegistryCodes = new Set(registryModules.map((m) => m.code));
+    const officialRegistryCodes = new Set(['core', 'bmm', ...registryModules.map((m) => m.code)]);
     const installedNonOfficial = [...installedModuleIds].filter((id) => !officialRegistryCodes.has(id));
 
     // Phase 2: Community modules (category drill-down)
@@ -630,6 +630,11 @@ class UI {
    * @returns {Array} Selected official module codes
    */
   async _selectOfficialModules(installedModuleIds = new Set()) {
+    // Built-in modules (core, bmm) come from local source, not the registry
+    const { OfficialModules } = require('./modules/official-modules');
+    const builtInModules = (await new OfficialModules().listAvailable()).modules || [];
+
+    // External modules come from the registry (with fallback)
     const externalManager = new ExternalModuleManager();
     const registryModules = await externalManager.listAvailable();
 
@@ -637,20 +642,34 @@ class UI {
     const initialValues = [];
     const lockedValues = ['core'];
 
-    const buildModuleEntry = async (mod) => {
-      const isInstalled = installedModuleIds.has(mod.code);
-      const version = await getMarketplaceVersion(mod.code);
-      const label = version ? `${mod.name} (v${version})` : mod.name;
+    const buildModuleEntry = async (code, name, description, isDefault) => {
+      const isInstalled = installedModuleIds.has(code);
+      const version = await getMarketplaceVersion(code);
+      const label = version ? `${name} (v${version})` : name;
       return {
         label,
-        value: mod.code,
-        hint: mod.description,
-        selected: isInstalled,
+        value: code,
+        hint: description,
+        selected: isInstalled || isDefault,
       };
     };
 
+    // Add built-in modules first (always available regardless of network)
+    const builtInCodes = new Set();
+    for (const mod of builtInModules) {
+      const code = mod.id;
+      builtInCodes.add(code);
+      const entry = await buildModuleEntry(code, mod.name, mod.description, mod.defaultSelected);
+      allOptions.push({ label: entry.label, value: entry.value, hint: entry.hint });
+      if (entry.selected) {
+        initialValues.push(code);
+      }
+    }
+
+    // Add external registry modules (skip built-in duplicates)
     for (const mod of registryModules) {
-      const entry = await buildModuleEntry(mod);
+      if (mod.builtIn || builtInCodes.has(mod.code)) continue;
+      const entry = await buildModuleEntry(mod.code, mod.name, mod.description, mod.defaultSelected);
       allOptions.push({ label: entry.label, value: entry.value, hint: entry.hint });
       if (entry.selected) {
         initialValues.push(mod.code);
@@ -1122,12 +1141,26 @@ class UI {
    * @returns {Array} Default module codes
    */
   async getDefaultModules(installedModuleIds = new Set()) {
-    const externalManager = new ExternalModuleManager();
-    const registryModules = await externalManager.listAvailable();
+    // Built-in modules with default_selected come from local source
+    const { OfficialModules } = require('./modules/official-modules');
+    const builtInModules = (await new OfficialModules().listAvailable()).modules || [];
 
     const defaultModules = [];
+    const seen = new Set();
+
+    for (const mod of builtInModules) {
+      if (mod.defaultSelected || installedModuleIds.has(mod.id)) {
+        defaultModules.push(mod.id);
+        seen.add(mod.id);
+      }
+    }
+
+    // Add external registry defaults
+    const externalManager = new ExternalModuleManager();
+    const registryModules = await externalManager.listAvailable();
 
     for (const mod of registryModules) {
+      if (mod.builtIn || seen.has(mod.code)) continue;
       if (mod.defaultSelected || installedModuleIds.has(mod.code)) {
         defaultModules.push(mod.code);
       }

package/tools/migrate-custom-module-paths.js

@@ -3,7 +3,7 @@
  * This should be run once to update existing installations
  */
 
-const fs = require('fs-extra');
+const fs = require('./installer/fs-native');
 const path = require('node:path');
 const yaml = require('yaml');
 const chalk = require('chalk');

package/tools/installer/ide/shared/agent-command-generator.js

@@ -1,180 +0,0 @@
-const path = require('node:path');
-const fs = require('fs-extra');
-const { toColonPath, toDashPath, customAgentColonName, customAgentDashName, BMAD_FOLDER_NAME } = require('./path-utils');
-
-/**
- * Generates launcher command files for each agent
- */
-class AgentCommandGenerator {
-  constructor(bmadFolderName = BMAD_FOLDER_NAME) {
-    this.templatePath = path.join(__dirname, '../templates/agent-command-template.md');
-    this.bmadFolderName = bmadFolderName;
-  }
-
-  /**
-   * Collect agent artifacts for IDE installation
-   * @param {string} bmadDir - BMAD installation directory
-   * @param {Array} selectedModules - Modules to include
-   * @returns {Object} Artifacts array with metadata
-   */
-  async collectAgentArtifacts(bmadDir, selectedModules = []) {
-    const { getAgentsFromBmad } = require('./bmad-artifacts');
-
-    // Get agents from INSTALLED bmad/ directory
-    const agents = await getAgentsFromBmad(bmadDir, selectedModules);
-
-    const artifacts = [];
-
-    for (const agent of agents) {
-      const launcherContent = await this.generateLauncherContent(agent);
-      // Use relativePath if available (for nested agents), otherwise just name with .md
-      const agentPathInModule = agent.relativePath || `${agent.name}.md`;
-      // Calculate the relative agent path (e.g., bmm/agents/pm.md)
-      let agentRelPath = agent.path || '';
-      // Normalize path separators for cross-platform compatibility
-      agentRelPath = agentRelPath.replaceAll('\\', '/');
-      // Remove _bmad/ prefix if present to get relative path from project root
-      // Handle both absolute paths (/path/to/_bmad/...) and relative paths (_bmad/...)
-      if (agentRelPath.includes('_bmad/')) {
-        const parts = agentRelPath.split(/_bmad\//);
-        if (parts.length > 1) {
-          agentRelPath = parts.slice(1).join('/');
-        }
-      }
-      artifacts.push({
-        type: 'agent-launcher',
-        name: agent.name,
-        description: agent.description || `${agent.name} agent`,
-        module: agent.module,
-        canonicalId: agent.canonicalId || '',
-        relativePath: path.join(agent.module, 'agents', agentPathInModule), // For command filename
-        agentPath: agentRelPath, // Relative path to actual agent file
-        content: launcherContent,
-        sourcePath: agent.path,
-      });
-    }
-
-    return {
-      artifacts,
-      counts: {
-        agents: agents.length,
-      },
-    };
-  }
-
-  /**
-   * Generate launcher content for an agent
-   * @param {Object} agent - Agent metadata
-   * @returns {string} Launcher file content
-   */
-  async generateLauncherContent(agent) {
-    // Load the template
-    const template = await fs.readFile(this.templatePath, 'utf8');
-
-    // Replace template variables
-    // Use relativePath if available (for nested agents), otherwise just name with .md
-    const agentPathInModule = agent.relativePath || `${agent.name}.md`;
-    return template
-      .replaceAll('{{name}}', agent.name)
-      .replaceAll('{{module}}', agent.module)
-      .replaceAll('{{path}}', agentPathInModule)
-      .replaceAll('{{description}}', agent.description || `${agent.name} agent`)
-      .replaceAll('_bmad', this.bmadFolderName)
-      .replaceAll('_bmad', '_bmad');
-  }
-
-  /**
-   * Write agent launcher artifacts to IDE commands directory
-   * @param {string} baseCommandsDir - Base commands directory for the IDE
-   * @param {Array} artifacts - Agent launcher artifacts
-   * @returns {number} Count of launchers written
-   */
-  async writeAgentLaunchers(baseCommandsDir, artifacts) {
-    let writtenCount = 0;
-
-    for (const artifact of artifacts) {
-      if (artifact.type === 'agent-launcher') {
-        const moduleAgentsDir = path.join(baseCommandsDir, artifact.module, 'agents');
-        await fs.ensureDir(moduleAgentsDir);
-
-        const launcherPath = path.join(moduleAgentsDir, `${artifact.name}.md`);
-        await fs.writeFile(launcherPath, artifact.content);
-        writtenCount++;
-      }
-    }
-
-    return writtenCount;
-  }
-
-  /**
-   * Write agent launcher artifacts using underscore format (Windows-compatible)
-   * Creates flat files like: bmad_bmm_pm.md
-   *
-   * @param {string} baseCommandsDir - Base commands directory for the IDE
-   * @param {Array} artifacts - Agent launcher artifacts
-   * @returns {number} Count of launchers written
-   */
-  async writeColonArtifacts(baseCommandsDir, artifacts) {
-    let writtenCount = 0;
-
-    for (const artifact of artifacts) {
-      if (artifact.type === 'agent-launcher') {
-        // Convert relativePath to underscore format: bmm/agents/pm.md → bmad_bmm_pm.md
-        const flatName = toColonPath(artifact.relativePath);
-        const launcherPath = path.join(baseCommandsDir, flatName);
-        await fs.ensureDir(path.dirname(launcherPath));
-        await fs.writeFile(launcherPath, artifact.content);
-        writtenCount++;
-      }
-    }
-
-    return writtenCount;
-  }
-
-  /**
-   * Write agent launcher artifacts using dash format (NEW STANDARD)
-   * Creates flat files like: bmad-agent-bmm-pm.md
-   *
-   * The bmad-agent- prefix distinguishes agents from workflows/tasks/tools.
-   *
-   * @param {string} baseCommandsDir - Base commands directory for the IDE
-   * @param {Array} artifacts - Agent launcher artifacts
-   * @returns {number} Count of launchers written
-   */
-  async writeDashArtifacts(baseCommandsDir, artifacts) {
-    let writtenCount = 0;
-
-    for (const artifact of artifacts) {
-      if (artifact.type === 'agent-launcher') {
-        // Convert relativePath to dash format: bmm/agents/pm.md → bmad-agent-bmm-pm.md
-        const flatName = toDashPath(artifact.relativePath);
-        const launcherPath = path.join(baseCommandsDir, flatName);
-        await fs.ensureDir(path.dirname(launcherPath));
-        await fs.writeFile(launcherPath, artifact.content);
-        writtenCount++;
-      }
-    }
-
-    return writtenCount;
-  }
-
-  /**
-   * Get the custom agent name in underscore format (Windows-compatible)
-   * @param {string} agentName - Custom agent name
-   * @returns {string} Underscore-formatted filename
-   */
-  getCustomAgentColonName(agentName) {
-    return customAgentColonName(agentName);
-  }
-
-  /**
-   * Get the custom agent name in underscore format (Windows-compatible)
-   * @param {string} agentName - Custom agent name
-   * @returns {string} Underscore-formatted filename
-   */
-  getCustomAgentDashName(agentName) {
-    return customAgentDashName(agentName);
-  }
-}
-
-module.exports = { AgentCommandGenerator };