toolfunnel 0.6.0 → 0.7.1

package/src/core/child-reaper.js

@@ -0,0 +1,61 @@
+'use strict';
+
+/**
+ * child-reaper.js - last-resort cleanup for spawned hook/tool children.
+ *
+ * The hook runner and both local executors spawn their children `detached` on POSIX so the
+ * process GROUP can be killed as a tree. setsid() has a consequence: the children leave the
+ * gateway's session, so a terminal Ctrl-C no longer reaches them, and a gateway that dies
+ * without executing its per-child kill path leaves them reparented to init running to their
+ * natural end - with their supervising timeout timers dead alongside the gateway.
+ *
+ * This module is the counterpart: every spawn site registers its child here and unregisters on
+ * settle; process exit / SIGINT / SIGTERM sweeps whatever is still tracked. Synchronous kills
+ * only - an 'exit' handler cannot await. Windows gets child.kill() (the shell only; taskkill is
+ * async and cannot run here) - best effort, matching the platform's weaker group semantics.
+ * A SIGKILLed gateway sweeps nothing; that limit is inherent to SIGKILL.
+ */
+
+const live = new Set();
+let installed = false;
+
+function sweep() {
+  for (const child of live) {
+    try {
+      if (child.pid != null && process.platform !== 'win32') {
+        try { process.kill(-child.pid, 'SIGKILL'); } catch (_eg) { child.kill('SIGKILL'); }
+      } else {
+        child.kill();
+      }
+    } catch (_e) { /* already gone */ }
+  }
+  live.clear();
+}
+
+function install() {
+  if (installed) return;
+  installed = true;
+  process.on('exit', sweep);
+  // On a signal, sweep and re-raise the default behaviour by exiting: only do so if nobody
+  // else handles the signal (respect an embedding host's own handlers).
+  for (const sig of ['SIGINT', 'SIGTERM']) {
+    process.on(sig, () => {
+      sweep();
+      if (process.listenerCount(sig) === 1) process.exit(sig === 'SIGINT' ? 130 : 143);
+    });
+  }
+}
+
+/** Register a spawned child for the last-resort sweep. Call untrack() when it settles. */
+function track(child) {
+  if (!child || typeof child.kill !== 'function') return;
+  install();
+  live.add(child);
+}
+
+/** Remove a settled child from the sweep set. Safe to call twice. */
+function untrack(child) {
+  live.delete(child);
+}
+
+module.exports = { track, untrack };

package/src/core/config-home.js

