build(node): enforce direct dependency engine floor (#1337)

Why:
- The root Node 20.9 contract predates direct runtime dependencies whose declared minimums now reach Node 22.19.
- README, contributor, localized docs, and the OpenMAIC extension skill repeated the stale supported-version claim.

What:
- Raise the root Node minimum to 22.19 and align every operator, contributor, locale, and skill prerequisite.
- Add a check that compares the root minimum with installed direct production dependency engine minimums.
- Run the new contract check in CI after the frozen dependency install.

Risk:
- This changes the declared minimum only; no upper bound is added and Node 24 compatibility remains a separate concern.
- The localized docs build was validated with the independent #1306 boundary fix from PR #1307, which is not included here.

Tests:
- RED on the base: engine check reported pi-agent-core, pi-ai, svg-pathdata, and undici floors
- GREEN: root minimum 22.19 satisfies 35 engine-constrained direct dependencies
- Node 20 lockfile-only install reports the root unsupported-engine warning
- Node 22 frozen install and postinstall
- Docs build with PR #1307 boundary: 34 pages and all locale postexport checks; docs types:check
- Root Prettier, ESLint, TypeScript, i18n, package-version, and internal-dependency gates
- Root pnpm test: 7137 passed, 81 skipped

Live Docs:
- GitHub issue #1304 tracks the Node contract; #1306 / PR #1307 tracks the separate docs-build prerequisite.

Co-authored-by: wyuc <wang-yc24@mails.tsinghua.edu.cn>
This commit is contained in:
Zhenghan Song 2026-09-02 16:29:52 +08:00 committed by GitHub
parent e58c700082
commit ca3d785221
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
19 changed files with 94 additions and 17 deletions

View File

@ -90,6 +90,9 @@ jobs:
- run: pnpm install --frozen-lockfile
- name: Node engine contract
run: pnpm check:node-engine
# `postinstall` builds all five @openmaic packages, and some of them
# generate tracked, publishable files (renderer's fonts.css and its KaTeX
# font snapshot). The publish workflow refuses to release when the build

View File

@ -24,7 +24,7 @@ To avoid duplicate effort, please **comment on an issue** to claim it before you
## Prerequisites
- [Node.js](https://nodejs.org/) >= 20.9.0
- [Node.js](https://nodejs.org/) >= 22.19.0
- [pnpm](https://pnpm.io/) (latest)
- A copy of `.env.local` — see [`.env.example`](.env.example) for reference

View File

@ -92,7 +92,7 @@ https://github.com/user-attachments/assets/dbd013f6-9fab-43c5-a788-b47126cff7a8
### 环境要求
- **Node.js** >= 20
- **Node.js** >= 22.19
- **pnpm** >= 10
### 1. 克隆 & 安装

View File

@ -105,7 +105,7 @@ https://github.com/user-attachments/assets/b4ab35ac-f994-46b1-8957-e82fe87ff0e9
### Prerequisites
- **Node.js** >= 20
- **Node.js** >= 22.19
- **pnpm** >= 10
### 1. Clone & Install

View File

@ -4,7 +4,7 @@
"private": true,
"license": "MIT",
"engines": {
"node": ">=20.9.0"
"node": ">=22.19.0"
},
"scripts": {
"postinstall": "cd packages/mathml2omml && npm run build && cd ../pptxgenjs && npm run build && cd ../@openmaic/dsl && pnpm run build && cd ../generation && pnpm run build && cd ../storage && pnpm run build && cd ../importer && pnpm run build && cd ../renderer && pnpm run build && cd ../editor && pnpm run build && cd ../../.. && node scripts/sync-maic-importer.mjs",
@ -17,6 +17,7 @@
"start": "next start",
"lint": "eslint",
"check:i18n-keys": "node scripts/check-i18n-keys.mjs",
"check:node-engine": "node scripts/check-node-engine-contract.mjs",
"check:package-versions": "node scripts/check-package-version-bumps.mjs",
"check": "prettier . --check",
"format": "prettier . --write",

View File

@ -56,7 +56,7 @@ services:
## الاستضافة الذاتية على جهاز افتراضي
يحتاج المضيف إلى Node.js `20.9.0` أو أحدث، وpnpm `10.28.0`. قم بالبناء والتشغيل باستخدام `pnpm`:
يحتاج المضيف إلى Node.js `22.19.0` أو أحدث، وpnpm `10.28.0`. قم بالبناء والتشغيل باستخدام `pnpm`:
```bash
pnpm install

View File

@ -56,7 +56,7 @@ Docker コンテナ内の `localhost` はコンテナ自身を指します。ホ
## 自前の仮想マシンでのセルフホスト
ホストには Node.js `20.9.0` 以上と pnpm `10.28.0` が必要です。`pnpm` でビルドして起動します:
ホストには Node.js `22.19.0` 以上と pnpm `10.28.0` が必要です。`pnpm` でビルドして起動します:
```bash
pnpm install

View File

@ -56,7 +56,7 @@ Inside a Docker container, `localhost` refers to the container itself. If Ollama
## Self-host on a VM
The host needs Node.js `20.9.0` or later and pnpm `10.28.0`. Build and start with `pnpm`:
The host needs Node.js `22.19.0` or later and pnpm `10.28.0`. Build and start with `pnpm`:
```bash
pnpm install

View File

@ -56,7 +56,7 @@ services:
## Самостоятельный хостинг на виртуальной машине
Требуется Node.js версии не ниже `20.9.0` и pnpm `10.28.0`. Соберите и запустите через `pnpm`:
Требуется Node.js версии не ниже `22.19.0` и pnpm `10.28.0`. Соберите и запустите через `pnpm`:
```bash
pnpm install

View File

@ -56,7 +56,7 @@ Docker 容器中的 `localhost` 指向容器自身。若 Ollama、Lemonade、Vox
## 自建虚拟机
主机需要 Node.js `20.9.0` 或更高版本,以及 pnpm `10.28.0`。用 `pnpm` 构建并启动:
主机需要 Node.js `22.19.0` 或更高版本,以及 pnpm `10.28.0`。用 `pnpm` 构建并启动:
```bash
pnpm install

View File

@ -56,7 +56,7 @@ Docker 容器中的 `localhost` 指向容器本身。若 Ollama、Lemonade、Vox
## 自建 VM
主機需要 Node.js `20.9.0` 或更新版本,以及 pnpm `10.28.0`。使用 `pnpm` 建置並啟動:
主機需要 Node.js `22.19.0` 或更新版本,以及 pnpm `10.28.0`。使用 `pnpm` 建置並啟動:
```bash
pnpm install

View File

@ -7,7 +7,7 @@ OpenMAIC هو تطبيق Next.js يمكن تشغيله على جهازك الخ
## المتطلبات المسبقة
- **Node.js** 20.9.0 أو أحدث
- **Node.js** 22.19.0 أو أحدث
- **pnpm** 10.28.0 (إذا لم يكن مثبتًا، نفذ `npm install -g pnpm@10.28.0`)
- إعداد مزود LLM واحد على الأقل؛ عادةً ما تتطلب المزودات السحابية مفتاح API، أما Ollama أو Lemonade المحليان فلا يحتاجان إلى مفتاح API

View File

@ -7,7 +7,7 @@ OpenMAIC は自分のマシンで動かせる Next.js アプリケーション
## 前提条件
- **Node.js** 20.9.0 以上
- **Node.js** 22.19.0 以上
- **pnpm** 10.28.0(未インストールの場合は `npm install -g pnpm@10.28.0`)
- 少なくとも 1 つの LLM プロバイダーを設定。クラウドのプロバイダーは通常 API key が必要、ローカルの Ollama や Lemonade は API key 不要

View File

@ -7,7 +7,7 @@ OpenMAIC is a Next.js application that runs on your own machine. You need to con
## Prerequisites
- **Node.js** 20.9.0 or later
- **Node.js** 22.19.0 or later
- **pnpm** 10.28.0 (if needed, run `npm install -g pnpm@10.28.0`)
- At least one LLM provider; cloud providers usually require an API key, while local Ollama or Lemonade does not

View File

@ -7,7 +7,7 @@ OpenMAIC — это приложение на Next.js, которое можно
## Предварительные требования
- **Node.js** версии 20.9.0 или выше
- **Node.js** версии 22.19.0 или выше
- **pnpm** версии 10.28.0 (если не установлен, выполните `npm install -g pnpm@10.28.0`)
- Настроить как минимум одного LLM-провайдера; облачные провайдеры обычно требуют API key, локальные Ollama или Lemonade — нет

View File

@ -7,7 +7,7 @@ OpenMAIC 是一个 Next.js 应用,可以在自己的机器上运行。你需
## 前置条件
- **Node.js** 20.9.0 或更高
- **Node.js** 22.19.0 或更高
- **pnpm** 10.28.0(如果没装,先 `npm install -g pnpm@10.28.0`)
- 至少配置一个 LLM provider;云端 provider 通常需要 API key,本地 Ollama 或 Lemonade 不需要 API key

View File

@ -7,7 +7,7 @@ OpenMAIC 是一個 Next.js 應用程式,可以在自己的機器上執行。
## 前置條件
- **Node.js** 20.9.0 或更新版本
- **Node.js** 22.19.0 或更新版本
- **pnpm** 10.28.0(如果尚未安裝,請先執行 `npm install -g pnpm@10.28.0`)
- 至少設定一個 LLM provider;雲端 provider 通常需要 API key,本機 Ollama 或 Lemonade 不需要 API key

View File

@ -0,0 +1,73 @@
import { readFileSync } from 'node:fs';
import { dirname, join } from 'node:path';
import { fileURLToPath } from 'node:url';
import semver from 'semver';
const repositoryRoot = dirname(fileURLToPath(new URL('../package.json', import.meta.url)));
function readManifest(path) {
return JSON.parse(readFileSync(path, 'utf8'));
}
function fail(headline, problems) {
console.error([headline, ...problems.map((problem) => `- ${problem}`)].join('\n'));
process.exit(1);
}
const rootManifest = readManifest(join(repositoryRoot, 'package.json'));
const rootRange = rootManifest.engines?.node;
const rootMinimum = rootRange ? semver.minVersion(rootRange) : null;
if (!rootRange || rootMinimum === null) {
fail('The root Node engine contract is invalid:', [
`package.json engines.node must be a valid semver range, got ${JSON.stringify(rootRange)}.`,
]);
}
const failures = [];
let constrainedDependencies = 0;
for (const dependency of Object.keys(rootManifest.dependencies ?? {}).sort()) {
const manifestPath = join(
repositoryRoot,
'node_modules',
...dependency.split('/'),
'package.json',
);
let manifest;
try {
manifest = readManifest(manifestPath);
} catch (error) {
failures.push(
`cannot read installed manifest for ${dependency} at ${manifestPath}: ${String(error)}. ` +
'Run pnpm install before this check.',
);
continue;
}
const dependencyRange = manifest.engines?.node;
if (!dependencyRange) continue;
constrainedDependencies += 1;
const dependencyMinimum = semver.minVersion(dependencyRange);
if (dependencyMinimum === null) {
failures.push(
`${dependency} declares an invalid engines.node range: ${JSON.stringify(dependencyRange)}.`,
);
continue;
}
if (semver.lt(rootMinimum, dependencyMinimum)) {
failures.push(
`root engines.node ${JSON.stringify(rootRange)} starts at ${rootMinimum.version}, below ` +
`${dependency}@${manifest.version} engines.node ${JSON.stringify(dependencyRange)} ` +
`(minimum ${dependencyMinimum.version}).`,
);
}
}
if (failures.length > 0) {
fail('The root Node engine minimum is below its direct production dependencies:', failures);
}
console.log(
`Node engine contract passed: root minimum ${rootMinimum.version} satisfies ` +
`${constrainedDependencies} engine-constrained direct production dependencies.`,
);

View File

@ -9,7 +9,7 @@ This reference takes priority over the `accessCode` auto-shortcut in Phase 0: if
## Secondary-Development Rules
1. **Read before edit.** Before changing any file, read it (and the symbols it imports) so the edit matches surrounding conventions. Do not paste large code blocks into chat — point the user at `file:line` entry points and let them read.
2. **Toolchain is hard-required.** `pnpm@10.28.0` (root `packageManager`), Node `>=20.9` (`.nvmrc` pins `22`). Mismatched pnpm will fail install.
2. **Toolchain is hard-required.** `pnpm@10.28.0` (root `packageManager`), Node `>=22.19.0` (`.nvmrc` pins `22`). Mismatched pnpm will fail install.
3. **Forking and disabling CI are conditional, not defaults.** Decide per the user's intent — see Development Environment below — instead of reflexively forking every user.
## Development Environment (Same As Local Deployment)