supipowers 0.3.0 → 0.5.0

package/src/qa/prompt-builder.ts

@@ -0,0 +1,212 @@
+import type { AppTypeInfo, E2eQaConfig } from "./types.js";
+
+export interface E2ePromptOptions {
+  cwd: string;
+  appType: AppTypeInfo;
+  sessionDir: string;
+  scriptsDir: string;
+  config: E2eQaConfig;
+  discoveredRoutes: string;
+  previousMatrix: string | null;
+  skillContent: string;
+}
+
+export function buildE2eOrchestratorPrompt(options: E2ePromptOptions): string {
+  const { appType, sessionDir, scriptsDir, config, discoveredRoutes, previousMatrix, skillContent } = options;
+  const { playwright, execution } = config;
+
+  const sections: string[] = [
+    "# E2E QA Pipeline — Autonomous Execution",
+    "",
+    `You are an autonomous E2E QA pipeline for a **${appType.type}** application.`,
+    "Run all phases sequentially without stopping. Use the provided scripts for heavy operations.",
+    "",
+    "## Session Context",
+    "",
+    `- Session dir: \`${sessionDir}\``,
+    `- Base URL: \`${appType.baseUrl}\``,
+    `- Dev command: \`${appType.devCommand}\``,
+    `- Port: ${appType.port}`,
+    `- Browser: ${playwright.browser}`,
+    `- Headless: ${playwright.headless}`,
+    `- Test timeout: ${playwright.timeout}ms`,
+    `- maxRetries: ${execution.maxRetries}`,
+    `- maxFlows: ${execution.maxFlows}`,
+    "",
+  ];
+
+  // Previous matrix
+  if (previousMatrix) {
+    sections.push(
+      "## Previous Matrix",
+      "",
+      "Last-known flow states from `.omp/supipowers/e2e-matrix.json`:",
+      "",
+      "```json",
+      previousMatrix,
+      "```",
+      "",
+      "Compare your findings against this matrix to detect regressions, new flows, and removed flows.",
+      "",
+    );
+  }
+
+  // Discovered routes
+  sections.push(
+    "## Discovered Routes",
+    "",
+    "Pre-scanned routes/pages/forms from the codebase (JSONL):",
+    "",
+    "```jsonl",
+    discoveredRoutes,
+    "```",
+    "",
+    "Use these as a starting point. You may discover additional flows by reading the codebase.",
+    "",
+  );
+
+  // Skill content
+  if (skillContent) {
+    sections.push(
+      "## E2E Testing Methodology",
+      "",
+      skillContent,
+      "",
+    );
+  }
+
+  // Step 1: Flow Discovery
+  sections.push(
+    "## Step 1: Flow Discovery",
+    "",
+    "Analyze the discovered routes and the codebase to identify user flows:",
+    "",
+    "1. Read the route scan output above",
+    "2. Explore the codebase for additional flows not captured by the scan (modals, multi-step wizards, etc.)",
+    "3. Identify forms, auth flows, CRUD operations, navigation patterns",
+    "4. Compare against the previous matrix (if any) to detect:",
+    "   - **New flows**: routes that weren't in the matrix before",
+    "   - **Removed flows**: routes in the matrix that no longer exist",
+    "   - **Changed flows**: routes whose structure or behavior changed",
+    "5. Assign priority: critical (auth, payment), high (core CRUD), medium (secondary features), low (nice-to-have)",
+    `6. Write the flow manifest to \`${sessionDir}/flows.json\``,
+    "",
+  );
+
+  // Step 2: Test Generation
+  sections.push(
+    "## Step 2: Test Generation",
+    "",
+    "Write playwright test specs for each discovered flow:",
+    "",
+    `1. Create \`.spec.ts\` files in \`${sessionDir}/tests/\``,
+    "2. Each flow gets its own test file",
+    "3. Use playwright best practices:",
+    "   - Use `page.getByRole()`, `page.getByText()`, `page.getByTestId()` for locators",
+    "   - Use `expect(page).toHaveURL()`, `expect(locator).toBeVisible()` for assertions",
+    "   - Use `page.waitForLoadState('networkidle')` or `page.waitForSelector()` before assertions",
+    "   - Set meaningful test descriptions that describe the user journey",
+    `4. Import from \`@playwright/test\``,
+    `5. Each test should start with \`await page.goto('${appType.baseUrl}/...')\``,
+    "",
+    "Example test structure:",
+    "```typescript",
+    "import { test, expect } from '@playwright/test';",
+    "",
+    "test.describe('Login flow', () => {",
+    "  test('should log in with valid credentials', async ({ page }) => {",
+    `    await page.goto('${appType.baseUrl}/login');`,
+    "    await page.getByLabel('Email').fill('user@example.com');",
+    "    await page.getByLabel('Password').fill('password123');",
+    "    await page.getByRole('button', { name: 'Sign in' }).click();",
+    `    await expect(page).toHaveURL('${appType.baseUrl}/dashboard');`,
+    "  });",
+    "});",
+    "```",
+    "",
+  );
+
+  // Step 3: Execution
+  sections.push(
+    "## Step 3: Execution",
+    "",
+    "Run the generated tests:",
+    "",
+    `1. Start the dev server:`,
+    "```bash",
+    `bash ${scriptsDir}/start-dev-server.sh "${options.cwd}" "${appType.devCommand}" ${appType.port} 60 "${sessionDir}"`,
+    "```",
+    "   Read the JSON output. If `ready: false`, stop and report the error.",
+    "",
+    "2. Run the tests — **IMPORTANT: never run playwright directly. Always use the script:**",
+    "```bash",
+    `bash ${scriptsDir}/run-e2e-tests.sh "${sessionDir}/tests" "${appType.baseUrl}"`,
+    "```",
+    "   Read the JSON output. It contains `total`, `passed`, `failed`, `failures[]`.",
+    "",
+    `3. If there are failures and retries remain (max ${execution.maxRetries}):`,
+    "   - Read the `failures` array (do NOT read full test output)",
+    "   - Analyze each failure: is it a test issue or a real app bug?",
+    "   - If test issue: fix the test file and re-run",
+    "   - If real app bug: note it for the report",
+    "",
+    "4. Stop the dev server:",
+    "```bash",
+    `bash ${scriptsDir}/stop-dev-server.sh "${sessionDir}"`,
+    "```",
+    "",
+  );
+
+  // Step 4: Regression Analysis & Reporting
+  sections.push(
+    "## Step 4: Regression Analysis & Reporting",
+    "",
+    "Compare results against the previous matrix to detect regressions:",
+    "",
+    "For each flow that was **passing** in the matrix but now **fails**:",
+    "- This is a **regression** — record it in the ledger's `regressions` array:",
+    '  `{ "flowId": "...", "flowName": "...", "previousStatus": "pass", "currentStatus": "fail", "error": "..." }`',
+    "",
+    "Update the persistent matrix at `.omp/supipowers/e2e-matrix.json`:",
+    "- Update `lastStatus` and `lastTestedAt` for each tested flow",
+    "- Add new flows with `lastStatus: \"untested\"` and `addedAt` timestamp",
+    "- Mark removed flows with `removedAt` timestamp (don't delete them)",
+    "",
+    "Write the final report to the session ledger:",
+    "- Total flows tested, passed, failed",
+    "- List of regressions (if any)",
+    "- List of new flows discovered",
+    "- Coverage summary",
+    "",
+    `Update the session ledger at \`${sessionDir}/ledger.json\` with results and mark all phases completed.`,
+    "",
+  );
+
+  // Script paths
+  sections.push(
+    "## Script Paths",
+    "",
+    `- detect-app-type.sh: \`${scriptsDir}/detect-app-type.sh\``,
+    `- discover-routes.sh: \`${scriptsDir}/discover-routes.sh\``,
+    `- ensure-playwright.sh: \`${scriptsDir}/ensure-playwright.sh\``,
+    `- start-dev-server.sh: \`${scriptsDir}/start-dev-server.sh\``,
+    `- run-e2e-tests.sh: \`${scriptsDir}/run-e2e-tests.sh\``,
+    `- stop-dev-server.sh: \`${scriptsDir}/stop-dev-server.sh\``,
+    "",
+  );
+
+  // Token guidance
+  sections.push(
+    "## Token Guidance",
+    "",
+    "To minimize token usage:",
+    "- Always use `run-e2e-tests.sh` — never run playwright directly",
+    "- Only read the `failures` array from test results, skip passed tests",
+    "- Don't cat full test files when analyzing failures — read only the failing line range",
+    "- Write tests incrementally by flow group, run after each group to catch issues early",
+    "- Don't dump raw playwright output — the script produces a compact JSON summary",
+    "",
+  );
+
+  return sections.join("\n");
+}

package/src/qa/scripts/detect-app-type.sh

@@ -0,0 +1,68 @@
+#!/usr/bin/env bash
+# Detect web app framework, dev command, and port.
+# Usage: detect-app-type.sh <cwd>
+# Output: JSON on stdout
+set -euo pipefail
+
+CWD="${1:-.}"
+
+type="generic"
+devCommand="npm run dev"
+port=3000
+
+# Check for Next.js
+if [ -f "$CWD/next.config.js" ] || [ -f "$CWD/next.config.mjs" ] || [ -f "$CWD/next.config.ts" ]; then
+  if [ -d "$CWD/app" ]; then
+    type="nextjs-app"
+  elif [ -d "$CWD/src/app" ]; then
+    type="nextjs-app"
+  elif [ -d "$CWD/pages" ] || [ -d "$CWD/src/pages" ]; then
+    type="nextjs-pages"
+  else
+    type="nextjs-app"
+  fi
+  port=3000
+
+# Check for Vite
+elif [ -f "$CWD/vite.config.ts" ] || [ -f "$CWD/vite.config.js" ] || [ -f "$CWD/vite.config.mjs" ]; then
+  type="vite"
+  port=5173
+
+# Check for Angular
+elif [ -f "$CWD/angular.json" ]; then
+  type="generic"
+  devCommand="npm start"
+  port=4200
+
+# Check for Express (look for express in dependencies)
+elif [ -f "$CWD/package.json" ]; then
+  if grep -q '"express"' "$CWD/package.json" 2>/dev/null; then
+    type="express"
+    port=3000
+  fi
+fi
+
+# Try to detect dev command from package.json scripts
+if [ -f "$CWD/package.json" ]; then
+  # Check for common dev script names
+  if node -e "const p=JSON.parse(require('fs').readFileSync('$CWD/package.json','utf8')); process.exit(p.scripts?.dev ? 0 : 1)" 2>/dev/null; then
+    devCommand="npm run dev"
+  elif node -e "const p=JSON.parse(require('fs').readFileSync('$CWD/package.json','utf8')); process.exit(p.scripts?.start ? 0 : 1)" 2>/dev/null; then
+    devCommand="npm start"
+  elif node -e "const p=JSON.parse(require('fs').readFileSync('$CWD/package.json','utf8')); process.exit(p.scripts?.serve ? 0 : 1)" 2>/dev/null; then
+    devCommand="npm run serve"
+  fi
+
+  # Try to detect port from scripts
+  devScript=$(node -e "const p=JSON.parse(require('fs').readFileSync('$CWD/package.json','utf8')); console.log(p.scripts?.dev || p.scripts?.start || '')" 2>/dev/null || echo "")
+  portMatch=$(echo "$devScript" | grep -oE '(--port|PORT=)\s*([0-9]+)' | grep -oE '[0-9]+' | head -1 || echo "")
+  if [ -n "$portMatch" ]; then
+    port="$portMatch"
+  fi
+fi
+
+baseUrl="http://localhost:$port"
+
+cat <<EOF
+{"type": "$type", "devCommand": "$devCommand", "port": $port, "baseUrl": "$baseUrl"}
+EOF

