10xgraph-api 0.7.0__py3-none-any.whl

tenxgraph_api/cli/core/theme.py

@@ -0,0 +1,242 @@
+"""Brand palette, glyph sets, and gradient helpers for the 10xGraph terminal UI.
+
+Everything visual in the CLI resolves through this module so a single palette
+change restyles intros, timelines, tables, and completion screens at once.
+Glyphs are separated from color because a terminal can support one without the
+other: ASCII fallbacks keep the layout identical when Unicode is unavailable.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from rich.text import Text
+from rich.theme import Theme
+
+
+# 10xGraph brand palette, from the docs site tokens (agentflow-docs/src/styles/global.css).
+# A terminal's background is unknown, so each color sits between the docs light-theme and
+# dark-theme value and stays legible on both. Primary text uses the terminal's own
+# foreground (plain ``bold``), like the logo's ink, so it never vanishes on a light theme.
+ACCENT = "#6a93f0"  # docs --accent: #2f5bd3 light / #7ea6ff dark
+AMBER = "#de8a55"  # logo entry node, docs --brand-amber: #c8692f / #e9a57c
+SUCCESS = "#3fbf98"  # docs --tip: #0f7a5c / #4fd1ae
+WARNING = "#e0a447"  # docs --warn: #8a5a00 / #f0b45a
+ERROR = "#e5666d"  # docs --danger: #b4232c / #f2868a
+MUTED = "#8691a3"  # docs --muted / --faint
+LINE = "#4f5a68"  # rules and dividers
+PENDING = "#5c6674"  # not-yet-reached steps
+
+# Surfaces painted only inside the opt-in full-screen frame, which is always dark
+# (docs --bg / --surface / --surface-2 / --line / --text).
+BACKGROUND = "#0b0e13"
+SURFACE = "#10151d"
+SURFACE_RAISED = "#161c27"
+LINE_ON_DARK = "#2d3849"
+INK_ON_DARK = "#eceff4"
+
+# Motion tint: the docs accent flowing into the logo's amber entry node. Sampled
+# continuously, so the two stops never band.
+BRAND_RAMP: tuple[str, ...] = (ACCENT, AMBER)
+
+# Used for rows that are done, running, and not started, respectively.
+STATE_RAMP: tuple[str, ...] = (SUCCESS, ACCENT, PENDING)
+
+TENXGRAPH_THEME = Theme(
+    {
+        "tenxgraph.success": f"bold {SUCCESS}",
+        "tenxgraph.error": f"bold {ERROR}",
+        "tenxgraph.warning": f"bold {WARNING}",
+        "tenxgraph.info": ACCENT,
+        "tenxgraph.muted": MUTED,
+        "tenxgraph.title": "bold",
+        "tenxgraph.brand": f"bold {AMBER}",
+        "tenxgraph.command": "bold",
+        "tenxgraph.progress": ACCENT,
+        "tenxgraph.accent": ACCENT,
+        "tenxgraph.pending": PENDING,
+        "tenxgraph.rule": LINE,
+        "tenxgraph.chip": f"bold {INK_ON_DARK} on {SURFACE_RAISED}",
+        # Header band, drawn only by the full-screen frame on its dark surface.
+        "tenxgraph.header": f"on {SURFACE}",
+        "tenxgraph.elapsed": MUTED,
+    }
+)
+
+
+@dataclass(frozen=True)
+class Glyphs:
+    """Symbol set for one invocation, chosen by terminal encoding support."""
+
+    check: str
+    cross: str
+    warn: str
+    info: str
+    bullet: str
+    arrow: str
+    pending: str
+    active: str
+    skipped: str
+    rule: str
+    thin_rule: str
+    node: str
+    diamond: str
+    caret: str
+    block: str
+    cursor: str
+    tree_stem: str
+    tree_branch: str
+    tree_end: str
+    spinner: tuple[str, ...]
+    shades: tuple[str, ...]
+
+
+UNICODE_GLYPHS = Glyphs(
+    check="✓",
+    cross="✗",
+    warn="▲",
+    info="•",
+    bullet="•",
+    arrow="→",
+    pending="○",
+    active="◆",
+    skipped="⊘",
+    rule="━",
+    thin_rule="─",
+    node="◉",
+    diamond="◆",
+    caret="▸",
+    block="█",
+    cursor="▌",
+    tree_stem="┃",
+    tree_branch="┣",
+    tree_end="┗",
+    spinner=("⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"),
+    shades=(" ", "░", "▒", "▓", "█"),
+)
+
+ASCII_GLYPHS = Glyphs(
+    check="OK",
+    cross="X",
+    warn="!",
+    info="*",
+    bullet="*",
+    arrow="->",
+    pending="o",
+    active="*",
+    skipped="-",
+    rule="=",
+    thin_rule="-",
+    node="O",
+    diamond="*",
+    caret=">",
+    block="#",
+    cursor="|",
+    tree_stem="|",
+    tree_branch="+",
+    tree_end="\\",
+    spinner=("|", "/", "-", "\\"),
+    shades=(" ", ".", ":", "+", "#"),
+)
+
+
+def glyphs_for(unicode: bool) -> Glyphs:
+    """Return the glyph set matching the terminal's encoding support."""
+    return UNICODE_GLYPHS if unicode else ASCII_GLYPHS
+
+
+def _hex_to_rgb(value: str) -> tuple[int, int, int]:
+    raw = value.lstrip("#")
+    return int(raw[0:2], 16), int(raw[2:4], 16), int(raw[4:6], 16)
+
+
+def _rgb_to_hex(rgb: tuple[int, int, int]) -> str:
+    return "#{:02x}{:02x}{:02x}".format(*rgb)
+
+
+def sample_ramp(position: float, ramp: tuple[str, ...] = BRAND_RAMP) -> str:
+    """Sample a continuous color from ``ramp`` at ``position`` in ``[0, 1]``.
+
+    Interpolating between stops rather than snapping to the nearest one is what
+    keeps a wide gradient bar from showing visible banding.
+    """
+    if not ramp:
+        return INK_ON_DARK
+    if len(ramp) == 1:
+        return ramp[0]
+
+    clamped = min(max(position, 0.0), 1.0)
+    scaled = clamped * (len(ramp) - 1)
+    index = int(scaled)
+    if index >= len(ramp) - 1:
+        return ramp[-1]
+
+    blend = scaled - index
+    start = _hex_to_rgb(ramp[index])
+    end = _hex_to_rgb(ramp[index + 1])
+    return _rgb_to_hex(
+        (
+            round(start[0] + (end[0] - start[0]) * blend),
+            round(start[1] + (end[1] - start[1]) * blend),
+            round(start[2] + (end[2] - start[2]) * blend),
+        )
+    )
+
+
+def dim_hex(value: str, factor: float) -> str:
+    """Scale a hex color toward black, for pending or background elements."""
+    red, green, blue = _hex_to_rgb(value)
+    scale = min(max(factor, 0.0), 1.0)
+    return _rgb_to_hex((round(red * scale), round(green * scale), round(blue * scale)))
+
+
+def gradient_text(
+    value: str,
+    *,
+    ramp: tuple[str, ...] = BRAND_RAMP,
+    bold: bool = False,
+    offset: float = 0.0,
+    span: float = 1.0,
+) -> Text:
+    """Paint ``value`` with a per-character sweep through ``ramp``.
+
+    ``offset`` shifts the sweep so successive frames can animate a shimmer
+    without rebuilding the palette.
+    """
+    text = Text()
+    length = max(len(value), 1)
+    weight = "bold " if bold else ""
+    for index, character in enumerate(value):
+        position = (offset + (index / length) * span) % 1.0
+        text.append(character, style=f"{weight}{sample_ramp(position, ramp)}")
+    return text
+
+
+def gradient_rule(
+    width: int,
+    *,
+    glyphs: Glyphs,
+    thin: bool = False,
+    offset: float = 0.0,
+) -> Text:
+    """Build a full-width rule that frames branded sections.
+
+    Calm by design: a solid line with a short amber lead-in, echoing the logo's entry
+    node. ``offset`` is kept for callers that once animated the rule.
+    """
+    del offset
+    character = glyphs.thin_rule if thin else glyphs.rule
+    span = max(width, 1)
+    lead = min(4, span)
+    text = Text(character * lead, style=AMBER)
+    text.append(character * (span - lead), style=LINE)
+    return text
+
+
+def wordmark(color: str | None = None) -> Text:
+    """The ``10xgraph`` name as the CLI shows it: bold ink, like the logo.
+
+    Without ``color`` it uses the terminal's own foreground; pass ``INK_ON_DARK`` on a
+    surface that paints its own dark background.
+    """
+    return Text("10xgraph", style=f"bold {color}" if color else "bold")

