glaip-sdk 0.0.10__py3-none-any.whl → 0.0.12__py3-none-any.whl

glaip_sdk/cli/mcp_validators.py

@@ -0,0 +1,297 @@
+"""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:
+    """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/parsers/__init__.py

@@ -0,0 +1,9 @@
+"""CLI input parsers.
+
+Authors:
+    Putu Ravindra Wiguna (putu.r.wiguna@gdplabs.id)
+"""
+
+from glaip_sdk.cli.parsers.json_input import parse_json_input
+
+__all__ = ["parse_json_input"]

glaip_sdk/cli/parsers/json_input.py

@@ -0,0 +1,140 @@
+"""JSON input parser for CLI options.
+
+Handles both inline JSON strings and @file references.
+
+Authors:
+    Putu Ravindra Wiguna (putu.r.wiguna@gdplabs.id)
+"""
+
+import json
+import os
+from pathlib import Path
+from typing import Any
+
+import click
+
+
+def _format_file_error(
+    prefix: str, file_path_str: str, resolved_path: Path, *, detail: str | None = None
+) -> str:
+    """Format a file-related error message with path context.
+
+    Args:
+        prefix: Main error message
+        file_path_str: Original file path string provided by user
+        resolved_path: Resolved absolute path
+        detail: Optional additional detail to append
+
+    Returns:
+        Formatted error message string with file path context
+
+    Examples:
+        >>> from pathlib import Path
+        >>> _format_file_error("File not found", "config.json", Path("/abs/config.json"))
+        'File not found: config.json\\nResolved path: /abs/config.json'
+    """
+    parts = [f"{prefix}: {file_path_str}", f"Resolved path: {resolved_path}"]
+    if detail:
+        parts.append(detail)
+    return "\n".join(parts)
+
+
+def _parse_json_from_file(file_path_str: str) -> Any:
+    """Parse JSON from a file path.
+
+    Args:
+        file_path_str: Path to the JSON file (without @ prefix).
+
+    Returns:
+        Parsed dictionary from file.
+
+    Raises:
+        click.ClickException: If file not found, not readable, empty, or invalid JSON.
+    """
+    # Resolve relative paths against CWD
+    file_path = Path(file_path_str)
+    if not file_path.is_absolute():
+        file_path = Path.cwd() / file_path
+
+    # Check if file exists and is a regular file
+    if not file_path.is_file():
+        raise click.ClickException(
+            _format_file_error("File not found or not a file", file_path_str, file_path)
+        )
+
+    # Check if file is readable
+    if not os.access(file_path, os.R_OK):
+        raise click.ClickException(
+            _format_file_error(
+                "File not readable (permission denied)", file_path_str, file_path
+            )
+        )
+
+    # Read file content
+    try:
+        content = file_path.read_text(encoding="utf-8")
+    except Exception as e:
+        raise click.ClickException(
+            _format_file_error(
+                "Error reading file", file_path_str, file_path, detail=f"Error: {e}"
+            )
+        )
+
+    # Check for empty content
+    if not content.strip():
+        raise click.ClickException(
+            _format_file_error("File is empty", file_path_str, file_path)
+        )
+
+    # Parse JSON from file content
+    try:
+        return json.loads(content)
+    except json.JSONDecodeError as e:
+        raise click.ClickException(
+            _format_file_error(
+                "Invalid JSON in file",
+                file_path_str,
+                file_path,
+                detail=f"Error: {e.msg} at line {e.lineno}, column {e.colno}",
+            )
+        )
+
+
+def parse_json_input(value: str | None) -> Any:
+    """Parse JSON input from inline string or file reference.
+
+    Args:
+        value: JSON string or @file reference. If None, returns None.
+
+    Returns:
+        Parsed JSON value (dict, list, str, int, float, bool, None) or None if value is None.
+
+    Raises:
+        click.ClickException: If file not found, not readable, empty, or invalid JSON.
+
+    Examples:
+        >>> parse_json_input('{"key": "value"}')
+        {'key': 'value'}
+
+        >>> parse_json_input('@/path/to/config.json')
+        # Returns content of config.json parsed as JSON
+
+        >>> parse_json_input(None)
+        None
+    """
+    if value is None:
+        return None
+
+    # Check if value is a file reference (strip whitespace first)
+    trimmed = value.strip()
+    if trimmed.startswith("@"):
+        return _parse_json_from_file(trimmed[1:])
+
+    # Parse inline JSON
+    try:
+        return json.loads(value)
+    except json.JSONDecodeError as e:
+        raise click.ClickException(
+            f"Invalid JSON in inline value\n"
+            f"Error: {e.msg} at line {e.lineno}, column {e.colno}"
+        )

glaip_sdk/cli/slash/session.py

@@ -76,6 +76,8 @@ class SlashSession:
         self._setup_prompt_toolkit()
         self._register_defaults()
         self._branding = AIPBranding.create_from_sdk()
+        self._suppress_login_layout = False
+        self._default_actions_shown = False
 
     # ------------------------------------------------------------------
     # Session orchestration
@@ -96,7 +98,9 @@ class SlashSession:
         if not self._ensure_configuration():
             return
 
-        self._render_header(initial=True)
+        self._render_header(initial=not self._welcome_rendered)
+        if not self._default_actions_shown:
+            self._show_default_quick_actions()
         self._render_home_hint()
         self._run_interactive_loop()
 
