toolfunnel 0.4.0 → 0.6.0

package/src/core/logger.js

@@ -1,171 +1,171 @@
-'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 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 };

package/src/core/matcher.js

@@ -1,51 +1,51 @@
-'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? (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 };

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 };