wafer-core 0.1.37__py3-none-any.whl → 0.1.39__py3-none-any.whl

wafer_core/rollouts/_pytui/console.py

@@ -0,0 +1,291 @@
+"""Console: unified output manager coordinating spinners with logging.
+
+The problem: Spinner animations and log messages both write to stderr.
+When they interleave, output gets corrupted. Console solves this by:
+1. Owning the spinner lifecycle
+2. Providing a logging handler that pauses the spinner before emitting
+
+Usage:
+    import logging
+    from pytui import Console
+
+    logger = logging.getLogger(__name__)
+    console = Console()
+    console.install_logging_handler(logger)
+
+    with console.spinner("Provisioning..."):
+        # Any logger.info/warning/error calls here will:
+        # 1. Pause the spinner (clear its line)
+        # 2. Print the log message on its own line
+        # 3. Resume the spinner below
+        result = do_stuff_that_logs()
+    # Shows: ✓ Provisioning...
+
+Three levels of granularity (Casey Muratori's rule: no API holes):
+    - Low-level: pause_spinner(), resume_spinner(), write()
+    - Mid-level: status() for one-off messages
+    - High-level: spinner() context manager
+"""
+
+from __future__ import annotations
+
+import itertools
+import logging
+import sys
+import threading
+import time
+from collections.abc import Iterator
+from contextlib import contextmanager
+from typing import TextIO
+
+BRAILLE_FRAMES = ("⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏")
+
+
+class Console:
+    """Unified output manager coordinating spinners with logging.
+
+    Args:
+        output: Stream to write to. Defaults to stderr (matches logging convention).
+        spinner_interval: Seconds between spinner frame updates.
+    """
+
+    def __init__(
+        self,
+        output: TextIO = sys.stderr,
+        spinner_interval: float = 0.08,
+    ) -> None:
+        self._output = output
+        self._spinner_interval = spinner_interval
+        self._lock = threading.Lock()
+
+        # Active spinner state (immediate mode: only one at a time)
+        self._spinner_message: str | None = None
+        self._spinner_frame_iter: Iterator[str] | None = None
+        self._spinner_stop: threading.Event | None = None
+        self._spinner_thread: threading.Thread | None = None
+        self._spinner_paused: bool = False
+        self._spinner_start_time: float | None = None
+
+        # Installed logging handlers (for cleanup)
+        self._handlers: list[tuple[logging.Logger, logging.Handler]] = []
+
+    # ─── Low-level API ─────────────────────────────────────────────────────
+
+    def write(self, text: str) -> None:
+        """Write text to output stream. Thread-safe."""
+        with self._lock:
+            self._output.write(text)
+            self._output.flush()
+
+    def write_line(self, text: str) -> None:
+        """Write a complete line to output. Coordinates with active spinner."""
+        with self._lock:
+            if self._spinner_message is not None and not self._spinner_paused:
+                # Clear spinner line, write message, redraw spinner
+                self._output.write(f"\r\033[K{text}\n")
+                frame = next(self._spinner_frame_iter) if self._spinner_frame_iter else "⠋"
+                self._output.write(f"{frame} {self._spinner_message}")
+                self._output.flush()
+            else:
+                self._output.write(f"{text}\n")
+                self._output.flush()
+
+    def pause_spinner(self) -> None:
+        """Pause the spinner animation and clear its line.
+
+        Used by ConsoleHandler before emitting log records.
+        """
+        with self._lock:
+            if self._spinner_message is not None and not self._spinner_paused:
+                self._spinner_paused = True
+                self._output.write("\r\033[K")
+                self._output.flush()
+
+    def resume_spinner(self) -> None:
+        """Resume the spinner animation.
+
+        Used by ConsoleHandler after emitting log records.
+        """
+        with self._lock:
+            if self._spinner_message is not None and self._spinner_paused:
+                self._spinner_paused = False
+                frame = next(self._spinner_frame_iter) if self._spinner_frame_iter else "⠋"
+                self._output.write(f"{frame} {self._spinner_message}")
+                self._output.flush()
+
+    # ─── Mid-level API ─────────────────────────────────────────────────────
+
+    def status(self, text: str, success: bool = True) -> None:
+        """Print a status line with ✓ or ✗ prefix."""
+        mark = "✓" if success else "✗"
+        self.write_line(f"{mark} {text}")
+
+    # ─── High-level API ────────────────────────────────────────────────────
+
+    @contextmanager
+    def spinner(self, message: str) -> Iterator[SpinnerHandle]:
+        """Context manager for spinner animation.
+
+        Any log messages emitted inside the block will be coordinated:
+        the spinner pauses, the message prints, the spinner resumes.
+
+        Args:
+            message: Text to display next to the spinner.
+
+        Yields:
+            SpinnerHandle with update() method to change the message.
+
+        Example:
+            with console.spinner("Loading...") as s:
+                s.update("Loading... 50%")
+                do_work()
+            # Shows: ✓ Loading... 50%
+        """
+        assert self._spinner_message is None, "Cannot nest spinners"
+
+        handle = SpinnerHandle(self)
+        self._spinner_message = message
+        self._spinner_frame_iter = itertools.cycle(BRAILLE_FRAMES)
+        self._spinner_stop = threading.Event()
+        self._spinner_paused = False
+        self._spinner_start_time = time.time()
+
+        self._spinner_thread = threading.Thread(target=self._spin_loop, daemon=True)
+        self._spinner_thread.start()
+
+        exc_info: BaseException | None = None
+        try:
+            yield handle
+        except BaseException as e:
+            exc_info = e
+            raise
+        finally:
+            # Stop spinner thread
+            assert self._spinner_stop is not None
+            self._spinner_stop.set()
+            if self._spinner_thread is not None:
+                self._spinner_thread.join()
+                self._spinner_thread = None
+
+            # Print final status with elapsed time
+            final_message = self._spinner_message
+            success = exc_info is None
+            mark = "✓" if success else "✗"
+            elapsed = self._format_elapsed(time.time() - self._spinner_start_time)
+
+            with self._lock:
+                self._output.write(f"\r\033[K{mark} {final_message} ({elapsed})\n")
+                self._output.flush()
+
+            # Clear spinner state
+            self._spinner_message = None
+            self._spinner_frame_iter = None
+            self._spinner_stop = None
+            self._spinner_paused = False
+            self._spinner_start_time = None
+
+    def _spin_loop(self) -> None:
+        """Background thread that animates the spinner."""
+        assert self._spinner_stop is not None
+        assert self._spinner_frame_iter is not None
+        assert self._spinner_start_time is not None
+
+        while not self._spinner_stop.is_set():
+            with self._lock:
+                if not self._spinner_paused and self._spinner_message is not None:
+                    frame = next(self._spinner_frame_iter)
+                    elapsed = self._format_elapsed(time.time() - self._spinner_start_time)
+                    self._output.write(f"\r\033[K{frame} {self._spinner_message} ({elapsed})")
+                    self._output.flush()
+            time.sleep(self._spinner_interval)
+
+    @staticmethod
+    def _format_elapsed(seconds: float) -> str:
+        """Format elapsed time as human-readable string (e.g., '1m7s', '45s')."""
+        seconds = int(seconds)
+        if seconds < 60:
+            return f"{seconds}s"
+        minutes = seconds // 60
+        secs = seconds % 60
+        if minutes < 60:
+            return f"{minutes}m{secs}s" if secs else f"{minutes}m"
+        hours = minutes // 60
+        mins = minutes % 60
+        if secs:
+            return f"{hours}h{mins}m{secs}s"
+        elif mins:
+            return f"{hours}h{mins}m"
+        else:
+            return f"{hours}h"
+
+    # ─── Logging Integration ───────────────────────────────────────────────
+
+    def install_logging_handler(
+        self,
+        logger: logging.Logger | None = None,
+        level: int = logging.DEBUG,
+        fmt: str = "[%(asctime)s] %(levelname)s: %(message)s",
+        datefmt: str = "%H:%M:%S",
+    ) -> logging.Handler:
+        """Install a logging handler that coordinates with the spinner.
+
+        Args:
+            logger: Logger to attach to. Defaults to root logger.
+            level: Minimum log level to handle.
+            fmt: Log message format string.
+            datefmt: Date format for %(asctime)s.
+
+        Returns:
+            The installed handler (for advanced use cases).
+        """
+        if logger is None:
+            logger = logging.getLogger()
+
+        handler = ConsoleHandler(self)
+        handler.setLevel(level)
+        handler.setFormatter(logging.Formatter(fmt, datefmt))
+        logger.addHandler(handler)
+
+        self._handlers.append((logger, handler))
+        return handler
+
+    def remove_logging_handlers(self) -> None:
+        """Remove all logging handlers installed by this Console."""
+        for logger, handler in self._handlers:
+            logger.removeHandler(handler)
+        self._handlers.clear()
+
+
+class SpinnerHandle:
+    """Handle returned by Console.spinner() for updating the message."""
+
+    def __init__(self, console: Console) -> None:
+        self._console = console
+
+    def update(self, message: str) -> None:
+        """Update the spinner message."""
+        with self._console._lock:
+            self._console._spinner_message = message
+
+
+class ConsoleHandler(logging.Handler):
+    """Logging handler that coordinates with Console's spinner.
+
+    When a log record is emitted:
+    1. Pause the spinner (clear its line)
+    2. Print the formatted log message
+    3. Resume the spinner on a new line
+    """
+
+    def __init__(self, console: Console) -> None:
+        super().__init__()
+        self._console = console
+
+    def emit(self, record: logging.LogRecord) -> None:
+        try:
+            msg = self.format(record)
+            self._console.pause_spinner()
+            self._console.write_line(msg)
+            self._console.resume_spinner()
+        except Exception:
+            self.handleError(record)

