portograph 0.0.0-stage → 0.2.0

package/bin/cli.mjs

@@ -0,0 +1,256 @@
+// portograph command line. Plain JavaScript: it loads the built library from
+// dist/ at run time, so `npm run build` must run before the CLI is usable.
+//
+// This process parses arguments, prints diagnostics to stderr and writes artifacts. It does no
+// layout work itself. `layout`, `render` and `score` run in one child process (`compute.mjs`),
+// because that is the only boundary that can really stop them: ELK and libavoid run in worker
+// threads *inside* that child, and `score()` is synchronous, so an in-thread timer or a
+// `Promise.race` could not interrupt either. The parent owns the single absolute deadline and
+// kills the child on expiry, which takes its worker threads with it.
+import { fork } from 'node:child_process';
+import { existsSync, lstatSync, mkdtempSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import * as nodeModule from 'node:module';
+import { fileURLToPath } from 'node:url';
+import { VERDANA_WARNING, verdanaInstalled } from './font-check.mjs';
+
+// Node 22.1 and newer keep the compiled code of the library on disk between runs; older Node has no such call. The cache holds compiled code only.
+nodeModule.enableCompileCache?.();
+const require = nodeModule.createRequire(import.meta.url);
+const { version } = require('../package.json');
+const COMPUTE = fileURLToPath(new URL('./compute.mjs', import.meta.url));
+
+async function loadLibrary() {
+  try {
+    return await import('../dist/portograph.js');
+  } catch (error) {
+    // A missing solver package is also ERR_MODULE_NOT_FOUND; only a missing bundle means "build first".
+    if (error && error.code === 'ERR_MODULE_NOT_FOUND' && !existsSync(new URL('../dist/portograph.js', import.meta.url))) {
+      throw new Error('portograph: build output missing; run `npm run build` first', { cause: error });
+    }
+    throw error;
+  }
+}
+
+/** All of a stream as UTF-8 text; stdin is read here, in the parent, so the child needs no handle on it. */
+async function readAll(stream) {
+  const chunks = [];
+  for await (const chunk of stream) chunks.push(typeof chunk === 'string' ? Buffer.from(chunk) : chunk);
+  return Buffer.concat(chunks).toString('utf8');
+}
+
+/** The deadline a command really gets. The environment override exists so tests can prove the
+ * termination path with real computational work instead of waiting a minute. */
+function deadlineMs(fallback) {
+  const raw = process.env.PORTOGRAPH_COMMAND_DEADLINE_MS;
+  if (raw === undefined) return fallback;
+  const value = Number(raw);
+  if (!Number.isFinite(value) || value <= 0) throw new Error(`portograph: PORTOGRAPH_COMMAND_DEADLINE_MS must be a positive number of milliseconds`);
+  return value;
+}
+
+/**
+ * When the deadline clock starts. A test hook only: `PORTOGRAPH_COMMAND_DEADLINE_FROM=elk-worker`
+ * starts the `PORTOGRAPH_COMMAND_DEADLINE_MS` clock when the first ELK worker starts, so a test can
+ * prove the kill during real ELK work on a host of any speed. Until then, the shipped deadline holds.
+ */
+function deadlinePlan(fallback) {
+  const limitMs = deadlineMs(fallback);
+  const from = process.env.PORTOGRAPH_COMMAND_DEADLINE_FROM;
+  if (from === undefined) return { startMs: limitMs };
+  if (from !== 'elk-worker') throw new Error(`portograph: PORTOGRAPH_COMMAND_DEADLINE_FROM must be elk-worker`);
+  return { startMs: fallback, elkMs: limitMs };
+}
+
+/**
+ * Run the compute job in a child process under one absolute deadline.
+ *
+ * Returns `{ ok: true, result }`, or `{ ok: false, kind, message, diagnostics }` where `kind` is
+ * `input` or `processing`. Progress and diagnostics reach `io.err` while the child still runs, so
+ * a long command is not silent.
+ */
+function compute(request, io, plan, inputText) {
+  return new Promise((resolve) => {
+    // The child's own budget always counts from the start. The test hook moves only this process's deadline.
+    const commandDeadlineAt = Date.now() + plan.startMs;
+    let deadlineAt = commandDeadlineAt, limitText = `${plan.startMs} ms`, timer, elkArmed = false;
+    let child;
+    try {
+      child = fork(COMPUTE, [], { stdio: ['ignore', 'pipe', 'pipe', 'ipc'] });
+    } catch (error) {
+      resolve({ ok: false, kind: 'processing', message: `could not start the compute process: ${error.message}`, diagnostics: [] });
+      return;
+    }
+    // Nothing the child writes to its own streams is ever an artifact. Forward both to stderr so a
+    // worker crash is visible without being able to pollute the primary artifact on stdout.
+    for (const stream of [child.stdout, child.stderr]) stream?.on('data', (chunk) => io.err.write(chunk));
+
+    if (process.env.PORTOGRAPH_PROGRESS === '1') io.err.write(`portograph: compute process ${child.pid}\n`);
+    let settled = false;
+    const finish = (value) => {
+      if (settled) return;
+      if (value.ok && Date.now() >= deadlineAt) value = { ok: false, kind: 'processing', code: 'COMMAND_DEADLINE',
+        message: `the command did not finish within ${limitText}; no artifacts were published` };
+      settled = true;
+      clearTimeout(timer);
+      // Whatever the outcome, this process tree stops here: SIGKILL cannot be caught or delayed,
+      // and it takes the child's ELK and libavoid worker threads with it.
+      if (child.exitCode !== null || child.signalCode !== null) { resolve(value); return; }
+      child.once('exit', () => resolve(value));
+      child.kill('SIGKILL');
+    };
+    const arm = () => {
+      clearTimeout(timer);
+      timer = setTimeout(() => {
+        finish({ ok: false, kind: 'processing', code: 'COMMAND_DEADLINE',
+          message: `the command did not finish within ${limitText}; no layout, score or gate result was produced` });
+      }, Math.max(1, deadlineAt - Date.now()));
+    };
+    arm();
+
+    child.on('message', (message) => {
+      if (message.type === 'diagnostic' || message.type === 'progress') io.err.write(`${message.text}\n`);
+      else if (message.type === 'result') finish(message.value);
+      else if (message.type === 'elk-worker' && plan.elkMs !== undefined && !elkArmed && !settled) {
+        elkArmed = true;
+        deadlineAt = Date.now() + plan.elkMs;
+        limitText = `${plan.elkMs} ms after the ELK worker started`;
+        arm();
+      }
+    });
+    child.on('error', (error) => finish({ ok: false, kind: 'processing', message: `compute process failed: ${error.message}` }));
+    // A queued result message is delivered before this turn of the loop ends; defer so an exit
+    // that follows a successful send is not mistaken for a silent death.
+    child.on('exit', (code, signal) => setImmediate(() => finish({ ok: false, kind: 'processing',
+      message: `compute process ended without a result (${signal ? `signal ${signal}` : `exit code ${code}`})` })));
+    child.send({ type: 'run', request, inputText, deadlineAt: commandDeadlineAt });
+  });
+}
+
+/** Stage every artifact before replacing any destination; roll back the set on an I/O failure. */
+function publishArtifacts(entries) {
+  for (const [path] of entries) {
+    if (existsSync(path) && !lstatSync(path).isFile() && !lstatSync(path).isSymbolicLink()) {
+      throw new Error(`${path} is not a file`);
+    }
+  }
+  const temporary = mkdtempSync(join(dirname(entries[0][0]), '.portograph-'));
+  const installed = [], saved = [];
+  let removeTemporary = true;
+  try {
+    for (const [index, [, contents]] of entries.entries()) writeFileSync(join(temporary, `new-${index}`), contents);
+    for (const [index, [path]] of entries.entries()) {
+      const backup = join(temporary, `old-${index}`);
+      // lstat also sees a dangling symlink, which existsSync deliberately does not.
+      try { lstatSync(path); renameSync(path, backup); saved.push([path, backup]); }
+      catch (error) { if (error.code !== 'ENOENT') throw error; }
+      renameSync(join(temporary, `new-${index}`), path);
+      installed.push(path);
+    }
+  } catch (error) {
+    try {
+      for (const path of installed.reverse()) rmSync(path, { force: true });
+      for (const [path, backup] of saved.reverse()) renameSync(backup, path);
+    } catch (rollbackError) {
+      removeTemporary = false;
+      throw new Error(`${error.message}; rollback failed: ${rollbackError.message}; retained backups in ${temporary}`, { cause: rollbackError });
+    }
+    throw error;
+  } finally {
+    if (removeTemporary) rmSync(temporary, { recursive: true, force: true });
+  }
+}
+
+function writeArtifacts(command, result, io, library) {
+  const { EXIT, sidecarPaths, formatStatus } = library;
+  const status = (severity, code, message) => io.err.write(`${formatStatus(command.diagnostics, severity, code, message)}\n`);
+  if (command.output === undefined) {
+    io.out.write(result.primary);
+    if (!result.primary.endsWith('\n')) io.out.write('\n');
+  } else {
+    try {
+      if (result.sidecars) {
+        const paths = sidecarPaths(command.output);
+        publishArtifacts([[command.output, result.primary], [paths.layout, result.sidecars.layout], [paths.score, result.sidecars.score]]);
+        status('info', 'WROTE', `wrote ${command.output}, ${paths.layout}, ${paths.score}`);
+      } else {
+        publishArtifacts([[command.output, result.primary]]);
+        status('info', 'WROTE', `wrote ${command.output}`);
+      }
+    } catch (error) {
+      status('error', 'OUTPUT_FAILED', `cannot write ${command.output}: ${error.message}`);
+      return EXIT.inputError;
+    }
+  }
+  if (result.passed === false) {
+    status('error', 'GATE_FAILED', 'an enforced gate or assertion failed; see the score report');
+    return command.allowGateFailures ? EXIT.ok : EXIT.gateFailure;
+  }
+  return EXIT.ok;
+}
+
+/**
+ * Run the CLI on `argv` (without the node and script paths).
+ * Writes to `io.out` / `io.err` and returns the process exit code.
+ */
+export async function main(argv, io = { out: process.stdout, err: process.stderr, in: process.stdin }) {
+  const library = await loadLibrary();
+  const { COMMAND_DEADLINE_MS, EXIT, formatStatus, helpText, isVerb, parseCommand } = library;
+  const [verb, ...rest] = argv;
+
+  if (verb === undefined || verb === '--help' || verb === '-h') {
+    io.out.write(helpText());
+    return EXIT.ok;
+  }
+  if (verb === '--version' || verb === '-V') {
+    io.out.write(`${version}\n`);
+    return EXIT.ok;
+  }
+  if (!isVerb(verb)) {
+    io.err.write(`portograph: unknown verb '${verb}'\n\n${helpText()}`);
+    return EXIT.inputError;
+  }
+  if (rest.includes('--help') || rest.includes('-h')) {
+    io.out.write(helpText());
+    return EXIT.ok;
+  }
+
+  let command;
+  try {
+    command = parseCommand(verb, rest);
+  } catch (error) {
+    // A caller that asked for JSON gets JSON for a usage error too; the option is read before parsing fails.
+    const asJson = rest.includes('--diagnostics=json') || rest.some((argument, index) => argument === '--diagnostics' && rest[index + 1] === 'json');
+    if (asJson) io.err.write(`${formatStatus('json', 'error', 'USAGE', error.message)}\n`);
+    else io.err.write(`portograph: ${error.message}\n\nRun 'portograph --help' for the full usage.\n`);
+    return EXIT.inputError;
+  }
+
+  let plan;
+  try {
+    plan = deadlinePlan(COMMAND_DEADLINE_MS);
+  } catch (error) {
+    io.err.write(`${error.message}\n`);
+    return EXIT.inputError;
+  }
+
+  let inputText;
+  if (command.input === '-') {
+    try {
+      inputText = await readAll(io.in);
+    } catch (error) {
+      io.err.write(`${formatStatus(command.diagnostics, 'error', 'STDIN_FAILED', `cannot read stdin: ${error.message}`)}\n`);
+      return EXIT.inputError;
+    }
+  }
+
+  // Only the CLI looks at the machine's fonts; the library output stays a pure function of the document.
+  if ((verb === 'render' || verb === 'layout') && !verdanaInstalled()) {
+    io.err.write(`${formatStatus(command.diagnostics, 'warning', 'FONT_MISSING', VERDANA_WARNING, true)}\n`);
+  }
+
+  const outcome = await compute(command, io, plan, inputText);
+  if (outcome.ok) return writeArtifacts(command, outcome.result, io, library);
+  io.err.write(`${formatStatus(command.diagnostics, 'error', outcome.code ?? (outcome.kind === 'input' ? 'INVALID_INPUT' : 'FAILED'), outcome.message, Boolean(outcome.code))}\n`);
+  return outcome.kind === 'input' ? EXIT.inputError : EXIT.processingFailure;
+}

package/bin/compute.mjs

@@ -0,0 +1,177 @@
+// The CLI's compute boundary. One command's whole job runs here, in a child process the parent
+// can really terminate: ELK and libavoid run in worker threads inside this process, and `score()`
+// is a synchronous loop, so nothing inside could interrupt itself. The parent kills this process
+// when its deadline expires, which takes the worker threads with it.
+//
+// This process writes no artifact and no diagnostic of its own. It returns strings to the parent,
+// which owns stdout, stderr and the files.
+import { readFileSync } from 'node:fs';
+import * as nodeModule from 'node:module';
+
+// Node 22.1 and newer keep the compiled code of the library and of its packages on disk between runs; older Node has no such call. The cache holds compiled code only.
+nodeModule.enableCompileCache?.();
+const require = nodeModule.createRequire(import.meta.url);
+
+function loadLibrary() {
+  return import('../dist/portograph.js');
+}
+
+/** `input` blames the document, `processing` blames the tool: a deadline, an asset, an internal bug. */
+const failure = (kind, message, code) => ({ ok: false, kind, message, ...(code ? { code } : {}) });
+
+function readInput(path, stdinText) {
+  if (path === '-') return { ok: true, text: stdinText ?? '' };
+  try {
+    return { ok: true, text: readFileSync(path, 'utf8') };
+  } catch (error) {
+    return failure('input', `cannot read ${path}: ${error.message}`);
+  }
+}
+
+async function run(request, emit) {
+  const api = await loadLibrary();
+  const { CommandDeadlineError, ElkDeadlineError, RouteDeadlineError, ParseError, ResolveError, createBudget, formatDiagnostic, formatDiagnosticJson, layout,
+    drawio, migrateWithDiagnostics, parseWithDiagnostics, render, restoreFinalLayout, score,
+    serializeLayoutModel } = api;
+
+  const budget = createBudget(Math.max(1, request.deadlineAt - Date.now()));
+  const printed = new Set();
+  const say = (diagnostic, location) => {
+    const key = JSON.stringify(diagnostic);
+    if (printed.has(key)) return;
+    printed.add(key);
+    const place = location === undefined ? undefined : { source: label, ...location };
+    emit({ type: 'diagnostic', text: (request.command.diagnostics === 'json' ? formatDiagnosticJson : formatDiagnostic)(diagnostic, place) });
+  };
+  const progress = process.env.PORTOGRAPH_PROGRESS === '1'
+    ? (event) => emit({ type: 'progress',
+      text: `portograph: ${event.stage} took ${Math.round(event.durationMs)} ms, ${Number.isFinite(event.remainingMs) ? `${Math.round(event.remainingMs)} ms left` : 'no deadline'}` })
+    : undefined;
+
+  const label = request.command.input === '-' ? '<stdin>' : request.command.input;
+  const { verb, input, force, allowGateFailures, timings, layers, format, theme, labels, icons } = request.command;
+  // One place decides what `render` writes, so the restored-layout path and the from-YAML path can
+  // never drift apart on it.
+  const primaryArtifact = (model) => format === 'drawio'
+    ? drawio(model, { ...(layers ? { layers } : {}), ...(theme ? { theme } : {}), ...(labels ? { labels } : {}), ...(icons ? { icons } : {}),
+      onDiagnostic: (diagnostic) => say(diagnostic) })
+    : render(model, layers ? { layers } : {});
+  // Timings change on every run. The published artifacts leave them out unless `--timings` asks.
+  const published = (model) => (timings ? model : { ...model, runtime: { stages: [] } });
+  const publishedReport = (report) => {
+    if (timings) return report;
+    return { snapshot: report.snapshot, runtime: { stages: [] } };
+  };
+  void allowGateFailures; // the parent applies it to the exit code; the report never changes.
+  const source = readInput(input, request.inputText);
+  if (source.ok !== true) return source;
+  if (verb === 'migrate') {
+    const result = migrateWithDiagnostics(source.text, { force });
+    for (const diagnostic of result.diagnostics) say(diagnostic);
+    return result.ok ? { ok: true, result: { primary: result.yaml } }
+      : failure('input', `${label} cannot be migrated`);
+  }
+
+  // `score` reads a serialized layout, never authored YAML. YAML is a superset of JSON, so handing
+  // this text to the parser would "succeed" at reinterpreting a layout model as a document.
+  let serializedLayout = verb === 'score';
+  if (verb === 'render') {
+    try {
+      const candidate = JSON.parse(source.text);
+      serializedLayout = candidate !== null && typeof candidate === 'object'
+        && ['document', 'stage', 'freeze', 'tierBands'].some(key => Object.hasOwn(candidate, key));
+    } catch { /* Authored YAML, or an input error for the schema parser to explain. */ }
+  }
+  if (serializedLayout) {
+    let model;
+    try {
+      model = restoreFinalLayout(source.text);
+    } catch (error) {
+      return failure('input', `${label} is not a final layout: ${error.message}`);
+    }
+    for (const diagnostic of model.diagnostics) say(diagnostic);
+    if (Object.keys(model.nodes).length > 1000 && !force) {
+      return failure('input', `${label} has more than 1000 nodes; ${verb} requires --force`);
+    }
+    const report = score(model, { force });
+    if (verb === 'render') return { ok: true, result: {
+      primary: primaryArtifact(model),
+      sidecars: { layout: `${serializeLayoutModel(published(model))}\n`, score: `${JSON.stringify(publishedReport(report), null, 2)}\n` },
+      passed: report.snapshot.passed,
+    } };
+    return { ok: true, result: { primary: `${JSON.stringify(publishedReport(report), null, 2)}\n`, passed: report.snapshot.passed } };
+  }
+
+  // One ELK worker serves every attempt of this command. It boots on its own thread while the parser runs; a worker that fails to start
+  // is reported after the parse, as before, so an input error is never hidden behind an asset error.
+  let nodeRuntime;
+  let elk;
+  let assetError;
+  try {
+    nodeRuntime = require('../dist/node.cjs');
+    // The warm worker is internal to the CLI: it is built here on the worker file of the installed `elkjs`, not exported by `portograph/node`.
+    const Worker = require('web-worker');
+    const workerUrl = require.resolve('elkjs/lib/elk-worker.min.js');
+    elk = require('../dist/warm-elk.cjs').createWarmElk(api.createWorkerElkAttempt, () => new Worker(workerUrl));
+    elk.warm();
+  } catch (error) {
+    assetError = error;
+  }
+
+  const parsed = parseWithDiagnostics(source.text, { force, onDiagnostic: say });
+  if (!parsed.ok) return failure('input', `${label} has ${parsed.diagnostics.filter((d) => d.severity === 'error').length} error(s)`);
+
+  let router;
+  try {
+    if (assetError) throw assetError;
+    router = nodeRuntime.createNodeRouteFactory();
+  } catch (error) {
+    return failure('processing', `a solver worker or module is unavailable: ${error.message}`, 'WORKER_ASSET');
+  }
+
+  let model;
+  try {
+    model = await layout(parsed.document, {
+      diagnostics: parsed.diagnostics,
+      createElkAttempt: () => {
+        const attempt = elk.attempt();
+        // The test hook of the parent (`PORTOGRAPH_COMMAND_DEADLINE_FROM`) starts its deadline clock here, before the progress line.
+        if (process.env.PORTOGRAPH_COMMAND_DEADLINE_FROM === 'elk-worker') emit({ type: 'elk-worker' });
+        if (progress) emit({ type: 'progress', text: 'portograph: ELK worker started' });
+        return attempt;
+      },
+      createRouteAttempt: router,
+      budget,
+      ...(progress ? { onProgress: progress } : {}),
+    });
+  } catch (error) {
+    if (error instanceof ResolveError || error instanceof ParseError) {
+      for (const diagnostic of error.diagnostics) say(diagnostic);
+      return failure('input', `${label} cannot be laid out`);
+    }
+    if (error instanceof CommandDeadlineError || error instanceof RouteDeadlineError || error instanceof ElkDeadlineError) return failure('processing', error.message, 'COMMAND_DEADLINE');
+    return failure('processing', `layout failed: ${error.message}`, 'PIPELINE_FAILED');
+  }
+  for (const diagnostic of model.diagnostics) say(diagnostic);
+
+  const layoutJson = `${serializeLayoutModel(published(model))}\n`;
+  if (verb === 'layout') return { ok: true, result: { primary: layoutJson } };
+
+  const report = score(model, { force });
+  return { ok: true, result: {
+    primary: primaryArtifact(model),
+    sidecars: { layout: layoutJson, score: `${JSON.stringify(publishedReport(report), null, 2)}\n` },
+    passed: report.snapshot.passed,
+  } };
+}
+
+process.on('message', (message) => {
+  if (message.type !== 'run') return;
+  const emit = (event) => { process.send?.(event); };
+  const send = (value) => {
+    // Flush the result before exiting, so the parent can never see the exit without the answer.
+    process.send?.({ type: 'result', value }, () => { process.exit(0); });
+  };
+  run({ command: message.request, deadlineAt: message.deadlineAt, inputText: message.inputText }, emit)
+    .then(send, (error) => send(failure('processing', `internal error: ${error && error.stack ? error.stack : String(error)}`, 'INTERNAL')));
+});

package/bin/font-check.d.mts

@@ -0,0 +1,4 @@
+/** Is Verdana installed on this machine? The CLI warns when it is not; see `font-check.mjs`. */
+export declare function fontDirectories(platform?: string, env?: Record<string, string | undefined>, home?: string): string[];
+export declare function verdanaInstalled(directories?: string[]): boolean;
+export declare const VERDANA_WARNING: string;

package/bin/font-check.mjs

@@ -0,0 +1,58 @@
+// Is Verdana installed on this machine? The CLI warns when it is not. The library never asks: its output is a
+// pure function of the document, and the text is measured from the checked-in Verdana advances either way.
+// The check is cheap and best effort: it looks in the usual font directories of macOS, Linux and Windows,
+// three levels deep, for a file named like Verdana. A font that only a font server or an application knows is missed.
+import { readdirSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+const FILE = /^verdana.*\.(ttf|otf|ttc)$/i;
+const DEPTH = 3;
+
+/** The usual font directories of the platform. `PORTOGRAPH_FONT_DIRS` (a path-delimited list) replaces them; tests use it. */
+export function fontDirectories(platform = process.platform, env = process.env, home = homedir()) {
+  if (env.PORTOGRAPH_FONT_DIRS !== undefined) return env.PORTOGRAPH_FONT_DIRS.split(platform === 'win32' ? ';' : ':').filter(Boolean);
+  if (platform === 'darwin') {
+    return ['/System/Library/Fonts/Supplemental', '/System/Library/Fonts', '/Library/Fonts', join(home, 'Library/Fonts')];
+  }
+  if (platform === 'win32') {
+    const windows = env.WINDIR ?? env.SystemRoot ?? 'C:\\Windows';
+    const local = env.LOCALAPPDATA ?? join(home, 'AppData', 'Local');
+    return [join(windows, 'Fonts'), join(local, 'Microsoft', 'Windows', 'Fonts')];
+  }
+  return ['/usr/share/fonts', '/usr/local/share/fonts', join(home, '.fonts'), join(home, '.local/share/fonts')];
+}
+
+function linksToFile(path) {
+  try {
+    return statSync(path).isFile();
+  } catch {
+    // A broken link holds no font.
+    return false;
+  }
+}
+
+function hasVerdana(directory, depth) {
+  let entries;
+  try {
+    entries = readdirSync(directory, { withFileTypes: true });
+  } catch {
+    // An absent or unreadable directory holds no font for this check; "not found" is reported only after all of them.
+    return false;
+  }
+  for (const entry of entries) {
+    if (entry.isFile() && FILE.test(entry.name)) return true;
+    // A font manager (Homebrew casks, Nix, fontconfig setups) can link a font file into the directory; the link counts when it ends at a file.
+    if (entry.isSymbolicLink() && FILE.test(entry.name) && linksToFile(join(directory, entry.name))) return true;
+    if (entry.isDirectory() && depth > 1 && hasVerdana(join(directory, entry.name), depth - 1)) return true;
+  }
+  return false;
+}
+
+/** True when a Verdana file sits in one of `directories` (default: the usual ones of this platform). */
+export function verdanaInstalled(directories = fontDirectories()) {
+  return directories.some((directory) => hasVerdana(directory, DEPTH));
+}
+
+export const VERDANA_WARNING =
+  'Verdana is not installed on this machine. Text is measured from Verdana, so a viewer without it draws text that can overflow its box. Install Verdana (see the README).';

package/bin/portograph.mjs

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+// Executable shim. It carries the .mjs extension because the package is
+// "type": "module" and Node refuses to load an extensionless entry point in that
+// context (ERR_UNKNOWN_FILE_EXTENSION).
+import { main } from './cli.mjs';
+
+// A reader that closes early (`portograph layout x.yaml | head`) is not a failure of the tool.
+process.stdout.on('error', (error) => {
+  if (error.code === 'EPIPE') process.exit(0);
+  throw error;
+});
+
+main(process.argv.slice(2)).then(
+  (code) => {
+    process.exitCode = code;
+  },
+  (error) => {
+    // main() returns 2 for every input error it recognises, so anything that escapes it is the
+    // tool failing, not the document: a missing build, an unwritable path, an internal bug.
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 3;
+  },
+);

package/dist/cli.d.cts

@@ -0,0 +1,109 @@
+import { Diagnostic, Layer } from './model/index.cjs';
+import { ThemeMode } from './profiles/network/theme.cjs';
+export declare const VERBS: readonly [{
+    readonly name: "layout";
+    readonly summary: "YAML in, layout JSON out";
+}, {
+    readonly name: "render";
+    readonly summary: "YAML in, SVG plus layout JSON and score out";
+}, {
+    readonly name: "score";
+    readonly summary: "layout JSON in, gates and soft score out";
+}, {
+    readonly name: "migrate";
+    readonly summary: "d3-fd YAML in, schema v2 YAML out";
+}];
+export type Verb = (typeof VERBS)[number]['name'];
+/**
+ * Process exit codes.
+ *
+ * `gateFailure` means a *complete* score report says an enforced gate or assertion failed — the
+ * artifacts are still written, because a failing report is the useful output. `inputError` covers
+ * usage, unreadable files, invalid YAML or JSON, and the node-count refusal. `processingFailure`
+ * covers a command deadline, a missing solver worker or module and any internal pipeline failure:
+ * calling one of those an input error would blame the author for the tool's own limit.
+ */
+export declare const EXIT: {
+    readonly ok: 0;
+    readonly gateFailure: 1;
+    readonly inputError: 2;
+    readonly processingFailure: 3;
+};
+/** Wall milliseconds a whole command may take before its compute boundary is terminated. */
+export declare const COMMAND_DEADLINE_MS = 120000;
+export declare function isVerb(value: string): value is Verb;
+export declare class UsageError extends Error {
+    constructor(message: string);
+}
+/** How diagnostics and status lines reach stderr: a text line each, or one JSON object per line. */
+export declare const DIAGNOSTIC_FORMATS: readonly ["text", "json"];
+export type DiagnosticFormat = (typeof DIAGNOSTIC_FORMATS)[number];
+export interface Command {
+    verb: Verb;
+    /** A path, or `-` for stdin. */
+    input: string;
+    /** Absent means the primary artifact goes to stdout; so does `-`, which parsing drops. */
+    output?: string;
+    /** Absent means `text`. */
+    diagnostics?: DiagnosticFormat;
+    force: boolean;
+    allowGateFailures: boolean;
+    /** Keep the wall-clock stage timings in the layout and score JSON. Absent means they are left out, so two runs write the same bytes. */
+    timings: boolean;
+    /** `render` only. Absent means both families draw and `document.overlays` applies. */
+    layers?: Layer[];
+    /** `render` only. Absent means SVG. */
+    format?: Format;
+    /** `render --format drawio` only. Absent means `auto`: every colour as a light/dark pair. */
+    theme?: ThemeMode | 'auto';
+    /** `render --format drawio` only. Absent means `on-run`. */
+    labels?: LabelPlacement;
+    /** `render --format drawio` only. Absent means `cisco19`. */
+    icons?: IconSet;
+}
+export declare function helpText(): string;
+/** The formats `render` can write. The SVG carries all three palettes; a draw.io file carries one. */
+export declare const FORMATS: readonly ["svg", "drawio"];
+export type Format = (typeof FORMATS)[number];
+/** Where a draw.io link label sits; see `DrawioOptions.labels`. */
+export declare const LABEL_PLACEMENTS: readonly ["on-run", "measured"];
+export type LabelPlacement = (typeof LABEL_PLACEMENTS)[number];
+/** Which glyphs a draw.io export draws; see `DrawioOptions.icons`. */
+export declare const ICON_SETS: readonly ["cisco19", "profile"];
+export type IconSet = (typeof ICON_SETS)[number];
+/**
+ * Parse one already-validated verb's arguments. Options and the single input path may come in any
+ * order, each option at most once, and an option a verb does not accept is a usage error rather
+ * than something quietly ignored.
+ */
+export declare function parseCommand(verb: Verb, args: readonly string[]): Command;
+export declare function sidecarPaths(output: string): {
+    layout: string;
+    score: string;
+};
+/** Where a diagnostic points in the authored text, as `parseWithDiagnostics` reports it. */
+export interface DiagnosticPlace {
+    source: string;
+    line: number;
+    column: number;
+}
+/**
+ * One diagnostic, one stderr line, built from its structured fields. A parse diagnostic keeps its
+ * exact JSONPath and, when the place in the text is known, adds `file:line:col` before it; a later
+ * stage names the objects it is about, because those have no source path.
+ */
+export declare function formatDiagnostic(diagnostic: Diagnostic & {
+    path?: string;
+}, place?: DiagnosticPlace): string;
+/**
+ * The same diagnostic as one JSON object, for `--diagnostics json`. The structured fields stay as
+ * they are; a place in the authored text is added as `source`, `line` and `column`.
+ */
+export declare function formatDiagnosticJson(diagnostic: Diagnostic & {
+    path?: string;
+}, place?: DiagnosticPlace): string;
+/**
+ * A status line of the command itself (not a diagnostic of the document) in the chosen format.
+ * The text form names severity and code only when `showCode` is set, as the coded failures do.
+ */
+export declare function formatStatus(format: DiagnosticFormat | undefined, severity: 'info' | 'warning' | 'error', code: string, message: string, showCode?: boolean): string;