slab-cli 0.1.0__py3-none-any.whl

slab_cli/flags.py

@@ -0,0 +1,189 @@
+"""The shared search-flag grammar — ONE definition of the --flags every search command accepts.
+
+The grammar mirrors the wire contract instead of re-inventing it per command: CARD_FLAGS maps onto
+`slab_schemas.CardFilter` (the filter grammar catalog and collection search share on the server),
+and COLLECTION_SEARCH_FLAGS extends it exactly like `CollectionSearchQuery` extends `CardFilter`.
+Each search command parses with its list and also attaches it to the handler (`handler.flags`), so
+`--help` renders the flag table from the same spec dispatch uses — help and behavior can't drift.
+
+Parsing is loud: an unknown flag raises `FlagError` with a did-you-mean suggestion instead of being
+silently folded into the free-text query (which made `collection list --team wild` search for the
+literal string "--team wild")."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import date
+from decimal import Decimal, InvalidOperation
+from difflib import get_close_matches
+from typing import Any
+
+
+class FlagError(Exception):
+    """A bad flag on the command line — unknown, missing its value, or an unparseable value.
+    The message is user-facing; main() catches this and prints it without a traceback."""
+
+
+@dataclass(frozen=True)
+class Flag:
+    """One --flag: the query field it fills, how its value parses, and its help line.
+
+    kind:
+      bool    — no value; stores `store` (lets --raw store graded=False)
+      str     — one value, kept as-is
+      int     — one value, int-parsed
+      decimal — one value, Decimal-parsed
+      date    — one value, ISO date (YYYY-MM-DD)
+      csv     — one value per use, repeatable; collects into a list (any-of on the server)
+    """
+
+    name: str
+    field: str
+    kind: str
+    help: str
+    store: Any = True
+    metavar: str = ""
+
+    def usage(self) -> str:
+        """`--team <value>` — the flag as it appears in help."""
+        if self.kind == "bool":
+            return self.name
+        meta = self.metavar or {"int": "<n>", "decimal": "<amount>", "date": "<yyyy-mm-dd>"}.get(
+            self.kind, "<value>"
+        )
+        return f"{self.name} {meta}"
+
+
+def _convert(spec: Flag, raw: str) -> Any:
+    if spec.kind == "int":
+        try:
+            return int(raw)
+        except ValueError:
+            raise FlagError(f"{spec.name} expects a number, got {raw!r}") from None
+    if spec.kind == "decimal":
+        try:
+            return Decimal(raw)
+        except InvalidOperation:
+            raise FlagError(f"{spec.name} expects an amount, got {raw!r}") from None
+    if spec.kind == "date":
+        try:
+            return date.fromisoformat(raw)
+        except ValueError:
+            raise FlagError(f"{spec.name} expects a date like 2026-01-31, got {raw!r}") from None
+    return raw
+
+
+def parse_flags(args: list[str], flags: list[Flag]) -> tuple[dict[str, Any], str | None]:
+    """Split `args` into (query-field values, free-text q).
+
+    Bare words join into the free-text query; anything starting with `--` must be a known flag
+    (`--flag value` or `--flag=value`). Repeatable csv flags accumulate. Unknown flags, missing
+    values, and bad values raise FlagError."""
+    by_name = {f.name: f for f in flags}
+    values: dict[str, Any] = {}
+    q_parts: list[str] = []
+
+    i = 0
+    while i < len(args):
+        arg = args[i]
+        if not arg.startswith("--"):
+            q_parts.append(arg)
+            i += 1
+            continue
+
+        name, _, inline = arg.partition("=")
+        spec = by_name.get(name)
+        if spec is None:
+            msg = f"unknown flag {name}"
+            hint = get_close_matches(name, list(by_name), n=1, cutoff=0.6)
+            if hint:
+                msg += f" (did you mean {hint[0]}?)"
+            raise FlagError(msg)
+
+        if spec.kind == "bool":
+            if inline:
+                raise FlagError(f"{spec.name} takes no value")
+            values[spec.field] = spec.store
+        else:
+            if inline:
+                raw = inline
+            else:
+                i += 1
+                if i >= len(args) or args[i].startswith("--"):
+                    raise FlagError(f"{spec.name} needs a value ({spec.usage()})")
+                raw = args[i]
+            val = _convert(spec, raw)
+            if spec.kind == "csv":
+                values.setdefault(spec.field, []).append(val)
+            else:
+                values[spec.field] = val
+        i += 1
+
+    return values, " ".join(q_parts) or None
+
+
+# --- The card grammar: mirrors slab_schemas.CardFilter --------------------------------------
+
+CARD_FLAGS: list[Flag] = [
+    # text / player
+    Flag("--player", "subject", "str", "Player name (substring match)", metavar="<name>"),
+    Flag("--number", "card_number", "str", "Card number (exact, e.g. YG-201)", metavar="<num>"),
+    # product
+    Flag("--set", "set_slug", "csv", "Set slug — repeatable, any-of", metavar="<slug>"),
+    Flag("--brand", "brand", "csv", "Brand name — repeatable, any-of", metavar="<name>"),
+    Flag("--subset", "subset", "csv", "Subset name — repeatable, any-of", metavar="<name>"),
+    Flag("--year", "year", "int", "Exact season-start year (2025 = 2025-26)", metavar="<year>"),
+    Flag("--year-min", "year_min", "int", "Season-start year >= this", metavar="<year>"),
+    Flag("--year-max", "year_max", "int", "Season-start year <= this", metavar="<year>"),
+    Flag("--sport", "sport", "csv", "Sport — repeatable, any-of", metavar="<name>"),
+    Flag("--league", "league", "csv", "League — repeatable, any-of", metavar="<name>"),
+    # who
+    Flag("--team", "team", "csv", "Team name — repeatable, any-of", metavar="<name>"),
+    # type / attributes
+    Flag("--attr", "attribute", "csv", "Attribute name — repeatable, any-of", metavar="<name>"),
+    Flag("--rookie", "rookie", "bool", "Only rookie cards"),
+    Flag("--auto", "auto", "bool", "Only autographed cards"),
+    Flag("--relic", "relic", "bool", "Only memorabilia cards"),
+    # finish / parallel
+    Flag("--finish", "finish", "csv", "Finish name — repeatable, any-of", metavar="<name>"),
+    Flag("--base", "base_only", "bool", "Only base printings (no parallels)"),
+    Flag("--parallel", "parallel_only", "bool", "Only parallels (has a finish)"),
+    # scarcity
+    Flag("--numbered", "is_numbered", "bool", "Only serial-numbered cards"),
+    Flag("--1of1", "is_1of1", "bool", "Only one-of-ones"),
+    Flag("--run-min", "numbered_min", "int", "Print run >= this"),
+    Flag("--run-max", "numbered_max", "int", "Print run <= this"),
+]
+
+_PAGING_FLAGS: list[Flag] = [
+    Flag("--sort", "sort", "str", "Sort key, prefix - for descending (keys listed above)", metavar="<key>"),
+    Flag("--limit", "limit", "int", "Results to show (default 25)"),
+]
+
+# What each search command parses: the shared card grammar + its scope's extras.
+
+CARD_SEARCH_FLAGS: list[Flag] = CARD_FLAGS + _PAGING_FLAGS
+
+COLLECTION_SEARCH_FLAGS: list[Flag] = CARD_FLAGS + [
+    # collection-only filters — mirrors CollectionSearchQuery's extension of CardFilter
+    Flag("--status", "status", "csv", "Copy status — repeatable, any-of", metavar="<status>"),
+    Flag("--graded", "graded", "bool", "Only professionally graded copies"),
+    Flag("--raw", "graded", "bool", "Only ungraded copies", store=False),
+    Flag("--company", "grading_company", "csv", "Grading company — repeatable", metavar="<name>"),
+    Flag("--self-grade", "self_grade", "csv", "Your self-grade rung — repeatable", metavar="<grade>"),
+    Flag("--acq", "acquisition_type", "csv", "Acquisition type — repeatable", metavar="<type>"),
+    Flag("--location", "storage_location", "str", "Storage location (substring)", metavar="<text>"),
+    Flag("--serial", "serial", "int", "The copy's serial number"),
+    Flag("--cost-min", "acquisition_cost_min", "decimal", "Acquisition cost >= this"),
+    Flag("--cost-max", "acquisition_cost_max", "decimal", "Acquisition cost <= this"),
+    Flag("--acquired-after", "acquired_after", "date", "Acquired on/after this date"),
+    Flag("--acquired-before", "acquired_before", "date", "Acquired on/before this date"),
+] + _PAGING_FLAGS
+
+SET_SEARCH_FLAGS: list[Flag] = [
+    # mirrors SetSearchQuery (sets have a slimmer grammar than cards)
+    Flag("--brand", "brand", "csv", "Brand name — repeatable, any-of", metavar="<name>"),
+    Flag("--year", "year", "int", "Exact season-start year", metavar="<year>"),
+    Flag("--sport", "sport", "str", "Sport", metavar="<name>"),
+    Flag("--limit", "limit", "int", "Results to show (default 25)"),
+]

slab_cli/help.py

@@ -0,0 +1,87 @@
+"""Help screens, rendered from the command registry.
+
+`slab` (no args) and `slab <group>` both land here. Because the text is generated from
+`commands.registry.GROUPS` — the same list dispatch uses — the help can never fall out of sync with
+what the CLI actually does. This screen is the CLI's source of truth for its command surface."""
+
+from __future__ import annotations
+
+from rich.table import Table
+from rich.text import Text
+
+import inspect
+
+from .banner import BANNER
+from .commands.registry import GROUPS, Command, Group
+from .theme import console, heading
+
+_CONFIG = "SLAB_API_URL · SLAB_API_KEY · SLAB_COLLECTOR"
+
+
+def _group_table(group: Group) -> Table:
+    """A group's verbs as an aligned two-column grid: full invocation, then its one-line summary."""
+    grid = Table.grid(padding=(0, 3))
+    grid.add_column(justify="left", no_wrap=True)
+    grid.add_column(justify="left", style="slab.dim")
+    for c in group.commands:
+        invocation = Text()
+        invocation.append("  slab ", style="slab.muted")
+        invocation.append(group.name, style="slab.foil")
+        invocation.append(f" {c.verb}", style="slab.value")
+        if c.args:
+            invocation.append(f" {c.args}", style="slab.dim")
+        grid.add_row(invocation, c.summary)
+    return grid
+
+
+def render_group_help(group: Group) -> None:
+    """`slab <group>` — just that noun's verbs."""
+    console.print(heading(group.name, group.blurb))
+    console.print(_group_table(group))
+    console.print()
+
+
+def render_command_help(group: Group, command: Command) -> None:
+    """`slab <group> <cmd> --help` — one command in detail: usage, summary, its handler's own
+    docstring (the leaf-level self-documentation), and — for search commands — the flag table,
+    rendered from the same spec list the parser uses (`handler.flags`) so it can't drift."""
+    console.print(Text.from_markup(
+        f"[slab.muted]usage:[/] [slab.foil]slab {group.name}[/] "
+        f"[slab.value]{command.verb}[/]"
+        + (f" [slab.dim]{command.args}[/]" if command.args else "")
+    ))
+    console.print(Text.from_markup(f"\n  {command.summary}"))
+    doc = inspect.getdoc(command.handler)
+    if doc:
+        # The handler docstring is the authoritative per-command detail — print it verbatim,
+        # indented, so a leaf command explains itself with no portal round-trip.
+        body = "\n".join(f"  {line}" for line in doc.splitlines())
+        console.print(Text.from_markup(f"\n[slab.dim]{body}[/]"))
+    flags = getattr(command.handler, "flags", None)
+    if flags:
+        console.print(Text.from_markup("\n  [slab.label]Flags[/]"))
+        grid = Table.grid(padding=(0, 3))
+        grid.add_column(justify="left", no_wrap=True, style="slab.value")
+        grid.add_column(justify="left", style="slab.dim")
+        for f in flags:
+            grid.add_row(f"    {f.usage()}", f.help)
+        console.print(grid)
+    console.print()
+
+
+def render_root_help() -> None:
+    """`slab` — the whole command surface, grouped by noun. The discovery home."""
+    console.print(BANNER)
+    console.print(Text.from_markup(
+        "  [slab.value]slab[/] [slab.dim]<group> <command> [options][/]     "
+        "[slab.muted]# e.g.[/] [slab.dim]slab card search mcdavid[/]"
+    ))
+    console.print(Text.from_markup(
+        "  [slab.muted]Drill into a group:[/] [slab.dim]slab card[/]    "
+        "[slab.muted]Help for one command:[/] [slab.dim]slab card search --help[/]\n"
+    ))
+    for group in GROUPS:
+        console.print(heading(group.name, group.blurb))
+        console.print(_group_table(group))
+        console.print()
+    console.print(Text.from_markup(f"  [slab.label]Config[/]  [slab.dim]{_CONFIG}[/]\n"))

