feat!: bump devframe to v0.4.1, migrate diagnostic handles to callable API

`nostics` 0.2 (via devframe 0.4) drops `.report()` / `.throw()` on diagnostic
handles — each handle is now callable. Rewrite all 23 call sites across kit,
core, and rolldown to the new form, and refresh AGENTS.md, the diagnostics
doc, the kit skill reference, and MIGRATION.md to match.

Author: antfu

AGENTS.md

@@ -125,11 +125,13 @@ Codes are sequential 4-digit numbers per prefix (e.g. `DTK0033`, `RDDT0003`). Ch
    import { diagnostics } from './diagnostics'
 
    // For thrown errors — always prefix with `throw` for TypeScript control flow:
-   throw diagnostics.DTK0033.throw({ name })
+   throw diagnostics.DTK0033({ name })
 
-   // For reported (non-thrown) diagnostics:
-   diagnostics.DTK0033.report({ name })
-   diagnostics.DTK0033.report({ name, cause: error }) // attach cause via params
+   // For reported (non-thrown) diagnostics. The default console method is `warn`;
+   // override with the 2nd-arg reporter options when needed:
+   diagnostics.DTK0033({ name }) // console.warn
+   diagnostics.DTK0033({ name }, { method: 'error' }) // console.error
+   diagnostics.DTK0033({ name, cause: error }) // attach cause via params
    ```
 
 3. **Create a docs page** at `docs/errors/DTK0033.md`:

MIGRATION.md

@@ -50,3 +50,20 @@ These types are no longer re-exported from `@vitejs/devtools-kit`. Import them f
 ```
 
 The `@vitejs/devtools-kit/utils/when` subpath remains and re-exports these types alongside `evaluateWhen` and `resolveContextValue`.
+
+#### Diagnostic handles are callable
+
+`nostics` 0.2 (pulled in via devframe 0.4) drops the `.report()` / `.throw()` methods on diagnostic handles. Each handle is now a callable that builds and emits a diagnostic; prefix with `throw` to raise.
+
+```diff
+- throw ctx.diagnostics.logger.MYP0001.throw({ name })
++ throw ctx.diagnostics.logger.MYP0001({ name })
+
+- ctx.diagnostics.logger.MYP0002.report()
++ ctx.diagnostics.logger.MYP0002()
+
+- ctx.diagnostics.logger.MYP0002.report({ name }, { method: 'error' })
++ ctx.diagnostics.logger.MYP0002({ name }, { method: 'error' })
+```
+
+The payload shape (including `cause`) and the optional reporter-options second argument are unchanged. Apply the same rewrite to typed handles returned from `ctx.diagnostics.defineDiagnostics()`.

devframe

@@ -13,7 +13,8 @@
 interface DevToolsDiagnosticsHost {
   /**
    * Proxy-backed lookup of every registered code by name. Each entry is a
-   * `nostics` handle with `.report()` and `.throw()` methods.
+   * `nostics` `DiagnosticHandle` — a callable that builds a diagnostic and
+   * routes it through registered reporters; prefix with `throw` to raise.
    */
   readonly logger: Record<string, any>
 
@@ -56,7 +57,7 @@ export function MyPlugin(): PluginWithDevTools {
         ctx.diagnostics.register(diagnostics)
 
         // Emit codes through the shared lookup:
-        ctx.diagnostics.logger.MYP0002.report()
+        ctx.diagnostics.logger.MYP0002()
       },
     },
   }
@@ -80,23 +81,26 @@ Each definition supports `why` (string or function returning a string) and an op
 
 ## Emit a diagnostic
 
-Each registered code is reachable as a property on `ctx.diagnostics.logger`. Every handle exposes `.throw(params)` and `.report(params)`.
+Each registered code is reachable as a property on `ctx.diagnostics.logger`. Every handle is a callable — invoke it to report (returns the `Diagnostic`), or prefix with `throw` to raise.
 
 ```ts
 // Throw — control flow stops here
-throw ctx.diagnostics.logger.MYP0001.throw({ name: 'foo' })
+throw ctx.diagnostics.logger.MYP0001({ name: 'foo' })
 
-// Report without throwing (goes through the host's reporter)
-ctx.diagnostics.logger.MYP0002.report()
+// Report without throwing (default console method: `warn`)
+ctx.diagnostics.logger.MYP0002()
+
+// Override the console method per call
+ctx.diagnostics.logger.MYP0002({}, { method: 'error' })
 
 // Attach a `cause` via the params object
-ctx.diagnostics.logger.MYP0001.report({ name: 'foo', cause: error })
+ctx.diagnostics.logger.MYP0001({ name: 'foo', cause: error })
 ```
 
-`.throw()` is typed `never`. Prefix the call with `throw` so TypeScript narrows control flow correctly:
+The callable returns a `Diagnostic` (which extends `Error`). Prefix with `throw` so TypeScript narrows the lines after as unreachable:
 
 ```ts
-throw ctx.diagnostics.logger.MYP0001.throw({ name })
+throw ctx.diagnostics.logger.MYP0001({ name })
 ```
 
 ## Typed handle reference