@@ -1,134 +1,134 @@
-'use strict';
-
-/**
- * config-home.js - WHERE the gateway's mutable config lives (board item 9, the packaging enabler).
- *
- * The problem this solves: an npm/npx-installed gateway keeps its config INSIDE the package
- * directory, so `npm update toolfunnel` replaces the package tree and EATS the user's tools,
- * hooks, curation, and identity. Config must be able to live in a home of its own:
- *
- *   resolution precedence:  --config-dir flag  >  TOOLFUNNEL_HOME env  >  the package root
- *
- * The default is UNCHANGED: a git clone keeps everything in the repo root exactly as before
- * (home === package root, no seeding, byte-identical behaviour). Pointing TOOLFUNNEL_HOME at an
- * empty directory makes the gateway SEED it on first use - the shipped register + its scripts, an
- * empty expose.json, the default hooks manifest - and every mutable path (tools/ mcp/ hooks/
- * auth/ logs/ toolfunnel.json packages/) anchors there from then on. Seeding never overwrites an
- * existing file, so a home survives package updates by construction.
- *
- * Two env vars are the process-tree contract (children inherit them via defaultRunScript's
- * spawn env):
- *   TOOLFUNNEL_HOME - the resolved ABSOLUTE config home (normalised at init so a relative value
- *                     can't skew between processes with different cwds).
- *   TOOLFUNNEL_PKG  - the package root of the gateway that spawned the tool, so a management
- *                     script SEEDED INTO an external home can still require the engine code
- *                     (src/...) it was copied away from. A script always prefers its own
- *                     __dirname-derived root when that root contains the engine (the git-clone
- *                     layout), so a stale inherited value can never shadow a real local install.
- *
- * Zero new dependencies. Node built-ins only.
- */
-
-const fs = require('node:fs');
-const path = require('node:path');
-
-/** The package root: this file lives at <pkg>/src/core/config-home.js. */
-const PKG_ROOT = path.resolve(__dirname, '..', '..');
-
-/**
- * Resolve the config home. Pure - no filesystem writes, no env mutation.
- * @param {{dir?: string}} [opts]  dir = an explicit --config-dir value (wins over the env)
- * @returns {string} absolute config-home path
- */
-function resolveConfigHome(opts) {
-  const o = opts || {};
-  const fromFlag = typeof o.dir === 'string' && o.dir.trim().length > 0 ? o.dir.trim() : null;
-  const fromEnv = typeof process.env.TOOLFUNNEL_HOME === 'string' && process.env.TOOLFUNNEL_HOME.trim().length > 0
-    ? process.env.TOOLFUNNEL_HOME.trim()
-    : null;
-  const chosen = fromFlag || fromEnv;
-  return chosen ? path.resolve(chosen) : PKG_ROOT;
-}
-
-/** Recursively copy a directory, skipping any destination file that already exists. */
-function copyTreeIfAbsent(srcDir, destDir, seeded) {
-  let entries;
-  try {
-    entries = fs.readdirSync(srcDir, { withFileTypes: true });
-  } catch (_e) {
-    return; // a missing source dir seeds nothing (defensive)
-  }
-  fs.mkdirSync(destDir, { recursive: true });
-  for (const e of entries) {
-    const from = path.join(srcDir, e.name);
-    const to = path.join(destDir, e.name);
-    if (e.isDirectory()) {
-      copyTreeIfAbsent(from, to, seeded);
-    } else if (e.isFile() && !fs.existsSync(to)) {
-      fs.copyFileSync(from, to);
-      seeded.push(to);
-    }
-  }
-}
-
-/**
- * Make `home` a working config home, seeding whatever is ABSENT from the shipped defaults.
- * Idempotent and never destructive: an existing file is NEVER overwritten (a home must survive
- * package updates - that is the whole point). home === package root -> a no-op (the git-clone
- * layout is already complete). Throws only if the home cannot be created at all.
- *
- * Deliberately NOT seeded: tools.state.json (absent = default visibility), auth/ (absent = auth
- * off), logs/ (absent = logging off), toolfunnel.json (absent = the default identity - an
- * npm-wrap ships its OWN copy inside its bundled home).
- *
- * @param {string} home  absolute config-home path (from resolveConfigHome)
- * @returns {{home: string, seeded: string[]}} the files seeded on THIS call (empty = was complete)
- */
-function ensureConfigHome(home) {
-  const seeded = [];
-  if (path.resolve(home) === PKG_ROOT) return { home: PKG_ROOT, seeded };
-  fs.mkdirSync(home, { recursive: true });
-
-  // The register + every shipped script (management tf_* + demo tools). The management scripts
-  // are config-tree citizens (the register's invoke paths point at them), so they travel.
-  copyTreeIfAbsent(path.join(PKG_ROOT, 'tools'), path.join(home, 'tools'), seeded);
-  // The state overlay is user-state, not a shipped default - drop a copied one if the package
-  // tree happened to carry local toggles (dev clone); a FRESH home starts with default visibility.
-  const strayState = path.join(home, 'tools', 'tools.state.json');
-  if (seeded.includes(strayState)) {
-    try { fs.unlinkSync(strayState); } catch (_e) { /* best-effort */ }
-    seeded.splice(seeded.indexOf(strayState), 1);
-  }
-
-  // The upstream/curation store and the hooks tree. NOTE the npm tarball ships
-  // mcp/expose.example.json but NOT mcp/expose.json (the live store is user-state), so after the
-  // tree copy the live store is synthesised EMPTY when absent. Never seed it from the example -
-  // the example is a POPULATED demo (it attaches the mock upstream), and a fresh home must start
-  // connected to nothing, exactly like a fresh clone.
-  copyTreeIfAbsent(path.join(PKG_ROOT, 'mcp'), path.join(home, 'mcp'), seeded);
-  const exposePath = path.join(home, 'mcp', 'expose.json');
-  if (!fs.existsSync(exposePath)) {
-    fs.mkdirSync(path.dirname(exposePath), { recursive: true });
-    fs.writeFileSync(exposePath, JSON.stringify({ version: 1, upstreams: [], expose: [] }, null, 2) + '\n');
-    seeded.push(exposePath);
-  }
-  copyTreeIfAbsent(path.join(PKG_ROOT, 'hooks'), path.join(home, 'hooks'), seeded);
-  return { home, seeded };
-}
-
-/**
- * The one-call init used by bin/toolfunnel.js for every mode: resolve, seed, and write the
- * process-tree contract back into the env (see the header) so every module loaded AFTER this -
- * and every child tool spawned later - reads the same resolved home.
- * @param {{dir?: string}} [opts]
- * @returns {{home: string, seeded: string[]}}
- */
-function initConfigHome(opts) {
-  const home = resolveConfigHome(opts);
-  const res = ensureConfigHome(home);
-  process.env.TOOLFUNNEL_HOME = res.home;
-  process.env.TOOLFUNNEL_PKG = PKG_ROOT;
-  return res;
-}
-
-module.exports = { PKG_ROOT, resolveConfigHome, ensureConfigHome, initConfigHome };
+'use strict';
+
+/**
+ * config-home.js - WHERE the gateway's mutable config lives (board item 9, the packaging enabler).
+ *
+ * The problem this solves: an npm/npx-installed gateway keeps its config INSIDE the package
+ * directory, so `npm update toolfunnel` replaces the package tree and EATS the user's tools,
+ * hooks, curation, and identity. Config must be able to live in a home of its own:
+ *
+ *   resolution precedence:  --config-dir flag  >  TOOLFUNNEL_HOME env  >  the package root
+ *
+ * The default is UNCHANGED: a git clone keeps everything in the repo root exactly as before
+ * (home === package root, no seeding, byte-identical behaviour). Pointing TOOLFUNNEL_HOME at an
+ * empty directory makes the gateway SEED it on first use - the shipped register + its scripts, an
+ * empty expose.json, the default hooks manifest - and every mutable path (tools/ mcp/ hooks/
+ * auth/ logs/ toolfunnel.json packages/) anchors there from then on. Seeding never overwrites an
+ * existing file, so a home survives package updates by construction.
+ *
+ * Two env vars are the process-tree contract (children inherit them via defaultRunScript's
+ * spawn env):
+ *   TOOLFUNNEL_HOME - the resolved ABSOLUTE config home (normalised at init so a relative value
+ *                     can't skew between processes with different cwds).
+ *   TOOLFUNNEL_PKG  - the package root of the gateway that spawned the tool, so a management
+ *                     script SEEDED INTO an external home can still require the engine code
+ *                     (src/...) it was copied away from. A script always prefers its own
+ *                     __dirname-derived root when that root contains the engine (the git-clone
+ *                     layout), so a stale inherited value can never shadow a real local install.
+ *
+ * Zero new dependencies. Node built-ins only.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+/** The package root: this file lives at <pkg>/src/core/config-home.js. */
+const PKG_ROOT = path.resolve(__dirname, '..', '..');
+
+/**
+ * Resolve the config home. Pure - no filesystem writes, no env mutation.
+ * @param {{dir?: string}} [opts]  dir = an explicit --config-dir value (wins over the env)
+ * @returns {string} absolute config-home path
+ */
+function resolveConfigHome(opts) {
+  const o = opts || {};
+  const fromFlag = typeof o.dir === 'string' && o.dir.trim().length > 0 ? o.dir.trim() : null;
+  const fromEnv = typeof process.env.TOOLFUNNEL_HOME === 'string' && process.env.TOOLFUNNEL_HOME.trim().length > 0
+    ? process.env.TOOLFUNNEL_HOME.trim()
+    : null;
+  const chosen = fromFlag || fromEnv;
+  return chosen ? path.resolve(chosen) : PKG_ROOT;
+}
+
+/** Recursively copy a directory, skipping any destination file that already exists. */
+function copyTreeIfAbsent(srcDir, destDir, seeded) {
+  let entries;
+  try {
+    entries = fs.readdirSync(srcDir, { withFileTypes: true });
+  } catch (_e) {
+    return; // a missing source dir seeds nothing (defensive)
+  }
+  fs.mkdirSync(destDir, { recursive: true });
+  for (const e of entries) {
+    const from = path.join(srcDir, e.name);
+    const to = path.join(destDir, e.name);
+    if (e.isDirectory()) {
+      copyTreeIfAbsent(from, to, seeded);
+    } else if (e.isFile() && !fs.existsSync(to)) {
+      fs.copyFileSync(from, to);
+      seeded.push(to);
+    }
+  }
+}
+
+/**
+ * Make `home` a working config home, seeding whatever is ABSENT from the shipped defaults.
+ * Idempotent and never destructive: an existing file is NEVER overwritten (a home must survive
+ * package updates - that is the whole point). home === package root -> a no-op (the git-clone
+ * layout is already complete). Throws only if the home cannot be created at all.
+ *
+ * Deliberately NOT seeded: tools.state.json (absent = default visibility), auth/ (absent = auth
+ * off), logs/ (absent = logging off), toolfunnel.json (absent = the default identity - an
+ * npm-wrap ships its OWN copy inside its bundled home).
+ *
+ * @param {string} home  absolute config-home path (from resolveConfigHome)
+ * @returns {{home: string, seeded: string[]}} the files seeded on THIS call (empty = was complete)
+ */
+function ensureConfigHome(home) {
+  const seeded = [];
+  if (path.resolve(home) === PKG_ROOT) return { home: PKG_ROOT, seeded };
+  fs.mkdirSync(home, { recursive: true });
+
+  // The register + every shipped script (management tf_* + demo tools). The management scripts
+  // are config-tree citizens (the register's invoke paths point at them), so they travel.
+  copyTreeIfAbsent(path.join(PKG_ROOT, 'tools'), path.join(home, 'tools'), seeded);
+  // The state overlay is user-state, not a shipped default - drop a copied one if the package
+  // tree happened to carry local toggles (dev clone); a FRESH home starts with default visibility.
+  const strayState = path.join(home, 'tools', 'tools.state.json');
+  if (seeded.includes(strayState)) {
+    try { fs.unlinkSync(strayState); } catch (_e) { /* best-effort */ }
+    seeded.splice(seeded.indexOf(strayState), 1);
+  }
+
+  // The upstream/curation store and the hooks tree. NOTE the npm tarball ships
+  // mcp/expose.example.json but NOT mcp/expose.json (the live store is user-state), so after the
+  // tree copy the live store is synthesised EMPTY when absent. Never seed it from the example -
+  // the example is a POPULATED demo (it attaches the mock upstream), and a fresh home must start
+  // connected to nothing, exactly like a fresh clone.
+  copyTreeIfAbsent(path.join(PKG_ROOT, 'mcp'), path.join(home, 'mcp'), seeded);
+  const exposePath = path.join(home, 'mcp', 'expose.json');
+  if (!fs.existsSync(exposePath)) {
+    fs.mkdirSync(path.dirname(exposePath), { recursive: true });
+    fs.writeFileSync(exposePath, JSON.stringify({ version: 1, upstreams: [], expose: [] }, null, 2) + '\n');
+    seeded.push(exposePath);
+  }
+  copyTreeIfAbsent(path.join(PKG_ROOT, 'hooks'), path.join(home, 'hooks'), seeded);
+  return { home, seeded };
+}
+
+/**
+ * The one-call init used by bin/toolfunnel.js for every mode: resolve, seed, and write the
+ * process-tree contract back into the env (see the header) so every module loaded AFTER this -
+ * and every child tool spawned later - reads the same resolved home.
+ * @param {{dir?: string}} [opts]
+ * @returns {{home: string, seeded: string[]}}
+ */
+function initConfigHome(opts) {
+  const home = resolveConfigHome(opts);
+  const res = ensureConfigHome(home);
+  process.env.TOOLFUNNEL_HOME = res.home;
+  process.env.TOOLFUNNEL_PKG = PKG_ROOT;
+  return res;
+}
+
+module.exports = { PKG_ROOT, resolveConfigHome, ensureConfigHome, initConfigHome };

