fix(cli): fail clearly on unsupported Node versions (#2388)

.fallowrc.jsonc

@@ -88,6 +88,8 @@
     // the sync-hyperframes-codegen.yml workflow; complexity/dead-code
     // findings on this file are not actionable from this repo.
     "packages/cli/src/cloud/_gen/**",
+    // Published launcher imports generated dist files that do not exist in a source checkout.
+    "packages/cli/bin/**",
   ],
   "ignoreExports": [
     // Public player-state types are consumed by package users outside this

packages/cli/bin/hyperframes.mjs

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+
+import { runtimeVersionError } from "../dist/runtimeVersion.js";
+
+const error = runtimeVersionError(process.versions.node);
+if (error) {
+  console.error(error);
+  process.exitCode = 1;
+} else {
+  await import("../dist/cli.js");
+}

packages/cli/package.json

@@ -9,9 +9,10 @@
     "directory": "packages/cli"
   },
   "bin": {
-    "hyperframes": "./dist/cli.js"
+    "hyperframes": "./bin/hyperframes.mjs"
   },
   "files": [
+    "bin",
     "dist"
   ],
   "type": "module",

packages/cli/src/runtimeVersion.test.ts

@@ -0,0 +1,19 @@
+import { describe, expect, it } from "vitest";
+import { runtimeVersionError } from "./runtimeVersion.js";
+
+describe("runtimeVersionError", () => {
+  it("rejects Node 20 before the bundled CLI is imported", () => {
+    expect(runtimeVersionError("20.11.1")).toBe(
+      "HyperFrames requires Node.js >= 22 (current: 20.11.1). Switch Node versions and retry.",
+    );
+  });
+
+  it("accepts supported Node releases", () => {
+    expect(runtimeVersionError("22.0.0")).toBeNull();
+    expect(runtimeVersionError("24.14.0")).toBeNull();
+  });
+
+  it("rejects malformed versions safely", () => {
+    expect(runtimeVersionError("unknown")).toContain("requires Node.js >= 22");
+  });
+});

packages/cli/src/runtimeVersion.ts

@@ -0,0 +1,7 @@
+const MINIMUM_NODE_MAJOR = 22;
+
+export function runtimeVersionError(version: string): string | null {
+  const major = Number.parseInt(version.split(".", 1)[0] ?? "", 10);
+  if (Number.isFinite(major) && major >= MINIMUM_NODE_MAJOR) return null;
+  return `HyperFrames requires Node.js >= ${MINIMUM_NODE_MAJOR} (current: ${version}). Switch Node versions and retry.`;
+}

packages/cli/tsup.config.ts

@@ -9,6 +9,7 @@ const pkg = JSON.parse(readFileSync(new URL("./package.json", import.meta.url),
 export default defineConfig({
   entry: {
     cli: "src/cli.ts",
+    runtimeVersion: "src/runtimeVersion.ts",
     shaderTransitionWorker: "../producer/src/services/shaderTransitionWorker.ts",
   },
   format: ["esm"],