Skip to content

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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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 externalizes
diff --git a/scripts/deploy.mjs b/scripts/deploy.mjs
index 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.mts
new file mode 100644
index 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.mjs
new file mode 100644
index 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(" ");