@8bitscript/cli 0.1.0

package/src/setup/rom.mjs

@@ -0,0 +1,188 @@
+// MEGA65 ROM handling: validating the legally-obtained C65 base ROM and the
+// official 920413 patch's own byte format, and deciding how the canonical
+// ROM should relate to Xemu's per-user data directory — all pure/testable,
+// no filesystem or network access. The one filesystem-touching helper at the
+// bottom (`inspectXemuRomLink`) is a thin real-fs wrapper around the pure
+// `classifyXemuRomLink` below it, kept here so doctor.mjs and setup/mega65.mjs
+// share one implementation of "is this symlink already correct".
+//
+// 8BitScript never bundles or downloads the ROM itself — see docs/setup/
+// mega65.md. What lives here only checks a ROM the *user* already has.
+import { createHash } from 'node:crypto';
+import {
+  lstat as fsLstat, readlink as fsReadlink, readFile as fsReadFile,
+  mkdir as fsMkdir, symlink as fsSymlink, unlink as fsUnlink,
+} from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+
+// The free C65 910828 ROM from Cloanto's "C64 Forever Free Express Edition",
+// which the official MEGA65 920413 patch is diffed against. Confirmed size
+// and hash from a working install (see the setup brief this module
+// implements) — this is the gate that stops a wrong/corrupt base ROM from
+// silently producing a bad MEGA65.ROM.
+export const C65_BASE_ROM = {
+  filename: 'c-65-19910828.rom',
+  size: 131072,
+  sha256: '0c4a00b45b65ca553b8a9f38cae83fe5f7dca7e809c24c0051ae40956640509d',
+};
+
+// The official MEGA65 920413 ROM release. `patchUrl` carries a suffix
+// (`_Sn7YEw`) that looks like a content hash or random token MEGA65's file
+// host generated for this specific upload — nothing says it is stable across
+// future releases or re-uploads of this same release, so treat it as a
+// best-effort default, not a permanent API. `romSha256` is the value that
+// actually matters: it's checked against the *generated* MEGA65.ROM, which
+// stays correct even if this URL goes stale (setup's --rom-patch flag is the
+// escape hatch for that case — see setup/mega65.mjs).
+export const MEGA65_ROM_920413 = {
+  release: '920413',
+  patchUrl: 'https://files.mega65.org/files/other/920413_Sn7YEw.zip',
+  rdfEntryName: '920413.rdf',
+  romSize: 131072,
+  romSha256: 'af3c447f791a2fdc48cb21e1bd3fab015e32641228d9d30d21259b9e878c6fa0',
+};
+
+export function sha256Hex(buffer) {
+  return createHash('sha256').update(buffer).digest('hex');
+}
+
+/** Check a ROM (or ROM-shaped) buffer against a known {size, sha256}. */
+export function validateRomBuffer(buffer, expected) {
+  const size = buffer.length;
+  const sha256 = sha256Hex(buffer);
+  return {
+    size,
+    sha256,
+    sizeOk: size === expected.size,
+    hashOk: sha256 === expected.sha256,
+    ok: size === expected.size && sha256 === expected.sha256,
+  };
+}
+
+// ---- RDF (romdiff patch) header ---------------------------------------
+//
+// Confirmed directly against the real 920413.rdf from
+// https://files.mega65.org/files/other/920413_Sn7YEw.zip, and against
+// romdiff's own source (MEGA65/mega65-tools, src/tools/romdiff.c): a fixed
+// 256-byte header before the diff payload —
+//   offset 0x00, 32 bytes: magic, "MEGA65ROMPATCH01.00", NUL-padded
+//   offset 0x20, 64 bytes: reference (base) ROM filename, NUL-padded
+//   offset 0x60, 160 bytes: output ROM filename, NUL-padded
+// romdiff itself only checks the first 16 bytes ("MEGA65ROMPATCH01") and
+// reads the reference filename as a NUL-terminated C string at offset 32 —
+// this parses the same way rather than assuming this release's exact
+// filenames, per the brief.
+const RDF_MAGIC = 'MEGA65ROMPATCH01';
+const RDF_HEADER_SIZE = 256;
+const RDF_FIELDS = [
+  ['magic', 0, 32],
+  ['referenceFilename', 32, 64],
+  ['outputFilename', 96, 160],
+];
+
+function readNulTerminated(buffer, start, maxLen) {
+  const field = buffer.subarray(start, start + maxLen);
+  const nul = field.indexOf(0);
+  return (nul === -1 ? field : field.subarray(0, nul)).toString('ascii');
+}
+
+/**
+ * Parse an .rdf patch file's header. Returns null if `buffer` is too short
+ * or does not carry the expected magic — the caller should treat that as
+ * "not a MEGA65 ROM diff file", the same thing romdiff itself refuses.
+ */
+export function parseRdfHeader(buffer) {
+  if (buffer.length < RDF_HEADER_SIZE) return null;
+  const magic = readNulTerminated(buffer, 0, 32);
+  if (!magic.startsWith(RDF_MAGIC)) return null;
+  const fields = {};
+  for (const [name, start, len] of RDF_FIELDS) {
+    fields[name] = readNulTerminated(buffer, start, len);
+  }
+  return fields;
+}
+
+// ---- canonical ROM vs. Xemu's per-user ROM -----------------------------
+
+/**
+ * How does the path Xemu reads its ROM from (~/.xemu-lgb/MEGA65.ROM) relate
+ * to the canonical install (/opt/mega65/MEGA65.ROM)? Pure classifier over
+ * pre-gathered facts, so it never has to be exercised against a real
+ * filesystem to test the branch matrix the "never overwrite an unrelated
+ * ROM without confirmation" requirement hinges on.
+ *
+ *   'absent'     — nothing at the link path yet; safe to create the symlink
+ *   'linked'     — already a symlink to the canonical path; nothing to do
+ *   'migratable' — a regular file that *is* a valid copy of the expected
+ *                  ROM; safe to offer replacing it with the symlink
+ *   'foreign'    — a symlink elsewhere, or a regular file that doesn't
+ *                  match the expected ROM; never touch without asking
+ */
+export function classifyXemuRomLink({ exists, isSymlink, resolvedTarget, canonicalPath, isValidRom }) {
+  if (!exists) return 'absent';
+  if (isSymlink) return resolvedTarget === canonicalPath ? 'linked' : 'foreign';
+  return isValidRom ? 'migratable' : 'foreign';
+}
+
+/**
+ * Real-filesystem version of the above: gathers the facts `classifyXemuRomLink`
+ * needs from `linkPath` and `canonicalPath`, then classifies them. Kept
+ * separate from the pure classifier so doctor.mjs and setup/mega65.mjs can
+ * both call this one thing instead of duplicating the fs plumbing, while
+ * still being able to unit-test the decision itself without a filesystem.
+ * `fs` overrides (`lstatFn`/`readlinkFn`/`readFileFn`) let both callers fake
+ * the filesystem entirely for `8bs setup mega65`'s own unit tests — real
+ * `node:fs/promises` functions by default.
+ */
+export async function inspectXemuRomLink(linkPath, canonicalPath, expected = MEGA65_ROM_920413, {
+  lstatFn = fsLstat, readlinkFn = fsReadlink, readFileFn = fsReadFile,
+} = {}) {
+  let exists = false;
+  let isSymlink = false;
+  let resolvedTarget = null;
+  let isValidRom = false;
+  try {
+    const lstat = await lstatFn(linkPath);
+    exists = true;
+    isSymlink = lstat.isSymbolicLink();
+    if (isSymlink) {
+      const target = await readlinkFn(linkPath);
+      // A relative symlink target resolves against the *directory containing
+      // the link*, not the link path itself.
+      resolvedTarget = target.startsWith('/') ? target : resolve(dirname(linkPath), target);
+    } else if (lstat.isFile()) {
+      const { ok } = validateRomBuffer(await readFileFn(linkPath), { size: expected.romSize, sha256: expected.romSha256 });
+      isValidRom = ok;
+    }
+  } catch {
+    exists = false;
+  }
+  const state = classifyXemuRomLink({ exists, isSymlink, resolvedTarget, canonicalPath, isValidRom });
+  return { state, exists, isSymlink, resolvedTarget, isValidRom };
+}
+
+/**
+ * Create or repair the Xemu-local ROM link, based on what `inspectXemuRomLink`
+ * found. Never touches anything but `linkPath` itself, and never overwrites
+ * a 'foreign' file (an unrelated symlink, or a regular file that isn't a
+ * valid copy of the expected ROM) — that always comes back as
+ * 'skipped-foreign' with no write performed, regardless of `allowMigrate`.
+ * A 'migratable' regular file (a valid ROM already sitting at the link path,
+ * predating the canonical install) is only replaced with the symlink when
+ * the caller passes `allowMigrate: true` — i.e. after asking the user.
+ */
+export async function ensureXemuRomLink(linkPath, canonicalPath, {
+  allowMigrate = false, expected = MEGA65_ROM_920413,
+  mkdir = fsMkdir, symlink = fsSymlink, unlink = fsUnlink,
+  lstatFn, readlinkFn, readFileFn,
+  inspect = (lp, cp, exp) => inspectXemuRomLink(lp, cp, exp, { lstatFn, readlinkFn, readFileFn }),
+} = {}) {
+  const inspection = await inspect(linkPath, canonicalPath, expected);
+  if (inspection.state === 'linked') return { action: 'none', ...inspection };
+  if (inspection.state === 'foreign') return { action: 'skipped-foreign', ...inspection };
+  if (inspection.state === 'migratable' && !allowMigrate) return { action: 'skipped-migratable', ...inspection };
+  await mkdir(dirname(linkPath), { recursive: true });
+  if (inspection.state === 'migratable') await unlink(linkPath);
+  await symlink(canonicalPath, linkPath);
+  return { action: inspection.state === 'migratable' ? 'migrated' : 'linked', ...inspection };
+}

