argusqa-os 9.2.0

package/src/orchestration/watch-mode.js

@@ -0,0 +1,316 @@
+/**
+ * Argus Watch Mode — passive browser monitoring.
+ *
+ * Instead of navigating to URLs itself, Argus connects to whatever page is
+ * already open in Chrome and polls list_console_messages / list_network_requests
+ * at a configurable interval, reporting new errors in real time.
+ *
+ * Usage (production):
+ *   npm run watch
+ *   # or: node src/orchestration/watch-mode.js
+ *
+ * The WatchSession class is exported separately so the test harness can drive
+ * individual poll() calls without running the interval loop.
+ *
+ * Environment variables:
+ *   ARGUS_WATCH_INTERVAL_MS  — poll interval in ms (default: 3000)
+ *   TARGET_DEV_URL           — base URL to monitor (default: http://localhost:3000)
+ */
+
+import fs   from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import 'dotenv/config';
+import { createMcpClient } from '../utils/mcp-client.js';
+import { childLogger } from '../utils/logger.js';
+
+const logger = childLogger('watch-mode');
+import { CdpBrowserAdapter } from '../adapters/browser.js';
+import {
+  analyzeSecurityConsole,
+  analyzeSecurityNetwork,
+} from '../utils/security-analyzer.js';
+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');
+
+// ── Deduplication key generators ───────────────────────────────────────────────
+// Two messages/requests are considered "the same" if their keys match. This
+// prevents re-reporting errors that were already captured in a previous poll.
+//
+// Content-based keys (not ID-based) are intentional: msgid/reqid can reset
+// after navigation, which would cause ID-based dedup to suppress new findings
+// on a freshly loaded page if a prior page had the same IDs.
+
+const consoleKey = (m) =>
+  `${(m.level ?? m.type ?? 'log').toLowerCase()}::${(m.text ?? m.message ?? '').slice(0, 200)}`;
+
+const networkKey = (r) =>
+  `${r.method ?? 'GET'}::${r.url ?? ''}::${r.status ?? r.statusCode ?? 0}`;
+
+// ── Classifiers ────────────────────────────────────────────────────────────────
+
+function classifyConsoleMsg(msg, url) {
+  const level = (msg.level ?? msg.type ?? '').toLowerCase();
+  if (level === 'error' || level === 'exception' || level === 'jsexception') {
+    return {
+      type: 'console',
+      severity: 'warning',
+      message: msg.text ?? msg.message ?? '(empty)',
+      url,
+      source: msg.source ?? null,
+    };
+  }
+  if (level === 'warning' || level === 'warn') {
+    return {
+      type: 'console_warning',
+      severity: 'info',
+      message: msg.text ?? msg.message ?? '(empty)',
+      url,
+      source: msg.source ?? null,
+    };
+  }
+  return null;
+}
+
+function classifyNetworkReq(req, url) {
+  const status = req.status ?? req.statusCode ?? 0;
+  const reqUrl  = req.url ?? '';
+
+  if (status === 401 || status === 403) {
+    return {
+      type: status === 401 ? 'network_auth_error' : 'network_forbidden',
+      severity: 'critical',
+      message: `HTTP ${status} — ${reqUrl}`,
+      url: reqUrl,
+      status,
+    };
+  }
+  if (status === 404) {
+    return {
+      type: 'network_not_found',
+      severity: 'warning',
+      message: `HTTP 404 — ${reqUrl}`,
+      url: reqUrl,
+      status,
+    };
+  }
+  if (status >= 500) {
+    return {
+      type: 'network_server_error',
+      severity: 'critical',
+      message: `HTTP ${status} — ${reqUrl}`,
+      url: reqUrl,
+      status,
+    };
+  }
+  // CORS / net::ERR_* failures surface as failed requests with no status
+  if (req.failed || req.error) {
+    const err = (req.error ?? req.errorText ?? '').toLowerCase();
+    if (err.includes('cors') || err.includes('blocked') || err.includes('cross-origin')) {
+      return {
+        type: 'cors_error',
+        severity: 'critical',
+        message: `CORS blocked — ${reqUrl}`,
+        url: reqUrl,
+      };
+    }
+    if (reqUrl) {
+      return {
+        type: 'network_failed',
+        severity: 'warning',
+        message: `Request failed — ${reqUrl}${req.error ? ': ' + req.error : ''}`,
+        url: reqUrl,
+      };
+    }
+  }
+  return null;
+}
+
+// ── WatchSession ───────────────────────────────────────────────────────────────
+
+/**
+ * WatchSession tracks state between polls (seen console keys, seen network keys,
+ * accumulated findings). It does NOT own the mcp client — the caller manages
+ * the client lifecycle.
+ *
+ * Exported so the test harness can call poll() in isolation without running
+ * the interval-based runWatchMode() entry point.
+ */
+export class WatchSession {
+  constructor(browser, baseUrl) {
+    this._browser     = browser;
+    this._baseUrl     = baseUrl;
+    this._seenConsole = new Set();
+    this._seenNetwork = new Set();
+    this._allFindings = [];
+  }
+
+  /**
+   * Run one poll cycle.
+   *
+   * @returns {{ findings: object[], newConsole: object[], newNetwork: object[] }}
+   *   findings    — only the NEW findings detected this poll (not previously seen)
+   *   newConsole  — raw new console messages (for caller inspection)
+   *   newNetwork  — raw new network requests (for caller inspection)
+   */
+  async poll() {
+    const findings = [];
+
+    // ── Console ──────────────────────────────────────────────────────────────
+    const allConsole = await this._browser.listConsole();
+    const newConsole = allConsole.filter(m => {
+      const k = consoleKey(m);
+      if (this._seenConsole.has(k)) return false;
+      this._seenConsole.add(k);
+      return true;
+    });
+
+    for (const msg of newConsole) {
+      const f = classifyConsoleMsg(msg, this._baseUrl);
+      if (f) findings.push(f);
+    }
+
+    // ── Network ──────────────────────────────────────────────────────────────
+    const allNetwork = await this._browser.listNetwork();
+    const newNetwork = allNetwork.filter(r => {
+      const k = networkKey(r);
+      if (this._seenNetwork.has(k)) return false;
+      this._seenNetwork.add(k);
+      return true;
+    });
+
+    for (const req of newNetwork) {
+      const f = classifyNetworkReq(req, this._baseUrl);
+      if (f) findings.push(f);
+    }
+
+    // ── Security surface (reuses existing analyzers) ──────────────────────────
+    findings.push(...analyzeSecurityConsole(newConsole, this._baseUrl));
+    findings.push(...analyzeSecurityNetwork(newNetwork, this._baseUrl));
+
+    this._allFindings.push(...findings);
+    return { findings, newConsole, newNetwork };
+  }
+
+  /** All findings accumulated across every poll() call so far. */
+  getAllFindings() {
+    return [...this._allFindings];
+  }
+}
+
+// ── Production entry point ─────────────────────────────────────────────────────
+
+/**
+ * Start the watch loop. Polls on ARGUS_WATCH_INTERVAL_MS interval, prints new
+ * findings to the terminal, posts to Slack if configured, and on Ctrl+C writes
+ * a final HTML report.
+ *
+ * @param {string} [baseUrl] — URL to attribute findings to (does not navigate)
+ */
+export async function runWatchMode(baseUrl) {
+  const target          = baseUrl ?? process.env.TARGET_DEV_URL ?? 'http://localhost:3000';
+  const pollIntervalMs  = parseInt(process.env.ARGUS_WATCH_INTERVAL_MS ?? '3000', 10);
+
+  const mcp     = await createMcpClient();
+  const browser = new CdpBrowserAdapter(mcp);
+  const session = new WatchSession(browser, target);
+
+  logger.info('\n[ARGUS WATCH] ─────────────────────────────────────────────────');
+  logger.info(`[ARGUS WATCH] Passive monitoring — ${target}`);
+  logger.info(`[ARGUS WATCH] Polling every ${pollIntervalMs}ms. Press Ctrl+C to stop.`);
+  logger.info('[ARGUS WATCH] ─────────────────────────────────────────────────\n');
+
+  const badge = (severity) =>
+    severity === 'critical' ? '✗ CRIT' :
+    severity === 'warning'  ? '! WARN' : 'i INFO';
+
+  const doPoll = async () => {
+    try {
+      const { findings } = await session.poll();
+      if (findings.length === 0) return;
+
+      logger.info(`\n[ARGUS WATCH] ${new Date().toLocaleTimeString()} — ${findings.length} new finding(s):`);
+      for (const f of findings) {
+        logger.info(`  [${badge(f.severity)}] [${f.type}] ${f.message}`);
+      }
+
+      if (isSlackConfigured()) {
+        const bySeverity = { critical: [], warning: [], info: [] };
+        for (const f of findings) {
+          (bySeverity[f.severity] ?? bySeverity.info).push(f);
+        }
+        for (const [sev, group] of Object.entries(bySeverity)) {
+          if (group.length === 0) continue;
+          await postBugReport({
+            severity: sev,
+            title: `[Watch] ${group.length} ${sev} finding(s) — ${target}`,
+            description: group.map(f => `• *[${f.type}]* ${f.message}`).join('\n'),
+            url: target,
+            screenshotPath: null,
+            details: { findings: group, source: 'watch-mode' },
+          }).catch(e => logger.warn('[ARGUS WATCH] Slack post failed:', e.message));
+        }
+      }
+    } catch (err) {
+      logger.warn('[ARGUS WATCH] Poll error:', err.message);
+    }
+  };
+
+  // First poll fires immediately, then on interval
+  await doPoll();
+  const interval = setInterval(doPoll, pollIntervalMs);
+
+  process.on('SIGINT', async () => {
+    clearInterval(interval);
+    const all = session.getAllFindings();
+
+    logger.info(`\n[ARGUS WATCH] Stopped. Total findings: ${all.length}`);
+
+    if (all.length > 0) {
+      try {
+        fs.mkdirSync(REPORTS_DIR, { recursive: true });
+        const reportJson = {
+          baseUrl:     target,
+          generatedAt: new Date().toISOString(),
+          summary: {
+            total:    all.length,
+            critical: all.filter(f => f.severity === 'critical').length,
+            warning:  all.filter(f => f.severity === 'warning').length,
+            info:     all.filter(f => f.severity === 'info').length,
+          },
+          routes: [{ route: 'watch', url: target, errors: all }],
+          flows:  [],
+        };
+        const jsonPath = path.join(REPORTS_DIR, 'watch-report.json');
+        fs.writeFileSync(jsonPath, JSON.stringify(reportJson, null, 2), 'utf8');
+        const htmlPath = generateHtmlReport(jsonPath);
+        logger.info(`[ARGUS WATCH] HTML report written → ${htmlPath}`);
+      } catch (e) {
+        logger.warn('[ARGUS WATCH] HTML report failed:', e.message);
+      }
+    } else {
+      logger.info('[ARGUS WATCH] No issues detected during this session. ✓');
+    }
+
+    try { await browser.close(); } catch { /* ignore */ }
+    process.exit(0);
+  });
+}
+
+// ── CLI invocation ─────────────────────────────────────────────────────────────
+
+// Run when invoked directly: node src/orchestration/watch-mode.js [url]
+if (process.argv[1]?.endsWith('watch-mode.js')) {
+  runWatchMode(process.argv[2]).catch(err => {
+    logger.error('[ARGUS WATCH] Fatal:', err.message);
+    process.exit(1);
+  });
+}

