@vertaaux/cli 0.4.0 → 0.5.1

package/dist/commands/explain.js

@@ -17,15 +17,15 @@
  */
 import fs from "fs";
 import path from "path";
-import chalk from "chalk";
+import { bold, dim, colorize, boldColor, brand, severity as severityPalette, renderError, createRenderer, runSteps } from "@vertaaux/tui";
 import { ExitCode } from "../utils/exit-codes.js";
-import { resolveApiBase, getApiKey, apiRequest } from "../utils/client.js";
+import { resolveApiBase, getApiKey, apiRequest, createClient } from "../utils/client.js";
 import { resolveConfig } from "../config/loader.js";
-import { writeJsonOutput, writeOutput } from "../output/envelope.js";
+import { writeDataOutput, writeJsonOutput } 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";
+import { AI_TIMEOUT_MS } from "../utils/ai-error.js";
+import { strings } from "../ui/strings.js";
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
@@ -61,15 +61,15 @@ function coloredSeverity(severity) {
     switch (sev) {
         case "critical":
         case "error":
-            return chalk.red.bold(sev.toUpperCase());
+            return boldColor(sev.toUpperCase(), severityPalette.error);
         case "serious":
         case "warning":
-            return chalk.yellow.bold(sev.toUpperCase());
+            return boldColor(sev.toUpperCase(), severityPalette.warning);
         case "moderate":
         case "minor":
-            return chalk.cyan(sev.toUpperCase());
+            return colorize(sev.toUpperCase(), brand.cyan);
         default:
-            return chalk.dim(sev.toUpperCase());
+            return dim(sev.toUpperCase());
     }
 }
 function truncate(str, maxLength) {
@@ -87,37 +87,37 @@ export function formatEvidenceBundle(issue) {
     const lines = [];
     const ruleId = getRuleId(issue);
     const severity = coloredSeverity(issue.severity);
-    lines.push(chalk.bold(`ISSUE: ${ruleId} (${severity})`));
+    lines.push(bold(`ISSUE: ${ruleId} (${severity})`));
     lines.push("");
-    lines.push(chalk.cyan.bold("DESCRIPTION"));
+    lines.push(boldColor("DESCRIPTION", brand.cyan));
     lines.push(issue.description || issue.title || "No description available");
     lines.push("");
     if (issue.selector) {
-        lines.push(chalk.cyan.bold("SELECTOR"));
-        lines.push(chalk.gray(issue.selector));
+        lines.push(boldColor("SELECTOR", brand.cyan));
+        lines.push(dim(issue.selector));
         lines.push("");
     }
     if (issue.wcag_reference) {
-        lines.push(chalk.cyan.bold("WCAG REFERENCE"));
+        lines.push(boldColor("WCAG REFERENCE", brand.cyan));
         lines.push(issue.wcag_reference);
         lines.push("");
     }
     const recommendation = issue.recommendation || issue.recommended_fix;
     if (recommendation) {
-        lines.push(chalk.cyan.bold("RECOMMENDATION"));
+        lines.push(boldColor("RECOMMENDATION", brand.cyan));
         lines.push(recommendation);
         lines.push("");
     }
     const hasEvidence = issue.screenshot || issue.html || issue.element || issue.helpUrl;
     if (hasEvidence) {
-        lines.push(chalk.cyan.bold("EVIDENCE"));
+        lines.push(boldColor("EVIDENCE", brand.cyan));
         if (issue.screenshot)
-            lines.push(`- Screenshot: ${chalk.underline(issue.screenshot)}`);
+            lines.push(`- Screenshot: ${issue.screenshot}`);
         if (issue.html || issue.element) {
-            lines.push(`- DOM Snapshot: ${chalk.dim(truncate(issue.html || issue.element || "", 100))}`);
+            lines.push(`- DOM Snapshot: ${dim(truncate(issue.html || issue.element || "", 100))}`);
         }
         if (issue.helpUrl)
-            lines.push(`- Help: ${chalk.underline(issue.helpUrl)}`);
+            lines.push(`- Help: ${issue.helpUrl}`);
     }
     return lines.join("\n");
 }
@@ -147,27 +147,27 @@ export function explainIssue(issue) {
 function formatAiExplainHuman(response, verbose, issues) {
     const lines = [];
     // 3-bullet summary
-    lines.push(chalk.bold("Summary"));
+    lines.push(bold("Summary"));
     for (const bullet of response.summary) {
-        lines.push(`  ${chalk.cyan(">")} ${bullet}`);
+        lines.push(`  ${colorize(">", brand.cyan)} ${bullet}`);
     }
     lines.push("");
     // Issues grouped by severity
-    lines.push(chalk.bold("Issues"));
+    lines.push(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(`  ${severity} ${bold(issue.title)}${issue.id ? dim(` (${issue.id})`) : ""}`);
         lines.push(`  ${issue.explanation}`);
-        lines.push(`  ${chalk.green("Fix:")} ${issue.fix}`);
+        lines.push(`  ${colorize("Fix:", brand.lime)} ${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}`);
+                    lines.push(`  ${dim("Selector:")} ${original.selector}`);
                 if (original.wcag_reference)
-                    lines.push(`  ${chalk.dim("WCAG:")} ${original.wcag_reference}`);
+                    lines.push(`  ${dim("WCAG:")} ${original.wcag_reference}`);
             }
         }
         lines.push("");
@@ -177,13 +177,12 @@ function formatAiExplainHuman(response, verbose, issues) {
 // ---------------------------------------------------------------------------
 // Evidence mode handler (backward compat)
 // ---------------------------------------------------------------------------
-async function handleEvidenceMode(findingId, options, config, format) {
+async function resolveEvidenceIssue(findingId, options, config) {
     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);
+            throw new Error(strings.explain.errors.fileNotFound(filePath));
         }
         const data = JSON.parse(fs.readFileSync(filePath, "utf-8"));
         let issues;
@@ -206,9 +205,8 @@ async function handleEvidenceMode(findingId, options, config, format) {
         }
     }
     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 sdkClient = createClient({ base: options.base, apiKey: config.apiKey });
+        const result = await sdkClient.audits.retrieve(options.job);
         const issues = normalizeIssues(result.issues);
         issue = issues.find((i) => i.id === findingId ||
             getRuleId(i) === findingId ||
@@ -218,14 +216,12 @@ async function handleEvidenceMode(findingId, options, config, format) {
     else {
         const recent = loadRecentAudits();
         if (recent.length === 0) {
-            console.error("Error: No recent audits found. Provide --job or --file option.");
-            process.exit(ExitCode.ERROR);
+            throw new Error(strings.explain.errors.noRecentAudits);
         }
-        const base = resolveApiBase(options.base);
-        const apiKey = getApiKey(config.apiKey);
+        const sdkClient = createClient({ base: options.base, apiKey: config.apiKey });
         for (const audit of recent) {
             try {
-                const result = await apiRequest(base, `/audit/${audit.jobId}`, { method: "GET" }, apiKey);
+                const result = await sdkClient.audits.retrieve(audit.jobId);
                 const issues = normalizeIssues(result.issues);
                 issue = issues.find((i) => i.id === findingId ||
                     getRuleId(i) === findingId ||
@@ -240,123 +236,208 @@ async function handleEvidenceMode(findingId, options, config, format) {
         }
     }
     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));
+        throw new Error(strings.explain.errors.findingNotFound(findingId, options.job || options.file));
     }
+    return 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);
-        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);
+export async function handleExplain(opts) {
+    const config = { apiKey: opts.apiKey };
+    const format = resolveCommandFormat("explain", opts.format, opts.machine || false);
+    const verbose = opts.verbose || false;
+    const renderer = createRenderer("auto");
+    const baseState = {
+        phase: "explain",
+        phaseIndex: 1,
+        phaseTotal: 2,
+        url: "",
+        mode: "explain",
+        progress: {},
+        totals: {},
+        issueCount: 0,
+        scorePreview: null,
+        verbose: false,
+        elapsed: 0,
+    };
+    const startTime = Date.now();
+    if (opts.findingId) {
+        // Evidence mode — fetch and display a specific finding
+        let foundIssue = null;
+        const steps = [
+            {
+                id: "fetch",
+                actionText: "Fetching audit finding...",
+                summaryText: "Finding loaded",
+                run: async () => {
+                    foundIssue = await resolveEvidenceIssue(opts.findingId, { job: opts.job, file: opts.file, base: opts.base }, config);
+                },
+            },
+            {
+                id: "explain",
+                actionText: "Generating explanation...",
+                summaryText: "Explanation generated",
+                run: async () => {
+                    // Explanation is the formatted evidence bundle; output after steps
+                },
+            },
+        ];
+        const { success, states } = await runSteps(steps, {
+            onStateChange: (stepStates) => {
+                renderer.update({ ...baseState, stepStates, elapsed: Date.now() - startTime });
+            },
+        });
+        renderer.finish({
+            url: "",
+            mode: "explain",
+            overallScore: success ? 100 : 0,
+            scores: {},
+            issueCount: 0,
+            passed: success,
+            elapsed: Date.now() - startTime,
+        });
+        if (!success) {
+            const failed = states.find(s => s.status === "failed");
+            process.stderr.write(renderError({
+                message: failed?.failReason || "Command failed",
+                suggestion: "vertaa audit <url>",
+            }) + "\n");
+            process.exitCode = ExitCode.ERROR;
+        }
+        if (success && foundIssue) {
+            const issue = foundIssue;
+            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 {
+                writeDataOutput(formatEvidenceBundle(issue));
+            }
         }
-        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);
-    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 {
+        // AI mode — explain all issues in an audit
+        let responseData = null;
+        let rawIssues = [];
+        const steps = [
+            {
+                id: "fetch",
+                actionText: strings.explain.run.action,
+                summaryText: "Finding loaded",
+                run: async () => {
+                    let auditData = null;
+                    if (opts.job) {
+                        const sdkClient = createClient({ base: opts.base, apiKey: config.apiKey });
+                        const result = await sdkClient.audits.retrieve(opts.job);
+                        rawIssues = normalizeIssues(result.issues);
+                        auditData = {
+                            job_id: result.job_id || opts.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 {
+                        const input = await readJsonInput(opts.file);
+                        if (!input) {
+                            throw new Error(strings.explain.errors.noAuditData);
+                        }
+                        const data = input;
+                        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) {
+                        throw new Error(strings.explain.errors.noIssuesFound);
+                    }
+                    const base = resolveApiBase(opts.base);
+                    const apiKey = getApiKey(config.apiKey);
+                    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)),
+                    ]);
+                    responseData = response.data;
+                },
+            },
+            {
+                id: "explain",
+                actionText: "Generating explanation...",
+                summaryText: responseData ? strings.explain.run.done(responseData.issues.length) : "Explanation generated",
+                run: async () => {
+                    // Explanation data gathered in fetch step; output after steps
+                },
+            },
+        ];
+        const { success, states } = await runSteps(steps, {
+            onStateChange: (stepStates) => {
+                renderer.update({ ...baseState, stepStates, elapsed: Date.now() - startTime });
+            },
+        });
+        renderer.finish({
+            url: "",
+            mode: "explain",
+            overallScore: success ? 100 : 0,
+            scores: {},
+            issueCount: 0,
+            passed: success,
+            elapsed: Date.now() - startTime,
+        });
+        if (!success) {
+            const failed = states.find(s => s.status === "failed");
+            process.stderr.write(renderError({
+                message: failed?.failReason || "Command failed",
+                suggestion: "vertaa audit <url>",
+            }) + "\n");
+            process.exitCode = ExitCode.ERROR;
         }
-        else {
-            writeOutput(formatAiExplainHuman(response.data, verbose, rawIssues));
+        if (success && responseData) {
+            if (format === "json") {
+                writeJsonOutput(responseData, "explain");
+            }
+            else {
+                writeDataOutput(formatAiExplainHuman(responseData, verbose, rawIssues));
+            }
         }
     }
-    catch (error) {
-        handleAiCommandError(error, "explain", spinner);
-    }
 }
+// ---------------------------------------------------------------------------
+// Command Registration
+// ---------------------------------------------------------------------------
 export function registerExplainCommand(program) {
     program
         .command("explain [finding-id]")
@@ -382,18 +463,23 @@ Modes:
             const config = await resolveConfig(globalOpts.config);
             const machineMode = globalOpts.machine || false;
             const verbose = globalOpts.verbose || false;
-            const format = resolveCommandFormat("explain", options.format, machineMode);
-            if (findingId) {
-                // Backward-compatible evidence mode
-                await handleEvidenceMode(findingId, options, config, format);
-            }
-            else {
-                // AI-powered explain mode
-                await handleAiMode(options, config, format, verbose);
-            }
+            await handleExplain({
+                findingId,
+                job: options.job,
+                file: options.file,
+                format: options.format,
+                base: globalOpts.base,
+                verbose,
+                machine: machineMode,
+                apiKey: config.apiKey,
+            });
         }
         catch (error) {
-            console.error("Error:", error instanceof Error ? error.message : String(error));
+            process.stderr.write(renderError({
+                message: error instanceof Error ? error.message : String(error),
+                suggestion: "vertaa audit <url>",
+                exitCode: ExitCode.ERROR,
+            }) + "\n");
             process.exit(ExitCode.ERROR);
         }
     });

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