slab_cli/main.py

@@ -0,0 +1,95 @@
+"""slab CLI — catalog, collect, and track your cards from the terminal.
+
+Commands are pure noun-verb: `slab <group> <command>` (like `git`, `docker`, `gh`). Run `slab` with
+no arguments for the full, grouped command surface — that screen is generated from the command
+registry (`commands/registry.py`), so it's always an accurate source of truth. `slab <group>` lists
+one group; `slab <group> <command> --help` explains a single command.
+"""
+
+from __future__ import annotations
+
+import sys
+
+from .client import ApiConnectionError, ApiError
+from .commands.registry import get_command, get_group, suggest_group, suggest_verb
+from .context import MissingCollector
+from .display import console
+from .flags import FlagError
+from .help import render_command_help, render_group_help, render_root_help
+
+_HELP_FLAGS = ("-h", "--help", "help")
+
+
+def _run(args: list[str]) -> int:
+    """Resolve `args` against the registry and run the command. Returns a process exit code."""
+    if not args or args[0] in _HELP_FLAGS:
+        render_root_help()
+        return 0
+
+    group_name = args[0]
+    group = get_group(group_name)
+    if group is None:
+        console.print(f"[red]Unknown command group: {group_name}[/red]")
+        hint = suggest_group(group_name)
+        if hint:
+            console.print(f"[dim]Did you mean [/dim][slab.value]slab {hint}[/][dim]?[/dim]")
+        console.print("[dim]Run [/dim][slab.value]slab[/][dim] to see all commands.[/dim]")
+        return 1
+
+    # `slab <group> --help` → list that group; bare `slab <group>` runs its default verb if it
+    # declares one (`slab community` → the board), otherwise also lists the group.
+    if len(args) == 1 or args[1] in _HELP_FLAGS:
+        if len(args) == 1 and group.default:
+            get_command(group_name, group.default).handler([])
+            return 0
+        render_group_help(group)
+        return 0
+
+    verb = args[1]
+    command = get_command(group_name, verb)
+    if command is None:
+        console.print(f"[red]Unknown command: slab {group_name} {verb}[/red]")
+        hint = suggest_verb(group_name, verb)
+        if hint:
+            console.print(f"[dim]Did you mean [/dim][slab.value]slab {group_name} {hint}[/][dim]?[/dim]")
+        console.print(f"[dim]Run [/dim][slab.value]slab {group_name}[/][dim] to see its commands.[/dim]")
+        return 1
+
+    # `slab <group> <cmd> --help` → explain this one command instead of running it.
+    if args[2:3] and args[2] in _HELP_FLAGS:
+        render_command_help(group, command)
+        return 0
+
+    command.handler(args[2:])
+    return 0
+
+
+def main() -> None:
+    try:
+        sys.exit(_run(sys.argv[1:]))
+    except KeyboardInterrupt:
+        console.print("\n[dim]Cancelled.[/dim]")
+    except FlagError as e:
+        console.print(f"[red]{e}[/red]")
+        sys.exit(2)
+    except MissingCollector:
+        console.print("[red]No collector set.[/red]")
+        console.print("  1. Run: slab collector create <your name>")
+        console.print("  2. Run: export SLAB_COLLECTOR=<uuid from step 1>")
+        sys.exit(1)
+    except ApiConnectionError as e:
+        console.print(f"\n[red]{e}[/red]")
+        console.print("[dim]  Check that the API is running and SLAB_API_URL is correct.[/dim]")
+        sys.exit(1)
+    except ApiError as e:
+        if e.status == 404:
+            console.print(f"[yellow]Not found: {e.detail}[/yellow]")
+        elif e.status == 401:
+            console.print("[red]Unauthorized — check your SLAB_API_KEY.[/red]")
+        else:
+            console.print(f"[red]API error: {e}[/red]")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

