miravo 0.2.3 → 0.3.0

package/src/commands/ps.ts

@@ -0,0 +1,116 @@
+import type { EngineMetricsSnapshot } from "@miravo/shared";
+import type { Command } from "commander";
+import { isPidAlive, listEntries, sweepStaleEntries } from "../lib/daemon-registry.ts";
+import { handleCommandError, writeOutput } from "../logger.ts";
+import { formatTable } from "../output.ts";
+
+interface PsOptions {
+  readonly json?: boolean;
+}
+
+export function registerPsCommand(program: Command): void {
+  program
+    .command("ps")
+    .description("List background simulations with live metrics")
+    .option("--json", "Machine-readable JSON output")
+    .addHelpText(
+      "after",
+      `
+Examples:
+  $ miravo ps                              List background simulations
+  $ miravo ps --json                       Machine-readable JSON output`,
+    )
+    .action(async (options: PsOptions) => {
+      try {
+        await psAction(options);
+      } catch (error) {
+        handleCommandError(error);
+      }
+    });
+}
+
+type PsRow = Record<string, string> & {
+  readonly name: string;
+  readonly status: string;
+  readonly uptime: string;
+  readonly ticks: string;
+  readonly instances: string;
+  readonly admin: string;
+  readonly mqtt: string;
+  readonly opcua: string;
+};
+
+async function psAction(options: PsOptions): Promise<void> {
+  await sweepStaleEntries();
+  const entries = await listEntries();
+
+  if (entries.length === 0) {
+    writeOutput("No running simulations.");
+    return;
+  }
+
+  const rows: PsRow[] = [];
+
+  for (const entry of entries) {
+    const alive = isPidAlive(entry.pid);
+    let status = alive ? "running" : "dead";
+    let uptime = "-";
+    let ticks = "-";
+    let instances = "-";
+
+    if (alive) {
+      try {
+        const url = `http://${entry.adminHost}:${entry.adminPort}/metrics`;
+        const response = await fetch(url, { signal: AbortSignal.timeout(2_000) });
+        if (response.ok) {
+          const metrics = (await response.json()) as EngineMetricsSnapshot;
+          status = metrics.core.state === "running" ? "running" : metrics.core.state;
+          uptime = formatUptime(metrics.core.uptimeMs);
+          ticks = String(metrics.core.tickCount);
+          instances = String(metrics.core.instanceCount);
+        }
+      } catch {
+        status = "starting";
+      }
+    }
+
+    const mqttAdapter = entry.adapters["mqtt"];
+    const opcuaAdapter = entry.adapters["opcua"];
+
+    rows.push({
+      name: entry.name,
+      status,
+      uptime,
+      ticks,
+      instances,
+      admin: `:${entry.adminPort}`,
+      mqtt: mqttAdapter ? `:${mqttAdapter.port}` : "-",
+      opcua: opcuaAdapter ? `:${opcuaAdapter.port}` : "-",
+    });
+  }
+
+  if (options.json) {
+    writeOutput(JSON.stringify(rows, null, 2));
+    return;
+  }
+
+  const headers: Record<string, string> = {
+    name: "NAME",
+    status: "STATUS",
+    uptime: "UPTIME",
+    ticks: "TICKS",
+    instances: "INSTANCES",
+    admin: "ADMIN",
+    mqtt: "MQTT",
+    opcua: "OPC UA",
+  };
+
+  writeOutput(formatTable(headers, rows));
+}
+
+function formatUptime(ms: number): string {
+  const totalSeconds = Math.floor(ms / 1_000);
+  const hours = Math.floor(totalSeconds / 3_600);
+  const minutes = Math.floor((totalSeconds % 3_600) / 60);
+  return `${hours}h ${String(minutes).padStart(2, "0")}m`;
+}

package/src/commands/remove.ts

