bmad-method 6.3.1-next.2 → 6.3.1-next.21

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/modules/registry-fallback.yaml

@@ -1,6 +1,10 @@
 # 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.
+#
+# default_channel (optional) — the install channel when the user does not
+# override with --channel/--pin/--next. Valid values: stable | next.
+# Omit to inherit the installer's hardcoded default (stable).
 
 modules:
   bmad-builder:
@@ -12,6 +16,7 @@ modules:
     defaultSelected: false
     type: bmad-org
     npmPackage: bmad-builder
+    default_channel: stable
 
   bmad-creative-intelligence-suite:
     url: https://github.com/bmad-code-org/bmad-module-creative-intelligence-suite
@@ -22,6 +27,7 @@ modules:
     defaultSelected: false
     type: bmad-org
     npmPackage: bmad-creative-intelligence-suite
+    default_channel: stable
 
   bmad-game-dev-studio:
     url: https://github.com/bmad-code-org/bmad-module-game-dev-studio.git
@@ -32,6 +38,7 @@ modules:
     defaultSelected: false
     type: bmad-org
     npmPackage: bmad-game-dev-studio
+    default_channel: stable
 
   bmad-method-test-architecture-enterprise:
     url: https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise
@@ -42,3 +49,4 @@ modules:
     defaultSelected: false
     type: bmad-org
     npmPackage: bmad-method-test-architecture-enterprise
+    default_channel: stable

package/tools/installer/modules/version-resolver.js

