@hachej/boring-workspace 0.1.0

package/docs/plugins.md

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

package/package.json

@@ -0,0 +1,164 @@
+{
+  "name": "@hachej/boring-workspace",
+  "version": "0.1.0",
+  "type": "module",
+  "license": "MIT",
+  "description": "Workspace UI, plugin, and bridge package for composing chat, files, catalogs, editors, and app-specific panes.",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/hachej/boring-ui.git"
+  },
+  "homepage": "https://github.com/hachej/boring-ui",
+  "files": [
+    "dist",
+    "docs"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/workspace.d.ts",
+      "import": "./dist/workspace.js"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "import": "./dist/testing.js"
+    },
+    "./testing/e2e": {
+      "types": "./dist/testing-e2e.d.ts",
+      "import": "./dist/testing-e2e.js"
+    },
+    "./charts": {
+      "types": "./dist/charts.d.ts",
+      "import": "./dist/charts.js"
+    },
+    "./shared": {
+      "types": "./dist/shared.d.ts",
+      "import": "./dist/shared.js"
+    },
+    "./app/front": {
+      "types": "./dist/app-front.d.ts",
+      "import": "./dist/app-front.js",
+      "default": "./dist/app-front.js"
+    },
+    "./app/server": {
+      "types": "./dist/app-server.d.ts",
+      "import": "./dist/app-server.js",
+      "default": "./dist/app-server.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js",
+      "default": "./dist/server.js"
+    },
+    "./events": {
+      "types": "./dist/events.d.ts",
+      "import": "./dist/events.js"
+    },
+    "./globals.css": "./dist/workspace.css"
+  },
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0",
+    "recharts": "^2.15.0"
+  },
+  "peerDependenciesMeta": {
+    "@codemirror/state": {
+      "optional": true
+    },
+    "@codemirror/view": {
+      "optional": true
+    },
+    "@tiptap/react": {
+      "optional": true
+    },
+    "@tiptap/starter-kit": {
+      "optional": true
+    },
+    "recharts": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@codemirror/commands": "^6.10.3",
+    "@codemirror/lang-javascript": "^6.2.5",
+    "@codemirror/lang-json": "^6.0.2",
+    "@codemirror/lang-markdown": "^6.5.0",
+    "@codemirror/lang-python": "^6.2.1",
+    "@codemirror/lang-sql": "^6.10.0",
+    "@codemirror/lang-yaml": "^6.1.3",
+    "@codemirror/language": "^6.12.3",
+    "@codemirror/search": "^6.7.0",
+    "@codemirror/state": "^6.6.0",
+    "@codemirror/view": "^6.41.1",
+    "@lezer/highlight": "^1.2.3",
+    "@tanstack/react-query": "^5.0.0",
+    "@tiptap/core": "^3.22.4",
+    "@tiptap/extension-code-block-lowlight": "^3.22.4",
+    "@tiptap/extension-highlight": "^3.22.4",
+    "@tiptap/extension-image": "^3.22.4",
+    "@tiptap/extension-link": "^3.22.4",
+    "@tiptap/extension-placeholder": "^3.22.4",
+    "@tiptap/extension-table": "^3.22.5",
+    "@tiptap/extension-table-cell": "^3.22.5",
+    "@tiptap/extension-table-header": "^3.22.5",
+    "@tiptap/extension-table-row": "^3.22.5",
+    "@tiptap/extension-task-item": "^3.22.4",
+    "@tiptap/extension-task-list": "^3.22.4",
+    "@tiptap/extension-text-align": "^3.22.4",
+    "@tiptap/extension-underline": "^3.22.4",
+    "@tiptap/pm": "^3.22.4",
+    "@tiptap/react": "^3.22.4",
+    "@tiptap/starter-kit": "^3.22.4",
+    "class-variance-authority": "^0.7.0",
+    "clsx": "^2.1.0",
+    "cmdk": "^1.1.1",
+    "dockview-react": "^4.13.1",
+    "fastify": "^5.3.3",
+    "lowlight": "^3.3.0",
+    "lucide-react": "^1.8.0",
+    "micromatch": "^4.0.8",
+    "radix-ui": "^1.4.3",
+    "react-arborist": "^3.4.0",
+    "tailwind-merge": "^2.0.0",
+    "tiptap-markdown": "^0.9.0",
+    "zod": "^3.23.0",
+    "zustand": "^5.0.0",
+    "@hachej/boring-agent": "0.1.0",
+    "@hachej/boring-ui-kit": "0.1.0"
+  },
+  "devDependencies": {
+    "@tailwindcss/postcss": "^4.0.0",
+    "@tailwindcss/vite": "^4.0.0",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.2",
+    "@testing-library/user-event": "^14.6.1",
+    "@types/micromatch": "^4.0.10",
+    "@types/node": "^22.15.3",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "@vitejs/plugin-react": "^4.0.0",
+    "fast-check": "^4.7.0",
+    "jsdom": "^29.0.2",
+    "postcss": "^8.5.13",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "recharts": "^2.15.4",
+    "tailwindcss": "^4.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0",
+    "vite": "^6.0.0",
+    "vite-plugin-dts": "^4.5.4",
+    "vitest": "^2.0.0"
+  },
+  "scripts": {
+    "dev": "vite",
+    "build": "pnpm --filter @hachej/boring-ui-kit build && tsup && vite build && node ./scripts/build-workspace-css.mjs && node ./scripts/assert-build-artifacts.mjs",
+    "typecheck": "pnpm --filter @hachej/boring-ui-kit build && pnpm --filter @hachej/boring-agent build && tsc --noEmit -p tsconfig.front.json && tsc --noEmit -p tsconfig.server.json",
+    "test": "vitest run",
+    "check:bundle-size": "node ./scripts/check-bundle-size.mjs",
+    "lint:plugin-invariants": "node ./scripts/check-plugin-invariants.mjs",
+    "lint": "pnpm run typecheck"
+  }
+}