sunpeak 0.19.12 → 0.20.2

package/bin/commands/test-init.mjs

@@ -1,10 +1,23 @@
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
 import { execSync } from 'child_process';
 import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
 import * as p from '@clack/prompts';
 import { EVAL_PROVIDERS, generateModelLines } from '../lib/eval/eval-providers.mjs';
 import { detectPackageManager } from '../utils.mjs';
 
+/** Read the current sunpeak package version for pinning in scaffolded configs. */
+function getSunpeakVersion() {
+  try {
+    const __dirname = dirname(fileURLToPath(import.meta.url));
+    const pkgPath = join(__dirname, '..', '..', 'package.json');
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+    return pkg.version ? `^${pkg.version}` : 'latest';
+  } catch {
+    return 'latest';
+  }
+}
+
 /**
  * Default dependencies (real implementations).
  * Override in tests via the `deps` parameter.
@@ -27,6 +40,7 @@ export const defaultDeps = {
   mkdirSync,
   execSync,
   cwd: () => process.cwd(),
+  isTTY: () => !!process.stdin.isTTY,
   intro: p.intro,
   outro: p.outro,
   confirm: p.confirm,
@@ -49,7 +63,7 @@ export const defaultDeps = {
  *
  * Scaffolds all 5 test types:
  * 1. E2E tests — Playwright-based inspector tests (mcp fixture)
- * 2. Visual regression — Screenshot comparison via mcp.screenshot()
+ * 2. Visual regression — Screenshot comparison via result.screenshot()
  * 3. Live tests — Test against real ChatGPT/Claude hosts
  * 4. Evals — Multi-model tool calling reliability tests
  * 5. Unit tests — Direct tool handler tests (JS/TS projects only)
@@ -67,6 +81,7 @@ export async function testInit(args = [], deps = defaultDeps) {
       : undefined;
 
   const projectType = detectProjectType(d);
+  const interactive = d.isTTY();
 
   if (projectType === 'sunpeak') {
     await initSunpeakProject(d);
@@ -76,74 +91,76 @@ export async function testInit(args = [], deps = defaultDeps) {
     await initExternalProject(cliServer, d);
   }
 
-  // Offer to configure eval providers
-  const providers = await d.selectProviders();
-  if (!d.isCancel(providers) && providers.length > 0) {
-    const pm = d.detectPackageManager();
-    const pkgsToInstall = ['ai', ...providers.map((p) => p.pkg)];
-    const installCmd = `${pm} add -D ${pkgsToInstall.join(' ')}`;
-    try {
-      d.execSync(installCmd, { cwd: d.cwd(), stdio: 'inherit' });
-    } catch {
-      d.log.info(`Provider install failed. Install manually: ${installCmd}`);
-    }
+  // Offer to configure eval providers (skip without a TTY — prompts can't work)
+  if (interactive) {
+    const providers = await d.selectProviders();
+    if (!d.isCancel(providers) && providers.length > 0) {
+      const pm = d.detectPackageManager();
+      const pkgsToInstall = ['ai', ...providers.map((p) => p.pkg)];
+      const installCmd = `${pm} add -D ${pkgsToInstall.join(' ')}`;
+      try {
+        d.execSync(installCmd, { cwd: d.cwd(), stdio: 'inherit' });
+      } catch {
+        d.log.info(`Provider install failed. Install manually: ${installCmd}`);
+      }
 
-    // Uncomment selected models in eval.config.ts
-    const evalDir = d.existsSync(join(d.cwd(), 'tests', 'evals'))
-      ? join(d.cwd(), 'tests', 'evals')
-      : d.existsSync(join(d.cwd(), 'tests', 'sunpeak', 'evals'))
-        ? join(d.cwd(), 'tests', 'sunpeak', 'evals')
-        : null;
-    if (evalDir) {
-      const configPath = join(evalDir, 'eval.config.ts');
-      if (d.existsSync(configPath)) {
-        let config = d.readFileSync(configPath, 'utf-8');
-        for (const prov of providers) {
-          for (const model of prov.models) {
-            config = config.replace(
-              new RegExp(`^(\\s*)// ('${model.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}',?.*)$`, 'm'),
-              '$1$2'
-            );
+      // Uncomment selected models in eval.config.ts
+      const evalDir = d.existsSync(join(d.cwd(), 'tests', 'evals'))
+        ? join(d.cwd(), 'tests', 'evals')
+        : d.existsSync(join(d.cwd(), 'tests', 'sunpeak', 'evals'))
+          ? join(d.cwd(), 'tests', 'sunpeak', 'evals')
+          : null;
+      if (evalDir) {
+        const configPath = join(evalDir, 'eval.config.ts');
+        if (d.existsSync(configPath)) {
+          let config = d.readFileSync(configPath, 'utf-8');
+          for (const prov of providers) {
+            for (const model of prov.models) {
+              config = config.replace(
+                new RegExp(`^(\\s*)// ('${model.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}',?.*)$`, 'm'),
+                '$1$2'
+              );
+            }
           }
+          d.writeFileSync(configPath, config);
         }
-        d.writeFileSync(configPath, config);
-      }
 
-      // Prompt for API keys and write .env
-      const envLines = [];
-      const seen = new Set();
-      for (const prov of providers) {
-        if (seen.has(prov.envVar)) continue;
-        seen.add(prov.envVar);
-        const key = await d.password({
-          message: `${prov.envVar} (enter to skip)`,
-          mask: '*',
-        });
-        if (!d.isCancel(key) && key) {
-          envLines.push(`${prov.envVar}=${key}`);
+        // Prompt for API keys and write .env
+        const envLines = [];
+        const seen = new Set();
+        for (const prov of providers) {
+          if (seen.has(prov.envVar)) continue;
+          seen.add(prov.envVar);
+          const key = await d.password({
+            message: `${prov.envVar} (enter to skip)`,
+            mask: '*',
+          });
+          if (!d.isCancel(key) && key) {
+            envLines.push(`${prov.envVar}=${key}`);
+          }
+        }
+        if (envLines.length > 0 && evalDir) {
+          const relEnvPath = evalDir.startsWith(d.cwd()) ? evalDir.slice(d.cwd().length + 1) : evalDir;
+          d.writeFileSync(join(evalDir, '.env'), envLines.join('\n') + '\n');
+          d.log.info(`API keys saved to ${relEnvPath}/.env (gitignored)`);
         }
-      }
-      if (envLines.length > 0 && evalDir) {
-        const relEnvPath = evalDir.startsWith(d.cwd()) ? evalDir.slice(d.cwd().length + 1) : evalDir;
-        d.writeFileSync(join(evalDir, '.env'), envLines.join('\n') + '\n');
-        d.log.info(`API keys saved to ${relEnvPath}/.env (gitignored)`);
       }
     }
-  }
 
-  // Offer to install the testing skill
-  const installSkill = await d.confirm({
-    message: 'Install the test-mcp-server skill? (helps your coding agent write tests)',
-    initialValue: true,
-  });
-  if (!d.isCancel(installSkill) && installSkill) {
-    try {
-      d.execSync('pnpm 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');
+    // Offer to install the testing skill
+    const installSkill = await d.confirm({
+      message: 'Install the test-mcp-server skill? (helps your coding agent write tests)',
+      initialValue: true,
+    });
+    if (!d.isCancel(installSkill) && installSkill) {
+      try {
+        d.execSync('pnpm 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');
+      }
     }
   }
 
@@ -178,6 +195,11 @@ async function getServerConfig(cliServer, d) {
     return { type: 'command', value: cliServer };
   }
 
+  // Without a TTY, interactive prompts can't work — default to "configure later".
+  if (!d.isTTY()) {
+    return { type: 'later' };
+  }
+
   const serverType = await d.select({
     message: 'How does your MCP server start?',
     options: [
@@ -212,11 +234,32 @@ async function getServerConfig(cliServer, d) {
 
 function generateServerConfigBlock(server, relativeTo = '.') {
   if (server.type === 'later') {
-    return `  // TODO: Configure your MCP server connection
+    return `  // TODO: Configure your MCP server connection before running tests.
+  // Uncomment one of the options below:
+  //
+  // HTTP server (Python FastAPI, Go, etc.):
+  // server: { url: 'http://localhost:8000/mcp' },
+  //
+  // Python (uv):
+  // server: { command: 'uv', args: ['run', 'python', 'server.py'] },
+  //
+  // Python (venv):
+  // server: { command: '.venv/bin/python', args: ['server.py'] },
+  //
+  // Go:
+  // server: { command: 'go', args: ['run', './cmd/server'] },
+  //
+  // Node.js:
+  // server: { command: 'node', args: ['server.js'] },
+  //
+  // Optional server options:
   // server: {
-  //   command: 'python',
-  //   args: ['server.py'],
-  // },`;
+  //   command: 'python', args: ['server.py'],
+  //   env: { API_KEY: 'test-key' },  // Extra environment variables
+  //   cwd: './backend',               // Working directory
+  // },
+  //
+  // timeout: 120_000,  // Server startup timeout in ms (default: 60s)`;
   }
   if (server.type === 'url') {
     return `  server: {
@@ -369,31 +412,31 @@ function scaffoldVisualTest(filePath, d) {
  * Uncomment the tests below and replace 'your-tool' with your tool name.
  */
 
