miravo 0.4.0 → 0.6.0

package/src/commands/start/daemon.ts

@@ -0,0 +1,255 @@
+import { resolve } from "node:path";
+import {
+  DEFAULT_MODBUS_PORT,
+  DEFAULT_MQTT_PORT,
+  DEFAULT_OPCUA_PORT,
+  MiravoError,
+} from "@miravo/shared";
+import { colors } from "consola/utils";
+import type { DaemonRegistryEntry } from "../../lib/daemon-registry.ts";
+import {
+  acquireNameLock,
+  checkNameConflict,
+  checkPortConflicts,
+  displayHost,
+  isPidAlive,
+  writeEntry,
+} from "../../lib/daemon-registry.ts";
+import { controlLog, writeOutput } from "../../logger.ts";
+
+// ---------------------------------------------------------------------------
+// Detach mode — spawn background simulation
+// ---------------------------------------------------------------------------
+
+interface DetachOptions {
+  readonly simulationName: string;
+  readonly templatePath: string;
+  readonly seed: number;
+  readonly seedExplicit: boolean;
+  readonly adminHost: string;
+  readonly adminPort: number;
+  readonly mqttPort: number | undefined;
+  readonly mqttHost: string | undefined;
+  readonly mqttEmbedded: boolean;
+  readonly mqttEnabled: boolean;
+  readonly opcuaPort: number | undefined;
+  readonly opcuaHost: string | undefined;
+  readonly opcuaEnabled: boolean;
+  readonly modbusPort: number | undefined;
+  readonly modbusHost: string | undefined;
+  readonly modbusEnabled: boolean;
+}
+
+export async function detachAction(opts: DetachOptions): Promise<void> {
+  const { simulationName } = opts;
+
+  // 1. Acquire exclusive lock to prevent concurrent starts
+  const releaseLock = await acquireNameLock(simulationName);
+  try {
+    await detachActionLocked(opts, releaseLock);
+  } catch (error) {
+    await releaseLock();
+    throw error;
+  }
+}
+
+async function detachActionLocked(
+  opts: DetachOptions,
+  releaseLock: () => Promise<void>,
+): Promise<void> {
+  const { simulationName, adminHost, adminPort } = opts;
+
+  // 1. Check name conflict
+  const existing = await checkNameConflict(simulationName);
+  if (existing) {
+    throw new MiravoError(
+      `Simulation "${simulationName}" is already running (PID ${existing.pid}).`,
+      `Stop it first: miravo stop ${simulationName}`,
+    );
+  }
+
+  // 2. Check port conflicts
+  const ports = new Map<string, number>();
+  ports.set("admin", adminPort);
+  if (opts.mqttEnabled && opts.mqttEmbedded && opts.mqttPort !== undefined) {
+    ports.set("mqtt", opts.mqttPort);
+  }
+  if (opts.opcuaEnabled && opts.opcuaPort !== undefined) ports.set("opcua", opts.opcuaPort);
+  if (opts.modbusEnabled && opts.modbusPort !== undefined) ports.set("modbus", opts.modbusPort);
+
+  const conflicts = await checkPortConflicts(ports);
+  if (conflicts.length > 0) {
+    throw new MiravoError(
+      conflicts[0] ?? "Port conflict detected.",
+      "Use different port options or stop the conflicting simulation.",
+    );
+  }
+
+  // 3. Generate run ID and rebuild args
+  const runId = crypto.randomUUID();
+  const childArgs = rebuildArgsForDetach(opts);
+
+  // 4. Spawn child process
+  controlLog.info(`Starting simulation "${simulationName}" in background...`);
+  const proc = Bun.spawn({
+    cmd: [process.execPath, ...childArgs],
+    stdin: "ignore",
+    stdout: "ignore",
+    stderr: "ignore",
+    env: {
+      ...process.env,
+      MIRAVO_DAEMON_RUN_ID: runId,
+    },
+  });
+  proc.unref();
+
+  // 5. Poll for readiness
+  const adminUrl = `http://${adminHost}:${adminPort}`;
+  const ready = await pollReadiness(proc.pid, adminUrl, runId, 10, 1_000);
+
+  if (!ready) {
+    // Kill child if still alive
+    if (isPidAlive(proc.pid)) {
+      try {
+        process.kill(proc.pid, "SIGKILL");
+      } catch {
+        // Ignore kill errors
+      }
+    }
+
+    throw new MiravoError(
+      `Simulation "${simulationName}" failed to start within the readiness timeout.`,
+      "Check template and port availability. Run without -d to see full output.",
+    );
+  }
+
+  // 6. Write registry entry
+  const adapters: DaemonRegistryEntry["adapters"] = {};
+  if (opts.mqttEnabled) {
+    const mqttPort = opts.mqttPort ?? DEFAULT_MQTT_PORT;
+    adapters["mqtt"] = { port: mqttPort, host: opts.mqttHost ?? "0.0.0.0" };
+  }
+  if (opts.opcuaEnabled) {
+    const opcuaPort = opts.opcuaPort ?? DEFAULT_OPCUA_PORT;
+    adapters["opcua"] = { port: opcuaPort, host: opts.opcuaHost ?? "0.0.0.0" };
+  }
+  if (opts.modbusEnabled) {
+    const modbusPort = opts.modbusPort ?? DEFAULT_MODBUS_PORT;
+    adapters["modbus"] = { port: modbusPort, host: opts.modbusHost ?? "0.0.0.0" };
+  }
+
+  const entry: DaemonRegistryEntry = {
+    name: simulationName,
+    pid: proc.pid,
+    adminPort,
+    adminHost,
+    adapters,
+    templatePath: resolve(opts.templatePath),
+    startedAt: new Date().toISOString(),
+    seed: opts.seed,
+    runId,
+  };
+  try {
+    await writeEntry(entry);
+  } catch (err) {
+    // Registry write failed — kill the orphan child so it doesn't run invisible
+    // to miravo ps/stop/rm.
+    try {
+      process.kill(proc.pid, "SIGKILL");
+    } catch {
+      // Process may have already exited
+    }
+    throw err;
+  }
+  await releaseLock();
+
+  // 7. Print detach summary
+  printDetachSummary(entry);
+  process.exit(0);
+}
+
+function rebuildArgsForDetach(opts: DetachOptions): string[] {
+  // Start from the original argv, filtering out -d/--detach
+  const originalArgs = process.argv.slice(1); // skip bun/node executable
+  const filtered: string[] = [];
+  let hasName = false;
+  let hasSeed = false;
+
+  for (let i = 0; i < originalArgs.length; i++) {
+    const arg = originalArgs[i];
+    if (arg === undefined) continue;
+    if (arg === "-d" || arg === "--detach") continue;
+    if (arg === "-n" || arg === "--name") hasName = true;
+    if (arg === "--seed") hasSeed = true;
+    filtered.push(arg);
+  }
+
+  // Inject --name if not explicitly passed (ensures child uses same resolved name)
+  if (!hasName) {
+    filtered.push("--name", opts.simulationName);
+  }
+  // Inject --seed to freeze the seed (so child reproduces the same simulation)
+  if (!hasSeed) {
+    filtered.push("--seed", String(opts.seed));
+  }
+
+  return filtered;
+}
+
+async function pollReadiness(
+  pid: number,
+  adminUrl: string,
+  runId: string,
+  maxRetries: number,
+  intervalMs: number,
+): Promise<boolean> {
+  for (let attempt = 0; attempt < maxRetries; attempt++) {
+    await Bun.sleep(intervalMs);
+
+    if (!isPidAlive(pid)) return false;
+
+    try {
+      // Use /readyz to verify identity via runId. Accept any status (not just "ok")
+      // so external-MQTT daemons with slow broker reconnect can still start.
+      const response = await fetch(`${adminUrl}/readyz`, {
+        signal: AbortSignal.timeout(2_000),
+      });
+      const body = (await response.json()) as Record<string, unknown>;
+      if (body["runId"] === runId) return true;
+    } catch {
+      // Not ready yet — retry
+    }
+  }
+  return false;
+}
+
+function printDetachSummary(entry: DaemonRegistryEntry): void {
+  const admin = `http://${displayHost(entry.adminHost)}:${entry.adminPort}`;
+  const lines = [
+    `Simulation "${entry.name}" started in background (PID ${entry.pid})`,
+    "",
+    `  Console   ${admin}`,
+  ];
+
+  for (const [name, adapter] of Object.entries(entry.adapters) as [
+    string,
+    { port: number; host: string },
+  ][]) {
+    const host = displayHost(adapter.host);
+    if (name === "mqtt") {
+      lines.push(`  MQTT      mqtt://${host}:${adapter.port}`);
+    } else if (name === "opcua") {
+      lines.push(`  OPC UA    opc.tcp://${host}:${adapter.port}`);
+    } else if (name === "modbus") {
+      lines.push(`  Modbus    modbus://${host}:${adapter.port}`);
+    } else {
+      lines.push(`  ${name}      ${host}:${adapter.port}`);
+    }
+  }
+
+  lines.push("");
+  lines.push(`  Use ${colors.cyan(`miravo logs ${entry.name}`)} to view events`);
+  lines.push(`  Use ${colors.cyan(`miravo stop ${entry.name}`)} to stop`);
+
+  writeOutput(lines.join("\n"));
+}

