toolfunnel 0.7.0 → 0.8.0

package/tools/scripts/tf-hook-add.js

@@ -1,151 +1,151 @@
-#!/usr/bin/env node
-'use strict';
-
-/**
- * tf-hook-add.js - management tool: add a hook entry to the hook manifest.
- *
- * A first-party "gateway-run" management function: it configures ToolFunnel's
- * OWN hook manifest (and, optionally, drops an inline hook script into the
- * scripts copy dir). Discovered via list_tools and executed via run_tool
- * through the PreToolUse gate - it is NOT a new MCP-protocol command.
- *
- * Contract with the register (`defaultRunScript`)
- * ----------------------------------------------------------
- *   - Structured args arrive as JSON in env TOOLFUNNEL_TOOL_ARGS ({} if absent).
- *   - Args: { id, event, matcher?, command, script?, timeout?, enabled?=true,
- *             description?, scriptText? }.
- *   - Prints EXACTLY ONE JSON object to stdout and exits 0 - ALWAYS exit 0, even
- *     on a logical error, which is reported as { ok:false, error }.
- *
- * Output (stdout), exactly one JSON object:
- *   success: { ok:true,  id, hook, scriptWritten }
- *   failure: { ok:false, error }
- *
- * Ordering note (verified against src/core/hook-loader.js)
- * -------------------------------------------------------
- *   HookLoader.writeScript(id, text) resolves the script path from the spec and
- *   THROWS for an unknown id (getSpec must find the row). Since addEntry rejects
- *   duplicate ids, this tool only ever creates NEW hooks - so the manifest row
- *   must be registered FIRST, then the inline script can be written. If the
- *   inline write fails, the just-added entry is rolled back so the add stays
- *   atomic (the intent behind a write-then-register ordering).
- *
- * Safety invariants:
- *   - Touches only ToolFunnel's own manifest + scripts dir (resolved from
- *     __dirname, never a caller-supplied absolute path).
- *   - NO network. NEVER throws for ordinary conditions - only JSON on stdout.
- */
-
-const path = require('node:path');
-// Shared HOME/engine resolution (see tf-env.js): config beside us, engine from the package.
-const { HOME, srcRequire } = require('./tf-env');
-const { loadManifest } = srcRequire('core/hook-loader');
-
-const ROOT = HOME;
-
-/** The hook manifest, relative to ROOT. */
-const MANIFEST = path.join(ROOT, 'hooks', 'hooks.manifest.json');
-
-/**
- * Parse the structured args handed in via env TOOLFUNNEL_TOOL_ARGS. Absent/empty
- * is treated as an empty object. Returns the parsed value or a parse-error
- * sentinel so the caller surfaces a clean { ok:false, error }.
- *
- * @returns {{ value: any } | { parseError: string }}
- */
-function parseStructuredArgs() {
-  const raw = process.env.TOOLFUNNEL_TOOL_ARGS;
-  if (raw === undefined || raw === null || raw === '') {
-    return { value: {} };
-  }
-  try {
-    return { value: JSON.parse(raw) };
-  } catch (_err) {
-    return { parseError: `TOOLFUNNEL_TOOL_ARGS was not valid JSON: ${String(raw)}` };
-  }
-}
-
-/**
- * Pure-ish core: validate args, register the hook, optionally write the inline
- * script. Never throws for ordinary conditions (addEntry's own validation errors
- * are caught in main).
- *
- * @param {any} args
- * @returns {object} the JSON-serialisable result
- */
-function run(args) {
-  if (!args || typeof args !== 'object' || Array.isArray(args)) {
-    return { ok: false, error: 'args must be an object { id, event, command, ... }' };
-  }
-
-  const { id, event, matcher, command, script, timeout, description, scriptText } = args;
-
-  // Clear up-front checks for fields addEntry does not (id/event/command are
-  // re-validated by addEntry). scriptText is checked before any mutation so a
-  // bad value never leaves a half-added entry behind.
-  if (typeof id !== 'string' || id.length === 0) {
-    return { ok: false, error: 'id must be a non-empty string' };
-  }
-  if (scriptText !== undefined && typeof scriptText !== 'string') {
-    return { ok: false, error: 'scriptText must be a string when provided' };
-  }
-
-  // enabled defaults to TRUE (opt-out) for this tool, unlike the loader's
-  // addEntry default of false - so it is passed explicitly.
-  const enabled = args.enabled === undefined ? true : args.enabled === true;
-
-  // Build the spec from only the supplied optional fields (keeps the manifest
-  // tidy); addEntry stores them verbatim.
-  const spec = { id, event, command, enabled };
-  if (matcher !== undefined) spec.matcher = matcher;
-  if (script !== undefined) spec.script = script;
-  if (timeout !== undefined) spec.timeout = timeout;
-  if (description !== undefined) spec.description = description;
-
-  const loader = loadManifest(MANIFEST);
-
-  // Register first (see Ordering note in the header). addEntry validates
-  // id/event/command and rejects duplicate ids by throwing - caught in main.
-  const stored = loader.addEntry(spec);
-
-  let scriptWritten = false;
-  if (typeof scriptText === 'string') {
-    try {
-      loader.writeScript(id, scriptText);
-      scriptWritten = true;
-    } catch (err) {
-      // Roll the entry back so a failed inline write leaves no orphan row.
-      try {
-        loader.removeEntry(id);
-      } catch (_) {
-        /* best-effort rollback */
-      }
-      return {
-        ok: false,
-        error: `script write failed (entry rolled back): ${(err && err.message) || String(err)}`,
-      };
-    }
-  }
-
-  return { ok: true, id, hook: stored, scriptWritten };
-}
-
-function main() {
-  const parsed = parseStructuredArgs();
-  let payload;
-  if (parsed.parseError) {
-    payload = { ok: false, error: parsed.parseError };
-  } else {
-    try {
-      payload = run(parsed.value);
-    } catch (err) {
-      // addEntry throws on validation / duplicate-id failures - report them as
-      // a logical error, still exit 0.
-      payload = { ok: false, error: (err && err.message) || String(err) };
-    }
-  }
-  process.stdout.write(JSON.stringify(payload) + '\n');
-  process.exit(0);
-}
-
-main();
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * tf-hook-add.js - management tool: add a hook entry to the hook manifest.
+ *
+ * A first-party "gateway-run" management function: it configures ToolFunnel's
+ * OWN hook manifest (and, optionally, drops an inline hook script into the
+ * scripts copy dir). Discovered via list_tools and executed via run_tool
+ * through the PreToolUse gate - it is NOT a new MCP-protocol command.
+ *
+ * Contract with the register (`defaultRunScript`)
+ * ----------------------------------------------------------
+ *   - Structured args arrive as JSON in env TOOLFUNNEL_TOOL_ARGS ({} if absent).
+ *   - Args: { id, event, matcher?, command, script?, timeout?, enabled?=true,
+ *             description?, scriptText? }.
+ *   - Prints EXACTLY ONE JSON object to stdout and exits 0 - ALWAYS exit 0, even
+ *     on a logical error, which is reported as { ok:false, error }.
+ *
+ * Output (stdout), exactly one JSON object:
+ *   success: { ok:true,  id, hook, scriptWritten }
+ *   failure: { ok:false, error }
+ *
+ * Ordering note (verified against src/core/hook-loader.js)
+ * -------------------------------------------------------
+ *   HookLoader.writeScript(id, text) resolves the script path from the spec and
+ *   THROWS for an unknown id (getSpec must find the row). Since addEntry rejects
+ *   duplicate ids, this tool only ever creates NEW hooks - so the manifest row
+ *   must be registered FIRST, then the inline script can be written. If the
+ *   inline write fails, the just-added entry is rolled back so the add stays
+ *   atomic (the intent behind a write-then-register ordering).
+ *
+ * Safety invariants:
+ *   - Touches only ToolFunnel's own manifest + scripts dir (resolved from
+ *     __dirname, never a caller-supplied absolute path).
+ *   - NO network. NEVER throws for ordinary conditions - only JSON on stdout.
+ */
+
+const path = require('node:path');
+// Shared HOME/engine resolution (see tf-env.js): config beside us, engine from the package.
+const { HOME, srcRequire } = require('./tf-env');
+const { loadManifest } = srcRequire('core/hook-loader');
+
+const ROOT = HOME;
+
+/** The hook manifest, relative to ROOT. */
+const MANIFEST = path.join(ROOT, 'hooks', 'hooks.manifest.json');
+
+/**
+ * Parse the structured args handed in via env TOOLFUNNEL_TOOL_ARGS. Absent/empty
+ * is treated as an empty object. Returns the parsed value or a parse-error
+ * sentinel so the caller surfaces a clean { ok:false, error }.
+ *
+ * @returns {{ value: any } | { parseError: string }}
+ */
+function parseStructuredArgs() {
+  const raw = process.env.TOOLFUNNEL_TOOL_ARGS;
+  if (raw === undefined || raw === null || raw === '') {
+    return { value: {} };
+  }
+  try {
+    return { value: JSON.parse(raw) };
+  } catch (_err) {
+    return { parseError: `TOOLFUNNEL_TOOL_ARGS was not valid JSON: ${String(raw)}` };
+  }
+}
+
+/**
+ * Pure-ish core: validate args, register the hook, optionally write the inline
+ * script. Never throws for ordinary conditions (addEntry's own validation errors
+ * are caught in main).
+ *
+ * @param {any} args
+ * @returns {object} the JSON-serialisable result
+ */
+function run(args) {
+  if (!args || typeof args !== 'object' || Array.isArray(args)) {
+    return { ok: false, error: 'args must be an object { id, event, command, ... }' };
+  }
+
+  const { id, event, matcher, command, script, timeout, description, scriptText } = args;
+
+  // Clear up-front checks for fields addEntry does not (id/event/command are
+  // re-validated by addEntry). scriptText is checked before any mutation so a
+  // bad value never leaves a half-added entry behind.
+  if (typeof id !== 'string' || id.length === 0) {
+    return { ok: false, error: 'id must be a non-empty string' };
+  }
+  if (scriptText !== undefined && typeof scriptText !== 'string') {
+    return { ok: false, error: 'scriptText must be a string when provided' };
+  }
+
+  // enabled defaults to TRUE (opt-out) for this tool, unlike the loader's
+  // addEntry default of false - so it is passed explicitly.
+  const enabled = args.enabled === undefined ? true : args.enabled === true;
+
+  // Build the spec from only the supplied optional fields (keeps the manifest
+  // tidy); addEntry stores them verbatim.
+  const spec = { id, event, command, enabled };
+  if (matcher !== undefined) spec.matcher = matcher;
+  if (script !== undefined) spec.script = script;
+  if (timeout !== undefined) spec.timeout = timeout;
+  if (description !== undefined) spec.description = description;
+
+  const loader = loadManifest(MANIFEST);
+
+  // Register first (see Ordering note in the header). addEntry validates
+  // id/event/command and rejects duplicate ids by throwing - caught in main.
+  const stored = loader.addEntry(spec);
+
+  let scriptWritten = false;
+  if (typeof scriptText === 'string') {
+    try {
+      loader.writeScript(id, scriptText);
+      scriptWritten = true;
+    } catch (err) {
+      // Roll the entry back so a failed inline write leaves no orphan row.
+      try {
+        loader.removeEntry(id);
+      } catch (_) {
+        /* best-effort rollback */
+      }
+      return {
+        ok: false,
+        error: `script write failed (entry rolled back): ${(err && err.message) || String(err)}`,
+      };
+    }
+  }
+
+  return { ok: true, id, hook: stored, scriptWritten };
+}
+
+function main() {
+  const parsed = parseStructuredArgs();
+  let payload;
+  if (parsed.parseError) {
+    payload = { ok: false, error: parsed.parseError };
+  } else {
+    try {
+      payload = run(parsed.value);
+    } catch (err) {
+      // addEntry throws on validation / duplicate-id failures - report them as
+      // a logical error, still exit 0.
+      payload = { ok: false, error: (err && err.message) || String(err) };
+    }
+  }
+  process.stdout.write(JSON.stringify(payload) + '\n');
+  process.exit(0);
+}
+
+main();

