glaip-sdk 0.6.15b2__py3-none-any.whl → 0.6.16__py3-none-any.whl

glaip_sdk/cli/update_notifier.py

@@ -0,0 +1,290 @@
+"""Utility helpers for checking and displaying SDK update notifications.
+
+Author:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+import importlib
+import logging
+import sys
+from collections.abc import Callable, Iterable, Iterator
+from contextlib import contextmanager
+from typing import Any, Literal
+
+import click
+import httpx
+from packaging.version import InvalidVersion, Version
+from rich import box
+from rich.console import Console
+
+from glaip_sdk.branding import (
+    ACCENT_STYLE,
+    ERROR_STYLE,
+    SUCCESS_STYLE,
+    WARNING_STYLE,
+)
+from glaip_sdk.cli.commands.update import update_command
+from glaip_sdk.cli.constants import UPDATE_CHECK_ENABLED
+from glaip_sdk.cli.hints import format_command_hint
+from glaip_sdk.cli.utils import command_hint
+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
+
+_LOGGER = logging.getLogger(__name__)
+
+
+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 _suppress_library_logging():
+            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 as exc:
+        _LOGGER.debug("Update check failed: %s", exc, exc_info=True)
+        return None
+    except ValueError as exc:
+        _LOGGER.debug("Invalid JSON while checking for updates: %s", exc, exc_info=True)
+        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."""
+    # Check module attribute first (for test overrides), then fall back to imported constant
+    module = sys.modules.get(__name__)
+    if module and hasattr(module, "UPDATE_CHECK_ENABLED"):
+        return getattr(module, "UPDATE_CHECK_ENABLED")
+    return UPDATE_CHECK_ENABLED
+
+
+def _build_update_panel(
+    current_version: str,
+    latest_version: str,
+    command_text: str,
+    *,
+    show_command_hint: bool,
+) -> AIPPanel:
+    """Create a Rich panel that prompts the user to update."""
+    command_markup = format_command_hint(command_text) or command_text
+    message = (
+        f"[{WARNING_STYLE}]✨ Update available![/] "
+        f"{current_version} → {latest_version}\n\n"
+        "See the latest release notes:\n"
+        f"https://pypi.org/project/glaip-sdk/{latest_version}/"
+    )
+    if show_command_hint:
+        message += f"\n\n[{ACCENT_STYLE}]Run[/] {command_markup} to install."
+    return AIPPanel(
+        message,
+        title=f"[{SUCCESS_STYLE}]AIP SDK Update[/]",
+        box=box.ROUNDED,
+        padding=(0, 3),
+        expand=False,
+    )
+
+
+def maybe_notify_update(
+    current_version: str,
+    *,
+    package_name: str = "glaip-sdk",
+    console: Console | None = None,
+    fetch_latest_version: FetchLatestVersion | None = None,
+    ctx: Any | None = None,
+    slash_command: str | None = None,
+    style: Literal["panel", "inline"] = "panel",
+) -> None:
+    """Check PyPI for a newer version and display a prompt if one exists."""
+    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
+
+    command_text = command_hint("update", slash_command=slash_command, ctx=ctx)
+    if command_text is None:
+        return
+
+    active_console = console or Console()
+    should_prompt = _should_prompt_for_action(active_console, ctx)
+
+    if style == "inline":
+        if should_prompt:
+            message = (
+                f"[{WARNING_STYLE}]✨ Update[/] "
+                f"{current_version} → {latest_version} "
+                "- choose Update now or Skip to continue."
+            )
+            active_console.print(message)
+            _handle_update_decision(active_console, ctx)
+            return
+
+        command_markup = format_command_hint(command_text) or command_text
+        active_console.print(f"[{WARNING_STYLE}]✨ Update[/] {current_version} → {latest_version} - {command_markup}")
+        return
+
+    panel = _build_update_panel(
+        current_version,
+        latest_version,
+        command_text,
+        show_command_hint=not should_prompt,
+    )
+    active_console.print(panel)
+    if should_prompt:
+        _handle_update_decision(active_console, ctx)
+
+
+def _handle_update_decision(console: Console, ctx: Any) -> None:
+    """Prompt the user to take action on the available update."""
+    choice = _prompt_update_decision(console)
+    if choice == "skip":
+        return
+
+    _run_update_command(console, ctx)
+
+
+def _should_prompt_for_action(console: Console, ctx: Any | None) -> bool:
+    """Return True when we can safely block for interactive input."""
+    if ctx is None or not hasattr(ctx, "invoke"):
+        return False
+
+    is_interactive = getattr(console, "is_interactive", False)
+    if not isinstance(is_interactive, bool) or not is_interactive:
+        return False
+
+    is_terminal = getattr(console, "is_terminal", False)
+    if not isinstance(is_terminal, bool) or not is_terminal:
+        return False
+
+    input_method = getattr(console, "input", None)
+    return callable(input_method)
+
+
+def _prompt_update_decision(console: Console) -> Literal["update", "skip"]:
+    """Ask the user to choose between updating now or skipping."""
+    console.print(
+        f"[{ACCENT_STYLE}]Select an option to continue:[/]\n"
+        f"  [{SUCCESS_STYLE}]1.[/] Update now\n"
+        f"  [{WARNING_STYLE}]2.[/] Skip\n"
+    )
+    console.print("[dim]Press Enter after typing your choice.[/]")
+
+    while True:
+        try:
+            response = console.input("Choice [1/2]: ").strip().lower()
+        except (KeyboardInterrupt, EOFError):
+            console.print(f"\n[{WARNING_STYLE}]Update skipped.[/]")
+            return "skip"
+
+        if response in {"1", "update", "u"}:
+            return "update"
+        if response in {"2", "skip", "s"}:
+            return "skip"
+
+        console.print(f"[{ERROR_STYLE}]Please enter 1 to update now or 2 to skip.[/]")
+
+
+def _run_update_command(console: Console, ctx: Any) -> None:
+    """Invoke the built-in update command and surface any errors."""
+    try:
+        ctx.invoke(update_command)
+    except click.ClickException as exc:
+        exc.show()
+        console.print(f"[{ERROR_STYLE}]Update command exited with an error.[/]")
+    except click.Abort:
+        console.print(f"[{WARNING_STYLE}]Update aborted by user.[/]")
+    except Exception as exc:  # pragma: no cover - defensive guard
+        console.print(f"[{ERROR_STYLE}]Unexpected error while running update: {exc}[/]")
+    else:
+        _refresh_installed_version(console, ctx)
+
+
+@contextmanager
+def _suppress_library_logging(
+    logger_names: Iterable[str] | None = None, *, level: int = logging.WARNING
+) -> Iterator[None]:
+    """Temporarily raise log level for selected libraries during update checks."""
+    names = tuple(logger_names) if logger_names is not None else ("httpx",)
+    captured: list[tuple[logging.Logger, int]] = []
+    try:
+        for name in names:
+            logger = logging.getLogger(name)
+            captured.append((logger, logger.level))
+            logger.setLevel(level)
+        yield
+    finally:
+        for logger, previous_level in captured:
+            logger.setLevel(previous_level)
+
+
+def _refresh_installed_version(console: Console, ctx: Any) -> None:
+    """Reload runtime metadata after an in-process upgrade."""
+    new_version: str | None = None
+    branding_module: Any | None = None
+
+    try:
+        version_module = importlib.reload(importlib.import_module("glaip_sdk._version"))
+        new_version = getattr(version_module, "__version__", None)
+    except Exception as exc:  # pragma: no cover - defensive guard
+        _LOGGER.debug("Failed to reload glaip_sdk._version: %s", exc, exc_info=True)
+
+    try:
+        branding_module = importlib.reload(importlib.import_module("glaip_sdk.branding"))
+        if new_version:
+            branding_module.SDK_VERSION = new_version
+    except Exception as exc:  # pragma: no cover - defensive guard
+        _LOGGER.debug("Failed to update branding metadata: %s", exc, exc_info=True)
+        branding_module = None
+
+    session = _get_slash_session(ctx)
+    if session and hasattr(session, "refresh_branding"):
+        try:
+            branding_cls = getattr(branding_module, "AIPBranding", None) if branding_module else None
+            session.refresh_branding(new_version, branding_cls=branding_cls)
+            return
+        except Exception as exc:  # pragma: no cover - defensive guard
+            _LOGGER.debug("Failed to refresh active slash session: %s", exc, exc_info=True)
+
+    if new_version:
+        console.print(f"[{SUCCESS_STYLE}]CLI now running glaip-sdk {new_version}.[/]")
+
+
+def _get_slash_session(ctx: Any) -> Any | None:
+    """Return active slash session from the Click context if present."""
+    ctx_obj = getattr(ctx, "obj", None)
+    if isinstance(ctx_obj, dict):
+        return ctx_obj.get("_slash_session")
+    return None
+
+
+__all__ = ["maybe_notify_update"]

