cli.py

Go to the documentation of this file.

"""Command line: argument parsing, save auto-detection, and main()."""
 
import argparse
import glob
import hashlib
import json
import os
import sys
import tempfile
from datetime import datetime, timezone
 
from validators import run_validation
from validators.file_rules import run_file_validation
from validators.text import validation_text, validation_text_file
 
from .bnd4 import checksum_ok, parse_bnd4
from .combine import build_combined, find_saves
from .convert import parse_save, render_markdown
from .edit import set_steam_id, trim_er_slots, trim_inactive_slots
from .jsonout import build_json, parse_meta
 
 
## @brief Folders a Souls save can live in, per OS. Each game keeps its `.sl2` in
#  a game-named subfolder, hence the trailing `*/`. Steam/Proton, Heroic, Lutris,
#  and plain Wine all mirror the Windows `%APPDATA%` tree inside a prefix, so the
#  tail of every glob is the same `.../AppData/Roaming/<game>/*.sl2`.
def _save_globs():
    globs = ["*.sl2", os.path.join("*", "*.sl2")]  # cwd and one level down
    home = os.path.expanduser("~")
    appdata = os.environ.get("APPDATA")
    if appdata:  # native Windows
        globs.append(os.path.join(appdata, "*", "*.sl2"))
        globs.append(os.path.join(appdata, "*", "*", "*.sl2"))
    # Most games write %APPDATA%/<game>/<file>.sl2; Sekiro puts a Steam-id folder in
    # between, so every prefix is searched at both depths.
    roaming = [
        "drive_c/users/steamuser/AppData/Roaming/*/*.sl2",
        "drive_c/users/steamuser/AppData/Roaming/*/*/*.sl2",
    ]
    user_roaming = [
        "drive_c/users/*/AppData/Roaming/*/*.sl2",
        "drive_c/users/*/AppData/Roaming/*/*/*.sl2",
    ]
    # Steam through Proton.
    for steam in (".local/share/Steam", ".steam/steam", ".steam/root"):
        for tail in roaming:
            globs.append(os.path.join(home, steam, "steamapps/compatdata/*/pfx", tail))
    # Heroic (Epic / GOG) Wine prefixes. Heroic names a prefix after the game, so the
    # per-game folder is a wildcard too.
    for heroic in (
        "Games/Heroic/Prefixes/default/*/pfx",
        "Games/Heroic/Prefixes/*/pfx",
        ".config/heroic/prefixes/default/*/pfx",
        "Games/Heroic/*/pfx",
    ):
        for tail in roaming:
            globs.append(os.path.join(home, heroic, tail))
    # Lutris and a plain ~/.wine prefix (user-named, not always "steamuser").
    for tail in user_roaming:
        globs.append(os.path.join(home, ".local/share/lutris/*/pfx", tail))
        globs.append(os.path.join(home, ".wine", tail))
    return globs
 
 
##
# @brief Find a `.sl2` when none was given on the command line.
# @details Globs the current folder and the usual Steam/Proton and Windows save
# locations, and returns the most recently modified match — the live character is
# almost always the newest file. Exits with a clear message if nothing is found.
# @return The path to the chosen save.
def auto_find_save():
    found = []
    for pat in _save_globs():
        found += glob.glob(pat)
    found = sorted(set(found), key=lambda p: os.path.getmtime(p), reverse=True)
    if not found:
        sys.exit(
            "No .sl2 found in the current folder or the usual save locations. "
            "Pass the path explicitly: sl2_to_md.py <save.sl2>"
        )
    if len(found) > 1:
        print(f"Auto-detected {len(found)} saves; using the newest: {found[0]}")
        print("  (pass a path to pick another)")
    else:
        print(f"Auto-detected save: {found[0]}")
    return found[0]
 
 
