diagrams-js 0.6.0 → 0.7.0

package/dist/index.d.ts

@@ -1593,4 +1593,4 @@ declare namespace index_d_exports {
   export { ChangeKind, Cluster, ClusterDiff, ClusterOptions, CreatePlugin, Custom, DependencyError, Diagram, DiagramClusterJSON, DiagramDiffResult, DiagramEdgeJSON, DiagramJSON, DiagramNodeJSON, DiagramOptions, DiagramsPlugin, DiffMeta, DiffOptions, DiffSummary, Edge, EdgeDiff, EdgeOptions, ExportContext, ExporterCapability, FromJSONOptions, HookCapability, HookContext, HookEvent, HookHandler, Iconify, ImportContext, ImporterCapability, MetadataCapability, MetadataContext, Node, NodeDiff, NodeMetadata, NodeOptions, PluginCapability, PluginContext, PluginError, PluginRegistry, ProviderModule, RenderContext, RenderDiffOptions, RendererCapability, RuntimeError, RuntimeSupport, ThemeConfig, ThemeName, Yaml, computeDiff, createJSONPlugin, createPluginRegistry, createSVGPlugin, jsonPlugin, renderDiff, svgPlugin };
 }
 //#endregion
-export { type ChangeKind, Cluster, type ClusterDiff, type ClusterOptions, type CreatePlugin, Custom, DependencyError, Diagram, type DiagramClusterJSON, type DiagramDiffResult, type DiagramEdgeJSON, type DiagramJSON, type DiagramNodeJSON, type DiagramOptions, type DiagramsPlugin, type DiffMeta, type DiffOptions, type DiffSummary, Edge, type EdgeDiff, type EdgeOptions, type ExportContext, type ExporterCapability, type FromJSONOptions, type HookCapability, type HookContext, HookEvent, type HookHandler, Iconify, type ImportContext, type ImporterCapability, type MetadataCapability, type MetadataContext, type Node, type NodeDiff, type NodeMetadata, type NodeOptions, type PluginCapability, type PluginContext, PluginError, type PluginRegistry, type ProviderModule, type RenderContext, type RenderDiffOptions, type RendererCapability, RuntimeError, type RuntimeSupport, type ThemeConfig, type ThemeName, type Yaml, computeDiff, createJSONPlugin, createPluginRegistry, createSVGPlugin, jsonPlugin, renderDiff, svgPlugin };
+export { type ChangeKind, Cluster, type ClusterDiff, type ClusterOptions, type CreatePlugin, Custom, DependencyError, Diagram, type DiagramClusterJSON, type DiagramDiffResult, type DiagramEdgeJSON, type DiagramJSON, type DiagramNodeJSON, type DiagramOptions, type DiagramsPlugin, type DiffMeta, type DiffOptions, type DiffSummary, Edge, type EdgeDiff, type EdgeOptions, type ExportContext, type ExporterCapability, type FromJSONOptions, type HookCapability, type HookContext, HookEvent, type HookHandler, Iconify, type ImportContext, type ImporterCapability, type MetadataCapability, type MetadataContext, Node, type NodeDiff, type NodeMetadata, type NodeOptions, type PluginCapability, type PluginContext, PluginError, type PluginRegistry, type ProviderModule, type RenderContext, type RenderDiffOptions, type RendererCapability, RuntimeError, type RuntimeSupport, type ThemeConfig, type ThemeName, type Yaml, computeDiff, createJSONPlugin, createPluginRegistry, createSVGPlugin, jsonPlugin, renderDiff, svgPlugin };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "diagrams-js",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "A TypeScript port of the diagrams Python library for drawing cloud system architecture diagrams as code",
   "keywords": [
     "architecture",

package/skills/diagrams-js/cli/SKILL.md

@@ -0,0 +1,220 @@
+---
+name: diagrams-js/cli
+description: >
+  Command-line interface for diagrams-js. Install @diagrams-js/cli and use
+  diagrams <command> to render, export, diff, init, watch, and manage
+  plugins. Cross-platform CLI with programmatic API. Supports file and stdin
+  input.
+type: tooling
+library: diagrams-js
+library_version: "0.5.0"
+requires:
+  - diagrams-js/getting-started
+sources:
+  - "hatemhosny/diagrams-js:docs/docs/guides/cli.mdx"
+  - "hatemhosny/diagrams-js:cli/src/cli.ts"
+---
+
+This skill builds on diagrams-js/getting-started. Read it first for foundational concepts.
+
+# diagrams-js CLI
+
+Command-line interface for diagrams-js. Render diagrams, import via plugins, export, generate diffs, scaffold new files, and watch for changes. Supports file and stdin input.
+
+## Installation
+
+```bash
+npm install -g @diagrams-js/cli
+```
+
+Or use with `npx`:
+
+```bash
+npx @diagrams-js/cli render diagram.ts -o out.svg
+```
+
+## Commands
+
+### render — Render diagrams and import via plugins
+
+```bash
+# Render diagram source to SVG (default: same-name.svg)
+diagrams render diagram.ts
+
+# Render to PNG
+diagrams render diagram.ts -o diagram.png
+
+# Render with options
+diagrams render diagram.ts -f svg -t dark -d LR -o out.svg
+
+# Import Docker Compose via plugin and render to SVG
+diagrams render docker-compose.yml
+
+# Import Kubernetes via plugin
+diagrams render k8s.yaml -p kubernetes -o architecture.svg
+
+# Output to stdout
+diagrams render diagram.ts --stdout
+
+# Write to file AND stdout
+diagrams render diagram.ts -o out.svg --stdout
+
+# Render from stdin
+cat diagram.json | diagrams render - -f json -o out.svg
+
+```
+
+**Input sources:** file (`.ts`, `.js`, `.mjs`, `.json`, `.svg`, `.yaml`, `.yml`), stdin (`-`)
+
+**Output formats:** `svg`, `png`, `jpg`, `dot`, `json`
+
+Plugin auto-detection for `.yaml`/`.yml`:
+
+- Files with `services:` → docker-compose
+- Files with `apiVersion:` and `kind:` → kubernetes
+
+### export — Export to plugin formats
+
+```bash
+# Export to Docker Compose (default: same-name.yml)
+diagrams export diagram.json -f docker-compose
+
+# Export to Kubernetes
+diagrams export diagram.ts -f kubernetes -o manifest.yaml
+
+# Export from stdin
+cat diagram.json | diagrams export - -f docker-compose
+
+# Export to stdout
+diagrams export diagram.json -f docker-compose --stdout
+```
+
+### diff — Visual diffs in git
+
+```bash
+# Diff against HEAD (default: diagram-diff.html)
+diagrams diff show HEAD diagram.ts
+
+# Diff with explicit output
+diagrams diff show HEAD diagram.ts -o diff.html
+
+# Diff to stdout
+diagrams diff show HEAD diagram.ts --stdout
+
+# Diff between branches
+diagrams diff show main...feature diagram.json -F html
+
+# List changed files
+diagrams diff list HEAD
+
+# Batch diff all changes
+diagrams diff batch main...feature -o ./diffs
+```
+
+### init — Scaffold new diagrams
+
+```bash
+# Basic diagram
+diagrams init "My Architecture"
+
+# AWS template
+diagrams init "AWS Stack" -t aws -o aws.ts
+
+# Kubernetes template
+diagrams init "K8s Cluster" -t k8s -o k8s.ts
+```
+
+**Templates:** `basic`, `aws`, `k8s`
+
+### watch — Watch and auto-render
+
+```bash
+# Watch file and re-render on changes (default: same-name.svg)
+diagrams watch diagram.ts
+
+# Watch with explicit output
+diagrams watch diagram.ts -o out.svg
+
+# Watch with PNG output
+diagrams watch diagram.ts -f png --scale 2 -o out.png
+```
+
+### plugins — Discover plugins
+
+```bash
+# List installed plugins
+diagrams plugins list
+
+# Show plugin details
+diagrams plugins info docker-compose
+```
+
+## Configuration
+
+Create `.diagramsrc.json`:
+
+```json
+{
+  "format": "svg",
+  "theme": "light",
+  "direction": "TB",
+  "curveStyle": "ortho",
+  "scale": 2,
+  "diff": {
+    "layout": "side-by-side",
+    "showUnchanged": "show",
+    "ignorePosition": true
+  }
+}
+```
+
+## Common Mistakes
+
+### HIGH Wrong input file format
+
+Wrong:
+
+```bash
+diagrams render diagram.txt  # .txt not supported
+```
+
+Correct:
+
+```bash
+diagrams render diagram.ts   # .ts, .js, .json, .svg, .yaml, .yml supported
+```
+
+### MEDIUM Forgetting output format for PNG/JPG
+
+Wrong:
+
+```bash
+diagrams render diagram.ts -o out.jpg  # Missing -f jpg
+```
+
+Correct:
+
+```bash
+diagrams render diagram.ts -f jpg -o out.jpg
+```
+
+### CRITICAL Wrong diff command syntax
+
+Wrong:
+
+```bash
+diagrams diff HEAD diagram.ts  # Missing subcommand
+```
+
+Correct:
+
+```bash
+diagrams diff show HEAD diagram.ts
+```
+
+## See Also
+
+- diagrams-js/getting-started — Basic diagram creation
+- diagrams-js/diagram-diff — Visual diff details
+- diagrams-js-plugin-system — Creating custom plugins
+- diagrams-js/github-action — CI/CD integration

package/skills/diagrams-js/creating-plugins/SKILL.md

@@ -443,13 +443,31 @@ export const myPlugin = () => ({
 3. **Version**: `npm version patch|minor|major`
 4. **Publish**: `npm publish --access public`
 
+### Naming Convention
+
+Name your plugin with the `diagrams-js-plugin-` prefix so the CLI and users can find it:
+
+```json
+{
+  "name": "diagrams-js-plugin-terraform"
+}
+```
+
+Or with a scope:
+
+```json
+{
+  "name": "@myorg/diagrams-js-plugin-terraform"
+}
+```
+
 ### NPM Keywords for Discoverability
 
 Add `diagrams-js` to your `package.json` keywords to make your plugin discoverable:
 
 ```json
 {
-  "name": "@diagrams-js/plugin-my-format",
+  "name": "diagrams-js-plugin-my-format",
   "keywords": ["diagrams-js", "diagrams", "architecture", "plugin", "import", "export"]
 }
 ```

package/skills/diagrams-js/diagram-diff/SKILL.md

@@ -191,20 +191,29 @@ These appear in the HTML output under "Diagram Options Changed".
 
 ## CLI Tool
 
-Use `diagrams-diff-cli` for git workflows:
+Use `@diagrams-js/cli` for git workflows:
 
 ```bash
 # Install globally
-npm install -g diagrams-diff-cli
+npm install -g @diagrams-js/cli
 
-# Compare with HEAD
-diagrams-diff HEAD diagram.json -o diff.html
+# Compare with HEAD (default: diagram-diff.html)
+diagrams diff show HEAD diagram.json
+
+# Compare with explicit output
+diagrams diff show HEAD diagram.json -o diff.html
+
+# Output to stdout
+diagrams diff show HEAD diagram.json --stdout
 
 # Compare branches
-diagrams-diff main...feature diagram.json -o diff.html
+diagrams diff show main...feature diagram.json -F html -o diff.html
+
+# List changed files
+diagrams diff list HEAD
 
-# Terminal preview
-diagrams-diff HEAD diagram.json --format terminal
+# Batch diff all changed files
+diagrams diff batch main...feature -o ./diffs
 ```
 
 ## Common Mistakes

package/skills/diagrams-js/github-action/SKILL.md

@@ -0,0 +1,318 @@
+---
+name: diagrams-js/github-action
+description: >
+  GitHub Action for diagrams-js. Use diagrams-js/action@v1 in CI/CD workflows
+  to render, diff, import, and validate architecture diagrams. Supports PR
+  comments, artifact uploads, and plugin integration.
+type: tooling
+library: diagrams-js
+library_version: "0.5.0"
+requires:
+  - diagrams-js/getting-started
+  - diagrams-js/cli
+sources:
+  - "hatemhosny/diagrams-js:docs/docs/guides/github-action.mdx"
+  - "hatemhosny/diagrams-js:action/action.yml"
+---
+
+This skill builds on diagrams-js/getting-started and diagrams-js/cli. Read them first for foundational concepts.
+
+# diagrams-js GitHub Action
+
+Use diagrams-js in GitHub Actions for CI/CD. Render diagrams on push, generate visual diffs in PRs, validate diagrams, and auto-render from Docker Compose or Kubernetes files.
+
+## Quick Start
+
+```yaml
+- uses: diagrams-js/action@v1
+  with:
+    command: render
+    args: architecture.ts
+    output: architecture.svg
+```
+
+## Inputs
+
+| Input               | Description                                       | Default           |
+| ------------------- | ------------------------------------------------- | ----------------- |
+| `command`           | CLI command: `render`, `import`, `export`, `diff` | `render`          |
+| `args`              | Arguments for the command                         | `""`              |
+| `format`            | Output format                                     | `svg`             |
+| `output`            | Output file path                                  | `""`              |
+| `theme`             | Color theme                                       | `""`              |
+| `direction`         | Layout direction                                  | `""`              |
+| `plugin`            | Plugin name                                       | `""`              |
+| `comment-pr`        | Comment on PR                                     | `false`           |
+| `upload-artifact`   | Upload artifact                                   | `true`            |
+| `artifact-name`     | Artifact name                                     | `diagrams-output` |
+| `working-directory` | Working directory                                 | `""`              |
+| `node-version`      | Node.js version                                   | `22`              |
+| `cli-version`       | CLI version                                       | `latest`          |
+
+## Outputs
+
+| Output          | Description         |
+| --------------- | ------------------- |
+| `output-path`   | Generated file path |
+| `output-format` | Output format       |
+
+## Core Patterns
+
+### Render on push
+
+```yaml
+name: Render Diagrams
+on:
+  push:
+    branches: [main]
+    paths:
+      - "diagrams/**"
+
+jobs:
+  render:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: diagrams-js/action@v1
+        with:
+          command: render
+          args: diagrams/architecture.ts
+          output: architecture.svg
+      - uses: actions/upload-artifact@v4
+        with:
+          name: diagrams
+          path: architecture.svg
+```
+
+### Diff in PR
+
+```yaml
+name: Diagram Diff
+on:
+  pull_request:
+    paths:
+      - "**/*.ts"
+      - "**/*.json"
+      - "**/*.svg"
+
+jobs:
+  diff:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: diagrams-js/action@v1
+        with:
+          command: diff
+          args: show origin/${{ github.base_ref }} architecture.ts
+          output: diff.html
+          format: html
+          comment-pr: true
+```
+
+### Validate diagrams
+
+```yaml
+name: Validate Diagrams
+on: [pull_request]
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: diagrams-js/action@v1
+        with:
+          command: render
+          args: diagram.ts
+          format: svg
+```
+
+### Import from Docker Compose
+
+```yaml
+- uses: diagrams-js/action@v1
+  with:
+    command: import
+    args: docker-compose.yml
+    output: architecture.svg
+    plugin: docker-compose
+```
+
+### Import from Kubernetes
+
+```yaml
+- uses: diagrams-js/action@v1
+  with:
+    command: import
+    args: k8s/manifest.yaml
+    output: k8s-architecture.svg
+    plugin: kubernetes
+```
+
+## PR Comments
+
+Enable `comment-pr: true` to post results on pull requests:
+
+```yaml
+- uses: diagrams-js/action@v1
+  with:
+    command: diff
+    args: show HEAD diagram.ts
+    output: diff.html
+    format: html
+    comment-pr: true
+```
+
+## Artifacts
+
+Outputs auto-upload as artifacts. Disable with `upload-artifact: false`:
+
+```yaml
+- uses: diagrams-js/action@v1
+  with:
+    command: render
+    args: diagram.ts
+    output: diagram.svg
+    artifact-name: my-diagram
+```
+
+## Version Pinning
+
+Pin CLI version for reproducible builds:
+
+```yaml
+- uses: diagrams-js/action@v1
+  with:
+    command: render
+    args: diagram.ts
+    cli-version: "0.1.0"
+```
+
+## Working Directory
+
+Run in a subdirectory:
+
+```yaml
+- uses: diagrams-js/action@v1
+  with:
+    command: render
+    args: diagram.ts
+    working-directory: ./projects/my-app
+```
+
+## Common Mistakes
+
+### CRITICAL Missing fetch-depth for diffs
+
+Wrong:
+
+```yaml
+- uses: actions/checkout@v4
+- uses: diagrams-js/action@v1
+  with:
+    command: diff
+    args: show origin/main diagram.ts
+```
+
+Correct:
+
+```yaml
+- uses: actions/checkout@v4
+  with:
+    fetch-depth: 0
+- uses: diagrams-js/action@v1
+  with:
+    command: diff
+    args: show origin/main diagram.ts
+```
+
+Git diff requires full history. Always set `fetch-depth: 0`.
+
+### HIGH Wrong command for diff
+
+Wrong:
+
+```yaml
+with:
+  command: diff
+  args: HEAD diagram.ts
+```
+
+Correct:
+
+```yaml
+with:
+  command: diff
+  args: show HEAD diagram.ts
+```
+
+Diff requires subcommand: `show`, `list`, or `batch`.
+
+### MEDIUM Forgetting output path
+
+Without `output`, the action generates default filenames. Always specify `output` for clarity:
+
+```yaml
+with:
+  command: render
+  args: diagram.ts
+  output: diagram.svg
+```
+
+## Best Practices
+
+### 1. Trigger on relevant paths
+
+Only run when diagram files change:
+
+```yaml
+on:
+  push:
+    paths:
+      - "diagrams/**"
+      - "**/*.diagram.ts"
+```
+
+### 2. Use matrix for multiple diagrams
+
+```yaml
+strategy:
+  matrix:
+    diagram: [architecture.ts, infrastructure.ts]
+steps:
+  - uses: diagrams-js/action@v1
+    with:
+      command: render
+      args: diagrams/${{ matrix.diagram }}
+      output: ${{ matrix.diagram }}.svg
+```
+
+### 3. Combine with artifact upload
+
+```yaml
+- uses: diagrams-js/action@v1
+  with:
+    command: render
+    args: diagram.ts
+    output: diagram.svg
+- uses: actions/upload-artifact@v4
+  with:
+    name: diagrams
+    path: diagram.svg
+```
+
+### 4. Pin versions in production
+
+```yaml
+- uses: diagrams-js/action@v1
+  with:
+    cli-version: "0.1.0"
+```
+
+## See Also
+
+- diagrams-js/cli — Command-line interface
+- diagrams-js/diagram-diff — Visual diff details
+- diagrams-js-plugin-system — Creating custom plugins