miravo 0.6.0 → 0.6.2

package/src/lib/le/le-template-exporter.ts

@@ -1,459 +0,0 @@
-/**
- * Litmus Edge template export (JSON + tags CSV) from desired state.
- *
- * The JSON template includes hardcoded `driverId` per protocol to support direct upload to LE.
- * The CSV template uses `driverName` since that is expected by the LE CSV import format.
- */
-
-import type { ProtocolName } from "@miravo/shared";
-import type { ApplyDesiredState, DesiredDevice, DesiredTag } from "./le-apply.ts";
-import { buildLeDeviceHubDeviceProperties } from "./le-devicehub-properties.ts";
-import { LE_DRIVER_IDS, LE_DRIVER_NAMES } from "./le-drivers.ts";
-import { encodeDeviceMarkers } from "./le-markers.ts";
-
-const ZERO = "00000000-0000-0000-0000-000000000000";
-
-interface LeExportResult {
-  readonly templateJson: string;
-  readonly tagsCSV: string;
-}
-
-/**
- * Convert offline desired state into a full LE template JSON + tags CSV.
- *
- * The JSON includes devicehub devices with registers, DT models and instances,
- * and stats config. The CSV covers all tags across all devices in one file,
- * with deviceId/registerId cross-referenced from the generated template.
- */
-export function buildLeExport(desired: ApplyDesiredState, templateId: string): LeExportResult {
-  const generatedDevices = desired.devices.map((d) => generateDevice(d, templateId));
-  const modelObjects = extractModelObjects(desired, templateId);
-  const modelByName = new Map(
-    modelObjects.map((m) => [(m as Record<string, unknown>)["name"] as string, m]),
-  );
-  const instanceObjects = desired.instances.map((inst) => {
-    const model = modelByName.get(inst.dtModelName);
-    if (!model) throw new Error(`Model "${inst.dtModelName}" not found in desired state`);
-    return buildInstance(
-      crypto.randomUUID(), // LE requires a UUID, not the human-readable instanceId
-      inst.dtInstanceName,
-      inst.modelName,
-      inst.boundDeviceName,
-      templateId,
-      model as Record<string, unknown>,
-      inst.browsePath,
-    );
-  });
-
-  const template = {
-    devicehub: { Devs: generatedDevices.map((g) => g.devObj) },
-    dtwin: { models: modelObjects, instances: instanceObjects },
-    stats: buildStats(generatedDevices),
-  };
-
-  return {
-    templateJson: JSON.stringify(template, null, 2),
-    tagsCSV: buildTagsCSV(generatedDevices),
-  };
-}
-
-interface GeneratedDevice {
-  readonly id: string;
-  readonly name: string;
-  readonly instanceId: string;
-  readonly modelName: string;
-  readonly protocol: ProtocolName;
-  readonly registers: GeneratedRegister[];
-  readonly devObj: unknown;
-}
-
-interface GeneratedRegister {
-  readonly id: string;
-  readonly tag: DesiredTag;
-  readonly protocol: ProtocolName;
-}
-
-function generateDevice(device: DesiredDevice, templateId: string): GeneratedDevice {
-  const deviceId = crypto.randomUUID();
-  const registers: GeneratedRegister[] = device.tags.map((tag) => ({
-    id: crypto.randomUUID(),
-    tag,
-    protocol: device.protocol,
-  }));
-
-  const markers = encodeDeviceMarkers({
-    templateId,
-    instanceId: device.instanceId,
-    modelName: device.modelName,
-    protocol: device.protocol,
-    unsPath: device.browsePath,
-  });
-
-  const devObj = {
-    Dev: {
-      id: deviceId,
-      name: device.deviceName,
-      driverId: LE_DRIVER_IDS[device.protocol],
-      settings: buildDeviceSettings(device),
-      aliasTopics: true,
-      meta_tags: Object.fromEntries(markers.map(({ Key, Value }) => [Key, Value])),
-      debug: false,
-      stopped: true,
-      version: "0.0.1",
-    },
-    Registers: registers.map((r) => buildRegisterObj(r, deviceId)),
-  };
-
-  return {
-    id: deviceId,
-    name: device.deviceName,
-    instanceId: device.instanceId,
-    modelName: device.modelName,
-    protocol: device.protocol,
-    registers,
-    devObj,
-  };
-}
-
-function buildDeviceSettings(device: DesiredDevice): Record<string, string> {
-  const { host, port } = device.endpoint;
-  return Object.fromEntries(
-    buildLeDeviceHubDeviceProperties(device.protocol, host, port).map((item) => [
-      item.Key,
-      item.Value,
-    ]),
-  );
-}
-
-function buildRegisterObj(reg: GeneratedRegister, deviceId: string): Record<string, unknown> {
-  return {
-    id: reg.id,
-    deviceId,
-    value_type: reg.tag.valueType,
-    name: reg.tag.name,
-    tag_name: reg.tag.tagName,
-    settings: buildRegisterSettings(reg.tag, reg.protocol),
-  };
-}
-
-function buildRegisterSettings(tag: DesiredTag, protocol: ProtocolName): Record<string, string> {
-  if (protocol === "modbus") {
-    const propMap = new Map(tag.properties.map((p) => [p.Key, p.Value]));
-    return {
-      address: propMap.get("address") ?? "0",
-      count: propMap.get("count") ?? "1",
-      pollingInterval: "1000",
-    };
-  }
-  return {};
-}
-
-/**
- * Adapt leDtJson models for /dm/template/v2 import. The ImportModel mutation
- * and the template import use different subsets of the model schema:
- *
- * - version: must be absent (0 causes "restore failed")
- * - dynamicAttributes.topicExpression: must be absent (template rejects it; instances carry it)
- * - parameters: must include id/ownerId/ownerType (template rejects simple {name,value} form)
- * - staticAttributes: $param.* references and __miravo_placeholder__ are resolved/sanitized
- */
-function extractModelObjects(desired: ApplyDesiredState, templateId: string): unknown[] {
-  return desired.models.flatMap((m) => {
-    const arr = m.leDtJson as unknown[];
-    const models = Array.isArray(arr) ? arr : [arr];
-    return models.map((model) => {
-      if (!model || typeof model !== "object") return model;
-      const { version: _v, ...rest } = model as Record<string, unknown>;
-      const modelId = rest["id"] as string;
-      const modelNameLower = String(rest["name"] ?? "").toLowerCase();
-
-      const dynAttrs = rest["dynamicAttributes"] as Array<Record<string, unknown>> | undefined;
-      if (dynAttrs) {
-        rest["dynamicAttributes"] = dynAttrs.map(
-          ({ topicExpression: _te, topic: _t, ...attr }) => ({
-            ...attr,
-            topic: "",
-            unit: sanitizeUnit(String(attr["unit"] ?? "")),
-          }),
-        );
-      }
-
-      const params = rest["parameters"] as Array<Record<string, unknown>> | undefined;
-      if (params?.[0] && !params[0]["id"]) {
-        rest["parameters"] = params.map((p) => ({
-          id: crypto.randomUUID(),
-          ownerId: modelId,
-          ownerType: 2,
-          name: p["name"],
-          value: p["value"],
-        }));
-      }
-
-      const staticAttrs = rest["staticAttributes"] as Array<Record<string, unknown>> | undefined;
-      if (staticAttrs) {
-        rest["staticAttributes"] = staticAttrs.map((a) => {
-          const key = String(a["key"] ?? "");
-          let value = String(a["value"] ?? "");
-          // Resolve miravo marker placeholders at model level where possible
-          if (value === "__miravo_placeholder__") {
-            if (key === "miravo_template") value = templateId;
-            else if (key === "miravo_model") value = modelNameLower;
-            // miravo_instance cannot be resolved at model level — keep placeholder
-          }
-          // Template-exported models are Miravo-owned — mark as managed so cleanup can target them
-          if (key === "miravo_managed") value = "true";
-          // LE rejects $param.* template references and empty values
-          if (value.startsWith("$")) value = "N/A";
-          return { ...a, value };
-        });
-      }
-
-      return rest;
-    });
-  });
-}
-
-function buildInstance(
-  instanceId: string,
-  instanceName: string,
-  modelName: string,
-  deviceName: string,
-  templateId: string,
-  model: Record<string, unknown>,
-  browsePath: string,
-): Record<string, unknown> {
-  const modelId = model["id"] as string;
-  const modelNameLower = (model["name"] as string).toLowerCase();
-
-  const modelDynAttrs = (model["dynamicAttributes"] as Array<Record<string, unknown>>) ?? [];
-  const modelStaticAttrs = (model["staticAttributes"] as Array<Record<string, unknown>>) ?? [];
-  const modelParams = (model["parameters"] as Array<Record<string, unknown>>) ?? [];
-
-  const dynamicAttributes = modelDynAttrs.map((a) => {
-    const name = String(a["name"] ?? "");
-    // The LE template import format rejects `topicExpression` on model objects
-    // (extractModelObjects strips it), but instance objects require it.
-    // Reconstruct it here using the standard devicehub alias formula; the {device}
-    // parameter is resolved at runtime by LE using the instance's bound device name.
-    const topicExpression =
-      (a["topicExpression"] as string | undefined) || `devicehub.alias.{device}.${name}`;
-    return {
-      id: crypto.randomUUID(),
-      modelId: ZERO,
-      parentId: a["id"] as string,
-      instanceId,
-      topic: "",
-      name,
-      unit: sanitizeUnit(String(a["unit"] ?? "")),
-      dataType: a["dataType"] ?? "",
-      schemaId: ZERO,
-      skipParentKey: a["skipParentKey"] ?? false,
-      topicExpression,
-    };
-  });
-
-  const staticAttributes = modelStaticAttrs.map((a) => {
-    const key = String(a["key"] ?? "");
-    let value: string;
-    switch (key) {
-      case "miravo_managed":
-        value = "true";
-        break;
-      case "miravo_template":
-        value = templateId;
-        break;
-      case "miravo_model":
-        value = modelName;
-        break;
-      case "miravo_instance":
-        value = instanceName;
-        break;
-      case "uns_path":
-        value = browsePath;
-        break;
-      default:
-        value = sanitizeStaticValue(String(a["value"] ?? ""));
-    }
-    return {
-      id: crypto.randomUUID(),
-      parentId: a["id"] as string,
-      modelId: ZERO,
-      instanceId,
-      key,
-      value,
-      type: a["type"] ?? 0,
-    };
-  });
-
-  // Override model's {device} parameter with the bound device name.
-  const parameters = modelParams.map((p) => ({
-    id: crypto.randomUUID(),
-    ownerId: instanceId,
-    ownerType: 1,
-    name: p["name"] as string,
-    value: p["name"] === "device" ? deviceName : (p["value"] as string),
-  }));
-
-  return {
-    id: instanceId,
-    modelId,
-    name: instanceName,
-    topic: `digitaltwins.${modelNameLower}.${instanceName}`,
-    interval: 1,
-    image: "",
-    dynamicAttributes,
-    staticAttributes,
-    transformationBackup: null,
-    parameters,
-    flatten: false,
-    isEnabled: true,
-    publishAttributes: false,
-  };
-}
-
-function buildStats(devices: GeneratedDevice[]): Record<string, unknown> {
-  const statsDevices = devices.map((d) => ({
-    name: d.name,
-    id: d.id,
-    retention_hours: 720,
-    save_all: true,
-    topic: `devicehub.alias.${d.name}.>`,
-  }));
-
-  const timeseries = devices.map((d) => ({
-    id: d.id,
-    name: d.name,
-    topics: [`devicehub.alias.${d.name}.>`],
-  }));
-
-  return {
-    devices: statsDevices,
-    timeseries,
-    timeseries_db: { source: "internal", enabled: true },
-  };
-}
-
-/** LE DeviceHub CSV header — matches the real LE export format. */
-const CSV_HEADER =
-  "deviceId,deviceName,driverName,name,tagName,description,valueType,registerId,publishCoV,tagFormula,metaData,Retain,Qos,address,count,pollingInterval,endianness";
-
-function buildTagsCSV(devices: GeneratedDevice[]): string {
-  const rows = [CSV_HEADER];
-  for (const device of devices) {
-    for (const reg of device.registers) {
-      rows.push(buildCSVRow(device, reg));
-    }
-  }
-  return `${rows.join("\n")}\n`;
-}
-
-function buildCSVRow(device: GeneratedDevice, reg: GeneratedRegister): string {
-  const { id: deviceId, name: deviceName, instanceId, modelName, protocol } = device;
-  const { tag, id: registerId } = reg;
-  const driverName = LE_DRIVER_NAMES[protocol];
-  const propMap = new Map(tag.properties.map((p) => [p.Key, p.Value]));
-  const metaData = buildTagMetaDataJson(tag, instanceId, modelName);
-
-  switch (protocol) {
-    case "opcua":
-      return [
-        deviceId,
-        esc(deviceName),
-        esc(driverName),
-        esc(tag.name), // OPC-UA NodeId
-        esc(tag.tagName),
-        "",
-        tag.valueType,
-        registerId,
-        "false",
-        "",
-        metaData,
-        "",
-        "",
-        "",
-        "",
-        "",
-        "",
-      ].join(",");
-
-    case "modbus":
-      return [
-        deviceId,
-        esc(deviceName),
-        esc(driverName),
-        "H", // Holding register
-        esc(tag.tagName),
-        "",
-        tag.valueType,
-        registerId,
-        "false",
-        "",
-        metaData,
-        "",
-        "",
-        propMap.get("address") ?? "0",
-        propMap.get("count") ?? "1",
-        "1.0000000000",
-        "AB CD",
-      ].join(",");
-
-    case "mqtt":
-      return [
-        deviceId,
-        esc(deviceName),
-        esc(driverName),
-        esc(tag.name), // MQTT topic
-        esc(tag.tagName),
-        "",
-        tag.valueType,
-        registerId,
-        "false",
-        "",
-        metaData,
-        "Disable",
-        "0",
-        "",
-        "",
-        "",
-        "",
-      ].join(",");
-
-    default: {
-      const _never: never = protocol;
-      throw new Error(`Unknown protocol: ${_never}`);
-    }
-  }
-}
-
-function buildTagMetaDataJson(tag: DesiredTag, instanceId: string, modelName: string): string {
-  const meta: Record<string, string> = {
-    uns_path: tag.unsPath,
-    model: modelName,
-    instance: instanceId,
-    access: tag.access,
-  };
-  if (tag.unit) meta["unit"] = tag.unit;
-  if (tag.euRange) {
-    meta["eu_range_min"] = String(tag.euRange[0]);
-    meta["eu_range_max"] = String(tag.euRange[1]);
-  }
-  return esc(JSON.stringify(meta));
-}
-
-function esc(value: string): string {
-  if (value.includes(",") || value.includes('"') || value.includes("\n")) {
-    return `"${value.replace(/"/g, '""')}"`;
-  }
-  return value;
-}
-
-/** LE rejects staticAttribute values that are empty or have leading/trailing spaces. */
-function sanitizeStaticValue(value: string): string {
-  const trimmed = value.trim();
-  return trimmed.length > 0 ? trimmed : "N/A";
-}
-
-/** LE rejects dynamicAttribute units containing /, ^, or %. */
-function sanitizeUnit(unit: string): string {
-  return unit.replace(/[/^%]/g, "");
-}

