@8bitscript/cli 0.1.0

package/src/setup/exec.mjs

@@ -0,0 +1,110 @@
+// Process execution for `8bs setup`. Two shapes, both plain argv arrays
+// (never a shell string — see execCapture/execInherit below), plus a sudo
+// wrapper that is the *only* place elevated privileges are allowed to enter
+// this pipeline. Kept separate from doctor.mjs's own private `run()`: that
+// one buffers output for parsing a version string; a source build wants its
+// output streamed to the terminal live, and setup also needs a sudo path
+// doctor's checks never do.
+import { spawn } from 'node:child_process';
+
+/** Run a command, buffering stdout/stderr. For output setup needs to parse
+ * or validate (e.g. `pacman -Qi`) rather than show the user directly. */
+export function execCapture(command, args, { timeout = 30_000, cwd } = {}) {
+  return new Promise((resolvePromise) => {
+    let child;
+    try {
+      child = spawn(command, args, { stdio: ['ignore', 'pipe', 'pipe'], cwd });
+    } catch {
+      resolvePromise({ code: null, stdout: '', stderr: '', missing: true });
+      return;
+    }
+    let stdout = '';
+    let stderr = '';
+    const timer = timeout ? setTimeout(() => child.kill('SIGKILL'), timeout) : null;
+    child.stdout.on('data', (d) => { stdout += d; });
+    child.stderr.on('data', (d) => { stderr += d; });
+    child.on('error', () => {
+      if (timer) clearTimeout(timer);
+      resolvePromise({ code: null, stdout, stderr, missing: true });
+    });
+    child.on('close', (code) => {
+      if (timer) clearTimeout(timer);
+      resolvePromise({ code, stdout, stderr, missing: false });
+    });
+  });
+}
+
+/** Run a command with its stdio connected straight to this process — for a
+ * build (`make`), a clone (`git`), or an extraction (`msiextract`) whose
+ * live output the user should see, and whose exit code is the only thing
+ * that matters afterward. Never treats stderr output alone as failure: the
+ * brief is explicit that harmless compiler warnings are not a build error —
+ * only a non-zero exit code (or, separately, a missing resulting binary) is. */
+export function execInherit(command, args, { cwd } = {}) {
+  return new Promise((resolvePromise) => {
+    let child;
+    try {
+      child = spawn(command, args, { stdio: 'inherit', cwd });
+    } catch {
+      resolvePromise({ code: null, missing: true });
+      return;
+    }
+    child.on('error', () => resolvePromise({ code: null, missing: true }));
+    child.on('close', (code) => resolvePromise({ code, missing: false }));
+  });
+}
+
+// The only destinations any `8bs setup <target>` is allowed to write to as
+// root: one /opt/<tool> directory per source-built tool, plus /usr/local/bin
+// for the launchers that put them on PATH. Adding a target means adding its
+// /opt directory here — deliberately, in one place — rather than widening
+// the check.
+export const SUDO_ALLOWED_ROOTS = Object.freeze([
+  '/opt/xemu', '/opt/mega65', '/opt/commander-x16', '/usr/local/bin',
+]);
+
+/** Last non-flag argument — for `mkdir -p <dir>`, `install -m755 <src>
+ * <dst>`, and `ln -sf <target> <linkname>`, that's the one path each of
+ * these commands actually *writes* to (a copy/link source, like `install`'s
+ * <src>, is only ever read — it isn't a privilege-escalation target and
+ * legitimately lives outside the allowed roots, e.g. under the user's own
+ * ~/.cache build tree). */
+function writeTarget(args) {
+  const positionals = args.filter((a) => !a.startsWith('-'));
+  return positionals[positionals.length - 1];
+}
+
+/**
+ * Enforce the brief's sudo allowlist at the one place every elevated call in
+ * this pipeline goes through, rather than leaving it as a comment code
+ * review has to keep true by hand: `pacman` (package installation) is always
+ * allowed; `mkdir`/`install`/`ln` are allowed only when the path they write
+ * to falls under SUDO_ALLOWED_ROOTS; anything else is refused outright.
+ * Homebrew is deliberately *not* here: `brew` must never run as root (it
+ * refuses to), so setup runs it as the normal user through execInherit.
+ * Throws rather than silently skipping, since a caller reaching this with an
+ * unexpected command/target is a bug worth surfacing immediately.
+ */
+export function assertSudoAllowed(command, args) {
+  if (command === 'pacman') return;
+  if (command === 'mkdir' || command === 'install' || command === 'ln') {
+    const target = writeTarget(args);
+    const allowed = target && SUDO_ALLOWED_ROOTS.some((root) => target === root || target.startsWith(`${root}/`));
+    if (allowed) return;
+    throw new Error(
+      `refusing 'sudo ${command} ${args.join(' ')}' — '${target}' is outside the allowed `
+      + `sudo write targets (${SUDO_ALLOWED_ROOTS.join(', ')})`,
+    );
+  }
+  throw new Error(`refusing 'sudo ${command}' — not one of the sudo operations this setup pipeline allows`);
+}
+
+/** Run one command under sudo, as an explicit argv array — never a shell
+ * string, so a path or filename containing spaces or shell metacharacters
+ * can't be reinterpreted. `-n` (non-interactive) is deliberately not passed:
+ * a real sudo password prompt should work normally; this only removes the
+ * possibility of silently shelling out through an interpreter. */
+export function sudoRun(command, args, opts) {
+  assertSudoAllowed(command, args);
+  return execInherit('sudo', [command, ...args], opts);
+}

