sunpeak 0.19.12 → 0.20.1

package/bin/commands/test.mjs

@@ -70,6 +70,9 @@ export async function runTest(args) {
         'playwright.config.js',
         'sunpeak.config.ts',
         'sunpeak.config.js',
+        // Fallback for non-JS projects: tests/sunpeak/ self-contained directory
+        'tests/sunpeak/playwright.config.ts',
+        'tests/sunpeak/playwright.config.js',
       ],
       visual: isVisual,
       updateSnapshots: isVisual && isUpdate,
@@ -82,6 +85,9 @@ export async function runTest(args) {
       configCandidates: [
         'tests/live/playwright.config.ts',
         'tests/live/playwright.config.js',
+        // Fallback for non-JS projects: tests/sunpeak/ self-contained directory
+        'tests/sunpeak/live/playwright.config.ts',
+        'tests/sunpeak/live/playwright.config.js',
       ],
       configRequired: true,
       configErrorMessage: 'No live test config found at tests/live/playwright.config.ts',

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

@@ -15,6 +15,7 @@
  * and external servers.
  */
 import { createBaseConfig, resolvePorts } from '../test/base-config.mjs';
+import { resolveSunpeakBin } from '../resolve-bin.mjs';
 
 /**
  * Create a complete Playwright config for testing an external MCP server.
@@ -26,6 +27,9 @@ import { createBaseConfig, resolvePorts } from '../test/base-config.mjs';
  * @param {string[]} [options.hosts=['chatgpt', 'claude']] - Host shells to test
  * @param {string} [options.name] - App name in inspector chrome
  * @param {Object} [options.use] - Additional Playwright `use` options
+ * @param {number} [options.timeout] - Server startup timeout in ms (default: 60000)
+ * @param {Record<string, string>} [options.env] - Environment variables for stdio servers
+ * @param {string} [options.cwd] - Working directory for stdio servers
  * @returns {import('@playwright/test').PlaywrightTestConfig}
  */
 export function defineInspectConfig(options) {
@@ -37,6 +41,9 @@ export function defineInspectConfig(options) {
     name,
     use: userUse,
     visual,
+    timeout,
+    env,
+    cwd,
   } = options;
 
   if (!server) {
@@ -49,8 +56,15 @@ export function defineInspectConfig(options) {
   const serverArg = server.includes(' ') ? `"${server}"` : server;
   const command = [
     `SUNPEAK_SANDBOX_PORT=${sandboxPort}`,
-    'sunpeak inspect',
+    `${resolveSunpeakBin()} inspect`,
     `--server ${serverArg}`,
+    ...(env
+      ? Object.entries(env).map(([k, v]) => {
+          const pair = `${k}=${v}`;
+          return pair.includes(' ') ? `--env "${pair}"` : `--env ${pair}`;
+        })
+      : []),
+    ...(cwd ? [cwd.includes(' ') ? `--cwd "${cwd}"` : `--cwd ${cwd}`] : []),
     ...(simulationsDir ? [`--simulations ${simulationsDir}`] : []),
     `--port ${port}`,
     ...(name ? [`--name "${name}"`] : []),
@@ -62,6 +76,7 @@ export function defineInspectConfig(options) {
     port,
     use: userUse,
     visual,
+    timeout,
     webServer: {
       command,
       healthUrl: `http://localhost:${port}/health`,

package/bin/lib/inspect/inspect-server.d.mts

@@ -0,0 +1,32 @@
+/**
+ * Start the sunpeak inspector server programmatically.
+ *
+ * Connects to the provided MCP server, discovers tools and resources,
+ * and serves the inspector UI on the specified port.
+ */
+export function inspectServer(opts: {
+  /** MCP server URL or stdio command. */
+  server: string;
+  /** Path to simulation fixtures directory. */
+  simulationsDir?: string | null;
+  /** Dev server port (default: 3000). */
+  port?: number;
+  /** App name in inspector chrome. */
+  name?: string;
+  /** Existing sandbox server URL (skips creating one). */
+  sandboxUrl?: string;
+  /** If true, show framework-only controls (Prod Resources). */
+  frameworkMode?: boolean;
+  /** Initial prod resources state. */
+  defaultProdResources?: boolean;
+  /** Project directory for serving /dist/ files (prod resources). */
+  projectRoot?: string | null;
+  /** Whether to open browser (default: !CI). */
+  open?: boolean;
+  /** Additional cleanup callback on exit. */
+  onCleanup?: () => Promise<void>;
+  /** Extra environment variables for stdio server processes. */
+  env?: Record<string, string>;
+  /** Working directory for stdio server processes. */
+  cwd?: string;
+}): Promise<void>;

package/bin/lib/inspect/inspect-server.mjs

@@ -0,0 +1,11 @@
+/**
+ * Programmatic entry point for the sunpeak inspector server.
+ *
+ * Allows frameworks to start the inspector from their own CLI without
+ * shelling out to the `sunpeak inspect` command.
+ *
+ * Usage:
+ *   import { inspectServer } from 'sunpeak/inspect';
+ *   await inspectServer({ server: 'http://localhost:8000/mcp', port: 3000 });
+ */
+export { inspectServer } from '../../commands/inspect.mjs';

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 ?? {};
 
@@ -52,7 +53,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,6 +73,7 @@ export function defineConfig(options = {}) {
     use: userUse,
     globalSetup,
     visual,
+    timeout,
     webServer: {
       command,
       healthUrl: `http://localhost:${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;
 }>;