miravo 0.1.4 → 0.2.1

package/src/lib/template-category.test.ts

@@ -21,7 +21,10 @@ function discoveredTemplate(id: string, name: string): DiscoveredTemplate {
 
 describe("template category helpers", () => {
   test("categorizeTemplate maps stress templates to Stress & Benchmark", () => {
-    expect(categorizeTemplate(discoveredTemplate("stress-10k-uns", "Stress 10K"))).toBe(
+    expect(categorizeTemplate(discoveredTemplate("stress-5k", "Stress 5K"))).toBe(
+      "Stress & Benchmark",
+    );
+    expect(categorizeTemplate(discoveredTemplate("stress-10k", "Stress 10K"))).toBe(
       "Stress & Benchmark",
     );
     expect(categorizeTemplate(discoveredTemplate("smart-factory", "Smart Factory"))).toBe(
@@ -31,24 +34,28 @@ describe("template category helpers", () => {
 
   test("sortTemplatesByCategoryAndName sorts by category then name", () => {
     const templates = [
-      discoveredTemplate("stress-100k-uns", "Stress 100K"),
+      discoveredTemplate("stress-100k", "Stress 100K"),
       discoveredTemplate("water-treatment", "Water Treatment"),
       discoveredTemplate("smart-factory", "Smart Factory"),
-      discoveredTemplate("stress-10k-uns", "Stress 10K"),
+      discoveredTemplate("stress-10k", "Stress 10K"),
+      discoveredTemplate("stress-5k", "Stress 5K"),
+      discoveredTemplate("stress-50k", "Stress 50K"),
     ];
 
     const sortedIds = sortTemplatesByCategoryAndName(templates).map((template) => template.id);
     expect(sortedIds).toEqual([
       "smart-factory",
       "water-treatment",
-      "stress-100k-uns",
-      "stress-10k-uns",
+      "stress-100k",
+      "stress-10k",
+      "stress-50k",
+      "stress-5k",
     ]);
   });
 
   test("groupTemplatesByCategory returns non-empty groups in category order", () => {
     const templates = sortTemplatesByCategoryAndName([
-      discoveredTemplate("stress-50k-uns", "Stress 50K"),
+      discoveredTemplate("stress-50k", "Stress 50K"),
       discoveredTemplate("water-treatment", "Water Treatment"),
     ]);
 
@@ -58,6 +65,6 @@ describe("template category helpers", () => {
       "Stress & Benchmark",
     ]);
     expect(grouped[0]?.templates.map((template) => template.id)).toEqual(["water-treatment"]);
-    expect(grouped[1]?.templates.map((template) => template.id)).toEqual(["stress-50k-uns"]);
+    expect(grouped[1]?.templates.map((template) => template.id)).toEqual(["stress-50k"]);
   });
 });

package/src/lib/template-category.ts

@@ -4,8 +4,13 @@ export type TemplateCategory = "Industrial Scenarios" | "Stress & Benchmark";
 
 const CATEGORY_ORDER: readonly TemplateCategory[] = ["Industrial Scenarios", "Stress & Benchmark"];
 
+/** True if the template is a stress/benchmark template (excluded from built-in list in CLI, same as in standalone binaries). */
+export function isStressBenchmarkTemplate(id: string): boolean {
+  return id.startsWith("stress-");
+}
+
 export function categorizeTemplate(template: Pick<DiscoveredTemplate, "id">): TemplateCategory {
-  if (template.id.startsWith("stress-")) {
+  if (isStressBenchmarkTemplate(template.id)) {
     return "Stress & Benchmark";
   }
   return "Industrial Scenarios";

package/src/lib/template-locator.ts

@@ -1,16 +1,13 @@
 import { resolve } from "node:path";
 import { ContentCatalog, type DiscoveredTemplateWithSource } from "@miravo/core";
-import { MIRAVO_CONTENT_DIR_ENV, MiravoError, TEMPLATE_FILE_EXTENSION } from "@miravo/shared";
+import { MiravoError, TEMPLATE_FILE_EXTENSION } from "@miravo/shared";
 
 /**
- * Create a ContentCatalog with standard env-var fallback for content-dir.
+ * Create a ContentCatalog with default settings.
  * Shared across all CLI commands to ensure consistent resolution.
  */
-export function createCatalog(contentDir: string | undefined): ContentCatalog {
-  const resolved = contentDir ?? Bun.env[MIRAVO_CONTENT_DIR_ENV];
-  return new ContentCatalog({
-    ...(resolved && resolved.trim().length > 0 ? { contentDir: resolved } : {}),
-  });
+export function createCatalog(): ContentCatalog {
+  return new ContentCatalog();
 }
 
 export function isTemplatePathLike(idNameOrPath: string): boolean {
@@ -23,7 +20,7 @@ export function isTemplatePathLike(idNameOrPath: string): boolean {
 }
 
 /**
- * Return local (non-builtin) templates from the catalog: content-dir + cwd.
+ * Return local (non-builtin) templates from the catalog: cwd + local registry.
  */
 export async function discoverPreferredLocalTemplates(
   catalog: ContentCatalog,

package/src/lib/template-utils.ts

@@ -0,0 +1,14 @@
+import type { MiravoTemplate } from "@miravo/shared";
+
+/** Collect all unique model names referenced by a template's twin assignments. */
+export function collectReferencedModels(template: MiravoTemplate): Set<string> {
+  const models = new Set<string>();
+  for (const area of template.areas) {
+    for (const line of area.lines) {
+      for (const twin of line.twins) {
+        models.add(twin.model);
+      }
+    }
+  }
+  return models;
+}

package/src/logger.test.ts

@@ -43,13 +43,13 @@ async function captureConsoleLogs<T>(
 describe("configureLogger", () => {
   test("--silent trumps --verbose", () => {
     configureLogger({ verbose: true, silent: true });
-    expect(logger.level).toBe(1);
+    expect(logger.level).toBe(0);
     expect(isSilent()).toBe(true);
   });
 
   test("--silent sets output suppressed", () => {
     configureLogger({ silent: true });
-    expect(logger.level).toBe(1);
+    expect(logger.level).toBe(0);
     expect(isSilent()).toBe(true);
   });
 

package/src/logger.ts

@@ -4,20 +4,42 @@ import { createConsola } from "consola";
 import { colors, stripAnsi } from "consola/utils";
 
 export type LogFormat = "pretty" | "json";
+export type LogLevel = "debug" | "info" | "warn" | "error";
+
+const LOG_LEVEL_MAP: Readonly<Record<LogLevel, number>> = {
+  debug: 4,
+  info: 3,
+  warn: 2,
+  error: 0,
+};
 
 /**
- * Color map for log tags. Consola wraps tags in `colors.gray()`, but inner
- * ANSI codes take precedence, so pre-coloring the tag overrides the gray.
+ * Color map for log tags. Used in pretty mode to prepend a colored label.
  */
 const TAG_COLORS: Readonly<Record<string, (s: string) => string>> = {
   engine: colors.cyan,
   mqtt: colors.green,
+  opcua: colors.blue,
   config: colors.yellow,
   lifecycle: colors.magenta,
-  fault: colors.red,
+  fault: colors.yellowBright,
   control: colors.blue,
 };
 
+/**
+ * Display names for log tags. Tags are internal identifiers; these are
+ * the user-facing labels shown at the start of each log line.
+ */
+const TAG_DISPLAY_NAMES: Readonly<Record<string, string>> = {
+  engine: "Engine",
+  mqtt: "MQTT",
+  opcua: "OPC UA",
+  config: "Config",
+  lifecycle: "Lifecycle",
+  fault: "Fault",
+  control: "Control",
+};
+
 /**
  * Root consola logger for the Miravo CLI.
  * `fancy: true` enables icons and color when a TTY is available.
@@ -43,14 +65,21 @@ interface ReporterLogObject {
 const fancyReporters = [...logger.options.reporters];
 const prettyReporter = {
   log(logObj: ReporterLogObject, ctx: unknown) {
-    if (logObj.args.length > 0 && typeof logObj.args[0] === "string") {
-      logObj.args[0] = ` ${logObj.args[0]}`;
-    }
+    // Move tag from the right side to a colored prefix at the start of the message
     if (logObj.tag) {
-      const colorFn = TAG_COLORS[logObj.tag];
-      if (colorFn) {
-        logObj.tag = colorFn(logObj.tag);
+      const rawTag = logObj.tag;
+      const displayName = TAG_DISPLAY_NAMES[rawTag] ?? rawTag;
+      const colorFn = TAG_COLORS[rawTag] ?? colors.gray;
+      const prefix = `${colorFn(displayName)}${colors.dim(":")}`;
+      if (logObj.args.length > 0 && typeof logObj.args[0] === "string") {
+        logObj.args[0] = ` ${prefix} ${logObj.args[0]}`;
+      } else {
+        logObj.args.unshift(` ${prefix}`);
       }
+      // Clear the tag so consola doesn't also render it on the right
+      logObj.tag = "";
+    } else if (logObj.args.length > 0 && typeof logObj.args[0] === "string") {
+      logObj.args[0] = ` ${logObj.args[0]}`;
     }
     for (const reporter of fancyReporters) {
       reporter.log(logObj as never, ctx as never);
@@ -81,7 +110,8 @@ function levelToString(level: number): "trace" | "debug" | "info" | "warn" | "er
   if (level === 4) return "debug";
   if (level === 3) return "info";
   if (level === 2) return "warn";
-  if (level === 1) return "error";
+  if (level === 1) return "warn";
+  if (level === 0) return "error";
   return "fatal";
 }
 
@@ -137,6 +167,9 @@ export const lifecycleLog: ConsolaInstance = logger.withTag("lifecycle");
 /** Fault trigger and clear events. */
 export const faultLog: ConsolaInstance = logger.withTag("fault");
 
+/** OPC UA adapter connection and server events. */
+export const opcuaLog: ConsolaInstance = logger.withTag("opcua");
+
 /** Control plane status and command routing events. */
 export const controlLog: ConsolaInstance = logger.withTag("control");
 
@@ -145,6 +178,7 @@ const allLoggers: ConsolaInstance[] = [
   logger,
   engineLog,
   mqttLog,
+  opcuaLog,
   configLog,
   lifecycleLog,
   faultLog,
@@ -164,12 +198,14 @@ export interface LoggerOptions {
   readonly silent?: boolean | undefined;
   readonly plain?: boolean | undefined;
   readonly logFormat?: LogFormat | undefined;
+  readonly logLevel?: LogLevel | undefined;
 }
 
 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,
@@ -183,6 +219,14 @@ export function parseLogFormat(raw: string): LogFormat {
   );
 }
 
+export function parseLogLevel(raw: string): LogLevel {
+  if (raw === "debug" || raw === "info" || raw === "warn" || raw === "error") return raw;
+  throw new MiravoError(
+    `Invalid log level "${raw}".`,
+    "Use --log-level debug | info | warn | error.",
+  );
+}
+
 export function setRuntimeLogContext(context: { simulationName?: string; runId?: string }): void {
   runtimeLogContext.simulationName = context.simulationName;
   runtimeLogContext.runId = context.runId;
@@ -195,9 +239,9 @@ export function clearRuntimeLogContext(): void {
 
 /**
  * Set the global log level based on CLI flags.
- * --silent trumps --verbose when both are provided.
+ * Priority: --silent > --log-level > --verbose > default (info).
  *
- * Levels: 1 = errors/fatals only, 3 = info (default), 4 = debug.
+ * Consola levels: 0 = errors/fatals, 2 = warn, 3 = info, 4 = debug.
  */
 export function configureLogger(opts: LoggerOptions): void {
   if (_locked) return;
@@ -207,15 +251,19 @@ export function configureLogger(opts: LoggerOptions): void {
 
   let level: number;
   if (opts.silent) {
-    level = 1;
+    level = 0;
     _outputSuppressed = true;
+  } else if (opts.logLevel) {
+    level = LOG_LEVEL_MAP[opts.logLevel];
+    _outputSuppressed = false;
   } else if (opts.verbose) {
-    level = 4;
+    level = LOG_LEVEL_MAP.debug;
     _outputSuppressed = false;
   } else {
-    level = 3;
+    level = LOG_LEVEL_MAP.info;
     _outputSuppressed = false;
   }
+  _currentLevel = level;
   for (const l of allLoggers) {
     l.level = level;
   }
@@ -280,6 +328,11 @@ 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

@@ -3,7 +3,8 @@
  * Uses consola/utils for ANSI-aware width calculation.
  */
 
-import { stripAnsi } from "consola/utils";
+import type { AdapterHealthSnapshot, AdapterMetrics } from "@miravo/shared";
+import { colors, stripAnsi } from "consola/utils";
 
 /** A single row in a table, where each cell is a string value keyed by column key. */
 interface TableRow {
@@ -115,3 +116,42 @@ export function formatDuration(ms: number): string {
 
   return parts.join(" ");
 }
+
+/**
+ * Format the health suffix for an adapter line in pretty/plain CLI output.
+ * Returns a string like: " · State: healthy" or " · Pending: 18,420 · State: saturated"
+ */
+export function formatHealthSuffix(metrics: AdapterMetrics, sep: string): string {
+  const health = metrics.health;
+  if (!health) return "";
+
+  let suffix = "";
+
+  if (health.pendingWorkCount > 0) {
+    suffix += `${sep}Pending: ${colors.yellow(formatCount(health.pendingWorkCount))}`;
+  }
+
+  suffix += `${sep}State: ${healthStateColor(health.state)}`;
+
+  return suffix;
+}
+
+function healthStateColor(state: AdapterHealthSnapshot["state"]): string {
+  switch (state) {
+    case "healthy":
+      return colors.green(state);
+    case "busy":
+      return colors.yellow(state);
+    case "saturated":
+      return colors.red(state);
+  }
+}
+
+/**
+ * Compute average throughput over the entire run.
+ * Returns null when there's no meaningful data (zero uptime or zero messages).
+ */
+export function computeAverageThroughput(totalMessages: number, uptimeMs: number): number | null {
+  if (uptimeMs <= 0 || totalMessages === 0) return null;
+  return Math.round(totalMessages / (uptimeMs / 1_000));
+}

package/src/lib/health-server.test.ts

@@ -1,161 +0,0 @@
-import { afterEach, describe, expect, test } from "bun:test";
-import type { EngineCoreMetrics, EngineStateSnapshot } from "@miravo/core";
-import { startHealthServer } from "./health-server.ts";
-
-function createMockHealthEngine(initialState: EngineCoreMetrics["state"], tickIntervalMs: number) {
-  const runtime = {
-    state: initialState as EngineCoreMetrics["state"],
-    tickCount: 0,
-    lastTickProgressAt: Date.now(),
-  };
-
-  const snapshot: EngineStateSnapshot = {
-    simulationName: "test-sim",
-    models: [],
-    instances: [],
-    config: {
-      seed: 1,
-      tickIntervalMs,
-      timeMultiplier: 1,
-      adapters: [],
-    },
-  };
-
-  return {
-    engine: {
-      getMetrics: () => ({
-        core: {
-          state: runtime.state,
-          tickCount: runtime.tickCount,
-          simulationTimeSeconds: 0,
-          instanceCount: 1,
-          unsEntryCount: 1,
-          quarantinedInstanceCount: 0,
-          engineErrorsCount: 0,
-          tickOverrunsCount: 0,
-          circuitBreakerTripsCount: 0,
-          uptimeMs: 0,
-          actualTicksPerSecond: 1,
-        },
-      }),
-      getState: () => snapshot,
-    },
-    setState(state: EngineCoreMetrics["state"]) {
-      runtime.state = state;
-    },
-    setTickCount(tickCount: number) {
-      runtime.tickCount = tickCount;
-    },
-    setLastTickProgressAt(timestamp: number) {
-      runtime.lastTickProgressAt = timestamp;
-    },
-    getLastTickProgressAt() {
-      return runtime.lastTickProgressAt;
-    },
-  };
-}
-
-function serverBaseUrl(endpoint: string): string {
-  const url = new URL(endpoint);
-  return `http://127.0.0.1:${url.port}`;
-}
-
-interface StartServerOptions {
-  readonly state: EngineCoreMetrics["state"];
-  readonly tickIntervalMs?: number;
-  readonly mqttEnabled: boolean;
-  readonly isMqttConnected: () => boolean;
-}
-
-function startTestServer(options: StartServerOptions, handles: Array<{ stop: () => void }>) {
-  const mock = createMockHealthEngine(options.state, options.tickIntervalMs ?? 1000);
-  const handle = startHealthServer({
-    engine: mock.engine,
-    host: "127.0.0.1",
-    port: 0,
-    mqttEnabled: options.mqttEnabled,
-    isMqttConnected: options.isMqttConnected,
-    getLastTickProgressAt: () => mock.getLastTickProgressAt(),
-  });
-  handles.push(handle);
-  const baseUrl = serverBaseUrl(handle.endpoint);
-  return { mock, baseUrl };
-}
-
-describe("health server", () => {
-  const handles: Array<{ stop: () => void }> = [];
-
-  afterEach(() => {
-    for (const handle of handles) {
-      handle.stop();
-    }
-    handles.length = 0;
-  });
-
-  test.each([
-    {
-      label: "200 when running and mqtt connected",
-      state: "running" as const,
-      healthStatus: 200,
-      readyStatus: 200,
-    },
-    { label: "503 when paused", state: "paused" as const, healthStatus: 200, readyStatus: 503 },
-  ])("/readyz returns $label", async ({ state, healthStatus, readyStatus }) => {
-    const { baseUrl } = startTestServer(
-      { state, mqttEnabled: true, isMqttConnected: () => true },
-      handles,
-    );
-
-    const health = await fetch(`${baseUrl}/healthz`);
-    const ready = await fetch(`${baseUrl}/readyz`);
-
-    expect(health.status).toBe(healthStatus);
-    expect(ready.status).toBe(readyStatus);
-  });
-
-  test("/readyz returns 503 when mqtt is enabled but disconnected", async () => {
-    const { baseUrl } = startTestServer(
-      { state: "running", mqttEnabled: true, isMqttConnected: () => false },
-      handles,
-    );
-
-    const ready = await fetch(`${baseUrl}/readyz`);
-    expect(ready.status).toBe(503);
-  });
-
-  test("/readyz ignores mqtt when mqtt is disabled", async () => {
-    const { baseUrl } = startTestServer(
-      { state: "running", mqttEnabled: false, isMqttConnected: () => false },
-      handles,
-    );
-
-    const ready = await fetch(`${baseUrl}/readyz`);
-    expect(ready.status).toBe(200);
-  });
-
-  test("/healthz returns 503 when state is stopped", async () => {
-    const { baseUrl } = startTestServer(
-      { state: "stopped", mqttEnabled: false, isMqttConnected: () => false },
-      handles,
-    );
-
-    const health = await fetch(`${baseUrl}/healthz`);
-    expect(health.status).toBe(503);
-  });
-
-  test("/healthz returns 503 on the first probe after running tick loop stalls", async () => {
-    const { mock, baseUrl } = startTestServer(
-      { state: "running", mqttEnabled: false, isMqttConnected: () => false },
-      handles,
-    );
-    mock.setLastTickProgressAt(Date.now() - 3_500);
-
-    const stalled = await fetch(`${baseUrl}/healthz`);
-    expect(stalled.status).toBe(503);
-
-    mock.setLastTickProgressAt(Date.now());
-    mock.setTickCount(1);
-    const recovered = await fetch(`${baseUrl}/healthz`);
-    expect(recovered.status).toBe(200);
-  });
-});

package/src/lib/health-server.ts

@@ -1,154 +0,0 @@
-import type { EngineCoreMetrics, EngineStateSnapshot } from "@miravo/core";
-
-interface HealthEngine {
-  getMetrics(): { readonly core: EngineCoreMetrics };
-  getState(): EngineStateSnapshot;
-}
-
-interface HealthServerOptions {
-  readonly engine: HealthEngine;
-  readonly host: string;
-  readonly port: number;
-  readonly mqttEnabled: boolean;
-  readonly isMqttConnected: () => boolean;
-  readonly getLastTickProgressAt: () => number;
-}
-
-interface HealthServerStatus {
-  readonly status: "ok" | "fail";
-  readonly reason?: string;
-}
-
-interface HealthServerHandle {
-  readonly endpoint: string;
-  stop(): void;
-}
-
-interface HealthResponseBody {
-  readonly status: "ok" | "fail";
-  readonly simulationState: EngineCoreMetrics["state"];
-  readonly tickCount: number;
-  readonly mqttEnabled: boolean;
-  readonly mqttConnected: boolean | null;
-  readonly stalled: boolean;
-  readonly reason?: string;
-}
-
-function toJsonResponse(body: HealthResponseBody, status: number): Response {
-  return new Response(JSON.stringify(body), {
-    status,
-    headers: {
-      "content-type": "application/json; charset=utf-8",
-      "cache-control": "no-store",
-    },
-  });
-}
-
-function livenessStatus(input: {
-  readonly core: EngineCoreMetrics;
-  readonly stalled: boolean;
-}): HealthServerStatus {
-  if (input.core.state === "stopped") {
-    return { status: "fail", reason: 'engine state is "stopped"' };
-  }
-  if (input.stalled) {
-    return { status: "fail", reason: "tick loop stalled" };
-  }
-  return { status: "ok" };
-}
-
-function readinessStatus(input: {
-  readonly core: EngineCoreMetrics;
-  readonly stalled: boolean;
-  readonly mqttEnabled: boolean;
-  readonly mqttConnected: boolean;
-}): HealthServerStatus {
-  if (input.core.state !== "running") {
-    return { status: "fail", reason: `engine state is "${input.core.state}"` };
-  }
-  if (input.stalled) {
-    return { status: "fail", reason: "tick loop stalled" };
-  }
-  if (input.mqttEnabled && !input.mqttConnected) {
-    return { status: "fail", reason: "mqtt disconnected" };
-  }
-  return { status: "ok" };
-}
-
-/**
- * Start a lightweight HTTP health server for container probes.
- *
- * - `/healthz`: liveness (process/tick loop health)
- * - `/readyz`: readiness (engine running + MQTT connected when enabled)
- */
-function startHealthServer(options: HealthServerOptions): HealthServerHandle {
-  const { engine, host, port, mqttEnabled, isMqttConnected, getLastTickProgressAt } = options;
-
-  const server = Bun.serve({
-    hostname: host,
-    port,
-    fetch(request) {
-      const pathname = new URL(request.url).pathname;
-      const metrics = engine.getMetrics();
-      const state = engine.getState();
-
-      const now = Date.now();
-      const stallThresholdMs = Math.max(100, state.config.tickIntervalMs * 3);
-      const lastTickProgressAt = getLastTickProgressAt();
-      const stalled =
-        metrics.core.state === "running" &&
-        Number.isFinite(lastTickProgressAt) &&
-        now - lastTickProgressAt > stallThresholdMs;
-
-      const mqttConnected = mqttEnabled ? isMqttConnected() : false;
-      const bodyBase = {
-        simulationState: metrics.core.state,
-        tickCount: metrics.core.tickCount,
-        mqttEnabled,
-        mqttConnected: mqttEnabled ? mqttConnected : null,
-        stalled,
-      } as const;
-
-      if (pathname === "/healthz") {
-        const status = livenessStatus({ core: metrics.core, stalled });
-        return toJsonResponse(
-          {
-            status: status.status,
-            ...bodyBase,
-            ...(status.reason ? { reason: status.reason } : {}),
-          },
-          status.status === "ok" ? 200 : 503,
-        );
-      }
-
-      if (pathname === "/readyz") {
-        const status = readinessStatus({
-          core: metrics.core,
-          stalled,
-          mqttEnabled,
-          mqttConnected,
-        });
-        return toJsonResponse(
-          {
-            status: status.status,
-            ...bodyBase,
-            ...(status.reason ? { reason: status.reason } : {}),
-          },
-          status.status === "ok" ? 200 : 503,
-        );
-      }
-
-      return new Response("Not Found", { status: 404 });
-    },
-  });
-
-  return {
-    endpoint: `http://${host}:${server.port}`,
-    stop() {
-      server.stop(true);
-    },
-  };
-}
-
-export { startHealthServer };
-export type { HealthEngine, HealthServerHandle, HealthServerOptions };