##
# @brief Program entry point.
# @details Output format follows the -o extension (.json → JSON, anything else →
#  Markdown) unless --format says otherwise, so the common case is one flag, not two.
# @return None. Writes the chosen file and prints where it went.
def main():
    ap = argparse.ArgumentParser(
        description="FromSoftware .sl2 save -> Markdown or JSON playthrough summary "
        "(DS PtDE/Remastered, DS2 vanilla/SOTFS, DS3, Sekiro, Elden Ring)",
        epilog="Metadata example: --meta source=Steam --meta os='Nobara 43' "
        "--meta launcher=Heroic --meta proton='GE-Proton 9-20' "
        "--meta dlc='Ashes of Ariandel' --meta dlc='The Ringed City'. "
        "A key repeated becomes a list. Any key is accepted.",
    )
    ap.add_argument(
        "sl2",
        nargs="*",
        help="path to a .sl2 save, or a FOLDER of them (auto-detected if "
        "omitted). Several paths, or one folder, produce a combined "
        "playthrough document covering every character found.",
    )
    ap.add_argument(
        "-o",
        "--out",
        default="playthrough.md",
        help="output path; a .json extension selects JSON",
    )
    ap.add_argument(
        "--format",
        choices=("auto", "md", "json"),
        default="auto",
        help="output format (default: from the -o extension)",
    )
    ap.add_argument(
        "--meta",
        action="append",
        metavar="KEY=VALUE",
        help="record how the game was run: store, version, DLC, OS, "
        "launcher, Proton build, anything. Repeatable; a repeated "
        "key becomes a list. None of it is read from the save.",
    )
    ap.add_argument(
        "--meta-json",
        metavar="PATH",
        help="JSON object of the same metadata, merged underneath --meta",
    )
    ap.add_argument(
        "--indent",
        type=int,
        default=2,
        help="JSON indent; 0 for one dense line (default: 2)",
    )
    ap.add_argument(
        "--validate",
        action="store_true",
        help="run the validation pass and add its findings to the output: "
        "states an unmodified game could not produce, and internal "
        "contradictions. Off by default, and it never changes what is parsed",
    )
    ap.add_argument(
        "--combined",
        action="store_true",
        help="force the combined document even for a single save",
    )
    ap.add_argument(
        "--set-steam-id",
        metavar="STEAMID64",
        help="write a verified SteamID64 to a NEW .sl2 copy (DS2, DS3, Sekiro)",
    )
    ap.add_argument(
        "--set-username",
        metavar="USERNAME",
        help="always refused: Steam usernames are not stored in .sl2 saves",
    )
    ap.add_argument(
        "--trim-slots",
        metavar="SLOT",
        nargs="+",
        type=int,
        help="write a NEW Elden Ring copy clearing every unselected fixed slot (same file size)",
    )
    ap.add_argument(
        "--trim-inactive",
        action="store_true",
        help="write a NEW Sekiro or Elden Ring copy clearing inactive slots (same file size)",
    )
    ap.add_argument(
        "--archive-manifest",
        nargs="?",
        const="",
        metavar="PATH",
        help="write a JSON archive sidecar; omit PATH only with an archive-copy edit",
    )
    ap.add_argument(
        "--verify-archive",
        action="store_true",
        help="read and verify one save, or every save in the named folder(s)",
    )
    ap.add_argument(
        "--force",
        action="store_true",
        help="allow an archive copy or manifest to replace its existing output",
    )
    args = ap.parse_args()
 
    if args.set_username is not None:
        sys.exit("Steam usernames are not stored in .sl2 saves; nothing was changed.")
    if args.trim_slots is not None and args.trim_inactive:
        sys.exit("Choose either --trim-slots or --trim-inactive.")
    edit_requested = any(
        (args.set_steam_id is not None, args.trim_slots is not None, args.trim_inactive)
    )
    # The db_* folders sit beside the package, not inside it.
    base_dir = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
    if args.verify_archive:
        if edit_requested or args.archive_manifest is not None or args.combined:
            sys.exit(
                "--verify-archive cannot be combined with edit, manifest, or combined mode."
            )
        verify_archive(args.sl2, base_dir)
        return
    if edit_requested and (
        args.combined or len(args.sl2) != 1 or not os.path.isfile(args.sl2[0])
    ):
        sys.exit("An edit needs exactly one existing .sl2 input file.")
    if edit_requested:
        edit_save(args)
        return
 
    try:
        meta = parse_meta(args.meta, args.meta_json)
    except (OSError, ValueError) as exc:
        sys.exit(str(exc))
 
    # A folder, or more than one path, can only mean the combined document — there is
    # no single save to summarise. One file still takes the single-save path unless
    # --combined asks otherwise.
    paths = list(args.sl2)
    files = []
    for p in paths:
        if os.path.isdir(p):
            files += find_saves(p)
        elif os.path.isfile(p):
            files.append(os.path.abspath(p))
        else:
            sys.exit(f"No such file or folder: {p}")
    if paths and not files:
        sys.exit("No .sl2 files found in: " + ", ".join(paths))
 
    if args.combined or len(files) > 1 or any(os.path.isdir(p) for p in paths):
        text = build_combined(files, base_dir, meta)
        if text is None:
            sys.exit("None of those files could be read as a supported save.")
        write_out(args.out, text)
        return
 
    sl2 = files[0] if files else auto_find_save()
    if not os.path.isfile(sl2):
        sys.exit(f"No such file: {sl2}")
    with open(sl2, "rb") as f:
        data = f.read()
 
    if args.archive_manifest is not None:
        if args.archive_manifest == "":
            sys.exit("Pass a manifest path when not creating an archive copy.")
        save = parse_save(data, base_dir)
        write_archive_manifest(args.archive_manifest, sl2, data, save, force=args.force)
        return
 
    fmt = args.format
    if fmt == "auto":
        fmt = "json" if args.out.lower().endswith(".json") else "md"
 
    name = os.path.basename(sl2)
    save = parse_save(data, base_dir)
    warn_foreign_folder(sl2, save)
    if fmt == "json":
        text = json.dumps(
            build_json(save, name, meta, args.validate, data),
            ensure_ascii=False,
            indent=args.indent or None,
        )
        text += "\n"
    else:
        text = render_markdown(save, name, meta, args.validate, data)
 
    write_out(args.out, text)
    if args.validate:
        print_validation(save, data)
 
 
