@tsplc/build 0.0.0-stage → 0.2.0

package/src/docker-build.ts

@@ -0,0 +1,163 @@
+import { execFile } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { cp, mkdir, mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { resolve } from "node:path";
+import { promisify } from "node:util";
+import { readBuild } from "./artifacts";
+import { dockerImage, type ResolvedConfig } from "./config";
+import { prepareDockerContext } from "./docker-context.ts";
+import { buildFailureFile, buildFailureSchema, CodesysCompilerError } from "./diagnostics.ts";
+import { prepareContainerRun, runDocker } from "./docker-run.ts";
+import { packageDirectory } from "./package-path.ts";
+
+const execute = promisify(execFile);
+
+/** Install the IDE and its prerequisites in the Docker builder image. */
+export const configureDocker = async () => {
+  const image = dockerImage;
+  const { stdout } = await execute(
+    "docker",
+    ["info", "--format", "{{.OSType}}/{{.Architecture}}"],
+    { timeout: 30_000 },
+  ).catch((cause: unknown) => {
+    throw new Error("Cannot connect to Docker. Install and start Docker Desktop or Docker Engine", {
+      cause,
+    });
+  });
+  const architecture = stdout.trim();
+  const arm = architecture === "linux/aarch64" || architecture === "linux/arm64";
+  if (!arm && architecture !== "linux/x86_64" && architecture !== "linux/amd64") {
+    throw new Error("The builder requires a Linux Docker server on ARM64 or AMD64");
+  }
+  const context = await mkdtemp(resolve(tmpdir(), "codesys-installer-"));
+  let buildContext: string | undefined;
+  try {
+    buildContext = await prepareDockerContext();
+    const cache = resolve(context, "winetricks");
+    await mkdir(cache);
+    if (process.env["CODESYS_WINETRICKS_CACHE"]) {
+      await cp(process.env["CODESYS_WINETRICKS_CACHE"], cache, {
+        recursive: true,
+      });
+    }
+    console.log(
+      `Preparing Docker builder (${image}). Downloading and installing CODESYS 3.5.22.30 and prerequisites.`,
+    );
+    await runDocker(
+      [
+        "build",
+        "--platform",
+        "linux/amd64",
+        "--build-arg",
+        `SETUP_BASE=${arm ? "arm-setup" : "base"}`,
+        "--build-arg",
+        `SETUP_PLATFORM=${arm ? "linux/arm64" : "linux/amd64"}`,
+        "--build-arg",
+        "INSTALLER_SOURCE=installer-download",
+        "--progress",
+        "plain",
+        "--build-context",
+        `installer=${context}`,
+        "-f",
+        resolve(buildContext, "docker/Dockerfile"),
+        "-t",
+        image,
+        buildContext,
+      ],
+      (status) =>
+        `Docker configuration failed (${status}). Review the image-build output and run tsplc configure again`,
+    );
+    return image;
+  } finally {
+    await Promise.all([
+      rm(context, { recursive: true, force: true }),
+      ...(buildContext ? [rm(buildContext, { recursive: true, force: true })] : []),
+    ]);
+  }
+};
+
+export const runtimeImage = "tsplc-control-linux-sl:4.22.0.0";
+
+/** Build the local CODESYS Control for Linux SL runtime, the same device as a production build. */
+export const configureRuntime = async () => {
+  const context = resolve(packageDirectory, "docker/control-linux-sl");
+  console.log(`Preparing the local PLC runtime (${runtimeImage}).`);
+  await runDocker(
+    ["build", "--platform", "linux/amd64", "--progress", "plain", "-t", runtimeImage, context],
+    (status) => `Runtime image build failed (${status}). Review the image-build output`,
+  );
+  return runtimeImage;
+};
+
+export const gatewayImage = "tsplc-edge-gateway:4.22.0.0";
+
+/** Build the CODESYS Edge Gateway that builder containers reach a plant controller through. */
+export const configureGateway = async () => {
+  const context = resolve(packageDirectory, "docker/edge-gateway");
+  console.log(`Preparing the CODESYS gateway (${gatewayImage}).`);
+  await runDocker(
+    ["build", "--platform", "linux/amd64", "--progress", "plain", "-t", gatewayImage, context],
+    (status) => `Gateway image build failed (${status}). Review the image-build output`,
+  );
+  return gatewayImage;
+};
+
+export const buildInDocker = async (config: ResolvedConfig, image: string) => {
+  const requestDirectory = await mkdtemp(resolve(tmpdir(), "codesys-docker-"));
+  try {
+    const operationId = randomUUID();
+    await mkdir(config.outDir, { recursive: true });
+    const failurePath = resolve(config.outDir, buildFailureFile);
+    await rm(failurePath, { force: true });
+    const args = [
+      "run",
+      "--rm",
+      ...(await prepareContainerRun(config, requestDirectory, { network: "none", sources: true })),
+      image,
+      "--request",
+      "/input/config.json",
+      "--operation-id",
+      operationId,
+    ];
+    console.log(`Building with Docker (${image})`);
+    try {
+      await runDocker(
+        args,
+        (status) =>
+          `Docker build failed (${status}). Run tsplc configure if the image is missing; inspect ${config.outDir}/.codesys/docker for compiler logs`,
+      );
+    } catch (cause) {
+      const message = cause instanceof Error ? cause.message : String(cause);
+      const failure = await readFile(failurePath, "utf8")
+        .then((text) => buildFailureSchema.parse(JSON.parse(text)))
+        .catch((error: unknown) => {
+          if (error instanceof Error && "code" in error && error.code === "ENOENT") return;
+          throw new AggregateError(
+            [cause, error],
+            `${message}. Invalid CODESYS failure metadata (${failurePath})`,
+            { cause: error },
+          );
+        });
+      if (!failure) throw cause;
+      if (failure.operationId !== operationId)
+        throw new Error(
+          `${message}. CODESYS failure metadata belongs to a different Docker build`,
+          {
+            cause,
+          },
+        );
+      if (cause instanceof Error) {
+        // The mapper keeps ordinary error messages as notes, while vendor
+        // diagnostics supply their own text. Preserve shutdown context there.
+        cause.message = `${message}\n${failure.message}`;
+        if (failure.diagnostics.length)
+          cause.cause = new CodesysCompilerError(failure.message, failure.diagnostics);
+      }
+      throw cause;
+    }
+    return await readBuild(config.outDir);
+  } finally {
+    await rm(requestDirectory, { recursive: true, force: true });
+  }
+};

package/src/docker-context.ts

@@ -0,0 +1,35 @@
+import { cp, mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { createRequire } from "node:module";
+import { tmpdir } from "node:os";
+import { dirname, resolve } from "node:path";
+import { packageDirectory } from "./package-path.ts";
+
+export async function prepareDockerContext() {
+  const context = await mkdtemp(resolve(tmpdir(), "tsplc-docker-"));
+  try {
+    for (const directory of ["src", "python", "docker", "runtime"])
+      await cp(resolve(packageDirectory, directory), resolve(context, directory), {
+        recursive: true,
+      });
+    const configRoot = resolve(
+      dirname(createRequire(import.meta.url).resolve("@tsplc/config/build")),
+      "..",
+    );
+    await mkdir(resolve(context, "shared-config"));
+    await cp(resolve(configRoot, "src"), resolve(context, "shared-config/src"), {
+      recursive: true,
+    });
+    await cp(resolve(configRoot, "templates"), resolve(context, "shared-config/templates"), {
+      recursive: true,
+    });
+    await cp(resolve(configRoot, "package.json"), resolve(context, "shared-config/package.json"));
+    await writeFile(
+      resolve(context, "package.json"),
+      JSON.stringify({ type: "module", dependencies: { zod: "4.3.6", jiti: "2.7.0" } }),
+    );
+    return context;
+  } catch (cause) {
+    await rm(context, { recursive: true, force: true });
+    throw cause;
+  }
+}

package/src/docker-run.ts

@@ -0,0 +1,103 @@
+import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { basename, posix, relative, resolve, sep } from "node:path";
+import type { ResolvedConfig } from "./config.ts";
+
+/** Run a Docker client command attached to this terminal and forward interruption to it. */
+export const runDocker = (args: string[], failure: (status: string | number | null) => string) =>
+  new Promise<void>((accept, reject) => {
+    const child = spawn("docker", args, {
+      stdio: ["inherit", process.env["TSPLC_LOG_STDERR"] === "1" ? 2 : "inherit", "inherit"],
+    });
+    const interrupt = () => child.kill("SIGINT");
+    const terminate = () => child.kill("SIGTERM");
+    process.on("SIGINT", interrupt);
+    process.on("SIGTERM", terminate);
+    const cleanup = () => {
+      process.off("SIGINT", interrupt);
+      process.off("SIGTERM", terminate);
+    };
+    child.once("error", (cause) => {
+      cleanup();
+      reject(
+        new Error("Cannot start Docker. Install and start Docker Desktop or Docker Engine", {
+          cause,
+        }),
+      );
+    });
+    child.once("exit", (code, signal) => {
+      cleanup();
+      if (code === 0) {
+        accept();
+      } else {
+        reject(new Error(failure(signal ?? code)));
+      }
+    });
+  });
+
+const bindMount = (source: string, target: string, readonly = false) =>
+  `type=bind,"source=${source.replaceAll('"', '""')}",target=${target}${readonly ? ",readonly" : ""}`;
+
+async function mountLibraries(libraries: ResolvedConfig["libraries"], directory: string) {
+  if (!libraries?.length) return undefined;
+  await mkdir(resolve(directory, "libraries"), { recursive: true });
+  return Promise.all(
+    libraries.map(async (library) => {
+      const data = await readFile(library.path);
+      if (createHash("sha256").update(data).digest("hex") !== library.sha256)
+        throw new Error(`Library changed after installation: ${library.title}`);
+      const filename = `${library.sha256}-${basename(library.path)}`;
+      await writeFile(resolve(directory, "libraries", filename), data);
+      return { ...library, path: `/input/libraries/${filename}` };
+    }),
+  );
+}
+
+/**
+ * Write the builder container's request and return the `docker run` options that precede
+ * the image; the caller chooses `--rm` or `--detach`. The request names only container paths;
+ * host paths enter through these mounts, and host-only Docker, CODESYS and runtime settings
+ * stay outside.
+ */
+export const prepareContainerRun = async (
+  config: ResolvedConfig,
+  requestDirectory: string,
+  options: { network: string; environment?: string[]; sources: boolean },
+) => {
+  await writeFile(
+    resolve(requestDirectory, "config.json"),
+    JSON.stringify({
+      ...config,
+      libraries: options.sources ? await mountLibraries(config.libraries, requestDirectory) : [],
+      configFile: undefined,
+      docker: undefined,
+      codesys: undefined,
+      sourceDir: "/sources",
+      entry: posix.resolve(
+        "/sources",
+        relative(config.sourceDir, config.entry).split(sep).join("/"),
+      ),
+      template: "/template.project",
+      outDir: "/output",
+      runtime: undefined,
+    }),
+  );
+  return [
+    "--init",
+    ...(config.docker?.cpuSet ? ["--cpuset-cpus", config.docker.cpuSet] : []),
+    "--network",
+    options.network,
+    ...(process.getuid && process.getgid
+      ? ["--user", `${process.getuid()}:${process.getgid()}`]
+      : []),
+    ...(options.environment ?? []).flatMap((name) => ["--env", name]),
+    "--mount",
+    bindMount(requestDirectory, "/input", true),
+    ...(options.sources ? ["--mount", bindMount(config.sourceDir, "/sources", true)] : []),
+    "--mount",
+    bindMount(config.template, "/template.project", true),
+    "--mount",
+    bindMount(config.outDir, "/output"),
+  ];
+};

package/src/host/codesys-command.ts

@@ -0,0 +1,45 @@
+export { commandArgumentSchema } from "@tsplc/config/build";
+import type { ResolvedConfig } from "../config";
+
+export const codesysCommandFilename = "run.cmd";
+
+// Keep arguments in the Windows command line: Wine's direct launcher loses the
+// quoting CODESYS needs around profile names containing spaces.
+export const codesysCommand = [
+  "@echo off",
+  "setlocal DisableDelayedExpansion",
+  '"%CODESYS_BUILD_EXE%" --profile="%CODESYS_BUILD_PROFILE%" --noUI --runscript="%CODESYS_BUILD_SCRIPT%"',
+  'set "CODESYS_BUILD_STATUS=%errorlevel%"',
+  'if not "%CODESYS_BUILD_STATUS%"=="0" echo CODESYS Windows exit status: %CODESYS_BUILD_STATUS%',
+  "exit /b %CODESYS_BUILD_STATUS%",
+  "",
+].join("\r\n");
+
+export const getHostCommand = (
+  config: Pick<ResolvedConfig["codesys"], "commandProcessor" | "wine">,
+  platform: NodeJS.Platform = process.platform,
+) => {
+  if (platform === "win32") {
+    return {
+      args: ["/d", "/c", codesysCommandFilename],
+      executable: config.commandProcessor,
+    };
+  }
+  const wine = config.wine?.binary ?? "wine";
+  const args = ["cmd", "/d", "/c", codesysCommandFilename];
+  // --noUI suppresses the IDE, but CODESYS can still allocate a Wine console.
+  // A private PTY makes Wine use its Unix console instead of a desktop window.
+  return {
+    args:
+      platform === "darwin"
+        ? ["-q", "/dev/null", wine, ...args]
+        : [
+            "-q",
+            "-e",
+            "-c",
+            [wine, ...args].map((argument) => `'${argument.replaceAll("'", "'\\''")}'`).join(" "),
+            "/dev/null",
+          ],
+    executable: "script",
+  };
+};

package/src/host/codesys-host.ts

@@ -0,0 +1,145 @@
+import { execFile, spawn } from "node:child_process";
+import { appendFileSync, constants, renameSync, writeFileSync } from "node:fs";
+import { access, open, readFile, rm, writeFile } from "node:fs/promises";
+import { delimiter, resolve } from "node:path";
+import { promisify } from "node:util";
+import { z } from "zod";
+import type { ResolvedConfig } from "../config";
+import { codesysCommand, codesysCommandFilename, getHostCommand } from "./codesys-command";
+import { toWindowsPath } from "./windows-path";
+
+const execute = promisify(execFile);
+const exitSchema = z.object({
+  pid: z.int().positive(),
+  code: z.int().nullable(),
+  signal: z.string().nullable(),
+});
+
+export const createCodesysHost = (config: ResolvedConfig) => {
+  const native = process.platform === "win32";
+  const { codesys, timeouts } = config;
+  const hostEnv = {
+    // Child processes inherit OS settings such as PATH and DISPLAY.
+    ...process.env,
+    WINEPREFIX: codesys.wine?.prefix,
+    WINEDEBUG: codesys.wine?.debug,
+    CODESYS_BUILD_NATIVE_EXIT: String(codesys.wine?.nativeExit ?? false),
+  };
+
+  /** Start the headless worker script; its launcher outlives this CLI process. */
+  const startWorker = async (directory: string) => {
+    if (!native) {
+      await execute(codesys.wine?.binary ?? "wine", ["--version"], {
+        env: hostEnv,
+        timeout: timeouts.hostCommand,
+      }).catch((cause: unknown) => {
+        throw new Error("Wine is missing. Install Wine; Winetricks alone cannot run CODESYS", {
+          cause,
+        });
+      });
+      const candidates = (process.env["PATH"] ?? "").split(delimiter);
+      const available = await Promise.all(
+        candidates.map((path) =>
+          access(resolve(path, "script"), constants.X_OK).then(
+            () => true,
+            () => false,
+          ),
+        ),
+      );
+      if (!available.some(Boolean)) {
+        throw new Error(
+          "Headless Wine builds require the script utility (install util-linux on Linux)",
+        );
+      }
+    }
+    await writeFile(resolve(directory, codesysCommandFilename), codesysCommand);
+    const env = {
+      ...hostEnv,
+      CODESYS_BUILD_SCRIPT: await toWindowsPath(resolve(directory, "worker.py"), codesys.wine),
+      CODESYS_BUILD_SESSION: await toWindowsPath(directory, codesys.wine),
+      CODESYS_BUILD_EXE: await toWindowsPath(codesys.executable, codesys.wine),
+      CODESYS_BUILD_PROFILE: codesys.profile,
+    };
+    const launcher = getHostCommand(codesys);
+    const logPath = resolve(directory, "codesys.log");
+    const exitPath = resolve(directory, "launcher-exit.json");
+    await rm(exitPath, { force: true });
+    const log = await open(logPath, "w");
+    try {
+      const child = spawn(launcher.executable, launcher.args, {
+        cwd: directory,
+        detached: true,
+        windowsHide: true,
+        env,
+        stdio: ["ignore", log.fd, log.fd],
+      });
+      child.once("exit", (code, signal) => {
+        try {
+          appendFileSync(logPath, `\nCODESYS launcher exit status: ${signal ?? code}\n`);
+        } catch {
+          // A failed diagnostic write must preserve the original process failure.
+        }
+        try {
+          const temporary = `${exitPath}.${child.pid}.tmp`;
+          writeFileSync(temporary, JSON.stringify({ pid: child.pid, code, signal }));
+          renameSync(temporary, exitPath);
+        } catch {
+          // The log still records the exit if the optional status file cannot be published.
+        }
+      });
+      await new Promise<void>((resolve, reject) => {
+        child.once("error", reject);
+        child.once("spawn", resolve);
+      });
+      if (!child.pid) {
+        throw new Error("CODESYS launcher has no process ID");
+      }
+      child.unref();
+      return child.pid;
+    } finally {
+      await log.close();
+    }
+  };
+
+  return {
+    exitStatus: async (directory: string, pid: number) => {
+      const path = resolve(directory, "launcher-exit.json");
+      const value = await readFile(path, "utf8").catch((error: unknown) => {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT") return;
+        throw error;
+      });
+      if (value === undefined) return;
+      const status = exitSchema.parse(JSON.parse(value));
+      if (status.pid !== pid) return;
+      if (!native && status.code === 0 && status.signal === null) {
+        const logPath = resolve(directory, "codesys.log");
+        const log = (await readFile(logPath, "utf8"))
+          // Terminal color escapes must not hide a native assertion signature.
+          // eslint-disable-next-line no-control-regex
+          .replace(/\u001b\[[0-?]*[ -/]*[@-~]/g, "")
+          .replace(/\r/g, "");
+        // A Wine helper can abort under Rosetta while the main launcher returns 0.
+        // That command still failed; publishing its artifacts would hide the fault.
+        const assertion =
+          /^assertion failed \[[^\n]+\]:[^\n]*\n[ \t]*\(ThreadContext[^\n]*\)/m.exec(log);
+        if (assertion) {
+          throw new Error(
+            `Wine translation aborted: ${assertion[0].replace(/\s+/g, " ")}. See ${logPath}`,
+          );
+        }
+      }
+      return status;
+    },
+    startWorker,
+    terminate: async (pid: number) => {
+      if (native) {
+        await execute("taskkill.exe", ["/pid", String(pid), "/t", "/f"], {
+          env: hostEnv,
+          timeout: timeouts.hostCommand,
+        });
+        return;
+      }
+      process.kill(-pid, "SIGKILL");
+    },
+  };
+};