pull_users_xml.py

#!/usr/bin/env python3
"""Pull Shadow Fight 2 save files from a connected Android device."""

from __future__ import annotations

import argparse
import shutil
import subprocess
import sys
from pathlib import Path

from dotenv import load_dotenv

DEFAULT_PACKAGE = "com.nekki.shadowfight"


def run(command: list[str], *, check: bool = True) -> subprocess.CompletedProcess[str]:
  print("+", " ".join(command))
  return subprocess.run(command, check=check, text=True)


def adb_path(package: str, filename: str) -> str:
  return f"/sdcard/Android/data/{package}/files/userdata/{filename}"


def check_adb_available() -> None:
  if shutil.which("adb") is None:
    print(
      "adb not found in PATH. Install Android platform-tools and ensure adb is on $PATH.",
      file=sys.stderr,
    )
    sys.exit(1)


def main() -> int:
  load_dotenv()

  parser = argparse.ArgumentParser(description="Pull Shadow Fight 2 users.xml save files for manual editing.")
  parser.add_argument("--package", default=DEFAULT_PACKAGE)
  parser.add_argument("--out-dir", type=Path, default=Path(".local/saves"))
  args = parser.parse_args()

  check_adb_available()

  out_dir = args.out_dir.resolve()
  out_dir.mkdir(parents=True, exist_ok=True)

  files = [
    "users.xml",
    "users.xml.hash",
    "users_backup.xml",
    "users_backup.xml.hash",
  ]
  existing = [name for name in files if (out_dir / name).exists()]
  if existing:
    print(f"Warning: these local files will be overwritten: {', '.join(existing)}")

  # A save the game has only just created has no backup pair yet, so a missing
  # file is normal rather than a failure. users.xml is the one that must exist.
  pulled = []
  for filename in files:
    result = run(["adb", "pull", adb_path(args.package, filename), str(out_dir / filename)], check=False)
    if result.returncode == 0:
      pulled.append(filename)
    else:
      print(f"Skipped {filename}: not present on the device.")

  if "users.xml" not in pulled:
    print(
      f"Could not pull users.xml. Launch the game once so it writes a save, then retry.",
      file=sys.stderr,
    )
    return 1

  print(f"Pulled save files into {out_dir}: {', '.join(pulled)}")
  print("Edit users.xml, then run: uv run push_users_xml.py")
  return 0


if __name__ == "__main__":
  raise SystemExit(main())