sunpeak 0.16.21 → 0.16.24

package/bin/lib/live/global-setup.mjs

@@ -0,0 +1,150 @@
+/**
+ * Global setup for live tests.
+ *
+ * Runs exactly once before all workers. Two responsibilities:
+ *  1. Authenticate — import cookies from the user's real browser or open a
+ *     manual login window. Session state is saved to disk for 24 hours.
+ *  2. Refresh MCP server — navigate to host settings and click Refresh so
+ *     all workers start with pre-loaded resources.
+ *
+ * This file is referenced by the Playwright config created by defineLiveConfig().
+ * The auth file path is passed via SUNPEAK_AUTH_FILE env var.
+ */
+import { existsSync, mkdirSync, statSync } from 'fs';
+import { dirname } from 'path';
+import { ANTI_BOT_ARGS, CHROME_USER_AGENT, resolvePlaywright, getAppName } from './utils.mjs';
+import { launchAuthenticatedBrowser, detectBrowser } from './browser-auth.mjs';
+import { ChatGPTPage, CHATGPT_SELECTORS, CHATGPT_URLS } from './chatgpt-page.mjs';
+
+/** Auth state expires after 24 hours — ChatGPT session cookies are short-lived. */
+const MAX_AGE_MS = 24 * 60 * 60 * 1000;
+
+/** Reuse selectors and URLs from the canonical ChatGPT page object. */
+const CHATGPT_URL = CHATGPT_URLS.base;
+const LOGIN_SELECTOR = CHATGPT_SELECTORS.loggedInIndicator;
+
+function isAuthFresh(authFile) {
+  if (!existsSync(authFile)) return false;
+  const age = Date.now() - statSync(authFile).mtimeMs;
+  return age < MAX_AGE_MS;
+}
+
+/**
+ * Refresh the MCP server connection in ChatGPT settings.
+ * Opens a browser with the saved auth, navigates to settings, clicks Refresh,
+ * then closes. Runs once so parallel test workers don't each refresh.
+ */
+async function refreshMcpServer(authFile) {
+  const projectRoot = process.env.SUNPEAK_PROJECT_ROOT || process.cwd();
+  const appName = getAppName(projectRoot);
+  const { chromium } = resolvePlaywright(projectRoot);
+
+  const browser = await chromium.launch({
+    headless: false,
+    args: ANTI_BOT_ARGS,
+  });
+  const context = await browser.newContext({
+    userAgent: CHROME_USER_AGENT,
+    storageState: authFile,
+  });
+  const page = await context.newPage();
+
+  try {
+    const hostPage = new ChatGPTPage(page);
+    await hostPage.refreshMcpServer({ appName });
+    console.log('MCP server refreshed.');
+  } finally {
+    await browser.close();
+  }
+}
+
+export default async function globalSetup() {
+  // If storage state was provided externally, skip auth but still refresh.
+  const authFile = process.env.SUNPEAK_AUTH_FILE;
+
+  if (!process.env.SUNPEAK_STORAGE_STATE) {
+    if (!authFile) {
+      console.warn('SUNPEAK_AUTH_FILE not set — skipping auth setup.');
+      return;
+    }
+
+    if (!isAuthFresh(authFile)) {
+      await authenticate(authFile);
+    }
+  }
+
+  // Refresh MCP server connection so all workers start with pre-loaded resources.
+  const resolvedAuth = process.env.SUNPEAK_STORAGE_STATE || authFile;
+  if (resolvedAuth && existsSync(resolvedAuth)) {
+    await refreshMcpServer(resolvedAuth);
+  }
+}
+
+/**
+ * Authenticate by importing cookies from the user's browser or manual login.
+ */
+async function authenticate(authFile) {
+  // Try importing cookies from the user's real browser profile.
+  const browserName = process.env.SUNPEAK_LIVE_BROWSER || detectBrowser();
+  if (browserName) {
+    let auth;
+    try {
+      auth = await launchAuthenticatedBrowser({ browser: browserName, headless: false });
+      const page = auth.page;
+
+      await page.goto(CHATGPT_URL, { waitUntil: 'domcontentloaded' });
+
+      const loggedIn = await page
+        .locator(LOGIN_SELECTOR)
+        .first()
+        .waitFor({ timeout: 15_000 })
+        .then(() => true)
+        .catch(() => false);
+
+      if (loggedIn) {
+        mkdirSync(dirname(authFile), { recursive: true });
+        await auth.context.storageState({ path: authFile });
+        console.log(`Session imported from ${browserName} browser.`);
+      }
+
+      await auth.context.close();
+      auth.cleanup();
+
+      if (loggedIn) return;
+      // Not logged in — fall through to manual login.
+    } catch {
+      // Profile copy failed — clean up and fall through to manual login.
+      if (auth) {
+        try { await auth.context.close(); } catch {}
+        auth.cleanup();
+      }
+    }
+  }
+
+  // Fallback: open a bare browser for the user to log in manually.
+  console.log('\nNo saved ChatGPT session found (or session expired).');
+  console.log('Opening browser — please log in to chatgpt.com.\n');
+
+  const projectRoot = process.env.SUNPEAK_PROJECT_ROOT || process.cwd();
+  const { chromium } = resolvePlaywright(projectRoot);
+
+  const browser = await chromium.launch({
+    headless: false,
+    args: ANTI_BOT_ARGS,
+  });
+
+  const context = await browser.newContext({
+    userAgent: CHROME_USER_AGENT,
+  });
+
+  const page = await context.newPage();
+  await page.goto(CHATGPT_URL, { waitUntil: 'domcontentloaded' });
+
+  console.log('Waiting for login... (this will timeout after 5 minutes)\n');
+  await page.locator(LOGIN_SELECTOR).first().waitFor({ timeout: 300_000 });
+  console.log('Logged in! Saving session...\n');
+
+  mkdirSync(dirname(authFile), { recursive: true });
+  await context.storageState({ path: authFile });
+  await browser.close();
+}

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

