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

package/src/host/tools/c1541.ts

@@ -0,0 +1,255 @@
+// The c1541 adapter. c1541 does all image access: it recognises the
+// image, reports free blocks and the BAM, follows sector chains and writes raw
+// blocks. File names never go to c1541: its name arguments and its directory
+// listing change letter case, so the adapter reads the raw header and
+// directory blocks and matches names by their exact PETSCII bytes.
+//
+// c1541 exits 0 after most errors, so success is decided from its output and
+// from the output files it was asked to write.
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { petsciiNameToText, textToPetsciiName } from "../../c64.ts";
+import { WireFailure } from "../../protocol/messages.ts";
+import { CBM_FILE_TYPES, type C1541Params, type C1541Result, type CbmFileType, type DiskFile, type DiskSector } from "../../protocol/tools.ts";
+import { Workspace } from "../../native/staging.ts";
+import { C1541, findTool } from "../../native/discover.ts";
+import { requireMinimumVersion } from "./version.ts";
+import { runToolOrFail, type ToolContext } from "../../native/run.ts";
+
+const TIMEOUT_MS = 30_000;
+const BLOCK_BYTES = 256;
+/** Block reads in one c1541 call, so that its command line stays far below the Windows limit of 32767 characters. */
+export const READS_PER_CALL = 256;
+
+/** Where a drive format keeps its header block and the header's fields. */
+interface Layout {
+  header: DiskSector;
+  name: number;
+  id: number;
+  dos: number;
+}
+
+const LAYOUTS: Record<string, Layout> = {
+  "1541": { header: { track: 18, sector: 0 }, name: 0x90, id: 0xa2, dos: 0xa5 },
+  "1571": { header: { track: 18, sector: 0 }, name: 0x90, id: 0xa2, dos: 0xa5 },
+  "1581": { header: { track: 40, sector: 0 }, name: 0x04, id: 0x16, dos: 0x19 },
+};
+
+export interface DiskEntry extends DiskFile {
+  /** The name's PETSCII bytes, up to the first shifted space ($a0). */
+  nameBytes: Uint8Array;
+  startTrack: number;
+  startSector: number;
+}
+
+const damaged = (message: string) => new WireFailure("media-error", `The disk image is damaged: ${message}`);
+
+/** The drive format and track count from c1541's info command. */
+export function parseInfo(output: string): { format: string; tracks: number } {
+  const format = /^disk format\s*:\s*(\S+)/m.exec(output);
+  const tracks = /^track count\s*:\s*(\d+)/m.exec(output);
+  if (format === null || tracks === null) {
+    throw new WireFailure("media-error", "c1541 does not recognise the disk image. Check that the file is a complete disk image of the given type.");
+  }
+  return { format: format[1]!, tracks: Number(tracks[1]) };
+}
+
+export function parseFreeBlocks(output: string): number {
+  const match = /^(\d+) blocks free\.$/m.exec(output);
+  if (match === null) throw new WireFailure("operation-failed", "c1541 did not report the free blocks of the disk.");
+  return Number(match[1]);
+}
+
+/** A sector chain as c1541's chain command prints it: "(17, 1) -> (17,11) -> 207". */
+export function parseChain(output: string, start: DiskSector): DiskSector[] {
+  const where = `the sector chain from track ${start.track} sector ${start.sector}`;
+  if (/cyclic reference found/.test(output)) throw damaged(`${where} loops.`);
+  const line = /^\(\s*\d+,\s*\d+\).*$/m.exec(output)?.[0];
+  if (line === undefined) throw damaged(`${where} cannot be read.`);
+  const parts = line.split(" -> ");
+  const end = parts.pop()!;
+  if (!/^\d+$/.test(end.trim())) throw damaged(`${where} leaves the disk.`);
+  return parts.map((part) => {
+    const match = /^\(\s*(\d+),\s*(\d+)\)$/.exec(part.trim());
+    if (match === null) throw new WireFailure("operation-failed", "c1541 printed a sector chain in an unknown form.");
+    return { track: Number(match[1]), sector: Number(match[2]) };
+  });
+}
+
+/** The BAM grid c1541 prints: one row per track, "*" for a used sector, "." for a free one. */
+export function parseBam(output: string, tracks: number): Array<{ track: number; freeSectors: number[]; usedSectors: number[] }> {
+  const rows: Array<{ track: number; freeSectors: number[]; usedSectors: number[] }> = [];
+  for (const line of output.split(/\r?\n/)) {
+    const match = /^\s*(\d+)\s+([.*]{1,8}(?: [.*]{1,8})*)\s*$/.exec(line);
+    if (match === null) continue;
+    const row = { track: Number(match[1]), freeSectors: [] as number[], usedSectors: [] as number[] };
+    [...match[2]!.replace(/ /g, "")].forEach((mark, sector) => (mark === "*" ? row.usedSectors : row.freeSectors).push(sector));
+    rows.push(row);
+  }
+  const complete = rows.length === tracks && rows.every((row, index) => row.track === index + 1);
+  if (!complete) throw new WireFailure("operation-failed", `c1541 printed a BAM that does not cover the ${tracks} tracks of the disk.`);
+  return rows;
+}
+
+/** The bytes of a name field up to the first shifted space ($a0). */
+function nameField(block: Buffer, offset: number, length: number): Uint8Array {
+  const field = block.subarray(offset, offset + length);
+  const end = field.indexOf(0xa0);
+  return Uint8Array.from(end < 0 ? field : field.subarray(0, end));
+}
+
+function fileType(typeByte: number): CbmFileType {
+  return CBM_FILE_TYPES[typeByte & 0x07] ?? "unknown";
+}
+
+/** The disk header and the directory entries, from the raw header block and the directory blocks after it. */
+export function parseDirectory(blocks: Buffer[], layout: Layout): { diskName: string; diskId: string; dosType: string; entries: DiskEntry[] } {
+  const [header, ...directory] = blocks;
+  if (header === undefined) throw new WireFailure("operation-failed", "c1541 returned no header block.");
+  const entries: DiskEntry[] = [];
+  for (const block of directory) {
+    for (let offset = 0; offset < BLOCK_BYTES; offset += 32) {
+      const typeByte = block.readUInt8(offset + 2);
+      // Type 0 is an empty or scratched slot; the DOS lists no file there.
+      if (typeByte === 0) continue;
+      const nameBytes = nameField(block, offset + 5, 16);
+      entries.push({
+        name: petsciiNameToText(nameBytes),
+        nameBytes,
+        type: fileType(typeByte),
+        blocks: block.readUInt16LE(offset + 30),
+        closed: (typeByte & 0x80) !== 0,
+        locked: (typeByte & 0x40) !== 0,
+        startTrack: block.readUInt8(offset + 3),
+        startSector: block.readUInt8(offset + 4),
+      });
+    }
+  }
+  return {
+    diskName: petsciiNameToText(nameField(header, layout.name, 16)),
+    diskId: petsciiNameToText(header.subarray(layout.id, layout.id + 2)),
+    dosType: petsciiNameToText(header.subarray(layout.dos, layout.dos + 2)),
+    entries,
+  };
+}
+
+/** A file's data from its blocks in chain order: 254 bytes per block, the last block up to its end index. */
+export function fileData(blocks: Buffer[], chain: DiskSector[]): Buffer {
+  const parts: Buffer[] = [];
+  blocks.forEach((block, index) => {
+    const next = chain[index + 1];
+    if (next === undefined) {
+      if (block[0] !== 0) throw new WireFailure("operation-failed", "c1541 returned a last file block that links further.");
+      parts.push(block.subarray(2, Math.max(2, block.readUInt8(1) + 1)));
+    } else {
+      if (block[0] !== next.track || block[1] !== next.sector) throw new WireFailure("operation-failed", "c1541 returned file blocks that do not match the sector chain.");
+      parts.push(block.subarray(2));
+    }
+  });
+  return Buffer.concat(parts);
+}
+
+const toFile = (entry: DiskEntry): DiskFile => ({ name: entry.name, type: entry.type, blocks: entry.blocks, closed: entry.closed, locked: entry.locked });
+
+const sameBytes = (a: Uint8Array, b: Uint8Array) => a.length === b.length && a.every((byte, index) => byte === b[index]);
+
+/** Runs c1541 commands on the staged image and returns all its output. */
+export class C1541Session {
+  readonly #executable: string;
+  readonly #workspace: Workspace;
+  readonly #image: string;
+  readonly #context: ToolContext;
+  #reads = 0;
+
+  constructor(executable: string, workspace: Workspace, image: string, context: ToolContext) {
+    this.#executable = executable;
+    this.#workspace = workspace;
+    this.#image = image;
+    this.#context = context;
+  }
+
+  async run(commands: string[]): Promise<string> {
+    const run = await runToolOrFail(
+      "c1541",
+      "The disk inspection",
+      {
+        argv: [this.#executable, "-attach", this.#image, ...commands],
+        cwd: this.#workspace.root,
+        timeoutMs: TIMEOUT_MS,
+        truncated: "c1541 printed more output than the host accepts.",
+      },
+      this.#context,
+    );
+    return `${run.stdout}\n${run.stderr}`;
+  }
+
+  async chain(start: DiskSector): Promise<DiskSector[]> {
+    return parseChain(await this.run(["-chain", String(start.track), String(start.sector)]), start);
+  }
+
+  /** Raw blocks, in the given order, through c1541's block read: at most READS_PER_CALL blocks in each c1541 call. */
+  async blocks(sectors: DiskSector[]): Promise<Buffer[]> {
+    const blocks: Buffer[] = [];
+    for (let first = 0; first < sectors.length; first += READS_PER_CALL) {
+      blocks.push(...(await this.#readBlocks(sectors.slice(first, first + READS_PER_CALL))));
+    }
+    return blocks;
+  }
+
+  async #readBlocks(sectors: DiskSector[]): Promise<Buffer[]> {
+    const directory = `blocks-${this.#reads++}`;
+    const full = this.#workspace.directory(directory);
+    const reads = sectors.map((at, index) => ({ at, file: `${index}.bin` }));
+    const output = await this.run(reads.flatMap(({ at, file }) => ["-bread", join(directory, file), String(at.track), String(at.sector)]));
+    return reads.map(({ at, file }) => {
+      const path = join(full, file);
+      const block = existsSync(path) ? readFileSync(path) : undefined;
+      if (block?.length === BLOCK_BYTES) return block;
+      if (/cannot read track|out of bounds/.test(output)) throw damaged(`track ${at.track} sector ${at.sector} cannot be read.`);
+      throw new WireFailure("operation-failed", `c1541 did not write track ${at.track} sector ${at.sector}.`);
+    });
+  }
+}
+
+export async function inspect(params: C1541Params, image: Buffer, context: ToolContext): Promise<{ result: C1541Result; attachments?: Buffer[] }> {
+  const executable = findTool(C1541, context.env);
+  await requireMinimumVersion(C1541, executable, context);
+  const workspace = Workspace.create(context.supervisor);
+  try {
+    const file = `image.${params.imageType}`;
+    workspace.materialize("input", [{ path: file, size: image.length }], [image]);
+    const c1541 = new C1541Session(executable, workspace, `input/${file}`, context);
+    const overview = await c1541.run(["-info", "-dir"]);
+    const info = parseInfo(overview);
+    const layout = LAYOUTS[info.format];
+    if (layout === undefined) throw new WireFailure("media-error", `The disk image has the drive format ${info.format}; only 1541, 1571 and 1581 disks are supported.`);
+
+    if (params.action === "bam") {
+      return { result: { action: "bam", tracks: parseBam(await c1541.run(["-bam"]), info.tracks) } };
+    }
+    const headerChain = await c1541.chain(layout.header);
+    const directory = parseDirectory(await c1541.blocks(headerChain), layout);
+    if (params.action === "directory") {
+      const { diskName, diskId, dosType, entries } = directory;
+      return { result: { action: "directory", diskName, diskId, dosType, freeBlocks: parseFreeBlocks(overview), entries: entries.map(toFile) } };
+    }
+
+    if (params.name === undefined) throw new WireFailure("invalid-input", `action ${params.action} needs a file name`);
+    const wanted = textToPetsciiName(params.name);
+    const entry = directory.entries.find((candidate) => sameBytes(candidate.nameBytes, wanted));
+    if (entry === undefined) return { result: { action: params.action, found: false } };
+    if (params.action === "entry") {
+      return { result: { action: "entry", found: true, entry: { ...toFile(entry), startTrack: entry.startTrack, startSector: entry.startSector } } };
+    }
+    // A file without blocks (a DEL entry, for example) has no chain.
+    const start = { track: entry.startTrack, sector: entry.startSector };
+    const chain = start.track === 0 ? [] : await c1541.chain(start);
+    if (params.action === "chain") return { result: { action: "chain", found: true, sectors: chain } };
+    const data = fileData(await c1541.blocks(chain), chain);
+    return { result: { action: "read", found: true, name: entry.name, bytes: data.length }, attachments: [data] };
+  } finally {
+    workspace.remove();
+  }
+}

package/src/host/tools/index.ts

@@ -0,0 +1,31 @@
+// The typed tool dispatcher of the Host Runtime. The host runs only
+// VICE and the tools that come with it (c1541, petcat); skill scripts run
+// ACME, DXA and Ghidra themselves. One entry per operation, never a
+// generic executable route.
+
+import type { ProcessSupervisor } from "../../native/processes.ts";
+import type { ToolContext } from "../../native/run.ts";
+import type { ToolOperation, ToolOperations } from "../../protocol/tools.ts";
+import type { ToolDispatcher } from "../server.ts";
+import { inspect } from "./c1541.ts";
+import { decode } from "./petcat.ts";
+import { hostStatus } from "./status.ts";
+
+/** Runs one operation with its validated parameters and attachments. */
+type Adapter<O extends ToolOperation> = (
+  params: ToolOperations[O]["params"],
+  attachments: Buffer[],
+  context: ToolContext,
+) => Promise<{ result: ToolOperations[O]["result"]; attachments?: Buffer[] }>;
+
+const ADAPTERS: { [O in ToolOperation]: Adapter<O> } = {
+  "host.status": (_params, _attachments, context) => hostStatus(context),
+  "c1541.inspect": (params, attachments, context) => inspect(params, attachments[0]!, context),
+  "petcat.decode": (_params, attachments, context) => decode(attachments[0]!, context),
+};
+
+export function createToolDispatcher(options: { supervisor: ProcessSupervisor; env?: NodeJS.ProcessEnv; log?: (line: string) => void }): ToolDispatcher {
+  return (op, params, attachments, signal) => {
+    return ADAPTERS[op](params, attachments, { supervisor: options.supervisor, signal, env: options.env, log: options.log });
+  };
+}

package/src/host/tools/petcat.ts

@@ -0,0 +1,70 @@
+// The petcat adapter. petcat makes the C64 BASIC V2 listing; the
+// adapter parses the tokenized program itself to check that listing and to
+// find the machine-code handoffs, because petcat's exit status proves nothing
+// (it prints any bytes as text).
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { findHandoffs, parseTokenized } from "../../c64.ts";
+import { WireFailure } from "../../protocol/messages.ts";
+import { type PetcatResult } from "../../protocol/tools.ts";
+import { Workspace } from "../../native/staging.ts";
+import { findTool, PETCAT } from "../../native/discover.ts";
+import { requireMinimumVersion } from "./version.ts";
+import { runToolOrFail, type ToolContext } from "../../native/run.ts";
+
+const TIMEOUT_MS = 30_000;
+const LISTING = "listing.txt";
+/** petcat's listing lines ("   10 sys2061"), as number and text. */
+export function parseListing(listing: string): Array<{ number: number; text: string }> {
+  const lines: Array<{ number: number; text: string }> = [];
+  for (const line of listing.split(/\r?\n/)) {
+    if (line.trim() === "") continue;
+    const match = /^\s*(\d+) ?(.*)$/.exec(line);
+    if (match === null) throw new WireFailure("operation-failed", "petcat printed a listing line without a line number.");
+    lines.push({ number: Number(match[1]), text: match[2]! });
+  }
+  return lines;
+}
+
+export async function decode(
+  program: Buffer,
+  context: ToolContext,
+): Promise<{ result: PetcatResult }> {
+  const tokenized = parseTokenized(program);
+  if ("reason" in tokenized) return { result: { decoded: false, reason: tokenized.reason } };
+  const executable = findTool(PETCAT, context.env);
+  await requireMinimumVersion(PETCAT, executable, context);
+  const workspace = Workspace.create(context.supervisor);
+  try {
+    workspace.materialize("input", [{ path: "program.prg", size: program.length }], [program]);
+    const listingPath = join(workspace.directory("out"), LISTING);
+    const run = await runToolOrFail(
+      "petcat",
+      "The BASIC decode",
+      // -2: C64 BASIC V2 keywords. -nh: no header. The input is never read as an option.
+      { argv: [executable, "-2", "-nh", "-o", listingPath, "--", "input/program.prg"], cwd: workspace.root, timeoutMs: TIMEOUT_MS },
+      context,
+    );
+    if (run.code !== 0 || !existsSync(listingPath)) {
+      context.log?.(`petcat exited ${run.code}:\n${run.stdout}\n${run.stderr}`);
+      throw new WireFailure("operation-failed", "petcat could not decode the program.");
+    }
+    const lines = parseListing(readFileSync(listingPath, "latin1"));
+    const agrees = lines.length === tokenized.lines.length && lines.every((line, index) => line.number === tokenized.lines[index]!.number);
+    if (!agrees) throw new WireFailure("operation-failed", "petcat's listing does not match the lines of the program.");
+    return {
+      result: {
+        decoded: true,
+        loadAddress: tokenized.loadAddress,
+        basicEnd: tokenized.basicEnd,
+        listing: lines.map((line) => `${line.number} ${line.text}`).join("\n"),
+        lines,
+        handoffs: findHandoffs(tokenized.lines),
+      },
+    };
+  } finally {
+    workspace.remove();
+  }
+}

package/src/host/tools/status.ts

@@ -0,0 +1,30 @@
+// host.status: VICE and the tools that come with it, each found the way its
+// operations find it and run once with a version option. A tool from a
+// VICE older than MIN_VICE is reported as not working, as its operations refuse it.
+
+import type { ToolStatus } from "../../protocol/tools.ts";
+import { C1541, findTool, isOlderThanMinimum, MIN_VICE, PETCAT, VICE, viceVersionOf, type ToolSpec } from "../../native/discover.ts";
+import type { ToolContext } from "../../native/run.ts";
+import { probeTools } from "../../native/status.ts";
+import { findVice } from "../vice/process.ts";
+
+function requireMinimum(status: ToolStatus, tool: ToolSpec): ToolStatus {
+  if (!status.runs) return status;
+  const version = viceVersionOf(status.version ?? "");
+  if (version !== undefined && !isOlderThanMinimum(version)) return status;
+  const found = version === undefined ? "It does not tell its VICE version" : `It comes from VICE ${version.major}.${version.minor}`;
+  return { ...status, runs: false, problem: `${found}, and c64-re-tools needs VICE ${MIN_VICE.major}.${MIN_VICE.minor} or later. ${tool.remedy}` };
+}
+
+export async function hostStatus(context: ToolContext): Promise<{ result: { tools: ToolStatus[] } }> {
+  const specs = [VICE, C1541, PETCAT];
+  const tools = await probeTools(
+    [
+      { name: VICE.name, find: findVice, args: ["-version"], pattern: /^x64sc \(VICE \d/ },
+      { name: C1541.name, find: (env) => findTool(C1541, env), args: ["-version"], pattern: /^c1541 \(VICE \d/ },
+      { name: PETCAT.name, find: (env) => findTool(PETCAT, env), args: ["-version"], pattern: /^petcat \(VICE \d/ },
+    ],
+    context,
+  );
+  return { result: { tools: tools.map((status, index) => requireMinimum(status, specs[index]!)) } };
+}

package/src/host/tools/version.ts

@@ -0,0 +1,41 @@
+// The VICE tools on the host must come from a VICE that c64-re-tools works
+// with. Each executable is asked once for its version; a version that
+// cannot be read is refused, as is one that is too old.
+
+import { tmpdir } from "node:os";
+
+import { WireFailure } from "../../protocol/messages.ts";
+import { isOlderThanMinimum, MIN_VICE, viceVersionOf, type ToolSpec } from "../../native/discover.ts";
+import { runToolOrFail, type ToolContext } from "../../native/run.ts";
+
+const VERSION_TIMEOUT_MS = 30_000;
+const checked = new Map<string, Promise<void>>();
+
+/** Refuses a tool from a VICE older than MIN_VICE, or one whose VICE version cannot be read, by name and with the remedy. */
+export function requireMinimumVersion(tool: ToolSpec, executable: string, context: ToolContext): Promise<void> {
+  let check = checked.get(executable);
+  if (check === undefined) {
+    // Every caller waits for the same check, so no caller's cancel may stop it; its own time limit bounds it.
+    const shared: ToolContext = { ...context, signal: new AbortController().signal };
+    check = (async () => {
+      const run = await runToolOrFail(tool.name, `The ${tool.name} version check`, { argv: [executable, "-version"], cwd: tmpdir(), timeoutMs: VERSION_TIMEOUT_MS }, shared);
+      const version = viceVersionOf(`${run.stdout}\n${run.stderr}`);
+      if (version === undefined) {
+        throw new WireFailure(
+          "installation-incomplete",
+          `${tool.name} does not tell its VICE version, and c64-re-tools needs VICE ${MIN_VICE.major}.${MIN_VICE.minor} or later. ${tool.remedy}`,
+        );
+      }
+      if (isOlderThanMinimum(version)) {
+        throw new WireFailure(
+          "installation-incomplete",
+          `${tool.name} comes from VICE ${version.major}.${version.minor}, and c64-re-tools needs VICE ${MIN_VICE.major}.${MIN_VICE.minor} or later. ${tool.remedy}`,
+        );
+      }
+    })();
+    // A refusal or a failed check is asked again next time: the user can install a newer VICE meanwhile.
+    check.catch(() => checked.delete(executable));
+    checked.set(executable, check);
+  }
+  return check;
+}