package/src/setup/host.mjs

@@ -0,0 +1,58 @@
+// Host-platform prerequisites for `8bs setup` that aren't packages: the
+// Apple Command Line Tools on macOS, and PATH inspection every launcher
+// install needs. Process boundaries are injected (an `exec` matching
+// exec.mjs's execCapture/execInherit) so unit tests never run them.
+import { existsSync } from 'node:fs';
+import { delimiter, join } from 'node:path';
+
+/** Is `name` an executable on PATH? Same logic as doctor.mjs's private
+ * onPath(); exported here so setup shares it rather than re-deriving it. */
+export function hasBinaryOnPath(name, env = process.env, platform = process.platform) {
+  const binary = platform === 'win32' ? `${name}.exe` : name;
+  return (env.PATH ?? '')
+    .split(delimiter)
+    .some((dir) => dir && existsSync(join(dir, binary)));
+}
+
+/** Is `dir` one of PATH's entries? `/usr/local/bin` is the tested launcher
+ * location on both macOS and Linux, but a minimal PATH (some CI images,
+ * some shells' non-login profiles) can omit it — in which case a launcher
+ * installed there is real but invisible, and setup should say so. */
+export function isDirOnPath(dir, env = process.env) {
+  return (env.PATH ?? '').split(delimiter).some((entry) => entry && entry.replace(/\/+$/, '') === dir);
+}
+
+/**
+ * `xcode-select -p` exits 0 (printing the active developer directory) only
+ * when the Command Line Tools — or a full Xcode — are installed; it exits
+ * non-zero with "unable to get active developer directory" otherwise.
+ * Checked before ever offering `xcode-select --install`, so a machine that
+ * already has them is never asked again (the install command is a GUI
+ * dialog, not something to re-trigger on every run).
+ */
+export async function hasXcodeCommandLineTools(exec) {
+  const r = await exec('xcode-select', ['-p']);
+  return !r.missing && r.code === 0;
+}
+
+/** Trigger Apple's Command Line Tools installer. This opens a macOS dialog
+ * and returns immediately — the download runs outside our process — so the
+ * caller has to tell the user to re-run setup once it finishes, rather than
+ * waiting on the exit code. */
+export function installXcodeCommandLineTools(exec) {
+  return exec('xcode-select', ['--install']);
+}
+
+/** Full path of the first `name` on PATH, or null — what `command -v`
+ * answers. The doctor reports this for x16emu so a reader sees *which*
+ * launcher is in play (`/usr/local/bin/x16emu`), and inspects that exact
+ * file for the macOS symlink trap. */
+export function resolveOnPath(name, env = process.env, platform = process.platform) {
+  const binary = platform === 'win32' ? `${name}.exe` : name;
+  for (const dir of (env.PATH ?? '').split(delimiter)) {
+    if (!dir) continue;
+    const candidate = join(dir, binary);
+    if (existsSync(candidate)) return candidate;
+  }
+  return null;
+}

