@mirrowel/opencode-openshare 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mirrowel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,182 @@
-# Temporary Holding Version
+# Open(code)Share plugin (`@mirrowel/opencode-openshare`)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The opencode side of [Open(code)Share](../README.md) — session sharing for
+OpenCode v1 and v2, self-hosted on your own worker.
+
+## Artifacts
+
+| Artifact | What it is | Share mode |
+|---|---|---|
+| `dist/server.js` | package server entry (opencode.json `plugin` array) | all, unless the TUI is registered |
+| `dist/tui.js` | package TUI entry (tui.json `plugin` array) | its presence flips the server to manual |
+| `ci/openshare.js` | single-file, zero-dependency bundle of the same engine (committed; rebuilt by `npm run build`) | always all — the CI bundle |
+
+All three are behavior-identical where they overlap — `npm run
+test:regression` proves the single file and the package match the frozen
+original (`reference/openshare.legacy.js`) on the full share lifecycle.
+
+## Install
+
+From the registry (published). **v1 hosts** — the bare package name in
+BOTH config files (no `/tui` suffix; opencode resolves the entrypoints
+itself):
+
+```jsonc
+// opencode.json
+{ "plugin": ["@mirrowel/opencode-openshare"] }
+// tui.json (global ~/.config/opencode/tui.json or project)
+{ "plugin": ["@mirrowel/opencode-openshare"] }
+```
+
+**v2 hosts** — the CLI writes the config for you:
+
+```sh
+opencode plugin add @mirrowel/opencode-openshare
+```
+
+Restart opencode; `/share` and `/openshare` appear in the TUI.
+
+Then configure. For an npm install the durable config file is the
+**settings home** (`~/.config/opencode/openshare.config.json` — also
+what `/openshare` writes); "next to the package" only applies to file
+installs (the CI bundle):
+
+```jsonc
+{
+  "servers": {
+    "https://your-worker.workers.dev": { "token": "osk_…", "active": true },
+    "https://team-server.example.com": { "code": "osc_invite-from-hoster" }
+  }
+}
+```
+
+`workerUrl`/`createToken` is the legacy single-server shorthand for the
+same thing — the `servers` form above is canonical.
+
+From a local checkout (developing / tracking main): use the directory
+spec `"file:///…/openshare/share-plugin"` in both config files (run
+`npm run build` first — `dist/` is not committed). The CI bundle needs
+no build at all: [`ci/openshare.js`](ci/README.md), committed ready to
+use.
+
+**With no token the plugin enrolls itself** on first contact: public
+servers (hoster set `AUTH_MODE=public`) take anyone; private ones need
+a `code` from the hoster (activation-budgeted invite). The enrolled
+token persists to `~/.config/opencode/openshare.config.json` — enroll
+once per server, then it just works. A revoked token re-enrolls the
+same way (public/code available); if enrollment is impossible the
+plugin says so on stderr and stops — no retry storms.
+
+## Share modes
+
+`shareMode` is explicit config (`"all"` / `"manual"`, env
+`OPENSHARE_SHARE_MODE` > plugin options > config file) or — when unset —
+**TUI presence**: the server scans the tui.json layers (global,
+`OPENCODE_TUI_CONFIG`, project directory chain) for the openshare TUI
+entry. Registered → manual (opt-in per session). Not registered → all.
+No selfwiring: which parts you install IS the switch.
+
+Manual mode stores the opt-in in session metadata:
+`metadata.openshare = { v: 2, enabled: true, opts? }` with per-session
+overrides (`ttlDays`, `authLogin`, `authPassword`, `modelLabel`). The
+per-server binding map (`servers: {url: {id, secret, rev, url}}`) is
+written next to it — legacy flat bindings migrate at read. The key is
+stripped from everything synced and never reaches viewers.
+
+On OpenCode v2: the package declaring its `tui` entrypoint is the presence
+signal (the v2 host auto-loads it); the single file declares none and
+stays all-mode.
+
+## TUI
+
+- `/share` — share the session (one-time consent; copies the URL). On a
+  child session, shares the whole family. Already shared → the share
+  manager: copy links (per server), per-server stop / leave-as-snapshot,
+  share to another server, stop all. A credential conflict opens the
+  collision dialog (copy debug info / share on a new share / don't share).
+- `/openshare` — grouped settings (compact root with live summaries →
+  focused submenus): This session (share/stop — delete or leave a
+  snapshot —, TTL override, session read auth), **Servers** (connection
+  AND membership: legacy pair, connect, enroll, rotate, get-a-user-token
+  for root holders, disconnect, per-server **admin panel** — users,
+  tokens, codes, shares, purge —, test, remove), Sharing (share mode +
+  booleans via selection menus), Read auth, Interface (one combined
+  Menu-size picker: live width cycling + height slider + capped-height
+  preview), Advanced, Config files. Danger rows red, dirty rows green,
+  `[i]` panes paged (`## sections`, 1-9 jump), messages wrap in real
+  bodies (no clipped one-liners).
+- Sidebar chip — share status next to the session title (`·N` when the
+  session streams to several servers); click copies the link. A share
+  whose page died server-side renders `⊘ gone` — clicking opens the share
+  manager, which verifies every bound server, auto-clears dead entries
+  and offers Share again (see Gone detection in the root README).
+- Every menu row carries an `[i]` detail pane (what it does, current
+  value + source, full URLs/ids); Interface rows set menu width/height
+  (host preference store).
+
+## Development
+
+```bash
+npm install
+npm run build         # tsc -> dist/ + bun bundle -> ci/openshare.js (Bun on PATH)
+npm run typecheck
+npm run test          # full matrix via the parallel driver (~4.5 min)
+npm run test:quick     # everyday gate (~90s): parity + manual core + TUI + v2 + auth
+```
+
+Suites (shared machinery in `scripts/suite-lib.mjs`; every run is
+watchdogged, port-swept, and drives real `opencode serve` instances with
+a mock OpenAI-compatible provider — except where noted):
+
+- `test:regression` — parity of legacy / single-file / package across the
+  full lifecycle (create → prompt → completed → delete → 404).
+- `test:manual` — dormancy, flag activation + backfill, restart attach,
+  unshare, re-share, per-session auth opts, all-override, pre-existing
+  gates, undo tombstones, completed debounce, turn-mode drops.
+- `test:tui-flow` — share/unshare flows, config round-trip, connect
+  flow (enroll + persist + rotate), admin console round-trip.
+- `test:v2` — the v2 adapter against a **scripted mock v2 host** (event
+  classification, message conversion, live re-sync, delete).
+- `test:auth` — the **server identity contract** exercised over HTTP/WS
+  (no opencode instance): enrollment, code burn, rotate, freeze (secret
+  dead too), limits, reassign, public mode (48 checks).
+- `test:enroll` — the plugin's enrollment lifecycle end to end (code
+  enroll, token persistence across processes, revoke → re-enroll,
+  blocked path, public zero-config).
+- `test:fanout` — multi-server: v2 bindings, content parity across
+  servers, mid-session join with full-history backfill, per-session
+  opt-outs.
+- `test:cli` — real `opencode run` end to end (single file + package +
+  silenced outputs; mock provider, sandboxed XDG homes) — on demand.
+- `node scripts/npm-e2e.mjs` — the **published** npm package installed
+  by registry spec, end to end — on demand.
+- `test:server-auth` / `test:server-enroll` — the SAME auth/enroll
+  suites against the portable Bun backend (`../share-server`): the
+  two-backends-one-protocol parity guarantee.
+
+Layout:
+
+```
+src/
+  config.ts        config load/save (servers group, field-level merge), shareMode, tui.json scan
+  core.ts          the engine: fan-out remotes (socket/spool/rev per server),
+                   ws handshake, chunked syncs, backfill, collisions, opt-outs
+  server.ts        v1 entry {id, server, setup}
+  tui.tsx          v1 TUI entry + host facade
+  commands.ts      /share (toggle + fan-out manager + collision dialog) /openshare
+  share-flow.ts    host-agnostic flows: flag, bindings v1/v2, enrollment,
+                   rotate/disconnect, admin client, unshare multi-delete
+  settings.ts      grouped settings tree + servers section + admin console
+  dialogs.tsx      MenuDialog/InfoDialog/PromptDialog + the sizing core (75% budget)
+  ui-prefs.ts      menu size prefs (host kv store)
+  sidebar.tsx      sidebar_title slot chip (v1, box-rooted)
+  tui-host.ts      host facade interface
+  v2-server.ts     v2 setup: event mapping + client adapter + v2->v1 conversion
+  v2-tui.ts        v2 TUI adapter (dialogs, keymap, kv)
+  v2-types.ts      structural v2 types (no SDK import)
+```
+
+The TUI surface (palette, dialogs, sidebar) is verified live; the flow
+logic is covered headlessly. The v2 integration is verified against a
+scripted host; run it live on a beta build via
+`bun run dev` in your beta checkout with both package entries registered.

