@vertaaux/cli 0.3.3 → 0.5.0

package/dist/commands/baseline.d.ts

@@ -15,6 +15,7 @@ export interface BaselineCommandOptions {
     list?: boolean;
     base?: string;
 }
+export declare function handleBaseline(jobIdArg: string | undefined, cmdOptions: BaselineCommandOptions): Promise<void>;
 /**
  * Register the baseline command with the Commander program.
  */

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

@@ -1 +1 @@
-{"version":3,"file":"baseline.d.ts","sourceRoot":"","sources":["../../src/commands/baseline.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAoIzC,MAAM,WAAW,sBAAsB;IACrC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA8H9D"}
+{"version":3,"file":"baseline.d.ts","sourceRoot":"","sources":["../../src/commands/baseline.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAsFzC,MAAM,WAAW,sBAAsB;IACrC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,wBAAsB,cAAc,CAClC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,UAAU,EAAE,sBAAsB,GACjC,OAAO,CAAC,IAAI,CAAC,CAkOf;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA4B9D"}

package/dist/commands/baseline.js

@@ -8,51 +8,18 @@
  */
 import { readFile } from "fs/promises";
 import { existsSync } from "fs";
+import { renderError, renderWarning, runSteps, createRenderer } from "@vertaaux/tui";
 import { ExitCode } from "../utils/exit-codes.js";
+import { createClient } from "../utils/client.js";
 import { loadBaseline, saveBaseline, createBaseline, addToBaseline, DEFAULT_BASELINE_PATH, } from "../baseline/manager.js";
 import { generateFingerprint } from "../baseline/hash.js";
-const DEFAULT_API_BASE = "https://vertaaux.ai/v1";
+import { writeOutput } from "../output/envelope.js";
+import { strings } from "../ui/strings.js";
 /**
- * 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.
+ * Fetch audit results via SDK client.
  */
 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());
+    return createClient().audits.retrieve(jobId);
 }
 /**
  * Normalize issues from various API response formats.
@@ -106,6 +73,199 @@ function formatBaselineSummary(baseline) {
     }
     return lines.join("\n");
 }
+export async function handleBaseline(jobIdArg, cmdOptions) {
+    const baselinePath = cmdOptions.path || DEFAULT_BASELINE_PATH;
+    const renderer = createRenderer("auto");
+    const baseState = {
+        phase: "baseline",
+        phaseIndex: 1,
+        phaseTotal: 1,
+        url: "",
+        mode: "baseline",
+        progress: {},
+        totals: {},
+        issueCount: 0,
+        scorePreview: null,
+        verbose: false,
+        elapsed: 0,
+    };
+    const startTime = Date.now();
+    // Handle --list: show baseline summary
+    if (cmdOptions.list) {
+        const steps = [
+            {
+                id: "fetch",
+                actionText: "Fetching baseline...",
+                summaryText: "Baseline loaded",
+                run: async () => {
+                    const baseline = await loadBaseline(baselinePath);
+                    if (!baseline) {
+                        process.stderr.write(renderWarning({
+                            message: "No baseline found.",
+                            suggestion: `vertaa baseline <job-id> --path ${baselinePath}`,
+                        }) + "\n");
+                        return;
+                    }
+                    writeOutput(formatBaselineSummary(baseline));
+                },
+            },
+        ];
+        const { success, states } = await runSteps(steps, {
+            failFast: true,
+            onStateChange: (stepStates) => {
+                renderer.update({ ...baseState, stepStates, elapsed: Date.now() - startTime });
+            },
+        });
+        renderer.finish({ url: "", mode: "baseline", overallScore: 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 doctor",
+            }) + "\n");
+            process.exitCode = ExitCode.ERROR;
+        }
+        return;
+    }
+    // Handle --ignore: add single issue to baseline
+    if (cmdOptions.ignore) {
+        const issueId = cmdOptions.ignore;
+        const steps = [
+            {
+                id: "update",
+                actionText: "Updating baseline...",
+                summaryText: "Baseline updated",
+                run: async () => {
+                    let baseline = await loadBaseline(baselinePath);
+                    if (!baseline) {
+                        throw new Error("No baseline found. Create one first with: vertaa baseline <job-id>");
+                    }
+                    // Need to find the issue to add it properly
+                    let issue;
+                    if (jobIdArg) {
+                        const audit = await fetchAudit(jobIdArg);
+                        const issues = normalizeIssues(audit.issues);
+                        const found = findIssueById(issues, issueId);
+                        if (!found) {
+                            throw new Error(`Issue "${issueId}" not found in job ${jobIdArg}`);
+                        }
+                        issue = found;
+                    }
+                    else {
+                        // Create minimal issue from ID only
+                        issue = { id: issueId, description: `Ignored: ${issueId}` };
+                    }
+                    baseline = addToBaseline(baseline, issue, cmdOptions.reason);
+                    await saveBaseline(baseline, baselinePath);
+                },
+            },
+        ];
+        const { success: ignoreSuccess, states: ignoreStates } = await runSteps(steps, {
+            failFast: true,
+            onStateChange: (stepStates) => {
+                renderer.update({ ...baseState, stepStates, elapsed: Date.now() - startTime });
+            },
+        });
+        renderer.finish({ url: "", mode: "baseline", overallScore: 0, scores: {}, issueCount: 0, passed: ignoreSuccess, elapsed: Date.now() - startTime });
+        if (!ignoreSuccess) {
+            const failed = ignoreStates.find(s => s.status === "failed");
+            process.stderr.write(renderError({
+                message: failed?.failReason || "Command failed",
+                suggestion: "vertaa doctor",
+            }) + "\n");
+            process.exitCode = ExitCode.ERROR;
+        }
+        writeOutput(`Added issue ${issueId} to baseline${cmdOptions.reason ? `\nReason: ${cmdOptions.reason}` : ""}`);
+        return;
+    }
+    // Handle --from-file: create baseline from JSON file
+    if (cmdOptions.fromFile) {
+        const filePath = cmdOptions.fromFile;
+        if (!existsSync(filePath)) {
+            process.stderr.write(renderError({
+                message: `File not found: ${filePath}`,
+                suggestion: "vertaa audit <url>",
+                exitCode: ExitCode.ERROR,
+            }) + "\n");
+            process.exit(ExitCode.ERROR);
+        }
+        const steps = [
+            {
+                id: "save",
+                actionText: "Saving baseline...",
+                summaryText: "Baseline saved",
+                run: async () => {
+                    const content = await readFile(filePath, "utf-8");
+                    const data = JSON.parse(content);
+                    const issues = normalizeIssues(data.issues);
+                    const url = data.url || "unknown";
+                    const baseline = createBaseline(issues, url);
+                    await saveBaseline(baseline, baselinePath);
+                    writeOutput(`Baseline created with ${issues.length} issues\nSaved to: ${baselinePath}`);
+                },
+            },
+        ];
+        const { success: fileSuccess, states: fileStates } = await runSteps(steps, {
+            failFast: true,
+            onStateChange: (stepStates) => {
+                renderer.update({ ...baseState, stepStates, elapsed: Date.now() - startTime });
+            },
+        });
+        renderer.finish({ url: "", mode: "baseline", overallScore: 0, scores: {}, issueCount: 0, passed: fileSuccess, elapsed: Date.now() - startTime });
+        if (!fileSuccess) {
+            const failed = fileStates.find(s => s.status === "failed");
+            process.stderr.write(renderError({
+                message: failed?.failReason || "Command failed",
+                suggestion: "vertaa doctor",
+            }) + "\n");
+            process.exitCode = ExitCode.ERROR;
+        }
+        return;
+    }
+    // Handle job-id: create baseline from API audit
+    if (!jobIdArg) {
+        process.stderr.write(renderError({
+            message: "Provide job ID or use --from-file or --list",
+            context: "Usage: vertaa baseline <job-id>\n       vertaa baseline --from-file <audit.json>\n       vertaa baseline --list",
+            suggestion: "vertaa baseline --list",
+            exitCode: ExitCode.ERROR,
+        }) + "\n");
+        process.exit(ExitCode.ERROR);
+    }
+    const steps = [
+        {
+            id: "fetch",
+            actionText: "Fetching audit results...",
+            summaryText: "Audit results loaded",
+            run: async () => {
+                const audit = await fetchAudit(jobIdArg);
+                if (audit.status !== "completed") {
+                    throw new Error(strings.fixAll.auditIncomplete(jobIdArg, audit.status || "unknown"));
+                }
+                const issues = normalizeIssues(audit.issues);
+                const url = audit.url || "unknown";
+                const baseline = createBaseline(issues, url);
+                await saveBaseline(baseline, baselinePath);
+                writeOutput(`Baseline created with ${issues.length} issues\nSaved to: ${baselinePath}`);
+            },
+        },
+    ];
+    const { success: jobSuccess, states: jobStates } = await runSteps(steps, {
+        failFast: true,
+        onStateChange: (stepStates) => {
+            renderer.update({ ...baseState, stepStates, elapsed: Date.now() - startTime });
+        },
+    });
+    renderer.finish({ url: "", mode: "baseline", overallScore: 0, scores: {}, issueCount: 0, passed: jobSuccess, elapsed: Date.now() - startTime });
+    if (!jobSuccess) {
+        const failed = jobStates.find(s => s.status === "failed");
+        process.stderr.write(renderError({
+            message: failed?.failReason || "Command failed",
+            suggestion: "vertaa doctor",
+        }) + "\n");
+        process.exitCode = ExitCode.ERROR;
+    }
+}
 /**
  * Register the baseline command with the Commander program.
  */
