argusqa-os 9.6.5 → 9.7.3

package/README.md

@@ -4,7 +4,7 @@
 
 [![npm](https://img.shields.io/npm/v/argusqa-os?color=7C3AED)](https://www.npmjs.com/package/argusqa-os)
 [![MCP Server](https://glama.ai/mcp/servers/ironclawdevs27/Argus/badges/card.svg)](https://glama.ai/mcp/servers/ironclawdevs27/Argus)
-[![Harness](https://img.shields.io/badge/harness-641%2F644-4ADE80)](test-harness/)
+[![Harness](https://img.shields.io/badge/harness-679%2F679-4ADE80)](test-harness/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
 **Argus catches the bugs your test suite misses — visual regressions, API loops, CSS drift, console noise, accessibility failures, and more — and delivers rich reports to Slack (or a local HTML dashboard).**
@@ -62,7 +62,7 @@ Argus scans your app and either posts findings to Slack or opens a local `report
 
 ## What Argus Catches
 
-31 analysis engines, 138 distinct issue types, zero test-file maintenance:
+32 analysis engines, 140 distinct issue types, zero test-file maintenance:
 
 | Category | What it detects |
 |---|---|
@@ -71,7 +71,7 @@ Argus scans your app and either posts findings to Slack or opens a local `report
 | **Performance** | LCP > 2500ms, CLS > 0.1, TTFB > 800ms, slow APIs > 1s/3s, payloads > 500KB/2MB, JS bundles > 500KB |
 | **Accessibility** | axe-core (80+ WCAG rules), color-blind simulation, missing ARIA, keyboard focus, heading hierarchy |
 | **SEO** | Missing meta description, OG tags, canonical, viewport, h1 |
-| **Security** | Auth tokens in localStorage/URL, `eval()`, missing CSP/X-Frame-Options, CSP violations |
+| **Security** | Auth tokens in localStorage/URL, `eval()`, missing CSP/X-Frame-Options, CSP violations, missing SRI on external scripts, source map exposure, open redirects, npm CVEs |
 | **CSS** | Cascade overrides, component style leaks, unused rules, React inline style conflicts |
 | **Content** | `null`/`undefined` as visible text, lorem ipsum, broken images, empty data lists |
 | **Responsive** | Horizontal overflow at 375px/768px, touch targets < 44×44px |
@@ -84,6 +84,13 @@ Argus scans your app and either posts findings to Slack or opens a local `report
 | **Network baseline** | New requests, missing requests, status-code regressions vs saved HAR baseline |
 | **Environment diff** | Dev vs staging — screenshot diff, DOM changes, console/network regressions |
 
+And every finding is post-processed with:
+
+| Post-processor | What it adds |
+|---|---|
+| **Intelligent baseline filtering** | Findings that flip-flop across runs are tagged `noisy` and downgraded to info — pure cross-run heuristics, no API calls (`ARGUS_NOISE_FILTER=0` to disable) |
+| **Root cause linking** | New findings are annotated with the recent git commits and files most likely to have caused them (`ARGUS_ROOT_CAUSE=0` to disable) |
+
 > All findings are classified as `critical` / `warning` / `info` and routed to the right Slack channel — or surfaced in the local HTML report. For per-finding severity tables and detection methods, see [REFERENCE.md](REFERENCE.md).
 
 ---
@@ -201,14 +208,18 @@ export const routes = [
 ## CLI Commands
 
 ```bash
+npm run chrome         # Launch Chrome with --remote-debugging-port=9222 (auto-detects binary)
+npm run doctor         # Pre-flight check: Chrome reachable, .mcp.json valid, .env has TARGET_DEV_URL
 npm run crawl          # Batch audit of all configured routes
 npm run compare        # Dev vs staging diff (CSS-only if no staging URL)
 npm run watch          # Passive monitor — polls open Chrome tab every 1s
 npm run report:html    # Generate reports/report.html from last JSON audit
+npm run report:pdf     # Export HTML report to A4 PDF (requires: npm install puppeteer)
 npm run server         # Start Slack slash-command server (port 3001)
 npm run init           # Interactive setup wizard
-npm run test:unit      # 61 unit tests — no Chrome required
-npm run test:harness   # 138-block correctness harness — requires Chrome
+npm run test:unit          # 61 unit tests — no Chrome required
+npm run test:harness       # 139-block correctness harness — requires Chrome
+npm run test:harness:log   # same, but tees full output to harness-results.txt
 ```
 
 **Watch mode** — live monitoring as you develop:
@@ -331,12 +342,7 @@ Argus is a **complementary layer**, not a replacement for unit or E2E tests:
 
 ## Known Limitations
 
-3 permanent test failures (`641/644`) are MCP-layer restrictions — not fixable in Argus code:
-
-| Tool | Constraint |
-|---|---|
-| `drag` | Uses mouse simulation, not HTML5 DnD — `dragstart`/`dragover`/`drop` events never fire |
-| `list_console_messages({ types: ['issue'] })` | Issues panel returns empty even when violations exist |
+All 679 harness assertions pass (`679/679`) — there are currently no known MCP- or Chrome-layer restrictions. Soft assertions (Lighthouse, performance traces) still require non-headless Chrome and are skipped in headless CI.
 
 ---
 
@@ -347,11 +353,15 @@ src/
   argus.js              — single-page audit entry point
   mcp-server.js         — 9 MCP tools exposed to Claude / any MCP client
   orchestration/        — crawl loop, Slack/GitHub dispatch, env comparison, watch mode
-  utils/                — 30+ analysis engines (accessibility, security, performance, etc.)
+  utils/                — 32 analysis engines (accessibility, security, performance, PDF, recording, etc.)
   adapters/browser.js   — CdpBrowserAdapter — wraps all chrome-devtools-mcp calls
   config/targets.js     — routes, thresholds, auth steps
-  cli/init.js           — argus init interactive setup wizard
-test-harness/           — 138-block correctness harness, 62 fixture pages
+  cli/
+    init.js             — argus init interactive setup wizard
+    chrome-launcher.js  — npm run chrome / argus-chrome — launches Chrome with correct flags
+    doctor.js           — npm run doctor / argus-doctor — pre-flight checks
+    pr-validate.js      — headless CI entry point for GitHub Actions
+test-harness/           — 139-block correctness harness, 664 hard assertions, 62 fixture pages
 test/unit/              — 61 Vitest unit tests (no Chrome required)
 landing/                — Product landing page (React 19 + Vite + Tailwind)
 ```

package/glama.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://glama.ai/mcp/schemas/server.json",
   "name": "argus",
-  "description": "AI-powered QA harness that audits web apps via Chrome DevTools Protocol. Catches JS errors, network failures, a11y violations, SEO issues, security headers, CSS regressions, and more — directly from Claude conversations. 9 MCP tools: argus_audit (fast 8-analyzer pass), argus_audit_full (Lighthouse + memory + responsive), argus_compare (dev vs staging diff), argus_last_report (retrieve last JSON report), argus_watch_snapshot (live tab snapshot without navigating), argus_get_context (LLM-optimized context + fix loop with snapshot_id diff), argus_design_audit (Figma design fidelity — 13 finding types), argus_visual_diff (screenshot baseline comparison, updateBaseline flag), argus_pr_validate (PR diff → affected routes → targeted audit → blocked flag). 137 test blocks, 634 hard assertions, 63 detection categories.",
+  "description": "AI-powered QA harness that audits web apps via Chrome DevTools Protocol. Catches JS errors, network failures, a11y violations, SEO issues, security headers, CSS regressions, and more — directly from Claude conversations. 9 MCP tools: argus_audit (fast 8-analyzer pass), argus_audit_full (Lighthouse + memory + responsive), argus_compare (dev vs staging diff), argus_last_report (retrieve last JSON report), argus_watch_snapshot (live tab snapshot without navigating), argus_get_context (LLM-optimized context + fix loop with snapshot_id diff), argus_design_audit (Figma design fidelity — 13 finding types), argus_visual_diff (screenshot baseline comparison, updateBaseline flag), argus_pr_validate (PR diff → affected routes → targeted audit → blocked flag). Every finding is post-processed with intelligent baseline filtering (cross-run noise classifier) and root cause linking (recent git commits mapped to new findings). 141 test blocks, 679 hard assertions, 67 detection categories.",
   "maintainers": ["ironclawdevs27"],
   "tools": [
     {

package/package.json

@@ -1,71 +1,77 @@
-{
-  "name": "argusqa-os",
-  "version": "9.6.5",
-  "mcpName": "io.github.ironclawdevs27/argus",
-  "description": "Argus — AI-powered automated dev-testing platform using Chrome DevTools MCP and Claude Code",
-  "keywords": [
-    "mcp",
-    "mcp-server",
-    "claude",
-    "qa",
-    "testing",
-    "accessibility",
-    "automation",
-    "chrome-devtools",
-    "web-testing"
-  ],
-  "author": "ironclawdevs",
-  "license": "MIT",
-  "homepage": "https://argus-qa.com",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/ironclawdevs27/Argus.git"
-  },
-  "files": [
-    "src/",
-    ".mcp.json",
-    "glama.json"
-  ],
-  "type": "module",
-  "engines": {
-    "node": ">=20.19.0"
-  },
-  "bin": {
-    "argus": "src/cli/init.js",
-    "argus-mcp": "src/mcp-server.js",
-    "argusqa-os": "src/mcp-server.js",
-    "argus-pr-validate": "src/cli/pr-validate.js"
-  },
-  "scripts": {
-    "setup": "node -e \"import('fs').then(fs => fs.default.mkdirSync('./reports', { recursive: true }))\"",
-    "init": "node src/cli/init.js",
-    "crawl": "node src/orchestration/crawl-and-report.js",
-    "compare": "node src/orchestration/env-comparison.js",
-    "watch": "node src/orchestration/watch-mode.js",
-    "server": "node src/server/index.js",
-    "harness": "node test-harness/server.js",
-    "harness:staging": "PORT=3101 node test-harness/server.js",
-    "test:harness": "node test-harness/validate.js",
-    "test:unit": "vitest run test/unit",
-    "test": "npm run test:unit && npm run test:harness",
-    "report:html": "node src/utils/html-reporter.js",
-    "mcp-server": "node src/mcp-server.js"
-  },
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.29.0",
-    "@opentelemetry/api": "^1.9.1",
-    "@opentelemetry/sdk-node": "^0.218.0",
-    "@slack/web-api": "^7.16.0",
-    "axe-core": "^4.12.0",
-    "dotenv": "^17.4.2",
-    "express": "^5.2.1",
-    "pino": "^10.3.1",
-    "pino-pretty": "^13.1.3",
-    "pixelmatch": "^7.2.0",
-    "pngjs": "^7.0.0",
-    "zod": "^4.4.3"
-  },
-  "devDependencies": {
-    "vitest": "^4.1.8"
-  }
-}
+{
+  "name": "argusqa-os",
+  "version": "9.7.3",
+  "mcpName": "io.github.ironclawdevs27/argus",
+  "description": "Argus — AI-powered automated dev-testing platform using Chrome DevTools MCP and Claude Code",
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "claude",
+    "qa",
+    "testing",
+    "accessibility",
+    "automation",
+    "chrome-devtools",
+    "web-testing"
+  ],
+  "author": "ironclawdevs",
+  "license": "MIT",
+  "homepage": "https://argus-qa.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ironclawdevs27/Argus.git"
+  },
+  "files": [
+    "src/",
+    ".mcp.json",
+    "glama.json"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "bin": {
+    "argus": "src/cli/init.js",
+    "argus-mcp": "src/mcp-server.js",
+    "argusqa-os": "src/mcp-server.js",
+    "argus-pr-validate": "src/cli/pr-validate.js",
+    "argus-chrome": "src/cli/chrome-launcher.js",
+    "argus-doctor": "src/cli/doctor.js"
+  },
+  "scripts": {
+    "setup": "node -e \"import('fs').then(fs => fs.default.mkdirSync('./reports', { recursive: true }))\"",
+    "init": "node src/cli/init.js",
+    "chrome": "node src/cli/chrome-launcher.js",
+    "doctor": "node src/cli/doctor.js",
+    "crawl": "node src/orchestration/crawl-and-report.js",
+    "compare": "node src/orchestration/env-comparison.js",
+    "watch": "node src/orchestration/watch-mode.js",
+    "server": "node src/server/index.js",
+    "harness": "node test-harness/server.js",
+    "harness:staging": "PORT=3101 node test-harness/server.js",
+    "test:harness": "node --env-file=test-harness/.env.harness test-harness/validate.js",
+    "test:harness:log": "node test-harness/run-with-log.mjs",
+    "test:unit": "vitest run test/unit",
+    "test": "npm run test:unit && npm run test:harness",
+    "report:html": "node src/utils/html-reporter.js",
+    "report:pdf": "node src/utils/pdf-exporter.js",
+    "mcp-server": "node src/mcp-server.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@opentelemetry/api": "^1.9.1",
+    "@opentelemetry/sdk-node": "^0.218.0",
+    "@slack/web-api": "^7.16.0",
+    "axe-core": "^4.12.0",
+    "dotenv": "^17.4.2",
+    "express": "^5.2.1",
+    "pino": "^10.3.1",
+    "pino-pretty": "^13.1.3",
+    "pixelmatch": "^7.2.0",
+    "pngjs": "^7.0.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "vitest": "^4.1.8"
+  }
+}

package/src/adapters/browser.js

@@ -82,7 +82,8 @@ export class CdpBrowserAdapter {
   /**
    * Raw pass-through to list_console_messages with custom args.
    * Used by issues-analyzer.js for the DevTools Issues panel
-   * (types: ['issue']) which returns structured data, not text.
+   * (types: ['issue']). Like all MCP responses, the result is markdown
+   * text ("msgid=N [issue] text") — parse with parseConsoleMsgResponse.
    */
   listConsoleRaw(args = {}) { return this._mcp.list_console_messages(args); }
 }

package/src/cli/chrome-launcher.js

@@ -0,0 +1,175 @@
+#!/usr/bin/env node
+/**
+ * Argus Chrome Launcher — npm run chrome / argus-chrome
+ *
+ * Finds system Chrome / Chromium on Windows, macOS, and Linux,
+ * then launches it with the remote debugging port Argus needs.
+ *
+ * Exported for testing:
+ *   findChrome()       — returns path string or null
+ *   launchChrome(opts) — returns { chromePath, process }
+ *
+ * CLI flags:
+ *   --port=N       debugging port (default: 9222)
+ *   --headless     launch headless (default: visible)
+ *   --url=URL      initial URL (default: about:blank)
+ */
+
+import { execFileSync, spawn } from 'child_process';
+import fs   from 'fs';
+import os   from 'os';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+
+const CHROME_PATHS = {
+  win32: [
+    process.env.LOCALAPPDATA
+      ? path.join(process.env.LOCALAPPDATA, 'Google', 'Chrome', 'Application', 'chrome.exe')
+      : null,
+    'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe',
+    'C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe',
+    process.env.LOCALAPPDATA
+      ? path.join(process.env.LOCALAPPDATA, 'Chromium', 'Application', 'chrome.exe')
+      : null,
+  ].filter(Boolean),
+  darwin: [
+    '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+    '/Applications/Chromium.app/Contents/MacOS/Chromium',
+    '/Applications/Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary',
+  ],
+  linux: [
+    '/usr/bin/google-chrome',
+    '/usr/bin/google-chrome-stable',
+    '/usr/bin/chromium-browser',
+    '/usr/bin/chromium',
+    '/snap/bin/chromium',
+  ],
+};
+
+/**
+ * Find the first Chrome/Chromium binary available on this system.
+ * Returns the absolute path string or null if none found.
+ *
+ * Resolution order:
+ *   1. ARGUS_CHROME_PATH env var
+ *   2. Known platform-specific paths
+ *   3. `which` / `where` fallback
+ *
+ * @returns {string|null}
+ */
+export function findChrome() {
+  if (process.env.ARGUS_CHROME_PATH && fs.existsSync(process.env.ARGUS_CHROME_PATH)) {
+    return process.env.ARGUS_CHROME_PATH;
+  }
+
+  const platform   = process.platform;
+  const candidates = CHROME_PATHS[platform] ?? CHROME_PATHS.linux;
+  for (const p of candidates) {
+    if (p && fs.existsSync(p)) return p;
+  }
+
+  try {
+    const cmd   = platform === 'win32' ? 'where' : 'which';
+    const names = platform === 'win32'
+      ? ['chrome', 'chromium']
+      : ['google-chrome', 'google-chrome-stable', 'chromium-browser', 'chromium'];
+    for (const name of names) {
+      try {
+        const found = execFileSync(cmd, [name], {
+          encoding: 'utf8',
+          stdio: ['pipe', 'pipe', 'ignore'],
+        }).trim().split('\n')[0].trim();
+        if (found && fs.existsSync(found)) return found;
+      } catch { /* binary not in PATH */ }
+    }
+  } catch { /* which/where not available */ }
+
+  return null;
+}
+
+/**
+ * Launch Chrome with remote debugging enabled and return the spawned process.
+ *
+ * @param {{ port?: number, headless?: boolean, userDataDir?: string, url?: string }} [options]
+ * @returns {{ chromePath: string, process: import('child_process').ChildProcess }}
+ * @throws {Error} if Chrome binary cannot be found
+ */
+export function launchChrome(options = {}) {
+  const {
+    port        = 9222,
+    headless    = false,
+    userDataDir = path.join(os.tmpdir(), 'argus-chrome'),
+    url         = 'about:blank',
+  } = options;
+
+  const chromePath = findChrome();
+  if (!chromePath) {
+    throw new Error(
+      'Chrome not found. Install Google Chrome, then retry.\n' +
+      '  Download: https://www.google.com/chrome/\n' +
+      '  Or set ARGUS_CHROME_PATH=/path/to/chrome.'
+    );
+  }
+
+  const flags = [
+    `--remote-debugging-port=${port}`,
+    `--user-data-dir=${userDataDir}`,
+    '--no-first-run',
+    '--no-default-browser-check',
+    '--disable-background-networking',
+    '--disable-sync',
+    '--metrics-recording-only',
+    '--no-sandbox',
+    '--disable-gpu',
+  ];
+  if (headless) flags.push('--headless=new');
+  flags.push(url);
+
+  const child = spawn(chromePath, flags, { stdio: 'ignore', detached: true });
+  child.unref();
+  return { chromePath, process: child };
+}
+
+function parseCliArgs() {
+  const args = process.argv.slice(2);
+  const opts = { port: 9222, headless: false, url: 'about:blank' };
+  for (const arg of args) {
+    if (arg === '--headless' || arg === '--headless=new') { opts.headless = true; continue; }
+    const m = arg.match(/^--(\w[\w-]*)(?:=(.*))?$/);
+    if (!m) continue;
+    const [, key, val] = m;
+    if (key === 'port') { opts.port = parseInt(val, 10) || 9222; continue; }
+    if (key === 'url')  { opts.url  = val ?? opts.url;           continue; }
+  }
+  return opts;
+}
+
+if (process.argv[1] === __filename) {
+  const opts = parseCliArgs();
+  const ok   = s => process.stdout.write(`  ✓ ${s}\n`);
+  const fail = s => process.stderr.write(`  ✗ ${s}\n`);
+
+  process.stdout.write('\n');
+  process.stdout.write('  ╬ Argus Chrome Launcher\n\n');
+
+  const chromePath = findChrome();
+  if (!chromePath) {
+    fail('Chrome not found. Install Google Chrome or set ARGUS_CHROME_PATH.');
+    process.stdout.write('\n  Download: https://www.google.com/chrome/\n\n');
+    process.exit(1);
+  }
+
+  ok(`Found: ${chromePath}`);
+
+  try {
+    const { process: child } = launchChrome(opts);
+    ok(`Launched (PID ${child.pid}) — remote debugging on port ${opts.port}`);
+    process.stdout.write(`\n  CDP endpoint:  http://localhost:${opts.port}\n`);
+    process.stdout.write(`  Run \`npm run doctor\` to verify Argus can reach Chrome.\n\n`);
+  } catch (err) {
+    fail(err.message);
+    process.exit(1);
+  }
+}

package/src/cli/doctor.js

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+/**
+ * Argus Doctor — npm run doctor / argus-doctor
+ *
+ * Pre-flight check before running any Argus audit. Runs three checks:
+ *   1. Chrome CDP reachable at localhost:9222 (or ARGUS_CHROME_PORT)
+ *   2. .mcp.json exists, is valid JSON, has a chrome-devtools server entry
+ *   3. TARGET_DEV_URL is set (in .env or already in process.env)
+ *
+ * All three check functions are exported as pure async functions so the
+ * test harness can unit-test them without a real Chrome instance or disk setup.
+ */
+
+import fs   from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+
+/**
+ * Check whether Chrome's CDP endpoint is reachable on the given port.
+ *
+ * @param {number} [port=9222]
+ * @returns {Promise<{ ok: boolean, detail: string }>}
+ */
+export async function checkChrome(port = 9222) {
+  try {
+    const res = await fetch(`http://localhost:${port}/json/version`, {
+      signal: AbortSignal.timeout(3000),
+    });
+    if (!res.ok) return { ok: false, detail: `HTTP ${res.status}` };
+    const data = await res.json();
+    return { ok: true, detail: data.Browser ?? 'reachable' };
+  } catch (err) {
+    return { ok: false, detail: err.message ?? String(err) };
+  }
+}
+
+/**
+ * Check that .mcp.json exists, is valid JSON, and contains a chrome-devtools
+ * MCP server entry in mcpServers.
+ *
+ * @param {string} [filePath='.mcp.json']
+ * @returns {{ ok: boolean, detail: string }}
+ */
+export function checkMcpConfig(filePath = '.mcp.json') {
+  if (!fs.existsSync(filePath)) {
+    return {
+      ok:     false,
+      detail: `${path.basename(filePath)} not found — run \`argus init\` or copy .mcp.json from the Argus repo`,
+    };
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch (err) {
+    return { ok: false, detail: `Invalid JSON in ${path.basename(filePath)}: ${err.message}` };
+  }
+  const servers = parsed?.mcpServers ?? parsed?.servers ?? {};
+  const hasCdp  = Object.values(servers).some(s => {
+    const cmd  = String(s.command ?? '');
+    const args = Array.isArray(s.args) ? s.args.map(String) : [];
+    return cmd.includes('chrome-devtools') || args.some(a => a.includes('chrome-devtools'));
+  });
+  if (!hasCdp) {
+    return { ok: false, detail: 'No chrome-devtools MCP server entry found in mcpServers' };
+  }
+  return { ok: true, detail: `${Object.keys(servers).length} server(s) configured` };
+}
+
+/**
+ * Check that TARGET_DEV_URL is set — either already in process.env or present
+ * and non-empty in the .env file on disk.
+ *
+ * @param {string} [envFile='.env']
+ * @returns {{ ok: boolean, detail: string }}
+ */
+export function checkEnvKeys(envFile = '.env') {
+  if (process.env.TARGET_DEV_URL) {
+    return { ok: true, detail: `TARGET_DEV_URL=${process.env.TARGET_DEV_URL}` };
+  }
+  if (!fs.existsSync(envFile)) {
+    return {
+      ok:     false,
+      detail: `.env not found — run \`argus init\` to generate one`,
+    };
+  }
+  const content = fs.readFileSync(envFile, 'utf8');
+  const match   = content.match(/^TARGET_DEV_URL\s*=\s*(.+)$/m);
+  if (!match || !match[1].trim()) {
+    return {
+      ok:     false,
+      detail: 'TARGET_DEV_URL not set in .env — add TARGET_DEV_URL=http://localhost:3000',
+    };
+  }
+  return { ok: true, detail: `TARGET_DEV_URL=${match[1].trim()}` };
+}
+
+// ── CLI entry ─────────────────────────────────────────────────────────────────
+
+const PAD = 42;
+
+function row(label, result) {
+  const icon   = result.ok ? '✓' : '✗';
+  const status = result.ok ? 'OK  ' : 'FAIL';
+  process.stdout.write(`  ${icon} ${label.padEnd(PAD)} ${status}  ${result.detail}\n`);
+}
+
+if (process.argv[1] === __filename) {
+  const port = parseInt(process.env.ARGUS_CHROME_PORT ?? '9222', 10);
+
+  process.stdout.write('\n  ╬ Argus Doctor — pre-flight check\n\n');
+
+  const [chromeRes, mcpRes, envRes] = await Promise.all([
+    checkChrome(port),
+    Promise.resolve(checkMcpConfig()),
+    Promise.resolve(checkEnvKeys()),
+  ]);
+
+  row(`Chrome CDP reachable (port ${port})`, chromeRes);
+  row('.mcp.json valid + chrome-devtools entry', mcpRes);
+  row('TARGET_DEV_URL configured', envRes);
+
+  const allOk = chromeRes.ok && mcpRes.ok && envRes.ok;
+  process.stdout.write('\n');
+  if (allOk) {
+    process.stdout.write('  All checks passed — run `npm run crawl` to start auditing.\n\n');
+    process.exit(0);
+  } else {
+    process.stdout.write('  One or more checks failed — fix the issues above and retry.\n\n');
+    process.exit(1);
+  }
+}

package/src/cli/pr-validate.js

@@ -26,7 +26,7 @@ import path from 'path';
 import { fileURLToPath }                              from 'url';
 import { createMcpClient }                            from '../utils/mcp-client.js';
 import { crawlRouteCheap }                            from '../orchestration/crawl-and-report.js';
-import { parsePrUrl, fetchPrFiles, mapFilesToRoutes } from '../utils/pr-diff-analyzer.js';
+import { fetchPrFiles, mapFilesToRoutes } from '../utils/pr-diff-analyzer.js';
 
 // ── Exported helpers (testable without Chrome) ────────────────────────────────
 
@@ -125,7 +125,7 @@ export function writeStepSummary(markdown) {
 
 // ── Preflight reachability check ──────────────────────────────────────────────
 
-async function checkTargetReachable(url) {
+export async function checkTargetReachable(url) {
   try {
     // fetch throws only on network errors (ECONNREFUSED, ETIMEDOUT, DNS failure).
     // HTTP error status codes (4xx/5xx) still mean the server is up — Argus should
@@ -137,6 +137,21 @@ async function checkTargetReachable(url) {
   }
 }
 
+/**
+ * Normalize route paths — crawlRouteCheap builds URLs via string concatenation
+ * (baseUrl + route.path), so paths without a leading slash produce malformed URLs.
+ * @param {Array<{path: string, name?: string}>} routes
+ * @returns {Array<{path: string, name?: string}>}
+ */
+export function normalizeRoutePaths(routes) {
+  return routes.map(r => {
+    if (!r.path.startsWith('/')) {
+      return { ...r, path: `/${r.path}` };
+    }
+    return r;
+  });
+}
+
 // ── Route loader ──────────────────────────────────────────────────────────────
 
 async function loadRoutes() {
@@ -249,10 +264,9 @@ async function main() {
 
     // Normalize route paths — crawlRouteCheap builds URLs via string concat (baseUrl + route.path)
     // so paths without a leading slash produce malformed URLs like https://example.comlogin
-    const normalizedAffected = affected.map(r => {
-      if (!r.path.startsWith('/')) {
-        console.log(`::warning::Route path "${r.path}" has no leading slash — normalizing to "/${r.path}". Update argus.routes.json to use a leading slash.`);
-        return { ...r, path: `/${r.path}` };
+    const normalizedAffected = normalizeRoutePaths(affected).map((r, i) => {
+      if (r.path !== affected[i].path) {
+        console.log(`::warning::Route path "${affected[i].path}" has no leading slash — normalizing. Update argus.routes.json to use a leading slash.`);
       }
       return r;
     });
@@ -329,7 +343,10 @@ async function main() {
     console.log(JSON.stringify(result, null, 2));
 
     if (blocked) {
-      console.error(`::error::Argus PR Validator: ${summary.critical} critical finding(s) found. Merge blocked (block-on=${blockOn}).`);
+      const blockReason = blockOn === 'warning'
+        ? `${summary.critical} critical + ${summary.warning} warning finding(s) found`
+        : `${summary.critical} critical finding(s) found`;
+      console.error(`::error::Argus PR Validator: ${blockReason}. Merge blocked (block-on=${blockOn}).`);
       process.exit(1);
     }