package/ci/README.md

@@ -0,0 +1,56 @@
+# Open(code)Share — CI bundle (`openshare.js`)
+
+The single-file, zero-dependency build of the plugin. **Always shares all
+sessions** — this is the headless/CI artifact, behavior-identical to the
+package server (`../dist/server.js`), proven by `npm run test:regression`.
+
+This folder is deliberately separate from the package root so that loading
+the plugin by directory (`plugin: ["file:///…/share-plugin"]`) can only
+ever resolve the package — never this file.
+
+## Use
+
+Reference the FILE (not this folder) from a one-file config:
+
+```jsonc
+// OPENCODE_CONFIG (or opencode.json)
+{
+  "plugin": ["C:/path/to/share-plugin/ci/openshare.js"]
+}
+```
+
+Configure via env (CI) or the `openshare.config.json` next to the file —
+either the legacy pair or the `servers` group (recommended; see the root
+README's [Configuration](../../README.md#configuration)):
+
+```
+OPENSHARE_WORKER_URL=https://your-host
+OPENSHARE_CREATE_TOKEN=…            # legacy: root token
+OPENSHARE_URL_FILE=share-urls.txt   # each share URL appended + stderr line
+```
+
+```jsonc
+// openshare.config.json — enrollment shape (no root token needed)
+{
+  "servers": {
+    "https://your-host": { "code": "osc_…" }   // or "token": "osk_…"
+  }
+}
+```
+
+With no token held, the bundle **enrolls itself** on first contact
+(public servers take anyone; private ones consume the one-time code) and
+persists the token to `~/.config/opencode/openshare.config.json` —
+enroll once, then every run just shares. A revoked token re-enrolls the
+same way; if enrollment is impossible the error lands on stderr and
+sharing stops (no retry storms). The bundle also supports **fan-out**:
+multiple `active` servers in the `servers` group each get the session
+(one urlFile line per server).
+
+On OpenCode v2, plugin targets should be directories/packages — wrap this
+file in a folder with a `package.json` exporting it (`{"exports": {".": "./openshare.js"}}`)
+or install the package instead; the bundle itself works unchanged (its
+`setup` is the v2 adapter, and with no package.json present it stays
+share-all).
+
+Rebuild after changing `../src/`: `npm run build` in the package root.

package/ci/openshare.config.json

@@ -0,0 +1,10 @@
+{
+  "$comment": "Open(code)Share CI bundle config. This file sits NEXT TO openshare.js and is read at load; OPENSHARE_* env vars always win (the CI way). The single-file bundle ALWAYS shares all sessions. Prefer the servers form below (workerUrl/createToken is the legacy single-server shorthand). Empty string means unset. urlFile/announceStderr control the two URL outputs; 'none' disables the file.",
+  "servers": {
+    "https://your-worker.workers.dev": { "token": "" }
+  },
+  "workerUrl": "",
+  "createToken": "",
+  "urlFile": "",
+  "announceStderr": true
+}