glaip-sdk 0.0.7__py3-none-any.whl → 0.6.5b6__py3-none-any.whl

glaip_sdk/cli/core/rendering.py

@@ -0,0 +1,187 @@
+"""CLI rendering utilities: Rich console helpers, viewer launchers, renderer builders.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+    Putu Ravindra Wiguna (putu.r.wiguna@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from contextlib import AbstractContextManager, contextmanager, nullcontext
+from typing import Any
+
+from rich.console import Console
+
+from glaip_sdk.branding import ACCENT_STYLE
+from glaip_sdk.cli.context import _get_view, get_ctx_value
+from glaip_sdk.utils.rendering.renderer import (
+    CapturingConsole,
+    RendererFactoryOptions,
+    RichStreamRenderer,
+    make_default_renderer,
+    make_verbose_renderer,
+)
+
+# Export console for backward compatibility
+console = Console()
+
+
+def _can_use_spinner(ctx: Any | None, active_console: Console) -> bool:
+    """Check if spinner output is allowed in the current environment."""
+    if ctx is not None:
+        tty_enabled = bool(get_ctx_value(ctx, "tty", True))
+        view = (_get_view(ctx) or "rich").lower()
+        if not tty_enabled or view not in {"", "rich"}:
+            return False
+
+    if not active_console.is_terminal:
+        return False
+
+    return _stream_supports_tty(getattr(active_console, "file", None))
+
+
+def _stream_supports_tty(stream: Any) -> bool:
+    """Return True if the provided stream can safely render a spinner."""
+    target = stream if hasattr(stream, "isatty") else sys.stdout
+    try:
+        return bool(target.isatty())
+    except Exception:
+        return False
+
+
+def update_spinner(status_indicator: Any | None, message: str) -> None:
+    """Update spinner text when a status indicator is active."""
+    if status_indicator is None:
+        return
+
+    try:
+        status_indicator.update(message)
+    except Exception:  # pragma: no cover - defensive update
+        pass
+
+
+def stop_spinner(status_indicator: Any | None) -> None:
+    """Stop an active spinner safely."""
+    if status_indicator is None:
+        return
+
+    try:
+        status_indicator.stop()
+    except Exception:  # pragma: no cover - defensive stop
+        pass
+
+
+# Backwards compatibility aliases for legacy callers
+_spinner_update = update_spinner
+_spinner_stop = stop_spinner
+
+
+def spinner_context(
+    ctx: Any | None,
+    message: str,
+    *,
+    console_override: Console | None = None,
+    spinner: str = "dots",
+    spinner_style: str = ACCENT_STYLE,
+) -> AbstractContextManager[Any]:
+    """Return a context manager that renders a spinner when appropriate."""
+    active_console = console_override or console
+    if not _can_use_spinner(ctx, active_console):
+        return nullcontext()
+
+    status = active_console.status(
+        message,
+        spinner=spinner,
+        spinner_style=spinner_style,
+    )
+
+    if not hasattr(status, "__enter__") or not hasattr(status, "__exit__"):
+        return nullcontext()
+
+    return status
+
+
+def _register_renderer_with_session(ctx: Any, renderer: RichStreamRenderer) -> None:
+    """Attach renderer to an active slash session when present."""
+    try:
+        ctx_obj = getattr(ctx, "obj", None)
+        session = ctx_obj.get("_slash_session") if isinstance(ctx_obj, dict) else None
+        if session and hasattr(session, "register_active_renderer"):
+            session.register_active_renderer(renderer)
+    except Exception:
+        # Never let session bookkeeping break renderer creation
+        pass
+
+
+def build_renderer(
+    _ctx: Any,
+    *,
+    save_path: str | os.PathLike[str] | None,
+    verbose: bool = False,
+    _tty_enabled: bool = True,
+    live: bool | None = None,
+    snapshots: bool | None = None,
+) -> tuple[RichStreamRenderer, Console | CapturingConsole]:
+    """Build renderer and capturing console for CLI commands.
+
+    Args:
+        _ctx: Click context object for CLI operations.
+        save_path: Path to save output to (enables capturing console).
+        verbose: Whether to enable verbose mode.
+        _tty_enabled: Whether TTY is available for interactive features.
+        live: Whether to enable live rendering mode (overrides verbose default).
+        snapshots: Whether to capture and store snapshots.
+
+    Returns:
+        Tuple of (renderer, capturing_console) for streaming output.
+    """
+    # Use capturing console if saving output
+    working_console = CapturingConsole(console, capture=True) if save_path else console
+
+    # Configure renderer based on verbose mode and explicit overrides
+    live_enabled = bool(live) if live is not None else not verbose
+    cfg_overrides = {
+        "live": live_enabled,
+        "append_finished_snapshots": bool(snapshots) if snapshots is not None else False,
+    }
+    renderer_console = (
+        working_console.original_console if isinstance(working_console, CapturingConsole) else working_console
+    )
+    factory = make_verbose_renderer if verbose else make_default_renderer
+    factory_options = RendererFactoryOptions(
+        console=renderer_console,
+        cfg_overrides=cfg_overrides,
+        verbose=verbose if factory is make_default_renderer else None,
+    )
+    renderer = factory_options.build(factory)
+
+    # Link the renderer back to the slash session when running from the palette.
+    _register_renderer_with_session(_ctx, renderer)
+
+    return renderer, working_console
+
+
+@contextmanager
+def with_client_and_spinner(
+    ctx: Any,
+    spinner_message: str,
+    *,
+    console_override: Console | None = None,
+) -> Any:
+    """Context manager for commands that need client and spinner.
+
+    Args:
+        ctx: Click context.
+        spinner_message: Message to display in spinner.
+        console_override: Optional console override.
+
+    Yields:
+        Client instance.
+    """
+    from glaip_sdk.cli.core.context import get_client  # noqa: PLC0415
+
+    client = get_client(ctx)
+    with spinner_context(ctx, spinner_message, console_override=console_override):
+        yield client

glaip_sdk/cli/display.py

@@ -15,6 +15,10 @@ from rich.console import Console
 from rich.panel import Panel
 from rich.text import Text
 
+from glaip_sdk.branding import ERROR_STYLE, SUCCESS, SUCCESS_STYLE, WARNING_STYLE
+from glaip_sdk.cli.hints import command_hint, format_command_hint, in_slash_mode
+from glaip_sdk.cli.rich_helpers import markup_text
+from glaip_sdk.icons import ICON_AGENT, ICON_TOOL
 from glaip_sdk.rich_components import AIPPanel
 
 console = Console()
@@ -37,15 +41,13 @@ def display_creation_success(
     # Build additional fields display
     fields_display = ""
     if additional_fields:
-        fields_display = "\n" + "\n".join(
-            f"{key}: {value}" for key, value in additional_fields.items()
-        )
+        fields_display = "\n" + "\n".join(f"{key}: {value}" for key, value in additional_fields.items())
 
     return AIPPanel(
-        f"[green]✅ {resource_type} '{resource_name}' created successfully![/green]\n\n"
+        f"[{SUCCESS_STYLE}]✅ {resource_type} '{resource_name}' created successfully![/]\n\n"
         f"ID: {resource_id}{fields_display}",
-        title=f"🤖 {resource_type} Created",
-        border_style="green",
+        title=f"{ICON_AGENT} {resource_type} Created",
+        border_style=SUCCESS,
         padding=(0, 1),
     )
 
@@ -60,9 +62,7 @@ def display_update_success(resource_type: str, resource_name: str) -> Text:
     Returns:
         Rich Text object for display
     """
