@tsplc/build 0.0.0-stage → 0.2.0

package/src/__tests__/fixtures/xml/fb-state-machine.xml

@@ -0,0 +1,86 @@
+<?xml version="1.0" encoding="utf-8"?>
+<project xmlns="http://www.plcopen.org/xml/tc6_0200" xmlns:xhtml="http://www.w3.org/1999/xhtml">
+  <fileHeader companyName="" productName="CODESYS" productVersion="CODESYS V3.5 SP21" creationDateTime="<NORMALIZED>" />
+  <contentHeader name="FB_StateMachine" modificationDateTime="<NORMALIZED>">
+    <coordinateInfo>
+      <fbd><scaling x="1" y="1" /></fbd>
+      <ld><scaling x="1" y="1" /></ld>
+      <sfc><scaling x="1" y="1" /></sfc>
+    </coordinateInfo>
+  </contentHeader>
+  <types>
+    <dataTypes />
+    <pous>
+      <pou name="FB_StateMachine" pouType="functionBlock">
+        <interface>
+        <inputVars>
+          <variable name="bExecute">
+            <type><BOOL /></type>
+            <documentation><xhtml xmlns="http://www.w3.org/1999/xhtml">Rising edge starts cycle</xhtml></documentation>
+          </variable>
+          <variable name="tTimeout">
+            <type><TIME /></type>
+            <initialValue><simpleValue value="T#5s" /></initialValue>
+            <documentation><xhtml xmlns="http://www.w3.org/1999/xhtml">Operation timeout</xhtml></documentation>
+          </variable>
+        </inputVars>
+        <outputVars>
+          <variable name="bDone">
+            <type><BOOL /></type>
+            <documentation><xhtml xmlns="http://www.w3.org/1999/xhtml">Cycle complete</xhtml></documentation>
+          </variable>
+          <variable name="bBusy">
+            <type><BOOL /></type>
+            <documentation><xhtml xmlns="http://www.w3.org/1999/xhtml">Cycle in progress</xhtml></documentation>
+          </variable>
+          <variable name="bErr">
+            <type><BOOL /></type>
+            <documentation><xhtml xmlns="http://www.w3.org/1999/xhtml">Cycle errored</xhtml></documentation>
+          </variable>
+          <variable name="nErrId">
+            <type><INT /></type>
+            <documentation><xhtml xmlns="http://www.w3.org/1999/xhtml">Error ID</xhtml></documentation>
+          </variable>
+        </outputVars>
+        <localVars>
+          <variable name="nState">
+            <type><INT /></type>
+            <initialValue><simpleValue value="0" /></initialValue>
+            <documentation><xhtml xmlns="http://www.w3.org/1999/xhtml">State machine pointer</xhtml></documentation>
+          </variable>
+          <variable name="fbTimer">
+            <type><derived name="TON" /></type>
+            <documentation><xhtml xmlns="http://www.w3.org/1999/xhtml">Timeout watchdog</xhtml></documentation>
+          </variable>
+        </localVars>
+      </interface>
+        <body>
+          <ST>
+            <xhtml xmlns="http://www.w3.org/1999/xhtml"><![CDATA[CASE nState OF
+    0: (* IDLE *)
+        IF bExecute THEN
+            nState := 10;
+        END_IF
+    10: (* WORKING *)
+        bBusy := TRUE;
+        fbTimer(IN := TRUE, PT := tTimeout);
+        IF fbTimer.Q THEN
+            nState := 99;
+            nErrId := 100;
+        END_IF
+    90: (* DONE *)
+        bDone := TRUE;
+        bBusy := FALSE;
+    99: (* ERROR *)
+        bErr := TRUE;
+        bBusy := FALSE;
+END_CASE]]></xhtml>
+          </ST>
+        </body>
+      </pou>
+    </pous>
+  </types>
+  <instances>
+    <configurations />
+  </instances>
+</project>

package/src/__tests__/fixtures/xml/prg-cyclic.xml

