miravo 0.4.0 → 0.6.0

package/src/commands/export.ts

@@ -0,0 +1,404 @@
+import type { ProtocolName } from "@miravo/shared";
+import { CONTROL_CMD_TIMEOUT_MS } from "@miravo/shared";
+import type { Command } from "commander";
+import { getLeDtJson, getManifest, resolveAdminUrl } from "../lib/admin-client.ts";
+import { LE_DRIVER_NAMES } from "../lib/le/le-drivers.ts";
+import { buildDesiredStateFromTemplate } from "../lib/le/le-static-planner.ts";
+import { buildLeExport } from "../lib/le/le-template-exporter.ts";
+import { MODBUS_VALUE_TYPE, OPCUA_VALUE_TYPE } from "../lib/le/le-value-types.ts";
+import { parseTimeoutSeconds } from "../lib/parse.ts";
+import { createCatalog, resolveTemplateIdentifier } from "../lib/template-locator.ts";
+import { handleCommandError, writeOutput } from "../logger.ts";
+
+const VALID_PROTOCOLS = ["opcua", "modbus", "mqtt"] as const;
+
+/** LE DeviceHub CSV header — matches real LE export format. */
+const LE_CSV_HEADER =
+  "deviceId,deviceName,driverName,name,tagName,description,valueType,registerId,publishCoV,tagFormula,metaData,Retain,Qos,address,count,pollingInterval,endianness";
+
+// ---------------------------------------------------------------------------
+// Command
+// ---------------------------------------------------------------------------
+
+interface ExportLeTagsOptions {
+  readonly device: string;
+  readonly protocol: string;
+  readonly instance?: string;
+  readonly output?: string;
+  readonly adminUrl?: string;
+  readonly timeout?: number;
+}
+
+export function registerExportCommand(program: Command): void {
+  const exportCmd = program
+    .command("export")
+    .description("Export simulation data in platform-specific formats");
+
+  // -------------------------------------------------------------------------
+  // miravo export le-template — offline full LE template (JSON + tags CSV)
+  // -------------------------------------------------------------------------
+
+  interface ExportLeOptions {
+    readonly template: string;
+    readonly host: string;
+    readonly protocol?: string;
+    readonly output?: string;
+    readonly modelsDir?: string;
+  }
+
+  exportCmd
+    .command("le-template")
+    .description(
+      "Export a full Litmus Edge template (devices + DT) and tags CSV — no running instance needed",
+    )
+    .requiredOption("-t, --template <id>", "Template ID, name, or path (required)")
+    .option("--host <hostname>", "Source hostname embedded in device endpoints", "localhost")
+    .option("--protocol <name>", "Protocol override: opcua, modbus, or mqtt")
+    .option("-o, --output <prefix>", "Output file prefix (default: <template-id>)")
+    .option("--models-dir <path>", "Extra directory to search for .twin.yaml model files")
+    .addHelpText(
+      "after",
+      `
+Examples:
+  $ miravo export le-template -t smart-factory
+  $ miravo export le-template -t smart-factory --host 192.168.1.100 --protocol opcua
+  $ miravo export le-template -t ./my.miravo.yaml --models-dir ./models
+  $ miravo export le-template -t smart-factory -o ./out/sf`,
+    )
+    .action(async (options: ExportLeOptions) => {
+      try {
+        if (
+          options.protocol &&
+          !VALID_PROTOCOLS.includes(options.protocol as (typeof VALID_PROTOCOLS)[number])
+        ) {
+          writeOutput(`Unknown protocol "${options.protocol}". Valid options: opcua, modbus, mqtt`);
+          process.exitCode = 1;
+          return;
+        }
+
+        const catalog = options.modelsDir
+          ? createCatalog({ extraModelsDir: options.modelsDir })
+          : createCatalog();
+        const templatePath = await resolveTemplateIdentifier(options.template, catalog);
+        const { templateId, desired } = await buildDesiredStateFromTemplate({
+          templatePath,
+          catalog,
+          sourceHostname: options.host,
+          protocol: options.protocol as ProtocolName | undefined,
+        });
+
+        const { templateJson, tagsCSV } = buildLeExport(desired, templateId);
+
+        const prefix = options.output ?? templateId;
+        const jsonPath = `${prefix}.le-template.json`;
+        const csvPath = `${prefix}-tags.csv`;
+
+        await Bun.write(jsonPath, templateJson);
+        await Bun.write(csvPath, tagsCSV);
+
+        writeOutput(`LE template → ${jsonPath}`);
+        writeOutput(`Tags CSV   → ${csvPath}`);
+      } catch (error) {
+        handleCommandError(error);
+      }
+    });
+
+  exportCmd
+    .command("le-tags")
+    .description("Export tags as Litmus Edge DeviceHub CSV for bulk import")
+    .requiredOption("--device <name>", "LE device name (required)")
+    .requiredOption("--protocol <name>", "Protocol to export: opcua, modbus, or mqtt (required)")
+    .option("--instance <id>", "Export only tags for a specific instance")
+    .option("-o, --output <file>", "Write CSV to file instead of stdout")
+    .option("--admin-url <url>", "Admin API URL (env: MIRAVO_ADMIN_URL)")
+    .option("--timeout <seconds>", "Timeout in seconds (default: 5)", parseTimeoutSeconds)
+    .addHelpText(
+      "after",
+      `
+Examples:
+  $ miravo export le-tags --device DTW-FAB-PLC --protocol opcua
+  $ miravo export le-tags --device DTW-FAB-PLC --protocol modbus --instance pump-001
+  $ miravo export le-tags --device DTW-FAB-PLC --protocol mqtt -o tags.csv`,
+    )
+    .action(async (options: ExportLeTagsOptions) => {
+      try {
+        if (!VALID_PROTOCOLS.includes(options.protocol as (typeof VALID_PROTOCOLS)[number])) {
+          writeOutput(
+            `Unknown protocol "${options.protocol}". Valid options: ${VALID_PROTOCOLS.join(", ")}`,
+          );
+          process.exitCode = 1;
+          return;
+        }
+
+        const adminUrl = resolveAdminUrl(options.adminUrl);
+        const timeoutMs = options.timeout ?? CONTROL_CMD_TIMEOUT_MS;
+        const manifest = await getManifest(adminUrl, timeoutMs);
+
+        const allTags = manifest["tags"] as Array<Record<string, unknown>> | undefined;
+
+        if (!allTags || allTags.length === 0) {
+          writeOutput("No tags found in manifest.");
+          return;
+        }
+
+        // Filter by instance if specified
+        const filteredTags = options.instance
+          ? allTags.filter((s) => s["instance"] === options.instance)
+          : allTags;
+
+        if (filteredTags.length === 0) {
+          writeOutput(
+            options.instance
+              ? `No tags found for instance "${options.instance}".`
+              : "No tags found in manifest.",
+          );
+          return;
+        }
+
+        const protocol = options.protocol;
+        const driverName = LE_DRIVER_NAMES[protocol as keyof typeof LE_DRIVER_NAMES] ?? protocol;
+        const deviceName = options.device;
+
+        const csvRows = [LE_CSV_HEADER];
+        let totalRows = 0;
+
+        for (const tag of filteredTags) {
+          const protocols = tag["protocols"] as Record<string, Record<string, unknown>> | undefined;
+          const memberName = String(tag["member"] ?? "");
+          const browsePath = String(tag["browsePath"] ?? "");
+          const dataType = String(tag["dataType"] ?? "");
+          const unit = typeof tag["unit"] === "string" ? tag["unit"] : undefined;
+          const euRangeRaw = tag["euRange"];
+          const euRange =
+            Array.isArray(euRangeRaw) &&
+            euRangeRaw.length === 2 &&
+            typeof euRangeRaw[0] === "number" &&
+            typeof euRangeRaw[1] === "number"
+              ? ([euRangeRaw[0], euRangeRaw[1]] as [number, number])
+              : undefined;
+          const model = String(tag["model"] ?? "");
+          const instance = String(tag["instance"] ?? "");
+          const access = String(tag["access"] ?? "");
+          const protocolData = protocols?.[protocol];
+          if (!protocolData) continue; // tag not exposed on this protocol (e.g. String on Modbus, property on MQTT)
+
+          csvRows.push(
+            buildRow(protocol, {
+              deviceName,
+              driverName,
+              memberName,
+              browsePath,
+              dataType,
+              protocolData,
+              model,
+              instance,
+              access,
+              ...(unit !== undefined && { unit }),
+              ...(euRange !== undefined && { euRange }),
+            }),
+          );
+          totalRows++;
+        }
+
+        const csv = `${csvRows.join("\n")}\n`;
+
+        if (options.output) {
+          await Bun.write(options.output, csv);
+          writeOutput(`Wrote ${totalRows} tags to ${options.output}`);
+        } else {
+          writeOutput(csv);
+        }
+      } catch (error) {
+        handleCommandError(error);
+      }
+    });
+
+  // -------------------------------------------------------------------------
+  // miravo export le-dt — export a model as Litmus Edge Digital Twin JSON
+  // -------------------------------------------------------------------------
+
+  exportCmd
+    .command("le-dt")
+    .description("Export a model as Litmus Edge Digital Twin JSON for import into LE")
+    .requiredOption("--model <name>", "Model name to export (required)")
+    .option("-o, --output <file>", "Write JSON to file instead of stdout")
+    .option("--admin-url <url>", "Admin API URL (env: MIRAVO_ADMIN_URL)")
+    .option("--timeout <seconds>", "Timeout in seconds (default: 5)", parseTimeoutSeconds)
+    .addHelpText(
+      "after",
+      `
+Examples:
+  $ miravo export le-dt --model centrifugal-pump
+  $ miravo export le-dt --model centrifugal-pump -o pump.le-dt.json`,
+    )
+    .action(
+      async (options: {
+        readonly model: string;
+        readonly output?: string;
+        readonly adminUrl?: string;
+        readonly timeout?: number;
+      }) => {
+        try {
+          const adminUrl = resolveAdminUrl(options.adminUrl);
+          const timeoutMs = options.timeout ?? CONTROL_CMD_TIMEOUT_MS;
+          const leDt = await getLeDtJson(adminUrl, options.model, timeoutMs);
+          const json = JSON.stringify(leDt, null, 2);
+
+          if (options.output) {
+            await Bun.write(options.output, json);
+            writeOutput(`Wrote LE Digital Twin JSON to ${options.output}`);
+          } else {
+            writeOutput(json);
+          }
+        } catch (error) {
+          handleCommandError(error);
+        }
+      },
+    );
+}
+
+// ---------------------------------------------------------------------------
+// Row builder
+// ---------------------------------------------------------------------------
+
+interface RowInput {
+  readonly deviceName: string;
+  readonly driverName: string;
+  readonly memberName: string;
+  readonly browsePath: string;
+  readonly dataType: string;
+  readonly protocolData: Record<string, unknown> | undefined;
+  readonly unit?: string;
+  readonly euRange?: readonly [number, number];
+  readonly model: string;
+  readonly instance: string;
+  readonly access: string;
+}
+
+function buildRow(protocol: string, input: RowInput): string {
+  switch (protocol) {
+    case "mqtt":
+      return buildMqttRow(input);
+    case "opcua":
+      return buildOpcuaRow(input);
+    case "modbus":
+      return buildModbusRow(input);
+    default: {
+      const _exhaustive: never = protocol as never;
+      throw new Error(`Unsupported LE export protocol: "${_exhaustive}"`);
+    }
+  }
+}
+
+function buildMqttRow(input: RowInput): string {
+  const topic =
+    typeof input.protocolData?.["topic"] === "string"
+      ? input.protocolData["topic"]
+      : `${input.browsePath}/${input.memberName}`;
+
+  return [
+    "", // deviceId
+    esc(input.deviceName),
+    esc(input.driverName),
+    esc(topic), // name = MQTT topic
+    esc(input.memberName), // tagName
+    "", // description
+    "string", // valueType — MQTT is always string
+    "", // registerId
+    "false", // publishCoV
+    "", // tagFormula
+    buildMetaData(input), // metaData
+    "Disable", // Retain
+    "0", // Qos
+    "", // address
+    "", // count
+    "", // pollingInterval
+    "", // endianness
+  ].join(",");
+}
+
+function buildOpcuaRow(input: RowInput): string {
+  const nodeId =
+    typeof input.protocolData?.["nodeId"] === "string"
+      ? input.protocolData["nodeId"]
+      : `ns=1;s=${input.browsePath}/${input.memberName}`;
+  const valueType = OPCUA_VALUE_TYPE[input.dataType] ?? "string";
+
+  return [
+    "", // deviceId
+    esc(input.deviceName),
+    esc(input.driverName),
+    esc(nodeId), // name = OPC UA NodeId
+    esc(input.memberName), // tagName
+    "", // description
+    valueType,
+    "", // registerId
+    "false", // publishCoV
+    "", // tagFormula
+    buildMetaData(input), // metaData
+    "", // Retain
+    "", // Qos
+    "", // address
+    "", // count
+    "", // pollingInterval
+    "", // endianness
+  ].join(",");
+}
+
+function buildModbusRow(input: RowInput): string {
+  const registerType = String(input.protocolData?.["registerType"] ?? "");
+  const valueType = MODBUS_VALUE_TYPE[registerType] ?? "float32";
+  const address = input.protocolData?.["address"];
+
+  return [
+    "", // deviceId
+    esc(input.deviceName),
+    esc(input.driverName),
+    "H", // name = Holding register
+    esc(input.memberName), // tagName
+    "", // description
+    valueType,
+    "", // registerId
+    "false", // publishCoV
+    "", // tagFormula
+    buildMetaData(input), // metaData
+    "", // Retain
+    "", // Qos
+    typeof address === "number" ? String(address) : "0", // address
+    "1", // count — always 1 scalar value; LE derives register width from valueType
+    "1.0000000000", // pollingInterval
+    "AB CD", // endianness (big-endian — matches Miravo Modbus)
+  ].join(",");
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Escape a comma-delimited CSV field: quote if it contains delimiters, quotes, or newlines. */
+function esc(value: string): string {
+  if (value.includes(",") || value.includes('"') || value.includes("\n")) {
+    return `"${value.replace(/"/g, '""')}"`;
+  }
+  return value;
+}
+
+/** Build the LE metaData JSON cell from Miravo tag metadata. */
+function buildMetaData(input: RowInput): string {
+  const unsPath = input.browsePath ? `${input.browsePath}/${input.memberName}` : input.memberName;
+
+  const meta: Record<string, unknown> = {
+    uns_path: unsPath,
+    model: input.model,
+    instance: input.instance,
+    access: input.access,
+  };
+
+  if (input.unit != null) meta["unit"] = input.unit;
+  if (input.euRange != null) {
+    meta["eu_range_min"] = String(input.euRange[0]);
+    meta["eu_range_max"] = String(input.euRange[1]);
+  }
+
+  return esc(JSON.stringify(meta));
+}

package/src/commands/fork.ts

@@ -15,7 +15,7 @@ export function registerForkCommand(program: Command): void {
 
   fork
     .command("model <name>")
-    .description("Fork a model to ~/.miravo/registry/local/models/")
+    .description("Copy a built-in model to local registry for customization")
     .option("--force", "Overwrite if already exists in local")
     .addHelpText(
       "after",
@@ -30,7 +30,7 @@ Examples:
 
   fork
     .command("template <idNameOrPath>")
-    .description("Fork a template and its referenced models to ~/.miravo/registry/local/")
+    .description("Copy a template and its referenced models to local registry")
     .option("--force", "Overwrite if already exists in local")
     .option("--models-only", "Only fork referenced models, skip the template itself")
     .addHelpText(

package/src/commands/inject.ts

@@ -21,11 +21,11 @@ interface InjectOptions {
 export function registerInjectCommand(program: Command): void {
   program
     .command("inject [instanceId] [fault]")
-    .description("Trigger or clear a fault on a running instance")
+    .description("Trigger or clear a fault on a running instance (interactive if no args)")
     .option("--clear", "Clear the fault instead of triggering it")
     .option("--json", "Machine-readable JSON output")
     .option("--name <name>", "Target simulation name")
-    .option("--admin-url <url>", "Miravo admin server URL (env: MIRAVO_ADMIN_URL)")
+    .option("--admin-url <url>", "Admin API URL (env: MIRAVO_ADMIN_URL)")
     .option("--timeout <seconds>", "Timeout in seconds (default: 5)", parseTimeoutSeconds)
     .addHelpText(
       "after",

package/src/commands/load.ts

@@ -37,7 +37,7 @@ export function registerLoadCommand(program: Command): void {
       parsePositiveInt,
     )
     .option("--json", "Machine-readable JSON output")
-    .option("--admin-url <url>", "Miravo admin server URL (env: MIRAVO_ADMIN_URL)")
+    .option("--admin-url <url>", "Admin API URL (env: MIRAVO_ADMIN_URL)")
     .option("--timeout <seconds>", "Timeout in seconds (default: 5)", parseTimeoutSeconds)
     .addHelpText(
       "after",

package/src/commands/logs.ts

@@ -126,29 +126,27 @@ async function logsAction(name: string, options: LogsOptions): Promise<void> {
   }
 }
 
-/** Format a WebSocket message for terminal output. Returns null for tick events. */
-export function formatWSEvent(msg: WSMessage): string | null {
-  switch (msg.type) {
+/** Format a WebSocket message for terminal output. Returns null for tick/snapshot events. */
+function formatWSEvent(msg: WSMessage): string | null {
+  if (msg.type !== "runtime:event") return null;
+  const evt = msg.event;
+  switch (evt.kind) {
     case "fault:triggered":
-      return `${colors.red("[fault:triggered]")} ${msg.instanceId} · ${msg.fault}`;
+      return `${colors.red("[fault:triggered]")} ${evt.instanceId} · ${evt.fault}`;
     case "fault:cleared":
-      return `${colors.green("[fault:cleared]")} ${msg.instanceId} · ${msg.fault}`;
+      return `${colors.green("[fault:cleared]")} ${evt.instanceId} · ${evt.fault}`;
     case "lifecycle:changed":
-      return `${colors.blue("[lifecycle:changed]")} ${msg.instanceId} · ${msg.from} → ${msg.to}`;
+      return `${colors.blue("[lifecycle:changed]")} ${evt.instanceId} · ${evt.from} → ${evt.to}`;
     case "instance:created":
-      return `${colors.cyan("[instance:created]")} ${msg.id} · ${msg.assetType}`;
+      return `${colors.cyan("[instance:created]")} ${evt.id} · ${evt.assetType}`;
     case "instance:removed":
-      return `${colors.yellow("[instance:removed]")} ${msg.id}`;
+      return `${colors.yellow("[instance:removed]")} ${evt.id}`;
     case "engine:state":
-      return `${colors.magenta("[engine:state]")} ${msg.from} → ${msg.to}`;
+      return `${colors.magenta("[engine:state]")} ${evt.from} → ${evt.to}`;
     case "adapter:enabled":
-      return `${colors.cyan("[adapter:enabled]")} ${msg.name}`;
+      return `${colors.cyan("[adapter:enabled]")} ${evt.name}`;
     case "adapter:disabled":
-      return `${colors.yellow("[adapter:disabled]")} ${msg.name}`;
-    case "tick":
-    case "snapshot":
-    case "resync-required":
-      return null;
+      return `${colors.yellow("[adapter:disabled]")} ${evt.name}`;
     default:
       return null;
   }

package/src/commands/models.test.ts

@@ -88,7 +88,7 @@ describe("formatModelInspect", () => {
     expect(output).toContain("centrifugal-pump");
     expect(output).toContain("Parameters:");
     expect(output).toContain("rated_rpm");
-    expect(output).toContain("Members (30):");
+    expect(output).toContain("Members (24):");
     expect(output).toContain("Methods (5):");
     expect(output).toContain("availability_state");
     expect(output).toContain("Lifecycle: healthy");

package/src/commands/models.ts

@@ -19,7 +19,7 @@ export function registerModelsCommand(program: Command): void {
   models
     .command("list")
     .description("Discover and list available models")
-    .option("--dir <path>", "Additional directory to search for models")
+    .option("--dir <path>", "Additional directory to search for .twin.yaml models")
     .addHelpText(
       "after",
       `

package/src/commands/pause.ts

@@ -14,9 +14,9 @@ interface PauseResumeOptions {
 export function registerPauseCommand(program: Command): void {
   program
     .command("pause")
-    .description("Pause the running simulation")
+    .description("Pause the running simulation (state is preserved)")
     .option("--json", "Machine-readable JSON output")
-    .option("--admin-url <url>", "Miravo admin server URL (env: MIRAVO_ADMIN_URL)")
+    .option("--admin-url <url>", "Admin API URL (env: MIRAVO_ADMIN_URL)")
     .option("--timeout <seconds>", "Timeout in seconds (default: 5)", parseTimeoutSeconds)
     .addHelpText(
       "after",
@@ -38,7 +38,7 @@ export function registerResumeCommand(program: Command): void {
     .command("resume")
     .description("Resume a paused simulation")
     .option("--json", "Machine-readable JSON output")
-    .option("--admin-url <url>", "Miravo admin server URL (env: MIRAVO_ADMIN_URL)")
+    .option("--admin-url <url>", "Admin API URL (env: MIRAVO_ADMIN_URL)")
     .option("--timeout <seconds>", "Timeout in seconds (default: 5)", parseTimeoutSeconds)
     .addHelpText(
       "after",