@8bitscript/cli 0.1.0

package/src/png.mjs

@@ -0,0 +1,158 @@
+// A minimal PNG encoder — just enough to turn a raw RGBA buffer into a
+// `.png` file, with no dependency beyond Node's own zlib. Used by the
+// `--screenshot` targets that have no emulator-native PNG writer of their
+// own to call into (see screenshot.mjs's web target): once a target can
+// ask its own emulator to save a PNG (VICE's -exitscreenshot, Xemu's
+// -screenshot, FCEUX's gui.savescreenshotas), that's always preferred —
+// this exists only for the one target with nothing to ask.
+import { deflateSync, inflateSync } from 'node:zlib';
+
+// The standard CRC-32 (IEEE 802.3) table PNG's spec requires for every
+// chunk's trailing checksum.
+const CRC_TABLE = (() => {
+  const table = new Uint32Array(256);
+  for (let n = 0; n < 256; n += 1) {
+    let c = n;
+    for (let k = 0; k < 8; k += 1) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+    table[n] = c >>> 0;
+  }
+  return table;
+})();
+
+function crc32(buf) {
+  let c = 0xffffffff;
+  for (let i = 0; i < buf.length; i += 1) c = CRC_TABLE[(c ^ buf[i]) & 0xff] ^ (c >>> 8);
+  return (c ^ 0xffffffff) >>> 0;
+}
+
+function chunk(type, data) {
+  const typeBuf = Buffer.from(type, 'ascii');
+  const lenBuf = Buffer.alloc(4);
+  lenBuf.writeUInt32BE(data.length, 0);
+  const crcBuf = Buffer.alloc(4);
+  crcBuf.writeUInt32BE(crc32(Buffer.concat([typeBuf, data])), 0);
+  return Buffer.concat([lenBuf, typeBuf, data, crcBuf]);
+}
+
+const SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+
+/**
+ * Encode an RGBA pixel buffer (width*height*4 bytes, row-major, no padding)
+ * as a PNG file's bytes — 8-bit-per-channel, no filtering (filter type 0 on
+ * every scanline; the image sizes this project draws are small enough that
+ * skipping adaptive filtering costs a few hundred bytes, not correctness).
+ *
+ * @param {number} width
+ * @param {number} height
+ * @param {Uint8Array | Buffer} rgba
+ * @returns {Buffer}
+ */
+export function encodePNG(width, height, rgba) {
+  if (rgba.length !== width * height * 4) {
+    throw new Error(`png: expected ${width * height * 4} bytes for ${width}x${height} RGBA, got ${rgba.length}`);
+  }
+  const ihdr = Buffer.alloc(13);
+  ihdr.writeUInt32BE(width, 0);
+  ihdr.writeUInt32BE(height, 4);
+  ihdr[8] = 8; // bit depth
+  ihdr[9] = 6; // color type 6 = RGBA
+  ihdr[10] = 0; // compression method
+  ihdr[11] = 0; // filter method
+  ihdr[12] = 0; // interlace method
+
+  const stride = width * 4;
+  const raw = Buffer.alloc((stride + 1) * height);
+  for (let y = 0; y < height; y += 1) {
+    raw[y * (stride + 1)] = 0; // filter type 0 (None) for every row
+    Buffer.from(rgba.buffer ?? rgba, rgba.byteOffset ?? 0, rgba.length)
+      .copy(raw, y * (stride + 1) + 1, y * stride, y * stride + stride);
+  }
+  const idat = deflateSync(raw);
+
+  return Buffer.concat([
+    SIGNATURE,
+    chunk('IHDR', ihdr),
+    chunk('IDAT', idat),
+    chunk('IEND', Buffer.alloc(0)),
+  ]);
+}
+
+// ---- and just enough of a decoder to read one pixel back ----------------
+//
+// The machine packages' hardware probes are verified by running them under
+// a real emulator and screenshotting the result: the probe encodes its
+// answer as a border colour, and the test reads one pixel of the border
+// rather than trying to recognise text (see packages/c64/test/reu.test.mjs
+// and packages/cx16/test/banks.test.mjs). This reads that pixel. It
+// handles what the emulators actually write — 8 bits a channel, RGB, RGBA
+// or palette, not interlaced — and throws on anything else rather than
+// guessing.
+
+/**
+ * The colour at (x, y) of a PNG file, as `[r, g, b]`.
+ *
+ * @param {Buffer} buf  the file's bytes
+ * @param {number} x
+ * @param {number} y
+ * @returns {[number, number, number]}
+ */
+export function pixelAt(buf, x, y) {
+  const signature = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+  if (!buf.subarray(0, 8).equals(signature)) throw new Error('not a PNG');
+  let offset = 8;
+  let width = 0; let height = 0; let depth = 0; let colorType = 0; let interlace = 0;
+  let palette = null;
+  const idat = [];
+  while (offset + 8 <= buf.length) {
+    const length = buf.readUInt32BE(offset);
+    const type = buf.toString('ascii', offset + 4, offset + 8);
+    const data = buf.subarray(offset + 8, offset + 8 + length);
+    if (type === 'IHDR') {
+      width = data.readUInt32BE(0); height = data.readUInt32BE(4);
+      depth = data[8]; colorType = data[9]; interlace = data[12];
+    } else if (type === 'PLTE') palette = data;
+    else if (type === 'IDAT') idat.push(data);
+    else if (type === 'IEND') break;
+    offset += 12 + length;
+  }
+  if (depth !== 8) throw new Error(`PNG bit depth ${depth} is not 8`);
+  if (interlace !== 0) throw new Error('interlaced PNG');
+  if (x >= width || y >= height) throw new Error(`(${x}, ${y}) is outside a ${width}x${height} image`);
+  const channels = { 0: 1, 2: 3, 3: 1, 4: 2, 6: 4 }[colorType];
+  if (!channels) throw new Error(`PNG colour type ${colorType}`);
+  const raw = inflateSync(Buffer.concat(idat));
+  const stride = width * channels;
+  // Every row's filter is relative to the row above, so rows up to y have
+  // to be undone in order; nothing below y is touched.
+  let previous = Buffer.alloc(stride);
+  let line = previous;
+  for (let row = 0; row <= y; row += 1) {
+    const filter = raw[row * (stride + 1)];
+    line = Buffer.from(raw.subarray(row * (stride + 1) + 1, (row + 1) * (stride + 1)));
+    for (let i = 0; i < stride; i += 1) {
+      const a = i >= channels ? line[i - channels] : 0;
+      const b = previous[i];
+      const c = i >= channels ? previous[i - channels] : 0;
+      let predictor = 0;
+      if (filter === 1) predictor = a;
+      else if (filter === 2) predictor = b;
+      else if (filter === 3) predictor = (a + b) >> 1;
+      else if (filter === 4) {
+        const p = a + b - c;
+        const pa = Math.abs(p - a); const pb = Math.abs(p - b); const pc = Math.abs(p - c);
+        predictor = pa <= pb && pa <= pc ? a : (pb <= pc ? b : c);
+      }
+      line[i] = (line[i] + predictor) & 0xff;
+    }
+    previous = line;
+  }
+  if (colorType === 3) {
+    const index = line[x];
+    return [palette[index * 3], palette[index * 3 + 1], palette[index * 3 + 2]];
+  }
+  if (channels <= 2) {
+    const grey = line[x * channels];
+    return [grey, grey, grey];
+  }
+  return [line[x * channels], line[x * channels + 1], line[x * channels + 2]];
+}