@@ -0,0 +1,44 @@
+<?xml version="1.0" encoding="utf-8"?>
+<project xmlns="http://www.plcopen.org/xml/tc6_0200" xmlns:xhtml="http://www.w3.org/1999/xhtml">
+  <fileHeader companyName="" productName="CODESYS" productVersion="CODESYS V3.5 SP21" creationDateTime="<NORMALIZED>" />
+  <contentHeader name="PRG_Main" modificationDateTime="<NORMALIZED>">
+    <coordinateInfo>
+      <fbd><scaling x="1" y="1" /></fbd>
+      <ld><scaling x="1" y="1" /></ld>
+      <sfc><scaling x="1" y="1" /></sfc>
+    </coordinateInfo>
+  </contentHeader>
+  <types>
+    <dataTypes />
+    <pous>
+      <pou name="PRG_Main" pouType="program">
+        <interface>
+        <localVars>
+          <variable name="fbWorker">
+            <type><derived name="FB_StateMachine" /></type>
+            <documentation><xhtml xmlns="http://www.w3.org/1999/xhtml">Cycle worker</xhtml></documentation>
+          </variable>
+          <variable name="bStart">
+            <type><BOOL /></type>
+            <documentation><xhtml xmlns="http://www.w3.org/1999/xhtml">Operator start button</xhtml></documentation>
+          </variable>
+        </localVars>
+      </interface>
+        <body>
+          <ST>
+            <xhtml xmlns="http://www.w3.org/1999/xhtml"><![CDATA[fbWorker(
+    bExecute := bStart,
+);
+
+IF fbWorker.bDone THEN
+    bStart := FALSE;
+END_IF]]></xhtml>
+          </ST>
+        </body>
+      </pou>
+    </pous>
+  </types>
+  <instances>
+    <configurations />
+  </instances>
+</project>

package/src/artifacts.ts

