@blucca/n8n-check 0.0.0-stage → 0.1.6

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

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;