@vertaaux/cli 0.2.2 → 0.3.0

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"}

package/dist/utils/ai-error.js

@@ -0,0 +1,190 @@
+/**
+ * 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 { ExitCode } from "./exit-codes.js";
+import { failSpinner } from "../ui/spinner.js";
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** Default timeout for LLM API requests (30 seconds). */
+export const AI_TIMEOUT_MS = 30_000;
+// ---------------------------------------------------------------------------
+// Classification
+// ---------------------------------------------------------------------------
+/**
+ * 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 function classifyAiError(error) {
+    if (!error)
+        return "unknown";
+    const err = error;
+    const name = typeof err.name === "string" ? err.name : "";
+    const code = typeof err.code === "string" ? err.code : "";
+    const message = error instanceof Error
+        ? error.message.toLowerCase()
+        : typeof error === "string"
+            ? error.toLowerCase()
+            : "";
+    const status = typeof err.status === "number"
+        ? err.status
+        : typeof err.statusCode === "number"
+            ? err.statusCode
+            : extractHttpStatus(message);
+    // Timeout indicators
+    if (name === "AbortError" ||
+        code === "ETIMEDOUT" ||
+        code === "TIMEOUT" ||
+        code === "UND_ERR_CONNECT_TIMEOUT" ||
+        message.includes("timeout") ||
+        message.includes("timed out") ||
+        message.includes("aborted")) {
+        return "timeout";
+    }
+    // Unreachable / network errors
+    if (code === "ECONNREFUSED" ||
+        code === "ENOTFOUND" ||
+        code === "ECONNRESET" ||
+        code === "FETCH_ERROR" ||
+        code === "UND_ERR_SOCKET" ||
+        message.includes("fetch failed") ||
+        message.includes("network error") ||
+        message.includes("dns resolution") ||
+        name === "TypeError" && message.includes("fetch")) {
+        return "unreachable";
+    }
+    // HTTP status-based classification
+    if (status !== null) {
+        if (status === 401 || status === 403)
+            return "auth";
+        if (status === 429)
+            return "rate_limit";
+        if (status >= 500)
+            return "server_error";
+    }
+    // Auth keywords in message
+    if (message.includes("unauthorized") ||
+        message.includes("authentication required") ||
+        message.includes("invalid api key") ||
+        message.includes("forbidden")) {
+        return "auth";
+    }
+    // Rate limit keywords
+    if (message.includes("rate limit") ||
+        message.includes("too many requests")) {
+        return "rate_limit";
+    }
+    // Invalid response / schema mismatch
+    if (message.includes("unexpected token") ||
+        message.includes("invalid json") ||
+        message.includes("unexpected response") ||
+        message.includes("schema") ||
+        message.includes("validation failed")) {
+        return "invalid_response";
+    }
+    return "unknown";
+}
+/**
+ * Extract an HTTP status code from an error message like "HTTP 401: Unauthorized".
+ */
+function extractHttpStatus(message) {
+    const match = message.match(/\bhttp\s+(\d{3})\b/i);
+    if (match)
+        return parseInt(match[1], 10);
+    return null;
+}
+// ---------------------------------------------------------------------------
+// Formatting
+// ---------------------------------------------------------------------------
+/**
+ * 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 function formatAiError(kind, command) {
+    switch (kind) {
+        case "timeout":
+            return [
+                "LLM request timed out after 30 seconds.",
+                "",
+                "  Suggestions:",
+                "  - Try again (transient server load)",
+                "  - Use a simpler audit (fewer issues = faster response)",
+                "  - Check service status at https://status.vertaaux.ai",
+            ].join("\n");
+        case "unreachable":
+            return [
+                "Could not reach the VertaaUX API.",
+                "",
+                "  Suggestions:",
+                "  - Check your internet connection",
+                "  - Verify VERTAAUX_API_BASE is correct",
+                "  - Try: vertaa doctor",
+            ].join("\n");
+        case "auth":
+            return [
+                "Authentication required for AI commands.",
+                "",
+                "  Run: vertaa login",
+                "  Or set: VERTAAUX_API_KEY=<key>",
+            ].join("\n");
+        case "invalid_response":
+            return [
+                "Received unexpected response from AI service.",
+                "",
+                "  This is likely a temporary issue. Try again in a few moments.",
+            ].join("\n");
+        case "rate_limit":
+            return [
+                "Rate limit exceeded.",
+                "",
+                "  Wait a few seconds and try again.",
+            ].join("\n");
+        case "server_error":
+            return [
+                "VertaaUX API returned a server error.",
+                "",
+                "  This is usually temporary. Try again in a moment.",
+            ].join("\n");
+        case "unknown":
+            return [
+                `An unexpected error occurred during ${command}.`,
+                "",
+                "  Try: vertaa doctor",
+                "  If this persists, file an issue.",
+            ].join("\n");
+    }
+}
+// ---------------------------------------------------------------------------
+// Handler
+// ---------------------------------------------------------------------------
+/**
+ * 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 function handleAiCommandError(error, command, spinner) {
+    const kind = classifyAiError(error);
+    const message = formatAiError(kind, command);
+    failSpinner(spinner, `${command} failed`);
+    console.error(message);
+    process.exit(ExitCode.ERROR);
+}

package/dist/utils/detect-env.d.ts

@@ -29,13 +29,11 @@ export declare function isPiped(): boolean;
 /**
  * Determine if colors should be used in output.
  *
- * Priority:
- * 1. NO_COLOR env var (disable)
- * 2. FORCE_COLOR env var (enable)
- * 3. TTY detection
- * 4. CI environment (usually disable)
+ * Delegates to @vertaaux/tui's isColorEnabled() which is set
+ * by the CLI's preAction hook based on --color/--no-color flags
+ * and environment detection.
  */
