miravo 0.4.0 → 0.6.0

package/src/commands/start/index.ts

@@ -0,0 +1,897 @@
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import type { ControlPlane, Engine } from "@miravo/core";
+import { createControlPlane } from "@miravo/core";
+import { ModbusAdapter } from "@miravo/modbus";
+import { MQTTAdapter } from "@miravo/mqtt";
+import { OPCUAAdapter } from "@miravo/opcua";
+import { ConfigValidationError, MiravoError } from "@miravo/shared";
+import type { Command } from "commander";
+import { colors } from "consola/utils";
+import { startAdminServer } from "../../lib/admin-server.ts";
+import { resolveAdminPassword, saveCredential } from "../../lib/auth-store.ts";
+import { buildDesiredStateFromTemplate } from "../../lib/le/le-static-planner.ts";
+import { buildLeExport } from "../../lib/le/le-template-exporter.ts";
+import {
+  parseDurationMs,
+  parseNonNegativeInt,
+  parsePort,
+  parsePositiveFloat,
+  parsePositiveInt,
+} from "../../lib/parse.ts";
+import { createSessionStore } from "../../lib/session-store.ts";
+import { createShutdownController } from "../../lib/shutdown.ts";
+import { createCatalog, resolveTemplateIdentifier } from "../../lib/template-locator.ts";
+import {
+  adapterLogger,
+  clearRuntimeLogContext,
+  configLog,
+  controlLog,
+  engineLog,
+  handleCommandError,
+  setRuntimeLogContext,
+} from "../../logger.ts";
+import {
+  buildModbusDefaultConfig,
+  buildModbusEndpoint,
+  buildMQTTDefaultConfig,
+  buildMQTTEndpoint,
+  buildOPCUADefaultConfig,
+  buildOPCUAEndpoint,
+  parseMqttModeOption,
+} from "./adapter-config.ts";
+import { buildLeDtJsonFromSchema } from "./catalog-le-dt.ts";
+import { buildModelSchemaFromYaml } from "./catalog-model-schema.ts";
+import { buildTemplateDetail } from "./catalog-template-detail.ts";
+import { detachAction } from "./daemon.ts";
+import { printDryRunSummary, printStartupBanner } from "./display.ts";
+import {
+  createAndPopulateEngine,
+  loadAndValidateTemplate,
+  resolveSimulationName,
+} from "./engine-setup.ts";
+import { startPeriodicSummary, subscribeToEvents } from "./events.ts";
+import { resolveDetachAdapterConfigs } from "./protocol-plans.ts";
+import { buildTemplateCacheAndCatalog, createRuntimeTemplateLoader } from "./template-loader.ts";
+import {
+  peekSingleStateTemplatePath,
+  peekStateTemplatePath,
+  resolveTemplatePath,
+} from "./template-resolver.ts";
+import type { MqttRunOverrides, RestoreSummary, StartOptions } from "./types.ts";
+
+export { resolveSimulationName } from "./engine-setup.ts";
+export { incrementErrorContextCount, normalizeErrorContext } from "./events.ts";
+export { resolveDetachAdapterConfigs, resolveProtocolBootPlans } from "./protocol-plans.ts";
+export { buildBuiltinTemplateChoices } from "./template-resolver.ts";
+
+/** Resolve the path to the built console dist directory. Returns undefined if not found. */
+function resolveConsoleDir(): string | undefined {
+  // 1. Compiled standalone binary: Bun.main resolves to a /$bunfs/ virtual path.
+  //    Look for console-dist/ packaged alongside the binary.
+  if (Bun.main.startsWith("/$bunfs/")) {
+    const binaryDir = new URL(".", `file://${process.execPath}`).pathname.replace(/\/$/, "");
+    const sibling = `${binaryDir}/console-dist`;
+    if (Bun.file(`${sibling}/index.html`).size > 0) return sibling;
+  }
+
+  // 2. Dev / Docker: resolve via workspace package (@miravo/console is a devDependency,
+  //    available in workspace but not when installed from npm).
+  try {
+    const resolved = import.meta.resolve("@miravo/console");
+    const resolvedDir = new URL(".", resolved).pathname.replace(/\/$/, "");
+    if (resolvedDir.endsWith("/dist")) return resolvedDir;
+    return `${resolvedDir}/dist`;
+  } catch {
+    // @miravo/console not installed (npm/bunx) — fall through
+  }
+
+  // 3. Docker / monorepo: workspace symlinks may not exist (production install).
+  //    index.ts is at packages/cli/src/commands/start/ → ../../../../console/dist
+  const monorepo = resolve(import.meta.dir, "..", "..", "..", "..", "console", "dist");
+  if (existsSync(`${monorepo}/index.html`)) return monorepo;
+
+  // 4. npm install / bunx: look for console-dist/ shipped inside the published package.
+  //    index.ts is at packages/cli/src/commands/start/ → ../../../console-dist/
+  const shipped = resolve(import.meta.dir, "..", "..", "..", "console-dist");
+  if (existsSync(`${shipped}/index.html`)) return shipped;
+
+  return undefined;
+}
+
+/**
+ * Register the `miravo start` command with the root Commander program.
+ * Resolves template, creates the engine, starts MQTT, and runs the simulation loop.
+ */
+export function registerStartCommand(program: Command): void {
+  program
+    .command("start")
+    .description("Start a simulation from a template")
+    .option("-n, --name <name>", "Simulation name (env: MIRAVO_NAME, flag takes precedence)")
+    .option(
+      "-t, --template <id|name|path,...>",
+      "Template id, name, path, or comma-separated list (env: MIRAVO_TEMPLATE, flag takes precedence)",
+    )
+    .option("--models-dir <path>", "Additional directory to search for .twin.yaml models")
+    .option("-s, --speed <multiplier>", "Time multiplier (default: 1)", parsePositiveFloat)
+    .option("--seed <number>", "RNG seed for deterministic simulation", parseNonNegativeInt)
+    .option("--tick <ms>", "Tick interval in milliseconds (default: 1000)", parseDurationMs)
+    .option(
+      "-p, --mqtt-port <number>",
+      "MQTT broker port (default: 1883, env: MIRAVO_MQTT_PORT)",
+      parsePort,
+    )
+    .option("--mqtt-host <host>", "MQTT bind host (default: 0.0.0.0, env: MIRAVO_MQTT_HOST)")
+    .option(
+      "--mqtt-mode <mode>",
+      "MQTT broker mode: embedded (local) | external (remote) (env: MIRAVO_MQTT_MODE)",
+    )
+    .option("--mqtt-url <url>", "External MQTT broker URL (env: MIRAVO_MQTT_URL)")
+    .option("--mqtt-username <username>", "External MQTT username (env: MIRAVO_MQTT_USERNAME)")
+    .option("--mqtt-password <password>", "External MQTT password (env: MIRAVO_MQTT_PASSWORD)")
+    .option("--no-mqtt", "Disable MQTT broker")
+    .option("--opcua", "Enable OPC UA server")
+    .option(
+      "--opcua-port <number>",
+      "OPC UA server port (default: 4840, env: MIRAVO_OPCUA_PORT)",
+      parsePort,
+    )
+    .option("--opcua-host <host>", "OPC UA server bind host (env: MIRAVO_OPCUA_HOST)")
+    .option("--modbus", "Enable Modbus TCP server adapter")
+    .option(
+      "--modbus-port <number>",
+      `Modbus TCP port (default: 502, env: MIRAVO_MODBUS_PORT)`,
+      parsePort,
+    )
+    .option("--modbus-host <host>", "Modbus TCP bind host (env: MIRAVO_MODBUS_HOST)")
+    .option("--admin-host <host>", "Admin server host (default: 0.0.0.0, env: MIRAVO_ADMIN_HOST)")
+    .option(
+      "--admin-port <number>",
+      "Admin server port (default: 8080, env: MIRAVO_ADMIN_PORT)",
+      parsePort,
+    )
+    .option("-d, --detach", "Start simulation in background (daemon mode)")
+    .option("--dry-run", "Validate config and print summary without starting")
+    .option("--no-ui", "Disable embedded admin console")
+    .option("--no-auth", "Disable authentication — all requests treated as authenticated")
+    .option("--reset-state", "Reset persisted state — start fresh (ignore any saved snapshot)")
+    .option(
+      "--summary-interval <seconds>",
+      "Seconds between periodic summary lines (default: 5)",
+      parsePositiveInt,
+    )
+    .addHelpText(
+      "after",
+      `
+Examples:
+  $ miravo start                                   Start with auto-detected template
+  $ miravo start -t water-treatment                Start a specific template
+  $ miravo start -t smart-factory,water-treatment  Start with two templates
+  $ miravo start -d --name my-sim                  Start in background (daemon mode)
+  $ miravo start -s 10 --seed 42                   Run at 10x speed with fixed seed
+  $ miravo start --no-mqtt --opcua                 Disable MQTT, enable OPC UA
+  $ miravo start --dry-run                         Validate and print summary only`,
+    )
+    .action(async (options: StartOptions, command: Command) => {
+      await startAction({ ...options, command });
+    });
+}
+
+// ---------------------------------------------------------------------------
+// Start action orchestration
+// ---------------------------------------------------------------------------
+
+async function startAction(options: StartOptions): Promise<void> {
+  let runtimeLogContextSet = false;
+  let shutdown: ReturnType<typeof createShutdownController> | null = null;
+  let engine: Engine | undefined;
+  let stopCliResources = (): void => {};
+  try {
+    const catalog = createCatalog();
+
+    // Resolve env-var fallbacks for common options
+    const templateOptionRaw = options.template ?? Bun.env["MIRAVO_TEMPLATE"];
+    // Support comma-separated template identifiers: first is the boot template, rest loaded after startup
+    const templateParts: string[] = templateOptionRaw
+      ? templateOptionRaw
+          .split(",")
+          .map((s) => s.trim())
+          .filter(Boolean)
+      : [];
+    const templateOption: string | undefined = templateParts[0];
+    const extraTemplateIdentifiers: string[] = templateParts.slice(1);
+    const simulationNameEnv = Bun.env["MIRAVO_NAME"];
+    // Protocol selection: CLI flags override, template.protocols used as fallback
+    const mqttEnabled = options.mqtt !== false; // --no-mqtt disables
+    let opcuaEnabled = options.opcua === true; // --opcua enables
+    let modbusEnabled = options.modbus === true; // --modbus enables
+
+    // Warn on ignored MQTT flags (MQTT status is known at CLI parse time)
+    if (!mqttEnabled) {
+      if (options.mqttPort !== undefined) {
+        configLog.warn("--mqtt-port ignored because MQTT is disabled.");
+      }
+      if (options.mqttHost !== undefined) {
+        configLog.warn("--mqtt-host ignored because MQTT is disabled.");
+      }
+      if (options.mqttMode !== undefined) {
+        configLog.warn("--mqtt-mode ignored because MQTT is disabled.");
+      }
+    }
+    // OPC UA / Modbus warnings are deferred to after template load (template.protocols may auto-enable)
+
+    const adminHost = options.adminHost ?? Bun.env["MIRAVO_ADMIN_HOST"] ?? "0.0.0.0";
+    const adminPortEnv = Bun.env["MIRAVO_ADMIN_PORT"];
+    if (adminHost.trim().length === 0) {
+      throw new ConfigValidationError({
+        message: "Invalid admin server host: value is empty.",
+        fix: "Set --admin-host / MIRAVO_ADMIN_HOST to a valid host (for example, 127.0.0.1 or 0.0.0.0).",
+      });
+    }
+
+    // MQTT env overrides — only parsed when MQTT is enabled
+    let portOption = options.mqttPort;
+    let mqttOverrides: MqttRunOverrides = {};
+    if (mqttEnabled) {
+      const portEnv = Bun.env["MIRAVO_MQTT_PORT"];
+      const mqttHost = options.mqttHost ?? Bun.env["MIRAVO_MQTT_HOST"];
+      const mqttMode = parseMqttModeOption(options.mqttMode ?? Bun.env["MIRAVO_MQTT_MODE"]);
+      const mqttUrl = options.mqttUrl ?? Bun.env["MIRAVO_MQTT_URL"];
+      const mqttUsername = options.mqttUsername ?? Bun.env["MIRAVO_MQTT_USERNAME"];
+      const mqttPassword = options.mqttPassword ?? Bun.env["MIRAVO_MQTT_PASSWORD"];
+      // Tuning env vars for adapter performance
+      const drainBudgetEnv = Bun.env["MIRAVO_MQTT_DRAIN_BUDGET"];
+      const batchSizeEnv = Bun.env["MIRAVO_MQTT_BATCH_SIZE"];
+      const brokerConcurrencyEnv = Bun.env["MIRAVO_MQTT_BROKER_CONCURRENCY"];
+      const drainBudget = drainBudgetEnv ? parsePositiveInt(drainBudgetEnv) : undefined;
+      const batchSize = batchSizeEnv ? parsePositiveInt(batchSizeEnv) : undefined;
+      const brokerConcurrency = brokerConcurrencyEnv
+        ? parsePositiveInt(brokerConcurrencyEnv)
+        : undefined;
+      mqttOverrides = {
+        ...(mqttMode !== undefined ? { mode: mqttMode } : {}),
+        ...(mqttHost !== undefined && mqttHost.length > 0 ? { host: mqttHost } : {}),
+        ...(mqttUrl !== undefined && mqttUrl.length > 0 ? { url: mqttUrl } : {}),
+        ...(mqttUsername !== undefined && mqttUsername.length > 0
+          ? { username: mqttUsername }
+          : {}),
+        ...(mqttPassword !== undefined && mqttPassword.length > 0
+          ? { password: mqttPassword }
+          : {}),
+        ...(drainBudget !== undefined ? { drainBudget } : {}),
+        ...(batchSize !== undefined ? { batchSize } : {}),
+        ...(brokerConcurrency !== undefined ? { brokerConcurrency } : {}),
+      };
+      if (portOption === undefined && portEnv) {
+        try {
+          portOption = parsePort(portEnv);
+        } catch {
+          throw new ConfigValidationError({
+            message: `Invalid MIRAVO_MQTT_PORT environment variable: "${portEnv}".`,
+            fix: "Set MIRAVO_MQTT_PORT to a valid port number between 1 and 65535 (for example, 1883).",
+          });
+        }
+      }
+      if (mqttHost !== undefined && mqttHost.trim().length === 0) {
+        throw new ConfigValidationError({
+          message: "Invalid MQTT bind host: value is empty.",
+          fix: "Set --mqtt-host / MIRAVO_MQTT_HOST to a valid host (for example, 127.0.0.1 or 0.0.0.0).",
+        });
+      }
+    }
+
+    // OPC UA env overrides — only parsed when OPC UA is enabled
+    let opcuaPort: number | undefined = options.opcuaPort;
+    let opcuaHost: string | undefined;
+    let opcuaWriteBudget: number | undefined;
+    if (opcuaEnabled) {
+      const opcuaPortEnv = Bun.env["MIRAVO_OPCUA_PORT"];
+      if (opcuaPort === undefined && opcuaPortEnv) {
+        try {
+          opcuaPort = parsePort(opcuaPortEnv);
+        } catch {
+          throw new ConfigValidationError({
+            message: `Invalid MIRAVO_OPCUA_PORT environment variable: "${opcuaPortEnv}".`,
+            fix: "Set MIRAVO_OPCUA_PORT to a valid port number between 1 and 65535 (for example, 4840).",
+          });
+        }
+      }
+      opcuaHost = options.opcuaHost ?? Bun.env["MIRAVO_OPCUA_HOST"] ?? undefined;
+      if (opcuaHost !== undefined && opcuaHost.trim().length === 0) {
+        throw new ConfigValidationError({
+          message: "Invalid OPC UA bind host: value is empty.",
+          fix: "Set --opcua-host / MIRAVO_OPCUA_HOST to a valid host (for example, 0.0.0.0).",
+        });
+      }
+      const writeBudgetEnv = Bun.env["MIRAVO_OPCUA_WRITE_BUDGET"];
+      if (writeBudgetEnv) {
+        opcuaWriteBudget = parsePositiveInt(writeBudgetEnv);
+      }
+    }
+
+    // Modbus env overrides — only parsed when Modbus is enabled
+    let modbusPort: number | undefined = options.modbusPort;
+    let modbusHost: string | undefined;
+    if (modbusEnabled) {
+      const modbusPortEnv = Bun.env["MIRAVO_MODBUS_PORT"];
+      if (modbusPort === undefined && modbusPortEnv) {
+        try {
+          modbusPort = parsePort(modbusPortEnv);
+        } catch {
+          throw new ConfigValidationError({
+            message: `Invalid MIRAVO_MODBUS_PORT environment variable: "${modbusPortEnv}".`,
+            fix: "Set MIRAVO_MODBUS_PORT to a valid port number between 0 and 65535.",
+          });
+        }
+      }
+      modbusHost = options.modbusHost ?? Bun.env["MIRAVO_MODBUS_HOST"] ?? undefined;
+      if (modbusHost !== undefined && modbusHost.trim().length === 0) {
+        throw new ConfigValidationError({
+          message: "Invalid Modbus TCP bind host: value is empty.",
+          fix: "Set --modbus-host / MIRAVO_MODBUS_HOST to a valid host (for example, 0.0.0.0 or 127.0.0.1).",
+        });
+      }
+    }
+
+    let adminPort = options.adminPort;
+    if (adminPort === undefined && adminPortEnv) {
+      try {
+        adminPort = parsePort(adminPortEnv);
+      } catch {
+        throw new ConfigValidationError({
+          message: `Invalid MIRAVO_ADMIN_PORT environment variable: "${adminPortEnv}".`,
+          fix: "Set MIRAVO_ADMIN_PORT to a valid port number between 1 and 65535 (for example, 8080).",
+        });
+      }
+    }
+    adminPort ??= 8080;
+
+    // Step 1: Resolve template path(s)
+    // If the simulation name is explicitly known and no template was given,
+    // peek at persisted state to recover the template path — skipping the
+    // interactive picker on resume.
+    let effectiveTemplateOption = templateOption;
+    if (!effectiveTemplateOption && !options.resetState) {
+      const knownName = options.name ?? simulationNameEnv;
+      if (knownName) {
+        // Named: peek by explicit simulation name
+        const peeked = await peekStateTemplatePath(knownName);
+        if (peeked) {
+          effectiveTemplateOption = peeked;
+          configLog.debug(`Resuming from persisted state: template=${peeked}`);
+        }
+      } else {
+        // Unnamed: scan state dir — auto-resume if exactly one simulation exists
+        const peeked = await peekSingleStateTemplatePath();
+        if (peeked) {
+          effectiveTemplateOption = peeked;
+          configLog.debug(`Resuming from persisted state: template=${peeked}`);
+        }
+      }
+    }
+    const templatePath = await resolveTemplatePath(effectiveTemplateOption, catalog);
+    configLog.debug(`Resolved template: ${templatePath}`);
+    // Resolve any additional comma-separated templates upfront so errors surface before engine start
+    const extraTemplatePaths = await Promise.all(
+      extraTemplateIdentifiers.map((id) => resolveTemplateIdentifier(id, catalog)),
+    );
+
+    // Step 2: Load and validate
+    const { template, models, seed, seedExplicit } = await loadAndValidateTemplate(
+      templatePath,
+      options,
+      catalog,
+    );
+    // Auto-enable protocols declared in template.protocols (unless user explicitly set flags)
+    if (template.protocols) {
+      if (template.protocols.opcua !== undefined && options.opcua === undefined) {
+        opcuaEnabled = true;
+        const opcuaPortEnv = Bun.env["MIRAVO_OPCUA_PORT"];
+        if (opcuaPort === undefined && opcuaPortEnv) {
+          try {
+            opcuaPort = parsePort(opcuaPortEnv);
+          } catch {
+            throw new ConfigValidationError({
+              message: `Invalid MIRAVO_OPCUA_PORT environment variable: "${opcuaPortEnv}".`,
+              fix: "Set MIRAVO_OPCUA_PORT to a valid port number between 1 and 65535 (for example, 4840).",
+            });
+          }
+        }
+        opcuaHost = opcuaHost ?? options.opcuaHost ?? Bun.env["MIRAVO_OPCUA_HOST"] ?? undefined;
+        const writeBudgetEnv = Bun.env["MIRAVO_OPCUA_WRITE_BUDGET"];
+        if (writeBudgetEnv && opcuaWriteBudget === undefined) {
+          opcuaWriteBudget = parsePositiveInt(writeBudgetEnv);
+        }
+      }
+      if (template.protocols.modbus !== undefined && options.modbus === undefined) {
+        modbusEnabled = true;
+        const modbusPortEnv = Bun.env["MIRAVO_MODBUS_PORT"];
+        if (modbusPort === undefined && modbusPortEnv) {
+          try {
+            modbusPort = parsePort(modbusPortEnv);
+          } catch {
+            throw new ConfigValidationError({
+              message: `Invalid MIRAVO_MODBUS_PORT environment variable: "${modbusPortEnv}".`,
+              fix: "Set MIRAVO_MODBUS_PORT to a valid port number between 0 and 65535.",
+            });
+          }
+        }
+        modbusHost = modbusHost ?? options.modbusHost ?? Bun.env["MIRAVO_MODBUS_HOST"] ?? undefined;
+      }
+      // MQTT is already enabled by default; template.protocols.mqtt only affects config (port/host)
+    }
+
+    // Deferred warnings for OPC UA / Modbus flags (now that template auto-enable has run)
+    if (!opcuaEnabled) {
+      if (options.opcuaPort !== undefined) {
+        configLog.warn(
+          "--opcua-port ignored because OPC UA is not enabled. Use --opcua to enable it.",
+        );
+      }
+      if (options.opcuaHost !== undefined) {
+        configLog.warn(
+          "--opcua-host ignored because OPC UA is not enabled. Use --opcua to enable it.",
+        );
+      }
+    }
+    if (!modbusEnabled) {
+      if (options.modbusPort !== undefined) {
+        configLog.warn(
+          "--modbus-port ignored because Modbus is not enabled. Use --modbus to enable it.",
+        );
+      }
+      if (options.modbusHost !== undefined) {
+        configLog.warn(
+          "--modbus-host ignored because Modbus is not enabled. Use --modbus to enable it.",
+        );
+      }
+    }
+
+    const simulationName = resolveSimulationName({
+      template,
+      ...(options.name !== undefined ? { cliName: options.name } : {}),
+      ...(simulationNameEnv !== undefined ? { envName: simulationNameEnv } : {}),
+    });
+    configLog.debug(`Loaded ${models.size} models, seed=${seed} (explicit=${seedExplicit})`);
+
+    // Step 3: Dry-run check
+    if (options.dryRun) {
+      printDryRunSummary(template, models, seed, seedExplicit, templatePath);
+      return;
+    }
+
+    // Step 3b: Detach check — spawn background process and exit
+    if (options.detach) {
+      const detachAdapterConfigs = resolveDetachAdapterConfigs({
+        template,
+        simulationName,
+        mqtt: {
+          enabled: mqttEnabled,
+          portOverride: portOption,
+          overrides: mqttOverrides,
+        },
+        opcua: {
+          enabled: opcuaEnabled,
+          portOverride: opcuaPort,
+          hostOverride: opcuaHost,
+          writeBudgetOverride: opcuaWriteBudget,
+        },
+        modbus: {
+          enabled: modbusEnabled,
+          portOverride: modbusPort,
+          hostOverride: modbusHost,
+        },
+      });
+
+      await detachAction({
+        simulationName,
+        templatePath,
+        seed,
+        seedExplicit,
+        adminHost,
+        adminPort,
+        mqttPort: detachAdapterConfigs.mqtt.port,
+        mqttHost: detachAdapterConfigs.mqtt.host,
+        mqttEmbedded: detachAdapterConfigs.mqtt.embedded,
+        mqttEnabled,
+        opcuaPort: detachAdapterConfigs.opcua.port,
+        opcuaHost: detachAdapterConfigs.opcua.host,
+        opcuaEnabled,
+        modbusPort: detachAdapterConfigs.modbus.port,
+        modbusHost: detachAdapterConfigs.modbus.host,
+        modbusEnabled,
+      });
+      return;
+    }
+
+    const runId = Bun.env["MIRAVO_DAEMON_RUN_ID"] ?? crypto.randomUUID();
+    setRuntimeLogContext({ simulationName, runId });
+    runtimeLogContextSet = true;
+
+    shutdown = createShutdownController({
+      seed,
+      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,
+      catalog,
+      seed,
+      options,
+      templatePath,
+      simulationName,
+    );
+    shutdown.setEngine(engine);
+
+    // Wire up template loader for runtime loadTemplate commands
+    // Single discovery pass builds both the path cache and catalog (avoids re-reading YAML)
+    const { pathCache: templatePathCache, catalog: catalogTemplates } =
+      await buildTemplateCacheAndCatalog(catalog);
+    engine.setTemplateLoader(createRuntimeTemplateLoader(catalog, templatePathCache));
+
+    // Load any additional comma-separated templates as extra template runs
+    for (const extraPath of extraTemplatePaths) {
+      const result = await engine.execute({
+        type: "loadTemplate",
+        templatePath: extraPath,
+        count: 1,
+      });
+      if (!result.success) {
+        throw new MiravoError(
+          `Failed to load additional template "${extraPath}": ${result.message}`,
+          result.error ?? "Check that the template is valid and compatible.",
+        );
+      }
+      configLog.info(`Loaded additional template: ${extraPath}`);
+    }
+
+    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 unsubscribeAdapterLogging = (): 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();
+      unsubscribeAdapterLogging();
+    };
+
+    shutdown.addTask("cleanup", "CLI resources", stopCliResources);
+
+    // Step 5: Register adapter factories and enable active adapters
+    // Track the last created MQTT adapter via closure (needed for control plane transport)
+    let lastCreatedMqttAdapter: MQTTAdapter | null = null;
+    const eng = engine; // const alias for closures (engine is `let` and TS can't narrow across closures)
+
+    const mqttDefaultConfig = buildMQTTDefaultConfig(
+      template,
+      portOption,
+      mqttOverrides,
+      simulationName,
+    );
+    eng.registerAvailableAdapter(
+      "mqtt",
+      async (config) => {
+        const adapter = new MQTTAdapter(eng.bus);
+        await adapter.start(config);
+        lastCreatedMqttAdapter = adapter;
+        return { adapter, endpoint: buildMQTTEndpoint(config) };
+      },
+      mqttDefaultConfig,
+    );
+
+    const opcuaDefaultConfig = buildOPCUADefaultConfig(
+      template,
+      opcuaPort,
+      opcuaHost,
+      simulationName,
+      opcuaWriteBudget,
+    );
+    eng.registerAvailableAdapter(
+      "opcua",
+      async (config) => {
+        const adapter = new OPCUAAdapter(eng.bus, eng);
+        await adapter.start(config);
+        return { adapter, endpoint: buildOPCUAEndpoint(config) };
+      },
+      opcuaDefaultConfig,
+    );
+
+    const modbusDefaultConfig = buildModbusDefaultConfig(template, modbusPort, modbusHost);
+    eng.registerAvailableAdapter(
+      "modbus",
+      async (config) => {
+        const adapter = new ModbusAdapter(eng.bus, eng);
+        await adapter.start(config);
+        return { adapter, endpoint: buildModbusEndpoint(config) };
+      },
+      modbusDefaultConfig,
+    );
+
+    // Step 5b: Wire control plane (dynamically follows MQTT adapter lifecycle)
+    function wireControlPlane(): void {
+      // Stop old control plane before creating a new one (prevents listener leaks)
+      if (controlPlane) {
+        controlPlane.stop();
+        controlPlane = null;
+      }
+      const mqttAdapter = lastCreatedMqttAdapter as MQTTAdapter | null;
+      if (!mqttAdapter) return;
+      const transport = mqttAdapter.getControlTransport();
+      if (!transport) return;
+      controlPlane = createControlPlane({
+        simulationName,
+        engine: eng,
+        transport,
+        bus: eng.bus,
+      });
+      controlPlane.start();
+      controlLog.info(`active on $miravo/${simulationName}/* topics`);
+    }
+
+    // Wire now if MQTT was enabled at boot
+    wireControlPlane();
+
+    // Re-wire control plane on runtime MQTT enable/disable.
+    // Logging is intentionally absent here — startup adapter events would duplicate the banner.
+    // Terminal logging for adapter state changes is registered after the banner (below).
+    eng.bus.on("adapter:enabled", (evt) => {
+      if (evt.name === "mqtt") wireControlPlane();
+    });
+    eng.bus.on("adapter:disabled", (evt) => {
+      if (evt.name === "mqtt") {
+        controlPlane?.stop();
+        controlPlane = null;
+        lastCreatedMqttAdapter = null;
+      }
+    });
+
+    // Step 5c: Subscribe to events + periodic summary before engine.start() so restore events are visible
+    const errorContextCounts = new Map<string, number>();
+    unsubscribeEvents = subscribeToEvents(eng, errorContextCounts);
+    shutdown.setErrorContextCounts(errorContextCounts);
+    const summaryInterval = options.summaryInterval ?? 5;
+    summaryTimer = startPeriodicSummary(eng, summaryInterval);
+
+    eng.bus.on("tick:complete", onTickProgress);
+    tickProgressSubscribed = true;
+
+    let restoredState: RestoreSummary | null = null;
+    const onRestored = (event: RestoreSummary): void => {
+      restoredState = event;
+    };
+    eng.bus.on("engine:restored", onRestored);
+    try {
+      await eng.start();
+    } finally {
+      eng.bus.off("engine:restored", onRestored);
+    }
+    // Step 6: Start admin HTTP server after restore + adapter reconciliation
+    try {
+      const anonymousMode = options.auth === false || Bun.env["MIRAVO_ANONYMOUS_LOGIN"] === "true";
+      const resolved = await resolveAdminPassword();
+      let currentHash = resolved.passwordHash;
+      let isDefault = resolved.isDefault;
+      const sessionStore = createSessionStore();
+
+      if (anonymousMode) {
+        controlLog.warn(
+          "Authentication disabled — all requests are unauthenticated. Do not expose this server publicly.",
+        );
+      }
+
+      if (isDefault && !anonymousMode) {
+        controlLog.warn("Using default admin password (admin/admin). Change it at first login.");
+      }
+
+      adminServer = startAdminServer({
+        engine: eng,
+        eventLog: eng.eventLog,
+        network: {
+          host: adminHost,
+          port: adminPort,
+          tickIntervalMs: eng.getState().config.tickIntervalMs,
+        },
+        protocols: {
+          getLastTickProgressAt: () => lastTickProgressAt,
+        },
+        ws: {
+          bus: eng.bus,
+        },
+        auth: {
+          verifyPassword: (pw) => Bun.password.verify(pw, currentHash),
+          get isDefaultPassword() {
+            return isDefault;
+          },
+          sessionStore,
+          changePassword: async (oldPw, newPw) => {
+            const valid = await Bun.password.verify(oldPw, currentHash);
+            if (!valid) throw new Error("Invalid old password.");
+            const newHash = await Bun.password.hash(newPw);
+            await saveCredential("admin", newHash);
+            currentHash = newHash;
+            isDefault = false;
+          },
+          anonymousMode,
+        },
+        consoleDir: options.ui === false ? undefined : resolveConsoleDir(),
+        getCatalog: () => catalogTemplates,
+        getCatalogModels: async () => {
+          const models = await catalog.listModels();
+          return models.map((m) => ({
+            name: m.name,
+            description: m.description ?? null,
+            memberCount: m.memberCount,
+            methodCount: m.methodCount,
+            faultCount: m.faultCount,
+            hasLifecycle: m.hasLifecycle,
+            lifecycleStageCount: m.lifecycleStageCount,
+            source: m.source.kind,
+          }));
+        },
+        getCatalogModelSchema: async (name) => {
+          try {
+            const path = await catalog.resolveModel(name);
+            return await buildModelSchemaFromYaml(path);
+          } catch {
+            return null;
+          }
+        },
+        getModelYaml: async (name) => {
+          try {
+            const path = await catalog.resolveModel(name);
+            return await Bun.file(path).text();
+          } catch {
+            return null;
+          }
+        },
+        getLeDtJson: async (name) => {
+          try {
+            const path = await catalog.resolveModel(name);
+            const schema = await buildModelSchemaFromYaml(path);
+            return buildLeDtJsonFromSchema(schema);
+          } catch {
+            return null;
+          }
+        },
+        getLeExport: async (id, { host, protocol }) => {
+          const base = catalogTemplates.find((t) => t.id === id);
+          if (!base) return null;
+          try {
+            const path = await catalog.resolveTemplate(id);
+            const { templateId, desired } = await buildDesiredStateFromTemplate({
+              templatePath: path,
+              catalog,
+              sourceHostname: host,
+              protocol,
+            });
+            return buildLeExport(desired, templateId);
+          } catch {
+            return null;
+          }
+        },
+        getTemplateDetail: async (id) => {
+          const base = catalogTemplates.find((t) => t.id === id);
+          if (!base) return null;
+          try {
+            const path = await catalog.resolveTemplate(id);
+            return await buildTemplateDetail(path, base);
+          } catch {
+            return null;
+          }
+        },
+        getTemplateYaml: async (id) => {
+          try {
+            const path = await catalog.resolveTemplate(id);
+            return await Bun.file(path).text();
+          } catch {
+            return null;
+          }
+        },
+        simulationName,
+        runId,
+        requestShutdown: (reason) => shutdown?.requestShutdown(reason),
+      });
+      controlLog.info(`admin server ready · endpoint: ${colors.cyan(adminServer.endpoint)}`);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      throw new MiravoError(
+        `Admin server failed to start on ${adminHost}:${adminPort}: ${message}`,
+        "Set --admin-port / MIRAVO_ADMIN_PORT to a free port, or change --admin-host.",
+      );
+    }
+
+    // Step 7: Print startup banner from the post-restore runtime state
+    const availableAdapters = eng.getAvailableAdapters();
+    const mqttEndpoint =
+      availableAdapters.find((a) => a.name === "mqtt" && a.enabled)?.endpoint ?? null;
+    const opcuaEndpoint =
+      availableAdapters.find((a) => a.name === "opcua" && a.enabled)?.endpoint ?? null;
+    const modbusEndpoint =
+      availableAdapters.find((a) => a.name === "modbus" && a.enabled)?.endpoint ?? null;
+    printStartupBanner(
+      templatePath,
+      eng,
+      seed,
+      seedExplicit,
+      mqttEndpoint,
+      opcuaEndpoint,
+      modbusEndpoint,
+      simulationName,
+      adminServer.endpoint,
+    );
+
+    // Register adapter logging after the banner — events from here on are runtime toggles,
+    // not startup initialisation that would duplicate what the banner already shows.
+    const onAdapterEnabled = (evt: { name: string; endpoint: string }): void => {
+      adapterLogger(evt.name).info(`enabled · ${colors.cyan(evt.endpoint)}`);
+    };
+    const onAdapterDisabled = (evt: { name: string }): void => {
+      adapterLogger(evt.name).info("disabled");
+      if (evt.name === "mqtt") controlLog.info("control plane stopped");
+    };
+    eng.bus.on("adapter:enabled", onAdapterEnabled);
+    eng.bus.on("adapter:disabled", onAdapterDisabled);
+    unsubscribeAdapterLogging = (): void => {
+      eng.bus.off("adapter:enabled", onAdapterEnabled);
+      eng.bus.off("adapter:disabled", onAdapterDisabled);
+    };
+
+    const restoreSummary = restoredState as RestoreSummary | null;
+    if (restoreSummary !== null) {
+      engineLog.info(
+        `restored saved state · ${colors.bold(String(restoreSummary.instanceCount))} instances · ${colors.bold(String(restoreSummary.templateRunCount))} template runs · ${colors.bold(String(restoreSummary.adapterCount))} adapters · ${colors.cyan(restoreSummary.stateFilePath)}`,
+      );
+    } else if (options.resetState) {
+      engineLog.info("starting fresh (--reset-state)");
+    }
+
+    shutdown.markRunning();
+    engineLog.success("Simulation started.");
+    await shutdownRequested;
+    await shutdown.runShutdown();
+    shutdown.teardown();
+  } catch (error) {
+    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;
+    }
+    handleCommandError(error);
+  }
+}