An open source design system that's fully customizable and agent ready
TypeScript
fix(cli): friendly preflight error on unsupported Node versions (#2545)
Joey644fd34fcb51
diff --git a/packages/cli/bin/xds.mjs b/packages/cli/bin/xds.mjsold mode 100755new mode 100644index 12fbbc12bd..1be8c1b129--- a/packages/cli/bin/xds.mjs+++ b/packages/cli/bin/xds.mjs@@ -1,9 +1,32 @@#!/usr/bin/env node// Copyright (c) Meta Platforms, Inc. and affiliates.-import {program} from '../src/index.mjs';-import {isJsonMode, toErrorEnvelope} from '../src/lib/json.mjs';-import {handleCommanderError} from '../src/lib/json-shim.mjs';+// ---------------------------------------------------------------------------+// Node.js version preflight gate.+//+// The CLI and its dependencies use `styleText` from `node:util`, added in Node+// 22.13.0. On older runtimes the lazy-loaded subcommands die with a cryptic+// ESM error ("...does not provide an export named 'styleText'"). To give users+// a clear message instead, we check the running version FIRST, using only+// built-ins, and exit early before importing anything that touches styleText.+//+// `node-version.mjs` is intentionally dependency-free so it loads on the+// unsupported runtimes this guard protects against.+import {+ isNodeVersionSupported,+ unsupportedNodeMessage,+} from '../src/lib/node-version.mjs';++if (!isNodeVersionSupported(process.versions.node)) {+ console.error(unsupportedNodeMessage(process.versions.node));+ process.exit(1);+}++// Imports that transitively load `styleText` must happen AFTER the gate above,+// so they are dynamically imported here rather than at the top of the module.+const {program} = await import('../src/index.mjs');+const {isJsonMode, toErrorEnvelope} = await import('../src/lib/json.mjs');+const {handleCommanderError} = await import('../src/lib/json-shim.mjs');/*** Top-level error boundary (contract guarantee #4): an uncaught throw mustdiff --git a/packages/cli/src/lib/node-version.mjs b/packages/cli/src/lib/node-version.mjsnew file mode 100644index 0000000000..2569c0a68c--- /dev/null+++ b/packages/cli/src/lib/node-version.mjs@@ -0,0 +1,69 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file Node.js version preflight — runtime support gate.+ *+ * The CLI (and its dependencies) rely on `styleText` from `node:util`, which+ * was only added in Node 22.13.0. On older runtimes the lazy-loaded+ * subcommands die with a cryptic ESM error:+ *+ * failed to load: The requested module 'node:util' does not provide an+ * export named 'styleText'+ *+ * This module exposes a tiny, dependency-free comparison helper so the entry+ * point can gate on the running Node version BEFORE importing anything that+ * touches `styleText`, and surface a clear "upgrade Node" message instead.+ *+ * Kept free of any non-builtin imports so it can run on the unsupported+ * runtimes it is meant to guard against.+ */++/** Minimum supported Node.js version. */+export const MIN_NODE_VERSION = '22.13.0';++/**+ * Parse a Node.js version string ("22.14.1", "v20.10.0", "16.20.2-nightly")+ * into a {major, minor, patch} record. Missing or non-numeric segments+ * default to 0.+ *+ * @param {string} version+ * @returns {{major: number, minor: number, patch: number}}+ */+export function parseNodeVersion(version) {+ const cleaned = String(version).trim().replace(/^v/, '');+ const [major = 0, minor = 0, patch = 0] = cleaned+ .split('.')+ .map((seg) => parseInt(seg, 10) || 0);+ return {major, minor, patch};+}++/**+ * Returns true when `version` is greater than or equal to `minimum`.+ * Compares major, then minor, then patch.+ *+ * @param {string} version - the running Node version (e.g. process.versions.node)+ * @param {string} [minimum] - the minimum supported version+ * @returns {boolean}+ */+export function isNodeVersionSupported(version, minimum = MIN_NODE_VERSION) {+ const v = parseNodeVersion(version);+ const min = parseNodeVersion(minimum);+ if (v.major !== min.major) return v.major > min.major;+ if (v.minor !== min.minor) return v.minor > min.minor;+ return v.patch >= min.patch;+}++/**+ * Builds the friendly, human-facing message shown when the runtime is too old.+ *+ * @param {string} version - the running Node version+ * @param {string} [minimum] - the minimum supported version+ * @returns {string}+ */+export function unsupportedNodeMessage(version, minimum = MIN_NODE_VERSION) {+ const clean = String(version).trim().replace(/^v/, '');+ return (+ `xds requires Node.js >=${minimum} (you have v${clean}). ` ++ `Please upgrade Node and try again.`+ );+}diff --git a/packages/cli/src/lib/node-version.test.mjs b/packages/cli/src/lib/node-version.test.mjsnew file mode 100644index 0000000000..89618aefc6--- /dev/null+++ b/packages/cli/src/lib/node-version.test.mjs@@ -0,0 +1,91 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file Unit tests for the Node.js version preflight gate (`node-version.mjs`).+ *+ * The CLI requires Node >=22.13.0 because dependencies import `styleText` from+ * `node:util`, which only exists from that version onward. These tests lock in+ * the parsing and comparison logic that decides whether the running runtime is+ * supported, so the entry-point guard reliably rejects old Node and accepts new+ * Node across the major.minor.patch boundary.+ */++import {describe, it, expect} from 'vitest';+import {+ MIN_NODE_VERSION,+ parseNodeVersion,+ isNodeVersionSupported,+ unsupportedNodeMessage,+} from './node-version.mjs';++describe('parseNodeVersion', () => {+ it('parses a plain semver string', () => {+ expect(parseNodeVersion('22.14.1')).toEqual({major: 22, minor: 14, patch: 1});+ });++ it('strips a leading v', () => {+ expect(parseNodeVersion('v20.10.0')).toEqual({major: 20, minor: 10, patch: 0});+ });++ it('ignores a prerelease/build suffix on the patch segment', () => {+ expect(parseNodeVersion('16.20.2-nightly')).toEqual({major: 16, minor: 20, patch: 2});+ });++ it('defaults missing segments to 0', () => {+ expect(parseNodeVersion('24')).toEqual({major: 24, minor: 0, patch: 0});+ });+});++describe('isNodeVersionSupported', () => {+ it('rejects clearly old majors', () => {+ expect(isNodeVersionSupported('16.20.2')).toBe(false);+ expect(isNodeVersionSupported('20.10.0')).toBe(false);+ });++ it('rejects the same major but an older minor', () => {+ expect(isNodeVersionSupported('22.12.0')).toBe(false);+ });++ it('rejects the same major but an older minor regardless of patch', () => {+ expect(isNodeVersionSupported('22.12.99')).toBe(false);+ });++ it('accepts exactly the minimum version', () => {+ expect(isNodeVersionSupported('22.13.0')).toBe(true);+ });++ it('accepts a newer patch within the minimum minor', () => {+ expect(isNodeVersionSupported('22.13.1')).toBe(true);+ });++ it('accepts a newer minor', () => {+ expect(isNodeVersionSupported('22.14.1')).toBe(true);+ });++ it('accepts a newer major', () => {+ expect(isNodeVersionSupported('24.1.0')).toBe(true);+ });++ it('handles a v-prefixed running version', () => {+ expect(isNodeVersionSupported('v22.13.0')).toBe(true);+ expect(isNodeVersionSupported('v18.0.0')).toBe(false);+ });++ it('uses MIN_NODE_VERSION (22.13.0) as the default threshold', () => {+ expect(MIN_NODE_VERSION).toBe('22.13.0');+ expect(isNodeVersionSupported(MIN_NODE_VERSION)).toBe(true);+ });+});++describe('unsupportedNodeMessage', () => {+ it('names both the required minimum and the running version', () => {+ const msg = unsupportedNodeMessage('16.20.2');+ expect(msg).toContain('>=22.13.0');+ expect(msg).toContain('v16.20.2');+ expect(msg).toContain('upgrade Node');+ });++ it('normalizes a v-prefixed running version to a single v', () => {+ expect(unsupportedNodeMessage('v20.10.0')).toContain('v20.10.0');+ });+});