gog-cli 0.2.1__py3-none-any.whl

gog_cli/state.py

@@ -0,0 +1,193 @@
+"""Application state paths and JSON file helpers."""
+
+from __future__ import annotations
+
+import json
+import os
+from collections.abc import Mapping
+from contextlib import suppress
+from dataclasses import dataclass
+from datetime import UTC, datetime, timedelta
+from pathlib import Path
+from tempfile import NamedTemporaryFile
+from typing import Any, Literal
+
+APP_DIR_NAME = "gog-cli"
+
+CacheStatus = Literal["fresh", "stale"]
+
+
+class StateError(Exception):
+    """Base class for application state errors."""
+
+
+class StateFileMissingError(StateError):
+    """Raised when an expected state/cache file does not exist."""
+
+
+class StateFileCorruptError(StateError):
+    """Raised when a JSON state/cache file cannot be decoded."""
+
+
+class StateFileInvalidError(StateError):
+    """Raised when a state/cache file has an unsupported shape."""
+
+
+@dataclass(frozen=True)
+class AppRoots:
+    """Root directories owned by the application."""
+
+    config: Path
+    cache: Path
+    state: Path
+
+
+@dataclass(frozen=True)
+class AppPaths:
+    """Expected application-owned files and directories."""
+
+    roots: AppRoots
+    config_file: Path
+    library_cache: Path
+    downloads_cache_dir: Path
+    session_state: Path
+    cookies_file: Path
+    schema_file: Path
+    locks_dir: Path
+
+    def download_cache(self, product_id: str) -> Path:
+        """Return the per-game download-metadata cache path."""
+        if not product_id or "/" in product_id or "\x00" in product_id:
+            raise ValueError("product_id must be a non-empty path segment")
+        return self.downloads_cache_dir / f"{product_id}.json"
+
+
+@dataclass(frozen=True)
+class CacheReadResult:
+    """Read cache data plus freshness status."""
+
+    data: Mapping[str, Any]
+    status: CacheStatus
+
+
+def resolve_app_roots(env: Mapping[str, str] | None = None) -> AppRoots:
+    """Resolve app config/cache/state roots using Linux/XDG conventions."""
+    values = os.environ if env is None else env
+    home = Path(values.get("HOME") or str(Path.home())).expanduser()
+    config_base = _base_dir(values, "XDG_CONFIG_HOME", home / ".config")
+    cache_base = _base_dir(values, "XDG_CACHE_HOME", home / ".cache")
+    state_base = _base_dir(values, "XDG_DATA_HOME", home / ".local" / "share")
+    return AppRoots(
+        config=config_base / APP_DIR_NAME,
+        cache=cache_base / APP_DIR_NAME,
+        state=state_base / APP_DIR_NAME,
+    )
+
+
+def resolve_app_paths(env: Mapping[str, str] | None = None) -> AppPaths:
+    """Resolve expected application-owned paths."""
+    roots = resolve_app_roots(env)
+    return AppPaths(
+        roots=roots,
+        config_file=roots.config / "config.toml",
+        library_cache=roots.cache / "library.json",
+        downloads_cache_dir=roots.cache / "downloads",
+        session_state=roots.state / "session.json",
+        cookies_file=roots.state / "auth" / "cookies.txt",
+        schema_file=roots.state / "schema.json",
+        locks_dir=roots.state / "locks",
+    )
+
+
+def read_json_file(path: Path) -> Any:
+    """Read a JSON file, raising typed errors for missing or corrupt state."""
+    try:
+        with path.open("r", encoding="utf-8") as handle:
+            return json.load(handle)
+    except FileNotFoundError as exc:
+        raise StateFileMissingError(f"state file is missing: {path}") from exc
+    except json.JSONDecodeError as exc:
+        raise StateFileCorruptError(f"state file is corrupt JSON: {path}") from exc
+
+
+def write_json_file_atomic(path: Path, data: Any) -> None:
+    """Write JSON atomically by replacing through a temp file in the same dir."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    temp_name = ""
+    try:
+        with NamedTemporaryFile(
+            "w",
+            encoding="utf-8",
+            dir=path.parent,
+            prefix=f".{path.name}.",
+            suffix=".tmp",
+            delete=False,
+        ) as handle:
+            temp_name = handle.name
+            json.dump(data, handle, indent=2, sort_keys=True)
+            handle.write("\n")
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.replace(temp_name, path)
+    finally:
+        if temp_name:
+            with suppress(FileNotFoundError):
+                os.unlink(temp_name)
+
+
+def read_cache_file(
+    path: Path,
+    *,
+    max_age: timedelta | None = None,
+    now: datetime | None = None,
+) -> CacheReadResult:
+    """Read a JSON cache file and classify it as fresh or stale."""
+    data = read_json_file(path)
+    if not isinstance(data, Mapping):
+        raise StateFileInvalidError(f"cache file must contain a JSON object: {path}")
+    return CacheReadResult(
+        data=data,
+        status=_cache_status(data, max_age=max_age, now=now),
+    )
+
+
+def utc_timestamp() -> str:
+    """Return a UTC timestamp suitable for cache metadata."""
+    return datetime.now(UTC).replace(microsecond=0).isoformat().replace("+00:00", "Z")
+
+
+def _base_dir(env: Mapping[str, str], key: str, fallback: Path) -> Path:
+    value = env.get(key)
+    if not value:
+        return fallback.expanduser()
+    return Path(value).expanduser()
+
+
+def _cache_status(
+    data: Mapping[str, Any],
+    *,
+    max_age: timedelta | None,
+    now: datetime | None,
+) -> CacheStatus:
+    if max_age is None:
+        return "fresh"
+    updated_at = data.get("updated_at")
+    if not isinstance(updated_at, str):
+        return "stale"
+    updated = _parse_timestamp(updated_at)
+    if updated is None:
+        return "stale"
+    reference = now or datetime.now(UTC)
+    if reference.tzinfo is None:
+        reference = reference.replace(tzinfo=UTC)
+    return "stale" if reference - updated > max_age else "fresh"
+
+
+def _parse_timestamp(value: str) -> datetime | None:
+    try:
+        parsed = datetime.fromisoformat(value.replace("Z", "+00:00"))
+    except ValueError:
+        return None
+    if parsed.tzinfo is None:
+        return parsed.replace(tzinfo=UTC)
+    return parsed.astimezone(UTC)

gog_cli/sync.py

@@ -0,0 +1,146 @@
+"""Sync planning and stale-backup detection."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal
+
+from gog_cli.backup import FileSpec, PlannedFile, _game_product_id, _role_dir
+from gog_cli.layout import BackupLayout, sanitize_filename
+
+ComparisonStatus = Literal["current", "stale", "missing", "partial", "unverified"]
+
+
+@dataclass
+class FileComparison:
+    source_id: str
+    role: str
+    platform: str | None
+    language: str | None
+    status: ComparisonStatus
+    stale_reason: str | None = None
+
+
+@dataclass
+class SyncPlan:
+    destination: Path
+    comparisons: list[FileComparison]
+    to_download: list[PlannedFile]
+    to_verify: list[PlannedFile]
+    current: list[FileComparison]
+    estimated_bytes: int
+
+
+def compare_file(spec: FileSpec, manifest_record: dict | None) -> FileComparison:
+    base = FileComparison(
+        source_id=spec.source_id,
+        role=spec.role,
+        platform=spec.platform,
+        language=spec.language,
+        status="missing",
+    )
+
+    if manifest_record is None:
+        return base
+
+    rec_status = manifest_record.get("status", "")
+    if rec_status == "partial":
+        return FileComparison(**{**base.__dict__, "status": "partial"})
+    if rec_status == "downloaded":
+        return FileComparison(**{**base.__dict__, "status": "unverified"})
+
+    # Check staleness
+    if manifest_record.get("source_id") != spec.source_id:
+        return FileComparison(**{**base.__dict__, "status": "stale", "stale_reason": "id_changed"})
+    if manifest_record.get("version") != spec.version:
+        return FileComparison(
+            **{**base.__dict__, "status": "stale", "stale_reason": "version_changed"}
+        )
+    if manifest_record.get("expected_size") != spec.expected_size:
+        return FileComparison(
+            **{**base.__dict__, "status": "stale", "stale_reason": "size_changed"}
+        )
+    record_md5 = manifest_record.get("expected_md5")
+    checksum = manifest_record.get("checksum")
+    if isinstance(checksum, dict):
+        record_md5 = checksum.get("value")
+    if record_md5 != spec.expected_md5:
+        return FileComparison(
+            **{**base.__dict__, "status": "stale", "stale_reason": "checksum_changed"}
+        )
+
+    return FileComparison(**{**base.__dict__, "status": "current"})
+
+
+def plan_sync(
+    destination: Path,
+    games: list[dict],
+    download_specs: dict[str, list[FileSpec]],
+    manifest: dict,
+    layout: BackupLayout,
+    *,
+    platforms: list[str] | None = None,
+    languages: list[str] | None = None,
+    file_roles: list[str] | None = None,
+) -> SyncPlan:
+    manifest_games: dict[str, dict] = {}
+    for g in manifest.get("games", []):
+        for f in g.get("files", []):
+            key = _file_key(f.get("role"), f.get("platform"), f.get("language"), f.get("source_id"))
+            manifest_games.setdefault(str(g.get("product_id", "")), {})[key] = f
+
+    comparisons: list[FileComparison] = []
+    to_download: list[PlannedFile] = []
+    to_verify: list[PlannedFile] = []
+    current: list[FileComparison] = []
+    estimated_bytes = 0
+
+    for game in games:
+        product_id = _game_product_id(game)
+        slug = sanitize_filename(game.get("slug") or product_id)
+        game_dir = layout.game_dir(slug)
+        game_manifest = manifest_games.get(product_id, {})
+
+        for spec in download_specs.get(product_id, []):
+            if platforms and spec.platform and spec.platform not in platforms:
+                continue
+            if languages and spec.language and spec.language not in languages:
+                continue
+            if file_roles and spec.role not in file_roles:
+                continue
+
+            key = _file_key(spec.role, spec.platform, spec.language, spec.source_id)
+            record = game_manifest.get(key)
+            comparison = compare_file(spec, record)
+            comparisons.append(comparison)
+
+            dest_dir = _role_dir(layout, game_dir, spec.role)
+            dest = dest_dir / sanitize_filename(spec.filename or spec.source_id)
+
+            if comparison.status in ("missing", "stale", "partial"):
+                to_download.append(PlannedFile(spec=spec, dest=dest, action="download"))
+                if spec.expected_size:
+                    estimated_bytes += spec.expected_size
+            elif comparison.status == "unverified":
+                to_verify.append(PlannedFile(spec=spec, dest=dest, action="verify"))
+            elif comparison.status == "current":
+                current.append(comparison)
+
+    return SyncPlan(
+        destination=destination,
+        comparisons=comparisons,
+        to_download=to_download,
+        to_verify=to_verify,
+        current=current,
+        estimated_bytes=estimated_bytes,
+    )
+
+
+def _file_key(
+    role: str | None,
+    platform: str | None,
+    language: str | None,
+    source_id: str | None,
+) -> str:
+    return f"{role}:{platform}:{language}:{source_id}"

