glaip-sdk 0.0.20__py3-none-any.whl → 0.7.7__py3-none-any.whl

glaip_sdk/cli/slash/tui/background_tasks.py

@@ -0,0 +1,72 @@
+"""Shared mixin for tracking background asyncio tasks in Textual apps.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from collections.abc import Callable, Coroutine
+from typing import Any
+
+
+class BackgroundTaskMixin:
+    """Mixin that tracks background tasks and cleans them up on unmount."""
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        """Initialize task tracking set for derived Textual apps."""
+        super().__init__(*args, **kwargs)
+        self._pending_tasks: set[asyncio.Task[Any]] = set()
+
+    def track_task(
+        self,
+        coro: Coroutine[Any, Any, Any],
+        *,
+        on_error: Callable[[Exception], None] | None = None,
+        logger: logging.Logger | None = None,
+    ) -> asyncio.Task[Any]:
+        """Create and track a background task with optional error handling."""
+        task = asyncio.create_task(coro)
+        self._pending_tasks.add(task)
+
+        def _cleanup(finished: asyncio.Task[Any]) -> None:
+            self._pending_tasks.discard(finished)
+            if finished.cancelled():
+                return
+            try:
+                exc = finished.exception()
+            except Exception:
+                return
+            if exc:
+                if on_error:
+                    on_error(exc)
+                elif logger:
+                    logger.debug("Background task failed", exc_info=exc)
+
+        task.add_done_callback(_cleanup)
+        return task
+
+    def on_unmount(self) -> None:  # pragma: no cover - UI lifecycle hook
+        """Ensure background tasks are cleaned up on exit."""
+        pending = [task for task in self._pending_tasks if not task.done()]
+        for task in pending:
+            try:
+                task.cancel()
+            except Exception:
+                continue
+        if pending:
+            try:
+                loop = asyncio.get_running_loop()
+            except RuntimeError:
+                loop = None
+            if loop and loop.is_running():
+                try:
+                    loop.create_task(asyncio.gather(*pending, return_exceptions=True))
+                except Exception:
+                    pass
+        self._pending_tasks.clear()
+        parent_on_unmount = getattr(super(), "on_unmount", None)
+        if callable(parent_on_unmount):
+            parent_on_unmount()  # type: ignore[misc]

glaip_sdk/cli/slash/tui/clipboard.py

@@ -0,0 +1,147 @@
+"""Clipboard adapter for TUI copy actions."""
+
+from __future__ import annotations
+
+import base64
+import os
+import platform
+import shutil
+import subprocess
+import sys
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any
+from collections.abc import Callable
+
+from glaip_sdk.cli.slash.tui.terminal import TerminalCapabilities, detect_osc52_support
+
+
+class ClipboardMethod(str, Enum):
+    """Supported clipboard backends."""
+
+    OSC52 = "osc52"
+    PBCOPY = "pbcopy"
+    XCLIP = "xclip"
+    XSEL = "xsel"
+    WL_COPY = "wl-copy"
+    CLIP = "clip"
+    NONE = "none"
+
+
+@dataclass(frozen=True, slots=True)
+class ClipboardResult:
+    """Result of a clipboard operation."""
+
+    success: bool
+    method: ClipboardMethod
+    message: str
+
+
+_SUBPROCESS_COMMANDS: dict[ClipboardMethod, list[str]] = {
+    ClipboardMethod.PBCOPY: ["pbcopy"],
+    ClipboardMethod.XCLIP: ["xclip", "-selection", "clipboard"],
+    ClipboardMethod.XSEL: ["xsel", "--clipboard", "--input"],
+    ClipboardMethod.WL_COPY: ["wl-copy"],
+    ClipboardMethod.CLIP: ["clip"],
+}
+
+
+class ClipboardAdapter:
+    """Cross-platform clipboard access with OSC 52 fallback."""
+
+    def __init__(
+        self,
+        *,
+        terminal: TerminalCapabilities | None = None,
+        method: ClipboardMethod | None = None,
+    ) -> None:
+        """Initialize the adapter."""
+        self._terminal = terminal
+        self._method = method or self._detect_method()
+
+    @property
+    def method(self) -> ClipboardMethod:
+        """Return the detected clipboard backend."""
+        return self._method
+
+    def copy(self, text: str, *, writer: Callable[[str], Any] | None = None) -> ClipboardResult:
+        """Copy text to clipboard using the best available method.
+
+        Args:
+            text: Text to copy.
+            writer: Optional function to write OSC 52 sequence (e.g., self.app.console.write).
+                   Defaults to sys.stdout.write if not provided.
+        """
+        if self._method == ClipboardMethod.OSC52:
+            return self._copy_osc52(text, writer=writer)
+
+        command = _SUBPROCESS_COMMANDS.get(self._method)
+        if command is None:
+            return self._copy_osc52(text, writer=writer)
+
+        result = self._copy_subprocess(command, text)
+        if not result.success:
+            return self._copy_osc52(text, writer=writer)
+
+        return result
+
+    def _detect_method(self) -> ClipboardMethod:
+        if self._terminal.osc52 if self._terminal else detect_osc52_support():
+            return ClipboardMethod.OSC52
+
+        system = platform.system()
+        if system == "Darwin":
+            return self._detect_darwin_method()
+        if system == "Linux":
+            return self._detect_linux_method()
+        if system == "Windows":
+            return self._detect_windows_method()
+        return ClipboardMethod.NONE
+
+    def _detect_darwin_method(self) -> ClipboardMethod:
+        return ClipboardMethod.PBCOPY if shutil.which("pbcopy") else ClipboardMethod.NONE
+
+    def _detect_linux_method(self) -> ClipboardMethod:
+        if not os.getenv("DISPLAY") and not os.getenv("WAYLAND_DISPLAY"):
+            return ClipboardMethod.NONE
+
+        for cmd, method in (
+            ("xclip", ClipboardMethod.XCLIP),
+            ("xsel", ClipboardMethod.XSEL),
+            ("wl-copy", ClipboardMethod.WL_COPY),
+        ):
+            if shutil.which(cmd):
+                return method
+        return ClipboardMethod.NONE
+
+    def _detect_windows_method(self) -> ClipboardMethod:
+        return ClipboardMethod.CLIP if shutil.which("clip") else ClipboardMethod.NONE
+
+    def _copy_osc52(self, text: str, *, writer: Callable[[str], Any] | None = None) -> ClipboardResult:
+        encoded = base64.b64encode(text.encode("utf-8")).decode("ascii")
+        sequence = f"\x1b]52;c;{encoded}\x07"
+        try:
+            if writer:
+                writer(sequence)
+            else:
+                sys.stdout.write(sequence)
+                sys.stdout.flush()
+        except Exception as exc:
+            return ClipboardResult(False, ClipboardMethod.OSC52, str(exc))
+
+        return ClipboardResult(True, ClipboardMethod.OSC52, "Copied to clipboard")
+
+    def _copy_subprocess(self, cmd: list[str], text: str) -> ClipboardResult:
+        try:
+            completed = subprocess.run(
+                cmd,
+                input=text.encode("utf-8"),
+                check=False,
+            )
+        except OSError as exc:
+            return ClipboardResult(False, self._method, str(exc))
+
+        if completed.returncode == 0:
+            return ClipboardResult(True, self._method, "Copied to clipboard")
+
+        return ClipboardResult(False, self._method, f"Command failed: {completed.returncode}")

glaip_sdk/cli/slash/tui/context.py

@@ -0,0 +1,59 @@
+"""Shared context for all TUI components.
+
+This module provides the TUIContext dataclass, which serves as the Python equivalent
+of OpenCode's nested provider pattern. It provides a single container for all TUI
+services and state that can be injected into components.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from glaip_sdk.cli.slash.tui.terminal import TerminalCapabilities
+from glaip_sdk.cli.slash.tui.theme import ThemeManager
+
+if TYPE_CHECKING:
+    from glaip_sdk.cli.slash.tui.toast import ToastBus
+
+
+@dataclass
+class TUIContext:
+    """Shared context for all TUI components (Python equivalent of OpenCode's providers).
+
+    This context provides access to all TUI services and state. Components that will
+    be implemented in later phases are typed as Optional and will be None initially.
+
+    Attributes:
+        terminal: Terminal capability detection results.
+        keybinds: Central keybind registry (Phase 3).
+        theme: Theme manager for light/dark mode and color tokens (Phase 2).
+        toasts: Toast notification bus (Phase 4).
+        clipboard: Clipboard adapter with OSC 52 support (Phase 4).
+    """
+
+    terminal: TerminalCapabilities
+    keybinds: object | None = None
+    theme: ThemeManager | None = None
+    toasts: ToastBus | None = None
+    clipboard: object | None = None
+
+    @classmethod
+    async def create(cls) -> TUIContext:
+        """Create a TUIContext instance with detected terminal capabilities.
+
+        This factory method detects terminal capabilities asynchronously and
+        returns a populated TUIContext instance. Other components (keybinds,
+        theme, toasts, clipboard) will be set incrementally as they are created.
+
+        Returns:
+            TUIContext instance with terminal capabilities detected.
+        """
+        terminal = await TerminalCapabilities.detect()
+        theme_name = os.getenv("AIP_TUI_THEME") or None
+        theme = ThemeManager(terminal, theme=theme_name)
+        return cls(terminal=terminal, theme=theme)

