glaip-sdk 0.0.5b1__py3-none-any.whl → 0.0.7__py3-none-any.whl

glaip_sdk/cli/utils.py

@@ -14,6 +14,8 @@ import shlex
 import shutil
 import subprocess
 import tempfile
+from collections.abc import Callable
+from pathlib import Path
 from typing import TYPE_CHECKING, Any
 
 import click
@@ -28,18 +30,16 @@ try:
     from prompt_toolkit.shortcuts import prompt
 
     _HAS_PTK = True
-except Exception:
+except Exception:  # pragma: no cover - optional dependency
     _HAS_PTK = False
 
 try:
     import questionary
-except Exception:
+except Exception:  # pragma: no cover - optional dependency
     questionary = None
 
-if TYPE_CHECKING:
+if TYPE_CHECKING:  # pragma: no cover - import-only during type checking
     from glaip_sdk import Client
-
-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.utils import is_uuid
@@ -52,6 +52,31 @@ from glaip_sdk.utils.rendering.renderer import (
 console = Console()
 
 
+# ----------------------------- 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 ----------------------------- #
 
 
@@ -75,8 +100,8 @@ def _prepare_pager_env(
 
 
 def _render_ansi(
-    renderable,
-) -> str:  # pragma: no cover - rendering requires real terminal
+    renderable: Any,
+) -> str:
     """Render a Rich renderable to an ANSI string suitable for piping to 'less'."""
     buf = io.StringIO()
     tmp_console = Console(
@@ -92,7 +117,7 @@ def _render_ansi(
     return buf.getvalue()
 
 
-def _pager_header() -> str:  # pragma: no cover - terminal UI helper
+def _pager_header() -> str:
     v = (os.getenv("AIP_PAGER_HEADER", "1") or "1").strip().lower()
     if v in {"0", "false", "off"}:
         return ""
@@ -105,15 +130,17 @@ def _pager_header() -> str:  # pragma: no cover - terminal UI helper
     )
 
 
-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."""
+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:
@@ -122,60 +149,92 @@ def _page_with_system_pager(
             pager_cmd = parts
 
     less_path = shutil.which("less")
-    if pager_cmd or less_path:
-        _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:
-            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)
-        finally:
-            try:
-                os.unlink(tmp_path)
-            except Exception:
-                pass
+    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."""
+    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:
+        try:
+            os.unlink(tmp_path)
+        except Exception:
+            pass
+
+
+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():
+        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
+        )
 
     # 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)
-    more_path = shutil.which("more")
-    if more_path:
-        with tempfile.NamedTemporaryFile("w", delete=False, encoding="utf-8") as tmp:
-            tmp.write(_pager_header())
-            tmp.write(ansi_text)
-            tmp_path = tmp.name
-        try:
-            subprocess.run([more_path, tmp_path], check=False)
-        finally:
-            try:
-                os.unlink(tmp_path)
-            except Exception:
-                pass
-        return True
+    return _run_pager_with_temp_file(_run_more_pager, ansi_text)
 
-    return False
 
+def _get_view(ctx: Any) -> str:
+    view = get_ctx_value(ctx, "view")
+    if view:
+        return view
 
-def _get_view(ctx) -> str:
-    obj = (ctx.obj or {}) if ctx is not None else {}
-    return obj.get("view") or obj.get("format") or "rich"
+    fallback = get_ctx_value(ctx, "format")
+    return fallback or "rich"
 
 
 # ----------------------------- Client config ----------------------------- #
 
 
-def get_client(ctx) -> Client:
+def get_client(ctx: Any) -> Client:  # pragma: no cover
     """Get configured client from context, env, and config file (ctx > env > file)."""
+    from glaip_sdk import Client
+
     file_config = load_config() or {}
-    context_config = (ctx.obj or {}) if ctx else {}
+    context_config_obj = getattr(ctx, "obj", None)
+    context_config = context_config_obj or {}
 
     raw_timeout = os.getenv("AIP_TIMEOUT", "0") or "0"
     try:
@@ -269,17 +328,17 @@ def _resolve_mask_fields() -> set[str]:
 # ----------------------------- Fuzzy palette ----------------------------- #
 
 
-def _row_display(row: dict[str, Any], columns: list[tuple]) -> str:
-    """
-    Build a compact text label for the palette.
-    Prefers: name • type • framework • [id] (when available)
-    Falls back to first 2 columns + [id].
-    """
+def _extract_display_fields(row: dict[str, Any]) -> tuple[str, str, str, str]:
+    """Extract display fields from row data."""
     name = str(row.get("name", "")).strip()
     _id = str(row.get("id", "")).strip()
     type_ = str(row.get("type", "")).strip()
     fw = str(row.get("framework", "")).strip()
+    return name, _id, type_, fw
 
+
+def _build_primary_parts(name: str, type_: str, fw: str) -> list[str]:
+    """Build primary display parts from name, type, and framework."""
     parts = []
     if name:
         parts.append(name)
@@ -287,18 +346,58 @@ def _row_display(row: dict[str, Any], columns: list[tuple]) -> str:
         parts.append(type_)
     if fw:
         parts.append(fw)
+    return parts
+
+
+def _get_fallback_columns(columns: list[tuple]) -> list[tuple]:
+    """Get first two visible columns for fallback display."""
+    return columns[:2]
+
+
+def _is_standard_field(k: str) -> bool:
+    """Check if field is a standard field to skip."""
+    return k in ("id", "name", "type", "framework")
+
+
+def _extract_fallback_values(row: dict[str, Any], columns: list[tuple]) -> list[str]:
+    """Extract fallback values from columns."""
+    fallback_parts = []
+    for k, _hdr, _style, _w in columns:
+        if _is_standard_field(k):
+            continue
+        val = str(row.get(k, "")).strip()
+        if val:
+            fallback_parts.append(val)
+        if len(fallback_parts) >= 2:
+            break
+    return fallback_parts
+
+
+def _build_display_parts(
+    name: str, _id: str, type_: str, fw: str, row: dict[str, Any], columns: list[tuple]
+) -> list[str]:
+    """Build complete display parts list."""
+    parts = _build_primary_parts(name, type_, fw)
+
     if not parts:
-        # use first two visible columns
-        for k, _hdr, _style, _w in columns[:2]:
-            if k in ("id", "name", "type", "framework"):
-                continue
-            val = str(row.get(k, "")).strip()
-            if val:
-                parts.append(val)
-            if len(parts) >= 2:
-                break
+        # Use fallback columns
+        fallback_columns = _get_fallback_columns(columns)
+        parts.extend(_extract_fallback_values(row, fallback_columns))
+
     if _id:
         parts.append(f"[{_id}]")
+
+    return parts
+
+
+def _row_display(row: dict[str, Any], columns: list[tuple]) -> str:
+    """
+    Build a compact text label for the palette.
+    Prefers: name • type • framework • [id] (when available)
+    Falls back to first 2 columns + [id].
+    """
+    name, _id, type_, fw = _extract_display_fields(row)
+    parts = _build_display_parts(name, _id, type_, fw, row, columns)
     return " • ".join(parts) if parts else (_id or "(row)")
 
 
@@ -332,10 +431,12 @@ def _build_unique_labels(
 class _FuzzyCompleter:
     """Fuzzy completer for prompt_toolkit."""
 
-    def __init__(self, words: list[str]):
+    def __init__(self, words: list[str]) -> None:
         self.words = words
 
-    def get_completions(self, document, _complete_event):
+    def get_completions(
+        self, document: Any, _complete_event: Any
+    ) -> Any:  # pragma: no cover
         word = document.get_word_before_cursor()
         if not word:
             return
@@ -346,7 +447,7 @@ class _FuzzyCompleter:
             if self._fuzzy_match(word_lower, label_lower):
                 yield Completion(label, start_position=-len(word))
 
-    def _fuzzy_match(self, search: str, target: str) -> bool:
+    def _fuzzy_match(self, search: str, target: str) -> bool:  # pragma: no cover
         """True fuzzy matching: checks if all characters in search appear in order in target."""
         if not search:
             return True
@@ -404,47 +505,37 @@ def _fuzzy_pick(
             complete_in_thread=True,
             complete_while_typing=True,
         )
-    except (KeyboardInterrupt, EOFError):
+    except (KeyboardInterrupt, EOFError):  # pragma: no cover - user cancelled input
         return None
 
     return _perform_fuzzy_search(answer, labels, by_label) if answer else None
 
 
-def _fuzzy_score(search: str, target: str) -> int:
-    """
-    Calculate fuzzy match score.
-    Higher score = better match.
-    Returns -1 if no match possible.
-    """
+def _is_fuzzy_match(search: str, target: str) -> bool:
+    """Check if search string is a fuzzy match for target."""
     if not search:
-        return 0
+        return True
 
-    # Check if it's a fuzzy match first
     search_idx = 0
     for char in target:
         if search_idx < len(search) and search[search_idx] == char:
             search_idx += 1
             if search_idx == len(search):
-                break
+                return True
+    return False
 
-    if search_idx < len(search):
-        return -1  # Not a fuzzy match
 
-    # Calculate score based on:
-    # 1. Exact substring match gets bonus points
-    # 2. Consecutive character matches get bonus points
-    # 3. Shorter search terms get bonus points
+def _calculate_exact_match_bonus(search: str, target: str) -> int:
+    """Calculate bonus for exact substring matches."""
+    return 100 if search.lower() in target.lower() else 0
 
-    score = 0
 
-    # Exact substring bonus
-    if search.lower() in target.lower():
-        score += 100
-
-    # Consecutive character bonus
+def _calculate_consecutive_bonus(search: str, target: str) -> int:
+    """Calculate bonus for consecutive character matches."""
     consecutive = 0
     max_consecutive = 0
     search_idx = 0
+
     for char in target:
         if search_idx < len(search) and search[search_idx] == char:
             consecutive += 1
@@ -453,10 +544,31 @@ def _fuzzy_score(search: str, target: str) -> int:
         else:
             consecutive = 0
 
-    score += max_consecutive * 10
+    return max_consecutive * 10
+
 
-    # Length bonus (shorter searches get higher scores)
-    score += (len(target) - len(search)) * 2
+def _calculate_length_bonus(search: str, target: str) -> int:
+    """Calculate bonus for shorter search terms."""
+    return (len(target) - len(search)) * 2
+
+
+def _fuzzy_score(search: str, target: str) -> int:
+    """
+    Calculate fuzzy match score.
+    Higher score = better match.
+    Returns -1 if no match possible.
+    """
+    if not search:
+        return 0
+
+    if not _is_fuzzy_match(search, target):
+        return -1  # Not a fuzzy match
+
+    # Calculate score based on different factors
+    score = 0
+    score += _calculate_exact_match_bonus(search, target)
+    score += _calculate_consecutive_bonus(search, target)
+    score += _calculate_length_bonus(search, target)
 
     return score
 
@@ -511,12 +623,12 @@ def _render_markdown_output(data: Any) -> None:
 
 
 def output_result(
-    ctx,
+    ctx: Any,
     result: Any,
     title: str = "Result",
     panel_title: str | None = None,
     success_message: str | None = None,
-):
+) -> None:
     fmt = _get_view(ctx)
 
     data = _coerce_result_payload(result)
@@ -557,7 +669,9 @@ def output_result(
 # _PICK_THRESHOLD = int(os.getenv("AIP_PICK_THRESHOLD", "5") or "5")
 
 
-def _normalise_rows(items: list[Any], transform_func) -> list[dict[str, Any]]:
+def _normalise_rows(
+    items: list[Any], transform_func: Callable[[Any], dict[str, Any]] | None
+) -> list[dict[str, Any]]:
     try:
         rows: list[dict[str, Any]] = []
         for item in items:
@@ -620,7 +734,7 @@ def _should_sort_rows(rows: list[dict[str, Any]]) -> bool:
     )
 
 
-def _create_table(columns: list[tuple], title: str):
+def _create_table(columns: list[tuple[str, str, str, int | None]], title: str) -> Any:
     table = AIPTable(title=title, expand=True)
     for _key, header, style, width in columns:
         table.add_column(header, style=style, width=width)
@@ -651,37 +765,93 @@ def _should_page_output(row_count: int, is_tty: bool) -> bool:
         return is_tty
 
 
+def _handle_json_output(items: list[Any], rows: list[dict[str, Any]]) -> None:
+    """Handle JSON output format."""
+    data = (
+        rows
+        if rows
+        else [it.to_dict() if hasattr(it, "to_dict") else it for it in items]
+    )
+    click.echo(json.dumps(data, indent=2, default=str))
+
+
+def _handle_plain_output(
+    rows: list[dict[str, Any]], title: str, columns: list[tuple]
+) -> None:
+    """Handle plain text output format."""
+    _render_plain_list(rows, title, columns)
+
+
+def _handle_markdown_output(
+    rows: list[dict[str, Any]], title: str, columns: list[tuple]
+) -> None:
+    """Handle markdown output format."""
+    _render_markdown_list(rows, title, columns)
+
+
+def _handle_empty_items(title: str) -> None:
+    """Handle case when no items are found."""
+    console.print(Text(f"[yellow]No {title.lower()} found.[/yellow]"))
+
+
+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 = (
+        _fuzzy_pick(rows, columns, title)
+        if console.is_terminal and os.isatty(1)
+        else None
+    )
+    if picked:
+        table = _create_table(columns, title)
+        table.add_row(*[str(picked.get(key, "N/A")) for key, _, _, _ in columns])
+        console.print(table)
+        console.print(Text("\n[dim]Tip: use `aip agents get <ID>` for details[/dim]"))
+        return True
+    return False
+
+
+def _handle_table_output(
+    rows: list[dict[str, Any]], columns: list[tuple], title: str
+) -> None:
+    """Handle table output with paging."""
+    content = _build_table_group(rows, columns, title)
+    if _should_page_output(len(rows), console.is_terminal and os.isatty(1)):
+        ansi = _render_ansi(content)
+        if not _page_with_system_pager(ansi):
+            with console.pager(styles=True):
+                console.print(content)
+    else:
+        console.print(content)
+
+
 def output_list(
-    ctx,
+    ctx: Any,
     items: list[Any],
     title: str,
-    columns: list[tuple],
-    transform_func=None,
-):
+    columns: list[tuple[str, str, str, int | None]],
+    transform_func: Callable | None = None,
+) -> None:
     """Display a list with fuzzy palette by default on TTY, Rich table as fallback."""
     fmt = _get_view(ctx)
     rows = _normalise_rows(items, transform_func)
     rows = _mask_rows_if_configured(rows)
 
     if fmt == "json":
