argusqa-os 9.5.1 → 9.5.5

package/src/utils/mcp-client.js

@@ -17,15 +17,8 @@ import { childLogger } from './logger.js';
 
 const logger = childLogger('mcp-client');
 
-// Validate MCP_BROWSER_URL before embedding it in a shell:true spawn argument.
-// Two-step defense:
-//   1. new URL() rejects malformed/non-http(s) values.
-//   2. Shell-metacharacter check rejects valid URLs whose query strings contain
-//      &, |, ;, backtick, $() etc. — new URL().toString() preserves & in query
-//      strings (valid URL syntax), but & is a shell background-operator that
-//      would split the spawn command on both bash and cmd.exe.
-//      A legitimate Chrome remote-debug URL is always http(s)://host:port with
-//      no path or query string, so this check never fires in practice.
+// Validate MCP_BROWSER_URL — new URL() rejects malformed/non-http(s) values.
+// A legitimate Chrome remote-debug URL is always http(s)://host:port.
 const _rawBrowserUrl = process.env.MCP_BROWSER_URL ?? 'http://127.0.0.1:9222';
 let BROWSER_URL;
 try {
@@ -37,14 +30,6 @@ try {
 } catch (e) {
   throw new Error(`[ARGUS] Invalid MCP_BROWSER_URL "${_rawBrowserUrl}": ${e.message}`);
 }
-// Shell-metacharacter guard — must run AFTER URL re-serialization.
-const _SHELL_META = /[&|;<>`${}()\n\r!"]/;
-if (_SHELL_META.test(BROWSER_URL)) {
-  throw new Error(
-    `[ARGUS] MCP_BROWSER_URL contains shell-unsafe characters — ` +
-    `use a plain http(s)://host:port URL (got: "${BROWSER_URL}")`
-  );
-}
 
 /**
  * Unwrap an evaluate_script result to its plain value.

package/src/utils/retry.js

@@ -29,7 +29,7 @@ export async function withRetry(fn, { attempts, delayMs = 400, label = '' } = {}
     } catch (err) {
       if (i === maxAttempts - 1) throw err;
       const wait = delayMs * Math.pow(2, i);
-      logger.debug(`[ARGUS] ${label ? label + ': ' : ''}retry ${i + 1}/${maxAttempts - 1} after ${wait}ms — ${err.message}`);
+      logger.debug(`[ARGUS] ${label ? label + ': ' : ''}retry ${i + 1}/${maxAttempts - 1} after ${wait}ms — ${err.constructor?.name ?? 'Error'}: ${err.message}`);
       await new Promise(r => setTimeout(r, wait));
     }
   }

package/src/utils/session-persistence.js

@@ -104,11 +104,19 @@ export async function saveSession(browser, sessionFile) {
   };
 
   const dir = path.dirname(sessionFile);
-  if (dir) fs.mkdirSync(dir, { recursive: true });
+  try {
+    if (dir) fs.mkdirSync(dir, { recursive: true });
+  } catch (err) {
+    throw new Error(`[ARGUS] saveSession: failed to create directory "${dir}": ${err.message}`);
+  }
 
   const tmpFile = `${sessionFile}.tmp`;
-  fs.writeFileSync(tmpFile, JSON.stringify(state, null, 2), 'utf8');
-  fs.renameSync(tmpFile, sessionFile);
+  try {
+    fs.writeFileSync(tmpFile, JSON.stringify(state, null, 2), 'utf8');
+    fs.renameSync(tmpFile, sessionFile);
+  } catch (err) {
+    throw new Error(`[ARGUS] saveSession: failed to write session file "${sessionFile}": ${err.message}`);
+  }
 
   const lsCount   = Object.keys(state.localStorage).length;
   const ssCount   = Object.keys(state.sessionStorage).length;
@@ -162,7 +170,11 @@ export async function restoreSession(browser, baseUrl, sessionFile) {
     } catch { /* URL parse failure — proceed and let Chrome handle it */ }
   }
 
