@tsplc/build 0.0.0-stage → 0.2.0

package/src/controller-online.ts

@@ -0,0 +1,297 @@
+import { execFile } from "node:child_process";
+import { existsSync } from "node:fs";
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { resolve } from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+import { promisify } from "node:util";
+import { z } from "zod";
+import { controllerSchema, dockerImage, type ResolvedConfig } from "./config";
+import { controllerFailureFile } from "./diagnostics.ts";
+import { prepareContainerRun, runDocker } from "./docker-run.ts";
+
+const execute = promisify(execFile);
+const imageIdSchema = z.string().regex(/^sha256:[a-f0-9]{64}$/);
+const endpointSchema = z.strictObject({
+  host: z.string().nonempty(),
+  port: z.number().int().min(1).max(65535),
+});
+export const controllerResultSchema = z.strictObject({
+  schemaVersion: z.literal(1),
+  operationId: z.uuid(),
+  operation: z.enum(["download", "online-change", "inspect"]),
+  imageId: imageIdSchema,
+  templateHash: z.string().regex(/^[a-f0-9]{64}$/),
+  target: z.strictObject({
+    network: z.string().nonempty(),
+    gateway: endpointSchema,
+    device: endpointSchema,
+    controller: controllerSchema.optional(),
+  }),
+  generation: z.string().nonempty(),
+  application: z.string().nonempty(),
+  applicationGuid: z.string().nonempty(),
+  controllerIds: z.strictObject({
+    codeId: z.string().nonempty(),
+    dataId: z.string().nonempty(),
+  }),
+  state: z.string().nonempty(),
+  values: z.record(z.string(), z.string()),
+});
+export type ControllerResult = z.infer<typeof controllerResultSchema>;
+export type ControllerUpdateOptions = {
+  initializeUser?: boolean;
+  read?: string[];
+};
+
+/** Checks the settings every engineering connection needs and names its builder image and target. */
+const controllerConnection = async (config: ResolvedConfig) => {
+  if (!config.docker || !config.online) {
+    throw new Error(
+      "Docker image and online gateway/device configuration are required for controller operations",
+    );
+  }
+  const environmentNames = config.online.credentials
+    ? [config.online.credentials.usernameEnv, config.online.credentials.passwordEnv]
+    : [];
+  for (const name of environmentNames) {
+    if (process.env[name] === undefined) {
+      throw new Error(`Controller credential environment variable ${name} is not set`);
+    }
+  }
+  const { stdout } = await execute(
+    "docker",
+    ["image", "inspect", "--format", "{{.Id}}", dockerImage],
+    { timeout: config.timeouts.hostCommand },
+  ).catch((cause: unknown) => {
+    throw new Error(
+      `Cannot inspect Docker builder image ${dockerImage}. Install and start Docker, then run tsplc-build configure if the image is missing`,
+      { cause },
+    );
+  });
+  return {
+    environmentNames,
+    imageId: imageIdSchema.parse(stdout.trim()),
+    templateHash: createHash("sha256")
+      .update(await readFile(config.template))
+      .digest("hex"),
+    target: {
+      network: config.online.network,
+      gateway: config.online.gateway,
+      device: config.online.device,
+      controller: config.controller,
+    },
+  };
+};
+
+const controllerOperation = async (
+  config: ResolvedConfig,
+  operation: ControllerResult["operation"],
+  options: ControllerUpdateOptions,
+): Promise<ControllerResult> => {
+  const { environmentNames, imageId, templateHash, target } = await controllerConnection(config);
+  const operationId = randomUUID();
+  const requestDirectory = await mkdtemp(resolve(tmpdir(), "codesys-controller-"));
+  const diagnostics = resolve(config.outDir, ".codesys/controller");
+  const failure = resolve(config.outDir, controllerFailureFile);
+  try {
+    await mkdir(config.outDir, { recursive: true });
+    await rm(failure, { force: true });
+    await runDocker(
+      [
+        "run",
+        "--rm",
+        ...(await prepareContainerRun(config, requestDirectory, {
+          network: target.network,
+          environment: environmentNames,
+          sources: operation !== "inspect",
+        })),
+        imageId,
+        operation,
+        "--request",
+        "/input/config.json",
+        "--operation-id",
+        operationId,
+        "--image-id",
+        imageId,
+        ...(options.initializeUser ? ["--initialize-user"] : []),
+        ...(options.read ? ["--read", JSON.stringify(options.read)] : []),
+      ],
+      (status) =>
+        `Docker controller operation failed (${status}). Inspect ${diagnostics} for diagnostics`,
+    ).catch(async (cause: unknown) => {
+      if (!existsSync(failure)) throw cause;
+      // A CODESYS failure arrives as a Python traceback, whose last line names it.
+      const reason = (await readFile(failure, "utf8")).trim().split("\n").at(-1);
+      throw new Error(`${reason}. Inspect ${diagnostics} for diagnostics`, { cause });
+    });
+    const result = await readFile(resolve(diagnostics, "result.json"), "utf8")
+      .then((content) => controllerResultSchema.parse(JSON.parse(content)))
+      .catch((cause: unknown) => {
+        throw new Error(
+          `Docker did not produce a valid controller receipt. Inspect ${diagnostics} for diagnostics`,
+          { cause },
+        );
+      });
+    if (
+      result.operationId !== operationId ||
+      result.operation !== operation ||
+      result.imageId !== imageId ||
+      result.templateHash !== templateHash ||
+      JSON.stringify(result.target) !== JSON.stringify(target)
+    ) {
+      throw new Error(
+        `Controller receipt does not match this operation's image, template or target. Inspect ${diagnostics} for diagnostics`,
+      );
+    }
+    return result;
+  } finally {
+    await rm(requestDirectory, { recursive: true, force: true });
+  }
+};
+
+/** Download or apply an online change using the original CODESYS Docker compiler. */
+export const updateController = (
+  config: ResolvedConfig,
+  operation: "download" | "online-change",
+  options: ControllerUpdateOptions = {},
+) => controllerOperation(config, operation, options);
+
+/** Read the controller using the runner's saved compilation baseline. */
+export const inspectController = (config: ResolvedConfig, read?: string[]) =>
+  controllerOperation(config, "inspect", { read });
+
+/**
+ * Ends every refusal that only a full download resolves, so callers can offer one. The Python
+ * online operations end theirs with the same words.
+ */
+export const explicitDownload = "use an explicit download";
+
+export const loginCommandSchema = z.discriminatedUnion("command", [
+  z.strictObject({ command: z.literal("state") }),
+  z.strictObject({
+    command: z.literal("read"),
+    expressions: z.array(z.string().nonempty()).nonempty(),
+  }),
+  z.strictObject({
+    command: z.enum(["write", "force"]),
+    values: z.record(z.string().nonempty(), z.string().nonempty()),
+  }),
+  // No expressions unforces everything; `restore` puts back the value from before forcing.
+  z.strictObject({
+    command: z.literal("unforce"),
+    expressions: z.array(z.string().nonempty()),
+    restore: z.boolean(),
+  }),
+  z.strictObject({ command: z.enum(["start", "stop"]) }),
+  z.strictObject({ command: z.literal("reset"), kind: z.enum(["Warm", "Cold"]) }),
+]);
+export type LoginCommand = z.infer<typeof loginCommandSchema>;
+export const loginResultSchema = z.union([
+  z.strictObject({ values: z.record(z.string(), z.string()) }),
+  z.strictObject({ state: z.string(), forced: z.array(z.string()) }),
+]);
+export type LoginResult = z.infer<typeof loginResultSchema>;
+const loginReplySchema = z.discriminatedUnion("ok", [
+  z.strictObject({ ok: z.literal(true), result: z.unknown() }),
+  z.strictObject({ ok: z.literal(false), error: z.string() }),
+]);
+
+/** The port a login container serves its commands on, published to the host's loopback only. */
+const loginPort = 4851;
+
+const docker = (args: string[], timeout: number) =>
+  execute("docker", args, { timeout }).then(({ stdout }) => stdout.trim());
+
+const isRunning = async (name: string, timeout: number) =>
+  (await docker(["container", "ls", "--quiet", "--filter", `name=^${name}$`], timeout)) !== "";
+
+/** A login held open in builder container `name`; it ends with `close` or when the container stops. */
+const attachLogin = async (name: string, timeout: number) => {
+  const published = await docker(["port", name, String(loginPort)], timeout);
+  const url = `http://${published.split("\n")[0]}`;
+  const call = async (init: RequestInit) => {
+    const reply = loginReplySchema.parse(await (await fetch(url, init)).json());
+    if (!reply.ok) throw new Error(reply.error);
+    return reply.result;
+  };
+  return {
+    name,
+    /** The relay answers only once CODESYS has logged in. */
+    ready: () =>
+      fetch(url)
+        .then((response) => response.ok)
+        .catch(() => false),
+    send: async (command: LoginCommand) =>
+      loginResultSchema.parse(
+        await call({
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify(command),
+        }),
+      ),
+    /** Logs out and waits for the container to stop. */
+    close: async () => {
+      await call({ method: "DELETE" });
+      await docker(["wait", name], timeout);
+      await docker(["rm", name], timeout);
+    },
+  };
+};
+export type ControllerLogin = Awaited<ReturnType<typeof attachLogin>>;
+
+/** The login in container `name`, if one is running; it outlives the process that opened it. */
+export const findControllerLogin = async (name: string) =>
+  (await isRunning(name, 15_000)) ? attachLogin(name, 15_000) : undefined;
+
+/**
+ * Logs in to the running application from the saved download baseline, in a detached builder
+ * container named `name`. Commands then take seconds instead of a CODESYS start each.
+ */
+export const openControllerLogin = async (config: ResolvedConfig, name: string) => {
+  const { environmentNames, imageId, target } = await controllerConnection(config);
+  const timeout = config.timeouts.hostCommand;
+  // A login that failed to open leaves its stopped container for diagnostics until the next one.
+  await docker(["rm", "--force", name], timeout);
+  // The request is overwritten in place: a bind mount of a recreated directory can still show
+  // Docker Desktop's cached, empty view of the deleted one.
+  const requestDirectory = resolve(config.outDir, ".codesys/login-request");
+  await mkdir(requestDirectory, { recursive: true });
+  await docker(
+    [
+      "run",
+      "--detach",
+      "--name",
+      name,
+      "--publish",
+      `127.0.0.1::${loginPort}`,
+      ...(await prepareContainerRun(config, requestDirectory, {
+        network: target.network,
+        environment: environmentNames,
+        sources: false,
+      })),
+      imageId,
+      "login",
+      "--request",
+      "/input/config.json",
+      "--image-id",
+      imageId,
+      "--port",
+      String(loginPort),
+    ],
+    timeout,
+  );
+  const deadline = Date.now() + config.timeouts.startup + config.timeouts.build;
+  while (Date.now() < deadline) {
+    if (!(await isRunning(name, timeout))) {
+      const logs = await execute("docker", ["logs", "--tail", "40", name], { timeout });
+      throw new Error(`The controller login failed:\n${logs.stdout}${logs.stderr}`);
+    }
+    const login = await attachLogin(name, timeout);
+    if (await login.ready()) return login;
+    await delay(2000);
+  }
+  await docker(["rm", "--force", name], timeout);
+  throw new Error("The controller login did not open in time");
+};

