miravo 0.5.0 → 0.6.0

package/src/lib/ws-hub.ts

@@ -1,6 +1,6 @@
 import type { EventBus, MiravoEvents } from "@miravo/core";
 import { subscribeToDomainEvents } from "@miravo/core";
-import type { EngineRunState, WSMessage } from "@miravo/shared";
+import type { RuntimeSnapshot, WSMessage } from "@miravo/shared";
 import type { ServerWebSocket } from "bun";
 
 /** Channels a client can subscribe to. */
@@ -25,10 +25,20 @@ interface WSClientData {
   channels: Set<Channel>;
 }
 
+/**
+ * Callback that provides the engine data needed to build a RuntimeSnapshot.
+ * Accepts any structurally compatible type — the data is JSON-serialized in
+ * buildRuntimeSnapshot(), so readonly core types and mutable Zod types both work.
+ */
+interface RuntimeSnapshotSource {
+  readonly getState: () => unknown;
+  readonly getMetrics: () => unknown;
+  readonly getRunningTemplates: () => unknown;
+}
+
 interface WSHubOptions {
   readonly bus: EventBus;
-  readonly getEngineState: () => EngineRunState;
-  readonly getTickInfo: () => { tick: number; simulationTime: number; instanceCount: number };
+  readonly snapshotSource: RuntimeSnapshotSource;
   readonly maxConnections?: number;
   readonly backpressureThreshold?: number;
 }
@@ -44,8 +54,7 @@ class WSHub {
   readonly #clients = new Set<ServerWebSocket<WSClientData>>();
   readonly #maxConnections: number;
   readonly #backpressureThreshold: number;
-  readonly #getEngineState: () => EngineRunState;
-  readonly #getTickInfo: () => { tick: number; simulationTime: number; instanceCount: number };
+  readonly #snapshotSource: RuntimeSnapshotSource;
   readonly #bus: EventBus;
   readonly #tickHandler: (evt: MiravoEvents["tick:complete"]) => void;
   readonly #adapterEnabledHandler: (evt: MiravoEvents["adapter:enabled"]) => void;
@@ -56,14 +65,13 @@ class WSHub {
   constructor(options: WSHubOptions) {
     this.#maxConnections = options.maxConnections ?? DEFAULT_MAX_CONNECTIONS;
     this.#backpressureThreshold = options.backpressureThreshold ?? DEFAULT_BACKPRESSURE_THRESHOLD;
-    this.#getEngineState = options.getEngineState;
-    this.#getTickInfo = options.getTickInfo;
+    this.#snapshotSource = options.snapshotSource;
     this.#bus = options.bus;
 
     // Tick events are on their own channel (highest frequency)
     this.#tickHandler = (evt) => {
       this.#broadcast("tick", {
-        type: "tick",
+        type: "runtime:tick",
         revision: this.#nextRevision(),
         tick: evt.tick,
         simulationTime: evt.simulationTime,
@@ -76,17 +84,16 @@ class WSHub {
     // Adapter lifecycle events
     this.#adapterEnabledHandler = (evt) => {
       this.#broadcast("adapters", {
-        type: "adapter:enabled",
+        type: "runtime:event",
         revision: this.#nextRevision(),
-        name: evt.name,
-        endpoint: evt.endpoint,
+        event: { kind: "adapter:enabled", name: evt.name, endpoint: evt.endpoint },
       });
     };
     this.#adapterDisabledHandler = (evt) => {
       this.#broadcast("adapters", {
-        type: "adapter:disabled",
+        type: "runtime:event",
         revision: this.#nextRevision(),
-        name: evt.name,
+        event: { kind: "adapter:disabled", name: evt.name },
       });
     };
     this.#bus.on("adapter:enabled", this.#adapterEnabledHandler);