@@ -115,7 +119,7 @@ const myDiagnostics = ctx.diagnostics.defineDiagnostics({
 ctx.diagnostics.register(myDiagnostics)
 
 // Use the typed handle directly at emit sites
-myDiagnostics.MYP0001.report({ name: 'foo' })
+myDiagnostics.MYP0001({ name: 'foo' })
 ```
 
 Both paths share the formatter and reporter defaults set by the host (ANSI console output).
@@ -135,7 +139,7 @@ Each page covers the message, cause, example, and fix; see any [DTK code page](/
 
 ## When to use what
 
-- **`ctx.diagnostics`** — coded conditions worth looking up: misconfiguration, deprecations, validation failures, internal invariants. Always docs-backed. Often `.throw()`.
+- **`ctx.diagnostics`** — coded conditions worth looking up: misconfiguration, deprecations, validation failures, internal invariants. Always docs-backed. Often `throw`-prefixed.
 - **[`ctx.messages`](./messages)** — user-facing activity surfaces in the DevTools UI: progress indicators, audit results, "URL copied" toasts. Just a message and a level.
 
 Diagnostics target tool authors and CI; messages target the human in front of the DevTools panel.

docs/kit/diagnostics.md

@@ -89,5 +89,5 @@ export async function build(options: BuildOptions) {
     outDir,
   })
 
-  diagnostics.DTK0010.report()
+  diagnostics.DTK0010()
 }

packages/core/src/node/cli-commands.ts

@@ -78,7 +78,7 @@ export async function createDevToolsContext(
       await plugin.devtools?.setup?.(context)
     }
     catch (error) {
-      throw diagnostics.DTK0014.throw({ name: plugin.name, cause: error })
+      throw diagnostics.DTK0014({ name: plugin.name, cause: error })
     }
   }
 

packages/core/src/node/context.ts

@@ -14,10 +14,10 @@ export const docksOnLaunch = defineRpcFunction({
 
         const entry = context.docks.values().find(entry => entry.id === entryId)
         if (!entry) {
-          throw diagnostics.DTK0030.throw({ id: entryId })
+          throw diagnostics.DTK0030({ id: entryId })
         }
         if (entry.type !== 'launcher') {
-          throw diagnostics.DTK0031.throw({ id: entryId })
+          throw diagnostics.DTK0031({ id: entryId })
         }
         try {
           context.docks.update({
@@ -43,7 +43,7 @@ export const docksOnLaunch = defineRpcFunction({
           return result
         }
         catch (error) {
-          diagnostics.DTK0032.report({ id: entryId, cause: error })
+          diagnostics.DTK0032({ id: entryId, cause: error })
           context.docks.update({
             ...entry,
             launcher: {

packages/core/src/node/rpc/internal/docks-on-launch.ts

@@ -15,7 +15,7 @@ export const openInEditor = defineRpcFunction({
 
         // Prevent escaping the workspace root
         if (rel.startsWith('..') || rel.includes('\0')) {
-          throw diagnostics.DTK0028.throw()
+          throw diagnostics.DTK0028()
         }
 
         launchEditor(resolved)

packages/core/src/node/rpc/public/open-in-editor.ts

@@ -15,7 +15,7 @@ export const openInFinder = defineRpcFunction({
 
         // Ensure the path stays within workspace root
         if (rel.startsWith('..') || rel.includes('\0')) {
-          throw diagnostics.DTK0029.throw()
+          throw diagnostics.DTK0029()
         }
 
         await open(resolved)

packages/core/src/node/rpc/public/open-in-finder.ts

@@ -50,7 +50,7 @@ export async function createWsServer(options: CreateWsServerOptions) {
 
   const isClientAuthDisabled = context.mode === 'build' || context.viteConfig.devtools?.config?.clientAuth === false || process.env.VITE_DEVTOOLS_DISABLE_CLIENT_AUTH === 'true'
   if (isClientAuthDisabled) {
-    diagnostics.DTK0008.report()
+    diagnostics.DTK0008()
   }
 
   contextInternal.wsEndpoint = {
@@ -74,10 +74,10 @@ export async function createWsServer(options: CreateWsServerOptions) {
     {
       rpcOptions: {
         onFunctionError(error, name) {
-          diagnostics.DTK0011.report({ name, cause: error })
+          diagnostics.DTK0011({ name, cause: error })
         },
         onGeneralError(error) {
-          diagnostics.DTK0012.report({ cause: error })
+          diagnostics.DTK0012({ cause: error })
         },
         resolver(name, fn) {
           // eslint-disable-next-line ts/no-this-alias
@@ -86,7 +86,7 @@ export async function createWsServer(options: CreateWsServerOptions) {
           // Block unauthorized access to non-anonymous methods
           if (!name.startsWith(ANONYMOUS_SCOPE) && !rpc.$meta.isTrusted) {
             return () => {
-              throw diagnostics.DTK0013.throw({ name, clientId: rpc.$meta.id })
+              throw diagnostics.DTK0013({ name, clientId: rpc.$meta.id })
             }
           }