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

package/src/native/acme.ts

@@ -0,0 +1,116 @@
+// The ACME adapter: argv from the typed request only, structured
+// diagnostics and symbols, and a validated C64 PRG as the result.
+
+import { existsSync, readFileSync } from "node:fs";
+import { isAbsolute, join, relative, sep } from "node:path";
+
+import { WireFailure } from "../protocol/messages.ts";
+import { isRelativePath } from "../protocol/tools.ts";
+import type { AcmeParams, AcmeResult, AssembledSymbol, Diagnostic } from "./types.ts";
+import { Workspace } from "./staging.ts";
+import { ACME, findTool } from "./discover.ts";
+import { outputTail, runToolOrFail, type ToolContext } from "./run.ts";
+
+const PROGRAM = "program.prg";
+const SYMBOLS = "symbols.txt";
+const TIMEOUT_MS = 60_000;
+
+/** True for a relative path that stays inside the source root: no absolute path, no drive letter and no "..". */
+const insideSourceRoot = (path: string) => isRelativePath(path) && !/^[A-Za-z]:/.test(path);
+
+/** Refuses an entry source or include directory that ACME could read outside the source root, by name. */
+export function checkAcmeParams(params: AcmeParams): void {
+  if (!insideSourceRoot(params.entrySource)) throw new WireFailure("invalid-input", `The entry source ${params.entrySource} is not a relative path inside the source root.`);
+  if (params.entrySource.startsWith("-")) throw new WireFailure("invalid-input", `The entry source ${params.entrySource} starts with a hyphen, which ACME reads as an option. Give the file a different name.`);
+  for (const directory of params.includeDirs) {
+    if (!insideSourceRoot(directory)) throw new WireFailure("invalid-input", `The include directory ${directory} is not a relative path inside the source root.`);
+  }
+}
+
+/** The argv for one assembly; every value comes from the request that checkAcmeParams accepted. */
+export function acmeArguments(executable: string, params: AcmeParams, outputDirectory: string): string[] {
+  const argv = [executable, "--format", "cbm", "--cpu", "6510", "--maxerrors", "100", "-o", join(outputDirectory, PROGRAM), "--symbollist", join(outputDirectory, SYMBOLS)];
+  for (const directory of params.includeDirs) argv.push("-I", directory);
+  for (const [name, value] of Object.entries(params.defines)) argv.push(`-D${name}=${typeof value === "boolean" ? (value ? 1 : 0) : value}`);
+  if (params.setPc !== undefined) argv.push("--setpc", String(params.setPc));
+  argv.push(params.entrySource);
+  return argv;
+}
+
+const DIAGNOSTIC = /^(Error|Warning|Serious error) - File (.+?), line (\d+)(?: \(.*?\))?: (.*)$/;
+
+/** Parses ACME's "Error - File main.a, line 4 (Zone ...): message" lines. Files become source-root relative. */
+export function parseDiagnostics(output: string, sourceRoot: string): Diagnostic[] {
+  const diagnostics: Diagnostic[] = [];
+  for (const line of output.split(/\r?\n/)) {
+    const match = DIAGNOSTIC.exec(line.trim());
+    if (match !== null) {
+      let file = match[2]!;
+      if (isAbsolute(file)) {
+        const inside = relative(sourceRoot, file);
+        file = inside.startsWith("..") || isAbsolute(inside) ? "(outside the source root)" : inside.split(sep).join("/");
+      }
+      diagnostics.push({ severity: match[1] === "Warning" ? "warning" : "error", file, line: Number(match[3]), message: match[4]! });
+    } else if (/^(Error|Serious error|Warning)\b/.test(line.trim())) {
+      diagnostics.push({ severity: line.trim().startsWith("Warning") ? "warning" : "error", message: line.trim() });
+    }
+  }
+  return diagnostics;
+}
+
+/**
+ * Parses ACME's symbol list ("\tname\t= $2100\t; unused"). A value inside the
+ * assembled program is an address; any other value is a constant.
+ */
+export function parseSymbols(list: string, program: { start: number; end: number }): AssembledSymbol[] {
+  const symbols: AssembledSymbol[] = [];
+  for (const line of list.split(/\r?\n/)) {
+    const match = /^\s*([A-Za-z_][\w.]*)\s*=\s*\$([0-9a-fA-F]+)\s*(?:;\s*(.*?))?\s*$/.exec(line);
+    if (match === null) continue;
+    const name = match[1]!;
+    const value = Number.parseInt(match[2]!, 16);
+    const used = match[3] !== "unused";
+    symbols.push(value >= program.start && value <= program.end ? { name, kind: "address", address: value, used } : { name, kind: "constant", value, used });
+  }
+  // Code-point order: the same on every host, whatever its locale.
+  return symbols.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+}
+
+export async function assemble(
+  params: AcmeParams,
+  files: Buffer[],
+  context: ToolContext,
+): Promise<{ result: AcmeResult; attachments?: Buffer[] }> {
+  checkAcmeParams(params);
+  const executable = findTool(ACME, context.env);
+  const workspace = Workspace.create(context.supervisor);
+  try {
+    const source = workspace.materialize("source", params.files, files);
+    // A fresh output directory, so no stale file can pass for this run's output.
+    const output = workspace.directory("out");
+    const run = await runToolOrFail("ACME", "The assembly", { argv: acmeArguments(executable, params, output), cwd: source, timeoutMs: TIMEOUT_MS }, context);
+    const diagnostics = parseDiagnostics(`${run.stdout}\n${run.stderr}`, source);
+    const programPath = join(output, PROGRAM);
+    if (run.code !== 0) {
+      if (diagnostics.every((diagnostic) => diagnostic.severity !== "error")) {
+        context.log?.(`ACME exited ${run.code} without a parsed error:\n${run.stdout}\n${run.stderr}`);
+        diagnostics.push({ severity: "error", message: `ACME stopped with exit code ${run.code} and gave no error in its usual form.${outputTail("ACME", run, workspace.root)}` });
+      }
+      return { result: { assembled: false, diagnostics } };
+    }
+    if (!existsSync(programPath)) throw new WireFailure("operation-failed", "ACME reported success but wrote no program.");
+    const program = readFileSync(programPath);
+    if (program.length < 3) throw new WireFailure("operation-failed", "ACME wrote a program without bytes.");
+    const start = program.readUInt16LE(0);
+    const bytes = program.length - 2;
+    if (start + bytes > 0x10000) throw new WireFailure("operation-failed", "ACME wrote a program that runs past $ffff.");
+    const end = start + bytes - 1;
+    const symbolList = existsSync(join(output, SYMBOLS)) ? readFileSync(join(output, SYMBOLS), "latin1") : "";
+    return {
+      result: { assembled: true, loadRange: { start, end, bytes }, symbols: parseSymbols(symbolList, { start, end }), diagnostics },
+      attachments: [program],
+    };
+  } finally {
+    workspace.remove();
+  }
+}

