romdev-mcp 0.1.1

package/src/toolchains/cc65/da65.js

@@ -0,0 +1,119 @@
+// da65 — cc65's 6502 / 65C02 / 65816 disassembler, in WASM.
+//
+// Run with --cpu 6502 (default). For SNES/65816 use --cpu 65816.
+
+import { fileURLToPath } from "node:url";
+import { existsSync } from "node:fs";
+import path from "node:path";
+
+import { runIsolated, textFile, binaryFile } from "../_worker/run.js";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// da65's WASM ships in romdev-toolchain-cc65 (alongside cc65 / ca65 / ld65).
+// Resolve from that package; fall back to a local copy under src/ if present
+// (transition / dev). The package is a hard dep of romdev.
+function resolveDa65Glue() {
+  try {
+    const u = import.meta.resolve("romdev-toolchain-cc65");
+    const p = path.join(path.dirname(fileURLToPath(u)), "wasm", "da65.js");
+    if (existsSync(p)) return p;
+  } catch { /* package not resolvable — fall through to local */ }
+  const local = path.join(__dirname, "wasm", "da65.js");
+  if (existsSync(local)) return local;
+  throw new Error("da65 WASM not found — install romdev-toolchain-cc65");
+}
+// Lazy + memoized: resolve only on the first da65 disassembly, not at boot.
+let _glue;
+const glue = () => (_glue ??= resolveDa65Glue());
+
+/**
+ * Disassemble a chunk of bytes.
+ *
+ * da65 quirk: by default it treats input bytes as DATA (emits `.byte`)
+ * for 65816/65c02/etc. and only decodes opcodes for ranges marked as
+ * Code in an info file. The 6502 default happens to decode because of
+ * compatibility behavior. For non-6502 CPUs we synthesize a minimal
+ * info file that declares the entire input range as Code. Callers can
+ * override by passing their own `info` string.
+ *
+ * @param {Object} args
+ * @param {Uint8Array} args.bytes   the bytes to disassemble
+ * @param {"6502" | "65c02" | "65816" | "65sc02" | "huc6280"} [args.cpu] CPU dialect (default 6502)
+ * @param {number} [args.startAddress] address of the first byte (default 0x8000 for NES)
+ * @param {string} [args.info] explicit da65 info-file contents. If omitted
+ *   AND cpu is non-6502, a minimal "treat the whole input as Code" info
+ *   file is synthesized so the agent gets actual mnemonics.
+ * @param {string[]} [args.options] extra da65 flags
+ * @returns {Promise<{ asm: string, log: string, exitCode: number }>}
+ */
+export async function runDa65(args) {
+  const cpu = args.cpu ?? "6502";
+  const startAddress = args.startAddress ?? 0x8000;
+  const extra = args.options ?? [];
+  // Synthesize a minimal info file for non-6502 CPUs so da65 emits
+  // mnemonics instead of `.byte` data dumps. RANGE Type=Code is the
+  // magic incantation.
+  const info = args.info ?? (cpu !== "6502" ? defaultCodeInfo(startAddress, args.bytes.length, cpu) : null);
+
+  /** @type {import("../_worker/run.js").InputFile[]} */
+  const inputFiles = [binaryFile("/work/in.bin", args.bytes)];
+  if (info) inputFiles.push(textFile("/work/in.info", info));
+  // da65 writes output to stdout (we capture via the worker's print).
+  const argv = [
+    "--cpu", cpu,
+    "--start-addr", "$" + startAddress.toString(16).toUpperCase(),
+    ...(info ? ["-i", "/work/in.info"] : []),
+    ...extra,
+    "/work/in.bin",
+  ];
+  const r = await runIsolated({
+    gluePath: glue(),
+    argv,
+    inputFiles,
+  });
+  return {
+    asm: r.log,
+    log: "",
+    exitCode: r.exitCode,
+    ...(r.crash ? { crash: r.crash, stage: "crash" } : {}),
+  };
+}
+
+/**
+ * Synthesize the minimum da65 info file that gets opcodes decoded.
+ * Forces the entire input range to be treated as Code rather than
+ * Data (the default for non-6502 CPUs).
+ *
+ * @param {number} startAddress
+ * @param {number} length bytes available
+ * @param {string} cpu
+ */
+function defaultCodeInfo(startAddress, length, cpu) {
+  // Don't put CPU in the info file — we already pass --cpu, and da65
+  // errors on duplicate. INPUTOFFS too; we set --start-addr.
+  // 65816 RANGEs need an ADDRMODE: M0X0 = both 16-bit, M1X1 = both 8-bit
+  // (the reset state). Default to M1X1 — matches what hardware boots
+  // into. Caller can override via custom info string for 16-bit modes.
+  const hex = (n) => "$" + n.toString(16).toUpperCase();
+  const endAddress = startAddress + length - 1;
+  // da65 ADDRMODE grammar (from src/da65/infofile.c):
+  //   char 0 must be 'm' or 'M' (lowercase = A is 16-bit, uppercase = 8-bit)
+  //   char 1 must be 'x' or 'X' (lowercase = X/Y are 16-bit, uppercase = 8-bit)
+  // Post-reset SNES state is 8-bit A AND 8-bit X/Y → "MX".
+  // RANGE START/END are 16-bit only — da65 doesn't accept 24-bit
+  // bank-prefixed addresses in info-file RANGEs (it's an old NES/65xx
+  // tool). Strip the bank for the info file; we'll still pass the full
+  // 24-bit start to --start-addr so the asm output uses real labels.
+  const lo16 = (n) => "$" + (n & 0xFFFF).toString(16).toUpperCase();
+  const start16 = lo16(startAddress);
+  const end16 = lo16(endAddress);
+  // Top-level sections (RANGE { ... }) need a trailing semicolon, per
+  // da65's parser (src/da65/infofile.c line 921 InfoConsumeSemi after
+  // each section).
+  if (cpu === "65816") {
+    return `RANGE {\n  START ${start16};\n  END ${end16};\n  TYPE Code;\n  ADDRMODE "MX";\n};\n`;
+  }
+  return `RANGE { START ${hex(startAddress)}; END ${hex(endAddress)}; TYPE Code; };\n`;
+}

