glaip-sdk 0.0.14__py3-none-any.whl → 0.0.16__py3-none-any.whl

glaip_sdk/cli/pager.py

@@ -0,0 +1,272 @@
+"""Pager-related helpers for CLI output.
+
+Authors:
+    Putu Ravindra Wiguna (putu.r.wiguna@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+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
+
+__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:
+        from glaip_sdk.cli import utils as 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 with AIP_PAGER_WRAP=1 to drop -S.
+    Power users can override via AIP_LESS_FLAGS.
+
+    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:
+        want_wrap = os.getenv("AIP_PAGER_WRAP", "0") == "1"
+        base = "-R" if want_wrap else "-RS"
+        default_flags = base if clear_on_exit else (base + "FX")
+        os.environ["LESS"] = os.getenv("AIP_LESS_FLAGS", 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
+    """
+    v = (os.getenv("AIP_PAGER_HEADER", "1") or "1").strip().lower()
+    if v in {"0", "false", "off"}:
+        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_env = (os.getenv("AIP_PAGER", "auto") or "auto").lower()
+    if pager_env in ("0", "off", "false"):
+        return False
+    if pager_env 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/json_input.py

@@ -17,7 +17,7 @@ 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.
+    r"""Format a file-related error message with path context.
 
     Args:
         prefix: Main error message
@@ -31,7 +31,7 @@ def _format_file_error(
     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'
+        'File not found: config.json\nResolved path: /abs/config.json'
     """
     parts = [f"{prefix}: {file_path_str}", f"Resolved path: {resolved_path}"]
     if detail:

glaip_sdk/cli/resolution.py

