romdevtools 0.40.0 → 0.40.2

package/CHANGELOG.md

@@ -4,6 +4,48 @@ All notable changes to `romdevtools`. Dates are release dates.
 (Published as `romdev-mcp` through 0.11.0; renamed to `romdevtools` in 0.13.0 —
 the `romdev-mcp` bin is kept as an alias.)
 
+## 0.40.2 — 2026-06-11
+
+### Fixed — SNES `disasm({target:'decompile'})` treated the address as a raw file offset
+
+On SNES, `decompile` decompiled the function at raw FILE offset `address`, but
+`functions` / `cfg` / `xrefs` all report LoROM/HiROM **CPU** addresses — so the
+documented "decompile an address from `functions`" loop silently returned the
+wrong function (e.g. asking for the entry at CPU `$00:8000` decompiled file
+`0x8000` = CPU `$01:8000`, the wrong bank).
+
+Fix: SNES now lays the cart out by **24-bit CPU address** — each ROM chunk is
+placed at its CPU bank (LoROM `$bank:8000`, HiROM `$C0+bank`), with the
+`$80-$FF` FastROM (and HiROM `$40-$7F`) mirrors filled in — then decompiles at
+the CPU address directly. This fixes both the function lookup AND in-bank /
+`jsl` operand resolution (a flat-at-0 image would mis-label every cross-bank
+call). The CPU-addressed image is ~16MB sparse (zero-filled between banks); a
+real 4MB cart decompiles in ~1.2s. (No change to the `romdev-analysis*`
+packages — the fix is in the address-mapping JS.)
+
+Note: 65816 decompiler output is medium quality (variable register width, BCD/
+decimal-flag expansion, direct-page guards) — for SNES, lean on `cfg` / `xrefs`
++ targeted `decompile` of leaf routines over big dispatchers.
+
+## 0.40.1 — 2026-06-11
+
+### Fixed — Genesis `disasm({target:'decompile'})` was shifted +0x200
+
+A Genesis decompile at a caller-supplied address silently returned the function
+0x200 bytes too low (the wrong one, or an empty `{ return; }` / `halt_baddata()`),
+with no warning. `cfg` / `xrefs` / `functions` on the same address were correct —
+only `decompile` was off.
+
+Root cause: Rizin's Mega Drive loader splits a flat `.bin` into vtable / header /
+text segments and reports a non-zero address delta (`0x200`) on the code segment;
+the decompiler's address mapping honored that delta, but the raw image handed to
+Ghidra loads flat at offset 0, so the two disagreed by exactly 0x200. Fix: flat-
+cartridge platforms (Genesis, SMS, Game Gear, MSX, Game Boy / GBC) now force
+file-offset == CPU-address and ignore Rizin's segment delta. The 6502-family
+platforms were unaffected (they use a separate base-address path). Regression
+test added. (No change to the `romdev-analysis` / `romdev-analysis-decompiler`
+packages — the fix is entirely in the address-mapping JS.)
+
 ## 0.40.0 — 2026-06-11
 
 ### Reverse-engineering analysis engine — control-flow graphs, deep xrefs, function detection, and a decompiler

package/README.md

