toolfunnel 0.5.0 → 0.7.0

package/src/core/logger.js

@@ -1,171 +1,297 @@
-'use strict';
-
-/**
- * logger.js — a toggleable JSONL activity/audit log for the gateway.
- *
- * DEFAULT OFF (privacy + lean). Nothing is written, and no files are created, unless
- * logging has been explicitly enabled via setConfig(). A MISSING config file means
- * disabled — the safe default — so a fresh checkout logs nothing.
- *
- * Design rules:
- *   - Zero dependencies. Node built-ins only (fs, path). No transport, no SDK.
- *   - Config is read FRESH on every call (no caching), so a toggle takes effect for the
- *     very next event without a reconnect or restart.
- *   - log() must NEVER throw. A logging failure (bad config, unwritable disk, full FS)
- *     must never break a tool call or the gate. Everything is wrapped; failures are
- *     swallowed silently.
- *
- * Paths are resolved against the repo root (two dirs up from src/core/). The configured
- * log `path` may be relative (resolved against root) or absolute.
- *
- * Config file: <root>/logs/log.config.json
- *   { "enabled": false, "path": "logs/toolfunnel.log.jsonl" }
- *
- * CommonJS only.
- */
-
-const fs = require('node:fs');
-const path = require('node:path');
-
-/** The CONFIG HOME (TOOLFUNNEL_HOME / --config-dir; defaults to the package root — see
- *  config-home.js). Logs + their toggle are user-state, so they live with the home. */
-const { resolveConfigHome } = require('./config-home');
-const ROOT = resolveConfigHome();
-
-/** The toggle/config file. NOT created until setConfig() writes it. */
-const CONFIG_PATH = path.join(ROOT, 'logs', 'log.config.json');
-
-/** Safe defaults — used whenever the config file is absent or unreadable. */
-const DEFAULT_ENABLED = false;
-const DEFAULT_PATH = 'logs/toolfunnel.log.jsonl';
-
-/**
- * Resolve a (possibly relative) log path against the repo root.
- * @param {string} p
- * @returns {string}
- */
-function resolveLogPath(p) {
-  return path.isAbsolute(p) ? p : path.join(ROOT, p);
-}
-
-/**
- * getConfig — the resolved { enabled, path }.
- *
- * Reads the config file fresh. A missing/unreadable/malformed file resolves to the
- * safe defaults (disabled). Never throws.
- *
- * @returns {{ enabled: boolean, path: string }}
- */
-function getConfig() {
-  try {
-    const raw = fs.readFileSync(CONFIG_PATH, 'utf8');
-    const parsed = JSON.parse(raw);
-    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
-      return { enabled: DEFAULT_ENABLED, path: DEFAULT_PATH };
-    }
-    return {
-      enabled: parsed.enabled === true,
-      path:
-        typeof parsed.path === 'string' && parsed.path.length > 0
-          ? parsed.path
-          : DEFAULT_PATH,
-    };
-  } catch (_err) {
-    // Missing file = disabled (the safe default); also covers unreadable/malformed.
-    return { enabled: DEFAULT_ENABLED, path: DEFAULT_PATH };
-  }
-}
-
-/**
- * log — append one JSONL record IF logging is enabled, else a silent no-op.
- *
- * The record is the event fields plus a logger-stamped ISO-8601 "ts" timestamp.
- * Resolves the configured path against root, mkdir -p its directory, and appends one
- * line with fs.appendFileSync. NEVER throws — any failure is swallowed.
- *
- * @param {object} event arbitrary serialisable fields (e.g. { type, tool, decision }).
- */
-function log(event) {
-  try {
-    const cfg = getConfig();
-    if (!cfg.enabled) return; // default-off: no-op, no file created.
-
-    const record = Object.assign(
-      { ts: new Date().toISOString() },
-      event && typeof event === 'object' && !Array.isArray(event) ? event : {}
-    );
-
-    const logPath = resolveLogPath(cfg.path);
-    fs.mkdirSync(path.dirname(logPath), { recursive: true });
-    fs.appendFileSync(logPath, JSON.stringify(record) + '\n');
-  } catch (_err) {
-    // Logging must NEVER break the caller. Swallow everything.
-  }
-}
-
-/**
- * setConfig — atomically merge a patch into logs/log.config.json (temp + rename).
- *
- * Merges with the current resolved config so a partial patch (e.g. { enabled: true })
- * preserves the existing path. Creates the logs/ dir and the config file if absent —
- * this is the ONLY function that creates the config file.
- *
- * @param {{ enabled?: boolean, path?: string }} patch
- * @returns {{ enabled: boolean, path: string }} the merged, written config.
- */
-function setConfig(patch) {
-  const current = getConfig();
-  const p = patch && typeof patch === 'object' && !Array.isArray(patch) ? patch : {};
-
-  const next = {
-    enabled: typeof p.enabled === 'boolean' ? p.enabled : current.enabled,
-    path:
-      typeof p.path === 'string' && p.path.length > 0 ? p.path : current.path,
-  };
-
-  fs.mkdirSync(path.dirname(CONFIG_PATH), { recursive: true });
-  // Atomic write: write a unique temp file, then rename over the target.
-  const tmp = CONFIG_PATH + '.' + process.pid + '.' + Date.now() + '.tmp';
-  fs.writeFileSync(tmp, JSON.stringify(next, null, 2) + '\n');
-  fs.renameSync(tmp, CONFIG_PATH);
-
-  return next;
-}
-
-/**
- * tail — return the last n parsed JSON lines from the configured log.
- *
- * Returns [] if the log is missing or unreadable. Unparseable lines are skipped. When
- * n is not a positive finite number, all lines are returned. Never throws.
- *
- * @param {number} [n] how many trailing lines to parse and return.
- * @returns {object[]}
- */
-function tail(n) {
-  try {
-    const cfg = getConfig();
-    const logPath = resolveLogPath(cfg.path);
-    const raw = fs.readFileSync(logPath, 'utf8');
-    const lines = raw.split('\n').filter(function (l) {
-      return l.length > 0;
-    });
-
-    const wanted =
-      typeof n === 'number' && isFinite(n) && n > 0 ? Math.floor(n) : lines.length;
-    const slice = lines.slice(-wanted);
-
-    const out = [];
-    for (let i = 0; i < slice.length; i++) {
-      try {
-        out.push(JSON.parse(slice[i]));
-      } catch (_e) {
-        // Skip a corrupt/partial line rather than failing the whole tail.
-      }
-    }
-    return out;
-  } catch (_err) {
-    return [];
-  }
-}
-
-module.exports = { log, setConfig, getConfig, tail };
+'use strict';
+
+/**
+ * logger.js - a toggleable JSONL activity/audit log for the gateway.
+ *
+ * DEFAULT OFF (privacy + lean). Nothing is written, and no files are created, unless
+ * logging has been explicitly enabled via setConfig(). A MISSING config file means
+ * disabled - the safe default - so a fresh checkout logs nothing.
+ *
+ * Design rules:
+ *   - Zero dependencies. Node built-ins only (fs, path). No transport, no SDK.
+ *   - Config is read FRESH on every call (no caching), so a toggle takes effect for the
+ *     very next event without a reconnect or restart.
+ *   - log() must NEVER throw. A logging failure (bad config, unwritable disk, full FS)
+ *     must never break a tool call or the gate. Everything is wrapped; failures are
+ *     swallowed silently.
+ *
+ * Paths are resolved against the config home, and the resolved path MUST stay inside
+ * <home>/logs/ (0.7.0; logging.test.js step 5 is the acceptance). The log path is
+ * settable from the tf_log tool surface and the UI's POST /api/logs/config, and every
+ * other file-writing path in the repo is confined to its root (hook-loader's scripts-dir
+ * assert, registry.writeScript, sendStatic) - this one now matches. setConfig REFUSES an
+ * out-of-home path loudly; getConfig treats one already in the file as unset (default),
+ * so log() and tail() stay in-home even against a hand-edited config. An operator who
+ * wants the log on another disk can make <home>/logs a symlink/junction - containment is
+ * checked on the unfollowed path.
+ *
+ * Config file: <root>/logs/log.config.json
+ *   { "enabled": false, "path": "logs/toolfunnel.log.jsonl" }
+ *
+ * Both paths are BOUNDED (0.7.0, log-rotation.test.js): the live file rotates to `<path>.1`
+ * at MAX_LOG_BYTES (one older generation kept), and tail(n) reads a trailing slice rather
+ * than the whole file - with a whole-file fallback so bounding never changes an answer.
+ *
+ * CommonJS only.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+/** The CONFIG HOME (TOOLFUNNEL_HOME / --config-dir; defaults to the package root - see
+ *  config-home.js). Logs + their toggle are user-state, so they live with the home. */
+const { resolveConfigHome } = require('./config-home');
+const ROOT = resolveConfigHome();
+
+/** The toggle/config file. NOT created until setConfig() writes it. */
+const CONFIG_PATH = path.join(ROOT, 'logs', 'log.config.json');
+
+/** Safe defaults - used whenever the config file is absent or unreadable. */
+const DEFAULT_ENABLED = false;
+const DEFAULT_PATH = 'logs/toolfunnel.log.jsonl';
+
+/**
+ * The live file's size cap. An append that finds the file at/over it first renames the
+ * file to `<path>.1` (ONE older generation, overwritten by the next rotation), so disk
+ * use is bounded at ~2x the cap and the no-argument tail() (the documented all-lines
+ * mode, tf_log status's count) can never be asked to parse an unbounded file again.
+ * Rotation is best-effort: if the rename is refused (e.g. a reader holds `.1` open on
+ * win32) the append proceeds on the oversized live file and rotation retries next call -
+ * a record is never dropped for the sake of the cap.
+ */
+const MAX_LOG_BYTES = 5 * 1024 * 1024;
+
+/** tail(n)'s bounded read: bytes budgeted per requested line (generous - records run
+ *  ~100-200 bytes), with a floor so tiny n still reads one decent chunk. */
+const TAIL_BYTES_PER_LINE = 1024;
+const TAIL_READ_MIN_BYTES = 64 * 1024;
+
+/** The directory every log path must resolve inside. */
+const LOG_DIR = path.join(ROOT, 'logs');
+
+/**
+ * Resolve a (possibly relative) log path against the config home, REQUIRING the result
+ * to stay inside <home>/logs/. Returns the resolved absolute path, or null when it
+ * resolves outside (same refusal shape as registry.js defaultRunScript: '' would be the
+ * dir itself, '..'-prefixed left it, absolute rel = another drive on win32).
+ * @param {string} p
+ * @returns {string|null}
+ */
+function resolveLogPath(p) {
+  const resolved = path.resolve(ROOT, String(p));
+  const rel = path.relative(LOG_DIR, resolved);
+  if (rel === '' || rel.startsWith('..') || path.isAbsolute(rel)) return null;
+  return resolved;
+}
+
+/**
+ * getConfig - the resolved { enabled, path }.
+ *
+ * Reads the config file fresh. A missing/unreadable/malformed file resolves to the
+ * safe defaults (disabled). Never throws.
+ *
+ * @returns {{ enabled: boolean, path: string }}
+ */
+function getConfig() {
+  try {
+    const raw = fs.readFileSync(CONFIG_PATH, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+      return { enabled: DEFAULT_ENABLED, path: DEFAULT_PATH };
+    }
+    return {
+      enabled: parsed.enabled === true,
+      // A path that resolves outside <home>/logs/ is treated as UNSET, not honoured: the
+      // config file can be edited directly, and the readers (log/tail) must stay in-home
+      // regardless of how the value got there. setConfig additionally refuses one loudly.
+      path:
+        typeof parsed.path === 'string' && parsed.path.length > 0 && resolveLogPath(parsed.path) !== null
+          ? parsed.path
+          : DEFAULT_PATH,
+    };
+  } catch (_err) {
+    // Missing file = disabled (the safe default); also covers unreadable/malformed.
+    return { enabled: DEFAULT_ENABLED, path: DEFAULT_PATH };
+  }
+}
+
+/**
+ * log - append one JSONL record IF logging is enabled, else a silent no-op.
+ *
+ * The record is the event fields plus a logger-stamped ISO-8601 "ts" timestamp.
+ * Resolves the configured path against root, mkdir -p its directory, and appends one
+ * line with fs.appendFileSync. NEVER throws - any failure is swallowed.
+ *
+ * @param {object} event arbitrary serialisable fields (e.g. { type, tool, decision }).
+ */
+function log(event) {
+  try {
+    const cfg = getConfig();
+    if (!cfg.enabled) return; // default-off: no-op, no file created.
+
+    const record = Object.assign(
+      { ts: new Date().toISOString() },
+      event && typeof event === 'object' && !Array.isArray(event) ? event : {}
+    );
+
+    const logPath = resolveLogPath(cfg.path);
+    if (logPath === null) return; // cannot happen via getConfig (it sanitises); belt-and-braces
+    fs.mkdirSync(path.dirname(logPath), { recursive: true });
+
+    // Rotate BEFORE the append when the live file has reached the cap. Its own try/catch:
+    // a refused stat/rename must never cost the record below. `logPath + '.1'` inherits
+    // logPath's containment, and rename replaces an existing `.1` (one older generation).
+    try {
+      if (fs.statSync(logPath).size >= MAX_LOG_BYTES) {
+        fs.renameSync(logPath, logPath + '.1');
+      }
+    } catch (_e) {
+      // Missing file (nothing to rotate) or a refused rename - append regardless.
+    }
+
+    fs.appendFileSync(logPath, JSON.stringify(record) + '\n');
+  } catch (_err) {
+    // Logging must NEVER break the caller. Swallow everything.
+  }
+}
+
+/**
+ * setConfig - atomically merge a patch into logs/log.config.json (temp + rename).
+ *
+ * Merges with the current resolved config so a partial patch (e.g. { enabled: true })
+ * preserves the existing path. Creates the logs/ dir and the config file if absent -
+ * this is the ONLY function that creates the config file.
+ *
+ * @param {{ enabled?: boolean, path?: string }} patch
+ * @returns {{ enabled: boolean, path: string }} the merged, written config.
+ */
+function setConfig(patch) {
+  const current = getConfig();
+  const p = patch && typeof patch === 'object' && !Array.isArray(patch) ? patch : {};
+
+  // Refuse an out-of-home path LOUDLY before anything is written. Reaches every setter
+  // surface (tf_log's { ok:false }, the UI's error response) with nothing persisted.
+  // `current.path` needs no re-check - getConfig only ever returns a contained path.
+  // The code lets callers tell "you sent a bad path" (client input -> the UI's 400) apart
+  // from a genuine write failure (disk, perms -> 500) without matching on message prose.
+  if (typeof p.path === 'string' && p.path.length > 0 && resolveLogPath(p.path) === null) {
+    const err = new Error(
+      `log path refused: "${p.path}" resolves outside the config home's logs directory - ` +
+      'the activity log lives inside <home>/logs'
+    );
+    err.code = 'TF_LOG_PATH_REFUSED';
+    throw err;
+  }
+
+  const next = {
+    enabled: typeof p.enabled === 'boolean' ? p.enabled : current.enabled,
+    path:
+      typeof p.path === 'string' && p.path.length > 0 ? p.path : current.path,
+  };
+
+  fs.mkdirSync(path.dirname(CONFIG_PATH), { recursive: true });
+  // Atomic write: write a unique temp file, then rename over the target.
+  const tmp = CONFIG_PATH + '.' + process.pid + '.' + Date.now() + '.tmp';
+  fs.writeFileSync(tmp, JSON.stringify(next, null, 2) + '\n');
+  fs.renameSync(tmp, CONFIG_PATH);
+
+  return next;
+}
+
+/**
+ * Read the trailing slice of a file that is expected to contain the last `wanted` lines:
+ * the final min(size, max(64 KB, wanted KB)) bytes. When the read starts mid-file the
+ * first segment may be a PARTIAL line, so it is dropped (mid-character utf8 starts land
+ * in that dropped segment too). Returns the complete lines it can vouch for, plus whether
+ * the whole file was covered - the caller falls back to a whole-file read on a shortfall
+ * (e.g. one line longer than the window), so the bounded path can never change an answer,
+ * only the bytes it took to produce it.
+ * @param {string} logPath
+ * @param {number} wanted
+ * @returns {{ lines: string[], wholeFile: boolean }}
+ */
+function readTrailingLines(logPath, wanted) {
+  const fd = fs.openSync(logPath, 'r');
+  try {
+    const size = fs.fstatSync(fd).size;
+    const budget = Math.max(TAIL_READ_MIN_BYTES, wanted * TAIL_BYTES_PER_LINE);
+    const readLen = Math.min(size, budget);
+    const position = size - readLen;
+    const buf = Buffer.alloc(readLen);
+    let got = 0;
+    while (got < readLen) {
+      const r = fs.readSync(fd, buf, got, readLen - got, position + got);
+      if (r <= 0) break; // shrank underneath us (rotation) - use what we have
+      got += r;
+    }
+    let text = buf.toString('utf8', 0, got);
+    if (position > 0) {
+      const firstNl = text.indexOf('\n');
+      text = firstNl === -1 ? '' : text.slice(firstNl + 1);
+    }
+    const lines = text.split('\n').filter(function (l) { return l.length > 0; });
+    return { lines, wholeFile: position === 0 };
+  } finally {
+    try { fs.closeSync(fd); } catch (_e) { /* ignore */ }
+  }
+}
+
+/**
+ * tail - return the last n parsed JSON lines from the configured log.
+ *
+ * Returns [] if the log is missing or unreadable. Unparseable lines are skipped. When
+ * n is not a positive finite number, all lines are returned. Never throws.
+ *
+ * A finite n reads a BOUNDED trailing slice (~1 KB budgeted per requested line), not the
+ * whole file - with a whole-file fallback when the slice holds fewer than n lines, so the
+ * answer is byte-identical to the unbounded engine's in every case. The no-argument mode
+ * still reads everything by design; rotation (MAX_LOG_BYTES) bounds that file for it.
+ *
+ * @param {number} [n] how many trailing lines to parse and return.
+ * @returns {object[]}
+ */
+function tail(n) {
+  try {
+    const cfg = getConfig();
+    const logPath = resolveLogPath(cfg.path);
+    if (logPath === null) return []; // cannot happen via getConfig (it sanitises); belt-and-braces
+
+    const bounded = typeof n === 'number' && isFinite(n) && n > 0;
+    let lines;
+    let wanted;
+    if (bounded) {
+      wanted = Math.floor(n);
+      const sliceRead = readTrailingLines(logPath, wanted);
+      if (sliceRead.lines.length >= wanted || sliceRead.wholeFile) {
+        lines = sliceRead.lines;
+      } else {
+        // Shortfall on a partial window (unusually long lines): take the exact answer
+        // over the byte bound.
+        lines = fs.readFileSync(logPath, 'utf8').split('\n').filter(function (l) {
+          return l.length > 0;
+        });
+      }
+    } else {
+      lines = fs.readFileSync(logPath, 'utf8').split('\n').filter(function (l) {
+        return l.length > 0;
+      });
+      wanted = lines.length;
+    }
+
+    const slice = lines.slice(-wanted);
+
+    const out = [];
+    for (let i = 0; i < slice.length; i++) {
+      try {
+        out.push(JSON.parse(slice[i]));
+      } catch (_e) {
+        // Skip a corrupt/partial line rather than failing the whole tail.
+      }
+    }
+    return out;
+  } catch (_err) {
+    return [];
+  }
+}
+
+module.exports = { log, setConfig, getConfig, tail };

