@blucca/n8n-check 0.0.0-stage → 0.1.7

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;
+}

package/src/mock.mjs

@@ -0,0 +1,72 @@
+import http from 'node:http';
+import { isDeepStrictEqual } from 'node:util';
+
+export async function startMock(spec) {
+  const requests = [];
+  const counts = new Map();
+  const errors = [];
+  const server = http.createServer(async (req, res) => {
+    const send = (status, body, headers = {}) => {
+      res.writeHead(status, { 'content-type': 'application/json', ...headers });
+      res.end(JSON.stringify(body));
+    };
+    try {
+      let raw = '';
+      for await (const chunk of req) {
+        raw += chunk;
+        if (Buffer.byteLength(raw) > 1024 * 1024) {
+          errors.push('Mock request body exceeded 1 MiB');
+          return send(413, { error: 'Mock request body limit' });
+        }
+      }
+      const url = new URL(req.url, 'http://127.0.0.1');
+      const match = url.pathname.match(/^\/(\d+)(\/.*)$/);
+      const mockIndex = match ? Number(match[1]) : -1;
+      const mock = spec.mocks[mockIndex];
+      const path = (match?.[2] ?? url.pathname) + url.search;
+      const routeIndex = mock?.routes.findIndex(route => route.method === req.method && route.path === path) ?? -1;
+      const route = mock?.routes[routeIndex];
+      let body = raw;
+      try { body = raw ? JSON.parse(raw) : null; } catch {}
+      const record = { node: mock?.node ?? null, method: req.method, path, body, matched: Boolean(route) };
+      const key = `${mockIndex}:${routeIndex}`;
+      const sequence = counts.get(key) ?? 0;
+      counts.set(key, sequence + 1);
+      if (requests.length >= (spec.maxRequests ?? 100)) {
+        if (!errors.includes('Mock request count cap reached')) errors.push('Mock request count cap reached');
+        return send(429, { error: 'Mock request count cap reached' });
+      }
+      requests.push(record);
+      if (!route) {
+        record.status = 404;
+        return send(404, { error: 'Unexpected mock request', method: req.method, path });
+      }
+      const response = route.responses[Math.min(sequence, route.responses.length - 1)];
+      record.status = response.status;
+      record.response = response.json;
+      send(response.status, response.json, response.headers);
+    } catch (error) {
+      errors.push(error.message);
+      if (!res.headersSent) send(500, { error: 'Mock server error' });
+      else res.end();
+    }
+  });
+  server.requestTimeout = 10000;
+  await new Promise((resolve, reject) => { server.once('error', reject); server.listen(0, '127.0.0.1', resolve); });
+  return {
+    baseUrl: `http://127.0.0.1:${server.address().port}`,
+    requests,
+    close: () => new Promise(resolve => { server.close(resolve); server.closeAllConnections(); }),
+    checks() {
+      const checks = [{ name: 'mock: all requests match routes', passed: requests.every(r => r.matched), actual: requests.filter(r => !r.matched) }];
+      checks.push({ name: 'mock: request limits and server', passed: errors.length === 0, actual: errors });
+      for (const mock of spec.mocks) for (const route of mock.routes) {
+        const observed = requests.filter(r => r.node === mock.node && r.method === route.method && r.path === route.path);
+        const prefix = `${mock.node}: ${route.method} ${route.path}`;
+        checks.push({ name: `${prefix} request count`, passed: observed.length === route.expect.count, expected: route.expect.count, actual: observed.length });
+        if (route.expect.bodies !== undefined) checks.push({ name: `${prefix} request bodies`, passed: isDeepStrictEqual(observed.map(r => r.body), route.expect.bodies), expected: route.expect.bodies, actual: observed.map(r => r.body) });
+      }
+      return checks;
+    },
+  };
+}

package/src/report.mjs

