@henols/c64-re-tools 2.0.0 → 2.1.0-rc.1

package/skills/c64-testing/scripts/record.ts

@@ -0,0 +1,96 @@
+// The c64-testing record script: plays the steps of a record file on the
+// original program in the replay core (c64run), and writes the session as a
+// recording folder: recording.json, reads.txt, checkpoints.txt, coverage.bin.
+// Exit status: 0 recorded, 1 the session did not complete, 2 a bad call.
+
+import { parseArgs } from "node:util";
+
+import { COVERAGE } from "#src/c64.ts";
+import { writeProjectFile } from "#src/host-client/transfer.ts";
+import { C64RunSession, PAL_FRAME_CYCLES } from "#src/native/c64run.ts";
+import { localToolContext } from "#src/native/local.ts";
+import { Workspace } from "#src/native/staging.ts";
+import { resolveProjectPath } from "#src/project.ts";
+import { runScript, UsageError } from "#src/script.ts";
+import { play } from "./lib/play.ts";
+import { record, readRecordFile, RECORDING_FILES } from "./lib/recording.ts";
+import { ScenarioError } from "./lib/scenario.ts";
+
+const USAGE = `record.ts <record.json> --out <folder> [--play [--joystick 1|2] [--http-port <n>]]
+
+<record.json> is a record file relative to the project folder. See
+references/recording-format.md. --out is the recording folder, for example
+tests/recordings/<name>. With --play, a person plays after the steps: the
+script prints the address of a page on stderr and runs until Stop on the page.
+--joystick is the port of the arrow keys, space and the gamepad (default 2).
+--http-port is the port of the page (default 6465). The result is one JSON object.`;
+
+/** The default port of the --play page: next to the Host Runtime's 6464. */
+const DEFAULT_HTTP_PORT = 6465;
+
+async function run(argv: string[]): Promise<Record<string, unknown>> {
+  const { values, positionals } = parseArgs({
+    args: argv,
+    strict: true,
+    allowPositionals: true,
+    options: { out: { type: "string" }, play: { type: "boolean" }, joystick: { type: "string" }, "http-port": { type: "string" }, help: { type: "boolean" } },
+  });
+  if (values.help) throw new UsageError("");
+  if (positionals.length !== 1) throw new UsageError("give one record file");
+  if (values.out === undefined) throw new UsageError("give --out, the recording folder");
+  try {
+    resolveProjectPath(values.out);
+  } catch {
+    throw new UsageError(`--out must be a path relative to the project folder that stays inside it, not ${values.out}`);
+  }
+  if (!values.play && (values.joystick !== undefined || values["http-port"] !== undefined)) throw new UsageError("--joystick and --http-port are for --play");
+  const joystick = values.joystick === undefined ? 2 : Number(values.joystick);
+  if (joystick !== 1 && joystick !== 2) throw new UsageError("--joystick must be 1 or 2");
+  const httpPort = values["http-port"] === undefined ? DEFAULT_HTTP_PORT : Number(values["http-port"]);
+  if (!Number.isInteger(httpPort) || httpPort < 0 || httpPort > 65535) throw new UsageError("--http-port must be a TCP port from 0 to 65535");
+  let file;
+  try {
+    file = readRecordFile(positionals[0]!);
+  } catch (error) {
+    if (error instanceof ScenarioError) throw new UsageError(error.message);
+    throw error;
+  }
+  const context = localToolContext();
+  const core = await C64RunSession.open(context);
+  const workspace = Workspace.create(context.supervisor, "c64-re-tools-record-");
+  try {
+    let outcome;
+    try {
+      const person = values.play
+        ? (session: C64RunSession) =>
+            play(session, { httpPort, joystick, ready: (url) => process.stderr.write(`Play at ${url} and press Stop on the page to save the recording.\n`) })
+        : undefined;
+      outcome = await record(core, file, workspace, person);
+    } catch (error) {
+      if (error instanceof ScenarioError) throw new UsageError(error.message);
+      throw error;
+    }
+    const summary = {
+      name: file.name,
+      frames: Math.round(outcome.recording.ticks / PAL_FRAME_CYCLES),
+      inputSites: outcome.recording.sites.length,
+      events: outcome.recording.events.length,
+      // The instructions in the coverage map: 0 when the program never read its input from RAM.
+      executed: outcome.coverage.reduce((count, byte) => count + ((byte & COVERAGE.ramExecute) === 0 ? 0 : 1), 0),
+    };
+    if (outcome.reason !== undefined) {
+      process.exitCode = 1;
+      return { recorded: false, reason: outcome.reason, ...summary };
+    }
+    const write = (name: string, bytes: Uint8Array) => writeProjectFile(`${values.out}/${name}`, bytes, { what: "--out" });
+    write(RECORDING_FILES.recording, Buffer.from(`${JSON.stringify(outcome.recording, null, 2)}\n`));
+    write(RECORDING_FILES.reads, outcome.reads);
+    write(RECORDING_FILES.coverage, outcome.coverage);
+    return { recorded: true, out: values.out, ...summary, files: Object.values(RECORDING_FILES) };
+  } finally {
+    await core.close();
+    workspace.remove();
+  }
+}
+
+await runScript(run, { usage: USAGE });

