glaip-sdk 0.6.5b3__py3-none-any.whl → 0.7.17__py3-none-any.whl

glaip_sdk/cli/slash/tui/toast.py

@@ -0,0 +1,388 @@
+"""Toast widgets and state management for the TUI."""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Callable
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any, cast
+
+from rich.text import Text
+from textual.message import Message
+from textual.widget import Widget
+from textual.widgets import Static
+
+
+class ToastVariant(str, Enum):
+    """Toast message variant for styling and behavior."""
+
+    INFO = "info"
+    SUCCESS = "success"
+    WARNING = "warning"
+    ERROR = "error"
+
+
+DEFAULT_TOAST_DURATIONS_SECONDS: dict[ToastVariant, float] = {
+    ToastVariant.SUCCESS: 2.0,
+    ToastVariant.INFO: 3.0,
+    ToastVariant.WARNING: 3.0,
+    ToastVariant.ERROR: 5.0,
+}
+
+
+@dataclass(frozen=True, slots=True)
+class ToastState:
+    """Immutable toast notification state."""
+
+    message: str
+    variant: ToastVariant
+    duration_seconds: float
+
+
+class ToastBus:
+    """Toast state manager with auto-dismiss functionality."""
+
+    class Changed(Message):
+        """Message sent when toast state changes."""
+
+        def __init__(self, state: ToastState | None) -> None:
+            """Initialize the changed message with new toast state."""
+            super().__init__()
+            self.state = state
+
+    def __init__(self, on_change: Callable[[ToastBus.Changed], None] | None = None) -> None:
+        """Initialize the toast bus with optional change callback."""
+        self._state: ToastState | None = None
+        self._dismiss_task: asyncio.Task[None] | None = None
+        self._on_change = on_change
+
+    @property
+    def state(self) -> ToastState | None:
+        """Return the current toast state, or None if no toast is shown."""
+        return self._state
+
+    def show(
+        self,
+        message: str,
+        variant: ToastVariant | str = ToastVariant.INFO,
+        *,
+        duration_seconds: float | None = None,
+    ) -> None:
+        """Show a toast notification with the given message and variant.
+
+        Args:
+            message: The message to display in the toast.
+            variant: The visual variant of the toast (INFO, SUCCESS, WARNING, ERROR).
+            duration_seconds: Optional custom duration in seconds. If None, uses default
+                duration for the variant (2s for SUCCESS, 3s for INFO/WARNING, 5s for ERROR).
+        """
+        resolved_variant = self._coerce_variant(variant)
+        resolved_duration = (
+            DEFAULT_TOAST_DURATIONS_SECONDS[resolved_variant] if duration_seconds is None else float(duration_seconds)
+        )
+
+        self._state = ToastState(
+            message=message,
+            variant=resolved_variant,
+            duration_seconds=resolved_duration,
+        )
+
+        self._cancel_dismiss_task()
+
+        try:
+            loop = asyncio.get_running_loop()
+        except RuntimeError:
+            raise RuntimeError(
+                "Cannot schedule toast auto-dismiss: no running event loop. "
+                "ToastBus.show() must be called from within an async context."
+            ) from None
+
+        self._dismiss_task = loop.create_task(self._auto_dismiss(resolved_duration))
+        self._notify_changed()
+
+    def clear(self) -> None:
+        """Clear the current toast notification immediately."""
+        self._cancel_dismiss_task()
+        self._state = None
+        self._notify_changed()
+
+    def copy_success(self, label: str | None = None) -> None:
+        """Show a success toast for clipboard copy operations.
+
+        Args:
+            label: Optional label for what was copied (e.g., "Run ID", "JSON").
+        """
+        message = "Copied to clipboard" if not label else f"Copied {label} to clipboard"
+        self.show(message=message, variant=ToastVariant.SUCCESS)
+
+    def copy_failed(self) -> None:
+        """Show a warning toast when clipboard copy fails."""
+        self.show(message="Clipboard unavailable. Text printed below.", variant=ToastVariant.WARNING)
+
+    def _coerce_variant(self, variant: ToastVariant | str) -> ToastVariant:
+        if isinstance(variant, ToastVariant):
+            return variant
+        try:
+            return ToastVariant(variant)
+        except ValueError:
+            return ToastVariant.INFO
+
+    def _cancel_dismiss_task(self) -> None:
+        if self._dismiss_task is None:
+            return
+        if not self._dismiss_task.done():
+            self._dismiss_task.cancel()
+        self._dismiss_task = None
+
+    async def _auto_dismiss(self, duration_seconds: float) -> None:
+        try:
+            await asyncio.sleep(duration_seconds)
+        except asyncio.CancelledError:
+            return
+
+        self._state = None
+        self._dismiss_task = None
+        self._notify_changed()
+
+    def _notify_changed(self) -> None:
+        if self._on_change:
+            self._on_change(ToastBus.Changed(self._state))
+
+
+class ToastHandlerMixin:
+    """Mixin providing common toast handling functionality.
+
+    Classes that inherit from this mixin can handle ToastBus.Changed messages
+    by automatically updating all Toast widgets in the component tree.
+    """
+
+    def on_toast_bus_changed(self, message: ToastBus.Changed) -> None:
+        """Refresh the toast widget when the toast bus updates.
+
+        Args:
+            message: The toast bus changed message containing the new state.
+        """
+        try:
+            for toast in self.query(Toast):
+                toast.update_state(message.state)
+        except Exception:
+            pass
+
+
+class ClipboardToastMixin:
+    """Mixin providing clipboard and toast orchestration functionality.
+
+    Classes that inherit from this mixin get shared clipboard adapter selection,
+    OSC52 writer setup, toast bus lookup, and copy-success/failure orchestration.
+    This consolidates duplicate clipboard/toast logic across TUI apps.
+
+    Expected attributes:
+        _ctx: TUIContext | None - Shared TUI context (optional)
+        _clipboard: ClipboardAdapter | None - Cached clipboard adapter (optional)
+        _local_toasts: ToastBus | None - Local toast bus instance (optional)
+    """
+
+    def _clipboard_adapter(self) -> Any:  # ClipboardAdapter
+        """Get or create a clipboard adapter instance.
+
+        Returns:
+            ClipboardAdapter instance, preferring context's adapter if available.
+        """
+        # Import here to avoid circular dependency
+        from glaip_sdk.cli.slash.tui.clipboard import ClipboardAdapter  # noqa: PLC0415
+
+        ctx = getattr(self, "_ctx", None)
+        clipboard = getattr(self, "_clipboard", None)
+
+        if ctx is not None and ctx.clipboard is not None:
+            return cast(ClipboardAdapter, ctx.clipboard)
+        if clipboard is not None:
+            return clipboard
+
+        adapter = ClipboardAdapter(terminal=ctx.terminal if ctx else None)
+        if ctx is not None:
+            ctx.clipboard = adapter
+        else:
+            self._clipboard = adapter
+        return adapter
+
+    def _osc52_writer(self) -> Callable[[str], Any] | None:
+        """Get an OSC52 writer function if console output is available.
+
+        Returns:
+            Writer function that writes OSC52 sequences to console output, or None.
+        """
+        try:
+            # Try self.app.console first (for Screen subclasses)
+            if hasattr(self, "app") and hasattr(self.app, "console"):
+                console = self.app.console
+            # Fall back to self.console (for App subclasses)
+            else:
+                console = getattr(self, "console", None)
+        except Exception:
+            return None
+
+        if console is None:
+            return None
+
+        output = getattr(console, "file", None)
+        if output is None:
+            return None
+
+        def _write(sequence: str, _output: Any = output) -> None:
+            _output.write(sequence)
+            _output.flush()
+
+        return _write
+
+    def _toast_bus(self) -> ToastBus | None:
+        """Get the toast bus instance.
+
+        Returns:
+            ToastBus instance, preferring context's bus if available, or None.
+        """
+        local_toasts = getattr(self, "_local_toasts", None)
+        ctx = getattr(self, "_ctx", None)
+
+        if local_toasts is not None:
+            return local_toasts
+        if ctx is not None and ctx.toasts is not None:
+            return ctx.toasts
+        return None
+
+    def _copy_to_clipboard(self, text: str, *, label: str | None = None) -> None:
+        """Copy text to clipboard and show toast notification.
+
+        Args:
+            text: The text to copy to clipboard.
+            label: Optional label for what was copied (e.g., "Run ID", "JSON").
+        """
+        adapter = self._clipboard_adapter()
+        writer = self._osc52_writer()
+        if writer:
+            result = adapter.copy(text, writer=writer)
+        else:
+            result = adapter.copy(text)
+
+        toasts = self._toast_bus()
+        if result.success:
+            if toasts:
+                toasts.copy_success(label)
+            else:
+                # Fallback to status announcement if toast bus unavailable
+                if hasattr(self, "_announce_status"):
+                    if label:
+                        self._announce_status(f"Copied {label} to clipboard.")
+                    else:
+                        self._announce_status("Copied to clipboard.")
+            return
+
+        # Copy failed
+        if toasts:
+            toasts.copy_failed()
+        else:
+            # Fallback to status announcement if toast bus unavailable
+            if hasattr(self, "_announce_status"):
+                self._announce_status("Clipboard unavailable. Text printed below.")
+
+        # Append fallback text output
+        if hasattr(self, "_append_copy_fallback"):
+            self._append_copy_fallback(text)
+
+
+class ToastContainer(Widget):
+    """Simple wrapper for docking toast widgets without relying on containers.
+
+    This class exists to provide a lightweight widget wrapper for toast containers
+    that avoids direct dependency on Textual's Container class. It allows the toast
+    system to work consistently across different Textual versions and provides a
+    stable API for toast container composition.
+
+    Usage:
+        yield ToastContainer(Toast(), id="toast-container")
+    """
+
+
+class Toast(Static):
+    """A Textual widget that displays toast notifications at the top-right of the screen.
+
+    The Toast widget is updated via `update_state()` calls from message handlers
+    (e.g., `on_toast_bus_changed`). The widget does not auto-subscribe to ToastBus
+    state changes; the app must call `update_state()` when toast state changes.
+    """
+
+    DEFAULT_CSS = """
+    #toast-container {
+        width: 100%;
+        height: auto;
+        dock: top;
+        align: right top;
+    }
+
+    Toast {
+        width: auto;
+        min-width: 20;
+        max-width: 40;
+        height: auto;
+        padding: 0 1;
+        margin: 1 2;
+        background: $surface;
+        color: $text;
+        border: solid $primary;
+        display: none;
+    }
+
+    Toast.visible {
+        display: block;
+    }
+
+    Toast.info {
+        border: solid $accent;
+    }
+
+    Toast.success {
+        border: solid $success;
+    }
+
+    Toast.warning {
+        border: solid $warning;
+    }
+
+    Toast.error {
+        border: solid $error;
+    }
+    """
+
+    def __init__(self) -> None:
+        """Initialize the Toast widget.
+
+        The widget is updated via `update_state()` calls from message handlers
+        (e.g., `on_toast_bus_changed`). The widget does not auto-subscribe to
+        a ToastBus; the app must call `update_state()` when toast state changes.
+        """
+        super().__init__("")
+
+    def update_state(self, state: ToastState | None) -> None:
+        """Update the toast display based on the provided state.
+
+        Args:
+            state: The toast state to display, or None to hide the toast.
+        """
+        if not state:
+            self.remove_class("visible")
+            return
+
+        icon = "ℹ️"
+        if state.variant == ToastVariant.SUCCESS:
+            icon = "✅"
+        elif state.variant == ToastVariant.WARNING:
+            icon = "⚠️"
+        elif state.variant == ToastVariant.ERROR:
+            icon = "❌"
+
+        self.update(Text.assemble((f"{icon} ", "bold"), state.message))
+
+        self.remove_class("info", "success", "warning", "error")
+        self.add_class(state.variant.value)
+        self.add_class("visible")

