@vertaaux/cli 0.2.0

package/dist/commands/diff.js

@@ -0,0 +1,196 @@
+/**
+ * Diff command for VertaaUX CLI.
+ *
+ * Compares current audit results against baseline or previous audit.
+ * Shows three categories: new, fixed, still present.
+ *
+ * Exit codes:
+ * - 0: No new issues
+ * - 1: New issues found
+ * - 2: Error
+ */
+import { readFile } from "fs/promises";
+import { existsSync } from "fs";
+import { ExitCode } from "../utils/exit-codes.js";
+import { loadBaseline, DEFAULT_BASELINE_PATH } from "../baseline/manager.js";
+import { computeDiff, formatDiffHuman, formatDiffJson } from "../baseline/diff.js";
+import { writeJsonOutput, writeOutput } from "../output/envelope.js";
+import { resolveCommandFormat } from "../output/formats.js";
+const DEFAULT_API_BASE = "https://vertaaux.ai/v1";
+/**
+ * Get API base URL from environment.
+ */
+function getApiBase() {
+    return (process.env.VERTAAUX_API_BASE || DEFAULT_API_BASE).replace(/\/$/, "");
+}
+/**
+ * Get API key from environment.
+ */
+function getApiKey() {
+    const key = process.env.VERTAAUX_API_KEY;
+    if (!key) {
+        throw new Error("VERTAAUX_API_KEY is required");
+    }
+    return key;
+}
+/**
+ * Fetch audit results from API.
+ */
+async function fetchAudit(jobId) {
+    const base = getApiBase();
+    const url = `${base}/audit/${jobId}`;
+    const res = await fetch(url, {
+        method: "GET",
+        headers: {
+            "Content-Type": "application/json",
+            "X-API-Key": getApiKey(),
+        },
+    });
+    if (!res.ok) {
+        let detail = res.statusText;
+        try {
+            const data = (await res.json());
+            detail = data.error || data.message || detail;
+        }
+        catch {
+            // ignore
+        }
+        throw new Error(`HTTP ${res.status}: ${detail}`);
+    }
+    return (await res.json());
+}
+/**
+ * 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 [];
+}
+/**
+ * Register the diff command with the Commander program.
+ */
+export function registerDiffCommand(program) {
+    program
+        .command("diff [job-id]")
+        .description("Compare audit results against baseline")
+        .option("--baseline <path>", "Baseline file path", DEFAULT_BASELINE_PATH)
+        .option("--compare <job-id>", "Compare two audit jobs instead of baseline")
+        .option("--format <format>", "Output format: json | human (default: auto)")
+        .option("--verbose", "Show all present issues")
+        .option("--from-file <file>", "Read current audit from JSON file")
+        .action(async (jobIdArg, cmdOptions, cmd) => {
+        try {
+            const baselinePath = cmdOptions.baseline || DEFAULT_BASELINE_PATH;
+            const machineMode = cmd.optsWithGlobals?.().machine || false;
+            const format = resolveCommandFormat("diff", cmdOptions.format, machineMode);
+            const verbose = cmdOptions.verbose || false;
+            // Get current audit issues
+            let currentIssues;
+            let currentUrl;
+            if (cmdOptions.fromFile) {
+                // Load from file
+                const filePath = cmdOptions.fromFile;
+                if (!existsSync(filePath)) {
+                    console.error(`File not found: ${filePath}`);
+                    process.exit(ExitCode.ERROR);
+                }
+                const content = await readFile(filePath, "utf-8");
+                const data = JSON.parse(content);
+                currentIssues = normalizeIssues(data.issues);
+                currentUrl = data.url || "unknown";
+            }
+            else if (jobIdArg) {
+                // Fetch from API
+                const audit = await fetchAudit(jobIdArg);
+                if (audit.status !== "completed") {
+                    console.error(`Audit ${jobIdArg} is not completed (status: ${audit.status})`);
+                    process.exit(ExitCode.ERROR);
+                }
+                currentIssues = normalizeIssues(audit.issues);
+                currentUrl = audit.url || "unknown";
+            }
+            else {
+                console.error("Provide job ID or use --from-file");
+                console.error("Usage: vertaa diff <job-id>");
+                console.error("       vertaa diff --from-file <audit.json>");
+                process.exit(ExitCode.ERROR);
+            }
+            // Handle --compare: compare two audits
+            if (cmdOptions.compare) {
+                const compareAudit = await fetchAudit(cmdOptions.compare);
+                if (compareAudit.status !== "completed") {
+                    console.error(`Audit ${cmdOptions.compare} is not completed (status: ${compareAudit.status})`);
+                    process.exit(ExitCode.ERROR);
+                }
+                // Create temporary baseline from compare job
+                const compareIssues = normalizeIssues(compareAudit.issues);
+                const tempBaseline = {
+                    version: 1,
+                    created: new Date().toISOString(),
+                    updated: new Date().toISOString(),
+                    url: compareAudit.url || "unknown",
+                    issues: compareIssues.map((issue) => ({
+                        fingerprint: "",
+                        ruleId: issue.ruleId || issue.rule_id || issue.id || "unknown",
+                        severity: issue.severity || "warning",
+                        category: issue.category || "general",
+                        description: issue.description || "",
+                        selector: issue.selector,
+                        baselinedAt: new Date().toISOString(),
+                    })),
+                };
+                // Re-generate fingerprints using the proper function
+                const { generateFingerprint } = await import("../baseline/hash.js");
+                for (let i = 0; i < tempBaseline.issues.length; i++) {
+                    tempBaseline.issues[i].fingerprint = generateFingerprint(compareIssues[i]);
+                }
+                const diff = computeDiff(currentIssues, tempBaseline);
+                // Output
+                if (format === "json") {
+                    const diffData = JSON.parse(formatDiffJson(diff));
+                    writeJsonOutput(diffData, "diff");
+                }
+                else {
+                    console.error(`Comparing ${currentUrl} (current) vs ${tempBaseline.url} (previous)\n`);
+                    writeOutput(formatDiffHuman(diff, verbose));
+                }
+                // Exit code: 1 if new issues
+                if (diff.summary.newCount > 0) {
+                    process.exit(1);
+                }
+                return;
+            }
+            // Load baseline
+            const baseline = await loadBaseline(baselinePath);
+            if (!baseline) {
+                console.error(`No baseline found at: ${baselinePath}`);
+                console.error("Create one with: vertaa baseline <job-id>");
+                process.exit(ExitCode.ERROR);
+            }
+            // Compute diff
+            const diff = computeDiff(currentIssues, baseline);
+            // Output
+            if (format === "json") {
+                const diffData = JSON.parse(formatDiffJson(diff));
+                writeJsonOutput(diffData, "diff");
+            }
+            else {
+                console.error(`Comparing ${currentUrl} against baseline\n`);
+                writeOutput(formatDiffHuman(diff, verbose));
+            }
+            // Exit code: 1 if new issues
+            if (diff.summary.newCount > 0) {
+                process.exit(1);
+            }
+        }
+        catch (error) {
+            console.error("Error:", error instanceof Error ? error.message : String(error));
+            process.exit(ExitCode.ERROR);
+        }
+    });
+}

