miravo 0.1.4 → 0.2.0

package/README.md

@@ -1,8 +1,8 @@
 # Miravo
 
-Digital Twin Engine & Unified Namespace Simulator for Industrial IoT.
+Industrial environment platform. Canonical asset models, multi-protocol output, structured plant topology.
 
-Miravo generates realistic industrial sensor data — correlated signals, lifecycle degradation, cascading faults — and publishes it to a fully structured **Unified Namespace** following the ISA-95 hierarchy. One command gives you thousands of data points that behave like a real plant.
+Miravo simulates industrial assets with realistic physics — correlated signals, lifecycle degradation, cascading faults — and projects them over MQTT and OPC UA from a single canonical asset model. One command gives you a fully structured namespace with typed members that behave like a real plant.
 
 ```
 MiravoWorks/smart-factory
@@ -56,7 +56,7 @@ Connect any MQTT client to `localhost:1883` and subscribe to `#` to see the data
 
 ## Built-In Models
 
-Miravo ships with 8 industrial digital twin models, each with realistic sensor correlations, lifecycle stages, and fault modes:
+Miravo ships with 8 canonical asset models, each with typed members, lifecycle stages, and fault modes:
 
 | Model              | Key Signals                               | Fault Examples                     |
 | ------------------ | ----------------------------------------- | ---------------------------------- |
@@ -87,24 +87,29 @@ miravo start --content-dir ./my-content
 
 Start the simulation engine with an embedded MQTT broker.
 
-| Option                        | Description                                                                   |
-| ----------------------------- | ----------------------------------------------------------------------------- |
-| `--template <id\|name\|path>` | Template to run (env: `MIRAVO_TEMPLATE`)                                      |
-| `--content-dir <path>`        | User content root with `/templates` and `/models` (env: `MIRAVO_CONTENT_DIR`) |
-| `--models-dir <path>`         | Additional `.twin.yaml` model directory                                       |
-| `--speed <multiplier>`        | Time multiplier (default: `1`)                                                |
-| `--seed <number>`             | Deterministic RNG seed                                                        |
-| `--tick <ms>`                 | Tick interval in ms (default: `1000`)                                         |
-| `--port <number>`             | MQTT port (default: `1883`, env: `MIRAVO_MQTT_PORT`)                          |
-| `--mqtt-host <host>`          | MQTT bind host (default: `127.0.0.1`, env: `MIRAVO_MQTT_HOST`)                |
-| `--mqtt-mode <mode>`          | `embedded` or `external` (env: `MIRAVO_MQTT_MODE`)                            |
-| `--mqtt-url <url>`            | External broker URL (env: `MIRAVO_MQTT_URL`)                                  |
-| `--mqtt-username <user>`      | External broker username (env: `MIRAVO_MQTT_USERNAME`)                        |
-| `--mqtt-password <pass>`      | External broker password (env: `MIRAVO_MQTT_PASSWORD`)                        |
-| `--health-host <host>`        | Health server host (default: `0.0.0.0`, env: `MIRAVO_HEALTH_HOST`)            |
-| `--health-port <number>`      | Health server port (default: `8080`, env: `MIRAVO_HEALTH_PORT`)               |
-| `--dry-run`                   | Validate and print summary without starting                                   |
-| `--summary-interval <s>`      | Seconds between periodic summaries (default: `5`)                             |
+| Option                            | Description                                                                   |
+| --------------------------------- | ----------------------------------------------------------------------------- |
+| `-t, --template <id\|name\|path>` | Template to run (env: `MIRAVO_TEMPLATE`)                                      |
+| `-n, --name <name>`               | Simulation name for control topics (env: `MIRAVO_NAME`)                       |
+| `--content-dir <path>`            | User content root with `/templates` and `/models` (env: `MIRAVO_CONTENT_DIR`) |
+| `--models-dir <path>`             | Additional `.twin.yaml` model directory                                       |
+| `-s, --speed <multiplier>`        | Time multiplier (default: `1`)                                                |
+| `--seed <number>`                 | Deterministic RNG seed                                                        |
+| `--tick <ms>`                     | Tick interval in ms (default: `1000`)                                         |
+| `-p, --mqtt-port <number>`        | MQTT port (default: `1883`, env: `MIRAVO_MQTT_PORT`)                          |
+| `--mqtt-host <host>`              | MQTT bind host (default: `127.0.0.1`, env: `MIRAVO_MQTT_HOST`)                |
+| `--mqtt-mode <mode>`              | `embedded` or `external` (env: `MIRAVO_MQTT_MODE`)                            |
+| `--mqtt-url <url>`                | External broker URL (env: `MIRAVO_MQTT_URL`)                                  |
+| `--mqtt-username <user>`          | External broker username (env: `MIRAVO_MQTT_USERNAME`)                        |
+| `--mqtt-password <pass>`          | External broker password (env: `MIRAVO_MQTT_PASSWORD`)                        |
+| `--no-mqtt`                       | Disable MQTT broker                                                           |
+| `--opcua`                         | Enable OPC UA server                                                          |
+| `--opcua-port <number>`           | OPC UA port (default: `4840`, env: `MIRAVO_OPCUA_PORT`)                       |
+| `--opcua-host <host>`             | OPC UA bind host (default: `0.0.0.0`, env: `MIRAVO_OPCUA_HOST`)               |
+| `--admin-host <host>`             | Admin server host (default: `127.0.0.1`, env: `MIRAVO_ADMIN_HOST`)            |
+| `--admin-port <number>`           | Admin server port (default: `8080`, env: `MIRAVO_ADMIN_PORT`)                 |
+| `-d, --dry-run`                   | Validate and print summary without starting                                   |
+| `--summary-interval <s>`          | Seconds between periodic summaries (default: `5`)                             |
 
 ### `miravo templates list`
 
