@diagrammo/dgmo 0.8.3 → 0.8.5

package/.claude/commands/dgmo-diagram-this.md

@@ -0,0 +1,60 @@
+# /dgmo-diagram-this — Generate Diagrams from Code
+
+You are reading the user's code and generating DGMO diagrams that document what it does. Don't ask what kind of diagram — figure it out from the code.
+
+## Prerequisites
+
+Verify DGMO MCP tools are available by calling `mcp__dgmo__list_chart_types`. If not available, tell the user to run `/dgmo` first to set up the MCP server.
+
+## Step 1 — Determine Scope
+
+The user may provide:
+- **A file path** — diagram that specific file
+- **A function/class name** — diagram that specific piece
+- **A directory** — diagram the module/package
+- **Nothing** — look at the current working directory and diagram the overall project structure
+
+If scope is unclear, read the project root (`package.json`, `README.md`, `src/` listing) and pick the most interesting thing to diagram.
+
+## Step 2 — Read the Code
+
+Read the relevant source files. Look for:
+- Function signatures and call chains
+- API endpoints and request handlers
+- Database models, schemas, ORM entities
+- State machines, status enums, workflow transitions
+- Service-to-service calls, message passing
+- Infrastructure config (Docker, k8s, terraform)
+- Import graphs and module dependencies
+
+## Step 3 — Pick the Diagram Type
+
+| What you found | Diagram type |
+|---|---|
+| API handler calling other services/DB | `sequence` |
+| Multiple models with relationships | `er` |
+| Service/module dependency graph | `c4` (container level) |
+| State enum, FSM, workflow transitions | `state` |
+| Decision logic, branching control flow | `flowchart` |
+| Docker/k8s/cloud infra config | `infra` |
+| Class hierarchy with methods | `class` |
+| Team/org structure data | `org` |
+
+If a single file contains multiple diagrammable things (e.g., models AND an API handler), generate multiple diagrams.
+
+## Step 4 — Generate
+
+1. Call `mcp__dgmo__get_language_reference("<type>")` for syntax.
+2. Call `mcp__dgmo__get_examples("<type>")` for idiomatic patterns.
+3. Write the DGMO using **real names from the code** — actual function names, model names, service names, field types.
+4. Call `mcp__dgmo__validate_diagram(dgmo)` — fix any errors.
+5. Call `mcp__dgmo__preview_diagram([{dgmo, title}])` to show the result.
+6. Save to `<descriptive-name>.dgmo` in the project.
+
+## Rules
+
+- **Use real names** — `UserService`, `orders` table, `POST /api/auth/login` — not generic placeholders
+- **Keep it focused** — a sequence diagram with 5-8 messages is better than one with 30. Show the main flow, not every edge case.
+- **Lean on inference** — don't declare `PostgresDB is a database` (the name auto-infers). Only use `is a` when the name doesn't match.
+- **No colons in directives** — `sequence Auth Flow`, not `chart: sequence`
+- **Multiple diagrams are fine** — if the code has both a schema and an API flow, generate both and use `preview_diagram` with multiple entries

package/.claude/commands/dgmo-document-project.md