package/src/native/discover.ts

@@ -0,0 +1,179 @@
+// One discovery rule for every native tool: C64RT_<TOOL> names
+// the executable, else the tool's usual name on PATH. A missing tool is
+// refused by name with the remedy; nothing is ever installed.
+
+import { accessSync, constants, statSync } from "node:fs";
+import { isAbsolute, join, posix, win32 } from "node:path";
+
+import { WireFailure } from "../protocol/messages.ts";
+
+/** Where the user finds the install steps of the native tools for each system (D38). */
+export const INSTALL_STEPS = "Steps for each system: https://github.com/henols/c64-re-tools/blob/main/docs/install-tools.md";
+
+export interface ToolSpec {
+  /** Human name, for messages. */
+  name: string;
+  /** Environment variable that can name the executable. */
+  envVar: string;
+  /** Executable names to look for on PATH, in order. */
+  binaries: string[];
+  /** Where the tool runs: the Host Runtime's machine, or the skill script's. */
+  where: "on the host" | "on this machine";
+  /** What the user does when the tool is missing. */
+  remedy: string;
+}
+
+export const ACME: ToolSpec = {
+  name: "ACME",
+  envVar: "C64RT_ACME",
+  binaries: ["acme"],
+  where: "on this machine",
+  remedy: `Install the ACME cross-assembler on the machine that runs the skill scripts so that acme is on PATH, or set C64RT_ACME to its full path. ${INSTALL_STEPS}`,
+};
+
+export const C1541: ToolSpec = {
+  name: "c1541",
+  envVar: "C64RT_C1541",
+  binaries: ["c1541"],
+  where: "on the host",
+  remedy: "Install VICE 3.9 or later on the host (c1541 comes with it) so that c1541 is on PATH, or set C64RT_C1541 to its full path, then restart the Host Runtime.",
+};
+
+export const PETCAT: ToolSpec = {
+  name: "petcat",
+  envVar: "C64RT_PETCAT",
+  binaries: ["petcat"],
+  where: "on the host",
+  remedy: "Install VICE 3.9 or later on the host (petcat comes with it) so that petcat is on PATH, or set C64RT_PETCAT to its full path, then restart the Host Runtime.",
+};
+
+export const DXA: ToolSpec = {
+  name: "dxa",
+  envVar: "C64RT_DXA",
+  binaries: ["dxa"],
+  where: "on this machine",
+  remedy: `Install dxa 0.1.5 on the machine that runs the skill scripts so that dxa is on PATH, or set C64RT_DXA to its full path. ${INSTALL_STEPS}`,
+};
+
+export const VICE: ToolSpec = {
+  name: "VICE (x64sc)",
+  envVar: "C64RT_VICE",
+  binaries: ["x64sc"],
+  where: "on the host",
+  remedy: "Install VICE 3.9 or later on the host so that x64sc is on PATH, or set C64RT_VICE to the full path of x64sc, then restart the Host Runtime.",
+};
+
+/**
+ * The oldest VICE that works: 3.7 has no monitor profiler, and its CPU
+ * history, until-return and c1541 chain output differ.
+ */
+export const MIN_VICE = { major: 3, minor: 9 } as const;
+
+/** A VICE version; `revision` is the SVN revision of a build from VICE's source tree (nightly builds), absent for a release. */
+export interface ViceVersion {
+  major: number;
+  minor: number;
+  revision?: number;
+}
+
+/** "x64sc (VICE 3.10)", "c1541 (VICE 3.9)", "VICE 3.9.0" or "x64sc (VICE 3.10 SVN r45999)": the major and minor version, and the SVN revision. */
+export function viceVersionOf(text: string): ViceVersion | undefined {
+  const match = /VICE (\d+)\.(\d+)(?:[.\d]*)(?: SVN r(\d+))?/.exec(text);
+  if (match === null) return undefined;
+  return { major: Number(match[1]), minor: Number(match[2]), ...(match[3] === undefined ? {} : { revision: Number(match[3]) }) };
+}
+
+/**
+ * Known flaws of VICE versions that c64-re-tools still runs on (D56). A flaw
+ * is not worked around: it is named with the VICE version that fixes it.
+ * `upTo` is the last flawed major.minor; `fixedRevision` the first SVN
+ * revision with the fix, for builds from VICE's source tree.
+ */
+const VICE_FLAWS = [
+  {
+    upTo: { major: 3, minor: 10 },
+    fixedRevision: 45971,
+    text:
+      "VICE 3.10 and older hold bits 5-7 of CIA 1 ports A and B low with the joystick device that c64-re-tools uses (VICE bug #2202). " +
+      "$DC00 and $DC01 read $1F with no input. A program that waits for one key of the keyboard matrix (for example LDA $DC01 / CMP #$EF for SPACE) waits forever. " +
+      "A program that compares the full byte of a joystick port also waits forever. " +
+      "A KERNAL tape LOAD of a .tap image stops after FOUND, with no LOADING, and the C64 shows READY. The fix is in the next VICE release, and in VICE nightly builds now (SVN r45971 or later). " +
+      "Install the latest VICE when this matters.",
+  },
+] as const;
+
+/** The known flaws of this VICE version, as text for a person or an agent. */
+export function viceFlaws(version: ViceVersion): string[] {
+  return VICE_FLAWS.filter((flaw) => {
+    const newer = version.major > flaw.upTo.major || (version.major === flaw.upTo.major && version.minor > flaw.upTo.minor);
+    return !newer && (version.revision === undefined || version.revision < flaw.fixedRevision);
+  }).map((flaw) => flaw.text);
+}
+
+export function isOlderThanMinimum(version: { major: number; minor: number }): boolean {
+  return version.major < MIN_VICE.major || (version.major === MIN_VICE.major && version.minor < MIN_VICE.minor);
+}
+
+/** A file this process may run. Windows has no execute permission (X_OK checks nothing there): a file is enough. */
+export function isExecutableFile(path: string): boolean {
+  try {
+    if (!statSync(path).isFile()) return false;
+    if (process.platform !== "win32") accessSync(path, constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The value of an environment variable. Windows ignores the case of the name,
+ * also in a copied environment, where PATH is often named "Path".
+ */
+export function environmentValue(env: NodeJS.ProcessEnv, name: string, platform: NodeJS.Platform = process.platform): string | undefined {
+  if (platform !== "win32" || env[name] !== undefined) return env[name];
+  const key = Object.keys(env).find((candidate) => candidate.toUpperCase() === name.toUpperCase());
+  return key === undefined ? undefined : env[key];
+}
+
+/** The extensions that the supervisor can start on Windows: programs directly, batch files through cmd.exe. */
+const STARTABLE = [".com", ".exe", ".bat", ".cmd"];
+
+/**
+ * The suffixes that a name on PATH can have. On Windows, the PATHEXT
+ * extensions that the supervisor can start, in PATHEXT order, and never the
+ * bare name: Windows does not start a file without an extension. Elsewhere
+ * only the bare name.
+ */
+export function pathSuffixes(env: NodeJS.ProcessEnv, platform: NodeJS.Platform = process.platform): string[] {
+  if (platform !== "win32") return [""];
+  const listed = (environmentValue(env, "PATHEXT", platform) ?? "").split(";").map((suffix) => suffix.trim().toLowerCase());
+  const suffixes = listed.filter((suffix, index) => STARTABLE.includes(suffix) && listed.indexOf(suffix) === index);
+  return suffixes.length === 0 ? STARTABLE : suffixes;
+}
+
+/** The first executable named `binary + suffix` in a PATH directory, in PATH order; undefined when there is none. */
+export function findOnPath(binaries: readonly string[], env: NodeJS.ProcessEnv, suffixes: readonly string[] = pathSuffixes(env), platform: NodeJS.Platform = process.platform): string | undefined {
+  const delimiter = platform === "win32" ? win32.delimiter : posix.delimiter;
+  for (const dir of (environmentValue(env, "PATH", platform) ?? "").split(delimiter)) {
+    if (dir === "") continue;
+    for (const binary of binaries) {
+      for (const suffix of suffixes) {
+        const candidate = join(dir, binary + suffix);
+        if (isExecutableFile(candidate)) return candidate;
+      }
+    }
+  }
+  return undefined;
+}
+
+/** Finds a tool's executable. Throws WireFailure(installation-incomplete) naming the tool and the remedy. */
+export function findTool(tool: ToolSpec, env: NodeJS.ProcessEnv = process.env): string {
+  const configured = env[tool.envVar];
+  if (configured !== undefined && configured !== "") {
+    if (isAbsolute(configured) && isExecutableFile(configured)) return configured;
+    throw new WireFailure("installation-incomplete", `${tool.envVar} ${tool.where} does not name an executable ${tool.name} file. ${tool.remedy}`);
+  }
+  const found = findOnPath(tool.binaries, env);
+  if (found !== undefined) return found;
+  throw new WireFailure("installation-incomplete", `${tool.name} is not installed ${tool.where}. ${tool.remedy}`);
+}

package/src/native/dxa.ts

@@ -0,0 +1,166 @@
+// The DXA adapter. DXA prints an assembler listing only; with
+// "-a dump" each line starts with its address and bytes, so the adapter can
+// tell code from data line by line. The whole listing is checked before the
+// script imports anything: lines in address order from the load address to
+// the end, each line as long as its bytes or data items, so a truncated or
+// changed listing is refused instead of half imported.
+
+import { writeFileSync } from "node:fs";
+
+import { SYMBOL_NAME } from "../c64.ts";
+import { describeError, WireFailure } from "../protocol/messages.ts";
+import { checkDxaResult, checkRequestBounds, imageRange, seedsInside, type DxaParams, type DxaResult } from "./types.ts";
+import { Workspace } from "./staging.ts";
+import { DXA, findTool } from "./discover.ts";
+import { outputTail, runTool, runToolOrFail, type ToolContext } from "./run.ts";
+import { DXA_VERSION, versionLine } from "./status.ts";
+
+const TIMEOUT_MS = 120_000;
+/** The listing is returned as an attachment; larger output is refused. */
+const MAX_LISTING = 8 * 1024 * 1024;
+const VERSION_TIMEOUT_MS = 20_000;
+const MAX_VERSION_OUTPUT = 64 * 1024;
+
+const hex = (value: number) => value.toString(16).padStart(4, "0");
+
+/**
+ * The options for one run; every value comes from the validated request. A
+ * seed file is passed only when it has lines: dxa refuses an empty one.
+ */
+export function dxaArguments(executable: string, params: DxaParams, files: { image: string; routines?: string; blocks?: string; labels?: string }): string[] {
+  const argv = [executable, "-a", "dump", "-p", "all-nmos6502", "-d", "skip-scanning"];
+  if (files.routines !== undefined) argv.push("-R", files.routines);
+  if (files.blocks !== undefined) argv.push("-B", files.blocks);
+  if (files.labels !== undefined) argv.push("-l", files.labels);
+  // A PRG gives its load address and may start with BASIC (-U finds its SYS);
+  // 64 KiB of memory starts at $0000 and has no load address.
+  if (params.imageKind === "prg") argv.push("-U");
+  else argv.push("-g", "0000", "-q");
+  argv.push(files.image);
+  return argv;
+}
+
+/** Number of data bytes in a .byt or .word line, or undefined for an instruction. */
+function dataSize(operation: string): number | undefined {
+  const match = /^\.(byt|word)\s+(.+)$/.exec(operation.trim());
+  if (match === null) return undefined;
+  const items = match[2]!.split(",").length;
+  return match[1] === "word" ? items * 2 : items;
+}
+
+/**
+ * Parses a "-a dump" listing into regions and labels for [start, end].
+ * Throws an Error when the listing is not a complete, consistent listing of
+ * exactly that range.
+ */
+export function parseListing(listing: string, start: number, end: number): Pick<DxaResult, "regions" | "labels"> {
+  const statements: Array<{ address: number; dumped: number; data: number | undefined }> = [];
+  const labels: DxaResult["labels"] = [];
+  for (const line of listing.split(/\r?\n/)) {
+    // dxa prints a seed label as it is, also a local name that starts with a dot.
+    const label = /^([0-9a-f]{4})\s+(\.?[A-Za-z_]\w*):\s*$/.exec(line);
+    if (label !== null) {
+      const address = Number.parseInt(label[1]!, 16);
+      if (address < start || address > end || !SYMBOL_NAME.test(label[2]!)) throw new Error(`label ${label[2]} at $${label[1]} is not usable`);
+      labels.push({ address, name: label[2]! });
+      continue;
+    }
+    // dxa pads the bytes column with a tab, but a two-byte .word line with spaces only.
+    const statement = /^([0-9a-f]{4}) ((?:[0-9a-f]{2} ?){1,3})\s+(\S.*)$/.exec(line);
+    if (statement === null) continue;
+    statements.push({ address: Number.parseInt(statement[1]!, 16), dumped: statement[2]!.trim().split(/\s+/).length, data: dataSize(statement[3]!) });
+  }
+  const first = statements[0];
+  const last = statements.at(-1);
+  if (first === undefined || last === undefined) throw new Error("the listing has no statements");
+  if (first.address !== start) throw new Error(`the listing starts at $${hex(first.address)}, not at $${hex(start)}`);
+  if (last.address > end) throw new Error("the listing runs past the end of the program");
+  const regions: DxaResult["regions"] = [];
+  statements.forEach((statement, index) => {
+    const next = statements[index + 1]?.address ?? end + 1;
+    const size = next - statement.address;
+    if (size <= 0) throw new Error(`the listing goes back at $${hex(next)}`);
+    // Data lines count their items; an instruction line dumps exactly its bytes.
+    const expected = statement.data ?? statement.dumped;
+    if (expected !== size) throw new Error(`the line at $${hex(statement.address)} holds ${expected} bytes, but the next line is ${size} bytes later`);
+    const classification = statement.data === undefined ? "code" : "data";
+    const last = regions.at(-1);
+    if (last?.classification === classification) last.end = next - 1;
+    else regions.push({ start: statement.address, end: next - 1, classification });
+  });
+  return { regions, labels };
+}
+
+/**
+ * The version line of dxa, for example "dxa v0.1.5 -- symbolic 65xx
+ * disassembler". "dxa -V" prints it before its usage and exits with status 1.
+ * On Windows dxa names itself by its full path and ".exe": the line names it
+ * "dxa" on every system. Undefined when dxa prints no version line.
+ */
+export async function dxaVersion(executable: string, cwd: string, context: ToolContext): Promise<string | undefined> {
+  const run = await runTool({ argv: [executable, "-V"], cwd, supervisor: context.supervisor, signal: context.signal, timeoutMs: VERSION_TIMEOUT_MS, outputLimit: MAX_VERSION_OUTPUT, env: context.env });
+  return versionLine(`${run.stdout}\n${run.stderr}`, DXA_VERSION)?.replace(/^(?:.*[\\/])?dxa(?:\.exe)?/i, "dxa");
+}
+
+export async function analyze(
+  params: DxaParams,
+  image: Buffer,
+  context: ToolContext,
+): Promise<{ result: DxaResult; attachments: Buffer[] }> {
+  checkRequestBounds(params);
+  const executable = findTool(DXA, context.env);
+  const { start, end } = imageRange(params.imageKind, image);
+  const { entryPoints, dataRanges } = seedsInside(params, start, end);
+
+  const workspace = Workspace.create(context.supervisor);
+  try {
+    // A cancelled version run gives no version; the analysis run below then refuses the cancelled request.
+    const toolVersion = await dxaVersion(executable, workspace.root, context);
+    workspace.materialize("input", [{ path: "image.bin", size: image.length }], [image]);
+    const files: Parameters<typeof dxaArguments>[2] = { image: "input/image.bin" };
+    const seed = (name: "routines" | "blocks" | "labels", lines: string[]) => {
+      if (lines.length === 0) return;
+      writeFileSync(workspace.path(`${name}.txt`), lines.join(""));
+      files[name] = `${name}.txt`;
+    };
+    seed("routines", entryPoints.map((address) => `${hex(address)}\n`));
+    seed("blocks", dataRanges.map((range) => `${hex(range.start)}-${hex(range.end)}\n`));
+    // The xa label file format: name, address, flags. dxa reads the name up to the first blank, so a leading dot stays.
+    seed("labels", params.labels.filter((label) => SYMBOL_NAME.test(label.name)).map((label) => `${label.name}, 0x${hex(label.address)}, 0x0000\n`));
+    const run = await runToolOrFail(
+      "dxa",
+      "The DXA analysis",
+      {
+        argv: dxaArguments(executable, params, files),
+        cwd: workspace.root,
+        timeoutMs: TIMEOUT_MS,
+        outputLimit: MAX_LISTING,
+        truncated: `dxa printed a listing that is larger than ${MAX_LISTING / 1024 / 1024} MiB. Nothing was imported.`,
+      },
+      context,
+    );
+    if (run.code !== 0) {
+      context.log?.(`dxa exited ${run.code}: ${run.stderr}`);
+      const tail = outputTail("dxa", run, workspace.root);
+      throw new WireFailure("operation-failed", `dxa could not analyze the program${tail === "" ? ` (exit ${run.code}).` : `.${tail}`}`);
+    }
+    const listing = Buffer.from(run.stdout, "utf8");
+    let result: DxaResult;
+    try {
+      const parsed = parseListing(run.stdout, start, end);
+      // DXA classifies every byte, so its regions are complete; it names only referenced addresses.
+      result = checkDxaResult(
+        { coverage: [{ start, end }], ...parsed, listingBytes: listing.length, completeness: { regions: true, labels: false }, ...(toolVersion === undefined ? {} : { toolVersion }) },
+        [listing],
+      );
+    } catch (error) {
+      context.log?.(`dxa listing rejected: ${describeError(error)}`);
+      // The listing is on stdout: only dxa's messages on stderr are quoted.
+      const tail = outputTail("dxa", { stdout: "", stderr: run.stderr }, workspace.root);
+      throw new WireFailure("operation-failed", `dxa returned an incomplete or inconsistent listing. Nothing was imported. The check found: ${describeError(error)}.${tail}`);
+    }
+    return { result, attachments: [listing] };
+  } finally {
+    workspace.remove();
+  }
+}

package/src/native/ghidra/analyze.ts

@@ -0,0 +1,86 @@
+// The Ghidra analysis: one disposable headless run with the NMOS
+// 6510 language, knowledge seeds before analysis, and the structural export
+// after it. The result is checked completely before the script imports it.
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+
+import { describeError, isObject, WireFailure } from "../../protocol/messages.ts";
+import { checkGhidraResult, checkRequestBounds, GHIDRA_LIMITS, imageRange, seedsInside, type GhidraParams, type GhidraResult } from "../types.ts";
+import { outputTail, type ToolContext } from "../run.ts";
+import { Workspace } from "../staging.ts";
+import { findGhidra, ghidraVersion, runHeadless, SCRIPT_DIRECTORY } from "./index.ts";
+
+const TIMEOUT_MS = 600_000;
+/** The part of the run that the decompilations leave for the export, the project removal and the end of Ghidra. */
+const AFTER_DECOMPILE_MS = 30_000;
+
+export async function analyze(
+  params: GhidraParams,
+  image: Buffer,
+  context: ToolContext,
+): Promise<{ result: GhidraResult }> {
+  checkRequestBounds(params);
+  const ghidra = findGhidra(context.env);
+  const { start, end, body } = imageRange(params.imageKind, image);
+  const base = start;
+
+  // Ghidra disassembles and defines data only in the loaded bytes; labels may name any address.
+  const { entryPoints, dataRanges } = seedsInside(params, start, end);
+  if (entryPoints.length === 0) {
+    throw new WireFailure("invalid-input", "Give at least one entry point inside the program, for example the SYS address of its BASIC loader.");
+  }
+
+  const workspace = Workspace.create(context.supervisor);
+  try {
+    workspace.materialize("input", [{ path: "image.bin", size: body.length }], [body]);
+    writeFileSync(workspace.path("seeds.json"), JSON.stringify({ start, end, entryPoints, dataRanges, labels: params.labels }));
+    writeFileSync(
+      workspace.path("request.json"),
+      JSON.stringify({
+        start,
+        end,
+        decompile: params.decompile,
+        maxChars: GHIDRA_LIMITS.decompiledChars,
+        maxTotalChars: GHIDRA_LIMITS.decompiledTotalChars,
+        decompileDeadline: Date.now() + TIMEOUT_MS - AFTER_DECOMPILE_MS,
+      }),
+    );
+    const run = await runHeadless({
+      ghidra,
+      workspace,
+      file: "input/image.bin",
+      baseAddress: base,
+      scriptDirectories: [SCRIPT_DIRECTORY],
+      preScripts: [{ name: "C64Prepare.java", args: [workspace.path("seeds.json")] }],
+      postScripts: [{ name: "C64Export.java", args: [workspace.path("request.json"), workspace.path("out.json")] }],
+      analyze: true,
+      timeoutMs: TIMEOUT_MS,
+      supervisor: context.supervisor,
+      signal: context.signal,
+      ...(context.env === undefined ? {} : { env: context.env }),
+    }).catch((error: unknown) => {
+      context.log?.(`Ghidra failed: ${describeError(error)}`);
+      throw error;
+    });
+    const outPath = workspace.path("out.json");
+    if (!existsSync(outPath)) {
+      context.log?.(`Ghidra wrote no result:\n${run.stdout.slice(-4000)}\n${run.stderr.slice(-4000)}`);
+      // Ghidra's own warnings and errors say why its export script wrote nothing.
+      throw new WireFailure("operation-failed", `Ghidra finished without a result.${outputTail("Ghidra", run, workspace.root, /ERROR|WARN|Exception|Error:|SCRIPT/)}`);
+    }
+    let result: GhidraResult;
+    try {
+      const exported: unknown = JSON.parse(readFileSync(outPath, "utf8"));
+      // The version comes from the installation's application.properties, which findGhidra read.
+      result = checkGhidraResult(isObject(exported) ? { ...exported, toolVersion: ghidraVersion(ghidra) } : exported);
+      const [range] = result.coverage;
+      if (result.coverage.length !== 1 || range === undefined || range.start !== start || range.end !== end) throw new Error("the coverage is not the loaded program");
+    } catch (error) {
+      context.log?.(`Ghidra result rejected: ${describeError(error)}`);
+      throw new WireFailure("operation-failed", `Ghidra returned an incomplete or inconsistent result. Nothing was imported. The check found: ${describeError(error)}.`);
+    }
+    return { result };
+  } finally {
+    workspace.remove();
+  }
+}