@vertaaux/cli 0.2.2 → 0.3.0

package/dist/commands/explain.js

@@ -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 fs from "fs";
 import path from "path";
@@ -21,47 +23,39 @@ 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";
-/**
- * Path to recent audits cache.
- */
+import { createSpinner, succeedSpinner } from "../ui/spinner.js";
+import { readJsonInput } from "../utils/stdin.js";
+import { handleAiCommandError, AI_TIMEOUT_MS } from "../utils/ai-error.js";
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
 const RECENT_AUDITS_PATH = ".vertaaux/recent.json";
-/**
- * Load recent audits from cache file.
- */
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
 function loadRecentAudits() {
     const filePath = path.resolve(process.cwd(), RECENT_AUDITS_PATH);
-    if (!fs.existsSync(filePath)) {
+    if (!fs.existsSync(filePath))
         return [];
-    }
     try {
-        const content = fs.readFileSync(filePath, "utf-8");
-        return JSON.parse(content);
+        return JSON.parse(fs.readFileSync(filePath, "utf-8"));
     }
     catch {
         return [];
     }
 }
-/**
- * Normalize issues from various API response formats.
- */
 function normalizeIssues(issues) {
     if (Array.isArray(issues))
         return issues;
     if (issues && typeof issues === "object") {
         const values = Object.values(issues);
-        return values.flatMap((value) => Array.isArray(value) ? value : []);
+        return values.flatMap((v) => (Array.isArray(v) ? v : []));
     }
     return [];
 }
-/**
- * Get display-friendly rule ID from issue.
- */
 function getRuleId(issue) {
     return issue.ruleId || issue.rule_id || issue.id || "unknown";
 }
