border-customs 0.6.0 → 0.7.1

package/README.md

@@ -717,7 +717,7 @@ plugin entry ships as `exports["./server"]`):
 ```jsonc
 {
   // pin the exact version — an @latest channel hits the registry on every cold start
-  "plugin": ["border-customs@0.6.0"]
+  "plugin": ["border-customs@0.7.1"]
 }
 ```
 
@@ -738,6 +738,18 @@ exit 2 and never overwritten, uninstall removes only marker-bearing files, and i
 report `up to date`. Either route, restart opencode afterwards — tools and commands are
 scanned at startup.
 
+**OpenCode 2 (beta) compatibility (0.7.0).** The same module is dual-shaped: V1 hosts call
+`server()` (object entry form, opencode ≥ 1.18.29 required); V2 hosts (`@opencode-ai/cli@beta`,
+bin `opencode2`) call `setup(ctx)` and register the identical tool through
+`ctx.tool.transform` — hand-written `{id, setup}` (the SDK's `define()` is identity), plain
+JSON Schema input, zero V2-SDK runtime dependency. Live-verified on beta-19271 via
+project-local `.opencode/plugins/` (both single-file and package-directory shapes; directory
+discovery resolves the root `index.ts` re-export, which is why the package ships it). V2
+activates plugins lazily — listing them requires `POST /api/plugin/await-activation` first.
+The `/border` slash command stays V1-only until the V2 command-delivery API settles; the
+`border` tool is the supported V2 surface. Config keys are shared (V2 normalizes
+`plugin`→`plugins`). Global file-drop discovery under V2 is untested and not claimed.
+
 What loads is one agent tool `border` plus a `/border` slash command. The tool spawns the CLI
 argv-only (no shell; 300 s cap, 64 KiB per stream) restricted to the closed command list
 `check`, `push`, `status`, `llm-request`, `llm-ingest`, `scan`, `roundtrip`, `--help`, and
@@ -803,6 +815,31 @@ code.
 
 ## Changelog
 
+### 0.7.1 (2026-09-30)
+- Fix: **release-gate test ruler race** (`test/push.integration.test.ts` I4) — the
+  "dry-run made ZERO verdaccio requests" invariant counted lines in verdaccio's stdout
+  log, an eventually-consistent view: on a saturated CI runner the gate-leg probe lines
+  of an earlier phase land after the snapshot, inflating the dry-run delta (v0.7.0 CI
+  run 36671401844 failed `6 !== 2` while the identical bytes pass locally). The suite
+  now takes every snapshot through a FIFO drain barrier (sentinel request whose log line
+  must be visible before counting; sentinel traffic is excluded from the count). The
+  zero-network dry-run contract itself is unchanged — verified request-free on both sides
+  of the barrier; only the measuring instrument was repaired.
+
+### 0.7.0 (2026-09-28)
+- Add: **OpenCode 2 (beta) plugin compatibility** — the plugin module is dual-shaped
+  (`{id, setup}` for V2 hosts, frozen V1 `server()`), sharing the pre-spawn
+  allowlist/`--yes` gates and the 0.5.1 identity handshake across both shapes;
+  refusal/handshake/rendering byte-parity between edges is pinned by
+  `test/opencode.v2shape.test.ts` while the V1 path stays 16/16 on unmodified
+  tests. Root `index.ts` re-export shipped for V2 directory discovery (which
+  bypasses the exports map; live-proven on `@opencode-ai/cli` beta-19271).
+- Fix: the live V1 probe is anti-vacuous — opting in (`BORDER_OPENCODE_PROBE=1`)
+  without a resolvable binary or built dist now FAILS naming the remedy instead
+  of skipping green-adjacent (`BORDER_OPENCODE_BIN` override added).
+- Docs: support matrix (V1 object entry ≥ 1.18.29; V2 project-local verified;
+  `/border` command V1-only pending the V2 delivery API).
+
 ### 0.6.0 (2026-09-25)
 - Add: **the exfil lens** — five rules (`exfil-rfc1918`, `exfil-ssh-target`,
   `exfil-home-path`, `exfil-cred-location`, `exfil-host-profile`) that flag
@@ -963,6 +1000,10 @@ MIT, see [LICENSE](LICENSE).
 
 ## 中文概要
 
+**0.7.1（2026-09-30）发布门禁尺伤修复**：I4 集成测试的"dry-run 对 registry 零请求"断言按 verdaccio stdout 日志行计数，而日志是最终一致视图——CI 满载 runner 上更早阶段的合法 probe 行晚于快照落盘，把差额错记到 dry-run 头上（v0.7.0 run 36671401844 红 `6 !== 2`，同字节本机绿）。修复=尺子不松语义：所有快照前后加 FIFO drain 屏障（哨兵请求行可见⇒先前请求行必已落盘；哨兵流量不计入计数）。dry-run 零网络契约本身未动，两侧实测请求为零。
+
+**0.7.0（2026-09-28）OpenCode 2（beta）兼容**：插件模块双形状——V1 宿主调 `server()`（对象入口需 ≥1.18.29），V2 宿主（`opencode2`）调 `setup(ctx)` 经 `ctx.tool.transform` 注册同一个工具；spawn 前门（allowlist/`--yes`）与 0.5.1 身份握手两形状共享，双边渲染逐字 parity 由测试钉死。V2 懒激活（断言前须 `POST /api/plugin/await-activation`）；`/border` 命令暂仅 V1（V2 投递 API 未定形）；已在 beta-19271 项目本地两形态活体验证。V1 活体探针反真空化：opt-in 缺前提即 FAIL 点名补救。
+
 border 是一个 fail-closed(失败即拦截)的推送前门禁 CLI:`npm install -g border-customs` 安装,在仓库里跑 `border check`。它扫描 git 历史、工作区(未跟踪文件同样是一等输入)、归档、tag 注释和将要发布的 npm/PyPI/crates/RubyGems 字节,检出密钥与供应链风险;只有当"当前状态指纹"存在新鲜且完整的 PASS 记录时才允许 `border push --yes` 放行。指纹是 sha256(head、porcelain 摘要、规则哈希、暴露面、ref 集合、有效目标)六元组,任何一处变动,旧的 PASS 立即失效,必须重查。流水线:gitleaks(历史+工作区+tag,内置 8.30.1 规则,仓库自带的 ignore 文件直接判 CRITICAL)+ secretlint(进程内,AWS Key 规则强制开启)+ 原生规则(AI 会话产物闭集、提交身份白名单含传输对象检查)+ 注册表预检(版本已存在=必须 bump,名称被外人占有=拒绝;空响应/超时/解析失败一律 exit 2,沉默绝不等于不存在)。构件只构建一次进 `.border/dist/`,扫描的就是发布的字节,发布时再哈希比对,不一致直接拒发。跳过台账让重复检查不到 1 秒,但回放前先重算指纹并重新 pack 验证新鲜度。报告只输出掩码片段(sha256 摘要 + 前4…后4)。push 是多目标状态机,多 remote 先做全有或全无的 fast-forward 预检,永不 force-push;npm/twine/cargo/gem 的凭据经 stdio 透传,border 从不触碰。0.2.0 新增 crates.io 与 RubyGems 通道(公开 crates.io 固定、rubygems 可用 host 覆盖私有镜像),既有配置行为不变。0.3.0 新增残留扫描(residue gate):发布字节里的安装期钩子按 T0-T4 闭集签名表分类(闭集 T1 树内钩子降为 MEDIUM,未知形态原样保留 CRITICAL),外加跨包管理器写入、配对标记缺失(`# BEGIN` 块只检测不豁免)与 gem 不可解析扩展共七条 `residue-*` 规则;`residue.enabled` 是唯一豁免开关且改动指纹使旧 PASS 失效,规则表与分类器源码进入 rulesHash,改一个签名即强制重查。静态分析只证明"能力"不证明"事实",border 不是恶意软件沙箱,从不执行被读代码。0.4.0 新增证明阀
 `residue.requireProof`(默认关,strict):开启后,发布构件若触发阻断级 `residue-*` 发现,通道 PASS
 还要求账本里存在按其 sha256 索引且 rulesHash 新鲜的 `border roundtrip` 实测记录——check 自身从不

package/dist/assets/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "border-customs",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "border-customs",
-      "version": "0.6.0",
+      "version": "0.7.1",
       "license": "MIT",
       "dependencies": {
         "@opencode-ai/plugin": "^1.17.4",

package/dist/index.js

@@ -45059,7 +45059,7 @@ import { createHash as createHash18 } from "node:crypto";
 import { basename as basename5 } from "node:path";
 var SCAN_MAX_ARTIFACT_BYTES = 200 * 1024 * 1024;
 var SCAN_REQUEST_TIMEOUT_MS = 6e4;
-var SCAN_USER_AGENT = "border-customs/0.6.0 (+https://github.com/sumteclab/border; border scan)";
+var SCAN_USER_AGENT = "border-customs/0.7.1 (+https://github.com/sumteclab/border; border scan)";
 var CRATES_DOWNLOAD_HOST = "https://static.crates.io";
 var defaultScanFetcher = async (url2, init) => {
   if (!/^https?:\/\//.test(url2)) throw new EngineRunError(`border scan refuses non-http(s) URL: ${url2}`, null);

package/index.ts

@@ -0,0 +1,7 @@
+// provenance: .omo/plans/border-opencode-v2-plugin.md T1 — V2 project-directory plugin
+// discovery resolves <dir>/index directly (bypassing the package exports map, live-proven
+// on cli beta-19271); this re-export lets the unpacked package directory itself serve as a
+// V2 local plugin. Name-based imports continue to enter through exports["./server"].
+import plugin from "./plugin/border.ts";
+
+export default plugin;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "border-customs",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "//": "publint is a runtime dep (exact pin): the npm-stage engine is invoked via bin resolution against the installed layout, so consumers get the publint-fail leg out of the box; the dev suite resolves the same node_modules/.bin/publint — no devDependencies entry is needed for it to stay green.",
   "description": "Fail-closed git push gate: secret scanning + supply-chain checks before any remote leaves the machine",
   "type": "module",
@@ -14,7 +14,8 @@
   },
   "files": [
     "dist",
-    "plugin"
+    "plugin",
+    "index.ts"
   ],
   "engines": {
     "node": ">=22.0.0"

package/plugin/border.ts

@@ -1,4 +1,4 @@
-// border-opencode-plugin v0.6.0
+// border-opencode-plugin v0.7.1
 // Official opencode plugin adapter for the border fail-closed push gate.
 // Registers ONE agent tool, `border`, that drives the border CLI — argv-only
 // (node:child_process execFile, never a shell), top-level commands restricted
@@ -6,9 +6,17 @@
 // the human gate: nothing here can push for real (a bare `border push` is a
 // DRY-RUN by the CLI's own contract, and `--yes` is refused outright).
 //
-// V1 plugin format (opencode >= 1.14): default export { id, server }, where
+// Dual-shape default export — one module, two host generations:
+// V1 plugin format (opencode >= 1.18.29, object entry): { id, server }, where
 // server(input, options) resolves to Hooks; Hooks.tool is a
-// { [name]: ToolDefinition } record (see @opencode-ai/plugin).
+// { [name]: ToolDefinition } record (see @opencode-ai/plugin). The V1 host
+// ignores the extra `setup` key (this is the official dual-shape form).
+// V2 plugin format (@opencode-ai/cli beta line): the loader accepts only
+// { id, setup } (or { id, effect }) and silently drops anything else, so the
+// SAME tool registers through setup(ctx) -> ctx.tool.transform ->
+// editor.add(Info). Both edges share the pre-spawn gate (gateArgv) and the
+// execute substance (buildToolResult) below, so behavior stays identical;
+// test/opencode.v2shape.test.ts pins V1↔V2 rendering and refusal parity.
 // This file ships as-is (package.json "files") and reaches a session by two
 // routes, neither compiling it through border's tsc:
 // (A) copied into <CONFIG>/plugins/ by `border opencode install`, which also
@@ -234,8 +242,160 @@ contract: it reports the verdict the gate would produce without touching any
 remote.
 `;
 
+// --- V2 loader surface: local structural types ---------------------------------
+// shape proven from @opencode-ai/plugin beta-19271 .d.ts; live-gated by
+// test/opencode.v2.probe (plan T3). Deliberately NO V2 SDK import here (wave
+// plan D1/R3 pending): only the two members the setup() seam touches are
+// typed — ctx.tool.transform and editor.add — everything else stays opaque.
+
+/** Parsed tool input, mirroring the V1 args schema (command required, extra optional). */
+interface V2ToolArgs {
+  readonly command: string;
+  readonly extra?: readonly string[];
+}
+
+/** The V2 promise-entry result envelope: the rendered text in `content`. */
+interface V2ToolResult {
+  readonly content: string;
+}
+
+/** One tool registration handed to ToolEditor.add by the transform callback. */
+export interface V2ToolInfo {
+  readonly name: string;
+  readonly description: string;
+  /** Pure JSON Schema — ValueSchema accepts it without a schema-library import. */
+  readonly input: Record<string, unknown>;
+  readonly execute: (args: V2ToolArgs, context?: unknown) => Promise<V2ToolResult>;
+}
+
+export interface V2ToolEditor {
+  add(info: V2ToolInfo): void;
+}
+
+interface V2ToolRegistry {
+  transform(callback: (editor: V2ToolEditor) => void): Promise<unknown>;
+}
+
+export interface V2PluginContext {
+  readonly tool: V2ToolRegistry;
+}
+
+/**
+ * The ONE tool description, byte-shared by both edges: the V1 tool() schema
+ * and the V2 Info both render exactly this text (single source of truth).
+ */
+const TOOL_DESCRIPTION =
+  "Run the border fail-closed push-gate CLI on this machine. " +
+  "Pass the top-level command word in `command` (one of: check, push, status, " +
+  "llm-request, llm-ingest, scan, roundtrip, --help) and every remaining argv " +
+  "token in `extra`. The call is spawned argv-only (no shell) with a 300s " +
+  "timeout; the result always ends with the CLI exit code: 0 pass, 1 " +
+  "gate-blocked or partial push, 2 gate could not answer. Before running your " +
+  "argv the tool handshakes its binary candidate with `--help` and refuses " +
+  "everything (exit 2, cannot-answer) unless the responder provably is the " +
+  "border CLI — it never falls back to another binary. Honest privilege " +
+  "note: this tool runs the border CLI, and the CLI IS the gate that decides " +
+  "what leaves this machine — it carries the same power as the binary, so an " +
+  "agent may only *ask* the gate, never bypass it. `push --yes` is " +
+  "deliberately NOT reachable here: real pushes are the human gate and belong " +
+  "to a terminal. A bare `border push` through this tool is a DRY-RUN by the " +
+  "CLI's own contract.";
+
+/**
+ * The pre-spawn gate — the deliberate seam split, load-bearing for security:
+ *   gateArgv(argv) decides WHETHER the argv may run at all (allowlist
+ *   membership, `--yes` refusal) and returns the refusal text or null;
+ *   buildToolResult(argv) does the actual work (handshake, spawn, render)
+ *   and NEVER re-gates — it trusts its caller.
+ * Every edge (today: V1 tool.execute and V2 Info.execute) MUST call gateArgv
+ * BEFORE buildToolResult. A future edge that skips the gate silently gets no
+ * gating; test/opencode.v2shape.test.ts pins refusal parity on both edges.
+ */
+function gateArgv(argv: readonly string[]): string | null {
+  const command = argv[0] ?? "";
+  if (!ALLOWED_COMMANDS.includes(command)) {
+    return (
+      `border: refused '${command}' — not an allowed command. ` +
+      `Allowed: ${ALLOWED_COMMANDS.join(", ")}. Put the command word in 'command' ` +
+      `and every other token in 'extra'.`
+    );
+  }
+  if (argv.includes("--yes")) {
+    return (
+      `border: refused '${command}' with '--yes' — a real push is the human gate ` +
+      `and happens in a terminal. Run \`border push --yes\` there if a visible ` +
+      `human go-ahead exists. A bare \`border push\` through this tool is a ` +
+      `DRY-RUN by the CLI's own contract.`
+    );
+  }
+  return null;
+}
+
+/**
+ * The tool-execute substance shared by both edges (wave plan D2): resolve the
+ * CLI via resolveVerified (identity handshake included), spawn it argv-only
+ * via runCli, render the sectioned result. No gates and no V1-only
+ * context.metadata here — those stay at each edge, see gateArgv above.
+ */
+async function buildToolResult(argv: readonly string[]): Promise<string> {
+  const resolution = await resolveVerified();
+  if (!resolution.ok) {
+    return [
+      `$ border ${argv.join(" ")}`,
+      "exit: 2",
+      `note: cannot-answer — no border CLI passed the identity handshake, so nothing was run. Tried: ${resolution.reasons.join("; ")}. ` +
+        "Remedies: point BORDER_BIN at a real border CLI, run 'border opencode install' (route A), or npm i -g border-customs (PATH entry).",
+      "--- stdout ---\n(empty)",
+      "--- stderr ---\n(empty)",
+    ].join("\n");
+  }
+  const result = await runCli(resolution.resolution, argv, TIMEOUT_MS);
+  if (result.spawnFailed) verified = null;
+  const sections = [
+    `$ border ${argv.join(" ")}`,
+    `exit: ${String(result.status)}`,
+  ];
+  if (result.note.length > 0) sections.push(`note: ${result.note}`);
+  sections.push(`--- stdout ---\n${result.stdout.length === 0 ? "(empty)" : result.stdout}`);
+  sections.push(`--- stderr ---\n${result.stderr.length === 0 ? "(empty)" : result.stderr}`);
+  return sections.join("\n");
+}
+
+/** The V2-side tool registration: same gate + same substance as the V1 tool. */
+function makeV2ToolInfo(): V2ToolInfo {
+  return {
+    name: "border",
+    description: TOOL_DESCRIPTION,
+    input: {
+      type: "object",
+      properties: {
+        command: { type: "string" },
+        extra: { type: "array", items: { type: "string" } },
+      },
+      required: ["command"],
+      additionalProperties: false,
+    },
+    execute: async (args: V2ToolArgs): Promise<V2ToolResult> => {
+      const argv: readonly string[] = [args.command.trim(), ...(args.extra ?? [])];
+      const refusal = gateArgv(argv);
+      if (refusal !== null) return { content: refusal };
+      return { content: await buildToolResult(argv) };
+    },
+  };
+}
+
 export default {
+  // Shared plugin id: the V1 host reads it for the {id, server} object entry
+  // and the V2 loader reads this same id for its {id, setup} schema check.
   id: "border",
+  setup: async (ctx: V2PluginContext): Promise<void> => {
+    // transform's return is awaited (Promise<Registration>), but the callback
+    // body itself must stay SYNCHRONOUS — only editor.add inside, any async
+    // work belongs in Info.execute (contract E3; pinned by v2shape test (d)).
+    await ctx.tool.transform((editor: V2ToolEditor): void => {
+      editor.add(makeV2ToolInfo());
+    });
+  },
   server: async () => ({
     // Self-registering /border: opencode calls hook.config(cfg) once per
     // instance after ALL config sources are merged — file-based commands are
@@ -251,22 +411,7 @@ export default {
     },
     tool: {
       border: tool({
-        description:
-          "Run the border fail-closed push-gate CLI on this machine. " +
-          "Pass the top-level command word in `command` (one of: check, push, status, " +
-          "llm-request, llm-ingest, scan, roundtrip, --help) and every remaining argv " +
-          "token in `extra`. The call is spawned argv-only (no shell) with a 300s " +
-          "timeout; the result always ends with the CLI exit code: 0 pass, 1 " +
-          "gate-blocked or partial push, 2 gate could not answer. Before running your " +
-          "argv the tool handshakes its binary candidate with `--help` and refuses " +
-          "everything (exit 2, cannot-answer) unless the responder provably is the " +
-          "border CLI — it never falls back to another binary. Honest privilege " +
-          "note: this tool runs the border CLI, and the CLI IS the gate that decides " +
-          "what leaves this machine — it carries the same power as the binary, so an " +
-          "agent may only *ask* the gate, never bypass it. `push --yes` is " +
-          "deliberately NOT reachable here: real pushes are the human gate and belong " +
-          "to a terminal. A bare `border push` through this tool is a DRY-RUN by the " +
-          "CLI's own contract.",
+        description: TOOL_DESCRIPTION,
         args: {
           command: tool.schema
             .string()
@@ -276,47 +421,13 @@ export default {
             .optional()
             .describe("remaining argv tokens, e.g. ['--force']"),
         },
+        // V1 edge: gate → V1-only metadata → shared substance (see gateArgv).
         execute: async (args, context) => {
-          const command = args.command.trim();
-          if (!ALLOWED_COMMANDS.includes(command)) {
-            return (
-              `border: refused '${command}' — not an allowed command. ` +
-              `Allowed: ${ALLOWED_COMMANDS.join(", ")}. Put the command word in 'command' ` +
-              `and every other token in 'extra'.`
-            );
-          }
-          const extra = args.extra ?? [];
-          if (extra.includes("--yes")) {
-            return (
-              `border: refused '${command}' with '--yes' — a real push is the human gate ` +
-              `and happens in a terminal. Run \`border push --yes\` there if a visible ` +
-              `human go-ahead exists. A bare \`border push\` through this tool is a ` +
-              `DRY-RUN by the CLI's own contract.`
-            );
-          }
-          const argv: readonly string[] = [command, ...extra];
+          const argv: readonly string[] = [args.command.trim(), ...(args.extra ?? [])];
+          const refusal = gateArgv(argv);
+          if (refusal !== null) return refusal;
           context.metadata({ title: `border ${argv.join(" ")}` });
-          const resolution = await resolveVerified();
-          if (!resolution.ok) {
-            return [
-              `$ border ${argv.join(" ")}`,
-              "exit: 2",
-              `note: cannot-answer — no border CLI passed the identity handshake, so nothing was run. Tried: ${resolution.reasons.join("; ")}. ` +
-                "Remedies: point BORDER_BIN at a real border CLI, run 'border opencode install' (route A), or npm i -g border-customs (PATH entry).",
-              "--- stdout ---\n(empty)",
-              "--- stderr ---\n(empty)",
-            ].join("\n");
-          }
-          const result = await runCli(resolution.resolution, argv, TIMEOUT_MS);
-          if (result.spawnFailed) verified = null;
-          const sections = [
-            `$ border ${argv.join(" ")}`,
-            `exit: ${String(result.status)}`,
-          ];
-          if (result.note.length > 0) sections.push(`note: ${result.note}`);
-          sections.push(`--- stdout ---\n${result.stdout.length === 0 ? "(empty)" : result.stdout}`);
-          sections.push(`--- stderr ---\n${result.stderr.length === 0 ? "(empty)" : result.stderr}`);
-          return sections.join("\n");
+          return buildToolResult(argv);
         },
       }),
     },