@@ -32,20 +32,22 @@ def resolve_resource_reference(
     This is a common pattern used across all resource types.
 
     Args:
-        ctx: Click context
-        client: API client
-        reference: Resource ID or name
-        resource_type: Type of resource
-        get_by_id_func: Function to get resource by ID
-        find_by_name_func: Function to find resources by name
-        label: Label for error messages
-        select: Selection index for ambiguous matches
+        ctx: Click context for CLI operations.
+        _client: API client instance for backend operations.
+        reference: Resource ID or name to resolve.
+        resource_type: Type of resource being resolved.
+        get_by_id_func: Function to get resource by ID.
+        find_by_name_func: Function to find resources by name.
+        label: Label for error messages and user feedback.
+        select: Selection index for ambiguous matches in non-interactive mode.
+        interface_preference: Interface preference for user interaction ("fuzzy" or "questionary").
+        spinner_message: Custom message to show during resolution process.
 
     Returns:
-        Resolved resource object
+        Resolved resource object or None if not found.
 
     Raises:
-        click.ClickException: If resolution fails
+        click.ClickException: If resolution fails.
     """
     try:
         message = (

glaip_sdk/cli/slash/agent_session.py

@@ -22,6 +22,12 @@ class AgentRunSession:
     """Per-agent execution context for the command palette."""
 
     def __init__(self, session: SlashSession, agent: Any) -> None:
+        """Initialize the agent run session.
+
+        Args:
+            session: The slash session context
+            agent: The agent to interact with
+        """
         self.session = session
         self.agent = agent
         self.console = session.console
@@ -39,6 +45,7 @@ class AgentRunSession:
         }
 
     def run(self) -> None:
+        """Run the interactive agent session loop."""
         self.session.set_contextual_commands(
             self._contextual_completion_help, include_global=False
         )

glaip_sdk/cli/slash/prompt.py

@@ -46,6 +46,11 @@ if _HAS_PROMPT_TOOLKIT:
         """Provide slash command completions inside the prompt."""
 
         def __init__(self, session: SlashSession) -> None:
+            """Initialize the slash completer.
+
+            Args:
+                session: The slash session context
+            """
             self._session = session
 
         def get_completions(
@@ -53,6 +58,15 @@ if _HAS_PROMPT_TOOLKIT:
             document: Any,
             _complete_event: Any,  # type: ignore[no-any-return]
         ) -> Iterable[Completion]:  # pragma: no cover - UI
+            """Get completions for slash commands.
+
+            Args:
+                document: The document being edited
+                _complete_event: The completion event
+
+            Yields:
+                Completion objects for matching commands
+            """
             if Completion is None:
                 return
 
@@ -66,7 +80,14 @@ if _HAS_PROMPT_TOOLKIT:
 else:  # pragma: no cover - fallback when prompt_toolkit is missing
 
     class SlashCompleter:  # type: ignore[too-many-ancestors]
+        """Fallback slash completer when prompt_toolkit is not available."""
+
         def __init__(self, session: SlashSession) -> None:  # noqa: D401 - stub
+            """Initialize the fallback slash completer.
+
+            Args:
+                session: The slash session context
+            """
             self._session = session
 
 
@@ -76,7 +97,6 @@ def setup_prompt_toolkit(
     interactive: bool,
 ) -> tuple[Any | None, Any | None]:
     """Configure prompt_toolkit session and style for interactive mode."""
-
     if not (interactive and _HAS_PROMPT_TOOLKIT):
         return None, None
 
@@ -105,7 +125,6 @@ def setup_prompt_toolkit(
 
 def _create_key_bindings(session: SlashSession) -> Any:
     """Create prompt_toolkit key bindings for the command palette."""
-
     if KeyBindings is None:
         return None
 

glaip_sdk/cli/slash/session.py

@@ -19,7 +19,7 @@ from rich.table import Table
 
 from glaip_sdk.branding import AIPBranding
 from glaip_sdk.cli.commands.configure import configure_command, load_config
-from glaip_sdk.cli.utils import _fuzzy_pick_for_resources, get_client
+from glaip_sdk.cli.utils import _fuzzy_pick_for_resources, command_hint, get_client
 from glaip_sdk.rich_components import AIPPanel
 
 from .agent_session import AgentRunSession
@@ -49,6 +49,12 @@ class SlashSession:
     """Interactive command palette controller."""
 
     def __init__(self, ctx: click.Context, *, console: Console | None = None) -> None:
+        """Initialize the slash session.
+
+        Args:
+            ctx: The Click context
+            console: Optional console instance, creates default if None
+        """
         self.ctx = ctx
         self.console = console or Console()
         self._commands: dict[str, SlashCommand] = {}
@@ -90,7 +96,6 @@ class SlashSession:
 
     def run(self, initial_commands: Iterable[str] | None = None) -> None:
         """Start the command palette session loop."""
-
         if not self._interactive:
             self._run_non_interactive(initial_commands)
             return
@@ -153,7 +158,6 @@ class SlashSession:
 
     def _ensure_configuration(self) -> bool:
         """Ensure the CLI has both API URL and credentials before continuing."""
-
         while not self._configuration_ready():
             self.console.print(
                 "[yellow]Configuration required.[/] Launching `/login` wizard..."
@@ -173,7 +177,6 @@ class SlashSession:
 
     def _configuration_ready(self) -> bool:
         """Check whether API URL and credentials are available."""
-
         config = self._load_config()
         api_url = self._get_api_url(config)
         if not api_url:
@@ -188,7 +191,6 @@ class SlashSession:
 
     def handle_command(self, raw: str, *, invoked_from_agent: bool = False) -> bool:
         """Parse and execute a single slash command string."""
-
         verb, args = self._parse(raw)
         if not verb:
             self.console.print("[red]Unrecognised command[/red]")
@@ -308,9 +310,13 @@ class SlashSession:
             return True
 
         if not agents:
-            self.console.print(
-                "[yellow]No agents available. Use `aip agents create` to add one.[/yellow]"
-            )
+            hint = command_hint("agents create", slash_command=None, ctx=self.ctx)
+            if hint:
+                self.console.print(
+                    f"[yellow]No agents available. Use `{hint}` to add one.[/yellow]"
+                )
+            else:
+                self.console.print("[yellow]No agents available.[/yellow]")
             return True
 
         if args:
@@ -373,7 +379,7 @@ class SlashSession:
         self._register(
             SlashCommand(
                 name="login",
-                help="Run `aip configure` to set credentials.",
+                help="Run `/login` (alias `/configure`) to set credentials.",
                 handler=SlashSession._cmd_login,
                 aliases=("configure",),
             )
@@ -419,12 +425,10 @@ class SlashSession:
     @property
     def verbose_enabled(self) -> bool:
         """Return whether verbose agent runs are enabled."""
-
         return self._verbose_enabled
 
     def set_verbose(self, enabled: bool, *, announce: bool = True) -> None:
         """Enable or disable verbose mode with optional announcement."""
-
         if self._verbose_enabled == enabled:
             if announce:
                 self._print_verbose_status(context="already")
@@ -437,12 +441,10 @@ class SlashSession:
 
     def toggle_verbose(self, *, announce: bool = True) -> None:
         """Flip verbose mode state."""
-
         self.set_verbose(not self._verbose_enabled, announce=announce)
 
     def _cmd_verbose(self, args: list[str], _invoked_from_agent: bool) -> bool:
         """Slash handler for `/verbose` command."""
-
         if args:
             self.console.print(
                 "Usage: `/verbose` toggles verbose streaming output. Press Ctrl+T as a shortcut."
@@ -470,30 +472,25 @@ class SlashSession:
     # ------------------------------------------------------------------
     def register_active_renderer(self, renderer: Any) -> None:
         """Register the renderer currently streaming an agent run."""
-
         self._active_renderer = renderer
         self._sync_active_renderer()
 
     def clear_active_renderer(self, renderer: Any | None = None) -> None:
         """Clear the active renderer if it matches the provided instance."""
-
         if renderer is not None and renderer is not self._active_renderer:
             return
         self._active_renderer = None
 
     def notify_agent_run_started(self) -> None:
         """Mark that an agent run is in progress."""
-
         self.clear_active_renderer()
 
     def notify_agent_run_finished(self) -> None:
         """Mark that the active agent run has completed."""
-
         self.clear_active_renderer()
 
     def _sync_active_renderer(self) -> None:
         """Ensure the active renderer reflects the current verbose state."""
-
         renderer = self._active_renderer
         if renderer is None:
             return
@@ -622,18 +619,15 @@ class SlashSession:
         self, commands: dict[str, str] | None, *, include_global: bool = True
     ) -> None:
         """Set context-specific commands that should appear in completions."""
-
         self._contextual_commands = dict(commands or {})
         self._contextual_include_global = include_global if commands else True
 
     def get_contextual_commands(self) -> dict[str, str]:  # type: ignore[no-any-return]
         """Return a copy of the currently active contextual commands."""
-
         return dict(self._contextual_commands)
 
     def should_include_global_commands(self) -> bool:
         """Return whether global slash commands should appear in completions."""
-
         return self._contextual_include_global
 
     def _remember_agent(self, agent: Any) -> None:  # type: ignore[no-any-return]

glaip_sdk/cli/update_notifier.py

@@ -13,6 +13,7 @@ import httpx
 from packaging.version import InvalidVersion, Version
 from rich.console import Console
 
+from glaip_sdk.cli.utils import command_hint
 from glaip_sdk.rich_components import AIPPanel
 
 FetchLatestVersion = Callable[[], str | None]
@@ -59,6 +60,7 @@ def _should_check_for_updates() -> bool:
 def _build_update_panel(
     current_version: str,
     latest_version: str,
+    command_text: str,
 ) -> AIPPanel:
     """Create a Rich panel that prompts the user to update."""
     message = (
@@ -66,7 +68,7 @@ def _build_update_panel(
         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."
+        f"[cyan]Run[/cyan] [bold]{command_text}[/bold] to install."
     )
     return AIPPanel(
         message,
@@ -99,8 +101,12 @@ def maybe_notify_update(
     if current is None or latest is None or latest <= current:
         return
 
+    command_text = command_hint("update")
+    if command_text is None:
+        return
+
     active_console = console or Console()
-    panel = _build_update_panel(current_version, latest_version)
+    panel = _build_update_panel(current_version, latest_version, command_text)
     active_console.print(panel)