jdi-cli 0.1.0

package/core/skills/frontend-validator/SKILL.md

@@ -0,0 +1,567 @@
+---
+name: jdi-frontend-validator
+description: Validates live UI via Playwright + axe-core. Detects Playwright; installs if missing (with user consent). Spawns dev server, navigates critical routes on mobile+desktop, captures console errors, network failures, a11y violations, screenshots, layout shifts. Structured JSON output for the reviewer to parse.
+type: skill
+applies_to: |
+  Loaded by jdi-reviewer-{slug} at gate 7 when `frontend.has_frontend: true` in .jdi/PROJECT.md.
+  Can be invoked manually for ad-hoc UI validation.
+loaded_by:
+  - jdi-reviewer-{slug} (conditional)
+runtime_overrides:
+  antigravity:
+    triggers:
+      - "validate UI"
+      - "run playwright"
+      - "check accessibility"
+      - "smoke test frontend"
+      - "validate live interface"
+---
+
+# Skill: jdi-frontend-validator
+
+Runs UI validation in a real browser. Without Playwright installed, installs with consent. Output always JSON in `.jdi/cache/ui-findings.json` for the parent reviewer to consume.
+
+## When to apply
+
+Reviewer calls at gate 7. Preconditions in PROJECT.md:
+
+```yaml
+frontend:
+  has_frontend: true
+  frontend_url: http://localhost:5173
+  dev_command: pnpm dev
+  critical_paths:
+    - /
+    - /login
+    - /dashboard
+```
+
+Missing any key -> abort with descriptive error.
+
+## Procedure
+
+### Step 1: Pre-flight
+
+```bash
+# bash
+test -d .jdi/ || { echo "No .jdi/. Run /jdi-new"; exit 1; }
+test -f .jdi/PROJECT.md || { echo "PROJECT.md missing"; exit 1; }
+
+# Read frontend.has_frontend, frontend_url, dev_command, critical_paths
+# (simple YAML parse - assume well-defined format)
+
+# Create cache
+mkdir -p .jdi/cache/screenshots
+
+# .gitignore guarantee
+grep -q '^\.jdi/cache/' .gitignore 2>/dev/null || echo '.jdi/cache/' >> .gitignore
+```
+
+```powershell
+# PowerShell
+if (-not (Test-Path .jdi)) { Write-Error "No .jdi/. Run /jdi-new"; exit 1 }
+if (-not (Test-Path .jdi/PROJECT.md)) { Write-Error "PROJECT.md missing"; exit 1 }
+
+New-Item -ItemType Directory -Force -Path .jdi/cache/screenshots | Out-Null
+
+if (-not (Test-Path .gitignore) -or -not (Select-String -Path .gitignore -Pattern '^\.jdi/cache/' -Quiet)) {
+  Add-Content .gitignore '.jdi/cache/'
+}
+```
+
+### Step 2: Detect package manager
+
+Lockfile detection (more reliable than `which`):
+
+```bash
+# bash
+if [ -f pnpm-lock.yaml ]; then PKG_MGR=pnpm
+elif [ -f yarn.lock ]; then PKG_MGR=yarn
+elif [ -f bun.lockb ] || [ -f bun.lock ]; then PKG_MGR=bun
+elif [ -f package-lock.json ]; then PKG_MGR=npm
+else PKG_MGR=npm  # fallback
+fi
+```
+
+```powershell
+# PowerShell
+if (Test-Path pnpm-lock.yaml) { $PKG_MGR = "pnpm" }
+elseif (Test-Path yarn.lock) { $PKG_MGR = "yarn" }
+elseif ((Test-Path bun.lockb) -or (Test-Path bun.lock)) { $PKG_MGR = "bun" }
+elseif (Test-Path package-lock.json) { $PKG_MGR = "npm" }
+else { $PKG_MGR = "npm" }
+```
+
+Corresponding install command:
+
+| Pkg mgr | Install dev dep | Run binary |
+|---|---|---|
+| npm | `npm install --save-dev <pkg>` | `npx <bin>` |
+| pnpm | `pnpm add -D <pkg>` | `pnpm exec <bin>` or `pnpm dlx <bin>` |
+| yarn | `yarn add -D <pkg>` | `yarn <bin>` |
+| bun | `bun add -d <pkg>` | `bunx <bin>` |
+
+### Step 3: Detect Playwright
+
+```bash
+# bash
+PW_BIN="npx --no-install playwright"
+[ "$PKG_MGR" = "pnpm" ] && PW_BIN="pnpm exec playwright"
+[ "$PKG_MGR" = "yarn" ] && PW_BIN="yarn playwright"
+[ "$PKG_MGR" = "bun" ] && PW_BIN="bunx playwright"
+
+if ! $PW_BIN --version >/dev/null 2>&1; then
+  PLAYWRIGHT_MISSING=1
+fi
+
+# Check axe-core/playwright separately
+if [ -f package.json ] && ! grep -q '@axe-core/playwright' package.json; then
+  AXE_MISSING=1
+fi
+```
+
+```powershell
+# PowerShell - simplified
+$pwExists = $false
+try {
+  $null = & npx --no-install playwright --version 2>$null
+  if ($LASTEXITCODE -eq 0) { $pwExists = $true }
+} catch {}
+if (-not $pwExists) { $env:PLAYWRIGHT_MISSING = "1" }
+
+$axeExists = $false
+if (Test-Path package.json) {
+  if (Select-String -Path package.json -Pattern '@axe-core/playwright' -Quiet) { $axeExists = $true }
+}
+if (-not $axeExists) { $env:AXE_MISSING = "1" }
+```
+
+### Step 4: If missing, ask consent + install
+
+Use AskUserQuestion (or prompt fallback if runtime doesn't support it):
+
+```
+Playwright not installed in this project.
+
+Install now?
+- [Yes, install with Chromium] (~150MB, 2-5min, recommended)
+- [Yes, install with all browsers] (~500MB, 5-10min)
+- [No, skip gate 7 this time] (gate returns SKIPPED)
+- [Cancel entire review]
+```
+
+Choice mapping:
+
+**Yes, Chromium:**
+```bash
+$INSTALL_CMD @playwright/test @axe-core/playwright
+$PLAYWRIGHT_INSTALL chromium
+```
+
+Where:
+- `$INSTALL_CMD` = `pnpm add -D` / `npm install --save-dev` / etc based on PKG_MGR
+- `$PLAYWRIGHT_INSTALL` = `$PW_BIN install`
+
+**Yes, all browsers:**
+```bash
+$INSTALL_CMD @playwright/test @axe-core/playwright
+$PLAYWRIGHT_INSTALL
+```
+
+**No, skip:**
+Returns `{ "status": "SKIPPED", "reason": "user declined Playwright install" }` - reviewer marks gate 7 as SKIPPED (not BLOCK).
+
+**Cancel review:**
+Returns error code, reviewer aborts.
+
+### Step 5: Generate temporary Playwright spec
+
+Creates `.jdi/cache/playwright-check.spec.js` (gitignored). Content:
+
+```javascript
+// Auto-generated by jdi-frontend-validator. DO NOT edit manually.
+// @ts-check
+const { test, expect } = require('@playwright/test');
+const AxeBuilder = require('@axe-core/playwright').default;
+const fs = require('fs');
+const path = require('path');
+
+const URL = process.env.JDI_FRONTEND_URL;
+const ROUTES = (process.env.JDI_ROUTES || '/').split(',').map(r => r.trim()).filter(Boolean);
+const OUT = process.env.JDI_OUT || '.jdi/cache/ui-findings.json';
+const SCREENSHOT_DIR = process.env.JDI_SCREENSHOT_DIR || '.jdi/cache/screenshots';
+
+const VIEWPORTS = [
+  { name: 'mobile', width: 375, height: 667 },
+  { name: 'desktop', width: 1280, height: 720 }
+];
+
+const findings = {
+  metadata: { url: URL, routes: ROUTES, timestamp: new Date().toISOString() },
+  console: [],
+  network: [],
+  a11y: [],
+  layout: [],
+  screenshots: [],
+  navigationFailures: []
+};
+
+for (const route of ROUTES) {
+  for (const viewport of VIEWPORTS) {
+    test(`${route} @ ${viewport.name}`, async ({ page }) => {
+      await page.setViewportSize({ width: viewport.width, height: viewport.height });
+
+      page.on('console', msg => {
+        if (msg.type() === 'error') {
+          findings.console.push({
+            route,
+            viewport: viewport.name,
+            text: msg.text(),
+            location: msg.location()
+          });
+        }
+      });
+
+      page.on('requestfailed', req => {
+        findings.network.push({
+          route,
+          viewport: viewport.name,
+          url: req.url(),
+          method: req.method(),
+          failure: req.failure()?.errorText,
+          severity: 'requestfailed'
+        });
+      });
+
+      page.on('response', res => {
+        if (res.status() >= 500) {
+          findings.network.push({
+            route,
+            viewport: viewport.name,
+            url: res.url(),
+            status: res.status(),
+            severity: '5xx'
+          });
+        } else if (res.status() >= 400 && res.status() !== 404) {
+          findings.network.push({
+            route,
+            viewport: viewport.name,
+            url: res.url(),
+            status: res.status(),
+            severity: '4xx'
+          });
+        }
+      });
+
+      const targetUrl = `${URL}${route}`;
+      let response;
+      try {
+        response = await page.goto(targetUrl, { waitUntil: 'networkidle', timeout: 30000 });
+      } catch (err) {
+        findings.navigationFailures.push({
+          route,
+          viewport: viewport.name,
+          error: err.message
+        });
+        return;
+      }
+
+      if (!response || !response.ok()) {
+        findings.navigationFailures.push({
+          route,
+          viewport: viewport.name,
+          status: response?.status() ?? 'no-response',
+          url: targetUrl
+        });
+        return;
+      }
+
+      // Detect horizontal scroll
+      const hasHScroll = await page.evaluate(() => {
+        return document.documentElement.scrollWidth > document.documentElement.clientWidth + 1;
+      });
+      if (hasHScroll) {
+        findings.layout.push({
+          route,
+          viewport: viewport.name,
+          issue: 'horizontal_scroll'
+        });
+      }
+
+      // axe-core a11y scan
+      try {
+        const axeResults = await new AxeBuilder({ page })
+          .withTags(['wcag2a', 'wcag2aa', 'wcag22aa', 'best-practice'])
+          .analyze();
+
+        for (const v of axeResults.violations) {
+          findings.a11y.push({
+            route,
+            viewport: viewport.name,
+            id: v.id,
+            impact: v.impact,
+            help: v.help,
+            helpUrl: v.helpUrl,
+            nodes: v.nodes.length,
+            sample: v.nodes.slice(0, 3).map(n => ({
+              target: n.target,
+              html: n.html.slice(0, 200)
+            }))
+          });
+        }
+      } catch (err) {
+        // axe-core failure doesn't block run
+        findings.a11y.push({
+          route,
+          viewport: viewport.name,
+          error: `axe-core failed: ${err.message}`
+        });
+      }
+
+      // Screenshot
+      const safeName = (route === '/' ? 'root' : route.replace(/^\//, '').replace(/\//g, '_'));
+      const screenshotPath = path.join(SCREENSHOT_DIR, `${safeName}_${viewport.name}.png`);
+      await page.screenshot({ path: screenshotPath, fullPage: true });
+      findings.screenshots.push({ route, viewport: viewport.name, path: screenshotPath });
+    });
+  }
+}
+
+test.afterAll(() => {
+  fs.writeFileSync(OUT, JSON.stringify(findings, null, 2));
+});
+```
+
+And inline config `.jdi/cache/playwright.config.js`:
+
+```javascript
+module.exports = {
+  testDir: '.jdi/cache',
+  testMatch: 'playwright-check.spec.js',
+  timeout: 60000,
+  retries: 0,
+  workers: 1,
+  reporter: [['line']],
+  use: {
+    headless: true,
+    ignoreHTTPSErrors: true
+  }
+};
+```
+
+### Step 6: Spawn dev server
+
+```bash
+# bash
+DEV_LOG=.jdi/cache/dev-server.log
+DEV_PID_FILE=.jdi/cache/dev-server.pid
+
+# Spawn in background, redirecting log
+nohup $DEV_COMMAND > $DEV_LOG 2>&1 &
+echo $! > $DEV_PID_FILE
+
+# Wait ready (poll URL, timeout 60s)
+READY=0
+for i in $(seq 1 60); do
+  if curl -sSf -o /dev/null --max-time 2 "$FRONTEND_URL"; then
+    READY=1
+    break
+  fi
+  sleep 1
+done
+
+if [ $READY -eq 0 ]; then
+  # Cleanup
+  kill $(cat $DEV_PID_FILE) 2>/dev/null
+  echo '{"status":"INCONCLUSIVE","reason":"dev server failed to start in 60s","logs":"'$DEV_LOG'"}' > .jdi/cache/ui-findings.json
+  exit 0  # doesn't fail the reviewer - INCONCLUSIVE is WARN
+fi
+```
+
+```powershell
+# PowerShell
+$DEV_LOG = ".jdi/cache/dev-server.log"
+$DEV_PID_FILE = ".jdi/cache/dev-server.pid"
+
+$proc = Start-Process -FilePath pwsh -ArgumentList "-NoProfile", "-Command", $DEV_COMMAND `
+  -RedirectStandardOutput $DEV_LOG -RedirectStandardError $DEV_LOG `
+  -PassThru -WindowStyle Hidden
+$proc.Id | Out-File -FilePath $DEV_PID_FILE
+
+$ready = $false
+for ($i = 0; $i -lt 60; $i++) {
+  try {
+    $r = Invoke-WebRequest -Uri $FRONTEND_URL -UseBasicParsing -TimeoutSec 2 -ErrorAction Stop
+    if ($r.StatusCode -eq 200) { $ready = $true; break }
+  } catch {}
+  Start-Sleep -Seconds 1
+}
+
+if (-not $ready) {
+  Stop-Process -Id $proc.Id -Force -ErrorAction SilentlyContinue
+  $err = @{ status="INCONCLUSIVE"; reason="dev server failed to start in 60s"; logs=$DEV_LOG } | ConvertTo-Json
+  $err | Out-File .jdi/cache/ui-findings.json
+  exit 0
+}
+```
+
+### Step 7: Run Playwright
+
+```bash
+# bash
+JDI_FRONTEND_URL="$FRONTEND_URL" \
+JDI_ROUTES="$(echo $CRITICAL_PATHS | tr '\n' ',')" \
+JDI_OUT=".jdi/cache/ui-findings.json" \
+JDI_SCREENSHOT_DIR=".jdi/cache/screenshots" \
+  $PW_BIN test --config=.jdi/cache/playwright.config.js 2>&1 | tee .jdi/cache/playwright.log
+
+# Playwright exit code doesn't matter - findings already written by afterAll
+```
+
+```powershell
+# PowerShell
+$env:JDI_FRONTEND_URL = $FRONTEND_URL
+$env:JDI_ROUTES = ($CRITICAL_PATHS -join ',')
+$env:JDI_OUT = ".jdi/cache/ui-findings.json"
+$env:JDI_SCREENSHOT_DIR = ".jdi/cache/screenshots"
+
+& npx playwright test --config=.jdi/cache/playwright.config.js 2>&1 | Tee-Object -FilePath .jdi/cache/playwright.log
+```
+
+### Step 8: Kill dev server (always, even on failure)
+
+```bash
+# bash
+if [ -f $DEV_PID_FILE ]; then
+  PID=$(cat $DEV_PID_FILE)
+  # Kill process + children (dev server usually has children: node, esbuild, vite, etc)
+  pkill -P $PID 2>/dev/null
+  kill $PID 2>/dev/null
+  # Safeguard on common ports (in case wrong PID)
+  # Vite: 5173, Next: 3000, etc - skip aggressive cleanup
+  rm $DEV_PID_FILE
+fi
+```
+
+```powershell
+# PowerShell
+if (Test-Path $DEV_PID_FILE) {
+  $pid = Get-Content $DEV_PID_FILE
+  # Kill children first
+  Get-CimInstance Win32_Process -Filter "ParentProcessId=$pid" -ErrorAction SilentlyContinue |
+    ForEach-Object { Stop-Process -Id $_.ProcessId -Force -ErrorAction SilentlyContinue }
+  # Kill the parent
+  Stop-Process -Id $pid -Force -ErrorAction SilentlyContinue
+  Remove-Item $DEV_PID_FILE
+}
+```
+
+### Step 9: Return to parent reviewer
+
+Skill doesn't write REVIEW.md. Only writes `.jdi/cache/ui-findings.json` + screenshots.
+
+Reviewer reads the JSON, classifies severities, and writes "UI Validation" section in REVIEW.md.
+
+## Finding classification (reference for the reviewer)
+
+| Finding | Severity |
+|---|---|
+| `console.error` on any route | BLOCK |
+| `network.5xx` on critical_path | BLOCK |
+| `network.4xx` on critical_path | WARN |
+| `network.requestfailed` (CORS/abort/etc) | WARN |
+| `navigationFailures` (404/timeout/etc on critical_path) | BLOCK |
+| `a11y.impact=critical` | BLOCK |
+| `a11y.impact=serious` | BLOCK |
+| `a11y.impact=moderate` | WARN |
+| `a11y.impact=minor` | INFO |
+| `layout.horizontal_scroll` on mobile | BLOCK |
+| `layout.horizontal_scroll` on desktop | INFO |
+| `axe-core failed` (technical error) | WARN |
+| `INCONCLUSIVE` (dev server timeout) | WARN |
+| `SKIPPED` (user declined install) | WARN |
+
+## Expected inputs
+
+From PROJECT.md (passed as environment variables by the reviewer):
+- `frontend.frontend_url` -> `FRONTEND_URL`
+- `frontend.dev_command` -> `DEV_COMMAND`
+- `frontend.critical_paths` -> `CRITICAL_PATHS` (list)
+
+## Outputs
+
+Files created in `.jdi/cache/` (gitignored):
+- `ui-findings.json` - structured findings
+- `screenshots/*.png` - 1 per route x viewport
+- `dev-server.log` - dev server log
+- `playwright.log` - Playwright run log
+- `playwright-check.spec.js` - generated spec
+- `playwright.config.js` - generated config
+
+NEVER commit `.jdi/cache/`.
+
+## Anti-patterns
+
+- Running against prod URL - dev local only. Prod is out of scope for this gate
+- Testing flows that require login - MVP doesn't support auth setup. Critical paths must be public OR pre-authenticated manually (cookie/session passed via PROJECT.md in follow-up)
+- Blocking review if Playwright install fails - degrade to SKIPPED
+- Leaving dev server alive after gate - always kill, even on error
+- Committing screenshots - .gitignore guaranteed in pre-flight
+- Running parallel (workers > 1) - local dev server doesn't scale, and race conditions confuse findings
+- Using `--headed` in CI - always headless
+- Trusting Playwright exit code - findings come from afterAll, even with test failure
+
+## References
+
+- `references/playwright-setup.md` - Detailed install per package manager + troubleshoot
+- `references/dev-server-detection.md` - Heuristics for detecting ready (curl, wait-on, polling)
+- `references/axe-rules.md` - Mapping of axe rule IDs -> WCAG -> severity
+- `references/auth-flows.md` - Roadmap for authenticated flows (future)
+
+## Examples
+
+### Example 1: Vite + React, Playwright missing, user accepts install
+
+```
+1. Reviewer triggers gate 7
+2. Skill detects `npx playwright --version` -> exit 1
+3. Lockfile = pnpm-lock.yaml -> PKG_MGR=pnpm
+4. AskUserQuestion -> user picks "Yes, Chromium"
+5. pnpm add -D @playwright/test @axe-core/playwright
+6. pnpm exec playwright install chromium
+7. Spawns `pnpm dev` in bg, PID 12345
+8. Waits http://localhost:5173 -> ready in 4s
+9. Runs Playwright on /, /login, /dashboard x mobile + desktop = 6 navigations
+10. Findings:
+    - 1 console error (uncaught promise) on /dashboard mobile + desktop
+    - 0 network errors
+    - 2 a11y serious on /login (missing label + contrast)
+    - 1 horizontal scroll on /dashboard mobile
+11. Kill PID 12345 + children
+12. Writes .jdi/cache/ui-findings.json
+13. Reviewer reads JSON, marks gate 7 = BLOCK (3 issues), writes REVIEW.md
+```
+
+### Example 2: API-only, has_frontend=false
+
+Skill is not even loaded. Reviewer skips gate 7 with SKIPPED.
+
+### Example 3: Dev server fails to start
+
+```
+1. Spawns `pnpm dev` -> process dies after 2s (port 5173 occupied)
+2. Poll of 60s expires without 200 OK
+3. Cleanup of PID
+4. Writes {"status":"INCONCLUSIVE","reason":"dev server failed to start in 60s"}
+5. Reviewer marks gate 7 = WARN with link to dev-server.log
+6. Review not blocked, but user alerted
+```
+
+### Example 4: User declines to install Playwright
+
+```
+1. AskUserQuestion -> "No, skip gate 7"
+2. Writes {"status":"SKIPPED","reason":"user declined Playwright install"}
+3. Reviewer marks gate 7 = SKIPPED (warn not block)
+4. REVIEW.md notes "UI Validation: SKIPPED - run /jdi-verify again when you accept installing"
+```