@diagc/cli 1.8.0 → 1.9.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 +1 -1
- package/assets/guide/compose.md +84 -0
- package/assets/guide/index.md +9 -1
- package/assets/skill/SKILL.md +2 -1
- package/assets/studio/assets/{index-DzVDK5uD.css → index-CAVbaTgv.css} +1 -1
- package/assets/studio/assets/index-Cgkqoymm.js +112 -0
- package/assets/studio/index.html +2 -2
- package/assets/viewer/shared/caveat-cyrillic-500-normal.woff +0 -0
- package/assets/viewer/shared/caveat-cyrillic-500-normal.woff2 +0 -0
- package/assets/viewer/shared/caveat-cyrillic-700-normal.woff +0 -0
- package/assets/viewer/shared/caveat-cyrillic-700-normal.woff2 +0 -0
- package/assets/viewer/shared/caveat-cyrillic-ext-500-normal.woff +0 -0
- package/assets/viewer/shared/caveat-cyrillic-ext-500-normal.woff2 +0 -0
- package/assets/viewer/shared/caveat-cyrillic-ext-700-normal.woff +0 -0
- package/assets/viewer/shared/caveat-cyrillic-ext-700-normal.woff2 +0 -0
- package/assets/viewer/shared/caveat-latin-500-normal.woff +0 -0
- package/assets/viewer/shared/caveat-latin-500-normal.woff2 +0 -0
- package/assets/viewer/shared/caveat-latin-700-normal.woff +0 -0
- package/assets/viewer/shared/caveat-latin-700-normal.woff2 +0 -0
- package/assets/viewer/shared/caveat-latin-ext-500-normal.woff +0 -0
- package/assets/viewer/shared/caveat-latin-ext-500-normal.woff2 +0 -0
- package/assets/viewer/shared/caveat-latin-ext-700-normal.woff +0 -0
- package/assets/viewer/shared/caveat-latin-ext-700-normal.woff2 +0 -0
- package/assets/viewer/shared/chakra-petch-latin-500-normal.woff2 +0 -0
- package/assets/viewer/shared/chakra-petch-latin-600-normal.woff2 +0 -0
- package/assets/viewer/shared/inter-latin-400-normal.woff2 +0 -0
- package/assets/viewer/shared/inter-latin-600-normal.woff2 +0 -0
- package/assets/viewer/shared/jetbrains-mono-latin-400-normal.woff2 +0 -0
- package/assets/viewer/shared/jetbrains-mono-latin-600-normal.woff2 +0 -0
- package/assets/viewer/shared/kalam-devanagari-400-normal.woff +0 -0
- package/assets/viewer/shared/kalam-devanagari-400-normal.woff2 +0 -0
- package/assets/viewer/shared/kalam-devanagari-700-normal.woff +0 -0
- package/assets/viewer/shared/kalam-devanagari-700-normal.woff2 +0 -0
- package/assets/viewer/shared/kalam-latin-400-normal.woff +0 -0
- package/assets/viewer/shared/kalam-latin-400-normal.woff2 +0 -0
- package/assets/viewer/shared/kalam-latin-700-normal.woff +0 -0
- package/assets/viewer/shared/kalam-latin-700-normal.woff2 +0 -0
- package/assets/viewer/shared/kalam-latin-ext-400-normal.woff +0 -0
- package/assets/viewer/shared/kalam-latin-ext-400-normal.woff2 +0 -0
- package/assets/viewer/shared/kalam-latin-ext-700-normal.woff +0 -0
- package/assets/viewer/shared/kalam-latin-ext-700-normal.woff2 +0 -0
- package/assets/viewer/shared/viewer.css +2 -0
- package/assets/viewer/shared/viewer.js +46 -0
- package/dist/api/diagrams.d.ts +20 -0
- package/dist/api/diagrams.js +69 -3
- package/dist/api/handlers.d.ts +1 -1
- package/dist/api/handlers.js +1 -1
- package/dist/api/routes.js +13 -0
- package/dist/cli/parse.d.ts +1 -0
- package/dist/cli/parse.js +1 -0
- package/dist/cli.js +2 -0
- package/dist/commands/compile.d.ts +1 -1
- package/dist/commands/compile.js +5 -6
- package/dist/commands/lint.js +4 -5
- package/dist/commands/publish.d.ts +1 -1
- package/dist/commands/publish.js +15 -7
- package/dist/commands/shared.d.ts +9 -0
- package/dist/commands/shared.js +30 -1
- package/dist/compile.d.ts +11 -1
- package/dist/compile.js +25 -6
- package/dist/guide.js +22 -10
- package/dist/home.d.ts +5 -1
- package/dist/home.js +2 -0
- package/dist/init.d.ts +1 -1
- package/dist/init.js +1 -1
- package/dist/lint.js +2 -1
- package/dist/loadHints.d.ts +8 -0
- package/dist/loadHints.js +36 -0
- package/dist/names.js +1 -1
- package/dist/publish/html.d.ts +13 -0
- package/dist/publish/html.js +54 -2
- package/dist/publish/publish.d.ts +10 -0
- package/dist/publish/publish.js +45 -23
- package/dist/publish/snapshot.d.ts +21 -2
- package/dist/publish/snapshot.js +95 -18
- package/dist/watch.js +23 -7
- package/package.json +2 -2
- package/assets/studio/assets/index-CB6jjAka.js +0 -112
package/dist/api/diagrams.d.ts
CHANGED
|
@@ -7,6 +7,10 @@ export interface DiagramEntry {
|
|
|
7
7
|
message: string;
|
|
8
8
|
}[];
|
|
9
9
|
editable: boolean;
|
|
10
|
+
/** the `.diagram.ts` a compiled diagram comes from, relative to the sources dir
|
|
11
|
+
* (`team/arch.diagram.ts`), when it is there: what the studio names on its
|
|
12
|
+
* read-only chip and opens on request */
|
|
13
|
+
source?: string;
|
|
10
14
|
}
|
|
11
15
|
/** Render-ready models for the studio boot: JSON sources (editable) served from
|
|
12
16
|
* `diagramsDir`, compiled TS artifacts from `artifactsDir`. A source shadows its
|
|
@@ -17,6 +21,13 @@ export declare function listDiagramModels(diagramsDir: string, artifactsDir: str
|
|
|
17
21
|
* spelling, is what keeps it inside the two directories: a compiled diagram's name
|
|
18
22
|
* comes from its `.diagram.ts` file and need not pass `isSafeName`. */
|
|
19
23
|
export declare function diagramAsShown(diagramsDir: string, artifactsDir: string, name: string): Promise<DiagramEntry | undefined>;
|
|
24
|
+
/** The TypeScript a compiled diagram comes from, as plain text: what the studio's
|
|
25
|
+
* read-only chip opens. Only `.diagram.ts` is served — a JSON source is the
|
|
26
|
+
* studio's own, read through `readDiagram`. */
|
|
27
|
+
export declare function readDiagramSource(diagramsDir: string, name: string): Promise<HandlerResult & {
|
|
28
|
+
bytes?: Buffer;
|
|
29
|
+
contentType?: string;
|
|
30
|
+
}>;
|
|
20
31
|
/** the JSON source (+ sibling layout and drawings) of a designer-owned diagram — the studio
|
|
21
32
|
* reads these directly so it never depends on a compile watcher for its own files */
|
|
22
33
|
export declare function readDiagram(diagramsDir: string, name: string): Promise<HandlerResult>;
|
|
@@ -27,6 +38,15 @@ export declare function saveDiagram(diagramsDir: string, name: string, payload:
|
|
|
27
38
|
/** Move a designer-owned diagram (and its sibling layout, if any) to a new name,
|
|
28
39
|
* rewriting the model's id to match so the file stays self-consistent. */
|
|
29
40
|
export declare function renameDiagram(diagramsDir: string, from: string, to: string): Promise<HandlerResult>;
|
|
41
|
+
/**
|
|
42
|
+
* Remove a studio-owned diagram: its JSON source, its layout and drawings sidecars,
|
|
43
|
+
* and its compiled artifact — the watcher's copy, which would otherwise list the
|
|
44
|
+
* diagram again, read-only, the next time the studio starts without a watcher
|
|
45
|
+
* having seen the deletion. A diagram with a `.diagram.ts` is TypeScript's: the
|
|
46
|
+
* studio never offers to delete it, and the route refuses too (409). Published
|
|
47
|
+
* pages and PNGs are left where they are; `diagc publish` regenerates them.
|
|
48
|
+
*/
|
|
49
|
+
export declare function deleteDiagram(diagramsDir: string, artifactsDir: string, name: string): Promise<HandlerResult>;
|
|
30
50
|
/** Promote a JSON-owned diagram to a generated `.diagram.ts`. See `ejectDiagram`
|
|
31
51
|
* for the round-trip guarantee; this just maps its failure codes to statuses. */
|
|
32
52
|
export declare function ejectDiagramSource(diagramsDir: string, artifactsDir: string, name: string): Promise<HandlerResult>;
|
package/dist/api/diagrams.js
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { access, mkdir, readFile, rename, unlink } from 'node:fs/promises';
|
|
1
|
+
import { access, mkdir, readFile, rename, rm, unlink } from 'node:fs/promises';
|
|
2
2
|
import path from 'node:path';
|
|
3
3
|
import { composeIncludes, errMessage, validate } from '@diagc/core/internal';
|
|
4
4
|
import { writeFileAtomic } from '../atomic-write.js';
|
|
@@ -42,9 +42,12 @@ async function loadEntry(diagramsDir, artifactsDir, name, isSource) {
|
|
|
42
42
|
const issues = [];
|
|
43
43
|
if (isSource && !editable) {
|
|
44
44
|
issues.push({
|
|
45
|
-
message: `'${name}' is read-only here: the studio saves names of lowercase letters, digits, '-' and '/', none ending in /rename, /eject or /
|
|
45
|
+
message: `'${name}' is read-only here: the studio saves names of lowercase letters, digits, '-' and '/', none ending in /rename, /eject, /composed or /source. Rename the file to edit it.`,
|
|
46
46
|
});
|
|
47
47
|
}
|
|
48
|
+
// A compiled diagram names the TypeScript it comes from, when it is beside the
|
|
49
|
+
// sources: an artifact with no source here (a build output copied in) names none.
|
|
50
|
+
const source = isSource ? undefined : await tsSourceOf(diagramsDir, name);
|
|
48
51
|
try {
|
|
49
52
|
model = JSON.parse(await readFile(file, 'utf8'));
|
|
50
53
|
}
|
|
@@ -53,7 +56,32 @@ async function loadEntry(diagramsDir, artifactsDir, name, isSource) {
|
|
|
53
56
|
}
|
|
54
57
|
if (isSource && hasIncludes(model))
|
|
55
58
|
model = await composedForList(model, file, diagramsDir, issues);
|
|
56
|
-
return { name, model, issues, editable };
|
|
59
|
+
return { name, model, issues, editable, ...(source !== undefined ? { source } : {}) };
|
|
60
|
+
}
|
|
61
|
+
/** `<name>.diagram.ts` relative to `diagramsDir` when that file exists, else undefined. */
|
|
62
|
+
async function tsSourceOf(diagramsDir, name) {
|
|
63
|
+
const rel = `${name}.diagram.ts`;
|
|
64
|
+
try {
|
|
65
|
+
await access(path.join(diagramsDir, rel));
|
|
66
|
+
return rel;
|
|
67
|
+
}
|
|
68
|
+
catch {
|
|
69
|
+
return undefined;
|
|
70
|
+
}
|
|
71
|
+
}
|
|
72
|
+
/** The TypeScript a compiled diagram comes from, as plain text: what the studio's
|
|
73
|
+
* read-only chip opens. Only `.diagram.ts` is served — a JSON source is the
|
|
74
|
+
* studio's own, read through `readDiagram`. */
|
|
75
|
+
export async function readDiagramSource(diagramsDir, name) {
|
|
76
|
+
if (!isSafeName(name))
|
|
77
|
+
return refuse(400, `Unsafe name '${name}'`);
|
|
78
|
+
try {
|
|
79
|
+
const bytes = await readFile(path.join(diagramsDir, `${name}.diagram.ts`));
|
|
80
|
+
return { status: 200, body: undefined, bytes, contentType: 'text/plain; charset=utf-8' };
|
|
81
|
+
}
|
|
82
|
+
catch {
|
|
83
|
+
return refuse(404, `No TypeScript source '${name}'`);
|
|
84
|
+
}
|
|
57
85
|
}
|
|
58
86
|
/** `model` with its includes expanded for the list, or `model` itself when they
|
|
59
87
|
* cannot be, with what went wrong added to `issues`. */
|
|
@@ -263,6 +291,44 @@ async function moveIfPresent(src, dst) {
|
|
|
263
291
|
throw e;
|
|
264
292
|
}
|
|
265
293
|
}
|
|
294
|
+
/**
|
|
295
|
+
* Remove a studio-owned diagram: its JSON source, its layout and drawings sidecars,
|
|
296
|
+
* and its compiled artifact — the watcher's copy, which would otherwise list the
|
|
297
|
+
* diagram again, read-only, the next time the studio starts without a watcher
|
|
298
|
+
* having seen the deletion. A diagram with a `.diagram.ts` is TypeScript's: the
|
|
299
|
+
* studio never offers to delete it, and the route refuses too (409). Published
|
|
300
|
+
* pages and PNGs are left where they are; `diagc publish` regenerates them.
|
|
301
|
+
*/
|
|
302
|
+
export async function deleteDiagram(diagramsDir, artifactsDir, name) {
|
|
303
|
+
if (!isSafeName(name))
|
|
304
|
+
return refuse(400, `Unsafe name '${name}'`);
|
|
305
|
+
const tsPath = path.join(diagramsDir, `${name}.diagram.ts`);
|
|
306
|
+
try {
|
|
307
|
+
await access(tsPath);
|
|
308
|
+
return refuse(409, `'${name}' is TypeScript-owned (${tsPath}) — delete its source`);
|
|
309
|
+
}
|
|
310
|
+
catch {
|
|
311
|
+
/* no TypeScript source — the studio's to delete */
|
|
312
|
+
}
|
|
313
|
+
const source = path.join(diagramsDir, `${name}.diagram.json`);
|
|
314
|
+
try {
|
|
315
|
+
await access(source);
|
|
316
|
+
}
|
|
317
|
+
catch {
|
|
318
|
+
return refuse(404, `No diagram source '${name}'`);
|
|
319
|
+
}
|
|
320
|
+
// The sidecars and the artifact first, the source last: a failure part-way
|
|
321
|
+
// leaves a diagram the studio still lists and can retry on.
|
|
322
|
+
for (const file of [
|
|
323
|
+
path.join(diagramsDir, `${name}.layout.json`),
|
|
324
|
+
path.join(diagramsDir, `${name}.drawings.json`),
|
|
325
|
+
path.join(artifactsDir, `${name}.diagram.json`),
|
|
326
|
+
]) {
|
|
327
|
+
await rm(file, { force: true });
|
|
328
|
+
}
|
|
329
|
+
await unlink(source);
|
|
330
|
+
return { status: 200, body: { ok: true } };
|
|
331
|
+
}
|
|
266
332
|
/** Promote a JSON-owned diagram to a generated `.diagram.ts`. See `ejectDiagram`
|
|
267
333
|
* for the round-trip guarantee; this just maps its failure codes to statuses. */
|
|
268
334
|
export async function ejectDiagramSource(diagramsDir, artifactsDir, name) {
|
package/dist/api/handlers.d.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
export { MAX_ASSET_BYTES, readAsset, saveAsset } from './assets.js';
|
|
2
|
-
export { ejectDiagramSource, listDiagramModels, readComposedDiagram, readDiagram, renameDiagram, saveDiagram, type DiagramEntry, } from './diagrams.js';
|
|
2
|
+
export { deleteDiagram, ejectDiagramSource, listDiagramModels, readComposedDiagram, readDiagram, readDiagramSource, renameDiagram, saveDiagram, type DiagramEntry, } from './diagrams.js';
|
|
3
3
|
export { walkDiagramJson, walkFiles } from './files.js';
|
|
4
4
|
export { readLibrary, saveLibrary } from './library.js';
|
|
5
5
|
export { exportPage } from './pages.js';
|
package/dist/api/handlers.js
CHANGED
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
// the Obsidian vault host imports the file by path. So each export is named, and a
|
|
4
4
|
// helper one subject module exports to another does not become part of that type.
|
|
5
5
|
export { MAX_ASSET_BYTES, readAsset, saveAsset } from './assets.js';
|
|
6
|
-
export { ejectDiagramSource, listDiagramModels, readComposedDiagram, readDiagram, renameDiagram, saveDiagram, } from './diagrams.js';
|
|
6
|
+
export { deleteDiagram, ejectDiagramSource, listDiagramModels, readComposedDiagram, readDiagram, readDiagramSource, renameDiagram, saveDiagram, } from './diagrams.js';
|
|
7
7
|
export { walkDiagramJson, walkFiles } from './files.js';
|
|
8
8
|
export { readLibrary, saveLibrary } from './library.js';
|
|
9
9
|
export { exportPage } from './pages.js';
|
package/dist/api/routes.js
CHANGED
|
@@ -36,11 +36,24 @@ export const ROUTES = [
|
|
|
36
36
|
pattern: /^\/api\/diagrams\/(.+)\/composed$/,
|
|
37
37
|
handler: (h, c) => h.readComposedDiagram(c.diagramsDir, decodeURIComponent(c.match[1] ?? '')),
|
|
38
38
|
},
|
|
39
|
+
// The TypeScript a compiled diagram comes from, as text. Before the generic read
|
|
40
|
+
// for the same reason as the composed one.
|
|
41
|
+
{
|
|
42
|
+
method: 'GET',
|
|
43
|
+
pattern: /^\/api\/diagrams\/(.+)\/source$/,
|
|
44
|
+
handler: (h, c) => h.readDiagramSource(c.diagramsDir, decodeURIComponent(c.match[1] ?? '')),
|
|
45
|
+
},
|
|
39
46
|
{
|
|
40
47
|
method: 'GET',
|
|
41
48
|
pattern: /^\/api\/diagrams\/(.+)$/,
|
|
42
49
|
handler: (h, c) => h.readDiagram(c.diagramsDir, decodeURIComponent(c.match[1] ?? '')),
|
|
43
50
|
},
|
|
51
|
+
// A diagram the studio owns, with its sidecars and its compiled artifact.
|
|
52
|
+
{
|
|
53
|
+
method: 'DELETE',
|
|
54
|
+
pattern: /^\/api\/diagrams\/(.+)$/,
|
|
55
|
+
handler: (h, c) => h.deleteDiagram(c.diagramsDir, c.artifactsDir, decodeURIComponent(c.match[1] ?? '')),
|
|
56
|
+
},
|
|
44
57
|
// Rename must be checked before the generic save route, whose `(.+)`
|
|
45
58
|
// would otherwise swallow `<from>/rename` as a filename.
|
|
46
59
|
{
|
package/dist/cli/parse.d.ts
CHANGED
package/dist/cli/parse.js
CHANGED
|
@@ -121,6 +121,7 @@ const FLAGS = {
|
|
|
121
121
|
'--ascii': null,
|
|
122
122
|
'--color': null,
|
|
123
123
|
'--no-color': null,
|
|
124
|
+
'--single-file': null,
|
|
124
125
|
};
|
|
125
126
|
const isFlag = (arg) => Object.hasOwn(FLAGS, arg);
|
|
126
127
|
/** Read argv against every flag there is, whichever command it names: which arguments
|
package/dist/cli.js
CHANGED
|
@@ -48,6 +48,8 @@ Options:
|
|
|
48
48
|
--out dir Artifact output directory (default .diagrams/.artifacts;
|
|
49
49
|
diff: .diagrams/diff/<from>..<to>)
|
|
50
50
|
--no-images Publish (or diff) HTML without rendering PNG images
|
|
51
|
+
--single-file Publish every page whole, the viewer inside it, as a file to send
|
|
52
|
+
on its own (default: the pages share one diagc-viewer/ folder)
|
|
51
53
|
--link url Publish with a link to url in the index header
|
|
52
54
|
--style id Publish: take the PNGs in this style preset (clean, sketch, …) in
|
|
53
55
|
place of each diagram's own; tui: draw every diagram in dos or clean
|
|
@@ -1,3 +1,3 @@
|
|
|
1
1
|
import type { Command } from '../cli/command.js';
|
|
2
|
-
/** `diagc compile [files...]`: the files named, or every source, into artifacts. */
|
|
2
|
+
/** `diagc compile [files...]`: the files or diagrams named, or every source, into artifacts. */
|
|
3
3
|
export declare const compile: Command<'--out' | '--update-includes'>;
|
package/dist/commands/compile.js
CHANGED
|
@@ -1,16 +1,15 @@
|
|
|
1
1
|
import { errMessage } from '@diagc/core/internal';
|
|
2
2
|
import { compileFile } from '../compile.js';
|
|
3
|
-
import { globSorted } from '../glob.js';
|
|
4
3
|
import { RELATIVE_PATHS } from '../paths.js';
|
|
5
4
|
import { formatCompileEvent } from '../watch.js';
|
|
6
|
-
import {
|
|
7
|
-
/** `diagc compile [files...]`: the files named, or every source, into artifacts. */
|
|
5
|
+
import { resolveSources } from './shared.js';
|
|
6
|
+
/** `diagc compile [files...]`: the files or diagrams named, or every source, into artifacts. */
|
|
8
7
|
export const compile = {
|
|
9
8
|
flags: ['--out', '--update-includes'],
|
|
10
9
|
async run({ positionals, flags }, { io, home, snapshots }) {
|
|
11
|
-
const files =
|
|
12
|
-
if (
|
|
13
|
-
|
|
10
|
+
const files = await resolveSources(io, positionals);
|
|
11
|
+
if (files === undefined)
|
|
12
|
+
return 1;
|
|
14
13
|
let failed = false;
|
|
15
14
|
for (const file of files) {
|
|
16
15
|
try {
|
package/dist/commands/lint.js
CHANGED
|
@@ -1,14 +1,13 @@
|
|
|
1
1
|
import { formatLintReport, lintFile } from '../lint.js';
|
|
2
|
-
import { globSorted } from '../glob.js';
|
|
3
2
|
import { RELATIVE_PATHS } from '../paths.js';
|
|
4
|
-
import {
|
|
3
|
+
import { resolveSources } from './shared.js';
|
|
5
4
|
/** `diagc lint [files...] [--json]`: every finding, and exit 1 on any. */
|
|
6
5
|
export const lint = {
|
|
7
6
|
flags: ['--json'],
|
|
8
7
|
async run({ positionals, flags }, { io, home, snapshots }) {
|
|
9
|
-
const files =
|
|
10
|
-
if (
|
|
11
|
-
|
|
8
|
+
const files = await resolveSources(io, positionals);
|
|
9
|
+
if (files === undefined)
|
|
10
|
+
return 1;
|
|
12
11
|
const reports = [];
|
|
13
12
|
for (const file of files) {
|
|
14
13
|
reports.push(...(await lintFile(file, {
|
|
@@ -7,5 +7,5 @@ type PublishDirs = Pick<PublishOptions, 'srcDir' | 'artifactsDir' | 'htmlDir' |
|
|
|
7
7
|
* that embed them expect to find them. */
|
|
8
8
|
export declare function publishDirs(out: string): PublishDirs;
|
|
9
9
|
/** `diagc publish [names...]`: compile, then a page per diagram, the gallery, and PNGs. */
|
|
10
|
-
export declare const publish: Command<'--out' | '--no-images' | '--link' | '--update-includes' | '--style' | '--theme'>;
|
|
10
|
+
export declare const publish: Command<'--out' | '--no-images' | '--link' | '--update-includes' | '--style' | '--theme' | '--single-file'>;
|
|
11
11
|
export {};
|
package/dist/commands/publish.js
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import { existsSync } from 'node:fs';
|
|
2
|
+
import path from 'node:path';
|
|
2
3
|
import { errMessage } from '@diagc/core/internal';
|
|
3
4
|
import { compileFile } from '../compile.js';
|
|
4
5
|
import { globSorted } from '../glob.js';
|
|
@@ -40,16 +41,19 @@ async function compileSources(dirs, { io, home, snapshots }) {
|
|
|
40
41
|
}
|
|
41
42
|
/** `diagc publish [names...]`: compile, then a page per diagram, the gallery, and PNGs. */
|
|
42
43
|
export const publish = {
|
|
43
|
-
flags: ['--out', '--no-images', '--link', '--update-includes', '--style', '--theme'],
|
|
44
|
+
flags: ['--out', '--no-images', '--link', '--update-includes', '--style', '--theme', '--single-file'],
|
|
44
45
|
async run({ positionals, flags }, ctx) {
|
|
45
46
|
const { io, home, snapshots } = ctx;
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
47
|
+
const singleFile = flags['--single-file'] === true;
|
|
48
|
+
// The shell for whole pages, the folder for pages that share the viewer: one
|
|
49
|
+
// build makes both. Only a checkout can be missing them; an installed package
|
|
50
|
+
// ships both, so there the message would send the reader off to build a repo
|
|
51
|
+
// they do not have.
|
|
52
|
+
const needed = singleFile ? home.viewerShell : path.join(home.viewerDir, 'viewer.js');
|
|
53
|
+
if (!existsSync(needed)) {
|
|
50
54
|
io.err(home.layout === 'monorepo'
|
|
51
|
-
? 'viewer
|
|
52
|
-
: `viewer
|
|
55
|
+
? 'viewer not built — run `pnpm --filter @diagc/viewer build` in the monorepo.'
|
|
56
|
+
: `viewer missing from this install (${needed}) — reinstall diagc.`);
|
|
53
57
|
return 1;
|
|
54
58
|
}
|
|
55
59
|
const dirs = publishDirs(flags['--out'] ?? RELATIVE_PATHS.artifactsDir);
|
|
@@ -67,6 +71,8 @@ export const publish = {
|
|
|
67
71
|
const res = await publishDiagrams({
|
|
68
72
|
...dirs,
|
|
69
73
|
shellPath: home.viewerShell,
|
|
74
|
+
viewerDir: home.viewerDir,
|
|
75
|
+
singleFile,
|
|
70
76
|
libraryDir: home.libraryDir,
|
|
71
77
|
images: renderPng !== undefined,
|
|
72
78
|
names,
|
|
@@ -80,6 +86,8 @@ export const publish = {
|
|
|
80
86
|
warn: io.err,
|
|
81
87
|
});
|
|
82
88
|
io.out(`✓ ${res.pages.length} page(s) -> ${dirs.htmlDir}`);
|
|
89
|
+
if (res.viewer !== undefined)
|
|
90
|
+
io.out(`✓ viewer -> ${res.viewer}`);
|
|
83
91
|
if (res.images.length > 0)
|
|
84
92
|
io.out(`✓ ${res.images.length} image(s) -> ${dirs.staticDir}`);
|
|
85
93
|
io.out(`✓ gallery -> ${res.gallery}`);
|
|
@@ -17,6 +17,15 @@ export declare function diagramNames(io: CliIo, files: readonly string[], known:
|
|
|
17
17
|
* says so on stderr, and the pages go out as HTML only. Playwright loads only when a
|
|
18
18
|
* picture is wanted. */
|
|
19
19
|
export declare function pngRenderer(io: CliIo, images: boolean): Promise<NonNullable<PublishOptions['renderPng']> | undefined>;
|
|
20
|
+
/**
|
|
21
|
+
* The sources `compile` and `lint` read for `files...`: a path as given, or a
|
|
22
|
+
* diagram name read as `publish` reads one (`shop` is `.diagrams/src/shop.diagram.ts`,
|
|
23
|
+
* else its `.diagram.json`). None given means every source, in path order, with
|
|
24
|
+
* the no-sources warning when there is none. An argument that is neither a file
|
|
25
|
+
* nor a diagram is one line on stderr each, and the result is then undefined: an
|
|
26
|
+
* empty selection would look like nothing to do.
|
|
27
|
+
*/
|
|
28
|
+
export declare function resolveSources(io: CliIo, args: readonly string[]): Promise<string[] | undefined>;
|
|
20
29
|
/** The source a diagram name reads from: its `.diagram.ts`, else its `.diagram.json`;
|
|
21
30
|
* undefined when it has neither. TypeScript first, as the hand-written one of the two
|
|
22
31
|
* (a `.diagram.json` beside it is the studio's, or a leftover from an eject). */
|
package/dist/commands/shared.js
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import { existsSync } from 'node:fs';
|
|
2
2
|
import path from 'node:path';
|
|
3
|
+
import { globSorted } from '../glob.js';
|
|
3
4
|
import { diagramName } from '../names.js';
|
|
4
5
|
import { RELATIVE_PATHS } from '../paths.js';
|
|
5
6
|
/** The sources compile and lint read when they are named none. */
|
|
@@ -29,11 +30,39 @@ export async function pngRenderer(io, images) {
|
|
|
29
30
|
return undefined;
|
|
30
31
|
const snapshot = await import('../publish/snapshot.js');
|
|
31
32
|
if (snapshot.findChrome() === undefined) {
|
|
32
|
-
io.err(
|
|
33
|
+
io.err(snapshot.NO_CHROME_MESSAGE);
|
|
33
34
|
return undefined;
|
|
34
35
|
}
|
|
35
36
|
return snapshot.renderPng;
|
|
36
37
|
}
|
|
38
|
+
/**
|
|
39
|
+
* The sources `compile` and `lint` read for `files...`: a path as given, or a
|
|
40
|
+
* diagram name read as `publish` reads one (`shop` is `.diagrams/src/shop.diagram.ts`,
|
|
41
|
+
* else its `.diagram.json`). None given means every source, in path order, with
|
|
42
|
+
* the no-sources warning when there is none. An argument that is neither a file
|
|
43
|
+
* nor a diagram is one line on stderr each, and the result is then undefined: an
|
|
44
|
+
* empty selection would look like nothing to do.
|
|
45
|
+
*/
|
|
46
|
+
export async function resolveSources(io, args) {
|
|
47
|
+
if (args.length === 0) {
|
|
48
|
+
const files = await globSorted(SOURCES);
|
|
49
|
+
if (files.length === 0)
|
|
50
|
+
warnNoSources(io);
|
|
51
|
+
return files;
|
|
52
|
+
}
|
|
53
|
+
const files = [];
|
|
54
|
+
let unknown = false;
|
|
55
|
+
for (const arg of args) {
|
|
56
|
+
const file = existsSync(arg) ? arg : sourceOf(diagramName(arg));
|
|
57
|
+
if (file === undefined) {
|
|
58
|
+
unknown = true;
|
|
59
|
+
io.err(`diagc: no diagram '${arg}' — not a file, and nothing under ${RELATIVE_PATHS.srcDir} is named that`);
|
|
60
|
+
continue;
|
|
61
|
+
}
|
|
62
|
+
files.push(file);
|
|
63
|
+
}
|
|
64
|
+
return unknown ? undefined : files;
|
|
65
|
+
}
|
|
37
66
|
/** The source a diagram name reads from: its `.diagram.ts`, else its `.diagram.json`;
|
|
38
67
|
* undefined when it has neither. TypeScript first, as the hand-written one of the two
|
|
39
68
|
* (a `.diagram.json` beside it is the studio's, or a leftover from an eject). */
|
package/dist/compile.d.ts
CHANGED
|
@@ -10,12 +10,18 @@ import { type DiagramModel, type IncludeResolver } from '@diagc/core/internal';
|
|
|
10
10
|
export declare class LoadError extends Error {
|
|
11
11
|
readonly file: string;
|
|
12
12
|
readonly reason: string;
|
|
13
|
+
/** the rule a builder refusal names (`missing-kind`); undefined for a source
|
|
14
|
+
* that simply threw, which lint reports as `load` */
|
|
15
|
+
readonly code?: string | undefined;
|
|
13
16
|
readonly line: number | undefined;
|
|
14
17
|
readonly column: number | undefined;
|
|
15
18
|
constructor(file: string, reason: string, position?: {
|
|
16
19
|
line: number;
|
|
17
20
|
column: number;
|
|
18
|
-
}
|
|
21
|
+
},
|
|
22
|
+
/** the rule a builder refusal names (`missing-kind`); undefined for a source
|
|
23
|
+
* that simply threw, which lint reports as `load` */
|
|
24
|
+
code?: string | undefined);
|
|
19
25
|
}
|
|
20
26
|
/** The line and column of the first `at` frame inside `file`. Matched on the
|
|
21
27
|
* basename after a path separator: a frame spells the path as it was imported,
|
|
@@ -46,4 +52,8 @@ export interface LoadOptions {
|
|
|
46
52
|
* model `compile` writes and `lint` inspects. Throws on anything invalid.
|
|
47
53
|
*/
|
|
48
54
|
export declare function loadModel(file: string, opts?: LoadOptions): Promise<DiagramModel>;
|
|
55
|
+
/** Where `file` compiles to under `outDir`: its name as `.diagram.json`, in the
|
|
56
|
+
* subdirectory it has under `rootDir`. The watcher removes the same path when the
|
|
57
|
+
* source goes. */
|
|
58
|
+
export declare function artifactPathFor(file: string, outDir: string, rootDir?: string): string;
|
|
49
59
|
export declare function compileFile(file: string, outDir: string, opts?: LoadOptions): Promise<string>;
|
package/dist/compile.js
CHANGED
|
@@ -4,6 +4,7 @@ import path from 'node:path';
|
|
|
4
4
|
import { createJiti } from 'jiti';
|
|
5
5
|
import { composeIncludes, DiagramValidationError, diagramWarnings, errMessage, validate, } from '@diagc/core/internal';
|
|
6
6
|
import { resolveInclude } from './includes.js';
|
|
7
|
+
import { loadHint } from './loadHints.js';
|
|
7
8
|
import { lockedResolverFor } from './snapshots.js';
|
|
8
9
|
/**
|
|
9
10
|
* Shape guard: with `{ default: true }` jiti returns the module NAMESPACE when
|
|
@@ -29,17 +30,30 @@ function assertDiagramShape(model, file) {
|
|
|
29
30
|
export class LoadError extends Error {
|
|
30
31
|
file;
|
|
31
32
|
reason;
|
|
33
|
+
code;
|
|
32
34
|
line;
|
|
33
35
|
column;
|
|
34
|
-
constructor(file, reason, position
|
|
36
|
+
constructor(file, reason, position,
|
|
37
|
+
/** the rule a builder refusal names (`missing-kind`); undefined for a source
|
|
38
|
+
* that simply threw, which lint reports as `load` */
|
|
39
|
+
code) {
|
|
35
40
|
super(position !== undefined ? `${file}:${position.line}:${position.column}: ${reason}` : reason);
|
|
36
41
|
this.file = file;
|
|
37
42
|
this.reason = reason;
|
|
43
|
+
this.code = code;
|
|
38
44
|
this.name = 'LoadError';
|
|
39
45
|
this.line = position?.line;
|
|
40
46
|
this.column = position?.column;
|
|
41
47
|
}
|
|
42
48
|
}
|
|
49
|
+
/** The code a builder refusal carries, or undefined for any other error. By name,
|
|
50
|
+
* not instanceof: the diagram ran in jiti's own copy of core. */
|
|
51
|
+
function builderCode(e) {
|
|
52
|
+
if (!(e instanceof Error) || e.name !== 'BuilderError')
|
|
53
|
+
return undefined;
|
|
54
|
+
const code = e.code;
|
|
55
|
+
return typeof code === 'string' ? code : undefined;
|
|
56
|
+
}
|
|
43
57
|
/** The line and column of the first `at` frame inside `file`. Matched on the
|
|
44
58
|
* basename after a path separator: a frame spells the path as it was imported,
|
|
45
59
|
* which a symlinked temp dir would not equal; the message line is skipped because
|
|
@@ -80,7 +94,7 @@ export async function executeDiagramTs(file, coreEntry) {
|
|
|
80
94
|
// `issues` by name. Everything else is the source failing to run.
|
|
81
95
|
if (e instanceof Error && e.name === 'DiagramValidationError')
|
|
82
96
|
throw e;
|
|
83
|
-
throw new LoadError(file, errMessage(e), positionIn(e instanceof Error ? e.stack : undefined, file));
|
|
97
|
+
throw new LoadError(file, loadHint(errMessage(e)), positionIn(e instanceof Error ? e.stack : undefined, file), builderCode(e));
|
|
84
98
|
}
|
|
85
99
|
const hasToJSON = typeof def?.toJSON === 'function';
|
|
86
100
|
const model = (hasToJSON ? def.toJSON() : def);
|
|
@@ -150,6 +164,13 @@ export async function loadModel(file, opts) {
|
|
|
150
164
|
}
|
|
151
165
|
return model;
|
|
152
166
|
}
|
|
167
|
+
/** Where `file` compiles to under `outDir`: its name as `.diagram.json`, in the
|
|
168
|
+
* subdirectory it has under `rootDir`. The watcher removes the same path when the
|
|
169
|
+
* source goes. */
|
|
170
|
+
export function artifactPathFor(file, outDir, rootDir) {
|
|
171
|
+
const base = path.basename(file).replace(/\.diagram\.(ts|json)$/, '');
|
|
172
|
+
return path.join(outDir, relativeSubdir(file, rootDir), `${base}.diagram.json`);
|
|
173
|
+
}
|
|
153
174
|
export async function compileFile(file, outDir, opts) {
|
|
154
175
|
const model = await loadModel(file, opts);
|
|
155
176
|
// Sound but probably not what was meant (a fishbone cause on no bone, a typo'd
|
|
@@ -157,10 +178,8 @@ export async function compileFile(file, outDir, opts) {
|
|
|
157
178
|
// complaint. `diagc lint` is the strict reading of the same list.
|
|
158
179
|
for (const w of diagramWarnings(model))
|
|
159
180
|
(opts?.warn ?? console.warn)(`${file}: ${w.message}`);
|
|
160
|
-
const
|
|
161
|
-
|
|
162
|
-
await mkdir(artifactDir, { recursive: true });
|
|
163
|
-
const artifact = path.join(artifactDir, `${base}.diagram.json`);
|
|
181
|
+
const artifact = artifactPathFor(file, outDir, opts?.rootDir);
|
|
182
|
+
await mkdir(path.dirname(artifact), { recursive: true });
|
|
164
183
|
await writeFile(artifact, `${JSON.stringify(model, null, 2)}\n`);
|
|
165
184
|
return artifact;
|
|
166
185
|
}
|
package/dist/guide.js
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
import { existsSync, readdirSync, readFileSync } from 'node:fs';
|
|
2
2
|
import path from 'node:path';
|
|
3
3
|
import { NODE_TYPES, NOTATION_NODE_TYPES, NOTATION_RELATION_KINDS, RELATION_KINDS } from '@diagc/core/internal';
|
|
4
|
-
import { UnknownStarterError, readStarter } from './starters.js';
|
|
4
|
+
import { UnknownStarterError, readStarter, starterTypes } from './starters.js';
|
|
5
5
|
const INDEX = 'index';
|
|
6
6
|
/** `diagc guide all`: the index, then every topic — for a reader who cannot ask
|
|
7
7
|
* for one (the copy published on the website). */
|
|
@@ -62,17 +62,27 @@ function nodeTypesFor(page) {
|
|
|
62
62
|
function relationKindsFor(page) {
|
|
63
63
|
return [...new Set([...RELATION_KINDS, ...notationOwn(NOTATION_RELATION_KINDS, page)])];
|
|
64
64
|
}
|
|
65
|
-
/**
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
65
|
+
/**
|
|
66
|
+
* One bullet per topic of one kind: the command that prints it, and its own title.
|
|
67
|
+
* A topic with a starter is a diagram type (`init --type` offers it); one without is
|
|
68
|
+
* a feature any diagram can use (composition). Every topic's title is read whatever
|
|
69
|
+
* its kind, so a page with none fails here. `at` names the page the placeholder is in.
|
|
70
|
+
*/
|
|
71
|
+
function topicList(ctx, kind, placeholder, at) {
|
|
72
|
+
const types = new Set(starterTypes(ctx.startersDir));
|
|
73
|
+
const bullets = [];
|
|
74
|
+
for (const topic of guideTopics(ctx.guideDir)) {
|
|
75
|
+
const file = path.join(ctx.guideDir, `${topic}.md`);
|
|
70
76
|
const title = /^# (.+)$/m.exec(readFileSync(file, 'utf8'))?.[1];
|
|
71
77
|
if (title === undefined)
|
|
72
78
|
throw new Error(`${file}: a topic starts with a '# Title' line`);
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
79
|
+
if (types.has(topic) === (kind === 'types'))
|
|
80
|
+
bullets.push(`- \`diagc guide ${topic}\` — ${title.trim()}`);
|
|
81
|
+
}
|
|
82
|
+
if (bullets.length === 0) {
|
|
83
|
+
throw new Error(`${at}: ${placeholder} is empty — ${kind === 'types' ? 'no topic has a starter' : 'every topic has a starter'}`);
|
|
84
|
+
}
|
|
85
|
+
return bullets.join('\n');
|
|
76
86
|
}
|
|
77
87
|
/** One page with its placeholders filled. The replacer is a function, so what it
|
|
78
88
|
* returns is taken literally: a starter holding `$&` or a `{{…}}` of its own is
|
|
@@ -97,7 +107,9 @@ function renderPage(page, ctx) {
|
|
|
97
107
|
case 'relation-kinds':
|
|
98
108
|
return codeList(relationKindsFor(page));
|
|
99
109
|
case 'topics':
|
|
100
|
-
return topicList(ctx
|
|
110
|
+
return topicList(ctx, 'types', whole, file);
|
|
111
|
+
case 'feature-topics':
|
|
112
|
+
return topicList(ctx, 'features', whole, file);
|
|
101
113
|
case 'version':
|
|
102
114
|
return ctx.version;
|
|
103
115
|
default:
|
package/dist/home.d.ts
CHANGED
|
@@ -9,8 +9,12 @@ export type HomeLayout = 'monorepo' | 'packaged';
|
|
|
9
9
|
export interface HomePaths {
|
|
10
10
|
root: string;
|
|
11
11
|
layout: HomeLayout;
|
|
12
|
-
/** single-file viewer HTML that `publish
|
|
12
|
+
/** single-file viewer HTML that `publish --single-file`, the studio's export and
|
|
13
|
+
* `diff` stamp models into */
|
|
13
14
|
viewerShell: string;
|
|
15
|
+
/** the same viewer as separate files (`viewer.js`, `viewer.css`, fonts), which
|
|
16
|
+
* `publish` copies once beside the pages for them to share */
|
|
17
|
+
viewerDir: string;
|
|
14
18
|
/** icon/shape library that `publish` inlines `/library/...` refs from */
|
|
15
19
|
libraryDir: string;
|
|
16
20
|
/** module `@diagc/core` is aliased to when jiti executes a `.diagram.ts` */
|
package/dist/home.js
CHANGED
|
@@ -57,6 +57,7 @@ export function homePaths(home, coreEntry = resolveCoreEntry) {
|
|
|
57
57
|
root,
|
|
58
58
|
layout,
|
|
59
59
|
viewerShell: path.join(root, 'assets', 'viewer', 'index.html'),
|
|
60
|
+
viewerDir: path.join(root, 'assets', 'viewer', 'shared'),
|
|
60
61
|
// The studio bundle carries its own `public/library` through the Vite
|
|
61
62
|
// build, so publish and the studio server read one staged copy.
|
|
62
63
|
libraryDir: path.join(studioDir, 'library'),
|
|
@@ -71,6 +72,7 @@ export function homePaths(home, coreEntry = resolveCoreEntry) {
|
|
|
71
72
|
root,
|
|
72
73
|
layout,
|
|
73
74
|
viewerShell: path.join(root, 'apps', 'viewer', 'dist', 'index.html'),
|
|
75
|
+
viewerDir: path.join(root, 'apps', 'viewer', 'dist', 'shared'),
|
|
74
76
|
libraryDir: path.join(root, 'apps', 'studio', 'public', 'library'),
|
|
75
77
|
coreEntry: path.join(root, 'packages', 'core', 'src', 'index.ts'),
|
|
76
78
|
studioDir: path.join(root, 'apps', 'studio'),
|
package/dist/init.d.ts
CHANGED
|
@@ -31,7 +31,7 @@ export declare const AGENTS_END = "<!-- diagc:end -->";
|
|
|
31
31
|
/** What `--agents` writes. Commands, not DSL: the guide is where the DSL lives, so
|
|
32
32
|
* this block does not go stale when the DSL grows. The markers let a later run
|
|
33
33
|
* replace it in place. */
|
|
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 show <name>` to read the picture as text, and `diagc publish <name>` to look at `.diagrams/static/<name>.png`.\n<!-- diagc:end -->\n";
|
|
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, and `diagc guide compose` pulling other diagrams in.\n- Run `diagc lint --json` until it reports nothing.\n- Run `diagc show <name>` to read the picture as text, and `diagc publish <name>` to look at `.diagrams/static/<name>.png`.\n<!-- diagc:end -->\n";
|
|
35
35
|
/** Where the skill goes: the folder Claude Code reads a repository's skills from. */
|
|
36
36
|
export declare const SKILL_PATH = ".claude/skills/diagc/SKILL.md";
|
|
37
37
|
/** `existing` with `block` added at the end, or — when an earlier block is there —
|
package/dist/init.js
CHANGED
|
@@ -25,7 +25,7 @@ export const AGENTS_BLOCK = `${AGENTS_BEGIN}
|
|
|
25
25
|
|
|
26
26
|
Diagrams live in \`.diagrams/src/*.diagram.ts\` and are built with \`diagc\`.
|
|
27
27
|
|
|
28
|
-
- Run \`diagc guide\` before writing or changing one; \`diagc guide <type>\` covers one diagram type.
|
|
28
|
+
- Run \`diagc guide\` before writing or changing one; \`diagc guide <type>\` covers one diagram type, and \`diagc guide compose\` pulling other diagrams in.
|
|
29
29
|
- Run \`diagc lint --json\` until it reports nothing.
|
|
30
30
|
- Run \`diagc show <name>\` to read the picture as text, and \`diagc publish <name>\` to look at \`.diagrams/static/<name>.png\`.
|
|
31
31
|
${AGENTS_END}
|
package/dist/lint.js
CHANGED
|
@@ -30,7 +30,8 @@ export async function lintFile(file, opts) {
|
|
|
30
30
|
{
|
|
31
31
|
file,
|
|
32
32
|
severity: 'error',
|
|
33
|
-
|
|
33
|
+
// a builder refusal names its rule; a source that simply threw is `load`
|
|
34
|
+
code: e.code ?? 'load',
|
|
34
35
|
message: e.reason,
|
|
35
36
|
...(e.line !== undefined && e.column !== undefined ? { line: e.line, column: e.column } : {}),
|
|
36
37
|
},
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* A load error's message with what the author probably meant, when the shape of
|
|
3
|
+
* the message says: `x.y is not a function` is a method that does not exist, so
|
|
4
|
+
* the closest one that does is named, by the lint's own did-you-mean rule — and a
|
|
5
|
+
* composition verb gets told where composition lives instead, since no method is
|
|
6
|
+
* close to what they wanted. Anything else is returned as it is.
|
|
7
|
+
*/
|
|
8
|
+
export declare function loadHint(message: string): string;
|