-    return Text(
-        f"[green]✅ {resource_type} '{resource_name}' updated successfully[/green]"
-    )
+    return markup_text(f"[{SUCCESS_STYLE}]✅ {resource_type} '{resource_name}' updated successfully[/]")
 
 
 def display_deletion_success(resource_type: str, resource_name: str) -> Text:
@@ -75,9 +75,7 @@ def display_deletion_success(resource_type: str, resource_name: str) -> Text:
     Returns:
         Rich Text object for display
     """
-    return Text(
-        f"[green]✅ {resource_type} '{resource_name}' deleted successfully[/green]"
-    )
+    return markup_text(f"[{SUCCESS_STYLE}]✅ {resource_type} '{resource_name}' deleted successfully[/]")
 
 
 def display_api_error(error: Exception, operation: str = "operation") -> None:
@@ -88,8 +86,15 @@ def display_api_error(error: Exception, operation: str = "operation") -> None:
         operation: Description of the operation that failed
     """
     error_type = type(error).__name__
-    console.print(Text(f"[red]Error during {operation}: {error}[/red]"))
-    console.print(Text(f"[dim]Error type: {error_type}[/dim]"))
+    error_message = markup_text(f"[{ERROR_STYLE}]Error during {operation}: {error}[/]")
+    error_message.no_wrap = True
+    error_message.overflow = "ignore"
+    console.print(error_message)
+
+    error_type_message = markup_text(f"[dim]Error type: {error_type}[/dim]")
+    error_type_message.no_wrap = True
+    error_type_message.overflow = "ignore"
+    console.print(error_type_message)
 
 
 def print_api_error(e: Exception) -> None:
@@ -102,30 +107,85 @@ def print_api_error(e: Exception) -> None:
         - Extracts status_code, error_type, and payload from APIError exceptions
         - Provides consistent error reporting across CLI commands
         - Handles both JSON and Rich output formats
+        - Special handling for validation errors with detailed field-level errors
     """
-    if hasattr(e, "__dict__"):  # Check if it's an APIError-like object
-        error_info = {
-            "error": str(e),
-            "status_code": getattr(e, "status_code", None),
-            "error_type": getattr(e, "error_type", None),
-            "details": getattr(e, "payload", None),
-        }
-
-        # Filter out None values
-        error_info = {k: v for k, v in error_info.items() if v is not None}
-
-        # For JSON view, just return the structured error
-        # (CLI commands handle the JSON formatting)
-        if hasattr(e, "status_code"):
-            console.print(f"[red]API Error: {e}[/red]")
-            if hasattr(e, "status_code"):
-                console.print(f"[yellow]Status: {e.status_code}[/yellow]")
-            if hasattr(e, "payload"):
-                console.print(f"[yellow]Details: {e.payload}[/yellow]")
+    if not hasattr(e, "__dict__"):
+        console.print(f"[{ERROR_STYLE}]Error: {e}[/]")
+        return
+
+    if not hasattr(e, "status_code"):
+        console.print(f"[{ERROR_STYLE}]Error: {e}[/]")
+        return
+
+    error_text = str(e).strip()
+    if not error_text:
+        error_text = "Unknown error"
+    if "\n" in error_text:
+        error_text = error_text.splitlines()[0]
+    console.print(f"[{ERROR_STYLE}]API Error: {error_text}[/]")
+    status_code = getattr(e, "status_code", None)
+    if status_code is not None:
+        console.print(f"[{WARNING_STYLE}]Status: {status_code}[/]")
+
+    payload = getattr(e, "payload", _MISSING)
+    if payload is _MISSING:
+        return
+
+    if payload:
+        if not _print_structured_payload(payload):
+            console.print(f"[{WARNING_STYLE}]Details: {payload}[/]")
+    else:
+        console.print(f"[{WARNING_STYLE}]Details: {payload}[/]")
+
+
+def _print_structured_payload(payload: Any) -> bool:
+    """Print structured payloads with enhanced formatting. Returns True if handled."""
+    if not isinstance(payload, dict):
+        return False
+
+    if "detail" in payload and _print_validation_details(payload["detail"]):
+        return True
+
+    if "details" in payload and _print_details_field(payload["details"]):
+        return True
+
+    return False
+
+
+def _print_validation_details(detail: Any) -> bool:
+    """Render FastAPI-style validation errors."""
+    if not isinstance(detail, list) or not detail:
+        return False
+
+    console.print(f"[{ERROR_STYLE}]Validation Errors:[/]")
+    for error in detail:
+        if isinstance(error, dict):
+            loc = " -> ".join(str(x) for x in error.get("loc", []))
+            msg = error.get("msg", "Unknown error")
+            error_type = error.get("type", "unknown")
+            location = loc if loc else "field"
+            console.print(f"  [{WARNING_STYLE}]• {location}:[/] {msg}")
+            if error_type != "unknown":
+                console.print(f"    [dim]({error_type})[/dim]")
         else:
-            console.print(f"[red]Error: {e}[/red]")
+            console.print(f"  [{WARNING_STYLE}]•[/] {error}")
+    return True
+
+
+def _print_details_field(details: Any) -> bool:
+    """Render custom error details from API payloads."""
+    if not details:
+        return False
+
+    console.print(f"[{ERROR_STYLE}]Error Details:[/]")
+    if isinstance(details, str):
+        console.print(f"  [{WARNING_STYLE}]•[/] {details}")
+    elif isinstance(details, list):
+        for detail in details:
+            console.print(f"  [{WARNING_STYLE}]•[/] {detail}")
     else:
-        console.print(f"[red]Error: {e}[/red]")
+        console.print(f"  [{WARNING_STYLE}]•[/] {details}")
+    return True
 
 
 _MISSING = object()
@@ -133,7 +193,6 @@ _MISSING = object()
 
 def build_resource_result_data(resource: Any, fields: list[str]) -> dict[str, Any]:
     """Return a normalized mapping of ``fields`` extracted from ``resource``."""
-
     result: dict[str, Any] = {}
     for field in fields:
         try:
@@ -149,6 +208,7 @@ def build_resource_result_data(resource: Any, fields: list[str]) -> dict[str, An
 
 
 def _normalise_field_value(field: str, value: Any) -> Any:
+    """Convert special sentinel values into display-friendly text."""
     if value is _MISSING:
         return "N/A"
     if hasattr(value, "_mock_name"):
@@ -233,9 +293,7 @@ def display_confirmation_prompt(resource_type: str, resource_name: str) -> bool:
     Returns:
         True if user confirms, False otherwise
     """