@@ -126,7 +131,7 @@ Show template details or copy it locally.
 
 ### `miravo models list`
 
-List all discovered digital twin models.
+List all discovered canonical asset models.
 
 | Option         | Description                  |
 | -------------- | ---------------------------- |
@@ -134,7 +139,7 @@ List all discovered digital twin models.
 
 ### `miravo models inspect <name>`
 
-Show model details — sensors, lifecycle stages, fault definitions.
+Show model details — typed members, lifecycle stages, fault definitions.
 
 | Option  | Description    |
 | ------- | -------------- |
@@ -142,15 +147,16 @@ Show model details — sensors, lifecycle stages, fault definitions.
 
 ### `miravo status`
 
-Read live state from a running simulation via MQTT control plane.
+Read live state from a running simulation via the admin HTTP server. `--discover` still uses MQTT when enabled.
 
 | Option              | Description                                                 |
 | ------------------- | ----------------------------------------------------------- |
-| `-w, --watch`       | Stay subscribed and re-render on updates                    |
+| `--admin-url <url>` | Admin server URL (env: `MIRAVO_ADMIN_URL`)                  |
+| `-w, --watch`       | Poll and re-render on updates                               |
 | `--instance <id>`   | Show one instance instead of fleet overview                 |
 | `--json`            | Machine-readable JSON output                                |
-| `--template <path>` | Template for broker URL resolution (env: `MIRAVO_TEMPLATE`) |
-| `--timeout <ms>`    | Connection timeout (default: `5000`)                        |
+| `--template <path>` | Template for MQTT discovery only (env: `MIRAVO_TEMPLATE`)   |
+| `--timeout <ms>`    | Request timeout (default: `5000`)                           |
 
 ### `miravo inject [instanceId] [fault]`
 
@@ -159,8 +165,8 @@ Trigger or clear faults on running instances.
 | Option              | Description                                                 |
 | ------------------- | ----------------------------------------------------------- |
 | `--clear`           | Clear fault instead of triggering                           |
-| `--template <path>` | Template for broker URL resolution (env: `MIRAVO_TEMPLATE`) |
-| `--timeout <ms>`    | Command timeout (default: `5000`)                           |
+| `--admin-url <url>` | Admin server URL (env: `MIRAVO_ADMIN_URL`)                  |
+| `--timeout <ms>`    | Request timeout (default: `5000`)                           |
 
 If `instanceId` and `fault` are omitted in a TTY, an interactive picker is shown.
 
