miravo 0.4.0 → 0.6.0

package/src/commands/start/adapter-config.ts

@@ -0,0 +1,157 @@
+import type { MiravoTemplate, ProtocolConfig } from "@miravo/shared";
+import {
+  ConfigValidationError,
+  DEFAULT_MODBUS_PORT,
+  DEFAULT_MQTT_PORT,
+  DEFAULT_OPCUA_PORT,
+} from "@miravo/shared";
+import { displayHost } from "../../lib/daemon-registry.ts";
+import type { MqttMode, MqttRunOverrides } from "./types.ts";
+
+// ---------------------------------------------------------------------------
+// Step 5: Adapter default config builders
+// ---------------------------------------------------------------------------
+
+export function buildMQTTDefaultConfig(
+  template: MiravoTemplate,
+  portOverride: number | undefined,
+  mqttOverrides: MqttRunOverrides,
+  simulationName: string,
+): Record<string, unknown> {
+  const mqttConfig = template.protocols?.mqtt;
+  const port = portOverride ?? mqttConfig?.port ?? DEFAULT_MQTT_PORT;
+  let embedded = mqttConfig?.embedded ?? true;
+  let external = mqttConfig?.external;
+  let host = "0.0.0.0";
+  let username = mqttConfig?.username;
+  let password = mqttConfig?.password;
+  const modeOverride = mqttOverrides.mode;
+  if (modeOverride !== undefined) {
+    embedded = modeOverride === "embedded";
+    if (embedded) {
+      external = undefined;
+      username = undefined;
+      password = undefined;
+    }
+  }
+  if (mqttOverrides.url !== undefined) external = mqttOverrides.url;
+  if (mqttOverrides.host !== undefined) host = mqttOverrides.host;
+  if (mqttOverrides.username !== undefined) username = mqttOverrides.username;
+  if (mqttOverrides.password !== undefined) password = mqttOverrides.password;
+
+  if (embedded && (external || username || password)) {
+    throw new ConfigValidationError({
+      message: "Embedded MQTT mode cannot be combined with external MQTT URL or credentials.",
+      fix: "Use --mqtt-mode external for external broker settings, or remove external MQTT overrides.",
+    });
+  }
+  if (!embedded && !external) {
+    throw new ConfigValidationError({
+      message: "MQTT mode is external but no broker URL was provided.",
+      fix: "Set protocols.mqtt.external in template or pass --mqtt-url / MIRAVO_MQTT_URL.",
+    });
+  }
+  if (password && !username) {
+    throw new ConfigValidationError({
+      message: "MQTT password was provided without username.",
+      fix: "Provide --mqtt-username / MIRAVO_MQTT_USERNAME when setting a password.",
+    });
+  }
+
+  const drainBudget = mqttOverrides.drainBudget ?? mqttConfig?.drain_budget;
+  const batchSize = mqttOverrides.batchSize ?? mqttConfig?.batch_size;
+  const brokerConcurrency = mqttOverrides.brokerConcurrency ?? mqttConfig?.broker_concurrency;
+
+  return {
+    name: "mqtt",
+    enabled: true,
+    simulationName,
+    embedded,
+    port,
+    host,
+    retain: mqttConfig?.retain ?? false,
+    ...(external !== undefined ? { external } : {}),
+    ...(username !== undefined ? { username } : {}),
+    ...(password !== undefined ? { password } : {}),
+    ...(mqttConfig?.reconnect !== undefined ? { reconnect: mqttConfig.reconnect } : {}),
+    ...(mqttConfig?.rbe !== undefined ? { rbe: mqttConfig.rbe } : {}),
+    ...(mqttConfig?.metadata !== undefined ? { metadata: mqttConfig.metadata } : {}),
+    ...(drainBudget !== undefined ? { drain_budget: drainBudget } : {}),
+    ...(batchSize !== undefined ? { batch_size: batchSize } : {}),
+    ...(brokerConcurrency !== undefined ? { broker_concurrency: brokerConcurrency } : {}),
+  };
+}
+
+export function buildOPCUADefaultConfig(
+  template: MiravoTemplate,
+  portOverride: number | undefined,
+  hostOverride: string | undefined,
+  simulationName: string,
+  writeBudgetOverride?: number,
+): Record<string, unknown> {
+  const opcuaConfig = template.protocols?.opcua;
+  const port = portOverride ?? opcuaConfig?.port ?? DEFAULT_OPCUA_PORT;
+  const host = hostOverride ?? opcuaConfig?.host ?? "0.0.0.0";
+  const writeBudget = writeBudgetOverride ?? opcuaConfig?.write_budget;
+
+  return {
+    name: "opcua",
+    enabled: true,
+    port,
+    host,
+    security: opcuaConfig?.security ?? "none",
+    simulationName,
+    ...(opcuaConfig?.buildInfo ? { buildInfo: opcuaConfig.buildInfo } : {}),
+    ...(writeBudget !== undefined ? { write_budget: writeBudget } : {}),
+  };
+}
+
+export function buildModbusDefaultConfig(
+  template: MiravoTemplate,
+  portOverride: number | undefined,
+  hostOverride: string | undefined,
+): Record<string, unknown> {
+  const modbusConfig = template.protocols?.modbus;
+  const port = portOverride ?? modbusConfig?.port ?? DEFAULT_MODBUS_PORT;
+  const host = hostOverride ?? modbusConfig?.host ?? "0.0.0.0";
+  return { name: "modbus", enabled: true, port, host };
+}
+
+/** Derive the MQTT endpoint string from a resolved adapter config. */
+export function buildMQTTEndpoint(config: ProtocolConfig): string {
+  const cfg = config as Record<string, unknown>;
+  const port = cfg["port"] ?? DEFAULT_MQTT_PORT;
+  const embedded = cfg["embedded"] ?? true;
+  const external = cfg["external"] as string | undefined;
+  return embedded ? `mqtt://localhost:${port}` : (external as string);
+}
+
+/** Derive the OPC UA endpoint string from a resolved adapter config. */
+export function buildOPCUAEndpoint(config: ProtocolConfig): string {
+  const cfg = config as Record<string, unknown>;
+  const port = cfg["port"] ?? DEFAULT_OPCUA_PORT;
+  const host = cfg["host"] ?? "0.0.0.0";
+  const resolvedDisplayHost = host === "0.0.0.0" ? "localhost" : host;
+  return `opc.tcp://${resolvedDisplayHost}:${port}`;
+}
+
+export function buildModbusEndpoint(config: Record<string, unknown>): string {
+  const port = (config as { port?: number }).port ?? DEFAULT_MODBUS_PORT;
+  const host = (config as { host?: string }).host ?? "0.0.0.0";
+  return `modbus://${displayHost(String(host))}:${port}`;
+}
+
+export function parseMqttModeOption(raw: string | undefined): MqttMode | undefined {
+  if (raw === undefined) {
+    return undefined;
+  }
+
+  if (raw === "embedded" || raw === "external") {
+    return raw;
+  }
+
+  throw new ConfigValidationError({
+    message: `Invalid MQTT mode "${raw}".`,
+    fix: "Use --mqtt-mode embedded|external or MIRAVO_MQTT_MODE=embedded|external.",
+  });
+}

