romdev-mcp 0.1.1

package/src/toolchains/assemble-snippet.js

@@ -0,0 +1,256 @@
+// assembleSnippet — take a small chunk of asm and return raw bytes.
+//
+// NOT a full build. NO header, NO linker config, NO segments. Just:
+//   { cpu: "6502", origin: 0xC500, code: "lda #$05\nsta $0123\nrts" }
+//   → { bytes: Uint8Array, asm: "...effective source...", log: string }
+//
+// This is the highest-leverage tool for ROM-hacking workflows: paired
+// with patchFile, the agent does "assemble → splice" in 2 MCP calls
+// instead of writing a wrapper.s + linkerConfig for every byte patch.
+//
+// Each CPU routes to the right assembler:
+//   6502, 65c02, huc6280  → ca65 + ld65 with synthesized minimal config
+//   65816                 → asar (uses inline `org` directive, emits raw)
+//   68k                   → vasm68k -Fbin
+//   z80                   → sdasz80 + sdld (via the existing sdcc helpers)
+//   sm83 (gb/gbc)         → rgbasm + rgblink + rgbfix -p 0 (flat binary)
+//   spc700                → NOT YET BUNDLED — throws structured error
+//
+// All return shape: { ok: true, cpu, origin, bytes: Uint8Array, length, hex, asm, log }
+
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { runCa65, runLd65 } from "./cc65/cc65.js";
+import { runAsar } from "./asar/asar.js";
+import { runVasm68k } from "./vasm68k/vasm68k.js";
+import { runSdasz80, runSdld, ihxToBin } from "./sdcc/sdcc.js";
+import { runRgbasm, runRgblink, runRgbfix } from "./rgbds/rgbds.js";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+/**
+ * CPU dialect → assembler dispatch. Keys are also the public API.
+ */
+const CPU_ASSEMBLERS = {
+  "6502":    assembleCa65,
+  "65c02":   assembleCa65,
+  "huc6280": assembleCa65,
+  "65816":   assembleAsar,
+  "68k":     assembleVasm68k,
+  "m68k":    assembleVasm68k,   // alias
+  "z80":     assembleSdcc,
+  "sm83":    assembleRgbds,     // GB/GBC LR35902
+  "gb":      assembleRgbds,     // alias for sm83
+  "gbc":     assembleRgbds,     // alias for sm83
+  // spc700 — TODO: would need a dedicated SPC700 assembler bundle. We have
+  // NO upstream WASM assembler for SPC700; raw 6502 doesn't work because
+  // the ISA differs. Caller gets a clear "not supported yet" message.
+  "spc700":  () => { throw new Error(
+    "assembleSnippet: spc700 not yet supported. " +
+    "No SPC700 assembler is currently bundled (would need to extract one " +
+    "from bsnes or write a tiny encoder — captured in plan as future work).");
+  },
+};
+
+/**
+ * Public entry. Pure function shape; resolves to a result or throws.
+ *
+ * @param {Object} args
+ * @param {string} args.cpu        one of the CPU keys above
+ * @param {number} [args.origin]   where the code is intended to live in CPU
+ *   address space. Required for any code that uses absolute addressing or
+ *   relative branches that need a real target. Default 0x0000.
+ * @param {string} args.code       the asm source (no .org / no headers needed —
+ *   we synthesize them based on cpu + origin).
+ * @returns {Promise<{ ok: boolean, cpu: string, origin: number, bytes: Uint8Array, length: number, hex: string, log: string }>}
+ */
+export async function assembleSnippet(args) {
+  const { cpu, code } = args;
+  const origin = args.origin ?? 0x0000;
+  if (typeof code !== "string" || code.length === 0) {
+    throw new Error("assembleSnippet: 'code' must be a non-empty string of asm source");
+  }
+  const dispatch = CPU_ASSEMBLERS[cpu];
+  if (!dispatch) {
+    throw new Error(
+      `assembleSnippet: unknown cpu '${cpu}'. ` +
+      `Supported: ${Object.keys(CPU_ASSEMBLERS).filter((k) => k !== "spc700").join(", ")}.`,
+    );
+  }
+  const { bytes, log } = await dispatch({ origin, code });
+  return {
+    ok: true,
+    cpu,
+    origin,
+    bytes,
+    length: bytes.length,
+    hex: Array.from(bytes, (b) => b.toString(16).padStart(2, "0").toUpperCase()).join(" "),
+    log: log ?? "",
+  };
+}
+
+// ─── ca65 (6502 + variants) ────────────────────────────────────────────
+// Strategy: write source with `.org` directive, assemble to .o, link with
+// a trivial config that places .CODE at the origin and outputs raw bytes.
+async function assembleCa65({ origin, code }, cpu = "6502") {
+  // Always start with .feature labels_without_colons so simple snippets
+  // work with or without colons. ca65 default already accepts colons so
+  // this is purely additive.
+  const source = `.setcpu "${cpu.toUpperCase()}"\n.segment "CODE"\n${code}\n`;
+
+  const asm = await runCa65({ source });
+  if (!asm.object) {
+    throw new Error(`assembleSnippet[ca65]: assembly failed.\nlog:\n${asm.log ?? ""}`);
+  }
+
+  // Minimal linker config: one MEMORY block at `origin`, one SEGMENT
+  // mapping CODE there. Output is raw bytes — no header bytes prepended.
+  const cfg = `MEMORY { OUT: file = %O, start = $${origin.toString(16).toUpperCase()}, size = $10000 - $${origin.toString(16).toUpperCase()}, fill = no; }
+SEGMENTS { CODE: load = OUT, type = ro; }
+`;
+  const linked = await runLd65({
+    objects: { "snippet.o": asm.object },
+    target: "none",
+    linkerConfig: cfg,
+  });
+  if (!linked.binary) {
+    throw new Error(`assembleSnippet[ld65]: link failed.\nlog:\n${linked.log ?? ""}`);
+  }
+  return { bytes: linked.binary, log: (asm.log ?? "") + (linked.log ?? "") };
+}
+
+// ─── asar (65816) ─────────────────────────────────────────────────────
+// Asar normally patches a ROM image. For a snippet we hand it a sentinel-
+// filled 64KB scratch + an `org $origin` directive, then scan the file for
+// the contiguous non-sentinel run and slice it out. Asar in default
+// (LoROM-like) mode maps `$00:8000` → file offset $0000; the exact file
+// position doesn't matter because we locate the bytes by scanning.
+async function assembleAsar({ origin, code }) {
+  if (origin > 0xFFFFFF) {
+    throw new Error("assembleSnippet[asar]: origin must be a 24-bit SNES address (e.g. 0x008000)");
+  }
+  const hex24 = "$" + origin.toString(16).toUpperCase().padStart(6, "0");
+  const SENTINEL = 0xAA;
+  const baseRom = new Uint8Array(64 * 1024).fill(SENTINEL);
+  const source = `org ${hex24}\n${code}\n`;
+  const r = await runAsar({ source, baseRom, symbols: false });
+  if (!r.binary) {
+    throw new Error(`assembleSnippet[asar]: assembly failed.\nlog:\n${r.log ?? ""}`);
+  }
+  const bin = r.binary;
+  // Find first non-sentinel byte (asar may have written anywhere depending
+  // on how it interpreted the absolute address). Then walk until a long
+  // sentinel run signals end-of-code.
+  let start = -1;
+  for (let i = 0; i < bin.length; i++) {
+    if (bin[i] !== SENTINEL) { start = i; break; }
+  }
+  if (start < 0) {
+    throw new Error(`assembleSnippet[asar]: no bytes written (origin 0x${origin.toString(16)})\nlog:\n${r.log ?? ""}`);
+  }
+  let end = start + 1;
+  let sentinelRun = 0;
+  for (let i = start; i < bin.length; i++) {
+    if (bin[i] === SENTINEL) {
+      sentinelRun++;
+      if (sentinelRun >= 64) break;
+    } else {
+      sentinelRun = 0;
+      end = i + 1;
+    }
+  }
+  return { bytes: bin.slice(start, end), log: r.log ?? "" };
+}
+
+// ─── vasm68k (m68k) ────────────────────────────────────────────────────
+// vasm has -Fbin output mode that emits raw bytes (no header, no symtab).
+// We pass org via the source itself.
+async function assembleVasm68k({ origin, code }) {
+  // vasm motorola syntax treats lines starting in column 0 as labels. We
+  // auto-indent any line that doesn't already start with whitespace and
+  // doesn't look like a label definition (ends with `:` or starts with a
+  // dot for local labels).
+  const indented = code.split("\n").map((line) => {
+    if (line.length === 0) return line;
+    if (line[0] === " " || line[0] === "\t") return line;
+    if (/^[A-Za-z_.][\w$]*:/.test(line) || line.startsWith(";") || line.startsWith("*")) return line;
+    return "\t" + line;
+  }).join("\n");
+  const source = `\torg $${origin.toString(16).toUpperCase()}\n${indented}\n`;
+  const r = await runVasm68k({ source, options: ["-Fbin"] });
+  if (!r.binary || (r.exitCode != null && r.exitCode !== 0)) {
+    throw new Error(`assembleSnippet[vasm68k]: assembly failed.\nlog:\n${r.log ?? ""}`);
+  }
+  return { bytes: r.binary, log: r.log ?? "" };
+}
+
+// ─── sdcc (z80) ────────────────────────────────────────────────────────
+// sdasz80 produces a .rel; sdld relocates _CODE to codeLoc=origin and emits
+// an .ihx. We feed sdld a minimal empty crt0 (no entry, no startup code) so
+// the snippet bytes are the entire output. Then parse the .ihx and slice
+// from origin to the last byte written.
+//
+// Note: sdas refuses `.org` in a REL area, so we declare `_CODE` as REL and
+// let sdld relocate it. Leading tabs are required on each instruction line.
+async function assembleSdcc({ origin, code }) {
+  const indented = code.split("\n").map((l) => l.trim() ? "\t" + l.trim() : l).join("\n");
+  const source = `\t.module snippet\n\t.area _CODE\n${indented}\n`;
+  const asm = await runSdasz80({ source });
+  if (!asm.rel) {
+    throw new Error(`assembleSnippet[sdasz80]: assembly failed.\nlog:\n${asm.log ?? ""}`);
+  }
+  // Minimal empty crt0 rel: just declares _HEADER0 (zero bytes) and is
+  // enough for sdld to satisfy its hardcoded crt0.rel dependency.
+  const emptyCrt0 = "XL2\nH 1 areas 0 global symbols\nM crt0\nA _HEADER0 size 0 flags 0 addr 0\n";
+  const linked = await runSdld({
+    objects: { "main.rel": asm.rel },
+    port: "z80",
+    codeLoc: origin,
+    crt0: emptyCrt0,
+    libraries: [],
+  });
+  if (!linked.ihx) {
+    throw new Error(`assembleSnippet[sdld]: link failed.\nlog:\n${linked.log ?? ""}`);
+  }
+  const padded = ihxToBin(linked.ihx, 0x10000, 0xFF);
+  // Find first and last non-FF byte from origin onwards. The snippet bytes
+  // are exactly the run from origin to the last set byte.
+  let lastSet = origin - 1;
+  for (let i = origin; i < padded.length; i++) {
+    if (padded[i] !== 0xFF) lastSet = i;
+  }
+  if (lastSet < origin) {
+    throw new Error(`assembleSnippet[sdld]: no bytes produced at origin 0x${origin.toString(16)}`);
+  }
+  return { bytes: padded.slice(origin, lastSet + 1), log: (asm.log ?? "") + (linked.log ?? "") };
+}
+
+// ─── rgbds (GB / GBC SM83) ─────────────────────────────────────────────
+// rgbasm produces .o → rgblink → flat .gb (zero-padded). Slice from origin.
+async function assembleRgbds({ origin, code }) {
+  // rgbasm needs SECTION declarations to place code at an address.
+  const sectionAt = `$${origin.toString(16).toUpperCase()}`;
+  const source = `SECTION "snippet", ROMX[${sectionAt}], BANK[0]\n${code}\n`;
+  // Actually GB has no BANK[0] for fixed ROM — use ROM0 if origin < 0x4000.
+  const useRom0 = origin < 0x4000;
+  const realSource = useRom0
+    ? `SECTION "snippet", ROM0[${sectionAt}]\n${code}\n`
+    : `SECTION "snippet", ROMX[${sectionAt}], BANK[1]\n${code}\n`;
+  const asm = await runRgbasm({ source: realSource });
+  if (!asm.object) {
+    throw new Error(`assembleSnippet[rgbasm]: assembly failed.\nlog:\n${asm.log ?? ""}`);
+  }
+  const linked = await runRgblink({ objects: { "snippet.o": asm.object }, padValue: 0x00 });
+  if (!linked.binary) {
+    throw new Error(`assembleSnippet[rgblink]: link failed.\nlog:\n${linked.log ?? ""}`);
+  }
+  // Slice from origin, find last non-zero byte.
+  const start = useRom0 ? origin : (origin - 0x4000 + 0x4000); // bank 1 lives at file 0x4000
+  let lastNonZero = start;
+  for (let i = start; i < linked.binary.length; i++) {
+    if (linked.binary[i] !== 0) lastNonZero = i;
+  }
+  return { bytes: linked.binary.slice(start, lastNonZero + 1), log: (asm.log ?? "") + (linked.log ?? "") };
+}