glaip_sdk/cli/utils.py

@@ -0,0 +1,263 @@
+"""CLI utilities for glaip-sdk (facade for backward compatibility).
+
+This module is a backward-compatible facade that re-exports functions from
+glaip_sdk.cli.core.* modules. New code should import directly from the core modules.
+The facade is deprecated and will be removed after consumers migrate to core modules;
+see docs/specs/refactor/cli-core-modularization.md for the migration plan.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+    Putu Ravindra Wiguna (putu.r.wiguna@gdplabs.id)
+"""  # pylint: disable=duplicate-code
+
+from __future__ import annotations
+
+import threading
+import warnings
+
+# Re-export from core modules
+from glaip_sdk.cli.core.context import (
+    bind_slash_session_context,
+    get_client,
+    handle_best_effort_check,
+    restore_slash_session_context,
+)
+from glaip_sdk.cli.core.output import (
+    coerce_to_row,
+    detect_export_format,
+    fetch_resource_for_export,
+    format_datetime_fields,
+    format_size,
+    handle_ambiguous_resource,
+    handle_resource_export,
+    output_list,
+    output_result,
+    parse_json_line,
+    resolve_resource,
+    sdk_version,
+    # Private functions for backward compatibility (used in tests)
+    _build_table_group,
+    _build_yaml_renderable,
+    _coerce_result_payload,
+    _create_table,
+    _ensure_displayable,
+    _format_yaml_text,
+    _get_interface_order,
+    _handle_empty_items,
+    _handle_fallback_numeric_ambiguity,
+    _handle_fuzzy_pick_selection,
+    _handle_json_output,
+    _handle_json_view_ambiguity,
+    _handle_markdown_output,
+    _handle_plain_output,
+    _handle_questionary_ambiguity,
+    _handle_table_output,
+    _literal_str_representer,
+    _normalise_rows,
+    _normalize_interface_preference,
+    _print_selection_tip,
+    _render_markdown_list,
+    _render_markdown_output,
+    _render_plain_list,
+    _resolve_by_id,
+    _resolve_by_name_multiple_fuzzy,
+    _resolve_by_name_multiple_questionary,
+    _resolve_by_name_multiple_with_select,
+    _resource_tip_command,
+    _should_fallback_to_numeric_prompt,
+    _should_sort_rows,
+    _should_use_fuzzy_picker,
+    _try_fuzzy_pick,
+    _try_fuzzy_selection,
+    _try_interface_selection,
+    _try_questionary_selection,
+    _LiteralYamlDumper,
+)
+from glaip_sdk.cli.core.prompting import (
+    _FuzzyCompleter,  # Private class for backward compatibility (used in tests)
+    _fuzzy_pick_for_resources,
+    prompt_export_choice_questionary,
+    questionary_safe_ask,
+    # Private functions for backward compatibility (used in tests)
+    _asyncio_loop_running,
+    _basic_prompt,
+    _build_resource_labels,
+    _build_display_parts,
+    _build_primary_parts,
+    _build_unique_labels,
+    _calculate_consecutive_bonus,
+    _calculate_exact_match_bonus,
+    _calculate_length_bonus,
+    _check_fuzzy_pick_requirements,
+    _extract_display_fields,
+    _extract_fallback_values,
+    _extract_id_suffix,
+    _get_fallback_columns,
+    _fuzzy_pick,
+    _fuzzy_score,
+    _is_fuzzy_match,
+    _is_standard_field,
+    _load_questionary_module,
+    _make_questionary_choice,
+    _perform_fuzzy_search,
+    _prompt_with_auto_select,
+    _rank_labels,
+    _row_display,
+    _run_questionary_in_thread,
+    _strip_spaces_for_matching,
+)
+from glaip_sdk.cli.core.rendering import (
+    build_renderer,
+    spinner_context,
+    stop_spinner,
+    update_spinner,
+    with_client_and_spinner,
+    # Private functions for backward compatibility (used in tests)
+    _can_use_spinner,
+    _register_renderer_with_session,
+    _spinner_stop,
+    _spinner_update,
+    _stream_supports_tty,
+)
+
+# Re-export from other modules for backward compatibility
+from glaip_sdk.cli.context import get_ctx_value
+from glaip_sdk.cli.hints import command_hint
+from glaip_sdk.utils import is_uuid
+
+# Re-export module-level variables for backward compatibility
+# Note: console is re-exported from output.py since that's where _handle_table_output uses it
+from glaip_sdk.cli.core.output import console
+import logging
+
+logger = logging.getLogger("glaip_sdk.cli.utils")
+questionary = None  # type: ignore[assignment]
+
+_warn_lock = threading.Lock()
+_warned = False
+
+
+def _warn_once() -> None:
+    """Emit the deprecation warning once in a thread-safe way."""
+    global _warned
+    if _warned:
+        return
+    with _warn_lock:
+        if _warned:
+            return
+        warnings.warn(
+            "Importing from glaip_sdk.cli.utils is deprecated. Use glaip_sdk.cli.core.* modules instead.",
+            DeprecationWarning,
+            stacklevel=3,
+        )
+        _warned = True
+
+
+_warn_once()
+
+# Re-export everything for backward compatibility
+__all__ = [
+    # Context
+    "bind_slash_session_context",
+    "get_client",
+    "get_ctx_value",  # Re-exported from context module
+    "handle_best_effort_check",
+    "restore_slash_session_context",
+    # Prompting
+    "_FuzzyCompleter",  # Private class for backward compatibility (used in tests)
+    "_asyncio_loop_running",  # Private function for backward compatibility (used in tests)
+    "_basic_prompt",  # Private function for backward compatibility (used in tests)
+    "_build_display_parts",  # Private function for backward compatibility (used in tests)
+    "_build_primary_parts",  # Private function for backward compatibility (used in tests)
+    "_build_resource_labels",  # Private function for backward compatibility (used in tests)
+    "_build_unique_labels",  # Private function for backward compatibility (used in tests)
+    "_calculate_consecutive_bonus",  # Private function for backward compatibility (used in tests)
+    "_calculate_exact_match_bonus",  # Private function for backward compatibility (used in tests)
+    "_calculate_length_bonus",  # Private function for backward compatibility (used in tests)
+    "_check_fuzzy_pick_requirements",  # Private function for backward compatibility (used in tests)
+    "_extract_display_fields",  # Private function for backward compatibility (used in tests)
+    "_extract_fallback_values",  # Private function for backward compatibility (used in tests)
+    "_extract_id_suffix",  # Private function for backward compatibility (used in tests)
+    "_fuzzy_pick",  # Private function for backward compatibility (used in tests)
+    "_fuzzy_pick_for_resources",
+    "_fuzzy_score",  # Private function for backward compatibility (used in tests)
+    "_get_fallback_columns",  # Private function for backward compatibility (used in tests)
+    "_is_fuzzy_match",  # Private function for backward compatibility (used in tests)
+    "_is_standard_field",  # Private function for backward compatibility (used in tests)
+    "_load_questionary_module",  # Private function for backward compatibility (used in tests)
+    "_make_questionary_choice",  # Private function for backward compatibility (used in tests)
+    "_perform_fuzzy_search",  # Private function for backward compatibility (used in tests)
+    "_prompt_with_auto_select",  # Private function for backward compatibility (used in tests)
+    "_rank_labels",  # Private function for backward compatibility (used in tests)
+    "_row_display",  # Private function for backward compatibility (used in tests)
+    "_run_questionary_in_thread",  # Private function for backward compatibility (used in tests)
+    "_strip_spaces_for_matching",  # Private function for backward compatibility (used in tests)
+    "prompt_export_choice_questionary",
+    "questionary_safe_ask",
+    # Rendering
+    "_can_use_spinner",  # Private function for backward compatibility (used in tests)
+    "_register_renderer_with_session",  # Private function for backward compatibility (used in tests)
+    "_spinner_stop",  # Private function for backward compatibility (used in tests)
+    "_spinner_update",  # Private function for backward compatibility (used in tests)
+    "_stream_supports_tty",  # Private function for backward compatibility (used in tests)
+    "build_renderer",
+    "console",  # Module-level variable for backward compatibility
+    "logger",  # Module-level variable for backward compatibility
+    "questionary",  # Module-level variable for backward compatibility
+    "spinner_context",
+    "stop_spinner",
+    "update_spinner",
+    "with_client_and_spinner",
+    # Output
+    "_LiteralYamlDumper",  # Private class for backward compatibility (used in tests)
+    "_build_table_group",  # Private function for backward compatibility (used in tests)
+    "_build_yaml_renderable",  # Private function for backward compatibility (used in tests)
+    "_coerce_result_payload",  # Private function for backward compatibility (used in tests)
+    "_create_table",  # Private function for backward compatibility (used in tests)
+    "_ensure_displayable",  # Private function for backward compatibility (used in tests)
+    "_format_yaml_text",  # Private function for backward compatibility (used in tests)
+    "_get_interface_order",  # Private function for backward compatibility (used in tests)
+    "_handle_empty_items",  # Private function for backward compatibility (used in tests)
+    "_handle_fallback_numeric_ambiguity",  # Private function for backward compatibility (used in tests)
+    "_handle_fuzzy_pick_selection",  # Private function for backward compatibility (used in tests)
+    "_handle_json_output",  # Private function for backward compatibility (used in tests)
+    "_handle_json_view_ambiguity",  # Private function for backward compatibility (used in tests)
+    "_handle_markdown_output",  # Private function for backward compatibility (used in tests)
+    "_handle_plain_output",  # Private function for backward compatibility (used in tests)
+    "_handle_questionary_ambiguity",  # Private function for backward compatibility (used in tests)
+    "_handle_table_output",  # Private function for backward compatibility (used in tests)
+    "_literal_str_representer",  # Private function for backward compatibility (used in tests)
+    "_normalise_rows",  # Private function for backward compatibility (used in tests)
+    "_normalize_interface_preference",  # Private function for backward compatibility (used in tests)
+    "_print_selection_tip",  # Private function for backward compatibility (used in tests)
+    "_render_markdown_list",  # Private function for backward compatibility (used in tests)
+    "_render_markdown_output",  # Private function for backward compatibility (used in tests)
+    "_render_plain_list",  # Private function for backward compatibility (used in tests)
+    "_resolve_by_id",  # Private function for backward compatibility (used in tests)
+    "_resolve_by_name_multiple_fuzzy",  # Private function for backward compatibility (used in tests)
+    "_resolve_by_name_multiple_questionary",  # Private function for backward compatibility (used in tests)
+    "_resolve_by_name_multiple_with_select",  # Private function for backward compatibility (used in tests)
+    "_resource_tip_command",  # Private function for backward compatibility (used in tests)
+    "_should_fallback_to_numeric_prompt",  # Private function for backward compatibility (used in tests)
+    "_should_sort_rows",  # Private function for backward compatibility (used in tests)
+    "_should_use_fuzzy_picker",  # Private function for backward compatibility (used in tests)
+    "_try_fuzzy_pick",  # Private function for backward compatibility (used in tests)
+    "_try_fuzzy_selection",  # Private function for backward compatibility (used in tests)
+    "_try_interface_selection",  # Private function for backward compatibility (used in tests)
+    "_try_questionary_selection",  # Private function for backward compatibility (used in tests)
+    "coerce_to_row",
+    "command_hint",  # Re-exported from hints module
+    "detect_export_format",
+    "fetch_resource_for_export",
+    "format_datetime_fields",
+    "format_size",
+    "handle_ambiguous_resource",
+    "handle_resource_export",
+    "output_list",
+    "output_result",
+    "parse_json_line",
+    "resolve_resource",
+    "sdk_version",
+    # Utils
+    "is_uuid",  # Re-exported from glaip_sdk.utils for backward compatibility
+]