toolfunnel 0.7.0 → 0.8.0

package/src/extend/howto.js

@@ -1,102 +1,102 @@
-'use strict';
-
-/**
- * howto.js - the loader behind the `toolfunnel_howto` meta-tool.
- *
- * `toolfunnel_howto({ topic })` returns the self-extension instructions for one topic. This module
- * resolves a topic to its authored markdown file (the topic -> file map below) and reads it.
- *
- *   howto(topic) -> string   // the markdown content for that topic
- *
- * Topics: create-tool | add-mcp | add-hook | package | wrap | configure
- * (the original four topics, plus the 0.6.0 pair - the transparent wrap and the no-code
- * config map - so a primer-less agent can learn the headline feature from inside).
- * Unknown topics THROW (the protocol layer turns that into a clean tool error, not a crash).
- *
- * Isolation: reads are confined to THIS directory (src/extend). The topic map is a fixed
- * allow-list of basenames - there is no path interpolation from the caller, so an untrusted
- * `topic` cannot traverse out of src/extend. We additionally re-verify the resolved path is
- * inside this directory (defense-in-depth, mirroring the hook loader's writeScript guard).
- *
- * CommonJS only. Node built-ins only. No transport, pure file read - unit-testable directly.
- */
-
-const fs = require('node:fs');
-const path = require('node:path');
-
-// The directory these instruction files live in (this module's own directory).
-const EXTEND_DIR = __dirname;
-
-/**
- * Fixed topic -> filename map. The set of keys IS the list of valid topics; the values are
- * plain basenames (no separators) so nothing the caller passes is ever joined into a path.
- * @type {Readonly<Record<string,string>>}
- */
-const TOPIC_FILES = Object.freeze({
-  'create-tool': 'create-tool.md',
-  'add-mcp': 'add-mcp.md',
-  'add-hook': 'add-hook.md',
-  package: 'package.md',
-  wrap: 'wrap.md',
-  configure: 'configure.md',
-});
-
-/**
- * The valid topic names, for error messages and for callers that want to enumerate
- * (e.g. the protocol layer validating args, or a UI listing the howto topics).
- * @returns {string[]}
- */
-function topics() {
-  return Object.keys(TOPIC_FILES);
-}
-
-/**
- * Resolve a topic to the instruction markdown content.
- *
- * @param {string} topic one of: create-tool | add-mcp | add-hook | package | wrap | configure
- * @returns {string} the UTF-8 markdown content of the matching file
- * @throws {Error} if `topic` is not a string, is unknown, or (defensively) resolves outside
- *                 src/extend or the file is missing.
- */
-function howto(topic) {
-  if (typeof topic !== 'string' || topic.length === 0) {
-    throw new Error(
-      `howto: topic must be a non-empty string. Known topics: ${topics().join(', ')}`
-    );
-  }
-
-  // Look up against the fixed allow-list - own property only (guards against "constructor",
-  // "__proto__", etc. resolving via the prototype chain).
-  if (!Object.prototype.hasOwnProperty.call(TOPIC_FILES, topic)) {
-    throw new Error(
-      `howto: unknown topic "${topic}". Known topics: ${topics().join(', ')}`
-    );
-  }
-
-  const fileName = TOPIC_FILES[topic];
-  const filePath = path.join(EXTEND_DIR, fileName);
-
-  // Defense-in-depth: confirm the resolved path is still inside EXTEND_DIR. With a fixed
-  // basename map this can never fail, but the guard documents and enforces the isolation rule.
-  const rel = path.relative(EXTEND_DIR, filePath);
-  if (rel === '' || rel.startsWith('..') || path.isAbsolute(rel)) {
-    throw new Error(`howto: refusing to read outside src/extend ("${fileName}")`);
-  }
-
-  try {
-    return fs.readFileSync(filePath, 'utf8');
-  } catch (err) {
-    // A known topic whose file is missing is a packaging error, not an unknown-topic error.
-    throw new Error(
-      `howto: instruction file for topic "${topic}" is missing or unreadable ` +
-        `(${filePath}): ${(err && err.message) || String(err)}`
-    );
-  }
-}
-
-module.exports = {
-  howto,
-  topics,
-  TOPIC_FILES,
-  EXTEND_DIR,
-};
+'use strict';
+
+/**
+ * howto.js - the loader behind the `toolfunnel_howto` meta-tool.
+ *
+ * `toolfunnel_howto({ topic })` returns the self-extension instructions for one topic. This module
+ * resolves a topic to its authored markdown file (the topic -> file map below) and reads it.
+ *
+ *   howto(topic) -> string   // the markdown content for that topic
+ *
+ * Topics: create-tool | add-mcp | add-hook | package | wrap | configure
+ * (the original four topics, plus the 0.6.0 pair - the transparent wrap and the no-code
+ * config map - so a primer-less agent can learn the headline feature from inside).
+ * Unknown topics THROW (the protocol layer turns that into a clean tool error, not a crash).
+ *
+ * Isolation: reads are confined to THIS directory (src/extend). The topic map is a fixed
+ * allow-list of basenames - there is no path interpolation from the caller, so an untrusted
+ * `topic` cannot traverse out of src/extend. We additionally re-verify the resolved path is
+ * inside this directory (defense-in-depth, mirroring the hook loader's writeScript guard).
+ *
+ * CommonJS only. Node built-ins only. No transport, pure file read - unit-testable directly.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+// The directory these instruction files live in (this module's own directory).
+const EXTEND_DIR = __dirname;
+
+/**
+ * Fixed topic -> filename map. The set of keys IS the list of valid topics; the values are
+ * plain basenames (no separators) so nothing the caller passes is ever joined into a path.
+ * @type {Readonly<Record<string,string>>}
+ */
+const TOPIC_FILES = Object.freeze({
+  'create-tool': 'create-tool.md',
+  'add-mcp': 'add-mcp.md',
+  'add-hook': 'add-hook.md',
+  package: 'package.md',
+  wrap: 'wrap.md',
+  configure: 'configure.md',
+});
+
+/**
+ * The valid topic names, for error messages and for callers that want to enumerate
+ * (e.g. the protocol layer validating args, or a UI listing the howto topics).
+ * @returns {string[]}
+ */
+function topics() {
+  return Object.keys(TOPIC_FILES);
+}
+
+/**
+ * Resolve a topic to the instruction markdown content.
+ *
+ * @param {string} topic one of: create-tool | add-mcp | add-hook | package | wrap | configure
+ * @returns {string} the UTF-8 markdown content of the matching file
+ * @throws {Error} if `topic` is not a string, is unknown, or (defensively) resolves outside
+ *                 src/extend or the file is missing.
+ */
+function howto(topic) {
+  if (typeof topic !== 'string' || topic.length === 0) {
+    throw new Error(
+      `howto: topic must be a non-empty string. Known topics: ${topics().join(', ')}`
+    );
+  }
+
+  // Look up against the fixed allow-list - own property only (guards against "constructor",
+  // "__proto__", etc. resolving via the prototype chain).
+  if (!Object.prototype.hasOwnProperty.call(TOPIC_FILES, topic)) {
+    throw new Error(
+      `howto: unknown topic "${topic}". Known topics: ${topics().join(', ')}`
+    );
+  }
+
+  const fileName = TOPIC_FILES[topic];
+  const filePath = path.join(EXTEND_DIR, fileName);
+
+  // Defense-in-depth: confirm the resolved path is still inside EXTEND_DIR. With a fixed
+  // basename map this can never fail, but the guard documents and enforces the isolation rule.
+  const rel = path.relative(EXTEND_DIR, filePath);
+  if (rel === '' || rel.startsWith('..') || path.isAbsolute(rel)) {
+    throw new Error(`howto: refusing to read outside src/extend ("${fileName}")`);
+  }
+
+  try {
+    return fs.readFileSync(filePath, 'utf8');
+  } catch (err) {
+    // A known topic whose file is missing is a packaging error, not an unknown-topic error.
+    throw new Error(
+      `howto: instruction file for topic "${topic}" is missing or unreadable ` +
+        `(${filePath}): ${(err && err.message) || String(err)}`
+    );
+  }
+}
+
+module.exports = {
+  howto,
+  topics,
+  TOPIC_FILES,
+  EXTEND_DIR,
+};