package/src/qa/scripts/discover-routes.sh

@@ -0,0 +1,143 @@
+#!/usr/bin/env bash
+# Scan project for routes, pages, forms, and auth flows.
+# Usage: discover-routes.sh <cwd> <app_type>
+# Output: JSONL on stdout (one JSON object per line)
+set -euo pipefail
+
+CWD="${1:-.}"
+APP_TYPE="${2:-generic}"
+
+cd "$CWD"
+
+# Helper: output a route as JSONL
+emit() {
+  local routePath="$1" file="$2" type="$3" hasForm="${4:-false}" methods="${5:-}"
+  if [ -n "$methods" ]; then
+    echo "{\"path\": \"$routePath\", \"file\": \"$file\", \"type\": \"$type\", \"hasForm\": $hasForm, \"methods\": $methods}"
+  else
+    echo "{\"path\": \"$routePath\", \"file\": \"$file\", \"type\": \"$type\", \"hasForm\": $hasForm}"
+  fi
+}
+
+# Check if file likely contains a form
+has_form() {
+  local file="$1"
+  grep -qE '(<form|onSubmit|handleSubmit|useForm|formik|react-hook-form)' "$file" 2>/dev/null && echo "true" || echo "false"
+}
+
+case "$APP_TYPE" in
+  nextjs-app)
+    # Scan app/ directory for page.tsx/page.jsx/page.ts/page.js files
+    for dir in "app" "src/app"; do
+      if [ -d "$dir" ]; then
+        find "$dir" -name 'page.tsx' -o -name 'page.jsx' -o -name 'page.ts' -o -name 'page.js' 2>/dev/null | while read -r file; do
+          # Convert file path to route: app/login/page.tsx -> /login
+          route=$(echo "$file" | sed "s|^$dir||" | sed 's|/page\.\(tsx\|jsx\|ts\|js\)$||' | sed 's|^$|/|')
+          # Skip route groups (parenthesized segments)
+          if echo "$route" | grep -qE '\([^)]+\)'; then
+            route=$(echo "$route" | sed 's|/([^)]*)||g')
+          fi
+          [ -z "$route" ] && route="/"
+          formFlag=$(has_form "$file")
+          emit "$route" "$file" "page" "$formFlag"
+        done
+
+        # Scan for API routes
+        find "$dir" -name 'route.tsx' -o -name 'route.ts' -o -name 'route.js' 2>/dev/null | while read -r file; do
+          route=$(echo "$file" | sed "s|^$dir||" | sed 's|/route\.\(tsx\|ts\|js\)$||')
+          methods=$(grep -oE '(GET|POST|PUT|PATCH|DELETE)' "$file" 2>/dev/null | sort -u | awk 'BEGIN{ORS=""} NR>1{printf ","} {printf "\"%s\"", $0}' || echo "")
+          [ -n "$methods" ] && methods="[$methods]" || methods='["GET"]'
+          emit "$route" "$file" "api" "false" "$methods"
+        done
+      fi
+    done
+    ;;
+
+  nextjs-pages)
+    # Scan pages/ directory
+    for dir in "pages" "src/pages"; do
+      if [ -d "$dir" ]; then
+        find "$dir" -name '*.tsx' -o -name '*.jsx' -o -name '*.ts' -o -name '*.js' 2>/dev/null | while read -r file; do
+          # Skip _app, _document, _error, api files
+          basename=$(basename "$file")
+          case "$basename" in _app.* | _document.* | _error.*) continue;; esac
+
+          route=$(echo "$file" | sed "s|^$dir||" | sed 's|\.\(tsx\|jsx\|ts\|js\)$||' | sed 's|/index$|/|')
+          [ -z "$route" ] && route="/"
+
+          # Check if it's an API route
+          if echo "$file" | grep -q '/api/'; then
+            methods=$(grep -oE '(GET|POST|PUT|PATCH|DELETE)' "$file" 2>/dev/null | sort -u | awk 'BEGIN{ORS=""} NR>1{printf ","} {printf "\"%s\"", $0}' || echo "")
+            [ -n "$methods" ] && methods="[$methods]" || methods='["GET"]'
+            emit "$route" "$file" "api" "false" "$methods"
+          else
+            formFlag=$(has_form "$file")
+            emit "$route" "$file" "page" "$formFlag"
+          fi
+        done
+      fi
+    done
+    ;;
+
+  react-router)
+    # Grep for Route path= patterns
+    grep -rn --include='*.tsx' --include='*.jsx' --include='*.ts' --include='*.js' \
+      -E '<Route\s+.*path=' "$CWD/src" 2>/dev/null | while read -r line; do
+      file=$(echo "$line" | cut -d: -f1)
+      routePath=$(echo "$line" | grep -oE 'path="[^"]*"' | head -1 | sed 's/path="//;s/"//')
+      [ -z "$routePath" ] && continue
+      formFlag=$(has_form "$file")
+      emit "$routePath" "$file" "page" "$formFlag"
+    done || true
+
+    # Also check for createBrowserRouter patterns
+    grep -rn --include='*.tsx' --include='*.jsx' --include='*.ts' --include='*.js' \
+      -E 'path:\s*["\x27]' "$CWD/src" 2>/dev/null | while read -r line; do
+      file=$(echo "$line" | cut -d: -f1)
+      routePath=$(echo "$line" | grep -oE "path:\s*[\"'][^\"']*[\"']" | head -1 | sed "s/path:\s*[\"']//;s/[\"']//")
+      [ -z "$routePath" ] && continue
+      formFlag=$(has_form "$file")
+      emit "$routePath" "$file" "page" "$formFlag"
+    done || true
+    ;;
+
+  express)
+    # Grep for app.get/post/put/delete/use patterns
+    grep -rn --include='*.ts' --include='*.js' \
+      -E '\.(get|post|put|patch|delete|use)\s*\(\s*["\x27/]' "$CWD/src" "$CWD/routes" "$CWD/server" 2>/dev/null | while read -r line; do
+      file=$(echo "$line" | cut -d: -f1)
+      method=$(echo "$line" | grep -oE '\.(get|post|put|patch|delete)' | head -1 | tr -d '.')
+      routePath=$(echo "$line" | grep -oE "[\"'][/][^\"']*[\"']" | head -1 | tr -d "\"'")
+      [ -z "$routePath" ] && continue
+      [ -z "$method" ] && method="GET"
+      methods="[\"$(echo "$method" | tr '[:lower:]' '[:upper:]')\"]"
+      emit "$routePath" "$file" "api" "false" "$methods"
+    done || true
+    ;;
+
+  vite|generic)
+    # Generic: look for common patterns
+    if [ -d "src" ]; then
+      # Check for React Router in any form
+      grep -rln --include='*.tsx' --include='*.jsx' --include='*.ts' --include='*.js' \
+        -E '(<Route|createBrowserRouter|useRoutes)' src/ 2>/dev/null | while read -r file; do
+        grep -oE 'path[=:]\s*["\x27][^"\x27]*["\x27]' "$file" 2>/dev/null | while read -r match; do
+          routePath=$(echo "$match" | sed "s/path[=:]\s*[\"']//;s/[\"']//")
+          [ -z "$routePath" ] && continue
+          formFlag=$(has_form "$file")
+          emit "$routePath" "$file" "page" "$formFlag"
+        done
+      done || true
+    fi
+    ;;
+esac
+
+# Always scan for auth-related files regardless of framework
+find "$CWD/src" -type f \( -name '*auth*' -o -name '*login*' -o -name '*signup*' -o -name '*register*' \) \
+  -not -path '*/node_modules/*' -not -path '*/.next/*' -not -name '*.test.*' -not -name '*.spec.*' 2>/dev/null | while read -r file; do
+  # Only emit if not already covered by framework-specific scan
+  formFlag=$(has_form "$file")
+  # Use filename as hint for route
+  basename=$(basename "$file" | sed 's/\.\(tsx\|jsx\|ts\|js\)$//')
+  emit "/$basename" "$file" "auth" "$formFlag"
+done || true

