@ikunin/sprintpilot 2.3.5 → 2.3.7

package/_Sprintpilot/manifest.yaml

@@ -1,6 +1,6 @@
 addon:
   name: sprintpilot
-  version: 2.3.5
+  version: 2.3.7
   description: Sprintpilot — autopilot and multi-agent addon for BMad Method (git workflow, parallel agents, autonomous story execution)
   bmad_compatibility: ">=6.2.0"
   modules:

package/_Sprintpilot/scripts/resolve-dag.js

@@ -640,6 +640,50 @@ function hasGraphvizBinary() {
   }
 }
 
+// Find the Mermaid CLI binary on PATH. Cross-platform: npm installs
+// CLI tools as `.cmd` shims on Windows, and Node's spawn family does
+// not auto-resolve PATHEXT extensions without `shell: true`. We probe
+// platform-appropriate candidates explicitly. Returns the resolved
+// binary name (suitable for spawnSync) or null if none found.
+function findMermaidCliBinary() {
+  const candidates =
+    process.platform === 'win32'
+      ? ['mmdc.cmd', 'mmdc.ps1', 'mmdc.bat', 'mmdc.exe', 'mmdc']
+      : ['mmdc'];
+  for (const name of candidates) {
+    try {
+      const r = spawnSync(name, ['--version'], { stdio: 'ignore' });
+      if (r.status === 0) return name;
+    } catch {
+      // ENOENT etc — try next candidate
+    }
+  }
+  return null;
+}
+
+// Try to render `<mmd>` to a sibling `<mmd>.png` via mmdc. Returns
+//   { written: true, file: <png-path> }                                — success
+//   { written: false, reason: 'mmdc-missing' }                         — toolchain absent
+//   { written: false, reason: 'render-failed', message: <stderr> }    — toolchain errored
+// Never throws; the caller threads the result into the envelope.
+function tryRenderMermaidPng(mmdPath) {
+  const bin = findMermaidCliBinary();
+  if (!bin) {
+    return { written: false, reason: 'mmdc-missing' };
+  }
+  const pngPath = mmdPath.endsWith('.mmd') ? mmdPath.slice(0, -4) + '.png' : mmdPath + '.png';
+  const r = spawnSync(bin, ['-i', mmdPath, '-o', pngPath, '-b', 'transparent', '--quiet'], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+    windowsHide: true,
+  });
+  if (r.status !== 0) {
+    const message = (r.stderr || r.stdout || 'mmdc exited non-zero').trim();
+    return { written: false, reason: 'render-failed', message };
+  }
+  return { written: true, file: pngPath };
+}
+
 function defaultRenderOutputPath(projectRoot, format) {
   const ext = format === 'graphviz' ? 'dot' : 'mmd';
   return path.join(projectRoot, '_bmad-output', 'implementation-artifacts', `sprint-plan-dag.${ext}`);
@@ -694,12 +738,29 @@ function runRender({ projectRoot, epic, format, output }) {
     };
   }
 
+  // Sibling-PNG render (mermaid only). Non-fatal: caller surfaces the
+  // reason if mmdc is missing or errored. graphviz users render via
+  // `dot -Tpng …` themselves; no auto-PNG for that format.
+  let pngEnvelope = null;
+  if (effectiveFormat === 'mermaid') {
+    const pngResult = tryRenderMermaidPng(outputPath);
+    if (pngResult.written) {
+      pngEnvelope = { png_file: pngResult.file };
+    } else {
+      pngEnvelope = {
+        png_reason: pngResult.reason,
+        ...(pngResult.message ? { png_message: pngResult.message } : {}),
+      };
+    }
+  }
+
   return {
     wrote: true,
     file: outputPath,
     format: effectiveFormat,
     requested_format: requestedFormat,
     ...(fallbackReason ? { fallback: fallbackReason } : {}),
+    ...(pngEnvelope || {}),
     nodes: dag.nodes.length,
     edges: dag.edges.length,
   };

