@vertaaux/cli 0.2.3 → 0.3.0

package/dist/commands/compare.js

@@ -0,0 +1,335 @@
+/**
+ * Compare command for VertaaUX CLI (upgraded).
+ *
+ * Two modes:
+ * 1. URL comparison (backward compat): `vertaa compare <urlA> <urlB> --wait`
+ *    Runs two audits and shows a score/category delta table.
+ * 2. File-based LLM comparison: `vertaa compare --before old.json --after new.json`
+ *    Sends both audit JSONs to the LLM compare endpoint for a narrative analysis.
+ *
+ * When --before/--after are provided, the LLM mode is used automatically.
+ * When positional URLs are given, the legacy comparison mode is used.
+ *
+ * Examples:
+ *   vertaa compare https://a.com https://b.com --wait
+ *   vertaa compare --before baseline.json --after current.json
+ *   vertaa compare --before baseline.json --after current.json --verbose
+ */
+import chalk from "chalk";
+import { ExitCode } from "../utils/exit-codes.js";
+import { resolveApiBase, getApiKey, apiRequest, waitForAudit, } from "../utils/client.js";
+import { resolveConfig } from "../config/loader.js";
+import { writeJsonOutput, writeOutput } from "../output/envelope.js";
+import { resolveCommandFormat } from "../output/formats.js";
+import { createSpinner, succeedSpinner, failSpinner } from "../ui/spinner.js";
+import { readJsonInput } from "../utils/stdin.js";
+import { handleAiCommandError, AI_TIMEOUT_MS } from "../utils/ai-error.js";
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function normalizeIssues(issues) {
+    let list;
+    if (Array.isArray(issues)) {
+        list = issues;
+    }
+    else if (issues && typeof issues === "object") {
+        list = Object.values(issues).flatMap((v) => Array.isArray(v) ? v : []);
+    }
+    else {
+        return [];
+    }
+    return list.map((raw) => {
+        const i = raw;
+        return {
+            id: i.id || i.ruleId || i.rule_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,
+        };
+    });
+}
+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((v) => toNumber(v))
+        .filter((v) => v !== null);
+    if (numeric.length === 0)
+        return null;
+    const avg = numeric.reduce((sum, v) => sum + v, 0) / numeric.length;
+    return Math.round(avg);
+}
+function buildAuditPayload(result, fallbackJobId) {
+    const issues = normalizeIssues(result.issues);
+    return {
+        job_id: result.job_id || fallbackJobId || null,
+        url: result.url || null,
+        scores: result.scores || null,
+        issues,
+    };
+}
+// ---------------------------------------------------------------------------
+// Formatters — Legacy URL comparison
+// ---------------------------------------------------------------------------
+function formatLegacyCompareHuman(data) {
+    const lines = [];
+    lines.push(chalk.bold("Audit Comparison"));
+    lines.push(`  URL A: ${chalk.cyan(data.urlA)}`);
+    lines.push(`  URL B: ${chalk.cyan(data.urlB)}`);
+    lines.push("");
+    // Overall scores
+    const deltaStr = data.delta !== null
+        ? (data.delta >= 0 ? chalk.green(`+${data.delta}`) : chalk.red(`${data.delta}`))
+        : chalk.dim("n/a");
+    lines.push(chalk.bold("Overall Scores"));
+    lines.push(`  A: ${data.overallA ?? "n/a"}  B: ${data.overallB ?? "n/a"}  Delta: ${deltaStr}`);
+    lines.push("");
+    // Category deltas
+    const entries = Object.entries(data.categoryDeltas);
+    if (entries.length > 0) {
+        lines.push(chalk.bold("Category Scores"));
+        for (const [key, vals] of entries) {
+            const d = vals.delta !== null
+                ? (vals.delta >= 0 ? chalk.green(`+${vals.delta}`) : chalk.red(`${vals.delta}`))
+                : chalk.dim("n/a");
+            lines.push(`  ${key}: ${vals.a ?? "n/a"} → ${vals.b ?? "n/a"} (${d})`);
+        }
+        lines.push("");
+    }
+    // Issue counts
+    lines.push(chalk.bold("Issue Counts"));
+    lines.push(`  A: ${data.issuesA}  B: ${data.issuesB}`);
+    return lines.join("\n");
+}
+// ---------------------------------------------------------------------------
+// Formatters — LLM comparison
+// ---------------------------------------------------------------------------
+function formatLlmCompareHuman(data, verbose) {
+    const lines = [];
+    lines.push(chalk.bold(data.headline));
+    lines.push("");
+    // Score delta
+    const d = data.score_delta.overall;
+    const deltaStr = d >= 0 ? chalk.green(`+${d}`) : chalk.red(`${d}`);
+    lines.push(`Overall delta: ${deltaStr}`);
+    if (data.score_delta.categories && verbose) {
+        for (const [cat, val] of Object.entries(data.score_delta.categories)) {
+            const catDelta = val >= 0 ? chalk.green(`+${val}`) : chalk.red(`${val}`);
+            lines.push(`  ${cat}: ${catDelta}`);
+        }
+    }
+    lines.push("");
+    // Improvements
+    if (data.improvements.length > 0) {
+        lines.push(chalk.green.bold(`Improvements (${data.improvements.length})`));
+        for (const item of data.improvements) {
+            lines.push(`  ${chalk.green("+")} ${item}`);
+        }
+        lines.push("");
+    }
+    // Regressions
+    if (data.regressions.length > 0) {
+        lines.push(chalk.red.bold(`Regressions (${data.regressions.length})`));
+        for (const item of data.regressions) {
+            lines.push(`  ${chalk.red("-")} ${item}`);
+        }
+        lines.push("");
+    }
+    lines.push(chalk.dim(`Unchanged: ${data.unchanged}`));
+    if (verbose) {
+        lines.push("");
+        lines.push(chalk.bold("Analysis"));
+        lines.push(data.narrative);
+    }
+    return lines.join("\n");
+}
+// ---------------------------------------------------------------------------
+// Command Registration
+// ---------------------------------------------------------------------------
+export function registerCompareCommand(program) {
+    program
+        .command("compare [urlA] [urlB]")
+        .description("Compare two audits — by URL (run audits) or by file (LLM analysis)")
+        .option("--before <path>", "Baseline audit JSON file")
+        .option("--after <path>", "Current audit JSON file")
+        .option("--mode <mode>", "Audit depth: basic|standard|deep", "basic")
+        .option("--wait", "Wait for audits to complete (URL mode)")
+        .option("--timeout <ms>", "Wait timeout in milliseconds", "60000")
+        .option("--interval <ms>", "Poll interval in milliseconds", "5000")
+        .option("--fail-on-score <n>", "Exit non-zero if score below n (0-100)")
+        .option("-f, --format <format>", "Output format: json | human")
+        .addHelpText("after", `
+Examples:
+  vertaa compare https://a.com https://b.com --wait
+  vertaa compare --before baseline.json --after current.json
+  vertaa compare --before baseline.json --after current.json --verbose
+`)
+        .action(async (urlA, urlB, options, command) => {
+        try {
+            const globalOpts = command.optsWithGlobals();
+            const config = await resolveConfig(globalOpts.config);
+            const machineMode = globalOpts.machine || false;
+            const verbose = globalOpts.verbose || false;
+            const format = resolveCommandFormat("compare", options.format, machineMode);
+            // Decide mode: file-based LLM or URL-based legacy
+            const isFileMode = options.before || options.after;
+            if (isFileMode) {
+                await runLlmCompare(options, globalOpts, config, format, verbose);
+            }
+            else if (urlA && urlB) {
+                await runUrlCompare(urlA, urlB, options, globalOpts, config, format);
+            }
+            else {
+                console.error("Error: Provide either two URLs or --before/--after files.");
+                console.error("Usage:");
+                console.error("  vertaa compare https://a.com https://b.com --wait");
+                console.error("  vertaa compare --before baseline.json --after current.json");
+                process.exit(ExitCode.ERROR);
+            }
+        }
+        catch (error) {
+            console.error("Error:", error instanceof Error ? error.message : String(error));
+            process.exit(ExitCode.ERROR);
+        }
+    });
+}
+// ---------------------------------------------------------------------------
+// LLM-based comparison (new)
+// ---------------------------------------------------------------------------
+async function runLlmCompare(options, globalOpts, config, format, verbose) {
+    if (!options.before || !options.after) {
+        console.error("Error: Both --before and --after are required for file-based comparison.");
+        process.exit(ExitCode.ERROR);
+    }
+    const beforeInput = await readJsonInput(options.before);
+    const afterInput = await readJsonInput(options.after);
+    if (!beforeInput || !afterInput) {
+        console.error("Error: Could not read audit files.");
+        process.exit(ExitCode.ERROR);
+    }
+    function extractPayload(input) {
+        const data = input;
+        const inner = (data.data && typeof data.data === "object" ? data.data : data);
+        const issues = normalizeIssues(inner.issues);
+        return {
+            job_id: inner.job_id || null,
+            url: inner.url || null,
+            scores: inner.scores || null,
+            issues,
+        };
+    }
+    const beforePayload = extractPayload(beforeInput);
+    const afterPayload = extractPayload(afterInput);
+    const base = resolveApiBase(globalOpts.base);
+    const apiKey = getApiKey(config.apiKey);
+    const spinner = createSpinner("Comparing audits...");
+    try {
+        const response = await Promise.race([
+            apiRequest(base, "/cli/ai/compare", { method: "POST", body: { before: beforePayload, after: afterPayload } }, apiKey),
+            new Promise((_, reject) => setTimeout(() => reject(new Error("LLM request timed out")), AI_TIMEOUT_MS)),
+        ]);
+        succeedSpinner(spinner, "Comparison complete");
+        if (format === "json") {
+            writeJsonOutput(response.data, "compare");
+        }
+        else {
+            writeOutput(formatLlmCompareHuman(response.data, verbose));
+        }
+    }
+    catch (error) {
+        handleAiCommandError(error, "compare", spinner);
+    }
+}
+// ---------------------------------------------------------------------------
+// URL-based comparison (legacy backward compat)
+// ---------------------------------------------------------------------------
+async function runUrlCompare(urlA, urlB, options, globalOpts, config, format) {
+    const base = resolveApiBase(globalOpts.base);
+    const apiKey = getApiKey(config.apiKey);
+    const mode = options.mode || "basic";
+    const spinner = createSpinner("Starting audits...");
+    const jobA = await apiRequest(base, "/audit", {
+        method: "POST",
+        body: { url: urlA, mode },
+    }, apiKey);
+    const jobB = await apiRequest(base, "/audit", {
+        method: "POST",
+        body: { url: urlB, mode },
+    }, apiKey);
+    if (!options.wait) {
+        succeedSpinner(spinner, "Audits queued");
+        const payload = { job_a: jobA, job_b: jobB };
+        if (format === "json") {
+            writeJsonOutput(payload, "compare");
+        }
+        else {
+            writeOutput(`Audit comparison queued:\n  Job A: ${jobA.job_id}\n  Job B: ${jobB.job_id}`);
+        }
+        return;
+    }
+    if (!jobA.job_id || !jobB.job_id) {
+        failSpinner(spinner, "Missing job IDs");
+        throw new Error("Compare response missing job_id");
+    }
+    const timeout = parseInt(options.timeout || "60000", 10);
+    const interval = parseInt(options.interval || "5000", 10);
+    const [resultA, resultB] = await Promise.all([
+        waitForAudit(base, jobA.job_id, timeout, interval, apiKey),
+        waitForAudit(base, jobB.job_id, timeout, interval, apiKey),
+    ]);
+    succeedSpinner(spinner, "Audits complete");
+    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 compareData = {
+        urlA,
+        urlB,
+        jobA: resultA.job_id || "",
+        jobB: resultB.job_id || "",
+        overallA,
+        overallB,
+        delta,
+        categoryDeltas,
+        issuesA,
+        issuesB,
+    };
+    const failOnScore = options.failOnScore ? parseInt(options.failOnScore, 10) : undefined;
+    if (failOnScore !== undefined &&
+        ((overallA !== null && overallA < failOnScore) ||
+            (overallB !== null && overallB < failOnScore))) {
+        process.exitCode = 1;
+    }
+    if (format === "json") {
+        writeJsonOutput(compareData, "compare");
+    }
+    else {
+        writeOutput(formatLegacyCompareHuman(compareData));
+    }
+}

