archivedive 0.1.0__tar.gz

archivedive-0.1.0/.claude/settings.local.json

@@ -0,0 +1,40 @@
+{
+  "permissions": {
+    "allow": [
+      "WebSearch",
+      "WebFetch(domain:api-docs.gatcg.com)",
+      "WebFetch(domain:scryfall.com)",
+      "Bash(uv --version)",
+      "Bash(uv sync *)",
+      "Bash(git init *)",
+      "Skill(git-commit)",
+      "Bash(git add *)",
+      "Bash(git commit *)",
+      "Bash(uv run *)",
+      "Bash(git restore *)",
+      "Bash(uv add *)",
+      "Bash(uv remove *)",
+      "Bash(uv pip *)",
+      "WebFetch(domain:index.gatcg.com)",
+      "WebFetch(domain:rules.gatcg.com)",
+      "WebFetch(domain:www.gatcg.com)",
+      "Read(//home/celeryjro/Documents/Projects/ga-archivedive/ga_archivedive/**)",
+      "Read(//home/celeryjro/Documents/Projects/ga-archivedive/**)",
+      "Bash(python3 *)",
+      "Bash(.venv/bin/pytest *)",
+      "Bash(.venv/bin/python *)",
+      "Bash(curl -s \"https://api.gatcg.com/cards/search?subtype=CLERIC&per_page=3\")",
+      "Bash(curl -s \"https://api.gatcg.com/cards/search?subtype=MAGE&per_page=3\")",
+      "Bash(curl -s \"https://api.gatcg.com/cards/search?per_page=1\")",
+      "Bash(curl -s \"https://api.gatcg.com/cards/search?subtype=CLERIC&per_page=1\")",
+      "Bash(curl -s \"https://api.gatcg.com/cards/search?subtype=MAGE&per_page=1\")",
+      "Bash(python *)",
+      "WebFetch(domain:github.com)",
+      "WebFetch(domain:textual.textualize.io)",
+      "WebFetch(domain:raw.githubusercontent.com)",
+      "WebFetch(domain:darren.codes)",
+      "Bash(gh issue *)",
+      "WebFetch(domain:gitlab.gnome.org)"
+    ]
+  }
+}

archivedive-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+.venv/
+__pycache__/
+*.pyc
+*.pyo
+.pytest_cache/
+dist/
+*.egg-info/
+.DS_Store
+REVIEW.md

archivedive-0.1.0/.python-version

@@ -0,0 +1 @@
+3.11

archivedive-0.1.0/PKG-INFO

