glaip-sdk 0.1.3__py3-none-any.whl → 0.6.19__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

@@ -16,8 +16,8 @@ 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.cli.utils import command_hint, format_command_hint
 from glaip_sdk.icons import ICON_AGENT, ICON_TOOL
 from glaip_sdk.rich_components import AIPPanel
 
@@ -208,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"):
@@ -303,6 +304,7 @@ 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,
@@ -312,27 +314,41 @@ def display_agent_run_suggestions(agent: Any) -> Panel:
         slash_command=None,
     )
 
-    cli_section = ""
-    if run_hint_id and run_hint_name:
-        cli_section = (
-            "📋 Prefer the CLI instead?\n"
-            f"   {format_command_hint(run_hint_id) or run_hint_id}\n"
-            f"   {format_command_hint(run_hint_name) or run_hint_name}\n\n"
+    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"🚀 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"{cli_section}"
-        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]",
+        "".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,6 +7,7 @@ Authors:
     Raymond Christopher (raymond.christopher@gdplabs.id)
 """
 
+from importlib import import_module
 from pathlib import Path
 from typing import TYPE_CHECKING, Any
 
@@ -25,9 +26,11 @@ if TYPE_CHECKING:  # pragma: no cover - typing-only imports
 
 def _create_console() -> "Console":
     """Return a Console instance (lazy import for easier testing)."""
-    from rich.console import Console  # Local import for test patching
-
-    return Console()
+    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]: