bmad-method 6.3.1-next.8 → 6.4.0

package/tools/installer/core/manifest.js

@@ -1,9 +1,20 @@
 const path = require('node:path');
+const https = require('node:https');
+const { execFile } = require('node:child_process');
+const { promisify } = require('node:util');
 const fs = require('../fs-native');
 const crypto = require('node:crypto');
-const { getProjectRoot } = require('../project-root');
+const { resolveModuleVersion } = require('../modules/version-resolver');
 const prompts = require('../prompts');
 
+const execFileAsync = promisify(execFile);
+const NPM_LOOKUP_TIMEOUT_MS = 10_000;
+const NPM_PACKAGE_NAME_PATTERN = /^(?:@[a-z0-9][a-z0-9._~-]*\/)?[a-z0-9][a-z0-9._~-]*$/;
+
+function isValidNpmPackageName(packageName) {
+  return typeof packageName === 'string' && NPM_PACKAGE_NAME_PATTERN.test(packageName);
+}
+
 class Manifest {
   /**
    * Create a new manifest
@@ -180,7 +191,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 +208,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(),
       };
     }
@@ -258,13 +279,11 @@ class Manifest {
    * @returns {Object} Version info object with version, source, npmPackage, repoUrl
    */
   async getModuleVersionInfo(moduleName, bmadDir, moduleSourcePath = null) {
-    const yaml = require('yaml');
-
     // Resolve source type first, then read version with the correct path context
     if (['core', 'bmm'].includes(moduleName)) {
-      const version = await this._readMarketplaceVersion(moduleName, moduleSourcePath);
+      const versionInfo = await resolveModuleVersion(moduleName, { moduleSourcePath });
       return {
-        version,
+        version: versionInfo.version,
         source: 'built-in',
         npmPackage: null,
         repoUrl: null,
@@ -277,13 +296,17 @@ class Manifest {
     const moduleInfo = await extMgr.getModuleByCode(moduleName);
 
     if (moduleInfo) {
-      // External module: use moduleSourcePath if provided, otherwise fall back to cache
-      const version = await this._readMarketplaceVersion(moduleName, moduleSourcePath);
+      const externalResolution = extMgr.getResolution(moduleName);
+      const versionInfo = await resolveModuleVersion(moduleName, { moduleSourcePath });
       return {
-        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,
       };
     }
 
@@ -292,12 +315,20 @@ class Manifest {
     const communityMgr = new CommunityModuleManager();
     const communityInfo = await communityMgr.getModuleByCode(moduleName);
     if (communityInfo) {
-      const communityVersion = await this._readMarketplaceVersion(moduleName, moduleSourcePath);
+      const communityResolution = communityMgr.getResolution(moduleName);
+      const versionInfo = await resolveModuleVersion(moduleName, {
+        moduleSourcePath,
+        fallbackVersion: communityInfo.version,
+      });
       return {
-        version: communityVersion || 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,
       };
     }
 
@@ -307,110 +338,75 @@ class Manifest {
     const resolved = customMgr.getResolution(moduleName);
     const customSource = await customMgr.findModuleSourceByCode(moduleName, { bmadDir });
     if (customSource || resolved) {
-      const customVersion = resolved?.version || (await this._readMarketplaceVersion(moduleName, moduleSourcePath));
+      const versionInfo = await resolveModuleVersion(moduleName, {
+        moduleSourcePath: moduleSourcePath || customSource,
+        fallbackVersion: resolved?.version,
+        marketplacePluginNames: resolved?.pluginName ? [resolved.pluginName] : [],
+      });
+      const hasGitClone = !!resolved?.repoUrl;
       return {
-        version: customVersion,
+        // 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,
       };
     }
 
     // Unknown module
-    const version = await this._readMarketplaceVersion(moduleName, moduleSourcePath);
+    const versionInfo = await resolveModuleVersion(moduleName, { moduleSourcePath });
     return {
-      version,
+      version: versionInfo.version,
       source: 'unknown',
       npmPackage: null,
       repoUrl: null,
     };
   }
 
-  /**
-   * Read version from .claude-plugin/marketplace.json for a module
-   * @param {string} moduleName - Module code
-   * @returns {string|null} Version or null
-   */
-  async _readMarketplaceVersion(moduleName, moduleSourcePath = null) {
-    const os = require('node:os');
-    let marketplacePath;
-
-    if (['core', 'bmm'].includes(moduleName)) {
-      marketplacePath = path.join(getProjectRoot(), '.claude-plugin', 'marketplace.json');
-    } else if (moduleSourcePath) {
-      // Walk up from source path to find marketplace.json
-      let dir = moduleSourcePath;
-      for (let i = 0; i < 5; i++) {
-        const candidate = path.join(dir, '.claude-plugin', 'marketplace.json');
-        if (await fs.pathExists(candidate)) {
-          marketplacePath = candidate;
-          break;
-        }
-        const parent = path.dirname(dir);
-        if (parent === dir) break;
-        dir = parent;
-      }
-    }
-
-    // Fallback to external module cache
-    if (!marketplacePath) {
-      const cacheDir = path.join(os.homedir(), '.bmad', 'cache', 'external-modules', moduleName);
-      marketplacePath = path.join(cacheDir, '.claude-plugin', 'marketplace.json');
-    }
-
-    try {
-      if (await fs.pathExists(marketplacePath)) {
-        const data = JSON.parse(await fs.readFile(marketplacePath, 'utf8'));
-        const plugins = data?.plugins;
-        if (!Array.isArray(plugins) || plugins.length === 0) return null;
-        let best = null;
-        for (const p of plugins) {
-          if (p.version && (!best || p.version > best)) best = p.version;
-        }
-        return best;
-      }
-    } catch {
-      // ignore
-    }
-    return null;
-  }
-
   /**
    * Fetch latest version from npm for a package
    * @param {string} packageName - npm package name
    * @returns {string|null} Latest version or null
    */
   async fetchNpmVersion(packageName) {
-    try {
-      const https = require('node:https');
-      const { execSync } = require('node:child_process');
+    if (!isValidNpmPackageName(packageName)) {
+      return null;
+    }
 
+    try {
       // Try using npm view first (more reliable)
       try {
-        const result = execSync(`npm view ${packageName} version`, {
+        const { stdout } = await execFileAsync('npm', ['view', packageName, 'version'], {
           encoding: 'utf8',
-          stdio: 'pipe',
-          timeout: 10_000,
+          timeout: NPM_LOOKUP_TIMEOUT_MS,
         });
-        return result.trim();
+        return stdout.trim();
       } catch {
         // Fallback to npm registry API
-        return new Promise((resolve, reject) => {
-          https
-            .get(`https://registry.npmjs.org/${packageName}`, (res) => {
-              let data = '';
-              res.on('data', (chunk) => (data += chunk));
-              res.on('end', () => {
-                try {
-                  const pkg = JSON.parse(data);
-                  resolve(pkg['dist-tags']?.latest || pkg.version || null);
-                } catch {
-                  resolve(null);
-                }
-              });
-            })
-            .on('error', () => resolve(null));
+        return new Promise((resolve) => {
+          const request = https.get(`https://registry.npmjs.org/${encodeURIComponent(packageName)}`, (res) => {
+            let data = '';
+            res.on('data', (chunk) => (data += chunk));
+            res.on('end', () => {
+              try {
+                const pkg = JSON.parse(data);
+                resolve(pkg['dist-tags']?.latest || pkg.version || null);
+              } catch {
+                resolve(null);
+              }
+            });
+          });
+
+          request.setTimeout(NPM_LOOKUP_TIMEOUT_MS, () => {
+            request.destroy();
+            resolve(null);
+          });
+
+          request.on('error', () => resolve(null));
         });
       }
     } catch {
@@ -424,6 +420,7 @@ class Manifest {
    * @returns {Array} Array of update info objects
    */
   async checkForUpdates(bmadDir) {
+    const semver = require('semver');
     const modules = await this.getAllModuleVersions(bmadDir);
     const updates = [];
 
@@ -437,7 +434,10 @@ class Manifest {
         continue;
       }
 
-      if (module.version !== latestVersion) {
+      const installedVersion = semver.valid(module.version) || semver.valid(semver.coerce(module.version || ''));
+      const availableVersion = semver.valid(latestVersion) || semver.valid(semver.coerce(latestVersion));
+
+      if (installedVersion && availableVersion && semver.gt(availableVersion, installedVersion)) {
         updates.push({
           name: module.name,
           installedVersion: module.version,

package/tools/installer/fs-native.js

@@ -82,7 +82,9 @@ module.exports = {
   stat: fsp.stat,
   readdir: fsp.readdir,
   access: fsp.access,
+  realpath: fsp.realpath,
   rename: fsp.rename,
+  rmdir: fsp.rmdir,
   unlink: fsp.unlink,
   chmod: fsp.chmod,
   mkdir: fsp.mkdir,
@@ -103,6 +105,9 @@ module.exports = {
   existsSync: fs.existsSync.bind(fs),
   readFileSync: fs.readFileSync.bind(fs),
   writeFileSync: fs.writeFileSync.bind(fs),
+  statSync: fs.statSync.bind(fs),
+  accessSync: fs.accessSync.bind(fs),
+  readdirSync: fs.readdirSync.bind(fs),
   createReadStream: fs.createReadStream.bind(fs),
   pathExistsSync: fs.existsSync.bind(fs),
 

package/tools/installer/ide/platform-codes.yaml

@@ -114,6 +114,12 @@ platforms:
         - .kilocode/workflows
       target_dir: .kilocode/skills
 
+  kimi-code:
+    name: "Kimi Code"
+    preferred: false
+    installer:
+      target_dir: .kimi/skills
+
   kiro:
     name: "Kiro"
     preferred: false

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