alloy-runtime-cli 0.1.0__py3-none-any.whl

cli/infrastructure/tui/formatters.py

@@ -0,0 +1,105 @@
+"""Common formatters for TUI table displays."""
+
+from datetime import datetime
+from typing import Any
+
+
+def truncate_text(text: str, max_length: int = 40) -> str:
+    """Truncate text with ellipsis if too long.
+
+    Args:
+        text: The text to truncate
+        max_length: Maximum length before truncation
+
+    Returns:
+        Truncated text with ellipsis, or original if short enough
+    """
+    if len(text) <= max_length:
+        return text
+    return text[: max_length - 3] + "..."
+
+
+# Threshold for considering content "long" and needing truncation
+LONG_CONTENT_THRESHOLD = 2000  # characters
+
+
+def truncate_long_content(
+    text: str,
+    *,
+    threshold: int = LONG_CONTENT_THRESHOLD,
+    head_chars: int = 50,
+    tail_chars: int = 50,
+) -> tuple[str, bool]:
+    """Truncate long content for display, preserving head and tail.
+
+    Designed for chat message display where very long injected content
+    (e.g., from @fragment()) would overwhelm the TUI.
+
+    Args:
+        text: The text to potentially truncate
+        threshold: Character count above which to truncate
+        head_chars: Number of characters to show from the start
+        tail_chars: Number of characters to show from the end
+
+    Returns:
+        Tuple of (truncated_text, was_truncated)
+        - truncated_text: The possibly truncated text
+        - was_truncated: True if content was truncated
+    """
+    if len(text) <= threshold:
+        return text, False
+
+    truncated_count = len(text) - head_chars - tail_chars
+    head = text[:head_chars]
+    tail = text[-tail_chars:]
+
+    # Build truncation indicator
+    truncated_text = f"{head}... [{truncated_count:,} chars truncated] ...{tail}"
+
+    return truncated_text, True
+
+
+def format_tags_list(
+    tags: list[dict[str, Any]], path_key: str = "tag_path", max_display: int = 2
+) -> str:
+    """Format a list of tags for table display.
+
+    Args:
+        tags: List of tag dicts
+        path_key: Key to extract tag path from each dict
+        max_display: Maximum number of tags to show before truncating
+
+    Returns:
+        Formatted string like "tag1, tag2 (+3)"
+    """
+    if not tags:
+        return "-"
+
+    tag_paths = [str(t.get(path_key, "")) for t in tags[:max_display]]
+    result = ", ".join(tag_paths)
+
+    if len(tags) > max_display:
+        result += f" (+{len(tags) - max_display})"
+
+    return result
+
+
+def format_datetime(dt: datetime | str | None, fmt: str = "%Y-%m-%d") -> str:
+    """Format a datetime for display.
+
+    Args:
+        dt: datetime object, ISO string, or None
+        fmt: strftime format string
+
+    Returns:
+        Formatted date string, or "-" if None/invalid
+    """
+    if not dt:
+        return "-"
+
+    try:
+        if isinstance(dt, str):
+            dt = datetime.fromisoformat(dt.replace("Z", "+00:00"))
+        return dt.strftime(fmt)
+    except (ValueError, AttributeError):
+        return str(dt)[:10] if dt else "-"

cli/infrastructure/tui/preview.py

@@ -0,0 +1,14 @@
+"""Preview pane formatting utilities for TUI applications."""
+
+
+def format_preview_field(label: str, value: str) -> str:
+    """Format a single label/value pair for preview pane using Rich markup.
+
+    Args:
+        label: The field label (e.g., "ID", "Name")
+        value: The field value
+
+    Returns:
+        Formatted string with Rich markup
+    """
+    return f"[bold]{label}:[/] {value}"

cli/infrastructure/tui/selectable.py

