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

package/bin/cli.js

@@ -40,6 +40,7 @@ const { uninstallProfileArtifacts } = require('../lib/uninstall');
 const bmad = require('../lib/bmad');
 const { getBmadPlatformCode } = require('../lib/agents');
 const { enumerateCustomSource, NFR71_WARNING, CustomMarketplaceError, reconcileCustomMarketplaceSelection, registryTrustLabel } = require('../lib/custom-marketplace');
+const { setLogSink, diag, diagError } = require('../lib/diag');
 const { handleCreateSkill, handleValidateSkill, handleSetMandatory, handleCustomizeAgent, handleCreateAgent } = require('../lib/skill-authoring');
 
 const PKG = require('../package.json');
@@ -55,9 +56,21 @@ const VERSION = PKG.version;
  */
 function setupLogging(logFilePath) {
   const logFd = fs.openSync(logFilePath, 'w');
-  const header = `[${new Date().toISOString()}] ${NAME} v${VERSION} — log started\n`;
+  // Rich header — the environment facts needed to make sense of a report later:
+  // exact version, how it was invoked, runtime, platform, and where it ran.
+  const header =
+    `[${new Date().toISOString()}] ${NAME} v${VERSION} — log started\n` +
+    `  argv:     ${process.argv.slice(1).join(' ')}\n` +
+    `  node:     ${process.version}\n` +
+    `  platform: ${process.platform} ${process.arch}\n` +
+    `  cwd:      ${process.cwd()}\n`;
   fs.writeSync(logFd, header);
 
+  // Route log-file-only diagnostics (lib/diag.js) to this fd. These breadcrumbs
+  // (custom-marketplace phases, swallowed error causes, etc.) land ONLY in the
+  // log, never on the user's console.
+  setLogSink((s) => { try { fs.writeSync(logFd, s); } catch { /* ignore */ } });
+
   const origStdoutWrite = process.stdout.write.bind(process.stdout);
   const origStderrWrite = process.stderr.write.bind(process.stderr);
 
@@ -81,6 +94,7 @@ function setupLogging(logFilePath) {
     process.stderr.write = origStderrWrite;
     const footer = `\n[${new Date().toISOString()}] log ended\n`;
     try { fs.writeSync(logFd, footer); } catch { /* ignore */ }
+    setLogSink(null);
     try { fs.closeSync(logFd); } catch { /* ignore */ }
     delete process.env.MA_AGENTS_LOG_ACTIVE;
   };
@@ -1025,13 +1039,16 @@ async function promptCustomMarketplace({ bmadCustomSourceFlag = '', yesFlag = fa
   }
 
   let enumerated;
+  diag('custom-source: enumerate begin', { source });
   try {
     enumerated = await enumerateCustomSource(source);
   } catch (err) {
     // Fail clean (spike §3 contract) — a short, human-readable message only.
     // Never print err.stack here: an unreachable/unauthorized custom source
     // must not dump a raw upstream stack, and must never touch the base
-    // install (the rest of installWizard proceeds unaffected).
+    // install (the rest of installWizard proceeds unaffected). The full cause
+    // (and stack) goes to the LOG FILE only, for diagnosis.
+    diagError('custom-source: enumerate failed', err);
     const message = err instanceof CustomMarketplaceError ? err.message : `Custom marketplace source error: ${err.message}`;
     console.log(chalk.red(`\n  ${message}`));
     console.log(chalk.gray('  Skipping custom marketplace source; the rest of the install is unaffected.'));
@@ -1039,6 +1056,11 @@ async function promptCustomMarketplace({ bmadCustomSourceFlag = '', yesFlag = fa
   }
 
   const { plugins, mode, rootDir, sourceUrl } = enumerated;
+  diag('custom-source: enumerated', {
+    source, mode, rootDir, sourceUrl,
+    pluginCount: (plugins || []).length,
+    codes: (plugins || []).map((p) => p.code),
+  });
   if (!plugins || plugins.length === 0) {
     console.log(chalk.yellow(`  Custom marketplace source "${source}" declared no plugins — nothing to select.`));
     return { source, mode, selectedCodes: [], plugins: [], rootDir, sourceUrl };
@@ -1117,12 +1139,16 @@ async function promptCustomMarketplace({ bmadCustomSourceFlag = '', yesFlag = fa
  */
 async function reconcileCustomMarketplaceOnUpdate({ projectRoot }) {
   const persisted = getCustomMarketplaceSelection(projectRoot);
+  diag('custom-source: reconcile on update', persisted
+    ? { source: persisted.source, mode: persisted.mode, selectedCodes: persisted.selectedCodes }
+    : { persisted: false });
   if (!persisted) return undefined;
 
   let enumerated;
   try {
     enumerated = await enumerateCustomSource(persisted.source);
   } catch (err) {
+    diagError('custom-source: reconcile re-enumerate failed', err);
     const message = err instanceof CustomMarketplaceError ? err.message : `Custom marketplace source error: ${err.message}`;
     console.log(chalk.red(`\n  Custom marketplace update FAILED: ${message}`));
     console.log(
@@ -1547,6 +1573,12 @@ async function installWizard(preselectedSkill, preselectedAgents, customPath, fo
         }
       }
       if (customMarketplaceSelection && customMarketplaceSelection.selectedCodes.length > 0) {
+        diag('custom-source: install begin', {
+          mode: customMarketplaceSelection.mode,
+          source: customMarketplaceSelection.source,
+          selectedCodes: customMarketplaceSelection.selectedCodes,
+          baseBmadOk,
+        });
         if (!baseBmadOk) {
           // AC 6 (30.6b) — never layer --custom-source onto a project with no
           // (or a broken) base BMAD install. The rest of the install is
@@ -1565,10 +1597,14 @@ async function installWizard(preselectedSkill, preselectedAgents, customPath, fo
               tools: bmadTools,
               selection: customMarketplaceSelection,
             });
+            diag('custom-source: install result', { success: !!success });
             if (success) {
               console.log(chalk.green('  Custom marketplace subset installed successfully!'));
             }
           } catch (err) {
+            // User sees the one-liner; the full cause/stack (which entry, the
+            // git/resolve error, the FR238 zero-module detail) goes to the log.
+            diagError('custom-source: install failed', err);
             console.log(chalk.red(`\n  Custom marketplace install failed: ${err.message}`));
           }
         }

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

package/lib/custom-marketplace.js

@@ -40,6 +40,7 @@
 const path = require('node:path');
 const fs = require('fs-extra');
 const yaml = require('js-yaml');
+const { diag } = require('./diag');
 
 /** Deep, pinned-internal require path (NFR17). Single call site. */
 const CUSTOM_MODULE_MANAGER_PATH = 'bmad-method/tools/installer/modules/custom-module-manager.js';
@@ -554,6 +555,19 @@ async function resolveSelectedPlugins({ mode, rootDir, sourceUrl, plugins, selec
 function assertResolutionNonEmptyAndUniqueLeaves(resolvedByPlugin, { source = '', mode = null } = {}) {
     const allModules = resolvedByPlugin.flatMap((r) => r.resolved || []);
 
+    // Per-plugin resolution detail → log file only. When the guard below trips,
+    // this line pinpoints WHICH entry resolved to nothing (and how many
+    // skills each resolved module got) — the crux of a "zero modules" report.
+    diag('custom-source: resolution', {
+        source, mode,
+        perPlugin: resolvedByPlugin.map((r) => ({
+            plugin: (r.plugin && (r.plugin.code || r.plugin.name)) || (r.rawPlugin && r.rawPlugin.name) || '?',
+            modules: (r.resolved || []).length,
+            skills: (r.resolved || []).reduce((n, m) => n + ((m.skillPaths && m.skillPaths.length) || 0), 0),
+        })),
+        totalModules: allModules.length,
+    });
+
     if (allModules.length === 0) {
         // AC7 — a direct-mode source that resolves to nothing is the exact
         // failure a mis-pointed registry URL used to produce. Name the likely
@@ -741,6 +755,13 @@ async function resolveRegistryEntry(plugin, resolveSourceFn, resolvePluginFn) {
     // source string.
     const safePinRef = pinRef && /^[\w.\-+/]+$/.test(pinRef) && !pinRef.includes(':') ? pinRef : null;
     const cloneInput = safePinRef ? `${plugin.repository}@${safePinRef}` : plugin.repository;
+    diag('custom-source: registry entry clone', {
+        code: plugin.code,
+        repository: plugin.repository,
+        pinRef: safePinRef,
+        approvedSha: plugin.approvedSha || null,
+        moduleDefinition: plugin.moduleDefinition || '(none — repo root)',
+    });
 
     let resolvedSource;
     try {
@@ -781,6 +802,12 @@ async function resolveRegistryEntry(plugin, resolveSourceFn, resolvePluginFn) {
         relModuleDirPosix === '.' ? entryRootDir : path.join(entryRootDir, ...relModuleDirPosix.split('/'));
     const skillNames = await scanSkillDirs(moduleBaseAbs);
     const skillRelPaths = skillNames.map((n) => (relModuleDirPosix === '.' ? n : `${relModuleDirPosix}/${n}`));
+    diag('custom-source: registry entry resolved', {
+        code: plugin.code,
+        moduleDir: relModuleDirPosix,
+        skillDirsFound: skillNames.length,
+        skills: skillNames,
+    });
 
     const rawPlugin = {
         name: plugin.code,

package/lib/diag.js

@@ -0,0 +1,86 @@
+'use strict';
+
+/**
+ * Log-file-only diagnostics.
+ *
+ * When `--log` is active, bin/cli.js#setupLogging installs a sink that writes
+ * to the log file descriptor. `diag()`/`diagError()` then emit structured
+ * breadcrumbs to the LOG FILE ONLY — never to the user's console (the wizard's
+ * user-facing output intentionally stays clean; e.g. a failed custom-marketplace
+ * source shows a one-line message, not a raw stack — NFR71). Without a sink
+ * (no `--log`), every call is a cheap no-op.
+ *
+ * This is how the swallowed root cause of a custom-marketplace failure (the
+ * git/clone/resolve error behind a clean CustomMarketplaceError, the per-entry
+ * module_definition that was missing, the FR238 zero-module trigger, etc.)
+ * reaches the log for post-hoc diagnosis without leaking to the terminal.
+ */
+
+let sink = null;
+
+/**
+ * @param {((text: string) => void)|null} fn - writer for log-file output, or null to disable.
+ */
+function setLogSink(fn) {
+  sink = typeof fn === 'function' ? fn : null;
+}
+
+/** @returns {boolean} whether diagnostics are being captured. */
+function isActive() {
+  return sink !== null;
+}
+
+function stamp() {
+  // new Date() is available in the CLI runtime (this is not a workflow script).
+  return new Date().toISOString();
+}
+
+function stringify(detail) {
+  if (typeof detail === 'string') return detail;
+  try {
+    return JSON.stringify(detail);
+  } catch {
+    return String(detail);
+  }
+}
+
+/**
+ * Emit one diagnostic breadcrumb to the log file (no-op without a sink).
+ * @param {string} label
+ * @param {*} [detail] - string or JSON-serializable value.
+ */
+function diag(label, detail) {
+  if (!sink) return;
+  let line = `[diag ${stamp()}] ${label}`;
+  if (detail !== undefined) line += `: ${stringify(detail)}`;
+  try {
+    sink(line + '\n');
+  } catch {
+    /* never let diagnostics break the install */
+  }
+}
+
+/**
+ * Emit an error — including its `stack` AND any wrapped `cause` (message +
+ * stack) — to the log file. This is the crucial bit for custom-marketplace
+ * failures, whose user-facing message deliberately hides the upstream cause.
+ * @param {string} label
+ * @param {Error|*} err
+ */
+function diagError(label, err) {
+  if (!sink || !err) return;
+  const parts = [`[diag ${stamp()}] ${label}: ${err.message || String(err)}`];
+  if (err.stack) parts.push(`  stack: ${err.stack}`);
+  if (err.cause) {
+    const c = err.cause;
+    parts.push(`  cause: ${(c && c.message) || String(c)}`);
+    if (c && c.stack) parts.push(`  cause.stack: ${c.stack}`);
+  }
+  try {
+    sink(parts.join('\n') + '\n');
+  } catch {
+    /* never let diagnostics break the install */
+  }
+}
+
+module.exports = { setLogSink, isActive, diag, diagError };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ma-agents",
-  "version": "3.17.0-beta.1",
+  "version": "3.17.0-beta.2",
   "description": "NPX tool to install skills for AI coding agents (Claude Code, Gemini, Copilot, Kilocode, Cline, Cursor, Roo Code)",
   "main": "index.js",
   "bin": {
@@ -8,7 +8,7 @@
   },
   "scripts": {
     "start": "node bin/cli.js",
-    "test": "node test/yes-flag.test.js && node test/skill-authoring.test.js && node test/skill-validation.test.js && node test/skill-mandatory.test.js && node test/skill-customize-agent.test.js && node test/create-agent.test.js && node test/generate-project-context.test.js && node test/build-bmad-args.test.js && node test/build-bmad-cache-reader.test.js && node test/bundle-filter-set-equality.test.js && node test/bmad-version-bump.test.js && node test/staging-6-10-0-regression.test.js && node test/uv-transition-resilience.test.js && node test/passthrough-reconciliation-6-9-0.test.js && node test/extension-module-restructure.test.js && node test/convert-agents-to-skills.test.js && node test/migration.test.js && node test/migration-validation.test.js && node test/story-15-5-workflow-skills.test.js && node test/repo-layout.test.js && node test/config-storage.test.js && node test/cross-repo-validation.test.js && node test/config-lost-on-update.test.js && node test/portable-paths.test.js && node test/cicd-remote-mode.test.js && node test/config-layout.test.js && node test/roo-code-agent.test.js && node test/roo-code-injection.test.js && node test/profile.test.js && node test/instruction-block.test.js && node test/instruction-injection.test.js && node test/agents-md.test.js && node test/instruction-block-git.test.js && node test/onprem-injection.test.js && node test/onprem-layer.test.js && node test/copilot-instructions-path.test.js && node test/roomodes.test.js && node test/clinerules.test.js && node test/cline-workflow-reconciliation.test.js && node test/reconfigure.test.js && node test/experimental-warning.test.js && node test/bmad-persona-phase-prefix.test.js && node test/f1a-on-prem-prefix-post-install.test.js && node test/retired-skills-migration.test.js && node test/rename-migration.test.js && node test/uninstall.test.js && node test/offline-recompile.test.js && node test/plugin-manifests.test.js && node test/demerzel-ml-removal-drift.test.js && node test/demerzel-deprecation-notice.test.js && node test/build-plugin.test.js && node test/config-path-migration.test.js && node test/gitignore-plugin-stage.test.js && node test/customizations-translation.test.js && node test/routing-parity.test.js && node test/bmad-extension.test.js && node test/integration-verification.test.js && node test/agent-scope.test.js && node test/obsolete-tool-dirs.test.js && node test/bmad-empty-tools-guard.test.js && node test/v68-pluginresolver-enumeration-passthrough.test.js && node test/agents.test.js && node test/installer.test.js && node test/bmad.test.js && node test/cli.test.js && node test/knowledge-atlas-smoke.test.js && node test/knowledge-atlas-manifest.test.js && node test/knowledge-atlas-render.test.js && node test/knowledge-atlas-graph.test.js && node test/knowledge-atlas-packaging.test.js && node test/knowledge-atlas-offline-safety.test.js && node test/knowledge-atlas-reconcile.test.js && node test/knowledge-atlas-determinism.test.js && node test/knowledge-atlas-degradation.test.js && node test/knowledge-atlas-realproject.test.js && node test/knowledge-atlas-link-integrity.test.js && node test/knowledge-atlas-config-scan.test.js && node test/knowledge-atlas-references.test.js && node test/agent-injection-strategy.test.js && node test/bmad-module-selection.test.js && node test/custom-marketplace-surface-drift.test.js && node test/custom-marketplace-wizard.test.js && node test/custom-marketplace-live-clone.test.js && node test/custom-marketplace-stage-install.test.js && node test/custom-marketplace-persist-reconcile.test.js && node test/demerzel-nondestructive-invariant.test.js && node test/fr243-custom-source-allowlist-nonleak.test.js && node test/custom-marketplace-registry.test.js",
+    "test": "node test/yes-flag.test.js && node test/skill-authoring.test.js && node test/skill-validation.test.js && node test/skill-mandatory.test.js && node test/skill-customize-agent.test.js && node test/create-agent.test.js && node test/generate-project-context.test.js && node test/build-bmad-args.test.js && node test/build-bmad-cache-reader.test.js && node test/bundle-filter-set-equality.test.js && node test/bmad-version-bump.test.js && node test/staging-6-10-0-regression.test.js && node test/uv-transition-resilience.test.js && node test/passthrough-reconciliation-6-9-0.test.js && node test/extension-module-restructure.test.js && node test/convert-agents-to-skills.test.js && node test/migration.test.js && node test/migration-validation.test.js && node test/story-15-5-workflow-skills.test.js && node test/repo-layout.test.js && node test/config-storage.test.js && node test/cross-repo-validation.test.js && node test/config-lost-on-update.test.js && node test/portable-paths.test.js && node test/cicd-remote-mode.test.js && node test/config-layout.test.js && node test/roo-code-agent.test.js && node test/roo-code-injection.test.js && node test/profile.test.js && node test/instruction-block.test.js && node test/instruction-injection.test.js && node test/agents-md.test.js && node test/instruction-block-git.test.js && node test/onprem-injection.test.js && node test/onprem-layer.test.js && node test/copilot-instructions-path.test.js && node test/roomodes.test.js && node test/clinerules.test.js && node test/cline-workflow-reconciliation.test.js && node test/reconfigure.test.js && node test/experimental-warning.test.js && node test/bmad-persona-phase-prefix.test.js && node test/f1a-on-prem-prefix-post-install.test.js && node test/retired-skills-migration.test.js && node test/rename-migration.test.js && node test/uninstall.test.js && node test/offline-recompile.test.js && node test/plugin-manifests.test.js && node test/demerzel-ml-removal-drift.test.js && node test/demerzel-deprecation-notice.test.js && node test/build-plugin.test.js && node test/config-path-migration.test.js && node test/gitignore-plugin-stage.test.js && node test/customizations-translation.test.js && node test/routing-parity.test.js && node test/bmad-extension.test.js && node test/integration-verification.test.js && node test/agent-scope.test.js && node test/obsolete-tool-dirs.test.js && node test/bmad-empty-tools-guard.test.js && node test/v68-pluginresolver-enumeration-passthrough.test.js && node test/agents.test.js && node test/installer.test.js && node test/bmad.test.js && node test/cli.test.js && node test/knowledge-atlas-smoke.test.js && node test/knowledge-atlas-manifest.test.js && node test/knowledge-atlas-render.test.js && node test/knowledge-atlas-graph.test.js && node test/knowledge-atlas-packaging.test.js && node test/knowledge-atlas-offline-safety.test.js && node test/knowledge-atlas-reconcile.test.js && node test/knowledge-atlas-determinism.test.js && node test/knowledge-atlas-degradation.test.js && node test/knowledge-atlas-realproject.test.js && node test/knowledge-atlas-link-integrity.test.js && node test/knowledge-atlas-config-scan.test.js && node test/knowledge-atlas-references.test.js && node test/agent-injection-strategy.test.js && node test/bmad-module-selection.test.js && node test/custom-marketplace-surface-drift.test.js && node test/custom-marketplace-wizard.test.js && node test/custom-marketplace-live-clone.test.js && node test/custom-marketplace-stage-install.test.js && node test/custom-marketplace-persist-reconcile.test.js && node test/demerzel-nondestructive-invariant.test.js && node test/fr243-custom-source-allowlist-nonleak.test.js && node test/custom-marketplace-registry.test.js && node test/diag.test.js",
     "build:bmad-cache": "node scripts/build-bmad-cache.js",
     "build:plugin": "node scripts/build-plugin.js",
     "build:atlas": "node scripts/build-atlas.js",