@uniqbit/mate-core 0.18.3-canary.0 → 0.18.3

package/claude-plugin/hooks/hooks.json

@@ -1,5 +1,5 @@
 {
-  "description": "Mate hooks — PreToolUse artifact-path guardrail, SessionStart banner and companion guidance",
+  "description": "Mate hooks \u2014 PreToolUse artifact-path guardrail, SessionStart banner, companion guidance and session prepare",
   "hooks": {
     "PreToolUse": [
       {
@@ -28,6 +28,15 @@
             "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/session-guidance.mjs\""
           }
         ]
+      },
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/session-prepare.mjs\"",
+            "timeout": 45
+          }
+        ]
       }
     ]
   }

package/claude-plugin/hooks/session-banner.mjs

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
-// Thin shim: hook logic lives in src/hooks/session-banner.ts, loaded through
-// ts-loader.mjs because the installed plugin sits inside node_modules where
-// node's native type stripping is disabled.
+/**
+ * Thin shim for src/hooks/session-banner.ts, loaded through ts-loader.mjs: the installed
+ * plugin sits inside node_modules, where node's native type stripping is off.
+ */
 import "./ts-loader.mjs";
 
 const { run } = await import("../../src/hooks/session-banner.ts");

package/claude-plugin/hooks/session-prepare.mjs

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+/**
+ * Thin shim for src/hooks/session-prepare.ts, loaded through ts-loader.mjs: the installed
+ * plugin sits inside node_modules, where node's native type stripping is off.
+ */
+import "./ts-loader.mjs";
+
+const { run } = await import("../../src/hooks/session-prepare.ts");
+process.exitCode = await run();

package/opencode-plugin/src/companion.ts

@@ -1,3 +1,4 @@
+import fs from "node:fs";
 import path from "node:path";
 
 import type { Context } from "@opencode/plugin/promise/plugin";
@@ -6,14 +7,36 @@ import { COMPANION_POLICY_MARKER, type MateGuidanceFile } from "../../src/runtim
 
 import type { CompanionContext } from "../../src/opencode/companion-policy";
 import { resolveOpenCodeGuidance } from "../../src/opencode/projected-guidance";
+import {
+  runtimeDirectoryPath,
+  runtimeMateBin,
+  runtimeWrapperBinPath,
+} from "../../src/runtime/runtime-directory";
 
 function prependPathEntry(pathValue: string | undefined, entry: string): string {
   const entries = (pathValue ?? "").split(path.delimiter).filter(Boolean);
   return [entry, ...entries.filter((value) => value !== entry)].join(path.delimiter);
 }
 