@@ -0,0 +1,61 @@
+/**
+ * Factory for creating host-specific Playwright fixtures.
+ *
+ * Each host (ChatGPT, Claude) creates its own fixtures by calling
+ * createHostFixtures() with its HostPage subclass and message formatting.
+ *
+ * This keeps the fixture logic DRY — login, refresh, invoke, and
+ * app name handling are shared across all hosts.
+ */
+import { resolvePlaywrightESM, getAppName } from './utils.mjs';
+
+// Resolve @playwright/test from the user's project (pnpm strict resolution).
+const projectRoot = process.env.SUNPEAK_PROJECT_ROOT || process.cwd();
+const { test: base, expect } = await resolvePlaywrightESM(projectRoot);
+
+/** App name from the project's package.json — read once at module load. */
+const appName = getAppName(projectRoot);
+
+/**
+ * Create Playwright test fixtures for a specific host.
+ *
+ * @param {Object} options
+ * @param {string} options.fixtureName - Fixture name in test signatures (e.g., 'chatgpt', 'claude')
+ * @param {typeof import('./host-page.mjs').HostPage} options.HostPageClass - Host page class
+ * @param {(appName: string, text: string) => string} [options.formatMessage] - Format user messages (e.g., add /{appName} prefix)
+ */
+export function createHostFixtures({ fixtureName, HostPageClass, formatMessage }) {
+  const test = base.extend({
+    [fixtureName]: async ({ page }, use) => {
+      const hostPage = new HostPageClass(page);
+      await hostPage.verifyLoggedIn();
+
+      // MCP server refresh is handled once in globalSetup — no per-worker refresh needed.
+
+      // Enhanced interface with app name handling and invoke() shortcut
+      const fixture = Object.create(hostPage);
+
+      if (formatMessage) {
+        fixture.sendMessage = async (text) => {
+          return hostPage.sendMessage(formatMessage(appName, text));
+        };
+      }
+      fixture.sendRawMessage = hostPage.sendMessage.bind(hostPage);
+
+      /**
+       * One-liner: start a new chat, send a prompt, and wait for the app iframe.
+       * Returns the FrameLocator for the rendered app — ready for assertions.
+       */
+      fixture.invoke = async (prompt, options) => {
+        await hostPage.startNewChat();
+        const message = formatMessage ? formatMessage(appName, prompt) : prompt;
+        await hostPage.sendMessage(message);
+        return hostPage.waitForAppIframe(options);
+      };
+
+      await use(fixture);
+    },
+  });
+
+  return { test, expect };
+}

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

