miravo 0.1.4 → 0.2.0

package/src/lib/shutdown.ts

@@ -1,7 +1,9 @@
 import type { Engine, EngineMetricsSnapshot } from "@miravo/core";
-import { box, colors } from "consola/utils";
-import { engineLog, isPlain, isSilent, mqttLog, writeOutput } from "../logger.ts";
-import { formatCount, formatDuration } from "../output.ts";
+import type { AdapterHealthSnapshot } from "@miravo/shared";
+import type { TreeItem } from "consola/utils";
+import { box, colors, formatTree } from "consola/utils";
+import { engineLog, isJsonLogFormat, isPlain, isSilent, writeOutput } from "../logger.ts";
+import { computeAverageThroughput, formatCount, formatDuration } from "../output.ts";
 
 /** Parameters for the shutdown handler. Supports dependency injection for tests. */
 export interface ShutdownOptions {
@@ -54,14 +56,13 @@ export function installShutdownHandlers(options: ShutdownOptions): () => void {
     // Capture metrics before stop() clears bus listeners
     const finalMetrics = engine.getMetrics();
 
-    cleanup?.();
-
     let timedOut = false;
     let timeoutHandle: ReturnType<typeof setTimeout> | null = null;
     try {
-      mqttLog.start("Flushing pending messages (5s timeout)...");
+      engineLog.start("Flushing pending messages (5s timeout)...");
       const stopResult = engine.stop(signal === "SIGINT" ? "user interrupt" : signal);
-      // Race engine.stop() against a 5s timeout so shutdown never hangs
+      // Suppress unhandled rejection if stop() rejects after timeout wins the race
+      stopResult.catch(() => {});
       await Promise.race([
         stopResult,
         new Promise<void>((resolve) => {
@@ -74,7 +75,7 @@ export function installShutdownHandlers(options: ShutdownOptions): () => void {
       if (timedOut) {
         engineLog.warn("Engine stop timed out after 5s, proceeding with exit.");
       } else {
-        mqttLog.success("Stopped.");
+        engineLog.success("Stopped.");
       }
     } catch (err) {
       engineLog.error("Error during shutdown:", err);
@@ -84,11 +85,16 @@ export function installShutdownHandlers(options: ShutdownOptions): () => void {
       }
     }
 
+    // Clean up timers, admin server, and bus listeners AFTER engine.stop()
+    // so that adapter shutdown errors are still observable on the bus.
+    cleanup?.();
+
     if (forcedExit) {
       return;
     }
 
     printShutdownSummary(finalMetrics, seed, seedExplicit, errorContextCounts);
+    Bun.stdout.writer().flush();
     exit(0);
   };
 
@@ -109,52 +115,212 @@ export function installShutdownHandlers(options: ShutdownOptions): () => void {
   };
 }
 
-function printShutdownSummary(
-  metrics: EngineMetricsSnapshot,
-  seed: number,
-  seedExplicit: boolean,
-  errorContextCounts?: ReadonlyMap<string, number>,
-): void {
-  if (isSilent()) return;
+// ---------------------------------------------------------------------------
+// Shared summary rendering
+// ---------------------------------------------------------------------------
+
+interface SummaryInput {
+  readonly metrics: EngineMetricsSnapshot;
+  readonly seed?: number | undefined;
+  readonly seedExplicit?: boolean | undefined;
+  readonly errorContextCounts?: ReadonlyMap<string, number> | undefined;
+}
 
-  const { core, fleet, adapters } = metrics;
-  const mqttAdapter = adapters.find((a) => a.name === "mqtt");
+function healthStateLabel(state: AdapterHealthSnapshot["state"]): string {
+  switch (state) {
+    case "healthy":
+      return colors.green(state);
+    case "busy":
+      return colors.yellow(state);
+    case "saturated":
+      return colors.red(state);
+  }
+}
 
+/**
+ * Build the pretty summary lines from an engine metrics snapshot.
+ * Used by both the shutdown summary and periodic summary.
+ */
+function buildSummaryLines(input: SummaryInput): string[] {
+  const { core, fleet, adapters } = input.metrics;
   const sep = colors.dim(" \u00B7 ");
   const lines: string[] = [];
 
+  // --- Core stats ---
   lines.push(
-    `${colors.bold(formatDuration(core.uptimeMs))}${sep}${colors.bold(formatCount(core.tickCount))} ticks${sep}${colors.bold(formatCount(core.instanceCount))} instances${sep}${colors.bold(formatCount(core.unsEntryCount))} UNS topics`,
+    `${colors.bold(formatDuration(core.uptimeMs))}${sep}${colors.bold(formatCount(core.tickCount))} ticks${sep}${colors.bold(String(core.actualTicksPerSecond.toFixed(1)))} ticks/s`,
+  );
+  lines.push(
+    `${colors.bold(formatCount(core.instanceCount))} instances${sep}${colors.bold(formatCount(core.memberValueCount))} data points${sep}sim: ${colors.bold(core.simulationTimeSeconds.toFixed(1))}s`,
   );
 
-  if (mqttAdapter) {
-    const errCount = mqttAdapter.metrics.errorsCount;
+  // --- Protocol adapters ---
+  for (const adapter of adapters) {
+    const m = adapter.metrics;
+    const label = adapter.name === "opcua" ? "OPC UA" : adapter.name.toUpperCase();
+    const verb = adapter.name === "opcua" ? "updates" : "published";
+    const connStr = m.connected ? colors.green("connected") : colors.red("disconnected");
     const errStr =
-      errCount === 0 ? colors.green(formatCount(errCount)) : colors.yellow(formatCount(errCount));
+      m.errorsCount === 0
+        ? colors.green(formatCount(m.errorsCount))
+        : colors.yellow(formatCount(m.errorsCount));
+    const avgThroughput = computeAverageThroughput(m.messagesPublished, core.uptimeMs);
+    const throughputStr = avgThroughput !== null ? `${sep}${formatCount(avgThroughput)} msg/s` : "";
+    const filteredStr =
+      m.messagesFiltered > 0 ? `${sep}${colors.dim(formatCount(m.messagesFiltered))} filtered` : "";
     lines.push(
-      `MQTT: ${colors.bold(formatCount(mqttAdapter.metrics.messagesPublished))} published${sep}${errStr} errors`,
+      `${label}: ${connStr}${sep}${colors.bold(formatCount(m.messagesPublished))} ${verb}${sep}${errStr} errors${throughputStr}${filteredStr}`,
     );
+    // Health on a separate line to keep the box narrow
+    const health = m.health;
+    if (health) {
+      const pendingStr =
+        health.pendingWorkCount > 0 ? `${formatCount(health.pendingWorkCount)} pending${sep}` : "";
+      lines.push(`  ${pendingStr}${healthStateLabel(health.state)}`);
+    }
   }
 
+  // --- Fleet health ---
+  const healthParts: string[] = [];
   if (fleet.activeFaultCount > 0) {
-    lines.push(`Active faults at shutdown: ${colors.yellow(String(fleet.activeFaultCount))}`);
+    healthParts.push(`${colors.yellow(String(fleet.activeFaultCount))} active faults`);
+  }
+  if (core.quarantinedInstanceCount > 0) {
+    healthParts.push(`${colors.yellow(String(core.quarantinedInstanceCount))} quarantined`);
+  }
+  if (core.engineErrorsCount > 0) {
+    healthParts.push(`${colors.yellow(formatCount(core.engineErrorsCount))} engine errors`);
+  }
+  if (core.tickOverrunsCount > 0) {
+    healthParts.push(`${colors.yellow(formatCount(core.tickOverrunsCount))} overruns`);
+  }
+  if (core.circuitBreakerTripsCount > 0) {
+    healthParts.push(`${colors.yellow(formatCount(core.circuitBreakerTripsCount))} breaker trips`);
+  }
+  if (healthParts.length > 0) {
+    lines.push(healthParts.join(sep));
   }
 
-  const seedLine = seedExplicit
-    ? `Seed: ${colors.bold(String(seed))}`
-    : `Seed: ${colors.bold(String(seed))} ${colors.gray("(add seed to config to reproduce)")}`;
-  lines.push(seedLine);
+  // --- Fault breakdown (tree) ---
+  if (fleet.faultBreakdown.length > 0) {
+    const faultItems: TreeItem[] = fleet.faultBreakdown.map(
+      (f) => `${colors.yellow(String(f.count))} ${f.fault}`,
+    );
+    lines.push(formatTree(faultItems, { color: "yellow", prefix: "  " }).trimEnd());
+  }
 
-  if (errorContextCounts && errorContextCounts.size > 0) {
-    const topContexts = [...errorContextCounts.entries()].sort((a, b) => b[1] - a[1]).slice(0, 5);
-    lines.push("Top error contexts:");
-    for (const [context, count] of topContexts) {
-      lines.push(`  ${context} ${colors.dim("·")} ${colors.bold(formatCount(count))}`);
-    }
+  // --- Model & lifecycle (tree) ---
+  const treeItems: TreeItem[] = [];
+  if (fleet.modelBreakdown.length > 0) {
+    treeItems.push({
+      text: `${colors.cyan("Models")} ${colors.dim(`(${fleet.modelBreakdown.length})`)}`,
+      children: fleet.modelBreakdown.map((m) => `${colors.bold(String(m.count))} ${m.model}`),
+    });
+  }
+  const lifecycleEntries = Object.entries(fleet.lifecycleBreakdown).filter(
+    ([, count]) => count > 0,
+  );
+  if (lifecycleEntries.length > 0) {
+    treeItems.push({
+      text: colors.cyan("Lifecycle"),
+      children: lifecycleEntries.map(([stage, count]) => `${colors.bold(String(count))} ${stage}`),
+    });
+  }
+  if (treeItems.length > 0) {
+    lines.push(formatTree(treeItems, { color: "gray", prefix: "  " }).trimEnd());
+  }
+
+  // --- Seed ---
+  if (input.seed !== undefined) {
+    const seedLine = input.seedExplicit
+      ? `Seed: ${colors.bold(String(input.seed))}`
+      : `Seed: ${colors.bold(String(input.seed))} ${colors.gray("(add seed to config to reproduce)")}`;
+    lines.push(seedLine);
+  }
+
+  // --- Top error contexts (tree) ---
+  if (input.errorContextCounts && input.errorContextCounts.size > 0) {
+    const topContexts = [...input.errorContextCounts.entries()]
+      .sort((a, b) => b[1] - a[1])
+      .slice(0, 5);
+    const errorItems: TreeItem[] = topContexts.map(
+      ([context, count]) => `${context} ${colors.dim("\u00B7")} ${colors.bold(formatCount(count))}`,
+    );
+    lines.push(`${colors.cyan("Top errors")}`);
+    lines.push(formatTree(errorItems, { color: "red", prefix: "  " }).trimEnd());
+  }
+
+  return lines;
+}
+
+/**
+ * Build a structured summary object for JSON log output.
+ */
+function buildJsonSummary(input: SummaryInput): Record<string, unknown> {
+  const { core, fleet, adapters } = input.metrics;
+
+  const adapterSummaries: Record<string, unknown>[] = [];
+  for (const adapter of adapters) {
+    const m = adapter.metrics;
+    const avgThroughput = computeAverageThroughput(m.messagesPublished, core.uptimeMs);
+    adapterSummaries.push({
+      name: adapter.name,
+      messagesPublished: m.messagesPublished,
+      errorsCount: m.errorsCount,
+      connected: m.connected,
+      ...(avgThroughput !== null ? { avgMsgPerSecond: avgThroughput } : {}),
+      ...(m.health
+        ? { health: { state: m.health.state, pendingWorkCount: m.health.pendingWorkCount } }
+        : {}),
+    });
+  }
+
+  const summary: Record<string, unknown> = {
+    uptimeMs: core.uptimeMs,
+    tickCount: core.tickCount,
+    ticksPerSecond: Number(core.actualTicksPerSecond.toFixed(1)),
+    simulationTimeSeconds: Number(core.simulationTimeSeconds.toFixed(1)),
+    instanceCount: core.instanceCount,
+    memberValueCount: core.memberValueCount,
+    engineErrorsCount: core.engineErrorsCount,
+    activeFaultCount: fleet.activeFaultCount,
+    quarantinedInstanceCount: core.quarantinedInstanceCount,
+    tickOverrunsCount: core.tickOverrunsCount,
+    circuitBreakerTripsCount: core.circuitBreakerTripsCount,
+    lifecycleBreakdown: fleet.lifecycleBreakdown,
+    adapters: adapterSummaries,
+  };
+
+  if (input.seed !== undefined) {
+    summary["seed"] = input.seed;
+    summary["seedExplicit"] = input.seedExplicit ?? false;
+  }
+
+  if (input.errorContextCounts && input.errorContextCounts.size > 0) {
+    const topContexts = [...input.errorContextCounts.entries()]
+      .sort((a, b) => b[1] - a[1])
+      .slice(0, 5);
+    summary["topErrorContexts"] = Object.fromEntries(topContexts);
+  }
+
+  return summary;
+}
+
+/**
+ * Render a summary box (or plain/JSON equivalent) with a given title.
+ * Shared renderer for shutdown and periodic summaries.
+ */
+export function printSummaryBox(title: string, input: SummaryInput, logLabel: string): void {
+  if (isSilent()) return;
+
+  if (isJsonLogFormat()) {
+    engineLog.info(logLabel, buildJsonSummary(input));
   }
 
+  const lines = buildSummaryLines(input);
+
   if (isPlain()) {
-    writeOutput("Shutdown Summary");
+    writeOutput(title);
     for (const line of lines) {
       writeOutput(`  ${line}`);
     }
@@ -164,8 +330,25 @@ function printShutdownSummary(
 
   writeOutput(
     box(lines.join("\n"), {
-      title: " Shutdown Summary ",
+      title: ` ${title} `,
       style: { borderColor: "gray", borderStyle: "rounded" },
     }),
   );
 }
+
+// ---------------------------------------------------------------------------
+// Shutdown-specific
+// ---------------------------------------------------------------------------
+
+function printShutdownSummary(
+  metrics: EngineMetricsSnapshot,
+  seed: number,
+  seedExplicit: boolean,
+  errorContextCounts?: ReadonlyMap<string, number>,
+): void {
+  printSummaryBox(
+    "Shutdown Summary",
+    { metrics, seed, seedExplicit, errorContextCounts },
+    "Shutdown summary",
+  );
+}

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.green,
   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