romledger 0.2.0__py3-none-any.whl

romledger/__init__.py

@@ -0,0 +1,4 @@
+from importlib.metadata import version
+
+__version__ = version("romledger")
+DOCS_URL = "https://github.com/kjiwa/romledger/blob/master/docs"

romledger/canary.py

@@ -0,0 +1,368 @@
+import re
+from collections.abc import Callable, Mapping, Sequence
+from dataclasses import dataclass
+from functools import partial
+
+import httpx
+
+from romledger import dats, http, igir, registry
+from romledger.sources import coolrom, internet_archive
+from romledger.sources.base import Site
+from romledger.sources.errors import FetchError, SourceBlocked, SourceChanged
+
+COOLROM_PLATFORM = "atari7800"
+VIMM_URL = "https://vimm.net"
+VIMM_HOSTS = ("vimm.net",)
+VIMM_SYSTEM = "NES"
+ARCHIVE_ITEM = "No-Intro_NES"
+IGIR_RELEASE_URL = "https://api.github.com/repos/emmercm/igir/releases/latest"
+COOLROM_PLATFORM_LINK = re.compile(r'href="/roms/([a-z0-9]+)/"')
+VIMM_PLATFORM_LINK = re.compile(r'href="/vault/([A-Za-z0-9-]+)"')
+VIMM_ROW_LINK = re.compile(r'href="/vault/\d+"')
+CHALLENGE_MARKERS = ("just a moment", "checking if you are human")
+
+
+@dataclass(frozen=True)
+class Finding:
+    key: str
+    title: str
+    detail: str
+
+
+@dataclass(frozen=True)
+class Report:
+    findings: list[Finding]
+    notes: list[str]
+    inconclusive: list[str]
+
+
+class Inconclusive(Exception):
+    pass
+
+
+class Skipped(Exception):
+    pass
+
+
+class Drift(Exception):
+    pass
+
+
+Check = Callable[[], list[Finding]]
+
+
+@dataclass(frozen=True)
+class Step:
+    check: Check
+    keys: tuple[str, ...]
+
+
+def run(
+    client: httpx.Client,
+    throttle: http.Throttle,
+    entries: Mapping[str, registry.Entry],
+    ignored: Mapping[str, frozenset[str]],
+    pinned_igir: str = igir.IGIR_VERSION,
+    token: str | None = None,
+) -> Report:
+    return _merge(
+        [
+            _run_steps("coolrom", _coolrom_steps(client, throttle, entries, ignored["coolrom"])),
+            _run_steps("vimm", _vimm_steps(client, throttle, entries, ignored["vimm"])),
+            _run_steps("internet-archive", _archive_steps(client, throttle)),
+            _run_steps("dat", _dat_steps(client, throttle, entries)),
+            _run_steps("igir", _igir_steps(client, throttle, pinned_igir, token)),
+        ]
+    )
+
+
+def _merge(reports: Sequence[Report]) -> Report:
+    return Report(
+        [finding for report in reports for finding in report.findings],
+        [note for report in reports for note in report.notes],
+        [prefix for report in reports for prefix in report.inconclusive],
+    )
+
+
+def _run_steps(group: str, steps: Sequence[Step]) -> Report:
+    report = Report([], [], [])
+    for index, step in enumerate(steps):
+        try:
+            report.findings.extend(step.check())
+        except Skipped:
+            report.inconclusive.extend(step.keys)
+        except Inconclusive as note:
+            report.notes.append(str(note))
+            report.inconclusive.append(group)
+            report.inconclusive.extend(key for later in steps[index:] for key in later.keys)
+            break
+    return report
+
+
+def _step(keys: tuple[str, ...], title: str, check: Check) -> Step:
+    def guarded() -> list[Finding]:
+        try:
+            return check()
+        except Drift as error:
+            detail = str(error)
+        except SourceChanged as error:
+            detail = f"{error.url}: {error.what}"
+        return [Finding(keys[0], title, detail)]
+
+    return Step(guarded, keys)
+
+
+def _coolrom_steps(
+    client: httpx.Client,
+    throttle: http.Throttle,
+    entries: Mapping[str, registry.Entry],
+    ignored: frozenset[str],
+) -> list[Step]:
+    site = Site(coolrom.BASE_URL, coolrom.HOSTS, coolrom.MIN_GAP, client, throttle)
+    first_rows: list[coolrom.Row] = []
+    return [
+        _step(
+            (
+                "coolrom:contract:platform-links",
+                "coolrom:missing-platform",
+                "coolrom:new-platform",
+            ),
+            "CoolROM platform list changed",
+            partial(_coolrom_platforms, site, entries, ignored),
+        ),
+        _step(
+            ("coolrom:contract:section",),
+            "CoolROM section page changed",
+            partial(_coolrom_section, site, first_rows),
+        ),
+        _step(
+            ("coolrom:contract:download-link",),
+            "CoolROM download page changed",
+            partial(_coolrom_download, site, first_rows),
+        ),
+    ]
+
+
+def _coolrom_platforms(
+    site: Site, entries: Mapping[str, registry.Entry], ignored: frozenset[str]
+) -> list[Finding]:
+    url = f"{coolrom.BASE_URL}/roms/"
+    found = set(COOLROM_PLATFORM_LINK.findall(_page(site, url).text))
+    mapped = {entry.coolrom for entry in entries.values() if entry.coolrom}
+    return _platform_findings("coolrom", url, found, mapped, ignored)
+
+
+def _coolrom_section(site: Site, first_rows: list[coolrom.Row]) -> list[Finding]:
+    url = f"{coolrom.BASE_URL}/roms/{COOLROM_PLATFORM}/x/"
+    rows = coolrom.parse_section(_page(site, url).text, COOLROM_PLATFORM, url)
+    if not rows:
+        raise Drift(f"{url}: no game rows found")
+    first_rows.append(rows[0])
+    return []
+
+
+def _coolrom_download(site: Site, first_rows: list[coolrom.Row]) -> list[Finding]:
+    if not first_rows:
+        raise Skipped
+    url = f"{coolrom.BASE_URL}/dlpop.php?id={first_rows[0].id}"
+    coolrom.parse_signed_link(_page(site, url).text, url)
+    return []
+
+
+def _vimm_steps(
+    client: httpx.Client,
+    throttle: http.Throttle,
+    entries: Mapping[str, registry.Entry],
+    ignored: frozenset[str],
+) -> list[Step]:
+    site = Site(VIMM_URL, VIMM_HOSTS, http.DEFAULT_GAP, client, throttle)
+    return [
+        _step(
+            ("vimm:contract:platform-links", "vimm:missing-platform", "vimm:new-platform"),
+            "Vimm's Lair platform list changed",
+            partial(_vimm_platforms, site, entries, ignored),
+        ),
+        _step(
+            ("vimm:contract:list",),
+            "Vimm's Lair list page changed",
+            partial(_vimm_list, site),
+        ),
+    ]
+
+
+def _vimm_platforms(
+    site: Site, entries: Mapping[str, registry.Entry], ignored: frozenset[str]
+) -> list[Finding]:
+    url = f"{VIMM_URL}/vault/"
+    codes = VIMM_PLATFORM_LINK.findall(_page(site, url).text)
+    found = {code for code in codes if not code.isdigit()}
+    mapped = {entry.vimm for entry in entries.values() if entry.vimm}
+    return _platform_findings("vimm", url, found, mapped, ignored)
+
+
+def _vimm_list(site: Site) -> list[Finding]:
+    url = f"{VIMM_URL}/vault/?p=list&system={VIMM_SYSTEM}&section=x"
+    if not VIMM_ROW_LINK.search(_page(site, url).text):
+        raise Drift(f"{url}: no game row links found")
+    return []
+
+
+def _platform_findings(
+    site: str, url: str, found: set[str], mapped: set[str], ignored: frozenset[str]
+) -> list[Finding]:
+    if not found:
+        raise Drift(f"{url}: no platform links found")
+    findings = [
+        Finding(
+            f"{site}:missing-platform:{code}",
+            f"{site} no longer lists a registry platform: {code}",
+            f"{url} has no link for {code}. Correct the {site} code in "
+            "src/romledger/platforms.toml.",
+        )
+        for code in sorted(mapped - found)
+    ]
+    findings.extend(
+        Finding(
+            f"{site}:new-platform:{code}",
+            f"{site} lists a platform missing from the registry: {code}",
+            f'{url} links {code}. Add `{site} = "{code}"` to its platform in '
+            f"src/romledger/platforms.toml, or add it to [ignore] {site}.",
+        )
+        for code in sorted(found - mapped - ignored)
+    )
+    return findings
+
+
+def _archive_steps(client: httpx.Client, throttle: http.Throttle) -> list[Step]:
+    site = Site(
+        internet_archive.BASE_URL, internet_archive.HOSTS, http.DEFAULT_GAP, client, throttle
+    )
+    return [
+        _step(
+            ("internet-archive:contract:metadata",),
+            "Internet Archive metadata changed",
+            partial(_archive_metadata, site),
+        )
+    ]
+
+
+def _archive_metadata(site: Site) -> list[Finding]:
+    url = f"{internet_archive.BASE_URL}/metadata/{ARCHIVE_ITEM}"
+    files = internet_archive.index(_page(site, url), url, ARCHIVE_ITEM)
+    if not any(isinstance(entry.get("md5"), str) for entry in files.values()):
+        raise Drift(f"{url}: no file entry has an md5")
+    return []
+
+
+def _dat_steps(
+    client: httpx.Client, throttle: http.Throttle, entries: Mapping[str, registry.Entry]
+) -> list[Step]:
+    return [
+        Step(partial(_dat_exists, client, throttle, entry), (f"dat:missing:{entry.slug}",))
+        for entry in entries.values()
+    ]
+
+
+def _dat_exists(
+    client: httpx.Client, throttle: http.Throttle, entry: registry.Entry
+) -> list[Finding]:
+    url = dats.url(entry.dat)
+    status = _send(client, throttle, "HEAD", url).status_code
+    if status == httpx.codes.OK:
+        return []
+    if status != httpx.codes.NOT_FOUND:
+        raise Inconclusive(f"{url}: HTTP {status}")
+    return [
+        Finding(
+            f"dat:missing:{entry.slug}",
+            f"libretro-database has no DAT for {entry.slug}",
+            f"{url}: HTTP 404. Correct dat for {entry.slug} in src/romledger/platforms.toml.",
+        )
+    ]
+
+
+def _igir_steps(
+    client: httpx.Client, throttle: http.Throttle, pinned: str, token: str | None
+) -> list[Step]:
+    return [
+        _step(
+            ("igir:contract:release", "igir:update"),
+            "igir release lookup changed",
+            partial(_igir_update, client, throttle, pinned, token),
+        )
+    ]
+
+
+def _igir_update(
+    client: httpx.Client, throttle: http.Throttle, pinned: str, token: str | None
+) -> list[Finding]:
+    headers = {"Accept": "application/vnd.github+json"}
+    if token:
+        headers["Authorization"] = f"Bearer {token}"
+    response = _send(client, throttle, "GET", IGIR_RELEASE_URL, headers, follow_redirects=False)
+    if response.status_code != httpx.codes.OK:
+        raise Inconclusive(f"{IGIR_RELEASE_URL}: HTTP {response.status_code}")
+    tag = _release_tag(response)
+    if tag.removeprefix("v") == pinned:
+        return []
+    return [
+        Finding(
+            f"igir:update:{tag}",
+            f"igir {tag} is out; romledger pins {pinned}",
+            f"Run `uv run pytest -m igir --no-cov`, then set IGIR_VERSION to "
+            f"{tag.removeprefix('v')} in src/romledger/igir.py.",
+        )
+    ]
+
+
+def _release_tag(response: httpx.Response) -> str:
+    try:
+        tag = response.json()["tag_name"]
+    except (ValueError, KeyError, TypeError) as error:
+        raise Drift(f"{IGIR_RELEASE_URL}: response has no tag_name") from error
+    if not isinstance(tag, str) or not tag:
+        raise Drift(f"{IGIR_RELEASE_URL}: tag_name is not a string")
+    return tag
+
+
+def _page(site: Site, url: str) -> httpx.Response:
+    try:
+        response = site.get(url, expect=(httpx.codes.OK, httpx.codes.NOT_FOUND))
+    except (FetchError, SourceBlocked) as error:
+        raise Inconclusive(str(error)) from error
+    except httpx.HTTPError as error:
+        raise Inconclusive(_unreachable(url, error)) from error
+    if response.status_code == httpx.codes.NOT_FOUND:
+        raise Drift(f"{url}: HTTP 404")
+    if _is_challenge(response):
+        raise Inconclusive(f"{url}: bot challenge page")
+    return response
+
+
+def _send(
+    client: httpx.Client,
+    throttle: http.Throttle,
+    method: str,
+    url: str,
+    headers: Mapping[str, str] | None = None,
+    *,
+    follow_redirects: bool = True,
+) -> httpx.Response:
+    throttle.wait(url)
+    try:
+        return client.request(method, url, headers=headers, follow_redirects=follow_redirects)
+    except httpx.HTTPError as error:
+        raise Inconclusive(_unreachable(url, error)) from error
+
+
+def _unreachable(url: str, error: httpx.HTTPError) -> str:
+    return f"{url}: request failed ({str(error) or type(error).__name__})"
+
+
+def _is_challenge(response: httpx.Response) -> bool:
+    if response.headers.get("cf-mitigated") == "challenge":
+        return True
+    if "text/html" not in response.headers.get("content-type", ""):
+        return False
+    text = response.text.lower()
+    return any(marker in text for marker in CHALLENGE_MARKERS)

