toolfunnel 0.5.0 → 0.6.0

package/tools/scripts/text-stats.js

@@ -1,131 +1,131 @@
-#!/usr/bin/env node
-'use strict';
-
-/**
- * text-stats.js — a safe, dependency-free local text-statistics tool.
- *
- * Purpose
- * -------
- * Count characters, words, lines, and UTF-8 bytes for a string. A handy
- * Tool-Manager utility for sizing prompts, snippets, and payloads. Pure
- * string work — no network, no filesystem, no new deps.
- *
- * Contract with the register (the register's `defaultRunScript`)
- * ----------------------------------------------------------
- *   - Structured args arrive as JSON in env TOOLFUNNEL_TOOL_ARGS.
- *   - Args: { text: <string> }.
- *   - Prints a SINGLE JSON object to stdout and exits 0 — ALWAYS exit 0, even
- *     on bad input (reported as { ok:false, error }), never a thrown exception.
- *
- * Output (stdout), exactly one JSON object:
- *   success: { ok:true, chars, words, lines, bytes }
- *   failure: { ok:false, error }
- *
- * Counting conventions (documented so callers know exactly what they get):
- *   - chars : JS string length (UTF-16 code units — the same number `"".length`
- *             reports). Documented as such; for ASCII text it equals the visible
- *             character count.
- *   - words : maximal runs of non-whitespace separated by whitespace. The empty
- *             / all-whitespace string has 0 words.
- *   - lines : number of lines. The empty string is 0 lines; otherwise it is the
- *             count of newline-separated segments (a trailing newline does NOT
- *             add a phantom empty final line — `"a\n"` is 1 line, `"a\nb"` is 2).
- *   - bytes : UTF-8 byte length (Buffer.byteLength), the on-the-wire size.
- *
- * Safety invariants (mirror the isolation rule):
- *   - NO filesystem, NO network, NO process mutation. Pure CPU on the args.
- *   - NEVER throws for ordinary bad input — only well-shaped JSON on stdout.
- */
-
-/**
- * Parse the structured args handed in via env TOOLFUNNEL_TOOL_ARGS.
- * @returns {{ value: any } | { parseError: string }}
- */
-function parseStructuredArgs() {
-  const raw = process.env.TOOLFUNNEL_TOOL_ARGS;
-  if (raw === undefined || raw === null || raw === '') {
-    return { value: null };
-  }
-  try {
-    return { value: JSON.parse(raw) };
-  } catch (_err) {
-    return { parseError: `TOOLFUNNEL_TOOL_ARGS was not valid JSON: ${String(raw)}` };
-  }
-}
-
-/**
- * Count lines per the documented convention: 0 for the empty string, else the
- * number of newline-separated segments WITHOUT counting a phantom trailing
- * empty line. We normalise CRLF/CR to LF first so line counts match what a user
- * sees regardless of the platform that produced the text.
- *
- * @param {string} text
- * @returns {number}
- */
-function countLines(text) {
-  if (text.length === 0) return 0;
-  const normalised = text.replace(/\r\n?/g, '\n');
-  // Trailing newline should not add an empty line: trim a single trailing '\n'
-  // before splitting, then add 1 for the final (now-unterminated) line.
-  const trimmed = normalised.endsWith('\n') ? normalised.slice(0, -1) : normalised;
-  // Each '\n' in `trimmed` separates two lines → lines = (#newlines) + 1.
-  let newlines = 0;
-  for (let i = 0; i < trimmed.length; i += 1) {
-    if (trimmed.charCodeAt(i) === 10) newlines += 1;
-  }
-  return newlines + 1;
-}
-
-/**
- * Count words: maximal non-whitespace runs. Empty / whitespace-only → 0.
- *
- * @param {string} text
- * @returns {number}
- */
-function countWords(text) {
-  const trimmed = text.trim();
-  if (trimmed.length === 0) return 0;
-  // Split on any whitespace run; the trim above guarantees no empty edge tokens.
-  return trimmed.split(/\s+/).length;
-}
-
-/**
- * Pure core: given the parsed args, produce the result object. Never throws.
- *
- * @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 { text }' };
-  }
-  const { text } = args;
-  if (typeof text !== 'string') {
-    return { ok: false, error: 'text must be a string' };
-  }
-  return {
-    ok: true,
-    chars: text.length,
-    words: countWords(text),
-    lines: countLines(text),
-    bytes: Buffer.byteLength(text, 'utf8'),
-  };
-}
-
-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: `unexpected error: ${(err && err.message) || String(err)}` };
-    }
-  }
-  process.stdout.write(JSON.stringify(payload) + '\n');
-  process.exit(0);
-}
-
-main();
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * text-stats.js - a safe, dependency-free local text-statistics tool.
+ *
+ * Purpose
+ * -------
+ * Count characters, words, lines, and UTF-8 bytes for a string. A handy
+ * Tool-Manager utility for sizing prompts, snippets, and payloads. Pure
+ * string work - no network, no filesystem, no new deps.
+ *
+ * Contract with the register (the register's `defaultRunScript`)
+ * ----------------------------------------------------------
+ *   - Structured args arrive as JSON in env TOOLFUNNEL_TOOL_ARGS.
+ *   - Args: { text: <string> }.
+ *   - Prints a SINGLE JSON object to stdout and exits 0 - ALWAYS exit 0, even
+ *     on bad input (reported as { ok:false, error }), never a thrown exception.
+ *
+ * Output (stdout), exactly one JSON object:
+ *   success: { ok:true, chars, words, lines, bytes }
+ *   failure: { ok:false, error }
+ *
+ * Counting conventions (documented so callers know exactly what they get):
+ *   - chars : JS string length (UTF-16 code units - the same number `"".length`
+ *             reports). Documented as such; for ASCII text it equals the visible
+ *             character count.
+ *   - words : maximal runs of non-whitespace separated by whitespace. The empty
+ *             / all-whitespace string has 0 words.
+ *   - lines : number of lines. The empty string is 0 lines; otherwise it is the
+ *             count of newline-separated segments (a trailing newline does NOT
+ *             add a phantom empty final line - `"a\n"` is 1 line, `"a\nb"` is 2).
+ *   - bytes : UTF-8 byte length (Buffer.byteLength), the on-the-wire size.
+ *
+ * Safety invariants (mirror the isolation rule):
+ *   - NO filesystem, NO network, NO process mutation. Pure CPU on the args.
+ *   - NEVER throws for ordinary bad input - only well-shaped JSON on stdout.
+ */
+
+/**
+ * Parse the structured args handed in via env TOOLFUNNEL_TOOL_ARGS.
+ * @returns {{ value: any } | { parseError: string }}
+ */
+function parseStructuredArgs() {
+  const raw = process.env.TOOLFUNNEL_TOOL_ARGS;
+  if (raw === undefined || raw === null || raw === '') {
+    return { value: null };
+  }
+  try {
+    return { value: JSON.parse(raw) };
+  } catch (_err) {
+    return { parseError: `TOOLFUNNEL_TOOL_ARGS was not valid JSON: ${String(raw)}` };
+  }
+}
+
+/**
+ * Count lines per the documented convention: 0 for the empty string, else the
+ * number of newline-separated segments WITHOUT counting a phantom trailing
+ * empty line. We normalise CRLF/CR to LF first so line counts match what a user
+ * sees regardless of the platform that produced the text.
+ *
+ * @param {string} text
+ * @returns {number}
+ */
+function countLines(text) {
+  if (text.length === 0) return 0;
+  const normalised = text.replace(/\r\n?/g, '\n');
+  // Trailing newline should not add an empty line: trim a single trailing '\n'
+  // before splitting, then add 1 for the final (now-unterminated) line.
+  const trimmed = normalised.endsWith('\n') ? normalised.slice(0, -1) : normalised;
+  // Each '\n' in `trimmed` separates two lines -> lines = (#newlines) + 1.
+  let newlines = 0;
+  for (let i = 0; i < trimmed.length; i += 1) {
+    if (trimmed.charCodeAt(i) === 10) newlines += 1;
+  }
+  return newlines + 1;
+}
+
+/**
+ * Count words: maximal non-whitespace runs. Empty / whitespace-only -> 0.
+ *
+ * @param {string} text
+ * @returns {number}
+ */
+function countWords(text) {
+  const trimmed = text.trim();
+  if (trimmed.length === 0) return 0;
+  // Split on any whitespace run; the trim above guarantees no empty edge tokens.
+  return trimmed.split(/\s+/).length;
+}
+
+/**
+ * Pure core: given the parsed args, produce the result object. Never throws.
+ *
+ * @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 { text }' };
+  }
+  const { text } = args;
+  if (typeof text !== 'string') {
+    return { ok: false, error: 'text must be a string' };
+  }
+  return {
+    ok: true,
+    chars: text.length,
+    words: countWords(text),
+    lines: countLines(text),
+    bytes: Buffer.byteLength(text, 'utf8'),
+  };
+}
+
+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: `unexpected error: ${(err && err.message) || String(err)}` };
+    }
+  }
+  process.stdout.write(JSON.stringify(payload) + '\n');
+  process.exit(0);
+}
+
+main();

package/tools/scripts/tf-env.js

@@ -1,43 +1,43 @@
-'use strict';
-
-/**
- * tf-env.js — shared HOME/ENGINE resolution for the tf-* management scripts.
- *
- * A management script runs in one of two layouts:
- *   1. The git-clone original: it lives at <pkg>/tools/scripts/, and TWO dirs up is a root that
- *      holds BOTH the config (tools/ mcp/ hooks/) and the engine code (src/).
- *   2. A copy SEEDED into an external CONFIG HOME (TOOLFUNNEL_HOME / --config-dir — see
- *      src/core/config-home.js): the config sits beside it, but the engine code does NOT.
- *      The gateway that spawned it wrote the process-tree contract into the env:
- *      TOOLFUNNEL_HOME (the resolved absolute home) + TOOLFUNNEL_PKG (the package root).
- *
- * Resolution rules:
- *   - ENGINE: prefer the LOCAL __dirname-derived root whenever it actually contains the engine
- *     (layout 1) so a stale inherited TOOLFUNNEL_PKG can never shadow a real install; else the
- *     env; else the local root anyway (the require failure is then the clearest error).
- *   - HOME:   TOOLFUNNEL_HOME when set (the gateway always sets it), else the local root.
- *
- * Same-dir require ('./tf-env') keeps this working in BOTH layouts — the seeder copies the whole
- * scripts directory, so this file always travels with its callers. Node built-ins only.
- */
-
-const fs = require('node:fs');
-const path = require('node:path');
-
-const LOCAL_ROOT = path.resolve(__dirname, '..', '..');
-const HAS_LOCAL_ENGINE = fs.existsSync(path.join(LOCAL_ROOT, 'src', 'tools', 'registry.js'));
-
-/** The package root holding the engine code (src/…). */
-const PKG = HAS_LOCAL_ENGINE ? LOCAL_ROOT : (process.env.TOOLFUNNEL_PKG || LOCAL_ROOT);
-
-/** The config home holding tools/ mcp/ hooks/ (the mutable state this script edits). */
-const HOME = typeof process.env.TOOLFUNNEL_HOME === 'string' && process.env.TOOLFUNNEL_HOME.trim().length > 0
-  ? path.resolve(process.env.TOOLFUNNEL_HOME.trim())
-  : LOCAL_ROOT;
-
-/** Require an engine module by its src-relative path, e.g. srcRequire('tools/registry'). */
-function srcRequire(rel) {
-  return require(path.join(PKG, 'src', rel));
-}
-
-module.exports = { PKG, HOME, srcRequire };
+'use strict';
+
+/**
+ * tf-env.js - shared HOME/ENGINE resolution for the tf-* management scripts.
+ *
+ * A management script runs in one of two layouts:
+ *   1. The git-clone original: it lives at <pkg>/tools/scripts/, and TWO dirs up is a root that
+ *      holds BOTH the config (tools/ mcp/ hooks/) and the engine code (src/).
+ *   2. A copy SEEDED into an external CONFIG HOME (TOOLFUNNEL_HOME / --config-dir - see
+ *      src/core/config-home.js): the config sits beside it, but the engine code does NOT.
+ *      The gateway that spawned it wrote the process-tree contract into the env:
+ *      TOOLFUNNEL_HOME (the resolved absolute home) + TOOLFUNNEL_PKG (the package root).
+ *
+ * Resolution rules:
+ *   - ENGINE: prefer the LOCAL __dirname-derived root whenever it actually contains the engine
+ *     (layout 1) so a stale inherited TOOLFUNNEL_PKG can never shadow a real install; else the
+ *     env; else the local root anyway (the require failure is then the clearest error).
+ *   - HOME:   TOOLFUNNEL_HOME when set (the gateway always sets it), else the local root.
+ *
+ * Same-dir require ('./tf-env') keeps this working in BOTH layouts - the seeder copies the whole
+ * scripts directory, so this file always travels with its callers. Node built-ins only.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const LOCAL_ROOT = path.resolve(__dirname, '..', '..');
+const HAS_LOCAL_ENGINE = fs.existsSync(path.join(LOCAL_ROOT, 'src', 'tools', 'registry.js'));
+
+/** The package root holding the engine code (src/...). */
+const PKG = HAS_LOCAL_ENGINE ? LOCAL_ROOT : (process.env.TOOLFUNNEL_PKG || LOCAL_ROOT);
+
+/** The config home holding tools/ mcp/ hooks/ (the mutable state this script edits). */
+const HOME = typeof process.env.TOOLFUNNEL_HOME === 'string' && process.env.TOOLFUNNEL_HOME.trim().length > 0
+  ? path.resolve(process.env.TOOLFUNNEL_HOME.trim())
+  : LOCAL_ROOT;
+
+/** Require an engine module by its src-relative path, e.g. srcRequire('tools/registry'). */
+function srcRequire(rel) {
+  return require(path.join(PKG, 'src', rel));
+}
+
+module.exports = { PKG, HOME, srcRequire };

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();