package/src/commands/start/display.ts

@@ -0,0 +1,150 @@
+import { basename } from "node:path";
+import type { Engine } from "@miravo/core";
+import type { MiravoTemplate, TwinModel } from "@miravo/shared";
+import { MIRAVO_VERSION } from "@miravo/shared";
+import { box, colors } from "consola/utils";
+import { forEachTwin } from "../../lib/template-utils.ts";
+import { configLog, engineLog, isPlain, writeOutput } from "../../logger.ts";
+import { formatKeyValue, formatTable, sep } from "../../output.ts";
+
+// ---------------------------------------------------------------------------
+// Step 6: Startup banner
+// ---------------------------------------------------------------------------
+
+export function printStartupBanner(
+  templatePath: string,
+  engine: Engine,
+  seed: number,
+  seedExplicit: boolean,
+  mqttEndpoint: string | null,
+  opcuaEndpoint: string | null,
+  modbusEndpoint: string | null,
+  simulationName: string,
+  adminEndpoint: string,
+): void {
+  const state = engine.getState();
+  // Tier 1: identity — name, instance count, model count
+  const identity =
+    `    ${colors.bold(simulationName)}` +
+    `${sep}${colors.bold(String(state.instances.length))} instances` +
+    `${sep}${colors.bold(String(state.models.length))} models`;
+
+  // Tier 2: active endpoints only — disabled adapters are omitted
+  const endpointEntries: Array<readonly [string, string]> = [
+    [colors.dim("Admin"), colors.cyan(adminEndpoint)],
+  ];
+  if (mqttEndpoint) endpointEntries.push([colors.dim("MQTT"), colors.cyan(mqttEndpoint)]);
+  if (opcuaEndpoint) endpointEntries.push([colors.dim("OPC UA"), colors.cyan(opcuaEndpoint)]);
+  if (modbusEndpoint) endpointEntries.push([colors.dim("Modbus"), colors.cyan(modbusEndpoint)]);
+
+  // Tier 3: config footer — compact, all dimmed, one line
+  const seedStr = seedExplicit ? `seed ${seed}` : `seed ${seed} (random)`;
+  const configFooter = colors.dim(
+    `    ${basename(templatePath)} · ${state.config.tickIntervalMs}ms · ${state.config.timeMultiplier}x · ${seedStr}`,
+  );
+
+  const content = [identity, "", formatKeyValue(endpointEntries), "", configFooter].join("\n");
+  const header = `${colors.cyan(colors.bold("Miravo"))} ${colors.dim(`v${MIRAVO_VERSION}`)}`;
+
+  if (isPlain()) {
+    writeOutput(header);
+    writeOutput(content);
+    writeOutput();
+    engineLog.start("Press Ctrl+C to stop.");
+    return;
+  }
+
+  writeOutput(
+    box(content, {
+      title: header,
+      style: { borderColor: "cyan", borderStyle: "rounded" },
+    }),
+  );
+  engineLog.start("Press Ctrl+C to stop.");
+}
+
+// ---------------------------------------------------------------------------
+// Step 3: Dry-run summary
+// ---------------------------------------------------------------------------
+
+export function printDryRunSummary(
+  template: MiravoTemplate,
+  models: Map<string, TwinModel>,
+  seed: number,
+  seedExplicit: boolean,
+  templatePath: string,
+): void {
+  configLog.success("Dry-run validation passed.");
+
+  const seedValue = seedExplicit
+    ? colors.bold(String(seed))
+    : `${colors.bold(String(seed))} ${colors.gray("(random — add seed to config to reproduce)")}`;
+
+  const lines: string[] = [];
+
+  lines.push(
+    formatKeyValue([
+      [colors.dim("Template"), templatePath],
+      [colors.dim("Seed"), seedValue],
+    ]),
+  );
+
+  // Model table
+  const modelRows = [...models.values()].map((m) => ({
+    name: colors.cyan(m.model.name),
+    members: String(Object.keys(m.members).length),
+    faults: String(m.faults?.length ?? 0),
+    lifecycle: m.lifecycle ? `${m.lifecycle.stages.length} stages` : colors.dim("none"),
+  }));
+
+  if (modelRows.length > 0) {
+    lines.push("");
+    lines.push(`  ${colors.bold("Models:")}`);
+    lines.push(
+      formatTable(
+        {
+          name: colors.dim("Name"),
+          members: colors.dim("Members"),
+          faults: colors.dim("Faults"),
+          lifecycle: colors.dim("Lifecycle"),
+        },
+        modelRows,
+      ),
+    );
+  }
+
+  // Instance summary
+  let totalInstances = 0;
+  let totalMembers = 0;
+  forEachTwin(template, (_area, _line, twin) => {
+    totalInstances += twin.count;
+    const model = models.get(twin.model);
+    if (model) {
+      totalMembers += twin.count * Object.keys(model.members).length;
+    }
+  });
+
+  lines.push("");
+  lines.push(
+    formatKeyValue([
+      [colors.dim("Total instances"), colors.bold(String(totalInstances))],
+      [colors.dim("Total members"), colors.bold(String(totalMembers))],
+    ]),
+  );
+
+  if (isPlain()) {
+    writeOutput("Summary");
+    for (const line of lines) {
+      writeOutput(line);
+    }
+    writeOutput();
+    return;
+  }
+
+  writeOutput(
+    box(lines.join("\n"), {
+      title: " Summary ",
+      style: { borderColor: "cyan", borderStyle: "rounded" },
+    }),
+  );
+}

