argusqa-os 9.5.5 → 9.6.0

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. 7 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). 130 test blocks, 581 hard assertions, 58 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). 137 test blocks, 634 hard assertions, 63 detection categories.",
   "maintainers": ["ironclawdevs27"],
   "tools": [
     {
@@ -31,6 +31,14 @@
     {
       "name": "argus_design_audit",
       "description": "Full Figma design-to-implementation fidelity audit. Fetches design spec from a Figma frame URL (requires FIGMA_API_TOKEN) and compares every extracted property against live DOM computed styles. Detects 13 mismatch finding types: CSS token values, component presence, fill/text color (RGB distance), typography (fontSize/fontWeight/lineHeight/fontFamily/letterSpacing), Auto Layout padding and gap, border-radius (per-corner), bounding-box overflow, absolute position drift (scroll-corrected x/y vs Figma bounds), border stroke (color+weight), box-shadow (offset+blur+spread+color), opacity, and text content. Selector fallback: tries [data-testid], [aria-label], #id, .class per node."
+    },
+    {
+      "name": "argus_visual_diff",
+      "description": "Screenshot baseline comparison for a URL. First call saves a baseline PNG to reports/baselines/screenshots/. Subsequent calls diff the current screenshot against the baseline using pixelmatch and return visual_regression (warning ≥0.1% / critical ≥5% pixels changed) + visual_diff_summary (always). Pass updateBaseline: true to force-refresh the stored baseline after intentional UI changes."
+    },
+    {
+      "name": "argus_pr_validate",
+      "description": "Targeted QA audit driven by a GitHub pull request diff. Fetches the PR's changed files, maps them to affected routes in your target config using path-slug heuristics (infrastructure changes trigger a full audit), then audits only those routes. Returns { findings, affectedRoutes, changedFiles, perRoute, summary, blocked, blockOn }. Use in CI to gate merges — blocked:true when findings meet the blockOn threshold (none/warning/critical, default: critical). Requires Chrome on --remote-debugging-port=9222. GITHUB_TOKEN env var recommended for private repos."
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "argusqa-os",
-  "version": "9.5.5",
+  "version": "9.6.0",
   "mcpName": "io.github.ironclawdevs27/argus",
   "description": "Argus — AI-powered automated dev-testing platform using Chrome DevTools MCP and Claude Code",
   "keywords": [
@@ -55,7 +55,8 @@
     "@opentelemetry/api": "^1.9.1",
     "@opentelemetry/sdk-node": "^0.218.0",
     "@slack/web-api": "^7.16.0",
-    "dotenv": "^16.4.5",
+    "axe-core": "^4.12.0",
+    "dotenv": "^17.4.2",
     "express": "^5.2.1",
     "pino": "^10.3.1",
     "pino-pretty": "^13.1.3",
@@ -64,6 +65,6 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "vitest": "^4.1.7"
+    "vitest": "^4.1.8"
   }
 }

package/src/adapters/browser.js

@@ -48,6 +48,7 @@ export class CdpBrowserAdapter {
   emulate(viewport)              { return this._mcp.emulate({ viewport }); }
   emulateCpu(rate)               { return this._mcp.emulate({ cpuThrottlingRate: rate }); }
   emulateColorScheme(scheme)     { return this._mcp.emulate({ colorScheme: scheme }); }
+  emulateReducedMotion(pref)     { return this._mcp.emulate({ reducedMotion: pref }); }
   resize(w, h)                   { return this._mcp.resize_page({ width: w, height: h }); }
 
   // ── Network & performance ───────────────────────────────────────────────────

package/src/cli/init.js

@@ -287,11 +287,15 @@ async function main() {
                                              githubToken, githubRepo, sourceDir, envFile: envFilePath });
     const targetsContent = generateTargetsJs(finalRoutes, { framework, sourceDir, envFile: envFilePath });
 
-    if (fs.existsSync('.env')) {
-      logger.warn('  ⚠  .env already exists — skipping write to preserve existing credentials. Delete it manually to regenerate.');
-    } else {
-      fs.writeFileSync('.env', envContent, 'utf8');
+    try {
+      fs.writeFileSync('.env', envContent, { flag: 'wx', encoding: 'utf8' });
       tick('Wrote .env');
+    } catch (err) {
+      if (err.code === 'EEXIST') {
+        logger.warn('  ⚠  .env already exists — skipping write to preserve existing credentials. Delete it manually to regenerate.');
+      } else {
+        throw err;
+      }
     }
 
     const targetsPath = path.join('src', 'config', 'targets.js');

package/src/config/targets.js

@@ -68,6 +68,16 @@ export const thresholds = {
     warnPercent: parseFloat(process.env.VISUAL_WARN_PERCENT ?? '0.1'),  // % pixels changed → warning
     critPercent: parseFloat(process.env.VISUAL_CRIT_PERCENT ?? '5.0'),  // % pixels changed → critical
   },
+  a11y: {
+    contrastAA:       parseFloat(process.env.A11Y_CONTRAST_AA ?? '4.5'),  // WCAG AA normal text contrast ratio
+    maxAxeViolations: parseInt(process.env.A11Y_MAX_AXE ?? '50', 10),     // cap axe-core violations per run
+  },
+  motion: {
+    animationPropertyCount: parseInt(process.env.MOTION_ANIM_COUNT ?? '1', 10), // flag interactive animations at this count
+  },
+  font: {
+    slowLoadMs: parseInt(process.env.FONT_SLOW_MS ?? '1000', 10),  // ms threshold for slow font load warning
+  },
 };
 
 /**

package/src/mcp-server.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * Argus MCP Server (v9.5.5)
+ * Argus MCP Server (v9.6.0)
  *
  * 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
@@ -32,6 +32,8 @@ import { WatchSession }                       from './orchestration/watch-mode.j
 import { CdpBrowserAdapter }                  from './adapters/browser.js';
 import { getFigmaFrame }                      from './adapters/figma.js';
 import { analyzeDesignFidelity }             from './utils/design-fidelity-analyzer.js';
+import { analyzeVisualRegression }           from './utils/visual-diff-analyzer.js';
+import { parsePrUrl, fetchPrFiles, mapFilesToRoutes } from './utils/pr-diff-analyzer.js';
 
 const REPORTS_DIR = path.resolve(process.cwd(), 'reports');
 
@@ -119,6 +121,19 @@ const TOOLS = [
       },
     },
   },
+  {
+    name: 'argus_visual_diff',
+    description: 'Screenshot baseline comparison for a URL — captures a PNG screenshot and compares it pixel-by-pixel against a stored baseline using pixelmatch. First call: saves baseline, returns visual_baseline_created (info). Subsequent calls: returns visual_regression (warning ≥0.1% / critical ≥5% pixels changed) + visual_diff_summary (always). Baseline stored in reports/baselines/screenshots/. Use in CI or fix loops to detect unintended visual regressions without a full audit. Pass updateBaseline: true to force-refresh the stored baseline (e.g. after intentional UI changes). Requires Chrome on --remote-debugging-port=9222.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        url:           { type: 'string',  description: 'Full URL to capture and compare (e.g. http://localhost:3000/dashboard). Must be reachable by the running Chrome instance.' },
+        updateBaseline: { type: 'boolean', description: 'When true, deletes the existing baseline PNG and saves a fresh one from the current screenshot. Use after intentional UI changes to reset the reference.', default: false },
+        baselineDir:   { type: 'string',  description: 'Optional override for the baseline storage directory. Defaults to reports/baselines/screenshots/.' },
+      },
+      required: ['url'],
+    },
+  },
   {
     name: 'argus_design_audit',
     description: 'Full design-to-implementation fidelity audit against a Figma frame. 13 mismatch finding types: CSS token values, component presence, fill/text color (RGB delta), typography (fontSize/fontWeight/lineHeight/fontFamily/letterSpacing), Auto Layout padding and gap, border-radius (per-corner), bounding-box overflow, absolute position drift (scroll-corrected x/y, 20px threshold), border stroke (color+weight), box-shadow (offset+blur+spread+color), opacity, and text content. Selector fallback: tries [data-testid], [aria-label], #id, .class per node. Requires FIGMA_API_TOKEN env var and Chrome on --remote-debugging-port=9222. Returns { findings, summary } where summary includes 13 mismatch-type counts.',
@@ -131,6 +146,20 @@ const TOOLS = [
       required: ['url', 'figmaFrameUrl'],
     },
   },
+  {
+    name: 'argus_pr_validate',
+    description: 'Runs a targeted Argus audit on the routes affected by a GitHub pull request. Fetches the PR diff, maps changed files to routes in your target config using path-slug heuristics (infrastructure changes trigger a full audit; targeted otherwise), and audits only those routes — faster than a full scan and focused on what the PR actually touched. Returns { findings, affectedRoutes, changedFiles, perRoute, summary, blocked, blockOn }. Use in CI to gate merges: check blocked:true or pipe findings to an AI verdict step. Requires Chrome on --remote-debugging-port=9222. GITHUB_TOKEN env var recommended for private repos.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        prUrl:       { type: 'string',  description: 'Full GitHub PR URL (e.g. https://github.com/owner/repo/pull/42). Used to fetch the list of changed files via the GitHub REST API.' },
+        targetUrl:   { type: 'string',  description: 'Base URL to audit (e.g. https://staging.example.com). Overrides TARGET_DEV_URL env var.' },
+        githubToken: { type: 'string',  description: 'GitHub Personal Access Token or workflow GITHUB_TOKEN. Optional for public repos. Falls back to GITHUB_TOKEN env var.' },
+        blockOn:     { type: 'string',  enum: ['none', 'warning', 'critical'], description: '"critical" = block only when critical findings exist. "warning" = block on any warning or critical. "none" = never block. Defaults to ARGUS_BLOCK_ON env var, then "critical".', default: 'critical' },
+      },
+      required: ['prUrl'],
+    },
+  },
 ];
 
 // ── Helpers ───────────────────────────────────────────────────────────────────
@@ -282,6 +311,42 @@ async function handleGetContext({ url, snapshot_id: prevId, tabId } = {}) {
   });
 }
 
+async function handleVisualDiff({ url, updateBaseline = false, baselineDir }) {
+  if (!url) throw new Error('argus_visual_diff: url is required');
+
+  return withMcp(async (mcp) => {
+    const browser = new CdpBrowserAdapter(mcp);
+    const opts    = baselineDir ? { baselineDir } : {};
+
+    if (updateBaseline) {
+      // Delete existing baseline so analyzeVisualRegression treats it as first run
+      const path_   = await import('path');
+      const fs_     = await import('fs');
+      const { slugify } = await import('./utils/slug.js');
+      const { config }  = await import('./config/targets.js');
+      const dir  = baselineDir ?? path_.default.join(config.outputDir, 'baselines', 'screenshots');
+      const file = path_.default.join(dir, `${slugify(url)}.png`);
+      try { fs_.default.unlinkSync(file); } catch {}
+    }
+
+    const findings = await analyzeVisualRegression(browser, url, opts);
+    const regression = findings.find(f => f.type === 'visual_regression');
+    const baseline   = findings.find(f => f.type === 'visual_baseline_created');
+    const summary    = findings.find(f => f.type === 'visual_diff_summary');
+
+    return { content: [{ type: 'text', text: JSON.stringify({
+      findings,
+      summary: {
+        status:      regression ? 'regression' : baseline ? 'baseline_created' : 'no_change',
+        diffPercent: summary?.diffPercent ?? 0,
+        diffPixels:  summary?.diffPixels  ?? 0,
+        totalPixels: summary?.totalPixels ?? 0,
+        severity:    regression?.severity ?? 'info',
+      },
+    }, null, 2) }] };
+  });
+}
+
 async function handleDesignAudit({ url, figmaFrameUrl }) {
   if (!url)           throw new Error('argus_design_audit: url is required');
   if (!figmaFrameUrl) throw new Error('argus_design_audit: figmaFrameUrl is required');
@@ -318,6 +383,52 @@ async function handleDesignAudit({ url, figmaFrameUrl }) {
   });
 }
 
+async function handlePrValidate({ prUrl, targetUrl, githubToken, blockOn } = {}) {
+  if (!prUrl) throw new Error('argus_pr_validate: prUrl is required');
+
+  const { routes } = await import('./config/targets.js');
+  const token  = githubToken ?? process.env.GITHUB_TOKEN;
+  const base   = targetUrl  ?? process.env.TARGET_DEV_URL ?? 'http://localhost:3000';
+  const policy = blockOn    ?? process.env.ARGUS_BLOCK_ON ?? 'critical';
+
+  const changedFiles   = await fetchPrFiles(prUrl, token);
+  const affectedRoutes = mapFilesToRoutes(changedFiles, routes ?? []);
+
+  const allFindings = [];
+  const perRoute    = [];
+
+  for (const route of affectedRoutes) {
+    const url = new URL(route.path, base).href;
+    const res = await handleAudit({ url, critical: route.critical ?? false });
+    const data = JSON.parse(res.content[0].text);
+    allFindings.push(...(data.findings ?? []));
+    perRoute.push({ route: route.path, ...data.summary });
+  }
+
+  const summary = {
+    critical: allFindings.filter(f => f.severity === 'critical').length,
+    warning:  allFindings.filter(f => f.severity === 'warning').length,
+    info:     allFindings.filter(f => f.severity === 'info').length,
+  };
+
+  const blocked =
+    policy === 'critical' ? summary.critical > 0 :
+    policy === 'warning'  ? summary.critical + summary.warning > 0 :
+    false;
+
+  return { content: [{ type: 'text', text: JSON.stringify({
+    prUrl,
+    targetUrl: base,
+    affectedRoutes: affectedRoutes.map(r => r.path),
+    changedFiles,
+    findings: allFindings,
+    perRoute,
+    summary,
+    blocked,
+    blockOn: policy,
+  }, null, 2) }] };
+}
+
 async function handleLastReport() {
   if (!fs.existsSync(REPORTS_DIR)) {
     return { content: [{ type: 'text', text: '{"error":"No reports found in reports/"}' }] };
@@ -336,7 +447,7 @@ async function handleLastReport() {
 // ── Server bootstrap ──────────────────────────────────────────────────────────
 
 const server = new Server(
-  { name: 'argus', version: '9.5.5' },
+  { name: 'argus', version: '9.6.0' },
   { capabilities: { tools: {} } },
 );
 
@@ -351,7 +462,9 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
       case 'argus_last_report':     return await handleLastReport();
       case 'argus_watch_snapshot':  return await handleWatchSnapshot(req.params.arguments ?? {});
       case 'argus_get_context':     return await handleGetContext(req.params.arguments ?? {});
+      case 'argus_visual_diff':     return await handleVisualDiff(req.params.arguments ?? {});
       case 'argus_design_audit':    return await handleDesignAudit(req.params.arguments ?? {});
+      case 'argus_pr_validate':     return await handlePrValidate(req.params.arguments ?? {});
       default: throw new Error(`Unknown tool: ${req.params.name}`);
     }
   } catch (err) {

package/src/orchestration/dispatcher.js

@@ -26,7 +26,7 @@ function openInBrowser(filePath) {
   try {
     const abs = path.resolve(filePath);
     if (process.platform === 'win32') {
-      execFile('cmd', ['/c', 'start', '', abs], () => {});
+      execFile('cmd', ['/c', 'start', '', abs], () => {}); // lgtm[js/shell-command-injection-from-environment] — execFile with args array is injection-safe; abs is path.resolve() of an internally-computed report path
     } else if (process.platform === 'darwin') {
       execFile('open', [abs], () => {});
     } else {

package/src/orchestration/env-comparison.js

@@ -21,7 +21,6 @@ import { unwrapEval } from '../utils/mcp-client.js';
 import { childLogger } from '../utils/logger.js';
 
 const logger = childLogger('env-comparison');
-import { normalizeArray } from '../utils/flow-runner.js';
 import { CdpBrowserAdapter } from '../adapters/browser.js';
 
 import { comparisonRoutes, config } from '../config/targets.js';

package/src/orchestration/orchestrator.js

@@ -45,6 +45,11 @@ import '../utils/theme-analyzer.js';
 import '../utils/design-fidelity-analyzer.js';
 import '../utils/web-vitals-analyzer.js';
 import '../utils/visual-diff-analyzer.js';
+import '../utils/a11y-deep-analyzer.js';
+import '../utils/har-recorder.js';
+import '../utils/motion-analyzer.js';
+import '../utils/font-analyzer.js';
+import '../utils/form-analyzer.js';
 
 import { getExpensive }          from '../registry.js';
 import { deduplicateFindings as deduplicateErrors } from './report-processor.js';
@@ -485,7 +490,7 @@ export async function crawlRouteCheap(route, baseUrl, mcp) {
     const text = (msg.text ?? msg.message ?? '');
     if (text.toLowerCase().includes('has been blocked by cors policy')) continue;
     const severity = classifyConsoleMessage(msg, route.critical);
-    if (severity !== null && msg.level !== 'log') {
+    if (msg.level !== 'log') {
       result.errors.push({
         type: 'console',
         level: msg.level,
@@ -1021,10 +1026,10 @@ export async function runCrawl(mcp, routeOverrides = null, baseUrlOverride = nul
   // Auth session persistence (B2)
   const sessionFile = auth?.sessionFile ?? '.argus-session.json';
   if (auth?.steps?.length > 0) {
-    if (!hasSession(sessionFile, auth.sessionMaxAgeMs)) {
-      logger.info(`[ARGUS] Auth: running login flow (${auth.steps.length} steps)...`);
+    if (!hasSession(sessionFile, auth?.sessionMaxAgeMs)) {
+      logger.info(`[ARGUS] Auth: running login flow (${auth?.steps?.length ?? 0} steps)...`);
       try {
-        await runLoginFlow(browser, targetBaseUrl, auth.steps);
+        await runLoginFlow(browser, targetBaseUrl, auth?.steps ?? []);
         await saveSession(browser, sessionFile);
       } catch (err) {
         logger.warn(`[ARGUS] Auth: login flow failed — crawl will proceed unauthenticated: ${err.message}`);
@@ -1149,5 +1154,5 @@ export async function runCrawl(mcp, routeOverrides = null, baseUrlOverride = nul
 if (process.argv[1] && fileURLToPath(import.meta.url) === path.resolve(process.argv[1])) {
   logger.info('[ARGUS] orchestrator.js loaded. Invoke runCrawl(mcp) from Claude Code with MCP tools connected.');
   logger.info('[ARGUS] Target base URL: ' + BASE_URL);
-  logger.info('[ARGUS] Routes to crawl: ' + (routes ?? []).map(r => r?.path ?? '(no path)').join(', '));
+  logger.info('[ARGUS] Routes to crawl: ' + routes.map(r => r?.path ?? '(no path)').join(', '));
 }

package/src/orchestration/report-processor.js

@@ -108,7 +108,7 @@ export async function processReport(report, { outputDir, severityOverrides }) {
   const timestamp  = new Date().toISOString().replace(/[:.]/g, '-');
   const reportPath = path.join(outputDir, `error-report-${timestamp}.json`);
   try {
-    fs.writeFileSync(reportPath, JSON.stringify(report, null, 2));
+    fs.writeFileSync(reportPath, JSON.stringify(report, null, 2)); // lgtm[js/network-data-to-file] — intentional: Argus persists crawl findings to a local JSON report file by design
   } catch (err) {
     logger.error(`[ARGUS] Failed to write report JSON: ${err.message}`);
     throw err;

package/src/orchestration/slack-notifier.js

@@ -99,7 +99,7 @@ async function uploadFileToSlack(filePath, channelId, filename) {
     const response = await fetch(uploadUrl, {
       method: 'PUT',
       headers: { 'Content-Type': 'application/octet-stream' },
-      body: fileBuffer,
+      body: fileBuffer, // lgtm[js/file-access-to-http] — intentional screenshot upload to Slack pre-signed URL; file path is internally generated by Argus, not from HTTP request input
       signal: AbortSignal.timeout(30000),
     });
     if (!response.ok) {

package/src/orchestration/watch-mode.js

@@ -35,10 +35,6 @@ import {
 import { postBugReport }      from './slack-notifier.js';
 import { isSlackConfigured }  from '../utils/slack-guard.js';
 import { generateHtmlReport } from '../utils/html-reporter.js';
-import {
-  parseConsoleMsgResponse,
-  parseNetworkReqResponse,
-} from '../utils/mcp-parsers.js';
 
 const __dirname   = path.dirname(fileURLToPath(import.meta.url));
 const REPORTS_DIR = path.resolve(__dirname, '../../reports');

package/src/server/index.js

@@ -50,6 +50,28 @@ app.use((req, res, next) => {
   next();
 });
 
+// ── Rate limiting (per-IP, in-memory) ──────────────────────────────────────────
+// 30 requests per minute per IP — prevents Slack endpoint flooding.
+// Slack signature verification rejects invalid payloads, but rate limiting adds
+// a defence-in-depth layer before signature verification even runs.
+const RATE_WINDOW_MS = 60_000;
+const RATE_MAX       = 30;
+const rateLimitMap   = new Map();
+
+function slackRateLimit(req, res, next) {
+  const key   = req.ip ?? 'unknown';
+  const now   = Date.now();
+  const entry = rateLimitMap.get(key) ?? { count: 0, start: now };
+  if (now - entry.start > RATE_WINDOW_MS) { entry.count = 0; entry.start = now; }
+  entry.count++;
+  rateLimitMap.set(key, entry);
+  if (entry.count > RATE_MAX) {
+    res.setHeader('Retry-After', Math.ceil(RATE_WINDOW_MS / 1000));
+    return res.status(429).json({ error: 'Too Many Requests' });
+  }
+  next();
+}
+
 // ── Routes ─────────────────────────────────────────────────────────────────────
 
 app.get('/health', (req, res) => {
@@ -57,10 +79,10 @@ app.get('/health', (req, res) => {
 });
 
 // Slack slash commands
-app.post('/slack/commands', handleSlashCommand);
+app.post('/slack/commands', slackRateLimit, handleSlashCommand);
 
 // Slack Block Kit interactions (button clicks)
-app.post('/slack/interactions', handleInteraction);
+app.post('/slack/interactions', slackRateLimit, handleInteraction);
 
 // ── Start ──────────────────────────────────────────────────────────────────────
 

package/src/server/slash-command-handler.js

@@ -15,7 +15,6 @@
  */
 
 import crypto from 'crypto';
-import { postBugReport } from '../orchestration/slack-notifier.js';
 import { createMcpClient } from '../utils/mcp-client.js';
 import { runCrawl } from '../orchestration/crawl-and-report.js';
 import { WebClient } from '@slack/web-api';