@vertaaux/cli 0.2.0

package/dist/templates/jenkins.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Jenkins pipeline template generator for VertaaUX.
+ *
+ * Generates Jenkinsfile with Warnings NG plugin integration:
+ * - Checkstyle format output for Warnings NG parsing
+ * - recordIssues step for quality gate enforcement
+ *
+ * Requires Jenkins Warnings NG Plugin:
+ * @see https://plugins.jenkins.io/warnings-ng/
+ */
+export interface JenkinsOptions {
+    /** URL to audit (optional, can be set in config) */
+    auditUrl?: string;
+    /** Severity threshold for CI failure */
+    failOn?: "error" | "warning" | "info" | "none";
+    /** Minimum score threshold (0 = disabled) */
+    threshold?: number;
+}
+/**
+ * Generate Jenkinsfile template for VertaaUX integration.
+ *
+ * @param options - Configuration options
+ * @returns Groovy Jenkinsfile content
+ */
+export declare function generateJenkinsTemplate(options?: JenkinsOptions): string;
+//# sourceMappingURL=jenkins.d.ts.map

package/dist/templates/jenkins.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jenkins.d.ts","sourceRoot":"","sources":["../../src/templates/jenkins.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,MAAM,WAAW,cAAc;IAC7B,oDAAoD;IACpD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,wCAAwC;IACxC,MAAM,CAAC,EAAE,OAAO,GAAG,SAAS,GAAG,MAAM,GAAG,MAAM,CAAC;IAC/C,6CAA6C;IAC7C,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,GAAE,cAAmB,GAAG,MAAM,CAgG5E"}

package/dist/templates/jenkins.js

@@ -0,0 +1,110 @@
+/**
+ * Jenkins pipeline template generator for VertaaUX.
+ *
+ * Generates Jenkinsfile with Warnings NG plugin integration:
+ * - Checkstyle format output for Warnings NG parsing
+ * - recordIssues step for quality gate enforcement
+ *
+ * Requires Jenkins Warnings NG Plugin:
+ * @see https://plugins.jenkins.io/warnings-ng/
+ */
+/**
+ * Generate Jenkinsfile template for VertaaUX integration.
+ *
+ * @param options - Configuration options
+ * @returns Groovy Jenkinsfile content
+ */
+export function generateJenkinsTemplate(options = {}) {
+    const { auditUrl, failOn = "error", threshold } = options;
+    // Build audit command with options
+    const auditArgs = [];
+    if (auditUrl) {
+        auditArgs.push(`--url "${auditUrl}"`);
+    }
+    if (failOn !== "none") {
+        auditArgs.push(`--fail-on ${failOn}`);
+    }
+    if (threshold && threshold > 0) {
+        auditArgs.push(`--threshold ${threshold}`);
+    }
+    const auditSuffix = auditArgs.length > 0 ? ` ${auditArgs.join(" ")}` : "";
+    return `// VertaaUX Accessibility & UX Audit
+// https://vertaaux.ai
+//
+// Jenkinsfile with Warnings NG plugin integration.
+// Requires:
+//   - NodeJS 20 tool configured in Jenkins Global Tool Configuration
+//   - Warnings NG plugin installed (https://plugins.jenkins.io/warnings-ng/)
+//   - VERTAAUX_API_KEY credential configured in Jenkins
+
+pipeline {
+    agent any
+
+    tools {
+        nodejs 'NodeJS 20'
+    }
+
+    environment {
+        // Load API key from Jenkins credentials
+        VERTAAUX_API_KEY = credentials('vertaaux-api-key')
+    }
+
+    stages {
+        stage('Setup') {
+            steps {
+                sh 'npm install -g @vertaaux/cli'
+            }
+        }
+
+        stage('Audit') {
+            steps {
+                // Generate checkstyle format for Warnings NG plugin
+                sh '''
+                    vertaa audit \\
+                        --format checkstyle \\
+                        --output vertaaux-results.xml${auditSuffix}
+                '''
+
+                // Generate HTML report for archive
+                sh '''
+                    vertaa audit \\
+                        --format html \\
+                        --output vertaaux-report.html${auditSuffix}
+                '''
+            }
+        }
+    }
+
+    post {
+        always {
+            // Parse results with Warnings NG plugin
+            // Uses checkStyle parser which understands checkstyle XML format
+            recordIssues(
+                tools: [checkStyle(pattern: 'vertaaux-results.xml', id: 'vertaaux', name: 'VertaaUX')],
+                qualityGates: [
+                    [threshold: 1, type: 'NEW', criticality: 'FAILURE']
+                ],
+                // Fail build if new issues found
+                failOnError: true
+            )
+
+            // Archive HTML report
+            archiveArtifacts(
+                artifacts: 'vertaaux-report.html',
+                allowEmptyArchive: true
+            )
+
+            // Clean up generated files
+            cleanWs(
+                cleanWhenNotBuilt: false,
+                deleteDirs: true,
+                patterns: [
+                    [pattern: 'vertaaux-results.xml', type: 'INCLUDE'],
+                    [pattern: 'vertaaux-report.html', type: 'INCLUDE']
+                ]
+            )
+        }
+    }
+}
+`;
+}