package/src/qa/scripts/ensure-playwright.sh

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+# Check if playwright is installed, install if needed.
+# Usage: ensure-playwright.sh <cwd>
+# Output: JSON on stdout
+set -euo pipefail
+
+CWD="${1:-.}"
+cd "$CWD"
+
+installed=false
+browsers="[]"
+
+# Check if playwright is available
+if npx playwright --version >/dev/null 2>&1; then
+  installed=true
+else
+  # Try to install playwright
+  if npm install --save-dev @playwright/test >/dev/null 2>&1; then
+    installed=true
+  else
+    echo '{"installed": false, "browsers": [], "error": "Failed to install @playwright/test"}'
+    exit 1
+  fi
+fi
+
+# Install chromium browser if not present
+if $installed; then
+  if npx playwright install chromium >/dev/null 2>&1; then
+    browsers='["chromium"]'
+  else
+    echo '{"installed": true, "browsers": [], "error": "Failed to install chromium browser"}'
+    exit 1
+  fi
+fi
+
+cat <<EOF
+{"installed": $installed, "browsers": $browsers}
+EOF

package/src/qa/scripts/run-e2e-tests.sh

@@ -0,0 +1,99 @@
+#!/usr/bin/env bash
+# Run playwright tests and produce a compact JSON summary.
+# Usage: run-e2e-tests.sh <test_dir> <base_url> [test_filter]
+# Output: Compact JSON summary on stdout
+set -euo pipefail
+
+TEST_DIR="$1"
+BASE_URL="$2"
+TEST_FILTER="${3:-}"
+RESULTS_DIR="${TEST_DIR}/../results"
+SCREENSHOTS_DIR="${TEST_DIR}/../screenshots"
+
+mkdir -p "$RESULTS_DIR" "$SCREENSHOTS_DIR"
+
+# Build playwright command
+PW_ARGS=(
+  test
+  "$TEST_DIR"
+  --reporter=json
+  --output="$RESULTS_DIR"
+)
+
+if [ -n "$TEST_FILTER" ]; then
+  PW_ARGS+=(--grep "$TEST_FILTER")
+fi
+
+# Run playwright, capture JSON output
+RAW_OUTPUT="$RESULTS_DIR/raw-results.json"
+set +e
+BASE_URL="$BASE_URL" npx playwright "${PW_ARGS[@]}" > "$RAW_OUTPUT" 2>/dev/null
+PW_EXIT=$?
+set -e
+
+# If no JSON output was produced, create a minimal error report
+if [ ! -s "$RAW_OUTPUT" ]; then
+  cat <<EOF
+{"total": 0, "passed": 0, "failed": 0, "skipped": 0, "duration": 0, "failures": [], "error": "Playwright produced no output (exit code: $PW_EXIT)"}
+EOF
+  exit 0
+fi
+
+# Parse the JSON output into compact summary using node (more reliable than jq)
+node -e "
+const fs = require('fs');
+const raw = JSON.parse(fs.readFileSync('$RAW_OUTPUT', 'utf-8'));
+
+const suites = raw.suites || [];
+const results = [];
+
+function collectTests(suite, parentTitle) {
+  const title = parentTitle ? parentTitle + ' > ' + suite.title : suite.title;
+  for (const spec of (suite.specs || [])) {
+    for (const test of (spec.tests || [])) {
+      for (const result of (test.results || [])) {
+        results.push({
+          test: title + ' > ' + spec.title,
+          file: spec.file + (spec.line ? ':' + spec.line : ''),
+          status: result.status,
+          duration: result.duration || 0,
+          error: result.error?.message || null,
+        });
+      }
+    }
+  }
+  for (const child of (suite.suites || [])) {
+    collectTests(child, title);
+  }
+}
+
+for (const suite of suites) {
+  collectTests(suite, '');
+}
+
+const passed = results.filter(r => r.status === 'passed').length;
+const failed = results.filter(r => r.status === 'failed' || r.status === 'timedOut').length;
+const skipped = results.filter(r => r.status === 'skipped').length;
+const totalDuration = results.reduce((sum, r) => sum + r.duration, 0);
+
+const failures = results
+  .filter(r => r.status === 'failed' || r.status === 'timedOut')
+  .map(r => ({
+    test: r.test,
+    file: r.file,
+    error: r.error || 'Unknown error',
+  }));
+
+const summary = {
+  total: results.length,
+  passed,
+  failed,
+  skipped,
+  duration: totalDuration,
+  failures,
+};
+
+console.log(JSON.stringify(summary));
+" 2>/dev/null || cat <<EOF
+{"total": 0, "passed": 0, "failed": 0, "skipped": 0, "duration": 0, "failures": [], "error": "Failed to parse playwright output"}
+EOF