package/src/core/events.js

@@ -1,105 +1,105 @@
-'use strict';
-
-/**
- * events.js - lifecycle event names + per-event stdin payload builder.
- *
- * This is the contract surface from HOOK_ENGINE.md §1 (the six events) and §2
- * (the exact stdin JSON shape). Field names are FROZEN by §2's table - they must
- * match Claude Code's documented hook input byte-for-byte so the real hook
- * scripts run unchanged. Do not rename or add fields.
- *
- * CommonJS only. Zero host imports (core/ must run headless under node --test).
- */
-
-/**
- * The six lifecycle events v3 supports (HOOK_ENGINE.md §1).
- * Values equal the `hook_event_name` written into the stdin payload.
- * Frozen so callers can rely on identity comparison and can't mutate the set.
- */
-const EVENTS = Object.freeze({
-  SessionStart: 'SessionStart',
-  UserPromptSubmit: 'UserPromptSubmit',
-  PreToolUse: 'PreToolUse',
-  PostToolUse: 'PostToolUse',
-  Stop: 'Stop',
-  PreCompact: 'PreCompact',
-});
-
-// Set of valid event names for fast membership checks / validation.
-const EVENT_NAMES = Object.freeze(Object.values(EVENTS));
-
-/**
- * Build the stdin JSON object the runner pipes to a hook command.
- *
- * Every event carries the four common fields (HOOK_ENGINE.md §2):
- *   session_id, transcript_path, cwd, hook_event_name
- * supplied by `ctx`. Each event then adds its own fields from `extra`:
- *
- *   SessionStart      -> source            : "startup" | "resume" | "compact"
- *   UserPromptSubmit  -> prompt            : "<user text>"
- *   PreToolUse        -> tool_name, tool_input
- *   PostToolUse       -> tool_name, tool_input, tool_response
- *   Stop              -> stop_hook_active   : true | false
- *   PreCompact        -> trigger ("manual"|"auto"), custom_instructions
- *
- * @param {string} event  one of EVENTS (the hook_event_name).
- * @param {object} ctx    common fields: { session_id, transcript_path, cwd }.
- * @param {object} [extra] event-specific fields (see table above).
- * @returns {object} the stdin payload, with frozen field names per §2.
- * @throws {Error} if `event` is not one of the six known events.
- */
-function buildPayload(event, ctx, extra) {
-  if (!EVENT_NAMES.includes(event)) {
-    throw new Error(`buildPayload: unknown event "${event}"`);
-  }
-
-  const c = ctx || {};
-  const e = extra || {};
-
-  // Common fields - present on EVERY event, in the order §2 lists them.
-  // hook_event_name is always the canonical event string (not whatever ctx held).
-  const payload = {
-    session_id: c.session_id,
-    transcript_path: c.transcript_path,
-    cwd: c.cwd,
-    hook_event_name: event,
-  };
-
-  // Event-specific additions. Each branch sets EXACTLY the fields §2 names -
-  // no more, no fewer - so the payload matches Claude Code's shape precisely.
-  switch (event) {
-    case EVENTS.SessionStart:
-      payload.source = e.source;
-      break;
-
-    case EVENTS.UserPromptSubmit:
-      payload.prompt = e.prompt;
-      break;
-
-    case EVENTS.PreToolUse:
-      payload.tool_name = e.tool_name;
-      payload.tool_input = e.tool_input;
-      break;
-
-    case EVENTS.PostToolUse:
-      payload.tool_name = e.tool_name;
-      payload.tool_input = e.tool_input;
-      payload.tool_response = e.tool_response;
-      break;
-
-    case EVENTS.Stop:
-      payload.stop_hook_active = e.stop_hook_active;
-      break;
-
-    case EVENTS.PreCompact:
-      payload.trigger = e.trigger;
-      payload.custom_instructions = e.custom_instructions;
-      break;
-
-    // No default: the membership check above already rejected unknown events.
-  }
-
-  return payload;
-}
-
-module.exports = { EVENTS, EVENT_NAMES, buildPayload };
+'use strict';
+
+/**
+ * events.js - lifecycle event names + per-event stdin payload builder.
+ *
+ * This is the hook contract surface: the six lifecycle events and
+ * (the exact stdin JSON shape). Field names are FROZEN - they are the hook wire contract and must
+ * match Claude Code's documented hook input byte-for-byte so the real hook
+ * scripts run unchanged. Do not rename or add fields.
+ *
+ * CommonJS only. Zero host imports (core/ must run headless under node --test).
+ */
+
+/**
+ * The six lifecycle events v3 supports.
+ * Values equal the `hook_event_name` written into the stdin payload.
+ * Frozen so callers can rely on identity comparison and can't mutate the set.
+ */
+const EVENTS = Object.freeze({
+  SessionStart: 'SessionStart',
+  UserPromptSubmit: 'UserPromptSubmit',
+  PreToolUse: 'PreToolUse',
+  PostToolUse: 'PostToolUse',
+  Stop: 'Stop',
+  PreCompact: 'PreCompact',
+});
+
+// Set of valid event names for fast membership checks / validation.
+const EVENT_NAMES = Object.freeze(Object.values(EVENTS));
+
+/**
+ * Build the stdin JSON object the runner pipes to a hook command.
+ *
+ * Every event carries the same four common fields:
+ *   session_id, transcript_path, cwd, hook_event_name
+ * supplied by `ctx`. Each event then adds its own fields from `extra`:
+ *
+ *   SessionStart      -> source            : "startup" | "resume" | "compact"
+ *   UserPromptSubmit  -> prompt            : "<user text>"
+ *   PreToolUse        -> tool_name, tool_input
+ *   PostToolUse       -> tool_name, tool_input, tool_response
+ *   Stop              -> stop_hook_active   : true | false
+ *   PreCompact        -> trigger ("manual"|"auto"), custom_instructions
+ *
+ * @param {string} event  one of EVENTS (the hook_event_name).
+ * @param {object} ctx    common fields: { session_id, transcript_path, cwd }.
+ * @param {object} [extra] event-specific fields (see table above).
+ * @returns {object} the stdin payload, with the contract's frozen field names.
+ * @throws {Error} if `event` is not one of the six known events.
+ */
+function buildPayload(event, ctx, extra) {
+  if (!EVENT_NAMES.includes(event)) {
+    throw new Error(`buildPayload: unknown event "${event}"`);
+  }
+
+  const c = ctx || {};
+  const e = extra || {};
+
+  // Common fields - present on EVERY event, in their contract order.
+  // hook_event_name is always the canonical event string (not whatever ctx held).
+  const payload = {
+    session_id: c.session_id,
+    transcript_path: c.transcript_path,
+    cwd: c.cwd,
+    hook_event_name: event,
+  };
+
+  // Event-specific additions. Each branch sets EXACTLY the fields the contract names -
+  // no more, no fewer - so the payload matches Claude Code's shape precisely.
+  switch (event) {
+    case EVENTS.SessionStart:
+      payload.source = e.source;
+      break;
+
+    case EVENTS.UserPromptSubmit:
+      payload.prompt = e.prompt;
+      break;
+
+    case EVENTS.PreToolUse:
+      payload.tool_name = e.tool_name;
+      payload.tool_input = e.tool_input;
+      break;
+
+    case EVENTS.PostToolUse:
+      payload.tool_name = e.tool_name;
+      payload.tool_input = e.tool_input;
+      payload.tool_response = e.tool_response;
+      break;
+
+    case EVENTS.Stop:
+      payload.stop_hook_active = e.stop_hook_active;
+      break;
+
+    case EVENTS.PreCompact:
+      payload.trigger = e.trigger;
+      payload.custom_instructions = e.custom_instructions;
+      break;
+
+    // No default: the membership check above already rejected unknown events.
+  }
+
+  return payload;
+}
+
+module.exports = { EVENTS, EVENT_NAMES, buildPayload };