romdevtools 0.13.0

package/src/mcp/tools/snippets.js

@@ -0,0 +1,209 @@
+// getStarterSnippet / listStarterSnippets — vetted boilerplate the agent
+// can include in their project instead of writing from scratch. Encodes
+// the foot-guns we've already hit so the next agent doesn't have to.
+//
+// Snippets live in: src/platforms/<platform>/lib/[<language>/]<name>.<ext>
+//   - Flat layout (current): lib/foo.s, lib/bar.s — language-implicit (asm)
+//   - Language layout: lib/asm/foo.s, lib/c/baz.h — supports multiple
+//     languages per platform without name collisions.
+// Both layouts are supported simultaneously: language-specific dirs
+// override flat names when a language is requested.
+
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+import { readdir, readFile, stat, mkdir, writeFile } from "node:fs/promises";
+
+import { jsonContent, safeTool, textContent, writeOutput } from "../util.js";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const LIB_ROOT = path.resolve(__dirname, "..", "..", "platforms");
+
+// Map file extension → language id. Anything not listed is treated as "asm"
+// for backward compat (the existing flat snippets are all .s/.asm).
+const EXT_TO_LANG = {
+  ".c": "c",
+  ".h": "c",
+  ".cpp": "cpp",
+  ".s": "asm",
+  ".asm": "asm",
+  ".inc": "asm",
+};
+
+/**
+ * Walk a platform's lib/ and return every snippet found, tagged with
+ * language. Snippets in lib/<lang>/ are tagged with that language; flat
+ * snippets are tagged by extension.
+ *
+ * @returns {Promise<Array<{name: string, file: string, language: string}>>}
+ *   `name` is the bare logical name (no extension), `file` is the path
+ *   relative to lib/, `language` is the inferred language id.
+ */
+async function listSnippetsForPlatform(platform) {
+  const dir = path.join(LIB_ROOT, platform, "lib");
+  /** @type {Array<{name: string, file: string, language: string}>} */
+  const out = [];
+  let entries;
+  try { entries = await readdir(dir); } catch { return out; }
+  for (const entry of entries.sort()) {
+    if (entry.startsWith(".") || entry === "README.md") continue;
+    const full = path.join(dir, entry);
+    let s;
+    try { s = await stat(full); } catch { continue; }
+    if (s.isDirectory()) {
+      // Language-specific subdir (e.g. lib/c/, lib/asm/).
+      // ONLY list regular files inside — directory-shaped entries
+      // (vendored SDK trees like lib/pvsneslib/include, lib/sgdk/
+      // include) shouldn't appear as snippets because:
+      //   1. They'd crash copyStarterSnippets with EISDIR.
+      //   2. Multi-hundred-file SDK trees aren't "snippets" anyway.
+      // Such trees ship via the createProject template's runtimeDirs
+      // (vendor/<sdk>/...) which copies them recursively.
+      const sub = await readdir(full).catch(() => []);
+      for (const f of sub.sort()) {
+        if (f.startsWith(".") || f === "README.md") continue;
+        const subFull = path.join(full, f);
+        let subStat;
+        try { subStat = await stat(subFull); } catch { continue; }
+        if (subStat.isDirectory()) continue;  // skip nested SDK trees
+        const ext = path.extname(f).toLowerCase();
+        out.push({
+          name: f.slice(0, f.length - ext.length),
+          file: `${entry}/${f}`,
+          language: entry,  // dir name IS the language id
+        });
+      }
+    } else {
+      // Flat file at lib/ root — infer language from extension.
+      const ext = path.extname(entry).toLowerCase();
+      const lang = EXT_TO_LANG[ext] ?? "asm";
+      out.push({
+        name: entry.slice(0, entry.length - ext.length),
+        file: entry,
+        language: lang,
+      });
+    }
+  }
+  return out;
+}
+
+export function registerSnippetTools(server, z) {
+  // ── Shared implementations for the three snippet modes ──────────
+  async function snippetsList(platform, language) {
+    const all = await listSnippetsForPlatform(platform);
+    const filtered = language ? all.filter((s) => s.language === language) : all;
+    const languages = [...new Set(all.map((s) => s.language))].sort();
+    return jsonContent({
+      platform, languages, snippets: filtered,
+      note: filtered.length === 0
+        ? `No snippets matched for '${platform}'${language ? ` (language=${language})` : ""}.`
+        : `Fetch one with starterSnippets({ platform, mode:'get', name${language ? ", language" : ""} }), or all with mode:'getAll'.`,
+    });
+  }
+  async function snippetsGet(platform, name, language) {
+    if (!name) throw new Error("starterSnippets mode:'get' requires `name`.");
+    if (name.includes("..") || (name.includes("/") && !/^[a-z]+\/[\w.-]+$/i.test(name))) {
+      throw new Error("snippet name must not contain '..' or arbitrary path separators");
+    }
+    const all = await listSnippetsForPlatform(platform);
+    const bare = name.replace(/\.\w+$/, "");
+    let hit = all.find((s) => s.file === name);
+    if (!hit && language) hit = all.find((s) => s.name === bare && s.language === language);
+    if (!hit) hit = all.find((s) => s.name === bare);
+    if (!hit) {
+      const available = all.map((s) => `${s.name} (${s.language})`).sort().join(", ");
+      throw new Error(`no snippet '${name}' for platform '${platform}'. Available: ${available || "(none)"}`);
+    }
+    const contents = await readFile(path.join(LIB_ROOT, platform, "lib", hit.file), "utf-8");
+    return jsonContent({ platform, name: hit.name, file: hit.file, language: hit.language, contents });
+  }
+  async function snippetsGetAll(platform, language, outputPath, inline) {
+    const all = await listSnippetsForPlatform(platform);
+    const filtered = language ? all.filter((s) => s.language === language) : all;
+    if (filtered.length === 0) {
+      return textContent(`No snippets available for '${platform}'${language ? ` (language=${language})` : ""}.`);
+    }
+    if (!inline && !outputPath) {
+      throw new Error("starterSnippets mode:'getAll': pass outputPath (write the joined snippets to disk, returns {path}) or inline:true (return `combined` in the response). Or use copyStarterSnippets to write each snippet as its own file.");
+    }
+    const parts = [];
+    for (const s of filtered) {
+      const contents = await readFile(path.join(LIB_ROOT, platform, "lib", s.file), "utf-8");
+      const sep = s.language === "c" ? "// =====" : "; =====";
+      parts.push(`${sep} ${s.file} =====\n${contents}`);
+    }
+    const combined = parts.join("\n\n");
+    const meta = {
+      platform, language: language ?? null,
+      snippets: filtered.map((s) => ({ name: s.name, file: s.file, language: s.language })),
+    };
+    if (inline) {
+      return jsonContent({ ...meta, combined });
+    }
+    const { path: outPath, bytes } = writeOutput(combined, { outputPath, what: "joined snippets" });
+    return jsonContent({ ...meta, path: outPath, bytes });
+  }
+
+  // exported below as starterSnippetsCore.
+  starterSnippetsCore = async ({ platform, mode = "list", name, language, outputPath, inline }) => {
+      if (mode === "get") return snippetsGet(platform, name, language);
+      if (mode === "getAll") return snippetsGetAll(platform, language, outputPath, inline);
+      return snippetsList(platform, language);
+  };
+
+  copyStarterSnippetsCore = async ({ platform, destinationDir, language, include, overwrite = true }) => {
+      const all = await listSnippetsForPlatform(platform);
+      let filtered = language ? all.filter((s) => s.language === language) : all;
+      if (include && include.length > 0) {
+        const wanted = new Set(include);
+        filtered = filtered.filter((s) => wanted.has(s.name));
+      }
+      if (filtered.length === 0) {
+        const langPart = language ? ` (language=${language})` : "";
+        const includePart = include ? ` (include=${JSON.stringify(include)})` : "";
+        throw new Error(`copyStarterSnippets: no snippets matched for platform '${platform}'${langPart}${includePart}.`);
+      }
+      await mkdir(destinationDir, { recursive: true });
+      const written = [];
+      const skipped = [];
+      for (const s of filtered) {
+        const srcPath = path.join(LIB_ROOT, platform, "lib", s.file);
+        const bareName = path.basename(s.file);                       // flatten lib/<lang>/<file>
+        const dstPath = path.join(destinationDir, bareName);
+        if (!overwrite) {
+          try {
+            await stat(dstPath);
+            skipped.push({ name: s.name, file: s.file, dstPath, reason: "exists" });
+            continue;
+          } catch { /* doesn't exist — proceed */ }
+        }
+        const bytes = await readFile(srcPath);
+        await writeFile(dstPath, bytes);
+        written.push({
+          name: s.name,
+          srcFile: s.file,           // relative to platforms/<p>/lib/
+          dstPath,                   // absolute
+          language: s.language,
+          bytes: bytes.length,
+        });
+      }
+      return jsonContent({
+        platform,
+        destinationDir,
+        language: language ?? null,
+        include: include ?? null,
+        written,
+        skipped,
+        summary: `Copied ${written.length} snippet${written.length === 1 ? "" : "s"}` +
+                 (skipped.length ? ` (skipped ${skipped.length} existing)` : "") +
+                 ` into ${destinationDir}.`,
+      });
+  };
+}
+
+// starterSnippets/copyStarterSnippets folded into the `scaffold` tool. The cores
+// are assigned inside registerSnippetTools (they close over the local helpers);
+// scaffold imports these and calls them. registerSnippetTools registers NO tools
+// now — it just wires the cores.
+export let starterSnippetsCore = async () => { throw new Error("snippet cores not initialized — registerSnippetTools must run first"); };
+export let copyStarterSnippetsCore = async () => { throw new Error("snippet cores not initialized — registerSnippetTools must run first"); };

