toolfunnel 0.3.0

package/tools/scripts/base64.js

@@ -0,0 +1,139 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * base64-tool.js — a safe, dependency-free local Base64 codec tool.
+ *
+ * Purpose
+ * -------
+ * Encode UTF-8 text to standard Base64, or decode Base64 back to UTF-8 text.
+ * A genuinely useful utility for the Tool Manager: inspecting / producing
+ * Base64 blobs is a frequent chore and this gives a gated, no-side-effect way
+ * to do it. Uses ONLY Node built-ins (Buffer) — no network, no filesystem.
+ *
+ * Contract with the register (the register's `defaultRunScript`)
+ * ----------------------------------------------------------
+ *   - Structured args arrive as JSON in env TOOLFUNNEL_TOOL_ARGS.
+ *   - Args: { op: "encode" | "decode", text: <string> }.
+ *   - Prints a SINGLE JSON object to stdout and exits 0 — ALWAYS exit 0, even
+ *     on bad input. Bad input is reported as { ok:false, error } rather than a
+ *     thrown exception, because the gated run-path treats exit-0-with-parseable
+ *     stdout as a completed run.
+ *
+ * Output (stdout), exactly one JSON object:
+ *   success: { ok:true,  op, result }
+ *   failure: { ok:false, error }
+ *
+ * Notes on tolerance
+ * ------------------
+ *   - encode: any string is encodable. A non-string `text` is rejected.
+ *   - decode: Node's Buffer.from(x,'base64') is itself lenient (it skips
+ *     non-base64 chars), so to give callers a MEANINGFUL "bad base64" signal we
+ *     validate the input shape first and round-trip-check the result. If the
+ *     re-encoded form does not match a normalised version of the input, we
+ *     report ok:false rather than silently returning garbage.
+ *
+ * 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 the parsed value, or a sentinel describing a parse failure so the
+ * caller can surface a clean { ok:false, error } instead of crashing.
+ *
+ * @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)}` };
+  }
+}
+
+/**
+ * Decode tolerantly: validate that the input looks like Base64, decode it, and
+ * round-trip-check so genuinely malformed input is reported rather than mangled.
+ *
+ * @param {string} text the candidate Base64 string
+ * @returns {{ ok:true, result:string } | { ok:false, error:string }}
+ */
+function decodeTolerant(text) {
+  // Strip surrounding whitespace; Base64 may legitimately contain internal
+  // newlines (MIME wrapping), so remove all ASCII whitespace before validating.
+  const stripped = String(text).replace(/\s+/g, '');
+  if (stripped.length === 0) {
+    // Empty input decodes to empty string — a valid, unambiguous result.
+    return { ok: true, result: '' };
+  }
+  // Standard Base64 alphabet (with optional '=' padding). Reject anything else
+  // up front so the caller gets a clear "bad base64" rather than silent garbage.
+  if (!/^[A-Za-z0-9+/]+={0,2}$/.test(stripped)) {
+    return { ok: false, error: 'input is not valid Base64' };
+  }
+  // Length of a Base64 string (sans padding-trimming nuance) must be a multiple
+  // of 4 once padding is included; reject obviously truncated input.
+  if (stripped.length % 4 !== 0) {
+    return { ok: false, error: 'input is not valid Base64 (bad length)' };
+  }
+  const buf = Buffer.from(stripped, 'base64');
+  // Round-trip: re-encode and compare to the normalised input. Buffer's decoder
+  // is lenient, so this catches inputs that "decode" but were never valid.
+  const reencoded = buf.toString('base64');
+  if (reencoded !== stripped) {
+    return { ok: false, error: 'input is not valid Base64' };
+  }
+  return { ok: true, result: buf.toString('utf8') };
+}
+
+/**
+ * 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 { op, text }' };
+  }
+  const { op, text } = args;
+  if (op !== 'encode' && op !== 'decode') {
+    return { ok: false, error: 'op must be "encode" or "decode"' };
+  }
+  if (typeof text !== 'string') {
+    return { ok: false, error: 'text must be a string' };
+  }
+  if (op === 'encode') {
+    return { ok: true, op: 'encode', result: Buffer.from(text, 'utf8').toString('base64') };
+  }
+  // op === 'decode'
+  const decoded = decodeTolerant(text);
+  if (!decoded.ok) return { ok: false, error: decoded.error };
+  return { ok: true, op: 'decode', result: decoded.result };
+}
+
+function main() {
+  const parsed = parseStructuredArgs();
+  let payload;
+  if (parsed.parseError) {
+    payload = { ok: false, error: parsed.parseError };
+  } else {
+    try {
+      payload = run(parsed.value);
+    } catch (err) {
+      // Defensive: run() is written not to throw, but never let an unexpected
+      // error escape as a non-zero exit / unparseable stdout.
+      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/danger.js

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * danger-tool.js — a demo "dangerous" tool used to PROVE the gate works.
+ *
+ * The safety case is: `toolfunnel_run_tool` must route through the hook
+ * engine's PreToolUse gate, and a DENY there must mean the tool's side effect
+ * never happens.
+ *
+ * This tool's observable side effect is: it APPENDS one line to the file named
+ * by the env var TOOLFUNNEL_DANGER_LOG. A test arranges a PreToolUse hook that
+ * DENIES this tool, runs the gated path, and then asserts the log file was NOT
+ * written (or did not gain a line). If the gate had failed open, the line would
+ * appear.
+ *
+ * When it DOES run (gate allows, or run-direct), it:
+ *   1. appends `<ISO timestamp> danger-tool fired <args>\n` to TOOLFUNNEL_DANGER_LOG
+ *   2. prints a JSON confirmation to stdout
+ *   3. exits 0
+ *
+ * If TOOLFUNNEL_DANGER_LOG is unset, it still "fires" (prints, exits 0) but
+ * writes nothing — so it is never destructive on its own; the log is the only
+ * effect and the caller chooses the path.
+ */
+
+const fs = require('node:fs');
+
+function structuredArgs() {
+  const raw = process.env.TOOLFUNNEL_TOOL_ARGS;
+  if (!raw) return null;
+  try {
+    return JSON.parse(raw);
+  } catch (_err) {
+    return { _parseError: raw };
+  }
+}
+
+function main() {
+  const logPath = process.env.TOOLFUNNEL_DANGER_LOG;
+  const args = structuredArgs();
+  const argv = process.argv.slice(2);
+  let wrote = false;
+
+  if (logPath) {
+    const line =
+      new Date().toISOString() +
+      ' danger-tool fired ' +
+      JSON.stringify({ args, argv }) +
+      '\n';
+    fs.appendFileSync(logPath, line, 'utf8');
+    wrote = true;
+  }
+
+  process.stdout.write(
+    JSON.stringify({ ok: true, fired: true, wrote, logPath: logPath || null }) + '\n'
+  );
+  process.exit(0);
+}
+
+main();

package/tools/scripts/echo.js

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * echo-tool.js — a safe local demo tool.
+ *
+ * Prints a JSON object of the args it was invoked with, then exits 0.
+ * It has NO side effects: it touches no filesystem, no network, no env-driven
+ * writes. It exists so the register / run-path / gate tests have a benign tool
+ * to exercise (the "allowed" counterpart to danger-tool.js).
+ *
+ * Args are read two ways so callers can use whichever is convenient:
+ *   1. process.argv         — positional CLI args, e.g. `node echo-tool.js a b c`
+ *   2. TOOLFUNNEL_TOOL_ARGS — a JSON-encoded object/array of structured args
+ *      (this is how the register's "script" invoke passes `args` through).
+ *
+ * Output (stdout): a single JSON object { ok, args, argv }.
+ */
+
+function parseStructuredArgs() {
+  const raw = process.env.TOOLFUNNEL_TOOL_ARGS;
+  if (!raw) return null;
+  try {
+    return JSON.parse(raw);
+  } catch (_err) {
+    // Malformed env — surface it rather than silently dropping.
+    return { _parseError: `TOOLFUNNEL_TOOL_ARGS was not valid JSON: ${raw}` };
+  }
+}
+
+function main() {
+  const argv = process.argv.slice(2);
+  const args = parseStructuredArgs();
+  const payload = { ok: true, args, argv };
+  process.stdout.write(JSON.stringify(payload) + '\n');
+  process.exit(0);
+}
+
+main();

package/tools/scripts/hash.js

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * hash-tool.js — a safe, dependency-free local cryptographic-digest tool.
+ *
+ * Purpose
+ * -------
+ * Hash UTF-8 text with a chosen algorithm (sha256 default; sha1 / md5 also
+ * offered) and return the lowercase hex digest. Useful from the Tool Manager
+ * for checksums, fingerprinting, and quick integrity checks. Uses ONLY the
+ * Node built-in `node:crypto` — 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: { algo?: "sha256" | "sha1" | "md5", text: <string> }.
+ *     `algo` defaults to "sha256" when omitted.
+ *   - 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,  algo, hexdigest }
+ *   failure: { ok:false, error }
+ *
+ * Safety invariants (mirror the isolation rule):
+ *   - NO filesystem, NO network, NO process mutation. Pure CPU on the args.
+ *   - Only an explicit allow-list of algorithms is accepted, so the tool can
+ *     never be coaxed into an unexpected / unavailable OpenSSL algorithm name.
+ *   - NEVER throws for ordinary bad input — only well-shaped JSON on stdout.
+ */
+
+const crypto = require('node:crypto');
+
+/** Algorithms this tool will accept (the names the task specifies). */
+const ALLOWED_ALGOS = new Set(['sha256', 'sha1', 'md5']);
+const DEFAULT_ALGO = 'sha256';
+
+/**
+ * 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)}` };
+  }
+}
+
+/**
+ * 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 { algo?, text }' };
+  }
+  const { text } = args;
+  const algo = args.algo === undefined || args.algo === null ? DEFAULT_ALGO : args.algo;
+  if (typeof algo !== 'string' || !ALLOWED_ALGOS.has(algo)) {
+    return { ok: false, error: `algo must be one of ${[...ALLOWED_ALGOS].join(', ')}` };
+  }
+  if (typeof text !== 'string') {
+    return { ok: false, error: 'text must be a string' };
+  }
+  // createHash can throw only for an unavailable algorithm; the allow-list above
+  // covers the universally-available ones, but wrap defensively just in case a
+  // hardened OpenSSL build (e.g. FIPS) disables md5/sha1.
+  let hexdigest;
+  try {
+    hexdigest = crypto.createHash(algo).update(text, 'utf8').digest('hex');
+  } catch (err) {
+    return { ok: false, error: `hash failed for algo "${algo}": ${(err && err.message) || String(err)}` };
+  }
+  return { ok: true, algo, hexdigest };
+}
+
+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/json.js

@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * json-tool.js — a safe, dependency-free local JSON formatter / validator.
+ *
+ * Purpose
+ * -------
+ * Validate a JSON string and either pretty-print it (default) or minify it.
+ * Useful from the Tool Manager for tidying up JSON blobs or confirming a string
+ * is valid JSON. Pure JSON.parse / JSON.stringify — no network, no filesystem.
+ *
+ * Contract with the register (the register's `defaultRunScript`)
+ * ----------------------------------------------------------
+ *   - Structured args arrive as JSON in env TOOLFUNNEL_TOOL_ARGS.
+ *   - Args: { text: <string>, indent?: <integer 0..10>, minify?: <boolean> }.
+ *       indent defaults to 2 (used for the pretty form).
+ *       minify true → return the compact (no-whitespace) form instead.
+ *   - Prints a SINGLE JSON object to stdout and exits 0 — ALWAYS exit 0, even
+ *     for invalid JSON input (reported as { ok:false, error }).
+ *
+ * Output (stdout), exactly one JSON object:
+ *   pretty:  { ok:true, pretty: "<indented json>" }      (minify falsey)
+ *   minify:  { ok:true, minified: "<compact json>" }     (minify true)
+ *   failure: { ok:false, error }                          (invalid JSON / bad args)
+ *
+ * Safety invariants (mirror the isolation rule):
+ *   - NO filesystem, NO network, NO process mutation. Pure CPU on the args.
+ *   - indent is clamped to a sane [0,10] range so a huge indent cannot blow up.
+ *   - NEVER throws for ordinary bad input — only well-shaped JSON on stdout.
+ */
+
+const MAX_INDENT = 10;
+const DEFAULT_INDENT = 2;
+
+/**
+ * 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)}` };
+  }
+}
+
+/**
+ * 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, indent?, minify? }' };
+  }
+  const { text } = args;
+  if (typeof text !== 'string') {
+    return { ok: false, error: 'text must be a string' };
+  }
+
+  // Validate indent (only meaningful for the pretty path, but validate eagerly).
+  let indent = DEFAULT_INDENT;
+  if (args.indent !== undefined && args.indent !== null) {
+    if (typeof args.indent !== 'number' || !Number.isInteger(args.indent)) {
+      return { ok: false, error: 'indent must be an integer' };
+    }
+    if (args.indent < 0 || args.indent > MAX_INDENT) {
+      return { ok: false, error: `indent must be between 0 and ${MAX_INDENT}` };
+    }
+    indent = args.indent;
+  }
+
+  // Parse the supplied JSON text — THIS is the validation step.
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch (err) {
+    return { ok: false, error: `invalid JSON: ${(err && err.message) || String(err)}` };
+  }
+
+  if (args.minify === true) {
+    return { ok: true, minified: JSON.stringify(parsed) };
+  }
+  return { ok: true, pretty: JSON.stringify(parsed, null, indent) };
+}
+
+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/text-stats.js

@@ -0,0 +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();