romdevtools 0.13.0

package/src/cheats/lookup.js

@@ -0,0 +1,262 @@
+// Match a ROM to the bundled cheat index and return its decoded entries.
+//
+// CONFIDENCE — the trust model (same discipline as byte-exact disasm: never
+// overclaim). Three tiers, always reported so the agent knows how much to trust
+// the labels:
+//   "name"     — matched by No-Intro game name derived from the file. We do NOT
+//                have a CRC database to confirm the exact dump, so this is a
+//                PROBABLE match: the labels are very likely right but the tool
+//                MUST tell the agent it cannot positively identify the ROM.
+//   "filename" — matched by the file's basename alone (weaker than a parsed
+//                No-Intro name). Probable, lower confidence.
+//   "none"     — no match; return nothing rather than guess.
+// (A future "crc" tier would confirm via a No-Intro DAT; not bundled yet.)
+
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { existsSync } from "node:fs";
+import Fuse from "fuse.js";
+
+// The cheat index lives in the romdev_game_codes package (kept separate so the
+// main package stays small and the DB versions on its own cadence). Resolve its
+// index/ directory once via the package's module URL — same pattern the core
+// registry uses (import.meta.resolve). Fall back to a sibling ./index dir for
+// dev checkouts where the package isn't linked yet.
+function resolveIndexDir() {
+  try {
+    const pkgUrl = import.meta.resolve("romdev_game_codes");
+    return path.join(path.dirname(fileURLToPath(pkgUrl)), "index");
+  } catch {
+    return path.join(path.dirname(fileURLToPath(import.meta.url)), "index");
+  }
+}
+const INDEX_DIR = resolveIndexDir();
+
+// CRC32 (IEEE) — computed but currently informational (no DAT to verify
+// against). Returned in the result so callers/users can cross-check externally.
+let _crcTable = null;
+function crc32(bytes) {
+  if (!_crcTable) {
+    _crcTable = new Uint32Array(256);
+    for (let n = 0; n < 256; n++) {
+      let c = n;
+      for (let k = 0; k < 8; k++) c = (c & 1) ? (0xedb88320 ^ (c >>> 1)) : (c >>> 1);
+      _crcTable[n] = c >>> 0;
+    }
+  }
+  let crc = 0xffffffff;
+  for (let i = 0; i < bytes.length; i++) crc = _crcTable[(crc ^ bytes[i]) & 0xff] ^ (crc >>> 8);
+  return ((crc ^ 0xffffffff) >>> 0);
+}
+
+const _indexCache = new Map(); // platform → parsed index (or null)
+async function loadIndex(platform) {
+  if (_indexCache.has(platform)) return _indexCache.get(platform);
+  const p = path.join(INDEX_DIR, `${platform}.json`);
+  let idx = null;
+  if (existsSync(p)) {
+    try { idx = JSON.parse(await readFile(p, "utf8")); } catch { idx = null; }
+  }
+  _indexCache.set(platform, idx);
+  return idx;
+}
+
+// Per-platform Fuse index, built lazily and cached. We do NOT let Fuse search
+// the raw No-Intro names directly — those are dominated by region/revision tags
+// (`(World)`, `(USA, Europe)`, `(Rev A)`) that swamp the fuzzy distance. Instead
+// we index the TAG-STRIPPED baseName as the search key (Fuse handles typos +
+// word-order/substring fuzz; baseName handles the tag noise), and keep the raw
+// `game` name + `cheats` count on each record for display. Same library +
+// ignoreLocation:true config loukai uses for media search.
+const _fuseCache = new Map(); // platform → Fuse | null
+async function getFuse(platform) {
+  if (_fuseCache.has(platform)) return _fuseCache.get(platform);
+  const idx = await loadIndex(platform);
+  if (!idx || !idx.games) { _fuseCache.set(platform, null); return null; }
+  const records = Object.keys(idx.games).map((game) => ({
+    game,                       // raw No-Intro name (for display/return)
+    base: baseName(game),       // tag-stripped key Fuse searches
+    cheats: (idx.games[game] || []).length,
+  }));
+  const fuse = new Fuse(records, {
+    keys: ["base"],
+    threshold: 0.3,        // 0 = exact, 1 = match anything (loukai's media-search default)
+    ignoreLocation: true,  // match anywhere in the name, not just the start
+    includeScore: true,    // Fuse score is a DISTANCE: 0 = perfect, 1 = worst
+    findAllMatches: true,
+    minMatchCharLength: 2,
+  });
+  _fuseCache.set(platform, fuse);
+  return fuse;
+}
+
+// Fuse returns a distance (0 best). Convert to a 0..1 SIMILARITY for our API
+// (1 best) so the returned `score` keeps its old meaning for callers.
+function simFromFuse(distance) {
+  return Math.round((1 - (distance ?? 1)) * 100) / 100;
+}
+
+// Normalize a name for fuzzy comparison: lowercase, drop extension, collapse
+// whitespace. We do NOT strip region/revision tags — those distinguish dumps
+// (USA vs Japan have different addresses), so an EXACT match must keep them.
+function normalize(name) {
+  return name.toLowerCase().replace(/\.[a-z0-9]+$/i, "").replace(/\s+/g, " ").trim();
+}
+
+// A "base name" with region/revision/dump tags stripped — for FUZZY matching
+// only. "(World)", "(USA, Europe)", "(Rev A)", "[!]", "(Action Replay)" etc. are
+// dropped and separators normalized, so "NBA Jam - Tournament Edition (World)",
+// "NBA Jam Tournament Edition", and "NBA Jam - Tournament Edition (USA) (Rev 1)"
+// collapse to the same key. Used as a fallback when exact match fails.
+function baseName(name) {
+  return name
+    .toLowerCase()
+    .replace(/\.[a-z0-9]+$/i, "")          // extension
+    .replace(/\([^)]*\)/g, " ")            // (World), (Rev A), (USA, Europe), ...
+    .replace(/\[[^\]]*\]/g, " ")           // [!], [b1], ...
+    .replace(/[-_:]/g, " ")                // separators
+    .replace(/[^a-z0-9 ]/g, " ")           // punctuation
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+/**
+ * Fuzzy-search a platform's cheat index by game name. Returns the best-matching
+ * game names + cheat counts WITHOUT dumping the whole DB — so an agent can find
+ * "NBA Jam Tournament" → the real entry without a huge context load.
+ * @param {object} a
+ * @param {string} a.platform
+ * @param {string} a.query
+ * @param {number} [a.limit]
+ * @param {number} [a.minScore]
+ * @returns {Promise<{platform:string, query:string, matches:Array<{game:string, score:number, cheats:number}>, gameCount:number, note:string}>}
+ */
+export async function searchCheatGames({ platform, query, limit = 12, minScore = 0.25 }) {
+  const idx = await loadIndex(platform);
+  if (!idx || !idx.games) {
+    return { platform, query, matches: [], gameCount: 0, note: `No bundled cheat index for platform '${platform}'.` };
+  }
+  const names = Object.keys(idx.games);
+  const fuse = await getFuse(platform);
+  // Search the tag-stripped query against the tag-stripped baseName index.
+  const results = fuse.search(baseName(query));
+  const matches = results
+    .map((r) => ({ game: r.item.game, score: simFromFuse(r.score), cheats: r.item.cheats }))
+    .filter((m) => m.score >= minScore)
+    .sort((a, b) => b.score - a.score || a.game.length - b.game.length)
+    .slice(0, limit);
+  return {
+    platform, query, matches,
+    gameCount: idx.gameCount ?? names.length,
+    note: matches.length === 0
+      ? `No game in the ${platform} cheat DB (${names.length} games) is close to "${query}". Try fewer/looser words.`
+      : `${matches.length} candidate(s) by fuzzy name match (region/revision tags ignored, typo-tolerant). Pass an exact \`game\` to cheats({op:'lookup'}) (it also fuzzy-matches). Score is name similarity, not a content guarantee — verify a label before patching.`,
+  };
+}
+
+/**
+ * Look up cheats for a ROM.
+ * @param {object} a
+ * @param {string} a.platform   our platform id (nes/gb/genesis/...)
+ * @param {string} [a.romName]  No-Intro-style name (from identifyRom), preferred
+ * @param {string} [a.fileName] the ROM file's basename, fallback match
+ * @param {Uint8Array} [a.bytes] ROM bytes, for the informational CRC32
+ * @returns {Promise<{matched:boolean, confidence:string, game?:string,
+ *   platform:string, crc32?:string, entries?:Array, note:string}>}
+ */
+export async function lookupCheats({ platform, romName, fileName, bytes }) {
+  const idx = await loadIndex(platform);
+  const crc = bytes ? crc32(bytes).toString(16).padStart(8, "0").toUpperCase() : undefined;
+  if (!idx || !idx.games) {
+    return {
+      matched: false, confidence: "none", platform,
+      ...(crc ? { crc32: crc } : {}),
+      note: `No bundled cheat index for platform '${platform}'.`,
+    };
+  }
+
+  const names = Object.keys(idx.games);
+  const want = romName ? normalize(romName) : null;
+  const wantFile = fileName ? normalize(fileName) : null;
+
+  // 1. Exact No-Intro name match (strongest available).
+  let hit = null, confidence = "none";
+  if (want) {
+    hit = names.find((n) => normalize(n) === want);
+    if (hit) confidence = "name";
+  }
+  // 2. Fall back to filename match.
+  if (!hit && wantFile) {
+    hit = names.find((n) => normalize(n) === wantFile);
+    if (hit) confidence = "filename";
+    // 2b. lenient: filename is a prefix of a DB name (drops "(USA)" etc.)
+    if (!hit) {
+      hit = names.find((n) => normalize(n).startsWith(wantFile + " ("));
+      if (hit) confidence = "filename";
+    }
+  }
+
+  // 3. FUZZY fallback (Fuse over the tag-stripped baseName). Catches the common
+  //    failure where identifyRom's name differs from the DB key by a region/
+  //    revision tag or punctuation ("NBA Jam - Tournament Edition (World)" vs a
+  //    (USA) dump or a missing hyphen), AND now typos — the entry IS in the DB,
+  //    just under a sibling name. Stricter threshold than searchCheats: this
+  //    auto-PICKS an entry, so require a strong (≤0.4 distance → ≥0.6 sim) match.
+  let fuzzyAlternatives = [];
+  if (!hit) {
+    const q = romName || fileName;
+    if (q) {
+      const fuse = await getFuse(platform);
+      const ranked = fuse.search(baseName(q))
+        .map((r) => ({ n: r.item.game, score: simFromFuse(r.score) }))
+        .filter((r) => r.score >= 0.6)
+        .sort((a, b) => b.score - a.score || a.n.length - b.n.length);
+      if (ranked.length) {
+        hit = ranked[0].n;
+        confidence = "fuzzy";
+        // Surface a few sibling matches (other regions/revisions) so the agent
+        // can pick the right dump — addresses can differ across regions.
+        fuzzyAlternatives = ranked.slice(0, 6).map((r) => r.n);
+      }
+    }
+  }
+
+  if (!hit) {
+    return {
+      matched: false, confidence: "none", platform,
+      ...(crc ? { crc32: crc } : {}),
+      note: `No cheat-DB entry matched this ROM in the bundled '${platform}' index ` +
+        `(${names.length} games). It may be an unlisted dump, a homebrew/WIP ROM, ` +
+        `or a name/revision the DB doesn't carry. Try searchCheats({platform, query}) ` +
+        `with a looser name if you think it should be there.`,
+    };
+  }
+
+  const howMatched = confidence === "name" ? "No-Intro name"
+    : confidence === "filename" ? "filename"
+    : "fuzzy name similarity (tags stripped)";
+  return {
+    matched: true,
+    confidence,
+    game: hit,
+    platform,
+    ...(crc ? { crc32: crc } : {}),
+    ...(fuzzyAlternatives.length > 1 ? { alternatives: fuzzyAlternatives } : {}),
+    entries: idx.games[hit],
+    // CRITICAL honesty: a name/filename/fuzzy match is NOT a positive identification.
+    note:
+      "PROBABLE MATCH by " + howMatched +
+      " — NOT a verified (CRC) identification. The cheat labels are very likely " +
+      "correct for this game, but a different ROM revision/region can use different " +
+      "addresses. Verify a label (e.g. apply the cheat and observe, or check the " +
+      "address in live memory) before relying on it for a patch. crc32 is provided " +
+      "for your own cross-check." +
+      (confidence === "fuzzy"
+        ? " NOTE: this was a FUZZY match — the exact dump name didn't match the DB, so I picked the closest title" +
+          (fuzzyAlternatives.length > 1 ? `; \`alternatives\` lists sibling region/revision entries — pick the one matching your ROM's region, addresses can differ.` : ".")
+        : ""),
+  };
+}
+
+export { crc32 };

