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:
parent
e58c700082
commit
ca3d785221
3
.github/workflows/ci.yml
vendored
3
.github/workflows/ci.yml
vendored
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
|
||||
@ -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. 克隆 & 安装
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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",
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
|
||||
@ -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 不要
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
|
||||
@ -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 — нет
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
|
||||
73
scripts/check-node-engine-contract.mjs
Normal file
73
scripts/check-node-engine-contract.mjs
Normal 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.`,
|
||||
);
|
||||
@ -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)
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user