fix: guard showcase installs from incompatible Node versions (#77)

Author: icecreamx10

lynxtron-go/src/main/desktop/preload-showcase-service.ts

@@ -4,12 +4,15 @@ import os from 'os';
 import path from 'path';
 import {
   buildShowcaseInstallEnv,
+  formatShowcaseInstallNodeCompatibilityError,
   getShowcaseDependencyStatus as computeShowcaseDependencyStatus,
   getShowcaseTargets,
   hasShowcaseScript,
   hasShowcaseSourceChangesSinceBuild,
   hasShowcaseWebSourceChangesSinceBuild,
   isShowcaseWebBuilt,
+  isNodeVersionSatisfied,
+  SHOWCASE_INSTALL_NODE_RANGE,
 } from './showcase-install';
 import { readInstallState, writeInstallState } from './preload-config-store';
 import type { DebugLogger } from './preload-log';
@@ -202,6 +205,29 @@ function getShowcaseDependencyStatus(showcasePath: string, dbg: DebugLogger) {
   return status;
 }
 
+function readInstallNodeVersion(env: NodeJS.ProcessEnv): string | null {
+  const nodeCommand = process.platform === 'win32' ? 'node.exe' : 'node';
+  try {
+    return execFileSync(nodeCommand, ['--version'], {
+      env,
+      encoding: 'utf-8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim().replace(/^v/i, '') || null;
+  } catch {
+    return null;
+  }
+}
+
+function assertCompatibleInstallNode(env: NodeJS.ProcessEnv) {
+  const nodeVersion = readInstallNodeVersion(env);
+  if (!nodeVersion) {
+    throw new Error('Node.js was not detected. Install Node.js (including npm), then retry.');
+  }
+  if (!isNodeVersionSatisfied(nodeVersion, SHOWCASE_INSTALL_NODE_RANGE)) {
+    throw new Error(formatShowcaseInstallNodeCompatibilityError(nodeVersion));
+  }
+}
+
 async function ensureShowcaseDependencies(
   showcasePath: string,
   dbg: DebugLogger,
@@ -214,6 +240,8 @@ async function ensureShowcaseDependencies(
   }
 
   const commandText = `${status.installPlan.command} ${status.installPlan.args.join(' ')}`;
+  const installEnv = buildShowcaseInstallEnv(status.installPlan.userConfigPath);
+  assertCompatibleInstallNode(installEnv);
   dbg(
     `showcase.install: cwd=${status.installPlan.cwd} reason=${force ? 'forced' : status.reason} command=${commandText}`
     + (status.installPlan.userConfigPath ? ` userconfig=${status.installPlan.userConfigPath}` : '')
@@ -226,7 +254,7 @@ async function ensureShowcaseDependencies(
       command: status.installPlan.command,
       args: status.installPlan.args,
       cwd: status.installPlan.cwd,
-      env: buildShowcaseInstallEnv(status.installPlan.userConfigPath),
+      env: installEnv,
       outputBuffer,
     });
   } catch (error: any) {

lynxtron-go/src/main/desktop/showcase-install.test.ts

@@ -6,6 +6,7 @@ import path from 'path';
 import { afterEach, describe, expect, it } from 'vitest';
 import {
   buildShowcaseInstallEnv,
+  formatShowcaseInstallNodeCompatibilityError,
   formatNodeVersionRequirementError,
   getShowcaseTargets,
   getShowcaseDependencyStatus,
@@ -17,6 +18,7 @@ import {
   hasShowcaseWebSourceChangesSinceBuild,
   isShowcaseWebBuilt,
   isNodeVersionSatisfied,
+  SHOWCASE_INSTALL_NODE_RANGE,
 } from './showcase-install';
 
 function writeJson(filePath: string, value: unknown) {
@@ -315,13 +317,28 @@ describe('showcase install helpers', () => {
     expect(isNodeVersionSatisfied('23.0.0', '>=22 <23')).toBe(false);
   });
 
+  it('rejects only Node versions affected by the legacy extract-zip stream regression', () => {
+    expect(isNodeVersionSatisfied('22.0.0', SHOWCASE_INSTALL_NODE_RANGE)).toBe(true);
+    expect(isNodeVersionSatisfied('24.15.99', SHOWCASE_INSTALL_NODE_RANGE)).toBe(true);
+    expect(isNodeVersionSatisfied('24.16.0', SHOWCASE_INSTALL_NODE_RANGE)).toBe(false);
+    expect(isNodeVersionSatisfied('24.17.99', SHOWCASE_INSTALL_NODE_RANGE)).toBe(false);
+    expect(isNodeVersionSatisfied('24.18.0', SHOWCASE_INSTALL_NODE_RANGE)).toBe(true);
+    expect(isNodeVersionSatisfied('25.9.0', SHOWCASE_INSTALL_NODE_RANGE)).toBe(true);
+    expect(isNodeVersionSatisfied('26.0.0', SHOWCASE_INSTALL_NODE_RANGE)).toBe(true);
+    expect(isNodeVersionSatisfied('26.1.0', SHOWCASE_INSTALL_NODE_RANGE)).toBe(false);
+    expect(isNodeVersionSatisfied('26.7.0', SHOWCASE_INSTALL_NODE_RANGE)).toBe(false);
+  });
+
+  it('formats an actionable showcase installer compatibility error', () => {
+    expect(formatShowcaseInstallNodeCompatibilityError('26.7.0'))
+      .toBe(`Node.js version 26.7.0 is incompatible with the Lynxtron showcase installer. Use a Node.js version matching ${SHOWCASE_INSTALL_NODE_RANGE}, then retry.`);
+  });
+
   it('formats a user-facing node version mismatch error', () => {
-    // npm runs with Lynxtron-as-node — the message must blame the runtime,
-    // not the system Node install.
     expect(formatNodeVersionRequirementError({ range: '>=22', sourceKind: 'engines' }, '20.11.1'))
-      .toBe("Lynxtron's Node.js version 20.11.1 does not satisfy required version >=22. Update Lynxtron to a build shipping Node 22 or newer.");
+      .toBe('Node.js version 20.11.1 does not satisfy required version >=22. Update Node to 22 or newer, then retry.');
     expect(formatNodeVersionRequirementError({ range: '22', sourceKind: 'nvmrc' }, null))
-      .toBe("Lynxtron's Node.js runtime was not detected. Reinstall or update Lynxtron and retry.");
+      .toBe('Node.js was not detected. Install Node 22.x (including npm), then retry.');
   });
 
   it('detects saved source changes newer than dist', () => {

lynxtron-go/src/main/desktop/showcase-install.ts

@@ -33,6 +33,12 @@ export interface NodeVersionRequirement {
 
 export type ShowcaseTarget = 'desktop' | 'web';
 
+// @lynx-js/lynxtron <= 0.0.15 installs its runtime with extract-zip@2.0.1,
+// whose yauzl@2.x stream can hang on Node 24.16-24.17 and Node >=26.1.
+// Node 24.18 reverted the stream regression; keep the upper bound conservative
+// until the Node 26 line ships and verifies the corresponding fix.
+export const SHOWCASE_INSTALL_NODE_RANGE = '>=22 <24.16.0 || >=24.18.0 <26.1.0';
+
 const SOURCE_SKIP_DIRS = new Set([
   '.git',
   'node_modules',
@@ -285,6 +291,10 @@ export function isNodeVersionSatisfied(currentVersion: string, range: string): b
   return disjunctions.some(part => tokenizeNodeRange(part).every(token => satisfiesRangeToken(versionParts, token)));
 }
 
+export function formatShowcaseInstallNodeCompatibilityError(currentVersion: string): string {
+  return `Node.js version ${currentVersion} is incompatible with the Lynxtron showcase installer. Use a Node.js version matching ${SHOWCASE_INSTALL_NODE_RANGE}, then retry.`;
+}
+
 function describeNodeVersionRange(range: string): string {
   const trimmed = range.trim();
   const atLeastMatch = trimmed.match(/^>=\s*v?(\d+)(?:\.(\d+))?(?:\.(\d+))?$/);
@@ -307,10 +317,10 @@ export function formatNodeVersionRequirementError(
 ): string {
   const installHint = describeNodeVersionRange(requirement.range);
   if (!currentVersion) {
-    return `Node.js was not detected. Install Node ${installHint} or newer (including npm), then retry.`;
+    return `Node.js was not detected. Install Node ${installHint} (including npm), then retry.`;
   }
 
-  return `Node.js version ${currentVersion} does not satisfy required version ${requirement.range}. Update Node to ${installHint} or newer, then retry.`;
+  return `Node.js version ${currentVersion} does not satisfy required version ${requirement.range}. Update Node to ${installHint}, then retry.`;
 }
 
 export function getShowcaseInstallPlan(showcasePath: string): ShowcaseInstallPlan {