package/src/core/matcher.js

@@ -1,51 +1,100 @@
-'use strict';
-
-/**
- * matcher.js — does a hook's matcher string fire for a given tool? (HOOK_ENGINE.md §5)
- *
- * Mirrors Claude Code's matcher semantics:
- *   - ""  | undefined | "*"  → always fire (wildcard).
- *   - otherwise the matcher is a regex, anchored as a FULL match against toolName
- *     (e.g. "Bash|Write|Edit").
- *   - tool-less events (SessionStart, UserPromptSubmit, Stop, PreCompact) pass
- *     toolName == null/undefined → always fire (the matcher is ignored).
- *
- * CommonJS only. Zero host imports (core/ must run headless under node --test).
- */
-
-/**
- * @param {string|undefined|null} matcher  the hook's matcher string.
- * @param {string|undefined|null} toolName the tool the model requested, or
- *        null/undefined for events without a tool.
- * @returns {boolean} true if the hook should fire for this tool.
- */
-function matches(matcher, toolName) {
-  // Wildcard / unset matcher → always fire, regardless of tool.
-  if (matcher === undefined || matcher === null || matcher === '' || matcher === '*') {
-    return true;
-  }
-
-  // Tool-less events: there is nothing to match against, so the matcher is
-  // ignored and the hook always fires (§5). This is checked AFTER the wildcard
-  // case so a "*" matcher is handled uniformly, and BEFORE we attempt a regex
-  // (which would otherwise need a string to test).
-  if (toolName === undefined || toolName === null) {
-    return true;
-  }
-
-  // Anything else is a regex, anchored as a full match against toolName.
-  // We wrap in ^(?:…)$ so alternations like "Bash|Write" mean "the whole tool
-  // name is one of these", not "contains one of these".
-  let re;
-  try {
-    re = new RegExp(`^(?:${matcher})$`);
-  } catch (err) {
-    // A malformed matcher must never throw out of the engine. Treat an
-    // uncompilable pattern as "does not match" — fail closed, stay defensive.
-    return false;
-  }
-
-  return re.test(toolName);
-}
-
-module.exports = { matches };
+'use strict';
+
+/**
+ * matcher.js - does a hook's matcher string fire for a given tool?
+ *
+ * Mirrors Claude Code's matcher semantics:
+ *   - ""  | undefined | "*"  -> always fire (wildcard).
+ *   - otherwise the matcher is a regex, anchored as a FULL match against toolName
+ *     (e.g. "Bash|Write|Edit").
+ *   - tool-less events (SessionStart, UserPromptSubmit, Stop, PreCompact) pass
+ *     toolName == null/undefined -> always fire (the matcher is ignored).
+ *
+ * CommonJS only. Zero host imports (core/ must run headless under node --test).
+ */
+
+// One compile per distinct matcher string. matches() sits on the gate's hot path (every
+// hook x every tool call), and rebuilding `^(?:Bash|Write|Edit)$` per call was pure waste:
+// RegExp construction is a deterministic function of the string and ours carries no flags
+// (no g/y -> no lastIndex state), so memoising by the string can never change an answer.
+// Invalidation is by construction, not by event: a reloaded manifest's new matcher is a
+// NEW string -> a new key; the old entry just goes unused. Failed compiles memoise too
+// (a malformed matcher answers false without a fresh throw per call). The cap is a
+// backstop against degenerate dynamically-generated matchers: past it the memo resets -
+// worst case is exactly the old per-call compile, never unbounded growth or a wrong fire.
+const COMPILE_CACHE_MAX = 256;
+const compileCache = new Map(); // String(matcher) -> { re: RegExp|null, err: string|null }
+
+/**
+ * The memoised compile shared by matches() / matcherError(). Keyed on String(matcher) so a
+ * non-string matcher coerces exactly as the template literal always did.
+ * @param {*} matcher
+ * @returns {{ re: RegExp|null, err: string|null }}
+ */
+function compiled(matcher) {
+  const key = String(matcher);
+  let hit = compileCache.get(key);
+  if (hit) return hit;
+  try {
+    hit = { re: new RegExp(`^(?:${key})$`), err: null };
+  } catch (err) {
+    hit = { re: null, err: (err && err.message) || String(err) };
+  }
+  if (compileCache.size >= COMPILE_CACHE_MAX) compileCache.clear();
+  compileCache.set(key, hit);
+  return hit;
+}
+
+/**
+ * @param {string|undefined|null} matcher  the hook's matcher string.
+ * @param {string|undefined|null} toolName the tool the model requested, or
+ *        null/undefined for events without a tool.
+ * @returns {boolean} true if the hook should fire for this tool.
+ */
+function matches(matcher, toolName) {
+  // Wildcard / unset matcher -> always fire, regardless of tool.
+  if (matcher === undefined || matcher === null || matcher === '' || matcher === '*') {
+    return true;
+  }
+
+  // Tool-less events: there is nothing to match against, so the matcher is
+  // ignored and the hook always fires. This is checked AFTER the wildcard
+  // case so a "*" matcher is handled uniformly, and BEFORE we attempt a regex
+  // (which would otherwise need a string to test).
+  if (toolName === undefined || toolName === null) {
+    return true;
+  }
+
+  // Anything else is a regex, anchored as a full match against toolName.
+  // We wrap in ^(?:...)$ so alternations like "Bash|Write" mean "the whole tool
+  // name is one of these", not "contains one of these".
+  const c = compiled(matcher);
+  if (!c.re) {
+    // A malformed matcher must never throw out of the engine, and matches() cannot
+    // claim a fire it could not evaluate - so this answers false. That is NOT
+    // permission to proceed: callers that gate on the answer must distinguish
+    // "did not match" from "could not be read" via matcherError() (hook-engine
+    // denies the call; hook-loader.addEntry refuses to store the matcher at all).
+    return false;
+  }
+
+  return c.re.test(toolName);
+}
+
+/**
+ * Why does this matcher NOT compile? Returns null for a wildcard/unset matcher or one that
+ * compiles under the same ^(?:...)$ anchoring matches() applies; otherwise the compile error's
+ * message. This is the discriminator between "did not match" and "could not be read":
+ * authoring surfaces (hook-loader.addEntry, and through it the UI and tf_hook_add) use it to
+ * REFUSE a pattern that can never be evaluated, and hook-engine.fire treats a non-null answer
+ * on a tool-bearing event as an unreadable gate and denies the call (matcher-compile.test.js).
+ *
+ * @param {string|undefined|null} m the hook's matcher string.
+ * @returns {string|null} the compile problem, or null when the matcher is usable.
+ */
+function matcherError(m) {
+  if (m === undefined || m === null || m === '' || m === '*') return null;
+  return compiled(m).err;
+}
+
+module.exports = { matches, matcherError };