@blucca/n8n-check 0.1.6 → 0.1.7

package/README.md

@@ -6,9 +6,11 @@ Give it a workflow export, fixture inputs and HTTP mock responses. It runs the a
 
 ## Build a check for your own workflow
 
-**[Open the local case builder](https://blucca.github.io/n8n-check/)** — import an n8n export, choose the fixture boundary and the output to preserve, then download a case and GitHub Actions file.
+**[Open the local case builder](https://blucca.github.io/n8n-check/)** — import an n8n export, choose the fixture boundary and the output to preserve, then download a **local run pack** or GitHub Actions file.
 
-Exported JSON pins can prefill the input and expected items. The builder lists the nodes in the slice and identifies missing fixtures, HTTP mock contracts, and structural dependencies before you install a runtime. File contents stay in your browser tab; review the snapshots against the behavior you want to preserve. A completed case runs with the released **v0.1.6** CLI or Action. Select **Full JSON items** for a complete snapshot, **Selected field + item count** for stable IDs with changing timestamps, or **Item count** for output volume. Field paths start at the n8n item, such as `json.id`; expected values preserve order and duplicates.
+**Have Docker? Download → unzip → `sh run.sh`.** The pack includes your workflow, editable case, and a pinned runner script. The first run downloads n8n and verifies the v0.1.6 runner against its SHA-256; subsequent runs reuse the local cache. Execution uses a loopback-only container with read-only input mounts, and writes `results/report.json` and `results/junit.xml`. Requires Docker with Linux containers and a shell on Linux, macOS, or WSL2. Your workflow and fixture files stay local.
+
+Exported JSON pins can prefill the input and expected items. The builder lists the nodes in the slice and identifies missing fixtures, HTTP mock contracts, and structural dependencies before you install a runtime. File contents stay in your browser tab; review the snapshots against the behavior you want to preserve. A completed case runs with the released **v0.1.7** CLI or Action. Select **Full JSON items** for a complete snapshot, **Selected field + item count** for stable IDs with changing timestamps, or **Item count** for output volume. Field paths start at the n8n item, such as `json.id`; expected values preserve order and duplicates.
 
 For a local-first example, choose **Try the nine-row example**. Its synthetic pins create a case that passes with the fixed workflow and catches the obsolete filter in the broken workflow. The page prepares files; the n8n engine produces the execution results.
 
@@ -56,6 +58,8 @@ Each case checks request counts, bodies, and final outputs with the actual engin
 
 **[Replay invoice-history checks against real Data Tables](examples/morsof-invoice-history/):** seven batch cases from Morsof’s invoice follow-up template, plus a second execution that preserves stored IDs and preparation timestamps. Includes a version-pinned Data Table CLI adapter.
 
+**[Check a Vapi tool-call response before a client demo](examples/vapi-tool-contract/):** two tool calls, two distinct result IDs. Run successful, empty, and backend-503 responses through the real n8n engine; the same contract catches a mislabelled tool result. Includes a fork-and-run Action with synthetic API responses.
+
 ## Add a check to GitHub Actions
 
 **One workflow file. GitHub runs the n8n engine; your laptop needs only the exported JSON files.**
@@ -75,7 +79,7 @@ jobs:
       - uses: actions/checkout@v7
         with:
           persist-credentials: false
-      - uses: blucca/n8n-check@v0.1.6
+      - uses: blucca/n8n-check@v0.1.7
         with:
           workflow: workflows/render.json
           case: tests/render.case.json
@@ -103,7 +107,7 @@ Replace `workflow` and `case` with paths in your repository. The action builds t
 Set `n8n-version` to an exact official image release:
 
 ```yaml
-      - uses: blucca/n8n-check@v0.1.6
+      - uses: blucca/n8n-check@v0.1.7
         with:
           n8n-version: '2.38.4'
           workflow: workflows/render.json
@@ -120,7 +124,7 @@ For local Docker runs, use `docker build --build-arg N8N_VERSION=2.38.4 -t n8n-c
 With Git and Docker installed:
 
 ```sh
-git clone --branch v0.1.6 https://github.com/blucca/n8n-check.git
+git clone --branch v0.1.7 https://github.com/blucca/n8n-check.git
 cd n8n-check
 docker build -t n8n-check .
 
@@ -148,12 +152,12 @@ The complete change in `Render.parameters.jsonBody`:
 
 Both example inputs use an object for `styling`. The broken expression converts that object to `[object Object]`; the fixed expression preserves the object. The workflow export remains unchanged on disk.
 
-## Install the CLI from GitHub
+## Install the CLI from npm
 
 Node.js 24+ and an installed n8n CLI are required for this route. The runner has zero npm dependencies; n8n is installed separately under its own license.
 
 ```sh
-npm install --global https://github.com/blucca/n8n-check/releases/download/v0.1.6/blucca-n8n-check-0.1.6.tgz
+npm install --global @blucca/n8n-check
 n8n-check --help
 
 # Trusted local development, using your existing n8n installation:
@@ -163,7 +167,7 @@ n8n-check workflow.json case.json --allow-network --out results
 n8n-check workflow.json case.json --n8n /path/to/n8n --allow-network
 ```
 
-The GitHub release package works independently of npm registry availability. Docker is the simplest route to a pinned runtime and loopback-only networking. Default runtime: **n8n 2.41.7**; local CLI installation: Node.js **24+**. The [version matrix](examples/version-matrix/) also exercises 2.38.4, and the JSON request/output case passes on 2.37.9. The CLI uses the official [workflow import and execute commands](https://docs.n8n.io/hosting/cli-commands/).
+The official package is [@blucca/n8n-check on npm](https://www.npmjs.com/package/@blucca/n8n-check). For a reproducible CLI install, use `npm install --global @blucca/n8n-check@0.1.7`. A standalone `.tgz` is also available in the [GitHub release](https://github.com/blucca/n8n-check/releases/tag/v0.1.7). Docker is the simplest route to a pinned runtime and loopback-only networking. Default runtime: **n8n 2.41.7**; local CLI installation: Node.js **24+**. The [version matrix](examples/version-matrix/) also exercises 2.38.4, and the JSON request/output case passes on 2.37.9. The CLI uses the official [workflow import and execute commands](https://docs.n8n.io/hosting/cli-commands/).
 
 ## Your first case
 
@@ -174,7 +178,7 @@ For your own export, replace **all three node-name fields** below: `input.node`
 Save the JSON below as `case.json`. If you installed the CLI globally, download the example workflow into the same directory, then run:
 
 ```sh
-curl --fail --location https://raw.githubusercontent.com/blucca/n8n-check/v0.1.6/examples/object-body/fixed.json \
+curl --fail --location https://raw.githubusercontent.com/blucca/n8n-check/v0.1.7/examples/object-body/fixed.json \
   --output first-case.workflow.json
 n8n-check first-case.workflow.json case.json --allow-network --out results/first-case
 ```

package/examples/vapi-tool-contract/README.md

@@ -0,0 +1,67 @@
+# Vapi tool calls: preserve the caller, surface the backend failure
+
+**Two tool calls in one request. Two different customers. Every response keeps its own `toolCallId`.**
+
+This synthetic backend check looks up customer orders through a real n8n HTTP Request node. It checks outgoing customer/ID pairs, response serialization, and the complete Vapi `results` envelope.
+
+| Scenario | Backend responses | Expected tool response |
+| --- | --- | --- |
+| `success` | Two HTTP 200 responses with different orders | Two distinct IDs and the correct serialized order data |
+| `backend-503` | Customer A succeeds; customer B returns 503 | A retains its result; B receives an explicit `error` string |
+| `empty-orders` | Customer B returns `{"orders":[]}` | B receives the successful string `"{\"orders\":[]}"` |
+| `wrong-id.json` with the unchanged success case | Both backend requests succeed | **FAIL**: the second result incorrectly repeats the first tool-call ID |
+
+## The workflow
+
+`Vapi webhook → Split tool calls → Lookup orders → Build Vapi response → Respond to Vapi`
+
+- [`workflow.json`](workflow.json) is an importable synthetic workflow with a Webhook input and Respond to Webhook configured for HTTP 200.
+- Each case injects the Webhook node's `body.message` JSON and stops after **Build Vapi response**. The real Split, HTTP Request, and response-building nodes execute; the fixture replaces webhook delivery and the response node sits beyond this test boundary.
+- HTTP Request uses **Include Response Headers and Status** and **Never Error** to preserve the backend's status for response mapping. Local HTTP mocks return the declared 200/503 responses.
+- Response construction follows n8n item pairing back to each split tool call. Each route checks exactly one request and its exact customer/`toolCallId` body.
+- Success uses `JSON.stringify` for a single-line `result`. HTTP 503 maps to `error`, preserving the sibling success. Empty order data stays an explicit successful result.
+
+## Run from your browser
+
+1. [Fork n8n-check](https://github.com/blucca/n8n-check/fork), then enable **Actions** in your fork.
+2. Open **Try a Vapi tool-call contract → Run workflow**.
+3. Choose `backend-503` with `workflow` to check a successful result beside an explicit tool error. Choose `success` with `wrong-id` to see the regression turn the job red.
+4. Read the check summary; download `vapi-tool-contract-results` for JSON/JUnit.
+
+This Action runs the selected case with the released **v0.1.7** runner and **n8n 2.41.7**, using loopback-only Docker networking and synthetic data. GitHub Actions usage follows your account plan. [Action source](../../.github/workflows/try-vapi-tool-contract.yml).
+
+## Run with real n8n
+
+From the repository root, with Node.js 24+ and n8n installed:
+
+```sh
+# Optional: select an existing installation.
+# export N8N_BINARY=/absolute/path/to/n8n
+for scenario in success backend-503 empty-orders; do
+  node bin/n8n-check.mjs examples/vapi-tool-contract/workflow.json \
+    "examples/vapi-tool-contract/$scenario.case.json" \
+    --allow-network --out "temp/vapi-tool-contract/$scenario" || exit $?
+done
+
+# Negative control: expect exit 1 and a failed Build Vapi response assertion.
+node bin/n8n-check.mjs examples/vapi-tool-contract/wrong-id.json \
+  examples/vapi-tool-contract/success.case.json \
+  --allow-network --out temp/vapi-tool-contract/wrong-id
+```
+
+The bundled source and fixtures use synthetic values. The local command enables host networking; the runner redirects both HTTP routes to its loopback mock. Use the repository's [Docker route](../../README.md#try-a-failure-then-its-fix) for an isolated runtime. Run local CLI cases sequentially: n8n's task broker uses a shared default port.
+
+Recorded execution: **n8n 2.41.7, n8n-check 0.1.6**, three passing cases, each with eight checks and two HTTP requests. The wrong-ID control retains successful execution and both correct backend requests while failing the output assertion. [`observed-results.json`](observed-results.json) contains compact check results, mock traces, and the actual emitted envelopes.
+
+**[Completed GitHub Actions run](https://github.com/blucca/n8n-check/actions/runs/37558788945):** `backend-503`, 8/8 checks, two HTTP requests, loopback-only networking. The result preserves customer A’s order and returns customer B’s tool error.
+
+## Verified Vapi contract and scope
+
+Official references, read 2026-10-07:
+
+- [Custom tools — request and response format](https://docs.vapi.ai/tools/custom-tools): `message.toolCallList[].function.name` and object-valued `function.arguments`; `results[]` associates each response with `toolCallId`; `result` and `error` are single-line strings. Each entry uses one of those fields. Multiple results may appear in any order. The server returns HTTP 200 for successful and tool-error envelopes.
+- [Server URL events — tool calls](https://docs.vapi.ai/server-url/events): documents tool-call delivery and response correlation. Its introductory flattened `name`/`parameters` example is a separate input shape; this fixture follows the custom-tools function/arguments example above.
+
+This pack covers one tool, `lookupOrders`, a non-empty batch with unique call IDs, object-valued arguments, synthetic customer IDs, and backend HTTP responses containing JSON. The assertions preserve this sample's response order as well as the Vapi ID mapping. HTTP error handling here covers returned statuses; transport timeouts/DNS errors, malformed tool arguments, webhook authentication/delivery, and actual HTTP 200 response delivery require additional integration cases. The sample's Webhook response configuration is supplied for importing and subsequent endpoint testing.
+
+Voice/audio, Twilio delivery, ElevenLabs speech, model decisions, live Vapi acceptance, and production credentials are separate live-agent acceptance work. A buyer's export, tool schema, example call trace, and agreed behavior provide the next test inputs.

package/examples/vapi-tool-contract/backend-503.case.json

@@ -0,0 +1,113 @@
+{
+  "version": 1,
+  "name": "Vapi tool contract: backend-503",
+  "input": {
+    "node": "Vapi webhook",
+    "items": [
+      {
+        "body": {
+          "message": {
+            "type": "tool-calls",
+            "toolCallList": [
+              {
+                "id": "call-order-A",
+                "type": "function",
+                "function": {
+                  "name": "lookupOrders",
+                  "arguments": {
+                    "customerId": "customer-A"
+                  }
+                }
+              },
+              {
+                "id": "call-order-B",
+                "type": "function",
+                "function": {
+                  "name": "lookupOrders",
+                  "arguments": {
+                    "customerId": "customer-B"
+                  }
+                }
+              }
+            ]
+          }
+        }
+      }
+    ]
+  },
+  "stopAfter": "Build Vapi response",
+  "mocks": [
+    {
+      "node": "Lookup orders",
+      "url": "/lookup/{{ $json.customerId }}",
+      "routes": [
+        {
+          "method": "POST",
+          "path": "/lookup/customer-A",
+          "responses": [
+            {
+              "status": 200,
+              "json": {
+                "orders": [
+                  {
+                    "id": "order-A-101",
+                    "status": "shipped"
+                  }
+                ]
+              }
+            }
+          ],
+          "expect": {
+            "count": 1,
+            "bodies": [
+              {
+                "customerId": "customer-A",
+                "toolCallId": "call-order-A"
+              }
+            ]
+          }
+        },
+        {
+          "method": "POST",
+          "path": "/lookup/customer-B",
+          "responses": [
+            {
+              "status": 503,
+              "json": {
+                "message": "upstream overloaded"
+              }
+            }
+          ],
+          "expect": {
+            "count": 1,
+            "bodies": [
+              {
+                "customerId": "customer-B",
+                "toolCallId": "call-order-B"
+              }
+            ]
+          }
+        }
+      ]
+    }
+  ],
+  "assertions": [
+    {
+      "node": "Build Vapi response",
+      "equals": [
+        {
+          "results": [
+            {
+              "toolCallId": "call-order-A",
+              "result": "{\"orders\":[{\"id\":\"order-A-101\",\"status\":\"shipped\"}]}"
+            },
+            {
+              "toolCallId": "call-order-B",
+              "error": "Order service temporarily unavailable. Please try again later."
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}

package/examples/vapi-tool-contract/empty-orders.case.json

@@ -0,0 +1,113 @@
+{
+  "version": 1,
+  "name": "Vapi tool contract: empty-orders",
+  "input": {
+    "node": "Vapi webhook",
+    "items": [
+      {
+        "body": {
+          "message": {
+            "type": "tool-calls",
+            "toolCallList": [
+              {
+                "id": "call-order-A",
+                "type": "function",
+                "function": {
+                  "name": "lookupOrders",
+                  "arguments": {
+                    "customerId": "customer-A"
+                  }
+                }
+              },
+              {
+                "id": "call-order-B",
+                "type": "function",
+                "function": {
+                  "name": "lookupOrders",
+                  "arguments": {
+                    "customerId": "customer-B"
+                  }
+                }
+              }
+            ]
+          }
+        }
+      }
+    ]
+  },
+  "stopAfter": "Build Vapi response",
+  "mocks": [
+    {
+      "node": "Lookup orders",
+      "url": "/lookup/{{ $json.customerId }}",
+      "routes": [
+        {
+          "method": "POST",
+          "path": "/lookup/customer-A",
+          "responses": [
+            {
+              "status": 200,
+              "json": {
+                "orders": [
+                  {
+                    "id": "order-A-101",
+                    "status": "shipped"
+                  }
+                ]
+              }
+            }
+          ],
+          "expect": {
+            "count": 1,
+            "bodies": [
+              {
+                "customerId": "customer-A",
+                "toolCallId": "call-order-A"
+              }
+            ]
+          }
+        },
+        {
+          "method": "POST",
+          "path": "/lookup/customer-B",
+          "responses": [
+            {
+              "status": 200,
+              "json": {
+                "orders": []
+              }
+            }
+          ],
+          "expect": {
+            "count": 1,
+            "bodies": [
+              {
+                "customerId": "customer-B",
+                "toolCallId": "call-order-B"
+              }
+            ]
+          }
+        }
+      ]
+    }
+  ],
+  "assertions": [
+    {
+      "node": "Build Vapi response",
+      "equals": [
+        {
+          "results": [
+            {
+              "toolCallId": "call-order-A",
+              "result": "{\"orders\":[{\"id\":\"order-A-101\",\"status\":\"shipped\"}]}"
+            },
+            {
+              "toolCallId": "call-order-B",
+              "result": "{\"orders\":[]}"
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}

package/examples/vapi-tool-contract/observed-results.json

@@ -0,0 +1,234 @@
+{
+  "n8nVersion": "2.41.7",
+  "runnerVersion": "0.1.6",
+  "networkMode": "host-network",
+  "boundary": "Fixture at Vapi webhook; real Split tool calls, Lookup orders HTTP Request and Build Vapi response; stop before Respond to Vapi. Local synthetic HTTP mocks.",
+  "runs": [
+    {
+      "scenario": "success",
+      "workflow": "workflow.json",
+      "case": "success.case.json",
+      "startedAt": "2026-10-07T01:44:22.166Z",
+      "status": "passed",
+      "exitCode": 0,
+      "checksPassed": 8,
+      "checksTotal": 8,
+      "failedChecks": [],
+      "requests": [
+        {
+          "node": "Lookup orders",
+          "method": "POST",
+          "path": "/lookup/customer-A",
+          "body": {
+            "customerId": "customer-A",
+            "toolCallId": "call-order-A"
+          },
+          "status": 200
+        },
+        {
+          "node": "Lookup orders",
+          "method": "POST",
+          "path": "/lookup/customer-B",
+          "body": {
+            "customerId": "customer-B",
+            "toolCallId": "call-order-B"
+          },
+          "status": 200
+        }
+      ],
+      "actualResponse": {
+        "results": [
+          {
+            "toolCallId": "call-order-A",
+            "result": "{\"orders\":[{\"id\":\"order-A-101\",\"status\":\"shipped\"}]}"
+          },
+          {
+            "toolCallId": "call-order-B",
+            "result": "{\"orders\":[{\"id\":\"order-B-202\",\"status\":\"processing\"}]}"
+          }
+        ]
+      }
+    },
+    {
+      "scenario": "backend-503",
+      "workflow": "workflow.json",
+      "case": "backend-503.case.json",
+      "startedAt": "2026-10-07T01:44:47.031Z",
+      "status": "passed",
+      "exitCode": 0,
+      "checksPassed": 8,
+      "checksTotal": 8,
+      "failedChecks": [],
+      "requests": [
+        {
+          "node": "Lookup orders",
+          "method": "POST",
+          "path": "/lookup/customer-A",
+          "body": {
+            "customerId": "customer-A",
+            "toolCallId": "call-order-A"
+          },
+          "status": 200
+        },
+        {
+          "node": "Lookup orders",
+          "method": "POST",
+          "path": "/lookup/customer-B",
+          "body": {
+            "customerId": "customer-B",
+            "toolCallId": "call-order-B"
+          },
+          "status": 503
+        }
+      ],
+      "actualResponse": {
+        "results": [
+          {
+            "toolCallId": "call-order-A",
+            "result": "{\"orders\":[{\"id\":\"order-A-101\",\"status\":\"shipped\"}]}"
+          },
+          {
+            "toolCallId": "call-order-B",
+            "error": "Order service temporarily unavailable. Please try again later."
+          }
+        ]
+      }
+    },
+    {
+      "scenario": "empty-orders",
+      "workflow": "workflow.json",
+      "case": "empty-orders.case.json",
+      "startedAt": "2026-10-07T01:44:29.107Z",
+      "status": "passed",
+      "exitCode": 0,
+      "checksPassed": 8,
+      "checksTotal": 8,
+      "failedChecks": [],
+      "requests": [
+        {
+          "node": "Lookup orders",
+          "method": "POST",
+          "path": "/lookup/customer-A",
+          "body": {
+            "customerId": "customer-A",
+            "toolCallId": "call-order-A"
+          },
+          "status": 200
+        },
+        {
+          "node": "Lookup orders",
+          "method": "POST",
+          "path": "/lookup/customer-B",
+          "body": {
+            "customerId": "customer-B",
+            "toolCallId": "call-order-B"
+          },
+          "status": 200
+        }
+      ],
+      "actualResponse": {
+        "results": [
+          {
+            "toolCallId": "call-order-A",
+            "result": "{\"orders\":[{\"id\":\"order-A-101\",\"status\":\"shipped\"}]}"
+          },
+          {
+            "toolCallId": "call-order-B",
+            "result": "{\"orders\":[]}"
+          }
+        ]
+      }
+    },
+    {
+      "scenario": "wrong-id",
+      "workflow": "wrong-id.json",
+      "case": "success.case.json",
+      "startedAt": "2026-10-07T01:44:56.484Z",
+      "status": "failed",
+      "exitCode": 1,
+      "checksPassed": 7,
+      "checksTotal": 8,
+      "failedChecks": [
+        {
+          "name": "Build Vapi response: output 0",
+          "passed": false,
+          "expected": [
+            {
+              "results": [
+                {
+                  "toolCallId": "call-order-A",
+                  "result": "{\"orders\":[{\"id\":\"order-A-101\",\"status\":\"shipped\"}]}"
+                },
+                {
+                  "toolCallId": "call-order-B",
+                  "result": "{\"orders\":[{\"id\":\"order-B-202\",\"status\":\"processing\"}]}"
+                }
+              ]
+            }
+          ],
+          "actual": [
+            {
+              "results": [
+                {
+                  "toolCallId": "call-order-A",
+                  "result": "{\"orders\":[{\"id\":\"order-A-101\",\"status\":\"shipped\"}]}"
+                },
+                {
+                  "toolCallId": "call-order-A",
+                  "result": "{\"orders\":[{\"id\":\"order-B-202\",\"status\":\"processing\"}]}"
+                }
+              ]
+            }
+          ]
+        }
+      ],
+      "requests": [
+        {
+          "node": "Lookup orders",
+          "method": "POST",
+          "path": "/lookup/customer-A",
+          "body": {
+            "customerId": "customer-A",
+            "toolCallId": "call-order-A"
+          },
+          "status": 200
+        },
+        {
+          "node": "Lookup orders",
+          "method": "POST",
+          "path": "/lookup/customer-B",
+          "body": {
+            "customerId": "customer-B",
+            "toolCallId": "call-order-B"
+          },
+          "status": 200
+        }
+      ],
+      "actualResponse": {
+        "results": [
+          {
+            "toolCallId": "call-order-A",
+            "result": "{\"orders\":[{\"id\":\"order-A-101\",\"status\":\"shipped\"}]}"
+          },
+          {
+            "toolCallId": "call-order-A",
+            "result": "{\"orders\":[{\"id\":\"order-B-202\",\"status\":\"processing\"}]}"
+          }
+        ]
+      }
+    }
+  ],
+  "ci": {
+    "url": "https://github.com/blucca/n8n-check/actions/runs/37558788945",
+    "sourceCommit": "fe78330",
+    "scenario": "backend-503",
+    "workflow": "workflow.json",
+    "n8nVersion": "2.41.7",
+    "runnerVersion": "0.1.6",
+    "networkMode": "loopback-only",
+    "checksPassed": 8,
+    "checksTotal": 8,
+    "requests": 2,
+    "exitCode": 0
+  }
+}

package/examples/vapi-tool-contract/success.case.json

@@ -0,0 +1,118 @@
+{
+  "version": 1,
+  "name": "Vapi tool contract: success",
+  "input": {
+    "node": "Vapi webhook",
+    "items": [
+      {
+        "body": {
+          "message": {
+            "type": "tool-calls",
+            "toolCallList": [
+              {
+                "id": "call-order-A",
+                "type": "function",
+                "function": {
+                  "name": "lookupOrders",
+                  "arguments": {
+                    "customerId": "customer-A"
+                  }
+                }
+              },
+              {
+                "id": "call-order-B",
+                "type": "function",
+                "function": {
+                  "name": "lookupOrders",
+                  "arguments": {
+                    "customerId": "customer-B"
+                  }
+                }
+              }
+            ]
+          }
+        }
+      }
+    ]
+  },
+  "stopAfter": "Build Vapi response",
+  "mocks": [
+    {
+      "node": "Lookup orders",
+      "url": "/lookup/{{ $json.customerId }}",
+      "routes": [
+        {
+          "method": "POST",
+          "path": "/lookup/customer-A",
+          "responses": [
+            {
+              "status": 200,
+              "json": {
+                "orders": [
+                  {
+                    "id": "order-A-101",
+                    "status": "shipped"
+                  }
+                ]
+              }
+            }
+          ],
+          "expect": {
+            "count": 1,
+            "bodies": [
+              {
+                "customerId": "customer-A",
+                "toolCallId": "call-order-A"
+              }
+            ]
+          }
+        },
+        {
+          "method": "POST",
+          "path": "/lookup/customer-B",
+          "responses": [
+            {
+              "status": 200,
+              "json": {
+                "orders": [
+                  {
+                    "id": "order-B-202",
+                    "status": "processing"
+                  }
+                ]
+              }
+            }
+          ],
+          "expect": {
+            "count": 1,
+            "bodies": [
+              {
+                "customerId": "customer-B",
+                "toolCallId": "call-order-B"
+              }
+            ]
+          }
+        }
+      ]
+    }
+  ],
+  "assertions": [
+    {
+      "node": "Build Vapi response",
+      "equals": [
+        {
+          "results": [
+            {
+              "toolCallId": "call-order-A",
+              "result": "{\"orders\":[{\"id\":\"order-A-101\",\"status\":\"shipped\"}]}"
+            },
+            {
+              "toolCallId": "call-order-B",
+              "result": "{\"orders\":[{\"id\":\"order-B-202\",\"status\":\"processing\"}]}"
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}

package/examples/vapi-tool-contract/workflow.json

@@ -0,0 +1,143 @@
+{
+  "name": "Vapi tool-call contract \u2014 synthetic order lookup",
+  "nodes": [
+    {
+      "id": "vapi-webhook",
+      "name": "Vapi webhook",
+      "type": "n8n-nodes-base.webhook",
+      "typeVersion": 2.1,
+      "position": [
+        0,
+        0
+      ],
+      "parameters": {
+        "httpMethod": "POST",
+        "path": "vapi-tool-contract",
+        "responseMode": "responseNode",
+        "options": {}
+      }
+    },
+    {
+      "id": "split-tool-calls",
+      "name": "Split tool calls",
+      "type": "n8n-nodes-base.code",
+      "typeVersion": 2,
+      "position": [
+        220,
+        0
+      ],
+      "parameters": {
+        "mode": "runOnceForAllItems",
+        "jsCode": "const message = $input.first().json.body.message;\nif (message.type !== 'tool-calls' || !Array.isArray(message.toolCallList) || !message.toolCallList.length) throw new Error('Expected a non-empty tool-calls message');\nconst seen = new Set();\nreturn message.toolCallList.map(call => {\n  if (typeof call.id !== 'string' || !call.id || seen.has(call.id)) throw new Error('Each tool call needs a unique ID');\n  seen.add(call.id);\n  if (call.function?.name !== 'lookupOrders' || typeof call.function.arguments?.customerId !== 'string' || !/^[a-zA-Z0-9-]+$/.test(call.function.arguments.customerId)) throw new Error('Expected lookupOrders with a customerId');\n  return {json: {toolCallId: call.id, customerId: call.function.arguments.customerId}, pairedItem: {item: 0}};\n});"
+      }
+    },
+    {
+      "id": "lookup-orders",
+      "name": "Lookup orders",
+      "type": "n8n-nodes-base.httpRequest",
+      "typeVersion": 4.2,
+      "position": [
+        440,
+        0
+      ],
+      "parameters": {
+        "method": "POST",
+        "url": "=https://orders.example.invalid/lookup/{{ $json.customerId }}",
+        "sendBody": true,
+        "specifyBody": "json",
+        "jsonBody": "={{ {customerId: $json.customerId, toolCallId: $json.toolCallId} }}",
+        "options": {
+          "timeout": 5000,
+          "response": {
+            "response": {
+              "fullResponse": true,
+              "neverError": true,
+              "responseFormat": "json"
+            }
+          }
+        }
+      }
+    },
+    {
+      "id": "build-vapi-response",
+      "name": "Build Vapi response",
+      "type": "n8n-nodes-base.code",
+      "typeVersion": 2,
+      "position": [
+        660,
+        0
+      ],
+      "parameters": {
+        "mode": "runOnceForAllItems",
+        "jsCode": "const results = $input.all().map((item, index) => {\n  const { toolCallId } = $('Split tool calls').itemMatching(index).json;\n  if (item.json.statusCode === 503) return {toolCallId, error: 'Order service temporarily unavailable. Please try again later.'};\n  if (item.json.statusCode !== 200) return {toolCallId, error: 'Order lookup failed.'};\n  if (!Array.isArray(item.json.body?.orders)) return {toolCallId, error: 'Order service returned an invalid response.'};\n  return {toolCallId, result: JSON.stringify({orders: item.json.body.orders})};\n});\nreturn [{json: {results}}];"
+      }
+    },
+    {
+      "id": "respond-to-vapi",
+      "name": "Respond to Vapi",
+      "type": "n8n-nodes-base.respondToWebhook",
+      "typeVersion": 1.4,
+      "position": [
+        880,
+        0
+      ],
+      "parameters": {
+        "respondWith": "json",
+        "responseBody": "={{ $json }}",
+        "options": {
+          "responseCode": 200
+        }
+      }
+    }
+  ],
+  "connections": {
+    "Vapi webhook": {
+      "main": [
+        [
+          {
+            "node": "Split tool calls",
+            "type": "main",
+            "index": 0
+          }
+        ]
+      ]
+    },
+    "Split tool calls": {
+      "main": [
+        [
+          {
+            "node": "Lookup orders",
+            "type": "main",
+            "index": 0
+          }
+        ]
+      ]
+    },
+    "Lookup orders": {
+      "main": [
+        [
+          {
+            "node": "Build Vapi response",
+            "type": "main",
+            "index": 0
+          }
+        ]
+      ]
+    },
+    "Build Vapi response": {
+      "main": [
+        [
+          {
+            "node": "Respond to Vapi",
+            "type": "main",
+            "index": 0
+          }
+        ]
+      ]
+    }
+  },
+  "settings": {
+    "executionOrder": "v1"
+  },
+  "active": false
+}

package/examples/vapi-tool-contract/wrong-id.json

@@ -0,0 +1,143 @@
+{
+  "name": "Vapi tool-call contract \u2014 synthetic order lookup \u2014 wrong ID control",
+  "nodes": [
+    {
+      "id": "vapi-webhook",
+      "name": "Vapi webhook",
+      "type": "n8n-nodes-base.webhook",
+      "typeVersion": 2.1,
+      "position": [
+        0,
+        0
+      ],
+      "parameters": {
+        "httpMethod": "POST",
+        "path": "vapi-tool-contract",
+        "responseMode": "responseNode",
+        "options": {}
+      }
+    },
+    {
+      "id": "split-tool-calls",
+      "name": "Split tool calls",
+      "type": "n8n-nodes-base.code",
+      "typeVersion": 2,
+      "position": [
+        220,
+        0
+      ],
+      "parameters": {
+        "mode": "runOnceForAllItems",
+        "jsCode": "const message = $input.first().json.body.message;\nif (message.type !== 'tool-calls' || !Array.isArray(message.toolCallList) || !message.toolCallList.length) throw new Error('Expected a non-empty tool-calls message');\nconst seen = new Set();\nreturn message.toolCallList.map(call => {\n  if (typeof call.id !== 'string' || !call.id || seen.has(call.id)) throw new Error('Each tool call needs a unique ID');\n  seen.add(call.id);\n  if (call.function?.name !== 'lookupOrders' || typeof call.function.arguments?.customerId !== 'string' || !/^[a-zA-Z0-9-]+$/.test(call.function.arguments.customerId)) throw new Error('Expected lookupOrders with a customerId');\n  return {json: {toolCallId: call.id, customerId: call.function.arguments.customerId}, pairedItem: {item: 0}};\n});"
+      }
+    },
+    {
+      "id": "lookup-orders",
+      "name": "Lookup orders",
+      "type": "n8n-nodes-base.httpRequest",
+      "typeVersion": 4.2,
+      "position": [
+        440,
+        0
+      ],
+      "parameters": {
+        "method": "POST",
+        "url": "=https://orders.example.invalid/lookup/{{ $json.customerId }}",
+        "sendBody": true,
+        "specifyBody": "json",
+        "jsonBody": "={{ {customerId: $json.customerId, toolCallId: $json.toolCallId} }}",
+        "options": {
+          "timeout": 5000,
+          "response": {
+            "response": {
+              "fullResponse": true,
+              "neverError": true,
+              "responseFormat": "json"
+            }
+          }
+        }
+      }
+    },
+    {
+      "id": "build-vapi-response",
+      "name": "Build Vapi response",
+      "type": "n8n-nodes-base.code",
+      "typeVersion": 2,
+      "position": [
+        660,
+        0
+      ],
+      "parameters": {
+        "mode": "runOnceForAllItems",
+        "jsCode": "const results = $input.all().map((item, index) => {\n  const { toolCallId } = $('Split tool calls').itemMatching(index).json;\n  if (item.json.statusCode === 503) return {toolCallId, error: 'Order service temporarily unavailable. Please try again later.'};\n  if (item.json.statusCode !== 200) return {toolCallId, error: 'Order lookup failed.'};\n  if (!Array.isArray(item.json.body?.orders)) return {toolCallId, error: 'Order service returned an invalid response.'};\n  return {toolCallId, result: JSON.stringify({orders: item.json.body.orders})};\n});\nresults[1].toolCallId = results[0].toolCallId;\nreturn [{json: {results}}];"
+      }
+    },
+    {
+      "id": "respond-to-vapi",
+      "name": "Respond to Vapi",
+      "type": "n8n-nodes-base.respondToWebhook",
+      "typeVersion": 1.4,
+      "position": [
+        880,
+        0
+      ],
+      "parameters": {
+        "respondWith": "json",
+        "responseBody": "={{ $json }}",
+        "options": {
+          "responseCode": 200
+        }
+      }
+    }
+  ],
+  "connections": {
+    "Vapi webhook": {
+      "main": [
+        [
+          {
+            "node": "Split tool calls",
+            "type": "main",
+            "index": 0
+          }
+        ]
+      ]
+    },
+    "Split tool calls": {
+      "main": [
+        [
+          {
+            "node": "Lookup orders",
+            "type": "main",
+            "index": 0
+          }
+        ]
+      ]
+    },
+    "Lookup orders": {
+      "main": [
+        [
+          {
+            "node": "Build Vapi response",
+            "type": "main",
+            "index": 0
+          }
+        ]
+      ]
+    },
+    "Build Vapi response": {
+      "main": [
+        [
+          {
+            "node": "Respond to Vapi",
+            "type": "main",
+            "index": 0
+          }
+        ]
+      ]
+    }
+  },
+  "settings": {
+    "executionOrder": "v1"
+  },
+  "active": false
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blucca/n8n-check",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "Run n8n workflow regression checks with fixtures, local HTTP mocks and JUnit reports.",
   "type": "module",
   "bin": {

package/src/local-bundle.mjs

@@ -0,0 +1,154 @@
+// Portable browser module: UTF-8, uncompressed ZIP; no network or dependencies.
+export const RUNNER_URL = 'https://github.com/blucca/n8n-check/releases/download/v0.1.6/blucca-n8n-check-0.1.6.tgz';
+export const RUNNER_SHA256 = '8ac4b07df6fc6eb83726793137e5ad3eb7e97f5bcca243a97cc6c82e6a5ed53d';
+const versionPattern = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z]+(?:[.-][0-9A-Za-z]+)*)?$/;
+
+export function localBundleFiles({ workflow, caseFile, n8nVersion = '2.41.7' }) {
+  if (typeof n8nVersion !== 'string' || !versionPattern.test(n8nVersion)) throw new Error('Choose an exact n8n release, such as 2.41.7.');
+  for (const [name, value] of Object.entries({ workflow, caseFile })) {
+    if (!value || typeof value !== 'object') throw new Error(`${name}: supply a JSON object.`);
+  }
+  return {
+    'workflow.json': JSON.stringify(workflow, null, 2) + '\n',
+    'case.json': JSON.stringify(caseFile, null, 2) + '\n',
+    'run.sh': `#!/bin/sh
+set -eu
+# Setup errors return 2; the final runner preserves its 0/1/2 result.
+trap 'code=$?; if [ "$code" -ne 0 ]; then exit 2; fi' 0
+cd -- "$(dirname -- "$0")"
+ROOT=$(pwd -P)
+case "$ROOT" in
+  *','* | *':'* | *'\n'*) echo 'Extract into a directory whose path uses letters, spaces, numbers, dashes or underscores.' >&2; exit 2 ;;
+esac
+mkdir -p .cache results
+rm -f results/report.json results/junit.xml
+N8N_VERSION=\${N8N_VERSION:-${n8nVersion}}
+case "$N8N_VERSION" in *'\n'*) echo 'N8N_VERSION: use a single exact release.' >&2; exit 2 ;; esac
+printf '%s\\n' "$N8N_VERSION" | grep -Eq '^(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)(-[0-9A-Za-z]+([.-][0-9A-Za-z]+)*)?$' || {
+  echo 'N8N_VERSION: choose an exact release, such as 2.41.7.' >&2; exit 2;
+}
+command -v docker >/dev/null 2>&1 || { echo 'Install and start Docker, then run sh run.sh again.' >&2; exit 2; }
+[ -f workflow.json ] && [ -f case.json ] || { echo 'Keep workflow.json and case.json beside run.sh.' >&2; exit 2; }
+BASE="ghcr.io/n8n-io/n8n:$N8N_VERSION"
+IMAGE="n8n-check-local:0.1.6-$N8N_VERSION"
+# Docker obtains the official image on first use. This bootstrap sees only .cache.
+# Its Node runtime downloads and verifies the fixed runner release on Mac/Linux.
+docker run --rm -i --user "$(id -u):$(id -g)" \\
+  --mount "type=bind,source=$ROOT/.cache,target=/cache" \\
+  --entrypoint node "$BASE" --input-type=module - <<'NODE'
+import { readFile, writeFile, rename } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+const file = '/cache/runner.tgz';
+const expected = '${RUNNER_SHA256}';
+const valid = data => createHash('sha256').update(data).digest('hex') === expected;
+let cached;
+try { cached = await readFile(file); } catch (error) { if (error.code !== 'ENOENT') throw error; }
+if (!cached || !valid(cached)) {
+  console.log('Downloading n8n-check v0.1.6...');
+  const response = await fetch('${RUNNER_URL}', { signal: AbortSignal.timeout(120000) });
+  if (!response.ok) throw new Error('Runner download HTTP ' + response.status);
+  const data = Buffer.from(await response.arrayBuffer());
+  if (!valid(data)) throw new Error('Runner SHA256 mismatch; download stopped.');
+  await writeFile(file + '.partial', data);
+  await rename(file + '.partial', file);
+}
+console.log('Runner SHA256 verified.');
+NODE
+cat > .cache/Dockerfile <<'DOCKERFILE'
+ARG N8N_VERSION
+FROM ghcr.io/n8n-io/n8n:\${N8N_VERSION}
+USER root
+ADD runner.tgz /opt/n8n-check/
+USER node
+WORKDIR /work
+ENTRYPOINT ["node", "/opt/n8n-check/package/bin/n8n-check.mjs"]
+DOCKERFILE
+# Only the verified archive and generated Dockerfile enter the build context.
+printf '*\\n!runner.tgz\\n!Dockerfile\\n' > .cache/.dockerignore
+docker build --network none --build-arg "N8N_VERSION=$N8N_VERSION" --tag "$IMAGE" .cache
+printf '\\nRunning checks with n8n %s; results: %s/results\\n' "$N8N_VERSION" "$ROOT"
+trap - 0
+set +e
+docker run --rm --network none --user "$(id -u):$(id -g)" \\
+  --mount "type=bind,source=$ROOT/workflow.json,target=/inputs/workflow.json,readonly" \\
+  --mount "type=bind,source=$ROOT/case.json,target=/inputs/case.json,readonly" \\
+  --mount "type=bind,source=$ROOT/results,target=/results" \\
+  "$IMAGE" /inputs/workflow.json /inputs/case.json --out /results
+CODE=$?
+case "$CODE" in 0|1|2) exit "$CODE" ;; *) exit 2 ;; esac
+`,
+    'README.md': `# Run your n8n regression check locally
+
+1. Install and start Docker (Docker Desktop on macOS; Docker Engine/Desktop on Linux).
+2. Extract all four files into a dedicated directory.
+3. Open a terminal in that directory and run:
+
+\`\`\`sh
+sh run.sh
+\`\`\`
+
+Selected n8n release: **${n8nVersion}**. To test another exact release:
+
+\`\`\`sh
+N8N_VERSION=2.41.7 sh run.sh
+\`\`\`
+
+The first run downloads the official n8n image and n8n-check v0.1.6. Docker supplies Node. The runner archive stays in .cache and its SHA256 is checked on every run. Subsequent runs reuse Docker layers and the verified archive. An uncached n8n version needs internet access. Choose a published version supported by your workflow's nodes and the runner (Node 24+).
+
+The workflow executes with Docker --network none: HTTP mocks use loopback, and external networking is disabled. workflow.json and case.json are mounted read-only; results/ is writable. Execution uses your local UID/GID and a fresh n8n database. Use trusted workflows and synthetic fixtures; workflow code executes in the container. Inline values and assertion differences can appear in local reports.
+
+Results: results/report.json and results/junit.xml. Exit codes: 0 passed, 1 regression, 2 setup error. Each attempt clears the previous two report files; setup errors appear in the terminal. Save reports before rerunning when comparing versions.
+
+Keep Docker running and allow it access to this directory. Windows users can run the bundle inside WSL with Docker integration. Directory paths may contain spaces; choose paths free of commas, colons and line breaks for Docker bind mounts.
+
+Edit case.json to add fixtures, HTTP contracts or assertions, then rerun the same command. The bundle contains the original workflow export and the case selected in the builder; review their contents before sharing.
+
+Runner: ${RUNNER_URL}
+SHA256: ${RUNNER_SHA256}
+Documentation: https://github.com/blucca/n8n-check
+`,
+  };
+}
+
+function crc32(bytes) {
+  let crc = 0xffffffff;
+  for (const byte of bytes) {
+    crc ^= byte;
+    for (let bit = 0; bit < 8; bit++) crc = (crc >>> 1) ^ ((crc & 1) ? 0xedb88320 : 0);
+  }
+  return (crc ^ 0xffffffff) >>> 0;
+}
+
+export function buildLocalBundle(options) {
+  const encoder = new TextEncoder();
+  const files = Object.entries(localBundleFiles(options)).map(([name, text]) => ({ name: encoder.encode(name), data: encoder.encode(text) }));
+  const size = files.reduce((sum, file) => sum + 30 + file.name.length + file.data.length + 46 + file.name.length, 22);
+  if (size > 0xffffffff) throw new Error('Bundle exceeds the ZIP size limit.');
+  const zip = new Uint8Array(size);
+  const view = new DataView(zip.buffer);
+  let offset = 0;
+  const u16 = (at, value) => view.setUint16(at, value, true);
+  const u32 = (at, value) => view.setUint32(at, value, true);
+  for (const file of files) {
+    file.offset = offset;
+    file.crc = crc32(file.data);
+    u32(offset, 0x04034b50); u16(offset + 4, 20); u16(offset + 6, 0x800);
+    u16(offset + 12, 0x21); // Fixed 1980-01-01, deterministic exports.
+    u32(offset + 14, file.crc); u32(offset + 18, file.data.length); u32(offset + 22, file.data.length);
+    u16(offset + 26, file.name.length);
+    zip.set(file.name, offset + 30); zip.set(file.data, offset + 30 + file.name.length);
+    offset += 30 + file.name.length + file.data.length;
+  }
+  const centralOffset = offset;
+  for (const file of files) {
+    u32(offset, 0x02014b50); u16(offset + 4, 20); u16(offset + 6, 20); u16(offset + 8, 0x800);
+    u16(offset + 14, 0x21); u32(offset + 16, file.crc);
+    u32(offset + 20, file.data.length); u32(offset + 24, file.data.length);
+    u16(offset + 28, file.name.length); u32(offset + 42, file.offset);
+    zip.set(file.name, offset + 46);
+    offset += 46 + file.name.length;
+  }
+  u32(offset, 0x06054b50); u16(offset + 8, files.length); u16(offset + 10, files.length);
+  u32(offset + 12, offset - centralOffset); u32(offset + 16, centralOffset);
+  return zip;
+}