Skip to content

feat: standard npm install path for the opencode native plugin (#925) - #931

Merged
ranxianglei merged 1 commit into
masterfrom
2026-09-18_opencode-native-packaging
Sep 18, 2026
Merged

ranxianglei merged 1 commit into
masterfrom
2026-09-18_opencode-native-packaging

Conversation

@ranxianglei

Copy link
Copy Markdown
Owner

What

Standard npm install path for the opencode native plugin (#925): "plugins": ["billion-context"] in an opencode config loads the plugin through opencode's own Npm.add machinery — zero absolute paths, host-managed install/upgrade, portable across machines.

Stacked on feat/pi-native-plugin per owner direction in the #925 thread ("先堆叠"): the native entry (dist/agent/opencode-native.js) exists only there; this rides into master with #706.

Changes

  1. package.json — explicit exports map (no wildcards, per the locked opencode 2.x: no-launcher npm-plugin deployment — plugins: ["billion-context"], plugin lazily spawns the proxy #809 decision):

    "exports": { ".": "./dist/index.js", "./server": "./dist/agent/opencode-native.js" }
  2. src/plugin-install.ts — origin-aware opencode installer:

    • New isNpmInstallForm(root): package root under node_modules (npm/pnpm/yarn, both path-separator styles) ⇒ npm form.
    • New applyOpencodePluginEntry(): npm form writes the bare name billion-context into plugin and deletes any legacy shim dir; checkout/dev form keeps the local shim dir (<configDir>/plugins/billion-context/index.js) and prints a note that it is a machine-local dev form, not portable across machines. Single-owner replacement between forms; re-running install migrates entries.
    • remove/status recognize both forms.
  3. tests/plugin-install-opencode.test.ts (new, 8 tests): origin-detection table (npm global / pnpm nested / yarn / Windows backslash / checkouts), both entry forms (fresh / migrate / idempotent / cross-form replace / non-string filter behavior), full install→status→remove e2e through the real installer with hermetic XDG env.

  4. README.md / README.zh-CN.md: document the two entry forms.

Verification

  • npm run typecheck clean; npm test: 1704 pass / 0 fail / 2 skipped (e2e gate).
  • npm run build + npm pack on this branch: tarball contains dist/agent/opencode-native.js; packed package.json carries the exports map (acceptance item 1).
  • Resolution simulation against the packed tarball (fresh project, npm install billion-context-*.tgz):
    • require.resolve("billion-context/server") → …/dist/agent/opencode-native.js ✓ (was MODULE_NOT_FOUND before)
    • import("billion-context/server") → default export object { id, setup, server }, zero import-time side effects (no listener, no timer) ✓
    • require.resolve("billion-context") → still dist/index.js (root unchanged) ✓
    • require.resolve("billion-context/dist/index.js") → ERR_PACKAGE_PATH_NOT_EXPORTED (sealed as designed) ✓

Ordering caveat

Acceptance items 2–3 (bare name loads end-to-end + self-spawned proxy; same config works on another machine) become live once this reaches master via #706 and a release publishes it — no further packaging work needed at that point.

Closes #925

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 收到。这是上一轮会话按 #925「先堆叠」指示开的 PR(分支 2026-09-18_opencode-native-packaging,单 commit 81d647c),不重做——现在独立核验:拉分支对照描述逐项审代码、跑全量 typecheck/test/build、npm pack 实证验收项 1、对打包产物做解析模拟、查 CI 状态,随后回帖结论。

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 核验完成(这是上一轮会话按 #925「先堆叠」指示开的 PR,单 commit 81d647c,按 [PR] 协议走独立核验而非重做)。结论:代码与描述逐项吻合,全部本地检查独立复现通过,可以随 #706 落地。

代码审查(diff vs base feat/pi-native-plugin @ 2c5a6f8)

5 文件 +227/−24,每一行都与本 PR 目的相关——无跑题文件、无空格噪音、无锁文件漂移、version 未动(内容分支正确行为):

  • package.json:exports { ".": "./dist/index.js", "./server": "./dist/agent/opencode-native.js" } —— 显式枚举无 wildcard(opencode 2.x: no-launcher npm-plugin deployment — plugins: ["billion-context"], plugin lazily spawns the proxy #809 拍板形态),. 与 main 字节等价。
  • src/plugin-install.ts:isNpmInstallForm(root)(/(^|[/\\])node_modules[/\\]/,覆盖 npm/pnpm 嵌套/yarn/Windows 反斜杠)、applyOpencodePluginEntry() 逐行审过——两形态单一属主替换、npm 形态迁移时删遗留 shim 目录、dev 形态输出不可跨机提示、幂等与跨形态替换逻辑均正确;非字符串条目过滤是既有行为未变。remove/status 双形态识别正确。
  • tests/plugin-install-opencode.test.ts:8 例与描述一致(来源判别表、两形态 fresh/migrate/idempotent/cross-form、hermetic XDG 下真实 installer 全链路 install→status→remove)。
  • README EN+ZH 同步两种入口形态。

本地独立复现(分支头 81d647c,干净检出 + npm ci)

项 结果
npm run typecheck 干净 ✓
npm test 1706 tests / 1704 pass / 0 fail / 2 skip(e2e gate) —— 与 PR 声称完全一致 ✓
npm run build + npm pack tarball 含 package/dist/agent/opencode-native.js(1.92 MB),包内 package.json 带 exports map → 验收项 1 独立达成 ✓

解析模拟(全新项目 npm install <tarball>):

  • require.resolve("billion-context/server") → …/node_modules/billion-context/dist/agent/opencode-native.js ✓(修复前 MODULE_NOT_FOUND)
  • import("billion-context/server") → default { id: "billion-context-opencode-native", setup: fn, server: fn } ✓
  • 导入副作用探针(stdio 预热后对 active handles 做前后普查 +2s 等待):Server 0→0、Timeout 0→0、Socket 无变化 → 零导入期监听/定时器 ✓(首轮探针曾多出一个 Socket,复查确认是我自己日志触发的 stdio 惰性注册,非插件行为)
  • 裸包名仍 → dist/index.js(现有消费者不受影响)✓;billion-context/dist/* 裸子路径 → ERR_PACKAGE_PATH_NOT_EXPORTED(按设计封印)✓

CI 状态(head commit 81d647c)

  • check-runs:real codex vs deterministic fake upstream (zero tokens)(ci-e2e-fake.yml,所有 PR 触发)→ completed/success ✓
  • ci.yml / pr-artifact.yml 仅在 base=master 的 PR 上触发,对本堆叠 PR 不适用;typecheck/test/build 由上面的本地全量复现覆盖,且会在随 feat(pi): native plugin mode — self-bootstrapping proxy + fetch interception #706 落 master 时由 ci.yml 再跑一遍。

备注(仅报告,不另开 issue)

  1. 验收项 2–3 保持门禁中(PR 正文已声明):裸包名端到端加载 + 自拉起、配置跨机生效,要等 feat(pi): native plugin mode — self-bootstrapping proxy + fetch interception #706 合入 master 并由某次 release 发布后自动成立,届时无需额外打包工作。同理 Closes #925 也要等落到默认分支才生效。
  2. base PR feat(pi): native plugin mode — self-bootstrapping proxy + fetch interception #706 当前与 master 冲突(API 实测 mergeable_state: dirty)——feat: standard npm install path for the opencode native plugin (#925) #931 相对其 base 本身 clean;落地前需要先处理 feat(pi): native plugin mode — self-bootstrapping proxy + fetch interception #706 的 rebase。另注意堆叠分支的版本号还停在 0.1.115,落后于已发布的 0.1.118/0.1.119 线,rebase 时会一并对齐。
  3. 封印裸 dist/* 子路径的跨仓零破坏面依据 opencode 2.x: no-launcher npm-plugin deployment — plugins: ["billion-context"], plugin lazily spawns the proxy #809 已记录的跨仓搜索结论,本轮未重复执行。

无需任何修改。结论:可合并(待 #706 先落地)。


中文摘要:独立核验了上一轮会话开的本 PR——代码与描述逐项吻合(显式 exports、来源感知安装器、8 个新测试、双语文档),本地全量复现 typecheck 干净、1704/1704 测试通过、打包产物实证含 native 入口且 billion-context/server 可解析、导入零副作用(验收项 1 达成);CI 的 e2e-fake 绿,其余 CI 因 base 非 master 未触发(落 master 时补跑)。验收项 2/3 按设计等 #706 合入并发布后端到端成立;唯一行动项是 #706 当前与 master 冲突需先 rebase。本 PR 本身可直接随 #706 合并。

Base automatically changed from feat/pi-native-plugin to master September 18, 2026 07:54
…925)

- package.json: explicit exports { ".": dist/index.js, "./server":
  dist/agent/opencode-native.js } — opencode's loader tries <pkg>/server
  first (verified in the shipped @opencode/cli 2.0.7 binary), so the bare
  name no longer falls back to main and runs the CLI in-host
- plugin install opencode: origin-aware — npm installs (package root under
  node_modules) write the bare package name (host-managed via Npm.add,
  portable config); checkout/dev installs keep the local shim dir and say
  so in the output; remove/status handle both forms; re-run migrates
- tests: 8 new cases (origin table, both forms fresh/migrate/idempotent,
  full install/remove/status e2e); docs EN+ZH
@ranxianglei
ranxianglei force-pushed the 2026-09-18_opencode-native-packaging branch from 81d647c to bdc894b Compare September 18, 2026 08:00
@github-actions

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: 2026-09-18_opencode-native-packaging (bdc894b)

Option A — Install from npm PR tag (recommended)

npm install -g billion-context@pr-931

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

Option B — Download artifact

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

Install instructions are refreshed on each push.

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

Labels

None yet

Projects

None yet

1 participant