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

package/src/host/tools/index.ts

@@ -0,0 +1,35 @@
+// 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 { ViceVersion } from "../../native/discover.ts";
+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),
+};
+
+/** `vice`: the version that the host read from the emulator at start, for host.status. */
+export function createToolDispatcher(options: { supervisor: ProcessSupervisor; env?: NodeJS.ProcessEnv; log?: (line: string) => void; vice?: ViceVersion }): ToolDispatcher {
+  return (op, params, attachments, signal) => {
+    const context = { supervisor: options.supervisor, signal, env: options.env, log: options.log };
+    if (op === "host.status") return hostStatus(context, options.vice) as ReturnType<ToolDispatcher>;
+    return ADAPTERS[op](params, attachments, context);
+  };
+}

package/src/host/tools/petcat.ts

@@ -0,0 +1,77 @@
+// 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. petcat
+ * prints π ($ff) as `~`, which is no PETSCII character: the text has π (F-13).
+ */
+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]!.replaceAll("~", "π") });
+  }
+  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);
+  // petcat gets the BASIC text only, closed with a real end marker: after a
+  // link that only ends BASIC (machine code right after the last line), petcat
+  // prints a comment line where a listing line belongs.
+  const text = Buffer.concat([program.subarray(0, tokenized.textBytes), Buffer.of(0, 0)]);
+  const workspace = Workspace.create(context.supervisor);
+  try {
+    workspace.materialize("input", [{ path: "program.prg", size: text.length }], [text]);
+    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,47 @@
+// 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.
+// VICE itself is reported with the version that the host read from the
+// running emulator at start: the Homebrew x64sc of VICE 3.10 on macOS stops
+// on -version ("argv[0] is NULL") although the emulator runs.
+
+import { arch, platform, release } from "node:os";
+
+import { PACKAGE } from "../../package.ts";
+import type { HostInfo, ToolStatus } from "../../protocol/tools.ts";
+import { C1541, findTool, isOlderThanMinimum, MIN_VICE, PETCAT, VICE, viceFlaws, viceVersionOf, type ToolSpec, type ViceVersion } 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}` };
+}
+
+/** The version text of a VICE version, as x64sc -version prints it. */
+const versionText = (version: ViceVersion) => `x64sc (VICE ${version.major}.${version.minor}${version.revision === undefined ? "" : ` SVN r${version.revision}`})`;
+
+/** `started`: the version that the host read from the emulator at start; without it, VICE is probed with -version too. */
+export async function hostStatus(context: ToolContext, started?: ViceVersion): Promise<{ result: { host: HostInfo; tools: ToolStatus[] } }> {
+  const specs = [VICE, C1541, PETCAT];
+  const probed = await probeTools(
+    [
+      ...(started === undefined ? [{ 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,
+  );
+  const tools = started === undefined ? probed : [{ name: VICE.name, found: true, path: findVice(context.env ?? process.env), version: versionText(started), runs: true }, ...probed];
+  const checked = tools.map((status, index) => requireMinimum(status, specs[index]!));
+  // VICE runs with its known flaws; status names them (D56).
+  const vice = checked[0]!;
+  const version = vice.runs ? viceVersionOf(vice.version ?? "") : undefined;
+  const flaws = version === undefined ? [] : viceFlaws(version);
+  if (flaws.length > 0) checked[0] = { ...vice, flaws };
+  return { result: { host: { version: PACKAGE.version, platform: platform(), release: release(), arch: arch() }, tools: checked } };
+}

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;
+}