package/dist/commands/doctor.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Doctor command for VertaaUX CLI.
+ *
+ * Runs health checks on config, auth, network, and output contracts.
+ * Reports pass/fail with actionable remediation instructions.
+ * Never crashes -- all checks are wrapped in try/catch.
+ */
+import type { Command } from "commander";
+export interface DoctorCheck {
+    name: string;
+    status: "pass" | "fail" | "warn" | "skip";
+    message: string;
+    remediation?: string;
+    detail?: string;
+}
+export interface DoctorResult {
+    checks: DoctorCheck[];
+    summary: {
+        pass: number;
+        fail: number;
+        warn: number;
+        skip: number;
+    };
+}
+/**
+ * Check 1: Configuration validity.
+ * Uses resolveConfig() from config/loader.ts.
+ */
+export declare function checkConfig(): Promise<DoctorCheck>;
+/**
+ * Check 2: Authentication status.
+ * Checks CI token env vars first, then stored credentials.
+ * --online flag verifies credentials against the API.
+ */
+export declare function checkAuth(online: boolean): Promise<DoctorCheck>;
+/**
+ * Check 3: Network connectivity.
+ * Uses fetch with 5s timeout to the /auth/validate endpoint.
+ * Any response (even 401) counts as reachable.
+ */
+export declare function checkNetwork(): Promise<DoctorCheck>;
+/**
+ * Check 4: Output contract health (only with --deep).
+ * Verifies COMMAND_FORMATS registry has entries for expected commands
+ * and that the config schema file is loadable.
+ */
+export declare function checkOutputContracts(deep: boolean): DoctorCheck;
+export declare function formatDoctorHuman(result: DoctorResult): string;
+export declare function handleDoctor(options: {
+    online?: boolean;
+    deep?: boolean;
+    format?: string;
+}): Promise<void>;
+/**
+ * Register the doctor command with the Commander program.
+ */
+export declare function registerDoctorCommand(program: Command): void;
+//# sourceMappingURL=doctor.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/commands/doctor.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAmBzC,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;CACrE;AAMD;;;GAGG;AACH,wBAAsB,WAAW,IAAI,OAAO,CAAC,WAAW,CAAC,CAkCxD;AAED;;;;GAIG;AACH,wBAAsB,SAAS,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,WAAW,CAAC,CA4FrE;AAED;;;;GAIG;AACH,wBAAsB,YAAY,IAAI,OAAO,CAAC,WAAW,CAAC,CAsBzD;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,OAAO,GAAG,WAAW,CAuD/D;AAMD,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CAqC9D;AAMD,wBAAsB,YAAY,CAAC,OAAO,EAAE;IAC1C,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,GAAG,OAAO,CAAC,IAAI,CAAC,CAgChB;AAMD;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAwB5D"}

