romdevtools 0.71.1 → 0.84.1

package/src/toolchains/common/c-build.js

@@ -0,0 +1,109 @@
+// Shared C-SDK build-pipeline helper (0.81.0). The gba-c / genesis-c / mips-c / sh-c
+// builders all walk the SAME spine — compile each .c (cc1 → as), assemble raw .s,
+// assemble a crt0, link, optionally objcopy, finalize — and at EVERY stage repeat the
+// identical 5-part dance:
+//
+//     const r = await runX(...);
+//     log += `--- stage ---\n${r.log || "(ok)"}\n`;
+//     if (r.exitCode !== 0 || !r.<output>)
+//       return { ok: false, binary: null, log, exitCode: r.exitCode || 1, stage, ...(r.crash ? { crash } : {}) };
+//
+// That `if (...) return { ok:false, ... }` line appeared ~73 times across the 5 builders.
+// CBuild owns it: each builder makes one `new CBuild()`, calls `.stage(name, () => runX(...), pick)`,
+// and the helper accumulates the log + THROWS a BuildError on any failure. The builder
+// wraps its body in try/catch and turns a BuildError into the same `{ ok:false, ... }` shape
+// it returned before — so the public contract is byte-for-byte unchanged, the boilerplate
+// is gone, and each builder keeps only its genuinely-per-platform wiring (which crt0, which
+// libs, finalize). No behavior change.
+
+/**
+ * Thrown by CBuild.stage() when a stage fails. Carries everything the builder's
+ * error return needs. The builder catches it and maps to its result object.
+ */
+export class BuildError extends Error {
+  /** @param {{stage:string, exitCode:number, log:string, crash?:any}} info */
+  constructor(info) {
+    super(`build failed at stage: ${info.stage}`);
+    this.name = "BuildError";
+    this.stage = info.stage;
+    this.exitCode = info.exitCode;
+    this.log = info.log;
+    if (info.crash) this.crash = info.crash;
+  }
+  /**
+   * The canonical failure result the GCC/tcc C-SDK builders return (includes
+   * `ok: false`). Pass extra fields (e.g. a platform-specific `{ runtime }`) to merge.
+   * @param {Record<string, any>} [extra]
+   */
+  toResult(extra = {}) {
+    return { ok: false, ...this.fields(extra) };
+  }
+
+  /**
+   * The failure fields WITHOUT a forced `ok` — for builders (cc65/sdcc) whose
+   * lower layer returns `{ binary, log, exitCode, stage }` and lets the caller
+   * (index.js) add `ok`. Same { binary:null, log, exitCode, stage, crash? } core
+   * + any `extra` (e.g. sdcc's `failedTU` / `compiledOK`). Note: crash is only
+   * spread when present (cc65/sdcc historically never carried it — pass nothing).
+   * @param {Record<string, any>} [extra]
+   */
+  fields(extra = {}) {
+    return {
+      binary: null,
+      log: this.log,
+      exitCode: this.exitCode,
+      stage: this.stage,
+      ...(this.crash ? { crash: this.crash } : {}),
+      ...extra,
+    };
+  }
+}
+
+/**
+ * A build-log accumulator + stage runner. One per build.
+ *
+ * Usage:
+ *   const cb = new CBuild();
+ *   const cc = await cb.stage(`cc1 (${name})`, () => runCc1x({...}), r => r.asmSource);
+ *   // cc is the full run result; cb.log has the accumulated log.
+ *   // a failure THROWS BuildError — wrap the build body in try/catch.
+ */
+export class CBuild {
+  constructor() {
+    /** @type {string} accumulated build log */
+    this.log = "";
+  }
+
+  /**
+   * Run one toolchain stage, append its log, and throw BuildError on failure.
+   *
+   * @template T
+   * @param {string} name  stage label — the failure `stage` field AND, by default,
+   *                       the log header. Most builders use one string for both.
+   * @param {() => Promise<T>} run  the toolchain call (returns {log, exitCode, crash?, ...output})
+   * @param {(r: T) => any} pick  selects the stage's required output (e.g. r => r.object);
+   *                              a falsy result is treated as failure even if exitCode is 0
+   * @param {{logName?:string}} [opts]  `logName` overrides ONLY the log header when a
+   *                       builder historically logged a label that differs from the
+   *                       failure `stage` string (e.g. log "as (x → .o)" / stage "as (x)").
+   * @returns {Promise<T>} the full run result (on success)
+   */
+  async stage(name, run, pick, opts = {}) {
+    const r = await run();
+    this.log += `--- ${opts.logName ?? name} ---\n${r.log || "(ok)"}\n`;
+    if (r.exitCode !== 0 || !pick(r)) {
+      throw new BuildError({
+        stage: name,
+        exitCode: r.exitCode || 1,
+        log: this.log,
+        crash: r.crash,
+      });
+    }
+    return r;
+  }
+
+  /** Append a freeform note to the log (e.g. a sub-step that isn't a toolchain stage). */
+  note(text) {
+    this.log += text.endsWith("\n") ? text : text + "\n";
+  }
+}

