romdevtools 0.71.0 → 0.71.1

package/CHANGELOG.md

@@ -4,6 +4,27 @@ 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.71.1 — 2026-06-29
+
+Feedback from the first run against the `pret/pokeruby` GBA decompilation.
+
+- **Project-mode `entry` now resolves a NESTED path** (e.g. `entry:'src/main.c'`). The
+  recursive asset staging already walked subdirs, but entry resolution stayed top-level
+  only — so any decomp/SDK-layout project whose entry isn't at the repo root failed with
+  "entry not found." Now it resolves against the recursive file set, reads the nested file
+  as the entry **source**, accepts a bare filename when it uniquely matches one nested
+  file, and errors with a "did you mean `src/…`?" hint.
+- **`platform({op:'list'})` honors the `platform` filter** — returns just that one
+  platform's row instead of the whole 17-platform matrix (the biggest token sink reported:
+  ~17 KB → ~0.8 KB for one platform). New **`slim:true`** drops the verbose per-language
+  `note` + `quirks` prose (~60× smaller); detail stays behind `op:'doc'`/`op:'capabilities'`.
+- **`platform({op:'resolve'})` surfaces the toolchain(s)** + a note that the build
+  toolchain is WASM/harness-only (was core-paths-only, forcing `node_modules` spelunking).
+- **GBA `mental_model` "What's NOT bundled"** now calls out **agbcc's absence** (the real
+  blocker for byte-exact Gen-III decomps like pokeruby/pokeemerald) and adds a "romdev's
+  build model" section: `build` is single-shot compile→ROM, the toolchain can't back an
+  external Makefile, with the confirmed host agbcc recipe for matching builds.
+
 ## 0.71.0 — 2026-06-28
 
 ### N64 / PS1 / Dreamcast reach full parity: cpuState + audioDebug + GPU-rendering helper libs + 5 examples each

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "romdevtools",
-  "version": "0.71.0",
+  "version": "0.71.1",
   "description": "Tool server giving coding agents full control of homebrew ROM development AND reverse-engineering/romhacking across 17 retro platforms (NES, SNES, GB, Genesis, Atari, C64, PC Engine, MSX, PlayStation, N64, Dreamcast, ...) 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/mcp/tools/platforms.js

@@ -93,9 +93,17 @@ const PLATFORM_QUIRKS = {
 };
 
 /** op:'list' — every platform with core/toolchains/languages/quirks. */