tenxgraph_api/cli/core/validation.py

@@ -0,0 +1,251 @@
+"""Input validation utilities for the CLI."""
+
+import re
+from pathlib import Path
+from typing import Any
+
+from tenxgraph_api.cli.exceptions import ValidationError
+
+
+class Validator:
+    """Input validation utilities."""
+
+    @staticmethod
+    def validate_port(port: int) -> int:
+        """Validate port number.
+
+        Args:
+            port: Port number to validate
+
+        Returns:
+            Validated port number
+
+        Raises:
+            ValidationError: If port is invalid
+        """
+        if not isinstance(port, int):
+            raise ValidationError("Port must be an integer", field="port")
+
+        if port < 1 or port > 65535:  # noqa: PLR2004
+            raise ValidationError("Port must be between 1 and 65535", field="port")
+
+        return port
+
+    @staticmethod
+    def validate_host(host: str) -> str:
+        """Validate host address.
+
+        Args:
+            host: Host address to validate
+
+        Returns:
+            Validated host address
+
+        Raises:
+            ValidationError: If host is invalid
+        """
+        if not isinstance(host, str):
+            raise ValidationError("Host must be a string", field="host")
+
+        if not host.strip():
+            raise ValidationError("Host cannot be empty", field="host")
+
+        # Basic validation - could be enhanced with more sophisticated checks
+        if len(host) > 255:  # noqa: PLR2004
+            raise ValidationError("Host address too long", field="host")
+
+        return host.strip()
+
+    @staticmethod
+    def validate_path(path: str | Path, must_exist: bool = False) -> Path:
+        """Validate file path.
+
+        Args:
+            path: Path to validate
+            must_exist: Whether the path must exist
+
+        Returns:
+            Validated Path object
+
+        Raises:
+            ValidationError: If path is invalid
+        """
+        try:
+            path_obj = Path(path)
+        except (TypeError, ValueError) as e:
+            raise ValidationError(f"Invalid path: {e}", field="path") from e
+
+        if must_exist and not path_obj.exists():
+            raise ValidationError(f"Path does not exist: {path_obj}", field="path")
+
+        return path_obj
+
+    @staticmethod
+    def validate_python_version(version: str) -> str:
+        """Validate Python version string.
+
+        Args:
+            version: Python version to validate
+
+        Returns:
+            Validated version string
+
+        Raises:
+            ValidationError: If version is invalid
+        """
+        if not isinstance(version, str):
+            raise ValidationError("Python version must be a string", field="python_version")
+
+        # Pattern for semantic versioning (major.minor or major.minor.patch)
+        version_pattern = r"^(\d+)\.(\d+)(?:\.(\d+))?$"
+
+        if not re.match(version_pattern, version):
+            raise ValidationError(
+                "Python version must be in format 'X.Y' or 'X.Y.Z'", field="python_version"
+            )
+
+        # Extract major and minor versions
+        parts = version.split(".")
+        major, minor = int(parts[0]), int(parts[1])
+
+        # Validate Python version range (3.8+)
+        if major < 3 or (major == 3 and minor < 8):  # noqa: PLR2004
+            raise ValidationError("Python version must be 3.8 or higher", field="python_version")
+
+        return version
+
+    @staticmethod
+    def validate_service_name(name: str) -> str:
+        """Validate service name for Docker.
+
+        Args:
+            name: Service name to validate
+
+        Returns:
+            Validated service name
+
+        Raises:
+            ValidationError: If name is invalid
+        """
+        if not isinstance(name, str):
+            raise ValidationError("Service name must be a string", field="service_name")
+
+        name = name.strip()
+        if not name:
+            raise ValidationError("Service name cannot be empty", field="service_name")
+
+        # Docker service name validation
+        if not re.match(r"^[a-zA-Z0-9][a-zA-Z0-9_.-]*$", name):
+            raise ValidationError(
+                "Service name must start with alphanumeric character and "
+                "contain only alphanumeric, underscore, period, or hyphen",
+                field="service_name",
+            )
+
+        if len(name) > 63:  # noqa: PLR2004
+            raise ValidationError(
+                "Service name must be 63 characters or less", field="service_name"
+            )
+
+        return name
+
+    @staticmethod
+    def validate_config_structure(config: dict[str, Any]) -> dict[str, Any]:
+        """Validate configuration structure.
+
+        Args:
+            config: Configuration dictionary to validate
+
+        Returns:
+            Validated configuration
+
+        Raises:
+            ValidationError: If configuration is invalid
+        """
+        if not isinstance(config, dict):
+            raise ValidationError("Configuration must be a dictionary")
+
+        # Required fields
+        required_fields = ["agent"]
+        for field in required_fields:
+            if field not in config:
+                raise ValidationError(f"Missing required field: {field}")
+
+        # Validate agent field
+        agent = config["agent"]
+        if not isinstance(agent, str):
+            raise ValidationError("Field 'agent' must be a string")
+
+        return config
+
+    @staticmethod
+    def validate_environment_file(env_file: str | Path) -> Path:
+        """Validate environment file.
+
+        Args:
+            env_file: Path to environment file
+
+        Returns:
+            Validated Path object
+
+        Raises:
+            ValidationError: If environment file is invalid
+        """
+        env_path = Validator.validate_path(env_file, must_exist=True)
+
+        if not env_path.is_file():
+            raise ValidationError(f"Environment file is not a file: {env_path}", field="env_file")
+
+        # Basic validation of .env file format
+        try:
+            with env_path.open("r", encoding="utf-8") as f:
+                for line_num, line in enumerate(f, 1):
+                    up_line = line.strip()
+                    if up_line and not up_line.startswith("#") and "=" not in up_line:
+                        raise ValidationError(
+                            f"Invalid environment file format at line {line_num}: {up_line}",
+                            field="env_file",
+                        )
+        except UnicodeDecodeError as e:
+            raise ValidationError(
+                f"Environment file contains invalid characters: {e}", field="env_file"
+            ) from e
+        except OSError as e:
+            raise ValidationError(f"Cannot read environment file: {e}", field="env_file") from e
+
+        return env_path
+
+
+# Convenience functions for common validations
+def validate_cli_options(
+    host: str,
+    port: int,
+    config: str | None = None,
+    python_version: str | None = None,
+) -> dict[str, Any]:
+    """Validate common CLI options.
+
+    Args:
+        host: Host address
+        port: Port number
+        config: Optional config file path
+        python_version: Optional Python version
+
+    Returns:
+        Dictionary of validated options
+
+    Raises:
+        ValidationError: If any option is invalid
+    """
+    validated = {
+        "host": Validator.validate_host(host),
+        "port": Validator.validate_port(port),
+    }
+
+    if config:
+        validated["config"] = Validator.validate_path(config)
+
+    if python_version:
+        validated["python_version"] = Validator.validate_python_version(python_version)
+
+    return validated

