argusqa-os 9.2.0

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "argusqa-os",
+  "version": "9.2.0",
+  "description": "Argus — AI-powered automated dev-testing platform using Chrome DevTools MCP and Claude Code",
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "claude",
+    "qa",
+    "testing",
+    "accessibility",
+    "automation",
+    "chrome-devtools",
+    "web-testing"
+  ],
+  "author": "ironclawdevs",
+  "license": "MIT",
+  "homepage": "https://argus-qa.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ironclawdevs27/Argus.git"
+  },
+  "files": [
+    "src/",
+    ".mcp.json"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "bin": {
+    "argus": "src/cli/init.js",
+    "argus-mcp": "src/mcp-server.js",
+    "argusqa-os": "src/mcp-server.js"
+  },
+  "scripts": {
+    "setup": "node -e \"import('fs').then(fs => fs.default.mkdirSync('./reports', { recursive: true }))\"",
+    "init": "node src/cli/init.js",
+    "crawl": "node src/orchestration/crawl-and-report.js",
+    "compare": "node src/orchestration/env-comparison.js",
+    "watch": "node src/orchestration/watch-mode.js",
+    "server": "node src/server/index.js",
+    "harness": "node test-harness/server.js",
+    "harness:staging": "PORT=3101 node test-harness/server.js",
+    "test:harness": "node test-harness/validate.js",
+    "test:unit": "vitest run test/unit",
+    "test": "npm run test:unit && npm run test:harness",
+    "report:html": "node src/utils/html-reporter.js",
+    "mcp-server": "node src/mcp-server.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@opentelemetry/api": "^1.9.1",
+    "@opentelemetry/sdk-node": "^0.218.0",
+    "@slack/web-api": "^7.3.4",
+    "chrome": "^0.1.0",
+    "dotenv": "^16.4.5",
+    "express": "^4.19.2",
+    "pino": "^10.3.1",
+    "pino-pretty": "^13.1.3",
+    "pixelmatch": "^5.3.0",
+    "pngjs": "^7.0.0",
+    "sharp": "^0.33.4",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "vitest": "^4.1.7"
+  }
+}

package/src/adapters/browser.js

