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

cli/infrastructure/filter_parser.py

@@ -0,0 +1,256 @@
+"""Shorthand filter parser for JSONB structured content filtering.
+
+Provides a concise syntax for building structured filters without writing JSON.
+Multiple -w options are combined with AND logic.
+
+Syntax Reference:
+    field=value         Equal (string)
+    field:=value        Equal (JSON: number, bool, null, array, object)
+    field!=value        Not equal
+    field>value         Greater than
+    field>=value        Greater than or equal
+    field<value         Less than
+    field<=value        Less than or equal
+    field~=pattern      Case-insensitive LIKE (ilike)
+    field~~pattern      Case-sensitive LIKE
+    field?=a,b,c        In list (comma-separated)
+    field!?=a,b,c       Not in list
+    field?              Key exists
+    field!?             Key does not exist
+    field@=jsonb        JSONB contains
+
+Nested paths use dot notation:
+    data.count>=10
+    metadata.user.email~=%@gmail.com%
+
+Examples:
+    -w status=complete                    # status equals "complete"
+    -w "count:=10"                        # count equals 10 (number)
+    -w "active:=true"                     # active equals true (boolean)
+    -w "data.score>=85"                   # nested path, gte comparison
+    -w "email~=%@example.com%"            # case-insensitive pattern match
+    -w "status?=pending,review,approved"  # status in list
+    -w "error?"                           # error key exists
+    -w "deprecated!?"                     # deprecated key does not exist
+
+Usage with Typer:
+    from cli.infrastructure.filter_parser import parse_where_filters
+
+    @app.command()
+    def my_command(
+        where: Annotated[
+            list[str] | None,
+            typer.Option("--where", "-w", help="Filter conditions"),
+        ] = None,
+    ) -> None:
+        filter_spec = parse_where_filters(where)
+        # filter_spec is ConditionSpec | LogicalSpec | None
+"""
+
+import json
+import re
+from typing import Any, cast
+
+import typer
+
+from alloy_runtime_types.dtos.structured_filter import (
+    ConditionOperator,
+    ConditionSpec,
+    LogicalSpec,
+)
+
+# Operator patterns ordered by specificity (longest match first)
+# Format: (regex_pattern, literal_str, operator, has_value, value_parser)
+# The regex_pattern is for matching, literal_str is the actual operator string
+OPERATOR_PATTERNS: list[tuple[str, str, str, bool, str]] = [
+    # Multi-char operators first (order matters - longer/more specific first)
+    (r"!\?=", "!?=", "nin", True, "list"),  # not in list
+    (r"\?=", "?=", "in", True, "list"),  # in list
+    (r">=", ">=", "gte", True, "auto"),  # greater than or equal
+    (r"<=", "<=", "lte", True, "auto"),  # less than or equal
+    (r"~=", "~=", "ilike", True, "string"),  # case-insensitive like
+    (r"~~", "~~", "like", True, "string"),  # case-sensitive like
+    (r"@=", "@=", "contains", True, "json"),  # jsonb contains
+    (r":=", ":=", "eq", True, "json"),  # equal with JSON value
+    (r"!=", "!=", "ne", True, "auto"),  # not equal
+    (r"!\?", "!?", "not_exists", False, "none"),  # key does not exist
+    (r"\?", "?", "exists", False, "none"),  # key exists (must be after ?=)
+    # Single-char operators last
+    (r">", ">", "gt", True, "auto"),  # greater than
+    (r"<", "<", "lt", True, "auto"),  # less than
+    (r"=", "=", "eq", True, "auto"),  # equal (default string)
+]
+
+# Compile regex pattern for finding operators
+# Matches field name, then operator, then optional value
+FILTER_REGEX = re.compile(
+    r"^([a-zA-Z_][a-zA-Z0-9_]*(?:\.[a-zA-Z_][a-zA-Z0-9_]*)*)"  # field path
+    r"(" + "|".join(p[0] for p in OPERATOR_PATTERNS) + r")"  # operator
+    r"(.*)$"  # value (may be empty)
+)
+
+
+def _parse_auto_value(value: str) -> Any:
+    """Parse a value with automatic type detection.
+
+    Tries JSON parsing first, falls back to string.
+    """
+    if not value:
+        return ""
+
+    # Try to parse as JSON (handles numbers, bools, null)
+    try:
+        return json.loads(value)
+    except json.JSONDecodeError:
+        # Return as string
+        return value
+
+
+def _parse_json_value(value: str, field: str) -> Any:
+    """Parse a value as JSON, raising error if invalid."""
+    try:
+        return json.loads(value)
+    except json.JSONDecodeError as e:
+        raise typer.BadParameter(
+            f"Invalid JSON value for field '{field}': {value}. Error: {e}"
+        )
+
+
+def _parse_list_value(value: str) -> list[str]:
+    """Parse a comma-separated list of values."""
+    if not value:
+        return []
+    return [v.strip() for v in value.split(",") if v.strip()]
+
+
+def parse_single_filter(expr: str) -> ConditionSpec:
+    """Parse a single filter expression into a ConditionSpec.
+
+    Args:
+        expr: Filter expression (e.g., "status=complete", "count>=10")
+
+    Returns:
+        ConditionSpec for the filter
+
+    Raises:
+        typer.BadParameter: If expression is invalid
+    """
+    expr = expr.strip()
+    if not expr:
+        raise typer.BadParameter("Empty filter expression")
+
+    match = FILTER_REGEX.match(expr)
+    if not match:
+        raise typer.BadParameter(
+            f"Invalid filter syntax: '{expr}'. "
+            "Expected format: field<op>value (e.g., status=complete, count>=10)"
+        )
+
+    field = match.group(1)
+    op_str = match.group(2)
+    raw_value = match.group(3)
+
+    # Find the operator details by matching the literal string
+    op_name = None
+    has_value = True
+    value_parser = "auto"
+
+    for _regex_pattern, literal_str, name, needs_value, parser in OPERATOR_PATTERNS:
+        if op_str == literal_str:
+            op_name = name
+            has_value = needs_value
+            value_parser = parser
+            break
+
+    if op_name is None:
+        raise typer.BadParameter(f"Unknown operator in: '{expr}'")
+
+    # Validate value presence
+    if has_value and not raw_value:
+        raise typer.BadParameter(f"Missing value for operator '{op_str}' in: '{expr}'")
+
+    if not has_value and raw_value:
+        raise typer.BadParameter(
+            f"Operator '{op_str}' does not take a value, but got: '{raw_value}'"
+        )
+
+    # Parse the value based on type
+    value: Any = None
+    if has_value:
+        if value_parser == "json":
+            value = _parse_json_value(raw_value, field)
+        elif value_parser == "list":
+            value = _parse_list_value(raw_value)
+        elif value_parser == "string":
+            value = raw_value
+        else:  # auto
+            value = _parse_auto_value(raw_value)
+
+    # For exists/not_exists, value should be None (or True for consistency)
+    if op_name in ("exists", "not_exists"):
+        value = True
+
+    # Cast op_name to the literal type since we've validated it above
+    op_literal = cast(ConditionOperator, op_name)
+    return ConditionSpec(field=field, op=op_literal, value=value)
+
+
+def parse_where_filters(
+    filters: list[str] | None,
+) -> ConditionSpec | LogicalSpec | None:
+    """Parse multiple -w filter expressions into a filter spec.
+
+    Multiple filters are combined with AND logic.
+
+    Args:
+        filters: List of filter expressions from repeated -w options
+
+    Returns:
+        - None if no filters provided
+        - ConditionSpec if single filter
+        - LogicalSpec (AND) if multiple filters
+
+    Raises:
+        typer.BadParameter: If any expression is invalid
+
+    Examples:
+        >>> parse_where_filters(["status=complete"])
+        ConditionSpec(field="status", op="eq", value="complete")
+
+        >>> parse_where_filters(["status=complete", "count>=10"])
+        LogicalSpec(op="and", conditions=[...])
+    """
+    if not filters:
+        return None
+
+    conditions = [parse_single_filter(f) for f in filters]
+
+    if len(conditions) == 1:
+        return conditions[0]
+
+    # Cast to the expected type for LogicalSpec
+    return LogicalSpec(op="and", conditions=list(conditions))
+
+
+def merge_filter_specs(
+    where_spec: ConditionSpec | LogicalSpec | None,
+    json_spec: ConditionSpec | LogicalSpec | None,
+) -> ConditionSpec | LogicalSpec | None:
+    """Merge filter specs from -w and --structured-filter options.
+
+    If both are provided, combines them with AND logic.
+
+    Args:
+        where_spec: Filter spec from -w options
+        json_spec: Filter spec from --structured-filter JSON
+
+    Returns:
+        Combined filter spec, or None if both are None
+    """
+    if where_spec is None:
+        return json_spec
+    if json_spec is None:
+        return where_spec
+
+    # Both exist - combine with AND
+    return LogicalSpec(op="and", conditions=[where_spec, json_spec])

