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

package/src/host-client/steps.ts

@@ -1,133 +1,302 @@
-// The action steps of the step language: 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.
+// The action steps of the scripts. A step is { "<kind>": <input> }, and the
+// input has the fields, ranges and defaults of the MCP tool that does the same:
+//
+//   write     c64_memory_write   { address, data, space?, view? }
+//   registers c64_registers      the values of action write: { pc?, a?, x?, y?, sp?, flags? }
+//   joystick  c64_joystick       { port, direction, fire? }
+//   type      c64_keyboard       { mode: "text", text } or { mode: "petscii", bytes }: the KERNAL keyboard queue
+//   frames    c64_execution      the count of advance-frames
+//   runUntil  c64_run_until      { target, timeoutFrames? }
+//   press     (no tool)          keys of the keyboard matrix; only the replay core of c64-testing record and replay has them
+//
+// An address in a step is $ and 1 to 4 hex digits, or a name that the script resolves.
+// The scripts install without packages, so this checker has no zod: the MCP
+// tools keep their zod schemas, and a test checks that both take the same inputs.
 
-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 { c64AddressOf, SYMBOL_NAME, textToPetscii } from "../c64.ts";
+import { isRefusal, Refusal } from "../errors.ts";
+import {
+  COMPARISONS,
+  CONDITION_REGISTERS,
+  JOYSTICK_DIRECTIONS,
+  MAX_EXECUTION_COUNT,
+  MAX_KEYBOARD_BYTES,
+  MAX_MEMORY_WRITE,
+  MAX_TIMEOUT_FRAMES,
+  MEMORY_VIEWS,
+  SPACES,
+  type Condition,
+  type RunTarget,
+  type RunUntilResult,
+} from "../protocol/vice.ts";
+import { readProjectFile } from "./transfer.ts";
 import type { ViceSessionClient } from "./vice-session.ts";
 
-/** A "$xxxx" address, or a symbol name where the caller resolves names. */
+/** A "$xxxx" address or a name, which the caller resolves. */
 export type Location = string;
 
-type JoystickDirection = (typeof JOYSTICK_DIRECTIONS)[number];
+type Space = (typeof SPACES)[number];
+type View = (typeof MEMORY_VIEWS)[number];
+type Comparison = (typeof COMPARISONS)[number];
+type Flags = Partial<Record<"n" | "v" | "b" | "d" | "i" | "z" | "c", boolean>>;
+
+export type StepCondition =
+  | { kind: "register"; register: (typeof CONDITION_REGISTERS)[number]; operator: Comparison; value: number }
+  | { kind: "memory"; address: Location; operator: Comparison; value: number; space: Space; view: View }
+  | { kind: "raster"; line: number; cycle?: number };
+
+export type StepTarget =
+  | { kind: "address"; address: Location; space: Space; condition?: StepCondition }
+  | { kind: "memory"; address: Location; operator: Comparison; value: number; space: Space; view: View }
+  | { kind: "raster"; line: number; cycle?: number };
+
+export type KeyboardInput = { mode: "text"; text: string } | { mode: "petscii"; bytes: 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 }
+  | { write: { address: Location; data: string; space: Space; view: View } }
+  | { registers: { pc?: Location; a?: number; x?: number; y?: number; sp?: number; flags?: Flags } }
+  | { joystick: { port: 1 | 2; direction: (typeof JOYSTICK_DIRECTIONS)[number]; fire: boolean } }
+  | { type: KeyboardInput }
+  | { press: string }
   | { frames: number }