package/src/toolchains/common/gcc-toolchain.js

@@ -0,0 +1,164 @@
+// Shared GCC-family toolchain factory (0.81.0). The arm/m68k/mips/sh "gcc" wrappers
+// were ~73% identical: each exported runCc1X / runXAs / runXLd / runXObjcopy that did
+// the same input-marshalling + runIsolated() + output-decoding, differing only in:
+//   - the npm package the glue ships in + the glue filenames
+//   - the per-stage arch flags (cc1 / as / ld), which for MIPS depend on endian
+//   - the linker-script filename + the objcopy output filename
+// makeGccToolchain(config) returns the 4 run functions, so each arch shrinks to a
+// small config object. Glue resolution is lazy+memoized (booting never loads a
+// toolchain package until something is actually built with it).
+//
+// All four stages keep the exact pre-refactor argv, /work paths, output encodings,
+// and return shapes (including `...(r.crash ? { crash, stage:"crash" } : {})`), so
+// this is a pure de-duplication — no behavior change.
+import { runIsolated, getOutputBytes, getOutputText } from "../_worker/run.js";
+import { makeGlueResolver, marshalInputs } from "./wasm-tool.js";
+
+/**
+ * @typedef {Object} GccArchConfig
+ * @property {string}   pkg          npm package the glue ships in
+ * @property {string}   localDir     the wrapper's __dirname (dev fallback base)
+ * @property {string}   label        tool label for "not found" errors
+ * @property {Object}   glue         glue filenames per stage
+ * @property {string}   glue.cc1     e.g. "cc1-m68k.mjs"
+ * @property {string}   glue.as      e.g. "m68k-elf-as.mjs"
+ * @property {string}   glue.ld      e.g. "m68k-elf-ld.mjs"
+ * @property {string}   glue.objcopy e.g. "m68k-elf-objcopy.mjs"
+ * @property {string[]|((endian:string)=>string[])} cc1Flags  arch flags for cc1 (before -iquote/-I)
+ * @property {string[]|((endian:string)=>string[])} asFlags   arch flags for as (before -I)
+ * @property {string[]|((endian:string)=>string[])} [ldFlags] arch flags for ld (before -T); default []
+ * @property {string}   ldScriptName name the link script is mounted as (e.g. "genesis.ld")
+ * @property {string}   outputName   objcopy output filename (e.g. "main.bin", "main.gba")
+ * @property {string}   [defaultEndian] "big"|"little" — only meaningful when flags are fns
+ */
+
+/** Resolve a flags entry that may be a constant array or an endian-dependent fn. */
+function flags(entry, endian) {
+  return typeof entry === "function" ? entry(endian) : (entry ?? []);
+}
+
+/**
+ * Build the 4 GCC-stage run functions for one architecture.
+ * @param {GccArchConfig} config
+ * @returns {{ runCc1:Function, runAs:Function, runLd:Function, runObjcopy:Function }}
+ */
+export function makeGccToolchain(config) {
+  const glue = makeGlueResolver({ pkg: config.pkg, localDir: config.localDir, label: config.label });
+  const endianOf = (args) => args.endian ?? config.defaultEndian ?? "big";
+
+  /** cc1: C source → assembly (.s). */
+  async function runCc1(args) {
+    const { source, options = [] } = args;
+    const inputFiles = marshalInputs({ primary: { name: "main.c", text: source }, text: args.headers ?? {} });
+    const argv = [
+      ...flags(config.cc1Flags, endianOf(args)),
+      "-iquote", "/work",
+      "-I", "/work",
+      ...options,
+      "/work/main.c",
+      "-o", "/work/main.s",
+    ];
+    const r = await runIsolated({
+      gluePath: glue(config.glue.cc1),
+      argv,
+      inputFiles,
+      outputFiles: [{ vfsPath: "/work/main.s", encoding: "utf8" }],
+    });
+    return {
+      log: r.log,
+      exitCode: r.exitCode,
+      asmSource: getOutputText(r, "/work/main.s") || null,
+      ...(r.crash ? { crash: r.crash, stage: "crash" } : {}),
+    };
+  }
+
+  /** as: assembly (.s) → object (.o). */
+  async function runAs(args) {
+    const { source, options = [] } = args;
+    const inputFiles = marshalInputs({
+      primary: { name: "main.s", text: source },
+      text: args.includes ?? {},
+      binary: args.binaryIncludes ?? {},
+    });
+    const argv = [
+      ...flags(config.asFlags, endianOf(args)),
+      "-I", "/work",
+      ...options,
+      "/work/main.s",
+      "-o", "/work/main.o",
+    ];
+    const r = await runIsolated({
+      gluePath: glue(config.glue.as),
+      argv,
+      inputFiles,
+      outputFiles: [{ vfsPath: "/work/main.o", encoding: "base64" }],
+    });
+    return {
+      log: r.log,
+      exitCode: r.exitCode,
+      object: getOutputBytes(r, "/work/main.o"),
+      ...(r.crash ? { crash: r.crash, stage: "crash" } : {}),
+    };
+  }
+
+  /** ld: objects + link script → ELF (+ map). */
+  async function runLd(args) {
+    const { objects, linkScript, libraries = [], libraryPaths = [], options = [] } = args;
+    const inputFiles = marshalInputs({
+      text: { [config.ldScriptName]: linkScript },
+      binary: { ...objects, ...(args.archives ?? {}) },
+    });
+    const argv = [
+      ...flags(config.ldFlags, endianOf(args)),
+      "-T", "/work/" + config.ldScriptName,
+      "-o", "/work/main.elf",
+      "-Map=/work/main.map",
+      ...libraryPaths.flatMap((p) => ["-L", p]),
+      ...Object.keys(objects).map((n) => "/work/" + n),
+      ...libraries.map((l) => `-l${l}`),
+      ...options,
+    ];
+    const r = await runIsolated({
+      gluePath: glue(config.glue.ld),
+      argv,
+      inputFiles,
+      outputFiles: [
+        { vfsPath: "/work/main.elf", encoding: "base64" },
+        { vfsPath: "/work/main.map", encoding: "utf8" },
+      ],
+    });
+    return {
+      log: r.log,
+      exitCode: r.exitCode,
+      elf: getOutputBytes(r, "/work/main.elf"),
+      map: getOutputText(r, "/work/main.map") || null,
+      ...(r.crash ? { crash: r.crash, stage: "crash" } : {}),
+    };
+  }
+
+  /** objcopy: ELF → raw binary. */
+  async function runObjcopy(args) {
+    const { elf, options = [] } = args;
+    const inputFiles = marshalInputs({ binary: { "main.elf": elf } });
+    const argv = [
+      "-O", "binary",
+      ...options,
+      "/work/main.elf",
+      "/work/" + config.outputName,
+    ];
+    const r = await runIsolated({
+      gluePath: glue(config.glue.objcopy),
+      argv,
+      inputFiles,
+      outputFiles: [{ vfsPath: "/work/" + config.outputName, encoding: "base64" }],
+    });
+    return {
+      log: r.log,
+      exitCode: r.exitCode,
+      binary: getOutputBytes(r, "/work/" + config.outputName),
+      ...(r.crash ? { crash: r.crash, stage: "crash" } : {}),
+    };
+  }
+
+  return { runCc1, runAs, runLd, runObjcopy };
+}

