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

cli/infrastructure/config.py

@@ -0,0 +1,188 @@
+"""Configuration management for CLI.
+
+Loads configuration with hierarchy: CLI flags > Environment variables > Config file
+"""
+
+import os
+
+from pydantic import BaseModel, Field, field_validator
+
+from cli.infrastructure.auth_storage import load_credentials
+
+
+# Global storage for CLI flag overrides (set by main.py callback)
+_global_api_url: str | None = None
+_global_api_key: str | None = None
+
+
+def set_global_overrides(
+    api_url: str | None = None, api_key: str | None = None
+) -> None:
+    """Set global CLI flag overrides.
+
+    Called by the main app callback to store --api-url and --api-key flags.
+
+    Args:
+        api_url: Global --api-url flag value
+        api_key: Global --api-key flag value
+    """
+    global _global_api_url, _global_api_key
+    _global_api_url = api_url
+    _global_api_key = api_key
+
+
+def get_api_url(default: str = "http://localhost:8000") -> str:
+    """Get API URL using the configuration hierarchy.
+
+    Precedence order (highest to lowest):
+    1. Global CLI flag (--api-url)
+    2. Environment variable (ALLOY_RUNTIME_API_URL)
+    3. Config file (~/.alloy-runtime/config)
+    4. Default value
+
+    Args:
+        default: Fallback value if no configuration source provides URL
+
+    Returns:
+        API URL string
+
+    Example:
+        api_url = get_api_url()  # Uses hierarchy with localhost default
+    """
+    # Try global flag (highest priority)
+    if _global_api_url:
+        return _global_api_url
+
+    # Try environment variable
+    env_url = os.environ.get("ALLOY_RUNTIME_API_URL")
+    if env_url:
+        return env_url
+
+    # Try config file
+    file_config = load_credentials()
+    if file_config:
+        return file_config[0]
+
+    # Use default
+    return default
+
+
+class CLIConfig(BaseModel):
+    """CLI configuration with hierarchical loading.
+
+    Precedence order (highest to lowest):
+    1. CLI flags (--api-key, --api-url)
+    2. Environment variables (ALLOY_RUNTIME_API_KEY, ALLOY_RUNTIME_API_URL)
+    3. Config file (~/.alloy-runtime/config)
+    """
+
+    api_url: str = Field(..., description="Alloy Runtime server base URL")
+    api_key: str = Field(..., description="API authentication key")
+    timeout: float | None = Field(
+        default=None, description="Request timeout in seconds"
+    )
+
+    @field_validator("api_url")
+    @classmethod
+    def validate_api_url(cls, v: str) -> str:
+        """Ensure API URL is non-empty and properly formatted."""
+        _ = cls  # Required by Pydantic validator
+        if not v or not v.strip():
+            raise ValueError("API URL cannot be empty")
+        return v.rstrip("/")  # Remove trailing slash
+
+    @field_validator("api_key")
+    @classmethod
+    def validate_api_key(cls, v: str) -> str:
+        """Ensure API key is non-empty."""
+        _ = cls  # Required by Pydantic validator
+        if not v or not v.strip():
+            raise ValueError("API key cannot be empty")
+        return v
+
+
+class ConfigurationError(Exception):
+    """Raised when configuration cannot be loaded."""
+
+    pass
+
+
+def load_config() -> CLIConfig:
+    """Load CLI configuration with hierarchical precedence.
+
+    Precedence order (highest to lowest):
+    1. Global CLI flags (--api-key, --api-url set via callback)
+    2. Environment variables (ALLOY_RUNTIME_API_KEY, ALLOY_RUNTIME_API_URL)
+    3. Config file (~/.alloy-runtime/config)
+
+    Returns:
+        Validated CLI configuration
+
+    Raises:
+        ConfigurationError: If no configuration source provides required values
+
+    Example:
+        # Load with hierarchy
+        config = load_config()
+
+        # CLI usage:
+        alloy --api-url https://prod.example.com sync models
+        alloy --api-key sk_prod_... credentials update <id>
+    """
+    # Load from config file (lowest priority)
+    file_config = load_credentials()
+    api_url_from_file = file_config[0] if file_config else None
+    api_key_from_file = file_config[1] if file_config else None
+
+    # Load from environment variables (middle priority)
+    api_url_from_env = os.environ.get("ALLOY_RUNTIME_API_URL")
+    api_key_from_env = os.environ.get("ALLOY_RUNTIME_API_KEY")
+
+    # Apply hierarchy: Global CLI flags > env vars > config file
+    # Note: Must check "is not None" because flags can be explicitly None when not passed
+    if _global_api_url is not None:
+        api_url = _global_api_url
+    elif api_url_from_env:
+        api_url = api_url_from_env
+    else:
+        api_url = api_url_from_file
+
+    if _global_api_key is not None:
+        api_key = _global_api_key
+    elif api_key_from_env:
+        api_key = api_key_from_env
+    else:
+        api_key = api_key_from_file
+
+    # Validate that we have the required configuration
+    if not api_url:
+        raise ConfigurationError(
+            "API URL not configured. Please provide via:\n"
+            "  1. CLI flag: --api-url http://localhost:8000\n"
+            "  2. Environment variable: ALLOY_RUNTIME_API_URL\n"
+            "  3. Login first: alloy login"
+        )
+
+    if not api_key:
+        raise ConfigurationError(
+            "API key not configured. Please provide via:\n"
+            "  1. CLI flag: --api-key sk_live_...\n"
+            "  2. Environment variable: ALLOY_RUNTIME_API_KEY\n"
+            "  3. Login first: alloy login"
+        )
+
+    # Load optional timeout
+    timeout = None
+    timeout_str = os.environ.get("ALLOY_RUNTIME_TIMEOUT")
+    if timeout_str:
+        try:
+            timeout = float(timeout_str)
+        except ValueError:
+            raise ConfigurationError(
+                "ALLOY_RUNTIME_TIMEOUT must be a valid number (seconds)"
+            )
+
+    try:
+        return CLIConfig(api_url=api_url, api_key=api_key, timeout=timeout)
+    except ValueError as e:
+        raise ConfigurationError(f"Invalid configuration: {e}")

