argusqa-os 9.3.1 → 9.4.1

package/README.md

@@ -79,7 +79,7 @@ The `landing/` directory contains the product landing page (React + Vite + Tailw
 
 | 🔴 Critical / 🟡 Warning / 🔵 Info | ⚙️ | 🧪 | 📋 |
 | :---: | :---: | :---: | :---: |
-| **114 distinct issue types detected** | **24 analysis engines** | **360 test assertions** | **83 test blocks** |
+| **114 distinct issue types detected** | **24 analysis engines** | **367 test assertions** | **84 test blocks** |
 
 </div>
 
@@ -943,7 +943,7 @@ argus/
 │   └── README.md                     # Setup guide, Supabase SQL schema, env vars, deployment
 ├── scripts/
 │   └── dispatch-report.js            # Standalone Slack re-dispatch script (re-posts last report.json to Slack)
-├── test-harness/                     # Fixture server + test runner (83 blocks, 360 hard assertions, 54 fixture pages)
+├── test-harness/                     # Fixture server + test runner (84 blocks, 367 hard assertions, 54 fixture pages)
 │   ├── README.md
 │   ├── server.js                     # Express fixture server (ports 3100 dev / 3101 staging)
 │   ├── harness-config.js             # Route definitions + expected findings
@@ -988,7 +988,7 @@ argus/
 
 ## Known MCP Tool Limitations
 
-The Chrome DevTools MCP behavioral constraints below cause **3 permanent test failures** in the harness (`357/360` pass). These are MCP-layer restrictions — they cannot be fixed in Argus code.
+The Chrome DevTools MCP behavioral constraints below cause **3 permanent test failures** in the harness (`364/367` pass). These are MCP-layer restrictions — they cannot be fixed in Argus code. `validate.js` now exits with code 0 when only these 3 failures remain, making the CI harness gate reliable.
 
 > **`type_text` clarification**: `type_text` does fire DOM `input` events when the element is properly focused first with `mcp.click({ uid })`. Always use uid-based focus — passing `{ selector }` to `mcp.click` silently does nothing.
 

package/glama.json

@@ -1,4 +1,32 @@
 {
   "$schema": "https://glama.ai/mcp/schemas/server.json",
-  "maintainers": ["ironclawdevs27"]
+  "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. 6 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). 84 test blocks, 367 hard assertions, 54 detection categories.",
+  "maintainers": ["ironclawdevs27"],
+  "tools": [
+    {
+      "name": "argus_audit",
+      "description": "Fast QA audit — JS errors, network failures (4xx/5xx), API frequency loops, CSS cascade issues, SEO violations, security headers, accessibility, and content. Returns { findings, summary }. Supports cache: true to skip re-crawl on repeat calls."
+    },
+    {
+      "name": "argus_audit_full",
+      "description": "Deep QA audit — extends argus_audit with Lighthouse performance/accessibility scoring, responsive layout checks at 4 viewports, memory leak detection via heap snapshot, and accessibility tree analysis."
+    },
+    {
+      "name": "argus_compare",
+      "description": "Diffs dev vs staging environments side-by-side. Captures screenshots, runs all analyzers on each, and surfaces regressions — findings present in staging but not dev, or with changed severity."
+    },
+    {
+      "name": "argus_last_report",
+      "description": "Returns the most recent Argus JSON report from the reports/ directory without re-running a scan."
+    },
+    {
+      "name": "argus_watch_snapshot",
+      "description": "Snapshots the currently open Chrome tab without navigating — captures console errors, network failures, CORS blocks, and auth failures in one poll. Accepts optional tabId to inspect a specific tab."
+    },
+    {
+      "name": "argus_get_context",
+      "description": "LLM-optimized diagnostic context for the open Chrome tab. Returns snapshot_id for fix-loop diffing: pass it back on the next call to get resolved/new_issues/persisting arrays. Accepts optional tabId for multi-tab workflows."
+    }
+  ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "argusqa-os",
-  "version": "9.3.1",
+  "version": "9.4.1",
   "mcpName": "io.github.ironclawdevs27/argus",
   "description": "Argus — AI-powered automated dev-testing platform using Chrome DevTools MCP and Claude Code",
   "keywords": [

package/src/adapters/browser.js

@@ -56,6 +56,10 @@ export class CdpBrowserAdapter {
   stopTrace()              { return this._mcp.performance_stop_trace({}); }
   analyzeInsight(opts)     { return this._mcp.performance_analyze_insight(opts); }
 
+  // ── Tab management ─────────────────────────────────────────────────────────
+  listPages()              { return this._mcp.list_pages({}); }
+  selectPage(tabId)        { return this._mcp.select_page({ pageId: tabId }); }
+
   // ── Lifecycle ───────────────────────────────────────────────────────────────
   close()                  { return this._mcp.close(); }
 

package/src/mcp-server.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * Argus MCP Server (v9.3.1)
+ * Argus MCP Server (v9.4.1)
  *
  * Exposes Argus as an MCP server so Claude (or any MCP client) can call
  * argus_audit, argus_audit_full, argus_compare, argus_last_report, and
@@ -38,6 +38,10 @@ const REPORTS_DIR = path.resolve(process.cwd(), 'reports');
 const snapshotStore = new Map();
 const MAX_SNAPSHOTS = 20;
 
+// Audit cache: stores argus_audit results keyed by URL so cache:true skips re-crawl.
+const auditCache = new Map();
+const MAX_AUDIT_CACHE = 20;
+
 function storeSnapshot(id, findings) {
   snapshotStore.set(id, findings);
   if (snapshotStore.size > MAX_SNAPSHOTS) {
@@ -45,17 +49,25 @@ function storeSnapshot(id, findings) {
   }
 }
 
+function cacheAudit(url, result) {
+  auditCache.set(url, { result, ts: Date.now() });
+  if (auditCache.size > MAX_AUDIT_CACHE) {
+    auditCache.delete(auditCache.keys().next().value);
+  }
+}
+
 // ── Tool definitions ─────────────────────────────────────────────────────────
 
 const TOOLS = [
   {
     name: 'argus_audit',
-    description: 'Fast QA audit on a URL via Chrome DevTools Protocol. Runs 8 analyzers in one pass: JS errors, unhandled rejections, network failures (4xx/5xx), API frequency loops, CSS cascade issues, SEO violations, security header checks, and accessibility. Returns { findings: [{severity, type, message, url}], summary: {critical, warning, info} }. Use for CI smoke tests and pre-deploy gates. For Lighthouse scoring and memory leak detection, use argus_audit_full. Requires Chrome running with --remote-debugging-port=9222.',
+    description: 'Fast QA audit on a URL via Chrome DevTools Protocol. Runs 8 analyzers in one pass: JS errors, unhandled rejections, network failures (4xx/5xx), API frequency loops, CSS cascade issues, SEO violations, security header checks, and accessibility. Returns { findings: [{severity, type, message, url}], summary: {critical, warning, info} }. Use for CI smoke tests and pre-deploy gates. Pass cache: true to skip re-crawl on repeat calls to the same URL within a session — useful in tight fix loops. For Lighthouse scoring and memory leak detection, use argus_audit_full. Requires Chrome running with --remote-debugging-port=9222.',
     inputSchema: {
       type: 'object',
       properties: {
         url:      { type: 'string',  description: 'Full URL to audit, including protocol and path (e.g. http://localhost:3000/checkout). Must be reachable by the running Chrome instance.' },
         critical: { type: 'boolean', description: 'When true, console.error calls are escalated to critical severity. Set true for business-critical routes (login, checkout, dashboard) where any error is a blocker.', default: false },
+        cache:    { type: 'boolean', description: 'When true, returns the cached result for this URL if one exists (from a previous argus_audit call in this session) without re-crawling. Use in fix loops to cheaply re-read the last audit while iterating on a fix. Cache is per-session, max 20 entries, LRU eviction.', default: false },
       },
       required: ['url'],
     },
@@ -84,22 +96,24 @@ const TOOLS = [
   },
   {
     name: 'argus_watch_snapshot',
-    description: 'Snapshots the currently open Chrome tab without navigating — captures console errors, network failures (4xx/5xx), CORS blocks, and auth failures in one poll. Returns { findings: [{severity, type, message, url}], newConsole, newNetwork }. Use during active development to inspect what is happening on the current page without running a full audit. Requires Chrome on --remote-debugging-port=9222 with a page already open.',
+    description: 'Snapshots the currently open Chrome tab without navigating — captures console errors, network failures (4xx/5xx), CORS blocks, and auth failures in one poll. Returns { findings: [{severity, type, message, url}], newConsole, newNetwork }. Use during active development to inspect what is happening on the current page without running a full audit. Pass tabId to inspect a specific tab (get IDs from argus_get_context or list_pages). Without tabId, reads the active tab. Requires Chrome on --remote-debugging-port=9222 with a page already open.',
     inputSchema: {
       type: 'object',
       properties: {
-        url: { type: 'string', description: 'Optional base URL to attribute findings to (default: TARGET_DEV_URL env var). Does not navigate — reads the currently open Chrome tab.' },
+        url:   { type: 'string', description: 'Optional base URL to attribute findings to (default: TARGET_DEV_URL env var). Does not navigate — reads the currently open Chrome tab.' },
+        tabId: { type: 'string', description: 'Optional Chrome page/tab ID (e.g. from a prior argus_get_context response). When provided, switches focus to that tab before snapshotting — useful for SPAs that spawn new windows or multi-tab flows.' },
       },
     },
   },
   {
     name: 'argus_get_context',
-    description: 'Captures everything currently broken on the open Chrome tab and formats it as a diagnostic context for Claude to read and suggest fixes. Does NOT navigate — reads the live tab state after user interactions, in authenticated sessions, or mid-flow. Returns { snapshot_id, summary, url, timestamp, critical_issues, warnings, js_errors, network_failures, console_errors, recent_requests }. Fix loop: pass the snapshot_id from a previous call as snapshot_id to get a diff — the response will include resolved (cleared since last snapshot), new_issues (appeared since last snapshot), and persisting (unchanged). Workflow: call argus_get_context → Claude suggests fix → apply fix → call argus_get_context with snapshot_id → verify resolved array is non-empty. Requires Chrome on --remote-debugging-port=9222.',
+    description: 'Captures everything currently broken on the open Chrome tab and formats it as a diagnostic context for Claude to read and suggest fixes. Does NOT navigate — reads the live tab state after user interactions, in authenticated sessions, or mid-flow. Returns { snapshot_id, summary, url, timestamp, critical_issues, warnings, js_errors, network_failures, console_errors, recent_requests, open_tabs }. Fix loop: pass the snapshot_id from a previous call as snapshot_id to get a diff — the response will include resolved (cleared since last snapshot), new_issues (appeared since last snapshot), and persisting (unchanged). Multi-tab: pass tabId to inspect a specific tab, or omit to read the active tab. The open_tabs array always lists all currently open Chrome tabs. Workflow: call argus_get_context → Claude suggests fix → apply fix → call argus_get_context with snapshot_id → verify resolved array is non-empty. Requires Chrome on --remote-debugging-port=9222.',
     inputSchema: {
       type: 'object',
       properties: {
-        url: { type: 'string', description: 'Optional base URL to attribute findings to (default: TARGET_DEV_URL env var). Does not navigate — inspects the currently open Chrome tab.' },
+        url:         { type: 'string', description: 'Optional base URL to attribute findings to (default: TARGET_DEV_URL env var). Does not navigate — inspects the currently open Chrome tab.' },
         snapshot_id: { type: 'string', description: 'Optional snapshot_id from a previous argus_get_context call. When provided, the response includes resolved/new_issues/persisting arrays showing what changed since that snapshot.' },
+        tabId:       { type: 'string', description: 'Optional Chrome page/tab ID. When provided, switches focus to that specific tab before capturing context — useful for SPAs that spawn new windows (e.g. OAuth popups, checkout flows). Get tab IDs from the open_tabs array in a prior argus_get_context response.' },
       },
     },
   },
@@ -118,12 +132,29 @@ async function withMcp(fn) {
 
 // ── Tool handlers ─────────────────────────────────────────────────────────────
 
-async function handleAudit({ url, critical = false }) {
+async function handleAudit({ url, critical = false, cache = false }) {
+  if (cache && auditCache.has(url)) {
+    const { result, ts } = auditCache.get(url);
+    return { content: [{ type: 'text', text: JSON.stringify({ ...result, _cached: true, _cachedAt: new Date(ts).toISOString() }, null, 2) }] };
+  }
   return withMcp(async (mcp) => {
-    const parsed  = new URL(url);
-    const route   = { path: parsed.pathname + parsed.search + parsed.hash, name: 'audit', critical };
-    const findings = await crawlRouteCheap(route, parsed.origin, mcp);
-    return { content: [{ type: 'text', text: JSON.stringify(findings, null, 2) }] };
+    const parsed = new URL(url);
+    const route  = { path: parsed.pathname + parsed.search + parsed.hash, name: 'audit', critical };
+    const raw    = await crawlRouteCheap(route, parsed.origin, mcp);
+    const findings = Array.isArray(raw.errors) ? raw.errors : [];
+    const result = {
+      findings,
+      summary: {
+        critical: findings.filter(f => f.severity === 'critical').length,
+        warning:  findings.filter(f => f.severity === 'warning').length,
+        info:     findings.filter(f => f.severity === 'info').length,
+      },
+      url:        raw.url,
+      pageTitle:  raw.pageTitle,
+      screenshot: raw.screenshot,
+    };
+    if (cache) cacheAudit(url, result);
+    return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
   });
 }
 
@@ -146,9 +177,10 @@ async function handleCompare() {
   });
 }
 
-async function handleWatchSnapshot({ url } = {}) {
+async function handleWatchSnapshot({ url, tabId } = {}) {
   return withMcp(async (mcp) => {
     const browser = new CdpBrowserAdapter(mcp);
+    if (tabId) await browser.selectPage(tabId);
     const baseUrl = url ?? process.env.TARGET_DEV_URL ?? 'http://localhost:3000';
     const session = new WatchSession(browser, baseUrl);
     const result  = await session.poll();
@@ -156,13 +188,23 @@ async function handleWatchSnapshot({ url } = {}) {
   });
 }
 
-async function handleGetContext({ url, snapshot_id: prevId } = {}) {
+async function handleGetContext({ url, snapshot_id: prevId, tabId } = {}) {
   return withMcp(async (mcp) => {
     const browser = new CdpBrowserAdapter(mcp);
+    if (tabId) await browser.selectPage(tabId);
     const baseUrl = url ?? process.env.TARGET_DEV_URL ?? 'http://localhost:3000';
     const session = new WatchSession(browser, baseUrl);
     const { findings, newConsole, newNetwork } = await session.poll();
 
+    // List all open tabs so the caller can target a specific tab on the next call.
+    let open_tabs = [];
+    try {
+      const pages = await browser.listPages();
+      if (Array.isArray(pages)) {
+        open_tabs = pages.map(p => ({ id: p.id ?? p.pageId, url: p.url, title: p.title }));
+      }
+    } catch { /* list_pages not available in all Chrome configs — degrade gracefully */ }
+
     const newId = Date.now().toString(36) + Math.random().toString(36).slice(2, 6);
     storeSnapshot(newId, findings);
 
@@ -215,6 +257,7 @@ async function handleGetContext({ url, snapshot_id: prevId } = {}) {
       network_failures: findings.filter(f => f.type === 'network-error' || f.type === 'cors-error' || f.type === 'auth-error'),
       console_errors:   newConsole.filter(m => m.level === 'error' || m.level === 'warning'),
       recent_requests:  newNetwork.slice(-20),
+      open_tabs,
       ...(isDiff ? { resolved, new_issues, persisting } : {}),
     };
 
@@ -240,7 +283,7 @@ async function handleLastReport() {
 // ── Server bootstrap ──────────────────────────────────────────────────────────
 
 const server = new Server(
-  { name: 'argus', version: '9.3.1' },
+  { name: 'argus', version: '9.4.1' },
   { capabilities: { tools: {} } },
 );