romdevtools 0.40.0 → 0.40.1

package/CHANGELOG.md

@@ -4,6 +4,25 @@ 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.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.1",
   "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" });
@@ -208,7 +221,7 @@ export async function analyzeDecompile(romPath, address, platformOverride) {
   // 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.",