@henols/c64-re-tools 2.1.2 → 2.1.3

package/src/host/vice/session.ts

@@ -13,7 +13,7 @@ import { setTimeout as sleep } from "node:timers/promises";
 
 import { formatC64Address, instructionLength } from "../../c64.ts";
 import { encodePng, type IndexedFrame } from "../../graphics.ts";
-import { instructionText, operandAddress } from "../../opcodes.ts";
+import { accessedValue, instructionText, operandAddress } from "../../opcodes.ts";
 import type { ProcessSupervisor } from "../../native/processes.ts";
 import { trace } from "../../trace.ts";
 import type { ViceSessionFactory, ViceSessionHandle } from "../server.ts";
@@ -31,7 +31,7 @@ import { decodeProgramCounter, MonitorConnectionError, MonitorError, MonitorTime
 import { decodeCia, decodeSid, decodeSprite, decodeVicii } from "./chips.ts";
 import { compareFrames, differenceImage } from "./screen.ts";
 import { isRefusal } from "../../errors.ts";
-import { checkMedia } from "../../media.ts";
+import { checkMedia, hasSignature } from "../../media.ts";
 import { launchVice, startErrorLines, type ViceMode, type ViceProcess } from "./process.ts";
 import { TextMonitorError, TextMonitorTimeoutError } from "./text-monitor.ts";
 
@@ -80,7 +80,6 @@ const WINDOW_CLOSED =
 
 /** Emulator state that a move to another VICE cannot carry. */
 /** The first bytes of every VICE snapshot file. */
-const VSF_MAGIC = Buffer.from("VICE Snapshot File\x1a", "latin1");
 const NOT_CARRIED = ["cpu history", "memory map", "profile", "keyboard input not yet typed"];
 
 /** Starts another VICE for this session; `log` also gets that launch's lines. */
@@ -202,6 +201,21 @@ export class ViceSession implements ViceSessionHandle {
   #autostarting = false;
   /** The C64 clock just after the last snapshot restore: VICE keeps the history of before it. */
   #historySince: bigint | undefined;
+  /**
+   * A breakpoint or watchpoint stopped a step, next or until-return early. VICE
+   * keeps the rest of that step and stops the machine once more when it ends.
+   * No monitor command ends it without running the CPU, so the session takes
+   * that one stop as the end of the step and lets the machine run on.
+   */
+  #pendingStep = false;
+  /**
+   * The CPU stands at the stop of a reset without run, and nothing ran since. VICE
+   * (3.9, 3.10) stops answering at the restore of a snapshot saved here while the
+   * disk drive was busy, so a save here is refused.
+   */
+  #atResetStop = false;
+  /** The CPU that the last run stopped in, when it was the drive: status then gives the drive's pc. */
+  #stopSpace: "c64" | "drive8" = "c64";
   /** VICE records no CPU history after a JAM until the next reset. */
   #historyStopped = false;
   /** The CPU ran again after a JAM without a reset: the CPU history that VICE gives is old. */
@@ -558,7 +572,7 @@ export class ViceSession implements ViceSessionHandle {
       if (stop !== undefined) Object.assign(status, stop);
       // A point in the drive stopped it: the pc is the drive's, as advance-frames and run-until give it.
       const point = status.pointId === undefined ? undefined : (status.stopReason === "watchpoint" ? this.#watchpoints : this.#breakpoints).get(status.pointId);
-      status.space = point?.space === "drive8" ? "drive8" : "c64";
+      status.space = point?.space === "drive8" || this.#stopSpace === "drive8" ? "drive8" : "c64";
       if (status.space === "drive8") status.pc = (await this.#machine.readRegisters("drive8")).pc;
     }
     return status;
@@ -572,6 +586,7 @@ export class ViceSession implements ViceSessionHandle {
       if (this.#state === "stopped") {
         await this.#refuseJammed("resume");
         await this.#resume();
+        if (this.#pendingStep) await this.#endPendingStep();
       }
       return { state: "running" };
     }
@@ -600,6 +615,7 @@ export class ViceSession implements ViceSessionHandle {
         throw new WireFailure("invalid-input", `The anchor is outside the frame: a ${this.#videoStandard} frame has lines 0-${raster.lines - 1} and cycles 0-${raster.cycles - 1}.`);
       }
       const outcome = await this.#runFrames(params.count, undefined, params.anchor);
+      this.#stopSpace = outcome.space;
       return {
         state: "stopped",
         // A stop event carries the computer's PC; a stop in the drive reports the drive's.
@@ -612,6 +628,8 @@ export class ViceSession implements ViceSessionHandle {
     }
     await this.#stop();
     await this.#refuseJammed(params.action);
+    // A new step replaces the rest of an earlier one in VICE.
+    this.#pendingStep = false;
     if (params.action === "until-return") {
       const stopped = this.#nextStop(this.#untilReturnLimitMs);
       await this.#resumingCommand(() => this.#machine.untilReturn());
@@ -623,18 +641,39 @@ export class ViceSession implements ViceSessionHandle {
           `The routine did not return within ${this.#untilReturnLimitMs / 1000} seconds. The machine is stopped at ${formatC64Address(await this.#pc())}.`,
         );
       }
-      return { state: "stopped", pc: stop.pc };
+      return { state: "stopped", pc: stop.pc, ...this.#stepStoppedByPoint() };
     }
     const count = params.count ?? 1;
+    this.#atResetStop = false;
     try {
       await this.#machine.step(count, params.action === "next", this.#stepLimitMs);
     } catch (error) {
       if (error instanceof MonitorTimeoutError) throw new StepTimeout(stepNotEnded(params.action, count, this.#stepLimitMs), error);
       throw error;
     }
-    // VICE answers a step only after the machine stopped again.
+    // VICE answers a step only after the machine stopped again; a ping reads the events of that stop (a hit point).
+    await this.#machine.stop();
     this.#state = "stopped";
-    return { state: "stopped", pc: await this.#pc(), executed: count };
+    const point = this.#stepStoppedByPoint();
+    // A point stops the step early: VICE does not tell how many instructions ran.
+    return { state: "stopped", pc: await this.#pc(), ...(point.pointId === undefined ? { executed: count } : point) };
+  }
+
+  /** The breakpoint or watchpoint that stopped a step, next or until-return early; VICE then keeps the rest of the step. */
+  #stepStoppedByPoint(): { stopReason?: PointStopReason; pointId?: number } {
+    const stop = this.#lastStop;
+    if (stop?.pointId === undefined) return {};
+    this.#pendingStep = true;
+    return { stopReason: stop.stopReason, pointId: stop.pointId };
+  }
+
+  /** After a resume: waits for the stop that ends the rest of an earlier step, and runs on. */
+  async #endPendingStep(): Promise<void> {
+    const stop = await this.#nextStop(HALF_FRAME_LIMIT_MS);
+    if (stop === undefined) return;
+    this.#pendingStep = false;
+    // A user point or a JAM stopped the machine: it stays stopped and status tells why.
+    if (stop.hits.length === 0 && this.#lastStop === undefined) await this.#resume();
   }
 
   async #reset(params: { mode: "soft" | "hard"; run: boolean }): Promise<{ state: RunState; pc?: number }> {
@@ -659,6 +698,7 @@ export class ViceSession implements ViceSessionHandle {
     if (!reached) await this.#stop();
     await this.#machine.deleteCheckpoint(checkpoint);
     if (!reached) throw new WireFailure("operation-failed", "The C64 did not reach its reset vector after the reset.");
+    this.#atResetStop = true;
     return { state: "stopped", pc: vector };
   }
 
@@ -715,6 +755,11 @@ export class ViceSession implements ViceSessionHandle {
         }
         if (end === "unknown") {
           if (await this.#jamAt(stop.pc)) return { end: "jam", frames, pc: stop.pc, space: "c64" };
+          if (this.#pendingStep) {
+            // The rest of an earlier step ended: run on.
+            this.#pendingStep = false;
+            continue;
+          }
           throw new WireFailure("operation-failed", "The emulator stopped the machine for a reason outside this run.");
         }
         // A drive stop is completed before the result names the computer's pc; `space` says which CPU stopped.
@@ -783,6 +828,10 @@ export class ViceSession implements ViceSessionHandle {
         const point = this.#userPoint(stop.hits);
         if (point !== undefined) return { hits, frames, end: point.stopReason, pc: stop.pc };
         if (await this.#jamAt(stop.pc)) return { hits, frames, end: "jam", pc: stop.pc };
+        if (this.#pendingStep) {
+          this.#pendingStep = false;
+          continue;
+        }
         throw new WireFailure("operation-failed", "The emulator stopped the machine for a reason outside this trace.");
       }
     } finally {
@@ -841,10 +890,22 @@ export class ViceSession implements ViceSessionHandle {
       frame,
       rasterLine: Math.floor(at / cycles),
       rasterCycle: at % cycles,
-      ...(address === undefined ? {} : { address, value: await byteAt(address) }),
+      ...(address === undefined ? {} : { address, ...(await this.#accessed(bytes[0]!, entry, address, byteAt)) }),
     };
   }
 
+  /**
+   * The byte of a read or write hit. A read of an I/O register after the
+   * access can give another byte than the access did (raster bits, cleared
+   * flags), so for $D000-$DFFF only a load or a store gives a value.
+   */
+  async #accessed(opcode: number, before: { a: number; x: number; y: number }, address: number, byteAt: (address: number) => Promise<number>): Promise<{ value?: number }> {
+    const after = await this.#machine.readRegisters("c64");
+    const io = address >= 0xd000 && address <= 0xdfff;
+    const value = accessedValue(opcode, before, after, io ? undefined : await byteAt(address));
+    return value === undefined ? {} : { value };
+  }
+
   /**
    * Completes a stop that a drive 8 checkpoint caused: the computer runs to
    * its next instruction boundary, where a computer checkpoint stops it, so
@@ -975,6 +1036,7 @@ export class ViceSession implements ViceSessionHandle {
       const stopReason = outcome.end === "frames" ? "timeout" : outcome.end;
       // A stop event carries the computer's PC; a stop in the drive reports the drive's.
       const pc = outcome.space === "drive8" ? (await this.#machine.readRegisters("drive8")).pc : outcome.pc;
+      this.#stopSpace = outcome.space;
       return { reached: stopReason === "target", stopReason, state: "stopped", pc, space: outcome.space, ...(outcome.pointId === undefined ? {} : { pointId: outcome.pointId }) };
     } finally {
       await this.#machine.deleteCheckpoint(checkpoint);
@@ -1030,7 +1092,10 @@ export class ViceSession implements ViceSessionHandle {
 
   #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}.`);
+    if (point === undefined) {
+      const other = kind === "breakpoint" ? (this.#watchpoints.has(id) ? "watchpoint" : undefined) : this.#breakpoints.has(id) ? "breakpoint" : undefined;
+      throw new WireFailure("not-found", `There is no ${kind} with id ${id}.${other === undefined ? "" : ` Id ${id} is a ${other}: use c64_${other}.`}`);
+    }
     return point;
   }
 
@@ -1145,7 +1210,11 @@ export class ViceSession implements ViceSessionHandle {
     }
     return this.#observe(async () => {
       const all = await this.#machine.history(params.limit, params.space);
-      if (params.space === "drive8") return { entries: all.map(({ clock: _clock, ...entry }) => entry) };
+      if (params.space === "drive8") {
+        // VICE records a wrong third byte for a 3-byte drive instruction ("JSR $00a6" for 20 a6 d5): the drive memory gives the bytes.
+        const memory = await this.#machine.readAll("drive8");
+        return { entries: all.map(({ clock: _clock, ...entry }) => driveEntry(entry, memory)) };
+      }
       const now = await this.#machine.clock();
       const raw = entriesSince(all, this.#historySince, now);
       const position = await this.#machine.rasterPosition();
@@ -1221,6 +1290,13 @@ export class ViceSession implements ViceSessionHandle {
     if (params.action === "list") return { snapshots: [...this.#snapshots.keys()] };
     const existing = this.#snapshots.get(params.name);
     if (params.action === "save") {
+      if (this.#atResetStop) {
+        throw new WireFailure(
+          "operation-failed",
+          "The CPU stands at the reset stop of c64_reset with run false. The emulator stops answering at the restore of a snapshot saved here when the disk drive was busy. " +
+            "Step one instruction with c64_execution, then save the snapshot.",
+        );
+      }
       if (existing === undefined && this.#snapshots.size >= MAX_SNAPSHOTS) {
         throw new WireFailure("limit-exceeded", `A session keeps at most ${MAX_SNAPSHOTS} snapshots. Remove one first with action remove.`);
       }
@@ -1266,7 +1342,7 @@ export class ViceSession implements ViceSessionHandle {
     }
     const bytes = onlyAttachment(attachments);
     // Checked before the machine stops: VICE gives no reason for a file that is no snapshot.
-    if (!bytes.subarray(0, VSF_MAGIC.length).equals(VSF_MAGIC)) throw new WireFailure("invalid-input", "The file is not a VICE snapshot file (.vsf). Give a file that c64_snapshot save wrote.");
+    if (!hasSignature("vsf", bytes)) throw new WireFailure("invalid-input", "The file is not a VICE snapshot file (.vsf). Give a file that c64_snapshot save wrote.");
     const file = this.#stage(bytes, "vsf");
     // VICE resets the machine after a snapshot file that it cannot read: a backup keeps the state before the restore.
     const backup = join(this.#workDir, "before-restore.vsf");
@@ -1452,6 +1528,8 @@ export class ViceSession implements ViceSessionHandle {
    * arrive together, and those events must have the last word.
    */
   async #resumingCommand(send: () => Promise<void>): Promise<void> {
+    this.#atResetStop = false;
+    this.#stopSpace = "c64";
     this.#state = "running";
     this.#lastStop = undefined;
     try {
@@ -1643,6 +1721,15 @@ export class ViceSession implements ViceSessionHandle {
   }
 }
 
+/** A drive history entry with its bytes and text from drive memory, when the opcode there is still the one that ran. */
+export function driveEntry<T extends { address: number; bytes: string; text: string }>(entry: T, memory: Uint8Array): T {
+  const opcode = Number.parseInt(entry.bytes.slice(0, 2), 16);
+  if (memory[entry.address] !== opcode) return entry;
+  const length = instructionLength(opcode);
+  const bytes = Array.from({ length }, (_, offset) => memory[(entry.address + offset) & 0xffff]!);
+  return { ...entry, bytes: Buffer.from(bytes).toString("hex"), text: instructionText(bytes, entry.address) };
+}
+
 /**
  * The history entries (oldest first) that the CPU executed after a restore at
  * clock `since`, with the clock at `now`: the last entries, back to the first

package/src/host-client/image.ts

@@ -36,20 +36,34 @@ const MEDIA_KINDS: Record<string, string> = {
 /** The remedy for a disk, tape or cartridge file where a PRG must be: get the PRG out of it. */
 export const MEDIA_REMEDY = "Get the PRG out of it with disk.ts read (or disk.ts crt for a cartridge) of the c64-disk skill";
 
-/** Refuses a disk, tape or cartridge file by its extension (`type`, lowercase, without the dot): invalid-input with `remedy`. */
-function refuseMedia(path: string, type: string, remedy: string): void {
+/**
+ * Refuses a file that is no PRG by its extension (`type`, lowercase, without
+ * the dot): invalid-input. A disk, tape or cartridge file gets `remedy`. A PRG
+ * ends in .prg in any letter case, or has no extension, as c1541 writes the
+ * names of the files that it reads from a disk; every other extension is
+ * refused. `accepted` names what the reader takes, for the message.
+ */
+export function refuseNotPrg(path: string, type: string, remedy = MEDIA_REMEDY, accepted = "a PRG"): void {
   const media = MEDIA_KINDS[type];
   if (media !== undefined) throw new Refusal("invalid-input", `${path} is ${media} (.${type}), not a PRG. ${remedy}.`);
+  if (type !== "prg" && type !== "") {
+    throw new Refusal("invalid-input", `${path} is not ${accepted}: a PRG has the extension .prg or no extension, not .${type}. Give the PRG of the program, or rename the file to .prg when it is a PRG.`);
+  }
 }
 
 /**
  * Reads a PRG of the project: a 2-byte load address, and bytes that end at
- * $ffff or before. Refuses a disk, tape or cartridge file and any other file
- * that is no PRG with invalid-input; `remedy` tells what to do in its place.
+ * $ffff or before. Refuses with invalid-input a file that is no PRG by its
+ * extension (refuseNotPrg) or by its bytes; `remedy` tells what to do in place
+ * of a disk, tape or cartridge file. A file of fewer than 3 bytes is refused
+ * as too short: no remedy applies.
  */
-export function readPrg(path: string, remedy = MEDIA_REMEDY): { bytes: Buffer; start: number; end: number; body: Uint8Array } {
+export function readPrg(path: string, remedy = MEDIA_REMEDY, accepted = "a PRG"): { bytes: Buffer; start: number; end: number; body: Uint8Array } {
   const { bytes, type } = readProjectFile(path);
-  refuseMedia(path, type, remedy);
+  refuseNotPrg(path, type, remedy, accepted);
+  if (bytes.length < 3) {
+    throw new Refusal("invalid-input", `${path} is too short for a PRG: it has ${bytes.length} ${bytes.length === 1 ? "byte" : "bytes"}, and a PRG has a 2-byte load address and at least one byte. Give the complete PRG file.`);
+  }
   try {
     return { bytes, ...prgRange(bytes) };
   } catch (error) {
@@ -58,10 +72,10 @@ export function readPrg(path: string, remedy = MEDIA_REMEDY): { bytes: Buffer; s
   }
 }
 
-/** Reads an image.json or a PRG, relative to the project folder. Refuses a disk, tape or cartridge file as readPrg does. */
+/** Reads an image.json or a PRG, relative to the project folder. Refuses every other file as readPrg does. */
 export function readImage(path: string): Image {
   if (!path.endsWith(".json")) {
-    const range = readPrg(path);
+    const range = readPrg(path, MEDIA_REMEDY, "an image.json of the c64-unpacker skill or a PRG");
     return { segments: [{ start: range.start, end: range.end }], byteAt: (address) => range.body[address - range.start]! };
   }
   const { bytes } = readProjectFile(path);

package/src/host-client/steps.ts

@@ -228,8 +228,8 @@ function checkTarget(value: unknown, where: string, fail: (message: string) => n
   return fail(`${where}.kind must be one of address, memory, raster`);
 }
 
-/** What a step of a script without the replay core gets for press. */
-const PRESS_REMEDY = "press pushes keys of the keyboard matrix, and only the record and replay commands of c64-testing have them. Use type for the KERNAL keyboard queue, or open the window and ask the user to press the key";
+/** What a step of a script without the replay core gets for press: the scripts that read these steps run without a window. */
+const PRESS_REMEDY = "press pushes keys of the keyboard matrix, and only the replay core of c64-testing has them. Use type for the KERNAL keyboard queue, or put the press step in a record file and play it with testing.ts record of c64-testing";
 
 /** Checks the input of one step kind and returns it with the defaults of its MCP tool. */
 function checkInput(kind: ActionStepKind, value: unknown, at: string, fail: (message: string) => never): ActionStep {

package/src/host-client/tools.ts

@@ -6,6 +6,7 @@
 import { ProtocolError, WireFailure } from "../protocol/messages.ts";
 import { DISK_IMAGE_TYPES, validateToolResult, type C1541Result, type DiskAction, type DiskImageType, type PetcatResult, type ToolOperation, type ToolOperations, type HostInfo, type ToolStatus } from "../protocol/tools.ts";
 import { HostConnection } from "./connect.ts";
+import { readPrg } from "./image.ts";
 import { readProjectFile } from "./transfer.ts";
 
 export interface ToolCallOptions {
@@ -72,10 +73,10 @@ export async function inspectDisk(request: InspectDiskRequest, options: ToolCall
   return result.action === "read" && result.found ? { ...result, data: attachments[0]! } : result;
 }
 
-/** petcat.decode: the C64 BASIC V2 listing of a project program and its machine-code handoffs. */
+/** petcat.decode: the C64 BASIC V2 listing of a project program and its machine-code handoffs. Refuses a file that is no PRG as readPrg does. */
 export async function decodeBasic(request: { program: string }, options: ToolCallOptions = {}): Promise<PetcatResult> {
-  const file = readProjectFile(request.program);
-  return (await callTool("petcat.decode", {}, [file.bytes], options)).result;
+  const { bytes } = readPrg(request.program);
+  return (await callTool("petcat.decode", {}, [bytes], options)).result;
 }
 
 /** host.status: the Host Runtime, and each native tool on the host, found and run once. */

package/src/host-client/transfer.ts

@@ -20,6 +20,11 @@ export function projectFolder(project: string | undefined): string {
   return resolveProject(project, process.cwd(), { remedy: "Give project: <folder>" });
 }
 
+/** Refuses an MCP `out` before the tool does any work, with the checks that every --out of a script gets. */
+export function checkOut(path: string, project: string | undefined): void {
+  checkOutputPath(path, "file", { root: projectFolder(project), what: "out" });
+}
+
 /** The project folder of this process (--project or the project lookup), or a WireFailure. */
 function currentProject(): string {
   return projectRoot();
@@ -36,17 +41,17 @@ export interface ProjectFile {
  * project rules refuse, not-found when nothing is there, limit-exceeded when
  * the file is too large to transfer.
  */
-export function readProjectFile(path: string, options: { root?: string } = {}): ProjectFile {
+export function readProjectFile(path: string, options: { root?: string; what?: string } = {}): ProjectFile {
   const root = options.root ?? currentProject();
   let real: string;
   try {
     real = resolveProjectFile(path, root);
   } catch (error) {
     if ((error as NodeJS.ErrnoException).code === "ENOENT") {
-      throw new WireFailure("not-found", `There is no file at ${path} in the project folder.`);
+      throw new WireFailure("not-found", `${options.what === undefined ? "" : `${options.what}: `}There is no file at ${path} in the project folder.`);
     }
     if (isRefusal(error) && error.code === "invalid-input") {
-      throw new WireFailure("invalid-input", `${path}: give a path relative to the project folder that stays inside it.`);
+      throw new WireFailure("invalid-input", `${options.what ?? path}: give a path relative to the project folder that stays inside it, not ${path}.`);
     }
     throw error;
   }