argusqa-os 9.2.0

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

@@ -0,0 +1,185 @@
+/**
+ * ARGUS Slash Command Handler
+ *
+ * Handles Slack slash command: /argus-retest <url>
+ *
+ * Flow:
+ *   1. Slack POSTs to this handler with the slash command payload
+ *   2. We verify the request signature (SLACK_SIGNING_SECRET)
+ *   3. Respond immediately with 200 + "Running..." (Slack requires < 3s response)
+ *   4. Kick off the test run asynchronously
+ *   5. Post results back to the channel as a follow-up message
+ *
+ * Configure in Slack App:
+ *   Slash Commands → /argus-retest → Request URL: https://your-server.com/slack/commands
+ */
+
+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';
+import { childLogger } from '../utils/logger.js';
+
+const logger = childLogger('slash-command-handler');
+
+// Lazy-initialize the Slack client so SLACK_BOT_TOKEN is read at call time,
+// not at module import time (before dotenv has run).
+let _slack;
+function getSlack() {
+  return (_slack ??= new WebClient(process.env.SLACK_BOT_TOKEN));
+}
+
+/**
+ * Verify that a request genuinely came from Slack using the signing secret.
+ * https://api.slack.com/authentication/verifying-requests-from-slack
+ *
+ * @param {object} req - Express request
+ * @returns {boolean}
+ */
+export function verifySlackSignature(req) {
+  const signingSecret = process.env.SLACK_SIGNING_SECRET;
+  if (!signingSecret) return false;
+
+  const slackSignature = req.headers['x-slack-signature'];
+  const timestamp = req.headers['x-slack-request-timestamp'];
+
+  if (!slackSignature || !timestamp) return false;
+
+  // Reject requests older than 5 minutes (replay attack protection)
+  const nowSeconds = Math.floor(Date.now() / 1000);
+  const ts = parseInt(timestamp, 10);
+  if (!Number.isFinite(ts) || Math.abs(nowSeconds - ts) > 300) return false;
+
+  const sigBasestring = `v0:${timestamp}:${req.rawBody}`;
+  const mySignature = 'v0=' + crypto
+    .createHmac('sha256', signingSecret)
+    .update(sigBasestring)
+    .digest('hex');
+
+  // timingSafeEqual throws TypeError if buffer lengths differ — pre-check so we
+  // return false (invalid signature) instead of crashing with an unhandled exception.
+  if (mySignature.length !== slackSignature.length) return false;
+  return crypto.timingSafeEqual(
+    Buffer.from(mySignature),
+    Buffer.from(slackSignature)
+  );
+}
+
+/**
+ * Handle POST /slack/commands
+ * @param {object} req - Express request
+ * @param {object} res - Express response
+ */
+export async function handleSlashCommand(req, res) {
+  // Verify signature
+  if (!verifySlackSignature(req)) {
+    return res.status(401).json({ error: 'Invalid signature' });
+  }
+
+  const { command, text, response_url } = req.body;
+  // Slack guarantees channel_id and user_name in slash commands, but crafted or
+  // malformed POSTs may omit them. Guard explicitly so downstream interpolations are safe.
+  const channel_id = req.body.channel_id;
+  const user_name = req.body.user_name ?? 'unknown';
+  if (!channel_id) return res.status(400).json({ error: 'Missing channel_id' });
+
+  if (command !== '/argus-retest') {
+    return res.status(400).json({ error: 'Unknown command' });
+  }
+
+  const targetUrl = (text ?? '').trim();
+
+  if (!targetUrl) {
+    return res.json({
+      response_type: 'ephemeral',
+      text: '⚠️ Usage: `/argus-retest <url>`\nExample: `/argus-retest https://staging.yourapp.com/checkout`',
+    });
+  }
+
+  // Validate URL — reject invalid, non-http(s), and private/loopback addresses (SSRF prevention)
+  let parsedTarget;
+  try {
+    parsedTarget = new URL(targetUrl);
+  } catch {
+    return res.json({
+      response_type: 'ephemeral',
+      text: `⚠️ Invalid URL: \`${targetUrl}\`. Please provide a full URL including protocol.`,
+    });
+  }
+  if (!['http:', 'https:'].includes(parsedTarget.protocol)) {
+    return res.json({ response_type: 'ephemeral', text: '⚠️ Only http and https URLs are allowed.' });
+  }
+  if (/^(localhost|127\.|0\.0\.0\.0|10\.|192\.168\.|172\.(1[6-9]|2[0-9]|3[01])\.|169\.254\.|::1)/i.test(parsedTarget.hostname)) {
+    return res.json({ response_type: 'ephemeral', text: '⚠️ Private and loopback URLs are not allowed.' });
+  }
+
+  // Strip backticks from the URL before interpolating into Slack mrkdwn — a URL
+  // containing a backtick would break out of the inline code span and could alter formatting.
+  const safeUrl      = targetUrl.replace(/`/g, '');
+  const safeName     = user_name.replace(/[*_`~<>&]/g, '');
+
+  // Respond immediately — Slack requires a response within 3 seconds
+  res.json({
+    response_type: 'in_channel',
+    text: `🔄 *ARGUS retest started* for \`${safeUrl}\`\nRequested by @${safeName}. Results will appear here shortly...`,
+  });
+
+  // Attach .catch() so an unexpected rejection doesn't become an unhandled rejection
+  // that crashes the server (Node 15+ terminates on unhandled rejections).
+  runRetestAsync({ targetUrl, channelId: channel_id, responseUrl: response_url, requestedBy: user_name })
+    .catch(err => logger.error('[ARGUS] runRetestAsync unhandled:', err.message));
+}
+
+/**
+ * Run a retest for a specific URL and post results back to Slack.
+ * Runs after the 200 response is already sent.
+ */
+async function runRetestAsync({ targetUrl, channelId, responseUrl, requestedBy }) {
+  let mcp;
+  try {
+    mcp = await createMcpClient();
+
+    // Do NOT mutate process.env.TARGET_DEV_URL — concurrent retests share
+    // the same Node.js process env and would corrupt each other's URLs. Pass targetUrl directly.
+    const singleRoute = [{ path: '', name: 'Retest', critical: true, waitFor: null }];
+    const CRAWL_TIMEOUT_MS = parseInt(process.env.ARGUS_CRAWL_TIMEOUT_MS ?? '120000', 10);
+    const report = await Promise.race([
+      runCrawl(mcp, singleRoute, targetUrl),
+      new Promise((_, reject) => setTimeout(() => reject(new Error(`Crawl timed out after ${Math.round(CRAWL_TIMEOUT_MS / 1000)}s`)), CRAWL_TIMEOUT_MS)),
+    ]);
+
+    const { summary } = report;
+    const passed = summary.critical === 0;
+    const emoji = passed ? '✅' : '❌';
+    const status = passed ? 'PASSED' : 'FAILED';
+
+    const safeRequestedBy = (requestedBy ?? 'unknown').replace(/[*_`~<>&]/g, '');
+    await getSlack().chat.postMessage({
+      channel: channelId,
+      text: `${emoji} *Retest ${status}* for \`${targetUrl}\`\n` +
+        `Requested by @${safeRequestedBy}\n` +
+        `Critical: ${summary.critical} | Warnings: ${summary.warning} | Info: ${summary.info}`,
+    });
+
+    // Guard against SLACK_CHANNEL_CRITICAL being unset — would post "#undefined"
+    if (!passed && process.env.SLACK_CHANNEL_CRITICAL) {
+      await getSlack().chat.postMessage({
+        channel: channelId,
+        text: `↑ Full bug reports sent to <#${process.env.SLACK_CHANNEL_CRITICAL}>`,
+      });
+    }
+  } catch (err) {
+    // Log full error server-side; post only a generic message to Slack so internal
+    // paths/stack traces/env var names are not leaked to the channel.
+    logger.error('[ARGUS] Retest failed:', err);
+    // Log delivery failures — silent .catch(() => {}) meant the operator
+    // had no indication when the error notification itself failed to post.
+    await getSlack().chat.postMessage({
+      channel: channelId,
+      text: `⚠️ *Retest error* for \`${targetUrl}\` — check server logs for details`,
+    }).catch(e => logger.error('[ARGUS] Failed to post error notification:', e.message));
+  } finally {
+    mcp?.close?.();
+  }
+}

