@vertaaux/cli 0.4.0 → 0.5.0

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

@@ -152,6 +152,13 @@ declare function boldColor(text: string, hex: string): string;
 declare function dim$1(text: string): string;
 /** Apply bold styling */
 declare function bold$1(text: string): string;
+/**
+ * Get colored severity label for a severity level.
+ * High-severity levels (critical, error, serious, warning) are bold; others are plain colored.
+ */
+declare function severityColor(level: string | undefined): string;
+/** Apply background hex color to text */
+declare function bgColor(text: string, hex: string): string;
 /** Apply gradient across text characters */
 declare function applyGradient(text: string, colors?: readonly string[]): string;
 
@@ -175,13 +182,104 @@ declare function isStdinTTY(): boolean;
  * 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. */
+/** Get terminal width from stderr (where UI renders). Falls back to 80.
+ *
+ * Checks COLUMNS env var first so that non-PTY subprocesses (e.g. snapshot
+ * test harness) can set a deterministic width for reproducible output.
+ */
 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;
 
+/**
+ * Plain mode state management.
+ *
+ * --plain is a superset of --no-color: it also replaces Unicode box-drawing
+ * chars and status symbols with ASCII equivalents, making output
+ * grep/awk/pipe-friendly (PLAIN-01, PLAIN-02).
+ *
+ * Circular dependency note: symbols.ts does NOT import from plain.ts.
+ * This module calls setSymbolTier() directly. detectSymbolTier() accepts
+ * a plainMode option parameter to receive state without circular import.
+ */
+/**
+ * Enable or disable plain mode.
+ *
+ * When enabled:
+ * - isColorEnabled() returns false (color disabled)
+ * - Symbol tier is switched to "ascii"
+ * - toPlainBox() replaces Unicode box-drawing chars with ASCII
+ */
+declare function setPlainMode(enabled: boolean): void;
+/** Whether plain mode is currently active */
+declare function isPlainMode(): boolean;
+/**
+ * Replace Unicode box-drawing characters with ASCII equivalents.
+ *
+ * Is a no-op when plain mode is not active.
+ * Replacements:
+ *   ─━═ → -   │┃║ → |   all corners/junctions (including rounded ╭╮╰╯) → +
+ */
+declare function toPlainBox(str: string): string;
+
+/**
+ * Three-tier glyph map for terminal status symbols.
+ *
+ * Tiers: nerd (Nerd Font PUA glyphs) → unicode (basic Unicode) → ascii (--plain)
+ * Default tier is "unicode". Tier is switched to "ascii" by setPlainMode(true).
+ *
+ * Circular dependency note: This module does NOT import from plain.ts.
+ * plain.ts calls setSymbolTier("ascii") directly. detectSymbolTier() accepts
+ * an options parameter to receive the plain mode state without importing it.
+ */
+type SymbolRole = "success" | "fail" | "warning" | "info" | "pending" | "running";
+type SymbolTier = "nerd" | "unicode" | "ascii";
+/** Set the active symbol tier */
+declare function setSymbolTier(tier: SymbolTier): void;
+/** Get the symbol string for a given role using the current tier */
+declare function sym(role: SymbolRole): string;
+interface DetectSymbolTierOptions {
+    /** Override plain mode state (avoids circular dependency with plain.ts) */
+    plainMode?: boolean;
+}
+/**
+ * Detect the appropriate symbol tier based on environment.
+ *
+ * Priority:
+ * 1. plainMode option (or isPlainMode()) → "ascii"
+ * 2. VERTAA_ICONS env var (nerd|unicode|ascii) → explicit choice
+ * 3. Known Nerd Font terminals (TERM_PROGRAM) → "nerd"
+ * 4. supportsUnicode() → "unicode"
+ * 5. Fallback → "ascii"
+ */
+declare function detectSymbolTier(options?: DetectSymbolTierOptions): SymbolTier;
+
+/**
+ * Easing functions for animation clock.
+ *
+ * Pure math functions with no side effects or dependencies.
+ * Consumed by Phase 97+ for banner entrance animation and spinner timing.
+ */
+/** Linear progression — t maps directly to output */
+declare function linear(t: number): number;
+/** Ease in — slow start, fast end (quadratic) */
+declare function easeIn(t: number): number;
+/** Ease out — fast start, slow end */
+declare function easeOut(t: number): number;
+/** Ease in-out — slow start and end, fast middle */
+declare function easeInOut(t: number): number;
+/**
+ * Interpolate between two values using an easing function.
+ *
+ * @param from - Start value
+ * @param to - End value
+ * @param t - Progress 0..1 (clamped automatically)
+ * @param ease - Easing function (default: linear)
+ */
+declare function lerp(from: number, to: number, t: number, ease?: typeof linear): number;
+
 /**
  * Text styling primitives for terminal output.
  *
@@ -310,6 +408,13 @@ declare function renderTable(rows: Record<string, string>[], columns: Column[],
  * Renders an animated spinner with text to stderr.
  * Writes ONLY to stderr — never pollutes stdout.
  */
