@diagc/cli 1.3.0 → 1.5.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/assets/studio/assets/index-DRsUukzt.js +112 -0
- package/assets/studio/index.html +1 -1
- package/assets/viewer/index.html +33 -33
- package/dist/api/diagrams.d.ts +5 -0
- package/dist/api/diagrams.js +37 -24
- package/dist/api/dispatch.d.ts +3 -0
- package/dist/api/handlers.d.ts +1 -0
- package/dist/api/handlers.js +1 -0
- package/dist/api/pages.d.ts +21 -0
- package/dist/api/pages.js +50 -0
- package/dist/api/routes.d.ts +2 -0
- package/dist/api/routes.js +6 -0
- package/dist/cli/parse.d.ts +6 -0
- package/dist/cli/parse.js +34 -0
- package/dist/cli.js +3 -0
- package/dist/commands/publish.d.ts +1 -1
- package/dist/commands/publish.js +6 -1
- package/dist/publish/publish.d.ts +20 -3
- package/dist/publish/publish.js +33 -17
- package/dist/publish/snapshot.d.ts +13 -4
- package/dist/publish/snapshot.js +16 -9
- package/dist/serve.d.ts +3 -0
- package/dist/serve.js +2 -2
- package/dist/studio.js +1 -0
- package/package.json +2 -2
- package/assets/studio/assets/index-CKMBmn_i.js +0 -110
package/dist/api/diagrams.d.ts
CHANGED
|
@@ -12,6 +12,11 @@ export interface DiagramEntry {
|
|
|
12
12
|
* `diagramsDir`, compiled TS artifacts from `artifactsDir`. A source shadows its
|
|
13
13
|
* artifact so unsaved-compile staleness never shows. */
|
|
14
14
|
export declare function listDiagramModels(diagramsDir: string, artifactsDir: string): Promise<HandlerResult>;
|
|
15
|
+
/** The diagram `name` as the studio's list shows it, or undefined when the list has
|
|
16
|
+
* no such name. Looking the name up in the listing, rather than checking its
|
|
17
|
+
* spelling, is what keeps it inside the two directories: a compiled diagram's name
|
|
18
|
+
* comes from its `.diagram.ts` file and need not pass `isSafeName`. */
|
|
19
|
+
export declare function diagramAsShown(diagramsDir: string, artifactsDir: string, name: string): Promise<DiagramEntry | undefined>;
|
|
15
20
|
/** the JSON source (+ sibling layout and drawings) of a designer-owned diagram — the studio
|
|
16
21
|
* reads these directly so it never depends on a compile watcher for its own files */
|
|
17
22
|
export declare function readDiagram(diagramsDir: string, name: string): Promise<HandlerResult>;
|
package/dist/api/diagrams.js
CHANGED
|
@@ -16,32 +16,45 @@ export async function listDiagramModels(diagramsDir, artifactsDir) {
|
|
|
16
16
|
const artifactNames = await walkDiagramJson(artifactsDir);
|
|
17
17
|
const all = [...new Set([...sourceNames, ...artifactNames])].sort();
|
|
18
18
|
const diagrams = [];
|
|
19
|
-
for (const name of all)
|
|
20
|
-
|
|
21
|
-
// Every read and save refuses a name isSafeName refuses, so such a source is shown but not offered for editing.
|
|
22
|
-
const editable = isSource && isSafeName(name);
|
|
23
|
-
const file = isSource
|
|
24
|
-
? path.join(diagramsDir, `${name}.diagram.json`)
|
|
25
|
-
: path.join(artifactsDir, `${name}.diagram.json`);
|
|
26
|
-
let model = null;
|
|
27
|
-
const issues = [];
|
|
28
|
-
if (isSource && !editable) {
|
|
29
|
-
issues.push({
|
|
30
|
-
message: `'${name}' is read-only here: the studio saves names of lowercase letters, digits, '-' and '/', none ending in /rename, /eject or /composed. Rename the file to edit it.`,
|
|
31
|
-
});
|
|
32
|
-
}
|
|
33
|
-
try {
|
|
34
|
-
model = JSON.parse(await readFile(file, 'utf8'));
|
|
35
|
-
}
|
|
36
|
-
catch {
|
|
37
|
-
issues.push({ message: `Could not read model for '${name}'` });
|
|
38
|
-
}
|
|
39
|
-
if (isSource && hasIncludes(model))
|
|
40
|
-
model = await composedForList(model, file, diagramsDir, issues);
|
|
41
|
-
diagrams.push({ name, model, issues, editable });
|
|
42
|
-
}
|
|
19
|
+
for (const name of all)
|
|
20
|
+
diagrams.push(await loadEntry(diagramsDir, artifactsDir, name, sourceNames.has(name)));
|
|
43
21
|
return { status: 200, body: { diagrams } };
|
|
44
22
|
}
|
|
23
|
+
/** The diagram `name` as the studio's list shows it, or undefined when the list has
|
|
24
|
+
* no such name. Looking the name up in the listing, rather than checking its
|
|
25
|
+
* spelling, is what keeps it inside the two directories: a compiled diagram's name
|
|
26
|
+
* comes from its `.diagram.ts` file and need not pass `isSafeName`. */
|
|
27
|
+
export async function diagramAsShown(diagramsDir, artifactsDir, name) {
|
|
28
|
+
if ((await walkDiagramJson(diagramsDir)).includes(name))
|
|
29
|
+
return loadEntry(diagramsDir, artifactsDir, name, true);
|
|
30
|
+
if ((await walkDiagramJson(artifactsDir)).includes(name))
|
|
31
|
+
return loadEntry(diagramsDir, artifactsDir, name, false);
|
|
32
|
+
return undefined;
|
|
33
|
+
}
|
|
34
|
+
/** One listed diagram: its JSON source with includes expanded, or else its artifact. */
|
|
35
|
+
async function loadEntry(diagramsDir, artifactsDir, name, isSource) {
|
|
36
|
+
// Every read and save refuses a name isSafeName refuses, so such a source is shown but not offered for editing.
|
|
37
|
+
const editable = isSource && isSafeName(name);
|
|
38
|
+
const file = isSource
|
|
39
|
+
? path.join(diagramsDir, `${name}.diagram.json`)
|
|
40
|
+
: path.join(artifactsDir, `${name}.diagram.json`);
|
|
41
|
+
let model = null;
|
|
42
|
+
const issues = [];
|
|
43
|
+
if (isSource && !editable) {
|
|
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 /composed. Rename the file to edit it.`,
|
|
46
|
+
});
|
|
47
|
+
}
|
|
48
|
+
try {
|
|
49
|
+
model = JSON.parse(await readFile(file, 'utf8'));
|
|
50
|
+
}
|
|
51
|
+
catch {
|
|
52
|
+
issues.push({ message: `Could not read model for '${name}'` });
|
|
53
|
+
}
|
|
54
|
+
if (isSource && hasIncludes(model))
|
|
55
|
+
model = await composedForList(model, file, diagramsDir, issues);
|
|
56
|
+
return { name, model, issues, editable };
|
|
57
|
+
}
|
|
45
58
|
/** `model` with its includes expanded for the list, or `model` itself when they
|
|
46
59
|
* cannot be, with what went wrong added to `issues`. */
|
|
47
60
|
async function composedForList(model, file, diagramsDir, issues) {
|
package/dist/api/dispatch.d.ts
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import type { IncomingMessage, ServerResponse } from 'node:http';
|
|
2
|
+
import type { PageSources } from './pages.js';
|
|
2
3
|
/** The handler module, passed in rather than imported: the Vite adapter loads it
|
|
3
4
|
* through the dev pipeline, the packaged server imports it directly. */
|
|
4
5
|
export type Handlers = typeof import('./handlers.js');
|
|
@@ -6,6 +7,8 @@ export type Handlers = typeof import('./handlers.js');
|
|
|
6
7
|
export interface ApiContext {
|
|
7
8
|
diagramsDir: string;
|
|
8
9
|
artifactsDir: string;
|
|
10
|
+
/** what the page route builds from; a host without it answers that route 501 */
|
|
11
|
+
pages?: PageSources;
|
|
9
12
|
}
|
|
10
13
|
/** A request in transport-neutral terms: no `IncomingMessage`, so a host with
|
|
11
14
|
* no HTTP objects at all (the Obsidian in-process bridge) can still drive a
|
package/dist/api/handlers.d.ts
CHANGED
|
@@ -2,6 +2,7 @@ export { MAX_ASSET_BYTES, readAsset, saveAsset } from './assets.js';
|
|
|
2
2
|
export { ejectDiagramSource, listDiagramModels, readComposedDiagram, readDiagram, renameDiagram, saveDiagram, type DiagramEntry, } from './diagrams.js';
|
|
3
3
|
export { walkDiagramJson, walkFiles } from './files.js';
|
|
4
4
|
export { readLibrary, saveLibrary } from './library.js';
|
|
5
|
+
export { exportPage } from './pages.js';
|
|
5
6
|
export type { HandlerResult } from './result.js';
|
|
6
7
|
export { listDrawings, listLayouts, saveDrawings, saveLayout } from './sidecars.js';
|
|
7
8
|
export { isSafeName } from '../names.js';
|
package/dist/api/handlers.js
CHANGED
|
@@ -6,6 +6,7 @@ export { MAX_ASSET_BYTES, readAsset, saveAsset } from './assets.js';
|
|
|
6
6
|
export { ejectDiagramSource, listDiagramModels, readComposedDiagram, readDiagram, renameDiagram, saveDiagram, } from './diagrams.js';
|
|
7
7
|
export { walkDiagramJson, walkFiles } from './files.js';
|
|
8
8
|
export { readLibrary, saveLibrary } from './library.js';
|
|
9
|
+
export { exportPage } from './pages.js';
|
|
9
10
|
export { listDrawings, listLayouts, saveDrawings, saveLayout } from './sidecars.js';
|
|
10
11
|
// The name rule every route checks, for the hosts and tests that reach it here.
|
|
11
12
|
export { isSafeName } from '../names.js';
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
import { type HandlerResult } from './result.js';
|
|
2
|
+
/** What a host builds a diagram's web page from: the viewer page `publish` stamps
|
|
3
|
+
* models into, and the icon library its `/library/…` pictures are read from. Each
|
|
4
|
+
* host has its own copies (a checkout's build output, a package's `assets/`, the
|
|
5
|
+
* Obsidian plugin's folder), so each says where they are. */
|
|
6
|
+
export interface PageSources {
|
|
7
|
+
shellPath: string;
|
|
8
|
+
libraryDir: string;
|
|
9
|
+
}
|
|
10
|
+
/**
|
|
11
|
+
* The diagram `name` as one self-contained web page: the page `publish` writes for
|
|
12
|
+
* it, built here so the studio can hand it over as a download. The model is the one
|
|
13
|
+
* the studio shows (the saved source, includes expanded, or else the compiled
|
|
14
|
+
* artifact), so the page cannot lag a compile the way an artifact can.
|
|
15
|
+
*
|
|
16
|
+
* Answered as JSON, `{ html, warnings }`, not as raw bytes: what could not be
|
|
17
|
+
* packed in (a missing picture, a malformed drawings sidecar) still leaves a page
|
|
18
|
+
* worth saving, and the studio should say so rather than hand over a quietly
|
|
19
|
+
* broken one.
|
|
20
|
+
*/
|
|
21
|
+
export declare function exportPage(diagramsDir: string, artifactsDir: string, sources: PageSources | undefined, name: string): Promise<HandlerResult>;
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
import { access, readFile } from 'node:fs/promises';
|
|
2
|
+
import path from 'node:path';
|
|
3
|
+
import { stampHtml } from '../publish/html.js';
|
|
4
|
+
import { inlineAssets, readSidecars } from '../publish/publish.js';
|
|
5
|
+
import { diagramAsShown } from './diagrams.js';
|
|
6
|
+
import { refuse } from './result.js';
|
|
7
|
+
const existing = async (p) => {
|
|
8
|
+
try {
|
|
9
|
+
await access(p);
|
|
10
|
+
return p;
|
|
11
|
+
}
|
|
12
|
+
catch {
|
|
13
|
+
return undefined;
|
|
14
|
+
}
|
|
15
|
+
};
|
|
16
|
+
/**
|
|
17
|
+
* The diagram `name` as one self-contained web page: the page `publish` writes for
|
|
18
|
+
* it, built here so the studio can hand it over as a download. The model is the one
|
|
19
|
+
* the studio shows (the saved source, includes expanded, or else the compiled
|
|
20
|
+
* artifact), so the page cannot lag a compile the way an artifact can.
|
|
21
|
+
*
|
|
22
|
+
* Answered as JSON, `{ html, warnings }`, not as raw bytes: what could not be
|
|
23
|
+
* packed in (a missing picture, a malformed drawings sidecar) still leaves a page
|
|
24
|
+
* worth saving, and the studio should say so rather than hand over a quietly
|
|
25
|
+
* broken one.
|
|
26
|
+
*/
|
|
27
|
+
export async function exportPage(diagramsDir, artifactsDir, sources, name) {
|
|
28
|
+
if (sources === undefined)
|
|
29
|
+
return refuse(501, 'This studio cannot build web pages: its host has no viewer page to build them from.');
|
|
30
|
+
const entry = await diagramAsShown(diagramsDir, artifactsDir, name);
|
|
31
|
+
if (entry === undefined)
|
|
32
|
+
return refuse(404, `No diagram '${name}'`);
|
|
33
|
+
if (entry.model === null)
|
|
34
|
+
return { status: 500, body: { issues: entry.issues } };
|
|
35
|
+
let shell;
|
|
36
|
+
try {
|
|
37
|
+
shell = await readFile(sources.shellPath, 'utf8');
|
|
38
|
+
}
|
|
39
|
+
catch {
|
|
40
|
+
return refuse(500, `No viewer page at ${sources.shellPath} — in a checkout, build it with \`pnpm build:cli\`.`);
|
|
41
|
+
}
|
|
42
|
+
const warnings = [];
|
|
43
|
+
const warn = (line) => void warnings.push(line);
|
|
44
|
+
const sidecar = (suffix) => existing(path.join(diagramsDir, `${name}.${suffix}.json`));
|
|
45
|
+
const [layoutPath, drawingsPath] = await Promise.all([sidecar('layout'), sidecar('drawings')]);
|
|
46
|
+
const sidecars = await readSidecars({ name, layoutPath, drawingsPath }, warn);
|
|
47
|
+
const assets = { libraryDir: sources.libraryDir, assetsDir: path.join(diagramsDir, 'assets'), warn };
|
|
48
|
+
const model = await inlineAssets(entry.model, assets, new Map(), `diagram "${name}"`);
|
|
49
|
+
return { status: 200, body: { html: stampHtml(shell, { model, ...sidecars }), warnings } };
|
|
50
|
+
}
|
package/dist/api/routes.d.ts
CHANGED
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import type { PageSources } from './pages.js';
|
|
1
2
|
type Handlers = typeof import('./handlers.js');
|
|
2
3
|
/** One route handler's result: handlers' JSON envelope plus readAsset's
|
|
3
4
|
* optional `bytes`/`contentType`, which the wrapper streams raw. */
|
|
@@ -10,6 +11,7 @@ export interface RouteCtx {
|
|
|
10
11
|
contentType?: string;
|
|
11
12
|
diagramsDir: string;
|
|
12
13
|
artifactsDir: string;
|
|
14
|
+
pages?: PageSources;
|
|
13
15
|
}
|
|
14
16
|
export type BodyMode = 'none' | 'json' | 'raw';
|
|
15
17
|
export interface Route {
|
package/dist/api/routes.js
CHANGED
|
@@ -74,6 +74,12 @@ export const ROUTES = [
|
|
|
74
74
|
: h.saveDrawings(c.diagramsDir, name, c.body);
|
|
75
75
|
},
|
|
76
76
|
},
|
|
77
|
+
// --- pages: a diagram as one self-contained web page, for the studio to download ---
|
|
78
|
+
{
|
|
79
|
+
method: 'GET',
|
|
80
|
+
pattern: /^\/api\/pages\/(.+)$/,
|
|
81
|
+
handler: (h, c) => h.exportPage(c.diagramsDir, c.artifactsDir, c.pages, decodeURIComponent(c.match[1] ?? '')),
|
|
82
|
+
},
|
|
77
83
|
];
|
|
78
84
|
/** The route matching `method` + `url`, or undefined. First match wins. */
|
|
79
85
|
export function matchRoute(method, url) {
|
package/dist/cli/parse.d.ts
CHANGED
|
@@ -9,6 +9,8 @@ export interface FlagValues {
|
|
|
9
9
|
'--update-includes': true;
|
|
10
10
|
'--type': string;
|
|
11
11
|
'--agents': true;
|
|
12
|
+
'--style': string;
|
|
13
|
+
'--theme': 'light' | 'dark';
|
|
12
14
|
}
|
|
13
15
|
export type Flag = keyof FlagValues;
|
|
14
16
|
/** What a command takes, as the parser checks it before the command runs. */
|
|
@@ -37,6 +39,10 @@ export declare class UsageError extends Error {
|
|
|
37
39
|
readonly exitCode: number;
|
|
38
40
|
constructor(message: string, exitCode: number);
|
|
39
41
|
}
|
|
42
|
+
/** The style presets `--style` takes: the renderer's, by id and in its order. The CLI
|
|
43
|
+
* cannot import the renderer (it only couples to the viewer as a built artifact), so
|
|
44
|
+
* the list is written out and styleIds.test.ts pins it to the renderer's. */
|
|
45
|
+
export declare const STYLE_IDS: string[];
|
|
40
46
|
/** Read argv against every flag there is, whichever command it names: which arguments
|
|
41
47
|
* are values depends on the flags alone, and the command may come after its flags. The
|
|
42
48
|
* first mistake in argv's order is thrown as a {@link UsageError}. An unknown flag is an
|
package/dist/cli/parse.js
CHANGED
|
@@ -11,6 +11,25 @@ export class UsageError extends Error {
|
|
|
11
11
|
}
|
|
12
12
|
}
|
|
13
13
|
const badValue = (flag, why) => new UsageError(`${flag}: ${why}`, 1);
|
|
14
|
+
/** The style presets `--style` takes: the renderer's, by id and in its order. The CLI
|
|
15
|
+
* cannot import the renderer (it only couples to the viewer as a built artifact), so
|
|
16
|
+
* the list is written out and styleIds.test.ts pins it to the renderer's. */
|
|
17
|
+
export const STYLE_IDS = [
|
|
18
|
+
'clean',
|
|
19
|
+
'sketch',
|
|
20
|
+
'hand-drawn',
|
|
21
|
+
'pencil',
|
|
22
|
+
'blueprint',
|
|
23
|
+
'marker',
|
|
24
|
+
'soft',
|
|
25
|
+
'pastel',
|
|
26
|
+
'cards',
|
|
27
|
+
'layered',
|
|
28
|
+
'neon',
|
|
29
|
+
'terminal',
|
|
30
|
+
'ascii',
|
|
31
|
+
'dos',
|
|
32
|
+
];
|
|
14
33
|
/** Every flag, in the order the refusal of one a command does not take goes through them:
|
|
15
34
|
* how it reads its value, or null for a flag that takes none. */
|
|
16
35
|
const FLAGS = {
|
|
@@ -53,6 +72,21 @@ const FLAGS = {
|
|
|
53
72
|
return next;
|
|
54
73
|
},
|
|
55
74
|
'--agents': null,
|
|
75
|
+
'--style': (next) => {
|
|
76
|
+
// No fallback: a missing value would otherwise swallow the next flag as the style.
|
|
77
|
+
if (next === undefined || next.startsWith('--'))
|
|
78
|
+
throw badValue('--style', `needs a style id, e.g. --style sketch (one of ${STYLE_IDS.join(', ')})`);
|
|
79
|
+
// Refused here rather than passed on: the page falls back to the diagram's own
|
|
80
|
+
// style for an id it does not know, so a typo would quietly publish the wrong look.
|
|
81
|
+
if (!STYLE_IDS.includes(next))
|
|
82
|
+
throw badValue('--style', `no style '${next}'; one of ${STYLE_IDS.join(', ')}`);
|
|
83
|
+
return next;
|
|
84
|
+
},
|
|
85
|
+
'--theme': (next) => {
|
|
86
|
+
if (next !== 'light' && next !== 'dark')
|
|
87
|
+
throw badValue('--theme', 'light or dark, e.g. --theme dark');
|
|
88
|
+
return next;
|
|
89
|
+
},
|
|
56
90
|
};
|
|
57
91
|
const isFlag = (arg) => Object.hasOwn(FLAGS, arg);
|
|
58
92
|
/** Read argv against every flag there is, whichever command it names: which arguments
|
package/dist/cli.js
CHANGED
|
@@ -44,6 +44,9 @@ Options:
|
|
|
44
44
|
diff: .diagrams/diff/<from>..<to>)
|
|
45
45
|
--no-images Publish (or diff) HTML without rendering PNG images
|
|
46
46
|
--link url Publish with a link to url in the index header
|
|
47
|
+
--style id Publish: take the PNGs in this style preset (clean, sketch, …) in
|
|
48
|
+
place of each diagram's own
|
|
49
|
+
--theme t Publish: take the PNGs light (the default) or dark
|
|
47
50
|
--json lint: print the findings as a JSON array; diff: the changes as JSON
|
|
48
51
|
--labels a,b diff: name the two sides (default: the refs)
|
|
49
52
|
--image-url t diff: summary.md's image links as t, {path} standing for each PNG
|
|
@@ -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'>;
|
|
10
|
+
export declare const publish: Command<'--out' | '--no-images' | '--link' | '--update-includes' | '--style' | '--theme'>;
|
|
11
11
|
export {};
|
package/dist/commands/publish.js
CHANGED
|
@@ -40,7 +40,7 @@ async function compileSources(dirs, { io, home, snapshots }) {
|
|
|
40
40
|
}
|
|
41
41
|
/** `diagc publish [names...]`: compile, then a page per diagram, the gallery, and PNGs. */
|
|
42
42
|
export const publish = {
|
|
43
|
-
flags: ['--out', '--no-images', '--link', '--update-includes'],
|
|
43
|
+
flags: ['--out', '--no-images', '--link', '--update-includes', '--style', '--theme'],
|
|
44
44
|
async run({ positionals, flags }, ctx) {
|
|
45
45
|
const { io, home, snapshots } = ctx;
|
|
46
46
|
if (!existsSync(home.viewerShell)) {
|
|
@@ -71,6 +71,11 @@ export const publish = {
|
|
|
71
71
|
images: renderPng !== undefined,
|
|
72
72
|
names,
|
|
73
73
|
...(renderPng !== undefined ? { renderPng } : {}),
|
|
74
|
+
// the pictures' look; the pages keep the diagram's own, with the reader's picker
|
|
75
|
+
look: {
|
|
76
|
+
...(flags['--style'] !== undefined ? { style: flags['--style'] } : {}),
|
|
77
|
+
...(flags['--theme'] !== undefined ? { theme: flags['--theme'] } : {}),
|
|
78
|
+
},
|
|
74
79
|
...(flags['--link'] !== undefined ? { link: flags['--link'] } : {}),
|
|
75
80
|
warn: io.err,
|
|
76
81
|
});
|
|
@@ -1,4 +1,6 @@
|
|
|
1
|
-
import type { DiagramModel } from '@diagc/core/internal';
|
|
1
|
+
import type { DiagramModel, LayoutOverlay, Drawings } from '@diagc/core/internal';
|
|
2
|
+
import { type DiscoveredDiagram } from './discover.js';
|
|
3
|
+
import type { PictureLook } from './snapshot.js';
|
|
2
4
|
export interface PublishOptions {
|
|
3
5
|
srcDir: string;
|
|
4
6
|
artifactsDir: string;
|
|
@@ -9,8 +11,10 @@ export interface PublishOptions {
|
|
|
9
11
|
assetsDir: string;
|
|
10
12
|
images: boolean;
|
|
11
13
|
names?: string[];
|
|
12
|
-
/** takes `htmlPath`'s picture
|
|
13
|
-
renderPng?: (htmlPath: string, pngPath: string,
|
|
14
|
+
/** takes `htmlPath`'s picture into `pngPath`, of the plane and in the look `look` says */
|
|
15
|
+
renderPng?: (htmlPath: string, pngPath: string, look?: PictureLook) => Promise<void>;
|
|
16
|
+
/** the look every picture is taken in, in place of the page's own: `--style`, `--theme` */
|
|
17
|
+
look?: Pick<PictureLook, 'style' | 'theme'>;
|
|
14
18
|
/** an http(s) address for the gallery's header — never put on a diagram page */
|
|
15
19
|
link?: string;
|
|
16
20
|
/** where a warning goes, one line each: `console.warn` by default, so a caller with
|
|
@@ -31,6 +35,19 @@ export interface PublishResult {
|
|
|
31
35
|
* diagram in the warnings for refs it has to leave as they are.
|
|
32
36
|
*/
|
|
33
37
|
export declare function inlineAssets(model: DiagramModel, opts: Pick<PublishOptions, 'libraryDir' | 'assetsDir' | 'warn'>, cache: Map<string, Buffer>, label: string): Promise<DiagramModel>;
|
|
38
|
+
/** What a page carries beside its model. */
|
|
39
|
+
export interface PageSidecars {
|
|
40
|
+
layout?: LayoutOverlay;
|
|
41
|
+
drawings?: Drawings;
|
|
42
|
+
}
|
|
43
|
+
/**
|
|
44
|
+
* A diagram's layout and drawings as its page carries them; a path left out is a
|
|
45
|
+
* sidecar the diagram does not have. A hand-edited drawings sidecar can be valid
|
|
46
|
+
* JSON and still not be a drawings overlay. Stamping it would put shapeless data
|
|
47
|
+
* into a page that has no validator of its own, so it is warned about and dropped
|
|
48
|
+
* — the page still ships, just without ink. Unparseable JSON throws.
|
|
49
|
+
*/
|
|
50
|
+
export declare function readSidecars(d: Pick<DiscoveredDiagram, 'name' | 'layoutPath' | 'drawingsPath'>, warn: (line: string) => void): Promise<PageSidecars>;
|
|
34
51
|
/** One picture of a diagram: its plane (absent = the first) and what goes between
|
|
35
52
|
* the diagram's name and `.png`. */
|
|
36
53
|
export interface PlanePicture {
|
package/dist/publish/publish.js
CHANGED
|
@@ -60,6 +60,26 @@ export async function inlineAssets(model, opts, cache, label) {
|
|
|
60
60
|
}
|
|
61
61
|
return rewriteAssetRefs(model, (ref) => cache.get(ref));
|
|
62
62
|
}
|
|
63
|
+
/**
|
|
64
|
+
* A diagram's layout and drawings as its page carries them; a path left out is a
|
|
65
|
+
* sidecar the diagram does not have. A hand-edited drawings sidecar can be valid
|
|
66
|
+
* JSON and still not be a drawings overlay. Stamping it would put shapeless data
|
|
67
|
+
* into a page that has no validator of its own, so it is warned about and dropped
|
|
68
|
+
* — the page still ships, just without ink. Unparseable JSON throws.
|
|
69
|
+
*/
|
|
70
|
+
export async function readSidecars(d, warn) {
|
|
71
|
+
const out = {};
|
|
72
|
+
if (d.layoutPath !== undefined)
|
|
73
|
+
out.layout = JSON.parse(await readFile(d.layoutPath, 'utf8'));
|
|
74
|
+
if (d.drawingsPath !== undefined) {
|
|
75
|
+
const parsed = JSON.parse(await readFile(d.drawingsPath, 'utf8'));
|
|
76
|
+
if (isDrawings(parsed))
|
|
77
|
+
out.drawings = parsed;
|
|
78
|
+
else
|
|
79
|
+
warn(`publish: ignoring malformed drawings sidecar for diagram "${d.name}" (${d.drawingsPath}); the page ships without ink.`);
|
|
80
|
+
}
|
|
81
|
+
return out;
|
|
82
|
+
}
|
|
63
83
|
/**
|
|
64
84
|
* The pictures publish takes of a model, one per plane. The first plane's is
|
|
65
85
|
* `<name>.png`, the picture docs and READMEs already link; each further plane's
|
|
@@ -86,7 +106,10 @@ async function renderPictures(name, model, pagePath, run) {
|
|
|
86
106
|
}
|
|
87
107
|
const pngPath = path.join(run.staticDir, `${file}.png`);
|
|
88
108
|
await mkdir(path.dirname(pngPath), { recursive: true });
|
|
89
|
-
await run.render(pagePath, pngPath,
|
|
109
|
+
await run.render(pagePath, pngPath, {
|
|
110
|
+
...(picture.plane !== undefined ? { plane: picture.plane } : {}),
|
|
111
|
+
...run.look,
|
|
112
|
+
});
|
|
90
113
|
written.push(pngPath);
|
|
91
114
|
}
|
|
92
115
|
return written;
|
|
@@ -114,27 +137,20 @@ export async function publishDiagrams(opts) {
|
|
|
114
137
|
try {
|
|
115
138
|
const modelRaw = JSON.parse(await readFile(d.modelPath, 'utf8'));
|
|
116
139
|
titles.set(d.name, modelRaw.name);
|
|
117
|
-
const
|
|
118
|
-
// A hand-edited sidecar can be valid JSON and still not be a drawings
|
|
119
|
-
// overlay. Publishing it would stamp shapeless data into a page that has
|
|
120
|
-
// no validator of its own, so it is warned about and dropped — the page
|
|
121
|
-
// still ships, just without ink. (Unparseable JSON keeps its old
|
|
122
|
-
// behaviour: it throws, and the diagram is skipped below.)
|
|
123
|
-
let drawings;
|
|
124
|
-
if (d.drawingsPath !== undefined) {
|
|
125
|
-
const parsed = JSON.parse(await readFile(d.drawingsPath, 'utf8'));
|
|
126
|
-
if (isDrawings(parsed))
|
|
127
|
-
drawings = parsed;
|
|
128
|
-
else
|
|
129
|
-
warn(`publish: ignoring malformed drawings sidecar for diagram "${d.name}" (${d.drawingsPath}); the page ships without ink.`);
|
|
130
|
-
}
|
|
140
|
+
const sidecars = await readSidecars(d, warn);
|
|
131
141
|
const inlined = await inlineAssets(modelRaw, opts, cache, `diagram "${d.name}"`);
|
|
132
142
|
const pagePath = path.join(opts.htmlDir, `${d.name}.html`);
|
|
133
143
|
await mkdir(path.dirname(pagePath), { recursive: true });
|
|
134
|
-
await writeFile(pagePath, stampHtml(shell, { model: inlined,
|
|
144
|
+
await writeFile(pagePath, stampHtml(shell, { model: inlined, ...sidecars }));
|
|
135
145
|
pages.push(pagePath);
|
|
136
146
|
if (opts.images && opts.renderPng !== undefined) {
|
|
137
|
-
const run = {
|
|
147
|
+
const run = {
|
|
148
|
+
render: opts.renderPng,
|
|
149
|
+
look: opts.look ?? {},
|
|
150
|
+
staticDir: opts.staticDir,
|
|
151
|
+
diagrams: discovered,
|
|
152
|
+
warn,
|
|
153
|
+
};
|
|
138
154
|
images.push(...(await renderPictures(d.name, modelRaw, pagePath, run)));
|
|
139
155
|
}
|
|
140
156
|
}
|
|
@@ -1,6 +1,15 @@
|
|
|
1
1
|
/** Locate an installed Chrome/Chromium; undefined means "no browser available". */
|
|
2
2
|
export declare function findChrome(): string | undefined;
|
|
3
|
-
/**
|
|
4
|
-
*
|
|
5
|
-
|
|
6
|
-
export
|
|
3
|
+
/** How a picture is taken: which plane (the first when absent), and the look the
|
|
4
|
+
* publisher chose — a style preset, light or dark — in place of the page's own
|
|
5
|
+
* (the diagram's style, light). */
|
|
6
|
+
export interface PictureLook {
|
|
7
|
+
plane?: string;
|
|
8
|
+
style?: string;
|
|
9
|
+
theme?: 'light' | 'dark';
|
|
10
|
+
}
|
|
11
|
+
/** The page's export render: `?export=1` unfolds every group for a full overview;
|
|
12
|
+
* `plane`, `style` and `theme` say which plane, and in what look (see PictureLook —
|
|
13
|
+
* the viewer reads them as apps/viewer/src/style.ts and theme.ts say). */
|
|
14
|
+
export declare function exportUrl(htmlPath: string, look?: PictureLook): string;
|
|
15
|
+
export declare function renderPng(htmlPath: string, pngPath: string, look?: PictureLook): Promise<void>;
|
package/dist/publish/snapshot.js
CHANGED
|
@@ -20,27 +20,34 @@ export function findChrome() {
|
|
|
20
20
|
}
|
|
21
21
|
/** Frame padding around the graph, in screen px. */
|
|
22
22
|
const FRAME_PADDING = 32;
|
|
23
|
-
/** The page's export render: `?export=1` unfolds every group for a full overview
|
|
24
|
-
* and `
|
|
25
|
-
|
|
26
|
-
|
|
23
|
+
/** The page's export render: `?export=1` unfolds every group for a full overview;
|
|
24
|
+
* `plane`, `style` and `theme` say which plane, and in what look (see PictureLook —
|
|
25
|
+
* the viewer reads them as apps/viewer/src/style.ts and theme.ts say). */
|
|
26
|
+
export function exportUrl(htmlPath, look = {}) {
|
|
27
|
+
const query = new URLSearchParams({
|
|
28
|
+
export: '1',
|
|
29
|
+
...(look.plane !== undefined ? { plane: look.plane } : {}),
|
|
30
|
+
...(look.style !== undefined ? { style: look.style } : {}),
|
|
31
|
+
...(look.theme !== undefined ? { theme: look.theme } : {}),
|
|
32
|
+
});
|
|
27
33
|
return `${pathToFileURL(path.resolve(htmlPath)).href}?${query.toString()}`;
|
|
28
34
|
}
|
|
29
|
-
export async function renderPng(htmlPath, pngPath,
|
|
35
|
+
export async function renderPng(htmlPath, pngPath, look = {}) {
|
|
30
36
|
const executablePath = findChrome();
|
|
31
37
|
if (executablePath === undefined) {
|
|
32
38
|
throw new Error('No Chrome found for image export. Install Google Chrome/Chromium, set CHROME_PATH, or run with --no-images.');
|
|
33
39
|
}
|
|
34
40
|
const browser = await chromium.launch({ executablePath, headless: true });
|
|
35
41
|
try {
|
|
36
|
-
//
|
|
37
|
-
// prefers, and this says so where
|
|
42
|
+
// Named, not left to the browser: `?export=1` already makes the viewer light (or
|
|
43
|
+
// the theme in the address) whatever the browser prefers, and this says so where
|
|
44
|
+
// the picture is taken.
|
|
38
45
|
const page = await browser.newPage({
|
|
39
46
|
viewport: { width: 1600, height: 1000 },
|
|
40
47
|
deviceScaleFactor: 2,
|
|
41
|
-
colorScheme: 'light',
|
|
48
|
+
colorScheme: look.theme ?? 'light',
|
|
42
49
|
});
|
|
43
|
-
await page.goto(exportUrl(htmlPath,
|
|
50
|
+
await page.goto(exportUrl(htmlPath, look));
|
|
44
51
|
await page.waitForFunction(() => window.__DG_READY__ === true, null, {
|
|
45
52
|
timeout: 15_000,
|
|
46
53
|
});
|
package/dist/serve.d.ts
CHANGED
|
@@ -1,9 +1,12 @@
|
|
|
1
|
+
import type { PageSources } from './api/pages.js';
|
|
1
2
|
export declare const contentTypeFor: (file: string) => string;
|
|
2
3
|
export interface ServeOptions {
|
|
3
4
|
/** prebuilt studio bundle (index.html + assets + library) */
|
|
4
5
|
studioDir: string;
|
|
5
6
|
diagramsDir: string;
|
|
6
7
|
artifactsDir: string;
|
|
8
|
+
/** what the page route builds from (see `PageSources`) */
|
|
9
|
+
pages?: PageSources;
|
|
7
10
|
/** first port to try; the server walks upward when one is taken */
|
|
8
11
|
port?: number;
|
|
9
12
|
host?: string;
|
package/dist/serve.js
CHANGED
|
@@ -110,13 +110,13 @@ function listen(server, port, host, attempts = 20) {
|
|
|
110
110
|
* itself is an ordinary SPA that only ever talks to `/api/*`, which is what
|
|
111
111
|
* makes a static bundle behave identically here. */
|
|
112
112
|
export async function startStudioServer(opts) {
|
|
113
|
-
const { studioDir, diagramsDir, artifactsDir } = opts;
|
|
113
|
+
const { studioDir, diagramsDir, artifactsDir, pages } = opts;
|
|
114
114
|
const host = opts.host ?? '127.0.0.1';
|
|
115
115
|
const index = path.join(studioDir, 'index.html');
|
|
116
116
|
const server = createServer((req, res) => {
|
|
117
117
|
void (async () => {
|
|
118
118
|
try {
|
|
119
|
-
if (await handleApiRequest(req, res, { diagramsDir, artifactsDir }, handlers))
|
|
119
|
+
if (await handleApiRequest(req, res, { diagramsDir, artifactsDir, pages }, handlers))
|
|
120
120
|
return;
|
|
121
121
|
const file = resolveStatic(studioDir, req.url ?? '/');
|
|
122
122
|
if (file === undefined) {
|
package/dist/studio.js
CHANGED
|
@@ -84,6 +84,7 @@ async function servePackaged(home, env) {
|
|
|
84
84
|
studioDir: home.studioDir,
|
|
85
85
|
diagramsDir: env.DIAGRAMS_DIR,
|
|
86
86
|
artifactsDir: env.ARTIFACTS_DIR,
|
|
87
|
+
pages: { shellPath: home.viewerShell, libraryDir: home.libraryDir },
|
|
87
88
|
});
|
|
88
89
|
console.log(`Studio ready on ${server.url}`);
|
|
89
90
|
if (env.DIAGRAMS_OPEN === '1')
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@diagc/cli",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.5.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": "1.
|
|
47
|
+
"@diagc/core": "1.5.0"
|
|
48
48
|
},
|
|
49
49
|
"publishConfig": {
|
|
50
50
|
"access": "public"
|