@@ -0,0 +1,242 @@
+/**
+ * Base class for host page objects (ChatGPT, Claude, etc.).
+ *
+ * Each host subclass provides:
+ *   - selectors: DOM selectors for the host's UI
+ *   - urls: host-specific URLs
+ *   - Host-specific overrides for login detection, MCP refresh, iframe access
+ *
+ * Shared behavior (sendMessage flow, screenshot debugging, selector health checks)
+ * lives here and is inherited by all hosts.
+ */
+
+/**
+ * @typedef {Object} HostSelectors
+ * @property {string} chatInput - Chat input field
+ * @property {string} sendButton - Send message button
+ * @property {string} newChatLink - "New chat" link/button
+ * @property {string} loggedInIndicator - Element visible when logged in
+ * @property {string} loginPage - Element visible on login page
+ * @property {string} stopButton - Streaming stop button
+ */
+
+/**
+ * @typedef {Object} HostUrls
+ * @property {string} base - Host base URL (e.g., 'https://chatgpt.com')
+ * @property {string} settings - MCP settings URL
+ * @property {string} loginTestId - Test ID for login detection (if using getByTestId)
+ */
+
+export class HostPage {
+  /**
+   * @param {import('playwright').Page} page
+   */
+  constructor(page) {
+    this.page = page;
+  }
+
+  /** @returns {string} Host identifier ('chatgpt' | 'claude') */
+  get hostId() {
+    throw new Error('Subclass must implement hostId');
+  }
+
+  /** @returns {string} Host display name */
+  get hostName() {
+    throw new Error('Subclass must implement hostName');
+  }
+
+  /** @returns {HostSelectors} */
+  get selectors() {
+    throw new Error('Subclass must implement selectors');
+  }
+
+  /** @returns {HostUrls} */
+  get urls() {
+    throw new Error('Subclass must implement urls');
+  }
+
+  /**
+   * Check that key selectors still resolve on the current page.
+   * Logs warnings instead of failing so tests can still attempt to run.
+   */
+  async checkSelectorsHealth() {
+    const criticalSelectors = [
+      ['chatInput', this.selectors.chatInput],
+      ['loggedInIndicator', this.selectors.loggedInIndicator],
+    ];
+
+    const warnings = [];
+    for (const [name, selector] of criticalSelectors) {
+      try {
+        const count = await this.page.locator(selector).first().count();
+        if (count === 0) {
+          warnings.push(`  "${name}" selector not found: ${selector}`);
+        }
+      } catch {
+        warnings.push(`  "${name}" selector error: ${selector}`);
+      }
+    }
+
+    if (warnings.length > 0) {
+      console.warn(
+        `\n⚠️  ${this.hostName} DOM may have changed — update selectors in ${this.hostId}-page.mjs:\n` +
+        warnings.join('\n') + '\n'
+      );
+    }
+
+    return warnings.length === 0;
+  }
+
+  /**
+   * Verify the user is logged into the host.
+   * Navigates to the host if not already there.
+   */
+  async verifyLoggedIn() {
+    const url = this.page.url();
+    if (!url.includes(new URL(this.urls.base).hostname)) {
+      await this.page.goto(this.urls.base, { waitUntil: 'domcontentloaded' });
+    }
+
+    const loggedIn = this.page.locator(this.selectors.loggedInIndicator).first();
+    const loginPage = this.page.locator(this.selectors.loginPage);
+
+    const result = await Promise.race([
+      loggedIn.waitFor({ timeout: 15_000 }).then(() => 'logged-in'),
+      loginPage.waitFor({ timeout: 15_000 }).then(() => 'login-page'),
+    ]).catch(() => 'timeout');
+
+    if (result !== 'logged-in') {
+      throw new Error(
+        `Not logged into ${this.hostName}. Run \`pnpm test:live\` to open a browser and log in.\n` +
+        'Your session is saved for 24 hours after the first login.'
+      );
+    }
+  }
+
+  /**
+   * Refresh the MCP server connection in host settings.
+   * Subclasses must implement this — each host has different settings UI.
+   *
+   * @param {Object} [options]
+   * @param {string} [options.tunnelUrl] - Tunnel URL for error messages
+   * @param {string} [options.appName] - App name as configured in the host
+   */
+  async refreshMcpServer(_options) {
+    throw new Error(`${this.hostName} refreshMcpServer not implemented`);
+  }
+
+  /**
+   * Start a new chat conversation.
+   */
+  async startNewChat() {
+    const newChatLink = this.page.locator(this.selectors.newChatLink).first();
+    const isVisible = await newChatLink.isVisible().catch(() => false);
+    if (isVisible) {
+      await newChatLink.click();
+    } else {
+      await this.page.goto(this.urls.base, { waitUntil: 'domcontentloaded' });
+    }
+
+    await this.page.locator(this.selectors.chatInput).waitFor({ timeout: 10_000 });
+  }
+
+  /**
+   * Send a message in the current chat.
+   * @param {string} text - The message to send
+   */
+  async sendMessage(text) {
+    const input = this.page.locator(this.selectors.chatInput);
+    await input.waitFor({ timeout: 10_000 });
+    await input.click();
+
+    // Use keyboard typing — host React textareas often don't respond to fill()
+    await input.pressSequentially(text, { delay: 10 });
+
+    const sendBtn = this.page.locator(this.selectors.sendButton);
+    await sendBtn.waitFor({ state: 'visible', timeout: 10_000 });
+    await sendBtn.click();
+  }
+
+  /**
+   * Wait for a MCP app iframe to appear in the conversation.
+   * Subclasses must implement this — each host renders iframes differently.
+   *
+   * @param {Object} [options]
+   * @param {number} [options.timeout=90000] - Max time to wait (ms)
+   * @returns {Promise<import('playwright').FrameLocator>}
+   */
+  async waitForAppIframe(_options) {
+    throw new Error(`${this.hostName} waitForAppIframe not implemented`);
+  }
+
+  /**
+   * Get the app iframe FrameLocator.
+   * @returns {import('playwright').FrameLocator}
+   */
+  getAppIframe() {
+    throw new Error(`${this.hostName} getAppIframe not implemented`);
+  }
+
+  /**
+   * Capture a debug screenshot and throw with helpful message.
+   * @param {string} context - Context label for the screenshot filename
+   * @param {string} [tunnelUrl] - Tunnel URL for the error message
+   * @protected
+   */
+  async _screenshotAndThrow(context, tunnelUrl) {
+    const screenshotPath = `/tmp/sunpeak-live-debug-${this.hostId}-${context}.png`;
+    try {
+      await this.page.screenshot({ path: screenshotPath, fullPage: true });
+      console.error(`\nDebug screenshot saved to: ${screenshotPath}`);
+    } catch {
+      // Screenshot failed — continue with the error
+    }
+
+    try {
+      const buttons = await this.page.locator('button').allTextContents();
+      console.error('Visible buttons on page:', buttons.filter(t => t.trim()).join(', '));
+    } catch {
+      // Best effort
+    }
+
+    throw new Error(
+      `Could not find Refresh/Reconnect button in ${this.hostName} settings.\n` +
+      `Make sure your MCP server is added in ${this.hostName} settings` +
+      (tunnelUrl ? ` with URL: ${tunnelUrl}/mcp` : '') +
+      `\n\nDebug screenshot: ${screenshotPath}`
+    );
+  }
+
+  /**
+   * Wait for a toast/alert banner and check for errors.
+   * Many hosts show success/error toasts after settings actions.
+   * @param {Object} [options]
+   * @param {string} [options.alertSelector='[role="alert"]'] - Selector for toast elements
+   * @param {number} [options.timeout=30000] - Max time to wait
+   * @param {number} [options.minTextLength=5] - Minimum text length to consider as a real toast
+   * @protected
+   */
+  async _waitForToast({ alertSelector = '[role="alert"]', timeout = 30_000, minTextLength = 5 } = {}) {
+    try {
+      await this.page.waitForFunction(
+        ({ selector, minLen }) => {
+          const alerts = document.querySelectorAll(selector);
+          for (const alert of alerts) {
+            const text = alert.textContent?.trim();
+            if (text && text.length > minLen) return true;
+          }
+          return false;
+        },
+        { selector: alertSelector, minLen: minTextLength },
+        { timeout },
+      );
+    } catch {
+      console.warn('No toast detected — assuming success.');
+      return { texts: [], hasError: false };
+    }
+
+    const texts = await this.page.locator(alertSelector).allTextContents();
+    const errorText = texts.find((t) => /error/i.test(t));
+    return { texts, hasError: !!errorText, errorText };
+  }
+}

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

