fix(ci): make CJS runtime smoke test strict on every supported Node (#864 review)

The `test:cjs-runtime` one-liner hard-coded `--no-experimental-require-module`,
a flag that doesn't exist on Node 18.x or 20.0-20.18 (it was added in v22.0.0
and backported to v20.19.0). On the declared engines floor (>=18) the script
would abort with `node: bad option` instead of exercising the loader — a false
result on exactly the old Node versions the guard targets.

Replace the inline flag with scripts/smoke-cjs-runtime.js, which probes whether
the running Node recognizes the flag and applies it only when supported. On
Node >= 20.19/22.12 it forces require()-of-ESM off so the mismatch can't be
masked; on older Node (already strict by default) it omits the flag. The guard
is now strict on every supported Node rather than depending on which Node runs
it -- the meta-mistake behind #864.

Verified GREEN (loads dist/ on this Node) and RED (exits non-zero with
ERR_REQUIRE_ESM against an ESM-only module). Updates the CHANGELOG and CI
comment wording to match.

Addresses Copilot review comments on #865.

Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: czlonkowski

.github/workflows/test.yml

@@ -250,11 +250,11 @@ jobs:
           retention-days: 30
 
   # Verify the compiled CommonJS artifact loads under Node's CJS loader (regression guard for #864).
-  # Node 20.19+/22.12+ silently tolerate require() of ESM-only deps, but the minimum supported
-  # Node (>=18) and older 20.x/22.x throw ERR_REQUIRE_ESM. --no-experimental-require-module forces
-  # that strict behavior, so a CJS/ESM mismatch in a shipped dependency (e.g. uuid@14) fails here
-  # regardless of the runner's Node version. The unit suite runs under Vitest's ESM pipeline and
-  # cannot catch this; tsc only type-checks.
+  # Node 20.19+/22.12+ silently tolerate require() of ESM-only deps; scripts/smoke-cjs-runtime.js
+  # forces the strict loader (--no-experimental-require-module) when the running Node supports it,
+  # so a CJS/ESM mismatch in a shipped dependency (e.g. uuid@14) fails here regardless of the
+  # runner's Node version. The unit suite runs under Vitest's ESM pipeline and cannot catch this;
+  # tsc only type-checks.
   cjs-runtime:
     runs-on: ubuntu-latest
     timeout-minutes: 10

CHANGELOG.md