package/src/commands/start/engine-setup.ts

@@ -0,0 +1,247 @@
+import { resolve } from "node:path";
+import type { ContentCatalog, Engine } from "@miravo/core";
+import {
+  createEngine,
+  loadTemplate,
+  loadTwinModel,
+  resolveModelPath,
+  validateFullTemplate,
+} from "@miravo/core";
+import type { MiravoTemplate, TwinModel } from "@miravo/shared";
+import {
+  ConfigValidationError,
+  DEFAULT_TICK_INTERVAL_MS,
+  DEFAULT_TIME_MULTIPLIER,
+  SimulationNameSchema,
+} from "@miravo/shared";
+import {
+  buildUNSBasePath,
+  collectReferencedModels,
+  forEachTwin,
+} from "../../lib/template-utils.ts";
+import { configLog } from "../../logger.ts";
+import {
+  getCommandOptionSource,
+  reconcileProtocolBootPlan,
+  resolveProtocolBootPlans,
+} from "./protocol-plans.ts";
+import { loadTemplateModels, registerModelFromSearchPaths } from "./template-loader.ts";
+import type { StartOptions } from "./types.ts";
+
+// ---------------------------------------------------------------------------
+// Step 2: Load and validate
+// ---------------------------------------------------------------------------
+
+export async function loadAndValidateTemplate(
+  templatePath: string,
+  options: StartOptions,
+  catalog: ContentCatalog,
+): Promise<{
+  template: MiravoTemplate;
+  models: Map<string, TwinModel>;
+  seed: number;
+  seedExplicit: boolean;
+}> {
+  const template = await loadTemplate(templatePath);
+
+  // Build model search paths from catalog
+  const catalogSearchPaths = catalog.getTemplateValidationSearchPaths(templatePath);
+  const searchPaths = [...catalogSearchPaths];
+  if (options.modelsDir) {
+    // Insert after template dir but before other paths
+    searchPaths.splice(1, 0, resolve(options.modelsDir));
+  }
+  const uniqueSearchPaths = [...new Set(searchPaths.map((path) => resolve(path)))];
+
+  // Cross-validate
+  const validation = await validateFullTemplate(templatePath, uniqueSearchPaths);
+  for (const issue of validation.issues) {
+    if (issue.severity === "error") {
+      configLog.error(`${issue.message}\n  Fix: ${issue.fix}`);
+    } else {
+      configLog.warn(issue.message);
+    }
+  }
+  if (!validation.valid) {
+    throw new ConfigValidationError({
+      message: "Template validation failed. See errors above.",
+      fix: "Fix the reported issues and try again.",
+      filePath: templatePath,
+    });
+  }
+
+  // Build inline models map
+  const models = new Map<string, TwinModel>();
+  if (template.models) {
+    for (const inlineModel of template.models) {
+      models.set(inlineModel.model.name, inlineModel);
+    }
+  }
+
+  // Resolve and load all referenced models not already inline
+  const referencedModelNames = collectReferencedModels(template);
+
+  for (const modelName of referencedModelNames) {
+    if (models.has(modelName)) continue;
+    const modelPath = await resolveModelPath(modelName, uniqueSearchPaths);
+    const model = await loadTwinModel(modelPath);
+    models.set(modelName, model);
+  }
+
+  // Resolve seed: CLI flag > config setting > random
+  const configSeed = template.settings?.seed;
+  const cliSeed = options.seed;
+  const seedExplicit = cliSeed !== undefined || configSeed !== undefined;
+  const seed = cliSeed ?? configSeed ?? Date.now();
+
+  return { template, models, seed, seedExplicit };
+}
+
+export function resolveSimulationName(input: {
+  readonly template: MiravoTemplate;
+  readonly cliName?: string;
+  readonly envName?: string;
+}): string {
+  const { template, cliName, envName } = input;
+
+  const nameFromNamespace = (): string | undefined => {
+    const namespace = template.namespace;
+    if (!namespace) return undefined;
+    if ("enterprise" in namespace) {
+      return `${namespace.enterprise}-${namespace.site}`.toLowerCase();
+    }
+    return namespace.prefix.toLowerCase();
+  };
+
+  const rawName = cliName ?? envName ?? nameFromNamespace();
+  if (!rawName) {
+    throw new ConfigValidationError({
+      message: "Template has no namespace.",
+      fix: "Provide a simulation name via --name or MIRAVO_NAME.",
+    });
+  }
+
+  const parsed = SimulationNameSchema.safeParse(rawName);
+  if (!parsed.success) {
+    throw new ConfigValidationError({
+      message: `Invalid simulation name "${rawName}".`,
+      fix: "Use lowercase letters, numbers, and hyphens only (for example: north-plant).",
+    });
+  }
+
+  return parsed.data;
+}
+
+// ---------------------------------------------------------------------------
+// Step 4: Engine creation
+// ---------------------------------------------------------------------------
+
+export function createAndPopulateEngine(
+  template: MiravoTemplate,
+  models: Map<string, TwinModel>,
+  catalog: ContentCatalog,
+  seed: number,
+  options: StartOptions,
+  templatePath: string,
+  simulationName: string,
+): Engine {
+  const tickIntervalMs =
+    options.tick ?? template.settings?.tick_interval_ms ?? DEFAULT_TICK_INTERVAL_MS;
+  const timeMultiplier =
+    options.speed ?? template.settings?.time_multiplier ?? DEFAULT_TIME_MULTIPLIER;
+  const overrunThresholdMultiplier = template.settings?.overrun_threshold_multiplier;
+  const searchPaths = catalog.getTemplateValidationSearchPaths(templatePath);
+
+  let engine!: Engine;
+  engine = createEngine({
+    simulationName,
+    seed,
+    tickIntervalMs,
+    timeMultiplier,
+    overrunThresholdMultiplier,
+    templateMetadata: {
+      name: template.name,
+      path: templatePath,
+    },
+    beforeRun: async ({ restoredFromPersistence, persistedDisabledAdapters }) => {
+      const protocolBootPlans = resolveProtocolBootPlans({
+        options,
+        optionSources: {
+          mqtt: getCommandOptionSource(options.command, "mqtt"),
+          opcua: getCommandOptionSource(options.command, "opcua"),
+          mqttPort: getCommandOptionSource(options.command, "mqttPort"),
+          mqttHost: getCommandOptionSource(options.command, "mqttHost"),
+          mqttMode: getCommandOptionSource(options.command, "mqttMode"),
+          mqttUrl: getCommandOptionSource(options.command, "mqttUrl"),
+          mqttUsername: getCommandOptionSource(options.command, "mqttUsername"),
+          mqttPassword: getCommandOptionSource(options.command, "mqttPassword"),
+          opcuaPort: getCommandOptionSource(options.command, "opcuaPort"),
+          opcuaHost: getCommandOptionSource(options.command, "opcuaHost"),
+          modbus: getCommandOptionSource(options.command, "modbus"),
+          modbusPort: getCommandOptionSource(options.command, "modbusPort"),
+          modbusHost: getCommandOptionSource(options.command, "modbusHost"),
+        },
+        restoredFromPersistence,
+        persistedDisabledAdapters,
+        templateProtocols: template.protocols,
+      });
+
+      for (const plan of protocolBootPlans) {
+        await reconcileProtocolBootPlan(engine, plan);
+      }
+    },
+    persistence: {
+      enabled: true,
+      resetOnStart: options.resetState ?? false,
+      ensureModelRegistered: (modelName) =>
+        registerModelFromSearchPaths(engine.runtime, modelName, searchPaths),
+      loadTemplateModels: (persistedTemplatePath) => {
+        loadTemplateModels(catalog, persistedTemplatePath, engine.runtime);
+      },
+    },
+  });
+
+  // Register template-referenced models
+  for (const [, model] of models) {
+    engine.runtime.registerModel(model);
+  }
+
+  // Register all builtin models so they're available for ad-hoc spawning
+  const builtinDir = catalog.getBuiltinModelsDir();
+  for (const path of new Bun.Glob("*.twin.yaml").scanSync({ cwd: builtinDir })) {
+    const name = path.replace(".twin.yaml", "");
+    if (!engine.runtime.getModel(name)) {
+      registerModelFromSearchPaths(engine.runtime, name, searchPaths);
+    }
+  }
+
+  // Spawn instances from template with boot-time run ID
+  const bootRunId = 1;
+  const allInstanceIds: string[] = [];
+
+  forEachTwin(template, (area, line, twin) => {
+    const unsBasePath = buildUNSBasePath(template, area.name, line.name);
+    const spawned = engine.runtime.spawn(twin.model, twin.count, {
+      variation: twin.variation,
+      unsBasePath,
+      ...(twin.parameters !== undefined ? { parameterOverrides: twin.parameters } : {}),
+      ...(twin.starting_hours !== undefined ? { startingHours: twin.starting_hours } : {}),
+      templateRunId: bootRunId,
+    });
+    for (const node of spawned) {
+      allInstanceIds.push(node.id);
+    }
+  });
+
+  // Register boot-time template as a template run for persistence/unload support
+  engine.registerTemplateRun({
+    templateRunId: bootRunId,
+    templateName: template.name,
+    templatePath,
+    prefix: "boot",
+    instanceIds: allInstanceIds,
+    models: [...models.keys()],
+  });
+
+  return engine;
+}