@hachej/boring-workspace 0.1.0

package/docs/INTERFACES.md

@@ -0,0 +1,58 @@
+# Workspace Interfaces
+
+Last updated: 2026-05-02
+
+`@boring/workspace` is a workspace UI and bridge package. The app shell owns
+auth, routing, application persistence, and the concrete chat component.
+Workspace owns layout runtime, layout preferences, plugin registries, bridge
+commands, and default workspace plugins.
+
+## Package Boundaries
+
+- `src/front/` hosts React providers, layouts, Dockview chrome, registries,
+  bridge clients, and generic UI.
+- `src/plugins/` hosts plugin-owned domain behavior. Plugin code is split by
+  layer: `front/`, `server/`, and `shared/`.
+- `src/server/` hosts workspace UI bridge routes, UI tools, and server plugin
+  bootstrap helpers.
+- `src/shared/` hosts browser-safe contracts only. No `node:*`, no `Buffer`,
+  and no agent package imports.
+- `src/app/` hosts front/server composition helpers such as
+  `WorkspaceAgentFront` and `createWorkspaceAgentServer`, where workspace app
+  code may compose with documented `@boring/agent/server` APIs.
+
+## Core Contracts
+
+- Plugin outputs: `src/shared/plugins/types.ts`
+  - `panel`, `left-tab`, `command`, `catalog`, `binding`, `provider`,
+    `surface-resolver`, and `agent-tool`.
+- Surface opening: `src/shared/types/surface.ts`
+  - `SurfaceOpenRequest { kind, target, meta }` is resolved by plugin
+    `surface-resolver` outputs into panel openings.
+- UI bridge: `src/shared/ui-bridge.ts`
+  - Agents and servers post `UiCommand` values. The front-end dispatches them
+    against the workspace runtime.
+- Filesystem data: `src/plugins/filesystemPlugin/front/data`
+  - Filesystem client, hooks, event stream, and cache invalidation are plugin
+    owned.
+- Data catalog: `src/plugins/dataCatalogPlugin/front` and
+  `src/plugins/dataCatalogPlugin/server`
+  - Catalog rows are opened through `openSurface`; row-to-panel mapping belongs
+    to the plugin resolver.
+- Server plugins: `src/server/plugins`
+  - `defineServerPlugin()` validates tools, routes, provisioning, and native Pi
+    package declarations.
+  - `composeServerPlugins()` combines smaller server plugin fragments.
+  - `piPackages` are passed to `@boring/agent` as in-memory Pi settings, so
+    workspace adapters can depend on native Pi packages without requiring
+    Boring-specific exports from those packages.
+
+## Ownership Rules
+
+- Workspace chrome must not hardcode plugin panel ids or plugin domain rules.
+- Plugin data APIs stay under the owning plugin; there is no `front/data`
+  compatibility layer.
+- Use `openSurface` for domain targets that need resolver selection.
+- Use `openPanel` only when the caller intentionally names the concrete panel.
+- Front/shared workspace code does not value-import `@boring/agent`; app/server
+  composition may import documented agent server APIs.

package/docs/PLUGIN_STRUCTURE.md

