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

glaip_sdk/cli/utils.py

@@ -2,23 +2,17 @@
 
 Authors:
     Raymond Christopher (raymond.christopher@gdplabs.id)
+    Putu Ravindra Wiguna (putu.r.wiguna@gdplabs.id)
 """
 
 from __future__ import annotations
 
-import io
 import json
 import logging
 import os
-import platform
-import shlex
-import shutil
-import subprocess
 import sys
-import tempfile
 from collections.abc import Callable
 from contextlib import AbstractContextManager, nullcontext
-from pathlib import Path
 from typing import TYPE_CHECKING, Any
 
 import click
@@ -27,6 +21,8 @@ from rich.markdown import Markdown
 from rich.pretty import Pretty
 from rich.text import Text
 
+from glaip_sdk.rich_components import AIPPanel
+
 # Optional interactive deps (fuzzy palette)
 try:
     from prompt_toolkit.completion import Completion
@@ -43,8 +39,16 @@ except Exception:  # pragma: no cover - optional dependency
 
 if TYPE_CHECKING:  # pragma: no cover - import-only during type checking
     from glaip_sdk import Client
-from glaip_sdk.cli.commands.configure import load_config
-from glaip_sdk.rich_components import AIPPanel, AIPTable
+from glaip_sdk.cli import masking, pager
+from glaip_sdk.cli.config import load_config
+from glaip_sdk.cli.context import (
+    _get_view,
+    get_ctx_value,
+)
+from glaip_sdk.cli.context import (
+    detect_export_format as _detect_export_format,
+)
+from glaip_sdk.rich_components import AIPTable
 from glaip_sdk.utils import is_uuid
 from glaip_sdk.utils.rendering.renderer import (
     CapturingConsole,
@@ -53,180 +57,61 @@ from glaip_sdk.utils.rendering.renderer import (
 )
 
 console = Console()
+pager.console = console
 logger = logging.getLogger("glaip_sdk.cli.utils")
 
 
 # ----------------------------- Context helpers ---------------------------- #
 
 
-def get_ctx_value(ctx: Any, key: str, default: Any = None) -> Any:
-    """Safely resolve a value from click's context object."""
-    if ctx is None:
-        return default
-
-    obj = getattr(ctx, "obj", None)
-    if obj is None:
-        return default
-
-    if isinstance(obj, dict):
-        return obj.get(key, default)
-
-    getter = getattr(obj, "get", None)
-    if callable(getter):
-        try:
-            return getter(key, default)
-        except TypeError:
-            return default
-
-    return getattr(obj, key, default) if hasattr(obj, key) else default
-
-
-# ----------------------------- Pager helpers ----------------------------- #
-
-
-def _prepare_pager_env(
-    clear_on_exit: bool = True,
-) -> None:  # pragma: no cover - terminal UI setup
-    """
-    Configure LESS flags for a predictable, high-quality UX:
-      -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.
-    """
-    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'."""
-    buf = io.StringIO()
-    tmp_console = Console(
-        file=buf,
-        force_terminal=True,
-        color_system=console.color_system or "auto",
-        width=console.size.width or 100,
-        legacy_windows=False,
-        soft_wrap=False,
-        record=False,
-    )
-    tmp_console.print(renderable)
-    return buf.getvalue()
-
-
-def _pager_header() -> str:
-    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."""
-    if not (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."""
-    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 detect_export_format(file_path: str | os.PathLike[str]) -> str:
+    """Backward-compatible proxy to `glaip_sdk.cli.context.detect_export_format`."""
+    return _detect_export_format(file_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."""
-    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."""
-    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."""
-    _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:
-        # If pager fails, return False to indicate paging was not successful
-        return False
-    finally:
+def in_slash_mode(ctx: click.Context | None = None) -> bool:
+    """Return True when running inside the slash command palette."""
+    if ctx is None:
         try:
-            os.unlink(tmp_path)
-        except Exception:
-            pass
+            ctx = click.get_current_context(silent=True)
+        except RuntimeError:
+            ctx = None
 
-
-def _page_with_system_pager(
-    ansi_text: str,
-) -> bool:  # pragma: no cover - spawns real pager
-    """Prefer 'less' with a temp file so stdin remains the TTY."""
-    if not _should_use_pager():
+    if ctx is None:
         return False
 
-    pager_cmd, less_path = _resolve_pager_command()
+    obj = getattr(ctx, "obj", None)
+    if isinstance(obj, dict):
+        return bool(obj.get("_slash_session"))
 
-    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
-        )
+    return bool(getattr(obj, "_slash_session", False))
 
-    # Windows 'more' is poor with ANSI; let Rich fallback handle it
-    if platform.system().lower().startswith("win"):
-        return False
 
-    # POSIX 'more' fallback (may or may not honor ANSI)
-    return _run_pager_with_temp_file(_run_more_pager, ansi_text)
+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.
 
+    Args:
+        cli_command: Command string without the ``aip`` prefix (e.g., ``"status"``).
+        slash_command: Slash command counterpart (e.g., ``"status"`` or ``"/status"``).
+        ctx: Optional Click context override.
 
-def _get_view(ctx: Any) -> str:
-    view = get_ctx_value(ctx, "view")
-    if view:
-        return view
+    Returns:
+        The formatted command string for the active mode, or ``None`` when no
+        equivalent command exists in that mode.
+    """
+    if in_slash_mode(ctx):
+        if not slash_command:
+            return None
+        return slash_command if slash_command.startswith("/") else f"/{slash_command}"
 
-    fallback = get_ctx_value(ctx, "format")
-    return fallback or "rich"
+    if not cli_command:
+        return None
+    return f"aip {cli_command}"
 
 
 def spinner_context(
@@ -238,7 +123,6 @@ def spinner_context(
     spinner_style: str = "cyan",
 ) -> 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()
@@ -252,7 +136,6 @@ def spinner_context(
 
 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()
@@ -267,7 +150,6 @@ def _can_use_spinner(ctx: Any | None, active_console: Console) -> bool:
 
 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())
@@ -277,7 +159,6 @@ def _stream_supports_tty(stream: Any) -> bool:
 
 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
 
@@ -289,7 +170,6 @@ def update_spinner(status_indicator: Any | None, message: str) -> None:
 
 def stop_spinner(status_indicator: Any | None) -> None:
     """Stop an active spinner safely."""
-
     if status_indicator is None:
         return
 
@@ -336,9 +216,12 @@ def get_client(ctx: Any) -> Client:  # pragma: no cover
     }
 
     if not config.get("api_url") or not config.get("api_key"):
-        raise click.ClickException(
-            "Missing api_url/api_key. Run `aip configure` or set AIP_* env vars."
-        )
+        configure_hint = command_hint("configure", slash_command="login", ctx=ctx)
+        actions = []
+        if configure_hint:
+            actions.append(f"Run `{configure_hint}`")
+        actions.append("set AIP_* env vars")
+        raise click.ClickException(f"Missing api_url/api_key. {' or '.join(actions)}.")
 
     return Client(
         api_url=config.get("api_url"),
@@ -349,61 +232,6 @@ def get_client(ctx: Any) -> Client:  # pragma: no cover
 
 # ----------------------------- Secret masking ---------------------------- #
 
-_DEFAULT_MASK_FIELDS = {
-    "api_key",
-    "apikey",
-    "token",
-    "access_token",
-    "secret",
-    "client_secret",
-    "password",
-    "private_key",
-    "bearer",
-}
-
-
-def _mask_value(v: Any) -> str:
-    s = str(v)
-    if len(s) <= 8:
-        return "••••"
-    return f"{s[:4]}••••••••{s[-4:]}"
-
-
-def _mask_any(value: Any, mask_fields: set[str]) -> Any:
-    """Recursively mask sensitive fields in mappings / lists."""
-
-    if isinstance(value, dict):
-        masked: dict[Any, Any] = {}
-        for key, raw in value.items():
-            if isinstance(key, str) and key.lower() in mask_fields and raw is not None:
-                masked[key] = _mask_value(raw)
-            else:
-                masked[key] = _mask_any(raw, mask_fields)
-        return masked
-
-    if isinstance(value, list):
-        return [_mask_any(item, mask_fields) for item in value]
-
-    return value
-
-
-def _maybe_mask_row(row: dict[str, Any], mask_fields: set[str]) -> dict[str, Any]:
-    """Mask a single row (legacy function, now uses _mask_any)."""
-    if not mask_fields:
-        return row
-    return _mask_any(row, mask_fields)
-
-
-def _resolve_mask_fields() -> set[str]:
-    if os.getenv("AIP_MASK_OFF", "0") in ("1", "true", "on", "yes"):
-        return set()
-    env_fields = (os.getenv("AIP_MASK_FIELDS") or "").strip()
-    if env_fields:
-        parts = [p.strip().lower() for p in env_fields.split(",") if p.strip()]
-        return set(parts)
-    return set(_DEFAULT_MASK_FIELDS)
-
-
 # ----------------------------- Fuzzy palette ----------------------------- #
 
 
@@ -470,8 +298,8 @@ def _build_display_parts(
 
 
 def _row_display(row: dict[str, Any], columns: list[tuple]) -> str:
-    """
-    Build a compact text label for the palette.
+    """Build a compact text label for the palette.
+
     Prefers: name • type • framework • [id] (when available)
     Falls back to first 2 columns + [id].
     """
@@ -564,8 +392,8 @@ def _perform_fuzzy_search(
 def _fuzzy_pick(
     rows: list[dict[str, Any]], columns: list[tuple], title: str
 ) -> dict[str, Any] | None:  # pragma: no cover - requires interactive prompt toolkit
-    """
-    Open a minimal fuzzy palette using prompt_toolkit.
+    """Open a minimal fuzzy palette using prompt_toolkit.
+
     Returns the selected row (dict) or None if cancelled/missing deps.
     """
     if not _check_fuzzy_pick_requirements():
@@ -634,8 +462,8 @@ def _calculate_length_bonus(search: str, target: str) -> int:
 
 
 def _fuzzy_score(search: str, target: str) -> int:
-    """
-    Calculate fuzzy match score.
+    """Calculate fuzzy match score.
+
     Higher score = better match.
     Returns -1 if no match possible.
     """
@@ -667,16 +495,6 @@ def _coerce_result_payload(result: Any) -> Any:
     return result
 
 
-def _apply_mask_if_configured(payload: Any) -> Any:
-    mask_fields = _resolve_mask_fields()
-    if not mask_fields:
-        return payload
-    try:
-        return _mask_any(payload, mask_fields)
-    except Exception:
-        return payload
-
-
 def _ensure_displayable(payload: Any) -> Any:
     if isinstance(payload, dict | list | str | int | float | bool) or payload is None:
         return payload
@@ -708,12 +526,19 @@ def output_result(
     result: Any,
     title: str = "Result",
     panel_title: str | None = None,
-    success_message: str | None = None,
 ) -> None:
+    """Output a result to the console with optional title.
+
+    Args:
+        ctx: Click context
+        result: Result data to output
+        title: Optional title for the output
+        panel_title: Optional Rich panel title for structured output
+    """
     fmt = _get_view(ctx)
 
     data = _coerce_result_payload(result)
-    data = _apply_mask_if_configured(data)
+    data = masking.mask_payload(data)
     data = _ensure_displayable(data)
 
     if fmt == "json":
@@ -728,20 +553,12 @@ def output_result(
         _render_markdown_output(data)
         return
 
-    if success_message:
-        console.print(Text(f"[green]✅ {success_message}[/green]"))
-
+    renderable = Pretty(data)
     if panel_title:
-        console.print(
-            AIPPanel(
-                Pretty(data),
-                title=panel_title,
-                border_style="blue",
-            )
-        )
+        console.print(AIPPanel(renderable, title=panel_title))
     else:
         console.print(Text(f"[cyan]{title}:[/cyan]"))
-        console.print(Pretty(data))
+        console.print(renderable)
 
 
 # ----------------------------- List rendering ---------------------------- #
@@ -771,16 +588,6 @@ def _normalise_rows(
         return []
 
 
-def _mask_rows_if_configured(rows: list[dict[str, Any]]) -> list[dict[str, Any]]:
-    mask_fields = _resolve_mask_fields()
-    if not mask_fields:
-        return rows
-    try:
-        return [_maybe_mask_row(row, mask_fields) for row in rows]
-    except Exception:
-        return rows
-
-
 def _render_plain_list(
     rows: list[dict[str, Any]], title: str, columns: list[tuple]
 ) -> None:
@@ -832,20 +639,6 @@ def _build_table_group(
     return Group(table, footer)
 
 
-def _should_page_output(row_count: int, is_tty: bool) -> bool:
-    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 = 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
-
-
 def _handle_json_output(items: list[Any], rows: list[dict[str, Any]]) -> None:
     """Handle JSON output format."""
     data = (
@@ -877,7 +670,6 @@ def _handle_empty_items(title: str) -> None:
 
 def _should_use_fuzzy_picker() -> bool:
     """Return True when the interactive fuzzy picker can be shown."""
-
     return console.is_terminal and os.isatty(1)
 
 
@@ -885,7 +677,6 @@ def _try_fuzzy_pick(
     rows: list[dict[str, Any]], columns: list[tuple], title: str
 ) -> dict[str, Any] | None:
     """Best-effort fuzzy selection; returns None if the picker fails."""
-
     if not _should_use_fuzzy_picker():
         return None
 
@@ -896,36 +687,34 @@ def _try_fuzzy_pick(
         return None
 
 
-def _resource_tip_command(title: str) -> str:
+def _resource_tip_command(title: str) -> str | None:
     """Resolve the follow-up command hint for the given table title."""
-
     title_lower = title.lower()
     mapping = {
-        "agent": "aip agents get",
-        "tool": "aip tools get",
-        "mcp": "aip mcps get",
-        "model": "aip models list",  # models only ship a list command
+        "agent": ("agents get", "agents"),
+        "tool": ("tools get", None),
+        "mcp": ("mcps get", None),
+        "model": ("models list", None),  # models only ship a list command
     }
-    for keyword, command in mapping.items():
+    for keyword, (cli_command, slash_command) in mapping.items():
         if keyword in title_lower:
-            return command
-    return "aip agents get"
+            return command_hint(cli_command, slash_command=slash_command)
+    return command_hint("agents get", slash_command="agents")
 
 
 def _print_selection_tip(title: str) -> None:
     """Print the contextual follow-up tip after a fuzzy selection."""
-
     tip_cmd = _resource_tip_command(title)
-    console.print(
-        Text.from_markup(f"\n[dim]Tip: use `{tip_cmd} <ID>` for details[/dim]")
-    )
+    if tip_cmd:
+        console.print(
+            Text.from_markup(f"\n[dim]Tip: use `{tip_cmd} <ID>` for details[/dim]")
+        )
 
 
 def _handle_fuzzy_pick_selection(
     rows: list[dict[str, Any]], columns: list[tuple], title: str
 ) -> bool:
     """Handle fuzzy picker selection, returns True if selection was made."""
-
     picked = _try_fuzzy_pick(rows, columns, title)
     if picked is None:
         return False
@@ -947,14 +736,14 @@ def _handle_table_output(
     """Handle table output with paging."""
     content = _build_table_group(rows, columns, title)
     should_page = (
-        _should_page_output(len(rows), console.is_terminal and os.isatty(1))
+        pager._should_page_output(len(rows), console.is_terminal and os.isatty(1))
         if use_pager is None
         else use_pager
     )
 
     if should_page:
-        ansi = _render_ansi(content)
-        if not _page_with_system_pager(ansi):
+        ansi = pager._render_ansi(content)
+        if not pager._page_with_system_pager(ansi):
             with console.pager(styles=True):
                 console.print(content)
     else:
@@ -974,7 +763,7 @@ def output_list(
     """Display a list with optional fuzzy palette for quick selection."""
     fmt = _get_view(ctx)
     rows = _normalise_rows(items, transform_func)
-    rows = _mask_rows_if_configured(rows)
+    rows = masking.mask_rows(rows)
 
     if fmt == "json":
         _handle_json_output(items, rows)
@@ -1004,50 +793,6 @@ def output_list(
     _handle_table_output(rows, columns, title, use_pager=use_pager)
 
 
-# ------------------------- Output flags decorator ------------------------ #
-
-
-def _set_view(ctx: Any, _param: Any, value: str) -> None:
-    if not value:
-        return
-    ctx.ensure_object(dict)
-    ctx.obj["view"] = value
-
-
-def _set_json(ctx: Any, _param: Any, value: bool) -> None:
-    if not value:
-        return
-    ctx.ensure_object(dict)
-    ctx.obj["view"] = "json"
-
-
-def output_flags() -> Callable[[Callable[..., Any]], Callable[..., Any]]:
-    """Decorator to allow output format flags on any subcommand."""
-
-    def decorator(f: Callable[..., Any]) -> Callable[..., Any]:
-        f = click.option(
-            "--json",
-            "json_mode",
-            is_flag=True,
-            expose_value=False,
-            help="Shortcut for --view json",
-            callback=_set_json,
-        )(f)
-        f = click.option(
-            "-o",
-            "--output",
-            "--view",
-            "view_opt",
-            type=click.Choice(["rich", "plain", "json", "md"]),
-            expose_value=False,
-            help="Output format",
-            callback=_set_view,
-        )(f)
-        return f
-
-    return decorator
-
-
 # ------------------------- Ambiguity handling --------------------------- #
 
 
@@ -1084,14 +829,16 @@ def build_renderer(
     """Build renderer and capturing console for CLI commands.
 
     Args:
-        ctx: Click context
-        save_path: Path to save output to (enables capturing)
-        theme: Color theme ("dark" or "light")
-        verbose: Whether to enable verbose mode
-        tty_enabled: Whether TTY is available
+        _ctx: Click context object for CLI operations.
+        save_path: Path to save output to (enables capturing console).
+        theme: Color theme ("dark" or "light").
+        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)
+        Tuple of (renderer, capturing_console) for streaming output.
     """
     # Use capturing console if saving output
     working_console = console
@@ -1170,8 +917,7 @@ def _build_resource_labels(resources: list[Any]) -> tuple[list[str], dict[str, A
 def _fuzzy_pick_for_resources(
     resources: list[Any], resource_type: str, _search_term: str
 ) -> Any | None:  # pragma: no cover - interactive selection helper
-    """
-    Fuzzy picker for resource objects, similar to _fuzzy_pick but without column dependencies.
+    """Fuzzy picker for resource objects, similar to _fuzzy_pick but without column dependencies.
 
     Args:
         resources: List of resource objects to choose from
@@ -1400,19 +1146,3 @@ def handle_ambiguous_resource(
         else:
             # Re-raise cancellation exceptions
             raise
-
-
-def detect_export_format(file_path: str | Path) -> str:
-    """Detect export format from file extension.
-
-    Args:
-        file_path: Path to the export file
-
-    Returns:
-        "yaml" if file extension is .yaml or .yml, "json" otherwise
-    """
-    path = Path(file_path)
-    if path.suffix.lower() in [".yaml", ".yml"]:
-        return "yaml"
-    else:
-        return "json"