@diagc/cli 0.12.0 → 0.13.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 +4 -3
- package/assets/guide/index.md +1 -1
- package/assets/skill/SKILL.md +29 -0
- package/dist/cli.d.ts +1 -1
- package/dist/cli.js +5 -2
- package/dist/home.d.ts +2 -0
- package/dist/home.js +2 -0
- package/dist/init.d.ts +14 -5
- package/dist/init.js +60 -20
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -23,14 +23,15 @@ diagc studio # opens the editor, recompiling as you edit
|
|
|
23
23
|
|
|
24
24
|
| Command | What it does |
|
|
25
25
|
| --- | --- |
|
|
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. |
|
|
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 (`AGENTS.md` / `CLAUDE.md`, and a Claude Code skill). |
|
|
27
27
|
| `diagc compile` | Compile `.diagrams/src/**/*.diagram.{ts,json}` into validated artifacts under `.diagrams/.artifacts/`. The default command. |
|
|
28
|
+
| `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
29
|
| `diagc watch` | The same, recompiling on change. |
|
|
29
30
|
| `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
31
|
| `diagc publish` | Write self-contained HTML pages to `.diagrams/html/` and PNGs to `.diagrams/static/`. |
|
|
31
32
|
| `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
33
|
|
|
33
|
-
Flags: `--out <dir>` (artifact directory), `--no-images` (publish HTML only), `--link <url>` (link the published index to an address), `--help`.
|
|
34
|
+
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
35
|
|
|
35
36
|
PNG export drives headless Chrome. Without one, `publish` writes HTML and says so; point `CHROME_PATH` at a browser to get images.
|
|
36
37
|
|
|
@@ -38,7 +39,7 @@ PNG export drives headless Chrome. Without one, `publish` writes HTML and says s
|
|
|
38
39
|
|
|
39
40
|
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
41
|
|
|
41
|
-
Commit `.diagrams/src/`. `.diagrams/.artifacts/` and `.diagrams/
|
|
42
|
+
Commit `.diagrams/src/`. `.diagrams/.artifacts/`, `.diagrams/html/` and `.diagrams/diff/` are build output — `diagc init` gitignores them.
|
|
42
43
|
|
|
43
44
|
## Documentation
|
|
44
45
|
|
package/assets/guide/index.md
CHANGED
|
@@ -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/
|
|
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 -->
|
package/dist/cli.d.ts
CHANGED
|
@@ -16,7 +16,7 @@ interface Args {
|
|
|
16
16
|
labels?: [string, string];
|
|
17
17
|
/** init `--type`: which starter to copy */
|
|
18
18
|
type?: string;
|
|
19
|
-
/** init `--agents`: write the coding-agent block */
|
|
19
|
+
/** init `--agents`: write the coding-agent block and the Claude Code skill */
|
|
20
20
|
agents: boolean;
|
|
21
21
|
}
|
|
22
22
|
/** Parse argv into command + flags. Unknown flags (anything `--…` that is not
|
package/dist/cli.js
CHANGED
|
@@ -43,7 +43,8 @@ const USAGE = `Usage: diagc <init|compile|lint|watch|publish|studio|eject|diff|g
|
|
|
43
43
|
Commands:
|
|
44
44
|
init init [name] [--type <type>] [--agents]: set a repository up — a starter
|
|
45
45
|
diagram under .diagrams/src (compiled), the .gitignore lines, and with
|
|
46
|
-
--agents a pointer to the guide for coding agents (AGENTS.md / CLAUDE.md
|
|
46
|
+
--agents a pointer to the guide for coding agents (AGENTS.md / CLAUDE.md,
|
|
47
|
+
and a skill where Claude Code is in use)
|
|
47
48
|
compile Compile *.diagram.{ts,json} sources into overlay artifacts once
|
|
48
49
|
lint Report suspicious diagrams (typos, duplicates, unused or undrawn parts); exit 1 on any
|
|
49
50
|
watch Recompile — and live-recompile — a directory of sources
|
|
@@ -65,7 +66,8 @@ Options:
|
|
|
65
66
|
--image-url t diff: summary.md's image links as t, {path} standing for each PNG
|
|
66
67
|
--update-includes Refetch remote includes and rewrite the snapshot lock
|
|
67
68
|
--type <type> init: the starter to copy (default basic; 'diagc guide' lists the types)
|
|
68
|
-
--agents init: write the coding-agent block into AGENTS.md / CLAUDE.md
|
|
69
|
+
--agents init: write the coding-agent block into AGENTS.md / CLAUDE.md, and
|
|
70
|
+
the skill into .claude/skills/diagc/ where Claude Code is in use
|
|
69
71
|
--help, -h Show this help and exit
|
|
70
72
|
`;
|
|
71
73
|
/** Parse argv into command + flags. Unknown flags (anything `--…` that is not
|
|
@@ -406,6 +408,7 @@ async function main() {
|
|
|
406
408
|
...(args.type !== undefined ? { type: args.type } : {}),
|
|
407
409
|
agents: args.agents,
|
|
408
410
|
startersDir: home.startersDir,
|
|
411
|
+
skillFile: home.skillFile,
|
|
409
412
|
version: cliVersion(home.root),
|
|
410
413
|
coreEntry: home.coreEntry,
|
|
411
414
|
resolver: snap.resolver,
|
package/dist/home.d.ts
CHANGED
|
@@ -21,6 +21,8 @@ export interface HomePaths {
|
|
|
21
21
|
guideDir: string;
|
|
22
22
|
/** `<type>/starter.diagram.ts`, one folder per diagram type */
|
|
23
23
|
startersDir: string;
|
|
24
|
+
/** the Claude Code skill `diagc init --agents` writes into a repository */
|
|
25
|
+
skillFile: string;
|
|
24
26
|
}
|
|
25
27
|
export interface Home {
|
|
26
28
|
root: string;
|
package/dist/home.js
CHANGED
|
@@ -64,6 +64,7 @@ export function homePaths(home, coreEntry = resolveCoreEntry) {
|
|
|
64
64
|
studioDir,
|
|
65
65
|
guideDir: path.join(root, 'assets', 'guide'),
|
|
66
66
|
startersDir: path.join(root, 'assets', 'starters'),
|
|
67
|
+
skillFile: path.join(root, 'assets', 'skill', 'SKILL.md'),
|
|
67
68
|
};
|
|
68
69
|
}
|
|
69
70
|
return {
|
|
@@ -77,6 +78,7 @@ export function homePaths(home, coreEntry = resolveCoreEntry) {
|
|
|
77
78
|
// A checkout reads the starters where the examples keep them; `stage-assets`
|
|
78
79
|
// copies only the starter files out, into the same `<type>/` shape.
|
|
79
80
|
startersDir: path.join(root, '.diagrams', 'src', 'examples'),
|
|
81
|
+
skillFile: path.join(root, 'packages', 'diagc', 'skill', 'SKILL.md'),
|
|
80
82
|
};
|
|
81
83
|
}
|
|
82
84
|
/** The release this CLI is, read from the home's own `package.json`. release-please
|
package/dist/init.d.ts
CHANGED
|
@@ -8,9 +8,11 @@ export interface InitOptions {
|
|
|
8
8
|
name?: string;
|
|
9
9
|
/** the starter to copy; `basic` when omitted */
|
|
10
10
|
type?: string;
|
|
11
|
-
/** write the coding-agent block into AGENTS.md / CLAUDE.md */
|
|
11
|
+
/** write the coding-agent block into AGENTS.md / CLAUDE.md, and the Claude Code skill */
|
|
12
12
|
agents: boolean;
|
|
13
13
|
startersDir: string;
|
|
14
|
+
/** the skill the package ships, copied into a repository that uses Claude Code */
|
|
15
|
+
skillFile: string;
|
|
14
16
|
/** what the `npm i -D @diagc/core@…` hint names */
|
|
15
17
|
version: string;
|
|
16
18
|
coreEntry: string;
|
|
@@ -30,10 +32,17 @@ export declare const AGENTS_END = "<!-- diagc:end -->";
|
|
|
30
32
|
* this block does not go stale when the DSL grows. The markers let a later run
|
|
31
33
|
* replace it in place. */
|
|
32
34
|
export declare const AGENTS_BLOCK = "<!-- diagc:begin -->\n## Diagrams\n\nDiagrams live in `.diagrams/src/*.diagram.ts` and are built with `diagc`.\n\n- Run `diagc guide` before writing or changing one; `diagc guide <type>` covers one diagram type.\n- Run `diagc lint --json` until it reports nothing.\n- Run `diagc publish <name>` and look at `.diagrams/static/<name>.png` to check the picture.\n<!-- diagc:end -->\n";
|
|
33
|
-
/**
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
35
|
+
/** Where the skill goes: the folder Claude Code reads a repository's skills from. */
|
|
36
|
+
export declare const SKILL_PATH = ".claude/skills/diagc/SKILL.md";
|
|
37
|
+
/** `existing` with `block` added at the end, or — when an earlier block is there —
|
|
38
|
+
* with that block replaced where it stands, so a second run never duplicates it
|
|
39
|
+
* and a run after an upgrade refreshes it. `block` runs from the begin marker to
|
|
40
|
+
* the newline after the end marker. */
|
|
41
|
+
export declare function withBlock(existing: string, block: string): {
|
|
42
|
+
text: string;
|
|
43
|
+
replaced: boolean;
|
|
44
|
+
};
|
|
45
|
+
export declare const withAgentsBlock: (existing: string) => {
|
|
37
46
|
text: string;
|
|
38
47
|
replaced: boolean;
|
|
39
48
|
};
|
package/dist/init.js
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { existsSync } from 'node:fs';
|
|
1
|
+
import { existsSync, statSync } from 'node:fs';
|
|
2
2
|
import { mkdir, readFile, writeFile } from 'node:fs/promises';
|
|
3
3
|
import path from 'node:path';
|
|
4
4
|
import fg from 'fast-glob';
|
|
@@ -27,24 +27,27 @@ Diagrams live in \`.diagrams/src/*.diagram.ts\` and are built with \`diagc\`.
|
|
|
27
27
|
- Run \`diagc publish <name>\` and look at \`.diagrams/static/<name>.png\` to check the picture.
|
|
28
28
|
${AGENTS_END}
|
|
29
29
|
`;
|
|
30
|
-
/**
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
30
|
+
/** Where the skill goes: the folder Claude Code reads a repository's skills from. */
|
|
31
|
+
export const SKILL_PATH = '.claude/skills/diagc/SKILL.md';
|
|
32
|
+
/** An earlier block: a begin marker, its end marker with no second begin between
|
|
33
|
+
* them, and the closing newline the block carries. A begin whose end was deleted
|
|
34
|
+
* by hand is not one — taking it up to the next block's end would delete
|
|
35
|
+
* whatever the user wrote in between. */
|
|
36
|
+
const EARLIER_BLOCK = new RegExp(`${AGENTS_BEGIN}(?:(?!${AGENTS_BEGIN})[\\s\\S])*?${AGENTS_END}\\n?`);
|
|
37
|
+
/** `existing` with `block` added at the end, or — when an earlier block is there —
|
|
38
|
+
* with that block replaced where it stands, so a second run never duplicates it
|
|
39
|
+
* and a run after an upgrade refreshes it. `block` runs from the begin marker to
|
|
40
|
+
* the newline after the end marker. */
|
|
41
|
+
export function withBlock(existing, block) {
|
|
42
|
+
// A function, so a `$&` in the block is text and not a back-reference.
|
|
43
|
+
if (EARLIER_BLOCK.test(existing))
|
|
44
|
+
return { text: existing.replace(EARLIER_BLOCK, () => block), replaced: true };
|
|
43
45
|
if (existing === '')
|
|
44
|
-
return { text:
|
|
46
|
+
return { text: block, replaced: false };
|
|
45
47
|
const sep = existing.endsWith('\n\n') ? '' : existing.endsWith('\n') ? '\n' : '\n\n';
|
|
46
|
-
return { text: `${existing}${sep}${
|
|
48
|
+
return { text: `${existing}${sep}${block}`, replaced: false };
|
|
47
49
|
}
|
|
50
|
+
export const withAgentsBlock = (existing) => withBlock(existing, AGENTS_BLOCK);
|
|
48
51
|
const COL = 38;
|
|
49
52
|
const done = (left, right) => `✓ ${left.padEnd(COL)}${right}`;
|
|
50
53
|
const skipped = (left, right) => `· ${left.padEnd(COL)}${right}`;
|
|
@@ -141,7 +144,41 @@ async function agentsStep(cwd, io) {
|
|
|
141
144
|
io.out(done(name, replaced ? '(diagc block refreshed)' : '(diagc block added)'));
|
|
142
145
|
}
|
|
143
146
|
}
|
|
144
|
-
/**
|
|
147
|
+
/** `.claude/` is Claude Code's own folder, not neutral ground like `AGENTS.md`, so
|
|
148
|
+
* the skill goes only where the repository already shows that tool in use. */
|
|
149
|
+
const usesClaudeCode = (cwd) => (statSync(path.join(cwd, '.claude'), { throwIfNoEntry: false })?.isDirectory() ?? false) || existsSync(path.join(cwd, 'CLAUDE.md'));
|
|
150
|
+
/** Everything step 4 has to read, read before the first write: an install that
|
|
151
|
+
* lost its skill is a refusal, and a refusal leaves the tree untouched. A new file
|
|
152
|
+
* is the shipped one, frontmatter and all; in a file that is already there only
|
|
153
|
+
* the text between the markers is diagc's, as in AGENTS.md. Undefined where the
|
|
154
|
+
* skill does not go. */
|
|
155
|
+
async function planSkill(opts) {
|
|
156
|
+
if (!opts.agents || !usesClaudeCode(opts.cwd))
|
|
157
|
+
return undefined;
|
|
158
|
+
if (!existsSync(opts.skillFile))
|
|
159
|
+
throw new InitError(`skill file missing from this install (${opts.skillFile}) — reinstall diagc.`);
|
|
160
|
+
const source = await readFile(opts.skillFile, 'utf8');
|
|
161
|
+
const begin = source.indexOf(AGENTS_BEGIN);
|
|
162
|
+
// The shipped file's own shape, held by skillContent.test.ts: a bug, not a refusal.
|
|
163
|
+
if (begin === -1)
|
|
164
|
+
throw new Error(`${opts.skillFile}: no ${AGENTS_BEGIN} marker`);
|
|
165
|
+
const file = path.join(opts.cwd, SKILL_PATH);
|
|
166
|
+
const existing = existsSync(file) ? await readFile(file, 'utf8') : '';
|
|
167
|
+
// An empty file has no frontmatter to keep: it gets the whole skill, as a new one does.
|
|
168
|
+
return existing.trim() === '' ? { text: source, replaced: false } : withBlock(existing, source.slice(begin));
|
|
169
|
+
}
|
|
170
|
+
/** Step 4: the Claude Code skill, with `--agents`. */
|
|
171
|
+
async function skillStep(cwd, plan, io) {
|
|
172
|
+
if (plan === undefined) {
|
|
173
|
+
io.out(skipped(SKILL_PATH, 'no .claude/ or CLAUDE.md here — skill skipped'));
|
|
174
|
+
return;
|
|
175
|
+
}
|
|
176
|
+
const file = path.join(cwd, SKILL_PATH);
|
|
177
|
+
await mkdir(path.dirname(file), { recursive: true });
|
|
178
|
+
await writeFile(file, plan.text);
|
|
179
|
+
io.out(done(SKILL_PATH, plan.replaced ? '(diagc skill refreshed)' : '(diagc skill added)'));
|
|
180
|
+
}
|
|
181
|
+
/** Step 5: compile what was written, so the user starts from a diagram that is
|
|
145
182
|
* known to build and sees where the artifact went. */
|
|
146
183
|
async function compileStep(file, opts, io) {
|
|
147
184
|
let artifact;
|
|
@@ -157,7 +194,7 @@ async function compileStep(file, opts, io) {
|
|
|
157
194
|
}
|
|
158
195
|
io.out(done('compiled', `-> ${path.relative(opts.cwd, artifact).split(path.sep).join('/')}`));
|
|
159
196
|
}
|
|
160
|
-
/** Step
|
|
197
|
+
/** Step 6: what to do now. The `--agents` line goes when `--agents` was given; the
|
|
161
198
|
* install hint only where there is a `package.json` to install into. */
|
|
162
199
|
function nextSteps(opts) {
|
|
163
200
|
const lines = [
|
|
@@ -165,7 +202,7 @@ function nextSteps(opts) {
|
|
|
165
202
|
['diagc guide', 'how to write diagrams (for you or your agent)'],
|
|
166
203
|
];
|
|
167
204
|
if (!opts.agents)
|
|
168
|
-
lines.push(['diagc init --agents', 'point coding agents at the guide (AGENTS.md)']);
|
|
205
|
+
lines.push(['diagc init --agents', 'point coding agents at the guide (AGENTS.md, Claude Code skill)']);
|
|
169
206
|
if (existsSync(path.join(opts.cwd, 'package.json')))
|
|
170
207
|
lines.push([`npm i -D @diagc/core@${opts.version}`, 'editor types for .diagram.ts']);
|
|
171
208
|
return `\nNext:\n${lines.map(([cmd, what]) => ` ${cmd.padEnd(COL)}${what}`).join('\n')}`;
|
|
@@ -178,10 +215,13 @@ const stdio = {
|
|
|
178
215
|
* line on stderr; anything else is a bug and is left to throw. */
|
|
179
216
|
export async function runInit(opts, io = stdio) {
|
|
180
217
|
try {
|
|
218
|
+
const skill = await planSkill(opts);
|
|
181
219
|
const written = await starterStep(opts, io);
|
|
182
220
|
await gitignoreStep(opts.cwd, io);
|
|
183
|
-
if (opts.agents)
|
|
221
|
+
if (opts.agents) {
|
|
184
222
|
await agentsStep(opts.cwd, io);
|
|
223
|
+
await skillStep(opts.cwd, skill, io);
|
|
224
|
+
}
|
|
185
225
|
if (written !== undefined)
|
|
186
226
|
await compileStep(written, opts, io);
|
|
187
227
|
io.out(nextSteps(opts));
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@diagc/cli",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.13.0",
|
|
4
4
|
"description": "Author software-architecture diagrams as code, compile them to a validated model, edit them in a local studio, and publish pages and images.",
|
|
5
5
|
"license": "AGPL-3.0-only",
|
|
6
6
|
"author": "Bogdan Frankovskyi",
|
|
@@ -44,7 +44,7 @@
|
|
|
44
44
|
"fast-glob": "^3.3.0",
|
|
45
45
|
"jiti": "^2.0.0",
|
|
46
46
|
"playwright-core": "^1.62.0",
|
|
47
|
-
"@diagc/core": "0.
|
|
47
|
+
"@diagc/core": "0.13.0"
|
|
48
48
|
},
|
|
49
49
|
"publishConfig": {
|
|
50
50
|
"access": "public"
|