qa360 2.1.7 → 2.2.0

package/core/src/tui/monitor.ts

@@ -0,0 +1,331 @@
+/**
+ * TUI Monitor - Real-time test execution monitor
+ * Listens to Phase3Runner events and updates the terminal UI
+ */
+
+import type { TUIOptions, TUIState, TUIEvent, TUIGateState } from './types.js';
+import { TerminalRenderer } from './renderer.js';
+
+export class TUIMonitor {
+  private renderer: TerminalRenderer;
+  private state: TUIState;
+  private refreshInterval?: NodeJS.Timeout;
+  private eventBuffer: TUIEvent[] = [];
+  private gateStartTime = new Map<string, number>();
+
+  constructor(private options: TUIOptions = {}) {
+    this.renderer = new TerminalRenderer({
+      colors: options.colors ?? true,
+      width: options.width
+    });
+
+    this.state = {
+      status: 'idle',
+      currentPhase: 'Initializing',
+      progress: 0,
+      gates: [],
+      startTime: Date.now(),
+      elapsed: 0
+    };
+
+    // Hide cursor for cleaner UI
+    process.stdout.write('\x1b[?25l');
+  }
+
+  /**
+   * Start monitoring a test run
+   */
+  start(totalGates: number): void {
+    this.state.status = 'running';
+    this.state.currentPhase = 'Setup';
+    this.state.gates = Array.from({ length: totalGates }, (_, i) => ({
+      name: `Gate ${i + 1}`,
+      status: 'pending'
+    }));
+    this.state.startTime = Date.now();
+
+    // Start refresh loop
+    const refreshRate = this.options.refreshRate ?? 500;
+    this.refreshInterval = setInterval(() => {
+      this.updateElapsed();
+      this.calculateETA();
+      this.renderer.render(this.state);
+    }, refreshRate);
+
+    // Handle exit signals
+    this.setupExitHandlers();
+  }
+
+  /**
+   * Emit an event during test execution
+   */
+  emit(event: TUIEvent): void {
+    this.eventBuffer.push(event);
+    this.processEvent(event);
+  }
+
+  /**
+   * Update gate status
+   */
+  updateGate(name: string, updates: Partial<TUIGateState>): void {
+    const gate = this.state.gates.find(g => g.name === name);
+    if (gate) {
+      Object.assign(gate, updates);
+    }
+  }
+
+  /**
+   * Mark gate as started
+   */
+  startGate(name: string): void {
+    // If gate doesn't exist, add it
+    if (!this.state.gates.find(g => g.name === name)) {
+      this.state.gates.push({ name, status: 'pending' });
+    }
+
+    this.gateStartTime.set(name, Date.now());
+    this.updateGate(name, {
+      status: 'running'
+    });
+    this.state.currentGate = name;
+  }
+
+  /**
+   * Mark gate as completed
+   */
+  completeGate(name: string, success: boolean, results?: {
+    total: number;
+    passed: number;
+    failed: number;
+  }): void {
+    const startTime = this.gateStartTime.get(name);
+    const duration = startTime ? Date.now() - startTime : undefined;
+
+    this.updateGate(name, {
+      status: success ? 'passed' : 'failed',
+      duration,
+      testsTotal: results?.total,
+      testsPassed: results?.passed,
+      testsFailed: results?.failed
+    });
+
+    this.state.currentGate = undefined;
+    this.updateProgress();
+  }
+
+  /**
+   * Set current phase
+   */
+  setPhase(phase: string): void {
+    this.state.currentPhase = phase;
+  }
+
+  /**
+   * Set current progress (0-100)
+   */
+  setProgress(progress: number): void {
+    this.state.progress = Math.max(0, Math.min(100, progress));
+  }
+
+  /**
+   * Update test progress for current gate
+   */
+  updateTestProgress(gateName: string, completed: number, total: number): void {
+    this.updateGate(gateName, {
+      testsTotal: total,
+      testsPassed: completed
+    });
+  }
+
+  /**
+   * Mark run as failed
+   */
+  fail(error: string): void {
+    this.state.status = 'failed';
+    this.stop();
+  }
+
+  /**
+   * Mark run as completed
+   */
+  complete(): void {
+    this.state.status = 'completed';
+    this.state.progress = 100;
+    this.stop();
+  }
+
+  /**
+   * Stop monitoring and cleanup
+   */
+  stop(): void {
+    if (this.refreshInterval) {
+      clearInterval(this.refreshInterval);
+      this.refreshInterval = undefined;
+    }
+
+    // Final render
+    this.renderer.render(this.state);
+
+    // Wait a bit to show final state, then cleanup
+    setTimeout(() => {
+      this.cleanup();
+    }, 1000);
+  }
+
+  /**
+   * Cleanup and restore terminal
+   */
+  cleanup(): void {
+    this.renderer.cleanup();
+    this.removeExitHandlers();
+
+    // Print final summary
+    this.printSummary();
+  }
+
+  /**
+   * Get current state
+   */
+  getState(): Readonly<TUIState> {
+    return this.state;
+  }
+
+  /**
+   * Get event buffer
+   */
+  getEvents(): ReadonlyArray<TUIEvent> {
+    return this.eventBuffer;
+  }
+
+  // Private methods
+
+  private processEvent(event: TUIEvent): void {
+    switch (event.type) {
+      case 'phase_start':
+        this.setPhase(String(event.data.phase));
+        break;
+      case 'gate_start':
+        this.startGate(String(event.data.gate));
+        break;
+      case 'gate_end':
+        this.completeGate(
+          String(event.data.gate),
+          Boolean(event.data.success),
+          event.data.results as { total: number; passed: number; failed: number } | undefined
+        );
+        break;
+      case 'test_progress':
+        this.updateTestProgress(
+          String(event.data.gate),
+          Number(event.data.completed),
+          Number(event.data.total)
+        );
+        break;
+      case 'error':
+        this.fail(String(event.data.error));
+        break;
+    }
+  }
+
+  private updateElapsed(): void {
+    this.state.elapsed = Date.now() - this.state.startTime;
+  }
+
+  private calculateETA(): void {
+    if (this.state.progress <= 0) {
+      this.state.eta = undefined;
+      return;
+    }
+
+    const elapsed = this.state.elapsed;
+    const progress = this.state.progress / 100;
+    const estimatedTotal = elapsed / progress;
+    this.state.eta = estimatedTotal - elapsed;
+  }
+
+  private updateProgress(): void {
+    const total = this.state.gates.length;
+    const completed = this.state.gates.filter(g =>
+      g.status === 'passed' || g.status === 'failed' || g.status === 'skipped'
+    ).length;
+
+    this.state.progress = total > 0 ? (completed / total) * 100 : 0;
+  }
+
+  private printSummary(): void {
+    const { status, gates, elapsed } = this.state;
+
+    console.log('\n' + '='.repeat(60));
+    console.log(`  Test Run ${status === 'completed' ? 'Completed' : 'Failed'}`);
+    console.log('='.repeat(60));
+
+    const passed = gates.filter(g => g.status === 'passed').length;
+    const failed = gates.filter(g => g.status === 'failed').length;
+    const skipped = gates.filter(g => g.status === 'skipped').length;
+
+    console.log(`  Total Gates: ${gates.length}`);
+    console.log(`  Passed: ${this.formatCount(passed, 'green')}`);
+    console.log(`  Failed: ${this.formatCount(failed, 'red')}`);
+    console.log(`  Skipped: ${this.formatCount(skipped, 'dim')}`);
+    console.log(`  Duration: ${this.formatDuration(elapsed)}`);
+    console.log('='.repeat(60) + '\n');
+  }
+
+  private formatCount(count: number, color: string): string {
+    const code = { green: '32', red: '31', dim: '2' }[color] || '0';
+    return `\x1b[${code}m${count}\x1b[0m`;
+  }
+
+  private formatDuration(ms: number): string {
+    if (ms < 1000) return `${ms}ms`;
+    if (ms < 60000) return `${(ms / 1000).toFixed(1)}s`;
+    const min = Math.floor(ms / 60000);
+    const sec = Math.floor((ms % 60000) / 1000);
+    return `${min}m ${sec}s`;
+  }
+
+  private setupExitHandlers(): void {
+    process.on('SIGINT', this.handleExit.bind(this));
+    process.on('SIGTERM', this.handleExit.bind(this));
+  }
+
+  private removeExitHandlers(): void {
+    process.off('SIGINT', this.handleExit.bind(this));
+    process.off('SIGTERM', this.handleExit.bind(this));
+  }
+
+  private handleExit(): void {
+    this.cleanup();
+    process.exit(0);
+  }
+}
+
+/**
+ * Create a monitor instance for programmatic use
+ */
+export function createMonitor(options?: TUIOptions): TUIMonitor {
+  return new TUIMonitor(options);
+}
+
+/**
+ * Convenience function to monitor a Phase3Runner execution
+ */
+export async function monitorExecution(
+  execute: (emit: (event: TUIEvent) => void) => Promise<void>,
+  options?: TUIOptions
+): Promise<void> {
+  const monitor = new TUIMonitor(options);
+
+  try {
+    await execute(monitor.emit.bind(monitor));
+    monitor.complete();
+  } catch (error) {
+    monitor.emit({
+      type: 'error',
+      timestamp: Date.now(),
+      data: { error: error instanceof Error ? error.message : String(error) }
+    });
+  }
+
+  return;
+}