@@ -0,0 +1,38 @@
+import type { EngineCommand } from "@miravo/shared";
+import { CONTROL_CMD_TIMEOUT_MS } from "@miravo/shared";
+import type { Command } from "commander";
+import { executeAdminCommand, resolveAdminUrl } from "../lib/admin-client.ts";
+import { parseTimeoutSeconds } from "../lib/parse.ts";
+import { handleCommandError, handleCommandResult } from "../logger.ts";
+
+interface RemoveOptions {
+  readonly json?: boolean;
+  readonly adminUrl?: string;
+  readonly timeout?: number;
+}
+
+export function registerRemoveCommand(program: Command): void {
+  program
+    .command("remove <instanceId>")
+    .description("Remove an instance from the running simulation")
+    .option("--json", "Machine-readable JSON output")
+    .option("--admin-url <url>", "Miravo admin server URL (env: MIRAVO_ADMIN_URL)")
+    .option("--timeout <seconds>", "Timeout in seconds (default: 5)", parseTimeoutSeconds)
+    .addHelpText(
+      "after",
+      `
+Examples:
+  $ miravo remove pump-001                 Remove instance by ID`,
+    )
+    .action(async (instanceId: string, options: RemoveOptions) => {
+      try {
+        const adminUrl = resolveAdminUrl(options.adminUrl);
+        const timeoutMs = options.timeout ?? CONTROL_CMD_TIMEOUT_MS;
+        const command: EngineCommand = { type: "removeInstance", instanceId };
+        const result = await executeAdminCommand(adminUrl, command, timeoutMs);
+        handleCommandResult(result, options.json);
+      } catch (error) {
+        handleCommandError(error);
+      }
+    });
+}

package/src/commands/reset.ts

@@ -0,0 +1,44 @@
+import type { EngineCommand } from "@miravo/shared";
+import { CONTROL_CMD_TIMEOUT_MS } from "@miravo/shared";
+import type { Command } from "commander";
+import { executeAdminCommand, resolveAdminUrl } from "../lib/admin-client.ts";
+import { parseTimeoutSeconds } from "../lib/parse.ts";
+import { handleCommandError, handleCommandResult } from "../logger.ts";
+
+interface ResetOptions {
+  readonly clearPersistence?: boolean;
+  readonly json?: boolean;
+  readonly adminUrl?: string;
+  readonly timeout?: number;
+}
+
+export function registerResetCommand(program: Command): void {
+  program
+    .command("reset")
+    .description("Reset the simulation: remove all instances and template runs")
+    .option("--clear-persistence", "Also clear persisted state (start fresh on next boot)")
+    .option("--json", "Machine-readable JSON output")
+    .option("--admin-url <url>", "Miravo admin server URL (env: MIRAVO_ADMIN_URL)")
+    .option("--timeout <seconds>", "Timeout in seconds (default: 5)", parseTimeoutSeconds)
+    .addHelpText(
+      "after",
+      `
+Examples:
+  $ miravo reset                           Reset simulation state
+  $ miravo reset --clear-persistence       Reset and clear saved state`,
+    )
+    .action(async (options: ResetOptions) => {
+      try {
+        const adminUrl = resolveAdminUrl(options.adminUrl);
+        const timeoutMs = options.timeout ?? CONTROL_CMD_TIMEOUT_MS;
+        const command: EngineCommand = {
+          type: "resetSimulation",
+          clearPersistence: options.clearPersistence ?? false,
+        };
+        const result = await executeAdminCommand(adminUrl, command, timeoutMs);
+        handleCommandResult(result, options.json);
+      } catch (error) {
+        handleCommandError(error);
+      }
+    });
+}

package/src/commands/rm.ts

@@ -0,0 +1,97 @@
+import type { Command } from "commander";
+import { probeEntryIdentity, readEntry, removeEntry } from "../lib/daemon-registry.ts";
+import { handleCommandError, writeOutput } from "../logger.ts";
+
+interface RmOptions {
+  readonly force?: boolean;
+  readonly json?: boolean;
+}
+
+export function registerRmCommand(program: Command): void {
+  program
+    .command("rm <name>")
+    .description("Remove a stale daemon registry entry")
+    .option("-f, --force", "Kill the process if still alive before removing")
+    .option("--json", "Machine-readable JSON output")
+    .addHelpText(
+      "after",
+      `
+Examples:
+  $ miravo rm my-sim                       Remove stale registry entry
+  $ miravo rm my-sim --force               Kill process and remove entry`,
+    )
+    .action(async (name: string, options: RmOptions) => {
+      try {
+        await rmAction(name, options);
+      } catch (error) {
+        handleCommandError(error);
+      }
+    });
+}
+
+function jsonOut(obj: Record<string, unknown>): void {
+  console.log(JSON.stringify(obj, null, 2));
+}
+
+async function rmAction(name: string, options: RmOptions): Promise<void> {
+  const entry = await readEntry(name);
+  if (!entry) {
+    const msg = `Simulation "${name}" not found in daemon registry.`;
+    if (options.json) {
+      jsonOut({ success: false, name, message: msg });
+    } else {
+      writeOutput(msg);
+    }
+    process.exitCode = 1;
+    return;
+  }
+
+  const identity = await probeEntryIdentity(entry);
+
+  if (identity.status === "unreachable") {
+    const msg = `Simulation "${name}" could not be safely verified because its admin server is unreachable while PID ${entry.pid} is still alive.`;
+    if (options.json) {
+      jsonOut({
+        success: false,
+        name,
+        message: msg,
+        error: "Retry later, or inspect the process manually before removing the registry entry.",
+      });
+    } else {
+      writeOutput(
+        `${msg} Retry later, or inspect the process manually before removing the registry entry.`,
+      );
+    }
+    process.exitCode = 1;
+    return;
+  }
+
+  if (identity.status === "verified") {
+    if (!options.force) {
+      const msg = `Simulation "${name}" is still running (PID ${entry.pid}). Use --force to kill it, or 'miravo stop ${name}' for graceful shutdown.`;
+      if (options.json) {
+        jsonOut({ success: false, name, message: msg });
+      } else {
+        writeOutput(msg);
+      }
+      process.exitCode = 1;
+      return;
+    }
+
+    // Force kill
+    try {
+      process.kill(entry.pid, "SIGKILL");
+    } catch {
+      // Ignore — may have exited between check and kill
+    }
+    await Bun.sleep(200);
+  }
+
+  await removeEntry(name);
+  const msg = `Removed daemon registry entry for "${name}".`;
+  if (options.json) {
+    jsonOut({ success: true, name, message: msg });
+  } else {
+    writeOutput(msg);
+  }
+}

