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

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.",
+    ),
   );
 }
 

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;
+}

package/src/host-client/steps.ts

@@ -0,0 +1,170 @@
+// The action steps of the step language (D43): write, registers, joystick,
+// type, frames and runUntil. c64-testing scenarios and the c64-unpacker
+// steps file share them; each caller adds its own steps around them.
+
+import { parseC64Address, textToPetscii } from "../c64.ts";
+import { JOYSTICK_DIRECTIONS, MAX_EXECUTION_COUNT, MAX_KEYBOARD_BYTES, MAX_MEMORY_WRITE, MAX_TIMEOUT_FRAMES } from "../protocol/vice.ts";
+import type { RunTarget, RunUntilResult } from "../protocol/vice.ts";
+import type { ViceSessionClient } from "./vice-session.ts";
+
+/** A "$xxxx" address, or a symbol name where the caller resolves names. */
+export type Location = string;
+
+type JoystickDirection = (typeof JOYSTICK_DIRECTIONS)[number];
+
+export type ActionStep =
+  | { write: { at: Location; bytes: number[] } }
+  | { registers: Partial<Record<"pc" | "a" | "x" | "y" | "sp", number | Location>> }
+  | { joystick: { port: 1 | 2; direction: JoystickDirection; fire?: boolean } }
+  | { type: string }
+  | { frames: number }
+  | { runUntil: { at: Location; raster?: number } | { raster: number } | { memory: { at: Location; equals: number } }; timeoutFrames: number };
+
+/** The highest raster line of a PAL frame; an NTSC frame has fewer, which the emulator checks. */
+const MAX_RASTER_LINE = 311;
+
+export const ACTION_STEP_KINDS = ["write", "registers", "joystick", "type", "frames", "runUntil"] as const;
+
+/** The keys a step of each kind can have, when it is more than the kind itself. */
+export const ACTION_STEP_KEYS: Record<string, readonly string[]> = { runUntil: ["runUntil", "timeoutFrames"] };
+
+/** The registers a registers step can set. */
+export const SET_REGISTERS = ["pc", "a", "x", "y", "sp"];
+
+export const isObject = (value: unknown): value is Record<string, unknown> => typeof value === "object" && value !== null && !Array.isArray(value);
+export const isInteger = (value: unknown, min: number, max: number): value is number => Number.isInteger(value) && (value as number) >= min && (value as number) <= max;
+
+/** Checks a "$xxxx" address, or also a symbol name when `names` allows it. */
+export function checkLocation(value: unknown, what: string, fail: (message: string) => never, names = true): void {
+  if (typeof value !== "string" || value === "") fail(`${what} must be a $ address${names ? " or a symbol name" : ""}`);
+  if ((value as string).startsWith("$")) {
+    try {
+      parseC64Address(value as string);
+    } catch {
+      fail(`${what} must be $ followed by four hex digits, not ${value as string}`);
+    }
+  } else if (!names) {
+    fail(`${what} must be $ followed by four hex digits, not ${value as string}`);
+  }
+}
+
+/** Checks one action step of the given kind. `names` says whether symbol names may stand for addresses. */
+export function checkActionStep(kind: string, step: Record<string, unknown>, at: string, fail: (message: string) => never, names = true): void {
+  switch (kind) {
+    case "write": {
+      const write = step.write;
+      if (!isObject(write) || Object.keys(write).some((key) => key !== "at" && key !== "bytes")) return fail(`${at}: write needs at and bytes, and nothing else`);
+      checkLocation(write.at, `${at}: write.at`, fail, names);
+      if (!Array.isArray(write.bytes) || write.bytes.length === 0 || write.bytes.length > MAX_MEMORY_WRITE || !write.bytes.every((byte) => isInteger(byte, 0, 0xff))) {
+        fail(`${at}: write.bytes must be a list of 1 to ${MAX_MEMORY_WRITE} numbers from 0 to 255`);
+      }
+      return;
+    }
+    case "registers": {
+      const registers = step.registers;
+      if (!isObject(registers) || Object.keys(registers).length === 0) return fail(`${at}: registers must name at least one of ${SET_REGISTERS.join(", ")}`);
+      for (const [name, value] of Object.entries(registers)) {
+        if (!SET_REGISTERS.includes(name)) fail(`${at}: registers can set only ${SET_REGISTERS.join(", ")}, not ${name}`);
+        if (typeof value === "string") checkLocation(value, `${at}: registers.${name}`, fail, names);
+        else if (!isInteger(value, 0, name === "pc" ? 0xffff : 0xff)) fail(`${at}: registers.${name} must be ${names ? "a symbol name, " : ""}a $ address or a number from 0 to ${name === "pc" ? 65535 : 255}`);
+      }
+      return;
+    }
+    case "joystick": {
+      const joystick = step.joystick;
+      if (!isObject(joystick) || Object.keys(joystick).some((key) => !["port", "direction", "fire"].includes(key))) return fail(`${at}: joystick needs port and direction, and fire is optional`);
+      if (joystick.port !== 1 && joystick.port !== 2) fail(`${at}: joystick.port must be 1 or 2`);
+      if (!(JOYSTICK_DIRECTIONS as readonly unknown[]).includes(joystick.direction)) fail(`${at}: joystick.direction must be one of ${JOYSTICK_DIRECTIONS.join(", ")}`);
+      if (joystick.fire !== undefined && typeof joystick.fire !== "boolean") fail(`${at}: joystick.fire must be true or false`);
+      return;
+    }
+    case "type": {
+      if (typeof step.type !== "string" || step.type === "") return fail(`${at}: type needs text`);
+      let bytes: Uint8Array;
+      try {
+        bytes = textToPetscii(step.type);
+      } catch (error) {
+        return fail(`${at}: ${(error as Error).message}`);
+      }
+      if (bytes.length > MAX_KEYBOARD_BYTES) fail(`${at}: type can have at most ${MAX_KEYBOARD_BYTES} keys`);
+      return;
+    }
+    case "frames":
+      if (!isInteger(step.frames, 1, MAX_EXECUTION_COUNT)) fail(`${at} needs a frame count from 1 to ${MAX_EXECUTION_COUNT}`);
+      return;
+    case "runUntil": {
+      const target = step.runUntil;
+      const keys = isObject(target) ? Object.keys(target).sort().join(",") : "";
+      // at, raster, at with raster (the address only on that line, D46), or memory.
+      if (!["at", "raster", "at,raster", "memory"].includes(keys)) return fail(`${at}: runUntil needs at, raster, at and raster, or memory`);
+      const until = target as Record<string, unknown>;
+      if ("raster" in until && !isInteger(until.raster, 0, MAX_RASTER_LINE)) fail(`${at}: runUntil.raster must be a raster line from 0 to ${MAX_RASTER_LINE}`);
+      if ("at" in until) checkLocation(until.at, `${at}: runUntil.at`, fail, names);
+      else if ("memory" in until) {
+        const memory = until.memory;
+        if (!isObject(memory) || Object.keys(memory).some((key) => key !== "at" && key !== "equals")) return fail(`${at}: runUntil.memory needs at and equals, and nothing else`);
+        checkLocation(memory.at, `${at}: runUntil.memory.at`, fail, names);
+        if (!isInteger(memory.equals, 0, 0xff)) fail(`${at}: runUntil.memory.equals must be a number from 0 to 255`);
+      }
+      if (!isInteger(step.timeoutFrames, 1, MAX_TIMEOUT_FRAMES)) fail(`${at} needs timeoutFrames from 1 to ${MAX_TIMEOUT_FRAMES}`);
+      return;
+    }
+    default:
+      fail(`${at}: ${kind} is not an action step`);
+  }
+}
+
+/** Checks a list of action steps only, with $ addresses only: the steps file of c64-unpacker. */
+export function checkActionSteps(value: unknown, fail: (message: string) => never): ActionStep[] {
+  if (!Array.isArray(value) || value.length === 0) return fail("the steps are a JSON list with at least one step");
+  value.forEach((step: unknown, index) => {
+    const at = `step ${index + 1}`;
+    if (!isObject(step)) return fail(`${at} must be an object`);
+    const kinds = Object.keys(step).filter((key) => (ACTION_STEP_KINDS as readonly string[]).includes(key));
+    if (kinds.length !== 1) return fail(`${at} must have exactly one of ${ACTION_STEP_KINDS.join(", ")}`);
+    const kind = kinds[0]!;
+    const allowed = ACTION_STEP_KEYS[kind] ?? [kind];
+    for (const key of Object.keys(step)) if (!allowed.includes(key)) fail(`${at} has the key ${key}, which a ${kind} step does not have`);
+    checkActionStep(kind, step, at, fail, false);
+  });
+  return value as ActionStep[];
+}
+
+/** Stops the CPU when it runs: a write, a register change or an exact frame count needs it stopped. */
+async function stop(client: ViceSessionClient): Promise<void> {
+  if ((await client.status()).state === "running") await client.execution({ action: "pause", space: "c64" });
+}
+
+/**
+ * Runs one action step. `at` turns a location into an address. A runUntil
+ * step that does not reach its target returns the stop, for the caller to judge.
+ */
+export async function runActionStep(client: ViceSessionClient, step: ActionStep, at: (location: Location) => number): Promise<RunUntilResult | undefined> {
+  if ("write" in step) {
+    await stop(client);
+    await client.memoryWrite({ address: at(step.write.at), data: Buffer.from(step.write.bytes).toString("hex"), space: "c64", view: "cpu" });
+  } else if ("registers" in step) {
+    await stop(client);
+    const values: Record<string, number> = {};
+    for (const [name, value] of Object.entries(step.registers)) values[name] = typeof value === "number" ? value : at(value as Location);
+    await client.registersSet("c64", values);
+  } else if ("joystick" in step) {
+    await client.joystick({ port: step.joystick.port, direction: step.joystick.direction, fire: step.joystick.fire ?? false });
+  } else if ("type" in step) {
+    await client.keyboard(textToPetscii(step.type));
+  } else if ("frames" in step) {
+    await stop(client);
+    await client.execution({ action: "advance-frames", count: step.frames, space: "c64" });
+  } else {
+    const until = step.runUntil;
+    const target: RunTarget =
+      "at" in until
+        ? { kind: "address", address: at(until.at), space: "c64", ...(until.raster === undefined ? {} : { condition: { kind: "raster" as const, line: until.raster } }) }
+        : "raster" in until
+          ? { kind: "raster", line: until.raster }
+          : { kind: "memory", address: at(until.memory.at), operator: "eq", value: until.memory.equals, space: "c64", view: "cpu" };
+    const reached = await client.runUntil({ target, timeoutFrames: step.timeoutFrames });
+    if (!reached.reached) return reached;
+  }
+  return undefined;
+}

