@diagc/cli 1.6.0 → 1.8.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 +8 -3
- package/assets/guide/git-graph.md +3 -0
- package/assets/guide/index.md +3 -3
- package/assets/skill/SKILL.md +1 -1
- package/assets/studio/assets/index-CB6jjAka.js +112 -0
- package/assets/studio/index.html +1 -1
- package/assets/viewer/index.html +23 -23
- package/dist/cli/parse.d.ts +8 -1
- package/dist/cli/parse.js +13 -1
- package/dist/cli/run.js +6 -2
- package/dist/cli.js +6 -2
- package/dist/commands/show.d.ts +1 -1
- package/dist/commands/show.js +12 -2
- package/dist/commands/tui.d.ts +1 -1
- package/dist/commands/tui.js +10 -2
- package/dist/text/ansi.js +11 -5
- package/dist/text/canvas.d.ts +9 -2
- package/dist/text/canvas.js +25 -7
- package/dist/text/dos.d.ts +69 -0
- package/dist/text/dos.js +93 -0
- package/dist/text/git.d.ts +52 -0
- package/dist/text/git.js +274 -0
- package/dist/text/glyphs.d.ts +4 -3
- package/dist/text/glyphs.js +18 -2
- package/dist/text/layout.d.ts +39 -1
- package/dist/text/layout.js +10 -7
- package/dist/text/legend.js +17 -13
- package/dist/text/paint.d.ts +6 -4
- package/dist/text/paint.js +164 -17
- package/dist/text/scene.d.ts +7 -0
- package/dist/text/scene.js +16 -4
- package/dist/tui/actions.d.ts +5 -0
- package/dist/tui/actions.js +17 -2
- package/dist/tui/app.d.ts +3 -0
- package/dist/tui/app.js +18 -5
- package/dist/tui/nav.d.ts +16 -10
- package/dist/tui/nav.js +26 -4
- package/dist/tui/overview.d.ts +4 -2
- package/dist/tui/overview.js +38 -8
- package/dist/tui/screen.d.ts +10 -0
- package/dist/tui/screen.js +105 -23
- package/dist/tui/state.d.ts +14 -10
- package/dist/tui/state.js +13 -4
- package/package.json +2 -2
- package/assets/studio/assets/index-DRsUukzt.js +0 -112
package/README.md
CHANGED
|
@@ -5,6 +5,7 @@ Diagrams as code, with a local studio. diagc turns diagram sources that live in
|
|
|
5
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
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
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
|
+
- **In the terminal.** `diagc show` prints a diagram as text, for a pipe or a coding agent. `diagc tui` browses the diagrams full-screen and redraws as you edit.
|
|
8
9
|
|
|
9
10
|
Diagrams are plain files in your repository, so they diff, review and refactor like the rest of it.
|
|
10
11
|
|
|
@@ -30,12 +31,16 @@ diagc studio # opens the editor, recompiling as you edit
|
|
|
30
31
|
| `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). |
|
|
31
32
|
| `diagc compile` | Compile `.diagrams/src/**/*.diagram.{ts,json}` into validated artifacts under `.diagrams/.artifacts/`. The default command. |
|
|
32
33
|
| `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. |
|
|
33
|
-
| `diagc watch` |
|
|
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`. |
|
|
34
|
+
| `diagc watch` | Compile, then again on every change. |
|
|
35
35
|
| `diagc publish` | Write self-contained HTML pages to `.diagrams/html/` and PNGs to `.diagrams/static/`. |
|
|
36
|
+
| `diagc show` | Print a diagram as text: boxes, lines and labels in box-drawing characters, coloured on a terminal and plain in a pipe. `--plane`, `--layers`, `--depth` and `--root` choose the view, `--ascii` the characters. |
|
|
37
|
+
| `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`. |
|
|
38
|
+
| `diagc tui` | Browse the diagrams full-screen in the terminal: fold and unfold, go into a group, switch planes and layers, search. Redraws as the sources change. |
|
|
39
|
+
| `diagc eject` | Replace a drawn `.diagram.json` with a generated `.diagram.ts`, checked first to rebuild the same model. |
|
|
40
|
+
| `diagc diff` | Draw what changed in the diagrams between two git refs, or a ref and the working tree: before and after pages and PNGs, and a summary. |
|
|
36
41
|
| `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. |
|
|
37
42
|
|
|
38
|
-
|
|
43
|
+
`diagc --help` lists every command and flag, and the [CLI reference](https://ferroman.github.io/diagc/docs/reference/cli.html) has the details.
|
|
39
44
|
|
|
40
45
|
PNG export drives headless Chrome. Without one, `publish` writes HTML and says so; point `CHROME_PATH` at a browser to get images.
|
|
41
46
|
|
|
@@ -13,6 +13,9 @@ A branching history: one lane per branch, commits along it, and the branch-offs
|
|
|
13
13
|
- `branch.merge(src, { tag })` adds a commit that absorbs the commit `src` from another lane. It throws if `src` is on the same lane.
|
|
14
14
|
- `g.stage(id, { name, from, to })` frames a span of columns across every lane. `to` defaults to `from`. Declare it after the commits it names.
|
|
15
15
|
- Columns are worked out from the links: a commit sits one column after everything it follows, branches from or merges. Do not try to place commits.
|
|
16
|
+
- A column widens to fit what is drawn in it: a commit moves right until its tag clears the tag before it on the lane, and a stage's frame widens to its title. Use `gap` for time passing, not to make room for a label.
|
|
17
|
+
- Branches, commits and stages are nodes, and every node shares one id space. A commit's id defaults to `<branch id>-<n>`. `g.stage('release', …)` after `g.branch('release')` throws at that line: name the stage `release-stage`.
|
|
18
|
+
- Commits may share a tag: two deploys to prod are two commits tagged `deploy = prod`, and lint does not report them.
|
|
16
19
|
|
|
17
20
|
## Node types
|
|
18
21
|
|
package/assets/guide/index.md
CHANGED
|
@@ -8,7 +8,7 @@ This guide is for diagc {{version}}.
|
|
|
8
8
|
|
|
9
9
|
1. Write or edit `.diagrams/src/<name>.diagram.ts`. A folder is allowed: `.diagrams/src/team/app.diagram.ts` is the diagram `team/app`.
|
|
10
10
|
2. Run `diagc lint --json`. It prints `[]` and exits 0 when everything is clean. Otherwise each finding has `file`, `severity`, `code` and `message`: fix it and run again. An `error` means the diagram does not compile. A `warning` compiles but is probably a mistake, such as a misspelled type.
|
|
11
|
-
3. Run `diagc show <name>` to read the picture as text: the boxes, what sits inside what, and the arrows with their labels, every group open. It needs nothing else. Run `diagc publish <name>` and look at `.diagrams/static/<name>.png` to check the picture itself. It needs Chrome; set `CHROME_PATH` when none is found. The PNG shows the first plane with every group opened and only the layers that plane turns on; each further plane gets `.diagrams/static/<name>.<plane>.png`, and the other layers are on the page `.diagrams/html/<name>.html`.
|
|
11
|
+
3. Run `diagc show <name>` to read the picture as text: the boxes, what sits inside what, and the arrows with their labels, every group open. It needs nothing else. Run `diagc publish <name>` and look at `.diagrams/static/<name>.png` to check the picture itself; `diagc publish` with no name publishes every diagram. It needs Chrome; set `CHROME_PATH` when none is found. The PNG shows the first plane with every group opened and only the layers that plane turns on; each further plane gets `.diagrams/static/<name>.<plane>.png`, and the other layers are on the page `.diagrams/html/<name>.html`.
|
|
12
12
|
|
|
13
13
|
A person runs `diagc studio` to browse every diagram and to move boxes by hand.
|
|
14
14
|
|
|
@@ -34,7 +34,7 @@ More node options:
|
|
|
34
34
|
| `metadata` | Free-form key and value data. |
|
|
35
35
|
| `plane`, `layer` | Show the node in one plane only, or put it on a layer. |
|
|
36
36
|
|
|
37
|
-
More relation options: `layer`, `plane` (drawn on that plane only), `description`, `id
|
|
37
|
+
More relation options: `layer`, `plane` (drawn on that plane only), `description`, `id`, and `style`, one arrow's look: `{ color: '#c0392b', line: 'dashed', shape: 'step', end: 'none' }` (`line` is `solid`, `dashed` or `dotted`; `shape` is `curved`, `straight` or `step`; `end` is `arrow`, `dot`, `square`, `diamond` or `none`; `RelationStyle` in `reference/model.md` has the rest). The file is TypeScript, so to give many arrows one look, declare the style once (`const toProd = { color: '#c0392b' }`) and pass `style: toProd` to each.
|
|
38
38
|
|
|
39
39
|
## Types and kinds
|
|
40
40
|
|
|
@@ -91,7 +91,7 @@ export default m;
|
|
|
91
91
|
|
|
92
92
|
## Rules that catch people
|
|
93
93
|
|
|
94
|
-
-
|
|
94
|
+
- Declaring an id twice throws at the second declaration, and the message names its line. Every node shares one id space, whatever declares it: `m.node`, a git branch, a commit, a stage. Declare a node once and keep the handle.
|
|
95
95
|
- `m.relate(a, 'b-id', …)` does not work. Pass the handle that `m.node` returned.
|
|
96
96
|
- Put what the reader must see in `name`. `description` is not drawn.
|
|
97
97
|
- Keep a relation `label` to a short phrase. It is cut at about 24 characters.
|
package/assets/skill/SKILL.md
CHANGED
|
@@ -17,7 +17,7 @@ A diagram is a TypeScript file under `.diagrams/src/`; `diagc` validates it, lay
|
|
|
17
17
|
|
|
18
18
|
1. Write or edit `.diagrams/src/<name>.diagram.ts`.
|
|
19
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 show <name>` and read the picture as text: the boxes, the nesting and the arrows with their labels. Then run `diagc publish <name>` and look at `.diagrams/static/<name>.png
|
|
20
|
+
3. Run `diagc show <name>` and read the picture as text: the boxes, the nesting and the arrows with their labels. Then run `diagc publish <name>` and look at `.diagrams/static/<name>.png`; `diagc publish` with no name does every diagram at once. It needs Chrome (set `CHROME_PATH` when none is found); without one it writes the HTML page only.
|
|
21
21
|
|
|
22
22
|
## Rules
|
|
23
23
|
|