-/**
- * Get severity label with appropriate color.
- */
 function coloredSeverity(severity) {
     const sev = (severity || "info").toLowerCase();
     switch (sev) {
@@ -78,64 +72,57 @@ function coloredSeverity(severity) {
             return chalk.dim(sev.toUpperCase());
     }
 }
+function truncate(str, maxLength) {
+    if (str.length <= maxLength)
+        return str;
+    return str.slice(0, maxLength - 3) + "...";
+}
+// ---------------------------------------------------------------------------
+// Evidence mode formatters (backward compat)
+// ---------------------------------------------------------------------------
 /**
  * Format a full evidence bundle for display.
- *
- * @param issue - Issue with evidence
- * @returns Formatted string for terminal display
  */
 export function formatEvidenceBundle(issue) {
     const lines = [];
-    // Header
     const ruleId = getRuleId(issue);
     const severity = coloredSeverity(issue.severity);
     lines.push(chalk.bold(`ISSUE: ${ruleId} (${severity})`));
     lines.push("");
-    // Description
     lines.push(chalk.cyan.bold("DESCRIPTION"));
     lines.push(issue.description || issue.title || "No description available");
     lines.push("");
-    // Selector
     if (issue.selector) {
         lines.push(chalk.cyan.bold("SELECTOR"));
         lines.push(chalk.gray(issue.selector));
         lines.push("");
     }
-    // WCAG Reference
     if (issue.wcag_reference) {
         lines.push(chalk.cyan.bold("WCAG REFERENCE"));
         lines.push(issue.wcag_reference);
         lines.push("");
     }
-    // Recommendation
     const recommendation = issue.recommendation || issue.recommended_fix;
     if (recommendation) {
         lines.push(chalk.cyan.bold("RECOMMENDATION"));
         lines.push(recommendation);
         lines.push("");
     }
-    // Evidence section
     const hasEvidence = issue.screenshot || issue.html || issue.element || issue.helpUrl;
     if (hasEvidence) {
         lines.push(chalk.cyan.bold("EVIDENCE"));
-        if (issue.screenshot) {
+        if (issue.screenshot)
             lines.push(`- Screenshot: ${chalk.underline(issue.screenshot)}`);
-        }
         if (issue.html || issue.element) {
-            const snippet = issue.html || issue.element || "";
-            lines.push(`- DOM Snapshot: ${chalk.dim(truncate(snippet, 100))}`);
+            lines.push(`- DOM Snapshot: ${chalk.dim(truncate(issue.html || issue.element || "", 100))}`);
         }
-        if (issue.helpUrl) {
+        if (issue.helpUrl)
             lines.push(`- Help: ${chalk.underline(issue.helpUrl)}`);
-        }
     }
     return lines.join("\n");
 }
-/**
- * Format evidence as JSON.
- */
 export function formatEvidenceJson(issue) {
-    const output = {
+    return JSON.stringify({
         ruleId: getRuleId(issue),
         severity: issue.severity,
         category: issue.category,
@@ -148,150 +135,261 @@ export function formatEvidenceJson(issue) {
             html: issue.html || issue.element,
             helpUrl: issue.helpUrl,
         },
-    };
-    return JSON.stringify(output, null, 2);
-}
-/**
- * Truncate string with ellipsis.
- */
-function truncate(str, maxLength) {
-    if (str.length <= maxLength)
-        return str;
-    return str.slice(0, maxLength - 3) + "...";
+    }, null, 2);
 }
-/**
- * Export for reuse in fix-wizard.
- *
- * @param issue - Issue to explain
- * @returns Formatted evidence string
- */
+/** Exported for reuse in fix-wizard. */
 export function explainIssue(issue) {
     return formatEvidenceBundle(issue);
 }
-/**
- * Register the explain command with the Commander program.
- */
+// ---------------------------------------------------------------------------
+// AI mode formatters
+// ---------------------------------------------------------------------------
+function formatAiExplainHuman(response, verbose, issues) {
+    const lines = [];
+    // 3-bullet summary
+    lines.push(chalk.bold("Summary"));
+    for (const bullet of response.summary) {
+        lines.push(`  ${chalk.cyan(">")} ${bullet}`);
+    }
+    lines.push("");
+    // Issues grouped by severity
+    lines.push(chalk.bold("Issues"));
+    lines.push("");
+    for (const issue of response.issues) {
+        const severity = coloredSeverity(issue.severity);
+        lines.push(`  ${severity} ${chalk.bold(issue.title)}${issue.id ? chalk.dim(` (${issue.id})`) : ""}`);
+        lines.push(`  ${issue.explanation}`);
+        lines.push(`  ${chalk.green("Fix:")} ${issue.fix}`);
+        if (verbose && issues) {
+            // Find the matching original issue for full evidence
+            const original = issues.find((i) => getRuleId(i) === issue.id || i.id === issue.id);
+            if (original) {
+                if (original.selector)
+                    lines.push(`  ${chalk.dim("Selector:")} ${original.selector}`);
+                if (original.wcag_reference)
+                    lines.push(`  ${chalk.dim("WCAG:")} ${original.wcag_reference}`);
+            }
+        }
+        lines.push("");
+    }
+    return lines.join("\n");
+}
+// ---------------------------------------------------------------------------
+// Evidence mode handler (backward compat)
+// ---------------------------------------------------------------------------
+async function handleEvidenceMode(findingId, options, config, format) {
+    let issue = null;
+    if (options.file) {
+        const filePath = path.resolve(process.cwd(), options.file);
+        if (!fs.existsSync(filePath)) {
+            console.error(`Error: File not found: ${filePath}`);
+            process.exit(ExitCode.ERROR);
+        }
+        const data = JSON.parse(fs.readFileSync(filePath, "utf-8"));
+        let issues;
+        if (Array.isArray(data)) {
+            issues = data;
+        }
+        else if (data.issues) {
+            issues = normalizeIssues(data.issues);
+        }
+        else {
+            if (data.id === findingId || data.ruleId === findingId)
+                issue = data;
+            issues = [];
+        }
+        if (!issue) {
+            issue = issues.find((i) => i.id === findingId ||
+                getRuleId(i) === findingId ||
+                i.id?.startsWith(findingId) ||
+                getRuleId(i).startsWith(findingId)) || null;
+        }
+    }
+    else if (options.job) {
+        const base = resolveApiBase(options.base);
+        const apiKey = getApiKey(config.apiKey);
+        const result = await apiRequest(base, `/audit/${options.job}`, { method: "GET" }, apiKey);
+        const issues = normalizeIssues(result.issues);
+        issue = issues.find((i) => i.id === findingId ||
+            getRuleId(i) === findingId ||
+            i.id?.startsWith(findingId) ||
+            getRuleId(i).startsWith(findingId)) || null;
+    }
+    else {
+        const recent = loadRecentAudits();
+        if (recent.length === 0) {
+            console.error("Error: No recent audits found. Provide --job or --file option.");
+            process.exit(ExitCode.ERROR);
+        }
+        const base = resolveApiBase(options.base);
+        const apiKey = getApiKey(config.apiKey);
+        for (const audit of recent) {
+            try {
+                const result = await apiRequest(base, `/audit/${audit.jobId}`, { method: "GET" }, apiKey);
+                const issues = normalizeIssues(result.issues);
+                issue = issues.find((i) => i.id === findingId ||
+                    getRuleId(i) === findingId ||
+                    i.id?.startsWith(findingId) ||
+                    getRuleId(i).startsWith(findingId)) || null;
+                if (issue)
+                    break;
+            }
+            catch {
+                continue;
+            }
+        }
+    }
+    if (!issue) {
+        console.error(`Error: Finding "${findingId}" not found.`);
+        if (options.job)
+            console.error(`Looked in job: ${options.job}`);
+        else if (options.file)
+            console.error(`Looked in file: ${options.file}`);
+        else
+            console.error("Try specifying --job or --file to narrow the search.");
+        process.exit(ExitCode.ERROR);
+    }
+    if (format === "json") {
+        writeJsonOutput({
+            ruleId: getRuleId(issue),
+            severity: issue.severity,
+            category: issue.category,
+            description: issue.description || issue.title,
+            selector: issue.selector,
+            wcagReference: issue.wcag_reference,
+            recommendation: issue.recommendation || issue.recommended_fix,
+            evidence: {
+                screenshot: issue.screenshot,
+                html: issue.html || issue.element,
+                helpUrl: issue.helpUrl,
+            },
+        }, "explain");
+    }
+    else {
+        writeOutput(formatEvidenceBundle(issue));
+    }
+}
+// ---------------------------------------------------------------------------
+// AI mode handler
+// ---------------------------------------------------------------------------
+async function handleAiMode(options, config, format, verbose) {
+    // Read audit JSON from stdin, --file, or --job
+    let auditData = null;
+    let rawIssues = [];
+    if (options.job) {
+        // Fetch full audit from API
+        const base = resolveApiBase(options.base, undefined);
+        const apiKey = getApiKey(config.apiKey);
+        const result = await apiRequest(base, `/audit/${options.job}`, { method: "GET" }, apiKey);
+        rawIssues = normalizeIssues(result.issues);
+        auditData = {
+            job_id: result.job_id || options.job,
+            url: result.url || null,
+            scores: result.scores || null,
+            issues: rawIssues.map((i) => ({
+                id: i.id || getRuleId(i),
+                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,
+            })),
+        };
+    }
+    else {
+        // Read from stdin or --file
+        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 explain");
+            console.error("  vertaa explain --file audit.json");
+            console.error("  vertaa explain --job <job-id>");
+            console.error("  vertaa explain <finding-id> --job <job-id>");
+            process.exit(ExitCode.ERROR);
+        }
+        const data = input;
+        // Handle the envelope format { meta: {...}, data: {...} }
+        const innerData = (data.data && typeof data.data === "object" ? data.data : data);
+        rawIssues = normalizeIssues(innerData.issues);
+        auditData = {
+            job_id: innerData.job_id || null,
+            url: innerData.url || null,
+            scores: innerData.scores || null,
+            issues: rawIssues.map((i) => ({
+                id: i.id || getRuleId(i),
+                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,
+            })),
+        };
+    }
+    if (!auditData ||
+        !Array.isArray(auditData.issues) ||
+        auditData.issues.length === 0) {
+        console.error("Error: No issues found in audit data.");
+        process.exit(ExitCode.ERROR);
+    }
+    // Call the LLM explain API
+    const base = resolveApiBase(options.base, undefined);
+    const apiKey = getApiKey(config.apiKey);
+    const spinner = createSpinner("Analyzing findings...");
+    try {
+        const response = await Promise.race([
+            apiRequest(base, "/cli/ai/explain", { method: "POST", body: { audit: auditData } }, apiKey),
+            new Promise((_, reject) => setTimeout(() => reject(new Error("LLM request timed out")), AI_TIMEOUT_MS)),
+        ]);
+        succeedSpinner(spinner, "Analysis complete");
+        if (format === "json") {
+            writeJsonOutput(response.data, "explain");
+        }
+        else {
+            writeOutput(formatAiExplainHuman(response.data, verbose, rawIssues));
+        }
+    }
+    catch (error) {
+        handleAiCommandError(error, "explain", spinner);
+    }
+}
 export function registerExplainCommand(program) {
     program
-        .command("explain <finding-id>")
-        .description("Show full evidence bundle for a finding")
-        .option("--job <job-id>", "Job ID containing the finding")
-        .option("--file <path>", "Load findings from local JSON file")
-        .option("-f, --format <format>", "Output format: json | human", "human")
+        .command("explain [finding-id]")
+        .description("Explain audit findings with AI, or show evidence for a specific finding")
+        .option("--job <job-id>", "Job ID (for fetching audit data or finding)")
+        .option("--file <path>", "Load audit JSON from file")
+        .option("-f, --format <format>", "Output format: json | human")
+        .addHelpText("after", `
+Modes:
+  AI mode (no finding-id):
+    vertaa audit https://example.com --json | vertaa explain
+    vertaa explain --job <job-id>
+    vertaa explain --file audit.json
+    vertaa explain --file audit.json --verbose
+
+  Evidence mode (with finding-id):
+    vertaa explain color-contrast-001 --job <job-id>
+    vertaa explain axe-label --file results.json
+`)
         .action(async (findingId, options, command) => {
         try {
-            // Load config (supports --config global option)
             const globalOpts = command.optsWithGlobals();
             const config = await resolveConfig(globalOpts.config);
-            // Validate format using per-command registry
             const machineMode = globalOpts.machine || false;
+            const verbose = globalOpts.verbose || false;
             const format = resolveCommandFormat("explain", options.format, machineMode);
-            let issue = null;
-            if (options.file) {
-                // Load from local file
-                const filePath = path.resolve(process.cwd(), options.file);
-                if (!fs.existsSync(filePath)) {
-                    console.error(`Error: File not found: ${filePath}`);
-                    process.exit(ExitCode.ERROR);
-                }
-                const content = fs.readFileSync(filePath, "utf-8");
-                const data = JSON.parse(content);
-                // Handle different file structures
-                let issues;
-                if (Array.isArray(data)) {
-                    issues = data;
-                }
-                else if (data.issues) {
-                    issues = normalizeIssues(data.issues);
-                }
-                else {
-                    // Single issue object
-                    if (data.id === findingId || data.ruleId === findingId) {
-                        issue = data;
-                    }
-                    issues = [];
-                }
-                if (!issue) {
-                    issue =
-                        issues.find((i) => i.id === findingId ||
-                            getRuleId(i) === findingId ||
-                            i.id?.startsWith(findingId) ||
-                            getRuleId(i).startsWith(findingId)) || null;
-                }
-            }
-            else if (options.job) {
-                // Fetch from API
-                const base = resolveApiBase(options.base);
-                const apiKey = getApiKey(config.apiKey);
-                const result = await apiRequest(base, `/audit/${options.job}`, { method: "GET" }, apiKey);
-                const issues = normalizeIssues(result.issues);
-                issue =
-                    issues.find((i) => i.id === findingId ||
-                        getRuleId(i) === findingId ||
-                        i.id?.startsWith(findingId) ||
-                        getRuleId(i).startsWith(findingId)) || null;
-            }
-            else {
-                // Try recent audits
-                const recent = loadRecentAudits();
-                if (recent.length === 0) {
-                    console.error("Error: No recent audits found. Provide --job or --file option.");
-                    process.exit(ExitCode.ERROR);
-                }
-                // Try each recent audit
-                const base = resolveApiBase(options.base);
-                const apiKey = getApiKey(config.apiKey);
-                for (const audit of recent) {
-                    try {
-                        const result = await apiRequest(base, `/audit/${audit.jobId}`, { method: "GET" }, apiKey);
-                        const issues = normalizeIssues(result.issues);
-                        issue =
-                            issues.find((i) => i.id === findingId ||
-                                getRuleId(i) === findingId ||
-                                i.id?.startsWith(findingId) ||
-                                getRuleId(i).startsWith(findingId)) || null;
-                        if (issue)
-                            break;
-                    }
-                    catch {
-                        // Try next audit
-                        continue;
-                    }
-                }
-            }
-            if (!issue) {
-                console.error(`Error: Finding "${findingId}" not found.`);
-                if (options.job) {
-                    console.error(`Looked in job: ${options.job}`);
-                }
-                else if (options.file) {
-                    console.error(`Looked in file: ${options.file}`);
-                }
-                else {
-                    console.error("Try specifying --job or --file to narrow the search.");
-                }
-                process.exit(ExitCode.ERROR);
-            }
-            // Output
-            if (format === "json") {
-                const evidenceData = {
-                    ruleId: getRuleId(issue),
-                    severity: issue.severity,
-                    category: issue.category,
-                    description: issue.description || issue.title,
-                    selector: issue.selector,
-                    wcagReference: issue.wcag_reference,
-                    recommendation: issue.recommendation || issue.recommended_fix,
-                    evidence: {
-                        screenshot: issue.screenshot,
-                        html: issue.html || issue.element,
-                        helpUrl: issue.helpUrl,
-                    },
-                };
-                writeJsonOutput(evidenceData, "explain");
+            if (findingId) {
+                // Backward-compatible evidence mode
+                await handleEvidenceMode(findingId, options, config, format);
             }
             else {
-                writeOutput(formatEvidenceBundle(issue));
+                // AI-powered explain mode
+                await handleAiMode(options, config, format, verbose);
             }
         }
         catch (error) {

package/dist/commands/fix-plan.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Fix-plan command for VertaaUX CLI.
+ *
+ * Accepts full audit JSON (via stdin, --file, or --job) and calls the
+ * LLM fix-plan endpoint to produce a structured remediation plan with
+ * ordered steps, effort estimates, and code hints.
+ *
+ * Examples:
+ *   vertaa audit https://example.com --json | vertaa fix-plan
+ *   vertaa fix-plan --job abc123
+ *   vertaa fix-plan --file audit.json --json
+ */
+import { Command } from "commander";
+export declare function registerFixPlanCommand(program: Command): void;
+//# sourceMappingURL=fix-plan.d.ts.map

package/dist/commands/fix-plan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fix-plan.d.ts","sourceRoot":"","sources":["../../src/commands/fix-plan.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAuIpC,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA6G7D"}