sidwizard-driver 0.2.0__py3-none-any.whl

sidwizard_driver/__init__.py

@@ -0,0 +1,16 @@
+"""sidwizard-driver — Python harness for SID-Wizard inside asid-vice."""
+
+from .d64 import build_d64_with_prg, write_d64_with_prg, write_d64_with_swm
+from .fetch import fetch_disk1_d64
+from .sidwizard import Sidwizard, SidwizardError
+
+__all__ = [
+    "Sidwizard",
+    "SidwizardError",
+    "build_d64_with_prg",
+    "fetch_disk1_d64",
+    "write_d64_with_prg",
+    "write_d64_with_swm",
+]
+
+__version__ = "0.2.0"

sidwizard_driver/capture.py

@@ -0,0 +1,191 @@
+"""Capture SID register writes from SID-Wizard's real player to CSV."""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import os
+import sys
+import tempfile
+
+from vice_driver import BinMon, DiskMount, ViceContainer, ViceContainerError
+
+from .dump import PAL_CYCLES_PER_FRAME, decode_dump_file
+from .fetch import fetch_disk1_d64
+from .sidwizard import Sidwizard, SidwizardError
+
+# SWM header: 2-byte PRG load address + 4-byte magic + framespeed byte at +4.
+SWM_FRAMESPEED_OFFSET = 2 + 0x04
+
+# anarkiwi/headlessvice's x64sc needs a writable $HOME/.local/state/vice.
+VICE_STATE_DIR = "/root/.local/state/vice"
+
+
+def _read_swm_framespeed(swm_path: str) -> int:
+    with open(swm_path, "rb") as fp:
+        head = fp.read(SWM_FRAMESPEED_OFFSET + 1)
+    if len(head) <= SWM_FRAMESPEED_OFFSET:
+        raise ValueError(f"{swm_path}: too short to read framespeed")
+    fs = head[SWM_FRAMESPEED_OFFSET]
+    if not 1 <= fs <= 4:
+        raise ValueError(f"{swm_path}: unreasonable framespeed value {fs}")
+    return fs
+
+
+log = logging.getLogger("sidwizard_driver.capture")
+
+
+def _parse_args(argv: list[str] | None) -> argparse.Namespace:  # pragma: no cover - CLI glue
+    p = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    p.add_argument("--d64", help="SID-Wizard editor .d64 (auto-fetched if omitted)")
+    p.add_argument("--swm", help="SWM module to play (required unless --smoke or --dump-only)")
+    p.add_argument("--frames", type=int, default=1500, help="number of PAL frames to capture")
+    p.add_argument("--out", required=True, help="output CSV path")
+    p.add_argument(
+        "--smoke", action="store_true", help="skip SWM load; capture default editor state"
+    )
+    p.add_argument("--dump-only", metavar="PATH", help="re-decode an existing dump file")
+    p.add_argument(
+        "--no-dedup", action="store_true", help="don't collapse consecutive duplicate writes"
+    )
+    p.add_argument("--image", default="anarkiwi/headlessvice:latest")
+    p.add_argument("--port", type=int, default=6502)
+    p.add_argument("--idle-timeout", type=float, default=60.0)
+    p.add_argument("--load-timeout", type=float, default=10.0)
+    p.add_argument("--capture-timeout", type=float, default=120.0)
+    p.add_argument(
+        "--mute-editor",
+        action="store_true",
+        help="zero $D400-$D418 at the pre-F1 checkpoint to suppress editor audition residue",
+    )
+    p.add_argument("-v", "--verbose", action="count", default=0)
+    return p.parse_args(argv)
+
+
+def _decode_to_csv(
+    dump_path: str, out_path: str, dedup: bool
+) -> int:  # pragma: no cover - CLI glue
+    with open(out_path, "w", newline="") as fp:
+        return decode_dump_file(dump_path, fp, dedup=dedup)
+
+
+def main(argv: list[str] | None = None) -> int:  # pragma: no cover - CLI entry point
+    args = _parse_args(argv)
+    logging.basicConfig(
+        level=logging.DEBUG if args.verbose >= 2 else logging.INFO,
+        format="%(asctime)s %(name)s %(levelname)s %(message)s",
+    )
+
+    if args.dump_only:
+        if not os.path.isfile(args.dump_only):
+            print(f"not a file: {args.dump_only}", file=sys.stderr)
+            return 2
+        n = _decode_to_csv(args.dump_only, args.out, dedup=not args.no_dedup)
+        print(f"wrote {n} rows to {args.out}")
+        return 0
+
+    if not args.smoke and not args.swm:
+        print("--swm is required (or pass --smoke)", file=sys.stderr)
+        return 2
+
+    if not args.d64:
+        args.d64 = str(fetch_disk1_d64())
+
+    return _run_live(args)
+
+
+def _run_live(args: argparse.Namespace) -> int:  # pragma: no cover - requires live VICE
+    if not os.path.isfile(args.d64):
+        print(f"not a file: {args.d64}", file=sys.stderr)
+        return 2
+    if args.swm and not os.path.isfile(args.swm):
+        print(f"not a file: {args.swm}", file=sys.stderr)
+        return 2
+
+    host_work_dir = tempfile.mkdtemp(prefix="sidwizard-driver-")
+    container_work_dir = "/tmp/sidwizard-driver"
+    host_dump = os.path.join(host_work_dir, "trace.txt")
+    container_dump = f"{container_work_dir}/trace.txt"
+    host_swm_d64 = os.path.join(host_work_dir, "tune.d64")
+    container_swm_d64 = f"{container_work_dir}/tune.d64"
+    host_vice_state = tempfile.mkdtemp(prefix="sidwizard-driver-vice-")
+
+    container_d64 = "/tmp/sidwizard-editor.d64"
+
+    mounts = [
+        DiskMount(host_path=args.d64, container_path=container_d64, read_only=True),
+        DiskMount(host_path=host_work_dir, container_path=container_work_dir, read_only=False),
+        DiskMount(host_path=host_vice_state, container_path=VICE_STATE_DIR, read_only=False),
+    ]
+    container = ViceContainer(
+        image=args.image,
+        entrypoint="x64sc",
+        binmon_port=args.port,
+        autostart=container_d64,
+        mounts=mounts,
+        warp=True,
+        sounddev="dump",
+        sounddump_path=container_dump,
+    )
+
+    framespeed = _read_swm_framespeed(args.swm) if args.swm else 1
+    cycles_per_frame = PAL_CYCLES_PER_FRAME // framespeed
+    target_cycles = args.frames * cycles_per_frame
+
+    start_cycle = 0
+    try:
+        with container:
+            with BinMon(port=args.port) as bm:
+                bm.exit()
+                sw = Sidwizard(bm)
+                tuneheader = sw.wait_for_idle(timeout=args.idle_timeout)
+                log.info("TUNEHEADER = $%04X", tuneheader)
+
+                if args.swm:
+                    sw.load_swm_via_menu(
+                        swm_path=args.swm,
+                        host_d64_path=host_swm_d64,
+                        container_d64_path=container_swm_d64,
+                        tuneheader=tuneheader,
+                        load_timeout=args.load_timeout,
+                    )
+
+                # Pre-arm a stop-on-hit checkpoint at $1003 (PLAYER
+                # dispatch) BEFORE F1, so frame 0 anchors to the first
+                # player tick instead of to the keypress (~0.5s of menu
+                # IRQ state).
+                pre_cp = bm.checkpoint_set(0x1003, stop_when_hit=True)
+                sw.play()
+
+                start_cycle = sw.cycle()
+                if args.mute_editor:
+                    sw.clear_sid_registers()
+                bm.checkpoint_delete(pre_cp.checknum)
+                _, end_cycle = sw.wait_for_cycles(target_cycles, timeout=args.capture_timeout)
+                log.info("captured %d cycles", end_cycle - start_cycle)
+    except ViceContainerError as e:
+        print(f"VICE container error: {e}", file=sys.stderr)
+        return 4
+    except SidwizardError as e:
+        print(f"SID-Wizard error: {e}", file=sys.stderr)
+        return 5
+
+    if not os.path.isfile(host_dump):
+        print(f"no dump file produced at {host_dump}", file=sys.stderr)
+        return 6
+
+    with open(args.out, "w", newline="") as fp:
+        n = decode_dump_file(
+            host_dump,
+            fp,
+            cycles_per_frame=cycles_per_frame,
+            dedup=not args.no_dedup,
+            start_cycle=start_cycle,
+            max_frame=args.frames - 1,
+        )
+    print(f"wrote {n} rows to {args.out} (workdir preserved at {host_work_dir})")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