package/core/src/tui/renderer.ts

@@ -0,0 +1,269 @@
+/**
+ * TUI Renderer - Renders UI components to terminal
+ * Pure ANSI/Unicode rendering with no external dependencies
+ */
+
+import type {
+  TUIState,
+  TUIGateState,
+  TUIRenderer,
+  TUIProgressBarOptions,
+  TUITableOptions,
+  TUILayout,
+  TUISection
+} from './types.js';
+
+export class TerminalRenderer implements TUIRenderer {
+  private readonly colors: boolean;
+  private readonly width: number;
+  private lastRender = '';
+  private renderCount = 0;
+
+  constructor(options?: { colors?: boolean; width?: number }) {
+    this.colors = options?.colors ?? true;
+    this.width = options?.width ?? this.getTerminalWidth();
+  }
+
+  private getTerminalWidth(): number {
+    return process.stdout.columns || 80;
+  }
+
+  render(state: TUIState): string {
+    this.renderCount++;
+
+    const layout: TUILayout = {
+      header: this.renderHeader(state),
+      sections: [
+        { type: 'divider' },
+        { type: 'text', content: this.renderProgress(state) },
+        { type: 'progress', options: this.createProgressBar(state) },
+        { type: 'divider' },
+        { type: 'table', options: this.createGatesTable(state) }
+      ],
+      footer: this.renderFooter(state)
+    };
+
+    const output = this.renderLayout(layout);
+
+    // Only output if changed (reduces flicker)
+    if (output !== this.lastRender) {
+      this.lastRender = output;
+      // Clear screen and move to top
+      process.stdout.write('\x1b[2J\x1b[H');
+      process.stdout.write(output);
+    }
+
+    return output;
+  }
+
+  cleanup(): void {
+    // Clear any remaining progress indicators
+    process.stdout.write('\x1b[2J\x1b[H');
+    process.stdout.write('\x1b[?25h'); // Show cursor
+  }
+
+  private renderLayout(layout: TUILayout): string {
+    const lines: string[] = [];
+
+    if (layout.header) {
+      lines.push(layout.header);
+    }
+
+    for (const section of layout.sections) {
+      switch (section.type) {
+        case 'text':
+          if (section.content) lines.push(section.content);
+          break;
+        case 'divider':
+          lines.push(this.divider(this.width));
+          break;
+        case 'progress':
+          if (section.options) lines.push(this.progressBar(section.options as TUIProgressBarOptions));
+          break;
+        case 'table':
+          if (section.options) lines.push(...this.table(section.options as TUITableOptions));
+          break;
+      }
+    }
+
+    if (layout.footer) {
+      lines.push('');
+      lines.push(layout.footer);
+    }
+
+    return lines.join('\n');
+  }
+
+  private renderHeader(state: TUIState): string {
+    const statusIcon = this.getStatusIcon(state.status);
+    const statusText = this.colorize(state.status.toUpperCase(), state.status);
+    const version = 'QA360 v1.4.7';
+
+    return [
+      this.colorize('╔════════════════════════════════════════════════════════════╗', 'dim'),
+      this.colorize(`║  ${version} - Test Execution Monitor${' '.repeat(Math.max(0, this.width - 60))}║`, 'bold'),
+      this.colorize('╠════════════════════════════════════════════════════════════╣', 'dim'),
+      this.colorize(`║  Status: ${statusIcon} ${statusText}${' '.repeat(Math.max(0, this.width - 65))}║`, 'reset'),
+      this.colorize('╚════════════════════════════════════════════════════════════╝', 'dim')
+    ].join('\n');
+  }
+
+  private renderProgress(state: TUIState): string {
+    const elapsed = this.formatDuration(state.elapsed);
+    const eta = state.eta ? this.formatDuration(state.eta) : '--:--';
+    const progress = state.progress.toFixed(1);
+
+    return `  Phase: ${state.currentPhase}  |  Progress: ${progress}%  |  Elapsed: ${elapsed}  |  ETA: ${eta}`;
+  }
+
+  private createProgressBar(state: TUIState): TUIProgressBarOptions {
+    return {
+      width: this.width - 10,
+      progress: state.progress,
+      label: state.currentGate ? `Running: ${state.currentGate}` : undefined,
+      showPercent: true
+    };
+  }
+
+  private createGatesTable(state: TUIState): TUITableOptions {
+    return {
+      columns: [
+        { key: 'status', width: 3, label: '' },
+        { key: 'name', width: 25, label: 'Gate' },
+        { key: 'tests', width: 20, label: 'Tests' },
+        { key: 'duration', width: 10, label: 'Duration' }
+      ],
+      rows: state.gates.map(gate => ({
+        status: this.getGateStatusIcon(gate.status),
+        name: gate.name,
+        tests: this.formatTestCounts(gate),
+        duration: gate.duration ? this.formatDuration(gate.duration) : '--'
+      })),
+      showHeaders: true
+    };
+  }
+
+  private renderFooter(state: TUIState): string {
+    const help = 'Press Ctrl+C to exit';
+    return this.colorize(`  ${help}`, 'dim');
+  }
+
+  // UI Components
+
+  divider(width: number, char = '─'): string {
+    return this.colorize(char.repeat(Math.min(width, 80)), 'dim');
+  }
+
+  progressBar(options: TUIProgressBarOptions): string {
+    const { width, progress, label, showPercent } = options;
+    const filled = Math.floor((progress / 100) * (width - 4));
+    const empty = (width - 4) - filled;
+
+    const bar = '├' +
+      '█'.repeat(filled) +
+      (empty > 0 ? '░' : '') +
+      '░'.repeat(Math.max(0, empty - 1)) +
+      '┤';
+
+    const percent = showPercent ? ` ${progress.toFixed(1)}%` : '';
+    const labelStr = label ? `${label} ` : '';
+
+    return `  ${labelStr}${bar}${percent}`;
+  }
+
+  table(options: TUITableOptions): string[] {
+    const { columns, rows, showHeaders } = options;
+    const lines: string[] = [''];
+
+    // Header
+    if (showHeaders) {
+      const header = columns.map(col =>
+        (col.label || col.key).padEnd(col.width)
+      ).join('  ');
+      lines.push(`  ${this.colorize(header, 'bold')}`);
+      lines.push(`  ${'─'.repeat(header.length)}`);
+    }
+
+    // Rows
+    for (const row of rows) {
+      const line = columns.map(col =>
+        String(row[col.key] || '').padEnd(col.width)
+      ).join('  ');
+      lines.push(`  ${line}`);
+    }
+
+    return lines;
+  }
+
+  // Utilities
+
+  private getStatusIcon(status: TUIState['status']): string {
+    const icons = {
+      idle: '○',
+      running: '●',
+      paused: '◐',
+      completed: '✓',
+      failed: '✗'
+    };
+    return this.colorize(icons[status] || '○', status);
+  }
+
+  private getGateStatusIcon(status: TUIGateStatusType): string {
+    const icons = {
+      pending: this.colorize('○', 'dim'),
+      running: this.colorize('●', 'yellow'),
+      passed: this.colorize('✓', 'green'),
+      failed: this.colorize('✗', 'red'),
+      skipped: this.colorize('○', 'dim')
+    };
+    return icons[status] || icons.pending;
+  }
+
+  private formatTestCounts(gate: TUIGateState): string {
+    if (gate.testsTotal === undefined) return '--';
+    const passed = gate.testsPassed ?? 0;
+    const failed = gate.testsFailed ?? 0;
+    return `${passed}/${gate.testsTotal} ${failed > 0 ? `(${failed} failed)` : ''}`;
+  }
+
+  private formatDuration(ms: number): string {
+    if (ms < 1000) return `${ms}ms`;
+    if (ms < 60000) return `${(ms / 1000).toFixed(1)}s`;
+    const min = Math.floor(ms / 60000);
+    const sec = Math.floor((ms % 60000) / 1000);
+    return `${min}m ${sec}s`;
+  }
+
+  private colorize(text: string, type: ColorType): string {
+    if (!this.colors) return text;
+
+    const codes = {
+      green: '32',
+      red: '31',
+      yellow: '33',
+      blue: '34',
+      dim: '2',
+      bold: '1',
+      reset: '0',
+      passed: '32',
+      failed: '31',
+      running: '33',
+      pending: '2',
+      skipped: '2',
+      idle: '34',
+      completed: '32',
+      paused: '33'
+    };
+
+    const code = codes[type] || '0';
+    return `\x1b[${code}m${text}\x1b[0m`;
+  }
+
+  getRenderCount(): number {
+    return this.renderCount;
+  }
+}
+
+type TUIGateStatusType = 'pending' | 'running' | 'passed' | 'failed' | 'skipped';
+
+type ColorType = 'green' | 'red' | 'yellow' | 'blue' | 'dim' | 'bold' | 'reset' | TUIGateStatusType | TUIState['status'];

