@nuxt/devtools-kit 4.0.0-alpha.7 → 4.0.0-alpha.8

package/dist/index.cjs

@@ -2,8 +2,112 @@
 
 const kit = require('@nuxt/kit');
 const tinyexec = require('tinyexec');
+const nostics = require('nostics');
 
+function diagnosticsDocsBase(code) {
+  return `https://devtools.nuxt.com/module/migration-v4#${String(code).toLowerCase()}`;
+}
+const diagnosticCodes = {
+  /** `startSubprocess().getProcess()` → `getResult()`. */
+  NDT_DEP_0001: {
+    why: (p) => `\`${p.api}\` is deprecated.`,
+    fix: (p) => `Use \`${p.replacement}\` instead.`
+  },
+  // NDT_DEP_0002 is retired (was `disableAuthorization`, now a supported
+  // first-class option). The code is left unused so numbers stay stable.
+  /** `extendServerRpc` → `onDevtoolsReady((ctx) => ctx.rpc.register(...))`. */
+  NDT_DEP_0003: {
+    why: (p) => `\`${p.api}\` is deprecated.`,
+    fix: (p) => `Use \`${p.replacement}\` instead.`
+  },
+  /** `startSubprocess` → `onDevtoolsReady((ctx) => ctx.terminals.startChildProcess(...))`. */
+  NDT_DEP_0004: {
+    why: (p) => `\`${p.api}\` is deprecated.`,
+    fix: (p) => `Use \`${p.replacement}\` instead.`
+  },
+  /** `addCustomTab` → `onDevtoolsReady((ctx) => ctx.docks.register(...))`. */
+  NDT_DEP_0005: {
+    why: (p) => `\`${p.api}\` is deprecated.`,
+    fix: (p) => `Use \`${p.replacement}\` instead.`
+  },
+  /** `refreshCustomTabs` → `onDevtoolsReady((ctx) => ctx.docks.register(...))`. */
+  NDT_DEP_0006: {
+    why: (p) => `\`${p.api}\` is deprecated.`,
+    fix: (p) => `Use \`${p.replacement}\` instead.`
+  },
+  /** Direct `nuxt.devtools.rpc` access (`broadcast` / `functions`). */
+  NDT_DEP_0007: {
+    why: (p) => `\`${p.api}\` is deprecated.`,
+    fix: (p) => `Use \`${p.replacement}\` instead.`
+  },
+  // NDT_DEP_0008 is reserved for the removed `vscode` module option.
+  /** `getServerData()` RPC → the Data Inspector panel's `Nuxt Application` source. */
+  NDT_DEP_0009: {
+    why: (p) => `\`${p.api}\` is deprecated.`,
+    fix: (p) => `Use \`${p.replacement}\` instead.`
+  }
+};
+const consoleDiagnostics = nostics.defineDiagnostics({
+  docsBase: diagnosticsDocsBase,
+  reporters: [nostics.createConsoleReporter()],
+  codes: diagnosticCodes
+});
+const stateByCtx = /* @__PURE__ */ new WeakMap();
+const fallbackState = { emitted: /* @__PURE__ */ new Set() };
+function getState(ctx) {
+  if (!ctx)
+    return fallbackState;
+  let state = stateByCtx.get(ctx);
+  if (!state) {
+    state = { emitted: /* @__PURE__ */ new Set() };
+    stateByCtx.set(ctx, state);
+  }
+  return state;
+}
+function getServerContext(nuxt) {
+  return nuxt?.devtools;
+}
+function registerHostDiagnostics(ctx) {
+  const host = ctx.devtoolsKit?.diagnostics;
+  if (!host)
+    return;
+  const catalog = host.defineDiagnostics({
+    docsBase: diagnosticsDocsBase,
+    codes: diagnosticCodes
+  });
+  host.register(catalog);
+  getState(ctx).hostCatalog = catalog;
+}
+function deprecate(nuxt, code, params, options = {}) {
+  const ctx = getServerContext(nuxt);
+  const state = getState(ctx);
+  const dedupeKey = `${code}:${options.key ?? code}`;
+  if (state.emitted.has(dedupeKey))
+    return;
+  state.emitted.add(dedupeKey);
+  const method = options.method ?? "warn";
+  const hostHandle = state.hostCatalog?.[code];
+  if (hostHandle)
+    return hostHandle(params, { method });
+  const handle = consoleDiagnostics[code];
+  return handle(params, { method });
+}
+function defineStandaloneDiagnostics(options) {
+  return nostics.defineDiagnostics({
+    ...options,
+    reporters: options.reporters ?? [nostics.createConsoleReporter()]
+  });
+}
+function deprecateWithNuxt(code, params, options) {
+  return deprecate(kit.useNuxt(), code, params, options);
+}
+
+const NUXT_DEVTOOLS_GROUP_ID = "nuxt";
 function addCustomTab(tab, nuxt = kit.useNuxt()) {
+  deprecate(nuxt, "NDT_DEP_0005", {
+    api: "addCustomTab",
+    replacement: "onDevtoolsReady((ctx) => ctx.docks.register(...))"
+  }, { key: typeof tab === "function" ? void 0 : tab.name });
   nuxt.hook("devtools:customTabs", async (tabs) => {
     if (typeof tab === "function")
       tab = await tab();
@@ -11,9 +115,17 @@ function addCustomTab(tab, nuxt = kit.useNuxt()) {
   });
 }
 function refreshCustomTabs(nuxt = kit.useNuxt()) {
+  deprecate(nuxt, "NDT_DEP_0006", {
+    api: "refreshCustomTabs",
+    replacement: "onDevtoolsReady((ctx) => ctx.docks.register(...).update(...))"
+  });
   return nuxt.callHook("devtools:customTabs:refresh");
 }
 function startSubprocess(execaOptions, tabOptions, nuxt = kit.useNuxt()) {
+  deprecate(nuxt, "NDT_DEP_0004", {
+    api: "startSubprocess",
+    replacement: "onDevtoolsReady((ctx) => ctx.terminals.startChildProcess(...))"
+  }, { key: tabOptions.id });
   const id = tabOptions.id;
   let restarting = false;
   function start() {
@@ -89,7 +201,10 @@ function startSubprocess(execaOptions, tabOptions, nuxt = kit.useNuxt()) {
   return {
     /** @deprecated Use `getResult()` instead */
     getProcess: () => {
-      console.warn("[nuxt-devtools] `getProcess()` is deprecated, use `getResult()` instead.");
+      deprecate(nuxt, "NDT_DEP_0001", {
+        api: "startSubprocess().getProcess()",
+        replacement: "getResult()"
+      }, { key: id });
       return result.process;
     },
     getResult: () => result,
@@ -107,12 +222,26 @@ function extendServerRpc(namespace, functions, nuxt = kit.useNuxt()) {
 function onDevToolsInitialized(fn, nuxt = kit.useNuxt()) {
   nuxt.hook("devtools:initialized", fn);
 }
+function onDevtoolsReady(fn, nuxt = kit.useNuxt()) {
+  nuxt.hook("devtools:ready", fn);
+}
 function _getContext(nuxt = kit.useNuxt()) {
   return nuxt?.devtools;
 }
 
+exports.createConsoleReporter = nostics.createConsoleReporter;
+exports.defineDiagnostics = nostics.defineDiagnostics;
+exports.NUXT_DEVTOOLS_GROUP_ID = NUXT_DEVTOOLS_GROUP_ID;
 exports.addCustomTab = addCustomTab;
+exports.consoleDiagnostics = consoleDiagnostics;
+exports.defineStandaloneDiagnostics = defineStandaloneDiagnostics;
+exports.deprecate = deprecate;
+exports.deprecateWithNuxt = deprecateWithNuxt;
+exports.diagnosticCodes = diagnosticCodes;
+exports.diagnosticsDocsBase = diagnosticsDocsBase;
 exports.extendServerRpc = extendServerRpc;
 exports.onDevToolsInitialized = onDevToolsInitialized;
+exports.onDevtoolsReady = onDevtoolsReady;
 exports.refreshCustomTabs = refreshCustomTabs;
+exports.registerHostDiagnostics = registerHostDiagnostics;
 exports.startSubprocess = startSubprocess;

package/dist/index.d.cts

@@ -1,44 +1,266 @@
 import * as _nuxt_schema from '@nuxt/schema';
+import { ViteDevToolsNodeContext } from '@vitejs/devtools-kit';
 import { BirpcGroup } from 'birpc';
 import { ChildProcess } from 'node:child_process';
 import { Result } from 'tinyexec';
-import { r as ModuleCustomTab, O as NuxtDevtoolsInfo, a4 as SubprocessOptions, a9 as TerminalState } from './shared/devtools-kit.BwQLAI1z.cjs';
+import { N as NuxtDevtoolsServerContext, M as ModuleCustomTab, a as NuxtDevtoolsInfo, S as SubprocessOptions, T as TerminalState } from './shared/devtools-kit.CC-eVeXW.cjs';
+import * as nostics from 'nostics';
+import { defineDiagnostics } from 'nostics';
+export { createConsoleReporter, defineDiagnostics } from 'nostics';
+import { Nuxt } from 'nuxt/schema';
 import 'vue';
-import '@vitejs/devtools-kit';
-import 'nuxt/schema';
 import 'unimport';
 import 'vue-router';
 import 'nitropack';
 import 'unstorage';
 import 'vite';
 
+/**
+ * Canonical docs URL for a Nuxt DevTools diagnostic code.
+ *
+ * Each code links to a per-code anchor in the v4 migration guide, e.g.
+ * `NDT_DEP_0001` → `.../module/migration-v4#ndt_dep_0001`.
+ */
+declare function diagnosticsDocsBase(code: string | number): string;
+/**
+ * Parameters shared by every deprecation code: the API being used and its
+ * recommended replacement. Interpolated into the `why`/`fix` messages.
+ */
+interface DeprecationParams {
+    /** The deprecated API / option being used. */
+    api: string;
+    /** The recommended replacement to migrate to. */
+    replacement: string;
+}
+/**
+ * The Nuxt DevTools diagnostics catalog.
+ *
+ * Codes are grouped by prefix:
+ * - `NDT_DEP_xxxx` — soft/hard deprecations (this is the only range used today).
+ *
+ * Severity is **not** encoded here; it is chosen per emission via the reporter
+ * `method` (`warn` by default, `error` for hard breaks).
+ */
+declare const diagnosticCodes: {
+    /** `startSubprocess().getProcess()` → `getResult()`. */
+    NDT_DEP_0001: {
+        why: (p: DeprecationParams) => string;
+        fix: (p: DeprecationParams) => string;
+    };
+    /** `extendServerRpc` → `onDevtoolsReady((ctx) => ctx.rpc.register(...))`. */
+    NDT_DEP_0003: {
+        why: (p: DeprecationParams) => string;
+        fix: (p: DeprecationParams) => string;
+    };
+    /** `startSubprocess` → `onDevtoolsReady((ctx) => ctx.terminals.startChildProcess(...))`. */
+    NDT_DEP_0004: {
+        why: (p: DeprecationParams) => string;
+        fix: (p: DeprecationParams) => string;
+    };
+    /** `addCustomTab` → `onDevtoolsReady((ctx) => ctx.docks.register(...))`. */
+    NDT_DEP_0005: {
+        why: (p: DeprecationParams) => string;
+        fix: (p: DeprecationParams) => string;
+    };
+    /** `refreshCustomTabs` → `onDevtoolsReady((ctx) => ctx.docks.register(...))`. */
+    NDT_DEP_0006: {
+        why: (p: DeprecationParams) => string;
+        fix: (p: DeprecationParams) => string;
+    };
+    /** Direct `nuxt.devtools.rpc` access (`broadcast` / `functions`). */
+    NDT_DEP_0007: {
+        why: (p: DeprecationParams) => string;
+        fix: (p: DeprecationParams) => string;
+    };
+    /** `getServerData()` RPC → the Data Inspector panel's `Nuxt Application` source. */
+    NDT_DEP_0009: {
+        why: (p: DeprecationParams) => string;
+        fix: (p: DeprecationParams) => string;
+    };
+};
+type NuxtDiagnosticCode = keyof typeof diagnosticCodes;
+/**
+ * Standalone catalog that prints to the terminal via nostics'
+ * {@link createConsoleReporter} (default method `warn`). Works before the Vite
+ * DevTools kit connects, so it is the fallback sink for pre-connect emissions.
+ */
+declare const consoleDiagnostics: nostics.Diagnostics<{
+    /** `startSubprocess().getProcess()` → `getResult()`. */
+    NDT_DEP_0001: {
+        why: (p: DeprecationParams) => string;
+        fix: (p: DeprecationParams) => string;
+    };
+    /** `extendServerRpc` → `onDevtoolsReady((ctx) => ctx.rpc.register(...))`. */
+    NDT_DEP_0003: {
+        why: (p: DeprecationParams) => string;
+        fix: (p: DeprecationParams) => string;
+    };
+    /** `startSubprocess` → `onDevtoolsReady((ctx) => ctx.terminals.startChildProcess(...))`. */
+    NDT_DEP_0004: {
+        why: (p: DeprecationParams) => string;
+        fix: (p: DeprecationParams) => string;
+    };
+    /** `addCustomTab` → `onDevtoolsReady((ctx) => ctx.docks.register(...))`. */
+    NDT_DEP_0005: {
+        why: (p: DeprecationParams) => string;
+        fix: (p: DeprecationParams) => string;
+    };
+    /** `refreshCustomTabs` → `onDevtoolsReady((ctx) => ctx.docks.register(...))`. */
+    NDT_DEP_0006: {
+        why: (p: DeprecationParams) => string;
+        fix: (p: DeprecationParams) => string;
+    };
+    /** Direct `nuxt.devtools.rpc` access (`broadcast` / `functions`). */
+    NDT_DEP_0007: {
+        why: (p: DeprecationParams) => string;
+        fix: (p: DeprecationParams) => string;
+    };
+    /** `getServerData()` RPC → the Data Inspector panel's `Nuxt Application` source. */
+    NDT_DEP_0009: {
+        why: (p: DeprecationParams) => string;
+        fix: (p: DeprecationParams) => string;
+    };
+}, readonly [nostics.DiagnosticReporter<{
+    method?: nostics.ConsoleMethod;
+}>]>;
+/**
+ * Register the Nuxt deprecation codes into the connected Vite DevTools kit's
+ * diagnostics host so they are known to DevTools and post-connect emissions
+ * surface in the DevTools diagnostics UI. Safe to call when no host is present.
+ *
+ * Called from `connectDevToolsKit`.
+ */
+declare function registerHostDiagnostics(ctx: NuxtDevtoolsServerContext): void;
+/**
+ * Options for {@link deprecate}.
+ */
+interface DeprecateOptions {
+    /**
+     * Dedupe key appended to the code. Defaults to the code itself, i.e. the
+     * deprecation warns once per process. Pass a finer key (e.g. a subprocess id)
+     * to warn once per distinct call site instead.
+     */
+    key?: string;
+    /**
+     * Reporter method / severity. `warn` (default) for soft deprecations, `error`
+     * for hard breaks. The returned {@link Diagnostic} can be thrown to abort.
+     */
+    method?: 'warn' | 'error';
+}
+/**
+ * Emit a Nuxt DevTools deprecation diagnostic.
+ *
+ * Routing: when the Vite DevTools kit is connected the emission goes through the
+ * DevTools host catalog (terminal **and** the DevTools diagnostics UI); before
+ * connect it falls back to the terminal-only console catalog. A single emission
+ * per call — no double printing.
+ *
+ * Deduped per `${code}:${key ?? code}` on the resolved server context, so a hot
+ * path warns only once.
+ *
+ * @returns the built `Diagnostic` (which extends `Error`, so it can be thrown
+ * for hard breaks), or `undefined` if the emission was deduped.
+ */
+declare function deprecate(nuxt: Nuxt, code: NuxtDiagnosticCode, params: DeprecationParams, options?: DeprecateOptions): Error | undefined;
+/**
+ * Build a standalone nostics catalog that prints to the terminal.
+ *
+ * Used by the connect-safe `nuxt.devtools.diagnostics` accessor so module
+ * authors can define + emit diagnostics before the Vite DevTools kit connects.
+ * A `createConsoleReporter()` is added automatically unless the caller supplies
+ * its own `reporters`.
+ */
+declare function defineStandaloneDiagnostics(options: Parameters<typeof defineDiagnostics>[0]): ReturnType<typeof defineDiagnostics>;
+/**
+ * Convenience wrapper for call sites that don't already hold the Nuxt instance.
+ */
+declare function deprecateWithNuxt(code: NuxtDiagnosticCode, params: DeprecationParams, options?: DeprecateOptions): Error | undefined;
+
+/**
+ * The public `Nuxt` dock group id registered on the Vite DevTools framework
+ * category. Module authors join the group natively by pointing their own
+ * dock entries at it — no special Nuxt API required:
+ *
+ * @example
+ * ```ts
+ * import { NUXT_DEVTOOLS_GROUP_ID, onDevtoolsReady } from '@nuxt/devtools-kit'
+ *
+ * onDevtoolsReady((ctx) => {
+ *   ctx.docks.register({
+ *     id: 'my-module',
+ *     type: 'iframe',
+ *     title: 'My Module',
+ *     icon: 'i-ph-puzzle-piece',
+ *     url: '/my-module/',
+ *     groupId: NUXT_DEVTOOLS_GROUP_ID,
+ *   })
+ * })
+ * ```
+ */
+declare const NUXT_DEVTOOLS_GROUP_ID = "nuxt";
 /**
  * Hooks to extend a custom tab in devtools.
  *
  * Provide a function to pass a factory that can be updated dynamically.
+ *
+ * @deprecated Register a dock entry from the `devtools:ready` hook instead:
+ * `onDevtoolsReady((ctx) => ctx.docks.register(...))`. Still works as a shim, but
+ * emits the `NDT_DEP_0005` deprecation diagnostic. Note the docks host does not
+ * yet cover `vnode` views or tab categories.
  */
 declare function addCustomTab(tab: ModuleCustomTab | (() => ModuleCustomTab | Promise<ModuleCustomTab>), nuxt?: _nuxt_schema.Nuxt): void;
 /**
  * Retrigger update for custom tabs, `devtools:customTabs` will be called again.
+ *
+ * @deprecated Update dock entries directly via the handle returned by
+ * `ctx.docks.register(...)` inside the `devtools:ready` hook. Still works as a
+ * shim, but emits the `NDT_DEP_0006` deprecation diagnostic.
  */
 declare function refreshCustomTabs(nuxt?: _nuxt_schema.Nuxt): void | Promise<any>;
-/**
- * Create a subprocess that handled by the DevTools.
- */
-declare function startSubprocess(execaOptions: SubprocessOptions, tabOptions: TerminalState, nuxt?: _nuxt_schema.Nuxt): {
+interface StartSubprocessReturn {
     /** @deprecated Use `getResult()` instead */
     getProcess: () => ChildProcess | undefined;
     getResult: () => Result;
     terminate: () => void;
     restart: () => void;
     clear: () => void;
-};
+}
+/**
+ * Create a subprocess that handled by the DevTools.
+ *
+ * @deprecated Use the Vite DevTools terminals host from the `devtools:ready`
+ * hook instead: `onDevtoolsReady((ctx) => ctx.terminals.startChildProcess(...))`.
+ * Still works as a shim, but emits the `NDT_DEP_0004` deprecation diagnostic.
+ */
+declare function startSubprocess(execaOptions: SubprocessOptions, tabOptions: TerminalState, nuxt?: _nuxt_schema.Nuxt): StartSubprocessReturn;
 /**
  * Extend server RPC with namespaced functions.
  *
  * Returns an object with a `broadcast` proxy for calling client functions.
+ *
+ * @deprecated Register RPC functions from the `devtools:ready` hook instead:
+ * `onDevtoolsReady((ctx) => ctx.rpc.register(defineRpcFunction(...)))`. Still
+ * works as a shim, but emits the `NDT_DEP_0003` deprecation diagnostic.
  */
 declare function extendServerRpc<ClientFunctions extends object = Record<string, unknown>, ServerFunctions extends object = Record<string, unknown>>(namespace: string, functions: ServerFunctions, nuxt?: _nuxt_schema.Nuxt): BirpcGroup<ClientFunctions, ServerFunctions>;
 declare function onDevToolsInitialized(fn: (info: NuxtDevtoolsInfo) => void, nuxt?: _nuxt_schema.Nuxt): void;
+/**
+ * Run a callback once the Vite DevTools kit has connected, receiving the
+ * connected `ViteDevToolsNodeContext`.
+ *
+ * This is the recommended entry point for DevTools integration: the kit is
+ * guaranteed available, so you can use `ctx.docks` / `ctx.terminals` /
+ * `ctx.messages` / `ctx.commands` / `ctx.rpc` / `ctx.diagnostics` directly
+ * without the connect-safe accessors on `nuxt.devtools`.
+ *
+ * @example
+ * ```ts
+ * onDevtoolsReady((ctx) => {
+ *   ctx.docks.register({ id: 'my-module', title: 'My Module', type: 'iframe', url: '/…' })
+ * })
+ * ```
+ */
+declare function onDevtoolsReady(fn: (ctx: ViteDevToolsNodeContext) => void | Promise<void>, nuxt?: _nuxt_schema.Nuxt): void;
 
-export { addCustomTab, extendServerRpc, onDevToolsInitialized, refreshCustomTabs, startSubprocess };
+export { NUXT_DEVTOOLS_GROUP_ID, addCustomTab, consoleDiagnostics, defineStandaloneDiagnostics, deprecate, deprecateWithNuxt, diagnosticCodes, diagnosticsDocsBase, extendServerRpc, onDevToolsInitialized, onDevtoolsReady, refreshCustomTabs, registerHostDiagnostics, startSubprocess };
+export type { DeprecateOptions, DeprecationParams, NuxtDiagnosticCode, StartSubprocessReturn };