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

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

@@ -0,0 +1,241 @@
+const https = require('node:https');
+const semver = require('semver');
+
+/**
+ * Channel resolver for external and community modules.
+ *
+ * A "channel" is the resolution strategy that decides which ref of a module
+ * to clone when no explicit version is supplied:
+ *   - stable: highest pure-semver git tag (excludes -alpha/-beta/-rc)
+ *   - next:   main branch HEAD
+ *   - pinned: an explicit user-supplied tag
+ *
+ * This module is pure (no prompts, no git, no filesystem). It only talks to
+ * the GitHub tags API and performs semver math. Clone logic lives in the
+ * module managers that call resolveChannel().
+ */
+
+const GITHUB_API_BASE = 'https://api.github.com';
+const DEFAULT_TIMEOUT_MS = 10_000;
+const USER_AGENT = 'bmad-method-installer';
+
+// Per-process cache: { 'owner/repo' => string[] sorted desc } of pure-semver tags.
+const tagCache = new Map();
+
+/**
+ * Parse a GitHub repo URL into { owner, repo }. Returns null if the URL is
+ * not a GitHub URL the resolver can handle.
+ */
+function parseGitHubRepo(url) {
+  if (!url || typeof url !== 'string') return null;
+  const trimmed = url
+    .trim()
+    .replace(/\.git$/, '')
+    .replace(/\/$/, '');
+
+  // https://github.com/owner/repo
+  const httpsMatch = trimmed.match(/^https?:\/\/github\.com\/([^/]+)\/([^/]+)(?:\/.*)?$/i);
+  if (httpsMatch) return { owner: httpsMatch[1], repo: httpsMatch[2] };
+
+  // git@github.com:owner/repo
+  const sshMatch = trimmed.match(/^git@github\.com:([^/]+)\/([^/]+)$/i);
+  if (sshMatch) return { owner: sshMatch[1], repo: sshMatch[2] };
+
+  return null;
+}
+
+function fetchJson(url, { timeout = DEFAULT_TIMEOUT_MS } = {}) {
+  const headers = {
+    'User-Agent': USER_AGENT,
+    Accept: 'application/vnd.github+json',
+    'X-GitHub-Api-Version': '2022-11-28',
+  };
+  if (process.env.GITHUB_TOKEN) {
+    headers.Authorization = `Bearer ${process.env.GITHUB_TOKEN}`;
+  }
+
+  return new Promise((resolve, reject) => {
+    const req = https.get(url, { headers, timeout }, (res) => {
+      let body = '';
+      res.on('data', (chunk) => (body += chunk));
+      res.on('end', () => {
+        if (res.statusCode < 200 || res.statusCode >= 300) {
+          const err = new Error(`GitHub API ${res.statusCode} for ${url}: ${body.slice(0, 200)}`);
+          err.statusCode = res.statusCode;
+          return reject(err);
+        }
+        try {
+          resolve(JSON.parse(body));
+        } catch (error) {
+          reject(new Error(`Failed to parse GitHub response: ${error.message}`));
+        }
+      });
+    });
+    req.on('error', reject);
+    req.on('timeout', () => {
+      req.destroy();
+      reject(new Error(`GitHub API request timed out: ${url}`));
+    });
+  });
+}
+
+/**
+ * Strip a leading 'v' and return a valid semver string, or null if the tag
+ * is not valid semver or is a prerelease (contains -alpha/-beta/-rc/etc.).
+ */
+function normalizeStableTag(tagName) {
+  if (typeof tagName !== 'string') return null;
+  const stripped = tagName.startsWith('v') ? tagName.slice(1) : tagName;
+  const valid = semver.valid(stripped);
+  if (!valid) return null;
+  // Exclude prereleases. semver.prerelease returns null for pure releases.
+  if (semver.prerelease(valid)) return null;
+  return valid;
+}
+
+/**
+ * Fetch pure-semver tags (highest first) from a GitHub repo.
+ * Cached per-process per owner/repo.
+ *
+ * @returns {Promise<Array<{tag: string, version: string}>>}
+ *   tag is the original ref name (e.g. "v1.7.0"), version is the cleaned
+ *   semver (e.g. "1.7.0").
+ */
+async function fetchStableTags(owner, repo, { timeout } = {}) {
+  const cacheKey = `${owner}/${repo}`;
+  if (tagCache.has(cacheKey)) return tagCache.get(cacheKey);
+
+  // GitHub returns up to 100 tags per page; one page is plenty for our modules.
+  const url = `${GITHUB_API_BASE}/repos/${owner}/${repo}/tags?per_page=100`;
+  const raw = await fetchJson(url, { timeout });
+  if (!Array.isArray(raw)) {
+    throw new TypeError(`Unexpected response from ${url}`);
+  }
+
+  const stable = [];
+  for (const entry of raw) {
+    const version = normalizeStableTag(entry?.name);
+    if (version) stable.push({ tag: entry.name, version });
+  }
+  stable.sort((a, b) => semver.rcompare(a.version, b.version));
+
+  tagCache.set(cacheKey, stable);
+  return stable;
+}
+
+/**
+ * Resolve a channel plan for a single module into a git-clonable ref.
+ *
+ * @param {Object} args
+ * @param {'stable'|'next'|'pinned'} args.channel
+ * @param {string} [args.pin] - Required when channel === 'pinned'
+ * @param {string} args.repoUrl - Module's git URL (for tag lookup)
+ * @returns {Promise<{channel, ref, version}>} where
+ *   ref:     the git ref to pass to `git clone --branch`, or null for HEAD (next)
+ *   version: the resolved version string (tag name for stable/pinned, 'main' for next)
+ *
+ * Throws on:
+ *   - pinned without a pin value
+ *   - stable with no GitHub repo parseable from the URL (pass through to caller to fall back)
+ *
+ * Falls back to next-channel semantics and sets resolvedFallback=true when
+ * stable resolution turns up no tags.
+ */
+async function resolveChannel({ channel, pin, repoUrl, timeout }) {
+  if (channel === 'pinned') {
+    if (!pin) throw new Error('resolveChannel: pinned channel requires a pin value');
+    return { channel: 'pinned', ref: pin, version: pin, resolvedFallback: false };
+  }
+
+  if (channel === 'next') {
+    return { channel: 'next', ref: null, version: 'main', resolvedFallback: false };
+  }
+
+  if (channel === 'stable') {
+    const parsed = parseGitHubRepo(repoUrl);
+    if (!parsed) {
+      // No GitHub URL — caller must handle by falling back to next.
+      return { channel: 'next', ref: null, version: 'main', resolvedFallback: true, reason: 'not-a-github-url' };
+    }
+
+    try {
+      const tags = await fetchStableTags(parsed.owner, parsed.repo, { timeout });
+      if (tags.length === 0) {
+        return { channel: 'next', ref: null, version: 'main', resolvedFallback: true, reason: 'no-stable-tags' };
+      }
+      const top = tags[0];
+      return { channel: 'stable', ref: top.tag, version: top.tag, resolvedFallback: false };
+    } catch (error) {
+      // Propagate the error; callers decide whether to fall back or abort.
+      error.message = `Failed to resolve stable channel for ${parsed.owner}/${parsed.repo}: ${error.message}`;
+      throw error;
+    }
+  }
+
+  throw new Error(`resolveChannel: unknown channel '${channel}'`);
+}
+
+/**
+ * Verify that a specific tag exists in a GitHub repo. Used to validate
+ * --pin values before the user sits through a long clone that then fails.
+ */
+async function tagExists(owner, repo, tagName, { timeout } = {}) {
+  const url = `${GITHUB_API_BASE}/repos/${owner}/${repo}/git/refs/tags/${encodeURIComponent(tagName)}`;
+  try {
+    await fetchJson(url, { timeout });
+    return true;
+  } catch (error) {
+    if (error.statusCode === 404) return false;
+    throw error;
+  }
+}
+
+/**
+ * Classify the semver delta between two versions.
+ *   - 'none'  → same version (or downgrade; treated same)
+ *   - 'patch' → same major.minor, higher patch
+ *   - 'minor' → same major, higher minor
+ *   - 'major' → different major
+ *   - 'unknown' → either version is not valid semver; caller should treat as major
+ */
+function classifyUpgrade(currentVersion, newVersion) {
+  const current = semver.valid(semver.coerce(currentVersion));
+  const next = semver.valid(semver.coerce(newVersion));
+  if (!current || !next) return 'unknown';
+  if (semver.lte(next, current)) return 'none';
+  const diff = semver.diff(current, next);
+  if (diff === 'patch') return 'patch';
+  if (diff === 'minor' || diff === 'preminor') return 'minor';
+  if (diff === 'major' || diff === 'premajor') return 'major';
+  // prepatch, prerelease — treat conservatively as minor (prereleases shouldn't
+  // normally surface here since stable channel filters them out).
+  return 'minor';
+}
+
+/**
+ * Build the GitHub release notes URL for a resolved tag.
+ * Returns null if the repo URL isn't a GitHub URL.
+ */
+function releaseNotesUrl(repoUrl, tag) {
+  const parsed = parseGitHubRepo(repoUrl);
+  if (!parsed || !tag) return null;
+  return `https://github.com/${parsed.owner}/${parsed.repo}/releases/tag/${encodeURIComponent(tag)}`;
+}
+
+/**
+ * Test-only: clear the per-process tag cache.
+ */
+function _clearTagCache() {
+  tagCache.clear();
+}
+
+module.exports = {
+  parseGitHubRepo,
+  fetchStableTags,
+  resolveChannel,
+  tagExists,
+  classifyUpgrade,
+  releaseNotesUrl,
+  normalizeStableTag,
+  _clearTagCache,
+};

