The tool now runs on Node 16 instead of refusing below 20

[qwerfunch]

The tool now runs on Node 16 instead of refusing below 20

2026-09-10 · feature/node-floor-cli-entry → develop

A global install on Node 16 died with a raw ERR_UNKNOWN_FILE_EXTENSION trace from inside Node's own loader. The entry file now carries an extension so it loads everywhere, and the supported floor moved from 20 down to 16 by removing the dependencies that reached above it.

Heads-up: the Node 20 floor was never real. Measured against running releases rather than read off a dependency declaration, the shipped bundle already ran on Node 18, and only four platform surfaces stood between it and Node 16 — three of them from one dependency used solely to spawn external commands. Because the engine ships as a single bundled file, that dependency's floor had silently become the whole tool's floor.

Fixed

▸ The entry file had no extension. The package declares the ESM module type, and Node's loader refuses an extensionless file in that scope. The crash happened before a single line of project code ran, which is why the message named neither the tool nor a version. Measured: Node 16 refuses the extensionless form, 18 and above accept it, and every release accepts an explicit module extension. Never a Windows defect — the same rejection reproduces on Linux.

▸ One dependency was setting the floor for everything. It reached for util.aborted, stream.getDefaultHighWaterMark and events.addAbortListener. Every external command now goes through one small runner over the platform's own child-process module, including the conformance harness, so that dependency leaves the tree entirely rather than sitting unused in the manifest. Four of its behaviours are reproduced deliberately, because a stage verdict changes otherwise:

• Windows command resolution. The replaced library never called the raw platform spawn — it routed arguments through a portable resolver first. On Windows a bare npm is really npm.cmd, which the raw call cannot find, and spawning a .cmd without a shell throws outright on patched releases. The runner keeps that resolver. A shell would "work" while letting the command processor mangle an unquoted argument, which the architecture stage's exclusion pattern would hit immediately.
• Final-newline stripping. The old library removed one trailing newline; the platform call does not. Call sites compare captured output against expected tokens.
• The capture limit. The old default was 100 MB; the platform default is 1 MB and truncates silently past it. A verbose linter or test reporter exceeds 1 MB, and a truncated report parses as garbage — a passing suite read as a failure.
• An absent exit status when the spawn never started. On Linux and macOS that falls out of the platform call. On Windows it does not: an unresolvable command is wrapped in the command processor, which exits 1, and the resolver then synthesizes the not-found error — so the raw result carries both. Keying on the error rather than the status keeps the shape identical everywhere, which is what the stages' missing-tool skip depends on.

▸ Our own two blockers. A single interactive prompt statically imported the promise flavour of readline, which exists only from Node 17, and that one import made the entire bundle unloadable on Node 16. It now uses the callback form. Built-in network fetch arrives in Node 18 and is used only by the direct model lanes; those lanes now name the missing capability and the release that provides it, and every other command keeps working. Refusing the whole tool for one optional path is the defect this work undoes.

Added

▸ A check that the floor cannot drift back. A script reads every platform-module import out of the built bundle and resolves each against the running release. No version table to maintain and no model involved. It runs in the build job and again on the floor release itself, so a dependency upgrade that reaches above the floor fails loudly instead of reaching a terminal. Its reach limit is documented in the script: it reads static imports, so a bundled CommonJS dependency reaching through require slips past — which is why the floor cell also runs real commands rather than printing a version string.

▸ CI cells for the two axes this bug lived on. The workflow was one job, one platform, one Node version. The entry job now packs the tarball and installs it through npm's own bin shim on Linux with Node 16, 20 and 22, on Windows with 22, and on Linux with Node 14 to prove the refusal still speaks below the floor. The Windows cell also runs the runner's own tests, since those drive real child processes and are the only place the Windows spawn path executes.

Verification

Through the real install path, not a direct file invocation:

node:14  →  cladding requires Node 16 or newer. This is Node 14.21.3.
            Upgrade Node, then run the command again.            exit=1
node:16  →  0.10.0                                               exit=0
node:18  →  0.10.0                                               exit=0
node:20  →  0.10.0                                               exit=0
node:22  →  0.10.0                                               exit=0

On Node 16 the originally reported command completes, and so does real work:

$ clad setup     # node:16 — completes, reports which hosts were wired
$ clad sync      # ✓ sync  306 features valid
$ clad status    # renders the feature × stage matrix
$ clad check --tier=pre-commit
  ✓ Type   ✓ Drift   ✓ Architecture   ✓ Secret

Full suite 3855 of 3855, conformance fixtures 33 of 33, typecheck and lint clean, strict pre-push gate green, and on the commit itself a rebuild produces no diff while the strict gate leaves the tree clean.

The branch also carries the 0.10.1 release preparation: eleven version sites, the six README record rows with the pins that hold them, and the release notes. Re-verified at that version through the install path — Node 14 refuses and exits 1, while 16, 18, 20, 22 and 24 all print 0.10.1.

Notes for the reviewer

▸ The conformance tests caught a real defect in the runner. Written in a separate context from the implementation, they found that every successful run was reporting itself as failed: the portable resolver assigns its error field to null rather than leaving it absent, and an identity check against undefined therefore saw a failure on every healthy spawn. No caller reads that field today, so nothing was visibly broken — which is exactly why a test rather than a reading found it.

▸ A skipped-conditionally test claims no criterion. The binding harvester reads titles only from plain test(...) calls, so a test.skipIf(...)('[covers:…]') title is invisible to it and the completion gate reports the criterion as unclaimed. Worth fixing in the harvester separately; here the affected test was expressed in plain form.

▸ On Node 16 the Lint stage reports a tool failure, because this project's own linter needs Node 18. That is a delegated toolchain reported as a stage finding rather than a crash, and it is the user's toolchain rather than the tool's floor. Contributors still need Node 20 for the test runner, which the contributor docs now say explicitly while the setup guide tells a user 16.

▸ Node 14 and below stay out of reach, deliberately. Node 14 additionally needs our own recursive-copy implementation and Node 12 two more of our own calls, for runtimes three years past end of life. Below the floor the refusal message is the honest answer.

▸ The conformance fixtures still pass, 33 of 33. Their git setup calls went through the removed dependency, which threw on failure; the replacement reports failure as data, so fixture setup now uses a small helper that throws loudly instead — a silent git init failure would build the wrong fixture and make the verdict meaningless.

▸ One pinned measurement moved: the design evidence page records the byte total of the routed design set and a test holds it to the real figure, so editing design documents refreshed it. The surrounding figures in that paragraph are a dated snapshot and were already behind before this change.