miravo 0.5.0 → 0.6.0

package/src/lib/shutdown.test.ts

@@ -141,6 +141,43 @@ describe("createShutdownController", () => {
     expect(exitCode).toBe(0);
   });
 
+  test("SIGTERM during graceful shutdown does not force-exit (parent runner cleanup)", async () => {
+    const engine = createMockEngine();
+    let exitCode: number | undefined;
+    let engineStopped = false;
+
+    (engine as unknown as Record<string, unknown>)["stop"] = () =>
+      new Promise<void>((resolve) =>
+        setTimeout(() => {
+          engineStopped = true;
+          resolve();
+        }, 50),
+      );
+
+    const controller = createShutdownController({
+      seed: 42,
+      seedExplicit: true,
+      exit: (code) => {
+        exitCode = code;
+      },
+    });
+    teardowns.push(controller.teardown);
+    controller.setEngine(engine);
+
+    process.emit("SIGINT");
+    await controller.waitForShutdownRequest();
+    const shutdownPromise = controller.runShutdown();
+    await new Promise((resolve) => setTimeout(resolve, 10));
+    // Simulate bun run / bunx forwarding SIGTERM to the child as the parent exits
+    process.emit("SIGTERM");
+    await controller.completion;
+    await shutdownPromise;
+
+    // Graceful shutdown must complete: engine stopped, exit(0), not force-stopped
+    expect(engineStopped).toBe(true);
+    expect(exitCode).toBe(0);
+  });
+
   test("second signal during shutdown calls exit(1)", async () => {
     const engine = createMockEngine();
     const exitCodes: number[] = [];
@@ -151,6 +188,7 @@ describe("createShutdownController", () => {
     const controller = createShutdownController({
       seed: 42,
       seedExplicit: true,
+      sigintCoalesceWindowMs: 20,
       exit: (code) => {
         exitCodes.push(code);
       },
@@ -161,12 +199,86 @@ describe("createShutdownController", () => {
     process.emit("SIGINT");
     await controller.waitForShutdownRequest();
     const shutdownPromise = controller.runShutdown();
-    await new Promise((resolve) => setTimeout(resolve, 10));
+    await new Promise((resolve) => setTimeout(resolve, 40));
     process.emit("SIGINT");
     await controller.completion;
     await shutdownPromise;
 
-    expect(exitCodes).toContain(1);
+    expect(exitCodes).toEqual([1]);
+  });
+
+  test("duplicate SIGINT from bun run does not force-exit on a single Ctrl+C", async () => {
+    const engine = createMockEngine();
+    let exitCode: number | undefined;
+    let engineStopped = false;
+
+    (engine as unknown as Record<string, unknown>)["stop"] = () =>
+      new Promise<void>((resolve) =>
+        setTimeout(() => {
+          engineStopped = true;
+          resolve();
+        }, 50),
+      );
+
+    const controller = createShutdownController({
+      seed: 42,
+      seedExplicit: true,
+      sigintCoalesceWindowMs: 20,
+      exit: (code) => {
+        exitCode = code;
+      },
+    });
+    teardowns.push(controller.teardown);
+    controller.setEngine(engine);
+
+    process.emit("SIGINT");
+    await controller.waitForShutdownRequest();
+    const shutdownPromise = controller.runShutdown();
+    // Regression: `bun run <script>` forwards a second SIGINT to its child
+    // immediately after the terminal already delivered SIGINT to the group.
+    process.emit("SIGINT");
+    await controller.completion;
+    await shutdownPromise;
+
+    expect(engineStopped).toBe(true);
+    expect(exitCode).toBe(0);
+  });
+
+  test("runShutdown() without prior requestShutdown() throws synchronously", () => {
+    const controller = createShutdownController({
+      seed: 1,
+      seedExplicit: true,
+      exit: () => {},
+    });
+    teardowns.push(controller.teardown);
+
+    expect(() => controller.runShutdown()).toThrow(
+      "Shutdown was not requested before runShutdown()",
+    );
+  });
+
+  test("duplicate requestShutdown before runShutdown is deduplicated (no force-exit)", async () => {
+    const engine = createMockEngine();
+    const exitCodes: number[] = [];
+
+    const controller = createShutdownController({
+      seed: 1,
+      seedExplicit: true,
+      exit: (code) => {
+        exitCodes.push(code);
+      },
+    });
+    teardowns.push(controller.teardown);
+    controller.setEngine(engine);
+
+    // First request via signal, second via direct API (simulating admin /shutdown race with SIGINT)
+    process.emit("SIGINT");
+    await controller.waitForShutdownRequest();
+    controller.requestShutdown("admin api"); // second call before runShutdown starts
+    await controller.runShutdown();
+
+    expect(exitCodes).toEqual([0]);
+    expect(engine.stopCalled).toBe(true);
   });
 
   test("shutdown request is inert until the owner runs shutdown", async () => {
@@ -195,6 +307,76 @@ describe("createShutdownController", () => {
     expect(stopCallCount).toBe(1);
   });
 
+  test("task that hangs past timeout: warns and shutdown continues", async () => {
+    const engine = createMockEngine();
+    const steps: string[] = [];
+    let exitCode: number | undefined;
+
+    const controller = createShutdownController({
+      seed: 1,
+      seedExplicit: true,
+      taskTimeoutMs: 30,
+      exit: (code) => {
+        exitCode = code;
+      },
+    });
+    teardowns.push(controller.teardown);
+    controller.setEngine(engine);
+
+    controller.addTask("cleanup", "hanging task", () => new Promise<void>(() => {}));
+    controller.addTask("finalize", "post-timeout step", () => {
+      steps.push("finalize ran");
+    });
+
+    process.emit("SIGINT");
+    await controller.waitForShutdownRequest();
+    await controller.runShutdown();
+
+    expect(steps).toEqual(["finalize ran"]);
+    expect(exitCode).toBe(0);
+  });
+
+  test("task that rejects after timeout does not cause unhandled rejection", async () => {
+    const engine = createMockEngine();
+    const unhandledReasons: unknown[] = [];
+    const onUnhandled = (reason: unknown) => {
+      unhandledReasons.push(reason);
+    };
+    process.on("unhandledRejection", onUnhandled);
+
+    try {
+      const controller = createShutdownController({
+        seed: 1,
+        seedExplicit: true,
+        taskTimeoutMs: 30,
+        exit: () => {},
+      });
+      teardowns.push(controller.teardown);
+      controller.setEngine(engine);
+
+      let rejectLate!: (err: Error) => void;
+      controller.addTask(
+        "cleanup",
+        "slow-then-reject",
+        () =>
+          new Promise<void>((_, reject) => {
+            rejectLate = reject;
+          }),
+      );
+
+      process.emit("SIGINT");
+      await controller.waitForShutdownRequest();
+      await controller.runShutdown(); // task times out after 30ms
+
+      rejectLate(new Error("late rejection after timeout"));
+      await new Promise((resolve) => setTimeout(resolve, 50));
+    } finally {
+      process.removeListener("unhandledRejection", onUnhandled);
+    }
+
+    expect(unhandledReasons).toHaveLength(0);
+  });
+
   test("teardown removes signal handlers", async () => {
     const engine = createMockEngine();
 

package/src/lib/shutdown.ts

@@ -3,21 +3,22 @@ import type { AdapterHealthSnapshot } from "@miravo/shared";
 import type { TreeItem } from "consola/utils";
 import { box, colors, formatTree, stripAnsi } from "consola/utils";
 import {
+  adapterLogger,
   engineLog,
   isJsonLogFormat,
   isPlain,
   isQuiet,
-  modbusLog,
-  mqttLog,
-  opcuaLog,
+  writeOutput,
 } from "../logger.ts";
-import { computeAverageThroughput, formatCount, formatDuration } from "../output.ts";
+import { computeAverageThroughput, formatCount, formatDuration, sep } from "../output.ts";
 
 const SHUTDOWN_TASK_TIMEOUT_MS = 6_000;
 const FINAL_OUTPUT_GRACE_MS = 50;
+const FORWARDED_SIGINT_COALESCE_WINDOW_MS = 100;
 
 type ShutdownTaskStage = "cleanup" | "finalize";
 type ShutdownPhase = "booting" | "running" | "shutting_down" | "forced_exit" | "exited";
+type ShutdownRequestSource = "api" | "sigint" | "sigterm";
 
 interface ShutdownTask {
   readonly name: string;
@@ -25,7 +26,7 @@ interface ShutdownTask {
 }
 
 /** Parameters for the shutdown controller. Supports dependency injection for tests. */
-export interface ShutdownControllerOptions {
+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). */
@@ -36,9 +37,13 @@ export interface ShutdownControllerOptions {
   readonly exit?: (code: number) => void;
   /** Optional writer override for the final shutdown summary render. */
   readonly writeFinalOutput?: (text: string) => Promise<void>;
+  /** Per-task timeout in ms. Defaults to SHUTDOWN_TASK_TIMEOUT_MS. Inject a small value in tests. */
+  readonly taskTimeoutMs?: number;
+  /** Duplicate SIGINT coalescing window in ms. Inject a small value in tests. */
+  readonly sigintCoalesceWindowMs?: number;
 }
 
-export interface ShutdownController {
+interface ShutdownController {
   readonly completion: Promise<void>;
   addTask(stage: ShutdownTaskStage, name: string, run: () => void | Promise<void>): void;
   isShuttingDown(): boolean;
@@ -62,13 +67,19 @@ export interface ShutdownController {
 export function createShutdownController(options: ShutdownControllerOptions): ShutdownController {
   const exit = options.exit ?? ((code: number) => process.exit(code));
   const writeFinalOutput = options.writeFinalOutput ?? writeShutdownOutput;
+  const taskTimeoutMs = options.taskTimeoutMs ?? SHUTDOWN_TASK_TIMEOUT_MS;
+  const sigintCoalesceWindowMs =
+    options.sigintCoalesceWindowMs ?? FORWARDED_SIGINT_COALESCE_WINDOW_MS;
 
   let phase: ShutdownPhase = "booting";
   let forcedExitRequested = false;
   let engine: Engine | null = null;
   let errorContextCounts = options.errorContextCounts;
   let requestedReason: string | null = null;
+  let requestSource: ShutdownRequestSource | null = null;
   let shutdownPromise: Promise<void> | null = null;
+  let requestedAtMs = 0;
+  let forwardedSigintIgnored = false;
 
   const tasks: Record<ShutdownTaskStage, ShutdownTask[]> = {
     cleanup: [],
@@ -85,9 +96,31 @@ export function createShutdownController(options: ShutdownControllerOptions): Sh
   });
 
   const keepAlive = setInterval(() => {}, 60_000);
+  const shouldIgnoreForwardedSigint = (): boolean => {
+    if (requestSource !== "sigint" || forwardedSigintIgnored) {
+      return false;
+    }
+    const elapsedMs = performance.now() - requestedAtMs;
+    if (elapsedMs > sigintCoalesceWindowMs) {
+      return false;
+    }
+    forwardedSigintIgnored = true;
+    engineLog.debug(`Ignoring duplicate SIGINT ${elapsedMs.toFixed(1)}ms after shutdown request.`);
+    return true;
+  };
+
   const forceSignalHandler = (): void => {
+    if (shouldIgnoreForwardedSigint()) {
+      return;
+    }
     forceExit();
   };
+  // Absorbs SIGTERM during graceful shutdown without terminating.
+  // bun run / bunx forwards SIGTERM to the child process when the parent
+  // runner receives SIGINT and exits — leaving SIGTERM unhandled would restore
+  // the OS default (abrupt termination). This no-op keeps the process alive
+  // long enough for cleanup tasks and engine.stop() to complete.
+  const absorbSigterm = (): void => {};
 
   const forceExit = (): void => {
     if (phase === "forced_exit" || phase === "exited") return;
@@ -101,14 +134,18 @@ export function createShutdownController(options: ShutdownControllerOptions): Sh
 
   const runWithTimeout = async (name: string, run: () => void | Promise<void>): Promise<void> => {
     let timer: ReturnType<typeof setTimeout> | null = null;
+    // Declared outside try so finally can suppress late rejections on timeout.
+    // Remains null if run() throws synchronously — no dangling promise in that case.
+    let runPromise: Promise<void> | null = null;
     try {
+      runPromise = Promise.resolve(run()); // sync throws are caught by this try block
       await Promise.race([
-        Promise.resolve(run()),
+        runPromise,
         new Promise<void>((resolve) => {
           timer = setTimeout(() => {
-            engineLog.warn(`${name} timed out after ${SHUTDOWN_TASK_TIMEOUT_MS / 1000}s.`);
+            engineLog.warn(`${name} timed out after ${taskTimeoutMs / 1000}s.`);
             resolve();
-          }, SHUTDOWN_TASK_TIMEOUT_MS);
+          }, taskTimeoutMs);
         }),
       ]);
     } catch (error) {
@@ -117,6 +154,10 @@ export function createShutdownController(options: ShutdownControllerOptions): Sh
       if (timer !== null) {
         clearTimeout(timer);
       }
+      // If the timeout fired first, runPromise is still pending. Attach a no-op
+      // catch so a future rejection from the dangling task does not become an
+      // unhandled-rejection crash.
+      runPromise?.catch(() => {});
     }
   };
 
@@ -173,27 +214,52 @@ export function createShutdownController(options: ShutdownControllerOptions): Sh
   const armForceExitHandlers = (): void => {
     process.removeListener("SIGINT", sigintHandler);
     process.removeListener("SIGTERM", sigtermHandler);
-    process.once("SIGINT", forceSignalHandler);
-    process.once("SIGTERM", forceSignalHandler);
+    // Use process.on (not once): under `bun run <script>` a single Ctrl+C sends
+    // SIGINT to the entire foreground process group, then Bun forwards the same
+    // SIGINT to its child process as well. The first duplicate is coalesced
+    // inside forceSignalHandler(); later SIGINTs still force-exit.
+    process.on("SIGINT", forceSignalHandler);
+    // SIGTERM is absorbed (no-op) rather than re-armed as a force handler.
+    // bun run / bunx forwards SIGTERM to the child process when the parent
+    // runner exits from its own SIGINT — leaving SIGTERM unhandled would
+    // restore the OS default (abrupt kill), so we absorb it instead and let
+    // cleanup tasks finish. A second Ctrl+C (SIGINT) still force-stops.
+    // Use process.on (not once): after the first SIGTERM is absorbed the listener
+    // must remain registered. If it were once, a second OS-level SIGTERM would
+    // find no handler and revert to the OS default (abrupt termination).
+    // teardown() removes it when shutdown completes.
+    process.on("SIGTERM", absorbSigterm);
   };
 
-  const requestShutdown = (reason: string): void => {
+  const requestShutdownInternal = (reason: string, source: ShutdownRequestSource): void => {
     if (phase === "forced_exit" || phase === "exited") return;
     if (requestedReason !== null) {
-      forceExit();
+      // Only force-exit if shutdown is actively running. A duplicate request
+      // that arrives before runShutdown() starts (e.g. admin /shutdown racing
+      // with SIGINT) is silently deduplicated — first caller wins.
+      if (phase === "shutting_down") {
+        forceExit();
+      }
       return;
     }
     requestedReason = reason;
+    requestSource = source;
+    requestedAtMs = performance.now();
+    forwardedSigintIgnored = false;
     resolveRequest(reason);
     armForceExitHandlers();
   };
 
+  const requestShutdown = (reason: string): void => {
+    requestShutdownInternal(reason, "api");
+  };
+
   const sigintHandler = (): void => {
-    requestShutdown("user interrupt");
+    requestShutdownInternal("user interrupt", "sigint");
   };
 
   const sigtermHandler = (): void => {
-    requestShutdown("SIGTERM");
+    requestShutdownInternal("SIGTERM", "sigterm");
   };
 
   process.once("SIGINT", sigintHandler);
@@ -233,7 +299,7 @@ export function createShutdownController(options: ShutdownControllerOptions): Sh
       process.removeListener("SIGINT", sigintHandler);
       process.removeListener("SIGTERM", sigtermHandler);
       process.removeListener("SIGINT", forceSignalHandler);
-      process.removeListener("SIGTERM", forceSignalHandler);
+      process.removeListener("SIGTERM", absorbSigterm);
       clearInterval(keepAlive);
     },
     waitForShutdownRequest() {
@@ -246,8 +312,6 @@ export function createShutdownController(options: ShutdownControllerOptions): Sh
 // Shared helpers
 // ---------------------------------------------------------------------------
 
-const sep = colors.dim(" \u00B7 ");
-
 interface SummaryInput {
   readonly metrics: EngineMetricsSnapshot;
   readonly seed?: number | undefined;
@@ -263,16 +327,13 @@ function healthStateLabel(state: AdapterHealthSnapshot["state"]): string {
       return colors.yellow(state);
     case "saturated":
       return colors.red(state);
+    default: {
+      const _exhaustive: never = state;
+      return _exhaustive;
+    }
   }
 }
 
-function adapterLogger(name: string) {
-  if (name === "mqtt") return mqttLog;
-  if (name === "opcua") return opcuaLog;
-  if (name === "modbus") return modbusLog;
-  return engineLog;
-}
-
 function adapterLabel(name: string): string {
   if (name === "opcua") return "OPC UA";
   if (name === "modbus") return "Modbus";
@@ -284,16 +345,14 @@ function formatAdapterLine(
   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 connStr = m.connected ? colors.green("✓") : colors.red("✗");
+  const verb = name === "opcua" || name === "modbus" ? "updates" : "published";
   const avgThroughput = computeAverageThroughput(m.messagesPublished, uptimeMs);
   const throughputStr = avgThroughput !== null ? `${sep}${formatCount(avgThroughput)} msg/s` : "";
-  const verb = name === "opcua" || name === "modbus" ? "updates" : "published";
+  const errStr =
+    m.errorsCount > 0 ? `${sep}${colors.yellow(formatCount(m.errorsCount))} errors` : "";
   const health = m.health ? `${sep}${healthStateLabel(m.health.state)}` : "";
-  return `${connStr}${sep}${formatCount(m.messagesPublished)} ${verb}${sep}${errStr} errors${throughputStr}${health}`;
+  return `${connStr} ${formatCount(m.messagesPublished)} ${verb}${throughputStr}${errStr}${health}`;
 }
 
 // ---------------------------------------------------------------------------
@@ -311,14 +370,15 @@ export function printSummaryLine(metrics: EngineMetricsSnapshot): void {
     return;
   }
 
+  // Blank line before each summary block to visually separate it from event lines
+  writeOutput();
+
   const { core, fleet, adapters } = metrics;
 
-  // Core stats
+  // Core stats — omit tick count (redundant with rate) and instance count (static, already in banner)
   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) {
@@ -557,5 +617,5 @@ async function writeToStream(stream: NodeJS.WriteStream, text: string): Promise<
 
 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));
+  await Bun.sleep(FINAL_OUTPUT_GRACE_MS);
 }

package/src/lib/template-category.ts

@@ -1,6 +1,6 @@
 import type { DiscoveredTemplate } from "@miravo/shared";
 
-export type TemplateCategory = "Industrial Scenarios" | "Stress & Benchmark";
+type TemplateCategory = "Industrial Scenarios" | "Stress & Benchmark";
 
 const CATEGORY_ORDER: readonly TemplateCategory[] = ["Industrial Scenarios", "Stress & Benchmark"];
 
@@ -16,7 +16,7 @@ export function categorizeTemplate(template: Pick<DiscoveredTemplate, "id">): Te
   return "Industrial Scenarios";
 }
 
-export function compareTemplatesByCategoryAndName(
+function compareTemplatesByCategoryAndName(
   a: Pick<DiscoveredTemplate, "id" | "name">,
   b: Pick<DiscoveredTemplate, "id" | "name">,
 ): number {
@@ -39,7 +39,7 @@ export function sortTemplatesByCategoryAndName<T extends Pick<DiscoveredTemplate
   return [...templates].sort(compareTemplatesByCategoryAndName);
 }
 
-export interface TemplateCategoryGroup<T extends Pick<DiscoveredTemplate, "id" | "name">> {
+interface TemplateCategoryGroup<T extends Pick<DiscoveredTemplate, "id" | "name">> {
   readonly category: TemplateCategory;
   readonly templates: readonly T[];
 }

package/src/lib/template-locator.ts

@@ -5,9 +5,15 @@ import { MiravoError, TEMPLATE_FILE_EXTENSION } from "@miravo/shared";
 /**
  * Create a ContentCatalog with default settings.
  * Shared across all CLI commands to ensure consistent resolution.
+ *
+ * @param opts.extraModelsDir - Optional extra directory scanned for .twin.yaml files
+ *   before the built-in catalog. Useful when template files live in a sibling
+ *   directory not on the default discovery path (e.g. --models-dir ./models).
  */
-export function createCatalog(): ContentCatalog {
-  return new ContentCatalog();
+export function createCatalog(opts: { extraModelsDir?: string } = {}): ContentCatalog {
+  return new ContentCatalog(
+    opts.extraModelsDir ? { extraModelsDirs: [resolve(opts.extraModelsDir)] } : undefined,
+  );
 }
 
 export function isTemplatePathLike(idNameOrPath: string): boolean {