package/src/extend/package.md

@@ -1,190 +1,190 @@
-# How to package and share units (self-extension)
-
-This is the instruction served by `toolfunnel_howto({ topic: "package" })`. It explains how to bundle
-tools, hooks, and MCP configs into a **shareable package** and how import/export work. Packaging is a
-**byproduct** of the gateway design: because every unit is already structured and
-self-documented, a package is just a folder that lists its units and carries their files.
-
----
-
-## 0. The WHOLE-SETUP path - `tf_pack` (start here)
-
-Since 0.4.0 the fastest way to ship is not per-unit packaging but the **whole setup**: your entire
-config home (tools + scripts, hot/hidden curation, upstream references, policy hooks, identity) is
-already the product. One call packages it into a deployment-ready artifact under `<home>/dist/`:
-
-- `tf_pack { format: "home" }` → a **portable config home**. Zip it, git-init it, or run it
-  directly: `toolfunnel --config-dir <dir>`. The receiving gateway seeds nothing - the pack IS the
-  config, including the hooks: **the gate travels**, enforcing your policy on the recipient's
-  machine regardless of which MCP client they use.
-- `tf_pack { format: "npm", name: "my-mcp" }` → a **publishable npm package**: a generated
-  `package.json` that depends on `toolfunnel` (caret range - DEPEND, never copy the engine), a
-  2-line bin launcher pointing `--config-dir` at the bundled home, and a README stub.
-  `cd dist/my-mcp && npm publish` → your users run `npx my-mcp` and get YOUR server, under YOUR
-  name (the bundled `toolfunnel.json` identity), with YOUR gate.
-
-Declare the runtimes your tools need in the home's `toolfunnel.json` - they travel with the pack
-and the receiving gateway warns at startup about anything missing:
-
-```json
-"requires": [ { "command": "python", "min": "3.10", "why": "the pdf tools" } ]
-```
-
-Audit honesty (both directions): packs spawn commands. Tell your users to read your pack's
-`expose.json`, `tools.register.json`, AND `toolfunnel.json` (its `requires` probes execute at
-gateway startup - bare program names only, the loader rejects anything shell-shaped) - and read
-all three yourself in anything you install.
-
-The per-UNIT packaging below remains the right shape for sharing a single tool/hook/MCP selection
-rather than a whole gateway.
-
-The per-unit package is a CONVENTION, not machinery: export and import are the structured
-hand-steps below (each one maps onto a management function), so a package needs no importer
-binary - and the whole-setup `tf_pack` above covers the common case with one call.
-
----
-
-## 1. What a unit is (and what travels with it)
-
-Each unit is self-contained - this is the whole reason packaging is cheap:
-
-| Unit | Its metadata | Its files |
-|---|---|---|
-| **tool** | one `tools.register.json` entry (`id/name/summary/category/instructions/invoke`) | the script under `tools/scripts/` (for `invoke.type === "script"`) |
-| **hook** | one `hooks.manifest.json` entry (`id/event/matcher/command/script/timeout/description`) + its `hooks.state.json` enabled value | the script under `hooks/scripts/` |
-| **mcp** | one `expose.json` `upstreams[]` entry + its `expose[]` selections | any vendored server files it spawns (must live inside the package) |
-
-A package gathers one or more of these, plus the files they reference.
-
----
-
-## 2. Package layout
-
-A package is a folder (conventionally `packages/<name>/` inside the config home) containing a
-manifest and the units' files in a mirrored tree so import is a structured copy, not guesswork:
-
-```
-packages/
-  notify-pack/
-    package.json          # the package manifest (below)
-    tools/
-      scripts/
-        msg-digest.sh
-    hooks/
-      scripts/
-        rate-limit.sh
-    mcp/
-      vendor/             # any vendored upstream server files
-```
-
-### `package.json` - the package manifest
-
-A `package.json`-style manifest listing the package's identity and its units (the metadata blocks are
-embedded so import is self-sufficient - it does not need the source register/manifest to reconstruct
-entries):
-
-```json
-{
-  "name": "notify-pack",
-  "version": "1.0.0",
-  "description": "Message digest tool + rate-limit gate + upstream MCP exposure.",
-  "author": "unknown",
-  "units": {
-    "tools": [
-      {
-        "entry": {
-          "id": "msg-digest",
-          "name": "Message Digest",
-          "summary": "Summarises unread chats.",
-          "category": "messaging",
-          "instructions": "Pass { since? }. Returns a per-chat unread digest.",
-          "invoke": { "type": "script", "path": "scripts/msg-digest.sh" }
-        },
-        "files": ["tools/scripts/msg-digest.sh"]
-      }
-    ],
-    "hooks": [
-      {
-        "entry": {
-          "id": "pre-tool-use/rate-limit",
-          "event": "PreToolUse",
-          "matcher": "msg_send_message",
-          "type": "command",
-          "command": "bash \"${HOOKS_DIR}/scripts/rate-limit.sh\"",
-          "script": "scripts/rate-limit.sh",
-          "timeout": 5,
-          "description": "Denies sends past a per-minute cap."
-        },
-        "enabled": true,
-        "files": ["hooks/scripts/rate-limit.sh"]
-      }
-    ],
-    "mcp": [
-      {
-        "upstream": {
-          "id": "notify",
-          "transport": "stdio",
-          "command": "node",
-          "args": ["mcp/vendor/notify-mcp/server.js"],
-          "enabled": true,
-          "description": "Messaging bridge MCP."
-        },
-        "expose": [
-          { "upstream": "notify", "tool": "list_chats", "as": "msg_list_chats", "category": "messaging", "enabled": true },
-          { "upstream": "notify", "tool": "send_message", "as": "msg_send_message", "category": "messaging", "enabled": true }
-        ],
-        "files": ["mcp/vendor/notify-mcp/server.js"]
-      }
-    ]
-  }
-}
-```
-
-| Field | Meaning |
-|---|---|
-| `name` / `version` / `description` / `author` | Package identity. `name` is the folder name and the import key. |
-| `units.tools[]` | Each has the full register `entry` plus `files` (paths inside the package). |
-| `units.hooks[]` | Each has the full manifest `entry`, its seed `enabled` (for `hooks.state.json`), and `files`. |
-| `units.mcp[]` | Each has an `upstream` block, its `expose[]` selections, and any vendored `files`. |
-
-Write vendored-server paths RELATIVE and set the upstream's `cwd` to the installed package
-folder (or write the absolute inside-home path at import time) - the isolation guard requires
-them inside the config home either way.
-
----
-
-## 3. Export - bundling a unit (or several)
-
-To export, gather a unit's metadata and its files into a package folder:
-
-1. Create `packages/<name>/` with a `package.json` manifest.
-2. For each tool: copy its `tools.register.json` entry into `units.tools[].entry`, copy its
-   `tools/scripts/<file>` into the package's `tools/scripts/`, and list it in `files`.
-3. For each hook: copy its `hooks.manifest.json` entry into `units.hooks[].entry`, copy its enabled
-   value from `hooks.state.json` into `enabled`, copy the script into `hooks/scripts/`, list it.
-4. For each MCP: copy the `upstreams[]` block + matching `expose[]` selections, and vendor any server
-   files into `mcp/vendor/`.
-
-The package is then a single folder, self-describing and copy-portable. (Everything stays inside
-`packages/` - the isolation rule still holds.)
-
----
-
-## 4. Import - installing a package
-
-Import is the reverse: **drop a package folder in `packages/` + register its units.**
-
-1. Read `packages/<name>/package.json`.
-2. **Tools:** copy each `units.tools[].files` into `tools/scripts/` and add each `entry` to
-   `tools.register.json` (atomic write via `registry.js`). Reject id collisions or prompt to rename.
-3. **Hooks:** copy each `units.hooks[].files` into `hooks/scripts/` and add each `entry` to
-   `hooks.manifest.json`; write its `enabled` into `hooks.state.json`.
-4. **MCP:** copy vendored `files` into the package's `mcp/vendor/`, add each `upstream` to
-   `expose.json` `upstreams[]` and its `expose[]` selections, rewriting the vendored paths for
-   their installed location (inside the config home - the isolation rule).
-
-After import: tools are live immediately (the register is read fresh on every `toolfunnel_list_tools`).
-Hooks take effect once the loader re-scans (next startup, or a reload). Curated-direct MCP tools need
-a reconnect to reach the CLI surface (register-routed tools do not). Verify with `toolfunnel_list_tools`
-and a `run`/run-once test that the gate still fires on the imported units - the PreToolUse gate
-applies to imported tools exactly as it does to local ones.
+# How to package and share units (self-extension)
+
+This is the instruction served by `toolfunnel_howto({ topic: "package" })`. It explains how to bundle
+tools, hooks, and MCP configs into a **shareable package** and how import/export work. Packaging is a
+**byproduct** of the gateway design: because every unit is already structured and
+self-documented, a package is just a folder that lists its units and carries their files.
+
+---
+
+## 0. The WHOLE-SETUP path - `tf_pack` (start here)
+
+The fastest way to ship is not per-unit packaging but the **whole setup**: your entire
+config home (tools + scripts, hot/hidden curation, upstream references, policy hooks, identity) is
+already the product. One call packages it into a deployment-ready artifact under `<home>/dist/`:
+
+- `tf_pack { format: "home" }` → a **portable config home**. Zip it, git-init it, or run it
+  directly: `toolfunnel --config-dir <dir>`. The receiving gateway seeds nothing - the pack IS the
+  config, including the hooks: **the gate travels**, enforcing your policy on the recipient's
+  machine regardless of which MCP client they use.
+- `tf_pack { format: "npm", name: "my-mcp" }` → a **publishable npm package**: a generated
+  `package.json` that depends on `toolfunnel` (caret range - DEPEND, never copy the engine), a
+  2-line bin launcher pointing `--config-dir` at the bundled home, and a README stub.
+  `cd dist/my-mcp && npm publish` → your users run `npx my-mcp` and get YOUR server, under YOUR
+  name (the bundled `toolfunnel.json` identity), with YOUR gate.
+
+Declare the runtimes your tools need in the home's `toolfunnel.json` - they travel with the pack
+and the receiving gateway warns at startup about anything missing:
+
+```json
+"requires": [ { "command": "python", "min": "3.10", "why": "the pdf tools" } ]
+```
+
+Audit honesty (both directions): packs spawn commands. Tell your users to read your pack's
+`expose.json`, `tools.register.json`, AND `toolfunnel.json` (its `requires` probes execute at
+gateway startup - bare program names only, the loader rejects anything shell-shaped) - and read
+all three yourself in anything you install.
+
+The per-UNIT packaging below remains the right shape for sharing a single tool/hook/MCP selection
+rather than a whole gateway.
+
+The per-unit package is a CONVENTION, not machinery: export and import are the structured
+hand-steps below (each one maps onto a management function), so a package needs no importer
+binary - and the whole-setup `tf_pack` above covers the common case with one call.
+
+---
+
+## 1. What a unit is (and what travels with it)
+
+Each unit is self-contained - this is the whole reason packaging is cheap:
+
+| Unit | Its metadata | Its files |
+|---|---|---|
+| **tool** | one `tools.register.json` entry (`id/name/summary/category/instructions/invoke`) | the script under `tools/scripts/` (for `invoke.type === "script"`) |
+| **hook** | one `hooks.manifest.json` entry (`id/event/matcher/command/script/timeout/description`) + its `hooks.state.json` enabled value | the script under `hooks/scripts/` |
+| **mcp** | one `expose.json` `upstreams[]` entry + its `expose[]` selections | any vendored server files it spawns (must live inside the package) |
+
+A package gathers one or more of these, plus the files they reference.
+
+---
+
+## 2. Package layout
+
+A package is a folder (conventionally `packages/<name>/` inside the config home) containing a
+manifest and the units' files in a mirrored tree so import is a structured copy, not guesswork:
+
+```
+packages/
+  notify-pack/
+    package.json          # the package manifest (below)
+    tools/
+      scripts/
+        msg-digest.sh
+    hooks/
+      scripts/
+        rate-limit.sh
+    mcp/
+      vendor/             # any vendored upstream server files
+```
+
+### `package.json` - the package manifest
+
+A `package.json`-style manifest listing the package's identity and its units (the metadata blocks are
+embedded so import is self-sufficient - it does not need the source register/manifest to reconstruct
+entries):
+
+```json
+{
+  "name": "notify-pack",
+  "version": "1.0.0",
+  "description": "Message digest tool + rate-limit gate + upstream MCP exposure.",
+  "author": "unknown",
+  "units": {
+    "tools": [
+      {
+        "entry": {
+          "id": "msg-digest",
+          "name": "Message Digest",
+          "summary": "Summarises unread chats.",
+          "category": "messaging",
+          "instructions": "Pass { since? }. Returns a per-chat unread digest.",
+          "invoke": { "type": "script", "path": "scripts/msg-digest.sh" }
+        },
+        "files": ["tools/scripts/msg-digest.sh"]
+      }
+    ],
+    "hooks": [
+      {
+        "entry": {
+          "id": "pre-tool-use/rate-limit",
+          "event": "PreToolUse",
+          "matcher": "msg_send_message",
+          "type": "command",
+          "command": "bash \"${HOOKS_DIR}/scripts/rate-limit.sh\"",
+          "script": "scripts/rate-limit.sh",
+          "timeout": 5,
+          "description": "Denies sends past a per-minute cap."
+        },
+        "enabled": true,
+        "files": ["hooks/scripts/rate-limit.sh"]
+      }
+    ],
+    "mcp": [
+      {
+        "upstream": {
+          "id": "notify",
+          "transport": "stdio",
+          "command": "node",
+          "args": ["mcp/vendor/notify-mcp/server.js"],
+          "enabled": true,
+          "description": "Messaging bridge MCP."
+        },
+        "expose": [
+          { "upstream": "notify", "tool": "list_chats", "as": "msg_list_chats", "category": "messaging", "enabled": true },
+          { "upstream": "notify", "tool": "send_message", "as": "msg_send_message", "category": "messaging", "enabled": true }
+        ],
+        "files": ["mcp/vendor/notify-mcp/server.js"]
+      }
+    ]
+  }
+}
+```
+
+| Field | Meaning |
+|---|---|
+| `name` / `version` / `description` / `author` | Package identity. `name` is the folder name and the import key. |
+| `units.tools[]` | Each has the full register `entry` plus `files` (paths inside the package). |
+| `units.hooks[]` | Each has the full manifest `entry`, its seed `enabled` (for `hooks.state.json`), and `files`. |
+| `units.mcp[]` | Each has an `upstream` block, its `expose[]` selections, and any vendored `files`. |
+
+Write vendored-server paths RELATIVE and set the upstream's `cwd` to the installed package
+folder (or write the absolute inside-home path at import time) - the isolation guard requires
+them inside the config home either way.
+
+---
+
+## 3. Export - bundling a unit (or several)
+
+To export, gather a unit's metadata and its files into a package folder:
+
+1. Create `packages/<name>/` with a `package.json` manifest.
+2. For each tool: copy its `tools.register.json` entry into `units.tools[].entry`, copy its
+   `tools/scripts/<file>` into the package's `tools/scripts/`, and list it in `files`.
+3. For each hook: copy its `hooks.manifest.json` entry into `units.hooks[].entry`, copy its enabled
+   value from `hooks.state.json` into `enabled`, copy the script into `hooks/scripts/`, list it.
+4. For each MCP: copy the `upstreams[]` block + matching `expose[]` selections, and vendor any server
+   files into `mcp/vendor/`.
+
+The package is then a single folder, self-describing and copy-portable. (Everything stays inside
+`packages/` - the isolation rule still holds.)
+
+---
+
+## 4. Import - installing a package
+
+Import is the reverse: **drop a package folder in `packages/` + register its units.**
+
+1. Read `packages/<name>/package.json`.
+2. **Tools:** copy each `units.tools[].files` into `tools/scripts/` and add each `entry` to
+   `tools.register.json` (atomic write via `registry.js`). Reject id collisions or prompt to rename.
+3. **Hooks:** copy each `units.hooks[].files` into `hooks/scripts/` and add each `entry` to
+   `hooks.manifest.json`; write its `enabled` into `hooks.state.json`.
+4. **MCP:** copy vendored `files` into the package's `mcp/vendor/`, add each `upstream` to
+   `expose.json` `upstreams[]` and its `expose[]` selections, rewriting the vendored paths for
+   their installed location (inside the config home - the isolation rule).
+
+After import: tools are live immediately (the register is read fresh on every `toolfunnel_list_tools`).
+Hooks take effect once the loader re-scans (next startup, or a reload). Curated-direct MCP tools need
+a reconnect to reach the CLI surface (register-routed tools do not). Verify with `toolfunnel_list_tools`
+and a `run`/run-once test that the gate still fires on the imported units - the PreToolUse gate
+applies to imported tools exactly as it does to local ones.