sidwizard_driver/d64.py

@@ -0,0 +1,180 @@
+"""Minimal Commodore 1541 .d64 disk image writer (single PRG)."""
+
+from __future__ import annotations
+
+SECTOR_SIZE = 256
+TOTAL_SECTORS = 683
+D64_SIZE = SECTOR_SIZE * TOTAL_SECTORS  # 174848
+
+SECTORS_PER_TRACK: list[int] = (
+    [21] * 17  # tracks 1..17
+    + [19] * 7  # tracks 18..24
+    + [18] * 6  # tracks 25..30
+    + [17] * 5  # tracks 31..35
+)
+
+DIR_TRACK = 18
+BAM_SECTOR = 0
+FIRST_DIR_SECTOR = 1
+
+SECTOR_DATA = SECTOR_SIZE - 2
+
+PRG_START_TRACK = 17
+PRG_START_SECTOR = 0
+
+
+def _track_sector_offset(track: int, sector: int) -> int:
+    if not 1 <= track <= 35:
+        raise ValueError(f"track out of range: {track}")
+    spt = SECTORS_PER_TRACK[track - 1]
+    if not 0 <= sector < spt:
+        raise ValueError(f"sector {sector} out of range for track {track} (0..{spt - 1})")
+    off = 0
+    for t in range(1, track):
+        off += SECTORS_PER_TRACK[t - 1]
+    return (off + sector) * SECTOR_SIZE
+
+
+def _petscii_name(name: str, fill: int = 0xA0, length: int = 16) -> bytes:
+    up = name.upper()
+    if not all(0x20 <= ord(c) < 0x7F for c in up):
+        raise ValueError(f"filename has non-printable ASCII: {name!r}")
+    raw = up.encode("ascii")
+    if len(raw) > length:
+        raise ValueError(f"filename too long (>{length} chars): {name!r}")
+    return raw + bytes([fill] * (length - len(raw)))
+
+
+def build_d64_with_prg(
+    prg_bytes: bytes,
+    filename: str,
+    disk_name: str = "SIDWIZARD",
+    disk_id: bytes = b"01",
+) -> bytes:
+    """Return a 174848-byte d64 image containing one PRG file."""
+    if len(prg_bytes) == 0:
+        raise ValueError("prg_bytes is empty")
+    if len(disk_id) != 2:
+        raise ValueError("disk_id must be exactly 2 bytes")
+
+    image = bytearray(D64_SIZE)
+
+    needed_sectors = (len(prg_bytes) + SECTOR_DATA - 1) // SECTOR_DATA
+    spt_17 = SECTORS_PER_TRACK[PRG_START_TRACK - 1]
+    if needed_sectors > spt_17:
+        # Refuse rather than silently implementing a multi-track chain
+        # we can't test offline; SWM files in practice fit one track.
+        raise ValueError(
+            f"prg too large for single-track chain on track {PRG_START_TRACK}: "
+            f"{needed_sectors} sectors needed, {spt_17} available"
+        )
+
+    cursor = 0
+    used_sectors_on_prg_track: list[int] = []
+    for sector_index in range(needed_sectors):
+        sector_no = (PRG_START_SECTOR + sector_index) % spt_17
+        used_sectors_on_prg_track.append(sector_no)
+        is_last = sector_index == needed_sectors - 1
+        chunk = prg_bytes[cursor : cursor + SECTOR_DATA]
+        cursor += len(chunk)
+        sector_buf = bytearray(SECTOR_SIZE)
+        if is_last:
+            sector_buf[0] = 0
+            sector_buf[1] = len(chunk) + 1
+        else:
+            next_sector_no = (PRG_START_SECTOR + sector_index + 1) % spt_17
+            sector_buf[0] = PRG_START_TRACK
+            sector_buf[1] = next_sector_no
+        sector_buf[2 : 2 + len(chunk)] = chunk
+        off = _track_sector_offset(PRG_START_TRACK, sector_no)
+        image[off : off + SECTOR_SIZE] = sector_buf
+
+    dir_off = _track_sector_offset(DIR_TRACK, FIRST_DIR_SECTOR)
+    dir_sector = bytearray(SECTOR_SIZE)
+    dir_sector[0] = 0
+    dir_sector[1] = 0xFF
+    entry = dir_sector
+    entry[2] = 0x82  # closed PRG
+    entry[3] = PRG_START_TRACK
+    entry[4] = PRG_START_SECTOR
+    entry[5:21] = _petscii_name(filename, fill=0xA0, length=16)
+    entry[28:30] = b"\x00\x00"
+    size_blocks = needed_sectors
+    entry[30] = size_blocks & 0xFF
+    entry[31] = (size_blocks >> 8) & 0xFF
+
+    image[dir_off : dir_off + SECTOR_SIZE] = dir_sector
+
+    bam_off = _track_sector_offset(DIR_TRACK, BAM_SECTOR)
+    bam_sector = bytearray(SECTOR_SIZE)
+    bam_sector[0] = DIR_TRACK
+    bam_sector[1] = FIRST_DIR_SECTOR
+    bam_sector[2] = 0x41  # DOS 'A'
+    bam_sector[3] = 0x00
+
+    for track in range(1, 36):
+        spt = SECTORS_PER_TRACK[track - 1]
+        if track == DIR_TRACK:
+            free = 0
+            bitmap = 0
+        elif track == PRG_START_TRACK:
+            free = spt - len(used_sectors_on_prg_track)
+            bitmap = (1 << spt) - 1
+            for s in used_sectors_on_prg_track:
+                bitmap &= ~(1 << s)
+        else:
+            free = spt
+            bitmap = (1 << spt) - 1
+        slot = 4 + (track - 1) * 4
+        bam_sector[slot] = free
+        bam_sector[slot + 1] = bitmap & 0xFF
+        bam_sector[slot + 2] = (bitmap >> 8) & 0xFF
+        bam_sector[slot + 3] = (bitmap >> 16) & 0xFF
+
+    bam_sector[0x90:0xA0] = _petscii_name(disk_name, fill=0xA0, length=16)
+    bam_sector[0xA0] = 0xA0
+    bam_sector[0xA1] = 0xA0
+    bam_sector[0xA2:0xA4] = disk_id
+    bam_sector[0xA4] = 0xA0
+    bam_sector[0xA5] = 0x32
+    bam_sector[0xA6] = 0x41
+    bam_sector[0xA7:0xAB] = b"\xa0\xa0\xa0\xa0"
+
+    image[bam_off : bam_off + SECTOR_SIZE] = bam_sector
+
+    return bytes(image)
+
+
+def write_d64_with_prg(out_path: str, prg_bytes: bytes, filename: str) -> None:
+    image = build_d64_with_prg(prg_bytes, filename)
+    with open(out_path, "wb") as fp:
+        fp.write(image)
+
+
+def write_d64_with_swm(out_path: str, swm_path: str, filename: str | None = None) -> str:
+    """Copy an on-disk ``.swm`` into a fresh single-file d64.
+
+    SID-Wizard's ``regname`` appends ``.SWM`` to the typed filename, so
+    the on-disk name must carry the extension too. Returns the on-disk
+    filename (with extension) so the caller can drive the file dialog.
+    """
+    with open(swm_path, "rb") as fp:
+        swm_bytes = fp.read()
+    if filename is None:
+        import os
+
+        stem = os.path.splitext(os.path.basename(swm_path))[0].upper()
+        filename = stem + ".SWM"
+    write_d64_with_prg(out_path, swm_bytes, filename)
+    return filename
+
+
+__all__ = [
+    "D64_SIZE",
+    "SECTOR_SIZE",
+    "TOTAL_SECTORS",
+    "SECTORS_PER_TRACK",
+    "build_d64_with_prg",
+    "write_d64_with_prg",
+    "write_d64_with_swm",
+]