-        data = (
-            rows
-            if rows
-            else [it.to_dict() if hasattr(it, "to_dict") else it for it in items]
-        )
-        click.echo(json.dumps(data, indent=2, default=str))
+        _handle_json_output(items, rows)
         return
 
     if fmt == "plain":
-        _render_plain_list(rows, title, columns)
+        _handle_plain_output(rows, title, columns)
         return
 
     if fmt == "md":
-        _render_markdown_list(rows, title, columns)
+        _handle_markdown_output(rows, title, columns)
         return
 
     if not items:
-        console.print(Text(f"[yellow]No {title.lower()} found.[/yellow]"))
+        _handle_empty_items(title)
         return
 
     if _should_sort_rows(rows):
@@ -690,50 +860,33 @@ def output_list(
         except Exception:
             pass
 
-    picked = (
-        _fuzzy_pick(rows, columns, title)
-        if console.is_terminal and os.isatty(1)
-        else None
-    )
-    if picked:
-        table = _create_table(columns, title)
-        table.add_row(*[str(picked.get(key, "N/A")) for key, _, _, _ in columns])
-        console.print(table)
-        console.print(Text("\n[dim]Tip: use `aip agents get <ID>` for details[/dim]"))
+    if _handle_fuzzy_pick_selection(rows, columns, title):
         return
 
-    content = _build_table_group(rows, columns, title)
-    if _should_page_output(len(rows), console.is_terminal and os.isatty(1)):
-        ansi = _render_ansi(content)
-        if not _page_with_system_pager(ansi):
-            with console.pager(styles=True):
-                console.print(content)
-        return
-
-    console.print(content)
+    _handle_table_output(rows, columns, title)
 
 
 # ------------------------- Output flags decorator ------------------------ #
 
 
-def _set_view(ctx, _param, value):
+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, _param, 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():
+def output_flags() -> Callable[[Callable[..., Any]], Callable[..., Any]]:
     """Decorator to allow output format flags on any subcommand."""
 
-    def decorator(f):
+    def decorator(f: Callable[..., Any]) -> Callable[..., Any]:
         f = click.option(
             "--json",
             "json_mode",
@@ -760,7 +913,7 @@ def output_flags():
 # ------------------------- Ambiguity handling --------------------------- #
 
 
-def coerce_to_row(item, keys: list[str]) -> dict[str, Any]:
+def coerce_to_row(item: Any, keys: list[str]) -> dict[str, Any]:
     """Coerce an item (dict or object) to a row dict with specified keys.
 
     Args:
@@ -781,15 +934,15 @@ def coerce_to_row(item, keys: list[str]) -> dict[str, Any]:
 
 
 def build_renderer(
-    _ctx,
+    _ctx: Any,
     *,
-    save_path,
-    theme="dark",
-    verbose=False,
-    _tty_enabled=True,
-    live=None,
-    snapshots=None,
-):
+    save_path: str | os.PathLike[str] | None,
+    theme: str = "dark",
+    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:
@@ -901,16 +1054,49 @@ def _fuzzy_pick_for_resources(
     return _perform_fuzzy_search(answer, labels, by_label) if answer else None
 
 
+def _resolve_by_id(ref: str, get_by_id: Callable) -> Any | None:
+    """Resolve resource by UUID if ref is a valid UUID."""
+    if is_uuid(ref):
+        return get_by_id(ref)
+    return None
+
+
+def _resolve_by_name_multiple_with_select(matches: list[Any], select: int) -> Any:
+    """Resolve multiple matches using select parameter."""
+    idx = int(select) - 1
+    if not (0 <= idx < len(matches)):
+        raise click.ClickException(f"--select must be 1..{len(matches)}")
+    return matches[idx]
+
+
+def _resolve_by_name_multiple_fuzzy(
+    ctx: Any, ref: str, matches: list[Any], label: str
+) -> Any:
+    """Resolve multiple matches using fuzzy picker interface."""
+    picked = _fuzzy_pick_for_resources(matches, label.lower(), ref)
+    if picked:
+        return picked
+    # Fallback to original ambiguity handler if fuzzy picker fails
+    return handle_ambiguous_resource(ctx, label.lower(), ref, matches)
+
+
+def _resolve_by_name_multiple_questionary(
+    ctx: Any, ref: str, matches: list[Any], label: str
+) -> Any:
+    """Resolve multiple matches using questionary interface."""
+    return handle_ambiguous_resource(ctx, label.lower(), ref, matches)
+
+
 def resolve_resource(
-    ctx,
+    ctx: Any,
     ref: str,
     *,
-    get_by_id,
-    find_by_name,
+    get_by_id: Callable,
+    find_by_name: Callable,
     label: str,
     select: int | None = None,
     interface_preference: str = "fuzzy",
-):
+) -> Any | None:
     """Resolve resource reference (ID or name) with ambiguity handling.
 
     Args:
@@ -925,8 +1111,14 @@ def resolve_resource(
     Returns:
         Resolved resource object
     """
+    # Try to resolve by ID first
+    result = _resolve_by_id(ref, get_by_id)
+    if result is not None:
+        return result
+
+    # If get_by_id returned None, the resource doesn't exist
     if is_uuid(ref):
-        return get_by_id(ref)
+        raise click.ClickException(f"{label} '{ref}' not found")
 
     # Find resources by name
     matches = find_by_name(name=ref)
@@ -936,59 +1128,66 @@ def resolve_resource(
     if len(matches) == 1:
         return matches[0]
 
-    # Multiple matches - handle ambiguity
+    # Multiple matches found, handle ambiguity
     if select:
-        idx = int(select) - 1
-        if not (0 <= idx < len(matches)):
-            raise click.ClickException(f"--select must be 1..{len(matches)}")
-        return matches[idx]
+        return _resolve_by_name_multiple_with_select(matches, select)
 
     # Choose interface based on preference
     if interface_preference == "fuzzy":
-        # Use fuzzy picker for modern UX
-        picked = _fuzzy_pick_for_resources(matches, label.lower(), ref)
-        if picked:
-            return picked
-        # Fallback to original ambiguity handler if fuzzy picker fails
-        return handle_ambiguous_resource(ctx, label.lower(), ref, matches)
+        return _resolve_by_name_multiple_fuzzy(ctx, ref, matches, label)
     else:
-        # Use questionary interface for traditional up/down selection
-        return handle_ambiguous_resource(ctx, label.lower(), ref, matches)
+        return _resolve_by_name_multiple_questionary(ctx, ref, matches, label)
 
 
-def handle_ambiguous_resource(
-    ctx, resource_type: str, ref: str, matches: list[Any]
+def _handle_json_view_ambiguity(matches: list[Any]) -> Any:
+    """Handle ambiguity in JSON view by returning first match."""
+    return matches[0]
+
+
+def _handle_questionary_ambiguity(
+    resource_type: str, ref: str, matches: list[Any]
 ) -> Any:
-    """Handle multiple resource matches gracefully."""
-    if _get_view(ctx) == "json":
-        return matches[0]
+    """Handle ambiguity using questionary interactive interface."""
+    if not (questionary and os.getenv("TERM") and os.isatty(0) and os.isatty(1)):
+        raise click.ClickException("Interactive selection not available")
+
+    # Escape special characters for questionary
+    safe_resource_type = resource_type.replace("{", "{{").replace("}", "}}")
+    safe_ref = ref.replace("{", "{{").replace("}", "}}")
+
+    picked_idx = questionary.select(
+        f"Multiple {safe_resource_type}s match '{safe_ref}'. Pick one:",
+        choices=[
+            questionary.Choice(
+                title=f"{getattr(m, 'name', '—').replace('{', '{{').replace('}', '}}')} — {getattr(m, 'id', '').replace('{', '{{').replace('}', '}}')}",
+                value=i,
+            )
+            for i, m in enumerate(matches)
+        ],
+        use_indicator=True,
+        qmark="🧭",
+        instruction="↑/↓ to select • Enter to confirm",
+    ).ask()
+    if picked_idx is None:
+        raise click.ClickException("Selection cancelled")
+    return matches[picked_idx]
+
+
+def _handle_fallback_numeric_ambiguity(
+    resource_type: str, ref: str, matches: list[Any]
+) -> Any:
+    """Handle ambiguity using numeric prompt fallback."""
+    # Escape special characters for display
+    safe_resource_type = resource_type.replace("{", "{{").replace("}", "}}")
+    safe_ref = ref.replace("{", "{{").replace("}", "}}")
 
-    if questionary and os.getenv("TERM") and os.isatty(0) and os.isatty(1):
-        picked_idx = questionary.select(
-            f"Multiple {resource_type.replace('{', '{{').replace('}', '}}')}s match '{ref.replace('{', '{{').replace('}', '}}')}'. Pick one:",
-            choices=[
-                questionary.Choice(
-                    title=f"{getattr(m, 'name', '—').replace('{', '{{').replace('}', '}}')} — {getattr(m, 'id', '').replace('{', '{{').replace('}', '}}')}",
-                    value=i,
-                )
-                for i, m in enumerate(matches)
-            ],
-            use_indicator=True,
-            qmark="🧭",
-            instruction="↑/↓ to select • Enter to confirm",
-        ).ask()
-        if picked_idx is None:
-            raise click.ClickException("Selection cancelled")
-        return matches[picked_idx]
-
-    # Fallback numeric prompt
     console.print(
         Text(
-            f"[yellow]Multiple {resource_type.replace('{', '{{').replace('}', '}}')}s found matching '{ref.replace('{', '{{').replace('}', '}}')}':[/yellow]"
+            f"[yellow]Multiple {safe_resource_type}s found matching '{safe_ref}':[/yellow]"
         )
     )
     table = AIPTable(
-        title=f"Select {resource_type.replace('{', '{{').replace('}', '}}').title()}",
+        title=f"Select {safe_resource_type.title()}",
     )
     table.add_column("#", style="dim", width=3)
     table.add_column("ID", style="dim", width=36)
@@ -996,10 +1195,60 @@ def handle_ambiguous_resource(
     for i, m in enumerate(matches, 1):
         table.add_row(str(i), str(getattr(m, "id", "")), str(getattr(m, "name", "")))
     console.print(table)
-    choice = click.prompt(
-        f"Select {resource_type.replace('{', '{{').replace('}', '}}')} (1-{len(matches)})",
-        type=int,
+    choice_str = click.prompt(
+        f"Select {safe_resource_type} (1-{len(matches)})",
     )
+    try:
+        choice = int(choice_str)
+    except ValueError:
+        raise click.ClickException("Invalid selection")
     if 1 <= choice <= len(matches):
         return matches[choice - 1]
     raise click.ClickException("Invalid selection")
+
+
+def _should_fallback_to_numeric_prompt(exception: Exception) -> bool:
+    """Determine if we should fallback to numeric prompt for this exception."""
+    # Re-raise cancellation - user explicitly cancelled
+    if "Selection cancelled" in str(exception):
+        return False
+
+    # Fall back to numeric prompt for other exceptions
+    return True
+
+
+def handle_ambiguous_resource(
+    ctx: Any, resource_type: str, ref: str, matches: list[Any]
+) -> Any:
+    """Handle multiple resource matches gracefully."""
+    if _get_view(ctx) == "json":
+        return _handle_json_view_ambiguity(matches)
+
+    try:
+        return _handle_questionary_ambiguity(resource_type, ref, matches)
+    except Exception as e:
+        if _should_fallback_to_numeric_prompt(e):
+            try:
+                return _handle_fallback_numeric_ambiguity(resource_type, ref, matches)
+            except Exception:
+                # If fallback also fails, re-raise the original exception
+                raise e
+        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"