package/skills/c64-testing/scripts/replay.ts

@@ -0,0 +1,163 @@
+// The c64-testing replay script: replays a recording in the replay core
+// (c64run). First on the original program, which must end with the recorded
+// state hash. Then, with --rebuild, on the rebuild: it compares the state at
+// each checkpoint with the original's. --checkpoint and --state choose the
+// comparison, else the record file gave it.
+// Exit status: 0 PASS, 1 FAIL, 3 INCONCLUSIVE, 2 a bad call.
+
+import { createHash } from "node:crypto";
+import { parseArgs } from "node:util";
+
+import { readProjectFile, writeProjectFile } from "#src/host-client/transfer.ts";
+import { C64RunSession } from "#src/native/c64run.ts";
+import { localToolContext } from "#src/native/local.ts";
+import { Workspace } from "#src/native/staging.ts";
+import { resolveProjectPath } from "#src/project.ts";
+import { runScript, UsageError } from "#src/script.ts";
+import { codeLabels, firstDifference, parseStateItem, pinLines, readRecording, replaySide, siteMap, type Comparison, type ReplayResult, type ReplaySubject } from "./lib/recording.ts";
+import { ScenarioError } from "./lib/scenario.ts";
+
+const USAGE = `replay.ts <recording folder> [--checkpoint <routine> --state <item> ... [--pin <item> ...]] [--rebuild <prg> [--symbols <file>]] [--out <dir>]
+
+<recording folder> is a folder that record.ts wrote, relative to the project
+folder. --checkpoint is the name or $ address of a routine; each entry is a
+checkpoint. --state is a name or $ address with :size, one for each item.
+--pin is random state in RAM in the same form: at each checkpoint the rebuild
+gets the original's values there.
+Without them, the replay uses the comparison of the record file. --symbols
+gives the names of the rebuild: the c64-assembler output (default: the
+symbols of the recording). A recording without names takes the names of the
+knowledge for the original. A $ address is an address of the original: on the
+rebuild it moves with the name before it. With --out, a FAIL writes the RAM
+of both sides at the first different checkpoint into <dir>. The result is one
+JSON object.`;
+
+const EXIT = { PASS: 0, FAIL: 1, INCONCLUSIVE: 3 } as const;
+const MAX_STATE_ITEMS = 16;
+
+async function run(argv: string[]): Promise<ReplayResult> {
+  const { values, positionals } = parseArgs({
+    args: argv,
+    strict: true,
+    allowPositionals: true,
+    options: {
+      checkpoint: { type: "string" },
+      state: { type: "string", multiple: true },
+      pin: { type: "string", multiple: true },
+      rebuild: { type: "string" },
+      symbols: { type: "string" },
+      out: { type: "string" },
+      help: { type: "boolean" },
+    },
+  });
+  if (values.help) throw new UsageError("");
+  if (positionals.length !== 1) throw new UsageError("give one recording folder");
+  if (values.symbols !== undefined && values.rebuild === undefined) throw new UsageError("--symbols is for the rebuild: give --rebuild too");
+  if ((values.checkpoint === undefined) !== (values.state === undefined)) throw new UsageError("give --checkpoint and --state together");
+  if ((values.state?.length ?? 0) + (values.pin?.length ?? 0) > MAX_STATE_ITEMS) throw new UsageError(`give at most ${MAX_STATE_ITEMS} --state and --pin items`);
+  if (values.pin !== undefined && values.checkpoint === undefined) throw new UsageError("--pin needs --checkpoint and --state");
+  if (values.out !== undefined) {
+    try {
+      resolveProjectPath(values.out);
+    } catch {
+      throw new UsageError(`--out must be a path relative to the project folder that stays inside it, not ${values.out}`);
+    }
+  }
+  const folder = positionals[0]!.replace(/\/+$/, "").replace(/\/recording\.json$/, "");
+  let recording;
+  let given: Comparison | undefined;
+  try {
+    recording = readRecording(folder);
+    given =
+      values.checkpoint === undefined
+        ? undefined
+        : { checkpoint: values.checkpoint, state: values.state!.map(parseStateItem), ...(values.pin === undefined ? {} : { pin: values.pin.map(parseStateItem) }) };
+  } catch (error) {
+    if (error instanceof ScenarioError) throw new UsageError(error.message);
+    throw error;
+  }
+  const compare = given ?? recording.compare;
+  if (values.rebuild !== undefined && compare === undefined) throw new UsageError("the recording has no checkpoint and state: give --checkpoint and --state");
+  const result = (outcome: ReplayResult["result"], side: ReplayResult["side"], fields: Partial<ReplayResult> = {}): ReplayResult => ({
+    result: outcome,
+    recording: folder,
+    side,
+    ...(compare === undefined ? {} : { checkpoint: compare.checkpoint }),
+    checkpoints: 0,
+    compared: 0,
+    ...fields,
+  });
+  const sha256 = createHash("sha256").update(readProjectFile(recording.program).bytes).digest("hex");
+  if (sha256 !== recording.sha256) return result("INCONCLUSIVE", "original", { reason: `${recording.program} is not the program of the recording (its SHA-256 changed); record the session again` });
+
+  const context = localToolContext();
+  const core = await C64RunSession.open(context);
+  const workspace = Workspace.create(context.supervisor, "c64-re-tools-replay-");
+  try {
+    // A recording made without names takes the names that the knowledge has now.
+    const originalSymbols = recording.symbols === "none" ? "knowledge" : recording.symbols;
+    const original: ReplaySubject = { side: "original", program: recording.program, symbols: originalSymbols };
+    const side = async (subject: ReplaySubject, options: Parameters<typeof replaySide>[5]) => {
+      try {
+        return await replaySide(core, recording, folder, subject, workspace, options);
+      } catch (error) {
+        if (error instanceof ScenarioError) throw new UsageError(error.message);
+        throw error;
+      }
+    };
+    // The self-check: the original ends the session with the recorded state, to the cycle.
+    const self = await side(original, { ...(compare === undefined ? {} : { compare }) });
+    if (self.problem !== undefined) return result("INCONCLUSIVE", "original", { reason: `the recording does not reproduce on the original: ${self.problem}` });
+    if (self.unknown > 0 || self.misses > 0) {
+      return result("INCONCLUSIVE", "original", { reason: `the recording does not reproduce on the original: ${self.unknown + self.misses} input reads had no recorded value; record the session again with this c64run` });
+    }
+    if (self.end.tick !== recording.ticks || self.end.hash !== recording.hash) {
+      return result("INCONCLUSIVE", "original", { reason: "the recording does not reproduce on the original: the state at its end is different; record the session again with this c64run" });
+    }
+    const expected = self.samples;
+    if (compare !== undefined && expected.length === 0) return result("INCONCLUSIVE", "original", { reason: `the original never came to the checkpoint ${compare.checkpoint} in the session` });
+    if (values.rebuild === undefined) return result("PASS", "original", { checkpoints: expected.length });
+
+    const rebuild: ReplaySubject = { side: "rebuild", program: values.rebuild, symbols: values.symbols ?? originalSymbols };
+    let movedSites: number;
+    try {
+      movedSites = siteMap(recording.sites, codeLabels(originalSymbols), codeLabels(rebuild.symbols)).length;
+    } catch (error) {
+      throw new UsageError(`--symbols ${rebuild.symbols}: ${(error as Error).message}`);
+    }
+    const pins = pinLines(expected, compare!.state);
+    const replayed = await side(rebuild, { compare: compare!, stop: expected.length, pins });
+    const difference = firstDifference(expected, replayed.samples, compare!.state);
+    // A read that the recording has no value for gets the idle value: it is in the result, never silent.
+    const base = { checkpoints: expected.length, movedSites, ...(replayed.unknown > 0 ? { idleReads: replayed.unknown } : {}) };
+    if (difference === undefined && replayed.samples.length >= expected.length) return result("PASS", "rebuild", { ...base, compared: expected.length });
+    const reason =
+      difference !== undefined
+        ? `the state differs at checkpoint ${difference.checkpoint} of ${expected.length}${replayed.unknown > 0 ? `; the rebuild read input ${replayed.unknown} times at sites that the recording does not have` : ""}`
+        : `the rebuild came to ${replayed.samples.length} of ${expected.length} checkpoints${replayed.problem === undefined ? "" : `: ${replayed.problem}`}`;
+    const failed = result("FAIL", "rebuild", { ...base, compared: (difference?.checkpoint ?? replayed.samples.length + 1) - 1, reason, ...(difference === undefined ? {} : { firstDifference: difference }) });
+    if (values.out !== undefined && difference !== undefined) {
+      const files: string[] = [];
+      for (const subject of [original, rebuild]) {
+        const dumped = await side(subject, { compare: compare!, dump: difference.checkpoint, ...(subject.side === "rebuild" ? { pins } : {}) });
+        const name = `${subject.side}-${difference.checkpoint}.bin`;
+        writeProjectFile(`${values.out}/${name}`, dumped.ram!, { what: "--out" });
+        files.push(name);
+      }
+      failed.files = files;
+    }
+    return failed;
+  } finally {
+    await core.close();
+    workspace.remove();
+  }
+}
+
+await runScript(
+  async (argv) => {
+    const result = await run(argv);
+    process.exitCode = EXIT[result.result];
+    return result;
+  },
+  { usage: USAGE },
+);

