@vertaaux/cli 0.2.0

package/dist/index.js

@@ -0,0 +1,1090 @@
+#!/usr/bin/env node
+/**
+ * VertaaUX CLI - UX audits, accessibility checks, and CI gating.
+ *
+ * Refactored to use Commander.js for command parsing with config file support.
+ * Maintains backward compatibility with existing command syntax.
+ */
+import dotenv from "dotenv";
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+import { Command } from "commander";
+import { showBanner, getVersion } from "./ui/banner.js";
+import { registerAuditCommand } from "./commands/audit.js";
+import { registerBaselineCommand } from "./commands/baseline.js";
+import { registerCommentCommand } from "./commands/comment.js";
+import { registerDiffCommand } from "./commands/diff.js";
+import { registerExplainCommand } from "./commands/explain.js";
+import { registerLoginCommand } from "./commands/login.js";
+import { registerInitCommand } from "./commands/init.js";
+import { registerUploadCommand } from "./commands/upload.js";
+import { registerDownloadCommand } from "./commands/download.js";
+import { registerPolicyCommand } from "./commands/policy.js";
+import { registerDoctorCommand } from "./commands/doctor.js";
+import { ExitCode } from "./utils/exit-codes.js";
+import { formatCommanderError } from "./ui/diagnostics.js";
+import { parseMode, parseTimeout, parseInterval, parseScore } from "./utils/validators.js";
+import { isInteractive, selectAction } from "./interactive/prompts.js";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+// Load environment variables from multiple locations
+const envCandidates = [
+    path.resolve(process.cwd(), ".env.local"),
+    path.resolve(process.cwd(), ".env"),
+    path.resolve(__dirname, "../.env.local"),
+    path.resolve(__dirname, "../.env"),
+    path.resolve(__dirname, "../../.env.local"),
+    path.resolve(__dirname, "../../.env"),
+];
+// Silence any dotenv stdout output during loading
+const originalLog = console.log;
+console.log = (...args) => {
+    const msg = String(args[0] || "");
+    if (msg.includes("[dotenv"))
+        return; // suppress dotenv banners (e.g. [dotenv@17.2.3])
+    originalLog.apply(console, args);
+};
+for (const candidate of envCandidates) {
+    if (fs.existsSync(candidate)) {
+        dotenv.config({ path: candidate, override: false });
+    }
+}
+console.log = originalLog;
+const DEFAULT_API_BASE = "https://vertaaux.ai/v1";
+// ============================================================================
+// Legacy helper functions (kept for backward compatibility with other commands)
+// ============================================================================
+function parseArgs(args) {
+    const positional = [];
+    const flags = {};
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "--") {
+            positional.push(...args.slice(i + 1));
+            break;
+        }
+        if (arg.startsWith("--")) {
+            const [rawKey, rawValue] = arg.slice(2).split("=", 2);
+            if (rawValue !== undefined) {
+                flags[rawKey] = rawValue;
+                continue;
+            }
+            const next = args[i + 1];
+            if (next && !next.startsWith("-")) {
+                flags[rawKey] = next;
+                i += 1;
+            }
+            else {
+                flags[rawKey] = true;
+            }
+            continue;
+        }
+        if (arg.startsWith("-") && arg.length > 1) {
+            const key = arg.slice(1);
+            if (key === "u") {
+                const next = args[i + 1];
+                if (next && !next.startsWith("-")) {
+                    flags.url = next;
+                    i += 1;
+                }
+                else {
+                    flags.url = true;
+                }
+                continue;
+            }
+            if (key === "b") {
+                const next = args[i + 1];
+                if (next && !next.startsWith("-")) {
+                    flags.base = next;
+                    i += 1;
+                }
+                else {
+                    flags.base = true;
+                }
+                continue;
+            }
+            if (key === "f") {
+                const next = args[i + 1];
+                if (next && !next.startsWith("-")) {
+                    flags.format = next;
+                    i += 1;
+                }
+                else {
+                    flags.format = true;
+                }
+                continue;
+            }
+            if (key === "h") {
+                flags.help = true;
+                continue;
+            }
+            if (key === "q") {
+                flags.quiet = true;
+                continue;
+            }
+            const next = args[i + 1];
+            if (next && !next.startsWith("-")) {
+                flags[key] = next;
+                i += 1;
+            }
+            else {
+                flags[key] = true;
+            }
+            continue;
+        }
+        positional.push(arg);
+    }
+    return { positional, flags };
+}
+function getString(flags, key) {
+    const value = flags[key];
+    if (typeof value === "string")
+        return value;
+    // Fallback: try camelCase version (Commander.js converts --multi-word to multiWord)
+    const camelKey = key.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+    if (camelKey !== key) {
+        const camelValue = flags[camelKey];
+        if (typeof camelValue === "string")
+            return camelValue;
+    }
+    return undefined;
+}
+function getBool(flags, key) {
+    if (flags[key] === true)
+        return true;
+    // Fallback: try camelCase version (Commander.js converts --multi-word to multiWord)
+    const camelKey = key.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+    if (camelKey !== key)
+        return flags[camelKey] === true;
+    return false;
+}
+function getNumber(flags, key) {
+    const raw = getString(flags, key);
+    if (raw === undefined)
+        return undefined;
+    const parsed = Number(raw);
+    if (Number.isNaN(parsed)) {
+        throw new Error(`Invalid --${key} value: ${raw}`);
+    }
+    return parsed;
+}
+function resolveFormat(flags) {
+    if (getBool(flags, "json"))
+        return "json";
+    if (getBool(flags, "md") || getBool(flags, "markdown"))
+        return "md";
+    const raw = getString(flags, "format") || "json";
+    if (raw === "md" || raw === "markdown")
+        return "md";
+    return "json";
+}
+function resolveApiBase(flags) {
+    const raw = getString(flags, "base") || process.env.VERTAAUX_API_BASE || DEFAULT_API_BASE;
+    return raw.replace(/\/$/, "");
+}
+function getApiKey() {
+    const key = process.env.VERTAAUX_API_KEY;
+    if (!key) {
+        throw new Error("VERTAAUX_API_KEY is required");
+    }
+    return key;
+}
+async function apiRequest(base, reqPath, options) {
+    const apiKey = getApiKey();
+    const url = `${base}${reqPath}`;
+    const res = await fetch(url, {
+        method: options.method,
+        headers: {
+            "Content-Type": "application/json",
+            "X-API-Key": apiKey,
+        },
+        body: options.body ? JSON.stringify(options.body) : undefined,
+    });
+    if (!res.ok) {
+        let detail = res.statusText;
+        try {
+            const data = (await res.json());
+            detail =
+                (data && (data.error || data.message)) ||
+                    JSON.stringify(data) ||
+                    detail;
+        }
+        catch {
+            try {
+                detail = await res.text();
+            }
+            catch {
+                // ignore
+            }
+        }
+        throw new Error(`HTTP ${res.status}: ${detail}`);
+    }
+    return (await res.json().catch(() => ({})));
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function waitForAudit(base, jobId, timeoutMs, intervalMs) {
+    const start = Date.now();
+    while (true) {
+        const status = await apiRequest(base, `/audit/${jobId}`, {
+            method: "GET",
+        });
+        if (status.status === "completed")
+            return status;
+        if (status.status === "failed")
+            return status;
+        if (Date.now() - start > timeoutMs) {
+            throw new Error(`Timed out waiting for audit ${jobId}`);
+        }
+        await sleep(intervalMs);
+    }
+}
+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 [];
+}
+function toNumber(value) {
+    if (typeof value === "number" && Number.isFinite(value))
+        return value;
+    return null;
+}
+function getOverallScore(scores) {
+    if (!scores)
+        return null;
+    const direct = toNumber(scores.overall ?? scores.ux ?? scores.total);
+    if (direct !== null)
+        return direct;
+    const numeric = Object.values(scores)
+        .map((value) => toNumber(value))
+        .filter((value) => value !== null);
+    if (numeric.length === 0)
+        return null;
+    const avg = numeric.reduce((sum, value) => sum + value, 0) / numeric.length;
+    return Math.round(avg);
+}
+function getCategoryScore(scores, key) {
+    if (!scores)
+        return null;
+    return toNumber(scores[key]);
+}
+function formatScoresTable(scores) {
+    if (!scores)
+        return "No scores available.";
+    const entries = Object.entries(scores).filter(([, value]) => typeof value === "number");
+    if (entries.length === 0)
+        return "No scores available.";
+    const lines = ["| Category | Score |", "| --- | --- |"];
+    for (const [key, value] of entries) {
+        lines.push(`| ${key} | ${value} |`);
+    }
+    return lines.join("\n");
+}
+function formatIssuesList(issues, limit = 5) {
+    if (!issues.length)
+        return "No issues.";
+    const lines = issues.slice(0, limit).map((issue, index) => {
+        const label = issue.title || issue.id || "Issue";
+        const severity = issue.severity ? issue.severity.toUpperCase() : "INFO";
+        return `${index + 1}. [${severity}] ${label}`;
+    });
+    if (issues.length > limit) {
+        lines.push(`...and ${issues.length - limit} more`);
+    }
+    return lines.join("\n");
+}
+function formatAuditMarkdown(result) {
+    const status = result.status || "unknown";
+    const lines = [`## Audit Results`, `- Status: ${status}`];
+    if (result.job_id)
+        lines.push(`- Job ID: ${result.job_id}`);
+    if (result.url)
+        lines.push(`- URL: ${result.url}`);
+    if (result.mode)
+        lines.push(`- Mode: ${result.mode}`);
+    if (typeof result.progress === "number" && status !== "completed") {
+        lines.push(`- Progress: ${result.progress}%`);
+    }
+    if (status !== "completed")
+        return lines.join("\n");
+    const overall = getOverallScore(result.scores);
+    if (overall !== null)
+        lines.push(`- Overall score: ${overall}`);
+    lines.push("\n### Scores");
+    lines.push(formatScoresTable(result.scores));
+    const issues = normalizeIssues(result.issues);
+    lines.push("\n### Issues");
+    lines.push(`Total issues: ${issues.length}`);
+    lines.push(formatIssuesList(issues));
+    return lines.join("\n");
+}
+function formatA11yMarkdown(result) {
+    const lines = [`## Accessibility Audit`, `- Status: ${result.status || "unknown"}`];
+    if (result.url)
+        lines.push(`- URL: ${result.url}`);
+    if (result.mode)
+        lines.push(`- Mode: ${result.mode}`);
+    if (result.status !== "completed")
+        return lines.join("\n");
+    const a11yScore = getCategoryScore(result.scores, "accessibility");
+    if (a11yScore !== null)
+        lines.push(`- Accessibility score: ${a11yScore}`);
+    const issues = normalizeIssues(result.issues).filter((issue) => {
+        const category = (issue.category || "").toLowerCase();
+        return (category.includes("accessibility") ||
+            category.includes("a11y") ||
+            category.includes("wcag"));
+    });
+    lines.push("\n### Accessibility Issues");
+    lines.push(`Total accessibility issues: ${issues.length}`);
+    lines.push(formatIssuesList(issues));
+    return lines.join("\n");
+}
+function formatCompareMarkdown(compare) {
+    const lines = ["## Audit Comparison"];
+    lines.push(`- URL A: ${compare.urlA}`);
+    lines.push(`- URL B: ${compare.urlB}`);
+    lines.push(`- Job A: ${compare.jobA}`);
+    lines.push(`- Job B: ${compare.jobB}`);
+    lines.push("\n### Overall Scores");
+    lines.push("| Site | Score | Delta |");
+    lines.push("| --- | --- | --- |");
+    lines.push(`| A | ${compare.overallA ?? "n/a"} | ${compare.delta ?? "n/a"} |`);
+    lines.push(`| B | ${compare.overallB ?? "n/a"} | ${compare.delta ?? "n/a"} |`);
+    lines.push("\n### Category Scores");
+    lines.push("| Category | A | B | Delta |");
+    lines.push("| --- | --- | --- | --- |");
+    for (const [key, values] of Object.entries(compare.categoryDeltas)) {
+        lines.push(`| ${key} | ${values.a ?? "n/a"} | ${values.b ?? "n/a"} | ${values.delta ?? "n/a"} |`);
+    }
+    lines.push("\n### Issue Counts");
+    lines.push(`- A: ${compare.issuesA}`);
+    lines.push(`- B: ${compare.issuesB}`);
+    return lines.join("\n");
+}
+function formatExplainMarkdown(issue) {
+    const lines = ["## Issue Explanation"];
+    if (issue.id)
+        lines.push(`- ID: ${issue.id}`);
+    if (issue.severity)
+        lines.push(`- Severity: ${issue.severity}`);
+    if (issue.category)
+        lines.push(`- Category: ${issue.category}`);
+    if (issue.selector)
+        lines.push(`- Selector: ${issue.selector}`);
+    if (issue.description) {
+        lines.push("\n### Description");
+        lines.push(issue.description);
+    }
+    const recommendation = issue.recommendation || issue.recommended_fix;
+    if (recommendation) {
+        lines.push("\n### Recommendation");
+        lines.push(recommendation);
+    }
+    if (issue.wcag_reference) {
+        lines.push("\n### WCAG Reference");
+        lines.push(issue.wcag_reference);
+    }
+    return lines.join("\n");
+}
+function formatPatchMarkdown(patch) {
+    if (!patch)
+        return "No patch generated.";
+    const lines = [
+        "## Patch Generated",
+        "",
+        `**Confidence:** ${patch.confidence.label} (${patch.confidence.percentage}%)`,
+        `**Classification:** ${patch.classification}`,
+        "",
+        "### Explanation",
+        patch.explanation,
+        "",
+        "### Search",
+        "```",
+        patch.search,
+        "```",
+        "",
+        "### Replace",
+        "```",
+        patch.replace,
+        "```",
+    ];
+    return lines.join("\n");
+}
+function formatVerifyMarkdown(result) {
+    if (!result.success || !result.verification) {
+        return `## Verification Failed\n\n${result.error?.message || "Unknown error"}`;
+    }
+    const v = result.verification;
+    const deltaSign = v.score_delta.delta >= 0 ? "+" : "";
+    const lines = [
+        "## Verification Result",
+        "",
+        `**Issue Fixed:** ${v.issue_fixed ? "Yes" : "No"}`,
+        `**Score Delta:** ${v.score_delta.before} -> ${v.score_delta.after} (${deltaSign}${v.score_delta.delta})`,
+        `**Component:** ${v.component_audited}`,
+        `**Duration:** ${v.duration_ms}ms`,
+    ];
+    if (v.regressions.length > 0) {
+        lines.push("", "### Regressions");
+        for (const r of v.regressions) {
+            lines.push(`- [${r.impact.toUpperCase()}] ${r.rule_id}: ${r.description}`);
+        }
+    }
+    else {
+        lines.push("", "### Regressions", "None");
+    }
+    if (v.error) {
+        lines.push("", `**Warning:** ${v.error}`);
+    }
+    return lines.join("\n");
+}
+// Auto-fixable issue types (from lib/patch/classifier.ts)
+const AUTO_FIXABLE_TYPES = new Set([
+    "label",
+    "input-missing-label",
+    "form-field-label",
+    "button-name",
+    "missing-button-name",
+    "link-name",
+    "html-has-lang",
+    "missing-lang-attribute",
+    "html-lang-valid",
+    "document-title",
+    "bypass",
+    "region",
+    "landmark-one-main",
+    "color-contrast",
+    "autocomplete-valid",
+    "aria-required-attr",
+    "aria-valid-attr",
+    "aria-valid-attr-value",
+]);
+function isAutoFixable(issueType) {
+    const normalized = issueType.toLowerCase().replace(/^(axe|wcag)-/, "");
+    return AUTO_FIXABLE_TYPES.has(normalized);
+}
+function formatBatchMarkdown(results) {
+    const lines = [
+        "## Batch Patch Results",
+        "",
+        `**Total Requested:** ${results.totalRequested}`,
+        `**Succeeded:** ${results.successes.length}`,
+        `**Failed:** ${results.failures.length}`,
+        `**Skipped:** ${results.totalSkipped}`,
+    ];
+    if (results.successes.length > 0) {
+        lines.push("", "### Successful Patches");
+        for (const s of results.successes) {
+            const conf = s.patch?.confidence;
+            const cls = s.patch?.classification || "unknown";
+            const confStr = conf ? `${conf.label} (${conf.percentage}%)` : "n/a";
+            lines.push(`- ${s.issueId}: ${confStr} [${cls}]`);
+        }
+    }
+    if (results.failures.length > 0) {
+        lines.push("", "### Failed");
+        for (const f of results.failures) {
+            const details = f.details ? ` - ${f.details}` : "";
+            lines.push(`- ${f.issueId}: ${f.reason}${details}`);
+        }
+    }
+    return lines.join("\n");
+}
+function printOutput(format, data, markdown) {
+    if (format === "md") {
+        console.log(markdown || "");
+        return;
+    }
+    console.log(JSON.stringify(data, null, 2));
+}
+// ============================================================================
+// Legacy command handlers (a11y, scan, compare, status, explain, fix, etc.)
+// ============================================================================
+async function runAuditCommand(base, url, flags, label) {
+    const mode = getString(flags, "mode") || "basic";
+    const timeout = getNumber(flags, "timeout");
+    const userAgent = getString(flags, "user-agent");
+    const engineVersion = getString(flags, "engine-version");
+    const failOnScore = getNumber(flags, "fail-on-score");
+    const created = await apiRequest(base, "/audit", {
+        method: "POST",
+        body: {
+            url,
+            mode,
+            timeout,
+            user_agent: userAgent,
+            engine_version: engineVersion,
+            fail_on_score: failOnScore,
+        },
+    });
+    const format = resolveFormat(flags);
+    if (!getBool(flags, "wait")) {
+        const markdown = `## Audit queued\n- Job ID: ${created.job_id}\n- URL: ${created.url}\n- Mode: ${created.mode}`;
+        printOutput(format, created, markdown);
+        return;
+    }
+    if (!created.job_id) {
+        throw new Error("Audit response missing job_id");
+    }
+    const waitTimeout = getNumber(flags, "timeout") || 60000;
+    const interval = getNumber(flags, "interval") || 5000;
+    const result = await waitForAudit(base, created.job_id, waitTimeout, interval);
+    if (label === "a11y") {
+        const a11yScore = getCategoryScore(result.scores, "accessibility");
+        if (failOnScore !== undefined && a11yScore !== null && a11yScore < failOnScore) {
+            process.exitCode = 1;
+        }
+        const issues = normalizeIssues(result.issues).filter((issue) => {
+            const category = (issue.category || "").toLowerCase();
+            return (category.includes("accessibility") ||
+                category.includes("a11y") ||
+                category.includes("wcag"));
+        });
+        const payload = {
+            ...result,
+            accessibility_score: a11yScore,
+            accessibility_issues: issues,
+        };
+        printOutput(format, payload, formatA11yMarkdown(result));
+        return;
+    }
+    const overall = getOverallScore(result.scores);
+    if (failOnScore !== undefined && overall !== null && overall < failOnScore) {
+        process.exitCode = 1;
+    }
+    printOutput(format, result, formatAuditMarkdown(result));
+}
+async function runCompareCommand(base, urls, flags) {
+    const mode = getString(flags, "mode") || "basic";
+    const wait = getBool(flags, "wait");
+    const format = resolveFormat(flags);
+    const [urlA, urlB] = urls;
+    const jobA = await apiRequest(base, "/audit", {
+        method: "POST",
+        body: { url: urlA, mode },
+    });
+    const jobB = await apiRequest(base, "/audit", {
+        method: "POST",
+        body: { url: urlB, mode },
+    });
+    if (!wait) {
+        const payload = { job_a: jobA, job_b: jobB };
+        const markdown = `## Audit comparison queued\n- Job A: ${jobA.job_id}\n- Job B: ${jobB.job_id}`;
+        printOutput(format, payload, markdown);
+        return;
+    }
+    if (!jobA.job_id || !jobB.job_id) {
+        throw new Error("Compare response missing job_id");
+    }
+    const timeout = getNumber(flags, "timeout") || 60000;
+    const interval = getNumber(flags, "interval") || 5000;
+    const resultA = await waitForAudit(base, jobA.job_id, timeout, interval);
+    const resultB = await waitForAudit(base, jobB.job_id, timeout, interval);
+    const overallA = getOverallScore(resultA.scores);
+    const overallB = getOverallScore(resultB.scores);
+    const delta = overallA !== null && overallB !== null ? overallB - overallA : null;
+    const scoresA = resultA.scores || {};
+    const scoresB = resultB.scores || {};
+    const keys = new Set([...Object.keys(scoresA), ...Object.keys(scoresB)]);
+    const categoryDeltas = {};
+    for (const key of keys) {
+        const a = toNumber(scoresA[key]);
+        const b = toNumber(scoresB[key]);
+        categoryDeltas[key] = {
+            a,
+            b,
+            delta: a !== null && b !== null ? b - a : null,
+        };
+    }
+    const issuesA = normalizeIssues(resultA.issues).length;
+    const issuesB = normalizeIssues(resultB.issues).length;
+    const compare = {
+        urlA,
+        urlB,
+        jobA: resultA.job_id || "",
+        jobB: resultB.job_id || "",
+        overallA,
+        overallB,
+        delta,
+        categoryDeltas,
+        issuesA,
+        issuesB,
+    };
+    const failOnScore = getNumber(flags, "fail-on-score");
+    if (failOnScore !== undefined &&
+        ((overallA !== null && overallA < failOnScore) ||
+            (overallB !== null && overallB < failOnScore))) {
+        process.exitCode = 1;
+    }
+    printOutput(format, compare, formatCompareMarkdown(compare));
+}
+async function runFixCommand(base, jobId, issueId, flags) {
+    const fileContent = getString(flags, "file-content");
+    const format = resolveFormat(flags);
+    if (!fileContent) {
+        throw new Error("fix requires --file-content <code>");
+    }
+    const isTTYOutput = process.stdout.isTTY && !getBool(flags, "json");
+    if (isTTYOutput) {
+        process.stderr.write("Generating patch...\r");
+    }
+    const result = await apiRequest(base, "/patch", {
+        method: "POST",
+        body: {
+            job_id: jobId,
+            issue_id: issueId,
+            file_content: fileContent,
+        },
+    });
+    if (isTTYOutput) {
+        process.stderr.write("                    \r");
+    }
+    if (!result.success) {
+        process.exitCode = 1;
+    }
+    if (format === "json") {
+        console.log(JSON.stringify(result, null, 2));
+    }
+    else {
+        if (result.success && result.patch) {
+            console.log(formatPatchMarkdown(result.patch));
+        }
+        else {
+            console.log(`## Patch Generation Failed\n\n${result.error?.message || "Unknown error"}`);
+        }
+    }
+}
+async function runVerifyCommand(base, flags) {
+    const search = getString(flags, "search");
+    const replace = getString(flags, "replace");
+    const issueId = getString(flags, "issue");
+    const url = getString(flags, "url");
+    const selector = getString(flags, "selector");
+    const timeoutMs = getNumber(flags, "timeout");
+    const format = resolveFormat(flags);
+    if (!search || !replace || !issueId || !url || !selector) {
+        throw new Error("verify requires --search, --replace, --issue, --url, and --selector");
+    }
+    const isTTYOutput = process.stdout.isTTY && !getBool(flags, "json");
+    if (isTTYOutput) {
+        process.stderr.write("Running verification...\r");
+    }
+    const result = await apiRequest(base, "/verify", {
+        method: "POST",
+        body: {
+            patch: {
+                search,
+                replace,
+                issue_id: issueId,
+            },
+            url,
+            selector,
+            timeout_ms: timeoutMs || 60000,
+        },
+    });
+    if (isTTYOutput) {
+        process.stderr.write("                         \r");
+    }
+    // Exit code: 1 if verification failed OR issue not fixed OR regressions
+    if (!result.success) {
+        process.exitCode = 1;
+    }
+    else if (result.verification &&
+        (!result.verification.issue_fixed || result.verification.regressions.length > 0)) {
+        process.exitCode = 1;
+    }
+    if (format === "json") {
+        console.log(JSON.stringify(result, null, 2));
+    }
+    else {
+        console.log(formatVerifyMarkdown(result));
+    }
+}
+const BATCH_LIMIT = 10;
+async function runFixAllCommand(base, jobId, flags) {
+    const fileContent = getString(flags, "file-content");
+    const autoFixOnly = getBool(flags, "auto-fix-only");
+    const format = resolveFormat(flags);
+    if (!fileContent) {
+        throw new Error("fix-all requires --file-content <code>");
+    }
+    const isTTYOutput = process.stdout.isTTY && !getBool(flags, "json");
+    // Fetch audit to get issues
+    if (isTTYOutput) {
+        process.stderr.write("Fetching audit...\r");
+    }
+    const audit = await apiRequest(base, `/audit/${jobId}`, {
+        method: "GET",
+    });
+    if (audit.status !== "completed") {
+        throw new Error(`Audit ${jobId} is not completed (status: ${audit.status})`);
+    }
+    // Normalize and filter issues
+    let issues = normalizeIssues(audit.issues);
+    const totalRequested = issues.length;
+    if (autoFixOnly) {
+        issues = issues.filter((issue) => {
+            const typeId = issue.id || "";
+            return isAutoFixable(typeId);
+        });
+    }
+    // Respect batch limit
+    const totalSkipped = Math.max(0, issues.length - BATCH_LIMIT);
+    const issuesToProcess = issues.slice(0, BATCH_LIMIT);
+    if (isTTYOutput) {
+        process.stderr.write("                    \r");
+    }
+    const results = {
+        successes: [],
+        failures: [],
+        totalRequested,
+        totalSkipped,
+    };
+    // Process issues sequentially to avoid overwhelming LLM API
+    for (let i = 0; i < issuesToProcess.length; i++) {
+        const issue = issuesToProcess[i];
+        const curIssueId = issue.id || `issue-${i}`;
+        if (isTTYOutput) {
+            process.stderr.write(`Generating patch ${i + 1}/${issuesToProcess.length}...\r`);
+        }
+        try {
+            const patchResult = await apiRequest(base, "/patch", {
+                method: "POST",
+                body: {
+                    job_id: jobId,
+                    issue_id: curIssueId,
+                    file_content: fileContent,
+                },
+            });
+            if (patchResult.success && patchResult.patch) {
+                results.successes.push({
+                    issueId: curIssueId,
+                    patch: patchResult.patch,
+                });
+            }
+            else {
+                results.failures.push({
+                    issueId: curIssueId,
+                    reason: patchResult.error?.code || "PATCH_FAILED",
+                    details: patchResult.error?.message,
+                });
+            }
+        }
+        catch (err) {
+            results.failures.push({
+                issueId: curIssueId,
+                reason: "REQUEST_ERROR",
+                details: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    // Clear progress line
+    if (isTTYOutput) {
+        process.stderr.write("                                      \r");
+    }
+    // Exit code 1 if any failures
+    if (results.failures.length > 0) {
+        process.exitCode = 1;
+    }
+    if (format === "json") {
+        console.log(JSON.stringify(results, null, 2));
+    }
+    else {
+        console.log(formatBatchMarkdown(results));
+    }
+}
+async function runExplainCommand(base, flags) {
+    const format = resolveFormat(flags);
+    const issueJson = getString(flags, "issue");
+    const issueFile = getString(flags, "file");
+    const jobId = getString(flags, "job") || getString(flags, "job-id");
+    const issueId = getString(flags, "issue-id") || getString(flags, "id");
+    let issue = null;
+    if (issueJson) {
+        issue = JSON.parse(issueJson);
+    }
+    else if (issueFile) {
+        const raw = fs.readFileSync(issueFile, "utf-8");
+        issue = JSON.parse(raw);
+    }
+    else if (jobId && issueId) {
+        const result = await apiRequest(base, `/audit/${jobId}`, {
+            method: "GET",
+        });
+        const issues = normalizeIssues(result.issues);
+        issue = issues.find((item) => item.id === issueId) || null;
+        if (!issue) {
+            throw new Error(`Issue ${issueId} not found in job ${jobId}`);
+        }
+    }
+    if (!issue) {
+        throw new Error("Provide --issue, --file, or --job with --issue-id");
+    }
+    const payload = { issue };
+    printOutput(format, payload, formatExplainMarkdown(issue));
+}
+// ============================================================================
+// Commander.js CLI setup
+// ============================================================================
+const version = getVersion();
+const program = new Command();
+program
+    .name("vertaa")
+    .description("VertaaUX CLI for UX audits, accessibility checks, and CI gating")
+    .version(version, "-v, --version", "Output the version number")
+    .enablePositionalOptions()
+    .option("-b, --base <url>", "API base URL")
+    .option("-c, --config <path>", "Path to config file (overrides auto-detection)")
+    .option("-q, --quiet", "Suppress banner and non-essential output")
+    .option("--no-banner", "Hide the V-mark banner")
+    .option("--machine", "Strict machine-readable output (JSON stdout, diagnostics stderr)")
+    .configureOutput({
+    outputError: (str, _write) => {
+        const formatted = formatCommanderError(str);
+        process.stderr.write(formatted + "\n");
+    },
+})
+    .exitOverride((err) => {
+    if (err.code === "commander.invalidArgument" ||
+        err.code === "commander.missingArgument" ||
+        err.code === "commander.missingMandatoryOptionValue" ||
+        err.code === "commander.optionMissingArgument") {
+        process.exit(2);
+    }
+    // For other Commander errors (help, version), use Commander's default exit code
+    process.exit(err.exitCode);
+})
+    .hook("preAction", (thisCommand) => {
+    const opts = thisCommand.optsWithGlobals();
+    const machineMode = opts.machine || false;
+    if (machineMode) {
+        opts.quiet = true;
+        opts.banner = false;
+    }
+    showBanner({
+        version,
+        quiet: opts.quiet || machineMode,
+        noBanner: opts.banner === false || machineMode,
+    });
+});
+// Register commands (new Commander.js implementations)
+registerAuditCommand(program);
+registerBaselineCommand(program);
+registerCommentCommand(program);
+registerDiffCommand(program);
+registerExplainCommand(program);
+registerLoginCommand(program);
+registerInitCommand(program);
+registerUploadCommand(program);
+registerDownloadCommand(program);
+registerPolicyCommand(program);
+registerDoctorCommand(program);
+// Legacy commands using old argument parsing
+// These will be migrated in subsequent plans
+program
+    .command("a11y <url>")
+    .description("Run accessibility-focused audit (alias for audit with a11y filter)")
+    .option("--mode <mode>", "Audit depth: basic|standard|deep", parseMode, "basic")
+    .option("--wait", "Wait for audit completion")
+    .option("--timeout <ms>", "Wait timeout in milliseconds (1-300000)", parseTimeout, 60000)
+    .option("--interval <ms>", "Poll interval in milliseconds (1-300000)", parseInterval, 5000)
+    .option("--fail-on-score <n>", "Exit non-zero if score below n (0-100)", parseScore)
+    .action(async (url, cmdOptions) => {
+    try {
+        const base = resolveApiBase(cmdOptions);
+        await runAuditCommand(base, url, { ...cmdOptions, wait: cmdOptions.wait ?? true }, "a11y");
+    }
+    catch (error) {
+        process.stderr.write(`Error: ${error instanceof Error ? error.message : String(error)}\n`);
+        process.exit(ExitCode.ERROR);
+    }
+});
+program
+    .command("scan <url>")
+    .description("Run UX scan (alias for audit)")
+    .option("--mode <mode>", "Audit depth: basic|standard|deep", parseMode, "basic")
+    .option("--wait", "Wait for audit completion")
+    .option("--timeout <ms>", "Wait timeout in milliseconds (1-300000)", parseTimeout, 60000)
+    .option("--interval <ms>", "Poll interval in milliseconds (1-300000)", parseInterval, 5000)
+    .option("--fail-on-score <n>", "Exit non-zero if score below n (0-100)", parseScore)
+    .action(async (url, cmdOptions) => {
+    try {
+        const base = resolveApiBase(cmdOptions);
+        await runAuditCommand(base, url, { ...cmdOptions, wait: cmdOptions.wait ?? true }, "scan");
+    }
+    catch (error) {
+        process.stderr.write(`Error: ${error instanceof Error ? error.message : String(error)}\n`);
+        process.exit(ExitCode.ERROR);
+    }
+});
+program
+    .command("compare <urlA> <urlB>")
+    .description("Compare audits of two URLs")
+    .option("--mode <mode>", "Audit depth: basic|standard|deep", parseMode, "basic")
+    .option("--wait", "Wait for audits to complete")
+    .option("--timeout <ms>", "Wait timeout in milliseconds (1-300000)", parseTimeout, 60000)
+    .option("--interval <ms>", "Poll interval in milliseconds (1-300000)", parseInterval, 5000)
+    .option("--fail-on-score <n>", "Exit non-zero if score below n (0-100)", parseScore)
+    .action(async (urlA, urlB, cmdOptions) => {
+    try {
+        const base = resolveApiBase(cmdOptions);
+        await runCompareCommand(base, [urlA, urlB], cmdOptions);
+    }
+    catch (error) {
+        process.stderr.write(`Error: ${error instanceof Error ? error.message : String(error)}\n`);
+        process.exit(ExitCode.ERROR);
+    }
+});
+program
+    .command("status <jobId>")
+    .description("Get status of an audit job")
+    .option("--fail-on-score <n>", "Exit non-zero if score below n (0-100)", parseScore)
+    .action(async (jobId, cmdOptions) => {
+    try {
+        const base = resolveApiBase(cmdOptions);
+        const result = await apiRequest(base, `/audit/${jobId}`, {
+            method: "GET",
+        });
+        const format = resolveFormat(cmdOptions);
+        const overall = getOverallScore(result.scores);
+        const payload = { ...result, overall_score: overall };
+        const markdown = formatAuditMarkdown(result);
+        const failOnScore = getNumber(cmdOptions, "fail-on-score");
+        if (failOnScore !== undefined && overall !== null && overall < failOnScore) {
+            process.exitCode = 1;
+        }
+        printOutput(format, payload, markdown);
+    }
+    catch (error) {
+        process.stderr.write(`Error: ${error instanceof Error ? error.message : String(error)}\n`);
+        process.exit(ExitCode.ERROR);
+    }
+});
+// Legacy explain command removed - using new registerExplainCommand
+program
+    .command("fix <jobId>")
+    .description("Generate a fix patch for an issue")
+    .requiredOption("--issue <id>", "Issue ID to fix")
+    .requiredOption("--file-content <code>", "Source code content")
+    .action(async (jobId, cmdOptions) => {
+    try {
+        const base = resolveApiBase(cmdOptions);
+        const issueId = getString(cmdOptions, "issue");
+        if (!issueId)
+            throw new Error("--issue is required");
+        await runFixCommand(base, jobId, issueId, cmdOptions);
+    }
+    catch (error) {
+        process.stderr.write(`Error: ${error instanceof Error ? error.message : String(error)}\n`);
+        process.exit(ExitCode.ERROR);
+    }
+});
+program
+    .command("fix-all <jobId>")
+    .description("Generate fix patches for all issues in an audit")
+    .requiredOption("--file-content <code>", "Source code content")
+    .option("--auto-fix-only", "Only process auto-fixable issues")
+    .action(async (jobId, cmdOptions) => {
+    try {
+        const base = resolveApiBase(cmdOptions);
+        await runFixAllCommand(base, jobId, cmdOptions);
+    }
+    catch (error) {
+        process.stderr.write(`Error: ${error instanceof Error ? error.message : String(error)}\n`);
+        process.exit(ExitCode.ERROR);
+    }
+});
+program
+    .command("verify")
+    .description("Verify that a patch fixes an issue")
+    .requiredOption("--search <text>", "Search pattern")
+    .requiredOption("--replace <text>", "Replace pattern")
+    .requiredOption("--issue <id>", "Issue ID")
+    .requiredOption("--url <url>", "Target URL")
+    .requiredOption("--selector <css>", "CSS selector")
+    .option("--timeout <ms>", "Timeout in milliseconds (1-300000)", parseTimeout, 60000)
+    .action(async (cmdOptions) => {
+    try {
+        const base = resolveApiBase(cmdOptions);
+        await runVerifyCommand(base, cmdOptions);
+    }
+    catch (error) {
+        process.stderr.write(`Error: ${error instanceof Error ? error.message : String(error)}\n`);
+        process.exit(ExitCode.ERROR);
+    }
+});
+/**
+ * Interactive menu when no command given in TTY.
+ */
+async function showInteractiveMenu() {
+    const action = await selectAction("What would you like to do?", [
+        {
+            name: "Run audit",
+            value: "audit",
+            description: "Audit a URL for UX and accessibility issues",
+        },
+        {
+            name: "Initialize project",
+            value: "init",
+            description: "Create .vertaaux.yml configuration",
+        },
+        {
+            name: "Check health",
+            value: "doctor",
+            description: "Run diagnostics on CLI configuration and connectivity",
+        },
+        {
+            name: "View help",
+            value: "help",
+            description: "Show all available commands",
+        },
+        {
+            name: "Exit",
+            value: "exit",
+        },
+    ]);
+    switch (action) {
+        case "audit":
+            // Re-parse with audit command
+            process.argv.push("audit");
+            program.parse();
+            break;
+        case "init":
+            // Re-parse with init command
+            process.argv.push("init");
+            program.parse();
+            break;
+        case "doctor":
+            process.argv.push("doctor");
+            program.parse();
+            break;
+        case "help":
+            program.outputHelp();
+            break;
+        case "exit":
+            process.exit(0);
+            break;
+    }
+}
+// Parse and execute
+// If no command and TTY, show interactive menu
+const args = process.argv.slice(2);
+const hasCommand = args.length > 0 && !args[0].startsWith("-");
+if (!hasCommand && isInteractive()) {
+    // Show banner first
+    showBanner({ version, quiet: false, noBanner: false });
+    showInteractiveMenu().catch((error) => {
+        process.stderr.write(`Error: ${error instanceof Error ? error.message : String(error)}\n`);
+        process.exit(ExitCode.ERROR);
+    });
+}
+else {
+    program.parse();
+}