miravo 0.2.0 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "miravo",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "type": "module",
   "description": "Industrial environment platform with canonical asset models and MQTT + OPC UA protocol adapters",
   "license": "Apache-2.0",
@@ -31,10 +31,10 @@
   ],
   "dependencies": {
     "@clack/prompts": "^1.1.0",
-    "@miravo/core": "0.2.0",
-    "@miravo/mqtt": "0.2.0",
-    "@miravo/opcua": "0.2.0",
-    "@miravo/shared": "0.2.0",
+    "@miravo/core": "0.2.1",
+    "@miravo/mqtt": "0.2.1",
+    "@miravo/opcua": "0.2.1",
+    "@miravo/shared": "0.2.1",
     "commander": "^13.0.0",
     "consola": "^3.4.0",
     "mqtt": "^5.15.0"

package/src/commands/start.ts

@@ -35,7 +35,7 @@ import {
   parsePositiveFloat,
   parsePositiveInt,
 } from "../lib/parse.ts";
-import { installShutdownHandlers, printSummaryBox } from "../lib/shutdown.ts";
+import { createShutdownController, printSummaryLine } from "../lib/shutdown.ts";
 import {
   groupTemplatesByCategory,
   isStressBenchmarkTemplate,
@@ -156,8 +156,9 @@ export function registerStartCommand(program: Command): void {
 
 async function startAction(options: StartOptions): Promise<void> {
   let runtimeLogContextSet = false;
-  /** Adapter stop functions accumulated during setup. Drained on partial startup failure. */
-  const pendingAdapterStops: Array<() => Promise<void>> = [];
+  let shutdown: ReturnType<typeof createShutdownController> | null = null;
+  let engine: Engine | undefined;
+  let stopCliResources = (): void => {};
   try {
     const catalog = createCatalog();
 
@@ -307,31 +308,60 @@ async function startAction(options: StartOptions): Promise<void> {
     runtimeLogContextSet = true;
     controlLog.info(`Run ID: ${runId}`);
 
-    // Step 4: Create engine and populate
-    const engine = createAndPopulateEngine(
-      template,
-      models,
+    shutdown = createShutdownController({
       seed,
-      options,
-      templatePath,
-      simulationName,
-    );
+      seedExplicit,
+    });
+    const shutdownRequested = shutdown.waitForShutdownRequest();
+    shutdown.addTask("finalize", "runtime log context", () => {
+      if (runtimeLogContextSet) {
+        clearRuntimeLogContext();
+        runtimeLogContextSet = false;
+      }
+    });
+
+    // Step 4: Create engine and populate
+    engine = createAndPopulateEngine(template, models, seed, options, templatePath, simulationName);
+    shutdown.setEngine(engine);
+
+    let controlPlane: ControlPlane | null = null;
+    let adminServer: { endpoint: string; stop: () => void } | null = null;
+    let lastTickProgressAt = performance.now();
+    let tickProgressSubscribed = false;
+    const onTickProgress = (): void => {
+      lastTickProgressAt = performance.now();
+    };
+    let unsubscribeEvents = (): void => {};
+    let summaryTimer: ReturnType<typeof setInterval> | null = null;
+
+    stopCliResources = (): void => {
+      controlPlane?.stop();
+      adminServer?.stop();
+      if (summaryTimer !== null) {
+        clearInterval(summaryTimer);
+        summaryTimer = null;
+      }
+      if (tickProgressSubscribed && engine) {
+        engine.bus.off("tick:complete", onTickProgress);
+        tickProgressSubscribed = false;
+      }
+      unsubscribeEvents();
+    };
+
+    shutdown.addTask("cleanup", "CLI resources", stopCliResources);
 
     // Step 5: Start MQTT adapter (unless --no-mqtt)
     const mqttStartResult = mqttEnabled
       ? await startMQTTAdapter(engine, template, portOption, mqttOverrides, simulationName)
       : null;
     const adapter = mqttStartResult?.adapter ?? null;
-    if (adapter) pendingAdapterStops.push(() => adapter.stop());
 
     // Step 5a: Start OPC UA adapter (only when --opcua)
     const opcuaResult = opcuaEnabled
       ? await startOPCUAAdapter(engine, template, opcuaPort, opcuaHost, simulationName)
       : null;
-    if (opcuaResult) pendingAdapterStops.push(() => opcuaResult.adapter.stop());
 
     // Step 5b: Wire control plane
-    let controlPlane: ControlPlane | null = null;
     if (adapter) {
       const transport = adapter.getControlTransport();
       if (transport) {
@@ -347,12 +377,8 @@ async function startAction(options: StartOptions): Promise<void> {
     }
 
     // Step 5c: Start admin HTTP server
-    let adminServer: { endpoint: string; stop: () => void } | null = null;
-    let lastTickProgressAt = performance.now();
-    const onTickProgress = (): void => {
-      lastTickProgressAt = performance.now();
-    };
     engine.bus.on("tick:complete", onTickProgress);
+    tickProgressSubscribed = true;
     try {
       adminServer = startAdminServer({
         engine,
@@ -367,6 +393,7 @@ async function startAction(options: StartOptions): Promise<void> {
       });
       controlLog.info(`admin server ready · endpoint: ${colors.cyan(adminServer.endpoint)}`);
     } catch (error) {
+      tickProgressSubscribed = false;
       engine.bus.off("tick:complete", onTickProgress);
       const message = error instanceof Error ? error.message : String(error);
       throw new MiravoError(
@@ -390,46 +417,30 @@ async function startAction(options: StartOptions): Promise<void> {
 
     // Step 7: Subscribe to events + periodic summary
     const errorContextCounts = new Map<string, number>();
-    const unsubscribeEvents = subscribeToEvents(engine, errorContextCounts);
+    unsubscribeEvents = subscribeToEvents(engine, errorContextCounts);
+    shutdown.setErrorContextCounts(errorContextCounts);
     const summaryInterval = options.summaryInterval ?? 5;
-    const summaryTimer = startPeriodicSummary(engine, summaryInterval);
-
-    // Step 8: Install shutdown handler and start
-    const teardownShutdown = installShutdownHandlers({
-      engine,
-      seed,
-      seedExplicit,
-      cleanup: () => {
-        controlPlane?.stop();
-        adminServer?.stop();
-        engine.bus.off("tick:complete", onTickProgress);
-        clearInterval(summaryTimer);
-        unsubscribeEvents();
-        clearRuntimeLogContext();
-        runtimeLogContextSet = false;
-      },
-      errorContextCounts,
-    });
+    summaryTimer = startPeriodicSummary(engine, summaryInterval);
 
-    try {
-      engine.start();
-    } catch (error) {
-      teardownShutdown();
-      controlPlane?.stop();
-      adminServer?.stop();
-      engine.bus.off("tick:complete", onTickProgress);
-      clearInterval(summaryTimer);
-      unsubscribeEvents();
-      clearRuntimeLogContext();
-      runtimeLogContextSet = false;
-      throw error;
-    }
-    // Engine running — shutdown handlers now own adapter lifecycle
-    pendingAdapterStops.length = 0;
+    engine.start();
+    shutdown.markRunning();
     engineLog.success("Simulation started.");
+    await shutdownRequested;
+    await shutdown.runShutdown();
+    shutdown.teardown();
   } catch (error) {
-    // Stop adapters started before engine/shutdown handlers took ownership
-    await Promise.allSettled(pendingAdapterStops.map((fn) => fn()));
+    if (shutdown?.isShuttingDown()) {
+      await shutdown.runShutdown();
+      shutdown.teardown();
+      return;
+    }
+    shutdown?.teardown();
+    stopCliResources();
+    try {
+      await engine?.stop("boot error");
+    } catch {
+      // engine may not exist yet or stop may fail — swallow
+    }
     if (runtimeLogContextSet) {
       clearRuntimeLogContext();
       runtimeLogContextSet = false;
@@ -826,9 +837,7 @@ async function startMQTTAdapter(
       ...(mqttConfig?.metadata !== undefined ? { metadata: mqttConfig.metadata } : {}),
     };
 
-    await adapter.start({
-      ...resolvedConfig,
-    });
+    await adapter.start(resolvedConfig);
     engine.registerAdapter(adapter);
     mqttLog.ready(`connected · broker: ${colors.cyan(endpoint)}`);
     return { adapter, endpoint };
@@ -861,7 +870,6 @@ async function startOPCUAAdapter(
   opcuaLog.debug(`starting adapter · endpoint: opc.tcp://${host}:${port}`);
 
   const opcuaAdapter = new OPCUAAdapter(engine.bus, engine);
-
   try {
     const resolvedConfig = {
       name: "opcua" as const,
@@ -1009,7 +1017,7 @@ function subscribeToEvents(engine: Engine, errorContextCounts: Map<string, numbe
   };
 
   const onWarn = (event: { message: string; context: string }): void => {
-    engineLog.warn(event.message, { context: event.context });
+    engineLog.debug(event.message, { context: event.context });
   };
 
   const onError = (event: { context: string; error: Error }): void => {
@@ -1068,7 +1076,7 @@ function startPeriodicSummary(
 ): ReturnType<typeof setInterval> {
   return setInterval(() => {
     const metrics = engine.getMetrics();
-    printSummaryBox("Summary", { metrics }, "Periodic summary");
+    printSummaryLine(metrics);
   }, intervalSeconds * 1_000);
 }
 

package/src/index.ts

@@ -80,11 +80,35 @@ export function createProgram(): Command {
 
 // Only run when executed directly, not when imported in tests
 if (import.meta.path === Bun.main) {
-  // Import the generated manifest to trigger Bun's file embedding in compiled binaries.
+  // In compiled binaries, extract embedded content to a temp directory so
+  // ContentCatalog's filesystem-based discovery can find built-in models/templates.
   // The manifest only exists during `bun run build:standalone`; the catch is a no-op in dev.
   try {
     // @ts-expect-error — file is generated at build time and does not exist in source tree
-    await import("./_embedded-manifest.ts");
+    const manifest = await import("./_embedded-manifest.ts");
+    const { modelPaths, templatePaths } = manifest as {
+      modelPaths: string[];
+      templatePaths: string[];
+    };
+    const { basename, join } = await import("node:path");
+    const { tmpdir } = await import("node:os");
+    const { mkdirSync } = await import("node:fs");
+    const { registerEmbeddedContentDir } = await import("@miravo/core");
+
+    const contentDir = join(tmpdir(), "miravo-embedded");
+    const modelsDir = join(contentDir, "models");
+    const templatesDir = join(contentDir, "templates");
+    mkdirSync(modelsDir, { recursive: true });
+    mkdirSync(templatesDir, { recursive: true });
+
+    for (const p of modelPaths) {
+      await Bun.write(join(modelsDir, basename(p)), Bun.file(p));
+    }
+    for (const p of templatePaths) {
+      await Bun.write(join(templatesDir, basename(p)), Bun.file(p));
+    }
+
+    registerEmbeddedContentDir(contentDir);
   } catch {
     // Not a compiled binary or manifest not present — expected in dev mode
   }

package/src/lib/shutdown.test.ts

@@ -11,9 +11,52 @@ import {
   lockLogger,
   logger,
   mqttLog,
+  opcuaLog,
   unlockLogger,
 } from "../logger.ts";
-import { installShutdownHandlers } from "./shutdown.ts";
+import { createShutdownController } from "./shutdown.ts";
+
+const noopReporter = { log() {} };
+
+function configureSummaryLogger(
+  options: { plain?: boolean; logFormat?: "pretty" | "json" } = {},
+): void {
+  unlockLogger();
+  configureLogger({
+    plain: options.plain ?? false,
+    logFormat: options.logFormat ?? "pretty",
+  });
+  for (const l of [
+    logger,
+    engineLog,
+    mqttLog,
+    opcuaLog,
+    configLog,
+    lifecycleLog,
+    faultLog,
+    controlLog,
+  ]) {
+    l.level = -999;
+    l.setReporters([noopReporter]);
+  }
+  lockLogger();
+}
+
+function setStdoutIsTTY(value: boolean): () => void {
+  const descriptor = Object.getOwnPropertyDescriptor(process.stdout, "isTTY");
+  Object.defineProperty(process.stdout, "isTTY", {
+    configurable: true,
+    value,
+  });
+
+  return () => {
+    if (descriptor) {
+      Object.defineProperty(process.stdout, "isTTY", descriptor);
+      return;
+    }
+    delete (process.stdout as { isTTY?: boolean }).isTTY;
+  };
+}
 
 function createMockEngine(): Engine & { stopCalled: boolean; stopReason: string | undefined } {
   const metrics: EngineMetricsSnapshot = {
@@ -53,31 +96,33 @@ function createMockEngine(): Engine & { stopCalled: boolean; stopReason: string
   return mock;
 }
 
-describe("installShutdownHandlers", () => {
-  let teardown: (() => void) | undefined;
+describe("createShutdownController", () => {
+  const teardowns: Array<() => void> = [];
 
   afterEach(() => {
-    teardown?.();
-    teardown = undefined;
+    while (teardowns.length > 0) {
+      teardowns.pop()?.();
+    }
+    muteAllLoggers();
   });
 
   test("first SIGINT calls engine.stop and exit(0)", async () => {
     const engine = createMockEngine();
     let exitCode: number | undefined;
 
-    teardown = installShutdownHandlers({
-      engine,
+    const controller = createShutdownController({
       seed: 42,
       seedExplicit: true,
       exit: (code) => {
         exitCode = code;
       },
     });
+    teardowns.push(controller.teardown);
+    controller.setEngine(engine);
 
     process.emit("SIGINT");
-
-    // Allow async shutdown to complete
-    await new Promise((resolve) => setTimeout(resolve, 50));
+    await controller.waitForShutdownRequest();
+    await controller.runShutdown();
 
     expect(engine.stopCalled).toBe(true);
     expect(engine.stopReason).toBe("user interrupt");
@@ -88,153 +133,236 @@ describe("installShutdownHandlers", () => {
     const engine = createMockEngine();
     const exitCodes: number[] = [];
 
-    // Make stop() slow so we can fire a second signal during shutdown
     (engine as unknown as Record<string, unknown>)["stop"] = () =>
       new Promise((resolve) => setTimeout(resolve, 200));
 
-    teardown = installShutdownHandlers({
-      engine,
+    const controller = createShutdownController({
       seed: 42,
-      seedExplicit: false,
+      seedExplicit: true,
       exit: (code) => {
         exitCodes.push(code);
       },
     });
+    teardowns.push(controller.teardown);
+    controller.setEngine(engine);
 
-    // First signal starts shutdown
     process.emit("SIGINT");
-    // Brief delay to let shuttingDown be set
+    await controller.waitForShutdownRequest();
+    const shutdownPromise = controller.runShutdown();
     await new Promise((resolve) => setTimeout(resolve, 10));
-    // Second signal should force exit
     process.emit("SIGINT");
-
-    await new Promise((resolve) => setTimeout(resolve, 250));
+    await controller.completion;
+    await shutdownPromise;
 
     expect(exitCodes).toContain(1);
   });
 
-  test("engine.stop() throwing still exits 0", async () => {
+  test("shutdown request is inert until the owner runs shutdown", async () => {
     const engine = createMockEngine();
-    let exitCode: number | undefined;
+    let stopCallCount = 0;
 
-    // Make stop() throw
     (engine as unknown as Record<string, unknown>)["stop"] = async () => {
-      throw new Error("adapter disconnect");
+      stopCallCount++;
     };
 
-    teardown = installShutdownHandlers({
-      engine,
+    const controller = createShutdownController({
       seed: 1,
       seedExplicit: true,
-      exit: (code) => {
-        exitCode = code;
-      },
+      exit: () => {},
     });
+    teardowns.push(controller.teardown);
+    controller.setEngine(engine);
 
     process.emit("SIGINT");
-    await new Promise((resolve) => setTimeout(resolve, 50));
+    await controller.waitForShutdownRequest();
 
-    expect(exitCode).toBe(0);
+    expect(stopCallCount).toBe(0);
+
+    await controller.runShutdown();
+
+    expect(stopCallCount).toBe(1);
   });
 
-  test("concurrent SIGINT+SIGTERM only runs shutdown once", async () => {
+  test("teardown removes signal handlers", async () => {
     const engine = createMockEngine();
-    let stopCallCount = 0;
-
-    (engine as unknown as Record<string, unknown>)["stop"] = async () => {
-      stopCallCount++;
-    };
 
-    teardown = installShutdownHandlers({
-      engine,
+    const controller = createShutdownController({
       seed: 1,
       seedExplicit: true,
       exit: () => {},
     });
+    controller.setEngine(engine);
+    controller.teardown();
 
-    // Fire both signals nearly simultaneously
     process.emit("SIGINT");
-    process.emit("SIGTERM");
     await new Promise((resolve) => setTimeout(resolve, 50));
 
-    // The shuttingDown guard should prevent the second from starting a new shutdown
-    expect(stopCallCount).toBe(1);
+    expect(engine.stopCalled).toBe(false);
   });
 
-  test("teardown removes signal handlers", async () => {
+  test("runs cleanup before summary and exit", async () => {
     const engine = createMockEngine();
+    const steps: string[] = [];
+    configureSummaryLogger({ plain: false, logFormat: "pretty" });
 
-    teardown = installShutdownHandlers({
-      engine,
-      seed: 1,
+    const controller = createShutdownController({
+      seed: 42,
       seedExplicit: true,
-      exit: () => {},
+      writeFinalOutput: async () => {
+        steps.push("summary");
+      },
+      exit: () => {
+        steps.push("exit");
+      },
+    });
+    teardowns.push(controller.teardown);
+    controller.setEngine(engine);
+    controller.addTask("cleanup", "cleanup", async () => {
+      await new Promise((resolve) => setTimeout(resolve, 25));
+      steps.push("cleanup");
+    });
+    controller.addTask("finalize", "finalize", () => {
+      steps.push("finalize");
     });
 
-    // Remove handlers
-    teardown();
-    teardown = undefined;
-
-    // Fire SIGINT after teardown — our handler should NOT run.
-    // If handlers weren't removed, the mock engine would get stopped.
     process.emit("SIGINT");
-    await new Promise((resolve) => setTimeout(resolve, 50));
-    expect(engine.stopCalled).toBe(false);
+    await controller.waitForShutdownRequest();
+    await controller.runShutdown();
+
+    expect(steps).toEqual(["cleanup", "summary", "finalize", "exit"]);
   });
 
-  test("prints top 5 error contexts in shutdown summary", async () => {
+  test("cleanup failure does not suppress the shutdown summary", async () => {
     const engine = createMockEngine();
     let exitCode: number | undefined;
-    const originalLog = console.log;
-    const calls: string[] = [];
-    console.log = (...args: unknown[]) => {
-      calls.push(args.map((arg) => String(arg)).join(" "));
-    };
+    const renders: string[] = [];
 
-    // Enable writeOutput (plain mode, not suppressed) so the shutdown summary
-    // flows through console.log where we can capture it. Then mute consola
-    // reporters so engineLog/mqttLog don't leak to stdout.
-    unlockLogger();
-    configureLogger({ plain: true });
-    const noopReporter = { log() {} };
-    for (const l of [logger, engineLog, mqttLog, configLog, lifecycleLog, faultLog, controlLog]) {
-      l.level = -999;
-      l.setReporters([noopReporter]);
-    }
-    lockLogger();
+    configureSummaryLogger({ plain: false, logFormat: "pretty" });
+
+    const controller = createShutdownController({
+      seed: 42,
+      seedExplicit: true,
+      writeFinalOutput: async (text) => {
+        renders.push(text);
+      },
+      exit: (code) => {
+        exitCode = code;
+      },
+    });
+    teardowns.push(controller.teardown);
+    controller.setEngine(engine);
+    controller.addTask("cleanup", "cleanup", () => {
+      throw new Error("cleanup failed");
+    });
+
+    process.emit("SIGINT");
+    await controller.waitForShutdownRequest();
+    await controller.runShutdown();
+
+    expect(exitCode).toBe(0);
+    expect(renders).toHaveLength(1);
+    expect(renders[0]?.includes("Shutdown Summary")).toBe(true);
+  });
+
+  test("renders the rounded shutdown box in pretty mode even when stdout is not a TTY", async () => {
+    const engine = createMockEngine();
+    let exitCode: number | undefined;
+    const renders: string[] = [];
+    const restoreTTY = setStdoutIsTTY(false);
+    configureSummaryLogger({ plain: false, logFormat: "pretty" });
 
     try {
-      teardown = installShutdownHandlers({
-        engine,
+      const controller = createShutdownController({
         seed: 42,
         seedExplicit: true,
-        errorContextCounts: new Map([
-          ["mqtt:publish", 9],
-          ["tick-overrun", 7],
-          ["mqtt:backpressure", 5],
-          ["mqtt:reconnect", 3],
-          ['circuit-breaker instance="pump-001"', 2],
-          ["mqtt:client", 1],
-        ]),
+        writeFinalOutput: async (text) => {
+          renders.push(text);
+        },
         exit: (code) => {
           exitCode = code;
         },
       });
+      teardowns.push(controller.teardown);
+      controller.setEngine(engine);
 
       process.emit("SIGINT");
-      await new Promise((resolve) => setTimeout(resolve, 50));
+      await controller.waitForShutdownRequest();
+      await controller.runShutdown();
     } finally {
-      console.log = originalLog;
-      muteAllLoggers();
+      restoreTTY();
     }
 
     expect(exitCode).toBe(0);
-    expect(calls.some((line) => line.includes("Top errors"))).toBe(true);
-    expect(calls.some((line) => line.includes("mqtt:publish"))).toBe(true);
-    expect(calls.some((line) => line.includes("tick-overrun"))).toBe(true);
-    expect(calls.some((line) => line.includes("mqtt:backpressure"))).toBe(true);
-    expect(calls.some((line) => line.includes("mqtt:reconnect"))).toBe(true);
-    expect(calls.some((line) => line.includes('circuit-breaker instance="pump-001"'))).toBe(true);
-    expect(calls.some((line) => line.includes("mqtt:client"))).toBe(false);
+    expect(renders).toHaveLength(1);
+    expect(renders[0]?.includes("Shutdown Summary")).toBe(true);
+    expect(renders[0]?.includes("╭")).toBe(true);
+    expect(renders[0]?.includes("╰")).toBe(true);
+  });
+
+  test("keeps shutdown output plain when --plain is enabled", async () => {
+    const engine = createMockEngine();
+    const renders: string[] = [];
+    configureSummaryLogger({ plain: true, logFormat: "pretty" });
+
+    const controller = createShutdownController({
+      seed: 42,
+      seedExplicit: true,
+      writeFinalOutput: async (text) => {
+        renders.push(text);
+      },
+      exit: () => {},
+    });
+    teardowns.push(controller.teardown);
+    controller.setEngine(engine);
+
+    process.emit("SIGINT");
+    await controller.waitForShutdownRequest();
+    await controller.runShutdown();
+
+    expect(renders).toHaveLength(1);
+    expect(renders[0]?.startsWith("Shutdown Summary\n")).toBe(true);
+    expect(renders[0]?.includes("╭")).toBe(false);
+  });
+
+  test("prints top 5 error contexts in shutdown summary", async () => {
+    const engine = createMockEngine();
+    let exitCode: number | undefined;
+    const renders: string[] = [];
+    configureSummaryLogger({ plain: true, logFormat: "pretty" });
+
+    const controller = createShutdownController({
+      seed: 42,
+      seedExplicit: true,
+      errorContextCounts: new Map([
+        ["mqtt:publish", 9],
+        ["tick-overrun", 7],
+        ["mqtt:backpressure", 5],
+        ["mqtt:reconnect", 3],
+        ['circuit-breaker instance="pump-001"', 2],
+        ["mqtt:client", 1],
+      ]),
+      writeFinalOutput: async (text) => {
+        renders.push(text);
+      },
+      exit: (code) => {
+        exitCode = code;
+      },
+    });
+    teardowns.push(controller.teardown);
+    controller.setEngine(engine);
+
+    process.emit("SIGINT");
+    await controller.waitForShutdownRequest();
+    await controller.runShutdown();
+
+    const output = renders[0] ?? "";
+    expect(exitCode).toBe(0);
+    expect(output.includes("Top errors")).toBe(true);
+    expect(output.includes("mqtt:publish")).toBe(true);
+    expect(output.includes("tick-overrun")).toBe(true);
+    expect(output.includes("mqtt:backpressure")).toBe(true);
+    expect(output.includes("mqtt:reconnect")).toBe(true);
+    expect(output.includes('circuit-breaker instance="pump-001"')).toBe(true);
+    expect(output.includes("mqtt:client")).toBe(false);
   });
 });

package/src/lib/shutdown.ts

@@ -1,124 +1,245 @@
 import type { Engine, EngineMetricsSnapshot } from "@miravo/core";
 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 { box, colors, formatTree, stripAnsi } from "consola/utils";
+import { engineLog, isJsonLogFormat, isPlain, isSilent, mqttLog, opcuaLog } from "../logger.ts";
 import { computeAverageThroughput, formatCount, formatDuration } from "../output.ts";
 
-/** Parameters for the shutdown handler. Supports dependency injection for tests. */
-export interface ShutdownOptions {
-  /** The running engine to stop. */
-  readonly engine: Engine;
+const SHUTDOWN_TASK_TIMEOUT_MS = 6_000;
+const FINAL_OUTPUT_GRACE_MS = 50;
+
+type ShutdownTaskStage = "cleanup" | "finalize";
+type ShutdownPhase = "booting" | "running" | "shutting_down" | "forced_exit" | "exited";
+
+interface ShutdownTask {
+  readonly name: string;
+  readonly run: () => void | Promise<void>;
+}
+
+/** Parameters for the shutdown controller. Supports dependency injection for tests. */
+export interface ShutdownControllerOptions {
   /** The RNG seed used for this run (printed in summary for reproducibility). */
   readonly seed: number;
   /** Whether the seed was explicitly configured (vs. randomly generated). */
   readonly seedExplicit: boolean;
-  /** Optional cleanup callback for timers, intervals, etc. */
-  readonly cleanup?: () => void;
   /** Optional aggregated engine-error counts by context. */
   readonly errorContextCounts?: ReadonlyMap<string, number>;
   /** Process exit function. Defaults to process.exit. Inject for testing. */
   readonly exit?: (code: number) => void;
+  /** Optional writer override for the final shutdown summary render. */
+  readonly writeFinalOutput?: (text: string) => Promise<void>;
+}
+
+export interface ShutdownController {
+  readonly completion: Promise<void>;
+  addTask(stage: ShutdownTaskStage, name: string, run: () => void | Promise<void>): void;
+  isShuttingDown(): boolean;
+  markRunning(): void;
+  requestShutdown(reason: string): void;
+  runShutdown(): Promise<void>;
+  setEngine(engine: Engine): void;
+  setErrorContextCounts(counts: ReadonlyMap<string, number>): void;
+  teardown(): void;
+  waitForShutdownRequest(): Promise<string>;
 }
 
 /**
- * Install SIGINT and SIGTERM handlers for graceful shutdown.
- *
- * - First signal: stop engine, drain adapters, print summary, exit 0.
- * - Second signal during shutdown: force exit immediately with exit 1.
+ * Create a single-owner shutdown controller for `miravo start`.
  *
- * @returns A teardown function that removes the installed signal handlers.
+ * Signals are installed immediately. The controller owns the full shutdown
+ * lifecycle: pre-stop cleanup, engine stop, post-stop cleanup, final summary,
+ * and process exit. Callers should await `completion` to keep the command alive
+ * until shutdown fully finishes.
  */
-export function installShutdownHandlers(options: ShutdownOptions): () => void {
-  const { engine, seed, seedExplicit, cleanup, errorContextCounts } = options;
+export function createShutdownController(options: ShutdownControllerOptions): ShutdownController {
   const exit = options.exit ?? ((code: number) => process.exit(code));
+  const writeFinalOutput = options.writeFinalOutput ?? writeShutdownOutput;
+
+  let phase: ShutdownPhase = "booting";
+  let forcedExitRequested = false;
+  let engine: Engine | null = null;
+  let errorContextCounts = options.errorContextCounts;
+  let requestedReason: string | null = null;
+  let shutdownPromise: Promise<void> | null = null;
+
+  const tasks: Record<ShutdownTaskStage, ShutdownTask[]> = {
+    cleanup: [],
+    finalize: [],
+  };
 
-  let shuttingDown = false;
-  let forcedExit = false;
+  let resolveCompletion = () => {};
+  const completion = new Promise<void>((resolve) => {
+    resolveCompletion = resolve;
+  });
+  let resolveRequest = (_reason: string) => {};
+  const request = new Promise<string>((resolve) => {
+    resolveRequest = resolve;
+  });
+
+  const keepAlive = setInterval(() => {}, 60_000);
+  const forceSignalHandler = (): void => {
+    forceExit();
+  };
 
-  const forceExitHandler = (): void => {
-    if (forcedExit) return;
-    forcedExit = true;
+  const forceExit = (): void => {
+    if (phase === "forced_exit" || phase === "exited") return;
+    forcedExitRequested = true;
+    phase = "forced_exit";
+    clearInterval(keepAlive);
     engineLog.warn("Force stopping. Goodbye.");
+    resolveCompletion();
     exit(1);
   };
 
-  const handleSignal = async (signal: string): Promise<void> => {
-    // A second signal during shutdown should always force an immediate exit.
-    if (shuttingDown) {
-      forceExitHandler();
-      return;
-    }
-    shuttingDown = true;
-
-    engineLog.start("Stopping simulation...");
-
-    // Capture metrics before stop() clears bus listeners
-    const finalMetrics = engine.getMetrics();
-
-    let timedOut = false;
-    let timeoutHandle: ReturnType<typeof setTimeout> | null = null;
+  const runWithTimeout = async (name: string, run: () => void | Promise<void>): Promise<void> => {
+    let timer: ReturnType<typeof setTimeout> | null = null;
     try {
-      engineLog.start("Flushing pending messages (5s timeout)...");
-      const stopResult = engine.stop(signal === "SIGINT" ? "user interrupt" : signal);
-      // Suppress unhandled rejection if stop() rejects after timeout wins the race
-      stopResult.catch(() => {});
       await Promise.race([
-        stopResult,
+        Promise.resolve(run()),
         new Promise<void>((resolve) => {
-          timeoutHandle = setTimeout(() => {
-            timedOut = true;
+          timer = setTimeout(() => {
+            engineLog.warn(`${name} timed out after ${SHUTDOWN_TASK_TIMEOUT_MS / 1000}s.`);
             resolve();
-          }, 5_000);
+          }, SHUTDOWN_TASK_TIMEOUT_MS);
         }),
       ]);
-      if (timedOut) {
-        engineLog.warn("Engine stop timed out after 5s, proceeding with exit.");
-      } else {
-        engineLog.success("Stopped.");
-      }
-    } catch (err) {
-      engineLog.error("Error during shutdown:", err);
+    } catch (error) {
+      engineLog.error(`Error during ${name}:`, error);
     } finally {
-      if (timeoutHandle !== null) {
-        clearTimeout(timeoutHandle);
+      if (timer !== null) {
+        clearTimeout(timer);
       }
     }
+  };
 
-    // Clean up timers, admin server, and bus listeners AFTER engine.stop()
-    // so that adapter shutdown errors are still observable on the bus.
-    cleanup?.();
+  const runStage = async (stage: ShutdownTaskStage): Promise<void> => {
+    const stageTasks = tasks[stage];
+    let index = 0;
+    while (index < stageTasks.length) {
+      const task = stageTasks[index];
+      if (task !== undefined) {
+        await runWithTimeout(task.name, task.run);
+      }
+      index++;
+    }
+  };
 
-    if (forcedExit) {
-      return;
+  const shutdown = async (reason: string): Promise<void> => {
+    if (phase === "forced_exit" || phase === "exited") return;
+    phase = "shutting_down";
+    engineLog.info("Stopping simulation...");
+
+    const finalMetrics = engine?.getMetrics() ?? null;
+
+    await runStage("cleanup");
+
+    const engineToStop = engine;
+    if (engineToStop) {
+      await runWithTimeout("engine stop", () => engineToStop.stop(reason));
+    }
+
+    if (!forcedExitRequested && finalMetrics !== null) {
+      await printShutdownSummary(
+        finalMetrics,
+        options.seed,
+        options.seedExplicit,
+        errorContextCounts,
+        writeFinalOutput,
+      ).catch((error) => {
+        engineLog.error("Error rendering shutdown summary:", error);
+      });
+    }
+
+    await runStage("finalize");
+
+    const forced = forcedExitRequested;
+    clearInterval(keepAlive);
+    phase = "exited";
+    resolveCompletion();
+
+    if (!forced) {
+      exit(0);
     }
+  };
 
-    printShutdownSummary(finalMetrics, seed, seedExplicit, errorContextCounts);
-    Bun.stdout.writer().flush();
-    exit(0);
+  const armForceExitHandlers = (): void => {
+    process.removeListener("SIGINT", sigintHandler);
+    process.removeListener("SIGTERM", sigtermHandler);
+    process.once("SIGINT", forceSignalHandler);
+    process.once("SIGTERM", forceSignalHandler);
+  };
+
+  const requestShutdown = (reason: string): void => {
+    if (phase === "forced_exit" || phase === "exited") return;
+    if (requestedReason !== null) {
+      forceExit();
+      return;
+    }
+    requestedReason = reason;
+    resolveRequest(reason);
+    armForceExitHandlers();
   };
 
   const sigintHandler = (): void => {
-    void handleSignal("SIGINT");
+    requestShutdown("user interrupt");
   };
 
   const sigtermHandler = (): void => {
-    void handleSignal("SIGTERM");
+    requestShutdown("SIGTERM");
   };
 
-  process.on("SIGINT", sigintHandler);
-  process.on("SIGTERM", sigtermHandler);
-
-  return () => {
-    process.removeListener("SIGINT", sigintHandler);
-    process.removeListener("SIGTERM", sigtermHandler);
+  process.once("SIGINT", sigintHandler);
+  process.once("SIGTERM", sigtermHandler);
+
+  return {
+    completion,
+    addTask(stage, name, run) {
+      tasks[stage].push({ name, run });
+    },
+    isShuttingDown() {
+      return requestedReason !== null || phase === "shutting_down" || phase === "forced_exit";
+    },
+    markRunning() {
+      if (phase === "booting") {
+        phase = "running";
+      }
+    },
+    requestShutdown,
+    runShutdown() {
+      if (shutdownPromise) {
+        return shutdownPromise;
+      }
+      if (requestedReason === null) {
+        throw new Error("Shutdown was not requested before runShutdown().");
+      }
+      shutdownPromise = shutdown(requestedReason);
+      return shutdownPromise;
+    },
+    setEngine(nextEngine) {
+      engine = nextEngine;
+    },
+    setErrorContextCounts(counts) {
+      errorContextCounts = counts;
+    },
+    teardown() {
+      process.removeListener("SIGINT", sigintHandler);
+      process.removeListener("SIGTERM", sigtermHandler);
+      process.removeListener("SIGINT", forceSignalHandler);
+      process.removeListener("SIGTERM", forceSignalHandler);
+      clearInterval(keepAlive);
+    },
+    waitForShutdownRequest() {
+      return request;
+    },
   };
 }
 
 // ---------------------------------------------------------------------------
-// Shared summary rendering
+// Shared helpers
 // ---------------------------------------------------------------------------
 
+const sep = colors.dim(" \u00B7 ");
+
 interface SummaryInput {
   readonly metrics: EngineMetricsSnapshot;
   readonly seed?: number | undefined;
@@ -137,16 +258,81 @@ function healthStateLabel(state: AdapterHealthSnapshot["state"]): string {
   }
 }
 
+function adapterLogger(name: string) {
+  if (name === "mqtt") return mqttLog;
+  if (name === "opcua") return opcuaLog;
+  return engineLog;
+}
+
+function adapterLabel(name: string): string {
+  if (name === "opcua") return "OPC UA";
+  return name.toUpperCase();
+}
+
+function formatAdapterLine(
+  name: string,
+  m: EngineMetricsSnapshot["adapters"][number]["metrics"],
+  uptimeMs: number,
+): string {
+  const connStr = m.connected ? colors.green("connected") : colors.red("disconnected");
+  const errStr =
+    m.errorsCount === 0
+      ? colors.green(formatCount(m.errorsCount))
+      : colors.yellow(formatCount(m.errorsCount));
+  const avgThroughput = computeAverageThroughput(m.messagesPublished, uptimeMs);
+  const throughputStr = avgThroughput !== null ? `${sep}${formatCount(avgThroughput)} msg/s` : "";
+  const verb = name === "opcua" ? "updates" : "published";
+  const health = m.health ? `${sep}${healthStateLabel(m.health.state)}` : "";
+  return `${connStr}${sep}${formatCount(m.messagesPublished)} ${verb}${sep}${errStr} errors${throughputStr}${health}`;
+}
+
+// ---------------------------------------------------------------------------
+// Periodic summary (single-line per component)
+// ---------------------------------------------------------------------------
+
 /**
- * Build the pretty summary lines from an engine metrics snapshot.
- * Used by both the shutdown summary and periodic summary.
+ * Print a compact periodic summary: one line for core stats, one per adapter.
  */
+export function printSummaryLine(metrics: EngineMetricsSnapshot): void {
+  if (isSilent()) return;
+
+  if (isJsonLogFormat()) {
+    engineLog.info("Periodic summary", buildJsonSummary({ metrics }));
+    return;
+  }
+
+  const { core, fleet, adapters } = metrics;
+
+  // Core stats
+  const parts = [
+    formatDuration(core.uptimeMs),
+    `${formatCount(core.tickCount)} ticks`,
+    `${core.actualTicksPerSecond.toFixed(1)} ticks/s`,
+    `${formatCount(core.instanceCount)} instances`,
+    `${formatCount(core.memberValueCount)} data points`,
+  ];
+  if (fleet.activeFaultCount > 0) {
+    parts.push(`${colors.yellow(String(fleet.activeFaultCount))} faults`);
+  }
+  engineLog.info(parts.join(sep));
+
+  // Per-adapter line
+  for (const adapter of adapters) {
+    adapterLogger(adapter.name).info(
+      formatAdapterLine(adapter.name, adapter.metrics, core.uptimeMs),
+    );
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Shutdown summary (box)
+// ---------------------------------------------------------------------------
+
 function buildSummaryLines(input: SummaryInput): string[] {
   const { core, fleet, adapters } = input.metrics;
-  const sep = colors.dim(" \u00B7 ");
   const lines: string[] = [];
 
-  // --- Core stats ---
+  // Core stats
   lines.push(
     `${colors.bold(formatDuration(core.uptimeMs))}${sep}${colors.bold(formatCount(core.tickCount))} ticks${sep}${colors.bold(String(core.actualTicksPerSecond.toFixed(1)))} ticks/s`,
   );
@@ -154,11 +340,10 @@ function buildSummaryLines(input: SummaryInput): string[] {
     `${colors.bold(formatCount(core.instanceCount))} instances${sep}${colors.bold(formatCount(core.memberValueCount))} data points${sep}sim: ${colors.bold(core.simulationTimeSeconds.toFixed(1))}s`,
   );
 
-  // --- Protocol adapters ---
+  // 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 label = adapterLabel(adapter.name);
     const connStr = m.connected ? colors.green("connected") : colors.red("disconnected");
     const errStr =
       m.errorsCount === 0
@@ -166,21 +351,20 @@ function buildSummaryLines(input: SummaryInput): string[] {
         : 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` : "";
+    const verb = adapter.name === "opcua" ? "updates" : "published";
     lines.push(
-      `${label}: ${connStr}${sep}${colors.bold(formatCount(m.messagesPublished))} ${verb}${sep}${errStr} errors${throughputStr}${filteredStr}`,
+      `${label}: ${connStr}${sep}${colors.bold(formatCount(m.messagesPublished))} ${verb}${sep}${errStr} errors${throughputStr}`,
     );
-    // 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)}`);
+    if (m.health) {
+      const pendingPrefix =
+        m.health.pendingWorkCount > 0
+          ? `${formatCount(m.health.pendingWorkCount)} pending${sep}`
+          : "";
+      lines.push(`  ${pendingPrefix}${healthStateLabel(m.health.state)}`);
     }
   }
 
-  // --- Fleet health ---
+  // Fleet health warnings
   const healthParts: string[] = [];
   if (fleet.activeFaultCount > 0) {
     healthParts.push(`${colors.yellow(String(fleet.activeFaultCount))} active faults`);
@@ -201,7 +385,7 @@ function buildSummaryLines(input: SummaryInput): string[] {
     lines.push(healthParts.join(sep));
   }
 
-  // --- Fault breakdown (tree) ---
+  // Fault breakdown
   if (fleet.faultBreakdown.length > 0) {
     const faultItems: TreeItem[] = fleet.faultBreakdown.map(
       (f) => `${colors.yellow(String(f.count))} ${f.fault}`,
@@ -209,7 +393,7 @@ function buildSummaryLines(input: SummaryInput): string[] {
     lines.push(formatTree(faultItems, { color: "yellow", prefix: "  " }).trimEnd());
   }
 
-  // --- Model & lifecycle (tree) ---
+  // Models & lifecycle
   const treeItems: TreeItem[] = [];
   if (fleet.modelBreakdown.length > 0) {
     treeItems.push({
@@ -230,7 +414,7 @@ function buildSummaryLines(input: SummaryInput): string[] {
     lines.push(formatTree(treeItems, { color: "gray", prefix: "  " }).trimEnd());
   }
 
-  // --- Seed ---
+  // Seed
   if (input.seed !== undefined) {
     const seedLine = input.seedExplicit
       ? `Seed: ${colors.bold(String(input.seed))}`
@@ -238,7 +422,7 @@ function buildSummaryLines(input: SummaryInput): string[] {
     lines.push(seedLine);
   }
 
-  // --- Top error contexts (tree) ---
+  // Top error contexts
   if (input.errorContextCounts && input.errorContextCounts.size > 0) {
     const topContexts = [...input.errorContextCounts.entries()]
       .sort((a, b) => b[1] - a[1])
@@ -246,16 +430,13 @@ function buildSummaryLines(input: SummaryInput): string[] {
     const errorItems: TreeItem[] = topContexts.map(
       ([context, count]) => `${context} ${colors.dim("\u00B7")} ${colors.bold(formatCount(count))}`,
     );
-    lines.push(`${colors.cyan("Top errors")}`);
+    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;
 
@@ -306,49 +487,65 @@ function buildJsonSummary(input: SummaryInput): Record<string, unknown> {
   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));
-  }
-
+function renderSummaryText(title: string, input: SummaryInput): string {
   const lines = buildSummaryLines(input);
 
   if (isPlain()) {
-    writeOutput(title);
-    for (const line of lines) {
-      writeOutput(`  ${line}`);
-    }
-    writeOutput();
-    return;
+    return [title, ...lines.map((line) => `  ${stripAnsi(line)}`), ""].join("\n");
   }
 
-  writeOutput(
-    box(lines.join("\n"), {
-      title: ` ${title} `,
-      style: { borderColor: "gray", borderStyle: "rounded" },
-    }),
-  );
+  return box(lines.join("\n"), {
+    title: ` ${title} `,
+    style: { borderColor: "gray", borderStyle: "rounded" },
+  });
 }
 
-// ---------------------------------------------------------------------------
-// Shutdown-specific
-// ---------------------------------------------------------------------------
-
-function printShutdownSummary(
+async function printShutdownSummary(
   metrics: EngineMetricsSnapshot,
   seed: number,
   seedExplicit: boolean,
   errorContextCounts?: ReadonlyMap<string, number>,
-): void {
-  printSummaryBox(
-    "Shutdown Summary",
-    { metrics, seed, seedExplicit, errorContextCounts },
-    "Shutdown summary",
+  writeFinal: (text: string) => Promise<void> = writeShutdownOutput,
+): Promise<void> {
+  if (isSilent()) return;
+
+  if (isJsonLogFormat()) {
+    engineLog.info(
+      "Shutdown summary",
+      buildJsonSummary({ metrics, seed, seedExplicit, errorContextCounts }),
+    );
+    await flushOutputStreams();
+    return;
+  }
+
+  await writeFinal(
+    renderSummaryText("Shutdown Summary", {
+      metrics,
+      seed,
+      seedExplicit,
+      errorContextCounts,
+    }),
   );
 }
+
+async function writeShutdownOutput(text: string): Promise<void> {
+  await writeToStream(process.stdout, text.endsWith("\n") ? text : `${text}\n`);
+  await flushOutputStreams();
+}
+
+async function writeToStream(stream: NodeJS.WriteStream, text: string): Promise<void> {
+  await new Promise<void>((resolve, reject) => {
+    stream.write(text, (error?: Error | null) => {
+      if (error) {
+        reject(error);
+        return;
+      }
+      resolve();
+    });
+  });
+}
+
+async function flushOutputStreams(): Promise<void> {
+  await Promise.all([writeToStream(process.stdout, ""), writeToStream(process.stderr, "")]);
+  await new Promise<void>((resolve) => setTimeout(resolve, FINAL_OUTPUT_GRACE_MS));
+}

package/src/logger.ts

@@ -19,7 +19,7 @@ const LOG_LEVEL_MAP: Readonly<Record<LogLevel, number>> = {
 const TAG_COLORS: Readonly<Record<string, (s: string) => string>> = {
   engine: colors.cyan,
   mqtt: colors.green,
-  opcua: colors.green,
+  opcua: colors.blue,
   config: colors.yellow,
   lifecycle: colors.magenta,
   fault: colors.yellowBright,