@tsplc/compiler 0.1.0 → 0.2.1

package/project/plant.ts

@@ -0,0 +1,437 @@
+import { basename, relative, resolve, sep } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { pathToFileURL } from "node:url";
+import {
+  AgentOperationError,
+  type AgentClient,
+  createAgentClient,
+  type ReleaseFile,
+} from "@tsplc/agent/client";
+import type { Credentials, ReleaseManifest, Target, Variable } from "@tsplc/agent";
+import type { LoginCommand, LoginResult } from "@tsplc/build";
+import { controllerFor, type loadTsplcConfig } from "@tsplc/config";
+import { hasErrors } from "@tsplc/compiler/ir";
+import { generateProject } from "@tsplc/typegen";
+import { z } from "zod";
+import { buildProject, projectTargets } from "./project.ts";
+import { buildServer } from "./server.ts";
+
+export const plantCommands = new Set([
+  "deploy",
+  "target",
+  "status",
+  "login",
+  "logout",
+  "vars",
+  "read",
+  "write",
+  "force",
+  "unforce",
+  "start",
+  "stop",
+  "reset",
+]);
+
+export interface PlantFlags {
+  download?: boolean;
+  "initialize-user"?: boolean;
+  restore?: boolean;
+  select?: boolean;
+  yes?: boolean;
+  "frozen-lockfile"?: boolean;
+}
+
+type LoadedConfig = Awaited<ReturnType<typeof loadTsplcConfig>>;
+
+const ask = async (question: string) => {
+  const lines = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    return (await lines.question(question)).trim();
+  } finally {
+    lines.close();
+  }
+};
+
+/** Reads a line without echoing it. */
+const askSecret = (question: string) =>
+  new Promise<string>((accept, reject) => {
+    if (!process.stdin.isTTY) {
+      reject(new Error("The controller password needs an interactive terminal."));
+      return;
+    }
+    // Echo goes off before the prompt appears, so nothing typed at it can show.
+    process.stdin.setRawMode(true);
+    process.stdin.setEncoding("utf8");
+    process.stdin.resume();
+    process.stdout.write(question);
+    let secret = "";
+    const finish = () => {
+      process.stdin.off("data", read);
+      process.stdin.setRawMode(false);
+      process.stdin.pause();
+      process.stdout.write("\n");
+    };
+    const read = (text: string) => {
+      for (const character of text) {
+        if (character === "\r" || character === "\n") {
+          finish();
+          accept(secret);
+          return;
+        }
+        if (character === "\u0003") {
+          finish();
+          reject(new Error("Cancelled."));
+          return;
+        }
+        secret = character === "\u007f" ? secret.slice(0, -1) : secret + character;
+      }
+    };
+    process.stdin.on("data", read);
+  });
+
+const choose = async <T>(question: string, items: readonly T[], label: (item: T) => string) => {
+  items.forEach((item, index) => console.log(`  ${index + 1}. ${label(item)}`));
+  while (true) {
+    const item = items[Number(await ask(`${question} [1-${items.length}]: `)) - 1];
+    if (item !== undefined) return item;
+  }
+};
+
+const confirm = async (question: string, flags: PlantFlags) =>
+  flags.yes || /^y(es)?$/i.test(await ask(`${question} [y/N]: `));
+
+const askCredentials = async (): Promise<Credentials> => ({
+  username: await ask("Controller username: "),
+  password: await askSecret("Controller password: "),
+});
+
+const progress = (message: string) => console.log(`  ${message}`);
+
+const connect = () => {
+  const environment = z
+    .object({
+      TSPLC_AGENT_URL: z.url({
+        error: "Set TSPLC_AGENT_URL to the plant agent, such as http://line-pc:4850",
+      }),
+      TSPLC_AGENT_TOKEN: z.string({ error: "Set TSPLC_AGENT_TOKEN to the plant agent's token" }),
+    })
+    .parse(process.env);
+  return createAgentClient({
+    url: environment.TSPLC_AGENT_URL,
+    token: environment.TSPLC_AGENT_TOKEN,
+  });
+};
+
+const selectTarget = async (agent: AgentClient): Promise<Target> => {
+  const interfaces = await agent.interfaces();
+  if (!interfaces.length) throw new Error("The plant PC has no IPv4 network.");
+  const network =
+    interfaces.length === 1 && interfaces[0]
+      ? interfaces[0]
+      : await choose(
+          "Which network is the controller on?",
+          interfaces,
+          (item) => `${item.name}  ${item.address}/${item.prefixLength}`,
+        );
+  console.log(`Scanning ${network.address}/${network.prefixLength} for CODESYS controllers…`);
+  const found = await agent.discover(network.name);
+  const manual = { address: "", port: 11740, hostname: null };
+  const choice = await choose("Which controller?", [...found, manual], (item) =>
+    item === manual
+      ? "Enter an address"
+      : `${item.address}${item.hostname ? `  (${item.hostname})` : ""}`,
+  );
+  const host = choice === manual ? await ask("Controller address: ") : choice.address;
+  return agent.setTarget({ host, port: choice.port });
+};
+
+/** Every published leaf the generated contract describes, as CODESYS expressions name it. */
+const contractVariables = async (config: LoadedConfig["config"], root: string) => {
+  if (!config.typegen) return [];
+  const contract = z
+    .object({
+      symbols: z.array(z.object({ name: z.string(), gvl: z.string(), type: z.string() })),
+      typeFields: z.record(z.string(), z.array(z.object({ field: z.string(), type: z.string() }))),
+    })
+    .parse(await import(pathToFileURL(resolve(root, config.typegen.dir, "plc.ts")).href));
+  return contract.symbols.flatMap(({ name, gvl, type }): Variable[] => {
+    const path = `${gvl}.${name}`;
+    const fields = contract.typeFields[type];
+    if (!fields) return [{ path, type }];
+    return fields.map((field) => ({
+      path:
+        field.field === ""
+          ? path
+          : `${path}${field.field.startsWith("[") ? "" : "."}${field.field}`,
+      type: field.type,
+    }));
+  });
+};
+
+/** Compiles the production program and its server into the files `tsplc deploy` uploads. */
+const prepareRelease = async (file: string, loaded: LoadedConfig, flags: PlantFlags) => {
+  const { config, root } = loaded;
+  if (!config.compiler) throw new Error("tsplc deploy deploys tsPLC programs; configure compiler.");
+  const emitted = await buildProject(file, {
+    emitOnly: true,
+    forController: true,
+    frozenLockfile: flags["frozen-lockfile"],
+    loaded,
+    buildTarget: "production",
+    controller: controllerFor(config, "deploy"),
+  });
+  if (hasErrors(emitted.diagnostics)) return { diagnostics: emitted.diagnostics };
+  const settings = emitted.controllerConfig;
+  if (!settings) throw new Error("Configure build settings for deployment.");
+  await generateProject(file, { loaded, targets: await projectTargets(file, { loaded }) });
+
+  const portable = (path: string) => path.split(sep).join("/");
+  const libraries = (settings.libraries ?? []).map((library) => ({
+    ...library,
+    release: `libraries/${library.sha256}-${basename(library.path)}`,
+  }));
+  const files: ReleaseFile[] = [
+    { path: "template.project", content: Bun.file(settings.template) },
+    ...libraries.map((library) => ({ path: library.release, content: Bun.file(library.path) })),
+  ];
+  // Plain TypeScript programs emit their generated modules under `.tsplc/`.
+  for await (const source of new Bun.Glob("**/*").scan({ cwd: settings.sourceDir, dot: true }))
+    files.push({
+      path: `st/${portable(source)}`,
+      content: Bun.file(resolve(settings.sourceDir, source)),
+    });
+  let server: string | undefined;
+  if (config.server?.runtime) {
+    const { executable } = (await buildServer(config, root)).server;
+    server = `server/${basename(executable)}`;
+    files.push({ path: server, content: Bun.file(executable) });
+  }
+  const manifest: ReleaseManifest = {
+    // Paths are relative to the release; the agent supplies the output and controller settings.
+    config: {
+      io: {},
+      deviceTree: settings.deviceTree,
+      controller: settings.controller,
+      libraryReferences: settings.libraryReferences,
+      libraries: libraries.map(({ release, ...library }) => ({ ...library, path: release })),
+      task: settings.task,
+      tasks: settings.tasks,
+      removeObjects: settings.removeObjects,
+      symbols: settings.symbols,
+      timeouts: settings.timeouts,
+      template: "template.project",
+      sourceDir: "st",
+      entry: `st/${portable(relative(settings.sourceDir, settings.entry))}`,
+    },
+    variables: await contractVariables(config, root),
+    server,
+  };
+  return { release: { manifest, files } };
+};
+
+const deploy = async (
+  agent: AgentClient,
+  file: string,
+  loaded: LoadedConfig,
+  flags: PlantFlags,
+) => {
+  const status = await agent.status();
+  if (status.login) throw new Error("A login is open; log out before deploying: tsplc logout");
+  const target = !status.target || flags.select ? await selectTarget(agent) : status.target;
+  console.log(`Building the release for ${target.host}…`);
+  const { release, diagnostics } = await prepareRelease(file, loaded, flags);
+  if (!release) return { diagnostics };
+  if (
+    flags.download &&
+    !(await confirm(
+      "A full download stops the running application while it loads. Continue?",
+      flags,
+    ))
+  )
+    throw new Error("Cancelled.");
+  const credentials = await askCredentials();
+  const settings = {
+    credentials,
+    download: flags.download ?? false,
+    initializeUser: flags["initialize-user"] ?? false,
+  };
+  console.log(
+    release.manifest.server ? "Deploying the server and the program…" : "Deploying the program…",
+  );
+  try {
+    return await agent.deploy(release, settings, progress);
+  } catch (error) {
+    if (
+      !(error instanceof AgentOperationError && error.downloadRequired) ||
+      !(await confirm(
+        `${error.message}. A full download stops the running application while it loads. Download now?`,
+        flags,
+      ))
+    )
+      throw error;
+    return agent.deploy(release, { ...settings, download: true }, progress);
+  }
+};
+
+/** Opens a login when none is open; it stays open across commands until `tsplc logout`. */
+const ensureLogin = async (agent: AgentClient) => {
+  if ((await agent.status()).login) return;
+  const credentials = await askCredentials();
+  console.log(
+    "Logging in. CODESYS takes a few minutes to start; the login stays open until tsplc logout.",
+  );
+  await agent.login(credentials, progress);
+};
+
+/** The children of `prefix` in the variable tree, with array indexes folded into one range. */
+export const variableChildren = (variables: readonly Variable[], prefix: string) => {
+  const children = new Map<string, { type?: string; leaves: number }>();
+  const start = prefix.toLowerCase();
+  for (const { path, type } of variables) {
+    const lower = path.toLowerCase();
+    if (
+      prefix &&
+      !(lower === start || lower.startsWith(`${start}.`) || lower.startsWith(`${start}[`))
+    )
+      continue;
+    const rest = path.slice(prefix.length).replace(/^\./, "");
+    if (rest === "") return [{ name: path, type, leaves: 1 }];
+    const name = /^(\[[^\]]*\]|[^.[]+)/.exec(rest)?.[0] ?? rest;
+    const child = children.get(name) ?? { leaves: 0 };
+    children.set(name, { type: rest === name ? type : undefined, leaves: child.leaves + 1 });
+  }
+  const indexes = [...children.keys()]
+    .filter((name) => /^\[\d+\]$/.test(name))
+    .map((name) => Number(name.slice(1, -1)));
+  const listed = [...children].filter(([name]) => !/^\[\d+\]$/.test(name));
+  if (indexes.length) {
+    const first = children.get(`[${Math.min(...indexes)}]`);
+    listed.unshift([`[${Math.min(...indexes)}..${Math.max(...indexes)}]`, first ?? { leaves: 0 }]);
+  }
+  return listed.map(([name, child]) => ({ name, ...child }));
+};
+
+const printLogin = (result: LoginResult) => {
+  if ("values" in result) {
+    for (const [expression, value] of Object.entries(result.values))
+      console.log(`${expression} = ${value}`);
+    return;
+  }
+  console.log(`Application ${result.state}`);
+  if (result.forced.length) console.log(`Forced: ${result.forced.join(", ")}`);
+};
+
+/**
+ * Runs a command against the plant agent named by TSPLC_AGENT_URL and TSPLC_AGENT_TOKEN.
+ * Returns a deployment's compiler diagnostics when the program doesn't compile.
+ */
+export const runPlantCommand = async (
+  command: string,
+  args: string[],
+  flags: PlantFlags,
+  project: { file: string; load: () => Promise<LoadedConfig> },
+) => {
+  const agent = connect();
+  const expect = (count: number, usage: string) => {
+    if (args.length !== count) throw new Error(`Usage: tsplc ${command} ${usage}`);
+  };
+  const send = async (loginCommand: LoginCommand) => {
+    await ensureLogin(agent);
+    printLogin(await agent.command(loginCommand));
+  };
+  switch (command) {
+    case "deploy": {
+      expect(0, "[--download] [--select] [--initialize-user]");
+      const deployed = await deploy(agent, project.file, await project.load(), flags);
+      if ("diagnostics" in deployed) return deployed;
+      console.log(`Deployed release ${deployed.id} (${deployed.operation}).`);
+      return;
+    }
+    case "target": {
+      expect(0, "");
+      const target = await selectTarget(agent);
+      console.log(`Deployments now go to ${target.host}:${target.port}.`);
+      return;
+    }
+    case "status": {
+      expect(0, "");
+      const status = await agent.status();
+      console.log(
+        `Controller  ${status.target ? `${status.target.host}:${status.target.port}` : "not selected (tsplc target)"}`,
+      );
+      console.log(
+        `Release     ${status.release ? `${status.release.id}, ${status.release.operation} at ${status.release.deployedAt}` : "none"}`,
+      );
+      console.log(
+        `Server      ${status.server ? `${status.server.running ? "running" : "restarting"} (${status.server.executable})` : "none"}`,
+      );
+      console.log(
+        `Login       ${status.login ? `open; application ${status.login.state}${status.login.forced.length ? `; forced: ${status.login.forced.join(", ")}` : ""}` : "closed"}`,
+      );
+      return;
+    }
+    case "login":
+      expect(0, "");
+      await ensureLogin(agent);
+      printLogin(await agent.command({ command: "state" }));
+      return;
+    case "logout": {
+      expect(0, "");
+      const forced = (await agent.status()).login?.forced ?? [];
+      if (
+        forced.length &&
+        !(await confirm(
+          `Forced: ${forced.join(", ")}. Forces stay on the controller after logout. Log out anyway?`,
+          flags,
+        ))
+      )
+        throw new Error("Cancelled.");
+      await agent.logout();
+      console.log("Logged out.");
+      return;
+    }
+    case "vars": {
+      if (args.length > 1) throw new Error("Usage: tsplc vars [path]");
+      const variables = await agent.variables();
+      const children = variableChildren(variables, args[0] ?? "");
+      if (!children.length) throw new Error(`No published variable ${args[0]}.`);
+      for (const child of children)
+        console.log(`${child.name.padEnd(32)} ${child.type ?? `${child.leaves} variables`}`);
+      return;
+    }
+    case "read": {
+      const [first, ...rest] = args;
+      if (!first) throw new Error("Usage: tsplc read <expression>...");
+      return send({ command: "read", expressions: [first, ...rest] });
+    }
+    case "write":
+    case "force": {
+      const [expression, value, ...extra] = args;
+      if (!expression || !value || extra.length)
+        throw new Error(`Usage: tsplc ${command} <expression> <value>`);
+      return send({ command, values: { [expression]: value } });
+    }
+    case "unforce":
+      return send({ command: "unforce", expressions: args, restore: flags.restore ?? false });
+    case "start":
+      expect(0, "");
+      return send({ command: "start" });
+    case "stop":
+      expect(0, "");
+      if (!(await confirm("Stop the application on the controller?", flags)))
+        throw new Error("Cancelled.");
+      return send({ command: "stop" });
+    case "reset": {
+      expect(1, "warm|cold");
+      const kind = z.enum(["warm", "cold"]).parse(args[0]);
+      if (
+        !(await confirm(
+          `Reset the application (${kind})? It stops and reinitializes its variables.`,
+          flags,
+        ))
+      )
+        throw new Error("Cancelled.");
+      return send({ command: "reset", kind: kind === "warm" ? "Warm" : "Cold" });
+    }
+  }
+};

