@tsplc/build 0.0.0-stage → 0.1.0

package/src/controller-online.ts

@@ -0,0 +1,143 @@
+import { execFile } from "node:child_process";
+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 { promisify } from "node:util";
+import { z } from "zod";
+import { controllerSchema, dockerImage, type ResolvedConfig } from "./config";
+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[];
+};
+
+const controllerOperation = async (
+  config: ResolvedConfig,
+  operation: ControllerResult["operation"],
+  options: ControllerUpdateOptions,
+): Promise<ControllerResult> => {
+  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 },
+    );
+  });
+  const imageId = imageIdSchema.parse(stdout.trim());
+  const templateHash = createHash("sha256")
+    .update(await readFile(config.template))
+    .digest("hex");
+  const operationId = randomUUID();
+  const target = {
+    network: config.online.network,
+    gateway: config.online.gateway,
+    device: config.online.device,
+    controller: config.controller,
+  };
+  const requestDirectory = await mkdtemp(resolve(tmpdir(), "codesys-controller-"));
+  const diagnostics = resolve(config.outDir, ".codesys/controller");
+  try {
+    await mkdir(config.outDir, { recursive: true });
+    await runDocker(
+      [
+        ...(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`,
+    );
+    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 });

package/src/controller-session.ts

@@ -0,0 +1,229 @@
+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 } 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; use an explicit download",
+    );
+  }
+  const project = resolve(previous, "project");
+  if (JSON.stringify(await projectFiles(project)) !== JSON.stringify(baseline.files)) {
+    throw new Error("Saved online project/reference files changed; use an explicit download");
+  }
+  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 });
+    }
+  });
+};

package/src/diagnostics.ts

@@ -0,0 +1,66 @@
+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";
+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 };
+}

package/src/docker-build.ts

@@ -0,0 +1,148 @@
+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 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 = [
+      ...(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;
+  }
+}