toolfunnel 0.3.0

package/src/tools/drift.js

@@ -0,0 +1,138 @@
+'use strict';
+
+/**
+ * drift.js — tool register drift detector.
+ *
+ * The register can go stale when entries are not maintained alongside the files
+ * they describe (a config file left unmaintained over time, tools missing). A
+ * behavioural "update it immediately" rule is fragile. This is the STRUCTURAL
+ * guard (fix-the-tool, not the discipline): scan the real scripts directory
+ * against the register and surface drift so it can never silently rot again.
+ *
+ * Mirrors the host's auto-detect (the folder is the source of truth for what
+ * EXISTS; the register carries config). Read-only — it never edits anything,
+ * inside or outside the gateway (honours the isolation rule: MAY READ the live
+ * scripts directory, MUST NOT write it).
+ *
+ * detectDrift({ registerPath, toolsDir }) -> {
+ *   ok, registerPath, toolsDir,
+ *   registeredCount,            // distinct .js basenames referenced by the register
+ *   onDiskCount,                // tool files found under toolsDir
+ *   missingFromRegister: [str], // on disk under toolsDir but NOT referenced by any entry
+ *   deadEntries: [{id, path}],  // entries whose referenced script no longer exists
+ *   note,
+ * }
+ *
+ * Matching is by FILENAME (basename), case-insensitive: an entry "covers" a file
+ * if the file's basename appears anywhere in the entry's `path` or invoke.command
+ * (so grouped family entries that list their variants in `path` cover them).
+ *
+ * CommonJS, Node built-ins only.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+// dirs/files that are not tools — never count as drift
+const SKIP_DIRS = new Set(['.archive', 'node_modules', 'scripts', 'docs', 'setup']);
+const TOOL_EXTS = new Set(['.js']);
+// obvious non-tool scripts (probes/tests) — surfaced separately, not as "missing"
+const NONTOOL_RE = /^(test_|_)/i;
+
+/** Every .js basename (lowercased) referenced by the register's path + invoke fields. */
+function registeredBasenames(data) {
+  const set = new Set();
+  const tools = Array.isArray(data && data.tools) ? data.tools : [];
+  const grab = (s) => {
+    if (typeof s !== 'string') return;
+    // filename run ending in .js — NO spaces in the class (so "wraps helper.js"
+    // yields "helper.js", not the whole phrase). path/dir prefixes are excluded too.
+    const m = s.match(/[A-Za-z0-9_.\-]+\.js/g);
+    if (m) for (const f of m) set.add(path.basename(f).toLowerCase());
+  };
+  for (const t of tools) {
+    grab(t.path);
+    if (t.invoke && typeof t.invoke.command === 'string') grab(t.invoke.command);
+    // a family entry may explicitly name the member files it covers
+    if (Array.isArray(t.covers)) for (const f of t.covers) {
+      if (typeof f === 'string') set.add(path.basename(f).toLowerCase());
+    }
+  }
+  return set;
+}
+
+/** Recursively collect .js files under dir, skipping SKIP_DIRS and dotdirs. */
+function scanTools(dir) {
+  const out = [];
+  let entries;
+  try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch (_e) { return out; }
+  for (const e of entries) {
+    if (e.isDirectory()) {
+      if (SKIP_DIRS.has(e.name) || e.name.startsWith('.')) continue;
+      out.push(...scanTools(path.join(dir, e.name)));
+    } else if (e.isFile() && TOOL_EXTS.has(path.extname(e.name).toLowerCase())) {
+      out.push(path.join(dir, e.name));
+    }
+  }
+  return out;
+}
+
+function detectDrift({ registerPath, toolsDir } = {}) {
+  if (!registerPath || !toolsDir) {
+    return { ok: false, error: 'detectDrift: registerPath and toolsDir are required' };
+  }
+  let data;
+  try {
+    data = JSON.parse(fs.readFileSync(registerPath, 'utf8'));
+  } catch (err) {
+    return { ok: false, error: `cannot read/parse register: ${err.message}` };
+  }
+
+  const registered = registeredBasenames(data);
+  const onDiskFiles = scanTools(toolsDir);
+  const onDiskBasenames = new Set(onDiskFiles.map((f) => path.basename(f).toLowerCase()));
+
+  // on disk but not referenced by any register entry (skip obvious probes/tests)
+  const missingFromRegister = [];
+  const nonToolScripts = [];
+  for (const f of onDiskFiles) {
+    const base = path.basename(f);
+    const lower = base.toLowerCase();
+    if (registered.has(lower)) continue;
+    if (NONTOOL_RE.test(base)) { nonToolScripts.push(base); continue; }
+    missingFromRegister.push(base);
+  }
+
+  // entries whose script-invoke path references a file no longer present under scriptsRoot
+  const deadEntries = [];
+  const tools = Array.isArray(data.tools) ? data.tools : [];
+  for (const t of tools) {
+    const p = typeof t.path === 'string' ? t.path : '';
+    const cmd = t.invoke && typeof t.invoke.command === 'string' ? t.invoke.command : '';
+    const m = p.match(/[A-Za-z0-9_\-]+\.js/) || cmd.match(/[A-Za-z0-9_\-]+\.js/);
+    if (m && !onDiskBasenames.has(m[0].toLowerCase())) {
+      deadEntries.push({ id: t.id, path: p });
+    }
+  }
+
+  missingFromRegister.sort();
+  nonToolScripts.sort();
+
+  return {
+    ok: true,
+    registerPath,
+    toolsDir,
+    registeredCount: registered.size,
+    onDiskCount: onDiskFiles.length,
+    missingFromRegister,
+    deadEntries,
+    nonToolScripts,
+    note:
+      'Scope: scans toolsDir (the scripts root) only. Scripts that live outside it ' +
+      'may be referenced by the register but are not drift-checked here. Matching is ' +
+      'by filename. nonToolScripts (test_*/_*) are listed separately, not counted as ' +
+      'missing.',
+  };
+}
+
+module.exports = { detectDrift, registeredBasenames, scanTools };