package/src/commands/start/catalog-le-dt.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, test } from "bun:test";
+import type { ModelSchema } from "@miravo/shared";
+import { buildLeDtJsonFromSchema } from "./catalog-le-dt.ts";
+
+function parseExport(json: string): {
+  staticAttributes: { key: string; value: string }[];
+} {
+  const payload = JSON.parse(json) as [{ staticAttributes: { key: string; value: string }[] }];
+  return payload[0];
+}
+
+const modelSchema: ModelSchema = {
+  name: "pump",
+  description: "Pump model",
+  parameters: {},
+  members: {
+    serial: {
+      kind: "property",
+      dataType: "String",
+      access: "read",
+      unit: null,
+      euRange: null,
+      default: "P-001",
+    },
+    rpm: {
+      kind: "variable",
+      dataType: "Float",
+      access: "read",
+      unit: null,
+      euRange: null,
+      default: null,
+    },
+  },
+  methods: {},
+  faults: [],
+  lifecycle: null,
+};
+
+describe("catalog LE DT export", () => {
+  test("includes Miravo marker placeholders in single-model export", () => {
+    const exported = parseExport(buildLeDtJsonFromSchema(modelSchema));
+    const markerValues = new Map(exported.staticAttributes.map((attr) => [attr.key, attr.value]));
+
+    expect(markerValues.get("miravo_managed")).toBe("false");
+    expect(markerValues.get("miravo_template")).toBe("__miravo_placeholder__");
+    expect(markerValues.get("miravo_model")).toBe("__miravo_placeholder__");
+    expect(markerValues.get("miravo_instance")).toBe("__miravo_placeholder__");
+    expect(markerValues.get("serial")).toBe("P-001");
+  });
+});