package/src/registry.js

@@ -0,0 +1,18 @@
+/**
+ * Argus Analyzer Plugin Registry (v9.1.2)
+ *
+ * Analyzers self-register at module load time by calling registerCheap()
+ * or registerExpensive(). The orchestrator iterates getCheap() / getExpensive()
+ * instead of 14+ named function calls — adding a new detector = 1 file only.
+ *
+ * clearAll() is a test helper — do not call in production code.
+ */
+
+const _cheap     = [];
+const _expensive = [];
+
+export const registerCheap      = (analyzer) => _cheap.push(analyzer);
+export const registerExpensive  = (analyzer) => _expensive.push(analyzer);
+export const getCheap           = () => [..._cheap];
+export const getExpensive       = () => [..._expensive];
+export const clearAll           = () => { _cheap.length = 0; _expensive.length = 0; };

package/src/server/index.js

@@ -0,0 +1,94 @@
+/**
+ * ARGUS Server
+ *
+ * Express server that receives:
+ *   POST /slack/commands     — slash command (/argus-retest <url>)
+ *   POST /slack/interactions — Block Kit button interactions (Acknowledge, Retest)
+ *   GET  /health             — health check
+ *
+ * Run: node src/server/index.js
+ *
+ * For production, expose this server via a public URL and configure it in
+ * your Slack App settings (Slash Commands + Interactivity & Shortcuts).
+ * For local development: cloudflared tunnel --url http://localhost:3001
+ */
+
+import express from 'express';
+import 'dotenv/config';
+
+import { handleSlashCommand } from './slash-command-handler.js';
+import { handleInteraction } from './interaction-handler.js';
+import { childLogger } from '../utils/logger.js';
+
+const logger = childLogger('server');
+
+const app = express();
+const PORT = process.env.PORT ?? 3001;
+
+// ── Raw body capture (needed for Slack signature verification) ─────────────────
+// Uses Express body-parser verify callbacks so req.rawBody is populated without
+// consuming the stream separately (separate stream consumer would leave body parsers
+// with an already-exhausted stream and produce empty req.body on every request).
+// 512 KB limit matches Slack's max payload size.
+const BODY_LIMIT = '512kb';
+
+function captureRawBody(req, _res, buf) {
+  req.rawBody = buf.toString('utf8');
+}
+
+// Parse URL-encoded bodies (Slack slash commands + interactions)
+app.use(express.urlencoded({ extended: true, limit: BODY_LIMIT, verify: captureRawBody }));
+// Parse JSON bodies
+app.use(express.json({ limit: BODY_LIMIT, verify: captureRawBody }));
+
+// ── Request error handler ──────────────────────────────────────────────────────
+app.use((req, res, next) => {
+  req.on('error', err => {
+    logger.error('[ARGUS] Request stream error:', err.message);
+    if (!res.headersSent) res.status(400).send('Bad request');
+  });
+  next();
+});
+
+// ── Routes ─────────────────────────────────────────────────────────────────────
+
+app.get('/health', (req, res) => {
+  res.json({ status: 'ok', service: 'argus', ts: new Date().toISOString() });
+});
+
+// Slack slash commands
+app.post('/slack/commands', handleSlashCommand);
+
+// Slack Block Kit interactions (button clicks)
+app.post('/slack/interactions', handleInteraction);
+
+// ── Start ──────────────────────────────────────────────────────────────────────
+
+// Capture server instance so we can attach an error listener.
+const server = app.listen(PORT, () => {
+  logger.info(`[ARGUS] Server running on port ${PORT}`);
+  logger.info(`[ARGUS] Slash commands:  POST http://localhost:${PORT}/slack/commands`);
+  logger.info(`[ARGUS] Interactions:    POST http://localhost:${PORT}/slack/interactions`);
+  logger.info(`[ARGUS] Health:          GET  http://localhost:${PORT}/health`);
+  logger.info('');
+  logger.info('[ARGUS] For local testing, expose with: cloudflared tunnel --url http://localhost:' + PORT);
+});
+
+// requestTimeout is assigned synchronously here — before the Node.js event loop
+// processes any incoming connection — so every request inherits the 10 s limit.
+// Must remain after app.listen() (the server object doesn't exist before that call)
+// but must remain synchronous (not inside the listen callback) to close the startup race.
+server.requestTimeout = 10_000;
+
+// Without this, a port conflict emits an unhandled 'error' event and terminates
+// the process with a cryptic EADDRINUSE message and no guidance.
+server.on('error', err => {
+  if (err.code === 'EADDRINUSE') {
+    logger.error(`[ARGUS] Port ${PORT} is already in use — try PORT=3002 node src/server/index.js`);
+  } else {
+    logger.error('[ARGUS] Server error:', err.message);
+  }
+  process.exit(1);
+});
+
+export default app;

