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

glaip_sdk/cli/slash/tui/clipboard.py

@@ -0,0 +1,195 @@
+"""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"],
+}
+
+_ENV_CLIPBOARD_METHOD = "AIP_TUI_CLIPBOARD_METHOD"
+_ENV_CLIPBOARD_FORCE = "AIP_TUI_CLIPBOARD_FORCE"
+_ENV_METHOD_MAP = {
+    "osc52": ClipboardMethod.OSC52,
+    "pbcopy": ClipboardMethod.PBCOPY,
+    "xclip": ClipboardMethod.XCLIP,
+    "xsel": ClipboardMethod.XSEL,
+    "wl-copy": ClipboardMethod.WL_COPY,
+    "wl_copy": ClipboardMethod.WL_COPY,
+    "clip": ClipboardMethod.CLIP,
+    "none": ClipboardMethod.NONE,
+}
+
+
+def _resolve_env_method() -> ClipboardMethod | None:
+    raw = os.getenv(_ENV_CLIPBOARD_METHOD)
+    if not raw:
+        return None
+    value = raw.strip().lower()
+    if value in ("auto", "default"):
+        return None
+    return _ENV_METHOD_MAP.get(value)
+
+
+def _is_env_force_enabled() -> bool:
+    raw = os.getenv(_ENV_CLIPBOARD_FORCE)
+    if not raw:
+        return False
+    return raw.strip().lower() in {"1", "true", "yes", "on"}
+
+
+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._force_method = False
+        if method is not None:
+            self._method = method
+        else:
+            env_method = _resolve_env_method()
+            if env_method is not None:
+                self._method = env_method
+                self._force_method = _is_env_force_enabled()
+            else:
+                self._method = 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:
+            if self._force_method:
+                return ClipboardResult(False, self._method, "Forced clipboard method unavailable.")
+            return self._copy_osc52(text, writer=writer)
+
+        result = self._copy_subprocess(command, text)
+        if not result.success:
+            if self._force_method:
+                return result
+            return self._copy_osc52(text, writer=writer)
+
+        return result
+
+    def _detect_method(self) -> ClipboardMethod:
+        system = platform.system()
+        method = ClipboardMethod.NONE
+        if system == "Darwin":
+            method = self._detect_darwin_method()
+        elif system == "Linux":
+            method = self._detect_linux_method()
+        elif system == "Windows":
+            method = self._detect_windows_method()
+
+        if method is not ClipboardMethod.NONE:
+            return method
+
+        if self._terminal.osc52 if self._terminal else detect_osc52_support():
+            return ClipboardMethod.OSC52
+
+        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,87 @@
+"""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 glaip_sdk.cli.account_store import get_account_store
+from glaip_sdk.cli.slash.tui.clipboard import ClipboardAdapter
+from glaip_sdk.cli.slash.tui.keybind_registry import KeybindRegistry
+from glaip_sdk.cli.slash.tui.terminal import TerminalCapabilities
+from glaip_sdk.cli.slash.tui.theme import ThemeManager
+from glaip_sdk.cli.slash.tui.toast import ToastBus
+from glaip_sdk.cli.tui_settings import load_tui_settings
+
+
+@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: KeybindRegistry | None = None
+    theme: ThemeManager | None = None
+    toasts: ToastBus | None = None
+    clipboard: ClipboardAdapter | None = None
+
+    @classmethod
+    async def create(cls, *, detect_osc11: bool = True) -> TUIContext:
+        """Create a TUIContext instance with detected terminal capabilities.
+
+        This factory method detects terminal capabilities asynchronously and
+        returns a populated TUIContext instance with all services initialized
+        (keybinds, theme, toasts, clipboard).
+
+        Args:
+            detect_osc11: When False, skip OSC 11 background detection.
+
+        Returns:
+            TUIContext instance with all services initialized.
+        """
+        terminal = await TerminalCapabilities.detect(detect_osc11=detect_osc11)
+        store = get_account_store()
+        settings = load_tui_settings(store=store)
+
+        # Handle env var override: normalize empty strings and "default" to None
+        # Empty string from os.getenv() is falsy, so strip() result becomes None in the or expression
+        env_theme = os.getenv("AIP_TUI_THEME")
+        env_theme = env_theme.strip() if env_theme else None
+        if env_theme and env_theme.lower() == "default":
+            env_theme = None
+
+        theme_name = env_theme or settings.theme_name
+        theme = ThemeManager(
+            terminal,
+            mode=settings.theme_mode,
+            theme=theme_name,
+            settings_store=store,
+        )
+        keybinds = KeybindRegistry()
+        toasts = ToastBus()
+        clipboard = ClipboardAdapter(terminal=terminal)
+        return cls(
+            terminal=terminal,
+            keybinds=keybinds,
+            theme=theme,
+            toasts=toasts,
+            clipboard=clipboard,
+        )

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/layouts/__init__.py

@@ -0,0 +1,14 @@
+"""Layout components for TUI applications.
+
+This package provides reusable layout components following the Harlequin pattern
+for multi-pane data-rich screens.
+"""
+
+from __future__ import annotations
+
+try:  # pragma: no cover - optional dependency
+    from glaip_sdk.cli.slash.tui.layouts.harlequin import HarlequinScreen
+except Exception:  # pragma: no cover - optional dependency
+    HarlequinScreen = None  # type: ignore[assignment, misc]
+
+__all__ = ["HarlequinScreen"]