-function resolveWrapperBinPath(): string {
-  return process.env.MATE_WRAPPER_BIN_PATH ?? "$MATE_WRAPPER_BIN_PATH";
+/**
+ * The launch environment first, then the runtime directory every `mate` run
+ * keeps current. `null` when neither exists: guidance naming an unresolved
+ * placeholder would send the model to a path that is not there.
+ */
+function resolveWrapperBinPath(): string | null {
+  if (process.env.MATE_WRAPPER_BIN_PATH) return process.env.MATE_WRAPPER_BIN_PATH;
+  const runtime = runtimeWrapperBinPath();
+  return fs.existsSync(runtime) ? runtime : null;
+}
+
+/** The runtime-directory launcher for the Mate CLI; `null` until a `mate` run wrote it. */
+export function resolveMateBin(): string | null {
+  const launcher = runtimeMateBin();
+  return fs.existsSync(launcher) ? launcher : null;
+}
+
+export function missingRuntimeDirectoryMessage(): string {
+  return `Mate runtime directory ${runtimeDirectoryPath()} is missing; run \`mate\` once to repair it.`;
 }
 
 function buildStartupError(details: string[]): Error {
@@ -37,8 +60,11 @@ function loadGuidance(directory: string): MateGuidanceFile | null {
   return guidance;
 }
 
-function materializeCompanionGuidance(guidance: string, context: CompanionContext): string {
-  const wrapperBinPath = resolveWrapperBinPath();
+function materializeCompanionGuidance(
+  guidance: string,
+  context: CompanionContext,
+  wrapperBinPath: string,
+): string {
   return guidance
     .replaceAll("$MATE_REPO_PATH", context.repositoryPath)
     .replaceAll("$MATE_ARTIFACT_PATH", context.companionPath)
@@ -46,8 +72,12 @@ function materializeCompanionGuidance(guidance: string, context: CompanionContex
     .replaceAll("$MATE_REPO_ID", context.repositoryId);
 }
 
-function buildSystemPrompt(context: CompanionContext, guidance: MateGuidanceFile): string[] {
-  const lines = [materializeCompanionGuidance(guidance.companionGuidance, context)];
+function buildSystemPrompt(
+  context: CompanionContext,
+  guidance: MateGuidanceFile,
+  wrapperBinPath: string,
+): string[] {
+  const lines = [materializeCompanionGuidance(guidance.companionGuidance, context, wrapperBinPath)];
 
   if (guidance.codebaseExplorationGuidance.trim()) {
     lines.push("", guidance.codebaseExplorationGuidance);
@@ -70,8 +100,8 @@ function readSystemText(part: unknown): string {
 function applyCompanionShellEnv(
   context: CompanionContext,
   env: Record<string, string | undefined>,
+  wrapperBinPath: string,
 ): void {
-  const wrapperBinPath = resolveWrapperBinPath();
   env.MATE_NAME = context.frameworkName;
   env.MATE_VERSION = process.env.MATE_VERSION ?? "unknown";
   env.MATE_ARTIFACT_PATH = context.companionPath;
@@ -95,8 +125,7 @@ function applyCompanionShellEnv(
   env.PATH = prependPathEntry(process.env.PATH, wrapperBinPath);
 }
 
-function companionPathsResult(context: CompanionContext) {
-  const wrapperBinPath = resolveWrapperBinPath();
+function companionPathsResult(context: CompanionContext, wrapperBinPath: string) {
   return {
     content: JSON.stringify(
       {
@@ -146,8 +175,14 @@ function mergeCompanionSystem(system: unknown[], companion: string): string[] {
 export async function registerCompanion(api: Context, context: CompanionContext): Promise<void> {
   const guidance = loadGuidance(api.location.directory);
   if (!guidance) return;
+  /** Reported, not thrown: the guardrails registered before this must stay live. */
+  const wrapperBinPath = resolveWrapperBinPath();
+  if (!wrapperBinPath) {
+    console.error(`mate: ${missingRuntimeDirectoryMessage()}`);
+    return;
+  }
 
-  const companion = buildSystemPrompt(context, guidance).join("\n");
+  const companion = buildSystemPrompt(context, guidance, wrapperBinPath).join("\n");
 
   await api.session.hook("context", (event) => {
     const merged = mergeCompanionSystem(event.system, companion);
@@ -164,7 +199,7 @@ export async function registerCompanion(api: Context, context: CompanionContext)
   });
 
   await api.shell.hook("create.before", (event) => {
-    applyCompanionShellEnv(context, event.env);
+    applyCompanionShellEnv(context, event.env, wrapperBinPath);
   });
 
   await api.tool.transform((editor) => {
@@ -173,7 +208,7 @@ export async function registerCompanion(api: Context, context: CompanionContext)
       description: `Return active ${context.frameworkName} companion framework and working repository paths.`,
       input: { type: "object", properties: {}, additionalProperties: false },
       async execute() {
-        return companionPathsResult(context);
+        return companionPathsResult(context, wrapperBinPath);
       },
     });
   });

package/opencode-plugin/src/server.ts

@@ -1,9 +1,40 @@
 import { Plugin } from "@opencode/plugin";
-import { registerCompanionHooks } from "../../src/opencode/companion-hooks";
+import type { Context } from "@opencode/plugin/promise/plugin";
+import {
+  registerCompanionHooks,
+  repositoryWrappedForOpenCode,
+} from "../../src/opencode/companion-hooks";
 import { readContext } from "../../src/opencode/companion-policy";
+import { registerSessionPrepare } from "../../src/opencode/session-prepare";
+import { hasLaunchEnvironment } from "../../src/runtime/env";
+import { spawnPrepareRunner } from "../../src/runtime/session-prepare-runner";
+import { readWrapStateSync } from "../../src/runtime/wrap-state";
 
 import { registerCompanionAccess } from "./add-dir";
-import { registerCompanion } from "./companion";
+import { missingRuntimeDirectoryMessage, registerCompanion, resolveMateBin } from "./companion";
+
+/**
+ * Only a location in a repository wrapped for OpenCode prepares, and only
+ * without a launch environment: `mate opencode` has already prepared the
+ * session it starts.
+ */
+async function registerPrepare(api: Context, companionPath: string) {
+  if (hasLaunchEnvironment(process.env)) return undefined;
+  const repoRoot = repositoryWrappedForOpenCode(api.location.directory);
+  if (!repoRoot) return undefined;
+  const mateBin = resolveMateBin();
+  if (!mateBin) {
+    console.error(`mate: ${missingRuntimeDirectoryMessage()}`);
+    return undefined;
+  }
+  return registerSessionPrepare(api, {
+    directory: api.location.directory,
+    repoPath: repoRoot,
+    companionPath,
+    mateServers: readWrapStateSync(repoRoot).openCodeMcpServers,
+    run: spawnPrepareRunner(mateBin, repoRoot),
+  });
+}
 
 /**
  * Mate OpenCode server plugin (OpenCode 2.x). Loaded through the package's
@@ -17,9 +48,13 @@ export const MateOpenCodePlugin = Plugin.define({
     if (!context.companionPath) return;
 
     await registerCompanionAccess(api, context.companionPath);
-    const cleanup = await registerCompanionHooks(api, context);
+    await registerCompanionHooks(api, context);
     await registerCompanion(api, context);
-    return cleanup;
+    /** Last: the guardrails above are live while the local phase holds `setup`. */
+    const prepareCleanup = await registerPrepare(api, context.companionPath);
+    return async () => {
+      await prepareCleanup?.();
+    };
   },
 });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniqbit/mate-core",
-  "version": "0.18.3-canary.0",
+  "version": "0.18.3",
   "description": "Core framework and plugin APIs for Mate.",
   "license": "MIT",
   "repository": {
@@ -35,8 +35,8 @@
     "typecheck": "bunx tsc --noEmit -p ../../tsconfig.json",
     "lint": "oxlint src/ opencode-plugin/",
     "lint:fix": "oxlint src/ opencode-plugin/ --fix",
-    "format": "oxfmt src/ opencode-plugin/ \"!**/*.generated.*\" \"!**/report-assets/**\"",
-    "format:check": "oxfmt src/ opencode-plugin/ \"!**/*.generated.*\" \"!**/report-assets/**\" --check"
+    "format": "oxfmt src/ opencode-plugin/ \"!**/*.generated.*\"",
+    "format:check": "oxfmt src/ opencode-plugin/ \"!**/*.generated.*\" --check"
   },
   "dependencies": {
     "@opencode/plugin": "^2.0.23",

package/src/cli/commands/artifact/finish/openspec.ts

@@ -356,7 +356,7 @@ export async function resolveDriftedSpecs(
       message: `mate: not a canonical spec: ${outside.join(", ")}. Only specs under ${SPECS_RELATIVE_DIR}/ are spec publication targets.`,
     };
   }
-  const driftedPaths = new Set(drifted);
+  const driftedPaths = new Set(drifted.map(withoutTrailingSlash));
   const notDrifted = normalized.filter((candidate) => !driftedPaths.has(candidate));
   if (notDrifted.length > 0) {
     return {

package/src/cli/commands/artifact/pending/discovery.ts

@@ -109,28 +109,32 @@ function changeKindFor(
   );
 }
 
+/**
+ * Every file beneath `directory`, as POSIX paths under `relativeRoot`. Reads directory
+ * entry names only, never file contents. Throws when `directory` cannot be read.
+ */
+async function filesUnder(directory: string, relativeRoot: string): Promise<string[]> {
+  const entries = await fs.readdir(directory, { withFileTypes: true });
+  const nested = await Promise.all(
+    entries.map(async (entry) => {
+      const entryRelative = path.posix.join(relativeRoot, entry.name);
+      if (entry.isDirectory()) return filesUnder(path.join(directory, entry.name), entryRelative);
+      return entry.isFile() ? [entryRelative] : [];
+    }),
+  );
+  return nested.flat();
+}
+
 /**
  * Canonical specs the change's delta specs applied to. Only directory entry names under
  * the archive's `specs/` tree are read — never any file contents — so archived prose
  * cannot influence discovery.
  */
 async function canonicalSpecsFor(companionPath: string, anchor: string): Promise<string[]> {
-  const collectDeltaSpecFiles = async (directory: string, relative = ""): Promise<string[]> => {
-    const entries = await fs.readdir(directory, { withFileTypes: true });
-    const nested = await Promise.all(
-      entries.map(async (entry) => {
-        const entryRelative = path.posix.join(relative, entry.name);
-        if (entry.isDirectory()) {
-          return collectDeltaSpecFiles(path.join(directory, entry.name), entryRelative);
-        }
-        return entry.isFile() ? [path.posix.join(SPECS_RELATIVE_DIR, entryRelative)] : [];
-      }),
-    );
-    return nested.flat();
-  };
   try {
-    const specs = await collectDeltaSpecFiles(
+    const specs = await filesUnder(
       path.join(companionPath, ARCHIVE_RELATIVE_DIR, anchor, "specs"),
+      SPECS_RELATIVE_DIR,
     );
     return specs.toSorted();
   } catch {
@@ -216,6 +220,32 @@ async function attributionIndex(
   );
 }
 
+/**
+ * The canonical spec files behind one uncommitted path. Porcelain collapses an untracked
+ * directory to `dir/`, so a collapsed path at or above a capability directory is expanded
+ * into the files beneath it, every one of them new; publish narrows by file, never by
+ * directory. Expansion reads directory entry names only, so spec prose cannot influence
+ * discovery.
+ */
+async function specFilesFor(
+  companionPath: string,
+  worktreePath: string,
+  changeKinds: Readonly<Record<string, WorkingTreeChange>>,
+): Promise<Array<{ path: string; kind: WorkingTreeChange }>> {
+  if (!worktreePath.endsWith("/")) {
+    return [{ path: worktreePath, kind: changeKindFor(worktreePath, changeKinds) }];
+  }
+  const collapsed = withoutTrailingSlash(worktreePath);
+  const root = collapsed.startsWith(`${SPECS_RELATIVE_DIR}/`) ? collapsed : SPECS_RELATIVE_DIR;
+  try {
+    const files = await filesUnder(path.join(companionPath, root), root);
+    return files.map((file) => ({ path: file, kind: "new" as const }));
+  } catch {
+    // A collapsed ancestor such as `openspec/` need not contain a spec tree at all.
+    return [];
+  }
+}
+
 /**
  * Uncommitted canonical specs that no pending change accounts for, each attributed to
  * every archive whose delta specs name it. An attributed spec belongs to a change whose
@@ -230,18 +260,27 @@ export async function unattributedSpecs(
   archives: ArchiveEntry[],
   changeKinds: Readonly<Record<string, WorkingTreeChange>> = {},
 ): Promise<UnattributedSpec[]> {
-  const claimed = new Set(pendingArchives(archives).flatMap((entry) => entry.uncommittedSpecs));
-  const specPaths = uncommittedPaths
-    .filter(
-      (worktreePath) => touches(worktreePath, SPECS_RELATIVE_DIR) && !claimed.has(worktreePath),
-    )
-    .toSorted();
+  const claimed = pendingArchives(archives).flatMap((entry) => entry.uncommittedSpecs);
+  const reported = await Promise.all(
+    uncommittedPaths.flatMap((worktreePath) =>
+      touches(worktreePath, SPECS_RELATIVE_DIR)
+        ? [specFilesFor(companionPath, worktreePath, changeKinds)]
+        : [],
+    ),
+  );
+  const driftKinds = new Map<string, WorkingTreeChange>();
+  for (const spec of reported.flat()) {
+    if (!claimed.some((claimedPath) => touches(claimedPath, spec.path))) {
+      driftKinds.set(spec.path, spec.kind);
+    }
+  }
+  const specPaths = [...driftKinds.keys()].toSorted();
   if (specPaths.length === 0) return [];
 
   const index = await attributionIndex(companionPath, archives);
   return specPaths.map((specPath) => ({
     path: specPath,
-    kind: changeKindFor(specPath, changeKinds),
+    kind: driftKinds.get(specPath) ?? "modified",
     touchedByArchives: index.flatMap(({ anchor, state, specs }) =>
       specs.some((spec) => touches(specPath, spec)) ? [{ anchor, state }] : [],
     ),

package/src/cli/commands/companion/link.ts

@@ -10,10 +10,12 @@ import {
 } from "../../companion-link-wizard";
 import { extractRepoName } from "../artifact/extract-repo-name";
 import { GlobalConfigStore } from "../../../lib/orchestrator/global-config-store";
-import { CompanionResolver } from "../../../lib/orchestrator/companion-resolver";
-import { companionRootedStore } from "../../../lib/orchestrator/companion-store";
+import {
+  CompanionResolver,
+  companionRootedStore,
+  findDescendantRepoLocalRegistries,
+} from "../../../lib/orchestrator/repository-link";
 import { inspectSetupPreflight } from "../../../lib/orchestrator/setup-preflight";
-import { findDescendantRepoLocalRegistries } from "../../../lib/orchestrator/repo-local-registry";
 import { runSetupFlowAtPath } from "../setup";
 import { runInstallCommand } from "../install";
 import type { CompanionSource, LinkedRepository } from "../../../lib/orchestrator/types";
@@ -164,14 +166,15 @@ export async function runCompanionLinkCommandWithDeps(
     if (!inputs.companionPaths?.length) {
       exitWithError("mate: no existing companion was selected.");
     }
-    companionPaths = [];
-    for (const rawCompanionPath of inputs.companionPaths) {
-      const resolvedCompanionPath = path.resolve(rawCompanionPath);
-      const existingTarget = await stat(resolvedCompanionPath).catch(() => null);
-      if (!existingTarget?.isDirectory()) {
-        exitWithError(`mate: existing companion must be a directory: ${resolvedCompanionPath}`);
-      }
-      companionPaths.push(resolvedCompanionPath);
+    companionPaths = inputs.companionPaths.map((rawCompanionPath) =>
+      path.resolve(rawCompanionPath),
+    );
+    const targets = await Promise.all(
+      companionPaths.map((companionPath) => stat(companionPath).catch(() => null)),
+    );
+    const notADirectory = companionPaths.find((_, index) => !targets[index]?.isDirectory());
+    if (notADirectory) {
+      exitWithError(`mate: existing companion must be a directory: ${notADirectory}`);
     }
   } else {
     const rawCompanionPath = inputs.localPath?.trim();
@@ -205,6 +208,7 @@ export async function runCompanionLinkCommandWithDeps(
   // Managed companions are git-backed; explicitly pasted paths retain local provenance.
   const persistedSource: CompanionSource = companionSource === "local" ? "local" : "git";
 
+  /* oxlint-disable no-await-in-loop -- each companion is set up, linked and installed in turn; a declined install stops the rest */
   for (const companionPath of companionPaths) {
     const preflight = await inspectPreflight(companionPath);
     if (companionSource === "git" && preflight.kind !== "existing-companion") {
@@ -216,6 +220,7 @@ export async function runCompanionLinkCommandWithDeps(
     await invalidateInstallState({ kind: "companion", companionPath });
     if ((await installCompanion(companionPath)) === false) return;
   }
+  /* oxlint-enable no-await-in-loop */
 
   let shadowedPaths: string[] = [];
   try {

package/src/cli/commands/companion/list.ts

@@ -1,4 +1,4 @@
-import { CompanionStore } from "../../../lib/orchestrator/companion-store";
+import { CompanionStore } from "../../../lib/orchestrator/repository-link";
 import { resolveFrameworkContext } from "../../../lib/orchestrator/framework-context";
 import { renderRepoListTable } from "../../repo-list-table";
 import { writeJsonStdout } from "../../write-json-stdout";
@@ -13,14 +13,13 @@ import { writeJsonStdout } from "../../write-json-stdout";
  * TTY (e.g. piped into another command).
  */
 export async function runCompanionListCommand(argv: string[] = []): Promise<void> {
-  const { configStore, workingRepoStore, repository, contextKind } = await resolveFrameworkContext(
-    process.cwd(),
-  );
+  const { companionPath, workingRepoStore, repository, contextKind } =
+    await resolveFrameworkContext(process.cwd());
   const repositories = repository
     ? [repository]
     : contextKind === "companion-root"
       ? []
-      : await new CompanionStore(configStore, workingRepoStore).listRepositories();
+      : await new CompanionStore(companionPath, workingRepoStore).listRepositories();
   const forceJson = argv.includes("--json");
 
   if (forceJson || !process.stdout.isTTY) {

package/src/cli/commands/companion/open.ts

@@ -1,4 +1,4 @@
-import { CompanionStore } from "../../../lib/orchestrator/companion-store";
+import { CompanionStore } from "../../../lib/orchestrator/repository-link";
 import { resolveForLaunch } from "../../../lib/orchestrator/framework-context";
 import { injectEditorFolder, getPreferredEditorCli } from "../../../lib/orchestrator/editor";
 import { ensureUnambiguousCompanion } from "../launch/shared";
@@ -7,9 +7,9 @@ export const workspaceOpenCommandDeps = {
   ensureUnambiguousCompanion: () => ensureUnambiguousCompanion(),
   resolveLaunchContext: () => resolveForLaunch(process.cwd()),
   createStore: (
-    configStore: ConstructorParameters<typeof CompanionStore>[0],
+    companionPath: ConstructorParameters<typeof CompanionStore>[0],
     workingRepoStore: ConstructorParameters<typeof CompanionStore>[1],
-  ) => new CompanionStore(configStore, workingRepoStore),
+  ) => new CompanionStore(companionPath, workingRepoStore),
   getPreferredEditorCli: () => getPreferredEditorCli(),
   injectEditorFolder,
 };
@@ -35,13 +35,12 @@ export async function runWorkspaceOpenCommand(): Promise<void> {
     companionPath,
     repositoryId,
     repository: localRepository,
-    configStore,
     workingRepoStore,
   } = await workspaceOpenCommandDeps.resolveLaunchContext();
   const repository =
     localRepository ??
     (await workspaceOpenCommandDeps
-      .createStore(configStore, workingRepoStore)
+      .createStore(companionPath, workingRepoStore)
       .getRepository(repositoryId));
 
   if (!repository) {

package/src/cli/commands/companion/tui.ts

@@ -4,7 +4,7 @@ import { accessSync } from "node:fs";
 import { getActiveDistribution } from "../../../distribution";
 import { FRAMEWORK_NAME } from "../../../framework";
 import { resolveFrameworkContext } from "../../../lib/orchestrator/framework-context";
-import { findRepoLocalLinkedRepository } from "../../../lib/orchestrator/repo-local-registry";
+import { findRepoLocalLinkedRepository } from "../../../lib/orchestrator/repository-link";
 import { ensureUnambiguousCompanion } from "../launch/shared";
 
 export function renderBanner(repoPath: string, companionPath: string): string {

package/src/cli/commands/doctor.ts

@@ -6,7 +6,7 @@ import { gitEnvironment } from "../../runtime/companion-git";
 import { getActiveDistribution } from "../../distribution";
 import { checkEngineRequirement } from "../../lib/orchestrator/engine-guard";
 import type { GlobalConfigStore } from "../../lib/orchestrator/global-config-store";
-import { pathIsDirectory } from "../../lib/orchestrator/repo-local-registry";
+import { pathIsDirectory } from "../../lib/fs-utils";
 import { resolveRootContext, type RootContext } from "../../lib/orchestrator/root-context";
 import type { CapabilityConfig, FrameworkConfig, HubMember } from "../../lib/orchestrator/types";
 import {

package/src/cli/commands/report/renderer.ts

@@ -1,6 +1,3 @@
-import { readFileSync } from "node:fs";
-import { join } from "node:path";
-
 import { reportDataToDocument } from "./adapter";
 import { validateReportDocument } from "./contract";
 import { highlightInline, highlightStyleBlock } from "./highlight";
@@ -14,26 +11,19 @@ import type {
   ReportValue,
 } from "./types";
 
-const MERMAID_RUNTIME_PATH = join(
-  import.meta.dirname,
-  "../../../templates/report-assets/mermaid.min.js",
-);
+/**
+ * Pinned and integrity-checked, so a CDN cannot serve other code. Offline, the
+ * script fails to load and each diagram stays readable as its escaped source.
+ */
+export const MERMAID_RUNTIME_URL =
+  "https://cdn.jsdelivr.net/npm/mermaid@12.0.0/dist/mermaid.min.js";
+const MERMAID_RUNTIME_INTEGRITY =
+  "sha384-xzghz1GQ5u9HCpVskeDPqMsdogD1yvuMQbEK53+wi+G70+6J1AG0L2cfi9PHjDWI";
 
 const MERMAID_RUNTIME_ID = "mermaid-runtime";
 
 const CODE_BLOCK_SELECTOR = "pre.report-code";
 
-let mermaidRuntime: string | undefined;
-
-/** A literal `</script` inside the bundle would close the inline element, so it is neutralised. */
-function readMermaidRuntime(): string {
-  mermaidRuntime ??= readFileSync(MERMAID_RUNTIME_PATH, "utf8").replaceAll(
-    "</script",
-    String.raw`<\/script`,
-  );
-  return mermaidRuntime;
-}
-
 const carriesMermaid = (sections: ReportSection[]): boolean =>
   sections.some((section) => section.type === "diagram" && section.mermaid !== undefined);
 
@@ -384,7 +374,7 @@ export function renderHTML(input: RenderInput): string {
     ? `\n  <style>${highlightStyleBlock(CODE_BLOCK_SELECTOR)}${VISUAL_SECTION_CSS}</style>`
     : "";
   const diagramRuntime = carriesMermaid(data.sections)
-    ? `\n  <script id="${MERMAID_RUNTIME_ID}">${readMermaidRuntime()}</script>\n  <script>mermaid.initialize({ startOnLoad: true, securityLevel: "strict" });</script>`
+    ? `\n  <script id="${MERMAID_RUNTIME_ID}" src="${MERMAID_RUNTIME_URL}" integrity="${MERMAID_RUNTIME_INTEGRITY}" crossorigin="anonymous"></script>\n  <script>window.mermaid?.initialize({ startOnLoad: true, securityLevel: "strict" });</script>`
     : "";
 
   return `<!doctype html>