@vertaaux/cli 0.2.2 → 0.3.0

package/dist/commands/protect.js

@@ -0,0 +1,323 @@
+/**
+ * Protect command for VertaaUX CLI.
+ *
+ * Implements the 3-step conversion flow from the command line:
+ *   1. Audit  - Captures scores (from latest audit or --input)
+ *   2. Protect - Generates policy YAML with score thresholds
+ *   3. Monitor - Outputs CI snippet for continuous quality gating
+ *
+ * Usage: vertaa protect [url] [options]
+ */
+import chalk from "chalk";
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { resolve, dirname } from "node:path";
+import { stringify } from "yaml";
+import { generatePolicyFromScores } from "@vertaaux/quality-control";
+import { generateTemplate } from "../templates/index.js";
+import { ExitCode } from "../utils/exit-codes.js";
+import { normalizeIssues, generateFingerprint } from "@vertaaux/quality-control";
+/**
+ * Path to the latest audit results cache.
+ */
+const LATEST_AUDIT_PATH = ".vertaaux/latest-audit.json";
+/**
+ * Default baseline file path.
+ */
+const DEFAULT_BASELINE_PATH = ".vertaaux/baseline.json";
+/**
+ * Maximum age (in ms) for a cached audit to be considered "recent" (1 hour).
+ */
+const MAX_AUDIT_AGE_MS = 60 * 60 * 1000;
+/**
+ * Extract numeric scores from audit scores object.
+ */
+function extractNumericScores(scores) {
+    if (!scores)
+        return {};
+    const result = {};
+    for (const [key, value] of Object.entries(scores)) {
+        if (typeof value === "number" && Number.isFinite(value)) {
+            result[key] = value;
+        }
+    }
+    return result;
+}
+/**
+ * Get the rule ID from an issue for fingerprinting.
+ */
+function getRuleId(issue) {
+    return issue.ruleId || issue.rule_id || issue.id || "unknown";
+}
+/**
+ * Register the protect command with the Commander program.
+ */
+export function registerProtectCommand(program) {
+    program
+        .command("protect [url]")
+        .description("Lock current scores as policy thresholds (audit -> protect -> monitor)")
+        .option("--buffer <points>", "Points below current scores for threshold", "5")
+        .option("--ci <provider>", "CI provider: github|gitlab|circleci|azure|jenkins", "github")
+        .option("--output <path>", "Policy output path", "vertaa.policy.yml")
+        .option("--no-baseline", "Skip implicit baseline creation")
+        .option("--no-ci-snippet", "Skip CI snippet generation")
+        .option("--input <path>", "Use existing audit results JSON instead of running audit")
+        .option("--format <format>", "Output format: human|json", "human")
+        .option("--force", "Overwrite existing policy file without prompting")
+        .action(async (urlArg, options) => {
+        try {
+            await executeProtect(urlArg, options);
+        }
+        catch (error) {
+            process.stderr.write(chalk.red(`Error: ${error instanceof Error ? error.message : String(error)}\n`));
+            process.exit(ExitCode.ERROR);
+        }
+    });
+}
+/**
+ * Execute the protect flow.
+ */
+async function executeProtect(urlArg, options) {
+    const buffer = parseInt(options.buffer, 10);
+    if (isNaN(buffer) || buffer < 0) {
+        process.stderr.write(chalk.red("Error: --buffer must be a non-negative integer\n"));
+        process.exit(ExitCode.ERROR);
+    }
+    // ─── Step 1: Get audit results ──────────────────────────────────────
+    let auditData;
+    let auditUrl;
+    if (options.input) {
+        // Read from explicit input file
+        const inputPath = resolve(process.cwd(), options.input);
+        if (!existsSync(inputPath)) {
+            process.stderr.write(chalk.red(`Error: Input file not found: ${inputPath}\n`));
+            process.exit(ExitCode.ERROR);
+        }
+        try {
+            const raw = readFileSync(inputPath, "utf-8");
+            auditData = JSON.parse(raw);
+        }
+        catch (err) {
+            process.stderr.write(chalk.red(`Error: Failed to parse input file: ${err instanceof Error ? err.message : String(err)}\n`));
+            process.exit(ExitCode.ERROR);
+            return; // TypeScript flow control
+        }
+        auditUrl = auditData.url || urlArg || "unknown";
+    }
+    else {
+        // Check latest-audit.json
+        const latestPath = resolve(process.cwd(), LATEST_AUDIT_PATH);
+        if (!existsSync(latestPath)) {
+            if (urlArg) {
+                process.stderr.write(chalk.red("Error: No recent audit found.\n\n"));
+                process.stderr.write(`Run ${chalk.cyan(`vertaa audit ${urlArg}`)} first, then ${chalk.cyan(`vertaa protect ${urlArg}`)}\n`);
+            }
+            else {
+                process.stderr.write(chalk.red("Error: No audit results found.\n\n"));
+                process.stderr.write(`Run ${chalk.cyan("vertaa audit <url>")} first, then ${chalk.cyan("vertaa protect <url>")}\n`);
+                process.stderr.write(`Or provide results directly: ${chalk.cyan("vertaa protect --input <audit.json>")}\n`);
+            }
+            process.exit(ExitCode.ERROR);
+            return;
+        }
+        try {
+            const raw = readFileSync(latestPath, "utf-8");
+            auditData = JSON.parse(raw);
+        }
+        catch (err) {
+            process.stderr.write(chalk.red(`Error: Failed to parse latest audit: ${err instanceof Error ? err.message : String(err)}\n`));
+            process.exit(ExitCode.ERROR);
+            return;
+        }
+        // If URL provided, check it matches the latest audit
+        if (urlArg && auditData.url && auditData.url !== urlArg) {
+            // Check if the latest audit is for a different URL
+            process.stderr.write(chalk.yellow(`Warning: Latest audit is for ${auditData.url}, not ${urlArg}\n`));
+            process.stderr.write(`Run ${chalk.cyan(`vertaa audit ${urlArg}`)} first, then ${chalk.cyan(`vertaa protect ${urlArg}`)}\n`);
+            process.exit(ExitCode.ERROR);
+            return;
+        }
+        // Check if the audit is recent enough (within 1 hour)
+        const auditTimestamp = auditData.completed_at || auditData.created_at;
+        if (auditTimestamp) {
+            const auditAge = Date.now() - new Date(auditTimestamp).getTime();
+            if (auditAge > MAX_AUDIT_AGE_MS) {
+                const auditAuditUrl = auditData.url || "the URL";
+                process.stderr.write(chalk.yellow(`Warning: Latest audit is ${Math.round(auditAge / 60000)} minutes old.\n`));
+                process.stderr.write(`Run ${chalk.cyan(`vertaa audit ${auditAuditUrl}`)} for fresh results, then ${chalk.cyan(`vertaa protect ${auditAuditUrl}`)}\n`);
+                process.exit(ExitCode.ERROR);
+                return;
+            }
+        }
+        auditUrl = auditData.url || urlArg || "unknown";
+    }
+    // Extract numeric scores
+    const scores = extractNumericScores(auditData.scores);
+    if (Object.keys(scores).length === 0) {
+        process.stderr.write(chalk.red("Error: Audit results do not contain scores.\n"));
+        process.stderr.write("Ensure the audit completed successfully before running protect.\n");
+        process.exit(ExitCode.ERROR);
+    }
+    // ─── Step 2: Generate policy ────────────────────────────────────────
+    const policy = generatePolicyFromScores({
+        scores,
+        buffer,
+        url: auditUrl,
+    });
+    const today = new Date().toISOString().slice(0, 10);
+    const header = [
+        `# Generated by vertaa protect on ${today}`,
+        `# Thresholds set ${buffer} points below current scores`,
+        "",
+    ].join("\n");
+    const yamlContent = header + stringify(policy, { lineWidth: 120 });
+    // ─── Step 3: Write policy file ──────────────────────────────────────
+    const outputPath = resolve(process.cwd(), options.output);
+    if (existsSync(outputPath) && !options.force) {
+        process.stderr.write(chalk.yellow(`Policy file already exists at ${options.output}. Use --force to overwrite.\n`));
+        process.exit(ExitCode.ERROR);
+    }
+    // Ensure directory exists
+    const outputDir = dirname(outputPath);
+    if (!existsSync(outputDir)) {
+        mkdirSync(outputDir, { recursive: true });
+    }
+    writeFileSync(outputPath, yamlContent, "utf-8");
+    // ─── Step 4: Create implicit baseline ───────────────────────────────
+    let baselineCreated = false;
+    if (options.baseline !== false) {
+        const baselinePath = resolve(process.cwd(), DEFAULT_BASELINE_PATH);
+        // Check if an explicit baseline already exists
+        if (existsSync(baselinePath)) {
+            try {
+                const existingRaw = readFileSync(baselinePath, "utf-8");
+                const existing = JSON.parse(existingRaw);
+                if (existing.source && existing.source !== "implicit") {
+                    process.stderr.write(chalk.dim("Explicit baseline exists, keeping it (implicit baseline skipped)\n"));
+                }
+                else {
+                    // Overwrite implicit baseline with fresh one
+                    const baseline = createImplicitBaseline(auditUrl, scores, auditData.issues);
+                    const baselineDir = dirname(baselinePath);
+                    if (!existsSync(baselineDir)) {
+                        mkdirSync(baselineDir, { recursive: true });
+                    }
+                    writeFileSync(baselinePath, JSON.stringify(baseline, null, 2) + "\n", "utf-8");
+                    baselineCreated = true;
+                }
+            }
+            catch {
+                // If we can't parse existing baseline, overwrite it
+                const baseline = createImplicitBaseline(auditUrl, scores, auditData.issues);
+                const baselineDir = dirname(baselinePath);
+                if (!existsSync(baselineDir)) {
+                    mkdirSync(baselineDir, { recursive: true });
+                }
+                writeFileSync(baselinePath, JSON.stringify(baseline, null, 2) + "\n", "utf-8");
+                baselineCreated = true;
+            }
+        }
+        else {
+            // No baseline exists -- create one
+            const baseline = createImplicitBaseline(auditUrl, scores, auditData.issues);
+            const baselineDir = dirname(baselinePath);
+            if (!existsSync(baselineDir)) {
+                mkdirSync(baselineDir, { recursive: true });
+            }
+            writeFileSync(baselinePath, JSON.stringify(baseline, null, 2) + "\n", "utf-8");
+            baselineCreated = true;
+        }
+    }
+    // ─── Step 5: Generate CI snippet ───────────────────────────────────
+    let ciSnippetContent = null;
+    let ciSnippetPath = null;
+    if (options.ciSnippet !== false) {
+        const template = generateTemplate(options.ci, {
+            auditUrl: auditUrl !== "unknown" ? auditUrl : undefined,
+            threshold: policy.assertions.overall_score,
+            failOn: "error",
+            uploadSarif: true,
+            postComment: true,
+        });
+        if (template) {
+            ciSnippetContent = template.content;
+            ciSnippetPath = template.path;
+        }
+    }
+    // ─── Step 6: Output ────────────────────────────────────────────────
+    if (options.format === "json") {
+        // JSON output to stdout
+        const output = {
+            url: auditUrl,
+            policy,
+            policyPath: options.output,
+            baseline: baselineCreated
+                ? { path: DEFAULT_BASELINE_PATH, created: true }
+                : { path: DEFAULT_BASELINE_PATH, created: false },
+            ciSnippet: ciSnippetContent
+                ? { provider: options.ci, path: ciSnippetPath, content: ciSnippetContent }
+                : null,
+        };
+        process.stdout.write(JSON.stringify(output, null, 2) + "\n");
+    }
+    else {
+        // Human-readable output to stderr (status) and stdout (CI snippet)
+        process.stderr.write("\n" + chalk.green.bold("Score protected!") + "\n\n");
+        process.stderr.write(chalk.bold("What happened:") + "\n");
+        process.stderr.write(`  ${chalk.cyan("1. Audit")}    ${chalk.dim("-")} Scores captured for ${chalk.underline(auditUrl)}\n`);
+        process.stderr.write(`  ${chalk.cyan("2. Protect")}  ${chalk.dim("-")} Policy saved to ${chalk.underline(options.output)}\n`);
+        process.stderr.write(`  ${chalk.cyan("3. Monitor")}  ${chalk.dim("-")} CI snippet ready (paste into your pipeline)\n`);
+        // Policy thresholds
+        process.stderr.write("\n" + chalk.bold("Policy thresholds:") + "\n");
+        process.stderr.write(`  Overall: ${chalk.yellow(String(policy.assertions.overall_score))}\n`);
+        if (policy.budgets) {
+            for (const [category, budget] of Object.entries(policy.budgets)) {
+                const currentScore = scores[category];
+                const scoreInfo = currentScore !== undefined
+                    ? chalk.dim(` (current: ${currentScore})`)
+                    : "";
+                process.stderr.write(`  ${category}: ${chalk.yellow(String(budget.min_score))}${scoreInfo}\n`);
+            }
+        }
+        if (baselineCreated) {
+            process.stderr.write("\n" +
+                chalk.dim(`Baseline saved to ${DEFAULT_BASELINE_PATH}\n`));
+        }
+        // CI snippet
+        if (ciSnippetContent && ciSnippetPath) {
+            process.stderr.write("\n" +
+                chalk.bold(`Next step: Add this to your CI pipeline (${ciSnippetPath}):`) +
+                "\n");
+            process.stderr.write(chalk.dim("---") + "\n");
+            process.stdout.write(ciSnippetContent + "\n");
+            process.stderr.write(chalk.dim("---") + "\n");
+        }
+    }
+}
+/**
+ * Create an implicit baseline from audit data.
+ *
+ * Produces a BaselineFile with source: "implicit" marker
+ * so it can be distinguished from explicit user-created baselines.
+ */
+function createImplicitBaseline(url, scores, rawIssues) {
+    const now = new Date().toISOString();
+    const issues = normalizeIssues(rawIssues);
+    const baselineIssues = issues.map((issue) => ({
+        fingerprint: generateFingerprint(issue),
+        ruleId: getRuleId(issue),
+        severity: issue.severity || "warning",
+        category: issue.category || "general",
+        description: issue.description || issue.title || "",
+        selector: issue.selector,
+        baselinedAt: now,
+    }));
+    return {
+        version: 1,
+        created: now,
+        updated: now,
+        url,
+        source: "implicit",
+        scores,
+        issues: baselineIssues,
+    };
+}

