sunpeak 0.20.2 → 0.20.5

package/README.md

@@ -16,7 +16,13 @@
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue?style=flat&logo=typescript&label=ts&color=FFB800&logoColor=white&labelColor=000035)](https://www.typescriptlang.org/)
 [![React](https://img.shields.io/badge/React-19-blue?style=flat&logo=react&label=react&color=FFB800&logoColor=white&labelColor=000035)](https://reactjs.org/)
 
-Inspector, testing framework, and runtime framework for MCP servers and MCP Apps.
+MCP App framework, MCP testing framework, and inspector for MCP servers and MCP Apps.
+
+Build cross-platform: sunpeak is a ChatGPT App framework, Claude Connector framework, and more.
+
+```bash
+npx sunpeak new
+```
 
 [Demo (Hosted)](https://sunpeak.ai/inspector) ~
 [Demo (Video)](https://cdn.sunpeak.ai/sunpeak-demo-prod.mp4) ~
@@ -26,126 +32,89 @@ Inspector, testing framework, and runtime framework for MCP servers and MCP Apps
 
 ## sunpeak is three things
 
-### 1. Inspector
+### 1. App Framework
+
+Building an MCP App from scratch means wiring up an MCP server, handling protocol message routing, managing resource HTML bundles, and setting up a dev environment with hot reload. Each host has different capabilities and CSS variables, so you end up writing platform-specific code without a clear structure.
 
-Manually test any MCP server in replicated ChatGPT and Claude runtimes.
+sunpeak gives you a convention-over-configuration framework with the inspector and testing built in.
 
 ```bash
-sunpeak inspect --server http://localhost:8000/mcp
+npx sunpeak new
 ```
 
-<div align="center">
-  <a href="https://sunpeak.ai/docs/mcp-apps-inspector">
-    <picture>
-      <img alt="Inspector" src="https://cdn.sunpeak.ai/chatgpt-simulator.png">
-    </picture>
-  </a>
-</div>
-
-- Multi-host inspector replicating ChatGPT and Claude runtimes
-- Toggle themes, display modes, device types from the sidebar or URL params
-- Call real tool handlers or use simulation fixtures for mock data
+This creates a project, starts a dev server with HMR, and opens the inspector at `localhost:3000`:
 
-### 2. Testing Framework
+```
+sunpeak-app/
+├── src/resources/review/review.tsx    # UI component (React)
+├── src/tools/review-diff.ts           # Tool handler, schema, resource link
+├── tests/simulations/review-diff.json # Mock data for the inspector
+└── package.json
+```
 
-Automatically test any MCP server against replicated ChatGPT and Claude runtimes.
+Tools, resources, and simulations are auto-discovered from the file system. Multi-platform React hooks (`useToolData`, `useAppState`, `useTheme`, `useDisplayMode`) let you write your app logic once and deploy it across ChatGPT, Claude, and future hosts.
 
-```ts
-import { test, expect } from 'sunpeak/test';
+[App framework documentation →](https://sunpeak.ai/docs/mcp-apps-framework)
 
-test('review tool renders title', async ({ inspector }) => {
-  const result = await inspector.renderTool('review-diff');
-  const app = result.app();
-  await expect(app.locator('h1:has-text("Refactor")')).toBeVisible();
-});
-```
+---
 
-- **Works for any MCP server**: `sunpeak test init` scaffolds tests for Python, Go, TS, or any language
-- **MCP-native assertions**: `toBeError()`, `toHaveTextContent()`, `toHaveStructuredContent()`
-- **Multi-host**: Tests run against ChatGPT and Claude hosts automatically
-- **Live tests**: Automated browser tests against real ChatGPT via `sunpeak/test/live`
-- **Evals**: Test your tool interface design against multiple LLMs (GPT-4o, Claude, Gemini, etc.) via `sunpeak/eval`
+### 2. Testing Framework
 
-### 3. App Framework
+MCP Apps render inside host iframes with host-specific themes, display modes, and capabilities. Standard browser testing can't replicate this because the runtime environment only exists inside ChatGPT and Claude. Each app also has many dimensions of state: tool inputs, tool results, server tool responses, host context, and display configuration. Testing all combinations manually is slow and error-prone.
 
-Next.js for MCP Apps. Convention-over-configuration project structure with the inspector and testing built in.
+sunpeak replicates these host runtimes and provides simulation fixtures (JSON files that define reproducible tool states) so you can test every combination of host, theme, and data in CI without accounts or API credits.
 
 ```bash
-sunpeak-app/
-├── src/
-│   ├── resources/
-│   │   └── review/
-│   │       └── review.tsx            # Review UI component + resource metadata.
-│   ├── tools/
-│   │   ├── review-diff.ts            # Tool with handler, schema, and optional resource link.
-│   │   ├── review-post.ts            # Multiple tools can share one resource.
-│   │   └── review.ts                 # Backend-only tool (no resource, no UI).
-│   └── server.ts                     # Optional: auth, server config.
-├── tests/simulations/
-│   ├── review-diff.json              # Mock state for testing (includes serverTools).
-│   ├── review-post.json              # Mock state for testing (includes serverTools).
-│   └── review-purchase.json          # Mock state for testing (includes serverTools).
-└── package.json
+npx sunpeak test init --server http://localhost:8000/mcp
 ```
 
-- **Runtime APIs**: Strongly typed React hooks (`useToolData`, `useAppState`, `useHostContext`, etc.)
-- **Convention over configuration**: Resources, tools, and simulations are auto-discovered
-- **Multi-platform**: Build once, deploy to ChatGPT, Claude, and future hosts
-
-## Quickstart
-
-Requirements: Node (20+), pnpm (10+)
+This scaffolds E2E tests, visual regression, live host tests, and multi-model evals. Then run them:
 
 ```bash
-pnpm add -g sunpeak
-sunpeak new
+npx sunpeak test
 ```
 
-## CLI
+Playwright fixtures handle inspector startup, MCP connection, iframe traversal, and host switching. Works with Python, Go, TypeScript, Rust, or any language.
 
-**Testing** (works with any MCP server):
+```ts
+import { test, expect } from 'sunpeak/test';
 
-| Command                               | Description                                 |
-| ------------------------------------- | ------------------------------------------- |
-| `sunpeak inspect --server <url\|cmd>` | Inspect any MCP server in the inspector     |
-| `sunpeak test`                        | Run unit + e2e tests                        |
-| `sunpeak test --unit`                 | Run unit tests only (Vitest)                |
-| `sunpeak test --e2e`                  | Run e2e tests only (Playwright)             |
-| `sunpeak test --visual`               | Run e2e tests with visual regression        |
-| `sunpeak test --visual --update`      | Update visual regression baselines          |
-| `sunpeak test --live`                 | Run live tests against real hosts           |
-| `sunpeak test --eval`                 | Run evals against multiple LLM models       |
-| `sunpeak test init`                   | Scaffold test infrastructure into a project |
+test('search tool returns results', async ({ mcp }) => {
+  const result = await mcp.callTool('search', { query: 'headphones' });
+  expect(result.isError).toBeFalsy();
+});
 
-**App framework** (for sunpeak projects):
+test('album cards render', async ({ inspector }) => {
+  const result = await inspector.renderTool('show-albums');
+  await expect(result.app().locator('button:has-text("Summer Slice")')).toBeVisible();
+});
+```
 
-| Command                          | Description                                 |
-| -------------------------------- | ------------------------------------------- |
-| `sunpeak new [name] [resources]` | Create a new project                        |
-| `sunpeak dev`                    | Start dev server + inspector + MCP endpoint |
-| `sunpeak build`                  | Build resources + tools for production      |
-| `sunpeak start`                  | Start production MCP server                 |
-| `sunpeak upgrade`                | Upgrade sunpeak to latest version           |
+[Testing documentation →](https://sunpeak.ai/docs/testing/overview)
 
-## Coding Agent Skills
+---
 
-Install the sunpeak skills to give your coding agent (Claude Code, Cursor, etc.) built-in knowledge of sunpeak patterns, hooks, and testing:
+### 3. Inspector
+
+MCP servers are opaque. You can call tools and read the JSON responses, but you can't see how your app actually looks and behaves inside ChatGPT or Claude without deploying to each host, setting up a tunnel, paying for accounts, and manually refreshing through a multi-step cycle on every code change.
+
+The sunpeak inspector replicates the ChatGPT and Claude app runtimes locally. Point it at any MCP server and see your tools and resources rendered the same way they appear in production hosts.
 
 ```bash
-pnpm dlx skills add Sunpeak-AI/sunpeak@create-sunpeak-app Sunpeak-AI/sunpeak@test-mcp-server
+npx sunpeak inspect --server http://localhost:8000/mcp
 ```
 
-## Troubleshooting
-
-If your app doesn't render in ChatGPT or Claude:
+<div align="center">
+  <a href="https://sunpeak.ai/docs/mcp-apps-inspector">
+    <picture>
+      <img alt="Inspector" src="https://cdn.sunpeak.ai/chatgpt-simulator.png">
+    </picture>
+  </a>
+</div>
 
-1. **Check your tunnel** is running and pointing to the correct port
-2. **Restart `sunpeak dev`** to clear stale connections
-3. **Refresh or re-add the MCP server** in the host's settings (Settings > MCP Servers)
-4. **Hard refresh** the host page (`Cmd+Shift+R` / `Ctrl+Shift+R`)
-5. **Open a new chat** in the host (cached iframes persist per-conversation)
+Toggle between hosts, themes, display modes, and device types from the sidebar. Call real tool handlers or load simulation fixtures for deterministic mock data. Changes reflect instantly via HMR. Works with any MCP server in any language.
 
-Full guide: [sunpeak.ai/docs/app-framework/guides/troubleshooting](https://sunpeak.ai/docs/app-framework/guides/troubleshooting)
+[Inspector documentation →](https://sunpeak.ai/docs/mcp-apps-inspector)
 
 ## Resources
 
@@ -153,3 +122,4 @@ Full guide: [sunpeak.ai/docs/app-framework/guides/troubleshooting](https://sunpe
 - [MCP Overview](https://sunpeak.ai/docs/mcp-apps/mcp/overview) · [Tools](https://sunpeak.ai/docs/mcp-apps/mcp/tools) · [Resources](https://sunpeak.ai/docs/mcp-apps/mcp/resources)
 - [MCP Apps SDK](https://github.com/modelcontextprotocol/ext-apps)
 - [ChatGPT Apps SDK Design Guidelines](https://developers.openai.com/apps-sdk/concepts/design-guidelines)
+- [Troubleshooting](https://sunpeak.ai/docs/app-framework/guides/troubleshooting)

package/bin/commands/inspect.mjs

@@ -667,6 +667,45 @@ root.render(
  * @param {{ callToolDirect?: (name: string, args: Record<string, unknown>) => Promise<object>, simulationsDir?: string | null }} [pluginOpts]
  */
 function sunpeakInspectEndpointsPlugin(getClient, setClient, pluginOpts = {}) {
+  // Server URL and options for automatic session recovery.
+  // Set by inspectServer() after creating the initial connection.
+  let _serverUrl = '';
+  /** @type {Record<string, unknown>} */
+  let _connectionOpts = {};
+
+  /**
+   * Check if an error is a dead-session error (MCP server no longer recognizes
+   * the session ID). This happens when the MCP server restarts, the session
+   * times out, or the connection is interrupted.
+   * @param {Error} err
+   */
+  function isDeadSession(err) {
+    const msg = err?.message ?? '';
+    return msg.includes('Unknown session') || msg.includes('404') || msg.includes('fetch failed');
+  }
+
+  /**
+   * Attempt to reconnect to the MCP server and replace the current client.
+   * Returns true if reconnection succeeded.
+   */
+  async function tryReconnect() {
+    if (!_serverUrl) return false;
+    try {
+      console.warn(`[inspect] MCP session lost, reconnecting to ${_serverUrl}...`);
+      const newConn = await createMcpConnection(_serverUrl, _connectionOpts);
+      setClient(newConn.client);
+      console.log('[inspect] MCP session re-established');
+      return true;
+    } catch (err) {
+      console.error(`[inspect] MCP reconnection failed: ${err?.message ?? err}`);
+      return false;
+    }
+  }
+
+  // Initialize reconnection state from plugin options.
+  if (pluginOpts.serverUrl) _serverUrl = pluginOpts.serverUrl;
+  if (pluginOpts.connectionOpts) _connectionOpts = pluginOpts.connectionOpts;
+
   // In-memory OAuth state keyed by server URL, persisted across reconnects.
   /** @type {Map<string, { provider: any, getAuthUrl: () => URL | undefined, hasTokens: () => boolean, stateParam: string }>} */
   const oauthProviders = new Map();
@@ -680,7 +719,7 @@ function sunpeakInspectEndpointsPlugin(getClient, setClient, pluginOpts = {}) {
   return {
     name: 'sunpeak-inspect-endpoints',
     configureServer(server) {
-      // List tools from connected server
+      // List tools from connected server (with automatic session recovery)
       server.middlewares.use('/__sunpeak/list-tools', async (_req, res) => {
         try {
           const client = getClient();
@@ -688,6 +727,15 @@ function sunpeakInspectEndpointsPlugin(getClient, setClient, pluginOpts = {}) {
           res.writeHead(200, { 'Content-Type': 'application/json' });
           res.end(JSON.stringify(result));
         } catch (err) {
+          // If the session died (server restarted, timeout, etc.), try to reconnect once.
+          if (isDeadSession(err) && await tryReconnect()) {
+            try {
+              const result = await getClient().listTools();
+              res.writeHead(200, { 'Content-Type': 'application/json' });
+              res.end(JSON.stringify(result));
+              return;
+            } catch { /* fall through to error response */ }
+          }
           res.writeHead(500, { 'Content-Type': 'application/json' });
           res.end(JSON.stringify({ error: err.message }));
         }
@@ -732,6 +780,16 @@ function sunpeakInspectEndpointsPlugin(getClient, setClient, pluginOpts = {}) {
           res.writeHead(200, { 'Content-Type': 'application/json' });
           res.end(JSON.stringify(result));
         } catch (err) {
+          // Try reconnecting on dead session before returning error
+          if (isDeadSession(err) && await tryReconnect()) {
+            try {
+              const { name, arguments: args } = parsed;
+              const result = await getClient().callTool({ name, arguments: args });
+              res.writeHead(200, { 'Content-Type': 'application/json' });
+              res.end(JSON.stringify(result));
+              return;
+            } catch { /* fall through */ }
+          }
           res.writeHead(200, { 'Content-Type': 'application/json' });
           res.end(
             JSON.stringify({
@@ -1171,6 +1229,22 @@ function sunpeakInspectEndpointsPlugin(getClient, setClient, pluginOpts = {}) {
             res.end('');
           }
         } catch (err) {
+          // Try reconnecting on dead session before returning error
+          if (isDeadSession(err) && await tryReconnect()) {
+            try {
+              const retryResult = await getClient().readResource({ uri });
+              const retryContent = retryResult.contents?.[0];
+              if (retryContent) {
+                const mimeType = retryContent.mimeType || 'text/html';
+                res.writeHead(200, {
+                  'Content-Type': `${mimeType}; charset=utf-8`,
+                  'X-Content-Type-Options': 'nosniff',
+                });
+                res.end(typeof retryContent.text === 'string' ? retryContent.text : '');
+                return;
+              }
+            } catch { /* fall through */ }
+          }
           res.writeHead(500, { 'Content-Type': 'text/plain' });
           res.end(`Error reading resource: ${err.message}`);
         }
@@ -1308,6 +1382,23 @@ export async function inspectServer(opts) {
 
   console.log('Connected. Discovering tools and resources...');
 
+  // Monitor transport health. The MCP SDK opens a background SSE stream after
+  // initialization. If this stream drops, the server may purge the session,
+  // causing "Unknown session" errors on subsequent requests. Log lifecycle
+  // events so we can diagnose connection issues when they occur.
+  if (mcpConnection.transport) {
+    const origOnError = mcpConnection.transport.onerror;
+    mcpConnection.transport.onerror = (err) => {
+      console.warn(`[inspect] MCP transport error: ${err?.message ?? err}`);
+      origOnError?.(err);
+    };
+    const origOnClose = mcpConnection.transport.onclose;
+    mcpConnection.transport.onclose = () => {
+      console.warn('[inspect] MCP transport closed (session may be lost)');
+      origOnClose?.();
+    };
+  }
+
   // Extract app name and icon from server info (reported during MCP initialize)
   const serverInfo = mcpConnection.client.getServerVersion();
   const serverAppName = nameOverride ?? serverInfo?.name;
@@ -1387,7 +1478,7 @@ export async function inspectServer(opts) {
       sunpeakInspectEndpointsPlugin(
         () => mcpConnection.client,
         (newClient) => { mcpConnection.client = newClient; },
-        { callToolDirect: opts.callToolDirect, simulationsDir }
+        { callToolDirect: opts.callToolDirect, simulationsDir, serverUrl: resolvedServerUrl, connectionOpts }
       ),
       // Serve /dist/{name}/{name}.html from the project directory (for Prod Resources mode).
       // The Inspector polls these paths via HEAD to check if built resources exist.
@@ -1476,6 +1567,10 @@ export async function inspectServer(opts) {
       // Without this, Vite defaults to localhost which may resolve to IPv6-only
       // (::1) on macOS, causing ECONNREFUSED for IPv4 clients.
       host: '0.0.0.0',
+      // Allow any hostname so the inspector works behind tunnels, in containers,
+      // and with custom /etc/hosts entries. Without this, Vite 8's DNS rebinding
+      // protection blocks requests whose Host header isn't localhost/127.0.0.1.
+      allowedHosts: 'all',
       open: open ?? (!process.env.CI && !process.env.SUNPEAK_LIVE_TEST),
     },
     optimizeDeps: {

package/bin/commands/new.mjs

@@ -299,6 +299,28 @@ export async function init(projectName, resourcesArg, deps = defaultDeps) {
 
   // Install dependencies with spinner
   const pm = d.detectPackageManager();
+
+  // Replace package manager references in README
+  if (pm !== 'pnpm') {
+    const readmePath = join(targetDir, 'README.md');
+    if (d.existsSync(readmePath)) {
+      const run = pm === 'npm' ? 'npm run' : pm;
+      const dlx = pm === 'npm' ? 'npx' : 'yarn dlx';
+      let readme = d.readFileSync(readmePath, 'utf-8');
+      readme = readme.replace(/pnpm dev\b/g, `${run} dev`);
+      readme = readme.replace(/pnpm build\b/g, `${run} build`);
+      readme = readme.replace(/pnpm start\b/g, `${run} start`);
+      readme = readme.replace(/pnpm test\b/g, `${run} test`);
+      readme = readme.replace(/pnpm test:unit\b/g, `${run} test:unit`);
+      readme = readme.replace(/pnpm test:e2e\b/g, `${run} test:e2e`);
+      readme = readme.replace(/pnpm test:visual\b/g, `${run} test:visual`);
+      readme = readme.replace(/pnpm test:live\b/g, `${run} test:live`);
+      readme = readme.replace(/pnpm test:eval\b/g, `${run} test:eval`);
+      readme = readme.replace(/pnpm add\b/g, pm === 'npm' ? 'npm install' : `${pm} add`);
+      readme = readme.replace(/pnpm dlx\b/g, dlx);
+      d.writeFileSync(readmePath, readme);
+    }
+  }
   const s = d.spinner();
   s.start(`Installing dependencies with ${pm}...`);
 
@@ -366,30 +388,32 @@ export async function init(projectName, resourcesArg, deps = defaultDeps) {
       initialValue: true,
     });
     if (!clack.isCancel(installSkill) && installSkill) {
+      const dlx = pm === 'yarn' ? 'yarn dlx' : pm === 'npm' ? 'npx' : 'pnpm dlx';
       try {
-        d.execSync('pnpm dlx skills add Sunpeak-AI/sunpeak@create-sunpeak-app Sunpeak-AI/sunpeak@test-mcp-server', {
+        d.execSync(`${dlx} skills add Sunpeak-AI/sunpeak@create-sunpeak-app Sunpeak-AI/sunpeak@test-mcp-server`, {
           cwd: targetDir,
           stdio: 'inherit',
         });
       } catch {
-        d.console.log('Skill install skipped. You can install later with: pnpm dlx skills add Sunpeak-AI/sunpeak@create-sunpeak-app Sunpeak-AI/sunpeak@test-mcp-server');
+        d.console.log(`Skill install skipped. You can install later with: ${dlx} skills add Sunpeak-AI/sunpeak@create-sunpeak-app Sunpeak-AI/sunpeak@test-mcp-server`);
       }
     }
   }
 
+  const run = pm === 'npm' ? 'npm run' : pm;
   d.outro(`Done! To get started:
 
   cd ${projectName}
-  sunpeak dev
+  ${run} dev
 
 Your project commands:
 
-  sunpeak dev                # Start dev server + MCP endpoint
-  sunpeak build              # Build for production
-  sunpeak test               # Run unit + e2e tests
-  sunpeak test --eval        # Run LLM evals (configure models in tests/evals/eval.config.ts)
-  sunpeak test --visual      # Run visual regression tests
-  sunpeak test --live        # Run live tests against real AI hosts`);
+  ${run} dev              # Start dev server + MCP endpoint
+  ${run} build            # Build for production
+  ${run} test             # Run unit + e2e tests
+  ${run} test:eval        # Run LLM evals (configure models in tests/evals/eval.config.ts)
+  ${run} test:visual      # Run visual regression tests
+  ${run} test:live        # Run live tests against real AI hosts`);
 }
 
 // Allow running directly

package/bin/commands/test-init.mjs

@@ -153,13 +153,15 @@ export async function testInit(args = [], deps = defaultDeps) {
       initialValue: true,
     });
     if (!d.isCancel(installSkill) && installSkill) {
+      const pm = d.detectPackageManager();
+      const dlx = pm === 'yarn' ? 'yarn dlx' : pm === 'npm' ? 'npx' : 'pnpm dlx';
       try {
-        d.execSync('pnpm dlx skills add Sunpeak-AI/sunpeak@test-mcp-server', {
+        d.execSync(`${dlx} skills add Sunpeak-AI/sunpeak@test-mcp-server`, {
           cwd: d.cwd(),
           stdio: 'inherit',
         });
       } catch {
-        d.log.info('Skill install skipped. Install later: pnpm dlx skills add Sunpeak-AI/sunpeak@test-mcp-server');
+        d.log.info(`Skill install skipped. Install later: ${dlx} skills add Sunpeak-AI/sunpeak@test-mcp-server`);
       }
     }
   }
@@ -357,7 +359,7 @@ function scaffoldEvals(evalsDir, { server, isSunpeak, d: deps } = {}) {
  * 2. Install the AI SDK and provider packages (e.g. pnpm add ai @ai-sdk/openai)
  * 3. Copy .env.example to .env and add your API keys
  * 4. Replace this file with evals for your own tools
- * 5. Run: sunpeak test --eval
+ * 5. Run: npx sunpeak test --eval
  *
  * Each case sends a prompt to every configured model and checks
  * that the model calls the expected tool with the expected arguments.
@@ -403,10 +405,10 @@ function scaffoldVisualTest(filePath, d) {
 /**
  * Visual regression tests — compare screenshots against saved baselines.
  *
- * Screenshots only run with: sunpeak test --visual
- * Update baselines with:     sunpeak test --visual --update
+ * Screenshots only run with: npx sunpeak test --visual
+ * Update baselines with:     npx sunpeak test --visual --update
  *
- * During normal \`sunpeak test\` runs, screenshot() calls are silently
+ * During normal \`npx sunpeak test\` runs, screenshot() calls are silently
  * skipped so these tests still pass without baselines.
  *
  * Uncomment the tests below and replace 'your-tool' with your tool name.
@@ -465,7 +467,7 @@ function scaffoldLiveTests(liveDir, { isSunpeak, server, d } = {}) {
  * Prerequisites:
  * 1. Your MCP server must be accessible via a public URL (e.g., ngrok tunnel)
  * 2. The server must be registered as an MCP action in the host
- * 3. Run: sunpeak test --live
+ * 3. Run: npx sunpeak test --live
  *
  * On first run, a browser window opens for you to log in to the host.
  * The session is saved for subsequent runs (typically lasts a few hours).
@@ -508,9 +510,9 @@ export default defineLiveConfig({${serverOption}
  * - live.setColorScheme('dark', app) — switch theme while app is visible
  * - live.page — the underlying Playwright page
  *
- * Run with: sunpeak test --live
+ * Run with: npx sunpeak test --live
  *
- * These tests are excluded from normal \`sunpeak test\` runs because
+ * These tests are excluded from normal \`npx sunpeak test\` runs because
  * they require host accounts and cost API credits.
  */
 
@@ -553,7 +555,7 @@ function scaffoldUnitTest(filePath, d) {
  * Import your tool handler directly and test its input/output
  * without starting the MCP server or inspector.
  *
- * Run with: sunpeak test --unit
+ * Run with: npx sunpeak test --unit
  *
  * To set up vitest, add it to your devDependencies:
  *   npm install -D vitest
@@ -701,10 +703,10 @@ test('server exposes tools', async ({ mcp }) => {
   }
 
   d.log.step('Ready! Run tests with:');
-  d.log.message('  sunpeak test              # E2E tests');
-  d.log.message('  sunpeak test --visual      # Visual regression (generates baselines on first run)');
-  d.log.message('  sunpeak test --live         # Live tests against real hosts (requires login)');
-  d.log.message('  sunpeak test --eval         # Multi-model evals (configure models in evals/eval.config.ts)');
+  d.log.message('  npx sunpeak test              # E2E tests');
+  d.log.message('  npx sunpeak test --visual      # Visual regression (generates baselines on first run)');
+  d.log.message('  npx sunpeak test --live         # Live tests against real hosts (requires login)');
+  d.log.message('  npx sunpeak test --eval         # Multi-model evals (configure models in evals/eval.config.ts)');
 }
 
 async function initJsProject(cliServer, d) {
@@ -784,11 +786,11 @@ test('server exposes tools', async ({ mcp }) => {
   d.log.message(`  ${pkgMgr} add -D sunpeak @playwright/test vitest`);
   d.log.message(`  ${pkgMgr} exec playwright install chromium`);
   d.log.message('');
-  d.log.message('  sunpeak test              # E2E tests');
-  d.log.message('  sunpeak test --unit        # Unit tests (vitest)');
-  d.log.message('  sunpeak test --visual      # Visual regression');
-  d.log.message('  sunpeak test --live         # Live tests against real hosts');
-  d.log.message('  sunpeak test --eval         # Multi-model evals');
+  d.log.message('  npx sunpeak test              # E2E tests');
+  d.log.message('  npx sunpeak test --unit        # Unit tests (vitest)');
+  d.log.message('  npx sunpeak test --visual      # Visual regression');
+  d.log.message('  npx sunpeak test --live         # Live tests against real hosts');
+  d.log.message('  npx sunpeak test --eval         # Multi-model evals');
 }
 
 async function initSunpeakProject(d) {
@@ -835,10 +837,10 @@ export default defineConfig();
   scaffoldUnitTest(join(cwd, 'tests', 'unit', 'example.test.ts'), d);
 
   d.log.step('Scaffolded test types:');
-  d.log.message('  tests/e2e/visual.test.ts    — Visual regression (sunpeak test --visual)');
-  d.log.message('  tests/live/                 — Live host tests (sunpeak test --live)');
-  d.log.message('  tests/evals/                — Multi-model evals (sunpeak test --eval)');
-  d.log.message('  tests/unit/example.test.ts  — Unit tests (sunpeak test --unit)');
+  d.log.message('  tests/e2e/visual.test.ts    — Visual regression (npx sunpeak test --visual)');
+  d.log.message('  tests/live/                 — Live host tests (npx sunpeak test --live)');
+  d.log.message('  tests/evals/                — Multi-model evals (npx sunpeak test --eval)');
+  d.log.message('  tests/unit/example.test.ts  — Unit tests (npx sunpeak test --unit)');
   d.log.message('');
   d.log.message('  Migrate existing e2e tests:');
   d.log.message('  Replace: import { test, expect } from "@playwright/test"');

package/bin/sunpeak.js

@@ -102,22 +102,11 @@ function getVersion() {
       {
         const resources = discoverResources();
         console.log(`
-☀️ 🏔️ sunpeak - Inspector, testing framework, and app framework for MCP Apps
+☀️ 🏔️ sunpeak - App framework, testing framework, and inspector for MCP Apps
 
-Install:
-  pnpm add -g sunpeak
+Usage: npx sunpeak <command>
 
-Testing (works with any MCP server):
-  sunpeak inspect          Inspect any MCP server in the inspector
-    --server, -s <url|cmd> MCP server URL or stdio command (required)
-    --simulations <dir>    Simulation JSON directory
-  sunpeak test             Run e2e tests against the inspector
-    init                   Scaffold test infrastructure into a project
-    --unit                 Run unit tests (vitest)
-    --live                 Run live tests against real hosts
-    --eval                 Run evals against LLM models
-
-App framework (for sunpeak projects):
+App framework:
   sunpeak new [name] [resources]  Create a new project
   sunpeak dev              Start dev server + inspector + MCP endpoint
     --no-begging           Suppress GitHub star message
@@ -125,8 +114,20 @@ App framework (for sunpeak projects):
   sunpeak start            Start production MCP server
     --port, -p             Server port (default: 8000, or PORT env)
   sunpeak upgrade          Upgrade sunpeak to latest version
-  sunpeak --version        Show version number
 
+Testing (works with any MCP server):
+  sunpeak test             Run e2e tests against the inspector
+    init                   Scaffold test infrastructure into a project
+    --unit                 Run unit tests (vitest)
+    --live                 Run live tests against real hosts
+    --eval                 Run evals against LLM models
+
+Inspector (works with any MCP server):
+  sunpeak inspect          Inspect any MCP server in the inspector
+    --server, -s <url|cmd> MCP server URL or stdio command (required)
+    --simulations <dir>    Simulation JSON directory
+
+  sunpeak --version        Show version number
   Resources: ${resources.join(', ')} (comma/space separated)
   Example: sunpeak new sunpeak-app "${resources.slice(0, 2).join(',')}"
 `);

package/dist/chatgpt/index.cjs

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_chunk = require("../chunk-9hOWP6kD.cjs");
-const require_inspector = require("../inspector-DAA1Wiyh.cjs");
+const require_inspector = require("../inspector-D0qOqYX2.cjs");
 const require_inspector_url = require("../inspector-url-C3LTKgXt.cjs");
 const require_discovery = require("../discovery-Clu4uHp1.cjs");
 //#region src/chatgpt/index.ts

package/dist/chatgpt/index.js

@@ -1,5 +1,5 @@
 import { r as __exportAll } from "../chunk-D6g4UhsZ.js";
-import { _ as McpAppHost, d as ThemeProvider, f as useThemeContext, g as extractResourceCSP, h as IframeResource, n as resolveServerToolResult, t as Inspector, v as SCREEN_WIDTHS } from "../inspector-BBDa5yCm.js";
+import { _ as McpAppHost, d as ThemeProvider, f as useThemeContext, g as extractResourceCSP, h as IframeResource, n as resolveServerToolResult, t as Inspector, v as SCREEN_WIDTHS } from "../inspector-60Na_Zc4.js";
 import { t as createInspectorUrl } from "../inspector-url-CyQcuBI9.js";
 import { c as toPascalCase, i as findResourceKey, n as extractSimulationKey, r as findResourceDirs, s as getComponentName, t as extractResourceKey } from "../discovery-Cgoegt62.js";
 //#region src/chatgpt/index.ts

package/dist/claude/index.cjs

@@ -1,4 +1,4 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 require("../chunk-9hOWP6kD.cjs");
-const require_inspector = require("../inspector-DAA1Wiyh.cjs");
+const require_inspector = require("../inspector-D0qOqYX2.cjs");
 exports.Inspector = require_inspector.Inspector;

package/dist/claude/index.js

@@ -1,2 +1,2 @@
-import { t as Inspector } from "../inspector-BBDa5yCm.js";
+import { t as Inspector } from "../inspector-60Na_Zc4.js";
 export { Inspector };

package/dist/host/chatgpt/index.cjs

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 require("../../chunk-9hOWP6kD.cjs");
-const require_use_app = require("../../use-app-DPkj5Jp_.cjs");
+const require_use_app = require("../../use-app-B33mckz4.cjs");
 let react = require("react");
 //#region src/host/chatgpt/openai-types.ts
 /**

package/dist/host/chatgpt/index.js

@@ -1,4 +1,4 @@
-import { t as useApp } from "../../use-app-Cr0auUa1.js";
+import { t as useApp } from "../../use-app-kv5GQr0G.js";
 import { useCallback } from "react";
 //#region src/host/chatgpt/openai-types.ts
 /**