package/src/qa/scripts/start-dev-server.sh

@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+# Start the dev server in the background and wait for it to be ready.
+# Usage: start-dev-server.sh <cwd> <dev_command> <port> <timeout_seconds> <session_dir>
+# Output: JSON on stdout
+set -euo pipefail
+
+CWD="$1"
+DEV_COMMAND="$2"
+PORT="$3"
+TIMEOUT="${4:-60}"
+SESSION_DIR="${5:-.}"
+
+cd "$CWD"
+
+# Check if port is already in use
+if curl -s -o /dev/null -w "%{http_code}" "http://localhost:$PORT" 2>/dev/null | grep -qE '^[0-9]'; then
+  echo "{\"pid\": null, \"url\": \"http://localhost:$PORT\", \"ready\": true, \"note\": \"Server already running\"}"
+  exit 0
+fi
+
+# Start dev server in background
+eval "$DEV_COMMAND" > "$SESSION_DIR/dev-server.log" 2>&1 &
+PID=$!
+echo "$PID" > "$SESSION_DIR/dev-server.pid"
+
+# Wait for server to be ready
+for i in $(seq 1 "$TIMEOUT"); do
+  # Check if process is still alive
+  if ! kill -0 "$PID" 2>/dev/null; then
+    echo "{\"pid\": $PID, \"url\": \"http://localhost:$PORT\", \"ready\": false, \"error\": \"Server process exited\"}"
+    exit 1
+  fi
+
+  # Check if port responds
+  if curl -s -o /dev/null "http://localhost:$PORT" 2>/dev/null; then
+    echo "{\"pid\": $PID, \"url\": \"http://localhost:$PORT\", \"ready\": true}"
+    exit 0
+  fi
+
+  sleep 1
+done
+
+# Timeout — kill the server
+kill "$PID" 2>/dev/null || true
+echo "{\"pid\": $PID, \"url\": \"http://localhost:$PORT\", \"ready\": false, \"error\": \"Timeout after ${TIMEOUT}s\"}"
+exit 1

