@diagc/cli 0.1.0

package/dist/cli.js

@@ -0,0 +1,271 @@
+/*
+ * diagc — author software-architecture diagrams as code.
+ * Copyright (C) 2026 Bogdan Frankovskyi
+ *
+ * This program is free software: you can redistribute it and/or modify it
+ * under the terms of the GNU Affero General Public License version 3 as
+ * published by the Free Software Foundation, with the additional permissions
+ * granted under section 7 that are set out in the LICENSE file alongside this
+ * package. Those permissions let you license diagram sources you author, and
+ * the output produced from them, under terms of your choosing.
+ *
+ * This program is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License
+ * for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ *
+ * SPDX-License-Identifier: AGPL-3.0-only
+ */
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import fg from 'fast-glob';
+import { errMessage } from '@diagc/core';
+import { compileFile } from './compile.js';
+import { ejectDiagram } from './eject.js';
+import { findHome, homePaths } from './home.js';
+import { resolveInclude } from './includes.js';
+import { snapshotSession } from './snapshots.js';
+import { formatCompileEvent, startWatch } from './watch.js';
+import { publishDiagrams } from './publish/publish.js';
+import { runStudio } from './studio.js';
+const USAGE = `Usage: diagc <compile|watch|publish|studio|eject> [files...] [--out dir]
+
+Commands:
+  compile   Compile *.diagram.{ts,json} sources into overlay artifacts once
+  watch     Recompile — and live-recompile — a directory of sources
+  publish   Compile and render an HTML/PNG site under .diagrams/
+  studio    Run the visual studio against the current directory
+  eject     Promote a JSON diagram to a generated TypeScript source (verified)
+
+Options:
+  --out dir       Artifact output directory (default .diagrams/.artifacts)
+  --no-images     Publish HTML without rendering PNG images
+  --update-includes  Refetch remote includes and rewrite the snapshot lock
+  --help, -h      Show this help and exit
+`;
+/** Parse argv into command + flags. Unknown flags (anything `--…` that is not
+ * recognized) are an error rather than being silently treated as a file path,
+ * so a typo surfaces loudly instead of quietly skewing the file set. */
+export function parseArgs(argv) {
+    let command = 'compile';
+    const files = [];
+    let out = '.diagrams/.artifacts';
+    let images = true;
+    let updateIncludes = false;
+    let commandSeen = false;
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === '--out') {
+            out = argv[++i] ?? out;
+            continue;
+        }
+        if (arg === '--no-images') {
+            images = false;
+            continue;
+        }
+        if (arg === '--update-includes') {
+            updateIncludes = true;
+            continue;
+        }
+        if (arg === '--help' || arg === '-h')
+            throw new HelpRequested();
+        if (arg.startsWith('--'))
+            throw new UnknownFlagError(arg);
+        // The first non-flag argument names the command; anything after it is a
+        // file path (flags may appear before or after the command).
+        if (!commandSeen) {
+            command = arg;
+            commandSeen = true;
+        }
+        else {
+            files.push(arg);
+        }
+    }
+    return { command, files, out, images, updateIncludes };
+}
+/** Thrown by {@link parseArgs} for `--help`/`-h`; `main` prints usage and exits 0. */
+export class HelpRequested extends Error {
+    constructor() {
+        super('help requested');
+        this.name = 'HelpRequested';
+    }
+}
+/** Thrown by {@link parseArgs} for an unrecognized flag; `main` prints the
+ * offending flag plus usage and exits 1. */
+export class UnknownFlagError extends Error {
+    constructor(flag) {
+        super(`Unknown flag '${flag}'`);
+        this.name = 'UnknownFlagError';
+    }
+}
+async function main() {
+    let args;
+    try {
+        args = parseArgs(process.argv.slice(2));
+    }
+    catch (e) {
+        if (e instanceof HelpRequested) {
+            console.log(USAGE);
+            process.exit(0);
+        }
+        if (e instanceof UnknownFlagError) {
+            console.error(`diagc: ${e.message}\n`);
+            console.error(USAGE);
+            process.exit(1);
+        }
+        throw e;
+    }
+    const home = homePaths(findHome(fileURLToPath(import.meta.url)));
+    // One session per CLI invocation, shared across every compile+publish in this
+    // run: the in-memory lock + touched set must span the whole run for prune()
+    // to see everything a full-tree compile actually resolved. `watch` builds its
+    // own separate always-locked session below instead of sharing this one.
+    const snap = snapshotSession(resolveInclude, '.diagrams', args.updateIncludes ? 'update' : 'locked');
+    if (args.command === 'compile') {
+        const files = args.files.length > 0 ? args.files : await fg('.diagrams/src/**/*.diagram.{ts,json}');
+        let failed = false;
+        for (const file of files) {
+            try {
+                const artifact = await compileFile(file, args.out, {
+                    rootDir: '.diagrams/src',
+                    coreEntry: home.coreEntry,
+                    resolver: snap.resolver,
+                });
+                console.log(formatCompileEvent({ file, ok: true, artifact }));
+            }
+            catch (e) {
+                failed = true;
+                console.error(formatCompileEvent({ file, ok: false, error: errMessage(e) }));
+            }
+        }
+        // A source that fails before include resolution (e.g. a pre-compose
+        // validation error) never touches its remote URLs, so pruning here would
+        // drop their still-valid lock entries and vendored files right along with
+        // the genuinely stale ones — skip the prune until every file compiles clean.
+        if (args.updateIncludes && args.files.length === 0 && !failed)
+            await snap.prune();
+        process.exit(failed ? 1 : 0);
+    }
+    else if (args.command === 'watch') {
+        // Always locked, independent of args.updateIncludes: watch is a long-running
+        // live loop with no point at which "refetch and rewrite the lock" makes
+        // sense, so it ignores the flag by design rather than inheriting the shared
+        // session's mode (mirrors studio.ts's own hardcoded 'locked' session).
+        if (args.updateIncludes)
+            console.error('ignoring --update-includes: watch always runs locked');
+        const dir = args.files[0] ?? '.diagrams/src';
+        const watchSnap = snapshotSession(resolveInclude, '.diagrams', 'locked');
+        startWatch(dir, args.out, {
+            coreEntry: home.coreEntry,
+            resolver: watchSnap.resolver,
+            onEvent: (e) => {
+                // Success goes to stdout, failure to stderr, so the streams stay parsed
+                // separately by anyone piping them.
+                if (e.ok)
+                    console.log(formatCompileEvent(e));
+                else
+                    console.error(formatCompileEvent(e));
+            },
+        });
+        console.log(`Watching ${dir} for *.diagram.{ts,json} changes...`);
+    }
+    else if (args.command === 'publish') {
+        if (!existsSync(home.viewerShell)) {
+            // Only a checkout can be missing it; an installed package ships the shell,
+            // so there the message would send the reader off to build a repo they
+            // do not have.
+            console.error(home.layout === 'monorepo'
+                ? 'viewer shell not built — run `pnpm --filter @diagc/viewer build` in the monorepo.'
+                : `viewer shell missing from this install (${home.viewerShell}) — reinstall diagc.`);
+            process.exit(1);
+        }
+        const srcDir = '.diagrams/src';
+        const artifactsDir = '.diagrams/.artifacts';
+        // Compile first so artifacts reflect current sources (TS + include expansion).
+        const sources = await fg('**/*.diagram.{ts,json}', { cwd: srcDir, absolute: true });
+        for (const f of sources) {
+            try {
+                await compileFile(f, artifactsDir, { rootDir: srcDir, coreEntry: home.coreEntry, resolver: snap.resolver });
+            }
+            catch (e) {
+                console.error(`✗ ${f}\n${errMessage(e)}`);
+            }
+        }
+        // publish's glob above ignores args.files (that only scopes which rendered
+        // pages come out below), so it always compiles the whole source tree —
+        // an update run here is always full-tree, so the prune is unguarded.
+        if (args.updateIncludes)
+            await snap.prune();
+        let images = args.images;
+        let renderPng;
+        if (args.images) {
+            const snapshot = await import('./publish/snapshot.js');
+            if (snapshot.findChrome() === undefined) {
+                console.log('No Chrome found — writing HTML only; install Chrome / set CHROME_PATH, or use --no-images.');
+                images = false;
+            }
+            else {
+                renderPng = snapshot.renderPng;
+            }
+        }
+        const res = await publishDiagrams({
+            srcDir,
+            artifactsDir,
+            htmlDir: '.diagrams/html',
+            staticDir: '.diagrams/static',
+            shellPath: home.viewerShell,
+            libraryDir: home.libraryDir,
+            assetsDir: path.join(srcDir, 'assets'),
+            images,
+            names: args.files,
+            ...(renderPng !== undefined ? { renderPng } : {}),
+        });
+        console.log(`✓ ${res.pages.length} page(s) -> .diagrams/html`);
+        if (res.images.length > 0)
+            console.log(`✓ ${res.images.length} image(s) -> .diagrams/static`);
+        console.log(`✓ gallery -> ${res.gallery}`);
+        process.exit(0);
+    }
+    else if (args.command === 'studio') {
+        // Studio's own compile-watch loop always resolves includes locked (see
+        // studio.ts) — same reasoning as watch above.
+        if (args.updateIncludes)
+            console.error('ignoring --update-includes: studio always runs locked');
+        await runStudio(home, process.cwd());
+        return;
+    }
+    else if (args.command === 'eject') {
+        // ejectDiagram's post-swap recompile always resolves includes locked (see
+        // eject.ts) — same reasoning as watch above.
+        if (args.updateIncludes)
+            console.error('ignoring --update-includes: eject always runs locked');
+        const name = args.files[0]?.replace(/^\.diagrams\/src\//, '').replace(/\.diagram\.(ts|json)$/, '');
+        if (name === undefined || name === '') {
+            console.error('diagc: eject needs a diagram name.');
+            console.error(USAGE);
+            process.exit(1);
+        }
+        try {
+            const res = await ejectDiagram('.diagrams/src', args.out, name, { coreEntry: home.coreEntry });
+            console.log(`✓ ${res.tsPath}`);
+            process.exit(0);
+        }
+        catch (e) {
+            console.error(errMessage(e));
+            process.exit(1);
+        }
+    }
+    else {
+        console.error(`diagc: Unknown command '${args.command}'.`);
+        console.error(USAGE);
+        process.exit(1);
+    }
+}
+main().catch((e) => {
+    console.error(errMessage(e));
+    process.exit(1);
+});

package/dist/compile.d.ts

@@ -0,0 +1,11 @@
+import { type DiagramModel, type IncludeResolver } from '@diagc/core';
+/**
+ * Execute a `.diagram.ts` through jiti (core pinned to `coreEntry`) and return
+ * its model — shape-guarded but not validated; callers own validation.
+ */
+export declare function executeDiagramTs(file: string, coreEntry?: string): Promise<DiagramModel>;
+export declare function compileFile(file: string, outDir: string, opts?: {
+    rootDir?: string;
+    coreEntry?: string;
+    resolver?: IncludeResolver;
+}): Promise<string>;

package/dist/compile.js

@@ -0,0 +1,106 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { createJiti } from 'jiti';
+import { composeIncludes, DiagramValidationError, validate, } from '@diagc/core';
+import { resolveInclude } from './includes.js';
+import { snapshotSession } from './snapshots.js';
+/**
+ * Shape guard: with `{ default: true }` jiti returns the module NAMESPACE when
+ * there is no default export, so a default-less file would otherwise be written
+ * verbatim. Reject anything that is not a diagram model before we validate it.
+ */
+function assertDiagramShape(model, file) {
+    if (typeof model !== 'object' ||
+        model === null ||
+        model.version !== 1 ||
+        !Array.isArray(model.nodes)) {
+        throw new Error(`${file}: no default export or not a diagram model`);
+    }
+}
+/**
+ * Execute a `.diagram.ts` through jiti (core pinned to `coreEntry`) and return
+ * its model — shape-guarded but not validated; callers own validation.
+ */
+export async function executeDiagramTs(file, coreEntry) {
+    // Always pin @diagc/core to the copy visible from this file. Bare
+    // resolution from the diagram's own location only works when the diagram
+    // lives under a node_modules-covered tree (it fails for e.g. /tmp), so
+    // `coreEntry` is not just a safeguard — without a default, compilation is
+    // at the mercy of the install layout.
+    const resolvedCoreEntry = coreEntry ?? createRequire(import.meta.url).resolve('@diagc/core');
+    const jiti = createJiti(import.meta.url, {
+        moduleCache: false,
+        alias: { '@diagc/core': resolvedCoreEntry },
+    });
+    const def = await jiti.import(path.resolve(file), { default: true });
+    const hasToJSON = typeof def?.toJSON === 'function';
+    const model = (hasToJSON ? def.toJSON() : def);
+    assertDiagramShape(model, file);
+    return model;
+}
+/**
+ * Resolve the subdirectory of `file` relative to `rootDir` so nested diagram
+ * files map to nested artifacts instead of clobbering each other by basename.
+ * Returns '' (flat) when there is no rootDir, the file is a top-level child of
+ * rootDir, or the file lives outside rootDir.
+ */
+function relativeSubdir(file, rootDir) {
+    if (!rootDir)
+        return '';
+    const rel = path.relative(path.resolve(rootDir), path.resolve(file));
+    if (rel.startsWith('..') || path.isAbsolute(rel))
+        return '';
+    const dir = path.dirname(rel);
+    return dir === '.' ? '' : dir;
+}
+export async function compileFile(file, outDir, opts) {
+    const isJsonSource = file.endsWith('.diagram.json');
+    let model;
+    if (isJsonSource) {
+        const def = JSON.parse(await readFile(path.resolve(file), 'utf8'));
+        const hasToJSON = typeof def?.toJSON === 'function';
+        model = (hasToJSON ? def.toJSON() : def);
+        assertDiagramShape(model, file);
+    }
+    else {
+        model = await executeDiagramTs(file, opts?.coreEntry);
+    }
+    // Validate unconditionally. The builder path already validated inside toJSON,
+    // but plain-object default exports never touched validate() — and re-validating
+    // the builder's output here is harmless and keeps a single code path. `validate`
+    // is a pure function, so there is no jiti class-identity problem, and the
+    // DiagramValidationError is constructed in this module world (instanceof works).
+    //
+    // Validate the authored source first (its own duplicate keys etc. must fail
+    // before composition would silently merge them), then expand includes and
+    // validate the composed result too.
+    const sourceIssues = validate(model);
+    if (sourceIssues.length > 0)
+        throw new DiagramValidationError(sourceIssues);
+    if (model.nodes.some((n) => n.include !== undefined)) {
+        // Default to a locked snapshot resolver rooted at rootDir's parent (the
+        // .diagrams root, same derivation as eject.ts): a call site that forgets
+        // to pass `resolver` must fail on an unsnapshotted remote include, not
+        // silently reintroduce live fetching. Local includes pass through either
+        // way; only without a rootDir to anchor the vendor dir does the raw
+        // resolver remain the fallback.
+        const resolver = opts?.resolver ??
+            (opts?.rootDir !== undefined
+                ? snapshotSession(resolveInclude, path.dirname(path.resolve(opts.rootDir)), 'locked').resolver
+                : resolveInclude);
+        const { model: composed, warnings } = await composeIncludes(model, path.resolve(file), resolver);
+        for (const w of warnings)
+            console.warn(`${file}: ${w}`);
+        model = composed;
+        const issues = validate(model);
+        if (issues.length > 0)
+            throw new DiagramValidationError(issues);
+    }
+    const base = path.basename(file).replace(/\.diagram\.(ts|json)$/, '');
+    const artifactDir = path.join(outDir, relativeSubdir(file, opts?.rootDir));
+    await mkdir(artifactDir, { recursive: true });
+    const artifact = path.join(artifactDir, `${base}.diagram.json`);
+    await writeFile(artifact, `${JSON.stringify(model, null, 2)}\n`);
+    return artifact;
+}

package/dist/eject.d.ts

@@ -0,0 +1,24 @@
+import { type DiagramModel } from '@diagc/core';
+export type EjectFailure = 'not-found' | 'already-ts' | 'invalid' | 'mismatch';
+export declare class EjectError extends Error {
+    readonly code: EjectFailure;
+    constructor(message: string, code: EjectFailure);
+}
+export interface EjectOptions {
+    coreEntry?: string;
+    /** test seam: replaces the emitter, so a mismatch is constructible */
+    emit?: (model: DiagramModel) => string;
+}
+/** Paths (dot-joined) where two models first differ, capped for readability. */
+export declare function diffPaths(a: unknown, b: unknown, limit?: number): string[];
+/**
+ * Promote `<name>.diagram.json` to a generated `<name>.diagram.ts` — but only
+ * after executing the generated source and proving it rebuilds the identical
+ * model. Every failure path leaves the source directory exactly as found; the
+ * TS is written before the JSON is deleted, so a crash between the two steps
+ * leaves both — they then compile to the same artifact (last write wins), and
+ * recovery is deleting whichever source is unwanted.
+ */
+export declare function ejectDiagram(diagramsDir: string, artifactsDir: string, name: string, opts?: EjectOptions): Promise<{
+    tsPath: string;
+}>;

package/dist/eject.js

@@ -0,0 +1,121 @@
+import { access, mkdtemp, readFile, rm, unlink, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
+import { ejectSource, errMessage, validate } from '@diagc/core';
+import { compileFile, executeDiagramTs } from './compile.js';
+import { resolveInclude } from './includes.js';
+import { snapshotSession } from './snapshots.js';
+export class EjectError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+        this.name = 'EjectError';
+    }
+}
+/** Paths (dot-joined) where two models first differ, capped for readability. */
+export function diffPaths(a, b, limit = 10) {
+    const out = [];
+    const walk = (x, y, at) => {
+        if (out.length >= limit || isDeepStrictEqual(x, y))
+            return;
+        const xo = typeof x === 'object' && x !== null;
+        const yo = typeof y === 'object' && y !== null;
+        if (!xo || !yo) {
+            out.push(at === '' ? '(root)' : at);
+            return;
+        }
+        const keys = new Set([...Object.keys(x), ...Object.keys(y)]);
+        for (const k of keys) {
+            if (out.length >= limit)
+                return;
+            walk(x[k], y[k], at === '' ? k : `${at}.${k}`);
+        }
+    };
+    walk(a, b, '');
+    return out;
+}
+/**
+ * Promote `<name>.diagram.json` to a generated `<name>.diagram.ts` — but only
+ * after executing the generated source and proving it rebuilds the identical
+ * model. Every failure path leaves the source directory exactly as found; the
+ * TS is written before the JSON is deleted, so a crash between the two steps
+ * leaves both — they then compile to the same artifact (last write wins), and
+ * recovery is deleting whichever source is unwanted.
+ */
+export async function ejectDiagram(diagramsDir, artifactsDir, name, opts) {
+    const jsonPath = path.join(diagramsDir, `${name}.diagram.json`);
+    const tsPath = path.join(diagramsDir, `${name}.diagram.ts`);
+    try {
+        await access(tsPath);
+        throw new EjectError(`'${name}' is already TypeScript-owned (${tsPath})`, 'already-ts');
+    }
+    catch (e) {
+        if (e instanceof EjectError)
+            throw e;
+        /* no TS source — proceed */
+    }
+    let raw;
+    try {
+        raw = await readFile(jsonPath, 'utf8');
+    }
+    catch {
+        throw new EjectError(`no diagram '${name}' (${jsonPath})`, 'not-found');
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (e) {
+        throw new EjectError(`'${name}' is not valid JSON: ${errMessage(e)}`, 'invalid');
+    }
+    const issues = validate(parsed);
+    if (issues.length > 0) {
+        throw new EjectError(`'${name}' fails validation; fix it before ejecting:\n${issues.map((i) => `  ${i.message}`).join('\n')}`, 'invalid');
+    }
+    // A validate-clean model can still hold a value the emitter genuinely
+    // cannot express (e.g. `undefined` reaching tsLiteral); classify that as a
+    // refusal instead of letting a plain Error escape the taxonomy — otherwise
+    // the API 500s and the CLI prints a bare, uncontextualized message.
+    let source;
+    try {
+        source = (opts?.emit ?? ejectSource)(parsed);
+    }
+    catch (e) {
+        throw new EjectError(`cannot eject '${name}': ${errMessage(e)}`, 'invalid');
+    }
+    // Execute from a temp dir outside the source glob, so a running compile
+    // watcher never sees the candidate file. coreEntry makes /tmp resolvable.
+    const tmpDir = await mkdtemp(path.join(os.tmpdir(), 'diagc-eject-'));
+    let rebuilt;
+    try {
+        const tmpFile = path.join(tmpDir, `${path.basename(name)}.diagram.ts`);
+        await writeFile(tmpFile, source);
+        try {
+            rebuilt = await executeDiagramTs(tmpFile, opts?.coreEntry);
+        }
+        catch (e) {
+            throw new EjectError(`generated source failed to execute: ${errMessage(e)}`, 'mismatch');
+        }
+    }
+    finally {
+        await rm(tmpDir, { recursive: true, force: true });
+    }
+    if (!isDeepStrictEqual(rebuilt, parsed)) {
+        throw new EjectError(`generated source does not reproduce the model — refusing to replace. Differs at:\n${diffPaths(rebuilt, parsed)
+            .map((p) => `  ${p}`)
+            .join('\n')}`, 'mismatch');
+    }
+    await writeFile(tsPath, source);
+    await unlink(jsonPath);
+    // path.dirname(diagramsDir) is the .diagrams root when diagramsDir is
+    // .diagrams/src — the same rootDir a locked session uses elsewhere.
+    const snap = snapshotSession(resolveInclude, path.dirname(diagramsDir), 'locked');
+    await compileFile(tsPath, artifactsDir, {
+        rootDir: diagramsDir,
+        resolver: snap.resolver,
+        ...(opts?.coreEntry !== undefined ? { coreEntry: opts.coreEntry } : {}),
+    });
+    return { tsPath };
+}

package/dist/home.d.ts

@@ -0,0 +1,36 @@
+/** Which of the two shipping shapes the CLI is running from.
+ *
+ * - `monorepo`: a checkout (or a `pnpm link --global` bin pointing into one).
+ *   Assets are read from `apps/`, the studio runs on Vite, core is TS source.
+ * - `packaged`: installed from the registry. Assets were staged into the
+ *   package at build time, the studio is a prebuilt bundle served by our own
+ *   http server, and core is the published dependency. */
+export type HomeLayout = 'monorepo' | 'packaged';
+export interface HomePaths {
+    root: string;
+    layout: HomeLayout;
+    /** single-file viewer HTML that `publish` stamps models into */
+    viewerShell: string;
+    /** icon/shape library that `publish` inlines `/library/...` refs from */
+    libraryDir: string;
+    /** module `@diagc/core` is aliased to when jiti executes a `.diagram.ts` */
+    coreEntry: string;
+    /** monorepo: the studio's Vite root; packaged: the prebuilt studio bundle */
+    studioDir: string;
+}
+export interface Home {
+    root: string;
+    layout: HomeLayout;
+}
+/** Locate the CLI's home and decide which layout it is.
+ *
+ * A workspace anywhere above wins over a packaged marker, even though the
+ * marker sits closer: once assets have been staged into `packages/diagc/assets`
+ * for a release, a depth-ordered search would find them first and quietly put a
+ * development checkout into packaged mode. */
+export declare function findHome(startPath: string): Home;
+/** Resolve the installed `@diagc/core` entry from this module's location,
+ * so jiti aliases a user's `.diagram.ts` to the very copy the CLI itself uses.
+ * Injectable for tests; the default is the real resolver. */
+export declare function resolveCoreEntry(resolve?: (id: string) => string): string;
+export declare function homePaths(home: Home, coreEntry?: typeof resolveCoreEntry): HomePaths;

package/dist/home.js

@@ -0,0 +1,75 @@
+import { existsSync, realpathSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+/** Marker that identifies a packaged install: the staged viewer shell. It is
+ * the one file `publish` cannot work without, so if it is missing the install
+ * is broken whatever we decide to call it. */
+const PACKAGED_MARKER = path.join('assets', 'viewer', 'index.html');
+/** Every directory from `startPath`'s realpath up to the filesystem root.
+ * Resolving the realpath first is what lets a globally linked bin find its
+ * source checkout through the symlink. */
+function ancestors(startPath) {
+    const out = [];
+    let dir = path.dirname(realpathSync(startPath));
+    for (;;) {
+        out.push(dir);
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return out;
+        dir = parent;
+    }
+}
+/** Locate the CLI's home and decide which layout it is.
+ *
+ * A workspace anywhere above wins over a packaged marker, even though the
+ * marker sits closer: once assets have been staged into `packages/diagc/assets`
+ * for a release, a depth-ordered search would find them first and quietly put a
+ * development checkout into packaged mode. */
+export function findHome(startPath) {
+    const dirs = ancestors(startPath);
+    for (const dir of dirs) {
+        if (existsSync(path.join(dir, 'pnpm-workspace.yaml')))
+            return { root: dir, layout: 'monorepo' };
+    }
+    for (const dir of dirs) {
+        if (existsSync(path.join(dir, PACKAGED_MARKER)) && existsSync(path.join(dir, 'package.json'))) {
+            return { root: dir, layout: 'packaged' };
+        }
+    }
+    throw new Error('cannot locate diagc home (expected an installed package with assets/, or a monorepo with pnpm-workspace.yaml above the bin); reinstall diagc, or re-run `pnpm link --global` from the monorepo.');
+}
+/** Resolve the installed `@diagc/core` entry from this module's location,
+ * so jiti aliases a user's `.diagram.ts` to the very copy the CLI itself uses.
+ * Injectable for tests; the default is the real resolver. */
+export function resolveCoreEntry(resolve = createRequire(import.meta.url).resolve) {
+    try {
+        return resolve('@diagc/core');
+    }
+    catch {
+        throw new Error("diagc is installed without its '@diagc/core' dependency — reinstall it (npm i -g @diagc/cli).");
+    }
+}
+export function homePaths(home, coreEntry = resolveCoreEntry) {
+    const { root, layout } = home;
+    if (layout === 'packaged') {
+        const studioDir = path.join(root, 'assets', 'studio');
+        return {
+            root,
+            layout,
+            viewerShell: path.join(root, 'assets', 'viewer', 'index.html'),
+            // The studio bundle carries its own `public/library` through the Vite
+            // build, so publish and the studio server read one staged copy.
+            libraryDir: path.join(studioDir, 'library'),
+            coreEntry: coreEntry(),
+            studioDir,
+        };
+    }
+    return {
+        root,
+        layout,
+        viewerShell: path.join(root, 'apps', 'viewer', 'dist', 'index.html'),
+        libraryDir: path.join(root, 'apps', 'studio', 'public', 'library'),
+        coreEntry: path.join(root, 'packages', 'core', 'src', 'index.ts'),
+        studioDir: path.join(root, 'apps', 'studio'),
+    };
+}

package/dist/includes.d.ts

@@ -0,0 +1,5 @@
+import type { IncludeSource } from '@diagc/core';
+/** diagc's include IO: http(s) URLs via fetch, everything else via the
+ * filesystem relative to the declaring file. Returns the canonical resolved
+ * ref so compose can detect cycles across mixed URL/path chains. */
+export declare function resolveInclude(spec: string, fromRef: string): Promise<IncludeSource>;

package/dist/includes.js

@@ -0,0 +1,17 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+const isHttp = (s) => /^https?:\/\//.test(s);
+/** diagc's include IO: http(s) URLs via fetch, everything else via the
+ * filesystem relative to the declaring file. Returns the canonical resolved
+ * ref so compose can detect cycles across mixed URL/path chains. */
+export async function resolveInclude(spec, fromRef) {
+    if (isHttp(spec) || isHttp(fromRef)) {
+        const url = isHttp(spec) ? spec : new URL(spec, fromRef).href;
+        const res = await fetch(url);
+        if (!res.ok)
+            throw new Error(`HTTP ${res.status} fetching ${url}`);
+        return { model: (await res.json()), ref: url };
+    }
+    const file = path.resolve(path.dirname(fromRef), spec);
+    return { model: JSON.parse(await readFile(file, 'utf8')), ref: file };
+}