@hachej/boring-workspace 0.1.17 → 0.1.18

package/docs/bridge.md

@@ -1,135 +0,0 @@
-> boring-ui agents use exec_ui to open panels and interact with the workspace. Ask boring-ui to wire up a new surface.
-
-# UI Bridge
-
-The UI bridge is the typed pubsub channel between the agent backend and the workspace frontend. The agent calls `exec_ui` (a tool) to post commands; the frontend dispatches them against the live workspace runtime.
-
-## Table of Contents
-
-- [Opening a panel from the agent](#opening-a-panel-from-the-agent)
-- [openSurface vs openPanel](#opensurface-vs-openpanel)
-- [Reading current UI state](#reading-current-ui-state)
-- [Surface resolvers](#surface-resolvers)
-- [Posting from server code](#posting-from-server-code)
-- [Frontend event bus](#frontend-event-bus)
-
----
-
-## Opening a panel from the agent
-
-Use `exec_ui` with `kind: "openSurface"`:
-
-```json
-{
-  "kind": "openSurface",
-  "params": {
-    "kind": "my-plugin.open",
-    "target": "item-123",
-    "meta": { "title": "My Item" }
-  }
-}
-```
-
-The workspace routes this to the plugin's `surface-resolver` output, which maps the `kind` to a concrete panel open call.
-
----
-
-## openSurface vs openPanel
-
-| method | use when |
-|---|---|
-| `openSurface` | you want plugin resolver selection — preferred for domain targets |
-| `openPanel` | you intentionally name the concrete panel id |
-
-**Prefer `openSurface`.** It keeps the agent decoupled from panel ids and lets the plugin control routing.
-
-Open a file in the editor (built-in surface):
-
-```json
-{
-  "kind": "openSurface",
-  "params": {
-    "kind": "workspace.open.path",
-    "target": "src/index.ts"
-  }
-}
-```
-
----
-
-## Reading current UI state
-
-Use `get_ui_state` before `openPanel` to discover which panel components are registered, or to check what the user is currently viewing:
-
-```json
-// tool call: get_ui_state (no params)
-// returns:
-{
-  "workbenchOpen": true,
-  "drawerOpen": false,
-  "openTabs": [{ "id": "...", "title": "...", "params": {} }],
-  "activeTab": "tab-id-or-null",
-  "activeFile": "src/index.ts-or-null",
-  "availablePanels": ["code-editor", "chart-canvas", "..."]
-}
-```
-
-`availablePanels` lists every component id registered by the host — use these with `exec_ui openPanel`.
-
----
-
-## Surface resolvers
-
-Register a surface resolver in your plugin to map `SurfaceOpenRequest` kinds to panel opens:
-
-```ts
-import { defineFrontPlugin, type SurfacePanelResolution } from '@boring/workspace'
-
-defineFrontPlugin({
-  outputs: [
-    {
-      type: 'surface-resolver',
-      resolve(req): SurfacePanelResolution | null {
-        if (req.kind === 'my-plugin.open') {
-          return {
-            panelId: 'my-panel',
-            params: { id: req.target },
-          }
-        }
-        return null
-      },
-    },
-  ],
-})
-```
-
----
-
-## Posting from server code
-
-From a Fastify route or server plugin:
-
-```ts
-import { postUiCommand } from '@boring/workspace/server'
-
-await postUiCommand(workspaceId, {
-  kind: 'openSurface',
-  params: { kind: 'my-plugin.open', target: 'item-123' },
-})
-```
-
----
-
-## Frontend event bus
-
-Subscribe to workspace events on the frontend:
-
-```ts
-import { events, workspaceEvents } from '@boring/workspace'
-
-events.on(workspaceEvents.panelOpened, (panel) => {
-  console.log('panel opened', panel.id)
-})
-```
-
-See [plugins.md](./plugins.md) to register a surface resolver in your plugin.

package/docs/panels.md

@@ -1,102 +0,0 @@
-> boring-ui can create panel components. Ask it to build one for your domain.
-
-# Panels
-
-Panels are React components rendered inside the workspace dockview layout. They receive `PaneProps<T>` and can be opened programmatically by the agent or user.
-
-## Table of Contents
-
-- [Defining a panel](#defining-a-panel)
-- [Panel component API](#panel-component-api)
-- [Placement](#placement)
-- [Auto-lazy loading](#auto-lazy-loading)
-- [Opening panels](#opening-panels)
-
----
-
-## Defining a panel
-
-```ts
-import { definePanel } from '@boring/workspace'
-
-export const myPanel = definePanel({
-  id: 'my-panel',
-  title: 'My Panel',
-  placement: 'center',
-  // Zero-arg factory → auto-detected as lazy (code-split)
-  component: () => import('./MyPane').then(m => ({ default: m.MyPane })),
-})
-```
-
----
-
-## Panel component API
-
-Panel components receive `PaneProps<T>`:
-
-```ts
-import type { PaneProps } from '@boring/workspace'
-
-interface Params { id?: string; query?: string }
-
-export function MyPane({ params, api, containerApi }: PaneProps<Params>) {
-  // params       — data passed when the panel is opened
-  // api          — DockviewPanelApi (close, setTitle, onDidParametersChange, …)
-  // containerApi — DockviewApi (addPanel, fromJSON, …)
-}
-```
-
-React to parameter changes (agent re-opens with new params):
-
-```ts
-useEffect(() => {
-  const disposable = api.onDidParametersChange(() => {
-    // params updated
-  })
-  return () => disposable.dispose()
-}, [api])
-```
-
----
-
-## Placement
-
-| value | where |
-|---|---|
-| `center` | main editor area |
-| `right` | right sidebar |
-| `bottom` | bottom panel |
-
----
-
-## Auto-lazy loading
-
-**Do not set `lazy: true`.** The registry auto-detects it:
-
-- Zero-arg function `() => import(...)` → lazy (code-split, loaded on first open)
-- Component `(props) => JSX` → eager (loaded at startup)
-
----
-
-## Opening panels
-
-From the agent via exec_ui (see [bridge.md](./bridge.md)):
-
-```json
-{
-  "kind": "openSurface",
-  "params": { "kind": "my-plugin.open", "target": "item-123" }
-}
-```
-
-From React code directly:
-
-```ts
-containerApi.addPanel({
-  id: 'my-panel',
-  component: 'my-panel',
-  params: { id: 'item-123' },
-})
-```
-
-See [plugins.md](./plugins.md) for the full plugin API.

package/docs/plugins.md

@@ -1,158 +0,0 @@
-> boring-ui can create plugins. Ask it to build one for your use case.
-
-# Plugins
-
-Plugins are the primary extension point. A plugin contributes panels, commands, catalogs, left-tabs, and surface resolvers to the workspace shell.
-
-**Key capabilities:**
-- **Panels** — center/right/bottom panes opened programmatically by the agent or user
-- **Commands** — entries in the command palette (`cmd+k`)
-- **Left tabs** — persistent tabs in the left sidebar
-- **Catalogs** — data explorer tabs with search + row selection
-- **Surface resolvers** — map agent-emitted `openSurface` requests to concrete panel opens
-- **Bindings / providers** — React components mounted in the provider tree
-
-## Table of Contents
-
-- [Minimal plugin](#minimal-plugin)
-- [Output types](#output-types)
-- [System prompt](#system-prompt)
-- [Composing plugins](#composing-plugins)
-- [Server plugins](#server-plugins)
-- [Registering with the shell](#registering-with-the-shell)
-- [Plugin folder layout](#plugin-folder-layout)
-- [Invariants](#invariants)
-
----
-
-## Minimal plugin
-
-```ts
-import { defineFrontPlugin, definePanel } from '@boring/workspace'
-
-export const myPlugin = defineFrontPlugin({
-  id: 'my-plugin',
-  label: 'My Plugin',
-  systemPrompt: "You can open the widget panel with the 'open-panel' tool.",
-  outputs: [
-    {
-      type: 'panel',
-      panel: definePanel({
-        id: 'my-widget',
-        title: 'Widget',
-        placement: 'center',
-        component: () => import('./WidgetPane').then(m => ({ default: m.WidgetPane })),
-      }),
-    },
-  ],
-})
-```
-
----
-
-## Output types
-
-| type | contributes |
-|---|---|
-| `panel` | a center/right/bottom pane opened programmatically |
-| `left-tab` | a persistent tab in the left sidebar |
-| `command` | an entry in the command palette |
-| `catalog` | a data explorer tab with search + row selection |
-| `surface-resolver` | maps a `SurfaceOpenRequest` kind → panel id |
-| `binding` | a React component mounted in the provider tree |
-| `provider` | same as binding but receives `apiBaseUrl`, `authHeaders`, etc. |
-
----
-
-## System prompt
-
-The `systemPrompt` field on a plugin is injected into the agent's context. Use it to teach the agent what panels exist and when to open them.
-
-```ts
-defineFrontPlugin({
-  id: 'contract-review',
-  systemPrompt: `
-    You can open the contract review panel when the user asks to review a contract.
-    Use exec_ui with kind "openSurface" and kind "contract-review.open".
-  `,
-  ...
-})
-```
-
-All plugin `systemPrompt` strings are concatenated and passed as `systemPromptAppend` to the agent harness.
-
----
-
-## Composing plugins
-
-```ts
-import { composePlugins } from '@boring/workspace'
-
-export const myPlugin = composePlugins({
-  id: 'my-plugin',
-  plugins: [panelsPlugin, catalogPlugin, surfacePlugin],
-})
-```
-
-`composePlugins` flattens child panels, commands, catalogs, bindings, and outputs into one `WorkspaceFrontPlugin`. Child ownership adopts to the parent plugin id by default.
-
----
-
-## Server plugins
-
-Server plugins contribute agent tools, routes, and pi package declarations:
-
-```ts
-import { defineServerPlugin } from '@boring/workspace/server'
-
-export const myServerPlugin = defineServerPlugin({
-  id: 'my-plugin',
-  tools: [myAgentTool],
-  promptText: 'You have access to the my_tool tool.',
-})
-```
-
-Compose server plugins with `composeServerPlugins()`.
-
----
-
-## Registering with the shell
-
-```tsx
-import { WorkspaceAgentFront } from '@boring/workspace'
-
-<WorkspaceAgentFront plugins={[myPlugin]} />
-```
-
----
-
-## Plugin folder layout
-
-```
-src/plugins/myPlugin/
-  front/
-    index.tsx          ← defineFrontPlugin(), public front exports
-    panels.tsx         ← panel definitions
-    surfaceResolver.ts ← openSurface kind → panel resolution
-  server/
-    index.ts           ← defineServerPlugin(), public server exports
-    tools.ts           ← agent tools
-  shared/
-    constants.ts       ← plugin id, surface kinds
-    types.ts           ← platform-neutral shared types
-```
-
-Use only the files the plugin needs.
-
----
-
-## Invariants
-
-```bash
-pnpm --filter @boring/workspace run lint:plugin-invariants
-```
-
-Rejects cross-layer imports, legacy file names, and plugin-domain imports from workspace chrome.
-
-See [panels.md](./panels.md) for panel component API.
-See [bridge.md](./bridge.md) for how to open panels from the agent.