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

cli/commands/content/list/export_formatters.py

@@ -0,0 +1,409 @@
+"""Export formatters for content list results.
+
+Provides various output formats for exporting content items:
+- markdown: Markdown list or grouped headers
+- xml: XML tags with content
+- numbered: Numbered list
+- plain: Plain text (content only)
+- json: JSON array
+"""
+
+import json
+from abc import ABC, abstractmethod
+from typing import Any
+
+from alloy_runtime_types.dtos.content import ContentPartItemResponse
+
+
+class ContentExportFormatter(ABC):
+    """Base class for content export formatters."""
+
+    @abstractmethod
+    def format(
+        self, items: list[ContentPartItemResponse], group_by: str | None = None
+    ) -> str:
+        """Format content items for export.
+
+        Args:
+            items: List of content part items to format
+            group_by: Optional tag prefix to group items by
+
+        Returns:
+            Formatted string ready for output
+        """
+        pass
+
+    def _get_content(self, item: ContentPartItemResponse) -> str:
+        """Extract content text from item.
+
+        Args:
+            item: Content part item
+
+        Returns:
+            Content as string (text or JSON-serialized structured content)
+        """
+        if item.content_text:
+            return item.content_text
+        if item.content_structured:
+            return json.dumps(item.content_structured, ensure_ascii=False)
+        return ""
+
+    def _group_items(
+        self, items: list[ContentPartItemResponse], group_by: str
+    ) -> dict[str, list[ContentPartItemResponse]]:
+        """Group items by tag path matching the group_by prefix.
+
+        Examples:
+            group_by="ads" groups by first subtag: ads.headline -> "headline"
+            group_by="ads.headline" groups by exact match -> "ads.headline"
+
+        Args:
+            items: List of content items to group
+            group_by: Tag prefix to group by
+
+        Returns:
+            Dictionary mapping group names to lists of items
+        """
+        groups: dict[str, list[ContentPartItemResponse]] = {}
+        ungrouped: list[ContentPartItemResponse] = []
+
+        for item in items:
+            matched = False
+            for tag in item.tags:
+                if tag.tag_path.startswith(group_by):
+                    # Extract the grouping key
+                    remaining = tag.tag_path[len(group_by) :].lstrip(".")
+                    if remaining:
+                        # Use first component after prefix
+                        key = remaining.split(".")[0]
+                    else:
+                        # Exact match - use full tag path
+                        key = tag.tag_path
+
+                    if key not in groups:
+                        groups[key] = []
+                    groups[key].append(item)
+                    matched = True
+                    break
+
+            if not matched:
+                ungrouped.append(item)
+
+        if ungrouped:
+            groups["(ungrouped)"] = ungrouped
+
+        return groups
+
+
+class MarkdownFormatter(ContentExportFormatter):
+    """Format content as markdown with numbered headers.
+
+    Output format (flat):
+        ## Item 1
+
+        <content>
+
+        ## Item 2
+
+        <content>
+
+    Output format (grouped):
+        ## group_name
+
+        ### Item 1
+
+        <content>
+
+        ### Item 2
+
+        <content>
+    """
+
+    def format(
+        self, items: list[ContentPartItemResponse], group_by: str | None = None
+    ) -> str:
+        """Format items as markdown.
+
+        Args:
+            items: Content items to format
+            group_by: Optional tag prefix for grouping
+
+        Returns:
+            Markdown formatted string
+        """
+        if group_by:
+            return self._format_grouped(items, group_by)
+        return self._format_flat(items)
+
+    def _format_flat(self, items: list[ContentPartItemResponse]) -> str:
+        """Format items with numbered headers."""
+        sections: list[str] = []
+        for i, item in enumerate(items, 1):
+            content = self._get_content(item)
+            sections.append(f"## Item {i}\n\n{content}")
+        return "\n\n".join(sections)
+
+    def _format_grouped(
+        self, items: list[ContentPartItemResponse], group_by: str
+    ) -> str:
+        """Format items grouped by tag prefix with nested headers."""
+        groups = self._group_items(items, group_by)
+        sections: list[str] = []
+        for group_name, group_items in groups.items():
+            group_sections: list[str] = [f"## {group_name}"]
+            for i, item in enumerate(group_items, 1):
+                content = self._get_content(item)
+                group_sections.append(f"### Item {i}\n\n{content}")
+            sections.append("\n\n".join(group_sections))
+        return "\n\n".join(sections)
+
+
+class XmlFormatter(ContentExportFormatter):
+    """Format content as XML tags.
+
+    Uses CDATA sections to preserve raw content without escaping,
+    which is important when content itself contains XML (e.g., system prompts).
+    """
+
+    def format(
+        self, items: list[ContentPartItemResponse], group_by: str | None = None
+    ) -> str:
+        """Format items as XML.
+
+        Args:
+            items: Content items to format
+            group_by: Optional tag prefix for grouping
+
+        Returns:
+            XML formatted string
+        """
+        if group_by:
+            return self._format_grouped(items, group_by)
+        return self._format_flat(items)
+
+    def _wrap_cdata(self, text: str) -> str:
+        """Wrap content in CDATA section to preserve raw content.
+
+        Handles the edge case where content contains ']]>' by splitting
+        into multiple CDATA sections.
+        """
+        # Handle edge case: content contains CDATA end marker
+        if "]]>" in text:
+            # Split at ]]> and rejoin with separate CDATA sections
+            text = text.replace("]]>", "]]]]><![CDATA[>")
+        return f"<![CDATA[{text}]]>"
+
+    def _safe_tag_name(self, name: str) -> str:
+        """Convert a name to a valid XML tag name."""
+        # Replace dots and other invalid chars with underscores
+        safe = name.replace(".", "_").replace("-", "_").replace(" ", "_")
+        # Ensure starts with letter or underscore
+        if safe and not (safe[0].isalpha() or safe[0] == "_"):
+            safe = "_" + safe
+        return safe or "item"
+
+    def _format_flat(self, items: list[ContentPartItemResponse]) -> str:
+        """Format items as a flat XML list."""
+        lines = ["<content_items>"]
+        for item in items:
+            content = self._get_content(item)
+            # Use first tag as element name, or "item"
+            tag_name = (
+                self._safe_tag_name(item.tags[0].tag_path) if item.tags else "item"
+            )
+            lines.append(f"  <{tag_name}>{self._wrap_cdata(content)}</{tag_name}>")
+        lines.append("</content_items>")
+        return "\n".join(lines)
+
+    def _format_grouped(
+        self, items: list[ContentPartItemResponse], group_by: str
+    ) -> str:
+        """Format items grouped by tag prefix."""
+        groups = self._group_items(items, group_by)
+        lines = ["<content_items>"]
+        for group_name, group_items in groups.items():
+            safe_name = self._safe_tag_name(group_name)
+            lines.append(f"  <{safe_name}>")
+            for item in group_items:
+                content = self._get_content(item)
+                lines.append(f"    <item>{self._wrap_cdata(content)}</item>")
+            lines.append(f"  </{safe_name}>")
+        lines.append("</content_items>")
+        return "\n".join(lines)
+
+
+class NumberedFormatter(ContentExportFormatter):
+    """Format content as numbered list."""
+
+    def format(
+        self, items: list[ContentPartItemResponse], group_by: str | None = None
+    ) -> str:
+        """Format items as numbered list.
+
+        Args:
+            items: Content items to format
+            group_by: Optional tag prefix for grouping
+
+        Returns:
+            Numbered list string
+        """
+        if group_by:
+            return self._format_grouped(items, group_by)
+        return self._format_flat(items)
+
+    def _format_flat(self, items: list[ContentPartItemResponse]) -> str:
+        """Format items as a flat numbered list."""
+        lines: list[str] = []
+        for i, item in enumerate(items, 1):
+            content = self._get_content(item)
+            # Handle multi-line content
+            content_lines = content.split("\n")
+            if len(content_lines) == 1:
+                lines.append(f"{i}. {content}")
+            else:
+                lines.append(f"{i}. {content_lines[0]}")
+                padding = " " * (len(str(i)) + 2)
+                for continuation in content_lines[1:]:
+                    lines.append(f"{padding}{continuation}")
+        return "\n".join(lines)
+
+    def _format_grouped(
+        self, items: list[ContentPartItemResponse], group_by: str
+    ) -> str:
+        """Format items grouped by tag prefix."""
+        groups = self._group_items(items, group_by)
+        lines: list[str] = []
+        for group_name, group_items in groups.items():
+            lines.append(f"[{group_name}]")
+            for i, item in enumerate(group_items, 1):
+                content = self._get_content(item)
+                content_lines = content.split("\n")
+                if len(content_lines) == 1:
+                    lines.append(f"  {i}. {content}")
+                else:
+                    lines.append(f"  {i}. {content_lines[0]}")
+                    padding = " " * (len(str(i)) + 4)
+                    for continuation in content_lines[1:]:
+                        lines.append(f"{padding}{continuation}")
+            lines.append("")
+        return "\n".join(lines).rstrip()
+
+
+class PlainFormatter(ContentExportFormatter):
+    """Format content as plain text (content only, one per line)."""
+
+    def format(
+        self, items: list[ContentPartItemResponse], group_by: str | None = None
+    ) -> str:
+        """Format items as plain text.
+
+        Grouping adds blank lines between groups but no headers.
+
+        Args:
+            items: Content items to format
+            group_by: Optional tag prefix for grouping
+
+        Returns:
+            Plain text string with content only
+        """
+        if group_by:
+            return self._format_grouped(items, group_by)
+        return self._format_flat(items)
+
+    def _format_flat(self, items: list[ContentPartItemResponse]) -> str:
+        """Format items as plain text."""
+        lines: list[str] = []
+        for item in items:
+            content = self._get_content(item)
+            lines.append(content)
+        return "\n".join(lines)
+
+    def _format_grouped(
+        self, items: list[ContentPartItemResponse], group_by: str
+    ) -> str:
+        """Format items grouped by tag prefix with blank line separators."""
+        groups = self._group_items(items, group_by)
+        sections: list[str] = []
+        for group_items in groups.values():
+            section_lines: list[str] = []
+            for item in group_items:
+                content = self._get_content(item)
+                section_lines.append(content)
+            sections.append("\n".join(section_lines))
+        return "\n\n".join(sections)
+
+
+class JsonExportFormatter(ContentExportFormatter):
+    """Format content as JSON array."""
+
+    def format(
+        self, items: list[ContentPartItemResponse], group_by: str | None = None
+    ) -> str:
+        """Format items as JSON.
+
+        Args:
+            items: Content items to format
+            group_by: Optional tag prefix for grouping
+
+        Returns:
+            JSON string (array or object if grouped)
+        """
+        if group_by:
+            return self._format_grouped(items, group_by)
+        return self._format_flat(items)
+
+    def _item_to_dict(self, item: ContentPartItemResponse) -> dict[str, Any]:
+        """Convert content item to dictionary for JSON serialization."""
+        return {
+            "id": str(item.id),
+            "content_type": item.content_type_id,
+            "content": item.content_text or item.content_structured,
+            "tags": [t.tag_path for t in item.tags],
+            "created_at": item.created_at.isoformat() if item.created_at else None,
+        }
+
+    def _format_flat(self, items: list[ContentPartItemResponse]) -> str:
+        """Format items as JSON array."""
+        data = [self._item_to_dict(item) for item in items]
+        return json.dumps(data, indent=2, ensure_ascii=False)
+
+    def _format_grouped(
+        self, items: list[ContentPartItemResponse], group_by: str
+    ) -> str:
+        """Format items as JSON object with groups."""
+        groups = self._group_items(items, group_by)
+        data = {
+            group_name: [self._item_to_dict(item) for item in group_items]
+            for group_name, group_items in groups.items()
+        }
+        return json.dumps(data, indent=2, ensure_ascii=False)
+
+
+# Registry of available export formatters
+EXPORT_FORMATTERS: dict[str, type[ContentExportFormatter]] = {
+    "markdown": MarkdownFormatter,
+    "xml": XmlFormatter,
+    "numbered": NumberedFormatter,
+    "plain": PlainFormatter,
+    "json": JsonExportFormatter,
+}
+
+
+def get_export_formatter(format_name: str) -> ContentExportFormatter | None:
+    """Get an export formatter instance by name.
+
+    Args:
+        format_name: Name of the format (markdown, xml, numbered, plain, json)
+
+    Returns:
+        Formatter instance or None if format not found
+    """
+    formatter_cls = EXPORT_FORMATTERS.get(format_name)
+    if formatter_cls:
+        return formatter_cls()
+    return None
+
+
+def get_available_formats() -> list[str]:
+    """Get list of available export format names."""
+    return list(EXPORT_FORMATTERS.keys())