package/src/toolchains/common/wasm-tool.js

@@ -0,0 +1,101 @@
+// Shared WASM-toolchain plumbing (0.81.0). Every toolchain wrapper used to
+// re-implement the SAME two things:
+//   1. Resolve a tool's emscripten glue from its npm package, with a local
+//      src/ fallback for dev, throwing an install hint if neither exists.
+//   2. Marshal { name: text|bytes } maps into the runIsolated() inputFiles[]
+//      shape (textFile / binaryFile per entry).
+// This module owns both so the per-tool wrappers carry only what's genuinely
+// tool-specific (package name, glue filename, argv, output decoding).
+//
+// Resolution stays LAZY at the call site (the wrappers memoize) so booting the
+// server never touches a 100MB+ toolchain package unless that toolchain is
+// actually used to build something.
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+import { textFile, binaryFile } from "../_worker/run.js";
+
+/**
+ * Resolve a single tool glue FILE from its package, falling back to a local
+ * in-tree copy. This is the arm/m68k/mips/sh-gcc + asar + wladx + rgbds + dasm +
+ * vasm68k + sjasm + tcc816 shape (one .js/.mjs glue per tool).
+ *
+ * @param {Object} a
+ * @param {string} a.pkg        npm package the glue ships in (e.g. "romdev-platform-gba")
+ * @param {string} a.file       glue filename inside the package's wasm/ dir (e.g. "cc1-arm.mjs")
+ * @param {string} a.localDir   the wrapper's __dirname (its wasm/ holds the dev fallback)
+ * @param {string} [a.label]    tool name for the "not found" error (defaults to file)
+ * @returns {string} absolute path to the glue file
+ */
+export function resolveGlueFile({ pkg, file, localDir, label }) {
+  try {
+    const u = import.meta.resolve(pkg);
+    const p = path.join(path.dirname(fileURLToPath(u)), "wasm", file);
+    if (existsSync(p)) return p;
+  } catch { /* package not resolvable — fall through to local */ }
+  const local = path.join(localDir, "wasm", file);
+  if (existsSync(local)) return local;
+  throw new Error(`${label ?? file} WASM not found — install ${pkg}`);
+}
+
+/**
+ * Resolve a tool's BASE directory (the caller derives wasm/ + share/ from it).
+ * This is the cc65 + sdcc shape, where one package holds several tools + shared
+ * data and the wrapper wants the root, validated by a sentinel file's presence.
+ *
+ * @param {Object} a
+ * @param {string} a.pkg          npm package (e.g. "romdev-toolchain-cc65")
+ * @param {string} a.sentinel     a path under the base that must exist (e.g. "wasm/cc65.js")
+ * @param {string} a.localDir     the wrapper's __dirname (the dev fallback base)
+ * @param {string} [a.label]      tool name for the "not found" error
+ * @returns {string} absolute path to the base dir
+ */
+export function resolveToolBaseDir({ pkg, sentinel, localDir, label }) {
+  try {
+    const u = import.meta.resolve(pkg);
+    const dir = path.dirname(fileURLToPath(u));
+    if (existsSync(path.join(dir, sentinel))) return dir;
+  } catch { /* package not resolvable — fall through to local */ }
+  if (existsSync(path.join(localDir, sentinel))) return localDir;
+  throw new Error(`${label ?? pkg} WASM not found — install ${pkg}`);
+}
+
+/**
+ * A lazy, memoized glue resolver bound to a package + local dir. Returns a
+ * function `glue(file)` that resolves+caches each glue path on first use.
+ * Replaces the `const _glue = {}; const xGlue = (f) => (_glue[f] ??= ...)`
+ * boilerplate every multi-tool wrapper repeats.
+ *
+ * @param {Object} a
+ * @param {string} a.pkg
+ * @param {string} a.localDir
+ * @param {string} [a.label]
+ * @returns {(file: string) => string}
+ */
+export function makeGlueResolver({ pkg, localDir, label }) {
+  const cache = {};
+  return (file) =>
+    (cache[file] ??= resolveGlueFile({ pkg, file, localDir, label }));
+}
+
+/**
+ * Marshal text + binary virtual-file maps into the runIsolated() inputFiles[]
+ * array, all rooted at /work. Order: the primary source first (if given), then
+ * text entries, then binary entries — matching what the wrappers built by hand.
+ *
+ * @param {Object} a
+ * @param {{name: string, text: string}} [a.primary]   the main source (e.g. main.c → /work/main.c)
+ * @param {Record<string,string>} [a.text]             virtual text files (headers, includes, link scripts)
+ * @param {Record<string,Uint8Array>} [a.binary]       virtual binary files (objects, archives, binary includes)
+ * @returns {import("../_worker/run.js").InputFile[]}
+ */
+export function marshalInputs({ primary, text = {}, binary = {} } = {}) {
+  /** @type {import("../_worker/run.js").InputFile[]} */
+  const files = [];
+  if (primary) files.push(textFile("/work/" + primary.name, primary.text));
+  for (const [name, content] of Object.entries(text))
+    files.push(textFile("/work/" + name, content));
+  for (const [name, bytes] of Object.entries(binary))
+    files.push(binaryFile("/work/" + name, bytes));
+  return files;
+}

