jpmanson/pele-skill

Pele

Rendre du code source Mermaid en SVG avec Pele. Pele est une bibliothèque synchrone : pas de Puppeteer, pas de mermaid-cli, pas de serveur MCP. L'interface de cette compétence est scripts/render.mjs.

La racine de la compétence est le répertoire qui contient ce fichier. Chaque chemin ci-dessous est relatif à ce répertoire. Cela reste vrai après l'installation de la compétence dans Claude Code, Hermes ou OpenCode.

Quand utiliser

• L'utilisateur souhaite un diagramme Mermaid sous forme de fichier SVG, HTML ou image.
• Un fichier .mmd, ou une clôture ```mermaid, doit être rendu et vérifié.
• L'utilisateur demande un diagramme que l'un des 32 types pris en charge peut dessiner, et souhaite un fichier, pas une clôture de chat. Cela inclut les types moins courants : diagramme de Wardley, fishbone, Venn, swimlane, radar, treemap, sankey, grammaire ferroviaire, arborescence de fichiers, Cynefin, modèle d'événements. Voir la liste des types ci-dessous.

Ne pas utiliser lorsque :

• La clôture Mermaid doit rester en Markdown que GitHub, Obsidian ou un autre visualiseur rend déjà.
• L'artefact demandé n'est pas du Mermaid (JSON Excalidraw dessiné à la main, page d'architecture sur mesure, annotation de capture d'écran).
• L'utilisateur a besoin d'une sortie mermaid.js identique au pixel près. Pele a sa propre mise en page.

Ne pas encapsuler cela dans un serveur MCP. Un seul appel de script constitue l'ensemble de la fonctionnalité.

Prérequis

• Node.js 20 ou plus récent, et npm dans le PATH.
• L'installation des dépendances a lieu dans la racine de la compétence (package.json à côté de ce fichier), jamais dans le projet de l'utilisateur.

Si node_modules/pele est manquant, le script exécute npm install à cet endroit. Vous pouvez aussi le faire vous-même :

npm install --no-fund --no-audit

Vérification : node scripts/render.mjs --check se termine avec le code 0 et stderr contient du JSON avec "ok": true et une version de pele.

Types de diagrammes

Connaître la liste complète avant de choisir. Pele rend 32 types, et un tiers d'entre eux nécessitent un en-tête -beta qui diffère du nom que l'utilisateur dirait.

node scripts/render.mjs --types

Cela imprime du JSON : type, l'header exact de la première ligne, ce à quoi il sert, et un example fonctionnel. references/diagram-types.md contient le même tableau, les en-têtes qui échouent et comment choisir un type.

• Choisissez le type qui montre ce dont le lecteur a besoin, pas le premier qui vient à l'esprit. Propriétaires par étape → swimlane. Causes d'un problème → ishikawa. Tâches datées → gantt. Disposition des dossiers → treeView. Flux proportionnels → sankey.
• Si la demande ne correspond à aucun type (disposition libre, une image, un type de graphique non listé), dites-le et ne le forcez pas dans un organigramme.
• Si l'utilisateur nomme un type de diagramme spécifique qui n'est pas dans la liste, dites-le avant de proposer le type pris en charge le plus proche. Ne l'approchez pas silencieusement.

Procédure

1. Choisissez le type et son en-tête exact depuis --types. Pour tout type -beta, ou tout type dont vous n'êtes pas sûr de la syntaxe, lisez d'abord son fichier example et copiez sa structure.
2. Écrivez le code source Mermaid dans un fichier .mmd. Ne transmettez pas un diagramme multi-lignes comme argument de shell.
3. Rendez-le :

node scripts/render.mjs INPUT.mmd OUTPUT.svg

4. Lisez le reçu JSON sur stderr. La réussite est tout à la fois : code de sortie 0, "ok": true, le type du reçu est le type que vous avez choisi, et le fichier de sortie commence par <svg.
5. Si "ok": false :
   • unsupported-diagram : la première ligne n'est pas un en-tête connu. Utilisez suggest[0].header s'il est présent, sinon choisissez-en un depuis --types.
   • syntax ou semantic : corrigez la source à la line / column en utilisant snippet, comparez avec l'exemple du type, puis rendez à nouveau.
   • Ne passez pas à mermaid-cli, un navigateur sans tête ou un SVG écrit à la main.
6. Signalez le chemin absolu du fichier de sortie. Ne collez pas le SVG dans le chat sauf si l'utilisateur a demandé le balisage. Ne revendiquez pas le succès sur une sortie non nulle.

Utilisez --html, ou un chemin de sortie se terminant par .html, lorsque l'utilisateur a besoin d'un fichier qu'il peut ouvrir dans un navigateur. Le HTML intègre le SVG et définit les variables de couleur CSS de Pele.

node scripts/render.mjs --html INPUT.mmd OUTPUT.html

Reçu

Succès sur stderr :

{"ok":true,"type":"flowchart","width":180,"height":80,"bytes":1200,"output":"/abs/OUTPUT.svg","html":false,"pele":"1.6.0"}

Échec sur stderr, code de sortie 1 (code de sortie 2 si Pele n'a pas pu être installé) :

{"ok":false,"code":"syntax","message":"...","type":"flowchart","line":2,"column":5,"snippet":"..."}

code peut être syntax, semantic, unsupported-diagram, limit, usage, install-failed, ou render-failed. Affichez message sous forme de texte. Il peut contenir le code source du diagramme.

Un reçu unsupported-diagram contient également hint et suggest :

{"ok":false,"code":"unsupported-diagram","hint":"Remplacez la première ligne par l'en-tête ci-dessous. De nombreux types nécessitent le suffixe -beta.","suggest":[{"type":"radar","header":"radar-beta","example":"/abs/examples/types/radar.mmd"}]}

Drapeaux

Drapeau	Utilisation
--check	Charge Pele, affiche la version, ne rend pas
--types	Affiche les types pris en charge, les en-têtes et les chemins d'exemples sous forme de JSON sur stdout
--html	HTML autonome au lieu de SVG brut
--fixed	Taille en pixels fixe. Par défaut pour un fichier .svg
--responsive	Le SVG peut rétrécir pour s'adapter à son conteneur. Par défaut pour stdout et HTML
--max-width <px>	Demande à Pele d'adapter la mise en page. Peut faire basculer un large organigramme LR en dessous de 640px
--font-size <px>	Taille de police de base
--font <family>	Police des étiquettes
--id-prefix <str>	Préfixe unique lorsque plusieurs SVG partagent une page

Stdout reste le SVG (ou HTML). Le reçu est toujours la dernière ligne JSON sur stderr.

Une clôture ```mermaid environnante est supprimée. Le frontmatter propre à Mermaid ne l'est pas.

