@tsplc/build 0.0.0-stage → 0.2.0

package/src/host/codesys-worker.ts

@@ -0,0 +1,348 @@
+// Engineering CLI lifecycle and diagnostics.
+import { createHash, randomUUID } from "node:crypto";
+import {
+  access,
+  copyFile,
+  mkdir,
+  open,
+  readFile,
+  rename,
+  rm,
+  unlink,
+  writeFile,
+} from "node:fs/promises";
+import { resolve } from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+import { z } from "zod";
+import type { ResolvedConfig } from "../config";
+import { CodesysCompilerError, compilerDiagnosticSchema } from "../diagnostics";
+import { packageDirectory } from "../package-path";
+import { codesysCommand, getHostCommand } from "./codesys-command";
+import { createCodesysHost } from "./codesys-host";
+
+const pythonDirectory = resolve(packageDirectory, "python");
+
+const sessionSchema = z.object({
+  directory: z.string(),
+  fingerprint: z.string(),
+  pid: z.int().positive(),
+});
+
+type Session = z.infer<typeof sessionSchema>;
+
+type WorkerCommand =
+  | { action: "build" | "online" | "ping" | "stop" }
+  | { action: "login"; arguments: Record<string, unknown> };
+
+const hasCode = (error: unknown, code: string) =>
+  error instanceof Error && "code" in error && error.code === code;
+
+const isProcessAlive = (pid: number) => {
+  try {
+    // Signal 0 checks process existence and permissions without killing it.
+    // Only ESRCH means it is gone; permission errors must still propagate.
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    if (hasCode(error, "ESRCH")) {
+      return false;
+    }
+    throw error;
+  }
+};
+
+const readJson = async (path: string): Promise<unknown> => {
+  try {
+    return JSON.parse(await readFile(path, "utf8"));
+  } catch (error) {
+    if (hasCode(error, "ENOENT")) {
+      return undefined;
+    }
+    throw error;
+  }
+};
+
+export const writeJson = async (path: string, value: unknown) => {
+  // Readers may poll while we write. A temporary file in the same directory
+  // lets rename publish the complete JSON atomically, without exposing partial data.
+  const temporary = `${path}.${randomUUID()}.tmp`;
+  await writeFile(temporary, JSON.stringify(value, null, 2));
+  await rename(temporary, path);
+};
+
+/** Serializes startup and builds across CLI processes, including separate terminals. */
+export const withWorkerLock = async <T>(
+  config: Pick<ResolvedConfig, "outDir" | "timeouts">,
+  run: () => Promise<T>,
+) => {
+  await mkdir(resolve(config.outDir, ".codesys"), { recursive: true });
+  const path = resolve(config.outDir, ".codesys/command.lock");
+  const deadline = Date.now() + config.timeouts.build + config.timeouts.startup;
+  while (true) {
+    const lock = await open(path, "wx").catch((error: unknown) => {
+      if (hasCode(error, "EEXIST")) {
+        return;
+      }
+      throw error;
+    });
+
+    if (lock) {
+      try {
+        await lock.writeFile(String(process.pid));
+        return await run();
+      } finally {
+        await lock.close();
+        await unlink(path);
+      }
+    }
+
+    const owner = Number(
+      await readFile(path, "utf8").catch((error: unknown) => {
+        if (hasCode(error, "ENOENT")) {
+          return "";
+        }
+        throw error;
+      }),
+    );
+    if (owner > 0 && !isProcessAlive(owner)) {
+      // Do not race another client by deleting a lock that it may have replaced.
+      throw new Error(`An interrupted command left ${path}. Remove that lock file and retry.`);
+    }
+    if (Date.now() >= deadline) {
+      throw new Error(`Timed out waiting for another CODESYS command (${path})`);
+    }
+    await delay(200);
+  }
+};
+
+/** The caller holds withWorkerLock throughout a command, so the mailbox has one writer. */
+export const createCodesysWorker = (config: ResolvedConfig) => {
+  const host = createCodesysHost(config);
+  const statePath = resolve(config.outDir, ".codesys/session.json");
+  const verifiedProcesses = new Set<number>();
+
+  const readSession = async (): Promise<Session | undefined> => {
+    const value = await readJson(statePath);
+    if (value === undefined) {
+      return undefined;
+    }
+    const session = sessionSchema.safeParse(value);
+    if (!session.success) {
+      throw new Error(`Invalid CODESYS session file: ${statePath}`, {
+        cause: session.error,
+      });
+    }
+    return session.data;
+  };
+
+  const terminate = async (session: Session) => {
+    if (isProcessAlive(session.pid)) {
+      await host.terminate(session.pid).catch((error: unknown) => {
+        if (isProcessAlive(session.pid)) {
+          throw error;
+        }
+      });
+    }
+    // Let the launcher reap its child before another error handler or CLI
+    // checks this PID. Sending a second group kill can otherwise race exit.
+    const deadline = Date.now() + config.timeouts.terminate;
+    while (isProcessAlive(session.pid)) {
+      if (Date.now() >= deadline) {
+        throw new Error("CODESYS launcher did not exit after termination");
+      }
+      await delay(50);
+    }
+  };
+
+  const request = async (session: Session, command: WorkerCommand, timeoutMs: number) => {
+    const id = randomUUID();
+    const reply = resolve(session.directory, `${id}.json`);
+    await writeJson(resolve(session.directory, "request.json"), {
+      ...command,
+      id,
+    });
+    const deadline = Date.now() + timeoutMs;
+    while (true) {
+      const result = await readJson(reply);
+      if (result !== undefined) {
+        await unlink(reply);
+        const response = z
+          .object({
+            error: z.string().optional(),
+            diagnostics: z.array(compilerDiagnosticSchema).optional(),
+            id: z.literal(id),
+            ok: z.boolean(),
+            result: z.unknown(),
+          })
+          .safeParse(result);
+        if (!response.success) {
+          throw new Error("CODESYS returned an invalid worker response", {
+            cause: response.error,
+          });
+        }
+        verifiedProcesses.add(session.pid);
+        if (!response.data.ok) {
+          const message = response.data.error ?? "CODESYS build failed";
+          if (response.data.diagnostics) {
+            throw new CodesysCompilerError(message, response.data.diagnostics);
+          }
+          throw new Error(message);
+        }
+        return response.data.result;
+      }
+      if (!isProcessAlive(session.pid)) {
+        throw new Error(
+          `CODESYS exited before completing ${command.action}. See ${session.directory}/codesys.log`,
+        );
+      }
+      if (Date.now() >= deadline) {
+        // A saved PID can belong to another process after a reboot. Only kill
+        // a process we launched or whose worker answered in this invocation.
+        if (!verifiedProcesses.has(session.pid)) {
+          throw new Error(
+            `CODESYS ${command.action} timed out without a worker response. Close the dedicated IDE if it is still running, then retry. Log: ${session.directory}/codesys.log`,
+          );
+        }
+        await terminate(session);
+        throw new Error(
+          `CODESYS ${command.action} timed out after ${timeoutMs} ms; the worker was stopped. See ${session.directory}/codesys.log`,
+        );
+      }
+      await delay(200);
+    }
+  };
+
+  const launch = async () => {
+    await access(config.codesys.executable);
+    const fingerprint = createHash("sha256")
+      .update(
+        JSON.stringify({
+          builder: await readFile(resolve(pythonDirectory, "build.py"), "utf8"),
+          online: await readFile(resolve(pythonDirectory, "codesys_online.py"), "utf8"),
+          login: await readFile(resolve(pythonDirectory, "codesys_login.py"), "utf8"),
+          command: codesysCommand,
+          codesys: config.codesys,
+          launcher: getHostCommand(config.codesys),
+          worker: await readFile(resolve(pythonDirectory, "worker.py"), "utf8"),
+        }),
+      )
+      .digest("hex");
+    const previous = await readSession();
+    if (previous && isProcessAlive(previous.pid)) {
+      if (previous.fingerprint !== fingerprint) {
+        throw new Error(
+          "CODESYS settings or worker scripts changed. Run stop-worker, then launch-worker to reload them.",
+        );
+      }
+      await request(previous, { action: "ping" }, config.timeouts.startup);
+      console.log(
+        `Reusing CODESYS worker (${previous.pid}). Log: ${previous.directory}/codesys.log`,
+      );
+      return previous;
+    }
+
+    const directory = resolve(config.outDir, ".codesys/worker");
+    await rm(directory, { recursive: true, force: true });
+    await mkdir(directory, { recursive: true });
+    await copyFile(resolve(pythonDirectory, "build.py"), resolve(directory, "build.py"));
+    await copyFile(resolve(pythonDirectory, "worker.py"), resolve(directory, "worker.py"));
+    for (const script of ["codesys_online.py", "codesys_login.py"]) {
+      await copyFile(resolve(pythonDirectory, script), resolve(directory, script));
+    }
+    console.log(`Starting CODESYS. Log: ${directory}/codesys.log`);
+    const pid = await host.startWorker(directory);
+    const session = { directory, fingerprint, pid };
+    verifiedProcesses.add(pid);
+    try {
+      await writeJson(statePath, session);
+      await request(session, { action: "ping" }, config.timeouts.startup);
+    } catch (error) {
+      await terminate(session);
+      throw error;
+    }
+    console.log(`CODESYS worker ready (${session.pid})`);
+    return session;
+  };
+
+  const checkExit = async (session: Session) => {
+    const status = await host.exitStatus(session.directory, session.pid);
+    if (!status) {
+      throw new Error(
+        `CODESYS launcher stopped but its exit status is unavailable. See ${session.directory}/codesys.log`,
+      );
+    }
+    if (status.code !== 0 || status.signal !== null) {
+      throw new Error(
+        `CODESYS launcher exited with ${status.signal ?? status.code ?? "unknown status"}. See ${session.directory}/codesys.log`,
+      );
+    }
+  };
+
+  const stop = async () => {
+    const session = await readSession();
+    if (!session) {
+      console.log("CODESYS worker is already stopped");
+      return;
+    }
+    if (!isProcessAlive(session.pid)) {
+      await checkExit(session);
+      console.log("CODESYS worker is already stopped");
+      return;
+    }
+    await request(session, { action: "stop" }, config.timeouts.stop);
+    const deadline = Date.now() + config.timeouts.stop;
+    while (isProcessAlive(session.pid)) {
+      if (Date.now() >= deadline) {
+        const message = `CODESYS stop timed out after ${config.timeouts.stop} ms. See ${session.directory}/codesys.log`;
+        try {
+          await terminate(session);
+        } catch (cause) {
+          throw new Error(`${message}; the worker could not be terminated`, { cause });
+        }
+        throw new Error(`${message}; the worker required forced termination`);
+      }
+      await delay(200);
+    }
+    await checkExit(session);
+    console.log("CODESYS worker stopped");
+  };
+
+  return { launch, request, stop };
+};
+
+/** Container jobs own a temporary worker; always stop it before returning a result. */
+export const withWorkerShutdown = async <T>(
+  config: ResolvedConfig,
+  worker: Pick<ReturnType<typeof createCodesysWorker>, "stop">,
+  operation: () => Promise<T>,
+) => {
+  const stop = async () => {
+    try {
+      await withWorkerLock(config, () => worker.stop());
+    } finally {
+      await rm(resolve(config.outDir, ".codesys/session.json"), { force: true });
+    }
+  };
+  return Promise.resolve()
+    .then(operation)
+    .then(
+      async (result) => {
+        await stop();
+        return result;
+      },
+      async (failure: unknown) => {
+        await stop().catch((shutdownFailure: unknown) => {
+          // Diagnostic mapping follows cause; keep the operation there and
+          // expose its shutdown failure alongside it in errors.
+          throw new AggregateError(
+            [failure, shutdownFailure],
+            "CODESYS operation and worker shutdown failed",
+            {
+              cause: failure,
+            },
+          );
+        });
+        throw failure;
+      },
+    );
+};

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,43 @@
+export { buildProject } from "./build";
+export {
+  type CodesysBuildConfig,
+  type CyclicTask,
+  configSchema,
+  defineConfig,
+  loadConfig,
+  type ResolvedConfig,
+  resolveConfig,
+} from "./config";
+export {
+  type ControllerLogin,
+  type ControllerResult,
+  explicitDownload,
+  findControllerLogin,
+  inspectController,
+  type LoginCommand,
+  loginCommandSchema,
+  type LoginResult,
+  loginResultSchema,
+  openControllerLogin,
+  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,
+  configureGateway,
+  configureRuntime,
+  gatewayImage,
+} 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);
+}