cli/infrastructure/formatters/base.py

@@ -0,0 +1,99 @@
+"""Base formatter interface for CLI output.
+
+Defines the contract that all output formatters must implement.
+"""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    pass
+
+
+@dataclass
+class ColumnMeta:
+    """Metadata about a column for formatters that need layout info.
+
+    This is a simplified view of ColumnConfig passed to formatters.
+    """
+
+    label: str
+    compact_line: int = 1
+    compact_style: str | None = None
+    width: int | None = None
+
+
+class Formatter(ABC):
+    """Abstract base class for output formatters.
+
+    Formatters transform data into specific output formats (Rich tables, JSON, YAML, etc.).
+    """
+
+    @abstractmethod
+    def format_entity(self, data: dict[str, Any], title: str | None = None) -> Any:
+        """Format a single entity's details as key-value pairs.
+
+        Args:
+            data: Dictionary mapping field labels to values
+            title: Optional title for the entity display
+
+        Returns:
+            Formatted output (str for JSON, Rich renderable for Rich, etc.)
+        """
+        pass
+
+    @abstractmethod
+    def format_list(
+        self,
+        items: list[dict[str, Any]],
+        title: str | None = None,
+        columns: list[ColumnMeta] | None = None,
+    ) -> Any:
+        """Format a list of items as a table or similar structure.
+
+        Args:
+            items: List of dictionaries, each representing one row
+            title: Optional title for the list display
+            columns: Optional column metadata for layout-aware formatters
+
+        Returns:
+            Formatted output (str for JSON, Rich renderable for Rich, etc.)
+        """
+        pass
+
+    @abstractmethod
+    def format_success(self, message: str) -> str:
+        """Format a success message.
+
+        Args:
+            message: Success message text
+
+        Returns:
+            Formatted success message
+        """
+        pass
+
+    @abstractmethod
+    def format_info(self, message: str) -> str:
+        """Format an informational message.
+
+        Args:
+            message: Info message text
+
+        Returns:
+            Formatted info message
+        """
+        pass
+
+    @abstractmethod
+    def format_warning(self, message: str) -> str:
+        """Format a warning message.
+
+        Args:
+            message: Warning message text
+
+        Returns:
+            Formatted warning message
+        """
+        pass