-    if not click.confirm(
-        f"Are you sure you want to delete {resource_type.lower()} '{resource_name}'?"
-    ):
+    if not click.confirm(f"Are you sure you want to delete {resource_type.lower()} '{resource_name}'?"):
         if console.is_terminal:
             console.print(Text("Deletion cancelled."))
         return False
@@ -244,22 +302,54 @@ def display_confirmation_prompt(resource_type: str, resource_name: str) -> bool:
 
 def display_agent_run_suggestions(agent: Any) -> Panel:
     """Return a panel with post-creation suggestions for an agent."""
+    agent_id = getattr(agent, "id", "")
+    agent_name = getattr(agent, "name", "")
+    slash_mode = in_slash_mode()
+    run_hint_id = command_hint(
+        f'agents run {agent_id} "Your message here"',
+        slash_command=None,
+    )
+    run_hint_name = command_hint(
+        f'agents run "{agent_name}" "Your message here"',
+        slash_command=None,
+    )
+
+    content_parts: list[str] = ["[bold blue]💡 Next Steps:[/bold blue]\n\n"]
+
+    if slash_mode:
+        slash_shortcuts = "\n".join(
+            f"   {format_command_hint(command, description) or command}"
+            for command, description in (
+                ("/details", "Show configuration (toggle preview)"),
+                ("/help", "Show command palette menu"),
+                ("/exit", "Return to the palette"),
+            )
+        )
+        content_parts.append(
+            f"🚀 Start chatting with [bold]{agent_name}[/bold] right here:\n"
+            f"   Type your message below and press Enter to run it immediately.\n\n"
+            f"{ICON_TOOL} Slash shortcuts:\n"
+            f"{slash_shortcuts}"
+        )
+    else:
+        cli_hint_lines = [format_command_hint(hint) or hint for hint in (run_hint_id, run_hint_name) if hint]
+        if cli_hint_lines:
+            joined_hints = "\n".join(f"   {hint}" for hint in cli_hint_lines)
+            content_parts.append(f"🚀 Run this agent from the CLI:\n{joined_hints}\n\n")
+        content_parts.append(
+            f"{ICON_TOOL} Available options:\n"
+            f"   [dim]--chat-history[/dim]  Include previous conversation\n"
+            f"   [dim]--file[/dim]          Attach files\n"
+            f"   [dim]--input[/dim]         Alternative input method\n"
+            f"   [dim]--timeout[/dim]       Set execution timeout\n"
+            f"   [dim]--save[/dim]          Save transcript to file\n"
+            f"   [dim]--verbose[/dim]       Show detailed execution\n\n"
+            f"💡 [dim]Input text can be positional OR use --input flag (both work!)[/dim]"
+        )
 
     return AIPPanel(
-        f"[bold blue]💡 Next Steps:[/bold blue]\n\n"
-        f"🚀 Run this agent:\n"
-        f'   [green]aip agents run {agent.id} "Your message here"[/green]\n\n'
-        f"📋 Or use the agent name:\n"
-        f'   [green]aip agents run "{agent.name}" "Your message here"[/green]\n\n'
-        f"🔧 Available options:\n"
-        f"   [dim]--chat-history[/dim]  Include previous conversation\n"
-        f"   [dim]--file[/dim]          Attach files\n"
-        f"   [dim]--input[/dim]         Alternative input method\n"
-        f"   [dim]--timeout[/dim]       Set execution timeout\n"
-        f"   [dim]--save[/dim]          Save transcript to file\n"
-        f"   [dim]--verbose[/dim]       Show detailed execution\n\n"
-        f"💡 [dim]Input text can be positional OR use --input flag (both work!)[/dim]",
-        title="🤖 Ready to Run Agent",
+        "".join(content_parts),
+        title=f"{ICON_AGENT} Ready to Run Agent",
         border_style="blue",
         padding=(0, 1),
     )