package/src/qa/scripts/stop-dev-server.sh

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+# Stop the dev server started by start-dev-server.sh.
+# Usage: stop-dev-server.sh <session_dir>
+set -euo pipefail
+
+SESSION_DIR="${1:-.}"
+PID_FILE="$SESSION_DIR/dev-server.pid"
+
+if [ ! -f "$PID_FILE" ]; then
+  echo '{"stopped": false, "error": "No PID file found"}'
+  exit 0
+fi
+
+PID=$(cat "$PID_FILE")
+
+if [ -z "$PID" ]; then
+  echo '{"stopped": false, "error": "Empty PID file"}'
+  exit 0
+fi
+
+# Kill the process and its children
+if kill -0 "$PID" 2>/dev/null; then
+  # Kill process group if possible
+  kill -- -"$PID" 2>/dev/null || kill "$PID" 2>/dev/null || true
+  # Wait briefly for cleanup
+  sleep 1
+  # Force kill if still alive
+  if kill -0 "$PID" 2>/dev/null; then
+    kill -9 "$PID" 2>/dev/null || true
+  fi
+  rm -f "$PID_FILE"
+  echo "{\"stopped\": true, \"pid\": $PID}"
+else
+  rm -f "$PID_FILE"
+  echo "{\"stopped\": true, \"pid\": $PID, \"note\": \"Process was already dead\"}"
+fi