cokit-cli 1.0.9 → 1.2.2

package/skills/mermaidjs-v11/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: mermaidjs-v11
+description: Create diagrams with Mermaid.js v11 syntax. Use for flowcharts, sequence diagrams, class diagrams, ER diagrams, Gantt charts, state diagrams, architecture diagrams, timelines, user journeys.
+---
+
+# Mermaid.js v11
+
+## Overview
+
+Create text-based diagrams using Mermaid.js v11 declarative syntax. Convert code to SVG/PNG/PDF via CLI or render in browsers/markdown files.
+
+## Quick Start
+
+**Basic Diagram Structure:**
+```
+{diagram-type}
+  {diagram-content}
+```
+
+**Common Diagram Types:**
+- `flowchart` - Process flows, decision trees
+- `sequenceDiagram` - Actor interactions, API flows
+- `classDiagram` - OOP structures, data models
+- `stateDiagram` - State machines, workflows
+- `erDiagram` - Database relationships
+- `gantt` - Project timelines
+- `journey` - User experience flows
+
+See `references/diagram-types.md` for all 24+ types with syntax.
+
+## Creating Diagrams
+
+**Inline Markdown Code Blocks:**
+````markdown
+```mermaid
+flowchart TD
+    A[Start] --> B{Decision}
+    B -->|Yes| C[Action]
+    B -->|No| D[End]
+```
+````
+
+**Configuration via Frontmatter:**
+````markdown
+```mermaid
+---
+theme: dark
+---
+flowchart LR
+    A --> B
+```
+````
+
+**Comments:** Use `%% ` prefix for single-line comments.
+
+## CLI Usage
+
+Convert `.mmd` files to images:
+```bash
+# Installation
+npm install -g @mermaid-js/mermaid-cli
+
+# Basic conversion
+mmdc -i diagram.mmd -o diagram.svg
+
+# With theme and background
+mmdc -i input.mmd -o output.png -t dark -b transparent
+
+# Custom styling
+mmdc -i diagram.mmd --cssFile style.css -o output.svg
+```
+
+See `references/cli-usage.md` for Docker, batch processing, and advanced workflows.
+
+## JavaScript Integration
+
+**HTML Embedding:**
+```html
+<pre class="mermaid">
+  flowchart TD
+    A[Client] --> B[Server]
+</pre>
+<script src="https://cdn.jsdelivr.net/npm/mermaid@latest/dist/mermaid.min.js"></script>
+<script>mermaid.initialize({ startOnLoad: true });</script>
+```
+
+See `references/integration.md` for Node.js API and advanced integration patterns.
+
+## Configuration & Theming
+
+**Common Options:**
+- `theme`: "default", "dark", "forest", "neutral", "base"
+- `look`: "classic", "handDrawn"
+- `fontFamily`: Custom font specification
+- `securityLevel`: "strict", "loose", "antiscript"
+
+See `references/configuration.md` for complete config options, theming, and customization.
+
+## Practical Patterns
+
+Load `references/examples.md` for:
+- Architecture diagrams
+- API documentation flows
+- Database schemas
+- Project timelines
+- State machines
+- User journey maps
+
+## Resources
+
+- `references/diagram-types.md` - Syntax for all 24+ diagram types
+- `references/configuration.md` - Config, theming, accessibility
+- `references/cli-usage.md` - CLI commands and workflows
+- `references/integration.md` - JavaScript API and embedding
+- `references/examples.md` - Practical patterns and use cases

package/skills/mermaidjs-v11/references/cli-usage.md