-export function listPlatformsCore() {
+export function listPlatformsCore({ platform, slim } = {}) {
       const available = new Set(listAvailableCores());
-      const platforms = Object.entries(CORES).map(([id, info]) => {
+      let ids = Object.keys(CORES);
+      if (platform) {
+        if (!CORES[platform]) {
+          throw new Error(`platform({op:'list'}): unknown platform '${platform}'. Known: ${ids.join(", ")}.`);
+        }
+        ids = [platform]; // per-platform filter — the big token-sink fix (v0.71.0 fb)
+      }
+      const platforms = ids.map((id) => {
+        const info = CORES[id];
         const toolchains = Object.values(TOOLCHAINS)
           .filter((t) => t.platforms.includes(id))
           .map((t) => ({ id: t.id, displayName: t.displayName, tier: t.tier }));
@@ -107,18 +115,45 @@ export function listPlatformsCore() {
           toolchains,
         };
         const langs = getLanguageOptions(id);
-        if (langs) entry.languages = langs;
-        if (PLATFORM_QUIRKS[id]) entry.quirks = PLATFORM_QUIRKS[id];
+        if (langs) {
+          // `slim` drops the heavy per-language `note` + `quirks` prose (the big
+          // token sink when you only need "which platforms/toolchains/languages
+          // exist"). Detail stays behind platform({op:'doc'}) + op:'capabilities'.
+          entry.languages = slim
+            ? { defaultLanguage: langs.defaultLanguage,
+                languages: (langs.languages || []).map((l) => ({ language: l.language, toolchain: l.toolchain, available: l.available })) }
+            : langs;
+        }
+        if (!slim && PLATFORM_QUIRKS[id]) entry.quirks = PLATFORM_QUIRKS[id];
         return entry;
       });
-      return { platforms };
+      // A single-platform query returns just that row (not wrapped in `platforms[]`).
+      return platform ? platforms[0] : { platforms };
 }
 
-/** op:'resolve' — resolved core paths for a platform (debugging aid). */
+/** op:'resolve' — resolved core paths + the toolchain summary for a platform. */
 export function resolvePlatformCore({ platform }) {
       const r = resolveCore(platform);
       if (!r) throw new Error(`no core available for platform '${platform}'`);
-      return r;
+      // Also surface the toolchain(s) — resolve used to report only the emulator
+      // core, so agents had to spelunk node_modules to learn the build path (v0.71.0
+      // fb #3). We do NOT hand out the WASM/.mjs artifact paths: those tools run ONLY
+      // inside romdev's `build` worker harness (virtual FS), so a node_modules path
+      // invites the wrong mental model (shimming them into an external Makefile —
+      // which does NOT work). The `note` states that plainly (fb #4/#5).
+      const toolchains = Object.values(TOOLCHAINS)
+        .filter((t) => t.platforms.includes(platform))
+        .map((t) => ({ id: t.id, displayName: t.displayName, tier: t.tier }));
+      return {
+        ...r,
+        toolchains,
+        toolchainNote:
+          "Build via the `build` tool (it compiles a source set into one ROM). The toolchain " +
+          "binaries are WASM, run ONLY inside romdev's build worker (virtual FS) — they are NOT " +
+          "host-callable and CANNOT back an external project's Makefile. For an existing decomp/" +
+          "romhack that needs its own legacy compiler (e.g. agbcc) + Makefile, build it on the host " +
+          "and use romdev to run/inspect/debug the resulting ROM.",
+      };
 }
 
 export function registerPlatformTools(server, z) {
@@ -142,14 +177,15 @@ export function registerPlatformTools(server, z) {
     "troubleshooting / upstream_sources; `platform:'romhacking'` + `name:'playbook'` for the RE decision tree). " +
     "Read MENTAL_MODEL before writing code, and the romhacking playbook before a hack.",
     {
-      op: z.enum(["list", "capabilities", "resolve", "toolchains", "docs", "doc"]).describe("list=platforms; capabilities=per-platform op support matrix; resolve=core paths; toolchains; docs=a platform's doc names; doc=read one doc."),
-      platform: z.string().optional().describe("op=resolve/docs/doc: platform id (e.g. nes, gb, genesis; 'romhacking' for the RE playbook)."),
+      op: z.enum(["list", "capabilities", "resolve", "toolchains", "docs", "doc"]).describe("list=platforms (pass `platform` to get just ONE, `slim:true` to drop the verbose notes); capabilities=per-platform op support matrix; resolve=core + toolchain artifact paths; toolchains; docs=a platform's doc names; doc=read one doc."),
+      platform: z.string().optional().describe("op=list/resolve/docs/doc/capabilities: platform id (e.g. nes, gb, genesis; 'romhacking' for the RE playbook). On op=list it filters to that ONE platform's row instead of the whole matrix (big token saver)."),
+      slim: z.boolean().optional().describe("op=list: drop the heavy per-language `note` + `quirks` prose; return just {platform, toolchains[], languages{defaultLanguage,…}}. Detail stays behind op:'doc' / op:'capabilities'."),
       id: z.string().optional().describe("op=toolchains: a specific toolchain's install status (e.g. 'cc65')."),
       name: z.string().optional().describe("op=doc: which doc — mental_model | troubleshooting | upstream_sources | playbook."),
     },
     safeTool(async (args) => {
       switch (args.op) {
-        case "list":    return jsonContent(listPlatformsCore());
+        case "list":    return jsonContent(listPlatformsCore({ platform: args.platform, slim: args.slim }));
         case "capabilities": {
           if (args.platform) {
             const cap = capabilitiesFor(args.platform);

package/src/mcp/tools/toolchain.js

@@ -977,16 +977,33 @@ export async function readProjectDir(projPath, platform, opts = {}) {
   const subAssets = await walkSubdirAssets(projPath);
 
   // Entry override: an existing project whose top file isn't main.* (e.g.
-  // smw.asm). Accept a project-relative or bare name; it becomes the single
-  // entry source. Without it, auto-detect main.c / main.s / main.asm.
-  const entryName = opts.entry ? path.normalize(opts.entry).replace(/^[./]+/, "") : null;
+  // smw.asm) OR is nested (e.g. src/main.c — common for decomps/SDK projects).
+  // Accept a project-relative path or a bare name; it becomes the single entry
+  // source. Resolve against BOTH the top-level files AND the recursively staged
+  // subdir set, with POSIX slashes (`path.normalize` may emit `\` on Windows).
+  const entryName = opts.entry
+    ? path.normalize(opts.entry).replace(/\\/g, "/").replace(/^[./]+/, "")
+    : null;
+  // The resolved {rel, abs} for the entry when it's nested in a subdirectory.
+  let entrySubAsset = null;
   if (entryName) {
-    const exists = files.some((f) => f.name === entryName) ||
-      subAssets.some((a) => a.rel === entryName);
-    if (!exists) {
+    const topMatch = files.some((f) => f.name === entryName);
+    entrySubAsset = subAssets.find((a) => a.rel === entryName) || null;
+    // Bare-filename fallback: `entry:'main.c'` matches `src/main.c` if unique.
+    if (!topMatch && !entrySubAsset && !entryName.includes("/")) {
+      const byBase = subAssets.filter((a) => a.rel.split("/").pop() === entryName);
+      if (byBase.length === 1) entrySubAsset = byBase[0];
+    }
+    if (!topMatch && !entrySubAsset) {
+      const nearby = subAssets
+        .filter((a) => a.rel.split("/").pop() === entryName.split("/").pop())
+        .map((a) => a.rel).slice(0, 8);
       throw new Error(
-        `entry '${entryName}' not found in ${projPath}. Found top-level: ` +
-        `${files.map((f) => f.name).join(", ") || "(none)"}.`
+        `entry '${entryName}' not found in ${projPath}. ` +
+        (nearby.length
+          ? `Did you mean: ${nearby.join(", ")}? (entry is project-relative — e.g. 'src/main.c'.)`
+          : `Top-level: ${files.map((f) => f.name).join(", ") || "(none)"}. ` +
+            `entry is project-relative — pass the path under the repo root (e.g. 'src/main.c').`)
       );
     }
   }
@@ -1006,7 +1023,7 @@ export async function readProjectDir(projPath, platform, opts = {}) {
   // the dir build matches the hand-written build({output:'run'}) call.
   const recipe = projectBuildRecipe(platform, files.map((f) => f.name));
 
-  // With a custom entry, the entry is the ONE source; every OTHER top-level
+  // With a custom ASM entry, the entry is the ONE source; every OTHER top-level
   // .asm/.s/.c routes as an include (asar/wla resolve `.include`/`#include`
   // from the includes mount), matching the single-source asm model.
   if (entryName && /\.(asm|s)$/i.test(entryName)) {
@@ -1040,7 +1057,7 @@ export async function readProjectDir(projPath, platform, opts = {}) {
   // the mount. Text-ish includes (.asm/.s/.h/.inc) found in subdirs go to includes
   // (so `incsrc "lib/foo.asm"` works); everything else is a binary asset.
   for (const a of subAssets) {
-    if (recipe.skip.has(a.rel) || a.rel === entryName) continue;
+    if (recipe.skip.has(a.rel) || a.rel === entrySubAsset?.rel) continue;
     if (/\.(h|inc|asm|s)$/i.test(a.rel)) {
       includes[a.rel] = (await readFile(a.abs)).toString("utf-8");
     } else {
@@ -1048,6 +1065,14 @@ export async function readProjectDir(projPath, platform, opts = {}) {
     }
   }
 
+  // A NESTED entry (e.g. src/main.c) is read here as the entry SOURCE — the
+  // top-level loop above only sees root files, so a subdir entry would otherwise
+  // never compile. Keyed by its relative path so #include/.include resolution
+  // from the same subdir works.
+  if (entrySubAsset) {
+    sources[entrySubAsset.rel] = (await readFile(entrySubAsset.abs)).toString("utf-8");
+  }
+
   // SMS/GG with no crt0 file in the dir → fall back to the bundled crt0,
   // exactly like the output:'rom'/'run' handlers do. Without this the link
   // silently uses SDCC's stock z80 crt0, which never calls main() (black

package/src/platforms/gba/MENTAL_MODEL.md

@@ -248,6 +248,11 @@ Loadable via mGBA (`loadMedia`).
 
 ## What's NOT bundled
 
+- **`agbcc` (the legacy GBA compiler).** romdev's GBA C path is **modern
+  `arm-none-eabi-gcc` 14.2.0** only. The byte-exact decompilations + romhacks
+  (pokeruby / pokeemerald / pokefirered, etc.) build with agbcc + a custom
+  `ld_script.txt`, so romdev **cannot reproduce a matching retail ROM** for those.
+  That's a hard limit, not a missing feature — see "romdev's build model" below.
 - **libgba's `console.c`** (iprintf-style stdio output). Pulls in
   devkitPro's libsysbase header chain — not yet ported. See
   TROUBLESHOOTING.md for the trade-off rationale and workarounds.
@@ -256,7 +261,23 @@ Loadable via mGBA (`loadMedia`).
 - **devkitARM's `bin2s`** (binary → assembly converter for asset
   pipelines). Not bundled; ship binary assets as C arrays for now.
 
-Everything else from a stock devkitARM install works.
+Everything else from a stock devkitARM install (homebrew-style) works.
+
+## romdev's build model (read this before driving an existing project)
+
+`build` is a **single-shot "compile these sources → one ROM" tool**, NOT an arbitrary
+build-system backend. The toolchain binaries are **WASM, run only inside romdev's build
+worker (virtual FS)** — they are **not host-callable** and **cannot back an external
+project's `Makefile`** as `$(TOOLCHAIN)/bin`. (The `.mjs` wrappers under `node_modules`
+export a worker factory, not a CLI `main` — invoking one directly exits 0 and writes
+nothing.)
+
+So for an **existing decomp/romhack** (agbcc-era or any project with its own Makefile):
+build it **on the host** with its own toolchain, then point romdev at the resulting
+`.gba` for the run / inspect / debug / decompile loop. Confirmed host recipe for the
+Pokémon Gen-III decomps: `brew install arm-none-eabi-gcc arm-none-eabi-binutils`, clone
+`pret/agbcc` → `./build.sh` → `./install.sh <repo>`, then `make <target>` (yields a
+byte-matching ROM). romdev's value here is everything AFTER the build, not the build.
 
 ## Horizontal scrolling (for side-scrollers)