cli/infrastructure/formatters/compact_formatter.py

@@ -0,0 +1,245 @@
+"""Compact block formatter for copy-friendly terminal output.
+
+Renders list items as 2-line blocks:
+- Line 1 (primary): ID + key metadata (fixed-width, colored)
+- Line 2 (detail): Description/content (dimmed, full-width)
+
+No borders = easy copy-paste. Wraps naturally on narrow terminals.
+Inspired by gh (GitHub CLI) and kubectl output styles.
+"""
+
+from typing import Any
+
+from rich.console import Console, Group, RenderableType
+from rich.text import Text
+
+from cli.infrastructure.console import get_console
+from cli.infrastructure.formatters.base import ColumnMeta, Formatter
+
+
+# Default styles for compact format columns
+DEFAULT_STYLES = {
+    "id": "cyan",
+    "uuid": "cyan",
+    "name": "white bold",
+    "type": "magenta",
+    "model": "green",
+    "provider": "green",
+    "date": "blue",
+    "created": "blue",
+    "time": "blue",
+    "version": "yellow",
+    "visibility": "dim",
+    "tags": "dim italic",
+    "description": "dim",
+    "content": "dim",
+    "status": "yellow",
+}
+
+
+def _infer_style(label: str) -> str:
+    """Infer a style based on column label.
+
+    Args:
+        label: Column header label
+
+    Returns:
+        Rich style string
+    """
+    label_lower = label.lower()
+    for key, style in DEFAULT_STYLES.items():
+        if key in label_lower:
+            return style
+    return "white"
+
+
+class CompactFormatter(Formatter):
+    """Formatter that renders items as compact 2-line blocks.
+
+    Line 1: Primary metadata (ID, type, model, date) - colored, spaced
+    Line 2: Detail content (description, content preview) - dimmed, indented
+
+    Benefits:
+    - No borders = double-click to select any field
+    - Line 2 wraps naturally on narrow terminals
+    - Easy to scan vertically (IDs align, models align)
+    """
+
+    def __init__(self, console: Console | None = None):
+        """Initialize compact formatter.
+
+        Args:
+            console: Optional Rich console instance. Uses shared console if not provided.
+        """
+        self.console = console or get_console()
+
+    def format_entity(self, data: dict[str, Any], title: str | None = None) -> Text:
+        """Format entity details as compact key-value block.
+
+        For single entities, we use a simple key: value format without borders.
+
+        Args:
+            data: Dictionary mapping field labels to values
+            title: Optional title for the entity
+
+        Returns:
+            Rich Text object ready for rendering
+        """
+        output = Text()
+
+        if title:
+            output.append(f"{title}\n", style="bold")
+            output.append("-" * len(title) + "\n", style="dim")
+
+        for field, value in data.items():
+            display_value = "-" if value is None else str(value)
+            output.append(f"{field}: ", style="cyan")
+            output.append(f"{display_value}\n", style="white")
+
+        return output
+
+    def format_list(
+        self,
+        items: list[dict[str, Any]],
+        title: str | None = None,
+        columns: list[ColumnMeta] | None = None,
+    ) -> Group:
+        """Format list of items as compact 2-line blocks.
+
+        Args:
+            items: List of dictionaries representing rows
+            title: Optional title for the list
+            columns: Column metadata for layout (line assignment, styles)
+
+        Returns:
+            Rich Group of Text objects ready for rendering
+        """
+        if not items:
+            return Group(Text(self.format_info("No items to display")))
+
+        renderables: list[RenderableType] = []
+
+        # Add title if provided
+        if title:
+            title_text = Text()
+            title_text.append(f"{title}\n", style="bold")
+            renderables.append(title_text)
+
+        # Build column lookup by label
+        col_meta_map: dict[str, ColumnMeta] = {}
+        if columns:
+            for col in columns:
+                col_meta_map[col.label] = col
+
+        # Separate columns into line 1 (primary) and line 2 (detail)
+        line1_labels: list[str] = []
+        line2_labels: list[str] = []
+        if columns:
+            for col in columns:
+                if col.compact_line == 2:
+                    line2_labels.append(col.label)
+                else:
+                    line1_labels.append(col.label)
+        else:
+            # Fallback: all columns on line 1
+            if items:
+                line1_labels = list(items[0].keys())
+
+        # Render each item as a 2-line block
+        for item in items:
+            block = Text()
+
+            # Line 1: Primary metadata (spaced columns)
+            line1_parts: list[tuple[str, str]] = []
+            for label in line1_labels:
+                raw_value = item.get(label)
+                if raw_value is None:
+                    value = "-"
+                else:
+                    value = str(raw_value)
+
+                # Get style from column meta or infer from label
+                meta = col_meta_map.get(label)
+                if meta and meta.compact_style:
+                    style: str = meta.compact_style
+                else:
+                    style = _infer_style(label)
+
+                # Apply width padding if specified
+                if meta and meta.width:
+                    value = f"{value:<{meta.width}}"
+
+                line1_parts.append((value, style))
+
+            # Join line 1 parts with double space
+            for i, (value, style) in enumerate(line1_parts):
+                if i > 0:
+                    block.append("  ", style="default")
+                block.append(value, style=style)
+
+            block.append("\n")
+
+            # Line 2: Detail content (indented, dimmed)
+            if line2_labels:
+                detail_parts: list[tuple[str, str]] = []
+                for label in line2_labels:
+                    raw_value = item.get(label)
+                    if raw_value is None or raw_value == "-":
+                        continue
+                    value = str(raw_value)
+
+                    # Get style - default to dim for detail line
+                    meta = col_meta_map.get(label)
+                    if meta and meta.compact_style:
+                        style = meta.compact_style
+                    else:
+                        style = "dim"
+
+                    detail_parts.append((value, style))
+
+                if detail_parts:
+                    block.append("   ")  # 3-space indent
+                    for i, (value, style) in enumerate(detail_parts):
+                        if i > 0:
+                            block.append(" · ", style="dim")
+                        block.append(value, style=style)
+                    block.append("\n")
+
+            # Add blank line between items
+            block.append("\n")
+            renderables.append(block)
+
+        return Group(*renderables)
+
+    def format_success(self, message: str) -> str:
+        """Format success message with checkmark.
+
+        Args:
+            message: Success message text
+
+        Returns:
+            Rich markup string
+        """
+        return f"[green]✓[/green] {message}"
+
+    def format_info(self, message: str) -> str:
+        """Format info message with info icon.
+
+        Args:
+            message: Info message text
+
+        Returns:
+            Rich markup string
+        """
+        return f"[blue]ℹ[/blue] {message}"
+
+    def format_warning(self, message: str) -> str:
+        """Format warning message with warning icon.
+
+        Args:
+            message: Warning message text
+
+        Returns:
+            Rich markup string
+        """
+        return f"[yellow]⚠[/yellow] {message}"