romledger/cli.py

@@ -0,0 +1,320 @@
+import argparse
+import dataclasses
+import functools
+import json
+import os
+import sys
+import webbrowser
+from collections.abc import Callable, Sequence
+
+import uvicorn
+
+from romledger import (
+    __version__,
+    canary,
+    config,
+    datindex,
+    dats,
+    fetch,
+    http,
+    igir,
+    importer,
+    links,
+    registry,
+    scan,
+    state,
+)
+from romledger.context import Context, load_context
+from romledger.web import auth
+from romledger.web.app import create_app
+
+DEFAULT_HOST = "127.0.0.1"
+WILDCARD_HOSTS = ("0.0.0.0", "::")  # noqa: S104
+DEFAULT_PORT = 8730
+STATUS_COLUMNS = ("wanted", "have", "inbox", "missing", "unmatched", "done")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="romledger",
+        description="Track which retro games you have and which are missing.",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    parser.add_argument(
+        "--config",
+        metavar="FILE",
+        help="config file (default: $ROMLEDGER_CONFIG, else "
+        "$XDG_CONFIG_HOME/romledger/config.toml, i.e. ~/.config/romledger/config.toml)",
+    )
+    commands = parser.add_subparsers(dest="command", required=True, metavar="command")
+    commands.add_parser("config", help="validate the config file and print a summary")
+    dats_parser = commands.add_parser("dats", help="manage platform DATs")
+    dats_commands = dats_parser.add_subparsers(dest="dats_command", required=True, metavar="action")
+    update = dats_commands.add_parser("update", help="download the latest DATs")
+    update.set_defaults(command="dats update")
+    update.add_argument("platforms", nargs="*", metavar="PLATFORM", help="default: all configured")
+    index = dats_commands.add_parser("index", help="rebuild the DAT hash index")
+    index.set_defaults(command="dats index")
+    index.add_argument("platforms", nargs="*", metavar="PLATFORM", help="default: all configured")
+    scan_parser = commands.add_parser("scan", help="match library and inbox files to DATs")
+    scan_parser.add_argument(
+        "platforms", nargs="*", metavar="PLATFORM", help="default: all configured"
+    )
+    import_parser = commands.add_parser("import", help="file inbox games into the library")
+    import_parser.add_argument(
+        "--dry-run", action="store_true", help="show what would happen; move nothing"
+    )
+    commands.add_parser("status", help="show have/missing counts per platform")
+    fetch_parser = commands.add_parser(
+        "fetch", help="download missing games from configured sources"
+    )
+    fetch_parser.add_argument("platform", metavar="PLATFORM")
+    fetch_parser.add_argument(
+        "--limit", type=positive_int, metavar="N", help="fetch at most N games"
+    )
+    fetch_parser.add_argument(
+        "--dry-run", action="store_true", help="show matches; download nothing"
+    )
+    fetch_parser.add_argument(
+        "--no-import", action="store_true", help="leave the downloads in the inbox"
+    )
+    fetch_parser.add_argument("--source", metavar="NAME", help="use only this configured source")
+    canary_parser = commands.add_parser(
+        "canary", help="check that the supported sites and upstream pins still match"
+    )
+    canary_parser.add_argument(
+        "--json", action="store_true", help="print findings as JSON; notes go to stderr"
+    )
+    missing = commands.add_parser("missing", help="list the games a platform is missing")
+    missing.add_argument("platform", metavar="PLATFORM")
+    missing.add_argument("--links", action="store_true", help="append a Vimm's Lair search URL")
+    serve_parser = commands.add_parser("serve", help="run the local dashboard and API")
+    serve_parser.add_argument(
+        "--host", default=DEFAULT_HOST, help=f"address to bind (default: {DEFAULT_HOST})"
+    )
+    serve_parser.add_argument(
+        "--port", type=port_number, default=DEFAULT_PORT, help=f"port (default: {DEFAULT_PORT})"
+    )
+    serve_parser.add_argument("--open", action="store_true", help="open the dashboard in a browser")
+    return parser
+
+
+def port_number(text: str) -> int:
+    if not text.isdigit() or not 1 <= int(text) <= 65535:
+        raise argparse.ArgumentTypeError(f"{text!r} is not a port between 1 and 65535")
+    return int(text)
+
+
+def positive_int(text: str) -> int:
+    if not text.isdigit() or int(text) < 1:
+        raise argparse.ArgumentTypeError(f"{text!r} is not a positive integer")
+    return int(text)
+
+
+def selected(context: Context, names: Sequence[str]) -> list[str]:
+    configured = list(context.config.platforms)
+    for name in names:
+        if name not in context.config.platforms:
+            raise config.ConfigError(
+                f"unknown platform {name!r}. Configured platforms: "
+                f"{', '.join(configured) or 'none'}."
+            )
+    return list(dict.fromkeys(names)) or configured
+
+
+def show_config(args: argparse.Namespace) -> int:
+    context = load_context(args.config)
+    print(f"config:  {context.path}")
+    print(f"data:    {context.data_dir}")
+    print(f"roms:    {context.config.library.roms}")
+    for inbox in context.config.library.inboxes:
+        print(f"inbox:   {inbox}")
+    for slug, platform in context.config.platforms.items():
+        print(f"{slug}: {platform.dat}")
+        print(f"  regions: {', '.join(platform.regions)}")
+        print(f"  languages: {', '.join(platform.languages)}")
+        if platform.sources:
+            print(f"  sources: {', '.join(platform.sources)}")
+        if platform.archive_item:
+            print(f"  archive_item: {platform.archive_item}")
+    if context.config.network.proxy:
+        print(f"proxy:   {http.redact(context.config.network.proxy)}")
+    for argv in context.config.hooks.after_import:
+        print(f"hook:    after_import {' '.join(argv)}")
+    return 0
+
+
+def update_dats(args: argparse.Namespace) -> int:
+    context = load_context(args.config)
+    slugs = selected(context, args.platforms)
+    wanted = {slug: context.config.platforms[slug].dat for slug in slugs}
+    with http.client(context.config.network.proxy) as client:
+        results = dats.update(context.data_dir, wanted, client)
+    for slug, result in results.items():
+        print(f"{slug} {result.version} ({'updated' if result.changed else 'unchanged'})")
+    return 0
+
+
+def scan_platforms(args: argparse.Namespace) -> int:
+    context = load_context(args.config)
+    slugs = selected(context, args.platforms)
+    scan.require_dats(context.config, slugs, context.data_dir)
+    scan.scan_each(slugs, lambda slug: scan.scan_platform(context.config, slug, context.data_dir))
+    return 0
+
+
+def import_games(args: argparse.Namespace) -> int:
+    return run_import(load_context(args.config), args.dry_run)
+
+
+def run_import(context: Context, dry_run: bool) -> int:
+    result = importer.import_inboxes(context.config, context.data_dir, dry_run)
+    return importer.print_result(result, dry_run=dry_run)
+
+
+def fetch_games(args: argparse.Namespace) -> int:
+    context = load_context(args.config)
+    (slug,) = selected(context, [args.platform])
+    if not context.config.platforms[slug].sources:
+        raise config.ConfigError(f"{slug} has no sources configured; set platforms.{slug}.sources")
+    with http.client(context.config.network.proxy) as client:
+        throttle = http.Throttle()
+        result = fetch.fetch_platform(
+            context.config,
+            slug,
+            context.data_dir,
+            args.limit,
+            args.dry_run,
+            functools.partial(fetch.build_sources, client=client, throttle=throttle),
+            client,
+            throttle,
+            args.source,
+        )
+    status = 1 if result.failed else 0
+    if result.fetched and not args.dry_run and not args.no_import:
+        status = max(status, run_import(context, dry_run=False))
+    return status
+
+
+def show_status(args: argparse.Namespace) -> int:
+    context = load_context(args.config)
+    with state.State(context.data_dir / "state.db") as database:
+        counts = database.counts()
+    rows = [status_row(slug, counts.get(slug)) for slug in context.config.platforms]
+    for line in format_table(("platform", *STATUS_COLUMNS), rows):
+        print(line)
+    if any(slug not in counts for slug in context.config.platforms):
+        print(scan.SCAN_HINT)
+    return 0
+
+
+def status_row(slug: str, counts: state.Counts | None) -> tuple[str, ...]:
+    if counts is None:
+        return (slug, *("-" for _ in STATUS_COLUMNS))
+    wanted = counts.have + counts.inbox + counts.missing
+    done = f"{counts.have * 100 // wanted}%" if wanted else "-"
+    values = (wanted, counts.have, counts.inbox, counts.missing, counts.unmatched)
+    return (slug, *(str(value) for value in values), done)
+
+
+def format_table(header: tuple[str, ...], rows: list[tuple[str, ...]]) -> list[str]:
+    widths = [max(len(cells[i]) for cells in (header, *rows)) for i in range(len(header))]
+    return [
+        "  ".join(
+            cell.ljust(width) if i == 0 else cell.rjust(width)
+            for i, (cell, width) in enumerate(zip(cells, widths, strict=True))
+        ).rstrip()
+        for cells in (header, *rows)
+    ]
+
+
+def show_missing(args: argparse.Namespace) -> int:
+    context = load_context(args.config)
+    (slug,) = selected(context, [args.platform])
+    games = scan.missing_games(context.data_dir, slug)
+    vimm = context.platforms[slug].vimm if slug in context.platforms else None
+    for game in games:
+        link = links.vimm_search(vimm, game) if args.links and vimm else None
+        print(f"{game}\t{link}" if link else game)
+    return 0
+
+
+def index_dats(args: argparse.Namespace) -> int:
+    context = load_context(args.config)
+    slugs = selected(context, args.platforms)
+    scan.require_dats(context.config, slugs, context.data_dir)
+    with state.State(context.data_dir / "state.db") as database:
+        for slug in slugs:
+            dat = dats.dat_path(context.data_dir, context.config.platforms[slug].dat)
+            rebuilt = datindex.ensure(database, slug, dat)
+            print(f"{slug} {'indexed' if rebuilt else 'unchanged'}")
+    return 0
+
+
+def serve(args: argparse.Namespace) -> int:
+    context = load_context(args.config)
+    token = auth.load_token(context.data_dir)
+    app = create_app(lambda: load_context(args.config), token)
+    link_host = "localhost" if args.host in WILDCARD_HOSTS else args.host
+    url = f"http://{link_host}:{args.port}/?token={token}"
+    print(f"romledger dashboard: {url}", flush=True)
+    if args.open:
+        webbrowser.open(url)
+    uvicorn.run(app, host=args.host, port=args.port, access_log=False)
+    return 0
+
+
+def run_canary(args: argparse.Namespace) -> int:
+    with http.client() as client:
+        report = canary.run(
+            client,
+            http.Throttle(),
+            registry.load(),
+            registry.ignored(),
+            token=os.environ.get("GITHUB_TOKEN"),
+        )
+    if args.json:
+        payload = {
+            "findings": [dataclasses.asdict(finding) for finding in report.findings],
+            "inconclusive": report.inconclusive,
+        }
+        print(json.dumps(payload, indent=2))
+    else:
+        for finding in report.findings:
+            print(f"finding {finding.key}: {finding.title}")
+    diagnostics = sys.stderr if args.json else sys.stdout
+    for note in report.notes:
+        print(f"note: {note}", file=diagnostics)
+    if not args.json:
+        for prefix in report.inconclusive:
+            print(f"unverified {prefix}")
+    return 1 if report.findings else 0
+
+
+HANDLERS: dict[str, Callable[[argparse.Namespace], int]] = {
+    "config": show_config,
+    "dats update": update_dats,
+    "dats index": index_dats,
+    "scan": scan_platforms,
+    "import": import_games,
+    "fetch": fetch_games,
+    "status": show_status,
+    "missing": show_missing,
+    "canary": run_canary,
+    "serve": serve,
+}
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        return HANDLERS[args.command](args)
+    except (config.ConfigError, dats.DatError, igir.ToolError) as error:
+        print(f"romledger: error: {error}", file=sys.stderr)
+        return 2
+    except BrokenPipeError:
+        os.dup2(os.open(os.devnull, os.O_WRONLY), sys.stdout.fileno())
+        return 0
+    except OSError as error:
+        print(f"romledger: error: {error}", file=sys.stderr)
+        return 2