@vertaaux/cli 0.4.0 → 0.5.0

package/dist/commands/audit.js

@@ -1,1097 +1,2 @@
-/**
- * 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 { getVersion } from "../ui/banner.js";
-import { createSpinner, updateSpinner, succeedSpinner, failSpinner, } from "../ui/spinner.js";
-import { createRenderer, createKeyboardHandler, AuditPhase, phaseIndex, phaseTotal, } from "@vertaaux/tui";
-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 { isLocalUrl } from "../utils/url-classify.js";
-import { captureLocalPage } from "../utils/local-capture.js";
-import chalk from "chalk";
-import semver from "semver";
-// Artifact directory
-const ARTIFACTS_DIR = ".vertaaux/artifacts";
-// CLI version for policy version requirements (read from package.json)
-const CLI_VERSION = getVersion();
-/**
- * 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;
-}
-/**
- * Output results in fire-and-forget mode (--no-wait).
- */
-function outputFireAndForget(created, format, formatter, options, quiet) {
-    if (format === "json") {
-        if (options.output) {
-            const output = JSON.stringify(createEnvelope(created, "audit"), null, 2);
-            const filePath = writeOutputToFile(output, options.output);
-            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);
-        }
-    }
-}
-/**
- * Load and resolve a policy file with branch-specific overrides.
- */
-async function loadAndResolvePolicy(options, quiet) {
-    let resolvedPolicy = null;
-    let policyPath = null;
-    try {
-        const policyResult = await loadPolicy(options.policy ? path.dirname(options.policy) : undefined);
-        if (options.policy) {
-            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 (resolvedPolicy) {
-            const currentBranch = detectCurrentBranch();
-            if (currentBranch) {
-                resolvedPolicy = resolveBranchPolicy(resolvedPolicy, currentBranch);
-            }
-            if (!quiet && policyPath) {
-                console.error(chalk.dim(`Using policy: ${policyPath}`));
-            }
-            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) {
-        if (options.policy) {
-            throw error;
-        }
-        if (!quiet) {
-            console.error(chalk.yellow(`Warning: Failed to load policy: ${error instanceof Error ? error.message : String(error)}`));
-        }
-    }
-    return { policy: resolvedPolicy, path: policyPath };
-}
-/**
- * Run the inline AI explanation for audit issues.
- */
-async function runInlineExplanation(issues, result, targetUrl, options, config) {
-    try {
-        const explainBase = resolveApiBase(options.base);
-        const explainKey = getApiKey(config.apiKey);
-        const explainIssues = issues.map((i) => ({
-            id: i.id || null,
-            title: i.title || i.description || null,
-            description: i.description || null,
-            severity: i.severity || null,
-            category: i.category || null,
-            selector: i.selector || null,
-            wcag_reference: i.wcag_reference || null,
-            recommendation: i.recommendation || i.recommended_fix || null,
-        }));
-        const explainPayload = {
-            job_id: result.job_id || null,
-            url: targetUrl || null,
-            scores: result.scores || null,
-            issues: explainIssues,
-        };
-        const explainSpinner = createSpinner("Generating AI explanation...");
-        const explainResponse = await apiRequest(explainBase, "/cli/ai/explain", { method: "POST", body: { audit: explainPayload } }, explainKey);
-        succeedSpinner(explainSpinner, "Explanation ready");
-        console.error("");
-        console.error(chalk.bold("AI Explanation"));
-        console.error(chalk.dim("─".repeat(40)));
-        for (const bullet of explainResponse.data.summary) {
-            console.error(`  ${chalk.cyan("*")} ${bullet}`);
-        }
-    }
-    catch (explainErr) {
-        console.error(chalk.dim(`\n(AI explanation unavailable: ${explainErr instanceof Error ? explainErr.message : String(explainErr)})`));
-    }
-}
-/**
- * Print quality gate result to stderr.
- */
-function outputQualityGateResult(gateResult) {
-    console.error("");
-    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}`));
-        }
-    }
-    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`));
-    }
-}
-/**
- * Write formatted audit results to output or stdout.
- */
-function outputFormattedResults(filteredResult, format, formatter, groupBy, options, quiet) {
-    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);
-            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);
-        }
-    }
-}
-/**
- * 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
-    // --json flag is a shorthand for --format json (convenient for piping)
-    const machineMode = options.machine || false;
-    const explicitFormat = options.json ? "json" : (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";
-    // Determine UI mode: dashboard (full-screen) vs spinner (inline)
-    const useDashboard = wait && !quiet && !machineMode && options.dashboard !== false;
-    const useSpinner = wait && isTTY() && !quiet && !useDashboard;
-    // Create dashboard renderer or fallback spinner
-    let renderer = null;
-    let keyboard = null;
-    let aborted = false;
-    const spinner = useSpinner
-        ? createSpinner(`Auditing ${targetUrl}...`)
-        : null;
-    if (useDashboard) {
-        renderer = createRenderer("auto");
-        keyboard = createKeyboardHandler();
-        keyboard.on("quit", () => {
-            aborted = true;
-            renderer?.dispose();
-            keyboard?.dispose();
-            process.stderr.write("\nAudit aborted by user.\n");
-            process.exitCode = ExitCode.ERROR;
-        });
-        keyboard.start();
-    }
-    const auditStartTime = Date.now();
-    try {
-        // Start spinner (dashboard renders on first update)
-        spinner?.start();
-        // Route based on URL type: local URLs are captured client-side
-        let created;
-        if (isLocalUrl(targetUrl)) {
-            // Local URL — capture HTML on this machine, send to /analyze
-            if (!quiet) {
-                console.error(chalk.cyan("Local URL detected — capturing page locally..."));
-                console.error(chalk.dim("Note: Local audits use static analysis. Some checks " +
-                    "(keyboard nav, visual hierarchy) are unavailable."));
-            }
-            if (spinner) {
-                updateSpinner(spinner, "Fetching local page...", 10, 100);
-            }
-            let captured;
-            try {
-                captured = await captureLocalPage(targetUrl, { timeoutMs: timeout });
-            }
-            catch (captureErr) {
-                throw new Error(`Cannot reach ${targetUrl}. Ensure your local server is running.\n` +
-                    `  ${captureErr instanceof Error ? captureErr.message : String(captureErr)}`);
-            }
-            if (spinner) {
-                updateSpinner(spinner, "Analyzing captured page...", 40, 100);
-            }
-            created = await apiRequest(base, "/analyze", {
-                method: "POST",
-                body: { html: captured.html, url: targetUrl, mode },
-            }, apiKey);
-        }
-        else {
-            // Public URL — send to cloud API for full audit
-            created = await apiRequest(base, "/audit", {
-                method: "POST",
-                body: { url: targetUrl, mode },
-            }, apiKey);
-        }
-        // If not waiting, just output the job info
-        if (!wait) {
-            spinner?.stop();
-            renderer?.dispose();
-            keyboard?.dispose();
-            outputFireAndForget(created, format, formatter, options, quiet);
-            return;
-        }
-        // Determine if the server returned results synchronously (status 200)
-        // or queued the job for background processing (status 202, legacy servers)
-        const isSyncResponse = created.status === "completed" && created.scores;
-        let result;
-        if (created.status === "failed") {
-            // Server ran the audit synchronously but it failed
-            throw new Error(created.error || "Audit failed on server");
-        }
-        if (isSyncResponse) {
-            // Server already ran the audit — use the response directly
-            result = created;
-        }
-        else {
-            // Legacy/async path: poll for completion
-            if (!created.job_id) {
-                throw new Error("Audit response missing job_id");
-            }
-            result = await waitForAudit(base, created.job_id, timeout, interval, apiKey, (progress, status) => {
-                if (aborted)
-                    return;
-                if (renderer) {
-                    const phase = mapStatusToPhase(status);
-                    const state = {
-                        phase,
-                        phaseIndex: phaseIndex(phase),
-                        phaseTotal: phaseTotal(),
-                        url: targetUrl,
-                        mode,
-                        progress: { audit: progress },
-                        totals: { audit: 100 },
-                        issueCount: 0,
-                        scorePreview: null,
-                        verbose: false,
-                        elapsed: Date.now() - auditStartTime,
-                    };
-                    renderer.update(state);
-                }
-                if (spinner) {
-                    updateSpinner(spinner, `Auditing ${targetUrl}`, progress, 100);
-                }
-            });
-        }
-        // Finish dashboard or spinner
-        if (renderer) {
-            const overallScore = getOverallScoreFromResult(result);
-            const summaryResult = {
-                url: targetUrl,
-                mode,
-                overallScore: overallScore ?? 0,
-                scores: extractNumericScores(result.scores),
-                issueCount: countTotalIssues(result.issues),
-                passed: (overallScore ?? 0) >= 70,
-                elapsed: Date.now() - auditStartTime,
-            };
-            renderer.finish(summaryResult);
-            keyboard?.dispose();
-        }
-        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)
-        await loadAndResolvePolicy(options, quiet);
-        // 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
-        outputFormattedResults(filteredResult, format, formatter, groupBy, options, quiet);
-        // Inline AI explanation (--explain flag, PROG-04)
-        if (options.explain && issues.length > 0) {
-            await runInlineExplanation(issues, result, targetUrl, options, config);
-        }
-        // Output quality gate result
-        if (!quiet) {
-            outputQualityGateResult(gateResult);
-        }
-        // 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 dashboard or spinner with failure
-        renderer?.dispose();
-        keyboard?.dispose();
-        if (spinner) {
-            failSpinner(spinner, `Audit failed: ${error instanceof Error ? error.message : String(error)}`);
-        }
-        throw error;
-    }
-}
-/**
- * Map API audit status to TUI phase name.
- */
-function mapStatusToPhase(status) {
-    switch (status) {
-        case "queued":
-        case "pending":
-            return AuditPhase.Connecting;
-        case "crawling":
-            return AuditPhase.Crawling;
-        case "running":
-        case "analyzing":
-            return AuditPhase.Analyzing;
-        case "scoring":
-            return AuditPhase.Scoring;
-        case "completed":
-            return AuditPhase.Done;
-        case "failed":
-            return AuditPhase.Failed;
-        default:
-            return AuditPhase.Analyzing;
-    }
-}
-/**
- * Extract overall score from audit result.
- */
-function getOverallScoreFromResult(result) {
-    if (!result.scores)
-        return null;
-    const scores = result.scores;
-    const direct = scores.overall ?? scores.ux ?? scores.total;
-    if (typeof direct === "number" && Number.isFinite(direct))
-        return direct;
-    const numeric = Object.values(scores)
-        .filter((v) => typeof v === "number" && Number.isFinite(v));
-    if (numeric.length === 0)
-        return null;
-    return Math.round(numeric.reduce((a, b) => a + b, 0) / numeric.length);
-}
-/**
- * Extract numeric scores from result scores object.
- */
-function extractNumericScores(scores) {
-    if (!scores)
-        return {};
-    const result = {};
-    for (const [key, value] of Object.entries(scores)) {
-        if (typeof value === "number" && key !== "overall") {
-            result[key] = value;
-        }
-    }
-    return result;
-}
-/**
- * Count total issues from various result formats.
- */
-function countTotalIssues(issues) {
-    if (Array.isArray(issues))
-        return issues.length;
-    if (issues && typeof issues === "object") {
-        return Object.values(issues)
-            .flatMap((v) => (Array.isArray(v) ? v : []))
-            .length;
-    }
-    return 0;
-}
-/**
- * Register the audit command with the Commander program.
- */
-export function registerAuditCommand(program) {
-    program
-        .command("audit [url]")
-        .description("Run UX and accessibility audit. Localhost and private URLs are " +
-        "captured locally and analyzed via static HTML analysis.")
-        .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 (default: human in terminal, auto-detected in CI)")
-        .option("--json", "Shorthand for --format json (convenient for piping)")
-        .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)")
-        .option("--explain", "Append AI explanation to audit results")
-        .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.json || 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);
-        }
-    });
-}
+// cli/src/commands/audit.ts — barrel re-export
+export { registerAuditCommand } from "./audit/index.js";