wafer_core/rollouts/_pytui/renderer.py

@@ -0,0 +1,210 @@
+"""Differential terminal renderer.
+
+Extracted from rollouts/frontends/tui/tui.py _do_render() - same algorithm.
+
+Compares new lines against previous lines and only updates changed regions.
+Uses synchronized output mode to prevent flicker.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import Any
+
+from .terminal import (
+    CLEAR_LINE_FULL,
+    CLEAR_SCREEN_HOME,
+    SYNC_OUTPUT_OFF,
+    SYNC_OUTPUT_ON,
+    Terminal,
+)
+from .text import truncate_to_width, visible_width
+
+# Type for render logging callback
+RenderLogFn = Callable[..., None] | None
+
+_ANSI_RE = re.compile(r"\x1b\[[0-9;]*m")
+
+
+def _strip_ansi(s: str) -> str:
+    return _ANSI_RE.sub("", s)
+
+
+@dataclass
+class RenderState:
+    """Tracks state between renders for differential updates."""
+
+    previous_lines: list[str] = field(default_factory=list)
+    previous_width: int = 0
+    cursor_row: int = 0  # 0-indexed, relative to first line
+    render_count: int = 0
+    log_fn: RenderLogFn = None
+    # Set by App before each render
+    msgs_batched: int = 0
+    msg_types_batched: dict = field(default_factory=dict)
+
+
+def diff_render(
+    terminal: Terminal,
+    new_lines: list[str],
+    state: RenderState,
+) -> None:
+    """Render lines to terminal with differential updates.
+
+    Only redraws lines that changed since last render.
+    Uses synchronized output mode (\\x1b[?2026h/l) to prevent flicker.
+
+    Args:
+        terminal: Terminal to write to.
+        new_lines: Complete list of lines to display.
+        state: Mutable render state (updated in place).
+    """
+    width = terminal.columns
+    height = terminal.rows
+    state.render_count += 1
+    _rlog = state.log_fn
+
+    # Common log data for every render
+    def _emit_log(kind: str, buffer: str, **extra: Any) -> None:
+        if not _rlog:
+            return
+        line0 = _strip_ansi(new_lines[0])[:80] if new_lines else ""
+        _rlog(
+            "render",
+            n=state.render_count,
+            kind=kind,
+            width=width,
+            height=height,
+            lines=len(new_lines),
+            prev_lines=len(state.previous_lines),
+            cursor_row_before=state.cursor_row,
+            buf_bytes=len(buffer),
+            line0=line0,
+            msgs=state.msgs_batched,
+            msg_types=state.msg_types_batched or None,
+            **extra,
+        )
+
+    # Width changed - need full re-render
+    width_changed = state.previous_width != 0 and state.previous_width != width
+
+    # First render - just output everything
+    if len(state.previous_lines) == 0:
+        buffer = SYNC_OUTPUT_ON
+        for i, line in enumerate(new_lines):
+            if i > 0:
+                buffer += "\r\n"
+            buffer += line
+        buffer += SYNC_OUTPUT_OFF
+        _emit_log("first", buffer)
+        terminal.write(buffer)
+        state.cursor_row = len(new_lines) - 1
+        state.previous_lines = list(new_lines)
+        state.previous_width = width
+        return
+
+    # Width changed - full re-render
+    if width_changed:
+        buffer = SYNC_OUTPUT_ON
+        buffer += CLEAR_SCREEN_HOME
+        for i, line in enumerate(new_lines):
+            if i > 0:
+                buffer += "\r\n"
+            buffer += line
+        buffer += SYNC_OUTPUT_OFF
+        _emit_log("width_changed", buffer, old_width=state.previous_width)
+        terminal.write(buffer)
+        state.cursor_row = len(new_lines) - 1
+        state.previous_lines = list(new_lines)
+        state.previous_width = width
+        return
+
+    # Find first changed line
+    first_changed = -1
+    max_lines = max(len(new_lines), len(state.previous_lines))
+
+    for i in range(max_lines):
+        old_line = state.previous_lines[i] if i < len(state.previous_lines) else ""
+        new_line = new_lines[i] if i < len(new_lines) else ""
+        if old_line != new_line:
+            first_changed = i
+            break
+
+    # No changes
+    if first_changed == -1:
+        return
+
+    # Check if first_changed is outside the viewport
+    viewport_top = state.cursor_row - height + 1
+    if first_changed < viewport_top:
+        # First change is above viewport - need full re-render
+        buffer = SYNC_OUTPUT_ON
+        buffer += CLEAR_SCREEN_HOME
+        for i, line in enumerate(new_lines):
+            if i > 0:
+                buffer += "\r\n"
+            buffer += line
+        buffer += SYNC_OUTPUT_OFF
+        _emit_log(
+            "above_viewport", buffer,
+            first_changed=first_changed, viewport_top=viewport_top,
+        )
+        terminal.write(buffer)
+        state.cursor_row = len(new_lines) - 1
+        state.previous_lines = list(new_lines)
+        state.previous_width = width
+        return
+
+    # Render from first changed line to end
+    line_diff = first_changed - state.cursor_row
+
+    buffer = SYNC_OUTPUT_ON
+
+    # Move cursor to first changed line
+    if line_diff > 0:
+        buffer += f"\x1b[{line_diff}B"  # Move down
+    elif line_diff < 0:
+        buffer += f"\x1b[{-line_diff}A"  # Move up
+
+    buffer += "\r"  # Move to column 0
+
+    # Render from first changed line to end, clearing each line before writing
+    cursor_after_render = first_changed
+    for i in range(first_changed, len(new_lines)):
+        if i > first_changed:
+            buffer += "\r\n"
+            cursor_after_render = i
+        buffer += CLEAR_LINE_FULL
+
+        line = new_lines[i]
+        if visible_width(line) > width:
+            line = truncate_to_width(line, width, ellipsis="\u2026")
+        buffer += line
+
+    # If we had more lines before, clear them
+    extra_cleared = 0
+    if len(state.previous_lines) > len(new_lines):
+        extra_cleared = len(state.previous_lines) - len(new_lines)
+        for _i in range(extra_cleared):
+            buffer += "\r\n" + CLEAR_LINE_FULL
+        # Move cursor back to correct position
+        lines_to_move_up = cursor_after_render + extra_cleared - (len(new_lines) - 1)
+        if lines_to_move_up > 0:
+            buffer += f"\x1b[{lines_to_move_up}A"
+
+    buffer += SYNC_OUTPUT_OFF
+
+    _emit_log(
+        "diff", buffer,
+        first_changed=first_changed,
+        cursor_move=line_diff,
+        redraw=len(new_lines) - first_changed,
+        extra_cleared=extra_cleared,
+    )
+
+    terminal.write(buffer)
+    state.cursor_row = len(new_lines) - 1
+    state.previous_lines = list(new_lines)
+    state.previous_width = width

wafer_core/rollouts/_pytui/spinner.py

@@ -0,0 +1,73 @@
+"""Standalone CLI spinner for long-running operations.
+
+No TUI app needed — just stderr + ANSI escape codes.
+Uses the same braille frames as the rollouts Loader component.
+
+Usage:
+    with Spinner("Provisioning GPU...") as s:
+        provision()
+        s.update("Deploying code...")
+        deploy()
+    # prints: ✓ Deploying code...
+
+    # Or without context manager:
+    s = Spinner("Working...")
+    s.start()
+    s.update("Still working...")
+    s.stop()            # prints: ✓ Still working...
+    s.stop("Failed!")   # prints: ✗ Failed!
+"""
+
+from __future__ import annotations
+
+import itertools
+import sys
+import threading
+import time
+
+BRAILLE_FRAMES = ("⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏")
+
+
+class Spinner:
+    """Braille spinner that overwrites a single stderr line."""
+
+    def __init__(self, message: str) -> None:
+        self._message = message
+        self._stop = threading.Event()
+        self._thread: threading.Thread | None = None
+
+    def update(self, message: str) -> None:
+        """Change the spinner text (thread-safe)."""
+        self._message = message
+
+    def start(self) -> None:
+        """Start the spinner background thread."""
+        assert self._thread is None, "Spinner already started"
+        self._thread = threading.Thread(target=self._spin, daemon=True)
+        self._thread.start()
+
+    def stop(self, final_message: str | None = None, success: bool = True) -> None:
+        """Stop the spinner and print final status."""
+        self._stop.set()
+        if self._thread is not None:
+            self._thread.join()
+            self._thread = None
+        msg = final_message or self._message
+        mark = "✓" if success else "✗"
+        sys.stderr.write(f"\r\033[K{mark} {msg}\n")
+        sys.stderr.flush()
+
+    def _spin(self) -> None:
+        for frame in itertools.cycle(BRAILLE_FRAMES):
+            if self._stop.is_set():
+                break
+            sys.stderr.write(f"\r\033[K{frame} {self._message}")
+            sys.stderr.flush()
+            time.sleep(0.08)
+
+    def __enter__(self) -> Spinner:
+        self.start()
+        return self
+
+    def __exit__(self, exc_type: type | None, *_: object) -> None:
+        self.stop(success=exc_type is None)