slab_cli/paging.py

@@ -0,0 +1,46 @@
+"""One paging loop for the whole CLI.
+
+Every "fetch the whole result set" flow (portfolio copies, the set catalog, a break checklist, an
+export) was its own hand-rolled `while` with its own cap convention (5000 / 1000 / uncapped). They
+all do the same thing: request pages until the server says there are no more. `fetch_all_pages`
+is that loop, once — the caller supplies only how to fetch one page.
+"""
+
+from __future__ import annotations
+
+from typing import Callable, Protocol, TypeVar
+
+
+class _Page(Protocol):
+    """The shape every search result already has: a page of items plus the full-result total."""
+    items: list
+    total: int
+
+
+P = TypeVar("P", bound=_Page)
+
+
+def fetch_all_pages(
+    fetch: Callable[[int, int], P], *, page: int = 200, cap: int | None = None
+) -> tuple[list, P | None]:
+    """Page ``fetch(limit, offset)`` to completion and return ``(all_items, first_page)``.
+
+    ``fetch`` returns a result object with ``.items`` (the page) and ``.total`` (the full count).
+    Paging stops when a short/empty page arrives, ``.total`` is reached, or ``cap`` items have been
+    collected (a safety bound against a runaway result set — ``None`` means no bound). ``first_page``
+    is the first response, handed back so callers can read page-invariant blocks (e.g. a portfolio
+    ``.summary``) without a second request; it's ``None`` only when ``fetch`` is never called, which
+    can't happen here but keeps the type honest.
+    """
+    items: list = []
+    first: P | None = None
+    offset = 0
+    while cap is None or len(items) < cap:
+        result = fetch(page, offset)
+        if first is None:
+            first = result
+        items.extend(result.items)
+        if not result.items or len(items) >= result.total:
+            break
+        offset += len(result.items)
+    return items, first