@@ -0,0 +1,162 @@
+# Workspace Plugin Structure
+
+Last updated: 2026-05-01
+
+Workspace plugins use a small, predictable folder shape. The goal is
+ownership clarity, not ceremony: plugin domain behavior stays in the plugin,
+and workspace core stays a generic host.
+
+See `INTERFACES.md` for the package-level contracts these plugins contribute
+to.
+
+## Standard Layout
+
+Start from `packages/workspace/templates/plugin/` when creating a new plugin,
+then delete the files the plugin does not need.
+
+```txt
+<plugin>/
+  front/
+    index.tsx            # front plugin factory and public front exports
+    panels.tsx           # panel definitions
+    catalogs.ts          # catalog outputs/config helpers
+    surfaceResolver.ts   # openSurface target -> panel resolution
+    bindings.tsx         # React side-effect bindings, if needed
+    data/                # plugin-owned client data API/hooks/cache
+  server/
+    index.ts             # server plugin factory and public server exports
+    tools.ts             # agent tools, if needed
+    routes.ts            # server routes, if needed
+  shared/
+    constants.ts         # plugin id, catalog ids, surface kinds
+    types.ts             # platform-neutral shared types, if needed
+```
+
+Use only the files a plugin actually needs. Large component families may live
+in subfolders such as `file-tree/`, `code-editor/`, or `empty-file-panel/`.
+
+## Ownership Rules
+
+- `front/index.tsx` composes front outputs; large behavior belongs in focused files.
+- `server/index.ts` composes server outputs with `defineServerPlugin()`.
+- Shared files must stay platform-neutral. Do not import plugin `front/` or
+  `server/` code from `shared/`.
+- Domain search belongs in `front/catalogs.ts`.
+- Domain open behavior belongs in `front/surfaceResolver.ts`.
+- Domain event names live in `shared/events.ts` when both layers need the
+  contract; event names must be keyed by plugin id.
+- Plugin data clients/hooks live in `front/data/`, not package `front/data`.
+- Server prompts/tools/routes/provisioning live under `server/`, not mixed
+  with client code.
+- Workspace core may host registries, providers, event transport, and bridge
+  dispatch only. It must not hardcode plugin panel ids or plugin domain rules.
+- Catalog selection and plugin-owned routing should prefer `openSurface`.
+  `openPanel` remains available for explicit app-level panel opens.
+- Executable agent tools should be server plugin contributions. The legacy
+  front `agentTools` field remains for migration only.
+
+## Composed Plugins
+
+Use `composePlugins()` when a front plugin is easier to build from smaller
+front fragments. The composed plugin flattens child panels, commands,
+catalogs, bindings, and outputs into one normal `WorkspaceFrontPlugin`.
+
+Default behavior adopts child ownership to the parent plugin id. Use
+`adoptOutputs: false` only when registry ownership must stay attached to the
+child fragment for diagnostics or selective unregister behavior.
+
+```ts
+const macroPlugin = composePlugins({
+  id: "boring-macro",
+  label: "Macro",
+  plugins: [macroPanelsPlugin, macroSurfacesPlugin, macroSeriesExplorerPlugin],
+})
+```
+
+Use `composeServerPlugins()` for the matching server side. It concatenates
+child tools, prompt text, pi package declarations, provisioning, and routes
+into one normal `WorkspaceServerPlugin`.
+
+```ts
+const macroServerPlugin = composeServerPlugins({
+  id: "boring-macro",
+  label: "Macro",
+  plugins: [macroToolsPlugin, macroRoutesPlugin],
+})
+```
+
+## Pi Package Adapters
+
+Treat pi packages as implementation dependencies. The app-facing contract is a
+workspace adapter plugin that wraps the pi package and optionally adds front
+integration.
+
+Do not require pi packages to export Boring-specific adapters. The pi ecosystem
+already has its own shape, such as `package.json` `pi.extensions` entries and
+extension functions that call `pi.registerCommand(...)`. Workspace adapters
+should adapt to that shape.
+
+Declare native pi package dependencies on the server plugin:
+
+```ts
+defineServerPlugin({
+  id: "markdown-preview",
+  piPackages: ["npm:pi-markdown-preview@0.9.7"],
+})
+```
+
+Workspace passes these declarations to `@boring/agent` as in-memory Pi
+settings. This enables Pi's native package loader without mutating
+`.pi/settings.json`.
+
+```txt
+src/plugins/markdownPreview/
+  shared/
+    constants.ts        # workspace ids, surface kinds, command names
+  server/
+    index.ts            # defineServerPlugin(), pi package dependency wrapper
+    routes.ts           # optional workspace-native render/preview routes
+  front/
+    index.tsx           # defineFrontPlugin()
+    panels.tsx          # workspace-native preview panel
+    surfaceResolver.ts  # markdown-preview.open -> panel resolution
+```
+
+For example, a wrapper around `pi-markdown-preview` can depend on that package,
+read or invoke its pi extension behavior on the server side, and expose a
+workspace-native `markdown-preview.open` surface on the front side. The agent
+prompt should teach the model to use workspace `openSurface` when a Boring app
+is present, even if the underlying pi package also provides terminal/browser
+slash commands.
+
+
+## Current Plugins
+
+- `packages/workspace/src/plugins/filesystemPlugin`
+- `packages/workspace/src/plugins/dataCatalogPlugin`
+- `apps/boring-macro-v2/src/plugins/macro`
+- `apps/workspace-playground/src/plugins/playgroundDataCatalog`
+
+## Invariants
+
+Run:
+
+```sh
+pnpm --filter @boring/workspace run lint:plugin-invariants
+```
+
+The scan rejects:
+
+- `filePatterns`, `fileFallback`, `PanelRegistry.resolve`, and file-handler
+  routing metadata in source.
+- `front/data` imports or path references in source.
+- `@boring/agent` imports from `workspace/src/shared/plugins`.
+- `front`/`server` imports from production `workspace/src/shared/plugins`.
+- Production plugin `front/`, `server/`, and `shared/` layers importing across
+  the wrong layer boundary.
+- TypeScript source files directly under a plugin root instead of
+  `front/`, `server/`, or `shared/`.
+- Plugin-domain imports from production `workspace/src/front/chrome`, `events`,
+  and `hooks`.
+- Legacy plugin file names such as `catalog.ts`, `surfaceTargets.ts`,
+  root-level `client.ts`, or root-level `server.ts`.

package/docs/README.md

@@ -0,0 +1,19 @@
+# Workspace Docs
+
+Current package docs live here. Active ownership plans stay in `docs/plans/`.
+Older implementation plans live in `docs/plans/archive/`.
+
+## Current References
+
+- `INTERFACES.md` - package boundaries and public abstractions.
+- `PLUGIN_STRUCTURE.md` - plugin folder shape and invariant scans.
+- `plans/PLUGIN_OUTPUTS_ISOLATION_PLAN.md` - latest plugin ownership plan.
+- `plans/UI_BRIDGE_OWNERSHIP_REFACTOR.md` - UI bridge ownership decision.
+- `plans/archive/` - superseded implementation plans.
+
+## Rules
+
+- Keep root package markdown to `README.md` and `CHANGELOG.md`.
+- Prefer short current-reference docs over long status reports.
+- Move old plans into `plans/archive/` instead of keeping them beside active
+  ownership plans.

package/docs/bridge.md

@@ -0,0 +1,135 @@
+> 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

@@ -0,0 +1,102 @@
+> 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.