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

cli/infrastructure/kv_parser.py

@@ -0,0 +1,130 @@
+"""HTTPie-style key-value parser for CLI options.
+
+Provides parsing for key=value and key:=json syntax, allowing users to
+build JSON objects without writing literal JSON strings.
+
+Syntax:
+    key=value   -> {"key": "value"}           (string value)
+    key:=value  -> {"key": <parsed JSON>}     (raw JSON: numbers, bools, arrays, objects)
+
+Examples:
+    name=John              -> {"name": "John"}
+    count:=5               -> {"count": 5}
+    active:=true           -> {"active": true}
+    tags:='["a","b"]'      -> {"tags": ["a", "b"]}
+    url=https://foo.com    -> {"url": "https://foo.com"}  (= in value is preserved)
+
+Usage with Typer:
+    from cli.infrastructure.kv_parser import kv_pairs_callback
+
+    @app.command()
+    def my_command(
+        variables: Annotated[
+            list[str] | None,
+            typer.Option(
+                "--var", "-v",
+                help="Variables in key=value or key:=json format",
+                callback=kv_pairs_callback,
+            ),
+        ] = None,
+    ) -> None:
+        # variables is now a dict[str, Any]
+        ...
+"""
+
+import json
+from typing import Any
+
+import typer
+
+
+def parse_kv_pairs(values: list[str] | None) -> dict[str, Any]:
+    """Parse a list of key=value or key:=json strings into a dictionary.
+
+    Args:
+        values: List of strings in "key=value" or "key:=json" format.
+                Can be None or empty.
+
+    Returns:
+        Dictionary with parsed key-value pairs. Empty dict if input is None/empty.
+
+    Raises:
+        typer.BadParameter: If a value has invalid format or invalid JSON for :=
+
+    Examples:
+        >>> parse_kv_pairs(["name=John", "age:=30"])
+        {"name": "John", "age": 30}
+
+        >>> parse_kv_pairs(["active:=true", "tags:=['a','b']"])
+        {"active": True, "tags": ["a", "b"]}
+
+        >>> parse_kv_pairs(None)
+        {}
+    """
+    if not values:
+        return {}
+
+    result: dict[str, Any] = {}
+
+    for item in values:
+        # Check for raw JSON syntax first (`:=`)
+        if ":=" in item:
+            key, raw_value = item.split(":=", 1)
+            key = key.strip()
+
+            if not key:
+                raise typer.BadParameter(
+                    f"Missing key in '{item}'. Expected format: key:=json_value"
+                )
+
+            try:
+                result[key] = json.loads(raw_value)
+            except json.JSONDecodeError as e:
+                raise typer.BadParameter(
+                    f"Invalid JSON for key '{key}': {raw_value}. Error: {e}"
+                )
+
+        # Check for string syntax (`=`)
+        elif "=" in item:
+            key, value = item.split("=", 1)
+            key = key.strip()
+
+            if not key:
+                raise typer.BadParameter(
+                    f"Missing key in '{item}'. Expected format: key=value"
+                )
+
+            result[key] = value
+
+        else:
+            raise typer.BadParameter(
+                f"Invalid format: '{item}'. Expected 'key=value' or 'key:=json_value'"
+            )
+
+    return result
+
+
+def kv_pairs_callback(values: list[str] | None) -> dict[str, Any]:
+    """Typer callback that transforms key-value pairs into a dictionary.
+
+    Use this as a callback for typer.Option to accept httpie-style key-value
+    pairs that get parsed into a dictionary before reaching your command function.
+
+    Args:
+        values: List of strings from repeated option usage (e.g., -v a=1 -v b=2)
+
+    Returns:
+        Parsed dictionary
+
+    Example:
+        @app.command()
+        def cmd(
+            vars: Annotated[
+                list[str] | None,
+                typer.Option("--var", "-v", callback=kv_pairs_callback),
+            ] = None,
+        ):
+            # vars is a dict here, not list[str]
+            print(vars)  # {"a": "1", "b": 2}
+    """
+    return parse_kv_pairs(values)

cli/infrastructure/local_storage.py