package/dist/commands/doctor.js

@@ -0,0 +1,338 @@
+/**
+ * Doctor command for VertaaUX CLI.
+ *
+ * Runs health checks on config, auth, network, and output contracts.
+ * Reports pass/fail with actionable remediation instructions.
+ * Never crashes -- all checks are wrapped in try/catch.
+ */
+import chalk from "chalk";
+import { createRequire } from "module";
+import { resolveConfig } from "../config/loader.js";
+import { ConfigValidationError, ConfigLoadError } from "../config/loader.js";
+import { loadToken, isTokenExpired, getCredentialsPath } from "../auth/token-store.js";
+import { getCIToken, validateCIToken } from "../auth/ci-token.js";
+import { resolveApiBase } from "../utils/client.js";
+import { ExitCode } from "../utils/exit-codes.js";
+import { writeJsonOutput, writeOutput } from "../output/envelope.js";
+import { COMMAND_FORMATS } from "../output/formats.js";
+import { getVersion } from "../ui/banner.js";
+const require = createRequire(import.meta.url);
+// ---------------------------------------------------------------------------
+// Individual health checks
+// ---------------------------------------------------------------------------
+/**
+ * Check 1: Configuration validity.
+ * Uses resolveConfig() from config/loader.ts.
+ */
+export async function checkConfig() {
+    try {
+        await resolveConfig();
+        return {
+            name: "Configuration",
+            status: "pass",
+            message: "Config loaded and validated successfully",
+        };
+    }
+    catch (error) {
+        if (error instanceof ConfigValidationError) {
+            return {
+                name: "Configuration",
+                status: "fail",
+                message: `Config validation failed: ${error.message}`,
+                remediation: "Run: vertaa init -y --force",
+                detail: "Config file exists but contains invalid values",
+            };
+        }
+        if (error instanceof ConfigLoadError) {
+            return {
+                name: "Configuration",
+                status: "warn",
+                message: "No config file found (using defaults)",
+                remediation: "Run: vertaa init",
+                detail: "CLI will use built-in defaults without a config file",
+            };
+        }
+        return {
+            name: "Configuration",
+            status: "fail",
+            message: `Unexpected error: ${error instanceof Error ? error.message : String(error)}`,
+            remediation: "Run: vertaa init -y --force",
+        };
+    }
+}
+/**
+ * Check 2: Authentication status.
+ * Checks CI token env vars first, then stored credentials.
+ * --online flag verifies credentials against the API.
+ */
+export async function checkAuth(online) {
+    try {
+        // Check for CI token first (env var)
+        const ciToken = getCIToken();
+        if (ciToken) {
+            if (online) {
+                const apiBase = resolveApiBase();
+                try {
+                    const valid = await validateCIToken(ciToken, apiBase);
+                    return {
+                        name: "Authentication",
+                        status: valid ? "pass" : "fail",
+                        message: valid
+                            ? "CI token valid (verified online)"
+                            : "CI token rejected by API",
+                        remediation: valid ? undefined : "Check your VERTAAUX_API_KEY or VERTAAUX_TOKEN value",
+                    };
+                }
+                catch {
+                    return {
+                        name: "Authentication",
+                        status: "warn",
+                        message: "CI token found but online verification failed",
+                        remediation: "Check network connectivity for online token validation",
+                        detail: "CI token present in environment but could not verify against API",
+                    };
+                }
+            }
+            return {
+                name: "Authentication",
+                status: "pass",
+                message: "CI token found in environment",
+            };
+        }
+        // Check stored credentials
+        const token = await loadToken();
+        if (!token) {
+            return {
+                name: "Authentication",
+                status: "fail",
+                message: "No credentials found",
+                remediation: "Run: vertaa login",
+                detail: `Checked: ${getCredentialsPath()} and env vars VERTAAUX_TOKEN, VERTAAUX_API_KEY`,
+            };
+        }
+        if (isTokenExpired(token)) {
+            return {
+                name: "Authentication",
+                status: "fail",
+                message: "Token expired",
+                remediation: "Run: vertaa login",
+                detail: `Token expired at ${token.expiresAt}`,
+            };
+        }
+        // Optionally verify online
+        if (online) {
+            const apiBase = resolveApiBase();
+            try {
+                const valid = await validateCIToken(token.accessToken, apiBase);
+                if (!valid) {
+                    return {
+                        name: "Authentication",
+                        status: "fail",
+                        message: "Token rejected by API (may be revoked)",
+                        remediation: "Run: vertaa login",
+                    };
+                }
+            }
+            catch {
+                return {
+                    name: "Authentication",
+                    status: "warn",
+                    message: "Token found but online verification failed",
+                    remediation: "Check network connectivity for online token validation",
+                };
+            }
+        }
+        return {
+            name: "Authentication",
+            status: "pass",
+            message: `Authenticated (${token.type} token, saved ${token.savedAt})`,
+        };
+    }
+    catch (error) {
+        return {
+            name: "Authentication",
+            status: "fail",
+            message: `Auth check error: ${error instanceof Error ? error.message : String(error)}`,
+            remediation: "Run: vertaa login",
+        };
+    }
+}
+/**
+ * Check 3: Network connectivity.
+ * Uses fetch with 5s timeout to the /auth/validate endpoint.
+ * Any response (even 401) counts as reachable.
+ */
+export async function checkNetwork() {
+    const apiBase = resolveApiBase();
+    try {
+        const res = await fetch(`${apiBase}/auth/validate`, {
+            method: "GET",
+            signal: AbortSignal.timeout(5000),
+        });
+        // Any response means API is reachable (even 401/403)
+        return {
+            name: "Network",
+            status: "pass",
+            message: `API reachable at ${apiBase} (HTTP ${res.status})`,
+        };
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        return {
+            name: "Network",
+            status: "fail",
+            message: `Cannot reach API: ${msg}`,
+            remediation: `Check network connectivity. API base: ${apiBase}. Set VERTAAUX_API_BASE to override.`,
+        };
+    }
+}
+/**
+ * Check 4: Output contract health (only with --deep).
+ * Verifies COMMAND_FORMATS registry has entries for expected commands
+ * and that the config schema file is loadable.
+ */
+export function checkOutputContracts(deep) {
+    if (!deep) {
+        return {
+            name: "Output Contracts",
+            status: "skip",
+            message: "Run with --deep to check output contracts",
+        };
+    }
+    try {
+        const expectedCommands = ["audit", "comment", "explain", "policy-show", "diff"];
+        const registeredCommands = Object.keys(COMMAND_FORMATS);
+        const missing = expectedCommands.filter((cmd) => !registeredCommands.includes(cmd));
+        if (missing.length > 0) {
+            return {
+                name: "Output Contracts",
+                status: "warn",
+                message: `Format registry missing entries for: ${missing.join(", ")}`,
+                detail: `Registered commands: ${registeredCommands.join(", ")}`,
+            };
+        }
+        // Check schema file accessibility via createRequire
+        let schemaOk = false;
+        try {
+            require("../../schemas/vertaaux.config.schema.json");
+            schemaOk = true;
+        }
+        catch {
+            // Schema not found
+        }
+        if (!schemaOk) {
+            return {
+                name: "Output Contracts",
+                status: "warn",
+                message: `Output contracts registered for ${registeredCommands.length} commands, but config schema file not accessible`,
+                detail: "Schema file: schemas/vertaaux.config.schema.json",
+                remediation: "Reinstall CLI: npm install -g @vertaaux/cli",
+            };
+        }
+        return {
+            name: "Output Contracts",
+            status: "pass",
+            message: `Output contracts registered for ${registeredCommands.length} commands, schema valid`,
+            detail: `Commands: ${registeredCommands.join(", ")}`,
+        };
+    }
+    catch (error) {
+        return {
+            name: "Output Contracts",
+            status: "fail",
+            message: `Contract check error: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+}
+// ---------------------------------------------------------------------------
+// Output formatting
+// ---------------------------------------------------------------------------
+export function formatDoctorHuman(result) {
+    const statusIcons = {
+        pass: chalk.green("PASS"),
+        fail: chalk.red("FAIL"),
+        warn: chalk.yellow("WARN"),
+        skip: chalk.dim("SKIP"),
+    };
+    const lines = [];
+    const version = getVersion();
+    lines.push(chalk.bold(`VertaaUX Doctor`) + chalk.dim(` v${version}`));
+    lines.push("");
+    for (const check of result.checks) {
+        lines.push(`  ${statusIcons[check.status]}  ${check.name}: ${check.message}`);
+        if (check.remediation) {
+            lines.push(`        ${chalk.cyan("Fix:")} ${check.remediation}`);
+        }
+        if (check.detail) {
+            lines.push(`        ${chalk.dim(check.detail)}`);
+        }
+    }
+    lines.push("");
+    const { pass, fail, warn } = result.summary;
+    if (fail > 0) {
+        lines.push(chalk.red(`${fail} check(s) failed.`) +
+            " Run the suggested fix commands above.");
+    }
+    else if (warn > 0) {
+        lines.push(chalk.yellow(`All checks passed (${warn} warning(s)).`));
+    }
+    else {
+        lines.push(chalk.green(`All ${pass} checks passed.`));
+    }
+    return lines.join("\n");
+}
+// ---------------------------------------------------------------------------
+// Command handler
+// ---------------------------------------------------------------------------
+export async function handleDoctor(options) {
+    const format = options.format || "human";
+    const online = options.online || false;
+    const deep = options.deep || false;
+    const checks = [];
+    // Run checks in dependency order
+    checks.push(await checkConfig());
+    checks.push(await checkAuth(online));
+    checks.push(await checkNetwork());
+    checks.push(checkOutputContracts(deep));
+    // Build summary
+    const summary = { pass: 0, fail: 0, warn: 0, skip: 0 };
+    for (const check of checks) {
+        summary[check.status]++;
+    }
+    const result = { checks, summary };
+    // Output
+    if (format === "json") {
+        writeJsonOutput(result, "doctor");
+    }
+    else {
+        writeOutput(formatDoctorHuman(result));
+    }
+    // Exit code: 0 on all-pass/warn, 1 on any fail
+    if (summary.fail > 0) {
+        process.exitCode = ExitCode.ISSUES_FOUND;
+    }
+}
+// ---------------------------------------------------------------------------
+// Command registration
+// ---------------------------------------------------------------------------
+/**
+ * Register the doctor command with the Commander program.
+ */
+export function registerDoctorCommand(program) {
+    program
+        .command("doctor")
+        .description("Check CLI health: config, auth, network, output contracts")
+        .option("--online", "Verify auth credentials against API (default: offline check)")
+        .option("--deep", "Run output contract self-tests")
+        .option("--format <format>", "Output format: human, json", "human")
+        .action(async (options) => {
+        try {
+            await handleDoctor(options);
+        }
+        catch (error) {
+            // Doctor must NEVER crash -- fallback error reporting
+            process.stderr.write(`Error: ${error instanceof Error ? error.message : String(error)}\n`);
+            process.exit(ExitCode.ERROR);
+        }
+    });
+}

package/dist/commands/download.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Download command for VertaaUX CLI.
+ *
+ * Syncs audit results from VertaaUX cloud to local.
+ * Enables pulling results from CI runs or shared audits.
+ */
+import { Command } from "commander";
+/**
+ * Register the download command with the Commander program.
+ */
+export declare function registerDownloadCommand(program: Command): void;
+//# sourceMappingURL=download.d.ts.map

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

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