@@ -0,0 +1,38 @@
+import type { PlaywrightTestConfig } from '@playwright/test';
+
+export interface LiveConfigOptions {
+  /** Test directory relative to playwright.config.ts. Default: '.' */
+  testDir?: string;
+  /** Directory for auth state. Default: '{testDir}/.auth' */
+  authDir?: string;
+  /** Port for the Vite dev server. MCP server always uses 8000. Default: 3456 */
+  vitePort?: number;
+
+  // --- Browser environment ---
+
+  /** Emulate light or dark mode (sets prefers-color-scheme). The host follows this for theming. */
+  colorScheme?: 'light' | 'dark';
+  /** Browser viewport size. Default: Playwright's default (1280x720). */
+  viewport?: { width: number; height: number };
+  /** Browser locale (e.g., 'en-US', 'fr-FR'). */
+  locale?: string;
+  /** IANA timezone ID (e.g., 'America/New_York', 'Europe/London'). */
+  timezoneId?: string;
+  /** Emulate geolocation coordinates. */
+  geolocation?: { latitude: number; longitude: number };
+  /** Browser permissions to grant (e.g., ['geolocation']). */
+  permissions?: string[];
+
+  /** Additional Playwright `use` options, merged with defaults. */
+  use?: Record<string, unknown>;
+}
+
+export interface HostConfigOptions {
+  hostId: string;
+  authFileName?: string;
+}
+
+export declare function createLiveConfig(
+  hostOptions: HostConfigOptions,
+  options?: LiveConfigOptions,
+): PlaywrightTestConfig;

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

