argusqa-os 9.2.0

package/src/utils/seo-analyzer.js

@@ -0,0 +1,164 @@
+/**
+ * ARGUS SEO Analyzer (v3 Phase A3)
+ *
+ * Injected via evaluate_script to inspect the live DOM for SEO signals:
+ *   - <meta name="description"> presence
+ *   - Open Graph tags (og:title, og:description, og:image)
+ *   - Number of <h1> tags
+ *   - <title> length / genericness
+ *   - <link rel="canonical"> presence
+ *   - <meta name="viewport"> presence
+ *
+ * Returns a JSON string that parseSeoAnalysisResult() converts to bug entries.
+ */
+
+/**
+ * JavaScript arrow function injected into the page via mcp.evaluate_script.
+ * Runs entirely in the page's browser context — no Node.js APIs available.
+ */
+export const SEO_ANALYSIS_SCRIPT = `() => {
+  function sel(s) { return !!document.querySelector(s); }
+  return JSON.stringify({
+    hasDescription:   sel('meta[name="description"]'),
+    hasOgTitle:       sel('meta[property="og:title"]'),
+    hasOgDescription: sel('meta[property="og:description"]'),
+    hasOgImage:       sel('meta[property="og:image"]'),
+    ogImageUrl:       (document.querySelector('meta[property="og:image"]') || {}).getAttribute?.('content') || null,
+    h1Count:          document.querySelectorAll('h1').length,
+    titleText:        document.title || '',
+    titleLength:      (document.title || '').trim().length,
+    hasCanonical:     sel('link[rel="canonical"]'),
+    hasViewport:      sel('meta[name="viewport"]'),
+  });
+}`;
+
+/**
+ * Convert the raw evaluate_script result from SEO_ANALYSIS_SCRIPT into
+ * structured bug entries for the Argus report.
+ *
+ * @param {object|string|null} rawResult - Parsed object, JSON string, or null
+ * @param {string} url - Page URL for error context
+ * @returns {object[]} Bug entries
+ */
+export function parseSeoAnalysisResult(rawResult, url) {
+  if (rawResult == null) return [];
+
+  // Unwrap MCP { result: '...' } response shape before parsing — the same
+  // pattern used by security-analyzer and content-analyzer. Without this, when the MCP
+  // client returns an object wrapper, JSON.stringify(rawResult) serialises the envelope
+  // instead of the inner payload and all SEO fields are undefined → false positives.
+  let inner = rawResult;
+  if (typeof rawResult === 'object' && rawResult !== null && !Array.isArray(rawResult)) {
+    inner = rawResult.result !== undefined ? rawResult.result : rawResult;
+  }
+
+  let data;
+  try {
+    const str = typeof inner === 'string' ? inner : JSON.stringify(inner);
+    data = JSON.parse(str);
+  } catch {
+    return [];
+  }
+
+  if (!data || typeof data !== 'object') return [];
+
+  const bugs = [];
+
+  if (!data.hasDescription) {
+    bugs.push({
+      type:    'seo_missing_description',
+      message: 'Missing <meta name="description"> — page has no search snippet',
+      severity: 'warning',
+      url,
+    });
+  }
+
+  if (!data.hasOgTitle) {
+    bugs.push({
+      type:     'seo_missing_og',
+      property: 'og:title',
+      message:  'Missing <meta property="og:title"> — social sharing title not set',
+      severity: 'warning',
+      url,
+    });
+  }
+
+  if (!data.hasOgDescription) {
+    bugs.push({
+      type:     'seo_missing_og',
+      property: 'og:description',
+      message:  'Missing <meta property="og:description"> — social sharing description not set',
+      severity: 'warning',
+      url,
+    });
+  }
+
+  if (!data.hasOgImage) {
+    bugs.push({
+      type:     'seo_missing_og',
+      property: 'og:image',
+      message:  'Missing <meta property="og:image"> — social sharing image not set',
+      severity: 'warning',
+      url,
+    });
+  } else if (data.ogImageUrl && !data.ogImageUrl.startsWith('http://') && !data.ogImageUrl.startsWith('https://')) {
+    const isProtocolRelative = data.ogImageUrl.startsWith('//');
+    bugs.push({
+      type:     'seo_og_image_relative_url',
+      property: 'og:image',
+      message:  isProtocolRelative
+        ? `og:image URL is protocol-relative ("${data.ogImageUrl}") — Open Graph requires an absolute URL with scheme (https://)`
+        : `og:image URL is relative ("${data.ogImageUrl}") — Open Graph requires an absolute URL`,
+      severity: 'warning',
+      url,
+    });
+  }
+
+  if (data.h1Count > 1) {
+    bugs.push({
+      type:    'seo_multiple_h1',
+      h1Count: data.h1Count,
+      message: `Multiple <h1> tags detected (${data.h1Count}) — page should have exactly one`,
+      severity: 'warning',
+      url,
+    });
+  } else if (data.h1Count === 0) {
+    bugs.push({
+      type:    'seo_missing_h1',
+      message: 'No <h1> tag on page — missing primary heading',
+      severity: 'warning',
+      url,
+    });
+  }
+
+  if (data.titleLength < 10) {
+    bugs.push({
+      type:        'seo_generic_title',
+      titleText:   data.titleText,
+      titleLength: data.titleLength,
+      message:     `Page title too short (${data.titleLength} chars: "${data.titleText}") — aim for 10–60 chars`,
+      severity:    'warning',
+      url,
+    });
+  }
+
+  if (!data.hasCanonical) {
+    bugs.push({
+      type:    'seo_missing_canonical',
+      message: 'Missing <link rel="canonical"> — duplicate content risk',
+      severity: 'warning',
+      url,
+    });
+  }
+
+  if (!data.hasViewport) {
+    bugs.push({
+      type:    'seo_missing_viewport',
+      message: 'Missing <meta name="viewport"> — mobile rendering undefined',
+      severity: 'warning',
+      url,
+    });
+  }
+
+  return bugs;
+}