package/src/setup/source.mjs

@@ -0,0 +1,60 @@
+// Source checkout and build steps shared by every source-built target
+// (`8bs setup mega65` builds Xemu, `8bs setup cx16` builds x16-emulator
+// and x16-rom). Every process/filesystem boundary is injected — an `exec`
+// matching exec.mjs's execInherit, plus `exists`/`mkdirFn` — so the
+// per-target modules stay thin and unit tests never clone or compile.
+import { access, mkdir } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+
+import { execInherit } from './exec.mjs';
+
+export async function pathExists(p) {
+  try {
+    await access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Clone `repo` into `sourceDir` the first time; fast-forward it on every
+ * later run. Never re-clones an existing checkout — a build directory that
+ * already exists there is exactly what makes a re-run cheap (an incremental
+ * `make` instead of a from-scratch build). Runs as the normal user; there is
+ * no sudo anywhere in this module.
+ */
+export async function syncRepository({
+  sourceDir, repo, exec = execInherit, exists = pathExists, mkdirFn = mkdir,
+}) {
+  if (await exists(join(sourceDir, '.git'))) {
+    const pull = await exec('git', ['-C', sourceDir, 'pull', '--ff-only']);
+    if (pull.code !== 0) return { ok: false, step: 'git pull', code: pull.code };
+    return { ok: true, action: 'updated' };
+  }
+  await mkdirFn(dirname(sourceDir), { recursive: true });
+  const clone = await exec('git', ['clone', repo, sourceDir]);
+  if (clone.code !== 0) return { ok: false, step: 'git clone', code: clone.code };
+  return { ok: true, action: 'cloned' };
+}
+
+/**
+ * Run one build command in `cwd` and confirm every path in `artifacts` came
+ * out of it. Warnings on stderr are never a failure — every source build
+ * this project does (Xemu under GCC, x16-emulator under AppleClang with its
+ * "reducing alignment of section" linker warnings, x16-rom's pages of
+ * ca65/ld65 notices) emits some on a perfectly good build. Only a non-zero
+ * exit, or a missing artifact afterward, is.
+ */
+export async function runBuild({
+  cwd, command = 'make', args = [], artifacts = [], exec = execInherit, exists = pathExists,
+}) {
+  const build = await exec(command, args, { cwd });
+  if (build.code !== 0) return { ok: false, step: command, code: build.code };
+  for (const artifact of artifacts) {
+    if (!(await exists(artifact))) {
+      return { ok: false, step: command, code: build.code, missingArtifact: artifact };
+    }
+  }
+  return { ok: true };
+}

package/src/setup/xemu.mjs

@@ -0,0 +1,107 @@
+// Building and installing xmega65 (Xemu's MEGA65 core) from source. The AUR
+// `xmega65-git` package is deliberately not used anywhere in this
+// project — see doctor.mjs's INSTALLERS.xmega65 comment — so this is the
+// only path `8bs setup mega65` has to a working emulator.
+import { lstat, mkdir, readlink, symlink } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+
+import { execInherit } from './exec.mjs';
+import { syncRepository, runBuild, pathExists } from './source.mjs';
+import {
+  xemuSourceDir, XEMU_INSTALL_DIR, XMEGA65_INSTALL_PATH, XMEGA65_SYMLINK_PATH,
+  xemuUserDataDir, xemuMega65RealDataDir,
+} from './paths.mjs';
+
+const XEMU_REPO = 'https://github.com/lgblgblgb/xemu.git';
+
+/**
+ * Clone-or-update lgblgblgb/xemu, then `make` only `targets/mega65` — this
+ * project has no use for Xemu's other machine cores. Harmless compiler
+ * warnings (confirmed against GCC 16 / sdl2-compat 2.32.70 / GTK3 on current
+ * Arch, and against Apple clang 21 / SDL 2.32.72 on Apple Silicon macOS —
+ * "experimental memory data pointers", "no _mm_malloc() on ARM", unused
+ * variables) are not a failure; only a non-zero `make` exit or a missing
+ * resulting binary is.
+ */
+export async function buildXemuMega65({
+  sourceDir = xemuSourceDir(), repo = XEMU_REPO, exec = execInherit, exists = pathExists, mkdirFn = mkdir,
+} = {}) {
+  const sync = await syncRepository({ sourceDir, repo, exec, exists, mkdirFn });
+  if (!sync.ok) return sync;
+  const binaryPath = join(sourceDir, 'build', 'bin', 'xmega65.native');
+  const build = await runBuild({ cwd: join(sourceDir, 'targets', 'mega65'), artifacts: [binaryPath], exec, exists });
+  if (!build.ok) return { ...build, binaryPath };
+  return { ok: true, binaryPath };
+}
+
+/**
+ * Install the built binary system-wide: `/opt/xemu/xmega65` (never named
+ * `xmega65.native` — the brief is explicit). Putting it on `PATH` is a
+ * separate step — see xmega65LauncherSpec() and setup/launcher.mjs — so a
+ * foreign `/usr/local/bin/xmega65` is never silently overwritten here.
+ */
+export async function installXemu(binaryPath, { sudoExec, installDir = XEMU_INSTALL_DIR, installPath = XMEGA65_INSTALL_PATH } = {}) {
+  const mkdirResult = await sudoExec('mkdir', ['-p', installDir]);
+  if (mkdirResult.code !== 0) return { ok: false, step: 'mkdir', code: mkdirResult.code };
+  const installResult = await sudoExec('install', ['-m755', binaryPath, installPath]);
+  if (installResult.code !== 0) return { ok: false, step: 'install', code: installResult.code };
+  return { ok: true, installPath };
+}
+
+/**
+ * Unlike Commander X16's x16emu, a plain `/usr/local/bin/xmega65 ->
+ * /opt/xemu/xmega65` symlink works correctly on macOS too — confirmed on a
+ * real Apple Silicon install: Xemu resolves its own data directory from
+ * `$HOME`, never from the path it was invoked through, so there's no
+ * platform split here and no wrapper script.
+ */
+export function xmega65LauncherSpec() {
+  return { path: XMEGA65_SYMLINK_PATH, target: XMEGA65_INSTALL_PATH, execLine: null, kind: 'symlink' };
+}
+
+/**
+ * What's at Xemu's `~/.xemu-lgb` compatibility path right now: `'missing'`
+ * (nothing there yet), `'symlink'` (resolved to its real target — Xemu's
+ * own first-run behaviour, or a prior run of this function), or `'other'`
+ * (a real directory, or anything else Xemu itself put there — left alone
+ * either way).
+ */
+export async function inspectXemuDataDir(linkPath, { lstatFn = lstat, readlinkFn = readlink } = {}) {
+  let stats;
+  try {
+    stats = await lstatFn(linkPath);
+  } catch {
+    return { state: 'missing' };
+  }
+  if (stats.isSymbolicLink()) {
+    const target = await readlinkFn(linkPath);
+    const resolved = target.startsWith('/') ? target : resolve(dirname(linkPath), target);
+    return { state: 'symlink', target: resolved };
+  }
+  return { state: 'other' };
+}
+
+/**
+ * Xemu creates `~/.xemu-lgb` itself, as a compatibility symlink into its
+ * real per-platform data directory (`~/Library/Application Support/
+ * xemu-lgb/mega65` on macOS, `~/.local/share/xemu-lgb/mega65` on Linux —
+ * both confirmed on real first launches), the first time it runs. Setup
+ * never launches the emulator just to get that layout, so if nothing is
+ * there yet it creates the identical layout itself: the real directory,
+ * then the symlink — so the ROM link step right after this has somewhere
+ * correct to land. Anything already at `linkPath` — any symlink, or a real
+ * directory — is Xemu's own (or a prior run of this same function) and is
+ * left completely untouched, per the brief's "never overwrite an existing
+ * ~/.xemu-lgb that points somewhere else" — extended here to "never
+ * overwrite it at all" once it exists.
+ */
+export async function ensureXemuDataDir({
+  platform = process.platform, linkPath = xemuUserDataDir(), realDir = xemuMega65RealDataDir(platform),
+  mkdirFn = mkdir, symlinkFn = symlink, inspect = inspectXemuDataDir,
+} = {}) {
+  const inspection = await inspect(linkPath);
+  if (inspection.state !== 'missing') return { ok: true, action: 'unchanged', ...inspection };
+  await mkdirFn(realDir, { recursive: true });
+  await symlinkFn(realDir, linkPath);
+  return { ok: true, action: 'created', realDir };
+}

package/src/setup/zip.mjs

@@ -0,0 +1,75 @@
+// A minimal ZIP reader, just enough to pull one named entry out of the
+// official MEGA65 ROM-patch archive (or a C64 Forever MSI's own zip-shaped
+// internals, if ever needed) without adding a zip library dependency this
+// project doesn't otherwise need. Supports the two compression methods a
+// real-world zip actually uses: 0 (stored) and 8 (deflate, via Node's own
+// zlib). Confirmed directly against the real 920413_Sn7YEw.zip from
+// files.mega65.org, whose three entries are all stored (method 0) — deflate
+// support is here so a future re-upload that does compress them still works.
+import { inflateRawSync } from 'node:zlib';
+
+const EOCD_SIGNATURE = 0x06054b50;
+const CENTRAL_DIR_SIGNATURE = 0x02014b50;
+const LOCAL_HEADER_SIGNATURE = 0x04034b50;
+
+/** Find the End Of Central Directory record by scanning backward from the
+ * end of the file — it can be followed by a variable-length comment, so its
+ * offset isn't fixed. */
+function findEndOfCentralDirectory(buffer) {
+  const maxCommentLength = 65535;
+  const searchStart = Math.max(0, buffer.length - 22 - maxCommentLength);
+  for (let offset = buffer.length - 22; offset >= searchStart; offset -= 1) {
+    if (buffer.readUInt32LE(offset) === EOCD_SIGNATURE) return offset;
+  }
+  return -1;
+}
+
+/** List every entry in a ZIP archive: { name, method, compressedSize,
+ * uncompressedSize, localHeaderOffset }. Throws if `buffer` isn't a ZIP
+ * this reader understands. */
+export function readZipEntries(buffer) {
+  const eocd = findEndOfCentralDirectory(buffer);
+  if (eocd === -1) throw new Error('not a ZIP file (no end-of-central-directory record found)');
+
+  const entryCount = buffer.readUInt16LE(eocd + 10);
+  const centralDirOffset = buffer.readUInt32LE(eocd + 16);
+
+  const entries = [];
+  let offset = centralDirOffset;
+  for (let i = 0; i < entryCount; i += 1) {
+    if (buffer.readUInt32LE(offset) !== CENTRAL_DIR_SIGNATURE) {
+      throw new Error(`ZIP central directory entry ${i} has a bad signature`);
+    }
+    const method = buffer.readUInt16LE(offset + 10);
+    const compressedSize = buffer.readUInt32LE(offset + 20);
+    const uncompressedSize = buffer.readUInt32LE(offset + 24);
+    const nameLength = buffer.readUInt16LE(offset + 28);
+    const extraLength = buffer.readUInt16LE(offset + 30);
+    const commentLength = buffer.readUInt16LE(offset + 32);
+    const localHeaderOffset = buffer.readUInt32LE(offset + 42);
+    const name = buffer.toString('utf8', offset + 46, offset + 46 + nameLength);
+    entries.push({ name, method, compressedSize, uncompressedSize, localHeaderOffset });
+    offset += 46 + nameLength + extraLength + commentLength;
+  }
+  return entries;
+}
+
+/** Decompressed bytes for one entry from `readZipEntries`. */
+export function extractZipEntry(buffer, entry) {
+  const localNameLength = buffer.readUInt16LE(entry.localHeaderOffset + 26);
+  const localExtraLength = buffer.readUInt16LE(entry.localHeaderOffset + 28);
+  const dataOffset = entry.localHeaderOffset + 30 + localNameLength + localExtraLength;
+  const compressed = buffer.subarray(dataOffset, dataOffset + entry.compressedSize);
+  if (entry.method === 0) return Buffer.from(compressed);
+  if (entry.method === 8) return inflateRawSync(compressed);
+  throw new Error(`ZIP entry '${entry.name}' uses unsupported compression method ${entry.method}`);
+}
+
+/** Find an entry by exact path, or by basename if no exact match — the
+ * official archive nests entries under a release-number directory
+ * (`920413/920413.rdf`) that this project should not assume is permanent. */
+export function findZipEntry(entries, name) {
+  const exact = entries.find((e) => e.name === name);
+  if (exact) return exact;
+  return entries.find((e) => e.name.split('/').pop() === name) ?? null;
+}

package/src/setup.mjs

@@ -0,0 +1,56 @@
+// `8bs setup <target>` — install/configure what a target needs beyond what
+// `8bs doctor` can offer as a single package-manager command: mega65 (Xemu
+// built from source, plus the legally-obtained ROM pipeline
+// docs/setup/mega65.md documents) and cx16 (x16emu and a matching ROM built
+// from upstream source, docs/setup/cx16.md). This file stays a thin
+// dispatcher; the shared machinery lives in setup/{deps,host,source,
+// install,launcher}.mjs so the next source-built target follows the same
+// shape.
+const TARGETS = {
+  mega65: () => import('./setup/mega65.mjs').then((m) => m.setupMega65),
+  cx16: () => import('./setup/cx16.mjs').then((m) => m.setupCx16),
+};
+
+const USAGE = 'Usage: 8bs setup <mega65|cx16> [--rom <path>] [--c64-forever <msi>] [--rom-patch <zip>] [--repair] [--update]\n';
+
+function parseArgs(args) {
+  const options = {};
+  const positionals = [];
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === '--rom') {
+      options.romPath = args[i + 1];
+      i += 1;
+    } else if (arg === '--c64-forever') {
+      options.c64ForeverPath = args[i + 1];
+      i += 1;
+    } else if (arg === '--rom-patch') {
+      options.romPatchPath = args[i + 1];
+      i += 1;
+    } else if (arg === '--repair') {
+      options.repair = true;
+    } else if (arg === '--update') {
+      options.update = true;
+    } else if (!arg.startsWith('-')) {
+      positionals.push(arg);
+    }
+  }
+  return { target: positionals[0], options };
+}
+
+/** @returns {Promise<number>} process exit code */
+export async function setup(args) {
+  const { target, options } = parseArgs(args);
+  if (!target) {
+    process.stderr.write(USAGE);
+    return 2;
+  }
+  const load = TARGETS[target];
+  if (!load) {
+    process.stderr.write(`8bs setup: no setup available for '${target}'. Run '8bs doctor' for what's missing — docs/setup/.\n`);
+    return 2;
+  }
+  const run = await load();
+  const result = await run(options);
+  return result.ok ? 0 : 1;
+}

