@vertaaux/cli 0.2.0

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

@@ -0,0 +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"}

package/dist/ui/table.js

@@ -0,0 +1,236 @@
+/**
+ * Table formatting utilities for CLI output.
+ *
+ * Uses cli-table3 for clean table 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);
+}
+/**
+ * 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;
+        return orderA - orderB;
+    });
+}
+/**
+ * Group issues by severity.
+ */
+export function groupBySeverity(issues) {
+    const groups = new Map();
+    for (const issue of issues) {
+        const severity = issue.severity?.toLowerCase() || "info";
+        const group = groups.get(severity) || [];
+        group.push(issue);
+        groups.set(severity, group);
+    }
+    return groups;
+}
+/**
+ * Group issues by category.
+ */
+export function groupByCategory(issues) {
+    const groups = new Map();
+    for (const issue of issues) {
+        const category = issue.category || "Uncategorized";
+        const group = groups.get(category) || [];
+        group.push(issue);
+        groups.set(category, 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.")
+            : "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];
+    if (showCategory) {
+        header.push("Category");
+        colWidths.push(15);
+    }
+    if (showSelector) {
+        header.push("Selector");
+        colWidths.push(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();
+}
+/**
+ * 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.")
+            : "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"] : [],
+        },
+    });
+    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();
+}
+/**
+ * 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 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];
+        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));
+            }
+            else {
+                parts.push(text);
+            }
+        }
+    }
+    if (!parts.length) {
+        return useColor ? chalk.green("No issues") : "No issues";
+    }
+    return parts.join(", ") + " issues";
+}

package/dist/utils/client.d.ts

@@ -0,0 +1,82 @@
+/**
+ * API client utilities for VertaaUX CLI.
+ *
+ * Provides helper functions for making authenticated API requests.
+ * Handles API key resolution and error formatting.
+ */
+import type { VertaauxConfig } from "../config/schema.js";
+/**
+ * Resolve the API base URL from various sources.
+ *
+ * Priority: flag > env > config > default
+ *
+ * @param flagBase - Base URL from command line flag
+ * @param configBase - Base URL from config file
+ * @returns Resolved API base URL (without trailing slash)
+ */
+export declare function resolveApiBase(flagBase?: string, configBase?: string): string;
+/**
+ * Get API key from environment or config.
+ *
+ * @param configApiKey - API key from config file
+ * @returns API key string
+ * @throws Error if no API key is available
+ */
+export declare function getApiKey(configApiKey?: string): string;
+/**
+ * Check if API key is available without throwing.
+ *
+ * @param config - Optional config with apiKey
+ * @returns true if API key is available
+ */
+export declare function hasApiKey(config?: VertaauxConfig): boolean;
+export interface ApiRequestOptions {
+    method: "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
+    body?: unknown;
+    headers?: Record<string, string>;
+}
+/**
+ * Make an authenticated API request.
+ *
+ * @param base - API base URL
+ * @param path - Request path (e.g., "/audit")
+ * @param options - Request options (method, body, headers)
+ * @param apiKey - API key for authentication
+ * @returns Parsed JSON response
+ * @throws Error on HTTP errors with details
+ */
+export declare function apiRequest<T>(base: string, path: string, options: ApiRequestOptions, apiKey: string): Promise<T>;
+/**
+ * Sleep for a specified duration.
+ *
+ * @param ms - Milliseconds to sleep
+ * @returns Promise that resolves after the duration
+ */
+export declare function sleep(ms: number): Promise<void>;
+export interface AuditResponse {
+    job_id?: string;
+    status?: string;
+    url?: string;
+    mode?: string;
+    progress?: number;
+    created_at?: string;
+    started_at?: string;
+    completed_at?: string;
+    scores?: Record<string, unknown>;
+    issues?: unknown;
+    error?: string;
+}
+/**
+ * Wait for an audit to complete, polling at intervals.
+ *
+ * @param base - API base URL
+ * @param jobId - Audit job ID
+ * @param timeoutMs - Maximum time to wait
+ * @param intervalMs - Poll interval
+ * @param apiKey - API key for authentication
+ * @param onProgress - Optional callback for progress updates
+ * @returns Completed audit response
+ * @throws Error on timeout or failure
+ */
+export declare function waitForAudit(base: string, jobId: string, timeoutMs: number, intervalMs: number, apiKey: string, onProgress?: (progress: number, status: string) => void): Promise<AuditResponse>;
+//# sourceMappingURL=client.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/utils/client.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAI1D;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,CAAC,EAAE,MAAM,EACjB,UAAU,CAAC,EAAE,MAAM,GAClB,MAAM,CAOR;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,CAQvD;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,MAAM,CAAC,EAAE,cAAc,GAAG,OAAO,CAE1D;AAED,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,GAAG,OAAO,CAAC;IACpD,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED;;;;;;;;;GASG;AACH,wBAAsB,UAAU,CAAC,CAAC,EAChC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,iBAAiB,EAC1B,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,CAAC,CAAC,CA+BZ;AAED;;;;;GAKG;AACH,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE/C;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,YAAY,CAChC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,EACd,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,GACtD,OAAO,CAAC,aAAa,CAAC,CA2BxB"}

package/dist/utils/client.js

@@ -0,0 +1,128 @@
+/**
+ * API client utilities for VertaaUX CLI.
+ *
+ * Provides helper functions for making authenticated API requests.
+ * Handles API key resolution and error formatting.
+ */
+const DEFAULT_API_BASE = "https://vertaaux.ai/v1";
+/**
+ * Resolve the API base URL from various sources.
+ *
+ * Priority: flag > env > config > default
+ *
+ * @param flagBase - Base URL from command line flag
+ * @param configBase - Base URL from config file
+ * @returns Resolved API base URL (without trailing slash)
+ */
+export function resolveApiBase(flagBase, configBase) {
+    const raw = flagBase ||
+        process.env.VERTAAUX_API_BASE ||
+        configBase ||
+        DEFAULT_API_BASE;
+    return raw.replace(/\/$/, "");
+}
+/**
+ * Get API key from environment or config.
+ *
+ * @param configApiKey - API key from config file
+ * @returns API key string
+ * @throws Error if no API key is available
+ */
+export function getApiKey(configApiKey) {
+    const key = process.env.VERTAAUX_API_KEY || configApiKey;
+    if (!key) {
+        throw new Error("VERTAAUX_API_KEY is required. Set it via environment variable or config file.");
+    }
+    return key;
+}
+/**
+ * Check if API key is available without throwing.
+ *
+ * @param config - Optional config with apiKey
+ * @returns true if API key is available
+ */
+export function hasApiKey(config) {
+    return Boolean(process.env.VERTAAUX_API_KEY || config?.apiKey);
+}
+/**
+ * Make an authenticated API request.
+ *
+ * @param base - API base URL
+ * @param path - Request path (e.g., "/audit")
+ * @param options - Request options (method, body, headers)
+ * @param apiKey - API key for authentication
+ * @returns Parsed JSON response
+ * @throws Error on HTTP errors with details
+ */
+export async function apiRequest(base, path, options, apiKey) {
+    const url = `${base}${path}`;
+    const res = await fetch(url, {
+        method: options.method,
+        headers: {
+            "Content-Type": "application/json",
+            "X-API-Key": apiKey,
+            ...options.headers,
+        },
+        body: options.body ? JSON.stringify(options.body) : undefined,
+    });
+    if (!res.ok) {
+        let detail = res.statusText;
+        try {
+            const data = (await res.json());
+            detail =
+                (data && (data.error || data.message)) ||
+                    JSON.stringify(data) ||
+                    detail;
+        }
+        catch {
+            try {
+                detail = await res.text();
+            }
+            catch {
+                // ignore
+            }
+        }
+        throw new Error(`HTTP ${res.status}: ${detail}`);
+    }
+    return (await res.json().catch(() => ({})));
+}
+/**
+ * Sleep for a specified duration.
+ *
+ * @param ms - Milliseconds to sleep
+ * @returns Promise that resolves after the duration
+ */
+export function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Wait for an audit to complete, polling at intervals.
+ *
+ * @param base - API base URL
+ * @param jobId - Audit job ID
+ * @param timeoutMs - Maximum time to wait
+ * @param intervalMs - Poll interval
+ * @param apiKey - API key for authentication
+ * @param onProgress - Optional callback for progress updates
+ * @returns Completed audit response
+ * @throws Error on timeout or failure
+ */
+export async function waitForAudit(base, jobId, timeoutMs, intervalMs, apiKey, onProgress) {
+    const start = Date.now();
+    while (true) {
+        const status = await apiRequest(base, `/audit/${jobId}`, { method: "GET" }, apiKey);
+        // Call progress callback if provided
+        if (onProgress && typeof status.progress === "number") {
+            onProgress(status.progress, status.status || "unknown");
+        }
+        if (status.status === "completed")
+            return status;
+        if (status.status === "failed") {
+            throw new Error(status.error || `Audit ${jobId} failed`);
+        }
+        if (Date.now() - start > timeoutMs) {
+            throw new Error(`Timed out waiting for audit ${jobId}`);
+        }
+        await sleep(intervalMs);
+    }
+}

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

@@ -0,0 +1,59 @@
+/**
+ * Environment detection utilities for CLI.
+ *
+ * Auto-detects appropriate output format, color support, and CI environment.
+ * Follows established patterns from ci-info and terminal detection.
+ */
+export type OutputFormat = "json" | "sarif" | "junit" | "html" | "human";
+/**
+ * Detect if running in a CI environment.
+ * Checks for common CI environment variables.
+ */
+export declare function isCI(): boolean;
+/**
+ * Check if running in GitHub Actions.
+ */
+export declare function isGitHubActions(): boolean;
+/**
+ * Check if running in GitLab CI.
+ */
+export declare function isGitLabCI(): boolean;
+/**
+ * Check if running in a TTY (interactive terminal).
+ */
+export declare function isTTY(): boolean;
+/**
+ * Check if output is being piped.
+ */
+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)
+ */
+export declare function shouldUseColor(): boolean;
+/**
+ * Detect the appropriate output format based on environment and explicit override.
+ *
+ * @param explicit - Explicit format override (from --format flag)
+ * @returns The resolved output format
+ *
+ * Priority:
+ * 1. Explicit format (if not "auto")
+ * 2. GitHub Actions -> sarif (CI-specific takes precedence)
+ * 3. GitLab/Jenkins/CircleCI -> junit
+ * 4. Other CI -> json
+ * 5. Piped output (non-CI) -> json
+ * 6. Interactive terminal -> human
+ */
+export declare function detectOutputFormat(explicit?: string): OutputFormat;
+/**
+ * Get terminal width for formatting.
+ * Falls back to 80 columns if not detectable.
+ */
+export declare function getTerminalWidth(): number;
+//# sourceMappingURL=detect-env.d.ts.map

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

@@ -0,0 +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"}

package/dist/utils/detect-env.js

@@ -0,0 +1,115 @@
+/**
+ * Environment detection utilities for CLI.
+ *
+ * Auto-detects appropriate output format, color support, and CI environment.
+ * Follows established patterns from ci-info and terminal detection.
+ */
+/**
+ * Detect if running in a CI environment.
+ * Checks for common CI environment variables.
+ */
+export function isCI() {
+    return Boolean(process.env.CI ||
+        process.env.CONTINUOUS_INTEGRATION ||
+        process.env.BUILD_NUMBER ||
+        process.env.GITHUB_ACTIONS ||
+        process.env.GITLAB_CI ||
+        process.env.CIRCLECI ||
+        process.env.JENKINS_URL ||
+        process.env.TRAVIS ||
+        process.env.BUILDKITE);
+}
+/**
+ * Check if running in GitHub Actions.
+ */
+export function isGitHubActions() {
+    return Boolean(process.env.GITHUB_ACTIONS);
+}
+/**
+ * Check if running in GitLab CI.
+ */
+export function isGitLabCI() {
+    return Boolean(process.env.GITLAB_CI);
+}
+/**
+ * Check if running in a TTY (interactive terminal).
+ */
+export function isTTY() {
+    return Boolean(process.stdout.isTTY);
+}
+/**
+ * Check if output is being piped.
+ */
+export function isPiped() {
+    return !process.stdout.isTTY;
+}
+/**
+ * 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)
+ */
+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();
+}
+/**
+ * Detect the appropriate output format based on environment and explicit override.
+ *
+ * @param explicit - Explicit format override (from --format flag)
+ * @returns The resolved output format
+ *
+ * Priority:
+ * 1. Explicit format (if not "auto")
+ * 2. GitHub Actions -> sarif (CI-specific takes precedence)
+ * 3. GitLab/Jenkins/CircleCI -> junit
+ * 4. Other CI -> json
+ * 5. Piped output (non-CI) -> json
+ * 6. Interactive terminal -> human
+ */
+export function detectOutputFormat(explicit) {
+    // Explicit format takes precedence
+    if (explicit && explicit !== "auto") {
+        return explicit;
+    }
+    // CI environment: default to appropriate format for CI platform
+    // Check CI first because CI outputs are always piped but we want
+    // SARIF for GitHub Actions, JUnit for GitLab/Jenkins
+    if (isCI()) {
+        if (isGitHubActions()) {
+            return "sarif";
+        }
+        if (isGitLabCI() || process.env.JENKINS_URL || process.env.CIRCLECI) {
+            return "junit";
+        }
+        return "json";
+    }
+    // Piped output (non-CI): use JSON for machine parsing
+    if (isPiped()) {
+        return "json";
+    }
+    // Interactive terminal: human-readable
+    return "human";
+}
+/**
+ * Get terminal width for formatting.
+ * Falls back to 80 columns if not detectable.
+ */
+export function getTerminalWidth() {
+    return process.stdout.columns || 80;
+}

package/dist/utils/exit-codes.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Semantic exit codes for CLI commands (CLI-12).
+ *
+ * CI tools depend on exit codes for gating decisions.
+ * These codes allow distinguishing between:
+ * - Success (no issues)
+ * - Issues found (but not necessarily a failure)
+ * - Runtime errors
+ * - Threshold/score failures
+ */
+export declare const ExitCode: {
+    /** Audit passed, no issues above threshold */
+    readonly SUCCESS: 0;
+    /** Issues found at or above specified severity */
+    readonly ISSUES_FOUND: 1;
+    /** Runtime error, invalid input, network failure */
+    readonly ERROR: 2;
+    /** Score below threshold */
+    readonly THRESHOLD_BREACH: 3;
+};
+export type ExitCodeType = (typeof ExitCode)[keyof typeof ExitCode];
+export interface AuditResultForExitCode {
+    error?: unknown;
+    scores?: {
+        overall?: number;
+        [key: string]: unknown;
+    };
+    issues?: Array<{
+        severity?: string;
+        [key: string]: unknown;
+    }>;
+}
+export interface ExitCodeOptions {
+    /** Minimum score threshold (0-100) */
+    threshold?: number;
+    /** Fail if issues at or above this severity */
+    failOn?: "error" | "warning" | "info";
+}
+/**
+ * Determine the appropriate exit code based on audit results and options.
+ *
+ * @param result - The audit result
+ * @param options - Exit code determination options
+ * @returns The semantic exit code
+ */
+export declare function determineExitCode(result: AuditResultForExitCode, options?: ExitCodeOptions): ExitCodeType;
+//# sourceMappingURL=exit-codes.d.ts.map

package/dist/utils/exit-codes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exit-codes.d.ts","sourceRoot":"","sources":["../../src/utils/exit-codes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,eAAO,MAAM,QAAQ;IACnB,8CAA8C;;IAE9C,kDAAkD;;IAElD,oDAAoD;;IAEpD,4BAA4B;;CAEpB,CAAC;AAEX,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,QAAQ,CAAC,CAAC,MAAM,OAAO,QAAQ,CAAC,CAAC;AAiBpE,MAAM,WAAW,sBAAsB;IACrC,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE;QACP,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;KACxB,CAAC;IACF,MAAM,CAAC,EAAE,KAAK,CAAC;QACb,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;KACxB,CAAC,CAAC;CACJ;AAED,MAAM,WAAW,eAAe;IAC9B,sCAAsC;IACtC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,+CAA+C;IAC/C,MAAM,CAAC,EAAE,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;CACvC;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,sBAAsB,EAC9B,OAAO,GAAE,eAAoB,GAC5B,YAAY,CA4Bd"}