@vertaaux/cli 0.2.3 → 0.3.0

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

package/dist/utils/stdin.js

@@ -0,0 +1,93 @@
+/**
+ * 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.).
+ */
+/**
+ * Check if stdin has piped data available.
+ */
+export function hasPipedInput() {
+    return !process.stdin.isTTY;
+}
+/**
+ * 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 async function readStdin() {
+    if (process.stdin.isTTY) {
+        return null;
+    }
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(chunk);
+    }
+    const raw = Buffer.concat(chunks).toString("utf-8").trim();
+    if (!raw) {
+        return null;
+    }
+    let json = null;
+    let isJson = false;
+    try {
+        json = JSON.parse(raw);
+        isJson = true;
+    }
+    catch {
+        // Not JSON — that's fine, could be plaintext (e.g., a diff)
+    }
+    return { raw, json, isJson };
+}
+/**
+ * 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 async function readJsonInput(filePath) {
+    // Priority 1: explicit file path
+    if (filePath) {
+        const fs = await import("fs");
+        const path = await import("path");
+        const resolved = path.resolve(process.cwd(), filePath);
+        if (!fs.existsSync(resolved)) {
+            throw new Error(`Input file not found: ${filePath}`);
+        }
+        const content = fs.readFileSync(resolved, "utf-8");
+        try {
+            return JSON.parse(content);
+        }
+        catch {
+            throw new Error(`Invalid JSON in file: ${filePath}`);
+        }
+    }
+    // Priority 2: piped stdin
+    const stdin = await readStdin();
+    if (stdin) {
+        if (!stdin.isJson) {
+            throw new Error("Could not parse input as JSON. If piping from vertaa, use --json flag:\n" +
+                "  vertaa audit https://example.com --json | vertaa explain");
+        }
+        return stdin.json;
+    }
+    // No input found
+    return null;
+}
+/**
+ * Read plaintext from stdin (for diffs, code, etc.).
+ *
+ * @returns Raw text content, or null if no piped input
+ */
+export async function readTextInput() {
+    const stdin = await readStdin();
+    return stdin?.raw ?? null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vertaaux/cli",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "description": "Run automated UX audits, accessibility checks, and performance analysis from the terminal or CI pipelines. Supports policy gating, SARIF output, and multi-page crawling. See https://github.com/PetriLahdelma/vertaa/tree/main/cli#readme for full docs.",
   "type": "module",
   "main": "dist/index.js",
@@ -40,19 +40,21 @@
     "dev": "tsc -w",
     "start": "node dist/index.js",
     "prepublishOnly": "npm run build && node scripts/verify-package.mjs",
-    "test": "vitest run --config vitest.config.ts"
+    "test": "vitest run --config vitest.config.ts --exclude tests/e2e/**/*.test.ts",
+    "test:e2e": "vitest run --config vitest.config.ts tests/e2e/cli-contract.test.ts",
+    "test:e2e:package": "vitest run --config vitest.config.ts tests/e2e/package-install.test.ts",
+    "test:e2e:ui": "vitest --ui --config vitest.config.ts tests/e2e/cli-contract.test.ts"
   },
   "dependencies": {
     "@inquirer/prompts": "^8.2.0",
+    "@vertaaux/tui": "file:../packages/tui",
     "ajv": "^8.17.1",
     "ajv-formats": "^3.0.1",
     "chalk": "^5.6.2",
-    "cli-table3": "^0.6.5",
     "commander": "^14.0.2",
     "cosmiconfig": "^9.0.0",
     "dotenv": "^17.2.3",
     "minimatch": "^10.1.1",
-    "ora": "^9.1.0",
     "semver": "^7.7.3",
     "yaml": "^2.8.2"
   },
@@ -60,6 +62,8 @@
     "@types/minimatch": "^5.1.2",
     "@types/node": "^20.11.25",
     "@types/semver": "^7.7.1",
-    "typescript": "^5.6.3"
+    "@vitest/ui": "^4.0.18",
+    "typescript": "^5.6.3",
+    "vitest": "^4.0.15"
   }
 }