@@ -193,13 +199,13 @@ docker run --rm -p 1883:1883 -p 8080:8080 \
   amineamaach/miravo:latest start --template my-template
 ```
 
-Health probes are available at `/healthz` (liveness) and `/readyz` (readiness) on port 8080.
+The admin server exposes `/healthz`, `/readyz`, `/state`, `/metrics`, and `/commands` on port 8080.
 
 ## Links
 
 - [GitHub](https://github.com/amine-amaach/miravo)
-- [Built-in Models & Templates Reference](https://github.com/amine-amaach/miravo/blob/main/docs/builtin-twins-and-templates.md)
-- [Writing Custom Twin Models](https://github.com/amine-amaach/miravo/blob/main/docs/builtin-twins-and-templates.md)
+- [Built-in Models & Templates Reference](https://github.com/amine-amaach/miravo/blob/main/docs/ai/05-builtin-twins-and-templates.md)
+- [Writing Custom Twin Models](https://github.com/amine-amaach/miravo/blob/main/docs/ai/05-builtin-twins-and-templates.md)
 
 ## License
 

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "miravo",
-  "version": "0.1.4",
+  "version": "0.2.0",
   "type": "module",
-  "description": "Digital twin engine for Industrial IoT simulation",
+  "description": "Industrial environment platform with canonical asset models and MQTT + OPC UA protocol adapters",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -31,11 +31,17 @@
   ],
   "dependencies": {
     "@clack/prompts": "^1.1.0",
-    "@miravo/core": "0.1.4",
-    "@miravo/mqtt": "0.1.4",
-    "@miravo/shared": "0.1.4",
+    "@miravo/core": "0.2.0",
+    "@miravo/mqtt": "0.2.0",
+    "@miravo/opcua": "0.2.0",
+    "@miravo/shared": "0.2.0",
     "commander": "^13.0.0",
     "consola": "^3.4.0",
     "mqtt": "^5.15.0"
+  },
+  "devDependencies": {
+    "node-opcua-client": "^2.163.1",
+    "node-opcua-variant": "^2.163.0",
+    "yaml": "^2.8.1"
   }
 }

package/src/__tests__/integration/executable-methods-runner.ts

@@ -0,0 +1,253 @@
+import {
+  createControlPlane,
+  createEngine,
+  loadTemplate,
+  loadTwinModel,
+  resolveModelPath,
+} from "@miravo/core";
+import { MQTTAdapter } from "@miravo/mqtt";
+import { OPCUAAdapter } from "@miravo/opcua";
+import type { MiravoTemplate, TwinModel } from "@miravo/shared";
+import { startAdminServer } from "../../lib/admin-server.ts";
+
+interface RunnerArgs {
+  readonly template: string;
+  readonly modelsDir: string;
+  readonly readyFile: string;
+  readonly rbeEnabled: boolean;
+  readonly rbeDeadband: number;
+}
+
+function parseArgs(argv: readonly string[]): RunnerArgs {
+  const values = new Map<string, string>();
+  for (let index = 0; index < argv.length; index += 2) {
+    const key = argv[index];
+    const value = argv[index + 1];
+    if (!key?.startsWith("--") || value === undefined) {
+      throw new Error(
+        "Invalid smoke runner arguments. Expected --template <path> --models-dir <path> --ready-file <path>.",
+      );
+    }
+    values.set(key.slice(2), value);
+  }
+
+  const template = values.get("template");
+  const modelsDir = values.get("models-dir");
+  const readyFile = values.get("ready-file");
+  if (!template || !modelsDir || !readyFile) {
+    throw new Error(
+      "Missing smoke runner arguments. Provide --template, --models-dir, and --ready-file.",
+    );
+  }
+
+  const rbeEnabled = values.get("rbe-enabled") === "true";
+  const rbeDeadband = Number.parseFloat(values.get("rbe-deadband") ?? "0");
+
+  return { template, modelsDir, readyFile, rbeEnabled, rbeDeadband };
+}
+
+function resolveSimulationName(template: MiravoTemplate): string {
+  const namespace = template.namespace;
+  if (!namespace) {
+    throw new Error("Smoke template is missing namespace metadata.");
+  }
+  if ("enterprise" in namespace) {
+    return `${namespace.enterprise}-${namespace.site}`.toLowerCase();
+  }
+  return namespace.prefix.toLowerCase();
+}
+
+function buildUNSBasePath(template: MiravoTemplate, areaName: string, lineName: string): string {
+  const segments: string[] = [];
+  const namespace = template.namespace;
+  if (namespace !== undefined) {
+    if ("enterprise" in namespace) {
+      segments.push(namespace.enterprise, namespace.site);
+    } else {
+      segments.push(namespace.prefix);
+    }
+  }
+  segments.push(areaName, lineName);
+  return segments.join("/");
+}
+
+async function loadModels(
+  template: MiravoTemplate,
+  modelsDir: string,
+): Promise<Map<string, TwinModel>> {
+  const models = new Map<string, TwinModel>();
+  if (template.models) {
+    for (const inlineModel of template.models) {
+      models.set(inlineModel.model.name, inlineModel);
+    }
+  }
+
+  const referencedModelNames = new Set<string>();
+  for (const area of template.areas) {
+    for (const line of area.lines) {
+      for (const twin of line.twins) {
+        referencedModelNames.add(twin.model);
+      }
+    }
+  }
+
+  for (const modelName of referencedModelNames) {
+    if (models.has(modelName)) {
+      continue;
+    }
+    const modelPath = await resolveModelPath(modelName, [modelsDir]);
+    const model = await loadTwinModel(modelPath);
+    models.set(modelName, model);
+  }
+
+  return models;
+}
+
+async function main(): Promise<void> {
+  const args = parseArgs(process.argv.slice(2));
+  const template = await loadTemplate(args.template);
+  const models = await loadModels(template, args.modelsDir);
+  const simulationName = resolveSimulationName(template);
+  const tickIntervalMs = template.settings?.tick_interval_ms ?? 100;
+  const timeMultiplier = template.settings?.time_multiplier ?? 1;
+  const seed = template.settings?.seed ?? 42;
+
+  const engine = createEngine({
+    simulationName,
+    seed,
+    tickIntervalMs,
+    timeMultiplier,
+    templateMetadata: {
+      name: template.name,
+      path: args.template,
+    },
+  });
+
+  for (const [, model] of models) {
+    engine.runtime.registerModel(model);
+  }
+
+  for (const area of template.areas) {
+    for (const line of area.lines) {
+      for (const twin of line.twins) {
+        engine.runtime.spawn(twin.model, twin.count, {
+          variation: twin.variation,
+          unsBasePath: buildUNSBasePath(template, area.name, line.name),
+          ...(twin.parameters !== undefined ? { parameterOverrides: twin.parameters } : {}),
+        });
+      }
+    }
+  }
+
+  const mqttAdapter = new MQTTAdapter(engine.bus);
+  await mqttAdapter.start({
+    name: "mqtt",
+    enabled: true,
+    embedded: true,
+    host: "127.0.0.1",
+    port: 0,
+    retain: false,
+    simulationName,
+    ...(args.rbeEnabled ? { rbe: { enabled: true, deadband: args.rbeDeadband } } : {}),
+  });
+  engine.registerAdapter(mqttAdapter);
+
+  const opcuaAdapter = new OPCUAAdapter(engine.bus, engine);
+  await opcuaAdapter.start({
+    name: "opcua",
+    enabled: true,
+    host: "127.0.0.1",
+    port: 0,
+    security: "none",
+    simulationName,
+  });
+  engine.registerAdapter(opcuaAdapter);
+
+  const transport = mqttAdapter.getControlTransport();
+  if (!transport) {
+    throw new Error("Smoke runtime failed to resolve MQTT control transport.");
+  }
+
+  const controlPlane = createControlPlane({
+    simulationName,
+    engine,
+    transport,
+    bus: engine.bus,
+  });
+  controlPlane.start();
+
+  let lastTickProgressAt = performance.now();
+  const onTickProgress = () => {
+    lastTickProgressAt = performance.now();
+  };
+  engine.bus.on("tick:complete", onTickProgress);
+
+  const adminServer = startAdminServer({
+    engine,
+    host: "127.0.0.1",
+    port: 0,
+    tickIntervalMs,
+    mqttEnabled: true,
+    isMqttConnected: () => mqttAdapter.getMetrics().connected,
+    opcuaEnabled: true,
+    isOpcuaConnected: () => opcuaAdapter.getMetrics().connected,
+    getLastTickProgressAt: () => lastTickProgressAt,
+  });
+
+  engine.start();
+
+  await Bun.sleep(Math.max(250, tickIntervalMs * 3));
+
+  const [instanceId, instance] = [...engine.runtime.getInstances()][0] ?? [];
+  if (!instanceId || !instance) {
+    throw new Error("Smoke runtime did not spawn any instances from the template.");
+  }
+  if (!mqttAdapter.brokerUrl) {
+    throw new Error("Smoke runtime did not expose an MQTT broker URL.");
+  }
+  if (!opcuaAdapter.endpointUrl) {
+    throw new Error("Smoke runtime did not expose an OPC UA endpoint URL.");
+  }
+  if (opcuaAdapter.port <= 0) {
+    throw new Error("Smoke runtime did not expose an OPC UA port.");
+  }
+
+  await Bun.write(
+    args.readyFile,
+    JSON.stringify({
+      simulationName,
+      adminUrl: adminServer.endpoint,
+      mqttBrokerUrl: mqttAdapter.brokerUrl,
+      opcuaEndpointUrl: opcuaAdapter.endpointUrl,
+      instanceId,
+      instancePath: instance.browsePath.join("/"),
+    }),
+  );
+
+  let shuttingDown = false;
+  const shutdown = async () => {
+    if (shuttingDown) {
+      return;
+    }
+    shuttingDown = true;
+    adminServer.stop();
+    engine.bus.off("tick:complete", onTickProgress);
+    controlPlane.stop();
+    await engine.stop("smoke runner shutdown");
+    process.exit(0);
+  };
+
+  process.on("SIGINT", () => {
+    void shutdown();
+  });
+  process.on("SIGTERM", () => {
+    void shutdown();
+  });
+
+  await new Promise(() => {});
+}
+
+void main().catch((error) => {
+  console.error(error instanceof Error ? (error.stack ?? error.message) : String(error));
+  process.exit(1);
+});