-// test('tool renders correctly in light mode', async ({ mcp }) => {
-//   const result = await mcp.callTool('your-tool', { key: 'value' }, { theme: 'light' });
+// test('tool renders correctly in light mode', async ({ inspector }) => {
+//   const result = await inspector.renderTool('your-tool', { key: 'value' }, { theme: 'light' });
 //   expect(result).not.toBeError();
 //
 //   // Wait for UI to render, then screenshot:
 //   // const app = result.app();
 //   // await expect(app.getByText('Expected text')).toBeVisible();
-//   // await mcp.screenshot('tool-light');
+//   // await result.screenshot('tool-light');
 // });
 
-// test('tool renders correctly in dark mode', async ({ mcp }) => {
-//   const result = await mcp.callTool('your-tool', { key: 'value' }, { theme: 'dark' });
+// test('tool renders correctly in dark mode', async ({ inspector }) => {
+//   const result = await inspector.renderTool('your-tool', { key: 'value' }, { theme: 'dark' });
 //   expect(result).not.toBeError();
 //
 //   // const app = result.app();
 //   // await expect(app.getByText('Expected text')).toBeVisible();
-//   // await mcp.screenshot('tool-dark');
+//   // await result.screenshot('tool-dark');
 // });
 
 // Full-page screenshot (captures the inspector chrome too):
