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

package/dist/shared/{devtools-kit.BwQLAI1z.d.mts → devtools-kit.Do7_fnKq.d.mts}

@@ -1,7 +1,7 @@
+import { DevToolsMessageLevel, DevToolsMessageFilePosition, ViteDevToolsNodeContext } from '@vitejs/devtools-kit';
 import { VNode, MaybeRefOrGetter } from 'vue';
-import { DevToolsNodeContext } from '@vitejs/devtools-kit';
 import { BirpcGroup } from 'birpc';
-import { Component, NuxtOptions, NuxtPage, NuxtLayout, NuxtApp, NuxtDebugModuleMutationRecord, Nuxt } from 'nuxt/schema';
+import { Component, NuxtOptions, NuxtPage, NuxtLayout, NuxtApp, Nuxt, NuxtDebugModuleMutationRecord } from 'nuxt/schema';
 import { Import, UnimportMeta } from 'unimport';
 import { RouteRecordNormalized } from 'vue-router';
 import { Nitro, StorageMounts } from 'nitropack';
@@ -130,6 +130,7 @@ interface ModuleBuiltinTab {
     title?: string;
     path?: string;
     category?: TabCategory;
+    defaultOrder?: number;
     show?: () => MaybeRefOrGetter<any>;
     badge?: () => MaybeRefOrGetter<number | string | undefined>;
     onClick?: () => void;
@@ -137,6 +138,51 @@ interface ModuleBuiltinTab {
 type ModuleTabInfo = ModuleCustomTab | ModuleBuiltinTab;
 type CategorizedTabs = [TabCategory, (ModuleCustomTab | ModuleBuiltinTab)[]][];
 
+/**
+ * Severity level of a notification, mirroring devframe's message levels.
+ *
+ * Determines the color/icon of the entry in the Vite DevTools **Messages** dock
+ * and its toast.
+ */
+type NuxtDevtoolsNotifyLevel = DevToolsMessageLevel;
+/**
+ * A Nuxt-friendly subset of devframe's `DevframeMessageEntryInput`.
+ *
+ * This is the input accepted by the `devtools:notify` Nuxt hook, the `notify`
+ * RPC function and the injected client's `notify()` — all of which forward to
+ * the connected `ctx.messages` host so notifications flow through the single
+ * devframe Messages system (persistent dock list + toast overlay).
+ *
+ * Tiers are expressed through the flags below:
+ * - **Ephemeral** (toast-only feedback like "Copied!"): `notify: true` with an
+ *   `autoDismiss` (toast lifetime) and `autoDelete` (entry lifetime) so it never
+ *   builds up history in the Messages dock.
+ * - **Persistent** (server-originated, leveled): omit `autoDelete` so the entry
+ *   is kept in the Messages dock list.
+ */
+interface NuxtDevtoolsNotifyInput {
+    /** Short title / summary of the message. */
+    message: string;
+    /** Severity level. Defaults to `'info'`. */
+    level?: NuxtDevtoolsNotifyLevel;
+    /** Optional detailed description or explanation. */
+    description?: string;
+    /** Optional tags/labels for filtering in the Messages dock. */
+    labels?: string[];
+    /** Optional grouping category (e.g. `'build'`, `'lint'`, `'runtime'`). */
+    category?: string;
+    /** Optional source file position (e.g. for a build/lint error). */
+    filePosition?: DevToolsMessageFilePosition;
+    /** Optional stack trace string. */
+    stacktrace?: string;
+    /** Whether this message should also appear as a transient toast. */
+    notify?: boolean;
+    /** Time in ms to auto-dismiss the toast (client-side). */
+    autoDismiss?: number;
+    /** Time in ms to auto-delete the entry from the persistent list (server-side). */
+    autoDelete?: number;
+}
+
 interface HookInfo {
     name: string;
     start: number;
@@ -338,13 +384,8 @@ interface ComponentWithRelationships {
     dependencies?: string[];
     dependents?: string[];
 }
-interface CodeServerOptions {
-    codeBinary: string;
-    launchArg: string;
-    licenseTermsArg: string;
-    connectionTokenArg: string;
-}
 
+/** @deprecated Part of the removed `vscode` integration. */
 type CodeServerType = 'ms-code-cli' | 'ms-code-server' | 'coder-code-server';
 interface ModuleOptions {
     /**
@@ -359,8 +400,12 @@ interface ModuleOptions {
      * This is in static format, for dynamic injection, call `nuxt.hook('devtools:customTabs')` instead
      */
     customTabs?: ModuleCustomTab[];
+    /** Code Server integration options. */
+    codeServer?: CodeServerIntegrationOptions;
     /**
-     * VS Code Server integration options.
+     * Legacy VS Code Server integration options.
+     *
+     * @deprecated Use `codeServer`. Legacy modes are no longer supported.
      */
     vscode?: VSCodeIntegrationOptions;
     /**
@@ -380,7 +425,14 @@ interface ModuleOptions {
      */
     viteInspect?: boolean;
     /**
-     * @deprecated Auth is now handled by Vite DevTools. This option is ignored.
+     * Disable the DevTools client authorization prompt, allowing any browser to
+     * connect without approving it first.
+     *
+     * Defaults to `true` in sandboxed environments (StackBlitz, CodeSandbox).
+     *
+     * Note: disabling authorization lets any browser (including other devices, if
+     * you expose the dev server to your LAN/WAN) connect to DevTools and access
+     * your server and filesystem. Only disable it in trusted environments.
      */
     disableAuthorization?: boolean;
     /**
@@ -442,6 +494,31 @@ interface ModuleOptions {
      */
     telemetry?: boolean;
 }
+interface CodeServerIntegrationOptions {
+    /**
+     * Enable the Code Server integration.
+     *
+     * @default true
+     */
+    enabled?: boolean;
+    /** Path or command name for Coder's `code-server` binary. */
+    bin?: string;
+    /** Workspace opened by Code Server. Defaults to the Nuxt root directory. */
+    cwd?: string;
+    /** Port for the Code Server process. Defaults to the plugin's free-port behavior. */
+    serverPort?: number;
+    /** Host for the Code Server process. Defaults to the plugin's loopback host. */
+    host?: string;
+    /** Additional safe arguments passed to `code-server`. */
+    args?: string[];
+    /** Additional safe environment variables passed to `code-server`. */
+    env?: Record<string, string>;
+    /** Suffix used to isolate the authenticated Code Server session cookie. */
+    cookieSuffix?: string;
+    /** Milliseconds to wait for Code Server to become ready. */
+    startTimeout?: number;
+}
+/** @deprecated Use {@link CodeServerIntegrationOptions}. */
 interface VSCodeIntegrationOptions {
     /**
      * Enable VS Code Server integration
@@ -487,6 +564,7 @@ interface VSCodeIntegrationOptions {
      */
     host?: string;
 }
+/** @deprecated Tunnels are not supported by the Code Server integration. */
 interface VSCodeTunnelOptions {
     /**
      * the machine name for port forwarding service
@@ -509,13 +587,10 @@ interface NuxtDevToolsOptions {
         componentsView: 'list' | 'graph';
         hiddenTabCategories: string[];
         hiddenTabs: string[];
-        interactionCloseOnOutsideClick: boolean;
         pinnedTabs: string[];
         scale: number;
         showExperimentalFeatures: boolean;
         showHelpButtons: boolean;
-        sidebarExpanded: boolean;
-        sidebarScrollable: boolean;
     };
     serverRoutes: {
         selectedRoute: ServerRouteInfo | null;
@@ -547,55 +622,23 @@ interface AnalyzeBuildMeta extends NuxtAnalyzeMeta {
 }
 interface AnalyzeBuildsInfo {
     isBuilding: boolean;
-    builds: AnalyzeBuildMeta[];
-}
-
-interface TerminalBase {
-    id: string;
-    name: string;
-    description?: string;
-    icon?: string;
-}
-type TerminalAction = 'restart' | 'terminate' | 'clear' | 'remove';
-interface SubprocessOptions {
-    command: string;
-    args?: string[];
-    cwd?: string;
-    env?: Record<string, string | undefined>;
-    nodeOptions?: SpawnOptions;
-}
-interface TerminalInfo extends TerminalBase {
     /**
-     * Whether the terminal can be restarted
+     * Unique id of the terminal session for the build currently in flight, or
+     * `undefined` when idle. The client reveals this session and derives its
+     * "Building…" state from it instead of an `onTerminalExit` broadcast.
      */
-    restartable?: boolean;
-    /**
-     * Whether the terminal can be terminated
-     */
-    terminatable?: boolean;
-    /**
-     * Whether the terminal is terminated
-     */
-    isTerminated?: boolean;
-    /**
-     * Content buffer
-     */
-    buffer?: string;
-}
-interface TerminalState extends TerminalInfo {
-    /**
-     * User action to restart the terminal, when not provided, this action will be disabled
-     */
-    onActionRestart?: () => Promise<void> | void;
-    /**
-     * User action to terminate the terminal, when not provided, this action will be disabled
-     */
-    onActionTerminate?: () => Promise<void> | void;
+    activeSessionId?: string;
+    builds: AnalyzeBuildMeta[];
 }
 
 interface ServerFunctions {
     getServerConfig: () => NuxtOptions;
     getServerDebugContext: () => Promise<ServerDebugContext | undefined>;
+    /**
+     * @deprecated Replaced by the Data Inspector panel's live `Nuxt Application`
+     * source. Kept as a compatibility shim (emits `NDT_DEP_0009`) for one
+     * migration window and will be removed in a future major.
+     */
     getServerData: () => Promise<NuxtServerData>;
     getServerRuntimeConfig: () => Record<string, any>;
     getModuleOptions: () => ModuleOptions;
@@ -618,9 +661,7 @@ interface ServerFunctions {
     runNpmCommand: (command: NpmCommandType, packageName: string, options?: NpmCommandOptions) => Promise<{
         processId: string;
     } | undefined>;
-    getTerminals: () => TerminalInfo[];
-    getTerminalDetail: (id: string) => Promise<TerminalInfo | undefined>;
-    runTerminalAction: (id: string, action: TerminalAction) => Promise<boolean>;
+    revealTerminal: (id: string) => Promise<boolean>;
     getStorageMounts: () => Promise<StorageMounts>;
     getStorageKeys: (base?: string) => Promise<string[]>;
     getStorageItem: (key: string) => Promise<StorageValue>;
@@ -635,13 +676,14 @@ interface ServerFunctions {
     writeStaticAssets: (file: AssetEntry[], folder: string) => Promise<string[]>;
     deleteStaticAsset: (filepath: string) => Promise<void>;
     renameStaticAsset: (oldPath: string, newPath: string) => Promise<void>;
+    notify: (input: NuxtDevtoolsNotifyInput) => Promise<void>;
     telemetryEvent: (payload: object, immediate?: boolean) => void;
     customTabAction: (name: string, action: number) => Promise<boolean>;
     enablePages: () => Promise<void>;
     openInEditor: (filepath: string) => Promise<boolean>;
     restartNuxt: (hard?: boolean) => Promise<void>;
-    installNuxtModule: (name: string, dry?: boolean) => Promise<InstallModuleReturn>;
-    uninstallNuxtModule: (name: string, dry?: boolean) => Promise<InstallModuleReturn>;
+    installNuxtModule: (name: string, dry?: boolean, sessionId?: string) => Promise<InstallModuleReturn>;
+    uninstallNuxtModule: (name: string, dry?: boolean, sessionId?: string) => Promise<InstallModuleReturn>;
     enableTimeline: (dry: boolean) => Promise<[string, string]>;
     requestForAuth: (info?: string, origin?: string) => Promise<void>;
     verifyAuthToken: () => Promise<boolean>;
@@ -650,15 +692,23 @@ interface ClientFunctions {
     refresh: (event: ClientUpdateEvent) => void;
     callHook: (hook: string, ...args: any[]) => Promise<void>;
     navigateTo: (path: string) => void;
-    onTerminalData: (_: {
-        id: string;
-        data: string;
-    }) => void;
+    /**
+     * Minimal server→client completion signal for generic package updates only
+     * (`runNpmCommand`): the run RPC returns before the process exits, so this
+     * lets `usePackageUpdate` and the restart prompt settle once it finishes. It
+     * carries only `{ id, code }` and is not a terminal-data transport. Module
+     * install/uninstall and analyze-build no longer rely on it — they clear their
+     * UI from the awaited RPC / refreshed info instead.
+     */
     onTerminalExit: (_: {
         id: string;
         code?: number;
     }) => void;
 }
+/**
+ * @deprecated The payload of the deprecated {@link ServerFunctions.getServerData}
+ * shim. Use the Data Inspector panel's live `Nuxt Application` source instead.
+ */
 interface NuxtServerData {
     nuxt: NuxtOptions;
     nitro?: Nitro['options'];
@@ -670,13 +720,16 @@ interface NuxtServerData {
 type ClientUpdateEvent = keyof ServerFunctions;
 
 /**
- * Compatibility RPC interface that supports broadcast and function access.
- * Backed by Vite DevTools Kit's RpcFunctionsHost internally.
+ * Legacy Nuxt DevTools RPC compatibility surface exposed on `nuxt.devtools.rpc`.
+ *
+ * For new integrations prefer {@link onDevtoolsReady}, where the connected
+ * `ViteDevToolsNodeContext` gives you the full devframe `ctx.rpc`
+ * (`register`/`invokeLocal`/`broadcast`/`sharedState`/…).
  */
 interface NuxtDevtoolsRpc {
     /**
      * Broadcast proxy for calling client functions.
-     * Supports `rpc.broadcast.refresh.asEvent(event)` pattern for backward compatibility.
+     * Supports `rpc.broadcast.refresh.asEvent(event)` for backward compatibility.
      */
     broadcast: {
         [K in keyof ClientFunctions]: ClientFunctions[K] & {
@@ -684,7 +737,7 @@ interface NuxtDevtoolsRpc {
         };
     };
     /**
-     * Proxy for accessing server functions locally.
+     * Proxy for reading/writing server functions locally.
      */
     functions: ServerFunctions;
 }
@@ -696,9 +749,14 @@ interface NuxtDevtoolsServerContext {
     options: ModuleOptions;
     rpc: NuxtDevtoolsRpc;
     /**
-     * The Vite DevTools Kit context, available after connection.
+     * The connected Vite DevTools kit context (`docks`/`terminals`/`messages`/
+     * `commands`/`rpc`/`diagnostics`/…).
+     *
+     * This is the raw escape hatch and is `undefined` until the Vite DevTools
+     * plugin connects. Prefer {@link onDevtoolsReady}, which hands you the
+     * connected context.
      */
-    devtoolsKit: DevToolsNodeContext | undefined;
+    devtoolsKit: ViteDevToolsNodeContext | undefined;
     /**
      * Hook to open file in editor
      */
@@ -707,6 +765,19 @@ interface NuxtDevtoolsServerContext {
      * Invalidate client cache for a function and ask for re-fetching
      */
     refresh: (event: keyof ServerFunctions) => void;
+    /**
+     * Push a notification through the devframe Messages system (`ctx.messages`).
+     *
+     * The connected messages host surfaces it in the Vite DevTools **Messages**
+     * dock and/or as a toast. Calls made before the kit connects are buffered and
+     * replayed on connect. Used by the `devtools:notify` hook, the `notify` RPC
+     * function and the curated built-in notification sources.
+     */
+    notify: (input: NuxtDevtoolsNotifyInput) => void;
+    /**
+     * @deprecated Use the Vite DevTools RPC registration instead:
+     * `nuxt.devtools.rpc.register(defineRpcFunction(...))`. Kept working as a shim.
+     */
     extendServerRpc: <ClientFunctions extends object = Record<string, unknown>, ServerFunctions extends object = Record<string, unknown>>(name: string, functions: ServerFunctions) => BirpcGroup<ClientFunctions, ServerFunctions>;
 }
 interface NuxtDevtoolsInfo {
@@ -726,6 +797,64 @@ interface ServerDebugContext {
     moduleMutationRecords: ServerDebugModuleMutationRecord[];
 }
 
+interface TerminalBase {
+    id: string;
+    name: string;
+    description?: string;
+    icon?: string;
+}
+type TerminalAction = 'restart' | 'terminate' | 'clear' | 'remove';
+interface SubprocessOptions {
+    command: string;
+    args?: string[];
+    cwd?: string;
+    env?: Record<string, string | undefined>;
+    nodeOptions?: SpawnOptions;
+}
+interface TerminalInfo extends TerminalBase {
+    /**
+     * Whether the terminal can be restarted.
+     *
+     * @deprecated Ignored since v4: legacy terminals are bridged onto the built-in
+     * Terminals dock as read-only, output-only sessions, so Devframe shows no
+     * restart control. Restart a `startSubprocess()`-owned process through its
+     * returned handle instead. Will be removed in v5.
+     */
+    restartable?: boolean;
+    /**
+     * Whether the terminal can be terminated.
+     *
+     * @deprecated Ignored since v4 (see {@link TerminalInfo.restartable}). Will be
+     * removed in v5.
+     */
+    terminatable?: boolean;
+    /**
+     * Whether the terminal is terminated
+     */
+    isTerminated?: boolean;
+    /**
+     * Content buffer
+     */
+    buffer?: string;
+}
+interface TerminalState extends TerminalInfo {
+    /**
+     * User action to restart the terminal, when not provided, this action will be disabled.
+     *
+     * @deprecated Ignored since v4: the bridge to the built-in Terminals dock
+     * cannot attach action callbacks to an externally registered session. Will be
+     * removed in v5.
+     */
+    onActionRestart?: () => Promise<void> | void;
+    /**
+     * User action to terminate the terminal, when not provided, this action will be disabled.
+     *
+     * @deprecated Ignored since v4 (see {@link TerminalState.onActionRestart}).
+     * Will be removed in v5.
+     */
+    onActionTerminate?: () => Promise<void> | void;
+}
+
 declare module '@nuxt/schema' {
     interface NuxtHooks {
         /**
@@ -736,6 +865,30 @@ declare module '@nuxt/schema' {
          * Called after devtools is initialized.
          */
         'devtools:initialized': (info: NuxtDevtoolsInfo) => void;
+        /**
+         * Called once the Vite DevTools kit has connected, with the connected
+         * `ViteDevToolsNodeContext`.
+         *
+         * This is the recommended place to do all DevTools integration
+         * (registering docks, terminals, messages, commands, RPC functions,
+         * diagnostics, …): the kit is guaranteed to be available here, so you don't
+         * need the connect-safe accessors on `nuxt.devtools`.
+         */
+        'devtools:ready': (ctx: ViteDevToolsNodeContext) => void | Promise<void>;
+        /**
+         * Push a notification through the devframe Messages system.
+         *
+         * Forwarded to the connected `ctx.messages` host, so it surfaces in the
+         * Vite DevTools **Messages** dock (persistent, when leveled) and/or as a
+         * transient toast (when `notify` is set). Calls made before the kit connects
+         * are buffered and replayed once it does.
+         *
+         * @example
+         * ```ts
+         * nuxt.callHook('devtools:notify', { message: 'Build failed', level: 'error' })
+         * ```
+         */
+        'devtools:notify': (input: NuxtDevtoolsNotifyInput) => void;
         /**
          * Hooks to extend devtools tabs.
          */
@@ -745,7 +898,11 @@ declare module '@nuxt/schema' {
          */
         'devtools:customTabs:refresh': () => void;
         /**
-         * Register a terminal.
+         * Register a terminal whose process is owned by the caller (module).
+         *
+         * The registered session is surfaced **read-only** in the built-in Vite
+         * DevTools **Terminals** dock; stream output into it via
+         * `devtools:terminal:write`.
          */
         'devtools:terminal:register': (terminal: TerminalState) => void;
         /**
@@ -774,19 +931,5 @@ declare module '@nuxt/schema' {
         }) => void;
     }
 }
-declare module '@nuxt/schema' {
-    /**
-     * Runtime Hooks
-     */
-    interface RuntimeNuxtHooks {
-        /**
-         * On terminal data.
-         */
-        'devtools:terminal:data': (payload: {
-            id: string;
-            data: string;
-        }) => void;
-    }
-}
 
-export type { ServerFunctions as $, AnalyzeBuildMeta as A, BasicModuleInfo as B, CategorizedTabs as C, ModuleType as D, ModuleVNodeView as E, ModuleView as F, GitHubContributor as G, HookInfo as H, ImageMeta as I, NpmCommandType as J, NuxtDevToolsOptions as K, LoadingTimeMetric as L, MaintainerInfo as M, NpmCommandOptions as N, NuxtDevtoolsInfo as O, NuxtDevtoolsRpc as P, NuxtDevtoolsServerContext as Q, NuxtServerData as R, PackageManagerName as S, PackageUpdateInfo as T, Payload as U, PluginInfoWithMetic as V, PluginMetric as W, RouteInfo as X, ScannedNitroTasks as Y, ServerDebugContext as Z, ServerDebugModuleMutationRecord as _, AnalyzeBuildsInfo as a, ServerRouteInfo as a0, ServerRouteInput as a1, ServerRouteInputType as a2, ServerTaskInfo as a3, SubprocessOptions as a4, TabCategory as a5, TerminalAction as a6, TerminalBase as a7, TerminalInfo as a8, TerminalState as a9, VSCodeIntegrationOptions as aa, VSCodeTunnelOptions as ab, VueInspectorClient as ac, VueInspectorData as ad, AssetEntry as b, AssetInfo as c, AssetType as d, AutoImportsWithMetadata as e, ClientFunctions as f, ClientUpdateEvent as g, CodeServerOptions as h, CodeServerType as i, CodeSnippet as j, CompatibilityStatus as k, ComponentRelationship as l, ComponentWithRelationships as m, InstallModuleReturn as n, InstalledModuleInfo as o, ModuleBuiltinTab as p, ModuleCompatibility as q, ModuleCustomTab as r, ModuleIframeTabLazyOptions as s, ModuleIframeView as t, ModuleLaunchAction as u, ModuleLaunchView as v, ModuleOptions as w, ModuleStaticInfo as x, ModuleStats as y, ModuleTabInfo as z };
+export type { PluginInfoWithMetic as $, AnalyzeBuildMeta as A, BasicModuleInfo as B, CategorizedTabs as C, ModuleStaticInfo as D, ModuleStats as E, ModuleTabInfo as F, GitHubContributor as G, HookInfo as H, ImageMeta as I, ModuleType as J, ModuleVNodeView as K, LoadingTimeMetric as L, ModuleCustomTab as M, NuxtDevtoolsServerContext as N, ModuleView as O, PluginMetric as P, NpmCommandOptions as Q, NpmCommandType as R, SubprocessOptions as S, TerminalState as T, NuxtDevToolsOptions as U, NuxtDevtoolsNotifyLevel as V, NuxtDevtoolsRpc as W, NuxtServerData as X, PackageManagerName as Y, PackageUpdateInfo as Z, Payload as _, NuxtDevtoolsInfo as a, RouteInfo as a0, ScannedNitroTasks as a1, ServerDebugContext as a2, ServerDebugModuleMutationRecord as a3, ServerRouteInfo as a4, ServerRouteInput as a5, ServerRouteInputType as a6, ServerTaskInfo as a7, TabCategory as a8, TerminalAction as a9, TerminalBase as aa, TerminalInfo as ab, VSCodeIntegrationOptions as ac, VSCodeTunnelOptions as ad, VueInspectorClient as ae, VueInspectorData as af, ServerFunctions as b, NuxtDevtoolsNotifyInput as c, AnalyzeBuildsInfo as d, AssetEntry as e, AssetInfo as f, AssetType as g, AutoImportsWithMetadata as h, ClientFunctions as i, ClientUpdateEvent as j, CodeServerIntegrationOptions as k, CodeServerType as l, CodeSnippet as m, CompatibilityStatus as n, ComponentRelationship as o, ComponentWithRelationships as p, InstallModuleReturn as q, InstalledModuleInfo as r, MaintainerInfo as s, ModuleBuiltinTab as t, ModuleCompatibility as u, ModuleIframeTabLazyOptions as v, ModuleIframeView as w, ModuleLaunchAction as x, ModuleLaunchView as y, ModuleOptions as z };