@vertaaux/cli 0.2.3 → 0.3.0

package/dist/ui/spinner.js

@@ -1,101 +1,54 @@
 /**
  * Progress spinner wrapper for CLI.
  *
- * Provides a consistent interface for showing progress during long-running operations.
- * Uses ora for elegant terminal spinners with TTY detection.
+ * Delegates to @vertaaux/tui for consistent terminal rendering.
+ * Writes ONLY to stderr — never pollutes stdout.
  */
-import ora from "ora";
-import chalk from "chalk";
-import { isTTY, shouldUseColor } from "../utils/detect-env.js";
-// Spinner style - classic dots for clean look
-const SPINNER_STYLE = {
-    frames: ["\u2807", "\u2819", "\u2839", "\u2838", "\u283C", "\u2834", "\u2826", "\u2827", "\u2807", "\u280F"],
-    interval: 80,
-};
-// Brand color for spinner
-const BRAND_COLOR = "#78FFB4";
+import { createSpinner as tuiCreateSpinner, } from "@vertaaux/tui";
 /**
  * Create a new spinner instance.
  *
  * Spinner only displays in TTY mode. In non-TTY environments,
  * returns a no-op spinner that still tracks state.
- *
- * @param text - Initial text to display next to spinner
- * @returns An ora spinner instance
  */
 export function createSpinner(text) {
-    const useColor = shouldUseColor();
-    const spinner = ora({
-        text,
-        spinner: SPINNER_STYLE,
-        color: "cyan",
-        isEnabled: isTTY(),
-        stream: process.stderr, // Write to stderr to avoid mixing with command output
-    });
-    // Apply brand color if colors are enabled
-    if (useColor) {
-        spinner.color = "cyan";
-    }
-    return spinner;
+    return tuiCreateSpinner(text);
 }
 /**
  * Update spinner text with optional progress indicator.
- *
- * @param spinner - The spinner instance to update
- * @param text - New text to display
- * @param current - Current progress count (optional)
- * @param total - Total items count (optional)
  */
 export function updateSpinner(spinner, text, current, total) {
     if (current !== undefined && total !== undefined) {
-        const progress = shouldUseColor()
-            ? chalk.dim(`(${current}/${total})`)
-            : `(${current}/${total})`;
-        spinner.text = `${text} ${progress}`;
+        spinner.setText(`${text} (${current}/${total})`);
     }
     else if (current !== undefined) {
-        const progress = shouldUseColor()
-            ? chalk.dim(`(${current})`)
-            : `(${current})`;
-        spinner.text = `${text} ${progress}`;
+        spinner.setText(`${text} (${current})`);
     }
     else {
-        spinner.text = text;
+        spinner.setText(text);
     }
 }
 /**
  * Complete spinner with success state.
- *
- * @param spinner - The spinner instance
- * @param text - Success message to display
  */
 export function succeedSpinner(spinner, text) {
-    spinner.succeed(shouldUseColor() ? chalk.green(text) : text);
+    spinner.succeed(text);
 }
 /**
  * Complete spinner with failure state.
- *
- * @param spinner - The spinner instance
- * @param text - Failure message to display
  */
 export function failSpinner(spinner, text) {
-    spinner.fail(shouldUseColor() ? chalk.red(text) : text);
+    spinner.fail(text);
 }
 /**
  * Complete spinner with warning state.
- *
- * @param spinner - The spinner instance
- * @param text - Warning message to display
  */
 export function warnSpinner(spinner, text) {
-    spinner.warn(shouldUseColor() ? chalk.yellow(text) : text);
+    spinner.warn(text);
 }
 /**
  * Complete spinner with info state.
- *
- * @param spinner - The spinner instance
- * @param text - Info message to display
  */
 export function infoSpinner(spinner, text) {
-    spinner.info(shouldUseColor() ? chalk.cyan(text) : text);
+    spinner.info(text);
 }

package/dist/ui/table.d.ts