package/dist/commands/doc.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Doc command for VertaaUX CLI.
+ *
+ * Accepts full audit JSON (via stdin, --file, or --job) and calls the
+ * LLM doc endpoint to produce a "Team Playbook" markdown document from
+ * recurring findings — patterns, root causes, correct implementations,
+ * and copy/paste checklists.
+ *
+ * Default output is markdown; use --format json for structured output.
+ *
+ * Examples:
+ *   vertaa audit https://example.com --json | vertaa doc
+ *   vertaa doc --job abc123
+ *   vertaa doc --file audit.json --team "Frontend Team"
+ */
+import { Command } from "commander";
+export declare function registerDocCommand(program: Command): void;
+//# sourceMappingURL=doc.d.ts.map

package/dist/commands/doc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doc.d.ts","sourceRoot":"","sources":["../../src/commands/doc.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAqFpC,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAoHzD"}

package/dist/commands/doc.js

@@ -0,0 +1,161 @@
+/**
+ * Doc command for VertaaUX CLI.
+ *
+ * Accepts full audit JSON (via stdin, --file, or --job) and calls the
+ * LLM doc endpoint to produce a "Team Playbook" markdown document from
+ * recurring findings — patterns, root causes, correct implementations,
+ * and copy/paste checklists.
+ *
+ * Default output is markdown; use --format json for structured output.
+ *
+ * Examples:
+ *   vertaa audit https://example.com --json | vertaa doc
+ *   vertaa doc --job abc123
+ *   vertaa doc --file audit.json --team "Frontend Team"
+ */
+import chalk from "chalk";
+import { ExitCode } from "../utils/exit-codes.js";
+import { resolveApiBase, getApiKey, apiRequest } from "../utils/client.js";
+import { resolveConfig } from "../config/loader.js";
+import { writeJsonOutput, writeOutput } from "../output/envelope.js";
+import { resolveCommandFormat } from "../output/formats.js";
+import { createSpinner, succeedSpinner } from "../ui/spinner.js";
+import { readJsonInput } from "../utils/stdin.js";
+import { handleAiCommandError, AI_TIMEOUT_MS } from "../utils/ai-error.js";
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function normalizeIssues(issues) {
+    let list;
+    if (Array.isArray(issues)) {
+        list = issues;
+    }
+    else if (issues && typeof issues === "object") {
+        list = Object.values(issues).flatMap((v) => Array.isArray(v) ? v : []);
+    }
+    else {
+        return [];
+    }
+    return list.map((raw) => {
+        const i = raw;
+        return {
+            id: i.id || i.ruleId || i.rule_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,
+        };
+    });
+}
+// ---------------------------------------------------------------------------
+// Formatters
+// ---------------------------------------------------------------------------
+function formatDocHuman(data) {
+    const lines = [];
+    lines.push(chalk.bold(data.title));
+    lines.push(chalk.dim("─".repeat(40)));
+    lines.push(chalk.dim(`Sections: ${data.sections.join(", ")}`));
+    lines.push("");
+    lines.push(data.content);
+    return lines.join("\n");
+}
+// ---------------------------------------------------------------------------
+// Command Registration
+// ---------------------------------------------------------------------------
+export function registerDocCommand(program) {
+    program
+        .command("doc")
+        .description("Generate a Team Playbook document from recurring audit findings")
+        .option("--job <job-id>", "Fetch audit data from a job ID")
+        .option("--file <path>", "Load audit JSON from file")
+        .option("--team <name>", "Team name for the playbook header")
+        .option("-f, --format <format>", "Output format: json | markdown")
+        .addHelpText("after", `
+Examples:
+  vertaa audit https://example.com --json | vertaa doc
+  vertaa doc --job abc123
+  vertaa doc --file audit.json --team "Frontend Team"
+`)
+        .action(async (options, command) => {
+        try {
+            const globalOpts = command.optsWithGlobals();
+            const config = await resolveConfig(globalOpts.config);
+            const machineMode = globalOpts.machine || false;
+            const format = resolveCommandFormat("doc", options.format, machineMode);
+            // Resolve audit data
+            let auditPayload;
+            if (options.job) {
+                const base = resolveApiBase(globalOpts.base);
+                const apiKey = getApiKey(config.apiKey);
+                const result = await apiRequest(base, `/audit/${options.job}`, { method: "GET" }, apiKey);
+                const issues = normalizeIssues(result.issues);
+                auditPayload = {
+                    job_id: result.job_id || options.job,
+                    url: result.url || null,
+                    scores: result.scores || null,
+                    issues,
+                };
+            }
+            else {
+                const input = await readJsonInput(options.file);
+                if (!input) {
+                    console.error("Error: No audit data provided.");
+                    console.error("Usage:");
+                    console.error("  vertaa audit https://example.com --json | vertaa doc");
+                    console.error("  vertaa doc --job <job-id>");
+                    console.error("  vertaa doc --file audit.json");
+                    process.exit(ExitCode.ERROR);
+                }
+                const data = input;
+                const innerData = (data.data && typeof data.data === "object" ? data.data : data);
+                const issues = normalizeIssues(innerData.issues);
+                auditPayload = {
+                    job_id: innerData.job_id || null,
+                    url: innerData.url || null,
+                    scores: innerData.scores || null,
+                    issues,
+                };
+            }
+            if (!Array.isArray(auditPayload.issues) ||
+                auditPayload.issues.length === 0) {
+                console.error("Error: No issues found in audit data.");
+                process.exit(ExitCode.ERROR);
+            }
+            // Auth check
+            const base = resolveApiBase(globalOpts.base);
+            const apiKey = getApiKey(config.apiKey);
+            // Call LLM doc API
+            const spinner = createSpinner("Generating team playbook...");
+            try {
+                const response = await Promise.race([
+                    apiRequest(base, "/cli/ai/doc", {
+                        method: "POST",
+                        body: {
+                            audit: auditPayload,
+                            teamName: options.team || null,
+                        },
+                    }, apiKey),
+                    new Promise((_, reject) => setTimeout(() => reject(new Error("LLM request timed out")), AI_TIMEOUT_MS)),
+                ]);
+                succeedSpinner(spinner, "Playbook ready");
+                if (format === "json") {
+                    writeJsonOutput(response.data, "doc");
+                }
+                else {
+                    // Default markdown output — just emit the content directly
+                    writeOutput(format === "markdown" ? response.data.content : formatDocHuman(response.data));
+                }
+            }
+            catch (error) {
+                handleAiCommandError(error, "doc", spinner);
+            }
+        }
+        catch (error) {
+            console.error("Error:", error instanceof Error ? error.message : String(error));
+            process.exit(ExitCode.ERROR);
+        }
+    });
+}

