Single target plugin entrypoints (#19467)

Author: kommander

.opencode/plugins/tui-smoke.tsx

@@ -1,7 +1,14 @@
 /** @jsxImportSource @opentui/solid */
 import { useKeyboard, useTerminalDimensions } from "@opentui/solid"
 import { RGBA, VignetteEffect } from "@opentui/core"
-import type { TuiKeybindSet, TuiPluginApi, TuiPluginMeta, TuiSlotPlugin } from "@opencode-ai/plugin/tui"
+import type {
+  TuiKeybindSet,
+  TuiPlugin,
+  TuiPluginApi,
+  TuiPluginMeta,
+  TuiPluginModule,
+  TuiSlotPlugin,
+} from "@opencode-ai/plugin/tui"
 
 const tabs = ["overview", "counter", "help"]
 const bind = {
@@ -813,7 +820,7 @@ const reg = (api: TuiPluginApi, input: Cfg, keys: Keys) => {
   ])
 }
 
-const tui = async (api: TuiPluginApi, options: Record<string, unknown> | null, meta: TuiPluginMeta) => {
+const tui: TuiPlugin = async (api, options, meta) => {
   if (options?.enabled === false) return
 
   await api.theme.install("./smoke-theme.json")
@@ -846,7 +853,9 @@ const tui = async (api: TuiPluginApi, options: Record<string, unknown> | null, m
   }
 }
 
-export default {
+const plugin: TuiPluginModule & { id: string } = {
   id: "tui-smoke",
   tui,
 }
+
+export default plugin

packages/opencode/specs/tui-plugins.md

@@ -8,6 +8,8 @@ Technical reference for the current TUI plugin system.
 - Author package entrypoint is `@opencode-ai/plugin/tui`.
 - Internal plugins load inside the CLI app the same way external TUI plugins do.
 - Package plugins can be installed from CLI or TUI.
+- v1 plugin modules are target-exclusive: a module can export `server` or `tui`, never both.
+- Server runtime keeps v0 legacy fallback (function exports / enumerated exports) after v1 parsing.
 
 ## TUI config
 
@@ -27,6 +29,7 @@ Example:
 - `plugin` entries can be either a string spec or `[spec, options]`.
 - Plugin specs can be npm specs, `file://` URLs, relative paths, or absolute paths.
 - Relative path specs are resolved relative to the config file that declared them.
+- A file module listed in `tui.json` must be a TUI module (`default export { id?, tui }`) and must not export `server`.
 - Duplicate npm plugins are deduped by package name; higher-precedence config wins.
 - Duplicate file plugins are deduped by exact resolved file spec. This happens while merging config, before plugin modules are loaded.
 - `plugin_enabled` is keyed by plugin id, not by plugin spec.
@@ -46,7 +49,7 @@ Minimal module shape:
 
 ```tsx
 /** @jsxImportSource @opentui/solid */
-import type { TuiPlugin } from "@opencode-ai/plugin/tui"
+import type { TuiPlugin, TuiPluginModule } from "@opencode-ai/plugin/tui"
 
 const tui: TuiPlugin = async (api, options, meta) => {
   api.command.register(() => [
@@ -69,16 +72,20 @@ const tui: TuiPlugin = async (api, options, meta) => {
   ])
 }
 
-export default {
+const plugin: TuiPluginModule & { id: string } = {
   id: "acme.demo",
   tui,
 }
+
+export default plugin
 ```
 
 - Loader only reads the module default export object. Named exports are ignored.
-- TUI shape is `default export { id?, tui }`.
+- TUI shape is `default export { id?, tui }`; including `server` is rejected.
+- A single module cannot export both `server` and `tui`.
 - `tui` signature is `(api, options, meta) => Promise<void>`.
 - If package `exports` contains `./tui`, the loader resolves that entrypoint. Otherwise it uses the resolved package target.
+- If a package supports both server and TUI, use separate files and package `exports` (`./server` and `./tui`) so each target resolves to a target-only module.
 - File/path plugins must export a non-empty `id`.
 - npm plugins may omit `id`; package `name` is used.
 - Runtime identity is the resolved plugin id. Later plugins with the same id are rejected, including collisions with internal plugin ids.
@@ -137,6 +144,7 @@ npm plugins can declare a version compatibility range in `package.json` using th
 - With `--force`, replacement matches by package name. If the existing row is `[spec, options]`, those tuple options are kept.
 - Tuple targets in `oc-plugin` provide default options written into config.
 - A package can target `server`, `tui`, or both.
+- If a package targets both, each target must still resolve to a separate target-only module. Do not export `{ server, tui }` from one module.
 - There is no uninstall, list, or update CLI command for external plugins.
 - Local file plugins are configured directly in `tui.json`.
 

packages/opencode/src/cli/cmd/tui/feature-plugins/home/tips.tsx

@@ -1,4 +1,4 @@
-import type { TuiPlugin } from "@opencode-ai/plugin/tui"
+import type { TuiPlugin, TuiPluginModule } from "@opencode-ai/plugin/tui"
 import { createMemo, Show } from "solid-js"
 import { Tips } from "./tips-view"
 
@@ -42,7 +42,9 @@ const tui: TuiPlugin = async (api) => {
   })
 }
 