package/src/mcp/tools/splice-chr.js

@@ -0,0 +1,190 @@
+// spliceCHR — png → platform-native tile bytes → splice into CHR file at a
+// tile index. Composition of convertImageToTiles (existing) + patchFile (#73).
+//
+// Most common ROM-hack workflow for sprite/tile edits: open the CHR data in
+// some pixel editor, save as PNG, drop into the ROM at the right tile slot.
+// Currently this is 3+ MCP calls (read CHR bank, convertImageToTiles, patch).
+// One call does the whole thing with a sidecar `expect` check on the tiles
+// being overwritten.
+
+import { readFile } from "node:fs/promises";
+
+/**
+ * Tile size in bytes per platform.
+ *   NES, GB, GBC: 16 bytes/tile (2bpp, 8x8)
+ */
+function tileSizeForPlatform(platform) {
+  switch (platform) {
+    case "nes":
+    case "gb":
+    case "gbc": return 16;       // 2bpp × 8 rows
+    case "c64": return 8;        // 1bpp charset, 8 rows × 1 byte
+    case "sms":
+    case "gg":
+    case "snes":
+    case "genesis":
+    case "megadrive":
+    case "md":
+    case "gba": return 32;       // 4bpp × 8 rows
+    case "atari2600":
+    case "a2600":
+    case "atari7800":
+    case "a7800":
+      throw new Error(
+        `spliceCHR: ${platform} doesn't have a fixed CHR tile size. Sprites/playfield are ` +
+        `1-bit bitmap bytes on 2600; 7800 graphics depend on per-display-list bit depth.`
+      );
+    default:
+      throw new Error(`spliceCHR: tile size unknown for platform '${platform}'`);
+  }
+}
+
+/**
+ * Resolve the file-offset where the CHR region starts for a path. For NES
+ * iNES files this is 16 + prgBanks*16384. Otherwise the caller must pass
+ * `chrFileOffset` explicitly.
+ */
+async function resolveChrBase(path, platform, explicitOffset) {
+  if (explicitOffset != null) return { fileOffset: explicitOffset, note: "explicit chrFileOffset" };
+  if (platform === "nes") {
+    const data = new Uint8Array(await readFile(path));
+    if (data[0] !== 0x4e || data[1] !== 0x45 || data[2] !== 0x53 || data[3] !== 0x1a) {
+      throw new Error(`spliceCHR: '${path}' is not a valid iNES ROM. Pass chrFileOffset explicitly.`);
+    }
+    const prgSize = data[4] * 16384;
+    const off = 16 + prgSize;
+    const chrSize = data[5] * 8192;
+    if (chrSize === 0) {
+      throw new Error(`spliceCHR: iNES ROM '${path}' has CHR-RAM (no CHR-ROM in the file). Use build({output:'rom'}) to generate CHR via your asm source.`);
+    }
+    return { fileOffset: off, chrSize, note: `iNES CHR-ROM bank @ file offset ${off}, ${chrSize} bytes` };
+  }
+  if (platform === "gb" || platform === "gbc") {
+    throw new Error(`spliceCHR: Game Boy tiles are in PRG ROM at arbitrary offsets — pass chrFileOffset explicitly (no auto-detect for GB).`);
+  }
+  if (platform === "sms" || platform === "gg") {
+    throw new Error(
+      `spliceCHR: SMS/GG tiles are uploaded to VRAM at runtime from arbitrary ROM ` +
+      `offsets — no auto-detect. Pass chrFileOffset explicitly. Typical approach: ` +
+      `disassembleRom near the VDP $BE writes to find where the game loads tiles ` +
+      `from in ROM, then point chrFileOffset there.`
+    );
+  }
+  if (platform === "snes" || platform === "genesis" || platform === "megadrive" || platform === "md") {
+    throw new Error(
+      `spliceCHR[${platform}]: tile data lives at arbitrary ROM offsets (game-specific). ` +
+      `Pass chrFileOffset explicitly. For SNES use disassembleRom + grep for DMA writes ` +
+      `to VRAM; for Genesis grep for VDP_DATA ($C00000) writes.`
+    );
+  }
+  if (platform === "c64") {
+    throw new Error(
+      `spliceCHR[c64]: C64 charset data lives at an arbitrary offset in your PRG ` +
+      `(wherever you placed the 8-byte-per-char bitmap table). Pass chrFileOffset ` +
+      `explicitly — it's the byte offset of char 0 in the file. Each char is 8 bytes ` +
+      `(1bpp, bit set = foreground).`
+    );
+  }
+  if (platform === "atari2600" || platform === "a2600") {
+    throw new Error(
+      `spliceCHR[2600]: the 2600 has no tile ROM region — graphics are 1-bit ` +
+      `sprite bytes written by code to GRP0/GRP1/PF0/PF1/PF2/ENABL each scanline. ` +
+      `There's nothing to splice generically. Use patchFile on specific ROM ` +
+      `bytes (find them via disassembleRom + lda/sta GRP/PF refs).`
+    );
+  }
+  if (platform === "atari7800" || platform === "a7800") {
+    throw new Error(
+      `spliceCHR[7800]: the 7800 reads tile/sprite graphics from MARIA display ` +
+      `lists at runtime — they live at arbitrary ROM offsets per game. Pass ` +
+      `chrFileOffset explicitly after finding the chargen base via ` +
+      `disassembleRom (look for the CHARBASE register write at $87).`
+    );
+  }
+  throw new Error(`spliceCHR: platform '${platform}' not yet supported. Pass chrFileOffset explicitly to splice raw tile bytes.`);
+}
+
+export async function spliceChrCore({
+  path, outputPath, platform, pngBase64, tileIndex,
+  chrFileOffset, bank, paletteHint, expect, allowExpand,
+}) {
+  const { imageToTiles } = await import("../../platforms/common/image-to-tiles.js");
+  const png = Buffer.from(pngBase64, "base64");
+  const hint = paletteHint ? paletteHint.map(parseRgb) : undefined;
+  const conv = imageToTiles(platform, png, { maxTiles: 8192, paletteHint: hint });
+  const tileBytes = conv.tiles;
+
+  const tileSize = tileSizeForPlatform(platform);
+  // Resolve CHR base: explicit chrFileOffset wins; else `bank` for NES; else auto.
+  let chrBase;
+  if (chrFileOffset != null) {
+    chrBase = { fileOffset: chrFileOffset, note: "explicit chrFileOffset" };
+  } else if (bank != null) {
+    const { readFile } = await import("node:fs/promises");
+    const data = new Uint8Array(await readFile(path));
+    chrBase = { fileOffset: bankToChrOffset(platform, data, bank), note: `${platform} bank ${bank}` };
+  } else {
+    chrBase = await resolveChrBase(path, platform, chrFileOffset);
+  }
+  const writeOffset = chrBase.fileOffset + tileIndex * tileSize;
+
+  const { patchFile } = await import("../../rom-id/patch.js");
+  const r = await patchFile({
+    path,
+    outputPath,
+    offset: writeOffset,
+    base64: Buffer.from(tileBytes).toString("base64"),
+    expect,
+    allowExpand: allowExpand ?? false,
+  });
+
+  return {
+    ...r,
+    tileIndex,
+    tilesWritten: conv.totalTiles,
+    chrBase: chrBase.fileOffset,
+    chrBaseNote: chrBase.note,
+    pngDimensionsTiles: { across: conv.tilesAcross, down: conv.tilesDown },
+  };
+}
+
+/**
+ * Map "bank N" to a CHR file offset for the given platform. Same idea as the
+ * NES helper in rom-id.js — kept separate here so spliceCHR can use it
+ * without circular imports.
+ */
+function bankToChrOffset(platform, bytes, bank) {
+  if (platform !== "nes") {
+    throw new Error(`bank arg currently only supported for platform='nes'. Pass chrFileOffset explicitly for '${platform}'.`);
+  }
+  if (bytes[0] !== 0x4E || bytes[1] !== 0x45 || bytes[2] !== 0x53 || bytes[3] !== 0x1A) {
+    throw new Error("bank arg requires an iNES file; pass chrFileOffset instead.");
+  }
+  const prgSize = bytes[4] * 16384;
+  const chrSize = bytes[5] * 8192;
+  if (chrSize === 0) throw new Error("CHR-RAM cart — no CHR in the file. Use writeMemory on the running emulator instead.");
+  const chrBase = 16 + prgSize;
+  const offset = chrBase + bank * 4096;
+  if (offset >= chrBase + chrSize) {
+    const maxBank = Math.floor(chrSize / 4096) - 1;
+    throw new Error(`bank ${bank} out of range; cart has banks 0..${maxBank}.`);
+  }
+  return offset;
+}
+
+/** Parse an RGB color hint: "#RRGGBB" or [r, g, b]. Returns [r, g, b]. */
+function parseRgb(input) {
+  if (Array.isArray(input) && input.length === 3) return input;
+  if (typeof input === "string") {
+    const m = input.match(/^#?([0-9a-fA-F]{6})$/);
+    if (m) {
+      const v = parseInt(m[1], 16);
+      return [(v >> 16) & 0xFF, (v >> 8) & 0xFF, v & 0xFF];
+    }
+  }
+  throw new Error(`paletteHint entry must be "#RRGGBB" or [r,g,b]; got ${JSON.stringify(input)}`);
+}
+
+// spliceCHR folded into the `romPatch` tool (romPatch({op:'spliceCHR'}),
+// rom-id.js, which imports spliceChrCore). Nothing registered here.
+export function registerSpliceChrTools() {}