midpoint-cli 1.6.0__py3-none-any.whl

midpoint_cli/prompt/console.py

@@ -0,0 +1,818 @@
+import csv
+import json
+import os
+import sys
+import time
+from abc import ABC, abstractmethod
+from collections import deque
+from collections.abc import Callable, Iterable, Mapping, Sequence
+from datetime import UTC, datetime
+from types import TracebackType
+from typing import Any
+
+from rich.console import Console as RichConsole
+from rich.console import OverflowMethod, RenderableType
+from rich.errors import LiveError
+from rich.markup import escape
+from rich.progress import BarColumn, Progress, ProgressColumn, SpinnerColumn, Task, TaskID
+from rich.status import Status
+from rich.style import StyleType
+from rich.syntax import Syntax
+from rich.table import Column, Table
+from rich.text import Text
+from rich.theme import Theme
+
+from midpoint_cli.client.observer import MidpointCommunicationObserver
+from midpoint_cli.client.progress import ProgressMonitor
+
+
+def is_tty() -> bool:
+    """Check if stdout is connected to a TTY (terminal)."""
+    return hasattr(sys.stdout, 'isatty') and sys.stdout.isatty()
+
+
+def is_stderr_tty() -> bool:
+    """Check if stderr, where messages and progress go, is connected to a TTY (terminal)."""
+    return hasattr(sys.stderr, 'isatty') and sys.stderr.isatty()
+
+
+# Shared outcome → Rich style map. Imported by both `audit ls` rendering
+# and the live audit stream emitted during `task run` / `task wait`.
+OUTCOME_STYLE = {
+    'success': 'green',
+    'fatalerror': 'red',
+    'fatal_error': 'red',
+    'partialerror': 'yellow',
+    'partial_error': 'yellow',
+    'warning': 'yellow',
+    'unknown': 'white',
+    'inprogress': 'cyan',
+    'in_progress': 'cyan',
+}
+
+
+def _outcome_style(outcome: str) -> str:
+    return OUTCOME_STYLE.get(outcome.replace('-', '_').lower(), 'white')
+
+
+def format_audit_event_line(event: Mapping[str, Any]) -> Text:
+    """Render an audit event as a single colored Rich Text line.
+
+    Used by the live stream above the progress bar in `task run`/`task wait`.
+    Plain-text consumers can call ``str(...)`` on the result.
+    """
+    timestamp = (event.get('Timestamp') or '')[11:19]  # HH:MM:SS slice of ISO-8601
+    event_type = event.get('EventType') or ''
+    target = event.get('Target') or ''
+    outcome = event.get('Outcome') or ''
+
+    line = Text()
+    line.append(f'[{timestamp}] ' if timestamp else '')
+    line.append(f'{event_type:<14} ', style='bright_cyan')
+    line.append(f'{target:<38} ', style='blue')
+    if outcome:
+        line.append(outcome, style=_outcome_style(outcome))
+    return line
+
+
+def _get_now_matching_timezone(reference_time: datetime | None) -> datetime:
+    """
+    Get current time matching the timezone awareness of reference_time.
+
+    Args:
+        reference_time: A datetime to match timezone awareness with
+
+    Returns:
+        Current time as timezone-aware if reference is aware, naive otherwise
+    """
+    if reference_time is None:
+        return datetime.now(UTC).replace(tzinfo=None)
+
+    if reference_time.tzinfo is not None and reference_time.tzinfo.utcoffset(reference_time) is not None:
+        # Reference is timezone-aware, return aware current time
+        return datetime.now(UTC)
+    else:
+        # Reference is naive, return naive current time
+        return datetime.now(UTC).replace(tzinfo=None)
+
+
+_THEME = Theme(
+    {
+        'info': 'cyan',
+        'warning': 'yellow',
+        'error': 'bold red',
+        'success': 'bold green',
+        'oid': 'blue',
+        'name': 'bright_cyan',
+        'status_running': 'yellow',
+        'status_success': 'green',
+        'status_error': 'red',
+    }
+)
+
+# Width of a stdout that is not a terminal: wide enough that piped tables are never cut
+# at 80 columns (OIDs shown as "0000…"). Rich tables only take the width their content needs.
+PIPE_WIDTH = 10_000
+
+# Rich Console singletons: data goes to stdout, messages and progress to stderr.
+_console_instance: RichConsole | None = None
+_error_console_instance: RichConsole | None = None
+
+
+def get_console() -> RichConsole:
+    """Get or create the Rich Console for data (tables, object details), writing to stdout."""
+    global _console_instance
+    if _console_instance is None:
+        width = None if is_tty() or os.environ.get('COLUMNS') else PIPE_WIDTH
+        _console_instance = RichConsole(theme=_THEME, highlight=False, width=width)
+    return _console_instance
+
+
+def get_error_console() -> RichConsole:
+    """Get or create the Rich Console for errors, warnings, status and progress, writing to stderr.
+
+    Keeping these off stdout means a redirected or piped command captures data only.
+    """
+    global _error_console_instance
+    if _error_console_instance is None:
+        _error_console_instance = RichConsole(theme=_THEME, highlight=False, stderr=True)
+    return _error_console_instance
+
+
+def print_error(message: str) -> None:
+    """Print an error message on stderr; the message is never read as Rich markup."""
+    get_error_console().print(f'[error]Error:[/error] {escape(message)}', soft_wrap=True)
+
+
+def print_success(message: str) -> None:
+    """Print a success message on stderr."""
+    get_error_console().print(f'[success]✓[/success] {escape(message)}', soft_wrap=True)
+
+
+def print_info(message: str) -> None:
+    """Print an info message on stderr."""
+    get_error_console().print(f'[info]ℹ[/info] {escape(message)}', soft_wrap=True)
+
+
+def print_warning(message: str) -> None:
+    """Print a warning message on stderr."""
+    get_error_console().print(f'[warning]⚠[/warning] {escape(message)}', soft_wrap=True)
+
+
+# Output formats of list commands, selected with the global -o/--output option.
+OUTPUT_TABLE = 'table'
+OUTPUT_JSON = 'json'
+OUTPUT_CSV = 'csv'
+OUTPUT_TSV = 'tsv'
+OUTPUT_FORMATS = (OUTPUT_TABLE, OUTPUT_JSON, OUTPUT_CSV, OUTPUT_TSV)
+
+_output_format = OUTPUT_TABLE
+
+
+def default_output_format() -> str:
+    """A table on a terminal, TSV when stdout is redirected or piped."""
+    return OUTPUT_TABLE if is_tty() else OUTPUT_TSV
+
+
+def set_output_format(output_format: str) -> None:
+    """Select how list commands render their rows."""
+    global _output_format
+    if output_format not in OUTPUT_FORMATS:
+        raise ValueError(f'Unknown output format {output_format!r}, expected one of: {", ".join(OUTPUT_FORMATS)}')
+    _output_format = output_format
+
+
+def get_output_format() -> str:
+    return _output_format
+
+
+def is_machine_output() -> bool:
+    """True when list commands write json, csv or tsv instead of a table."""
+    return _output_format != OUTPUT_TABLE
+
+
+def _column_style(header: str) -> str:
+    lowered = header.lower()
+    if 'oid' in lowered:
+        return 'blue'
+    if 'name' in lowered:
+        return 'bright_cyan'
+    if 'status' in lowered:
+        return 'yellow'
+    return 'white'
+
+
+def _is_identifier_column(header: str) -> bool:
+    """True for columns holding values a user copies into another command (OIDs, event identifiers)."""
+    lowered = header.lower()
+    return 'oid' in lowered or 'identifier' in lowered
+
+
+def _cell(value: Any) -> str:
+    return '' if value is None else str(value).strip()
+
+
+_TSV_ESCAPES = str.maketrans({'\\': '\\\\', '\t': '\\t', '\n': '\\n', '\r': '\\r'})
+
+
+def print_rows(
+    rows: Sequence[Mapping[str, Any]],
+    *,
+    title: str,
+    noun: str,
+    columns: Sequence[str] | None = None,
+    cell_style: Callable[[str, str], str | None] | None = None,
+) -> None:
+    """Render the rows of a list command in the selected output format.
+
+    Every list command goes through here, so all of them honour -o and report totals the
+    same way. Columns default to the keys of the first row. Values are written in full:
+    never parsed as Rich markup, and OIDs are never truncated.
+
+    * table: a Rich table on stdout, then ``Total: N <noun>`` (or ``No <noun> found``) on
+      stderr. ``cell_style(column, value)`` may return a style for a single cell.
+    * json: an array of objects keyed by column name.
+    * csv: RFC 4180, with a header line.
+    * tsv: a header line, then one line per row; backslash, tab, newline and carriage return
+      in a value are written as ``\\\\``, ``\\t``, ``\\n`` and ``\\r``.
+
+    Machine formats write nothing on stderr: an empty result is ``[]`` or no data lines.
+    """
+    headers = list(columns) if columns is not None else (list(rows[0].keys()) if rows else [])
+    values = [[_cell(row.get(h)) for h in headers] for row in rows]
+    output_format = get_output_format()
+
+    if output_format == OUTPUT_JSON:
+        records = [dict(zip(headers, row, strict=True)) for row in values]
+        sys.stdout.write(json.dumps(records, indent=2, ensure_ascii=False) + '\n')
+    elif output_format == OUTPUT_CSV:
+        writer = csv.writer(sys.stdout, lineterminator='\n')
+        if headers:
+            writer.writerow(headers)
+        writer.writerows(values)
+    elif output_format == OUTPUT_TSV:
+        for line in [headers, *values] if headers else values:
+            sys.stdout.write('\t'.join(value.translate(_TSV_ESCAPES) for value in line) + '\n')
+    elif not rows:
+        print_info(f'No {noun} found')
+    else:
+        table = create_table(title=title)
+        for header in headers:
+            # Fold rather than truncate, so a narrow terminal still shows whole OIDs and identifiers.
+            overflow: OverflowMethod = 'fold' if _is_identifier_column(header) else 'ellipsis'
+            table.add_column(header, style=_column_style(header), overflow=overflow)
+        for row in values:
+            cells: list[RenderableType] = []
+            for header, value in zip(headers, row, strict=True):
+                style = cell_style(header, value) if cell_style is not None else None
+                cells.append(Text(value, style=style) if style else value)
+            table.add_row(*cells)
+        get_console().print(table)
+        print_info(f'Total: {len(rows)} {noun}')
+
+
+# Columns of a detail view (and of `info`) in csv and tsv.
+DETAIL_COLUMNS = ('Property', 'Value')
+
+
+def _detail_value(value: Any) -> Any:
+    """A detail value for JSON: strings, and lists and objects of them, like print_rows cells."""
+    if isinstance(value, Mapping):
+        return {str(key): _detail_value(item) for key, item in value.items()}
+    if isinstance(value, list | tuple):
+        return [_detail_value(item) for item in value]
+    return _cell(value)
+
+
+def _flatten_detail(path: str, value: Any, rows: list[dict[str, str]]) -> None:
+    """Append one Property/Value row per scalar of value, named by its path (Roles[0].Name)."""
+    if isinstance(value, Mapping):
+        for key, item in value.items():
+            _flatten_detail(f'{path}.{key}' if path else str(key), item, rows)
+    elif isinstance(value, list | tuple):
+        for index, item in enumerate(value):
+            _flatten_detail(f'{path}[{index}]', item, rows)
+    else:
+        rows.append({DETAIL_COLUMNS[0]: path, DETAIL_COLUMNS[1]: _cell(value)})
+
+
+def print_details(details: Sequence[Mapping[str, Any]], *, as_list: bool) -> None:
+    """Render the objects of a detail view (user get, task get, ...) in a machine format.
+
+    Detail views print their own Rich tables; this is for json, csv and tsv only.
+
+    * json: one object, or an array of objects when ``as_list`` (the command took several
+      arguments). Values are strings; related records (a user's roles, a task's actions) are
+      arrays of objects under their own key.
+    * csv, tsv: ``Property``/``Value`` rows through print_rows, one per value, the objects one
+      after the other. Values of related records are named by their path, e.g.
+      ``Roles[0].Name``; a repeated property is ``name[0]``, ``name[1]``.
+
+    Nothing is written for a single object that could not be read.
+    """
+    if get_output_format() == OUTPUT_TABLE:
+        raise ValueError('print_details renders machine formats only')
+    if not details and not as_list:
+        return
+    if get_output_format() == OUTPUT_JSON:
+        records = [_detail_value(detail) for detail in details]
+        payload = records if as_list else records[0]
+        sys.stdout.write(json.dumps(payload, indent=2, ensure_ascii=False) + '\n')
+        return
+    rows: list[dict[str, str]] = []
+    for detail in details:
+        _flatten_detail('', detail, rows)
+    print_rows(rows, title='', noun='properties', columns=DETAIL_COLUMNS)
+
+
+def print_xml(xml_text: str, line_numbers: bool = False) -> None:
+    """Print XML with syntax highlighting."""
+    if is_tty():
+        syntax = Syntax(xml_text, 'xml', theme='monokai', line_numbers=line_numbers)
+        get_console().print(syntax, markup=False, soft_wrap=True)
+    else:
+        # Piped output must be byte-identical to what the server returned:
+        # no markup interpretation, no wrapping at the console width.
+        sys.stdout.write(xml_text if xml_text.endswith('\n') else xml_text + '\n')
+
+
+class PlainTextTable(Table):
+    """Rich table whose plain string cells are rendered literally.
+
+    Cell values usually come from the server (names, descriptions, ...) and may
+    contain square brackets; they must never be interpreted as Rich markup.
+    Callers wanting styled cells pass a ``rich.text.Text`` instead.
+    """
+
+    def add_row(
+        self,
+        *renderables: RenderableType | None,
+        style: StyleType | None = None,
+        end_section: bool = False,
+    ) -> None:
+        cells = [Text(cell) if isinstance(cell, str) else cell for cell in renderables]
+        super().add_row(*cells, style=style, end_section=end_section)
+
+
+def create_table(title: str | None = None, show_header: bool = True) -> Table:
+    """Create a Rich table with consistent styling; string cells are not parsed as markup."""
+    table = PlainTextTable(title=title, show_header=show_header, header_style='bold cyan', border_style='blue')
+    return table
+
+
+def _format_clock(seconds: float) -> str:
+    """Format a duration as H:MM:SS, or M:SS under an hour."""
+    hours, remainder = divmod(int(seconds), 3600)
+    minutes, secs = divmod(remainder, 60)
+    return f'{hours:d}:{minutes:02d}:{secs:02d}' if hours > 0 else f'{minutes:d}:{secs:02d}'
+
+
+def _status_print(*values: object, end: str = '\n', flush: bool = False) -> None:
+    """print() for waiting indicators and progress, which belong on stderr with the other messages."""
+    print(*values, end=end, flush=flush, file=sys.stderr)
+
+
+class Spinner:
+    """Reusable animated spinner using Rich for TTY/console output."""
+
+    def __init__(self) -> None:
+        self._console = get_error_console()
+        self._status: Status | None = None
+        self._message = ''
+
+    def start(self, message_callback: Callable[[str], str]) -> None:
+        """
+        Start spinner animation using Rich status.
+
+        Args:
+            message_callback: Function that receives spinner frame and returns full message to display
+        """
+        # Rich handles the spinner frame internally, so we just need the base message
+        self._message = message_callback('')
+        if is_stderr_tty():
+            status = self._console.status(self._message, spinner='dots')
+            try:
+                status.__enter__()
+            except LiveError:
+                # Rich before 14 allows one live display per console: while a task progress
+                # bar is shown, the bar's own spinner keeps moving instead.
+                return
+            self._status = status
+        else:
+            # For non-TTY, just print the message
+            _status_print(self._message, end='', flush=True)
+
+    def update(self, message: str) -> None:
+        """Change the message shown next to the spinner (TTY only)."""
+        self._message = message
+        if self._status:
+            self._status.update(message)
+
+    def stop(self, clear_length: int = 80) -> None:
+        """
+        Stop the spinner and clear the line.
+
+        Args:
+            clear_length: Number of characters to clear (default 80)
+        """
+        if self._status:
+            self._status.__exit__(None, None, None)
+            self._status = None
+        elif not is_stderr_tty():
+            # Clear the non-TTY message
+            _status_print('\r' + ' ' * clear_length + '\r', end='', flush=True)
+
+
+class WaitingIndicator(ABC):
+    """Abstract base class for waiting indicators."""
+
+    @abstractmethod
+    def start(self) -> None:
+        """Start displaying the waiting indicator."""
+        pass
+
+    @abstractmethod
+    def update(self) -> None:
+        """Update the waiting indicator (called on each retry)."""
+        pass
+
+    @abstractmethod
+    def stop(self) -> None:
+        """Stop displaying the waiting indicator."""
+        pass
+
+
+class SpinnerWaitingIndicator(WaitingIndicator):
+    """Animated spinner indicator for TTY/console output, with the retry count and time waited."""
+
+    MESSAGE = 'Waiting for http service'
+
+    def __init__(self) -> None:
+        self._spinner = Spinner()
+        self._retries = 0
+        self._started_at = 0.0
+
+    def start(self) -> None:
+        """Start the animated spinner."""
+        self._retries = 0
+        self._started_at = time.monotonic()
+        self._spinner.start(lambda frame: f'[info]{self.MESSAGE}...[/info]')
+
+    def update(self) -> None:
+        """Count a retry and show it with the time waited so far."""
+        self._retries += 1
+        waited = _format_clock(time.monotonic() - self._started_at)
+        self._spinner.update(f'[info]{self.MESSAGE}...[/info] [dim]retry {self._retries} · {waited}[/dim]')
+
+    def stop(self) -> None:
+        """Stop the animated spinner and clear the line."""
+        self._spinner.stop(clear_length=40)
+
+
+class DottedWaitingIndicator(WaitingIndicator):
+    """Classic dotted indicator for file redirection/non-TTY output."""
+
+    def start(self) -> None:
+        """Print initial waiting message."""
+        _status_print('Waiting for http service...', end='', flush=True)
+
+    def update(self) -> None:
+        """Print a dot on each update."""
+        _status_print('.', end='', flush=True)
+
+    def stop(self) -> None:
+        """Print newline to finish the line."""
+        _status_print('', flush=True)
+
+
+class ConsoleDisplay(MidpointCommunicationObserver):
+    def __init__(self) -> None:
+        self._waiting = False
+        # Detect if output is a TTY (console) or file redirection
+        self._indicator = SpinnerWaitingIndicator() if is_stderr_tty() else DottedWaitingIndicator()
+
+    def on_http_error(self) -> None:
+        if not self._waiting:
+            self._indicator.start()
+            self._waiting = True
+        else:
+            self._indicator.update()
+
+    def on_http_success(self) -> None:
+        if self._waiting:
+            self._indicator.stop()
+            self._waiting = False
+
+    def on_http_failure(self) -> None:
+        # Retries gave up: end the indicator so the error that follows stands on its own line.
+        self.on_http_success()
+
+    def on_http_call(self) -> None:
+        pass
+
+
+# Progress Monitors
+
+
+class CustomTimeElapsedColumn(ProgressColumn):
+    """Custom time elapsed column that supports a start time offset."""
+
+    def __init__(self, task_start_time: datetime | None = None) -> None:
+        super().__init__()
+        self._task_start_time = task_start_time
+        self._offset_seconds = 0.0
+        if task_start_time:
+            # Calculate how many seconds have elapsed since task started
+            now = _get_now_matching_timezone(task_start_time)
+            self._offset_seconds = (now - task_start_time).total_seconds()
+
+    def render(self, task: Task) -> Text:
+        """Render elapsed time including the offset from task start."""
+        elapsed = task.finished_time if task.finished else task.elapsed
+        if elapsed is None:
+            elapsed = 0.0
+
+        # Add the offset to show total time since task started
+        return Text(_format_clock(elapsed + self._offset_seconds), style='progress.elapsed')
+
+
+# Progress marks: one per processed item, a distinct one for each failure.
+SUCCESS_MARK = '.'
+FAILURE_MARK = 'F'
+
+
+class OutcomeMarks:
+    """Turn progress and failure counts, polled from the server, into one mark per processed item.
+
+    The server only reports totals: the progress (items processed) and the failed actions of
+    the task statistics. The items processed since the last poll are marked as failures up to
+    the number of new failures, the others as successes. Failures beyond the new items (one
+    item may fail several actions) are marked on later items, so no failure goes unmarked
+    while items keep coming.
+    """
+
+    def __init__(self) -> None:
+        self.progress = 0
+        self.failures_marked = 0
+
+    def advance_to(self, progress: int, failure_count: int) -> list[bool]:
+        """The marks of the items processed since the last call, True for a failure."""
+        new_items = max(progress - self.progress, 0)
+        failures = min(max(failure_count - self.failures_marked, 0), new_items)
+        self.progress += new_items
+        self.failures_marked += failures
+        return [False] * (new_items - failures) + [True] * failures
+
+
+class DottedProgressMonitor(ProgressMonitor):
+    """Dotted progress monitor for file redirection/non-TTY output.
+
+    Prints one mark per processed item: ``icon`` for a success, ``failure_icon`` for a failure.
+    """
+
+    def __init__(self, width: int = 80, icon: str = SUCCESS_MARK, failure_icon: str = FAILURE_MARK) -> None:
+        self._progress = 0
+        self._success_count = 0
+        self._failure_count = 0
+        self._width = width
+        self._icon = icon
+        self._failure_icon = failure_icon
+        self._marks = OutcomeMarks()
+        self._task_start_time: datetime | None = None
+        self._start_time = time.time()
+        # Set when log_event has interrupted the dot row; next advance must
+        # re-emit the "Progress: " prefix on a new line.
+        self._needs_progress_prefix = False
+
+    def set_task_start_time(self, start_time: datetime | None) -> None:
+        """Set the task's original start time for elapsed time calculation."""
+        self._task_start_time = start_time
+
+    def update(self, progress: int) -> None:
+        self.update_with_stats(progress, self._success_count, self._failure_count)
+
+    def update_with_stats(self, progress: int, success_count: int = 0, failure_count: int = 0) -> None:
+        """Update with progress and success/failure statistics, marking each new item."""
+        self._success_count = success_count
+        self._failure_count = failure_count
+        self._marks.progress = self._progress
+        for failed in self._marks.advance_to(progress, failure_count):
+            self.advance(self._failure_icon if failed else self._icon)
+
+    def log_event(self, event: Mapping[str, Any]) -> None:
+        # Break out of the in-flight dot row so the event line stands on its own.
+        if self._progress > 0 and self._progress % self._width != 0:
+            _status_print()
+        _status_print(str(format_audit_event_line(event)), flush=True)
+        if self._progress > 0:
+            self._needs_progress_prefix = True
+
+    def advance(self, icon: str | None = None) -> None:
+        if self._needs_progress_prefix:
+            _status_print('Progress: ', end='', flush=True)
+            self._needs_progress_prefix = False
+        elif self._progress % self._width == 0:
+            if self._progress > 0:
+                # Include stats in the progress line if available
+                if self._success_count > 0 or self._failure_count > 0:
+                    _status_print(
+                        f' {self._progress:7d} (Progress: {self._progress}, Success: {self._success_count}, Errors: {self._failure_count})'
+                    )
+                else:
+                    _status_print(f' {self._progress:7d}')
+
+            _status_print('Progress: ', end='', flush=True)
+
+        _status_print(icon or self._icon, end='', flush=True)
+        self._progress += 1
+
+    def __enter__(self) -> 'DottedProgressMonitor':
+        self._start_time = time.time()
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        _status_print()
+        # Build summary message with statistics if available
+        if self._success_count > 0 or self._failure_count > 0:
+            summary = (
+                f'Total progress: {self._progress} (Success: {self._success_count}, Errors: {self._failure_count})'
+            )
+        else:
+            summary = f'Total progress: {self._progress}'
+
+        # Add elapsed time if we have a task start time
+        if self._task_start_time:
+            # Calculate total time since task started
+            now = _get_now_matching_timezone(self._task_start_time)
+            total_elapsed = (now - self._task_start_time).total_seconds()
+            if self._success_count > 0 or self._failure_count > 0:
+                summary = f'Total progress: {self._progress} (Success: {self._success_count}, Errors: {self._failure_count}, Task running for {self._format_elapsed(total_elapsed)})'
+            else:
+                summary = f'Total progress: {self._progress} (Task running for {self._format_elapsed(total_elapsed)})'
+
+        _status_print(summary)
+
+    def _format_elapsed(self, seconds: float) -> str:
+        """Format elapsed time as HH:MM:SS or MM:SS."""
+        return _format_clock(seconds)
+
+
+def outcome_marks_text(marks: Iterable[bool]) -> Text:
+    """Render progress marks: a green dot per success, a bold red F per failure."""
+    text = Text()
+    for failed in marks:
+        if failed:
+            text.append(FAILURE_MARK, style='bold red')
+        else:
+            text.append(SUCCESS_MARK, style='green')
+    return text
+
+
+class RecentOutcomesColumn(ProgressColumn):
+    """The marks of the most recently processed items, read from the ``marks`` task field."""
+
+    def __init__(self, width: int) -> None:
+        super().__init__(table_column=Column(no_wrap=True, min_width=width))
+
+    def render(self, task: Task) -> Text:
+        return outcome_marks_text(task.fields.get('marks', ()))
+
+
+class ProcessedCountColumn(ProgressColumn):
+    """Items processed: ``42``, or ``42/100 42%`` when the task knows how many to expect."""
+
+    def render(self, task: Task) -> Text:
+        completed = int(task.completed)
+        if task.total:
+            percent = min(100, int(completed * 100 / task.total))
+            return Text(f'{completed}/{int(task.total)} {percent:>3d}%', style='progress.download')
+        return Text(str(completed), style='progress.download')
+
+
+class OutcomeCountsColumn(ProgressColumn):
+    """Successes and failures so far, from the ``success`` and ``failure`` task fields."""
+
+    def render(self, task: Task) -> Text:
+        return outcome_counts_text(task.fields.get('success', 0), task.fields.get('failure', 0))
+
+
+def outcome_counts_text(success_count: int, failure_count: int) -> Text:
+    """``✓ 40 ✗ 2``: successes in green, failures in red, or dimmed while there are none."""
+    text = Text()
+    if success_count or failure_count:
+        text.append(f'✓ {success_count}', style='green')
+        text.append(' ')
+        text.append(f'✗ {failure_count}', style='bold red' if failure_count else 'dim')
+    return text
+
+
+class AnimatedProgressMonitor(ProgressMonitor):
+    """Animated progress monitor using Rich Progress for TTY/console output.
+
+    One line on stderr: a spinner, a bar (filled against the expected total when the task
+    has one, pulsing otherwise), the items processed, the success and failure counts, the
+    marks of the latest items and the time since the task started. It is replaced by a
+    summary line when the task ends.
+    """
+
+    # Number of recent item marks shown next to the bar.
+    RECENT_MARKS = 16
+    BAR_WIDTH = 24
+
+    def __init__(self) -> None:
+        self._progress_value = 0
+        self._success_count = 0
+        self._failure_count = 0
+        self._expected_total: int | None = None
+        self._progress: Progress | None = None
+        self._task: TaskID | None = None
+        self._console = get_error_console()
+        self._task_start_time: datetime | None = None
+        self._marks = OutcomeMarks()
+        self._recent_marks: deque[bool] = deque(maxlen=self.RECENT_MARKS)
+
+    def set_task_start_time(self, start_time: datetime | None) -> None:
+        """Set the task's original start time for elapsed time calculation."""
+        self._task_start_time = start_time
+
+    def set_expected_total(self, total: int | None) -> None:
+        self._expected_total = total
+        if self._progress is not None and self._task is not None:
+            self._progress.update(self._task, total=total)
+
+    def update(self, progress: int) -> None:
+        self.update_with_stats(progress, self._success_count, self._failure_count)
+
+    def update_with_stats(self, progress: int, success_count: int = 0, failure_count: int = 0) -> None:
+        """Update with progress and success/failure statistics."""
+        self._progress_value = progress
+        self._success_count = success_count
+        self._failure_count = failure_count
+        self._recent_marks.extend(self._marks.advance_to(progress, failure_count))
+        if self._progress is not None and self._task is not None:
+            self._progress.update(
+                self._task,
+                completed=progress,
+                success=success_count,
+                failure=failure_count,
+                marks=tuple(self._recent_marks),
+            )
+
+    def log_event(self, event: Mapping[str, Any]) -> None:
+        # Rich Progress.console.print weaves the line above the live progress bar
+        # without breaking the spinner's redraw.
+        if self._progress is not None:
+            self._progress.console.print(format_audit_event_line(event))
+        else:
+            # Without a live display the line is a plain stderr message: never wrapped.
+            self._console.print(format_audit_event_line(event), soft_wrap=True)
+
+    def __enter__(self) -> 'AnimatedProgressMonitor':
+        if is_stderr_tty():
+            self._progress = Progress(
+                SpinnerColumn(),
+                BarColumn(bar_width=self.BAR_WIDTH),
+                ProcessedCountColumn(),
+                OutcomeCountsColumn(),
+                RecentOutcomesColumn(self.RECENT_MARKS),
+                CustomTimeElapsedColumn(self._task_start_time),
+                console=self._console,
+                transient=True,
+            )
+            self._progress.__enter__()
+            self._task = self._progress.add_task('Processing', total=self._expected_total)
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        if self._progress:
+            self._progress.__exit__(exc_type, exc_val, exc_tb)
+        self._console.print(self._summary(), soft_wrap=True)
+
+    def _summary(self) -> Text:
+        """``Total progress: 40 (✓ 38 ✗ 2) (Task running for 0:31)``."""
+        summary = Text(f'Total progress: {self._progress_value}')
+        if self._expected_total:
+            summary.append(f'/{self._expected_total}')
+        if self._success_count > 0 or self._failure_count > 0:
+            summary.append(' (')
+            summary.append_text(outcome_counts_text(self._success_count, self._failure_count))
+            summary.append(')')
+        if self._task_start_time:
+            now = _get_now_matching_timezone(self._task_start_time)
+            summary.append(f' (Task running for {_format_clock((now - self._task_start_time).total_seconds())})')
+        return summary
+
+
+def create_progress_monitor() -> ProgressMonitor:
+    """The progress monitor of a task followed to completion: animated on a terminal, dotted otherwise."""
+    return AnimatedProgressMonitor() if is_stderr_tty() else DottedProgressMonitor()