Pièges

• Le fichier SVG par défaut est responsive: false. Passez --responsive uniquement lorsque le SVG sera intégré et doit rétrécir.
• Node n'a pas de mesureur de toile. Les largeurs d'étiquettes peuvent différer d'un rendu de navigateur. C'est normal.
• Ne passez pas --max-width sauf si l'utilisateur a demandé une disposition étroite. Cela peut changer la direction.
• Les en-têtes sont exacts. radar, venn, wardley, swimlane, treeView, usecase, cynefin, railroad, agentflow nécessitent tous -beta ; architecture aussi. Il n'y a pas d'en-tête fishbone ; utilisez ishikawa-beta.
• Les noms d'icônes (fa:fa-user, icônes d'architecture autres que cloud, database, disk, internet, server) s'affichent comme un emplacement vide sans erreur. Ce script ne fournit pas de callback d'icône. Supprimez l'icône ou remplacez-la par du texte.
• La limite source est de 50 000 caractères. La limite de sortie est de 4 000 000. La limite d'arêtes d'organigramme est de 5 000.
• npm install dans le dépôt de l'utilisateur ne satisfera pas ce script. Le paquet se trouve dans la racine de la compétence.
• Si node_modules existe mais que Pele ne se charge pas, supprimez ce node_modules et exécutez npm install dans la racine de la compétence.
• Une session d'agent déjà ouverte ne verra pas une compétence installée en cours de session. C'est un cache de chargeur, pas une mauvaise installation.

Vérification

Depuis la racine de la compétence :

npm run smoke

Réussite : code de sortie 0, et stdout contient du JSON avec "ok": true, une version de pele, "types": 32, une liste rendered avec tous les types du catalogue, et une syntaxError avec code: "syntax" et un line non nul. Le test de fumée échoue également si scripts/catalog.mjs s'écarte de la liste des types de Pele, ou si un en-tête cesse de se détecter comme son type. examples/broken.mmd doit continuer à échouer. Une réussite du test de fumée ne signifie pas qu'un nouveau diagramme est correct ; chaque nouveau diagramme nécessite toujours son propre reçu.