package/src/toolchains/cc65/dbgparse.js

@@ -0,0 +1,274 @@
+// Parser for cc65 / ld65 `.dbg` debug info files.
+//
+// Documented format: https://cc65.github.io/doc/debug-info.html
+// Each line is `<type>\t<k1=v1>,<k2=v2>,...`. The first line is `version`,
+// the second is `info` (counts), then a stream of records by type.
+//
+// We don't parse every record type — only the ones an agent would want for
+// "what is this address" or "where is symbol X" workflows:
+//   sym    — assembly symbols
+//   csym   — C-level symbols (names from the original C source)
+//   scope  — scope ranges (functions etc.)
+//   seg    — segment definitions (e.g. CODE @ $8000, BSS @ $0000)
+//   line   — source line numbers
+//   span   — address ranges associated with lines/scopes
+//   file   — source file paths
+
+/**
+ * @typedef {Object} DbgInfo
+ * @property {Map<number, { name: string, file?: number, line?: number }>} files
+ * @property {Map<number, { name: string, addrsize: string, type?: string, val?: number, size?: number, scope?: number, ref?: number, exp?: number, sym?: number }>} syms
+ * @property {Map<number, { name: string, scope?: number, type?: string, sc?: string, sym?: number, offs?: number }>} csyms
+ * @property {Map<number, { name: string, mod?: number, type?: string, size?: number, parent?: number, sym?: number, span?: number }>} scopes
+ * @property {Map<number, { name: string, start: number, size: number, addrsize?: string, type?: string, oname?: string, ooffs?: number }>} segs
+ * @property {Map<number, { seg: number, start: number, size?: number, type?: string }>} spans
+ * @property {Map<number, { file: number, line: number, type?: string, span?: number | number[], count?: number }>} lines
+ */
+
+/**
+ * Parse a .dbg file's text contents.
+ * @param {string} text
+ * @returns {DbgInfo}
+ */
+export function parseDbg(text) {
+  /** @type {DbgInfo} */
+  const out = {
+    files: new Map(),
+    syms: new Map(),
+    csyms: new Map(),
+    scopes: new Map(),
+    segs: new Map(),
+    spans: new Map(),
+    lines: new Map(),
+  };
+
+  for (const line of text.split("\n")) {
+    if (!line || line.startsWith("version") || line.startsWith("info")) continue;
+    const tab = line.indexOf("\t");
+    if (tab < 0) continue;
+    const type = line.slice(0, tab);
+    const fields = parseFields(line.slice(tab + 1));
+    const id = fields.id !== undefined ? Number(fields.id) : -1;
+
+    switch (type) {
+      case "file":
+        out.files.set(id, { name: trimQ(fields.name) });
+        break;
+
+      case "sym":
+        out.syms.set(id, {
+          name: trimQ(fields.name),
+          addrsize: fields.addrsize,
+          type: fields.type,
+          val: fields.val !== undefined ? Number(fields.val) : undefined,
+          size: fields.size !== undefined ? Number(fields.size) : undefined,
+          scope: fields.scope !== undefined ? Number(fields.scope) : undefined,
+          ref: fields.ref !== undefined ? Number(fields.ref) : undefined,
+          exp: fields.exp !== undefined ? Number(fields.exp) : undefined,
+          sym: fields.sym !== undefined ? Number(fields.sym) : undefined,
+        });
+        break;
+
+      case "csym":
+        out.csyms.set(id, {
+          name: trimQ(fields.name),
+          scope: fields.scope !== undefined ? Number(fields.scope) : undefined,
+          type: fields.type,
+          sc: fields.sc,
+          sym: fields.sym !== undefined ? Number(fields.sym) : undefined,
+          offs: fields.offs !== undefined ? Number(fields.offs) : undefined,
+        });
+        break;
+
+      case "scope":
+        out.scopes.set(id, {
+          name: trimQ(fields.name),
+          mod: fields.mod !== undefined ? Number(fields.mod) : undefined,
+          type: fields.type,
+          size: fields.size !== undefined ? Number(fields.size) : undefined,
+          parent: fields.parent !== undefined ? Number(fields.parent) : undefined,
+          sym: fields.sym !== undefined ? Number(fields.sym) : undefined,
+          span: fields.span !== undefined ? Number(fields.span) : undefined,
+        });
+        break;
+
+      case "seg":
+        out.segs.set(id, {
+          name: trimQ(fields.name),
+          start: fields.start !== undefined ? Number(fields.start) : 0,
+          size: fields.size !== undefined ? Number(fields.size) : 0,
+          addrsize: fields.addrsize,
+          type: fields.type,
+          oname: fields.oname ? trimQ(fields.oname) : undefined,
+          ooffs: fields.ooffs !== undefined ? Number(fields.ooffs) : undefined,
+        });
+        break;
+
+      case "span":
+        out.spans.set(id, {
+          seg: fields.seg !== undefined ? Number(fields.seg) : -1,
+          start: fields.start !== undefined ? Number(fields.start) : 0,
+          size: fields.size !== undefined ? Number(fields.size) : undefined,
+          type: fields.type,
+        });
+        break;
+
+      case "line": {
+        let span;
+        if (fields.span !== undefined) {
+          // span can be "5" or "5+6+7"
+          const s = String(fields.span);
+          span = s.includes("+") ? s.split("+").map((n) => Number(n)) : Number(s);
+        }
+        out.lines.set(id, {
+          file: fields.file !== undefined ? Number(fields.file) : -1,
+          line: fields.line !== undefined ? Number(fields.line) : 0,
+          type: fields.type,
+          span,
+          count: fields.count !== undefined ? Number(fields.count) : undefined,
+        });
+        break;
+      }
+      default:
+        // Ignore mod/lib/type/sym-info — not needed for our queries yet.
+        break;
+    }
+  }
+
+  return out;
+}
+
+function parseFields(str) {
+  /** @type {Record<string, string>} */
+  const result = {};
+  let i = 0;
+  const n = str.length;
+  while (i < n) {
+    // Skip whitespace.
+    while (i < n && (str[i] === "," || str[i] === " ")) i++;
+    if (i >= n) break;
+    // Read key.
+    let k = "";
+    while (i < n && str[i] !== "=" && str[i] !== ",") {
+      k += str[i++];
+    }
+    if (str[i] !== "=") {
+      // Bare key (rare); store as empty value.
+      result[k] = "";
+      continue;
+    }
+    i++; // consume '='
+    // Read value: either a quoted string or until next comma.
+    let v = "";
+    if (str[i] === '"') {
+      v += str[i++];
+      while (i < n) {
+        v += str[i];
+        if (str[i] === '"' && str[i - 1] !== "\\") {
+          i++;
+          break;
+        }
+        i++;
+      }
+    } else {
+      while (i < n && str[i] !== ",") {
+        v += str[i++];
+      }
+    }
+    result[k] = v;
+  }
+  return result;
+}
+
+function trimQ(s) {
+  if (!s) return "";
+  if (s.length >= 2 && s[0] === '"' && s[s.length - 1] === '"') {
+    return s.slice(1, -1);
+  }
+  return s;
+}
+
+/**
+ * High-level helpers built on top of a parsed DbgInfo.
+ */
+export class DbgIndex {
+  /** @param {DbgInfo} info */
+  constructor(info) {
+    this.info = info;
+
+    // Build a name → list-of-symbols lookup.
+    /** @type {Map<string, { kind: "sym" | "csym", id: number, addr?: number }[]>} */
+    this.byName = new Map();
+
+    for (const [id, sym] of info.syms) {
+      const entry = { kind: /** @type {const} */ ("sym"), id, addr: sym.val };
+      const list = this.byName.get(sym.name) ?? [];
+      list.push(entry);
+      this.byName.set(sym.name, list);
+    }
+    for (const [id, csym] of info.csyms) {
+      // C symbols don't carry the address directly — they point at a sym.
+      let addr;
+      if (csym.sym !== undefined) {
+        const s = info.syms.get(csym.sym);
+        if (s) addr = s.val;
+      }
+      const entry = { kind: /** @type {const} */ ("csym"), id, addr };
+      const list = this.byName.get(csym.name) ?? [];
+      list.push(entry);
+      this.byName.set(csym.name, list);
+    }
+  }
+
+  /**
+   * Resolve a symbol name (C or asm) to an address.
+   * Returns null if not found, or the first matching address if multiple.
+   * @param {string} name
+   */
+  addressOf(name) {
+    const list = this.byName.get(name);
+    if (!list || list.length === 0) return null;
+    for (const e of list) {
+      if (typeof e.addr === "number") return e.addr;
+    }
+    return null;
+  }
+
+  /**
+   * Find the symbol whose value (if any) most closely contains the address.
+   * Returns the symbol nearest at-or-below the address.
+   * @param {number} addr
+   */
+  symbolAt(addr) {
+    /** @type {{ name: string, addr: number, kind: string } | null} */
+    let best = null;
+    for (const [_id, sym] of this.info.syms) {
+      if (typeof sym.val !== "number") continue;
+      if (sym.val > addr) continue;
+      if (!best || sym.val > best.addr) {
+        best = { name: sym.name, addr: sym.val, kind: "sym" };
+      }
+    }
+    return best;
+  }
+
+  /** Convenience: list every named symbol with an address. */
+  listSymbols() {
+    /** @type {{ name: string, addr: number, kind: string }[]} */
+    const out = [];
+    for (const [_id, sym] of this.info.syms) {
+      if (typeof sym.val === "number" && sym.name) {
+        out.push({ name: sym.name, addr: sym.val, kind: "sym" });
+      }
+    }
+    for (const [_id, csym] of this.info.csyms) {
+      if (csym.sym !== undefined) {
+        const s = this.info.syms.get(csym.sym);
+        if (s && typeof s.val === "number") {
+          out.push({ name: csym.name, addr: s.val, kind: "csym" });
+        }
+      }
+    }
+    return out.sort((a, b) => a.addr - b.addr);
+  }
+}

