diff --git a/.agents/plugins/marketplace.json b/.agents/plugins/marketplace.json new file mode 100644 index 0000000..bb360d8 --- /dev/null +++ b/.agents/plugins/marketplace.json @@ -0,0 +1,30 @@ +{ + "name": "visualcave", + "interface": { + "displayName": "VisualCave" + }, + "metadata": { + "description": "Interactive diagram generator — flowcharts, sequence, ER, class, state machines, mind maps", + "version": "1.0.0" + }, + "plugins": [ + { + "name": "visualcave", + "source": { + "source": "local", + "path": "." + }, + "policy": { + "installation": "AVAILABLE", + "authentication": "NONE" + }, + "category": "Developer Tools", + "interface": { + "displayName": "VisualCave", + "shortDescription": "Interactive diagram generator — flowcharts, sequence, ER, class, state machines, mind maps", + "developerName": "varkart", + "websiteURL": "https://varkart.github.io/visualcave" + } + } + ] +} diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index e27a36e..9bc5a3b 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -1,21 +1,32 @@ { "name": "visualcave", - "title": "VisualCave — Technical Diagrams", - "description": "Generate interactive, publication-quality technical diagrams as standalone HTML files. Powered by Mermaid.js — supports 11 diagram types including flowcharts, sequence diagrams, ER diagrams, class diagrams, git graphs, mind maps, and more.\n\nFeatures: dark/light mode toggle, step-through reveal for walkthroughs, hover highlight, and export to PNG/SVG/PDF/GIF via capture.js.", - "version": "1.0.0", - "category": "visualization", - "keywords": [ - "diagram", - "mermaid", - "infographic", - "flowchart", - "architecture", - "ER diagram", - "sequence diagram", - "visualization" - ], - "author": "varkart", - "repository": "https://github.com/varkart/visualcave", - "homepage": "https://varkart.github.io/visualcave", - "license": "MIT" + "id": "visualcave", + "owner": { + "name": "varkart" + }, + "metadata": { + "description": "Interactive diagram generator — flowcharts, sequence, ER, class, state machines, mind maps", + "version": "1.0.0", + "category": "Developer Tools" + }, + "plugins": [ + { + "name": "visualcave", + "source": "./", + "description": "Design and render interactive technical diagrams as standalone HTML files. Powered by Mermaid.js with dark mode, four theme presets, step-through reveal, hover highlighting, and one-click SVG/PNG/PDF export. Zero runtime dependencies.", + "version": "1.0.0", + "author": { + "name": "varkart" + }, + "keywords": [ + "diagram", + "mermaid", + "flowchart", + "architecture", + "visualization", + "interactive" + ], + "category": "Developer Tools" + } + ] } diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 258b048..4b5304e 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,23 +1,24 @@ { "name": "visualcave", - "description": "Generate interactive technical diagrams as standalone HTML files. Powered by Mermaid.js. Supports flowcharts, sequence diagrams, ER diagrams, class diagrams, state machines, timelines, mind maps, git graphs, pie charts, and quadrant charts. Dark mode, step-through reveal, and export built in.", + "description": "Design and render interactive technical diagrams as standalone HTML files or embeddable Astro/MDX components. Supports 11 Mermaid diagram types with dark mode, step-through reveal, hover highlighting, and one-click SVG/PNG/PDF export.", "version": "1.0.0", + "author": { + "name": "varkart", + "url": "https://github.com/varkart" + }, + "homepage": "https://varkart.github.io/visualcave", + "repository": "https://github.com/varkart/visualcave", + "license": "MIT", "keywords": [ "diagram", "mermaid", - "infographic", "flowchart", "architecture", - "technical-diagram", - "visualization" + "visualization", + "interactive", + "dark-mode", + "svg", + "export" ], - "skills": ["./"], - "interface": { - "defaultPrompt": [ - "/visualcave — how OAuth 2.0 works", - "/visualcave — transformer architecture with step-through guide", - "/visualcave — order lifecycle state machine", - "/visualcave — microservices architecture overview" - ] - } + "skills": ["."] } diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json index 9319627..376c070 100644 --- a/.codex-plugin/plugin.json +++ b/.codex-plugin/plugin.json @@ -1,25 +1,47 @@ { "name": "visualcave", - "description": "Generate interactive technical diagrams as standalone HTML files. Powered by Mermaid.js. Supports flowcharts, sequence diagrams, ER diagrams, class diagrams, state machines, timelines, mind maps, git graphs, pie charts, and quadrant charts. Dark mode, step-through reveal, and export built in.", "version": "1.0.0", + "description": "Design and render interactive technical diagrams as standalone HTML files or embeddable Astro/MDX components. Supports 11 Mermaid diagram types with dark mode, step-through reveal, hover highlighting, and one-click SVG/PNG/PDF export.", + "author": { + "name": "varkart", + "url": "https://github.com/varkart" + }, + "homepage": "https://varkart.github.io/visualcave", + "repository": "https://github.com/varkart/visualcave", + "license": "MIT", "keywords": [ "diagram", "mermaid", - "infographic", "flowchart", "architecture", - "technical-diagram", - "visualization" + "visualization", + "svg", + "infographic", + "sequence-diagram", + "er-diagram", + "class-diagram", + "state-machine", + "interactive", + "dark-mode", + "export" ], - "skills": ["./"], + "skills": "./", "interface": { - "capabilities": ["diagram-generation", "visualization", "technical-illustration"], - "brandColor": "#1E88E5", + "displayName": "VisualCave", + "shortDescription": "Interactive diagram generator for AI agents", + "longDescription": "Use VisualCave to design and render interactive technical diagrams as standalone HTML files. Supports flowcharts, sequence diagrams, ER diagrams, class diagrams, state machines, timelines, mind maps, git graphs, pie charts, and quadrant charts — all with dark mode, four theme presets, step-through reveal, hover highlighting, and one-click SVG/PNG/PDF export. Zero runtime dependencies.", + "developerName": "varkart", + "category": "Developer Tools", + "capabilities": ["Interactive", "Write"], + "websiteURL": "https://varkart.github.io/visualcave", + "privacyPolicyURL": "https://github.com/varkart/visualcave/blob/main/SECURITY.md", + "termsOfServiceURL": "https://github.com/varkart/visualcave/blob/main/LICENSE", "defaultPrompt": [ "Create a diagram showing how OAuth 2.0 works", "Draw a transformer architecture with step-through guide", - "Make an order lifecycle state machine", - "Visualize a microservices architecture" - ] + "Visualize a RAG pipeline from ingestion to grounded response", + "Make an order lifecycle state machine with all edge cases" + ], + "brandColor": "#1E88E5" } } diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 77d2676..4e61308 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -71,6 +71,17 @@ jobs: - name: npm audit (high + critical only) run: npm audit --audit-level=high --legacy-peer-deps + secret-scan: + name: Secret scan + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + - uses: gitleaks/gitleaks-action@v2 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + validate: name: Playwright — validate all examples render runs-on: ubuntu-latest diff --git a/.kiro/steering/visualcave.md b/.kiro/steering/visualcave.md new file mode 100644 index 0000000..34e4e87 --- /dev/null +++ b/.kiro/steering/visualcave.md @@ -0,0 +1,31 @@ +# VisualCave + +Trigger: use when the user asks to create a diagram, chart, infographic, flowchart, architecture illustration, or any technical visualization. Covers flowcharts, sequence diagrams, ER diagrams, class diagrams, state machines, timelines, mind maps, git graphs, pie charts, and quadrant charts. + +Output a **single self-contained `.html` file**. No markdown wrapper unless the user asks. + +**Style rules:** + +- Thick strokes (2px), 4px drop shadow, rounded nodes. +- Warm/cool subgraph alternation: yellow → blue → green → purple → teal → orange. +- Inter font for UI; JetBrains Mono for code/math labels. +- Pick the right Mermaid keyword for the diagram type. + +## Diagram Type Quick Reference + +| User says… | Use | +| ---------------------------------- | ----------------------- | +| flow, pipeline, architecture | `graph TD` / `graph LR` | +| sequence, API calls, who calls who | `sequenceDiagram` | +| class, OOP, domain model | `classDiagram` | +| state, lifecycle, FSM | `stateDiagram-v2` | +| database, schema, ER | `erDiagram` | +| priority matrix, 2×2 | `quadrantChart` | +| timeline, history, milestones | `timeline` | +| mind map, brainstorm | `mindmap` | +| git branching, gitflow | `gitGraph` | +| pie chart, distribution | `pie` | + +## HTML Template + +See full template and color reference at: https://github.com/varkart/visualcave/blob/main/SKILL.md diff --git a/POWER.md b/POWER.md new file mode 100644 index 0000000..6ea4660 --- /dev/null +++ b/POWER.md @@ -0,0 +1,43 @@ +--- +name: visualcave +description: Generate interactive Mermaid diagrams as self-contained HTML files with dark mode, step-through reveal, hover highlighting, and one-click SVG/PNG/PDF export +keywords: + - diagram + - flowchart + - mermaid + - architecture diagram + - sequence diagram + - ER diagram + - class diagram + - state machine + - timeline + - mind map + - git graph + - infographic + - visualization + - chart + - technical illustration +--- + +# VisualCave + +Output a **single self-contained `.html` file**. No markdown wrapper unless asked. + +Invoke with `/visualcave` or when the user asks to create a diagram, chart, flowchart, architecture illustration, or any technical visualization. + +Full instructions and HTML template: see `SKILL.md` in this directory, or at https://github.com/varkart/visualcave/blob/main/SKILL.md + +## Diagram Type Quick Reference + +| User says… | Mermaid keyword | +| ---------------------------------- | ----------------------- | +| flow, pipeline, architecture | `graph TD` / `graph LR` | +| sequence, API calls, actors | `sequenceDiagram` | +| class, OOP, domain model | `classDiagram` | +| state, lifecycle, FSM | `stateDiagram-v2` | +| database, schema, ER | `erDiagram` | +| priority matrix, 2×2 | `quadrantChart` | +| timeline, history, milestones | `timeline` | +| mind map, brainstorm | `mindmap` | +| git branching, gitflow | `gitGraph` | +| pie chart, distribution | `pie` | diff --git a/README.md b/README.md index 6e72986..21a2eae 100644 --- a/README.md +++ b/README.md @@ -33,13 +33,63 @@ git clone https://github.com/varkart/visualcave ~/.claude/skills/visualcave git clone https://github.com/varkart/visualcave .claude/skills/visualcave ``` -**Cursor** — copy `.cursor/rules/visualcave.mdc` into your project's `.cursor/rules/` directory. +**Cursor — global skill** -**Codex CLI** — install via `.codex-plugin/plugin.json` or clone and reference the skill directory. +```bash +git clone https://github.com/varkart/visualcave ~/.cursor/skills-cursor/visualcave +``` + +**Cursor — project rules only** + +Copy `.cursor/rules/visualcave.mdc` into your project's `.cursor/rules/` directory. + +**Codex CLI — skill (git)** + +```bash +git clone https://github.com/varkart/visualcave ~/.codex/skills/visualcave +``` + +**Codex CLI — plugin (marketplace)** + +```bash +codex plugin marketplace add varkart/visualcave +codex plugin add visualcave +``` + +**Gemini CLI — extension (git)** + +```bash +git clone https://github.com/varkart/visualcave ~/.gemini/extensions/visualcave +``` + +**Gemini CLI — extension (install command)** + +```bash +gemini extensions install https://github.com/varkart/visualcave +``` + +**Google Antigravity CLI (`agy`) — skill (git)** + +```bash +git clone https://github.com/varkart/visualcave ~/.gemini/antigravity-cli/skills/visualcave +``` + +**Google Antigravity CLI (`agy`) — plugin (git)** + +```bash +git clone https://github.com/varkart/visualcave ~/.gemini/antigravity-cli/plugins/visualcave +agy plugin install ~/.gemini/antigravity-cli/plugins/visualcave +``` + +**Kiro — skill (git)** + +```bash +git clone https://github.com/varkart/visualcave ~/.kiro/skills/visualcave +``` -**Gemini CLI** — clone the repo; Gemini CLI will pick up `gemini-extension.json` automatically and load `SKILL.md` as context. +**Kiro — Power** -**Kiro** — copy `.kiro/skills/visualcave.md` into your project's `.kiro/skills/` directory. (See [issue #7](https://github.com/varkart/visualcave/issues/7) — in progress) +Add as a Power in Kiro settings using the GitHub URL `https://github.com/varkart/visualcave`. For project-level steering, copy `.kiro/steering/visualcave.md` into your project's `.kiro/steering/` directory. No restart required after installation. diff --git a/SECURITY.md b/SECURITY.md index 433952a..9022c7b 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -10,7 +10,7 @@ Found a security issue? **Do not open a public GitHub issue.** -Email: https://github.com/varkart/visualcave/issues/new +Open a confidential issue: https://github.com/varkart/visualcave/issues/new Include: diff --git a/agents/openai.yaml b/agents/openai.yaml new file mode 100644 index 0000000..e2badc2 --- /dev/null +++ b/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "VisualCave" + short_description: "Interactive diagram generator — flowcharts, sequence, ER, class, state machines, mind maps" + default_prompt: "Use $visualcave to design and render an interactive technical diagram as a standalone HTML file with dark mode, step-through reveal, and one-click export." diff --git a/plugin.json b/plugin.json new file mode 100644 index 0000000..1d008ec --- /dev/null +++ b/plugin.json @@ -0,0 +1,12 @@ +{ + "name": "visualcave", + "version": "1.0.0", + "description": "Design and render interactive technical diagrams as standalone HTML files or embeddable Astro/MDX components. Supports 11 Mermaid diagram types with dark mode, step-through reveal, hover highlighting, and one-click SVG/PNG/PDF export.", + "author": { + "name": "varkart", + "url": "https://github.com/varkart" + }, + "license": "MIT", + "homepage": "https://varkart.github.io/visualcave", + "repository": "https://github.com/varkart/visualcave" +} diff --git a/skills/visualcave/SKILL.md b/skills/visualcave/SKILL.md new file mode 100644 index 0000000..bc0d52a --- /dev/null +++ b/skills/visualcave/SKILL.md @@ -0,0 +1,92 @@ +--- +name: visualcave +description: Use when the user asks to create a diagram, chart, infographic, flowchart, architecture illustration, or any technical visualization. Covers flowcharts, sequence diagrams, ER diagrams, class diagrams, state machines, timelines, mind maps, git graphs, pie charts, and quadrant charts. +license: MIT +--- + +# VisualCave + +Output a **single self-contained `.html` file**. No markdown wrapper unless the user asks for it. + +## Before You Draw + +**1. Identify the critical path.** Every good diagram has one story — the single flow or relationship the viewer must understand immediately. Name it before writing any Mermaid code. Let it govern which nodes exist and how subgraphs are grouped. Nodes that don't serve the story get cut. + +**2. Pick scope ruthlessly.** Aim for 8–15 nodes. Beyond 20 the diagram becomes unreadable. Group related details into a single labeled node rather than expanding every sub-step. + +**3. Choose labels like a senior engineer preparing a conference slide** — not an autogenerated dump. Node labels: 2–4 words. Edge labels: 1–3 words. Subgraph titles: a noun phrase, not a sentence. + +**Style rules:** + +- Thick strokes (2px), 4px drop shadow, rounded nodes. +- Warm/cool subgraph alternation: yellow → blue → green → purple → teal → orange. +- Inter font for UI; JetBrains Mono for code/math labels. +- Pick the right Mermaid keyword — see `references/diagram-types.md`. + +## HTML Template + +Read `references/template.html` verbatim. Replace: + +- `[Diagram Title]` and `[Subtitle]` in the header +- The placeholder Mermaid source inside `
` with the actual diagram + +Do not alter the CSS, THEMES object, or script block unless a specific feature requires it. + +## Colors + +`classDef` works in `graph`, `classDiagram`, `stateDiagram-v2`. For other types use `themeVariables`. + +| Class | Fill | Use for | +| ----------- | --------- | ----------------------------- | +| `:::yellow` | `#FFFDE7` | Users, browsers, entry points | +| `:::blue` | `#E3F2FD` | Services, APIs, compute | +| `:::green` | `#E8F5E9` | Databases, storage, success | +| `:::purple` | `#F3E5F5` | Auth, AI models, security | +| `:::teal` | `#E0F7FA` | Caching, CDN, external APIs | +| `:::orange` | `#FFF3E0` | Queues, events, pipelines | +| `:::note` | `#FFF9C4` | Annotations, callouts | + +## Interactive Features + +**Theme selector** — built into the template. Four themes: `default`, `minimal`, `pastel`, `print`. Persisted via `localStorage` key `vc-style`. No changes needed. + +**Step-through** (sequential reveal): copy `setupSteps()` pattern from `examples/transformer-ultra.html`. + +**Hover highlight**: add `data-node` / `data-connects` attributes post-render, include ``. + +**Export (in-page)**: every diagram has SVG, PNG, and PDF download buttons in the controls bar — no server or Node.js needed. SVG serializes the inline SVG with white background; PNG renders at 2x; PDF uses `window.print()` with controls hidden. + +**Export (CLI)**: `node capture.js file.html [--format=png|svg|pdf|og]` — for animated GIF, OG images, and headless batch export. + +**Brand theming**: see `references/theming.md`. + +**Animated diagrams**: see `references/animated.md`. + +**Animation Mode** — when user requests "animated", "living diagram", "canvas", "particles", "flowing edges", or "living visual": before generating, ask: + +> Which animation approach? +> +> 1. **CSS flow** — flowing edges + node glow on any Mermaid diagram. Zero extra deps. +> 2. **Canvas** — full custom animation (particles, physics, signal propagation). No Mermaid. Showpiece only. + +CSS flow: see `references/animated.md` § Mermaid CSS Flow. +Canvas: see `references/canvas-animation.md`. + +## Astro Component Mode (varkart.dev site) + +**Triggers**: "for the blog/site/article", "embed this", "Astro component", "MDX component" +Output a `.astro` file at `src/components/mdx/ComponentName.astro` (site: `github.com/varkart/personal-site`) instead of a standalone HTML file. +**For React/Next.js** ("React component", "TSX component"): output `.tsx` with inline SVG instead. +See `references/astro-component.md` for token tables, component template, badge palettes, dark-first CSS rule, Mermaid config, and React/TSX output. + +## Quality Pass + +After writing the Mermaid source, review before outputting the file: + +- [ ] Node count ≤ 20 (ideally ≤ 15). Merge or drop anything peripheral. +- [ ] Every node label ≤ 5 words. Abbreviate where meaning is preserved. +- [ ] No orphan nodes — every node connects to at least one edge. +- [ ] Subgraph nesting ≤ 3 levels deep. +- [ ] Color assignment is meaningful — same semantic color = same role category. +- [ ] The critical path is visually obvious top-to-bottom (or left-to-right). +- [ ] No redundant edges — if A→B→C and A→C both exist, the direct edge likely adds nothing.