package/src/utils/api-frequency.js

@@ -0,0 +1,128 @@
+/**
+ * Shared API frequency analysis utilities.
+ *
+ * Previously duplicated in crawl-and-report.js and env-comparison.js.
+ * Single source of truth — import from here in both orchestrators.
+ */
+
+import { thresholds } from '../config/targets.js';
+
+/**
+ * Detect API endpoints called more than once in a single page load.
+ * Groups by normalized URL + method. Flags duplicates with severity based
+ * on call count and whether it looks like an accidental double-fetch.
+ *
+ * @param {object[]} networkReqs - All network requests from list_network_requests
+ * @param {string} pageUrl - Page URL (for error reporting)
+ * @returns {object[]} Bug entries for duplicate/excessive API calls
+ */
+export function analyzeApiFrequency(networkReqs, pageUrl) {
+  const bugs = [];
+
+  // Only examine XHR/fetch calls — filter out static assets
+  const staticExtensions = /\.(js|css|png|jpg|jpeg|gif|svg|ico|woff|woff2|ttf|eot|map|webp|avif)(\?|$)/i;
+  const apiCalls = networkReqs.filter(req => {
+    const u = req.url ?? '';
+    if (staticExtensions.test(u)) return false;
+    // Include if it has /api/, /graphql, /v1/, /v2/, or is XHR/fetch type
+    return (
+      /\/(api|graphql|rest|v\d+|_next\/data|trpc)\//i.test(u) ||
+      req.resourceType === 'XHR' ||
+      req.resourceType === 'Fetch' ||
+      req.initiatorType === 'xmlhttprequest' ||
+      req.initiatorType === 'fetch'
+    );
+  });
+
+  // Group by method + normalized URL (strip query string for grouping key,
+  // but keep it in the report so you can see the exact calls made)
+  const groups = {};
+  for (const req of apiCalls) {
+    const method = (req.method ?? 'GET').toUpperCase();
+    // Coalesce req.url — the filter uses a coerced copy but the loop uses the
+    // original; req.url could still be undefined, causing new URL(undefined) to throw.
+    const normalized = normalizeApiUrl(req.url ?? '');
+    const key = `${method}::${normalized}`;
+    if (!groups[key]) {
+      groups[key] = { method, normalizedUrl: normalized, calls: [], key };
+    }
+    groups[key].calls.push({
+      url: req.url,
+      status: req.status,
+      duration: req.duration ?? req.time ?? null,
+      initiator: req.initiator ?? null,
+    });
+  }
+
+  // Report groups with more than one call
+  for (const group of Object.values(groups)) {
+    const count = group.calls.length;
+    if (count <= 1) continue;
+
+    // Severity ladder:
+    //   2 calls  → info    (might be intentional: prefetch + actual)
+    //   ≥ warningCount  → warning (likely a bug: double render, missing dependency array)
+    //   ≥ criticalCount → critical (runaway loop, missing cleanup)
+    let severity = 'info';
+    if (count >= thresholds.apiFrequency.criticalCount) severity = 'critical';
+    else if (count >= thresholds.apiFrequency.warningCount) severity = 'warning';
+
+    const durations = group.calls
+      .map(c => c.duration)
+      .filter(Boolean)
+      .map(d => `${Math.round(d)}ms`);
+
+    bugs.push({
+      type: 'api_duplicate_call',
+      method: group.method,
+      endpoint: group.normalizedUrl,
+      callCount: count,
+      calls: group.calls,
+      durations,
+      message: `API called ${count}x in one page load: ${group.method} ${group.normalizedUrl}${count >= 5 ? ' — possible infinite loop or missing cleanup' : count >= 3 ? ' — likely double-fetch bug (check useEffect deps or component re-mounts)' : ' — called twice (verify this is intentional)'}`,
+      severity,
+      url: pageUrl,
+    });
+  }
+
+  // Also report total unique API calls as an info summary
+  const uniqueCount = Object.keys(groups).length;
+  const totalCount = apiCalls.length;
+  if (totalCount > 0) {
+    bugs.push({
+      type: 'api_call_summary',
+      uniqueEndpoints: uniqueCount,
+      totalCalls: totalCount,
+      duplicateEndpoints: Object.values(groups).filter(g => g.calls.length > 1).length,
+      message: `API summary: ${totalCount} calls to ${uniqueCount} unique endpoints${Object.values(groups).filter(g => g.calls.length > 1).length > 0 ? ` (${Object.values(groups).filter(g => g.calls.length > 1).length} called more than once)` : ''}`,
+      severity: 'info',
+      url: pageUrl,
+    });
+  }
+
+  return bugs;
+}
+
+/**
+ * Normalize an API URL for grouping: strip query params, collapse IDs.
+ * e.g. /api/users/123/posts?page=2 → /api/users/{id}/posts
+ *
+ * @param {string} url
+ * @returns {string}
+ */
+export function normalizeApiUrl(url) {
+  // Guard non-string input — new URL(null) throws into the catch, then
+  // null.replace() in the catch block throws a second uncaught TypeError.
+  if (typeof url !== 'string') return '';
+  try {
+    const u = new URL(url);
+    const pathname = u.pathname
+      .replace(/\/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/gi, '/{id}')
+      .replace(/\/\d+/g, '/{id}');
+    // Include protocol so http://api.example.com and https://api.example.com
+    // are not collapsed to the same key in frequency analysis and diffs.
+    return `${u.protocol}//${u.hostname}${pathname}`;
+  } catch {
+    return url.replace(/[?#].*/, '').replace(/\/\d+/g, '/{id}');
+  }
+}

package/src/utils/baseline-manager.js

@@ -0,0 +1,255 @@
+/**
+ * Argus v3 Phase B3 — Historical baselines + trend tracking
+ * Phase D4 — Extended to cover flow findings (flow_assert_failed, flow_step_failed)
+ * Phase D7.2 — Per-branch baselines (getCurrentBranch → <branch>.json / <branch>-trends.json)
+ *
+ * Baseline file (reports/baselines/<branch>.json): per-route + per-flow finding key arrays.
+ * Trends file  (reports/baselines/<branch>-trends.json): append-only run history.
+ *
+ * Finding key: `type::message[:100]::status` — stable across runs, excludes timestamps.
+ */
+
+import fs            from 'fs';
+import path          from 'path';
+import { execSync }  from 'child_process';
+// Import shared findingKey from flakiness-detector so both modules use
+// identical normalization (trim + whitespace collapse). Local copy removed.
+import { findingKey } from './flakiness-detector.js';
+import { childLogger } from './logger.js';
+
+const logger = childLogger('baseline-manager');
+
+/**
+ * Sanitize a git branch name into a safe filename segment.
+ * Replaces any character that is not alphanumeric, dot, hyphen, or underscore with a hyphen.
+ * Collapses consecutive hyphens and strips leading/trailing hyphens.
+ */
+function sanitizeBranch(branch) {
+  return branch
+    .replace(/[^a-zA-Z0-9._-]/g, '-')
+    .replace(/-{2,}/g, '-')
+    .replace(/^-+|-+$/g, '')
+    || 'default';
+}
+
+/**
+ * Return the current git branch name as a sanitized filename segment.
+ *
+ * Resolution order:
+ *   1. Read <cwd>/.git/HEAD directly (fast, no subprocess)
+ *   2. Fall back to `git rev-parse --abbrev-ref HEAD`
+ *   3. Fall back to `'default'` when not in a git repo or in detached HEAD state
+ *
+ * Examples: "main" → "main", "feature/my-feat" → "feature-my-feat"
+ *
+ * @returns {string}
+ */
+export function getCurrentBranch() {
+  // Strategy 1: read .git/HEAD directly (no subprocess, works in any Node version)
+  try {
+    const headPath = path.resolve(process.cwd(), '.git', 'HEAD');
+    const head = fs.readFileSync(headPath, 'utf8').trim();
+    const match = head.match(/^ref: refs\/heads\/(.+)$/);
+    if (match) return sanitizeBranch(match[1]);
+    // Detached HEAD (contains a commit hash) — fall through to git command
+  } catch { /* .git/HEAD not readable — fall through */ }
+
+  // Strategy 2: git command
+  try {
+    const branch = execSync('git rev-parse --abbrev-ref HEAD', {
+      stdio: ['pipe', 'pipe', 'pipe'],
+      timeout: 3000,
+    }).toString().trim();
+    if (branch && branch !== 'HEAD') return sanitizeBranch(branch);
+  } catch { /* not a git repo or git not installed — fall through */ }
+
+  // Strategy 3: CI environment variables (GitHub Actions, GitLab CI, etc.)
+  const ciBranch = process.env.GITHUB_REF_NAME ?? process.env.CI_COMMIT_BRANCH ?? process.env.BRANCH_NAME;
+  if (ciBranch) return sanitizeBranch(ciBranch);
+
+  return 'default';
+}
+
+/**
+ * Load baseline from disk. Returns null if file does not exist or cannot be parsed.
+ * Route and flow keys are stored as Sets for O(1) lookup.
+ * Old baselines (pre-D4) have no `flows` field — flows defaults to an empty Map.
+ */
+export function loadBaseline(baselineFile) {
+  if (!fs.existsSync(baselineFile)) return null;
+  try {
+    const raw = JSON.parse(fs.readFileSync(baselineFile, 'utf8'));
+    const routes = new Map();
+    for (const [url, keys] of Object.entries(raw.routes ?? {})) {
+      routes.set(url, new Set(keys));
+    }
+    const flows = new Map();
+    for (const [flowName, keys] of Object.entries(raw.flows ?? {})) {
+      flows.set(flowName, new Set(keys));
+    }
+    const codebase = new Set(raw.codebase ?? []);
+    return { savedAt: raw.savedAt, routes, flows, codebase };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Persist current report as the new baseline.
+ * Writes per-route and per-flow arrays of finding keys — timestamps are excluded.
+ */
+export function saveBaseline(baselineFile, report) {
+  const dir = path.dirname(baselineFile);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  const routes = {};
+  for (const routeResult of report.routes) {
+    routes[routeResult.url] = (routeResult.errors ?? []).map(findingKey);
+  }
+  const flows = {};
+  for (const flowResult of (report.flows ?? [])) {
+    flows[flowResult.flowName] = (flowResult.findings ?? []).map(findingKey);
+  }
+  const codebase = (report.codebase ?? []).map(findingKey);
+  const tmpBaseline = baselineFile + '.tmp';
+  fs.writeFileSync(
+    tmpBaseline,
+    JSON.stringify({ savedAt: new Date().toISOString(), routes, flows, codebase }, null, 2),
+  );
+  fs.renameSync(tmpBaseline, baselineFile);
+}
+
+/**
+ * Annotate each finding in the report with `isNew: boolean`.
+ * Returns { isFirstRun, newCount, resolvedCount, flowNewCount, flowResolvedCount }.
+ *
+ * First run (baseline === null): all findings are new, resolved counts = 0.
+ * Old baselines (pre-D4) have no `flows` map — flow findings are treated as new.
+ */
+export function applyBaseline(report, baseline) {
+  if (!baseline) {
+    for (const routeResult of report.routes) {
+      for (const finding of routeResult.errors) {
+        finding.isNew = true;
+      }
+    }
+    for (const flowResult of (report.flows ?? [])) {
+      for (const finding of flowResult.findings) {
+        finding.isNew = true;
+      }
+    }
+    const newCount         = report.routes.reduce((n, r) => n + r.errors.length, 0);
+    const flowNewCount     = (report.flows ?? []).reduce((n, f) => n + f.findings.length, 0);
+    const codebaseNewCount = (report.codebase ?? []).length;
+    for (const finding of (report.codebase ?? [])) {
+      finding.isNew = true;
+    }
+    // Include codebase counts so PR/Slack trend summaries reflect codebase findings.
+    return { isFirstRun: true, newCount, resolvedCount: 0, flowNewCount, flowResolvedCount: 0, codebaseNewCount, codebaseResolvedCount: 0 };
+  }
+
+  let newCount = 0;
+  let resolvedCount = 0;
+
+  for (const routeResult of report.routes) {
+    const baselineKeys = baseline.routes.get(routeResult.url) ?? new Set();
+    const currentKeys = new Set();
+
+    for (const finding of routeResult.errors) {
+      const key = findingKey(finding);
+      currentKeys.add(key);
+      finding.isNew = !baselineKeys.has(key);
+      if (finding.isNew) newCount++;
+    }
+
+    for (const key of baselineKeys) {
+      if (!currentKeys.has(key)) resolvedCount++;
+    }
+  }
+
+  let flowNewCount = 0;
+  let flowResolvedCount = 0;
+  const baselineFlows = baseline.flows ?? new Map();
+
+  for (const flowResult of (report.flows ?? [])) {
+    const baselineKeys = baselineFlows.get(flowResult.flowName) ?? new Set();
+    const currentKeys = new Set();
+
+    for (const finding of flowResult.findings) {
+      const key = findingKey(finding);
+      currentKeys.add(key);
+      finding.isNew = !baselineKeys.has(key);
+      if (finding.isNew) flowNewCount++;
+    }
+
+    for (const key of baselineKeys) {
+      if (!currentKeys.has(key)) flowResolvedCount++;
+    }
+  }
+
+  // C1 codebase findings — annotate isNew + count new/resolved
+  const baselineCodebase = baseline.codebase ?? new Set();
+  const currentCodebaseKeys = new Set();
+  let codebaseNewCount = 0;
+  let codebaseResolvedCount = 0;
+  for (const finding of (report.codebase ?? [])) {
+    const key = findingKey(finding);
+    currentCodebaseKeys.add(key);
+    finding.isNew = !baselineCodebase.has(key);
+    if (finding.isNew) codebaseNewCount++;
+  }
+  for (const key of baselineCodebase) {
+    if (!currentCodebaseKeys.has(key)) codebaseResolvedCount++;
+  }
+
+  // Return codebase counts alongside route/flow counts so Slack/GitHub reporters
+  // can include codebase findings in trend summaries and PR comments.
+  return { isFirstRun: false, newCount, resolvedCount, flowNewCount, flowResolvedCount, codebaseNewCount, codebaseResolvedCount };
+}
+
+/**
+ * Append one trend entry to the trends file (creates the file if absent).
+ */
+export function appendTrend(trendsFile, entry) {
+  const dir = path.dirname(trendsFile);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+
+  const lockFile = trendsFile + '.lock';
+  // Remove stale lock files left by crashed processes (older than 60s)
+  try {
+    const lockStat = fs.statSync(lockFile);
+    if (Date.now() - lockStat.mtimeMs > 60_000) {
+      fs.unlinkSync(lockFile);
+      logger.warn('[ARGUS] Removed stale trend lock file:', lockFile);
+    }
+  } catch { /* lock doesn't exist — good */ }
+
+  let lockFd = null;
+  try {
+    lockFd = fs.openSync(lockFile, 'wx');
+  } catch (err) {
+    if (err.code === 'EEXIST') {
+      logger.warn('[ARGUS] appendTrend: lock held by another shard — skipping to avoid corruption');
+      return;
+    }
+    throw err;
+  }
+  try {
+    let trends = [];
+    if (fs.existsSync(trendsFile)) {
+      // JSON.parse may return a non-array (corrupt file contains `{}`); assigning
+      // that to trends would cause trends.push() to throw "not a function" later.
+      try {
+        const parsed = JSON.parse(fs.readFileSync(trendsFile, 'utf8'));
+        trends = Array.isArray(parsed) ? parsed : [];
+      } catch { trends = []; }
+    }
+    trends.push(entry);
+    if (trends.length > 500) trends = trends.slice(-500);
+    const tmpTrends = trendsFile + '.tmp';
+    fs.writeFileSync(tmpTrends, JSON.stringify(trends, null, 2));
+    fs.renameSync(tmpTrends, trendsFile);
+  } finally {
+    try { fs.closeSync(lockFd); } catch {}
+    try { fs.unlinkSync(lockFile); } catch {}
+  }
+}