package/src/lib/le/le-value-types.ts

@@ -1,23 +0,0 @@
-/**
- * Miravo → LE value type mappings (shared between export and apply).
- */
-
-/** OPC UA: map Miravo data types to LE OPC UA Client Advanced value types. */
-export const OPCUA_VALUE_TYPE: Readonly<Record<string, string>> = {
-  Boolean: "bool",
-  Int32: "int32",
-  UInt16: "uint16",
-  UInt32: "uint32",
-  Float: "float32",
-  Double: "float64",
-  String: "string",
-};
-
-/** Modbus: map Miravo register encodings to LE Modbus TCP value types. */
-export const MODBUS_VALUE_TYPE: Readonly<Record<string, string>> = {
-  float32: "float32",
-  int32: "int32",
-  uint32: "uint32",
-  uint16: "word",
-  boolean: "word",
-};

package/src/lib/mqtt-client.ts

@@ -1,115 +0,0 @@
-import { resolve } from "node:path";
-import { loadTemplate } from "@miravo/core";
-import { DEFAULT_MQTT_PORT, MiravoError } from "@miravo/shared";
-import type { MqttClient } from "mqtt";
-import { connect } from "mqtt";
-
-interface BrokerConnectionInfo {
-  readonly url: string;
-  readonly port: number;
-  readonly username?: string | undefined;
-  readonly password?: string | undefined;
-}
-
-/**
- * Resolve broker connection info from a template file or defaults.
- * Checks the template's `protocols.mqtt` config for an external URL or port.
- * Falls back to the default embedded broker at `mqtt://127.0.0.1:1883`.
- */
-async function resolveBrokerInfo(templatePath?: string): Promise<BrokerConnectionInfo> {
-  if (templatePath) {
-    const resolved = resolve(templatePath);
-    const template = await loadTemplate(resolved);
-    const mqttConfig = template.protocols?.mqtt;
-
-    const username = mqttConfig?.username;
-    const password = mqttConfig?.password;
-
-    if (mqttConfig?.external) {
-      const port = mqttConfig.port ?? DEFAULT_MQTT_PORT;
-      return { url: mqttConfig.external, port, username, password };
-    }
-
-    const port = mqttConfig?.port ?? DEFAULT_MQTT_PORT;
-    return { url: `mqtt://127.0.0.1:${port}`, port, username, password };
-  }
-
-  return { url: `mqtt://127.0.0.1:${DEFAULT_MQTT_PORT}`, port: DEFAULT_MQTT_PORT };
-}
-
-/**
- * Create an MQTT client and wait for connection with a timeout.
- * Rejects with a MiravoError containing an actionable fix message.
- */
-function connectWithTimeout(
-  url: string,
-  timeoutMs: number,
-  credentials?: { username: string; password?: string | undefined },
-): Promise<MqttClient> {
-  return new Promise<MqttClient>((resolve, reject) => {
-    const client = connect(url, {
-      connectTimeout: timeoutMs,
-      reconnectPeriod: 0, // No auto-reconnect for CLI commands
-      ...(credentials !== undefined && {
-        username: credentials.username,
-        ...(credentials.password !== undefined && { password: credentials.password }),
-      }),
-    });
-
-    const timer = setTimeout(() => {
-      client.end(true);
-      reject(
-        new MiravoError(
-          `Cannot connect to MQTT broker at ${url} within ${timeoutMs}ms.`,
-          "Is a simulation running? Start one with 'miravo start'.",
-        ),
-      );
-    }, timeoutMs);
-
-    client.on("connect", () => {
-      clearTimeout(timer);
-      resolve(client);
-    });
-
-    client.once("error", (err) => {
-      clearTimeout(timer);
-      client.end(true);
-      reject(
-        new MiravoError(
-          `MQTT connection error: ${err.message}`,
-          `Check that a simulation is running on ${url}. Start one with 'miravo start'.`,
-        ),
-      );
-    });
-  });
-}
-
-/**
- * Resolve broker info from a template and connect with credentials.
- * Convenience wrapper around resolveBrokerInfo + connectWithTimeout.
- */
-async function connectToBroker(
-  templatePath: string | undefined,
-  timeoutMs: number,
-): Promise<{ client: MqttClient; brokerInfo: BrokerConnectionInfo }> {
-  const brokerInfo = await resolveBrokerInfo(templatePath);
-  const credentials =
-    brokerInfo.username !== undefined
-      ? { username: brokerInfo.username, password: brokerInfo.password }
-      : undefined;
-  const client = await connectWithTimeout(brokerInfo.url, timeoutMs, credentials);
-  return { client, brokerInfo };
-}
-
-/**
- * Safely disconnect an MQTT client. Never throws.
- */
-function disconnectClient(client: MqttClient): void {
-  try {
-    client.end(true);
-  } catch {
-    // Ignore disconnect errors
-  }
-}
-
-export { connectToBroker, disconnectClient };