Skip to content

fix: strip JSDoc import() annotations from dist so bun-based plugin loaders can load it (#1255) - #1258

Closed
ranxianglei wants to merge 1 commit into
masterfrom
wt-1255-ework-daemon
Closed

ranxianglei wants to merge 1 commit into
masterfrom
wt-1255-ework-daemon

Conversation

@ranxianglei

Copy link
Copy Markdown
Owner

Fixes #1255

Root cause (re-verified on master)

The dist bundles contain zero real relative dynamic imports. Every import('./…') occurrence is a JSDoc type annotation from undici (@param {import('./client.js')} client, {import('./snapshot-utils').HeaderFilters}, …) that survives bundling because esbuild keeps class-body JSDoc in non-minified ESM output. Node's ESM loader ignores comment content, but the bun-based opencode binary resolves those relative specifiers as real files during plugin loading → ENOENT …/dist/agent/client.js → failed to load plugin → silently dead lane (no compression, no proxy, no updater).

Re-verified locally on current master: the gate below counts 770 relative import()/require() text occurrences across all 11 dist entries of an unflagged build — every one inside a JSDoc comment.

Changes

  1. tsup.config.ts: minifyWhitespace: true via the esbuildOptions hook — drops all non-legal comments (including the JSDoc annotations) while keeping identifiers readable; legal (license) comments are preserved.
  2. scripts/check-dist-import-annotations.mjs: new build gate wired into npm run build (and therefore CI): fails the build if any relative import()/require() text ever reappears in dist *.js. The lane cannot silently die again.

Pre-flight (this branch)

  • Gate proven effective both ways: flag off → npm run build fails with dist-import-annotations: FAIL — 770 relative import()/require() ref(s) in dist; flag on → dist-import-annotations: OK.
  • npm run typecheck clean; npm test: 2351 pass / 0 fail / 2 skipped.
  • All dist entries pass node --check; dynamic import of dist/agent/opencode-native.js (the file that failed under opencode) succeeds with the full export list including the default plugin function.
  • Content check: 0 relative import()/require() text left in dist; license comment intact; sourcemaps still ship.
  • End-to-end under an isolated opencode 1.14.46 (plugin loads with no ERROR, marker plugin fires alongside, native bootstrap spawns the proxy from the npm-form copy) per the issue's pre-flight; not re-run here.

⚠️ Behavior change: dist artifacts become whitespace-minified. No semantic change — only non-legal comments dropped and whitespace collapsed; stack-trace lines get denser (sourcemaps ship for mapping back). This is the intended fix mechanism.

@github-actions

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: wt-1255-ework-daemon (ced78c0)

Option A — Install from npm PR tag (recommended)

npm install -g billion-context@pr-1258

Each push to this PR publishes a new version under the pr-1258 npm tag.

Option B — Download artifact

  1. Download the artifact from the Actions run
  2. Extract the tarball and install:
tar xzf billion-context-pr1258.tgz
npm install -g package

Install instructions are refreshed on each push.

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

Review verdict: direction sound, independently verified — but this PR duplicates #1256. Closing #1258, keeping #1256 (reviewed + hardened).

① 原 issue(方向关)

Re-verified the root cause on current master (a1b4b471): undici (devDep ^7.29.0, locked 7.29.0) is bundled inline via src/upstream-proxy.ts:4 and src/fetch-util.ts:1; esbuild keeps class-body JSDoc in non-minified ESM output, so all 11 dist entries carry relative import()/require() text — 770 occurrences, every one inside a comment (@param {import('./client.js')} client, {import('./snapshot-utils').IsUrlExcluded}, …). Node ignores comment content; the bun-based opencode binary resolves those specifiers as real files → ENOENT …/dist/agent/client.js → silently dead lane. The fix acts on the producer (build config drops non-legal comments) and adds a loud regression gate — not a payload mask. Direction is right.

② 回归审查(既有行为清点)

  • Disclosed behavior change (intended mechanism): dist artifacts become whitespace-minified — non-legal comments dropped, legal /*! license */ comments preserved, sourcemaps still ship (verified: all 15 .map files present, index.js.map parses). Stack-trace lines get denser; no semantic change.
  • Wire protocol / message shape: untouched — zero src/ changes, build config + scripts only; both compression modes unaffected.
  • Config schema / persistence format / acp-kernel pin / src/update.ts: untouched.
  • Runtime readers of our own dist artifacts: grep over src/ finds none (no readFileSync/createRequire/dynamic import(/existsSync against dist paths) — nothing parses dist text at runtime, so minification cannot break a consumer.
  • Gate is wired into npm run build → enforced by CI on every push; failure mode is loud (exit 1 + per-file violation list).

③ 代码审查(主关)

  • tsup hook esbuildOptions(options) { options.minifyWhitespace = true } — the minimal correct knob (identifiers stay readable; no syntax minify needed).
  • Gate regex /(?:import|require)\(\s*['"]\.{1,2}\/[^'"]*['"][^)]*\)/g — catches multi-line and trailing-arg forms; .js-only walk correctly ignores .map.
  • Found & fixed directly on the kept branch: the main-module guard string-compared process.argv[1] against pathToFileURL(...). Node resolves entry-point symlinks, so when the gate is invoked through a symlink (pnpm-style symlinked trees, /tmp→/private/tmp) the comparison goes false and the gate exits 0 with no output — a silent gate death of exactly the class this PR exists to prevent. Reproduced locally, fixed with a realpathSync comparison (commit af65c573 on fix: strip JSDoc import() annotations from dist bundles — dead opencode plugin lane (#1255) #1256), re-verified: direct/symlink/copy invocations all run the check, the negative case still fails loudly, unit tests pass.

④ 测试有效性

⑤ diff 整洁度

Single commit, 4 files (#1256) / 3 files (#1258); every line on-purpose. Clean.

Independent verification evidence (rebased head on a1b4b471)

  • npm run typecheck clean; npm run build OK + dist-import-annotations: OK.
  • Full suite: 2448 pass / 3 fail / 2 skipped. The 3 failures are tests/claude-native.test.ts live-process e2e (ps-walk host resolution, watchdog target, shared-proxy survival) and fail identically on unmodified master in a clean baseline worktree → pre-existing environment-bound, not caused by this change.
  • Gate A/B: unflagged master dist → FAIL — 770 refs across 11 files (matches the issue's claim exactly); flag on → OK.

Duplicate resolution

Two daemon sessions raced on #1255 and produced two open PRs fixing it identically in scope. Keeping #1256 — unit tests for the gate, exported/testable gate functions, compliant branch name (2026-09-24_opencode-plugin-jsdoc-strip vs wt-1255-ework-daemon), newer base — and closing #1258 as 重复. Nothing unique is lost.

CI on #1256's old head 0efd9211 was fully green (all 9 checks incl. windows-22). After the rebase + hardening commit it's re-running on new head af65c573.

中文摘要: 审核了 #1258/#1256 这对重复 PR(同一修复的两份提交):根因(undici JSDoc import() 注释泄漏进 dist,bun 版 opencode 把注释当真实文件解析导致插件通道静默死亡)已在当前 master 复现确认(未修复构建中 11 个 dist 文件共 770 处),修复方向正确(从构建源头去掉非法律注释 + 构建期硬门禁,不是掩盖症状);独立验证通过(typecheck 干净、全量测试的 3 个失败证明是 master 既有环境问题、门禁 A/B 770→0、15 个 dist 产物全部可加载)。#1256 质量更高(门禁有单测、分支命名合规)予以保留,并已直接在分支上补了一个 review 中发现的小修(门禁经符号链接调用时会静默跳过,已改为 realpath 比较并验证);#1258 作为重复关闭。#1256 待新 CI 全绿后可以合并。

@ranxianglei

Copy link
Copy Markdown
Owner Author

Closing as a duplicate of #1256 — same root cause (#1255: undici JSDoc {import('./…')} annotations leaking into dist, which bun-based opencode resolves as real files and dies on) and the same two-part fix (minifyWhitespace in tsup + a build-time gate wired into npm run build). #1256 is retained because it is strictly stronger: unit tests for the gate (tests/dist-import-annotations.test.ts), exported/testable gate functions, a compliant branch name (2026-09-24_opencode-plugin-jsdoc-strip vs wt-1255-ework-daemon), and a newer base.

The full independent review — root cause re-verified on current master (770 offending refs across all 11 dist entries in an unflagged build, 0 after the fix), full test suite on the rebased head, dist smoke tests, plus one small gate hardening pushed directly onto the #1256 branch (symlinked invocation used to skip the check silently) — is posted in the tracking issue thread (#1258). Nothing unique is lost by closing this PR.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

OpenCode plugin lane silently dead on modern versions: bundled JSDoc import() annotations crash opencode's plugin loader (ENOENT client.js)

1 participant