package/src/commands/spawn.ts

@@ -0,0 +1,45 @@
+import type { EngineCommand } from "@miravo/shared";
+import { CONTROL_CMD_TIMEOUT_MS } from "@miravo/shared";
+import type { Command } from "commander";
+import { executeAdminCommand, resolveAdminUrl } from "../lib/admin-client.ts";
+import { parsePositiveInt, parseTimeoutSeconds } from "../lib/parse.ts";
+import { handleCommandError, handleCommandResult } from "../logger.ts";
+
+interface SpawnOptions {
+  readonly count?: number;
+  readonly json?: boolean;
+  readonly adminUrl?: string;
+  readonly timeout?: number;
+}
+
+export function registerSpawnCommand(program: Command): void {
+  program
+    .command("spawn <model>")
+    .description("Add new instances of a model to the running simulation")
+    .option("-c, --count <n>", "Number of instances to spawn (default: 1)", parsePositiveInt)
+    .option("--json", "Machine-readable JSON output")
+    .option("--admin-url <url>", "Miravo admin server URL (env: MIRAVO_ADMIN_URL)")
+    .option("--timeout <seconds>", "Timeout in seconds (default: 5)", parseTimeoutSeconds)
+    .addHelpText(
+      "after",
+      `
+Examples:
+  $ miravo spawn centrifugal-pump          Spawn one instance
+  $ miravo spawn centrifugal-pump -c 5     Spawn five instances`,
+    )
+    .action(async (model: string, options: SpawnOptions) => {
+      try {
+        const adminUrl = resolveAdminUrl(options.adminUrl);
+        const timeoutMs = options.timeout ?? CONTROL_CMD_TIMEOUT_MS;
+        const command: EngineCommand = {
+          type: "spawn",
+          model,
+          count: options.count ?? 1,
+        };
+        const result = await executeAdminCommand(adminUrl, command, timeoutMs);
+        handleCommandResult(result, options.json);
+      } catch (error) {
+        handleCommandError(error);
+      }
+    });
+}

package/src/commands/speed.ts

@@ -0,0 +1,40 @@
+import type { EngineCommand } from "@miravo/shared";
+import { CONTROL_CMD_TIMEOUT_MS } from "@miravo/shared";
+import type { Command } from "commander";
+import { executeAdminCommand, resolveAdminUrl } from "../lib/admin-client.ts";
+import { parsePositiveFloat, parseTimeoutSeconds } from "../lib/parse.ts";
+import { handleCommandError, handleCommandResult } from "../logger.ts";
+
+interface SpeedOptions {
+  readonly json?: boolean;
+  readonly adminUrl?: string;
+  readonly timeout?: number;
+}
+
+export function registerSpeedCommand(program: Command): void {
+  program
+    .command("speed <multiplier>")
+    .description("Set simulation time multiplier (1-1000)")
+    .option("--json", "Machine-readable JSON output")
+    .option("--admin-url <url>", "Miravo admin server URL (env: MIRAVO_ADMIN_URL)")
+    .option("--timeout <seconds>", "Timeout in seconds (default: 5)", parseTimeoutSeconds)
+    .addHelpText(
+      "after",
+      `
+Examples:
+  $ miravo speed 10                        Run at 10x real time
+  $ miravo speed 0.5                       Run at half speed`,
+    )
+    .action(async (multiplierStr: string, options: SpeedOptions) => {
+      try {
+        const multiplier = parsePositiveFloat(multiplierStr);
+        const adminUrl = resolveAdminUrl(options.adminUrl);
+        const timeoutMs = options.timeout ?? CONTROL_CMD_TIMEOUT_MS;
+        const command: EngineCommand = { type: "setSpeed", multiplier };
+        const result = await executeAdminCommand(adminUrl, command, timeoutMs);
+        handleCommandResult(result, options.json);
+      } catch (error) {
+        handleCommandError(error);
+      }
+    });
+}