@@ -96,53 +103,60 @@ class WSHub {
     this.#unsubscribeDomain = subscribeToDomainEvents(options.bus, {
       "fault:triggered": (evt) => {
         this.#broadcast("faults", {
-          type: "fault:triggered",
+          type: "runtime:event",
           revision: this.#nextRevision(),
-          instanceId: evt.instanceId,
-          fault: evt.fault,
-          effects: evt.effects,
+          event: {
+            kind: "fault:triggered",
+            instanceId: evt.instanceId,
+            fault: evt.fault,
+            effects: evt.effects,
+          },
         });
       },
       "fault:cleared": (evt) => {
         this.#broadcast("faults", {
-          type: "fault:cleared",
+          type: "runtime:event",
           revision: this.#nextRevision(),
-          instanceId: evt.instanceId,
-          fault: evt.fault,
+          event: { kind: "fault:cleared", instanceId: evt.instanceId, fault: evt.fault },
         });
       },
       "lifecycle:changed": (evt) => {
         this.#broadcast("lifecycle", {
-          type: "lifecycle:changed",
+          type: "runtime:event",
           revision: this.#nextRevision(),
-          instanceId: evt.instanceId,
-          from: evt.from,
-          to: evt.to,
-          operatingHours: evt.operatingHours,
+          event: {
+            kind: "lifecycle:changed",
+            instanceId: evt.instanceId,
+            from: evt.from,
+            to: evt.to,
+            operatingHours: evt.operatingHours,
+          },
         });
       },
       "instance:created": (evt) => {
         this.#broadcast("instances", {
-          type: "instance:created",
+          type: "runtime:event",
           revision: this.#nextRevision(),
-          id: evt.id,
-          assetType: evt.assetType,
-          browsePath: evt.browsePath,
+          event: {
+            kind: "instance:created",
+            id: evt.id,
+            assetType: evt.assetType,
+            browsePath: evt.browsePath,
+          },
         });
       },
       "instance:removed": (evt) => {
         this.#broadcast("instances", {
-          type: "instance:removed",
+          type: "runtime:event",
           revision: this.#nextRevision(),
-          id: evt.id,
+          event: { kind: "instance:removed", id: evt.id },
         });
       },
       "engine:state-changed": (evt) => {
         this.#broadcast("engine", {
-          type: "engine:state",
+          type: "runtime:event",
           revision: this.#nextRevision(),
-          from: evt.from,
-          to: evt.to,
+          event: { kind: "engine:state", from: evt.from, to: evt.to },
         });
       },
     });
@@ -152,6 +166,25 @@ class WSHub {
     return ++this.#revision;
   }
 
+  /** Current monotonic revision counter (does not increment). */
+  get currentRevision(): number {
+    return this.#revision;
+  }
+
+  /** Build a canonical RuntimeSnapshot using the current engine state. */
+  buildRuntimeSnapshot(): RuntimeSnapshot {
+    // JSON round-trip reconciles readonly engine types with Zod-inferred mutable types.
+    // Negligible cost: snapshots are serialized for HTTP/WS anyway.
+    return JSON.parse(
+      JSON.stringify({
+        state: this.#snapshotSource.getState(),
+        metrics: this.#snapshotSource.getMetrics(),
+        runningTemplates: this.#snapshotSource.getRunningTemplates(),
+        revision: this.#nextRevision(),
+      }),
+    ) as RuntimeSnapshot;
+  }
+
   #broadcast(channel: Channel, message: WSMessage): void {
     const json = JSON.stringify(message);
     for (const ws of this.#clients) {
@@ -186,17 +219,10 @@ class WSHub {
 
     this.#clients.add(ws);
 
-    // Send initial snapshot
-    const tickInfo = this.#getTickInfo();
-    const snapshot: WSMessage = {
-      type: "snapshot",
-      revision: this.#nextRevision(),
-      state: this.#getEngineState(),
-      tick: tickInfo.tick,
-      simulationTime: tickInfo.simulationTime,
-      instanceCount: tickInfo.instanceCount,
-    };
-    ws.send(JSON.stringify(snapshot));
+    // Send initial canonical runtime snapshot
+    const snapshot = this.buildRuntimeSnapshot();
+    const msg: WSMessage = { type: "runtime:snapshot", snapshot };
+    ws.send(JSON.stringify(msg));
   }
 
   /** Called when a WebSocket message is received from a client. */
@@ -251,5 +277,5 @@ class WSHub {
   }
 }
 
-export type { Channel, WSClientData, WSHubOptions };
+export type { WSClientData };
 export { ALL_CHANNELS, WSHub };

package/src/logger.ts

@@ -3,8 +3,8 @@ import type { ConsolaInstance } from "consola";
 import { createConsola } from "consola";
 import { colors, stripAnsi } from "consola/utils";
 