package/src/run.mjs

@@ -0,0 +1,311 @@
+// `8bs run <target>` — build, then actually run the program.
+//
+//   8bs run vic20        builds the .prg and opens it in the VICE VIC-20
+//                        emulator, machine model NTSC (60fps) — the default
+//   8bs run vic20 --pal  the same, machine model PAL (50fps)
+//   8bs run c64          the same idea, in the C64 emulator (NTSC default)
+//   8bs run c64 --pal
+//   8bs run pet          builds the .prg and opens it in VICE's PET emulator
+//                        (xpet) as the model the hardware names — a 3032 by
+//                        default: no CRTC, 40 columns, 32K, VICE's hardcoded
+//                        ~60.1Hz. --profile 8032 builds for and launches the
+//                        80-column business machine, 3008/3016/4016/4032 the
+//                        other RAM sizes and series (the `model` option in
+//                        packages/pet's catalog). There is no --pal for the
+//                        PET: its refresh is the model's (the CRTC models
+//                        run their 50Hz editor ROMs; the 60Hz ones make VICE
+//                        refuse autostart), and the program measures the
+//                        actual frame period at runtime (FRAME_SYNC.pet).
+//   8bs run c128         VICE's C128 emulator (x128), NTSC default, --pal
+//   8bs run atari8       builds for the default 800XL and opens it in
+//                        atari800; --profile picks another machine in the
+//                        family (130xe, xegs, ...), --pal/--ntsc the TV
+//                        standard (NTSC default)
+//   8bs run vic20 --profile 16k   builds for a 16K-expanded VIC-20 and
+//                        passes xvic the matching `-memory` flag, so the
+//                        emulated machine's RAM matches what the program
+//                        was linked for
+//   8bs run c64 --hardware ram=reu512,port1=mouse1351
+//                        builds for the stock C64 (neither changes the
+//                        memory map) and fits x64sc a 512K REU and a 1351
+//                        in port 1 — every option, and what each does, is
+//                        the machine package's catalog (`8bs targets`)
+//   8bs run nes          builds the .nes and opens it in FCEUX
+//   8bs run cx16          builds the .prg and opens it in x16emu
+//   8bs run mega65        builds the .prg and opens it in Xemu's MEGA65
+//                        core (xmega65) with -prg, which autoloads and RUNs
+//                        it in MEGA65 mode ($2001 load address; a c64-target
+//                        .prg would go to C64 mode) — verified on screen,
+//                        see packages/mega65/AGENTS.md
+//   8bs run web          builds the .wasm and opens it in the browser
+//                        runtime (web-runtime.mjs): the program runs in a
+//                        worker, its waitFrame() paced by the page's frame
+//                        clock, the page painting its screen memory — the
+//                        same for every program, whether it loops on
+//                        waitFrame(), returns, or spins
+//   8bs run web --no-open  the same, without spawning a browser window —
+//                        for pasting the printed URL into an editor's own
+//                        browser (e.g. VS Code/Cursor's "Simple Browser:
+//                        Show" command), which no CLI can open unattended:
+//                        that command only exists inside the editor, with
+//                        no terminal-invokable equivalent
+import { homedir, tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { readFile, writeFile } from 'node:fs/promises';
+
+import { compile } from './build.mjs';
+import { HARDWARE_USAGE, hardwareArgs, loadArgs } from './hardware.mjs';
+
+// The VICE family (vic20/c64/pet/c128): one emulator suite, one invocation
+// shape — -autostart injects the built file straight into RAM. Exported so
+// screenshot.mjs's --screenshot path (8bs run <target> --screenshot <file>)
+// can drive the same emulators/flags rather than keeping a second copy that
+// could drift from this one.
+export const VICE_EMULATOR = { vic20: 'xvic', c64: 'x64sc', pet: 'xpet', c128: 'x128' };
+
+// Flags the emulator needs to run our .prg files. The emulated machine must
+// match the memory layout the program was linked for: 8BitScript's vic20
+// target is the UNEXPANDED VIC-20 ($1001), which is also xvic's stock
+// configuration, so no memory flag is needed — but if the backend's
+// __memory_expansion pin ever changes, this table must change with it, or
+// autostart injects the program at the wrong address and silently never runs
+// it. RAM injection (-autostartprgmode 1) skips the emulated disk load. The
+// PET's __ram_size pin (32K) is likewise xpet's own stock default, so it
+// needs no matching flag either.
+// x128 alone among these drives two physical displays — the VIC-IIe (40-
+// column, what this target's screen/border/background all actually reach)
+// and the 80-column VDC, which this target never touches. Without
+// -hidevdcwindow, x128 opens a second window for it anyway, showing
+// whatever the VDC's power-on RAM happens to contain (typically a plain
+// black screen) alongside the real output — not a second copy of the
+// program, just an unused second monitor the hardware genuinely has.
+export const VICE_EMULATOR_ARGS = {
+  vic20: ['-autostartprgmode', '1'],
+  c64: ['-autostartprgmode', '1'],
+  pet: ['-autostartprgmode', '1'],
+  c128: ['-autostartprgmode', '1', '-hidevdcwindow'],
+};
+// -ntsc/-pal only flip VICE's sync factor (raster timing): the screen-origin
+// registers the KERNAL sets up at boot stay wired to whichever machine model
+// is loaded, so -ntsc alone can pair NTSC timing with PAL geometry and the
+// picture renders off-center. -model switches the whole machine (ROM set,
+// VIC-II/VIC geometry, and timing together), which is why vic20/c64/c128
+// name a model rather than a sync-factor flag. Verified against `x128 -help`
+// ("Set C128 model (c128/c128dcr, pal/ntsc)").
+//
+// The PET is not in this table: its refresh is not a sync factor but the
+// model's, and the model is a hardware option — see PET_REGION_NOTE below.
+export const VICE_MODEL_ARGS = {
+  vic20: { ntsc: ['-model', 'vic20ntsc'], pal: ['-model', 'vic20pal'] },
+  c64: { ntsc: ['-model', 'ntsc'], pal: ['-model', 'c64'] },
+  c128: { ntsc: ['-model', 'ntsc'], pal: ['-model', 'pal'] },
+};
+
+// The PET's model is a hardware option (packages/pet's catalog: `-model`
+// to xpet, `__ram_size` to the linker, the columns as a fact). No
+// `-ntsc`/`-pal` goes with it. VICE's own pet.h: 50Hz vs 60Hz on a PET is
+// which editor ROM programs the CRTC, not a sync factor. The 60Hz editor
+// ROMs VICE ships (`edit-4-*-60Hz*`) do switch the CRTC to ~60Hz, but
+// they also make VICE refuse autostart ("Autostart is not available on
+// this setup") — observed with both the 40-column and 80-column 60Hz
+// editors, with and without `-default` — so the CRTC models (4016, 4032,
+// 8032) run their stock 50Hz editors here, measured at 49.92-50.02Hz, and
+// the no-CRTC 3xxx models run at VICE's hardcoded ~60.1Hz. The program
+// measures whichever it gets at start-up (FRAME_SYNC.pet), so the build is
+// the same either way; `8bs run pet --pal` prints a note and changes
+// nothing. Verified with `xpet -verbose -limitcycles` and by whether
+// `-autostart` of examples/borders stays running.
+export const PET_REGION_NOTE = '8bs run: the PET has no --pal/--ntsc — its refresh rate is the model\'s. '
+  + 'Pick a model with --profile (3032 is ~60Hz; 4016, 4032 and 8032 are 50Hz).\n';
+
+// How each emulator is handed the built file when the hardware does not
+// say otherwise (a catalog value's `load` — the Atari XEGS cartridge —
+// overrides this; see hardware.mjs's loadArgs).
+export const DEFAULT_LOAD = {
+  xvic: (out) => ['-autostart', out],
+  x64sc: (out) => ['-autostart', out],
+  xpet: (out) => ['-autostart', out],
+  x128: (out) => ['-autostart', out],
+  atari800: (out) => ['-run', out],
+  fceux: (out) => [out],
+  x16emu: (out) => ['-prg', out, '-run'],
+  xmega65: (out) => ['-prg', out],
+};
+
+// atari800's SDL2 OpenGL shader (atari800-shader.frag) defaults
+// CRT_BEAM_SHAPE=10, which spreads each emulated pixel with a Gaussian
+// falloff — visible as dark vertical stripes across the whole frame,
+// border included, on top of the ordinary horizontal scanline overlay.
+// There is no CLI flag for that uniform (only SCANLINES_PERCENTAGE has
+// `-scanlines`), so `8bs run` copies the user's ~/.atari800.cfg, zeros
+// the CRT knobs, and points `-config` at a *per-process* copy with
+// `-no-autosave-config` so the user's own file is left alone. The path
+// includes the pid because `pnpm test` runs atari8 screenshot tests in
+// parallel (banks vs layers, and other packages' emulators at the same
+// time): a shared `8bs-atari800.cfg` is two writers and two atari800s
+// reading one file. ROM paths stay whatever the user already configured;
+// without those the emulator boots to black.
+export async function atari800CleanDisplayConfig() {
+  let cfg;
+  try {
+    cfg = await readFile(join(homedir(), '.atari800.cfg'), 'utf8');
+  } catch {
+    return null;
+  }
+  const setKey = (text, key, value) => {
+    const re = new RegExp(`^${key}=.*$`, 'm');
+    if (re.test(text)) return text.replace(re, `${key}=${value}`);
+    return `${text.trimEnd()}\n${key}=${value}\n`;
+  };
+  cfg = setKey(cfg, 'CRT_BEAM_SHAPE', '0');
+  cfg = setKey(cfg, 'CRT_PHOSPHOR_GLOW', '0');
+  cfg = setKey(cfg, 'SCANLINES_PERCENTAGE', '0');
+  cfg = setKey(cfg, 'INTERPOLATE_SCANLINES', '0');
+  const outPath = join(tmpdir(), `8bs-atari800-${process.pid}.cfg`);
+  await writeFile(outPath, cfg);
+  return outPath;
+}
+
+/** @returns {Promise<number>} exit code */
+export async function run(args) {
+  const pal = args.includes('--pal');
+  const open = !args.includes('--no-open');
+  const hw = hardwareArgs(args);
+  if (!hw.ok) {
+    process.stderr.write(`8bs run: ${hw.error}\n`);
+    return 2;
+  }
+  const screenshotIndex = args.indexOf('--screenshot');
+  const screenshotPath = screenshotIndex >= 0 ? resolve(args[screenshotIndex + 1]) : undefined;
+  const framesIndex = args.indexOf('--frames');
+  const framesArg = framesIndex >= 0 ? args[framesIndex + 1] : undefined;
+  const frames = framesArg !== undefined ? Number.parseInt(framesArg, 10) : undefined;
+  if (framesArg !== undefined && !Number.isFinite(frames)) {
+    process.stderr.write(`8bs run: --frames expects a number, got '${framesArg}'\n`);
+    return 2;
+  }
+  const consumed = new Set([
+    ...hw.consumed,
+    ...[screenshotIndex, framesIndex].flatMap((i) => (i >= 0 ? [i, i + 1] : [])),
+  ]);
+  const positionals = args.filter((a, i) => !consumed.has(i) && !a.startsWith('-'));
+  const target = positionals[0];
+  if (!target) {
+    process.stderr.write(
+      'Usage: 8bs run <vic20|c64|pet|c128|atari8|nes|cx16|mega65|web>\n'
+      + '                [--pal]\n'
+      + HARDWARE_USAGE
+      + '                [--no-open] [entry.8bs]\n'
+      + '                [--screenshot <file.png>] [--frames <n>]\n'
+      + '                  capture one screenshot through the target\'s own\n'
+      + '                  emulator API instead of opening an interactive\n'
+      + '                  window — see docs/setup/verify.md#screenshots for\n'
+      + '                  what --frames counts on each target\n',
+    );
+    return 2;
+  }
+  const entry = positionals[1];
+
+  // Said once, before either route — the PET has no region (PET_REGION_NOTE).
+  if (target === 'pet' && pal) process.stderr.write(PET_REGION_NOTE);
+
+  const { ok, outFile, frameRate, hardware } = await compile(target, entry, { pal, profile: hw.profile, hardware: hw.overrides });
+  if (!ok) return 1;
+
+  if (screenshotPath) {
+    const { captureScreenshot } = await import('./screenshot.mjs');
+    try {
+      await captureScreenshot(target, outFile, screenshotPath, {
+        pal, hardware, frames, frameRate,
+      });
+    } catch (err) {
+      process.stderr.write(`${err.message}\n`);
+      return 1;
+    }
+    process.stdout.write(`wrote ${screenshotPath}\n`);
+    return 0;
+  }
+
+  if (target === 'web') {
+    // Every program runs the same way on the web: in the browser runtime's
+    // worker (web-runtime.mjs), whether it loops on waitFrame(), returns, or
+    // spins. Headless execution is `--screenshot`'s job, bounded by --frames.
+    const { runInBrowser } = await import('./web-runtime.mjs');
+    const bytes = await readFile(outFile);
+    return runInBrowser(bytes, { open, frameRate, root: resolve('dist', 'web') });
+  }
+
+  const region = pal ? 'pal' : 'ntsc';
+
+  // The emulator's own flags for the machine, then whatever the hardware
+  // fits (the catalog's `run` list for this emulator), then the file.
+  let emulator;
+  let emulatorArgs;
+  if (target in VICE_EMULATOR) {
+    emulator = VICE_EMULATOR[target];
+    emulatorArgs = [
+      ...(VICE_EMULATOR_ARGS[target] ?? []),
+      ...(VICE_MODEL_ARGS[target]?.[region] ?? []),
+      ...(hardware.run[emulator] ?? []),
+      // Skip the "really quit?" confirmation dialog — closing the emulator
+      // window during dev/test cycles should not need a click every time.
+      '+confirmonexit',
+      ...loadArgs(hardware, emulator, outFile, DEFAULT_LOAD[emulator](outFile)),
+    ];
+  } else if (target === 'atari8') {
+    emulator = 'atari800';
+    // atari800's TV-area visible size (DOC/USAGE -horiz-area/-vert-area):
+    // 336 wide, 224 tall on NTSC and 240 tall on PAL. The emulator opens
+    // at 1x of that — a postage stamp on any modern display — and unlike
+    // VICE it has no larger default of its own. 3x is a window worth
+    // looking at on a 1080p screen and still an exact integer scale, which
+    // is what atari800's own default INTEGRAL stretch wants: a non-multiple
+    // just letterboxes the same small image inside a bigger window.
+    const tvHeight = pal ? 240 : 224;
+    const displayCfg = await atari800CleanDisplayConfig();
+    emulatorArgs = [
+      ...(displayCfg ? ['-config', displayCfg, '-no-autosave-config'] : []),
+      ...(hardware.run.atari800 ?? []),
+      pal ? '-pal' : '-ntsc',
+      '-horiz-area', 'tv',
+      '-vert-area', 'tv',
+      '-stretch', 'integral',
+      '-scanlines', '0',
+      '-win-width', String(336 * 3),
+      '-win-height', String(tvHeight * 3),
+      ...loadArgs(hardware, emulator, outFile, DEFAULT_LOAD.atari800(outFile)),
+    ];
+  } else if (target === 'nes') {
+    emulator = 'fceux';
+    emulatorArgs = [...(hardware.run.fceux ?? []), ...loadArgs(hardware, emulator, outFile, DEFAULT_LOAD.fceux(outFile))];
+  } else if (target === 'cx16') {
+    // Confirmed against the X16Community/x16-emulator README.
+    emulator = 'x16emu';
+    emulatorArgs = [...(hardware.run.x16emu ?? []), ...loadArgs(hardware, emulator, outFile, DEFAULT_LOAD.x16emu(outFile))];
+  } else if (target === 'mega65') {
+    // -videostd pins the video standard to match the region the .prg was
+    // built for (0=PAL, 1=NTSC); left unset, Xemu's Hyppo default is PAL
+    // regardless of which region this target compiled for, so an NTSC
+    // build gets PAL's ~100 extra scanlines of VIC-IV border/overscan — the
+    // exact off-geometry mismatch VICE_MODEL_ARGS above documents for
+    // -ntsc/-pal not implying a model.
+    emulator = 'xmega65';
+    emulatorArgs = [...(hardware.run.xmega65 ?? []), ...loadArgs(hardware, emulator, outFile, DEFAULT_LOAD.xmega65(outFile)), '-videostd', pal ? '0' : '1'];
+  } else {
+    // build() already validated the target against the same TARGETS set
+    // this function branches over, so this is unreachable.
+    process.stderr.write(`8bs run: no emulator wired up for target '${target}'\n`);
+    return 1;
+  }
+
+  process.stdout.write(`starting ${emulator}; close the emulator window to finish.\n`);
+  const { spawn } = await import('node:child_process');
+  return new Promise((resolvePromise) => {
+    const child = spawn(emulator, emulatorArgs, { stdio: 'inherit' });
+    child.on('error', () => {
+      process.stderr.write(`8bs run: cannot start ${emulator}. Run '8bs doctor' — docs/setup/index.md\n`);
+      resolvePromise(1);
+    });
+    child.on('close', (code) => resolvePromise(code === 0 ? 0 : 0));
+  });
+}