miravo 0.2.2 → 0.3.0

package/src/lib/ws-hub.ts

@@ -0,0 +1,255 @@
+import type { EventBus, MiravoEvents } from "@miravo/core";
+import { subscribeToDomainEvents } from "@miravo/core";
+import type { EngineRunState, WSMessage } from "@miravo/shared";
+import type { ServerWebSocket } from "bun";
+
+/** Channels a client can subscribe to. */
+type Channel = "tick" | "faults" | "lifecycle" | "instances" | "engine" | "adapters";
+
+/** All channels enabled by default. */
+const ALL_CHANNELS: ReadonlySet<Channel> = new Set([
+  "tick",
+  "faults",
+  "lifecycle",
+  "instances",
+  "engine",
+  "adapters",
+]);
+
+function isChannel(value: string): value is Channel {
+  return (ALL_CHANNELS as ReadonlySet<string>).has(value);
+}
+
+/** Per-connection state stored via Bun's WebSocket data field. */
+interface WSClientData {
+  channels: Set<Channel>;
+}
+
+interface WSHubOptions {
+  readonly bus: EventBus;
+  readonly getEngineState: () => EngineRunState;
+  readonly getTickInfo: () => { tick: number; simulationTime: number; instanceCount: number };
+  readonly maxConnections?: number;
+  readonly backpressureThreshold?: number;
+}
+
+const DEFAULT_MAX_CONNECTIONS = 10;
+const DEFAULT_BACKPRESSURE_THRESHOLD = 1024 * 64; // 64KB send buffer
+
+/**
+ * WebSocket hub that fans out engine events to connected clients.
+ * Read-only: clients can only subscribe to channels, not send commands.
+ */
+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 #bus: EventBus;
+  readonly #tickHandler: (evt: MiravoEvents["tick:complete"]) => void;
+  readonly #adapterEnabledHandler: (evt: MiravoEvents["adapter:enabled"]) => void;
+  readonly #adapterDisabledHandler: (evt: MiravoEvents["adapter:disabled"]) => void;
+  readonly #unsubscribeDomain: () => void;
+  #revision = 0;
+
+  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.#bus = options.bus;
+
+    // Tick events are on their own channel (highest frequency)
+    this.#tickHandler = (evt) => {
+      this.#broadcast("tick", {
+        type: "tick",
+        revision: this.#nextRevision(),
+        tick: evt.tick,
+        simulationTime: evt.simulationTime,
+        delta: evt.delta.memberChanged,
+        instanceCount: evt.graph.assets.size,
+      });
+    };
+    this.#bus.on("tick:complete", this.#tickHandler);
+
+    // Adapter lifecycle events
+    this.#adapterEnabledHandler = (evt) => {
+      this.#broadcast("adapters", {
+        type: "adapter:enabled",
+        revision: this.#nextRevision(),
+        name: evt.name,
+        endpoint: evt.endpoint,
+      });
+    };
+    this.#adapterDisabledHandler = (evt) => {
+      this.#broadcast("adapters", {
+        type: "adapter:disabled",
+        revision: this.#nextRevision(),
+        name: evt.name,
+      });
+    };
+    this.#bus.on("adapter:enabled", this.#adapterEnabledHandler);
+    this.#bus.on("adapter:disabled", this.#adapterDisabledHandler);
+
+    // Domain events use the shared subscriber (stays in sync with EventLog)
+    this.#unsubscribeDomain = subscribeToDomainEvents(options.bus, {
+      "fault:triggered": (evt) => {
+        this.#broadcast("faults", {
+          type: "fault:triggered",
+          revision: this.#nextRevision(),
+          instanceId: evt.instanceId,
+          fault: evt.fault,
+          effects: evt.effects,
+        });
+      },
+      "fault:cleared": (evt) => {
+        this.#broadcast("faults", {
+          type: "fault:cleared",
+          revision: this.#nextRevision(),
+          instanceId: evt.instanceId,
+          fault: evt.fault,
+        });
+      },
+      "lifecycle:changed": (evt) => {
+        this.#broadcast("lifecycle", {
+          type: "lifecycle:changed",
+          revision: this.#nextRevision(),
+          instanceId: evt.instanceId,
+          from: evt.from,
+          to: evt.to,
+          operatingHours: evt.operatingHours,
+        });
+      },
+      "instance:created": (evt) => {
+        this.#broadcast("instances", {
+          type: "instance:created",
+          revision: this.#nextRevision(),
+          id: evt.id,
+          assetType: evt.assetType,
+          browsePath: evt.browsePath,
+        });
+      },
+      "instance:removed": (evt) => {
+        this.#broadcast("instances", {
+          type: "instance:removed",
+          revision: this.#nextRevision(),
+          id: evt.id,
+        });
+      },
+      "engine:state-changed": (evt) => {
+        this.#broadcast("engine", {
+          type: "engine:state",
+          revision: this.#nextRevision(),
+          from: evt.from,
+          to: evt.to,
+        });
+      },
+    });
+  }
+
+  #nextRevision(): number {
+    return ++this.#revision;
+  }
+
+  #broadcast(channel: Channel, message: WSMessage): void {
+    const json = JSON.stringify(message);
+    for (const ws of this.#clients) {
+      if (!ws.data.channels.has(channel)) continue;
+
+      // Backpressure: close congested connections to prevent unbounded buffer growth.
+      // The client should reconnect and will receive a fresh snapshot.
+      if (ws.getBufferedAmount() > this.#backpressureThreshold) {
+        try {
+          ws.close(4008, "backpressure");
+        } catch {
+          // Client may have already disconnected
+        }
+        this.#clients.delete(ws);
+        continue;
+      }
+
+      try {
+        ws.send(json);
+      } catch {
+        // Client disconnected — will be cleaned up in onClose
+      }
+    }
+  }
+
+  /** Called when a new WebSocket connection opens. */
+  onOpen(ws: ServerWebSocket<WSClientData>): void {
+    if (this.#clients.size >= this.#maxConnections) {
+      ws.close(1013, "Max connections exceeded");
+      return;
+    }
+
+    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));
+  }
+
+  /** Called when a WebSocket message is received from a client. */
+  onMessage(ws: ServerWebSocket<WSClientData>, message: string | Buffer): void {
+    const text = typeof message === "string" ? message : message.toString();
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(text);
+    } catch {
+      return; // Ignore invalid JSON
+    }
+
+    if (typeof parsed !== "object" || parsed === null) return;
+    const msg = parsed as Record<string, unknown>;
+
+    if (msg["type"] === "subscribe" && Array.isArray(msg["channels"])) {
+      const newChannels = new Set<Channel>();
+      for (const ch of msg["channels"]) {
+        if (typeof ch === "string" && isChannel(ch)) {
+          newChannels.add(ch);
+        }
+      }
+      ws.data.channels = newChannels;
+    }
+  }
+
+  /** Called when a WebSocket connection closes. */
+  onClose(ws: ServerWebSocket<WSClientData>): void {
+    this.#clients.delete(ws);
+  }
+
+  /** Number of currently connected clients. */
+  get connectionCount(): number {
+    return this.#clients.size;
+  }
+
+  /** Close all connections and unsubscribe from bus events. */
+  close(): void {
+    this.#bus.off("tick:complete", this.#tickHandler);
+    this.#bus.off("adapter:enabled", this.#adapterEnabledHandler);
+    this.#bus.off("adapter:disabled", this.#adapterDisabledHandler);
+    this.#unsubscribeDomain();
+
+    for (const ws of this.#clients) {
+      try {
+        ws.close(1001, "Server shutting down");
+      } catch {
+        // Ignore
+      }
+    }
+    this.#clients.clear();
+  }
+}
+
+export type { Channel, WSClientData, WSHubOptions };
+export { ALL_CHANNELS, WSHub };