package/dist/ui/banner.d.ts

@@ -0,0 +1,31 @@
+/**
+ * V-mark ASCII banner for VertaaUX CLI.
+ *
+ * Displays a subtle gradient from lime to teal/cyan.
+ * Can be suppressed via --quiet, --no-banner, or non-TTY environments.
+ */
+export interface BannerOptions {
+    /** CLI version to display */
+    version: string;
+    /** Whether --quiet or -q was passed */
+    quiet?: boolean;
+    /** Whether --no-banner was passed */
+    noBanner?: boolean;
+}
+/**
+ * Show the V-mark banner with version and working directory.
+ *
+ * Banner is suppressed if:
+ * - --quiet or -q flag is set
+ * - --no-banner flag is set
+ * - Not running in a TTY (e.g., piped output)
+ *
+ * @param options - Banner display options
+ */
+export declare function showBanner(options: BannerOptions): void;
+/**
+ * Get version from package.json.
+ * Falls back to "0.0.0" if unable to read.
+ */
+export declare function getVersion(): string;
+//# sourceMappingURL=banner.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"banner.d.ts","sourceRoot":"","sources":["../../src/ui/banner.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAwCH,MAAM,WAAW,aAAa;IAC5B,6BAA6B;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,uCAAuC;IACvC,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,qCAAqC;IACrC,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,aAAa,GAAG,IAAI,CA0BvD;AAED;;;GAGG;AACH,wBAAgB,UAAU,IAAI,MAAM,CAOnC"}

package/dist/ui/banner.js

