miravo 0.6.0 → 0.6.1

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

@@ -1,247 +0,0 @@
-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;
-}

package/src/commands/start/events.ts

@@ -1,126 +0,0 @@
-import type { Engine } from "@miravo/core";
-import { colors } from "consola/utils";
-import { printSummaryLine } from "../../lib/shutdown.ts";
-import { engineLog, faultLog, lifecycleLog } from "../../logger.ts";
-
-/**
- * Shorten a full instance ID path to the last two segments for terminal output.
- * E.g. "area-1/line-2/pump-003" → "line-2/pump-003".
- * Full IDs can be 40+ chars with deep area/line/twin hierarchies.
- */
-function shortId(instanceId: string): string {
-  const parts = instanceId.split("/");
-  return parts.length > 2 ? parts.slice(-2).join("/") : instanceId;
-}
-
-// ---------------------------------------------------------------------------
-// Step 7: Event subscriptions + periodic summary
-// ---------------------------------------------------------------------------
-
-const MAX_ERROR_CONTEXT_KEYS = 256;
-const ERROR_CONTEXT_OVERFLOW = "__overflow__";
-
-export function subscribeToEvents(
-  engine: Engine,
-  errorContextCounts: Map<string, number>,
-): () => void {
-  const onLifecycle = (event: {
-    instanceId: string;
-    from: string;
-    to: string;
-    operatingHours: number;
-  }): void => {
-    lifecycleLog.info(
-      `${shortId(event.instanceId)} ${event.from} ${colors.dim("\u2192")} ${event.to} ${colors.gray(`(${event.operatingHours.toFixed(0)}h)`)}`,
-    );
-  };
-
-  const onFaultTriggered = (event: { instanceId: string; fault: string }): void => {
-    faultLog.warn(`${shortId(event.instanceId)} ${colors.bold(event.fault)} triggered`);
-  };
-
-  const onFaultCleared = (event: { instanceId: string; fault: string }): void => {
-    faultLog.info(`${shortId(event.instanceId)} ${colors.dim(event.fault)} cleared`);
-  };
-
-  const onWarn = (event: { message: string; context: string }): void => {
-    engineLog.debug(event.message, { context: event.context });
-  };
-
-  const onReset = (event: {
-    instanceCount: number;
-    templateRunCount: number;
-    clearPersistence: boolean;
-  }): void => {
-    const suffix = event.clearPersistence ? " · saved state cleared" : "";
-    engineLog.info(
-      `simulation reset · ${colors.bold(String(event.instanceCount))} instances · ${colors.bold(String(event.templateRunCount))} template runs${suffix}`,
-    );
-  };
-
-  const onError = (event: { context: string; error: Error }): void => {
-    incrementErrorContextCount(errorContextCounts, event.context);
-    engineLog.error(event.error.message, { context: event.context }, event.error);
-  };
-
-  const onStateChanged = (event: {
-    from: "idle" | "running" | "paused" | "stopped";
-    to: "idle" | "running" | "paused" | "stopped";
-  }): void => {
-    if (event.to === "paused") {
-      engineLog.info(`simulation paused`);
-    } else if (event.to === "running" && event.from === "paused") {
-      engineLog.info(`simulation resumed`);
-    }
-  };
-
-  engine.bus.on("lifecycle:changed", onLifecycle);
-  engine.bus.on("fault:triggered", onFaultTriggered);
-  engine.bus.on("fault:cleared", onFaultCleared);
-  engine.bus.on("engine:warn", onWarn);
-  engine.bus.on("engine:error", onError);
-  engine.bus.on("engine:reset", onReset);
-  engine.bus.on("engine:state-changed", onStateChanged);
-
-  return () => {
-    engine.bus.off("lifecycle:changed", onLifecycle);
-    engine.bus.off("fault:triggered", onFaultTriggered);
-    engine.bus.off("fault:cleared", onFaultCleared);
-    engine.bus.off("engine:warn", onWarn);
-    engine.bus.off("engine:error", onError);
-    engine.bus.off("engine:reset", onReset);
-    engine.bus.off("engine:state-changed", onStateChanged);
-  };
-}
-
-export function normalizeErrorContext(raw: string): string {
-  return raw
-    .replace(/tick=\d+/g, "tick=*")
-    .replace(/instance="[^"]+"/g, 'instance="*"')
-    .replace(/model="[^"]+"/g, 'model="*"');
-}
-
-export function incrementErrorContextCount(counts: Map<string, number>, rawContext: string): void {
-  const normalizedContext = normalizeErrorContext(rawContext);
-  if (counts.has(normalizedContext)) {
-    counts.set(normalizedContext, (counts.get(normalizedContext) ?? 0) + 1);
-    return;
-  }
-
-  if (counts.size < MAX_ERROR_CONTEXT_KEYS) {
-    counts.set(normalizedContext, 1);
-    return;
-  }
-
-  counts.set(ERROR_CONTEXT_OVERFLOW, (counts.get(ERROR_CONTEXT_OVERFLOW) ?? 0) + 1);
-}
-
-export function startPeriodicSummary(
-  engine: Engine,
-  intervalSeconds: number,
-): ReturnType<typeof setInterval> {
-  return setInterval(() => {
-    const metrics = engine.getMetrics();
-    printSummaryLine(metrics);
-  }, intervalSeconds * 1_000);
-}