package/core/src/tui/types.ts

@@ -0,0 +1,68 @@
+/**
+ * QA360 TUI (Terminal UI) Module
+ * Phase 8: Terminal UI for local monitoring
+ */
+
+export interface TUIOptions {
+  refreshRate?: number; // ms between updates, default 500
+  compact?: boolean; // Compact mode for small terminals
+  verbose?: boolean; // Show more details
+  colors?: boolean; // Enable colors (default: true)
+  width?: number; // Terminal width (for testing)
+}
+
+export interface TUIState {
+  status: 'idle' | 'running' | 'paused' | 'completed' | 'failed';
+  currentPhase: string;
+  progress: number; // 0-100
+  currentGate?: string;
+  gates: TUIGateState[];
+  startTime: number;
+  elapsed: number;
+  eta?: number;
+}
+
+export interface TUIGateState {
+  name: string;
+  status: 'pending' | 'running' | 'passed' | 'failed' | 'skipped';
+  duration?: number;
+  testsTotal?: number;
+  testsPassed?: number;
+  testsFailed?: number;
+}
+
+export interface TUIEvent {
+  type: 'phase_start' | 'phase_end' | 'gate_start' | 'gate_end' | 'test_progress' | 'error';
+  timestamp: number;
+  data: Record<string, unknown>;
+}
+
+export interface TUIRenderer {
+  render(state: TUIState): string;
+  cleanup(): void;
+}
+
+export interface TUIProgressBarOptions {
+  width: number;
+  progress: number; // 0-100
+  label?: string;
+  showPercent?: boolean;
+}
+
+export interface TUITableOptions {
+  columns: Array<{ key: string; width: number; label?: string }>;
+  rows: Array<Record<string, string | number>>;
+  showHeaders?: boolean;
+}
+
+export interface TUILayout {
+  header?: string;
+  sections: TUISection[];
+  footer?: string;
+}
+
+export interface TUISection {
+  type: 'text' | 'progress' | 'table' | 'divider';
+  content?: string;
+  options?: TUIProgressBarOptions | TUITableOptions;
+}