@@ -0,0 +1,227 @@
+"""Local JSON storage for CLI persistent data.
+
+Provides a scalable storage system for various CLI features like command history,
+preferences, cached data, etc. Data is stored in ~/.alloy-runtime/storage.json.
+"""
+
+import json
+import os
+from pathlib import Path
+from typing import Any, cast
+
+
+CONFIG_DIR = Path.home() / ".alloy-runtime"
+STORAGE_FILE = CONFIG_DIR / "storage.json"
+
+# Default limits for various storage features
+MAX_COMMAND_HISTORY = 15
+
+
+class LocalStorage:
+    """JSON-based local storage for CLI persistent data.
+
+    Provides getter/setter methods for various storage features.
+    Data is automatically persisted to ~/.alloy-runtime/storage.json.
+
+    Example:
+        storage = LocalStorage()
+
+        # Command history
+        storage.add_command("Hello, how are you?")
+        history = storage.get_command_history()
+
+        # Future features can add their own sections
+        storage.set("preferences", "theme", "dark")
+        theme = storage.get("preferences", "theme", default="light")
+    """
+
+    def __init__(self) -> None:
+        self._data: dict[str, Any] = self._load()
+
+    def _load(self) -> dict[str, Any]:
+        """Load storage data from disk."""
+        if not STORAGE_FILE.exists():
+            return self._default_data()
+
+        try:
+            with open(STORAGE_FILE, encoding="utf-8") as f:
+                data = json.load(f)
+                # Ensure all expected keys exist
+                return self._merge_with_defaults(data)
+        except (json.JSONDecodeError, OSError):
+            # If file is corrupted, start fresh
+            return self._default_data()
+
+    def _default_data(self) -> dict[str, Any]:
+        """Return default storage structure."""
+        return {
+            "command_history": [],
+            "preferences": {},
+            "cache": {},
+        }
+
+    def _merge_with_defaults(self, data: dict[str, Any]) -> dict[str, Any]:
+        """Merge loaded data with defaults to ensure all keys exist."""
+        defaults = self._default_data()
+        for key, value in defaults.items():
+            if key not in data:
+                data[key] = value
+        return data
+
+    def _save(self) -> None:
+        """Save storage data to disk."""
+        CONFIG_DIR.mkdir(exist_ok=True, mode=0o700)
+
+        with open(STORAGE_FILE, "w", encoding="utf-8") as f:
+            json.dump(self._data, f, indent=2)
+
+        # Set secure file permissions
+        os.chmod(STORAGE_FILE, 0o600)
+
+    # -------------------------------------------------------------------------
+    # Command History Methods
+    # -------------------------------------------------------------------------
+
+    def get_command_history(self) -> list[str]:
+        """Get the command history list.
+
+        Returns:
+            List of previously sent messages, most recent last.
+        """
+        history = self._data.get("command_history", [])
+        if isinstance(history, list):
+            return [str(item) for item in cast(list[Any], history)]
+        return []
+
+    def add_command(self, command: str) -> None:
+        """Add a command to history.
+
+        Maintains a maximum of MAX_COMMAND_HISTORY entries.
+        Duplicates are allowed (same message can appear multiple times).
+
+        Args:
+            command: The user message to add to history.
+        """
+        command = command.strip()
+        if not command:
+            return
+
+        history_data = self._data.get("command_history", [])
+        history: list[str]
+        if isinstance(history_data, list):
+            history = [str(item) for item in cast(list[Any], history_data)]
+        else:
+            history = []
+        history.append(command)
+
+        # Trim to max size, keeping most recent
+        if len(history) > MAX_COMMAND_HISTORY:
+            history = history[-MAX_COMMAND_HISTORY:]
+
+        self._data["command_history"] = history
+        self._save()
+
+    def clear_command_history(self) -> None:
+        """Clear all command history."""
+        self._data["command_history"] = []
+        self._save()
+
+    # -------------------------------------------------------------------------
+    # Generic Getter/Setter Methods (for future features)
+    # -------------------------------------------------------------------------
+
+    def get(self, section: str, key: str, default: Any = None) -> Any:
+        """Get a value from a storage section.
+
+        Args:
+            section: The storage section (e.g., "preferences", "cache")
+            key: The key within the section
+            default: Default value if key doesn't exist
+
+        Returns:
+            The stored value or default
+        """
+        section_data = self._data.get(section)
+        if isinstance(section_data, dict):
+            typed_section_data = cast(dict[str, Any], section_data)
+            return typed_section_data.get(key, default)
+        return default
+
+    def set(self, section: str, key: str, value: Any) -> None:
+        """Set a value in a storage section.
+
+        Args:
+            section: The storage section (e.g., "preferences", "cache")
+            key: The key within the section
+            value: The value to store (must be JSON-serializable)
+        """
+        if section not in self._data:
+            self._data[section] = {}
+
+        section_data = self._data[section]
+        if isinstance(section_data, dict):
+            typed_section_data = cast(dict[str, Any], section_data)
+            typed_section_data[key] = value
+            self._save()
+
+    def delete(self, section: str, key: str) -> bool:
+        """Delete a key from a storage section.
+
+        Args:
+            section: The storage section
+            key: The key to delete
+
+        Returns:
+            True if key was deleted, False if it didn't exist
+        """
+        section_data = self._data.get(section)
+        if isinstance(section_data, dict) and key in section_data:
+            typed_section_data = cast(dict[str, Any], section_data)
+            del typed_section_data[key]
+            self._save()
+            return True
+        return False
+
+    def get_section(self, section: str) -> dict[str, Any]:
+        """Get an entire storage section.
+
+        Args:
+            section: The storage section name
+
+        Returns:
+            The section data as a dict, or empty dict if not found
+        """
+        section_data = self._data.get(section)
+        if isinstance(section_data, dict):
+            typed_section_data = cast(dict[str, Any], section_data)
+            return dict(typed_section_data)
+        return {}
+
+    def clear_section(self, section: str) -> None:
+        """Clear all data in a storage section.
+
+        Args:
+            section: The storage section to clear
+        """
+        if section in self._data:
+            if section == "command_history":
+                self._data[section] = []
+            else:
+                self._data[section] = {}
+            self._save()
+
+
+# Singleton instance for convenience
+_storage: LocalStorage | None = None
+
+
+def get_storage() -> LocalStorage:
+    """Get the global LocalStorage instance.
+
+    Returns:
+        The singleton LocalStorage instance.
+    """
+    global _storage
+    if _storage is None:
+        _storage = LocalStorage()
+    return _storage