package/src/commands/start/catalog-le-dt.ts

@@ -0,0 +1,187 @@
+/**
+ * Generates Litmus Edge Digital Twin import JSON from Miravo models.
+ *
+ * The output matches the format produced by LE's `ExportModel` GraphQL mutation
+ * and can be imported directly via `ImportModel` or the LE UI.
+ *
+ * Model export mapping (`buildLeDtJsonFromSchema`):
+ *  - kind: property       → LE static attributes (placeholder values)
+ *  - kind: variable (r/rw)→ LE dynamic attributes via topicExpression devicehub.alias.{device}.<member>
+ *  - LE parameters        → wiring placeholders only ({device})
+ *  - Methods/faults/lifecycle are not exported
+ */
+
+import type { ModelSchema } from "@miravo/shared";
+
+/** Maps Miravo dataType → LE DynamicAttributeType enum values. */
+const LE_DATA_TYPE: Readonly<Record<string, string>> = {
+  Double: "number",
+  Float: "number",
+  Int32: "number",
+  UInt16: "number",
+  UInt32: "number",
+  Boolean: "boolean",
+  String: "string",
+};
+
+const ZERO = "00000000-0000-0000-0000-000000000000";
+const MIRAVO_MARKER_PLACEHOLDER = "__miravo_placeholder__";
+
+interface StaticAttr {
+  readonly id: string;
+  readonly parentId: string;
+  readonly modelId: string;
+  readonly instanceId: string;
+  readonly key: string;
+  readonly value: string;
+  readonly type: number;
+}
+
+function createStaticAttr(modelId: string, key: string, value: string): StaticAttr {
+  return {
+    id: crypto.randomUUID(),
+    parentId: ZERO,
+    modelId,
+    instanceId: ZERO,
+    key,
+    value,
+    type: 0,
+  };
+}
+
+function buildMiravoMarkerPlaceholders(modelId: string): StaticAttr[] {
+  return [
+    createStaticAttr(modelId, "miravo_managed", "false"),
+    createStaticAttr(modelId, "miravo_template", MIRAVO_MARKER_PLACEHOLDER),
+    createStaticAttr(modelId, "miravo_model", MIRAVO_MARKER_PLACEHOLDER),
+    createStaticAttr(modelId, "miravo_instance", MIRAVO_MARKER_PLACEHOLDER),
+    createStaticAttr(modelId, "uns_path", MIRAVO_MARKER_PLACEHOLDER),
+  ];
+}
+
+export function buildLeDtJsonFromSchema(schema: ModelSchema): string {
+  const modelId = crypto.randomUUID();
+
+  // Static attributes: Miravo marker placeholders + property members.
+  // LE materializes instance-owned static attrs from model attrs present at
+  // instance creation time, so these placeholders must exist on the model.
+  const staticAttributes = [
+    ...buildMiravoMarkerPlaceholders(modelId),
+    ...Object.entries(schema.members)
+      .filter(([, m]) => m.kind === "property")
+      .map(([key, m]) =>
+        createStaticAttr(modelId, key, m.default != null ? String(m.default) : "<>"),
+      ),
+  ];
+
+  // Dynamic attributes: readable variable members
+  const dynamicAttributes = Object.entries(schema.members)
+    .filter(([, m]) => m.kind === "variable")
+    .map(([name, m]) => ({
+      id: crypto.randomUUID(),
+      modelId,
+      parentId: ZERO,
+      instanceId: ZERO,
+      topic: "",
+      name,
+      unit: m.unit ?? "",
+      dataType: LE_DATA_TYPE[m.dataType] ?? "number",
+      schemaId: null,
+      skipParentKey: false,
+      topicExpression: `devicehub.alias.{device}.${name}`,
+    }));
+
+  // Hierarchy: "info" folder → static attrs, "measurements" folder → dynamic attrs
+  const hierarchyNodes = buildHierarchy(modelId, staticAttributes, dynamicAttributes);
+
+  return JSON.stringify(
+    [
+      {
+        id: modelId,
+        assets: "ASSET",
+        name: schema.name.toUpperCase(),
+        description: schema.description ?? "",
+        image: null,
+        dynamicAttributes,
+        staticAttributes,
+        hierarchyNodes,
+        transformationBackup: null,
+        parameters: [{ name: "device", value: "miravo" }],
+        isUNS: false,
+        connectorName: "",
+        version: 0,
+      },
+    ],
+    null,
+    2,
+  );
+}
+
+function buildHierarchy(
+  modelId: string,
+  staticAttrs: ReadonlyArray<{ id: string; key: string }>,
+  dynamicAttrs: ReadonlyArray<{ id: string; name: string }>,
+): Array<Record<string, unknown>> {
+  const nodes: Array<Record<string, unknown>> = [];
+  let rootPos = 0;
+
+  if (staticAttrs.length > 0) {
+    const folderId = crypto.randomUUID();
+    nodes.push(hFolder(folderId, modelId, rootPos++, "info"));
+    let pos = 0;
+    for (const a of staticAttrs) {
+      nodes.push(hLeaf(modelId, pos++, folderId, a.key, a.id, "static"));
+    }
+  }
+
+  if (dynamicAttrs.length > 0) {
+    const folderId = crypto.randomUUID();
+    nodes.push(hFolder(folderId, modelId, rootPos, "measurements"));
+    let pos = 0;
+    for (const a of dynamicAttrs) {
+      nodes.push(hLeaf(modelId, pos++, folderId, a.name, a.id, "dynamic"));
+    }
+  }
+
+  return nodes;
+}
+
+function hFolder(
+  id: string,
+  modelId: string,
+  position: number,
+  name: string,
+): Record<string, unknown> {
+  return {
+    id,
+    modelId,
+    position,
+    parentId: null,
+    name,
+    isFolder: true,
+    attributeId: null,
+    attributeType: null,
+    nodeType: "folder",
+  };
+}
+
+function hLeaf(
+  modelId: string,
+  position: number,
+  parentId: string,
+  name: string,
+  attributeId: string,
+  attributeType: string,
+): Record<string, unknown> {
+  return {
+    id: crypto.randomUUID(),
+    modelId,
+    position,
+    parentId,
+    name,
+    isFolder: false,
+    attributeId,
+    attributeType,
+    nodeType: "attribute",
+  };
+}