-// test('full page renders correctly', async ({ mcp }) => {
-//   const result = await mcp.callTool('your-tool', {}, { theme: 'light' });
+// test('full page renders correctly', async ({ inspector }) => {
+//   const result = await inspector.renderTool('your-tool', {}, { theme: 'light' });
 //   const app = result.app();
 //   await expect(app.getByText('Expected text')).toBeVisible();
-//   await mcp.screenshot('tool-page', { target: 'page', maxDiffPixelRatio: 0.02 });
+//   await result.screenshot('tool-page', { target: 'page', maxDiffPixelRatio: 0.02 });
 // });
 `
   );
@@ -403,9 +446,9 @@ function scaffoldVisualTest(filePath, d) {
 /**
  * Scaffold live test boilerplate (test against real ChatGPT/Claude).
  * @param {string} liveDir - Directory to create live test files in
- * @param {{ isSunpeak?: boolean, d: object }} options
+ * @param {{ isSunpeak?: boolean, server?: object, d: object }} options
  */
-function scaffoldLiveTests(liveDir, { isSunpeak, d } = {}) {
+function scaffoldLiveTests(liveDir, { isSunpeak, server, d } = {}) {
   if (d.existsSync(join(liveDir, 'playwright.config.ts'))) {
     d.log.info('Live test config already exists. Skipping live test scaffold.');
     return;
@@ -425,9 +468,24 @@ function scaffoldLiveTests(liveDir, { isSunpeak, d } = {}) {
  * 3. Run: 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).`;
