@henols/c64-re-tools 1.0.0 → 2.0.0-rc.10

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/tools.ts

@@ -0,0 +1,89 @@
+// Short-lived typed requests to the Host Runtime for skill scripts:
+// VICE's own tools (c1541, petcat) and the host tool status. Each request
+// opens its own "tool" connection, sends bytes, and closes. Skill scripts run
+// 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 HostInfo, type ToolStatus } from "../protocol/tools.ts";
+import { HostConnection } from "./connect.ts";
+import { readProjectFile } from "./transfer.ts";
+
+export interface ToolCallOptions {
+  env?: NodeJS.ProcessEnv;
+}
+
+/** Sends one tool request and returns its validated result and attachments. */
+export async function callTool<O extends ToolOperation>(
+  op: O,
+  params: ToolOperations[O]["params"],
+  attachments: readonly Uint8Array[],
+  options: ToolCallOptions = {},
+): Promise<{ result: ToolOperations[O]["result"]; attachments: Buffer[] }> {
+  const connection = await HostConnection.open({ role: "tool", ...(options.env === undefined ? {} : { env: options.env }) });
+  try {
+    return await new Promise((resolve, reject) => {
+      connection.onMessage((message, received) => {
+        if (message.type !== "reply" || message.id !== 1) {
+          reject(new WireFailure("installation-incomplete", "The c64-re-tools host runtime answered out of turn. Install the same c64-re-tools release on both sides."));
+          return;
+        }
+        if ("error" in message) {
+          reject(new WireFailure(message.error.code, message.error.message));
+          return;
+        }
+        try {
+          resolve({ result: validateToolResult(op, message.result, received), attachments: received });
+        } catch (error) {
+          reject(
+            new WireFailure(
+              "operation-failed",
+              error instanceof ProtocolError ? "The c64-re-tools host runtime sent an invalid reply." : "The c64-re-tools host-client could not read the reply of the host runtime.",
+            ),
+          );
+        }
+      });
+      void connection.closed.then(() =>
+        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);
+    });
+  } finally {
+    await connection.close();
+  }
+}
+
+export interface InspectDiskRequest {
+  /** Project-relative disk image; its extension gives the image type. */
+  image: string;
+  action: DiskAction;
+  /** entry, chain and read: the file name as the directory shows it. */
+  name?: string;
+}
+
+/** c1541.inspect: a found read also returns the file's bytes. */
+export async function inspectDisk(request: InspectDiskRequest, options: ToolCallOptions = {}): Promise<C1541Result & { data?: Buffer }> {
+  const file = readProjectFile(request.image);
+  if (!(DISK_IMAGE_TYPES as readonly string[]).includes(file.type)) {
+    throw new WireFailure("invalid-input", `${request.image} is not a disk image that this tool reads. Use a .d64, .d71, .d81 or .g64 file.`);
+  }
+  const params: ToolOperations["c1541.inspect"]["params"] = { action: request.action, imageType: file.type as DiskImageType };
+  if (request.name !== undefined) params.name = request.name;
+  const { result, attachments } = await callTool("c1541.inspect", params, [file.bytes], options);
+  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. */
+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;
+}
+
+/** 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, maskCoversFrame } from "../protocol/vice.ts";

package/src/host-client/transfer.ts

@@ -0,0 +1,126 @@
+// 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 { lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, statSync, writeFileSync } from "node:fs";
+import { dirname, extname, join, relative, sep } from "node:path";
+
+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";
+
+export interface ProjectFile {
+  bytes: Buffer;
+  /** Lowercase extension without the dot; empty when the file has none. */
+  type: string;
+}
+
+/**
+ * Reads one project file. Throws WireFailure: invalid-input for a path the
+ * 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 {
+  const root = options.root ?? projectRoot();
+  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.`);
+    }
+    if (error instanceof TypeError) {
+      throw new WireFailure("invalid-input", `${path}: give a path relative to the project directory that stays inside it.`);
+    }
+    throw error;
+  }
+  const stat = statSync(real);
+  if (!stat.isFile()) throw new WireFailure("invalid-input", `${path} is not a file.`);
+  if (stat.size > MAX_ATTACHMENT_BYTES) {
+    throw new WireFailure("limit-exceeded", `${path} has ${stat.size} bytes. The limit is ${MAX_ATTACHMENT_BYTES} bytes.`);
+  }
+  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"]);
+
+/**
+ * Reads a project directory 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();
+  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.`);
+    throw error;
+  }
+  if (!statSync(sourceRoot).isDirectory()) throw new WireFailure("invalid-input", `${path} is not a directory.`);
+
+  const files: SourceTree = [];
+  const contents: Buffer[] = [];
+  let total = 0;
+  // `realDirectory` is where `directory` really is; `ancestors` holds the real
+  // location of every directory on the walk down to it, so a link to one of
+  // them is a loop.
+  const walk = (directory: string, realDirectory: string, ancestors: Set<string>): void => {
+    for (const entry of readdirSync(directory, { withFileTypes: true }).sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))) {
+      const full = join(directory, entry.name);
+      let target = join(realDirectory, entry.name);
+      if (entry.isSymbolicLink()) {
+        target = realpathSync(full);
+        if (!isInside(sourceRoot, target)) {
+          throw new WireFailure("invalid-input", `${relative(projectRootPath, full)} links outside ${path}. Staging refuses a link that goes outside the source directory.`);
+        }
+      }
+      const stat = statSync(target);
+      if (stat.isDirectory()) {
+        if (SKIPPED_DIRECTORIES.has(entry.name)) continue;
+        if (ancestors.has(target)) {
+          throw new WireFailure("invalid-input", `${relative(projectRootPath, full)} points at a directory that contains it. Staging refuses a link loop.`);
+        }
+        walk(full, target, new Set(ancestors).add(target));
+        continue;
+      }
+      if (!stat.isFile()) continue;
+      if (files.length >= MAX_TREE_FILES) throw new WireFailure("limit-exceeded", `${path} has more than ${MAX_TREE_FILES} files.`);
+      total += stat.size;
+      if (total > MAX_ATTACHMENT_BYTES) throw new WireFailure("limit-exceeded", `${path} holds more than ${MAX_ATTACHMENT_BYTES} bytes.`);
+      files.push({ path: relative(sourceRoot, full).split(sep).join("/"), size: stat.size });
+      contents.push(readFileSync(target));
+    }
+  };
+  walk(sourceRoot, sourceRoot, new Set([sourceRoot]));
+  return { files, contents };
+}