package/src/commands/start/catalog-model-schema.ts

@@ -0,0 +1,89 @@
+/**
+ * Builds a ModelSchema from raw YAML without the engine runtime.
+ * Used by the catalog endpoints to serve model details for models
+ * that may not be loaded into the current simulation.
+ */
+
+import type { ModelSchema } from "@miravo/shared";
+import { TwinModelSchema } from "@miravo/shared";
+import { parse as parseYAML } from "yaml";
+
+/**
+ * Parse a .twin.yaml file and return a ModelSchema.
+ * Mirrors the logic in engine-introspection.ts getModelSchema()
+ * but operates on the raw parsed YAML instead of runtime objects.
+ */
+export async function buildModelSchemaFromYaml(modelPath: string): Promise<ModelSchema> {
+  const text = await Bun.file(modelPath).text();
+  const raw = TwinModelSchema.parse(parseYAML(text));
+
+  const parameters: Record<
+    string,
+    { type: string; default: number | string | boolean; unit?: string }
+  > = {};
+  if (raw.parameters) {
+    for (const [name, def] of Object.entries(raw.parameters)) {
+      parameters[name] = {
+        type: def.type,
+        default: def.default,
+        ...(def.unit ? { unit: def.unit } : {}),
+      };
+    }
+  }
+
+  const members: Record<string, ModelSchema["members"][string]> = {};
+  for (const [name, def] of Object.entries(raw.members)) {
+    const rawDefault = def.default;
+    members[name] = {
+      kind: def.kind,
+      dataType: def.data_type,
+      access: def.access,
+      unit: def.unit ?? null,
+      euRange: "eu_range" in def ? (def.eu_range ?? null) : null,
+      default:
+        typeof rawDefault === "number" ||
+        typeof rawDefault === "string" ||
+        typeof rawDefault === "boolean"
+          ? rawDefault
+          : null,
+    };
+  }
+
+  const methods: Record<string, ModelSchema["methods"][string]> = {};
+  if (raw.methods) {
+    for (const [name, def] of Object.entries(raw.methods)) {
+      methods[name] = {
+        description: def.description ?? null,
+        inputArguments: def.input_arguments
+          ? Object.entries(def.input_arguments).map(([argName, arg]) => ({
+              name: argName,
+              dataType: arg.data_type,
+              description: arg.description ?? null,
+            }))
+          : [],
+        outputArguments: def.output_arguments
+          ? Object.entries(def.output_arguments).map(([argName, arg]) => ({
+              name: argName,
+              dataType: arg.data_type,
+              description: arg.description ?? null,
+            }))
+          : [],
+      };
+    }
+  }
+
+  return {
+    name: raw.model.name,
+    description: raw.model.description ?? null,
+    parameters,
+    members,
+    methods,
+    faults: raw.faults?.map((f) => f.name) ?? [],
+    lifecycle: raw.lifecycle
+      ? {
+          stages: raw.lifecycle.stages.map((s) => s.name),
+          totalHours: raw.lifecycle.stages.reduce((sum, s) => sum + s.duration_hours[1], 0),
+        }
+      : null,
+  };
+}

