toolfunnel 0.6.0 → 0.7.1

package/src/core/metrics.js

@@ -1,75 +1,75 @@
-'use strict';
-
-/**
- * metrics.js - in-memory, per-process tool-call counters (lightweight observability).
- *
- * A privileged gateway should be able to answer "what has run through me, and how often did it
- * fail?" without standing up a metrics stack. This is the zero-dependency MVP of that: process-
- * lifetime counters incremented at the single tools/call chokepoint and surfaced via the HTTP
- * `/health` endpoint and the admin UI. It is NOT persistent (counts reset when the host restarts)
- * and NOT a substitute for the JSONL audit log (src/core/logger.js, which records individual events
- * to disk when enabled) - the two are complementary: the log is the durable per-event record, this
- * is the cheap live aggregate.
- *
- * Design rules (same discipline as logger.js):
- *   - Zero dependencies. Plain objects + integers.
- *   - record() / snapshot() NEVER throw - instrumentation must never break a tool call.
- *   - In-memory only; no files, no timers, no network.
- *
- * CommonJS only.
- */
-
-const state = {
-  startedAt: new Date().toISOString(),
-  calls: 0,
-  errors: 0,
-  byTool: Object.create(null), // name -> { calls, errors }
-};
-
-/**
- * record - count one tools/call outcome. `ok:false` (an isError result - a tool failure OR a
- * PreToolUse denial, which both surface as an error envelope) increments the error counters.
- * @param {{ tool?:string, ok?:boolean }} ev
- */
-function record(ev) {
-  try {
-    const tool = ev && typeof ev.tool === 'string' && ev.tool.length > 0 ? ev.tool : 'unknown';
-    const ok = !(ev && ev.ok === false);
-    state.calls += 1;
-    if (!ok) state.errors += 1;
-    let t = state.byTool[tool];
-    if (!t) {
-      t = { calls: 0, errors: 0 };
-      state.byTool[tool] = t;
-    }
-    t.calls += 1;
-    if (!ok) t.errors += 1;
-  } catch (_e) {
-    /* instrumentation must never break the caller */
-  }
-}
-
-/**
- * snapshot - a fresh, mutation-safe copy of the counters for /health + the UI. NEVER throws.
- * @returns {{ startedAt:string, calls:number, errors:number, byTool:Object<string,{calls:number,errors:number}> }}
- */
-function snapshot() {
-  try {
-    const byTool = {};
-    for (const k of Object.keys(state.byTool)) {
-      byTool[k] = { calls: state.byTool[k].calls, errors: state.byTool[k].errors };
-    }
-    return { startedAt: state.startedAt, calls: state.calls, errors: state.errors, byTool };
-  } catch (_e) {
-    return { startedAt: state.startedAt, calls: 0, errors: 0, byTool: {} };
-  }
-}
-
-/** reset - zero the counters (tests). The startedAt stamp is left as the process start. */
-function reset() {
-  state.calls = 0;
-  state.errors = 0;
-  state.byTool = Object.create(null);
-}
-
-module.exports = { record, snapshot, reset };
+'use strict';
+
+/**
+ * metrics.js - in-memory, per-process tool-call counters (lightweight observability).
+ *
+ * A privileged gateway should be able to answer "what has run through me, and how often did it
+ * fail?" without standing up a metrics stack. This is the zero-dependency MVP of that: process-
+ * lifetime counters incremented at the single tools/call chokepoint and surfaced via the HTTP
+ * `/health` endpoint and the admin UI. It is NOT persistent (counts reset when the host restarts)
+ * and NOT a substitute for the JSONL audit log (src/core/logger.js, which records individual events
+ * to disk when enabled) - the two are complementary: the log is the durable per-event record, this
+ * is the cheap live aggregate.
+ *
+ * Design rules (same discipline as logger.js):
+ *   - Zero dependencies. Plain objects + integers.
+ *   - record() / snapshot() NEVER throw - instrumentation must never break a tool call.
+ *   - In-memory only; no files, no timers, no network.
+ *
+ * CommonJS only.
+ */
+
+const state = {
+  startedAt: new Date().toISOString(),
+  calls: 0,
+  errors: 0,
+  byTool: Object.create(null), // name -> { calls, errors }
+};
+
+/**
+ * record - count one tools/call outcome. `ok:false` (an isError result - a tool failure OR a
+ * PreToolUse denial, which both surface as an error envelope) increments the error counters.
+ * @param {{ tool?:string, ok?:boolean }} ev
+ */
+function record(ev) {
+  try {
+    const tool = ev && typeof ev.tool === 'string' && ev.tool.length > 0 ? ev.tool : 'unknown';
+    const ok = !(ev && ev.ok === false);
+    state.calls += 1;
+    if (!ok) state.errors += 1;
+    let t = state.byTool[tool];
+    if (!t) {
+      t = { calls: 0, errors: 0 };
+      state.byTool[tool] = t;
+    }
+    t.calls += 1;
+    if (!ok) t.errors += 1;
+  } catch (_e) {
+    /* instrumentation must never break the caller */
+  }
+}
+
+/**
+ * snapshot - a fresh, mutation-safe copy of the counters for /health + the UI. NEVER throws.
+ * @returns {{ startedAt:string, calls:number, errors:number, byTool:Object<string,{calls:number,errors:number}> }}
+ */
+function snapshot() {
+  try {
+    const byTool = {};
+    for (const k of Object.keys(state.byTool)) {
+      byTool[k] = { calls: state.byTool[k].calls, errors: state.byTool[k].errors };
+    }
+    return { startedAt: state.startedAt, calls: state.calls, errors: state.errors, byTool };
+  } catch (_e) {
+    return { startedAt: state.startedAt, calls: 0, errors: 0, byTool: {} };
+  }
+}
+
+/** reset - zero the counters (tests). The startedAt stamp is left as the process start. */
+function reset() {
+  state.calls = 0;
+  state.errors = 0;
+  state.byTool = Object.create(null);
+}
+
+module.exports = { record, snapshot, reset };

