sunpeak 0.16.21 → 0.16.24

package/README.md

@@ -51,14 +51,15 @@ sunpeak new
 
 1. Runtime APIs: Strongly typed React hooks for interacting with the host runtime (`useApp`, `useToolData`, `useAppState`, `useHostContext`, `useUpdateModelContext`, `useAppTools`), architected to **support generic and platform-specific features** (ChatGPT, Claude, etc.). Host-specific hooks like `useUploadFile`, `useRequestModal`, and `useRequestCheckout` are available via `sunpeak/host/chatgpt`, with `isChatGPT()` / `isClaude()` host detection via `sunpeak/host`.
 2. Multi-host simulator: React component replicating host runtimes (ChatGPT, Claude) to **test Apps locally and automatically** via UI, props, or URL parameters.
-3. MCP server: Serve Resources with mock data to hosts like ChatGPT and Claude with HMR (**no more cache issues or 5-click manual refreshes**).
+3. Live testing: **Automated tests against real ChatGPT** — opens your browser, sends messages, validates your app renders correctly inside the real host. No more manual testing.
+4. MCP server: Serve Resources with mock data to hosts like ChatGPT and Claude with HMR (**no more cache issues or 5-click manual refreshes**).
 
 ### The `sunpeak` framework
 
-Next.js for MCP Apps. Using an example App `my-app` with a `Review` UI ([MCP resource](https://sunpeak.ai/docs/mcp-apps/mcp/resources)), `sunpeak` projects look like:
+Next.js for MCP Apps. Using an example App `sunpeak-app` with a `Review` UI ([MCP resource](https://sunpeak.ai/docs/mcp-apps/mcp/resources)), `sunpeak` projects look like:
 
 ```bash
-my-app/
+sunpeak-app/
 ├── src/
 │   ├── resources/
 │   │   └── review/

package/bin/commands/dev.mjs

@@ -6,6 +6,7 @@ const { join, resolve, basename, dirname } = path;
 import { createRequire } from 'module';
 import { pathToFileURL } from 'url';
 import { spawn } from 'child_process';
+import { getPort } from '../lib/get-port.mjs';
 
 /**
  * Import a module from the project's node_modules using ESM resolution
@@ -291,6 +292,16 @@ export async function dev(projectRoot = process.cwd(), args = []) {
       sunpeakFaviconPlugin(),
       sunpeakCallToolPlugin(),
       sunpeakDistPlugin(),
+      // Health endpoint for Playwright webServer readiness check
+      {
+        name: 'sunpeak-health',
+        configureServer(server) {
+          server.middlewares.use('/health', (_req, res) => {
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ status: 'ok' }));
+          });
+        },
+      },
     ],
     define: {
       '__SUNPEAK_PROD_TOOLS__': JSON.stringify(isProdTools),
@@ -307,7 +318,10 @@ export async function dev(projectRoot = process.cwd(), args = []) {
     },
     server: {
       port,
-      open: true,
+      // Don't auto-open browser when started by Playwright or CI
+      open: !process.env.CI && !process.env.SUNPEAK_LIVE_TEST,
+      // Allow tunnel hosts (ngrok, cloudflared, etc.) to reach the dev server
+      allowedHosts: 'all',
     },
   });
 
@@ -471,6 +485,10 @@ export async function dev(projectRoot = process.cwd(), args = []) {
 
   // Start MCP server with its own Vite instance for HMR
   if (simulations.length > 0) {
+    // Find available ports for the MCP server and HMR WebSocket
+    const mcpPort = await getPort(8000);
+    const hmrPort = await getPort(Number(process.env.SUNPEAK_HMR_PORT || 24679));
+
     console.log(`\nStarting MCP server with ${simulations.length} simulation(s) (Vite HMR)...`);
 
     // Virtual entry module plugin for MCP
@@ -538,7 +556,7 @@ if (import.meta.hot) {
       },
       server: {
         middlewareMode: true,
-        hmr: { port: Number(process.env.SUNPEAK_HMR_PORT || 24679) },
+        hmr: { port: hmrPort },
         allowedHosts: true,
         watch: {
           // Only watch files that affect the UI bundle (not JSON, tests, etc.)
@@ -564,7 +582,8 @@ if (import.meta.hot) {
       name: pkg.name || 'Sunpeak',
       version: pkg.version || '0.1.0',
       simulations,
-      port: 8000,
+      port: mcpPort,
+      hmrPort,
       // In --prod-resources mode, don't pass viteServer so the MCP server serves pre-built HTML.
       // Otherwise, pass it so ChatGPT gets Vite HMR.
       viteServer: isProdResources ? undefined : mcpViteServer,

package/bin/commands/new.mjs

@@ -19,8 +19,8 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 async function defaultPromptName() {
   const value = await clack.text({
     message: 'Project name',
-    placeholder: 'my-app',
-    defaultValue: 'my-app',
+    placeholder: 'sunpeak-app',
+    defaultValue: 'sunpeak-app',
     validate: (v) => {
       if (v === 'template') return '"template" is a reserved name';
     },
@@ -203,6 +203,10 @@ export async function init(projectName, resourcesArg, deps = defaultDeps) {
         if (src.includes('/tests/e2e/') && name === `${resource}.spec.ts`) {
           return false;
         }
+        // Skip live test files for excluded resources
+        if (src.includes('/tests/live/') && name === `${resource}.spec.ts`) {
+          return false;
+        }
       }
 
       return true;

package/bin/commands/start.mjs

@@ -3,6 +3,7 @@ import { existsSync, readFileSync, readdirSync } from 'fs';
 import { join, dirname } from 'path';
 import { createRequire } from 'module';
 import { pathToFileURL } from 'url';
+import { getPort } from '../lib/get-port.mjs';
 
 /**
  * Start a production MCP server from built artifacts.
@@ -183,6 +184,9 @@ export async function start(projectRoot = process.cwd(), args = []) {
   const name = serverConfig.name ?? pkg.name ?? 'sunpeak-app';
   const version = serverConfig.version ?? pkg.version ?? '0.1.0';
 
+  // Find an available port (prefer the configured one)
+  port = await getPort(port);
+
   console.log(`\nStarting ${name} v${version} on ${host}:${port}...`);
 
   startProductionHttpServer(

package/bin/lib/get-port.mjs

@@ -0,0 +1,60 @@
+import { createServer } from 'net';
+import { execSync } from 'child_process';
+
+/**
+ * Synchronous version of getPort — safe to call at Playwright config load time.
+ * Spawns a tiny Node child process that binds, prints the port, and exits.
+ *
+ * @param {number} preferred - Port to try first
+ * @returns {number} The available port number
+ */
+export function getPortSync(preferred) {
+  const script = `
+    const s = require("net").createServer();
+    s.listen(${preferred}, () => {
+      process.stdout.write(String(s.address().port));
+      s.close();
+    });
+    s.on("error", () => {
+      const f = require("net").createServer();
+      f.listen(0, () => {
+        process.stdout.write(String(f.address().port));
+        f.close();
+      });
+    });
+  `;
+  return Number(execSync(`node -e '${script}'`, { encoding: 'utf-8' }).trim());
+}
+
+/**
+ * Find an available TCP port, preferring the given port.
+ * If the preferred port is in use, returns a random available port.
+ *
+ * Listens without specifying a host so Node.js uses dual-stack `::`,
+ * which detects conflicts on both IPv4 and IPv6 interfaces.
+ *
+ * @param {number} preferred - Port to try first (default: 0 = any available)
+ * @returns {Promise<number>} The available port number
+ */
+export function getPort(preferred = 0) {
+  return new Promise((resolve, reject) => {
+    const server = createServer();
+    server.listen(preferred, () => {
+      const { port } = server.address();
+      server.close(() => resolve(port));
+    });
+    server.on('error', (err) => {
+      if (err.code === 'EADDRINUSE' && preferred !== 0) {
+        // Preferred port is busy — get any available port
+        const fallback = createServer();
+        fallback.listen(0, () => {
+          const { port } = fallback.address();
+          fallback.close(() => resolve(port));
+        });
+        fallback.on('error', reject);
+      } else {
+        reject(err);
+      }
+    });
+  });
+}

package/bin/lib/live/browser-auth.mjs

@@ -0,0 +1,125 @@
+import { mkdtempSync, mkdirSync, cpSync, existsSync } from 'fs';
+import { join } from 'path';
+import { tmpdir, homedir } from 'os';
+import { rimrafSync, ANTI_BOT_ARGS, CHROME_USER_AGENT } from './utils.mjs';
+
+/**
+ * Browser profile paths on macOS.
+ * Each entry maps a browser name to its user data directory.
+ */
+const BROWSER_PROFILES = {
+  chrome: join(homedir(), 'Library/Application Support/Google/Chrome'),
+  arc: join(homedir(), 'Library/Application Support/Arc/User Data'),
+  brave: join(homedir(), 'Library/Application Support/BraveSoftware/Brave-Browser'),
+  edge: join(homedir(), 'Library/Application Support/Microsoft Edge'),
+};
+
+/**
+ * Subdirectories/files to copy from the browser profile.
+ * These contain session cookies and local storage — enough for authenticated browsing.
+ * Copying only these keeps the operation fast (<2s) vs copying the full profile (500MB+).
+ */
+const ESSENTIAL_PATHS = [
+  'Default/Cookies',
+  'Default/Cookies-journal',
+  'Default/Local Storage',
+  'Default/Session Storage',
+  'Default/IndexedDB',
+  'Default/Login Data',
+  'Default/Login Data-journal',
+  'Default/Preferences',
+  'Default/Secure Preferences',
+  'Default/Web Data',
+  'Local State',
+];
+
+/**
+ * Detect which browser the user has installed.
+ * Returns the first available browser from the preference order.
+ */
+export function detectBrowser() {
+  const order = ['chrome', 'arc', 'brave', 'edge'];
+  for (const browser of order) {
+    if (existsSync(BROWSER_PROFILES[browser])) {
+      return browser;
+    }
+  }
+  return null;
+}
+
+/**
+ * Copy essential browser profile data to a temp directory.
+ * Returns the temp directory path.
+ */
+function copyProfile(browser) {
+  const profileDir = BROWSER_PROFILES[browser];
+  if (!profileDir || !existsSync(profileDir)) {
+    throw new Error(
+      `Browser profile not found for "${browser}" at ${profileDir || '(unknown)'}.\n` +
+      `Available browsers: ${Object.entries(BROWSER_PROFILES)
+        .filter(([, p]) => existsSync(p))
+        .map(([name]) => name)
+        .join(', ') || 'none detected'}`
+    );
+  }
+
+  const tempDir = mkdtempSync(join(tmpdir(), 'sunpeak-live-'));
+
+  for (const relativePath of ESSENTIAL_PATHS) {
+    const src = join(profileDir, relativePath);
+    if (!existsSync(src)) continue;
+
+    const dest = join(tempDir, relativePath);
+    try {
+      cpSync(src, dest, { recursive: true });
+    } catch {
+      // Some files may be locked; skip silently
+    }
+  }
+
+  // Ensure Default directory exists even if no essential files were copied.
+  // Use an allowlist to avoid copying large cache/media directories.
+  const defaultDir = join(tempDir, 'Default');
+  if (!existsSync(defaultDir)) {
+    mkdirSync(defaultDir, { recursive: true });
+  }
+
+  return tempDir;
+}
+
+/**
+ * Launch a Playwright Chromium browser authenticated with the user's real browser session.
+ *
+ * Copies the user's browser profile to a temp directory, then launches Playwright
+ * with that profile. The returned cleanup function removes the temp directory.
+ *
+ * @param {Object} options
+ * @param {string} [options.browser='chrome'] - Browser to copy profile from
+ * @param {boolean} [options.headless=false] - Run headless (usually false for live tests)
+ * @returns {Promise<{ context: BrowserContext, page: Page, cleanup: () => void }>}
+ */
+export async function launchAuthenticatedBrowser({ browser = 'chrome', headless = false } = {}) {
+  const { chromium } = await import('playwright');
+
+  const tempDir = copyProfile(browser);
+
+  const context = await chromium.launchPersistentContext(tempDir, {
+    headless,
+    args: ANTI_BOT_ARGS,
+    viewport: { width: 1280, height: 900 },
+    ignoreDefaultArgs: ['--enable-automation'],
+    userAgent: CHROME_USER_AGENT,
+  });
+
+  const page = context.pages()[0] || await context.newPage();
+
+  const cleanup = () => {
+    try {
+      rimrafSync(tempDir);
+    } catch {
+      // Best effort cleanup
+    }
+  };
+
+  return { context, page, cleanup };
+}

package/bin/lib/live/chatgpt-config.d.mts

@@ -0,0 +1,5 @@
+import type { PlaywrightTestConfig } from '@playwright/test';
+import type { LiveConfigOptions } from './live-config.d.mts';
+
+/** Create a complete Playwright config for live ChatGPT testing. */
+export declare function defineLiveConfig(options?: LiveConfigOptions): PlaywrightTestConfig;

package/bin/lib/live/chatgpt-config.mjs

@@ -0,0 +1,12 @@
+/**
+ * Playwright config for live ChatGPT tests.
+ *
+ * Usage in playwright.config.ts:
+ *   import { defineLiveConfig } from 'sunpeak/test/chatgpt/config';
+ *   export default defineLiveConfig();
+ */
+import { createLiveConfig } from './live-config.mjs';
+
+export function defineLiveConfig(options = {}) {
+  return createLiveConfig({ hostId: 'chatgpt' }, options);
+}

package/bin/lib/live/chatgpt-fixtures.d.mts

@@ -0,0 +1,12 @@
+import type { LiveFixture } from './types.d.mts';
+
+/** ChatGPT-specific fixture (alias of LiveFixture for backwards compatibility). */
+export type ChatGPTFixture = LiveFixture;
+
+export declare const test: {
+  (title: string, fn: (args: { chatgpt: ChatGPTFixture } & Record<string, any>) => Promise<void>): void;
+  describe: (title: string, fn: () => void) => void;
+  skip: (title: string, fn: (args: { chatgpt: ChatGPTFixture } & Record<string, any>) => Promise<void>) => void;
+};
+
+export declare const expect: (...args: any[]) => any;

package/bin/lib/live/chatgpt-fixtures.mjs

@@ -0,0 +1,25 @@
+/**
+ * Playwright fixtures for live ChatGPT testing.
+ *
+ * Provides a `chatgpt` fixture that handles login, MCP server refresh,
+ * and app name prefixing — so user test files only need assertions.
+ *
+ * Usage:
+ *   import { test, expect } from 'sunpeak/test/chatgpt';
+ *
+ *   test('my resource renders', async ({ chatgpt }) => {
+ *     const app = await chatgpt.invoke('show me something');
+ *     await expect(app.locator('img').first()).toBeVisible();
+ *   });
+ */
+import { ChatGPTPage } from './chatgpt-page.mjs';
+import { createHostFixtures } from './host-fixtures.mjs';
+
+const { test, expect } = createHostFixtures({
+  fixtureName: 'chatgpt',
+  HostPageClass: ChatGPTPage,
+  /** ChatGPT requires /{appName} prefix to invoke MCP apps. */
+  formatMessage: (appName, text) => `/${appName} ${text}`,
+});
+
+export { test, expect };

package/bin/lib/live/chatgpt-page.mjs

@@ -0,0 +1,210 @@
+/**
+ * ChatGPT host page object for live testing.
+ *
+ * All ChatGPT-specific DOM selectors and interaction logic lives here.
+ * When ChatGPT updates their UI, only this file needs updating.
+ *
+ * Extends HostPage which provides shared behavior (sendMessage, login, etc.).
+ */
+import { HostPage } from './host-page.mjs';
+
+/**
+ * All ChatGPT DOM selectors in one place for easy maintenance.
+ *
+ * Last verified: 2026-03-17 via live Playwright inspection.
+ */
+const SELECTORS = {
+  // Chat interface
+  chatInput: '#prompt-textarea',
+  sendButton: '[data-testid="send-button"]',
+  newChatLink: 'a:has-text("New chat")',
+
+  // Login detection — ChatGPT renders two profile buttons (sidebar compact + expanded); always use .first().
+  loggedInIndicator: '[data-testid="accounts-profile-button"]',
+  loginPage: 'button:has-text("Log in")',
+
+  // Settings navigation
+  appsTab: '[role="tab"]:has-text("Apps")',
+  refreshButton: 'button:has-text("Refresh")',
+  reconnectButton: 'button:has-text("Reconnect")',
+
+  // App iframe — ChatGPT uses a nested iframe structure:
+  //   outer: iframe[sandbox] (connector sandbox, no direct content)
+  //   inner: iframe name="root" (actual app React content)
+  mcpAppOuterIframe: 'iframe[sandbox*="allow-scripts"]',
+  mcpAppInnerFrameName: 'root',
+
+  // Streaming indicator
+  stopButton: 'button[aria-label="Stop streaming"], button:has-text("Stop")',
+};
+
+const URLS = {
+  base: 'https://chatgpt.com',
+  settings: 'https://chatgpt.com/#settings/Connectors',
+};
+
+export { SELECTORS as CHATGPT_SELECTORS, URLS as CHATGPT_URLS };
+
+export class ChatGPTPage extends HostPage {
+  get hostId() { return 'chatgpt'; }
+  get hostName() { return 'ChatGPT'; }
+  get selectors() { return SELECTORS; }
+  get urls() { return URLS; }
+
+  /**
+   * Refresh the MCP server connection in ChatGPT settings.
+   * Navigates to Settings > Apps, clicks the app entry, clicks Refresh,
+   * and waits for the success/error toast.
+   */
+  async refreshMcpServer({ tunnelUrl, appName } = {}) {
+    await this.page.goto(URLS.settings, { waitUntil: 'domcontentloaded' });
+    await this.page.waitForTimeout(3_000);
+
+    const found = await this._findAndClickRefresh(appName);
+
+    if (!found) {
+      const appsTab = this.page.locator(SELECTORS.appsTab);
+      const hasAppsTab = await appsTab.isVisible().catch(() => false);
+      if (hasAppsTab) {
+        await appsTab.click();
+        await this.page.waitForTimeout(2_000);
+        const retryFound = await this._findAndClickRefresh(appName);
+        if (!retryFound) {
+          await this._screenshotAndThrow('refresh-mcp-settings', tunnelUrl);
+        }
+      } else {
+        await this._screenshotAndThrow('no-apps-tab', tunnelUrl);
+      }
+    }
+
+    // Wait for the refresh toast
+    const { hasError, errorText } = await this._waitForToast();
+    if (hasError) {
+      throw new Error(
+        `MCP server refresh failed in ChatGPT:\n${errorText.trim()}\n\n` +
+        `Make sure your MCP dev server is running (pnpm dev) and your tunnel is active.`
+      );
+    }
+
+    // Wait for resource preloading to complete
+    await this.page.waitForTimeout(3_000);
+
+    // Navigate back to chat
+    await this.page.goto(URLS.base, { waitUntil: 'domcontentloaded' });
+    await this.page.locator(SELECTORS.chatInput).waitFor({ timeout: 10_000 });
+  }
+
+  /**
+   * Wait for a MCP app iframe to appear in the conversation.
+   * ChatGPT renders apps in a nested iframe (outer sandbox > inner #root).
+   */
+  async waitForAppIframe({ timeout = 90_000 } = {}) {
+    // Wait for streaming to finish
+    try {
+      await this.page.locator(SELECTORS.stopButton).waitFor({ state: 'hidden', timeout });
+    } catch {
+      // Stop button may never appear if response was instant
+    }
+
+    // Wait for the outer sandbox iframe
+    await this.page.locator(SELECTORS.mcpAppOuterIframe).first().waitFor({ state: 'attached', timeout: 30_000 });
+
+    // Wait for the inner frame to appear inside the sandboxed outer iframe.
+    // waitForFunction can't cross the sandbox boundary, so use Playwright's frameLocator instead.
+    const outerFrame = this.page.frameLocator(SELECTORS.mcpAppOuterIframe).first();
+    await outerFrame
+      .locator(`iframe[name="${SELECTORS.mcpAppInnerFrameName}"], iframe#${SELECTORS.mcpAppInnerFrameName}`)
+      .waitFor({ state: 'attached', timeout: 15_000 });
+
+    const appFrame = this.getAppIframe();
+
+    // Wait for content to render
+    try {
+      await appFrame.locator('body *').first().waitFor({ state: 'visible', timeout: 15_000 });
+    } catch {
+      // Caller's assertions will catch missing content
+    }
+
+    return appFrame;
+  }
+
+  getAppIframe() {
+    const name = SELECTORS.mcpAppInnerFrameName;
+    const outerFrame = this.page.frameLocator(SELECTORS.mcpAppOuterIframe).first();
+    return outerFrame.frameLocator(`iframe[name="${name}"], iframe#${name}`);
+  }
+
+  /**
+   * Send a message, pausing around the space after the /{appName} prefix.
+   * ChatGPT needs a moment to associate the app before the rest of the prompt is typed.
+   */
+  async sendMessage(text) {
+    const input = this.page.locator(SELECTORS.chatInput);
+    await input.waitFor({ timeout: 10_000 });
+    await input.click();
+
+    if (text.startsWith('/')) {
+      const spaceIdx = text.indexOf(' ');
+      if (spaceIdx !== -1) {
+        await input.pressSequentially(text.slice(0, spaceIdx), { delay: 10 });
+        await this.page.waitForTimeout(500);
+        await input.pressSequentially(' ', { delay: 10 });
+        await this.page.waitForTimeout(500);
+        await input.pressSequentially(text.slice(spaceIdx + 1), { delay: 10 });
+      } else {
+        await input.pressSequentially(text, { delay: 10 });
+      }
+    } else {
+      await input.pressSequentially(text, { delay: 10 });
+    }
+
+    const sendBtn = this.page.locator(SELECTORS.sendButton);
+    await sendBtn.waitFor({ state: 'visible', timeout: 10_000 });
+    await sendBtn.click();
+  }
+
+  // --- ChatGPT-specific private methods ---
+
+  /** @private */
+  async _findAndClickRefresh(appName) {
+    const refreshBtn = this.page.locator(SELECTORS.refreshButton).first();
+    const reconnectBtn = this.page.locator(SELECTORS.reconnectButton).first();
+
+    const tryClickRefresh = async () => {
+      if (await refreshBtn.isVisible().catch(() => false)) {
+        await refreshBtn.click();
+        return true;
+      }
+      if (await reconnectBtn.isVisible().catch(() => false)) {
+        await reconnectBtn.click();
+        return true;
+      }
+      return false;
+    };
+
+    if (await tryClickRefresh()) return true;
+
+    if (appName) {
+      const strategies = [
+        () => this.page.getByText(appName, { exact: true }).first(),
+        () => this.page.locator(`text=${appName}`).first(),
+        () => this.page.locator(`a:has-text("${appName}"), [role="button"]:has-text("${appName}")`).first(),
+      ];
+
+      for (const getLocator of strategies) {
+        try {
+          const el = getLocator();
+          if (await el.isVisible().catch(() => false)) {
+            await el.click();
+            await this.page.waitForTimeout(2_000);
+            if (await tryClickRefresh()) return true;
+          }
+        } catch {
+          // Strategy didn't work, try next
+        }
+      }
+    }
+
+    return false;
+  }
+}