@blucca/n8n-check 0.0.0-stage → 0.1.7

package/examples/version-matrix/observed-results.json

@@ -0,0 +1,307 @@
+{
+  "recordedAt": "2026-10-06T20:17:00Z",
+  "sourceCommit": "77e496f65105d5633374a65f63da990ab76ff4de",
+  "runUrl": "https://github.com/blucca/n8n-check/actions/runs/37524798259",
+  "sourceIssue": "https://github.com/n8n-io/n8n/issues/39395",
+  "inputs": {
+    "examples/propfind-body/workflow.json": "f365021255ae250b287848de1bb14c47ed2a244127957268044643ab956156e8",
+    "examples/propfind-body/case.json": "e37304adb5eacfad5ca773a77510505a8c3c89f1be451854d3b61e63a7029add"
+  },
+  "runs": [
+    {
+      "name": "Issue 39395 - PROPFIND transmits its XML body",
+      "startedAt": "2026-10-06T20:14:31.865Z",
+      "n8nVersion": "2.38.4",
+      "runnerVersion": "0.1.4",
+      "nodeVersion": "v26.7.0",
+      "network": {
+        "mode": "loopback-only",
+        "enforced": true,
+        "interfaces": [
+          "lo"
+        ]
+      },
+      "status": "failed",
+      "exitCode": 1,
+      "checks": [
+        {
+          "name": "n8n execution succeeds",
+          "passed": true,
+          "actual": {
+            "cliExitCode": 0,
+            "lastNode": "HTTP Request",
+            "executionFound": true
+          }
+        },
+        {
+          "name": "HTTP Request: output 0",
+          "passed": true,
+          "expected": [
+            {
+              "received": true
+            }
+          ],
+          "actual": [
+            {
+              "received": true
+            }
+          ]
+        },
+        {
+          "name": "mock: all requests match routes",
+          "passed": true,
+          "actual": []
+        },
+        {
+          "name": "mock: request limits and server",
+          "passed": true,
+          "actual": []
+        },
+        {
+          "name": "HTTP Request: PROPFIND /dav request count",
+          "passed": true,
+          "expected": 1,
+          "actual": 1
+        },
+        {
+          "name": "HTTP Request: PROPFIND /dav request bodies",
+          "passed": false,
+          "expected": [
+            "<?xml version=\"1.0\"?>\n<invalid>\n<d:propfind xmlns:d=\"DAV:\" xmlns:oc=\"http://owncloud.org/ns\" xmlns:nc=\"http://nextcloud.org/ns\">\n    <d:prop>\n        <d:creationdate />\n        <nc:upload_time />\n        <d:getlastmodified />\n        <d:getetag />\n        <d:getcontenttype />\n        <d:resourcetype />\n        <d:quota-used-bytes />\n        <d:quota-available-bytes />\n        <d:displayname />\n        <nc:has-preview />\n        <oc:id />\n        <oc:fileid />\n        <oc:permissions />\n        <oc:size />\n        <oc:favorite />\n        <oc:tags />\n        <oc:comments-unread />\n        <oc:owner-id />\n        <oc:owner-display-name />\n        <oc:share-types />\n    </d:prop>\n</d:propfind>"
+          ],
+          "actual": [
+            null
+          ]
+        }
+      ],
+      "requests": [
+        {
+          "node": "HTTP Request",
+          "method": "PROPFIND",
+          "path": "/dav",
+          "body": null,
+          "matched": true,
+          "status": 200,
+          "response": {
+            "received": true
+          }
+        }
+      ]
+    },
+    {
+      "name": "Issue 39395 - PROPFIND transmits its XML body",
+      "startedAt": "2026-10-06T20:14:26.062Z",
+      "n8nVersion": "2.41.7",
+      "runnerVersion": "0.1.4",
+      "nodeVersion": "v26.7.0",
+      "network": {
+        "mode": "loopback-only",
+        "enforced": true,
+        "interfaces": [
+          "lo"
+        ]
+      },
+      "status": "passed",
+      "exitCode": 0,
+      "checks": [
+        {
+          "name": "n8n execution succeeds",
+          "passed": true,
+          "actual": {
+            "cliExitCode": 0,
+            "lastNode": "HTTP Request",
+            "executionFound": true
+          }
+        },
+        {
+          "name": "HTTP Request: output 0",
+          "passed": true,
+          "expected": [
+            {
+              "received": true
+            }
+          ],
+          "actual": [
+            {
+              "received": true
+            }
+          ]
+        },
+        {
+          "name": "mock: all requests match routes",
+          "passed": true,
+          "actual": []
+        },
+        {
+          "name": "mock: request limits and server",
+          "passed": true,
+          "actual": []
+        },
+        {
+          "name": "HTTP Request: PROPFIND /dav request count",
+          "passed": true,
+          "expected": 1,
+          "actual": 1
+        },
+        {
+          "name": "HTTP Request: PROPFIND /dav request bodies",
+          "passed": true,
+          "expected": [
+            "<?xml version=\"1.0\"?>\n<invalid>\n<d:propfind xmlns:d=\"DAV:\" xmlns:oc=\"http://owncloud.org/ns\" xmlns:nc=\"http://nextcloud.org/ns\">\n    <d:prop>\n        <d:creationdate />\n        <nc:upload_time />\n        <d:getlastmodified />\n        <d:getetag />\n        <d:getcontenttype />\n        <d:resourcetype />\n        <d:quota-used-bytes />\n        <d:quota-available-bytes />\n        <d:displayname />\n        <nc:has-preview />\n        <oc:id />\n        <oc:fileid />\n        <oc:permissions />\n        <oc:size />\n        <oc:favorite />\n        <oc:tags />\n        <oc:comments-unread />\n        <oc:owner-id />\n        <oc:owner-display-name />\n        <oc:share-types />\n    </d:prop>\n</d:propfind>"
+          ],
+          "actual": [
+            "<?xml version=\"1.0\"?>\n<invalid>\n<d:propfind xmlns:d=\"DAV:\" xmlns:oc=\"http://owncloud.org/ns\" xmlns:nc=\"http://nextcloud.org/ns\">\n    <d:prop>\n        <d:creationdate />\n        <nc:upload_time />\n        <d:getlastmodified />\n        <d:getetag />\n        <d:getcontenttype />\n        <d:resourcetype />\n        <d:quota-used-bytes />\n        <d:quota-available-bytes />\n        <d:displayname />\n        <nc:has-preview />\n        <oc:id />\n        <oc:fileid />\n        <oc:permissions />\n        <oc:size />\n        <oc:favorite />\n        <oc:tags />\n        <oc:comments-unread />\n        <oc:owner-id />\n        <oc:owner-display-name />\n        <oc:share-types />\n    </d:prop>\n</d:propfind>"
+          ]
+        }
+      ],
+      "requests": [
+        {
+          "node": "HTTP Request",
+          "method": "PROPFIND",
+          "path": "/dav",
+          "body": "<?xml version=\"1.0\"?>\n<invalid>\n<d:propfind xmlns:d=\"DAV:\" xmlns:oc=\"http://owncloud.org/ns\" xmlns:nc=\"http://nextcloud.org/ns\">\n    <d:prop>\n        <d:creationdate />\n        <nc:upload_time />\n        <d:getlastmodified />\n        <d:getetag />\n        <d:getcontenttype />\n        <d:resourcetype />\n        <d:quota-used-bytes />\n        <d:quota-available-bytes />\n        <d:displayname />\n        <nc:has-preview />\n        <oc:id />\n        <oc:fileid />\n        <oc:permissions />\n        <oc:size />\n        <oc:favorite />\n        <oc:tags />\n        <oc:comments-unread />\n        <oc:owner-id />\n        <oc:owner-display-name />\n        <oc:share-types />\n    </d:prop>\n</d:propfind>",
+          "matched": true,
+          "status": 200,
+          "response": {
+            "received": true
+          }
+        }
+      ]
+    }
+  ],
+  "additionalRuntimeSmoke": {
+    "name": "Two render requests preserve object options",
+    "startedAt": "2026-10-06T20:12:16.116Z",
+    "n8nVersion": "2.37.9",
+    "runnerVersion": "0.1.4",
+    "nodeVersion": "v26.5.1",
+    "network": {
+      "mode": "loopback-only",
+      "enforced": true,
+      "interfaces": [
+        "lo"
+      ]
+    },
+    "status": "passed",
+    "exitCode": 0,
+    "checks": [
+      {
+        "name": "n8n execution succeeds",
+        "passed": true,
+        "actual": {
+          "cliExitCode": 0,
+          "lastNode": "Render",
+          "executionFound": true
+        }
+      },
+      {
+        "name": "Render: output 0",
+        "passed": true,
+        "expected": [
+          {
+            "id": "render-42"
+          },
+          {
+            "id": "render-43"
+          }
+        ],
+        "actual": [
+          {
+            "id": "render-42"
+          },
+          {
+            "id": "render-43"
+          }
+        ]
+      },
+      {
+        "name": "mock: all requests match routes",
+        "passed": true,
+        "actual": []
+      },
+      {
+        "name": "mock: request limits and server",
+        "passed": true,
+        "actual": []
+      },
+      {
+        "name": "Render: POST /renders request count",
+        "passed": true,
+        "expected": 2,
+        "actual": 2
+      },
+      {
+        "name": "Render: POST /renders request bodies",
+        "passed": true,
+        "expected": [
+          {
+            "shortId": 42,
+            "renderOptions": {
+              "color": "#112233",
+              "fontSize": 31
+            }
+          },
+          {
+            "shortId": 43,
+            "renderOptions": {
+              "color": "#aabbcc",
+              "fontSize": 47
+            }
+          }
+        ],
+        "actual": [
+          {
+            "shortId": 42,
+            "renderOptions": {
+              "color": "#112233",
+              "fontSize": 31
+            }
+          },
+          {
+            "shortId": 43,
+            "renderOptions": {
+              "color": "#aabbcc",
+              "fontSize": 47
+            }
+          }
+        ]
+      }
+    ],
+    "requests": [
+      {
+        "node": "Render",
+        "method": "POST",
+        "path": "/renders",
+        "body": {
+          "shortId": 42,
+          "renderOptions": {
+            "color": "#112233",
+            "fontSize": 31
+          }
+        },
+        "matched": true,
+        "status": 200,
+        "response": {
+          "id": "render-42"
+        }
+      },
+      {
+        "node": "Render",
+        "method": "POST",
+        "path": "/renders",
+        "body": {
+          "shortId": 43,
+          "renderOptions": {
+            "color": "#aabbcc",
+            "fontSize": 47
+          }
+        },
+        "matched": true,
+        "status": 200,
+        "response": {
+          "id": "render-43"
+        }
+      }
+    ]
+  }
+}

