push_users_xml.py

#!/usr/bin/env python3
"""Hash and push a local Shadow Fight 2 users.xml to a connected phone."""

from __future__ import annotations

import argparse
import os
import subprocess
from datetime import datetime
from pathlib import Path

from dotenv import load_dotenv

from hash_users_xml import (
  DEFAULT_APP_ID,
  DEFAULT_SALT_SUFFIX,
  build_salt,
  compute_users_hash,
)

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 default_hash_path(xml_path: Path) -> Path:
  if xml_path.name == "users.xml":
    return xml_path.with_name("users.xml.hash")
  if xml_path.name == "users_backup.xml":
    return xml_path.with_name("users_backup.xml.hash")
  return xml_path.with_name(xml_path.name + ".hash")


def write_hash(xml_path: Path, salt: str | None) -> Path:
  hash_path = default_hash_path(xml_path)
  digest = compute_users_hash(xml_path, salt, raw_file=False)
  hash_path.write_text(digest, encoding="ascii")
  print(f"Wrote {hash_path}")
  print(f"Hash for {xml_path.name}: {digest}")
  return hash_path


def push_pair(
  package: str,
  xml_path: Path,
  hash_path: Path,
  *,
  backup_xml_path: Path | None,
  backup_hash_path: Path | None,
) -> None:
  run(["adb", "shell", "am", "force-stop", package])
  run(["adb", "push", str(xml_path), adb_path(package, "users.xml")])
  run(["adb", "push", str(hash_path), adb_path(package, "users.xml.hash")])

  if backup_xml_path is not None and backup_hash_path is not None:
    run(["adb", "push", str(backup_xml_path), adb_path(package, "users_backup.xml")])
    run(["adb", "push", str(backup_hash_path), adb_path(package, "users_backup.xml.hash")])


def restore_backup(package: str, backup: Path) -> int:
  backup = backup.resolve()
  required = [
    "users.xml",
    "users.xml.hash",
    "users_backup.xml",
    "users_backup.xml.hash",
  ]
  missing = [name for name in required if not (backup / name).exists()]
  if missing:
    raise SystemExit(f"Backup {backup} is missing: {', '.join(missing)}")

  print(
    "Pushing raw backup bytes to the phone. This skips hash recomputation "
    "and assumes the backup directory contents are trusted."
  )
  run(["adb", "shell", "am", "force-stop", package])
  for filename in required:
    run(["adb", "push", str(backup / filename), adb_path(package, filename)])

  print("Restored backup. Launch the app manually.")
  return 0


def main() -> int:
  load_dotenv()

  parser = argparse.ArgumentParser(
    description=(
      "Compute users.xml.hash for a local users.xml and push both files to "
      "Shadow Fight 2's main and backup save slots."
    )
  )
  parser.add_argument("xml", nargs="?", type=Path, default=Path(".local/saves/users.xml"))
  parser.add_argument("--package", default=DEFAULT_PACKAGE)
  salt_group = parser.add_argument_group("salt")
  salt_group.add_argument(
    "--salt",
    dest="full_salt",
    default=os.environ.get("USER_XML_HASH_SALT"),
    help=(
      "Full second-stage salt. Overrides --device-value, --app-id, and "
      "--salt-suffix. Also read from USER_XML_HASH_SALT."
    ),
  )
  salt_group.add_argument(
    "--device-value",
    default=os.environ.get("USER_XML_HASH_DEVICE_VALUE"),
    help=(
      "Device value of the game install: `and_` plus its "
      "Settings.Secure.ANDROID_ID. Required unless --salt or "
      "USER_XML_HASH_SALT is set. Also read from USER_XML_HASH_DEVICE_VALUE."
    ),
  )
  salt_group.add_argument(
    "--app-id",
    default=os.environ.get("USER_XML_HASH_APP_ID", DEFAULT_APP_ID),
    help=(f"Unity Application.identifier value. Defaults to {DEFAULT_APP_ID}; also read from USER_XML_HASH_APP_ID."),
  )
  salt_group.add_argument(
    "--salt-suffix",
    default=os.environ.get("USER_XML_HASH_SALT_SUFFIX", DEFAULT_SALT_SUFFIX),
    help=(
      "Decoded constant appended after the app id. Defaults to "
      f"{DEFAULT_SALT_SUFFIX!r}; also read from USER_XML_HASH_SALT_SUFFIX."
    ),
  )
  parser.add_argument("--backup-dir", type=Path, default=Path(".local/backups"))
  parser.add_argument("--restore", type=Path, help="Restore a backup directory created by this script.")
  parser.add_argument(
    "--no-pre-push-snapshot",
    action="store_true",
    help="Skip pulling the current phone-side save pair before pushing.",
  )
  parser.add_argument(
    "--no-backup-slot",
    action="store_true",
    help="Push only users.xml/users.xml.hash, not users_backup.*.",
  )
  parser.add_argument(
    "--mirror-main-to-backup",
    action="store_true",
    help="Push users.xml to the backup slot too, ignoring local users_backup.xml.",
  )
  args = parser.parse_args()

  if args.restore is not None:
    return restore_backup(args.package, args.restore)

  xml_path = args.xml.resolve()
  if not xml_path.exists():
    raise SystemExit(f"XML file does not exist: {xml_path}")

  salt = build_salt(
    full_salt=args.full_salt,
    device_value=args.device_value,
    app_id=args.app_id,
    salt_suffix=args.salt_suffix,
  )
  if salt is None:
    raise SystemExit(
      "No device value available. Set USER_XML_HASH_DEVICE_VALUE in .env "
      "(see .env.example) or pass --device-value. Alternatively, set "
      "USER_XML_HASH_SALT or pass --salt to bypass device-value entirely."
    )
  hash_path = write_hash(xml_path, salt)

  backup_xml_path = None
  backup_hash_path = None
  if not args.no_backup_slot:
    candidate_backup_xml = xml_path.with_name("users_backup.xml")
    if args.mirror_main_to_backup or not candidate_backup_xml.exists():
      backup_xml_path = xml_path
      backup_hash_path = hash_path
      print(
        f"Backup slot will mirror {xml_path.name} "
        f"(same content, same hash {hash_path.read_text()})"
      )
    else:
      backup_xml_path = candidate_backup_xml.resolve()
      backup_hash_path = write_hash(backup_xml_path, salt)

  if not args.no_pre_push_snapshot:
    backup_dir = (args.backup_dir / datetime.now().strftime("%Y%m%d-%H%M%S%f")).resolve()
    backup_dir.mkdir(parents=True, exist_ok=True)
    run(["adb", "pull", adb_path(args.package, "users.xml"), str(backup_dir / "users.xml")], check=False)
    run(["adb", "pull", adb_path(args.package, "users.xml.hash"), str(backup_dir / "users.xml.hash")], check=False)
    run(["adb", "pull", adb_path(args.package, "users_backup.xml"), str(backup_dir / "users_backup.xml")], check=False)
    run(["adb", "pull", adb_path(args.package, "users_backup.xml.hash"), str(backup_dir / "users_backup.xml.hash")], check=False)
    print(f"Phone-side backup saved under {backup_dir}")

  push_pair(
    args.package,
    xml_path,
    hash_path,
    backup_xml_path=backup_xml_path,
    backup_hash_path=backup_hash_path,
  )

  print("Done. Launch the app manually.")
  return 0


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