opencode-webui 2.4.0 → 3.0.1

package/server/userExtensions.ts

@@ -11,7 +11,8 @@
  * the folder to uninstall. No config.ts list, no per-browser localStorage.
  *
  * Folder anatomy (new format; legacy `main.tsx`-only folders still load):
- *   manifest.json   { id?, name?, version?, description?, disabled? }
+ *   manifest.json   { id?, name?, version?, description?, disabled?,
+ *                     settings?, requires?, capabilities? }
  *   index.tsx       browser stratum entry (preferred)
  *   main.tsx        legacy browser entry (fallback)
  *   dom.ts          DOM stratum entry (spec §7 — post-render DOM changes)
@@ -23,7 +24,7 @@
  * (no index/main entry) still lists with only `domUrl`.
  */
 
-import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -37,6 +38,20 @@ export type UIEntry = {
   domEntry?: string;
   domMtimeMs?: number;
   source?: string;
+  /** manifest.json display fields, surfaced in Settings › Extensions. */
+  name?: string;
+  description?: string;
+  /**
+   * manifest.json `settings` — the declared settings schema (roadmap 5).
+   * Opaque here: the browser parses/normalizes it (`src/extensions/manifest.ts`);
+   * the proxy only carries it to the manifest so Settings can render it even
+   * while the extension is paused.
+   */
+  settings?: unknown;
+  /** manifest.json `requires` — the checkable contract (roadmap 8). Opaque. */
+  requires?: unknown;
+  /** manifest.json `capabilities` — declared capabilities (roadmap 8). Opaque. */
+  capabilities?: unknown;
   /** manifest.json `disabled: true` — paused, never bundled or imported. */
   disabled?: boolean;
   /** Which of the three sources won for this id. */
@@ -86,6 +101,17 @@ export function warnOnce(key: string, message: string): void {
   console.warn(`[webui] ${message}`);
 }
 
+/** Pass a malformed manifest field through as absent, warning once (roadmap 8). */
+function malformed(value: unknown, id: string, field: string): undefined {
+  if (value !== undefined) {
+    warnOnce(
+      `ext-manifest:${id}:${field}`,
+      `extension "${id}" manifest.json \`${field}\` has the wrong shape — ignored`,
+    );
+  }
+  return undefined;
+}
+
 let cache: { at: number; entries: UIEntry[] } | null = null;
 
 /** Drop the discovery cache so the next read re-scans disk (watcher path). */
@@ -93,11 +119,29 @@ export function invalidateExtensionCache(): void {
   cache = null;
 }
 
-function readManifest(dir: string): { id?: unknown; disabled?: unknown } | null {
+function readManifest(dir: string): {
+  id?: unknown;
+  disabled?: unknown;
+  name?: unknown;
+  description?: unknown;
+  settings?: unknown;
+  requires?: unknown;
+  capabilities?: unknown;
+} | null {
   try {
     const raw = readFileSync(join(dir, "manifest.json"), "utf8");
     const parsed: unknown = JSON.parse(raw);
-    if (parsed && typeof parsed === "object") return parsed as { id?: unknown; disabled?: unknown };
+    if (parsed && typeof parsed === "object") {
+      return parsed as {
+        id?: unknown;
+        disabled?: unknown;
+        name?: unknown;
+        description?: unknown;
+        settings?: unknown;
+        requires?: unknown;
+        capabilities?: unknown;
+      };
+    }
     return null;
   } catch {
     return null; // absent or unreadable — legacy folder, id falls back to dir name
@@ -153,7 +197,15 @@ function scanRoot(root: string, origin: UIEntry["origin"], entries: UIEntry[], s
       continue;
     }
     const dir = join(root, name);
-    let manifest: { id?: unknown; disabled?: unknown } | null = null;
+    let manifest: {
+      id?: unknown;
+      disabled?: unknown;
+      name?: unknown;
+      description?: unknown;
+      settings?: unknown;
+      requires?: unknown;
+      capabilities?: unknown;
+    } | null = null;
     try {
       manifest = readManifest(dir);
     } catch {
@@ -165,7 +217,21 @@ function scanRoot(root: string, origin: UIEntry["origin"], entries: UIEntry[], s
       warnOnce(`ext-dup:${id}`, `extension "${id}" shadowed — keeping the higher-precedence copy`);
       continue;
     }
+    const displayName = typeof manifest?.name === "string" && manifest.name.length > 0 ? manifest.name : undefined;
+    const description =
+      typeof manifest?.description === "string" && manifest.description.length > 0 ? manifest.description : undefined;
     const disabled = manifest?.disabled === true;
+    // Roadmap 5/8: carry the declared settings schema / requires / capabilities
+    // through to the manifest. Malformed shapes are dropped with one warning
+    // (never a silent no-op) — validation proper happens browser-side.
+    const settings = Array.isArray(manifest?.settings) ? manifest.settings : malformed(manifest?.settings, id, "settings");
+    const requires =
+      manifest?.requires && typeof manifest.requires === "object" && !Array.isArray(manifest.requires)
+        ? manifest.requires
+        : malformed(manifest?.requires, id, "requires");
+    const capabilities = Array.isArray(manifest?.capabilities)
+      ? manifest.capabilities
+      : malformed(manifest?.capabilities, id, "capabilities");
     const entry = disabled ? null : folderEntry(dir);
     const dom = disabled ? null : folderDomEntry(dir);
     // A paused extension needs no entry file; an enabled one without any
@@ -194,6 +260,11 @@ function scanRoot(root: string, origin: UIEntry["origin"], entries: UIEntry[], s
       domEntry,
       domMtimeMs,
       source: `webui-extensions:${dir}`,
+      name: displayName,
+      description,
+      settings,
+      requires,
+      capabilities,
       disabled: disabled || undefined,
       origin,
     });
@@ -220,3 +291,125 @@ export function discoverUserUIEntries(): UIEntry[] {
   cache = { at: now, entries };
   return entries;
 }
+
+// ---------------------------------------------------------------------------
+// Enable / pause from the webui (Settings › Extensions toggle).
+//
+// Gating stays owned by the folder: we only edit the winning source's
+// manifest.json `disabled` field. Shipped extensions are never edited in place
+// (an app update would clobber the flag) — disabling one writes a tiny
+// user-level shadow folder with the same id, which wins by precedence and
+// vanishes again when it is re-enabled.
+// ---------------------------------------------------------------------------
+
+const EXT_ID_RE = /^[A-Za-z0-9._-]+$/;
+const SOURCE_PREFIX = "webui-extensions:";
+
+/** The on-disk folder for a discovery entry, if it has one. */
+function entryDir(entry: UIEntry): string | null {
+  if (entry.source?.startsWith(SOURCE_PREFIX)) return entry.source.slice(SOURCE_PREFIX.length);
+  if (entry.entry) return dirname(entry.entry);
+  if (entry.domEntry) return dirname(entry.domEntry);
+  return null;
+}
+
+function errText(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}
+
+/** True when a folder holds only a manifest.json — our pause marker, no code. */
+function isPureShadowDir(dir: string): boolean {
+  try {
+    return readdirSync(dir).every((n) => n === "manifest.json");
+  } catch {
+    return false;
+  }
+}
+
+/** Remove a user-level shadow folder we created, or clear its flag. */
+function removeShippedShadow(shadowDir: string): void {
+  try {
+    const manifestPath = join(shadowDir, "manifest.json");
+    if (!existsSync(manifestPath)) return;
+    const others = readdirSync(shadowDir).filter((n) => n !== "manifest.json");
+    if (others.length > 0) {
+      // Not our pure marker — don't delete user files, just clear the flag.
+      const raw = JSON.parse(readFileSync(manifestPath, "utf8")) as Record<string, unknown>;
+      delete raw.disabled;
+      writeFileSync(manifestPath, `${JSON.stringify(raw, null, 2)}\n`);
+      return;
+    }
+    rmSync(shadowDir, { recursive: true, force: true });
+  } catch {
+    /* best-effort — a stale shadow is harmless (it just keeps it paused) */
+  }
+}
+
+/**
+ * Pause/resume one extension by id. Writes the higher-precedence user folder
+ * for a shipped id, or edits the winning folder's own manifest otherwise.
+ * The caller should invalidate caches / push the manifest after this.
+ */
+export function setExtensionDisabled(
+  id: string,
+  disabled: boolean,
+): { ok: true; reload?: boolean } | { ok: false; error: string } {
+  if (!EXT_ID_RE.test(id)) return { ok: false, error: "invalid extension id" };
+  invalidateExtensionCache();
+  const entry = discoverUserUIEntries().find((e) => e.id === id);
+  if (!entry) return { ok: false, error: `unknown extension: ${id}` };
+  const dir = entryDir(entry);
+  if (!dir) return { ok: false, error: "extension folder not found" };
+  const shadowDir = join(globalUserExtensionsDir(), id);
+
+  if (entry.origin === "shipped") {
+    try {
+      if (disabled) {
+        mkdirSync(shadowDir, { recursive: true });
+        writeFileSync(
+          join(shadowDir, "manifest.json"),
+          `${JSON.stringify({ id, name: entry.name, disabled: true }, null, 2)}\n`,
+        );
+      } else {
+        removeShippedShadow(shadowDir);
+      }
+    } catch (err) {
+      return { ok: false, error: errText(err) };
+    }
+    invalidateExtensionCache();
+    // Re-enabling needs a reload: the shipped browser bundle is owned by the
+    // in-repo Vite glob, which cannot re-register after being unregistered.
+    return { ok: true, reload: !disabled };
+  }
+
+  // A pure user-level shadow (manifest only, no code files) is our own pause
+  // marker for a shipped extension — removing it re-exposes the shipped copy,
+  // which again needs a reload to re-run the in-repo glob. A real user
+  // extension that happens to live at <global>/<id> is NOT a shadow and falls
+  // through to the normal manifest edit below.
+  if (!disabled && dir === shadowDir && isPureShadowDir(dir)) {
+    removeShippedShadow(dir);
+    invalidateExtensionCache();
+    return { ok: true, reload: true };
+  }
+
+  // user/project: edit the folder's own manifest.json, preserving its fields.
+  const manifestPath = join(dir, "manifest.json");
+  let raw: Record<string, unknown> = {};
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(manifestPath, "utf8"));
+    if (parsed && typeof parsed === "object") raw = parsed as Record<string, unknown>;
+  } catch {
+    raw = {};
+  }
+  raw.id ??= id;
+  if (disabled) raw.disabled = true;
+  else delete raw.disabled;
+  try {
+    writeFileSync(manifestPath, `${JSON.stringify(raw, null, 2)}\n`);
+  } catch (err) {
+    return { ok: false, error: errText(err) };
+  }
+  invalidateExtensionCache();
+  return { ok: true };
+}

package/skills/webui/SKILL.md

@@ -10,8 +10,22 @@ the `opencode` TUI, with a Bun proxy in front so the browser never holds
 service credentials. One port for UI + `/api/*`: http://localhost:4097
 (`WEBUI_PROXY_PORT`).
 
+On first boot the webui self-installs a global `opencode-webui` command and an
+OpenCode lifecycle plugin (in `~/.config/opencode/plugins/opencode-webui/`) that
+starts it as soon as you use OpenCode — so an instance is usually already
+running at that port. Check before starting another (a second run reports "already
+running" and exits 0). Manage it with `opencode-webui update|status|stop|restart|uninstall`;
+`WEBUI_NO_SETUP=1` skips setup for a one-off run.
+
+Serve/security settings (host, port, auth, allowed hosts, trust proxy, autostart)
+persist in `~/.config/opencode/webui/config.json` — environment variables
+override the file — and are edited with `opencode-webui config get|set|unset` or
+in **Settings › Access**; changes apply after a restart. Authentication is
+optional (`auth: none`) for private networks/proxies, but reachable-without-a-
+password changes need explicit confirmation.
+
 - **Repo**: https://github.com/AbdelftahZowail/opencode-webui
-- **This skill's version**: 2.4.0 (matches the `v2.4.0` git tag —
+- **This skill's version**: 3.0.1 (matches the `v3.0.1` git tag —
   the file links below are pinned to it, so they always describe the code
   this skill was generated with)
 - **A running instance exposes its version** at `GET /api/webui/config` →
@@ -24,13 +38,20 @@ fetch the exact file at the pinned tag instead of reading a local clone:
 
 | File | Purpose |
 | --- | --- |
-| https://raw.githubusercontent.com/AbdelftahZowail/opencode-webui/v2.4.0/webui-extensions/README.md | Full authoring guide — the source of truth for strata/kinds/hooks/anchors |
-| https://raw.githubusercontent.com/AbdelftahZowail/opencode-webui/v2.4.0/src/extensions/registry.tsx | The extension registry — exact register() shapes per kind |
-| https://raw.githubusercontent.com/AbdelftahZowail/opencode-webui/v2.4.0/src/extensions/hooks.ts | Shared fireHooks runner — how open hook events fire |
-| https://raw.githubusercontent.com/AbdelftahZowail/opencode-webui/v2.4.0/src/lib/domKit.ts | DOM-stratum kit (foreign/watch/styles) + the data-oc-* anchor table |
-| https://raw.githubusercontent.com/AbdelftahZowail/opencode-webui/v2.4.0/server/ext/types.ts | Proxy-stratum types — server.ts routes/middleware/onEvent/pollers shapes |
-| https://raw.githubusercontent.com/AbdelftahZowail/opencode-webui/v2.4.0/docs/extension-system-spec.md | The v2 decision record — strata, precedence, deletions, acceptance checks |
-| https://raw.githubusercontent.com/AbdelftahZowail/opencode-webui/v2.4.0/src/store.ts | The store — actions useStore exposes to extensions |
+| https://raw.githubusercontent.com/AbdelftahZowail/opencode-webui/v3.0.1/webui-extensions/README.md | Full authoring guide — the source of truth for strata/kinds/hooks/anchors |
+| https://raw.githubusercontent.com/AbdelftahZowail/opencode-webui/v3.0.1/src/extensions/registry.tsx | The extension registry — exact register() shapes per kind |
+| https://raw.githubusercontent.com/AbdelftahZowail/opencode-webui/v3.0.1/src/extensions/context.ts | Activation context — the `activate(ctx)` entry, disposal, and the full `ctx` surface |
+| https://raw.githubusercontent.com/AbdelftahZowail/opencode-webui/v3.0.1/src/extensions/slots.tsx | Slot ids (placement contract) + the Slot renderer |
+| https://raw.githubusercontent.com/AbdelftahZowail/opencode-webui/v3.0.1/src/extensions/manifest.ts | Manifest contract — settings schema + requires parsing/checks |
+| https://raw.githubusercontent.com/AbdelftahZowail/opencode-webui/v3.0.1/src/extensions/hooks.ts | Shared fireHooks runner — how open hook events fire |
+| https://raw.githubusercontent.com/AbdelftahZowail/opencode-webui/v3.0.1/src/lib/domKit.ts | DOM-stratum kit (foreign/watch/styles) + the data-oc-* anchor table |
+| https://raw.githubusercontent.com/AbdelftahZowail/opencode-webui/v3.0.1/src/lib/storeFacade.ts | Curated store surface extensions get as `store` (raw module = `advanced.store`) |
+| https://raw.githubusercontent.com/AbdelftahZowail/opencode-webui/v3.0.1/src/lib/eventBus.ts | Event bus — raw engine events + derived lifecycle, frame-batched |
+| https://raw.githubusercontent.com/AbdelftahZowail/opencode-webui/v3.0.1/src/lib/extSettings.ts | Per-extension declared settings — schema, resolve, persist, subscribe |
+| https://raw.githubusercontent.com/AbdelftahZowail/opencode-webui/v3.0.1/src/lib/extBus.ts | Extension-to-extension peer bus (publish/subscribe) |
+| https://raw.githubusercontent.com/AbdelftahZowail/opencode-webui/v3.0.1/server/ext/types.ts | Proxy-stratum types — server.ts routes/middleware/onEvent/pollers shapes |
+| https://raw.githubusercontent.com/AbdelftahZowail/opencode-webui/v3.0.1/docs/extension-system-spec.md | The v2 decision record — strata, precedence, deletions, acceptance checks |
+| https://raw.githubusercontent.com/AbdelftahZowail/opencode-webui/v3.0.1/src/store.ts | The raw store module (reachable as `advanced.store`; prefer the facade) |
 
 ## Environment
 
@@ -39,6 +60,8 @@ fetch the exact file at the pinned tag instead of reading a local clone:
 | `WEBUI_PASSWORD` | generated on first boot, printed once | Shared login passphrase. |
 | `WEBUI_HOST` | `127.0.0.1` | Bind address — a wildcard is refused without a password. |
 | `WEBUI_PROXY_PORT` | `4097` | Port for the UI and `/api/*`. |
+| `WEBUI_NO_SETUP` | unset | `1` — skip first-run setup (global command + lifecycle plugin) for this run. |
+| `WEBUI_NO_PLUGIN` | unset | `1` — install the global command but not the OpenCode lifecycle plugin. |
 | `WEBUI_EXTENSION_DIR` | the global + project dirs | Replace both with ONE directory (the sandbox does this to keep WIP isolated). |
 | `WEBUI_ENGINE_URL` | `service.json` discovery | Aim the proxy at a chosen engine — skips `Service.ensure()`, so a stale pid can never spawn a rogue serve. Explicit env wins. |
 | `WEBUI_ENGINE_PASSWORD` | `service.json` password | Engine password for the override above (no file fallback when the URL is overridden — a chosen engine has its own credential). |
@@ -76,8 +99,9 @@ dir, never reuse a port.
 ## The model in one minute
 
 One extension = **one folder**: `manifest.json` (id, version, description,
-`disabled`?) + `index.tsx` (browser stratum) + `dom.ts` (DOM stratum) +
-`server.ts` (proxy stratum) + `engine/` (opencode plugin payload).
+`disabled`?, `settings`?, `requires`?) + `index.tsx` (browser stratum) +
+`dom.ts` (DOM stratum) + `server.ts` (proxy stratum) + `engine/` (opencode
+plugin payload).
 Presence = installed; `disabled: true` = paused; delete the folder =
 uninstalled. Precedence, highest wins: `~/.config/opencode/webui-extensions/`
 (user) → `<project>/.opencode/webui-extensions/` (project) → shipped
@@ -111,11 +135,30 @@ register({
 });
 ```
 
+### Activation context (browser stratum)
+
+Prefer `export function activate(ctx)` over module-scope `register()` — the
+context owns lifecycle + disposal. On it: `ctx.register(entry)` (the five
+kinds); `ctx.poll({ name, minInterval, run })` and `ctx.after(ms, fn)` (the
+shared tier-aware scheduler, auto-stopped); `ctx.on(name, fn)` (event bus —
+a raw engine type or a derived name: `run.started`, `run.ended`,
+`tool.called`, `tool.completed`, `message.appended`; `"*"` = all);
+`ctx.subscribe(selector, fn)` (derived store read); `ctx.store` (curated
+store facade — selectors + actions); `ctx.settings` (declared settings);
+`ctx.collections` / `ctx.bus` (peer composition); `ctx.onDispose(fn)` or
+returning a teardown. Everything a context creates is disposed on hot-swap,
+`disabled`, and delete. Module-scope `register()` still works but is being
+deprecated.
+
+Manifest `settings` declares options core renders in Settings › Extensions;
+`requires` (`api`/`targets`/`slots`/`services`) is checked on every
+sync and an unmet reference is a visible warning, not a silent blank spot.
+
 ## Five kinds, one job each (the contract)
 
 | Kind | Job | Staleness |
 | --- | --- | --- |
-| `wrap` | Flow-through tweak of any registered target: `render(props, next)` — transform props/output, delegate to live core by default | **Stale-proof by construction.** Core updates always render *through* it. The default path for edits. |
+| `wrap` | Flow-through tweak of any registered target: `render(props, next)` — transform output, and/or call `next(overrides)` to merge changed/extra props into the rest of the chain, delegating to live core by default | **Stale-proof by construction.** Core updates always render *through* it. The default path for edits. |
 | `replace` | Take ownership of one registered target: `render(props, core)` wins outright at its priority; return `null` to fall through to the next candidate / core | **Frozen snapshot.** You opt out of core updates for that target — the marked escape hatch. Still receives `core` so you *can* compose. |
 | `contribute` | Add an item to a named collection (`collection` + `item`, `order` sorts, lower first) | Data, not code — core owns the list, you own your row. |
 | `hook` | Interception at instrumented boundaries: `{ event, handler(ctx, next) }` — `event` is an open string | New seams are new event names, never a registry change. |
@@ -124,7 +167,10 @@ register({
 Contribute collections (registry-owned lists — data, not new kinds):
 `palette`, `slash` (UI-only; engine commands win name clashes),
 `pages` (routed at `/ext/{id}`), `settings`,
-`contextMenu.message` / `contextMenu.session` / `contextMenu.file`.
+`contextMenu.message` / `contextMenu.session` / `contextMenu.file`, and
+`slot:<id>` (named placement points — `conversation.header.actions`,
+`conversation.empty`, `composer.above`, `composer.actions`,
+`sidebar.header.actions`).
 
 ### Hook catalog
 
@@ -164,6 +210,7 @@ own the fragility").
 | `data-oc-queue-strip` | QueueStrip (steer/queue rows) |
 | `data-oc-subagent-strip` | SubagentStrip |
 | `data-oc-runs-panel` | RunsPanel |
+| `data-oc-slot` | Slot wrapper (`slot:<id>` — one per known slot id) |
 
 ## Sandbox (iterate without touching the user's webui)