package/src/core/rename-migration.js

@@ -0,0 +1,163 @@
+'use strict';
+
+/**
+ * rename-migration.js - keep gates and per-tool state attached across a SURFACED-NAME change
+ * (0.7.0; the rename-safety.test.js invariants are the acceptance).
+ *
+ * A tool's SURFACED name is the string the PreToolUse gate matches and the tools.state.json
+ * key is written against. 0.6.0 let that name change (an expose `as` edit, an enabled flip, a
+ * local display-name edit) while the gate matcher and the state key silently kept the OLD
+ * string - a deny gate stopped firing and a disabled tool resurrected. The policy here,
+ * MATCHER-MIGRATE-ON-RENAME:
+ *
+ *   - A WILDCARD matcher ('', '*', unset) fires for every tool name - it already covers the
+ *     new name; untouched.
+ *   - An EXACT-LITERAL matcher - the `escapeRegex(oldName)` shape every ToolFunnel surface
+ *     (tf_* tools, the UI) writes - is REWRITTEN to `escapeRegex(newName)`.
+ *   - Any OTHER matcher that would fire for the old name (same anchored-regex semantics as
+ *     core/matcher.js, the gate's own matching) is one WE DID NOT AUTHOR and cannot safely
+ *     rewrite: the rename is REFUSED with the hook named. Update the hook first, then rename.
+ *   - tools.state.json: the old key's entry (enabled/hidden/hot) MOVES to the new key. A
+ *     collision (both keys present with different content) refuses - never clobber curation.
+ *
+ * Validation runs COMPLETELY before the first write, and the caller invokes this BEFORE
+ * persisting its own rename - a refusal leaves every file untouched.
+ *
+ * CommonJS only. Node built-ins + core/matcher only (core/ stays headless).
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { matches, matcherError } = require('./matcher');
+
+/** Regex-escape a literal so a matcher built from it FULL-matches the string verbatim.
+ *  (Same shape as ui/server.js escapeRegex - the shape ToolFunnel-authored matchers use.) */
+function escapeRegex(str) {
+  return String(str).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/** Copied exactly from registry.js::atomicWriteJson - crash leaves old file or new, never half. */
+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);
+}
+
+function readJsonIfPresent(p) {
+  try {
+    return JSON.parse(fs.readFileSync(p, 'utf8'));
+  } catch (_e) {
+    return null; // absent or unreadable -> nothing to migrate there
+  }
+}
+
+/**
+ * Migrate every gate matcher and state key from oldName to newName, or throw a refusal.
+ * @param {object} o
+ * @param {string} o.hooksPath  hooks.manifest.json path (may be absent on disk)
+ * @param {string} o.statePath  tools.state.json path (may be absent on disk)
+ * @param {string} o.oldName    the surfaced name being retired
+ * @param {string} o.newName    the surfaced name taking over
+ */
+function migrateSurfacedName(o) {
+  const { hooksPath, statePath, oldName, newName } = o || {};
+  if (typeof oldName !== 'string' || typeof newName !== 'string' || oldName === newName) return;
+
+  // ── Phase A: VALIDATE everything, write nothing ─────────────────────────────────────────────
+  const manifest = hooksPath ? readJsonIfPresent(hooksPath) : null;
+  const hooks = manifest && Array.isArray(manifest.hooks) ? manifest.hooks : [];
+  const literal = escapeRegex(oldName);
+  const rewrites = [];
+  for (const h of hooks) {
+    if (!h || typeof h !== 'object') continue;
+    const m = h.matcher;
+    if (m === undefined || m === null || m === '' || m === '*') continue; // wildcard covers both names
+    if (m === literal || m === oldName) {
+      // The exact-literal shape ToolFunnel authors (escaped, or the bare name when it contains
+      // no regex specials - the two are identical then, but hand-written manifests may carry
+      // the bare form for a name that DOES contain specials, e.g. "my.tool").
+      rewrites.push(h);
+      continue;
+    }
+    // A matcher that does not COMPILE cannot be evaluated against oldName at all - matches()
+    // would answer false, silently carrying the rename past a hook this code cannot read.
+    // Same policy as a matching non-literal: refuse, name the hook, touch nothing.
+    // (addEntry refuses these at authoring, so only a hand-edited manifest reaches here.)
+    const compileProblem = matcherError(m);
+    if (compileProblem) {
+      throw new Error(
+        `rename refused: hook "${h.id || '(unnamed)'}" matcher ${JSON.stringify(m)} does not ` +
+        `compile (${compileProblem}) - it cannot be checked against "${oldName}", so the rename ` +
+        'cannot proceed safely. Fix the hook first, then rename'
+      );
+    }
+    if (matches(m, oldName)) {
+      throw new Error(
+        `rename refused: hook "${h.id || '(unnamed)'}" matcher "${m}" matches "${oldName}" but is ` +
+        'not an exact-literal matcher ToolFunnel can rewrite - update the hook to cover ' +
+        `"${newName}" first, then rename`
+      );
+    }
+  }
+
+  const state = statePath ? readJsonIfPresent(statePath) : null;
+  const hasOldState = !!(state && Object.prototype.hasOwnProperty.call(state, oldName));
+  if (hasOldState && Object.prototype.hasOwnProperty.call(state, newName) &&
+      JSON.stringify(state[oldName]) !== JSON.stringify(state[newName])) {
+    throw new Error(
+      `rename refused: tools.state.json already has an entry for "${newName}" that differs from ` +
+      `"${oldName}"'s - resolve the curation collision first, then rename`
+    );
+  }
+
+  // ── Phase B: WRITE (all validation passed) ──────────────────────────────────────────────────
+  if (rewrites.length) {
+    for (const h of rewrites) h.matcher = escapeRegex(newName);
+    atomicWriteJson(hooksPath, manifest);
+  }
+  if (hasOldState) {
+    state[newName] = state[oldName];
+    delete state[oldName];
+    atomicWriteJson(statePath, state);
+  }
+}
+
+/**
+ * Convenience for the two stores: derive the sibling config paths from the CONFIG-HOME layout
+ * (<root>/mcp/expose.json, <root>/tools/tools.register.json, <root>/tools/tools.state.json,
+ * <root>/hooks/hooks.manifest.json) and migrate. `storeFilePath` is the calling store's own
+ * file; its grandparent is the home root.
+ *
+ * `opts.migrateState` (default TRUE) selects whether the tools.state.json key moves with the
+ * name. The gate matcher ALWAYS moves - it genuinely fires on the surfaced name for both stores.
+ * The state key does NOT, because the overlay has TWO key namespaces:
+ *   - UPSTREAM tools are keyed by their SURFACED name (server.js:638,733,924; ui:1273) - an
+ *     expose `as` edit changes that key, so ExposeStore migrates state (the default).
+ *   - LOCAL register tools are keyed by their register ID (server.js:290,337,814-815,952;
+ *     ui:326-328; tf-tool-set.js) - an id is immutable and a display-name edit does not touch
+ *     it, so Registry passes migrateState:false. Moving the key there would ORPHAN the entry:
+ *     the readers still look up the id, find nothing, and fall back to the defaults - which are
+ *     enabled - so a tool deliberately switched off would come back on (rename-safety S5).
+ *     Bites whenever name === id, i.e. every tf_* management tool.
+ */
+function migrateForStoreFile(storeFilePath, oldName, newName, opts) {
+  const root = path.dirname(path.dirname(path.resolve(storeFilePath)));
+  const migrateState = !(opts && opts.migrateState === false);
+  migrateSurfacedName({
+    hooksPath: path.join(root, 'hooks', 'hooks.manifest.json'),
+    statePath: migrateState ? path.join(root, 'tools', 'tools.state.json') : null,
+    oldName,
+    newName,
+  });
+}
+
+module.exports = { migrateSurfacedName, migrateForStoreFile, escapeRegex };