##
# @brief Print each character's validation block to the terminal.
# @details The findings are already in the document; this is so a run that was only
# asking "does this save add up" answers without opening the file. Stdout, one block per
# character, in the shape validators/text.py defines.
# @param save The parsed @ref sl2.convert.SaveData. @param data The file bytes, for
#        the file-level rules.
def print_validation(save, data):
    start = save.cfg["slots"].start
    for i, ch in save.characters:
        label = f"Slot {i - start + 1}" + (f": {ch['name']}" if ch.get("name") else "")
        print()
        print("\n".join(validation_text(run_validation(ch, save.game), label)))
    entries = parse_bnd4(data) or []
    report = run_file_validation(save.game, entries, data, checksum_ok)
    print()
    print("\n".join(validation_text_file(report)))
 
 
##
# @brief Warn when a save is sitting in a folder belonging to a different account.
# @details DS3, Sekiro and Elden Ring write the owning account into the save, and the
# game only reads a save back from the folder named for that account — so a save whose
# account id changed underneath it (a Steam emulator reconfigured, a different profile)
# will not load, and the game says nothing useful about why. Comparing the two is free
# once both are known.
# @note Deliberately printed to STDERR and never into the document: the browser cannot
# see a dropped file's folder, and the two front ends have to stay byte-identical.
# @param path The save file's path. @param save The parsed @ref sl2.convert.SaveData.
def warn_foreign_folder(path, save):
    if save.folder is None:
        return
    here = os.path.basename(os.path.dirname(os.path.abspath(path)))
    # Only complain when the folder is clearly one of the game's own account folders:
    # same width as the real thing and made of the right digits. A save copied into a
    # working directory is not a mismatch, it is just somewhere else — and the width
    # test is what stops an ordinary folder that happens to spell hex ("beef", "decade")
    # from being read as somebody's account.
    if not here or here.lower() == save.folder.lower() or len(here) != len(save.folder):
        return
    if not all(c in "0123456789abcdefABCDEF" for c in here):
        return
    print(
        f"Warning: this save was written by Steam account {save.owner[0]} and the "
        f"game will only load it from a folder named '{save.folder}', but it is in "
        f"'{here}'. Under the account that owns '{here}' the game will not see it.",
        file=sys.stderr,
    )
 
 
## @brief Write the document, making the output folder if it does not exist yet.
def write_out(path, text):
    out_dir = os.path.dirname(os.path.abspath(path))
    if out_dir and not os.path.isdir(out_dir):
        os.makedirs(out_dir, exist_ok=True)
    with open(path, "w", encoding="utf-8") as f:
        f.write(text)
    print(f"Wrote {path}")
 
 
