@diagc/cli 0.12.0 → 0.14.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,8 +1,12 @@
1
1
  # diagc
2
2
 
3
- Author software-architecture diagrams as code, edit them in a local visual studio, and publish them as shareable pages and images.
3
+ Diagrams as code, with a local studio. diagc turns diagram sources that live in your repository into things other people can open.
4
4
 
5
- Diagrams are plain files in your repo, so they diff, review, and refactor like the rest of it.
5
+ - **Pages and pictures.** `diagc publish` writes one self-contained HTML page per diagram, and a PNG. The page folds, zooms and switches views in the browser, with no server behind it. Host the pages on GitHub Pages, GitLab Pages or any static host, and put the PNG in a README.
6
+ - **Diffs in pull requests.** A GitHub Action comments on a pull request that changes a diagram: the list of changes, and the before and after pictures.
7
+ - **A local studio.** `diagc studio` opens a browser app against your repository. Draw a diagram there and the studio saves it as a file in the repository. `diagc eject` turns a drawn diagram into TypeScript.
8
+
9
+ Diagrams are plain files in your repository, so they diff, review and refactor like the rest of it.
6
10
 
7
11
  ```bash
8
12
  npm i -g @diagc/cli # or: npx @diagc/cli studio
@@ -23,14 +27,15 @@ diagc studio # opens the editor, recompiling as you edit
23
27
 
24
28
  | Command | What it does |
25
29
  | --- | --- |
26
- | `diagc init` | Set a repository up: a starter diagram (`--type c4` for a C4 one), the `.gitignore` lines, and with `--agents` a pointer to the guide for coding agents. |
30
+ | `diagc init` | Set a repository up: a starter diagram (`--type c4` for a C4 one), the `.gitignore` lines, and with `--agents` a pointer to the guide for coding agents (`AGENTS.md` / `CLAUDE.md`, and a Claude Code skill). |
27
31
  | `diagc compile` | Compile `.diagrams/src/**/*.diagram.{ts,json}` into validated artifacts under `.diagrams/.artifacts/`. The default command. |
32
+ | `diagc lint` | Report what compiles but is probably a mistake — typos, duplicates, unused or undrawn parts. `--json` for a script or an agent; exit 1 until clean. |
28
33
  | `diagc watch` | The same, recompiling on change. |
29
34
  | `diagc studio` | Serve the visual editor against the current directory (default `http://127.0.0.1:5173`). Diagrams drawn here are saved back as `.diagram.json`. |
30
35
  | `diagc publish` | Write self-contained HTML pages to `.diagrams/html/` and PNGs to `.diagrams/static/`. |
31
36
  | `diagc guide` | Print how to write a diagram: the DSL, then one topic per diagram type (`diagc guide c4`). Written for a coding agent as much as for a person. |
32
37
 
33
- Flags: `--out <dir>` (artifact directory), `--no-images` (publish HTML only), `--link <url>` (link the published index to an address), `--help`.
38
+ Flags: `--type <type>` and `--agents` (init), `--out <dir>` (artifact directory), `--json` (lint findings as JSON), `--no-images` (publish HTML only), `--link <url>` (link the published index to an address), `--help`.
34
39
 
35
40
  PNG export drives headless Chrome. Without one, `publish` writes HTML and says so; point `CHROME_PATH` at a browser to get images.
36
41
 
@@ -38,10 +43,12 @@ PNG export drives headless Chrome. Without one, `publish` writes HTML and says s
38
43
 
39
44
  Write a `.diagram.ts` with the builder DSL, or draw one in the studio and it writes a `.diagram.json` for you. Both compile to the same validated model, so a diagram is never trapped in the tool that made it. Positions live in a separate `<name>.layout.json`, which keeps meaning and coordinates in different diffs.
40
45
 
41
- Commit `.diagrams/src/`. `.diagrams/.artifacts/` and `.diagrams/html/` are build output.
46
+ Commit `.diagrams/src/`. `.diagrams/.artifacts/`, `.diagrams/html/` and `.diagrams/diff/` are build output — `diagc init` gitignores them.
42
47
 
43
48
  ## Documentation
44
49
 
50
+ Website and live examples: <https://ferroman.github.io/diagc/>
51
+
45
52
  Full docs, tutorials, and the model reference: <https://github.com/Ferroman/diagc>
46
53
 
47
54
  ## License
@@ -12,7 +12,7 @@ This guide is for diagc {{version}}.
12
12
 
13
13
  A person runs `diagc studio` to browse every diagram and to move boxes by hand.
14
14
 
15
- Commit `.diagrams/src/` and `.diagrams/static/`. `.diagrams/.artifacts/` and `.diagrams/html/` are build output.
15
+ Commit `.diagrams/src/` and `.diagrams/static/`. `.diagrams/.artifacts/`, `.diagrams/html/` and `.diagrams/diff/` are build output.
16
16
 
17
17
  ## A diagram
18
18
 
@@ -0,0 +1,29 @@
1
+ ---
2
+ name: diagc
3
+ description: Write, change or fix a diagc diagram (.diagrams/src/*.diagram.ts) — architecture, C4, deployment, ER, activity, threat model, causal loop, plan and more. Use when asked to draw or update a diagram in a repository that uses diagc.
4
+ ---
5
+
6
+ <!-- diagc:begin -->
7
+ # Writing diagrams with diagc
8
+
9
+ A diagram is a TypeScript file under `.diagrams/src/`; `diagc` validates it, lays it out and draws it. The DSL is documented by the installed CLI, not here. Read it each time: it describes the version that is installed.
10
+
11
+ ## Before writing
12
+
13
+ 1. Run `diagc guide`: the DSL, the node types and relation kinds, the rules, and the list of diagram types.
14
+ 2. Run `diagc guide <topic>` when the diagram is one of those types (`c4`, `er`, `deployment`, …). Each topic prints a complete starter to begin from.
15
+
16
+ ## The loop
17
+
18
+ 1. Write or edit `.diagrams/src/<name>.diagram.ts`.
19
+ 2. Run `diagc lint --json` until it prints `[]` and exits 0. Each finding has `file`, `severity`, `code` and `message`: an `error` does not compile, a `warning` compiles but is probably a mistake.
20
+ 3. Run `diagc publish <name>` and look at `.diagrams/static/<name>.png`. It needs Chrome (set `CHROME_PATH` when none is found); without one it writes the HTML page only.
21
+
22
+ ## Rules
23
+
24
+ - Never write positions or sizes. Layout is automatic. A person adjusts it in `diagc studio`, which saves `<name>.layout.json` beside the source: leave that file alone.
25
+ - A `.diagram.ts` diagram is read-only in the studio. Change it in its source.
26
+ - A `.diagram.json` file is a diagram drawn in the studio. Leave it to the studio unless asked; `diagc eject <name>` turns one into TypeScript.
27
+ - Commit `.diagrams/src/` and `.diagrams/static/`. `.diagrams/.artifacts/`, `.diagrams/html/` and `.diagrams/diff/` are build output.
28
+ - Do not paste guide text into the repository. Run `diagc guide` instead.
29
+ <!-- diagc:end -->