@@ -0,0 +1,84 @@
+/**
+ * V-mark ASCII banner for VertaaUX CLI.
+ *
+ * Displays a subtle gradient from lime to teal/cyan.
+ * Can be suppressed via --quiet, --no-banner, or non-TTY environments.
+ */
+import chalk from "chalk";
+import { createRequire } from "module";
+import { isTTY, shouldUseColor } from "../utils/detect-env.js";
+// For JSON imports in ESM
+const require = createRequire(import.meta.url);
+// V-mark ASCII art (3 lines)
+const V_MARK = [" \u2588\u2588\u2557   \u2588\u2588\u2557", " \u255a\u2588\u2588\u2557 \u2588\u2588\u2554\u255d", "  \u255a\u2588\u2588\u2588\u2588\u2554\u255d"];
+// Gradient colors: lime -> teal/cyan
+const GRADIENT_COLORS = [
+    "#78FFB4", // Lime
+    "#6BEEBD", // Light teal
+    "#5EDDC6", // Teal
+    "#51CCCE", // Cyan-ish teal
+];
+/**
+ * Apply gradient to text by coloring each character.
+ */
+function applyGradient(text, colors) {
+    const colorCount = colors.length;
+    let result = "";
+    let colorIndex = 0;
+    for (const char of text) {
+        if (char !== " ") {
+            result += chalk.hex(colors[colorIndex % colorCount])(char);
+            colorIndex++;
+        }
+        else {
+            result += char;
+        }
+    }
+    return result;
+}
+/**
+ * Show the V-mark banner with version and working directory.
+ *
+ * Banner is suppressed if:
+ * - --quiet or -q flag is set
+ * - --no-banner flag is set
+ * - Not running in a TTY (e.g., piped output)
+ *
+ * @param options - Banner display options
+ */
+export function showBanner(options) {
+    const { version, quiet = false, noBanner = false } = options;
+    // Skip banner in non-interactive or suppressed modes
+    if (quiet || noBanner || !isTTY()) {
+        return;
+    }
+    const useColor = shouldUseColor();
+    const cwd = process.cwd();
+    // Build banner lines
+    const lines = useColor
+        ? [
+            `${applyGradient(V_MARK[0], GRADIENT_COLORS)}  ${chalk.bold("VertaaUX")} v${version}`,
+            `${applyGradient(V_MARK[1], GRADIENT_COLORS)}  ${chalk.dim(cwd)}`,
+            `${applyGradient(V_MARK[2], GRADIENT_COLORS)}`,
+        ]
+        : [
+            `${V_MARK[0]}  VertaaUX v${version}`,
+            `${V_MARK[1]}  ${cwd}`,
+            `${V_MARK[2]}`,
+        ];
+    // Write to stderr to avoid mixing with command output
+    process.stderr.write(lines.join("\n") + "\n\n");
+}
+/**
+ * Get version from package.json.
+ * Falls back to "0.0.0" if unable to read.
+ */
+export function getVersion() {
+    try {
+        const pkg = require("../../package.json");
+        return pkg.version || "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+}

package/dist/ui/diagnostics.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Branded error formatting for VertaaUX CLI.
+ *
+ * Renders box-drawn error frames with brand colors in TTY mode,
+ * and structured plain text in non-TTY/CI/NO_COLOR environments.
+ *
+ * Integrates with Commander's configureOutput({ outputError }) hook
+ * to intercept and restyle all validation and argument errors.
+ */
+export interface ValidationErrorOptions {
+    flag: string;
+    value: string;
+    message: string;
+    hint?: string;
+    suggestion?: string;
+    validValues?: string[];
+    moreIssues?: number;
+}
+/**
+ * Format a validation error with branded styling.
+ *
+ * Rich mode (TTY + color): Box-drawn frame with Unicode chars, brand colors.
+ * Plain mode (non-TTY/NO_COLOR/CI): Structured indented text, no decorations.
+ */
+export declare function formatValidationError(opts: ValidationErrorOptions): string;
+/**
+ * Parse and reformat Commander error messages with branded styling.
+ *
+ * Commander passes raw error strings to configureOutput({ outputError }).
+ * This function parses them to extract flag/value information and applies
+ * branded formatting.
+ *
+ * InvalidArgumentError pattern:
+ *   "error: option '--flag <arg>' argument 'value' is invalid. Detail"
+ *
+ * Other Commander errors (missing required, etc.) get branded prefix.
+ */
+export declare function formatCommanderError(rawMessage: string): string;
+//# sourceMappingURL=diagnostics.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.d.ts","sourceRoot":"","sources":["../../src/ui/diagnostics.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAoCH,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,sBAAsB,GAAG,MAAM,CAK1E;AA8ED;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CA+C/D"}

package/dist/ui/diagnostics.js

@@ -0,0 +1,153 @@
+/**
+ * Branded error formatting for VertaaUX CLI.
+ *
+ * Renders box-drawn error frames with brand colors in TTY mode,
+ * and structured plain text in non-TTY/CI/NO_COLOR environments.
+ *
+ * Integrates with Commander's configureOutput({ outputError }) hook
+ * to intercept and restyle all validation and argument errors.
+ */
+import chalk from "chalk";
+import { shouldUseColor, isTTY, getTerminalWidth, } from "../utils/detect-env.js";
+// ---------------------------------------------------------------------------
+// Brand colors (matching banner.ts gradient)
+// ---------------------------------------------------------------------------
+const BRAND_ACCENT = "#78FFB4"; // Lime
+const ERROR_COLOR = "#FF6B6B"; // Red
+const HINT_COLOR = "#78FFB4"; // Brand lime for hints/suggestions
+// ---------------------------------------------------------------------------
+// Terminal capability detection
+// ---------------------------------------------------------------------------
+/**
+ * Determine if box-drawing characters and colors can be used.
+ * Returns false for dumb terminals, NO_COLOR, non-TTY, and CI.
+ */
+function canUseBoxDrawing() {
+    if (process.env.TERM === "dumb")
+        return false;
+    if (!shouldUseColor())
+        return false;
+    if (!isTTY())
+        return false;
+    return true;
+}
+/**
+ * Format a validation error with branded styling.
+ *
+ * Rich mode (TTY + color): Box-drawn frame with Unicode chars, brand colors.
+ * Plain mode (non-TTY/NO_COLOR/CI): Structured indented text, no decorations.
+ */
+export function formatValidationError(opts) {
+    if (canUseBoxDrawing()) {
+        return boxDrawnError(opts);
+    }
+    return plainTextError(opts);
+}
+/**
+ * Rich box-drawn error frame for TTY terminals with color support.
+ */
+function boxDrawnError(opts) {
+    const width = Math.min(getTerminalWidth(), 72);
+    const prefix = chalk.hex(BRAND_ACCENT).bold("vertaa");
+    const border = chalk.dim("  " + "\u2500".repeat(width - 4));
+    const pipe = chalk.dim("  \u2502");
+    const lines = [
+        `${prefix} ${chalk.hex(ERROR_COLOR).bold("error")}: ${opts.message}`,
+        border,
+        `${pipe} ${chalk.dim("flag:")} --${opts.flag}`,
+        `${pipe} ${chalk.dim("value:")} ${chalk.yellow(opts.value)}`,
+    ];
+    if (opts.suggestion) {
+        lines.push(pipe);
+        lines.push(`${pipe} ${chalk.hex(HINT_COLOR)("hint:")} Did you mean "${opts.suggestion}"?`);
+    }
+    if (opts.validValues && opts.validValues.length > 0) {
+        lines.push(`${pipe} ${chalk.dim("valid:")} ${chalk.dim(opts.validValues.join(", "))}`);
+    }
+    if (opts.hint) {
+        lines.push(pipe);
+        lines.push(`${pipe} ${chalk.dim(opts.hint)}`);
+    }
+    lines.push(border);
+    if (opts.moreIssues && opts.moreIssues > 0) {
+        lines.push(chalk.dim(`  ...and ${opts.moreIssues} more issues`));
+    }
+    return lines.join("\n");
+}
+/**
+ * Plain text error for non-TTY, NO_COLOR, CI, or TERM=dumb environments.
+ */
+function plainTextError(opts) {
+    const lines = [
+        `error: ${opts.message}`,
+        `  flag: --${opts.flag}`,
+        `  value: ${opts.value}`,
+    ];
+    if (opts.suggestion) {
+        lines.push(`  hint: Did you mean "${opts.suggestion}"?`);
+    }
+    if (opts.validValues && opts.validValues.length > 0) {
+        lines.push(`  valid: ${opts.validValues.join(", ")}`);
+    }
+    if (opts.hint) {
+        lines.push(`  ${opts.hint}`);
+    }
+    if (opts.moreIssues && opts.moreIssues > 0) {
+        lines.push(`  ...and ${opts.moreIssues} more issues`);
+    }
+    return lines.join("\n");
+}
+// ---------------------------------------------------------------------------
+// Commander error formatting
+// ---------------------------------------------------------------------------
+/**
+ * Parse and reformat Commander error messages with branded styling.
+ *
+ * Commander passes raw error strings to configureOutput({ outputError }).
+ * This function parses them to extract flag/value information and applies
+ * branded formatting.
+ *
+ * InvalidArgumentError pattern:
+ *   "error: option '--flag <arg>' argument 'value' is invalid. Detail"
+ *
+ * Other Commander errors (missing required, etc.) get branded prefix.
+ */
+export function formatCommanderError(rawMessage) {
+    // Strip leading "error: " prefix that Commander adds
+    const msg = rawMessage.replace(/^error:\s*/i, "").trim();
+    // Pattern: option '--flag <arg>' argument 'value' is invalid. Detail
+    const invalidArgMatch = msg.match(/option\s+'(--[\w-]+)(?:\s+<[^>]+>)?'\s+argument\s+'([^']+)'\s+is invalid\.\s*(.*)/i);
+    if (invalidArgMatch) {
+        const [, flag, value, detail] = invalidArgMatch;
+        const flagName = flag.replace(/^--/, "");
+        // Try to extract suggestion from the detail (e.g., 'Did you mean "deep"?')
+        const suggestionMatch = detail.match(/Did you mean "([^"]+)"/);
+        const suggestion = suggestionMatch ? suggestionMatch[1] : undefined;
+        // Try to extract valid values from the detail
+        const validValuesMatch = detail.match(/Valid values?:\s*(.+)/i);
+        const validValues = validValuesMatch
+            ? validValuesMatch[1].split(",").map((v) => v.trim())
+            : undefined;
+        return formatValidationError({
+            flag: flagName,
+            value,
+            message: detail || `invalid argument for --${flagName}`,
+            suggestion,
+            validValues,
+            hint: "Run vertaa <command> --help for all options",
+        });
+    }
+    // For other Commander errors: branded prefix with help hint
+    if (canUseBoxDrawing()) {
+        const prefix = chalk.hex(BRAND_ACCENT).bold("vertaa");
+        const errorLabel = chalk.hex(ERROR_COLOR).bold("error");
+        return [
+            `${prefix} ${errorLabel}: ${msg}`,
+            chalk.dim("  Run vertaa <command> --help for all options"),
+        ].join("\n");
+    }
+    return [
+        `vertaa error: ${msg}`,
+        "  Run vertaa <command> --help for all options",
+    ].join("\n");
+}

