romdevtools 0.15.0 → 0.16.0

package/AGENTS.md

@@ -43,7 +43,7 @@ Skip playtest only when there's clearly no human in the loop: CI runs, automated
 
 ## Tool surface: everything is loaded — just call the tool
 
-**All ~34 tools are registered and callable from session init — there is no loading step.** If you see a tool name anywhere in this doc or via `catalog({op:'categories'})`, you can call it right now. Each tool is a small VERB with an operation axis — `memory({op})`, `build({output})`, `sprites({op})`, `breakpoint({on})`, `cpu({op})` — so the whole surface is a few dozen names, not a few hundred.
+**All ~32 tools are registered and callable from session init — there is no loading step.** If you see a tool name anywhere in this doc or via `catalog({op:'categories'})`, you can call it right now. Each tool is a small VERB with an operation axis — `memory({op})`, `build({output})`, `sprites({op})`, `breakpoint({on})`, `cpu({op})` — so the whole surface is a few dozen names, not a few hundred.
 
 (We used to lazy-load tools behind a `loadCategory` call. It caused more harm than good — agents burned round-trips re-loading categories, and dynamic registration never propagated reliably to clients anyway. The consolidation shrank the surface enough that the entire thing loads up front; the old `loadCategory`/`describeTool` discovery tools are gone.)
 

package/CHANGELOG.md

@@ -67,6 +67,37 @@ instead of assuming the server is broken and installing their own tools.
 - The `uint8-loop-bound` preflight lint is scope-aware (no longer false-flags a
   `uint16_t` loop counter that shares a name with a `uint8_t` in another function).
 
+## 0.16.0
+
+**Build diagnostics: agents were building blind — errors AND warnings now reach
+the response as structured `issues[]`.** An agent can only fix what the toolchain
+tells it, where it tells it. Audited the whole build surface and closed the gaps
+so diagnostics (file/line/message/stage) come back in the tool result, not buried
+in the raw log. (Also bumps a doc count: the surface is 32 tools after 0.15.0's
+dmaTrace→watch / patchGbHeader→romPatch consolidation; stale "34" references in
+the docs + source comments updated.)
+
+### Fixed
+- **Warnings were OFF.** No C compiler was being asked for them. gcc (GBA/Genesis)
+  now compiles USER source with `-Wall -Wextra -Wno-unused-parameter` (the bundled
+  SDK stays warning-free so its noise doesn't bury the agent's); cc65 enables its
+  valid high-value `-W` set. So unused vars, implicit declarations, etc. are now
+  emitted and surfaced.
+- **Swallowed errors now structured:** SDCC's keyword-less `file:line: syntax
+  error: …` and `warning NNN: …` (GB/GBC/SMS/MSX previously returned an empty
+  `issues[]` on a syntax error); the sdld/ASlink `Undefined Global '_x'` link
+  error; vasm errors (Genesis asm emits no stage marker, so they hit the
+  fallback, which had skipped the vasm parser); and a **missing `incbin` asset**
+  — the #1 thing an agent forgets to pass — now reports `could not open <x.bin>`
+  with the exact filename.
+- **Fixed a build crash that ate the real error:** `build({output:'rom', path})`
+  fell into the source builder with no source and threw "Cannot read properties
+  of undefined (reading 'split')" instead of the compiler error; it now routes to
+  the project-dir builder like `output:'run'`/`'project'`.
+- Verified live across all 14 platforms; a `parse-errors-coverage` test locks the
+  formats in. (Known limit: asar/SNES-asm only yields a wrapper "aborted"
+  message — its WASM build aborts without printing line info.)
+
 ## 0.14.0
 
 **Two platform-specific top-level tools folded into their domain verbs, a

package/README.md

@@ -52,7 +52,7 @@ Agents: the server delivers [`AGENTS.md`](./AGENTS.md) as connection-time instru
 Most agents support MCP, but you don't have to use it. Run the server
 (`npx romdevtools`) and **skip wiring it into your agent's MCP
 config** — no `claude mcp add`, no `mcp.json` entry, no MCP client at all. The
-same 34 tools are reachable over plain HTTP / as an Agent Skill against the
+same 32 tools are reachable over plain HTTP / as an Agent Skill against the
 running server:
 
 - **Plain HTTP:** `POST http://127.0.0.1:7331/tool/{name}` with the args as a JSON

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "romdevtools",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "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/http/skill-doc.js