@@ -0,0 +1,25 @@
+/**
+ * Legacy fix-all command handler.
+ * Generates fix patches for all issues in an audit.
+ */
+import type { Command } from "commander";
+import type { Flags } from "../types.js";
+export interface FixAllCommandOptions {
+    base?: string;
+    jobId: string;
+    fileContent: string;
+    autoFixOnly?: boolean;
+    format?: string;
+    dryRun?: boolean;
+    yes?: boolean;
+}
+export declare function handleFixAll(opts: FixAllCommandOptions): Promise<void>;
+/**
+ * Shared fix-all runner used by the fix-all command (legacy wrapper for backward compat).
+ */
+export declare function runFixAllCommand(base: string, jobId: string, flags: Flags, globalFlags?: {
+    dryRun?: boolean;
+    yes?: boolean;
+}): Promise<void>;
+export declare function registerFixAllCommand(program: Command): void;
+//# sourceMappingURL=fix-all.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"fix-all.d.ts","sourceRoot":"","sources":["../../src/commands/fix-all.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAezC,OAAO,KAAK,EAAE,KAAK,EAAkD,MAAM,aAAa,CAAC;AAUzF,MAAM,WAAW,oBAAoB;IACnC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAED,wBAAsB,YAAY,CAAC,IAAI,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,CA4K5E;AAED;;GAEG;AACH,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,KAAK,EACZ,WAAW,GAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAC;IAAC,GAAG,CAAC,EAAE,OAAO,CAAA;CAAO,iBAmBtD;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAsB5D"}