package/examples/version-matrix/upgrade-check.yml

@@ -0,0 +1,32 @@
+# Save as .github/workflows/n8n-upgrade.yml in your own repository.
+# Replace both releases and both file paths with your project's values.
+name: n8n upgrade contract
+on: [push, pull_request, workflow_dispatch]
+permissions:
+  contents: read
+jobs:
+  contract:
+    name: n8n ${{ matrix.n8n }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        n8n: ['2.38.4', '2.41.7']
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - uses: blucca/n8n-check@v0.1.4
+        with:
+          n8n-version: ${{ matrix.n8n }}
+          workflow: workflows/workflow.json
+          case: tests/workflow.case.json
+          out: results/contract
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: n8n-contract-${{ matrix.n8n }}
+          path: |
+            results/contract/report.json
+            results/contract/junit.xml

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "@blucca/n8n-check",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.7",
+  "description": "Run n8n workflow regression checks with fixtures, local HTTP mocks and JUnit reports.",
+  "type": "module",
+  "bin": {
+    "n8n-check": "bin/n8n-check.mjs"
+  },
+  "exports": "./src/runner.mjs",
+  "files": [
+    "bin",
+    "src",
+    "examples",
+    "Dockerfile",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "license": "MIT",
+  "author": "blucca",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/blucca/n8n-check.git"
+  },
+  "homepage": "https://github.com/blucca/n8n-check#readme",
+  "bugs": "https://github.com/blucca/n8n-check/issues",
+  "keywords": [
+    "n8n",
+    "testing",
+    "workflow",
+    "regression",
+    "junit",
+    "mock"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/action.mjs

@@ -0,0 +1,108 @@
+import { spawnSync } from 'node:child_process';
+import { appendFileSync, existsSync, mkdirSync, readFileSync, realpathSync, rmSync, statSync } from 'node:fs';
+import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { createHash } from 'node:crypto';
+
+const html = value => String(value ?? '').replace(/[&<>"']/g, c => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c]);
+const cell = value => html(value).replace(/\|/g, '&#124;').replace(/[\r\n]+/g, ' ');
+const detail = value => html(JSON.stringify(value, null, 2)?.slice(0, 12000));
+
+export function summary(report) {
+  const checks = report.checks ?? [];
+  const passed = checks.filter(check => check.passed).length;
+  const rows = checks.map(check => `| ${check.passed ? '✅' : '❌'} | ${cell(check.name)} |`);
+  const failures = checks.filter(check => !check.passed).map(check => `<details><summary>${html(check.name)}</summary>\n\nExpected:<pre>${detail(check.expected)}</pre>\nActual:<pre>${detail(check.actual)}</pre>\n</details>`);
+  const requests = (report.requests ?? []).slice(0, 50).map((r, i) => `| ${i + 1} | ${cell(r.node)} | ${cell(r.method)} | ${cell(r.path)} | ${cell(r.status)} |`);
+  return [
+    `## n8n-check: ${cell(report.status).toUpperCase()}`,
+    `**${cell(report.name)}** · ${passed}/${checks.length} checks · ${(report.requests ?? []).length} HTTP requests`,
+    `n8n ${cell(report.n8nVersion ?? 'setup incomplete')} · runner ${cell(report.runnerVersion)} · ${cell(report.network?.mode ?? 'setup incomplete')}`,
+    report.error ? `<pre>${html(report.error)}</pre>` : '',
+    '| Result | Check |\n| --- | --- |\n' + rows.join('\n'),
+    ...failures,
+    requests.length ? '### Request trace\n\n| # | Node | Method | Path | Status |\n| --- | --- | --- | --- | --- |\n' + requests.join('\n') : '',
+    requests.length === 50 ? 'Trace preview: first 50 requests. The JSON report contains the full sequence.' : '',
+    'Reports: `report.json` and `junit.xml` in the configured output directory. Upload these files in an `if: always()` step to retain the results.',
+  ].filter(Boolean).join('\n\n') + '\n';
+}
+
+// Existing ancestors are resolved too, so an output symlink follows the same boundary.
+export function workspacePath(workspace, input, kind) {
+  if (!input || /[\r\n:,]/.test(input)) throw new Error(`${kind}: supply a repository-relative path without newlines, colons or commas.`);
+  if (isAbsolute(input)) throw new Error(`${kind}: use a repository-relative path.`);
+  const root = realpathSync(workspace);
+  const path = resolve(root, input);
+  let ancestor = path;
+  while (!existsSync(ancestor)) ancestor = dirname(ancestor);
+  const canonical = resolve(realpathSync(ancestor), relative(ancestor, path));
+  const rel = relative(root, canonical);
+  if (!rel || rel === '..' || rel.startsWith('../') || isAbsolute(rel)) throw new Error(`${kind}: path must be inside the checked-out repository.`);
+  if (kind !== 'out' && !statSync(canonical).isFile()) throw new Error(`${kind}: expected a JSON file.`);
+  if (kind === 'out' && existsSync(canonical) && !statSync(canonical).isDirectory()) throw new Error('out: expected a directory.');
+  return canonical;
+}
+
+export function dockerArguments({ workflow, caseFile, out, image, uid, gid }) {
+  return ['run', '--rm', '--network', 'none', '--user', `${uid}:${gid}`,
+    '--mount', `type=bind,source=${workflow},target=/inputs/workflow.json,readonly`,
+    '--mount', `type=bind,source=${caseFile},target=/inputs/case.json,readonly`,
+    '--mount', `type=bind,source=${out},target=/results`,
+    image, '/inputs/workflow.json', '/inputs/case.json', '--out', '/results'];
+}
+
+export function buildArguments({ actionRoot, image, n8nVersion }) {
+  if (!/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z]+(?:[.-][0-9A-Za-z]+)*)?$/.test(n8nVersion)) {
+    throw new Error('n8n-version: supply an exact release, such as 2.41.7.');
+  }
+  return ['build', '--build-arg', `N8N_VERSION=${n8nVersion}`, '--tag', image, actionRoot];
+}
+
+function execute(args) {
+  const result = spawnSync('docker', args, { stdio: 'inherit' });
+  if (result.error) throw result.error;
+  if (result.signal) throw new Error(`Docker interrupted by ${result.signal}`);
+  return result.status;
+}
+
+export function main(env = process.env) {
+  let exitCode = 2;
+  try {
+    if (process.platform !== 'linux') throw new Error('Use a Linux runner with Docker, such as ubuntu-latest.');
+    const workspace = env.GITHUB_WORKSPACE;
+    const actionRoot = env.ACTION_ROOT;
+    const n8nVersion = env.CHECK_N8N_VERSION || '2.41.7';
+    const hash = createHash('sha256').update(`${actionRoot}\0${n8nVersion}`).digest('hex').slice(0, 16);
+    const image = `n8n-check-action:${hash}`;
+    const build = buildArguments({ actionRoot, image, n8nVersion });
+    const workflow = workspacePath(workspace, env.CHECK_WORKFLOW, 'workflow');
+    const caseFile = workspacePath(workspace, env.CHECK_CASE, 'case');
+    const out = workspacePath(workspace, env.CHECK_OUT || '.n8n-check', 'out');
+    for (const input of [workflow, caseFile]) {
+      const rel = relative(out, input);
+      if (rel && rel !== '..' && !rel.startsWith('../') && !isAbsolute(rel)) throw new Error('out: choose a results directory separate from the workflow and case files.');
+    }
+    mkdirSync(out, { recursive: true });
+    // Each invocation reports its own result, including a build or startup failure.
+    for (const file of ['report.json', 'junit.xml']) rmSync(join(out, file), { force: true });
+    console.log(`::group::Build n8n-check with n8n ${n8nVersion}`);
+    const built = execute(build);
+    console.log('::endgroup::');
+    if (built !== 0) throw new Error(`Docker build exited ${built}.`);
+    const code = execute(dockerArguments({ workflow, caseFile, out, image, uid: process.getuid(), gid: process.getgid() }));
+    exitCode = [0, 1, 2].includes(code) ? code : 2;
+    if (existsSync(join(out, 'report.json'))) {
+      const report = JSON.parse(readFileSync(join(out, 'report.json'), 'utf8'));
+      if (env.GITHUB_STEP_SUMMARY) appendFileSync(env.GITHUB_STEP_SUMMARY, summary(report));
+      if (env.GITHUB_OUTPUT) appendFileSync(env.GITHUB_OUTPUT, `report=${join(out, 'report.json')}\njunit=${join(out, 'junit.xml')}\n`);
+    } else throw new Error(`Docker exited ${code} before producing a report.`);
+  } catch (error) {
+    exitCode = 2;
+    console.error(`n8n-check action: ${error.message}`);
+    if (env.GITHUB_STEP_SUMMARY) appendFileSync(env.GITHUB_STEP_SUMMARY, `## n8n-check: SETUP ERROR\n\n<pre>${html(error.message)}</pre>\n`);
+  }
+  if (env.GITHUB_OUTPUT) appendFileSync(env.GITHUB_OUTPUT, `exit-code=${exitCode}\n`);
+  return exitCode;
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) process.exitCode = main();

package/src/case-draft.mjs

@@ -0,0 +1,163 @@
+import { prepareWorkflow, validateCase, executionSlice } from './workflow.mjs';
+
+const plain = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+const copy = value => structuredClone(value);
+const has = (value, key) => Object.hasOwn(value, key);
+
+function workflowFrom(source) {
+  if (Array.isArray(source)) {
+    if (source.length !== 1) throw new Error('Supply one workflow export; received an array with multiple workflows');
+    source = source[0];
+  }
+  if (!plain(source) || !Array.isArray(source.nodes) || !plain(source.connections)) throw new Error('Expected an n8n workflow export with nodes and connections');
+  if (source.nodes.some(node => !plain(node) || typeof node.name !== 'string' || typeof node.type !== 'string')) throw new Error('Each workflow node needs a name and type');
+  if (new Set(source.nodes.map(node => node.name)).size !== source.nodes.length) throw new Error('Workflow node names must be unique');
+  return source;
+}
+
+function linksFrom(source) {
+  const links = [];
+  for (const [from, types] of Object.entries(source.connections)) {
+    if (!plain(types)) throw new Error(`Invalid connections for node: ${from}`);
+    for (const branches of Object.values(types)) {
+      if (!Array.isArray(branches) || branches.some(branch => !Array.isArray(branch) || branch.some(edge => !plain(edge) || typeof edge.node !== 'string'))) throw new Error(`Invalid connections for node: ${from}`);
+      for (const branch of branches) for (const edge of branch) links.push({ from, to: edge.node });
+    }
+  }
+  return links;
+}
+
+function reachable(input, links, stopAfter) {
+  const kept = new Set(input ? [input] : []);
+  for (const name of kept) if (name !== stopAfter) for (const link of links) if (link.from === name) kept.add(link.to);
+  return kept;
+}
+
+function targetFor(source, input, links) {
+  const kept = reachable(input, links);
+  const candidates = source.nodes.filter(node => kept.has(node.name) && node.name !== input && node.type !== 'n8n-nodes-base.stickyNote');
+  const terminal = candidates.filter(node => !links.some(link => link.from === node.name));
+  return (terminal.find(node => has(source.pinData ?? {}, node.name)) ?? terminal.at(-1) ?? candidates.at(-1))?.name ?? '';
+}
+
+export function inspectWorkflow(raw) {
+  const source = workflowFrom(raw);
+  const links = linksFrom(source);
+  const nodes = source.nodes.map(node => ({ name: node.name, type: node.type, hasPinData: has(source.pinData ?? {}, node.name), pinItemCount: Array.isArray(source.pinData?.[node.name]) ? source.pinData[node.name].length : 0 }));
+  const candidates = nodes.filter(node => node.type !== 'n8n-nodes-base.stickyNote' && links.some(link => link.from === node.name));
+  const suggestedInputNode = (candidates.find(node => node.hasPinData && node.pinItemCount > 0) ?? candidates[0] ?? nodes.find(node => node.type !== 'n8n-nodes-base.stickyNote'))?.name ?? '';
+  return { nodes, suggestedInputNode, suggestedAssertNode: targetFor(source, suggestedInputNode, links) };
+}
+
+/** Pure local planning: exported pins supply JSON snapshots; HTTP contracts are supplied by the author. */
+export function draftCase(raw, options = {}) {
+  const source = workflowFrom(raw);
+  const inspected = inspectWorkflow(source);
+  const links = linksFrom(source);
+  const inputNode = options.inputNode ?? inspected.suggestedInputNode;
+  const assertNode = options.assertNode ?? options.stopAfter ?? targetFor(source, inputNode, links);
+  const output = options.output ?? 0;
+  let kept;
+  try { ({ kept } = executionSlice(source, inputNode, options.stopAfter)); }
+  catch { kept = reachable(inputNode, links, options.stopAfter); } // The structural probe below reports the error alongside pending fields.
+  const selected = source.nodes.filter(node => kept.has(node.name));
+  const http = selected.filter(node => node.name !== inputNode && node.type === 'n8n-nodes-base.httpRequest');
+  const issues = [];
+  const issue = (code, path, message) => issues.push({ code, path, message });
+  const itemsFor = (optionKey, nodeName, path, allowPins = true) => {
+    if (has(options, optionKey) && options[optionKey] !== undefined) {
+      const value = options[optionKey];
+      if (!Array.isArray(value) || !value.every(plain)) issue('items_required', path, 'Supply an array of JSON objects.');
+      else if (optionKey === 'inputItems' && value.length === 0) issue('input_empty', path, 'Add at least one input item to exercise the downstream slice.');
+      return copy(value);
+    }
+    const pins = source.pinData?.[nodeName];
+    if (allowPins && Array.isArray(pins) && pins.every(item => plain(item) && plain(item.json) && !has(item, 'binary'))) {
+      if (optionKey === 'inputItems' && pins.length === 0) issue('input_empty', path, 'The pinned input is empty. Add at least one input item to exercise the downstream slice.');
+      return copy(pins.map(item => item.json));
+    }
+    const detail = pins !== undefined && allowPins ? ' Use JSON-only pins in [{"json": {...}}] form, or enter the JSON item array.' : ' Pin this node after a known-good run and re-export, or enter the JSON item array.';
+    issue('items_required', path, `Supply ${optionKey === 'inputItems' ? 'fixture input' : 'expected output'} for "${nodeName || 'select a node'}".${detail}`);
+    return null;
+  };
+  const inputItems = itemsFor('inputItems', inputNode, 'input.items');
+  const assertionMode = options.assertionMode ?? 'exact';
+  const assertion = { node: assertNode, ...(output ? { output } : {}) };
+  if (assertionMode === 'exact') {
+    assertion.equals = itemsFor('expectedItems', assertNode, 'assertions[0].equals', output === 0);
+  } else if (['pluck', 'count'].includes(assertionMode)) {
+    const pins = source.pinData?.[assertNode];
+    const usablePins = output === 0 && Array.isArray(pins) && pins.every(item => plain(item) && plain(item.json) && !has(item, 'binary'));
+    assertion.count = options.expectedCount !== undefined ? copy(options.expectedCount) : usablePins ? pins.length : null;
+    if (!Number.isInteger(assertion.count) || assertion.count < 0) issue('count_required', 'assertions[0].count', 'Enter the expected item count as a whole number starting at 0.');
+    if (assertionMode === 'pluck') {
+      assertion.pluck = options.pluck === undefined ? 'json.id' : options.pluck;
+      const validPath = typeof assertion.pluck === 'string' && assertion.pluck.split('.').every(part => part.length > 0);
+      if (!validPath) issue('pluck_required', 'assertions[0].pluck', 'Enter a dot-separated path from the n8n item, such as json.id.');
+      assertion.equals = options.expectedValues !== undefined ? copy(options.expectedValues) : null;
+      if (options.expectedValues === undefined && usablePins && validPath) {
+        const missingItems = [];
+        const values = pins.map((item, index) => {
+          let value = item;
+          for (const key of assertion.pluck.split('.')) {
+            if (value === null || typeof value !== 'object' || !has(value, key)) {
+              missingItems.push(index);
+              return undefined;
+            }
+            value = value[key];
+          }
+          return copy(value);
+        });
+        if (missingItems.length) issue('projection_missing', 'assertions[0].equals', `The selected field is missing in pinned items at zero-based indexes ${missingItems.join(', ')}. Choose a present field or enter expected values.`);
+        else assertion.equals = values;
+      }
+      if (!Array.isArray(assertion.equals)) issue('values_required', 'assertions[0].equals', 'Enter an array of expected field values in run order, such as ["row-A", "row-B"].');
+      else if (Number.isInteger(assertion.count) && assertion.count >= 0 && assertion.count !== assertion.equals.length) issue('count_mismatch', 'assertions[0].count', 'Match the item count to the number of expected field values.');
+    }
+  } else {
+    issue('assertion_mode', 'assertions[0]', 'Choose exact, pluck, or count assertion mode.');
+    assertion.equals = null;
+  }
+  if (inputNode === assertNode && inputNode) issue('assert_downstream', 'assertions[0].node', 'Choose a downstream assertion node to check executed behavior. The input node is replaced with your fixture.');
+  if (!assertNode) issue('assert_required', 'assertions[0].node', 'Choose a downstream node whose output this case should preserve.');
+
+  let mocks;
+  if (options.mocks !== undefined) {
+    mocks = copy(options.mocks);
+    if (Array.isArray(mocks)) for (const [index, mock] of mocks.entries()) {
+      if (mock?.url === '/TODO') issue('mock_path_required', `mocks[${index}].url`, `\"${mock.node}\": replace /TODO with the local URL path or expression for this HTTP node.`);
+      if (Array.isArray(mock?.routes)) for (const [routeIndex, route] of mock.routes.entries()) {
+        if (route?.path === '/TODO') issue('mock_path_required', `mocks[${index}].routes[${routeIndex}].path`, `\"${mock.node}\": replace /TODO with a concrete route path for your fixture IDs.`);
+      }
+    }
+  }
+  else mocks = http.map((node, index) => {
+    const original = node.parameters?.url;
+    let path = '/TODO';
+    if (typeof original === 'string' && !original.includes('{{') && !original.startsWith('=')) {
+      try { const url = new URL(original); if (['http:', 'https:'].includes(url.protocol)) path = url.pathname + url.search; } catch {}
+    }
+    const method = node.parameters?.method ?? 'GET';
+    issue('mock_contract_required', `mocks[${index}]`, `"${node.name}": enter response status/body and expected request count for each route. Pinned output is a snapshot; HTTP status, request count and response grouping are author-supplied contracts.`);
+    if (path === '/TODO') issue('mock_path_required', `mocks[${index}].url`, `"${node.name}": set the local URL expression and concrete route paths for your fixture IDs.`);
+    return { node: node.name, url: path, routes: [{ method, path, responses: [{ status: null, json: null }], expect: { count: null } }] };
+  });
+  const boundary = options.stopAfter === undefined ? {} : { stopAfter: options.stopAfter };
+  const spec = { version: 1, name: options.name ?? `${source.name || 'Workflow'} check`, input: { node: inputNode, items: inputItems }, ...boundary, mocks, assertions: [assertion] };
+  // Valid placeholders exist only in this structural probe; the saved draft retains pending fields.
+  const probe = {
+    version: 1, name: 'Draft structure check', input: { node: inputNode, items: [] }, ...boundary,
+    mocks: http.map(node => ({ node: node.name, url: '/draft', routes: [{ method: 'GET', path: '/draft', responses: [{ status: 200, json: {} }], expect: { count: 0 } }] })),
+    assertions: [{ node: assertNode, equals: [] }],
+  };
+  try { prepareWorkflow(source, probe, 'http://127.0.0.1:1'); }
+  catch (error) { issue('slice_structure', 'workflow', error.message); }
+  if (issues.length === 0) {
+    try { validateCase(spec); prepareWorkflow(source, spec, 'http://127.0.0.1:1'); }
+    catch (error) { issue('case_invalid', 'case', error.message); }
+  } else if (options.mocks !== undefined) {
+    try { validateCase({ ...spec, input: { node: inputNode, items: [] }, assertions: [{ node: assertNode, equals: [] }] }); }
+    catch (error) { issue('case_invalid', 'case', error.message); }
+  }
+  return { spec, issues, ready: issues.length === 0, summary: { inputNode, assertNode, ...(options.stopAfter === undefined ? {} : { stopAfter: options.stopAfter }), keptNodes: selected.map(node => node.name), omittedNodes: source.nodes.filter(node => !kept.has(node.name)).map(node => node.name), httpNodes: http.map(node => node.name) } };
+}