## @brief Apply one or both copy-only edits and atomically create the requested .sl2.
def edit_save(args):
    source = os.path.abspath(args.sl2[0])
    output = os.path.abspath(args.out)
    if not output.lower().endswith(".sl2"):
        sys.exit("An edited save needs an explicit .sl2 --out path.")
    if os.path.realpath(source) == os.path.realpath(output):
        sys.exit("Refusing to overwrite the input save; choose a different --out path.")
    if os.path.exists(output) and not args.force:
        sys.exit("Output already exists; choose another path or pass --force.")
    if args.archive_manifest is not None:
        manifest = archive_manifest_path(args.archive_manifest, output)
        if os.path.exists(manifest) and not args.force:
            sys.exit("Manifest already exists; choose another path or pass --force.")
    with open(source, "rb") as f:
        data = f.read()
    original = data
    try:
        if args.set_steam_id is not None:
            data = set_steam_id(data, args.set_steam_id)
        if args.trim_slots is not None:
            data = trim_er_slots(data, args.trim_slots)
        if args.trim_inactive:
            data = trim_inactive_slots(data)
        base_dir = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
        checked = parse_save(data, base_dir)
    except (ValueError, SystemExit) as exc:
        sys.exit(str(exc))
    folder = os.path.dirname(output) or os.curdir
    os.makedirs(folder, exist_ok=True)
    fd, temporary = tempfile.mkstemp(prefix=".sl2-analyzer-", suffix=".tmp", dir=folder)
    try:
        with os.fdopen(fd, "wb") as f:
            f.write(data)
            f.flush()
            os.fsync(f.fileno())
        os.replace(temporary, output)
    except OSError:
        try:
            os.unlink(temporary)
        except OSError:
            pass
        raise
    print(f"Wrote verified archive copy {args.out}")
    if args.set_steam_id is not None and checked.folder is not None:
        print(f"Place it in the Steam folder named {checked.folder}.")
    if args.archive_manifest is not None:
        operations = []
        if args.set_steam_id is not None:
            operations.append({"set_steam_id": checked.owner[1]})
        if args.trim_slots is not None:
            operations.append({"trim_slots": sorted(set(args.trim_slots))})
        if args.trim_inactive:
            operations.append({"trim_inactive": True})
        write_archive_manifest(
            args.archive_manifest,
            output,
            data,
            checked,
            source=(source, original),
            operations=operations,
            force=args.force,
        )
 
 
## @brief Write a small, auditable sidecar describing one parsed archive copy.
def write_archive_manifest(
    option, archive, data, save, source=None, operations=None, force=False
):
    path = archive_manifest_path(option, archive)
    if os.path.exists(path) and not force:
        sys.exit("Manifest already exists; choose another path or pass --force.")
    slots = []
    for index, ch in save.characters:
        row = {"slot": index - save.cfg["slots"].start + 1}
        for key in ("name", "level"):
            if ch.get(key) is not None:
                row[key] = ch[key]
        slots.append(row)
    manifest = {
        "format": "sl2-analyzer archive manifest",
        "version": 1,
        "created_utc": datetime.now(timezone.utc).isoformat(),
        "archive": {
            "name": os.path.basename(archive),
            "bytes": len(data),
            "sha256": hashlib.sha256(data).hexdigest(),
        },
        "game": save.game,
        "steam_id64": save.owner[1] if save.owner else None,
        "slots": slots,
        "operations": operations or [],
    }
    if source is not None:
        manifest["source"] = {
            "name": os.path.basename(source[0]),
            "sha256": hashlib.sha256(source[1]).hexdigest(),
        }
    folder = os.path.dirname(path) or os.curdir
    os.makedirs(folder, exist_ok=True)
    fd, temporary = tempfile.mkstemp(prefix=".sl2-analyzer-", suffix=".tmp", dir=folder)
    try:
        with os.fdopen(fd, "w", encoding="utf-8") as f:
            json.dump(manifest, f, ensure_ascii=False, indent=2)
            f.write("\n")
            f.flush()
            os.fsync(f.fileno())
        os.replace(temporary, path)
    except OSError:
        try:
            os.unlink(temporary)
        except OSError:
            pass
        raise
    print(f"Wrote archive manifest {path}")
 
 
## @brief Resolve an explicit archive sidecar path, or the archive's default neighbor.
def archive_manifest_path(option, archive):
    return archive + ".archive.json" if option == "" else os.path.abspath(option)
 
 
## @brief Read every named archive and report BND4, parse, and ownership status.
def verify_archive(paths, base_dir):
    files = []
    for path in paths or [auto_find_save()]:
        if os.path.isdir(path):
            files += find_saves(path)
        elif os.path.isfile(path):
            files.append(os.path.abspath(path))
        else:
            sys.exit(f"No such file or folder: {path}")
    if not files:
        sys.exit("No .sl2 files found to verify.")
    failures = []
    for path in sorted(set(files)):
        try:
            with open(path, "rb") as f:
                data = f.read()
            entries = parse_bnd4(data)
            bad = [str(e.index) for e in entries if not checksum_ok(data, e)]
            if bad:
                raise ValueError("bad checksum(s): " + ", ".join(bad))
            save = parse_save(data, base_dir)
            warn_foreign_folder(path, save)
        except (OSError, ValueError, SystemExit) as exc:
            failures.append(f"FAIL {path}: {exc}")
            continue
        print(
            f"OK {path}: {save.cfg['title']}, {len(save.characters)} slot(s), sha256 {hashlib.sha256(data).hexdigest()}"
        )
    if failures:
        print("\n".join(failures), file=sys.stderr)
        sys.exit(f"Archive verification failed for {len(failures)} file(s).")