cli/infrastructure/console.py

@@ -0,0 +1,27 @@
+"""Unified console service for all CLI output.
+
+This is the single source of truth for console output. All features
+MUST use this module for output instead of creating their own Console.
+"""
+
+from rich.console import Console
+from rich.prompt import Confirm, Prompt
+
+# Singleton console instance
+_console: Console | None = None
+
+
+def get_console() -> Console:
+    """Get the global console instance.
+
+    Returns:
+        Shared Console instance for all CLI output
+    """
+    global _console
+    if _console is None:
+        _console = Console()
+    return _console
+
+
+# Re-export Rich prompts for convenience
+__all__ = ["get_console", "Prompt", "Confirm"]

cli/infrastructure/editor.py

@@ -0,0 +1,138 @@
+"""External editor integration for template content editing.
+
+Opens the user's preferred $EDITOR to edit template content,
+with fallback to common terminal editors.
+"""
+
+import os
+import shutil
+import subprocess
+import tempfile
+from pathlib import Path
+
+
+class EditorError(Exception):
+    """Raised when editor operations fail."""
+
+
+def get_editor() -> str:
+    """Get the user's preferred editor.
+
+    Checks in order:
+    1. $EDITOR environment variable
+    2. $VISUAL environment variable
+    3. Common editors on PATH (nano, vim, vi)
+
+    Returns:
+        Path/name of editor to use
+
+    Raises:
+        EditorError: If no suitable editor is found
+    """
+    # Check environment variables first
+    editor = os.environ.get("EDITOR") or os.environ.get("VISUAL")
+    if editor:
+        return editor
+
+    # Fall back to common editors
+    for fallback in ("nano", "vim", "vi"):
+        if shutil.which(fallback):
+            return fallback
+
+    raise EditorError(
+        "No editor found. Set $EDITOR environment variable or install nano/vim."
+    )
+
+
+def open_editor(initial_content: str = "") -> str | None:
+    """Open the user's editor with optional initial content.
+
+    Creates a temporary file, opens it in the editor, waits for the editor
+    to close, then reads and returns the file content.
+
+    Args:
+        initial_content: Initial content to populate the file with
+
+    Returns:
+        The edited content from the file, or None if the editor failed
+        or the user quit without saving.
+
+    Raises:
+        EditorError: If no editor is available
+    """
+    editor = get_editor()
+
+    # Create temp file with .jinja2 extension for syntax highlighting
+    with tempfile.NamedTemporaryFile(
+        mode="w",
+        suffix=".jinja2",
+        delete=False,
+    ) as f:
+        f.write(initial_content)
+        temp_path = Path(f.name)
+
+    try:
+        # Get file modification time before editing
+        mtime_before = temp_path.stat().st_mtime
+
+        # Open editor and wait for it to close
+        # Shell=False for security, but we need to handle editor args
+        editor_parts = editor.split()
+        cmd = editor_parts + [str(temp_path)]
+
+        result = subprocess.call(cmd)
+
+        if result != 0:
+            return None
+
+        # Check if file was modified
+        mtime_after = temp_path.stat().st_mtime
+        if mtime_after == mtime_before:
+            # File wasn't modified - could mean user quit without saving
+            # Still return content in case they just didn't change anything
+            pass
+
+        # Read the edited content
+        content = temp_path.read_text()
+        return content
+
+    finally:
+        # Clean up temp file
+        try:
+            temp_path.unlink()
+        except OSError:
+            pass  # Best effort cleanup
+
+
+def open_editor_with_hints(initial_content: str = "") -> str | None:
+    """Open editor with helpful comments about macro syntax.
+
+    Adds instructional comments at the top of the file that explain
+    the macro syntax. These comments are stripped from the final output.
+
+    Args:
+        initial_content: Initial content to populate the file with
+
+    Returns:
+        The edited content with hint comments removed, or None if failed
+    """
+    # Only show hints when content is empty
+    if initial_content:
+        full_content = initial_content
+    else:
+        hints = """@fragment(name) - Include fragment
+@text(name) - Insert text from a content part
+@json(name) - Insert JSON from a content part
+@schema(name) - Reference a schema
+{{ var }} - Variable interpolation
+"""
+        full_content = hints
+
+    result = open_editor(full_content)
+
+    if result is None:
+        return None
+
+    # Don't strip comments - let user decide what to keep
+    # They're valid Jinja2 comments anyway
+    return result