package/dist/ui/spinner.d.ts

@@ -0,0 +1,61 @@
+/**
+ * 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.
+ */
+import { type Ora } from "ora";
+export interface SpinnerOptions {
+    /** Initial text to display */
+    text: string;
+    /** Color for the spinner (default: brand lime) */
+    color?: string;
+}
+/**
+ * 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 declare function createSpinner(text: string): Ora;
+/**
+ * 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 declare function updateSpinner(spinner: Ora, text: string, current?: number, total?: number): void;
+/**
+ * Complete spinner with success state.
+ *
+ * @param spinner - The spinner instance
+ * @param text - Success message to display
+ */
+export declare function succeedSpinner(spinner: Ora, text: string): void;
+/**
+ * Complete spinner with failure state.
+ *
+ * @param spinner - The spinner instance
+ * @param text - Failure message to display
+ */
+export declare function failSpinner(spinner: Ora, text: string): void;
+/**
+ * Complete spinner with warning state.
+ *
+ * @param spinner - The spinner instance
+ * @param text - Warning message to display
+ */
+export declare function warnSpinner(spinner: Ora, text: string): void;
+/**
+ * Complete spinner with info state.
+ *
+ * @param spinner - The spinner instance
+ * @param text - Info message to display
+ */
+export declare function infoSpinner(spinner: Ora, text: string): void;
+//# sourceMappingURL=spinner.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"spinner.d.ts","sourceRoot":"","sources":["../../src/ui/spinner.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAY,EAAE,KAAK,GAAG,EAAE,MAAM,KAAK,CAAC;AAapC,MAAM,WAAW,cAAc;IAC7B,8BAA8B;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,kDAAkD;IAClD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,GAAG,CAiB/C;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,GAAG,EACZ,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,MAAM,EAChB,KAAK,CAAC,EAAE,MAAM,GACb,IAAI,CAcN;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAE/D;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAE5D;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAE5D;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAE5D"}