gog_cli-0.2.1.dist-info/METADATA

@@ -0,0 +1,193 @@
+Metadata-Version: 2.4
+Name: gog-cli
+Version: 0.2.1
+Summary: CLI tool for backing up DRM-free GOG games.
+Author: gog-cli contributors
+License: MIT License
+        
+        Copyright (c) 2026 gog-cli contributors
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/aleksandarristic/gog-cli
+Project-URL: Repository, https://github.com/aleksandarristic/gog-cli
+Project-URL: Bug Tracker, https://github.com/aleksandarristic/gog-cli/issues
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.32
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: responses>=0.25; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Dynamic: license-file
+
+# gog-cli
+
+[![CI](https://github.com/aleksandarristic/gog-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/aleksandarristic/gog-cli/actions/workflows/ci.yml)
+
+`gog` is a Python CLI for backing up a user's owned DRM-free GOG game library.
+
+It is focused on safe, scriptable workflows:
+
+- list owned games with filtering and fuzzy search
+- plan and execute backups to a local directory
+- preserve metadata needed to audit and restore backups
+- download installers and related files with resumable behavior
+- verify downloaded files when checksums are available
+
+## Install
+
+Requires Python 3.12 or newer.
+
+```sh
+pip install git+https://github.com/aleksandarristic/gog-cli.git
+```
+
+## Development
+
+```sh
+python3 -m venv .venv
+. .venv/bin/activate
+python -m pip install -e ".[dev]"
+python -m pytest
+```
+
+Run the CLI locally:
+
+```sh
+gog --help
+gog list
+gog plan --destination /path/to/backups --all --summary
+gog backup --destination /path/to/backups --games-from games.txt --dry-run
+```
+
+## Basic Workflow
+
+```sh
+gog auth login
+gog refresh
+gog list purchased
+gog plan --destination /path/to/backups --all --storage --check-free-space
+gog backup --destination /path/to/backups --all --yes
+gog list backed-up --destination /path/to/backups
+gog sync --destination /path/to/backups --all --yes
+```
+
+`gog refresh` updates the local purchased-library and download-metadata caches.
+It does not download game installers. Run it before browsing or filtering newly
+added library metadata.
+
+## Browsing Purchased Games
+
+`gog list purchased` reads the local cache written by `gog refresh`; it does not
+contact GOG. Human output includes ID, title, release year, genre/category, and
+platforms when those fields are available. JSON output also includes scriptable
+metadata such as `owned`, `release_date`, `genres`, and `is_installable`.
+
+Examples:
+
+```sh
+gog list purchased
+gog list purchased --format json
+gog list purchased --search witcher
+gog list purchased --search "baldurs gate"
+gog list purchased --platform windows
+gog list purchased --platform linux --search ftl
+gog list purchased --year 1998..2005
+gog list purchased --year 2010..2020 --include-unknown-year
+gog list purchased --genre strategy
+gog list purchased --genre arcade,rts
+gog list purchased --genre strategy --include-unknown-genre
+gog list purchased --search "baldurs gate" --platform linux --format json
+```
+
+Year filters omit games with unknown years by default; use
+`--include-unknown-year` to keep them. Genre filters similarly omit unknown
+genres by default; use `--include-unknown-genre` to keep those rows.
+
+## Planning Backups
+
+`gog plan` shows the same dry-run plan as `gog backup --dry-run` without
+downloading files or creating backup directories. Use it before long backup runs
+to estimate size, inspect filters, and check destination free space.
+
+Examples:
+
+```sh
+gog plan --destination /path/to/backups --all
+gog plan --destination /path/to/backups --all --summary
+gog plan --destination /path/to/backups --all --storage
+gog plan --destination /path/to/backups --all --check-free-space
+gog plan --destination /path/to/backups --all --format json
+gog plan --destination /path/to/backups cyberpunk_2077
+```
+
+Platform and language filters can reduce backup size:
+
+```sh
+gog plan --destination /path/to/backups --all --platform linux --storage
+gog plan --destination /path/to/backups --all --platform windows --language en --storage
+```
+
+## Selecting Games
+
+Game selectors can be product IDs, slugs, or exact titles. Commands that select
+games accept repeated `--game` flags:
+
+```sh
+gog plan --destination /path/to/backups --game witcher_3 --game cyberpunk_2077
+gog backup --destination /path/to/backups --game 123456789 --yes
+```
+
+For larger curated lists, put selectors in a UTF-8 text file and pass
+`--games-from`. Blank lines and lines whose first non-whitespace character is
+`#` are ignored.
+
+Example `games.txt`:
+
+```text
+# first NAS batch
+witcher_3
+cyberpunk_2077
+123456789
+```
+
+Use the selector file in plan, backup, or sync workflows:
+
+```sh
+gog plan --destination /path/to/backups --games-from games.txt --storage
+gog backup --destination /path/to/backups --games-from games.txt --downloader aria2c --yes
+gog sync --destination /path/to/backups --games-from games.txt --dry-run
+```
+
+`--games-from` is repeatable and combines with repeated `--game` flags. Do not
+combine explicit game selectors with `--all`.
+
+## Downloading
+
+`gog backup` defaults to the built-in direct downloader. To use `aria2c`, install
+`aria2c` and pass `--downloader aria2c` on an executing backup run:
+
+```sh
+gog backup --destination /path/to/backups --games-from games.txt --downloader aria2c --yes
+```
+
+Without `--yes`, backup and sync commands print a dry-run plan and exit without
+downloading or modifying backup files.

gog_cli-0.2.1.dist-info/RECORD

@@ -0,0 +1,25 @@
+gog_cli/__init__.py,sha256=cVhMzEvfgCoD2nRTTCEETe6ct0TfruTaiJ8lddmXO_c,73
+gog_cli/api.py,sha256=v-iEV7T_seYUWNl2AHHy-qLODewkQh7vrNIjpWf1yt8,5246
+gog_cli/aria2c.py,sha256=DFRL4GUGE-JzSKPuU0BvazKdwCYJNtT43V4RtALRG7U,4181
+gog_cli/auth.py,sha256=6AhtJ3v_2wlAdw0wR8KoKOCz4xaBBoym5K8iv9bfHso,7144
+gog_cli/backup.py,sha256=MsQDM2h8_hFjCCFadMQNH5ZybblrVjvWZSlmTaOXmZU,5971
+gog_cli/cli.py,sha256=77BtIc9rQhLffKfDsetOsKje8Q5JQDMBzy1Ad-HqgEU,18168
+gog_cli/config.py,sha256=4nY62B0ElRV6cW1y_UcXJFNi6RZGI8nA2eBxZlu04hk,4185
+gog_cli/downloader.py,sha256=G0cBQ4CNN4FYNZi-_k1jZGKdgcCaXOnhU6kO8F6eY_g,6919
+gog_cli/errors.py,sha256=iUo3xAQliNJuQUzVQPiIfRxJHtm6bEmwonvrlNChR1I,1185
+gog_cli/execution.py,sha256=WMaQAojT2grafBAzIoPFL_obXUF1snjolxRRJWTMe0o,36571
+gog_cli/layout.py,sha256=Ea1utRw7MjcXTznI5bpi3DgIokZNj-Yv3w0xUcPXcXc,1921
+gog_cli/listing.py,sha256=mZYUmk7geEms6e_DtPKJY-xV45CcUu9H5WWS6rbdM8g,22884
+gog_cli/log.py,sha256=z6sEDbqS7kQYeeD6MCFx3RaFF997lA_Boges-jAHLgI,468
+gog_cli/metadata.py,sha256=5hP16kpxt-N2rzpPWWnIUOnNdG0lkkRTMCQ9AfAcdBs,6961
+gog_cli/output.py,sha256=r4Zou7BpAzMXdVbGtQoT7Qq9lqsdZQIJDdnLUH7gPtw,2561
+gog_cli/prompt.py,sha256=tbWPr_9yd3-SMhQqxnx_hUM6s4pszh_6ph5-KvqPNKQ,1670
+gog_cli/refresh.py,sha256=VTM6Gthi97pvRuZhRlPg32ixUF9xpKOzfZj_2oTDcCo,7277
+gog_cli/state.py,sha256=X4DkVkJ4ZViH1wgLA8xHZgOABqlIwdato5zS6FpZ9VY,5904
+gog_cli/sync.py,sha256=OS0nWNxd4LLIMe2NKDHII8oiQX1DZS72W_dKmgmwilM,4971
+gog_cli-0.2.1.dist-info/licenses/LICENSE,sha256=6gwrSQnIro2IPRBL1bUj7r9cc7oG-WsufbDC8xHv1Lg,1077
+gog_cli-0.2.1.dist-info/METADATA,sha256=aAlbT8u4UuTFf5m1c_5URCsmb0o7oYlhYwEj9nW12jU,6673
+gog_cli-0.2.1.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+gog_cli-0.2.1.dist-info/entry_points.txt,sha256=R8ndz-Q46JZ2OBsfqsZN4b5DhHkFvEUwbGkc0P0rqI8,41
+gog_cli-0.2.1.dist-info/top_level.txt,sha256=ghVgOu6AMaHYlBtW37jklNOIdZviBwVAvN23Eq1EOLw,8
+gog_cli-0.2.1.dist-info/RECORD,,

gog_cli-0.2.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

gog_cli-0.2.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+gog = gog_cli.cli:main

gog_cli-0.2.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 gog-cli contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

gog_cli-0.2.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+gog_cli