package/src/toolchains/cc65/cc65.js

@@ -0,0 +1,395 @@
+// cc65 — bundled 6502 C compiler + assembler + linker.
+//
+// Provides a Node API that runs cc65 → ca65 → ld65 entirely in WebAssembly.
+// Each tool runs in its own Emscripten module with its own MEMFS. We shuttle
+// files between them via byte arrays.
+//
+// Public API:
+//   runCc65({ source, headers? }) → { asmSource, log, exitCode }
+//   runCa65({ source, includes? }) → { object, log, exitCode }
+//   runLd65({ objects, config, target, libraries? }) → { binary, log, exitCode }
+//   buildC({ source, target, headers?, includes? }) → { binary, log, exitCode }
+//   buildAsm({ source, target, includes? }) → { binary, log, exitCode }
+
+import { fileURLToPath } from "node:url";
+import { existsSync } from "node:fs";
+import path from "node:path";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// cc65's tool WASM AND its target share/ tree (include / asminc / lib / cfg /
+// target) both ship in romdev-toolchain-cc65. The share/ files are what ld65
+// needs to link a target, so they must come from the same place as the WASM.
+// Resolve the package's base dir once; fall back to a local copy under src/
+// if present (transition / dev). The package is a hard dep of romdev.
+function resolveCc65BaseDir() {
+  try {
+    const u = import.meta.resolve("romdev-toolchain-cc65");
+    const dir = path.dirname(fileURLToPath(u));
+    if (existsSync(path.join(dir, "wasm", "cc65.js"))) return dir;
+  } catch { /* package not resolvable — fall through to local */ }
+  if (existsSync(path.join(__dirname, "wasm", "cc65.js"))) return __dirname;
+  throw new Error("cc65 WASM not found — install romdev-toolchain-cc65");
+}
+// Lazy + memoized: resolve (and possibly throw "not installed") only on the
+// first cc65 build (NES/C64/Atari7800/Lynx), not at module load — so booting
+// the server never touches this package unless cc65 is actually used. Resolve
+// the base dir once; derive the wasm + share dirs from it on demand.
+let _cc65Base;
+const cc65Base = () => (_cc65Base ??= resolveCc65BaseDir());
+const wasmDir  = () => path.join(cc65Base(), "wasm");
+const shareDir = () => path.join(cc65Base(), "share", "cc65");
+
+import { runIsolated, textFile, binaryFile, getOutputBytes, getOutputText } from "../_worker/run.js";
+
+/**
+ * Compile a C source to 6502 assembly via cc65.
+ * @param {Object} args
+ * @param {string} args.source
+ * @param {Record<string, string>} [args.headers]
+ * @param {string[]} [args.options] extra cc65 flags
+ * @param {string} [args.target] target id (e.g. "nes", "c64")
+ */
+export async function runCc65(args) {
+  const { source, options = [], target } = args;
+  const headers = args.headers ?? {};
+  /** @type {import("../_worker/run.js").InputFile[]} */
+  const inputFiles = [textFile("/work/main.c", source)];
+  for (const [name, content] of Object.entries(headers)) {
+    inputFiles.push(textFile("/work/" + name, content));
+  }
+  const r = await runIsolated({
+    gluePath: path.join(wasmDir(), "cc65.js"),
+    argv: [
+      ...(target ? ["-t", target] : []),
+      "-I", "/share/cc65/include",
+      "-I", "/work",
+      ...options,
+      "-o", "/work/out.s",
+      "/work/main.c",
+    ],
+    inputFiles,
+    hostDirMounts: [
+      { hostDir: path.join(shareDir(), "include"), vfsDir: "/share/cc65/include" },
+    ],
+    outputFiles: [{ vfsPath: "/work/out.s", encoding: "utf8" }],
+  });
+  return {
+    log: r.log,
+    exitCode: r.exitCode,
+    asmSource: getOutputText(r, "/work/out.s"),
+    ...(r.crash ? { crash: r.crash, stage: "crash" } : {}),
+  };
+}
+
+/**
+ * Assemble a .s file with ca65.
+ * @param {Object} args
+ * @param {string} args.source assembly source
+ * @param {Record<string, string>} [args.includes]
+ * @param {string[]} [args.options]
+ * @param {string} [args.target]
+ */
+export async function runCa65(args) {
+  const { source, options = [], target } = args;
+  const includes = args.includes ?? {};
+  const binaryIncludes = args.binaryIncludes ?? {};
+  /** @type {import("../_worker/run.js").InputFile[]} */
+  const inputFiles = [textFile("/work/main.s", source)];
+  for (const [name, content] of Object.entries(includes)) {
+    inputFiles.push(textFile("/work/" + name, content));
+  }
+  for (const [name, b64] of Object.entries(binaryIncludes)) {
+    const bytes = b64 instanceof Uint8Array ? b64 : Buffer.from(b64, "base64");
+    inputFiles.push(binaryFile("/work/" + name, bytes));
+  }
+  const r = await runIsolated({
+    gluePath: path.join(wasmDir(), "ca65.js"),
+    argv: [
+      ...(target ? ["-t", target] : []),
+      "-I", "/share/cc65/asminc",
+      "-I", "/work",
+      ...options,
+      "-o", "/work/out.o",
+      "/work/main.s",
+    ],
+    inputFiles,
+    hostDirMounts: [
+      { hostDir: path.join(shareDir(), "asminc"), vfsDir: "/share/cc65/asminc" },
+    ],
+    outputFiles: [{ vfsPath: "/work/out.o", encoding: "base64" }],
+  });
+  return {
+    log: r.log,
+    exitCode: r.exitCode,
+    object: getOutputBytes(r, "/work/out.o"),
+    ...(r.crash ? { crash: r.crash, stage: "crash" } : {}),
+  };
+}
+
+/**
+ * Link object files into a final binary using ld65.
+ *
+ * @param {Object} args
+ * @param {Record<string, Uint8Array>} args.objects map of name → object bytes
+ * @param {string} args.target target id (resolves to lib/<target>.lib + cfg/<target>.cfg)
+ * @param {string[]} [args.libraries] extra .lib names (without path) to add
+ * @param {string[]} [args.options] extra ld65 flags
+ * @param {boolean} [args.debug] if true, emit `/work/out.dbg` debug info
+ * @param {string} [args.linkerConfig] custom ld65 config (overrides the per-target default)
+ */
+export async function runLd65(args) {
+  const { objects, target, libraries = [], options = [], debug, linkerConfig } = args;
+  const extra = debug ? ["--dbgfile", "/work/out.dbg"] : [];
+  // If a custom config is supplied, use -C and skip -t (mixing the two confuses ld65;
+  // -t auto-loads cfg/<target>.cfg from the search path which overrides our intent).
+  const configArgs = linkerConfig
+    ? ["-C", "/work/custom.cfg"]
+    : ["-t", target];
+  /** @type {import("../_worker/run.js").InputFile[]} */
+  const inputFiles = [];
+  for (const [name, bytes] of Object.entries(objects)) {
+    inputFiles.push(binaryFile("/work/" + name, bytes));
+  }
+  if (linkerConfig) {
+    inputFiles.push(textFile("/work/custom.cfg", linkerConfig));
+  }
+  const outputFiles = [
+    { vfsPath: "/work/out.bin", encoding: "base64" },
+    // Always emit the linker map — its Segment list gives us per-segment
+    // sizes (BSS / DATA / ZEROPAGE / stack), which we surface as RAM usage
+    // so the agent sees "you used 380/512 B of BSS" instead of discovering
+    // a silent overflow at runtime.
+    { vfsPath: "/work/out.map", encoding: "utf8" },
+  ];
+  if (debug) outputFiles.push({ vfsPath: "/work/out.dbg", encoding: "utf8" });
+  const r = await runIsolated({
+    gluePath: path.join(wasmDir(), "ld65.js"),
+    argv: [
+      ...configArgs,
+      "-o", "/work/out.bin",
+      "--mapfile", "/work/out.map",
+      ...extra,
+      ...options,
+      ...Object.keys(objects).map((n) => "/work/" + n),
+      "/share/cc65/lib/" + target + ".lib",
+      ...libraries.map((l) => "/share/cc65/lib/" + l),
+    ],
+    inputFiles,
+    hostDirMounts: [
+      { hostDir: path.join(shareDir(), "lib"), vfsDir: "/share/cc65/lib" },
+      { hostDir: path.join(shareDir(), "cfg"), vfsDir: "/share/cc65/cfg" },
+    ],
+    outputFiles,
+  });
+  return {
+    log: r.log,
+    exitCode: r.exitCode,
+    binary: getOutputBytes(r, "/work/out.bin"),
+    dbg: debug ? getOutputText(r, "/work/out.dbg") : null,
+    map: getOutputText(r, "/work/out.map") || null,
+    ...(r.crash ? { crash: r.crash, stage: "crash" } : {}),
+  };
+}
+
+/**
+ * Parse an ld65 map file's "Segment list" into RAM-usage info. ld65's map
+ * has a section like:
+ *   Segments list:
+ *   -------------
+ *   ZEROPAGE          Start End   Size  Align ...
+ *   BSS               000300 0004C8 0001C8 ...
+ * We pull out the segments that live in RAM (BSS / DATA / ZEROPAGE / a few
+ * common stack/heap names) with their sizes, so the agent can see how close
+ * it is to the per-config RAM ceiling. Returns null if the map can't be
+ * parsed (best-effort — never throws).
+ * @param {string|null} mapText
+ * @returns {{segments: Array<{name:string,start:number,end:number,size:number}>, note:string}|null}
+ */
+export function parseRamUsage(mapText) {
+  if (!mapText || typeof mapText !== "string") return null;
+  // The map's segment table rows look like: NAME  HHHHHH  HHHHHH  HHHHHH  ...
+  // (name, start, end, size — all hex). Match those rows.
+  const rows = [];
+  const re = /^([A-Z_][A-Z0-9_]*)\s+([0-9A-Fa-f]{6})\s+([0-9A-Fa-f]{6})\s+([0-9A-Fa-f]{6})\b/gm;
+  let m;
+  while ((m = re.exec(mapText))) {
+    const size = parseInt(m[4], 16);
+    if (size === 0) continue;
+    rows.push({ name: m[1], start: parseInt(m[2], 16), end: parseInt(m[3], 16), size });
+  }
+  if (!rows.length) return null;
+  // RAM-resident segments (cc65 conventions). BSS = uninitialised globals,
+  // DATA = initialised globals (RAM copy), ZEROPAGE = zp vars. Stack/heap
+  // segments vary by target; include common names.
+  // RAM = the data/bss/zp segments, AND they must live below the ROM window
+  // (cc65 RAM is in low memory; PRG/code segments like STARTUP/CODE sit at
+  // $8000+ on NES and shouldn't count as RAM usage).
+  const segments = rows.filter(
+    (r) => /^(BSS|DATA|ZEROPAGE|ZP|BSS2)$/.test(r.name) && r.start < 0x8000,
+  );
+  if (!segments.length) return null;
+  return {
+    segments,
+    note: "RAM segments from the linker map (sizes in bytes). On NROM/CHR-RAM, " +
+      "normal RAM is tight (~512 B for BSS/DATA outside zeropage + stack + " +
+      "shadow OAM). If BSS+DATA approaches the config's RAM region size, you're " +
+      "near overflow — symptoms are corrupted state / mystery crashes.",
+  };
+}
+
+/**
+ * Convenience: compile + assemble + link a C project to a binary.
+ *
+ * Supports either a single C source (`source: string`) or multiple translation
+ * units (`sources: { "main.c": "...", "level.c": "...", "audio.s": "..." }`).
+ * Files ending in `.s`/`.asm` are passed straight to ca65; everything else is
+ * treated as C and compiled to .s first.
+ *
+ * @param {Object} args
+ * @param {string} [args.source] single C file (shortcut)
+ * @param {Record<string, string>} [args.sources] map of filename → source
+ * @param {string} args.target target id (e.g. "nes")
+ * @param {Record<string, string>} [args.headers] virtual headers visible to cc65
+ * @param {Record<string, string>} [args.asmIncludes] virtual includes visible to ca65
+ * @param {boolean} [args.debug] if true, also produce a ld65 .dbg file
+ * @param {string} [args.linkerConfig] custom ld65 .cfg (overrides per-target default)
+ */
+export async function buildC(args) {
+  const ccOpts = args.debug ? ["-g"] : [];
+  const caOpts = args.debug ? ["-g"] : [];
+  const sources = normalizeSources(args, "main.c");
+
+  let log = "";
+  /** @type {Record<string, Uint8Array>} */
+  const objects = {};
+  for (const [name, src] of Object.entries(sources)) {
+    const ext = path.extname(name).toLowerCase();
+    let asmSource;
+    let asmName;
+    if (ext === ".s" || ext === ".asm") {
+      asmSource = src;
+      asmName = name;
+    } else {
+      const cc = await runCc65({
+        source: src,
+        headers: args.headers,
+        target: args.target,
+        options: ccOpts,
+      });
+      log += `--- cc65 (${name}) ---\n` + cc.log + "\n";
+      if (cc.exitCode !== 0 || !cc.asmSource) {
+        return { binary: null, log, exitCode: cc.exitCode || 1, stage: "cc65" };
+      }
+      asmSource = cc.asmSource;
+      asmName = name.replace(/\.(c|h)$/i, ".s");
+    }
+    const ca = await runCa65({
+      source: asmSource,
+      includes: args.asmIncludes,
+      binaryIncludes: args.binaryIncludes,
+      target: args.target,
+      options: caOpts,
+    });
+    log += `--- ca65 (${asmName}) ---\n` + ca.log + "\n";
+    if (ca.exitCode !== 0 || !ca.object) {
+      return { binary: null, log, exitCode: ca.exitCode || 1, stage: "ca65" };
+    }
+    const objName = asmName.replace(/\.s$/, ".o");
+    objects[objName] = ca.object;
+  }
+  const ld = await runLd65({
+    objects,
+    target: args.target,
+    debug: args.debug,
+    linkerConfig: args.linkerConfig,
+  });
+  log += "--- ld65 ---\n" + ld.log;
+  return {
+    binary: ld.binary,
+    dbg: ld.dbg,
+    log,
+    exitCode: ld.exitCode,
+    ramUsage: parseRamUsage(ld.map),
+    stage: ld.exitCode === 0 ? "done" : "ld65",
+  };
+}
+
+/**
+ * Convenience: assemble + link a ca65 project to a binary.
+ *
+ * Supports either a single .s source (`source: string`) or multiple
+ * translation units (`sources: { "main.s": "...", "aliens.s": "..." }`).
+ * Each source becomes its own .o file and the linker is called once with the
+ * full bag.
+ *
+ * @param {Object} args
+ * @param {string} [args.source]
+ * @param {Record<string, string>} [args.sources]
+ * @param {string} args.target
+ * @param {Record<string, string>} [args.includes] visible to every ca65 invocation (via `.include "name"`)
+ * @param {boolean} [args.debug]
+ * @param {string} [args.linkerConfig] custom ld65 .cfg
+ */
+export async function buildAsm(args) {
+  const caOpts = args.debug ? ["-g"] : [];
+  const sources = normalizeSources(args, "main.s");
+
+  let log = "";
+  /** @type {Record<string, Uint8Array>} */
+  const objects = {};
+  for (const [name, src] of Object.entries(sources)) {
+    const ca = await runCa65({
+      source: src,
+      includes: args.includes,
+      binaryIncludes: args.binaryIncludes,
+      target: args.target,
+      options: caOpts,
+    });
+    log += `--- ca65 (${name}) ---\n` + ca.log + "\n";
+    if (ca.exitCode !== 0 || !ca.object) {
+      return { binary: null, log, exitCode: ca.exitCode || 1, stage: "ca65" };
+    }
+    const objName = name.replace(/\.(s|asm)$/i, ".o");
+    objects[objName] = ca.object;
+  }
+  const ld = await runLd65({
+    objects,
+    target: args.target,
+    debug: args.debug,
+    linkerConfig: args.linkerConfig,
+  });
+  log += "--- ld65 ---\n" + ld.log;
+  return {
+    binary: ld.binary,
+    dbg: ld.dbg,
+    log,
+    exitCode: ld.exitCode,
+    ramUsage: parseRamUsage(ld.map),
+    stage: ld.exitCode === 0 ? "done" : "ld65",
+  };
+}
+
+/**
+ * Build helpers accept either { source: "..." } or { sources: {name: "..."}}.
+ * This normalizes either shape into a single map. Throws if both/neither given.
+ * @param {{source?: string, sources?: Record<string, string>}} args
+ * @param {string} defaultName filename to assign when only `source` is given
+ * @returns {Record<string, string>}
+ */
+function normalizeSources(args, defaultName) {
+  if (args.sources && args.source) {
+    throw new Error("pass either `source` (single) or `sources` (map), not both");
+  }
+  if (args.sources) {
+    if (Object.keys(args.sources).length === 0) {
+      throw new Error("`sources` must be a non-empty map of filename → contents");
+    }
+    return args.sources;
+  }
+  if (typeof args.source === "string") {
+    return { [defaultName]: args.source };
+  }
+  throw new Error("missing `source` or `sources`");
+}