Skip to content

Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.

5.3 KB
Raw Blame
# SPDX-License-Identifier: Apache-2.0
"""One preferences file; read-only queries, atomic compare-and-swap writes.

Version 2 holds the per-journey `profiles` and the `general` settings every profile shares
(`catalog.GENERAL_FIELDS`); a version 1 file (profiles only) reads with no general settings and is
written as version 2 by the next save."""
from __future__ import annotations

import argparse
import hashlib
import json
import os
from pathlib import Path

from sprite_gen.spec.runio import atomic_write_text, publish_guard
from .catalog import FIELDS, FLOWS, GENERAL_FIELDS, validate_choices, validate_general

VERSION = 2


def settings_path() -> Path:
    configured = os.environ.get("SPRITE_GEN_CONFIG_DIR")
    if configured is not None and not configured.strip():
        raise ValueError("SPRITE_GEN_CONFIG_DIR is empty")
    root = Path(configured).expanduser() if configured is not None else Path.home() / ".config" / "sprite-gen"
    return root / "preferences.json"


def read_settings() -> dict:
    path = settings_path()
    try:
        raw = path.read_bytes()
    except FileNotFoundError:
        return {"path": str(path), "revision": "missing", "profiles": {}, "general": {}}
    try:
        data = json.loads(raw)
        shapes = {1: {"version", "profiles"}, VERSION: {"version", "profiles", "general"}}
        if (not isinstance(data, dict) or type(data.get("version")) is not int
                or shapes.get(data["version"]) != set(data)):
            raise ValueError(f"expected preferences version 1 or {VERSION}")
        if not isinstance(data["profiles"], dict):
            raise ValueError("profiles must be an object")
        for kind, choices in data["profiles"].items():
            validate_choices(kind, choices)
        general = validate_general(data.get("general", {}))
    except (ValueError, TypeError) as exc:
        raise ValueError(f"invalid preferences at {path}: {exc}; repair or explicitly remove the file") from exc
    return {"path": str(path), "revision": hashlib.sha256(raw).hexdigest(), "profiles": data["profiles"],
            "general": general}


def save_settings(kind: str | None, choices: dict, *, expected_revision: str, clear: bool = False,
                  general: dict | None = None) -> dict:
    """Only explicit user-approved calls write. First matching revision wins a race. `kind` and `choices` save or
    `clear` one profile; `general` saves settings every profile shares (no `kind` needed for those alone)."""
    general = validate_general(general or {})
    if kind is not None or choices or clear:
        choices = validate_choices(kind, choices)
    if not expected_revision:
        raise ValueError("expected_revision is required; read current settings first")
    if not clear and not choices and not general:
        raise ValueError("provide at least one default to save")
    path = settings_path()
    path.parent.mkdir(parents=True, exist_ok=True)
    # Reuse the package's cross-platform lock backend. The stable sidecar is for
    # this file (not the replaceable JSON inode); atomic replace keeps reads pure.
    with publish_guard(path):
        before = read_settings()
        if before["revision"] != expected_revision:
            raise ValueError("preferences changed since they were read; read again and reconfirm the intended change")
        profiles = before["profiles"]
        if clear:
            profiles.pop(kind, None)
        elif choices:
            profiles[kind] = {**profiles.get(kind, {}), **choices}
        payload = json.dumps({"version": VERSION, "profiles": profiles, "general": {**before["general"], **general}},
                             ensure_ascii=False, sort_keys=True, indent=2) + "\n"
        if not path.exists() or path.read_text(encoding="utf-8") != payload:
            atomic_write_text(path, payload)
        return read_settings()


def add_arguments(parser: argparse.ArgumentParser) -> None:
    parser.add_argument("action", choices=("show", "save", "clear"))
    parser.add_argument("--kind", choices=FLOWS)
    parser.add_argument("--expected-revision")
    for key, field in FIELDS.items():
        parser.add_argument("--" + key.replace("_", "-"), choices=field["options"])
    for key, field in GENERAL_FIELDS.items():
        parser.add_argument("--" + key.replace("_", "-"), choices=field["options"], help="shared by every profile; "
                            "saved without --kind")


def run(**kwargs) -> int:
    args = argparse.Namespace(**kwargs)
    choices = {key: getattr(args, key, None) for key in FIELDS if getattr(args, key, None) is not None}
    general = {key: getattr(args, key, None) for key in GENERAL_FIELDS if getattr(args, key, None) is not None}
    try:
        if args.action == "show":
            if choices or general or args.kind or args.expected_revision:
                raise ValueError("show accepts no mutation arguments")
            result = read_settings()
        else:
            if args.action == "clear" and (choices or general):
                raise ValueError("clear does not accept choices")
            result = save_settings(args.kind, choices, expected_revision=args.expected_revision,
                                   clear=args.action == "clear", general=general)
    except (ValueError, OSError) as exc:
        raise SystemExit(f"defaults: {exc}") from exc
    print(json.dumps(result, ensure_ascii=False, indent=2))
    return 0