package/src/toolchains/cc65/preset-resolver.js

@@ -0,0 +1,59 @@
+// Resolve a `linkerConfig` argument. If it looks like a known preset name
+// (no newlines, matches a shipped file under presets/<platform>/), load
+// the .cfg AND any companion support sources (e.g. a custom crt0).
+// Otherwise treat the argument as the literal ld65 config contents.
+//
+// Presets layout: src/toolchains/cc65/presets/<platform>/
+//   <preset>.cfg         — the ld65 config
+//   <preset>.crt0.s      — optional custom crt0 spliced into sources
+//   <preset>.*.s         — additional support sources
+
+import path from "node:path";
+import { readFile, readdir } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const PRESETS_DIR = path.resolve(__dirname, "presets");
+
+/**
+ * @param {string} platform
+ * @param {string | undefined} arg
+ * @returns {Promise<{ cfg: string | undefined, supportSources: Record<string, string> }>}
+ */
+export async function resolveLinkerConfig(platform, arg) {
+  if (!arg) return { cfg: undefined, supportSources: {} };
+  if (arg.includes("\n") || arg.length > 200) {
+    return { cfg: arg, supportSources: {} };
+  }
+  const preset = arg.trim();
+  if (!/^[a-z][a-z0-9-]*$/i.test(preset)) {
+    return { cfg: arg, supportSources: {} };
+  }
+  const presetDir = path.join(PRESETS_DIR, platform);
+  let cfg;
+  try {
+    cfg = await readFile(path.join(presetDir, `${preset}.cfg`), "utf-8");
+  } catch {
+    throw new Error(
+      `linkerConfig: unknown preset '${preset}' for platform '${platform}'. ` +
+      `Pass either a known preset name (e.g. 'chr-ram' for NES) or the full .cfg contents.`
+    );
+  }
+  const supportSources = {};
+  try {
+    const entries = await readdir(presetDir);
+    const prefix = `${preset}.`;
+    for (const f of entries) {
+      if (!f.startsWith(prefix) || f === `${preset}.cfg`) continue;
+      const ext = path.extname(f).toLowerCase();
+      if (ext === ".s" || ext === ".asm") {
+        const contents = await readFile(path.join(presetDir, f), "utf-8");
+        const suffix = f.slice(prefix.length);
+        supportSources[`_preset_${suffix}`] = contents;
+      }
+    }
+  } catch {
+    // No support files.
+  }
+  return { cfg, supportSources };
+}

