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

glaip_sdk/cli/commands/mcps.py

@@ -5,6 +5,7 @@ Authors:
 """
 
 import json
+import sys
 from pathlib import Path
 from typing import Any
 
@@ -21,9 +22,6 @@ from glaip_sdk.cli.display import (
     handle_json_output,
     handle_rich_output,
 )
-from glaip_sdk.cli.io import (
-    export_resource_to_file_with_validation as export_resource_to_file,
-)
 from glaip_sdk.cli.io import (
     fetch_raw_resource_details,
 )
@@ -40,20 +38,41 @@ from glaip_sdk.cli.utils import (
 )
 from glaip_sdk.rich_components import AIPPanel
 from glaip_sdk.utils import format_datetime
+from glaip_sdk.utils.serialization import (
+    build_mcp_export_payload,
+    write_resource_export,
+)
 
 console = Console()
 
 
 @click.group(name="mcps", no_args_is_help=True)
 def mcps_group() -> None:
-    """MCP management operations."""
+    """MCP management operations.
+
+    Provides commands for creating, listing, updating, deleting, and managing
+    Model Context Protocol (MCP) configurations.
+    """
     pass
 
 
 def _resolve_mcp(
     ctx: Any, client: Any, ref: str, select: int | None = None
 ) -> Any | None:
-    """Resolve MCP reference (ID or name) with ambiguity handling."""
+    """Resolve MCP reference (ID or name) with ambiguity handling.
+
+    Args:
+        ctx: Click context object
+        client: API client instance
+        ref: MCP reference (ID or name)
+        select: Index to select when multiple matches found
+
+    Returns:
+        MCP object if found, None otherwise
+
+    Raises:
+        ClickException: If MCP not found or selection invalid
+    """
     return resolve_resource_reference(
         ctx,
         client,
@@ -70,7 +89,14 @@ def _resolve_mcp(
 @output_flags()
 @click.pass_context
 def list_mcps(ctx: Any) -> None:
-    """List all MCPs."""
+    """List all MCPs in a formatted table.
+
+    Args:
+        ctx: Click context containing output format preferences
+
+    Raises:
+        ClickException: If API request fails
+    """
     try:
         client = get_client(ctx)
         with spinner_context(
@@ -117,7 +143,18 @@ def list_mcps(ctx: Any) -> None:
 def create(
     ctx: Any, name: str, transport: str, description: str | None, config: str | None
 ) -> None:
-    """Create a new MCP."""
+    """Create a new MCP with specified configuration.
+
+    Args:
+        ctx: Click context containing output format preferences
+        name: MCP name (required)
+        transport: MCP transport protocol (required)
+        description: Optional MCP description
+        config: JSON configuration string for MCP settings
+
+    Raises:
+        ClickException: If JSON parsing fails or API request fails
+    """
     try:
         client = get_client(ctx)
 
@@ -163,22 +200,191 @@ def create(
         raise click.ClickException(str(e))
 
 
+def _handle_mcp_export(
+    ctx: Any,
+    client: Any,
+    mcp: Any,
+    export_path: Path,
+    no_auth_prompt: bool,
+    auth_placeholder: str,
+) -> None:
+    """Handle MCP export to file with format detection and auth handling.
+
+    Args:
+        ctx: Click context for spinner management
+        client: API client for fetching MCP details
+        mcp: MCP object to export
+        export_path: Target file path (format detected from extension)
+        no_auth_prompt: Skip interactive secret prompts if True
+        auth_placeholder: Placeholder text for missing secrets
+
+    Note:
+        Supports JSON (.json) and YAML (.yaml/.yml) export formats.
+        In interactive mode, prompts for secret values.
+        In non-interactive mode, uses placeholder values.
+    """
+    # Auto-detect format from file extension
+    detected_format = detect_export_format(export_path)
+
+    # Always export comprehensive data - re-fetch with full details
+    try:
+        with spinner_context(
+            ctx,
+            "[bold blue]Fetching complete MCP details…[/bold blue]",
+            console_override=console,
+        ):
+            mcp = client.mcps.get_mcp_by_id(mcp.id)
+    except Exception as e:
+        console.print(
+            Text(f"[yellow]⚠️  Could not fetch full MCP details: {e}[/yellow]")
+        )
+        console.print(Text("[yellow]⚠️  Proceeding with available data[/yellow]"))
+
+    # Determine if we should prompt for secrets
+    prompt_for_secrets = not no_auth_prompt and sys.stdin.isatty()
+
+    # Warn user if non-interactive mode forces placeholder usage
+    if not no_auth_prompt and not sys.stdin.isatty():
+        console.print(
+            Text(
+                "[yellow]⚠️  Non-interactive mode detected. "
+                "Using placeholder values for secrets.[/yellow]"
+            )
+        )
+
+    # Build and write export payload
+    if prompt_for_secrets:
+        # Interactive mode: no spinner during prompts
+        export_payload = build_mcp_export_payload(
+            mcp,
+            prompt_for_secrets=prompt_for_secrets,
+            placeholder=auth_placeholder,
+            console=console,
+        )
+        with spinner_context(
+            ctx,
+            "[bold blue]Writing export file…[/bold blue]",
+            console_override=console,
+        ):
+            write_resource_export(export_path, export_payload, detected_format)
+    else:
+        # Non-interactive mode: spinner for entire export process
+        with spinner_context(
+            ctx,
+            "[bold blue]Exporting MCP configuration…[/bold blue]",
+            console_override=console,
+        ):
+            export_payload = build_mcp_export_payload(
+                mcp,
+                prompt_for_secrets=prompt_for_secrets,
+                placeholder=auth_placeholder,
+                console=console,
+            )
+            write_resource_export(export_path, export_payload, detected_format)
+
+    console.print(
+        Text(
+            f"[green]✅ Complete MCP configuration exported to: "
+            f"{export_path} (format: {detected_format})[/green]"
+        )
+    )
+
+
+def _display_mcp_details(ctx: Any, client: Any, mcp: Any) -> None:
+    """Display MCP details using raw API data or fallback to Pydantic model.
+
+    Args:
+        ctx: Click context containing output format preferences
+        client: API client for fetching raw MCP data
+        mcp: MCP object to display details for
+
+    Note:
+        Attempts to fetch raw API data first to preserve all fields.
+        Falls back to Pydantic model data if raw data unavailable.
+        Formats datetime fields for better readability.
+    """
+    # Try to fetch raw API data first to preserve ALL fields
+    with spinner_context(
+        ctx,
+        "[bold blue]Fetching detailed MCP data…[/bold blue]",
+        console_override=console,
+    ):
+        raw_mcp_data = fetch_raw_resource_details(client, mcp, "mcps")
+
+    if raw_mcp_data:
+        # Use raw API data - this preserves ALL fields
+        formatted_data = raw_mcp_data.copy()
+        if "created_at" in formatted_data:
+            formatted_data["created_at"] = format_datetime(formatted_data["created_at"])
+        if "updated_at" in formatted_data:
+            formatted_data["updated_at"] = format_datetime(formatted_data["updated_at"])
+
+        output_result(
+            ctx,
+            formatted_data,
+            title="MCP Details",
+            panel_title=f"🔌 {raw_mcp_data.get('name', 'Unknown')}",
+        )
+    else:
+        # Fall back to Pydantic model data
+        console.print("[yellow]Falling back to Pydantic model data[/yellow]")
+        result_data = {
+            "id": str(getattr(mcp, "id", "N/A")),
+            "name": getattr(mcp, "name", "N/A"),
+            "type": getattr(mcp, "type", "N/A"),
+            "config": getattr(mcp, "config", "N/A"),
+            "status": getattr(mcp, "status", "N/A"),
+            "connection_status": getattr(mcp, "connection_status", "N/A"),
+        }
+        output_result(
+            ctx, result_data, title="MCP Details", panel_title=f"🔌 {mcp.name}"
+        )
+
+
 @mcps_group.command()
 @click.argument("mcp_ref")
 @click.option(
     "--export",
     type=click.Path(dir_okay=False, writable=True),
-    help="Export complete MCP configuration to file (format auto-detected from .json/.yaml extension)",
+    help="Export complete MCP configuration to file "
+    "(format auto-detected from .json/.yaml extension)",
+)
+@click.option(
+    "--no-auth-prompt",
+    is_flag=True,
+    help="Skip interactive secret prompts and use placeholder values.",
+)
+@click.option(
+    "--auth-placeholder",
+    default="<INSERT VALUE>",
+    show_default=True,
+    help="Placeholder text used when secrets are unavailable.",
 )
 @output_flags()
 @click.pass_context
-def get(ctx: Any, mcp_ref: str, export: str | None) -> None:
-    """Get MCP details.
+def get(
+    ctx: Any,
+    mcp_ref: str,
+    export: str | None,
+    no_auth_prompt: bool,
+    auth_placeholder: str,
+) -> None:
+    """Get MCP details and optionally export configuration to file.
+
+    Args:
+        ctx: Click context containing output format preferences
+        mcp_ref: MCP reference (ID or name)
+        export: Optional file path to export MCP configuration
+        no_auth_prompt: Skip interactive secret prompts if True
+        auth_placeholder: Placeholder text for missing secrets
+
+    Raises:
+        ClickException: If MCP not found or export fails
 
     Examples:
         aip mcps get my-mcp
-        aip mcps get my-mcp --export mcp.json    # Exports complete configuration as JSON
-        aip mcps get my-mcp --export mcp.yaml    # Exports complete configuration as YAML
+        aip mcps get my-mcp --export mcp.json    # Export as JSON
+        aip mcps get my-mcp --export mcp.yaml    # Export as YAML
     """
     try:
         client = get_client(ctx)