-export default {
+const plugin: TuiPluginModule & { id: string } = {
   id,
   tui,
 }
+
+export default plugin

packages/opencode/src/cli/cmd/tui/feature-plugins/sidebar/context.tsx

@@ -1,5 +1,5 @@
 import type { AssistantMessage } from "@opencode-ai/sdk/v2"
-import type { TuiPlugin, TuiPluginApi } from "@opencode-ai/plugin/tui"
+import type { TuiPlugin, TuiPluginApi, TuiPluginModule } from "@opencode-ai/plugin/tui"
 import { createMemo } from "solid-js"
 
 const id = "internal:sidebar-context"
@@ -55,7 +55,9 @@ const tui: TuiPlugin = async (api) => {
   })
 }
 
-export default {
+const plugin: TuiPluginModule & { id: string } = {
   id,
   tui,
 }
+
+export default plugin

packages/opencode/src/cli/cmd/tui/feature-plugins/sidebar/files.tsx

@@ -1,4 +1,4 @@
-import type { TuiPlugin, TuiPluginApi } from "@opencode-ai/plugin/tui"
+import type { TuiPlugin, TuiPluginApi, TuiPluginModule } from "@opencode-ai/plugin/tui"
 import { createMemo, For, Show, createSignal } from "solid-js"
 
 const id = "internal:sidebar-files"
@@ -54,7 +54,9 @@ const tui: TuiPlugin = async (api) => {
   })
 }
 
-export default {
+const plugin: TuiPluginModule & { id: string } = {
   id,
   tui,
 }
+
+export default plugin

packages/opencode/src/cli/cmd/tui/feature-plugins/sidebar/footer.tsx

@@ -1,4 +1,4 @@
-import type { TuiPlugin, TuiPluginApi } from "@opencode-ai/plugin/tui"
+import type { TuiPlugin, TuiPluginApi, TuiPluginModule } from "@opencode-ai/plugin/tui"
 import { createMemo, Show } from "solid-js"
 import { Global } from "@/global"
 
@@ -85,7 +85,9 @@ const tui: TuiPlugin = async (api) => {
   })
 }
 
-export default {
+const plugin: TuiPluginModule & { id: string } = {
   id,
   tui,
 }
+
+export default plugin

packages/opencode/src/cli/cmd/tui/feature-plugins/sidebar/lsp.tsx

@@ -1,4 +1,4 @@
-import type { TuiPlugin, TuiPluginApi } from "@opencode-ai/plugin/tui"
+import type { TuiPlugin, TuiPluginApi, TuiPluginModule } from "@opencode-ai/plugin/tui"
 import { createMemo, For, Show, createSignal } from "solid-js"
 
 const id = "internal:sidebar-lsp"
@@ -58,7 +58,9 @@ const tui: TuiPlugin = async (api) => {
   })
 }
 
