toolfunnel 0.3.0 → 0.5.0

package/tools/scripts/tf-pack.js

@@ -0,0 +1,237 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * tf-pack.js — a first-party MANAGEMENT tool that packages the LIVE setup for deployment.
+ *
+ * Purpose
+ * -------
+ * Everything you built in this gateway — your tools + scripts, your hot/hidden curation, your
+ * upstream selections, your policy hooks, your identity — IS a config home. This tool snapshots
+ * it into a deployment-ready artifact in a SEPARATE location (never the live tree), so "ship what
+ * I made" is one call instead of a hand-rolled copy job:
+ *
+ *   format "home" (default): <home>/dist/<name>/ = a portable config home. Zip it, git-init it,
+ *     or point any toolfunnel at it via --config-dir / TOOLFUNNEL_HOME.
+ *   format "npm": <home>/dist/<name>/ = a PUBLISHABLE npm package: package.json (with toolfunnel
+ *     as a caret DEPENDENCY — depend, never copy: your users' installs count as toolfunnel
+ *     downloads and our fixes reach them via npm update), a 2-line bin launcher pointing
+ *     --config-dir at the bundled home/, and a README stub. `cd dist/<name> && npm publish` is
+ *     your own MCP server on npm.
+ *
+ * Args (env TOOLFUNNEL_TOOL_ARGS, mirrors the other tf-* scripts):
+ *   { format?: 'home'|'npm' (default 'home'),
+ *     name?: string,        // pack/package name (default: the home's serverName, else 'my-mcp')
+ *     version?: string,     // default: the home's explicit serverVersion, else '0.1.0'
+ *     description?: string, // npm format: package.json description
+ *     out?: string,         // FOLDER NAME under <home>/dist/ (basename only; default: name)
+ *     force?: boolean }     // overwrite files in an existing non-empty out dir
+ *
+ * What travels: tools/ (register + state overlay + scripts — the hot/hidden curation IS the
+ * product), mcp/ (expose.json upstream references + any vendored servers), hooks/ (THE GATE
+ * TRAVELS — the shipped pack enforces its policy on the recipient's machine regardless of
+ * client), toolfunnel.json (identity + requires; rewritten with the pack's name/version).
+ * What NEVER travels: auth/ (environment-specific OAuth config), logs/, dist/ (recursion),
+ * packages/, node_modules, .git.
+ *
+ * Output (stdout), exactly one JSON object:
+ *   success: { ok:true, format, out, files, next:[…] }
+ *   failure: { ok:false, error }
+ * Safety: writes ONLY under <home>/dist/<basename> (the live config is read, never touched);
+ * refuses a non-empty destination without force:true; ALWAYS exits 0.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+// Shared HOME/engine resolution (see tf-env.js): config beside us, engine from the package.
+const { HOME, PKG } = require('./tf-env');
+
+const EXCLUDE_DIRS = new Set(['dist', 'logs', 'auth', 'packages', 'node_modules', '.git', '.idea', '.vscode']);
+
+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)}` };
+  }
+}
+
+/** The home's toolfunnel.json as raw JSON (or {}). Read directly — we want the EXPLICIT fields,
+ *  not the loader's folded-in defaults (a pack must not inherit toolfunnel's own version). */
+function homeIdentity() {
+  try {
+    const d = JSON.parse(fs.readFileSync(path.join(HOME, 'toolfunnel.json'), 'utf8'));
+    return d && typeof d === 'object' && !Array.isArray(d) ? d : {};
+  } catch (_e) {
+    return {};
+  }
+}
+
+/** npm-legal name: lowercase, spaces/illegals → '-', collapsed. */
+function sanitizeName(name) {
+  const s = String(name).toLowerCase().replace(/[^a-z0-9._-]+/g, '-').replace(/^[-._]+|[-._]+$/g, '');
+  return s || 'my-mcp';
+}
+
+/** Recursively copy `srcDir` → `destDir`, skipping EXCLUDE_DIRS at the top level and dotfiles
+ *  everywhere. Overwrites only when `force`. Returns the number of files written. */
+function copyTree(srcDir, destDir, force, topLevel) {
+  let count = 0;
+  let entries;
+  try {
+    entries = fs.readdirSync(srcDir, { withFileTypes: true });
+  } catch (_e) {
+    return count;
+  }
+  fs.mkdirSync(destDir, { recursive: true });
+  for (const e of entries) {
+    if (topLevel && EXCLUDE_DIRS.has(e.name)) continue;
+    if (e.name.startsWith('.')) continue;
+    const from = path.join(srcDir, e.name);
+    const to = path.join(destDir, e.name);
+    if (e.isDirectory()) {
+      count += copyTree(from, to, force, false);
+    } else if (e.isFile()) {
+      if (!force && fs.existsSync(to)) continue;
+      fs.copyFileSync(from, to);
+      count += 1;
+    }
+  }
+  return count;
+}
+
+/** The 4 config pillars → destHome. Identity is rewritten (name/version/description overlay). */
+function snapshotHome(destHome, force, identity) {
+  let files = 0;
+  for (const dir of ['tools', 'mcp', 'hooks']) {
+    files += copyTree(path.join(HOME, dir), path.join(destHome, dir), force, true);
+  }
+  fs.writeFileSync(path.join(destHome, 'toolfunnel.json'), JSON.stringify(identity, null, 2) + '\n');
+  return files + 1;
+}
+
+function run(args) {
+  const a = args && typeof args === 'object' && !Array.isArray(args) ? args : {};
+  const format = a.format === 'npm' ? 'npm' : a.format === 'home' || a.format === undefined ? 'home' : null;
+  if (format === null) return { ok: false, error: 'format must be "home" or "npm"' };
+  const force = a.force === true;
+
+  const id = homeIdentity();
+  const name = sanitizeName(a.name || id.serverName || 'my-mcp');
+  const version = typeof a.version === 'string' && a.version.trim() ? a.version.trim()
+    : (typeof id.serverVersion === 'string' && id.serverVersion.trim() ? id.serverVersion.trim() : '0.1.0');
+  const description = typeof a.description === 'string' && a.description.trim()
+    ? a.description.trim()
+    : `${name} — an MCP server built on toolfunnel.`;
+
+  // The destination: ALWAYS <home>/dist/<basename> — the separate-location guarantee. `out` is a
+  // folder NAME (basename strips traversal), never a path, so the live tree can't be targeted.
+  const outName = path.basename(String(a.out || name));
+  const outDir = path.join(HOME, 'dist', outName);
+  const rel = path.relative(path.join(HOME, 'dist'), outDir);
+  if (rel === '' || rel.startsWith('..') || path.isAbsolute(rel)) {
+    return { ok: false, error: `out "${a.out}" escapes <home>/dist` };
+  }
+  if (!force && fs.existsSync(outDir) && fs.readdirSync(outDir).length > 0) {
+    return { ok: false, error: `destination is not empty: ${outDir} — pass force:true to overwrite (files are replaced, extras are kept)` };
+  }
+
+  // The identity the pack CARRIES (preserves requires + any custom fields; stamps name/version).
+  const identity = Object.assign({}, id, { serverName: name, serverVersion: version });
+
+  let files = 0;
+  const next = [];
+  if (format === 'home') {
+    files = snapshotHome(outDir, force, identity);
+    next.push(`portable config home written — zip it, git-init it, or run: toolfunnel --config-dir "${outDir}"`);
+  } else {
+    // npm: bundled home + generated package.json + 2-line bin + README stub.
+    files = snapshotHome(path.join(outDir, 'home'), force, identity);
+
+    let tfVersion = '0.4.0';
+    try { tfVersion = require(path.join(PKG, 'package.json')).version || tfVersion; } catch (_e) { /* keep fallback */ }
+    const envOverride = name.toUpperCase().replace(/[^A-Z0-9]+/g, '_') + '_HOME';
+
+    const pkgJson = {
+      name,
+      version,
+      description,
+      license: 'MIT',
+      type: 'commonjs',
+      bin: { [name]: `bin/${name}.js` },
+      files: ['bin/', 'home/'],
+      // DEPEND, never copy: installs of this package count as toolfunnel downloads, and
+      // toolfunnel's fixes reach it through a normal `npm update` instead of a stale fork.
+      dependencies: { toolfunnel: `^${tfVersion}` },
+      engines: { node: '>=18' },
+    };
+    fs.writeFileSync(path.join(outDir, 'package.json'), JSON.stringify(pkgJson, null, 2) + '\n');
+
+    const binDir = path.join(outDir, 'bin');
+    fs.mkdirSync(binDir, { recursive: true });
+    fs.writeFileSync(path.join(binDir, `${name}.js`), [
+      '#!/usr/bin/env node',
+      "'use strict';",
+      `// ${name} — an MCP server built on toolfunnel, launched against its own bundled config home.`,
+      `// Set ${envOverride} to run from an external copy of the home (survives npm updates).`,
+      "const path = require('node:path');",
+      `const home = process.env.${envOverride} || path.join(__dirname, '..', 'home');`,
+      "process.argv.splice(2, 0, '--config-dir', home);",
+      "require('toolfunnel/bin/toolfunnel.js');",
+      '',
+    ].join('\n'));
+
+    const readmePath = path.join(outDir, 'README.md');
+    if (force || !fs.existsSync(readmePath)) {
+      fs.writeFileSync(readmePath, [
+        `# ${name}`,
+        '',
+        description,
+        '',
+        'An MCP server packaged with [toolfunnel](https://github.com/Rendeverance/toolfunnel) —',
+        'the bundled `home/` carries the tools, curation, upstream references, AND the policy',
+        'hooks: the gate travels with the pack and enforces itself on any MCP client.',
+        '',
+        '## Run',
+        '```bash',
+        `npx ${name}`,
+        '```',
+        '',
+        '## Use an external home (survives npm updates)',
+        `Set \`${envOverride}\` to a directory holding a copy of \`home/\`.`,
+        '',
+        '## Audit honesty',
+        'Packs spawn commands. Read `home/mcp/expose.json`, `home/tools/tools.register.json`,',
+        'and `home/toolfunnel.json` (its `requires` probes run at startup) of anything you',
+        'install — including this.',
+        '',
+      ].join('\n'));
+      files += 1;
+    }
+    files += 2; // package.json + bin
+    next.push(`publishable npm package written — review it, then: cd "${outDir}" && npm publish`);
+    next.push(`try it locally first: node "${path.join(outDir, 'bin', `${name}.js`)}"`);
+  }
+
+  return { ok: true, format, out: outDir, files, next };
+}
+
+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();

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