package/src/toolchains/cc65/presets/nes/chr-ram-runtime.cfg

@@ -0,0 +1,79 @@
+# NES CHR-RAM linker config preset for romdev.
+#
+# DIFFERENCE FROM DEFAULT nes.cfg:
+#   - HEADER's iNES byte 5 (CHR-ROM bank count) is set to 0 via the
+#     project's own HEADER segment (the project must supply HEADER).
+#     We don't ship HEADER bytes here because cc65's stock crt0.s emits
+#     them — and pulling in stock crt0 also pulls in NESfont (4KB CHARS).
+#     So this preset is meant to be used WITH a custom header source
+#     that defines .segment "HEADER" + provides chr=0 bytes.
+#   - ROM2 (8K CHR ROM bank) is REMOVED. Pattern tables live in CHR-RAM
+#     ($0000-$1FFF on the PPU bus) and are written by your game at
+#     runtime. There is no CHARS segment.
+#
+# To use this preset:
+#   1. linkerConfig: "chr-ram" on buildSource
+#   2. Supply your own crt0/header source that writes the 16-byte iNES
+#      header with byte 5 = 0. Easiest: paste the snippet
+#      getStarterSnippet({platform:"nes", name:"chr_ram_header", language:"asm"}).
+#   3. Write CHR data from C at runtime: PPUADDR = 0x00; PPUDATA = byte; etc.
+
+SYMBOLS {
+    __STACKSIZE__: type = weak, value = $0300;
+}
+MEMORY {
+    ZP:     file = "", start = $0002, size = $001A, type = rw, define = yes;
+
+    # INES Cartridge Header — provided by your project (HEADER segment).
+    HEADER: file = %O, start = $0000, size = $0010, fill = yes;
+
+    # PRG-ROM: 2 × 16K = 32K (NROM-256 style; covers most projects).
+    ROM0:   file = %O, start = $8000, size = $7FFA, fill = yes, define = yes;
+
+    # Hardware vectors at end of PRG.
+    ROMV:   file = %O, start = $FFFA, size = $0006, fill = yes;
+
+    # NO ROM2 / CHARS — this is the whole point of the CHR-RAM preset.
+
+    SRAM:   file = "", start = $0500, size = __STACKSIZE__, define = yes;
+
+    # BSS / DATA live in real RAM ($0300-$04FF, 512 bytes). NROM (mapper 0)
+    # with no battery has $6000-$7FFF UNMAPPED — reads return open bus.
+    # Putting BSS there means `int counter = 0;` reads garbage (intermittent
+    # garbage that "works" only via open-bus parasitic capacitance).
+    # 512 bytes is plenty for tiny NROM carts; for more, opt into a mapper
+    # that maps PRG-RAM at $6000 and use a different preset.
+    RAM:    file = "", start = $0300, size = $0200, define = yes;
+
+    # Shadow OAM at $0200 (page 2). Game code populates this, NMI handler
+    # DMAs it to PPU sprite RAM via $4014. 256 bytes = 64 sprites × 4.
+    OAM:    file = "", start = $0200, size = $0100;
+}
+SEGMENTS {
+    ZEROPAGE: load = ZP,              type = zp;
+    HEADER:   load = HEADER,          type = ro;
+    STARTUP:  load = ROM0,            type = ro,  define   = yes;
+    LOWCODE:  load = ROM0,            type = ro,  optional = yes;
+    ONCE:     load = ROM0,            type = ro,  optional = yes;
+    CODE:     load = ROM0,            type = ro,  define   = yes;
+    RODATA:   load = ROM0,            type = ro,  define   = yes;
+    DATA:     load = ROM0, run = RAM, type = rw,  define   = yes;
+    VECTORS:  load = ROMV,            type = rw;
+    BSS:      load = RAM,             type = bss, define   = yes;
+    OAM:      load = OAM,             type = bss, optional = yes;
+}
+FEATURES {
+    CONDES: type    = constructor,
+            label   = __CONSTRUCTOR_TABLE__,
+            count   = __CONSTRUCTOR_COUNT__,
+            segment = ONCE;
+    CONDES: type    = destructor,
+            label   = __DESTRUCTOR_TABLE__,
+            count   = __DESTRUCTOR_COUNT__,
+            segment = RODATA;
+    CONDES: type    = interruptor,
+            label   = __INTERRUPTOR_TABLE__,
+            count   = __INTERRUPTOR_COUNT__,
+            segment = RODATA,
+            import  = __CALLIRQ__;
+}