@te-river/opencode-team-mode 1.5.15 → 1.6.1

package/docs/research/plugin-loader-contract.md

@@ -0,0 +1,261 @@
+# OpenCode 2.0.16 — how the host actually loads a plugin from `config.plugins`
+
+**Scope:** read-only forensics. The strings below were cut out of
+`resources/opencode-cli.exe` with a windowed byte scan; the live confirmations were
+run against a sandboxed `OPENCODE_CONFIG_DIR` + temp store roots. Nothing in the host
+was modified, and no path, URL, command line or env value of the user's appears here.
+
+**Why this page exists.** The official v2 plugin docs document a `"plugins"` key
+(a list of package names), and for a while our answer to "can the installer just write
+that key?" was "no, it does not load". That answer was **wrong**, and the wrong answer
+was the reason the installers carried a cache-purge/re-resolve story that v2 does not
+need. This page is the corrected contract, with the host's own code as the evidence.
+
+## 0. Where each claim comes from
+
+| Tag | Source | Strength |
+|---|---|---|
+| `[B]` | Verbatim from the embedded Effect/JS in `resources/opencode-cli.exe` (`opencode-cli.version` reads `2.0.16`) | strongest offline |
+| `[L]` | Our own live boot probe against a sandboxed config dir (`--standalone`, `--print-logs`, `v2-boot` trajectory line) | strongest overall |
+| `[R]` | Our repo (`index.js`, `package.json#files`) | ours, verified |
+| `[D]` | Official v2 docs | corroborating |
+
+## 1. The entry: `config.plugins` is read, mapped, then resolved
+
+The code blocks below are the host's own minified text **reformatted for reading**:
+identifiers, strings and control flow are untouched, whitespace is not. The unmodified
+bytes are in the extract window quoted per line.
+
+`[B]` `ConfigPluginSource.scan` (minified `BN`) takes `l.info.plugins ?? []` from every
+parsed config **document** and maps each entry through the operation builder `DN`:
+
+```js
+function DN(e){
+  if (typeof e !== "string") return {type:"add", target:e.package, options:e.options ?? {}}
+  if (!e.startsWith("-"))   return {type:"add", target:e, options:{}}
+  if (e.length === 1) throw Error("Plugin remove operation requires a target")
+  return {type:"remove", target:e.slice(1)}
+}
+```
+
+So an entry is either a bare string, an object `{package, options}`, or a
+**`-<target>` string that removes** a previously-declared plugin. Then the target is
+resolved relative to the file that declared it:
+
+```js
+let g = l.path ? ln.dirname(l.path) : a.directory
+let v = c.target.startsWith("file://")  ? dm(c.target)
+      : (c.target.startsWith("./") || c.target.startsWith("../"))
+        ? ln.resolve(g, c.target)
+        : c.target
+```
+
+`[B]` Three branches follow, and they are the whole answer to the installer question:
+
+1. **Not absolute** (a plain npm/git specifier) → handed to the package installer
+   (`PluginModule.load` calls `Bun.add(target)` unless `options.install === false`),
+   i.e. `"@te-river/opencode-team-mode@latest"` works exactly as documented.
+2. **Absolute and a FILE** → `Dt("configured plugin path must be a directory", {target})`
+   (a warning) and the entry is dropped (`Ie()`).
+3. **Absolute and a DIRECTORY**, or a relative path that resolved to one → the entrypoint
+   is resolved for the directory, and **if that resolution yields no server the entry
+   returns `[]` — no log, no warning, no error**:
+
+```js
+let c = yield*e.isDir(l.target)
+let g = c ? yield*y(()=>U0({directory: l.target})) : {server: UN(l.target).href}
+if (!g.server) return []            // <-- silent
+if (c) { let k = resolve(l.target), f = resolve(dm(g.server))
+         if (!contains(k, f)) return [] }   // entrypoint must live inside the dir
+```
+
+`[L]` This is the branch that ate our afternoon: `plugins: ["C:/…/team-mode"]` pointing at
+a directory that declared only `package.json#exports` produced **one line of output —
+nothing** — and a perfectly healthy-looking host with no Team tools.
+
+## 2. What a directory must contain to be loadable
+
+`[B]` `PluginModule.load` (minified `SB`) resolves the entrypoint and only then logs:
+
+```js
+// PluginModule.load (SB): `r` = target is absolute, `i.install === false` skips the
+// package installer, `U0` is the entrypoint resolver, `rL` is the host's log call.
+let p = r ? void 0 : (i?.install === false ? await resolve(e.target) : await add(e.target))
+let l = r && (await stat(e.target)).isFile()
+        ? {server: fileURL(e.target).href}
+        : await U0(p ?? {directory: e.target})
+let c = l.server
+if (!r && i?.install === false && !c) return {pending: true}
+if (!c) return new LoadError({message: `Plugin entrypoint not found: ${e.target}`})
+yield* log({msg: "loading plugin", id: e.target, entrypoint: c})
+```
+
+and the module must then validate as a definition:
+
+```
+Plugin must export a default definition with an id and an effect or setup function.
+```
+
+`[L]` For a **directory** target, the entrypoint that `U0` returns on 2.0.16 is
+`<dir>/index.js`. Measured with `--print-logs`:
+
+```
+msg="loading plugin" id=…\vendor\team-mode entrypoint=file:///…/vendor/team-mode/index.js
+```
+
+A directory holding only `package.json` (`exports` → `./dist/index.js`, `main` likewise)
+is **not** resolved to `dist/index.js` — it falls into the `if (!g.server) return []`
+branch above and is skipped with no message at all. That is why the package now ships a
+root [`index.js`](../../index.js) `[R]` re-exporting `./dist/index.js`, and why it is in
+`package.json#files`: it is part of the host contract, not a convenience shim.
+
+## 3. Consequences for the installer
+
+- `"plugins"` **is** the right key to write, and the documented npm-specifier form works
+  without a cache purge: the host's own `opencode plugin add` installs and writes that
+  field (`[D]`+`[L]`). v1's purge machinery has nothing to do on v2.
+- A **local** install (this repo, or a copy on disk) must point at a **directory that
+  contains `index.js`**, and the value must be relative (`"./vendor/team-mode"`, resolved
+  against the config file's own directory) or an absolute directory. An absolute path to
+  `index.js` itself is refused as "must be a directory".
+- Whatever path style is used, the only proof of success is the host's own
+  `msg="loading plugin"` line or our `v2-boot` trajectory row — never the config write
+  returning 0. The silent `return []` has no diagnostic to fail on.
+- Dedup matters: the same plugin reachable both as an npm cache copy and as a local
+  directory is loaded twice, and the second registration is the one that wins the hooks.
+  `PluginModule.watch` keeps a per-path set, so two *different* paths are two watchers.
+
+## 5. The entrypoint resolver, in full (`U0`)
+
+`[B]` Everything above funnels into one small function, and it is the reason a local
+install has exactly one legal shape. Reformatted for reading; identifiers untouched:
+
+```js
+function U0(r){
+  let n = (t) => {
+    for (let o of t) {
+      let i = r.name ? [r.name, o].filter(Boolean).join("/") : s.resolve(r.directory, o || "index")
+      try { return R0(i, r.directory) }              // resolve as a module specifier
+      catch (e) { if (!["ENOENT","ENOTDIR","MODULE_NOT_FOUND","ERR_MODULE_NOT_FOUND",
+                       "ERR_PACKAGE_PATH_NOT_EXPORTED","ERR_UNSUPPORTED_DIR_IMPORT"]
+                     .includes(String(e.code))) throw e }
+    }
+    return                                            // nothing resolved → undefined
+  }
+  return { server: n(["server",""]), tui: n(["tui"]), rpc: n(["rpc"]) }
+}
+```
+
+Read it as a decision table:
+
+| target | what `U0` is called with | what resolves |
+|---|---|---|
+| an installed package | `{name:"@te-river/opencode-team-mode", directory:<cache>}` | the specifier `@te-river/opencode-team-mode/server`, then the package root — i.e. `package.json#exports`, so `dist/index.js` arrives |
+| a directory path | `{directory:<path>}` (no `name`) | `resolve(dir, "index")` → **`<dir>/index.js`** and nothing else |
+
+So the asymmetry is not a documentation gap, it is the code: a package may declare its
+entrypoint, a directory may not. A directory that resolves nothing returns
+`{server: undefined}`, and `ConfigPluginSource.scan` then drops the entry with
+`return []` — the silent skip in §1. `[L]` Measured both ways on 2.0.18: with a root
+`index.js` the host logs `entrypoint=file:///…/vendor/team-mode/index.js`; without it,
+the boot is clean and the plugin is simply absent.
+
+`features.tui` / `features.rpc` in the load result come from the same call, which is why
+a TUI-only plugin is recorded somewhere else — see §6.
+
+## 6. What `opencode plugin add` actually does
+
+`[B]` The subcommand (`cli.plugin.add`) is four steps, and each one closes an option the
+installer might otherwise reach for:
+
+```js
+if (!(yield* ne(()=>pP(e.package))))
+  return h(Error("Plugin target must be an npm registry package or Git package specifier"))
+let r = yield* (yield* ga).add(e.package)          // install
+let l = U0(r), o = k(l.server, l.tui)              // configurationTarget: "server" | "tui"
+if (!o) return h(Error(`Plugin package has no server or TUI entrypoint: ${e.package}`))
+```
+
+- **A local directory is refused**, by name. Vendoring a tree is therefore a config edit,
+  never a `plugin add`.
+- A **server** plugin is written by `writePluginConfig` into the global config the Config
+  service names (`i.config`). `[L]` Measured with a redirected `HOME`: it created and
+  edited `~/.config/opencode/opencode.json` — not the `.jsonc` — and printed the file it
+  touched.
+- Its dedupe is `d(t, n)`: `r === n || (typeof r === "object" && r.package === n)`, i.e.
+  **the identical string only**. Two spellings of one plugin are two entries.
+- It parses with `allowTrailingComma`, edits the AST (`Ru(doc, ["plugins"], [...t, n])`,
+  tab size 2) and swaps the file through `<file>.tmp` + rename, mode `0o600`. So a
+  trailing comma in a user's array is legal to the host — and the reason our own writer
+  must not leave one dangling is that the NEXT hand edit may not be a lenient parser.
+- A **TUI-only** plugin goes to a different service (`Il`) with its own `plugins` array.
+  Our package has a `server` entrypoint, so it always takes the first branch.
+
+## 7. Why two entries really do load twice
+
+`[B]` `PluginSupervisor.resolve` iterates the operations and, before loading, asks only
+whether the target matches an already-known plugin **id**:
+
+```js
+let l = (N,O) => N === "*" || (N.endsWith(".*") ? O.startsWith(N.slice(0,-1)) : N === O)
+let O = S().filter((ee) => l(N.target, ee.id))
+if (O.length > 0 || N.target === "*" || …) { O.forEach(ee => g.add(ee.id)); continue }
+let Q = yield* e.load(N, { install: s })          // otherwise: load it
+```
+
+`N.target` is the config string (`@te-river/opencode-team-mode@latest`, or a path) and
+`ee.id` is the plugin's own exported id (`team-mode`). They are never equal, so that
+guard is a no-op for package entries, and a second operation for the same package
+reaches `e.load` again. `[L]` Confirmed: the same spec present in `opencode.json` and
+`opencode.jsonc` produced two `msg="loading plugin"` lines for one id, with no warning —
+two personalities, the same tools and hooks bound twice.
+
+A load failure is loud, unlike the directory skip: `failed to load plugin` carries
+`target`, a `ref`, and the cause, and `PluginModule.LoadError` is what `@opencode-aide`
+1.6.0 produces on a 2.x host —
+
+```
+Plugin must export a default definition with an id and an effect or setup function.
+(cause: SchemaError(Missing key at ["default"]["effect"] / ["default"]["setup"]))
+```
+
+because the accepted shape is a union, `bB = U([ {id, effect:fn}, {id, setup:fn} ])`, and
+a v1-only `{id, server}` default satisfies neither. That is the whole reason this package
+ships one barrel exporting both personalities.
+
+## 8. What the Extensions panel's row name tells you (and what it does not)
+
+`[L]` Observed on the user's desktop, before and after a config change: a plugin loaded
+from `~/.config/opencode/plugins/team-mode.js` (the directory-scan path the docs
+describe) is listed as `team-mode`, which is that FILE's basename, while an npm entry is
+listed verbatim as `@te-river/opencode-team-mode@latest`. A `plugins` entry pointing at a
+local directory also listed itself as `team-mode` — the loaded plugin's own id.
+
+The mechanism is inferred, the consequence is not: **the row name cannot tell you which
+spelling is installed**, because a file named `team-mode.js` and a package whose id is
+`team-mode` print identically. Two rows that look like one plugin may be two loads, and
+one row may be either a loader file or a directory entry. The only channel that
+distinguishes them is `msg="loading plugin" id=<target> entrypoint=<url>`, which names
+the config string and the resolved file, and our own `v2-boot` trajectory line.
+
+**How the installers use this:** `scripts/lib/config-surgery.cjs` keeps exactly one Team
+entry across `opencode.jsonc` and `opencode.json`, matching our own entries by
+`/opencode[-_]?team[-_]?mode|vendor[/\\]team-mode/i` — case- and hyphen-tolerant, because
+a working tree is `D:/Github/Opencode-TeamMode` and an entry it fails to recognise is one
+it would add beside the existing one.
+
+
+## 9. What this page does NOT establish
+
+`[U]` Whether an object entry's `options` carries anything beyond `install:false` — the
+scanned code reads only that field, which is not a claim that nothing else exists.
+`[U]` Whether the `<dir>/index` resolution survives a future host: it is read off 2.0.16
+and 2.0.18, and the shipped `package.json#exports` stays as the belt while the root
+`index.js` is the part this contract requires. `[U]` Which file the Config service names
+as `i.config` when both `opencode.json` and `opencode.jsonc` exist — measured only in the
+case where the `.jsonc` was absent, so the installers do not depend on it: they write the
+`.jsonc` and reclaim their own entry from the `.json`. `[U]` Whether the host prunes the
+timestamped `~/.cache/opencode/npm/<pkg>@latest/<ts>/` directories: one existed after
+several installs on this machine, which is an observation, not a garbage-collection
+guarantee.
+