package/src/cheats/parse-cht.js

@@ -0,0 +1,92 @@
+// Parser for RetroArch `.cht` cheat files.
+//
+// Format (one game per file):
+//   cheats = N
+//   cheat0_desc = "Infinite Lives"
+//   cheat0_code = "00C7:FF"          (or a Game Genie code, or +-joined combo)
+//   cheat0_enable = false
+//   cheat1_desc = ...
+//
+// We parse this into a flat list of { desc, code } entries. Decoding the code
+// into an address/value (and classifying ram vs code) is a SEPARATE step
+// (gamegenie.js) so the parser stays format-only and testable in isolation.
+
+/**
+ * Parse `.cht` text → { count, entries: [{ index, desc, code, enable }] }.
+ * @param {string} text
+ * @param {object} [opts]
+ * @param {boolean} [opts.decimalAddrVal] When an entry uses the newer
+ *   `cheatK_address`/`cheatK_value` struct form (no `cheatK_code`), interpret
+ *   those numbers as DECIMAL and emit a hex `ADDR:VAL` code. RetroArch's MSX
+ *   (and a few other newer cores') .cht files store address/value in decimal;
+ *   the rest of our pipeline (decodeRaw) reads `ADDR:VAL` as hex, so we convert
+ *   here. Default false (legacy files already write hex in the address field).
+ */
+export function parseCht(text, opts = {}) {
+  const decimalAddrVal = !!opts.decimalAddrVal;
+  const entries = new Map(); // index → partial entry
+  let declaredCount = null;
+
+  for (const rawLine of text.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith("#") || line.startsWith(";")) continue;
+
+    const eq = line.indexOf("=");
+    if (eq < 0) continue;
+    const key = line.slice(0, eq).trim();
+    let val = line.slice(eq + 1).trim();
+    // Strip surrounding quotes from string values.
+    if (val.startsWith('"') && val.endsWith('"')) val = val.slice(1, -1);
+
+    if (key === "cheats") {
+      const n = parseInt(val, 10);
+      if (!Number.isNaN(n)) declaredCount = n;
+      continue;
+    }
+
+    // cheatK_field
+    const m = /^cheat(\d+)_(desc|code|enable|address|value)$/.exec(key);
+    if (!m) continue;
+    const idx = parseInt(m[1], 10);
+    const field = m[2];
+    let e = entries.get(idx);
+    if (!e) { e = { index: idx }; entries.set(idx, e); }
+
+    if (field === "desc") e.desc = val;
+    else if (field === "code") e.code = val;
+    else if (field === "enable") e.enable = /^true$/i.test(val);
+    // Some older .cht use cheatK_address / cheatK_value instead of _code.
+    else if (field === "address") e.address = val;
+    else if (field === "value") e.value = val;
+  }
+
+  // Normalize: an entry with address+value but no code becomes an ADDR:VAL code.
+  const list = Array.from(entries.values())
+    .sort((a, b) => a.index - b.index)
+    .map((e) => {
+      let code = e.code;
+      if (!code && e.address != null && e.value != null) {
+        if (decimalAddrVal) {
+          // Newer struct form stores decimal address/value; emit hex ADDR:VAL
+          // so the downstream hex decoder (decodeRaw) reads it correctly.
+          const a = parseInt(e.address, 10);
+          const v = parseInt(e.value, 10);
+          code = (Number.isNaN(a) || Number.isNaN(v))
+            ? null
+            : `${a.toString(16)}:${v.toString(16)}`;
+        } else {
+          code = `${e.address}:${e.value}`;
+        }
+      }
+      return { index: e.index, desc: e.desc ?? "", code: code ?? "", enable: !!e.enable };
+    })
+    .filter((e) => e.code); // drop entries with no usable code
+
+  return { count: declaredCount ?? list.length, entries: list };
+}
+
+/** Split a `+`-joined multi-code combo into its individual codes. A single
+ *  cheat may patch several locations; each sub-code decodes independently. */
+export function splitCombo(code) {
+  return String(code).split("+").map((c) => c.trim()).filter(Boolean);
+}