glaip_sdk/cli/slash/tui/keybind_registry.py

@@ -0,0 +1,235 @@
+"""Keybinding registry helpers for TUI applications."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from dataclasses import dataclass
+
+DEFAULT_LEADER = "ctrl+x"
+_LEADER_TOKEN = "<leader>"
+
+_MODIFIER_ORDER = ("ctrl", "alt", "shift", "meta")
+_MODIFIER_SYNONYMS = {
+    "control": "ctrl",
+    "ctl": "ctrl",
+    "cmd": "meta",
+    "command": "meta",
+    "option": "alt",
+    "return": "enter",
+}
+
+_KEY_SYNONYMS = {
+    "esc": "escape",
+}
+
+_KEY_DISPLAY = {
+    "escape": "Esc",
+    "enter": "Enter",
+    "space": "Space",
+    "tab": "Tab",
+    "backspace": "Backspace",
+}
+
+
+@dataclass(frozen=True, slots=True)
+class Keybind:
+    """A registered keybinding."""
+
+    action: str
+    sequence: tuple[str, ...]
+    description: str
+    category: str | None = None
+
+    def __repr__(self) -> str:
+        """Return a readable representation of the keybind."""
+        return (
+            f"Keybind(action={self.action!r}, sequence={self.sequence}, "
+            f"description={self.description!r}, category={self.category!r})"
+        )
+
+
+class KeybindRegistry:
+    """Central registry of keybindings and associated metadata."""
+
+    def __init__(self, *, leader: str = DEFAULT_LEADER) -> None:
+        """Initialize the registry."""
+        normalized = _normalize_chord(leader)
+        self._leader = normalized or DEFAULT_LEADER
+        self._keybinds: dict[str, Keybind] = {}
+
+    @property
+    def leader(self) -> str:
+        """Return the normalized leader chord."""
+        return self._leader
+
+    def register(
+        self,
+        *,
+        action: str,
+        key: str,
+        description: str,
+        category: str | None = None,
+    ) -> Keybind:
+        """Register a keybinding for an action."""
+        if action in self._keybinds:
+            raise ValueError(f"Action already registered: {action}")
+
+        sequence = parse_key_sequence(key)
+        keybind = Keybind(action=action, sequence=sequence, description=description, category=category)
+        self._keybinds[action] = keybind
+        return keybind
+
+    def get(self, action: str) -> Keybind | None:
+        """Return keybind for action, if present."""
+        return self._keybinds.get(action)
+
+    def actions(self) -> list[str]:
+        """Return sorted list of registered actions."""
+        return sorted(self._keybinds)
+
+    def matches(self, action: str, sequence: str | Iterable[str]) -> bool:
+        """Return True if the provided sequence matches the action's keybind."""
+        keybind = self._keybinds.get(action)
+        if keybind is None:
+            return False
+
+        candidate = _coerce_sequence(sequence)
+        return candidate == keybind.sequence
+
+    def format(self, action: str) -> str:
+        """Return a human-readable sequence for an action."""
+        keybind = self._keybinds.get(action)
+        if keybind is None:
+            return ""
+
+        return format_key_sequence(keybind.sequence, leader=self._leader)
+
+
+def parse_key_sequence(key: str) -> tuple[str, ...]:
+    """Parse a key sequence string into normalized tokens."""
+    tokens = [token for token in key.strip().split() if token]
+    normalized: list[str] = []
+
+    for token in tokens:
+        if token.lower() == _LEADER_TOKEN:
+            normalized.append(_LEADER_TOKEN)
+            continue
+
+        chord = _normalize_chord(token)
+        if chord:
+            normalized.append(chord)
+
+    return tuple(normalized)
+
+
+def format_key_sequence(sequence: tuple[str, ...], *, leader: str = DEFAULT_LEADER) -> str:
+    """Format a normalized sequence into a display string."""
+    rendered: list[str] = []
+
+    for token in sequence:
+        if token == _LEADER_TOKEN:
+            rendered.append(_format_token(leader))
+            continue
+        rendered.append(_format_token(token))
+
+    return " ".join(rendered)
+
+
+def _coerce_sequence(sequence: str | Iterable[str]) -> tuple[str, ...]:
+    if isinstance(sequence, str):
+        return parse_key_sequence(sequence)
+
+    tokens: list[str] = []
+    for token in sequence:
+        if not token:
+            continue
+        if token.lower() == _LEADER_TOKEN:
+            tokens.append(_LEADER_TOKEN)
+            continue
+        chord = _normalize_chord(token)
+        if chord:
+            tokens.append(chord)
+
+    return tuple(tokens)
+
+
+def _normalize_chord(chord: str) -> str:
+    """Normalize a key chord string to canonical form.
+
+    Normalization rules:
+    - Converts separators: both '-' and '+' are normalized to '+'
+    - Handles synonyms: 'control'/'ctl' -> 'ctrl', 'cmd'/'command' -> 'meta', 'option' -> 'alt'
+    - Deduplicates modifiers: 'ctrl+ctrl+l' -> 'ctrl+l'
+    - Orders modifiers: ctrl < alt < shift < meta (unknown modifiers sort last)
+    - Case-insensitive: 'Ctrl+L' == 'ctrl+l' == 'CTRL-L'
+
+    Args:
+        chord: Key chord string (e.g., "Ctrl+L", "ctrl-l", "CTRL+CTRL+L")
+
+    Returns:
+        Normalized chord string (e.g., "ctrl+l") or empty string if invalid.
+    """
+    parts = [part for part in chord.replace("-", "+").split("+") if part.strip()]
+    if not parts:
+        return ""
+
+    normalized_parts = [_normalize_key_part(part) for part in parts]
+    if len(normalized_parts) == 1:
+        return normalized_parts[0]
+
+    modifiers, key = normalized_parts[:-1], normalized_parts[-1]
+
+    seen: set[str] = set()
+    unique_mods: list[str] = []
+    for mod in modifiers:
+        if mod in seen:
+            continue
+        seen.add(mod)
+        unique_mods.append(mod)
+
+    unique_mods.sort(key=_modifier_sort_key)
+    return "+".join([*unique_mods, key])
+
+
+def _normalize_key_part(part: str) -> str:
+    token = part.strip().lower()
+    token = _MODIFIER_SYNONYMS.get(token, token)
+    return _KEY_SYNONYMS.get(token, token)
+
+
+def _modifier_sort_key(modifier: str) -> int:
+    try:
+        return _MODIFIER_ORDER.index(modifier)
+    except ValueError:
+        return len(_MODIFIER_ORDER)
+
+
+def _format_token(token: str) -> str:
+    if "+" in token:
+        return _format_chord(token)
+
+    return _KEY_DISPLAY.get(token, token)
+
+
+def _format_chord(chord: str) -> str:
+    parts = chord.split("+")
+    modifiers, key = parts[:-1], parts[-1]
+
+    rendered_mods: list[str] = []
+    for mod in modifiers:
+        if mod == "ctrl":
+            rendered_mods.append("Ctrl")
+        elif mod == "alt":
+            rendered_mods.append("Alt")
+        elif mod == "shift":
+            rendered_mods.append("Shift")
+        elif mod == "meta":
+            rendered_mods.append("Meta")
+        else:
+            rendered_mods.append(mod.title())
+
+    rendered_key = _KEY_DISPLAY.get(key, key)
+    if len(rendered_key) == 1 and rendered_key.isalpha():
+        rendered_key = rendered_key.upper()
+
+    return "+".join([*rendered_mods, rendered_key])

