rcf-lite 0.0.1 → 0.8.0

package/src/ruleset/index.js

@@ -0,0 +1,140 @@
+// Shared standards ruleset loader (NV-BL-SR-01, NV-BL-SR-02, NV-BL-SR-03).
+//
+// The ruleset is a single machine-readable artefact bundled inside the
+// rcf-lite umbrella package (JSON, camelCase per estate convention). Both
+// build-lite (as a gate) and rcf-define-lite (as an elicitation checklist,
+// from the umbrella release that adds the define payload) consume the
+// identical ruleset from the identical umbrella version.
+//
+// Per NV-BL-SR-02 (ratified 2026-08-11, ruling-sheet items 2 and 6): the
+// ruleset carries no separate semver. Its version IS the rcf-lite umbrella
+// package version. This loader stamps `rulesetVersion` at read time from
+// the umbrella's package.json so a redeploy of the same JSON on a bumped
+// umbrella version reports the new version without a data edit.
+//
+// Ruleset scope covers chain admissibility AND the estate's traceability
+// and query tooling (ratified 2026-08-11, ruling-sheet item 1 addendum).
+// See toolScope on the artefact.
+
+import { readFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const rulesetPath = join(here, 'ruleset.json');
+const packageJsonPath = resolve(here, '..', '..', 'package.json');
+
+/**
+ * @typedef {object} RulesetRule
+ * @property {string} id
+ * @property {string} title
+ * @property {boolean} [refuseByDefault]
+ * @property {string} [overrideChannel]
+ */
+
+/**
+ * @typedef {object} Ruleset
+ * @property {string} id
+ * @property {string} rulesetVersion - the rcf-lite umbrella package version at load time.
+ * @property {RulesetRule[]} admissibilityRules
+ * @property {RulesetRule[]} gateRules
+ * @property {object} scopeTagVocabulary
+ * @property {Array<{ marker: string, caseInsensitive: boolean }>} sourceCommentMarkers
+ * @property {Array<{ id: string, title: string, surface: string }>} tcTemplateFamily
+ * @property {Array<{ id: string, title: string, kind: string }>} rulingConsistencyChecks
+ * @property {{ chainAdmissibility: boolean, traceabilityAndQueryTools: boolean }} toolScope
+ */
+
+let cachedRuleset = null;
+let cachedUmbrellaVersion = null;
+
+async function readJson(path) {
+  const raw = await readFile(path, 'utf8');
+  return JSON.parse(raw);
+}
+
+/**
+ * The rcf-lite umbrella package version at load time. Used by
+ * `getRuleset()` to stamp `rulesetVersion` per NV-BL-SR-02; also exported
+ * so consumers can read the umbrella version without opening
+ * `package.json` themselves.
+ *
+ * @returns {Promise<string>}
+ */
+export async function getUmbrellaVersion() {
+  if (cachedUmbrellaVersion) return cachedUmbrellaVersion;
+  const pkg = await readJson(packageJsonPath);
+  if (typeof pkg?.version !== 'string' || pkg.version.length === 0) {
+    throw new Error('rcf-lite umbrella package.json is missing a version string');
+  }
+  cachedUmbrellaVersion = pkg.version;
+  return cachedUmbrellaVersion;
+}
+
+/**
+ * Load the shared standards ruleset artefact and stamp its `rulesetVersion`
+ * from the umbrella package.json. The artefact itself carries no version
+ * field (NV-BL-SR-02); read-time stamping is the single source of truth.
+ *
+ * @param {object} [opts]
+ * @param {boolean} [opts.fresh] - bypass the module-scope cache and re-read
+ * @returns {Promise<Ruleset>}
+ */
+export async function getRuleset({ fresh = false } = {}) {
+  if (!fresh && cachedRuleset) return cachedRuleset;
+  const [artefact, umbrellaVersion] = await Promise.all([
+    readJson(rulesetPath),
+    getUmbrellaVersion(),
+  ]);
+  // Defensive: strip any accidental rulesetVersion baked into the JSON so
+  // the umbrella version is authoritative. NV-BL-SR-02 is emphatic about
+  // this: a divergence here is a spec drift, not a data field.
+  delete artefact.rulesetVersion;
+  cachedRuleset = Object.freeze({ ...artefact, rulesetVersion: umbrellaVersion });
+  return cachedRuleset;
+}
+
+/**
+ * Detect whether the ruleset version on a chain differs from the shipping
+ * ruleset version, and classify the drift for NV-BL-ADM-06 (build-stage
+ * refusal) and DL-REQ-VALIDATE-03 (define-stage warning).
+ *
+ * Additive-only drift (only new rule ids appear on the shipping side) is
+ * classified `additive` and warns rather than refuses. Any other version
+ * mismatch is classified `behavioural` and refuses at build stage.
+ *
+ * Same-version comparisons return `{ drift: 'none' }`.
+ *
+ * @param {object} args
+ * @param {string|null|undefined} args.chainRulesetVersion - version the chain declared it was authored against.
+ * @param {Ruleset} [args.ruleset] - shipping ruleset; defaults to the loaded artefact.
+ * @returns {Promise<{ drift: 'none' | 'additive' | 'behavioural' | 'missing', shippingVersion: string, chainVersion: string | null }>}
+ */
+export async function detectRulesetDrift({ chainRulesetVersion, ruleset } = {}) {
+  const shipping = ruleset ?? (await getRuleset());
+  const shippingVersion = shipping.rulesetVersion;
+  const chainVersion = typeof chainRulesetVersion === 'string' && chainRulesetVersion.length > 0
+    ? chainRulesetVersion
+    : null;
+  if (chainVersion === null) {
+    return { drift: 'missing', shippingVersion, chainVersion };
+  }
+  if (chainVersion === shippingVersion) {
+    return { drift: 'none', shippingVersion, chainVersion };
+  }
+  // v1 policy: any version mismatch is treated as behavioural drift for
+  // the build stage refusal path (NV-BL-ADM-06). Additive-only drift
+  // becomes distinguishable once the umbrella starts landing patch bumps
+  // that only add rules; the classifier lives here so define-stage
+  // warning (DL-REQ-VALIDATE-03) can consume it without duplicating logic.
+  return { drift: 'behavioural', shippingVersion, chainVersion };
+}
+
+/**
+ * Reset the module-scope cache. For tests that mutate the on-disk artefact
+ * or the package version.
+ */
+export function resetRulesetCache() {
+  cachedRuleset = null;
+  cachedUmbrellaVersion = null;
+}

package/src/ruleset/ruleset.json

@@ -0,0 +1,146 @@
+{
+  "$schemaComment": "rcf-lite shared standards ruleset v1. Machine-readable contract consumed by build-lite's chain-admissibility lint, verify's per-AC scope check, and (from the umbrella release that adds it) rcf-define-lite's elicitation checklist. camelCase per estate convention. The rulesetVersion is stamped at load time from the umbrella package.json (see src/ruleset/index.js) per NV-BL-SR-02: there is no separate ruleset semver, its version is the rcf-lite umbrella version.",
+  "id": "rcf-lite-ruleset",
+  "provenance": {
+    "requirementsDoc": "projects/rcf-build-lite/docs/2026-08-06_build-lite-nextver-requirements.md",
+    "rulingSheet": "projects/rcf-build-lite/docs/2026-08-06_nextver-ruling-sheet.md",
+    "designWorkItem": "w-2026-07-28-012",
+    "ratifiedItems": [1, 2, 3, 4, 6, 7, 8, 11, 14, 15, 16, 17, 19]
+  },
+  "admissibilityRules": [
+    {
+      "id": "NV-BL-ADM-01",
+      "title": "Every functional REQ terminates in at least one AC observable as behaviour of the running product",
+      "requiresScopeTagVocabulary": true,
+      "refuseByDefault": true,
+      "overrideChannel": "recordedInChain",
+      "notes": "For every REQ classified functional, the chain must contain at least one AC that is observable in the running product, not only in a library or a fixture. AC-shape classifier tags govern which REQ-shapes must terminate in a runtime- or deployed-scope AC."
+    },
+    {
+      "id": "NV-BL-ADM-02",
+      "title": "AC-shape classifier assigns each AC a scope tag (library / runtime / deployed)",
+      "requiresScopeTagVocabulary": true,
+      "refuseByDefault": true,
+      "overrideChannel": "migrationStateUnclassified",
+      "notes": "The scope-tag vocabulary and the AC schema field that carries the tag live in rcf-schemas. See scopeTagVocabulary below."
+    },
+    {
+      "id": "NV-BL-ADM-03",
+      "title": "Bound TCs must exercise their AC's declared scope",
+      "requiresScopeTagVocabulary": true,
+      "refuseByDefault": true,
+      "overrideChannel": "migrationStateUnclassified",
+      "notes": "For each AC, the bound TC's scope must be equal to or wider than the AC's scope tag. Bootstrap window: chains authored before scope tags land carry scope 'unclassified' and are tolerated for one release cycle."
+    },
+    {
+      "id": "NV-BL-ADM-04",
+      "title": "Source-comment honesty gate",
+      "refuseByDefault": true,
+      "overrideChannel": "adrExternalBoundaryOnly",
+      "markerVocabularyRef": "sourceCommentMarkers",
+      "notes": "Source files bound to any FBS at status complete are scanned for admission markers. Any match refuses FBS completion. Per ratified ruling-sheet item 16, the only permitted override channel is an ADR recording the deferral for a genuine external-boundary blocker; the ADR names the marker text, the blocker, and the reason. NV-BL-ADM-05's generic recorded-override channel no longer covers source markers."
+    },
+    {
+      "id": "NV-BL-ADM-05",
+      "title": "Chain-admissibility gate is refuse-first, override-recorded",
+      "refuseByDefault": true,
+      "overrideChannel": "recordedInChain",
+      "notes": "A chain failing any admissibility check is refused before build starts. Explicit overrides are permitted for non-source-marker checks, recorded in the chain with rule id, reason, and authoring identity, and surfaced in the finalise summary. Source-comment markers (NV-BL-ADM-04) fall outside this generic override channel."
+    },
+    {
+      "id": "NV-BL-ADM-06",
+      "title": "Build-stage refusal on ruleset-version drift",
+      "refuseByDefault": true,
+      "overrideChannel": "recordedInChain",
+      "notes": "At build start, build-lite compares the ruleset version the chain declares it was authored against with the version the shipping lint enforces. Behaviour-changing drift refuses; additive-only drift warns. Ratified 2026-08-11 ruling-sheet item 7: define-stage drift is a warning-with-acknowledgement; build-stage drift is a refusal."
+    }
+  ],
+  "gateRules": [
+    {
+      "id": "NV-BL-GATE-01",
+      "title": "Pull rcf-verify profile-vs-AC check into the REVIEW stage",
+      "notes": "The profile-vs-AC scope-mismatch check runs at REVIEW time for every FBS, not only at finalise. Verify carries the check; the review-stage gate consumes the same helper."
+    },
+    {
+      "id": "NV-BL-GATE-02",
+      "title": "Deploy-smoke FBS is a chain-mandatory element for any REQ with deployed-scope ACs",
+      "requiresScopeTagVocabulary": true,
+      "notes": "Any chain whose REQ set contains at least one deployed-scope AC must contain at least one FBS whose build sequence boots the built artefact against a real config and asserts operator-visible behaviour."
+    },
+    {
+      "id": "NV-BL-GATE-03",
+      "title": "Boot-integration TC template family for runtime-scope ACs",
+      "templateFamilyRef": "tcTemplateFamily",
+      "notes": "Runtime-scope ACs whose bound TC is not a boot-integration TC or a wider-scope TC fail admissibility (via NV-BL-ADM-03) and REVIEW (via NV-BL-GATE-01)."
+    },
+    {
+      "id": "NV-BL-GATE-04",
+      "title": "Ruling-set consistency light-check at ruling-application time",
+      "checkFamilyRef": "rulingConsistencyChecks",
+      "notes": "Light mechanical checks only per ratified ruling-sheet item 4: no two rulings name the same external resource with contradictory constraints; no ruling implies a capability the ruled-in service does not have on the ruled-in tier. Probabilistic and suitability work belongs in rcf-define-lite under DL-REQ-VALIDATE-04."
+    }
+  ],
+  "scopeTagVocabulary": {
+    "sourcePackage": "@stravica-ai/rcf-schemas",
+    "schemaRef": "https://schemas.stravica.io/rcf/v0.4.0/common.schema.json#/$defs/scopeTag",
+    "values": [
+      { "value": "library", "description": "Observable in an isolated library or fixture." },
+      { "value": "runtime", "description": "Observable in the running product against local integration." },
+      { "value": "deployed", "description": "Observable on a booted artefact against real config and real network." },
+      { "value": "unclassified", "description": "Migration state for chains authored before the scope-tag vocabulary shipped; ruleset-enforcing consumers decide whether unclassified is currently accepted." }
+    ],
+    "unclassifiedMigrationTolerance": {
+      "toleratedFor": "one release cycle from the umbrella release that first ships this ruleset",
+      "expiresWhen": "rcf-define-lite ships and can take over elicitation"
+    }
+  },
+  "sourceCommentMarkers": [
+    { "marker": "TODO", "caseInsensitive": true },
+    { "marker": "FIXME", "caseInsensitive": true },
+    { "marker": "XXX", "caseInsensitive": true },
+    { "marker": "HACK", "caseInsensitive": true },
+    { "marker": "placeholder", "caseInsensitive": true },
+    { "marker": "v1 refinement", "caseInsensitive": true },
+    { "marker": "deferred", "caseInsensitive": true },
+    { "marker": "stub", "caseInsensitive": true }
+  ],
+  "tcTemplateFamily": [
+    {
+      "id": "TCT-SERVER-BOOT",
+      "title": "Server-boot integration TC",
+      "surface": "server",
+      "notes": "Boots the built server against a real config and asserts an operator-visible observable (probe fires, page returns 200 with expected content, and so on)."
+    },
+    {
+      "id": "TCT-CLI-INVOKE",
+      "title": "CLI-invoke integration TC",
+      "surface": "cli",
+      "notes": "Invokes the packaged CLI as an installed artefact (not via the workspace source) against a real config and asserts an operator-visible observable."
+    },
+    {
+      "id": "TCT-CONTAINER-RUN",
+      "title": "Container-run integration TC",
+      "surface": "container",
+      "notes": "Runs the built container against a real config and asserts an operator-visible observable."
+    }
+  ],
+  "rulingConsistencyChecks": [
+    {
+      "id": "RCC-EXTERNAL-RESOURCE-CONTRADICTION",
+      "title": "No two rulings name the same external resource with contradictory constraints",
+      "kind": "lightMechanical",
+      "notes": "Detects the Resend-collision class: Ruling A names service.tier=free and Ruling B names service.domainCount=N with N > tier-limit(free)."
+    },
+    {
+      "id": "RCC-TIER-CAPABILITY-MISMATCH",
+      "title": "No ruling implies a capability the ruled-in service does not have on the ruled-in tier",
+      "kind": "lightMechanical",
+      "notes": "Detects the ruling-in of a capability against a tier that cannot deliver it. Deep suitability checks live in rcf-define-lite under DL-REQ-VALIDATE-04."
+    }
+  ],
+  "toolScope": {
+    "chainAdmissibility": true,
+    "traceabilityAndQueryTools": true,
+    "notes": "Per ratified ruling-sheet item 1 addendum: the same rule set governs what a traceability or query tool may return as much as it governs what build may consume. A query tool that hides an admissibility failure is the same class of defect as a build that hides one."
+  }
+}

package/src/server/index.js

@@ -0,0 +1,178 @@
+// HTTP + SSE server for the live-view surface. Wires the watch primitive
+// to the walker to the SSE hub: any change under `rcf/` triggers a full
+// re-walk (D4) and a `tree-update` broadcast (D12). Binds 127.0.0.1 only
+// (D11); EADDRINUSE is a hard failure (D10).
+//
+// Public surface:
+//   startServer({ projectRoot, port, host, log, heartbeatMs, watchImpl })
+//     -> Promise<{ url, port, close, hub, currentState }>
+// close() drains SSE with a `shutdown` event and releases the port. The
+// caller (bin/rcf-view.js) is responsible for the 2s force-exit budget
+// on top; the server itself does not `process.exit`.
+
+import { createServer } from 'node:http';
+import { join } from 'node:path';
+
+import { LIVE_CLIENT_PATH, STYLE_CSS_PATH, VENDORED_MERMAID_PATH, renderModelToPage } from '../view/index.js';
+import { watch as defaultWatch } from '../watch/index.js';
+import { createRouter } from './routes.js';
+import { createSseHub } from './sse.js';
+
+/**
+ * @typedef {object} StartServerOptions
+ * @property {string} projectRoot
+ * @property {number} [port=4373]
+ * @property {string} [host='127.0.0.1']
+ * @property {number} [heartbeatMs=30000]
+ * @property {number} [debounceMs=50]
+ * @property {(line: string) => void} [log] - stderr sink
+ * @property {typeof defaultWatch} [watchImpl] - injectable watch primitive for tests
+ */
+
+/**
+ * @param {StartServerOptions} args
+ * @returns {Promise<{
+ *   url: string,
+ *   port: number,
+ *   host: string,
+ *   close: () => Promise<void>,
+ *   currentState: () => { version: number, fullPageHtml: string, contentHtml: string } | null,
+ *   sse: ReturnType<typeof createSseHub>,
+ *   rewalk: () => Promise<void>,
+ * }>}
+ */
+export async function startServer(args) {
+  const projectRoot = args.projectRoot;
+  const port = typeof args.port === 'number' ? args.port : 4373;
+  const host = typeof args.host === 'string' ? args.host : '127.0.0.1';
+  const heartbeatMs = typeof args.heartbeatMs === 'number' ? args.heartbeatMs : 30000;
+  const debounceMs = typeof args.debounceMs === 'number' ? args.debounceMs : 50;
+  const log = typeof args.log === 'function' ? args.log : () => {};
+  const watchImpl = typeof args.watchImpl === 'function' ? args.watchImpl : defaultWatch;
+
+  /** @type {{ version: number, fullPageHtml: string, contentHtml: string, errors: import('#core/errors').RcfError[] } | null} */
+  let state = null;
+  let version = 0;
+  let rewalkInFlight = null;
+  let closed = false;
+
+  const sse = createSseHub({ heartbeatMs, log });
+
+  async function rewalk() {
+    if (closed) return;
+    if (rewalkInFlight) {
+      // Coalesce concurrent walks. The trailing one will pick up the
+      // final on-disk state; a middle one adds nothing.
+      return rewalkInFlight;
+    }
+    rewalkInFlight = (async () => {
+      try {
+        const result = await renderModelToPage({ projectRoot });
+        if (closed) return;
+        version += 1;
+        state = {
+          version,
+          fullPageHtml: result.fullPageHtml,
+          contentHtml: result.contentHtml,
+          errors: result.errors,
+        };
+        sse.broadcast('tree-update', { version, contentHtml: result.contentHtml });
+        if (result.errors && result.errors.length > 0) {
+          sse.broadcast('walker-error', { errors: result.errors });
+        }
+      } catch (err) {
+        log(`[server] walker failed: ${/** @type {Error} */ (err).message}`);
+        sse.broadcast('walker-error', {
+          errors: [{ kind: 'ioFailure', message: /** @type {Error} */ (err).message }],
+        });
+      } finally {
+        rewalkInFlight = null;
+      }
+    })();
+    return rewalkInFlight;
+  }
+
+  // Initial walk before we bind, so the first HTTP GET / has content ready
+  // and the first SSE connect gets a real payload.
+  await rewalk();
+
+  const router = createRouter({
+    currentState: () => state,
+    sse,
+    stylePath: STYLE_CSS_PATH,
+    mermaidPath: VENDORED_MERMAID_PATH,
+    liveClientPath: LIVE_CLIENT_PATH,
+  });
+
+  const server = createServer(router);
+
+  // Watcher: any .json change under rcf/ triggers a re-walk. Debounced
+  // per D4. Non-JSON files are filtered in the primitive itself.
+  const watchDir = join(projectRoot, 'rcf');
+  const watcher = watchImpl({
+    paths: [watchDir],
+    onChange: () => { rewalk().catch(() => {}); },
+    debounceMs,
+    onError: (err) => { log(`[watch] ${err.message}`); },
+  });
+
+  // Bind. EADDRINUSE surfaces as a rejected Promise so the caller can
+  // print a clear message and exit 2 (D10). On bind failure we also tear
+  // down the watcher and close the (unbound) http.Server so the process
+  // has no lingering handles.
+  try {
+    await new Promise((resolve, reject) => {
+      function onError(err) {
+        server.off('listening', onListening);
+        reject(err);
+      }
+      function onListening() {
+        server.off('error', onError);
+        resolve();
+      }
+      server.once('error', onError);
+      server.once('listening', onListening);
+      server.listen(port, host);
+    });
+  } catch (err) {
+    try { watcher.close(); } catch { /* swallow */ }
+    try { sse.close(); } catch { /* swallow */ }
+    try { server.close(); } catch { /* swallow */ }
+    throw err;
+  }
+
+  const boundPort = /** @type {import('node:net').AddressInfo} */ (server.address()).port;
+
+  async function close() {
+    if (closed) return;
+    closed = true;
+    try { watcher.close(); } catch { /* swallow */ }
+    await sse.drain('shutdown');
+    // Kick any lingering keep-alive sockets out first so `server.close()`
+    // resolves quickly. Node 18.2+ exposes both APIs.
+    try { server.closeIdleConnections?.(); } catch { /* swallow */ }
+    try { server.closeAllConnections?.(); } catch { /* swallow */ }
+    await new Promise((resolve) => {
+      let done = false;
+      server.close(() => { if (!done) { done = true; resolve(); } });
+      // Backstop: never let the promise hang beyond the bin's 2s budget.
+      const t = setTimeout(() => {
+        if (done) return;
+        done = true;
+        try { server.closeAllConnections?.(); } catch { /* swallow */ }
+        resolve();
+      }, 500);
+      if (typeof t.unref === 'function') t.unref();
+    });
+  }
+
+  return {
+    url: `http://${host}:${boundPort}/`,
+    port: boundPort,
+    host,
+    close,
+    currentState: () => state,
+    sse,
+    rewalk,
+  };
+}

package/src/server/routes.js

@@ -0,0 +1,110 @@
+// HTTP route table for the live-view server. Only five routes are served:
+// GET /              -> rendered page (text/html)
+// GET /events        -> SSE stream (text/event-stream)
+// GET /style.css     -> shipped stylesheet
+// GET /mermaid.min.js-> vendored mermaid runtime
+// GET /live-client.js-> phase 3.8 live client script
+// Everything else -> 404 text/plain.
+//
+// No CORS headers, no cache headers on static assets beyond what the
+// browser derives from same-origin/localhost trust (D5, D11).
+
+import { readFile, stat } from 'node:fs/promises';
+
+const MIME = {
+  html: 'text/html; charset=utf-8',
+  css: 'text/css; charset=utf-8',
+  js: 'application/javascript; charset=utf-8',
+  txt: 'text/plain; charset=utf-8',
+};
+
+/**
+ * @typedef {object} RouterDeps
+ * @property {() => { fullPageHtml: string, contentHtml: string, version: number } | null} currentState
+ * @property {ReturnType<typeof import('./sse.js').createSseHub>} sse
+ * @property {string} stylePath
+ * @property {string} mermaidPath
+ * @property {string} liveClientPath
+ */
+
+/**
+ * Create a request handler bound to the current state provider and the
+ * SSE hub. The returned function has signature `(req, res) -> void` and
+ * is ready to pass into `http.createServer`.
+ *
+ * @param {RouterDeps} deps
+ * @returns {(req: import('node:http').IncomingMessage, res: import('node:http').ServerResponse) => void}
+ */
+export function createRouter(deps) {
+  return function handle(req, res) {
+    if (req.method !== 'GET' && req.method !== 'HEAD') {
+      res.writeHead(405, { 'content-type': MIME.txt, allow: 'GET, HEAD' });
+      res.end('method not allowed\n');
+      return;
+    }
+    const url = new URL(req.url ?? '/', 'http://localhost');
+    const path = url.pathname;
+
+    if (path === '/' || path === '/index.html') {
+      const state = deps.currentState();
+      if (!state) {
+        res.writeHead(503, { 'content-type': MIME.txt });
+        res.end('view server initialising\n');
+        return;
+      }
+      res.writeHead(200, { 'content-type': MIME.html });
+      res.end(state.fullPageHtml);
+      return;
+    }
+    if (path === '/events') {
+      const state = deps.currentState();
+      const payload = state ? { version: state.version, contentHtml: state.contentHtml } : null;
+      deps.sse.handle(req, res, payload);
+      return;
+    }
+    if (path === '/style.css') {
+      serveFile(res, deps.stylePath, MIME.css).catch((err) => fail(res, err));
+      return;
+    }
+    if (path === '/mermaid.min.js') {
+      serveFile(res, deps.mermaidPath, MIME.js).catch((err) => fail(res, err));
+      return;
+    }
+    if (path === '/live-client.js') {
+      serveFile(res, deps.liveClientPath, MIME.js).catch((err) => fail(res, err));
+      return;
+    }
+
+    res.writeHead(404, { 'content-type': MIME.txt });
+    res.end('not found\n');
+  };
+}
+
+async function serveFile(res, path, contentType) {
+  let body;
+  let size;
+  try {
+    const [buf, s] = await Promise.all([readFile(path), stat(path)]);
+    body = buf;
+    size = s.size;
+  } catch (err) {
+    if (/** @type {NodeJS.ErrnoException} */ (err).code === 'ENOENT') {
+      res.writeHead(404, { 'content-type': MIME.txt });
+      res.end('not found\n');
+      return;
+    }
+    throw err;
+  }
+  res.writeHead(200, {
+    'content-type': contentType,
+    'content-length': String(size),
+  });
+  res.end(body);
+}
+
+function fail(res, err) {
+  try {
+    res.writeHead(500, { 'content-type': MIME.txt });
+    res.end(`internal error: ${err && err.message ? err.message : 'unknown'}\n`);
+  } catch { /* swallow */ }
+}