package/src/commands/start/catalog-template-detail.ts

@@ -0,0 +1,54 @@
+/**
+ * Builds a CatalogTemplateDetail from raw YAML.
+ * Used by the catalog endpoint to serve template topology
+ * for the inspect side sheet.
+ */
+
+import type { CatalogTemplate, CatalogTemplateDetail } from "@miravo/shared";
+import { MiravoTemplateSchema } from "@miravo/shared";
+import { parse as parseYAML } from "yaml";
+
+export async function buildTemplateDetail(
+  templatePath: string,
+  base: CatalogTemplate,
+): Promise<CatalogTemplateDetail> {
+  const text = await Bun.file(templatePath).text();
+  const raw = MiravoTemplateSchema.parse(parseYAML(text));
+
+  const topology = raw.areas.map((area) => ({
+    name: area.name,
+    ...(area.protocol_scope ? { protocol_scope: area.protocol_scope } : {}),
+    lines: area.lines.map((line) => ({
+      name: line.name,
+      ...(line.protocol_scope ? { protocol_scope: line.protocol_scope } : {}),
+      twins: line.twins.map((twin) => ({
+        model: twin.model,
+        count: twin.count,
+        variation: twin.variation,
+        ...(twin.parameters ? { parameters: twin.parameters } : {}),
+        ...(twin.protocol_scope ? { protocol_scope: twin.protocol_scope } : {}),
+      })),
+    })),
+  }));
+
+  // Extract namespace (ISA-95 or flat)
+  const namespace = raw.namespace
+    ? "enterprise" in raw.namespace
+      ? { enterprise: raw.namespace.enterprise, site: raw.namespace.site }
+      : { prefix: raw.namespace.prefix }
+    : undefined;
+
+  return {
+    ...base,
+    topology,
+    ...(namespace ? { namespace } : {}),
+    ...(raw.settings
+      ? {
+          settings: {
+            tickIntervalMs: raw.settings.tick_interval_ms,
+            timeMultiplier: raw.settings.time_multiplier,
+          },
+        }
+      : {}),
+  };
+}