package/src/controller-session.ts

@@ -0,0 +1,298 @@
+import { createHash, randomUUID } from "node:crypto";
+import { copyFile, cp, mkdir, readdir, readFile, rm, writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { z } from "zod";
+import type { ResolvedConfig } from "./config";
+import { controllerResultSchema, explicitDownload, loginCommandSchema } from "./controller-online";
+import {
+  createCodesysWorker,
+  withWorkerLock,
+  withWorkerShutdown,
+  writeJson,
+} from "./host/codesys-worker";
+import { toWindowsPath } from "./host/windows-path";
+import { loadSources } from "./sources";
+
+// Vendor code/data IDs are .NET Guid values derived from the compiler's data;
+// they do not carry RFC UUID version/variant bits.
+const guid = z.string().regex(/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/i);
+const hash = z.string().regex(/^[a-f0-9]{64}$/);
+const pointerSchema = z.strictObject({
+  schemaVersion: z.literal(1),
+  generation: z.uuid(),
+});
+const baselineSchema = controllerResultSchema.extend({
+  objects: z.array(z.record(z.string(), z.unknown())),
+  files: z.record(z.string(), hash),
+});
+const sha256 = (data: Uint8Array) => createHash("sha256").update(data).digest("hex");
+
+const guidBytes = (value: string): Buffer => {
+  const bytes = Buffer.from(value.replaceAll("-", ""), "hex");
+  bytes.subarray(0, 4).reverse();
+  bytes.subarray(4, 6).reverse();
+  bytes.subarray(6, 8).reverse();
+  return bytes;
+};
+
+/** Hash the complete project directory, including the vendor's downloaded reference. */
+const projectFiles = async (directory: string): Promise<Record<string, string>> => {
+  const files: Record<string, string> = {};
+  const visit = async (folder: string, prefix: string) => {
+    for (const item of await readdir(folder, { withFileTypes: true })) {
+      const name = prefix + item.name;
+      if (item.isSymbolicLink()) {
+        throw new Error(`Online project state contains a symlink: ${name}`);
+      }
+      if (item.isDirectory()) {
+        await visit(resolve(folder, item.name), `${name}/`);
+      } else if (item.isFile()) {
+        files[name] = sha256(await readFile(resolve(folder, item.name)));
+      }
+    }
+  };
+  await visit(directory, "");
+  return Object.fromEntries(Object.entries(files).sort(([a], [b]) => a.localeCompare(b)));
+};
+
+/** Load the committed generation and prove it still matches this image, template and target. */
+const readBaseline = async (
+  root: string,
+  expected: Pick<z.infer<typeof baselineSchema>, "imageId" | "templateHash" | "target">,
+) => {
+  const pointer = pointerSchema.parse(
+    JSON.parse(await readFile(resolve(root, "current.json"), "utf8")),
+  );
+  const previous = resolve(root, "generations", pointer.generation);
+  const baseline = baselineSchema.parse(
+    JSON.parse(await readFile(resolve(previous, "manifest.json"), "utf8")),
+  );
+  if (
+    baseline.generation !== pointer.generation ||
+    baseline.imageId !== expected.imageId ||
+    baseline.templateHash !== expected.templateHash ||
+    JSON.stringify(baseline.target) !== JSON.stringify(expected.target)
+  ) {
+    throw new Error(
+      `Downloaded baseline uses a different image, template or controller; ${explicitDownload}`,
+    );
+  }
+  const project = resolve(previous, "project");
+  if (JSON.stringify(await projectFiles(project)) !== JSON.stringify(baseline.files)) {
+    throw new Error(`Saved online project/reference files changed; ${explicitDownload}`);
+  }
+  return { baseline, project };
+};
+
+/** Called inside the builder container while its output-directory flock is held. */
+export const runControllerSession = async (
+  config: ResolvedConfig,
+  operation: "download" | "online-change" | "inspect",
+  options: {
+    imageId: string;
+    operationId: string;
+    initializeUser?: boolean;
+    read?: string[];
+  },
+) => {
+  if (!config.online) {
+    throw new Error("Controller operations require online settings");
+  }
+  const root = resolve(config.outDir, ".codesys/controller");
+  await mkdir(root, { recursive: true });
+  const resultPath = resolve(root, "result.json");
+  await rm(resultPath, { force: true });
+  const templateHash = sha256(await readFile(config.template));
+  const { network, gateway, device } = config.online;
+  // A different development controller needs a fresh download from the template.
+  const target = { network, gateway, device, controller: config.controller };
+  const previous =
+    operation === "download"
+      ? undefined
+      : await readBaseline(root, { imageId: options.imageId, templateHash, target });
+  const baseline = previous?.baseline;
+  if (options.initializeUser && operation !== "download") {
+    throw new Error("Initial user creation requires an explicit download");
+  }
+  const generation = randomUUID();
+  const candidate = resolve(root, "generations", generation);
+  const project = resolve(candidate, "project", "Application.project");
+  await mkdir(resolve(candidate, "project"), { recursive: true });
+  if (previous) {
+    await cp(previous.project, resolve(candidate, "project"), {
+      recursive: true,
+    });
+  } else {
+    await copyFile(config.template, project);
+  }
+  const jobConfig = {
+    ...config,
+    outDir: resolve(root, "jobs", options.operationId),
+  };
+  const requestDirectory = resolve(jobConfig.outDir, ".codesys/controller");
+  await mkdir(requestDirectory, { recursive: true });
+  const sources = operation === "inspect" ? undefined : await loadSources(config);
+  const request = {
+    libraries: await Promise.all(
+      (config.libraries ?? []).map(async (library) => ({
+        ...library,
+        path: await toWindowsPath(library.path, config.codesys.wine),
+      })),
+    ),
+    ...sources,
+    task: config.task,
+    ...(config.tasks && { tasks: config.tasks }),
+    removeObjects: config.removeObjects,
+    symbols: config.symbols,
+    operation,
+    initializeUser: options.initializeUser ?? false,
+    online: config.online,
+    controller: config.controller,
+    project: await toWindowsPath(project, config.codesys.wine),
+    progress: await toWindowsPath(resolve(requestDirectory, "progress.log"), config.codesys.wine),
+    baseline,
+    read: options.read ?? [],
+  };
+  await writeFile(resolve(requestDirectory, "request.json"), JSON.stringify(request, null, 2));
+  const worker = createCodesysWorker(jobConfig);
+  return withWorkerShutdown(jobConfig, worker, async () => {
+    const result = await withWorkerLock(jobConfig, async () => {
+      const session = await worker.launch();
+      await worker.request(session, { action: "online" }, config.timeouts.build);
+      return z
+        .object({
+          applicationGuid: guid,
+          application: z.string().optional(),
+          controllerIds: z.strictObject({ codeId: guid, dataId: guid }),
+          state: z.string(),
+          values: z.record(z.string(), z.string()),
+        })
+        .parse(JSON.parse(await readFile(resolve(requestDirectory, "result.json"), "utf8")));
+    });
+    const receipt = controllerResultSchema.parse({
+      ...result,
+      application: result.application ?? baseline?.application,
+      schemaVersion: 1,
+      operationId: options.operationId,
+      operation,
+      imageId: options.imageId,
+      templateHash,
+      target,
+      generation: operation === "inspect" ? baseline?.generation : generation,
+    });
+    if (operation !== "inspect") {
+      const files = await projectFiles(resolve(candidate, "project"));
+      if (!Object.keys(files).some((name) => name.endsWith(".compileinfo"))) {
+        throw new Error(
+          "CODESYS acknowledged the operation but no downloaded compiler reference was saved; candidate is retained for recovery",
+        );
+      }
+      const bootIds = Object.keys(files).filter((name) =>
+        name.endsWith(`.${receipt.applicationGuid}.bootinfo_guids`),
+      );
+      const expectedBootIds = Buffer.concat([
+        guidBytes(receipt.controllerIds.codeId),
+        guidBytes(receipt.controllerIds.dataId),
+      ]);
+      const bootReference = bootIds[0]?.replace(/_guids$/, "") ?? "";
+      const downloadedReference = bootReference.replace(/\.bootinfo$/, ".compileinfo");
+      if (
+        bootIds.length !== 1 ||
+        !files[bootReference] ||
+        files[bootReference] === sha256(new Uint8Array()) ||
+        files[bootReference] !== files[downloadedReference] ||
+        !(await readFile(resolve(candidate, "project", bootIds[0] ?? ""))).equals(expectedBootIds)
+      ) {
+        throw new Error(
+          "CODESYS acknowledged the operation but matching boot reference was not saved; candidate is retained for recovery",
+        );
+      }
+      await writeJson(resolve(candidate, "manifest.json"), {
+        ...receipt,
+        objects: sources?.objects,
+        files,
+      });
+      // Each generation is immutable. A single atomic pointer commits it only
+      // after controller acknowledgement and matching downloaded/boot references.
+      await writeJson(resolve(root, "current.json"), {
+        schemaVersion: 1,
+        generation,
+      });
+    }
+    await writeJson(resultPath, receipt);
+    return receipt;
+  }).finally(async () => {
+    if (operation === "inspect") {
+      await rm(candidate, { recursive: true, force: true });
+    }
+  });
+};
+
+/**
+ * Called inside the builder container: holds one login to the running application, made
+ * from the committed baseline, and serves its commands on `port` until a DELETE closes it.
+ */
+export const serveControllerLogin = async (
+  config: ResolvedConfig,
+  options: { imageId: string; port: number },
+) => {
+  if (!config.online) {
+    throw new Error("Controller logins require online settings");
+  }
+  const root = resolve(config.outDir, ".codesys/controller");
+  const { network, gateway, device } = config.online;
+  const { baseline, project } = await readBaseline(root, {
+    imageId: options.imageId,
+    templateHash: sha256(await readFile(config.template)),
+    target: { network, gateway, device, controller: config.controller },
+  });
+  const jobConfig = { ...config, outDir: resolve(root, "login") };
+  await rm(jobConfig.outDir, { recursive: true, force: true });
+  // CODESYS writes into an open project, and the committed baseline must not change.
+  await cp(project, resolve(jobConfig.outDir, "project"), { recursive: true });
+  const worker = createCodesysWorker(jobConfig);
+  await withWorkerShutdown(jobConfig, worker, () =>
+    withWorkerLock(jobConfig, async () => {
+      const session = await worker.launch();
+      const send = (command: Record<string, unknown>) =>
+        worker.request(session, { action: "login", arguments: command }, config.timeouts.build);
+      await send({
+        command: "open",
+        project: await toWindowsPath(
+          resolve(jobConfig.outDir, "project", "Application.project"),
+          config.codesys.wine,
+        ),
+        online: config.online,
+        baseline,
+      });
+      const closed = Promise.withResolvers<void>();
+      // The worker has one mailbox, so commands run one at a time.
+      let previous: Promise<unknown> = Promise.resolve();
+      const server = Bun.serve({
+        port: options.port,
+        idleTimeout: 0,
+        fetch: async (request) => {
+          if (request.method === "GET") return Response.json({ ok: true });
+          const close = request.method === "DELETE";
+          const command = close
+            ? { command: "close" }
+            : loginCommandSchema.parse(await request.json());
+          const result = previous.then(() => send(command));
+          previous = result.catch(() => undefined);
+          try {
+            return Response.json({ ok: true, result: await result });
+          } catch (error) {
+            // The worker reports a Python traceback; its last line names the failure.
+            const message = error instanceof Error ? error.message : String(error);
+            const reason = message.trim().split("\n").at(-1) ?? message;
+            return Response.json({ ok: false, error: reason.replace(/^\w+: /, "") });
+          } finally {
+            if (close) closed.resolve();
+          }
+        },
+      });
+      await closed.promise;
+      await server.stop();
+    }),
+  );
+};

package/src/diagnostics.ts

@@ -0,0 +1,68 @@
+import { z } from "zod";
+
+export const compilerDiagnosticSchema = z
+  .object({
+    category: z.string(),
+    text: z.string(),
+    severity: z.string().nullable(),
+    project: z.string().nullable(),
+    object: z
+      .object({
+        name: z.string(),
+        guid: z.string(),
+        path: z.array(z.string()),
+        /** Verified against this message project's active application GUID. */
+        isApplicationChild: z.boolean().nullable(),
+      })
+      .passthrough()
+      .nullable(),
+    /** Opaque vendor position. It must not be decoded as a line or column. */
+    position: z.string().nullable(),
+    positionText: z.string().nullable(),
+    positionOffset: z.int().nullable(),
+    length: z.int().nullable(),
+    prefix: z.string().nullable(),
+    number: z.int().nullable(),
+  })
+  .passthrough();
+
+export type CodesysCompilerDiagnostic = z.infer<typeof compilerDiagnosticSchema>;
+
+/** Preserves vendor diagnostics as the cause of a buildProject failure. */
+export class CodesysCompilerError extends Error {
+  constructor(
+    message: string,
+    readonly diagnostics: readonly CodesysCompilerDiagnostic[],
+  ) {
+    super(message);
+    this.name = "CodesysCompilerError";
+  }
+}
+
+// A failed container job publishes diagnostics separately from its successful build receipt.
+export const buildFailureFile = ".codesys/docker/failure.json";
+/** Why the last download, online change or inspection failed, for the host to report. */
+export const controllerFailureFile = ".codesys/controller/failure.txt";
+export const buildFailureSchema = z.strictObject({
+  operationId: z.uuid(),
+  message: z.string(),
+  diagnostics: z.array(compilerDiagnosticSchema),
+});
+
+/** Keep the primary compiler location and the shutdown context across the Docker boundary. */
+export function describeBuildFailure(cause: unknown) {
+  const messages: string[] = [];
+  let diagnostics: readonly CodesysCompilerDiagnostic[] = [];
+  let current = cause;
+  while (current instanceof Error) {
+    messages.push(current.message);
+    if (current instanceof AggregateError) {
+      // withWorkerShutdown puts the primary failure in cause and secondary failures in errors.
+      for (const secondary of current.errors.slice(1))
+        messages.push(secondary instanceof Error ? secondary.message : String(secondary));
+    }
+    if (current instanceof CodesysCompilerError) diagnostics = current.diagnostics;
+    current = current.cause;
+  }
+  return { message: messages.length ? messages.join("\n") : String(cause), diagnostics };
+}