sidwizard_driver/dump.py

@@ -0,0 +1,144 @@
+"""Decoder for VICE ``sounddev=dump`` files.
+
+Each SID write produces one space-separated decimal line:
+
+    <cycle_delta> <irq_delta> <nmi_delta> <chipno> <addr> <byte>
+
+The legacy 3-field shape (``cycle_delta addr byte``, no chipno) is also
+accepted. Pass ``cycles_per_frame`` for NTSC (17095) or framespeed=2.
+"""
+
+from __future__ import annotations
+
+import csv
+from dataclasses import dataclass
+from typing import Iterable, Iterator, Optional, TextIO
+
+PAL_CYCLES_PER_FRAME = 19656
+
+SID_REG_MIN = 0x00
+SID_REG_MAX = 0x18
+
+
+@dataclass(frozen=True)
+class DumpRecord:
+    cycle: int
+    chipno: int
+    reg: int
+    value: int
+
+
+def iter_records(stream: Iterable[str]) -> Iterator[DumpRecord]:
+    """Yield ``DumpRecord`` for each dump line in ``stream``.
+
+    Tolerates a final partial line (VICE doesn't flush on shutdown),
+    but a short line followed by more data is treated as corruption.
+    """
+    abs_cycle = 0
+    pending_partial: Optional[str] = None
+    for raw in stream:
+        if pending_partial is not None:
+            raise ValueError(
+                f"unrecognised dump record (got "
+                f"{len(pending_partial.split())} fields): {pending_partial!r}"
+            )
+        line = raw.strip()
+        if not line or line.startswith("#"):
+            continue
+        parts = line.split()
+        if len(parts) == 6:
+            clks, _irq, _nmi, chipno, addr, byte = (int(p) for p in parts)
+        elif len(parts) == 3:
+            clks, addr, byte = (int(p) for p in parts)
+            chipno = 0
+        else:
+            pending_partial = line
+            continue
+        abs_cycle += clks
+        yield DumpRecord(cycle=abs_cycle, chipno=chipno, reg=addr, value=byte)
+
+
+def filter_sid(
+    records: Iterable[DumpRecord],
+    chipno: int = 0,
+    reg_min: int = SID_REG_MIN,
+    reg_max: int = SID_REG_MAX,
+) -> Iterator[DumpRecord]:
+    for r in records:
+        if r.chipno == chipno and reg_min <= r.reg <= reg_max:
+            yield r
+
+
+def quantise_to_frames(
+    records: Iterable[DumpRecord],
+    cycles_per_frame: int = PAL_CYCLES_PER_FRAME,
+    start_cycle: int = 0,
+) -> Iterator[tuple[int, int, int]]:
+    for r in records:
+        frame = (r.cycle - start_cycle) // cycles_per_frame
+        yield frame, r.reg, r.value
+
+
+def dedupe_consecutive(
+    rows: Iterable[tuple[int, int, int]],
+) -> Iterator[tuple[int, int, int]]:
+    last: dict[int, int] = {}
+    for frame, reg, value in rows:
+        prev = last.get(reg)
+        if prev == value:
+            continue
+        last[reg] = value
+        yield frame, reg, value
+
+
+def write_csv(rows: Iterable[tuple[int, int, int]], out: TextIO) -> int:
+    writer = csv.writer(out)
+    writer.writerow(["frame", "reg", "value"])
+    n = 0
+    for frame, reg, value in rows:
+        writer.writerow([frame, reg, value])
+        n += 1
+    return n
+
+
+def decode_dump_file(
+    path: str,
+    out: TextIO,
+    cycles_per_frame: int = PAL_CYCLES_PER_FRAME,
+    chipno: int = 0,
+    start_cycle: int = 0,
+    dedup: bool = True,
+    drop_pre_anchor: bool = True,
+    max_frame: Optional[int] = None,
+) -> int:
+    """Decode a dump file to CSV. Returns row count.
+
+    ``drop_pre_anchor`` discards negative frame numbers when
+    ``start_cycle > 0``. ``max_frame`` caps frames > N (trims writes
+    that leak in during container shutdown).
+    """
+
+    def _drop_negative(rows):
+        for frame, reg, value in rows:
+            if frame >= 0:
+                yield frame, reg, value
+
+    def _cap(rows, cap):
+        for frame, reg, value in rows:
+            if frame > cap:
+                return
+            yield frame, reg, value
+
+    with open(path) as fp:
+        records = iter_records(fp)
+        records = filter_sid(records, chipno=chipno)
+        rows = quantise_to_frames(
+            records, cycles_per_frame=cycles_per_frame, start_cycle=start_cycle
+        )
+        if drop_pre_anchor and start_cycle > 0:
+            rows = _drop_negative(rows)
+        if max_frame is not None:
+            rows = _cap(rows, max_frame)
+        if dedup:
+            rows = dedupe_consecutive(rows)
+        return write_csv(rows, out)