@@ -0,0 +1,98 @@
+/**
+ * Shared Playwright config factory for live tests across all hosts.
+ *
+ * Each host (ChatGPT, Claude) calls createLiveConfig() with its host-specific
+ * settings (project name, auth file name). Browser environment options
+ * (colorScheme, viewport, locale, etc.) are shared across all hosts.
+ *
+ * Host-specific configs re-export as defineLiveConfig() for user convenience.
+ */
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { ANTI_BOT_ARGS, CHROME_USER_AGENT } from './utils.mjs';
+import { getPortSync } from '../get-port.mjs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const GLOBAL_SETUP_PATH = join(__dirname, 'global-setup.mjs');
+
+/**
+ * Create a Playwright config for live testing against a specific host.
+ *
+ * @param {Object} hostOptions - Host-specific settings
+ * @param {string} hostOptions.hostId - Host identifier (e.g., 'chatgpt', 'claude')
+ * @param {string} [hostOptions.authFileName] - Auth state filename (default: '{hostId}.json')
+ *
+ * @param {Object} [options] - User-facing options
+ * @param {string} [options.testDir='.'] - Test directory (relative to playwright.config.ts)
+ * @param {string} [options.authDir] - Directory for auth state (defaults to {testDir}/.auth)
+ * @param {number} [options.vitePort] - Port for the Vite dev server (defaults to a free port near 3456)
+ * @param {'light'|'dark'} [options.colorScheme] - Emulate light or dark mode (prefers-color-scheme)
+ * @param {{ width: number, height: number }} [options.viewport] - Browser viewport size
+ * @param {string} [options.locale] - Browser locale (e.g., 'en-US', 'fr-FR')
+ * @param {string} [options.timezoneId] - Timezone (e.g., 'America/New_York')
+ * @param {{ latitude: number, longitude: number }} [options.geolocation] - Geolocation coordinates
+ * @param {string[]} [options.permissions] - Browser permissions to grant (e.g., ['geolocation'])
+ * @param {Object} [options.use] - Additional Playwright `use` options (merged with defaults)
+ */
+export function createLiveConfig(hostOptions, options = {}) {
+  const { hostId, authFileName } = hostOptions;
+  const {
+    testDir = '.',
+    authDir,
+    vitePort = getPortSync(3456),
+    colorScheme,
+    viewport,
+    locale,
+    timezoneId,
+    geolocation,
+    permissions,
+    use: userUse,
+  } = options;
+
+  const resolvedAuthDir = authDir || join(testDir, '.auth');
+  const authFile = join(process.cwd(), resolvedAuthDir, authFileName || `${hostId}.json`);
+
+  // Pass auth file path to global setup via env var (Playwright runs globalSetup
+  // in a separate worker, so we can't pass it as a function argument).
+  process.env.SUNPEAK_AUTH_FILE = authFile;
+
+  // Only include browser env keys that were actually passed so Playwright uses its defaults.
+  const browserEnv = {
+    ...(colorScheme && { colorScheme }),
+    ...(viewport && { viewport }),
+    ...(locale && { locale }),
+    ...(timezoneId && { timezoneId }),
+    ...(geolocation && { geolocation }),
+    ...(permissions && { permissions }),
+  };
+
+  return {
+    testDir,
+    globalSetup: GLOBAL_SETUP_PATH,
+    timeout: 120_000, // 2 minutes per test — LLM responses can be slow
+    retries: 1, // One retry for LLM non-determinism
+    fullyParallel: true, // Each test gets its own chat — safe to parallelize
+    reporter: 'list',
+    use: {
+      headless: false,
+      storageState: process.env.SUNPEAK_STORAGE_STATE || authFile,
+      userAgent: CHROME_USER_AGENT,
+      launchOptions: {
+        args: ANTI_BOT_ARGS,
+      },
+      ...browserEnv,
+      ...userUse,
+    },
+    projects: [
+      {
+        name: hostId,
+      },
+    ],
+    webServer: {
+      command: `SUNPEAK_LIVE_TEST=1 pnpm dev -- --prod-resources --port ${vitePort}`,
+      url: `http://localhost:${vitePort}/health`,
+      reuseExistingServer: !process.env.CI,
+      timeout: 60_000,
+    },
+  };
+}

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

@@ -0,0 +1,11 @@
+import type { LiveFixture } from './types.d.mts';
+
+export type { LiveFixture } from './types.d.mts';
+
+export declare const test: {
+  (title: string, fn: (args: { live: LiveFixture } & Record<string, any>) => Promise<void>): void;
+  describe: (title: string, fn: () => void) => void;
+  skip: (title: string, fn: (args: { live: LiveFixture } & Record<string, any>) => Promise<void>) => void;
+};
+
+export declare const expect: (...args: any[]) => any;