package/dist/commands/release-notes.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Release-notes command for VertaaUX CLI.
+ *
+ * Reads diff data (via stdin, --file, or from two --job-a/--job-b jobs)
+ * and calls the LLM release-notes endpoint to produce developer-facing
+ * and PM-facing release notes.
+ *
+ * Default output is markdown; use --format json for structured output.
+ *
+ * Examples:
+ *   vertaa diff --job-a abc --job-b def --json | vertaa release-notes
+ *   vertaa release-notes --file diff.json
+ *   vertaa release-notes --job-a abc --job-b def
+ */
+import { Command } from "commander";
+export declare function registerReleaseNotesCommand(program: Command): void;
+//# sourceMappingURL=release-notes.d.ts.map

package/dist/commands/release-notes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"release-notes.d.ts","sourceRoot":"","sources":["../../src/commands/release-notes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA0EpC,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAgHlE"}

package/dist/commands/release-notes.js

@@ -0,0 +1,145 @@
+/**
+ * Release-notes command for VertaaUX CLI.
+ *
+ * Reads diff data (via stdin, --file, or from two --job-a/--job-b jobs)
+ * and calls the LLM release-notes endpoint to produce developer-facing
+ * and PM-facing release notes.
+ *
+ * Default output is markdown; use --format json for structured output.
+ *
+ * Examples:
+ *   vertaa diff --job-a abc --job-b def --json | vertaa release-notes
+ *   vertaa release-notes --file diff.json
+ *   vertaa release-notes --job-a abc --job-b def
+ */
+import chalk from "chalk";
+import { ExitCode } from "../utils/exit-codes.js";
+import { resolveApiBase, getApiKey, apiRequest } from "../utils/client.js";
+import { resolveConfig } from "../config/loader.js";
+import { writeJsonOutput, writeOutput } from "../output/envelope.js";
+import { resolveCommandFormat } from "../output/formats.js";
+import { createSpinner, succeedSpinner } from "../ui/spinner.js";
+import { readJsonInput } from "../utils/stdin.js";
+import { handleAiCommandError, AI_TIMEOUT_MS } from "../utils/ai-error.js";
+// ---------------------------------------------------------------------------
+// Formatters
+// ---------------------------------------------------------------------------
+function formatReleaseNotesHuman(data) {
+    const lines = [];
+    lines.push(chalk.bold(data.headline));
+    lines.push("");
+    lines.push(chalk.bold.blue("Developer Notes"));
+    lines.push(chalk.dim("─".repeat(40)));
+    lines.push(data.developer_notes);
+    lines.push("");
+    lines.push(chalk.bold.green("PM / User-Facing Notes"));
+    lines.push(chalk.dim("─".repeat(40)));
+    lines.push(data.pm_notes);
+    return lines.join("\n");
+}
+function formatReleaseNotesMarkdown(data) {
+    const lines = [];
+    lines.push(`# ${data.headline}`);
+    lines.push("");
+    lines.push("## Developer Notes");
+    lines.push("");
+    lines.push(data.developer_notes);
+    lines.push("");
+    lines.push("## User-Facing Notes");
+    lines.push("");
+    lines.push(data.pm_notes);
+    return lines.join("\n");
+}
+// ---------------------------------------------------------------------------
+// Command Registration
+// ---------------------------------------------------------------------------
+export function registerReleaseNotesCommand(program) {
+    program
+        .command("release-notes")
+        .description("Generate developer + PM release notes from audit diff data")
+        .option("--file <path>", "Load diff JSON from file")
+        .option("--job-a <id>", "First audit job ID (baseline)")
+        .option("--job-b <id>", "Second audit job ID (current)")
+        .option("-f, --format <format>", "Output format: json | human | markdown")
+        .addHelpText("after", `
+Examples:
+  vertaa diff --job-a abc --job-b def --json | vertaa release-notes
+  vertaa release-notes --file diff.json
+  vertaa release-notes --job-a abc --job-b def
+`)
+        .action(async (options, command) => {
+        try {
+            const globalOpts = command.optsWithGlobals();
+            const config = await resolveConfig(globalOpts.config);
+            const machineMode = globalOpts.machine || false;
+            const format = resolveCommandFormat("release-notes", options.format, machineMode);
+            // Resolve diff data
+            let diffPayload;
+            if (options.jobA && options.jobB) {
+                // Fetch diff from two jobs via the diff API
+                const base = resolveApiBase(globalOpts.base);
+                const apiKey = getApiKey(config.apiKey);
+                const diffResult = await apiRequest(base, `/diff?job_a=${encodeURIComponent(options.jobA)}&job_b=${encodeURIComponent(options.jobB)}`, { method: "GET" }, apiKey);
+                diffPayload = diffResult.data;
+            }
+            else {
+                // Read from stdin or --file
+                const input = await readJsonInput(options.file);
+                if (!input) {
+                    console.error("Error: No diff data provided.");
+                    console.error("Usage:");
+                    console.error("  vertaa diff --job-a abc --job-b def --json | vertaa release-notes");
+                    console.error("  vertaa release-notes --file diff.json");
+                    console.error("  vertaa release-notes --job-a abc --job-b def");
+                    process.exit(ExitCode.ERROR);
+                }
+                const data = input;
+                const innerData = (data.data && typeof data.data === "object" ? data.data : data);
+                // Validate shape
+                if (!Array.isArray(innerData.new) || !Array.isArray(innerData.fixed)) {
+                    console.error("Error: Invalid diff data. Expected { new: [...], fixed: [...], summary: {...} }");
+                    console.error("Pipe from: vertaa diff --job-a abc --job-b def --json | vertaa release-notes");
+                    process.exit(ExitCode.ERROR);
+                }
+                diffPayload = {
+                    new: innerData.new,
+                    fixed: innerData.fixed,
+                    present: innerData.present || null,
+                    summary: innerData.summary || {
+                        newCount: innerData.new.length,
+                        fixedCount: innerData.fixed.length,
+                        presentCount: Array.isArray(innerData.present) ? innerData.present.length : null,
+                    },
+                };
+            }
+            // Auth check
+            const base = resolveApiBase(globalOpts.base);
+            const apiKey = getApiKey(config.apiKey);
+            // Call LLM release-notes API
+            const spinner = createSpinner("Generating release notes...");
+            try {
+                const response = await Promise.race([
+                    apiRequest(base, "/cli/ai/release-notes", { method: "POST", body: { diff: diffPayload } }, apiKey),
+                    new Promise((_, reject) => setTimeout(() => reject(new Error("LLM request timed out")), AI_TIMEOUT_MS)),
+                ]);
+                succeedSpinner(spinner, "Notes ready");
+                if (format === "json") {
+                    writeJsonOutput(response.data, "release-notes");
+                }
+                else if (format === "markdown") {
+                    writeOutput(formatReleaseNotesMarkdown(response.data));
+                }
+                else {
+                    writeOutput(formatReleaseNotesHuman(response.data));
+                }
+            }
+            catch (error) {
+                handleAiCommandError(error, "release-notes", spinner);
+            }
+        }
+        catch (error) {
+            console.error("Error:", error instanceof Error ? error.message : String(error));
+            process.exit(ExitCode.ERROR);
+        }
+    });
+}

package/dist/commands/report.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Report generation command for VertaaUX CLI.
+ *
+ * Generates consolidated multi-client reports by delegating
+ * data aggregation to the server-side consolidated report API.
+ * The CLI handles formatting only -- no data computation.
+ *
+ * Implements 46-06: CLI report command.
+ */
+import { Command } from "commander";
+/**
+ * Register the report command with the Commander program.
+ */
+export declare function registerReportCommand(program: Command): void;
+//# sourceMappingURL=report.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"report.d.ts","sourceRoot":"","sources":["../../src/commands/report.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAwPpC;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAyF5D"}