package/src/targets.mjs

@@ -0,0 +1,158 @@
+// `8bs targets [--json]` — every machine the toolchain builds for, and the
+// hardware each can be fitted with: the catalog every machine package
+// declares (packages/cli/src/hardware.mjs), plus the profiles the project
+// in the current directory composes in its 8bs.config.ts, and the whole
+// machines that config has been set up for in its `systems` block. The
+// editor reads the JSON form to build its System and Hardware controls, so
+// a new machine or option in a package — or a new system in a project — is
+// a new row there with nothing to update by hand.
+import { FACTS, MACHINES } from '@8bitscript/compiler';
+
+import { loadConfig } from './config.mjs';
+import {
+  REGION_MACHINES, loadCatalog, projectHardware, projectProfiles, projectRequires, projectSystems,
+  stockFacts,
+} from './hardware.mjs';
+import { VICE_EMULATOR } from './run.mjs';
+
+const EMULATOR = {
+  ...VICE_EMULATOR, atari8: 'atari800', nes: 'fceux', cx16: 'x16emu', mega65: 'xmega65', web: 'the browser',
+};
+const TITLE = {
+  vic20: 'Commodore VIC-20', c64: 'Commodore 64', pet: 'Commodore PET', c128: 'Commodore 128',
+  atari8: 'Atari 8-bit', nes: 'Nintendo Entertainment System', cx16: 'Commander X16', mega65: 'MEGA65', web: 'Web',
+};
+
+/**
+ * One entry per target: what the editor's dropdowns and hardware panel
+ * are built from.
+ *
+ * @param {object|null} config the project's 8bs.config.ts, if any
+ */
+export function describeTargets(config) {
+  return MACHINES.map((id) => {
+    const catalog = loadCatalog(id);
+    const options = Object.fromEntries(Object.entries(catalog.options).map(([optionId, option]) => [optionId, {
+      label: option.label,
+      default: option.default,
+      // The package subpath whose probe finds this hardware on the machine
+      // at run time, when one probe finds every value of the option; a
+      // value may name its own instead (see below). Null when the choice
+      // is the build's (a PET model).
+      detect: option.detect ?? null,
+      values: Object.fromEntries(Object.entries(option.values).map(([value, entry]) => [value, {
+        label: entry.label,
+        affectsBuild: Boolean(entry.build),
+        // What finds *this* value at run time: its own probe, or the
+        // option's when one probe covers them all.
+        detect: entry.detect ?? option.detect ?? null,
+        tag: Object.hasOwn(entry, 'tag') ? entry.tag : (value === option.default ? null : value),
+        facts: entry.facts ?? {},
+      }])),
+    }]));
+    return {
+      id,
+      title: TITLE[id],
+      emulator: EMULATOR[id],
+      region: REGION_MACHINES.has(id),
+      options,
+      presets: catalog.presets,
+      profiles: projectProfiles(config, id),
+      // The project's own default values for this machine, under any profile.
+      hardware: projectHardware(config, id),
+      // The stock machine's sheet; a chosen value's `facts` change it, in
+      // option order, the way resolveHardware merges them.
+      facts: stockFacts(id),
+    };
+  });
+}
+
+/** The fact keys, typed and described, so the editor's sheet labels itself from one place. */
+export function describeFacts() {
+  return [...FACTS].map(([key, fact]) => ({ key, ...fact }));
+}
+
+/** One line per system a config declares, for the table form. */
+function printSystems(systems) {
+  if (systems.length === 0) return;
+  process.stdout.write('\nThis project is set up for:\n');
+  for (const system of systems) {
+    const parts = [
+      system.profile && `--profile ${system.profile}`,
+      Object.entries(system.hardware).length > 0
+        && `--hardware ${Object.entries(system.hardware).map(([k, v]) => `${k}=${v}`).join(',')}`,
+      system.region === 'pal' && '--pal',
+    ].filter(Boolean);
+    process.stdout.write(`  ${system.name.padEnd(24)} 8bs run ${system.target}${parts.length > 0 ? ` ${parts.join(' ')}` : ''}\n`);
+    for (const { key, need, have } of system.unmet ?? []) {
+      process.stdout.write(`  ${' '.repeat(24)} short: ${key} needs ${need === true ? 'it' : need}, has ${have === true ? 'it' : have}\n`);
+    }
+  }
+}
+
+/** What the program asks of any machine, for the table form. */
+function printRequires(requires) {
+  const entries = Object.entries(requires);
+  if (entries.length === 0) return;
+  process.stdout.write('\nThis program needs, of any machine:\n');
+  for (const [key, need] of entries) {
+    process.stdout.write(`  ${key.padEnd(24)} ${need === true ? 'yes' : `at least ${need}`}\n`);
+  }
+}
+
+/** @returns {Promise<number>} exit code */
+export async function targets(args) {
+  const config = await loadConfig(process.cwd(), '8bs targets');
+  const required = projectRequires(config);
+  const systems = projectSystems(config);
+  const described = describeTargets(config);
+  if (args.includes('--json')) {
+    // A `systems` block the config gets wrong costs the reader its
+    // systems and nothing else: the machines and their catalogs are the
+    // toolchain's and are still true. The editor reads this, and a whole
+    // hardware panel disappearing because of a typo three lines away
+    // would say nothing about what is wrong.
+    process.stdout.write(`${JSON.stringify({
+      targets: described,
+      systems: systems.ok ? systems.systems : [],
+      systemsError: systems.ok ? null : systems.error,
+      requires: required.ok ? required.requires : {},
+      requiresError: required.ok ? null : required.error,
+      facts: describeFacts(),
+    }, null, 2)}\n`);
+    return 0;
+  }
+  for (const result of [required, systems]) {
+    if (!result.ok) {
+      process.stderr.write(`8bs targets: ${result.error}\n`);
+      return 1;
+    }
+  }
+  for (const t of described) {
+    const presets = Object.keys(t.presets);
+    const profiles = Object.keys(t.profiles);
+    process.stdout.write(`${t.id.padEnd(8)} ${t.title} — ${t.emulator}${t.region ? ', --pal available' : ''}\n`);
+    for (const [optionId, option] of Object.entries(t.options)) {
+      const values = Object.entries(option.values)
+        .map(([value, entry]) => `${value}${value === option.default ? '*' : ''}${entry.affectsBuild ? ' (build)' : ''}`)
+        .join(', ');
+      process.stdout.write(`         --hardware ${optionId}=  ${option.label}: ${values}\n`);
+      const probes = new Map();
+      for (const [value, entry] of Object.entries(option.values)) {
+        if (!entry.detect || value === option.default) continue;
+        probes.set(entry.detect, [...(probes.get(entry.detect) ?? []), value]);
+      }
+      for (const [probe, found] of probes) {
+        process.stdout.write(`                            ${found.join(', ')} found at run time by ${probe}\n`);
+      }
+    }
+    if (presets.length > 0) process.stdout.write(`         --profile  presets: ${presets.join(', ')}\n`);
+    if (profiles.length > 0) process.stdout.write(`         --profile  this project: ${profiles.join(', ')}\n`);
+    const own = Object.entries(t.hardware).map(([k, v]) => `${k}=${v}`);
+    if (own.length > 0) process.stdout.write(`         this project's default: ${own.join(' ')}\n`);
+  }
+  printRequires(required.requires);
+  printSystems(systems.systems);
+  process.stdout.write('\n* the default; (build) changes the program, not only the emulator\n');
+  return 0;
+}