@@ -0,0 +1,228 @@
+# Mermaid.js CLI Usage
+
+Command-line interface for converting Mermaid diagrams to SVG/PNG/PDF.
+
+## Installation
+
+**Global Install:**
+```bash
+npm install -g @mermaid-js/mermaid-cli
+```
+
+**Local Install:**
+```bash
+npm install @mermaid-js/mermaid-cli
+./node_modules/.bin/mmdc -h
+```
+
+**No Install (npx):**
+```bash
+npx -p @mermaid-js/mermaid-cli mmdc -h
+```
+
+**Docker:**
+```bash
+docker pull ghcr.io/mermaid-js/mermaid-cli/mermaid-cli
+```
+
+**Requirements:** Node.js ^18.19 || >=20.0
+
+## Basic Commands
+
+**Convert to SVG:**
+```bash
+mmdc -i input.mmd -o output.svg
+```
+
+**Convert to PNG:**
+```bash
+mmdc -i input.mmd -o output.png
+```
+
+**Convert to PDF:**
+```bash
+mmdc -i input.mmd -o output.pdf
+```
+
+Output format determined by file extension.
+
+## CLI Flags
+
+**Core Options:**
+- `-i, --input <file>` - Input file (use `-` for stdin)
+- `-o, --output <file>` - Output file path
+- `-t, --theme <name>` - Theme: default, dark, forest, neutral
+- `-b, --background <color>` - Background: transparent, white, #hex
+- `--cssFile <file>` - Custom CSS for styling
+- `--configFile <file>` - Mermaid configuration file
+- `-h, --help` - Show all options
+
+**Example with All Options:**
+```bash
+mmdc -i diagram.mmd -o output.png \
+  -t dark \
+  -b transparent \
+  --cssFile custom.css \
+  --configFile mermaid-config.json
+```
+
+## Advanced Usage
+
+**Stdin Piping:**
+```bash
+cat diagram.mmd | mmdc --input - -o output.svg
+
+# Or inline
+cat << EOF | mmdc --input - -o output.svg
+graph TD
+  A[Start] --> B[End]
+EOF
+```
+
+**Batch Processing:**
+```bash
+for file in *.mmd; do
+  mmdc -i "$file" -o "${file%.mmd}.svg"
+done
+```
+
+**Markdown Files:**
+Process markdown with embedded diagrams:
+```bash
+mmdc -i README.template.md -o README.md
+```
+
+## Docker Workflows
+
+**Basic Docker Usage:**
+```bash
+docker run --rm \
+  -u $(id -u):$(id -g) \
+  -v /path/to/diagrams:/data \
+  ghcr.io/mermaid-js/mermaid-cli/mermaid-cli \
+  -i diagram.mmd -o output.svg
+```
+
+**Mount Working Directory:**
+```bash
+docker run --rm -v $(pwd):/data \
+  ghcr.io/mermaid-js/mermaid-cli/mermaid-cli \
+  -i /data/input.mmd -o /data/output.png
+```
+
+**Podman (with SELinux):**
+```bash
+podman run --userns keep-id --user ${UID} \
+  --rm -v /path/to/diagrams:/data:z \
+  ghcr.io/mermaid-js/mermaid-cli/mermaid-cli \
+  -i diagram.mmd
+```
+
+## Configuration Files
+
+**Mermaid Config (JSON):**
+```json
+{
+  "theme": "dark",
+  "look": "handDrawn",
+  "fontFamily": "Arial",
+  "flowchart": {
+    "curve": "basis"
+  }
+}
+```
+
+**Usage:**
+```bash
+mmdc -i input.mmd --configFile config.json -o output.svg
+```
+
+**Custom CSS:**
+```css
+.node rect {
+  fill: #f9f;
+  stroke: #333;
+}
+.edgeLabel {
+  background-color: white;
+}
+```
+
+**Usage:**
+```bash
+mmdc -i input.mmd --cssFile styles.css -o output.svg
+```
+
+## Node.js API
+
+**Programmatic Usage:**
+```javascript
+import { run } from '@mermaid-js/mermaid-cli';
+
+await run('input.mmd', 'output.svg', {
+  theme: 'dark',
+  backgroundColor: 'transparent'
+});
+```
+
+**With Options:**
+```javascript
+import { run } from '@mermaid-js/mermaid-cli';
+
+await run('diagram.mmd', 'output.png', {
+  theme: 'forest',
+  backgroundColor: '#ffffff',
+  cssFile: 'custom.css',
+  configFile: 'config.json'
+});
+```
+
+## Common Workflows
+
+**Documentation Generation:**
+```bash
+# Convert all diagrams in docs/
+find docs/ -name "*.mmd" -exec sh -c \
+  'mmdc -i "$1" -o "${1%.mmd}.svg"' _ {} \;
+```
+
+**Styled Output:**
+```bash
+# Create dark-themed transparent diagrams
+mmdc -i architecture.mmd -o arch.png \
+  -t dark \
+  -b transparent \
+  --cssFile animations.css
+```
+
+**CI/CD Pipeline:**
+```yaml
+# GitHub Actions example
+- name: Generate Diagrams
+  run: |
+    npm install -g @mermaid-js/mermaid-cli
+    mmdc -i docs/diagram.mmd -o docs/diagram.svg
+```
+
+**Accessibility-Enhanced:**
+```bash
+# Diagrams with accTitle/accDescr preserved
+mmdc -i accessible-diagram.mmd -o output.svg
+```
+
+## Troubleshooting
+
+**Permission Issues (Docker):**
+Use `-u $(id -u):$(id -g)` to match host user permissions.
+
+**Large Diagrams:**
+Increase Node.js memory:
+```bash
+NODE_OPTIONS="--max-old-space-size=4096" mmdc -i large.mmd -o out.svg
+```
+
+**Validation:**
+Check syntax before rendering:
+```bash
+mmdc -i diagram.mmd -o /dev/null || echo "Invalid syntax"
+```