-export default {
+const plugin: TuiPluginModule & { id: string } = {
   id,
   tui,
 }
+
+export default plugin

packages/opencode/src/cli/cmd/tui/feature-plugins/sidebar/mcp.tsx

@@ -1,4 +1,4 @@
-import type { TuiPlugin, TuiPluginApi } from "@opencode-ai/plugin/tui"
+import type { TuiPlugin, TuiPluginApi, TuiPluginModule } from "@opencode-ai/plugin/tui"
 import { createMemo, For, Match, Show, Switch, createSignal } from "solid-js"
 
 const id = "internal:sidebar-mcp"
@@ -88,7 +88,9 @@ const tui: TuiPlugin = async (api) => {
   })
 }
 
-export default {
+const plugin: TuiPluginModule & { id: string } = {
   id,
   tui,
 }
+
+export default plugin

packages/opencode/src/cli/cmd/tui/feature-plugins/sidebar/todo.tsx

@@ -1,4 +1,4 @@
-import type { TuiPlugin, TuiPluginApi } from "@opencode-ai/plugin/tui"
+import type { TuiPlugin, TuiPluginApi, TuiPluginModule } from "@opencode-ai/plugin/tui"
 import { createMemo, For, Show, createSignal } from "solid-js"
 import { TodoItem } from "../../component/todo-item"
 
@@ -40,7 +40,9 @@ const tui: TuiPlugin = async (api) => {
   })
 }
 
-export default {
+const plugin: TuiPluginModule & { id: string } = {
   id,
   tui,
 }
+
+export default plugin

packages/opencode/src/cli/cmd/tui/feature-plugins/system/plugins.tsx

@@ -1,9 +1,9 @@
 import { Keybind } from "@/util/keybind"
-import type { TuiPlugin, TuiPluginApi, TuiPluginStatus } from "@opencode-ai/plugin/tui"
+import type { TuiPlugin, TuiPluginApi, TuiPluginModule, TuiPluginStatus } from "@opencode-ai/plugin/tui"
 import { useKeyboard, useTerminalDimensions } from "@opentui/solid"
 import { fileURLToPath } from "url"
 import { DialogSelect, type DialogSelectOption } from "@tui/ui/dialog-select"
-import { createEffect, createMemo, createSignal } from "solid-js"
+import { Show, createEffect, createMemo, createSignal } from "solid-js"
 
 const id = "internal:plugin-manager"
 const key = Keybind.parse("space").at(0)
@@ -53,11 +53,17 @@ function Install(props: { api: TuiPluginApi }) {
     <props.api.ui.DialogPrompt
       title="Install plugin"
       placeholder="npm package name"
+      busy={busy()}
+      busyText="Installing plugin..."
       description={() => (
         <box flexDirection="row" gap={1}>
           <text fg={props.api.theme.current.textMuted}>scope:</text>
-          <text fg={props.api.theme.current.text}>{global() ? "global" : "local"}</text>
-          <text fg={props.api.theme.current.textMuted}>({Keybind.toString(tab)} toggle)</text>
+          <text fg={busy() ? props.api.theme.current.textMuted : props.api.theme.current.text}>
+            {global() ? "global" : "local"}
+          </text>
+          <Show when={!busy()}>
+            <text fg={props.api.theme.current.textMuted}>({Keybind.toString(tab)} toggle)</text>
+          </Show>
         </box>
       )}
       onConfirm={(raw) => {
@@ -256,7 +262,9 @@ const tui: TuiPlugin = async (api) => {
   ])
 }
 
-export default {
+const plugin: TuiPluginModule & { id: string } = {
   id,
   tui,
 }
+
+export default plugin