opencode-webui 2.4.0 → 3.0.1

package/README.md

@@ -22,8 +22,8 @@ First boot prints the URL and a generated password — **shown once**:
               generated for this install — shown once
               set WEBUI_PASSWORD to choose your own
   sessions    the same ones as your opencode TUI — same engine, same history
-  extensions  ~/.config/opencode/webui-extensions/<name>/main.tsx   per-user
-              <project>/.opencode/webui-extensions/<name>/main.tsx  per-project
+  extensions  ~/.config/opencode/webui-extensions/<name>/index.tsx   per-user
+              <project>/.opencode/webui-extensions/<name>/index.tsx  per-project
   skill       agent skill synced to ~/.config/opencode/skills/webui/ — your agent knows this UI exists
 ```
 
@@ -37,9 +37,63 @@ Options:
 | `WEBUI_TRUST_PROXY` | unset | Set to `1` when a trusted reverse proxy sits in front, so `X-Forwarded-Host`/`Proto` are honored. Without it those headers are ignored. |
 | `WEBUI_PROXY_PORT` | `4097` | Port for the UI and `/api/*`. |
 | `WEBUI_EXTENSION_DIR` | the global + project dirs | Adds a higher-precedence source shadowing both (the sandbox uses this to keep WIP isolated; shipped extensions still load underneath). |
+| `WEBUI_NO_SETUP` | unset | `1` skips first-run setup for this run (CI, one-offs). |
+| `WEBUI_NO_PLUGIN` | unset | `1` installs the global command but not the OpenCode lifecycle plugin. |
+| `WEBUI_SETUP` | unset | `1` forces setup even in a repo checkout (testing). |
+
+The serve/security vars above can also be set **durably** — no shell needed —
+in `~/.config/opencode/webui/config.json`, edited from **Settings › Access** in
+the UI or `opencode-webui config` on the CLI. Precedence per key is
+**explicit env var → config file → default**; changes apply after a restart
+(the Access tab has a "Restart now" button). The file is `0600`; a password set
+there is stored as a SHA-256 hash, never plaintext. Setting a reachable bind or
+`allowedHosts: ["*"]` is allowed but warned about, and a *reachable* instance
+with **no password** needs an explicit confirmation.
 
 Sessions are shared with the `opencode` TUI — open a session in the TUI, continue it in the browser.
 
+### Setup (run once) — the `opencode-webui` command + OpenCode plugin
+
+First boot self-installs two things, so you don't pay for `bunx` on every
+start and the webui comes up with OpenCode:
+
+1. **A global `opencode-webui` command** (`~/.local/bin/opencode-webui`, or
+   `WEBUI_BIN_DIR`) that execs the installed entry directly — fast, no bunx
+   resolution. The first-boot banner tells you if that directory isn't on
+   `PATH`.
+2. **A built-in OpenCode lifecycle plugin** written to
+   `~/.config/opencode/plugins/opencode-webui/`, which the engine
+   auto-discovers. It starts the webui in the background as soon as OpenCode
+   activates its plugins (i.e. when you use OpenCode) — detached,
+   fire-and-forget, and it never starts a second copy (a running webui answers
+   on its port and wins).
+
+```sh
+opencode-webui            # start (starts the opencode service first if needed)
+opencode-webui update     # update to the latest version and restart
+opencode-webui status     # command, plugin, launch command, running pid
+opencode-webui restart    # restart the background webui
+opencode-webui stop       # stop it
+opencode-webui uninstall  # remove the command + plugin (remembered; no auto-reinstall)
+```
+
+A repo checkout (`bun run dev` / `bun run start`) never self-installs, so
+development cannot fight your installed command. `WEBUI_NO_SETUP=1` skips
+setup for one run, `WEBUI_NO_PLUGIN=1` installs the command but not the plugin,
+and `autostart: false` in the config (the **Startup** toggle in Settings ›
+Access) turns it off persistently. The plugin only ever starts a webui that is
+already installed; it installs only its own folder and removes it cleanly on
+`uninstall`.
+
+```sh
+opencode-webui config                 # show effective serve settings + source
+opencode-webui config set host 0.0.0.0
+opencode-webui config set allowed-hosts 192.168.1.5,myserver.lan
+opencode-webui config set password    # read from stdin
+opencode-webui config set auth none --confirm   # no login (warned)
+opencode-webui restart                # apply
+```
+
 ## Install (no Bun)
 
 Binaries are attached by CI on each version tag — grab one for your platform from
@@ -62,6 +116,13 @@ chmod +x opencode-webui-linux-x64
 Behind a reverse proxy (Caddy / nginx samples, incl. websocket + SSE timeouts):
 [docs/reverse-proxy.md](docs/reverse-proxy.md).
 
+## Install as app (PWA)
+
+Over HTTPS (e.g. Tailscale serve) Chrome offers install — standalone window, splash, home-screen icon.
+Settings → App shows install state plus the **live activity tile**: one silent notification following
+active sessions (dense strip text, tap opens that session, clears itself when idle). Needs notification
+permission; plain-LAN HTTP stays a browser tab (secure context required).
+
 ## Sandbox
 
 A second, private instance for agents (or you) to test extensions and settings
@@ -98,8 +159,8 @@ One extension = one folder, dropped in — no rebuild, no restart:
 
 ```
 my-extension/
-  manifest.json    id, version, description, disabled?
-  index.tsx        browser stratum (wrap / replace / contribute / hook / service)
+  manifest.json    id, version, description; optional disabled, settings, requires
+  index.tsx        browser stratum: register() and/or activate(ctx)
   dom.ts           DOM stratum (portals, canvas, post-render tweaks)
   server.ts        proxy stratum (routes, middleware, event tap, pollers)
   engine/          opencode plugin payload (model tools, prompt hints)
@@ -109,9 +170,10 @@ Presence = installed, `disabled: true` = paused, delete = uninstalled; a
 higher-precedence folder with the same id shadows the shipped one, so user
 customizations survive core updates with no forks. Hot reload everywhere:
 browser edits repaint live via the manifest SSE push, proxy edits reload
-with no restart. The full authoring guide — the five kinds, hook catalog,
-DOM kit, `server.ts` mounts, precedence, and the timestamp worked example —
-is [webui-extensions/README.md](webui-extensions/README.md).
+with no restart. The full authoring guide — the five kinds, the activation
+context, the event bus, declared settings + `requires`, slots, peer
+composition, the DOM kit, `server.ts` mounts, precedence, and the timestamp
+worked example — is [webui-extensions/README.md](webui-extensions/README.md).
 
 The built-in `/report` command files a prefilled GitHub issue with a diagnostics
 bundle (build version, enabled extensions, error ring); `--agent` hands it to the
@@ -121,14 +183,20 @@ session agent instead, so it can file it via `gh`.
 
 ```sh
 bun install
-bun run dev        # proxy (4097) + Vite (5173), HMR
+bun run dev        # proxy (config port, default 4097) + Vite (5173), HMR
 bun run sandbox    # isolated second instance (4099 / 5175, Vite in dev) — see Sandbox above
 bun run typecheck
 bun run build && bun start   # production: dist/ + API on 4097
 ```
 
+To open the dev UI from a phone/Tailscale, set the bind address to `0.0.0.0`
+and add your host under **Settings › Access** — Vite honors the same values, so
+`http://<this-machine>:5173` works (the proxy stays on its own port).
+
 - Extension authoring guide: [webui-extensions/README.md](webui-extensions/README.md)
 - Extension contract check: `bun run scripts/uitest/extensions-check.ts`
+- Setup check: `bun run check:setup` (global command + lifecycle plugin + CLI, isolated HOME/XDG)
+- Config check: `bun run check:config` (resolution/precedence, validation, exposure, `config` CLI)
 - Architecture, editing rules, roadmap: [AGENTS.md](AGENTS.md)
 
 ## License