package/src/cli/smoke.js

@@ -0,0 +1,283 @@
+#!/usr/bin/env node
+// romdev-cli — direct CLI for the romdev host.
+//
+// End users use `play` to fire up a ROM in a window. The other subcommands
+// are smoke-test harnesses that match what the MCP tools do, useful for
+// scripting + debugging without a running MCP server.
+//
+// Usage:
+//   romdev-cli play <rom-or-zip> [--platform PLAT] [--scale N]
+//   romdev-cli identify <rom-or-zip>
+//   romdev-cli run --core <path> --rom <path> [--frames N] [--screenshot out.png]
+//
+// `play` accepts .zip files — the first ROM-shaped entry is extracted to a
+// temp file and loaded into the matching libretro core. Platform is
+// inferred from the file extension if not given.
+
+import { writeFile, mkdtemp, readdir } from "node:fs/promises";
+import { existsSync, statSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { parseArgs } from "node:util";
+import yauzl from "yauzl";
+import { LibretroHost } from "../host/index.js";
+import { framebufferToPng } from "../host/framebuffer.js";
+import { resolveCore } from "../cores/registry.js";
+
+// Extension → platform mapping. Drives auto-detection when --platform isn't
+// passed. Keep this in sync with cores/registry.js platform IDs.
+const EXT_TO_PLATFORM = {
+  ".nes": "nes",
+  ".unf": "nes",
+  ".fds": "nes",
+  ".sfc": "snes",
+  ".smc": "snes",
+  ".swc": "snes",
+  ".fig": "snes",
+  ".gb":  "gb",
+  ".gbc": "gbc",
+  ".gba": "gba",
+  ".md":  "genesis",
+  ".gen": "genesis",
+  ".smd": "genesis",
+  ".bin": "genesis",  // ambiguous; could be Genesis or other — defaults to Genesis
+  ".sms": "sms",
+  ".gg":  "gg",
+  ".a26": "atari2600",
+  ".a78": "atari7800",
+  ".lnx": "lynx",
+  ".prg": "c64",
+  ".d64": "c64",
+  ".t64": "c64",
+};
+
+// Known ROM file extensions for picking which entry in a .zip is the real
+// ROM (vs. a README, save state, etc.).
+const ROM_EXTS = new Set(Object.keys(EXT_TO_PLATFORM));
+
+function platformFromExtension(filePath) {
+  const ext = path.extname(filePath).toLowerCase();
+  return EXT_TO_PLATFORM[ext] ?? null;
+}
+
+// Extract the first ROM-looking entry from a .zip to a temp file. Returns
+// { tempPath, originalName }.
+async function extractFirstRomFromZip(zipPath) {
+  return new Promise((resolve, reject) => {
+    yauzl.open(zipPath, { lazyEntries: true }, (err, zipfile) => {
+      if (err) return reject(err);
+      let found = false;
+      zipfile.on("entry", (entry) => {
+        if (found) return;
+        const ext = path.extname(entry.fileName).toLowerCase();
+        if (!ROM_EXTS.has(ext)) {
+          zipfile.readEntry();
+          return;
+        }
+        found = true;
+        zipfile.openReadStream(entry, async (e, stream) => {
+          if (e) return reject(e);
+          const chunks = [];
+          stream.on("data", (c) => chunks.push(c));
+          stream.on("end", async () => {
+            try {
+              const dir = await mkdtemp(path.join(tmpdir(), "romdev-"));
+              const tempPath = path.join(dir, path.basename(entry.fileName));
+              await writeFile(tempPath, Buffer.concat(chunks));
+              resolve({ tempPath, originalName: entry.fileName });
+            } catch (we) {
+              reject(we);
+            }
+          });
+          stream.on("error", reject);
+        });
+      });
+      zipfile.on("end", () => {
+        if (!found) reject(new Error(`no ROM-shaped file found in ${zipPath}`));
+      });
+      zipfile.on("error", reject);
+      zipfile.readEntry();
+    });
+  });
+}
+
+async function playCommand(romPath, opts) {
+  if (!existsSync(romPath)) {
+    throw new Error(`file not found: ${romPath}`);
+  }
+
+  // Extract zip if needed
+  let actualPath = romPath;
+  let extracted = false;
+  if (path.extname(romPath).toLowerCase() === ".zip") {
+    console.error(`unzipping ${path.basename(romPath)}...`);
+    const { tempPath, originalName } = await extractFirstRomFromZip(romPath);
+    actualPath = tempPath;
+    extracted = true;
+    console.error(`  → ${originalName} (${statSync(tempPath).size} bytes)`);
+  }
+
+  // Resolve platform
+  const platform = opts.platform ?? platformFromExtension(actualPath);
+  if (!platform) {
+    throw new Error(
+      `could not infer platform from extension ${path.extname(actualPath)}. ` +
+      `Pass --platform explicitly. Known extensions: ${Object.keys(EXT_TO_PLATFORM).join(", ")}`,
+    );
+  }
+
+  const core = resolveCore(platform);
+  if (!core) {
+    throw new Error(`no bundled core for platform '${platform}'`);
+  }
+  console.error(`platform: ${platform} (${core.displayName})`);
+
+  // Load core + media
+  const host = new LibretroHost();
+  await host.loadCore(core.jsPath, core.wasmPath);
+  await host.loadMedia({ platform, path: actualPath });
+
+  // Hand off to playtest
+  const { playtest } = await import("../playtest/playtest.js");
+  const scale = opts.scale ? parseInt(opts.scale, 10) : 3;
+  const title = opts.title ?? `romdev-cli — ${path.basename(romPath)}`;
+  const aspect = opts.aspect === "tv" ? "tv" : "fb";
+  const session = await playtest({ host, scale, title, aspect });
+  await session.closed;
+  console.error("playtest closed");
+}
+
+async function identifyCommand(romPath) {
+  if (!existsSync(romPath)) throw new Error(`file not found: ${romPath}`);
+  const { identifyRomFile } = await import("../rom-id/identifier.js");
+  const info = await identifyRomFile(romPath);
+  console.log(JSON.stringify(info, null, 2));
+}
+
+async function runCommand(values) {
+  if (!values.core) throw new Error("--core <path> is required");
+  if (!values.rom)  throw new Error("--rom <path> is required");
+
+  const host = new LibretroHost();
+  await host.loadCore(values.core);
+  await host.loadMedia({
+    platform: values.platform,
+    path: values.rom,
+    mediaKind: values["media-kind"],
+  });
+
+  const n = parseInt(values.frames, 10);
+  console.error(`stepping ${n} frames...`);
+  host.stepFrames(n);
+  const status = host.getStatus();
+  console.error(`done. frame=${status.frameCount} fb=${status.fbWidth}x${status.fbHeight}`);
+
+  if (values.screenshot) {
+    const f = host.getFramebuffer();
+    const png = framebufferToPng(f.width, f.height, f.pixels, f.pitch, f.format);
+    await writeFile(values.screenshot, png);
+    console.error(`wrote ${values.screenshot} (${png.length} bytes)`);
+  }
+}
+
+function usage(exitCode = 0) {
+  console.error(`romdev-cli — homebrew retro game tooling
+
+Usage:
+  romdev-cli play <rom-or-zip> [--platform PLAT] [--scale N] [--title T] [--aspect fb|tv]
+      Open a real SDL window for any ROM. Detects platform from extension.
+      Extracts the first ROM out of a .zip automatically.
+      --aspect fb (default): window opens at raw framebuffer * scale.
+      --aspect tv: stretch to the core's reported TV aspect ratio
+                   (Atari 2600 ~4:3, SNES ~8:7, etc.).
+      Run \`romdev-cli play --help\` for the keyboard/gamepad bindings.
+
+  romdev-cli identify <rom-or-zip>
+      Print a JSON description of the ROM (platform, mapper, hash, etc.).
+
+  romdev-cli run --core <_libretro.js> --rom <path> [--frames N] [--screenshot out.png]
+      Smoke-test: step N frames headless, optionally write a PNG. For
+      pipelines that need a fast no-window verification. Most users want
+      'play' instead.
+
+Examples:
+  romdev-cli play ~/Downloads/Donkey\\ Kong\\ Country.zip
+  romdev-cli play smb1.nes --scale 4
+  romdev-cli play Adventure.a26 --aspect tv
+  romdev-cli identify rom.smc
+`);
+  process.exit(exitCode);
+}
+
+async function playHelp() {
+  const { KEYBOARD_BINDINGS_HELP } = await import("../playtest/playtest.js");
+  console.error(`romdev-cli play — open a ROM in a native window
+
+Usage:
+  romdev-cli play <rom-or-zip> [options]
+
+Options:
+  --platform <id>   Override extension-based platform detection.
+  --scale <N>       Integer upscale factor (default: 3).
+  --title <text>    Window title.
+  --aspect <mode>   'fb' (default) = raw framebuffer * scale.
+                    'tv' = stretch to the core's reported TV aspect ratio.
+
+Controls:
+${KEYBOARD_BINDINGS_HELP}
+`);
+  process.exit(0);
+}
+
+async function main() {
+  const { values, positionals } = parseArgs({
+    allowPositionals: true,
+    options: {
+      core:       { type: "string" },
+      rom:        { type: "string" },
+      frames:     { type: "string", default: "60" },
+      screenshot: { type: "string" },
+      platform:   { type: "string" },
+      "media-kind": { type: "string" },
+      scale:      { type: "string" },
+      title:      { type: "string" },
+      aspect:     { type: "string" },
+      help:       { type: "boolean", short: "h" },
+    },
+  });
+
+  const cmd = positionals[0];
+  // Global --help with no command shows top-level usage. With a command,
+  // it falls through so the command can show its own detailed help.
+  if (values.help && !cmd) usage(0);
+  if (!cmd) usage(1);
+
+  switch (cmd) {
+    case "play":
+      if (values.help) { await playHelp(); break; }
+      if (!positionals[1]) {
+        console.error("usage: romdev-cli play <rom-or-zip>  (try --help for controls)");
+        process.exit(1);
+      }
+      await playCommand(positionals[1], values);
+      break;
+    case "identify":
+      if (!positionals[1]) {
+        console.error("usage: romdev-cli identify <rom-or-zip>");
+        process.exit(1);
+      }
+      await identifyCommand(positionals[1]);
+      break;
+    case "run":
+      await runCommand(values);
+      break;
+    default:
+      console.error(`unknown command: ${cmd}`);
+      usage(1);
+  }
+}
+
+main().catch((err) => {
+  console.error(err.stack ?? err.message ?? err);
+  process.exit(1);
+});