package/src/server/interaction-handler.js

@@ -0,0 +1,126 @@
+/**
+ * ARGUS Interaction Handler
+ *
+ * Handles Slack Block Kit button interactions:
+ *   - "Acknowledge" button → updates the original message with an acknowledged badge
+ *   - "Retest" button → triggers a new test run and posts results as thread reply
+ *
+ * Configure in Slack App:
+ *   Interactivity & Shortcuts → Request URL: https://your-server.com/slack/interactions
+ */
+
+import { verifySlackSignature } from './slash-command-handler.js';
+import { acknowledgeMessage, postRetestResult } from '../orchestration/slack-notifier.js';
+import { createMcpClient } from '../utils/mcp-client.js';
+import { runCrawl } from '../orchestration/crawl-and-report.js';
+import { childLogger } from '../utils/logger.js';
+
+const logger = childLogger('interaction-handler');
+
+/**
+ * Handle POST /slack/interactions
+ * @param {object} req - Express request
+ * @param {object} res - Express response
+ */
+export async function handleInteraction(req, res) {
+  if (!verifySlackSignature(req)) {
+    return res.status(401).json({ error: 'Invalid signature' });
+  }
+
+  let payload;
+  try {
+    // Slack sends interactions as URL-encoded JSON in the `payload` field
+    payload = JSON.parse(req.body.payload);
+  } catch {
+    return res.status(400).json({ error: 'Invalid payload' });
+  }
+
+  const { type, actions, message, channel, user } = payload;
+
+  if (type !== 'block_actions' || !actions?.length) {
+    return res.status(200).send(); // Unrecognised interaction — ack and ignore
+  }
+
+  const action = actions[0];
+  const actionId = action.action_id;
+  const messageTs = message?.ts;
+  const channelId = channel?.id;
+  const userName = user?.name ?? user?.username ?? 'unknown';
+
+  // Acknowledge the interaction immediately (Slack requires < 3s)
+  res.status(200).send();
+
+  // channelId is required for all follow-up Slack posts. Missing means the payload
+  // is from an unsupported interaction type — ack it (above) but skip async processing.
+  if (!channelId) {
+    logger.warn('[ARGUS] Interaction missing channel.id — cannot dispatch response');
+    return;
+  }
+
+  // Wrap post-response async work in try/catch. The response is already committed
+  // at this point, so any throws escape Express's error handler and become unhandled
+  // promise rejections — which crash the server in Node 15+.
+  try {
+    if (actionId === 'acknowledge') {
+      await acknowledgeMessage(messageTs, channelId, userName);
+    } else if (actionId === 'retest') {
+      await handleRetestAction({ action, messageTs, channelId, userName });
+    }
+    // 'view_page' is a URL button — Slack handles it client-side, no server action needed
+  } catch (err) {
+    logger.error('[ARGUS] Interaction post-response error:', err.message);
+  }
+}
+
+/**
+ * Handle the "Retest" button click.
+ * Triggers a new test run and posts result as thread reply.
+ */
+async function handleRetestAction({ action, messageTs, channelId, userName }) {
+  let parsedValue;
+  try {
+    parsedValue = JSON.parse(action.value ?? '{}');
+  } catch (e) {
+    // Log the raw value and error so we can diagnose malformed action payloads.
+    logger.warn('[ARGUS] Failed to parse action.value:', action.value, e.message);
+    parsedValue = {};
+  }
+
+  // Validate targetUrl is a string starting with http — parsedValue.url could be
+  // a number or boolean from a crafted payload, which passes the truthy check but breaks
+  // downstream string operations and URL construction in runCrawl.
+  const targetUrl = parsedValue.url;
+  if (typeof targetUrl !== 'string') return;
+  let _parsed;
+  try { _parsed = new URL(targetUrl); } catch { return; }
+  if (!['http:', 'https:'].includes(_parsed.protocol)) return;
+  if (/^(localhost|127\.|0\.0\.0\.0|10\.|192\.168\.|172\.(1[6-9]|2[0-9]|3[01])\.|169\.254\.|::1)/i.test(_parsed.hostname)) return;
+
+  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 CRAWL_TIMEOUT_MS = parseInt(process.env.ARGUS_CRAWL_TIMEOUT_MS ?? '120000', 10);
+    const report = await Promise.race([
+      runCrawl(mcp, [{ path: '', name: 'Retest', critical: true, waitFor: null }], targetUrl),
+      new Promise((_, reject) => setTimeout(() => reject(new Error(`Crawl timed out after ${Math.round(CRAWL_TIMEOUT_MS / 1000)}s`)), CRAWL_TIMEOUT_MS)),
+    ]);
+
+    const passed = report.summary.critical === 0;
+    const safeUserName = (userName ?? 'unknown').replace(/[*_`~<>&]/g, '');
+    const details =
+      `URL: ${targetUrl}\n` +
+      `Triggered by: @${safeUserName}\n` +
+      `Critical: ${report.summary.critical} | Warnings: ${report.summary.warning} | Info: ${report.summary.info}`;
+
+    await postRetestResult(messageTs, channelId, passed ? 'pass' : 'fail', details);
+  } catch (err) {
+    // Log full error server-side; redact from the thread reply.
+    logger.error('[ARGUS] Retest interaction failed:', err);
+    await postRetestResult(messageTs, channelId, 'fail', 'Error: check server logs for details');
+  } finally {
+    mcp?.close?.();
+  }
+}