ma-agents 3.18.0 → 3.18.1-beta.0

package/lib/bmad.js

@@ -626,6 +626,46 @@ function getInstallableBmadModules() {
     return [bmmEntry, ...cacheEntries];
 }
 
+/**
+ * Return the upstream release tag each bundled external module is pinned to,
+ * read from the `pinTag` field of `lib/bmad-cache/cache-manifest.json`.
+ *
+ * Why this exists: `bmad-method` itself is pinned exactly (package.json), but
+ * left to its defaults it resolves every external module to that module's
+ * LATEST stable tag at install time. An upstream release cut after ma-agents
+ * shipped then lands on users' machines untested — TEA v2.0.x dropped
+ * `src/module.yaml`, which bmad-method 6.10.0 requires, and broke every
+ * install that selected tea. Pinning to the tag the bundled cache was built
+ * from makes an online install resolve to the same release an offline one
+ * does.
+ *
+ * Entries without a `pinTag` are omitted (and so float, as before);
+ * test/bundled-module-pins.test.js fails the build when a bundled module
+ * ships without one.
+ *
+ * @param {string} [manifestPath] - Override the manifest path (tests only)
+ * @returns {Object<string, string>} module id → release tag (e.g. `{ tea: 'v1.19.0' }`);
+ *   empty when the manifest is missing or unreadable
+ */
+function getBundledModulePins(manifestPath = path.join(__dirname, 'bmad-cache', 'cache-manifest.json')) {
+    let manifest;
+    try {
+        manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+    } catch {
+        return {};
+    }
+    const pins = {};
+    for (const [id, meta] of Object.entries(manifest.modules || {})) {
+        const tag = meta && typeof meta.pinTag === 'string' ? meta.pinTag.trim() : '';
+        // The tag is interpolated into a shell command (buildBmadArgs), so
+        // accept only plain git-tag characters.
+        if (/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(tag)) {
+            pins[id] = tag;
+        }
+    }
+    return pins;
+}
+
 /**
  * Detect which BMad modules are already installed under a given project
  * root by checking for `_bmad/<id>/` directories. Used by the install
@@ -830,6 +870,10 @@ function resolveCustomContentFlag() {
  *   `--custom-source <path>`; when omitted no extension flag is added.
  *   The legacy fallback to `lib/bmad-extension/` was removed when the
  *   stage-and-invoke flow replaced applyCustomizations().
+ * @param {Object<string, string>} [ctx.pins] - module id → release tag to pass
+ *   as `--pin <id>=<tag>`. Defaults to getBundledModulePins(). Only modules in
+ *   `ctx.modules` are pinned (bmad-method warns on a pin for an unselected
+ *   module).
  * @returns {string} Complete command string ready for execSync
  */
 function buildBmadArgs(ctx) {
@@ -868,6 +912,16 @@ function buildBmadArgs(ctx) {
         parts.push(flag, `"${ctx.customSource}"`);
     }
 
+    // Pin each selected external module to the release the bundled cache was
+    // built from, so upstream releases cut after this ma-agents version can't
+    // reach the install (see getBundledModulePins).
+    const pins = ctx.pins || getBundledModulePins();
+    for (const mod of ctx.modules) {
+        if (pins[mod]) {
+            parts.push('--pin', `${mod}=${pins[mod]}`);
+        }
+    }
+
     if (ctx.action === 'update') {
         parts.push('--action', 'update');
     }
@@ -2118,12 +2172,20 @@ async function installCustomMarketplaceSubset({ projectRoot, modules, tools, sel
  * `stable` because that's bmad-method's own default when a registry
  * entry has no `default_channel` field.
  *
+ * When the manifest entry carries a `pinTag`, the marker is written on the
+ * `pinned` channel at that tag instead, matching the `--pin` buildBmadArgs
+ * passes. bmad-method compares the marker's channel to the requested one and
+ * wipes + re-clones the cache on a mismatch, which an air-gapped host cannot
+ * survive. A local tag ref is also created so bmad-method's
+ * `git fetch origin tag <pinTag>` (origin = the cache itself, see
+ * restoreGitDir) resolves without the network.
+ *
  * Best-effort: failures are swallowed. The next install attempt (online or
  * offline-with-marker) will write a fresh one.
  *
  * @param {string} moduleDir - Cache dir for the module
  *   (e.g. `~/.bmad/cache/external-modules/tea`)
- * @param {{ branch?: string, commitSha?: string }} [manifestEntry] - Entry
+ * @param {{ branch?: string, commitSha?: string, pinTag?: string }} [manifestEntry] - Entry
  *   from `lib/bmad-cache/cache-manifest.json` for this module
  * @returns {Promise<boolean>} `true` if the marker was written, `false` if
  *   it already existed or the manifest entry is missing required fields
@@ -2132,13 +2194,15 @@ async function ensureCacheMarker(moduleDir, manifestEntry) {
     const markerPath = path.join(moduleDir, '.bmad-channel.json');
     if (await fs.pathExists(markerPath)) return false;
     if (!manifestEntry || !manifestEntry.commitSha) return false;
+    const pinTag = manifestEntry.pinTag;
     try {
+        if (pinTag) ensureLocalTag(moduleDir, pinTag);
         await fs.writeFile(
             markerPath,
             JSON.stringify(
                 {
-                    channel: 'stable',
-                    version: manifestEntry.branch || 'main',
+                    channel: pinTag ? 'pinned' : 'stable',
+                    version: pinTag || manifestEntry.branch || 'main',
                     sha: manifestEntry.commitSha,
                     writtenAt: new Date().toISOString(),
                 },
@@ -2154,6 +2218,53 @@ async function ensureCacheMarker(moduleDir, manifestEntry) {
     }
 }
 
+/**
+ * Create tag `tag` at HEAD in a cached module's git repo unless it already
+ * exists. The bundled cache is a shallow clone of the commit the pin tag
+ * names (or a metadata-only commit past it), and the clone only carries the
+ * tag when it pointed at HEAD exactly.
+ *
+ * Best-effort: no `.git/` or no `git` binary is a silent no-op — bmad-method
+ * then falls back to cloning the tag from upstream.
+ *
+ * @param {string} moduleDir - Cached module directory
+ * @param {string} tag - Release tag (e.g. `v2.1.0`)
+ */
+function ensureLocalTag(moduleDir, tag) {
+    if (!fs.existsSync(path.join(moduleDir, '.git'))) return;
+    try {
+        execFileSync('git', ['rev-parse', '--quiet', '--verify', `refs/tags/${tag}`], { cwd: moduleDir, stdio: 'pipe' });
+    } catch {
+        try {
+            execFileSync('git', ['tag', tag, 'HEAD'], { cwd: moduleDir, stdio: 'pipe' });
+        } catch {
+            // Non-fatal — see above.
+        }
+    }
+}
+
+/**
+ * True when a cached module's `.bmad-channel.json` records a resolution other
+ * than the pin the manifest asks for — e.g. a cache bmad-method cloned at a
+ * newer upstream release before pinning existed. Such a cache must be
+ * replaced from the bundle: left alone, bmad-method would wipe it to switch
+ * channels and need the network to re-clone.
+ *
+ * @param {string} moduleDir - Cached module directory
+ * @param {{ pinTag?: string }} [manifestEntry] - Manifest entry for the module
+ * @returns {Promise<boolean>} `false` when the entry has no pinTag
+ */
+async function cacheDiffersFromPin(moduleDir, manifestEntry) {
+    if (!manifestEntry || !manifestEntry.pinTag) return false;
+    try {
+        const marker = JSON.parse(await fs.readFile(path.join(moduleDir, '.bmad-channel.json'), 'utf8'));
+        return marker.channel !== 'pinned' || marker.version !== manifestEntry.pinTag;
+    } catch {
+        // No marker or unreadable — we can't tell what this cache holds.
+        return true;
+    }
+}
+
 async function prePopulateBmadCache(force = false) {
     const cacheSource = path.join(__dirname, 'bmad-cache');
     if (!(await fs.pathExists(cacheSource))) {
@@ -2195,12 +2306,17 @@ async function prePopulateBmadCache(force = false) {
                 && (await fs.pathExists(path.join(src, 'skills')))
                 && !(await fs.pathExists(path.join(dst, 'skills')));
 
+            const manifestEntry = manifest && manifest.modules ? manifest.modules[mod] : null;
+            const offPin = (await fs.pathExists(dst)) && (await cacheDiffersFromPin(dst, manifestEntry));
+
             if (await fs.pathExists(dst)) {
-                if (force || structurallyBroken) {
+                if (force || structurallyBroken || offPin) {
                     await fs.remove(dst);
                     await fs.copy(src, dst);
                     restoreGitDir(dst);
-                    const reason = structurallyBroken ? '(structural repair)' : '';
+                    const reason = structurallyBroken
+                        ? '(structural repair)'
+                        : offPin ? `(not at pinned ${manifestEntry.pinTag})` : '';
                     console.log(chalk.cyan(`    + Replaced cached module: ${mod} ${reason}`));
                     replaced++;
                 } else {
@@ -2218,7 +2334,7 @@ async function prePopulateBmadCache(force = false) {
             // skip path, since prior ma-agents versions copied the module
             // without the marker and left users wedged on offline installs.
             // ensureCacheMarker no-ops when the marker already exists.
-            const wrote = await ensureCacheMarker(dst, manifest && manifest.modules ? manifest.modules[mod] : null);
+            const wrote = await ensureCacheMarker(dst, manifestEntry);
             if (wrote) markersWritten++;
         }
 
@@ -3747,4 +3863,7 @@ module.exports = {
     getDefaultBmadModules,
     // 3.12.2 — offline-fallback marker for bmad-method's cloneExternalModule
     ensureCacheMarker,
+    // Bug: external modules pinned to the bundled release (--pin)
+    getBundledModulePins,
+    cacheDiffersFromPin,
 };