@henols/c64-re-tools 2.0.0-rc.2 → 2.0.0-rc.4

package/src/host/server.ts

@@ -1,4 +1,3 @@
-import { createHash, timingSafeEqual } from "node:crypto";
 import { createServer, type Server, type Socket } from "node:net";
 
 import { encodeFrame, MessageReader } from "../protocol/framing.ts";
@@ -12,9 +11,10 @@ export interface ViceSessionHandle {
   /**
    * Runs one operation. The session serializes its own work. Throws
    * WireFailure for domain failures. `attachments` holds the bytes the
-   * operation takes (see attachmentCount).
+   * operation takes (see attachmentCount); bytes the operation sends back go
+   * into `reply`.
    */
-  handle<O extends ViceOperation>(op: O, params: ViceOperations[O]["params"], attachments?: Buffer[]): Promise<ViceOperations[O]["result"]>;
+  handle<O extends ViceOperation>(op: O, params: ViceOperations[O]["params"], attachments?: Buffer[], reply?: Buffer[]): Promise<ViceOperations[O]["result"]>;
   /** Stops the emulator and drops queued work. Safe to call more than once. */
   close(): Promise<void>;
 }
@@ -37,16 +37,8 @@ export interface HostServerOptions {
   createViceSession: ViceSessionFactory;
   /** Native-tool requests on "tool" connections; without it they are refused. */
   tools?: ToolDispatcher;
-  /** Defaults to 127.0.0.1. More addresses listen on the same port, for example a container bridge. */
+  /** Defaults to 127.0.0.1; 0.0.0.0 listens on every address, so a container reaches it too. */
   host?: string;
-  /** Extra addresses to listen on, on the same port as `host`. */
-  extraHosts?: string[];
-  /**
-   * The shared secret. A connection that arrives on an address that is
-   * not loopback must send it in its hello; without a token such a
-   * connection is refused.
-   */
-  token?: string;
   /** 0 picks a free port. */
   port: number;
   /** How long a new connection may stay silent before it must send hello. */
@@ -67,10 +59,6 @@ const DEFAULT_HANDSHAKE_TIMEOUT_MS = 10_000;
 /** How long a refused client may keep its side of the connection open after the host has ended its side. */
 const REFUSED_CLOSE_MS = 1_000;
 
-function digest(text: string): Buffer {
-  return createHash("sha256").update(text, "utf8").digest();
-}
-
 /** A caught value for the log, with its stack when it has one. */
 function describe(error: unknown): string {
   return error instanceof Error ? (error.stack ?? error.message) : String(error);
@@ -95,18 +83,6 @@ class Connection {
   #isTool = false;
   readonly #reader = new MessageReader();
 
-  /** A connection on a loopback address needs no token; any other needs the host's token. */
-  #checkToken(token: string | undefined): WireError | undefined {
-    if (isLoopback(this.#socket.localAddress ?? "")) return undefined;
-    const expected = this.#options.token;
-    // Equal-length digests: the comparison takes the same time for any token, also one with multibyte characters.
-    const matches = expected !== undefined && token !== undefined && timingSafeEqual(digest(token), digest(expected));
-    if (matches) return undefined;
-    return {
-      code: "installation-incomplete",
-      message: "The c64-re-tools host runtime refused this client: a connection from outside the host needs C64RT_HOST_TOKEN with the same value on both sides.",
-    };
-  }
   readonly #socket: Socket;
   readonly #options: HostServerOptions;
   readonly #log: (line: string) => void;
@@ -191,7 +167,7 @@ class Connection {
     if (this.#state === "handshake") {
       if (message.type !== "hello") throw new ProtocolError("first message is not hello");
       clearTimeout(this.#handshakeTimer);
-      const mismatch = checkHello(message) ?? this.#checkToken(message.token);
+      const mismatch = checkHello(message);
       if (mismatch !== undefined) {
         this.#log(`refusing a client: ${mismatch.message}`);
         trace().event("connection.refused", { connection: this.#id, role: message.role, ...mismatch });
@@ -270,10 +246,10 @@ class Connection {
         const session = this.#session;
         if (session === undefined || !isOneOf(VICE_OPERATIONS, op)) throw new WireFailure("invalid-input", `unknown operation: ${op}`);
         const params = validateViceParams(op, request.params);
-        if (attachments.length !== attachmentCount(op)) {
-          throw new WireFailure("invalid-input", `${op} takes ${attachmentCount(op)} file attachment(s)`);
+        if (attachments.length !== attachmentCount(op, params)) {
+          throw new WireFailure("invalid-input", `${op} takes ${attachmentCount(op, params)} file attachment(s)`);
         }
-        result = await session.handle(op, params, attachments);
+        result = await session.handle(op, params, attachments, replyAttachments);
       }
       this.#send({ type: "reply", id: request.id, result }, replyAttachments);
       record({ ok: true, result });
@@ -308,12 +284,6 @@ class Connection {
   }
 }
 
-/** True for 127.0.0.0/8 and ::1, also in their IPv4-mapped IPv6 form. */
-export function isLoopback(address: string): boolean {
-  const plain = address.startsWith("::ffff:") ? address.slice(7) : address;
-  return plain === "::1" || /^127\.\d+\.\d+\.\d+$/.test(plain);
-}
-
 /** A port as the user gives it: decimal digits only, 0 to 65535. Anything else gives undefined. */
 export function parsePort(text: string): number | undefined {
   if (!/^\d{1,5}$/.test(text)) return undefined;
@@ -386,8 +356,6 @@ export async function startHostServer(options: HostServerOptions): Promise<HostS
   let port: number;
   try {
     port = await listen(host, options.port);
-    // The extra addresses share the port, so one endpoint setting reaches every address.
-    for (const extra of options.extraHosts ?? []) await listen(extra, port);
   } catch (error) {
     await Promise.all(servers.map((server) => new Promise<void>((resolve) => server.close(() => resolve()))));
     throw error;

package/src/host/vice/adapter.ts

@@ -3,7 +3,7 @@
 
 import { WireFailure, type VideoStandard } from "../../protocol/messages.ts";
 import { type Comparison, type Condition, type BacktraceFrame, type HistoryEntry, type Instruction, type MemmapRange, type ProfileEntry, type JoystickState, type MemoryView, type RegisterValues, type Registers, type Space } from "../../protocol/vice.ts";
-import { formatC64Address, formatC64Byte } from "../../c64.ts";
+import { COVERAGE, formatC64Address, formatC64Byte } from "../../c64.ts";
 import { decodeDisplay, decodePalette, visibleFrame, type IndexedFrame } from "./screen.ts";
 import type { TextMonitor } from "./text-monitor.ts";
 import {
@@ -258,12 +258,27 @@ function unknownForm(what: string, lines: string[]): WireFailure {
   return new WireFailure("operation-failed", `VICE printed the ${what} in a form that c64-re-tools does not read: ${JSON.stringify(lines.slice(0, 3))}`);
 }
 
+/** The coverage byte (D40) of one memmap row's I/O, ROM and RAM columns, each "rwx" with "-" for no access. */
+export function memmapFlags(io: string, rom: string, ram: string): number {
+  let flags = 0;
+  if (ram[0] === "r") flags |= COVERAGE.ramRead;
+  if (ram[1] === "w") flags |= COVERAGE.ramWrite;
+  if (ram[2] === "x") flags |= COVERAGE.ramExecute;
+  if (rom[0] === "r") flags |= COVERAGE.romRead;
+  if (rom[2] === "x") flags |= COVERAGE.romExecute;
+  if (io[0] === "r") flags |= COVERAGE.ioRead;
+  if (io[1] === "w") flags |= COVERAGE.ioWrite;
+  if (io[2] === "x") flags |= COVERAGE.ioExecute;
+  return flags;
+}
+
 /**
  * Parses memmap rows such as "00c2: --- --- rw- (uninitialized read)": the I/O,
  * ROM and RAM access flags of one address. Adjacent addresses with the same
- * combined flags merge into one range; at most `maxRanges` come back.
+ * flags merge into one range; at most `maxRanges` come back. When more ranges
+ * follow, `next` is the first touched address that is not reported.
  */
-export function parseMemmap(answer: string, maxRanges: number): MemmapRange[] {
+export function parseMemmap(answer: string, maxRanges: number): { ranges: MemmapRange[]; next?: number } {
   const ranges: MemmapRange[] = [];
   const unknown: string[] = [];
   for (const line of answer.split("\n")) {
@@ -273,18 +288,18 @@ export function parseMemmap(answer: string, maxRanges: number): MemmapRange[] {
       continue;
     }
     const address = Number.parseInt(match[1]!, 16);
-    const flags = match[2]! + match[3]! + match[4]!;
-    const access = { execute: flags.includes("x"), read: flags.includes("r"), write: flags.includes("w") };
+    const flags = memmapFlags(match[2]!, match[3]!, match[4]!);
+    if (flags === 0) continue;
     const last = ranges.at(-1);
-    if (last !== undefined && last.end === address - 1 && last.execute === access.execute && last.read === access.read && last.write === access.write) {
+    if (last !== undefined && last.end === address - 1 && last.flags === flags) {
       last.end = address;
       continue;
     }
-    if (ranges.length >= maxRanges) break;
-    ranges.push({ start: address, end: address, ...access });
+    if (ranges.length >= maxRanges) return { ranges, next: address };
+    ranges.push({ start: address, end: address, flags });
   }
   if (ranges.length === 0 && unknown.length > 0) throw unknownForm("memory map", unknown);
-  return ranges;
+  return { ranges };
 }
 
 /**
@@ -739,7 +754,7 @@ export class ViceAdapter {
   }
 
   /** How the C64 CPU accessed [start, end] since the memmap was last cleared, as merged ranges. */
-  async memmap(start: number, end: number, maxRanges: number): Promise<MemmapRange[]> {
+  async memmap(start: number, end: number, maxRanges: number): Promise<{ ranges: MemmapRange[]; next?: number }> {
     // The first argument is the access mask ("ioRWXrwx"); ff shows every kind of access.
     return parseMemmap(await this.#computerText(`mmsh ff ${hex4(start)} ${hex4(end)}`, 60_000), maxRanges);
   }

package/src/host/vice/session.ts

@@ -4,8 +4,8 @@
 // and back; breakpoints, watchpoints and the rest go along.
 
 import { WireFailure, type VideoStandard } from "../../protocol/messages.ts";
-import { MAX_BASELINES, MAX_SNAPSHOTS, MAX_COMPARE_DIFFERENCES, RASTER, type Breakpoint, type BreakpointParams, type Condition, type ExecutionParams, type HistoryEntry, type RunTarget, type RunUntilResult, type ScreenComparison, type CiaSelection, type CiaState, type ObserveParams, type ObserveResult, type SidState, type SpriteState, type ViciiState, type JoystickState, type Watchpoint, type WatchpointParams, type ExecutionResult, type MachineStatus, type RunState, type ViceOperation, type ViceOperations, type WindowResult } from "../../protocol/vice.ts";
-import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { MAX_BASELINES, MAX_SNAPSHOTS, MAX_COMPARE_DIFFERENCES, RASTER, type Breakpoint, type BreakpointParams, type PointRemoved, type Condition, type ExecutionParams, type HistoryEntry, type RunTarget, type RunUntilResult, type ScreenComparison, type CiaSelection, type CiaState, type ObserveParams, type ObserveResult, type SidState, type SpriteState, type ViciiState, type JoystickState, type Watchpoint, type WatchpointParams, type ExecutionResult, type MachineStatus, type RunState, type ViceOperation, type ViceOperations, type WindowResult } from "../../protocol/vice.ts";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { setTimeout as sleep } from "node:timers/promises";
@@ -283,9 +283,10 @@ export class ViceSession implements ViceSessionHandle {
     op: O,
     params: ViceOperations[O]["params"],
     attachments: Buffer[] = [],
+    reply: Buffer[] = [],
   ): Promise<ViceOperations[O]["result"]> {
     // A window request for the mode the session is in sends nothing to VICE, so a held VICE does not stop it.
-    return this.#enqueue(() => this.#run(op, params, attachments), { whileHeld: op === "window" }) as Promise<ViceOperations[O]["result"]>;
+    return this.#enqueue(() => this.#run(op, params, attachments, reply), { whileHeld: op === "window" }) as Promise<ViceOperations[O]["result"]>;
   }
 
   async close(): Promise<void> {
@@ -303,10 +304,15 @@ export class ViceSession implements ViceSessionHandle {
     return this.#adapter;
   }
 
-  async #run(op: ViceOperation, params: unknown, attachments: Buffer[]): Promise<unknown> {
+  async #run(op: ViceOperation, params: unknown, attachments: Buffer[], reply: Buffer[]): Promise<unknown> {
     switch (op) {
       case "status":
         return this.#status();
+      case "ioRead": {
+        const read = params as ViceOperations["ioRead"]["params"];
+        const bytes = await this.#observe(() => this.#machine.readIo(read.address, read.size));
+        return { address: read.address, data: Buffer.from(bytes).toString("hex") };
+      }
       case "memoryRead": {
         const read = params as ViceOperations["memoryRead"]["params"];
         const data = await this.#observe(() => this.#machine.readMemory(read));
@@ -394,6 +400,8 @@ export class ViceSession implements ViceSessionHandle {
       }
       case "snapshot":
         return this.#snapshot(params as ViceOperations["snapshot"]["params"]);
+      case "snapshotFile":
+        return this.#snapshotFile(params as ViceOperations["snapshotFile"]["params"], attachments, reply);
       case "cpuHistory":
         return this.#cpuHistory(params as ViceOperations["cpuHistory"]["params"]);
       case "backtrace": {
@@ -422,7 +430,7 @@ export class ViceSession implements ViceSessionHandle {
           await this.#observe(() => this.#machine.clearMemmap());
           return { cleared: true };
         }
-        return { ranges: await this.#observe(() => this.#machine.memmap(request.start, request.end, request.maxRanges)) };
+        return await this.#observe(() => this.#machine.memmap(request.start, request.end, request.maxRanges));
       }
       case "vicii":
         return this.#observe(() => this.#vicii());
@@ -716,34 +724,44 @@ export class ViceSession implements ViceSessionHandle {
   async #changePoint<T extends { checkpoint: number; enabled: boolean }>(
     registry: Map<number, T>,
     kind: string,
-    params: { action: "remove" | "enable" | "disable"; id: number },
+    params: { action: "enable" | "disable"; id: number },
   ): Promise<T> {
-    const point = registry.get(params.id);
-    if (point === undefined) throw new WireFailure("not-found", `There is no ${kind} with id ${params.id}.`);
-    if (params.action === "remove") {
-      await this.#observe(() => this.#machine.deleteCheckpoint(point.checkpoint));
-      registry.delete(params.id);
-    } else {
-      const enabled = params.action === "enable";
-      await this.#observe(() => this.#machine.toggleCheckpoint(point.checkpoint, enabled));
-      point.enabled = enabled;
-    }
+    const point = this.#point(registry, kind, params.id);
+    const enabled = params.action === "enable";
+    await this.#observe(() => this.#machine.toggleCheckpoint(point.checkpoint, enabled));
+    point.enabled = enabled;
     return point;
   }
 
-  async #breakpoint(params: BreakpointParams): Promise<Breakpoint | { breakpoints: Breakpoint[] }> {
+  async #removePoint(registry: Map<number, { checkpoint: number }>, kind: string, id: number): Promise<PointRemoved> {
+    const point = this.#point(registry, kind, id);
+    await this.#observe(() => this.#machine.deleteCheckpoint(point.checkpoint));
+    registry.delete(id);
+    return { removed: true, id };
+  }
+
+  #point<T>(registry: Map<number, T>, kind: string, id: number): T {
+    const point = registry.get(id);
+    if (point === undefined) throw new WireFailure("not-found", `There is no ${kind} with id ${id}.`);
+    return point;
+  }
+
+  async #breakpoint(params: BreakpointParams): Promise<Breakpoint | PointRemoved | { breakpoints: Breakpoint[] }> {
     const publicView = ({ checkpoint: _checkpoint, expression: _expression, ...point }: Breakpoint & { checkpoint: number; expression?: string }): Breakpoint =>
       point;
     if (params.action === "list") return { breakpoints: [...this.#breakpoints.values()].map(publicView) };
+    if (params.action === "remove") return this.#removePoint(this.#breakpoints, "breakpoint", params.id);
     if (params.action !== "add") return publicView(await this.#changePoint(this.#breakpoints, "breakpoint", params));
+    // A breakpoint over a range stops at the first instruction executed in it: exec, not a watch (D43).
     const added = await this.#addPoint({
-      ...pointRange({ address: params.address }),
+      ...(params.size === undefined ? pointRange({ address: params.address }) : { start: params.address, end: params.address + params.size - 1, operation: 0x04 }),
       space: params.space,
       ...(params.condition === undefined ? {} : { condition: params.condition }),
     });
     const point = {
       id: this.#nextPointId++,
       address: params.address,
+      ...(params.size === undefined ? {} : { size: params.size }),
       space: params.space,
       enabled: true,
       ...(params.condition === undefined ? {} : { condition: params.condition }),
@@ -753,10 +771,11 @@ export class ViceSession implements ViceSessionHandle {
     return publicView(point);
   }
 
-  async #watchpoint(params: WatchpointParams): Promise<Watchpoint | { watchpoints: Watchpoint[] }> {
+  async #watchpoint(params: WatchpointParams): Promise<Watchpoint | PointRemoved | { watchpoints: Watchpoint[] }> {
     const publicView = ({ checkpoint: _checkpoint, expression: _expression, ...point }: Watchpoint & { checkpoint: number; expression?: string }): Watchpoint =>
       point;
     if (params.action === "list") return { watchpoints: [...this.#watchpoints.values()].map(publicView) };
+    if (params.action === "remove") return this.#removePoint(this.#watchpoints, "watchpoint", params.id);
     if (params.action !== "add") return publicView(await this.#changePoint(this.#watchpoints, "watchpoint", params));
     const added = await this.#addPoint({
       ...pointRange({ address: params.address, size: params.size, access: params.access }),
@@ -910,15 +929,40 @@ export class ViceSession implements ViceSessionHandle {
       this.#snapshots.delete(params.name);
       return { discarded: true };
     }
+    return this.#restoreFrom(existing);
+  }
+
+  /** Restores the machine from a .vsf in the session directory; the CPU stays stopped. */
+  async #restoreFrom(file: string): Promise<{ restored: true; state: "stopped" }> {
     await this.#stop();
     const elapsed = (await this.#machine.clock()) - this.#timingStart;
-    await this.#machine.restoreSnapshot(existing);
+    await this.#machine.restoreSnapshot(file);
     this.#state = "stopped";
     // The cycle clock jumped with the restore; the stopwatch keeps its reading, as a window move does.
     this.#timingStart = (await this.#machine.clock()) - elapsed;
     return { restored: true, state: "stopped" };
   }
 
+  /** A snapshot as bytes (D41): export a named one into `reply`, or restore from the attached .vsf. */
+  async #snapshotFile(params: ViceOperations["snapshotFile"]["params"], attachments: Buffer[], reply: Buffer[]): Promise<ViceOperations["snapshotFile"]["result"]> {
+    if (params.action === "export") {
+      const file = this.#snapshots.get(params.name);
+      if (file === undefined) throw new WireFailure("not-found", `There is no snapshot named ${params.name}.`);
+      const bytes = readFileSync(file);
+      reply.push(bytes);
+      return { exported: true, bytes: bytes.length };
+    }
+    const file = this.#stage(onlyAttachment(attachments), "vsf");
+    try {
+      return await this.#restoreFrom(file);
+    } catch (error) {
+      if (error instanceof WireFailure) throw error;
+      throw new WireFailure("invalid-input", "The emulator did not restore this snapshot file. A snapshot file restores only in the emulator version and with the machine settings that saved it.");
+    } finally {
+      rmSync(file, { force: true });
+    }
+  }
+
   /**
    * Moves the machine into a VICE of the other mode: a snapshot of this
    * one, restored in a new one, with the user points, joysticks, warp and the

package/src/host-client/autostart.ts

@@ -0,0 +1,45 @@
+// Autostart without the autostart's own RUN: the caller decides when the
+// program starts, so keys it types later never mix with VICE's typing.
+
+import { textToPetscii } from "../c64.ts";
+import type { ViceSessionClient } from "./vice-session.ts";
+
+/** How often, and for how long, a load is checked. */
+export const LOAD_POLL_FRAMES = 25;
+export const LOAD_LIMIT_FRAMES = 1500;
+
+/**
+ * Autostarts the PRG at `path` with run false and advances frames until its
+ * first bytes are at its load address. Returns false when they do not arrive
+ * within LOAD_LIMIT_FRAMES.
+ */
+export async function autostartLoaded(client: ViceSessionClient, path: string, prg: Uint8Array): Promise<boolean> {
+  const load = prg[0]! | (prg[1]! << 8);
+  const head = Buffer.from(prg.subarray(2, Math.min(prg.length, 2 + 64))).toString("hex");
+  await client.autostart({ path, index: 0, run: false });
+  for (let frames = 0; frames < LOAD_LIMIT_FRAMES; frames += LOAD_POLL_FRAMES) {
+    await client.execution({ action: "advance-frames", count: LOAD_POLL_FRAMES, space: "c64" });
+    if ((await client.memoryRead({ address: load, size: head.length / 2, space: "c64", view: "ram" })).data === head) return true;
+  }
+  return false;
+}
+
+/** CURLIN high byte: $ff while BASIC waits in direct mode, a line number's high byte while a program runs. */
+const CURLIN_HIGH = 0x003a;
+export const RUN_LIMIT_FRAMES = 300;
+
+/**
+ * Autostart that returns only when the program runs: load without VICE's
+ * own RUN, type RUN, and wait until BASIC runs a program line. A key that a
+ * later step types then reaches the program, never the READY prompt. Returns
+ * why it did not start, or undefined when it runs.
+ */
+export async function runProgram(client: ViceSessionClient, path: string, prg: Uint8Array): Promise<"not-loaded" | "not-started" | undefined> {
+  if (!(await autostartLoaded(client, path, prg))) return "not-loaded";
+  await client.keyboard(textToPetscii("RUN\n"));
+  const started = await client.runUntil({
+    target: { kind: "memory", address: CURLIN_HIGH, operator: "ne", value: 0xff, space: "c64", view: "ram" },
+    timeoutFrames: RUN_LIMIT_FRAMES,
+  });
+  return started.reached ? undefined : "not-started";
+}

package/src/host-client/connect.ts

@@ -4,7 +4,7 @@ import { connect as connectTcp, type Socket } from "node:net";
 
 import { encodeFrame, MessageReader } from "../protocol/framing.ts";
 import { elapsedMs, trace } from "../trace.ts";
-import { DEFAULT_HOST_PORT, HEARTBEAT_INTERVAL_MS, HEARTBEAT_TIMEOUT_MS, HOST_PROTOCOL_ID, HOST_PROTOCOL_VERSION, parseHostMessage, ProtocolError, WireFailure, type ErrorCode, type Hello, type HostMessage, type Ping, type Request, type Role, type VideoStandard } from "../protocol/messages.ts";
+import { DEFAULT_HOST_PORT, HEARTBEAT_INTERVAL_MS, HEARTBEAT_TIMEOUT_MS, HOST_PROTOCOL_ID, HOST_PROTOCOL_VERSION, parseHostMessage, ProtocolError, WireFailure, withStopAndAsk, type ErrorCode, type Hello, type HostMessage, type Ping, type Request, type Role, type VideoStandard } from "../protocol/messages.ts";
 
 export interface Endpoint {
   host: string;
@@ -40,7 +40,9 @@ function unreachable(role: Role): WireFailure {
   const code: ErrorCode = role === "vice-session" ? "machine-unavailable" : "operation-failed";
   return new WireFailure(
     code,
-    "The c64-re-tools host runtime is not running or cannot be reached. Start it on the host (npx -y --package=@henols/c64-re-tools@latest c64-re-tools-host) and try again.",
+    withStopAndAsk(
+      "The c64-re-tools host runtime is not running or cannot be reached. Start it on the host (npx -y --package=@henols/c64-re-tools@latest c64-re-tools-host) and try again.",
+    ),
   );
 }
 
@@ -150,9 +152,6 @@ export class HostConnection {
     const connection = new HostConnection(socket);
     const hello: Hello = { type: "hello", protocol: HOST_PROTOCOL_ID, version: HOST_PROTOCOL_VERSION, role: options.role };
     if (options.videoStandard !== undefined) hello.videoStandard = options.videoStandard;
-    // A host that listens beyond loopback checks this shared secret.
-    const token = (options.env ?? process.env).C64RT_HOST_TOKEN;
-    if (token !== undefined && token !== "") hello.token = token;
 
     const stop = () => void connection.close();
     signal?.addEventListener("abort", stop, { once: true });

package/src/host-client/coverage.ts

@@ -0,0 +1,59 @@
+// Reads the emulator's memory access map as coverage bytes (D40): one byte
+// per address, RAM, ROM and I/O apart. The MCP tool and the skill scripts share it.
+
+import { COVERAGE, type CodeRange } from "../c64.ts";
+import { MAX_MEMMAP_RANGES, type MemmapRange } from "../protocol/vice.ts";
+import { readProjectFile } from "./transfer.ts";
+import type { ViceSessionClient } from "./vice-session.ts";
+
+/** A full coverage file: offset n is address n (D40). */
+export const FULL_COVERAGE = 0x10000;
+
+/**
+ * Reads full coverage files from the project and joins them: an address has
+ * every flag that any run gave it. `fail` refuses a file of another size.
+ */
+export function readCoverageFiles(paths: string[], fail: (message: string) => never): Uint8Array | undefined {
+  if (paths.length === 0) return undefined;
+  const joined = new Uint8Array(FULL_COVERAGE);
+  for (const path of paths) {
+    const { bytes } = readProjectFile(path);
+    if (bytes.length !== FULL_COVERAGE) {
+      fail(`--coverage ${path} has ${bytes.length} bytes; a full coverage file has 65536, one for each address. Write it with c64_memmap action read and out, without start and end.`);
+    }
+    for (let address = 0; address < FULL_COVERAGE; address++) joined[address]! |= bytes[address]!;
+  }
+  return joined;
+}
+
+/** The coverage bytes of start..end, read from the session in parts. */
+export async function readCoverage(session: Pick<ViceSessionClient, "memmap">, start = 0x0000, end = 0xffff): Promise<Uint8Array> {
+  const map = new Uint8Array(end - start + 1);
+  for (let from: number | undefined = start; from !== undefined; ) {
+    const part: { ranges: MemmapRange[]; next?: number } = await session.memmap({ action: "read", start: from, end, maxRanges: MAX_MEMMAP_RANGES });
+    for (const range of part.ranges) map.fill(range.flags, range.start - start, range.end - start + 1);
+    from = part.next;
+  }
+  return map;
+}
+
+/** Runs of RAM that a program wrote, at least `minimum` bytes each, in a map from $0000. */
+export function writtenBlocks(map: Uint8Array, minimum: number): CodeRange[] {
+  const blocks: CodeRange[] = [];
+  let start = -1;
+  for (let address = 0; address <= map.length; address++) {
+    const written = address < map.length && (map[address]! & COVERAGE.ramWrite) !== 0;
+    if (written && start < 0) start = address;
+    if (!written && start >= 0) {
+      if (address - start >= minimum) blocks.push({ start, end: address - 1 });
+      start = -1;
+    }
+  }
+  return blocks;
+}
+
+/** True when the CPU executed an instruction in RAM somewhere in the range. */
+export function executedIn(map: Uint8Array, range: CodeRange): boolean {
+  for (let address = range.start; address <= range.end; address++) if ((map[address]! & COVERAGE.ramExecute) !== 0) return true;
+  return false;
+}