ma-agents 3.17.0-beta.2 → 3.17.0-beta.4

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.17.0-beta.2",
+      "version": "3.17.0-beta.4",
       "author": {
         "name": "Alon Mayaffit"
       },

package/lib/bmad.js

@@ -1719,12 +1719,19 @@ async function installCustomMarketplaceSubset({ projectRoot, modules, tools, sel
     let stagePath;
     let customSourceArg;
     let resolvedModules;
+    // Registry mode is best-effort across entries: `installedCodes` is the subset
+    // that actually resolved, `skipped` names the ones that did not (with reasons).
+    // discovery/direct are atomic → installedCodes = the selection, no skips.
+    let installedCodes = selection.selectedCodes;
+    let skipped = [];
     try {
         if (selection.mode === 'registry') {
             // Registry-index mode (this story): two-level clone+resolve+stage of
             // each selected entry's own repository. Shares the same stage dir +
             // install path as discovery/direct; only the staging step differs.
-            ({ stagePath, customSourceArg, resolvedModules } = await stageRegistryFn({
+            // Best-effort: a stale/broken entry is skipped (loudly), not fatal —
+            // it does not block the entries that do resolve.
+            ({ stagePath, customSourceArg, resolvedModules, installedCodes, skipped } = await stageRegistryFn({
                 source: selection.source,
                 plugins: selection.plugins,
                 selectedCodes: selection.selectedCodes,
@@ -1747,6 +1754,11 @@ async function installCustomMarketplaceSubset({ projectRoot, modules, tools, sel
         return false;
     }
 
+    // Defensive: a stager that predates the best-effort contract (or a partial
+    // mock) may omit these — fall back to treating the whole selection as installed.
+    if (!Array.isArray(installedCodes)) installedCodes = selection.selectedCodes;
+    if (!Array.isArray(skipped)) skipped = [];
+
     const command = buildBmadArgs({
         projectRoot,
         modules,
@@ -1755,7 +1767,7 @@ async function installCustomMarketplaceSubset({ projectRoot, modules, tools, sel
         customSource: customSourceArg,
     });
 
-    console.log(chalk.cyan(`  Installing custom marketplace subset (${selection.selectedCodes.join(', ')})...`));
+    console.log(chalk.cyan(`  Installing custom marketplace subset (${(installedCodes || []).join(', ')})...`));
     console.log(chalk.gray(`  Running: ${command}`));
 
     try {
@@ -1768,6 +1780,27 @@ async function installCustomMarketplaceSubset({ projectRoot, modules, tools, sel
         // for diagnostics on any post-invoke failure" policy (AC 8, 30.6b).
         cleanupStageFn(stagePath);
 
+        // LOUD best-effort report: any selected registry entry that could not be
+        // installed (unreachable repo, stale approved_tag, no skills) is named
+        // here with its reason — never silently omitted (FR238).
+        if (skipped && skipped.length > 0) {
+            console.log(
+                chalk.yellow(
+                    `\n  ${skipped.length} selected extension${skipped.length === 1 ? ' was' : 's were'} NOT installed ` +
+                    `(the rest installed fine):`
+                )
+            );
+            for (const s of skipped) {
+                console.log(chalk.yellow(`    - ${s.code}: ${s.reason}`));
+            }
+            console.log(
+                chalk.gray(
+                    '  These are typically stale/broken registry entries (e.g. an approved_tag that no longer ' +
+                    'exists upstream). Report them to the marketplace maintainer, or re-run without them.'
+                )
+            );
+        }
+
         // Story 30.7 (FR242) — persist source + selection (+ SHA pin) now that
         // the subset is actually installed. `resolvedModules[].cloneSha` is
         // only stamped for Git-URL sources (see custom-module-manager.js
@@ -1776,19 +1809,22 @@ async function installCustomMarketplaceSubset({ projectRoot, modules, tools, sel
         // failure is logged as a warning only — it must never turn an
         // otherwise-successful install into a reported failure.
         try {
+            // Persist only what ACTUALLY installed (`installedCodes`), not the
+            // raw selection — otherwise a skipped/broken entry would be recorded
+            // as installed and re-attempted (and re-reported) on every update.
             const persistEntry = {
                 source: selection.source,
                 sourceUrl: selection.sourceUrl ?? null,
                 mode: selection.mode,
-                selectedCodes: selection.selectedCodes,
+                selectedCodes: installedCodes,
             };
             if (selection.mode === 'registry') {
-                // AC5 — record each selected entry's registry-provided
+                // AC5 — record each INSTALLED entry's registry-provided
                 // `approved_sha` (the immutable pin the registry declares), plus
                 // its `approved_tag`. `sha` (the top-level field) mirrors the
                 // first available approved_sha for back-compat with readers that
                 // only look at `sha`.
-                const selectedSet = new Set(selection.selectedCodes);
+                const selectedSet = new Set(installedCodes);
                 const registryEntries = (selection.plugins || [])
                     .filter((p) => selectedSet.has(p.code))
                     .map((p) => ({ code: p.code, approvedSha: p.approvedSha ?? null, approvedTag: p.approvedTag ?? null }));

package/lib/custom-marketplace.js

@@ -478,6 +478,64 @@ async function scanDirectModeSkillDirs(rootDir) {
     return scanSkillDirs(rootDir);
 }
 
+/**
+ * Recursively collect every directory that contains a `SKILL.md`, returned as
+ * POSIX paths RELATIVE to `rootDirAbs`. Unlike {@link scanSkillDirs} (DIRECT
+ * children only), this walks the whole subtree: real BMAD modules nest skills
+ * under `agents/`, `workflows/<phase>/…`, etc. A dir that IS a skill (has
+ * SKILL.md) is recorded and not descended into (skills don't nest in skills);
+ * `node_modules`/`.git` are skipped.
+ */
+async function findSkillDirsRecursive(baseDirAbs, rootDirAbs) {
+    const found = [];
+    async function walk(dirAbs) {
+        if (await fs.pathExists(path.join(dirAbs, 'SKILL.md'))) {
+            found.push(toPosix(path.relative(rootDirAbs, dirAbs)));
+            return;
+        }
+        let entries;
+        try {
+            entries = await fs.readdir(dirAbs, { withFileTypes: true });
+        } catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (!entry.isDirectory()) continue;
+            if (entry.name === 'node_modules' || entry.name === '.git') continue;
+            await walk(path.join(dirAbs, entry.name));
+        }
+    }
+    await walk(baseDirAbs);
+    return found.sort();
+}
+
+/**
+ * Determine which directory to scan for a registry entry's skills, given the
+ * cloned repo root and the entry's `module_definition` (repo-relative path to
+ * its module.yaml). Skills are NOT always beside module.yaml:
+ *   - module.yaml at the skills' parent (`skills/module.yaml`,
+ *     `src/core-skills/module.yaml`, `src/module.yaml`) → scan THAT dir.
+ *   - module.yaml inside a `<name>-setup/assets/module.yaml` (bmad-method's
+ *     PluginResolver "setup skill" layout, e.g. suno-band-manager) → the
+ *     module's skills are SIBLINGS of the -setup skill, so scan the setup
+ *     skill's PARENT.
+ * Returns a POSIX path relative to the repo root ('.' = repo root). No
+ * module_definition → the repo root (direct-style scan).
+ */
+async function resolveRegistrySkillsRoot(entryRootDir, moduleDefPosix) {
+    if (!moduleDefPosix) return '.';
+    const mdDirPosix = path.posix.dirname(moduleDefPosix);
+    if (path.posix.basename(mdDirPosix) === 'assets') {
+        const setupSkillPosix = path.posix.dirname(mdDirPosix);
+        const setupSkillAbs = path.join(entryRootDir, ...setupSkillPosix.split('/'));
+        if (setupSkillPosix && (await fs.pathExists(path.join(setupSkillAbs, 'SKILL.md')))) {
+            const parentPosix = path.posix.dirname(setupSkillPosix);
+            return parentPosix === '' || parentPosix === '.' ? '.' : parentPosix;
+        }
+    }
+    return mdDirPosix === '' || mdDirPosix === '.' ? '.' : mdDirPosix;
+}
+
 /**
  * Resolve every selected plugin's installable skill/module layout via
  * bmad-method's own `CustomModuleManager#resolvePlugin` (the pinned-internal
@@ -784,10 +842,10 @@ async function resolveRegistryEntry(plugin, resolveSourceFn, resolvePluginFn) {
     // repo-relative path to the module's module.yaml; its directory is the
     // module root. Absent → fall back to the repo root (PluginResolver over the
     // whole clone), matching the AC3 fallback.
-    let relModuleDirPosix = '.';
+    let moduleDefPosix = null;
     if (plugin.moduleDefinition) {
-        const defPosix = toPosix(plugin.moduleDefinition).replace(/^\.\//, '');
-        const moduleYamlAbs = path.join(entryRootDir, ...defPosix.split('/'));
+        moduleDefPosix = toPosix(plugin.moduleDefinition).replace(/^\.\//, '');
+        const moduleYamlAbs = path.join(entryRootDir, ...moduleDefPosix.split('/'));
         if (!(await fs.pathExists(moduleYamlAbs))) {
             throw new CustomMarketplaceError(
                 `Registry entry '${plugin.code}': module_definition "${plugin.moduleDefinition}" ` +
@@ -795,27 +853,33 @@ async function resolveRegistryEntry(plugin, resolveSourceFn, resolvePluginFn) {
                 `repository layout changed; aborting before staging (FR238).`
             );
         }
-        relModuleDirPosix = path.posix.dirname(defPosix);
     }
 
-    const moduleBaseAbs =
-        relModuleDirPosix === '.' ? entryRootDir : path.join(entryRootDir, ...relModuleDirPosix.split('/'));
-    const skillNames = await scanSkillDirs(moduleBaseAbs);
-    const skillRelPaths = skillNames.map((n) => (relModuleDirPosix === '.' ? n : `${relModuleDirPosix}/${n}`));
+    // Skills are NOT necessarily beside module.yaml — resolve the module's real
+    // skills root (handles the setup-skill/assets layout and modules whose
+    // module.yaml sits at the skills' parent) and scan it RECURSIVELY. A shallow
+    // scan of module.yaml's own dir silently missed nested skills (gds/bmm) and
+    // the setup-skill layout entirely (suno), dropping those modules.
+    const skillsRootPosix = await resolveRegistrySkillsRoot(entryRootDir, moduleDefPosix);
+    const skillsRootAbs =
+        skillsRootPosix === '.' ? entryRootDir : path.join(entryRootDir, ...skillsRootPosix.split('/'));
+    const skillRelPaths = await findSkillDirsRecursive(skillsRootAbs, entryRootDir);
     diag('custom-source: registry entry resolved', {
         code: plugin.code,
-        moduleDir: relModuleDirPosix,
-        skillDirsFound: skillNames.length,
-        skills: skillNames,
+        moduleDef: moduleDefPosix,
+        skillsRoot: skillsRootPosix,
+        skillDirsFound: skillRelPaths.length,
+        skills: skillRelPaths,
     });
 
     const rawPlugin = {
         name: plugin.code,
         description: plugin.description || '',
         version: plugin.version || null,
-        source: relModuleDirPosix,
-        // Empty when the module dir has no SKILL.md subdirs — resolvePlugin then
-        // returns [] and the FR238 guard aborts cleanly (zero installable modules).
+        source: skillsRootPosix,
+        // Skill dirs relative to the repo root (what PluginResolver.resolve joins
+        // against repoPath). Empty → resolvePlugin returns [] and the selected
+        // entry surfaces in the per-entry guard below (never a silent drop).
         skills: skillRelPaths,
     };
 
@@ -877,11 +941,45 @@ async function stageRegistrySubset({ source, plugins, selectedCodes, projectRoot
         seenCodes.add(p.code);
     }
 
-    // Resolve every selected entry (each from its own clone) BEFORE touching the
-    // stage dir, so an unreachable/stale entry aborts clean with nothing staged.
+    // Resolve each selected entry INDEPENDENTLY (each from its own clone) BEFORE
+    // touching the stage dir. A community registry legitimately contains
+    // individually-broken/stale entries — an unreachable repo, a nonexistent
+    // approved_tag (e.g. the marketplace pinning wds@v0.1.0 when that tag does
+    // not exist), or a module with no skills. One bad entry must NOT nuke the
+    // whole multi-select. Best-effort: keep the resolvable entries, collect the
+    // skipped ones (with reasons), install the good ones, and let the caller
+    // report the skips LOUDLY. FR238 = no SILENT partial install — NOT
+    // all-or-nothing.
     const entries = [];
+    const skipped = [];
     for (const plugin of selected) {
-        entries.push(await resolveRegistryEntry(plugin, resolveSourceFn, resolvePluginFn));
+        let entry;
+        try {
+            entry = await resolveRegistryEntry(plugin, resolveSourceFn, resolvePluginFn);
+        } catch (err) {
+            diag('custom-source: registry entry skipped (resolve failed)', { code: plugin.code, error: err.message });
+            skipped.push({ code: plugin.code, reason: err.message });
+            continue;
+        }
+        if (!entry.resolved || entry.resolved.length === 0) {
+            const reason =
+                'resolved to zero installable modules — no SKILL.md directories found ' +
+                '(stale registry pointer, changed repo layout, or a module with no skills)';
+            diag('custom-source: registry entry skipped (zero modules)', { code: plugin.code, repository: plugin.repository });
+            skipped.push({ code: plugin.code, reason });
+            continue;
+        }
+        entries.push(entry);
+    }
+
+    // Hard-fail ONLY when nothing at all resolved — otherwise proceed with the
+    // resolvable subset and surface `skipped` to the caller for a loud report.
+    if (entries.length === 0) {
+        const detail = skipped.map((s) => `${s.code} (${s.reason})`).join('; ');
+        throw new CustomMarketplaceError(
+            `None of the ${selected.length} selected registry ${selected.length === 1 ? 'entry' : 'entries'} could be installed — ${detail}. ` +
+            `Nothing was staged (FR238).`
+        );
     }
 
     const allModules = assertResolutionNonEmptyAndUniqueLeaves(
@@ -937,7 +1035,13 @@ async function stageRegistrySubset({ source, plugins, selectedCodes, projectRoot
     );
 
     const customSourceArg = `./${CUSTOM_MARKETPLACE_STAGE_DIR_NAME}`;
-    return { stagePath, customSourceArg, resolvedModules: allModules };
+    return {
+        stagePath,
+        customSourceArg,
+        resolvedModules: allModules,
+        installedCodes: entries.map((e) => e.plugin.code),
+        skipped,
+    };
 }
 
 // ─── Story 30.7 — persist + re-enumerate/reconcile on update ───────────────
@@ -981,6 +1085,8 @@ module.exports = {
     CUSTOM_MARKETPLACE_STAGE_DIR_NAME,
     scanDirectModeSkillDirs,
     scanSkillDirs,
+    findSkillDirsRecursive,
+    resolveRegistrySkillsRoot,
     resolveSelectedPlugins,
     assertResolutionNonEmptyAndUniqueLeaves,
     stageCustomMarketplaceSubset,

package/package.json

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