@@ -6,7 +6,15 @@ The entry point for **romdev** — vibe-code real retro games. Build, run, inspe
 npx romdevtools
 ```
 
-That's it — one command starts the local romdev **tool server** (no global install, no host compiler/emulator). Point any coding agent at it three ways:
+**What you get:**
+
+- **Build** — bundled per-platform toolchains (cc65, SDCC, RGBDS, asar, vasm, SGDK, PVSnesLib, libtonc, …) as WASM. Write source, compile, get a real ROM.
+- **Run + see + drive** — load the ROM into an emulated console (libretro cores as WASM), step frames, screenshot, script controller input.
+- **Inspect + romhack** — read CPU/video/save RAM, watch memory, write-breakpoints, the Cheat-Engine value-search loop, a bundled cheat database, mapper-aware disassembly, and a byte-exact rebuildable-project disassembler.
+- **Reverse-engineering analysis engine (all 14 platforms)** — control-flow graphs, deep cross-references, auto-detected functions, a one-shot structural map, and a Ghidra **decompiler** (C-like pseudocode): `disasm({target:'cfg'|'xrefs'|'functions'|'decompile'})` and `symbols({op:'analyze'})`. Understand *how* a routine works before you touch it — no $3,000 IDA license, no install.
+- **Convert assets** — PNG → platform tiles/tilemaps, quantize-to-palette, audio importers (BRR for SNES, XGM2 PCM for Genesis).
+
+Point any coding agent at it three ways:
 
 - **Plain HTTP** — `POST http://127.0.0.1:7331/tool/{name}`; browse/try every tool at `/documentation`.
 - **Agent Skill** — `GET /skills/romdev/SKILL.md` (the [Agent Skills](https://agentskills.io) standard; save it to your skills dir as `skills/romdev/SKILL.md`; ~100 tokens until invoked).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "romdevtools",
-  "version": "0.40.0",
+  "version": "0.40.2",
   "description": "Tool server giving coding agents full control of homebrew ROM development AND reverse-engineering/romhacking across 14 retro platforms (NES, SNES, GB, Genesis, Atari, C64, PC Engine, MSX, ...) via WASM toolchains + emulator cores. Use over plain HTTP, as an Agent Skill, or as an MCP server.",
   "type": "module",
   "main": "src/mcp/server.js",

package/src/analysis/analyze.js

@@ -178,7 +178,20 @@ export async function analyzeStructure(romPath, platformOverride) {
  * entry carries {from (vaddr base), delta (vaddr-paddr), to}. Returns
  * { paddr, vbase } where paddr = vaddr-delta is the raw-file offset and vbase
  * (= delta) is the address byte 0 of the file maps to on the CPU bus. */
-async function vaMapping(romBytes, arch, bits, vaddr) {
+/** Platforms whose cartridge maps 1:1 to the CPU bus (file offset == CPU
+ * address, base 0). For these we DISTRUST Rizin's IO-map delta: some of Rizin's
+ * loaders (notably the Mega Drive loader) split the image into vtable/header/
+ * text SEGMENTS and report a non-zero delta on the code segment (e.g. 0x200 for
+ * Genesis), but the raw file we hand the decompiler loads flat at VMA 0 — so the
+ * vaddr IS the file offset and any delta is a lie for our purposes. Forcing
+ * identity here fixes the "+0x200 shifted decompile" bug (a code vaddr would
+ * otherwise resolve to vaddr-0x200, the WRONG function). */
+export const FLAT_CPU_MAP = new Set(["genesis", "sms", "gg", "msx", "gb", "gbc"]);
+
+export async function vaMapping(romBytes, arch, bits, vaddr, platform) {
+  // Flat-cartridge platforms: file offset == CPU address. Ignore Rizin's
+  // segment deltas entirely.
+  if (FLAT_CPU_MAP.has(platform)) return { paddr: vaddr, vbase: 0 };
   let maps;
   try {
     maps = await runRizinJson({ romBytes, arch, bits, commands: "omlj" });
@@ -191,6 +204,69 @@ async function vaMapping(romBytes, arch, bits, vaddr) {
   return { paddr: vaddr, vbase: 0 };
 }
 
+/** Build a CPU-ADDRESSED sparse image of a SNES cart for the decompiler.
+ *
+ * SNES is banked: the langid is `65816:LE:24:snes` (24-bit space). If we hand
+ * the decompiler the flat file, a LoROM function at CPU $00:8000 lives at file
+ * 0, but its in-bank `jsr $80xx` operands resolve to file 0x80xx — bank-1 code,
+ * a plausible-but-WRONG body. So we lay each ROM chunk at its CPU address
+ * (sparse, zero-filled between), making BOTH the function address and every
+ * in-bank/JSL operand resolve. ~2x ROM size; fine at SNES cart sizes.
+ *
+ * Mirrors the detection/fold in disasm.js's mapSnesAddress (kept local to avoid
+ * a circular import: disasm.js imports analyze.js).
+ *
+ * The image is laid out BY CPU address, so the decompiler offset for a CPU
+ * address is the address itself (24-bit). @returns {{ image: Uint8Array, isLo:boolean }}
+ */
+export function buildSnesCpuImage(romBytes, mapperHint) {
+  const copierOff = (romBytes.length % 0x8000 === 0x200) ? 0x200 : 0;
+  let isLo;
+  if (mapperHint === "lorom") isLo = true;
+  else if (mapperHint === "hirom") isLo = false;
+  else {
+    const loByte = romBytes[copierOff + 0x7FC0 + 0x15];
+    const hiByte = romBytes[copierOff + 0xFFC0 + 0x15];
+    const detLo = loByte === 0x20 || loByte === 0x30 || loByte === 0x32;
+    const detHi = hiByte === 0x21 || hiByte === 0x31;
+    isLo = detHi && !detLo ? false : true; // default LoROM when ambiguous
+  }
+  const body = romBytes.subarray(copierOff);
+
+  if (isLo) {
+    // LoROM: 32KB file chunk N maps to CPU bank N, $8000-$FFFF. Banks $80-$FF
+    // MIRROR $00-$7F (the FastROM image), and code commonly runs there (a JML to
+    // $F9xxxx is bank 0x79's ROM via the $80+ mirror). So we lay the full 16MB
+    // 24-bit space and mirror each chunk into BOTH its $00-$7F home and its
+    // $80-$FF twin — otherwise a reference into the high half "can't load N
+    // bytes" and the decompiler bails.
+    const fileBanks = Math.ceil(body.length / 0x8000); // ROM chunks (≤128)
+    const image = new Uint8Array(0x1000000); // full 16MB CPU space
+    for (let b = 0; b < fileBanks; b++) {
+      const src = body.subarray(b * 0x8000, (b + 1) * 0x8000);
+      const lo = (b & 0x7F);          // home bank $00-$7F
+      image.set(src, lo * 0x10000 + 0x8000);          // $lo:8000
+      image.set(src, (lo | 0x80) * 0x10000 + 0x8000); // $(lo|80):8000 mirror
+    }
+    return { image, isLo: true };
+  }
+  // HiROM: file 64KB chunk N is CPU bank $C0+N ($0000-$FFFF, the primary image),
+  // mirrored to bank $40+N. The upper half of each chunk also appears at
+  // $00-$3F:$8000-$FFFF and $80-$BF:$8000-$FFFF. Lay the full 16MB space and
+  // mirror so any of those references resolve.
+  const fileBanks = Math.ceil(body.length / 0x10000); // 64KB chunks
+  const image = new Uint8Array(0x1000000);
+  for (let b = 0; b < fileBanks; b++) {
+    const src = body.subarray(b * 0x10000, (b + 1) * 0x10000);
+    image.set(src, (0xC0 + b) * 0x10000);             // $C0+b: full bank (primary)
+    image.set(src, (0x40 + b) * 0x10000);             // $40+b: mirror
+    const upper = src.subarray(0x8000);               // $8000-$FFFF half
+    image.set(upper, b * 0x10000 + 0x8000);           // $00+b:8000 mirror
+    image.set(upper, (0x80 + b) * 0x10000 + 0x8000);  // $80+b:8000 mirror
+  }
+  return { image, isLo: false };
+}
+
 /**
  * Decompile the function containing `address` to C pseudocode (Ghidra).
  * @returns {{platform, langid, address, code, warnings, qualityNote}}
@@ -202,13 +278,37 @@ export async function analyzeDecompile(romPath, address, platformOverride) {
   if (!SLEIGH_LANGID[platform]) throw new Error(`analyze decompile: unsupported platform '${platform}'`);
   const romBytes = new Uint8Array(await readFile(romPath));
 
+  // SNES: banked 24-bit space. `address` is a LoROM/HiROM CPU address (what
+  // target='functions'/'cfg' report). Lay the cart out by CPU address so BOTH
+  // the function address AND its in-bank/JSL operands resolve, then decompile at
+  // the CPU address directly. (Flat-at-0 would decompile file[address] — the
+  // wrong bank — and mis-label every operand.)
+  if (platform === "snes") {
+    const { image } = buildSnesCpuImage(romBytes);
+    // The image is laid out by CPU address, so the file offset IS the address.
+    const imgOff = address >>> 0;
+    if (imgOff < 0 || imgOff >= image.length) {
+      throw new Error(
+        `decompile: SNES address ${hx(address)} is outside the ${image.length}-byte CPU image ` +
+        `(is it a valid LoROM/HiROM code address?).`
+      );
+    }
+    const rs = await decompileFunction({ platform, romBytes: image, fileOffset: imgOff });
+    return {
+      platform, langid: rs.langid,
+      address, addressHex: hx(address),
+      code: rs.code, warnings: rs.warnings,
+      qualityNote: "medium (65816 variable register width)",
+    };
+  }
+
   // Use rizin's loader mapping to turn the VA (what the user sees from
   // target='functions') into the file offset the raw decompiler image needs.
   // PCE uses the 6502 plugin only for the map/loader (HuC6280 decode is the
   // decompiler's job via SLEIGH) — its flat image bases at 0 either way.
   const arch = RIZIN_ARCH[platform] ?? "6502";
   const bits = { arm: 32, m68k: 32, snes: 16 }[arch];
-  const { paddr, vbase } = await vaMapping(romBytes, arch, bits, address);
+  const { paddr, vbase } = await vaMapping(romBytes, arch, bits, address, platform);
   if (paddr < 0 || paddr >= romBytes.length) {
     throw new Error(
       `decompile: address ${hx(address)} maps to file offset ${paddr}, outside the ` +

package/src/http/skill-doc.js

@@ -19,6 +19,7 @@ import { toolJsonSchema } from "./tool-registry.js";
 export const mcpPreamble = [
   "romdev: homebrew retro game development + reverse-engineering for coding agents.",
   "All ~32 tools register at session init — call any by name directly, no loading step. Each is a domain VERB with an operation axis: memory({op}), build({output}), breakpoint({on}), cpu({op}), sprites({op}), tiles({op}), disasm({target}), romPatch({op}), …",
+  "RE engine (all 14 platforms): disasm({target:'functions'}) auto-detects functions, disasm({target:'cfg'}) graphs control flow, disasm({target:'xrefs'}) finds cross-references, disasm({target:'decompile'}) emits Ghidra C pseudocode, symbols({op:'analyze'}) maps a ROM's structure in one call.",
   "catalog({op:'categories'}) maps the tools by purpose (a guide, not a gate); catalog({op:'status'}) is a session re-orient.",
 ].join("\n");
 
@@ -27,6 +28,7 @@ export const mcpPreamble = [
  */
 export const skillPreamble = [
   "romdev gives you homebrew retro game development + reverse-engineering for ~14 platforms (NES, SNES, Game Boy, Genesis, GBA, Atari, C64, and more) — build, run, screenshot, inspect, patch, disassemble, convert assets, drive emulators.",
+  "It also ships a full RE analysis engine (Rizin + Ghidra, all 14 platforms): control-flow graphs, cross-references, auto-detected functions, a one-shot structural map, and a C-pseudocode decompiler — `disasm({target:'cfg'|'xrefs'|'functions'|'decompile'})` and `symbols({op:'analyze'})`.",
   "",
   "## Prerequisite: romdev runs LOCALLY (same machine as you)",
   "romdev bundles every compiler + emulator as WASM and runs them in-process — that engine lives in the romdev SERVER, started once with `npx romdevtools` (listens on http://localhost:7331; no other install, no host gcc/emulator needed). If a call gets connection-refused, it isn't running — start it.",