openspec-playwright 0.3.42 → 0.3.44

package/dist/shared/mcp.d.ts

@@ -1,19 +1,18 @@
 /**
- * Check if Playwright MCP server is installed in Claude Code.
- * Returns true if "playwright" appears in `claude mcp list` output.
+ * Shared MCP (Model Context Protocol) utilities.
  *
- * Note: `claude mcp list` may exit non-zero if another MCP server is
- * pending approval or unhealthy, while still printing the list. In that
- * case, read stdout/stderr from the thrown error before returning false.
+ * Dispatches Playwright MCP install/remove to the right editor adapter.
+ * Each adapter handles its own install mechanism (`claude mcp add` vs
+ * editing `opencode.jsonc`), so this layer just routes the call and
+ * prints status messages.
  */
-export declare function isPlaywrightMcpInstalled(): boolean;
-/**
- * Ensure Playwright MCP server is installed globally.
- * Prints status messages. Throws on failure.
- */
-export declare function ensurePlaywrightMcp(): void;
-/**
- * Remove Playwright MCP server from Claude Code.
- * Prints status messages. Does not throw if already absent.
- */
-export declare function removePlaywrightMcp(): void;
+import { type EditorAdapter } from "../commands/editors.js";
+/** Check if the named MCP server is installed in this editor. */
+export declare function isMcpInstalled(adapter: EditorAdapter, serverName: string): boolean;
+/** Install an MCP server in this editor. Throws on failure. */
+export declare function ensureMcp(adapter: EditorAdapter, serverName: string, command: string[]): void;
+/** Remove an MCP server from this editor. Does not throw if missing. */
+export declare function removeMcp(adapter: EditorAdapter, serverName: string): void;
+export declare function isPlaywrightMcpInstalled(adapter: EditorAdapter): boolean;
+export declare function ensurePlaywrightMcp(adapter: EditorAdapter): void;
+export declare function removePlaywrightMcp(adapter: EditorAdapter): void;

package/dist/shared/mcp.js

