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

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "bmad-method",
-  "version": "6.3.1-next.20",
+  "version": "6.3.1-next.21",
   "description": "Breakthrough Method of Agile AI-driven Development",
   "keywords": [
     "agile",
@@ -41,7 +41,8 @@
     "prepare": "command -v husky >/dev/null 2>&1 && husky || exit 0",
     "quality": "npm run format:check && npm run lint && npm run lint:md && npm run docs:build && npm run test:install && npm run validate:refs && npm run validate:skills",
     "rebundle": "node tools/installer/bundlers/bundle-web.js rebundle",
-    "test": "npm run test:refs && npm run test:install && npm run lint && npm run lint:md && npm run format:check",
+    "test": "npm run test:refs && npm run test:install && npm run test:channels && npm run lint && npm run lint:md && npm run format:check",
+    "test:channels": "node test/test-installer-channels.js",
     "test:install": "node test/test-installation-components.js",
     "test:refs": "node test/test-file-refs-csv.js",
     "validate:refs": "node tools/validate-file-refs.js --strict",

package/tools/installer/commands/install.js

@@ -24,6 +24,19 @@ module.exports = {
     ['--output-folder <path>', 'Output folder path relative to project root (default: _bmad-output)'],
     ['--custom-source <sources>', 'Comma-separated Git URLs or local paths to install custom modules from'],
     ['-y, --yes', 'Accept all defaults and skip prompts where possible'],
+    [
+      '--channel <channel>',
+      'Apply channel (stable|next) to all external modules being installed. --all-stable and --all-next are aliases.',
+    ],
+    ['--all-stable', 'Alias for --channel=stable. Resolves externals to the highest stable release tag.'],
+    ['--all-next', 'Alias for --channel=next. Resolves externals to main HEAD.'],
+    ['--next <code>', 'Install module <code> from main HEAD (next channel). Repeatable.', (value, prev) => [...(prev || []), value], []],
+    [
+      '--pin <spec>',
+      'Pin module to a specific tag: --pin CODE=TAG (e.g. --pin bmb=v1.7.0). Repeatable.',
+      (value, prev) => [...(prev || []), value],
+      [],
+    ],
   ],
   action: async (options) => {
     try {

package/tools/installer/core/config.js

@@ -3,7 +3,7 @@
  * User input comes from either UI answers or headless CLI flags.
  */
 class Config {
-  constructor({ directory, modules, ides, skipPrompts, verbose, actionType, coreConfig, moduleConfigs, quickUpdate }) {
+  constructor({ directory, modules, ides, skipPrompts, verbose, actionType, coreConfig, moduleConfigs, quickUpdate, channelOptions }) {
     this.directory = directory;
     this.modules = Object.freeze([...modules]);
     this.ides = Object.freeze([...ides]);
@@ -13,6 +13,8 @@ class Config {
     this.coreConfig = coreConfig;
     this.moduleConfigs = moduleConfigs;
     this._quickUpdate = quickUpdate;
+    // channelOptions carry a Map + Set; don't deep-freeze.
+    this.channelOptions = channelOptions || null;
     Object.freeze(this);
   }
 
@@ -37,6 +39,7 @@ class Config {
       coreConfig: userInput.coreConfig || {},
       moduleConfigs: userInput.moduleConfigs || null,
       quickUpdate: userInput._quickUpdate || false,
+      channelOptions: userInput.channelOptions || null,
     });
   }
 

package/tools/installer/core/installer.js

@@ -601,22 +601,40 @@ class Installer {
           moduleConfig: moduleConfig,
           installer: this,
           silent: true,
+          channelOptions: config.channelOptions,
         },
       );
 
       // Get display name from source module.yaml and resolve the freshest version metadata we can find locally.
-      const sourcePath = await officialModules.findModuleSource(moduleName, { silent: true });
+      const sourcePath = await officialModules.findModuleSource(moduleName, {
+        silent: true,
+        channelOptions: config.channelOptions,
+      });
       const moduleInfo = sourcePath ? await officialModules.getModuleInfo(sourcePath, moduleName, '') : null;
       const displayName = moduleInfo?.name || moduleName;
 
+      const externalResolution = officialModules.externalModuleManager.getResolution(moduleName);
+      let communityResolution = null;
+      if (!externalResolution) {
+        const { CommunityModuleManager } = require('../modules/community-manager');
+        communityResolution = new CommunityModuleManager().getResolution(moduleName);
+      }
+      const resolution = externalResolution || communityResolution;
       const cachedResolution = CustomModuleManager._resolutionCache.get(moduleName);
       const versionInfo = await resolveModuleVersion(moduleName, {
         moduleSourcePath: sourcePath,
-        fallbackVersion: cachedResolution?.version,
+        fallbackVersion: resolution?.version || cachedResolution?.version,
         marketplacePluginNames: cachedResolution?.pluginName ? [cachedResolution.pluginName] : [],
       });
-      const version = versionInfo.version || '';
-      addResult(displayName, 'ok', '', { moduleCode: moduleName, newVersion: version });
+      // Prefer the git tag recorded by the resolution (e.g. "v1.7.0") over
+      // the on-disk package.json (which may be ahead of the released tag).
+      const version = resolution?.version || versionInfo.version || '';
+      addResult(displayName, 'ok', '', {
+        moduleCode: moduleName,
+        newVersion: version,
+        newChannel: resolution?.channel || null,
+        newSha: resolution?.sha || null,
+      });
     }
   }
 
@@ -1091,12 +1109,30 @@ class Installer {
       let detail = '';
       if (r.moduleCode && r.newVersion) {
         const oldVersion = preVersions.get(r.moduleCode);
-        if (oldVersion && oldVersion === r.newVersion) {
-          detail = ` (v${r.newVersion}, no change)`;
+        // Format a version label for display:
+        //   "main" → "main @ <short-sha>" (next channel shows what SHA landed)
+        //   "v1.7.0" or "1.7.0" → "v1.7.0" (prefix 'v' when missing)
+        //   anything else (legacy strings) → as-is
+        const fmt = (v, sha) => {
+          if (typeof v !== 'string' || !v) return '';
+          if (v === 'main' || v === 'HEAD') return sha ? `main @ ${sha.slice(0, 7)}` : 'main';
+          if (/^v?\d+\.\d+\.\d+/.test(v)) return v.startsWith('v') ? v : `v${v}`;
+          return v;
+        };
+        const newV = fmt(r.newVersion, r.newSha);
+        // 'main'/'HEAD' strings only identify the channel, not the commit, so
+        // we can't assert "no change" without comparing SHAs — and preVersions
+        // doesn't carry the old SHA. Render these as a refresh instead of a
+        // false-negative "no change".
+        const isMainLike = oldVersion === 'main' || oldVersion === 'HEAD';
+        if (oldVersion && oldVersion === r.newVersion && !isMainLike) {
+          detail = ` (${newV}, no change)`;
+        } else if (oldVersion && isMainLike) {
+          detail = ` (${newV}, refreshed)`;
         } else if (oldVersion) {
-          detail = ` (v${oldVersion} → v${r.newVersion})`;
+          detail = ` (${fmt(oldVersion, r.newSha)} → ${newV})`;
         } else {
-          detail = ` (v${r.newVersion}, installed)`;
+          detail = ` (${newV}, installed)`;
         }
       } else if (r.detail) {
         detail = ` (${r.detail})`;
@@ -1216,9 +1252,59 @@ class Installer {
       await prompts.log.warn(`Skipping ${skippedModules.length} module(s) - no source available: ${skippedModules.join(', ')}`);
     }
 
+    // Build channel options from the existing manifest FIRST so the config
+    // collector below (which triggers external-module clones via
+    // findModuleSource) knows each module's recorded channel and doesn't
+    // silently redecide it. Without this, modules previously on 'next' or
+    // 'pinned' would trigger a stable-channel tag lookup at config-collection
+    // time, burning GitHub API quota and potentially failing.
+    const manifestData = await this.manifest.read(bmadDir);
+    const channelOptions = { global: null, nextSet: new Set(), pins: new Map(), warnings: [] };
+    if (manifestData?.modulesDetailed) {
+      const { fetchStableTags, classifyUpgrade, parseGitHubRepo } = require('../modules/channel-resolver');
+      for (const entry of manifestData.modulesDetailed) {
+        if (!entry?.name || !entry?.channel) continue;
+        if (entry.channel === 'pinned' && entry.version) {
+          channelOptions.pins.set(entry.name, entry.version);
+          continue;
+        }
+        if (entry.channel === 'next') {
+          channelOptions.nextSet.add(entry.name);
+          continue;
+        }
+        // Stable: classify the available upgrade. Patches and minors fall
+        // through (stable default picks up the top tag). A major upgrade
+        // requires opt-in, so under quick-update's non-interactive semantics
+        // we pin to the current version to prevent a silent breaking jump.
+        if (entry.channel === 'stable' && entry.version && entry.repoUrl) {
+          const parsed = parseGitHubRepo(entry.repoUrl);
+          if (!parsed) continue;
+          try {
+            const tags = await fetchStableTags(parsed.owner, parsed.repo);
+            if (tags.length === 0) continue;
+            const topTag = tags[0].tag;
+            const cls = classifyUpgrade(entry.version, topTag);
+            if (cls === 'major') {
+              channelOptions.pins.set(entry.name, entry.version);
+              await prompts.log.warn(
+                `${entry.name} ${entry.version} → ${topTag} is a new major release; staying on ${entry.version}. ` +
+                  `Run \`bmad install\` (Modify) with \`--pin ${entry.name}=${topTag}\` to accept.`,
+              );
+            }
+          } catch (error) {
+            // Tag lookup failed (offline, rate-limited). Stay on the current
+            // version rather than guessing — the existing cache is already
+            // at that ref, so re-using it keeps the install stable.
+            channelOptions.pins.set(entry.name, entry.version);
+            await prompts.log.warn(`Could not check ${entry.name} for updates (${error.message}); staying on ${entry.version}.`);
+          }
+        }
+      }
+    }
+
     // Load existing configs and collect new fields (if any)
     await prompts.log.info('Checking for new configuration options...');
-    const quickModules = new OfficialModules();
+    const quickModules = new OfficialModules({ channelOptions });
     await quickModules.loadExistingConfig(projectDir);
 
     let promptedForNewFields = false;
@@ -1257,6 +1343,7 @@ class Installer {
       _quickUpdate: true,
       _preserveModules: skippedModules,
       _existingModules: installedModules,
+      channelOptions,
     };
 
     await this.install(installConfig);

package/tools/installer/core/manifest-generator.js

@@ -349,7 +349,22 @@ class ManifestGenerator {
         npmPackage: versionInfo.npmPackage,
         repoUrl: versionInfo.repoUrl,
       };
-      if (versionInfo.localPath) moduleEntry.localPath = versionInfo.localPath;
+      // Preserve channel/sha from the resolution (external/community/custom)
+      // or from the existing entry if this is a no-change rewrite.
+      const channel = versionInfo.channel ?? existing?.channel;
+      const sha = versionInfo.sha ?? existing?.sha;
+      if (channel) moduleEntry.channel = channel;
+      if (sha) moduleEntry.sha = sha;
+      if (versionInfo.localPath || existing?.localPath) {
+        moduleEntry.localPath = versionInfo.localPath || existing.localPath;
+      }
+      if (versionInfo.rawSource || existing?.rawSource) {
+        moduleEntry.rawSource = versionInfo.rawSource || existing.rawSource;
+      }
+      const regTag = versionInfo.registryApprovedTag ?? existing?.registryApprovedTag;
+      const regSha = versionInfo.registryApprovedSha ?? existing?.registryApprovedSha;
+      if (regTag) moduleEntry.registryApprovedTag = regTag;
+      if (regSha) moduleEntry.registryApprovedSha = regSha;
       updatedModules.push(moduleEntry);
     }
 

package/tools/installer/core/manifest.js

@@ -180,7 +180,12 @@ class Manifest {
         npmPackage: options.npmPackage || null,
         repoUrl: options.repoUrl || null,
       };
+      if (options.channel) entry.channel = options.channel;
+      if (options.sha) entry.sha = options.sha;
       if (options.localPath) entry.localPath = options.localPath;
+      if (options.rawSource) entry.rawSource = options.rawSource;
+      if (options.registryApprovedTag) entry.registryApprovedTag = options.registryApprovedTag;
+      if (options.registryApprovedSha) entry.registryApprovedSha = options.registryApprovedSha;
       manifest.modules.push(entry);
     } else {
       // Module exists, update its version info
@@ -192,6 +197,11 @@ class Manifest {
         npmPackage: options.npmPackage === undefined ? existing.npmPackage : options.npmPackage,
         repoUrl: options.repoUrl === undefined ? existing.repoUrl : options.repoUrl,
         localPath: options.localPath === undefined ? existing.localPath : options.localPath,
+        channel: options.channel === undefined ? existing.channel : options.channel,
+        sha: options.sha === undefined ? existing.sha : options.sha,
+        rawSource: options.rawSource === undefined ? existing.rawSource : options.rawSource,
+        registryApprovedTag: options.registryApprovedTag === undefined ? existing.registryApprovedTag : options.registryApprovedTag,
+        registryApprovedSha: options.registryApprovedSha === undefined ? existing.registryApprovedSha : options.registryApprovedSha,
         lastUpdated: new Date().toISOString(),
       };
     }
@@ -275,12 +285,17 @@ class Manifest {
     const moduleInfo = await extMgr.getModuleByCode(moduleName);
 
     if (moduleInfo) {
+      const externalResolution = extMgr.getResolution(moduleName);
       const versionInfo = await resolveModuleVersion(moduleName, { moduleSourcePath });
       return {
-        version: versionInfo.version,
+        // Git tag recorded during install trumps the on-disk package.json
+        // version, so the manifest carries "v1.7.0" instead of "1.7.0".
+        version: externalResolution?.version || versionInfo.version,
         source: 'external',
         npmPackage: moduleInfo.npmPackage || null,
         repoUrl: moduleInfo.url || null,
+        channel: externalResolution?.channel || null,
+        sha: externalResolution?.sha || null,
       };
     }
 
@@ -289,15 +304,20 @@ class Manifest {
     const communityMgr = new CommunityModuleManager();
     const communityInfo = await communityMgr.getModuleByCode(moduleName);
     if (communityInfo) {
+      const communityResolution = communityMgr.getResolution(moduleName);
       const versionInfo = await resolveModuleVersion(moduleName, {
         moduleSourcePath,
         fallbackVersion: communityInfo.version,
       });
       return {
-        version: versionInfo.version || communityInfo.version,
+        version: communityResolution?.version || versionInfo.version || communityInfo.version,
         source: 'community',
         npmPackage: communityInfo.npmPackage || null,
         repoUrl: communityInfo.url || null,
+        channel: communityResolution?.channel || null,
+        sha: communityResolution?.sha || null,
+        registryApprovedTag: communityResolution?.registryApprovedTag || null,
+        registryApprovedSha: communityResolution?.registryApprovedSha || null,
       };
     }
 
@@ -312,12 +332,17 @@ class Manifest {
         fallbackVersion: resolved?.version,
         marketplacePluginNames: resolved?.pluginName ? [resolved.pluginName] : [],
       });
+      const hasGitClone = !!resolved?.repoUrl;
       return {
-        version: versionInfo.version,
+        // Prefer the git ref we actually cloned over the package.json version.
+        version: resolved?.cloneRef || (hasGitClone ? 'main' : versionInfo.version),
         source: 'custom',
         npmPackage: null,
         repoUrl: resolved?.repoUrl || null,
         localPath: resolved?.localPath || null,
+        channel: hasGitClone ? (resolved?.cloneRef ? 'pinned' : 'next') : null,
+        sha: resolved?.cloneSha || null,
+        rawSource: resolved?.rawInput || null,
       };
     }
 

package/tools/installer/modules/channel-plan.js

@@ -0,0 +1,203 @@
+/**
+ * Channel plan: the per-module resolution decision applied at install time.
+ *
+ * A "plan entry" for a module is:
+ *   { channel: 'stable'|'next'|'pinned', pin?: string }
+ *
+ * We build the plan from:
+ *   1. CLI flags (--channel / --all-* / --next=CODE / --pin CODE=TAG)
+ *   2. Interactive answers (the "all stable?" gate + per-module picker)
+ *   3. Registry defaults (default_channel from registry-fallback.yaml / official.yaml)
+ *   4. Hardcoded fallback 'stable'
+ *
+ * Precedence: --pin > --next=CODE > --channel (global) > registry default > 'stable'.
+ *
+ * This module is pure. No prompts, no git, no filesystem.
+ */
+
+const VALID_CHANNELS = new Set(['stable', 'next']);
+
+/**
+ * Parse raw commander options into a structured channel options object.
+ *
+ * @param {Object} options - raw command-line options
+ * @returns {{
+ *   global: 'stable'|'next'|null,
+ *   nextSet: Set<string>,
+ *   pins: Map<string, string>,
+ *   warnings: string[]
+ * }}
+ */
+function parseChannelOptions(options = {}) {
+  const warnings = [];
+
+  // Global channel from --channel / --all-stable / --all-next.
+  let global = null;
+  const aliases = [];
+  if (options.channel) aliases.push({ flag: '--channel', value: normalizeChannel(options.channel, warnings, '--channel') });
+  if (options.allStable) aliases.push({ flag: '--all-stable', value: 'stable' });
+  if (options.allNext) aliases.push({ flag: '--all-next', value: 'next' });
+
+  const distinct = new Set(aliases.map((a) => a.value).filter(Boolean));
+  if (distinct.size > 1) {
+    warnings.push(
+      `Conflicting channel flags: ${aliases
+        .filter((a) => a.value)
+        .map((a) => a.flag + '=' + a.value)
+        .join(', ')}. Using first: ${aliases.find((a) => a.value).flag}.`,
+    );
+  }
+  const firstValid = aliases.find((a) => a.value);
+  if (firstValid) global = firstValid.value;
+
+  // --next=CODE (repeatable)
+  const nextSet = new Set();
+  for (const code of options.next || []) {
+    const trimmed = String(code).trim();
+    if (!trimmed) continue;
+    nextSet.add(trimmed);
+  }
+
+  // --pin CODE=TAG (repeatable)
+  const pins = new Map();
+  for (const spec of options.pin || []) {
+    const parsed = parsePinSpec(spec);
+    if (!parsed) {
+      warnings.push(`Ignoring malformed --pin value '${spec}'. Expected CODE=TAG.`);
+      continue;
+    }
+    if (pins.has(parsed.code)) {
+      warnings.push(`--pin specified multiple times for '${parsed.code}'. Using last: ${parsed.tag}.`);
+    }
+    pins.set(parsed.code, parsed.tag);
+  }
+
+  // --yes auto-confirms the community-module curator-bypass prompt so
+  // headless installs with --next=/--pin for a community module don't hang.
+  const acceptBypass = options.yes === true || options.acceptBypass === true;
+
+  return { global, nextSet, pins, warnings, acceptBypass };
+}
+
+function normalizeChannel(raw, warnings, flagName) {
+  if (typeof raw !== 'string') return null;
+  const lower = raw.trim().toLowerCase();
+  if (VALID_CHANNELS.has(lower)) return lower;
+  warnings.push(`Ignoring invalid ${flagName} value '${raw}'. Expected one of: stable, next.`);
+  return null;
+}
+
+function parsePinSpec(spec) {
+  if (typeof spec !== 'string') return null;
+  const idx = spec.indexOf('=');
+  if (idx <= 0 || idx === spec.length - 1) return null;
+  const code = spec.slice(0, idx).trim();
+  const tag = spec.slice(idx + 1).trim();
+  if (!code || !tag) return null;
+  return { code, tag };
+}
+
+/**
+ * Build a per-module plan entry, applying precedence.
+ *
+ * @param {Object} args
+ * @param {string} args.code
+ * @param {Object} args.channelOptions - from parseChannelOptions
+ * @param {string} [args.registryDefault] - module's default_channel, if any
+ * @returns {{channel: 'stable'|'next'|'pinned', pin?: string, source: string}}
+ *   source describes where the decision came from, for logging / debugging.
+ */
+function decideChannelForModule({ code, channelOptions, registryDefault }) {
+  const { global, nextSet, pins } = channelOptions || { nextSet: new Set(), pins: new Map() };
+
+  if (pins && pins.has(code)) {
+    return { channel: 'pinned', pin: pins.get(code), source: 'flag:--pin' };
+  }
+  if (nextSet && nextSet.has(code)) {
+    return { channel: 'next', source: 'flag:--next' };
+  }
+  if (global) {
+    return { channel: global, source: 'flag:--channel' };
+  }
+  if (registryDefault && VALID_CHANNELS.has(registryDefault)) {
+    return { channel: registryDefault, source: 'registry' };
+  }
+  return { channel: 'stable', source: 'default' };
+}
+
+/**
+ * Build a full channel plan map for a set of modules.
+ *
+ * @param {Object} args
+ * @param {Array<{code: string, defaultChannel?: string, builtIn?: boolean}>} args.modules
+ *   Only the modules that need a channel entry; callers should filter out
+ *   bundled modules (core/bmm) before calling.
+ * @param {Object} args.channelOptions - from parseChannelOptions
+ * @returns {Map<string, {channel: string, pin?: string, source: string}>}
+ */
+function buildPlan({ modules, channelOptions }) {
+  const plan = new Map();
+  for (const mod of modules || []) {
+    plan.set(
+      mod.code,
+      decideChannelForModule({
+        code: mod.code,
+        channelOptions,
+        registryDefault: mod.defaultChannel,
+      }),
+    );
+  }
+  return plan;
+}
+
+/**
+ * Report any --pin CODE=TAG entries that don't correspond to a selected module.
+ * These get warned about but don't abort the install.
+ */
+function orphanPinWarnings(channelOptions, selectedCodes) {
+  const warnings = [];
+  const selected = new Set(selectedCodes || []);
+  for (const code of channelOptions?.pins?.keys() || []) {
+    if (!selected.has(code)) {
+      warnings.push(`--pin for '${code}' has no effect (module not selected).`);
+    }
+  }
+  for (const code of channelOptions?.nextSet || []) {
+    if (!selected.has(code)) {
+      warnings.push(`--next for '${code}' has no effect (module not selected).`);
+    }
+  }
+  return warnings;
+}
+
+/**
+ * Warn when --pin / --next targets a bundled module (core, bmm). Those are
+ * shipped inside the installer binary — there's no git clone to override, so
+ * the flag has no effect. Users who actually want a prerelease core/bmm
+ * should use `npx bmad-method@next install`.
+ */
+function bundledTargetWarnings(channelOptions, bundledCodes) {
+  const warnings = [];
+  const bundled = new Set(bundledCodes || []);
+  const hint = '(bundled module; use `npx bmad-method@next install` for a prerelease)';
+  for (const code of channelOptions?.pins?.keys() || []) {
+    if (bundled.has(code)) {
+      warnings.push(`--pin for '${code}' has no effect ${hint}.`);
+    }
+  }
+  for (const code of channelOptions?.nextSet || []) {
+    if (bundled.has(code)) {
+      warnings.push(`--next for '${code}' has no effect ${hint}.`);
+    }
+  }
+  return warnings;
+}
+
+module.exports = {
+  parseChannelOptions,
+  decideChannelForModule,
+  buildPlan,
+  orphanPinWarnings,
+  bundledTargetWarnings,
+  parsePinSpec,
+};