@microsoft/m365-copilot-eval 1.0.1-preview.1 → 1.1.0-preview.1

package/src/clients/node-js/lib/progress.js

@@ -0,0 +1,677 @@
+/**
+ * Progress display module for CLI initialization
+ * Provides real-time progress indication with support for:
+ * - Interactive TTY terminals (in-place updates, spinners, progress bars)
+ * - CI/CD environments (timestamped line-based output)
+ * - Verbose mode (detailed sub-step information)
+ */
+
+import * as readline from 'readline';
+import { setInterval, clearInterval } from 'timers';
+
+/**
+ * Initialization phases configuration
+ */
+export const PHASES = [
+  {
+    id: 'download',
+    name: 'Downloading Python runtime',
+    order: 1,
+    progressType: 'determinate',
+  },
+  {
+    id: 'extract',
+    name: 'Extracting Python runtime',
+    order: 2,
+    progressType: 'indeterminate',
+  },
+  {
+    id: 'venv',
+    name: 'Creating virtual environment',
+    order: 3,
+    progressType: 'indeterminate',
+  },
+  {
+    id: 'deps',
+    name: 'Installing dependencies',
+    order: 4,
+    progressType: 'determinate',
+  },
+];
+
+/**
+ * Spinner frames for indeterminate progress (Unicode Braille)
+ */
+const SPINNER_FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+const SPINNER_INTERVAL = 80; // ms
+
+/**
+ * Default options for ProgressReporter
+ */
+const DEFAULT_OPTIONS = {
+  verbose: false,
+  quiet: false,
+  forceInteractive: false,
+  forceNonInteractive: false,
+  ciOutputInterval: 30000, // 30 seconds
+};
+
+/**
+ * Detect if running in an interactive terminal
+ * @returns {boolean} True if interactive TTY, false for CI/CD or piped output
+ */
+export function isInteractiveTerminal() {
+  // Not a TTY (pipes, redirects)
+  if (!process.stdout.isTTY) return false;
+
+  // Common CI environment variables
+  if (process.env.CI) return false;
+  if (process.env.GITHUB_ACTIONS) return false;
+  if (process.env.JENKINS_URL) return false;
+  if (process.env.GITLAB_CI) return false;
+  if (process.env.TF_BUILD) return false; // Azure Pipelines
+  if (process.env.CIRCLECI) return false;
+  if (process.env.TRAVIS) return false;
+  if (process.env.BUILDKITE) return false;
+
+  return true;
+}
+
+/**
+ * Format bytes to human-readable string
+ * @param {number} bytes - Number of bytes
+ * @returns {string} Formatted string (e.g., "45.2 MB")
+ */
+export function formatBytes(bytes) {
+  if (bytes === 0) return '0 B';
+  if (bytes < 0) return '0 B';
+
+  const units = ['B', 'KB', 'MB', 'GB', 'TB'];
+  const k = 1024;
+  const i = Math.floor(Math.log(bytes) / Math.log(k));
+  const index = Math.min(i, units.length - 1);
+
+  return `${(bytes / Math.pow(k, index)).toFixed(index > 0 ? 1 : 0)} ${units[index]}`;
+}
+
+/**
+ * Format duration in milliseconds to human-readable string
+ * @param {number} ms - Duration in milliseconds
+ * @returns {string} Formatted string (e.g., "2m 30s")
+ */
+export function formatDuration(ms) {
+  if (ms < 0) ms = 0;
+
+  const seconds = Math.floor(ms / 1000);
+  const minutes = Math.floor(seconds / 60);
+  const remainingSeconds = seconds % 60;
+
+  if (minutes > 0) {
+    return `${minutes}m ${remainingSeconds}s`;
+  }
+  return `${seconds}s`;
+}
+
+/**
+ * Calculate estimated time remaining
+ * @param {number} current - Current progress value
+ * @param {number} total - Total progress value
+ * @param {number} elapsedMs - Elapsed time in milliseconds
+ * @returns {number|null} Estimated remaining time in ms, or null if not calculable
+ */
+export function calculateETA(current, total, elapsedMs) {
+  if (current <= 0 || total <= 0 || elapsedMs <= 0) return null;
+
+  const percentage = (current / total) * 100;
+  // Only calculate when we have enough progress data (> 5%)
+  if (percentage < 5) return null;
+
+  const rate = current / elapsedMs; // units per ms
+  const remaining = total - current;
+  return Math.round(remaining / rate);
+}
+
+/**
+ * Render ASCII progress bar
+ * @param {number} percentage - Progress percentage (0-100)
+ * @param {number} width - Bar width in characters
+ * @returns {string} Progress bar string (e.g., "[████████░░░░]")
+ */
+export function renderProgressBar(percentage, width = 12) {
+  const clamped = Math.max(0, Math.min(100, percentage));
+  const filled = Math.round((clamped / 100) * width);
+  const empty = width - filled;
+  return `[${'█'.repeat(filled)}${'░'.repeat(empty)}]`;
+}
+
+/**
+ * Spinner class for indeterminate progress
+ */
+export class Spinner {
+  constructor(label = '') {
+    this.label = label;
+    this.frameIndex = 0;
+    this.interval = null;
+    this.isRunning = false;
+  }
+
+  /**
+   * Start the spinner animation
+   * @param {Function} renderFn - Function to call with each frame
+   */
+  start(renderFn) {
+    if (this.isRunning) return;
+    this.isRunning = true;
+
+    this.interval = setInterval(() => {
+      const frame = SPINNER_FRAMES[this.frameIndex++ % SPINNER_FRAMES.length];
+      if (renderFn) {
+        renderFn(frame, this.label);
+      }
+    }, SPINNER_INTERVAL);
+  }
+
+  /**
+   * Stop the spinner animation
+   */
+  stop() {
+    if (this.interval) {
+      clearInterval(this.interval);
+      this.interval = null;
+    }
+    this.isRunning = false;
+  }
+
+  /**
+   * Update the spinner label
+   * @param {string} label - New label text
+   */
+  setLabel(label) {
+    this.label = label;
+  }
+}
+
+/**
+ * Progress Reporter class for managing initialization progress display
+ */
+export class ProgressReporter {
+  /**
+   * @param {Object} options - Configuration options
+   * @param {boolean} options.verbose - Show detailed sub-step information
+   * @param {boolean} options.quiet - Suppress all progress output
+   * @param {boolean} options.forceInteractive - Force interactive mode (for testing)
+   * @param {boolean} options.forceNonInteractive - Force CI mode (for testing)
+   * @param {number} options.ciOutputInterval - Interval (ms) between CI output lines
+   */
+  constructor(options = {}) {
+    this.options = { ...DEFAULT_OPTIONS, ...options };
+    this.isInteractive = this._determineInteractiveMode();
+    this.startTime = Date.now();
+    this.phaseStartTime = null;
+    this.currentPhase = null;
+    this.phaseStatuses = new Map();
+    this.spinner = null;
+    this.lastCIOutput = 0;
+
+    // Initialize phase statuses
+    for (const phase of PHASES) {
+      this.phaseStatuses.set(phase.id, 'pending');
+    }
+  }
+
+  /**
+   * Determine if we should use interactive mode
+   * @private
+   */
+  _determineInteractiveMode() {
+    if (this.options.forceInteractive) return true;
+    if (this.options.forceNonInteractive) return false;
+    return isInteractiveTerminal();
+  }
+
+  /**
+   * Get phase info by ID
+   * @param {string} phaseId - Phase identifier
+   * @returns {Object|undefined} Phase configuration
+   */
+  _getPhase(phaseId) {
+    return PHASES.find((p) => p.id === phaseId);
+  }
+
+  /**
+   * Format phase prefix for display
+   * @param {string} phaseId - Phase identifier
+   * @returns {string} Formatted prefix (e.g., "[Step 1/4]")
+   */
+  formatPhasePrefix(phaseId) {
+    const phase = this._getPhase(phaseId);
+    if (!phase) return '';
+    return `[Step ${phase.order}/${PHASES.length}]`;
+  }
+
+  /**
+   * Update the current line in place (TTY) or print new line (CI)
+   * @param {string} text - Text to display
+   */
+  updateLine(text) {
+    if (this.options.quiet) return;
+
+    if (this.isInteractive) {
+      // Truncate text to terminal width
+      const maxWidth = (process.stdout.columns || 80) - 1;
+      let displayText = text;
+      if (text.length > maxWidth) {
+        displayText = text.substring(0, maxWidth - 3) + '...';
+      }
+
+      // Simple in-place update: carriage return, clear, write
+      // Note: Dynamic terminal resize may cause brief artifacts
+      process.stdout.write('\r');
+      readline.clearLine(process.stdout, 0);
+      process.stdout.write(displayText);
+    } else {
+      // CI mode: print with timestamp
+      const elapsed = formatDuration(Date.now() - this.startTime);
+      console.log(`[${elapsed}] ${text}`);
+    }
+  }
+
+  /**
+   * Print a new line (both TTY and CI)
+   * @param {string} text - Text to display
+   */
+  printLine(text) {
+    if (this.options.quiet) return;
+
+    if (this.isInteractive) {
+      // Truncate text to terminal width to prevent wrapping
+      const maxWidth = (process.stdout.columns || 80) - 1;
+      let displayText = text;
+      if (text.length > maxWidth) {
+        displayText = text.substring(0, maxWidth - 3) + '...';
+      }
+
+      // Clear current line, write text, and move to next line
+      readline.cursorTo(process.stdout, 0);
+      readline.clearLine(process.stdout, 0);
+      process.stdout.write(displayText);
+      process.stdout.write('\n');
+    } else {
+      const elapsed = formatDuration(Date.now() - this.startTime);
+      console.log(`[${elapsed}] ${text}`);
+    }
+  }
+
+  /**
+   * Start a new phase
+   * @param {string} phaseId - Phase identifier
+   */
+  startPhase(phaseId) {
+    const phase = this._getPhase(phaseId);
+    if (!phase) return;
+
+    // Stop any existing spinner
+    if (this.spinner) {
+      this.spinner.stop();
+      this.spinner = null;
+    }
+
+    this.currentPhase = phaseId;
+    this.phaseStartTime = Date.now();
+    this.phaseStatuses.set(phaseId, 'active');
+
+    const prefix = this.formatPhasePrefix(phaseId);
+
+    if (phase.progressType === 'indeterminate' && this.isInteractive) {
+      // Start spinner for indeterminate phases
+      this.spinner = new Spinner(phase.name);
+      this.spinner.start((frame, label) => {
+        this.updateLine(`${prefix} ${label} ${frame}`);
+      });
+    } else if (!this.isInteractive) {
+      // CI mode: print phase start
+      this.printLine(`${prefix} ${phase.name}...`);
+      this.lastCIOutput = Date.now();
+    }
+  }
+
+  /**
+   * Update progress for the current phase
+   * @param {Object} update - Progress update
+   * @param {string} update.phaseId - Phase identifier
+   * @param {number} [update.current] - Current progress value
+   * @param {number} [update.total] - Total progress value
+   * @param {string} [update.message] - Optional status message
+   */
+  updateProgress(update) {
+    if (this.options.quiet) return;
+
+    const { phaseId, current, total, message } = update;
+    const phase = this._getPhase(phaseId);
+    if (!phase) return;
+
+    const prefix = this.formatPhasePrefix(phaseId);
+    const elapsed = Date.now() - (this.phaseStartTime || this.startTime);
+
+    // Status-specific handling for deps phase (must come before generic checks)
+    if (
+      phase.progressType === 'determinate' &&
+      update.status === 'downloading' &&
+      current !== undefined &&
+      total !== undefined
+    ) {
+      // Downloading phase with known total (from collecting count)
+      // Guard against division by zero
+      if (total === 0) {
+        // Fall back to indeterminate spinner if total is invalid
+        if (this.isInteractive) {
+          if (!this.spinner || !this.spinner.isRunning) {
+            this.spinner = new Spinner('Downloading packages');
+            this.spinner.start((frame, label) => {
+              this.updateLine(`${prefix} ${frame} ${label}`);
+            });
+          }
+        }
+        return;
+      }
+
+      const percentage = Math.round((current / total) * 100);
+      const progressBar = renderProgressBar(percentage);
+      const countStr = ` (${current}/${total})`;
+
+      const displayText = `${prefix} Downloading packages ${progressBar} ${percentage}%${countStr}`;
+
+      if (this.isInteractive) {
+        // Stop spinner if running, switch to progress bar
+        if (this.spinner && this.spinner.isRunning) {
+          this.spinner.stop();
+          this.spinner = null;
+        }
+        this.updateLine(displayText);
+      } else {
+        const now = Date.now();
+        if (now - this.lastCIOutput >= this.options.ciOutputInterval) {
+          this.printLine(
+            `${prefix} Downloading packages... ${percentage}%${countStr}`
+          );
+          this.lastCIOutput = now;
+        }
+      }
+    } else if (
+      phase.progressType === 'determinate' &&
+      update.status === 'installing'
+    ) {
+      // Installing phase - show spinner with "Installing packages..." and elapsed time
+      const statusLabel = 'Installing packages';
+
+      if (this.isInteractive) {
+        if (!this.spinner || !this.spinner.isRunning) {
+          this.spinner = new Spinner(statusLabel);
+          this.spinner.start((frame, label) => {
+            const currentElapsed = formatDuration(
+              Date.now() - (this.phaseStartTime || this.startTime)
+            );
+            this.updateLine(`${prefix} ${label} [${currentElapsed}] ${frame}`);
+          });
+        } else {
+          this.spinner.setLabel(statusLabel);
+        }
+      } else {
+        const now = Date.now();
+        if (now - this.lastCIOutput >= this.options.ciOutputInterval) {
+          const elapsedStr = formatDuration(elapsed);
+          this.printLine(`${prefix} ${statusLabel}... [${elapsedStr}]`);
+          this.lastCIOutput = now;
+        }
+      }
+    } else if (
+      phase.progressType === 'determinate' &&
+      current !== undefined &&
+      total !== undefined &&
+      total > 0
+    ) {
+      // Generic determinate progress with known total (e.g., Python runtime download)
+      const rawPercentage = (current / total) * 100;
+      const percentage = Math.max(0, Math.min(100, Math.round(rawPercentage)));
+      const progressBar = renderProgressBar(percentage);
+
+      // Format size display (for downloads) - compact format for 80-column terminals
+      let sizeStr = '';
+      if (total > 1000) {
+        // Likely bytes - use shared unit for compactness
+        const currentBytes = formatBytes(current);
+        const totalBytes = formatBytes(total);
+        // Extract unit from total (e.g., "50.0 MB" -> "MB")
+        const unit = totalBytes.split(' ')[1];
+        const currentVal = currentBytes.split(' ')[0];
+        const totalVal = totalBytes.split(' ')[0];
+        sizeStr = ` (${currentVal}/${totalVal} ${unit})`;
+      } else {
+        // Likely count (packages)
+        sizeStr = ` (${current}/${total})`;
+      }
+
+      const displayText = `${prefix} ${phase.name} ${progressBar} ${percentage}%${sizeStr}`;
+
+      if (this.isInteractive) {
+        // Stop spinner if running (e.g., when deps transitions from installing spinner to determinate progress)
+        if (this.spinner && this.spinner.isRunning) {
+          this.spinner.stop();
+          this.spinner = null;
+        }
+        this.updateLine(displayText);
+      } else {
+        // CI mode: output periodically
+        const now = Date.now();
+        if (now - this.lastCIOutput >= this.options.ciOutputInterval) {
+          this.printLine(`${prefix} ${phase.name}... ${percentage}%${sizeStr}`);
+          this.lastCIOutput = now;
+        }
+      }
+
+      // Verbose mode: show additional details
+      if (this.options.verbose && message) {
+        if (this.isInteractive) {
+          console.log(`\n  → ${message}`);
+        } else {
+          console.log(`    → ${message}`);
+        }
+      }
+    } else if (
+      phase.progressType === 'determinate' &&
+      current !== undefined &&
+      total === undefined
+    ) {
+      // Progress with count but unknown total (e.g., pip collecting dependencies)
+      // Show spinner with count, status, and elapsed time
+      const status = update.status || 'collecting';
+      let statusLabel = phase.name;
+      let countStr = ` (${current} packages)`;
+      const elapsedStr = ` [${formatDuration(elapsed)}]`;
+
+      // Customize display based on pip phase
+      if (status === 'collecting') {
+        statusLabel = 'Collecting dependencies';
+        countStr = ` (${current} packages)`;
+      } else if (status === 'cached') {
+        statusLabel = 'Using cached packages';
+        countStr = ` (${current} cached)`;
+      }
+
+      if (this.isInteractive) {
+        // Use spinner with elapsed time to show activity
+        if (this.spinner && this.spinner.isRunning) {
+          this.spinner.setLabel(`${statusLabel}${countStr}${elapsedStr}`);
+        } else {
+          // Start spinner for count-based progress
+          if (!this.spinner) {
+            this.spinner = new Spinner(
+              `${statusLabel}${countStr}${elapsedStr}`
+            );
+            this.spinner.start((frame, label) => {
+              // Update elapsed time on each frame
+              const currentElapsed = formatDuration(
+                Date.now() - (this.phaseStartTime || this.startTime)
+              );
+              const baseLabel = label.replace(/\s*\[\d+m?\s*\d*s\]$/, ''); // Remove old elapsed
+              this.updateLine(
+                `${prefix} ${baseLabel} [${currentElapsed}] ${frame}`
+              );
+            });
+          } else {
+            this.spinner.setLabel(`${statusLabel}${countStr}${elapsedStr}`);
+          }
+        }
+      } else {
+        // CI mode: output periodically
+        const now = Date.now();
+        if (now - this.lastCIOutput >= this.options.ciOutputInterval) {
+          this.printLine(`${prefix} ${statusLabel}...${countStr}${elapsedStr}`);
+          this.lastCIOutput = now;
+        }
+      }
+
+      // Verbose mode: show package name
+      if (this.options.verbose && message) {
+        if (this.isInteractive) {
+          readline.clearLine(process.stdout, 0);
+          readline.cursorTo(process.stdout, 0);
+          console.log(`  → ${message}`);
+        } else {
+          console.log(`    → ${message}`);
+        }
+      }
+    } else if (phase.progressType === 'indeterminate') {
+      // For indeterminate phases, spinner handles display in interactive mode
+      // In CI mode, output periodically
+      if (!this.isInteractive) {
+        const now = Date.now();
+        if (now - this.lastCIOutput >= this.options.ciOutputInterval) {
+          this.printLine(`${prefix} ${phase.name}...`);
+          this.lastCIOutput = now;
+        }
+      }
+
+      // Verbose mode: show message if provided
+      if (this.options.verbose && message) {
+        if (this.isInteractive) {
+          // Clear spinner line and print message
+          readline.clearLine(process.stdout, 0);
+          readline.cursorTo(process.stdout, 0);
+          console.log(`  → ${message}`);
+        } else {
+          console.log(`    → ${message}`);
+        }
+      }
+    }
+  }
+
+  /**
+   * Mark a phase as complete
+   * @param {string} phaseId - Phase identifier
+   */
+  completePhase(phaseId) {
+    const phase = this._getPhase(phaseId);
+    if (!phase) return;
+
+    // Stop spinner if running
+    if (this.spinner) {
+      this.spinner.stop();
+      this.spinner = null;
+    }
+
+    this.phaseStatuses.set(phaseId, 'completed');
+    const prefix = this.formatPhasePrefix(phaseId);
+
+    this.printLine(`${prefix} ${phase.name} ✓`);
+    this.currentPhase = null;
+    this.phaseStartTime = null;
+  }
+
+  /**
+   * Mark a phase as failed
+   * @param {string} phaseId - Phase identifier
+   * @param {Error} error - The error that occurred
+   */
+  failPhase(phaseId, error) {
+    const phase = this._getPhase(phaseId);
+    if (!phase) return;
+
+    // Stop spinner if running
+    if (this.spinner) {
+      this.spinner.stop();
+      this.spinner = null;
+    }
+
+    this.phaseStatuses.set(phaseId, 'failed');
+
+    // Clear current line and display error
+    if (this.isInteractive) {
+      readline.clearLine(process.stdout, 0);
+      readline.cursorTo(process.stdout, 0);
+    }
+
+    console.log(`\n❌ Failed: ${phase.name}`);
+    console.log(`\nError: ${error.message}`);
+    console.log(`\nSuggested actions:`);
+    console.log(`  • Check your internet connection`);
+    console.log(`  • If behind a proxy, set HTTP_PROXY/HTTPS_PROXY`);
+    console.log(`  • Run with --verbose for detailed output`);
+
+    this.currentPhase = null;
+    this.phaseStartTime = null;
+  }
+
+  /**
+   * Mark a phase as skipped (cache hit)
+   * @param {string} phaseId - Phase identifier
+   */
+  skipPhase(phaseId) {
+    this.phaseStatuses.set(phaseId, 'skipped');
+    // Silent skip per FR-007 - no output
+  }
+
+  /**
+   * Display final completion summary
+   */
+  complete() {
+    if (this.options.quiet) return;
+
+    // Stop any running spinner
+    if (this.spinner) {
+      this.spinner.stop();
+      this.spinner = null;
+    }
+
+    const totalTime = formatDuration(Date.now() - this.startTime);
+    this.printLine(`\n✓ Initialization complete (${totalTime})`);
+  }
+
+  /**
+   * Create a progress callback function for use with initialization functions
+   * @returns {Function} Callback function accepting progress updates
+   */
+  createCallback() {
+    return (update) => {
+      switch (update.type) {
+        case 'start':
+          this.startPhase(update.phaseId);
+          break;
+        case 'progress':
+          this.updateProgress(update);
+          break;
+        case 'complete':
+          this.completePhase(update.phaseId);
+          break;
+        case 'error':
+          this.failPhase(update.phaseId, update.error);
+          break;
+        case 'skip':
+          this.skipPhase(update.phaseId);
+          break;
+      }
+    };
+  }
+}
+
+export default ProgressReporter;