cli/infrastructure/macro_parser.py

@@ -0,0 +1,215 @@
+"""Macro parser for template content.
+
+Parses @macro(query) syntax in template content and provides compilation
+to transform macros into valid Jinja2 syntax.
+
+Supported macros:
+- @fragment(query) -> {% include 'fragment_name' %}
+- @text(query) -> {{ text('uuid_or_external_id') }}
+- @json(query) -> {{ json('uuid_or_external_id') }}
+- @schema(query) -> {{ schema('name_or_uuid') }}
+"""
+
+import re
+from dataclasses import dataclass
+
+# Regex to match @type(query) macros
+# Group 1: macro type (e.g., "fragment", "text", "json", "schema")
+# Group 2: query string (e.g., "header", "article summary")
+MACRO_PATTERN = re.compile(r"@(\w+)\((.*?)\)")
+
+# Regex patterns for Jinja2 syntax detection in rendered output
+# These match Jinja2 constructs that survived rendering (e.g., from {% raw %} blocks)
+JINJA_EXPRESSION_PATTERN = re.compile(r"\{\{.*?\}\}", re.DOTALL)  # {{ ... }}
+JINJA_STATEMENT_PATTERN = re.compile(r"\{%.*?%\}", re.DOTALL)  # {% ... %}
+JINJA_COMMENT_PATTERN = re.compile(r"\{#.*?#\}", re.DOTALL)  # {# ... #}
+
+# Valid macro types that we support
+VALID_MACRO_TYPES = frozenset({"fragment", "text", "json", "schema"})
+
+
+@dataclass
+class MacroMatch:
+    """Represents a parsed macro from template content."""
+
+    macro_type: str
+    query: str
+    original_text: str
+    start: int
+    end: int
+
+    def __repr__(self) -> str:
+        return f"MacroMatch({self.macro_type}, {self.query!r})"
+
+
+def parse_macros(content: str) -> list[MacroMatch]:
+    """Parse all valid macros from template content.
+
+    Args:
+        content: Template content potentially containing macros
+
+    Returns:
+        List of MacroMatch objects for valid macros, in order of appearance
+    """
+    matches: list[MacroMatch] = []
+    for match in MACRO_PATTERN.finditer(content):
+        macro_type = match.group(1)
+        query = match.group(2).strip()
+
+        # Only include valid macro types
+        if macro_type in VALID_MACRO_TYPES:
+            matches.append(
+                MacroMatch(
+                    macro_type=macro_type,
+                    query=query,
+                    original_text=match.group(0),
+                    start=match.start(),
+                    end=match.end(),
+                )
+            )
+
+    return matches
+
+
+def deduplicate_macros(macros: list[MacroMatch]) -> list[MacroMatch]:
+    """Deduplicate macros by (macro_type, query) keeping first occurrence.
+
+    When the same macro (same type and query) appears multiple times in content,
+    this returns only the first occurrence. Useful for resolution flows where
+    the user should only need to resolve each unique macro once.
+
+    Args:
+        macros: List of MacroMatch objects (from parse_macros)
+
+    Returns:
+        List of unique MacroMatch objects, preserving order of first appearance
+    """
+    seen: set[tuple[str, str]] = set()
+    unique: list[MacroMatch] = []
+    for macro in macros:
+        key = (macro.macro_type, macro.query)
+        if key not in seen:
+            seen.add(key)
+            unique.append(macro)
+    return unique
+
+
+def compile_content(content: str, replacements: dict[str, str]) -> str:
+    """Apply macro replacements to template content.
+
+    Args:
+        content: Original template content with macros
+        replacements: Mapping of original macro text to replacement Jinja syntax
+
+    Returns:
+        Compiled content with macros replaced
+    """
+    result = content
+    for original, replacement in replacements.items():
+        result = result.replace(original, replacement)
+    return result
+
+
+def build_jinja_replacement(macro_type: str, resolved_value: str) -> str:
+    """Build the Jinja2 replacement syntax for a resolved macro.
+
+    Args:
+        macro_type: Type of macro (fragment, text, json, schema)
+        resolved_value: The resolved value (fragment name, content part UUID/external_id, or schema name/UUID)
+
+    Returns:
+        Valid Jinja2 syntax string
+
+    Note:
+        - fragment uses the template NAME (not UUID) because the renderer resolves by name
+        - text/json use UUIDs or external_ids to reference content parts
+        - schema uses the schema NAME (or UUID) because the renderer supports both
+    """
+    if macro_type == "fragment":
+        # Fragment uses name, not UUID
+        return f"{{% include '{resolved_value}' %}}"
+    elif macro_type == "text":
+        return f"{{{{ text('{resolved_value}') }}}}"
+    elif macro_type == "json":
+        return f"{{{{ json('{resolved_value}') }}}}"
+    elif macro_type == "schema":
+        return f"{{{{ schema('{resolved_value}') }}}}"
+    else:
+        raise ValueError(f"Unknown macro type: {macro_type}")
+
+
+@dataclass
+class JinjaSyntaxMatch:
+    """Represents a Jinja2 syntax match found in rendered content."""
+
+    syntax_type: str  # "expression", "statement", or "comment"
+    content: str  # The full matched text including delimiters
+    start: int
+    end: int
+
+    def __repr__(self) -> str:
+        preview = self.content[:50] + "..." if len(self.content) > 50 else self.content
+        return f"JinjaSyntaxMatch({self.syntax_type}, {preview!r})"
+
+
+def extract_jinja_syntax(content: str) -> list[JinjaSyntaxMatch]:
+    """Extract all Jinja2 syntax from rendered content.
+
+    Finds Jinja2 expressions ({{ }}), statements ({% %}), and comments ({# #})
+    that remain in the rendered output. These typically come from {% raw %} blocks
+    or escaped content that should be preserved for later use.
+
+    Args:
+        content: Rendered template content
+
+    Returns:
+        List of JinjaSyntaxMatch objects in order of appearance, deduplicated
+    """
+    matches: list[JinjaSyntaxMatch] = []
+    seen_content: set[str] = set()
+
+    # Find expressions {{ ... }}
+    for match in JINJA_EXPRESSION_PATTERN.finditer(content):
+        text = match.group(0)
+        if text not in seen_content:
+            seen_content.add(text)
+            matches.append(
+                JinjaSyntaxMatch(
+                    syntax_type="expression",
+                    content=text,
+                    start=match.start(),
+                    end=match.end(),
+                )
+            )
+
+    # Find statements {% ... %}
+    for match in JINJA_STATEMENT_PATTERN.finditer(content):
+        text = match.group(0)
+        if text not in seen_content:
+            seen_content.add(text)
+            matches.append(
+                JinjaSyntaxMatch(
+                    syntax_type="statement",
+                    content=text,
+                    start=match.start(),
+                    end=match.end(),
+                )
+            )
+
+    # Find comments {# ... #}
+    for match in JINJA_COMMENT_PATTERN.finditer(content):
+        text = match.group(0)
+        if text not in seen_content:
+            seen_content.add(text)
+            matches.append(
+                JinjaSyntaxMatch(
+                    syntax_type="comment",
+                    content=text,
+                    start=match.start(),
+                    end=match.end(),
+                )
+            )
+
+    # Sort by position in content
+    matches.sort(key=lambda m: m.start)
+    return matches