tenxgraph_api/cli/exceptions.py

@@ -0,0 +1,129 @@
+"""Custom exceptions for the 10xGraph CLI."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+
+class CLIError(Exception):
+    """Base exception for all 10xGraph CLI errors."""
+
+    def __init__(
+        self,
+        message: str,
+        exit_code: int = 1,
+        *,
+        code: str = "AF-CMD-001",
+        hints: Sequence[str] = (),
+        docs_url: str | None = None,
+    ) -> None:
+        """Initialize the exception with a message and exit code.
+
+        Args:
+            message: Error message to display
+            exit_code: Exit code to use when terminating
+        """
+        super().__init__(message)
+        self.message = message
+        self.exit_code = exit_code
+        self.code = code
+        self.hints = tuple(hints)
+        self.docs_url = docs_url
+
+
+class ConfigurationError(CLIError):
+    """Raised when there are configuration-related errors."""
+
+    def __init__(self, message: str, config_path: str | None = None) -> None:
+        """Initialize configuration error.
+
+        Args:
+            message: Error message
+            config_path: Path to the problematic config file
+        """
+        super().__init__(message, exit_code=2, code="AF-CONFIG-001")
+        self.config_path = config_path
+
+
+class ValidationError(CLIError):
+    """Raised when input validation fails."""
+
+    def __init__(self, message: str, field: str | None = None) -> None:
+        """Initialize validation error.
+
+        Args:
+            message: Error message
+            field: Name of the field that failed validation
+        """
+        super().__init__(message, exit_code=3, code="AF-INPUT-001")
+        self.field = field
+
+
+class FileOperationError(CLIError):
+    """Raised when file operations fail."""
+
+    def __init__(self, message: str, file_path: str | None = None) -> None:
+        """Initialize file operation error.
+
+        Args:
+            message: Error message
+            file_path: Path to the problematic file
+        """
+        super().__init__(message, exit_code=1, code="AF-FILE-001")
+        self.file_path = file_path
+
+
+class TemplateError(CLIError):
+    """Raised when template operations fail."""
+
+    def __init__(self, message: str, template_name: str | None = None) -> None:
+        """Initialize template error.
+
+        Args:
+            message: Error message
+            template_name: Name of the problematic template
+        """
+        super().__init__(message, exit_code=1, code="AF-TEMPLATE-001")
+        self.template_name = template_name
+
+
+class ServerError(CLIError):
+    """Raised when server operations fail."""
+
+    def __init__(self, message: str, host: str | None = None, port: int | None = None) -> None:
+        """Initialize server error.
+
+        Args:
+            message: Error message
+            host: Server host
+            port: Server port
+        """
+        super().__init__(message, exit_code=1, code="AF-SERVER-001")
+        self.host = host
+        self.port = port
+
+
+class DockerError(CLIError):
+    """Raised when Docker-related operations fail."""
+
+    def __init__(self, message: str, dockerfile_path: str | None = None) -> None:
+        """Initialize Docker error.
+
+        Args:
+            message: Error message
+            dockerfile_path: Path to the Dockerfile
+        """
+        super().__init__(message, exit_code=1, code="AF-DOCKER-001")
+        self.dockerfile_path = dockerfile_path
+
+
+class DependencyError(CLIError):
+    """Raised when an optional feature dependency is missing or incompatible."""
+
+    def __init__(self, message: str, *, hints: Sequence[str] = ()) -> None:
+        super().__init__(
+            message,
+            exit_code=4,
+            code="AF-DEPS-001",
+            hints=hints,
+        )

tenxgraph_api/cli/logger.py

@@ -0,0 +1,84 @@
+"""Centralized logging configuration for the 10xGraph CLI."""
+
+from __future__ import annotations
+
+import logging
+import sys
+from typing import TextIO
+
+from .constants import LOG_DATE_FORMAT, LOG_FORMAT
+
+
+_LOGGER_NAME = "tenxgraph_api.cli"
+
+
+class CLILoggerMixin:
+    """Mixin that obtains a child of the invocation-wide CLI logger."""
+
+    def __init__(self, *args, **kwargs) -> None:
+        super().__init__(*args, **kwargs)
+        self.logger = get_logger(self.__class__.__name__)
+
+
+def get_logger(
+    name: str,
+    level: int = logging.INFO,
+    stream: TextIO | None = None,
+) -> logging.Logger:
+    """Return a child logger governed by the shared root configuration.
+
+    A custom stream is intended for isolated tests and receives a local handler.
+    Normal command loggers propagate to exactly one root handler so verbosity
+    changes apply consistently and messages cannot be duplicated.
+    """
+    logger = logging.getLogger(f"{_LOGGER_NAME}.{name}")
+
+    if stream is not None:
+        logger.handlers.clear()
+        logger.setLevel(level)
+        handler = logging.StreamHandler(stream)
+        handler.setLevel(level)
+        handler.setFormatter(_formatter())
+        logger.addHandler(handler)
+        logger.propagate = False
+        return logger
+
+    root_logger = logging.getLogger(_LOGGER_NAME)
+    if not root_logger.handlers:
+        setup_cli_logging(level=level)
+    logger.handlers.clear()
+    logger.setLevel(logging.NOTSET)
+    logger.propagate = True
+    return logger
+
+
+def setup_cli_logging(
+    level: int = logging.INFO,
+    quiet: bool = False,
+    verbose: bool = False,
+) -> None:
+    """Configure the one shared CLI logging handler."""
+    if quiet:
+        level = logging.ERROR
+    elif verbose:
+        level = logging.DEBUG
+
+    root_logger = logging.getLogger(_LOGGER_NAME)
+    root_logger.setLevel(level)
+    root_logger.handlers.clear()
+
+    handler = logging.StreamHandler(sys.stderr)
+    handler.setLevel(level)
+    handler.setFormatter(_formatter())
+    root_logger.addHandler(handler)
+    root_logger.propagate = False
+
+
+def create_debug_logger(name: str) -> logging.Logger:
+    """Return a child logger after enabling debug output globally."""
+    setup_cli_logging(level=logging.DEBUG)
+    return get_logger(name)
+
+
+def _formatter() -> logging.Formatter:
+    return logging.Formatter(fmt=LOG_FORMAT, datefmt=LOG_DATE_FORMAT)