@vertaaux/cli 0.2.0

package/dist/commands/download.js

@@ -0,0 +1,183 @@
+/**
+ * Download command for VertaaUX CLI.
+ *
+ * Syncs audit results from VertaaUX cloud to local.
+ * Enables pulling results from CI runs or shared audits.
+ */
+import fs from "fs";
+import path from "path";
+import chalk from "chalk";
+import ora from "ora";
+import { loadToken } from "../auth/token-store.js";
+import { getCIToken } from "../auth/ci-token.js";
+import { resolveApiBase } from "../utils/client.js";
+import { resolveConfig } from "../config/loader.js";
+import { saveBaseline } from "../baseline/manager.js";
+import { isInteractive, confirmAction } from "../interactive/prompts.js";
+import { ExitCode } from "../utils/exit-codes.js";
+import { assertPathContainment } from "../utils/sanitize.js";
+/**
+ * Default output directory.
+ */
+const DEFAULT_OUTPUT_DIR = ".vertaaux";
+/**
+ * Get authentication token from stored credentials or environment.
+ */
+async function getAuthToken() {
+    // Check stored token first
+    const storedToken = await loadToken();
+    if (storedToken?.accessToken) {
+        return storedToken.accessToken;
+    }
+    // Check environment
+    return getCIToken();
+}
+/**
+ * Handle the download command.
+ */
+async function handleDownload(jobId, options) {
+    // Get auth token
+    const token = await getAuthToken();
+    if (!token) {
+        console.error(chalk.red("Error: Not authenticated."));
+        console.error("Run `vertaa login` to authenticate or set VERTAAUX_TOKEN environment variable.");
+        process.exit(ExitCode.ERROR);
+    }
+    // Load config for API base (supports --config global option)
+    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();
+    try {
+        // Build request URL
+        let url = `${apiBase}/sync/download/${jobId}`;
+        if (options.baseline) {
+            url += "?include_baseline=true";
+        }
+        // Make API request
+        const response = await fetch(url, {
+            method: "GET",
+            headers: {
+                "Content-Type": "application/json",
+                "X-API-Key": token,
+            },
+        });
+        if (!response.ok) {
+            const error = await response.json().catch(() => ({ error: { message: response.statusText } }));
+            throw new Error(error.error?.message || `HTTP ${response.status}`);
+        }
+        const result = (await response.json());
+        if (!result.success) {
+            throw new Error(result.error?.message || "Download failed");
+        }
+        // Create output directory
+        const resolvedOutputDir = path.resolve(process.cwd(), outputDir);
+        if (!fs.existsSync(resolvedOutputDir)) {
+            fs.mkdirSync(resolvedOutputDir, { recursive: true });
+        }
+        // Save audit results
+        if (result.audit) {
+            const auditPath = path.join(resolvedOutputDir, `audit-${jobId}.json`);
+            // Check for existing file
+            if (fs.existsSync(auditPath) && !options.force) {
+                if (isInteractive()) {
+                    const overwrite = await confirmAction(`File ${auditPath} already exists. Overwrite?`, false);
+                    if (!overwrite) {
+                        spinner.info("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)`);
+                }
+            }
+            else {
+                fs.writeFileSync(auditPath, JSON.stringify(result.audit, null, 2), "utf-8");
+            }
+        }
+        // Save baseline if included
+        if (options.baseline && result.baseline) {
+            const baselinePath = path.join(resolvedOutputDir, "baseline.json");
+            // Check for existing baseline
+            if (fs.existsSync(baselinePath) && !options.force) {
+                if (isInteractive()) {
+                    const overwrite = await confirmAction(`Baseline file already exists. Overwrite?`, false);
+                    if (!overwrite) {
+                        spinner.info("Skipping baseline (file exists).");
+                    }
+                    else {
+                        await saveBaseline(result.baseline, baselinePath);
+                    }
+                }
+                else {
+                    spinner.warn(`Skipping baseline (already exists, use --force to overwrite)`);
+                }
+            }
+            else {
+                await saveBaseline(result.baseline, baselinePath);
+            }
+        }
+        // Save artifacts if included
+        if (result.artifacts) {
+            const artifactsDir = path.join(resolvedOutputDir, "artifacts", jobId);
+            if (!fs.existsSync(artifactsDir)) {
+                fs.mkdirSync(artifactsDir, { recursive: true });
+            }
+            for (const [filename, content] of Object.entries(result.artifacts)) {
+                let filePath;
+                try {
+                    filePath = assertPathContainment(filename, artifactsDir);
+                }
+                catch {
+                    console.error(`Security: Rejected artifact "${filename}" -- path traversal outside output directory.`);
+                    continue;
+                }
+                const ext = path.extname(filename).toLowerCase();
+                const isBinary = [".png", ".jpg", ".jpeg", ".gif", ".zip"].includes(ext);
+                if (isBinary) {
+                    fs.writeFileSync(filePath, Buffer.from(content, "base64"));
+                }
+                else {
+                    fs.writeFileSync(filePath, content, "utf-8");
+                }
+            }
+        }
+        spinner.succeed("Download complete!");
+        console.error("");
+        console.error(`  Job ID:  ${result.job_id}`);
+        console.error(`  Output:  ${resolvedOutputDir}`);
+        if (result.audit) {
+            console.error(`  Status:  ${result.audit.status}`);
+            if (result.audit.url) {
+                console.error(`  URL:     ${result.audit.url}`);
+            }
+        }
+        if (options.baseline && result.baseline) {
+            console.error(`  Baseline: ${result.baseline.issues.length} issues`);
+        }
+        console.error("");
+    }
+    catch (error) {
+        spinner.fail("Download failed");
+        console.error(chalk.red("Error:"), error instanceof Error ? error.message : String(error));
+        process.exit(ExitCode.ERROR);
+    }
+}
+/**
+ * Register the download command with the Commander program.
+ */
+export function registerDownloadCommand(program) {
+    program
+        .command("download <job-id>")
+        .description("Download audit results from VertaaUX cloud")
+        .option("--baseline", "Also download baseline file")
+        .option("-o, --output <path>", "Output directory (default: .vertaaux)")
+        .option("-b, --base <url>", "API base URL")
+        .option("-f, --force", "Overwrite existing files without prompting")
+        .action(async (jobId, options, command) => {
+        const globalOpts = command.optsWithGlobals();
+        await handleDownload(jobId, { ...options, configPath: globalOpts.config });
+    });
+}

package/dist/commands/explain.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Explain command for VertaaUX CLI.
+ *
+ * Shows full evidence bundle for a specific finding:
+ * - Description
+ * - Selector
+ * - WCAG reference
+ * - Recommendation
+ * - Related artifacts (screenshots, DOM)
+ *
+ * Supports loading issues from:
+ * - Active job via --job flag
+ * - Local JSON file via --file flag
+ * - Recent audits from .vertaaux/recent.json
+ */
+import { Command } from "commander";
+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
+ */
+export declare function explainIssue(issue: EvidenceIssue): string;
+/**
+ * Command options for explain.
+ */
+export interface ExplainCommandOptions {
+    job?: string;
+    file?: string;
+    format?: "json" | "human";
+    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

@@ -0,0 +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"}

package/dist/commands/explain.js

@@ -0,0 +1,302 @@
+/**
+ * Explain command for VertaaUX CLI.
+ *
+ * Shows full evidence bundle for a specific finding:
+ * - Description
+ * - Selector
+ * - WCAG reference
+ * - Recommendation
+ * - Related artifacts (screenshots, DOM)
+ *
+ * Supports loading issues from:
+ * - Active job via --job flag
+ * - Local JSON file via --file flag
+ * - Recent audits from .vertaaux/recent.json
+ */
+import fs from "fs";
+import path from "path";
+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";
+/**
+ * Path to recent audits cache.
+ */
+const RECENT_AUDITS_PATH = ".vertaaux/recent.json";
+/**
+ * Load recent audits from cache file.
+ */
+function loadRecentAudits() {
+    const filePath = path.resolve(process.cwd(), RECENT_AUDITS_PATH);
+    if (!fs.existsSync(filePath)) {
+        return [];
+    }
+    try {
+        const content = fs.readFileSync(filePath, "utf-8");
+        return JSON.parse(content);
+    }
+    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 [];
+}
+/**
+ * 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) {
+        case "critical":
+        case "error":
+            return chalk.red.bold(sev.toUpperCase());
+        case "serious":
+        case "warning":
+            return chalk.yellow.bold(sev.toUpperCase());
+        case "moderate":
+        case "minor":
+            return chalk.cyan(sev.toUpperCase());
+        default:
+            return chalk.dim(sev.toUpperCase());
+    }
+}
+/**
+ * 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) {
+            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))}`);
+        }
+        if (issue.helpUrl) {
+            lines.push(`- Help: ${chalk.underline(issue.helpUrl)}`);
+        }
+    }
+    return lines.join("\n");
+}
+/**
+ * Format evidence as JSON.
+ */
+export function formatEvidenceJson(issue) {
+    const output = {
+        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,
+        },
+    };
+    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) + "...";
+}
+/**
+ * Export for reuse in fix-wizard.
+ *
+ * @param issue - Issue to explain
+ * @returns Formatted evidence string
+ */
+export function explainIssue(issue) {
+    return formatEvidenceBundle(issue);
+}
+/**
+ * Register the explain command with the Commander program.
+ */
+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")
+        .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 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");
+            }
+            else {
+                writeOutput(formatEvidenceBundle(issue));
+            }
+        }
+        catch (error) {
+            console.error("Error:", error instanceof Error ? error.message : String(error));
+            process.exit(ExitCode.ERROR);
+        }
+    });
+}

package/dist/commands/init.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Init command for VertaaUX CLI.
+ *
+ * Creates project configuration with guided wizard or defaults.
+ * Generates CI templates for popular platforms.
+ */
+import type { Command } from "commander";
+/**
+ * Register the init command with the Commander program.
+ */
+export declare function registerInitCommand(program: Command): void;
+//# sourceMappingURL=init.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/commands/init.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA6NzC;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAgC1D"}