package/src/host-client/transfer.ts

@@ -1,10 +1,10 @@
 // Reads project files on the client side for transfer to the Host Runtime.
 // The host never sees a client path: only bytes and the file's type.
 
-import { readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
-import { extname, join, relative, sep } from "node:path";
+import { lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, statSync, writeFileSync } from "node:fs";
+import { dirname, extname, join, relative, sep } from "node:path";
 
-import { isInside, projectRoot, resolveProjectFile } from "../project.ts";
+import { isInside, projectRoot, resolveProjectFile, resolveProjectPath } from "../project.ts";
 import { MAX_ATTACHMENT_BYTES } from "../protocol/framing.ts";
 import { WireFailure } from "../protocol/messages.ts";
 import { MAX_TREE_FILES, type SourceTree } from "../protocol/tools.ts";
@@ -42,6 +42,32 @@ export function readProjectFile(path: string, options: { root?: string } = {}):
   return { bytes: readFileSync(real), type: extname(path).slice(1).toLowerCase() };
 }
 
+/**
+ * Writes bytes to a project file on the client side, making its directories
+ * and overwriting it. Throws WireFailure(invalid-input) for a path outside the
+ * project, also one that leaves it through a symbolic link.
+ */
+export function writeProjectFile(path: string, bytes: Uint8Array, options: { root?: string; what?: string } = {}): void {
+  const root = options.root ?? projectRoot();
+  const refuse = () => new WireFailure("invalid-input", `${options.what ?? path}: give a path relative to the project directory that stays inside it, not ${path}.`);
+  let file: string;
+  try {
+    file = resolveProjectPath(path, root);
+  } catch {
+    throw refuse();
+  }
+  mkdirSync(dirname(file), { recursive: true });
+  if (!isInside(realpathSync(root), realpathSync(dirname(file)))) throw refuse();
+  let link = false;
+  try {
+    link = lstatSync(file).isSymbolicLink();
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+  }
+  if (link) throw refuse();
+  writeFileSync(file, bytes);
+}
+
 /** Directories never staged: version control and the toolkit's own project state. */
 const SKIPPED_DIRECTORIES = new Set([".git", ".hg", ".svn", ".c64-re-tools"]);