@tsplc/build 0.0.0-stage → 0.1.0

package/src/host/windows-path.ts

@@ -0,0 +1,73 @@
+import { execFile } from "node:child_process";
+import { readdir, realpath } from "node:fs/promises";
+import { relative, resolve, sep, win32 } from "node:path";
+import { promisify } from "node:util";
+import type { ResolvedConfig } from "../config";
+import { commandArgumentSchema } from "./codesys-command";
+import { codesysTimeouts } from "@tsplc/config/build";
+
+const execute = promisify(execFile);
+
+export const toWindowsPath = async (
+  path: string,
+  wine: ResolvedConfig["codesys"]["wine"],
+  platform: NodeJS.Platform = process.platform,
+) => {
+  if (platform === "win32") {
+    return commandArgumentSchema.parse(win32.resolve(path));
+  }
+  if (!wine?.prefix) {
+    throw new Error("Configure codesys.wine.prefix for CODESYS on macOS/Linux");
+  }
+
+  // Resolve filesystem aliases (e.g. macOS /var -> /private/var) so the file
+  // and drive roots are compared using the same paths. Fall back to the absolute
+  // spelling when realpath cannot resolve the file, such as before it exists.
+  const absolute = await realpath(resolve(path)).catch(() => resolve(path));
+  // Wine stores drive mappings as symlinks, e.g. dosdevices/c: -> ../drive_c.
+  // Reading these links avoids starting Wine just to convert a path.
+  const devices = resolve(wine.prefix, "dosdevices");
+  const drives = await readdir(devices).catch(() => []);
+  const mappings = await Promise.all(
+    drives
+      .filter((drive) => /^[a-z]:$/i.test(drive))
+      .map(async (drive) => {
+        const root = await realpath(resolve(devices, drive)).catch(() => undefined);
+        if (!root) {
+          return;
+        }
+
+        const suffix = relative(root, absolute);
+        // ".." or "../..." means the file is outside this drive's root.
+        // Match a full segment so a name such as "..notes" remains valid.
+        if (suffix === ".." || suffix.startsWith(`..${sep}`)) {
+          return;
+        }
+
+        return {
+          root,
+          windows: win32.join(`${drive.toUpperCase()}\\`, ...suffix.split(sep)),
+        };
+      }),
+  );
+  // Mappings can overlap: C: -> /wine/drive_c and Z: -> / may both contain
+  // the file. Prefer the longest matching root to use the most specific drive.
+  const [mapping] = mappings
+    .filter((value) => value !== undefined)
+    .sort((a, b) => b.root.length - a.root.length);
+  if (mapping) {
+    return commandArgumentSchema.parse(mapping.windows);
+  }
+
+  // No readable drive mapping covers the path; ask Wine to convert it instead.
+  const result = await execute(
+    wine.pathBinary,
+    ["-w", resolve(path)],
+    // Wine inherits OS process settings.
+    {
+      env: { ...process.env, WINEPREFIX: wine.prefix, WINEDEBUG: wine.debug },
+      timeout: codesysTimeouts.hostCommand,
+    },
+  );
+  return commandArgumentSchema.parse(result.stdout.trim());
+};

package/src/index.ts

@@ -0,0 +1,26 @@
+export { buildProject } from "./build";
+export {
+  type CodesysBuildConfig,
+  type CyclicTask,
+  configSchema,
+  defineConfig,
+  loadConfig,
+  type ResolvedConfig,
+  resolveConfig,
+} from "./config";
+export { type ControllerResult, inspectController, updateController } from "./controller-online";
+export { type CodesysCompilerDiagnostic, CodesysCompilerError } from "./diagnostics";
+export { runProject } from "./run";
+export { loadSources, type SourceObject } from "./sources";
+export { StSyntaxError } from "./st/lexer";
+export { type ObjectKind, type ParsedSource, parseSource } from "./st/parse";
+
+export {
+  installLibraries,
+  validateLibrary,
+  libraryIndex,
+  type InstalledLibrary,
+} from "./libraries.ts";
+
+export { configureDocker, configureRuntime } from "./docker-build.ts";
+export { readBuild } from "./artifacts.ts";

package/src/io.ts