-  | { runUntil: { at: Location; raster?: number } | { raster: number } | { memory: { at: Location; equals: number } }; timeoutFrames: number };
+  | { runUntil: { target: StepTarget; 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", "press", "frames", "runUntil"] as const;
+export type ActionStepKind = (typeof ACTION_STEP_KINDS)[number];
 
-export const ACTION_STEP_KINDS = ["write", "registers", "joystick", "type", "frames", "runUntil"] as const;
+/** The fields of each object of the steps: the same as the inputs of the MCP tools. */
+export const STEP_FIELDS = {
+  write: ["address", "data", "space", "view"],
+  registers: ["pc", "a", "x", "y", "sp", "flags"],
+  joystick: ["port", "direction", "fire"],
+  type: ["mode", "text", "bytes"],
+  runUntil: ["target", "timeoutFrames"],
+  addressTarget: ["kind", "address", "space", "condition"],
+  memoryTarget: ["kind", "address", "operator", "value", "space", "view"],
+  rasterTarget: ["kind", "line", "cycle"],
+  registerCondition: ["kind", "register", "operator", "value"],
+  memoryCondition: ["kind", "address", "operator", "value", "space", "view"],
+  rasterCondition: ["kind", "line", "cycle"],
+  flags: ["n", "v", "b", "d", "i", "z", "c"],
+} 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"];
+/** The highest raster line of a PAL frame; an NTSC frame has fewer, which the emulator checks. */
+export const MAX_RASTER_LINE = 311;
+/** The wait of a runUntil step without timeoutFrames, as c64_run_until has it. */
+export const DEFAULT_TIMEOUT_FRAMES = 3000;
 
 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;
+const isOneOf = <T extends string>(values: readonly T[], value: unknown): value is T => (values as readonly unknown[]).includes(value);
 
-/** 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}`);
+/** True for an address of a step or a file: $ and 1 to 4 hex digits, or a name. */
+export function isLocation(value: unknown): value is Location {
+  return typeof value === "string" && (c64AddressOf(value) !== undefined || SYMBOL_NAME.test(value));
+}
+
+/** Checks an address in a file: $ and 1 to 4 hex digits, or a name. */
+export function checkLocation(value: unknown, what: string, fail: (message: string) => never): void {
+  if (!isLocation(value)) fail(`${what} must be $ and 1 to 4 hex digits, for example $c000 or $fb, or a name`);
+}
+
+/** The PETSCII bytes of a keyboard input, or why the text has no keys. */
+export function keyboardBytes(input: { mode: "text" | "petscii"; text?: string | undefined; bytes?: number[] | undefined }): Uint8Array | string {
+  if (input.mode === "petscii") return Uint8Array.from(input.bytes ?? []);
+  try {
+    return textToPetscii(input.text ?? "");
+  } catch (error) {
+    if (isRefusal(error)) return `${error.message}. Use mode petscii for other keys`;
+    throw error;
   }
 }
 
-/** 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 {
+/** The checks of one input: `fail` names the field of the problem. */
+class Fields {
+  readonly #value: Record<string, unknown>;
+  readonly #where: string;
+  readonly #fail: (message: string) => never;
+
+  constructor(value: unknown, where: string, fields: readonly string[], fail: (message: string) => never) {
+    this.#where = where;
+    this.#fail = fail;
+    if (!isObject(value)) fail(`${where} must be an object with ${fields.join(", ")}`);
+    this.#value = value as Record<string, unknown>;
+    for (const key of Object.keys(this.#value)) if (!fields.includes(key)) fail(`${where} has the field ${key}, which it does not take. Its fields are ${fields.join(", ")}`);
+  }
+
+  fail(field: string, message: string): never {
+    return this.#fail(`${this.#where}.${field} ${message}`);
+  }
+
+  has(field: string): boolean {
+    return this.#value[field] !== undefined;
+  }
+
+  get(field: string): unknown {
+    return this.#value[field];
+  }
+
+  location(field: string): Location {
+    const value = this.#value[field];
+    if (!isLocation(value)) return this.fail(field, "must be $ and 1 to 4 hex digits, for example $c000 or $fb, or a name");
+    return value;
+  }
+
+  integer(field: string, min: number, max: number, fallback?: number): number {
+    const value = this.#value[field] ?? fallback;
+    if (!isInteger(value, min, max)) return this.fail(field, `must be a whole number from ${min} to ${max}`);
+    return value;
+  }
+
+  oneOf<T extends string>(field: string, values: readonly T[], fallback?: T): T {
+    const value = this.#value[field] ?? fallback;
+    if (!isOneOf(values, value)) return this.fail(field, `must be one of ${values.join(", ")}`);
+    return value;
+  }
+
+  boolean(field: string, fallback?: boolean): boolean {
+    const value = this.#value[field] ?? fallback;
+    if (typeof value !== "boolean") return this.fail(field, "must be true or false");
+    return value;
+  }
+}
+
+function checkCondition(value: unknown, where: string, fail: (message: string) => never): StepCondition {
+  const kind = isObject(value) ? value.kind : undefined;
+  if (kind === "register") {
+    const fields = new Fields(value, where, STEP_FIELDS.registerCondition, fail);
+    return { kind, register: fields.oneOf("register", CONDITION_REGISTERS), operator: fields.oneOf("operator", COMPARISONS), value: fields.integer("value", 0, 0xff) };
+  }
+  if (kind === "memory") {
+    const fields = new Fields(value, where, STEP_FIELDS.memoryCondition, fail);
+    return { kind, address: fields.location("address"), operator: fields.oneOf("operator", COMPARISONS), value: fields.integer("value", 0, 0xff), space: fields.oneOf("space", SPACES, "c64"), view: fields.oneOf("view", MEMORY_VIEWS, "cpu") };
+  }
+  if (kind === "raster") return raster(new Fields(value, where, STEP_FIELDS.rasterCondition, fail));
+  return fail(`${where}.kind must be one of register, memory, raster`);
+}
+
+function raster(fields: Fields): { kind: "raster"; line: number; cycle?: number } {
+  const line = fields.integer("line", 0, MAX_RASTER_LINE);
+  return fields.has("cycle") ? { kind: "raster", line, cycle: fields.integer("cycle", 0, 64) } : { kind: "raster", line };
+}
+
+function checkTarget(value: unknown, where: string, fail: (message: string) => never): StepTarget {
+  const kind = isObject(value) ? value.kind : undefined;
+  if (kind === "address") {
+    const fields = new Fields(value, where, STEP_FIELDS.addressTarget, fail);
+    const target: StepTarget = { kind, address: fields.location("address"), space: fields.oneOf("space", SPACES, "c64") };
+    if (fields.has("condition")) target.condition = checkCondition(fields.get("condition"), `${where}.condition`, fail);
+    return target;
+  }
+  if (kind === "memory") {
+    const fields = new Fields(value, where, STEP_FIELDS.memoryTarget, fail);
+    return { kind, address: fields.location("address"), operator: fields.oneOf("operator", COMPARISONS), value: fields.integer("value", 0, 0xff), space: fields.oneOf("space", SPACES, "c64"), view: fields.oneOf("view", MEMORY_VIEWS, "cpu") };
+  }
+  if (kind === "raster") return raster(new Fields(value, where, STEP_FIELDS.rasterTarget, fail));
+  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";
+
+/** 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 {
+  const where = `${at}: ${kind}`;
   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;
+      const fields = new Fields(value, where, STEP_FIELDS.write, fail);
+      const data = fields.get("data");
+      if (typeof data !== "string" || !/^(?:[0-9a-fA-F]{2})+$/.test(data)) fields.fail("data", "must be hex bytes, two digits per byte, no separators, for example a9008d20d0");
+      if ((data as string).length / 2 > MAX_MEMORY_WRITE) fields.fail("data", `has at most ${MAX_MEMORY_WRITE} bytes`);
+      return { write: { address: fields.location("address"), data: (data as string).toLowerCase(), space: fields.oneOf("space", SPACES, "c64"), view: fields.oneOf("view", MEMORY_VIEWS, "cpu") } };
     }
     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}`);
+      const fields = new Fields(value, where, STEP_FIELDS.registers, fail);
+      const registers: Extract<ActionStep, { registers: unknown }>["registers"] = {};
+      if (fields.has("pc")) registers.pc = fields.location("pc");
+      for (const name of ["a", "x", "y", "sp"] as const) if (fields.has(name)) registers[name] = fields.integer(name, 0, 0xff);
+      if (fields.has("flags")) {
+        const flags = new Fields(fields.get("flags"), `${where}.flags`, STEP_FIELDS.flags, fail);
+        registers.flags = Object.fromEntries(STEP_FIELDS.flags.filter((name) => flags.has(name)).map((name) => [name, flags.boolean(name)]));
       }
-      return;
+      if (Object.entries(registers).every(([name, item]) => name === "flags" && Object.keys(item as object).length === 0)) fail(`${where} must name at least one register`);
+      return { registers };
     }
     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;
+      const fields = new Fields(value, where, STEP_FIELDS.joystick, fail);
+      return { joystick: { port: fields.integer("port", 1, 2) as 1 | 2, direction: fields.oneOf("direction", JOYSTICK_DIRECTIONS), fire: fields.boolean("fire", false) } };
     }
     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}`);
+      const fields = new Fields(value, where, STEP_FIELDS.type, fail);
+      const mode = fields.oneOf("mode", ["text", "petscii"] as const);
+      let input: KeyboardInput;
+      if (mode === "text") {
+        if (typeof fields.get("text") !== "string" || fields.get("text") === "" || fields.has("bytes")) fail(`${where}: mode text takes text and no bytes`);
+        input = { mode, text: fields.get("text") as string };
+      } else {
+        const bytes = fields.get("bytes");
+        if (!Array.isArray(bytes) || bytes.length === 0 || !bytes.every((byte) => isInteger(byte, 1, 255)) || fields.has("text")) fail(`${where}: mode petscii takes bytes, a list of PETSCII codes from 1 to 255, and no text`);
+        input = { mode, bytes: bytes as number[] };
       }
-      if (bytes.length > MAX_KEYBOARD_BYTES) fail(`${at}: type can have at most ${MAX_KEYBOARD_BYTES} keys`);
-      return;
+      const keys = keyboardBytes(input);
+      if (typeof keys === "string") fail(`${where}.text: ${keys}`);
+      else if (keys.length > MAX_KEYBOARD_BYTES) fail(`${where}: the keyboard queue takes at most ${MAX_KEYBOARD_BYTES} keys at once. This input has ${keys.length} keys`);
+      return { type: input };
     }
+    case "press":
+      if (typeof value !== "string" || value === "") fail(`${where} needs the keys to press as text`);
+      return { press: value as string };
     case "frames":
-      if (!isInteger(step.frames, 1, MAX_TIMEOUT_FRAMES)) fail(`${at} needs a frame count from 1 to ${MAX_TIMEOUT_FRAMES}`);
-      return;
+      if (!isInteger(value, 1, MAX_TIMEOUT_FRAMES)) fail(`${where} must be a frame count from 1 to ${MAX_TIMEOUT_FRAMES}`);
+      return { frames: value as number };
     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), 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;
+      const fields = new Fields(value, where, STEP_FIELDS.runUntil, fail);
+      return { runUntil: { target: checkTarget(fields.get("target"), `${where}.target`, fail), timeoutFrames: fields.integer("timeoutFrames", 1, MAX_TIMEOUT_FRAMES, DEFAULT_TIMEOUT_FRAMES) } };
     }
-    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[] {
+/**
+ * Checks one action step of the given kind and returns it with the defaults
+ * filled in. The step has no other key. `press` is refused unless the caller
+ * runs the steps on the replay core.
+ */
+export function checkActionStep(kind: ActionStepKind, step: Record<string, unknown>, at: string, fail: (message: string) => never, options: { press?: boolean } = {}): ActionStep {
+  for (const key of Object.keys(step)) if (key !== kind) fail(`${at} has the key ${key}, which a ${kind} step does not have`);
+  if (kind === "press" && options.press !== true) fail(`${at}: ${PRESS_REMEDY}`);
+  return checkInput(kind, step[kind], at, fail);
+}
+
+/** The kind of a step: its one key from `kinds`. */
+export function stepKind<K extends string>(step: unknown, kinds: readonly K[], at: string, fail: (message: string) => never): K {
+  if (!isObject(step)) return fail(`${at} must be an object`);
+  const found = Object.keys(step).filter((key) => (kinds as readonly string[]).includes(key));
+  if (found.length !== 1) return fail(`${at} must have exactly one of ${kinds.join(", ")}`);
+  return found[0] as K;
+}
+
+/** Checks a list of action steps and returns them with the defaults filled in. */
+export function checkActionSteps(value: unknown, fail: (message: string) => never, options: { press?: boolean } = {}): 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) => {
+  return value.map((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 checkActionStep(stepKind(step, ACTION_STEP_KINDS, at, fail), step as Record<string, unknown>, at, fail, options);
   });
-  return value as ActionStep[];
+}
+
+/** Reads a steps file of the project: a JSON list of action steps. `option` names the option of the file in a refusal. */
+export function readActionSteps(path: string, option: string): ActionStep[] {
+  const fail = (message: string): never => {
+    throw new Refusal("invalid-input", `${option} ${path}: ${message}`);
+  };
+  let value: unknown;
+  try {
+    value = JSON.parse(readProjectFile(path).bytes.toString("utf8"));
+  } catch (error) {
+    if (error instanceof SyntaxError) return fail(`it is not JSON: ${error.message}`);
+    throw error;
+  }
+  return checkActionSteps(value, fail);
 }
 
 /** Stops the CPU when it runs: a write, a register change or an exact frame count needs it stopped. */
@@ -135,23 +304,38 @@ async function stop(client: ViceSessionClient): Promise<void> {
   if ((await client.status()).state === "running") await client.execution({ action: "pause", space: "c64" });
 }
 
+/** A run target of a step with its addresses resolved. */
+export function resolveTarget(target: StepTarget, at: (location: Location) => number): RunTarget {
+  if (target.kind === "raster") return target.cycle === undefined ? { kind: "raster", line: target.line } : { kind: "raster", line: target.line, cycle: target.cycle };
+  if (target.kind === "memory") return { ...target, address: at(target.address) };
+  const { condition } = target;
+  return {
+    kind: "address",
+    address: at(target.address),
+    space: target.space,
+    ...(condition === undefined ? {} : { condition: (condition.kind === "memory" ? { ...condition, address: at(condition.address) } : condition) as Condition }),
+  };
+}
+
 /**
- * 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.
+ * Runs one action step in VICE. `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" });
+    await client.memoryWrite({ ...step.write, address: at(step.write.address) });
   } 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);
+    const { pc, flags, ...bytes } = step.registers;
+    await client.registersSet("c64", { ...bytes, ...(pc === undefined ? {} : { pc: at(pc) }), ...(flags === undefined || Object.keys(flags).length === 0 ? {} : { flags }) });
   } else if ("joystick" in step) {
-    await client.joystick({ port: step.joystick.port, direction: step.joystick.direction, fire: step.joystick.fire ?? false });
+    await client.joystick(step.joystick);
   } else if ("type" in step) {
-    await client.keyboard(textToPetscii(step.type));
+    await client.keyboard(keyboardBytes(step.type) as Uint8Array);
+  } else if ("press" in step) {
+    throw new Refusal("invalid-input", PRESS_REMEDY);
   } else if ("frames" in step) {
     await stop(client);
     // One advance-frames runs at most MAX_EXECUTION_COUNT frames. Each part ends at the raster position
@@ -161,14 +345,7 @@ export async function runActionStep(client: ViceSessionClient, step: ActionStep,
       if (part.stopReason !== "frames") break;
     }
   } 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 });
+    const reached = await client.runUntil({ target: resolveTarget(step.runUntil.target, at), timeoutFrames: step.runUntil.timeoutFrames });
     if (!reached.reached) return reached;
   }
   return undefined;

package/src/host-client/transfer.ts

@@ -1,36 +1,28 @@
 // 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 { createHash } from "node:crypto";
 import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, statSync, writeFileSync } from "node:fs";
 import { dirname, extname, join, relative, sep } from "node:path";
 
-import { isInside, ProjectError, projectRoot, resolveProject, resolveProjectFile, resolveProjectPath } from "../project.ts";
+import { isInside, projectRoot, resolveProject, resolveProjectFile, resolveProjectPath } from "../project.ts";
+import { isRefusal } from "../errors.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";
 
-/** Runs a project lookup and gives a refusal of the project rules as a WireFailure with the same code and message. */
-function asWireFailure<T>(lookup: () => T): T {
-  try {
-    return lookup();
-  } catch (error) {
-    if (error instanceof ProjectError) throw new WireFailure(error.code, error.message);
-    throw error;
-  }
-}
-
 /**
  * The project folder of a call that names it with `project` (relative to the
  * working directory) or not. Throws WireFailure when the rules
  * refuse it, for example at a folder with several projects below it.
  */
 export function projectFolder(project: string | undefined): string {
-  return asWireFailure(() => resolveProject(project, process.cwd(), { remedy: "Give project: <folder>" }));
+  return resolveProject(project, process.cwd(), { remedy: "Give project: <folder>" });
 }
 
 /** The project folder of this process (--project or the project lookup), or a WireFailure. */
 function currentProject(): string {
-  return asWireFailure(projectRoot);
+  return projectRoot();
 }
 
 export interface ProjectFile {
@@ -53,7 +45,7 @@ export function readProjectFile(path: string, options: { root?: string } = {}):
     if ((error as NodeJS.ErrnoException).code === "ENOENT") {
       throw new WireFailure("not-found", `There is no file at ${path} in the project folder.`);
     }
-    if (error instanceof TypeError) {
+    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 error;
@@ -99,6 +91,20 @@ export function writeProjectFile(path: string, bytes: Uint8Array, options: { roo
 /** Directories never staged: version control and the toolkit's own project state. */
 const SKIPPED_DIRECTORIES = new Set([".git", ".hg", ".svn", ".c64-re-tools"]);
 
+/** What a result says of a file that it wrote: the path, the size and the SHA-256. The MCP tools and the scripts report a written file in this form. */
+export interface Written {
+  out: string;
+  bytes: number;
+  sha256: string;
+}
+
+/** Writes the bytes to a project file as writeProjectFile does, and reports the file. */
+export function writeReported(path: string, data: Uint8Array | string, options: { root?: string; what?: string } = {}): Written {
+  const bytes = typeof data === "string" ? Buffer.from(data, "utf8") : data;
+  writeProjectFile(path, bytes, options);
+  return { out: path, bytes: bytes.length, sha256: createHash("sha256").update(bytes).digest("hex") };
+}
+
 /**
  * Reads a project folder as a source tree for staging: ordinary
  * files with relative POSIX paths. A symbolic link is followed only when its
@@ -111,7 +117,7 @@ export function readProjectTree(path: string, options: { root?: string } = {}):
     sourceRoot = resolveProjectFile(path, projectRootPath);
   } catch (error) {
     if ((error as NodeJS.ErrnoException).code === "ENOENT") throw new WireFailure("not-found", `There is no directory ${path} in the project folder.`);
-    if (error instanceof TypeError) throw new WireFailure("invalid-input", `${path}: give a directory relative to the project folder that stays inside it.`);
+    if (isRefusal(error) && error.code === "invalid-input") throw new WireFailure("invalid-input", `${path}: give a directory relative to the project folder that stays inside it.`);
     throw error;
   }
   if (!statSync(sourceRoot).isDirectory()) throw new WireFailure("invalid-input", `${path} is not a directory.`);

package/src/host-client/vice-session.ts

@@ -255,7 +255,7 @@ export class ViceSessionClient {
     return this.#request("screenBaselines", {});
   }
 
-  screenDiscard(baseline: string): Promise<{ discarded: boolean }> {
+  screenDiscard(baseline: string): Promise<{ removed: boolean }> {
     return this.#request("screenDiscard", { baseline });
   }
 

package/src/knowledge/database.ts

@@ -6,6 +6,7 @@ import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { DatabaseSync } from "node:sqlite";
 import { join } from "node:path";
 
+import { Refusal } from "../errors.ts";
 import { ensureLocal, LOCAL_DIRECTORY, PROJECT_DIRECTORY, projectRoot } from "../project.ts";
 import { ensureSchema } from "./schema.ts";
 import { compareText, loadText, readText, REVISIONS_FILE, revisionsText, sha256, sqlName, TABLES, tableText, writeAtomic } from "./text.ts";
@@ -19,27 +20,6 @@ export const INDEX_FILE = "knowledge.db";
 // eol=lf: with core.autocrlf (the Windows default) git would check the files out with CRLF, so two computers would hold other bytes.
 export const GIT_ATTRIBUTES = "# The knowledge of c64-re-tools: git keeps the lines of both sides of a merge, with LF line ends on every system.\n*.jsonl merge=union text eol=lf\n.gitattributes text eol=lf\n";
 
-export const KNOWLEDGE_ERROR_CODES = [
-  "invalid-input",
-  "not-found",
-  "conflict",
-  "stale-revision",
-  "invalid-database",
-  "unsupported-schema",
-] as const;
-export type KnowledgeErrorCode = (typeof KNOWLEDGE_ERROR_CODES)[number];
-
-/** A refused knowledge operation, with a stable code and an actionable message. */
-export class KnowledgeError extends Error {
-  override name = "KnowledgeError";
-  readonly code: KnowledgeErrorCode;
-
-  constructor(code: KnowledgeErrorCode, message: string) {
-    super(message);
-    this.code = code;
-  }
-}
-
 /** The folder of the knowledge text: .c64-re-tools/knowledge/. */
 export function textPath(root: string = projectRoot()): string {
   return join(root, KNOWLEDGE_DIRECTORY, TEXT_DIRECTORY);
@@ -53,7 +33,7 @@ export function indexPath(root: string = projectRoot()): string {
 /** Refuses a project that has only the knowledge.db of an older c64-re-tools. */
 function refuseOldLayout(root: string): void {
   if (!existsSync(textPath(root)) && existsSync(join(root, KNOWLEDGE_DIRECTORY, INDEX_FILE))) {
-    throw new KnowledgeError(
+    throw new Refusal(
       "unsupported-schema",
       `${KNOWLEDGE_DIRECTORY}/${INDEX_FILE} is the knowledge of an older c64-re-tools. This c64-re-tools keeps the knowledge as text in ${KNOWLEDGE_DIRECTORY}/${TEXT_DIRECTORY}/. Convert it one time with distribution/convert-knowledge.ts of the c64-re-tools source repository.`,
     );
@@ -71,7 +51,7 @@ function open(path: string, readOnly: boolean): DatabaseSync {
     configure(db);
     db.prepare("SELECT count(*) FROM sqlite_master").get();
   } catch (error) {
-    throw new KnowledgeError("invalid-database", `${KNOWLEDGE_DIRECTORY}/${LOCAL_DIRECTORY}/${INDEX_FILE} is not a readable SQLite database: ${(error as Error).message} Delete it: it is made again from the knowledge text.`);
+    throw new Refusal("invalid-database", `${KNOWLEDGE_DIRECTORY}/${LOCAL_DIRECTORY}/${INDEX_FILE} is not a readable SQLite database: ${(error as Error).message} Delete it: it is made again from the knowledge text.`);
   }
   return db;
 }