package/dist/ui/spinner.js

@@ -0,0 +1,101 @@
+/**
+ * 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.
+ */
+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";
+/**
+ * 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;
+}
+/**
+ * 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}`;
+    }
+    else if (current !== undefined) {
+        const progress = shouldUseColor()
+            ? chalk.dim(`(${current})`)
+            : `(${current})`;
+        spinner.text = `${text} ${progress}`;
+    }
+    else {
+        spinner.text = 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);
+}
+/**
+ * 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);
+}
+/**
+ * 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);
+}
+/**
+ * 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);
+}

package/dist/ui/table.d.ts

@@ -0,0 +1,63 @@
+/**
+ * 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.
+ */
+export interface Issue {
+    id?: string;
+    severity?: string;
+    category?: string;
+    description?: string;
+    title?: string;
+    selector?: string;
+    wcag_reference?: string;
+}
+export interface FormatTableOptions {
+    /** Maximum width for description column */
+    maxDescriptionWidth?: number;
+    /** Maximum width for selector column */
+    maxSelectorWidth?: number;
+    /** Whether to show the selector column */
+    showSelector?: boolean;
+    /** Whether to show the category column */
+    showCategory?: boolean;
+}
+/**
+ * Group issues by severity.
+ */
+export declare function groupBySeverity(issues: Issue[]): Map<string, Issue[]>;
+/**
+ * Group issues by category.
+ */
+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