@@ -18,7 +18,7 @@ import { toolJsonSchema } from "./tool-registry.js";
  */
 export const mcpPreamble = [
   "romdev: homebrew retro game development + reverse-engineering for coding agents.",
-  "All ~34 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}), …",
+  "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}), …",
   "catalog({op:'categories'}) maps the tools by purpose (a guide, not a gate); catalog({op:'status'}) is a session re-orient.",
 ].join("\n");
 

package/src/http/tool-registry.js

@@ -1,7 +1,7 @@
 // Tool registry harvester — the single source the HTTP route/skill/OpenAPI
 // surfaces build from.
 //
-// The MCP path registers 34 tools via registerTools(server, z, sessionKey),
+// The MCP path registers 32 tools via registerTools(server, z, sessionKey),
 // where `server` is an McpServer and each handler closes over `sessionKey` for
 // per-session host isolation. The HTTP surfaces (POST /tool/{name},
 // /skills/romdev/SKILL.md, /openapi.json, /documentation) want the EXACT same handlers,

package/src/mcp/tools/index.js

@@ -1,6 +1,6 @@
 // Register MCP tools on the server.
 //
-// The surface is ~34 consolidated domain tools (memory({op}), build({output}),
+// The surface is ~32 consolidated domain tools (memory({op}), build({output}),
 // breakpoint({on}), …) and EVERY one registers at session init. There is no
 // progressive-disclosure / lean mode anymore: the dynamic loadCategory dance
 // never propagated reliably to clients (they don't re-read tools/list after a
