@diagc/cli 1.3.0 → 1.4.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.
@@ -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 {};
@@ -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,5 @@
1
1
  import type { DiagramModel } from '@diagc/core/internal';
2
+ import type { PictureLook } from './snapshot.js';
2
3
  export interface PublishOptions {
3
4
  srcDir: string;
4
5
  artifactsDir: string;
@@ -9,8 +10,10 @@ export interface PublishOptions {
9
10
  assetsDir: string;
10
11
  images: boolean;
11
12
  names?: string[];
12
- /** takes `htmlPath`'s picture of `plane` (the first plane when absent) into `pngPath` */
13
- renderPng?: (htmlPath: string, pngPath: string, plane?: string) => Promise<void>;
13
+ /** takes `htmlPath`'s picture into `pngPath`, of the plane and in the look `look` says */
14
+ renderPng?: (htmlPath: string, pngPath: string, look?: PictureLook) => Promise<void>;
15
+ /** the look every picture is taken in, in place of the page's own: `--style`, `--theme` */
16
+ look?: Pick<PictureLook, 'style' | 'theme'>;
14
17
  /** an http(s) address for the gallery's header — never put on a diagram page */
15
18
  link?: string;
16
19
  /** where a warning goes, one line each: `console.warn` by default, so a caller with
@@ -86,7 +86,10 @@ async function renderPictures(name, model, pagePath, run) {
86
86
  }
87
87
  const pngPath = path.join(run.staticDir, `${file}.png`);
88
88
  await mkdir(path.dirname(pngPath), { recursive: true });
89
- await run.render(pagePath, pngPath, picture.plane);
89
+ await run.render(pagePath, pngPath, {
90
+ ...(picture.plane !== undefined ? { plane: picture.plane } : {}),
91
+ ...run.look,
92
+ });
90
93
  written.push(pngPath);
91
94
  }
92
95
  return written;
@@ -134,7 +137,13 @@ export async function publishDiagrams(opts) {
134
137
  await writeFile(pagePath, stampHtml(shell, { model: inlined, layout, drawings }));
135
138
  pages.push(pagePath);
136
139
  if (opts.images && opts.renderPng !== undefined) {
137
- const run = { render: opts.renderPng, staticDir: opts.staticDir, diagrams: discovered, warn };
140
+ const run = {
141
+ render: opts.renderPng,
142
+ look: opts.look ?? {},
143
+ staticDir: opts.staticDir,
144
+ diagrams: discovered,
145
+ warn,
146
+ };
138
147
  images.push(...(await renderPictures(d.name, modelRaw, pagePath, run)));
139
148
  }
140
149
  }
@@ -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
- /** The page's export render: `?export=1` unfolds every group for a full overview,
4
- * and `plane` names the plane to draw (the first when absent). */
5
- export declare function exportUrl(htmlPath: string, plane?: string): string;
6
- export declare function renderPng(htmlPath: string, pngPath: string, plane?: string): Promise<void>;
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>;
@@ -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 `plane` names the plane to draw (the first when absent). */
25
- export function exportUrl(htmlPath, plane) {
26
- const query = new URLSearchParams({ export: '1', ...(plane !== undefined ? { plane } : {}) });
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, plane) {
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
- // Light, by name: `?export=1` already makes the viewer light whatever the browser
37
- // prefers, and this says so where the picture is taken.
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, plane));
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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@diagc/cli",
3
- "version": "1.3.0",
3
+ "version": "1.4.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.3.0"
47
+ "@diagc/core": "1.4.0"
48
48
  },
49
49
  "publishConfig": {
50
50
  "access": "public"