@@ -8,9 +8,10 @@
  * -------
  * The write-side counterpart to the read-only status / inventory tools: it lets
  * the manager surface a NEW tool in the register at runtime (no reconnect — the
- * meta-tools re-read the register every call). Optionally it also writes the
- * host-local script the new entry invokes, so a single call can create both the
- * register entry AND its backing script atomically.
+ * running gateway watches tools.register.json and hot-reloads its register on
+ * change). Optionally it also writes the host-local script the new entry invokes,
+ * so a single call can create both the register entry AND its backing script
+ * atomically.
  *
  * This is a "gateway-run" tool: it mutates ToolFunnel's OWN config (the register
  * and, optionally, a script under the scripts root). It runs through the same
@@ -20,9 +21,12 @@
  * Contract with the register (registry.js `defaultRunScript`)
  * ----------------------------------------------------------
  *   - Structured args arrive as JSON in env TOOLFUNNEL_TOOL_ARGS ({} / absent => null).
- *   - Args: { id, name, summary?, category?, instructions?,
+ *   - Args: { id, name, summary?, category?, instructions?, inputSchema?,
  *             invoke: { type:'script'|'shell', path?|command? },
  *             scriptText? }
+ *       inputSchema (a JSON Schema object) is what a HOT-promoted tool advertises verbatim in
+ *       the top-level tools/list — dropping it here was the gap between "your own tools" and
+ *       "your own tools AND schemas".
  *       When scriptText is a string AND invoke.type === 'script', the script is
  *       written first (registry.writeScript), THEN the entry is added.
  *   - Prints a SINGLE JSON object to stdout and exits 0 — ALWAYS exit 0, even on
@@ -41,17 +45,11 @@
  */
 
 const path = require('node:path');
-const { loadRegistry } = require('../../src/tools/registry');
+// Shared HOME/engine resolution (see tf-env.js): config beside us, engine from the package.
+const { HOME, srcRequire } = require('./tf-env');
+const { loadRegistry } = srcRequire('tools/registry');
 
-/**
- * The toolfunnel root, resolved from THIS file's location so the tool is portable
- * and stays inside the sandbox.
- *
- * This script lives at:  <root>/tools/scripts/tf-tool-add.js
- * so the root is two directories up from __dirname:
- *   scripts -> tools -> <root>
- */
-const ROOT = path.resolve(__dirname, '..', '..');
+const ROOT = HOME;
 const REGISTER_PATH = path.join(ROOT, 'tools', 'tools.register.json');
 const SCRIPTS_ROOT = path.join(ROOT, 'tools', 'scripts');
 
@@ -83,10 +81,10 @@ function run(args) {
   if (!args || typeof args !== 'object' || Array.isArray(args)) {
     return {
       ok: false,
-      error: 'args must be an object { id, name, summary?, category?, instructions?, invoke, scriptText? }',
+      error: 'args must be an object { id, name, summary?, category?, instructions?, inputSchema?, invoke, scriptText? }',
     };
   }
-  const { id, name, summary, category, instructions, invoke, scriptText } = args;
+  const { id, name, summary, category, instructions, inputSchema, invoke, scriptText } = args;
 
   // Build a clean register entry (only carry through the optional fields when
   // present so the persisted entry stays tidy). registry.add validates shape.
@@ -94,6 +92,8 @@ function run(args) {
   if (summary !== undefined) entry.summary = summary;
   if (category !== undefined) entry.category = category;
   if (instructions !== undefined) entry.instructions = instructions;
+  if (inputSchema !== undefined) entry.inputSchema = inputSchema; // validated by registry.add
+
 
   const registry = loadRegistry(REGISTER_PATH, { scriptsRoot: SCRIPTS_ROOT });
 

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

@@ -45,18 +45,12 @@
  */
 
 const path = require('node:path');
-const { loadRegistry } = require('../../src/tools/registry');
-const { setToolEnabled, setToolHot, setToolHidden, clearToolState } = require('../../src/tools/tool-state');
+// Shared HOME/engine resolution (see tf-env.js): config beside us, engine from the package.
+const { HOME, srcRequire } = require('./tf-env');
+const { loadRegistry } = srcRequire('tools/registry');
+const { setToolEnabled, setToolHot, setToolHidden, clearToolState } = srcRequire('tools/tool-state');
 
-/**
- * The toolfunnel root, resolved from THIS file's location so the tool is portable
- * and stays inside the sandbox.
- *
- * This script lives at:  <root>/tools/scripts/tf-tool-set.js
- * so the root is two directories up from __dirname:
- *   scripts -> tools -> <root>
- */
-const ROOT = path.resolve(__dirname, '..', '..');
+const ROOT = HOME;
 const REGISTER_PATH = path.join(ROOT, 'tools', 'tools.register.json');
 const STATE_PATH = path.join(ROOT, 'tools', 'tools.state.json');
 const SCRIPTS_ROOT = path.join(ROOT, 'tools', 'scripts');

package/tools/tools.register.json

@@ -84,7 +84,7 @@
       "name": "tf_tool_add",
       "summary": "Register a new tool entry in the gateway tool register.",
       "category": "management",
-      "instructions": "Add a register entry. Args: { id, name, summary?, category?, instructions?, invoke:{type:'script',path:'scripts/<file>'}|{type:'shell',command}, scriptText? }. If scriptText is given for a script invoke, the body is written to tools/scripts/<basename> first. Change is LIVE (no reconnect). Fails if id already exists.",
+      "instructions": "Add a register entry. Args: { id, name, summary?, category?, instructions?, inputSchema?, invoke:{type:'script',path:'scripts/<file>'}|{type:'shell',command}, scriptText? }. inputSchema is a JSON Schema object for the tool's args - a HOT-promoted tool advertises it verbatim in the top-level tools/list, so author it if the tool may be promoted. If scriptText is given for a script invoke, the body is written to tools/scripts/<basename> first. Change is LIVE (no reconnect). Fails if id already exists.",
       "invoke": {
         "type": "script",
         "path": "scripts/tf-tool-add.js"
@@ -166,6 +166,51 @@
         "type": "script",
         "path": "scripts/tf-log.js"
       }
+    },
+    {
+      "id": "tf_pack",
+      "name": "tf_pack",
+      "summary": "Package the LIVE setup into a deployment-ready artifact under <home>/dist/ (portable config home, or a publishable npm package wrapping toolfunnel).",
+      "category": "management",
+      "instructions": "Args: { format?:'home'|'npm' (default 'home'), name?, version?, description?, out?, force? }. Snapshots the current setup - tools + scripts, hot/hidden curation (tools.state.json), upstream references (mcp/expose.json), policy hooks (THE GATE TRAVELS), and identity (toolfunnel.json, rewritten with the pack's name/version; a declared `requires` travels too) - into <home>/dist/<out||name>/, a SEPARATE location from the live config. format 'home' = a portable config home (zip / git init / run via --config-dir). format 'npm' = a publishable package: generated package.json with toolfunnel as a caret DEPENDENCY (depend, never copy), a 2-line bin launcher pointing --config-dir at the bundled home/, and a README stub - then `cd dist/<name> && npm publish`. NEVER ships auth/ or logs/. Refuses a non-empty destination without force:true. out is a folder NAME under dist/, never a path.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "format": {
+            "type": "string",
+            "enum": [
+              "home",
+              "npm"
+            ],
+            "description": "Artifact type: portable config home (default) or publishable npm package."
+          },
+          "name": {
+            "type": "string",
+            "description": "Pack/package name (default: the home's serverName)."
+          },
+          "version": {
+            "type": "string",
+            "description": "Pack version (default: the home's serverVersion, else 0.1.0)."
+          },
+          "description": {
+            "type": "string",
+            "description": "npm format: the package.json description."
+          },
+          "out": {
+            "type": "string",
+            "description": "Folder NAME under <home>/dist/ (default: name)."
+          },
+          "force": {
+            "type": "boolean",
+            "description": "Overwrite files in an existing non-empty destination."
+          }
+        },
+        "additionalProperties": false
+      },
+      "invoke": {
+        "type": "script",
+        "path": "scripts/tf-pack.js"
+      }
     }
   ]
 }