@@ -0,0 +1,336 @@
+const path = require('node:path');
+const semver = require('semver');
+const yaml = require('yaml');
+const fs = require('../fs-native');
+const { getExternalModuleCachePath, getModulePath, resolveInstalledModuleYaml } = require('../project-root');
+
+const DEFAULT_PARENT_DEPTH = 8;
+
+/**
+ * Resolve a module version from authoritative on-disk metadata.
+ * Preference order:
+ *   1. package.json nearest the module source/cache root
+ *   2. module.yaml in the module source directory
+ *   3. .claude-plugin/marketplace.json
+ *   4. caller-provided fallback version
+ *
+ * @param {string} moduleName - Module code/name
+ * @param {Object} [options]
+ * @param {string} [options.moduleSourcePath] - Directory containing module.yaml
+ * @param {string} [options.fallbackVersion] - Final fallback when no metadata is found
+ * @param {string[]} [options.marketplacePluginNames] - Preferred marketplace plugin names
+ * @returns {Promise<{version: string|null, source: string|null, path: string|null}>}
+ */
+async function resolveModuleVersion(moduleName, options = {}) {
+  const moduleSourcePath = await normalizeDirectoryPath(options.moduleSourcePath);
+  const packageJsonPath = await findPackageJsonPath(moduleName, moduleSourcePath);
+
+  if (packageJsonPath) {
+    const packageVersion = await readPackageJsonVersion(packageJsonPath);
+    if (packageVersion) {
+      return {
+        version: packageVersion,
+        source: 'package.json',
+        path: packageJsonPath,
+      };
+    }
+  }
+
+  const moduleYamlPath = await findModuleYamlPath(moduleName, moduleSourcePath);
+  if (moduleYamlPath) {
+    const moduleVersion = await readModuleYamlVersion(moduleYamlPath);
+    if (moduleVersion) {
+      return {
+        version: moduleVersion,
+        source: 'module.yaml',
+        path: moduleYamlPath,
+      };
+    }
+  }
+
+  const marketplaceVersion = await findMarketplaceVersion(moduleName, moduleSourcePath, options.marketplacePluginNames || []);
+  if (marketplaceVersion) {
+    return marketplaceVersion;
+  }
+
+  const fallbackVersion = normalizeVersion(options.fallbackVersion);
+  if (fallbackVersion) {
+    return {
+      version: fallbackVersion,
+      source: 'fallback',
+      path: null,
+    };
+  }
+
+  return {
+    version: null,
+    source: null,
+    path: null,
+  };
+}
+
+async function findPackageJsonPath(moduleName, moduleSourcePath) {
+  const roots = await buildSearchRoots(moduleName, moduleSourcePath);
+
+  for (const root of roots) {
+    const packageJsonPath = await findNearestUpwardFile(root.searchDir, 'package.json', { boundaryDir: root.boundaryDir });
+    if (packageJsonPath) {
+      return packageJsonPath;
+    }
+  }
+
+  return null;
+}
+
+async function findModuleYamlPath(moduleName, moduleSourcePath) {
+  if (moduleSourcePath) {
+    const directModuleYamlPath = path.join(moduleSourcePath, 'module.yaml');
+    if (await fs.pathExists(directModuleYamlPath)) {
+      return directModuleYamlPath;
+    }
+  }
+
+  return resolveInstalledModuleYaml(moduleName);
+}
+
+async function findMarketplaceVersion(moduleName, moduleSourcePath, marketplacePluginNames) {
+  const roots = await buildSearchRoots(moduleName, moduleSourcePath);
+
+  for (const root of roots) {
+    const marketplacePath = await findNearestUpwardFile(root.searchDir, path.join('.claude-plugin', 'marketplace.json'), {
+      boundaryDir: root.boundaryDir,
+    });
+    if (!marketplacePath) {
+      continue;
+    }
+
+    const data = await readJsonFile(marketplacePath);
+    if (!data) {
+      continue;
+    }
+
+    const version = extractMarketplaceVersion(data, moduleName, marketplacePluginNames);
+    if (version) {
+      return {
+        version,
+        source: 'marketplace.json',
+        path: marketplacePath,
+      };
+    }
+  }
+
+  return null;
+}
+
+async function buildSearchRoots(moduleName, moduleSourcePath) {
+  const roots = [];
+  const seen = new Set();
+
+  const addRoot = async (candidate) => {
+    const normalized = await normalizeExistingDirectory(candidate);
+    if (!normalized || seen.has(normalized)) {
+      return;
+    }
+
+    seen.add(normalized);
+    roots.push({
+      searchDir: normalized,
+      boundaryDir: await findSearchBoundary(normalized),
+    });
+  };
+
+  await addRoot(moduleSourcePath);
+
+  if (moduleName === 'core' || moduleName === 'bmm') {
+    await addRoot(getModulePath(moduleName));
+  } else {
+    await addRoot(getExternalModuleCachePath(moduleName));
+  }
+
+  return roots;
+}
+
+async function findNearestUpwardFile(startDir, relativeFilePath, options = {}) {
+  const normalizedStartDir = await normalizeExistingDirectory(startDir);
+  if (!normalizedStartDir) {
+    return null;
+  }
+
+  const maxDepth = options.maxDepth ?? DEFAULT_PARENT_DEPTH;
+  const normalizedBoundaryDir = await normalizeDirectoryPath(options.boundaryDir);
+  let currentDir = normalizedStartDir;
+  for (let depth = 0; depth <= maxDepth; depth++) {
+    const candidate = path.join(currentDir, relativeFilePath);
+    if (await fs.pathExists(candidate)) {
+      return candidate;
+    }
+
+    if (normalizedBoundaryDir && currentDir === normalizedBoundaryDir) {
+      break;
+    }
+
+    const parentDir = path.dirname(currentDir);
+    if (parentDir === currentDir) {
+      break;
+    }
+    currentDir = parentDir;
+  }
+
+  return null;
+}
+
+async function findSearchBoundary(startDir) {
+  const normalizedStartDir = await normalizeExistingDirectory(startDir);
+  if (!normalizedStartDir) {
+    return null;
+  }
+
+  let currentDir = normalizedStartDir;
+  for (let depth = 0; depth <= DEFAULT_PARENT_DEPTH; depth++) {
+    if (
+      (await fs.pathExists(path.join(currentDir, 'package.json'))) ||
+      (await fs.pathExists(path.join(currentDir, '.claude-plugin', 'marketplace.json'))) ||
+      (await fs.pathExists(path.join(currentDir, '.git')))
+    ) {
+      return currentDir;
+    }
+
+    const parentDir = path.dirname(currentDir);
+    if (parentDir === currentDir) {
+      break;
+    }
+    currentDir = parentDir;
+  }
+
+  return normalizedStartDir;
+}
+
+async function normalizeDirectoryPath(candidate) {
+  if (!candidate) {
+    return null;
+  }
+
+  const resolvedPath = path.resolve(candidate);
+  try {
+    const stats = await fs.stat(resolvedPath);
+    return stats.isDirectory() ? resolvedPath : path.dirname(resolvedPath);
+  } catch {
+    return resolvedPath;
+  }
+}
+
+async function normalizeExistingDirectory(candidate) {
+  const normalized = await normalizeDirectoryPath(candidate);
+  if (!normalized) {
+    return null;
+  }
+
+  if (!(await fs.pathExists(normalized))) {
+    return null;
+  }
+
+  return normalized;
+}
+
+async function readPackageJsonVersion(packageJsonPath) {
+  const data = await readJsonFile(packageJsonPath);
+  return normalizeVersion(data?.version);
+}
+
+async function readModuleYamlVersion(moduleYamlPath) {
+  try {
+    const content = await fs.readFile(moduleYamlPath, 'utf8');
+    const data = yaml.parse(content);
+    return normalizeVersion(data?.version || data?.module_version || data?.moduleVersion);
+  } catch {
+    return null;
+  }
+}
+
+async function readJsonFile(filePath) {
+  try {
+    const content = await fs.readFile(filePath, 'utf8');
+    return JSON.parse(content);
+  } catch {
+    return null;
+  }
+}
+
+function extractMarketplaceVersion(data, moduleName, marketplacePluginNames = []) {
+  const plugins = Array.isArray(data?.plugins) ? data.plugins : [];
+  if (plugins.length === 0) {
+    return null;
+  }
+
+  const preferredNames = new Set(
+    [moduleName, ...marketplacePluginNames]
+      .filter((value) => typeof value === 'string')
+      .map((value) => value.trim())
+      .filter(Boolean),
+  );
+
+  const exactMatches = [];
+  const fallbackVersions = [];
+
+  for (const plugin of plugins) {
+    const version = normalizeVersion(plugin?.version);
+    if (!version) {
+      continue;
+    }
+
+    fallbackVersions.push(version);
+
+    const pluginNames = [plugin?.name, plugin?.code].filter((value) => typeof value === 'string').map((value) => value.trim());
+    if (pluginNames.some((name) => preferredNames.has(name))) {
+      exactMatches.push(version);
+    }
+  }
+
+  return pickBestVersion(exactMatches.length > 0 ? exactMatches : fallbackVersions);
+}
+
+function pickBestVersion(versions) {
+  const candidates = versions.map(normalizeVersion).filter(Boolean);
+  if (candidates.length === 0) {
+    return null;
+  }
+
+  candidates.sort(compareVersionsDescending);
+  return candidates[0];
+}
+
+function compareVersionsDescending(left, right) {
+  const leftSemver = normalizeSemver(left);
+  const rightSemver = normalizeSemver(right);
+
+  if (leftSemver && rightSemver) {
+    return semver.rcompare(leftSemver, rightSemver);
+  }
+
+  if (leftSemver) {
+    return -1;
+  }
+
+  if (rightSemver) {
+    return 1;
+  }
+
+  return right.localeCompare(left, undefined, { numeric: true, sensitivity: 'base' });
+}
+
+function normalizeSemver(version) {
+  return semver.valid(version) || semver.valid(semver.coerce(version));
+}
+
+function normalizeVersion(version) {
+  if (typeof version !== 'string') {
+    return null;
+  }
+
+  const trimmed = version.trim();
+  return trimmed || null;
+}
+
+module.exports = {
+  resolveModuleVersion,
+};

