miravo 0.2.2 → 0.3.0

package/src/lib/daemon-registry.ts

@@ -0,0 +1,345 @@
+/**
+ * Daemon registry — tracks background simulation processes.
+ *
+ * Each background simulation gets a JSON entry at `~/.miravo/daemon/<name>.json`.
+ * Management commands (ps, stop, logs, rm) use this registry to discover and
+ * interact with running simulations via their admin HTTP server.
+ */
+
+import { mkdir, open, readdir, rename, unlink } from "node:fs/promises";
+import { resolveMiravoHome } from "@miravo/core";
+import { MiravoError, SimulationNameSchema } from "@miravo/shared";
+import { z } from "zod";
+
+// ---------------------------------------------------------------------------
+// Schema (CLI-only — not in packages/shared/)
+// ---------------------------------------------------------------------------
+
+const DaemonAdapterEntrySchema = z.object({
+  port: z.number().int().positive(),
+  host: z.string().min(1),
+});
+
+const DaemonRegistryEntrySchema = z.object({
+  name: z.string().min(1),
+  pid: z.number().int().positive(),
+  adminPort: z.number().int().positive(),
+  adminHost: z.string().min(1),
+  adapters: z.record(z.string(), DaemonAdapterEntrySchema),
+  templatePath: z.string().min(1),
+  startedAt: z.string().min(1),
+  seed: z.number().finite(),
+  runId: z.string().min(1),
+});
+
+export type DaemonAdapterEntry = z.infer<typeof DaemonAdapterEntrySchema>;
+export type DaemonRegistryEntry = z.infer<typeof DaemonRegistryEntrySchema>;
+
+export interface EntryIdentityResult {
+  readonly status: "dead" | "verified" | "mismatch" | "unreachable";
+  readonly ready: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Directory resolution
+// ---------------------------------------------------------------------------
+
+/** Returns the path to the daemon registry directory (`~/.miravo/daemon/`). */
+export function daemonDir(): string {
+  return `${resolveMiravoHome()}/daemon`;
+}
+
+/**
+ * Validate a simulation name to prevent path traversal.
+ * Reuses the shared SimulationNameSchema (lowercase alphanumeric + hyphens).
+ */
+function validateName(name: string): void {
+  const result = SimulationNameSchema.safeParse(name);
+  if (!result.success) {
+    throw new MiravoError(
+      `Invalid simulation name: "${name}".`,
+      "Use lowercase letters, numbers, and hyphens only (e.g., my-sim-1).",
+    );
+  }
+}
+
+function entryPath(name: string): string {
+  validateName(name);
+  return `${daemonDir()}/${name}.json`;
+}
+
+// ---------------------------------------------------------------------------
+// CRUD operations
+// ---------------------------------------------------------------------------
+
+/** Write a registry entry atomically (temp file + rename). */
+export async function writeEntry(entry: DaemonRegistryEntry): Promise<void> {
+  const dir = daemonDir();
+  await mkdir(dir, { recursive: true });
+  const filePath = entryPath(entry.name);
+  const tmpPath = `${filePath}.${process.pid}.tmp`;
+  await Bun.write(tmpPath, JSON.stringify(entry, null, 2));
+  await rename(tmpPath, filePath);
+}
+
+/**
+ * Acquire an exclusive lock for a simulation name.
+ * Prevents concurrent `start -d` from spawning duplicate daemons.
+ * Returns a release function; call it when done (even on error).
+ *
+ * Stale locks from crashed processes are detected via PID liveness and
+ * cleaned up automatically before retrying.
+ *
+ * @throws MiravoError if the name is already locked by a live process.
+ */
+export async function acquireNameLock(name: string): Promise<() => Promise<void>> {
+  validateName(name);
+  const dir = daemonDir();
+  await mkdir(dir, { recursive: true });
+  const lockPath = `${dir}/${name}.lock`;
+
+  const tryAcquire = async (): Promise<void> => {
+    try {
+      // O_CREAT | O_EXCL — fails if file already exists
+      const handle = await open(lockPath, "wx");
+      await handle.writeFile(String(process.pid));
+      await handle.close();
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "EEXIST") {
+        // Check if the lock belongs to a live process or is stale (crashed).
+        try {
+          const content = await Bun.file(lockPath).text();
+          const pid = parseInt(content.trim(), 10);
+          if (!Number.isNaN(pid) && !isPidAlive(pid)) {
+            // Stale lock from a crashed process — remove and retry.
+            await unlink(lockPath);
+            return tryAcquire();
+          }
+        } catch {
+          // Lock file disappeared between EEXIST and reading — retry.
+          return tryAcquire();
+        }
+        throw new MiravoError(
+          `Another 'miravo start -d' is already starting simulation "${name}".`,
+          "Wait for the other start to complete, or remove the lock with 'miravo rm'.",
+        );
+      }
+      throw error;
+    }
+  };
+
+  await tryAcquire();
+
+  return async () => {
+    try {
+      await unlink(lockPath);
+    } catch {
+      // Ignore — lock may have been cleaned up already
+    }
+  };
+}
+
+/** Read and validate a registry entry. Returns null if missing or invalid. */
+export async function readEntry(name: string): Promise<DaemonRegistryEntry | null> {
+  const filePath = entryPath(name);
+  const file = Bun.file(filePath);
+  if (!(await file.exists())) return null;
+  try {
+    const content = await file.text();
+    const parsed: unknown = JSON.parse(content);
+    const result = DaemonRegistryEntrySchema.safeParse(parsed);
+    return result.success ? result.data : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Remove a registry entry. Safe if file does not exist. */
+export async function removeEntry(name: string): Promise<void> {
+  try {
+    await unlink(entryPath(name));
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+  }
+}
+
+/** List all valid registry entries. Invalid files are silently skipped. */
+export async function listEntries(): Promise<readonly DaemonRegistryEntry[]> {
+  const dir = daemonDir();
+  let files: string[];
+  try {
+    files = await readdir(dir);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
+    throw error;
+  }
+
+  const entries: DaemonRegistryEntry[] = [];
+  for (const file of files) {
+    if (!file.endsWith(".json") || file.endsWith(".tmp")) continue;
+    const name = file.slice(0, -5); // strip .json
+    const entry = await readEntry(name);
+    if (entry) entries.push(entry);
+  }
+  return entries;
+}
+
+// ---------------------------------------------------------------------------
+// Liveness checks
+// ---------------------------------------------------------------------------
+
+/** Check if a PID is alive using signal 0. */
+export function isPidAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Verify that a registry entry corresponds to a live Miravo simulation.
+ *
+ * Two-step check:
+ * 1. PID alive (fast, avoids network I/O for dead processes)
+ * 2. RunId matches via GET /readyz (guards against PID reuse after reboot)
+ */
+export async function probeEntryIdentity(entry: DaemonRegistryEntry): Promise<EntryIdentityResult> {
+  if (!isPidAlive(entry.pid)) {
+    return { status: "dead", ready: false };
+  }
+
+  try {
+    const url = `http://${entry.adminHost}:${entry.adminPort}/readyz`;
+    const response = await fetch(url, { signal: AbortSignal.timeout(2_000) });
+    const bodyText = await response.text();
+    let body: unknown;
+    try {
+      body = JSON.parse(bodyText) as unknown;
+    } catch {
+      return { status: "mismatch", ready: false };
+    }
+    if (
+      typeof body !== "object" ||
+      body === null ||
+      !("runId" in body) ||
+      typeof body["runId"] !== "string"
+    ) {
+      return { status: "mismatch", ready: false };
+    }
+    if (body["runId"] !== entry.runId) {
+      return { status: "mismatch", ready: false };
+    }
+    return { status: "verified", ready: response.ok };
+  } catch {
+    // Keep the registry entry when the admin server is temporarily unreachable,
+    // but do not treat the identity as safe for raw signal delivery.
+    return { status: "unreachable", ready: false };
+  }
+}
+
+export async function isEntryAlive(entry: DaemonRegistryEntry): Promise<boolean> {
+  const identity = await probeEntryIdentity(entry);
+  return identity.status === "verified" || identity.status === "unreachable";
+}
+
+export async function canSafelySignalEntry(entry: DaemonRegistryEntry): Promise<boolean> {
+  const identity = await probeEntryIdentity(entry);
+  return identity.status === "verified";
+}
+
+/**
+ * Remove all registry entries whose processes are no longer alive.
+ * Uses full identity verification (PID + runId) to handle PID reuse.
+ */
+export async function sweepStaleEntries(): Promise<void> {
+  const entries = await listEntries();
+  for (const entry of entries) {
+    const identity = await probeEntryIdentity(entry);
+    if (identity.status === "dead" || identity.status === "mismatch") {
+      await removeEntry(entry.name);
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Conflict detection
+// ---------------------------------------------------------------------------
+
+/**
+ * Check for port conflicts against live registry entries.
+ *
+ * @param ports - Map of label → port to check (e.g., "admin" → 8080, "mqtt" → 1883)
+ * @param excludeName - Optional entry name to exclude (for re-checking own entry)
+ * @returns Array of human-readable conflict messages (empty = no conflicts)
+ */
+export async function checkPortConflicts(
+  ports: ReadonlyMap<string, number>,
+  excludeName?: string,
+): Promise<readonly string[]> {
+  const entries = await listEntries();
+  const conflicts: string[] = [];
+
+  for (const entry of entries) {
+    if (entry.name === excludeName) continue;
+    // Use PID check only (not full identity verification) for performance —
+    // port conflicts are about actual port usage, not Miravo identity.
+    if (!isPidAlive(entry.pid)) continue;
+
+    // Check admin port
+    for (const [label, port] of ports) {
+      if (port === entry.adminPort) {
+        conflicts.push(
+          `Port ${port} (${label}) is already in use by simulation "${entry.name}". Stop it first: miravo stop ${entry.name}`,
+        );
+      }
+      // Check adapter ports
+      for (const [adapterName, adapter] of Object.entries(entry.adapters) as [
+        string,
+        DaemonAdapterEntry,
+      ][]) {
+        if (port === adapter.port) {
+          conflicts.push(
+            `Port ${port} (${label}) conflicts with ${adapterName} port of simulation "${entry.name}". Stop it first: miravo stop ${entry.name}`,
+          );
+        }
+      }
+    }
+  }
+
+  return conflicts;
+}
+
+/**
+ * Check if a simulation name is already in use by a live entry.
+ * Removes stale entries as a side effect.
+ *
+ * @returns The alive entry if the name is taken, null otherwise.
+ */
+export async function checkNameConflict(name: string): Promise<DaemonRegistryEntry | null> {
+  const entry = await readEntry(name);
+  if (!entry) return null;
+
+  const identity = await probeEntryIdentity(entry);
+  if (identity.status === "verified" || identity.status === "unreachable") return entry;
+
+  if (identity.status === "dead" || identity.status === "mismatch") {
+    // Stale entry — clean it up
+    await removeEntry(name);
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Display helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Map bind addresses to connectable addresses for display.
+ * `0.0.0.0` and `::` are replaced with `127.0.0.1`.
+ */
+export function displayHost(host: string): string {
+  if (host === "0.0.0.0" || host === "::") return "127.0.0.1";
+  return host;
+}

package/src/lib/mqtt-client.ts

@@ -112,5 +112,5 @@ function disconnectClient(client: MqttClient): void {
   }
 }
 
-export { connectToBroker, connectWithTimeout, disconnectClient, resolveBrokerInfo };
 export type { BrokerConnectionInfo };
+export { connectToBroker, connectWithTimeout, disconnectClient, resolveBrokerInfo };

package/src/lib/parse.ts

@@ -67,3 +67,21 @@ export function parseDurationMs(value: string): number {
   }
   return n;
 }
+
+/** Maximum allowed timeout in seconds (1 hour). */
+const MAX_TIMEOUT_SECONDS = 3_600;
+
+/**
+ * Parse a string as a timeout in seconds and return milliseconds.
+ * Accepts positive numbers (integers or decimals). The result is rounded to
+ * the nearest millisecond.
+ */
+export function parseTimeoutSeconds(value: string): number {
+  const n = parsePositiveFloat(value);
+  if (n > MAX_TIMEOUT_SECONDS) {
+    throw new InvalidArgumentError(
+      `Expected a timeout in seconds (max ${MAX_TIMEOUT_SECONDS}), got "${value}".`,
+    );
+  }
+  return Math.round(n * 1_000);
+}

package/src/lib/resolve-simulation.ts

@@ -177,10 +177,10 @@ async function resolveTargetSimulation(
   };
 }
 
-export { discoverRunningSimulations, resolveTargetSimulation };
 export type {
   ResolvedTargetSimulation,
   ResolveTargetSimulationOptions,
   SimulationResolverClient,
   SimulationTopics,
 };
+export { discoverRunningSimulations, resolveTargetSimulation };

package/src/lib/shutdown.test.ts

@@ -21,11 +21,23 @@ const noopReporter = { log() {} };
 function configureSummaryLogger(
   options: { plain?: boolean; logFormat?: "pretty" | "json" } = {},
 ): void {
+  const previousNoColor = Bun.env["NO_COLOR"];
+  if (!(options.plain ?? false)) {
+    delete Bun.env["NO_COLOR"];
+  }
   unlockLogger();
-  configureLogger({
-    plain: options.plain ?? false,
-    logFormat: options.logFormat ?? "pretty",
-  });
+  try {
+    configureLogger({
+      plain: options.plain ?? false,
+      logFormat: options.logFormat ?? "pretty",
+    });
+  } finally {
+    if (previousNoColor === undefined) {
+      delete Bun.env["NO_COLOR"];
+    } else {
+      Bun.env["NO_COLOR"] = previousNoColor;
+    }
+  }
   for (const l of [
     logger,
     engineLog,

package/src/lib/shutdown.ts

@@ -2,7 +2,7 @@ import type { Engine, EngineMetricsSnapshot } from "@miravo/core";
 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 { engineLog, isJsonLogFormat, isPlain, isQuiet, mqttLog, opcuaLog } from "../logger.ts";
 import { computeAverageThroughput, formatCount, formatDuration } from "../output.ts";
 
 const SHUTDOWN_TASK_TIMEOUT_MS = 6_000;
@@ -294,7 +294,7 @@ function formatAdapterLine(
  * Print a compact periodic summary: one line for core stats, one per adapter.
  */
 export function printSummaryLine(metrics: EngineMetricsSnapshot): void {
-  if (isSilent()) return;
+  if (isQuiet()) return;
 
   if (isJsonLogFormat()) {
     engineLog.info("Periodic summary", buildJsonSummary({ metrics }));
@@ -507,7 +507,7 @@ async function printShutdownSummary(
   errorContextCounts?: ReadonlyMap<string, number>,
   writeFinal: (text: string) => Promise<void> = writeShutdownOutput,
 ): Promise<void> {
-  if (isSilent()) return;
+  if (isQuiet()) return;
 
   if (isJsonLogFormat()) {
     engineLog.info(

package/src/lib/template-category.test.ts

@@ -15,6 +15,7 @@ function discoveredTemplate(id: string, name: string): DiscoveredTemplate {
     twinAssignmentCount: 1,
     inlineModelCount: 0,
     uniqueModelCount: 1,
+    modelNames: ["model-a"],
     totalTwinCount: 1,
   };
 }

package/src/lib/template-utils.ts

@@ -3,12 +3,43 @@ import type { MiravoTemplate } from "@miravo/shared";
 /** Collect all unique model names referenced by a template's twin assignments. */
 export function collectReferencedModels(template: MiravoTemplate): Set<string> {
   const models = new Set<string>();
+  forEachTwin(template, (_area, _line, twin) => models.add(twin.model));
+  return models;
+}
+
+/** Build a UNS base path from template namespace, area, and line. */
+export function buildUNSBasePath(
+  template: MiravoTemplate,
+  areaName: string,
+  lineName: string,
+): string {
+  const segments: string[] = [];
+  const ns = template.namespace;
+  if (ns !== undefined) {
+    if ("enterprise" in ns) {
+      segments.push(ns.enterprise, ns.site);
+    } else if ("prefix" in ns) {
+      segments.push(ns.prefix);
+    }
+  }
+  segments.push(areaName, lineName);
+  return segments.join("/");
+}
+
+/** Iterate all twin assignments across all areas and lines. */
+export function forEachTwin(
+  template: MiravoTemplate,
+  callback: (
+    area: MiravoTemplate["areas"][number],
+    line: MiravoTemplate["areas"][number]["lines"][number],
+    twin: MiravoTemplate["areas"][number]["lines"][number]["twins"][number],
+  ) => void,
+): void {
   for (const area of template.areas) {
     for (const line of area.lines) {
       for (const twin of line.twins) {
-        models.add(twin.model);
+        callback(area, line, twin);
       }
     }
   }
-  return models;
 }