@mirrowel/opencode-openshare 0.2.1 → 0.3.0-dev.10

package/README.md

@@ -1,8 +1,28 @@
 # Open(code)Share plugin (`@mirrowel/opencode-openshare`)
 
-The opencode side of [Open(code)Share](../README.md) — session sharing for
+The opencode side of [Open(code)Share](../README.md) - session sharing for
 OpenCode v1 and v2, self-hosted on your own worker.
 
+**This package is only the plugin.** It captures and uploads sessions, but a
+share needs a backend to upload to. OpenShare ships as four parts that
+version and release together:
+
+| Part | What it does | Where to get it |
+|---|---|---|
+| **This plugin** | hooks into opencode, syncs sessions | this npm package |
+| **Worker** | the Cloudflare backend - stores shares, serves the viewer | deploy from the repo: `share-worker/` (3-command setup, see the repo README) |
+| **Server** | self-hosted alternative to the worker - one Bun process, SQLite, Docker image | repo `share-server/` |
+| **Viewer** | the share page - ships inside the worker/server assets; nothing to install separately | repo `share-viewer/` (embedded automatically) |
+
+The repo also builds **offline snapshots** - a single self-contained HTML
+file of any share, generated by the viewer's download button or the
+`osh-snapshot` CLI - so a shared link keeps working even with no backend at
+all.
+
+Everything lives in one repository: **https://github.com/Mirrowel/openshare**
+(clone it, or browse the [README](https://github.com/Mirrowel/openshare#readme)
+for the full picture - deployment, configuration, and the viewer tour).
+
 Every plugin config key, its file chain, and the cross-package config surface are inventoried in [../CONFIGURATION.md](../CONFIGURATION.md).
 
 ## Artifacts
@@ -14,8 +34,9 @@ Every plugin config key, its file chain, and the cross-package config surface ar
 | `ci/openshare.js` | single-file, zero-dependency bundle of the same engine (committed; rebuilt by `npm run build`) | all-mode **by default** — it declares no TUI entry, but an explicit `shareMode` in config/env still wins |
 
 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.
+test:regression` drives the single file and the package entry through
+the same real lifecycle (a local worker, a mock provider, a real
+`opencode serve`) and diffs the resulting share data.
 
 ## Install
 
@@ -36,7 +57,9 @@ itself):
 opencode plugin add @mirrowel/opencode-openshare
 ```
 
-Restart opencode; `/share` and `/openshare` appear in the TUI.
+Restart opencode; `/share` and `/openshare` appear in the TUI. The
+settings dialog's title carries the running plugin's version (read from
+its own package manifest at runtime).
 
 Then configure. For an npm install the durable config file is the
 **settings home** (`~/.config/opencode/openshare.config.json` — also
@@ -61,12 +84,26 @@ spec `"file:///…/openshare/share-plugin"` in both config files (run
 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
+**Server-held config sets**: set `configSet` (or
+`OPENSHARE_CONFIG_SET`) to pick a named set provisioned on your server
+token - the server applies its auth/TTL at create (nothing sensitive in
+the repo), and suggests modelLabel/shareMode which the plugin adopts once
+per boot when you haven't set them locally.
+
+**Identity is never assumed**: with no token configured the plugin does
+NOT silently enroll. A configured `code` IS expressed
+intent — the engine enrolls with it headlessly (the CI shape). Without
+one: public servers share **anonymously** (ownerless shares under the
+server's global anonymous caps), private servers refuse with guidance.
+Onboarding happens through the ask-once TUI flow — `/share` first run
+or `/openshare` → Servers → Connect to a server offers "Onboard (get an
+account)" vs "Stay anonymous" (with the differences explained), detects
+whether a code is needed, and only then prompts for one; the outcome is
+remembered per server (token = onboarded, `anonymous` flag = declined,
+onboard later via the server menu's Enroll now). 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
+(code configured / codeless server); if enrollment is impossible the
 plugin says so on stderr and stops — no retry storms.
 
 ## Share modes
@@ -80,7 +117,7 @@ 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
+overrides (`ttlHours`, `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.
@@ -89,6 +126,19 @@ 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.
 
+## Trust controls (config)
+
+Client-side redaction runs at the engine's single enqueue choke point
+(backfill and live events both), so stripped secrets never reach a
+queue, spool or wire:
+
+- `redact.patterns` — extra regexes (strings) redacted beside the built-in
+  detectors on UNGATED shares only (a gated share is already
+  login-private): GitHub/AWS/Slack/Google key shapes, `sk-` keys, Bearer
+  tokens, PEM private-key blocks, `.env`-shaped assignments and
+  connection-string passwords, replaced with `[redacted:<kind>]`. The
+  consent dialog previews counts and the first hits.
+
 ## TUI
 
 - `/share` — share the session (explicit consent on EVERY creation —
@@ -96,12 +146,13 @@ stays all-mode.
   session, shares the whole family. Already shared → the session menu,
   identical to `/openshare → This session`: copy links (per server, or
   all), stop sharing — delete or leave a snapshot, per-server stop on
-  multi-server shares —, share to another server, session TTL and read
+  multi-server shares —, share to another server, session TTL, read
   auth. 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
+  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 +
@@ -120,13 +171,17 @@ stays all-mode.
   value + source, full URLs/ids); Interface rows set menu width/height
   (host preference store).
 
+## Versioning
+
+Releases are automatic (conventional commits). The plugin reports its version in the `/openshare` title; the system version ships in every part and the worker's `/health` carries it in full (`version · date · commit`). Designating a version by hand: `bash .github/scripts/release-kit.sh next <1.2.3|major|minor|patch>` in the repo (see DEVELOPMENT.md).
+
 ## 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          # full matrix via the parallel driver (~2.5 min)
 npm run test:quick     # everyday gate (~90s): parity + manual core + TUI + v2 + auth
 ```
 
@@ -135,20 +190,11 @@ watchdogged, port-swept, and drives real `opencode serve` instances with
 a mock OpenAI-compatible provider — except where noted). The canonical
 suite table — what each covers, including the big/backends scale suites —
 lives in [`../DEVELOPMENT.md`](../DEVELOPMENT.md#test-suites); the
-commands:
-
-- `test:regression` — parity of legacy / single-file / package across the
-  full lifecycle.
-- `test:manual` — the engine scenarios (dormancy, backfill, tombstones,
-  timers, turn sockets, all-mode gating).
-- `test:tui-flow` — share/manager flows, config write targets, enrollment,
-  admin console, gone detection.
-- `test:v2` — the v2 adapter against a scripted mock v2 host.
-- `test:auth` / `test:server-auth` — the identity contract (52 checks)
-  against the Cloudflare worker and the Bun backend.
-- `test:enroll` / `test:server-enroll`, `test:fanout`, `test:big` /
-  `test:server-big` — enrollment lifecycle, multi-server fan-out,
-  big-session scale (both backends).
+everyday commands:
+
+- `test:quick` — the everyday gate: parity + manual core + TUI + v2 + auth.
+- `test:auth` / `test:server-auth` — the identity contract against the
+  Cloudflare worker and the Bun backend.
 - `test:cli`, `node scripts/npm-e2e.mjs` — real `opencode run` / the
   published npm package — on demand only.
 

package/ci/README.md

@@ -31,10 +31,22 @@ README's [Configuration](../../README.md#configuration)):
 
 ```
 OPENSHARE_WORKER_URL=https://your-host
-OPENSHARE_CREATE_TOKEN=…            # legacy: root token
+OPENSHARE_CREATE_TOKEN=:            # legacy: root token
 OPENSHARE_URL_FILE=share-urls.txt   # each share URL appended + stderr line
 ```
 
+CI conveniences:
+
+- `OPENSHARE_CONFIG_JSON` - the whole config as one env var (same keys as
+  the config file), when mounting a file is awkward. A specific
+  `OPENSHARE_*` var still wins over it.
+- `OPENSHARE_URL_FILE_FORMAT=json` - urlFile lines become
+  `{"id":"…","url":"…","status":"…","gated":false}` objects, one per
+  line, so workflow steps read fields instead of parsing URLs.
+- `meta` in the config stamps free-form labels (env-interpolated, e.g.
+  `"branch": "${GITHUB_REF_NAME}"`) onto every share - visible in the
+  server's admin shares listing.
+
 ```jsonc
 // openshare.config.json — enrollment shape (no root token needed)
 {
@@ -44,22 +56,26 @@ OPENSHARE_URL_FILE=share-urls.txt   # each share URL appended + stderr line
 }
 ```
 
-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).
+With no token held the bundle never silently enrolls: a configured
+`code` enrolls with it headlessly (the CI shape — each code use is one
+enrollment); without one, public servers share anonymously (ownerless
+shares under the server's global anonymous caps) and private servers
+refuse with guidance. When enrollment does run, the token persists to
+`~/.config/opencode/openshare.config.json` — enroll once, then every
+run just shares. A revoked token re-enrolls the same way (code
+configured / codeless server); if enrollment is impossible the error
+lands on stderr and sharing stops (no retry storms).
 
 **Ephemeral runners** (GitHub-hosted, containers): do NOT enroll through
 a code - each fresh machine would burn one activation. Ask the hoster
-for a pre-minted registered token (`osk_…`) and pass it via
-`OPENSHARE_CREATE_TOKEN` (or the config's token field) - registered
-tokens skip enrollment entirely and never expire on their own. Point
-`OPENSHARE_CONFIG_DIR` (or mount) the settings home at a cached path
-only if you want the token persisted; env alone is enough. Note:
-revoking that token (when it is the user's last) freezes control of all
-its shares server-side, even ones holding the share secret.
+for a pre-registered token and pass it via `OPENSHARE_CREATE_TOKEN`
+(or the config's token field); registered tokens skip enrollment
+entirely and never expire on their own. A **scoped** token
+(`POST /api/token {"kind":"scoped"}`, minted by any full token) is the
+right credential here: it creates within its limits, reaches only the
+shares it created, and revoking it never freezes the owner's account.
+Point `OPENCODE_CONFIG_DIR` (or mount) the settings home at a cached
+path only if you want the token persisted; env alone is enough.
 
 The bundle also supports **fan-out**: multiple `active` servers in the
 `servers` group each get the session (one urlFile line per server).