miravo 0.6.0 → 0.6.1

package/src/lib/le/le-static-planner.ts

@@ -1,442 +0,0 @@
-/**
- * Builds desired state for LE apply from a local template + model catalog.
- */
-
-import { resolve } from "node:path";
-import type { ContentCatalog } from "@miravo/core";
-import { deriveInstancePrefix } from "@miravo/core";
-import { dataTypeToModbus } from "@miravo/modbus";
-import type { MiravoTemplate, ProtocolName, TwinModel } from "@miravo/shared";
-import {
-  MiravoError,
-  MiravoTemplateSchema,
-  resolveProtocolScope,
-  TWIN_FILE_EXTENSION,
-  TwinModelSchema,
-} from "@miravo/shared";
-import { parse as parseYAML } from "yaml";
-import { buildLeDtJsonFromSchema } from "../../commands/start/catalog-le-dt.ts";
-import { buildUNSBasePath, collectReferencedModels } from "../template-utils.ts";
-import type {
-  ApplyDesiredState,
-  DesiredDevice,
-  DesiredInstance,
-  DesiredModel,
-  DesiredTag,
-} from "./le-apply.ts";
-import { extractTemplateId } from "./le-cli-helpers.ts";
-import { buildLeDeviceHubDeviceProperties } from "./le-devicehub-properties.ts";
-import { resolveProtocolPort } from "./le-endpoint.ts";
-import { toModelSchema } from "./le-static-model-schema.ts";
-import { MODBUS_VALUE_TYPE, OPCUA_VALUE_TYPE } from "./le-value-types.ts";
-
-interface StaticPlannerFilters {
-  readonly area?: string | undefined;
-  readonly line?: string | undefined;
-  readonly instance?: string | undefined;
-}
-
-interface BuildStaticDesiredStateInput {
-  readonly templatePath: string;
-  readonly catalog: ContentCatalog;
-  readonly sourceHostname: string;
-  readonly protocol?: ProtocolName | undefined;
-  readonly filters?: StaticPlannerFilters | undefined;
-  readonly onDefaultProtocol?: ((protocol: ProtocolName) => void) | undefined;
-}
-
-interface StaticPlannerResult {
-  readonly templateId: string;
-  readonly desired: ApplyDesiredState;
-}
-
-interface PlannedInstance {
-  readonly instanceId: string;
-  readonly modelName: string;
-  readonly protocol: ProtocolName;
-  readonly browsePath: string;
-  readonly areaName: string;
-  readonly lineName: string;
-}
-
-interface ProtocolPortConfig {
-  readonly mqtt?: { readonly port?: number };
-  readonly opcua?: { readonly port?: number };
-  readonly modbus?: { readonly port?: number };
-}
-
-export async function buildDesiredStateFromTemplate(
-  input: BuildStaticDesiredStateInput,
-): Promise<StaticPlannerResult> {
-  if (!input.sourceHostname.trim()) {
-    throw new MiravoError(
-      "sourceHostname must not be empty.",
-      "Provide a valid hostname or IP address for the source server.",
-    );
-  }
-
-  const template = await loadTemplate(input.templatePath);
-  const modelsByName = await loadReferencedModels(template, input.templatePath, input.catalog);
-
-  const plannedInstances: PlannedInstance[] = [];
-  const modelCounters = new Map<string, number>();
-  const modbusAddressByMember = new Map<string, number>();
-  let nextModbusAddress = 0;
-
-  for (const area of template.areas) {
-    for (const line of area.lines) {
-      for (const twin of line.twins) {
-        const protocol = resolveSingleProtocol(
-          area.name,
-          line.name,
-          twin.model,
-          { template, area, line, twin },
-          input.protocol,
-          input.onDefaultProtocol,
-        );
-
-        const model = modelsByName.get(twin.model);
-        if (!model) {
-          throw new MiravoError(
-            `Model "${twin.model}" was not loaded for static LE planning.`,
-            "Ensure the template references valid model files and retry.",
-          );
-        }
-
-        for (let index = 0; index < twin.count; index++) {
-          const counter = (modelCounters.get(twin.model) ?? 0) + 1;
-          modelCounters.set(twin.model, counter);
-
-          const instanceId = `${deriveInstancePrefix(twin.model)}-${String(counter).padStart(3, "0")}`;
-          const browsePath = `${buildUNSBasePath(template, area.name, line.name)}/${instanceId}`;
-
-          plannedInstances.push({
-            instanceId,
-            modelName: twin.model,
-            protocol,
-            browsePath,
-            areaName: area.name,
-            lineName: line.name,
-          });
-
-          if (protocol === "modbus") {
-            const modbusAddresses = allocateModbusAddresses(model, nextModbusAddress);
-            for (const [memberName, address] of modbusAddresses.addressByMember) {
-              modbusAddressByMember.set(`${instanceId}/${memberName}`, address);
-            }
-            nextModbusAddress = modbusAddresses.nextAddress;
-          }
-        }
-      }
-    }
-  }
-
-  const devices: DesiredDevice[] = [];
-  const instances: DesiredInstance[] = [];
-  const selectedModels = new Set<string>();
-  const protocolPortConfig = buildProtocolPortConfig(template);
-
-  for (const instance of plannedInstances) {
-    if (!matchesFilters(instance, input.filters)) continue;
-
-    const model = modelsByName.get(instance.modelName);
-    if (!model) continue;
-
-    selectedModels.add(instance.modelName);
-
-    const endpointPort = resolveProtocolPort(instance.protocol, protocolPortConfig);
-
-    devices.push({
-      instanceId: instance.instanceId,
-      modelName: instance.modelName,
-      protocol: instance.protocol,
-      deviceName: instance.instanceId,
-      browsePath: instance.browsePath,
-      endpoint: {
-        host: input.sourceHostname,
-        port: endpointPort,
-      },
-      properties: buildLeDeviceHubDeviceProperties(
-        instance.protocol,
-        input.sourceHostname,
-        endpointPort,
-      ),
-      tags: buildTagsForInstance({
-        instance,
-        model,
-        modbusAddressByMember,
-      }),
-    });
-
-    instances.push({
-      instanceId: instance.instanceId,
-      modelName: instance.modelName,
-      dtInstanceName: instance.instanceId,
-      dtModelName: instance.modelName.toUpperCase(),
-      boundDeviceName: instance.instanceId,
-      browsePath: instance.browsePath,
-    });
-  }
-
-  const models: DesiredModel[] = [];
-  for (const modelName of selectedModels) {
-    const model = modelsByName.get(modelName);
-    if (!model) continue;
-
-    models.push({
-      name: modelName.toUpperCase(),
-      leDtJson: JSON.parse(buildLeDtJsonFromSchema(toModelSchema(model))) as unknown,
-    });
-  }
-
-  return {
-    templateId: extractTemplateId(input.templatePath),
-    desired: {
-      devices,
-      models,
-      instances,
-    },
-  };
-}
-
-function matchesFilters(
-  instance: PlannedInstance,
-  filters?: StaticPlannerFilters | undefined,
-): boolean {
-  if (!filters) return true;
-  if (filters.area && instance.areaName !== filters.area) return false;
-  if (filters.line && instance.lineName !== filters.line) return false;
-  if (filters.instance && instance.instanceId !== filters.instance) return false;
-  return true;
-}
-
-function resolveSingleProtocol(
-  areaName: string,
-  lineName: string,
-  modelName: string,
-  ctx: Parameters<typeof resolveProtocolScope>[0],
-  cliProtocol?: ProtocolName | undefined,
-  onDefaultProtocol?: ((protocol: ProtocolName) => void) | undefined,
-): ProtocolName {
-  const scope = resolveProtocolScope(ctx);
-
-  // CLI --protocol override or default when template has no protocol config
-  if (scope.length === 0) {
-    const resolved = cliProtocol ?? "opcua";
-    if (!cliProtocol) onDefaultProtocol?.(resolved);
-    return resolved;
-  }
-
-  // CLI --protocol narrows multi-protocol scope to the requested one
-  if (scope.length > 1) {
-    if (cliProtocol) {
-      if (scope.includes(cliProtocol)) return cliProtocol;
-      throw new MiravoError(
-        `--protocol ${cliProtocol} is not in scope (${scope.join(", ")}) for model "${modelName}" at ${areaName}/${lineName}.`,
-        `Choose one of: ${scope.join(", ")}.`,
-      );
-    }
-    throw new MiravoError(
-      `Instance scope for model "${modelName}" at ${areaName}/${lineName} resolved to multiple protocols: ${scope.join(", ")}.`,
-      "Provide --protocol to select one, or set protocol_scope to exactly one protocol.",
-    );
-  }
-
-  const protocol = scope[0];
-  if (!protocol) {
-    throw new MiravoError(
-      `Failed to resolve protocol for model "${modelName}" at ${areaName}/${lineName}.`,
-      "Provide --protocol <mqtt|opcua|modbus>.",
-    );
-  }
-
-  return protocol;
-}
-
-function buildProtocolPortConfig(template: MiravoTemplate): ProtocolPortConfig {
-  const config: {
-    mqtt?: { port?: number };
-    opcua?: { port?: number };
-    modbus?: { port?: number };
-  } = {};
-
-  const protocols = template.protocols;
-  if (!protocols) return config;
-
-  if (protocols.mqtt !== undefined) {
-    config.mqtt = protocols.mqtt.port !== undefined ? { port: protocols.mqtt.port } : {};
-  }
-  if (protocols.opcua !== undefined) {
-    config.opcua = protocols.opcua.port !== undefined ? { port: protocols.opcua.port } : {};
-  }
-  if (protocols.modbus !== undefined) {
-    config.modbus = protocols.modbus.port !== undefined ? { port: protocols.modbus.port } : {};
-  }
-
-  return config;
-}
-
-function buildTagsForInstance(input: {
-  instance: PlannedInstance;
-  model: TwinModel;
-  modbusAddressByMember: ReadonlyMap<string, number>;
-}): readonly DesiredTag[] {
-  const memberEntries = Object.entries(input.model.members);
-
-  switch (input.instance.protocol) {
-    case "opcua":
-      return memberEntries.map(([memberName, memberDef]) => ({
-        name: `ns=1;s=${input.instance.browsePath}/${memberName}`,
-        tagName: memberName,
-        valueType: OPCUA_VALUE_TYPE[memberDef.data_type] ?? "string",
-        properties: [],
-        unsPath: `${input.instance.browsePath}/${memberName}`,
-        access: memberDef.access,
-        unit: memberDef.unit,
-        euRange: "eu_range" in memberDef ? memberDef.eu_range : undefined,
-      }));
-
-    case "mqtt":
-      return memberEntries.map(([memberName, memberDef]) => ({
-        name: `${input.instance.browsePath}/${memberName}`,
-        tagName: memberName,
-        valueType: "string",
-        properties: [],
-        unsPath: `${input.instance.browsePath}/${memberName}`,
-        access: memberDef.access,
-        unit: memberDef.unit,
-        euRange: "eu_range" in memberDef ? memberDef.eu_range : undefined,
-      }));
-
-    case "modbus": {
-      const tags: DesiredTag[] = [];
-      for (const [memberName, memberDef] of memberEntries) {
-        const typeInfo = dataTypeToModbus(memberDef.data_type);
-        if (!typeInfo) continue;
-
-        const addressKey = `${input.instance.instanceId}/${memberName}`;
-        const address = input.modbusAddressByMember.get(addressKey);
-        if (address === undefined) {
-          throw new MiravoError(
-            `Missing planned Modbus address for "${addressKey}".`,
-            "Re-run LE apply; if this persists, inspect model member data types.",
-          );
-        }
-
-        tags.push({
-          name: "H",
-          tagName: memberName,
-          valueType: MODBUS_VALUE_TYPE[typeInfo.encoding] ?? "float32",
-          properties: [
-            { Key: "address", Value: String(address) },
-            { Key: "count", Value: "1" },
-            { Key: "polling_interval", Value: "1.0" },
-            { Key: "endianness", Value: "AB CD" },
-          ],
-          unsPath: `${input.instance.browsePath}/${memberName}`,
-          access: memberDef.access,
-          unit: memberDef.unit ?? undefined,
-          euRange: "eu_range" in memberDef ? (memberDef.eu_range ?? undefined) : undefined,
-        });
-      }
-
-      return tags;
-    }
-
-    default: {
-      const _never: never = input.instance.protocol;
-      throw new Error(`Unknown protocol: ${_never}`);
-    }
-  }
-}
-
-function allocateModbusAddresses(
-  model: TwinModel,
-  startAddress: number,
-): {
-  readonly addressByMember: ReadonlyMap<string, number>;
-  readonly nextAddress: number;
-} {
-  const addressByMember = new Map<string, number>();
-  let nextAddress = startAddress;
-
-  for (const [memberName, memberDef] of Object.entries(model.members)) {
-    const typeInfo = dataTypeToModbus(memberDef.data_type);
-    if (!typeInfo) continue;
-
-    addressByMember.set(memberName, nextAddress);
-    nextAddress += typeInfo.registerCount;
-  }
-
-  return { addressByMember, nextAddress };
-}
-
-async function loadTemplate(templatePath: string): Promise<MiravoTemplate> {
-  try {
-    const text = await Bun.file(templatePath).text();
-    return MiravoTemplateSchema.parse(parseYAML(text));
-  } catch (error) {
-    throw new MiravoError(
-      `Failed to load template "${templatePath}" for static LE planning.`,
-      error instanceof Error ? error.message : "Ensure the template YAML is valid.",
-    );
-  }
-}
-
-async function loadReferencedModels(
-  template: MiravoTemplate,
-  templatePath: string,
-  catalog: ContentCatalog,
-): Promise<ReadonlyMap<string, TwinModel>> {
-  const modelsByName = new Map<string, TwinModel>();
-
-  if (template.models) {
-    for (const model of template.models) {
-      modelsByName.set(model.model.name, model);
-    }
-  }
-
-  const referencedModelNames = collectReferencedModels(template);
-
-  for (const modelName of referencedModelNames) {
-    if (modelsByName.has(modelName)) continue;
-
-    const modelPath = await resolveModelPath(catalog, templatePath, modelName);
-    const model = await loadTwinModelFromPath(modelName, modelPath);
-    modelsByName.set(modelName, model);
-  }
-
-  return modelsByName;
-}
-
-async function resolveModelPath(
-  catalog: ContentCatalog,
-  templatePath: string,
-  modelName: string,
-): Promise<string> {
-  const searchPaths = catalog.getTemplateValidationSearchPaths(templatePath);
-
-  for (const dir of searchPaths) {
-    const candidate = resolve(dir, `${modelName}${TWIN_FILE_EXTENSION}`);
-    if (await Bun.file(candidate).exists()) {
-      return candidate;
-    }
-  }
-
-  throw new MiravoError(
-    `Model "${modelName}" not found for template "${templatePath}".`,
-    `Add "${modelName}${TWIN_FILE_EXTENSION}" to the template directory or one of: ${searchPaths.join(", ")}.`,
-  );
-}
-
-async function loadTwinModelFromPath(modelName: string, modelPath: string): Promise<TwinModel> {
-  try {
-    const text = await Bun.file(modelPath).text();
-    return TwinModelSchema.parse(parseYAML(text));
-  } catch (error) {
-    throw new MiravoError(
-      `Failed to load model "${modelName}" from "${modelPath}".`,
-      error instanceof Error ? error.message : "Ensure the model YAML is valid.",
-    );
-  }
-}