@nuxt/devtools-kit 3.4.0 → 4.0.0-alpha.10

package/dist/index.mjs

@@ -1,7 +1,116 @@
 import { useNuxt } from '@nuxt/kit';
-import { execa } from 'execa';
+import { x } from 'tinyexec';
+import { defineDiagnostics, createConsoleReporter } from 'nostics';
+export { createConsoleReporter, defineDiagnostics } from '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.`
+  },
+  /** Removed `vscode` module option → `codeServer`. */
+  NDT_DEP_0008: {
+    why: (p) => `\`${p.api}\` is deprecated and its legacy modes are no longer supported.`,
+    fix: (p) => `Use \`${p.replacement}\` instead. The legacy value is ignored rather than partially translated.`
+  },
+  /** `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 = defineDiagnostics({
+  docsBase: diagnosticsDocsBase,
+  reporters: [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 defineDiagnostics({
+    ...options,
+    reporters: options.reporters ?? [createConsoleReporter()]
+  });
+}
+function deprecateWithNuxt(code, params, options) {
+  return deprecate(useNuxt(), code, params, options);
+}
+
+const NUXT_DEVTOOLS_GROUP_ID = "nuxt";
 function addCustomTab(tab, nuxt = 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();
@@ -9,56 +118,67 @@ function addCustomTab(tab, nuxt = useNuxt()) {
   });
 }
 function refreshCustomTabs(nuxt = 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 = 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() {
-    const process2 = execa(
+    const proc = x(
       execaOptions.command,
       execaOptions.args,
       {
-        reject: false,
-        ...execaOptions,
-        env: {
-          COLORS: "true",
-          FORCE_COLOR: "true",
-          ...execaOptions.env,
-          // Force disable Nuxi CLI override
-          __CLI_ARGV__: void 0
+        nodeOptions: {
+          ...execaOptions.nodeOptions,
+          cwd: execaOptions.cwd ?? execaOptions.nodeOptions?.cwd,
+          env: {
+            ...process.env,
+            COLORS: "true",
+            FORCE_COLOR: "true",
+            ...execaOptions.env,
+            ...execaOptions.nodeOptions?.env,
+            __CLI_ARGV__: void 0
+          }
         }
       }
     );
     nuxt.callHook("devtools:terminal:write", { id, data: `> ${[execaOptions.command, ...execaOptions.args || []].join(" ")}
 
 ` });
-    process2.stdout.on("data", (data) => {
+    proc.process?.stdout?.on("data", (data) => {
       nuxt.callHook("devtools:terminal:write", { id, data: data.toString() });
     });
-    process2.stderr.on("data", (data) => {
+    proc.process?.stderr?.on("data", (data) => {
       nuxt.callHook("devtools:terminal:write", { id, data: data.toString() });
     });
-    process2.on("exit", (code) => {
+    proc.process?.on("exit", (code) => {
       if (!restarting) {
         nuxt.callHook("devtools:terminal:write", { id, data: `
-> process terminalated with ${code}
+> process terminated with ${code}
 ` });
         nuxt.callHook("devtools:terminal:exit", { id, code: code || 0 });
       }
     });
-    return process2;
+    return proc;
   }
   register();
   nuxt.hook("close", () => {
     terminate();
   });
-  let process = start();
+  let result = start();
   function restart() {
     restarting = true;
-    process?.kill();
+    result.kill();
     clear();
-    process = start();
+    result = start();
     restarting = false;
   }
   function clear() {
@@ -68,7 +188,7 @@ function startSubprocess(execaOptions, tabOptions, nuxt = useNuxt()) {
   function terminate() {
     restarting = false;
     try {
-      process?.kill();
+      result.kill();
     } catch {
     }
     nuxt.callHook("devtools:terminal:remove", { id });
@@ -82,7 +202,15 @@ function startSubprocess(execaOptions, tabOptions, nuxt = useNuxt()) {
     });
   }
   return {
-    getProcess: () => process,
+    /** @deprecated Use `getResult()` instead */
+    getProcess: () => {
+      deprecate(nuxt, "NDT_DEP_0001", {
+        api: "startSubprocess().getProcess()",
+        replacement: "getResult()"
+      }, { key: id });
+      return result.process;
+    },
+    getResult: () => result,
     terminate,
     restart,
     clear
@@ -97,8 +225,11 @@ function extendServerRpc(namespace, functions, nuxt = useNuxt()) {
 function onDevToolsInitialized(fn, nuxt = useNuxt()) {
   nuxt.hook("devtools:initialized", fn);
 }
+function onDevtoolsReady(fn, nuxt = useNuxt()) {
+  nuxt.hook("devtools:ready", fn);
+}
 function _getContext(nuxt = useNuxt()) {
   return nuxt?.devtools;
 }
 
-export { addCustomTab, extendServerRpc, onDevToolsInitialized, refreshCustomTabs, startSubprocess };
+export { NUXT_DEVTOOLS_GROUP_ID, addCustomTab, consoleDiagnostics, defineStandaloneDiagnostics, deprecate, deprecateWithNuxt, diagnosticCodes, diagnosticsDocsBase, extendServerRpc, onDevToolsInitialized, onDevtoolsReady, refreshCustomTabs, registerHostDiagnostics, startSubprocess };

package/dist/runtime/iframe-client.d.ts

@@ -1,4 +1,22 @@
+import type { DevToolsRpcClient } from '@vitejs/devtools-kit/client';
 import type { Ref } from 'vue';
 import type { NuxtDevtoolsIframeClient } from '../types';
 export declare function onDevtoolsClientConnected(fn: (client: NuxtDevtoolsIframeClient) => void): (() => void) | undefined;
+/**
+ * Run a callback once the Vite DevTools client is ready, receiving the connected
+ * `DevToolsRpcClient` — the client-side mirror of the server's
+ * `onDevtoolsReady((ctx) => …)`.
+ *
+ * This is the recommended way to do client-side DevTools integration (register
+ * client RPC functions, call server functions, shared state, streaming, …):
+ *
+ * ```ts
+ * import { onDevtoolsReady } from '@nuxt/devtools-kit/iframe-client'
+ *
+ * onDevtoolsReady((kit) => {
+ *   kit.client.register({ name: 'my-module:on-update', type: 'event', handler })
+ * })
+ * ```
+ */
+export declare function onDevtoolsReady(fn: (kit: DevToolsRpcClient) => void): (() => void) | undefined;
 export declare function useDevtoolsClient(): Ref<NuxtDevtoolsIframeClient | undefined, NuxtDevtoolsIframeClient | undefined>;

package/dist/runtime/iframe-client.mjs

@@ -25,6 +25,13 @@ export function onDevtoolsClientConnected(fn) {
     fns.splice(fns.indexOf(fn), 1);
   };
 }
+export function onDevtoolsReady(fn) {
+  return onDevtoolsClientConnected((client) => {
+    const kit = client.devtools.devtoolsKit;
+    if (kit)
+      fn(kit);
+  });
+}
 export function useDevtoolsClient() {
   if (!clientRef) {
     clientRef = shallowRef();