+declare const BRAILLE_FRAMES: string[];
+declare const FRAME_INTERVAL = 80;
+/**
+ * Pure function: return the braille spinner character for the given frame index.
+ * Wraps around using modulo — frame index can be any non-negative integer.
+ */
+declare function spinnerFrame(frameIndex: number): string;
 interface SpinnerInstance {
     /** Start the spinner animation */
     start(): void;
@@ -471,6 +576,117 @@ declare function renderDiff(lines: DiffLine[], opts?: DiffOptions): string;
  */
 declare function parseDiff(diffText: string): DiffLine[];
 
+/**
+ * Branded error and warning box primitives.
+ *
+ * Renders error/warning messages in a rounded-border box with
+ * color hierarchy: bold red message, dim context, lime suggestion,
+ * dim exit code.
+ *
+ * Delegates to box() for border rendering.
+ * In plain mode, box() automatically converts to ASCII chars.
+ */
+interface ErrorBoxOptions {
+    /** Primary error message (displayed bold) */
+    message: string;
+    /** Additional context about where/why the error occurred (displayed dim) */
+    context?: string;
+    /** Suggested resolution — displayed as "Try: suggestion" in lime */
+    suggestion?: string;
+    /** Exit code from underlying process */
+    exitCode?: number;
+}
+/**
+ * Render a branded error box.
+ *
+ * @param opts - Error box options
+ * @returns Rendered box string with rounded border, red border color
+ */
+declare function renderError(opts: ErrorBoxOptions): string;
+/**
+ * Render a branded warning box.
+ *
+ * @param opts - Warning box options (no exitCode)
+ * @returns Rendered box string with rounded border, amber border color
+ */
+declare function renderWarning(opts: Omit<ErrorBoxOptions, "exitCode">): string;
+
+/**
+ * Step-list rendering primitives for CLI step progress display.
+ *
+ * Provides types, pure rendering functions for multi-step progress UI.
+ * All rendering is stateless — pass StepState[] + frameIndex each render cycle.
+ */
+type StepStatus = "pending" | "running" | "done" | "failed" | "skipped" | "warning";
+/** Definition of a step (static configuration) */
+interface StepDef {
+    id: string;
+    actionText: string;
+    summaryText: string;
+    run: () => Promise<void>;
+    subSteps?: StepDef[];
+}
+/** Mutable state of a step during execution */
+interface StepState {
+    id: string;
+    actionText: string;
+    summaryText: string;
+    status: StepStatus;
+    startedAt: number | undefined;
+    finishedAt: number | undefined;
+    durationMs: number | undefined;
+    failReason: string | undefined;
+    subSteps: StepState[] | undefined;
+}
+/** Result of a completed step */
+interface StepResult {
+    id: string;
+    status: StepStatus;
+    durationMs: number | undefined;
+    failReason: string | undefined;
+}
+/**
+ * Render a list of steps as a terminal string.
+ *
+ * @param steps - Array of step states to render
+ * @param frameIndex - Current animation frame index (for spinner)
+ * @param termWidth - Terminal width for right-alignment (default: 80)
+ * @returns Rendered string without trailing newline
+ */
+declare function renderStepList(steps: StepState[], frameIndex: number, termWidth?: number): string;
+
+/**
+ * runSteps — async step orchestrator.
+ *
+ * Executes a list of StepDef sequentially, managing state transitions
+ * and reporting via onStateChange callback.
+ *
+ * Fail modes:
+ *   - failFast=true (CI/non-TTY default): mark current step "failed",
+ *     mark remaining steps "skipped", return immediately.
+ *   - failFast=false (interactive TTY default): mark current step "warning",
+ *     continue to next step.
+ */
+
+interface RunStepsOptions {
+    /** Whether to stop on first failure (default: isCI() || !isTTY()) */
+    failFast?: boolean;
+    /** Called after every state transition with the full states array */
+    onStateChange?: (states: StepState[]) => void;
+}
+interface RunStepsResult {
+    success: boolean;
+    states: StepState[];
+}
+/**
+ * Run a list of step definitions sequentially.
+ *
+ * @param defs - Step definitions to run
+ * @param opts - Options including failFast mode and onStateChange callback
+ * @returns Result with success flag and final states array
+ */
+declare function runSteps(defs: StepDef[], opts?: RunStepsOptions): Promise<RunStepsResult>;
+
 /**
  * Renderer interface and factory for terminal output.
  *
@@ -478,6 +694,7 @@ declare function parseDiff(diffText: string): DiffLine[];
  * - AlternateScreenRenderer: Full terminal takeover (TTY)
  * - InlineRenderer: Timestamped log lines (CI/piped)
  */
+
 interface DashboardState {
     phase: string;
     phaseIndex: number;
@@ -490,6 +707,9 @@ interface DashboardState {
     scorePreview: number | null;
     verbose: boolean;
     elapsed: number;
+    /** Optional step states for step-list rendering. When present and non-empty,
+     * ComposedRenderer replaces the single-spinner line with a step list. */
+    stepStates?: StepState[];
 }
 interface SummaryResult {
     url: string;
@@ -507,12 +727,21 @@ interface Renderer {
     finish(result: SummaryResult): void;
     /** Clean up resources (keyboard, alternate screen, etc.) */
     dispose(): void;
+    /** Stop animation and show cursor before a prompt */
+    suspend(): void;
+    /** Restart animation after a prompt resolves */
+    resume(): void;
 }
-type RendererMode = "alternate" | "inline" | "auto";
+type RendererMode = "alternate" | "inline" | "composed" | "auto";
+/** Set a renderer override. Pass null to clear. */
+declare function setRendererOverride(renderer: Renderer | null): void;
 /**
  * Create a renderer based on mode or auto-detection.
  *
- * auto: alternate in interactive TTY, inline in CI/piped
+ * If a renderer override is active (set by the interactive app),
+ * returns the override instead of creating a new one.
+ *
+ * auto: composed in interactive TTY, inline in CI/piped
  */
 declare function createRenderer(mode?: RendererMode, output?: NodeJS.WritableStream): Renderer;
 
@@ -531,9 +760,44 @@ declare class AlternateScreenRenderer implements Renderer {
     update(state: DashboardState): void;
     finish(result: SummaryResult): void;
     dispose(): void;
+    suspend(): void;
+    resume(): void;
     private renderSummary;
 }
 
+/**
+ * ComposedRenderer — scroll-proof terminal rendering using alternate screen.
+ *
+ * Enters the alternate screen buffer on first update, renders the step-list
+ * with animated spinners, and exits on finish(). The alternate screen is
+ * scroll-proof — users cannot scroll past the rendered content.
+ *
+ * After finish(), output returns to the normal terminal where results
+ * (scores, issues, quality gate) are written to scrollback.
+ */
+
+declare class ComposedRenderer implements Renderer {
+    private output;
+    private tickTimer;
+    private frameIndex;
+    private suspended;
+    private resizeTimer;
+    private lastState;
+    private entered;
+    constructor(output?: NodeJS.WritableStream);
+    update(state: DashboardState): void;
+    finish(result: SummaryResult): void;
+    dispose(): void;
+    suspend(): void;
+    resume(): void;
+    private startTick;
+    private stopTick;
+    private onResize;
+    private capContent;
+    private buildContent;
+    private buildFinishContent;
+}
+
 /**
  * Inline renderer for CI/piped environments.
  *
@@ -549,6 +813,98 @@ declare class InlineRenderer implements Renderer {
     update(state: DashboardState): void;
     finish(result: SummaryResult): void;
     dispose(): void;
+    suspend(): void;
+    resume(): void;
+}
+
+/**
+ * Physical row calculation for terminal cursor math.
+ *
+ * Calculates how many terminal rows a string occupies at a given terminal
+ * width, accounting for line wrapping and ANSI escape sequences.
+ *
+ * Used by ComposedRenderer to determine how far to move the cursor up
+ * before redrawing — prevents cursor drift at 120+ column widths.
+ */
+/**
+ * Calculate the number of physical terminal rows occupied by a string.
+ *
+ * Each logical line (split on "\n") occupies ceil(visibleLength / terminalWidth)
+ * rows, with a minimum of 1 row per line (empty lines still occupy a row).
+ *
+ * @param content - The string to measure (may contain ANSI escape codes and newlines)
+ * @param terminalWidth - The terminal column width
+ * @returns Number of physical rows, or 0 if terminalWidth <= 0
+ */
+declare function physicalRows(content: string, terminalWidth: number): number;
+
+/**
+ * ScrollingViewport — fixed-height arrow-key navigable list with expand/collapse.
+ *
+ * Renders a scrollable list of items within a bounded terminal region using
+ * cursor.up(N) + clearDown for in-place updates (no alternate screen).
+ *
+ * Features:
+ * - Up/Down arrows, j/k aliases, Page Up/Down navigation
+ * - Boundary stop (no wrap-around)
+ * - Top/bottom scroll indicators with item counts
+ * - Enter to toggle inline detail expansion; Esc to collapse
+ * - Ctrl+C exits cleanly and always restores terminal state
+ * - Terminal resize recalculates visibleRows and clamps scrollOffset
+ *
+ * All output goes to stderr (the `output` param). No alternate screen.
+ */
+interface ViewportItem {
+    /** Unique identifier for this item */
+    id: string;
+    /** Severity level: critical, error, serious, warning, moderate, minor, info */
+    severity: string;
+    /** Display title */
+    title: string;
+    /** Effort estimate: trivial|small|medium|large */
+    effort: string;
+    /** Optional detail text shown when item is expanded */
+    detail?: string;
+}
+interface ViewportOptions {
+    items: ViewportItem[];
+    /** Maximum visible rows. Actual visibleRows = Math.min(maxRows, termHeight - 4). Default: 10 */
+    maxRows?: number;
+    /** Output stream. Default: process.stderr */
+    output?: NodeJS.WritableStream;
+    /** Input stream. Default: process.stdin */
+    stdin?: NodeJS.ReadStream;
+}
+declare class ScrollingViewport {
+    private readonly items;
+    private readonly maxRows;
+    private readonly output;
+    private readonly stdin;
+    /** Index of the currently highlighted item (0-indexed) */
+    cursorIdx: number;
+    /** Index of first visible item */
+    scrollOffset: number;
+    /** Index of expanded item (-1 = none) */
+    expandedIdx: number;
+    /** Calculated visible rows (updated on resize) */
+    visibleRows: number;
+    private lastRows;
+    private resizeTimer;
+    constructor(options: ViewportOptions);
+    /**
+     * Run the viewport interactively.
+     *
+     * Guard: if stdin is not a TTY or setRawMode is unavailable, returns
+     * immediately (non-interactive fallback).
+     *
+     * Resolves when the user presses Ctrl+C.
+     */
+    run(): Promise<void>;
+    private calcVisibleRows;
+    private clampScrollOffset;
+    private handleAction;
+    private buildFrame;
+    private redraw;
 }
 
 /**
@@ -590,6 +946,7 @@ declare function phaseTotal(): number;
  * Listens for keypresses in raw mode and emits semantic events.
  * Only works in TTY — gracefully no-ops in non-TTY environments.
  */
+declare function setKeyboardOverrideActive(active: boolean): void;
 type KeyboardEvent = "quit" | "verbose";
 interface KeyboardHandler {
     /** Start listening for keypresses */
@@ -606,4 +963,4 @@ interface KeyboardHandler {
  */
 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 };
+export { AlternateScreenRenderer, AuditPhase, type AuditPhaseName, BRAILLE_FRAMES, type BorderChars, type BorderStyle, type BoxOptions, type Column, ComposedRenderer, type DashboardState, type DiffLine, type DiffMode, type DiffOptions, type ErrorBoxOptions, FRAME_INTERVAL, InlineRenderer, type KeyboardEvent, type KeyboardHandler, type ListOptions, type MultiProgress, PHASE_ORDER, type ProgressBar, type ProgressBarOptions, type Renderer, type RendererMode, type RunStepsOptions, ScrollingViewport, type SeverityLevel, type SpinnerInstance, type StepDef, type StepResult, type StepState, type StepStatus, type SummaryResult, type SymbolRole, type SymbolTier, type TableOptions, type TreeNode, type ViewportItem, type ViewportOptions, applyGradient, bgColor, bold$1 as bold, boldColor, borders, box, brand, center, colorize, createKeyboardHandler, createMultiProgress, createProgressBar, createRenderer, createSpinner, cursor, detectSymbolTier, dim$1 as dim, easeIn, easeInOut, easeOut, getTerminalHeight, getTerminalWidth, gradient, isCI, isColorEnabled, isPlainMode, isStdinTTY, isStdoutTTY, isTTY, lerp, linear, padEnd, padStart, parseDiff, phaseIndex, phaseTotal, physicalRows, renderDiff, renderError, renderFrame, renderGroupedList, renderList, renderStepList, renderTable, renderTree, renderWarning, runSteps, scoreColor, screen, setColorEnabled, setKeyboardOverrideActive, setPlainMode, setRendererOverride, setSymbolTier, severity, severityColor, severityLabels, severityOrder, shouldUseColor, spinnerFrame, stripAnsi, style, supportsUnicode, sym, text, toPlainBox, tokens, truncate, visibleLength };