@@ -0,0 +1,82 @@
+/**
+ * CdpBrowserAdapter — facade over chrome-devtools-mcp.
+ *
+ * All analyzer modules call browser.* methods instead of mcp.* directly.
+ * This single file is the only place that knows the chrome-devtools-mcp
+ * API shape, so any future API change (parameter renames, new tool versions)
+ * requires editing exactly one file.
+ *
+ * listConsole() and listNetwork() parse the markdown-text format that
+ * chrome-devtools-mcp@latest returns, so callers always receive structured
+ * arrays rather than raw text.
+ *
+ * listConsoleRaw(args) passes arbitrary args through unparsed — used by
+ * issues-analyzer.js which calls list_console_messages({ types: ['issue'] }).
+ */
+
+import { parseConsoleMsgResponse, parseNetworkReqResponse } from '../utils/mcp-parsers.js';
+import { withRetry } from '../utils/retry.js';
+
+export class CdpBrowserAdapter {
+  constructor(mcp) { this._mcp = mcp; }
+
+  // ── Navigation ──────────────────────────────────────────────────────────────
+  navigate(url)            { return withRetry(() => this._mcp.navigate_page({ url }), { label: `navigate(${url})` }); }
+
+  // ── Evaluation & snapshots ──────────────────────────────────────────────────
+  evaluate(fn)             { return this._mcp.evaluate_script({ function: fn }); }
+  snapshot()               { return this._mcp.take_snapshot(); }
+  screenshot(opts = {})    { return this._mcp.take_screenshot(opts); }
+  heapSnapshot(opts = {})  { return this._mcp.take_memory_snapshot(opts); }
+
+  // ── Interactions ────────────────────────────────────────────────────────────
+  // click is intentionally NOT retried — it is not idempotent (submits forms,
+  // toggles state, triggers deletions). A retry after an ambiguous MCP timeout
+  // cannot distinguish "Chrome never received the click" from "Chrome processed
+  // it but the pipe dropped the response" — firing twice causes duplicate actions.
+  click(uid)               { return this._mcp.click({ uid }); }
+  fill(uid, value)         { return withRetry(() => this._mcp.fill({ uid, value }), { label: `fill(${uid})` }); }
+  type(text)               { return this._mcp.type_text({ text }); }
+  pressKey(key)            { return this._mcp.press_key({ key }); }
+  hover(uid)               { return this._mcp.hover({ uid }); }
+  drag(src, tgt)           { return this._mcp.drag({ from_uid: src, to_uid: tgt }); }
+  uploadFile(uid, filePath) { return this._mcp.upload_file({ uid, filePath }); }
+  handleDialog(accept, promptText = '') { return this._mcp.handle_dialog({ accept, promptText }); }
+  waitFor(opts)            { return this._mcp.wait_for(opts); }
+
+  // ── Viewport ────────────────────────────────────────────────────────────────
+  emulate(viewport)        { return this._mcp.emulate({ viewport }); }
+  emulateCpu(rate)         { return this._mcp.emulate_cpu({ throttlingRate: rate }); }
+  resize(w, h)             { return this._mcp.resize_page({ width: w, height: h }); }
+
+  // ── Network & performance ───────────────────────────────────────────────────
+  getNetworkRequest(reqId) { return this._mcp.get_network_request({ requestId: reqId }); }
+  lighthouse(url, opts = {}) { return this._mcp.lighthouse_audit({ url, ...opts }); }
+  startTrace()             { return this._mcp.performance_start_trace({}); }
+  stopTrace()              { return this._mcp.performance_stop_trace({}); }
+  analyzeInsight(opts)     { return this._mcp.performance_analyze_insight(opts); }
+
+  // ── Lifecycle ───────────────────────────────────────────────────────────────
+  close()                  { return this._mcp.close(); }
+
+  // ── Console & network lists (text-parsed) ───────────────────────────────────
+
+  /** Returns structured array from list_console_messages (parses markdown text). */
+  async listConsole() {
+    const raw = await this._mcp.list_console_messages({});
+    return parseConsoleMsgResponse(raw);
+  }
+
+  /** Returns structured array from list_network_requests (parses markdown text). */
+  async listNetwork() {
+    const raw = await this._mcp.list_network_requests({});
+    return parseNetworkReqResponse(raw);
+  }
+
+  /**
+   * Raw pass-through to list_console_messages with custom args.
+   * Used by issues-analyzer.js for the DevTools Issues panel
+   * (types: ['issue']) which returns structured data, not text.
+   */
+  listConsoleRaw(args = {}) { return this._mcp.list_console_messages(args); }
+}

package/src/argus.js

@@ -0,0 +1,8 @@
+/**
+ * Argus — single-page audit entry point.
+ * Re-exports the main crawl pipeline from crawl-and-report.js.
+ * Run via: npm run crawl  (or node src/argus.js)
+ *
+ * Config validation (Zod) runs inside runCrawl() — src/config/schema.js.
+ */
+export * from './orchestration/crawl-and-report.js';

package/src/batch-runner.js

@@ -0,0 +1,8 @@
+/**
+ * Argus — multi-page batch audit entry point.
+ * Re-exports the main crawl pipeline from crawl-and-report.js.
+ * Run via: node src/batch-runner.js
+ *
+ * Config validation (Zod) runs inside runCrawl() — src/config/schema.js.
+ */
+export * from './orchestration/crawl-and-report.js';

package/src/cli/init.js