cli/infrastructure/formatters/json_formatter.py

@@ -0,0 +1,84 @@
+"""JSON formatter for machine-readable output.
+
+Provides JSON output suitable for scripting and automation.
+"""
+
+import json
+from typing import Any
+
+from cli.infrastructure.formatters.base import ColumnMeta, Formatter
+
+
+class JsonFormatter(Formatter):
+    """Formatter that outputs JSON for scripting and automation."""
+
+    def __init__(self, indent: int = 2):
+        """Initialize JSON formatter.
+
+        Args:
+            indent: Number of spaces for JSON indentation
+        """
+        self.indent = indent
+
+    def format_entity(self, data: dict[str, Any], title: str | None = None) -> str:
+        """Format entity as JSON object.
+
+        Args:
+            data: Dictionary mapping field labels to values
+            title: Ignored for JSON output
+
+        Returns:
+            JSON string
+        """
+        return json.dumps(data, indent=self.indent, default=str)
+
+    def format_list(
+        self,
+        items: list[dict[str, Any]],
+        title: str | None = None,
+        columns: list[ColumnMeta] | None = None,
+    ) -> str:
+        """Format list as JSON array.
+
+        Args:
+            items: List of dictionaries
+            title: Ignored for JSON output
+            columns: Ignored for JSON output
+
+        Returns:
+            JSON string
+        """
+        return json.dumps(items, indent=self.indent, default=str)
+
+    def format_success(self, message: str) -> str:
+        """Format success message as JSON.
+
+        Args:
+            message: Success message text
+
+        Returns:
+            JSON string with status and message
+        """
+        return json.dumps({"status": "success", "message": message}, indent=self.indent)
+
+    def format_info(self, message: str) -> str:
+        """Format info message as JSON.
+
+        Args:
+            message: Info message text
+
+        Returns:
+            JSON string with status and message
+        """
+        return json.dumps({"status": "info", "message": message}, indent=self.indent)
+
+    def format_warning(self, message: str) -> str:
+        """Format warning message as JSON.
+
+        Args:
+            message: Warning message text
+
+        Returns:
+            JSON string with status and message
+        """
+        return json.dumps({"status": "warning", "message": message}, indent=self.indent)