bmad-method 6.3.1-next.8 → 6.4.0

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

@@ -15,6 +15,11 @@ class OfficialModules {
     // Tracked during interactive config collection so {directory_name}
     // placeholder defaults can be resolved in buildQuestion().
     this.currentProjectDir = null;
+    // Install-time channel flag state. Set by Config.build once, then used as
+    // the default for every findModuleSource/cloneExternalModule call so that
+    // pre-install config collection and the install step agree on which ref
+    // to clone.
+    this.channelOptions = options.channelOptions || null;
   }
 
   /**
@@ -38,7 +43,7 @@ class OfficialModules {
    * @returns {OfficialModules}
    */
   static async build(config, paths) {
-    const instance = new OfficialModules();
+    const instance = new OfficialModules({ channelOptions: config.channelOptions });
 
     // Pre-collected by UI or quickUpdate — store and load existing for path-change detection
     if (config.moduleConfigs) {
@@ -196,6 +201,12 @@ class OfficialModules {
    * @returns {string|null} Path to the module source or null if not found
    */
   async findModuleSource(moduleCode, options = {}) {
+    // Inherit channelOptions from the install-scoped instance when the caller
+    // didn't pass one explicitly. Keeps pre-install config collection and the
+    // actual install step looking at the same git ref.
+    if (options.channelOptions === undefined && this.channelOptions) {
+      options = { ...options, channelOptions: this.channelOptions };
+    }
     const projectRoot = getProjectRoot();
 
     // Check for core module (directly under src/core-skills)
@@ -214,13 +225,13 @@ class OfficialModules {
       }
     }
 
-    // Check external official modules
+    // Check external official modules (pass channelOptions so channel plan applies)
     const externalSource = await this.externalModuleManager.findExternalModuleSource(moduleCode, options);
     if (externalSource) {
       return externalSource;
     }
 
-    // Check community modules
+    // Check community modules (pass channelOptions for --next/--pin overrides)
     const { CommunityModuleManager } = require('./community-manager');
     const communityMgr = new CommunityModuleManager();
     const communitySource = await communityMgr.findModuleSource(moduleCode, options);
@@ -258,7 +269,10 @@ class OfficialModules {
       return this.installFromResolution(resolved, bmadDir, fileTrackingCallback, options);
     }
 
-    const sourcePath = await this.findModuleSource(moduleName, { silent: options.silent });
+    const sourcePath = await this.findModuleSource(moduleName, {
+      silent: options.silent,
+      channelOptions: options.channelOptions,
+    });
     const targetPath = path.join(bmadDir, moduleName);
 
     if (!sourcePath) {
@@ -281,11 +295,24 @@ class OfficialModules {
     const manifestObj = new Manifest();
     const versionInfo = await manifestObj.getModuleVersionInfo(moduleName, bmadDir, sourcePath);
 
+    // Pick up channel resolution recorded by whichever manager did the clone.
+    const externalResolution = this.externalModuleManager.getResolution(moduleName);
+    let communityResolution = null;
+    if (!externalResolution) {
+      const { CommunityModuleManager } = require('./community-manager');
+      communityResolution = new CommunityModuleManager().getResolution(moduleName);
+    }
+    const resolution = externalResolution || communityResolution;
+
     await manifestObj.addModule(bmadDir, moduleName, {
-      version: versionInfo.version,
+      version: resolution?.version || versionInfo.version,
       source: versionInfo.source,
       npmPackage: versionInfo.npmPackage,
       repoUrl: versionInfo.repoUrl,
+      channel: resolution?.channel,
+      sha: resolution?.sha,
+      registryApprovedTag: communityResolution?.registryApprovedTag,
+      registryApprovedSha: communityResolution?.registryApprovedSha,
     });
 
     return { success: true, module: moduleName, path: targetPath, versionInfo };
@@ -333,18 +360,37 @@ class OfficialModules {
       await this.createModuleDirectories(resolved.code, bmadDir, options);
     }
 
-    // Update manifest
+    // Update manifest. For custom modules, derive channel from the git ref:
+    //   cloneRef present → pinned at that ref
+    //   cloneRef absent  → next (main HEAD)
+    //   local path       → no channel concept
     const { Manifest } = require('../core/manifest');
     const manifestObj = new Manifest();
 
-    await manifestObj.addModule(bmadDir, resolved.code, {
-      version: resolved.version || null,
+    const hasGitClone = !!resolved.repoUrl;
+    const manifestEntry = {
+      version: resolved.cloneRef || (hasGitClone ? 'main' : resolved.version || null),
       source: 'custom',
       npmPackage: null,
       repoUrl: resolved.repoUrl || null,
-    });
+    };
+    if (hasGitClone) {
+      manifestEntry.channel = resolved.cloneRef ? 'pinned' : 'next';
+      if (resolved.cloneSha) manifestEntry.sha = resolved.cloneSha;
+      if (resolved.rawInput) manifestEntry.rawSource = resolved.rawInput;
+    }
+    if (resolved.localPath) manifestEntry.localPath = resolved.localPath;
+    await manifestObj.addModule(bmadDir, resolved.code, manifestEntry);
 
-    return { success: true, module: resolved.code, path: targetPath, versionInfo: { version: resolved.version || '' } };
+    return {
+      success: true,
+      module: resolved.code,
+      path: targetPath,
+      // Match the manifestEntry.version expression above so downstream summary
+      // lines show the cloned ref (tag or 'main') instead of the on-disk
+      // package.json version for git-backed custom installs.
+      versionInfo: { version: resolved.cloneRef || (hasGitClone ? 'main' : resolved.version || '') },
+    };
   }
 
   /**
@@ -820,10 +866,10 @@ class OfficialModules {
     let foundAny = false;
     const entries = await fs.readdir(bmadDir, { withFileTypes: true });
 
+    const nonModuleDirs = new Set(['_config', '_memory', 'memory', 'docs', 'scripts', 'custom']);
     for (const entry of entries) {
       if (entry.isDirectory()) {
-        // Skip the _config directory - it's for system use
-        if (entry.name === '_config' || entry.name === '_memory') {
+        if (nonModuleDirs.has(entry.name)) {
           continue;
         }
 

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', () => {
@@ -50,6 +87,101 @@ class RegistryClient {
     const content = await this.fetch(url, timeout);
     return yaml.parse(content);
   }
+
+  /**
+   * 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
+   * @param {number} [maxRedirects=3] - Maximum redirects to follow
+   * @returns {Promise<string>} Response body
+   * @private
+   */
+  _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'));
+        });
+    });
+  }
 }
 
 module.exports = { RegistryClient };

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,
+};