refactor: consolidate MCP and dump trees, standardize util imports

AGENTS.md

@@ -30,7 +30,8 @@ The `pnpm test` script intentionally runs `build` first so `tsnapi` snapshots co
 ## Conventions
 
 - RPC functions must use `defineRpcFunction`; always namespace IDs (`my-plugin:fn-name`).
-- Shared state via `utils/shared-state`; keep values serializable.
+- Shared state via `devframe/utils/shared-state`; keep values serializable.
+- Utility imports use the package-path form `devframe/utils/*`, never relative `../utils/*`.
 - Dependencies go through the pnpm catalogs in `pnpm-workspace.yaml` (`cli`, `inlined`, `testing`, `types`) — add to a catalog and reference as `catalog:<name>`, don't pin versions in `package.json`.
 
 ### Devframe design principles

alias.ts

@@ -34,7 +34,7 @@ export const alias = {
   'devframe/adapters/build': r('devframe/src/adapters/build.ts'),
   'devframe/helpers/vite': r('devframe/src/helpers/vite.ts'),
   'devframe/adapters/embedded': r('devframe/src/adapters/embedded.ts'),
-  'devframe/adapters/mcp': r('devframe/src/adapters/mcp.ts'),
+  'devframe/adapters/mcp': r('devframe/src/adapters/mcp/index.ts'),
   '@devframes/nuxt/runtime/plugin.client': r('nuxt/src/runtime/plugin.client.ts'),
   '@devframes/nuxt': r('nuxt/src/index.ts'),
   'devframe/recipes/open-helpers': r('devframe/src/recipes/open-helpers.ts'),

docs/errors/DF0017.md

@@ -28,4 +28,4 @@ The agent-native surface is experimental and may change without a major version
 
 ## Source
 
-- [`packages/devframe/src/node/mcp/build-server.ts`](https://github.com/vitejs/devtools/blob/main/devframe/packages/devframe/src/node/mcp/build-server.ts) — `createMcpServer()` throws `DF0017` when the requested transport is unsupported or when the underlying transport fails to `connect()`.
+- [`packages/devframe/src/adapters/mcp/build-server.ts`](https://github.com/vitejs/devtools/blob/main/devframe/packages/devframe/src/adapters/mcp/build-server.ts) — `createMcpServer()` throws `DF0017` when the requested transport is unsupported or when the underlying transport fails to `connect()`.

docs/errors/DF0024.md

@@ -19,4 +19,4 @@ Add either `handler: ...` directly on the definition, or `setup: ctx => ({ handl
 ## Source
 
 - [`packages/devframe/src/rpc/handler.ts`](https://github.com/vitejs/devtools/blob/main/devframe/packages/devframe/src/rpc/handler.ts) — invocation throws `DF0024` when neither `handler` nor a `setup` returning `{ handler }` is provided.
-- [`packages/devframe/src/rpc/dumps.ts`](https://github.com/vitejs/devtools/blob/main/devframe/packages/devframe/src/rpc/dumps.ts) — dump generation also requires a handler and throws `DF0024` if the definition is incomplete.
+- [`packages/devframe/src/rpc/dump/index.ts`](https://github.com/vitejs/devtools/blob/main/devframe/packages/devframe/src/rpc/dump/index.ts) — dump generation also requires a handler and throws `DF0024` if the definition is incomplete.

docs/errors/DF0025.md

@@ -18,4 +18,4 @@ Re-run `createBuild` to regenerate the dump, or check that the call site uses th
 
 ## Source
 
-- [`packages/devframe/src/rpc/dumps.ts`](https://github.com/vitejs/devtools/blob/main/devframe/packages/devframe/src/rpc/dumps.ts) — the static-mode dump resolver throws `DF0025` when a client calls a function name that is not present in the baked dump store.
+- [`packages/devframe/src/rpc/dump/index.ts`](https://github.com/vitejs/devtools/blob/main/devframe/packages/devframe/src/rpc/dump/index.ts) — the static-mode dump resolver throws `DF0025` when a client calls a function name that is not present in the baked dump store.

docs/errors/DF0026.md

@@ -28,4 +28,4 @@ defineRpcFunction({
 
 ## Source
 
-- [`packages/devframe/src/rpc/dumps.ts`](https://github.com/vitejs/devtools/blob/main/devframe/packages/devframe/src/rpc/dumps.ts) — the static-mode dump resolver throws `DF0026` when none of the pre-computed inputs matches the call's args and no `fallback` was configured.
+- [`packages/devframe/src/rpc/dump/index.ts`](https://github.com/vitejs/devtools/blob/main/devframe/packages/devframe/src/rpc/dump/index.ts) — the static-mode dump resolver throws `DF0026` when none of the pre-computed inputs matches the call's args and no `fallback` was configured.

packages/devframe/src/adapters/build.ts

@@ -3,6 +3,8 @@ import type { DevframeDefinition } from '../types/devframe'
 import { existsSync } from 'node:fs'
 import fs from 'node:fs/promises'
 import process from 'node:process'
+import { colors as c } from 'devframe/utils/colors'
+import { structuredCloneStringify } from 'devframe/utils/structured-clone'
 import { dirname, resolve } from 'pathe'
 import {
   DEVTOOLS_CONNECTION_META_FILENAME,
@@ -11,10 +13,8 @@ import {
 } from '../constants'
 import { createHostContext } from '../node/context'
 import { createH3DevToolsHost } from '../node/host-h3'
-import { collectStaticRpcDump } from '../node/static-dump'
+import { collectStaticRpcDump } from '../rpc/dump/static'
 import { strictJsonStringify } from '../rpc/serialization'
-import { colors as c } from '../utils/colors'
-import { structuredCloneStringify } from '../utils/structured-clone'
 import { resolveBasePath } from './_shared'
 
 export interface CreateBuildOptions {

packages/devframe/src/adapters/cli.ts

@@ -3,7 +3,7 @@ import type { H3 } from 'h3'
 import type { DevframeDefinition } from '../types/devframe'
 import process from 'node:process'
 import cac from 'cac'
-import { colors as c } from '../utils/colors'
+import { colors as c } from 'devframe/utils/colors'
 import { createBuild } from './build'
 import { createDevServer, resolveDevServerPort } from './dev'
 import { flagKeyToOption, isBooleanFlag, parseCliFlags } from './flags'

packages/devframe/src/adapters/dev.ts

@@ -1,15 +1,15 @@
 import type { StartedServer } from '../node/server'
 import type { DevframeDefinition, DevframeSetupInfo } from '../types/devframe'
 import process from 'node:process'
+import { open } from 'devframe/utils/open'
+import { mountStaticHandler } from 'devframe/utils/serve-static'
 import { getPort } from 'get-port-please'
 import { H3 } from 'h3'
 import { resolve } from 'pathe'
 import { DEVTOOLS_CONNECTION_META_FILENAME } from '../constants'
 import { createHostContext } from '../node/context'
 import { createH3DevToolsHost } from '../node/host-h3'
 import { startHttpAndWs } from '../node/server'
-import { open } from '../utils/open'
-import { mountStaticHandler } from '../utils/serve-static'
 import { normalizeBasePath, resolveBasePath } from './_shared'
 
 const DEFAULT_PORT = 9999

packages/devframe/src/node/mcp/__tests__/mcp-server.test.ts → packages/devframe/src/adapters/mcp/__tests__/mcp-server.test.ts

@@ -1,8 +1,8 @@
 import type { DevToolsHost } from '../../../types/host'
 import { Client } from '@modelcontextprotocol/sdk/client/index.js'
 import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js'
+import { createHostContext } from 'devframe/node'
 import { describe, expect, it } from 'vitest'
-import { createHostContext } from '../../context'
 import { buildMcpServerFromContext } from '../build-server'
 
 function nullHost(): DevToolsHost {

packages/devframe/src/node/mcp/build-server.ts → packages/devframe/src/adapters/mcp/build-server.ts

@@ -10,9 +10,9 @@ import {
   ListToolsRequestSchema,
   ReadResourceRequestSchema,
 } from '@modelcontextprotocol/sdk/types.js'
+import { createHostContext } from 'devframe/node'
 import { join } from 'pathe'
-import { createHostContext } from '../context'
-import { logger } from '../diagnostics'
+import { logger } from '../../node/diagnostics'
 import { formatMcpError, stringifyForMcp } from './stringify'
 import { valibotArgsToJsonSchema, valibotReturnToJsonSchema } from './to-json-schema'
 

packages/devframe/src/adapters/mcp.ts → packages/devframe/src/adapters/mcp/index.ts

@@ -16,4 +16,4 @@ export {
   createMcpServer,
   type CreateMcpServerOptions,
   type McpServerHandle,
-} from '../node/mcp/build-server'
+} from './build-server'

packages/devframe/src/client/static-rpc.ts

@@ -1,7 +1,7 @@
 import type { RpcDumpRecordError } from '../rpc/types'
-import { reviveDumpError } from '../rpc/dump-error'
-import { hash } from '../utils/hash'
-import { structuredCloneDeserialize } from '../utils/structured-clone'
+import { hash } from 'devframe/utils/hash'
+import { structuredCloneDeserialize } from 'devframe/utils/structured-clone'
+import { reviveDumpError } from '../rpc/dump/error'
 
 export type StaticRpcSerialization = 'json' | 'structured-clone'
 

packages/devframe/src/helpers/vite.ts

@@ -1,10 +1,10 @@
 import type { DevframeDefinition } from '../types/devframe'
+import { serveStaticNodeMiddleware } from 'devframe/utils/serve-static'
 import { resolve } from 'pathe'
 import { resolveBasePath } from '../adapters/_shared'
 import { createDevServer, resolveDevServerPort } from '../adapters/dev'
 import { DEVTOOLS_CONNECTION_META_FILENAME } from '../constants'
 import { logger } from '../node/diagnostics'
-import { serveStaticNodeMiddleware } from '../utils/serve-static'
 
 export interface ViteDevBridgeOptions {
   /**

packages/devframe/src/node/diagnostics.ts

@@ -1,6 +1,6 @@
+import { colors as c } from 'devframe/utils/colors'
 import { consoleReporter, createLogger, defineDiagnostics } from 'logs-sdk'
 import { ansiFormatter } from 'logs-sdk/formatters/ansi'
-import { colors as c } from '../utils/colors'
 
 export const diagnostics = defineDiagnostics({
   docsBase: 'https://devfra.me/errors',

packages/devframe/src/node/host-diagnostics.ts

@@ -1,7 +1,7 @@
 import type { DevToolsDiagnosticsHost as DevToolsDiagnosticsHostType, DevToolsDiagnosticsLogger, DevToolsNodeContext } from 'devframe/types'
+import { colors as c } from 'devframe/utils/colors'
 import { consoleReporter, createLogger, defineDiagnostics } from 'logs-sdk'
 import { ansiFormatter } from 'logs-sdk/formatters/ansi'
-import { colors as c } from '../utils/colors'
 
 export class DevToolsDiagnosticsHost implements DevToolsDiagnosticsHostType {
   private _definitions: unknown[] = []

packages/devframe/src/node/index.ts

@@ -8,6 +8,5 @@ export * from './host-views'
 export * from './rpc-shared-state'
 export * from './rpc-streaming'
 export * from './server'
-export * from './static-dump'
 export * from './storage'
 export * from './utils'

packages/devframe/src/recipes/open-helpers.ts

@@ -1,7 +1,7 @@
+import { launchEditor } from 'devframe/utils/launch-editor'
+import { open } from 'devframe/utils/open'
 import * as v from 'valibot'
 import { defineRpcFunction } from '../rpc/define'
-import { launchEditor } from '../utils/launch-editor'
-import { open } from '../utils/open'
 
 /**
  * Prebuilt RPC action that opens a file in the user's configured editor.

packages/devframe/src/rpc/cache.ts

@@ -1,4 +1,4 @@
-import { hash } from '../utils/hash'
+import { hash } from 'devframe/utils/hash'
 
 export interface RpcCacheOptions {
   functions: string[]

packages/devframe/src/rpc/dumps.test.ts → packages/devframe/src/rpc/dump/__tests__/dump.test.ts

@@ -1,7 +1,7 @@
-import type { RpcDumpRecord } from './types'
+import type { RpcDumpRecord } from '../../types'
 import * as v from 'valibot'
 import { describe, expect, it } from 'vitest'
-import { createClientFromDump, createDefineWrapperWithContext, defineRpcFunction, dumpFunctions } from '.'
+import { createClientFromDump, createDefineWrapperWithContext, defineRpcFunction, dumpFunctions } from '../..'
 
 describe('dumps', () => {
   it('should collect dumps from definition', async () => {

packages/devframe/src/node/__tests__/static-dump.test.ts → packages/devframe/src/rpc/dump/__tests__/static.test.ts

@@ -3,7 +3,7 @@ import { DEVTOOLS_RPC_DUMP_DIRNAME } from 'devframe/constants'
 import { strictJsonStringify } from 'devframe/rpc'
 import { structuredCloneDeserialize, structuredCloneStringify } from 'devframe/utils/structured-clone'
 import { describe, expect, it } from 'vitest'
-import { collectStaticRpcDump } from '../static-dump'
+import { collectStaticRpcDump } from '../static'
 
 describe('collectStaticRpcDump', () => {
   it('tags entries as JSON when jsonSerializable: true is declared', async () => {

packages/devframe/src/rpc/dump-error.ts → packages/devframe/src/rpc/dump/error.ts

@@ -1,4 +1,4 @@
-import type { RpcDumpRecordError } from './types'
+import type { RpcDumpRecordError } from '../types'
 
 /**
  * Normalize a thrown value into a plain object suitable for storage in

packages/devframe/src/rpc/dumps.ts → packages/devframe/src/rpc/dump/index.ts

@@ -6,12 +6,12 @@ import type {
   RpcDumpDefinition,
   RpcDumpStore,
   RpcFunctionDefinitionAny,
-} from './types'
+} from '../types'
+import { hash } from 'devframe/utils/hash'
 import pLimit from 'p-limit'
-import { hash } from '../utils/hash'
-import { logger } from './diagnostics'
-import { reviveDumpError, serializeDumpError } from './dump-error'
-import { validateDefinitions } from './validation'
+import { logger } from '../diagnostics'
+import { validateDefinitions } from '../validation'
+import { reviveDumpError, serializeDumpError } from './error'
 
 function getDumpRecordKey(functionName: string, args: any[]): string {
   const argsHash = hash(args)

packages/devframe/src/rpc/index.ts

@@ -1,7 +1,9 @@
 export * from './cache'
 export * from './collector'
 export * from './define'
-export * from './dumps'
+export * from './dump'
+export * from './dump/error'
+export * from './dump/static'
 export * from './handler'
 export * from './serialization'
 export * from './types'

packages/devframe/src/rpc/transports/ws-client.ts

@@ -1,6 +1,6 @@
 import type { ChannelOptions } from 'birpc'
 import type { RpcFunctionDefinitionAny } from '../types'
-import { structuredCloneParse, structuredCloneStringify } from '../../utils/structured-clone'
+import { structuredCloneParse, structuredCloneStringify } from 'devframe/utils/structured-clone'
 import { strictJsonStringify, STRUCTURED_CLONE_PREFIX } from '../serialization'
 
 export interface WsRpcChannelOptions {

packages/devframe/src/rpc/transports/ws-server.ts

@@ -4,8 +4,8 @@ import type { ServerOptions as HttpsServerOptions } from 'node:https'
 import type { WebSocket } from 'ws'
 import type { RpcFunctionDefinitionAny } from '../types'
 import { createServer as createHttpsServer } from 'node:https'
+import { structuredCloneParse, structuredCloneStringify } from 'devframe/utils/structured-clone'
 import { WebSocketServer } from 'ws'
-import { structuredCloneParse, structuredCloneStringify } from '../../utils/structured-clone'
 import { strictJsonStringify, STRUCTURED_CLONE_PREFIX } from '../serialization'
 
 export interface DevToolsNodeRpcSessionMeta {

packages/devframe/src/types/rpc.ts

@@ -1,8 +1,8 @@
 import type { BirpcReturn } from 'birpc'
 import type { RpcFunctionsCollectorBase } from 'devframe/rpc'
 import type { DevToolsNodeRpcSessionMeta } from 'devframe/rpc/transports/ws-server'
-import type { SharedState } from '../utils/shared-state'
-import type { StreamReader, StreamSink } from '../utils/streaming-channel'
+import type { SharedState } from 'devframe/utils/shared-state'
+import type { StreamReader, StreamSink } from 'devframe/utils/streaming-channel'
 import type { DevToolsNodeContext } from './context'
 import type { DevToolsRpcClientFunctions, DevToolsRpcServerFunctions, DevToolsRpcSharedStates } from './rpc-augments'
 

packages/devframe/tsdown.config.ts

@@ -44,7 +44,7 @@ export default defineConfig({
     'adapters/build': 'src/adapters/build.ts',
     'helpers/vite': 'src/helpers/vite.ts',
     'adapters/embedded': 'src/adapters/embedded.ts',
-    'adapters/mcp': 'src/adapters/mcp.ts',
+    'adapters/mcp': 'src/adapters/mcp/index.ts',
     'client/index': 'src/client/index.ts',
     'recipes/open-helpers': 'src/recipes/open-helpers.ts',
   },

tests/__snapshots__/tsnapi/devframe/node.snapshot.d.ts

@@ -22,32 +22,6 @@ export interface CreateStorageOptions<T extends object> {
   mergeInitialValue?: false | ((_: T, _: T) => T);
   debounce?: number;
 }
-export interface StaticRpcDumpCollection {
-  manifest: StaticRpcDumpManifest;
-  files: Record<string, StaticRpcDumpFile>;
-}
-export interface StaticRpcDumpFile {
-  serialization: StaticRpcDumpSerialization;
-  fnName: string;
-  data: unknown;
-}
-export interface StaticRpcDumpManifestQueryEntry {
-  type: 'query';
-  records: Record<string, string>;
-  fallback?: string;
-  serialization?: StaticRpcDumpSerialization;
-}
-export interface StaticRpcDumpManifestStaticEntry {
-  type: 'static';
-  path: string;
-  serialization?: StaticRpcDumpSerialization;
-}
-// #endregion
-
-// #region Types
-export type StaticRpcDumpManifest = Record<string, StaticRpcDumpManifestValue>;
-export type StaticRpcDumpManifestValue = StaticRpcDumpManifestStaticEntry | StaticRpcDumpManifestQueryEntry | any;
-export type StaticRpcDumpSerialization = 'json' | 'structured-clone';
 // #endregion
 
 // #region Classes
@@ -108,7 +82,6 @@ export declare class RpcFunctionsHost extends RpcFunctionsCollectorBase<DevTools
 // #endregion
 
 // #region Functions
-export declare function collectStaticRpcDump(_: Iterable<RpcFunctionDefinitionAny>, _: any): Promise<StaticRpcDumpCollection>;
 export declare function createH3DevToolsHost(_: CreateH3DevToolsHostOptions): DevToolsHost;
 export declare function createHostContext(_: CreateHostContextOptions): Promise<DevToolsNodeContext>;
 export declare function createRpcSharedStateServerHost(_: RpcFunctionsHost$1): RpcSharedStateHost;

tests/__snapshots__/tsnapi/devframe/node.snapshot.js

@@ -7,7 +7,6 @@ export function normalizeHttpServerUrl(_, _) {}
 // #endregion
 
 // #region Other
-export { collectStaticRpcDump }
 export { createH3DevToolsHost }
 export { createHostContext }
 export { createRpcSharedStateServerHost }

tests/__snapshots__/tsnapi/devframe/rpc.snapshot.d.ts

@@ -4,6 +4,7 @@
 // #region Other
 export { BirpcFn }
 export { BirpcReturn }
+export { collectStaticRpcDump }
 export { createClientFromDump }
 export { createDefineWrapperWithContext }
 export { defineRpcFunction }
@@ -12,6 +13,7 @@ export { EntriesToObject }
 export { getDefinitionsWithDumps }
 export { getRpcHandler }
 export { getRpcResolvedSetupResult }
+export { reviveDumpError }
 export { RpcArgsSchema }
 export { RpcCacheManager }
 export { RpcCacheOptions }
@@ -36,6 +38,14 @@ export { RpcFunctionsCollectorBase }
 export { RpcFunctionSetupResult }
 export { RpcFunctionType }
 export { RpcReturnSchema }
+export { serializeDumpError }
+export { StaticRpcDumpCollection }
+export { StaticRpcDumpFile }
+export { StaticRpcDumpManifest }
+export { StaticRpcDumpManifestQueryEntry }
+export { StaticRpcDumpManifestStaticEntry }
+export { StaticRpcDumpManifestValue }
+export { StaticRpcDumpSerialization }
 export { strictJsonStringify }
 export { STRUCTURED_CLONE_PREFIX }
 export { Thenable }

tests/__snapshots__/tsnapi/devframe/rpc.snapshot.js

@@ -2,15 +2,18 @@
  * Generated by tsnapi — public API snapshot of `devframe/rpc`
  */
 // #region Other
+export { collectStaticRpcDump }
 export { createClientFromDump }
 export { createDefineWrapperWithContext }
 export { defineRpcFunction }
 export { dumpFunctions }
 export { getDefinitionsWithDumps }
 export { getRpcHandler }
 export { getRpcResolvedSetupResult }
+export { reviveDumpError }
 export { RpcCacheManager }
 export { RpcFunctionsCollectorBase }
+export { serializeDumpError }
 export { strictJsonStringify }
 export { STRUCTURED_CLONE_PREFIX }
 export { validateDefinition }

tsconfig.base.json

@@ -94,7 +94,7 @@
         "./packages/devframe/src/adapters/embedded.ts"
       ],
       "devframe/adapters/mcp": [
-        "./packages/devframe/src/adapters/mcp.ts"
+        "./packages/devframe/src/adapters/mcp/index.ts"
       ],
       "@devframes/nuxt/runtime/plugin.client": [
         "./packages/nuxt/src/runtime/plugin.client.ts"