@@ -0,0 +1,198 @@
+"""Copy-on-select widgets for TUI applications.
+
+This module provides widgets that automatically copy selected text to the clipboard.
+These are useful for allowing users to select and copy text from the TUI without
+needing to use explicit keybindings.
+
+Available widgets:
+- CopyOnSelectTextArea: TextArea that copies selected text automatically
+- SelectableTextArea: Read-only TextArea for displaying selectable content
+"""
+
+import asyncio
+import os
+import subprocess
+from typing import Any, Protocol, cast
+
+import pyperclip
+from textual import on, work
+from textual.widgets import TextArea
+
+
+class SupportsClipboard(Protocol):
+    """Minimal protocol for app clipboard support."""
+
+    def copy_to_clipboard(self, text: str) -> None: ...
+
+
+class CopyOnSelectTextArea(TextArea):
+    """TextArea that automatically copies selected text to clipboard.
+
+    This widget extends TextArea to provide copy-on-select functionality.
+    When the user selects text, it is automatically copied to the clipboard
+    after a short debounce period (to avoid copying while the user is still
+    making their selection).
+
+    The widget uses pyperclip for clipboard access with a fallback to
+    OSC 52 escape sequences for terminals that support it, and pbcopy
+    on macOS as a final fallback.
+
+    Attributes:
+        show_copy_notification: Whether to show a notification when text is copied.
+            Defaults to False to avoid notification spam.
+    """
+
+    show_copy_notification: bool = False
+
+    def __init__(
+        self,
+        *args: Any,
+        show_copy_notification: bool = False,
+        **kwargs: Any,
+    ) -> None:
+        """Initialize the copy-on-select TextArea.
+
+        Args:
+            *args: Positional arguments passed to TextArea.
+            show_copy_notification: Whether to show notifications when copying.
+            **kwargs: Keyword arguments passed to TextArea.
+        """
+        super().__init__(*args, **kwargs)
+        self._last_selection = ""
+        self._pending_copy: str | None = None
+        self.show_copy_notification = show_copy_notification
+
+    @on(TextArea.SelectionChanged)
+    def _on_selection_changed(self, event: TextArea.SelectionChanged) -> None:
+        """Handle selection changes and schedule copy operation."""
+        if event.selection.is_empty:
+            self._pending_copy = None
+            return
+
+        selected = event.text_area.selected_text
+        if selected and selected != self._last_selection:
+            self._pending_copy = selected
+            self._schedule_copy()
+
+    @work(exclusive=True)
+    async def _schedule_copy(self) -> None:
+        """Wait for selection to stabilize before copying.
+
+        This debounces the copy operation to avoid copying while the user
+        is still making their selection. Waits 150ms after the last
+        selection change before actually copying.
+        """
+        await asyncio.sleep(0.15)
+        if self._pending_copy:
+            self._copy_to_clipboard(self._pending_copy)
+            self._last_selection = self._pending_copy
+
+    def _copy_to_clipboard(self, text: str) -> None:
+        """Copy text to clipboard using the best available method.
+
+        Tries pyperclip first, then falls back to OSC 52 or pbcopy
+        depending on the terminal environment.
+        """
+        try:
+            pyperclip.copy(text)
+            if self.show_copy_notification:
+                char_count = len(text)
+                label = f"{char_count} char{'s' if char_count != 1 else ''}"
+                self.notify(f"Copied {label}", timeout=1)
+        except Exception:
+            # Fallback to OSC 52 or pbcopy
+            self._copy_fallback(text)
+
+    def _copy_fallback(self, text: str) -> None:
+        """Fallback clipboard copy methods."""
+        term_program = os.environ.get("TERM_PROGRAM", "")
+
+        # Apple Terminal doesn't support OSC 52
+        if term_program == "Apple_Terminal":
+            self._copy_via_pbcopy(text)
+        else:
+            # Try OSC 52 (works over SSH in supported terminals)
+            try:
+                app_obj = getattr(self, "app", None)
+                if app_obj is None:
+                    raise RuntimeError("App not available")
+                app = cast(SupportsClipboard, app_obj)
+                app.copy_to_clipboard(text)
+            except Exception:
+                self._copy_via_pbcopy(text)
+
+    def _copy_via_pbcopy(self, text: str) -> None:
+        """Copy text using macOS pbcopy."""
+        try:
+            subprocess.run("pbcopy", text=True, input=text, check=True)
+        except subprocess.SubprocessError:
+            pass  # Silent failure - clipboard unavailable
+
+
+class SelectableTextArea(CopyOnSelectTextArea):
+    """Read-only TextArea for displaying selectable content.
+
+    This widget provides a read-only text area that users can select text from.
+    Selected text is automatically copied to the clipboard. This is useful for
+    displaying content like chat messages or preview panes where users need
+    to be able to copy specific portions of text.
+
+    The widget is styled to look like a Static widget but with selection
+    capabilities.
+
+    Attributes:
+        show_line_numbers: Always False for this widget.
+        read_only: Always True for this widget.
+    """
+
+    DEFAULT_CSS = """
+    SelectableTextArea {
+        background: transparent;
+        border: none;
+        padding: 0;
+        min-height: 1;
+    }
+
+    SelectableTextArea:focus {
+        border: none;
+    }
+
+    SelectableTextArea > .text-area--cursor-line {
+        background: transparent;
+    }
+    """
+
+    def __init__(
+        self,
+        text: str = "",
+        *,
+        id: str | None = None,
+        classes: str | None = None,
+        show_copy_notification: bool = False,
+    ) -> None:
+        """Initialize the selectable text area.
+
+        Args:
+            text: Initial text content to display.
+            id: The CSS ID of the widget.
+            classes: CSS classes for the widget.
+            show_copy_notification: Whether to show notifications when copying.
+        """
+        super().__init__(
+            text,
+            id=id,
+            classes=classes,
+            read_only=True,
+            show_line_numbers=False,
+            show_copy_notification=show_copy_notification,
+        )
+
+    def set_content(self, content: str) -> None:
+        """Set the text content of the widget.
+
+        This is a convenience method that replaces all text in the widget.
+
+        Args:
+            content: The new text content to display.
+        """
+        self.text = content