@@ -0,0 +1,77 @@
+import { copyFile, cp, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { z } from "zod";
+import { cyclicTasksSchema } from "./config";
+
+export const buildFiles = {
+  project: "Application.project",
+  output: "runtime/Application.app",
+  checksum: "runtime/Application.crc",
+  receipt: "build.json",
+  // Normalized EDS files of a generated device tree, imported by the worker.
+  devices: "eds",
+  // With a generated device tree: the project plus the descriptions an IDE needs.
+  archive: "Application.projectarchive",
+} as const;
+
+const receiptSchema = z.object({
+  mode: z.literal("build"),
+  application: z.string().regex(/^[A-Za-z_][A-Za-z_0-9]*$/),
+  tasks: cyclicTasksSchema.optional(),
+});
+
+/** A receipt is published last, after every artifact has been checked and replaced. */
+export const readBuild = async (directory: string) => {
+  const receipt = receiptSchema.safeParse(
+    JSON.parse(await readFile(resolve(directory, buildFiles.receipt), "utf8")),
+  );
+  if (!receipt.success) {
+    throw new Error("CODESYS did not produce a valid build receipt", {
+      cause: receipt.error,
+    });
+  }
+  for (const file of [buildFiles.project, buildFiles.output, buildFiles.checksum]) {
+    const artifact = await stat(resolve(directory, file));
+    if (!artifact.isFile() || artifact.size === 0) {
+      throw new Error(`CODESYS produced an empty artifact: ${file}`);
+    }
+  }
+  return {
+    ...receipt.data,
+    directory,
+    project: resolve(directory, buildFiles.project),
+    output: resolve(directory, buildFiles.output),
+    checksum: resolve(directory, buildFiles.checksum),
+  };
+};
+
+/** Publish a verified IDE build, with the completion receipt written last. */
+export const publishBuild = async (
+  compiled: Awaited<ReturnType<typeof readBuild>>,
+  outDir: string,
+) => {
+  await copyFile(compiled.project, resolve(outDir, buildFiles.project));
+  await rm(resolve(outDir, "runtime"), { recursive: true, force: true });
+  await rename(resolve(compiled.directory, "runtime"), resolve(outDir, "runtime"));
+  await rm(resolve(outDir, buildFiles.archive), { force: true });
+  await cp(
+    resolve(compiled.directory, buildFiles.archive),
+    resolve(outDir, buildFiles.archive),
+  ).catch((cause: unknown) => {
+    if (!(cause && typeof cause === "object" && "code" in cause && cause.code === "ENOENT"))
+      throw cause;
+  });
+  await writeFile(
+    resolve(outDir, buildFiles.receipt),
+    JSON.stringify(
+      {
+        mode: "build",
+        application: compiled.application,
+        ...(compiled.tasks && { tasks: compiled.tasks }),
+      },
+      null,
+      2,
+    ),
+  );
+  return readBuild(outDir);
+};

package/src/build.ts

@@ -0,0 +1,87 @@
+import { createHash } from "node:crypto";
+import { access, copyFile, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { buildFiles, publishBuild, readBuild } from "./artifacts";
+import { dockerImage, type ResolvedConfig } from "./config";
+import { buildInDocker } from "./docker-build";
+import { createCodesysWorker, withWorkerLock } from "./host/codesys-worker";
+import { loadSources } from "./sources";
+import { toWindowsPath } from "./host/windows-path.ts";
+
+export const buildProject = async (config: ResolvedConfig) => {
+  if (!config.docker) throw new Error("Builds require a Docker builder image.");
+  return buildInDocker(config, dockerImage);
+};
+
+/** The container runner owns Wine; this operation is not a public host build. */
+export const buildInContainer = async (config: ResolvedConfig) => {
+  return withWorkerLock(config, async () => {
+    // Invalidate the previous build before validation, so run cannot deploy stale
+    // output after a failed rebuild. Keep the last project available for inspection.
+    await rm(resolve(config.outDir, buildFiles.receipt), { force: true });
+    const sources = await loadSources(config);
+    await access(config.template);
+    const worker = createCodesysWorker(config);
+    const session = await worker.launch();
+    const directory = resolve(config.outDir, ".codesys/build");
+    await rm(directory, { recursive: true, force: true });
+    await mkdir(resolve(directory, "runtime"), { recursive: true });
+    const template = resolve(directory, "Template.project");
+    await copyFile(config.template, template);
+    // CODESYS imports each adapter's EDS from the build directory.
+    const deviceTree = config.deviceTree && {
+      ...config.deviceTree,
+      devices: await Promise.all(
+        config.deviceTree.devices.map(async (device) => {
+          const eds = `${buildFiles.devices}/${device.name}.eds`;
+          await mkdir(resolve(directory, buildFiles.devices), { recursive: true });
+          await writeFile(resolve(directory, eds), device.eds);
+          // The digest keys project reuse on the description's content.
+          return { ...device, eds, sha256: createHash("sha256").update(device.eds).digest("hex") };
+        }),
+      ),
+    };
+    const request = {
+      libraryReferences: config.libraryReferences,
+      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,
+      ...(deviceTree && { deviceTree }),
+      ...(config.controller && { controller: config.controller }),
+      mode: "build",
+      output: buildFiles.output,
+      project: buildFiles.project,
+      archive: buildFiles.archive,
+      receipt: buildFiles.receipt,
+      template: "Template.project",
+      templateHash: createHash("sha256")
+        .update(await readFile(template))
+        .digest("hex"),
+    };
+    await writeFile(resolve(directory, "request.json"), JSON.stringify(request, null, 2));
+    console.log(`CODESYS build: ${config.outDir}`);
+    try {
+      await worker.request(session, { action: "build" }, config.timeouts.build);
+      const compiled = await readBuild(directory);
+      if (config.tasks && JSON.stringify(compiled.tasks) !== JSON.stringify(config.tasks)) {
+        throw new Error("CODESYS build receipt does not match the requested task plan");
+      }
+      // Builds and runs share the lock. Removing the receipt above keeps a failed
+      // publication from looking complete even if only some files were replaced.
+      return await publishBuild(compiled, config.outDir);
+    } catch (cause) {
+      throw new Error(
+        `CODESYS build failed. Inspect ${directory}/progress.log, error.txt and ${session.directory}/codesys.log`,
+        { cause },
+      );
+    }
+  });
+};

package/src/cli.ts

@@ -0,0 +1,116 @@
+#!/usr/bin/env bun
+import { parseArgs } from "node:util";
+import { deviceTree } from "@tsplc/typegen";
+import { loadHardware, resolveIo } from "@tsplc/typegen/hardware";
+import { controllerFor, loadTsplcConfig, rawBuildConfig } from "@tsplc/config";
+import { buildProject } from "./build.ts";
+import { resolveConfig } from "./config.ts";
+import { inspectController, updateController } from "./controller-online.ts";
+import { configureDocker, configureRuntime } from "./docker-build.ts";
+import { installLibraries } from "./libraries.ts";
+import { runProject } from "./run.ts";
+import { loadSources } from "./sources.ts";
+
+async function main() {
+  const { values, positionals } = parseArgs({
+    allowPositionals: true,
+    options: {
+      config: { type: "string" },
+      help: { type: "boolean", short: "h" },
+      read: { type: "string", multiple: true },
+      "initialize-user": { type: "boolean" },
+      "frozen-lockfile": { type: "boolean" },
+      runtime: { type: "boolean" },
+    },
+  });
+  const command = positionals[0];
+  const commands = new Set([
+    "configure",
+    "install",
+    "check",
+    "build",
+    "run",
+    "download",
+    "online-change",
+    "inspect",
+  ]);
+  if (positionals.length > 1) throw new Error("Specify one command.");
+  if (!command || values.help) {
+    console.log(
+      "tsplc-build configure|install|check|build|run|download|online-change|inspect [--config tsplc.config.ts] [--read symbol] [--runtime]",
+    );
+    return;
+  }
+  if (!commands.has(command)) throw new Error(`Unknown command ${command}.`);
+  if (values.runtime && command !== "configure")
+    throw new Error("--runtime applies only to configure.");
+  if (command === "configure") {
+    await (values.runtime ? configureRuntime() : configureDocker());
+    return;
+  }
+  const { config, configFile, root } = await loadTsplcConfig(values.config);
+  if (command === "install") {
+    const libraries = await installLibraries(config.dependencies, root, {
+      frozen: values["frozen-lockfile"],
+    });
+    console.log(`Installed ${libraries.length} CODESYS libraries.`);
+    return;
+  }
+  if (!config.build) throw new Error("Configure build options in tsplc.config.ts.");
+  if (command === "inspect") {
+    // Inspection only needs connection/baseline settings; it remains usable
+    // without sources, EDS descriptors or installed library payloads.
+    console.log(
+      JSON.stringify(
+        await inspectController(
+          resolveConfig(
+            { ...config.build, controller: controllerFor(config, command) },
+            configFile,
+          ),
+          values.read,
+        ),
+        null,
+        2,
+      ),
+    );
+    return;
+  }
+  if (config.compiler)
+    throw new Error("Use tsplc for TypeScript projects. tsplc-build accepts raw Structured Text.");
+  const build = rawBuildConfig(config);
+  const hardware = await loadHardware(config, root);
+  const io = resolveIo(config, hardware);
+  if (command === "check") {
+    const sources = await loadSources(resolveConfig({ ...build, io }, configFile));
+    console.log(`Validated ${sources.objects.length} Structured Text objects.`);
+    return;
+  }
+  const libraries = await installLibraries(config.dependencies, root, {
+    frozen: values["frozen-lockfile"],
+  });
+  const settings = resolveConfig(
+    {
+      ...build,
+      libraries,
+      io,
+      deviceTree: await deviceTree(config, hardware),
+      controller: controllerFor(config, command),
+    },
+    configFile,
+  );
+  if (command === "build") await buildProject(settings);
+  else if (command === "run") {
+    await buildProject(settings);
+    await runProject(settings, config.name);
+  } else if (command === "download" || command === "online-change")
+    await updateController(settings, command, {
+      initializeUser: values["initialize-user"],
+      read: values.read,
+    });
+}
+try {
+  await main();
+} catch (cause) {
+  console.error(cause instanceof Error ? cause.message : String(cause));
+  process.exitCode = 1;
+}

package/src/config.ts

@@ -0,0 +1,12 @@
+export {
+  configSchema,
+  controllerSchema,
+  cyclicTasksSchema,
+  dockerImage,
+  defineBuildConfig as defineConfig,
+  resolveConfig,
+  loadConfig,
+  type CodesysBuildConfig,
+  type ResolvedConfig,
+  type CyclicTask,
+} from "@tsplc/config/build";