package/skills/mermaidjs-v11/references/configuration.md

@@ -0,0 +1,232 @@
+# Mermaid.js Configuration & Theming
+
+Configuration options, theming, and customization for Mermaid.js v11.
+
+## Configuration Methods
+
+**1. Site-wide Initialization:**
+```javascript
+mermaid.initialize({
+  theme: 'dark',
+  startOnLoad: true,
+  securityLevel: 'strict',
+  fontFamily: 'Arial'
+});
+```
+
+**2. Diagram-level Frontmatter:**
+````markdown
+```mermaid
+---
+theme: forest
+look: handDrawn
+---
+flowchart TD
+  A --> B
+```
+````
+
+**3. Configuration Hierarchy:**
+Default config → Site config → Diagram config (highest priority)
+
+## Core Options
+
+**Rendering:**
+- `startOnLoad`: Auto-render on page load (default: true)
+- `securityLevel`: "strict" (default), "loose", "antiscript", "sandbox"
+- `deterministicIds`: Reproducible SVG IDs (default: false)
+- `maxTextSize`: Max diagram text (default: 50000)
+- `maxEdges`: Max drawable edges (default: 500)
+
+**Visual Style:**
+- `look`: "classic" (default), "handDrawn"
+- `handDrawnSeed`: Numeric seed for hand-drawn consistency
+- `darkMode`: Boolean toggle
+
+**Typography:**
+- `fontFamily`: "trebuchet ms, verdana, arial, sans-serif" (default)
+- `fontSize`: Base text size (default: 16)
+
+**Layout:**
+- `layout`: "dagre" (default), "elk", "tidy-tree", "cose-bilkent"
+
+**Debug:**
+- `logLevel`: 0-5 from trace to fatal
+- `htmlLabels`: Enable HTML in labels (default: false)
+
+## Theming
+
+**Built-in Themes:**
+- `default` - Standard colors
+- `dark` - Dark background
+- `forest` - Green tones
+- `neutral` - Grayscale
+- `base` - Fully customizable
+
+**Theme Variables (base theme only):**
+```javascript
+mermaid.initialize({
+  theme: 'base',
+  themeVariables: {
+    primaryColor: '#ff0000',
+    primaryTextColor: '#fff',
+    primaryBorderColor: '#7C0000',
+    secondaryColor: '#006100',
+    tertiaryColor: '#fff'
+  }
+});
+```
+
+**Customizable Variables:**
+- Color families: primary, secondary, tertiary
+- Node backgrounds and text colors
+- Border and line colors
+- Note background/text
+- Diagram-specific (flowchart nodes, sequence actors, pie sections)
+
+**Custom CSS:**
+```javascript
+mermaid.initialize({
+  themeCSS: `
+    .node rect { fill: #f9f; }
+    .edgeLabel { background-color: white; }
+  `
+});
+```
+
+## Accessibility
+
+**ARIA Support:**
+```
+accTitle: Diagram Title
+accDescr: Brief description
+accDescr {
+  Multi-line detailed
+  description
+}
+```
+
+**Auto-generated:**
+- `aria-roledescription` attributes
+- `<title>` and `<desc>` SVG elements
+- `aria-labelledby` and `aria-describedby`
+
+**WCAG Compliance:**
+Available for all diagram types (flowchart, sequence, class, Gantt, etc.)
+
+## Icon Configuration
+
+**Register Icon Packs:**
+```javascript
+import { registerIconPacks } from 'mermaid';
+registerIconPacks([
+  {
+    name: 'logos',
+    loader: () => import('https://esm.run/@iconify-json/logos')
+  }
+]);
+```
+
+**Usage:**
+```
+architecture-beta
+  service api(logos:nodejs)[API]
+```
+
+**Loading Methods:**
+1. CDN-based (lazy loading)
+2. npm with dynamic import
+3. Direct import
+
+## Math Rendering
+
+**KaTeX Support:**
+```
+graph LR
+  A["$$f(x) = x^2$$"] --> B
+```
+
+**Configuration:**
+- `legacyMathML`: Use old MathML rendering
+- `forceLegacyMathML`: Force legacy even if browser supports native
+
+## Security
+
+**Security Levels:**
+- `strict` - HTML encoding (default, recommended)
+- `loose` - Some HTML allowed
+- `antiscript` - Filter scripts
+- `sandbox` - Sandboxed mode
+
+**DOMPurify:**
+Enabled by default for XSS protection. Customize via `dompurifyConfig` (use caution).
+
+## Layout Algorithms
+
+**dagre (default):**
+Standard hierarchical layout for most diagrams.
+
+**elk:**
+Advanced layout with better handling of complex graphs.
+
+**tidy-tree:**
+Clean tree structures for hierarchies.
+
+**cose-bilkent:**
+Compound graph layout for nested structures.
+
+**Per-diagram Configuration:**
+````markdown
+```mermaid
+---
+layout: elk
+---
+flowchart TD
+  A --> B
+```
+````
+
+## Common Patterns
+
+**Consistent Hand-drawn Style:**
+```javascript
+mermaid.initialize({
+  look: 'handDrawn',
+  handDrawnSeed: 42  // Same seed = consistent appearance
+});
+```
+
+**Dark Mode Toggle:**
+```javascript
+const isDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
+mermaid.initialize({
+  theme: isDark ? 'dark' : 'default'
+});
+```
+
+**Performance Optimization:**
+```javascript
+mermaid.initialize({
+  startOnLoad: false,  // Manual rendering
+  maxEdges: 1000,       // Increase for complex graphs
+  deterministicIds: true  // Caching-friendly
+});
+```
+
+## Validation
+
+**Parse without Rendering:**
+```javascript
+try {
+  await mermaid.parse('graph TD\nA-->B');
+  console.log('Valid syntax');
+} catch(e) {
+  console.error('Invalid:', e);
+}
+```
+
+**Programmatic Rendering:**
+```javascript
+const { svg } = await mermaid.render('graphId', 'graph TD\nA-->B');
+document.getElementById('output').innerHTML = svg;
+```