+ * The session is saved for subsequent runs (typically lasts a few hours).
+ */`;
+
+  // Build the server option for non-sunpeak projects
+  let serverOption = '';
+  if (!isSunpeak && server?.type === 'url') {
+    serverOption = `\n  server: { url: '${server.value}' },`;
+  } else if (!isSunpeak && server?.type === 'command') {
+    const parts = server.value.split(/\s+/);
+    const cmd = parts[0];
+    const args = parts.slice(1);
+    serverOption = args.length > 0
+      ? `\n  server: { command: '${cmd}', args: [${args.map(a => `'${a}'`).join(', ')}] },`
+      : `\n  server: { command: '${cmd}' },`;
+  }
 
-  const liveConfigExport = `export default defineLiveConfig({
+  const configContent = `${liveConfigPreamble}
+export default defineLiveConfig({${serverOption}
   // hosts: ['chatgpt'],           // Which hosts to test against
   // colorScheme: 'light',         // Default color scheme
   // viewport: { width: 1280, height: 720 },
@@ -435,19 +493,6 @@ function scaffoldLiveTests(liveDir, { isSunpeak, d } = {}) {
 });
 `;
 
-  const configContent = isSunpeak
-    ? `${liveConfigPreamble}
- */
-${liveConfigExport}`
-    : `${liveConfigPreamble}
- *
- * NOTE: defineLiveConfig() starts a local sunpeak dev server as its backend.
- * If your MCP server is not a sunpeak project, you may need to customize the
- * webServer option in the Playwright config below to start your own server,
- * or remove webServer entirely if your server is already running.
- */
-${liveConfigExport}`;
-
   d.writeFileSync(join(liveDir, 'playwright.config.ts'), configContent);
 
   // Live test example
@@ -557,7 +602,7 @@ async function initExternalProject(cliServer, d) {
         type: 'module',
         devDependencies: {
           '@types/node': 'latest',
-          sunpeak: 'latest',
+          sunpeak: getSunpeakVersion(),
           '@playwright/test': 'latest',
         },
         scripts: {
@@ -599,24 +644,28 @@ ${serverBlock}
     ) + '\n'
   );
 
-  // 1. E2E test — smoke test, verifies the server is reachable
+  // 1. E2E test — smoke test, verifies the server exposes tools
   d.writeFileSync(
     join(testDir, 'smoke.test.ts'),
     `import { test, expect } from 'sunpeak/test';
 
-test('server is reachable and inspector loads', async ({ mcp }) => {
-  // Verify the inspector page loads successfully
-  await expect(mcp.page.locator('#root')).not.toBeEmpty();
+test('server exposes tools', async ({ mcp }) => {
+  const tools = await mcp.listTools();
+  expect(tools.length).toBeGreaterThan(0);
 });
 
-// Uncomment and customize for your tools:
-// test('my tool renders correctly', async ({ mcp }) => {
+// Protocol-level test (no UI rendering):
+// test('my tool returns data', async ({ mcp }) => {
 //   const result = await mcp.callTool('your-tool', { key: 'value' });
+//   expect(result.isError).toBeFalsy();
+// });
+
+// UI rendering test:
+// test('my tool renders correctly', async ({ inspector }) => {
+//   const result = await inspector.renderTool('your-tool', { key: 'value' });
 //   expect(result).not.toBeError();
-//
-//   // If your tool has a UI:
-//   // const app = result.app();
-//   // await expect(app.getByText('Hello')).toBeVisible();
+//   const app = result.app();
+//   await expect(app.getByText('Hello')).toBeVisible();
 // });
 `
   );
@@ -625,18 +674,33 @@ test('server is reachable and inspector loads', async ({ mcp }) => {
   scaffoldVisualTest(join(testDir, 'visual.test.ts'), d);
 
   // 3. Live tests
-  scaffoldLiveTests(join(testDir, 'live'), { isSunpeak: false, d });
+  scaffoldLiveTests(join(testDir, 'live'), { isSunpeak: false, server, d });
 
   // 4. Eval boilerplate
   scaffoldEvals(join(testDir, 'evals'), { server, d });
 
   d.log.success('Created tests/sunpeak/ with all test types.');
-  d.log.step('Next steps:');
+  if (server.type === 'later') {
+    d.log.warn('Server not configured. Edit tests/sunpeak/playwright.config.ts before running tests.');
+  }
+
+  // Auto-install dependencies so users can run tests immediately
   const pm = d.detectPackageManager();
-  d.log.message('  cd tests/sunpeak');
-  d.log.message(`  ${pm} install`);
-  d.log.message(`  ${pm} exec playwright install chromium`);
-  d.log.message('');
+  d.log.step('Installing dependencies...');
+  try {
+    d.execSync(`${pm} install`, { cwd: testDir, stdio: 'inherit' });
+  } catch {
+    d.log.warn(`Dependency install failed. Run manually: cd tests/sunpeak && ${pm} install`);
+  }
+
+  d.log.step('Installing Playwright browser...');
+  try {
+    d.execSync(`${pm} exec playwright install chromium`, { cwd: testDir, stdio: 'inherit' });
+  } catch {
+    d.log.warn(`Browser install failed. Run manually: cd tests/sunpeak && ${pm} exec playwright install chromium`);
+  }
+
+  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)');
@@ -677,18 +741,23 @@ ${serverBlock}
       testPath,
       `import { test, expect } from 'sunpeak/test';
 
-test('server is reachable and inspector loads', async ({ mcp }) => {
-  await expect(mcp.page.locator('#root')).not.toBeEmpty();
+test('server exposes tools', async ({ mcp }) => {
+  const tools = await mcp.listTools();
+  expect(tools.length).toBeGreaterThan(0);
 });
 
-// Uncomment and customize for your tools:
-// test('my tool renders correctly', async ({ mcp }) => {
+// Protocol-level test (no UI rendering):
+// test('my tool returns data', async ({ mcp }) => {
 //   const result = await mcp.callTool('your-tool', { key: 'value' });
+//   expect(result.isError).toBeFalsy();
+// });
+
+// UI rendering test:
+// test('my tool renders correctly', async ({ inspector }) => {
+//   const result = await inspector.renderTool('your-tool', { key: 'value' });
 //   expect(result).not.toBeError();
-//
-//   // If your tool has a UI:
-//   // const app = result.app();
-//   // await expect(app.getByText('Hello')).toBeVisible();
+//   const app = result.app();
+//   await expect(app.getByText('Hello')).toBeVisible();
 // });
 `
     );
@@ -699,7 +768,7 @@ test('server is reachable and inspector loads', async ({ mcp }) => {
   scaffoldVisualTest(join(e2eDir, 'visual.test.ts'), d);
 
   // 3. Live tests
-  scaffoldLiveTests(join(cwd, 'tests', 'live'), { isSunpeak: false, d });
+  scaffoldLiveTests(join(cwd, 'tests', 'live'), { isSunpeak: false, server, d });
 
   // 4. Eval boilerplate
   scaffoldEvals(join(cwd, 'tests', 'evals'), { server, d });
@@ -707,6 +776,9 @@ test('server is reachable and inspector loads', async ({ mcp }) => {
   // 5. Unit test
   scaffoldUnitTest(join(cwd, 'tests', 'unit', 'example.test.ts'), d);
 
+  if (server.type === 'later') {
+    d.log.warn('Server not configured. Edit playwright.config.ts before running tests.');
+  }
   const pkgMgr = d.detectPackageManager();
   d.log.step('Next steps:');
   d.log.message(`  ${pkgMgr} add -D sunpeak @playwright/test vitest`);
@@ -772,6 +844,6 @@ export default defineConfig();
   d.log.message('  Replace: import { test, expect } from "@playwright/test"');
   d.log.message('  With:    import { test, expect } from "sunpeak/test"');
   d.log.message('');
-  d.log.message('  Use the `mcp` fixture instead of raw page navigation.');
+  d.log.message('  Use the `mcp` and `inspector` fixtures instead of raw page navigation.');
   d.log.message('  See sunpeak docs for migration examples.');
 }

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,9 +85,15 @@ export async function runTest(args) {
       configCandidates: [
         'tests/live/playwright.config.ts',
         'tests/live/playwright.config.js',
+        // Non-JS projects: tests/sunpeak/ self-contained directory (run from project root)
+        'tests/sunpeak/live/playwright.config.ts',
+        'tests/sunpeak/live/playwright.config.js',
+        // Non-JS projects: run from within tests/sunpeak/ directly
+        'live/playwright.config.ts',
+        'live/playwright.config.js',
       ],
       configRequired: true,
-      configErrorMessage: 'No live test config found at tests/live/playwright.config.ts',
+      configErrorMessage: 'No live test config found. Expected at tests/live/playwright.config.ts or live/playwright.config.ts',
     });
     results.push({ suite: 'live', code });
   }
@@ -531,6 +540,8 @@ function findEvalDir() {
   const candidates = [
     'tests/evals',
     'tests/sunpeak/evals',
+    // When running from within tests/sunpeak/ directly (non-JS projects)
+    'evals',
   ];
 
   for (const candidate of candidates) {

package/bin/lib/eval/eval-runner.mjs

@@ -77,7 +77,13 @@ export async function createMcpConnection(serverArg) {
     const { StreamableHTTPClientTransport } = await import(
       '@modelcontextprotocol/sdk/client/streamableHttp.js'
     );
-    const transport = new StreamableHTTPClientTransport(new URL(serverArg));
+    // Follow redirects (e.g. /mcp → /mcp/) before creating the transport.
+    let finalUrl = serverArg;
+    try {
+      const resp = await fetch(serverArg, { method: 'HEAD', redirect: 'follow' });
+      if (resp.url && resp.url !== serverArg) finalUrl = resp.url;
+    } catch { /* use original URL */ }
+    const transport = new StreamableHTTPClientTransport(new URL(finalUrl));
     await client.connect(transport);
     return { client, transport };
   } else {

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,9 +76,10 @@ export function defineInspectConfig(options) {
     port,
     use: userUse,
     visual,
+    timeout,
     webServer: {
       command,
-      healthUrl: `http://localhost:${port}/health`,
+      healthUrl: `http://127.0.0.1:${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/live/live-config.d.mts

@@ -28,6 +28,16 @@ export interface LiveConfigOptions {
 
   /** Additional Playwright `use` options, merged with defaults. */
   use?: Record<string, unknown>;
+
+  /** External MCP server config. Omit for sunpeak framework projects. */
+  server?: {
+    /** Server URL (e.g., 'http://localhost:8000/mcp') */
+    url?: string;
+    /** Server start command */
+    command?: string;
+    /** Command arguments */
+    args?: string[];
+  };
 }
 
 export interface HostConfigOptions {