package/project/project.ts

@@ -158,6 +158,25 @@ export async function checkProject(
   };
 }
 
+/** The installed libraries and fieldbus device tree a CODESYS project of this program needs. */
+async function engineeringInputs(
+  shared: ResolvedTsplcConfig,
+  configFile: string,
+  bundle: Pick<ReturnType<typeof emitCodesys>, "ioMappings">,
+  frozen?: boolean,
+) {
+  const root = dirname(configFile);
+  const tree = await deviceTree(shared, await loadHardware(shared, root));
+  return {
+    libraries: await installLibraries(shared.dependencies, root, { frozen }),
+    // The emitted names locate mapped IO; the tree maps their channels.
+    deviceTree: tree && {
+      ...tree,
+      mappings: bundle.ioMappings.map(({ address, variable }) => ({ address, variable })),
+    },
+  };
+}
+
 export async function buildProject(
   file = "tsplc.config.ts",
   options: {
@@ -166,6 +185,8 @@ export async function buildProject(
     loaded?: LoadedConfig;
     controller?: Controller;
     buildTarget?: BuildTarget;
+    /** Resolve libraries and the device tree into `controllerConfig` even when only emitting. */
+    forController?: boolean;
   } = {},
 ): Promise<{
   directory?: string;
@@ -194,12 +215,18 @@ export async function buildProject(
     if (hasErrors(bundle.diagnostics)) {
       return { diagnostics: bundle.diagnostics };
     }
-    const controllerConfig = checked.shared?.build
+    const shared = checked.shared;
+    const engineering =
+      shared && (!options.emitOnly || options.forController)
+        ? await engineeringInputs(shared, configFile, bundle, options.frozenLockfile)
+        : undefined;
+    const controllerConfig = shared?.build
       ? codesysBuildConfig(checked.plan, bundle, {
           configFile,
           sourceDir: join(previous.output, "st"),
-          outDir: resolve(dirname(configFile), checked.shared.build.outDir),
+          outDir: resolve(dirname(configFile), shared.build.outDir),
           controller: options.controller,
+          ...engineering,
         })
       : undefined;
 
@@ -221,30 +248,17 @@ export async function buildProject(
     let vendor: Awaited<ReturnType<typeof buildCodesys>> | undefined;
     if (!options.emitOnly) {
       // The engineering cache has its own ownership marker and survives clean.
-      const engineering = checked.shared?.build
-        ? resolve(dirname(configFile), checked.shared.build.outDir ?? "build")
+      const outDir = shared?.build
+        ? resolve(dirname(configFile), shared.build.outDir ?? "build")
         : join(previous.root, "engineering");
-      const libraries = checked.shared
-        ? await installLibraries(checked.shared.dependencies, dirname(configFile), {
-            frozen: options.frozenLockfile,
-          })
-        : undefined;
-      await engineeringDirectory(engineering, configFile);
-      const tree =
-        checked.shared &&
-        (await deviceTree(checked.shared, await loadHardware(checked.shared, dirname(configFile))));
+      await engineeringDirectory(outDir, configFile);
       try {
         vendor = await buildCodesys(checked.plan, bundle, {
           configFile,
           sourceDir: join(staging, "st"),
-          outDir: engineering,
-          libraries,
+          outDir,
           controller: options.controller,
-          // The emitted names locate mapped IO; the tree maps their channels.
-          deviceTree: tree && {
-            ...tree,
-            mappings: bundle.ioMappings.map(({ address, variable }) => ({ address, variable })),
-          },
+          ...engineering,
         });
       } catch (cause) {
         return { diagnostics: diagnoseCodesys(cause, bundle) };