package/src/setup/install.mjs

@@ -0,0 +1,47 @@
+// Privileged file installation into /opt/<tool> and /usr/local/bin — the
+// only place `8bs setup` writes as root, and always through exec.mjs's
+// sudoRun allowlist. Files are compared before they're copied, so a re-run
+// against an already-complete install never asks for a password just to
+// overwrite a byte-identical binary.
+import { readFile } from 'node:fs/promises';
+
+/** Byte-for-byte comparison of two files; `false` when either is unreadable
+ * (missing, or a directory), which callers treat as "needs installing". */
+export async function filesIdentical(a, b, read = readFile) {
+  try {
+    const [x, y] = await Promise.all([read(a), read(b)]);
+    return x.equals(y);
+  } catch {
+    return false;
+  }
+}
+
+/** `sudo mkdir -p <dir>` — idempotent, and refused by sudoRun's allowlist
+ * for any directory outside the roots exec.mjs names. */
+export async function ensureDirectory(dir, sudoExec) {
+  const r = await sudoExec('mkdir', ['-p', dir]);
+  if (r.code !== 0) return { ok: false, step: 'mkdir', code: r.code, path: dir };
+  return { ok: true };
+}
+
+/**
+ * `sudo install -m<mode> <src> <dst>` for each file that isn't already in
+ * place with identical contents. Returns which paths were actually written
+ * so the caller can report "installed" vs "already current" honestly.
+ * Stops at the first failed step — a half-installed layout is reported, not
+ * papered over by the steps after it.
+ */
+export async function installFiles(files, sudoExec, { identical = filesIdentical } = {}) {
+  const installed = [];
+  const unchanged = [];
+  for (const { src, dst, mode } of files) {
+    if (await identical(src, dst)) {
+      unchanged.push(dst);
+      continue;
+    }
+    const r = await sudoExec('install', [`-m${mode}`, src, dst]);
+    if (r.code !== 0) return { ok: false, step: 'install', code: r.code, path: dst, installed, unchanged };
+    installed.push(dst);
+  }
+  return { ok: true, installed, unchanged };
+}

package/src/setup/launcher.mjs

