sunpeak 0.19.12 → 0.20.2

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

@@ -11,6 +11,7 @@ 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';
+import { resolveSunpeakBin } from '../resolve-bin.mjs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const GLOBAL_SETUP_PATH = join(__dirname, 'global-setup.mjs');
@@ -34,6 +35,10 @@ const GLOBAL_SETUP_PATH = join(__dirname, 'global-setup.mjs');
  * @param {string[]} [options.permissions] - Browser permissions to grant (e.g., ['geolocation'])
  * @param {boolean} [options.devOverlay=true] - Show the dev overlay (resource timestamp + tool timing) in resources
  * @param {Object} [options.use] - Additional Playwright `use` options (merged with defaults)
+ * @param {Object} [options.server] - External MCP server config (omit for sunpeak projects)
+ * @param {string} [options.server.url] - Server URL (e.g., 'http://localhost:8000/mcp')
+ * @param {string} [options.server.command] - Server start command
+ * @param {string[]} [options.server.args] - Command arguments
  */
 export function createLiveConfig(hostOptions, options = {}) {
   const { hostId, authFileName } = hostOptions;
@@ -49,6 +54,7 @@ export function createLiveConfig(hostOptions, options = {}) {
     geolocation,
     permissions,
     use: userUse,
+    server,
   } = options;
 
   const resolvedAuthDir = authDir || join(testDir, '.auth');
@@ -91,10 +97,36 @@ export function createLiveConfig(hostOptions, options = {}) {
       },
     ],
     webServer: {
-      command: `SUNPEAK_LIVE_TEST=1 SUNPEAK_SANDBOX_PORT=${getPortSync(24680)}${devOverlay ? '' : ' SUNPEAK_DEV_OVERLAY=false'} pnpm dev -- --prod-resources --port ${vitePort}`,
-      url: `http://localhost:${vitePort}/health`,
+      command: buildLiveWebServerCommand({ server, vitePort, devOverlay }),
+      url: `http://127.0.0.1:${vitePort}/health`,
       reuseExistingServer: !process.env.CI,
       timeout: 60_000,
     },
   };
 }
+
+/**
+ * Build the webServer command for live tests.
+ * Uses `sunpeak inspect` for external servers, `pnpm dev` for sunpeak projects.
+ */
+function buildLiveWebServerCommand({ server, vitePort, devOverlay }) {
+  const sandboxPort = getPortSync(24680);
+  const envPrefix = `SUNPEAK_LIVE_TEST=1 SUNPEAK_SANDBOX_PORT=${sandboxPort}${devOverlay ? '' : ' SUNPEAK_DEV_OVERLAY=false'}`;
+
+  if (server) {
+    // External MCP server — launch sunpeak inspect
+    const bin = resolveSunpeakBin();
+    if (server.url) {
+      return `${envPrefix} ${bin} inspect --server ${server.url} --port ${vitePort}`;
+    }
+    if (server.command) {
+      const cmd = server.args
+        ? `${server.command} ${server.args.join(' ')}`
+        : server.command;
+      return `${envPrefix} ${bin} inspect --server "${cmd}" --port ${vitePort}`;
+    }
+  }
+
+  // sunpeak framework project — use pnpm dev
+  return `${envPrefix} pnpm dev -- --prod-resources --port ${vitePort}`;
+}

package/bin/lib/resolve-bin.mjs