@@ -0,0 +1,314 @@
+#!/usr/bin/env node
+/**
+ * Argus Phase C4 — argus init CLI
+ *
+ * Guides first-time Argus setup against a target app:
+ *   1. Collect target URLs
+ *   2. Detect framework from source dir (Next.js / React Router / unknown)
+ *   3. Auto-discover routes using C3 route-discoverer
+ *   4. Prompt for Slack + GitHub config (fully optional)
+ *   5. Write .env with collected values
+ *   6. Write src/config/targets.js pre-filled with discovered routes
+ *
+ * Pure helpers (detectFramework, generateTargetsJs, generateEnvFile) are
+ * exported so the test harness can unit-test them without side effects.
+ * The interactive main() only runs when this file is the process entry point.
+ */
+
+import fs   from 'fs';
+import path from 'path';
+import readline from 'readline';
+import { fileURLToPath } from 'url';
+import { discoverRoutes } from '../utils/route-discoverer.js';
+import { childLogger } from '../utils/logger.js';
+
+const logger = childLogger('init');
+
+const __filename = fileURLToPath(import.meta.url);
+
+// ── C4.1  Framework detection ─────────────────────────────────────────────────
+
+/**
+ * Detect the frontend framework used in the given project root by reading its
+ * package.json.  Returns 'nextjs', 'react-router', or 'unknown'.
+ *
+ * @param {string} projectRoot  absolute path to the target app root
+ * @returns {'nextjs' | 'react-router' | 'unknown'}
+ */
+export function detectFramework(projectRoot) {
+  if (!projectRoot || !fs.existsSync(projectRoot)) return 'unknown';
+  const pkgPath = path.join(projectRoot, 'package.json');
+  if (!fs.existsSync(pkgPath)) return 'unknown';
+  let pkg;
+  try { pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8')); } catch { return 'unknown'; }
+  const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+  if (deps['next'])                                          return 'nextjs';
+  if (deps['react-router-dom'] || deps['react-router'])     return 'react-router';
+  return 'unknown';
+}
+
+// ── C4.2  targets.js generator ────────────────────────────────────────────────
+
+/**
+ * Generate a pre-filled src/config/targets.js from discovered routes.
+ *
+ * @param {Array<{path:string, name:string, critical:boolean, waitFor:string|null}>} routes
+ * @param {{ framework?: string, sourceDir?: string|null, envFile?: string|null }} options
+ * @returns {string}
+ */
+export function generateTargetsJs(routes, options = {}) {
+  const { framework = 'unknown', sourceDir = null, envFile = null } = options;
+
+  // Escape for single-quoted JS string literals: backslash → \\ , CR → \r , LF → \n , ' → \'
+  const esc = s => String(s ?? '').replace(/\\/g, '\\\\').replace(/\r/g, '\\r').replace(/\n/g, '\\n').replace(/'/g, "\\'");
+  const routeLines = routes.length
+    ? routes.map(r => {
+        const wf = r.waitFor ? `'${esc(r.waitFor)}'` : 'null';
+        return `  { path: '${esc(r.path)}', name: '${esc(r.name)}', critical: ${!!r.critical}, waitFor: ${wf} },`;
+      }).join('\n')
+    : `  { path: '/', name: 'Home', critical: true, waitFor: 'main' },`;
+
+  const autoDiscoverComment =
+    framework === 'nextjs'
+      ? '// Next.js detected — nextjs discovery enabled'
+      : framework === 'react-router'
+        ? '// React Router detected — reactRouter discovery enabled (experimental)'
+        : '// Set sitemap: true to fetch /sitemap.xml from TARGET_DEV_URL';
+
+  const sourceDirVal = sourceDir
+    ? `process.env.ARGUS_SOURCE_DIR ?? '${sourceDir}'`
+    : `process.env.ARGUS_SOURCE_DIR ?? null`;
+  const envFileVal = envFile
+    ? `process.env.ARGUS_ENV_FILE ?? '${envFile}'`
+    : `process.env.ARGUS_ENV_FILE ?? null`;
+
+  return `/**
+ * ARGUS Target Configuration — generated by argus init
+ *
+ * Edit to add routes, flows, and API contracts.
+ * Run \`npm run crawl\` to start auditing.
+ */
+
+export const config = {
+  pageSettleMs: 2000,
+  screenshotQuality: 90,
+  screenshotDiffThreshold: parseFloat(process.env.SCREENSHOT_DIFF_THRESHOLD ?? '0.5'),
+  outputDir: process.env.REPORT_OUTPUT_DIR ?? './reports',
+};
+
+export const routes = [
+${routeLines}
+];
+
+export const comparisonRoutes = routes.filter(r => r.critical);
+
+export const apiContracts = [];
+
+export const severityOverrides = {};
+
+export const auth = null;
+
+export const flows = [];
+
+export const codebase = {
+  sourceDir: ${sourceDirVal},
+  envFile:   ${envFileVal},
+};
+
+${autoDiscoverComment}
+export const autoDiscover = {
+  sitemap:     true,
+  nextjs:      ${framework === 'nextjs'},
+  reactRouter: ${framework === 'react-router'},
+};
+`;
+}
+
+// ── C4.3  .env generator ──────────────────────────────────────────────────────
+
+/**
+ * Generate a .env file with user-supplied configuration values substituted in.
+ * Any field that is blank/falsy is rendered as a commented-out placeholder.
+ *
+ * @param {{ devUrl?:string, stagingUrl?:string, slackToken?:string,
+ *           slackSecret?:string, slackCritical?:string, slackWarnings?:string,
+ *           slackDigest?:string, githubToken?:string, githubRepo?:string,
+ *           sourceDir?:string, envFile?:string }} options
+ * @returns {string}
+ */
+export function generateEnvFile(options = {}) {
+  const {
+    devUrl       = 'http://localhost:3000',
+    stagingUrl   = '',
+    slackToken   = '',
+    slackSecret  = '',
+    slackCritical = '',
+    slackWarnings = '',
+    slackDigest  = '',
+    githubToken  = '',
+    githubRepo   = '',
+    sourceDir    = '',
+    envFile      = '',
+  } = options;
+
+  const stagingLine = stagingUrl
+    ? `TARGET_STAGING_URL=${stagingUrl}`
+    : `# TARGET_STAGING_URL=`;
+
+  const slackSection = slackToken
+    ? `SLACK_BOT_TOKEN=${slackToken}
+SLACK_SIGNING_SECRET=${slackSecret}
+SLACK_CHANNEL_CRITICAL=${slackCritical}
+SLACK_CHANNEL_WARNINGS=${slackWarnings}
+${slackDigest ? `SLACK_CHANNEL_DIGEST=${slackDigest}` : '# SLACK_CHANNEL_DIGEST='}`
+    : `# SLACK_BOT_TOKEN=xoxb-...
+# SLACK_SIGNING_SECRET=...
+# SLACK_CHANNEL_CRITICAL=
+# SLACK_CHANNEL_WARNINGS=
+# SLACK_CHANNEL_DIGEST=`;
+
+  const githubSection = githubToken
+    ? `GITHUB_TOKEN=${githubToken}
+GITHUB_REPOSITORY=${githubRepo}`
+    : `# GITHUB_TOKEN=ghp_...
+# GITHUB_REPOSITORY=owner/repo`;
+
+  const sourceDirLine = sourceDir ? `ARGUS_SOURCE_DIR=${sourceDir}` : `# ARGUS_SOURCE_DIR=../my-app/src`;
+  const envFileLine   = envFile   ? `ARGUS_ENV_FILE=${envFile}`     : `# ARGUS_ENV_FILE=../my-app/.env`;
+
+  return `# Argus configuration — generated by argus init
+
+# Target URLs (required)
+TARGET_DEV_URL=${devUrl}
+${stagingLine}
+
+# Slack (optional — omit entirely to use local report.html instead)
+${slackSection}
+
+# GitHub PR integration (optional)
+${githubSection}
+
+# Codebase analysis + route discovery (optional — enables C1 + C3)
+${sourceDirLine}
+${envFileLine}
+
+# Auth credentials (only needed when auth is configured in targets.js)
+# ARGUS_AUTH_EMAIL=qa@example.com
+# ARGUS_AUTH_PASSWORD=...
+
+# Output settings
+REPORT_OUTPUT_DIR=./reports
+SCREENSHOT_DIFF_THRESHOLD=0.5
+`;
+}
+
+// ── C4.4  Interactive setup wizard ────────────────────────────────────────────
+
+function createPrompter() {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const ask = q => new Promise(res => rl.question(q, res));
+  return { ask, close: () => rl.close() };
+}
+
+const tick   = msg => process.stdout.write(`  ✓ ${msg}\n`);
+const note   = msg => process.stdout.write(`  ${msg}\n`);
+const step   = msg => process.stdout.write(`\n▶ ${msg}\n`);
+
+async function main() {
+  process.stdout.write('\n');
+  process.stdout.write('  ╔' + '═'.repeat(42) + '╗\n');
+  process.stdout.write('  ║     Argus init — first-time setup         ║\n');
+  process.stdout.write('  ╚' + '═'.repeat(42) + '╝\n\n');
+
+  const { ask, close } = createPrompter();
+
+  try {
+    // Step 1 — Target URLs
+    step('Step 1/4 — Target URLs');
+    const devUrl    = (await ask('  Dev URL [http://localhost:3000]: ')).trim() || 'http://localhost:3000';
+    const stagingUrl = (await ask('  Staging URL (blank to skip): ')).trim();
+
+    // Step 2 — Source code
+    step('Step 2/4 — Source Code (enables C1 env-var audit + C3 file-system discovery)');
+    const rawSourceDir = (await ask('  App source directory (blank to skip): ')).trim();
+    const sourceDir    = rawSourceDir ? path.resolve(rawSourceDir) : '';
+    const rawEnvFile   = (await ask('  App .env file (blank to skip): ')).trim();
+    const envFilePath  = rawEnvFile   ? path.resolve(rawEnvFile)   : '';
+
+    // Step 3 — Route discovery
+    step('Step 3/4 — Route Discovery');
+
+    const framework = sourceDir ? detectFramework(sourceDir) : 'unknown';
+    if (sourceDir) note(`Detected framework: ${framework}`);
+
+    const autoDiscoverConfig = {
+      sitemap:     true,
+      nextjs:      framework === 'nextjs',
+      reactRouter: framework === 'react-router',
+    };
+
+    const seedRoutes = [
+      { path: '/',      name: 'Home',  critical: true,  waitFor: 'main' },
+      { path: '/login', name: 'Login', critical: true,  waitFor: 'form' },
+    ];
+
+    note('Discovering routes (sitemap + framework structure)...');
+    let finalRoutes;
+    try {
+      finalRoutes = await discoverRoutes(devUrl, sourceDir || null, autoDiscoverConfig, seedRoutes);
+      const added = finalRoutes.filter(r => r.discovered).length;
+      tick(`Found ${finalRoutes.length} route(s) total (${added} auto-discovered)`);
+    } catch (err) {
+      note(`Route discovery skipped (${err.message}) — using seed routes`);
+      finalRoutes = seedRoutes;
+    }
+
+    // Step 4 — Slack + GitHub
+    step('Step 4/4 — Slack & GitHub (press Enter to skip each)');
+    const slackToken = (await ask('  Slack bot token (xoxb-..., blank to skip): ')).trim();
+    let slackSecret = '', slackCritical = '', slackWarnings = '', slackDigest = '';
+    if (slackToken) {
+      slackSecret   = (await ask('  Slack signing secret: ')).trim();
+      slackCritical = (await ask('  Slack critical channel ID (C...): ')).trim();
+      slackWarnings = (await ask('  Slack warnings channel ID (C...): ')).trim();
+      slackDigest   = (await ask('  Slack digest channel ID (C...): ')).trim();
+    }
+    const githubToken = (await ask('  GitHub token (ghp_..., blank to skip): ')).trim();
+    let githubRepo = '';
+    if (githubToken) {
+      githubRepo = (await ask('  GitHub repository (owner/repo): ')).trim();
+    }
+
+    // Write files
+    process.stdout.write('\n');
+
+    const envContent     = generateEnvFile({ devUrl, stagingUrl, slackToken, slackSecret,
+                                             slackCritical, slackWarnings, slackDigest,
+                                             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');
+      tick('Wrote .env');
+    }
+
+    const targetsPath = path.join('src', 'config', 'targets.js');
+    fs.mkdirSync(path.dirname(targetsPath), { recursive: true });
+    fs.writeFileSync(targetsPath, targetsContent, 'utf8');
+    tick(`Wrote ${targetsPath}`);
+
+    process.stdout.write('\n');
+    process.stdout.write('  ╔' + '═'.repeat(48) + '╗\n');
+    process.stdout.write('  ║  Done! Run `npm run crawl` to start auditing.  ║\n');
+    process.stdout.write('  ╚' + '═'.repeat(48) + '╝\n\n');
+
+  } finally {
+    close();
+  }
+}
+
+if (process.argv[1] === __filename) {
+  main().catch(err => { console.error('argus init failed:', err.message); process.exit(1); });
+}

package/src/config/schema.js

@@ -0,0 +1,108 @@
+/**
+ * Argus Config Schema (v9.1.6)
+ *
+ * Zod validation for src/config/targets.js exports.
+ * Called at startup (before any crawl begins) so misconfiguration is caught
+ * immediately with a clear error rather than a silent runtime failure mid-crawl.
+ *
+ * Usage:
+ *   import * as targets from './config/targets.js';
+ *   import { validateConfig } from './config/schema.js';
+ *   validateConfig(targets);
+ */
+
+import { z } from 'zod';
+
+// ── Route ─────────────────────────────────────────────────────────────────────
+
+const RouteSchema = z.object({
+  path:       z.string().startsWith('/'),
+  name:       z.string().min(1),
+  critical:   z.boolean().optional(),
+  waitFor:    z.string().nullable().optional(),
+  discovered: z.boolean().optional(),
+}).passthrough();
+
+// ── Thresholds ────────────────────────────────────────────────────────────────
+
+const LighthouseCategorySchema = z.object({
+  critical: z.number().min(0).max(100),
+  warning:  z.number().min(0).max(100),
+});
+
+const ThresholdsSchema = z.object({
+  perf: z.object({
+    LCP:  z.number().positive(),
+    CLS:  z.number().positive(),
+    FID:  z.number().positive(),
+    TTFB: z.number().positive(),
+  }),
+  network: z.object({
+    slowWarning:  z.number().positive(),
+    slowCritical: z.number().positive(),
+    sizeWarning:  z.number().positive(),
+    sizeCritical: z.number().positive(),
+  }),
+  memory: z.object({
+    detachedWarning:    z.number().nonnegative(),
+    detachedCritical:   z.number().nonnegative(),
+    heapGrowthWarning:  z.number().nonnegative(),
+    heapGrowthCritical: z.number().nonnegative(),
+  }),
+  hover: z.object({
+    waitMs:       z.number().nonnegative(),
+    maxDropdowns: z.number().int().positive(),
+    maxTooltips:  z.number().int().positive(),
+  }),
+  security: z.object({
+    headTimeoutMs: z.number().positive(),
+  }),
+  apiFrequency: z.object({
+    warningCount:  z.number().int().positive(),
+    criticalCount: z.number().int().positive(),
+  }),
+  lighthouse: z.object({
+    accessibility:    LighthouseCategorySchema,
+    performance:      LighthouseCategorySchema,
+    seo:              LighthouseCategorySchema,
+    'best-practices': LighthouseCategorySchema,
+  }),
+});
+
+// ── Top-level Config ──────────────────────────────────────────────────────────
+
+export const ConfigSchema = z.object({
+  config: z.object({
+    pageSettleMs:            z.number().positive(),
+    screenshotQuality:       z.number().min(1).max(100).optional(),
+    screenshotDiffThreshold: z.number().min(0).optional(),
+    outputDir:               z.string().optional(),
+  }).passthrough(),
+  routes:            z.array(RouteSchema),
+  thresholds:        ThresholdsSchema,
+  comparisonRoutes:  z.array(z.any()).optional(),
+  apiContracts:      z.array(z.any()).optional(),
+  severityOverrides: z.record(z.string()).optional(),
+  auth:              z.any().nullable().optional(),
+  flows:             z.array(z.any()).optional(),
+  codebase:          z.any().nullable().optional(),
+  autoDiscover:      z.any().nullable().optional(),
+}).passthrough();
+
+// ── Public API ────────────────────────────────────────────────────────────────
+
+/**
+ * Validate the targets.js namespace against ConfigSchema.
+ * Throws a descriptive Error (wrapping the ZodError) on any schema violation.
+ *
+ * @param {object} targets - The targets.js module namespace (import * as targets)
+ */
+export function validateConfig(targets) {
+  const result = ConfigSchema.safeParse(targets);
+  if (!result.success) {
+    const issues = result.error.issues
+      .map(i => `  ${i.path.join('.')}: ${i.message}`)
+      .join('\n');
+    throw new Error(`[ARGUS] Invalid targets.js configuration:\n${issues}`);
+  }
+}