sidwizard_driver/fetch.py

@@ -0,0 +1,123 @@
+"""Fetch SID-Wizard 1.94's ``disk1.d64`` from CSDB on demand."""
+
+from __future__ import annotations
+
+import hashlib
+import logging
+import os
+import tarfile
+import tempfile
+import urllib.request
+from pathlib import Path
+
+log = logging.getLogger(__name__)
+
+SIDWIZARD_TARBALL_URL = (
+    "https://csdb.dk/getinternalfile.php/276275/SID-Wizard-1.94-with-sources.tar.gz"
+)
+SIDWIZARD_TARBALL_SHA256 = "544e36aff3fe14b7e4cf81a04c680a6883191a222754b2f0489e15349a89b559"
+SIDWIZARD_TARBALL_SIZE = 8984028
+
+DISK1_TAR_MEMBER = "SID-Wizard-1.94/SID-Wizard-1.94-disk1.d64"
+DISK1_SHA256 = "4f6896db53c07aec7e6e7377acdb337d93b632b8c965bd37ea88db71216dcc39"
+DISK1_FILENAME = "SID-Wizard-1.94-disk1.d64"
+
+
+def default_cache_dir() -> Path:
+    xdg = os.environ.get("XDG_CACHE_HOME")
+    base = Path(xdg) if xdg else Path.home() / ".cache"
+    return base / "sidwizard-driver"
+
+
+def _sha256(path: Path) -> str:
+    h = hashlib.sha256()
+    with open(path, "rb") as fp:
+        for chunk in iter(lambda: fp.read(1 << 16), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def _download(url: str, dest: Path) -> None:
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    with tempfile.NamedTemporaryFile(
+        prefix=dest.name + ".",
+        suffix=".part",
+        dir=dest.parent,
+        delete=False,
+    ) as tmp:
+        tmp_path = Path(tmp.name)
+    try:
+        log.info("downloading %s", url)
+        with urllib.request.urlopen(url) as resp, open(tmp_path, "wb") as out:
+            while True:
+                chunk = resp.read(1 << 16)
+                if not chunk:
+                    break
+                out.write(chunk)
+        os.replace(tmp_path, dest)
+    except BaseException:
+        tmp_path.unlink(missing_ok=True)
+        raise
+
+
+def fetch_disk1_d64(cache_dir: Path | None = None) -> Path:
+    """Return a path to ``SID-Wizard-1.94-disk1.d64``, fetching on demand.
+
+    Idempotent. Raises ``RuntimeError`` if SHA-256 verification fails.
+    """
+    cache = cache_dir or default_cache_dir()
+    disk1 = cache / DISK1_FILENAME
+    if disk1.is_file() and _sha256(disk1) == DISK1_SHA256:
+        return disk1
+
+    cache.mkdir(parents=True, exist_ok=True)
+    tarball = cache / "SID-Wizard-1.94-with-sources.tar.gz"
+    if not (tarball.is_file() and _sha256(tarball) == SIDWIZARD_TARBALL_SHA256):
+        _download(SIDWIZARD_TARBALL_URL, tarball)
+        got = _sha256(tarball)
+        if got != SIDWIZARD_TARBALL_SHA256:
+            tarball.unlink(missing_ok=True)
+            raise RuntimeError(
+                f"SID-Wizard tarball SHA-256 mismatch: got {got}, "
+                f"expected {SIDWIZARD_TARBALL_SHA256}"
+            )
+
+    with tarfile.open(tarball, "r:gz") as tf:
+        member = tf.getmember(DISK1_TAR_MEMBER)
+        src = tf.extractfile(member)
+        if src is None:
+            raise RuntimeError(f"tarball member {DISK1_TAR_MEMBER} is not a file")
+        with open(disk1, "wb") as out:
+            while True:
+                chunk = src.read(1 << 16)
+                if not chunk:
+                    break
+                out.write(chunk)
+
+    got = _sha256(disk1)
+    if got != DISK1_SHA256:
+        disk1.unlink(missing_ok=True)
+        raise RuntimeError(
+            f"extracted disk1.d64 SHA-256 mismatch: got {got}, expected {DISK1_SHA256}"
+        )
+    return disk1
+
+
+def main(argv: list[str] | None = None) -> int:
+    import argparse
+
+    p = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    p.add_argument("--cache-dir", type=Path, default=None)
+    p.add_argument("-v", "--verbose", action="count", default=0)
+    args = p.parse_args(argv)
+    logging.basicConfig(
+        level=logging.DEBUG if args.verbose >= 2 else logging.INFO,
+        format="%(asctime)s %(name)s %(levelname)s %(message)s",
+    )
+    path = fetch_disk1_d64(cache_dir=args.cache_dir)
+    print(path)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())