-export type LogFormat = "pretty" | "json";
-export type LogLevel = "debug" | "info" | "warn" | "error";
+type LogFormat = "pretty" | "json";
+type LogLevel = "debug" | "info" | "warn" | "error";
 
 const LOG_LEVEL_MAP: Readonly<Record<LogLevel, number>> = {
   debug: 4,
@@ -26,6 +26,7 @@ const LOG_LEVEL_MAP: Readonly<Record<LogLevel, number>> = {
  *   lifecycle  → magenta      brand chart-4 #8b5cf6 (violet)
  *   fault      → redBright    brand destructive #f43f5e (rose)
  *   control    → blueBright   lighter blue, distinct from opcua
+ *   platform   → greenBright  LE apply/cleanup operations
  */
 const TAG_COLORS: Readonly<Record<string, (s: string) => string>> = {
   engine: colors.yellow,
@@ -36,6 +37,7 @@ const TAG_COLORS: Readonly<Record<string, (s: string) => string>> = {
   lifecycle: colors.magenta,
   fault: colors.redBright,
   control: colors.blueBright,
+  platform: colors.greenBright,
 };
 
 /**
@@ -51,6 +53,7 @@ const TAG_DISPLAY_NAMES: Readonly<Record<string, string>> = {
   lifecycle: "Lifecycle",
   fault: "Fault",
   control: "Control",
+  platform: "Platform",
 };
 
 /**
@@ -189,6 +192,17 @@ export const modbusLog: ConsolaInstance = logger.withTag("modbus");
 /** Control plane status and command routing events. */
 export const controlLog: ConsolaInstance = logger.withTag("control");
 
+/** Litmus Edge platform apply/cleanup operation events. */
+export const platformLog: ConsolaInstance = logger.withTag("platform");
+
+/** Route an adapter name to its dedicated logger. Falls back to engineLog for unknown names. */
+export function adapterLogger(name: string): ConsolaInstance {
+  if (name === "mqtt") return mqttLog;
+  if (name === "opcua") return opcuaLog;
+  if (name === "modbus") return modbusLog;
+  return engineLog;
+}
+
 /** All tag loggers, for bulk level updates. */
 const allLoggers: ConsolaInstance[] = [
   logger,
@@ -200,6 +214,7 @@ const allLoggers: ConsolaInstance[] = [
   lifecycleLog,
   faultLog,
   controlLog,
+  platformLog,
 ];
 
 function applyLogReporter(format: LogFormat): void {
@@ -210,7 +225,7 @@ function applyLogReporter(format: LogFormat): void {
 }
 
 /** Options for configuring log verbosity from CLI flags. */
-export interface LoggerOptions {
+interface LoggerOptions {
   readonly verbose?: boolean | undefined;
   readonly quiet?: boolean | undefined;
   readonly plain?: boolean | undefined;
@@ -222,7 +237,6 @@ let _outputSuppressed = false;
 let _plainOutput = false;
 let _locked = false;
 let _logFormat: LogFormat = "pretty";
-let _currentLevel = LOG_LEVEL_MAP.info;
 const runtimeLogContext: { simulationName: string | undefined; runId: string | undefined } = {
   simulationName: undefined,
   runId: undefined,
@@ -285,7 +299,6 @@ export function configureLogger(opts: LoggerOptions): void {
     level = LOG_LEVEL_MAP.info;
     _outputSuppressed = false;
   }
-  _currentLevel = level;
   for (const l of allLoggers) {
     l.level = level;
   }
@@ -350,11 +363,6 @@ export function isPlain(): boolean {
   return _plainOutput;
 }
 
-/** Returns true when log level is debug (--verbose or --log-level debug). */
-export function isDebugLevel(): boolean {
-  return _currentLevel >= LOG_LEVEL_MAP.debug;
-}
-
 /**
  * Handle a caught error in a CLI command action. If it's a `MiravoError`,
  * log the message and fix string and set a non-zero exit code. Otherwise

package/src/output.ts

@@ -11,6 +11,9 @@ interface TableRow {
   readonly [key: string]: string;
 }
 
+/** Dim separator used between values on a single summary line. */
+export const sep = colors.dim(" \u00B7 ");
+
 /**
  * Format a list of objects as a column-aligned table.
  * Column widths are auto-calculated from header labels and cell values.