polling.ts

/**
 * Generic Polling Utility
 *
 * Provides a reusable polling mechanism with progress spinner display.
 * Used by commands that need to wait for async operations to complete.
 */

import { TimeoutError } from "./errors.js";
import {
  formatProgressLine,
  truncateProgressMessage,
} from "./formatters/seer.js";

/** Default polling interval in milliseconds */
const DEFAULT_POLL_INTERVAL_MS = 1000;

/** Animation interval for spinner updates — 50ms gives 20fps, matching the ora/inquirer standard */
const ANIMATION_INTERVAL_MS = 50;

/** Default timeout in milliseconds (6 minutes) */
const DEFAULT_TIMEOUT_MS = 360_000;

/**
 * Options for the generic poll function.
 */
export type PollOptions<T> = {
  /** Function to fetch current state */
  fetchState: () => Promise<T | null>;
  /** Predicate to determine if polling should stop */
  shouldStop: (state: T) => boolean;
  /** Get progress message from state */
  getProgressMessage: (state: T) => string;
  /** Suppress progress output (JSON mode) */
  json?: boolean;
  /** Poll interval in ms (default: 1000) */
  pollIntervalMs?: number;
  /** Timeout in ms (default: 360000 / 6 min) */
  timeoutMs?: number;
  /** Custom timeout message */
  timeoutMessage?: string;
  /** Actionable hint appended to the TimeoutError (e.g., "Run the command again…") */
  timeoutHint?: string;
  /** Initial progress message */
  initialMessage?: string;
};

/**
 * Generic polling function with animated progress display.
 *
 * Polls the fetchState function until shouldStop returns true or timeout is reached.
 * Displays an animated spinner with progress messages when not in JSON mode.
 * Animation runs at 50ms intervals (20fps) independently of polling frequency.
 *
 * @typeParam T - The type of state being polled
 * @param options - Polling configuration
 * @returns The final state when shouldStop returns true
 * @throws {TimeoutError} When timeout is reached before shouldStop returns true
 *
 * @example
 * ```typescript
 * const finalState = await poll({
 *   fetchState: () => getAutofixState(org, issueId),
 *   shouldStop: (state) => isTerminalStatus(state.status),
 *   getProgressMessage: (state) => state.message ?? "Processing...",
 *   json: false,
 *   timeoutMs: 360_000,
 *   timeoutMessage: "Operation timed out after 6 minutes.",
 * });
 * ```
 */
export async function poll<T>(options: PollOptions<T>): Promise<T> {
  const {
    fetchState,
    shouldStop,
    getProgressMessage,
    json = false,
    pollIntervalMs = DEFAULT_POLL_INTERVAL_MS,
    timeoutMs = DEFAULT_TIMEOUT_MS,
    timeoutMessage = "Operation timed out after 6 minutes. Try again or check the Sentry web UI.",
    timeoutHint,
    initialMessage = "Waiting for operation to start...",
  } = options;

  const startTime = Date.now();
  const spinner = json ? null : startSpinner(initialMessage);

  try {
    while (Date.now() - startTime < timeoutMs) {
      const state = await fetchState();

      if (state) {
        // Always call getProgressMessage (callers may rely on the callback
        // being invoked), but only forward the result to the spinner.
        const msg = getProgressMessage(state);
        spinner?.setMessage(msg);

        if (shouldStop(state)) {
          return state;
        }
      }

      await Bun.sleep(pollIntervalMs);
    }

    throw new TimeoutError(timeoutMessage, timeoutHint);
  } finally {
    spinner?.stop();
    if (!json) {
      process.stderr.write("\n");
    }
  }
}

/**
 * Start an animated spinner that writes progress to stderr.
 *
 * Returns a controller with `setMessage` to update the displayed text
 * and `stop` to halt the animation. Writes directly to `process.stderr`.
 */
function startSpinner(initialMessage: string): {
  setMessage: (msg: string) => void;
  stop: () => void;
} {
  let currentMessage = initialMessage;
  let tick = 0;
  let stopped = false;

  const scheduleFrame = () => {
    if (stopped) {
      return;
    }
    const display = truncateProgressMessage(currentMessage);
    process.stderr.write(`\r\x1b[K${formatProgressLine(display, tick)}`);
    tick += 1;
    setTimeout(scheduleFrame, ANIMATION_INTERVAL_MS).unref();
  };
  scheduleFrame();

  return {
    setMessage: (msg: string) => {
      currentMessage = msg;
    },
    stop: () => {
      stopped = true;
    },
  };
}

/**
 * Options for {@link withProgress}.
 */
export type WithProgressOptions = {
  /** Initial spinner message */
  message: string;
  /** Suppress progress output (JSON mode). When true, the operation runs
   *  without a spinner — matching the behaviour of {@link poll}. */
  json?: boolean;
};

/**
 * Run an async operation with an animated spinner on stderr.
 *
 * The spinner uses the same braille frames as the Seer polling spinner,
 * giving a consistent look across all CLI commands. Progress output goes
 * to stderr, so it never contaminates stdout (safe to use alongside JSON output).
 *
 * When `options.json` is true the spinner is suppressed entirely, matching
 * the behaviour of {@link poll}. This avoids noisy ANSI escape sequences on
 * stderr when agents or CI pipelines consume `--json` output.
 *
 * The callback receives a `setMessage` function to update the displayed
 * message as work progresses (e.g. to show page counts during pagination).
 * Progress is automatically cleared when the operation completes.
 *
 * @param options - Spinner configuration
 * @param fn - Async operation to run; receives `setMessage` to update the displayed text
 * @returns The value returned by `fn`
 *
 * @example
 * ```typescript
 * const result = await withProgress(
 *   { message: "Fetching issues..." },
 *   async (setMessage) => {
 *     const data = await fetchWithPages({
 *       onPage: (fetched, total) => setMessage(`Fetching issues... ${fetched}/${total}`),
 *     });
 *     return data;
 *   }
 * );
 * ```
 */
export async function withProgress<T>(
  options: WithProgressOptions,
  fn: (setMessage: (msg: string) => void) => Promise<T>
): Promise<T> {
  if (options.json) {
    // JSON mode: skip the spinner entirely, pass a no-op setMessage
    return fn(() => {
      /* spinner suppressed in JSON mode */
    });
  }

  const spinner = startSpinner(options.message);

  try {
    return await fn(spinner.setMessage);
  } finally {
    spinner.stop();
    process.stderr.write("\r\x1b[K");
  }
}