glaip_sdk/cli/slash/tui/loading.py

@@ -0,0 +1,58 @@
+"""Shared helpers for toggling Textual loading indicators.
+
+Note: uses Textual's built-in LoadingIndicator as the MVP; upgrade to the
+PulseIndicator from cli-textual-animated-indicators.md when shipped.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import TYPE_CHECKING
+
+try:  # pragma: no cover - optional dependency
+    from textual.widgets import LoadingIndicator
+except Exception:  # pragma: no cover - optional dependency
+    LoadingIndicator = None  # type: ignore[assignment]
+
+if TYPE_CHECKING:  # pragma: no cover - type checking aid
+    from textual.widgets import LoadingIndicator as _LoadingIndicatorType
+
+    LoadingIndicator: type[_LoadingIndicatorType] | None
+
+
+def _set_indicator_display(app: object, selector: str, visible: bool) -> None:
+    """Safely toggle a LoadingIndicator's display property."""
+    if LoadingIndicator is None:
+        return
+    try:
+        indicator = app.query_one(selector, LoadingIndicator)  # type: ignore[arg-type]
+        indicator.display = visible
+    except Exception:
+        # Ignore lookup/rendering errors to keep UI resilient
+        return
+
+
+def show_loading_indicator(
+    app: object,
+    selector: str,
+    *,
+    message: str | None = None,
+    set_status: Callable[..., None] | None = None,
+    status_style: str = "cyan",
+) -> None:
+    """Show a loading indicator and optionally set a status message."""
+    _set_indicator_display(app, selector, True)
+    if message and set_status:
+        try:
+            set_status(message, status_style)
+        except TypeError:
+            # Fallback for setters that accept only a single arg or kwargs
+            try:
+                set_status(message)
+            except Exception:
+                return
+
+
+def hide_loading_indicator(app: object, selector: str) -> None:
+    """Hide a loading indicator."""
+    _set_indicator_display(app, selector, False)