ma-agents 3.12.1 → 3.12.2

package/lib/bmad-extension-plugin/.claude-plugin/marketplace.json

@@ -37,7 +37,7 @@
       "name": "ma-skills",
       "source": "./",
       "description": "ma-agents extension module providing enterprise SDLC personas and operational workflow skills.",
-      "version": "3.12.1",
+      "version": "3.12.2",
       "author": {
         "name": "Alon Mayaffit"
       },

package/lib/bmad.js

@@ -1552,6 +1552,66 @@ async function deployClineWorkflows(projectRoot, tools = []) {
     }
 }
 
+/**
+ * Write bmad-method's `.bmad-channel.json` marker for an offline-cached
+ * module if one is not already present.
+ *
+ * Why this exists: bmad-method's `cloneExternalModule()` (in
+ * `node_modules/bmad-method/tools/installer/modules/external-manager.js`)
+ * resolves the install ref by hitting GitHub's API for the latest stable
+ * tag. On an air-gapped machine the API call throws and the function
+ * falls back to reading the cached marker via `readChannelMarker()`. If
+ * the marker is missing, it instead throws `Could not resolve stable tag
+ * for '<module>'` and aborts the entire install.
+ *
+ * Pre-3.12.2 ma-agents copied each module's source tree (with `.git/`
+ * restored from `_git_preserved/`) into `~/.bmad/cache/external-modules/`
+ * but never wrote the marker. The result: any first-time offline install
+ * that pre-populated more than `bmm` failed at the first external module.
+ * Pre-3.12.1 the bug was masked because ma-agents only ever requested
+ * `--modules bmm` (built into bmad-method itself, no cache-marker check).
+ *
+ * The marker schema is the same one bmad-method writes after a successful
+ * online clone (line 419 of external-manager.js). Channel defaults to
+ * `stable` because that's bmad-method's own default when a registry
+ * entry has no `default_channel` field.
+ *
+ * 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
+ *   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
+ */
+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;
+    try {
+        await fs.writeFile(
+            markerPath,
+            JSON.stringify(
+                {
+                    channel: 'stable',
+                    version: manifestEntry.branch || 'main',
+                    sha: manifestEntry.commitSha,
+                    writtenAt: new Date().toISOString(),
+                },
+                null,
+                2,
+            ),
+        );
+        return true;
+    } catch {
+        // Best-effort — marker is a fallback, not a correctness requirement.
+        // If we can't write it, bmad-method will surface its own error.
+        return false;
+    }
+}
+
 async function prePopulateBmadCache(force = false) {
     const cacheSource = path.join(__dirname, 'bmad-cache');
     if (!(await fs.pathExists(cacheSource))) {
@@ -1563,10 +1623,23 @@ async function prePopulateBmadCache(force = false) {
         const targetDir = path.join(os.homedir(), '.bmad', 'cache', 'external-modules');
         await fs.ensureDir(targetDir);
 
+        // Load manifest once so each module copy can stamp a `.bmad-channel.json`
+        // marker for bmad-method's offline fallback. Missing/malformed manifest
+        // is non-fatal — copy still happens, marker is just skipped.
+        let manifest = null;
+        try {
+            const manifestPath = path.join(cacheSource, 'cache-manifest.json');
+            if (await fs.pathExists(manifestPath)) {
+                manifest = JSON.parse(await fs.readFile(manifestPath, 'utf8'));
+            }
+        } catch {
+            manifest = null;
+        }
+
         const entries = await fs.readdir(cacheSource);
         const modules = entries.filter(e => e !== 'cache-manifest.json');
 
-        let copied = 0, skipped = 0, replaced = 0;
+        let copied = 0, skipped = 0, replaced = 0, markersWritten = 0;
 
         for (const mod of modules) {
             const src = path.join(cacheSource, mod);
@@ -1598,11 +1671,21 @@ async function prePopulateBmadCache(force = false) {
                 console.log(chalk.cyan(`    + Pre-populated cached module: ${mod}`));
                 copied++;
             }
+
+            // Stamp the offline-fallback marker. Always attempt — even on the
+            // 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);
+            if (wrote) markersWritten++;
         }
 
         if (copied > 0 || replaced > 0) {
             console.log(chalk.gray(`  Cache pre-population complete: ${copied} copied, ${skipped} skipped, ${replaced} replaced`));
         }
+        if (markersWritten > 0) {
+            console.log(chalk.gray(`  Wrote ${markersWritten} offline-fallback marker(s) (.bmad-channel.json)`));
+        }
     } catch (err) {
         console.error(chalk.red(`  Cache pre-population failed: ${err.message}`));
     }
@@ -2724,4 +2807,6 @@ module.exports = {
     getInstallableBmadModules,
     getInstalledBmadModules,
     resolveBmadModules,
+    // 3.12.2 — offline-fallback marker for bmad-method's cloneExternalModule
+    ensureCacheMarker,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ma-agents",
-  "version": "3.12.1",
+  "version": "3.12.2",
   "description": "NPX tool to install skills for AI coding agents (Claude Code, Gemini, Copilot, Kilocode, Cline, Cursor, Roo Code)",
   "main": "index.js",
   "bin": {