glaip_sdk/cli/hints.py

@@ -0,0 +1,57 @@
+"""Helpers for formatting CLI/slash command hints.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+import click
+
+from glaip_sdk.branding import HINT_COMMAND_STYLE, HINT_DESCRIPTION_COLOR
+
+
+def in_slash_mode(ctx: click.Context | None = None) -> bool:
+    """Return True when running inside the slash command palette."""
+    if ctx is None:
+        try:
+            ctx = click.get_current_context(silent=True)
+        except RuntimeError:
+            ctx = None
+
+    if ctx is None:
+        return False
+
+    obj = getattr(ctx, "obj", None)
+    if isinstance(obj, dict):
+        return bool(obj.get("_slash_session"))
+
+    return bool(getattr(obj, "_slash_session", False))
+
+
+def command_hint(
+    cli_command: str | None,
+    slash_command: str | None = None,
+    *,
+    ctx: click.Context | None = None,
+) -> str | None:
+    """Return the appropriate command string for the current mode."""
+    if in_slash_mode(ctx):
+        if not slash_command:
+            return None
+        return slash_command if slash_command.startswith("/") else f"/{slash_command}"
+
+    if not cli_command:
+        return None
+    return f"aip {cli_command}"
+
+
+def format_command_hint(command: str | None, description: str | None = None) -> str | None:
+    """Return a Rich markup string that highlights a command hint."""
+    if not command:
+        return None
+
+    highlighted = f"[{HINT_COMMAND_STYLE}]{command}[/]"
+    if description:
+        highlighted += f"  [{HINT_DESCRIPTION_COLOR}]{description}[/{HINT_DESCRIPTION_COLOR}]"
+    return highlighted

glaip_sdk/cli/io.py

@@ -7,21 +7,33 @@ Authors:
     Raymond Christopher (raymond.christopher@gdplabs.id)
 """
 