@@ -208,7 +208,7 @@ export function registerTools(server, z, sessionKey) {
   if (!sessionKey) sessionKey = randomUUID();
   // Clear validation errors for EVERY tool registered below: turns the SDK's
   // raw JSON validation dump into a plain sentence and catches unknown/misspelled
-  // params (which the SDK otherwise drops silently). One wrap, all 34 tools.
+  // params (which the SDK otherwise drops silently). One wrap, all 32 tools.
   // This is what lets the param descriptions stay terse — the guidance lives in
   // the error (paid only on a bad call), not in every agent's initial context.
   server = withClearToolErrors(server, z);
@@ -259,7 +259,7 @@ export function registerTools(server, z, sessionKey) {
   );
 
   // loadCategory + describeTool DELETED with the progressive-disclosure path:
-  // the whole surface is ~34 tools now and every one registers at session init,
+  // the whole surface is ~32 tools now and every one registers at session init,
   // so the dynamic lean-mode dance (which never worked reliably — clients don't
   // re-read tools/list after list_changed) has no reason to exist. `catalog`
   // still exposes the category map for orientation. (See the consolidation.)
@@ -293,7 +293,7 @@ export function registerTools(server, z, sessionKey) {
   // So by default we register EVERY category at session init. listCategories
   // / loadCategory still exist (idempotent, harmless) for clients that probe
   // Register EVERY category now — there is no lean/deferred mode anymore. The
-  // surface is small enough (~34 tools) that loading it all up front is the
+  // surface is small enough (~32 tools) that loading it all up front is the
   // right call (the dynamic loadCategory dance never propagated reliably to
   // clients). `disclosure.loadCategory("all")` is just the internal "register
   // all categories" helper here, not a user-facing tool.

package/src/mcp/tools/toolchain.js

@@ -68,6 +68,7 @@ const LOG_TAIL = 1200;
 // stays visible. Left intact on failure (timing can matter when diagnosing a
 // hang/OOM). The full untrimmed log is still written to logPath when spilled.
 export function denoiseSuccessLog(log) {
+  if (typeof log !== "string") return log ?? "";
   const lines = log.split("\n");
   const kept = [];
   let inTiming = false;
@@ -657,7 +658,18 @@ export function registerToolchainTools(server, z, sessionKey) {
     },
     safeTool(async (args) => {
       switch (args.output) {
-        case "rom":          return await buildSourceImpl(args);
+        case "rom": {
+          // `build({output:'rom', path})` (a project dir, no explicit sources) is
+          // the natural "build my scaffolded dir to a ROM file" call. Route it to
+          // the dir builder (same recipe as output:'project'/'run') — otherwise it
+          // fell into buildSourceImpl with no source and crashed on an undefined
+          // log. With path AND explicit sources, the sources win (manual build).
+          if (args.path && args.source == null && args.sources == null &&
+              args.sourcePath == null && args.sourcesPaths == null) {
+            return await buildProjectImpl(args);
+          }
+          return await buildSourceImpl(args);
+        }
         case "run":          return await runSourceImpl(args);
         case "project": {
           if (!args.path) throw new Error("build({output:'project'}): `path` (the project directory) is required.");

package/src/toolchains/cc65/cc65.js

@@ -257,7 +257,14 @@ export function parseRamUsage(mapText) {
  * @param {string} [args.linkerConfig] custom ld65 .cfg (overrides per-target default)
  */
 export async function buildC(args) {
-  const ccOpts = args.debug ? ["-g"] : [];
+  // Enable cc65's high-value warnings so the agent SEES real bugs (parsed into
+  // structured issues[]). These are the valid cc65 -W names that catch actual
+  // mistakes; unused-param is left off (scaffold callbacks commonly ignore
+  // params). cc65's warning set is thin to begin with, but errors always surface
+  // and these are pure upside. (NOTE: cc65 errors on an unknown -W name, so this
+  // list is verified valid against the bundled cc65.)
+  const ccWarn = ["-W", "unused-var,unused-func,unused-label,const-comparison,struct-param,pointer-sign"];
+  const ccOpts = args.debug ? ["-g", ...ccWarn] : [...ccWarn];
   const caOpts = args.debug ? ["-g"] : [];
   const sources = normalizeSources(args, "main.c");
 

package/src/toolchains/gba-c/gba-c.js

@@ -92,7 +92,12 @@ export async function buildGbaC(args) {
   // per-symbol `.bss.<name>`/`.data.<name>` line — that's what lets
   // symbols({op:'resolve'}) turn a static C global's name into an address on GBA
   // (same as SGDK does for Genesis). Pure metadata; no codegen change to what's kept.
-  const cc1Options = args.cc1Options ?? ["-O2", "-mthumb", "-ffunction-sections", "-fdata-sections"];
+  // -Wall -Wextra so the agent SEES warnings (unused vars, implicit decls,
+  // sign-compare, etc.) — they're parsed into structured issues[]. Without these
+  // gcc is silent and agents build blind. -Wno-unused-parameter keeps the common
+  // intentional `(void)`-style scaffold params from being noise. Applied to USER
+  // .c only (the libtonc/maxmod SDK is a prebuilt seed, not recompiled here).
+  const cc1Options = args.cc1Options ?? ["-O2", "-mthumb", "-ffunction-sections", "-fdata-sections", "-Wall", "-Wextra", "-Wno-unused-parameter"];
   const sources = normalizeGbaSources(args);
   const binaryIncludes = args.binaryIncludes ?? {};
 

package/src/toolchains/genesis-c/genesis-c.js

@@ -264,6 +264,12 @@ async function buildWithSgdk({ sources, headers, binaryIncludes, cc1Options, reb
     "-fdata-sections",
     ...cc1Options,
   ];
+  // USER source gets warnings on so the agent SEES its bugs (unused vars,
+  // implicit decls, …) parsed into structured issues[]. The SGDK runtime is
+  // compiled WITHOUT these (sgdkCc1Options) — we can't fix SDK warnings and they'd
+  // bury the agent's own. -Wno-unused-parameter avoids the common `(void)hard`
+  // scaffold-param noise.
+  const userCc1Options = [...sgdkCc1Options, "-Wall", "-Wextra", "-Wno-unused-parameter"];
 
   // ── Stage A: gather SGDK headers (visible to tcc via tcc-style flat mount) ──
   // cc1's -iquote /work picks up sibling files mounted alongside main.c.
@@ -280,7 +286,7 @@ async function buildWithSgdk({ sources, headers, binaryIncludes, cc1Options, reb
     const cc = await runCc1m68k({
       source: sources[cName],
       headers: tccHeaders,
-      options: sgdkCc1Options,
+      options: userCc1Options,
     });
     log += `--- cc1 (${cName}) ---\n` + (cc.log || "(ok)") + "\n";
     if (cc.exitCode !== 0 || !cc.asmSource) {
@@ -469,12 +475,14 @@ async function buildMinimal(args) {
   // ── Stage 1: compile each .c file via cc1 → .s ─────────────────
   /** @type {Record<string, Uint8Array>} */
   const userObjs = {};
+  // User .c gets warnings on (minimal path has no SDK to flood). See buildWithSgdk.
+  const userCc1Options = [...cc1Options, "-Wall", "-Wextra", "-Wno-unused-parameter"];
   const cFiles = Object.keys(sources).filter((n) => /\.c$/i.test(n));
   for (const cName of cFiles) {
     const cc = await runCc1m68k({
       source: sources[cName],
       headers,
-      options: cc1Options,
+      options: userCc1Options,
     });
     log += `--- cc1 (${cName}) ---\n` + (cc.log || "(ok)") + "\n";
     if (cc.exitCode !== 0 || !cc.asmSource) {

package/src/toolchains/parse-errors.js

@@ -41,10 +41,12 @@ export function parseBuildLog(log) {
     } else if (/^vasm/.test(baseStage)) {
       issues.push(...parseVasm(text));
     } else if (/^sdcc$|^sdasz80$|^sdasgb$|^sdld$|^mcpp$/.test(baseStage)) {
-      // SDCC family: sdcc / sdasz80 / sdasgb / sdld / mcpp emit cc65-style
-      // `file:line: severity: msg` errors. Tag with the actual originating
-      // tool, not "asar" (the old fallback was wrong).
+      // SDCC family: sdcc / sdasz80 / sdasgb / sdld / mcpp. Some diagnostics use
+      // the cc65-style `file:line: Error: msg`; SDCC's frontend ALSO emits a
+      // keyword-less form — `main.c:2: syntax error: token -> ';' ; column 44`
+      // and `main.c:N: warning NNN: msg` — which parseCc65Like misses. Run both.
       issues.push(...parseCc65Like(text, baseStage));
+      issues.push(...parseSdcc(text, baseStage));
     } else if (/^wla|^wlalink|^wladx/.test(baseStage)) {
       // SNES C path: wla-65816 assembler + wlalink linker. wlalink floods a
       // symbol-table dump on failure — parseWla extracts just the diagnostics.
@@ -60,11 +62,18 @@ export function parseBuildLog(log) {
       // Tag everything with the (possibly empty) actual stage name so an
       // assembler error doesn't mistakenly report as "asar" on a non-SNES
       // build.
+      // Try EVERY parser — some toolchains (vasm genesis-asm) emit no
+      // "--- stage ---" marker, so the whole log lands here unnamed; if we skip
+      // a parser the error is silently swallowed (issues[] empty on a real
+      // failure). Include vasm + sdcc + wla, which the old fallback omitted.
       const tag = baseStage || "unknown";
       issues.push(...parseCc65Like(text, tag));
+      issues.push(...parseSdcc(text, tag));
       issues.push(...parseDasm(text));
       issues.push(...parseAsar(text, tag));
       issues.push(...parseRgbds(text, tag));
+      issues.push(...parseVasm(text));
+      issues.push(...parseWla(text, tag));
       issues.push(...parseGnuToolchain(text, tag));
     }
   }
@@ -122,6 +131,57 @@ function parseCc65Like(text, stage) {
   return out;
 }
 
+// SDCC's keyword-less diagnostics that parseCc65Like (which requires an explicit
+// "Error:"/"Warning:" word) doesn't catch:
+//   /work/main.c:2: syntax error: token -> ';' ; column 44
+//   /work/main.c:7: warning 112: function 'foo' implicit declaration
+//   /work/main.c:9: error 20: undefined identifier 'x'
+// We classify by the leading word after `file:line:` (syntax error / error / warning).
+function parseSdcc(text, stage) {
+  const out = [];
+  const re = /^(?<file>[^\n:]+):(?<line>\d+):\s*(?<kind>syntax error|error(?:\s+\d+)?|warning(?:\s+\d+)?):?\s*(?<msg>.*)$/gm;
+  let m;
+  while ((m = re.exec(text))) {
+    const kind = m.groups.kind.toLowerCase();
+    // Skip the forms parseCc65Like already caught ("Error:" capitalized w/ colon)
+    // — this regex is case-insensitive on `error`/`warning`, but parseCc65Like
+    // only matches when a colon immediately follows the keyword AND it's
+    // capitalized; SDCC's lowercase keyword-less form is what we add here.
+    const severity = kind.startsWith("warning") ? "warning"
+      : (kind.startsWith("error") || kind === "syntax error") ? "error" : "info";
+    const message = kind === "syntax error"
+      ? ("syntax error: " + m.groups.msg).trim().replace(/\s*;\s*$/, "")
+      : m.groups.msg.trim();
+    out.push({
+      severity,
+      file: m.groups.file,
+      line: parseInt(m.groups.line, 10),
+      message: message.replace(/\x1b\[[0-9;]*m/g, ""),
+      stage,
+    });
+  }
+  // sdld/ASlink linker diagnostics have NO file:line — they reference a symbol +
+  // module. The most common is an undefined symbol (a call to a function that was
+  // never defined/linked). Without parsing these the agent sees "build failed"
+  // with no reason in issues[] (the error lived only in the raw log).
+  //   ?ASlink-Warning-Undefined Global '_foo' referenced by module '_main'
+  //   ?ASlink-Error-...
+  const linkRe = /^\?ASlink-(?<sev>Warning|Error)-(?<msg>.+)$/gm;
+  let lm;
+  while ((lm = linkRe.exec(text))) {
+    const msg = lm.groups.msg.trim();
+    // An "Undefined Global" is effectively an error even though ASlink labels it
+    // a warning — the ROM won't run. Promote it so the agent treats it as fatal.
+    const isUndef = /undefined\s+global/i.test(msg);
+    out.push({
+      severity: lm.groups.sev === "Error" || isUndef ? "error" : "warning",
+      message: "linker: " + msg,
+      stage: "sdld",
+    });
+  }
+  return out;
+}
+
 // dasm example:
 //   main.asm (1): error: Unknown Mnemonic 'is'.
 function parseDasm(text) {
@@ -248,13 +308,15 @@ function parseWla(text, stage = "wla") {
 // vasm example:
 //   error 22 in line 5 of "/work/main.s": ...
 //   warning 1003 in line 8 of "main.s": ...
+//   fatal error 13 in line 1 of "/work/main.s": could not open <x.bin> for input
+//     (← a MISSING incbin asset: the #1 thing an agent forgets to pass)
 function parseVasm(text) {
   const out = [];
-  const re = /^(?<sev>error|warning)\s+\d+\s+in\s+line\s+(?<line>\d+)\s+of\s+"(?<file>[^"]+)":\s*(?<msg>.+)$/gm;
+  const re = /^(?<sev>fatal error|error|warning)\s+\d+\s+in\s+line\s+(?<line>\d+)\s+of\s+"(?<file>[^"]+)":\s*(?<msg>.+)$/gm;
   let m;
   while ((m = re.exec(text))) {
     out.push({
-      severity: m.groups.sev,
+      severity: m.groups.sev === "warning" ? "warning" : "error",
       file: m.groups.file,
       line: parseInt(m.groups.line, 10),
       message: m.groups.msg.trim(),