Auto-enable diagnostics surface when @solidjs/diagnostics is installed

Installing the dev dependency is now the whole setup: the dev-serve
diagnostics surface (bridge injection, /__solid/diagnostics endpoint,
startup breadcrumb) detects the package with a node_modules walk from
the project root and enables itself. The `diagnostics` option becomes
an override — `true` forces it on (hard error if the package is
missing), `false` opts out. Start mode resolves the same detection for
its client-entry bridge import.

No host guard on the endpoint: Vite's own DNS-rebinding host check
(all supported versions, peer ^8) runs ahead of plugin middleware —
verified empirically with a spoofed Host header.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: ryansolid

.changeset/diagnostics-auto-enable.md

@@ -0,0 +1,5 @@
+---
+'@solidjs/vite-plugin': patch
+---
+
+Auto-enable the agent diagnostics surface (dev serve only) when `@solidjs/diagnostics` is installed in the app — installing the dev dependency is now the whole setup. The `diagnostics` option becomes an override: `true` forces it on (erroring if the package is missing), `false` opts out entirely, omitted auto-detects. Start mode's generated/authored client entries follow the same detection for the bridge import.

src/diagnostics/index.ts

@@ -1,5 +1,9 @@
 /**
- * Agent diagnostics surface (`diagnostics: true`, dev serve only).
+ * Agent diagnostics surface (dev serve only).
+ *
+ * Enabled automatically when the app has `@solidjs/diagnostics` installed
+ * (the `diagnostics` option overrides: `true` forces it on and errors if
+ * the package is missing, `false` opts out entirely).
  *
  * Three pieces:
  * - an injected client module (virtual, imported by index.html or the
@@ -18,6 +22,7 @@
  * wire constants are re-declared here with types imported from the
  * package, so drift fails the plugin's own compile.
  */
+import fs from 'fs';
 import path from 'path';
 import type { IncomingMessage, ServerResponse } from 'http';
 import type { Plugin } from 'vite';
@@ -40,6 +45,28 @@ const METHODS = ['begin', 'end', 'active', 'whyDidRun', 'costs'] as const satisf
 /** How long the endpoint waits for a page to answer before failing the call. */
 const RESPONSE_TIMEOUT_MS = 10_000;
 
+/**
+ * Whether the app has `@solidjs/diagnostics` installed — the auto-enable
+ * signal. A plain node_modules walk (project root upward) rather than
+ * module resolution: the package is ESM-only, so `require.resolve` can't
+ * probe it, and this also matches hoisted installs. Yarn PnP has no
+ * node_modules and isn't detected — `diagnostics: true` is the escape
+ * hatch there.
+ */
+export function detectDiagnosticsPackage(root: string): boolean {
+  let dir = path.resolve(root);
+  while (true) {
+    if (
+      fs.existsSync(path.join(dir, 'node_modules', DIAGNOSTICS_PACKAGE, 'package.json'))
+    ) {
+      return true;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) return false;
+    dir = parent;
+  }
+}
+
 export function diagnosticsClientModuleCode(): string {
   // Runtime imports resolve to the APP's diagnostics package (see the
   // resolveId assist below) — the page speaks its own package's protocol.
@@ -103,9 +130,13 @@ function readJsonBody(req: IncomingMessage): Promise<unknown> {
   });
 }
 