@@ -12,7 +12,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Fixed
 
 - **Server no longer crashes on startup with `ERR_REQUIRE_ESM`** (#864). v2.59.1's `uuid` 10 → 14 bump (#850) moved the dependency to an ESM-only build (`"type": "module"`, no `require` export condition), but the shipped artifact is compiled to CommonJS and calls `require('uuid')`. On the supported minimum Node (`>=18`) — and any Node 20.x before 20.19 or 22.x before 22.12, including the reporter's 22.11 — Node's CommonJS loader throws `ERR_REQUIRE_ESM` at module load, before any config is read, so every MCP client (Claude Code, Cursor, etc.) just saw `MCP error -32000: Connection closed`. It slipped through release verification because `tsc` only type-checks, the Vitest suite runs under an ESM transform pipeline, and CI/Docker/local dev all ran Node ≥ 20.19/22.12 where `require()` of an ESM module is silently tolerated. `uuid` is now pinned to `^11.1.1`, which ships a CommonJS build (a `node.require` export condition) and still clears the original advisory (GHSA-w5hq-g745-h8pq / CVE-2026-41907 does not affect v11), so the security fix from #850 is preserved with no source changes — `v4`/`v5` named exports are API-identical across v10/v11/v14. Reported by @anpe-efficy (André Pereira).
-- **Added a CommonJS runtime smoke test** (`npm run test:cjs-runtime` and a dedicated `cjs-runtime` CI job) that loads the compiled `dist/` under `node --no-experimental-require-module`. The flag forces the strict pre-22.12 CommonJS loader behavior, so a CJS/ESM mismatch in any shipped dependency fails CI regardless of the runner's Node version — the gap that let #864 reach three releases.
+- **Added a CommonJS runtime smoke test** (`npm run test:cjs-runtime` and a dedicated `cjs-runtime` CI job) that loads the compiled `dist/` under the strictest CommonJS loader the running Node supports. On Node ≥ 20.19/22.12 it forces `require()`-of-ESM off via `--no-experimental-require-module` so the mismatch can't be masked; on older Node (down to the `>=18` floor) that strict behavior is already the default and the flag — which doesn't exist there — is omitted. Either way a CJS/ESM mismatch in any shipped dependency fails CI regardless of the runner's Node version, closing the gap that let #864 reach three releases.
 
 Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en
 

package.json

@@ -42,7 +42,7 @@
     "test:ci": "vitest run --coverage --coverage.thresholds.lines=0 --coverage.thresholds.functions=0 --coverage.thresholds.branches=0 --coverage.thresholds.statements=0 --reporter=default --reporter=junit",
     "test:watch": "vitest watch",
     "test:unit": "vitest run tests/unit",
-    "test:cjs-runtime": "node --no-experimental-require-module -e \"require('./dist/index.js'); console.log('CJS runtime load OK')\"",
+    "test:cjs-runtime": "node scripts/smoke-cjs-runtime.js",
     "test:integration": "vitest run --config vitest.config.integration.ts",
     "test:integration:n8n": "vitest run tests/integration/n8n-api",
     "test:cleanup:orphans": "tsx tests/integration/n8n-api/scripts/cleanup-orphans.ts",

scripts/smoke-cjs-runtime.js

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * CommonJS runtime smoke test — regression guard for #864.
+ *
+ * The shipped artifact is compiled to CommonJS and `require()`s its dependencies. If a
+ * dependency is ESM-only (no `require` export condition), `require()` throws
+ * ERR_REQUIRE_ESM and the server crashes at startup before any config is read — exactly
+ * how `uuid@14` broke v2.59.1–2.59.3.
+ *
+ * Node >= 20.19 / >= 22.12 enable `require(ESM)` by default, which silently masks the
+ * mismatch — so just requiring the artifact on a modern Node would NOT catch it. We force
+ * the strict (pre-`require(ESM)`) loader with `--no-experimental-require-module` so the
+ * mismatch surfaces regardless of the runner's Node version.
+ *
+ * That flag does not exist on older Node (added in v22.0.0, backported to v20.19.0;
+ * absent in 18.x and 20.0–20.18). On those versions the strict loader is already the
+ * default, so the flag is unnecessary — and passing it would error with `bad option`. We
+ * probe for flag support rather than hard-coding the version matrix, so the guard is
+ * strict on every supported Node (>=18) instead of depending on which Node happens to run
+ * it (the meta-mistake that produced #864).
+ */
+
+const { spawnSync } = require('node:child_process');
+const path = require('node:path');
+
+const FLAG = '--no-experimental-require-module';
+const entry = path.resolve(__dirname, '..', 'dist', 'index.js');
+const program =
+  `require(${JSON.stringify(entry)}); ` +
+  `console.log('CJS runtime load OK (node ' + process.versions.node + ')');`;
+
+// Probe: does this Node recognize the strict-loader flag? Run an empty program with it.
+const flagSupported =
+  spawnSync(process.execPath, [FLAG, '-e', ''], { stdio: 'ignore' }).status === 0;
+
+const args = flagSupported ? [FLAG, '-e', program] : ['-e', program];
+const result = spawnSync(process.execPath, args, { stdio: 'inherit' });
+
+if (result.status !== 0) {
+  console.error(
+    `\nCJS runtime smoke test FAILED (node ${process.versions.node}, strict loader forced: ${flagSupported}).`
+  );
+  console.error(
+    'The compiled dist/ could not be require()d under the CommonJS loader — a shipped ' +
+      'dependency is likely ESM-only. See #864.'
+  );
+  process.exit(result.status === null ? 1 : result.status);
+}