Skip to content

7.4 billion tokens per month. 34 free LLM providers. 635 free model endpoints. All behind one /v1 endpoint, plus any custom OpenAI-compatible endpoint. Smart routing, automatic failover, encrypted keys. Personal experimentation only.

TypeScript

fix(cli): say 'needs Node 20' instead of dying on old Node (#1283) (#1295)

tashdroida143971daab4
diff --git a/cli/src/index.test.ts b/cli/src/index.test.ts
index 341f46fb..0c1f40db 100644
--- a/cli/src/index.test.ts
+++ b/cli/src/index.test.ts
@@ -2,7 +2,7 @@ import fs from 'node:fs';
import os from 'node:os';
import path from 'node:path';
import { afterEach, describe, expect, it } from 'vitest';
-import { claudeLaunchEnv, codexArgs, main, parseArgs, resolvePinnedModel } from './index.js';
+import { claudeLaunchEnv, codexArgs, main, parseArgs, resolvePinnedModel, unsupportedNodeVersion } from './index.js';
import { UnknownModelError } from './models.js';
import type { CatalogModel } from './types.js';
@@ -195,4 +195,34 @@ describe('CLI arguments and launchers', () => {
);
expect(args).toContain('model_providers.freellmapi.wire_api="responses"');
});
+
+ // #1283: on Node <17.4 the CLI died at module-load time with
+ // ERR_UNKNOWN_BUILTIN_MODULE because `node:readline/promises` was imported
+ // statically, so no command — not even --help — could run, let alone print
+ // a readable reason. Two layers fix it: the readline import is now lazy
+ // (only the interactive key prompt needs it), and this pure check turns an
+ // old runtime into one clear sentence before main() runs.
+ describe('unsupportedNodeVersion (#1283)', () => {
+ it('accepts Node 20 and newer', () => {
+ expect(unsupportedNodeVersion('20.18.0')).toBeNull();
+ expect(unsupportedNodeVersion('22.5.1')).toBeNull();
+ expect(unsupportedNodeVersion('26.9.0')).toBeNull();
+ });
+
+ it('rejects the older runtimes from the issue reports', () => {
+ for (const version of ['12.22.12', '14.21.3', '16.20.2', '18.19.0', '19.9.0']) {
+ const message = unsupportedNodeVersion(version);
+ expect(message).toContain('Node.js 20 or newer');
+ expect(message).toContain(version);
+ }
+ });
+
+ it('says nothing when the runtime is unrecognised', () => {
+ // A non-Node runtime (or a mocked process) must not be told it is
+ // "old"; the failure, if any, should come from the code itself.
+ expect(unsupportedNodeVersion(undefined)).toBeNull();
+ expect(unsupportedNodeVersion('')).toBeNull();
+ expect(unsupportedNodeVersion('nightly')).toBeNull();
+ });
+ });
});
diff --git a/cli/src/index.ts b/cli/src/index.ts
index a02e8c82..50101984 100644
--- a/cli/src/index.ts
+++ b/cli/src/index.ts
@@ -3,7 +3,6 @@ import os from 'node:os';
import fs from 'node:fs';
import path from 'node:path';
import process from 'node:process';
-import readline from 'node:readline/promises';
import { spawn } from 'node:child_process';
import { Writable } from 'node:stream';
import { fileURLToPath } from 'node:url';
@@ -108,6 +107,13 @@ async function promptForKey(): Promise<string> {
'No API key supplied. Pass --api-key or set FREELLMAPI_API_KEY.',
);
}
+ // Imported lazily, not statically: `node:readline/promises` only exists on
+ // Node >=17.4, and a static import of it crashes the whole CLI at load time
+ // on older runtimes (#1283) — `npx freellmapi --help` died with
+ // ERR_UNKNOWN_BUILTIN_MODULE before main() or the engines check could say
+ // anything useful. Deferring it means only the interactive key prompt needs
+ // a modern Node; every other command degrades to the readable error below.
+ const readline = (await import('node:readline/promises')).default;
let muted = false;
const output = new Writable({
write(chunk, _encoding, callback) {
@@ -464,12 +470,33 @@ function isDirectExecution(): boolean {
}
}
+/** Minimum Node major this CLI actually runs on: `AbortSignal.timeout`
+ * (17.3), global `fetch` (18), `node:readline/promises` (17.4) — rounded to
+ * the package's engines floor of 20. npm treats `engines` as a warning by
+ * default (and npm 6, still common on Windows boxes hitting #1283, ignores it
+ * for `npx`), so without this check an unsupported runtime gets a stack
+ * trace instead of a sentence. Returns null when the runtime is fine. */
+export function unsupportedNodeVersion(
+ version: string | undefined = process.versions.node,
+ major: number | undefined = Number(version?.split('.')[0]),
+): string | null {
+ if (!version || !Number.isFinite(major)) return null; // Non-Node runtimes: don't guess.
+ if (major >= 20) return null;
+ return `freellmapi requires Node.js 20 or newer (found ${version}). Install one from https://nodejs.org and re-run.`;
+}
+
if (isDirectExecution()) {
- main().then(
- code => { process.exitCode = code; },
- error => {
- process.stderr.write(`freellmapi: ${error instanceof Error ? error.message : String(error)}\n`);
- process.exitCode = 1;
- },
- );
+ const unsupported = unsupportedNodeVersion();
+ if (unsupported) {
+ process.stderr.write(`freellmapi: ${unsupported}\n`);
+ process.exitCode = 1;
+ } else {
+ main().then(
+ code => { process.exitCode = code; },
+ error => {
+ process.stderr.write(`freellmapi: ${error instanceof Error ? error.message : String(error)}\n`);
+ process.exitCode = 1;
+ },
+ );
+ }
}