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

package/src/mcp/tools/video.ts

@@ -0,0 +1,260 @@
+// Video and chip tools: c64_vicii, c64_sprite, c64_cia, c64_sid, c64_screen
+// and c64_observe.
+
+import { z } from "zod";
+
+import { formatC64Address } from "../../c64.ts";
+import { WireFailure } from "../../protocol/messages.ts";
+import { CIA_SELECTIONS, MAX_MASK_RECTANGLES, MAX_MEMORY_READ, MAX_OBSERVE_BYTES, MAX_OBSERVE_RANGES, SPACES, VICII_MODES, type ObserveParams } from "../../protocol/vice.ts";
+import { AddressInput, AddressOutput, Byte, defineTool, HexData, MemoryViewInput, requireFields, SpaceInput, ToolOutput, TransientName } from "../server.ts";
+
+const Color = z.number().int().min(0).max(15);
+const NO_CHANGE = "This does not change the run state of the machine.";
+
+export const c64Vicii = defineTool({
+  name: "c64_vicii",
+  title: "VIC-II state",
+  description:
+    "Get the state of the VIC-II video chip: the raster line, the graphics mode, the screen and graphics addresses, " +
+    `the scroll values and the colors. The addresses include the 16 KB video bank that CIA 2 selects. ${NO_CHANGE}`,
+  inputSchema: z.object({}).strict(),
+  outputSchema: z.object({
+    rasterLine: z.number().int().min(0),
+    mode: z.enum(VICII_MODES),
+    screenAddress: AddressOutput,
+    graphicsAddress: AddressOutput.describe("character set in text modes, bitmap in bitmap modes"),
+    scrollX: z.number().int().min(0).max(7),
+    scrollY: z.number().int().min(0).max(7),
+    borderColor: Color,
+    backgroundColors: z.array(Color).length(4),
+  }),
+  readOnly: true,
+  async run(_input, session) {
+    const state = await session.vicii();
+    return { ...state, screenAddress: formatC64Address(state.screenAddress), graphicsAddress: formatC64Address(state.graphicsAddress) };
+  },
+});
+
+const SpriteOutput = z.object({
+  index: z.number().int().min(0).max(7),
+  x: z.number().int().min(0),
+  y: z.number().int().min(0),
+  enabled: z.boolean(),
+  color: Color,
+  multicolor: z.boolean(),
+  expandX: z.boolean(),
+  expandY: z.boolean(),
+  behindBackground: z.boolean(),
+  dataAddress: AddressOutput,
+});
+
+export const c64Sprite = defineTool({
+  name: "c64_sprite",
+  title: "Sprite state",
+  description:
+    "Get the state of sprites 0 to 7: position, enabled, color, multicolor, expansion, priority and the address of the sprite data. " +
+    `sprites selects which sprites to give. Without it, you get all eight. ${NO_CHANGE}`,
+  inputSchema: z
+    .object({ sprites: z.array(z.number().int().min(0).max(7)).min(1).max(8).optional().describe("sprite numbers 0 to 7, each once") })
+    .strict(),
+  outputSchema: z.object({ sprites: z.array(SpriteOutput) }),
+  readOnly: true,
+  async run(input, session) {
+    const result = await session.sprites(input.sprites ?? []);
+    return { sprites: result.sprites.map((sprite) => ({ ...sprite, dataAddress: formatC64Address(sprite.dataAddress) })) };
+  },
+});
+
+const CiaOutput = z.object({
+  id: z.union([z.literal(1), z.literal(2)]),
+  portA: Byte,
+  portB: Byte,
+  ddrA: Byte,
+  ddrB: Byte,
+  timerA: z.number().int().min(0).max(0xffff),
+  timerB: z.number().int().min(0).max(0xffff),
+  controlA: Byte,
+  controlB: Byte,
+  interruptStatus: Byte,
+  tod: z.object({ hours: z.number().int(), minutes: z.number().int(), seconds: z.number().int(), tenths: z.number().int() }),
+});
+
+export const c64Cia = defineTool({
+  name: "c64_cia",
+  title: "CIA state",
+  description:
+    "Get the state of CIA 1, CIA 2 or both. The state has the ports, the data direction registers and the current timer values. " +
+    `It also has the control registers, the interrupt flags and the time of day (hours 0 to 23). ${NO_CHANGE}`,
+  inputSchema: z.object({ cia: z.enum(CIA_SELECTIONS).default("both") }).strict(),
+  outputSchema: z.object({ chips: z.array(CiaOutput) }),
+  readOnly: true,
+  async run(input, session) {
+    return session.cia(input.cia);
+  },
+});
+
+export const c64Sid = defineTool({
+  name: "c64_sid",
+  title: "SID state",
+  description:
+    "Get the SID sound chip registers as the program last wrote them: the three voices, the filter and the volume. " +
+    `This is register state, not an analysis of the sound. ${NO_CHANGE}`,
+  inputSchema: z.object({}).strict(),
+  outputSchema: z.object({
+    voices: z.array(
+      z.object({
+        index: z.number().int().min(1).max(3),
+        frequency: z.number().int(),
+        pulseWidth: z.number().int(),
+        control: Byte,
+        attackDecay: Byte,
+        sustainRelease: Byte,
+      }),
+    ),
+    filter: z.object({ cutoff: z.number().int(), resonance: z.number().int(), routing: z.number().int(), mode: z.number().int() }),
+    volume: z.number().int().min(0).max(15),
+  }),
+  readOnly: true,
+  async run(_input, session) {
+    return session.sid();
+  },
+});
+
+const Rectangle = z
+  .object({ x: z.number().int().min(0), y: z.number().int().min(0), width: z.number().int().min(1), height: z.number().int().min(1) })
+  .strict();
+
+export const c64Screen = defineTool({
+  name: "c64_screen",
+  title: "Capture and compare the C64 screen",
+  description:
+    "Action capture returns the last frame the C64 drew, with its borders, as a PNG image, plus its width and height in pixels. " +
+    "With baseline, the session also keeps that frame under the name. " +
+    "Action compare compares the current frame with a baseline, pixel by pixel. mask lists rectangles to ignore. " +
+    "match is true when the part of compared pixels that differ is at most maxMismatchRatio (default 0). bounds holds every different pixel. " +
+    "With includeDiff, compare also returns an image with the different pixels in magenta. " +
+    "Action list gives the baseline names. Action discard removes a baseline. Baselines stay until the session ends. " +
+    "The emulator draws frames while the CPU runs. After the CPU stops, the frame stays the same. " +
+    "This does not change the run state of the machine.",
+  inputSchema: z
+    .object({
+      action: z.enum(["capture", "compare", "list", "discard"]),
+      baseline: TransientName.optional().describe("capture: keep the frame under this name. compare and discard: the baseline to use"),
+      maxMismatchRatio: z.number().min(0).max(1).optional().describe("compare only: 0 to 1, default 0"),
+      mask: z.array(Rectangle).max(MAX_MASK_RECTANGLES).optional().describe("compare only: rectangles to ignore, in frame pixels"),
+      includeDiff: z.boolean().optional().describe("compare only: also return a difference image"),
+    })
+    .strict(),
+  outputSchema: z.object({
+    width: z.number().int().min(1).optional(),
+    height: z.number().int().min(1).optional(),
+    baseline: z.string().optional(),
+    match: z.boolean().optional(),
+    mismatchingPixels: z.number().int().min(0).optional(),
+    mismatchRatio: z.number().min(0).max(1).optional(),
+    bounds: Rectangle.optional(),
+    baselines: z.array(z.string()).optional(),
+    discarded: z.boolean().optional(),
+  }),
+  readOnly: false,
+  async run(input, session) {
+    const { action, ...fields } = input;
+    if (action === "capture") {
+      requireFields(action, fields, ["baseline"]);
+      const shot = await session.screenCapture(fields.baseline);
+      const result = { width: shot.width, height: shot.height, ...(shot.baseline === undefined ? {} : { baseline: shot.baseline }) };
+      return new ToolOutput(result, [{ type: "image", data: shot.png, mimeType: "image/png" }]);
+    }
+    if (action === "compare") {
+      requireFields(action, fields, ["baseline", "maxMismatchRatio", "mask", "includeDiff"], ["baseline"]);
+      const { diffPng, ...result } = await session.screenCompare({
+        baseline: fields.baseline!,
+        maxMismatchRatio: fields.maxMismatchRatio ?? 0,
+        mask: fields.mask ?? [],
+        includeDiff: fields.includeDiff ?? false,
+      });
+      return diffPng === undefined ? result : new ToolOutput(result, [{ type: "image", data: diffPng, mimeType: "image/png" }]);
+    }
+    if (action === "list") {
+      requireFields(action, fields, []);
+      return session.screenBaselines();
+    }
+    requireFields(action, fields, ["baseline"], ["baseline"]);
+    return session.screenDiscard(fields.baseline!);
+  },
+});
+
+const FlagsOutput = z.object({ n: z.boolean(), v: z.boolean(), b: z.boolean(), d: z.boolean(), i: z.boolean(), z: z.boolean(), c: z.boolean() });
+
+export const c64Observe = defineTool({
+  name: "c64_observe",
+  title: "Observe several things at one moment",
+  description:
+    "Get several observations from one moment: the CPU stops once, the tool reads all of them, and then the CPU continues if it was running. " +
+    "Ask for any of registers (a space), memory ranges, vicii, sprites, cia, sid, screen and timing (the raster position). " +
+    `Ask for at least one. Use at most ${MAX_OBSERVE_RANGES} memory ranges with at most ${MAX_OBSERVE_BYTES} bytes together. ` +
+    "The result has only the parts you asked for. With screen, an image comes with the result.",
+  inputSchema: z
+    .object({
+      registers: z.enum(SPACES).optional().describe("the space whose CPU registers to read"),
+      memory: z
+        .array(
+          z
+            .object({ address: AddressInput, size: z.number().int().min(1).max(MAX_MEMORY_READ), space: SpaceInput, view: MemoryViewInput })
+            .strict(),
+        )
+        .min(1)
+        .max(MAX_OBSERVE_RANGES)
+        .optional(),
+      vicii: z.boolean().optional(),
+      sprites: z.array(z.number().int().min(0).max(7)).min(1).max(8).optional().describe("sprite numbers 0 to 7, each once"),
+      cia: z.enum(CIA_SELECTIONS).optional(),
+      sid: z.boolean().optional(),
+      screen: z.boolean().optional(),
+      timing: z.boolean().optional(),
+    })
+    .strict(),
+  outputSchema: z.object({
+    registers: z.object({ pc: AddressOutput, a: Byte, x: Byte, y: Byte, sp: Byte, flags: FlagsOutput }).optional(),
+    memory: z.array(z.object({ address: AddressOutput, data: HexData })).optional(),
+    vicii: c64Vicii.outputSchema.optional(),
+    sprites: z.array(SpriteOutput).optional(),
+    cia: z.array(CiaOutput).optional(),
+    sid: c64Sid.outputSchema.optional(),
+    screen: z.object({ width: z.number().int(), height: z.number().int() }).optional(),
+    timing: z.object({ rasterLine: z.number().int(), rasterCycle: z.number().int() }).optional(),
+  }),
+  readOnly: true,
+  async run(input, session) {
+    const params: ObserveParams = {};
+    if (input.registers !== undefined) params.registers = input.registers;
+    if (input.memory !== undefined) params.memory = input.memory;
+    if (input.vicii === true) params.vicii = true;
+    if (input.sprites !== undefined) params.sprites = input.sprites;
+    if (input.cia !== undefined) params.cia = input.cia;
+    if (input.sid === true) params.sid = true;
+    if (input.screen === true) params.screen = true;
+    if (input.timing === true) params.timing = true;
+    if (Object.keys(params).length === 0) throw new WireFailure("invalid-input", "Ask for at least one observation.");
+    const observed = await session.observe(params);
+    const result: Record<string, unknown> = {};
+    if (observed.registers !== undefined) result.registers = { ...observed.registers, pc: formatC64Address(observed.registers.pc) };
+    if (observed.memory !== undefined) result.memory = observed.memory.map((range) => ({ ...range, address: formatC64Address(range.address) }));
+    if (observed.vicii !== undefined) {
+      result.vicii = {
+        ...observed.vicii,
+        screenAddress: formatC64Address(observed.vicii.screenAddress),
+        graphicsAddress: formatC64Address(observed.vicii.graphicsAddress),
+      };
+    }
+    if (observed.sprites !== undefined) result.sprites = observed.sprites.map((sprite) => ({ ...sprite, dataAddress: formatC64Address(sprite.dataAddress) }));
+    if (observed.cia !== undefined) result.cia = observed.cia;
+    if (observed.sid !== undefined) result.sid = observed.sid;
+    if (observed.timing !== undefined) result.timing = observed.timing;
+    if (observed.screen === undefined) return result;
+    result.screen = { width: observed.screen.width, height: observed.screen.height };
+    return new ToolOutput(result, [{ type: "image", data: observed.screen.png, mimeType: "image/png" }]);
+  },
+});
+
+export const videoTools = [c64Vicii, c64Sprite, c64Cia, c64Sid, c64Screen, c64Observe];

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,141 @@
+// 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";
+
+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.",
+};
+
+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 (from the xa package, https://www.floodgap.com/retrotech/xa/) on the machine that runs the skill scripts so that dxa is on PATH, or set C64RT_DXA to its full path.",
+};
+
+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;
+
+/** "x64sc (VICE 3.10)", "c1541 (VICE 3.9)" or "VICE 3.9.0": the major and minor version. */
+export function viceVersionOf(text: string): { major: number; minor: number } | undefined {
+  const match = /VICE (\d+)\.(\d+)/.exec(text);
+  return match === null ? undefined : { major: Number(match[1]), minor: Number(match[2]) };
+}
+
+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}`);
+}