feat(cli): add runtime Node.js version check with clear error message (#11)

* feat(cli): add runtime Node.js version check with clear error message

* refactor(version-guard): extract to a documented module tested against the real implementation

Author: lxcario

src/index.ts

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+
 import { Command, CommanderError } from 'commander';
 import { createAgentCommand } from './commands/agent.js';
 import { createAuthCommand } from './commands/auth.js';
@@ -15,6 +16,16 @@ import { Output, isOutputMode } from './lib/output.js';
 import { renderCommanderError, rephraseUnknownOption } from './lib/render-error.js';
 import { maybeEmitSkillNudge } from './lib/skill-nudge.js';
 import { VERSION } from './version.js';
+import { shouldRejectNodeVersion } from './version-guard.js';
+
+// Guard: exit early with a clear message on unsupported Node.js versions,
+// rather than failing later with a cryptic ESM/runtime error.
+if (shouldRejectNodeVersion(process.versions.node)) {
+  process.stderr.write(
+    `Error: testsprite requires Node.js >= 20 (found ${process.versions.node}).\nInstall the latest LTS from https://nodejs.org\n`,
+  );
+  process.exit(1);
+}
 
 const program = new Command();
 

src/version-guard.test.ts

@@ -0,0 +1,51 @@
+import { describe, expect, it } from 'vitest';
+import {
+  MIN_SUPPORTED_NODE_MAJOR,
+  parseMajorVersion,
+  shouldRejectNodeVersion,
+} from './version-guard.js';
+
+// These tests exercise the REAL guard functions used by src/index.ts,
+// imported here rather than re-declared, so a regression in the source is
+// actually caught.
+
+describe('parseMajorVersion', () => {
+  it('extracts the leading major from a semver string', () => {
+    expect(parseMajorVersion('20.11.1')).toBe(20);
+    expect(parseMajorVersion('18.0.0')).toBe(18);
+    expect(parseMajorVersion('22.3.0')).toBe(22);
+  });
+
+  it('returns NaN for a non-numeric version string', () => {
+    expect(Number.isNaN(parseMajorVersion('not-a-version'))).toBe(true);
+  });
+});
+
+describe('shouldRejectNodeVersion', () => {
+  it('rejects majors below the supported floor', () => {
+    expect(shouldRejectNodeVersion('18.19.1')).toBe(true);
+    expect(shouldRejectNodeVersion('16.20.2')).toBe(true);
+    expect(shouldRejectNodeVersion('14.21.3')).toBe(true);
+  });
+
+  it('accepts the supported floor and above', () => {
+    expect(shouldRejectNodeVersion('20.0.0')).toBe(false);
+    expect(shouldRejectNodeVersion('20.11.0')).toBe(false);
+    expect(shouldRejectNodeVersion('21.0.0')).toBe(false);
+    expect(shouldRejectNodeVersion('22.1.0')).toBe(false);
+  });
+
+  it(`treats exactly ${MIN_SUPPORTED_NODE_MAJOR} as supported (boundary)`, () => {
+    expect(shouldRejectNodeVersion(`${MIN_SUPPORTED_NODE_MAJOR}.0.0`)).toBe(false);
+    expect(shouldRejectNodeVersion(`${MIN_SUPPORTED_NODE_MAJOR - 1}.9.9`)).toBe(true);
+  });
+
+  it('does not reject an unparseable version (guard never blocks on garbage)', () => {
+    expect(shouldRejectNodeVersion('not-a-version')).toBe(false);
+  });
+
+  it('the running Node satisfies the guard (meta-test)', () => {
+    // The test suite itself runs on a supported Node, so the guard must pass.
+    expect(shouldRejectNodeVersion(process.versions.node)).toBe(false);
+  });
+});

src/version-guard.ts

@@ -0,0 +1,41 @@
+/**
+ * Node.js runtime version guard.
+ *
+ * The CLI targets modern Node (see `engines.node` in package.json). Running on
+ * an older runtime tends to fail later with a cryptic ESM/syntax error, so the
+ * entrypoint (`src/index.ts`) uses {@link shouldRejectNodeVersion} to exit early
+ * with a clear, actionable message instead.
+ *
+ * The logic lives here (rather than inline) so it can be unit-tested against the
+ * real implementation the entrypoint uses — not a copy.
+ */
+
+/** Minimum Node.js major version supported by the CLI (matches package.json `engines.node`). */
+export const MIN_SUPPORTED_NODE_MAJOR = 20;
+
+/**
+ * Parse the leading major version number from a Node.js version string.
+ *
+ * @param nodeVersion - a dot-separated version string such as `process.versions.node`
+ *   (e.g. `"20.11.1"`). A leading `v` is not expected (Node does not include one here).
+ * @returns the major version as a number, or `NaN` if the string has no numeric leading segment.
+ */
+export function parseMajorVersion(nodeVersion: string): number {
+  return Number(nodeVersion.split('.')[0]);
+}
+
+/**
+ * Decide whether the given Node.js version is too old to run the CLI.
+ *
+ * A version is rejected only when its major number is a real value below
+ * {@link MIN_SUPPORTED_NODE_MAJOR}. An unparseable string yields `NaN`, which is
+ * treated as "do not reject" so the guard never blocks on a version string it
+ * cannot understand (the runtime would surface any real incompatibility itself).
+ *
+ * @param nodeVersion - a `process.versions.node` style string (e.g. `"18.19.1"`).
+ * @returns `true` when the runtime is below the supported floor and should be rejected.
+ */
+export function shouldRejectNodeVersion(nodeVersion: string): boolean {
+  const major = parseMajorVersion(nodeVersion);
+  return !Number.isNaN(major) && major < MIN_SUPPORTED_NODE_MAJOR;
+}