package/src/cli/main.ts

@@ -7,7 +7,7 @@ import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { parseArgs } from "node:util";
 
-import { PACKAGE } from "../package.ts";
+import { oldNodeRefusal, PACKAGE } from "../package.ts";
 import { localToolContext } from "../native/local.ts";
 import { localToolStatus } from "../native/status.ts";
 import { WireFailure } from "../protocol/messages.ts";
@@ -112,6 +112,12 @@ async function main(argv: string[]): Promise<number> {
   }
 }
 
+const oldNode = oldNodeRefusal();
+if (oldNode !== undefined) {
+  console.error(oldNode);
+  process.exit(1);
+}
+
 try {
   process.exitCode = await main(process.argv.slice(2));
 } catch (error) {

package/src/host/main.ts

@@ -11,7 +11,7 @@ import { inspect } from "./tools/c1541.ts";
 import { createToolDispatcher } from "./tools/index.ts";
 import { checkViceStarts, findVice } from "./vice/process.ts";
 import { viceSessionFactory } from "./vice/session.ts";
-import { PACKAGE } from "../package.ts";
+import { oldNodeRefusal, PACKAGE } from "../package.ts";
 
 const HELP = `c64-re-tools-host
 
@@ -144,4 +144,10 @@ async function main(): Promise<number> {
   return 0;
 }
 
+const oldNode = oldNodeRefusal();
+if (oldNode !== undefined) {
+  log(oldNode);
+  process.exit(1);
+}
+
 process.exitCode = await main();

package/src/mcp/main.ts

@@ -13,7 +13,7 @@ import { machineTools } from "./tools/machine.ts";
 import { mediaTools } from "./tools/media.ts";
 import { memoryTools } from "./tools/memory.ts";
 import { videoTools } from "./tools/video.ts";
-import { PACKAGE } from "../package.ts";
+import { oldNodeRefusal, PACKAGE } from "../package.ts";
 
 const HELP = `c64-re-tools-mcp
 
@@ -131,4 +131,10 @@ async function main(): Promise<void> {
   await server.connect(new StdioServerTransport());
 }
 
+const oldNode = oldNodeRefusal();
+if (oldNode !== undefined) {
+  log(oldNode);
+  process.exit(1);
+}
+
 await main();

package/src/native/c64run.ts

@@ -0,0 +1,162 @@
+// The c64run session: one replay core (a C64 emulator, see
+// devcontainer/src/c64-re-tools/c64run.c) for the life of a skill script,
+// driven by one command line and one answer line at a time over its stdin and
+// stdout. It is started through the supervisor like every native tool, so it
+// stops with the script.
+
+import { createInterface } from "node:readline";
+
+import { WireFailure } from "../protocol/messages.ts";
+import { C64RUN, findTool, INSTALL_STEPS } from "./discover.ts";
+import type { SupervisedProcess } from "./processes.ts";
+import type { ToolContext } from "./run.ts";
+
+/** The command protocol that this module speaks; c64run --version and version name it. */
+export const C64RUN_PROTOCOL = 1;
+
+/** CPU cycles in one PAL frame: 312 lines of 63 cycles. */
+export const PAL_FRAME_CYCLES = 19_656;
+
+const STOP_MS = 5_000;
+
+/** The machine state that most commands answer with. */
+export interface CoreStatus {
+  /** CPU cycles since the opcode fetch at the reset vector. */
+  tick: number;
+  /** At an opcode fetch: pc is the address of the next instruction. */
+  sync: boolean;
+  pc: number;
+  a: number;
+  x: number;
+  y: number;
+  s: number;
+  p: number;
+  line: number;
+  cycle: number;
+  /** FNV-1a of RAM from $0002 and of colour RAM. */
+  hash: string;
+  /** The word after "ok", if any: "reached" or "not-reached" for run-pc and run-reads. */
+  word?: string;
+}
+
+export function parseStatus(answer: string): CoreStatus {
+  const parts = answer.split(" ").slice(1);
+  const fields = new Map<string, string>();
+  let word: string | undefined;
+  for (const part of parts) {
+    const at = part.indexOf("=");
+    if (at < 0) word ??= part;
+    else fields.set(part.slice(0, at), part.slice(at + 1));
+  }
+  const hex = (key: string) => Number.parseInt(fields.get(key) ?? "", 16);
+  if (!fields.has("tick")) throw new WireFailure("operation-failed", `c64run gave no machine state: ${answer}`);
+  return {
+    tick: Number(fields.get("tick")),
+    sync: fields.get("sync") === "1",
+    pc: hex("pc"),
+    a: hex("a"),
+    x: hex("x"),
+    y: hex("y"),
+    s: hex("s"),
+    p: hex("p"),
+    line: Number(fields.get("line")),
+    cycle: Number(fields.get("cycle")),
+    hash: fields.get("hash") ?? "",
+    ...(word === undefined ? {} : { word }),
+  };
+}
+
+export class C64RunSession {
+  readonly #process: SupervisedProcess;
+  readonly #waiting: Array<{ resolve: (line: string) => void; reject: (error: Error) => void }> = [];
+  #stderr = "";
+  #ended: WireFailure | undefined;
+
+  private constructor(process: SupervisedProcess) {
+    this.#process = process;
+    const child = process.child;
+    // A core that ended (or never started) closes its stdin: the exit handler reports it.
+    child.stdin!.on("error", () => {});
+    child.stderr!.setEncoding("utf8");
+    child.stderr!.on("data", (chunk: string) => (this.#stderr = (this.#stderr + chunk).slice(-4000)));
+    createInterface({ input: child.stdout! }).on("line", (line) => this.#waiting.shift()?.resolve(line));
+    void process.exited.then((status) => {
+      const how = status.spawnError !== undefined ? `did not start (${status.spawnError})` : `ended (exit ${status.code ?? status.signal})`;
+      this.#ended = new WireFailure(status.spawnError !== undefined ? "installation-incomplete" : "operation-failed", `c64run ${how}.${this.#stderr === "" ? "" : ` ${this.#stderr.trim()}`}`);
+      for (const waiting of this.#waiting.splice(0)) waiting.reject(this.#ended);
+    });
+  }
+
+  /** Starts c64run (C64RT_C64RUN, else c64run on PATH) and checks its protocol. Refuses by name when it is missing. */
+  static async open(context: ToolContext): Promise<C64RunSession> {
+    const env = context.env ?? process.env;
+    const path = findTool(C64RUN, env);
+    const session = new C64RunSession(context.supervisor.spawn([path], { stdio: ["pipe", "pipe", "pipe"], env }));
+    const onAbort = () => void session.close();
+    context.signal.addEventListener("abort", onAbort, { once: true });
+    const version = await session.command("version");
+    const protocol = Number(/protocol=(\d+)/.exec(version)?.[1]);
+    if (protocol !== C64RUN_PROTOCOL) {
+      await session.close();
+      throw new WireFailure("installation-incomplete", `${path} speaks c64run protocol ${Number.isNaN(protocol) ? "(none)" : protocol}; c64-re-tools needs protocol ${C64RUN_PROTOCOL}. ${C64RUN.remedy}`);
+    }
+    return session;
+  }
+
+  /** Sends one command and gives its "ok ..." answer. An "err ..." answer throws operation-failed. */
+  command(text: string): Promise<string> {
+    if (this.#ended !== undefined) return Promise.reject(this.#ended);
+    const answer = new Promise<string>((resolve, reject) => this.#waiting.push({ resolve, reject }));
+    this.#process.child.stdin!.write(`${text}\n`);
+    return answer.then((line) => {
+      if (line.startsWith("ok")) return line;
+      throw new WireFailure("operation-failed", `c64run ${text.split(" ")[0]}: ${line.replace(/^err /, "")}`);
+    });
+  }
+
+  /** A command that answers with the machine state. */
+  async status(text: string): Promise<CoreStatus> {
+    return parseStatus(await this.command(text));
+  }
+
+  /** Power-on: the CPU stops at the reset vector, tick 0. Missing ROMs refuse with the remedy. */
+  async init(romFolder?: string): Promise<CoreStatus> {
+    try {
+      return await this.status(romFolder === undefined ? "init" : `init ${romFolder}`);
+    } catch (error) {
+      if (error instanceof WireFailure && /no ROM/.test(error.message)) {
+        throw new WireFailure(
+          "installation-incomplete",
+          `${error.message}. c64run needs the C64 ROMs kernal-901227-03.bin, basic-901226-01.bin and chargen-901225-01.bin: set C64RT_C64_ROMS to a folder with them (the C64 folder of VICE has them). ${INSTALL_STEPS}`,
+        );
+      }
+      throw error;
+    }
+  }
+
+  /** Writes bytes into RAM (the RAM view), in parts that fit one command line. */
+  async write(address: number, bytes: Uint8Array): Promise<void> {
+    for (let at = 0; at < bytes.length; at += 4096) {
+      await this.command(`write ${((address + at) & 0xffff).toString(16)} ${Buffer.from(bytes.subarray(at, at + 4096)).toString("hex")}`);
+    }
+  }
+
+  /** RAM bytes (the RAM view). */
+  async peek(address: number, size: number): Promise<Uint8Array> {
+    const parts: Buffer[] = [];
+    for (let at = 0; at < size; at += 4096) {
+      const answer = await this.command(`peek ${((address + at) & 0xffff).toString(16)} ${Math.min(4096, size - at)}`);
+      parts.push(Buffer.from(answer.slice(3), "hex"));
+    }
+    return Buffer.concat(parts);
+  }
+
+  /** Ends c64run: quit, then the stop of its process group (at once when it ended, else after STOP_MS). */
+  async close(): Promise<void> {
+    if (this.#ended === undefined) {
+      this.#process.child.stdin!.end("quit\n");
+      await Promise.race([this.#process.exited, new Promise((resolve) => setTimeout(resolve, STOP_MS).unref())]);
+    }
+    await this.#process.stop();
+  }
+}

package/src/native/discover.ts

@@ -55,6 +55,14 @@ export const DXA: ToolSpec = {
   remedy: `Install dxa 0.1.5 on the machine that runs the skill scripts so that dxa is on PATH, or set C64RT_DXA to its full path. ${INSTALL_STEPS}`,
 };
 
+export const C64RUN: ToolSpec = {
+  name: "c64run",
+  envVar: "C64RT_C64RUN",
+  binaries: ["c64run"],
+  where: "on this machine",
+  remedy: `Install c64run (the replay core of c64-testing, with its C64 ROMs) on the machine that runs the skill scripts so that c64run is on PATH, or set C64RT_C64RUN to its full path. The dev container has it. ${INSTALL_STEPS}`,
+};
+
 export const VICE: ToolSpec = {
   name: "VICE (x64sc)",
   envVar: "C64RT_VICE",

package/src/native/status.ts

@@ -8,7 +8,7 @@ import { stripVTControlCharacters } from "node:util";
 
 import { WireFailure } from "../protocol/messages.ts";
 import { type ToolStatus } from "../protocol/tools.ts";
-import { ACME, DXA, findTool } from "./discover.ts";
+import { ACME, C64RUN, DXA, findTool, INSTALL_STEPS } from "./discover.ts";
 import { findGhidra, ghidraVersion, NO_USABLE_JDK, noJdk } from "./ghidra/index.ts";
 import { runTool, type ToolContext } from "./run.ts";
 import { Workspace } from "./staging.ts";
@@ -101,6 +101,27 @@ export async function probeGhidra(context: ToolContext): Promise<ToolStatus> {
   }
 }
 
+/** c64run: --version prints its version and whether its ROM folder has the three C64 ROMs. */
+export async function probeC64run(context: ToolContext): Promise<ToolStatus> {
+  const env = context.env ?? process.env;
+  try {
+    const path = findTool(C64RUN, env);
+    return await run(
+      "c64run",
+      path,
+      ["--version"],
+      (output) => (/^roms=ok /m.test(output) ? versionLine(output, /^c64run protocol=/) : undefined),
+      context,
+      (output) => {
+        const missing = /^roms=missing (.*)$/m.exec(output)?.[1];
+        return missing === undefined ? undefined : `It has no C64 ROMs: ${missing}. Set C64RT_C64_ROMS to a folder with kernal-901227-03.bin, basic-901226-01.bin and chargen-901225-01.bin (the C64 folder of VICE has them). ${INSTALL_STEPS}`;
+      },
+    );
+  } catch (error) {
+    return missing("c64run", error);
+  }
+}
+
 /** The tools that skill scripts run themselves, on this machine. */
 export async function localToolStatus(context: ToolContext): Promise<ToolStatus[]> {
   const probes: Probe[] = [
@@ -109,5 +130,5 @@ export async function localToolStatus(context: ToolContext): Promise<ToolStatus[
     // directory only where that uses "/": on Windows the line starts with the full path.
     { name: "dxa", find: (env) => findTool(DXA, env), args: ["-V"], pattern: DXA_VERSION },
   ];
-  return [...(await probeTools(probes, context)), await probeGhidra(context)];
+  return [...(await probeTools(probes, context)), await probeGhidra(context), await probeC64run(context)];
 }

package/src/package.ts

@@ -14,8 +14,18 @@ export function channelOf(version: string): "latest" | "next" {
   return version.includes("-") ? "next" : "latest";
 }
 
-/** The name, version and dist-tag of this npm package, from its package.json. */
+/** The name, version and dist-tag of this npm package, and the Node.js major version that its engines field requires. */
 export const PACKAGE = (() => {
-  const metadata = JSON.parse(readFileSync(join(import.meta.dirname, "..", "package.json"), "utf8")) as { name: string; version: string };
-  return { name: metadata.name, version: metadata.version, tag: channelOf(metadata.version) };
+  const metadata = JSON.parse(readFileSync(join(import.meta.dirname, "..", "package.json"), "utf8")) as { name: string; version: string; engines?: { node?: string } };
+  const nodeMajor = Number(/(\d+)/.exec(metadata.engines?.node ?? "")?.[1]);
+  return { name: metadata.name, version: metadata.version, tag: channelOf(metadata.version), nodeMajor: Number.isInteger(nodeMajor) ? nodeMajor : undefined };
 })();
+
+/**
+ * The refusal for a Node.js older than `required`, or undefined. An older Node.js
+ * cannot run the skill scripts: they are TypeScript and use node:sqlite.
+ */
+export function oldNodeRefusal(version: string = process.versions.node, required: number | undefined = PACKAGE.nodeMajor): string | undefined {
+  if (required === undefined || Number(version.split(".")[0]) >= required) return undefined;
+  return `c64-re-tools needs Node.js ${required} or newer, and this is Node.js ${version}. Install Node.js ${required} from https://nodejs.org/ and run the command again.`;
+}