sunpeak 0.16.29 → 0.17.2

package/bin/commands/inspect.mjs

@@ -0,0 +1,763 @@
+/**
+ * `sunpeak inspect` — Connect to an external MCP server and launch the simulator.
+ *
+ * This command lets users test their own MCP server in the sunpeak simulator
+ * without adopting the sunpeak framework conventions. It connects to the server
+ * via MCP protocol, discovers tools and resources, and serves the simulator UI.
+ *
+ * The core logic lives in `inspectServer()`, which is also used by `sunpeak dev`
+ * to serve the simulator UI pointed at the local MCP server.
+ *
+ * Usage:
+ *   sunpeak inspect --server http://localhost:8000/mcp
+ *   sunpeak inspect --server "python my_server.py"
+ *   sunpeak inspect --server http://localhost:8000/mcp --simulations tests/simulations
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+const { existsSync, readdirSync, readFileSync } = fs;
+const { join, resolve, dirname } = path;
+import { fileURLToPath, pathToFileURL } from 'url';
+import { getPort } from '../lib/get-port.mjs';
+import { startSandboxServer } from '../lib/sandbox-server.mjs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const SUNPEAK_PKG_DIR = resolve(__dirname, '..', '..');
+
+/**
+ * Parse CLI arguments.
+ * @param {string[]} args
+ */
+function parseArgs(args) {
+  const opts = {
+    server: undefined,
+    simulations: undefined,
+    port: undefined,
+    name: undefined,
+  };
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if ((arg === '--server' || arg === '-s') && i + 1 < args.length) {
+      opts.server = args[++i];
+    } else if (arg === '--simulations' && i + 1 < args.length) {
+      opts.simulations = args[++i];
+    } else if ((arg === '--port' || arg === '-p') && i + 1 < args.length) {
+      opts.port = Number(args[++i]);
+    } else if (arg === '--name' && i + 1 < args.length) {
+      opts.name = args[++i];
+    } else if (arg === '--help' || arg === '-h') {
+      printHelp();
+      process.exit(0);
+    }
+  }
+
+  return opts;
+}
+
+function printHelp() {
+  console.log(`
+sunpeak inspect — Test an external MCP server in the simulator
+
+Usage:
+  sunpeak inspect --server <url-or-command>
+
+Options:
+  --server, -s <url|cmd>     MCP server URL or stdio command (required)
+  --simulations <dir>        Simulation JSON directory (opt-in, no default)
+  --port, -p <number>        Dev server port (default: 3000)
+  --name <string>            App name in simulator chrome
+  --help, -h                 Show this help
+
+Examples:
+  sunpeak inspect --server http://localhost:8000/mcp
+  sunpeak inspect --server "python my_server.py"
+  sunpeak inspect --server http://localhost:8000/mcp --simulations tests/simulations
+`);
+}
+
+/**
+ * Create an MCP client connection.
+ * @param {string} serverArg - URL or command string
+ * @returns {Promise<{ client: import('@modelcontextprotocol/sdk/client/index.js').Client, transport: import('@modelcontextprotocol/sdk/types.js').Transport }>}
+ */
+async function createMcpConnection(serverArg) {
+  const { Client } = await import('@modelcontextprotocol/sdk/client/index.js');
+  const client = new Client({ name: 'sunpeak-inspector', version: '1.0.0' });
+
+  if (serverArg.startsWith('http://') || serverArg.startsWith('https://')) {
+    // HTTP/SSE transport
+    const { StreamableHTTPClientTransport } = await import(
+      '@modelcontextprotocol/sdk/client/streamableHttp.js'
+    );
+    const transport = new StreamableHTTPClientTransport(new URL(serverArg));
+    await client.connect(transport);
+    return { client, transport };
+  } else {
+    // Stdio transport — parse command string
+    const parts = serverArg.split(/\s+/);
+    const command = parts[0];
+    const cmdArgs = parts.slice(1);
+    const { StdioClientTransport } = await import(
+      '@modelcontextprotocol/sdk/client/stdio.js'
+    );
+    const transport = new StdioClientTransport({ command, args: cmdArgs });
+    await client.connect(transport);
+    return { client, transport };
+  }
+}
+
+/**
+ * Discover tools and resources from the MCP server and build Simulation objects.
+ * @param {import('@modelcontextprotocol/sdk/client/index.js').Client} client
+ * @returns {Promise<Record<string, object>>} Map of simulation name → Simulation-shaped objects
+ */
+async function discoverSimulations(client) {
+  const { tools } = await client.listTools();
+
+  // Try to list resources (server may not support them)
+  let resources = [];
+  try {
+    const result = await client.listResources();
+    resources = result.resources || [];
+  } catch {
+    // Server doesn't support resources — that's fine
+  }
+
+  // Build resource URI map
+  const resourceByUri = new Map();
+  for (const resource of resources) {
+    resourceByUri.set(resource.uri, resource);
+  }
+
+  const simulations = {};
+
+  for (const tool of tools) {
+    const simName = tool.name;
+
+    // Match tool to resource via _meta.ui.resourceUri (MCP Apps extension).
+    // Supports both nested format (_meta.ui.resourceUri) and deprecated flat
+    // format (_meta["ui/resourceUri"]).
+    let resource;
+    let resourceUrl;
+    const uri = tool._meta?.ui?.resourceUri ?? tool._meta?.['ui/resourceUri'];
+    if (uri) {
+      resource = resourceByUri.get(uri);
+      if (resource) {
+        resourceUrl = `/__sunpeak/read-resource?uri=${encodeURIComponent(uri)}`;
+      }
+    }
+
+    simulations[simName] = {
+      name: simName,
+      tool,
+      resource,
+      resourceUrl,
+    };
+  }
+
+  return simulations;
+}
+
+/**
+ * Load simulation JSON fixtures from a directory and merge into discovered simulations.
+ * @param {string} dir - Simulation directory path
+ * @param {Record<string, object>} simulations - Discovered simulations to merge into
+ */
+function mergeSimulationFixtures(dir, simulations) {
+  if (!existsSync(dir)) return;
+
+  const files = readdirSync(dir).filter((f) => f.endsWith('.json'));
+  for (const file of files) {
+    try {
+      const fixture = JSON.parse(readFileSync(join(dir, file), 'utf-8'));
+      const toolName = fixture.tool;
+      if (!toolName) continue;
+
+      // Find matching simulation by tool name
+      const sim = simulations[toolName];
+      if (sim) {
+        // Merge fixture data into discovered simulation
+        if (fixture.toolInput !== undefined) sim.toolInput = fixture.toolInput;
+        if (fixture.toolResult !== undefined) sim.toolResult = fixture.toolResult;
+        if (fixture.serverTools !== undefined) sim.serverTools = fixture.serverTools;
+        if (fixture.userMessage !== undefined) sim.userMessage = fixture.userMessage;
+        if (fixture.hostContext !== undefined) sim.hostContext = fixture.hostContext;
+      } else {
+        // Create a new simulation from the fixture (tool not on server, but user wants to mock it)
+        const simName = file.replace(/\.json$/, '');
+        simulations[simName] = {
+          name: simName,
+          tool: { name: toolName, inputSchema: { type: 'object' } },
+          toolInput: fixture.toolInput,
+          toolResult: fixture.toolResult,
+          serverTools: fixture.serverTools,
+          userMessage: fixture.userMessage,
+          hostContext: fixture.hostContext,
+        };
+      }
+    } catch (err) {
+      console.warn(`Warning: Failed to parse simulation fixture ${file}:`, err.message);
+    }
+  }
+}
+
+/**
+ * Vite plugin that serves virtual modules for the inspect entry point.
+ *
+ * @param {Record<string, object>} simulations - Simulation objects
+ * @param {string|null} serverUrl - MCP server URL (null in framework mode to hide server UI)
+ * @param {string} appName - Display name
+ * @param {string|null} appIcon - Icon URL or emoji
+ * @param {string} sandboxUrl - Sandbox server URL
+ * @param {{ defaultProdTools?: boolean, defaultProdResources?: boolean }} [modeFlags] - Mode toggles
+ */
+function sunpeakInspectVirtualPlugin(simulations, serverUrl, appName, appIcon, sandboxUrl, modeFlags = {}) {
+  const ENTRY_ID = 'virtual:sunpeak-inspect-entry';
+  const RESOLVED_ENTRY_ID = '\0' + ENTRY_ID;
+
+  return {
+    name: 'sunpeak-inspect-virtual',
+    resolveId(id) {
+      if (id === ENTRY_ID) return RESOLVED_ENTRY_ID;
+    },
+    load(id) {
+      if (id !== RESOLVED_ENTRY_ID) return;
+
+      // In framework mode (serverUrl is null), don't pass mcpServerUrl to the
+      // Simulator — this enables the prod-tools/prod-resources toggles and hides
+      // the server URL input in the sidebar.
+      const mcpServerUrlProp = serverUrl != null
+        ? `mcpServerUrl: ${JSON.stringify(serverUrl)},`
+        : '';
+
+      return `
+import { createElement, StrictMode } from 'react';
+import { createRoot } from 'react-dom/client';
+import { Simulator } from 'sunpeak/simulator';
+import 'sunpeak/style.css';
+import 'sunpeak/chatgpt/globals.css';
+
+const simulations = ${JSON.stringify(simulations)};
+const appName = ${JSON.stringify(appName ?? 'MCP Inspector')};
+const appIcon = ${JSON.stringify(appIcon ?? null)};
+const sandboxUrl = ${JSON.stringify(sandboxUrl)};
+const defaultProdTools = ${JSON.stringify(modeFlags.defaultProdTools ?? false)};
+const defaultProdResources = ${JSON.stringify(modeFlags.defaultProdResources ?? false)};
+
+const onCallTool = async (params) => {
+  const res = await fetch('/__sunpeak/call-tool', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(params),
+  });
+  return res.json();
+};
+
+const onCallToolDirect = async (params) => {
+  const res = await fetch('/__sunpeak/call-tool-direct', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(params),
+  });
+  return res.json();
+};
+
+const root = createRoot(document.getElementById('root'));
+root.render(
+  createElement(StrictMode, null,
+    createElement(Simulator, {
+      simulations,
+      ${mcpServerUrlProp}
+      appName,
+      appIcon,
+      sandboxUrl,
+      onCallTool,
+      onCallToolDirect,
+      defaultProdTools,
+      defaultProdResources,
+    })
+  )
+);
+`;
+    },
+  };
+}
+
+/**
+ * Vite plugin for MCP server proxy endpoints.
+ * @param {() => import('@modelcontextprotocol/sdk/client/index.js').Client} getClient
+ * @param {{ callToolDirect?: (name: string, args: Record<string, unknown>) => Promise<object> }} [pluginOpts]
+ */
+function sunpeakInspectEndpointsPlugin(getClient, pluginOpts = {}) {
+  return {
+    name: 'sunpeak-inspect-endpoints',
+    configureServer(server) {
+      // List tools from connected server
+      server.middlewares.use('/__sunpeak/list-tools', async (_req, res) => {
+        try {
+          const client = getClient();
+          const result = await client.listTools();
+          res.writeHead(200, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify(result));
+        } catch (err) {
+          res.writeHead(500, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ error: err.message }));
+        }
+      });
+
+      // Call tool on connected server
+      server.middlewares.use('/__sunpeak/call-tool', async (req, res) => {
+        if (req.method !== 'POST') {
+          res.writeHead(405);
+          res.end('Method not allowed');
+          return;
+        }
+
+        const body = await readRequestBody(req);
+        let parsed;
+        try {
+          parsed = JSON.parse(body);
+        } catch {
+          res.writeHead(400, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ error: 'Invalid JSON in request body' }));
+          return;
+        }
+
+        try {
+          const { name, arguments: args } = parsed;
+          const client = getClient();
+          const result = await client.callTool({ name, arguments: args });
+          res.writeHead(200, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify(result));
+        } catch (err) {
+          res.writeHead(200, { 'Content-Type': 'application/json' });
+          res.end(
+            JSON.stringify({
+              content: [{ type: 'text', text: `Error: ${err.message}` }],
+              isError: true,
+            })
+          );
+        }
+      });
+
+      // Call tool handler directly, bypassing MCP server mock data.
+      // Used by the Prod Tools Run button so the real handler executes even
+      // when the MCP server would return simulation fixture data.
+      server.middlewares.use('/__sunpeak/call-tool-direct', async (req, res) => {
+        if (req.method !== 'POST') {
+          res.writeHead(405);
+          res.end('Method not allowed');
+          return;
+        }
+
+        if (!pluginOpts.callToolDirect) {
+          // No direct handler available (pure inspect mode) — fall back to MCP
+          const body = await readRequestBody(req);
+          let parsed;
+          try { parsed = JSON.parse(body); } catch {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Invalid JSON' }));
+            return;
+          }
+          try {
+            const client = getClient();
+            const result = await client.callTool({ name: parsed.name, arguments: parsed.arguments });
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify(result));
+          } catch (err) {
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ content: [{ type: 'text', text: `Error: ${err.message}` }], isError: true }));
+          }
+          return;
+        }
+
+        const body = await readRequestBody(req);
+        let parsed;
+        try { parsed = JSON.parse(body); } catch {
+          res.writeHead(400, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ error: 'Invalid JSON' }));
+          return;
+        }
+
+        try {
+          const result = await pluginOpts.callToolDirect(parsed.name, parsed.arguments ?? {});
+          res.writeHead(200, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify(result));
+        } catch (err) {
+          res.writeHead(200, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ content: [{ type: 'text', text: `Error: ${err.message}` }], isError: true }));
+        }
+      });
+
+      // Reconnect to a new server URL.
+      // Currently acknowledges without actually reconnecting — the MCP client
+      // connection is established at startup. Changing the URL in the sidebar
+      // requires restarting the inspect server. This endpoint exists so the
+      // useMcpConnection hook can verify the server is reachable.
+      server.middlewares.use('/__sunpeak/connect', async (req, res) => {
+        if (req.method !== 'POST') {
+          res.writeHead(405);
+          res.end('Method not allowed');
+          return;
+        }
+
+        try {
+          // Verify the MCP client is still connected by listing tools
+          const client = getClient();
+          await client.listTools();
+          res.writeHead(200, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ status: 'ok' }));
+        } catch (err) {
+          res.writeHead(500, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ error: err.message }));
+        }
+      });
+
+      // Read resource from connected server
+      server.middlewares.use('/__sunpeak/read-resource', async (req, res) => {
+        const url = new URL(req.url, 'http://localhost');
+        const uri = url.searchParams.get('uri');
+        if (!uri) {
+          res.writeHead(400);
+          res.end('Missing uri parameter');
+          return;
+        }
+
+        try {
+          const client = getClient();
+          const result = await client.readResource({ uri });
+          const content = result.contents?.[0];
+          if (!content) {
+            res.writeHead(404);
+            res.end('Resource not found');
+            return;
+          }
+
+          const mimeType = content.mimeType || 'text/html';
+          res.writeHead(200, { 'Content-Type': `${mimeType}; charset=utf-8` });
+          if (typeof content.text === 'string') {
+            res.end(content.text);
+          } else if (content.blob) {
+            res.end(Buffer.from(content.blob, 'base64'));
+          } else {
+            res.end('');
+          }
+        } catch (err) {
+          res.writeHead(500, { 'Content-Type': 'text/plain' });
+          res.end(`Error reading resource: ${err.message}`);
+        }
+      });
+    },
+  };
+}
+
+/**
+ * Read the full body of an HTTP request.
+ */
+function readRequestBody(req) {
+  return new Promise((resolve, reject) => {
+    let data = '';
+    req.on('data', (chunk) => (data += chunk));
+    req.on('end', () => resolve(data));
+    req.on('error', reject);
+  });
+}
+
+/**
+ * Core inspect server logic. Connects to an MCP server, discovers tools/resources,
+ * merges simulation fixtures, and serves the simulator UI via Vite.
+ *
+ * Used by both `sunpeak inspect` (CLI) and `sunpeak dev` (programmatic).
+ *
+ * @param {object} opts
+ * @param {string} opts.server - MCP server URL or stdio command
+ * @param {string|null} [opts.simulationsDir] - Path to simulation fixtures directory
+ * @param {number} [opts.port] - Dev server port (default: 3000)
+ * @param {string} [opts.name] - App name override
+ * @param {string} [opts.sandboxUrl] - Existing sandbox server URL (skips creating one)
+ * @param {boolean} [opts.frameworkMode] - If true, hide server URL UI and show mode toggles
+ * @param {boolean} [opts.defaultProdTools] - Initial prod tools state
+ * @param {boolean} [opts.defaultProdResources] - Initial prod resources state
+ * @param {string} [opts.projectRoot] - Project directory for serving /dist/ files (prod resources)
+ * @param {boolean} [opts.noBegging] - Suppress star message
+ * @param {boolean} [opts.open] - Whether to open browser (default: !CI && !SUNPEAK_LIVE_TEST)
+ * @param {(name: string, args: Record<string, unknown>) => Promise<object>} [opts.callToolDirect] - Direct handler call (bypasses MCP, for prod-tools)
+ * @param {() => Promise<void>} [opts.onCleanup] - Additional cleanup callback on exit
+ */
+export async function inspectServer(opts) {
+  const {
+    server: serverArg,
+    simulationsDir = null,
+    port: preferredPort,
+    name: nameOverride,
+    sandboxUrl: existingSandboxUrl,
+    frameworkMode = false,
+    defaultProdTools = false,
+    defaultProdResources = false,
+    projectRoot = null,
+    noBegging = false,
+    open,
+    onCleanup,
+  } = opts;
+
+  // Load favicon from sunpeak package for the inspector UI.
+  let faviconDataUri = null;
+  let faviconBuffer = null;
+  try {
+    const distMcp = join(SUNPEAK_PKG_DIR, 'dist/mcp/index.js');
+    if (existsSync(distMcp)) {
+      const mod = await import(pathToFileURL(distMcp).href);
+      faviconDataUri = mod.FAVICON_DATA_URI;
+      faviconBuffer = mod.FAVICON_BUFFER;
+    }
+  } catch {
+    // Non-fatal — inspector will just not have a favicon
+  }
+
+  console.log(`Connecting to MCP server: ${serverArg}`);
+
+  // Connect to the MCP server (with retry for local servers that may still be starting)
+  let mcpConnection;
+  const maxRetries = 5;
+  for (let attempt = 1; attempt <= maxRetries; attempt++) {
+    try {
+      mcpConnection = await createMcpConnection(serverArg);
+      break;
+    } catch (err) {
+      if (attempt === maxRetries) {
+        console.error(`Failed to connect to MCP server: ${err.message}`);
+        process.exit(1);
+      }
+      console.log(`Connection attempt ${attempt}/${maxRetries} failed, retrying...`);
+      await new Promise(r => setTimeout(r, 500));
+    }
+  }
+
+  console.log('Connected. Discovering tools and resources...');
+
+  // Extract app name and icon from server info (reported during MCP initialize)
+  const serverInfo = mcpConnection.client.getServerVersion();
+  const serverAppName = nameOverride ?? serverInfo?.name;
+  const serverAppIcon = serverInfo?.icons?.[0]?.src;
+
+  // Discover tools/resources and build simulations
+  const simulations = await discoverSimulations(mcpConnection.client);
+  const toolCount = Object.keys(simulations).length;
+  const resourceCount = Object.values(simulations).filter((s) => s.resource).length;
+  console.log(`Found ${toolCount} tool(s), ${resourceCount} resource(s).`);
+
+  // Merge simulation fixtures when a directory is provided
+  if (simulationsDir) {
+    mergeSimulationFixtures(simulationsDir, simulations);
+  }
+
+  // Start or reuse sandbox server
+  let sandbox;
+  let ownsSandbox = false;
+  if (existingSandboxUrl) {
+    sandbox = { url: existingSandboxUrl, close: async () => {} };
+  } else {
+    const sandboxPort = Number(process.env.SUNPEAK_SANDBOX_PORT) || undefined;
+    sandbox = await startSandboxServer({
+      preferredPort: sandboxPort ?? 24680,
+    });
+    ownsSandbox = true;
+  }
+
+  // Determine server port
+  const port = preferredPort || Number(process.env.PORT) || (await getPort(3000));
+
+  // Import Vite
+  const { createServer } = await import('vite');
+  const react = (await import('@vitejs/plugin-react')).default;
+
+  // Build the virtual index.html
+  const appTitle = (serverAppName ?? 'MCP Inspector').replace(/[<>&"']/g, (c) =>
+    ({ '<': '&lt;', '>': '&gt;', '&': '&amp;', '"': '&quot;', "'": '&#39;' })[c]
+  );
+  const indexHtml = `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>${appTitle} — sunpeak</title>${faviconDataUri ? `\n  <link rel="icon" type="image/png" href="${faviconDataUri}" />` : ''}
+  <style>html, body, #root { margin: 0; padding: 0; height: 100%; }</style>
+</head>
+<body>
+  <div id="root"></div>
+  <script type="module" src="/@id/__x00__virtual:sunpeak-inspect-entry"></script>
+</body>
+</html>`;
+
+  // In framework mode, don't pass serverUrl to the Simulator (hides the server
+  // URL input in the sidebar, enables prod-tools/prod-resources toggles).
+  const simulatorServerUrl = frameworkMode ? null : serverArg;
+
+  // Create the Vite server.
+  // Use the sunpeak package dir as root to avoid scanning the user's project
+  // files for dependencies (which can cause resolution errors for @ aliases etc.)
+  const server = await createServer({
+    root: SUNPEAK_PKG_DIR,
+    configFile: false,
+    plugins: [
+      react(),
+      sunpeakInspectVirtualPlugin(
+        simulations,
+        simulatorServerUrl,
+        serverAppName,
+        serverAppIcon,
+        sandbox.url,
+        { defaultProdTools, defaultProdResources }
+      ),
+      sunpeakInspectEndpointsPlugin(() => mcpConnection.client, {
+        callToolDirect: opts.callToolDirect,
+      }),
+      // Serve /dist/{name}/{name}.html from the project directory (for Prod Resources mode).
+      // The Simulator polls these paths via HEAD to check if built resources exist.
+      // Only intercepts .html files under /dist/ — other /dist/ paths (like sunpeak's
+      // own dist/simulator/index.js) must fall through to Vite's module resolution.
+      ...(projectRoot ? [{
+        name: 'sunpeak-dist-serve',
+        configureServer(server) {
+          server.middlewares.use((req, res, next) => {
+            if (!req.url?.startsWith('/dist/') || !req.url.endsWith('.html')) return next();
+            const filePath = join(projectRoot, req.url);
+            if (existsSync(filePath)) {
+              const content = readFileSync(filePath, 'utf-8');
+              res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+              res.end(content);
+            } else {
+              res.writeHead(404);
+              res.end('Not found');
+            }
+          });
+        },
+      }] : []),
+      // Serve virtual index.html
+      {
+        name: 'sunpeak-inspect-index-html',
+        configureServer(server) {
+          // Serve index.html for all non-API, non-asset requests (SPA fallback)
+          server.middlewares.use((req, res, next) => {
+            if (
+              req.url === '/' ||
+              req.url === '/index.html' ||
+              (!req.url.startsWith('/__sunpeak/') &&
+                !req.url.startsWith('/@') &&
+                !req.url.startsWith('/node_modules/') &&
+                req.url !== '/health' &&
+                !req.url.includes('.'))
+            ) {
+              // Transform through Vite to resolve module imports
+              server.transformIndexHtml(req.url, indexHtml).then((html) => {
+                res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+                res.end(html);
+              }).catch(next);
+              return;
+            }
+            next();
+          });
+        },
+      },
+      // Paint fence responder
+      {
+        name: 'sunpeak-fence-responder',
+        transformIndexHtml(html) {
+          const fenceScript = `<script>window.addEventListener("message",function(e){if(e.data&&e.data.method==="sunpeak/fence"){var fid=e.data.params&&e.data.params.fenceId;requestAnimationFrame(function(){e.source.postMessage({jsonrpc:"2.0",method:"sunpeak/fence-ack",params:{fenceId:fid}},"*");});}});</script>`;
+          return html.replace('</head>', fenceScript + '</head>');
+        },
+      },
+      // Favicon
+      ...(faviconBuffer ? [{
+        name: 'sunpeak-favicon',
+        configureServer(server) {
+          server.middlewares.use('/favicon.ico', (_req, res) => {
+            res.writeHead(200, {
+              'Content-Type': 'image/png',
+              'Content-Length': faviconBuffer.length,
+              'Cache-Control': 'public, max-age=86400',
+            });
+            res.end(faviconBuffer);
+          });
+        },
+      }] : []),
+      // Health endpoint
+      {
+        name: 'sunpeak-health',
+        configureServer(server) {
+          server.middlewares.use('/health', (_req, res) => {
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ status: 'ok' }));
+          });
+        },
+      },
+    ],
+    server: {
+      port,
+      open: open ?? (!process.env.CI && !process.env.SUNPEAK_LIVE_TEST),
+      allowedHosts: 'all',
+    },
+    optimizeDeps: {
+      // Only pre-bundle React — the virtual entry module imports sunpeak from
+      // node_modules, so no user source scanning needed.
+      include: ['react', 'react-dom', 'react/jsx-runtime'],
+      // Disable scanning user's project files (avoids @ alias resolution errors)
+      entries: [],
+    },
+  });
+
+  await server.listen();
+  server.printUrls();
+  server.bindCLIShortcuts({ print: true });
+
+  // Print star-begging message unless suppressed
+  if (!noBegging) {
+    // #FFB800 in 24-bit ANSI color
+    console.log('\n\n\x1b[38;2;255;184;0m\u2b50\ufe0f \u2192 \u2764\ufe0f  https://github.com/Sunpeak-AI/sunpeak\x1b[0m\n');
+  }
+
+  // Cleanup on exit
+  const cleanup = async () => {
+    if (ownsSandbox) await sandbox.close();
+    try {
+      await mcpConnection.client.close();
+    } catch {
+      // Ignore close errors
+    }
+    await server.close();
+    if (onCleanup) await onCleanup();
+  };
+
+  process.on('SIGINT', async () => {
+    await cleanup();
+    process.exit(0);
+  });
+  process.on('SIGTERM', async () => {
+    await cleanup();
+    process.exit(0);
+  });
+}
+
+/**
+ * CLI entry point for `sunpeak inspect`.
+ */
+export async function inspect(args) {
+  const opts = parseArgs(args);
+
+  if (!opts.server) {
+    console.error('Error: --server is required.');
+    console.error('Run "sunpeak inspect --help" for usage.');
+    process.exit(1);
+  }
+
+  const projectRoot = process.cwd();
+  const simulationsDir = opts.simulations ? resolve(projectRoot, opts.simulations) : null;
+
+  await inspectServer({
+    server: opts.server,
+    simulationsDir,
+    port: opts.port,
+    name: opts.name,
+  });
+}