@@ -0,0 +1,128 @@
+# /dgmo-document-project — Generate Diagrams for a Codebase
+
+You are generating a suite of DGMO diagrams that document the user's project. Your goal is to read the codebase, understand its architecture, and produce 3–6 diagrams that capture how the system works.
+
+## Prerequisites
+
+Before starting, verify that the DGMO MCP tools are available by calling `mcp__dgmo__list_chart_types`. If the tools are not available, tell the user to run `/dgmo` first to set up the MCP server, then come back to this command.
+
+## Step 1 — Understand the Project
+
+Read these files (skip any that don't exist):
+
+1. **README.md** or **README** — project purpose and overview
+2. **package.json** / **Cargo.toml** / **go.mod** / **pyproject.toml** / **requirements.txt** — tech stack and dependencies
+3. **docker-compose.yml** / **Dockerfile** / **k8s/** / **terraform/** — infrastructure
+4. **src/** or **app/** directory listing — code structure
+5. **.env.example** or config files — external services and integrations
+
+From this, determine:
+- What the project does (one sentence)
+- The tech stack (language, framework, database, message broker, etc.)
+- Key modules or services
+- External dependencies and integrations
+- Data models (if database-backed)
+
+## Step 2 — Decide Which Diagrams to Generate
+
+Pick 3–6 diagrams based on what the project actually has. Don't force a diagram type that doesn't fit. Use this decision matrix:
+
+| Signal in codebase | Diagram type | What to show |
+|---|---|---|
+| Multiple services, APIs, or modules | **c4** (context or container) | System components and their relationships |
+| REST/GraphQL endpoints, API handlers | **sequence** | 1–2 key request flows (e.g., auth, main business operation) |
+| Database models, ORM entities, schema files | **er** | Entity relationships and key fields |
+| Docker, k8s, cloud infra, load balancers | **infra** | Traffic flow and infrastructure components |
+| State machines, workflow engines, status fields | **state** | Key state transitions |
+| Multiple packages or layers | **flowchart** | Request lifecycle or data flow |
+| Microservices with message queues | **sequence** | Async event flow between services |
+
+**Rules:**
+- Always include a C4 context or container diagram — every project benefits from a high-level view
+- Prefer sequence diagrams for showing **behavior** (how things interact at runtime)
+- Prefer ER diagrams only if there's a real database schema to document
+- Don't generate infra diagrams for projects without infrastructure config
+- Don't generate more than 2 sequence diagrams — pick the most important flows
+
+## Step 3 — Get Syntax Help
+
+For each diagram type you'll generate, call:
+
+```
+mcp__dgmo__get_language_reference("<type>")
+```
+
+Also call `mcp__dgmo__get_examples("<type>")` to see real examples of that chart type. Use these as patterns — they show idiomatic DGMO style.
+
+## Step 4 — Generate the Diagrams
+
+Write the DGMO markup for each diagram. Follow these rules:
+
+- **Keep diagrams focused** — a C4 diagram with 5–8 components is better than one with 20
+- **Use real names from the codebase** — actual service names, model names, endpoint paths
+- **Lean on inference** — don't declare participant types unless the name doesn't match (e.g., `User` auto-infers as actor, `PostgresDB` as database)
+- **Add tags for color coding** when there are natural groupings (teams, domains, layers)
+- **Title every diagram** — the title goes on the first line after the chart type
+
+### Syntax reminders (no colons in directives or data):
+```
+sequence Auth Flow          // first line: type + title
+tag Layer alias l           // tag declaration (no colon)
+  Frontend(blue)
+  Backend(green)
+
+User -POST /login-> API     // sync arrow
+API ~publish~> Queue        // async arrow
+note Validates JWT          // note (no colon)
+```
+
+## Step 5 — Validate Before Rendering
+
+For each diagram, call `mcp__dgmo__validate_diagram(dgmo)` to check for errors. Fix any issues before proceeding.
+
+## Step 6 — Generate the Report
+
+Once all diagrams validate, bundle them into a report:
+
+```
+mcp__dgmo__generate_report({
+  title: "<Project Name> — Architecture Diagrams",
+  subtitle: "Auto-generated from codebase analysis",
+  sections: [
+    { title: "System Context (C4)", description: "High-level view of ...", dgmo: "..." },
+    { title: "Auth Flow", description: "How authentication works", dgmo: "..." },
+    ...
+  ],
+  theme: "dark",
+  palette: "nord",
+  include_source: true,
+  open: true
+})
+```
+
+## Step 7 — Save Source Files
+
+Write each diagram to a `diagrams/` directory in the project root:
+
+- `diagrams/c4-context.dgmo`
+- `diagrams/sequence-auth.dgmo`
+- `diagrams/er-schema.dgmo`
+- etc.
+
+Use descriptive filenames. Create the `diagrams/` directory if it doesn't exist.
+
+## Step 8 — Report to the User
+
+Summarize what was generated:
+
+1. List each diagram with a one-line description
+2. Mention the HTML report was opened in the browser
+3. Note the saved `.dgmo` files in `diagrams/`
+4. Suggest which diagrams might be worth expanding or adding next
+
+## Important Notes
+
+- This skill works with **any** project — not just TypeScript or JavaScript
+- Don't ask the user what diagrams to generate — make the decision based on what you find in the code. They can request changes after.
+- If the project is very small (single file, script), generate just 1–2 diagrams instead of forcing 6
+- If you can't determine the project structure, ask the user to point you at the main source directory