package/src/logger.test.ts

@@ -5,7 +5,7 @@ import {
   engineLog,
   isJsonLogFormat,
   isPlain,
-  isSilent,
+  isQuiet,
   lockLogger,
   logger,
   parseLogFormat,
@@ -19,8 +19,8 @@ beforeEach(() => {
 });
 
 afterEach(() => {
-  // Restore silent + locked for other test files
-  configureLogger({ silent: true });
+  // Restore quiet + locked for other test files
+  configureLogger({ quiet: true });
   lockLogger();
 });
 
@@ -41,35 +41,35 @@ async function captureConsoleLogs<T>(
 }
 
 describe("configureLogger", () => {
-  test("--silent trumps --verbose", () => {
-    configureLogger({ verbose: true, silent: true });
+  test("--quiet trumps --verbose", () => {
+    configureLogger({ verbose: true, quiet: true });
     expect(logger.level).toBe(0);
-    expect(isSilent()).toBe(true);
+    expect(isQuiet()).toBe(true);
   });
 
-  test("--silent sets output suppressed", () => {
-    configureLogger({ silent: true });
+  test("--quiet sets output suppressed", () => {
+    configureLogger({ quiet: true });
     expect(logger.level).toBe(0);
-    expect(isSilent()).toBe(true);
+    expect(isQuiet()).toBe(true);
   });
 
   test("--verbose sets debug level", () => {
     configureLogger({ verbose: true });
     expect(logger.level).toBe(4);
-    expect(isSilent()).toBe(false);
+    expect(isQuiet()).toBe(false);
   });
 
   test("default sets info level", () => {
     configureLogger({});
     expect(logger.level).toBe(3);
-    expect(isSilent()).toBe(false);
+    expect(isQuiet()).toBe(false);
   });
 
-  test("--verbose after --silent restores output", () => {
-    configureLogger({ silent: true });
-    expect(isSilent()).toBe(true);
+  test("--verbose after --quiet restores output", () => {
+    configureLogger({ quiet: true });
+    expect(isQuiet()).toBe(true);
     configureLogger({ verbose: true });
-    expect(isSilent()).toBe(false);
+    expect(isQuiet()).toBe(false);
   });
 
   test("--plain enables plain output mode", () => {
@@ -148,18 +148,18 @@ describe("configureLogger", () => {
     expect(calls[0]).toEqual(["red"]);
   });
 
-  test("writeOutput is suppressed by --silent even in plain mode", async () => {
+  test("writeOutput is suppressed by --quiet even in plain mode", async () => {
     const { calls } = await captureConsoleLogs(() => {
-      configureLogger({ silent: true, plain: true });
+      configureLogger({ quiet: true, plain: true });
       writeOutput("hidden");
     });
 
     expect(calls.length).toBe(0);
   });
 
-  test("--silent still emits error logs", async () => {
+  test("--quiet still emits error logs", async () => {
     const { calls } = await captureConsoleLogs(() => {
-      configureLogger({ silent: true, logFormat: "json" });
+      configureLogger({ quiet: true, logFormat: "json" });
       engineLog.error("still visible");
     });
 

package/src/logger.ts

@@ -195,7 +195,7 @@ function applyLogReporter(format: LogFormat): void {
 /** Options for configuring log verbosity from CLI flags. */
 export interface LoggerOptions {
   readonly verbose?: boolean | undefined;
-  readonly silent?: boolean | undefined;
+  readonly quiet?: boolean | undefined;
   readonly plain?: boolean | undefined;
   readonly logFormat?: LogFormat | undefined;
   readonly logLevel?: LogLevel | undefined;
@@ -239,7 +239,7 @@ export function clearRuntimeLogContext(): void {
 
 /**
  * Set the global log level based on CLI flags.
- * Priority: --silent > --log-level > --verbose > default (info).
+ * Priority: --quiet > --log-level > --verbose > default (info).
  *
  * Consola levels: 0 = errors/fatals, 2 = warn, 3 = info, 4 = debug.
  */
@@ -249,8 +249,13 @@ export function configureLogger(opts: LoggerOptions): void {
   applyLogReporter(_logFormat);
   _plainOutput = opts.plain ?? false;
 
+  // NO_COLOR convention: disable colors when set to any non-empty value
+  if (!_plainOutput && Bun.env["NO_COLOR"] !== undefined && Bun.env["NO_COLOR"] !== "") {
+    _plainOutput = true;
+  }
+
   let level: number;
-  if (opts.silent) {
+  if (opts.quiet) {
     level = 0;
     _outputSuppressed = true;
   } else if (opts.logLevel) {
@@ -275,7 +280,7 @@ export function isJsonLogFormat(): boolean {
 }
 
 /**
- * Write informational output to stdout, respecting --silent.
+ * Write informational output to stdout, respecting --quiet.
  * Use this for primary formatted output (tables, boxes, status renders).
  * Do NOT use for machine-readable output (--json, --raw) — those should
  * always go through `process.stdout.write()` or `console.log()` directly.
@@ -305,8 +310,8 @@ export function writeOutput(...args: unknown[]): void {
   console.log(...args);
 }
 
-/** Returns true when --silent is active. */
-export function isSilent(): boolean {
+/** Returns true when --quiet is active. */
+export function isQuiet(): boolean {
   return _outputSuppressed;
 }
 
@@ -347,3 +352,26 @@ export function handleCommandError(error: unknown, log: ConsolaInstance = config
     throw error;
   }
 }
+
+interface CommandResultLike {
+  readonly success: boolean;
+  readonly message: string;
+  readonly error?: string | undefined;
+}
+
+/**
+ * Handle the result of an admin command, respecting --json output.
+ * Writes success messages to stdout and errors to the control log.
+ * Sets process.exitCode = 1 on failure.
+ */
+export function handleCommandResult(result: CommandResultLike, json?: boolean): void {
+  if (json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else if (result.success) {
+    writeOutput(result.message);
+  } else {
+    controlLog.error(result.message);
+    if (result.error) controlLog.error(`Fix: ${result.error}`);
+  }
+  if (!result.success) process.exitCode = 1;
+}