Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

chore(tooling): align build target across the workspace (#339)

Myriad-Dreamin449a5341a8e2
diff --git a/changelog/unreleased/2026-08-19-tsup-node-target.md b/changelog/unreleased/2026-08-19-tsup-node-target.md
new file mode 100644
index 00000000..5ac6442d
--- /dev/null
+++ b/changelog/unreleased/2026-08-19-tsup-node-target.md
@@ -0,0 +1,30 @@
+# One Node build target across the workspace
+
+- **Date:** 2026-08-19
+- **Type:** process
+- **Scope:** `tooling`, `core`, `cli`, `server`, `skills`, `desktop`
+
+[中文版](2026-08-19-tsup-node-target.zh.md)
+
+Every package now compiles for the same Node version — `node24` — and the two published
+libraries that had never said which Node they need now declare it.
+
+`target` in a tsup config is the syntax level esbuild emits down to. It had drifted to five
+independent answers: `node20` for core, cli and skills, `node22` for server and desktop,
+while `engines.node` on the packages that declare it requires `>= 24`, CI runs Node 24 and
+releases ship a 24 runtime. Nothing was broken by it — targeting an older Node only means
+output that could have been left alone gets transpiled — but "which Node do we build for"
+had no single answer, and every new package was a coin flip.
+
+## Details
+
+- `@prismshadow/penguin-core` and `@prismshadow/penguin-skills` gain
+ `engines: { "node": ">=24" }`. They are published, they now emit Node 24 syntax, and
+ saying so is what surfaces the mismatch while a Node 20 user is installing — npm reports
+ `EBADENGINE`, and refuses outright under `engine-strict` — rather than letting them meet a
+ `SyntaxError` at import time. Both are already built and tested only on 24, and both are
+ consumed by packages that require it.
+- A drift guard in `packages/cli/test/tsup-target.test.ts` asserts every tsup config
+ declares the same target and that no published package emits syntax newer than its
+ `engines` admits to needing. It lives in `packages/cli` because the repo root runs no
+ suite of its own, following `dev-script-entry.test.ts`.
diff --git a/changelog/unreleased/2026-08-19-tsup-node-target.zh.md b/changelog/unreleased/2026-08-19-tsup-node-target.zh.md
new file mode 100644
index 00000000..5bbb86fb
--- /dev/null
+++ b/changelog/unreleased/2026-08-19-tsup-node-target.zh.md
@@ -0,0 +1,16 @@
+# 全仓库统一 Node 构建目标
+
+- **Date:** 2026-08-19
+- **Type:** process
+- **Scope:** `tooling`, `core`, `cli`, `server`, `skills`, `desktop`
+
+[English](2026-08-19-tsup-node-target.md)
+
+现在每个包都按同一个 Node 版本编译——`node24`——而此前两个从未声明过自己需要哪个 Node 的已发布库,也把它写了出来。
+
+tsup 配置里的 `target` 是 esbuild 向下降级到的语法级别。它此前漂移成了五个各自为政的答案:core、cli、skills 是 `node20`,server 与 desktop 是 `node22`,而声明了 `engines.node` 的那些包要求 `>= 24`,CI 跑的是 Node 24,发布物里随包分发的运行时也是 24。这并没有弄坏什么——把目标定低只意味着本可以原样保留的语法被多降级了一遍——但「我们到底为哪个 Node 构建」没有唯一答案,于是每新增一个包就是一次掷硬币。
+
+## 细节
+
+- `@prismshadow/penguin-core` 与 `@prismshadow/penguin-skills` 新增 `engines: { "node": ">=24" }`。它们是对外发布的包,现在会产出 Node 24 的语法,把这一点声明出来,Node 20 的用户才会在安装阶段就看到不兼容——npm 会报出 `EBADENGINE` 警告,开启 `engine-strict` 时更是直接拒绝安装——而不是在 import 时撞上 `SyntaxError`。这两个包本来也只在 24 上构建与测试,且都被要求 24 的包所依赖。
+- `packages/cli/test/tsup-target.test.ts` 里的漂移守卫会断言所有 tsup 配置声明同一个 target,并且任何已发布的包都不会产出比它 `engines` 所承认的更新的语法。它放在 `packages/cli` 是因为仓库根目录本身不跑测试套件——沿用 `dev-script-entry.test.ts` 的做法。
diff --git a/packages/cli/test/tsup-target.test.ts b/packages/cli/test/tsup-target.test.ts
new file mode 100644
index 00000000..9863ac8b
--- /dev/null
+++ b/packages/cli/test/tsup-target.test.ts
@@ -0,0 +1,97 @@
+/**
+ * Drift guard for the Node version every bundle is compiled against.
+ *
+ * `target` in a tsup config is the syntax level esbuild emits down to, and each package had
+ * drifted to its own answer — node20 for core, cli and skills, node22 for server and
+ * desktop — while the packages that declare `engines` all require Node >= 24, CI runs 24,
+ * and releases ship a 24 runtime. Nothing broke, because targeting an older Node only means
+ * output that could have been left alone gets transpiled; the cost is that "which Node do
+ * we build for" had five answers and no one of them was right.
+ *
+ * The rule this pins: one target across every package, and it agrees with the `engines`
+ * requirement those packages publish. A published package must never emit syntax older Node
+ * cannot parse without saying so in `engines` — that declaration is what makes the mismatch
+ * surface at install time, as npm's `EBADENGINE` warning and as an outright refusal under
+ * `engine-strict`, instead of the user meeting a SyntaxError at import time.
+ *
+ * Lives here rather than at the repo root because the root runs no test suite of its own,
+ * following dev-script-entry.test.ts.
+ */
+import { readFileSync, readdirSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "..");
+const packagesDir = path.join(repoRoot, "packages");
+
+/** Every package that builds with tsup, as [name, config source, package.json]. */
+const tsupPackages = readdirSync(packagesDir)
+ .map((name) => ({ name, dir: path.join(packagesDir, name) }))
+ .map(({ name, dir }) => ({
+ name,
+ configPath: path.join(dir, "tsup.config.ts"),
+ pkgPath: path.join(dir, "package.json"),
+ }))
+ .filter(({ configPath }) => {
+ try {
+ readFileSync(configPath);
+ return true;
+ } catch {
+ return false;
+ }
+ });
+
+/** The `target: "nodeNN"` a config declares. Read as text: importing it would run tsup's. */
+function declaredTarget(configPath: string): string | null {
+ return /target:\s*"(node\d+)"/.exec(readFileSync(configPath, "utf8"))?.[1] ?? null;
+}
+
+/**
+ * The major from an `engines.node` range, which this workspace always writes as `>=NN`.
+ *
+ * Anchored to that one form on purpose: a loose digit scan would read `"<24"` as major 24 and
+ * wave through a package whose declared runtimes are all older than the syntax it emits.
+ * Anything but `>=NN` reads as no answer, and the caller fails the package rather than
+ * guessing at the range's meaning.
+ */
+function requiredMajor(pkgPath: string): number | null {
+ const engines = (JSON.parse(readFileSync(pkgPath, "utf8")) as { engines?: { node?: string } })
+ .engines?.node;
+ const major = engines === undefined ? undefined : /^\s*>=\s*(\d+)\s*$/.exec(engines)?.[1];
+ return major === undefined ? null : Number(major);
+}
+
+describe("tsup build target", () => {
+ it("covers every package that builds with tsup", () => {
+ expect(tsupPackages.map((p) => p.name).sort()).toEqual([
+ "cli",
+ "core",
+ "desktop",
+ "server",
+ "skills",
+ ]);
+ });
+
+ it("is the same Node version everywhere", () => {
+ const targets = tsupPackages.map(({ name, configPath }) => [name, declaredTarget(configPath)]);
+ expect(Object.fromEntries(targets)).toEqual(
+ Object.fromEntries(tsupPackages.map(({ name }) => [name, "node24"])),
+ );
+ });
+
+ it("never emits syntax newer than a published package admits to needing", () => {
+ for (const { name, configPath, pkgPath } of tsupPackages) {
+ const target = declaredTarget(configPath);
+ const required = requiredMajor(pkgPath);
+ const published = !(JSON.parse(readFileSync(pkgPath, "utf8")) as { private?: boolean })
+ .private;
+ if (!published) continue;
+ expect(
+ required,
+ `${name} builds for ${target} but declares no engines.node range of the form ">=NN"`,
+ ).not.toBeNull();
+ expect(`node${required}`, `${name}: engines.node and tsup target disagree`).toBe(target);
+ }
+ });
+});
diff --git a/packages/cli/tsup.config.ts b/packages/cli/tsup.config.ts
index 83c21d87..816ce81b 100644
--- a/packages/cli/tsup.config.ts
+++ b/packages/cli/tsup.config.ts
@@ -3,7 +3,7 @@ import { defineConfig } from "tsup";
export default defineConfig({
entry: ["src/penguin.ts", "src/penguin-hmr.ts"],
format: ["esm"],
- target: "node20",
+ target: "node24",
platform: "node",
clean: true,
sourcemap: true,
diff --git a/packages/core/package.json b/packages/core/package.json
index 442ac68c..01cb5db1 100644
--- a/packages/core/package.json
+++ b/packages/core/package.json
@@ -2,6 +2,9 @@
"name": "@prismshadow/penguin-core",
"version": "0.2.3",
"type": "module",
+ "engines": {
+ "node": ">=24"
+ },
"description": "PenguinHarness core SDK: context_engine, OmniMessage protocol, LLM/Environment interfaces.",
"license": "Apache-2.0",
"repository": {
diff --git a/packages/core/tsup.config.ts b/packages/core/tsup.config.ts
index 673bafea..f310d37c 100644
--- a/packages/core/tsup.config.ts
+++ b/packages/core/tsup.config.ts
@@ -14,7 +14,7 @@ export default defineConfig({
"src/kernel/index.ts",
],
format: ["esm"],
- target: "node20",
+ target: "node24",
dts: true,
clean: true,
sourcemap: true,
diff --git a/packages/desktop/tsup.config.ts b/packages/desktop/tsup.config.ts
index 21542500..2e9c9555 100644
--- a/packages/desktop/tsup.config.ts
+++ b/packages/desktop/tsup.config.ts
@@ -18,7 +18,7 @@ export default defineConfig({
penguin: "../cli/dist/penguin.js",
},
format: ["esm"],
- target: "node22",
+ target: "node24",
platform: "node",
clean: true,
// Generated for a source run; electron-builder.yml keeps the .map files out of installers,
diff --git a/packages/server/tsup.config.ts b/packages/server/tsup.config.ts
index ead83e94..162f3a85 100644
--- a/packages/server/tsup.config.ts
+++ b/packages/server/tsup.config.ts
@@ -19,7 +19,7 @@ export default defineConfig({
"hmr/manifest": "src/hmr/manifest.ts",
},
format: ["esm"],
- target: "node22",
+ target: "node24",
dts: true,
clean: true,
sourcemap: true,
diff --git a/packages/skills/package.json b/packages/skills/package.json
index 97bcebf0..3c4343ff 100644
--- a/packages/skills/package.json
+++ b/packages/skills/package.json
@@ -2,6 +2,9 @@
"name": "@prismshadow/penguin-skills",
"version": "0.2.3",
"type": "module",
+ "engines": {
+ "node": ">=24"
+ },
"description": "PenguinHarness skill library: built-in SKILL.md documents and skill groups, decoupled from core.",
"license": "Apache-2.0",
"repository": {
diff --git a/packages/skills/tsup.config.ts b/packages/skills/tsup.config.ts
index 75bf9033..30688a7a 100644
--- a/packages/skills/tsup.config.ts
+++ b/packages/skills/tsup.config.ts
@@ -3,7 +3,7 @@ import { defineConfig } from "tsup";
export default defineConfig({
entry: ["src/index.ts"],
format: ["esm"],
- target: "node20",
+ target: "node24",
dts: true,
clean: true,
sourcemap: true,