package/_Sprintpilot/skills/sprintpilot-dependency-graph/workflow.md

@@ -113,8 +113,8 @@ node _Sprintpilot/scripts/resolve-dag.js render --format mermaid \
   [--epic <id>] [--output <path>] --project-root <root>
 ```
 
-Returns JSON `{wrote, file, format, nodes, edges, fallback?}`. Then
-read the rendered file and inline its contents in a ```mermaid fenced
+Returns JSON `{wrote, file, format, nodes, edges, fallback?, png_file?, png_reason?, png_message?}`.
+Then read the rendered file and inline its contents in a ```mermaid fenced
 code block so the chat client (Claude Code, etc.) renders the diagram
 inline. Also report the file path so the user can preview elsewhere:
 
@@ -134,6 +134,35 @@ cross-references back to the user's tracker (Jira / Linear / GitHub /
 GitLab). Stories/epics without an issue_id render with the bare key —
 silence communicates "not tracked" rather than spamming `[no issue]`.
 
+**PNG sibling render.** As a side-effect of the mermaid render, the
+script tries to produce a `<file>.png` next to the `.mmd` via the
+official Mermaid CLI (`mmdc`). You **MUST** examine the envelope's
+`png_*` fields and surface one of the three outcomes to the user —
+silence is a bug, especially when mmdc is missing.
+
+- **`png_file` set** → PNG produced. Report:
+  > Also wrote PNG: `<png_file>` (rendered via Mermaid CLI).
+
+- **`png_reason: "mmdc-missing"`** → Mermaid CLI is not installed.
+  You **MUST** tell the user how to install it, verbatim:
+  > PNG render skipped — Mermaid CLI (`mmdc`) is not installed.
+  > To get a `.png` alongside the `.mmd` next time, install it:
+  >
+  > ```
+  > npm install -g @mermaid-js/mermaid-cli
+  > ```
+  >
+  > Works on Windows, Linux, and macOS. Requires Node 18+.
+  > After installing, re-run `/sprintpilot-dependency-graph mermaid`.
+
+  Do not silently drop this. The `.mmd` file is still useful but the
+  install hint is the primary value of this code path.
+
+- **`png_reason: "render-failed"`** → mmdc was found but errored.
+  Report the `png_message` verbatim and suggest re-running with
+  `mmdc -i <mmd-path> -o <png-path>` outside the skill to see the
+  full toolchain error.
+
 ### Graphviz
 
 ```
@@ -224,4 +253,6 @@ have different leading hyphen segments — leverage the JSON output).</action>
 | Plan file corrupt | Surface the parse error from `sprint-plan.js read`; suggest re-running the planning skill. |
 | Cycle detected (`resolve-dag.js` exits 1 with "cycle detected") | Report the cycling node list verbatim. Suggest reviewing `plan.dependencies.stories` for the named keys, or re-running `/sprintpilot-plan-sprint` to re-infer. |
 | Graphviz binary missing | Note the fallback; tell the user how to install `dot`; do NOT silently retry with a different format. |
+| Mermaid CLI (`mmdc`) missing (mermaid format, `png_reason: "mmdc-missing"`) | You **MUST** report the install command: `npm install -g @mermaid-js/mermaid-cli` (cross-platform, requires Node 18+). The `.mmd` file is still written, but never skip the install hint — that's the user-actionable signal. |
+| Mermaid CLI present but errored (`png_reason: "render-failed"`) | Surface `png_message` verbatim; suggest re-running `mmdc -i <mmd> -o <png>` outside the skill to see the full toolchain error. |
 | Output file write fails (permission, disk full) | Surface the error from the resolve-dag stderr; chat-render the JSON output as a fallback so the user still gets something usable. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ikunin/sprintpilot",
-  "version": "2.3.5",
+  "version": "2.3.7",
   "description": "Sprintpilot — autopilot and multi-agent addon for BMad Method v6: git workflow, parallel agents, autonomous story execution",
   "license": "Apache-2.0",
   "repository": {