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

package/src/host-client/autostart.ts

@@ -0,0 +1,55 @@
+// 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";
+  return (await typeRun(client)) ? undefined : "not-started";
+}
+
+/**
+ * Types RUN at the READY prompt and stops where BASIC starts the first line,
+ * before its SYS. Every tool that starts a loaded program this way reaches
+ * its entry at the same raster line and timer values (D62). False when BASIC
+ * runs no line within RUN_LIMIT_FRAMES.
+ */
+export async function typeRun(client: ViceSessionClient): Promise<boolean> {
+  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;
+}

package/src/host-client/connect.ts

@@ -4,7 +4,8 @@ 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 Hello, type HostMessage, type Ping, type Request, type Role, type VideoStandard } from "../protocol/messages.ts";
+import { PACKAGE } from "../package.ts";
 
 export interface Endpoint {
   host: string;
@@ -36,17 +37,19 @@ export function hostEndpoints(env: NodeJS.ProcessEnv = process.env): Endpoint[]
   return ["127.0.0.1", "host.docker.internal", "host.containers.internal"].map((host) => ({ host, port: DEFAULT_HOST_PORT }));
 }
 
-function unreachable(role: Role): WireFailure {
-  const code: ErrorCode = role === "vice-session" ? "machine-unavailable" : "operation-failed";
+/** A host that does not run or cannot be reached is machine-unavailable for every role (D37). */
+function unreachable(): WireFailure {
   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.",
+    "machine-unavailable",
+    withStopAndAsk(
+      `The c64-re-tools host runtime is not running or cannot be reached. Start it on the host (npx -y --package=${PACKAGE.name}@${PACKAGE.tag} c64-re-tools-host) and try again.`,
+    ),
   );
 }
 
-function stopped(role: Role): WireFailure {
+function stopped(): WireFailure {
   return new WireFailure(
-    role === "vice-session" ? "machine-unavailable" : "operation-failed",
+    "machine-unavailable",
     "The connection to the c64-re-tools host runtime stopped before the host runtime was ready.",
   );
 }
@@ -143,16 +146,13 @@ export class HostConnection {
     }
     if (signal?.aborted) {
       socket?.destroy();
-      throw stopped(options.role);
+      throw stopped();
     }
-    if (socket === undefined) throw unreachable(options.role);
+    if (socket === undefined) throw unreachable();
 
     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 });
@@ -172,7 +172,7 @@ export class HostConnection {
     signal?.removeEventListener("abort", stop);
     if (signal?.aborted) {
       await connection.close();
-      throw stopped(options.role);
+      throw stopped();
     }
 
     if (!(answer instanceof Error) && answer.type === "ready") {
@@ -190,7 +190,7 @@ export class HostConnection {
         );
       }
       throw new WireFailure(
-        options.role === "vice-session" ? "machine-unavailable" : "operation-failed",
+        "machine-unavailable",
         "The c64-re-tools host runtime did not finish the handshake. Check that it is running and try again.",
       );
     }

package/src/host-client/coverage.ts