-export function solidDiagnostics(): Plugin {
+export function solidDiagnostics(mode: true | 'auto' = 'auto'): Plugin {
   let root = process.cwd();
   let base = '/';
+  // Resolved at configResolved: explicit `true` is unconditional (missing
+  // package becomes a hard error at bridge resolution); `'auto'` enables
+  // only when the app has the package installed.
+  let enabled = mode === true;
 
   return {
     name: 'solid:diagnostics',
@@ -117,6 +148,7 @@ export function solidDiagnostics(): Plugin {
     configResolved(config) {
       root = config.root;
       base = config.base;
+      if (mode === 'auto') enabled = detectDiagnosticsPackage(root);
     },
 
     async resolveId(source, importer) {
@@ -131,9 +163,9 @@ export function solidDiagnostics(): Plugin {
         });
         if (!resolved || resolved.id.startsWith('__vite-optional-peer-dep:')) {
           this.error(
-            `[@solidjs/vite-plugin] the diagnostics option requires ${DIAGNOSTICS_PACKAGE} ` +
+            `[@solidjs/vite-plugin] the diagnostics surface requires ${DIAGNOSTICS_PACKAGE} ` +
               'installed in the app (it provides the in-page bridge). Install it as a ' +
-              'development dependency or remove `diagnostics: true`.',
+              'development dependency, or set `diagnostics: false` to opt out.',
           );
         }
         return resolved;
@@ -149,6 +181,7 @@ export function solidDiagnostics(): Plugin {
     // Plain (index.html) apps get the client module injected here;
     // start-mode apps import it from the generated client entry instead.
     transformIndexHtml() {
+      if (!enabled) return undefined;
       return [
         {
           tag: 'script',
@@ -159,6 +192,11 @@ export function solidDiagnostics(): Plugin {
     },
 
     configureServer(server) {
+      // The whole surface (announcement, middleware, bridge injection) only
+      // exists when enabled, so the discovery breadcrumb never lies about
+      // a dead endpoint.
+      if (!enabled) return;
+
       // Announce the surface in the startup block. This is a discovery
       // channel: agents watching dev-server output learn the endpoint and
       // the skill documents without any project-level pointer (AGENTS.md).
@@ -171,8 +209,9 @@ export function solidDiagnostics(): Plugin {
           : DIAGNOSTICS_ENDPOINT;
         server.config.logger.info(
           `  ➜  Solid diagnostics: ${endpoint} ` +
-            `(GET status; POST {"method":"begin"|"end"|"whyDidRun"|"costs"})\n` +
-            `  ➜  Agent skills: node_modules/${DIAGNOSTICS_PACKAGE}/skills/agent-loops/SKILL.md, ` +
+            `(GET status; POST {"method":"begin"|"end"|"whyDidRun"|"costs"})` +
+            (mode === 'auto' ? ' — auto-enabled; `diagnostics: false` opts out' : '') +
+            `\n  ➜  Agent skills: node_modules/${DIAGNOSTICS_PACKAGE}/skills/agent-loops/SKILL.md, ` +
             `node_modules/solid-js/skills/reactivity-diagnostics/SKILL.md`,
         );
       };
@@ -192,6 +231,10 @@ export function solidDiagnostics(): Plugin {
         entry.resolve(data);
       });
 
+      // No host/origin validation here: on all supported Vite versions
+      // (peer range ^8) Vite's own DNS-rebinding host check runs ahead of
+      // plugin middleware — verified: requests with a disallowed Host
+      // header get Vite's 403 before reaching this handler.
       server.middlewares.use(DIAGNOSTICS_ENDPOINT, async (req, res) => {
         // The middleware mounts on the exact path; anything deeper is 404.
         if (req.url && req.url !== '/' && req.url !== '') {

src/index.ts

@@ -225,12 +225,17 @@ export interface Options {
    * Dev-serve only: expose Solid's diagnostic and attribution channels to
    * out-of-process consumers (agents, tests, curl). Injects a client module
    * that installs the in-page bridge from the app's own
-   * `@solidjs/diagnostics` (which must be installed as a dev dependency),
-   * and serves a `/__solid/diagnostics` endpoint on the dev server that
-   * forwards capture control (`begin`/`end`), `whyDidRun`, and cost queries
-   * to the page over the Vite WebSocket. No effect on builds or preview.
+   * `@solidjs/diagnostics`, and serves a `/__solid/diagnostics` endpoint on
+   * the dev server that forwards capture control (`begin`/`end`),
+   * `whyDidRun`, and cost queries to the page over the Vite WebSocket. No
+   * effect on builds or preview.
    *
-   * @default false
+   * Omitted (the default), the surface auto-enables when
+   * `@solidjs/diagnostics` is installed in the app — installing the dev
+   * dependency is the whole setup. `true` forces it on (erroring if the
+   * package is missing); `false` opts out entirely.
+   *
+   * @default undefined (auto-detect)
    */
   diagnostics?: boolean;
   /**
@@ -1270,7 +1275,7 @@ export default function solidPlugin(options: Partial<Options> = {}): Plugin[] {
         serverComponents,
         ssr: !!options.ssr,
         styleFilter: filterDevStyles,
-        diagnostics: !!options.diagnostics,
+        diagnostics: options.diagnostics ?? 'auto',
         onDocumentResolved(documentPath) {
           // Normalize to forward slashes to match Vite's transform ids.
           documentModuleId = documentPath ? documentPath.split(path.sep).join('/') : null;
@@ -1280,9 +1285,11 @@ export default function solidPlugin(options: Partial<Options> = {}): Plugin[] {
   }
 
   // Agent diagnostics endpoint + injected bridge (dev serve only — the
-  // plugin no-ops itself for builds and preview via `apply`).
-  if (options.diagnostics) {
-    plugins.push(solidDiagnostics());
+  // plugin no-ops itself for builds and preview via `apply`, and in the
+  // default auto mode additionally disables itself unless the app has
+  // `@solidjs/diagnostics` installed).
+  if (options.diagnostics !== false) {
+    plugins.push(solidDiagnostics(options.diagnostics === true ? true : 'auto'));
   }
 
   // Builder-mode (environments API) client-before-server build ordering.

src/ssr/index.ts

@@ -59,7 +59,7 @@ import {
   DEVTOOLS_PACKAGE,
   devtoolsMountModuleCode,
 } from '../devtools/index.js';
-import { DIAGNOSTICS_CLIENT_ID } from '../diagnostics/index.js';
+import { DIAGNOSTICS_CLIENT_ID, detectDiagnosticsPackage } from '../diagnostics/index.js';
 import {
   collectDevStyles,
   collectDevStyleSources,
@@ -434,7 +434,8 @@ export function startServe(
     serverComponents?: boolean;
     ssr?: boolean;
     styleFilter?: DevStyleFilter;
-    diagnostics?: boolean;
+    /** `'auto'` = enable when the app has `@solidjs/diagnostics` installed. */
+    diagnostics?: boolean | 'auto';
     /**
      * Reports the resolved document shell path (absolute, or null when the
      * built-in virtual document is used) back to the main plugin, which
@@ -464,7 +465,9 @@ export function startServe(
   const serverComponents = !!internal.serverComponents;
   const errorBoundary = options.errorBoundary !== false;
   const styleFilter = internal.styleFilter;
-  const diagnostics = !!internal.diagnostics;
+  // `'auto'` resolves against the project root in configResolved, before
+  // any of the (lazy) uses in entry codegen and the entry transform.
+  let diagnostics = internal.diagnostics === true;
   let devtoolsEnabled = false;
   let devtoolsResolutions: Partial<
     Record<'client' | 'server', Promise<string | null>>
@@ -1266,6 +1269,9 @@ export function startServe(
         root = config.root;
         base = config.base;
         isBuild = config.command === 'build';
+        if (internal.diagnostics === 'auto' && !isBuild) {
+          diagnostics = detectDiagnosticsPackage(root);
+        }
       },
       resolveId(source, importer, opts) {
         if (source === HANDLER_ID) {