package/src/tools/registry.js

@@ -0,0 +1,468 @@
+'use strict';
+
+/**
+ * registry.js — the dynamic, persisted Tool Register (see the architecture doc §5).
+ *
+ * This is distinct from src/core/tool-registry.js: that one is the in-memory
+ * catalogue of tools handed to a backend at connect time. THIS one is the
+ * structured, on-disk register the lean meta-tools (toolfunnel_list_tools /
+ * toolfunnel_tool_instructions / toolfunnel_run_tool) read every call — so register edits
+ * are visible with no reconnect (§1, "no restart for register changes").
+ *
+ * Register entry shape (tools.register.json -> { version, description, tools:[] }):
+ *   { id, name, summary, category, instructions, invoke, mode? }
+ *   invoke is one of:
+ *     { type: "script", path: "scripts/<file>" }   // run a host-local script
+ *     { type: "shell",  command: "..." }            // run a shell command
+ *   mode (optional) is one of:
+ *     "gateway"   — execute the invoke server-side via the gated run path (default for
+ *                   a script/shell invoke; the original behaviour).
+ *     "reference" — do NOT execute; toolfunnel_run_tool returns the instructions so the
+ *                   connected AI runs the action itself. invoke may be omitted.
+ *   When mode is absent it is inferred: script/shell invoke -> "gateway", else "reference".
+ *
+ * Responsibilities:
+ *   list({filter?, category?})  -> briefs only [{id,name,summary,category}]
+ *   instructions(id)            -> the full instructions string (throws on unknown)
+ *   getEntry(id)                -> the full entry (clone; throws on unknown)
+ *   add(entry) / update(id,patch) / remove(id)  -> mutate + ATOMIC persist
+ *   resolveExecution(id, args)  -> { type, run: () => Promise<result> }
+ *                                  describes HOW to run the invoke. It does NOT
+ *                                  gate — gating is gated-run.js's job (§9).
+ *
+ * Pure-ish: the registry only touches its own JSON file + (for script invokes)
+ * spawns node on a path resolved under this src/tools dir. Dependencies that a
+ * test may want to stub (the executor) are injectable.
+ *
+ * CommonJS, Node built-ins only, atomic writes (temp + rename).
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawn } = require('node:child_process');
+
+const VALID_INVOKE_TYPES = new Set(['script', 'shell']);
+
+/**
+ * Execution modes (optional per-entry "mode" field):
+ *   "gateway"   — ToolFunnel EXECUTES the invoke server-side through the gated run path
+ *                 (the original behaviour for every script/shell tool).
+ *   "reference" — ToolFunnel does NOT execute. toolfunnel_run_tool returns the tool's
+ *                 instructions so the connected AI performs the action in ITS OWN
+ *                 environment. A reference tool needs no invoke (nothing runs here).
+ */
+const VALID_MODES = new Set(['reference', 'gateway']);
+
+/**
+ * Resolve an entry's execution mode. An explicit, valid `mode` wins. When absent it is
+ * INFERRED backward-compatibly: a script/shell invoke means "gateway" (run it here, as
+ * every existing tool does); anything else means "reference" (there is nothing to run).
+ * @param {object} entry a register entry
+ * @returns {"gateway"|"reference"}
+ */
+function resolveMode(entry) {
+  if (entry && (entry.mode === 'reference' || entry.mode === 'gateway')) return entry.mode;
+  const t = entry && entry.invoke && entry.invoke.type;
+  return t === 'script' || t === 'shell' ? 'gateway' : 'reference';
+}
+
+/** Deep-ish clone for plain JSON entries (structuredClone may be absent on old node). */
+function cloneEntry(entry) {
+  return JSON.parse(JSON.stringify(entry));
+}
+
+/**
+ * Atomic write: serialise to a temp file in the SAME directory as the target
+ * (so rename is atomic on the same filesystem/drive), fsync, then rename over
+ * the target. A crash leaves either the old file or the new file, never a
+ * half-written register.
+ */
+function atomicWriteJson(targetPath, obj) {
+  const dir = path.dirname(targetPath);
+  const base = path.basename(targetPath);
+  const tmp = path.join(dir, `.${base}.${process.pid}.${Date.now()}.tmp`);
+  const data = JSON.stringify(obj, null, 2) + '\n';
+  const fd = fs.openSync(tmp, 'w');
+  try {
+    fs.writeSync(fd, data, 0, 'utf8');
+    fs.fsyncSync(fd);
+  } finally {
+    fs.closeSync(fd);
+  }
+  fs.renameSync(tmp, targetPath);
+}
+
+/** Validate a register entry shape; throws with a clear message on a bad shape. */
+function validateEntry(entry, { requireId = true } = {}) {
+  if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+    throw new Error('Registry: entry must be an object');
+  }
+  if (requireId && (typeof entry.id !== 'string' || entry.id.length === 0)) {
+    throw new Error('Registry: entry.id must be a non-empty string');
+  }
+  if (typeof entry.name !== 'string' || entry.name.length === 0) {
+    throw new Error(`Registry: entry.name must be a non-empty string (id=${entry.id})`);
+  }
+  // Optional execution mode. When present it must be one of the valid modes.
+  if (entry.mode !== undefined && !VALID_MODES.has(entry.mode)) {
+    throw new Error(
+      `Registry: entry.mode must be one of ${[...VALID_MODES].join('|')} (id=${entry.id})`
+    );
+  }
+  // A reference tool executes nothing server-side, so its invoke may be omitted. Only an
+  // EXPLICIT mode:"reference" relaxes this — with mode absent the invoke is still required
+  // (backward-compatible: every existing tool keeps its mandatory invoke).
+  if (entry.mode === 'reference' && entry.invoke === undefined) {
+    return entry;
+  }
+  const inv = entry.invoke;
+  if (!inv || typeof inv !== 'object') {
+    throw new Error(`Registry: entry.invoke is required (id=${entry.id})`);
+  }
+  if (!VALID_INVOKE_TYPES.has(inv.type)) {
+    throw new Error(
+      `Registry: entry.invoke.type must be one of ${[...VALID_INVOKE_TYPES].join('|')} (id=${entry.id})`
+    );
+  }
+  if (inv.type === 'script' && (typeof inv.path !== 'string' || inv.path.length === 0)) {
+    throw new Error(`Registry: script invoke needs a non-empty "path" (id=${entry.id})`);
+  }
+  if (inv.type === 'shell' && (typeof inv.command !== 'string' || inv.command.length === 0)) {
+    throw new Error(`Registry: shell invoke needs a non-empty "command" (id=${entry.id})`);
+  }
+  return entry;
+}
+
+/**
+ * Default script executor: spawn `node <resolved script>` with the structured
+ * args passed in env TOOLFUNNEL_TOOL_ARGS. Resolves with { ok, code, stdout, stderr }.
+ * Never rejects on a non-zero exit — the caller (the gated runner / meta-tool)
+ * decides how to surface a tool failure. It DOES reject only on spawn failure.
+ *
+ * Path safety: the script path must resolve INSIDE scriptsRoot (defense-in-depth
+ * for the isolation rule — a register entry must not become a path-escape).
+ */
+function defaultRunScript(scriptsRoot, invoke, args) {
+  return new Promise((resolve, reject) => {
+    const resolved = path.resolve(scriptsRoot, path.basename(invoke.path));
+    // path.basename strips any directory traversal; confirm anyway.
+    const rel = path.relative(scriptsRoot, resolved);
+    if (rel === '' || rel.startsWith('..') || path.isAbsolute(rel)) {
+      reject(new Error(`Registry: script path escapes scripts root ("${invoke.path}")`));
+      return;
+    }
+    if (!fs.existsSync(resolved)) {
+      reject(new Error(`Registry: script not found ("${resolved}")`));
+      return;
+    }
+    const child = spawn(process.execPath, [resolved], {
+      env: { ...process.env, TOOLFUNNEL_TOOL_ARGS: JSON.stringify(args ?? null) },
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    let stdout = '';
+    let stderr = '';
+    child.stdout.on('data', (d) => { stdout += d.toString(); });
+    child.stderr.on('data', (d) => { stderr += d.toString(); });
+    child.on('error', reject);
+    child.on('close', (code) => {
+      resolve({ ok: code === 0, code, stdout, stderr });
+    });
+  });
+}
+
+class Registry {
+  /**
+   * @param {object} opts
+   * @param {string} opts.filePath          path to tools.register.json (source of truth on disk)
+   * @param {object} opts.data              parsed register data { version, description, tools }
+   * @param {string} [opts.scriptsRoot]     dir holding script-invoke targets (default: <fileDir>/scripts)
+   * @param {Function} [opts.runScript]     injectable (scriptsRoot, invoke, args) => Promise<result>
+   */
+  constructor({ filePath, data, scriptsRoot, runScript } = {}) {
+    if (!filePath) throw new Error('Registry: filePath is required');
+    this._filePath = filePath;
+    this._scriptsRoot = scriptsRoot || path.join(path.dirname(filePath), 'scripts');
+    this._runScript = runScript || defaultRunScript;
+
+    const d = data && typeof data === 'object' ? data : {};
+    this._version = typeof d.version === 'number' ? d.version : 1;
+    this._description = typeof d.description === 'string' ? d.description : '';
+    const tools = Array.isArray(d.tools) ? d.tools : [];
+
+    // Index by id; reject duplicate ids at load (a duplicate id makes
+    // instructions(id)/run(id) ambiguous).
+    this._byId = new Map();
+    for (const t of tools) {
+      validateEntry(t);
+      if (this._byId.has(t.id)) {
+        throw new Error(`Registry: duplicate tool id "${t.id}" in ${filePath}`);
+      }
+      this._byId.set(t.id, cloneEntry(t));
+    }
+  }
+
+  // ---- read API -----------------------------------------------------------
+
+  /**
+   * Briefs only — the surface toolfunnel_list_tools returns. Optional case-insensitive
+   * substring `filter` (matched against id/name/summary) and exact `category`.
+   * @returns {Array<{id,name,summary,category}>} in insertion order.
+   */
+  list({ filter, category } = {}) {
+    const needle = typeof filter === 'string' && filter.length ? filter.toLowerCase() : null;
+    const out = [];
+    for (const t of this._byId.values()) {
+      if (category && t.category !== category) continue;
+      if (needle) {
+        const hay = `${t.id} ${t.name} ${t.summary || ''}`.toLowerCase();
+        if (!hay.includes(needle)) continue;
+      }
+      out.push({
+        id: t.id,
+        name: t.name,
+        summary: t.summary || '',
+        category: t.category || '',
+      });
+    }
+    return out;
+  }
+
+  /** Full instructions string for one tool. Throws on unknown id (per §5 contract). */
+  instructions(id) {
+    const t = this._byId.get(id);
+    if (!t) throw new Error(`Registry.instructions: unknown tool id "${id}"`);
+    return typeof t.instructions === 'string' ? t.instructions : '';
+  }
+
+  /** Full entry (cloned so callers can't mutate internal state). Throws on unknown id. */
+  getEntry(id) {
+    const t = this._byId.get(id);
+    if (!t) throw new Error(`Registry.getEntry: unknown tool id "${id}"`);
+    return cloneEntry(t);
+  }
+
+  /** @returns {boolean} */
+  has(id) {
+    return this._byId.has(id);
+  }
+
+  // ---- write API (atomic persist) ----------------------------------------
+
+  /** Add a new entry. Throws if id missing/duplicate or shape invalid. Persists. */
+  add(entry) {
+    validateEntry(entry);
+    if (this._byId.has(entry.id)) {
+      throw new Error(`Registry.add: tool id "${entry.id}" already exists`);
+    }
+    this._byId.set(entry.id, cloneEntry(entry));
+    this._persist();
+    return this.getEntry(entry.id);
+  }
+
+  /**
+   * Patch an existing entry. `id` cannot be changed via patch (it's the key).
+   * Merges shallow over the existing entry, re-validates, persists.
+   */
+  update(id, patch) {
+    const existing = this._byId.get(id);
+    if (!existing) throw new Error(`Registry.update: unknown tool id "${id}"`);
+    if (!patch || typeof patch !== 'object') {
+      throw new Error('Registry.update: patch must be an object');
+    }
+    const merged = { ...existing, ...patch, id };
+    validateEntry(merged);
+    this._byId.set(id, cloneEntry(merged));
+    this._persist();
+    return this.getEntry(id);
+  }
+
+  /** Remove an entry. Throws on unknown id. Persists. */
+  remove(id) {
+    if (!this._byId.has(id)) throw new Error(`Registry.remove: unknown tool id "${id}"`);
+    this._byId.delete(id);
+    this._persist();
+    return true;
+  }
+
+  /**
+   * Write a host-local script's text under this scriptsRoot, atomically.
+   *
+   * Resolves path.basename(invokePath) under scriptsRoot (basename strips any
+   * directory traversal) and GUARDS that the resolved path stays inside
+   * scriptsRoot — the same path-escape defence as defaultRunScript, so a
+   * tf_tool_add(scriptText) can never write outside the isolation root. Writes
+   * `text` via a temp file in the same dir + fsync + rename (mirror of
+   * atomicWriteJson): a crash leaves either no file or the complete file.
+   *
+   * @param {string} invokePath  e.g. "scripts/foo.js" — only the basename is honoured
+   * @param {string} text        full file contents to write
+   * @returns {string} the resolved absolute path that was written
+   */
+  writeScript(invokePath, text) {
+    if (typeof invokePath !== 'string' || invokePath.length === 0) {
+      throw new Error('Registry.writeScript: invokePath (non-empty string) is required');
+    }
+    if (typeof text !== 'string') {
+      throw new Error('Registry.writeScript: text must be a string');
+    }
+    const scriptsRoot = this._scriptsRoot;
+    const resolved = path.resolve(scriptsRoot, path.basename(invokePath));
+    // path.basename strips any directory traversal; confirm anyway.
+    const rel = path.relative(scriptsRoot, resolved);
+    if (rel === '' || rel.startsWith('..') || path.isAbsolute(rel)) {
+      throw new Error(`Registry.writeScript: script path escapes scripts root ("${invokePath}")`);
+    }
+    fs.mkdirSync(scriptsRoot, { recursive: true });
+    const dir = path.dirname(resolved);
+    const base = path.basename(resolved);
+    const tmp = path.join(dir, `.${base}.${process.pid}.${Date.now()}.tmp`);
+    const fd = fs.openSync(tmp, 'w');
+    try {
+      fs.writeSync(fd, text, 0, 'utf8');
+      fs.fsyncSync(fd);
+    } finally {
+      fs.closeSync(fd);
+    }
+    fs.renameSync(tmp, resolved);
+    return resolved;
+  }
+
+  // ---- execution description (does NOT gate) ------------------------------
+
+  /**
+   * Describe HOW to run a tool's invoke. Returns { type, run } where `run` is a
+   * zero-arg function returning a Promise of the tool result. resolveExecution
+   * performs NO gating — toolfunnel_run_tool / gated-run.js fires the PreToolUse hook
+   * and only then calls `run()` (the architecture doc §2/§9). Keeping the gate
+   * out of here keeps the safety case in one auditable place.
+   *
+   * - script invoke: run() spawns node on the host-local script (via the injected
+   *   runScript), passing args in TOOLFUNNEL_TOOL_ARGS.
+   * - shell invoke: run() does NOT execute here. It returns a descriptor
+   *   { type:'shell', command, args } so the gated runner owns the actual shell
+   *   spawn (the broadest power) behind the gate. This keeps arbitrary shell
+   *   execution out of the un-gated register module by design.
+   *
+   * @param {string} id
+   * @param {any} args  structured args forwarded to the tool
+   * @returns {{ type: string, run: () => Promise<any> }}
+   */
+  resolveExecution(id, args) {
+    const entry = this._byId.get(id);
+    if (!entry) throw new Error(`Registry.resolveExecution: unknown tool id "${id}"`);
+    const mode = resolveMode(entry);
+
+    // ---- reference mode: nothing runs here. ----------------------------------
+    // The connected AI performs the action in its own environment. We hand back the
+    // tool's instructions (no `run`) so the run-path can short-circuit BEFORE the gate
+    // — a reference tool never spawns and never needs gating (nothing executes).
+    if (mode === 'reference') {
+      return {
+        type: 'reference',
+        mode: 'reference',
+        instructions: typeof entry.instructions === 'string' ? entry.instructions : '',
+      };
+    }
+
+    const invoke = entry.invoke;
+
+    if (invoke.type === 'script') {
+      const scriptsRoot = this._scriptsRoot;
+      const runScript = this._runScript;
+      return {
+        type: 'script',
+        mode: 'gateway',
+        run: () => runScript(scriptsRoot, invoke, args),
+      };
+    }
+
+    if (invoke.type === 'shell') {
+      // Deliberately do NOT spawn a shell here. Hand the descriptor to the
+      // gated runner, which executes shell only after PreToolUse allows it.
+      return {
+        type: 'shell',
+        mode: 'gateway',
+        run: async () => ({
+          deferred: true,
+          type: 'shell',
+          command: invoke.command,
+          args: args ?? null,
+        }),
+      };
+    }
+
+    // validateEntry guards the load path, but guard here too for late mutation.
+    throw new Error(`Registry.resolveExecution: unsupported invoke.type for "${id}"`);
+  }
+
+  /**
+   * The resolved execution mode for a tool ("gateway" | "reference"). Exposed so callers
+   * (UI, tests) can ask without resolving a full executor. Throws on unknown id.
+   * @param {string} id
+   * @returns {"gateway"|"reference"}
+   */
+  mode(id) {
+    const entry = this._byId.get(id);
+    if (!entry) throw new Error(`Registry.mode: unknown tool id "${id}"`);
+    return resolveMode(entry);
+  }
+
+  // ---- internals ----------------------------------------------------------
+
+  /** Serialise current state back to the register file atomically. */
+  _persist() {
+    const obj = {
+      version: this._version,
+      description: this._description,
+      tools: [...this._byId.values()],
+    };
+    atomicWriteJson(this._filePath, obj);
+  }
+
+  /** @returns {number} */
+  get size() {
+    return this._byId.size;
+  }
+}
+
+/**
+ * loadRegistry(path) -> Registry
+ *
+ * Reads + parses the register JSON at `filePath` and returns a Registry bound to
+ * it. Throws a clear error on a missing/malformed file or a bad entry shape so
+ * misconfiguration is caught at load time, not at model-call time.
+ *
+ * @param {string} filePath
+ * @param {object} [opts]  forwarded to the Registry ctor (scriptsRoot, runScript)
+ * @returns {Registry}
+ */
+function loadRegistry(filePath, opts = {}) {
+  if (typeof filePath !== 'string' || filePath.length === 0) {
+    throw new Error('loadRegistry: filePath (non-empty string) is required');
+  }
+  let raw;
+  try {
+    raw = fs.readFileSync(filePath, 'utf8');
+  } catch (err) {
+    throw new Error(`loadRegistry: cannot read register at "${filePath}": ${err.message}`);
+  }
+  let data;
+  try {
+    data = JSON.parse(raw);
+  } catch (err) {
+    throw new Error(`loadRegistry: register at "${filePath}" is not valid JSON: ${err.message}`);
+  }
+  return new Registry({ filePath, data, ...opts });
+}
+
+module.exports = {
+  Registry,
+  loadRegistry,
+  // exported for unit tests / the gated runner
+  atomicWriteJson,
+  validateEntry,
+  defaultRunScript,
+  resolveMode,
+  VALID_INVOKE_TYPES,
+  VALID_MODES,
+};