dsh-mermaid-comm

Make the AI default to Mermaid diagrams in development conversations. Rendering is handled by dsh-mermaid; this plugin focuses on prompt guidance, syntax validation, and output safety.

Features

Capability	What it does
A. Behavior guidance	Injects a systemPrompt.section: architecture, data flow, sequence, state, and dependency topics default to Mermaid — diagram first, then a short explanation.
B. Syntax validation	Registers the mermaid_validate tool: dangerous-character scan first, then real parsing via the same-version mermaid-runtime shipped with dsh-mermaid.
C. Output gate	Listens for assistant message events; auto-fixes Unicode arrows / dangerous labels in Mermaid fences, and removes broken diagrams from the visible surface when they cannot be confirmed.
D. Mermaid Vault	Persists validated diagrams to <workspace>/.dsh/mermaid/ as versioned assets: <name>.mmd (current version) + <name>.history.md (evolution history) + INDEX.md. The index is injected into the system prompt so later conversations evolve existing diagrams instead of redrawing from scratch.

Mermaid Vault (diagram persistence)

New in 0.2.0. Diagrams worth keeping — architecture, data models, core flows — are saved to the vault as a same-topic versioned series:

<workspace>/.dsh/mermaid/
├── INDEX.md                 # vault index (topic/type/version/updatedAt)
├── payment-flow.mmd         # current active version (always renderable)
└── payment-flow.history.md  # v1/v2/... with per-version change notes

Four model-visible tools:

• mermaid_vault_list — list the vault index (optional type filter)
• mermaid_vault_read — read a topic: current code + evolution history
• mermaid_vault_save — save/update a diagram (forced real-parser validation; syntax errors are rejected, so the vault only ever holds renderable diagrams)
• mermaid_vault_delete — delete a topic (main file + history + index entry)

The vault index is injected into the system prompt (lightweight table only — diagram contents are read on demand via mermaid_vault_read). When a topic already exists, the model is guided to read its history and evolve it with save (creating v2/v3/...) rather than redrawing from zero — that is how later conversations see the diagram's continuous change and stay consistent with earlier work.

Safety: topic names are sanitized to [a-zA-Z0-9-_] (no path traversal), writes are locked inside the vault directory, files are written atomically, and size/version limits prevent unbounded growth.

Installation

dsh plugin --profile web add dsh-mermaid-comm
# also install dsh-mermaid (handles chat rendering)
dsh plugin --profile web add dsh-mermaid

Restart dsh web. If dsh-mermaid is not installed or its runtime is unavailable, mermaid_validate fails explicitly instead of reporting unvalidated diagrams as passing; the output gate never silently lets a broken diagram through.

Usage

The model defaults to Mermaid output for:

• Architecture / module relationships → flowchart or classDiagram
• Call chains / request sequences → sequenceDiagram
• State / lifecycle → stateDiagram-v2
• Data models / table relationships → erDiagram
• Branching strategy / Git history → gitGraph
• Plans / schedules → gantt

Validation rules

mermaid_validate returns:

• ok: whether the current code passes;
• built: the code after rule-based fixes;
• fixes: the fixes applied;
• errors: dangerous characters, missing runtime, or parse errors;
• mode: "true-runtime": mode marker for backward compatibility with older callers.

The output gate supports both ```mermaid and ```mermaidd fences. Each broken block is independently re-evaluated; a fixed version that passes the same runtime parser replaces the original block, and blocks that still fail are replaced with a safe notice instead of being handed to the renderer.

Safety boundary

• Unicode arrows, unpaired quotes, and subgraph special characters are scanned/fixed first;
• Real parsing uses dsh-mermaid's lib/mermaid-runtime.js directly — no reliance on the error-prone .hash field;
• Original events stay in the transcript; the fixed version overrides the visible message via a surface replace;
• The output gate only handles assistant/message append events and uses a gateFixed marker to prevent reprocessing.

Development

pnpm install
pnpm --filter dsh-mermaid-comm build
pnpm --filter dsh-mermaid-comm typecheck

Install from a checkout:

dsh plugin --profile web add file:/path/to/packages/dsh-mermaid-comm

License

MIT