@@ -1,81 +1,45 @@
-/**
- * Shared MCP (Model Context Protocol) utilities.
- * Centralizes claude mcp check / install / remove logic.
- */
-import { execFileSync } from "node:child_process";
-import { TIMEOUT } from "./constants.js";
-import { needsShell } from "./platform.js";
-function outputIncludesPlaywright(output) {
-    return String(output ?? "").includes("playwright");
+/** Check if the named MCP server is installed in this editor. */
+export function isMcpInstalled(adapter, serverName) {
+    return adapter.isMcpInstalled(process.cwd(), serverName);
 }
-/**
- * Check if Playwright MCP server is installed in Claude Code.
- * Returns true if "playwright" appears in `claude mcp list` output.
- *
- * Note: `claude mcp list` may exit non-zero if another MCP server is
- * pending approval or unhealthy, while still printing the list. In that
- * case, read stdout/stderr from the thrown error before returning false.
- */
-export function isPlaywrightMcpInstalled() {
-    try {
-        const output = execFileSync("claude", ["mcp", "list"], {
-            encoding: "utf-8",
-            timeout: TIMEOUT.MCP_LIST,
-            stdio: ["pipe", "pipe", "pipe"],
-            shell: needsShell,
-        });
-        return outputIncludesPlaywright(output);
-    }
-    catch (err) {
-        const e = err;
-        return outputIncludesPlaywright(e.stdout) || outputIncludesPlaywright(e.stderr);
-    }
-}
-/**
- * Ensure Playwright MCP server is installed globally.
- * Prints status messages. Throws on failure.
- */
-export function ensurePlaywrightMcp() {
-    if (isPlaywrightMcpInstalled()) {
-        console.log("  ✓ Playwright MCP already installed");
+/** Install an MCP server in this editor. Throws on failure. */
+export function ensureMcp(adapter, serverName, command) {
+    if (isMcpInstalled(adapter, serverName)) {
+        console.log(`  ✓ ${adapter.label}: ${serverName} MCP already installed`);
         return;
     }
     try {
-        execFileSync("claude", ["mcp", "add", "playwright", "npx", "@playwright/mcp@latest"], {
-            encoding: "utf-8",
-            timeout: TIMEOUT.MCP_LIST,
-            stdio: ["pipe", "pipe", "pipe"],
-            shell: needsShell,
-        });
-        console.log("  ✓ Playwright MCP installed globally");
+        adapter.installMcp(process.cwd(), serverName, command);
+        console.log(`  ✓ ${adapter.label}: ${serverName} MCP installed`);
     }
-    catch {
-        console.warn("  ⚠ Failed to install Playwright MCP");
-        console.log("  Run manually: claude mcp add playwright npx @playwright/mcp@latest");
-        throw new Error("MCP installation failed");
+    catch (err) {
+        console.warn(`  ⚠ ${adapter.label}: failed to install ${serverName} MCP`);
+        throw err;
     }
 }
-/**
- * Remove Playwright MCP server from Claude Code.
- * Prints status messages. Does not throw if already absent.
- */
-export function removePlaywrightMcp() {
-    if (!isPlaywrightMcpInstalled()) {
-        console.log("  ✓ Playwright MCP not installed (nothing to remove)");
+/** Remove an MCP server from this editor. Does not throw if missing. */
+export function removeMcp(adapter, serverName) {
+    if (!isMcpInstalled(adapter, serverName)) {
+        console.log(`  - ${adapter.label}: ${serverName} MCP not installed (nothing to remove)`);
         return;
     }
     try {
-        execFileSync("claude", ["mcp", "remove", "playwright"], {
-            encoding: "utf-8",
-            timeout: TIMEOUT.MCP_LIST,
-            stdio: ["pipe", "pipe", "pipe"],
-            shell: needsShell,
-        });
-        console.log("  ✓ Playwright MCP removed");
+        adapter.removeMcp(process.cwd(), serverName);
+        console.log(`  ✓ ${adapter.label}: ${serverName} MCP removed`);
     }
     catch {
-        console.warn("  ⚠ Failed to remove Playwright MCP");
-        console.log("  Run manually: claude mcp remove playwright");
+        console.warn(`  ⚠ ${adapter.label}: failed to remove ${serverName} MCP`);
     }
 }
+// ─── Playwright MCP conveniences ────────────────────────────────────────
+const PLAYWRIGHT_MCP_COMMAND = ["npx", "@playwright/mcp@latest"];
+export function isPlaywrightMcpInstalled(adapter) {
+    return isMcpInstalled(adapter, "playwright");
+}
+export function ensurePlaywrightMcp(adapter) {
+    ensureMcp(adapter, "playwright", PLAYWRIGHT_MCP_COMMAND);
+}
+export function removePlaywrightMcp(adapter) {
+    removeMcp(adapter, "playwright");
+}
 //# sourceMappingURL=mcp.js.map

package/dist/shared/mcp.js.map

@@ -1 +1 @@
-{"version":3,"file":"mcp.js","sourceRoot":"","sources":["../../src/shared/mcp.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AACzC,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAE3C,SAAS,wBAAwB,CAAC,MAAe;IAC/C,OAAO,MAAM,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC;AACrD,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,wBAAwB;IACtC,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,YAAY,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,CAAC,EAAE;YACrD,QAAQ,EAAE,OAAO;YACjB,OAAO,EAAE,OAAO,CAAC,QAAQ;YACzB,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC;YAC/B,KAAK,EAAE,UAAU;SAClB,CAAC,CAAC;QACH,OAAO,wBAAwB,CAAC,MAAM,CAAC,CAAC;IAC1C,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,CAAC,GAAG,GAA6C,CAAC;QACxD,OAAO,wBAAwB,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,wBAAwB,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;IAClF,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,mBAAmB;IACjC,IAAI,wBAAwB,EAAE,EAAE,CAAC;QAC/B,OAAO,CAAC,GAAG,CAAC,sCAAsC,CAAC,CAAC;QACpD,OAAO;IACT,CAAC;IAED,IAAI,CAAC;QACH,YAAY,CACV,QAAQ,EACR,CAAC,KAAK,EAAE,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE,wBAAwB,CAAC,EAC7D;YACE,QAAQ,EAAE,OAAO;YACjB,OAAO,EAAE,OAAO,CAAC,QAAQ;YACzB,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC;YAC/B,KAAK,EAAE,UAAU;SAClB,CACF,CAAC;QACF,OAAO,CAAC,GAAG,CAAC,uCAAuC,CAAC,CAAC;IACvD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,CAAC,IAAI,CAAC,sCAAsC,CAAC,CAAC;QACrD,OAAO,CAAC,GAAG,CAAC,sEAAsE,CAAC,CAAC;QACpF,MAAM,IAAI,KAAK,CAAC,yBAAyB,CAAC,CAAC;IAC7C,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,mBAAmB;IACjC,IAAI,CAAC,wBAAwB,EAAE,EAAE,CAAC;QAChC,OAAO,CAAC,GAAG,CAAC,sDAAsD,CAAC,CAAC;QACpE,OAAO;IACT,CAAC;IAED,IAAI,CAAC;QACH,YAAY,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,QAAQ,EAAE,YAAY,CAAC,EAAE;YACtD,QAAQ,EAAE,OAAO;YACjB,OAAO,EAAE,OAAO,CAAC,QAAQ;YACzB,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC;YAC/B,KAAK,EAAE,UAAU;SAClB,CAAC,CAAC;QACH,OAAO,CAAC,GAAG,CAAC,4BAA4B,CAAC,CAAC;IAC5C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,CAAC,IAAI,CAAC,qCAAqC,CAAC,CAAC;QACpD,OAAO,CAAC,GAAG,CAAC,8CAA8C,CAAC,CAAC;IAC9D,CAAC;AACH,CAAC"}
+{"version":3,"file":"mcp.js","sourceRoot":"","sources":["../../src/shared/mcp.ts"],"names":[],"mappings":"AAUA,iEAAiE;AACjE,MAAM,UAAU,cAAc,CAAC,OAAsB,EAAE,UAAkB;IACvE,OAAO,OAAO,CAAC,cAAc,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,UAAU,CAAC,CAAC;AAC3D,CAAC;AAED,+DAA+D;AAC/D,MAAM,UAAU,SAAS,CACvB,OAAsB,EACtB,UAAkB,EAClB,OAAiB;IAEjB,IAAI,cAAc,CAAC,OAAO,EAAE,UAAU,CAAC,EAAE,CAAC;QACxC,OAAO,CAAC,GAAG,CAAC,OAAO,OAAO,CAAC,KAAK,KAAK,UAAU,wBAAwB,CAAC,CAAC;QACzE,OAAO;IACT,CAAC;IACD,IAAI,CAAC;QACH,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,UAAU,EAAE,OAAO,CAAC,CAAC;QACvD,OAAO,CAAC,GAAG,CAAC,OAAO,OAAO,CAAC,KAAK,KAAK,UAAU,gBAAgB,CAAC,CAAC;IACnE,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,CAAC,IAAI,CAAC,OAAO,OAAO,CAAC,KAAK,uBAAuB,UAAU,MAAM,CAAC,CAAC;QAC1E,MAAM,GAAG,CAAC;IACZ,CAAC;AACH,CAAC;AAED,wEAAwE;AACxE,MAAM,UAAU,SAAS,CAAC,OAAsB,EAAE,UAAkB;IAClE,IAAI,CAAC,cAAc,CAAC,OAAO,EAAE,UAAU,CAAC,EAAE,CAAC;QACzC,OAAO,CAAC,GAAG,CAAC,OAAO,OAAO,CAAC,KAAK,KAAK,UAAU,wCAAwC,CAAC,CAAC;QACzF,OAAO;IACT,CAAC;IACD,IAAI,CAAC;QACH,OAAO,CAAC,SAAS,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,UAAU,CAAC,CAAC;QAC7C,OAAO,CAAC,GAAG,CAAC,OAAO,OAAO,CAAC,KAAK,KAAK,UAAU,cAAc,CAAC,CAAC;IACjE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,CAAC,IAAI,CAAC,OAAO,OAAO,CAAC,KAAK,sBAAsB,UAAU,MAAM,CAAC,CAAC;IAC3E,CAAC;AACH,CAAC;AAED,2EAA2E;AAE3E,MAAM,sBAAsB,GAAG,CAAC,KAAK,EAAE,wBAAwB,CAAC,CAAC;AAEjE,MAAM,UAAU,wBAAwB,CAAC,OAAsB;IAC7D,OAAO,cAAc,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;AAC/C,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,OAAsB;IACxD,SAAS,CAAC,OAAO,EAAE,YAAY,EAAE,sBAAsB,CAAC,CAAC;AAC3D,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,OAAsB;IACxD,SAAS,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;AACnC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openspec-playwright",
-  "version": "0.3.42",
+  "version": "0.3.44",
   "description": "OpenSpec + Playwright E2E verification setup tool for Claude Code",
   "type": "module",
   "bin": {
@@ -22,8 +22,9 @@
     "chalk": "^5.3.0",
     "commander": "^12.1.0",
     "glob": "^13.0.6",
+    "jsonc-parser": "^3.3.1",
     "playwright": "^1.50.0",
-    "tar": "^7.5.13"
+    "tar": "^7.5.16"
   },
   "devDependencies": {
     "@types/glob": "^8.1.0",
@@ -37,6 +38,9 @@
     "typescript": "^5.6.0",
     "vitest": "^4.1.2"
   },
+  "overrides": {
+    "vite": "^8.0.16"
+  },
   "engines": {
     "node": ">=20"
   },

package/templates/pages/BasePage.ts

@@ -4,7 +4,7 @@
 
 import { Page, Locator, expect } from '@playwright/test';
 
-const BASE_URL = process.env.BASE_URL || 'http://localhost:3000';
+const BASE_URL = process.env.BASE_URL;
 
 export class BasePage {
   protected page: Page;
@@ -23,7 +23,7 @@ export class BasePage {
     path: string,
     options?: { waitUntil?: 'domcontentloaded' | 'load' | 'networkidle' | 'commit' },
   ) {
-    const url = path.startsWith('http') ? path : `${BASE_URL}${path}`;
+    const url = path.startsWith('http') || !BASE_URL ? path : new URL(path, BASE_URL).toString();
     await this.page.goto(url, {
       waitUntil: options?.waitUntil ?? 'domcontentloaded',
     });

package/templates/playwright.config.ts

@@ -2,7 +2,7 @@ import { defineConfig, devices } from '@playwright/test';
 import { readFileSync, existsSync, readdirSync } from 'fs';
 import { join } from 'path';
 
-// ─── Detect project root (where openspec/ lives) ───
+// ─── Detect project root (where package.json lives) ───
 function findProjectRoot(start: string): string {
   let dir = start;
   for (let i = 0; i < 10; i++) {
@@ -23,7 +23,8 @@ function findNpmRoot(projectRoot: string, maxDepth = 5): string {
     if (existsSync(pkgPath)) {
       try {
         const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
-        if (pkg.scripts?.dev || pkg.scripts?.start || pkg.scripts?.serve || pkg.scripts?.preview) {
+        const scripts = pkg.scripts ?? {};
+        if (scripts['dev:all'] || scripts.dev || scripts.start || scripts.serve || scripts.preview) {
           return dir;
         }
       } catch {}
@@ -41,41 +42,116 @@ function findNpmRoot(projectRoot: string, maxDepth = 5): string {
   return search(projectRoot, 0) ?? projectRoot;
 }
 
+function parsePort(text: string): number | undefined {
+  const patterns = [
+    /(?:^|\s)(?:--port|-p)\s+([0-9]{2,5})(?:\s|$)/,
+    /(?:^|\s)--port=([0-9]{2,5})(?:\s|$)/,
+    /(?:^|\s)(?:PORT|VITE_PORT|PLAYWRIGHT_PORT|E2E_PORT)=([0-9]{2,5})(?:\s|$)/,
+    /port\s*:\s*([0-9]{2,5})/,
+  ];
+  for (const pattern of patterns) {
+    const match = text.match(pattern);
+    if (match) {
+      const port = Number(match[1]);
+      if (port > 0 && port <= 65535) return port;
+    }
+  }
+  return undefined;
+}
+
+function parseEnvPort(content: string): number | undefined {
+  const lines = content.split(/\r?\n/);
+  for (const key of ['PLAYWRIGHT_PORT', 'E2E_PORT', 'VITE_PORT', 'PORT']) {
+    for (const line of lines) {
+      const match = line.match(new RegExp(`^\\s*${key}\\s*=\\s*['\"]?([0-9]{2,5})['\"]?\\s*$`));
+      if (match) {
+        const port = Number(match[1]);
+        if (port > 0 && port <= 65535) return port;
+      }
+    }
+  }
+  return undefined;
+}
+
+function detectPortFromEnv(): number | undefined {
+  for (const key of ['PLAYWRIGHT_PORT', 'E2E_PORT', 'VITE_PORT', 'PORT']) {
+    const value = process.env[key];
+    if (!value) continue;
+    const port = Number(value);
+    if (Number.isInteger(port) && port > 0 && port <= 65535) return port;
+  }
+  return undefined;
+}
+
+function detectPortFromEnvFiles(npmRoot: string): number | undefined {
+  for (const file of ['.env.local', '.env.development', '.env']) {
+    const path = join(npmRoot, file);
+    if (!existsSync(path)) continue;
+    const port = parseEnvPort(readFileSync(path, 'utf-8'));
+    if (port) return port;
+  }
+  return undefined;
+}
+
+function detectVitePort(npmRoot: string): number | undefined {
+  for (const file of ['vite.config.ts', 'vite.config.mts', 'vite.config.js', 'vite.config.mjs', 'vite.config.cjs']) {
+    const path = join(npmRoot, file);
+    if (!existsSync(path)) continue;
+    const port = parsePort(readFileSync(path, 'utf-8'));
+    if (port) return port;
+  }
+  return undefined;
+}
+
+function frameworkDefaultPort(pkg: Record<string, any>, command = ''): number | undefined {
+  const deps = { ...(pkg.dependencies ?? {}), ...(pkg.devDependencies ?? {}) };
+  if (command.includes('vite') || deps.vite) return 5173;
+  if (command.includes('astro') || deps.astro) return 4321;
+  if (command.includes('next') || deps.next) return 3000;
+  if (command.includes('nuxt') || deps.nuxt) return 3000;
+  return undefined;
+}
+
 const projectRoot = findProjectRoot(process.cwd());
 const npmRoot = findNpmRoot(projectRoot);
+const npmPkg = join(npmRoot, 'package.json');
+const pkg = existsSync(npmPkg) ? JSON.parse(readFileSync(npmPkg, 'utf-8')) : {};
+const scripts = pkg.scripts ?? {};
+
+// ─── Dev command: detect from the npm project ───
+const scriptName = scripts['dev:all']
+  ? 'dev:all'
+  : scripts.dev
+    ? 'dev'
+    : scripts.start
+      ? 'start'
+      : scripts.serve
+        ? 'serve'
+        : scripts.preview
+          ? 'preview'
+          : 'dev';
+let devCmd = `npm run ${scriptName}`;
+if (npmRoot !== projectRoot) {
+  devCmd = `cd "${npmRoot}" && ${devCmd}`;
+}
 
-// ─── BASE_URL: prefer env, then seed.spec.ts, then default ───
+// ─── BASE_URL: prefer env, then detected port, then seed.spec.ts, then default ───
 const seedSpec = join(projectRoot, 'tests', 'playwright', 'seed.spec.ts');
-let baseUrl = process.env.BASE_URL || 'http://localhost:3000';
-if (!process.env.BASE_URL && existsSync(seedSpec)) {
+let baseUrl = process.env.BASE_URL;
+if (!baseUrl) {
+  const scriptPort = scripts[scriptName] ? parsePort(scripts[scriptName]) : undefined;
+  const port = detectPortFromEnv() ?? scriptPort ?? detectVitePort(npmRoot) ?? detectPortFromEnvFiles(npmRoot) ?? frameworkDefaultPort(pkg, scripts[scriptName]);
+  if (port) baseUrl = `http://localhost:${port}`;
+}
+if (!baseUrl && existsSync(seedSpec)) {
   const content = readFileSync(seedSpec, 'utf-8');
   const m = content.match(/BASE_URL\s*=\s*process\.env\.BASE_URL\s*\|\|\s*['"]([^'"]+)['"]/);
-  if (m) baseUrl = m[1];
-}
-
-// ─── Dev command: detect from the npm project ───
-let devCmd = 'npm run dev';
-const npmPkg = join(npmRoot, 'package.json');
-if (existsSync(npmPkg)) {
-  const pkg = JSON.parse(readFileSync(npmPkg, 'utf-8'));
-  const scripts = pkg.scripts ?? {};
-  const scriptName = scripts['dev:all']
-    ? 'dev:all'
-    : scripts.dev
-      ? 'dev'
-      : scripts.start
-        ? 'start'
-        : scripts.serve
-          ? 'serve'
-          : scripts.preview
-            ? 'preview'
-            : 'dev';
-  devCmd = `npm run ${scriptName}`;
-  // Prefix with cd if npmRoot differs from projectRoot
-  if (npmRoot !== projectRoot) {
-    devCmd = `cd ${npmRoot} && ${devCmd}`;
+  if (m) {
+    const candidate = m[1];
+    if (candidate.startsWith('http://') || candidate.startsWith('https://')) baseUrl = candidate;
   }
 }
+baseUrl ??= 'http://localhost:3000';
 
 const authStatePath = join(projectRoot, 'playwright', '.auth', 'user.json');
 const storageState = existsSync(authStatePath) ? authStatePath : undefined;

package/templates/seed.spec.ts

@@ -6,8 +6,8 @@ import { test, expect, Page, ConsoleMessage } from '@playwright/test';
 import { existsSync } from 'fs';
 import { BasePage } from './pages/BasePage';
 
-// Customize these for your application
-const BASE_URL = process.env.BASE_URL || 'http://localhost:3000';
+// Prefer Playwright config's use.baseURL; env var is still supported for one-off overrides.
+const BASE_URL = process.env.BASE_URL || '/';
 
 /**
  * Page Object Pattern - extends BasePage for shared utilities
@@ -69,7 +69,7 @@ test.describe('Application smoke tests', () => {
 
 test.describe('Environment validation', () => {
   test('BASE_URL responds 200', async ({ page }) => {
-    const res = await page.request.get(`${BASE_URL}/`);
+    const res = await page.request.get(BASE_URL);
     expect(res.status(), `BASE_URL ${BASE_URL} returned ${res.status()}`).toBeLessThan(500);
   });