@@ -154,6 +158,7 @@ class SlashSession:
             self.console.print(
                 "[yellow]Configuration required.[/] Launching `/login` wizard..."
             )
+            self._suppress_login_layout = True
             try:
                 self._cmd_login([], False)
             except KeyboardInterrupt:
@@ -161,6 +166,8 @@ class SlashSession:
                     "[red]Configuration aborted. Closing the command palette.[/red]"
                 )
                 return False
+            finally:
+                self._suppress_login_layout = False
 
         return True
 
@@ -260,13 +267,12 @@ class SlashSession:
         try:
             self.ctx.invoke(configure_command)
             self._config_cache = None
-            self._render_header(initial=True)
-            self._show_quick_actions(
-                [
-                    (self.STATUS_COMMAND, "Verify the connection"),
-                    (self.AGENTS_COMMAND, "Pick an agent to inspect or run"),
-                ]
-            )
+            if self._suppress_login_layout:
+                self._welcome_rendered = False
+                self._default_actions_shown = False
+            else:
+                self._render_header(initial=True)
+                self._show_default_quick_actions()
         except click.ClickException as exc:
             self.console.print(f"[red]{exc}[/red]")
         return True
@@ -349,7 +355,7 @@ class SlashSession:
             # running.
             return True
 
-        self.console.print("[cyan]Closing the command palette.")
+        self.console.print("[cyan]Closing the command palette.[/cyan]")
         return False
 
     # ------------------------------------------------------------------
@@ -772,6 +778,15 @@ class SlashSession:
             label = recent.get("name") or recent.get("id") or "-"
             lines.append(f"[dim]Recent agent[/dim]: {label} [{recent.get('id', '-')}]")
 
+    def _show_default_quick_actions(self) -> None:
+        self._show_quick_actions(
+            [
+                (self.STATUS_COMMAND, "Verify the connection"),
+                (self.AGENTS_COMMAND, "Pick an agent to inspect or run"),
+            ]
+        )
+        self._default_actions_shown = True
+
     def _render_home_hint(self) -> None:
         self.console.print(
             AIPPanel(

glaip_sdk/cli/update_notifier.py

@@ -0,0 +1,107 @@
+"""Utility helpers for checking and displaying SDK update notifications.
+
+Author:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Callable
+
+import httpx
+from packaging.version import InvalidVersion, Version
+from rich.console import Console
+
+from glaip_sdk.rich_components import AIPPanel
+
+FetchLatestVersion = Callable[[], str | None]
+
+PYPI_JSON_URL = "https://pypi.org/pypi/{package}/json"
+DEFAULT_TIMEOUT = 1.5  # seconds
+
+
+def _parse_version(value: str) -> Version | None:
+    """Parse a version string into a `Version`, returning None on failure."""
+    try:
+        return Version(value)
+    except InvalidVersion:
+        return None
+
+
+def _fetch_latest_version(package_name: str) -> str | None:
+    """Fetch the latest published version from PyPI."""
+    url = PYPI_JSON_URL.format(package=package_name)
+    timeout = httpx.Timeout(DEFAULT_TIMEOUT)
+
+    try:
+        with httpx.Client(timeout=timeout) as client:
+            response = client.get(url, headers={"Accept": "application/json"})
+            response.raise_for_status()
+            payload = response.json()
+    except httpx.HTTPError:
+        return None
+    except ValueError:
+        return None
+
+    info = payload.get("info") if isinstance(payload, dict) else None
+    latest_version = info.get("version") if isinstance(info, dict) else None
+    if isinstance(latest_version, str) and latest_version.strip():
+        return latest_version.strip()
+    return None
+
+
+def _should_check_for_updates() -> bool:
+    """Return False when update checks are explicitly disabled."""
+    return os.getenv("AIP_NO_UPDATE_CHECK") is None
+
+
+def _build_update_panel(
+    current_version: str,
+    latest_version: str,
+) -> AIPPanel:
+    """Create a Rich panel that prompts the user to update."""
+    message = (
+        f"[bold yellow]✨ Update available![/bold yellow] "
+        f"{current_version} → {latest_version}\n\n"
+        "See the latest release notes:\n"
+        f"https://pypi.org/project/glaip-sdk/{latest_version}/\n\n"
+        "[cyan]Run[/cyan] [bold]aip update[/bold] to install."
+    )
+    return AIPPanel(
+        message,
+        title="[bold green]AIP SDK Update[/bold green]",
+    )
+
+
+def maybe_notify_update(
+    current_version: str,
+    *,
+    package_name: str = "glaip-sdk",
+    console: Console | None = None,
+    fetch_latest_version: FetchLatestVersion | None = None,
+) -> None:
+    """Check PyPI for a newer version and display a prompt if one exists.
+
+    This function deliberately swallows network errors to avoid impacting CLI
+    startup time when offline or when PyPI is unavailable.
+    """
+    if not _should_check_for_updates():
+        return
+
+    fetcher = fetch_latest_version or (lambda: _fetch_latest_version(package_name))
+    latest_version = fetcher()
+    if not latest_version:
+        return
+
+    current = _parse_version(current_version)
+    latest = _parse_version(latest_version)
+    if current is None or latest is None or latest <= current:
+        return
+
+    active_console = console or Console()
+    panel = _build_update_panel(current_version, latest_version)
+    active_console.print(panel)
+
+
+__all__ = ["maybe_notify_update"]