@@ -0,0 +1,112 @@
+// PATH launchers for source-built tools installed under /opt/<tool>: the
+// `/usr/local/bin/<name>` entry that makes `8bs run` (and the user) able to
+// type the bare command. Two kinds, chosen per tool *and per platform* by
+// the target's setup module — never assumed:
+//
+//   symlink  /usr/local/bin/<name> -> /opt/<tool>/<name>
+//   wrapper  a two-line /bin/sh script that exec's the real binary with
+//            explicit arguments
+//
+// The wrapper exists because of a real, tested macOS failure: x16emu
+// locates its default rom.bin relative to the path it was *invoked* through,
+// so a direct symlink in /usr/local/bin makes it look for
+// /usr/local/bin/rom.bin and die with "Cannot open /usr/local/bin/rom.bin!".
+// On Linux the same symlink resolves fine. See setup/cx16.mjs for the
+// per-platform choice, and inspectLauncher() below for how a launcher that
+// exists but wasn't installed by this project is recognised and left alone
+// until the user says otherwise.
+import { lstat, readlink, readFile, mkdir, writeFile } from 'node:fs/promises';
+import { join, basename } from 'node:path';
+
+export const MANAGED_MARKER = '# managed by 8bs setup — re-run `8bs setup <target>` rather than editing';
+
+/** The wrapper's exact contents. The `exec` line is the tested one:
+ * `exec /opt/commander-x16/x16emu -rom /opt/commander-x16/rom.bin "$@"` for
+ * x16emu on macOS — `"$@"` last so every argument `8bs run` passes (-prg,
+ * -run) still reaches the emulator after the explicit ROM. */
+export function wrapperScript(execLine) {
+  return `#!/bin/sh\n${MANAGED_MARKER}\n${execLine}\n`;
+}
+
+const defaultFs = { lstatFn: lstat, readlinkFn: readlink, readFileFn: readFile };
+
+/**
+ * What's at `path` right now, classified against what this project would
+ * put there (`target` for a symlink, `execLine` for a wrapper):
+ *
+ *   missing          nothing there
+ *   symlink          a symlink to exactly `target` — correct on Linux, the
+ *                    broken layout on macOS; the caller's strategy decides
+ *   wrapper          a script whose exec line is exactly `execLine`
+ *   stale-wrapper    a script this project wrote (carries MANAGED_MARKER)
+ *                    whose exec line is now out of date — safe to rewrite
+ *   foreign-symlink  a symlink somewhere else — not ours; ask before touching
+ *   foreign-file     a file (or directory) this project didn't write — same
+ *
+ * Pure classification: no writes, and every filesystem call is injectable.
+ */
+export async function inspectLauncher({ path, target, execLine }, fs = {}) {
+  const { lstatFn, readlinkFn, readFileFn } = { ...defaultFs, ...fs };
+  let stats;
+  try {
+    stats = await lstatFn(path);
+  } catch {
+    return { state: 'missing', path };
+  }
+  if (stats.isSymbolicLink()) {
+    const linkTarget = await readlinkFn(path);
+    return { state: linkTarget === target ? 'symlink' : 'foreign-symlink', path, target: linkTarget };
+  }
+  if (!stats.isFile()) return { state: 'foreign-file', path };
+  let content;
+  try {
+    content = String(await readFileFn(path));
+  } catch {
+    return { state: 'foreign-file', path };
+  }
+  const lines = content.split('\n').map((l) => l.trim());
+  if (execLine && lines.includes(execLine.trim())) return { state: 'wrapper', path, content };
+  if (content.includes(MANAGED_MARKER)) return { state: 'stale-wrapper', path, content };
+  return { state: 'foreign-file', path, content };
+}
+
+/**
+ * Make `path` the launcher `kind` ('symlink' | 'wrapper') for `target`.
+ * Idempotent: an already-correct launcher is left untouched with no sudo
+ * call at all. Anything this project put there (the other kind, or a stale
+ * wrapper) is replaced without asking — that's the repair path for the old
+ * macOS symlink layout. Anything foreign is only replaced when
+ * `confirmReplace(inspection)` says so; otherwise it's reported and left.
+ *
+ * Both writes go through `sudoExec` (and so exec.mjs's allowlist): `ln -sf`
+ * for a symlink, and `install -m755` of a wrapper staged in `workDir` as
+ * the normal user. Both replace a symlink or regular file already at the
+ * path — BSD and GNU `install` unlink the destination first, and `ln -f`
+ * does by definition — so no separate `rm` runs as root.
+ */
+export async function ensureLauncher({
+  path, kind, target, execLine, sudoExec, workDir, confirmReplace = async () => false,
+}, fs = {}) {
+  const { mkdirFn = mkdir, writeFileFn = writeFile } = fs;
+  const inspection = await inspectLauncher({ path, target, execLine }, fs);
+  const correct = kind === 'symlink' ? 'symlink' : 'wrapper';
+  if (inspection.state === correct) return { ok: true, action: 'unchanged', inspection };
+
+  const foreign = inspection.state === 'foreign-symlink' || inspection.state === 'foreign-file';
+  if (foreign && !(await confirmReplace(inspection))) {
+    return { ok: false, action: 'skipped-foreign', inspection };
+  }
+  const action = inspection.state === 'missing' ? 'created' : foreign ? 'replaced' : 'repaired';
+
+  if (kind === 'symlink') {
+    const r = await sudoExec('ln', ['-sf', target, path]);
+    if (r.code !== 0) return { ok: false, action: 'failed', step: 'ln', code: r.code, inspection };
+    return { ok: true, action, inspection };
+  }
+  await mkdirFn(workDir, { recursive: true });
+  const staged = join(workDir, `${basename(path)}.launcher`);
+  await writeFileFn(staged, wrapperScript(execLine), { mode: 0o755 });
+  const r = await sudoExec('install', ['-m755', staged, path]);
+  if (r.code !== 0) return { ok: false, action: 'failed', step: 'install', code: r.code, inspection };
+  return { ok: true, action, inspection };
+}