-  await browser.navigate(baseUrl);
+  const NAV_TIMEOUT_MS = 10000;
+  await Promise.race([
+    browser.navigate(baseUrl),
+    new Promise((_, reject) => setTimeout(() => reject(new Error(`restoreSession: navigate to "${baseUrl}" timed out after ${NAV_TIMEOUT_MS}ms`)), NAV_TIMEOUT_MS)),
+  ]);
   await new Promise(r => setTimeout(r, 400));
 
   const restoreScript = buildRestoreScript(state);

package/src/utils/theme-analyzer.js

@@ -0,0 +1,173 @@
+/**
+ * ARGUS Theme Analyzer (Sprint 1 — A7: Theme & Dark Mode)
+ *
+ * Detects dark mode support gaps and theme consistency issues by:
+ *   1. Scanning all stylesheets for @media (prefers-color-scheme: dark) rules
+ *   2. Collecting :root CSS custom properties in light mode
+ *   3. Emulating dark mode via CDP, re-collecting custom properties
+ *   4. Flagging properties whose value does not change between modes
+ *
+ * Detections:
+ *   theme_no_dark_mode  — info    — no @media (prefers-color-scheme: dark) rule anywhere
+ *   theme_static_var    — warning — CSS custom property identical in light + dark mode
+ *   theme_summary       — info    — summary: dark mode supported/not, var count, screenshot taken
+ */
+
+import { registerExpensive } from '../registry.js';
+import { unwrapEval }        from './mcp-client.js';
+import { childLogger }       from './logger.js';
+
+const logger = childLogger('theme-analyzer');
+
+// ── Page script ────────────────────────────────────────────────────────────────
+// Injected via evaluate_script. Scans stylesheets and :root custom properties.
+// Returns JSON: { hasDarkModeQuery, rootVars }
+const THEME_SCAN_SCRIPT = `() => {
+  var result = { hasDarkModeQuery: false, rootVars: {} };
+
+  // Scan all stylesheets for @media (prefers-color-scheme: dark) rules
+  var sheets = Array.from(document.styleSheets);
+  for (var s = 0; s < sheets.length; s++) {
+    try {
+      var rules = Array.from(sheets[s].cssRules || []);
+      for (var r = 0; r < rules.length; r++) {
+        var rule = rules[r];
+        if (rule.type === 4 /* MEDIA_RULE */) {
+          var cond = rule.conditionText || (rule.media && rule.media.mediaText) || '';
+          if (cond.indexOf('prefers-color-scheme') !== -1 && cond.indexOf('dark') !== -1) {
+            result.hasDarkModeQuery = true;
+          }
+        }
+      }
+    } catch (e) { /* cross-origin stylesheet — skip */ }
+  }
+
+  // Collect all CSS custom properties declared on :root
+  var rootStyle = getComputedStyle(document.documentElement);
+  for (var i = 0; i < rootStyle.length; i++) {
+    var prop = rootStyle.item(i);
+    if (prop.charAt(0) === '-' && prop.charAt(1) === '-') {
+      result.rootVars[prop] = rootStyle.getPropertyValue(prop).trim();
+    }
+  }
+
+  return JSON.stringify(result);
+}`;
+
+// Names suggesting a color/theme token — only these are flagged as static vars
+const COLOR_VAR_RE = /color|bg|background|text|foreground|surface|fill|stroke|border|shadow|ring|accent|primary|secondary|muted|card|popover|input|destructive/i;
+
+// ── JSON parse helper ──────────────────────────────────────────────────────────
+function parseJson(raw) {
+  try {
+    const str = unwrapEval(raw);
+    if (typeof str === 'object' && str !== null) return str;
+    return JSON.parse(str);
+  } catch {
+    return null;
+  }
+}
+
+// ── Public API ─────────────────────────────────────────────────────────────────
+
+/**
+ * Analyse theme and dark mode support for a single page.
+ *
+ * @param {object} browser - CdpBrowserAdapter
+ * @param {string} url     - Fully-qualified URL to analyse
+ * @returns {Promise<object[]>} Array of theme finding objects
+ */
+export async function analyzeTheme(browser, url) {
+  const findings = [];
+
+  // Navigate and settle
+  try {
+    await browser.navigate(url);
+    await browser.waitFor({ state: 'networkidle' }).catch(() => {});
+    await new Promise(r => setTimeout(r, 400));
+  } catch {
+    return findings;
+  }
+
+  // ── Light mode scan ──────────────────────────────────────────────────────────
+  let lightData;
+  try {
+    const raw = await browser.evaluate(THEME_SCAN_SCRIPT);
+    lightData = parseJson(raw);
+  } catch (err) {
+    logger.warn(`[ARGUS] theme-analyzer: light scan failed for ${url}: ${err.message}`);
+    return findings;
+  }
+  if (!lightData) return findings;
+
+  const lightVars  = lightData.rootVars ?? {};
+  const varCount   = Object.keys(lightVars).length;
+
+  // ── Detection 1: no dark mode media query ────────────────────────────────────
+  if (!lightData.hasDarkModeQuery) {
+    findings.push({
+      type:    'theme_no_dark_mode',
+      message: 'No @media (prefers-color-scheme: dark) rule detected — page has no dark mode support',
+      severity: 'info',
+      url,
+    });
+  }
+
+  // ── Dark mode emulation + comparison ────────────────────────────────────────
+  let darkData = null;
+  try {
+    await browser.emulateColorScheme('dark');
+    await new Promise(r => setTimeout(r, 300));
+    const raw = await browser.evaluate(THEME_SCAN_SCRIPT);
+    darkData = parseJson(raw);
+  } catch (err) {
+    logger.debug(`[ARGUS] theme-analyzer: dark mode emulation skipped for ${url}: ${err.message}`);
+  } finally {
+    try { await browser.emulateColorScheme('light'); } catch { /* restore best-effort */ }
+  }
+
+  // ── Detection 2: CSS custom properties that don't adapt to dark mode ─────────
+  if (darkData && lightData.hasDarkModeQuery) {
+    const darkVars    = darkData.rootVars ?? {};
+    const staticVars  = [];
+
+    for (const [name, lightVal] of Object.entries(lightVars)) {
+      const darkVal = darkVars[name];
+      if (darkVal !== undefined && darkVal === lightVal && COLOR_VAR_RE.test(name)) {
+        staticVars.push(name);
+      }
+    }
+
+    if (staticVars.length > 0) {
+      const preview = staticVars.slice(0, 3).join(', ');
+      const extra   = staticVars.length > 3 ? ` (+${staticVars.length - 3} more)` : '';
+      findings.push({
+        type:     'theme_static_var',
+        vars:     staticVars.slice(0, 10),
+        count:    staticVars.length,
+        message:  `${staticVars.length} color custom propert${staticVars.length === 1 ? 'y does' : 'ies do'} not change between light and dark mode: ${preview}${extra}`,
+        severity: 'warning',
+        url,
+      });
+    }
+  }
+
+  // ── Summary finding ──────────────────────────────────────────────────────────
+  findings.push({
+    type:        'theme_summary',
+    hasDarkMode: lightData.hasDarkModeQuery,
+    rootVarCount: varCount,
+    darkEmulated: darkData !== null,
+    message:     `Theme: ${lightData.hasDarkModeQuery ? 'dark mode supported' : 'no dark mode'}, ${varCount} CSS custom propert${varCount === 1 ? 'y' : 'ies'} on :root`,
+    severity:    'info',
+    url,
+  });
+
+  return findings;
+}
+
+// ── Self-registration ─────────────────────────────────────────────────────────
+registerExpensive({
+  name: 'theme',
+  analyze: (browser, url) => analyzeTheme(browser, url),
+});