glaip_sdk/cli/slash/tui/layouts/harlequin.py

@@ -0,0 +1,160 @@
+"""Harlequin layout base class for multi-pane TUI screens.
+
+This module provides the HarlequinScreen base class, which implements a modern
+multi-pane "Harlequin" layout pattern for data-rich TUI screens. The layout uses
+a 25/75 split with a list on the left and detail content on the right.
+
+The Harlequin pattern is inspired by the Harlequin SQL client and provides:
+- Left Pane (25%): ListView or compact table for item selection
+- Right Pane (75%): Detail dashboard showing all fields, status, and action buttons
+- Black background (#000000) that overrides terminal transparency
+- Primary Blue borders (#005CB8)
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+try:  # pragma: no cover - optional dependency
+    from textual.containers import Container, Horizontal, Vertical
+    from textual.screen import Screen
+except Exception:  # pragma: no cover - optional dependency
+
+    class Screen:  # type: ignore[no-redef]
+        """Fallback Screen stub when Textual is unavailable."""
+
+        def __class_getitem__(cls, _):
+            """Return the class for typing subscripts."""
+            return cls
+
+    Horizontal = None  # type: ignore[assignment]
+    Vertical = None  # type: ignore[assignment]
+    Container = None  # type: ignore[assignment]
+
+if TYPE_CHECKING:
+    from glaip_sdk.cli.slash.tui.context import TUIContext
+
+try:  # pragma: no cover - optional dependency
+    from glaip_sdk.cli.slash.tui.toast import Toast
+except Exception:  # pragma: no cover - optional dependency
+    Toast = None  # type: ignore[assignment, misc]
+
+# GDP Labs Brand Palette
+PRIMARY_BLUE = "#005CB8"
+BLACK_BACKGROUND = "#000000"
+
+
+class HarlequinScreen(Screen[None]):  # type: ignore[misc]
+    """Base class for Harlequin-style multi-pane screens.
+
+    This screen provides a 25/75 split layout with a left pane for navigation
+    and a right pane for details. The layout uses a black background that
+    overrides terminal transparency and primary blue borders.
+
+    Subclasses should override `compose()` to add their specific widgets to
+    the left and right panes. Use the container IDs "left-pane" and "right-pane"
+    to target specific panes in CSS or when querying widgets.
+
+    Example:
+        ```python
+        class AccountHarlequinScreen(HarlequinScreen):
+            def compose(self) -> ComposeResult:
+                yield from super().compose()
+                # Add widgets to left and right panes
+                self.query_one("#left-pane").mount(AccountListView())
+                self.query_one("#right-pane").mount(AccountDetailView())
+        ```
+
+    CSS:
+        The screen includes default styling for the Harlequin layout:
+        - Black background (#000000) for the entire screen
+        - Primary blue borders (#005CB8) for panes
+        - 25% width for left pane, 75% width for right pane
+    """
+
+    CSS = """
+    HarlequinScreen {
+        background: #000000;
+        layers: base toasts;
+    }
+
+    #harlequin-container {
+        width: 100%;
+        height: 100%;
+    }
+
+    #left-pane {
+        width: 25%;
+        border: solid #005CB8;
+        background: #000000;
+    }
+
+    #right-pane {
+        width: 75%;
+        border: solid #005CB8;
+        background: #000000;
+    }
+
+    #toast-container {
+        width: 100%;
+        height: auto;
+        dock: top;
+        align: right top;
+        layer: toasts;
+    }
+    """
+
+    def __init__(
+        self,
+        *,
+        ctx: TUIContext | None = None,
+        name: str | None = None,
+        id: str | None = None,
+        classes: str | None = None,
+    ) -> None:
+        """Initialize the Harlequin screen.
+
+        Args:
+            ctx: Optional TUI context for accessing services (keybinds, theme, toasts, clipboard).
+            name: Optional name for the screen.
+            id: Optional ID for the screen.
+            classes: Optional CSS classes for the screen.
+        """
+        super().__init__(name=name, id=id, classes=classes)
+        self._ctx: TUIContext | None = ctx
+
+    def compose(self) -> Any:
+        """Compose the Harlequin layout with left and right panes.
+
+        This method creates the base 25/75 split layout. Subclasses should
+        call `super().compose()` and then add their specific widgets to the
+        left and right panes.
+
+        Returns:
+            ComposeResult yielding the base layout containers.
+        """
+        if Horizontal is None or Vertical is None or Container is None:
+            return
+
+        # Main container with horizontal split (25/75)
+        yield Horizontal(
+            Vertical(id="left-pane"),
+            Vertical(id="right-pane"),
+            id="harlequin-container",
+        )
+
+        # Toast container for notifications
+        if Toast is not None and Container is not None:
+            yield Container(Toast(), id="toast-container")
+
+    @property
+    def ctx(self) -> TUIContext | None:
+        """Get the TUI context if available.
+
+        Returns:
+            TUIContext instance or None if not provided.
+        """
+        return self._ctx