@@ -0,0 +1,73 @@
+import { isDeepStrictEqual } from 'node:util';
+
+// n8n surrounds --rawOutput JSON with logs on some failure paths.
+export function executionFrom(text) {
+  for (let start = 0; start < text.length; start++) {
+    if (text[start] !== '{' || (start > 0 && text[start - 1] !== '\n')) continue;
+    let depth = 0, quoted = false, escaped = false;
+    for (let i = start; i < text.length; i++) {
+      const char = text[i];
+      if (quoted) {
+        if (escaped) escaped = false;
+        else if (char === '\\') escaped = true;
+        else if (char === '"') quoted = false;
+      } else if (char === '"') quoted = true;
+      else if (char === '{') depth++;
+      else if (char === '}' && --depth === 0) {
+        try {
+          const value = JSON.parse(text.slice(start, i + 1));
+          if (value.data?.resultData) return value;
+        } catch {}
+        break;
+      }
+    }
+  }
+  return null;
+}
+
+export function executionChecks(execution, command, assertions) {
+  const result = execution?.data?.resultData;
+  // Preserve the runtime's explanation when it fails before emitting execution JSON,
+  // including errors while serializing a node's response stream.
+  const cliOutputTail = !execution
+    ? (command.stderr?.trim() || command.stdout?.trim() || '').slice(-4000) || undefined
+    : undefined;
+  const checks = [{
+    name: 'n8n execution succeeds',
+    passed: Boolean(execution && !result.error && command.exitCode === 0 && !command.error),
+    actual: { cliExitCode: command.exitCode, processError: command.error, lastNode: result?.lastNodeExecuted, message: result?.error?.message, description: result?.error?.description, executionFound: Boolean(execution), cliOutputTail },
+  }];
+  for (const assertion of assertions) {
+    const runs = result?.runData?.[assertion.node] ?? [];
+    const items = runs.flatMap(run => run.data?.main?.[assertion.output ?? 0] ?? []);
+    const name = `${assertion.node}: output ${assertion.output ?? 0}`;
+    if (assertion.count !== undefined) checks.push({ name: `${name} count`, passed: items.length === assertion.count, expected: assertion.count, actual: items.length });
+    if (assertion.equals !== undefined) {
+      const missingItems = [];
+      const path = assertion.pluck?.split('.');
+      const actual = items.map((item, index) => {
+        if (!path) return item.json;
+        let value = item;
+        for (const key of path) {
+          if (value === null || typeof value !== 'object' || !Object.hasOwn(value, key)) {
+            missingItems.push(index);
+            return undefined;
+          }
+          value = value[key];
+        }
+        return value;
+      });
+      checks.push({ name: path ? `${name} pluck ${assertion.pluck}` : name, passed: missingItems.length === 0 && isDeepStrictEqual(actual, assertion.equals), expected: assertion.equals, actual: missingItems.length ? { values: actual, missingItems } : actual });
+    }
+  }
+  return checks;
+}
+
+const xml = value => String(value).replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\ufffe\uffff]/g, '').replace(/[<>&"']/g, c => ({ '<': '&lt;', '>': '&gt;', '&': '&amp;', '"': '&quot;', "'": '&apos;' })[c]);
+export function junit(report) {
+  const error = report.status === 'error';
+  const checks = error ? [{ name: 'setup', passed: false, actual: report.error }] : report.checks;
+  const failed = checks.filter(check => !check.passed).length;
+  const cases = checks.map(check => `    <testcase classname="n8n-check" name="${xml(check.name)}">${check.passed ? '' : `\n      <${error ? 'error' : 'failure'} message="${xml(check.name)}">${xml(JSON.stringify({ expected: check.expected, actual: check.actual }, null, 2))}</${error ? 'error' : 'failure'}>\n    `}</testcase>`).join('\n');
+  return `<?xml version="1.0" encoding="UTF-8"?>\n<testsuites tests="${checks.length}" failures="${error ? 0 : failed}" errors="${error ? 1 : 0}">\n  <testsuite name="${xml(report.name)}" tests="${checks.length}" failures="${error ? 0 : failed}" errors="${error ? 1 : 0}" time="${(report.durationMs / 1000).toFixed(3)}">\n${cases}\n  </testsuite>\n</testsuites>\n`;
+}

package/src/runner.mjs

@@ -0,0 +1,111 @@
+import { spawn } from 'node:child_process';
+import { readFile, writeFile, mkdir, mkdtemp } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { validateCase, prepareWorkflow } from './workflow.mjs';
+import { startMock } from './mock.mjs';
+import { executionFrom, executionChecks, junit } from './report.mjs';
+import { version } from './version.mjs';
+
+export async function checkNetwork(allowNetwork) {
+  if (allowNetwork) return { mode: 'host-network', enforced: false };
+  if (process.platform === 'linux') {
+    const interfaces = (await readFile('/proc/self/net/dev', 'utf8')).trim().split('\n').slice(2).map(line => line.split(':')[0].trim());
+    if (interfaces.length === 1 && interfaces[0] === 'lo') return { mode: 'loopback-only', enforced: true, interfaces };
+  }
+  throw new Error('Run in a loopback-only network namespace (Docker --network none), or use --allow-network for a trusted local development run. See README Quick start.');
+}
+
+export function runtimeEnv(home) {
+  const env = {};
+  for (const key of ['PATH', 'SystemRoot', 'WINDIR', 'COMSPEC', 'PATHEXT', 'LANG', 'LC_ALL', 'TZ']) {
+    if (process.env[key]) env[key] = process.env[key];
+  }
+  return {
+    ...env, HOME: home, USERPROFILE: home, TMPDIR: join(home, 'tmp'), TEMP: join(home, 'tmp'), TMP: join(home, 'tmp'),
+    N8N_USER_FOLDER: home, DB_TYPE: 'sqlite', N8N_ENCRYPTION_KEY: randomBytes(32).toString('hex'),
+    N8N_DIAGNOSTICS_ENABLED: 'false', N8N_VERSION_NOTIFICATIONS_ENABLED: 'false', N8N_TEMPLATES_ENABLED: 'false',
+    N8N_RUNNERS_MODE: 'internal', N8N_LOG_LEVEL: 'info', N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS: 'true',
+    N8N_BLOCK_ENV_ACCESS_IN_NODE: 'true', N8N_COMMUNITY_PACKAGES_ENABLED: 'false',
+  };
+}
+
+export async function command(binary, args, env, timeoutMs = 120000) {
+  return new Promise(resolve => {
+    let child;
+    let stdout = '', stderr = '', bytes = 0, error, settled = false;
+    const stop = () => {
+      try { if (process.platform !== 'win32') process.kill(-child.pid, 'SIGKILL'); else child.kill('SIGKILL'); } catch {}
+    };
+    try { child = spawn(binary, args, { env, stdio: ['ignore', 'pipe', 'pipe'], detached: process.platform !== 'win32' }); }
+    catch (e) { return resolve({ stdout, stderr, exitCode: null, error: e.message }); }
+    const timer = setTimeout(() => { error = `Process timeout after ${timeoutMs} ms`; stop(); }, timeoutMs);
+    const capture = stream => chunk => {
+      bytes += Buffer.byteLength(chunk);
+      if (bytes > 16 * 1024 * 1024) { error = 'Process output exceeded 16 MiB'; stop(); return; }
+      if (stream === 'stdout') stdout += chunk.toString(); else stderr += chunk.toString();
+    };
+    child.stdout.setEncoding('utf8'); child.stderr.setEncoding('utf8');
+    child.stdout.on('data', capture('stdout')); child.stderr.on('data', capture('stderr'));
+    const interrupt = () => { error = 'Process interrupted'; stop(); };
+    process.once('SIGINT', interrupt); process.once('SIGTERM', interrupt);
+    child.on('error', e => { error = e.message; });
+    child.on('close', (exitCode, signal) => {
+      if (settled) return; settled = true; clearTimeout(timer);
+      process.removeListener('SIGINT', interrupt); process.removeListener('SIGTERM', interrupt);
+      // Ensure task-runner descendants terminate with their CLI parent.
+      stop();
+      resolve({ stdout, stderr, exitCode, signal, error });
+    });
+  });
+}
+
+export async function runCase(options) {
+  const start = Date.now();
+  const out = resolve(options.out ?? '.n8n-check');
+  const report = { schemaVersion: 1, runnerVersion: version, name: 'n8n-check', startedAt: new Date().toISOString(), nodeVersion: process.version, status: 'error', checks: [], artifacts: out };
+  let mock;
+  await mkdir(out, { recursive: true });
+  try {
+    const spec = validateCase(JSON.parse(await readFile(resolve(options.caseFile), 'utf8')));
+    report.name = spec.name;
+    report.network = await checkNetwork(options.allowNetwork);
+    const source = JSON.parse(await readFile(resolve(options.workflowFile), 'utf8'));
+    mock = await startMock(spec);
+    const prepared = prepareWorkflow(source, spec, mock.baseUrl);
+    report.preparation = { inputNode: spec.input.node, changes: prepared.changes, omittedNodes: prepared.omittedNodes };
+    const runDir = await mkdtemp(join(out, 'run-'));
+    report.runDirectory = runDir;
+    const home = join(runDir, 'n8n-home');
+    await mkdir(join(home, 'tmp'), { recursive: true });
+    const env = runtimeEnv(home);
+    const n8n = options.n8n ?? process.env.N8N_BINARY ?? 'n8n';
+    const invoke = async (args, name, timeout) => {
+      const result = await command(n8n, args, env, timeout);
+      await Promise.all(['stdout', 'stderr'].map(stream => writeFile(join(runDir, `${name}.${stream}.log`), result[stream])));
+      return result;
+    };
+    const version = await invoke(['--version'], 'version');
+    if (version.exitCode !== 0 || version.error) throw new Error(`n8n runtime unavailable: ${version.error || version.stderr || version.stdout}. Supply --n8n /path/to/n8n or use the Docker quick start.`);
+    report.n8nVersion = version.stdout.trim();
+    const workflowPath = join(runDir, 'workflow.json');
+    await writeFile(workflowPath, JSON.stringify(prepared.workflow, null, 2) + '\n');
+    const imported = await invoke(['import:workflow', `--input=${workflowPath}`], 'import');
+    if (imported.exitCode !== 0 || imported.error) throw new Error(`n8n import failed: ${imported.error || imported.stderr || imported.stdout}. Logs: ${runDir}`);
+    const executed = await invoke(['execute', `--id=${prepared.workflow.id}`, '--rawOutput'], 'execute', spec.timeoutMs ?? 60000);
+    const execution = executionFrom(executed.stdout + '\n' + executed.stderr);
+    if (execution) await writeFile(join(runDir, 'execution.json'), JSON.stringify(execution, null, 2) + '\n');
+    report.checks.push(...executionChecks(execution, executed, spec.assertions), ...mock.checks());
+    report.requests = mock.requests;
+    report.status = report.checks.every(check => check.passed) ? 'passed' : 'failed';
+  } catch (error) {
+    report.status = 'error'; report.error = error.message;
+  } finally {
+    if (mock) { report.requests = mock.requests; await mock.close(); }
+  }
+  report.durationMs = Date.now() - start;
+  report.exitCode = report.status === 'passed' ? 0 : report.status === 'failed' ? 1 : 2;
+  await writeFile(join(out, 'report.json'), JSON.stringify(report, null, 2) + '\n');
+  await writeFile(join(out, 'junit.xml'), junit(report));
+  return report;
+}

package/src/version.mjs

@@ -0,0 +1,3 @@
+import { readFileSync } from 'node:fs';
+
+export const version = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;

package/src/workflow.mjs

@@ -0,0 +1,140 @@
+const randomUUID = () => globalThis.crypto.randomUUID();
+
+const plain = value => value && typeof value === 'object' && !Array.isArray(value);
+const ensure = (condition, message) => { if (!condition) throw new Error(message); };
+export function validateCase(spec) {
+  ensure(plain(spec) && spec.version === 1, 'Case version must be 1');
+  ensure(typeof spec.name === 'string' && spec.name.length, 'Case name is required');
+  ensure(plain(spec.input) && typeof spec.input.node === 'string', 'input.node is required');
+  ensure(spec.stopAfter === undefined || (typeof spec.stopAfter === 'string' && spec.stopAfter.length > 0), 'stopAfter must be a non-empty node name');
+  ensure(Array.isArray(spec.input.items) && spec.input.items.every(plain), 'input.items must be an array of JSON objects');
+  ensure(Array.isArray(spec.mocks), 'mocks must be an array (use [] for local-only workflows)');
+  const names = new Set();
+  for (const mock of spec.mocks) {
+    ensure(typeof mock.node === 'string' && !names.has(mock.node), 'Each mock must name a unique HTTP Request node');
+    names.add(mock.node);
+    ensure(typeof mock.url === 'string' && mock.url.startsWith('/') && !mock.url.startsWith('//'), `Mock ${mock.node}: url must be a local path, optionally with n8n {{ expressions }}`);
+    ensure(Array.isArray(mock.routes) && mock.routes.length, `Mock ${mock.node}: routes are required`);
+    const routes = new Set();
+    for (const route of mock.routes) {
+      ensure(typeof route.method === 'string' && /^[A-Z]+$/.test(route.method), 'Route method must be uppercase');
+      ensure(typeof route.path === 'string' && route.path.startsWith('/'), 'Route path must start with /');
+      const key = `${route.method} ${route.path}`;
+      ensure(!routes.has(key), `Duplicate route: ${key}`); routes.add(key);
+      ensure(Array.isArray(route.responses) && route.responses.length, `Route ${key}: responses are required`);
+      for (const response of route.responses) {
+        ensure(plain(response) && Number.isInteger(response.status) && response.status >= 200 && response.status <= 599, `Route ${key}: response status must be 200–599`);
+        ensure(Object.hasOwn(response, 'json'), `Route ${key}: response.json is required`);
+        ensure(response.headers === undefined || (plain(response.headers) && Object.values(response.headers).every(v => typeof v === 'string')), `Route ${key}: headers must contain strings`);
+      }
+      ensure(plain(route.expect) && Number.isInteger(route.expect.count) && route.expect.count >= 0, `Route ${key}: expect.count must be a non-negative integer`);
+      ensure(route.expect.bodies === undefined || (Array.isArray(route.expect.bodies) && route.expect.bodies.length === route.expect.count), `Route ${key}: expect.bodies length must match expect.count`);
+    }
+  }
+  ensure(Array.isArray(spec.assertions) && spec.assertions.length, 'At least one output assertion is required');
+  for (const assertion of spec.assertions) {
+    ensure(plain(assertion) && typeof assertion.node === 'string' && assertion.node.length > 0, 'Each assertion needs a non-empty node name');
+    ensure(assertion.equals !== undefined || assertion.count !== undefined, 'Each assertion needs equals or count');
+    ensure(assertion.equals === undefined || Array.isArray(assertion.equals), 'assertion.equals must be an array');
+    ensure(assertion.count === undefined || (Number.isInteger(assertion.count) && assertion.count >= 0), 'assertion.count must be a non-negative integer');
+    ensure(assertion.pluck === undefined || (typeof assertion.pluck === 'string' && assertion.pluck.split('.').every(part => part.length > 0)), 'assertion.pluck must be a non-empty dot-separated path');
+    ensure(assertion.pluck === undefined || Array.isArray(assertion.equals), 'assertion.pluck requires equals');
+    ensure(assertion.output === undefined || (Number.isInteger(assertion.output) && assertion.output >= 0), 'assertion.output must be a non-negative integer');
+  }
+  ensure(spec.timeoutMs === undefined || (Number.isInteger(spec.timeoutMs) && spec.timeoutMs >= 1000 && spec.timeoutMs <= 600000), 'timeoutMs must be 1000–600000');
+  ensure(spec.maxRequests === undefined || (Number.isInteger(spec.maxRequests) && spec.maxRequests > 0 && spec.maxRequests <= 10000), 'maxRequests must be 1–10000');
+  return spec;
+}
+
+const edges = connections => Object.entries(connections ?? {}).flatMap(([from, types]) =>
+  Object.entries(types).flatMap(([type, branches]) => branches.flatMap(branch => branch.map(edge => ({ from, type, ...edge })))));
+
+/** Select the execution graph; sibling branches remain reachable after a stop. */
+export function executionSlice(source, inputNode, stopAfter) {
+  const byName = new Map(source.nodes.map(node => [node.name, node]));
+  ensure(byName.has(inputNode), `Input node not found: ${inputNode}`);
+  const links = edges(source.connections);
+  const reachable = (start, stop) => {
+    const found = new Set([start]);
+    for (const name of found) if (name !== stop) for (const edge of links) if (edge.from === name) found.add(edge.node);
+    return found;
+  };
+  if (stopAfter !== undefined) {
+    ensure(typeof stopAfter === 'string' && stopAfter.length > 0, 'stopAfter must be a non-empty node name');
+    ensure(byName.has(stopAfter), `stopAfter node not found: ${stopAfter}`);
+    ensure(reachable(inputNode).has(stopAfter), `stopAfter node "${stopAfter}" must be reachable from input "${inputNode}".`);
+    const afterStop = new Set(links.filter(edge => edge.from === stopAfter).map(edge => edge.node));
+    for (const name of afterStop) for (const edge of links) if (edge.from === name) afterStop.add(edge.node);
+    ensure(!afterStop.has(stopAfter), `stopAfter node "${stopAfter}" lies inside a loop. Choose a node after the loop's completed output.`);
+  }
+  const kept = reachable(inputNode, stopAfter);
+  for (const edge of links) if (kept.has(edge.from) && edge.from !== stopAfter) {
+    ensure(byName.has(edge.node), `Connection from ${edge.from} references missing node: ${edge.node}`);
+  }
+  return { kept, links };
+}
+
+export function prepareWorkflow(source, spec, mockBase) {
+  validateCase(spec);
+  if (Array.isArray(source)) {
+    ensure(source.length === 1, 'Supply one workflow export; received an array with multiple workflows');
+    source = source[0];
+  }
+  ensure(plain(source) && Array.isArray(source.nodes) && plain(source.connections), 'Expected an n8n workflow export with nodes and connections');
+  const workflow = structuredClone(source);
+  const byName = new Map(workflow.nodes.map(node => [node.name, node]));
+  ensure(byName.size === workflow.nodes.length, 'Workflow node names must be unique');
+  const { kept, links } = executionSlice(workflow, spec.input.node, spec.stopAfter);
+  for (const edge of links) {
+    if (kept.has(edge.node) && edge.node !== spec.input.node && !kept.has(edge.from)) {
+      throw new Error(`Slice needs incoming ${edge.type} connection from "${edge.from}" to "${edge.node}". Move input.node earlier or provide a self-contained workflow slice.`);
+    }
+  }
+  const changes = [{ node: spec.input.node, change: 'replace with fixture JSON items' }];
+  if (spec.stopAfter !== undefined) changes.push({ node: spec.stopAfter, change: 'stop this branch after the node; remove outgoing connections; retain independently reachable branches' });
+  const fixture = byName.get(spec.input.node);
+  const fixtureNode = {
+    id: fixture.id || randomUUID(), name: fixture.name, position: fixture.position || [0, 0],
+    type: 'n8n-nodes-base.code', typeVersion: 2,
+    parameters: { mode: 'runOnceForAllItems', jsCode: `return JSON.parse(${JSON.stringify(JSON.stringify(spec.input.items))}).map(json => ({json}));` },
+  };
+  workflow.nodes = workflow.nodes.filter(node => kept.has(node.name)).map(node => node.name === fixture.name ? fixtureNode : node);
+  workflow.connections = Object.fromEntries(Object.entries(workflow.connections).filter(([name]) => kept.has(name) && name !== spec.stopAfter).map(([name, types]) => [name,
+    Object.fromEntries(Object.entries(types).map(([type, branches]) => [type, branches.map(branch => branch.filter(edge => kept.has(edge.node)))])),
+  ]));
+  for (const edge of links) ensure(!(kept.has(edge.from) && edge.node === fixture.name), `Input node "${fixture.name}" lies inside a loop. Choose a fixture boundary before the loop.`);
+  let triggerName = 'n8n-check start';
+  while (byName.has(triggerName)) triggerName += '_';
+  workflow.nodes.unshift({ id: randomUUID(), name: triggerName, type: 'n8n-nodes-base.manualTrigger', typeVersion: 1, position: [-400, 0], parameters: {} });
+  workflow.connections[triggerName] = { main: [[{ node: fixture.name, type: 'main', index: 0 }]] };
+  const mockNames = new Set(spec.mocks.map(mock => mock.node));
+  for (let index = 0; index < spec.mocks.length; index++) {
+    const mock = spec.mocks[index];
+    const node = workflow.nodes.find(n => n.name === mock.node);
+    ensure(node?.type === 'n8n-nodes-base.httpRequest', `Mock node must be an HTTP Request node inside the slice: ${mock.node}`);
+    delete node.credentials;
+    node.parameters.authentication = 'none';
+    delete node.parameters.genericAuthType;
+    delete node.parameters.nodeCredentialType;
+    node.parameters.url = `${mock.url.includes('{{') ? '=' : ''}${mockBase}/${index}${mock.url}`;
+    changes.push({ node: node.name, change: 'route URL to local mock; remove credential references; authentication=none' });
+  }
+  for (const node of workflow.nodes) {
+    ensure(!node.credentials || !Object.keys(node.credentials).length, `Node "${node.name}" uses credentials. Replace this boundary with fixture input or an HTTP mock.`);
+    ensure(node.type !== 'n8n-nodes-base.httpRequest' || mockNames.has(node.name), `HTTP Request node "${node.name}" needs a mock entry`);
+    for (const match of JSON.stringify(node.parameters).matchAll(/(?:\$\(|\$items\(|\$node\[)\s*(?:\\?")([^"\\]+)(?:\\?")|(?:\$\(|\$items\(|\$node\[)\s*'([^']+)'/g)) {
+      const dependency = match[1] ?? match[2];
+      ensure(kept.has(dependency), `Node "${node.name}" references "${dependency}" outside the slice. Move input.node earlier or provide a self-contained workflow slice.`);
+    }
+  }
+  for (const assertion of spec.assertions) ensure(kept.has(assertion.node), `Assertion node outside the slice: ${assertion.node}`);
+  // Build a fresh workflow record: ownership, pinData, staticData and production settings stay in the source.
+  return {
+    workflow: {
+      id: randomUUID().replaceAll('-', '').slice(0, 16), name: `n8n-check: ${spec.name}`, active: false,
+      nodes: workflow.nodes, connections: workflow.connections,
+      settings: { ...(source.settings?.timezone ? { timezone: source.settings.timezone } : {}), executionOrder: source.settings?.executionOrder || 'v1', executionTimeout: Math.ceil((spec.timeoutMs ?? 60000) / 1000), saveExecutionProgress: true },
+    },
+    changes, omittedNodes: source.nodes.filter(node => !kept.has(node.name)).map(node => node.name),
+  };
+}