-export declare function shouldUseColor(): boolean;
+export { isColorEnabled as shouldUseColor } from "@vertaaux/tui";
 /**
  * Detect the appropriate output format based on environment and explicit override.
  *
@@ -53,7 +51,7 @@ export declare function shouldUseColor(): boolean;
 export declare function detectOutputFormat(explicit?: string): OutputFormat;
 /**
  * Get terminal width for formatting.
- * Falls back to 80 columns if not detectable.
+ * Delegates to @vertaaux/tui (reads from stderr where UI renders).
  */
-export declare function getTerminalWidth(): number;
+export { getTerminalWidth } from "@vertaaux/tui";
 //# sourceMappingURL=detect-env.d.ts.map

package/dist/utils/detect-env.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"detect-env.d.ts","sourceRoot":"","sources":["../../src/utils/detect-env.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,GAAG,MAAM,GAAG,OAAO,CAAC;AAEzE;;;GAGG;AACH,wBAAgB,IAAI,IAAI,OAAO,CAY9B;AAED;;GAEG;AACH,wBAAgB,eAAe,IAAI,OAAO,CAEzC;AAED;;GAEG;AACH,wBAAgB,UAAU,IAAI,OAAO,CAEpC;AAED;;GAEG;AACH,wBAAgB,KAAK,IAAI,OAAO,CAE/B;AAED;;GAEG;AACH,wBAAgB,OAAO,IAAI,OAAO,CAEjC;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,IAAI,OAAO,CAkBxC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,YAAY,CA0BlE;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,CAEzC"}
+{"version":3,"file":"detect-env.d.ts","sourceRoot":"","sources":["../../src/utils/detect-env.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,GAAG,MAAM,GAAG,OAAO,CAAC;AAEzE;;;GAGG;AACH,wBAAgB,IAAI,IAAI,OAAO,CAY9B;AAED;;GAEG;AACH,wBAAgB,eAAe,IAAI,OAAO,CAEzC;AAED;;GAEG;AACH,wBAAgB,UAAU,IAAI,OAAO,CAEpC;AAED;;GAEG;AACH,wBAAgB,KAAK,IAAI,OAAO,CAE/B;AAED;;GAEG;AACH,wBAAgB,OAAO,IAAI,OAAO,CAEjC;AAED;;;;;;GAMG;AACH,OAAO,EAAE,cAAc,IAAI,cAAc,EAAE,MAAM,eAAe,CAAC;AAEjE;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,YAAY,CA0BlE;AAED;;;GAGG;AACH,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC"}

package/dist/utils/detect-env.js

@@ -46,28 +46,11 @@ export function isPiped() {
 /**
  * Determine if colors should be used in output.
  *
- * Priority:
- * 1. NO_COLOR env var (disable)
- * 2. FORCE_COLOR env var (enable)
- * 3. TTY detection
- * 4. CI environment (usually disable)
+ * Delegates to @vertaaux/tui's isColorEnabled() which is set
+ * by the CLI's preAction hook based on --color/--no-color flags
+ * and environment detection.
  */
-export function shouldUseColor() {
-    // NO_COLOR takes highest priority (https://no-color.org/)
-    if (process.env.NO_COLOR !== undefined) {
-        return false;
-    }
-    // FORCE_COLOR overrides TTY detection
-    if (process.env.FORCE_COLOR !== undefined) {
-        return true;
-    }
-    // No color in CI by default
-    if (isCI()) {
-        return false;
-    }
-    // Use color if interactive TTY
-    return isTTY();
-}
+export { isColorEnabled as shouldUseColor } from "@vertaaux/tui";
 /**
  * Detect the appropriate output format based on environment and explicit override.
  *
@@ -108,8 +91,6 @@ export function detectOutputFormat(explicit) {
 }
 /**
  * Get terminal width for formatting.
- * Falls back to 80 columns if not detectable.
+ * Delegates to @vertaaux/tui (reads from stderr where UI renders).
  */
-export function getTerminalWidth() {
-    return process.stdout.columns || 80;
-}
+export { getTerminalWidth } from "@vertaaux/tui";

package/dist/utils/stdin.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Universal stdin reader for CLI commands.
+ *
+ * Detects piped input vs TTY, reads JSON or plaintext from stdin,
+ * and provides a consistent interface for all commands that accept
+ * piped data (explain, triage, fix-plan, patch-review, etc.).
+ */
+/**
+ * Result of reading from stdin.
+ */
+export interface StdinResult {
+    /** Raw string content from stdin */
+    raw: string;
+    /** Parsed JSON if input was valid JSON, otherwise null */
+    json: unknown | null;
+    /** Whether the input was valid JSON */
+    isJson: boolean;
+}
+/**
+ * Check if stdin has piped data available.
+ */
+export declare function hasPipedInput(): boolean;
+/**
+ * Read all available data from stdin.
+ *
+ * Only reads when stdin is piped (not a TTY). Returns null if
+ * stdin is a TTY (interactive terminal).
+ *
+ * @returns Parsed stdin result, or null if no piped input
+ */
+export declare function readStdin(): Promise<StdinResult | null>;
+/**
+ * Read JSON from stdin, a file path, or return null.
+ *
+ * Provides the common pattern used by AI commands:
+ * 1. Check --file flag → read file
+ * 2. Check stdin pipe → read piped JSON
+ * 3. Return null (caller should check --job or show error)
+ *
+ * @param filePath - Optional file path from --file flag
+ * @returns Parsed JSON object, or null if no input found
+ */
+export declare function readJsonInput(filePath?: string): Promise<unknown | null>;
+/**
+ * Read plaintext from stdin (for diffs, code, etc.).
+ *
+ * @returns Raw text content, or null if no piped input
+ */
+export declare function readTextInput(): Promise<string | null>;
+//# sourceMappingURL=stdin.d.ts.map

package/dist/utils/stdin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stdin.d.ts","sourceRoot":"","sources":["../../src/utils/stdin.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,oCAAoC;IACpC,GAAG,EAAE,MAAM,CAAC;IACZ,0DAA0D;IAC1D,IAAI,EAAE,OAAO,GAAG,IAAI,CAAC;IACrB,uCAAuC;IACvC,MAAM,EAAE,OAAO,CAAC;CACjB;AAED;;GAEG;AACH,wBAAgB,aAAa,IAAI,OAAO,CAEvC;AAED;;;;;;;GAOG;AACH,wBAAsB,SAAS,IAAI,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CA2B7D;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,aAAa,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CA+B9E;AAED;;;;GAIG;AACH,wBAAsB,aAAa,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAG5D"}