glaip-sdk 0.6.5b6__py3-none-any.whl → 0.7.12__py3-none-any.whl

glaip_sdk/cli/slash/tui/theme/catalog.py

@@ -0,0 +1,79 @@
+"""Built-in theme catalog for TUI applications.
+
+This module implements Phase 2 of the TUI Theme System spec, providing a foundational
+set of 12 color tokens (primary, secondary, accent, background, background_panel, text,
+text_muted, success, warning, error, info). Additional tokens (e.g., diff.added,
+syntax.*, backgroundElevated, textDim) will be added in future phases per the spec's
+"100+ color tokens" requirement.
+"""
+
+from __future__ import annotations
+
+from glaip_sdk.cli.slash.tui.theme.tokens import ThemeModeLiteral, ThemeTokens
+
+_BUILTIN_THEMES: dict[str, ThemeTokens] = {
+    "gl-dark": ThemeTokens(
+        name="gl-dark",
+        mode="dark",
+        primary="#6EA8FE",
+        secondary="#ADB5BD",
+        accent="#C77DFF",
+        background="#0B0F19",
+        background_panel="#111827",
+        text="#E5E7EB",
+        text_muted="#9CA3AF",
+        success="#34D399",
+        warning="#FBBF24",
+        error="#F87171",
+        info="#60A5FA",
+    ),
+    "gl-light": ThemeTokens(
+        name="gl-light",
+        mode="light",
+        primary="#1D4ED8",
+        secondary="#4B5563",
+        accent="#7C3AED",
+        background="#FFFFFF",
+        background_panel="#F3F4F6",
+        text="#111827",
+        text_muted="#4B5563",
+        success="#059669",
+        warning="#B45309",
+        error="#B91C1C",
+        info="#1D4ED8",
+    ),
+    "gl-high-contrast": ThemeTokens(
+        name="gl-high-contrast",
+        mode="dark",
+        # High-contrast theme uses uniform colors (#FFFFFF on #000000) to maximize
+        # contrast for accessibility. Semantic distinctions (success/warning/error)
+        # are intentionally uniform to prioritize maximum readability over color
+        # coding, per accessibility best practices for high-contrast modes.
+        primary="#FFFFFF",
+        secondary="#FFFFFF",
+        accent="#FFFFFF",
+        background="#000000",
+        background_panel="#000000",
+        text="#FFFFFF",
+        text_muted="#FFFFFF",
+        success="#FFFFFF",
+        warning="#FFFFFF",
+        error="#FFFFFF",
+        info="#FFFFFF",
+    ),
+}
+
+
+def get_builtin_theme(name: str) -> ThemeTokens | None:
+    """Return a built-in theme by name."""
+    return _BUILTIN_THEMES.get(name)
+
+
+def list_builtin_themes() -> list[str]:
+    """List available built-in theme names."""
+    return sorted(_BUILTIN_THEMES)
+
+
+def default_theme_name_for_mode(mode: ThemeModeLiteral) -> str:
+    """Return the default theme name for the given light/dark mode."""
+    return "gl-light" if mode == "light" else "gl-dark"

glaip_sdk/cli/slash/tui/theme/manager.py

