feat(devframe): framework-neutral devtools foundation + agent-native MCP (#297)

Author: antfu

AGENTS.md

@@ -8,9 +8,9 @@ Monorepo (`pnpm` workspaces + `turbo`). ESM TypeScript; bundled with `tsdown`. P
 
 | Package | npm | Description |
 |---------|-----|-------------|
-| `packages/core` | `@vitejs/devtools` | Vite plugin, CLI, runtime hosts (docks, views, terminals), WS RPC server, standalone/webcomponents client |
-| `packages/kit` | `@vitejs/devtools-kit` | Public types/utilities for integration authors (`defineRpcFunction`, shared state, events, client helpers) |
-| `packages/rpc` | `@vitejs/devtools-rpc` | Typed RPC wrapper over `birpc` with WS presets |
+| `packages/devframe` | `devframe` | Framework-neutral foundation — RPC layer (birpc + valibot + WS presets), host classes, createHostContext, six adapters at `devframe/adapters/*` (cli/build/spa/vite/kit/embedded), connectDevtool client |
+| `packages/core` | `@vitejs/devtools` | Vite plugin, CLI, standalone/webcomponents client. Wraps devframe's createHostContext with the Vite plugin scan |
+| `packages/kit` | `@vitejs/devtools-kit` | Vite-specific superset of devframe — adds PluginWithDevTools, ViteDevToolsNodeContext, and re-exports devframe's public types |
 | `packages/ui` | `@vitejs/devtools-ui` | Shared UI components, composables, and UnoCSS preset (`presetDevToolsUI`). Private, not published |
 | `packages/rolldown` | `@vitejs/devtools-rolldown` | Nuxt UI for Rolldown build data. Serves at `/.devtools-rolldown/` |
 | `packages/vite` | `@vitejs/devtools-vite` | Nuxt UI for Vite DevTools (WIP). Serves at `/.devtools-vite/` |
@@ -23,20 +23,25 @@ Other top-level directories:
 
 ```mermaid
 flowchart TD
-  core["core"] --> kit & rpc
+  kit --> devframe
+  core --> kit
   core --> rolldown & vite & self-inspect
-  rolldown --> kit & rpc & ui
-  vite --> kit & rpc & ui
-  self-inspect --> kit & rpc
+  rolldown --> kit & ui
+  vite --> kit & ui
+  self-inspect --> kit
   webext --> core
 ```
 
+## Dep Boundary
+
+`packages/devframe` is the lowest-level package in this monorepo and is positioned to be extracted into its own repo. It MUST NOT import from `vite` or any `@vitejs/*` package — not as a `dependencies` entry, not as an inlined dep, not as a source import. `packages/kit` and above build on top of devframe, never the reverse.
+
 ## Architecture
 
 - **Entry**: `createDevToolsContext` (`packages/core/src/node/context.ts`) builds `DevToolsNodeContext` with hosts for RPC, docks, views, terminals. Invokes `plugin.devtools.setup` hooks.
 - **Node context**: server-side (cwd, vite config, mode, hosts, auth storage at `node_modules/.vite/devtools/auth.json`).
 - **Client context**: webcomponents/Nuxt UI state (`packages/core/src/client/webcomponents/state/*`) — dock entries, panels, RPC client. Two modes: `embedded` (overlay in host app) and `standalone` (independent page).
-- **WS server** (`packages/core/src/node/ws.ts`): RPC via `@vitejs/devtools-rpc/presets/ws`. Auth skipped in build mode or when `devtools.clientAuth` is `false`.
+- **WS server** (`packages/core/src/node/ws.ts`): RPC via `devframe/rpc/transports/ws-server`. Auth skipped in build mode or when `devtools.clientAuth` is `false`.
 - **Nuxt UI plugins** (rolldown, vite, self-inspect): each registers RPC functions and hosts static Nuxt SPA at its own base path.
 
 ## Development
@@ -57,11 +62,21 @@ pnpm -C docs run docs                 # docs dev server
 
 - Use workspace aliases from `alias.ts`.
 - RPC functions must use `defineRpcFunction` from kit; always namespace IDs (`my-plugin:fn-name`).
-- Shared state via `@vitejs/devtools-kit/utils/shared-state`; keep values serializable.
+- Shared state via `devframe/utils/shared-state`; keep values serializable.
 - Nuxt UI base paths: `/.devtools-rolldown/`, `/.devtools-vite/`, `/.devtools-self-inspect/`.
 - Shared UI components/preset in `packages/ui`; use `presetDevToolsUI` from `@vitejs/devtools-ui/unocss`.
 - Currently focused on Rolldown build-mode analysis; dev-mode support is deferred.
 
+### Devframe design principles
+
+These apply to everything inside `packages/devframe` and to how host packages (`kit`, `core`, etc.) layer on top. When in doubt, err on the side of "devframe provides hooks, the app decides UX".
+
+- **Headless by default.** No default startup banners, no opinionated logging to stdout, no default styling. Provide hooks (`onReady`, `cli.configure`, etc.); let the application print its own branding. Structured diagnostics via `logs-sdk` are fine — ad-hoc `console.log`s baked into adapters are not.
+- **File watching is the app's job, not devframe's.** Don't add a generic watcher primitive. Authors wire chokidar / fs.watch / watchman themselves and signal change via `ctx.rpc.sharedState.set(...)` or event-type RPCs. devframe stays out of the filesystem-observation business.
+- **Mount path depends on adapter context.** Given `id: 'foo'`, the default mount path is `/.foo/` for *hosted* adapters (`vite`, `kit`, `embedded`) and `/` for *standalone* adapters (`cli`, `spa`, `build`). Authors override via `DevtoolDefinition.basePath`. Don't hardcode `DEVTOOLS_MOUNT_PATH` in adapter code paths that may run standalone.
+- **SPAs own their basePath at runtime.** Build SPAs with relative asset paths (`vite.base: './'`); discover the effective base in the browser from the executing script's location / `document.baseURI`. `createBuild` / `createSpa` copy SPA output verbatim — no HTML rewriting, no build-time `--base` injection. The client (`connectDevtool`) resolves `.connection.json` relative to the runtime base automatically.
+- **CLI flags compose from both sides.** The `cac` instance backing `createCli` is exposed both to the `DevtoolDefinition` (`cli.configure(cli)`) — for capabilities contributed by the tool itself — and to the `createCli` caller — for flags added at the final assembly stage. Parsed flag values are forwarded to `setup(ctx, { flags })`. Never hardcode domain-specific flags into `createCli`.
+
 ## Structured Diagnostics (Error Codes)
 
 All node-side warnings and errors use structured diagnostics via [`logs-sdk`](https://github.com/vercel-labs/logs-sdk). Never use raw `console.warn`, `console.error`, or `throw new Error` with ad-hoc messages in node-side code — always define a coded diagnostic.
@@ -70,7 +85,8 @@ All node-side warnings and errors use structured diagnostics via [`logs-sdk`](ht
 
 | Prefix | Package(s) | Diagnostics file |
 |--------|-----------|-----------------|
-| `DTK` | `packages/rpc`, `packages/core` | `packages/rpc/src/diagnostics.ts`, `packages/core/src/node/diagnostics.ts` |
+| `DF` | `packages/devframe` | `packages/devframe/src/node/diagnostics.ts`, `packages/devframe/src/rpc/diagnostics.ts` |
+| `DTK` | `packages/core` (Vite-specific remainder) | `packages/core/src/node/diagnostics.ts` |
 | `RDDT` | `packages/rolldown` | `packages/rolldown/src/node/diagnostics.ts` |
 | `VDT` | `packages/vite` (reserved) | — |
 

alias.ts

@@ -4,14 +4,36 @@ import { join, relative } from 'pathe'
 
 const root = fileURLToPath(new URL('.', import.meta.url))
 const r = (path: string) => fileURLToPath(new URL(`./packages/${path}`, import.meta.url))
+const df = (path: string) => fileURLToPath(new URL(`./devframe/packages/${path}`, import.meta.url))
 
 export const alias = {
-  '@vitejs/devtools-rpc/presets/ws/server': r('rpc/src/presets/ws/server.ts'),
-  '@vitejs/devtools-rpc/presets/ws/client': r('rpc/src/presets/ws/client.ts'),
-  '@vitejs/devtools-rpc/presets': r('rpc/src/presets/index.ts'),
-  '@vitejs/devtools-rpc/client': r('rpc/src/client.ts'),
-  '@vitejs/devtools-rpc/server': r('rpc/src/server.ts'),
-  '@vitejs/devtools-rpc': r('rpc/src'),
+  'devframe/rpc/transports/ws-server': df('devframe/src/rpc/transports/ws-server.ts'),
+  'devframe/rpc/transports/ws-client': df('devframe/src/rpc/transports/ws-client.ts'),
+  'devframe/rpc/client': df('devframe/src/rpc/client.ts'),
+  'devframe/rpc/server': df('devframe/src/rpc/server.ts'),
+  'devframe/rpc': df('devframe/src/rpc'),
+  'devframe/types': df('devframe/src/types/index.ts'),
+  'devframe/node': df('devframe/src/node/index.ts'),
+  'devframe/constants': df('devframe/src/constants.ts'),
+  'devframe/utils/events': df('devframe/src/utils/events.ts'),
+  'devframe/utils/human-id': df('devframe/src/utils/human-id.ts'),
+  'devframe/utils/nanoid': df('devframe/src/utils/nanoid.ts'),
+  'devframe/utils/promise': df('devframe/src/utils/promise.ts'),
+  'devframe/utils/shared-state': df('devframe/src/utils/shared-state.ts'),
+  'devframe/utils/state': df('devframe/src/utils/state.ts'),
+  'devframe/utils/when': df('devframe/src/utils/when.ts'),
+  'devframe/adapters/cli': df('devframe/src/adapters/cli.ts'),
+  'devframe/adapters/build': df('devframe/src/adapters/build.ts'),
+  'devframe/adapters/vite': df('devframe/src/adapters/vite.ts'),
+  'devframe/adapters/kit': df('devframe/src/adapters/kit.ts'),
+  'devframe/adapters/embedded': df('devframe/src/adapters/embedded.ts'),
+  'devframe/adapters/mcp': df('devframe/src/adapters/mcp.ts'),
+  'devframe/helpers/nuxt/runtime/plugin.client': df('devframe/src/helpers/nuxt/runtime/plugin.client.ts'),
+  'devframe/helpers/nuxt': df('devframe/src/helpers/nuxt/index.ts'),
+  'devframe/recipes/open-helpers': df('devframe/src/recipes/open-helpers.ts'),
+  'devframe/client': df('devframe/src/client/index.ts'),
+  'devframe': df('devframe/src'),
+  '@vitejs/devtools-kit/node': r('kit/src/node/index.ts'),
   '@vitejs/devtools-kit/client': r('kit/src/client/index.ts'),
   '@vitejs/devtools-kit/constants': r('kit/src/constants.ts'),
   '@vitejs/devtools-kit/utils/events': r('kit/src/utils/events.ts'),

devframe/README.md

@@ -0,0 +1,39 @@
+# DevFrame
+
+Framework-neutral foundation for building generic DevTools — an RPC layer (birpc + valibot + WS presets), runtime hosts (RPC / docks / views / terminals / logs / commands / agent), and adapters that deploy a single devtool definition to seven targets: `cli`, `build`, `vite`, `kit`, `embedded`, `mcp`, plus the `spa` mode.
+
+## Layout
+
+This directory is staged for extraction into a standalone repository. Until then it lives inside the [`vitejs/devtools`](https://github.com/vitejs/devtools) monorepo.
+
+| Path | Description |
+|------|-------------|
+| [`packages/devframe`](./packages/devframe) | The published [`devframe`](https://www.npmjs.com/package/devframe) npm package. |
+| [`docs`](./docs) | VitePress documentation site, deployed at https://devtools.vite.dev/devframe/. |
+| [`examples`](./examples) | End-to-end demos: [`devframe-counter`](./examples/devframe-counter) (smallest cross-adapter demo) and [`devframe-files-inspector`](./examples/devframe-files-inspector) (CLI dev/build/spa + Vite DevTools dock). |
+| [`tests`](./tests) | Public-API snapshot tests via [`tsnapi`](https://github.com/posva/tsnapi). |
+
+## Install
+
+```sh
+pnpm add devframe
+```
+
+## Documentation
+
+See [https://devtools.vite.dev/devframe/](https://devtools.vite.dev/devframe/) for the full guide and API reference.
+
+## Adapters
+
+| Adapter | Use case |
+|---------|----------|
+| `cli` | Standalone CLI tool with `dev` / `build` / `mcp` subcommands. |
+| `build` | Generates a static, self-contained SPA snapshot. |
+| `vite` | Runs as a Vite plugin alongside the host app's dev server. |
+| `kit` | Plugs into the DevTools Kit aggregator. |
+| `embedded` | Mounts as an overlay inside another devtool's UI. |
+| `mcp` | Exposes the devtool's RPC surface to coding agents over MCP. |
+
+## License
+
+[MIT](./packages/devframe/LICENSE.md)

devframe/docs/.vitepress/config.ts

@@ -0,0 +1,50 @@
+import { defineConfig } from 'vitepress'
+import { withMermaid } from 'vitepress-plugin-mermaid'
+import devframeSidebar from './sidebar'
+
+export default withMermaid(defineConfig({
+  title: 'DevFrame',
+  description: 'Framework-neutral foundation for building generic DevTools — RPC layer, hosts, and adapters.',
+  themeConfig: {
+    nav: [
+      { text: 'Guide', link: '/guide/' },
+      { text: 'Errors', link: '/errors/' },
+    ],
+    sidebar: devframeSidebar(),
+    search: {
+      provider: 'local',
+    },
+    socialLinks: [
+      { icon: 'github', link: 'https://github.com/vitejs/devtools' },
+    ],
+    editLink: {
+      pattern: 'https://github.com/vitejs/devtools/edit/main/devframe/docs/:path',
+      text: 'Suggest changes to this page',
+    },
+    footer: {
+      message: 'Released under the MIT License.',
+      copyright: 'Copyright © 2025-present VoidZero Inc. & Vite Contributors',
+    },
+    lastUpdated: {
+      text: 'Last updated',
+    },
+  },
+  mermaid: {
+    theme: 'base',
+    flowchart: {
+      curve: 'basis',
+      padding: 20,
+      nodeSpacing: 50,
+      rankSpacing: 60,
+      useMaxWidth: true,
+    },
+    sequence: {
+      actorMargin: 80,
+      boxMargin: 10,
+      boxTextMargin: 5,
+      noteMargin: 10,
+      messageMargin: 40,
+      useMaxWidth: true,
+    },
+  },
+}))

devframe/docs/.vitepress/sidebar.ts

@@ -0,0 +1,34 @@
+import type { DefaultTheme } from 'vitepress'
+
+export default function devframeSidebar(prefix = ''): DefaultTheme.SidebarItem[] {
+  return [
+    {
+      text: 'Guide',
+      items: [
+        { text: 'Introduction', link: `${prefix}/guide/` },
+        { text: 'Devtool Definition', link: `${prefix}/guide/devtool-definition` },
+        { text: 'Adapters', link: `${prefix}/guide/adapters` },
+        { text: 'RPC', link: `${prefix}/guide/rpc` },
+        { text: 'Shared State', link: `${prefix}/guide/shared-state` },
+        { text: 'Dock System', link: `${prefix}/guide/dock-system` },
+        { text: 'Commands', link: `${prefix}/guide/commands` },
+        { text: 'When Clauses', link: `${prefix}/guide/when-clauses` },
+        { text: 'Logs & Notifications', link: `${prefix}/guide/logs` },
+        { text: 'Terminals', link: `${prefix}/guide/terminals` },
+        { text: 'Client', link: `${prefix}/guide/client` },
+        { text: 'Standalone CLI', link: `${prefix}/guide/standalone-cli` },
+        { text: 'Nuxt Helper', link: `${prefix}/guide/nuxt` },
+        { text: 'Agent-Native (experimental)', link: `${prefix}/guide/agent-native` },
+      ],
+    },
+    {
+      text: 'Error Reference',
+      link: `${prefix}/errors/`,
+      collapsed: true,
+      items: Array.from({ length: 17 }, (_, i) => {
+        const code = `DF${String(i + 1).padStart(4, '0')}`
+        return { text: code, link: `${prefix}/errors/${code}` }
+      }),
+    },
+  ]
+}

devframe/docs/errors/DF0001.md

@@ -0,0 +1,27 @@
+---
+outline: deep
+---
+
+# DF0001: Dock Already Registered
+
+> Package: `devframe`
+
+## Message
+
+> Dock with id "`{id}`" is already registered
+
+## Cause
+
+`DevToolsDockHost.register()` rejects duplicate ids by default.
+
+## Fix
+
+Pass `force: true` as the second argument to intentionally overwrite, or choose a unique dock id.
+
+## Source
+
+`packages/devframe/src/node/host-docks.ts`
+
+## Migrated from
+
+Previously documented as `DTK0015` under `@vitejs/devtools`.

devframe/docs/errors/DF0002.md

@@ -0,0 +1,27 @@
+---
+outline: deep
+---
+
+# DF0002: Cannot Change Dock ID
+
+> Package: `devframe`
+
+## Message
+
+> Cannot change the id of a dock. Use register() to add new docks.
+
+## Cause
+
+`DevToolsDockHost.update()` rejects id changes because docks are keyed by id.
+
+## Fix
+
+Keep the `id` on `update(patch)` identical to the registered value, or call `register()` with a new id (and optionally `force: true`).
+
+## Source
+
+`packages/devframe/src/node/host-docks.ts`
+
+## Migrated from
+
+Previously documented as `DTK0016` under `@vitejs/devtools`.

devframe/docs/errors/DF0003.md

@@ -0,0 +1,27 @@
+---
+outline: deep
+---
+
+# DF0003: Dock Not Registered
+
+> Package: `devframe`
+
+## Message
+
+> Dock with id "`{id}`" is not registered. Use register() to add new docks.
+
+## Cause
+
+`DevToolsDockHost.update()` was called with an id that has no matching registration.
+
+## Fix
+
+Call `register()` first, or check the id against `dockHost.values()` before updating.
+
+## Source
+
+`packages/devframe/src/node/host-docks.ts`
+
+## Migrated from
+
+Previously documented as `DTK0017` under `@vitejs/devtools`.

devframe/docs/errors/DF0004.md

@@ -0,0 +1,27 @@
+---
+outline: deep
+---
+
+# DF0004: Terminal Session Already Registered
+
+> Package: `devframe`
+
+## Message
+
+> Terminal session with id "`{id}`" already registered
+
+## Cause
+
+`DevToolsTerminalHost.register()` already has a session under that id.
+
+## Fix
+
+Use a unique session id or call `unregister(id)` first.
+
+## Source
+
+`packages/devframe/src/node/host-terminals.ts`
+
+## Migrated from
+
+Previously documented as `DTK0018` under `@vitejs/devtools`.

devframe/docs/errors/DF0005.md

@@ -0,0 +1,27 @@
+---
+outline: deep
+---
+
+# DF0005: Terminal Session Not Registered
+
+> Package: `devframe`
+
+## Message
+
+> Terminal session with id "`{id}`" not registered
+
+## Cause
+
+A terminal operation (update, read, close) referenced an id that the host does not know about.
+
+## Fix
+
+Ensure the session was created via `register()` before calling update/read/close operations on it.
+
+## Source
+
+`packages/devframe/src/node/host-terminals.ts`
+
+## Migrated from
+
+Previously documented as `DTK0019` under `@vitejs/devtools`.