package/src/core/requires.js

@@ -1,138 +1,138 @@
-'use strict';
-
-/**
- * requires.js - runtime-requirement preflight (the packaging story's honesty layer).
- *
- * A shipped pack's tools may need runtimes the gateway itself does not (python for a PDF tool,
- * git for a repo tool). The pack DECLARES them in its toolfunnel.json - the identity file that
- * already travels with every config home - and the gateway probes them ONCE at startup:
- *
- *   "requires": [
- *     { "command": "python", "min": "3.10", "why": "the pdf-extract tools" },
- *     { "command": "git" }
- *   ]
- *
- * Probes are ADVISORY, never fatal: a missing runtime breaks only the tools that need it, so the
- * gateway starts and the operator gets a clear stderr line naming what is missing, the version
- * found vs needed, and the declared "why". Fields per entry (only `command` is required):
- *   command     the executable to probe (e.g. "python", "node", "git")
- *   versionArg  the flag that prints a version (default "--version")
- *   min         minimum version, dotted numerics (e.g. "3.10" / "18" / "3.10.2")
- *   why         shown in the warning so the operator knows which tools care
- *
- * Zero new dependencies: child_process probes + a hand-rolled dotted-numeric compare. NO semver
- * library - by the packaging hard constraint, and dotted numerics cover real runtime versions.
- */
-
-const fs = require('node:fs');
-const path = require('node:path');
-const { spawnSync } = require('node:child_process');
-
-/** Parse the FIRST dotted-numeric version out of a probe's output ("Python 3.12.1" -> [3,12,1]).
- *  Returns null when no version-shaped token is present. */
-function parseVersion(text) {
-  const m = /(\d+)\.(\d+)(?:\.(\d+))?/.exec(String(text || ''));
-  if (!m) {
-    const single = /\b(\d+)\b/.exec(String(text || ''));
-    return single ? [Number(single[1]), 0, 0] : null;
-  }
-  return [Number(m[1]), Number(m[2]), Number(m[3] || 0)];
-}
-
-/** Hand-rolled dotted-numeric compare: -1 | 0 | 1 for a<b | a==b | a>b. */
-function compareVersions(a, b) {
-  for (let i = 0; i < 3; i += 1) {
-    const x = a[i] || 0;
-    const y = b[i] || 0;
-    if (x < y) return -1;
-    if (x > y) return 1;
-  }
-  return 0;
-}
-
-/**
- * Probe one command for its version string. On Windows a PATHEXT shim (a .cmd like npx) cannot be
- * spawned shell:false (ENOENT/EINVAL - the CVE-2024-27980 mitigation), so a failed direct probe is
- * retried through cmd.exe, mirroring mcp-client's winLaunch.
- * @param {string} command
- * @param {string} versionArg
- * @returns {{found: boolean, version: (number[]|null), raw: string}}
- */
-function probe(command, versionArg) {
-  const runOnce = (cmd, args) => spawnSync(cmd, args, { encoding: 'utf8', windowsHide: true, timeout: 5000 });
-  let res = runOnce(command, [versionArg]);
-  if (res.error && process.platform === 'win32') {
-    const comspec = process.env.ComSpec || 'cmd.exe';
-    res = runOnce(comspec, ['/c', command, versionArg]);
-  }
-  if (res.error || res.status == null) return { found: false, version: null, raw: '' };
-  const raw = `${res.stdout || ''} ${res.stderr || ''}`.trim();
-  const version = parseVersion(raw);
-  // "Spawned" is not "exists": the cmd.exe fallback launches fine for a NONEXISTENT command and
-  // exits non-zero ("is not recognized..."). Existence = a clean exit OR a version-shaped answer.
-  const found = res.status === 0 || version !== null;
-  return { found, version: found ? version : null, raw };
-}
-
-/**
- * Check the `requires` declared in `<home>/toolfunnel.json`. Returns the problem list - the
- * caller decides how to surface it (the gateway logs each to stderr and starts anyway). NEVER
- * throws; a malformed requires entry is itself reported as a problem rather than crashing.
- * @param {string} home  the resolved config home
- * @returns {Array<{command:string, problem:string}>}
- */
-function checkRequires(home) {
-  let cfg;
-  try {
-    cfg = JSON.parse(fs.readFileSync(path.join(home, 'toolfunnel.json'), 'utf8'));
-  } catch (_e) {
-    return []; // absent/bad identity file -> nothing declared
-  }
-  const list = cfg && Array.isArray(cfg.requires) ? cfg.requires : [];
-  const problems = [];
-  for (const entry of list) {
-    if (!entry || typeof entry !== 'object' || typeof entry.command !== 'string' || entry.command.trim() === '') {
-      problems.push({ command: String(entry && entry.command), problem: 'malformed requires entry (needs a "command" string)' });
-      continue;
-    }
-    const command = entry.command.trim();
-    // A requires command is a bare PROGRAM NAME, never a shell string. This is load-bearing on
-    // Windows: the cmd.exe shim fallback below hands the token to cmd, where an unquoted
-    // metacharacter ("x&evil") would CHAIN commands - a probe must never be able to run anything
-    // beyond `<program> <versionArg>`. Reject anything shell-shaped up front (also catches paths:
-    // declare tools by PATH name, which is the only portable claim a pack can make anyway).
-    if (!/^[A-Za-z0-9][A-Za-z0-9._+-]*$/.test(command)) {
-      problems.push({ command, problem: `requires.command "${command}" is not a bare program name (no paths, spaces, or shell characters)` });
-      continue;
-    }
-    const why = typeof entry.why === 'string' && entry.why ? ` (needed for: ${entry.why})` : '';
-    const versionArg = typeof entry.versionArg === 'string' && /^--?[A-Za-z][A-Za-z-]*$/.test(entry.versionArg)
-      ? entry.versionArg
-      : '--version'; // same rule: a version FLAG, never a shell fragment
-    const p = probe(command, versionArg);
-    if (!p.found) {
-      problems.push({ command, problem: `"${command}" was not found on PATH${why}` });
-      continue;
-    }
-    if (typeof entry.min === 'string' && entry.min.trim() !== '') {
-      const min = parseVersion(entry.min);
-      if (!min) {
-        problems.push({ command, problem: `requires.min "${entry.min}" is not a dotted numeric version` });
-        continue;
-      }
-      if (!p.version) {
-        problems.push({ command, problem: `"${command}" answered but printed no recognisable version (wanted >= ${entry.min})${why}` });
-        continue;
-      }
-      if (compareVersions(p.version, min) < 0) {
-        problems.push({
-          command,
-          problem: `"${command}" is ${p.version.join('.')} but this setup declares >= ${entry.min}${why}`,
-        });
-      }
-    }
-  }
-  return problems;
-}
-
-module.exports = { checkRequires, parseVersion, compareVersions, probe };
+'use strict';
+
+/**
+ * requires.js - runtime-requirement preflight (the packaging story's honesty layer).
+ *
+ * A shipped pack's tools may need runtimes the gateway itself does not (python for a PDF tool,
+ * git for a repo tool). The pack DECLARES them in its toolfunnel.json - the identity file that
+ * already travels with every config home - and the gateway probes them ONCE at startup:
+ *
+ *   "requires": [
+ *     { "command": "python", "min": "3.10", "why": "the pdf-extract tools" },
+ *     { "command": "git" }
+ *   ]
+ *
+ * Probes are ADVISORY, never fatal: a missing runtime breaks only the tools that need it, so the
+ * gateway starts and the operator gets a clear stderr line naming what is missing, the version
+ * found vs needed, and the declared "why". Fields per entry (only `command` is required):
+ *   command     the executable to probe (e.g. "python", "node", "git")
+ *   versionArg  the flag that prints a version (default "--version")
+ *   min         minimum version, dotted numerics (e.g. "3.10" / "18" / "3.10.2")
+ *   why         shown in the warning so the operator knows which tools care
+ *
+ * Zero new dependencies: child_process probes + a hand-rolled dotted-numeric compare. NO semver
+ * library - by the packaging hard constraint, and dotted numerics cover real runtime versions.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+/** Parse the FIRST dotted-numeric version out of a probe's output ("Python 3.12.1" -> [3,12,1]).
+ *  Returns null when no version-shaped token is present. */
+function parseVersion(text) {
+  const m = /(\d+)\.(\d+)(?:\.(\d+))?/.exec(String(text || ''));
+  if (!m) {
+    const single = /\b(\d+)\b/.exec(String(text || ''));
+    return single ? [Number(single[1]), 0, 0] : null;
+  }
+  return [Number(m[1]), Number(m[2]), Number(m[3] || 0)];
+}
+
+/** Hand-rolled dotted-numeric compare: -1 | 0 | 1 for a<b | a==b | a>b. */
+function compareVersions(a, b) {
+  for (let i = 0; i < 3; i += 1) {
+    const x = a[i] || 0;
+    const y = b[i] || 0;
+    if (x < y) return -1;
+    if (x > y) return 1;
+  }
+  return 0;
+}
+
+/**
+ * Probe one command for its version string. On Windows a PATHEXT shim (a .cmd like npx) cannot be
+ * spawned shell:false (ENOENT/EINVAL - the CVE-2024-27980 mitigation), so a failed direct probe is
+ * retried through cmd.exe, mirroring mcp-client's winLaunch.
+ * @param {string} command
+ * @param {string} versionArg
+ * @returns {{found: boolean, version: (number[]|null), raw: string}}
+ */
+function probe(command, versionArg) {
+  const runOnce = (cmd, args) => spawnSync(cmd, args, { encoding: 'utf8', windowsHide: true, timeout: 5000 });
+  let res = runOnce(command, [versionArg]);
+  if (res.error && process.platform === 'win32') {
+    const comspec = process.env.ComSpec || 'cmd.exe';
+    res = runOnce(comspec, ['/c', command, versionArg]);
+  }
+  if (res.error || res.status == null) return { found: false, version: null, raw: '' };
+  const raw = `${res.stdout || ''} ${res.stderr || ''}`.trim();
+  const version = parseVersion(raw);
+  // "Spawned" is not "exists": the cmd.exe fallback launches fine for a NONEXISTENT command and
+  // exits non-zero ("is not recognized..."). Existence = a clean exit OR a version-shaped answer.
+  const found = res.status === 0 || version !== null;
+  return { found, version: found ? version : null, raw };
+}
+
+/**
+ * Check the `requires` declared in `<home>/toolfunnel.json`. Returns the problem list - the
+ * caller decides how to surface it (the gateway logs each to stderr and starts anyway). NEVER
+ * throws; a malformed requires entry is itself reported as a problem rather than crashing.
+ * @param {string} home  the resolved config home
+ * @returns {Array<{command:string, problem:string}>}
+ */
+function checkRequires(home) {
+  let cfg;
+  try {
+    cfg = JSON.parse(fs.readFileSync(path.join(home, 'toolfunnel.json'), 'utf8'));
+  } catch (_e) {
+    return []; // absent/bad identity file -> nothing declared
+  }
+  const list = cfg && Array.isArray(cfg.requires) ? cfg.requires : [];
+  const problems = [];
+  for (const entry of list) {
+    if (!entry || typeof entry !== 'object' || typeof entry.command !== 'string' || entry.command.trim() === '') {
+      problems.push({ command: String(entry && entry.command), problem: 'malformed requires entry (needs a "command" string)' });
+      continue;
+    }
+    const command = entry.command.trim();
+    // A requires command is a bare PROGRAM NAME, never a shell string. This is load-bearing on
+    // Windows: the cmd.exe shim fallback below hands the token to cmd, where an unquoted
+    // metacharacter ("x&denied") would CHAIN commands - a probe must never be able to run anything
+    // beyond `<program> <versionArg>`. Reject anything shell-shaped up front (also catches paths:
+    // declare tools by PATH name, which is the only portable claim a pack can make anyway).
+    if (!/^[A-Za-z0-9][A-Za-z0-9._+-]*$/.test(command)) {
+      problems.push({ command, problem: `requires.command "${command}" is not a bare program name (no paths, spaces, or shell characters)` });
+      continue;
+    }
+    const why = typeof entry.why === 'string' && entry.why ? ` (needed for: ${entry.why})` : '';
+    const versionArg = typeof entry.versionArg === 'string' && /^--?[A-Za-z][A-Za-z-]*$/.test(entry.versionArg)
+      ? entry.versionArg
+      : '--version'; // same rule: a version FLAG, never a shell fragment
+    const p = probe(command, versionArg);
+    if (!p.found) {
+      problems.push({ command, problem: `"${command}" was not found on PATH${why}` });
+      continue;
+    }
+    if (typeof entry.min === 'string' && entry.min.trim() !== '') {
+      const min = parseVersion(entry.min);
+      if (!min) {
+        problems.push({ command, problem: `requires.min "${entry.min}" is not a dotted numeric version` });
+        continue;
+      }
+      if (!p.version) {
+        problems.push({ command, problem: `"${command}" answered but printed no recognisable version (wanted >= ${entry.min})${why}` });
+        continue;
+      }
+      if (compareVersions(p.version, min) < 0) {
+        problems.push({
+          command,
+          problem: `"${command}" is ${p.version.join('.')} but this setup declares >= ${entry.min}${why}`,
+        });
+      }
+    }
+  }
+  return problems;
+}
+
+module.exports = { checkRequires, parseVersion, compareVersions, probe };