package/src/toolchains/dasm/dasm.js

@@ -3,32 +3,26 @@
 // Runs in an isolated child worker for crash isolation.
 
 import { fileURLToPath } from "node:url";
-import { existsSync } from "node:fs";
 import path from "node:path";
 
 import { runIsolated, textFile, getOutputBytes, getOutputText } from "../_worker/run.js";
+import { resolveGlueFile } from "../common/wasm-tool.js";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 
-// dasm's WASM ships in romdev-platform-atari2600 (the only platform that
-// uses it). 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 resolveDasmGlue() {
-  try {
-    const u = import.meta.resolve("romdev-platform-atari2600");
-    const p = path.join(path.dirname(fileURLToPath(u)), "wasm", "dasm.js");
-    if (existsSync(p)) return p;
-  } catch { /* package not resolvable — fall through to local */ }
-  const local = path.join(__dirname, "wasm", "dasm.js");
-  if (existsSync(local)) return local;
-  throw new Error("dasm WASM not found — install romdev-platform-atari2600");
-}
-// Lazy + memoized: resolve (and possibly throw "not installed") only on the
-// FIRST dasm build, not at module load — so booting the server never touches
-// this package unless an Atari 2600 ROM is actually built.
+// dasm's WASM ships in romdev-platform-atari2600 (the only platform that uses
+// it); a local src/ copy is the dev fallback. Lazy + memoized: resolve only on
+// the FIRST dasm build, not at boot — so booting the server never touches this
+// package unless an Atari 2600 ROM is actually built.
 let _gluePath;
-const gluePath = () => (_gluePath ??= resolveDasmGlue());
+const gluePath = () =>
+  (_gluePath ??= resolveGlueFile({
+    pkg: "romdev-platform-atari2600",
+    file: "dasm.js",
+    localDir: __dirname,
+    label: "dasm",
+  }));
 
 /**
  * Run dasm on a source program in-memory.