package/src/utils/visual-diff-analyzer.js

@@ -0,0 +1,207 @@
+/**
+ * ARGUS Visual Regression Analyzer (Sprint 3 — A8)
+ *
+ * Per-route visual regression detection via screenshot baseline comparison.
+ * Takes a PNG screenshot, compares it pixel-by-pixel against a stored baseline,
+ * and emits a finding when the diff exceeds the configured threshold.
+ *
+ * Works in headless Chrome — uses the Performance API screenshot path, not Lighthouse.
+ *
+ * Findings emitted:
+ *   visual_baseline_created — info, first run for a URL (baseline saved, no prior exists)
+ *   visual_regression       — warning ≥0.1%, critical ≥5% pixels changed
+ *   visual_diff_summary     — info, always emitted with full diff metrics
+ *
+ * Baseline storage: {config.outputDir}/baselines/screenshots/{slug}.png
+ * Override via opts.baselineDir for testing.
+ */
+
+import fs   from 'fs';
+import path from 'path';
+import os   from 'os';
+import { PNG }        from 'pngjs';
+import pixelmatch     from 'pixelmatch';
+import { registerExpensive } from '../registry.js';
+import { childLogger }       from './logger.js';
+import { slugify }           from './slug.js';
+import { config, thresholds } from '../config/targets.js';
+
+const logger = childLogger('visual-diff');
+
+// ── Thresholds ─────────────────────────────────────────────────────────────────
+const WARN_PERCENT = thresholds.visual?.warnPercent ?? 0.1;  // %
+const CRIT_PERCENT = thresholds.visual?.critPercent ?? 5.0;  // %
+
+// ── PNG helpers ────────────────────────────────────────────────────────────────
+
+function cropPng(img, width, height) {
+  if (img.width === width && img.height === height) return img;
+  const out = new PNG({ width, height });
+  for (let y = 0; y < height; y++) {
+    for (let x = 0; x < width; x++) {
+      const src = (y * img.width + x) * 4;
+      const dst = (y * width + x) * 4;
+      out.data[dst]     = img.data[src];
+      out.data[dst + 1] = img.data[src + 1];
+      out.data[dst + 2] = img.data[src + 2];
+      out.data[dst + 3] = img.data[src + 3];
+    }
+  }
+  return out;
+}
+
+/**
+ * Compare two PNG Buffers pixel-by-pixel using pixelmatch.
+ *
+ * @param {Buffer} bufA
+ * @param {Buffer} bufB
+ * @returns {{ diffPixels: number, totalPixels: number, diffPercent: number }}
+ */
+function comparePngBuffers(bufA, bufB) {
+  const imgA = PNG.sync.read(bufA);
+  const imgB = PNG.sync.read(bufB);
+
+  const width  = Math.min(imgA.width, imgB.width);
+  const height = Math.min(imgA.height, imgB.height);
+
+  if (width === 0 || height === 0) {
+    throw new Error(`visual-diff: zero-dimension PNG (${imgA.width}×${imgA.height} vs ${imgB.width}×${imgB.height})`);
+  }
+
+  const croppedA = cropPng(imgA, width, height);
+  const croppedB = cropPng(imgB, width, height);
+  const diff     = new PNG({ width, height });
+
+  const diffPixels  = pixelmatch(croppedA.data, croppedB.data, diff.data, width, height, { threshold: 0.1 });
+  const totalPixels = width * height;
+  const diffPercent = (diffPixels / totalPixels) * 100;
+
+  return { diffPixels, totalPixels, diffPercent };
+}
+
+// ── Public API ─────────────────────────────────────────────────────────────────
+
+/**
+ * Capture a screenshot of `url` and compare against the stored baseline.
+ *
+ * First run (no baseline): saves the screenshot as the new baseline and returns
+ * a `visual_baseline_created` info finding.
+ *
+ * Subsequent runs: compares pixel-by-pixel and emits `visual_regression` when
+ * the diff exceeds the threshold, plus always emits `visual_diff_summary`.
+ *
+ * @param {object}  browser          - CdpBrowserAdapter
+ * @param {string}  url              - Page URL (already loaded)
+ * @param {object}  [opts]
+ * @param {string}  [opts.baselineDir] - Override baseline storage directory
+ * @returns {Promise<object[]>}
+ */
+export async function analyzeVisualRegression(browser, url, opts = {}) {
+  const findings = [];
+
+  // ── 1. Take screenshot ──────────────────────────────────────────────────────
+  // Use filePath so the MCP server writes the PNG to disk — take_screenshot
+  // returns an image content block, not { data: base64 }, so the filePath
+  // approach is the only reliable way to get raw PNG bytes in headless mode.
+  const tmpPath = path.join(os.tmpdir(), `argus-visual-${Date.now()}-${slugify(url)}.png`);
+  try {
+    await browser.screenshot({ format: 'png', filePath: tmpPath });
+  } catch (err) {
+    logger.warn(`[ARGUS] visual-diff: screenshot failed for ${url}: ${err.message}`);
+    return findings;
+  }
+
+  let currentBuf;
+  try {
+    currentBuf = fs.readFileSync(tmpPath);
+  } catch (err) {
+    logger.warn(`[ARGUS] visual-diff: could not read screenshot from ${tmpPath}: ${err.message}`);
+    return findings;
+  } finally {
+    try { fs.unlinkSync(tmpPath); } catch {}
+  }
+
+  if (!currentBuf || currentBuf.length === 0) {
+    logger.warn(`[ARGUS] visual-diff: empty screenshot for ${url}`);
+    return findings;
+  }
+
+  // ── 2. Resolve baseline path ────────────────────────────────────────────────
+  const baselineDir = opts.baselineDir ??
+    path.join(config.outputDir, 'baselines', 'screenshots');
+
+  try {
+    fs.mkdirSync(baselineDir, { recursive: true });
+  } catch (err) {
+    logger.warn(`[ARGUS] visual-diff: could not create baseline dir ${baselineDir}: ${err.message}`);
+    return findings;
+  }
+
+  const slug         = slugify(url);
+  const baselinePath = path.join(baselineDir, `${slug}.png`);
+
+  // ── 3. First run: save baseline ─────────────────────────────────────────────
+  if (!fs.existsSync(baselinePath)) {
+    try {
+      fs.writeFileSync(baselinePath, currentBuf);
+    } catch (err) {
+      logger.warn(`[ARGUS] visual-diff: could not write baseline ${baselinePath}: ${err.message}`);
+      return findings;
+    }
+
+    findings.push({
+      type:     'visual_baseline_created',
+      message:  `Visual baseline saved for ${url} — next run will compare against this snapshot`,
+      severity: 'info',
+      url,
+      baselinePath,
+    });
+    return findings;
+  }
+
+  // ── 4. Compare against existing baseline ────────────────────────────────────
+  let result;
+  try {
+    const baselineBuf = fs.readFileSync(baselinePath);
+    result = comparePngBuffers(baselineBuf, currentBuf);
+  } catch (err) {
+    logger.warn(`[ARGUS] visual-diff: comparison failed for ${url}: ${err.message}`);
+    return findings;
+  }
+
+  const { diffPixels, totalPixels, diffPercent } = result;
+
+  // ── 5. Emit regression finding if threshold exceeded ────────────────────────
+  if (diffPercent >= WARN_PERCENT) {
+    const sev = diffPercent >= CRIT_PERCENT ? 'critical' : 'warning';
+    findings.push({
+      type:        'visual_regression',
+      diffPercent: parseFloat(diffPercent.toFixed(3)),
+      diffPixels,
+      totalPixels,
+      threshold:   WARN_PERCENT,
+      message:     `Visual regression: ${diffPercent.toFixed(2)}% pixels changed — threshold ${WARN_PERCENT}% (warning) / ${CRIT_PERCENT}% (critical)`,
+      severity:    sev,
+      url,
+    });
+  }
+
+  // ── 6. Summary — always emitted ─────────────────────────────────────────────
+  findings.push({
+    type:        'visual_diff_summary',
+    diffPercent: parseFloat(diffPercent.toFixed(3)),
+    diffPixels,
+    totalPixels,
+    message:     `Visual diff: ${diffPercent.toFixed(3)}% (${diffPixels}/${totalPixels} pixels changed)`,
+    severity:    'info',
+    url,
+  });
+
+  return findings;
+}
+
+// ── Self-registration ──────────────────────────────────────────────────────────
+registerExpensive({
+  name:    'visual',
+  analyze: (browser, url) => analyzeVisualRegression(browser, url),
+});