@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 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/html/` are build output.
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
 
@@ -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 -->
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
- /** `existing` with the block added at the end, or — when both markers are there —
34
- * with the earlier block replaced where it stands, so a second run never
35
- * duplicates it and a run after an upgrade refreshes it. */
36
- export declare function withAgentsBlock(existing: string): {
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
- /** `existing` with the block added at the end, or — when both markers are there —
31
- * with the earlier block replaced where it stands, so a second run never
32
- * duplicates it and a run after an upgrade refreshes it. */
33
- export function withAgentsBlock(existing) {
34
- const begin = existing.indexOf(AGENTS_BEGIN);
35
- const end = begin === -1 ? -1 : existing.indexOf(AGENTS_END, begin);
36
- if (begin !== -1 && end !== -1) {
37
- let after = end + AGENTS_END.length;
38
- // The block carries its own closing newline; take the old one with the old block.
39
- if (existing.startsWith('\n', after))
40
- after += 1;
41
- return { text: existing.slice(0, begin) + AGENTS_BLOCK + existing.slice(after), replaced: true };
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: AGENTS_BLOCK, replaced: false };
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}${AGENTS_BLOCK}`, replaced: false };
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
- /** Step 4: compile what was written, so the user starts from a diagram that is
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 5: what to do now. The `--agents` line goes when `--agents` was given; the
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.12.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.12.0"
47
+ "@diagc/core": "0.13.0"
48
48
  },
49
49
  "publishConfig": {
50
50
  "access": "public"