@diagc/cli 0.1.0

package/dist/snapshots.js

@@ -0,0 +1,113 @@
+import { createHash } from 'node:crypto';
+import { mkdir, readFile, readdir, rm, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { IncludeError } from '@diagc/core';
+const LOCK_NAME = 'includes.lock.json';
+const VENDOR_DIR = 'includes';
+const isHttp = (s) => /^https?:\/\//.test(s);
+const digest = (text) => createHash('sha256').update(text).digest('hex');
+/** vendor file name: url basename (sanitized) + hash prefix, collision-proof by content */
+function vendorName(url, hash) {
+    const base = (new URL(url).pathname.split('/').pop() ?? '')
+        .replace(/\.diagram\.json$/, '')
+        .replace(/[^A-Za-z0-9_-]/g, '-');
+    return `${base === '' ? 'include' : base}-${hash.slice(0, 8)}.diagram.json`;
+}
+/**
+ * Wrap an include resolver with lockfile-pinned vendoring for remote specs.
+ * Local specs pass straight through — they are already in-repo and reviewable.
+ * The wrapper always returns the ORIGINAL absolute URL as the ref, so cycle
+ * detection and nested relative resolution behave exactly as unlocked fetches.
+ */
+export function snapshotSession(base, rootDir, mode) {
+    const lockPath = path.join(rootDir, LOCK_NAME);
+    const vendorDir = path.join(rootDir, VENDOR_DIR);
+    let lock;
+    const touched = new Set();
+    const readLock = async () => {
+        try {
+            return JSON.parse(await readFile(lockPath, 'utf8'));
+        }
+        catch {
+            return { version: 1, includes: {} };
+        }
+    };
+    // Update mode keeps ONE in-memory lock for the whole session: every resolve
+    // mutates the same object in place before persisting it, and prune() needs to
+    // see everything touched across the run. Locked mode must NOT memoize —
+    // watch/studio hold one session open for as long as the process runs, and the
+    // whole point of the lockfile error's own remedy ("run `diagc compile
+    // --update-includes`") is that a *separate* process can write a new lock
+    // while this one keeps resolving. Caching a possibly-empty/stale read for the
+    // process lifetime would make that remedy silently ineffective, so a locked
+    // resolve re-reads the lockfile from disk every time instead.
+    const loadLock = async () => {
+        if (mode === 'locked')
+            return readLock();
+        if (lock === undefined)
+            lock = await readLock();
+        return lock;
+    };
+    const resolver = async (spec, fromRef) => {
+        if (!isHttp(spec) && !isHttp(fromRef))
+            return base(spec, fromRef);
+        const url = isHttp(spec) ? spec : new URL(spec, fromRef).href;
+        const l = await loadLock();
+        if (mode === 'locked') {
+            const entry = l.includes[url];
+            if (entry === undefined) {
+                throw new IncludeError(spec, `Include '${url}' is not snapshotted — run 'diagc compile --update-includes' and commit .diagrams/${VENDOR_DIR}/ + .diagrams/${LOCK_NAME}`);
+            }
+            let text;
+            try {
+                text = await readFile(path.join(rootDir, entry.file), 'utf8');
+            }
+            catch {
+                throw new IncludeError(spec, `Snapshot for '${url}' is missing its vendored file (${entry.file}) — run 'diagc compile --update-includes'`);
+            }
+            const hash = digest(text);
+            if (hash !== entry.sha256) {
+                throw new IncludeError(spec, `Snapshot for '${url}' does not match its lock entry (lock ${entry.sha256}, file ${hash}) — run 'diagc compile --update-includes'`);
+            }
+            return { model: JSON.parse(text), ref: url };
+        }
+        const got = await base(spec, fromRef);
+        const text = `${JSON.stringify(got.model, null, 2)}\n`;
+        const hash = digest(text);
+        const file = path.posix.join(VENDOR_DIR, vendorName(url, hash));
+        await mkdir(vendorDir, { recursive: true });
+        await writeFile(path.join(rootDir, file), text);
+        l.includes[url] = { file, sha256: hash };
+        touched.add(url);
+        await writeFile(lockPath, `${JSON.stringify(l, null, 2)}\n`);
+        return { model: got.model, ref: url };
+    };
+    const prune = async () => {
+        if (mode !== 'update')
+            return;
+        const l = await loadLock();
+        const kept = {};
+        for (const url of touched) {
+            const e = l.includes[url];
+            if (e !== undefined)
+                kept[url] = e;
+        }
+        l.includes = kept;
+        const referenced = new Set(Object.values(kept).map((e) => path.basename(e.file)));
+        let files = [];
+        try {
+            files = await readdir(vendorDir);
+        }
+        catch {
+            /* nothing vendored — nothing to prune */
+        }
+        for (const f of files) {
+            if (!referenced.has(f))
+                await rm(path.join(vendorDir, f), { force: true });
+        }
+        if (touched.size > 0 || files.length > 0) {
+            await writeFile(lockPath, `${JSON.stringify(l, null, 2)}\n`);
+        }
+    };
+    return { resolver, prune };
+}

package/dist/studio.d.ts

@@ -0,0 +1,28 @@
+import type { HomePaths } from './home.js';
+export interface StudioEnv {
+    DIAGRAMS_DIR: string;
+    ARTIFACTS_DIR: string;
+    DIAGRAMS_CWD: string;
+    DIAGRAMS_OPEN: string;
+}
+/** Env that points the monorepo's studio Vite server at the target repo. */
+export declare function studioEnv(cwd: string): StudioEnv;
+/** Per-platform "open this URL" command. */
+export declare function openCommand(platform: NodeJS.Platform): {
+    cmd: string;
+    args: string[];
+};
+/** Best-effort browser launch. A headless box has no opener and that is fine —
+ * the URL is already on stdout, so a failure here must never take the server
+ * down with it. */
+export declare function openBrowser(url: string, platform?: NodeJS.Platform): void;
+/** Run the studio against `cwd`: scaffold src, watch-compile into .artifacts,
+ * and serve the editor. Resolves when the server exits; Ctrl+C tears down both
+ * the watcher and the server.
+ *
+ * Which server depends on the layout (see home.ts). From a checkout it is the
+ * studio's own Vite dev server, so working on the studio keeps HMR. From an
+ * installed package there is no Vite and no workspace to spawn it in, so the
+ * prebuilt bundle is served directly — same API routes either way, because both
+ * hosts dispatch the table in `src/api`. */
+export declare function runStudio(home: HomePaths, cwd: string): Promise<void>;

package/dist/studio.js

@@ -0,0 +1,115 @@
+import { spawn } from 'node:child_process';
+import { mkdir } from 'node:fs/promises';
+import path from 'node:path';
+import { resolveInclude } from './includes.js';
+import { startStudioServer } from './serve.js';
+import { snapshotSession } from './snapshots.js';
+import { formatCompileEvent, startWatch } from './watch.js';
+/** Env that points the monorepo's studio Vite server at the target repo. */
+export function studioEnv(cwd) {
+    return {
+        DIAGRAMS_DIR: path.join(cwd, '.diagrams', 'src'),
+        ARTIFACTS_DIR: path.join(cwd, '.diagrams', '.artifacts'),
+        DIAGRAMS_CWD: cwd,
+        DIAGRAMS_OPEN: '1',
+    };
+}
+/** Per-platform "open this URL" command. */
+export function openCommand(platform) {
+    if (platform === 'darwin')
+        return { cmd: 'open', args: [] };
+    if (platform === 'win32')
+        return { cmd: 'cmd', args: ['/c', 'start', ''] };
+    return { cmd: 'xdg-open', args: [] };
+}
+/** Best-effort browser launch. A headless box has no opener and that is fine —
+ * the URL is already on stdout, so a failure here must never take the server
+ * down with it. */
+export function openBrowser(url, platform = process.platform) {
+    const { cmd, args } = openCommand(platform);
+    try {
+        const child = spawn(cmd, [...args, url], { stdio: 'ignore', detached: true });
+        child.on('error', () => { });
+        child.unref();
+    }
+    catch {
+        /* no opener available */
+    }
+}
+/** Run the studio against `cwd`: scaffold src, watch-compile into .artifacts,
+ * and serve the editor. Resolves when the server exits; Ctrl+C tears down both
+ * the watcher and the server.
+ *
+ * Which server depends on the layout (see home.ts). From a checkout it is the
+ * studio's own Vite dev server, so working on the studio keeps HMR. From an
+ * installed package there is no Vite and no workspace to spawn it in, so the
+ * prebuilt bundle is served directly — same API routes either way, because both
+ * hosts dispatch the table in `src/api`. */
+export async function runStudio(home, cwd) {
+    const env = studioEnv(cwd);
+    await mkdir(env.DIAGRAMS_DIR, { recursive: true });
+    // Studio's live watch-compile loop always resolves includes locked, same as
+    // the one-shot `compile`/`watch` commands default to — the studio has no
+    // `--update-includes` surface, so there is no other mode to offer here.
+    // rootDir is `<cwd>/.diagrams` (not process.cwd()'s `.diagrams`), matching
+    // env.DIAGRAMS_DIR/ARTIFACTS_DIR above: runStudio targets an arbitrary repo.
+    const { resolver } = snapshotSession(resolveInclude, path.join(cwd, '.diagrams'), 'locked');
+    const watcher = startWatch(env.DIAGRAMS_DIR, env.ARTIFACTS_DIR, {
+        coreEntry: home.coreEntry,
+        resolver,
+        onEvent: (e) => {
+            // The studio surfaces the same compile log as the one-shot `compile` and
+            // `watch` commands via the shared formatter (success to stdout, failure
+            // to stderr).
+            if (e.ok)
+                console.log(formatCompileEvent(e));
+            else
+                console.error(formatCompileEvent(e));
+        },
+    });
+    console.log(`Studio for ${cwd} — sources in ${env.DIAGRAMS_DIR}`);
+    const session = home.layout === 'packaged' ? await servePackaged(home, env) : spawnVite(home, env);
+    const shutdown = () => {
+        void watcher.close();
+        void session.stop();
+    };
+    process.on('SIGINT', shutdown);
+    process.on('SIGTERM', shutdown);
+    await session.exited;
+    await watcher.close();
+}
+/** Installed layout: serve the prebuilt bundle over plain http. */
+async function servePackaged(home, env) {
+    const server = await startStudioServer({
+        studioDir: home.studioDir,
+        diagramsDir: env.DIAGRAMS_DIR,
+        artifactsDir: env.ARTIFACTS_DIR,
+    });
+    console.log(`Studio ready on ${server.url}`);
+    if (env.DIAGRAMS_OPEN === '1')
+        openBrowser(server.url);
+    let release = () => { };
+    const exited = new Promise((resolve) => (release = resolve));
+    return {
+        exited,
+        stop: async () => {
+            await server.close();
+            release();
+        },
+    };
+}
+/** Monorepo layout: hand off to the studio's own Vite dev server. */
+function spawnVite(home, env) {
+    const child = spawn('pnpm', ['--filter', '@diagc/studio', 'dev'], {
+        cwd: home.root,
+        env: { ...process.env, ...env },
+        stdio: 'inherit',
+    });
+    return {
+        exited: new Promise((resolve) => child.on('exit', () => resolve())),
+        stop: async () => {
+            if (!child.killed)
+                child.kill('SIGINT');
+        },
+    };
+}

package/dist/watch.d.ts

@@ -0,0 +1,37 @@
+import { type IncludeResolver } from '@diagc/core';
+export type WatchEvent = {
+    file: string;
+    ok: true;
+    artifact: string;
+} | {
+    file: string;
+    ok: false;
+    error: string;
+};
+/** Human-readable rendering of a compile event, shared by the one-shot
+ * `compile` command, the `watch` command's live log, and the `studio` watcher
+ * so all three surface success/failure identically. `ok:false` events are
+ * reported with the '(keeping last good artifact)' cue because those commands
+ * only overwrite artifacts on success. */
+export declare function formatCompileEvent(e: WatchEvent): string;
+/**
+ * Serializes async work per key. Each `run(key)` chains its task onto the
+ * previous in-flight task for the same key, so tasks for one key execute
+ * sequentially in call order (a slower earlier task can no longer settle after
+ * a newer one); tasks for different keys still run concurrently. When a key's
+ * chain tail settles and is still the current tail, its map entry is dropped so
+ * the map does not grow without bound — a newer task queued behind the tail is
+ * never dropped. `task` is expected to handle its own errors (never reject),
+ * like the compile wrapper in `startWatch`.
+ */
+export declare function createSerialRunner(task: (key: string) => Promise<void>): {
+    run(key: string): void;
+    drain(): Promise<void>;
+};
+export declare function startWatch(dir: string, outDir: string, opts?: {
+    onEvent?: (e: WatchEvent) => void;
+    coreEntry?: string;
+    resolver?: IncludeResolver;
+}): {
+    close(): Promise<void>;
+};

package/dist/watch.js

@@ -0,0 +1,79 @@
+import { watch as chokidarWatch } from 'chokidar';
+import { errMessage } from '@diagc/core';
+import { compileFile } from './compile.js';
+/** Human-readable rendering of a compile event, shared by the one-shot
+ * `compile` command, the `watch` command's live log, and the `studio` watcher
+ * so all three surface success/failure identically. `ok:false` events are
+ * reported with the '(keeping last good artifact)' cue because those commands
+ * only overwrite artifacts on success. */
+export function formatCompileEvent(e) {
+    if (e.ok)
+        return `✓ ${e.file} -> ${e.artifact}`;
+    return `✗ ${e.file}\n${e.error}\n(keeping last good artifact)`;
+}
+/**
+ * Serializes async work per key. Each `run(key)` chains its task onto the
+ * previous in-flight task for the same key, so tasks for one key execute
+ * sequentially in call order (a slower earlier task can no longer settle after
+ * a newer one); tasks for different keys still run concurrently. When a key's
+ * chain tail settles and is still the current tail, its map entry is dropped so
+ * the map does not grow without bound — a newer task queued behind the tail is
+ * never dropped. `task` is expected to handle its own errors (never reject),
+ * like the compile wrapper in `startWatch`.
+ */
+export function createSerialRunner(task) {
+    // One tail promise per key; awaiting a tail awaits the whole chain for it.
+    const chains = new Map();
+    const run = (key) => {
+        const prev = chains.get(key) ?? Promise.resolve();
+        const next = prev.then(() => task(key));
+        chains.set(key, next);
+        // When this tail settles, drop the entry — but only if it is still the
+        // current tail, so a newer task chained behind it is never dropped.
+        const cleanup = () => {
+            if (chains.get(key) === next)
+                chains.delete(key);
+        };
+        next.then(cleanup, cleanup);
+    };
+    const drain = async () => {
+        await Promise.all([...chains.values()]);
+    };
+    return { run, drain };
+}
+export function startWatch(dir, outDir, opts = {}) {
+    const watcher = chokidarWatch(dir, { ignoreInitial: false });
+    const compile = async (file) => {
+        try {
+            const artifact = await compileFile(file, outDir, {
+                rootDir: dir,
+                ...(opts.coreEntry !== undefined ? { coreEntry: opts.coreEntry } : {}),
+                ...(opts.resolver !== undefined ? { resolver: opts.resolver } : {}),
+            });
+            opts.onEvent?.({ file, ok: true, artifact });
+        }
+        catch (e) {
+            opts.onEvent?.({ file, ok: false, error: errMessage(e) });
+        }
+    };
+    // Serialize compiles per file path: each event chains onto the previous
+    // in-flight compile for the same path, so events for one file are processed
+    // sequentially in trigger order (a slow earlier compile can no longer report
+    // or write a stale result after a newer one). Different files still compile
+    // concurrently.
+    const runner = createSerialRunner(compile);
+    const onFsEvent = (file) => {
+        if (!file.endsWith('.diagram.ts') && !file.endsWith('.diagram.json'))
+            return;
+        runner.run(file);
+    };
+    watcher.on('add', onFsEvent);
+    watcher.on('change', onFsEvent);
+    return {
+        async close() {
+            await watcher.close();
+            // Let any in-flight compile chains finish so no work leaks past teardown.
+            await runner.drain();
+        },
+    };
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@diagc/cli",
+  "version": "0.1.0",
+  "description": "Author software-architecture diagrams as code, compile them to a validated model, edit them in a local studio, and publish pages and images.",
+  "license": "AGPL-3.0-only",
+  "author": "Bogdan Frankovskyi",
+  "homepage": "https://github.com/Ferroman/diagc#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Ferroman/diagc.git",
+    "directory": "packages/diagc"
+  },
+  "bugs": "https://github.com/Ferroman/diagc/issues",
+  "keywords": [
+    "diagram",
+    "diagrams-as-code",
+    "architecture",
+    "c4",
+    "causal-loop",
+    "cli",
+    "studio"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "bin": {
+    "diagc": "bin/diagc.mjs"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/compile.d.ts",
+      "default": "./dist/compile.js"
+    }
+  },
+  "files": [
+    "bin",
+    "dist",
+    "assets",
+    "THIRD-PARTY-NOTICES.md"
+  ],
+  "dependencies": {
+    "chokidar": "^4.0.0",
+    "fast-glob": "^3.3.0",
+    "jiti": "^2.0.0",
+    "playwright-core": "^1.62.0",
+    "@diagc/core": "0.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {}
+}