cli/infrastructure/error_display.py

@@ -0,0 +1,178 @@
+"""Error display using Rich panels.
+
+Centralizes error formatting for consistent, user-friendly error messages.
+"""
+
+from rich.panel import Panel
+
+from cli.infrastructure.config import ConfigurationError
+from cli.infrastructure.console import get_console
+from alloy_runtime_sdk.exceptions.errors import (
+    AuthenticationError,
+    ConflictError,
+    ForbiddenError,
+    NotFoundError,
+    RequestError,
+    ServerError,
+    ValidationError,
+)
+
+
+def display_error(error: Exception) -> None:
+    """Display an error in a Rich panel with appropriate styling.
+
+    Args:
+        error: Exception to display
+    """
+    if isinstance(error, ConfigurationError):
+        _display_configuration_error(error)
+    elif isinstance(error, AuthenticationError):
+        _display_authentication_error(error)
+    elif isinstance(error, ForbiddenError):
+        _display_forbidden_error(error)
+    elif isinstance(error, NotFoundError):
+        _display_not_found_error(error)
+    elif isinstance(error, ValidationError):
+        _display_validation_error(error)
+    elif isinstance(error, ConflictError):
+        _display_conflict_error(error)
+    elif isinstance(error, RequestError):
+        _display_request_error(error)
+    elif isinstance(error, ServerError):
+        _display_server_error(error)
+    else:
+        _display_unexpected_error(error)
+
+
+def _display_configuration_error(error: ConfigurationError) -> None:
+    """Display configuration error panel."""
+    console = get_console()
+    console.print(
+        Panel(
+            f"[red]Configuration Error[/red]\n\n{str(error)}",
+            title="⚙️  Configuration Required",
+            border_style="red",
+        )
+    )
+
+
+def _display_authentication_error(error: AuthenticationError) -> None:
+    """Display authentication error panel."""
+    console = get_console()
+    console.print(
+        Panel(
+            f"[red]Authentication Failed[/red]\n\n{str(error)}\n\n"
+            "Please check your ALLOY_RUNTIME_API_KEY environment variable.\n"
+            "Ensure you have a valid API key with appropriate permissions.",
+            title="❌ Authentication Error",
+            border_style="red",
+        )
+    )
+
+
+def _display_forbidden_error(error: ForbiddenError) -> None:
+    """Display forbidden error panel."""
+    console = get_console()
+    console.print(
+        Panel(
+            f"[red]Access Forbidden[/red]\n\n{str(error)}\n\n"
+            "Your API key does not have permission to perform this operation.\n"
+            "System credential management requires system admin privileges.",
+            title="🚫 Forbidden",
+            border_style="red",
+        )
+    )
+
+
+def _display_not_found_error(error: NotFoundError) -> None:
+    """Display not found error panel."""
+    console = get_console()
+    console.print(
+        Panel(
+            f"[yellow]Resource Not Found[/yellow]\n\n{str(error)}\n\n"
+            "Please verify the credential ID is correct.\n"
+            "Use the credentials list command to see available credentials.",
+            title="⚠️  Not Found",
+            border_style="yellow",
+        )
+    )
+
+
+def _display_validation_error(error: ValidationError) -> None:
+    """Display validation error panel."""
+    console = get_console()
+    error_lines = ["[red]Validation Failed[/red]\n"]
+
+    if error.errors:
+        error_lines.append("The following validation errors occurred:\n")
+        for err in error.errors:
+            # Extract field path and message from error dict
+            field = " -> ".join(str(loc) for loc in err.get("loc", []))
+            message = err.get("msg", "Unknown error")
+            error_lines.append(f"  • [cyan]{field}[/cyan]: {message}")
+    else:
+        error_lines.append(str(error))
+
+    console.print(
+        Panel(
+            "\n".join(error_lines),
+            title="❌ Validation Error",
+            border_style="red",
+        )
+    )
+
+
+def _display_conflict_error(error: ConflictError) -> None:
+    """Display conflict error panel."""
+    console = get_console()
+    console.print(
+        Panel(
+            f"[yellow]Conflict Detected[/yellow]\n\n{str(error)}\n\n"
+            "The requested operation conflicts with existing data.",
+            title="⚠️  Conflict",
+            border_style="yellow",
+        )
+    )
+
+
+def _display_request_error(error: RequestError) -> None:
+    """Display request/network error panel."""
+    console = get_console()
+    console.print(
+        Panel(
+            f"[red]Request Failed[/red]\n\n{str(error)}\n\n"
+            "Possible causes:\n"
+            "  • Network connectivity issues\n"
+            "  • Server is not running\n"
+            "  • Incorrect ALLOY_RUNTIME_API_URL\n"
+            "  • Request timeout",
+            title="🌐 Network Error",
+            border_style="red",
+        )
+    )
+
+
+def _display_server_error(error: ServerError) -> None:
+    """Display server error panel."""
+    console = get_console()
+    console.print(
+        Panel(
+            f"[red]Server Error[/red]\n\n{str(error)}\n\n"
+            "The server encountered an internal error.\n"
+            "Please try again.",
+            title="❌ Server Error",
+            border_style="red",
+        )
+    )
+
+
+def _display_unexpected_error(error: Exception) -> None:
+    """Display unexpected error panel."""
+    console = get_console()
+    console.print(
+        Panel(
+            f"[red]Unexpected Error[/red]\n\n{type(error).__name__}: {str(error)}",
+            title="❌ Error",
+            border_style="red",
+        )
+    )