miravo 0.1.4 → 0.2.1

package/src/lib/shutdown.ts

@@ -1,171 +1,551 @@
 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";
-
-/** Parameters for the shutdown handler. Supports dependency injection for tests. */
-export interface ShutdownOptions {
-  /** The running engine to stop. */
-  readonly engine: Engine;
+import type { AdapterHealthSnapshot } from "@miravo/shared";
+import type { TreeItem } from "consola/utils";
+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";
+
+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 shuttingDown = false;
-  let forcedExit = false;
+  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 forceExitHandler = (): void => {
-    if (forcedExit) return;
-    forcedExit = true;
-    engineLog.warn("Force stopping. Goodbye.");
-    exit(1);
+  const tasks: Record<ShutdownTaskStage, ShutdownTask[]> = {
+    cleanup: [],
+    finalize: [],
   };
 
-  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...");
+  let resolveCompletion = () => {};
+  const completion = new Promise<void>((resolve) => {
+    resolveCompletion = resolve;
+  });
+  let resolveRequest = (_reason: string) => {};
+  const request = new Promise<string>((resolve) => {
+    resolveRequest = resolve;
+  });
 
-    // Capture metrics before stop() clears bus listeners
-    const finalMetrics = engine.getMetrics();
+  const keepAlive = setInterval(() => {}, 60_000);
+  const forceSignalHandler = (): void => {
+    forceExit();
+  };
 
-    cleanup?.();
+  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);
+  };
 
-    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 {
-      mqttLog.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
       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 {
-        mqttLog.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);
       }
     }
+  };
 
-    if (forcedExit) {
-      return;
+  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++;
+    }
+  };
+
+  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);
     }
+  };
+
+  const armForceExitHandlers = (): void => {
+    process.removeListener("SIGINT", sigintHandler);
+    process.removeListener("SIGTERM", sigtermHandler);
+    process.once("SIGINT", forceSignalHandler);
+    process.once("SIGTERM", forceSignalHandler);
+  };
 
-    printShutdownSummary(finalMetrics, seed, seedExplicit, errorContextCounts);
-    exit(0);
+  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);
+  process.once("SIGINT", sigintHandler);
+  process.once("SIGTERM", sigtermHandler);
 
-  return () => {
-    process.removeListener("SIGINT", sigintHandler);
-    process.removeListener("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;
+    },
   };
 }
 
-function printShutdownSummary(
-  metrics: EngineMetricsSnapshot,
-  seed: number,
-  seedExplicit: boolean,
-  errorContextCounts?: ReadonlyMap<string, number>,
-): void {
+// ---------------------------------------------------------------------------
+// Shared helpers
+// ---------------------------------------------------------------------------
+
+const sep = colors.dim(" \u00B7 ");
+
+interface SummaryInput {
+  readonly metrics: EngineMetricsSnapshot;
+  readonly seed?: number | undefined;
+  readonly seedExplicit?: boolean | undefined;
+  readonly errorContextCounts?: ReadonlyMap<string, number> | undefined;
+}
+
+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);
+  }
+}
+
+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)
+// ---------------------------------------------------------------------------
+
+/**
+ * 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;
-  const mqttAdapter = adapters.find((a) => a.name === "mqtt");
 
-  const sep = colors.dim(" \u00B7 ");
+  // 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 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;
+  // Adapters
+  for (const adapter of adapters) {
+    const m = adapter.metrics;
+    const label = adapterLabel(adapter.name);
+    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 verb = adapter.name === "opcua" ? "updates" : "published";
     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}`,
     );
+    if (m.health) {
+      const pendingPrefix =
+        m.health.pendingWorkCount > 0
+          ? `${formatCount(m.health.pendingWorkCount)} pending${sep}`
+          : "";
+      lines.push(`  ${pendingPrefix}${healthStateLabel(m.health.state)}`);
+    }
   }
 
+  // Fleet health warnings
+  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
+  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))}`);
-    }
+  // Models & lifecycle
+  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
+  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;
+}
+
+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;
+}
+
+function renderSummaryText(title: string, input: SummaryInput): string {
+  const lines = buildSummaryLines(input);
+
   if (isPlain()) {
-    writeOutput("Shutdown Summary");
-    for (const line of lines) {
-      writeOutput(`  ${line}`);
-    }
-    writeOutput();
+    return [title, ...lines.map((line) => `  ${stripAnsi(line)}`), ""].join("\n");
+  }
+
+  return box(lines.join("\n"), {
+    title: ` ${title} `,
+    style: { borderColor: "gray", borderStyle: "rounded" },
+  });
+}
+
+async function printShutdownSummary(
+  metrics: EngineMetricsSnapshot,
+  seed: number,
+  seedExplicit: boolean,
+  errorContextCounts?: ReadonlyMap<string, number>,
+  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;
   }
 
-  writeOutput(
-    box(lines.join("\n"), {
-      title: " Shutdown Summary ",
-      style: { borderColor: "gray", borderStyle: "rounded" },
+  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));
+}