cli/infrastructure/validation/tag_validation.py

@@ -0,0 +1,74 @@
+"""Tag path validation utilities for CLI.
+
+Validates tag paths against server constraints before submission to provide
+immediate feedback in the TUI instead of server-side errors.
+
+This mirrors the server-side validation in domain/tag_validation.py.
+"""
+
+import re
+
+# Matches the database constraint: ^[a-z0-9_.]+$
+TAG_PATH_PATTERN = re.compile(r"^[a-z0-9_.]+$")
+
+# Maximum hierarchy depth (matches database constraint: nlevel(tag_path) <= 10)
+MAX_TAG_DEPTH = 10
+
+
+def validate_tag_path(tag_path: str) -> tuple[bool, str | None]:
+    """
+    Validate a tag path against database constraints.
+
+    Returns a tuple of (is_valid, error_message).
+    If valid, error_message is None.
+
+    Constraints:
+    - Only lowercase letters (a-z), numbers (0-9), underscores (_), and dots (.)
+    - Dots are level separators (e.g., 'marketing.email.newsletter')
+    - Maximum 10 levels deep
+    - Cannot be empty
+    - Cannot start or end with a dot
+    - Cannot have consecutive dots
+
+    Args:
+        tag_path: The tag path to validate (e.g., 'marketing.email')
+
+    Returns:
+        Tuple of (is_valid, error_message or None)
+    """
+    if not tag_path:
+        return False, "Tag path cannot be empty"
+
+    # Check for uppercase letters (common mistake)
+    if tag_path != tag_path.lower():
+        suggestion = tag_path.lower()
+        return False, f"Must be lowercase. Try: {suggestion}"
+
+    # Check for hyphens (common mistake - suggest underscore)
+    if "-" in tag_path:
+        suggestion = tag_path.replace("-", "_")
+        return False, f"Use underscores, not hyphens. Try: {suggestion}"
+
+    # Check for spaces
+    if " " in tag_path:
+        suggestion = tag_path.replace(" ", "_")
+        return False, f"No spaces allowed. Try: {suggestion}"
+
+    # Check for consecutive dots
+    if ".." in tag_path:
+        return False, "Cannot contain consecutive dots (..)"
+
+    # Check for leading/trailing dots
+    if tag_path.startswith(".") or tag_path.endswith("."):
+        return False, "Cannot start or end with a dot"
+
+    # Check general format (must match ^[a-z0-9_.]+$)
+    if not TAG_PATH_PATTERN.match(tag_path):
+        return False, "Only lowercase letters, numbers, underscores, and dots allowed"
+
+    # Check depth (count dots + 1 = levels)
+    depth = tag_path.count(".") + 1
+    if depth > MAX_TAG_DEPTH:
+        return False, f"Too deep ({depth} levels). Maximum is {MAX_TAG_DEPTH}"
+
+    return True, None