package/src/utils/session-manager.js

@@ -0,0 +1,12 @@
+/**
+ * Session Manager — backward-compat re-export barrel (v9.1.7).
+ *
+ * All callers continue to import from this file unchanged.
+ * Implementations live in the two focused modules below.
+ *
+ *   session-persistence.js — saveSession, restoreSession, hasSession, clearSession
+ *   login-orchestrator.js  — runLoginFlow, refreshSession
+ */
+
+export * from './session-persistence.js';
+export * from './login-orchestrator.js';

package/src/utils/session-persistence.js

@@ -0,0 +1,214 @@
+/**
+ * Session Persistence — save / restore / query browser session state.
+ *
+ * Handles cookies (JS-accessible only), localStorage, and sessionStorage.
+ * Uses an atomic tmp→rename write so a mid-write crash leaves the previous
+ * session file intact rather than a truncated JSON blob.
+ *
+ * Session file format:
+ * {
+ *   savedAt:        ISO timestamp,
+ *   originUrl:      origin the session was captured from,
+ *   cookies:        document.cookie string (JS-visible cookies only),
+ *   localStorage:   { key → value },
+ *   sessionStorage: { key → value }
+ * }
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { unwrapEval } from './mcp-client.js';
+import { childLogger } from './logger.js';
+
+const logger = childLogger('session-persistence');
+
+// ── Capture Script ──────────────────────────────────────────────────────────────
+
+const SESSION_CAPTURE_SCRIPT = `() => {
+  var ls = {};
+  for (var i = 0; i < localStorage.length; i++) {
+    var k = localStorage.key(i);
+    if (k !== null) ls[k] = localStorage.getItem(k);
+  }
+  var ss = {};
+  for (var j = 0; j < sessionStorage.length; j++) {
+    var sk = sessionStorage.key(j);
+    if (sk !== null) ss[sk] = sessionStorage.getItem(sk);
+  }
+  return JSON.stringify({
+    cookies: document.cookie,
+    localStorage: ls,
+    sessionStorage: ss,
+    origin: window.location.origin
+  });
+}`;
+
+// ── Restore Script Builder ──────────────────────────────────────────────────────
+
+function buildRestoreScript(state) {
+  const lines = [];
+
+  if (state.cookies) {
+    for (const part of state.cookies.split(';')) {
+      const pair = part.trim();
+      if (pair) {
+        lines.push(`document.cookie=${JSON.stringify(pair + '; path=/')};`);
+      }
+    }
+  }
+
+  for (const [k, v] of Object.entries(state.localStorage ?? {})) {
+    lines.push(`localStorage.setItem(${JSON.stringify(k)},${JSON.stringify(String(v ?? ''))});`);
+  }
+
+  for (const [k, v] of Object.entries(state.sessionStorage ?? {})) {
+    lines.push(`sessionStorage.setItem(${JSON.stringify(k)},${JSON.stringify(String(v ?? ''))});`);
+  }
+
+  return `() => { ${lines.join(' ')} return true; }`;
+}
+
+// ── Session Save ────────────────────────────────────────────────────────────────
+
+/**
+ * Capture session state from the current page and write to a JSON file.
+ * Must be called while the browser is on the authenticated origin.
+ *
+ * @param {object} browser     - CdpBrowserAdapter
+ * @param {string} sessionFile - Path to write the session JSON
+ * @returns {Promise<object>}  The session state object
+ */
+export async function saveSession(browser, sessionFile) {
+  let raw;
+  try {
+    raw = await browser.evaluate(SESSION_CAPTURE_SCRIPT);
+  } catch (err) {
+    throw new Error(`[ARGUS] saveSession: evaluate_script failed — Chrome may not be running: ${err.message}`);
+  }
+  const val = unwrapEval(raw);
+
+  let parsed;
+  try {
+    parsed = typeof val === 'string' ? JSON.parse(val) : val;
+    if (!parsed || typeof parsed !== 'object') throw new Error('unexpected shape');
+  } catch {
+    throw new Error(`[ARGUS] saveSession: evaluate_script returned non-JSON — Chrome may not be running. Raw: ${String(val).slice(0, 120)}`);
+  }
+
+  const state = {
+    savedAt:        new Date().toISOString(),
+    originUrl:      String(parsed.origin ?? ''),
+    cookies:        String(parsed.cookies ?? ''),
+    localStorage:   parsed.localStorage  !== null && typeof parsed.localStorage  === 'object' ? parsed.localStorage  : {},
+    sessionStorage: parsed.sessionStorage !== null && typeof parsed.sessionStorage === 'object' ? parsed.sessionStorage : {},
+  };
+
+  const dir = path.dirname(sessionFile);
+  if (dir) fs.mkdirSync(dir, { recursive: true });
+
+  const tmpFile = `${sessionFile}.tmp`;
+  fs.writeFileSync(tmpFile, JSON.stringify(state, null, 2), 'utf8');
+  fs.renameSync(tmpFile, sessionFile);
+
+  const lsCount   = Object.keys(state.localStorage).length;
+  const ssCount   = Object.keys(state.sessionStorage).length;
+  const hasCookie = state.cookies.length > 0;
+  logger.info(
+    `[ARGUS] Session saved → ${sessionFile}` +
+    ` (${lsCount} localStorage, ${ssCount} sessionStorage, cookies: ${hasCookie ? 'yes' : 'none'})`
+  );
+
+  return state;
+}
+
+// ── Session Restore ─────────────────────────────────────────────────────────────
+
+/**
+ * Restore a saved session into the browser.
+ *
+ * Navigates to baseUrl so cookies land on the correct domain, injects saved
+ * state, then returns. Caller should navigate to the target route afterward.
+ *
+ * @param {object} browser     - CdpBrowserAdapter
+ * @param {string} baseUrl     - Must match the origin the session was captured from
+ * @param {string} sessionFile - Path to the session JSON file
+ * @returns {Promise<boolean>} true if session was restored, false if no session file
+ */
+export async function restoreSession(browser, baseUrl, sessionFile) {
+  if (!fs.existsSync(sessionFile)) {
+    logger.warn(`[ARGUS] No session file at ${sessionFile} — skipping restore`);
+    return false;
+  }
+
+  let state;
+  try {
+    state = JSON.parse(fs.readFileSync(sessionFile, 'utf8'));
+  } catch (err) {
+    logger.warn(`[ARGUS] Failed to parse session file ${sessionFile}: ${err.message}`);
+    return false;
+  }
+
+  if (state.originUrl) {
+    try {
+      const savedOrigin   = new URL(state.originUrl).origin;
+      const currentOrigin = new URL(baseUrl).origin;
+      if (savedOrigin !== currentOrigin) {
+        logger.warn(
+          `[ARGUS] Session origin mismatch: saved="${savedOrigin}" current="${currentOrigin}" — ` +
+          `session will not apply; re-run login to capture a fresh session`
+        );
+        return false;
+      }
+    } catch { /* URL parse failure — proceed and let Chrome handle it */ }
+  }
+
+  await browser.navigate(baseUrl);
+  await new Promise(r => setTimeout(r, 400));
+
+  const restoreScript = buildRestoreScript(state);
+  await browser.evaluate(restoreScript);
+
+  logger.info(`[ARGUS] Session restored from ${sessionFile} (saved at ${state.savedAt})`);
+  return true;
+}
+
+// ── Session Utilities ───────────────────────────────────────────────────────────
+
+/**
+ * Check whether a valid, non-expired session file exists.
+ *
+ * @param {string} sessionFile
+ * @param {number} [maxAgeMs=3600000] - Max age in ms before requiring re-login (default: 1 h)
+ * @returns {boolean}
+ */
+export function hasSession(sessionFile, maxAgeMs = 60 * 60 * 1000) {
+  if (!fs.existsSync(sessionFile)) return false;
+  try {
+    const state = JSON.parse(fs.readFileSync(sessionFile, 'utf8'));
+    const age   = Date.now() - new Date(state.savedAt).getTime();
+    return age < maxAgeMs;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Delete the session file, forcing re-login on the next run.
+ *
+ * @param {string} sessionFile
+ */
+export function clearSession(sessionFile) {
+  let cleared = false;
+  if (fs.existsSync(sessionFile)) {
+    fs.unlinkSync(sessionFile);
+    cleared = true;
+  }
+  const tmpFile = `${sessionFile}.tmp`;
+  if (fs.existsSync(tmpFile)) {
+    try {
+      fs.unlinkSync(tmpFile);
+      logger.debug(`[ARGUS] Removed stale session temp file: ${tmpFile}`);
+    } catch {}
+  }
+  if (cleared) logger.info(`[ARGUS] Session cleared: ${sessionFile}`);
+}

package/src/utils/severity-overrides.js

@@ -0,0 +1,91 @@
+/**
+ * Argus D7.5 — Severity policy overrides.
+ * Post-processes all findings in a report before Slack routing and baseline
+ * comparison, letting teams adjust or silence detection types without touching
+ * analyzer code.
+ *
+ * Configure in src/config/targets.js:
+ *   export const severityOverrides = {
+ *     seo_missing_description: 'info',      // downgrade to info
+ *     cache_headers_missing:   'suppress',  // remove entirely from report
+ *   };
+ *
+ * Supported target values: 'critical' | 'warning' | 'info' | 'suppress'
+ */
+
+import { childLogger } from './logger.js';
+
+const logger = childLogger('severity-overrides');
+
+const VALID_SEVERITIES = new Set(['critical', 'warning', 'info']);
+
+/**
+ * Apply severity overrides to every finding in the report (mutates in-place).
+ *
+ * For each finding whose `type` key appears in severityOverrides:
+ *   - If the override value is 'suppress'        → finding is removed from its array
+ *   - If the override is a valid severity string  → finding.severity is replaced
+ *   - If the override value is unrecognized       → finding is left unchanged
+ *
+ * After this call, report.routes[].errors and report.flows[].findings reflect
+ * the overridden state. The caller is responsible for rebuilding report.summary.
+ *
+ * @param {object} report           - Report object (mutated in-place)
+ * @param {object} severityOverrides - Map of finding type → target severity / 'suppress'
+ * @returns {{ overriddenCount: number, suppressedCount: number }}
+ */
+export function applyOverrides(report, severityOverrides) {
+  if (!severityOverrides || Object.keys(severityOverrides).length === 0) {
+    return { overriddenCount: 0, suppressedCount: 0 };
+  }
+
+  let overriddenCount = 0;
+  let suppressedCount = 0;
+
+  function processFindings(findings) {
+    // Guard against null/undefined — routeResult.errors may be absent if a route
+    // had no findings array populated; iterating undefined throws a TypeError.
+    if (!Array.isArray(findings)) return [];
+    const kept = [];
+    for (const finding of findings) {
+      const override = Object.prototype.hasOwnProperty.call(severityOverrides, finding.type)
+        ? severityOverrides[finding.type]
+        : undefined;
+      if (override === undefined) {
+        kept.push(finding);
+        continue;
+      }
+      if (override === 'suppress') {
+        suppressedCount++;
+        continue;
+      }
+      if (VALID_SEVERITIES.has(override)) {
+        if (finding.severity !== override) {
+          finding.severity = override;
+          overriddenCount++;
+        }
+        kept.push(finding);
+        continue;
+      }
+      // Log unknown override values — a typo in severityOverrides config silently
+      // does nothing; warn so developers can spot misconfiguration immediately.
+      logger.warn(`[ARGUS] severity-overrides: unrecognized value "${override}" for type "${finding.type}" — expected critical|warning|info|suppress`);
+      kept.push(finding);
+    }
+    return kept;
+  }
+
+  // report.routes must be guarded — report.flows uses ?? [] safely but routes did not;
+  // if routes is undefined the for-of throws a TypeError before any findings are processed.
+  for (const routeResult of (report.routes ?? [])) {
+    routeResult.errors = processFindings(routeResult.errors);
+  }
+  for (const flowResult of (report.flows ?? [])) {
+    flowResult.findings = processFindings(flowResult.findings);
+  }
+  if (report.codebase) {
+    report.codebase = processFindings(report.codebase);
+  }
+
+  return { overriddenCount, suppressedCount };
+}

package/src/utils/slack-guard.js

@@ -0,0 +1,18 @@
+/**
+ * Argus D7.7 — Slack-optional mode guard.
+ *
+ * Returns true only when a Slack Bot Token is present in the environment.
+ * Used by crawl-and-report.js to decide whether to dispatch to Slack or fall
+ * back to generating a local HTML report and opening it in the browser.
+ *
+ * Configure in .env:
+ *   SLACK_BOT_TOKEN=xoxb-...   ← Slack active
+ *   (absent)                   ← HTML-only mode
+ */
+
+/**
+ * @returns {boolean} true when SLACK_BOT_TOKEN is set and non-empty
+ */
+export function isSlackConfigured() {
+  return !!(process.env.SLACK_BOT_TOKEN ?? '').trim();
+}

package/src/utils/slug.js

@@ -0,0 +1,8 @@
+/**
+ * Shared slugify helper — converts a human-readable string to a URL/filename-safe slug.
+ * Used for screenshot filenames and report paths.
+ */
+export function slugify(str) {
+  if (str == null) return 'unnamed';
+  return (String(str).toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '')) || 'unnamed';
+}