cli/commands/content/list/export_handler.py

@@ -0,0 +1,165 @@
+"""Export handler for content list results.
+
+Routes formatted content to various destinations:
+- console: Print to stdout
+- clipboard: Copy using pyperclip
+- file: Write to specified path
+"""
+
+import sys
+from pathlib import Path
+from typing import Any
+
+from alloy_runtime_types.dtos.content import ContentPartItemResponse
+
+from cli.commands.content.list.export_formatters import (
+    EXPORT_FORMATTERS,
+    get_available_formats,
+)
+from cli.infrastructure.output import OutputService
+
+# Import pyperclip at module level for easier mocking in tests
+pyperclip: Any | None = None
+try:
+    import pyperclip as _pyperclip
+except ImportError:
+    pass
+else:
+    pyperclip = _pyperclip
+
+PYPERCLIP_AVAILABLE = pyperclip is not None
+
+
+def export_content(
+    items: list[ContentPartItemResponse],
+    export_format: str,
+    output_mode: str,
+    output_file: str | None,
+    group_by: str | None,
+) -> bool:
+    """Export content items to specified destination.
+
+    Args:
+        items: List of content part items to export
+        export_format: Format name (markdown, xml, numbered, plain, json)
+        output_mode: Destination (console, clipboard, file)
+        output_file: File path for file output mode
+        group_by: Optional tag prefix to group items by
+
+    Returns:
+        True on success, False on failure
+    """
+    output = OutputService.get()
+
+    # Validate format
+    formatter_cls = EXPORT_FORMATTERS.get(export_format)
+    if not formatter_cls:
+        available = ", ".join(get_available_formats())
+        output.warning(
+            f"Unknown export format: '{export_format}'. Available: {available}"
+        )
+        return False
+
+    # Check for empty items
+    if not items:
+        output.info("No content items to export")
+        return True
+
+    # Format the content
+    formatter = formatter_cls()
+    formatted_content = formatter.format(items, group_by)
+
+    # Route to destination
+    if output_mode == "clipboard":
+        return _copy_to_clipboard(formatted_content, len(items), output)
+    elif output_mode == "file":
+        return _save_to_file(formatted_content, output_file, len(items), output)
+    else:  # console (default)
+        return _print_to_console(formatted_content, output)
+
+
+def _print_to_console(content: str, _output: OutputService) -> bool:
+    """Print formatted content to stdout.
+
+    Args:
+        content: Formatted content string
+        output: Output service for messages
+
+    Returns:
+        True on success
+    """
+    try:
+        print(content, file=sys.stdout)
+        return True
+    except (BrokenPipeError, IOError):
+        # Pipe was closed (e.g., piping to head)
+        return True
+
+
+def _copy_to_clipboard(content: str, item_count: int, output: OutputService) -> bool:
+    """Copy formatted content to clipboard.
+
+    Args:
+        content: Formatted content string
+        item_count: Number of items exported (for status message)
+        output: Output service for messages
+
+    Returns:
+        True on success, False on failure
+    """
+    if not PYPERCLIP_AVAILABLE or pyperclip is None:
+        output.warning("pyperclip not installed. Install with: pip install pyperclip")
+        output.info("Falling back to console output...")
+        print(content, file=sys.stdout)
+        return False
+
+    try:
+        pyperclip.copy(content)
+        output.success(
+            f"Exported {item_count} item(s) to clipboard ({len(content):,} characters)"
+        )
+        return True
+    except Exception as e:
+        output.warning(f"Failed to copy to clipboard: {e}")
+        output.info("Falling back to console output...")
+        print(content, file=sys.stdout)
+        return False
+
+
+def _save_to_file(
+    content: str, output_file: str | None, item_count: int, output: OutputService
+) -> bool:
+    """Save formatted content to a file.
+
+    Args:
+        content: Formatted content string
+        output_file: Target file path
+        item_count: Number of items exported (for status message)
+        output: Output service for messages
+
+    Returns:
+        True on success, False on failure
+    """
+    if not output_file:
+        output.warning("No output file specified (use --output-file)")
+        return False
+
+    try:
+        file_path = Path(output_file).expanduser().resolve()
+
+        # Ensure parent directory exists
+        file_path.parent.mkdir(parents=True, exist_ok=True)
+
+        # Write the content
+        file_path.write_text(content, encoding="utf-8")
+
+        output.success(
+            f"Exported {item_count} item(s) to {file_path} ({len(content):,} characters)"
+        )
+        return True
+    except PermissionError:
+        output.warning(f"Permission denied: Cannot write to '{output_file}'")
+        return False
+    except OSError as e:
+        output.warning(f"Failed to save file: {e}")
+        return False