@@ -1,7 +1,7 @@
 /**
  * Table formatting utilities for CLI output.
  *
- * Uses cli-table3 for clean table rendering with severity-based coloring.
+ * Delegates to @vertaaux/tui for consistent rendering with severity-based coloring.
  * Respects terminal width and provides truncation for long content.
  */
 export interface Issue {
@@ -33,31 +33,14 @@ export declare function groupBySeverity(issues: Issue[]): Map<string, Issue[]>;
 export declare function groupByCategory(issues: Issue[]): Map<string, Issue[]>;
 /**
  * Format issues into a table string.
- *
- * Columns: Severity | ID | Description | Selector (optional)
- * Issues are sorted by severity (critical -> info).
- *
- * @param issues - Array of issues to format
- * @param options - Formatting options
- * @returns Formatted table string
  */
 export declare function formatIssuesTable(issues: Issue[], options?: FormatTableOptions): string;
-export interface Score {
-    category: string;
-    score: number;
-}
 /**
  * Format scores into a table string.
- *
- * @param scores - Object mapping category names to scores
- * @returns Formatted table string
  */
 export declare function formatScoresTable(scores: Record<string, number | unknown>): string;
 /**
  * Format a summary line showing issue counts by severity.
- *
- * @param issues - Array of issues
- * @returns Summary string like "3 critical, 5 serious, 12 minor issues"
  */
 export declare function formatIssueSummary(issues: Issue[]): string;
 //# sourceMappingURL=table.d.ts.map

package/dist/ui/table.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"table.d.ts","sourceRoot":"","sources":["../../src/ui/table.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAuCH,MAAM,WAAW,KAAK;IACpB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,kBAAkB;IACjC,2CAA2C;IAC3C,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,wCAAwC;IACxC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,0CAA0C;IAC1C,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,0CAA0C;IAC1C,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAqCD;;GAEG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,KAAK,EAAE,CAAC,CAWrE;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,KAAK,EAAE,CAAC,CAWrE;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,KAAK,EAAE,EACf,OAAO,GAAE,kBAAuB,GAC/B,MAAM,CAoER;AAED,MAAM,WAAW,KAAK;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,MAAM,CAyClF;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,CAkC1D"}
+{"version":3,"file":"table.d.ts","sourceRoot":"","sources":["../../src/ui/table.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAeH,MAAM,WAAW,KAAK;IACpB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,kBAAkB;IACjC,2CAA2C;IAC3C,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,wCAAwC;IACxC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,0CAA0C;IAC1C,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,0CAA0C;IAC1C,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAaD;;GAEG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,KAAK,EAAE,CAAC,CASrE;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,KAAK,EAAE,CAAC,CASrE;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,KAAK,EAAE,EACf,OAAO,GAAE,kBAAuB,GAC/B,MAAM,CAuCR;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,MAAM,CA2BlF;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,CA4B1D"}

package/dist/ui/table.js

@@ -1,71 +1,18 @@
 /**
  * Table formatting utilities for CLI output.
  *
- * Uses cli-table3 for clean table rendering with severity-based coloring.
+ * Delegates to @vertaaux/tui for consistent rendering with severity-based coloring.
  * Respects terminal width and provides truncation for long content.
  */
-import Table from "cli-table3";
-import chalk from "chalk";
-import { shouldUseColor, getTerminalWidth } from "../utils/detect-env.js";
-// Severity colors matching brand palette
-const SEVERITY_COLORS = {
-    critical: "#FF6B6B", // Red
-    error: "#FF6B6B", // Red (alias)
-    serious: "#FFD93D", // Yellow
-    warning: "#FFD93D", // Yellow (alias)
-    minor: "#6BCEFF", // Cyan
-    moderate: "#6BCEFF", // Cyan (alias)
-    info: "#888888", // Dim gray
-};
-// Severity display labels
-const SEVERITY_LABELS = {
-    critical: "CRITICAL",
-    error: "ERROR",
-    serious: "SERIOUS",
-    warning: "WARNING",
-    minor: "MINOR",
-    moderate: "MODERATE",
-    info: "INFO",
-};
-// Severity sort order (highest first)
-const SEVERITY_ORDER = {
-    critical: 0,
-    error: 1,
-    serious: 2,
-    warning: 3,
-    minor: 4,
-    moderate: 5,
-    info: 6,
-};
-/**
- * Truncate text to fit within max width, adding ellipsis if truncated.
- */
-function truncate(text, maxWidth) {
-    if (!text)
-        return "";
-    if (text.length <= maxWidth)
-        return text;
-    return text.slice(0, maxWidth - 3) + "...";
-}
-/**
- * Get colored severity label.
- */
-function colorSeverity(severity) {
-    const normalized = severity.toLowerCase();
-    const label = SEVERITY_LABELS[normalized] || severity.toUpperCase();
-    if (!shouldUseColor()) {
-        return label;
-    }
-    const color = SEVERITY_COLORS[normalized] || "#888888";
-    return chalk.hex(color).bold(label);
-}
+import { renderTable, text, } from "@vertaaux/tui";
+import { severityOrder, isColorEnabled, colorize, severity as severityPalette, tokens, } from "@vertaaux/tui";
 /**
  * Sort issues by severity (highest first).
  */
 function sortBySeverity(issues) {
     return [...issues].sort((a, b) => {
-        const orderA = SEVERITY_ORDER[a.severity?.toLowerCase() || "info"] ?? 6;
-        const orderB = SEVERITY_ORDER[b.severity?.toLowerCase() || "info"] ?? 6;
+        const orderA = severityOrder[a.severity?.toLowerCase() || "info"] ?? 6;
+        const orderB = severityOrder[b.severity?.toLowerCase() || "info"] ?? 6;
         return orderA - orderB;
     });
 }
@@ -75,10 +22,10 @@ function sortBySeverity(issues) {
 export function groupBySeverity(issues) {
     const groups = new Map();
     for (const issue of issues) {
-        const severity = issue.severity?.toLowerCase() || "info";
-        const group = groups.get(severity) || [];
+        const sev = issue.severity?.toLowerCase() || "info";
+        const group = groups.get(sev) || [];
         group.push(issue);
-        groups.set(severity, group);
+        groups.set(sev, group);
     }
     return groups;
 }
@@ -88,149 +35,95 @@ export function groupBySeverity(issues) {
 export function groupByCategory(issues) {
     const groups = new Map();
     for (const issue of issues) {
-        const category = issue.category || "Uncategorized";
-        const group = groups.get(category) || [];
+        const cat = issue.category || "Uncategorized";
+        const group = groups.get(cat) || [];
         group.push(issue);
-        groups.set(category, group);
+        groups.set(cat, group);
     }
     return groups;
 }
 /**
  * Format issues into a table string.
- *
- * Columns: Severity | ID | Description | Selector (optional)
- * Issues are sorted by severity (critical -> info).
- *
- * @param issues - Array of issues to format
- * @param options - Formatting options
- * @returns Formatted table string
  */
 export function formatIssuesTable(issues, options = {}) {
     if (!issues.length) {
-        return shouldUseColor()
-            ? chalk.green("No issues found.")
+        return isColorEnabled()
+            ? text.success("No issues found.")
             : "No issues found.";
     }
-    const termWidth = getTerminalWidth();
-    const { maxDescriptionWidth = Math.min(50, Math.floor(termWidth * 0.4)), maxSelectorWidth = Math.min(30, Math.floor(termWidth * 0.2)), showSelector = true, showCategory = false, } = options;
-    // Calculate column widths
-    const severityWidth = 10;
-    const idWidth = 20;
-    // Build header
-    const header = ["Severity", "ID", "Description"];
-    const colWidths = [severityWidth, idWidth, maxDescriptionWidth];
+    const { maxDescriptionWidth = 50, maxSelectorWidth = 30, showSelector = true, showCategory = false, } = options;
+    const sorted = sortBySeverity(issues);
+    const columns = [
+        { key: "severity", label: "Severity", width: 10, color: (val) => text.severityBadge(val) },
+        { key: "id", label: "ID", width: 20 },
+        { key: "description", label: "Description", width: maxDescriptionWidth },
+    ];
     if (showCategory) {
-        header.push("Category");
-        colWidths.push(15);
+        columns.push({ key: "category", label: "Category", width: 15 });
     }
     if (showSelector) {
-        header.push("Selector");
-        colWidths.push(maxSelectorWidth);
+        columns.push({ key: "selector", label: "Selector", width: maxSelectorWidth });
     }
-    const useColor = shouldUseColor();
-    const table = new Table({
-        head: useColor
-            ? header.map((h) => chalk.bold(h))
-            : header,
-        colWidths,
-        style: {
-            head: useColor ? ["cyan"] : [],
-            border: useColor ? ["dim"] : [],
-        },
-        wordWrap: true,
-    });
-    // Sort and add rows
-    const sortedIssues = sortBySeverity(issues);
-    for (const issue of sortedIssues) {
-        const row = [
-            colorSeverity(issue.severity || "info"),
-            truncate(issue.id || "-", idWidth - 2),
-            truncate(issue.description || issue.title || "-", maxDescriptionWidth - 2),
-        ];
-        if (showCategory) {
-            row.push(truncate(issue.category || "-", 13));
-        }
-        if (showSelector) {
-            row.push(truncate(issue.selector || "-", maxSelectorWidth - 2));
-        }
-        table.push(row);
-    }
-    return table.toString();
+    const rows = sorted.map((issue) => ({
+        severity: issue.severity?.toLowerCase() || "info",
+        id: issue.id || "-",
+        description: issue.description || issue.title || "-",
+        category: issue.category || "-",
+        selector: issue.selector || "-",
+    }));
+    return renderTable(rows, columns);
 }
 /**
  * Format scores into a table string.
- *
- * @param scores - Object mapping category names to scores
- * @returns Formatted table string
  */
 export function formatScoresTable(scores) {
     const entries = Object.entries(scores).filter(([, value]) => typeof value === "number");
     if (!entries.length) {
-        return shouldUseColor()
-            ? chalk.dim("No scores available.")
+        return isColorEnabled()
+            ? text.dim("No scores available.")
             : "No scores available.";
     }
-    const useColor = shouldUseColor();
-    const table = new Table({
-        head: useColor
-            ? [chalk.bold("Category"), chalk.bold("Score")]
-            : ["Category", "Score"],
-        colWidths: [20, 10],
-        style: {
-            head: useColor ? ["cyan"] : [],
-            border: useColor ? ["dim"] : [],
+    const columns = [
+        { key: "category", label: "Category", width: 20 },
+        {
+            key: "score",
+            label: "Score",
+            width: 10,
+            color: (val) => text.scoreBadge(Number(val)),
         },
-    });
-    for (const [category, score] of entries) {
-        const numScore = score;
-        let scoreStr = String(numScore);
-        if (useColor) {
-            if (numScore >= 90) {
-                scoreStr = chalk.green.bold(scoreStr);
-            }
-            else if (numScore >= 70) {
-                scoreStr = chalk.yellow(scoreStr);
-            }
-            else {
-                scoreStr = chalk.red(scoreStr);
-            }
-        }
-        table.push([category, scoreStr]);
-    }
-    return table.toString();
+    ];
+    const rows = entries.map(([category, score]) => ({
+        category,
+        score: String(score),
+    }));
+    return renderTable(rows, columns);
 }
 /**
  * Format a summary line showing issue counts by severity.
- *
- * @param issues - Array of issues
- * @returns Summary string like "3 critical, 5 serious, 12 minor issues"
  */
 export function formatIssueSummary(issues) {
     const counts = {};
     for (const issue of issues) {
-        const severity = issue.severity?.toLowerCase() || "info";
-        counts[severity] = (counts[severity] || 0) + 1;
+        const sev = issue.severity?.toLowerCase() || "info";
+        counts[sev] = (counts[sev] || 0) + 1;
     }
-    const useColor = shouldUseColor();
-    const parts = [];
-    // Order: critical, serious, minor, info
     const order = ["critical", "error", "serious", "warning", "minor", "moderate", "info"];
-    for (const severity of order) {
-        const count = counts[severity];
+    const parts = [];
+    for (const sev of order) {
+        const count = counts[sev];
         if (count) {
-            const label = count === 1 ? severity : severity;
-            const text = `${count} ${label}`;
-            if (useColor) {
-                const color = SEVERITY_COLORS[severity] || "#888888";
-                parts.push(chalk.hex(color)(text));
+            const label = `${count} ${sev}`;
+            if (isColorEnabled()) {
+                const hex = severityPalette[sev] || tokens.muted;
+                parts.push(colorize(label, hex));
             }
             else {
-                parts.push(text);
+                parts.push(label);
             }
         }
     }
     if (!parts.length) {
-        return useColor ? chalk.green("No issues") : "No issues";
+        return isColorEnabled() ? text.success("No issues") : "No issues";
     }
     return parts.join(", ") + " issues";
 }

package/dist/utils/ai-error.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Centralized AI error classification and formatting for CLI commands.
+ *
+ * Provides consistent error handling across all 8 AI-powered commands.
+ * Classifies errors into distinct types (timeout, unreachable, auth, etc.)
+ * and formats user-friendly messages with actionable suggestions.
+ */
+import { type SpinnerInstance } from "../ui/spinner.js";
+/** Default timeout for LLM API requests (30 seconds). */
+export declare const AI_TIMEOUT_MS = 30000;
+/**
+ * Classification of AI/LLM errors.
+ *
+ * Each kind maps to a distinct user-facing message with tailored suggestions.
+ */
+export type AiErrorKind = "timeout" | "unreachable" | "auth" | "invalid_response" | "rate_limit" | "server_error" | "unknown";
+/**
+ * Classify an unknown error into a specific AI error kind.
+ *
+ * Inspects error properties (name, code, message, status) to determine
+ * the most specific classification. Falls back to `"unknown"` when no
+ * pattern matches.
+ *
+ * @param error - The caught error (any type)
+ * @returns The classified error kind
+ */
+export declare function classifyAiError(error: unknown): AiErrorKind;
+/**
+ * Format an AI error kind into a user-friendly message with suggestions.
+ *
+ * @param kind - The classified error kind
+ * @param command - The CLI command name (e.g., "explain", "triage")
+ * @returns Multi-line string with error description and actionable suggestions
+ */
+export declare function formatAiError(kind: AiErrorKind, command: string): string;
+/**
+ * Handle an AI command error: classify, format, display, and exit.
+ *
+ * This is the primary entry point for error handling in AI commands.
+ * It classifies the error, fails the spinner with a summary, writes
+ * the full formatted message to stderr, and exits with ExitCode.ERROR.
+ *
+ * @param error - The caught error
+ * @param command - The CLI command name (e.g., "explain", "triage")
+ * @param spinner - Active spinner instance to fail
+ */
+export declare function handleAiCommandError(error: unknown, command: string, spinner: SpinnerInstance): never;
+//# sourceMappingURL=ai-error.d.ts.map

package/dist/utils/ai-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-error.d.ts","sourceRoot":"","sources":["../../src/utils/ai-error.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAe,KAAK,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAMrE,yDAAyD;AACzD,eAAO,MAAM,aAAa,QAAS,CAAC;AAMpC;;;;GAIG;AACH,MAAM,MAAM,WAAW,GACnB,SAAS,GACT,aAAa,GACb,MAAM,GACN,kBAAkB,GAClB,YAAY,GACZ,cAAc,GACd,SAAS,CAAC;AAMd;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,WAAW,CAoF3D;AAeD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CA2DxE;AAMD;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,eAAe,GACvB,KAAK,CAQP"}