@@ -188,83 +394,12 @@ def get(ctx: Any, mcp_ref: str, export: str | None) -> None:
 
         # Handle export option
         if export:
-            export_path = Path(export)
-            # Auto-detect format from file extension
-            detected_format = detect_export_format(export_path)
-
-            # Always export comprehensive data - re-fetch MCP with full details if needed
-            try:
-                with spinner_context(
-                    ctx,
-                    "[bold blue]Fetching complete MCP details…[/bold blue]",
-                    console_override=console,
-                ):
-                    mcp = client.mcps.get_mcp_by_id(mcp.id)
-            except Exception as e:
-                console.print(
-                    Text(f"[yellow]⚠️  Could not fetch full MCP details: {e}[/yellow]")
-                )
-                console.print(
-                    Text("[yellow]⚠️  Proceeding with available data[/yellow]")
-                )
-
-            with spinner_context(
-                ctx,
-                "[bold blue]Exporting MCP configuration…[/bold blue]",
-                console_override=console,
-            ):
-                export_resource_to_file(mcp, export_path, detected_format)
-            console.print(
-                Text(
-                    f"[green]✅ Complete MCP configuration exported to: {export_path} (format: {detected_format})[/green]"
-                )
+            _handle_mcp_export(
+                ctx, client, mcp, Path(export), no_auth_prompt, auth_placeholder
             )
 
-        # Try to fetch raw API data first to preserve ALL fields
-        with spinner_context(
-            ctx,
-            "[bold blue]Fetching detailed MCP data…[/bold blue]",
-            console_override=console,
-        ):
-            raw_mcp_data = fetch_raw_resource_details(client, mcp, "mcps")
-
-        if raw_mcp_data:
-            # Use raw API data - this preserves ALL fields
-            # Format dates for better display (minimal postprocessing)
-            formatted_data = raw_mcp_data.copy()
-            if "created_at" in formatted_data:
-                formatted_data["created_at"] = format_datetime(
-                    formatted_data["created_at"]
-                )
-            if "updated_at" in formatted_data:
-                formatted_data["updated_at"] = format_datetime(
-                    formatted_data["updated_at"]
-                )
-
-            # Display using output_result with raw data
-            output_result(
-                ctx,
-                formatted_data,
-                title="MCP Details",
-                panel_title=f"🔌 {raw_mcp_data.get('name', 'Unknown')}",
-            )
-        else:
-            # Fall back to original method if raw fetch fails
-            console.print("[yellow]Falling back to Pydantic model data[/yellow]")
-
-            # Create result data with actual available fields
-            result_data = {
-                "id": str(getattr(mcp, "id", "N/A")),
-                "name": getattr(mcp, "name", "N/A"),
-                "type": getattr(mcp, "type", "N/A"),
-                "config": getattr(mcp, "config", "N/A"),
-                "status": getattr(mcp, "status", "N/A"),
-                "connection_status": getattr(mcp, "connection_status", "N/A"),
-            }
-
-            output_result(
-                ctx, result_data, title="MCP Details", panel_title=f"🔌 {mcp.name}"
-            )
+        # Display MCP details
+        _display_mcp_details(ctx, client, mcp)
 
     except Exception as e:
         raise click.ClickException(str(e))
@@ -275,7 +410,15 @@ def get(ctx: Any, mcp_ref: str, export: str | None) -> None:
 @output_flags()
 @click.pass_context
 def list_tools(ctx: Any, mcp_ref: str) -> None:
-    """List tools from MCP."""
+    """List tools available from a specific MCP.
+
+    Args:
+        ctx: Click context containing output format preferences
+        mcp_ref: MCP reference (ID or name)
+
+    Raises:
+        ClickException: If MCP not found or tools fetch fails
+    """
     try:
         client = get_client(ctx)
 
@@ -325,7 +468,19 @@ def list_tools(ctx: Any, mcp_ref: str) -> None:
 @output_flags()
 @click.pass_context
 def connect(ctx: Any, config_file: str) -> None:
-    """Connect to MCP using config file."""
+    """Test MCP connection using a configuration file.
+
+    Args:
+        ctx: Click context containing output format preferences
+        config_file: Path to MCP configuration JSON file
+
+    Raises:
+        ClickException: If config file invalid or connection test fails
+
+    Note:
+        Loads MCP configuration from JSON file and tests connectivity.
+        Displays success or failure with connection details.
+    """
     try:
         client = get_client(ctx)
 
@@ -337,7 +492,8 @@ def connect(ctx: Any, config_file: str) -> None:
         if view != "json":
             console.print(
                 Text(
-                    f"[yellow]Connecting to MCP with config from {config_file}...[/yellow]"
+                    f"[yellow]Connecting to MCP with config from "
+                    f"{config_file}...[/yellow]"
                 )
             )
 
@@ -379,7 +535,22 @@ def update(
     description: str | None,
     config: str | None,
 ) -> None:
-    """Update an existing MCP."""
+    """Update an existing MCP with new configuration values.
+
+    Args:
+        ctx: Click context containing output format preferences
+        mcp_ref: MCP reference (ID or name)
+        name: New MCP name (optional)
+        description: New description (optional)
+        config: New JSON configuration string (optional)
+
+    Raises:
+        ClickException: If MCP not found, JSON invalid, or no fields specified
+
+    Note:
+        At least one field must be specified for update.
+        Uses PUT for complete updates or PATCH for partial updates.
+    """
     try:
         client = get_client(ctx)
 
@@ -425,7 +596,20 @@ def update(
 @output_flags()
 @click.pass_context
 def delete(ctx: Any, mcp_ref: str, yes: bool) -> None:
-    """Delete an MCP."""
+    """Delete an MCP after confirmation.
+
+    Args:
+        ctx: Click context containing output format preferences
+        mcp_ref: MCP reference (ID or name)
+        yes: Skip confirmation prompt if True
+
+    Raises:
+        ClickException: If MCP not found or deletion fails
+
+    Note:
+        Requires confirmation unless --yes flag is provided.
+        Deletion is permanent and cannot be undone.
+    """
     try:
         client = get_client(ctx)
 

glaip_sdk/cli/main.py

@@ -24,6 +24,7 @@ from glaip_sdk.cli.commands.configure import (
 from glaip_sdk.cli.commands.mcps import mcps_group
 from glaip_sdk.cli.commands.models import models_group
 from glaip_sdk.cli.commands.tools import tools_group
+from glaip_sdk.cli.update_notifier import maybe_notify_update
 from glaip_sdk.cli.utils import spinner_context, update_spinner
 from glaip_sdk.config.constants import (
     DEFAULT_AGENT_RUN_TIMEOUT,
@@ -82,6 +83,13 @@ def main(
 
     ctx.obj["tty"] = not no_tty
 
+    if not ctx.resilient_parsing and ctx.obj["tty"]:
+        console = Console()
+        maybe_notify_update(
+            _SDK_VERSION,
+            console=console,
+        )
+
     if ctx.invoked_subcommand is None and not ctx.resilient_parsing:
         if _should_launch_slash(ctx) and SlashSession is not None:
             session = SlashSession(ctx)

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"]