@@ -0,0 +1,127 @@
+import type { SourceObject } from "./sources.ts";
+import { tokenize, type Token } from "./st/lexer.ts";
+import { variableSections } from "./st/declarations.ts";
+
+export interface DirectIoBinding {
+  address: string;
+  type?: string;
+}
+// A span binds at its first element: ARRAY[l..u] OF <element> with consecutive addresses.
+const arrayType = /^ARRAY\s*\[\s*(-?\d+)\s*\.\.\s*(-?\d+)\s*\]\s*OF\s+(\w+)$/;
+const layout = (type: string) => {
+  const array = arrayType.exec(type);
+  return array
+    ? { element: array[3]!, length: Number(array[2]) - Number(array[1]) + 1 }
+    : { element: type, length: 1 };
+};
+const widths: Record<string, string> = {
+  BOOL: "X",
+  BYTE: "B",
+  SINT: "B",
+  USINT: "B",
+  WORD: "W",
+  INT: "W",
+  UINT: "W",
+  DWORD: "D",
+  DINT: "D",
+  UDINT: "D",
+  REAL: "D",
+};
+
+/** Apply the shared mapping to declarations in memory; authored ST stays untouched. */
+export function bindStructuredTextIo(
+  objects: SourceObject[],
+  bindings: Record<string, DirectIoBinding>,
+) {
+  const declarations: {
+    object: SourceObject;
+    name: string;
+    names: Token[];
+    colon: Token;
+    type: string;
+  }[] = [];
+  const visit = (object: SourceObject) => {
+    const tokens = tokenize(object.declaration, object.source);
+    let section = false,
+      start = 0;
+    for (let i = 0; i < tokens.length; i++) {
+      const token = tokens[i]!;
+      if (variableSections.has(token.value)) {
+        section = true;
+        start = i + 1;
+        continue;
+      }
+      if (token.value === "END_VAR") {
+        section = false;
+        continue;
+      }
+      if (!section || token.value !== ";") continue;
+      const part = tokens.slice(start, i).filter((t) => t.kind !== "pragma");
+      start = i + 1;
+      const colonIndex = part.findIndex((t) => t.value === ":");
+      if (colonIndex < 1) continue;
+      const names = part
+        .slice(0, colonIndex)
+        .filter(
+          (t) => t.kind === "word" && !["CONSTANT", "RETAIN", "PERSISTENT", "AT"].includes(t.value),
+        );
+      const at = part.findIndex((t) => t.value === "AT");
+      const variables = at < 0 ? names : names.filter((t) => t.start < part[at]!.start);
+      const initializer = part.findIndex((t, index) => index > colonIndex && t.value === ":=");
+      const typeTokens = part.slice(colonIndex + 1, initializer < 0 ? undefined : initializer);
+      const type = typeTokens.length
+        ? object.declaration
+            .slice(typeTokens[0]!.start, typeTokens.at(-1)!.end)
+            .replace(/\s+/g, " ")
+            .toUpperCase()
+        : "";
+      for (const name of variables)
+        declarations.push({
+          object,
+          name: name.value,
+          names: variables,
+          colon: part[colonIndex]!,
+          type,
+        });
+    }
+    object.children.forEach(visit);
+  };
+  objects.forEach(visit);
+  const edits = new Map<SourceObject, { start: number; end: number; text: string }[]>();
+  for (const [symbol, binding] of Object.entries(bindings)) {
+    const parts = symbol.toUpperCase().split(".");
+    if (parts.length > 2)
+      throw new Error(`${symbol}: direct IO maps a scalar declaration, not a nested field.`);
+    const matches = declarations.filter(
+      (d) =>
+        d.name === parts.at(-1) && (parts.length === 1 || d.object.name.toUpperCase() === parts[0]),
+    );
+    if (matches.length !== 1)
+      throw new Error(
+        `${symbol}: expected one ST variable declaration, found ${matches.length}. Use Object.Variable to disambiguate.`,
+      );
+    const declaration = matches[0]!;
+    if (declaration.names.length !== 1)
+      throw new Error(`${symbol}: declare mapped IO variables separately.`);
+    const declared = layout(declaration.type);
+    if (
+      !widths[declared.element] ||
+      (declared.length > 1 && declared.element === "BOOL") ||
+      binding.address[2] !== widths[declared.element]
+    )
+      throw new Error(`${symbol}: ${declaration.type} is incompatible with ${binding.address}.`);
+    const expected = binding.type && layout(binding.type.replace(/\s+/g, " ").toUpperCase());
+    if (expected && (expected.element !== declared.element || expected.length !== declared.length))
+      throw new Error(`${symbol}: expected ${binding.type}, found ${declaration.type}.`);
+    const list = edits.get(declaration.object) ?? [];
+    const start = declaration.names[0]!.end;
+    if (list.some((e) => e.start === start))
+      throw new Error(`${symbol}: the variable has more than one IO binding.`);
+    list.push({ start, end: declaration.colon.start, text: ` AT ${binding.address} ` });
+    edits.set(declaration.object, list);
+  }
+  for (const [object, list] of edits)
+    for (const edit of list.sort((a, b) => b.start - a.start))
+      object.declaration =
+        object.declaration.slice(0, edit.start) + edit.text + object.declaration.slice(edit.end);
+}

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";
+};