@@ -0,0 +1,36 @@
+// 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 type { ViceSessionClient } from "./vice-session.ts";
+
+/** A full coverage file: offset n is address n (D40). */
+export const FULL_COVERAGE = 0x10000;
+
+/** 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;
+}
+

package/src/host-client/image.ts

@@ -0,0 +1,63 @@
+// An image.json of the c64-unpacker skill (a 64 KiB memory and its segments)
+// or a PRG, read from the project to put it into the knowledge (D83).
+
+import { posix } from "node:path";
+
+import { formatC64Address, prgRange } from "../c64.ts";
+import { readProjectFile } from "./transfer.ts";
+
+/** A file that is no image: the scripts report it as a bad call. */
+export class ImageError extends Error {
+  override name = "ImageError";
+}
+
+export interface Image {
+  segments: Array<{ start: number; end: number }>;
+  /** The byte at an address inside a segment. */
+  byteAt: (address: number) => number;
+  entry?: number;
+  /** entry_state.json next to image.json. */
+  statePath?: string;
+  /** The stages of the capture in image.json, as the unpacker wrote them. */
+  stages?: Array<Record<string, unknown>>;
+}
+
+/** Reads an image.json or a PRG, relative to the project folder. */
+export function readImage(path: string): Image {
+  const { bytes } = readProjectFile(path);
+  if (!path.endsWith(".json")) {
+    let range: ReturnType<typeof prgRange>;
+    try {
+      range = prgRange(bytes);
+    } catch (error) {
+      throw new ImageError(`${path}: ${(error as Error).message}`);
+    }
+    return { segments: [{ start: range.start, end: range.end }], byteAt: (address) => range.body[address - range.start]! };
+  }
+  const fail = (what: string): never => {
+    throw new ImageError(`${path} is not an image.json of the c64-unpacker skill: ${what}`);
+  };
+  let manifest: Record<string, unknown>;
+  try {
+    manifest = JSON.parse(bytes.toString("utf8")) as Record<string, unknown>;
+  } catch (error) {
+    return fail((error as Error).message);
+  }
+  const address = (value: unknown, what: string) => (typeof value === "string" && /^\$[0-9a-f]{4}$/i.test(value) ? Number.parseInt(value.slice(1), 16) : fail(`${what} is not a $ address`));
+  if (typeof manifest.image !== "string") fail("it has no image");
+  if (!Array.isArray(manifest.segments) || manifest.segments.length === 0) fail("it has no segments");
+  const segments = (manifest.segments as Array<Record<string, unknown>>)
+    .map((segment, index) => ({ start: address(segment.start, `segment ${index + 1} start`), end: address(segment.end, `segment ${index + 1} end`) }))
+    .sort((a, b) => a.start - b.start);
+  segments.forEach((segment, index) => {
+    if (segment.end < segment.start) fail(`the segment at ${formatC64Address(segment.start)} ends before it starts`);
+    if (index > 0 && segment.start <= segments[index - 1]!.end) fail(`the segments at ${formatC64Address(segments[index - 1]!.start)} and ${formatC64Address(segment.start)} overlap`);
+  });
+  const directory = posix.dirname(path);
+  const memory = readProjectFile(posix.join(directory, manifest.image as string)).bytes;
+  if (memory.length !== 0x10000) fail(`its image has ${memory.length} bytes, not 65536`);
+  const image: Image = { segments, byteAt: (at) => memory[at]!, statePath: posix.join(directory, "entry_state.json") };
+  if (manifest.entry !== undefined) image.entry = address(manifest.entry, "entry");
+  if (Array.isArray(manifest.stages)) image.stages = manifest.stages as Array<Record<string, unknown>>;
+  return image;
+}

package/src/host-client/steps.ts

@@ -0,0 +1,175 @@
+// 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_TIMEOUT_FRAMES)) fail(`${at} needs a frame count from 1 to ${MAX_TIMEOUT_FRAMES}`);
+      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);
+    // One advance-frames runs at most MAX_EXECUTION_COUNT frames. Each part ends at the raster position
+    // where it started, so the parts give the same frames as one run; a breakpoint ends them all.
+    for (let left = step.frames; left > 0; left -= MAX_EXECUTION_COUNT) {
+      const part = await client.execution({ action: "advance-frames", count: Math.min(left, MAX_EXECUTION_COUNT), space: "c64" });
+      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 });
+    if (!reached.reached) return reached;
+  }
+  return undefined;
+}

package/src/host-client/tools.ts

@@ -4,7 +4,7 @@
 // ACME, DXA and Ghidra themselves through src/native.
 
 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 ToolStatus } from "../protocol/tools.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 { readProjectFile } from "./transfer.ts";
 
@@ -43,7 +43,7 @@ export async function callTool<O extends ToolOperation>(
         }
       });
       void connection.closed.then(() =>
-        reject(new WireFailure("operation-failed", "The connection to the c64-re-tools host runtime was lost during the request. Check that the Host Runtime (c64-re-tools-host) is running.")),
+        reject(new WireFailure("machine-unavailable", "The connection to the c64-re-tools host runtime was lost during the request. Check that the Host Runtime (c64-re-tools-host) is running.")),
       );
       connection.send({ type: "request", id: 1, op, params }, attachments);
     });
