glaip-sdk 0.6.15b2__py3-none-any.whl → 0.6.15b3__py3-none-any.whl

glaip_sdk/cli/masking.py

@@ -0,0 +1,136 @@
+"""Masking helpers for CLI output.
+
+Authors:
+    Putu Ravindra Wiguna (putu.r.wiguna@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from glaip_sdk.cli.constants import MASK_SENSITIVE_FIELDS, MASKING_ENABLED
+
+__all__ = [
+    "mask_payload",
+    "mask_rows",
+    "_mask_value",
+    "_mask_any",
+    "_maybe_mask_row",
+    "_resolve_mask_fields",
+    "mask_api_key_display",
+]
+
+
+def _mask_value(raw: Any) -> str:
+    """Return a masked representation of the provided value.
+
+    Args:
+        raw: The raw value to mask, converted to string.
+
+    Returns:
+        str: A masked representation showing first 4 and last 4 characters
+             separated by dots, or "••••" for strings ≤ 8 characters.
+    """
+    text = str(raw)
+    if len(text) <= 8:
+        return "••••"
+    return f"{text[:4]}••••••••{text[-4:]}"
+
+
+def _mask_any(value: Any, mask_fields: set[str]) -> Any:
+    """Recursively mask sensitive fields in mappings and iterables.
+
+    Args:
+        value: The value to process - can be dict, list, or any other type.
+        mask_fields: Set of field names (lowercase) that should be masked.
+
+    Returns:
+        Any: The processed value with sensitive fields masked. Dicts and lists
+             are processed recursively, other values are returned unchanged.
+    """
+    if isinstance(value, dict):
+        masked: dict[Any, Any] = {}
+        for key, raw in value.items():
+            if isinstance(key, str) and key.lower() in mask_fields and raw is not None:
+                masked[key] = _mask_value(raw)
+            else:
+                masked[key] = _mask_any(raw, mask_fields)
+        return masked
+
+    if isinstance(value, list):
+        return [_mask_any(item, mask_fields) for item in value]
+
+    return value
+
+
+def _maybe_mask_row(row: dict[str, Any], mask_fields: set[str]) -> dict[str, Any]:
+    """Mask a single row when masking is enabled.
+
+    Args:
+        row: A dictionary representing a single row of data.
+        mask_fields: Set of field names to mask. If empty, returns row unchanged.
+
+    Returns:
+        dict[str, Any]: The row with sensitive fields masked, or the original
+                       row if no mask_fields are provided.
+    """
+    if not mask_fields:
+        return row
+    return _mask_any(row, mask_fields)
+
+
+def _resolve_mask_fields() -> set[str]:
+    """Return the configured set of fields that should be masked."""
+    if not MASKING_ENABLED:
+        return set()
+    return set(MASK_SENSITIVE_FIELDS)
+
+
+def mask_payload(payload: Any) -> Any:
+    """Mask sensitive values in an arbitrary payload when masking is enabled.
+
+    Args:
+        payload: Any data structure (dict, list, or primitive) to mask.
+
+    Returns:
+        Any: The payload with sensitive fields masked based on configuration.
+    """
+    mask_fields = _resolve_mask_fields()
+    if not mask_fields:
+        return payload
+    try:
+        return _mask_any(payload, mask_fields)
+    except Exception:
+        return payload
+
+
+def mask_rows(rows: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    """Mask sensitive values in row-oriented data when masking is enabled.
+
+    Args:
+        rows: List of dictionaries representing rows of tabular data.
+
+    Returns:
+        list[dict[str, Any]]: List of rows with sensitive fields masked based
+                              on configuration. Returns original rows if
+                              masking is disabled or if an error occurs.
+    """
+    mask_fields = _resolve_mask_fields()
+    if not mask_fields:
+        return rows
+    try:
+        return [_maybe_mask_row(row, mask_fields) for row in rows]
+    except Exception:
+        return rows
+
+
+def mask_api_key_display(value: str | None) -> str:
+    """Mask API keys for CLI display while preserving readability for short keys."""
+    if not value:
+        return ""
+    length = len(value)
+    if length <= 4:
+        return "***"
+    if length <= 8:
+        return value[:1] + "••••" + value[-1:]
+    return value[:4] + "••••" + value[-4:]

glaip_sdk/cli/mcp_validators.py

@@ -0,0 +1,287 @@
+"""MCP configuration and authentication validation for CLI.
+
+This module provides validation functions for MCP config and auth structures
+that are used in CLI commands. It ensures data conforms to the MCP schema
+documented in docs/reference/schemas/mcps.md.
+
+Authors:
+    Putu Ravindra Wiguna (putu.r.wiguna@gdplabs.id)
+"""
+
+from typing import Any
+from urllib.parse import urlparse
+
+import click
+
+
+def format_validation_error(prefix: str, detail: str | None = None) -> str:
+    r"""Format a validation error message with optional detail.
+
+    Args:
+        prefix: Main error message
+        detail: Optional additional detail to append
+
+    Returns:
+        Formatted error message string
+
+    Examples:
+        >>> format_validation_error("Invalid config", "Missing 'url' field")
+        "Invalid config\nMissing 'url' field"
+    """
+    parts = [prefix]
+    if detail:
+        parts.append(detail)
+    return "\n".join(parts)
+
+
+def validate_mcp_config_structure(
+    config: Any, *, transport: str | None = None, source: str = "--config"
+) -> dict[str, Any]:
+    """Validate MCP configuration structure for CLI commands.
+
+    Validates that the config is a dictionary with a valid 'url' field.
+    The 'url' must be an absolute HTTP/HTTPS URL as required by the MCP schema.
+
+    Args:
+        config: Configuration value to validate (expected to be a dict)
+        transport: Optional transport type ('http' or 'sse') for context in errors
+        source: Source parameter name for error messages (default: "--config")
+
+    Returns:
+        Validated configuration dictionary
+
+    Raises:
+        click.ClickException: If config is not a dict, missing 'url', or URL is invalid
+
+    Examples:
+        >>> validate_mcp_config_structure({"url": "https://api.example.com"})
+        {'url': 'https://api.example.com'}
+
+        >>> validate_mcp_config_structure([1, 2, 3])  # doctest: +SKIP
+        ClickException: Invalid --config value
+        Expected a JSON object representing MCP configuration.
+
+    Schema Reference:
+        See docs/reference/schemas/mcps.md - Config Object Structure
+        - Required field: 'url' (string, must be valid HTTP/HTTPS URL)
+        - Additional fields allowed and passed through
+    """
+    if not isinstance(config, dict):
+        raise click.ClickException(
+            format_validation_error(
+                f"Invalid {source} value",
+                "Expected a JSON object representing MCP configuration.",
+            )
+        )
+
+    url_value = config.get("url")
+    if not isinstance(url_value, str) or not url_value.strip():
+        requirement = "Missing required 'url' field with a non-empty string value."
+        if transport:
+            requirement += f" Required for transport '{transport}'."
+        raise click.ClickException(format_validation_error(f"Invalid {source} value", requirement))
+
+    parsed_url = urlparse(url_value)
+    if parsed_url.scheme not in {"http", "https"} or not parsed_url.netloc:
+        raise click.ClickException(
+            format_validation_error(
+                f"Invalid {source} value",
+                "'url' must be an absolute HTTP or HTTPS URL.",
+            )
+        )
+
+    return config
+
+
+def _validate_headers_mapping(headers: Any, *, source: str, context: str) -> dict[str, str]:
+    """Validate headers mapping for authentication.
+
+    Args:
+        headers: Headers value to validate (expected to be a non-empty dict)
+        source: Source parameter name for error messages
+        context: Context description for error messages (e.g., "bearer-token authentication")
+
+    Returns:
+        Validated headers dictionary with string keys and values
+
+    Raises:
+        click.ClickException: If headers is not a dict, empty, or contains invalid entries
+    """
+    if not isinstance(headers, dict) or not headers:
+        raise click.ClickException(
+            format_validation_error(
+                f"Invalid {source} value",
+                f"{context} must provide a non-empty 'headers' object with string keys and values.",
+            )
+        )
+
+    normalized: dict[str, str] = {}
+    for key, value in headers.items():
+        if not isinstance(key, str) or not key.strip():
+            raise click.ClickException(
+                format_validation_error(
+                    f"Invalid {source} value",
+                    "Header names must be non-empty strings.",
+                )
+            )
+        if not isinstance(value, str) or not value.strip():
+            raise click.ClickException(
+                format_validation_error(
+                    f"Invalid {source} value",
+                    f"Header '{key}' must have a non-empty string value.",
+                )
+            )
+        normalized[key] = value
+    return normalized
+
+
+def _validate_bearer_token_auth(auth: dict[str, Any], source: str) -> dict[str, Any]:
+    """Validate bearer-token authentication.
+
+    Args:
+        auth: Authentication dictionary
+        source: Source parameter name for error messages
+
+    Returns:
+        Validated bearer-token authentication dictionary
+
+    Raises:
+        click.ClickException: If bearer-token structure is invalid
+    """
+    token = auth.get("token")
+    if isinstance(token, str) and token.strip():
+        return {"type": "bearer-token", "token": token}
+    headers = auth.get("headers")
+    normalized_headers = _validate_headers_mapping(headers, source=source, context="bearer-token authentication")
+    return {"type": "bearer-token", "headers": normalized_headers}
+
+
+def _validate_api_key_auth(auth: dict[str, Any], source: str) -> dict[str, Any]:
+    """Validate api-key authentication.
+
+    Args:
+        auth: Authentication dictionary
+        source: Source parameter name for error messages
+
+    Returns:
+        Validated api-key authentication dictionary
+
+    Raises:
+        click.ClickException: If api-key structure is invalid
+    """
+    headers = auth.get("headers")
+    if headers is not None:
+        normalized_headers = _validate_headers_mapping(headers, source=source, context="api-key authentication")
+        return {"type": "api-key", "headers": normalized_headers}
+
+    key = auth.get("key")
+    value = auth.get("value")
+    if not isinstance(key, str) or not key.strip():
+        raise click.ClickException(
+            format_validation_error(
+                f"Invalid {source} value",
+                "api-key authentication requires a non-empty 'key'.",
+            )
+        )
+    if not isinstance(value, str) or not value.strip():
+        raise click.ClickException(
+            format_validation_error(
+                f"Invalid {source} value",
+                "api-key authentication requires a non-empty 'value'.",
+            )
+        )
+    return {"type": "api-key", "key": key, "value": value}
+
+
+def _validate_custom_header_auth(auth: dict[str, Any], source: str) -> dict[str, Any]:
+    """Validate custom-header authentication.
+
+    Args:
+        auth: Authentication dictionary
+        source: Source parameter name for error messages
+
+    Returns:
+        Validated custom-header authentication dictionary
+
+    Raises:
+        click.ClickException: If custom-header structure is invalid
+    """
+    headers = auth.get("headers")
+    normalized_headers = _validate_headers_mapping(headers, source=source, context="custom-header authentication")
+    return {"type": "custom-header", "headers": normalized_headers}
+
+
+def validate_mcp_auth_structure(auth: Any, *, source: str = "--auth") -> dict[str, Any]:
+    """Validate MCP authentication structure for CLI commands.
+
+    Validates authentication objects according to the MCP schema, supporting:
+    - no-auth: No authentication required
+    - bearer-token: Bearer token via 'token' field or 'headers'
+    - api-key: API key via 'key'/'value' fields or 'headers'
+    - custom-header: Custom headers via 'headers' object
+
+    Args:
+        auth: Authentication value to validate (expected to be a dict or None)
+        source: Source parameter name for error messages (default: "--auth")
+
+    Returns:
+        Validated authentication dictionary, or empty dict if auth is None
+
+    Raises:
+        click.ClickException: If auth structure is invalid or type is unsupported
+
+    Examples:
+        >>> validate_mcp_auth_structure(None)
+        {}
+
+        >>> validate_mcp_auth_structure({"type": "no-auth"})
+        {'type': 'no-auth'}
+
+        >>> validate_mcp_auth_structure({"type": "bearer-token", "token": "abc123"})
+        {'type': 'bearer-token', 'token': 'abc123'}
+
+    Schema Reference:
+        See docs/reference/schemas/mcps.md - Authentication Types
+        - Required field: 'type' (string, one of: no-auth, bearer-token, api-key, custom-header)
+        - Additional fields depend on type
+    """
+    if auth is None:
+        return {}
+
+    if not isinstance(auth, dict):
+        raise click.ClickException(
+            format_validation_error(
+                f"Invalid {source} value",
+                "Expected a JSON object representing MCP authentication.",
+            )
+        )
+
+    raw_type = auth.get("type")
+    if not isinstance(raw_type, str) or not raw_type.strip():
+        raise click.ClickException(
+            format_validation_error(
+                f"Invalid {source} value",
+                "Authentication objects must include a non-empty 'type' field.",
+            )
+        )
+
+    auth_type = raw_type.strip()
+
+    # Dispatch to type-specific validators
+    if auth_type == "no-auth":
+        return {"type": "no-auth"}
+    if auth_type == "bearer-token":
+        return _validate_bearer_token_auth(auth, source)
+    if auth_type == "api-key":
+        return _validate_api_key_auth(auth, source)
+    if auth_type == "custom-header":
+        return _validate_custom_header_auth(auth, source)
+
+    # Unknown type
+    raise click.ClickException(
+        format_validation_error(
+            f"Invalid {source} value",
+            f"Unsupported authentication type '{auth_type}'. "
+            f"Supported types: no-auth, bearer-token, api-key, custom-header",
+        )
+    )

glaip_sdk/cli/pager.py

@@ -0,0 +1,266 @@
+"""Pager-related helpers for CLI output.
+
+Authors:
+    Putu Ravindra Wiguna (putu.r.wiguna@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+import importlib
+import io
+import os
+import platform
+import shlex
+import shutil
+import subprocess
+import tempfile
+from collections.abc import Callable
+from typing import Any
+
+from rich.console import Console
+
+from glaip_sdk.cli.constants import PAGER_HEADER_ENABLED, PAGER_MODE, PAGER_WRAP_LINES
+
+__all__ = [
+    "console",
+    "_prepare_pager_env",
+    "_render_ansi",
+    "_pager_header",
+    "_should_use_pager",
+    "_resolve_pager_command",
+    "_run_less_pager",
+    "_run_more_pager",
+    "_run_pager_with_temp_file",
+    "_page_with_system_pager",
+    "_should_page_output",
+]
+
+console: Console | None = None
+
+
+def _get_console() -> Console:
+    """Return the active console instance.
+
+    Returns:
+        Console: The active Rich console instance
+    """
+    global console
+    try:
+        cli_utils = importlib.import_module("glaip_sdk.cli.utils")
+    except Exception:  # pragma: no cover - fallback during import cycles
+        cli_utils = None
+
+    current_console = getattr(cli_utils, "console", None) if cli_utils else None
+    if current_console is not None and current_console is not console:
+        console = current_console
+
+    if console is None:
+        console = Console()
+    return console
+
+
+def _prepare_pager_env(clear_on_exit: bool = True) -> None:
+    """Configure LESS flags for a predictable, high-quality UX.
+
+    Sets sensible defaults for the system pager:
+      -R  : pass ANSI color escapes
+      -S  : chop long lines (horizontal scroll with ←/→)
+    (No -F, no -X) so we open a full-screen pager and clear on exit.
+    Toggle wrapping via `PAGER_WRAP_LINES` (True drops -S).
+
+    Args:
+        clear_on_exit: Whether to clear the pager on exit (default: True)
+
+    Returns:
+        None
+    """
+    os.environ.pop("LESSSECURE", None)
+    if os.getenv("LESS") is None:
+        base = "-R" if PAGER_WRAP_LINES else "-RS"
+        default_flags = base if clear_on_exit else (base + "FX")
+        os.environ["LESS"] = default_flags
+
+
+def _render_ansi(renderable: Any) -> str:
+    """Render a Rich renderable to an ANSI string suitable for piping to 'less'.
+
+    Args:
+        renderable: Any Rich-compatible renderable object
+
+    Returns:
+        str: ANSI string representation of the renderable
+    """
+    active_console = _get_console()
+    buf = io.StringIO()
+    tmp_console = Console(
+        file=buf,
+        force_terminal=True,
+        color_system=active_console.color_system or "auto",
+        width=active_console.size.width or 100,
+        legacy_windows=False,
+        soft_wrap=False,
+        record=False,
+    )
+    tmp_console.print(renderable)
+    return buf.getvalue()
+
+
+def _pager_header() -> str:
+    """Generate pager header with navigation instructions.
+
+    Returns:
+        str: Header text containing navigation help, or empty string if disabled
+    """
+    if not PAGER_HEADER_ENABLED:
+        return ""
+    return "\n".join(
+        [
+            "TABLE VIEW — ↑/↓ PgUp/PgDn, ←/→ horiz scroll (with -S), /search, n/N next/prev, h help, q quit",
+            "───────────────────────────────────────────────────────────────────────────────────────────────",
+            "",
+        ]
+    )
+
+
+def _should_use_pager() -> bool:
+    """Check if we should attempt to use a system pager.
+
+    Returns:
+        bool: True if we should use a pager, False otherwise
+    """
+    active_console = _get_console()
+    if not (active_console.is_terminal and os.isatty(1)):
+        return False
+    if (os.getenv("TERM") or "").lower() == "dumb":
+        return False
+    return True
+
+
+def _resolve_pager_command() -> tuple[list[str] | None, str | None]:
+    """Resolve the pager command and path to use.
+
+    Returns:
+        tuple[list[str] | None, str | None]: A tuple containing:
+            - list[str] | None: The pager command parts if PAGER is set to less, None otherwise
+            - str | None: The path to the less executable if found, None otherwise
+    """
+    pager_cmd = None
+    pager_env = os.getenv("PAGER")
+    if pager_env:
+        parts = shlex.split(pager_env)
+        if parts and os.path.basename(parts[0]).lower() == "less":
+            pager_cmd = parts
+
+    less_path = shutil.which("less")
+    return pager_cmd, less_path
+
+
+def _run_less_pager(pager_cmd: list[str] | None, less_path: str | None, tmp_path: str) -> None:
+    """Run less pager with appropriate command and flags.
+
+    Args:
+        pager_cmd: Custom pager command parts if PAGER is set to less, None otherwise
+        less_path: Path to the less executable, None if not found
+        tmp_path: Path to temporary file containing content to display
+
+    Returns:
+        None
+    """
+    if pager_cmd:
+        subprocess.run([*pager_cmd, tmp_path], check=False)
+    else:
+        flags = os.getenv("LESS", "-RS").split()
+        subprocess.run([less_path, *flags, tmp_path], check=False)
+
+
+def _run_more_pager(tmp_path: str) -> None:
+    """Run more pager as fallback.
+
+    Args:
+        tmp_path: Path to temporary file containing content to display
+
+    Returns:
+        None
+
+    Raises:
+        FileNotFoundError: If more command is not found
+    """
+    more_path = shutil.which("more")
+    if more_path:
+        subprocess.run([more_path, tmp_path], check=False)
+    else:
+        raise FileNotFoundError("more command not found")
+
+
+def _run_pager_with_temp_file(pager_runner: Callable[[str], None], ansi_text: str) -> bool:
+    """Run a pager using a temporary file containing the content.
+
+    Args:
+        pager_runner: Function that takes a temp file path and runs the pager
+        ansi_text: ANSI-formatted text content to display
+
+    Returns:
+        bool: True if pager executed successfully, False if there was an exception
+    """
+    _prepare_pager_env(clear_on_exit=True)
+    with tempfile.NamedTemporaryFile("w", delete=False, encoding="utf-8") as tmp:
+        tmp.write(_pager_header())
+        tmp.write(ansi_text)
+        tmp_path = tmp.name
+    try:
+        pager_runner(tmp_path)
+        return True
+    except Exception:
+        return False
+    finally:
+        try:
+            os.unlink(tmp_path)
+        except Exception:
+            pass
+
+
+def _page_with_system_pager(ansi_text: str) -> bool:
+    """Prefer 'less' with a temp file so stdin remains the TTY.
+
+    Args:
+        ansi_text: ANSI-formatted text content to display in the pager
+
+    Returns:
+        bool: True if pager was executed successfully, False otherwise
+    """
+    if not _should_use_pager():
+        return False
+
+    pager_cmd, less_path = _resolve_pager_command()
+
+    if pager_cmd or less_path:
+        return _run_pager_with_temp_file(lambda tmp_path: _run_less_pager(pager_cmd, less_path, tmp_path), ansi_text)
+
+    if platform.system().lower().startswith("win"):
+        return False
+
+    return _run_pager_with_temp_file(_run_more_pager, ansi_text)
+
+
+def _should_page_output(row_count: int, is_tty: bool) -> bool:
+    """Determine if output should be paginated based on content size and terminal.
+
+    Args:
+        row_count: Number of rows in the content to display
+        is_tty: Whether the output is going to a terminal
+
+    Returns:
+        bool: True if output should be paginated, False otherwise
+    """
+    active_console = _get_console()
+    pager_mode = (PAGER_MODE or "auto").lower()
+    if pager_mode in ("0", "off", "false"):
+        return False
+    if pager_mode in ("1", "on", "true"):
+        return is_tty
+    try:
+        term_h = active_console.size.height or 24
+        approx_lines = 5 + row_count
+        return is_tty and (approx_lines >= term_h * 0.5)
+    except Exception:
+        return is_tty

glaip_sdk/cli/parsers/__init__.py

@@ -0,0 +1,7 @@
+"""CLI input parsers.
+
+Authors:
+    Putu Ravindra Wiguna (putu.r.wiguna@gdplabs.id)
+"""
+
+__all__: list[str] = []