gog-cli 0.2.1__py3-none-any.whl

gog_cli/cli.py

@@ -0,0 +1,550 @@
+"""Command-line interface for gog-cli."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+
+from gog_cli import __version__
+from gog_cli.auth import handle_auth_login, handle_auth_logout, handle_auth_status
+from gog_cli.errors import GogError
+from gog_cli.execution import handle_backup, handle_plan, handle_sync
+from gog_cli.listing import handle_list_backed_up, handle_list_purchased, handle_search_catalog
+from gog_cli.refresh import handle_refresh
+
+_TOP_LEVEL_EXAMPLES = """examples:
+  gog auth login
+  gog refresh
+  gog list purchased --search witcher
+  gog plan --destination /backups/gog --all --storage
+  gog backup --destination /backups/gog --games-from games.txt --downloader aria2c --yes
+  gog sync --destination /backups/gog --all --dry-run"""
+
+_AUTH_EXAMPLES = """examples:
+  gog auth login
+  gog auth status
+  gog auth logout"""
+
+_REFRESH_EXAMPLES = """examples:
+  gog refresh
+  gog refresh --force
+  gog refresh --format json"""
+
+_LIST_EXAMPLES = """examples:
+  gog list purchased
+  gog list purchased --search witcher --platform linux
+  gog list backup --destination /backups/gog
+  gog list backup --destination /backups/gog --format json"""
+
+_LIST_PURCHASED_EXAMPLES = """examples:
+  gog list purchased --search witcher
+  gog list purchased --platform windows
+  gog list purchased --year 1998..2005
+  gog list purchased --year 2010..2020 --include-unknown-year
+  gog list purchased --genre strategy
+  gog list purchased --genre strategy --include-unknown-genre
+  gog list purchased --search "baldurs gate" --platform linux --format json"""
+
+_LIST_BACKUP_EXAMPLES = """examples:
+  gog list backup --destination /backups/gog
+  gog list backup --destination /backups/gog --format json"""
+
+_SEARCH_EXAMPLES = """examples:
+  gog search witcher
+  gog search "baldurs gate" --platform windows
+  gog search strategy --year 2000..2010
+  gog search rpg --genre "role-playing" --format json"""
+
+_PLAN_EXAMPLES = """examples:
+  gog plan --destination /backups/gog --all --storage
+  gog plan --destination /backups/gog --all --check-free-space
+  gog plan --destination /backups/gog --games-from games.txt --summary
+  gog plan --destination /backups/gog cyberpunk-2077
+  gog plan --destination /backups/gog --all --format json"""
+
+_BACKUP_EXAMPLES = """examples:
+  gog backup --destination /backups/gog --all
+  gog backup --destination /backups/gog --all --yes
+  gog backup --destination /backups/gog --games-from games.txt --downloader aria2c --yes
+  gog backup --destination /backups/gog --platform linux --language en --all --yes
+  gog backup --destination /backups/gog --all --format json"""
+
+_SYNC_EXAMPLES = """examples:
+  gog sync --destination /backups/gog --all
+  gog sync --destination /backups/gog --all --dry-run
+  gog sync --destination /backups/gog --games-from games.txt --yes"""
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="gog",
+        description=(
+            "Back up owned DRM-free GOG games. Commands are explicit and "
+            "non-destructive by default; backup and sync print a dry-run plan "
+            "unless --yes is passed."
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=_TOP_LEVEL_EXAMPLES,
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {__version__}",
+    )
+
+    subcommands = parser.add_subparsers(dest="command", required=True)
+
+    _add_auth_parser(subcommands)
+    _add_refresh_parser(subcommands)
+    _add_list_parser(subcommands)
+    _add_search_parser(subcommands)
+    _add_plan_parser(subcommands)
+    _add_backup_parser(subcommands)
+    _add_sync_parser(subcommands)
+
+    return parser
+
+
+def _add_auth_parser(subcommands: argparse._SubParsersAction) -> None:  # type: ignore[type-arg]
+    auth = subcommands.add_parser(
+        "auth",
+        help="Manage GOG credentials.",
+        description=(
+            "Manage the local GOG session used by refresh and download commands. "
+            "Tokens are stored in app state, not inside backup destinations."
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=_AUTH_EXAMPLES,
+    )
+    auth_sub = auth.add_subparsers(dest="auth_command", required=True)
+
+    auth_sub.add_parser(
+        "login",
+        help="Log in to GOG.",
+        description="Start the browser-based GOG login flow and store a local session.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="examples:\n  gog auth login",
+    ).set_defaults(handler=handle_auth_login)
+    auth_sub.add_parser(
+        "status",
+        help="Show authentication status.",
+        description="Show whether a local GOG session is available and when it expires.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="examples:\n  gog auth status",
+    ).set_defaults(handler=handle_auth_status)
+    auth_sub.add_parser(
+        "logout",
+        help="Log out and remove credentials.",
+        description="Remove the local GOG session from app state.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="examples:\n  gog auth logout",
+    ).set_defaults(
+        handler=handle_auth_logout
+    )
+
+
+def _add_refresh_parser(subcommands: argparse._SubParsersAction) -> None:  # type: ignore[type-arg]
+    refresh = subcommands.add_parser(
+        "refresh",
+        help="Fetch library and download metadata from GOG.",
+        description=(
+            "Fetch purchased-library and download metadata into the local cache. "
+            "This does not download game installers."
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=_REFRESH_EXAMPLES,
+    )
+    refresh.add_argument(
+        "--force",
+        action="store_true",
+        help="Re-fetch all download metadata even if recently cached.",
+    )
+    refresh.add_argument(
+        "-f", "--format",
+        choices=["human", "json"],
+        default="human",
+        dest="output_format",
+        help="Output format (default: human).",
+    )
+    refresh.set_defaults(handler=handle_refresh)
+
+
+def _add_list_parser(subcommands: argparse._SubParsersAction) -> None:  # type: ignore[type-arg]
+    list_cmd = subcommands.add_parser(
+        "list",
+        help="List games.",
+        description="List cached purchased games or games already recorded in a backup manifest.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=_LIST_EXAMPLES,
+    )
+    list_sub = list_cmd.add_subparsers(dest="list_command", required=True)
+
+    purchased = list_sub.add_parser(
+        "purchased",
+        help="List owned GOG games.",
+        description=(
+            "List owned games from the local cache written by `gog refresh`. "
+            "This command does not contact GOG."
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=_LIST_PURCHASED_EXAMPLES,
+    )
+    purchased.add_argument(
+        "-f", "--format",
+        choices=["human", "json"],
+        default="human",
+        dest="output_format",
+        help="Output format (default: human).",
+    )
+    purchased.add_argument(
+        "-p", "--platform",
+        action="append",
+        default=[],
+        dest="platforms",
+        metavar="PLATFORM",
+        help="Filter by platform (windows, mac, linux). Repeatable.",
+    )
+    purchased.add_argument(
+        "-y", "--year",
+        metavar="RANGE",
+        help="Filter by release year, e.g. 1998..2005, 2020.., or ..2000.",
+    )
+    purchased.add_argument(
+        "--include-unknown-year",
+        action="store_true",
+        help="Keep games with unknown release years when --year is used.",
+    )
+    purchased.add_argument(
+        "-G", "--genre",
+        action="append",
+        default=[],
+        dest="genres",
+        metavar="GENRE",
+        help="Filter by genre/category/tag. Repeatable; comma-separated values allowed.",
+    )
+    purchased.add_argument(
+        "--include-unknown-genre",
+        action="store_true",
+        help="Keep games with unknown genres when --genre is used.",
+    )
+    purchased.add_argument(
+        "-s", "--search",
+        metavar="TEXT",
+        help="Fuzzy title search.",
+    )
+    purchased.add_argument(
+        "-S", "--sort",
+        choices=["title", "year", "size"],
+        metavar="COLUMN",
+        help="Sort results by column: title (A-Z), year (oldest first), size (largest first).",
+    )
+    purchased.set_defaults(handler=handle_list_purchased)
+
+    backed_up = list_sub.add_parser(
+        "backup",
+        help="List locally backed-up games.",
+        description="Read the backup manifest at a destination and summarize recorded games/files.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=_LIST_BACKUP_EXAMPLES,
+    )
+    backed_up.add_argument(
+        "-d", "--destination",
+        required=False,
+        default=None,
+        type=Path,
+        help="Backup destination directory to inspect (default: from config).",
+    )
+    backed_up.add_argument(
+        "-f", "--format",
+        choices=["human", "json"],
+        default="human",
+        dest="output_format",
+        help="Output format (default: human).",
+    )
+    backed_up.add_argument(
+        "-S", "--sort",
+        choices=["title", "size", "status", "files"],
+        metavar="COLUMN",
+        help="Sort by column: title (A-Z), size (largest first), status (A-Z), files (most first).",
+    )
+    backed_up.set_defaults(handler=handle_list_backed_up)
+
+
+def _add_search_parser(subcommands: argparse._SubParsersAction) -> None:  # type: ignore[type-arg]
+    search = subcommands.add_parser(
+        "search",
+        help="Search the public GOG catalog.",
+        description=(
+            "Search public GOG catalog data. Results are public catalog entries; "
+            "use `gog list purchased` for owned-library data."
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=_SEARCH_EXAMPLES,
+    )
+    search.add_argument("query", help="Search query (title keywords).")
+    search.add_argument(
+        "-f", "--format",
+        choices=["human", "json"],
+        default="human",
+        dest="output_format",
+        help="Output format (default: human).",
+    )
+    search.add_argument(
+        "-p", "--platform",
+        action="append",
+        default=[],
+        dest="platforms",
+        metavar="PLATFORM",
+        help="Filter by platform (windows, mac, linux). Repeatable.",
+    )
+    search.add_argument(
+        "-y", "--year",
+        metavar="RANGE",
+        help="Filter by release year, e.g. 1998..2005, 2020.., or ..2000.",
+    )
+    search.add_argument(
+        "-G", "--genre",
+        action="append",
+        default=[],
+        dest="genres",
+        metavar="GENRE",
+        help="Filter by genre/category/tag. Repeatable.",
+    )
+    search.set_defaults(handler=handle_search_catalog)
+
+
+def _add_selector_flags(parser: argparse.ArgumentParser) -> None:
+    grp = parser.add_argument_group("game selection")
+    grp.add_argument(
+        "-g", "--game",
+        dest="games",
+        metavar="SELECTOR",
+        action="append",
+        default=[],
+        help="Select a game by product id, slug, or exact title. Repeatable.",
+    )
+    grp.add_argument(
+        "-F", "--games-from",
+        dest="games_from",
+        metavar="PATH",
+        action="append",
+        default=[],
+        type=Path,
+        help="Read game selectors from a UTF-8 text file, one per line. Repeatable.",
+    )
+    grp.add_argument(
+        "-x", "--exclude",
+        metavar="SELECTOR",
+        action="append",
+        default=[],
+        help="Exclude a game by product id, slug, or exact title. Repeatable.",
+    )
+    grp.add_argument(
+        "-a", "--all",
+        dest="all_games",
+        action="store_true",
+        help="Select all owned games.",
+    )
+    grp.add_argument(
+        "-p", "--platform",
+        metavar="PLATFORM",
+        action="append",
+        default=[],
+        dest="platforms",
+        help="Limit to this platform (e.g. windows, linux, mac). Repeatable.",
+    )
+    grp.add_argument(
+        "-l", "--language",
+        metavar="LANG",
+        action="append",
+        default=[],
+        dest="languages",
+        help="Limit to this language code. Repeatable.",
+    )
+
+
+def _add_interaction_flags(parser: argparse.ArgumentParser) -> None:
+    grp = parser.add_argument_group("interaction")
+    grp.add_argument(
+        "--yes",
+        action="store_true",
+        help="Skip confirmation prompts.",
+    )
+    grp.add_argument(
+        "-n", "--no-interactive",
+        dest="no_interactive",
+        action="store_true",
+        help="Fail rather than prompt when selectors are missing.",
+    )
+    grp.add_argument(
+        "-D", "--downloader",
+        choices=["direct", "aria2c"],
+        default="direct",
+        help="Download engine to use (default: direct).",
+    )
+
+
+def _add_backup_parser(subcommands: argparse._SubParsersAction) -> None:  # type: ignore[type-arg]
+    backup = subcommands.add_parser(
+        "backup",
+        help="Back up owned GOG games to a local directory.",
+        description=(
+            "Plan or execute a local backup. Without --yes this command prints "
+            "a dry-run plan and exits without downloading or modifying backup files."
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=_BACKUP_EXAMPLES,
+    )
+    backup.add_argument(
+        "-d", "--destination",
+        type=Path,
+        help="Directory where game backups should be stored.",
+    )
+    backup.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Show the plan without downloading files.",
+    )
+    backup.add_argument(
+        "-f", "--format",
+        choices=["human", "json"],
+        default="human",
+        dest="output_format",
+        help="Output format (default: human).",
+    )
+    backup.add_argument(
+        "--check-free-space",
+        action="store_true",
+        dest="check_free_space",
+        help="Fail if available disk space is less than the estimated download size.",
+    )
+    backup.add_argument(
+        "--storage",
+        action="store_true",
+        help="Show disk usage section in plan output.",
+    )
+    backup.add_argument(
+        "--summary",
+        action="store_true",
+        help="Print summary only, omit per-game file detail.",
+    )
+    backup.add_argument(
+        "--changed-only",
+        action="store_true",
+        dest="changed_only",
+        help="Show only games with pending downloads in per-game detail.",
+    )
+    backup.add_argument(
+        "--explain-skips",
+        action="store_true",
+        dest="explain_skips",
+        help="Annotate skipped files with their filter reason.",
+    )
+    _add_selector_flags(backup)
+    _add_interaction_flags(backup)
+    backup.set_defaults(handler=handle_backup)
+
+
+def _add_plan_parser(subcommands: argparse._SubParsersAction) -> None:  # type: ignore[type-arg]
+    plan = subcommands.add_parser(
+        "plan",
+        help="Show the backup plan without downloading files.",
+        description=(
+            "Show a non-destructive backup plan. This is equivalent to "
+            "`gog backup --dry-run` and does not download files or create backup "
+            "directories."
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=_PLAN_EXAMPLES,
+    )
+    plan.add_argument(
+        "selectors",
+        nargs="*",
+        metavar="GAME",
+        help="Game selector by product id, slug, or exact title.",
+    )
+    plan.add_argument(
+        "-d", "--destination",
+        type=Path,
+        help="Directory where game backups should be stored.",
+    )
+    plan.add_argument(
+        "-f", "--format",
+        choices=["human", "json"],
+        default="human",
+        dest="output_format",
+        help="Output format (default: human).",
+    )
+    plan.add_argument(
+        "--check-free-space",
+        action="store_true",
+        dest="check_free_space",
+        help="Fail if available disk space is less than the estimated download size.",
+    )
+    plan.add_argument(
+        "--storage",
+        action="store_true",
+        help="Show disk usage section in plan output.",
+    )
+    plan.add_argument(
+        "--summary",
+        action="store_true",
+        help="Print summary only, omit per-game file detail.",
+    )
+    plan.add_argument(
+        "--changed-only",
+        action="store_true",
+        dest="changed_only",
+        help="Show only games with pending downloads in per-game detail.",
+    )
+    plan.add_argument(
+        "--explain-skips",
+        action="store_true",
+        dest="explain_skips",
+        help="Annotate skipped files with their filter reason.",
+    )
+    _add_selector_flags(plan)
+    plan.set_defaults(handler=handle_plan)
+
+
+def _add_sync_parser(subcommands: argparse._SubParsersAction) -> None:  # type: ignore[type-arg]
+    sync = subcommands.add_parser(
+        "sync",
+        help="Update stale local backups.",
+        description=(
+            "Compare cached source metadata to a backup manifest and plan updates. "
+            "Without --yes this command prints a dry-run plan and exits without "
+            "downloading or modifying backup files."
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=_SYNC_EXAMPLES,
+    )
+    sync.add_argument(
+        "-d", "--destination",
+        type=Path,
+        help="Backup destination directory to sync.",
+    )
+    sync.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Show the plan without downloading files.",
+    )
+    _add_selector_flags(sync)
+    _add_interaction_flags(sync)
+    sync.set_defaults(handler=handle_sync)
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        return args.handler(args)
+    except GogError as exc:
+        print(str(exc), file=sys.stderr)
+        return exc.exit_code
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

gog_cli/config.py

@@ -0,0 +1,120 @@
+"""Configuration loading with TOML file, env vars, and built-in defaults."""
+
+from __future__ import annotations
+
+import os
+import tomllib
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from gog_cli.errors import UsageError
+from gog_cli.state import AppPaths
+
+_VALID_DOWNLOADERS = frozenset({"direct", "aria2c"})
+_VALID_FORMATS = frozenset({"human", "json"})
+_KNOWN_DEFAULTS_KEYS = frozenset(
+    {
+        "destination",
+        "downloader",
+        "file_roles",
+        "format",
+        "interactive",
+        "languages",
+        "platforms",
+    }
+)
+
+
+@dataclass
+class Config:
+    destination: Path | None = None
+    downloader: str = "direct"
+    platforms: list[str] = field(default_factory=list)
+    languages: list[str] = field(default_factory=list)
+    file_roles: list[str] = field(default_factory=list)
+    output_format: str = "human"
+    interactive: bool = True
+
+
+def load_config(paths: AppPaths, env: Mapping[str, str] | None = None) -> Config:
+    config = Config()
+    _apply_toml(config, paths.config_file)
+    _apply_env(config, os.environ if env is None else env)
+    _validate(config)
+    return config
+
+
+def _apply_toml(config: Config, path: Path) -> None:
+    try:
+        with path.open("rb") as fh:
+            data = tomllib.load(fh)
+    except FileNotFoundError:
+        return
+    except tomllib.TOMLDecodeError as exc:
+        raise UsageError(f"Invalid config file {path}: {exc}") from exc
+
+    unknown_top = set(data) - {"defaults"}
+    if unknown_top:
+        raise UsageError(f"Unknown top-level keys in {path}: {', '.join(sorted(unknown_top))}")
+
+    defaults = data.get("defaults", {})
+    if not isinstance(defaults, dict):
+        raise UsageError(f"[defaults] in {path} must be a TOML table")
+
+    unknown = set(defaults) - _KNOWN_DEFAULTS_KEYS
+    if unknown:
+        raise UsageError(f"Unknown config keys in {path}: {', '.join(sorted(unknown))}")
+
+    if "destination" in defaults:
+        config.destination = Path(str(defaults["destination"]))
+    if "downloader" in defaults:
+        config.downloader = str(defaults["downloader"])
+    if "platforms" in defaults:
+        config.platforms = [str(v) for v in defaults["platforms"]]
+    if "languages" in defaults:
+        config.languages = [str(v) for v in defaults["languages"]]
+    if "file_roles" in defaults:
+        config.file_roles = [str(v) for v in defaults["file_roles"]]
+    if "format" in defaults:
+        config.output_format = str(defaults["format"])
+    if "interactive" in defaults:
+        config.interactive = bool(defaults["interactive"])
+
+
+def _apply_env(config: Config, env: Mapping[str, str]) -> None:
+    if dest := env.get("GOG_CLI_DESTINATION"):
+        config.destination = Path(dest)
+    if downloader := env.get("GOG_CLI_DOWNLOADER"):
+        config.downloader = downloader
+    if platforms := env.get("GOG_CLI_PLATFORMS"):
+        config.platforms = [p.strip() for p in platforms.split(",") if p.strip()]
+    if languages := env.get("GOG_CLI_LANGUAGES"):
+        config.languages = [la.strip() for la in languages.split(",") if la.strip()]
+    if roles := env.get("GOG_CLI_FILE_ROLES"):
+        config.file_roles = [r.strip() for r in roles.split(",") if r.strip()]
+    if fmt := env.get("GOG_CLI_FORMAT"):
+        config.output_format = fmt
+    if interactive_val := env.get("GOG_CLI_INTERACTIVE"):
+        config.interactive = _parse_bool(interactive_val, "GOG_CLI_INTERACTIVE")
+
+
+def _parse_bool(value: str, name: str) -> bool:
+    if value.lower() in ("1", "true", "yes"):
+        return True
+    if value.lower() in ("0", "false", "no"):
+        return False
+    raise UsageError(f"Invalid boolean value for {name}: {value!r}")
+
+
+def _validate(config: Config) -> None:
+    if config.downloader not in _VALID_DOWNLOADERS:
+        raise UsageError(
+            f"Invalid downloader {config.downloader!r}."
+            f" Must be one of: {', '.join(sorted(_VALID_DOWNLOADERS))}"
+        )
+    if config.output_format not in _VALID_FORMATS:
+        raise UsageError(
+            f"Invalid format {config.output_format!r}."
+            f" Must be one of: {', '.join(sorted(_VALID_FORMATS))}"
+        )