glaip_sdk/cli/transcript/history.py

@@ -23,7 +23,7 @@ from glaip_sdk.cli.transcript.cache import (  # Reuse helpers even if marked pri
     transcript_path_candidates,
     write_manifest,
 )
-from glaip_sdk.cli.utils import parse_json_line
+from glaip_sdk.cli.core.output import parse_json_line
 from glaip_sdk.utils.datetime_helpers import coerce_datetime
 
 DEFAULT_HISTORY_LIMIT = 10

glaip_sdk/cli/transcript/viewer.py

@@ -21,8 +21,9 @@ except Exception:  # pragma: no cover - optional dependency
     Choice = None  # type: ignore[assignment]
 
 from glaip_sdk.cli.transcript.cache import suggest_filename
-from glaip_sdk.cli.utils import prompt_export_choice_questionary, questionary_safe_ask
+from glaip_sdk.cli.core.prompting import prompt_export_choice_questionary, questionary_safe_ask
 from glaip_sdk.utils.rendering.layout.progress import is_delegation_tool
+from glaip_sdk.utils.rendering.layout.transcript import DEFAULT_TRANSCRIPT_THEME
 from glaip_sdk.utils.rendering.viewer import (
     ViewerContext as PresenterViewerContext,
     prepare_viewer_snapshot as presenter_prepare_viewer_snapshot,
@@ -93,8 +94,9 @@ class PostRunViewer:  # pragma: no cover - interactive flows are not unit tested
         if self._view_mode == "default":
             presenter_render_post_run_view(self.console, self.ctx)
         else:
-            snapshot, state = presenter_prepare_viewer_snapshot(self.ctx, glyphs=None)
-            presenter_render_transcript_view(self.console, snapshot)
+            theme = DEFAULT_TRANSCRIPT_THEME
+            snapshot, state = presenter_prepare_viewer_snapshot(self.ctx, glyphs=None, theme=theme)
+            presenter_render_transcript_view(self.console, snapshot, theme=theme)
             presenter_render_transcript_events(self.console, state.events)
 
     # ------------------------------------------------------------------

glaip_sdk/cli/tui_settings.py

@@ -0,0 +1,125 @@
+"""Typed loader/saver for TUI preferences stored in config.yaml.
+
+This module implements the TUI preferences store as defined in
+`specs/architecture/tui-preferences-store/spec.md`.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Literal, cast
+
+from glaip_sdk.cli.account_store import AccountStore, get_account_store
+
+ThemeModeValue = Literal["auto", "light", "dark"]
+
+_DEFAULT_THEME_MODE: ThemeModeValue = "auto"
+_DEFAULT_LEADER = "ctrl+x"
+_DEFAULT_MOUSE_CAPTURE = False
+
+
+@dataclass(frozen=True)
+class TUISettings:
+    """Resolved TUI preferences from config.yaml."""
+
+    theme_mode: ThemeModeValue = _DEFAULT_THEME_MODE
+    theme_name: str | None = None
+    leader: str = _DEFAULT_LEADER
+    keybind_overrides: dict[str, str] = field(default_factory=dict)
+    mouse_capture: bool = _DEFAULT_MOUSE_CAPTURE
+
+
+def load_tui_settings(*, store: AccountStore | None = None) -> TUISettings:
+    """Load TUI preferences from the CLI config file."""
+    store = store or get_account_store()
+    config = store.load_config()
+
+    tui = _as_dict(config.get("tui"))
+    theme = _as_dict(tui.get("theme"))
+    mode = _coerce_theme_mode(theme.get("mode"))
+    name = _normalize_theme_name(theme.get("name"))
+
+    keybinds = _as_dict(tui.get("keybinds"))
+    leader = keybinds.get("leader")
+    if not isinstance(leader, str) or not leader.strip():
+        leader = _DEFAULT_LEADER
+
+    overrides = _coerce_keybind_overrides(keybinds.get("overrides"))
+
+    mouse_capture = tui.get("mouse_capture")
+    if not isinstance(mouse_capture, bool):
+        mouse_capture = _DEFAULT_MOUSE_CAPTURE
+
+    return TUISettings(
+        theme_mode=mode,
+        theme_name=name,
+        leader=leader,
+        keybind_overrides=overrides,
+        mouse_capture=mouse_capture,
+    )
+
+
+def update_tui_settings(patch: dict[str, Any], *, store: AccountStore | None = None) -> None:
+    """Update TUI preferences, preserving unrelated config keys."""
+    store = store or get_account_store()
+    config = store.load_config()
+
+    existing = _as_dict(config.get("tui"))
+    config["tui"] = _merge_dict(existing, patch)
+
+    store.save_config_updates(config)
+
+
+def persist_tui_theme(*, mode: ThemeModeValue, name: str | None, store: AccountStore | None = None) -> None:
+    """Persist theme preferences in the tui.theme namespace."""
+    update_tui_settings(
+        {"theme": {"mode": _coerce_theme_mode(mode), "name": _serialize_theme_name(name)}},
+        store=store,
+    )
+
+
+def _as_dict(value: Any) -> dict[str, Any]:
+    if isinstance(value, dict):
+        return dict(value)
+    return {}
+
+
+def _coerce_theme_mode(value: Any) -> ThemeModeValue:
+    if isinstance(value, str):
+        lowered = value.strip().lower()
+        if lowered in {"auto", "light", "dark"}:
+            return cast(ThemeModeValue, lowered)
+    return _DEFAULT_THEME_MODE
+
+
+def _normalize_theme_name(value: Any) -> str | None:
+    if not isinstance(value, str):
+        return None
+    cleaned = value.strip()
+    if not cleaned or cleaned.lower() == "default":
+        return None
+    return cleaned
+
+
+def _serialize_theme_name(name: str | None) -> str:
+    if isinstance(name, str):
+        cleaned = name.strip()
+        if cleaned:
+            return cleaned
+    return "default"
+
+
+def _coerce_keybind_overrides(value: Any) -> dict[str, str]:
+    if not isinstance(value, dict):
+        return {}
+    return {key: val for key, val in value.items() if isinstance(key, str) and isinstance(val, str)}
+
+
+def _merge_dict(base: dict[str, Any], patch: dict[str, Any]) -> dict[str, Any]:
+    merged = dict(base)
+    for key, value in patch.items():
+        if isinstance(value, dict) and isinstance(merged.get(key), dict):
+            merged[key] = _merge_dict(cast(dict[str, Any], merged[key]), value)
+        else:
+            merged[key] = value
+    return merged