Skip to content

[PR] fix: opencode 2.x native install writes the shim dir instead of the bare package name (#3976) - #6002

Merged
ranxianglei merged 3 commits into
masterfrom
2026-11-09_opencode-v2-shim-entry
Nov 10, 2026
Merged

ranxianglei merged 3 commits into
masterfrom
2026-11-09_opencode-v2-shim-entry

Conversation

@ranxianglei

Copy link
Copy Markdown
Owner

Closes #3976

Problem

bili plugin install opencode on OpenCode 2.x hosts wrote the bare package name into the config's plugins list. OpenCode 2.x resolves a bare plugin name through the package main field (dist/index.js — the CLI, no default export), so the module load fails:

  • 2.1.0 (Windows): Plugin must export a default definition … SchemaError(Missing key at ["default"]) ×3, plus Package is not installed: billion-context on the update check
  • 2.2.5 (Windows): worse — /reload throws TypeError: o is not a function

The README's "bare name loads through exports["./server"] via Npm.add" claim does not hold for how 2.x resolves a bare name. On Linux 2.1.0 the plural+bare form happens to load (Arborist cache copy) — which is why the old form passed review while both field reports are Windows.

Fix

Installer (src/plugin-install.ts): for every 2.x host (the plugins key) and any dev/git-checkout build, write the shim-dir entry <configDir>/plugins/billion-context/index.js → re-export of THIS install's dist/agent/opencode-native.js, instead of the bare name. 1.x npm installs keep the portable bare name (unchanged).

  • legacy bare entries in a 2.x config migrate automatically (reported as replaced)
  • a stale shim (pointing at an old install root) is regenerated to the current root, even on idempotent runs
  • doctor/update messages read the shim target to tell npm-root installs (self-updating in place) apart from checkouts
  • docs: README en/zh Quickstart Option 1 + docs/clients(.zh-CN).md §OpenCode manual-install split by host generation (1.x bare / 2.x shim dir); verified-on line refreshed to 2.1.0

Behavior changes (flagged)

old new why
installer entry, 2.x hosts "plugins": ["billion-context"] "plugins": ["<configDir>/plugins/billion-context"] (shim dir) bare name never loads under 2.x on Windows (#3976); shim proven on Linux+Windows × 2.1.0/2.2.5
installer entry, 1.x npm bare name unchanged still loads there
2.x npm-install update path opencode-host-managed Arborist cache copy + opencode plugin update bili's own self-update (global path stable under npm -g); doctor/update wording adjusted the host no longer sees a package spec, so its update check no longer applies
note strings for plugins-key installs plugin -> X plugins -> X cosmetic honesty

Evidence

  • Real @opencode/cli@2.1.0 binary, hermetic homes, sequential runs: plural+bare loads on Linux; singular+bare silently dropped; shim dir loads cleanly (zero failed to load lines, full module-graph resolution, watcher on the transitive plugin file); proxy boot confirmed via bili.log / port-zone.json.
  • Field: two independent Windows reports (2.1.0 and 2.2.5) where exactly this shim-dir form works end-to-end (proxy up, acp-usage logging, /reload clean).
  • Loader source at v2.0.3/v2.1.0 tags: Host.resolve probes <name>/server then <name>; the v2.0.3→v2.1.0 diff adds only a ManagedPolicy deny-gate around load.

Tests

ework-agent and others added 2 commits November 9, 2026 10:49
…n LIVE_FILES

Converged master-red fix (sentinel ci-fixes lane): #5989 merged the
spawning suite without registering it, so the #1248 SPAWN_RE tripwire
kills all 11 core-matrix test shards before any test runs on every PR
head. Hunk is byte-identical to open PR #5990 (which carries the same
registration plus a test-tolerance change to master).
…are package name (#3976)

OpenCode 2.x resolves a bare plugin package name through the package main field (dist/index.js, the CLI — no default export), so the entry form the installer wrote for 2.x hosts ("billion-context" under the plugins key) never loads: Plugin must export a default definition / on 2.2.5 a TypeError at /reload. Verified against the real @opencode/cli 2.1.0 binary (Linux): plural+bare does load there, but both field reports are Windows and the dir-shim form is proven on all four combinations (Linux/Windows x 2.1.0/2.2.5), so the installer now writes the shim dir (<configDir>/plugins/billion-context/index.js re-exporting this install dist/agent/opencode-native.js) for every 2.x host and any dev build; 1.x npm installs keep the portable bare name. Legacy bare entries in a 2.x config migrate automatically; a stale shim is regenerated to point at the current root; update messages read the shim target to tell npm-root installs from checkouts. README en/zh + clients docs en/zh: manual-install instructions split by host generation.
@github-actions

github-actions Bot commented Nov 9, 2026 •

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: 2026-11-09_opencode-v2-shim-entry (311a34f)

Latest build — install this exact version

npm install -g billion-context@0.0.8746-pr.6002.4a5ae46

This exact version is immutable and reproducible. The rolling pr tag tracks the newest test build across all PRs.

Recent builds (commit → version)

commit version build
311a34f billion-context@0.0.8746-pr.6002.4a5ae46 build
09bda56 billion-context@0.0.8745-pr.6002.c45748e build

Download artifact

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

Install instructions are refreshed on each push.

@ranxianglei ranxianglei changed the title fix: opencode 2.x native install writes the shim dir instead of the bare package name (#3976) [PR] fix: opencode 2.x native install writes the shim dir instead of the bare package name (#3976) Nov 9, 2026
@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

(ai: vllm-qwen/qwen3.8-27b)

Duplicate screening: not a duplicate. #6002 is the only PR referencing/closing #3976. Searched open+closed issues/PRs for the opencode-shim topic and for 3976 — no parallel fix exists for this thread (other opencode-lane PRs like #5938 / #5710 are different mechanisms/symptoms). #6002 stands alone; nothing to consolidate.

What I did. Reviewed the branch (installer + tests + docs) and checked CI live. The change itself is correct and complete; the only blocker was CI, and that red was not caused by this PR.

The CI red is an inherited master tripwire. On the original head (09bda560) all 11–12 test shards failed identically before running a single test:

process-spawning test files missing from LIVE_FILES in scripts/run-ci-tests.mjs:
tests/issue5955-wedged-same-lane-takeover.test.ts

That file landed via #5989 (PR #5972) without being registered in the runner's LIVE_FILES, so the pre-flight guard kills the entire matrix for every PR against current master. It's tracked in the CI control tower (#4599); the fix already sits on ci-fixes@831b645. A concurrent run had already merged ci-fixes into this branch — head is now 311a34f7e6 (12:32 +0800), carrying exactly the scripts/live-files.mjs registration and nothing else. (I reproduced the same merge locally before finding the remote tip, then aligned to it — no force-push, no duplicate commit.)

CI on the new head (live snapshot): 31 success / 11 skipped / 5 shards still running / 0 failures. Tripwire gone, tests executing normally — expecting fully green once the last shards land.

结构化八问:

  1. 是什么问题:OpenCode 2.x 宿主上 bili plugin install opencode 把裸包名写进配置,而 2.x 按包的 main 字段(dist/index.js,CLI、无 default 导出)解析裸名 → 插件加载失败([Bug] Plugin fails to load under OpenCode 2.1.0: bare package name entry dist/index.js lacks a default export (Plugin mu | [Bug] OpenCode 2.1.0 下插件加载失败:裸包名入口 dist/index.js 没有默认导出(Plugin must export a default definition) #3976;Windows 现场:SchemaError(Missing key ["default"])、/reload 抛 TypeError)。
  2. 什么原因导致:安装器只按「npm 形态→裸包名」单维决定入口,没纳入宿主代次;README「裸名经 exports["./server"] 由 Npm.add 加载」的说法对 2.x 不成立(2.x 走 main)。Linux 上因 Arborist 缓存副本偶然可加载而掩盖了它,所以旧形式过了评审,两份现场报告都在 Windows。
  3. 影响范围与严重程度:所有 OpenCode 2.x 宿主的原生安装(尤其 Windows)装完插件完全不加载 = 该段用户不可用,属可用性缺陷,p1;1.x 与 dev-form 不受影响。
  4. 怎么修复的:入口形态改由「安装来源 × 宿主代次」共同决定——凡 2.x(plugins 键,复用 plugin install opencode 写 V1 键名 plugin 到新建的 opencode.json:2.x 下该行无效(靠目录自动发现兜住),且与用户 opencode.jsonc 配置分裂 #927 pickPluginKey 既有不变量)或 dev-form 一律写本机 shim 目录(一行重导出本次安装的 opencode-native.js);1.x+npm 保持裸包名不变。顺带:shim 改为「内容漂移才重写」以修复重装到新路径的陈旧 shim;doctor/update 读 shim 目标区分 npm 根(自更新)与 checkout(需重建)。
  5. 是否有回归:逐条过既有行为——1.x+npm 裸名路径未动;dev-form 仍写 shim(仅「无条件写」→「漂移才写」,终态一致、更少 churn,非行为回归);rmSync 清理条件随 useShim 对齐(仅在切回裸名时清陈旧 shim,语义更精确);note 文案 plugin->→plugins->(纯诚实性,已披露);map-form 测试旧期望本就编码了 v2 bug,已按新行为重钉并注明。未见意外回归。
  6. 是否破坏缓存:不涉及——纯安装器与文档改动,不触碰压缩/缓存/重试/去重键。
  7. 是否改了设计方向:不改架构/边界/数据流;仅把入口判定从单维扩到双维,复用既有 plugins/plugin 键不变量,未新增任何配置面。
  8. 是否引入新配置:无新 env/config/默认值。

Minor nit (non-blocking): in updateLane, the shim-target read wraps fs.readFileSync in an empty catch {}. It's a deliberate best-effort (unreadable index.js → fall back to the "checkout — rebuild" message), but per the code-cleanliness norm an empty catch wants a one-line "why we swallow" comment. Not worth a separate commit on an otherwise clean PR — noted for the record.

Verdict: ready to merge once the remaining 5 shards confirm green (expected). All behavior changes are already disclosed in the PR body (installer entry 2.x bare→shim; 1.x unchanged; 2.x-npm update path host-managed→bili self-update; note-string plugin->→plugins->). No regression found; no cache or config-surface impact.

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

(ai: vllm-qwen/qwen3.8-27b)

CI is now fully green on head 311a34f7e6: 36 pass / 12 skipped / 0 failures across all shards (ubuntu + windows × node 22/24). The inherited issue5955 LIVE_FILES tripwire is gone — every test shard actually executed and passed.

Triage labels applied: bug · p1 · opencode · scope/wiring. Rationale for p1: on OpenCode 2.x hosts (notably Windows) the installed plugin never loads at all — the feature is unusable for that segment, not merely degraded — so it's an availability defect, not a p2.

Verdict: ready to merge. Merge is human-only per repo rules — please merge when you're ready: #6002

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 (ai: vllm-qwen/qwen3.8-27b)

Task complete — PR #6002 reviewed and green.

Ready for human-only merge: #6002

@ranxianglei
ranxianglei merged commit 513852a into master Nov 10, 2026
84 of 120 checks passed
ranxianglei pushed a commit that referenced this pull request Nov 10, 2026
…him-dir semantics

The fixture probes a deterministic 2.x host (fakeOpencodeBin prints 2.4.0),
so since 09bda56 (#3976 via #6002) 'plugin install opencode' writes the
machine-local shim dir and migrates the seeded legacy bare entry; the old
bare-name expectation now fails on both OS runners. Assert the migrated
shim entry, its re-export content pointing at the installed dist root, and
the migration note. Fixes master-red on 541cf26 (hermetic registry e2e,
ubuntu+windows); coordinated on #4599.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

1 participant