@@ -78,12 +78,13 @@ export async function decodeBasic(request: { program: string }, options: ToolCal
   return (await callTool("petcat.decode", {}, [file.bytes], options)).result;
 }
 
-/** host.status: each native tool on the host, found and run once. */
-export async function hostTools(options: ToolCallOptions = {}): Promise<ToolStatus[]> {
-  return (await callTool("host.status", {}, [], options)).result.tools;
+/** host.status: the Host Runtime, and each native tool on the host, found and run once. */
+export async function hostTools(options: ToolCallOptions = {}): Promise<{ host: HostInfo; tools: ToolStatus[] }> {
+  return (await callTool("host.status", {}, [], options)).result;
 }
 
 /** Skill scripts see failures and wire limits through the host-client, never the private protocol module. */
 export { WireFailure } from "../protocol/messages.ts";
 export { DISK_ACTIONS } from "../protocol/tools.ts";
-export { JOYSTICK_DIRECTIONS, MAX_BASELINES, MAX_EXECUTION_COUNT, MAX_KEYBOARD_BYTES, MAX_MASK_RECTANGLES, MAX_MEMORY_READ, MAX_MEMORY_WRITE, MAX_TIMEOUT_FRAMES } from "../protocol/vice.ts";
+export { JOYSTICK_DIRECTIONS, MAX_BASELINES, MAX_EXECUTION_COUNT, MAX_KEYBOARD_BYTES, MAX_MASK_RECTANGLES, MAX_MEMORY_READ, MAX_MEMORY_WRITE, MAX_TIMEOUT_FRAMES, maskCoversFrame } from "../protocol/vice.ts";
+export { MAX_TRACE_FRAMES, MAX_TRACE_HITS, MAX_TRACE_POINTS, TRACE_KINDS, type TraceHit, type TraceKind } from "../protocol/vice.ts";

package/src/host-client/transfer.ts

@@ -1,14 +1,38 @@
 // 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, ProjectError, projectRoot, resolveProject, 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";
 
+/** 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 (D67, D68). 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>" }));
+}
+
+/** The project folder of this process (--project or the D67 lookup), or a WireFailure. */
+function currentProject(): string {
+  return asWireFailure(projectRoot);
+}
+
 export interface ProjectFile {
   bytes: Buffer;
   /** Lowercase extension without the dot; empty when the file has none. */
@@ -21,16 +45,16 @@ export interface ProjectFile {
  * the file is too large to transfer.
  */
 export function readProjectFile(path: string, options: { root?: string } = {}): ProjectFile {
-  const root = options.root ?? projectRoot();
+  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 directory.`);
+      throw new WireFailure("not-found", `There is no file at ${path} in the project folder.`);
     }
     if (error instanceof TypeError) {
-      throw new WireFailure("invalid-input", `${path}: give a path relative to the project directory that stays inside it.`);
+      throw new WireFailure("invalid-input", `${path}: give a path relative to the project folder that stays inside it.`);
     }
     throw error;
   }
@@ -42,22 +66,48 @@ 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 ?? currentProject();
+  const refuse = () => new WireFailure("invalid-input", `${options.what ?? path}: give a path relative to the project folder 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"]);
 
 /**
- * Reads a project directory as a source tree for staging: ordinary
+ * Reads a project folder as a source tree for staging: ordinary
  * files with relative POSIX paths. A symbolic link is followed only when its
  * target stays inside the source root; otherwise the tree is refused.
  */
 export function readProjectTree(path: string, options: { root?: string } = {}): { files: SourceTree; contents: Buffer[] } {
-  const projectRootPath = options.root ?? projectRoot();
+  const projectRootPath = options.root ?? currentProject();
   let sourceRoot: string;
   try {
     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 directory.`);
-    if (error instanceof TypeError) throw new WireFailure("invalid-input", `${path}: give a directory relative to the project directory that stays inside it.`);
+    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.`);
     throw error;
   }
   if (!statSync(sourceRoot).isDirectory()) throw new WireFailure("invalid-input", `${path} is not a directory.`);