@@ -0,0 +1,112 @@
+"""Theme manager for TUI applications."""
+
+from __future__ import annotations
+
+import logging
+from enum import Enum
+from typing import Literal
+
+from glaip_sdk.cli.account_store import AccountStore, AccountStoreError
+from glaip_sdk.cli.slash.tui.terminal import TerminalCapabilities
+from glaip_sdk.cli.slash.tui.theme.catalog import default_theme_name_for_mode, get_builtin_theme
+from glaip_sdk.cli.slash.tui.theme.tokens import ThemeTokens
+from glaip_sdk.cli.tui_settings import persist_tui_theme
+
+logger = logging.getLogger(__name__)
+
+
+class ThemeMode(str, Enum):
+    """User-selectable theme mode."""
+
+    AUTO = "auto"
+    LIGHT = "light"
+    DARK = "dark"
+
+
+class ThemeManager:
+    """Resolve active theme tokens from terminal state and user preferences."""
+
+    def __init__(
+        self,
+        terminal: TerminalCapabilities,
+        *,
+        mode: ThemeMode | str = ThemeMode.AUTO,
+        theme: str | None = None,
+        settings_store: AccountStore | None = None,
+    ) -> None:
+        """Initialize the theme manager."""
+        self._terminal = terminal
+        self._mode = self._coerce_mode(mode)
+        self._theme = self._normalize_theme_name(theme)
+        self._settings_store = settings_store
+
+    @property
+    def mode(self) -> ThemeMode:
+        """Return configured mode (auto/light/dark)."""
+        return self._mode
+
+    @property
+    def effective_mode(self) -> Literal["light", "dark"]:
+        """Return resolved light/dark mode."""
+        if self._mode == ThemeMode.AUTO:
+            return self._terminal.background_mode
+        return "light" if self._mode == ThemeMode.LIGHT else "dark"
+
+    @property
+    def theme_name(self) -> str:
+        """Return resolved theme name."""
+        return self._theme or default_theme_name_for_mode(self.effective_mode)
+
+    @property
+    def tokens(self) -> ThemeTokens:
+        """Return tokens for the resolved theme."""
+        chosen = get_builtin_theme(self.theme_name)
+        if chosen is not None:
+            return chosen
+
+        fallback_name = default_theme_name_for_mode(self.effective_mode)
+        fallback = get_builtin_theme(fallback_name)
+        if fallback is None:
+            raise RuntimeError(f"Missing default theme: {fallback_name}")
+
+        return fallback
+
+    def set_mode(self, mode: ThemeMode | str) -> None:
+        """Set auto/light/dark mode."""
+        self._mode = self._coerce_mode(mode)
+        self._persist_preferences()
+
+    def set_theme(self, theme: str | None) -> None:
+        """Set explicit theme name (or None to use the default)."""
+        self._theme = self._normalize_theme_name(theme)
+        self._persist_preferences()
+
+    def _coerce_mode(self, mode: ThemeMode | str) -> ThemeMode:
+        """Coerce a mode value to ThemeMode enum, defaulting to AUTO on invalid input."""
+        if isinstance(mode, ThemeMode):
+            return mode
+        try:
+            return ThemeMode(mode)
+        except ValueError:
+            logger.warning(f"Invalid theme mode '{mode}', defaulting to AUTO")
+            return ThemeMode.AUTO
+
+    def _persist_preferences(self) -> None:
+        if self._settings_store is None:
+            return
+        try:
+            persist_tui_theme(mode=self._mode.value, name=self._theme, store=self._settings_store)
+        except (OSError, AccountStoreError) as exc:
+            # Log recoverable errors (permissions, I/O) as warnings
+            logger.warning(f"Failed to persist TUI theme preferences: {exc}")
+        except Exception as exc:
+            # Log unexpected errors at error level for debugging
+            logger.error(f"Unexpected error persisting TUI theme preferences: {exc}", exc_info=True)
+
+    def _normalize_theme_name(self, theme: str | None) -> str | None:
+        if not isinstance(theme, str):
+            return None
+        cleaned = theme.strip()
+        if not cleaned or cleaned.lower() == "default":
+            return None
+        return cleaned

glaip_sdk/cli/slash/tui/theme/tokens.py

@@ -0,0 +1,55 @@
+"""Theme token definitions for TUI applications."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+ThemeModeLiteral = Literal["light", "dark"]
+
+
+@dataclass(frozen=True, slots=True)
+class ThemeTokens:
+    """Color token set for a built-in theme."""
+
+    name: str
+    mode: ThemeModeLiteral
+
+    primary: str
+    secondary: str
+    accent: str
+
+    background: str
+    background_panel: str
+
+    text: str
+    text_muted: str
+
+    success: str
+    warning: str
+    error: str
+    info: str
+
+    def as_dict(self) -> dict[str, str]:
+        """Return color tokens as a plain dictionary.
+
+        Returns only color tokens (primary, secondary, accent, background, etc.),
+        excluding metadata fields (name, mode). This is intentional for use cases
+        like Textual TCSS mapping where only color values are needed.
+
+        Returns:
+            Dictionary mapping color token names to hex color strings.
+        """
+        return {
+            "primary": self.primary,
+            "secondary": self.secondary,
+            "accent": self.accent,
+            "background": self.background,
+            "background_panel": self.background_panel,
+            "text": self.text,
+            "text_muted": self.text_muted,
+            "success": self.success,
+            "warning": self.warning,
+            "error": self.error,
+            "info": self.info,
+        }

glaip_sdk/cli/slash/tui/toast.py

@@ -0,0 +1,374 @@
+"""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.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 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)
 
     # ------------------------------------------------------------------