package/tools/installer/project-root.js

@@ -1,5 +1,6 @@
 const path = require('node:path');
-const fs = require('fs-extra');
+const os = require('node:os');
+const fs = require('./fs-native');
 
 /**
  * Find the BMAD project root directory by looking for package.json
@@ -69,9 +70,62 @@ function getModulePath(moduleName, ...segments) {
   return getSourcePath('modules', moduleName, ...segments);
 }
 
+/**
+ * Path to the local external-module clone cache.
+ * External official modules (bmb, cis, gds, tea, wds, etc.) are cloned here
+ * by ExternalModuleManager during install and are not copied into <src>/modules/.
+ */
+function getExternalModuleCachePath(moduleName, ...segments) {
+  const base = process.env.BMAD_EXTERNAL_MODULES_CACHE || path.join(os.homedir(), '.bmad', 'cache', 'external-modules');
+  return path.join(base, moduleName, ...segments);
+}
+
+/**
+ * Locate an installed module's `module.yaml` by filesystem lookup only.
+ *
+ * Built-in modules (core, bmm) live under <src>. External official modules are
+ * cloned into ~/.bmad/cache/external-modules/<name>/ with varying internal
+ * layouts (some at src/module.yaml, some at skills/module.yaml, some nested).
+ * This mirrors the candidate-path search in
+ * ExternalModuleManager.findExternalModuleSource but performs no git/network
+ * work, which keeps it safe to call during manifest writing.
+ *
+ * @param {string} moduleName
+ * @returns {Promise<string|null>} Absolute path to module.yaml, or null if not found.
+ */
+async function resolveInstalledModuleYaml(moduleName) {
+  const builtIn = path.join(getModulePath(moduleName), 'module.yaml');
+  if (await fs.pathExists(builtIn)) return builtIn;
+
+  const cacheRoot = getExternalModuleCachePath(moduleName);
+  if (!(await fs.pathExists(cacheRoot))) return null;
+
+  for (const dir of ['skills', 'src']) {
+    const direct = path.join(cacheRoot, dir, 'module.yaml');
+    if (await fs.pathExists(direct)) return direct;
+
+    const dirPath = path.join(cacheRoot, dir);
+    if (await fs.pathExists(dirPath)) {
+      const entries = await fs.readdir(dirPath, { withFileTypes: true });
+      for (const entry of entries) {
+        if (!entry.isDirectory()) continue;
+        const nested = path.join(dirPath, entry.name, 'module.yaml');
+        if (await fs.pathExists(nested)) return nested;
+      }
+    }
+  }
+
+  const atRoot = path.join(cacheRoot, 'module.yaml');
+  if (await fs.pathExists(atRoot)) return atRoot;
+
+  return null;
+}
+
 module.exports = {
   getProjectRoot,
   getSourcePath,
   getModulePath,
+  getExternalModuleCachePath,
+  resolveInstalledModuleYaml,
   findProjectRoot,
 };