rpgsync 0.1.0__py3-none-any.whl

rpgsync/cli.py

@@ -0,0 +1,1242 @@
+"""Command line interface.
+
+cd /path/to/MyGame
+rpgsync                # keep game and scripts in sync (live); sets the scripts up the first time
+rpgsync status         # what is pending, on which side
+rpgsync pull           # game -> scripts
+rpgsync push           # scripts -> game
+rpgsync check          # compile, engine and type checks, without writing
+rpgsync clean          # delete the backups of overwritten files
+rpgsync locate --map 1 --event 2 --command 3   # FILE:LINE where a script writes it (for editors)
+rpgsync locate --troop 4 --page 1               # ... or a troop's battle event page
+
+Every command works on the game of the current folder (the folder holding
+RPG_RT.ldb, its Scripts folder, or any folder inside them), or on the game
+or scripts folder given as argument.
+
+With the RPG Maker 2000/2003 editor: rpgsync pull, edit the Python files,
+rpgsync push, then open the editor and keep editing there. Keep the editor
+closed while you edit the Python files: it keeps its own copy of the game in
+memory and ignores them.
+
+With the EasyRPG Editor (https://github.com/oulianov/Editor): turn on its
+rpgsync mode (Settings). It reloads what changes on disk and shows it as well
+as it can, so both can stay open while rpgsync runs.
+"""
+
+from __future__ import annotations
+
+import difflib
+import io
+import os
+import re
+import shutil
+import subprocess
+import sys
+import time
+import tomllib
+from collections.abc import Iterator
+from pathlib import Path
+from typing import Annotated, Any
+
+import typer
+from pydantic import BaseModel
+from rich.console import Console
+from rich.progress import BarColumn, MofNCompleteColumn, Progress, TextColumn, TimeElapsedColumn
+from rich.text import Text
+
+from . import dynrpg, scriptfiles
+from .commands import TableSize
+from .compat import check_specs, check_warnings, load_rules, target_engine
+from .maptree import StartSpec, TreeOrder, map_reference_problems, map_tree_maps, tree_problems
+from .project import Project
+from .resources import Collector
+from .resources import key as resource_key
+from .resources import problems as resource_problems
+from .scaffold import init_scripts_project, update_scripts_project
+from .script import (
+    CompileError,
+    compile_common_events_source,
+    compile_map_source,
+    compile_troop_events_source,
+    unreachable_pages,
+)
+from .sync import Result, ScriptError, Syncer, Unit, read_bytes, sha
+from .venv import repair as repair_venv
+
+EDITORS_HELP = (
+    "With the RPG Maker 2000/2003 editor: [bold]rpgsync pull[/bold], edit the Python files, "
+    "[bold]rpgsync push[/bold], then open the editor and keep editing there. "
+    "Keep the editor closed while you edit the Python files: it keeps its own copy "
+    "of the game in memory and ignores your Python edits.\n\n"
+    "With the EasyRPG Editor (https://github.com/oulianov/Editor): make sure its "
+    "[bold]rpgsync mode[/bold] is on (Settings). It reloads the changes made on disk "
+    "and shows them as well as it can, so it can stay open while rpgsync runs."
+)
+
+app = typer.Typer(
+    help="A python twin of your RPG Maker 2000/2003 game.",
+    epilog=EDITORS_HELP,
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+ProjectArg = Annotated[
+    str | None,
+    typer.Argument(
+        help="The game folder (with RPG_RT.ldb) or its scripts folder [default: the current folder].",
+        show_default=False,
+    ),
+]
+MapOpt = Annotated[list[int] | None, typer.Option("--map", help="Only this map id (repeatable).")]
+NoCommonOpt = Annotated[bool, typer.Option("--no-common", help="Skip database/common_events.py.")]
+YesOpt = Annotated[bool, typer.Option("--yes", "-y", help="First run: set the game up without asking.")]
+
+ENGINES = {"2k": "RPG Maker 2000", "2k3": "RPG Maker 2003"}
+
+
+# --------------------------------------------------------------------------
+# Output
+# --------------------------------------------------------------------------
+
+# one marker at the start of a line: an emoji, or plain ASCII where the
+# console cannot show emojis (Windows cmd.exe with cp437/cp850/cp1252...)
+MARKERS = {
+    "ok": ("\u2705", "[ok]"),  # check mark
+    "script": ("\U0001f40d", "[s]"),  # snake: a Python script was written / changed
+    "game": ("\U0001f5d2\ufe0f", "[g]"),  # spiral notepad: a game file was written / changed
+    "merge": ("\U0001f500", "[~]"),  # twisted arrows
+    "conflict": ("\u26a0\ufe0f", "[!]"),  # warning
+    "warning": ("\u26a0\ufe0f", "[!]"),
+    "error": ("\u274c", "[x]"),  # cross mark
+    "info": ("\u2139\ufe0f", "[i]"),  # information
+    "watch": ("\U0001f501", "[*]"),  # repeat: watching
+    "new": ("\u2728", "[+]"),  # sparkles
+    "file": ("\U0001f4c4", "[+]"),  # page
+    "delete": ("\U0001f5d1\ufe0f", "[-]"),  # wastebasket
+    "stop": ("\U0001f44b", "[.]"),  # waving hand
+}
+
+# shown the first time rpgsync runs on a game: colored block letters (ANSI escapes,
+# parsed by rich, so they go away with NO_COLOR or when the output is not a terminal)
+BANNER = [
+    "\x1b[0;91;41m░▒▒\x1b[0;31m▄\x1b[0;33m▓▄\x1b[0;37m \x1b[0;91;41m░▒▒░\x1b[0;33m▓▄\x1b[0;37m \x1b[0;31m▄\x1b[0;91;41m▒▓\x1b[0;91m█\x1b[0;91;41m▒░\x1b[0;37m \x1b[0;31m▄\x1b[0;91;41m▄▀▄\x1b[0;31m▄\x1b[0;37m  \x1b[0;31m█\x1b[0;91;41m▒\x1b[0;31m▌▐\x1b[0;91;41m▒░\x1b[0;37m \x1b[0;91;41m░▒▒░\x1b[0;33m▓▄\x1b[0;37m \x1b[0;31m▄\x1b[0;91;41m▄▀▄\x1b[0;31m▄\x1b[0;37m \x1b[0m",
+    "\x1b[0;33m▓\x1b[0;91;41m░\x1b[0;31m▌▐\x1b[0;33;41m▓\x1b[0;33m▓\x1b[0;37m \x1b[0;33m▓\x1b[0;91;41m░\x1b[0;31m▌▐\x1b[0;33;41m▓\x1b[0;33m▓\x1b[0;37m \x1b[0;91;41m▓\x1b[0;91;43m▓\x1b[0;31m▌▐\x1b[0;91;41m░\x1b[0;33m█\x1b[0;37m \x1b[0;91;41m▒▓\x1b[0;31m▌▐\x1b[0;91;41m▓▄\x1b[0;37m \x1b[0;91;41m▓\x1b[0;91;43m▓\x1b[0;31m▌▐\x1b[0;91;41m░\x1b[0;33m█\x1b[0;37m \x1b[0;33m▓\x1b[0;91;41m░\x1b[0;31m▌▐\x1b[0;33;41m▓\x1b[0;33m▓\x1b[0;37m \x1b[0;91;41m▒▓\x1b[0;31m▌▐\x1b[0;91;41m▓▄\x1b[0m",
+    "\x1b[0;33m▒▒\x1b[0;31m▌\x1b[0;37m    \x1b[0;33m▒▒\x1b[0;31m▌▐\x1b[0;33m▓▓\x1b[0;37m \x1b[0;33m▓\x1b[0;91;41m░\x1b[0;31m▌▐\x1b[0;33m▓▓\x1b[0;37m \x1b[0;31m▀\x1b[0;91m▀\x1b[0;91;41m▀\x1b[0;91m▄▄\x1b[0;31m▄\x1b[0;37m \x1b[0;33m▓\x1b[0;91;41m░\x1b[0;31m▌▐\x1b[0;33m▓▓\x1b[0;37m \x1b[0;33m▒▒\x1b[0;31m▌▐\x1b[0;33m▓▓\x1b[0;37m \x1b[0;91;41m░▒\x1b[0;31m▌\x1b[0;37m   \x1b[0m",
+    "\x1b[0;33m░░\x1b[0;31m▌\x1b[0;37m    \x1b[0;33m░░\x1b[0;31m▌▐\x1b[0;33m▒▒\x1b[0;37m \x1b[0;33m░▒\x1b[0;31m▌▐\x1b[0;33m▒▒\x1b[0;37m \x1b[0;33m▓\x1b[0;91;41m░\x1b[0;31m▌▐\x1b[0;91;41m░\x1b[0;33m█\x1b[0;37m \x1b[0;33m░▒\x1b[0;31m▌▐\x1b[0;33m▒▒\x1b[0;37m \x1b[0;33m░░\x1b[0;31m▌▐\x1b[0;33m▒▒\x1b[0;37m \x1b[0;33m▓\x1b[0;91;41m░\x1b[0;31m▌▐\x1b[0;91;41m░\x1b[0;33m█\x1b[0m",
+    "\x1b[0;90m░▒▌\x1b[0;37m    \x1b[0;90m▓▓▌██▀\x1b[0;37m  \x1b[0;90m▀▀▐██\x1b[0;37m \x1b[0;31m▀█\x1b[0;90;41m░▓▒\x1b[0;90m▀\x1b[0;37m  \x1b[0;90m▀▀▐██\x1b[0;37m \x1b[0;90m░▒▌▐██\x1b[0;37m  \x1b[0;31m▀\x1b[0;90;41m░▓▒\x1b[0;90m▀\x1b[0m",
+    "\x1b[0;37m       \x1b[0;90m▒▓\x1b[0;37m     \x1b[0;90m▒█▄█▓▀\x1b[0;37m        \x1b[0;90m▒█▄█▓▀\x1b[0;37m              \x1b[0m",
+]
+
+REPOSITORY = "https://github.com/oulianov/rpgsync"
+
+# file names in sync messages, shown in cyan
+FILE_NAMES = r"[\w./\\-]+\.(?:py|lmu|ldb)\b"
+
+
+def _never_fail(stream) -> None:
+    """Characters the console cannot show become "?" instead of raising UnicodeEncodeError."""
+    try:
+        if getattr(stream, "errors", "replace") == "strict":
+            stream.reconfigure(errors="replace")
+    except (AttributeError, ValueError, io.UnsupportedOperation):
+        pass
+
+
+def _emoji_ok(console: Console) -> bool:
+    """Emojis need a UTF-8 output and a terminal font that has them."""
+    if os.environ.get("RPGSYNC_ASCII"):
+        return False
+    encoding = (console.encoding or "").lower().replace("-", "").replace("_", "")
+    if not encoding.startswith("utf") or console.legacy_windows:
+        return False
+    if sys.platform == "win32":
+        # Python writes UTF-8 to every Windows console, but the classic console
+        # (cmd.exe, PowerShell window) shows emojis as boxes: only trust Windows
+        # Terminal and the VS Code terminal
+        return bool(os.environ.get("WT_SESSION") or os.environ.get("TERM_PROGRAM"))
+    return True
+
+
+class UI:
+    """rich output on stdout or stderr: colors on a terminal (unless NO_COLOR is set),
+    emojis only where the output encoding can show them."""
+
+    def __init__(self, err: bool = False):
+        _never_fail(sys.stderr if err else sys.stdout)
+        # markup/emoji off: paths and game texts may contain "[...]" or ":name:"
+        self.console = Console(stderr=err, highlight=False, soft_wrap=True, markup=False, emoji=False)
+        self.fancy = _emoji_ok(self.console)
+
+    def marker(self, kind: str) -> str:
+        emoji, ascii_marker = MARKERS[kind]
+        return (emoji if self.fancy else ascii_marker) + " "
+
+    def print(self, *parts: str | Text | tuple[str, str], kind: str | None = None) -> None:
+        """One line made of strings, Texts or (text, style) pairs, after an optional marker."""
+        t = Text(self.marker(kind)) if kind else Text()
+        for part in parts:
+            if isinstance(part, Text):
+                t.append_text(part)
+            elif isinstance(part, tuple):
+                t.append(*part)
+            else:
+                t.append(part)
+        self.console.print(t)
+
+    def echo(self, line: str) -> None:
+        self.console.print(Text(line))
+
+    def bullet(self, *parts: str | Text | tuple[str, str]) -> None:
+        self.print("  \u2022 " if self.fancy else "  - ", *parts)
+
+    def banner(self) -> None:
+        """The rpgsync title, one color per line, and what it does."""
+        self.echo("")
+        for line in BANNER:
+            self.console.print(Text.from_ansi(line))
+        self.print(("a Python twin of your RPG Maker 2000/2003 game", "italic dim"))
+        self.print(
+            (REPOSITORY, "underline cyan"),
+            (" \u00b7 " if self.fancy else " - ", "dim"),
+            ("MIT License, 2026", "dim"),
+        )
+        self.echo("")
+
+    def report(self, r: Result) -> None:
+        """A sync result as a log line: marker, time, unit, message, duration."""
+        if r.action == "none" and not r.message:
+            return
+        kind = {"export": "script", "import": "game", "merge": "merge", "conflict": "conflict", "error": "error"}
+        style = {"error": "red", "conflict": "yellow"}.get(r.action, "")
+        first, _, rest = (r.message or r.action).partition("\n")
+        msg = Text(first, style)
+        msg.highlight_regex(FILE_NAMES, "cyan")
+        parts: list = [("[%s] " % time.strftime("%H:%M:%S"), "dim"), (r.unit, "bold"), ": ", msg]
+        if r.seconds is not None and r.action != "none":
+            parts.append((" (%.2f s)" % r.seconds, "dim"))
+        if rest:
+            parts.append(("\n" + rest, style))
+        self.print(*parts, kind=kind.get(r.action, "info"))
+
+
+class CliSyncer(Syncer):
+    """A Syncer reporting through rich."""
+
+    def __init__(self, project: Project):
+        self.ui = UI()
+        super().__init__(project, log=self.ui.echo)
+
+    def report(self, r: Result) -> None:
+        self.ui.report(r)
+
+
+def _fail(message: str, code: int = 2) -> typer.Exit:
+    UI(err=True).print(("Error: %s" % message, "red"), kind="error")
+    return typer.Exit(code)
+
+
+# --------------------------------------------------------------------------
+# Finding the project
+# --------------------------------------------------------------------------
+
+
+class ProjectNotFound(Exception):
+    pass
+
+
+class Located(BaseModel):
+    game: str
+    scripts: str | None = None
+
+
+def _find(where: Path) -> Located | None:
+    """The game folder (RPG_RT.ldb) or scripts folder (pyproject.toml with
+    [tool.rpgsync] game = "...") containing `where`; the nearest one wins."""
+    for d in (where, *where.parents):
+        if (d / "RPG_RT.ldb").is_file():
+            return Located(game=str(d))
+        pyproject = d / "pyproject.toml"
+        if pyproject.is_file():
+            try:
+                game = tomllib.loads(pyproject.read_text(encoding="utf-8")).get("tool", {}).get("rpgsync", {})
+                game = game.get("game")
+            except (OSError, ValueError, AttributeError):
+                continue
+            if isinstance(game, str) and (d / game / "RPG_RT.ldb").is_file():
+                return Located(game=str((d / game).resolve()), scripts=str(d))
+    return None
+
+
+def _locate(project: str | None) -> Located:
+    """The project of a folder (default: the current one)."""
+    if project is not None and not os.path.isdir(project):
+        raise typer.BadParameter("%s is not a folder" % project)
+    where = Path(project if project is not None else os.getcwd()).resolve()
+    found = _find(where)
+    if found is None:
+        raise ProjectNotFound(
+            "no RPG Maker game at %s: neither it nor a parent folder holds RPG_RT.ldb or a scripts folder "
+            "(pyproject.toml with [tool.rpgsync]).\nRun rpgsync inside your game folder, or pass its path." % where
+        )
+    return found
+
+
+def _open(project: str | None) -> CliSyncer:
+    try:
+        loc = _locate(project)
+    except ProjectNotFound as e:
+        raise _fail(str(e)) from None
+    project = Project(loc.game, loc.scripts)
+    # a game folder copied or renamed: its scripts' commands still run the old one's
+    old = repair_venv(project.script_dir)
+    if old:
+        UI(err=True).print("repaired the scripts' Python environment, made in %s" % old, kind="info")
+    # files that an older rpgsync did not write; uv.lock and .venv follow pyproject.toml
+    if str(Path(project.script_dir) / "pyproject.toml") in update_scripts_project(project):
+        _uv_sync(project.script_dir, UI(err=True))
+    return CliSyncer(project)
+
+
+def _uv_sync(script_dir: str, ui: UI) -> None:
+    """Install the scripts' Python environment, when uv is there."""
+    if shutil.which("uv"):
+        with ui.console.status("Installing the scripts' Python environment (uv sync)..."):
+            subprocess.run(["uv", "sync", "--quiet"], cwd=script_dir, check=False)
+
+
+def _interactive() -> bool:
+    """Can we ask a question (a terminal on stdin)?"""
+    return sys.stdin.isatty()
+
+
+def _needs_set_up(syncer: CliSyncer) -> bool:
+    return not os.path.exists(os.path.join(syncer.project.script_dir, "pyproject.toml"))
+
+
+def _set_up(syncer: CliSyncer, yes: bool) -> None:
+    """First run on a game: say what will happen, ask, then make its scripts folder
+    a small Python project (pyproject.toml, tests, editor settings) installed with uv."""
+    ui, project = syncer.ui, syncer.project
+    maps = sum(u.kind == "map" for u in syncer.units())
+    engine = ENGINES.get(project.context().engine, project.context().engine)
+    scripts = os.path.relpath(project.script_dir, os.path.dirname(project.game_dir))
+    ui.banner()
+    ui.print(
+        (os.path.basename(project.game_dir), "bold bright_white"),
+        (" (%s, %d maps)" % (engine, maps), "dim"),
+        " is not synced with rpgsync yet.",
+        kind="info",
+    )
+    ui.print(("Setting it up will:", "bold"))
+    ui.bullet(
+        ("create ", "bold green"),
+        (scripts, "cyan"),
+        ": your maps, database and common events as Python scripts, with tests",
+    )
+    ui.bullet(("install ", "bold green"), "the scripts' Python environment with ", ("uv", "cyan"))
+    ui.bullet(("leave the game files as they are", "bold yellow"), ": only your edits to the scripts are written back")
+    if not yes:
+        if not _interactive():
+            raise _fail("not set up: run again with -y to set this game up")
+        question = "Set up rpgsync for this game?"
+        if ui.console.color_system is not None:
+            question = typer.style(question, bold=True)
+        if not typer.confirm(question, default=True):
+            raise typer.Exit(1)
+    ui.echo("")
+    written = init_scripts_project(project)
+    ui.print(
+        "created %s (%s)" % (scripts, ", ".join(os.path.relpath(p, project.script_dir) for p in written)),
+        kind="file",
+    )
+    _uv_sync(project.script_dir, ui)
+    ui.echo("")
+
+
+def _units(syncer: Syncer, maps: list[int] | None, no_common: bool) -> Iterator[Unit]:
+    for u in syncer.units():
+        if u.kind == "common" and no_common:
+            continue
+        if maps and (u.kind != "map" or u.map_id not in maps):
+            continue
+        yield u
+
+
+def _sync_all(
+    syncer: CliSyncer, units: list[Unit], prefer: str | None, initial: bool = False, force: bool = False
+) -> int:
+    """Sync units under a progress bar; return how many failed.  initial: the first
+    export of a new project, summed up in one line instead of one line per script."""
+    ui = syncer.ui
+    failed = unchanged = reported = written = 0
+    begin = time.perf_counter()
+    columns = (
+        TextColumn("{task.description}"),
+        BarColumn(),
+        MofNCompleteColumn(),
+        TextColumn("{task.fields[unit]}"),
+        TimeElapsedColumn(),
+    )
+    title = "Initial sync (game -> scripts)" if initial else "Syncing"
+    # the initial sync's bar stays on screen; later ones vanish once done
+    with Progress(*columns, console=ui.console, transient=not initial, disable=not ui.console.is_terminal) as progress:
+        task = progress.add_task(title, total=len(units), unit="")
+        for u in units:
+            progress.update(task, unit=u.name)
+            start = time.perf_counter()
+            r = syncer.sync(u, prefer, force)
+            r.seconds = time.perf_counter() - start
+            progress.advance(task)
+            if r.action in ("export", "import") and r.message.endswith(": no changes"):
+                unchanged += 1  # rewritten identically: one summary line for all of them
+                continue
+            if initial and r.action == "export":
+                written += 1
+                continue
+            syncer.report(r)
+            reported += r.action != "none" or bool(r.message)  # a line printed
+            failed += r.action in ("error", "conflict")
+    if initial:
+        took = time.perf_counter() - begin
+        if ui.console.is_terminal:
+            ui.echo("")  # after the bar
+        ui.print(
+            ("Initial sync done: ", "bold green"),
+            "%d scripts written in %s" % (written, _duration(took)),
+            kind="ok",
+        )
+    if unchanged:
+        files = "%d %sfile%s" % (unchanged, "other " if reported else "", "s" * (unchanged > 1))
+        ui.print(("%s already up to date" % files, "dim"))
+    elif prefer == "script" and not reported:
+        ui.print(("Nothing to push: no script or game file changed since the last sync", "dim"))
+    return failed
+
+
+def _duration(seconds: float) -> str:
+    return "%.1f s" % seconds if seconds < 60 else "%d min %02d s" % divmod(round(seconds), 60)
+
+
+def _run(syncer: CliSyncer, units, prefer: str | None, initial: bool = False, force: bool = False) -> None:
+    if _sync_all(syncer, list(units), prefer, initial, force):
+        raise typer.Exit(1)
+
+
+# --------------------------------------------------------------------------
+# Status helpers
+# --------------------------------------------------------------------------
+
+Part = tuple[str, str]  # (text, rich style)
+
+PLURAL = {"event": "events", "common event": "common events", "troop": "troops", "map": "maps", "entry": "entries"}
+
+
+def _ids(ids: list[int], limit: int = 8) -> str:
+    """1, 2, 3, 5 -> "1-3, 5"; long lists are cut."""
+    runs: list[list[int]] = []
+    for i in ids:
+        if runs and i == runs[-1][1] + 1:
+            runs[-1][1] = i
+        else:
+            runs.append([i, i])
+    out = [str(a) if a == b else "%d-%d" % (a, b) for a, b in runs]
+    if len(out) > limit:
+        out = out[:limit] + ["... (%d in all)" % len(ids)]
+    return ", ".join(out)
+
+
+def _entry_diff(old: list, new: list, what: str) -> list[Part]:
+    """Per-entry difference between two spec lists: what changed from old to new."""
+    a = {s.id: s for s in old if s.id is not None}
+    b = {s.id: s for s in new if s.id is not None}
+    parts: list[Part] = []
+    pa, pb = a.get(0), b.get(0)  # pseudo-entry 0: the table's size, or the map tree's order
+    if isinstance(pa, TableSize) and isinstance(pb, TableSize) and pa.size != pb.size:
+        parts.append(("size %d -> %d" % (pa.size, pb.size), "yellow"))
+    for label, ids, style in (
+        ("changed", sorted(i for i in a.keys() & b.keys() if i > 0 and a[i].key() != b[i].key()), "yellow"),
+        ("added", sorted(i for i in b.keys() - a.keys() if i > 0), "green"),
+        ("removed", sorted(i for i in a.keys() - b.keys() if i > 0), "red"),
+    ):
+        if ids:
+            parts.append(("%s %s %s" % (PLURAL[what] if len(ids) > 1 else what, _ids(ids), label), style))
+    if isinstance(pa, TreeOrder) and isinstance(pb, TreeOrder):
+        both = set(pa.order) & set(pb.order)  # maps added or removed are listed above
+        if [m for m in pa.order if m in both] != [m for m in pb.order if m in both]:
+            parts.append(("new tree order", "yellow"))
+    sa, sb = a.get(-1), b.get(-1)  # pseudo-entry -1: the map tree's start
+    if isinstance(sa, StartSpec) and isinstance(sb, StartSpec) and sa.key() != sb.key():
+        parts.append(("new start positions", "yellow"))
+    return parts
+
+
+def _line_counts(old: str, new: str) -> tuple[int, int]:
+    """Lines added and removed from old to new, like `git diff --stat`."""
+    plus = minus = 0
+    matcher = difflib.SequenceMatcher(None, old.splitlines(), new.splitlines(), autojunk=False)
+    for tag, i1, i2, j1, j2 in matcher.get_opcodes():
+        if tag != "equal":
+            minus += i2 - i1
+            plus += j2 - j1
+    return plus, minus
+
+
+class StatusLine(BaseModel):
+    name: str
+    counts: list[tuple[str, int, int]] = []  # (label, added lines, removed lines)
+    detail: list[Part] = []
+
+
+def _counts_text(counts: list[tuple[str, int, int]]) -> Text:
+    t = Text()
+    for n, (label, plus, minus) in enumerate(counts):
+        if n:
+            t.append(", ")
+        if label:
+            t.append(label + " ")
+        t.append("+%d" % plus, "green")
+        t.append(" ")
+        t.append("-%d" % minus, "red")
+    return t
+
+
+def _render(ui: UI, kind: str, title: str, lines: list[StatusLine], label: str, style: str, w: int, cw: int) -> None:
+    ui.print((title, "bold"), kind=kind)
+    console = ui.console
+    for line in lines:
+        t = Text(" " * 8)
+        if label:
+            t.append(label.ljust(12), style)
+        t.append(line.name.ljust(w), style)
+        if line.counts or line.detail:
+            counts = _counts_text(line.counts)
+            t.append("   ")
+            t.append_text(counts)
+            t.append(" " * (cw - len(counts.plain)))
+        for n, (text, part_style) in enumerate(line.detail):
+            t.append("   " if n == 0 else "; ")
+            t.append(text, part_style)
+        console.print(t)
+
+
+def _error_name(e: ScriptError, script_dir: str) -> str:
+    """A script error as status lists it: path:line (relative to the scripts folder): message."""
+    line = ":%d" % e.line if e.line else ""
+    return "%s%s: %s" % (os.path.relpath(e.path, script_dir), line, e.err)
+
+
+def _status(syncer: Syncer, units: list[Unit]) -> dict[str, list[StatusLine]]:
+    project = syncer.project
+    out: dict[str, list[StatusLine]] = {k: [] for k in ("script", "game", "both", "unsynced", "errors", "new")}
+    data_of: dict[str, bytes | None] = {}
+    for u in units:
+        if u.bin_path not in data_of:
+            data_of[u.bin_path] = read_bytes(u.bin_path)
+        data = data_of[u.bin_path]
+        if data is None:
+            continue
+        what = {"map": "event", "common": "common event", "troop": "troop", "maptree": "map"}.get(u.kind, "entry")
+        py_name = u.script_label(project.script_dir)
+        bin_name = os.path.relpath(u.bin_path, project.game_dir)
+        if u.kind == "database":
+            bin_name += " [%s]" % u.table
+        elif u.kind == "common":
+            bin_name += " [common events]"
+        elif u.kind == "troop":
+            bin_name += " [troop events]"
+        try:
+            found = u.read_script()
+        except ScriptError as e:
+            out["errors"].append(StatusLine(name=_error_name(e, project.script_dir)))
+            continue
+        if found is None:
+            out["new"].append(StatusLine(name=py_name))
+            continue
+        text = found.text
+        st = syncer.state.get(u)
+        bin_changed = u.bin_changed(data, st)
+        py_changed = st is None or sha(text.encode("utf-8")) != st["py"]
+        if not (bin_changed or py_changed):
+            continue
+
+        specs: list = []
+        if py_changed:
+            try:
+                specs, _ = u.compile_checked(text, data)
+            except ScriptError as e:
+                out["errors"].append(StatusLine(name=_error_name(e, project.script_dir)))
+                continue
+            problems = syncer.check_engine(u, specs, data)
+            if problems:
+                out["errors"] += [StatusLine(name="%s: %s" % (py_name, p)) for p in problems]
+                continue
+        game_specs = u.specs_from_bin(data)
+
+        if st is None:  # never synced: a sync adopts the pair if it agrees
+            detail = _entry_diff(game_specs, specs, what)
+            if detail:
+                out["unsynced"].append(StatusLine(name=py_name, detail=detail))
+            continue
+
+        base = syncer.state.base_text(u)
+        base_specs = None
+        if base is not None and bin_changed:
+            try:
+                base_specs = u.compile(base)
+            except Exception:  # base written by an older rpgsync, renamed switch...
+                base_specs = None
+        pulled = None
+        if bin_changed:
+            try:
+                pulled = u.decompile(data)
+            except Exception:
+                pulled = None
+
+        if py_changed and not bin_changed:
+            counts = [("", *_line_counts(base, text))] if base is not None else []
+            detail = _entry_diff(game_specs, specs, what) or [("no change for the game", "dim")]
+            out["script"].append(StatusLine(name=py_name, counts=counts, detail=detail))
+        elif bin_changed and not py_changed:
+            counts = [("", *_line_counts(text, pulled))] if base is not None and pulled is not None else []
+            detail = _entry_diff(base_specs, game_specs, what) if base_specs is not None else []
+            out["game"].append(StatusLine(name=bin_name, counts=counts, detail=detail))
+        else:
+            counts = []
+            if base is not None:
+                counts.append(("scripts", *_line_counts(base, text)))
+                if pulled is not None:
+                    counts.append(("game", *_line_counts(base, pulled)))
+            detail = []
+            if base_specs is not None:
+                for side, old, new in (("scripts", base_specs, specs), ("game", base_specs, game_specs)):
+                    parts = _entry_diff(old, new, what)
+                    if parts:  # "scripts: event 9 changed; game: event 1 changed"
+                        detail += [(side + ": " + parts[0][0], parts[0][1])] + parts[1:]
+            out["both"].append(StatusLine(name="%s / %s" % (py_name, bin_name), counts=counts, detail=detail))
+    return out
+
+
+# --------------------------------------------------------------------------
+# Commands
+# --------------------------------------------------------------------------
+
+
+def watch(
+    project: ProjectArg = None,
+    interval: Annotated[float, typer.Option(help="Poll interval in seconds.")] = 0.5,
+    yes: YesOpt = False,
+):
+    """Keep the game and its scripts in sync until Ctrl+C (also: `rpgsync [FOLDER]`).
+    The first time, the scripts are written and their folder is set up.
+
+    For the EasyRPG Editor with its rpgsync mode on, which reloads what changes on disk.
+    With the RPG Maker 2000/2003 editor, keep it closed while you edit the scripts."""
+    syncer = _open(project)
+    ui = syncer.ui
+    initial = _needs_set_up(syncer)
+    if initial:
+        _set_up(syncer, yes)
+    _sync_all(syncer, syncer.units(), None, initial)
+    if initial:
+        rel = os.path.relpath(syncer.project.script_dir, os.path.dirname(syncer.project.game_dir))
+        ui.echo("")
+        ui.print(("Next:", "bold"))
+        ui.bullet(("edit ", "bold green"), "the scripts in ", (rel, "cyan"), ": saving one writes it into the game")
+        ui.bullet(
+            ("Default RPG Maker 2000/2003 editor: ", "bold"),
+            "keep it closed while you edit the scripts (it keeps its own copy of the game "
+            "and ignores them), then open it and keep editing there",
+        )
+        ui.bullet(
+            ("EasyRPG Editor: ", "bold"),
+            "turn on its ",
+            ("rpgsync mode", "bold"),
+            " (Settings): it reloads what changes on disk, so it can stay open",
+        )
+        ui.bullet(
+            ("rpgsync status", "bold cyan"),
+            " lists what changed, ",
+            ("rpgsync check", "bold cyan"),
+            " runs the engine and type checks",
+        )
+        ui.echo("")
+    ui.print("Watching ", (syncer.project.game_dir, "cyan"), kind="watch")
+    ui.echo("Every edit will be synced between python files and game files.")
+    ui.echo("Ctrl+C to stop")
+    try:
+        syncer.watch(interval, announce=False, first_pass=False)
+    except KeyboardInterrupt:
+        ui.print("stopped", kind="stop")
+
+
+def pull(
+    project: ProjectArg = None,
+    map: MapOpt = None,
+    no_common: NoCommonOpt = False,
+    force: Annotated[bool, typer.Option("--force", help="Overwrite scripts that have unsynced edits.")] = False,
+    yes: YesOpt = False,
+):
+    """Game -> scripts: regenerate the scripts from the game files.
+
+    With the RPG Maker 2000/2003 editor: save and close it first."""
+    syncer = _open(project)
+    initial = _needs_set_up(syncer)
+    if initial:
+        _set_up(syncer, yes)
+    _run(syncer, _units(syncer, map, no_common), "game" if force else None, initial)
+
+
+def push(
+    project: ProjectArg = None,
+    map: MapOpt = None,
+    no_common: NoCommonOpt = False,
+    force: Annotated[
+        bool, typer.Option("--force", help="Write every script, also those unchanged since the last sync.")
+    ] = False,
+):
+    """Scripts -> game: write the scripts changed since the last sync into the game files (the
+    script wins over edits made in the editor).
+
+    With the RPG Maker 2000/2003 editor: open it after the push, so it reads them."""
+    syncer = _open(project)
+    _run(syncer, _units(syncer, map, no_common), "script", force=force)
+
+
+def locate(
+    project: ProjectArg = None,
+    map: Annotated[int | None, typer.Option("--map", help="The map of the event.")] = None,
+    event: Annotated[int | None, typer.Option("--event", help="The event, on --map.")] = None,
+    page: Annotated[int, typer.Option("--page", help="Its page, from 1.")] = 1,
+    common_event: Annotated[int | None, typer.Option("--common-event", help="A common event instead.")] = None,
+    troop: Annotated[
+        int | None, typer.Option("--troop", help="The battle events of a troop instead (with --page).")
+    ] = None,
+    command: Annotated[
+        int | None, typer.Option("--command", help="A command of the list, from 0 (as in the editor).")
+    ] = None,
+    map_tree: Annotated[
+        int | None,
+        typer.Option("--map-tree", help="A map or area of database/map_tree.py instead (0: the start positions)."),
+    ] = None,
+):
+    """Print FILE:LINE where a script writes an event, its page or one of its commands, a
+    map (--map alone) or a map's entry in the map tree (for editors: open the script
+    there). Writes nothing."""
+    syncer = _open(project)
+    proj = syncer.project
+    ctx = proj.context()
+    if map_tree is not None:
+        print("%s:%d" % _locate_tree_entry(proj, map_tree))
+        return
+    if map is not None and event is None and common_event is None and troop is None:
+        found = _read_script(proj.script_for_map(map), scriptfiles.MAP)
+        print("%s:%d" % _abs_where(found, 1))
+        return
+    if troop is not None:
+        path, style = proj.troop_events_script, scriptfiles.TROOP_EVENTS
+    elif common_event is not None:
+        path, style = proj.common_events_script, scriptfiles.COMMON_EVENTS
+    elif map is not None and event is not None:
+        path, style = proj.script_for_map(map), scriptfiles.MAP
+    else:
+        raise _fail("give --map and --event, --common-event, or --troop")
+    found = _read_script(path, style)
+    src = found.text
+    # compiled from the files as they are now: the lines of the cache can be stale
+    try:
+        if troop is not None:
+            specs = [s for s in compile_troop_events_source(src, ctx, path) if s.id == troop]
+            pages = specs[0].pages if specs else []
+            if specs and 1 <= page <= len(pages):
+                line, commands = pages[page - 1].lineno, pages[page - 1].commands
+            else:
+                line, commands = (specs[0].lineno if specs else None), []
+        elif common_event is not None:
+            specs = [s for s in compile_common_events_source(src, ctx, path) if s.id == common_event]
+            line = specs[0].lineno if specs else None
+            commands = specs[0].commands if specs else []
+        else:
+            specs = [s for s in compile_map_source(src, ctx, path) if s.id == event]
+            pages = specs[0].pages if specs else []
+            if specs and 1 <= page <= len(pages):
+                line, commands = pages[page - 1].lineno, pages[page - 1].commands
+            else:
+                line, commands = (specs[0].lineno if specs else None), []
+    except CompileError as e:
+        raise _fail("%s:%s: %s" % (*_abs_where(found, e.lineno or 1), e)) from None
+    if line is None:
+        raise _fail("not in %s" % path)
+    if command is not None and commands:
+        # the command, else the nearest one written before it (a block's end,
+        # the end of the list)
+        index = min(max(command, 0), len(commands) - 1)
+        lines = [c.line for c in commands[: index + 1] if c.line is not None]
+        line = lines[-1] if lines else line
+    print("%s:%d" % _abs_where(found, line))
+
+
+def _read_script(path: str, style: scriptfiles.Style | None) -> scriptfiles.ScriptFiles:
+    """A script as it is now (one file or a folder), or a failure."""
+    try:
+        found = scriptfiles.read(path, style)
+    except scriptfiles.LayoutError as e:
+        raise _fail(str(e)) from None
+    if found is None:
+        raise _fail("no script %s: run rpgsync first" % path)
+    return found
+
+
+def _abs_where(found: scriptfiles.ScriptFiles, line: int) -> tuple[str, int]:
+    """The absolute path and the line of a line of a script's text."""
+    path, n = found.where(line)
+    return os.path.abspath(path), n or 1
+
+
+def _locate_tree_entry(proj: Project, map_id: int) -> tuple[str, int]:
+    """map_tree.py and the line of a map's entry (0: of `start`)."""
+    from .maptree import StartSpec, compile_map_tree
+
+    path = proj.map_tree_script
+    if not os.path.isfile(path):
+        raise _fail("no script %s: run rpgsync first" % path)
+    with open(path, encoding="utf-8") as f:
+        src = f.read()
+    try:
+        specs = compile_map_tree(src, proj.context(), path)
+    except CompileError as e:
+        raise _fail("%s:%s: %s" % (path, e.lineno or 1, e)) from None
+    for s in specs:
+        if map_id == 0 and isinstance(s, StartSpec):
+            return os.path.abspath(path), s.lineno or 1
+        if map_id != 0 and getattr(s, "id", None) == map_id and s.lineno:
+            return os.path.abspath(path), s.lineno
+    raise _fail("map %d is not in %s" % (map_id, path))
+
+
+def status(project: ProjectArg = None, map: MapOpt = None, no_common: NoCommonOpt = False):
+    """Show what is pending on each side, without writing anything."""
+    syncer = _open(project)
+    ui = syncer.ui
+    engine = ENGINES.get(syncer.project.context().engine, syncer.project.context().engine)
+    ui.print("On ", (os.path.basename(syncer.project.game_dir), "bold"), " (%s)" % engine)
+    ui.print("  game:    ", (syncer.project.game_dir, "cyan"))
+    ui.print("  scripts: ", (syncer.project.script_dir, "cyan"))
+    ui.echo("")
+
+    found = _status(syncer, list(_units(syncer, map, no_common)))
+    found["tree"] = []
+    if not map and os.path.exists(syncer.project.lmt_path):
+        proj = syncer.project
+        tree_errors, tree_warnings = tree_problems(proj.game_dir, proj.script_dir, proj.encoding)
+        found["tree"] = [StatusLine(name=p) for p in tree_errors + tree_warnings]
+    listed = [line for k in ("script", "game", "both", "unsynced") for line in found[k]]
+    if not listed and not found["errors"] and not found["new"] and not found["tree"]:
+        ui.print(("All files are synced", "bold green"), kind="ok")
+        return
+    w = max((len(line.name) for line in listed), default=0)
+    cw = max((len(_counts_text(line.counts).plain) for line in listed), default=0)
+    sections = (
+        ("script", "Changes in scripts (`rpgsync push` writes them into the game):", "modified:", "yellow"),
+        ("game", "Changes in the game (`rpgsync pull` updates the scripts):", "modified:", "yellow"),
+        ("merge", "Changed on both sides (`rpgsync` merges them per event):", "modified:", "yellow"),
+        (
+            "conflict",
+            "Never synced and different (`rpgsync push` keeps the scripts, `rpgsync pull --force` keeps the game):",
+            "differs:",
+            "yellow",
+        ),
+        ("error", "Scripts with errors (fix them before they can be synced):", "", "red"),
+        ("new", "Not exported yet (`rpgsync pull` creates them):", "", "green"),
+        ("warning", "Map tree (maps, map files and scripts that don't match):", "", "yellow"),
+    )
+    keys = {
+        "script": "script",
+        "game": "game",
+        "merge": "both",
+        "conflict": "unsynced",
+        "error": "errors",
+        "warning": "tree",
+    }
+    for kind, title, label, style in sections:
+        lines = found[keys.get(kind, kind)]
+        if lines:
+            _render(ui, kind, title, lines, label, style, w if label else 0, cw)
+
+
+def check(
+    paths: Annotated[
+        list[str] | None,
+        typer.Argument(
+            help="The game folder (with RPG_RT.ldb) or its scripts folder (default: the current folder), "
+            "or scripts and folders of scripts to check only those: Scripts/Map0004.py, Scripts/database.",
+            show_default=False,
+        ),
+    ] = None,
+    map: MapOpt = None,
+    no_common: NoCommonOpt = False,
+    patches: Annotated[
+        list[str] | None,
+        typer.Option("--patch", help="Allowed engine patch: dynrpg, maniac or easyrpg (repeatable)."),
+    ] = None,
+    no_types: Annotated[bool, typer.Option("--no-types", help="Skip the type check (ty).")] = False,
+    resources: Annotated[
+        bool,
+        typer.Option(
+            "--resources",
+            help="Also check the resource files: used by an event but not imported, imported but never used.",
+        ),
+    ] = False,
+    jobs: Annotated[
+        int | None,
+        typer.Option(
+            "--jobs", "-j", min=1, help="Processes compiling the scripts (default: one per CPU for a large game)."
+        ),
+    ] = None,
+):
+    """Compile every script (or the ones given), check engine compatibility and types (ty), without
+    writing anything."""
+    syncer = _open(_paths_project(paths))
+    ui, err = syncer.ui, UI(err=True)
+    proj = syncer.project
+    chosen = _chosen_paths(proj, paths)  # None: the whole game
+    engine = target_engine(proj.script_dir, proj.context().engine)
+    declared, allow = load_rules(proj.script_dir)
+    errors = warnings = 0
+    tree_maps, sizes = map_tree_maps(proj)
+    files = Collector(proj.encoding) if resources else None  # the files the scripts and the game use
+    allowed = patches or declared
+    dyn = "dynrpg" in allowed or "easyrpg" in allowed  # plugin calls run: check them against the game
+    rules = _Rules(
+        engine=engine,
+        patches=allowed,
+        allow=allow,
+        tree_maps=tree_maps,
+        sizes=sizes,
+        plugins=dynrpg.installed(proj.game_dir) if dyn else None,
+        tables=proj.table_sizes() if dyn else None,
+    )
+    units = list(_units(syncer, map, no_common))
+    if chosen is not None:
+        keep = {u.py_path for u in _chosen_units(syncer.units(), chosen)}
+        units = [u for u in units if u.py_path in keep]
+    for found, part in _checked_units(proj, units, rules, resources, jobs):
+        for kind, where, problem in found:
+            color = "red" if kind == "error" else "yellow"
+            err.print(*([(where, "cyan"), ": "] if where else []), (problem, color), kind=kind)
+            errors += kind == "error"
+            warnings += kind == "warning"
+        if files is not None and part is not None:
+            files.merge(part)
+    if tree_maps is not None and any(u.kind == "maptree" for u in units):
+        tree_errors, tree_warnings = tree_problems(proj.game_dir, proj.script_dir, proj.encoding)
+        for problem in tree_errors:
+            err.print(("RPG_RT.lmt", "cyan"), ": ", (problem, "red"), kind="error")
+        for problem in tree_warnings:
+            err.print(("RPG_RT.lmt", "cyan"), ": ", (problem, "yellow"), kind="warning")
+        errors += len(tree_errors)
+        warnings += len(tree_warnings)
+    if rules.plugins is not None and "dynrpg" in rules.patches and chosen is None and not map:
+        for problem in dynrpg.setup_problems(rules.plugins, rules.tables):  # once, for the whole game
+            err.print(("DynRPG.ini", "cyan"), ": ", (problem, "yellow"), kind="warning")
+            warnings += 1
+        for problem in dynrpg.easyrpg_ini_problems(rules.plugins):
+            err.print(("EasyRPG.ini", "cyan"), ": ", (problem, "yellow"), kind="warning")
+            warnings += 1
+    if files is not None:
+        complete = chosen is None and not map and not no_common
+        warnings += _check_resources(files, proj, ui, err, complete=complete)
+    if not no_types:
+        errors += _check_types(syncer.project.script_dir, ui, err, chosen)
+    warned = ("%d warning(s)" % warnings, "bold yellow") if warnings else None
+    if errors:
+        ui.print(("%d problem(s)" % errors, "bold red"), *([", ", warned] if warned else []), kind="error")
+        raise typer.Exit(1)
+    if chosen is not None and len(units) == 1:  # Map0004.py compiles and fits the engine
+        scripts, verbs = units[0].script_label(), ("compiles", "fits", "passes")
+    else:
+        scripts, verbs = "All scripts" if chosen is None else "The %d scripts" % len(units), ("compile", "fit", "pass")
+    what = "%s and %s the engine" % verbs[:2] + (" and %s the type check" % verbs[2] if not no_types else "")
+    ui.print(("%s %s" % (scripts, what), "bold green"), *([" (", warned, ")"] if warned else []), kind="ok")
+
+
+def _paths_project(paths: list[str] | None) -> str | None:
+    """The folder whose game `check` checks: that of the paths it was given (one game)."""
+    if not paths:
+        return None
+    games = {}
+    for p in paths:
+        if not os.path.exists(p):
+            raise typer.BadParameter("%s does not exist" % p)
+        where = Path(p).resolve()
+        folder = where if where.is_dir() else where.parent
+        games[p] = (_find(folder), str(folder))
+    first = paths[0]
+    for p in paths[1:]:
+        if games[p][0] != games[first][0]:
+            raise typer.BadParameter("%s and %s are not in the same game" % (first, p))
+    return games[first][1]
+
+
+def _chosen_paths(proj: Project, paths: list[str] | None) -> list[Path] | None:
+    """The scripts and folders of scripts to check; None: the whole game (no paths, or its
+    game or scripts folder)."""
+    if not paths:
+        return None
+    chosen = [Path(p).resolve() for p in paths]
+    whole = (Path(proj.game_dir).resolve(), Path(proj.script_dir).resolve())
+    return None if any(p in whole for p in chosen) else chosen
+
+
+def _chosen_units(units: list[Unit], chosen: list[Path]) -> list[Unit]:
+    """The units whose script is one of `chosen` or in one of its folders (a file of a
+    script split in files counts for the whole script)."""
+    scripts = {u.py_path: Path(u.py_path).resolve() for u in units}
+    folders = {u.py_path: Path(scriptfiles.package_dir(u.py_path)).resolve() for u in units}
+
+    def chose(p: Path, py_path: str) -> bool:
+        s, d = scripts[py_path], folders[py_path]
+        return p == s or p in s.parents or p == d or d in p.parents
+
+    out = [u for u in units if any(chose(p, u.py_path) for p in chosen)]
+    for p in chosen:
+        if not any(chose(p, u.py_path) for u in units):
+            what = "holds no script" if p.is_dir() else "is not a script"
+            raise _fail("%s %s of the game (a map, a database table, the common events...)" % (p, what))
+    return out
+
+
+class _Rules(BaseModel):
+    """What `check` checks the compiled scripts against."""
+
+    engine: str
+    patches: list[str]
+    allow: list[int]
+    tree_maps: dict[int, str] | None  # the maps of the game (None: no map tree) and their sizes
+    sizes: dict[int, tuple[int, int] | None]
+    plugins: dynrpg.Installed | None = None  # DynPlugins/ and DynRPG.ini (None: no plugin call runs)
+    tables: dict[str, int] | None = None  # entries of the variables, actors, items, skills
+
+
+def _check_unit(u: Unit, rules: _Rules, files: Collector | None) -> list[tuple[str, str, str]]:
+    """Compile a unit's script and check it.  -> the problems to print: (kind, where, problem)"""
+    found: list[tuple[str, str, str]] = []
+    try:
+        script = u.read_script()
+        if script is None:
+            if files is not None:
+                _game_resources(files, u)
+            return found
+        specs, _ = u.compile_checked(script.text)
+    except ScriptError as e:
+        if files is not None:
+            _game_resources(files, u)
+        return [("error", "", str(e))]
+    if files is not None:
+        files.specs(specs, u.py_path, u.where if script.package else None)
+    entry_files = script.entry_files(u.split_style) if script.package else {}
+
+    def place(problem: str) -> str:  # "event 5 page 1: ...": the file of event 5, for a script in files
+        m = re.match(r"(?:event|common event|troop) (\d+)\b", problem)
+        return entry_files.get(int(m.group(1)), u.at(None)) if m and entry_files else u.at(None)
+
+    for problem in check_specs(specs, rules.engine, rules.patches, rules.allow):
+        found.append(("error", place(problem), problem))
+    for problem in check_warnings(specs, rules.engine, rules.patches, rules.allow, rules.plugins, rules.tables):
+        found.append(("warning", place(problem), problem))
+    if u.kind == "map":
+        # the active page is the last one whose conditions hold: pages after it may hide it
+        for line, problem in unreachable_pages(specs):
+            found.append(("warning", u.at(line), problem))
+    if rules.tree_maps is not None and u.kind in ("map", "common", "troop", "maptree"):
+        # teleports (vehicles, teleport / escape targets, start positions) to maps of the game, inside them
+        for line, problem in map_reference_problems(specs, rules.tree_maps, rules.sizes):
+            found.append(("error", u.at(line), problem))
+    return found
+
+
+_PARALLEL_SIZE = 3_000_000  # scripts (bytes) worth compiling in several processes: ~1 s in one
+
+
+def _checked_units(
+    proj: Project, units: list[Unit], rules: _Rules, resources: bool, jobs: int | None
+) -> Iterator[tuple[list[tuple[str, str, str]], Collector | None]]:
+    """_check_unit() of each unit, in order: (problems, the files it uses).  A large game's
+    scripts compile in several processes (`jobs`, default one per CPU)."""
+    sizes = {
+        u.py_path: sum(os.path.getsize(p) for p in scriptfiles.paths(u.py_path) if os.path.isfile(p)) for u in units
+    }
+    if jobs is None:
+        jobs = (os.cpu_count() or 1) if sum(sizes.values()) >= _PARALLEL_SIZE else 1
+    jobs = min(jobs, len(units))
+    if jobs <= 1:
+        for u in units:
+            files = Collector(proj.encoding) if resources else None
+            yield _check_unit(u, rules, files), files
+        return
+    import multiprocessing
+    from concurrent.futures import ProcessPoolExecutor
+
+    context = multiprocessing.get_context("spawn")  # fork is unsafe on macOS
+    init = (proj.game_dir, proj.script_dir, rules, resources)
+    with ProcessPoolExecutor(jobs, mp_context=context, initializer=_worker_init, initargs=init) as pool:
+        try:
+            # the largest first, so that the last ones to finish are short
+            futures = {
+                u.py_path: pool.submit(_worker_check, u.py_path) for u in sorted(units, key=lambda u: -sizes[u.py_path])
+            }
+            for u in units:
+                yield futures[u.py_path].result()
+        finally:
+            pool.shutdown(cancel_futures=True)
+
+
+_WORKER: dict[str, Any] = {}  # a check process: its units, rules
+
+
+def _worker_init(game_dir: str, script_dir: str, rules: _Rules, resources: bool) -> None:
+    project = Project(game_dir, script_dir)
+    _WORKER.update(units={u.py_path: u for u in Syncer(project).units()}, rules=rules, resources=resources)
+    _WORKER["encoding"] = project.encoding
+
+
+def _worker_check(py_path: str) -> tuple[list[tuple[str, str, str]], Collector | None]:
+    files = Collector(_WORKER["encoding"]) if _WORKER["resources"] else None
+    return _check_unit(_WORKER["units"][py_path], _WORKER["rules"], files), files
+
+
+def _game_resources(resources: Collector, unit: Unit) -> None:
+    """The resources of a unit whose script is missing or does not compile, from its game file."""
+    data = read_bytes(unit.bin_path)
+    if data is None:
+        return
+    try:
+        resources.specs(unit.bin_specs(data), os.path.basename(unit.bin_path))
+    except Exception:  # unreadable game data: reported by the sync
+        pass
+
+
+def _check_resources(resources: Collector, proj: Project, ui: UI, err: UI, complete: bool) -> int:
+    """Warn about references to files the game does not have (not imported), and, when
+    every script was read (`complete`), about imported files nothing uses.  -> warnings"""
+    if complete:
+        resources.game(proj.game_dir, proj.ldb_path)
+    found = resource_problems(resources, proj.game_dir, proj.context().engine, complete)
+    grouped: dict[tuple[str, str], list] = {}  # (database file, folder) -> its references
+    uses: dict[tuple[str, str], list] = {}  # (folder, file) -> the events using it
+    for ref in found.missing:
+        if not ref.event:  # the database keeps many (default entries never shown): one line per folder
+            grouped.setdefault((ref.path, ref.folder), []).append(ref)
+        else:  # one line per file, at its first use
+            uses.setdefault((ref.folder, resource_key(ref.name)), []).append(ref)
+    for refs in uses.values():
+        ref = refs[0]
+        where = "%s:%d" % (ref.path, ref.line) if ref.line else ref.path
+        problem = "%s uses %s/%s, which is not imported" % (ref.what, ref.folder, ref.name)
+        if len(refs) > 1:
+            others = [
+                "%s:%d" % (os.path.basename(r.path), r.line) if r.line else os.path.basename(r.path) for r in refs[1:4]
+            ]
+            more = " and %d more" % (len(refs) - 4) if len(refs) > 4 else ""
+            problem += " (also used at %s%s)" % (", ".join(others), more)
+        err.print((where, "cyan"), ": ", (problem, "yellow"), kind="warning")
+    for (path, folder), refs in grouped.items():
+        where = "%s:%d" % (path, refs[0].line) if refs[0].line else path
+        names = list(dict.fromkeys(r.name for r in refs))
+        shown = ", ".join(names[:8]) + (" and %d more" % (len(names) - 8) if len(names) > 8 else "")
+        if len(refs) == 1:
+            problem = "%s uses %s/%s, which is not imported" % (refs[0].what, folder, refs[0].name)
+        else:
+            problem = "%d entries use %s files that are not imported: %s" % (len(refs), folder, shown)
+        err.print((where, "cyan"), ": ", (problem, "yellow"), kind="warning")
+    for folder, names in found.unused.items():
+        problem = "%d imported file%s never used: %s" % (len(names), "s" * (len(names) > 1), ", ".join(names))
+        err.print((folder + "/", "cyan"), ": ", (problem, "yellow"), kind="warning")
+    if found.note:
+        ui.print(found.note, kind="info")
+    return len(uses) + len(grouped) + len(found.unused)
+
+
+def _ty(script_dir: str) -> str | None:
+    """The ty of the scripts folder's environment, else one on the PATH."""
+    for rel in (".venv/bin/ty", ".venv/Scripts/ty.exe"):
+        path = os.path.join(script_dir, rel)
+        if os.path.isfile(path):
+            return path
+    return shutil.which("ty")
+
+
+def _check_types(script_dir: str, ui: UI, err: UI, paths: list[Path] | None = None) -> int:
+    """Run ty on the scripts folder (or on `paths` in it); print its diagnostics.  -> number
+    of problems (With DynParams, database/game_types.py lets a variable stand where the DSL
+    takes a fixed number.)"""
+    ty = _ty(script_dir)
+    if ty is None:
+        ui.print("type check skipped: ty is not installed (run `uv sync` in %s)" % script_dir, kind="info")
+        return 0
+    cmd = [ty, "check", "--output-format", "concise", *(str(p) for p in paths or ())]
+    venv = os.path.join(script_dir, ".venv")
+    if os.path.isdir(venv):  # the scripts' environment, even when another virtualenv is active
+        cmd += ["--python", venv]
+    result = subprocess.run(cmd, cwd=script_dir, capture_output=True, text=True, errors="replace", check=False)
+    lines = [ln for ln in result.stdout.splitlines() if ln.strip() and not ln.startswith(("Found ", "All checks"))]
+    if result.returncode == 0 or not lines:
+        return 0
+    for line in lines:
+        err.print((line, "red"), kind="error")
+    return max(len(lines), 1)
+
+
+def clean(
+    project: ProjectArg = None,
+    yes: Annotated[bool, typer.Option("--yes", "-y", help="Do not ask for confirmation.")] = False,
+):
+    """Delete the backups of overwritten files (Scripts/.rpgsync/history)."""
+    syncer = _open(project)
+    ui = syncer.ui
+    history = Path(syncer.history_dir)
+    snapshots = sorted(history.iterdir()) if history.is_dir() else []
+    if not snapshots:
+        ui.print("no backups to delete", kind="info")
+        return
+    size = sum(f.stat().st_size for f in history.rglob("*") if f.is_file())
+    ui.print(
+        "%d backup(s), %.1f MB in " % (len(snapshots), max(size / 1e6, 0.1)), (str(history), "cyan"), kind="delete"
+    )
+    if not yes and typer.prompt('Type "yes" to delete them', default="", show_default=False) != "yes":
+        ui.print("nothing deleted", kind="info")
+        raise typer.Exit(1)
+    shutil.rmtree(history)
+    ui.print(("deleted", "green"), kind="ok")
+
+
+# registered here so that `rpgsync --help` lists them in this order
+for _command in (watch, status, check, pull, push, clean, locate):
+    app.command()(_command)
+
+COMMANDS = {"watch", "status", "check", "pull", "push", "clean", "locate"}
+
+
+def main() -> None:
+    """Entry point.  `rpgsync FOLDER` is a shortcut for `rpgsync watch FOLDER`,
+    and a bare `rpgsync` watches the game of the current folder."""
+    for stream in (sys.stdout, sys.stderr):
+        _never_fail(stream)  # legacy Windows consoles: "?" rather than UnicodeEncodeError
+    argv = sys.argv[1:]
+    if not argv:
+        try:
+            _locate(None)
+        except ProjectNotFound as e:
+            sys.argv.append("--help")
+            try:
+                app(prog_name="rpgsync")
+            except SystemExit:
+                pass
+            UI(err=True).echo("")
+            _fail(str(e))
+            sys.exit(2)
+        sys.argv.insert(1, "watch")
+    elif argv[0] not in COMMANDS and argv[0] != "--help":
+        # a project name/folder, or watch options such as --interval
+        sys.argv.insert(1, "watch")
+    app(prog_name="rpgsync")