Add Mermaid SVG/PNG CLI renderer

.github/workflows/unit-tests.yml

@@ -15,6 +15,8 @@ jobs:
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
+        with:
+          submodules: recursive
 
       - name: Set up Java 17
         uses: actions/setup-java@v4

.gitmodules

@@ -1,3 +1,6 @@
 [submodule "agents"]
 	path = agents
 	url = git@github.com:IstiN/dmtools-agents.git
+[submodule "dmtools-mermaid-renderer"]
+	path = dmtools-mermaid-renderer
+	url = git@github.com:IstiN/dmtools-mermaid-renderer.git

dmtools-ai-docs/per-skill-packages/dmtools-mermaid.md

@@ -0,0 +1,96 @@
+# dmtools-mermaid
+
+## Overview
+
+`dmtools-mermaid` is the DMtools skill for rendering Mermaid diagrams to SVG and PNG files entirely server-side — no Playwright, no browser, no network required. It uses an embedded GraalJS Mermaid engine for SVG generation and Apache Batik for SVG→PNG rasterisation.
+
+Supports all major Mermaid diagram types: flowchart, sequence, class, state, ER, user-journey, gantt, pie, git, mindmap, kanban, quadrant, requirement, timeline, venn, block, architecture, C4, sankey, radar, xy, treemap, treeview, ishikawa, packet, wardley.
+
+## Package / Artifact
+
+- Java package: `com.github.istin.dmtools.mermaid`
+- Renderer module: `com.github.istin:dmtools-mermaid-renderer` (submodule `dmtools-mermaid-renderer`)
+- Focused slash command: `/dmtools-mermaid`
+
+## Installer / CLI example
+
+```bash
+curl -fsSL https://github.com/epam/dm.ai/releases/latest/download/skill-install.sh | bash -s -- --skills mermaid
+```
+
+```bash
+bash install.sh --skills mermaid
+```
+
+## CLI commands
+
+```bash
+# Render to SVG (vector, lossless)
+dmtools mermaid_to_svg "flowchart TD; A[Start] --> B[Done]" --output diagram.svg
+
+# Render to PNG (raster, suitable for embedding in docs/PRs)
+dmtools mermaid_to_png "flowchart TD; A[Start] --> B[Done]" --output diagram.png
+
+# Generate diagrams from Confluence / Jira pages
+dmtools mermaid_index_generate confluence '["SPACE/pages/**"]' --storage_path ./diagrams
+```
+
+## Usage in JavaScript agents
+
+```javascript
+// Render a diagram to SVG or PNG from within a JS agent
+const svgPath = mermaid_to_svg("classDiagram\n  class User { +String name }",  "--output user.svg");
+const pngPath = mermaid_to_png("pie title Breakdown\n  \"A\":40\n  \"B\":60", "--output pie.png");
+```
+
+## Supported diagram types
+
+| Category | Types |
+|----------|-------|
+| Flow / Logic | `flowchart`, `sequenceDiagram`, `stateDiagram` |
+| Structure | `classDiagram`, `erDiagram`, `requirementDiagram`, `block`, `architecture`, `C4Context` |
+| Planning | `gantt`, `timeline`, `kanban`, `journey` (user journey) |
+| Data | `pie`, `xychart`, `sankey`, `quadrantChart`, `radar`, `treemap` |
+| Knowledge | `mindmap`, `gitGraph`, `venn`, `ishikawa`, `treeview`, `packet`, `wardley` |
+
+## Configuration
+
+No external API credentials required — the renderer runs entirely in-process using GraalJS. Only the dmtools JAR and the `dmtools-mermaid-renderer` submodule are needed.
+
+Ensure the submodule is initialised when building from source:
+```bash
+git submodule update --init dmtools-mermaid-renderer
+```
+
+## Compatibility / Supported versions
+
+- Requires Java 17+
+- GraalJS polyglot engine (bundled via `org.graalvm.polyglot`)
+- Apache Batik 1.17+ for PNG rasterisation
+- Compatible with current DMtools focused skill releases
+
+## Security & Permissions
+
+- No external network calls are made during rendering
+- Mermaid source text is processed in-memory — do not pass sensitive data as diagram text if logs are forwarded externally
+- Output files are written to the path you specify; ensure the target directory has correct permissions
+
+## MCP Tools reference
+
+See [mermaid-tools.md](../references/mcp-tools/mermaid-tools.md) for full parameter documentation of all 5 tools:
+- `mermaid_to_svg`
+- `mermaid_to_png`
+- `mermaid_index_generate`
+- `mermaid_index_read`
+- `mermaid_index_read_list`
+
+## Linkbacks
+
+- [Central installation guide](../references/installation/README.md)
+- [Per-skill package index](index.md)
+- [Mermaid MCP tools reference](../references/mcp-tools/mermaid-tools.md)
+
+## Maintainer / Contact
+
+- Maintainer: DMtools Team
+- Support: [github.com/epam/dm.ai/issues](https://github.com/epam/dm.ai/issues)

dmtools-ai-docs/per-skill-packages/index.md

@@ -13,6 +13,7 @@ This page is the canonical catalogue for the approved focused DMtools skill pack
 | `dmtools-testrail` | `/dmtools-testrail` | `com.github.istin.dmtools.testrail` | `com.github.istin:dmtools-testrail` |
 | `dmtools-teams` | `/dmtools-teams` | `com.github.istin.dmtools.microsoft.teams` | `com.github.istin:dmtools-teams` |
 | `dmtools-report` | `/dmtools-report` | `com.github.istin.dmtools.report` | `com.github.istin:dmtools-report` |
+| `dmtools-mermaid` | `/dmtools-mermaid` | `com.github.istin.dmtools.mermaid` | `com.github.istin:dmtools-mermaid-renderer` |
 
 ## Child pages
 
@@ -25,3 +26,4 @@ This page is the canonical catalogue for the approved focused DMtools skill pack
 - [dmtools-testrail](dmtools-testrail.md)
 - [dmtools-teams](dmtools-teams.md)
 - [dmtools-report](dmtools-report.md)
+- [dmtools-mermaid](dmtools-mermaid.md)

dmtools-ai-docs/references/mcp-tools/mermaid-tools.md

@@ -1,5 +1,184 @@
 # MERMAID MCP Tools
 
+**Total Tools**: 5
+
+## Quick Reference
+
+```bash
+# List all mermaid tools
+dmtools list | jq '.tools[] | select(.name | startswith("mermaid_"))'
+
+# Render Mermaid text to SVG file
+dmtools mermaid_to_svg "flowchart TD; A[Start] --> B[Done]" --output diagram.svg
+
+# Render Mermaid text to PNG file
+dmtools mermaid_to_png "flowchart TD; A[Start] --> B[Done]" --output diagram.png
+
+# Generate diagrams from Confluence / Jira content
+dmtools mermaid_index_generate [arguments]
+```
+
+## Usage in JavaScript Agents
+
+```javascript
+// Render a diagram to SVG or PNG
+const svgPath = mermaid_to_svg("flowchart TD; A --> B", "--output diagram.svg");
+const pngPath = mermaid_to_png("flowchart TD; A --> B", "--output diagram.png");
+
+// Index-based helpers
+const result = mermaid_index_generate(...);
+const result = mermaid_index_read_list(...);
+const result = mermaid_index_read(...);
+```
+
+## Available Tools
+
+| Tool Name | Description | Parameters |
+|-----------|-------------|------------|
+| `mermaid_to_svg` | Render a Mermaid diagram definition to an SVG file using the headless GraalJS renderer (no browser required). Supports all major diagram types: flowchart, sequence, class, state, ER, user-journey, gantt, pie, git, mindmap, kanban, quadrant, requirement, timeline, venn, block, architecture, C4, sankey, radar, xy, treemap, treeview, ishikawa, packet, wardley. | `diagram_text` (string, **required**)<br>`--output` (string, **required**) |
+| `mermaid_to_png` | Render a Mermaid diagram definition to a PNG image file using the headless GraalJS + Apache Batik renderer (no browser required). Same diagram-type coverage as `mermaid_to_svg`. | `diagram_text` (string, **required**)<br>`--output` (string, **required**) |
+| `mermaid_index_generate` | Generate Mermaid diagrams from content sources (Confluence or Jira) based on include/exclude patterns. Processes content recursively and stores diagrams in hierarchical file structure. | `integration` (string, **required**)<br>`include_patterns` (array, **required**)<br>`exclude_patterns` (array, optional)<br>`storage_path` (string, **required**)<br>`custom_fields` (array, optional)<br>`include_comments` (boolean, optional) |
+| `mermaid_index_read` | Read all Mermaid diagram files (.mmd) from storage path recursively. Returns list of diagrams with their paths and content. | `integration` (string, **required**)<br>`storage_path` (string, **required**) |
+| `mermaid_index_read_list` | Read all Mermaid diagram files (.mmd) from storage path recursively. Returns list of ToText objects with paths and content. | `integration` (string, **required**)<br>`storage_path` (string, **required**) |
+
+## Detailed Parameter Information
+
+### `mermaid_to_svg`
+
+Render a Mermaid diagram definition to an SVG vector-graphics file. Uses the embedded GraalJS Mermaid engine — no Playwright, no browser, no network required. Output is a self-contained SVG suitable for embedding in documents, web pages, or CI artefacts.
+
+**Parameters:**
+
+- **`diagram_text`** (string) 🔴 Required
+  - Full Mermaid diagram source text (any supported diagram type)
+  - Example: `flowchart TD; A[Start] --> B[Done]`
+
+- **`--output`** (string) 🔴 Required
+  - Destination file path for the SVG output
+  - Example: `./output/diagram.svg`
+
+**Supported diagram types:** flowchart, sequenceDiagram, classDiagram, stateDiagram, erDiagram, journey, gantt, pie, gitGraph, mindmap, kanban, quadrantChart, requirementDiagram, timeline, venn, block, architecture, C4Context, sankey, radar, xychart, treemap, treeview, ishikawa, packet, wardley
+
+**Example:**
+```bash
+dmtools mermaid_to_svg "flowchart TD; A[Start] --> B{Decision} --> C[End]" --output out.svg
+```
+
+```javascript
+const svgFile = mermaid_to_svg("sequenceDiagram\n  Alice->>Bob: Hello\n  Bob-->>Alice: Hi", "--output seq.svg");
+```
+
+---
+
+### `mermaid_to_png`
+
+Render a Mermaid diagram definition to a PNG raster image. Uses the embedded GraalJS Mermaid engine for SVG generation and Apache Batik for SVG→PNG rasterisation — no Playwright, no browser required. Output is a PNG file at screen resolution (~96 DPI).
+
+**Parameters:**
+
+- **`diagram_text`** (string) 🔴 Required
+  - Full Mermaid diagram source text (any supported diagram type)
+  - Example: `flowchart TD; A[Start] --> B[Done]`
+
+- **`--output`** (string) 🔴 Required
+  - Destination file path for the PNG output
+  - Example: `./output/diagram.png`
+
+**Example:**
+```bash
+dmtools mermaid_to_png "classDiagram\n  class Animal { +String name\n  +speak() }" --output class.png
+```
+
+```javascript
+const pngFile = mermaid_to_png("pie title Pet adoption\n  \"Dogs\":45\n  \"Cats\":30", "--output pie.png");
+```
+
+---
+
+### `mermaid_index_generate`
+
+Generate Mermaid diagrams from content sources (Confluence or Jira) based on include/exclude patterns. Processes content recursively and stores diagrams in hierarchical file structure.
+
+**Parameters:**
+
+- **`integration`** (string) 🔴 Required
+  - Integration type: 'confluence', 'jira', or 'jira_xray'
+  - Example: `confluence`
+
+- **`include_patterns`** (array) 🔴 Required
+  - Array of include patterns. For Confluence: ["SPACE/pages/PAGE_ID/PAGE_NAME/**"]. For Jira: ["JQL query"]
+  - Example: `["YOUR_SPACE/pages/PAGE_ID/Templates/**"]`
+
+- **`exclude_patterns`** (array) ⚪ Optional
+  - Optional array of exclude patterns to filter out specific content (not used for Jira)
+  - Example: `[]`
+
+- **`storage_path`** (string) 🔴 Required
+  - Base path for storing generated diagrams
+  - Example: `./mermaid-diagrams`
+
+- **`custom_fields`** (array) ⚪ Optional
+  - Optional array of custom field names to include in content (only for Jira integrations)
+  - Example: `["summary", "description", "customfield_10001"]`
+
+- **`include_comments`** (boolean) ⚪ Optional
+  - Whether to include comments in content (only for Jira integrations, default: false)
+  - Example: `false`
+
+**Example:**
+```bash
+dmtools mermaid_index_generate "confluence" '["MYSPACE/pages/123/Templates/**"]' --storage_path ./diagrams
+```
+
+```javascript
+const result = mermaid_index_generate("integration", "include_patterns");
+```
+
+---
+
+### `mermaid_index_read`
+
+Read all Mermaid diagram files (.mmd) from storage path recursively. Returns list of diagrams with their paths and content.
+
+**Parameters:**
+
+- **`integration`** (string) 🔴 Required
+  - Integration type (currently only 'confluence' is supported)
+  - Example: `confluence`
+
+- **`storage_path`** (string) 🔴 Required
+  - Base path where diagrams are stored
+  - Example: `./mermaid-diagrams`
+
+**Example:**
+```bash
+dmtools mermaid_index_read "confluence" "./mermaid-diagrams"
+```
+
+---
+
+### `mermaid_index_read_list`
+
+Read all Mermaid diagram files (.mmd) from storage path recursively. Returns list of ToText objects with paths and content.
+
+**Parameters:**
+
+- **`integration`** (string) 🔴 Required
+  - Integration type (currently only 'confluence' is supported)
+  - Example: `confluence`
+
+- **`storage_path`** (string) 🔴 Required
+  - Base path where diagrams are stored
+  - Example: `./mermaid-diagrams`
+
+**Example:**
+```bash
+dmtools mermaid_index_read_list "confluence" "./mermaid-diagrams"
+```
+
+---
+
+
 **Total Tools**: 3
 
 ## Quick Reference

dmtools-core/build.gradle

@@ -104,6 +104,7 @@ dependencies {
 
     // MCP annotations from separate module
     api project(':dmtools-mcp-annotations')
+    api 'com.github.istin:dmtools-mermaid-renderer:0.1.0-SNAPSHOT'
 
     // MCP Tools annotation processor - now in separate module
     annotationProcessor project(':dmtools-annotation-processor')

dmtools-core/src/main/java/com/github/istin/dmtools/job/JobRunner.java

@@ -31,6 +31,7 @@
 import com.github.istin.dmtools.teammate.Teammate;
 import com.github.istin.dmtools.js.JSRunner;
 import com.github.istin.dmtools.kb.KBProcessingJob;
+import com.github.istin.dmtools.mermaid.MermaidRendererCli;
 import com.github.istin.dmtools.mcp.cli.McpCliHandler;
 
 import java.io.InputStream;
@@ -176,6 +177,10 @@ public static void main(String[] args) throws Exception {
                 System.out.println(result);
                 return;
             }
+            if ("mermaid_to_svg".equals(firstArg) || "mermaid_to_png".equals(firstArg)) {
+                System.out.println(MermaidRendererCli.execute(args));
+                return;
+            }
             if ("run".equals(firstArg)) {
                 // Handle new run command with file + optional encoded parameter
                 RunCommandProcessor processor = new RunCommandProcessor();
@@ -281,6 +286,8 @@ private static void printHelp() {
         System.out.println("  dmtools run <json-file>                # Execute job with JSON config file");
         System.out.println("  dmtools run <job-name> [--key value]   # Execute a registered job without a config file");
         System.out.println("  dmtools run <json-file> <encoded>      # Execute job with file + encoded overrides");
+        System.out.println("  dmtools mermaid_to_svg \"diagram\"       # Render Mermaid text to an SVG file");
+        System.out.println("  dmtools mermaid_to_png \"diagram\"       # Render Mermaid text to a PNG file");
         System.out.println("  dmtools <tool> [args...]              # Execute MCP tool with args");
         System.out.println("  dmtools <tool> --data '{\"json\"}'      # Execute with inline JSON");
         System.out.println("  dmtools <tool> --file params.json     # Execute with JSON file");
@@ -294,6 +301,8 @@ private static void printHelp() {
         System.out.println("  dmtools list");
         System.out.println("  dmtools run job-config.json");
         System.out.println("  dmtools run codegenerator --param1 test");
+        System.out.println("  dmtools mermaid_to_svg \"flowchart TD; A[Start] --> B[Done]\" --output diagram.svg");
+        System.out.println("  dmtools mermaid_to_png \"flowchart TD; A[Start] --> B[Done]\"");
         System.out.println("  dmtools run job-config.json \"eyJvdmVycmlkZSI6InZhbHVlIn0=\"  # base64 encoded");
         System.out.println("  dmtools run job-config.json \"%7B%22override%22%3A%22value%22%7D\"  # URL encoded");
         System.out.println("  dmtools jira_get_ticket DMC-479 summary,description");