@vertaaux/cli 0.3.0 → 0.3.1

package/node_modules/@vertaaux/tui/dist/index.d.ts

@@ -0,0 +1,609 @@
+/**
+ * Raw ANSI escape sequences for terminal control.
+ *
+ * No dependencies — pure string constants and functions.
+ * Used by renderers and primitives for direct terminal manipulation.
+ */
+declare const cursor: {
+    /** Move cursor to row, col (1-indexed) */
+    readonly to: (row: number, col: number) => string;
+    /** Move cursor to top-left */
+    readonly home: "\u001B[H";
+    /** Move cursor up N lines */
+    readonly up: (n?: number) => string;
+    /** Move cursor down N lines */
+    readonly down: (n?: number) => string;
+    /** Move cursor to column N (1-indexed) */
+    readonly column: (n: number) => string;
+    /** Hide cursor */
+    readonly hide: "\u001B[?25l";
+    /** Show cursor */
+    readonly show: "\u001B[?25h";
+    /** Save cursor position */
+    readonly save: "\u001B7";
+    /** Restore cursor position */
+    readonly restore: "\u001B8";
+};
+declare const screen: {
+    /** Clear entire screen */
+    readonly clear: "\u001B[2J";
+    /** Clear from cursor to end of screen */
+    readonly clearDown: "\u001B[J";
+    /** Clear from cursor to end of line */
+    readonly clearLine: "\u001B[K";
+    /** Clear entire line */
+    readonly clearFullLine: "\u001B[2K";
+    /** Enter alternate screen buffer (preserves scrollback) */
+    readonly altEnter: "\u001B[?1049h";
+    /** Exit alternate screen buffer */
+    readonly altExit: "\u001B[?1049l";
+};
+declare const style: {
+    /** Reset all attributes */
+    readonly reset: "\u001B[0m";
+};
+declare const borders: {
+    readonly single: {
+        readonly topLeft: "┌";
+        readonly topRight: "┐";
+        readonly bottomLeft: "└";
+        readonly bottomRight: "┘";
+        readonly horizontal: "─";
+        readonly vertical: "│";
+    };
+    readonly double: {
+        readonly topLeft: "╔";
+        readonly topRight: "╗";
+        readonly bottomLeft: "╚";
+        readonly bottomRight: "╝";
+        readonly horizontal: "═";
+        readonly vertical: "║";
+    };
+    readonly rounded: {
+        readonly topLeft: "╭";
+        readonly topRight: "╮";
+        readonly bottomLeft: "╰";
+        readonly bottomRight: "╯";
+        readonly horizontal: "─";
+        readonly vertical: "│";
+    };
+    readonly heavy: {
+        readonly topLeft: "┏";
+        readonly topRight: "┓";
+        readonly bottomLeft: "┗";
+        readonly bottomRight: "┛";
+        readonly horizontal: "━";
+        readonly vertical: "┃";
+    };
+};
+type BorderStyle = keyof typeof borders;
+/** Common type for any border character set */
+interface BorderChars {
+    readonly topLeft: string;
+    readonly topRight: string;
+    readonly bottomLeft: string;
+    readonly bottomRight: string;
+    readonly horizontal: string;
+    readonly vertical: string;
+}
+/** Strip all ANSI escape sequences from a string */
+declare function stripAnsi(str: string): string;
+/** Get visible character width of a string (excluding ANSI codes) */
+declare function visibleLength(str: string): number;
+/** Pad string to visible width, accounting for ANSI codes */
+declare function padEnd(str: string, width: number): string;
+/** Pad string to visible width from left */
+declare function padStart(str: string, width: number): string;
+/** Center string within width, accounting for ANSI codes */
+declare function center(str: string, width: number): string;
+/** Truncate string to visible width, adding ellipsis */
+declare function truncate(str: string, maxWidth: number): string;
+
+/**
+ * VertaaUX brand theme for terminal output.
+ *
+ * Defines the color palette, severity colors, score gradients,
+ * and semantic tokens used across all TUI primitives.
+ */
+declare const brand: {
+    readonly lime: "#78FFB4";
+    readonly tealLight: "#6BEEBD";
+    readonly teal: "#5EDDC6";
+    readonly cyan: "#51CCCE";
+    readonly dark: "#0A0F1A";
+};
+/** Gradient stops from lime → cyan (for banner, headers, accents) */
+declare const gradient: readonly ["#78FFB4", "#6BEEBD", "#5EDDC6", "#51CCCE"];
+declare const severity: {
+    readonly critical: "#FF6B6B";
+    readonly error: "#FF6B6B";
+    readonly serious: "#FFD93D";
+    readonly warning: "#FFD93D";
+    readonly moderate: "#6BCEFF";
+    readonly minor: "#6BCEFF";
+    readonly info: "#888888";
+};
+type SeverityLevel = keyof typeof severity;
+/** Severity display labels */
+declare const severityLabels: Record<string, string>;
+/** Severity sort order (highest first) */
+declare const severityOrder: Record<string, number>;
+/**
+ * Get hex color for a score value (0-100).
+ */
+declare function scoreColor(score: number): string;
+declare const tokens: {
+    readonly success: "#4ADE80";
+    readonly error: "#F87171";
+    readonly warning: "#FACC15";
+    readonly info: "#6BCEFF";
+    readonly muted: "#6B7280";
+    readonly accent: "#78FFB4";
+};
+/** Set whether color output is enabled (call early, based on detect.ts) */
+declare function setColorEnabled(enabled: boolean): void;
+/** Check if color is currently enabled */
+declare function isColorEnabled(): boolean;
+/** Apply hex color to text (respects color-enabled state) */
+declare function colorize(text: string, hex: string): string;
+/** Apply bold + hex color */
+declare function boldColor(text: string, hex: string): string;
+/** Apply dim styling */
+declare function dim$1(text: string): string;
+/** Apply bold styling */
+declare function bold$1(text: string): string;
+/** Apply gradient across text characters */
+declare function applyGradient(text: string, colors?: readonly string[]): string;
+
+/**
+ * Environment detection for terminal capabilities.
+ *
+ * Standalone implementations (no CLI dependency) that detect
+ * TTY, CI, color support, and terminal dimensions.
+ */
+/** Check if running in a CI environment. */
+declare function isCI(): boolean;
+/** Check if stderr is a TTY (used for UI output). */
+declare function isTTY(): boolean;
+/** Check if stdout is a TTY (used for data output detection). */
+declare function isStdoutTTY(): boolean;
+/** Check if stdin is a TTY (used for keyboard input detection). */
+declare function isStdinTTY(): boolean;
+/**
+ * Determine if colors should be used.
+ *
+ * Priority: NO_COLOR > FORCE_COLOR > CI (off) > TTY detection
+ */
+declare function shouldUseColor(): boolean;
+/** Get terminal width from stderr (where UI renders). Falls back to 80. */
+declare function getTerminalWidth(): number;
+/** Get terminal height from stderr. Falls back to 24. */
+declare function getTerminalHeight(): number;
+/** Check if terminal supports Unicode (not dumb terminal). */
+declare function supportsUnicode(): boolean;
+
+/**
+ * Text styling primitives for terminal output.
+ *
+ * Semantic text functions for headings, labels, badges, and emphasis.
+ * All respect the color-enabled state from theme.ts.
+ */
+/** Render a section heading with brand accent */
+declare function heading(text: string): string;
+/** Render a sub-heading */
+declare function subheading(text: string): string;
+/** Render a label (key in key-value pairs) */
+declare function label(text: string): string;
+/** Render dimmed/muted text */
+declare function dim(text: string): string;
+/** Render bold text */
+declare function bold(text: string): string;
+/** Render a clickable-looking link (underlined cyan) */
+declare function link(text: string): string;
+/** Render severity badge: colored, bold, uppercase label */
+declare function severityBadge(level: string): string;
+/** Render score badge: color-coded number */
+declare function scoreBadge(score: number): string;
+/** Render success text */
+declare function success(text: string): string;
+/** Render error text */
+declare function error(text: string): string;
+/** Render warning text */
+declare function warning(text: string): string;
+/** Render info text */
+declare function info(text: string): string;
+/** Render a key: value pair with styled label */
+declare function keyValue(key: string, value: string): string;
+/** Render a horizontal rule that spans the terminal width */
+declare function hr(width: number, char?: string): string;
+/** Render a status indicator dot */
+declare function statusDot(status: "pass" | "fail" | "warn" | "skip" | "active"): string;
+
+declare const text_bold: typeof bold;
+declare const text_dim: typeof dim;
+declare const text_error: typeof error;
+declare const text_heading: typeof heading;
+declare const text_hr: typeof hr;
+declare const text_info: typeof info;
+declare const text_keyValue: typeof keyValue;
+declare const text_label: typeof label;
+declare const text_link: typeof link;
+declare const text_scoreBadge: typeof scoreBadge;
+declare const text_severityBadge: typeof severityBadge;
+declare const text_statusDot: typeof statusDot;
+declare const text_subheading: typeof subheading;
+declare const text_success: typeof success;
+declare const text_warning: typeof warning;
+declare namespace text {
+  export { text_bold as bold, text_dim as dim, text_error as error, text_heading as heading, text_hr as hr, text_info as info, text_keyValue as keyValue, text_label as label, text_link as link, text_scoreBadge as scoreBadge, text_severityBadge as severityBadge, text_statusDot as statusDot, text_subheading as subheading, text_success as success, text_warning as warning };
+}
+
+/**
+ * Box primitive for bordered terminal output.
+ *
+ * Renders content inside a Unicode box with optional title, subtitle,
+ * padding, and multiple border styles.
+ */
+
+interface BoxOptions {
+    /** Border style: single, double, rounded, heavy, none */
+    border?: BorderStyle | "none";
+    /** Inner padding (number of spaces on each side) */
+    padding?: number;
+    /** Vertical padding (blank lines above/below content) */
+    paddingY?: number;
+    /** Title displayed on the top border */
+    title?: string;
+    /** Subtitle displayed on the bottom border */
+    subtitle?: string;
+    /** Fixed width (defaults to terminal width - 2) */
+    width?: number;
+    /** Border color hex (defaults to brand.teal) */
+    borderColor?: string;
+    /** Title color hex (defaults to brand.lime) */
+    titleColor?: string;
+}
+/**
+ * Render content inside a bordered box.
+ *
+ * @param content - Text content (can be multi-line)
+ * @param opts - Box options
+ * @returns Rendered box string
+ */
+declare function box(content: string, opts?: BoxOptions): string;
+
+/**
+ * Table primitive for terminal output.
+ *
+ * Renders aligned, color-coded tables with auto-width,
+ * group headers, and terminal-width-aware truncation.
+ * No external table library — pure string rendering.
+ */
+interface Column {
+    /** Data key to read from row objects */
+    key: string;
+    /** Column header label */
+    label: string;
+    /** Fixed width (characters). If omitted, auto-calculated. */
+    width?: number;
+    /** Text alignment */
+    align?: "left" | "right" | "center";
+    /** Custom color function for cell values */
+    color?: (value: string) => string;
+}
+interface TableOptions {
+    /** Maximum total width (defaults to terminal width) */
+    maxWidth?: number;
+    /** Show borders between rows */
+    rowBorders?: boolean;
+    /** Group header styling */
+    groupLabel?: string;
+}
+/**
+ * Render a data table from rows and column definitions.
+ */
+declare function renderTable(rows: Record<string, string>[], columns: Column[], opts?: TableOptions): string;
+
+/**
+ * Spinner primitive for terminal progress indication.
+ *
+ * Renders an animated spinner with text to stderr.
+ * Writes ONLY to stderr — never pollutes stdout.
+ */
+interface SpinnerInstance {
+    /** Start the spinner animation */
+    start(): void;
+    /** Stop the spinner and clear the line */
+    stop(): void;
+    /** Update the display text */
+    setText(text: string): void;
+    /** Show phase label alongside text */
+    setPhase(phase: string): void;
+    /** Stop with success indicator */
+    succeed(text: string): void;
+    /** Stop with failure indicator */
+    fail(text: string): void;
+    /** Stop with warning indicator */
+    warn(text: string): void;
+    /** Stop with info indicator */
+    info(text: string): void;
+    /** Whether the spinner is currently running */
+    isRunning: boolean;
+}
+/**
+ * Create a new spinner instance.
+ *
+ * @param text - Initial text to display
+ * @param output - Writable stream (defaults to process.stderr)
+ */
+declare function createSpinner(text: string, output?: NodeJS.WritableStream): SpinnerInstance;
+
+/**
+ * Progress bar primitive for terminal output.
+ *
+ * Single bars and multi-bar stacks with percentage, ETA,
+ * and brand-colored fill. Writes to stderr only.
+ */
+interface ProgressBarOptions {
+    /** Total number of steps */
+    total: number;
+    /** Label displayed before the bar */
+    label?: string;
+    /** Bar width in characters (defaults to auto) */
+    width?: number;
+    /** Color hex for the filled portion */
+    color?: string;
+    /** Writable stream (defaults to stderr) */
+    output?: NodeJS.WritableStream;
+}
+interface ProgressBar {
+    /** Update progress to a new value */
+    update(current: number): void;
+    /** Complete the bar at 100% */
+    complete(message?: string): void;
+    /** Fail the bar with error indicator */
+    fail(message?: string): void;
+    /** Get the current rendered bar string (for embedding in frames) */
+    render(current: number, barWidth?: number): string;
+}
+/**
+ * Create a progress bar.
+ */
+declare function createProgressBar(opts: ProgressBarOptions): ProgressBar;
+interface MultiProgressOptions {
+    /** Writable stream (defaults to stderr) */
+    output?: NodeJS.WritableStream;
+}
+interface MultiProgress {
+    /** Add a named progress bar */
+    add(id: string, opts: Omit<ProgressBarOptions, "output">): void;
+    /** Update a specific bar */
+    update(id: string, current: number): void;
+    /** Mark a bar as complete */
+    complete(id: string): void;
+    /** Render all bars (returns multi-line string for dashboard embedding) */
+    renderAll(): string;
+    /** Write all bars to output (in-place update) */
+    draw(): void;
+    /** Clear all bar lines from terminal */
+    clear(): void;
+}
+/**
+ * Create a multi-progress bar stack.
+ */
+declare function createMultiProgress(opts?: MultiProgressOptions): MultiProgress;
+
+/**
+ * List and tree primitive for terminal output.
+ *
+ * Renders ordered/unordered lists and tree structures
+ * with Unicode connectors and configurable indentation.
+ */
+interface ListOptions {
+    /** Ordered (numbered) or unordered (bullet) */
+    ordered?: boolean;
+    /** Indentation level (for nesting) */
+    indent?: number;
+    /** Bullet character for unordered lists */
+    bullet?: string;
+}
+/**
+ * Render a flat list of items.
+ */
+declare function renderList(items: string[], opts?: ListOptions): string;
+interface TreeNode {
+    label: string;
+    children?: TreeNode[];
+    /** Whether this node's children should be collapsed (hidden) */
+    collapsed?: boolean;
+}
+/**
+ * Render a tree structure with Unicode box-drawing connectors.
+ *
+ * ```
+ * Root
+ * ├── Child 1
+ * │   ├── Grandchild A
+ * │   └── Grandchild B
+ * └── Child 2
+ * ```
+ */
+declare function renderTree(node: TreeNode, prefix?: string, isLast?: boolean, isRoot?: boolean): string;
+/**
+ * Render a grouped list with section headers.
+ *
+ * ```
+ * ── Critical (3) ──────────
+ *   • Issue 1
+ *   • Issue 2
+ *   • Issue 3
+ *
+ * ── Warning (5) ───────────
+ *   • Issue 4
+ *   ...
+ * ```
+ */
+declare function renderGroupedList(groups: Map<string, string[]> | Record<string, string[]>, opts?: ListOptions): string;
+
+/**
+ * Diff rendering primitive for terminal output.
+ *
+ * Displays unified or side-by-side diffs with
+ * colored additions/deletions.
+ */
+type DiffMode = "unified" | "side-by-side";
+interface DiffLine {
+    type: "add" | "remove" | "context" | "header";
+    content: string;
+    lineNum?: number;
+}
+interface DiffOptions {
+    mode?: DiffMode;
+    context?: number;
+    maxWidth?: number;
+}
+/**
+ * Render a unified diff from structured diff lines.
+ */
+declare function renderDiff(lines: DiffLine[], opts?: DiffOptions): string;
+/**
+ * Parse a unified diff string into structured DiffLine array.
+ */
+declare function parseDiff(diffText: string): DiffLine[];
+
+/**
+ * Renderer interface and factory for terminal output.
+ *
+ * Two rendering modes:
+ * - AlternateScreenRenderer: Full terminal takeover (TTY)
+ * - InlineRenderer: Timestamped log lines (CI/piped)
+ */
+interface DashboardState {
+    phase: string;
+    phaseIndex: number;
+    phaseTotal: number;
+    url: string;
+    mode: string;
+    progress: Record<string, number>;
+    totals: Record<string, number>;
+    issueCount: number;
+    scorePreview: number | null;
+    verbose: boolean;
+    elapsed: number;
+}
+interface SummaryResult {
+    url: string;
+    mode: string;
+    overallScore: number;
+    scores: Record<string, number>;
+    issueCount: number;
+    passed: boolean;
+    elapsed: number;
+}
+interface Renderer {
+    /** Update the display with new state */
+    update(state: DashboardState): void;
+    /** Show final summary and clean up */
+    finish(result: SummaryResult): void;
+    /** Clean up resources (keyboard, alternate screen, etc.) */
+    dispose(): void;
+}
+type RendererMode = "alternate" | "inline" | "auto";
+/**
+ * Create a renderer based on mode or auto-detection.
+ *
+ * auto: alternate in interactive TTY, inline in CI/piped
+ */
+declare function createRenderer(mode?: RendererMode, output?: NodeJS.WritableStream): Renderer;
+
+/**
+ * Alternate screen renderer for interactive TTY.
+ *
+ * Takes over the terminal with a full-screen dashboard.
+ * Uses the alternate screen buffer to preserve scrollback.
+ * On dispose, restores the original terminal.
+ */
+
+declare class AlternateScreenRenderer implements Renderer {
+    private output;
+    private entered;
+    constructor(output?: NodeJS.WritableStream);
+    update(state: DashboardState): void;
+    finish(result: SummaryResult): void;
+    dispose(): void;
+    private renderSummary;
+}
+
+/**
+ * Inline renderer for CI/piped environments.
+ *
+ * Writes timestamped, non-interactive log lines to stderr.
+ * No cursor movement, no ANSI escape sequences beyond color.
+ * Compatible with log aggregation tools.
+ */
+
+declare class InlineRenderer implements Renderer {
+    private output;
+    private lastPhase;
+    constructor(output?: NodeJS.WritableStream);
+    update(state: DashboardState): void;
+    finish(result: SummaryResult): void;
+    dispose(): void;
+}
+
+/**
+ * Dashboard frame renderer — pure function.
+ *
+ * Takes dashboard state + terminal dimensions, returns a string
+ * representing the full screen content. No side effects.
+ */
+
+/**
+ * Render a complete dashboard frame.
+ *
+ * Pure function — no I/O, no side effects, fully testable.
+ */
+declare function renderFrame(state: DashboardState, width: number, _height: number): string;
+
+/**
+ * Dashboard state types and phase definitions.
+ */
+declare const AuditPhase: {
+    readonly Connecting: "Connecting";
+    readonly Crawling: "Crawling";
+    readonly Analyzing: "Analyzing";
+    readonly Scoring: "Scoring";
+    readonly Done: "Done";
+    readonly Failed: "Failed";
+};
+type AuditPhaseName = (typeof AuditPhase)[keyof typeof AuditPhase];
+/** Ordered phases for progress indication */
+declare const PHASE_ORDER: AuditPhaseName[];
+/** Get the index of a phase in the ordered sequence */
+declare function phaseIndex(phase: string): number;
+/** Get the total number of actionable phases (excluding Done) */
+declare function phaseTotal(): number;
+
+/**
+ * Keyboard handler for dashboard interaction.
+ *
+ * Listens for keypresses in raw mode and emits semantic events.
+ * Only works in TTY — gracefully no-ops in non-TTY environments.
+ */
+type KeyboardEvent = "quit" | "verbose";
+interface KeyboardHandler {
+    /** Start listening for keypresses */
+    start(): void;
+    /** Stop listening and restore terminal state */
+    dispose(): void;
+    /** Register an event handler */
+    on(event: KeyboardEvent, handler: () => void): void;
+}
+/**
+ * Create a keyboard handler.
+ *
+ * @param stdin - Input stream (defaults to process.stdin, injectable for testing)
+ */
+declare function createKeyboardHandler(stdin?: NodeJS.ReadStream): KeyboardHandler;
+
+export { AlternateScreenRenderer, AuditPhase, type AuditPhaseName, type BorderChars, type BorderStyle, type BoxOptions, type Column, type DashboardState, type DiffLine, type DiffMode, type DiffOptions, InlineRenderer, type KeyboardEvent, type KeyboardHandler, type ListOptions, type MultiProgress, PHASE_ORDER, type ProgressBar, type ProgressBarOptions, type Renderer, type RendererMode, type SeverityLevel, type SpinnerInstance, type SummaryResult, type TableOptions, type TreeNode, applyGradient, bold$1 as bold, boldColor, borders, box, brand, center, colorize, createKeyboardHandler, createMultiProgress, createProgressBar, createRenderer, createSpinner, cursor, dim$1 as dim, getTerminalHeight, getTerminalWidth, gradient, isCI, isColorEnabled, isStdinTTY, isStdoutTTY, isTTY, padEnd, padStart, parseDiff, phaseIndex, phaseTotal, renderDiff, renderFrame, renderGroupedList, renderList, renderTable, renderTree, scoreColor, screen, setColorEnabled, severity, severityLabels, severityOrder, shouldUseColor, stripAnsi, style, supportsUnicode, text, tokens, truncate, visibleLength };