package/src/setup/mega65-rom.mjs

@@ -0,0 +1,165 @@
+// Building MEGA65.ROM from a user-supplied, legally obtained C65 base ROM
+// plus the official 920413 patch — the pipeline docs/setup/mega65.md
+// documents in prose. Every step here is a thin, mockable wrapper around one
+// piece of I/O (a download, an extraction, a build, a filesystem write), so
+// setup/mega65.mjs can drive them under real conditions while tests drive
+// them under fakes. Nothing in this file ever bundles, mirrors, or commits
+// ROM bytes — it only ever operates on files the user already has, or the
+// freely-redistributable .rdf patch (a diff, not ROM content) from MEGA65's
+// own file host.
+import {
+  mkdir, readFile, cp, rm, access,
+} from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+
+import { execInherit, execCapture } from './exec.mjs';
+import { readZipEntries, extractZipEntry, findZipEntry } from './zip.mjs';
+import {
+  C65_BASE_ROM, MEGA65_ROM_920413, validateRomBuffer, parseRdfHeader,
+} from './rom.mjs';
+import { mega65ToolsSourceDir } from './paths.mjs';
+
+/** Recursively find a file by exact basename under `rootDir`. Node's own
+ * recursive readdir, rather than shelling out to `find` — no risk of an
+ * untrusted path (an MSI's own internal names) reaching a shell. */
+export async function findByBasename(rootDir, basename, readdirFn) {
+  const { readdir } = await import('node:fs/promises');
+  const list = readdirFn ?? readdir;
+  const entries = await list(rootDir, { recursive: true, withFileTypes: true });
+  const match = entries.find((e) => e.isFile() && e.name === basename);
+  if (!match) return null;
+  const parent = match.parentPath ?? match.path;
+  return join(parent, match.name);
+}
+
+/** `msiextract -C <destDir> <msiPath>` — always as the normal user; never
+ * under sudo (the brief is explicit: msiextract never runs elevated). */
+export function extractC64ForeverMsi(msiPath, destDir, exec = execInherit) {
+  return exec('msiextract', ['-C', destDir, msiPath]);
+}
+
+/** Locate and validate the C65 910828 base ROM inside an extracted C64
+ * Forever tree. Returns `{ path, buffer, validation }` or null if the file
+ * isn't found anywhere under `extractedDir`. Validation failure is not
+ * thrown — the caller decides how to report a wrong/corrupt base ROM, per
+ * the brief's "stop and explain" requirement. */
+export async function locateC65BaseRom(extractedDir, { find = findByBasename, read = readFile } = {}) {
+  const path = await find(extractedDir, C65_BASE_ROM.filename);
+  if (!path) return null;
+  const buffer = await read(path);
+  return { path, buffer, validation: validateRomBuffer(buffer, C65_BASE_ROM) };
+}
+
+/**
+ * Get the 920413 .rdf patch's bytes, either from a local zip the user
+ * already downloaded (`localZipPath` — the escape hatch for the case the
+ * user flagged: `patchUrl`'s hashed-looking suffix may not be stable) or by
+ * downloading `MEGA65_ROM_920413.patchUrl` fresh. Either way the zip is read
+ * with the pure zip.mjs reader, never shelled out to `unzip`.
+ */
+export async function fetchRomPatch(
+  { localZipPath, fetchImpl = fetch, read = readFile } = {},
+) {
+  const zipBytes = localZipPath
+    ? Buffer.from(await read(localZipPath))
+    : await downloadZip(fetchImpl, MEGA65_ROM_920413.patchUrl);
+
+  const entries = readZipEntries(zipBytes);
+  const rdfEntry = findZipEntry(entries, MEGA65_ROM_920413.rdfEntryName);
+  if (!rdfEntry) {
+    throw new Error(
+      `the ROM patch archive did not contain ${MEGA65_ROM_920413.rdfEntryName} — `
+      + 'it may be a different release than expected',
+    );
+  }
+  const rdfBytes = extractZipEntry(zipBytes, rdfEntry);
+  const header = parseRdfHeader(rdfBytes);
+  if (!header) {
+    throw new Error(`${MEGA65_ROM_920413.rdfEntryName} does not look like a MEGA65 ROM diff file`);
+  }
+  return { rdfBytes, header };
+}
+
+async function downloadZip(fetchImpl, url) {
+  let response;
+  try {
+    response = await fetchImpl(url);
+  } catch (cause) {
+    throw new Error(
+      `could not download the MEGA65 ROM patch from ${url} — `
+      + `the download URL may have changed since this was written; pass --rom-patch <zip> `
+      + `with a copy downloaded by hand from https://files.mega65.org/`,
+      { cause },
+    );
+  }
+  if (!response.ok) {
+    throw new Error(
+      `downloading the MEGA65 ROM patch from ${url} failed (HTTP ${response.status}) — `
+      + `the download URL may have changed since this was written; pass --rom-patch <zip> `
+      + `with a copy downloaded by hand from https://files.mega65.org/`,
+    );
+  }
+  return Buffer.from(await response.arrayBuffer());
+}
+
+/** Clone-or-update MEGA65/mega65-tools into the setup source cache, and
+ * build only `bin/romdiff` — never `make all`, which the brief confirms
+ * fails under GCC 16 in the bundled cbmconvert project (a `false` enum
+ * identifier colliding with the C23 `false` keyword) and which this project
+ * doesn't need anyway. `which: no acme` warnings from this build are
+ * upstream noise and are not treated as failure — only a non-zero `make`
+ * exit or a missing resulting binary is. */
+export async function buildRomdiff({
+  sourceDir = mega65ToolsSourceDir(),
+  repo = 'https://github.com/MEGA65/mega65-tools.git',
+  exec = execInherit,
+  exists = async (p) => { try { await access(p); return true; } catch { return false; } },
+  mkdirFn = mkdir,
+} = {}) {
+  const gitDir = join(sourceDir, '.git');
+  if (await exists(gitDir)) {
+    const pull = await exec('git', ['-C', sourceDir, 'pull', '--ff-only']);
+    if (pull.code !== 0) return { ok: false, step: 'git pull', code: pull.code };
+  } else {
+    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 };
+  }
+  const build = await exec('make', ['bin/romdiff'], { cwd: sourceDir });
+  const binaryPath = join(sourceDir, 'bin', 'romdiff');
+  if (build.code !== 0 || !(await exists(binaryPath))) {
+    return { ok: false, step: 'make bin/romdiff', code: build.code, binaryPath };
+  }
+  return { ok: true, binaryPath };
+}
+
+/**
+ * Run `romdiff <rdfPath> <outputPath>` in a scratch working directory that
+ * contains only the base ROM, copied in under the exact filename the .rdf's
+ * own header names (`header.referenceFilename`, e.g. `910828.BIN`) — romdiff
+ * reads that filename from the diff file itself and looks for it in its
+ * current directory, so this never assumes a hardcoded name. The user's
+ * original base-ROM file and the mega65-tools checkout are both left
+ * untouched; everything romdiff touches lives under `workDir`.
+ */
+export async function patchRom({
+  romdiffPath, rdfPath, workDir, baseRomPath, header, exec = execCapture, copy = cp, mkdirFn = mkdir, read = readFile,
+}) {
+  await mkdirFn(workDir, { recursive: true });
+  const referenceFilename = header.referenceFilename;
+  await copy(baseRomPath, join(workDir, referenceFilename));
+  const outputPath = join(workDir, 'MEGA65.ROM');
+  const result = await exec(romdiffPath, [rdfPath, outputPath], { cwd: workDir });
+  if (result.code !== 0) {
+    return { ok: false, output: result.stdout + result.stderr };
+  }
+  const buffer = await read(outputPath);
+  const validation = validateRomBuffer(buffer, { size: MEGA65_ROM_920413.romSize, sha256: MEGA65_ROM_920413.romSha256 });
+  return {
+    ok: validation.ok, outputPath, buffer, validation, output: result.stdout + result.stderr,
+  };
+}
+
+export async function cleanupWorkDir(workDir, remove = rm) {
+  await remove(workDir, { recursive: true, force: true });
+}