@@ -120,90 +280,14 @@ export function registerBaselineCommand(program) {
         .option("--list", "Show baselined issues count and last update")
         .action(async (jobIdArg, cmdOptions) => {
         try {
-            const baselinePath = cmdOptions.path || DEFAULT_BASELINE_PATH;
-            // Handle --list: show baseline summary
-            if (cmdOptions.list) {
-                const baseline = await loadBaseline(baselinePath);
-                if (!baseline) {
-                    console.error("No baseline found.");
-                    console.error(`Create one with: vertaa baseline <job-id> --path ${baselinePath}`);
-                    return;
-                }
-                console.error(formatBaselineSummary(baseline));
-                return;
-            }
-            // Handle --ignore: add single issue to baseline
-            if (cmdOptions.ignore) {
-                const issueId = cmdOptions.ignore;
-                let baseline = await loadBaseline(baselinePath);
-                if (!baseline) {
-                    console.error("No baseline found. Create one first with: vertaa baseline <job-id>");
-                    process.exit(ExitCode.ERROR);
-                }
-                // Need to find the issue to add it properly
-                // If we have a job ID, fetch the audit; otherwise use a minimal issue
-                let issue;
-                if (jobIdArg) {
-                    const audit = await fetchAudit(jobIdArg);
-                    const issues = normalizeIssues(audit.issues);
-                    const found = findIssueById(issues, issueId);
-                    if (!found) {
-                        console.error(`Issue "${issueId}" not found in job ${jobIdArg}`);
-                        process.exit(ExitCode.ERROR);
-                    }
-                    issue = found;
-                }
-                else {
-                    // Create minimal issue from ID only
-                    issue = { id: issueId, description: `Ignored: ${issueId}` };
-                }
-                baseline = addToBaseline(baseline, issue, cmdOptions.reason);
-                await saveBaseline(baseline, baselinePath);
-                console.error(`Added issue ${issueId} to baseline`);
-                if (cmdOptions.reason) {
-                    console.error(`Reason: ${cmdOptions.reason}`);
-                }
-                return;
-            }
-            // Handle --from-file: create baseline from JSON file
-            if (cmdOptions.fromFile) {
-                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);
-                const issues = normalizeIssues(data.issues);
-                const url = data.url || "unknown";
-                const baseline = createBaseline(issues, url);
-                await saveBaseline(baseline, baselinePath);
-                console.error(`Baseline created with ${issues.length} issues`);
-                console.error(`Saved to: ${baselinePath}`);
-                return;
-            }
-            // Handle job-id: create baseline from API audit
-            if (!jobIdArg) {
-                console.error("Provide job ID or use --from-file or --list");
-                console.error("Usage: vertaa baseline <job-id>");
-                console.error("       vertaa baseline --from-file <audit.json>");
-                console.error("       vertaa baseline --list");
-                process.exit(ExitCode.ERROR);
-            }
-            const audit = await fetchAudit(jobIdArg);
-            if (audit.status !== "completed") {
-                console.error(`Audit ${jobIdArg} is not completed (status: ${audit.status})`);
-                process.exit(ExitCode.ERROR);
-            }
-            const issues = normalizeIssues(audit.issues);
-            const url = audit.url || "unknown";
-            const baseline = createBaseline(issues, url);
-            await saveBaseline(baseline, baselinePath);
-            console.error(`Baseline created with ${issues.length} issues`);
-            console.error(`Saved to: ${baselinePath}`);
+            await handleBaseline(jobIdArg, cmdOptions);
         }
         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/comment.d.ts

@@ -6,6 +6,28 @@
  * Uses sticky comment semantics to update existing comments.
  */
 import { Command } from "commander";
+import { type MarkdownOptions } from "../output/markdown.js";
+/**
+ * Options for comment generation.
+ */
+interface CommentOptions {
+    input?: string;
+    baseline?: string;
+    format?: "markdown" | "json";
+    output?: string;
+    collapse?: boolean;
+    groupBy?: MarkdownOptions["groupBy"];
+    post?: boolean;
+    githubToken?: string;
+    gitlabToken?: string;
+    pr?: number;
+    repo?: string;
+    noPostIfClean?: boolean;
+}
+/**
+ * Handle the comment command.
+ */
+export declare function handleComment(options: CommentOptions): Promise<void>;
 /**
  * Register the comment command with the Commander program.
  */

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

@@ -1 +1 @@
-{"version":3,"file":"comment.d.ts","sourceRoot":"","sources":["../../src/commands/comment.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAgZpC;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA6F7D;AAGD,OAAO,EAAE,qBAAqB,IAAI,eAAe,EAAE,MAAM,uBAAuB,CAAC"}
+{"version":3,"file":"comment.d.ts","sourceRoot":"","sources":["../../src/commands/comment.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAOpC,OAAO,EAGL,KAAK,eAAe,EAErB,MAAM,uBAAuB,CAAC;AA0B/B;;GAEG;AACH,UAAU,cAAc;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,UAAU,GAAG,MAAM,CAAC;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,OAAO,CAAC,EAAE,eAAe,CAAC,SAAS,CAAC,CAAC;IAErC,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAqJD;;GAEG;AACH,wBAAsB,aAAa,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAyQ1E;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAgG7D;AAGD,OAAO,EAAE,qBAAqB,IAAI,eAAe,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/commands/comment.js

@@ -7,6 +7,7 @@
  */
 import fs from "fs";
 import path from "path";
+import { renderError, runSteps, createRenderer } from "@vertaaux/tui";
 import { loadBaseline } from "../baseline/manager.js";
 import { ExitCode } from "../utils/exit-codes.js";
 import { formatMarkdownComment, categorizeIssuesForComment, } from "../output/markdown.js";
@@ -14,6 +15,7 @@ import { createEnvelope, writeJsonOutput, writeOutput } from "../output/envelope
 import { resolveCommandFormat } from "../output/formats.js";
 import { postOrUpdateGitHubComment, parseRepository, extractPRNumber, } from "../ci/github-api.js";
 import { postOrUpdateGitLabNote, getGitLabConfig, extractMRIid, } from "../ci/gitlab-api.js";
+import { strings } from "../ui/strings.js";
 /**
  * Default path for latest audit results.
  */
@@ -126,14 +128,33 @@ async function postComment(context, markdown) {
 /**
  * Handle the comment command.
  */
-async function handleComment(options) {
+export async function handleComment(options) {
+    const renderer = createRenderer("auto");
+    const baseState = {
+        phase: "comment",
+        phaseIndex: 1,
+        phaseTotal: 1,
+        url: "",
+        mode: "comment",
+        progress: {},
+        totals: {},
+        issueCount: 0,
+        scorePreview: null,
+        verbose: false,
+        elapsed: 0,
+    };
+    const startTime = Date.now();
     let auditResult;
-    // Load audit results
+    // Load audit results (pre-step, may need async iteration for stdin)
     if (options.input) {
         // From file
         const inputPath = path.resolve(process.cwd(), options.input);
         if (!fs.existsSync(inputPath)) {
-            console.error(`Error: Input file not found: ${options.input}`);
+            process.stderr.write(renderError({
+                message: `Input file not found: ${options.input}`,
+                suggestion: "vertaa audit <url>",
+                exitCode: ExitCode.ERROR,
+            }) + "\n");
             process.exit(ExitCode.ERROR);
         }
         const content = fs.readFileSync(inputPath, "utf-8");
@@ -156,7 +177,11 @@ async function handleComment(options) {
             auditResult = JSON.parse(content);
         }
         else {
-            console.error("Error: No audit results found. Provide --input or pipe results.");
+            process.stderr.write(renderError({
+                message: strings.comment.errors.noInput,
+                suggestion: "vertaa audit <url>",
+                exitCode: ExitCode.ERROR,
+            }) + "\n");
             process.exit(ExitCode.ERROR);
         }
     }
@@ -169,58 +194,85 @@ async function handleComment(options) {
         // Try default baseline
         baseline = await loadBaseline();
     }
-    // Categorize issues
-    const issues = normalizeIssues(auditResult.issues);
-    const { newIssues, fixedIssues, existingIssues } = categorizeIssuesForComment(issues, baseline);
-    // Build comment data
-    const commentData = {
-        auditId: auditResult.job_id,
-        url: auditResult.url,
-        newIssues,
-        fixedIssues,
-        existingIssues,
-        scores: auditResult.scores,
-    };
-    // Generate output
+    // State to capture within steps
+    let outputContent = "";
+    let jsonData = {};
     const isJson = options.format === "json";
-    const jsonData = {
-        auditId: auditResult.job_id,
-        url: auditResult.url,
-        newIssues: newIssues.length,
-        existingIssues: existingIssues.length,
-        fixedIssues: fixedIssues.length,
-        issues: {
-            new: newIssues,
-            existing: existingIssues,
-            fixed: fixedIssues,
+    const steps = [
+        {
+            id: "generate",
+            actionText: "Generating review comment...",
+            summaryText: "Comment generated",
+            run: async () => {
+                // Categorize issues
+                const issues = normalizeIssues(auditResult.issues);
+                const { newIssues, fixedIssues, existingIssues } = categorizeIssuesForComment(issues, baseline);
+                // Build comment data
+                const commentData = {
+                    auditId: auditResult.job_id,
+                    url: auditResult.url,
+                    newIssues,
+                    fixedIssues,
+                    existingIssues,
+                    scores: auditResult.scores,
+                };
+                jsonData = {
+                    auditId: auditResult.job_id,
+                    url: auditResult.url,
+                    newIssues: newIssues.length,
+                    existingIssues: existingIssues.length,
+                    fixedIssues: fixedIssues.length,
+                    issues: {
+                        new: newIssues,
+                        existing: existingIssues,
+                        fixed: fixedIssues,
+                    },
+                };
+                if (isJson) {
+                    outputContent = JSON.stringify(jsonData, null, 2);
+                }
+                else {
+                    outputContent = formatMarkdownComment(commentData, {
+                        groupBy: options.groupBy || "severity",
+                        collapse: options.collapse ?? newIssues.length > 3,
+                        collapseThreshold: 3,
+                        includeEvidence: true,
+                        includeFixes: true,
+                        baseUrl: "https://vertaaux.ai",
+                    });
+                }
+            },
         },
-    };
-    let output;
-    if (isJson) {
-        // JSON format - will be wrapped in envelope at output time
-        output = JSON.stringify(jsonData, null, 2);
+    ];
+    // Check if posting and we should skip
+    if (options.post && options.noPostIfClean) {
+        // We need to generate first to check, so we still run the step
     }
-    else {
-        // Markdown format (default)
-        output = formatMarkdownComment(commentData, {
-            groupBy: options.groupBy || "severity",
-            collapse: options.collapse ?? newIssues.length > 3,
-            collapseThreshold: 3,
-            includeEvidence: true,
-            includeFixes: true,
-            baseUrl: "https://vertaaux.ai",
-        });
+    const { success, states } = await runSteps(steps, {
+        failFast: true,
+        onStateChange: (stepStates) => {
+            renderer.update({ ...baseState, stepStates, elapsed: Date.now() - startTime });
+        },
+    });
+    renderer.finish({ url: "", mode: "comment", overallScore: 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 doctor",
+        }) + "\n");
+        process.exitCode = ExitCode.ERROR;
     }
     // Handle posting
     if (options.post) {
+        const newIssuesCount = jsonData.newIssues ?? 0;
         // Check if we should skip posting
-        if (options.noPostIfClean && newIssues.length === 0) {
-            console.error("No new issues found. Skipping comment post (--no-post-if-clean).");
+        if (options.noPostIfClean && newIssuesCount === 0) {
             // Still write output if requested
             if (options.output) {
                 const outputPath = path.resolve(process.cwd(), options.output);
-                fs.writeFileSync(outputPath, output, "utf-8");
-                console.error(`Comment written to: ${outputPath}`);
+                fs.writeFileSync(outputPath, outputContent, "utf-8");
+                writeOutput(`Comment written to: ${outputPath}`);
             }
             return;
         }
@@ -264,30 +316,38 @@ async function handleComment(options) {
             context = detectCIContext();
         }
         if (!context) {
-            console.error("Error: Cannot post comment - not in a recognized CI environment.");
-            console.error("Provide --github-token with --repo and --pr, or run in GitHub Actions/GitLab CI.");
+            process.stderr.write(renderError({
+                message: "Cannot post comment — not in a recognized CI environment.",
+                context: "Provide --github-token with --repo and --pr, or run in GitHub Actions/GitLab CI.",
+                suggestion: "vertaa comment --github-token <token> --repo owner/repo --pr <number>",
+                exitCode: ExitCode.ERROR,
+            }) + "\n");
             // Output for debugging via stdout
             if (isJson) {
                 writeJsonOutput(jsonData, "comment");
             }
             else {
-                writeOutput(output);
+                writeOutput(outputContent);
             }
             process.exit(ExitCode.ERROR);
         }
         try {
-            const result = await postComment(context, output);
-            console.error(`Comment posted: ${result.url}`);
+            const result = await postComment(context, outputContent);
+            writeOutput(`Comment posted: ${result.url}`);
         }
         catch (error) {
-            console.error(`Error posting comment: ${error instanceof Error ? error.message : String(error)}`);
+            process.stderr.write(renderError({
+                message: `Error posting comment: ${error instanceof Error ? error.message : String(error)}`,
+                context: "Generated output written for debugging.",
+                suggestion: "vertaa comment --github-token <token> --repo owner/repo --pr <number>",
+                exitCode: ExitCode.ERROR,
+            }) + "\n");
             // Output for debugging even on failure
-            console.error("\nGenerated output (for debugging):");
             if (isJson) {
                 writeJsonOutput(jsonData, "comment");
             }
             else {
-                writeOutput(output);
+                writeOutput(outputContent);
             }
             process.exit(ExitCode.ERROR);
         }
@@ -297,9 +357,9 @@ async function handleComment(options) {
         const outputPath = path.resolve(process.cwd(), options.output);
         const fileContent = isJson
             ? JSON.stringify(createEnvelope(jsonData, "comment"), null, 2)
-            : output;
+            : outputContent;
         fs.writeFileSync(outputPath, fileContent, "utf-8");
-        console.error(`Comment written to: ${outputPath}`);
+        writeOutput(`Comment written to: ${outputPath}`);
     }
     else if (!options.post) {
         // Only print to stdout if not posting (posting already logs URL)
@@ -307,7 +367,7 @@ async function handleComment(options) {
             writeJsonOutput(jsonData, "comment");
         }
         else {
-            writeOutput(output);
+            writeOutput(outputContent);
         }
     }
 }
@@ -354,7 +414,11 @@ export function registerCommentCommand(program) {
             });
         }
         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);
         }
     });