@@ -0,0 +1,39 @@
+/**
+ * Resolve the sunpeak CLI binary path.
+ *
+ * When sunpeak is installed as a local dependency (e.g., in tests/sunpeak/
+ * for non-JS projects), the bare `sunpeak` command won't be on PATH.
+ * This utility checks for the local .bin entry first, then falls back
+ * to the bare command name for global installs.
+ */
+import { existsSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+/**
+ * Find the sunpeak binary, preferring the local node_modules/.bin entry.
+ *
+ * Checks in order:
+ * 1. process.cwd() (works when running from the test directory directly)
+ * 2. The directory containing this file's package (works when the config is
+ *    loaded from a parent directory, e.g., `sunpeak test` run from project root
+ *    with config at tests/sunpeak/playwright.config.ts)
+ *
+ * @returns {string} Path to the sunpeak binary, or bare 'sunpeak' as fallback
+ */
+export function resolveSunpeakBin() {
+  // Check cwd first (covers `cd tests/sunpeak && sunpeak test`)
+  const cwdBin = join(process.cwd(), 'node_modules', '.bin', 'sunpeak');
+  if (existsSync(cwdBin)) return cwdBin;
+
+  // Check the directory containing this module's package, which is the
+  // sunpeak package root. Walk up from bin/lib/ to find node_modules/.bin/.
+  // This covers running from a parent dir (e.g., project root) where sunpeak
+  // is installed in a subdirectory (tests/sunpeak/node_modules/sunpeak/).
+  const __dirname = dirname(fileURLToPath(import.meta.url));
+  const pkgRoot = join(__dirname, '..', '..');
+  const pkgBin = join(pkgRoot, '..', '.bin', 'sunpeak');
+  if (existsSync(pkgBin)) return pkgBin;
+
+  return 'sunpeak';
+}

package/bin/lib/test/base-config.mjs

@@ -15,9 +15,10 @@ import { getPortSync } from '../get-port.mjs';
  * @param {number} options.port - Inspector port
  * @param {Object} [options.use] - Additional Playwright `use` options
  * @param {string} [options.globalSetup] - Global setup file path
+ * @param {number} [options.timeout] - WebServer startup timeout in ms (default: 60000)
  * @returns {import('@playwright/test').PlaywrightTestConfig}
  */
-export function createBaseConfig({ hosts, testDir, webServer, port, use, globalSetup, visual }) {
+export function createBaseConfig({ hosts, testDir, webServer, port, use, globalSetup, visual, timeout }) {
   // Separate snapshot path from other visual options passed to expect.toHaveScreenshot
   const { snapshotPathTemplate, ...toHaveScreenshotDefaults } = visual ?? {};
 
@@ -43,7 +44,9 @@ export function createBaseConfig({ hosts, testDir, webServer, port, use, globalS
       ? { expect: { toHaveScreenshot: toHaveScreenshotDefaults } }
       : {}),
     use: {
-      baseURL: `http://localhost:${port}`,
+      // Use 127.0.0.1 instead of localhost to avoid IPv4/IPv6 resolution
+      // ambiguity that causes ECONNREFUSED flakes on macOS.
+      baseURL: `http://127.0.0.1:${port}`,
       trace: 'on-first-retry',
       ...use,
     },
@@ -52,7 +55,7 @@ export function createBaseConfig({ hosts, testDir, webServer, port, use, globalS
       command: webServer.command,
       url: webServer.healthUrl,
       reuseExistingServer: !process.env.CI,
-      timeout: 60_000,
+      timeout: timeout ?? 60_000,
     },
   };
 }

package/bin/lib/test/matchers.mjs

@@ -1,8 +1,8 @@
 /**
  * MCP-native custom matchers for Playwright's expect.
  *
- * These matchers operate on ToolResult objects returned by mcp.callTool()
- * and provide MCP-concept-native assertions.
+ * These matchers operate on tool results from mcp.callTool() or
+ * InspectorResult from inspector.renderTool().
  */
 
 /**

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

@@ -18,6 +18,7 @@
 import { existsSync, readFileSync } from 'fs';
 import { join } from 'path';
 import { createBaseConfig, resolvePorts } from './base-config.mjs';
+import { resolveSunpeakBin } from '../resolve-bin.mjs';
 
 /**
  * @param {Object} [options]
@@ -26,11 +27,13 @@ import { createBaseConfig, resolvePorts } from './base-config.mjs';
  * @param {string[]} [options.server.args] - Command arguments
  * @param {string} [options.server.url] - HTTP server URL (alternative to command)
  * @param {Record<string, string>} [options.server.env] - Environment variables
+ * @param {string} [options.server.cwd] - Working directory for the server process
  * @param {string[]} [options.hosts] - Host shells to test (default: ['chatgpt', 'claude'])
  * @param {string} [options.testDir] - Test directory
  * @param {string} [options.simulationsDir] - Simulations directory for mock data
  * @param {string} [options.globalSetup] - Global setup file path
  * @param {Object} [options.use] - Additional Playwright `use` options
+ * @param {number} [options.timeout] - Server startup timeout in ms (default: 60000)
  * @returns {import('@playwright/test').PlaywrightTestConfig}
  */
 export function defineConfig(options = {}) {
@@ -42,6 +45,7 @@ export function defineConfig(options = {}) {
     globalSetup,
     use: userUse,
     visual,
+    timeout,
   } = options;
 
   const { port, sandboxPort } = resolvePorts();
@@ -69,9 +73,10 @@ export function defineConfig(options = {}) {
     use: userUse,
     globalSetup,
     visual,
+    timeout,
     webServer: {
       command,
-      healthUrl: `http://localhost:${port}/health`,
+      healthUrl: `http://127.0.0.1:${port}/health`,
     },
   });
 }
@@ -97,13 +102,7 @@ function detectSunpeakProject() {
 function buildInspectCommand({ server, port, sandboxPort, simulationsDir }) {
   const parts = [`SUNPEAK_SANDBOX_PORT=${sandboxPort}`];
 
-  if (server.env) {
-    for (const [key, value] of Object.entries(server.env)) {
-      parts.push(`${key}=${value}`);
-    }
-  }
-
-  parts.push('sunpeak inspect');
+  parts.push(`${resolveSunpeakBin()} inspect`);
 
   if (server.url) {
     parts.push(`--server ${server.url}`);
@@ -115,6 +114,18 @@ function buildInspectCommand({ server, port, sandboxPort, simulationsDir }) {
     parts.push(`--server "${cmd}"`);
   }
 
+  // Pass environment variables as --env KEY=VALUE flags (stdio servers only).
+  if (server.env) {
+    for (const [key, value] of Object.entries(server.env)) {
+      const pair = `${key}=${value}`;
+      parts.push(pair.includes(' ') ? `--env "${pair}"` : `--env ${pair}`);
+    }
+  }
+
+  if (server.cwd) {
+    parts.push(server.cwd.includes(' ') ? `--cwd "${server.cwd}"` : `--cwd ${server.cwd}`);
+  }
+
   if (simulationsDir) {
     parts.push(`--simulations ${simulationsDir}`);
   }

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

@@ -7,46 +7,40 @@ import type {
   PageAssertionsToHaveScreenshotOptions,
 } from '@playwright/test';
 
-/**
- * Result from calling an MCP tool via the inspector.
- */
-export interface ToolResult {
-  /** Raw MCP content items from the tool response. */
-  content: Array<{ type: string; text?: string; [key: string]: unknown }>;
-  /** Structured content from the tool response. */
+// ── MCP Protocol Types ──
+
+export interface Tool {
+  name: string;
+  description?: string;
+  inputSchema: Record<string, unknown>;
+  title?: string;
+  annotations?: Record<string, unknown>;
+  _meta?: Record<string, unknown>;
+}
+
+export interface Resource {
+  uri: string;
+  name: string;
+  mimeType?: string;
+  description?: string;
+  _meta?: Record<string, unknown>;
+}
+
+export interface CallToolResult {
+  content?: Array<{ type: string; text?: string; [key: string]: unknown }>;
   structuredContent?: unknown;
-  /** Whether the tool returned an error. */
-  isError: boolean;
-  /**
-   * Get a FrameLocator for the rendered resource UI.
-   * Handles the double-iframe traversal automatically.
-   */
-  app(): FrameLocator;
+  isError?: boolean;
 }
 
-/**
- * Options for callTool().
- */
-export interface CallToolOptions {
-  /** Color theme for the inspector. */
+// ── sunpeak Inspector Types ──
+
+export interface RenderToolOptions {
   theme?: 'light' | 'dark';
-  /** Display mode for the resource. */
   displayMode?: 'inline' | 'pip' | 'fullscreen';
-  /** Use production resource builds instead of HMR. */
-  prodResources?: boolean;
-  /** Additional inspector URL parameters. */
+  timeout?: number;
   [key: string]: unknown;
 }
 
-/**
- * Options for screenshot().
- *
- * Extends Playwright's toHaveScreenshot() options with sunpeak-specific
- * `target` and `element` fields. All standard Playwright options (threshold,
- * maxDiffPixelRatio, maxDiffPixels, mask, maskColor, animations, caret,
- * fullPage, clip, scale, stylePath, omitBackground, timeout, etc.)
- * are passed through directly.
- */
 export interface ScreenshotOptions extends PageAssertionsToHaveScreenshotOptions {
   /** What to screenshot: 'app' (inner iframe content) or 'page' (full inspector). Default: 'app'. */
   target?: 'app' | 'page';
@@ -54,76 +48,42 @@ export interface ScreenshotOptions extends PageAssertionsToHaveScreenshotOptions
   element?: Locator;
 }
 
-/**
- * MCP test fixture for testing MCP servers via the inspector.
- */
+export interface InspectorResult {
+  content: Array<{ type: string; text?: string; [key: string]: unknown }>;
+  structuredContent?: unknown;
+  isError: boolean;
+  source: 'fixture' | 'server';
+  app(): FrameLocator;
+  screenshot(options?: ScreenshotOptions): Promise<void>;
+  screenshot(name?: string, options?: ScreenshotOptions): Promise<void>;
+}
+
+// ── Fixtures ──
+
+/** MCP protocol fixture. Maps 1:1 to MCP protocol operations. */
 export interface McpFixture {
-  /** The underlying Playwright Page. */
-  page: Page;
-  /** Current host ID (from Playwright project name). */
-  host: string;
+  listTools(): Promise<Tool[]>;
+  callTool(name: string, input?: Record<string, unknown>): Promise<CallToolResult>;
+  listResources(): Promise<Resource[]>;
+  readResource(uri: string): Promise<string>;
+}
 
-  /**
-   * Call a tool and get the rendered result.
-   * Navigates the inspector, waits for the resource to render,
-   * and returns a ToolResult for assertions.
-   */
-  callTool(
+/** sunpeak inspector fixture. Renders tools in simulated host environments. */
+export interface InspectorFixture {
+  host: string;
+  page: Page;
+  renderTool(
     name: string,
     input?: Record<string, unknown>,
-    options?: CallToolOptions
-  ): Promise<ToolResult>;
-
-  /**
-   * Navigate to a tool with no mock data ("Press Run" state).
-   */
-  openTool(name: string, options?: { theme?: 'light' | 'dark' }): Promise<void>;
-
-  /**
-   * Click the Run button and return the rendered result.
-   */
-  runTool(): Promise<ToolResult>;
-
-  /** Change the theme via the sidebar toggle. */
-  setTheme(theme: 'light' | 'dark'): Promise<void>;
-
-  /** Change the display mode via the sidebar buttons. */
-  setDisplayMode(mode: 'inline' | 'pip' | 'fullscreen'): Promise<void>;
-
-  /**
-   * Take a screenshot and compare against a baseline.
-   * Only performs the comparison when visual testing is enabled
-   * (`sunpeak test --visual`). Silently skips otherwise.
-   *
-   * @param name - Snapshot name (auto-generated from test title if omitted)
-   * @param options - Screenshot and comparison options
-   */
-  screenshot(name?: string, options?: ScreenshotOptions): Promise<void>;
+    options?: RenderToolOptions
+  ): Promise<InspectorResult>;
 }
 
-/**
- * Extended Playwright test with `mcp` fixture.
- */
-export declare const test: TestType<{ mcp: McpFixture }, {}>;
+export declare const test: TestType<{ mcp: McpFixture; inspector: InspectorFixture }, {}>;
 
-/**
- * Extended Playwright expect with MCP-native matchers.
- */
 export declare const expect: Expect<{
-  /**
-   * Assert that a tool result is an error.
-   */
   toBeError(): void;
-  /**
-   * Assert that any content item's text contains the given string.
-   */
   toHaveTextContent(text: string): void;
-  /**
-   * Assert that structuredContent matches the expected shape.
-   */
   toHaveStructuredContent(shape: unknown): void;
-  /**
-   * Assert that content array contains an item of the given type.
-   */
   toHaveContentType(type: string): void;
 }>;