@chenmk/superflow 0.5.0 → 0.5.1

package/INSTALL.en.md

@@ -11,6 +11,10 @@ aliases, scripts, rules, and handoff state for Claude Code and Codex.
 npm install -g @chenmk/superflow
 ```
 
+> **Node.js requirement:** Node.js 20 or later is required. If `node -v` is older,
+> installation stops before command aliases are created. With nvm, run
+> `nvm install 22 && nvm use 22 && nvm alias default 22`, open a new terminal, and reinstall.
+
 The repository `install.sh` and `install.ps1` scripts detect the Codex/Claude
 Hosts actually installed and register their managed MCP entries together with
 CLI, Skills, and Hooks. Single and non-default Host combinations are not forced

package/INSTALL.md

@@ -28,6 +28,9 @@ docs -> design -> implement -> verify -> archive
 | Shell | macOS/Linux 原生 shell；Windows 使用 Git Bash 或兼容 shell | `bash --version` |
 | Python | hook 中的 Python 脚本需要 | `python3 --version` |
 
+> **Node 版本不足：** 安装会在创建命令前停止。若已安装 nvm，运行
+> `nvm install 22 && nvm use 22 && nvm alias default 22`，重新打开终端后再安装。
+
 支持系统：
 
 - macOS 10.15+

package/README.md

@@ -154,6 +154,9 @@ Each phase has a clear owner and an exit gate:
 npm install -g @chenmk/superflow
 ```
 
+> **Node.js requirement:** Node.js 20 or later is required. On an older runtime,
+> installation stops before command aliases are created and prints Node 22 upgrade instructions.
+
 For a source checkout, `bash install.sh` detects installed Codex, Claude, and
 Codex and Claude Hosts and installs CLI, Skills/Hooks, and their managed MCP registrations
 in one pass. Restart the detected Hosts afterwards.

package/README.zh-CN.md

@@ -105,6 +105,8 @@ npm install -g @chenmk/superflow
 # git clone https://github.com/.../superflow-cli && cd superflow-cli && bash install.sh
 ```
 
+> **Node.js 要求：** 需要 Node.js 20+。版本不足时，安装会在创建命令前停止，并打印 Node 22 的升级和重装指引。
+
 完整安装、初始化和日常使用教程见 [INSTALL.md](./INSTALL.md)。
 
 从源码执行 `bash install.sh` 时，会检测本机已有的 Codex、Claude，并一次完成

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chenmk/superflow",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "SuperBridge Flow workflow CLI for Claude Code and Codex",
   "license": "MIT",
   "type": "module",
@@ -40,6 +40,7 @@
     "prebuild": "npm run check:design-principles && npm run check:managed-design",
     "build": "node scripts/clean-dist.js && tsc && node scripts/ensure-bin-modes.js",
     "dev": "tsx watch src/cli/index.ts",
+    "preinstall": "node scripts/preinstall.js",
     "postinstall": "node scripts/postinstall.js",
     "prepack": "npm run build",
     "prepublishOnly": "npm run release:check && npm test && npm run build",

package/scripts/preinstall.js

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+import { resolveInstallLanguage } from './postinstall.js';
+
+const MIN_NODE_MAJOR = 20;
+
+export function nodeMajor(version) {
+  const match = String(version).match(/^v?(\d+)/);
+  return match ? Number.parseInt(match[1], 10) : 0;
+}
+
+export function isSupportedNode(version) {
+  return nodeMajor(version) >= MIN_NODE_MAJOR;
+}
+
+export function buildNodeVersionMessage(version, language) {
+  const commands = [
+    '  nvm install 22',
+    '  nvm use 22',
+    '  nvm alias default 22',
+  ].join('\n');
+
+  if (language === 'zh') {
+    return [
+      `[Superflow] 需要 Node.js ${MIN_NODE_MAJOR} 或更高版本，当前检测到 ${version}。`,
+      '',
+      '请先升级到 Node.js 22 LTS；Superflow 不会自动修改你的系统 Node。',
+      '若已安装 nvm，请运行：',
+      commands,
+      '',
+      '完成后重新打开终端，再运行：',
+      '  npm install -g @chenmk/superflow',
+      '未安装 nvm 时，请用系统包管理器或 https://nodejs.org 安装 Node.js 22 LTS。',
+    ].join('\n');
+  }
+
+  return [
+    `[Superflow] Node.js ${MIN_NODE_MAJOR} or later is required; detected ${version}.`,
+    '',
+    'Install Node.js 22 LTS first. Superflow never changes your system Node automatically.',
+    'If nvm is already installed, run:',
+    commands,
+    '',
+    'Open a new terminal, then rerun:',
+    '  npm install -g @chenmk/superflow',
+    'Without nvm, use your system package manager or https://nodejs.org to install Node.js 22 LTS.',
+  ].join('\n');
+}
+
+export function runPreinstall(version = process.versions.node, env = process.env) {
+  if (isSupportedNode(version)) return 0;
+  const language = resolveInstallLanguage(env);
+  console.error(buildNodeVersionMessage(version, language));
+  return 1;
+}
+
+const exitCode = runPreinstall();
+if (exitCode !== 0) process.exitCode = exitCode;