gog-cli 0.2.1__py3-none-any.whl

gog_cli/metadata.py

@@ -0,0 +1,212 @@
+"""Helpers for normalizing GOG metadata shapes."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from typing import Any
+
+_PLATFORM_ORDER = ("windows", "mac", "linux")
+_PLATFORM_ALIASES = {
+    "windows": "windows",
+    "win": "windows",
+    "mac": "mac",
+    "osx": "mac",
+    "macos": "mac",
+    "linux": "linux",
+}
+
+
+def normalize_platforms(values: Any) -> list[str]:
+    """Normalize platform names while preserving a stable display order."""
+    if isinstance(values, dict):
+        names = [key for key, enabled in values.items() if enabled]
+    elif isinstance(values, list | tuple | set):
+        names = list(values)
+    else:
+        names = []
+
+    normalized = {
+        platform
+        for value in names
+        if (platform := _PLATFORM_ALIASES.get(str(value).strip().lower()))
+    }
+    return [platform for platform in _PLATFORM_ORDER if platform in normalized]
+
+
+def extract_download_platforms(product_or_cache: dict[str, Any]) -> list[str]:
+    """Return platforms implied by product download metadata."""
+    product = product_or_cache.get("data", product_or_cache)
+    if not isinstance(product, dict):
+        return []
+
+    platform_values: list[str] = []
+    downloads = product.get("downloads", {})
+    if isinstance(downloads, dict):
+        for entries in downloads.values():
+            if not isinstance(entries, list):
+                continue
+            for entry in entries:
+                if not isinstance(entry, dict):
+                    continue
+                os_value = entry.get("os")
+                if os_value:
+                    platform_values.append(str(os_value))
+
+    compatibility = product.get("content_system_compatibility")
+    if isinstance(compatibility, dict):
+        platform_values.extend(
+            str(platform) for platform, supported in compatibility.items() if supported
+        )
+
+    return normalize_platforms(platform_values)
+
+
+def normalize_genres(*values: Any) -> list[str]:
+    """Normalize genre/category/tag-like metadata into display values."""
+    genres: list[str] = []
+    seen: set[str] = set()
+    for value in values:
+        for item in _flatten_metadata_values(value):
+            normalized = " ".join(str(item).strip().split())
+            if not normalized:
+                continue
+            if normalized.isdigit():
+                continue
+            key = normalized.casefold()
+            if key not in seen:
+                genres.append(normalized)
+                seen.add(key)
+    return genres
+
+
+def normalize_release_date(value: Any) -> str:
+    """Normalize GOG release date shapes to YYYY-MM-DD where possible."""
+    if isinstance(value, dict):
+        value = value.get("date")
+    if not isinstance(value, str) or not value.strip():
+        return ""
+
+    raw = value.strip()
+    candidates = [
+        raw,
+        raw.replace("Z", "+00:00"),
+        raw.replace(" ", "T"),
+    ]
+    for candidate in candidates:
+        try:
+            parsed = datetime.fromisoformat(candidate)
+        except ValueError:
+            continue
+        if parsed.tzinfo is not None:
+            parsed = parsed.astimezone(UTC)
+        return parsed.date().isoformat()
+
+    if len(raw) >= 10 and raw[4] == "-" and raw[7] == "-":
+        return raw[:10]
+    if len(raw) >= 4 and raw[:4].isdigit():
+        return raw[:4]
+    return raw
+
+
+def release_year(value: Any) -> int | None:
+    """Return the year from a normalized or raw GOG release date."""
+    release_date = normalize_release_date(value)
+    if len(release_date) >= 4 and release_date[:4].isdigit():
+        return int(release_date[:4])
+    return None
+
+
+def extract_size_summary(product_or_cache: dict[str, Any]) -> dict[str, Any]:
+    """Return installer sizes by platform and total extras size from download metadata."""
+    product = product_or_cache.get("data", product_or_cache)
+    if not isinstance(product, dict):
+        return {}
+    downloads = product.get("downloads")
+    if not isinstance(downloads, dict):
+        return {}
+
+    installer_sizes: dict[str, int] = {}
+    for entry in downloads.get("installers", []):
+        if not isinstance(entry, dict):
+            continue
+        platform = _PLATFORM_ALIASES.get(str(entry.get("os", "")).strip().lower())
+        if not platform:
+            continue
+        for file_entry in entry.get("files") or []:
+            if not isinstance(file_entry, dict):
+                continue
+            raw = (
+                file_entry["size"] if file_entry.get("size") is not None
+                else entry.get("total_size")
+            )
+            size = _parse_int(raw)
+            if size:
+                installer_sizes[platform] = installer_sizes.get(platform, 0) + size
+
+    extras_total = 0
+    for entry in downloads.get("bonus_content", []):
+        if not isinstance(entry, dict):
+            continue
+        for file_entry in entry.get("files") or []:
+            if not isinstance(file_entry, dict):
+                continue
+            raw = (
+                file_entry["size"] if file_entry.get("size") is not None
+                else entry.get("total_size")
+            )
+            size = _parse_int(raw)
+            if size:
+                extras_total += size
+
+    return {
+        "installer_sizes": installer_sizes if installer_sizes else None,
+        "extras_size": extras_total if extras_total else None,
+    }
+
+
+def _parse_int(value: Any) -> int | None:
+    if value is None:
+        return None
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return None
+
+
+def extract_download_summary(product_or_cache: dict[str, Any]) -> dict[str, Any]:
+    """Return list-facing metadata implied by product download metadata."""
+    product = product_or_cache.get("data", product_or_cache)
+    if not isinstance(product, dict):
+        return {}
+
+    summary: dict[str, Any] = {
+        "platforms": extract_download_platforms(product_or_cache),
+        "is_installable": (
+            bool(product["is_installable"]) if "is_installable" in product else None
+        ),
+        "download_type": str(product.get("game_type") or ""),
+    }
+    release_date = normalize_release_date(product.get("release_date"))
+    year = release_year(release_date)
+    if release_date and year is not None and year >= 1995:
+        summary["release_date"] = release_date
+        summary["release_year"] = year
+    return summary
+
+
+def _flatten_metadata_values(value: Any) -> list[Any]:
+    if value is None:
+        return []
+    if isinstance(value, str):
+        return [part for part in value.split(",") if part.strip()]
+    if isinstance(value, dict):
+        for key in ("name", "title", "label"):
+            if value.get(key):
+                return [value[key]]
+        return []
+    if isinstance(value, list | tuple | set):
+        items: list[Any] = []
+        for item in value:
+            items.extend(_flatten_metadata_values(item))
+        return items
+    return [value]

gog_cli/output.py

@@ -0,0 +1,99 @@
+"""Machine-readable output contracts and status vocabulary."""
+
+from __future__ import annotations
+
+import json
+import sys
+from dataclasses import dataclass
+from enum import StrEnum
+from typing import Any
+
+from gog_cli.state import utc_timestamp
+
+# ---------------------------------------------------------------------------
+# Format enum
+# ---------------------------------------------------------------------------
+
+
+class OutputFormat(StrEnum):
+    HUMAN = "human"
+    JSON = "json"
+
+
+# ---------------------------------------------------------------------------
+# JSON envelope
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class JsonEnvelope:
+    command: str
+    data: Any
+    schema_version: int = 1
+    generated_at: str = ""
+
+    def __post_init__(self) -> None:
+        if not self.generated_at:
+            self.generated_at = utc_timestamp()
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "schema_version": self.schema_version,
+            "command": self.command,
+            "generated_at": self.generated_at,
+            "data": self.data,
+        }
+
+
+# ---------------------------------------------------------------------------
+# Output helpers
+# ---------------------------------------------------------------------------
+
+
+def print_json(envelope: JsonEnvelope, *, file: Any = None) -> None:
+    if file is None:
+        file = sys.stdout
+    print(json.dumps(envelope.to_dict(), indent=2), file=file)
+
+
+def print_human(lines: list[str], *, file: Any = None) -> None:
+    if file is None:
+        file = sys.stdout
+    for line in lines:
+        print(line, file=file)
+
+
+def print_error(message: str, *, file: Any = None) -> None:
+    if file is None:
+        file = sys.stderr
+    print(message, file=file)
+
+
+# ---------------------------------------------------------------------------
+# Status vocabulary constants
+# ---------------------------------------------------------------------------
+
+# Cache status (TASK-0006)
+CACHE_FRESH = "fresh"
+CACHE_STALE = "stale"
+CACHE_MISSING = "missing"
+CACHE_CORRUPT = "corrupt"
+CACHE_UNSUPPORTED = "unsupported"
+
+# Game/backup status (TASK-0002)
+GAME_CURRENT = "current"
+GAME_PARTIAL = "partial"
+GAME_STALE = "stale"
+GAME_MISSING = "missing"
+GAME_UNVERIFIED = "unverified"
+GAME_ERROR = "error"
+
+# File status (TASK-0002)
+FILE_PLANNED = "planned"
+FILE_DOWNLOADING = "downloading"
+FILE_PARTIAL = "partial"
+FILE_DOWNLOADED = "downloaded"
+FILE_VERIFIED = "verified"
+FILE_FAILED = "failed"
+FILE_STALE = "stale"
+FILE_MISSING = "missing"

gog_cli/prompt.py

@@ -0,0 +1,57 @@
+"""Interactive and non-interactive selection helpers."""
+
+from __future__ import annotations
+
+import sys
+
+from gog_cli.errors import UsageError
+
+
+def is_interactive() -> bool:
+    """Return True when both stdin and stdout are TTYs."""
+    return sys.stdin.isatty() and sys.stdout.isatty()
+
+
+def numbered_prompt(items: list[str], prompt: str = "Enter selection:") -> list[int]:
+    """Print a numbered list to stderr and read a selection from stdin.
+
+    Accepts 'all' to select everything, or comma-separated 1-based numbers.
+    Returns a list of 0-based indices. Raises UsageError on invalid input.
+    """
+    if not items:
+        raise UsageError("No items available for selection")
+
+    for i, item in enumerate(items, 1):
+        print(f"  {i}. {item}", file=sys.stderr)
+
+    print(f"{prompt} ", end="", file=sys.stderr)
+    sys.stderr.flush()
+
+    try:
+        raw = sys.stdin.readline().strip()
+    except (EOFError, KeyboardInterrupt) as exc:
+        raise UsageError("Selection cancelled") from exc
+
+    if not raw:
+        raise UsageError("No selection made")
+
+    if raw.lower() == "all":
+        return list(range(len(items)))
+
+    indices: list[int] = []
+    for part in raw.split(","):
+        part = part.strip()
+        if not part:
+            continue
+        try:
+            n = int(part)
+        except ValueError:
+            raise UsageError(f"Invalid selection {part!r}: expected a number or 'all'") from None
+        if n < 1 or n > len(items):
+            raise UsageError(f"Selection {n} is out of range 1–{len(items)}")
+        indices.append(n - 1)
+
+    if not indices:
+        raise UsageError("No selection made")
+
+    return indices

gog_cli/refresh.py

@@ -0,0 +1,231 @@
+"""gog refresh — fetch library and download-metadata caches from GOG API."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from gog_cli import log
+from gog_cli.api import GogApiClient
+from gog_cli.auth import FileTokenStore
+from gog_cli.errors import ExitCode, NetworkError
+from gog_cli.metadata import (
+    extract_download_summary,
+    normalize_genres,
+    normalize_platforms,
+    normalize_release_date,
+    release_year,
+)
+from gog_cli.output import JsonEnvelope, OutputFormat, print_human, print_json
+from gog_cli.state import (
+    StateFileMissingError,
+    read_json_file,
+    resolve_app_paths,
+    utc_timestamp,
+    write_json_file_atomic,
+)
+
+_log = log.get_logger(__name__)
+
+
+def _normalize_game(product: dict) -> dict:
+    platforms = normalize_platforms(product.get("worksOn", {}))
+    release_date = normalize_release_date(product.get("releaseDate"))
+    return {
+        "product_id": product["id"],
+        "title": product.get("title", ""),
+        "slug": product.get("slug", ""),
+        "platforms": platforms,
+        "release_date": release_date,
+        "release_year": release_year(release_date),
+        "category": str(product.get("category") or ""),
+        "genres": normalize_genres(product.get("category"), product.get("tags", [])),
+        "image_url": product.get("image", ""),
+        "is_pre_order": bool(product.get("isComingSoon", False)),
+        "is_game": bool(product.get("isGame", True)),
+        "is_movie": bool(product.get("isMovie", False)),
+        "is_galaxy_compatible": bool(product.get("isGalaxyCompatible", False)),
+    }
+
+
+def _fetch_library(client: GogApiClient, *, progress: bool = False) -> list[dict]:
+    page = 1
+    games: list[dict] = []
+    total_pages: int | None = None
+    while True:
+        page_label = f"{page}/{total_pages}" if total_pages else str(page)
+        _print_progress(progress, f"Fetching library page {page_label}...")
+        data = client.get_library_page(page)
+        total_pages = int(data.get("totalPages", 1))
+        for product in data.get("products", []):
+            games.append(_normalize_game(product))
+        if page >= total_pages:
+            break
+        page += 1
+    _print_progress(progress, f"Fetched {len(games)} library entries.")
+    return games
+
+
+def _compute_delta(
+    old_games: list[dict], new_games: list[dict]
+) -> tuple[int, int, int]:
+    old_by_id = {g["product_id"]: g for g in old_games}
+    new_by_id = {g["product_id"]: g for g in new_games}
+    added = sum(1 for pid in new_by_id if pid not in old_by_id)
+    removed = sum(1 for pid in old_by_id if pid not in new_by_id)
+    changed = sum(
+        1
+        for pid, g in new_by_id.items()
+        if pid in old_by_id
+        and (
+            g["title"] != old_by_id[pid]["title"]
+            or g["slug"] != old_by_id[pid]["slug"]
+        )
+    )
+    return added, removed, changed
+
+
+def _load_old_games(library_cache: Path) -> list[dict]:
+    try:
+        data = read_json_file(library_cache)
+        return data.get("games", [])
+    except (StateFileMissingError, Exception):
+        return []
+
+
+def handle_refresh(args: argparse.Namespace) -> int:
+    paths = resolve_app_paths()
+    store = FileTokenStore(paths)
+    client = GogApiClient(store)
+
+    # load tokens early so AuthError surfaces before any network calls
+    store.load_tokens()
+
+    output_format = OutputFormat(getattr(args, "output_format", "human"))
+    force = getattr(args, "force", False)
+
+    old_games = _load_old_games(paths.library_cache)
+
+    progress = output_format == OutputFormat.HUMAN
+    games = _fetch_library(client, progress=progress)
+
+    failures: list[str] = []
+    fetched_at = utc_timestamp()
+    total_games = len(games)
+    _print_progress(progress, f"Refreshing download metadata for {total_games} games...")
+
+    for index, game in enumerate(games, start=1):
+        product_id = game["product_id"]
+        cache_path = paths.download_cache(str(product_id))
+        title = str(game.get("title") or product_id)
+
+        if not force and cache_path.exists():
+            _enrich_game_from_download_cache(game, cache_path)
+            _print_metadata_progress(progress, index, total_games, title, cached=True)
+            continue
+
+        try:
+            download_data = client.get_product_downloads(product_id)
+        except (NetworkError, Exception) as exc:  # noqa: BLE001
+            failures.append(f"{game['title']} ({product_id}): {exc}")
+            _log.warning("download fetch failed for %s: %s", product_id, exc)
+            _print_metadata_progress(progress, index, total_games, title, failed=True)
+            continue
+
+        _enrich_game_from_download_data(game, download_data)
+        _print_metadata_progress(progress, index, total_games, title)
+
+        write_json_file_atomic(
+            cache_path,
+            {
+                "fetched_at": fetched_at,
+                "product_id": product_id,
+                "data": download_data,
+            },
+        )
+
+    write_json_file_atomic(
+        paths.library_cache,
+        {"fetched_at": fetched_at, "games": games},
+    )
+
+    added, removed, changed = _compute_delta(old_games, games)
+    total = len(games)
+
+    if output_format == OutputFormat.JSON:
+        print_json(
+            JsonEnvelope(
+                command="refresh",
+                data={
+                    "total": total,
+                    "added": added,
+                    "removed": removed,
+                    "changed": changed,
+                    "failures": failures,
+                },
+            )
+        )
+    else:
+        print_human(
+            [
+                (
+                    f"Refreshed {total} games  "
+                    f"(+{added} added, -{removed} removed, ~{changed} changed)."
+                )
+            ]
+        )
+        for msg in failures:
+            print(f"  warning: {msg}", file=sys.stderr)
+
+    if failures:
+        return ExitCode.NETWORK
+    return ExitCode.SUCCESS
+
+
+def _print_progress(enabled: bool, message: str) -> None:
+    if enabled:
+        print(message, file=sys.stderr, flush=True)
+
+
+def _print_metadata_progress(
+    enabled: bool,
+    index: int,
+    total: int,
+    title: str,
+    *,
+    cached: bool = False,
+    failed: bool = False,
+) -> None:
+    if not enabled:
+        return
+    if index != 1 and index != total and index % 10 != 0 and not failed:
+        return
+    status = "cached" if cached else "fetched"
+    if failed:
+        status = "failed"
+    print(
+        f"Download metadata {index}/{total}: {status} {title}",
+        file=sys.stderr,
+        flush=True,
+    )
+
+
+def _enrich_game_from_download_cache(game: dict, cache_path: Path) -> None:
+    try:
+        cache = read_json_file(cache_path)
+    except Exception:  # noqa: BLE001
+        return
+    if isinstance(cache, dict):
+        _enrich_game_from_download_data(game, cache)
+
+
+def _enrich_game_from_download_data(game: dict, download_data: dict) -> None:
+    summary = extract_download_summary(download_data)
+    platforms = summary.get("platforms")
+    if platforms:
+        game["platforms"] = platforms
+    for key in ("is_installable", "download_type"):
+        value = summary.get(key)
+        if value not in (None, ""):
+            game[key] = value