A local-first multi-agent app development platform, built on PenguinHarness
fix(desktop,tooling): ESM bundles declare `__dirname` and `__filename`, not just `require` (#482)
Yaowei Zheng58dca0b38a45
diff --git a/changelog/unreleased/2026-08-27-desktop-bundle-cjs-globals.md b/changelog/unreleased/2026-08-27-desktop-bundle-cjs-globals.mdnew file mode 100644index 00000000..c4139fd7--- /dev/null+++ b/changelog/unreleased/2026-08-27-desktop-bundle-cjs-globals.md@@ -0,0 +1,41 @@+# The desktop app's Feishu binding connects again++- **Date:** 2026-08-27+- **Type:** fix+- **Scope:** `desktop`, `tooling`+- **PR:** [#482](https://github.com/Prism-Shadow/penguin-harness/pull/482)++[中文版](2026-08-27-desktop-bundle-cjs-globals.zh.md)++Binding a Feishu app from the desktop app failed at the credential test and at connect with+`__dirname is not defined`, so the messaging integration that shipped in 0.2.6+([#464](https://github.com/Prism-Shadow/penguin-harness/pull/464)) could not be used there at+all. Only the desktop app was affected: an npm or CLI install resolves+`@larksuiteoapi/node-sdk` from `node_modules`, where it runs as CommonJS and is handed its own+`__dirname`, while the desktop app bundles the server and the CLI into one self-contained ESM+file each and absorbs the SDK along with them. Those bundles carried a banner declaring+`require` for exactly this reason, but not `__filename` or `__dirname` — so the SDK's read of+its own `package.json`, which it uses to put a version into its User-Agent header, hit an+undeclared identifier and failed the whole connect attempt.++The banner was moved to a single definition in `scripts/esm-cjs-banner.mjs` and taught to+declare all three, and both bundling sites were pointed at it:+`packages/desktop/tsup.config.ts`, which builds the shipped app, and `compileEntry` in+`scripts/deploy.mjs`, which builds the hot-update platform and CLI bundles and would have met+the same wall on a push. Telegram bindings were never affected — that connector speaks HTTP+directly and loads no SDK.++## Details++The declarations restore the identifiers, not CommonJS's meaning of them: inside a bundle+`__dirname` names the bundle's own directory, not the directory the dependency was published+in. A dependency that reads it to find a file shipped beside itself still looks in the wrong+place, and one that must reach its own files cannot be bundled at all — which is why node-pty+ships as a real package directory next to the bundles instead. The Feishu SDK stays inside that+limit: its version lookup already falls back to `unknown` when it finds nothing, so the wrong+directory costs a version tag in a request header and nothing else.++The three are declared with `var` rather than `const`, so that a bundled module deriving+`__filename` and `__dirname` from `import.meta.url` itself — ordinary ESM boilerplate —+redeclares the name instead of colliding with it. A second lexical declaration of a name the+banner has already bound is a parse error that takes the whole bundle down at load.diff --git a/changelog/unreleased/2026-08-27-desktop-bundle-cjs-globals.zh.md b/changelog/unreleased/2026-08-27-desktop-bundle-cjs-globals.zh.mdnew file mode 100644index 00000000..244efb07--- /dev/null+++ b/changelog/unreleased/2026-08-27-desktop-bundle-cjs-globals.zh.md@@ -0,0 +1,31 @@+# 桌面应用重新能够连接飞书++- **Date:** 2026-08-27+- **Type:** fix+- **Scope:** `desktop`, `tooling`+- **PR:** [#482](https://github.com/Prism-Shadow/penguin-harness/pull/482)++[English](2026-08-27-desktop-bundle-cjs-globals.md)++在桌面应用中绑定飞书应用时,凭据测试与连接都以 `__dirname is not defined` 失败,0.2.6 交付的消息集成+([#464](https://github.com/Prism-Shadow/penguin-harness/pull/464))在桌面端完全不可用。只有桌面应用受影响:+npm 或 CLI 安装从 `node_modules` 解析 `@larksuiteoapi/node-sdk`,它在那里以 CommonJS 运行并获得自己的+`__dirname`;而桌面应用把 server 与 CLI 各自打成一个自包含的 ESM 文件,该 SDK 也被一并吸收进去。这些产物+携带的 banner 正是为此声明了 `require`,却没有声明 `__filename` 与 `__dirname`——于是 SDK 读取自身+`package.json`(用于在 User-Agent 头中带上版本号)时撞上未声明的标识符,整个连接过程随之失败。++banner 被收敛为 `scripts/esm-cjs-banner.mjs` 中的单一定义,并补齐了三者的声明,两处打包点都改为引用它:+构建发行应用的 `packages/desktop/tsup.config.ts`,以及构建热更新 platform 与 CLI 产物的+`scripts/deploy.mjs` 中的 `compileEntry`——后者在推送时会撞上同一堵墙。Telegram 绑定从未受影响:该+connector 直接使用 HTTP,不加载任何 SDK。++## 细节++这些声明恢复的是标识符本身,而非 CommonJS 赋予它的含义:在打包产物内部,`__dirname` 指向产物自身所在目录,+而不是该依赖发布时所处的目录。依赖若用它来寻找随自身一同发布的文件,仍会找错位置;而必须访问自身文件的依赖+根本不能被打包——node-pty 因此是以真实的包目录形式随产物一同交付的。飞书 SDK 处在该限制之内:其版本查找在+找不到时本就回退为 `unknown`,所以目录取错的代价仅是请求头中少了一个版本标记。++三者均以 `var` 而非 `const` 声明,使得某个被打包的模块若自行从 `import.meta.url` 推导 `__filename` 与+`__dirname`(常见的 ESM 样板写法),只是重复声明而不会与 banner 冲突。对 banner 已绑定的名字再作一次词法+声明会是解析错误,整个产物在加载时即告失败。diff --git a/packages/desktop/test/esm-cjs-banner.test.ts b/packages/desktop/test/esm-cjs-banner.test.tsnew file mode 100644index 00000000..585e748f--- /dev/null+++ b/packages/desktop/test/esm-cjs-banner.test.ts@@ -0,0 +1,177 @@+/**+ * The CJS-globals banner every ESM bundle in this repo carries (scripts/esm-cjs-banner.mjs).+ *+ * Bundling third-party CommonJS into an ESM file drops the module wrapper that supplied+ * `require`, `__filename` and `__dirname`, so each reference an absorbed dependency makes+ * has to find a declaration in the bundle's own top-level scope. The banner shipped only+ * `require` once, and `@larksuiteoapi/node-sdk`'s `__dirname` then failed the desktop app's+ * Feishu binding with `__dirname is not defined`. These tests pin all three: the banner's+ * own values, a real esbuild round-trip through a CJS dependency that reads them, the+ * redeclaration a bundled ESM module brings with it, and both bundling sites sourcing the+ * one banner rather than re-inlining a partial copy.+ *+ * Every module here is evaluated in a CHILD `node` process. Vitest runs test modules through+ * Vite's SSR runner, whose wrapper defines `__filename` and `__dirname` itself — importing+ * these fixtures in-process passes whether or not the banner declares anything, which is+ * exactly the failure being guarded against.+ */+import { execFileSync } from "node:child_process";+import fs from "node:fs";+import os from "node:os";+import path from "node:path";+import { fileURLToPath, pathToFileURL } from "node:url";+import { afterAll, describe, expect, it } from "vitest";+import { ESM_CJS_BANNER } from "../../../scripts/esm-cjs-banner.mjs";++/** The banner as it shipped in 0.2.6 — `require` alone, which is how `__dirname` slipped through. */+const REQUIRE_ONLY_BANNER =+ 'import { createRequire as __penguinCreateRequire } from "node:module"; const require = __penguinCreateRequire(import.meta.url);';++const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "..");++// Every path asserted below is compared against one Node reported, and Node resolves a module's+// real path before evaluating it — so the root they all derive from has to be a real one too.+// macOS gets there on its own, where os.tmpdir() is a /var/... symlink onto /private/var/...;+// reaching the root through a symlink of our own has every platform run that same resolution,+// so dropping the realpathSync fails here rather than on one runner only. `fs.realpathSync`+// and not its `.native` variant: that is the one the ESM loader uses, and the two disagree+// about Windows 8.3 short paths.+const tmpTarget = fs.mkdtempSync(path.join(os.tmpdir(), "penguin-esm-cjs-banner-"));+const tmpLink = `${tmpTarget}-link`;+fs.symlinkSync(tmpTarget, tmpLink, "junction");+const tmp = fs.realpathSync(tmpLink);+afterAll(() => {+ fs.rmSync(tmpLink, { recursive: true, force: true });+ fs.rmSync(tmp, { recursive: true, force: true });+});++/** Imports `moduleFile` in a real Node process and returns its `probe` export. */+function probeInNode(moduleFile: string): Record<string, unknown> {+ const runner = path.join(path.dirname(moduleFile), "run.mjs");+ fs.writeFileSync(+ runner,+ `const m = await import(${JSON.stringify(pathToFileURL(moduleFile).href)});\n` ++ `process.stdout.write(JSON.stringify(m.probe));\n`,+ );+ let stdout: string;+ try {+ // stderr is captured rather than inherited: one case below fails the child on purpose.+ stdout = execFileSync(process.execPath, [runner], {+ encoding: "utf8",+ stdio: ["ignore", "pipe", "pipe"],+ });+ } catch (err) {+ throw new Error(String((err as { stderr?: string }).stderr ?? (err as Error).message));+ }+ return JSON.parse(stdout);+}++/** A directory holding one fixture, so each case gets its own `run.mjs`. */+function caseDir(name: string): string {+ const dir = path.join(tmp, name);+ fs.mkdirSync(dir, { recursive: true });+ return dir;+}++/** Bundles `entry` to `outfile` the way both build sites do: ESM, node, banner attached. */+async function bundleWithBanner(entry: string, outfile: string): Promise<void> {+ const esbuild = await import("esbuild");+ await esbuild.build({+ entryPoints: [entry],+ bundle: true,+ format: "esm",+ platform: "node",+ outfile,+ logLevel: "silent",+ banner: { js: ESM_CJS_BANNER },+ });+}++describe("ESM_CJS_BANNER", () => {+ it("declares require, __filename and __dirname with the values CJS would have given", () => {+ const file = path.join(caseDir("values"), "probe.mjs");+ fs.writeFileSync(+ file,+ `${ESM_CJS_BANNER}\nexport const probe = { requireType: typeof require, sep: require("node:path").sep, filename: __filename, dirname: __dirname };\n`,+ );+ const probe = probeInNode(file);+ expect(probe.requireType).toBe("function");+ expect(probe.sep).toBe(path.sep);+ // Exactly CJS's spelling: the file itself, and its directory with no trailing separator.+ expect(probe.filename).toBe(file);+ expect(probe.dirname).toBe(path.dirname(file));+ });++ it("is what makes the difference — the require-only banner still throws", () => {+ const file = path.join(caseDir("require-only"), "probe.mjs");+ fs.writeFileSync(+ file,+ `${REQUIRE_ONLY_BANNER}\nexport const probe = { dirname: __dirname };\n`,+ );+ // Proves the harness can see the failure at all: without a child process, Vite's runner+ // supplies both globals and this case passes as readily as the one above.+ expect(() => probeInNode(file)).toThrow(/__dirname is not defined/);+ });++ it("carries a bundled CJS dependency's __dirname / __filename reads through esbuild", async () => {+ const dir = caseDir("bundle");+ // A CommonJS dependency of the shape that broke: it reads the globals its wrapper used+ // to supply, at module scope, unguarded.+ fs.writeFileSync(+ path.join(dir, "dep.cjs"),+ 'module.exports = { dir: __dirname, file: __filename, sep: require("node:path").sep };\n',+ );+ fs.writeFileSync(+ path.join(dir, "entry.mjs"),+ 'export { default as probe } from "./dep.cjs";\n',+ );++ const outfile = path.join(dir, "out.mjs");+ await bundleWithBanner(path.join(dir, "entry.mjs"), outfile);++ const probe = probeInNode(outfile);+ expect(probe.sep).toBe(path.sep);+ // The documented approximation: a bundled dependency sees the BUNDLE's location, not+ // the directory it was published in. Wrong for locating its own shipped files, but+ // defined — which is the whole difference between a wrong path and a hard crash.+ expect(probe.file).toBe(outfile);+ expect(probe.dir).toBe(dir);+ });++ it("survives a bundled module declaring __filename / __dirname of its own", async () => {+ const dir = caseDir("redeclare");+ // The boilerplate an ESM module writes to get the two names back. esbuild renames a+ // bundled module's own top-level `require` but leaves these two spelled as written, so a+ // `const` banner turns the whole bundle into a SyntaxError at load — a worse failure than+ // the one the banner exists to prevent.+ fs.writeFileSync(+ path.join(dir, "dep.mjs"),+ 'import { fileURLToPath } from "node:url";\nimport { dirname } from "node:path";\n' ++ "const __filename = fileURLToPath(import.meta.url);\n" ++ "const __dirname = dirname(__filename);\n" ++ "export const info = { dir: __dirname, file: __filename };\n",+ );+ fs.writeFileSync(path.join(dir, "entry.mjs"), 'export { info as probe } from "./dep.mjs";\n');++ const outfile = path.join(dir, "out.mjs");+ await bundleWithBanner(path.join(dir, "entry.mjs"), outfile);++ const probe = probeInNode(outfile);+ expect(probe.file).toBe(outfile);+ expect(probe.dir).toBe(dir);+ });+});++describe("bundling sites", () => {+ // Both emit ESM while absorbing third-party CommonJS, so both need the same declarations.+ // Sharing one constant is what keeps a fix to one of them from missing the other.+ const sites = ["packages/desktop/tsup.config.ts", "scripts/deploy.mjs"];++ it.each(sites)("%s takes its banner from scripts/esm-cjs-banner.mjs", (site) => {+ const source = fs.readFileSync(path.join(REPO_ROOT, site), "utf8");+ expect(source).toMatch(/import \{ ESM_CJS_BANNER \} from "[^"]*esm-cjs-banner\.mjs"/);+ expect(source).toMatch(/banner:\s*\{\s*js:\s*ESM_CJS_BANNER\s*\}/);+ // A hand-inlined banner is how the two drifted apart in the first place.+ expect(source).not.toMatch(/js:\s*['"`]import \{ createRequire/);+ });+});diff --git a/packages/desktop/tsup.config.ts b/packages/desktop/tsup.config.tsindex 240cc168..139359dd 100644--- a/packages/desktop/tsup.config.ts+++ b/packages/desktop/tsup.config.ts@@ -2,6 +2,9 @@ import { defineConfig } from "tsup";// Inlines this checkout's git identity into the artifact — see the helper's module doc:// the app bundles the server and the CLI whole, and a shipped bundle has no path back to the checkout it came from.import { buildGitDefine } from "../../scripts/build-git-stamp.mjs";+// The CJS globals these ESM bundles have to declare for the dependencies they absorb —+// see the helper's module doc for what the shim covers and where it only approximates.+import { ESM_CJS_BANNER } from "../../scripts/esm-cjs-banner.mjs";/*** Five self-contained bundles, no shared chunks: the shell itself, the server it forks as a@@ -34,12 +37,10 @@ export default defineConfig({// where they would roughly triple what these bundles add.sourcemap: true,splitting: false,- // Several bundled CJS dependencies (yaml, tar, smol-toml, commander, agenthub) call a bare- // `require(...)` inside their own wrapper, which esbuild's ESM output otherwise routes to a- // shim that always throws. Same banner scripts/deploy.mjs uses for the hot-update bundles.- banner: {- js: 'import { createRequire as __penguinCreateRequire } from "node:module"; const require = __penguinCreateRequire(import.meta.url);',- },+ // Load-bearing: bundled CJS dependencies reference `require` (yaml, tar, smol-toml,+ // commander, agenthub) and `__dirname` (@larksuiteoapi/node-sdk) inside their own wrapper,+ // and an ESM bundle supplies neither. scripts/deploy.mjs uses the same banner.+ banner: { js: ESM_CJS_BANNER },// `electron` is a runtime builtin inside the Electron main process, and its npm package is// only a shim that reads the binary's path from disk — bundling that shim is what a bare// `noExternal: [/.*/]` gets you. Everything else is bundled by default: tsup externalizesdiff --git a/scripts/deploy.mjs b/scripts/deploy.mjsindex 85d4a967..69b9d4e3 100644--- a/scripts/deploy.mjs+++ b/scripts/deploy.mjs@@ -28,6 +28,7 @@ import zlib from "node:zlib";import { fileURLToPath } from "node:url";import { unsafePlaintextTarget } from "./deploy-target-safety.mjs";import { buildGitDefine, checkoutFacts, originUrl } from "./build-git-stamp.mjs";+import { ESM_CJS_BANNER } from "./esm-cjs-banner.mjs";const require = createRequire(import.meta.url);const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");@@ -136,9 +137,9 @@ async function login() {}/**- * Compiles one entry to a self-contained ESM file. The banner is load-bearing: several- * bundled CJS deps call plain `require(...)` inside their own wrapper, and esbuild's ESM- * output otherwise routes those to a shim that always throws.+ * Compiles one entry to a self-contained ESM file. The banner is load-bearing: bundled CJS+ * deps reference `require`, `__filename` and `__dirname` inside their own wrapper, and an+ * ESM bundle supplies none of the three — see scripts/esm-cjs-banner.mjs.*/async function compileEntry(entry, outfile) {if (!fs.existsSync(entry)) throw new Error(`compile entry missing: ${entry}`);@@ -150,9 +151,7 @@ async function compileEntry(entry, outfile) {platform: "node",outfile,logLevel: "silent",- banner: {- js: 'import { createRequire as __penguinCreateRequire } from "node:module"; const require = __penguinCreateRequire(import.meta.url);',- },+ banner: { js: ESM_CJS_BANNER },alias: {"@prismshadow/penguin-core/kernel": require.resolve("@prismshadow/penguin-core/kernel"),},diff --git a/scripts/esm-cjs-banner.d.mts b/scripts/esm-cjs-banner.d.mtsnew file mode 100644index 00000000..22016776--- /dev/null+++ b/scripts/esm-cjs-banner.d.mts@@ -0,0 +1,6 @@+/**+ * Types for esm-cjs-banner.mjs. The module is plain JavaScript because the bundler configs+ * and scripts/deploy.mjs load it directly; this lets packages/desktop's typechecked test+ * import the same constant the build uses instead of re-stating it.+ */+export declare const ESM_CJS_BANNER: string;diff --git a/scripts/esm-cjs-banner.mjs b/scripts/esm-cjs-banner.mjsnew file mode 100644index 00000000..c98f1293--- /dev/null+++ b/scripts/esm-cjs-banner.mjs@@ -0,0 +1,46 @@+/**+ * The CommonJS ambient globals an ESM bundle has to declare for the CJS dependencies it+ * absorbs, shaped as an esbuild/tsup `banner` string.+ *+ * Two bundling sites emit `format: "esm"` while bundling third-party CommonJS whole:+ * `packages/desktop/tsup.config.ts` (the app's shell, server and CLI bundles) and+ * `compileEntry` in `scripts/deploy.mjs` (the hot-update platform and CLI bundles). In a+ * CJS module `require`, `__filename` and `__dirname` are supplied by the module wrapper;+ * in an ESM one they do not exist, so each such reference inside an absorbed dependency+ * resolves against the bundle's own top-level scope instead. Undeclared, `require(...)`+ * reaches esbuild's stub — which always throws — and `__dirname` / `__filename` are+ * simply undefined identifiers, so the first dependency to read one fails with+ * `__dirname is not defined`.+ *+ * `__filename` and `__dirname` are an approximation, not emulation: they name the+ * BUNDLE's own path, not the directory the dependency was published in. A dependency that+ * reads `__dirname` to reach a file it ships beside itself therefore looks in the wrong+ * directory — the crash becomes a wrong path. Bundling cannot give it back the layout it+ * expects; a dependency that needs its own files has to stay out of the bundle and ship as+ * a real package directory, which is what `packages/desktop/scripts/build-assets.mjs`+ * does for node-pty.+ *+ * What is bundled today stays inside that limit: `@larksuiteoapi/node-sdk` resolves its+ * own `package.json` through `__dirname` to put a version into its User-Agent header, and+ * already falls back to `unknown` when the read finds nothing — so the wrong directory+ * costs a version tag in a request header and nothing more.+ */++/**+ * Single line on purpose: a banner shifts every source line the bundle's sourcemap maps.+ *+ * `var`, not `const`: esbuild renames a bundled module's own top-level `require`, but it+ * leaves `__filename` and `__dirname` alone, and the ESM boilerplate that derives them from+ * `import.meta.url` is common enough to expect in the tree. A second lexical declaration of+ * a name the banner already bound is `SyntaxError: Identifier '__filename' has already been+ * declared` — the whole bundle fails to parse, which is worse than the crash being fixed.+ * Two `var`s of one name are legal, and inside a bundle both spell the same path anyway.+ */+export const ESM_CJS_BANNER = [+ 'import { createRequire as __penguinCreateRequire } from "node:module";',+ 'import { fileURLToPath as __penguinFileURLToPath } from "node:url";',+ 'import { dirname as __penguinDirname } from "node:path";',+ "var require = __penguinCreateRequire(import.meta.url);",+ "var __filename = __penguinFileURLToPath(import.meta.url);",+ "var __dirname = __penguinDirname(__filename);",+].join(" ");