@@ -0,0 +1,68 @@
+Metadata-Version: 2.4
+Name: archivedive
+Version: 0.1.0
+Summary: A Scryfall-like TUI card browser for Grand Archive TCG
+Author-email: Thi Dinh <vietthidinh2001@gmail.com>
+License: MIT
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: platformdirs>=4.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: textual>=8.2.7
+Description-Content-Type: text/markdown
+
+# ArchiveDive
+
+A terminal card browser for [Grand Archive TCG](https://www.gatcg.com/), inspired by [Scryfall](https://scryfall.com).
+
+![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue)
+
+## Install
+
+```
+pip install archivedive
+```
+
+or with uv (no install needed):
+
+```
+uvx archivedive
+```
+
+## Usage
+
+```
+archivedive
+```
+
+### Key bindings
+
+| Key      | Action                      |
+| -------- | --------------------------- |
+| `s`      | Focus search bar            |
+| `F1`     | Search syntax help          |
+| `c`      | Copy card text to clipboard |
+| `o`      | Open card image in browser  |
+| `ctrl+o` | Select art edition          |
+| `r`      | Show related cards          |
+| `ctrl+<` | Previous page               |
+| `ctrl+>` | Next page                   |
+| `ctrl+c` | Copy search bar text        |
+| `ctrl+q` | Quit                        |
+
+Clipboard copy requires `wl-clipboard` (Wayland), `xclip`, or `xsel` on Linux.
+
+## Search syntax
+
+Filters use `key:value` format and combine with `and`. Element filters use `or`.
+
+```
+silvie                          search by name
+t:ally e:fire cost:2            fire ally costing 2
+class:mage o:banish -r:common   mage with banish, not common
+e:fire or e:water               fire or water element
+t:champion legal:standard       standard-legal champions
+sort:rarity order:desc          sort by rarity descending
+```
+
+See [SEARCH_SYNTAX.md](SEARCH_SYNTAX.md) for the full reference.

archivedive-0.1.0/README.md

@@ -0,0 +1,55 @@
+# ArchiveDive
+
+A terminal card browser for [Grand Archive TCG](https://www.gatcg.com/), inspired by [Scryfall](https://scryfall.com).
+
+![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue)
+
+## Install
+
+```
+pip install archivedive
+```
+
+or with uv (no install needed):
+
+```
+uvx archivedive
+```
+
+## Usage
+
+```
+archivedive
+```
+
+### Key bindings
+
+| Key      | Action                      |
+| -------- | --------------------------- |
+| `s`      | Focus search bar            |
+| `F1`     | Search syntax help          |
+| `c`      | Copy card text to clipboard |
+| `o`      | Open card image in browser  |
+| `ctrl+o` | Select art edition          |
+| `r`      | Show related cards          |
+| `ctrl+<` | Previous page               |
+| `ctrl+>` | Next page                   |
+| `ctrl+c` | Copy search bar text        |
+| `ctrl+q` | Quit                        |
+
+Clipboard copy requires `wl-clipboard` (Wayland), `xclip`, or `xsel` on Linux.
+
+## Search syntax
+
+Filters use `key:value` format and combine with `and`. Element filters use `or`.
+
+```
+silvie                          search by name
+t:ally e:fire cost:2            fire ally costing 2
+class:mage o:banish -r:common   mage with banish, not common
+e:fire or e:water               fire or water element
+t:champion legal:standard       standard-legal champions
+sort:rarity order:desc          sort by rarity descending
+```
+
+See [SEARCH_SYNTAX.md](SEARCH_SYNTAX.md) for the full reference.

archivedive-0.1.0/SEARCH_SYNTAX.md

@@ -0,0 +1,201 @@
+# ArchiveDive Search Syntax
+
+## Basic search
+
+Plain text searches by card name (fuzzy match).
+
+    silvie
+    dungeon guide
+
+---
+
+## Keyword filters
+
+Filters use the format `key:value`. Multiple filters are combined with `and`.
+
+| Key       | Aliases                   | Description                     | Example            |
+| --------- | ------------------------- | ------------------------------- | ------------------ |
+| `name:`   | (plain text)              | Card name                       | `silvie`           |
+| `o:`      | `effect:`                 | Effect text (any edition)       | `o:banish`         |
+| `oc:`     | `oracle:`                 | Effect text (canonical only)    | `oc:banish`        |
+| `kw:`     | `keyword:`                | Keyword ability (exact match)   | `kw:stealth`       |
+| `rule:`   |                           | Rule text (title or body)       | `rule:graveyard`   |
+| `flavor:` |                           | Flavor text                     | `flavor:silvie`    |
+| `ill:`    | `illustrator:`            | Illustrator name (fuzzy)        | `ill:dragonart`    |
+| `t:`      | `type:` `sub:` `subtype:` | Type or subtype (searches both) | `t:ally` `t:human` |
+| `class:`  | `cl:`                     | Class                           | `class:mage`       |
+| `e:`      | `element:`                | Element (see below)             | `e:fire`           |
+| `r:`      | `rarity:`                 | Rarity (see below)              | `r:rare`           |
+| `set:`    | `s:`                      | Set prefix code                 | `set:DOA`          |
+| `cost:`   | `c:`                      | Memory or reserve cost (either) | `cost:3`           |
+| `m:`      | `memory:`                 | Memory cost only                | `m:3`              |
+| `res:`    | `reserve:`                | Reserve cost only               | `res:2`            |
+| `legal:`  |                           | Legal in format                 | `legal:standard`   |
+| `banned:` |                           | Banned in format                | `banned:standard`  |
+| `speed:`  |                           | Speed: fast or slow             | `speed:fast`       |
+| `is:`     |                           | Flags (see below)               | `is:material`      |
+| `pow:`    | `power:`                  | Power                           | `pow:3`            |
+| `life:`   |                           | Life                            | `life:4`           |
+| `dur:`    | `durability:`             | Durability                      | `dur:2`            |
+| `lvl:`    | `level:`                  | Level                           | `lvl:2`            |
+
+---
+
+## Flags (is:)
+
+| Flag           | Description                  | Expands to                                                                                                   |
+| -------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| `is:material`  | Material deck cards          | `t:champion or t:regalia`                                                                                    |
+| `is:permanent` | Cards that stay on the field | `t:ally or t:champion or t:item or t:weapon or t:token or t:status or t:regalia or t:phantasia or t:mastery` |
+
+---
+
+## Sorting
+
+Use `sort:` and `order:` to control result ordering.
+
+| Key      | Default | Values                                                       |
+| -------- | ------- | ------------------------------------------------------------ |
+| `sort:`  | `name`  | `name` `cost` `rarity` `power` `life` `level` `dur` `number` |
+| `order:` | `asc`   | `asc` `a` `desc` `d`                                         |
+
+Examples:
+
+    sort:rarity order:desc          highest rarity first
+    sort:cost                       cheapest cards first
+    e:fire sort:power order:desc    fire cards by power descending
+    t:champion sort:level           champions sorted by level
+
+---
+
+## Quoting phrases
+
+Wrap multi-word values in double quotes to search for an exact phrase.
+Without quotes, spaces end the value and the rest is parsed as new tokens.
+
+    o:"on enter"              effect contains the phrase "on enter"
+    o:"banish from memory"    exact phrase in effect text
+    name:"silvie"             works but unnecessary for single words
+    ill:dragonart             illustrator name
+
+---
+
+## Operators (numeric fields only)
+
+Supported: `=` (default), `>`, `<`, `>=`, `<=`
+
+    m>=3        memory cost 3 or more
+    pow<4       power less than 4
+    life=5      exactly 5 life
+    lvl<=2      level 2 or lower
+
+---
+
+## Negation
+
+Prefix a filter with `-` to exclude it. Handled client-side — pagination
+counts may differ slightly as results are filtered after fetching.
+
+    -e:fire       not fire element
+    -t:champion   not a champion
+    -r:common     not common rarity
+
+---
+
+## OR logic
+
+Use `or` or `OR` between filters. Handled client-side via two API calls
+merged and deduplicated.
+
+    e:fire or e:water           fire or water
+    e:fire or e:water           same thing
+    t:ally or t:champion        ally or champion
+    o:banish or o:memory        effect mentions banish or memory
+
+`or` binds more loosely than adjacent filters:
+
+    t:ally e:fire or t:champion     (ally AND fire) or (champion)
+
+Use parentheses to make explicit grouping:
+
+    (t:ally e:fire) or (t:champion e:water)   explicit grouping
+    (t:ally or t:champion) e:fire             fire ally or fire champion
+
+---
+
+## Combining filters
+
+    t:ally e:fire cost:2            fire ally costing 2 (memory or reserve)
+    t:human class:mage o:banish     human mage with banish in effect
+    t:champion -e:norm              champion with any element
+    e:fire or e:water -r:common     fire or water, excluding commons
+    set:DOA legal:standard          Dawn of Ashes cards legal in standard
+
+---
+
+## Elements
+
+    fire    water   wind    crux    norm
+    arcane  astra   tera    umbra   luxem
+    neos    exia    exalted
+
+Aliases: fi=fire wa=water wi=wind cr=crux no=norm
+
+---
+
+## Rarities
+
+    common (c)       uncommon (u)      rare (r)
+    superrare (sr)   ultrarare (ur)    promo (pr)
+    collectorsuper (csr)   collectorultra (cur)   collectorpromo (cpr)
+
+---
+
+## Legality formats
+
+Used with `legal:` and `banned:`:
+
+    standard (s)    pantheon (p)    draft (d)
+
+    legal:standard      legal:s
+    banned:pantheon     banned:p
+
+---
+
+## Keywords (kw:)
+
+Common keywords (59 total — see rules.gatcg.com/glossary/keywords-and-abilities):
+
+    stealth       taunt         steadfast     unblockable   true sight
+    intercept     cleave        agility       ambush        on enter
+    on death      on hit        on attack     on kill       floating memory
+    vigor         ranged        empower       bulwark       immortality
+
+`kw:` matches only cards that have the keyword — not cards that merely mention
+it in their text. Handled client-side: fetches by effect text, then filters
+to cards where the keyword appears as a standalone ability.
+
+---
+
+## Examples
+
+    silvie
+    t:ally e:fire cost:2
+    class:mage o:banish -r:common
+    t:champion legal:p lvl<=3
+    pow>=3 life>=3 t:human
+    o:memory speed:fast
+    set:DOA t:champion
+    banned:standard
+    legal:pantheon t:champion
+    is:material e:fire
+    is:permanent -t:champion
+    e:fire or e:water -r:common -r:uncommon
+    o:"on enter" t:ally class:mage
+    oc:"banish from memory"
+    kw:stealth t:ally
+    kw:taunt or kw:intercept
+    rule:graveyard
+    flavor:"courage"
+    ill:dragonart r:csr
+    is:material legal:s -r:common

archivedive-0.1.0/ga_archivedive/api.py

@@ -0,0 +1,301 @@
+from __future__ import annotations
+
+import json
+import sqlite3
+import time
+from pathlib import Path
+from typing import Any
+
+import httpx
+from platformdirs import user_cache_dir
+
+from .models import Card, SearchResponse
+
+BASE_URL = "https://api.gatcg.com"
+CACHE_TTL = 3600  # 1 hour
+
+
+def _cache_path() -> Path:
+    path = Path(user_cache_dir("ga-archivedive")) / "cache.db"
+    path.parent.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+class _Cache:
+    def __init__(self) -> None:
+        self._db = sqlite3.connect(_cache_path())
+        self._db.execute(
+            "CREATE TABLE IF NOT EXISTS cache "
+            "(key TEXT PRIMARY KEY, value TEXT, expires_at REAL)"
+        )
+        self._db.commit()
+
+    def get(self, key: str) -> Any | None:
+        row = self._db.execute(
+            "SELECT value, expires_at FROM cache WHERE key = ?", (key,)
+        ).fetchone()
+        if row is None:
+            return None
+        value, expires_at = row
+        if time.time() > expires_at:
+            self._db.execute("DELETE FROM cache WHERE key = ?", (key,))
+            self._db.commit()
+            return None
+        try:
+            return json.loads(value)
+        except json.JSONDecodeError:
+            self._db.execute("DELETE FROM cache WHERE key = ?", (key,))
+            self._db.commit()
+            return None
+
+    def set(self, key: str, value: Any, ttl: int = CACHE_TTL) -> None:
+        self._db.execute(
+            "INSERT OR REPLACE INTO cache (key, value, expires_at) VALUES (?, ?, ?)",
+            (key, json.dumps(value), time.time() + ttl),
+        )
+        self._db.commit()
+
+    def clear(self) -> None:
+        self._db.execute("DELETE FROM cache")
+        self._db.commit()
+
+
+def _or_sort_key(card: Card, sort: str) -> tuple:
+    name = (card.name or "").lower()
+    if sort == "name":
+        return (name,)
+    if sort == "power":
+        return (card.power or 0, name)
+    if sort == "life":
+        return (card.life or 0, name)
+    if sort == "level":
+        return (card.level or 0, name)
+    if sort == "durability":
+        return (card.durability or 0, name)
+    if sort in ("cost_memory", "cost_reserve"):
+        try:
+            v = int((card.cost and card.cost.value) or 0)
+        except (ValueError, TypeError):
+            v = 0
+        return (v, name)
+    if sort == "rarity":
+        eds = card.result_editions or card.editions
+        try:
+            r = int(eds[0].rarity) if eds and eds[0].rarity else 0
+        except (ValueError, TypeError):
+            r = 0
+        return (r, name)
+    return (name,)
+
+
+class GAClient:
+    def __init__(self) -> None:
+        self._http = httpx.AsyncClient(
+            base_url=BASE_URL,
+            timeout=10.0,
+            headers={"Accept": "application/json"},
+        )
+        self._cache = _Cache()
+
+    async def close(self) -> None:
+        await self._http.aclose()
+
+    async def search(
+        self,
+        *,
+        name: str | None = None,
+        element: list[str] | None = None,
+        type: list[str] | None = None,
+        subtype: list[str] | None = None,
+        cls: list[str] | None = None,
+        rarity: list[str] | None = None,
+        cost_memory: int | None = None,
+        cost_reserve: int | None = None,
+        effect: str | None = None,
+        legality_format: str | None = None,
+        sort: str = "name",
+        order: str = "ASC",
+        page: int = 1,
+        page_size: int = 50,
+    ) -> SearchResponse:
+        params: dict[str, Any] = {
+            "sort": sort,
+            "order": order,
+            "page": page,
+            "page_size": page_size,
+        }
+        if name:
+            params["name"] = name
+        if element:
+            params["element[]"] = element
+        if type:
+            params["type[]"] = type
+        if subtype:
+            params["subtype[]"] = subtype
+        if cls:
+            params["class[]"] = cls
+        if rarity:
+            params["rarity[]"] = rarity
+        if cost_memory is not None:
+            params["cost_memory"] = cost_memory
+        if cost_reserve is not None:
+            params["cost_reserve"] = cost_reserve
+        if effect:
+            params["effect"] = effect
+        if legality_format:
+            params["legality_format"] = legality_format
+
+        cache_key = f"search:{json.dumps(params, sort_keys=True)}"
+        if cached := self._cache.get(cache_key):
+            return SearchResponse.model_validate(cached)
+
+        response = await self._http.get("/cards/search", params=params)
+        response.raise_for_status()
+        data = response.json()
+        self._cache.set(cache_key, data)
+        return SearchResponse.model_validate(data)
+
+    async def get_card(self, slug: str) -> Card:
+        cache_key = f"card:{slug}"
+        if cached := self._cache.get(cache_key):
+            return Card.model_validate(cached)
+
+        response = await self._http.get(f"/cards/{slug}")
+        response.raise_for_status()
+        data = response.json()
+        self._cache.set(cache_key, data)
+        return Card.model_validate(data)
+
+    async def autocomplete(self, name: str) -> list[Card]:
+        cache_key = f"autocomplete:{name}"
+        if cached := self._cache.get(cache_key):
+            return [Card.model_validate(c) for c in cached]
+
+        response = await self._http.get("/cards/autocomplete", params={"name": name})
+        response.raise_for_status()
+        data = response.json()
+        results = data.get("data", data) if isinstance(data, dict) else data
+        self._cache.set(cache_key, results, ttl=300)
+        return [Card.model_validate(c) for c in results]
+
+    async def random(self, count: int = 8) -> list[Card]:
+        response = await self._http.get("/cards/random", params={"count": count})
+        response.raise_for_status()
+        data = response.json()
+        cards = data.get("data", data) if isinstance(data, dict) else data
+        return [Card.model_validate(c) for c in cards]
+
+    async def search_query(
+        self,
+        query: str,
+        page: int = 1,
+        page_size: int = 50,
+    ) -> SearchResponse:
+        from .query import parse, to_api_params, apply_client_filters
+
+        parsed = parse(query)
+
+        if not parsed.groups or all(not g for g in parsed.groups):
+            if parsed.warnings:
+                return SearchResponse(
+                    data=[], total_cards=0, total_pages=1, has_more=False,
+                    paginated_cards_count=0, page=page, page_size=page_size,
+                )
+            return await self.search(page=page, page_size=page_size)
+
+        if len(parsed.groups) == 1:
+            return await self._fetch_group(
+                parsed.groups[0], page, page_size,
+                sort=parsed.sort, order=parsed.order,
+            )
+
+        # OR: fetch each group and merge, deduplicated by slug
+        seen: set[str] = set()
+        merged: list[Card] = []
+        for group in parsed.groups:
+            result = await self._fetch_group(
+                group, page=1, page_size=page_size,
+                sort=parsed.sort, order=parsed.order,
+            )
+            for card in result.data:
+                if card.slug not in seen:
+                    seen.add(card.slug)
+                    merged.append(card)
+
+        merged.sort(
+            key=lambda c: _or_sort_key(c, parsed.sort),
+            reverse=(parsed.order.upper() == "DESC"),
+        )
+
+        resp = SearchResponse(
+            data=merged,
+            total_cards=len(merged),
+            total_pages=1,
+            has_more=False,
+            paginated_cards_count=len(merged),
+            page=1,
+            page_size=page_size,
+        )
+        return resp
+
+    async def _fetch_group(
+        self,
+        filters: list,
+        page: int,
+        page_size: int,
+        sort: str = "name",
+        order: str = "ASC",
+    ) -> SearchResponse:
+        from .query import to_api_params, apply_client_filters
+
+        params = to_api_params(filters)
+        params["sort"] = sort
+        params["order"] = order
+        params["page"] = page
+        params["page_size"] = page_size
+
+        cache_key = f"query:{json.dumps(params, sort_keys=True, default=str)}"
+        if cached := self._cache.get(cache_key):
+            result = SearchResponse.model_validate(cached)
+        else:
+            # Build httpx-compatible param list (multi-value support)
+            param_list: list[tuple[str, Any]] = []
+            for k, v in params.items():
+                if isinstance(v, list):
+                    for item in v:
+                        param_list.append((k, item))
+                else:
+                    param_list.append((k, v))
+
+            response = await self._http.get("/cards/search", params=param_list)
+            response.raise_for_status()
+            data = response.json()
+            self._cache.set(cache_key, data)
+            result = SearchResponse.model_validate(data)
+
+        result.data = apply_client_filters(result.data, filters)
+        return result
+
+    async def fetch_known_types(self) -> set[str]:
+        """Fetch all valid card types from the API definitions endpoint."""
+        cache_key = "definitions:types"
+        if cached := self._cache.get(cache_key):
+            return set(cached)
+        try:
+            response = await self._http.get("/option/search")
+            response.raise_for_status()
+            types = {entry["value"] for entry in response.json().get("type", [])}
+            self._cache.set(cache_key, list(types), ttl=86400)  # cache 24h
+            return types
+        except Exception:
+            return set()
+
+    def image_url(self, filename: str) -> str:
+        return f"{BASE_URL}/cards/images/{filename}"
+
+    async def fetch_image(self, filename: str) -> bytes:
+        if filename.startswith("/cards/images/"):
+            filename = filename[len("/cards/images/"):]
+        response = await self._http.get(f"/cards/images/{filename}")
+        response.raise_for_status()
+        return response.content