package/tools/installer/modules/community-manager.js

@@ -4,6 +4,8 @@ const path = require('node:path');
 const { execSync } = require('node:child_process');
 const prompts = require('../prompts');
 const { RegistryClient } = require('./registry-client');
+const { decideChannelForModule } = require('./channel-plan');
+const { parseGitHubRepo, tagExists } = require('./channel-resolver');
 
 const MARKETPLACE_OWNER = 'bmad-code-org';
 const MARKETPLACE_REPO = 'bmad-plugins-marketplace';
@@ -15,13 +17,29 @@ const MARKETPLACE_REF = 'main';
  * Returns empty results when the registry is unreachable.
  * Community modules are pinned to approved SHA when set; uses HEAD otherwise.
  */
+function quoteShellRef(ref) {
+  if (typeof ref !== 'string' || !/^[\w.\-+/]+$/.test(ref)) {
+    throw new Error(`Unsafe ref name: ${JSON.stringify(ref)}`);
+  }
+  return `"${ref}"`;
+}
+
 class CommunityModuleManager {
+  // moduleCode → { channel, version, sha, registryApprovedTag, registryApprovedSha, repoUrl, bypassedCurator }
+  // Shared across all instances; the manifest writer often uses a fresh instance.
+  static _resolutions = new Map();
+
   constructor() {
     this._client = new RegistryClient();
     this._cachedIndex = null;
     this._cachedCategories = null;
   }
 
+  /** Get the most recent channel resolution for a community module. */
+  getResolution(moduleCode) {
+    return CommunityModuleManager._resolutions.get(moduleCode) || null;
+  }
+
   // ─── Data Loading ──────────────────────────────────────────────────────────
 
   /**
@@ -196,12 +214,49 @@ class CommunityModuleManager {
       return await prompts.spinner();
     };
 
-    const sha = moduleInfo.approvedSha;
+    // ─── Resolve channel plan ──────────────────────────────────────────────
+    // Default community behavior (stable channel) honors the curator's
+    // approved SHA. --next=CODE and --pin CODE=TAG override the curator; we
+    // warn the user before bypassing the approved version.
+    const planEntry = decideChannelForModule({
+      code: moduleCode,
+      channelOptions: options.channelOptions,
+      registryDefault: 'stable',
+    });
+
+    const approvedSha = moduleInfo.approvedSha;
+    const approvedTag = moduleInfo.approvedTag;
+
+    let bypassedCurator = false;
+    if (planEntry.channel !== 'stable') {
+      bypassedCurator = true;
+      if (!silent) {
+        const approvedLabel = approvedTag || approvedSha || 'curator-approved version';
+        await prompts.log.warn(
+          `WARNING: Installing '${moduleCode}' from ${
+            planEntry.channel === 'pinned' ? `tag ${planEntry.pin}` : 'main HEAD'
+          } bypasses the curator-approved ${approvedLabel}. Proceed only if you trust this source.`,
+        );
+        if (!options.channelOptions?.acceptBypass) {
+          const proceed = await prompts.confirm({
+            message: `Continue installing '${moduleCode}' with curator bypass?`,
+            default: false,
+          });
+          if (!proceed) {
+            throw new Error(`Install of community module '${moduleCode}' cancelled by user.`);
+          }
+        }
+      }
+    }
+
     let needsDependencyInstall = false;
     let wasNewClone = false;
 
     if (await fs.pathExists(moduleCacheDir)) {
-      // Already cloned - update to latest HEAD
+      // Already cloned — refresh to the correct ref for the resolved channel.
+      // A pinned install must not reset to origin/HEAD (it would silently drift
+      // to main on every re-install). Stable + approvedSha is handled below
+      // by the curator-SHA checkout logic.
       const fetchSpinner = await createSpinner();
       fetchSpinner.start(`Checking ${moduleInfo.displayName}...`);
       try {
@@ -211,10 +266,24 @@ class CommunityModuleManager {
           stdio: ['ignore', 'pipe', 'pipe'],
           env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
         });
-        execSync('git reset --hard origin/HEAD', {
-          cwd: moduleCacheDir,
-          stdio: ['ignore', 'pipe', 'pipe'],
-        });
+        if (planEntry.channel === 'pinned') {
+          // Fetch the pin tag specifically and check it out.
+          execSync(`git fetch --depth 1 origin ${quoteShellRef(planEntry.pin)} --no-tags`, {
+            cwd: moduleCacheDir,
+            stdio: ['ignore', 'pipe', 'pipe'],
+            env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+          });
+          execSync('git checkout --quiet FETCH_HEAD', {
+            cwd: moduleCacheDir,
+            stdio: ['ignore', 'pipe', 'pipe'],
+          });
+        } else {
+          // stable (approvedSha path re-checks out below) and next: track main.
+          execSync('git reset --hard origin/HEAD', {
+            cwd: moduleCacheDir,
+            stdio: ['ignore', 'pipe', 'pipe'],
+          });
+        }
         const newRef = execSync('git rev-parse HEAD', { cwd: moduleCacheDir, stdio: 'pipe' }).toString().trim();
         if (currentRef !== newRef) needsDependencyInstall = true;
         fetchSpinner.stop(`Verified ${moduleInfo.displayName}`);
@@ -231,10 +300,17 @@ class CommunityModuleManager {
       const fetchSpinner = await createSpinner();
       fetchSpinner.start(`Fetching ${moduleInfo.displayName}...`);
       try {
-        execSync(`git clone --depth 1 "${moduleInfo.url}" "${moduleCacheDir}"`, {
-          stdio: ['ignore', 'pipe', 'pipe'],
-          env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
-        });
+        if (planEntry.channel === 'pinned') {
+          execSync(`git clone --depth 1 --branch ${quoteShellRef(planEntry.pin)} "${moduleInfo.url}" "${moduleCacheDir}"`, {
+            stdio: ['ignore', 'pipe', 'pipe'],
+            env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+          });
+        } else {
+          execSync(`git clone --depth 1 "${moduleInfo.url}" "${moduleCacheDir}"`, {
+            stdio: ['ignore', 'pipe', 'pipe'],
+            env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+          });
+        }
         fetchSpinner.stop(`Fetched ${moduleInfo.displayName}`);
         needsDependencyInstall = true;
       } catch (error) {
@@ -243,18 +319,19 @@ class CommunityModuleManager {
       }
     }
 
-    // If pinned to a specific SHA, check out that exact commit.
-    // Refuse to install if the approved SHA cannot be reached - security requirement.
-    if (sha) {
+    // ─── Check out the resolved ref per channel ──────────────────────────
+    if (planEntry.channel === 'stable' && approvedSha) {
+      // Default path: pin to the curator-approved SHA. Refuse install if the SHA
+      // is unreachable (tag may have been deleted or rewritten) — security requirement.
       const headSha = execSync('git rev-parse HEAD', { cwd: moduleCacheDir, stdio: 'pipe' }).toString().trim();
-      if (headSha !== sha) {
+      if (headSha !== approvedSha) {
         try {
-          execSync(`git fetch --depth 1 origin ${sha}`, {
+          execSync(`git fetch --depth 1 origin ${quoteShellRef(approvedSha)}`, {
             cwd: moduleCacheDir,
             stdio: ['ignore', 'pipe', 'pipe'],
             env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
           });
-          execSync(`git checkout ${sha}`, {
+          execSync(`git checkout ${quoteShellRef(approvedSha)}`, {
             cwd: moduleCacheDir,
             stdio: ['ignore', 'pipe', 'pipe'],
           });
@@ -262,12 +339,37 @@ class CommunityModuleManager {
         } catch {
           await fs.remove(moduleCacheDir);
           throw new Error(
-            `Community module '${moduleCode}' could not be pinned to its approved commit (${sha}). ` +
-              `Installation refused for security. The module registry entry may need updating.`,
+            `Community module '${moduleCode}' could not be pinned to its approved commit (${approvedSha}). ` +
+              `Installation refused for security. The module registry entry may need updating, ` +
+              `or use --next=${moduleCode} / --pin ${moduleCode}=<tag> to explicitly bypass.`,
           );
         }
       }
+    } else if (planEntry.channel === 'stable' && !approvedSha) {
+      // Registry data gap: tag or SHA missing. Warn but proceed at HEAD (pre-existing behavior).
+      if (!silent) {
+        await prompts.log.warn(`Community module '${moduleCode}' has no curator-approved SHA in the registry; installing from main HEAD.`);
+      }
+    } else if (planEntry.channel === 'pinned') {
+      // We cloned the tag directly above (via --branch), but ensure HEAD matches.
+      // No additional checkout needed.
     }
+    // else: 'next' channel — already at origin/HEAD from the fetch/reset above.
+
+    // Record the resolution so the manifest writer can pick up channel/version/sha.
+    const installedSha = execSync('git rev-parse HEAD', { cwd: moduleCacheDir, stdio: 'pipe' }).toString().trim();
+    const recordedVersion =
+      planEntry.channel === 'pinned' ? planEntry.pin : planEntry.channel === 'next' ? 'main' : approvedTag || installedSha.slice(0, 7);
+    CommunityModuleManager._resolutions.set(moduleCode, {
+      channel: planEntry.channel,
+      version: recordedVersion,
+      sha: installedSha,
+      registryApprovedTag: approvedTag || null,
+      registryApprovedSha: approvedSha || null,
+      repoUrl: moduleInfo.url,
+      bypassedCurator,
+      planSource: planEntry.source,
+    });
 
     // Install dependencies if needed
     const packageJsonPath = path.join(moduleCacheDir, 'package.json');