@vertaaux/cli 0.2.0

package/dist/commands/audit.js

@@ -0,0 +1,862 @@
+/**
+ * Audit command for VertaaUX CLI.
+ *
+ * Runs UX and accessibility audits on web pages.
+ * Supports various targets, output formats, and CI integration.
+ */
+import fs from "fs";
+import path from "path";
+import { resolveConfig } from "../config/loader.js";
+import { ExitCode } from "../utils/exit-codes.js";
+import { parseTimeout, parseInterval, parseConcurrency, parseThreshold, parseMode, parseFailOn, parseGroupBy, parseBudget, validateNumeric, } from "../utils/validators.js";
+import { isTTY } from "../utils/detect-env.js";
+import { resolveApiBase, getApiKey, apiRequest, waitForAudit, } from "../utils/client.js";
+import { createOutput, formatSarif, formatAuditHtml } from "../output/factory.js";
+import { createEnvelope, writeJsonOutput, writeOutput as writeStdout } from "../output/envelope.js";
+import { resolveCommandFormat } from "../output/formats.js";
+import { createSpinner, updateSpinner, succeedSpinner, failSpinner, } from "../ui/spinner.js";
+import { runFixWizard } from "../interactive/fix-wizard.js";
+import { isInteractive } from "../interactive/prompts.js";
+import { evaluateQualityGate, DEFAULT_QUALITY_GATE_CONFIG, } from "../quality-gate/index.js";
+import { loadBaseline } from "../baseline/manager.js";
+import { getChangedRoutes, detectBaseBranch, getBudgetConfig, } from "../ci/index.js";
+import { loadPolicy, resolveBranchPolicy, } from "../policy/index.js";
+import { detectMonorepo, getAuditableApps, generateMatrixConfig, aggregateResults, formatAggregatedResults, } from "../monorepo/index.js";
+import { createLogger } from "../utils/logger.js";
+import { validateBranchName, assertPathContainment } from "../utils/sanitize.js";
+import chalk from "chalk";
+import semver from "semver";
+// Artifact directory
+const ARTIFACTS_DIR = ".vertaaux/artifacts";
+// CLI version for policy version requirements
+const CLI_VERSION = "0.1.0";
+/**
+ * Detect current branch from CI environment or git.
+ */
+function detectCurrentBranch() {
+    // GitHub Actions
+    if (process.env.GITHUB_HEAD_REF) {
+        return process.env.GITHUB_HEAD_REF;
+    }
+    if (process.env.GITHUB_REF_NAME) {
+        return process.env.GITHUB_REF_NAME;
+    }
+    // GitLab CI
+    if (process.env.CI_COMMIT_REF_NAME) {
+        return process.env.CI_COMMIT_REF_NAME;
+    }
+    // Azure DevOps
+    if (process.env.BUILD_SOURCEBRANCHNAME) {
+        return process.env.BUILD_SOURCEBRANCHNAME;
+    }
+    // CircleCI
+    if (process.env.CIRCLE_BRANCH) {
+        return process.env.CIRCLE_BRANCH;
+    }
+    // Jenkins
+    if (process.env.GIT_BRANCH) {
+        // Jenkins often includes origin/, remove it
+        return process.env.GIT_BRANCH.replace(/^origin\//, "");
+    }
+    // Generic CI
+    if (process.env.BRANCH_NAME) {
+        return process.env.BRANCH_NAME;
+    }
+    // Default
+    return "";
+}
+/**
+ * Detect PR labels from CI environment variables.
+ *
+ * Supports:
+ * - GitHub Actions: GITHUB_EVENT_PATH contains event JSON with labels
+ * - GitLab CI: CI_MERGE_REQUEST_LABELS is comma-separated
+ */
+function detectPRLabels() {
+    // GitHub Actions: GITHUB_EVENT_PATH contains event JSON with labels
+    if (process.env.GITHUB_EVENT_PATH) {
+        try {
+            const eventContent = fs.readFileSync(process.env.GITHUB_EVENT_PATH, "utf-8");
+            const event = JSON.parse(eventContent);
+            const labels = event.pull_request?.labels;
+            if (Array.isArray(labels)) {
+                return labels.map((l) => l.name || "").filter(Boolean);
+            }
+        }
+        catch {
+            // Ignore errors reading event file
+        }
+    }
+    // GitLab CI: CI_MERGE_REQUEST_LABELS is comma-separated
+    if (process.env.CI_MERGE_REQUEST_LABELS) {
+        return process.env.CI_MERGE_REQUEST_LABELS.split(",")
+            .map((l) => l.trim())
+            .filter(Boolean);
+    }
+    return [];
+}
+/**
+ * Build quality gate configuration from options and config.
+ */
+function buildQualityGateConfig(config, options) {
+    // Start with defaults
+    const gateConfig = { ...DEFAULT_QUALITY_GATE_CONFIG };
+    // Apply config file settings
+    const configGate = config.qualityGate;
+    if (configGate) {
+        if (configGate.failOn)
+            gateConfig.failOn = configGate.failOn;
+        if (configGate.thresholds) {
+            gateConfig.thresholds = { ...gateConfig.thresholds, ...configGate.thresholds };
+        }
+        if (configGate.maxNew) {
+            gateConfig.maxNew = { ...gateConfig.maxNew, ...configGate.maxNew };
+        }
+        if (configGate.failOnExisting !== undefined) {
+            gateConfig.failOnExisting = configGate.failOnExisting;
+        }
+        if (configGate.bypassLabels) {
+            gateConfig.bypassLabels = configGate.bypassLabels;
+        }
+    }
+    // Apply CLI flags (highest precedence)
+    if (options.failOn) {
+        gateConfig.failOn = options.failOn;
+    }
+    if (options.threshold !== undefined) {
+        gateConfig.thresholds.overall = options.threshold;
+    }
+    if (options.maxNewErrors !== undefined) {
+        gateConfig.maxNew.error = options.maxNewErrors;
+    }
+    if (options.maxNewWarnings !== undefined) {
+        gateConfig.maxNew.warning = options.maxNewWarnings;
+    }
+    if (options.failOnExisting !== undefined) {
+        gateConfig.failOnExisting = options.failOnExisting;
+    }
+    if (options.bypassLabels) {
+        gateConfig.bypassLabels = options.bypassLabels.split(",").map((l) => l.trim());
+    }
+    return gateConfig;
+}
+/**
+ * Normalize issues from various API response formats.
+ */
+function normalizeIssues(issues) {
+    if (Array.isArray(issues))
+        return issues;
+    if (issues && typeof issues === "object") {
+        const values = Object.values(issues);
+        return values.flatMap((value) => Array.isArray(value) ? value : []);
+    }
+    return [];
+}
+/**
+ * Filter issues by severity.
+ */
+function filterBySeverity(issues, severityFilter) {
+    const allowed = new Set(severityFilter.split(",").map((s) => s.trim().toLowerCase()));
+    // Map common aliases
+    if (allowed.has("error"))
+        allowed.add("critical");
+    if (allowed.has("warning"))
+        allowed.add("serious");
+    return issues.filter((issue) => {
+        const sev = issue.severity?.toLowerCase() || "info";
+        return allowed.has(sev);
+    });
+}
+/**
+ * Filter issues by category.
+ */
+function filterByCategory(issues, categoryFilter) {
+    const allowed = new Set(categoryFilter.split(",").map((c) => c.trim().toLowerCase()));
+    return issues.filter((issue) => {
+        const cat = issue.category?.toLowerCase() || "";
+        return allowed.has(cat) || Array.from(allowed).some((a) => cat.includes(a));
+    });
+}
+/**
+ * Write output to file. Returns the resolved path if written to file, undefined otherwise.
+ */
+function writeOutputToFile(content, outputPath, defaultPath) {
+    // Determine the final output path
+    const finalPath = outputPath || defaultPath;
+    if (finalPath) {
+        // Write to file
+        const resolvedPath = path.resolve(process.cwd(), finalPath);
+        // Ensure directory exists
+        const dir = path.dirname(resolvedPath);
+        if (!fs.existsSync(dir)) {
+            fs.mkdirSync(dir, { recursive: true });
+        }
+        fs.writeFileSync(resolvedPath, content, "utf-8");
+        return resolvedPath;
+    }
+    return undefined;
+}
+/**
+ * Get default output path based on format.
+ * Returns undefined for formats that should go to stdout by default.
+ */
+function getDefaultOutputPath(format) {
+    switch (format) {
+        case "html":
+            return "vertaaux-report.html";
+        default:
+            return undefined;
+    }
+}
+/**
+ * Save repro artifacts from API response.
+ */
+function saveReproArtifacts(jobId, response, options, quiet) {
+    const hasArtifactOptions = options.saveTrace || options.saveHar || options.screenshots || options.domSnapshots;
+    if (!hasArtifactOptions)
+        return;
+    // Create artifacts directory
+    const artifactsPath = path.resolve(process.cwd(), ARTIFACTS_DIR, jobId);
+    // Check if API response includes artifact data
+    const responseAny = response;
+    const artifacts = responseAny.artifacts;
+    if (!artifacts) {
+        if (!quiet) {
+            console.error("Note: Repro artifacts were requested but not available in API response.");
+            console.error("Artifact capture may require a 'deep' mode audit or premium plan.");
+        }
+        return;
+    }
+    // Ensure directory exists
+    if (!fs.existsSync(artifactsPath)) {
+        fs.mkdirSync(artifactsPath, { recursive: true });
+    }
+    const saved = [];
+    // Save trace file if available and requested
+    if (options.saveTrace && artifacts.trace) {
+        const tracePath = path.join(artifactsPath, "trace.zip");
+        fs.writeFileSync(tracePath, Buffer.from(artifacts.trace, "base64"));
+        saved.push("trace.zip");
+    }
+    // Save HAR file if available and requested
+    if (options.saveHar && artifacts.har) {
+        const harPath = path.join(artifactsPath, "network.har");
+        fs.writeFileSync(harPath, typeof artifacts.har === "string" ? artifacts.har : JSON.stringify(artifacts.har, null, 2));
+        saved.push("network.har");
+    }
+    // Save screenshots if available and requested
+    if (options.screenshots && artifacts.screenshots) {
+        const screenshots = artifacts.screenshots;
+        for (const screenshot of screenshots) {
+            const screenshotName = screenshot.name || "screenshot.png";
+            let screenshotPath;
+            try {
+                screenshotPath = assertPathContainment(screenshotName, artifactsPath);
+            }
+            catch {
+                console.error(`Security: Rejected screenshot "${screenshotName}" -- path traversal outside artifacts directory.`);
+                continue;
+            }
+            fs.writeFileSync(screenshotPath, Buffer.from(screenshot.data, "base64"));
+            saved.push(screenshotName);
+        }
+    }
+    // Save DOM snapshots if available and requested
+    if (options.domSnapshots && artifacts.domSnapshots) {
+        const snapshots = artifacts.domSnapshots;
+        for (const snapshot of snapshots) {
+            const snapshotName = snapshot.name || "snapshot.html";
+            let snapshotPath;
+            try {
+                snapshotPath = assertPathContainment(snapshotName, artifactsPath);
+            }
+            catch {
+                console.error(`Security: Rejected snapshot "${snapshotName}" -- path traversal outside artifacts directory.`);
+                continue;
+            }
+            fs.writeFileSync(snapshotPath, snapshot.html);
+            saved.push(snapshotName);
+        }
+    }
+    if (saved.length > 0 && !quiet) {
+        console.error(`Artifacts saved to: ${artifactsPath}`);
+        console.error(`  - ${saved.join("\n  - ")}`);
+    }
+}
+/**
+ * Count issues by severity level.
+ */
+function countIssuesBySeverity(issues) {
+    const counts = { error: 0, warning: 0, info: 0 };
+    for (const issue of issues) {
+        const sev = (issue.severity || "info").toLowerCase();
+        if (sev === "error" || sev === "critical") {
+            counts.error++;
+        }
+        else if (sev === "warning" || sev === "serious") {
+            counts.warning++;
+        }
+        else {
+            counts.info++;
+        }
+    }
+    return counts;
+}
+/**
+ * Save CI artifact bundle for GitHub Actions upload.
+ *
+ * Creates a complete evidence bundle:
+ * - results.json: Full audit results
+ * - results.sarif: SARIF for Code Scanning
+ * - report.html: HTML report for viewing
+ * - manifest.json: Metadata about the bundle
+ */
+function saveArtifactBundle(jobId, result, issues, exitCode, quiet) {
+    const artifactsPath = path.resolve(process.cwd(), ARTIFACTS_DIR, jobId);
+    // Ensure directory exists
+    if (!fs.existsSync(artifactsPath)) {
+        fs.mkdirSync(artifactsPath, { recursive: true });
+    }
+    const files = [];
+    // 1. Save JSON results
+    const jsonPath = path.join(artifactsPath, "results.json");
+    fs.writeFileSync(jsonPath, JSON.stringify(result, null, 2), "utf-8");
+    files.push("results.json");
+    // 2. Save SARIF for Code Scanning
+    const sarifContent = formatSarif(result, {
+        workingDirectory: process.cwd(),
+    });
+    const sarifPath = path.join(artifactsPath, "results.sarif");
+    fs.writeFileSync(sarifPath, sarifContent, "utf-8");
+    files.push("results.sarif");
+    // 3. Save HTML report
+    const htmlContent = formatAuditHtml(result, {
+        interactive: true,
+    });
+    const htmlPath = path.join(artifactsPath, "report.html");
+    fs.writeFileSync(htmlPath, htmlContent, "utf-8");
+    files.push("report.html");
+    // 4. Save manifest
+    const manifest = {
+        job_id: jobId,
+        timestamp: new Date().toISOString(),
+        files,
+        audit_url: result.url,
+        issue_count: countIssuesBySeverity(issues),
+        exit_code: exitCode,
+    };
+    const manifestPath = path.join(artifactsPath, "manifest.json");
+    fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2), "utf-8");
+    files.push("manifest.json");
+    if (!quiet) {
+        console.error(`Artifacts saved to: ${artifactsPath}`);
+        console.error(`  - ${files.join("\n  - ")}`);
+    }
+    return artifactsPath;
+}
+/**
+ * Execute the audit command.
+ */
+async function executeAudit(targetUrl, options, config) {
+    // Resolve options with precedence: flags > env > config > defaults
+    const mode = options.mode || config.mode || "basic";
+    const timeout = options.timeout || config.timeout || 60000;
+    const interval = options.interval || config.interval || 5000;
+    const wait = options.wait ?? true; // Default to waiting for completion
+    const quiet = options.quiet ?? false;
+    const interactive = options.interactive ?? false;
+    // Interactive mode validation
+    if (interactive) {
+        if (!wait) {
+            throw new Error("--interactive requires --wait (audit must complete before interactive mode)");
+        }
+        if (!isInteractive()) {
+            throw new Error("Interactive mode requires a terminal. Use --format json in CI or piped environments.");
+        }
+    }
+    // Resolve API settings
+    const base = resolveApiBase(options.base);
+    const apiKey = getApiKey(config.apiKey);
+    // Resolve output format using per-command registry
+    const machineMode = options.machine || false;
+    const explicitFormat = options.format || config.output?.format;
+    const validatedFormat = resolveCommandFormat("audit", explicitFormat, machineMode);
+    const format = validatedFormat;
+    const formatter = createOutput(format);
+    const groupBy = options.groupBy || config.output?.groupBy || "severity";
+    // Create spinner for progress (only in TTY mode with wait)
+    const spinner = wait && isTTY() && !quiet
+        ? createSpinner(`Auditing ${targetUrl}...`)
+        : null;
+    try {
+        // Start spinner
+        spinner?.start();
+        // Create audit job
+        const created = await apiRequest(base, "/audit", {
+            method: "POST",
+            body: { url: targetUrl, mode },
+        }, apiKey);
+        // If not waiting, just output the job info
+        if (!wait) {
+            spinner?.stop();
+            if (format === "json") {
+                if (options.output) {
+                    const output = JSON.stringify(createEnvelope(created, "audit"), null, 2);
+                    const filePath = writeOutputToFile(output, options.output, undefined);
+                    if (filePath && !quiet) {
+                        console.error(`Report written to: ${filePath}`);
+                    }
+                }
+                else {
+                    writeJsonOutput(created, "audit");
+                }
+            }
+            else {
+                const output = formatter.formatResult(created);
+                const defaultPath = getDefaultOutputPath(format);
+                const filePath = writeOutputToFile(output, options.output, defaultPath);
+                if (filePath && !quiet) {
+                    console.error(`Report written to: ${filePath}`);
+                }
+                else if (!filePath) {
+                    writeStdout(output);
+                }
+            }
+            return;
+        }
+        // Wait for completion with progress updates
+        if (!created.job_id) {
+            throw new Error("Audit response missing job_id");
+        }
+        const result = await waitForAudit(base, created.job_id, timeout, interval, apiKey, (progress) => {
+            if (spinner) {
+                updateSpinner(spinner, `Auditing ${targetUrl}`, progress, 100);
+            }
+        });
+        // Stop spinner with success
+        if (spinner) {
+            succeedSpinner(spinner, `Audit complete: ${targetUrl}`);
+        }
+        // Save repro artifacts if requested
+        if (created.job_id) {
+            saveReproArtifacts(created.job_id, result, options, quiet);
+        }
+        // Apply filters to issues
+        let issues = normalizeIssues(result.issues);
+        if (options.severity) {
+            issues = filterBySeverity(issues, options.severity);
+        }
+        if (options.category) {
+            issues = filterByCategory(issues, options.category);
+        }
+        // Create filtered result for output
+        const filteredResult = {
+            ...result,
+            issues,
+        };
+        // Load and apply policy (CICD-17)
+        let resolvedPolicy = null;
+        let policyPath = null;
+        try {
+            const policyResult = await loadPolicy(options.policy ? path.dirname(options.policy) : undefined);
+            if (options.policy) {
+                // User specified a policy file, load it specifically
+                const { loadPolicyFile } = await import("../policy/index.js");
+                resolvedPolicy = await loadPolicyFile(options.policy);
+                policyPath = options.policy;
+            }
+            else if (policyResult.path) {
+                resolvedPolicy = policyResult.policy;
+                policyPath = policyResult.path;
+            }
+            // If policy found, resolve branch-specific overrides
+            if (resolvedPolicy) {
+                const currentBranch = detectCurrentBranch();
+                if (currentBranch) {
+                    resolvedPolicy = resolveBranchPolicy(resolvedPolicy, currentBranch);
+                }
+                if (!quiet && policyPath) {
+                    console.error(chalk.dim(`Using policy: ${policyPath}`));
+                }
+                // Check required CLI version
+                if (resolvedPolicy.required_version) {
+                    if (!semver.satisfies(CLI_VERSION, resolvedPolicy.required_version)) {
+                        console.error(chalk.red(`Policy requires CLI version ${resolvedPolicy.required_version}, ` +
+                            `but current version is ${CLI_VERSION}`));
+                        process.exit(ExitCode.ERROR);
+                    }
+                }
+            }
+        }
+        catch (error) {
+            // Policy loading errors should be reported but not fatal if no explicit policy specified
+            if (options.policy) {
+                throw error; // Re-throw if user explicitly specified a policy
+            }
+            if (!quiet) {
+                console.error(chalk.yellow(`Warning: Failed to load policy: ${error instanceof Error ? error.message : String(error)}`));
+            }
+        }
+        // Build quality gate config and evaluate
+        const gateConfig = buildQualityGateConfig(config, options);
+        // Load baseline if provided
+        const baselinePath = options.baseline || config.baseline?.path;
+        const baseline = baselinePath ? await loadBaseline(baselinePath) : null;
+        // Detect PR labels for bypass check
+        const prLabels = detectPRLabels();
+        // Evaluate quality gate
+        const gateResult = evaluateQualityGate({
+            auditResult: {
+                issues: issues, // Use the normalized issues array
+                scores: result.scores,
+            },
+            baseline,
+            config: gateConfig,
+            labels: prLabels,
+        });
+        // Use quality gate exit code
+        const exitCode = gateResult.exitCode;
+        // Format and output results
+        const formatOptions = {
+            human: {
+                groupBy,
+                showScores: true,
+                showSummary: true,
+            },
+        };
+        if (format === "json") {
+            if (options.output) {
+                const jsonStr = JSON.stringify(createEnvelope(filteredResult, "audit"), null, 2);
+                const filePath = writeOutputToFile(jsonStr, options.output, undefined);
+                if (filePath && !quiet) {
+                    console.error(`Report written to: ${filePath}`);
+                }
+            }
+            else {
+                writeJsonOutput(filteredResult, "audit");
+            }
+        }
+        else {
+            const output = formatter.formatResult(filteredResult, formatOptions);
+            const defaultPath = getDefaultOutputPath(format);
+            const filePath = writeOutputToFile(output, options.output, defaultPath);
+            if (filePath && !quiet) {
+                console.error(`Report written to: ${filePath}`);
+            }
+            else if (!filePath) {
+                writeStdout(output);
+            }
+        }
+        // Output quality gate result
+        if (!quiet) {
+            console.error(""); // Blank line before gate result
+            if (gateResult.bypassed) {
+                console.error(chalk.yellow(`Quality gate bypassed: ${gateResult.bypassReason}`));
+            }
+            else if (gateResult.passed) {
+                console.error(chalk.green("Quality gate: PASSED"));
+            }
+            else {
+                console.error(chalk.red("Quality gate: FAILED"));
+                for (const violation of gateResult.violations) {
+                    console.error(chalk.red(`  - ${violation.message}`));
+                }
+            }
+            // Summary
+            console.error("");
+            console.error(`New issues: ${gateResult.summary.newIssues.error} errors, ` +
+                `${gateResult.summary.newIssues.warning} warnings, ` +
+                `${gateResult.summary.newIssues.info} info`);
+            if (gateResult.summary.fixedIssues > 0) {
+                console.error(chalk.green(`Fixed: ${gateResult.summary.fixedIssues} issues`));
+            }
+            if (gateResult.summary.existingIssues > 0) {
+                console.error(chalk.dim(`Existing (baselined): ${gateResult.summary.existingIssues} issues`));
+            }
+        }
+        // Save CI artifact bundle if requested
+        if (options.uploadArtifacts && created.job_id) {
+            const artifactJobId = options.jobId || created.job_id;
+            saveArtifactBundle(artifactJobId, result, issues, exitCode, quiet);
+        }
+        // Interactive mode: run fix wizard if there are issues
+        if (interactive && issues.length > 0) {
+            await runFixWizard(issues, {
+                jobId: result.job_id,
+                url: targetUrl,
+                base: options.base,
+                config,
+            });
+        }
+        // Set exit code
+        if (exitCode !== ExitCode.SUCCESS) {
+            process.exitCode = exitCode;
+        }
+    }
+    catch (error) {
+        // Stop spinner with failure
+        if (spinner) {
+            failSpinner(spinner, `Audit failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        throw error;
+    }
+}
+/**
+ * Register the audit command with the Commander program.
+ */
+export function registerAuditCommand(program) {
+    program
+        .command("audit [url]")
+        .description("Run UX and accessibility audit")
+        .option("-u, --url <url>", "URL to audit")
+        .option("--repo <repo>", "GitHub repository to audit (owner/repo)")
+        .option("--storybook <url>", "Storybook URL to audit")
+        .option("--routes <routes>", "Comma-separated list of routes to audit")
+        .option("--auth-profile <profile>", "Authentication profile for protected pages")
+        .option("--mode <mode>", "Audit depth: basic|standard|deep", parseMode, "basic")
+        .option("--format <format>", "Output format: json|sarif|junit|html|human|auto")
+        .option("-o, --output <path>", "Output file path")
+        .option("--group-by <field>", "Group issues by: severity|category|route", parseGroupBy)
+        .option("--wait", "Wait for audit completion (default)")
+        .option("--no-wait", "Don't wait for audit completion")
+        .option("--severity <levels>", "Filter issues by severity: error|warning|info (comma-separated)")
+        .option("--category <categories>", "Filter issues by category (comma-separated)")
+        .option("--fail-on <severity>", "Exit 1 if new issues at or above severity: error|warning|info|none", parseFailOn)
+        .option("--threshold <score>", "Exit 3 if overall score below threshold (0-100)", parseThreshold)
+        .option("--max-new-errors <n>", "Maximum allowed new error-severity issues (default: 0)", (v) => validateNumeric(v, "max-new-errors", { min: 0, integer: true }))
+        .option("--max-new-warnings <n>", "Maximum allowed new warning-severity issues (default: unlimited)", (v) => validateNumeric(v, "max-new-warnings", { min: 0, integer: true }))
+        .option("--fail-on-existing", "Also fail on existing issues (legacy mode)")
+        .option("--bypass-labels <labels>", "Comma-separated PR labels that bypass quality gate")
+        .option("--baseline <path>", "Path to baseline file for new issue detection")
+        .option("--timeout <ms>", "Wait timeout in milliseconds (1-300000)", parseTimeout)
+        .option("--interval <ms>", "Poll interval in milliseconds (1-300000)", parseInterval)
+        .option("--interactive", "Step through issues interactively (requires --wait)")
+        // Repro artifact options (CLI-17)
+        .option("--save-trace", "Save Playwright trace for debugging")
+        .option("--save-har", "Save HAR network log")
+        .option("--screenshots", "Save page screenshots")
+        .option("--dom-snapshots", "Save DOM snapshots")
+        // Performance options (CLI-18)
+        .option("--concurrency <n>", "Number of concurrent audits (1-50, default: 3)", parseConcurrency)
+        .option("--cache", "Enable route caching to speed up repeated audits")
+        // CI artifact bundling (CICD-08)
+        .option("--upload-artifacts", "Save all outputs to .vertaaux/artifacts/ for CI upload")
+        .option("--job-id <id>", "Job identifier for artifact directory naming")
+        // Incremental mode (CICD-07)
+        .option("--incremental", "Only audit routes changed in PR")
+        .option("--base-branch <branch>", "Base branch for comparison (default: auto-detect)")
+        // Budget mode (CICD-13)
+        .option("--budget <mode>", "Budget mode: quick|standard|full", parseBudget)
+        // Monorepo options (CICD-16)
+        .option("--workspace <name>", "Audit specific workspace in monorepo")
+        .option("--all-workspaces", "Audit all workspaces in monorepo")
+        .option("--parallel", "Run workspace audits in parallel")
+        .option("--detect-matrix", "Output CI matrix config for monorepo (JSON)")
+        // Caching options (CICD-14)
+        .option("--no-cache", "Disable route caching")
+        .option("--cache-dir <path>", "Custom cache directory")
+        // Logging options (CICD-18)
+        .option("--json-logs", "Output structured JSON logs for CI")
+        // Policy options (CICD-17)
+        .option("--policy <file>", "Path to policy file (default: auto-detect vertaa.policy.yml)")
+        .action(async (urlArg, cmdOptions, command) => {
+        try {
+            // Initialize structured logger
+            const logger = createLogger({
+                json: cmdOptions.jsonLogs || false,
+                level: cmdOptions.quiet ? "error" : "info",
+            });
+            // Load config (supports --config global option)
+            const globalOpts = command.optsWithGlobals();
+            const config = await resolveConfig(globalOpts.config);
+            // Propagate global --machine flag to command options
+            cmdOptions.machine = globalOpts.machine || false;
+            // Handle monorepo detection and matrix output (CICD-16)
+            if (cmdOptions.detectMatrix || cmdOptions.allWorkspaces || cmdOptions.workspace) {
+                const monorepo = await detectMonorepo();
+                if (monorepo.type === "none") {
+                    if (cmdOptions.detectMatrix) {
+                        // Output empty matrix for non-monorepo
+                        process.stdout.write(JSON.stringify({ include: [] }) + "\n");
+                        process.exit(ExitCode.SUCCESS);
+                    }
+                    // Not a monorepo, continue with normal audit
+                }
+                else {
+                    logger.info(`Detected ${monorepo.type} monorepo`, {
+                        workspaces: monorepo.workspaces.length,
+                    });
+                    const apps = getAuditableApps(monorepo);
+                    logger.info(`Found ${apps.length} auditable apps`, {
+                        apps: apps.map((a) => a.name),
+                    });
+                    // Output matrix config for CI
+                    if (cmdOptions.detectMatrix) {
+                        const matrix = generateMatrixConfig(apps);
+                        process.stdout.write(JSON.stringify(matrix) + "\n");
+                        process.exit(ExitCode.SUCCESS);
+                    }
+                    // Audit specific workspace
+                    if (cmdOptions.workspace) {
+                        const workspace = monorepo.workspaces.find((w) => w.name === cmdOptions.workspace);
+                        if (!workspace) {
+                            console.error(`Error: Workspace "${cmdOptions.workspace}" not found`);
+                            console.error(`Available: ${monorepo.workspaces.map((w) => w.name).join(", ")}`);
+                            process.exit(ExitCode.ERROR);
+                        }
+                        // Use workspace URL or infer from type
+                        if (workspace.url) {
+                            urlArg = workspace.url;
+                            logger.info(`Auditing workspace`, { workspace: workspace.name, url: urlArg });
+                        }
+                    }
+                    // Audit all workspaces
+                    if (cmdOptions.allWorkspaces) {
+                        console.error(chalk.dim(`Auditing ${apps.length} workspaces in ${monorepo.type} monorepo`));
+                        const results = [];
+                        const startTime = Date.now();
+                        if (cmdOptions.parallel) {
+                            // Parallel execution
+                            const promises = apps.map(async (app) => {
+                                const wsStartTime = Date.now();
+                                logger.info(`Starting audit`, { workspace: app.name });
+                                try {
+                                    // Note: In production, this would call executeAudit
+                                    // For now, we return a placeholder result
+                                    return {
+                                        workspace: app,
+                                        auditResult: { url: app.url, issues: [], status: "complete" },
+                                        duration: Date.now() - wsStartTime,
+                                    };
+                                }
+                                catch (error) {
+                                    return {
+                                        workspace: app,
+                                        auditResult: null,
+                                        error: error instanceof Error ? error : new Error(String(error)),
+                                        duration: Date.now() - wsStartTime,
+                                    };
+                                }
+                            });
+                            results.push(...(await Promise.all(promises)));
+                        }
+                        else {
+                            // Sequential execution
+                            for (const app of apps) {
+                                const wsStartTime = Date.now();
+                                logger.info(`Auditing workspace`, { workspace: app.name });
+                                try {
+                                    results.push({
+                                        workspace: app,
+                                        auditResult: { url: app.url, issues: [], status: "complete" },
+                                        duration: Date.now() - wsStartTime,
+                                    });
+                                }
+                                catch (error) {
+                                    results.push({
+                                        workspace: app,
+                                        auditResult: null,
+                                        error: error instanceof Error ? error : new Error(String(error)),
+                                        duration: Date.now() - wsStartTime,
+                                    });
+                                }
+                            }
+                        }
+                        // Aggregate and output results
+                        const aggregated = aggregateResults(results);
+                        aggregated.totalDuration = Date.now() - startTime;
+                        if (cmdOptions.format === "json") {
+                            writeJsonOutput(aggregated, "audit");
+                        }
+                        else {
+                            writeStdout(formatAggregatedResults(aggregated));
+                        }
+                        // Exit with error if any failed
+                        if (aggregated.failedAudits > 0) {
+                            process.exit(ExitCode.ERROR);
+                        }
+                        if (aggregated.issuesBySeverity.error > 0) {
+                            process.exit(ExitCode.ISSUES_FOUND);
+                        }
+                        process.exit(ExitCode.SUCCESS);
+                    }
+                }
+            }
+            // Handle incremental mode (CICD-07)
+            if (cmdOptions.incremental) {
+                const baseBranch = validateBranchName(cmdOptions.baseBranch || detectBaseBranch());
+                const changedResult = await getChangedRoutes({
+                    baseBranch,
+                    routePatterns: [], // Use default patterns
+                });
+                if (!changedResult.hasChanges) {
+                    console.error(chalk.green("No relevant route changes detected. Skipping audit."));
+                    process.exit(ExitCode.SUCCESS);
+                }
+                // Log which routes will be audited
+                console.error(chalk.dim(`Incremental mode: Auditing ${changedResult.routes.length} changed routes`));
+                for (const route of changedResult.routes) {
+                    console.error(chalk.dim(`  - ${route}`));
+                }
+                // If routes were detected, use them instead of URL argument
+                if (!config.defaultUrl) {
+                    console.error("Error: --incremental requires defaultUrl in config to construct full URLs.");
+                    process.exit(ExitCode.ERROR);
+                }
+                // Set routes option for executeAudit
+                cmdOptions.routes = changedResult.routes.join(",");
+            }
+            // Handle budget mode (CICD-13)
+            if (cmdOptions.budget) {
+                const budgetConfig = getBudgetConfig(cmdOptions.budget);
+                // Apply budget constraints to options
+                if (!cmdOptions.concurrency) {
+                    cmdOptions.concurrency = budgetConfig.concurrency;
+                }
+                if (!cmdOptions.timeout) {
+                    cmdOptions.timeout = budgetConfig.maxTime;
+                }
+                console.error(chalk.dim(`Budget mode: ${cmdOptions.budget} (max ${budgetConfig.maxPages} pages, ${budgetConfig.maxTime / 1000}s timeout, ${budgetConfig.concurrency} concurrent)`));
+            }
+            // Resolve target URL
+            // Priority: positional > --url > --repo > --storybook > --routes > config default
+            let targetUrl;
+            if (urlArg) {
+                targetUrl = urlArg;
+            }
+            else if (cmdOptions.url) {
+                targetUrl = cmdOptions.url;
+            }
+            else if (cmdOptions.repo) {
+                // For repo audits, construct a special URL or handle differently
+                // For now, we'll just pass it as a marker
+                targetUrl = `repo:${cmdOptions.repo}`;
+            }
+            else if (cmdOptions.storybook) {
+                targetUrl = cmdOptions.storybook;
+            }
+            else if (cmdOptions.routes) {
+                // Routes require a base URL from config
+                if (!config.defaultUrl) {
+                    console.error("Error: --routes requires defaultUrl in config or a base URL.");
+                    process.exit(ExitCode.ERROR);
+                }
+                // For routes, we'll handle them as comma-separated paths
+                const routes = cmdOptions.routes.split(",").map((r) => r.trim());
+                targetUrl = `${config.defaultUrl}${routes[0]}`; // First route for now
+            }
+            else if (config.defaultUrl) {
+                targetUrl = config.defaultUrl;
+            }
+            if (!targetUrl) {
+                console.error("Error: URL is required. Provide as argument, --url flag, or defaultUrl in config.");
+                process.exit(ExitCode.ERROR);
+            }
+            await executeAudit(targetUrl, cmdOptions, config);
+        }
+        catch (error) {
+            console.error("Error:", error instanceof Error ? error.message : String(error));
+            process.exit(ExitCode.ERROR);
+        }
+    });
+}