@tsplc/config 0.0.0-stage → 0.2.0

package/src/loader.ts

@@ -0,0 +1,20 @@
+import { readFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { createJiti } from "jiti";
+import { tsplcConfigSchema } from "./schema.ts";
+export async function loadTsplcConfig(file = "tsplc.config.ts") {
+  const configFile = resolve(file);
+  await readFile(configFile);
+  const jiti = createJiti(import.meta.url, {
+    moduleCache: false,
+    fsCache: false,
+    interopDefault: false,
+    // Bun can import TS natively, but its module cache would hide config edits.
+    tryNative: false,
+  });
+  const module = await jiti.import<{ default?: unknown; config?: unknown }>(configFile);
+  const config = tsplcConfigSchema.parse(module.default ?? module.config);
+  if (config.compiler && !config.tasks)
+    throw new Error("TypeScript programs require a tasks configuration.");
+  return { configFile, root: dirname(configFile), config };
+}

package/src/schema.ts

@@ -0,0 +1,408 @@
+import { z } from "zod";
+import {
+  configSchema,
+  controllerDevices,
+  controllerTargetSchema,
+  cyclicTasksSchema,
+  directIoBindingSchema,
+  ioBindingOptions,
+  ethernetSchema,
+  type CodesysBuildConfig,
+} from "./build-schema.ts";
+import {
+  durationSchema,
+  validateConfig as validateCompilerConfig,
+  type PlcConfig,
+} from "./compiler.ts";
+
+export {
+  ns,
+  ms,
+  seconds,
+  definePlcConfig,
+  validateConfig,
+  type Duration,
+  type NormalizedConfig,
+  type PlcConfig,
+  type SourceExport,
+  type TargetDescriptor,
+  type TaskConfig,
+} from "./compiler.ts";
+export type { CodesysBuildConfig, Controller, DeviceTree } from "./build-schema.ts";
+
+export const httpOptionsSchema = z
+  .strictObject({
+    timeoutMs: z.number().int().positive().max(60000).default(2000),
+    credentials: z
+      .array(
+        z.strictObject({
+          originEnv: z.string().regex(/^[A-Za-z_][A-Za-z0-9_]*$/),
+          bearerTokenEnv: z.string().regex(/^[A-Za-z_][A-Za-z0-9_]*$/),
+        }),
+      )
+      .default([]),
+  })
+  .default({ timeoutMs: 2000, credentials: [] });
+export type HttpOptions = z.infer<typeof httpOptionsSchema>;
+
+const ioBindingSchema = z.union([
+  directIoBindingSchema,
+  z.strictObject({
+    device: z.string().min(1),
+    channel: z.string().min(1),
+    ...ioBindingOptions,
+  }),
+]);
+// Each field defaults: the assembly from the connection, the size from the EDS and,
+// with a generated device tree, the address from tsPLC's process-image layout.
+const assemblySchema = z.strictObject({
+  assembly: z.number().int().nonnegative().optional(),
+  size: z.number().int().positive().optional(),
+  address: z
+    .string()
+    .regex(/^%[IQ]B\d+$/)
+    .optional(),
+});
+const hardwareDeviceSchema = z.strictObject({
+  file: z.string().min(1),
+  connection: z.string().min(1).optional(),
+  inputs: assemblySchema.optional(),
+  outputs: assemblySchema.optional(),
+  // Registers the generated device tree writes over Modbus TCP, at network.address.
+  // Each maps a name to its wire offset, and is written with FC06 when its write channel rises.
+  modbus: z
+    .strictObject({
+      port: z.number().int().min(1).max(65535).default(502),
+      registers: z.record(
+        z.string().regex(/^[A-Za-z][A-Za-z0-9_]*$/),
+        z.number().int().min(0).max(65535),
+      ),
+    })
+    .optional(),
+  statusSymbols: z.record(z.string(), z.string()).optional(),
+  // The adapter's network identity in a generated device tree.
+  network: z
+    .strictObject({
+      address: z.ipv4().optional(),
+      rpi: durationSchema
+        .refine(
+          (rpi) => BigInt(rpi.nanoseconds) % 1000n === 0n,
+          "An RPI must be a whole number of microseconds.",
+        )
+        .optional(),
+    })
+    .optional(),
+});
+const dependencySchema = z.union([
+  z.string().regex(/^\d+\.\d+\.\d+\.\d+$/),
+  z.strictObject({
+    version: z.string().regex(/^\d+\.\d+\.\d+\.\d+$/),
+    company: z.string().optional(),
+    namespace: z.string().optional(),
+  }),
+  z.strictObject({ path: z.string().min(1), namespace: z.string().optional() }),
+]);
+const taskSchema = z.strictObject({
+  name: z.string().regex(/^[A-Za-z][A-Za-z0-9_]*$/),
+  schedule: z.strictObject({ kind: z.literal("cyclic"), interval: durationSchema }),
+  priority: z.number().int().min(0).max(31),
+  programs: z.array(z.string().min(1)).nonempty(),
+});
+const monitorSchema = z
+  .strictObject({
+    endpoint: z.string().url(),
+    namespaceUri: z.string().optional(),
+    symbols: z.array(z.string().min(1)).optional(),
+    securityMode: z.enum(["None", "Sign", "SignAndEncrypt"]).default("SignAndEncrypt"),
+    securityPolicy: z.enum(["None", "Basic256Sha256"]).optional(),
+    certificateDirectory: z.string().min(1).default(".tsplc/opcua-pki"),
+    username: z.string().min(1).optional(),
+    passwordEnv: z
+      .string()
+      .regex(/^[A-Za-z_][A-Za-z_0-9]*$/)
+      .optional(),
+  })
+  .superRefine((monitor, context) => {
+    if (
+      monitor.securityPolicy &&
+      (monitor.securityMode === "None") !== (monitor.securityPolicy === "None")
+    )
+      context.addIssue({
+        code: "custom",
+        path: ["securityPolicy"],
+        message: "None mode requires None policy; secure modes require Basic256Sha256.",
+      });
+    if (monitor.passwordEnv && !monitor.username)
+      context.addIssue({
+        code: "custom",
+        path: ["username"],
+        message: "Configure username when passwordEnv is used.",
+      });
+    if (monitor.username && monitor.securityMode === "None")
+      context.addIssue({
+        code: "custom",
+        path: ["securityMode"],
+        message: "Username authentication requires a secure OPC-UA connection.",
+      });
+  })
+  .transform((monitor) => ({
+    ...monitor,
+    securityPolicy:
+      monitor.securityPolicy ??
+      (monitor.securityMode === "None" ? ("None" as const) : ("Basic256Sha256" as const)),
+  }));
+export const typegenSchema = z.strictObject({
+  types: z.union([z.string(), z.array(z.string())]).optional(),
+  globals: z.union([z.string(), z.array(z.string())]).optional(),
+  /** Directory for the generated `plc.ts`, `hardware.ts` and `machines.ts`. */
+  dir: z.string().default("generated"),
+  /** Emit TypeScript declarations in `plc.ts`, not just the runtime field and symbol tables. */
+  declarations: z.boolean().default(true),
+  /** Emit the I/O binding types and device catalog in `hardware.ts`, not just the publication selectors. */
+  ioTypes: z.boolean().default(true),
+});
+export const buildTargetSchema = z.enum(["production", "development"]);
+export type BuildTarget = z.infer<typeof buildTargetSchema>;
+export const publicationSchema = z.strictObject({
+  production: z.array(z.string().nonempty()),
+  development: z.array(z.string().nonempty()),
+});
+export type Publication = Readonly<Record<BuildTarget, readonly string[]>>;
+/** A published PLC variable, as `Global.Field`. */
+const hmiTarget = z.string().regex(/^\w+(\.\w+|\[\d+\])+$/);
+const hmiControlSchema = z.discriminatedUnion("kind", [
+  /** Pulses a BOOL on for 200 ms, like a pushbutton. */
+  z.strictObject({
+    kind: z.literal("button"),
+    label: z.string().nonempty(),
+    target: hmiTarget,
+    tone: z.enum(["start", "stop"]).optional(),
+    /** Ask before pressing, for controls that start motion. */
+    confirm: z.boolean().optional(),
+  }),
+  /** Switches a BOOL on or off, and shows its current state. */
+  z.strictObject({
+    kind: z.literal("toggle"),
+    label: z.string().nonempty(),
+    target: hmiTarget,
+  }),
+  /** Writes an integer when released, and shows its current value. */
+  z.strictObject({
+    kind: z.literal("slider"),
+    label: z.string().nonempty(),
+    target: hmiTarget,
+    min: z.number().int(),
+    max: z.number().int(),
+  }),
+]);
+export const hmiSchema = z.strictObject({
+  title: z.string().nonempty(),
+  controls: z.array(hmiControlSchema).default([]),
+  /** The PLC reports whether each position of these conveyors is occupied, in this order. */
+  conveyors: z
+    .array(
+      z.strictObject({
+        label: z.string().nonempty(),
+        positions: z.number().int().positive(),
+        /** Positions that are diverters, drawn differently. */
+        diverters: z.array(z.number().int().nonnegative()).default([]),
+      }),
+    )
+    .default([]),
+});
+export type HmiConfig = z.input<typeof hmiSchema>;
+export type ResolvedHmiConfig = z.output<typeof hmiSchema>;
+
+export const tsplcConfigSchema = z.strictObject({
+  name: z.string().default("Application"),
+  backend: z.literal("codesys"),
+  publish: publicationSchema.optional(),
+  server: z
+    .strictObject({
+      baseUrlEnv: z.string().optional(),
+      transport: z.enum(["http", "opcua"]).default("http"),
+      runtime: z
+        .strictObject({
+          entry: z.string(),
+          target: z
+            .enum([
+              "bun-linux-x64",
+              "bun-linux-arm64",
+              "bun-darwin-x64",
+              "bun-darwin-arm64",
+              "bun-windows-x64",
+            ])
+            .optional(),
+        })
+        .optional(),
+    })
+    .optional(),
+  compiler: z
+    .strictObject({
+      tsconfig: z.string().default("tsconfig.json"),
+      programs: z.record(z.string(), z.strictObject({ module: z.string(), export: z.string() })),
+    })
+    .optional(),
+  tasks: z.array(taskSchema).nonempty().optional(),
+  // Keep an authored legacy task distinguishable from resolveConfig's default.
+  // An explicit shared schedule must have a single owner.
+  build: configSchema.extend({ task: configSchema.shape.task.unwrap().optional() }).optional(),
+  codesys: z
+    .strictObject({
+      http: httpOptionsSchema.optional(),
+      programNames: z.record(z.string(), z.string()).optional(),
+      // Generate an EtherNet/IP scanner with one adapter per entry in devices.
+      deviceTree: z.strictObject({ ethernet: ethernetSchema.optional() }).optional(),
+      // Each omitted controller keeps the template's device. See controllerFor.
+      controllers: z
+        .strictObject({
+          production: controllerTargetSchema.optional(),
+          development: controllerTargetSchema.optional(),
+        })
+        .optional(),
+    })
+    .optional(),
+  eds: z.union([z.string(), z.array(z.string())]).default("eds"),
+  devices: z.record(z.string(), hardwareDeviceSchema).default({}),
+  io: z.record(z.string(), ioBindingSchema).default({}),
+  dependencies: z.record(z.string(), dependencySchema).default({}),
+  // Raw ST builds opt into PLC contract generation by configuring this section.
+  typegen: typegenSchema.optional(),
+  monitor: monitorSchema.optional(),
+  hmi: hmiSchema.optional(),
+});
+export type TsplcConfig = z.input<typeof tsplcConfigSchema>;
+export type ResolvedTsplcConfig = z.output<typeof tsplcConfigSchema>;
+export type HardwareDevice = z.infer<typeof hardwareDeviceSchema>;
+export type LibraryDependency = z.infer<typeof dependencySchema>;
+
+/**
+ * `build` compiles for the production controller. `run` and controller
+ * operations target the local runtime, so they compile for the development one.
+ */
+export const buildTargetFor = (command: string): BuildTarget =>
+  ["run", "download", "online-change", "inspect"].includes(command) ? "development" : "production";
+export const controllerFor = (config: ResolvedTsplcConfig, command: string) => {
+  const controller = config.codesys?.controllers?.[buildTargetFor(command)];
+  return controller && { ...controllerDevices[controller.target], version: controller.version };
+};
+
+/**
+ * The project without fieldbus I/O, for a plant simulator that writes inputs over
+ * OPC UA: fieldbus input copies would overwrite those writes every scan.
+ */
+export const simulationConfig = (config: ResolvedTsplcConfig): ResolvedTsplcConfig => ({
+  ...config,
+  eds: [],
+  devices: {},
+  io: {},
+  ...(config.codesys && {
+    codesys: {
+      ...config.codesys,
+      deviceTree: undefined,
+    },
+  }),
+});
+
+/** All paths are relative to this file; no package has a second project config. */
+export function defineConfig<const C extends TsplcConfig>(config: C): C {
+  return config;
+}
+
+/** Raw ST program names already are IEC names; use the shared schedule directly. */
+export function rawBuildConfig(config: ResolvedTsplcConfig): CodesysBuildConfig {
+  if (config.compiler) throw new Error("Use the compiler build plan for TypeScript projects.");
+  if (!config.build) throw new Error("Configure build settings.");
+  if (!config.tasks) return config.build;
+  if (config.build.tasks || config.build.task !== undefined)
+    throw new Error("Configure the raw ST schedule in tasks or build.tasks/build.task, not both.");
+  return {
+    ...config.build,
+    tasks: cyclicTasksSchema.parse(
+      config.tasks.map((task) => ({
+        name: task.name,
+        intervalNanoseconds: task.schedule.interval.nanoseconds,
+        priority: task.priority,
+        programs: task.programs,
+      })),
+    ),
+  };
+}
+
+/** Adapt the shared project to the compiler's backend-independent scan model. */
+export function compilerConfig(
+  config: ResolvedTsplcConfig,
+  io: Record<string, { address: string; type?: string }>,
+  buildTarget: BuildTarget = "production",
+) {
+  if (!config.compiler || !config.tasks)
+    throw new Error("This project uses raw Structured Text; no TypeScript compiler is configured.");
+  // The device tree and controllers are build-time engineering; the compiler only sees addresses.
+  const { deviceTree: _deviceTree, controllers: _controllers, ...codesys } = config.codesys ?? {};
+  const value: PlcConfig = {
+    name: config.name,
+    tsconfig: config.compiler.tsconfig,
+    programs: config.compiler.programs,
+    tasks: config.tasks,
+    target: {
+      kind: config.backend,
+      options: {
+        ...codesys,
+        publish: config.publish,
+        buildTarget,
+        io: Object.fromEntries(
+          Object.entries(io).map(([name, binding]) => [
+            name,
+            {
+              kind: "direct",
+              ...binding,
+              ...(mappedChannel(config, name, binding) && { mapped: true }),
+            },
+          ]),
+        ),
+        engineering: {
+          kind: "v3.5",
+          ...(config.build ? { build: compilerBuildOptions(config.build) } : {}),
+        },
+      },
+    },
+  };
+  const validated = validateCompilerConfig(value);
+  if (!validated.config)
+    throw new Error(validated.diagnostics.map((item) => item.message).join("\n"));
+  return validated.config;
+}
+
+/**
+ * A generated device tree maps a device's bit or byte scalar to its variable in the
+ * I/O mapping. Wider values span several byte channels and keep an AT declaration.
+ */
+function mappedChannel(
+  config: ResolvedTsplcConfig,
+  name: string,
+  binding: { address: string; type?: string; inverted?: boolean; shared?: boolean },
+) {
+  const source = config.io[name];
+  return (
+    config.codesys?.deviceTree !== undefined &&
+    source !== undefined &&
+    "device" in source &&
+    // A channel maps to one variable as it stands, so these need an AT wire and a copy.
+    !binding.inverted &&
+    !binding.shared &&
+    /^%[IQ][XB]/.test(binding.address) &&
+    !/^ARRAY/i.test(binding.type ?? "")
+  );
+}
+
+function compilerBuildOptions(build: CodesysBuildConfig) {
+  const {
+    sourceDir: _source,
+    entry: _entry,
+    outDir: _out,
+    task: _task,
+    tasks: _tasks,
+    ...settings
+  } = build;
+  return settings;
+}

package/templates/README.md

@@ -0,0 +1,17 @@
+# Default engineering scaffold
+
+`default.project` is the SDK-owned CODESYS Virtual Control for Linux ARM64
+4.22.0.0 scaffold, saved with CODESYS V3.5 SP22 Patch 3. It contains the controller,
+Application, Library Manager and a 20 ms MainTask with an empty `PLC_PRG`.
+Library references include Standard, Util 3.5.22.0 (System), and device-provided
+placeholders. The compiler’s “UTF8 Encoding for STRING” option is enabled, matching
+tsPLC’s STRING contract and OPC UA encoding. No gateway or runtime credentials are selected.
+
+`provenance.json` pins the project hash. Builds copy the file into their private
+workspace and remove `PLC_PRG` automatically. Generated task definitions,
+controller selection, dependencies and hardware configuration supply the
+application-specific settings. The installed builder image supplies the vendor
+libraries and device descriptions.
+
+Applications may override `build.template` for custom engineering projects.
+Those keep their objects unless explicitly removed or replaced during import.

package/templates/provenance.json

@@ -0,0 +1,8 @@
+{
+  "project": "default.project",
+  "sha256": "41eae36376ecbb7556b124a1e3b5f975e2fce23703d1fc2d6421c9bc95378155",
+  "codesys": "CODESYS V3.5 SP22 Patch 3",
+  "target": "CODESYS Virtual Control for Linux ARM64 4.22.0.0",
+  "addedLibrary": "Util, 3.5.22.0 (System)",
+  "stringEncoding": "UTF-8"
+}