package/src/commands/start.test.ts

@@ -73,6 +73,7 @@ function discoveredTemplate(id: string, name: string, description?: string): Dis
     twinAssignmentCount: 1,
     inlineModelCount: 0,
     uniqueModelCount: 2,
+    modelNames: ["model-a", "model-b"],
     totalTwinCount: 5,
   };
 }
@@ -207,6 +208,98 @@ describe("resolveSimulationName", () => {
   });
 });
 
+describe("resolveProtocolBootPlans", () => {
+  test("preserves restored adapter state when no explicit protocol overrides are provided", async () => {
+    const { resolveProtocolBootPlans } = await import("./start.ts");
+
+    expect(
+      resolveProtocolBootPlans({
+        options: {},
+        optionSources: {},
+        restoredFromPersistence: true,
+      }),
+    ).toEqual([
+      { name: "mqtt", shouldEnable: true, overrideRestore: false },
+      { name: "opcua", shouldEnable: false, overrideRestore: false },
+    ]);
+  });
+
+  test("applies boot defaults when no persisted snapshot was restored", async () => {
+    const { resolveProtocolBootPlans } = await import("./start.ts");
+
+    expect(
+      resolveProtocolBootPlans({
+        options: {},
+        optionSources: {},
+        restoredFromPersistence: false,
+      }),
+    ).toEqual([
+      { name: "mqtt", shouldEnable: true, overrideRestore: true },
+      { name: "opcua", shouldEnable: false, overrideRestore: true },
+    ]);
+  });
+
+  test("treats explicit MQTT disable as authoritative over persisted state", async () => {
+    const { resolveProtocolBootPlans } = await import("./start.ts");
+
+    expect(
+      resolveProtocolBootPlans({
+        options: { mqtt: false },
+        optionSources: { mqtt: "cli" },
+        restoredFromPersistence: true,
+      }),
+    ).toContainEqual({ name: "mqtt", shouldEnable: false, overrideRestore: true });
+  });
+
+  test("treats explicit CLI MQTT config overrides as authoritative over persisted config", async () => {
+    const { resolveProtocolBootPlans } = await import("./start.ts");
+
+    expect(
+      resolveProtocolBootPlans({
+        options: { mqttPort: 1884 },
+        optionSources: { mqttPort: "cli" },
+        restoredFromPersistence: true,
+      }),
+    ).toContainEqual({ name: "mqtt", shouldEnable: true, overrideRestore: true });
+  });
+
+  test("does not treat env fallback config as authoritative over persisted MQTT state", async () => {
+    const { resolveProtocolBootPlans } = await import("./start.ts");
+
+    expect(
+      resolveProtocolBootPlans({
+        options: {},
+        optionSources: {},
+        restoredFromPersistence: true,
+      }),
+    ).toContainEqual({ name: "mqtt", shouldEnable: true, overrideRestore: false });
+  });
+
+  test("treats explicit OPC UA enable as authoritative over persisted state", async () => {
+    const { resolveProtocolBootPlans } = await import("./start.ts");
+
+    expect(
+      resolveProtocolBootPlans({
+        options: { opcua: true },
+        optionSources: { opcua: "cli" },
+        restoredFromPersistence: true,
+      }),
+    ).toContainEqual({ name: "opcua", shouldEnable: true, overrideRestore: true });
+  });
+
+  test("does not treat ignored OPC UA config flags as persisted-state overrides", async () => {
+    const { resolveProtocolBootPlans } = await import("./start.ts");
+
+    expect(
+      resolveProtocolBootPlans({
+        options: { opcuaPort: 4841 },
+        optionSources: { opcuaPort: "cli" },
+        restoredFromPersistence: true,
+      }),
+    ).toContainEqual({ name: "opcua", shouldEnable: false, overrideRestore: false });
+  });
+});
+
 describe("error context aggregation", () => {
   test("normalizeErrorContext redacts high-cardinality fragments", async () => {
     const { normalizeErrorContext } = await import("./start.ts");