package/tools/scripts/tf-hook-set.js

@@ -1,120 +1,120 @@
-#!/usr/bin/env node
-'use strict';
-
-/**
- * tf-hook-set.js - management tool: enable, disable, or remove a hook entry.
- *
- * A first-party "gateway-run" management function: it configures ToolFunnel's
- * OWN hook manifest / enabled-state overlay. Discovered via list_tools and
- * executed via run_tool through the PreToolUse gate - it is NOT a new
- * MCP-protocol command.
- *
- * Contract with the register (`defaultRunScript`)
- * ----------------------------------------------------------
- *   - Structured args arrive as JSON in env TOOLFUNNEL_TOOL_ARGS ({} if absent).
- *   - Args: { id, action: "enable" | "disable" | "remove" }.
- *   - Prints EXACTLY ONE JSON object to stdout and exits 0 - ALWAYS exit 0, even
- *     on a logical error, which is reported as { ok:false, error }.
- *
- * Output (stdout), exactly one JSON object:
- *   enable/disable: { ok:true, id, action, enabled }
- *   remove:         { ok:true, id, action, removed }
- *   failure:        { ok:false, error }
- *
- * Mapping (verified against src/core/hook-loader.js):
- *   - enable  -> loader.setEnabled(id, true)   (persists the state overlay + manifest;
- *               returns false on a miss - no manifest row, no detected script - and
- *               writes NOTHING, so a miss is reported as { ok:false, error })
- *   - disable -> loader.setEnabled(id, false)  (same miss contract)
- *   - remove  -> loader.removeEntry(id)        (returns false if the id was absent;
- *               that is information, not a fault, so ok stays true)
- *
- * Safety invariants:
- *   - Touches only ToolFunnel's own manifest / state (resolved from __dirname).
- *   - NO network. NEVER throws for ordinary conditions - only JSON on stdout.
- */
-
-const path = require('node:path');
-// Shared HOME/engine resolution (see tf-env.js): config beside us, engine from the package.
-const { HOME, srcRequire } = require('./tf-env');
-const { loadManifest } = srcRequire('core/hook-loader');
-
-const ROOT = HOME;
-
-/** The hook manifest, relative to ROOT. */
-const MANIFEST = path.join(ROOT, 'hooks', 'hooks.manifest.json');
-
-/**
- * Parse the structured args handed in via env TOOLFUNNEL_TOOL_ARGS. Absent/empty
- * is treated as an empty object. Returns the parsed value or a parse-error
- * sentinel so the caller surfaces a clean { ok:false, error }.
- *
- * @returns {{ value: any } | { parseError: string }}
- */
-function parseStructuredArgs() {
-  const raw = process.env.TOOLFUNNEL_TOOL_ARGS;
-  if (raw === undefined || raw === null || raw === '') {
-    return { value: {} };
-  }
-  try {
-    return { value: JSON.parse(raw) };
-  } catch (_err) {
-    return { parseError: `TOOLFUNNEL_TOOL_ARGS was not valid JSON: ${String(raw)}` };
-  }
-}
-
-/**
- * Pure-ish core: validate args and apply the requested action. Never throws for
- * ordinary conditions (any loader throw is caught in main).
- *
- * @param {any} args
- * @returns {object} the JSON-serialisable result
- */
-function run(args) {
-  if (!args || typeof args !== 'object' || Array.isArray(args)) {
-    return { ok: false, error: 'args must be an object { id, action }' };
-  }
-
-  const { id, action } = args;
-  if (typeof id !== 'string' || id.length === 0) {
-    return { ok: false, error: 'id must be a non-empty string' };
-  }
-  if (action !== 'enable' && action !== 'disable' && action !== 'remove') {
-    return { ok: false, error: 'action must be one of "enable", "disable", "remove"' };
-  }
-
-  const loader = loadManifest(MANIFEST);
-
-  if (action === 'remove') {
-    const removed = loader.removeEntry(id);
-    return { ok: true, id, action, removed };
-  }
-
-  const desired = action === 'enable';
-  // setEnabled reports whether the toggle matched anything (a manifest row or a
-  // detected script). A miss writes nothing, so claiming ok:true here would report
-  // a gate toggled when nothing changed.
-  const applied = loader.setEnabled(id, desired);
-  if (!applied) {
-    return { ok: false, error: `no hook with id "${id}" - nothing was changed` };
-  }
-  return { ok: true, id, action, enabled: desired };
-}
-
-function main() {
-  const parsed = parseStructuredArgs();
-  let payload;
-  if (parsed.parseError) {
-    payload = { ok: false, error: parsed.parseError };
-  } else {
-    try {
-      payload = run(parsed.value);
-    } catch (err) {
-      payload = { ok: false, error: (err && err.message) || String(err) };
-    }
-  }
-  process.stdout.write(JSON.stringify(payload) + '\n');
-  process.exit(0);
-}
-
-main();
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * tf-hook-set.js - management tool: enable, disable, or remove a hook entry.
+ *
+ * A first-party "gateway-run" management function: it configures ToolFunnel's
+ * OWN hook manifest / enabled-state overlay. Discovered via list_tools and
+ * executed via run_tool through the PreToolUse gate - it is NOT a new
+ * MCP-protocol command.
+ *
+ * Contract with the register (`defaultRunScript`)
+ * ----------------------------------------------------------
+ *   - Structured args arrive as JSON in env TOOLFUNNEL_TOOL_ARGS ({} if absent).
+ *   - Args: { id, action: "enable" | "disable" | "remove" }.
+ *   - Prints EXACTLY ONE JSON object to stdout and exits 0 - ALWAYS exit 0, even
+ *     on a logical error, which is reported as { ok:false, error }.
+ *
+ * Output (stdout), exactly one JSON object:
+ *   enable/disable: { ok:true, id, action, enabled }
+ *   remove:         { ok:true, id, action, removed }
+ *   failure:        { ok:false, error }
+ *
+ * Mapping (verified against src/core/hook-loader.js):
+ *   - enable  -> loader.setEnabled(id, true)   (persists the state overlay + manifest;
+ *               returns false on a miss - no manifest row, no detected script - and
+ *               writes NOTHING, so a miss is reported as { ok:false, error })
+ *   - disable -> loader.setEnabled(id, false)  (same miss contract)
+ *   - remove  -> loader.removeEntry(id)        (returns false if the id was absent;
+ *               that is information, not a fault, so ok stays true)
+ *
+ * Safety invariants:
+ *   - Touches only ToolFunnel's own manifest / state (resolved from __dirname).
+ *   - NO network. NEVER throws for ordinary conditions - only JSON on stdout.
+ */
+
+const path = require('node:path');
+// Shared HOME/engine resolution (see tf-env.js): config beside us, engine from the package.
+const { HOME, srcRequire } = require('./tf-env');
+const { loadManifest } = srcRequire('core/hook-loader');
+
+const ROOT = HOME;
+
+/** The hook manifest, relative to ROOT. */
+const MANIFEST = path.join(ROOT, 'hooks', 'hooks.manifest.json');
+
+/**
+ * Parse the structured args handed in via env TOOLFUNNEL_TOOL_ARGS. Absent/empty
+ * is treated as an empty object. Returns the parsed value or a parse-error
+ * sentinel so the caller surfaces a clean { ok:false, error }.
+ *
+ * @returns {{ value: any } | { parseError: string }}
+ */
+function parseStructuredArgs() {
+  const raw = process.env.TOOLFUNNEL_TOOL_ARGS;
+  if (raw === undefined || raw === null || raw === '') {
+    return { value: {} };
+  }
+  try {
+    return { value: JSON.parse(raw) };
+  } catch (_err) {
+    return { parseError: `TOOLFUNNEL_TOOL_ARGS was not valid JSON: ${String(raw)}` };
+  }
+}
+
+/**
+ * Pure-ish core: validate args and apply the requested action. Never throws for
+ * ordinary conditions (any loader throw is caught in main).
+ *
+ * @param {any} args
+ * @returns {object} the JSON-serialisable result
+ */
+function run(args) {
+  if (!args || typeof args !== 'object' || Array.isArray(args)) {
+    return { ok: false, error: 'args must be an object { id, action }' };
+  }
+
+  const { id, action } = args;
+  if (typeof id !== 'string' || id.length === 0) {
+    return { ok: false, error: 'id must be a non-empty string' };
+  }
+  if (action !== 'enable' && action !== 'disable' && action !== 'remove') {
+    return { ok: false, error: 'action must be one of "enable", "disable", "remove"' };
+  }
+
+  const loader = loadManifest(MANIFEST);
+
+  if (action === 'remove') {
+    const removed = loader.removeEntry(id);
+    return { ok: true, id, action, removed };
+  }
+
+  const desired = action === 'enable';
+  // setEnabled reports whether the toggle matched anything (a manifest row or a
+  // detected script). A miss writes nothing, so claiming ok:true here would report
+  // a gate toggled when nothing changed.
+  const applied = loader.setEnabled(id, desired);
+  if (!applied) {
+    return { ok: false, error: `no hook with id "${id}" - nothing was changed` };
+  }
+  return { ok: true, id, action, enabled: desired };
+}
+
+function main() {
+  const parsed = parseStructuredArgs();
+  let payload;
+  if (parsed.parseError) {
+    payload = { ok: false, error: parsed.parseError };
+  } else {
+    try {
+      payload = run(parsed.value);
+    } catch (err) {
+      payload = { ok: false, error: (err && err.message) || String(err) };
+    }
+  }
+  process.stdout.write(JSON.stringify(payload) + '\n');
+  process.exit(0);
+}
+
+main();