package/dist/commands/download.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"download.d.ts","sourceRoot":"","sources":["../../src/commands/download.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAsNpC;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAkB9D"}
+{"version":3,"file":"download.d.ts","sourceRoot":"","sources":["../../src/commands/download.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAuNpC;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAkB9D"}

package/dist/commands/download.js

@@ -7,7 +7,7 @@
 import fs from "fs";
 import path from "path";
 import chalk from "chalk";
-import ora from "ora";
+import { createSpinner, succeedSpinner, failSpinner, warnSpinner, infoSpinner } from "../ui/spinner.js";
 import { loadToken } from "../auth/token-store.js";
 import { getCIToken } from "../auth/ci-token.js";
 import { resolveApiBase } from "../utils/client.js";
@@ -47,7 +47,8 @@ async function handleDownload(jobId, options) {
     const config = await resolveConfig(options.configPath);
     const apiBase = resolveApiBase(options.base);
     const outputDir = options.output || DEFAULT_OUTPUT_DIR;
-    const spinner = ora(`Downloading audit ${jobId}...`).start();
+    const spinner = createSpinner(`Downloading audit ${jobId}...`);
+    spinner.start();
     try {
         // Build request URL
         let url = `${apiBase}/sync/download/${jobId}`;
@@ -83,14 +84,14 @@ async function handleDownload(jobId, options) {
                 if (isInteractive()) {
                     const overwrite = await confirmAction(`File ${auditPath} already exists. Overwrite?`, false);
                     if (!overwrite) {
-                        spinner.info("Skipping audit results (file exists).");
+                        infoSpinner(spinner, "Skipping audit results (file exists).");
                     }
                     else {
                         fs.writeFileSync(auditPath, JSON.stringify(result.audit, null, 2), "utf-8");
                     }
                 }
                 else {
-                    spinner.warn(`Skipping ${auditPath} (already exists, use --force to overwrite)`);
+                    warnSpinner(spinner, `Skipping ${auditPath} (already exists, use --force to overwrite)`);
                 }
             }
             else {
@@ -105,14 +106,14 @@ async function handleDownload(jobId, options) {
                 if (isInteractive()) {
                     const overwrite = await confirmAction(`Baseline file already exists. Overwrite?`, false);
                     if (!overwrite) {
-                        spinner.info("Skipping baseline (file exists).");
+                        infoSpinner(spinner, "Skipping baseline (file exists).");
                     }
                     else {
                         await saveBaseline(result.baseline, baselinePath);
                     }
                 }
                 else {
-                    spinner.warn(`Skipping baseline (already exists, use --force to overwrite)`);
+                    warnSpinner(spinner, `Skipping baseline (already exists, use --force to overwrite)`);
                 }
             }
             else {
@@ -144,7 +145,7 @@ async function handleDownload(jobId, options) {
                 }
             }
         }
-        spinner.succeed("Download complete!");
+        succeedSpinner(spinner, "Download complete!");
         console.error("");
         console.error(`  Job ID:  ${result.job_id}`);
         console.error(`  Output:  ${resolvedOutputDir}`);
@@ -160,7 +161,7 @@ async function handleDownload(jobId, options) {
         console.error("");
     }
     catch (error) {
-        spinner.fail("Download failed");
+        failSpinner(spinner, "Download failed");
         console.error(chalk.red("Error:"), error instanceof Error ? error.message : String(error));
         process.exit(ExitCode.ERROR);
     }

package/dist/commands/explain.d.ts

@@ -1,17 +1,19 @@
 /**
  * Explain command for VertaaUX CLI.
  *
- * Shows full evidence bundle for a specific finding:
- * - Description
- * - Selector
- * - WCAG reference
- * - Recommendation
- * - Related artifacts (screenshots, DOM)
+ * Two modes:
+ * 1. **AI mode** (no finding-id): Accepts full audit JSON via stdin, --file,
+ *    or --job. Calls the LLM explain endpoint to produce a 3-bullet summary
+ *    and per-issue explanations. Use --verbose for full evidence per issue.
  *
- * Supports loading issues from:
- * - Active job via --job flag
- * - Local JSON file via --file flag
- * - Recent audits from .vertaaux/recent.json
+ * 2. **Evidence mode** (with finding-id): Shows the full evidence bundle for
+ *    a specific finding (backward compatible with existing usage).
+ *
+ * Examples:
+ *   vertaa audit https://example.com --json | vertaa explain
+ *   vertaa explain --job abc123
+ *   vertaa explain --file audit.json --verbose
+ *   vertaa explain color-contrast-001 --job abc123   (legacy mode)
  */
 import { Command } from "commander";
 import type { Issue } from "../baseline/hash.js";
@@ -19,44 +21,23 @@ import type { Issue } from "../baseline/hash.js";
  * Extended issue type with additional evidence fields.
  */
 export interface EvidenceIssue extends Issue {
-    /** DOM snippet showing the issue */
     html?: string;
-    /** Element HTML snippet */
     element?: string;
-    /** Screenshot path or URL */
     screenshot?: string;
-    /** Help URL for the rule */
     helpUrl?: string;
 }
 /**
  * Format a full evidence bundle for display.
- *
- * @param issue - Issue with evidence
- * @returns Formatted string for terminal display
  */
 export declare function formatEvidenceBundle(issue: EvidenceIssue): string;
-/**
- * Format evidence as JSON.
- */
 export declare function formatEvidenceJson(issue: EvidenceIssue): string;
-/**
- * Export for reuse in fix-wizard.
- *
- * @param issue - Issue to explain
- * @returns Formatted evidence string
- */
+/** Exported for reuse in fix-wizard. */
 export declare function explainIssue(issue: EvidenceIssue): string;
-/**
- * Command options for explain.
- */
 export interface ExplainCommandOptions {
     job?: string;
     file?: string;
-    format?: "json" | "human";
+    format?: string;
     base?: string;
 }
-/**
- * Register the explain command with the Commander program.
- */
 export declare function registerExplainCommand(program: Command): void;
 //# sourceMappingURL=explain.d.ts.map

package/dist/commands/explain.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"explain.d.ts","sourceRoot":"","sources":["../../src/commands/explain.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AASpC,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAEjD;;GAEG;AACH,MAAM,WAAW,aAAc,SAAQ,KAAK;IAC1C,oCAAoC;IACpC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,2BAA2B;IAC3B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,6BAA6B;IAC7B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4BAA4B;IAC5B,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAyED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,CAyDjE;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,CAgB/D;AAUD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,CAEzD;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAC1B,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAgK7D"}
+{"version":3,"file":"explain.d.ts","sourceRoot":"","sources":["../../src/commands/explain.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAYpC,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAMjD;;GAEG;AACH,MAAM,WAAW,aAAc,SAAQ,KAAK;IAC1C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAiFD;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,CAyCjE;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,CAmB/D;AAED,wCAAwC;AACxC,wBAAgB,YAAY,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,CAEzD;AAqRD,MAAM,WAAW,qBAAqB;IACpC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA+C7D"}