slab_cli/picker.py

@@ -0,0 +1,78 @@
+"""One subject-first card picker for the whole CLI.
+
+Five commands (`card parallels`, `card price`/`comps`, `card history`, `collection add`,
+`chase add`) all resolve a human query to a specific catalog card the same way: search a player,
+pick the player, then pick the exact printing among that player's cards. This module is that flow,
+once. Callers that need a different *final* step (an FMV-tagged list, a set-narrowing step, a tuple
+return) build on `search_and_pick_subject`; the common case is `pick_card`.
+"""
+
+from __future__ import annotations
+
+from slab_schemas.cards import CardOut, CardSearchQuery
+
+from .context import ctx
+from .prompts import ask_text, select_printing, select_set_filter, select_subject
+from .theme import console
+
+
+def search_and_pick_subject(
+    query: str | None,
+    *,
+    prompt: str = "Search for a card (player):",
+    not_found: str = "No cards found.",
+    limit: int = 200,
+    **search_kwargs,
+) -> tuple[list[CardOut], str] | None:
+    """The shared subject-first core: resolve a query to ``(that subject's cards, subject name)``.
+
+    ``query`` is the search text; when falsy the user is prompted with ``prompt``. Extra
+    ``search_kwargs`` (e.g. ``release=[...]`` to scope to a box, ``include_market=True``,
+    ``collector=...``) pass straight through to ``CardSearchQuery``. Returns ``None`` if nothing
+    matched (prints ``not_found``) or the user backed out of the player pick — so the caller only
+    ever gets a non-empty card list plus the chosen subject.
+    """
+    q = query if query else ask_text(prompt)
+    result = ctx.client.search_cards(CardSearchQuery(subject=q, limit=limit, **search_kwargs))
+    if not result.items:
+        console.print(f"[yellow]{not_found}[/yellow]")
+        return None
+
+    subject = select_subject(result.items)
+    if subject is None:
+        return None
+
+    cards = [c for c in result.items if any(s.name == subject for s in c.subjects)]
+    return cards, subject
+
+
+def pick_card(
+    query: str | None,
+    *,
+    prompt: str = "Search for a card (player):",
+    not_found: str = "No cards found.",
+    limit: int = 200,
+    narrow_set: bool = False,
+    **search_kwargs,
+) -> CardOut | None:
+    """The common case: search a player, pick them, pick the exact printing. Returns the chosen
+    card, or ``None`` if nothing matched or the user backed out at any step.
+
+    With ``narrow_set=True`` an extra step lets you pick the set (or "all sets") after the player —
+    the same player → set → card flow the pricing commands use — so a player who appears across many
+    products isn't dumped into one undifferentiated list. The set name is shown on each row whenever
+    the (post-narrowing) list still spans more than one set."""
+    picked = search_and_pick_subject(
+        query, prompt=prompt, not_found=not_found, limit=limit, **search_kwargs
+    )
+    if picked is None:
+        return None
+    cards, subject = picked
+
+    if narrow_set:
+        slug = select_set_filter(cards)  # auto-returns "" (all) when the player is in only one set
+        if slug:
+            cards = [c for c in cards if c.set_slug == slug]
+
+    show_set = len({c.set_slug for c in cards}) > 1
+    return select_printing(cards, subject, show_set=show_set)