@vertaaux/cli 0.4.0 → 0.5.1

package/dist/commands/audit/index.js

@@ -0,0 +1,589 @@
+/**
+ * Audit command for VertaaUX CLI.
+ *
+ * Runs UX and accessibility audits on web pages.
+ * Supports various targets, output formats, and CI integration.
+ */
+import { colorize, dim, brand, severity as severityPalette } from "@vertaaux/tui";
+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 { resolveApiBase, getApiKey, apiRequest, waitForAudit, createClient, } from "../../utils/client.js";
+import { createOutput } from "../../output/factory.js";
+import { resolveCommandFormat } from "../../output/formats.js";
+import { writeOutput } from "../../output/envelope.js";
+import { createRenderer, createKeyboardHandler, runSteps, renderWarning, renderError, isCI, isTTY as tuiIsTTY, phaseIndex, phaseTotal, } from "@vertaaux/tui";
+import { runFixWizard } from "../../interactive/fix-wizard.js";
+import { isInteractive } from "../../interactive/prompts.js";
+import { evaluateQualityGate, } from "../../quality-gate/index.js";
+import { loadBaseline } from "../../baseline/manager.js";
+import { getChangedRoutes, detectBaseBranch, getBudgetConfig, } from "../../ci/index.js";
+import { detectMonorepo, getAuditableApps, generateMatrixConfig, } from "../../monorepo/index.js";
+import { createLogger } from "../../utils/logger.js";
+import { validateBranchName } from "../../utils/sanitize.js";
+import { isLocalUrl } from "../../utils/url-classify.js";
+import { captureLocalPage } from "../../utils/local-capture.js";
+import { strings } from "../../ui/strings.js";
+import { detectPRLabels } from "./ci-detection.js";
+import { normalizeIssues, filterBySeverity, filterByCategory } from "./filters.js";
+import { mapStatusToPhase, getOverallScoreFromResult, extractNumericScores, countTotalIssues } from "./scoring.js";
+import { saveReproArtifacts, saveArtifactBundle } from "./artifacts.js";
+import { outputFireAndForget, outputFormattedResults, outputQualityGateResult } from "./output.js";
+import { loadAndResolvePolicy, buildQualityGateConfig, resolveAuditProfile } from "./policy.js";
+import { runInlineExplanation } from "./explain.js";
+/**
+ * Apply filters, evaluate quality gate, and output results after audit completes.
+ */
+async function runPostAuditAnalysis(params) {
+    const { result, createdJobId, targetUrl, format, formatter, groupBy, options, config, interactive, quiet, profile } = params;
+    // Save repro artifacts if requested
+    if (createdJobId) {
+        saveReproArtifacts(createdJobId, 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);
+    const filteredResult = { ...result, issues };
+    // Load and apply policy (CICD-17)
+    await loadAndResolvePolicy(options, quiet);
+    // Build quality gate config and evaluate (profile applied between config and CLI flags)
+    const gateConfig = buildQualityGateConfig(config, options, profile);
+    const baselinePath = options.baseline || config.baseline?.path;
+    const baseline = baselinePath ? await loadBaseline(baselinePath) : null;
+    const prLabels = detectPRLabels();
+    const gateResult = evaluateQualityGate({
+        auditResult: {
+            issues,
+            scores: result.scores,
+        },
+        baseline,
+        config: gateConfig,
+        labels: prLabels,
+    });
+    // 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 && createdJobId) {
+        const artifactJobId = options.jobId || createdJobId;
+        saveArtifactBundle(artifactJobId, result, issues, gateResult.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 (gateResult.exitCode !== ExitCode.SUCCESS) {
+        process.exitCode = gateResult.exitCode;
+    }
+}
+/**
+ * Execute the audit command — exported as handleAudit for CommandRunnerView.
+ */
+export async function handleAudit(rawUrl, options, config) {
+    // Normalize URL: add https:// if no protocol specified
+    const targetUrl = /^https?:\/\//i.test(rawUrl) ? rawUrl : `https://${rawUrl}`;
+    // SECVAL-5: Reject non-http(s) schemes explicitly
+    try {
+        const parsed = new URL(targetUrl);
+        if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+            process.stderr.write(renderError({
+                message: `Unsupported URL scheme "${parsed.protocol}" — only http: and https: are allowed`,
+                suggestion: "Provide a URL starting with http:// or https://",
+                exitCode: ExitCode.ERROR,
+            }) + "\n");
+            process.exitCode = ExitCode.ERROR;
+            return;
+        }
+    }
+    catch {
+        process.stderr.write(renderError({
+            message: `Invalid URL: "${targetUrl}"`,
+            suggestion: "Provide a valid http:// or https:// URL",
+            exitCode: ExitCode.ERROR,
+        }) + "\n");
+        process.exitCode = ExitCode.ERROR;
+        return;
+    }
+    // Resolve audit profile (bundles categories, weights, thresholds, mode)
+    const profile = resolveAuditProfile(options.profile || config.profile, config.profiles);
+    // Resolve options with precedence: flags > config > profile > defaults
+    const mode = options.mode || config.mode || profile?.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 fail-fast mode: --strict > --continue-on-error > auto-detect
+    let failFast;
+    if (options.strict && options.continueOnError) {
+        writeOutput(renderWarning({ message: "--strict and --continue-on-error both set — --strict takes precedence" }));
+        failFast = true;
+    }
+    else if (options.strict) {
+        failFast = true;
+    }
+    else if (options.continueOnError) {
+        failFast = false;
+    }
+    else {
+        failFast = isCI() || !tuiIsTTY();
+    }
+    // Resolve API settings
+    const base = resolveApiBase(options.base);
+    const apiKey = getApiKey(config.apiKey);
+    const sdkClient = createClient({ base: options.base, apiKey: 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";
+    // Keyboard handler for abort
+    let keyboard = null;
+    let aborted = false;
+    // Create renderer for step-list display
+    const renderer = createRenderer("auto");
+    keyboard = createKeyboardHandler();
+    keyboard.on("quit", () => {
+        aborted = true;
+        renderer.dispose();
+        keyboard?.dispose();
+        writeOutput("\nAudit aborted by user.\n");
+        process.exitCode = ExitCode.ERROR;
+    });
+    keyboard.start();
+    const auditStartTime = Date.now();
+    const baseState = {
+        phase: strings.audit.run.action,
+        phaseIndex: 1,
+        phaseTotal: 3,
+        url: targetUrl,
+        mode,
+        progress: {},
+        totals: {},
+        issueCount: 0,
+        scorePreview: null,
+        verbose: false,
+        elapsed: 0,
+    };
+    let auditResult = null;
+    let createdJobId;
+    const steps = [
+        {
+            id: "fetch",
+            actionText: isLocalUrl(targetUrl)
+                ? strings.audit.localFetch.action
+                : strings.audit.run.action,
+            summaryText: isLocalUrl(targetUrl)
+                ? strings.audit.localFetch.done()
+                : strings.audit.localAnalyze.done(),
+            run: async () => {
+                if (aborted)
+                    return;
+                if (isLocalUrl(targetUrl)) {
+                    // Local URL — capture HTML on this machine, send to /analyze
+                    // Note: informational messages moved to step summaryText to avoid
+                    // writing to stderr during ComposedRenderer step execution.
+                    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)}`);
+                    }
+                    const created = await apiRequest(base, "/analyze", {
+                        method: "POST",
+                        body: { html: captured.html, url: targetUrl, mode },
+                    }, apiKey);
+                    auditResult = created;
+                    createdJobId = created.job_id;
+                }
+                else {
+                    // Public URL — send to cloud API.
+                    //
+                    // When the resolved profile declares a `categories` subset, we bypass
+                    // `sdkClient.audits.create` and POST directly via `apiRequest`
+                    // because the published @vertaaux/sdk typings don't yet include the
+                    // `categories` field (Phase 1.5 wire format). The wire format is
+                    // identical to the SDK's — same path, same auth — so this is a
+                    // targeted escape hatch, not a fork. Once the SDK typings are bumped
+                    // to include `categories?`, both branches collapse back to the SDK.
+                    const profileCategories = profile?.categories;
+                    const created = profileCategories && profileCategories.length > 0
+                        ? await apiRequest(base, "/audit", {
+                            method: "POST",
+                            body: {
+                                url: targetUrl,
+                                mode: mode,
+                                categories: profileCategories,
+                            },
+                        }, apiKey)
+                        : await sdkClient.audits.create({
+                            url: targetUrl,
+                            mode: mode,
+                        });
+                    auditResult = created;
+                    createdJobId = created.job_id;
+                    // If not waiting, just output the job info and stop processing.
+                    // Return early so the "wait" and "analyze" steps are skipped — the
+                    // quality gate must NOT run for --no-wait jobs since the audit may
+                    // not be complete yet (or may be from a sync server that returns the
+                    // completed result immediately).
+                    if (!wait) {
+                        renderer.finish({
+                            url: targetUrl,
+                            mode,
+                            overallScore: 0,
+                            scores: {},
+                            issueCount: 0,
+                            passed: true,
+                            elapsed: Date.now() - auditStartTime,
+                        });
+                        keyboard?.dispose();
+                        outputFireAndForget(created, format, formatter, options, quiet);
+                        return;
+                    }
+                }
+            },
+        },
+        {
+            id: "wait",
+            actionText: strings.audit.wait.action,
+            summaryText: strings.audit.wait.done(0),
+            run: async () => {
+                if (aborted || !wait || !auditResult)
+                    return;
+                const created = auditResult;
+                if (created.status === "failed") {
+                    throw new Error(created.error || "Audit failed on server");
+                }
+                const isSyncResponse = created.status === "completed" && created.scores;
+                if (isSyncResponse) {
+                    // Already done — nothing to wait for
+                    return;
+                }
+                if (!created.job_id) {
+                    throw new Error("Audit response missing job_id");
+                }
+                const result = await waitForAudit(sdkClient, created.job_id, timeout, interval, (progress, status) => {
+                    if (aborted)
+                        return;
+                    const phase = mapStatusToPhase(status);
+                    renderer.update({
+                        ...baseState,
+                        phase,
+                        phaseIndex: phaseIndex(phase),
+                        phaseTotal: phaseTotal(),
+                        progress: { audit: progress },
+                        totals: { audit: 100 },
+                        elapsed: Date.now() - auditStartTime,
+                    });
+                });
+                auditResult = result;
+            },
+        },
+        {
+            id: "analyze",
+            actionText: strings.audit.localAnalyze.action,
+            summaryText: strings.audit.run.done(0, targetUrl),
+            run: async () => {
+                // No-op: analysis output is written AFTER renderer.finish()
+                // to avoid breaking ComposedRenderer's cursor arithmetic.
+                if (aborted || !auditResult || !wait)
+                    return;
+            },
+        },
+    ];
+    const { success, states } = await runSteps(steps, {
+        failFast,
+        onStateChange: (stepStates) => {
+            renderer.update({
+                ...baseState,
+                stepStates,
+                elapsed: Date.now() - auditStartTime,
+            });
+        },
+    });
+    if (success && auditResult) {
+        const resolvedResult = auditResult;
+        const overallScore = getOverallScoreFromResult(resolvedResult);
+        renderer.finish({
+            url: targetUrl,
+            mode,
+            overallScore: overallScore ?? 0,
+            scores: extractNumericScores(resolvedResult.scores),
+            issueCount: countTotalIssues(resolvedResult.issues),
+            passed: (overallScore ?? 0) >= 70,
+            elapsed: Date.now() - auditStartTime,
+        });
+    }
+    else {
+        renderer.finish({
+            url: targetUrl,
+            mode,
+            overallScore: 0,
+            scores: {},
+            issueCount: 0,
+            passed: false,
+            elapsed: Date.now() - auditStartTime,
+        });
+    }
+    keyboard?.dispose();
+    if (!success) {
+        const failedStep = states.find((s) => s.status === "failed");
+        const reason = failedStep?.failReason || "(no reason captured)";
+        process.stderr.write(renderError({
+            message: `Audit failed — ${reason}`,
+            suggestion: "vertaa doctor",
+        }) + "\n");
+        process.exitCode = ExitCode.ERROR;
+        return;
+    }
+    // Run post-audit analysis AFTER renderer.finish() so output
+    // doesn't break ComposedRenderer's cursor arithmetic
+    if (auditResult && wait && !aborted) {
+        await runPostAuditAnalysis({
+            result: auditResult,
+            createdJobId,
+            targetUrl,
+            format,
+            formatter,
+            groupBy,
+            options,
+            config,
+            interactive,
+            quiet,
+            profile,
+        });
+    }
+}
+/**
+ * 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("--profile <name>", "Audit profile: wcag-aa|conversion-focus|quick-ux|ci-gate|compliance")
+        .option("--explain", "Append AI explanation to audit results")
+        .option("--strict", "Fail immediately on first step error")
+        .option("--continue-on-error", "Continue on step errors even in CI")
+        .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 and --base flags to command options
+            cmdOptions.machine = globalOpts.machine || false;
+            cmdOptions.base = globalOpts.base || cmdOptions.base;
+            // 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) {
+                            writeOutput(`Error: Workspace "${cmdOptions.workspace}" not found\nAvailable: ${monorepo.workspaces.map((w) => w.name).join(", ")}\n`);
+                            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 — not yet implemented (placeholder removed to prevent false-green CI results)
+                    if (cmdOptions.allWorkspaces) {
+                        // TODO: Implement real workspace audit execution (iterate apps, call executeAudit per workspace)
+                        writeOutput(colorize(strings.audit.errors.allWorkspacesNotImplemented, severityPalette.warning) +
+                            "\n" +
+                            apps.map((app) => dim(`  vertaa audit ${app.url || app.name}`)).join("\n") +
+                            "\n");
+                        process.exit(ExitCode.ERROR);
+                    }
+                }
+            }
+            // 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) {
+                    writeOutput(colorize(strings.audit.noRouteChanges, brand.lime) + "\n");
+                    process.exit(ExitCode.SUCCESS);
+                }
+                // Log which routes will be audited
+                writeOutput(dim(`Incremental mode: Auditing ${changedResult.routes.length} changed routes`) + "\n");
+                for (const route of changedResult.routes) {
+                    writeOutput(dim(`  - ${route}`) + "\n");
+                }
+                // If routes were detected, use them instead of URL argument
+                if (!config.defaultUrl) {
+                    writeOutput("Error: --incremental requires defaultUrl in config to construct full URLs.\n");
+                    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;
+                }
+                writeOutput(dim(`Budget mode: ${cmdOptions.budget} (max ${budgetConfig.maxPages} pages, ${budgetConfig.maxTime / 1000}s timeout, ${budgetConfig.concurrency} concurrent)`) + "\n");
+            }
+            // 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) {
+                    writeOutput("Error: --routes requires defaultUrl in config or a base URL.\n");
+                    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) {
+                writeOutput("Error: URL is required. Provide as argument, --url flag, or defaultUrl in config.\n");
+                process.exit(ExitCode.ERROR);
+            }
+            await handleAudit(targetUrl, cmdOptions, config);
+        }
+        catch (error) {
+            process.stderr.write(renderError({
+                message: error instanceof Error ? error.message : String(error),
+                suggestion: "vertaa doctor",
+                exitCode: ExitCode.ERROR,
+            }) + "\n");
+            process.exit(ExitCode.ERROR);
+        }
+    });
+}

package/dist/commands/audit/output.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Output formatting helpers for the audit command.
+ */
+import type { AuditResponse } from "../../utils/client.js";
+import { createOutput } from "../../output/factory.js";
+import { evaluateQualityGate } from "../../quality-gate/index.js";
+import type { OutputFormat } from "../../utils/detect-env.js";
+import type { IssueLike, AuditCommandOptions } from "./types.js";
+/**
+ * Write output to file. Returns the resolved path if written to file, undefined otherwise.
+ */
+export declare function writeOutputToFile(content: string, outputPath: string | undefined, defaultPath?: string): string | undefined;
+/**
+ * Get default output path based on format.
+ * Returns undefined for formats that should go to stdout by default.
+ */
+export declare function getDefaultOutputPath(format: OutputFormat): string | undefined;
+/**
+ * Output results in fire-and-forget mode (--no-wait).
+ */
+export declare function outputFireAndForget(created: AuditResponse, format: OutputFormat, formatter: ReturnType<typeof createOutput>, options: AuditCommandOptions, quiet: boolean): void;
+/**
+ * Print quality gate result to stderr.
+ */
+export declare function outputQualityGateResult(gateResult: ReturnType<typeof evaluateQualityGate>): void;
+/**
+ * Write formatted audit results to output or stdout.
+ */
+export declare function outputFormattedResults(filteredResult: Omit<AuditResponse, "issues"> & {
+    issues: IssueLike[];
+}, format: OutputFormat, formatter: ReturnType<typeof createOutput>, groupBy: "severity" | "category" | "route", options: AuditCommandOptions, quiet: boolean): void;
+//# sourceMappingURL=output.d.ts.map

package/dist/commands/audit/output.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"output.d.ts","sourceRoot":"","sources":["../../../src/commands/audit/output.ts"],"names":[],"mappings":"AAAA;;GAEG;AAKH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,EAAE,YAAY,EAAsB,MAAM,yBAAyB,CAAC;AAE3E,OAAO,EACL,mBAAmB,EACpB,MAAM,6BAA6B,CAAC;AACrC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAC9D,OAAO,KAAK,EAAE,SAAS,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAGjE;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,WAAW,CAAC,EAAE,MAAM,GACnB,MAAM,GAAG,SAAS,CAgBpB;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,GAAG,SAAS,CAO7E;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,aAAa,EACtB,MAAM,EAAE,YAAY,EACpB,SAAS,EAAE,UAAU,CAAC,OAAO,YAAY,CAAC,EAC1C,OAAO,EAAE,mBAAmB,EAC5B,KAAK,EAAE,OAAO,GACb,IAAI,CAqBN;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CACrC,UAAU,EAAE,UAAU,CAAC,OAAO,mBAAmB,CAAC,GACjD,IAAI,CAyBN;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,cAAc,EAAE,IAAI,CAAC,aAAa,EAAE,QAAQ,CAAC,GAAG;IAAE,MAAM,EAAE,SAAS,EAAE,CAAA;CAAE,EACvE,MAAM,EAAE,YAAY,EACpB,SAAS,EAAE,UAAU,CAAC,OAAO,YAAY,CAAC,EAC1C,OAAO,EAAE,UAAU,GAAG,UAAU,GAAG,OAAO,EAC1C,OAAO,EAAE,mBAAmB,EAC5B,KAAK,EAAE,OAAO,GACb,IAAI,CA6BN"}