feat: migrate warnings/errors to structured diagnostics via logs-sdk

Replace inconsistent console.warn/error/throw patterns with structured
diagnostics using @antfu/experimental-logs-sdk. Each error gets a unique
code (DTK0001-DTK0032 for core/rpc, RDDT0001-RDDT0002 for rolldown)
with auto-generated docs URLs and ANSI-formatted output.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: antfu

.gitignore

@@ -20,3 +20,6 @@ packages/kit/skills
 docs/.vitepress/cache
 .turbo
 .context
+
+# Agent skills from npm packages (managed by skills-npm)
+**/skills/npm-*

docs/.vitepress/config.ts

@@ -91,6 +91,29 @@ export default extendConfig(withMermaid(defineConfig({
           { text: 'Examples', link: '/kit/examples' },
         ],
       },
+      {
+        text: 'Error Reference',
+        link: '/errors/',
+        collapsed: true,
+        items: [
+          {
+            text: 'DevTools Kit (DTK)',
+            collapsed: true,
+            items: Array.from({ length: 32 }, (_, i) => {
+              const code = `DTK${String(i + 1).padStart(4, '0')}`
+              return { text: code, link: `/errors/${code}` }
+            }),
+          },
+          {
+            text: 'Rolldown DevTools (RDDT)',
+            collapsed: true,
+            items: [
+              { text: 'RDDT0001', link: '/errors/RDDT0001' },
+              { text: 'RDDT0002', link: '/errors/RDDT0002' },
+            ],
+          },
+        ],
+      },
     ],
 
     search: {

docs/errors/DTK0001.md

@@ -0,0 +1,60 @@
+---
+outline: deep
+---
+
+# DTK0001: RPC Function Already Registered
+
+> Package: `@vitejs/devtools-rpc`
+
+## Message
+
+> RPC function "`{name}`" is already registered
+
+## Cause
+
+This error is thrown by `RpcFunctionsCollectorBase.register()` when you attempt to register an RPC function with a name that already exists in the collector. Each function name must be unique within a collector instance unless you explicitly opt into overwriting.
+
+## Example
+
+```ts
+import { defineRpcFunction } from '@vitejs/devtools-kit'
+
+const getVersion = defineRpcFunction({
+  name: 'my-plugin:get-version',
+  type: 'static',
+  handler: () => '1.0.0',
+})
+
+const getVersionAlt = defineRpcFunction({
+  name: 'my-plugin:get-version', // same name as above
+  type: 'static',
+  handler: () => '2.0.0',
+})
+
+// First registration succeeds
+collector.register(getVersion)
+
+// Second registration throws DTK0001
+collector.register(getVersionAlt)
+```
+
+## Fix
+
+Either use a unique name for each function, or pass `force: true` to overwrite the existing registration:
+
+```ts
+// Option 1: Use a unique name
+const getVersionAlt = defineRpcFunction({
+  name: 'my-plugin:get-version-alt',
+  type: 'static',
+  handler: () => '2.0.0',
+})
+collector.register(getVersionAlt)
+
+// Option 2: Force overwrite
+collector.register(getVersionAlt, true)
+```
+
+## Source
+
+`packages/rpc/src/collector.ts`

docs/errors/DTK0002.md

@@ -0,0 +1,48 @@
+---
+outline: deep
+---
+
+# DTK0002: RPC Function Not Registered (Update)
+
+> Package: `@vitejs/devtools-rpc`
+
+## Message
+
+> RPC function "`{name}`" is not registered. Use register() to add new functions.
+
+## Cause
+
+This error is thrown by `RpcFunctionsCollectorBase.update()` when you attempt to update a function definition that has not been registered yet. The `update()` method is intended for replacing an existing definition, not for adding new ones.
+
+## Example
+
+```ts
+import { defineRpcFunction } from '@vitejs/devtools-kit'
+
+const getVersion = defineRpcFunction({
+  name: 'my-plugin:get-version',
+  type: 'static',
+  handler: () => '2.0.0',
+})
+
+// Throws DTK0002 because 'my-plugin:get-version' was never registered
+collector.update(getVersion)
+```
+
+## Fix
+
+Register the function first with `register()`, then use `update()` for subsequent changes. Alternatively, pass `force: true` to `update()` to allow upserting:
+
+```ts
+// Option 1: Register first, update later
+collector.register(getVersion)
+// ... later ...
+collector.update(getVersionUpdated)
+
+// Option 2: Force update (creates if missing)
+collector.update(getVersion, true)
+```
+
+## Source
+
+`packages/rpc/src/collector.ts`

docs/errors/DTK0003.md

@@ -0,0 +1,51 @@
+---
+outline: deep
+---
+
+# DTK0003: RPC Function Schema Not Found
+
+> Package: `@vitejs/devtools-rpc`
+
+## Message
+
+> RPC function "`{name}`" is not registered
+
+## Cause
+
+This error is thrown by `RpcFunctionsCollectorBase.getSchema()` when you request the argument and return schemas for a function name that does not exist in the collector. The function must be registered before its schema can be queried.
+
+## Example
+
+```ts
+// Throws DTK0003 because 'my-plugin:get-config' was never registered
+const schema = collector.getSchema('my-plugin:get-config')
+```
+
+## Fix
+
+Ensure the function is registered before querying its schema. You can check whether a function exists first using `has()`:
+
+```ts
+import { defineRpcFunction } from '@vitejs/devtools-kit'
+
+const getConfig = defineRpcFunction({
+  name: 'my-plugin:get-config',
+  type: 'query',
+  handler: () => ({ debug: false }),
+})
+
+// Register first
+collector.register(getConfig)
+
+// Now getSchema works
+const schema = collector.getSchema('my-plugin:get-config')
+
+// Or guard with has()
+if (collector.has('my-plugin:get-config')) {
+  const schema = collector.getSchema('my-plugin:get-config')
+}
+```
+
+## Source
+
+`packages/rpc/src/collector.ts`

docs/errors/DTK0004.md

@@ -0,0 +1,76 @@
+---
+outline: deep
+---
+
+# DTK0004: Missing RPC Handler
+
+> Package: `@vitejs/devtools-rpc`
+
+## Message
+
+> Either handler or setup function must be provided for RPC function "`{name}`"
+
+## Cause
+
+This error is thrown by `getRpcHandler()` when an RPC function definition provides neither a `handler` property nor a `setup` function that returns a `handler`. It can occur in two situations:
+
+1. When the collector's proxy tries to resolve a handler for a registered function.
+2. During `dumpFunctions()` when resolving handlers for pre-computation.
+
+Every RPC function must have a way to produce a handler -- either directly via `handler` or lazily via `setup`.
+
+## Example
+
+```ts
+import { defineRpcFunction } from '@vitejs/devtools-kit'
+
+// Missing both handler and setup
+const broken = defineRpcFunction({
+  name: 'my-plugin:broken',
+  type: 'query',
+})
+
+collector.register(broken)
+
+// Throws DTK0004 when the handler is resolved
+await collector.getHandler('my-plugin:broken')
+```
+
+A `setup` function that forgets to return a handler also triggers this error:
+
+```ts
+const alsoMissing = defineRpcFunction({
+  name: 'my-plugin:also-missing',
+  type: 'query',
+  setup: (ctx) => {
+    // Forgot to return { handler: ... }
+    return {}
+  },
+})
+```
+
+## Fix
+
+Provide a `handler` directly, or return one from `setup`:
+
+```ts
+// Option 1: Direct handler
+const getVersion = defineRpcFunction({
+  name: 'my-plugin:get-version',
+  type: 'static',
+  handler: () => '1.0.0',
+})
+
+// Option 2: Handler via setup (useful when you need context)
+const getConfig = defineRpcFunction({
+  name: 'my-plugin:get-config',
+  type: 'query',
+  setup: ctx => ({
+    handler: () => ctx.config,
+  }),
+})
+```
+
+## Source
+
+`packages/rpc/src/handler.ts`

docs/errors/DTK0005.md

@@ -0,0 +1,60 @@
+---
+outline: deep
+---
+
+# DTK0005: Function Not in Dump Store
+
+> Package: `@vitejs/devtools-rpc`
+
+## Message
+
+> Function "`{name}`" not found in dump store
+
+## Cause
+
+This error is thrown by `createClientFromDump()` when you call a function on the dump client that was not included in the definitions passed to `dumpFunctions()`. The dump store only contains entries for functions that were part of the original dump collection, and the client rejects calls to unknown functions.
+
+## Example
+
+```ts
+import { defineRpcFunction } from '@vitejs/devtools-kit'
+import { createClientFromDump, dumpFunctions } from '@vitejs/devtools-rpc'
+
+const getVersion = defineRpcFunction({
+  name: 'my-plugin:get-version',
+  type: 'static',
+  handler: () => '1.0.0',
+})
+
+// Only getVersion is dumped
+const store = await dumpFunctions([getVersion])
+const client = createClientFromDump(store)
+
+// Throws DTK0005 because 'my-plugin:get-config' is not in the store
+await client['my-plugin:get-config']()
+```
+
+## Fix
+
+Include the function in the definitions array passed to `dumpFunctions()`:
+
+```ts
+const getConfig = defineRpcFunction({
+  name: 'my-plugin:get-config',
+  type: 'query',
+  handler: () => ({ debug: false }),
+  dump: { inputs: [[]] },
+})
+
+// Include all needed functions in the dump
+const store = await dumpFunctions([getVersion, getConfig])
+const client = createClientFromDump(store)
+
+// Now both functions work
+await client['my-plugin:get-version']()
+await client['my-plugin:get-config']()
+```
+
+## Source
+
+`packages/rpc/src/dumps.ts`