@tsplc/build 0.0.0-stage → 0.2.0

package/src/libraries.ts

@@ -0,0 +1,166 @@
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { basename, relative, resolve } from "node:path";
+import type { LibraryDependency } from "@tsplc/config";
+
+export const libraryRegistry = "https://store-archive.codesys.com/CODESYSLibs";
+const libraryFile = /\.(?:compiled-library(?:-v\d+)?|library)$/i;
+type Fetcher = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+export interface InstalledLibrary {
+  title: string;
+  company?: string;
+  version?: string;
+  namespace?: string;
+  path: string;
+  sha256: string;
+  url?: string;
+}
+interface LibraryLock {
+  version: 1;
+  dependencies: Record<string, InstalledLibrary>;
+}
+const hash = (data: Uint8Array) => createHash("sha256").update(data).digest("hex");
+const component = (name: string) => {
+  if (!name.trim() || /[/\\\0\r\n]/.test(name) || name === "." || name === "..")
+    throw new Error(`Invalid library registry component: ${name}.`);
+  return encodeURIComponent(name);
+};
+async function response(url: string, fetcher: Fetcher) {
+  const result = await fetcher(url, { signal: AbortSignal.timeout(30_000) });
+  if (!result.ok) throw new Error(`Library registry ${result.status}: ${url}`);
+  return result;
+}
+export async function libraryIndex(
+  path: string[] = ["System"],
+  fetcher: Fetcher = fetch,
+): Promise<string[]> {
+  const url = `${libraryRegistry}/${path.map(component).join("/")}/index`;
+  const result = await response(url, fetcher);
+  const text = await result.text();
+  if (text.length > 4_000_000 || /<html/i.test(text))
+    throw new Error(`Invalid library registry index: ${url}`);
+  return text
+    .split(/\r?\n/)
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+export async function validateLibrary(
+  title: string,
+  version: string,
+  company = "System",
+  fetcher: Fetcher = fetch,
+) {
+  if (!(await libraryIndex([company], fetcher)).includes(title))
+    throw new Error(`Unknown CODESYS library ${company}/${title}. Names are case sensitive.`);
+  const versions = await libraryIndex([company, title], fetcher);
+  if (!versions.includes(version))
+    throw new Error(`Unknown version ${version} for ${title}. Available: ${versions.join(", ")}`);
+  const filenames = (await libraryIndex([company, title, version], fetcher)).filter((name) =>
+    libraryFile.test(name),
+  );
+  if (filenames.length !== 1)
+    throw new Error(
+      `Expected one library payload for ${title} ${version}, received ${filenames.length}.`,
+    );
+  return {
+    filename: filenames[0]!,
+    url: `${libraryRegistry}/${[company, title, version, filenames[0]!].map(component).join("/")}`,
+  };
+}
+export async function installLibraries(
+  dependencies: Record<string, LibraryDependency>,
+  root: string,
+  options: { frozen?: boolean; fetcher?: Fetcher } = {},
+) {
+  const file = resolve(root, "tsplc.lock.json"),
+    store = resolve(root, ".tsplc/libraries");
+  let previous: LibraryLock = { version: 1, dependencies: {} };
+  try {
+    previous = JSON.parse(await readFile(file, "utf8"));
+  } catch (cause) {
+    if (!(cause && typeof cause === "object" && "code" in cause && cause.code === "ENOENT"))
+      throw cause;
+  }
+  if (previous.version !== 1 || !previous.dependencies || typeof previous.dependencies !== "object")
+    throw new Error("Invalid tsplc.lock.json.");
+  const installed: Record<string, InstalledLibrary> = {};
+  const fetcher = options.fetcher ?? fetch;
+  await mkdir(store, { recursive: true });
+  for (const [title, dependency] of Object.entries(dependencies)) {
+    component(title);
+    const settings = typeof dependency === "string" ? { version: dependency } : dependency;
+    const locked = previous.dependencies[title];
+    const prior = locked ? { ...locked, path: resolve(root, locked.path) } : undefined;
+    const same =
+      prior !== undefined &&
+      prior.namespace === settings.namespace &&
+      ("path" in settings
+        ? prior.url === undefined && prior.path === resolve(root, settings.path)
+        : prior.version === settings.version && prior.company === (settings.company ?? "System"));
+    if (same) {
+      try {
+        if (hash(await readFile(prior.path)) === prior.sha256) {
+          installed[title] = prior;
+          continue;
+        }
+      } catch {
+        /* Missing cache can be restored from the exact URL. */
+      }
+      if (options.frozen) throw new Error(`Locked library ${title} is missing or changed.`);
+    } else if (options.frozen) throw new Error(`Dependency ${title} differs from tsplc.lock.json.`);
+    if ("path" in settings) {
+      const path = resolve(root, settings.path);
+      if (!libraryFile.test(path))
+        throw new Error(`${title}: expected a .library or .compiled-library file.`);
+      installed[title] = {
+        title,
+        path,
+        sha256: hash(await readFile(path)),
+        ...(settings.namespace ? { namespace: settings.namespace } : {}),
+      };
+    } else {
+      const company = settings.company ?? "System";
+      const payload = await validateLibrary(title, settings.version, company, fetcher);
+      const result = await response(payload.url, fetcher);
+      const data = new Uint8Array(await result.arrayBuffer());
+      if (!data.length || data.length > 256 * 1024 * 1024)
+        throw new Error(`${title}: invalid library payload size.`);
+      const sha256 = hash(data);
+      // An existing lock pins the payload, even if the registry later changes it.
+      if (same && prior.sha256 !== sha256)
+        throw new Error(
+          `Registry payload changed for locked library ${title} ${settings.version}.`,
+        );
+      const path = resolve(store, `${sha256}-${basename(payload.filename)}`),
+        temp = `${path}.${randomUUID()}.tmp`;
+      await writeFile(temp, data, { flag: "wx" });
+      await rename(temp, path);
+      installed[title] = {
+        title,
+        company,
+        version: settings.version,
+        path,
+        sha256,
+        url: payload.url,
+        ...(settings.namespace ? { namespace: settings.namespace } : {}),
+      };
+    }
+  }
+  if (
+    options.frozen &&
+    Object.keys(previous.dependencies).some((name) => !Object.hasOwn(dependencies, name))
+  )
+    throw new Error("Removed dependencies differ from tsplc.lock.json.");
+  if (!options.frozen) {
+    const temp = `${file}.${randomUUID()}.tmp`;
+    const portable = Object.fromEntries(
+      Object.entries(installed).map(([title, library]) => [
+        title,
+        { ...library, path: relative(root, library.path).replaceAll("\\", "/") },
+      ]),
+    );
+    await writeFile(temp, JSON.stringify({ version: 1, dependencies: portable }, null, 2) + "\n");
+    await rename(temp, file);
+  }
+  return Object.values(installed);
+}

package/src/package-path.ts

@@ -0,0 +1,5 @@
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// Both source modules and published bundles live one directory below the package root.
+export const packageDirectory = resolve(fileURLToPath(new URL("..", import.meta.url)));

package/src/run.ts

@@ -0,0 +1,133 @@
+import { execFile } from "node:child_process";
+import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { basename, dirname, join } from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+import { promisify } from "node:util";
+import { z } from "zod";
+import { readBuild } from "./artifacts";
+import type { ResolvedConfig } from "./config";
+import { runtimeImage } from "./docker-build";
+import { withWorkerLock } from "./host/codesys-worker";
+import { getApplicationStatus } from "./runtime-status";
+
+const execute = promisify(execFile);
+const stateSchema = z.object({
+  Running: z.boolean(),
+  StartedAt: z.iso.datetime({ offset: true }),
+});
+
+const service = "plc";
+
+/** The Docker Compose project of a tsPLC project: `FrameAssembly` runs as `frame-assembly`. */
+export const runtimeProject = (name: string) =>
+  name
+    .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+    .toLowerCase()
+    .replace(/[^a-z0-9_-]+/g, "-");
+
+/** The local PLC: named volumes keep its provisioning and the installed application across restarts. */
+export const runtimeDefinition = (name: string) => ({
+  services: {
+    [service]: {
+      image: runtimeImage,
+      platform: "linux/amd64",
+      hostname: `${runtimeProject(name)}-${service}`,
+      init: true,
+      ports: ["127.0.0.1:4840:4840", "127.0.0.1:11740:11740"],
+      cap_add: ["SYS_NICE", "IPC_LOCK"],
+      volumes: ["control-conf:/conf/codesyscontrol", "control-data:/data/codesyscontrol"],
+      restart: "no",
+    },
+  },
+  volumes: { "control-conf": {}, "control-data": {} },
+});
+
+/** Deploy the completed boot application to the project's local PLC container. */
+export const runProject = async (
+  config: Pick<ResolvedConfig, "outDir" | "timeouts">,
+  name: string,
+) =>
+  withWorkerLock(config, async () => {
+    // Validate before stopping anything. A missing receipt includes a failed rebuild.
+    const build = await readBuild(config.outDir).catch((cause: unknown) => {
+      throw new Error(`No complete build in ${config.outDir}. Run tsplc-build build first.`, {
+        cause,
+      });
+    });
+    const definitionDirectory = await mkdtemp(join(tmpdir(), "tsplc-runtime-"));
+    try {
+      const composeFile = join(definitionDirectory, "compose.yaml");
+      // JSON is valid YAML.
+      await writeFile(composeFile, JSON.stringify(runtimeDefinition(name)));
+      const docker = (...args: string[]) =>
+        execute("docker", args, {
+          timeout: config.timeouts.runtime,
+          maxBuffer: 8 * 1024 * 1024,
+        });
+      const compose = (...args: string[]) =>
+        docker("compose", "--project-name", runtimeProject(name), "--file", composeFile, ...args);
+      const installer = await readFile(new URL("../runtime/install.sh", import.meta.url), "utf8");
+      console.log(`Installing ${build.application} in Docker service ${service}`);
+      await compose("stop", service);
+      // The helper uses the service's volumes without starting its PLC or publishing
+      // ports. Its read-only artifact mount is removed with the helper container.
+      await compose(
+        "run",
+        "--rm",
+        "--no-deps",
+        "-T",
+        "--volume",
+        `${dirname(build.output)}:/codesys-build:ro`,
+        "--entrypoint",
+        "/bin/sh",
+        service,
+        "-c",
+        installer,
+        "codesys-build-install",
+        build.application,
+        basename(build.output, ".app"),
+      );
+      await compose("up", "--detach", "--no-deps", service);
+      const containers = (await compose("ps", "--all", "--quiet", service)).stdout
+        .trim()
+        .split(/\s+/)
+        .filter(Boolean);
+      if (containers.length !== 1 || !containers[0]) {
+        throw new Error(`Expected one container for Compose service ${service}`);
+      }
+      const container = containers[0];
+      const deadline = Date.now() + config.timeouts.runtime;
+      while (true) {
+        const state = stateSchema.parse(
+          JSON.parse((await docker("inspect", "--format", "{{json .State}}", container)).stdout),
+        );
+        if (!state.Running) {
+          throw new Error(
+            `Docker service ${service} exited before the application started. Check docker logs ${container}.`,
+          );
+        }
+        // Use this container start time, not the host clock or an old "started" event.
+        const { stdout: log } = await docker(
+          "exec",
+          container,
+          "/bin/sh",
+          "-c",
+          "if [ -f /data/codesyscontrol/codesyscontrol.log ]; then cat /data/codesyscontrol/codesyscontrol.log; fi",
+        );
+        const status = getApplicationStatus(log, build.application, Date.parse(state.StartedAt));
+        if (status === "running") {
+          console.log(`${build.application} is running in ${service}`);
+          return { ...build, container };
+        }
+        if (status === "failed" || Date.now() >= deadline) {
+          throw new Error(
+            `CODESYS did not start ${build.application}. Runtime log:\n${log.split("\n").slice(-25).join("\n")}`,
+          );
+        }
+        await delay(250);
+      }
+    } finally {
+      await rm(definitionDirectory, { force: true, recursive: true });
+    }
+  });

package/src/runtime-status.ts

@@ -0,0 +1,21 @@
+/** Runtime stdout is buffered in Docker. Its log file records start/stop events immediately. */
+export const getApplicationStatus = (log: string, application: string, startedAt: number) => {
+  const event = log
+    .split(/\r?\n/)
+    .reverse()
+    .find((line) => {
+      const timestamp = Date.parse(line.split(",")[0] ?? "");
+      if (!Number.isFinite(timestamp) || timestamp < startedAt) {
+        return false;
+      }
+      return (
+        line.includes(`<app>${application}</app>`) &&
+        /\b(started|stopped|exception|corrupt|failed|denied)\b/i.test(line) &&
+        !line.includes("load started")
+      );
+    });
+  if (!event) {
+    return "pending";
+  }
+  return event.includes(`Application [<app>${application}</app>] started`) ? "running" : "failed";
+};

package/src/sources.ts

@@ -0,0 +1,248 @@
+import { readdir, readFile } from "node:fs/promises";
+import { basename, resolve } from "node:path";
+import type { ResolvedConfig } from "./config";
+import { type ObjectKind, type ParsedSource, parseSource } from "./st/parse";
+import { bindStructuredTextIo } from "./io.ts";
+
+export type SourceObject = ParsedSource & {
+  source: string;
+  folder: string[];
+  children: SourceObject[];
+};
+type Files = {
+  combined: string[];
+  declaration: string[];
+  implementation: string[];
+};
+const prefixes: Record<string, ObjectKind> = {
+  FB: "function_block",
+  PRG: "program",
+  FUN: "function",
+  F: "function",
+  I: "interface",
+  ST: "dut",
+  E: "dut",
+  T: "dut",
+  U: "dut",
+  GVL: "gvl",
+};
+const childFolders: Record<string, ObjectKind> = {
+  methods: "method",
+  properties: "property",
+  actions: "action",
+};
+const canOwn = (kind: ObjectKind) =>
+  ["program", "function_block", "interface", "property"].includes(kind);
+const assertUnique = (objects: SourceObject[], scope: string) => {
+  const seen = new Map<string, string>();
+  for (const object of objects) {
+    const key = object.name.toLowerCase();
+    const previous = seen.get(key);
+    if (previous) {
+      throw new Error(
+        `Duplicate IEC name ${object.name} in ${scope}: ${previous} and ${object.source}`,
+      );
+    }
+    seen.set(key, object.source);
+    assertUnique(object.children, `${scope}.${object.name}`);
+  }
+};
+
+const readUnit = async (
+  name: string,
+  files: Files,
+  role?: ObjectKind,
+  interfaceMember = false,
+): Promise<ParsedSource & { source: string }> => {
+  if (!/^[A-Za-z_][A-Za-z_0-9]*$/.test(name)) {
+    throw new Error(`Invalid IEC object name: ${name}`);
+  }
+  for (const [part, candidates] of Object.entries(files)) {
+    if (candidates.length > 1) {
+      throw new Error(`Ambiguous ${part} for ${name}: ${candidates.join(", ")}`);
+    }
+  }
+  const combined = files.combined[0];
+  const declaration = files.declaration[0];
+  const implementation = files.implementation[0];
+  if (combined && (declaration || implementation)) {
+    throw new Error(`Both combined and split sources exist for ${name}`);
+  }
+  const path = combined ?? declaration ?? implementation;
+  if (!path) {
+    throw new Error(`Missing source for ${name}`);
+  }
+  if (role === "action") {
+    if (!combined) {
+      throw new Error(`Actions use one implementation-only .st file: ${path}`);
+    }
+    return {
+      kind: "action",
+      name,
+      declaration: "",
+      implementation: await readFile(combined, "utf8"),
+      source: combined,
+    };
+  }
+  if (role === "get" || role === "set") {
+    if (!combined) {
+      throw new Error(`Property accessors use one .st file: ${path}`);
+    }
+    const body = await readFile(combined, "utf8");
+    const header = `METHOD ${name}\n`;
+    const parsed = parseSource(`${header}${body}\nEND_METHOD`, {
+      filename: combined,
+    });
+    return {
+      ...parsed,
+      kind: role,
+      name,
+      declaration: parsed.declaration.slice(header.length),
+      source: combined,
+    };
+  }
+  if (!combined && !declaration) {
+    throw new Error(`Missing declaration for ${path}`);
+  }
+  const sourcePath = combined ?? declaration ?? path;
+  const parsed = parseSource(await readFile(sourcePath, "utf8"), {
+    filename: sourcePath,
+    name,
+    declarationOnly: !combined || interfaceMember,
+  });
+  if (parsed.name.toLowerCase() !== name.toLowerCase()) {
+    throw new Error(`Source name ${name} does not match declaration ${parsed.name}: ${sourcePath}`);
+  }
+  if (role && parsed.kind !== role) {
+    throw new Error(`Expected ${role}, found ${parsed.kind}: ${sourcePath}`);
+  }
+  if (!role && ["method", "property"].includes(parsed.kind)) {
+    throw new Error(`Child object has no enclosing POU: ${sourcePath}`);
+  }
+  const prefix = /^([A-Z]+)_/.exec(name.toUpperCase())?.[1];
+  if (!role && prefix && prefixes[prefix] && prefixes[prefix] !== parsed.kind) {
+    throw new Error(`Prefix ${prefix}_ conflicts with ${parsed.kind}: ${sourcePath}`);
+  }
+  const declarationOnly =
+    ["dut", "gvl", "interface", "property"].includes(parsed.kind) || interfaceMember;
+  if (declarationOnly && implementation) {
+    throw new Error(`This object has no implementation: ${implementation}`);
+  }
+  if (!combined && !declarationOnly && !implementation) {
+    throw new Error(`Missing implementation for ${sourcePath}`);
+  }
+  return {
+    ...parsed,
+    ...(implementation ? { implementation: await readFile(implementation, "utf8") } : {}),
+    source: sourcePath,
+  };
+};
+
+/** Folder placement organizes the IDE; it never changes IEC names or execution order. */
+export const loadSources = async (
+  config: Pick<ResolvedConfig, "sourceDir" | "entry" | "io" | "tasks">,
+) => {
+  const objects: SourceObject[] = [];
+  const visit = async (
+    directory: string,
+    folder: string[],
+    parent?: SourceObject,
+    role?: ObjectKind,
+  ): Promise<void> => {
+    const entries = (await readdir(directory, { withFileTypes: true })).sort((a, b) =>
+      a.name.localeCompare(b.name, "en"),
+    );
+    const groups = new Map<string, { name: string; files: Files }>();
+    for (const entry of entries) {
+      if (entry.isSymbolicLink()) {
+        throw new Error(`Source symlinks are not supported: ${resolve(directory, entry.name)}`);
+      }
+      if (!entry.isFile() || !/\.st$/i.test(entry.name)) {
+        continue;
+      }
+      const stem = entry.name.slice(0, -3);
+      const suffix = /^(.*)\.(declaration|implementation)$/.exec(stem);
+      const generic = ["source", "declaration", "implementation"].includes(stem);
+      const name = generic ? basename(directory) : (suffix?.[1] ?? stem);
+      const section = suffix?.[2] ?? stem;
+      const part = section === "declaration" || section === "implementation" ? section : "combined";
+      const key = name.toLowerCase();
+      const group = groups.get(key) ?? {
+        name,
+        files: { combined: [], declaration: [], implementation: [] },
+      };
+      group.files[part].push(resolve(directory, entry.name));
+      groups.set(key, group);
+    }
+    const units: SourceObject[] = [];
+    const ownKey = basename(directory).toLowerCase();
+    // Read an object's own source before its Get/Set files, which have no POU header.
+    const ordered = [...groups].sort(([a], [b]) => Number(b === ownKey) - Number(a === ownKey));
+    for (const [key, { name, files }] of ordered) {
+      const ownProperty = units.find(
+        (unit) => unit.kind === "property" && unit.name.toLowerCase() === ownKey,
+      );
+      const accessor = ownProperty && (key === "get" || key === "set") ? key : undefined;
+      const unit: SourceObject = {
+        ...(await readUnit(
+          accessor ? `${accessor[0]?.toUpperCase()}${accessor.slice(1)}` : name,
+          files,
+          accessor ?? role,
+          parent?.kind === "interface",
+        )),
+        folder: parent ? [] : folder,
+        children: [],
+      };
+      if (accessor && ownProperty) {
+        if (parent?.kind === "interface") {
+          throw new Error(`Interface properties cannot implement accessors: ${unit.source}`);
+        }
+        ownProperty.children.push(unit);
+      } else {
+        units.push(unit);
+        if (parent) {
+          parent.children.push(unit);
+        } else {
+          objects.push(unit);
+        }
+      }
+    }
+    const own = units.find((unit) => unit.name.toLowerCase() === ownKey && canOwn(unit.kind));
+    if (own && !parent) {
+      own.folder = folder.slice(0, -1);
+    }
+    for (const entry of entries.filter((entry) => entry.isDirectory())) {
+      const childRole = childFolders[entry.name];
+      if (own && childRole) {
+        if (own.kind === "property" || (own.kind === "interface" && childRole === "action")) {
+          throw new Error(`Unsupported ${entry.name} under ${own.name}`);
+        }
+        await visit(resolve(directory, entry.name), [], own, childRole);
+      } else if (parent) {
+        await visit(resolve(directory, entry.name), [], parent, role);
+      } else {
+        await visit(resolve(directory, entry.name), [...folder, entry.name]);
+      }
+    }
+  };
+  await visit(resolve(config.sourceDir), []);
+  assertUnique(objects, "Application");
+  if (config.io) bindStructuredTextIo(objects, config.io);
+  const entry = objects.find((object) => object.source === resolve(config.entry));
+  if (!entry) {
+    throw new Error(`Entry is not a discovered source: ${config.entry}`);
+  }
+  if (entry.kind !== "program") {
+    throw new Error(`Entry must be a PROGRAM: ${config.entry}`);
+  }
+  if (config.tasks) {
+    const programs = new Set(
+      objects.filter((object) => object.kind === "program").map((object) => object.name),
+    );
+    for (const task of config.tasks)
+      for (const program of task.programs)
+        if (!programs.has(program))
+          throw new Error(`Task ${task.name} references an undiscovered PROGRAM ${program}`);
+  }
+  return { entry: entry.name, objects };
+};