+from importlib import import_module
 from pathlib import Path
-from typing import Any
+from typing import TYPE_CHECKING, Any
 
 import click
 
+from glaip_sdk.branding import WARNING_STYLE
 from glaip_sdk.utils.serialization import (
     collect_attributes_for_export,
     load_resource_from_file,
     write_resource_export,
 )
 
+if TYPE_CHECKING:  # pragma: no cover - typing-only imports
+    from rich.console import Console
+
+
+def _create_console() -> "Console":
+    """Return a Console instance (lazy import for easier testing)."""
+    try:
+        console_module = import_module("rich.console")
+    except ImportError as exc:  # pragma: no cover - optional dependency missing
+        raise RuntimeError("Rich Console is not available") from exc
+    return console_module.Console()
 
-def load_resource_from_file_with_validation(
-    file_path: Path, resource_type: str
-) -> dict[str, Any]:
+
+def load_resource_from_file_with_validation(file_path: Path, resource_type: str) -> dict[str, Any]:
     """Load resource data from JSON or YAML file with CLI-friendly error handling.
 
     Args:
@@ -36,17 +48,15 @@ def load_resource_from_file_with_validation(
     """
     try:
         return load_resource_from_file(file_path)
-    except FileNotFoundError:
-        raise click.ClickException(f"File not found: {file_path}")
+    except FileNotFoundError as err:
+        raise click.ClickException(f"File not found: {file_path}") from err
     except ValueError as e:
-        raise click.ClickException(f"Invalid {resource_type.lower()} file format: {e}")
+        raise click.ClickException(f"Invalid {resource_type.lower()} file format: {e}") from e
     except Exception as e:
-        raise click.ClickException(f"Failed to load {resource_type.lower()} file: {e}")
+        raise click.ClickException(f"Failed to load {resource_type.lower()} file: {e}") from e
 
 
-def export_resource_to_file_with_validation(
-    resource: Any, file_path: Path, format: str = "json"
-) -> None:
+def export_resource_to_file_with_validation(resource: Any, file_path: Path, format: str = "json") -> None:
     """Export resource to file with CLI-friendly error handling.
 
     Args:
@@ -62,7 +72,7 @@ def export_resource_to_file_with_validation(
         export_data = collect_attributes_for_export(resource)
         write_resource_export(file_path, export_data, format)
     except Exception as e:
-        raise click.ClickException(f"Failed to export resource: {e}")
+        raise click.ClickException(f"Failed to export resource: {e}") from e
 
 
 def fetch_raw_resource_details(client: Any, resource: Any, resource_type: str) -> Any:
@@ -79,9 +89,7 @@ def fetch_raw_resource_details(client: Any, resource: Any, resource_type: str) -
     Notes:
         This is CLI-specific functionality for displaying comprehensive resource details.
     """
-    from rich.console import Console
-
-    console = Console()
+    console = _create_console()
 
     try:
         resource_id = str(getattr(resource, "id", "")).strip()
@@ -98,9 +106,7 @@ def fetch_raw_resource_details(client: Any, resource: Any, resource_type: str) -
                 # Direct response
                 return raw_response
     except Exception as e:
-        console.print(
-            f"[yellow]Failed to fetch raw {resource_type} details: {e}[/yellow]"
-        )
+        console.print(f"[{WARNING_STYLE}]Failed to fetch raw {resource_type} details: {e}[/]")
         # Fall back to regular method
         return None
     return None