browse_cmd.py

"""
Browse command for CLI.
"""

import asyncio
from typing import Annotated

import typer
from rich.console import Console
from rich.progress import Progress, SpinnerColumn, TextColumn

from ra_mcp_browse_lib.browse_operations import BrowseOperations
from ra_mcp_common.http_client import get_http_client
from ra_mcp_common.telemetry import get_tracer

from .formatter import RichConsoleFormatter


_tracer = get_tracer("ra_mcp.cli.browse")


console = Console()


def _print_renderables(renderables, console: Console) -> None:
    for item in renderables:
        console.print(item)


def browse(
    reference_code: Annotated[str, typer.Argument(help="Document reference code from search results (e.g., 'SE/RA/420422/01')")],
    pages: Annotated[
        str | None,
        typer.Option(help='Page specification: single ("5"), range ("1-10"), or list ("5,7,9"). Alias: --page'),
    ] = None,
    page: Annotated[
        str | None,
        typer.Option(help='Page specification: single ("5"), range ("1-10"), or list ("5,7,9"). Shorthand for --pages'),
    ] = None,
    search_term: Annotated[str | None, typer.Option("--search-term", help="Highlight keyword in transcribed text (case-insensitive)")] = None,
    max_display: Annotated[int, typer.Option("--max-display", help="Maximum number of pages to display in output")] = 20,
    log: Annotated[bool, typer.Option("--log", help="Enable detailed API request/response logging to ra_mcp_api.log file")] = False,
    show_links: Annotated[
        bool,
        typer.Option("--show-links", help="Display direct links to ALTO XML, IIIF images, and Bildvisaren viewer"),
    ] = False,
) -> None:
    """Browse pages by reference code.

    You can specify pages using either --pages or --page (they work the same way).
    If both are provided, --page takes precedence.

    Examples:
        ra browse "SE/RA/123" --page 5
        ra browse "SE/RA/123" --pages "1-10"
        ra browse "SE/RA/123" --page "5,7,9"
        ra browse "SE/RA/123" --page 1 --log      # With API logging
    """
    http_client = get_http_client(log)
    browse_operations = BrowseOperations(http_client=http_client)
    formatter = RichConsoleFormatter(console)

    console.print(f"\n[bold cyan]📖 Browsing document: {reference_code}[/bold cyan]\n")
    if log:
        console.print("[dim]API logging enabled - check ra_mcp_api.log[/dim]")

    requested_pages = page if page is not None else pages

    with _tracer.start_as_current_span(
        "cli.browse",
        attributes={
            "browse.reference_code": reference_code,
            "browse.pages": requested_pages or "1-20",
        },
    ):
        try:
            with Progress(
                SpinnerColumn(),
                TextColumn("[progress.description]{task.description}"),
                console=console,
            ) as progress:
                progress.add_task("Loading document...", total=None)

                browse_result = asyncio.run(
                    browse_operations.browse_document(
                        reference_code=reference_code,
                        pages=requested_pages or "1-20",
                        highlight_term=search_term,
                        max_pages=max_display,
                    )
                )

            if not browse_result.contexts and not browse_result.oai_metadata:
                console.print(f"[yellow]No pages found for '{reference_code}'[/yellow]")
                console.print("\n[dim]Suggestions:[/dim]")
                console.print("[dim]- Check the reference code format[/dim]")
                console.print("[dim]- Verify the document has transcribed pages[/dim]")
                console.print("[dim]- Try different page numbers[/dim]")
                raise typer.Exit(code=1)

            has_pages = bool(browse_result.contexts)
            renderables = formatter.format_browse_results(
                browse_result,
                highlight_term=search_term,
                show_links=show_links,
                show_success_message=has_pages,
            )
            _print_renderables(renderables, console)

        except typer.Exit:
            raise
        except Exception as error:
            console.print(f"[red]Browse failed: {error}[/red]")
            raise typer.Exit(code=1) from error