miravo 0.6.0 → 0.6.2

package/src/commands/status.ts

@@ -1,470 +0,0 @@
-import {
-  CONTROL_STATUS_TIMEOUT_MS,
-  type EngineMetricsSnapshot,
-  type EngineStateSnapshot,
-  MiravoError,
-} from "@miravo/shared";
-import type { Command } from "commander";
-import { colors } from "consola/utils";
-import { getAdminSnapshot, resolveAdminUrl } from "../lib/admin-client.ts";
-import { connectToBroker, disconnectClient } from "../lib/mqtt-client.ts";
-import { parseTimeoutSeconds } from "../lib/parse.ts";
-import { discoverRunningSimulations } from "../lib/resolve-simulation.ts";
-import { engineLog, handleCommandError, isPlain, writeOutput } from "../logger.ts";
-import {
-  formatCount,
-  formatDuration,
-  formatHealthSuffix,
-  formatKeyValue,
-  formatTable,
-} from "../output.ts";
-
-const STATUS_WATCH_INTERVAL_MS = 1000;
-
-interface StatusOptions {
-  readonly name?: string;
-  readonly discover?: boolean;
-  readonly watch?: boolean;
-  readonly instance?: string;
-  readonly json?: boolean;
-  readonly adminUrl?: string;
-  readonly template?: string;
-  readonly timeout?: number;
-}
-
-/**
- * Register the `miravo status` command with the root Commander program.
- * Shows status of a running simulation via the admin HTTP server.
- */
-export function registerStatusCommand(program: Command): void {
-  program
-    .command("status")
-    .description("Show live status, metrics, and instances of a running simulation")
-    .option("--name <name>", "Target simulation name")
-    .option("--discover", "Discover running simulations and exit")
-    .option("-w, --watch", "Poll the admin server and re-render on updates")
-    .option("--instance <id>", "Show detailed status for one instance")
-    .option("--json", "Machine-readable JSON output")
-    .option("--admin-url <url>", "Admin API URL (env: MIRAVO_ADMIN_URL)")
-    .option(
-      "--template <path>",
-      "Path to .miravo.yaml for MQTT discovery connection info (env: MIRAVO_TEMPLATE)",
-    )
-    .option("--timeout <seconds>", "Timeout in seconds (default: 5)", parseTimeoutSeconds)
-    .addHelpText(
-      "after",
-      `
-Examples:
-  $ miravo status                          Show simulation overview
-  $ miravo status -w                       Watch mode (live updates)
-  $ miravo status --instance pump-001      Detail view for one instance
-  $ miravo status --json                   Machine-readable JSON output
-  $ miravo status --discover               Find running simulations via MQTT`,
-    )
-    .action(async (options: StatusOptions) => {
-      await statusAction(options);
-    });
-}
-
-type MetricsSnapshot = EngineMetricsSnapshot;
-type StateSnapshot = EngineStateSnapshot;
-
-// ---------------------------------------------------------------------------
-// Action
-// ---------------------------------------------------------------------------
-
-async function statusAction(options: StatusOptions): Promise<void> {
-  try {
-    const timeoutMs = options.timeout ?? CONTROL_STATUS_TIMEOUT_MS;
-    if (options.discover) {
-      await discoverMode(options, timeoutMs);
-      return;
-    }
-
-    const adminUrl = resolveAdminUrl(options.adminUrl);
-    if (options.watch) {
-      await watchMode(adminUrl, options, timeoutMs);
-    } else {
-      await snapshotMode(adminUrl, options, timeoutMs);
-    }
-  } catch (error) {
-    handleCommandError(error, engineLog);
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Discover mode (MQTT-only)
-// ---------------------------------------------------------------------------
-
-async function discoverMode(options: StatusOptions, timeoutMs: number): Promise<void> {
-  const templateOption = options.template ?? Bun.env["MIRAVO_TEMPLATE"];
-  const { client, brokerInfo } = await connectToBroker(templateOption, timeoutMs);
-  try {
-    const simulations = await discoverRunningSimulations(client, {
-      timeoutMs,
-      brokerUrl: brokerInfo.url,
-    });
-    if (simulations.length === 0) {
-      engineLog.error(
-        `No running simulations found on broker ${brokerInfo.url}. Start one with 'miravo start'.`,
-      );
-      process.exitCode = 1;
-      return;
-    }
-    writeOutput(`Found ${simulations.length} simulation(s):`);
-    for (const simulationName of simulations) {
-      writeOutput(`  ${simulationName}`);
-    }
-  } finally {
-    disconnectClient(client);
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Snapshot mode (default): get one reading and exit
-// ---------------------------------------------------------------------------
-
-async function snapshotMode(
-  adminUrl: string,
-  options: StatusOptions,
-  timeoutMs: number,
-): Promise<void> {
-  const data = await getStatusSnapshot(adminUrl, timeoutMs, options.name);
-
-  if (options.json) {
-    const filtered = filterForJson(data.metrics, data.state, options.instance);
-    writeOutput(JSON.stringify(filtered.payload, null, 2));
-    if (filtered.missingInstance) {
-      process.exitCode = 1;
-    }
-    return;
-  }
-
-  if (options.instance) {
-    renderInstanceDetail(data.metrics, data.state, options.instance);
-  } else {
-    renderOverview(data.metrics, data.state);
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Watch mode: continuous updates
-// ---------------------------------------------------------------------------
-
-async function watchMode(
-  adminUrl: string,
-  options: StatusOptions,
-  timeoutMs: number,
-): Promise<void> {
-  let firstRender = true;
-  let stopped = false;
-  const stop = (): void => {
-    stopped = true;
-  };
-
-  process.once("SIGINT", stop);
-  process.once("SIGTERM", stop);
-
-  try {
-    while (!stopped) {
-      const snapshot = await getStatusSnapshot(adminUrl, timeoutMs, options.name);
-      renderFrame(snapshot.metrics, snapshot.state, options, firstRender);
-      firstRender = false;
-
-      if (!stopped) {
-        await Bun.sleep(STATUS_WATCH_INTERVAL_MS);
-      }
-    }
-  } finally {
-    process.off("SIGINT", stop);
-    process.off("SIGTERM", stop);
-  }
-}
-
-function renderFrame(
-  metrics: MetricsSnapshot,
-  state: StateSnapshot,
-  options: StatusOptions,
-  _isFirst: boolean,
-): void {
-  if (options.json) {
-    // NDJSON: one JSON object per line
-    const filtered = filterForJson(metrics, state, options.instance);
-    writeOutput(JSON.stringify(filtered.payload));
-    if (filtered.missingInstance) {
-      process.exitCode = 1;
-    }
-    return;
-  }
-
-  // Clear screen for re-render
-  if (process.stdout.isTTY && !isPlain()) {
-    process.stdout.write("\x1B[2J\x1B[H");
-  }
-
-  if (options.instance) {
-    renderInstanceDetail(metrics, state, options.instance);
-  } else {
-    renderOverview(metrics, state);
-  }
-}
-
-// ---------------------------------------------------------------------------
-// JSON output filtering
-// ---------------------------------------------------------------------------
-
-/**
- * When `--instance` is combined with `--json`, narrow the output to the
- * single requested instance instead of dumping the full fleet payload.
- */
-function filterForJson(
-  metrics: MetricsSnapshot,
-  state: StateSnapshot,
-  instanceId?: string,
-): { readonly payload: unknown; readonly missingInstance: boolean } {
-  if (!instanceId) {
-    return { payload: { metrics, state }, missingInstance: false };
-  }
-
-  const instance = state.instances.find((i) => i.id === instanceId);
-  if (!instance) {
-    return {
-      payload: {
-        error: `Instance "${instanceId}" not found`,
-        available: state.instances.map((i) => i.id),
-      },
-      missingInstance: true,
-    };
-  }
-
-  return {
-    payload: {
-      metrics: metrics.core,
-      instance,
-      ...(state.config.template ? { template: state.config.template } : {}),
-    },
-    missingInstance: false,
-  };
-}
-
-async function getStatusSnapshot(
-  adminUrl: string,
-  timeoutMs: number,
-  expectedName?: string,
-): Promise<{ readonly metrics: MetricsSnapshot; readonly state: StateSnapshot }> {
-  const snapshot = await getAdminSnapshot(adminUrl, timeoutMs);
-  if (expectedName && snapshot.state.simulationName !== expectedName) {
-    throw new MiravoError(
-      `Connected to simulation "${snapshot.state.simulationName}" instead of "${expectedName}".`,
-      "Pass --admin-url for the correct Miravo process, or omit --name to inspect the connected simulation.",
-    );
-  }
-  return snapshot;
-}
-
-// ---------------------------------------------------------------------------
-// Render: overview
-// ---------------------------------------------------------------------------
-
-function renderOverview(metrics: MetricsSnapshot, state: StateSnapshot): void {
-  const { core, fleet } = metrics;
-  const mqttAdapter = metrics.adapters.find((a) => a.name === "mqtt");
-
-  const sep = colors.dim(" | ");
-
-  // Header
-  writeOutput();
-  writeOutput(`  ${colors.bold(colors.cyan("Miravo Status"))}`);
-  writeOutput();
-
-  // Engine line
-  const stateColor =
-    core.state === "running" ? colors.green : core.state === "paused" ? colors.yellow : colors.red;
-  const tps =
-    core.actualTicksPerSecond > 0 ? `${core.actualTicksPerSecond.toFixed(1)} ticks/s` : "";
-
-  writeOutput(
-    formatKeyValue([
-      [
-        colors.dim("Engine"),
-        `${stateColor(core.state)}${sep}tick #${formatCount(core.tickCount)}${sep}uptime: ${formatDuration(core.uptimeMs)}${tps ? sep + tps : ""}`,
-      ],
-      [
-        colors.dim("Fleet"),
-        `${colors.bold(String(core.instanceCount))} instances${sep}${colors.bold(String(core.memberValueCount))} data points`,
-      ],
-    ]),
-  );
-
-  if (state.config.template) {
-    const templateLabel = `${colors.bold(state.config.template.name)}${sep}${colors.dim(state.config.template.path)}`;
-    writeOutput(formatKeyValue([[colors.dim("Template"), templateLabel]]));
-  }
-
-  // Health
-  const lifecycleEntries = Object.entries(fleet.lifecycleBreakdown);
-  if (lifecycleEntries.length > 0) {
-    const healthStr = lifecycleEntries.map(([stage, count]) => `${count} ${stage}`).join(", ");
-    writeOutput(formatKeyValue([[colors.dim("Health"), healthStr]]));
-  }
-
-  // Faults
-  if (fleet.activeFaultCount > 0) {
-    const faultStr = fleet.faultBreakdown.map((f) => `${f.fault} (${f.count})`).join(", ");
-    writeOutput(
-      formatKeyValue([
-        [
-          colors.dim("Faults"),
-          `${colors.yellow(String(fleet.activeFaultCount))} active: ${faultStr}`,
-        ],
-      ]),
-    );
-  } else {
-    writeOutput(formatKeyValue([[colors.dim("Faults"), colors.green("none")]]));
-  }
-
-  // MQTT
-  if (mqttAdapter) {
-    const connStr = mqttAdapter.metrics.connected
-      ? colors.green("connected")
-      : colors.red("disconnected");
-    const errStr =
-      mqttAdapter.metrics.errorsCount > 0
-        ? colors.yellow(String(mqttAdapter.metrics.errorsCount))
-        : colors.green("0");
-    const healthStr = formatHealthSuffix(mqttAdapter.metrics, sep);
-    writeOutput(
-      formatKeyValue([
-        [
-          colors.dim("MQTT"),
-          `${connStr}${sep}${formatCount(mqttAdapter.metrics.messagesPublished)} published${sep}${errStr} errors${healthStr}`,
-        ],
-      ]),
-    );
-  }
-
-  // OPC UA
-  const opcuaAdapter = metrics.adapters.find((a) => a.name === "opcua");
-  if (opcuaAdapter) {
-    const connStr = opcuaAdapter.metrics.connected
-      ? colors.green("connected")
-      : colors.red("disconnected");
-    const errStr =
-      opcuaAdapter.metrics.errorsCount > 0
-        ? colors.yellow(String(opcuaAdapter.metrics.errorsCount))
-        : colors.green("0");
-    const healthStr = formatHealthSuffix(opcuaAdapter.metrics, sep);
-    writeOutput(
-      formatKeyValue([
-        [
-          colors.dim("OPC UA"),
-          `${connStr}${sep}${formatCount(opcuaAdapter.metrics.messagesPublished)} updates${sep}${errStr} errors${healthStr}`,
-        ],
-      ]),
-    );
-  }
-
-  // Errors
-  if (
-    core.engineErrorsCount > 0 ||
-    core.tickOverrunsCount > 0 ||
-    core.circuitBreakerTripsCount > 0
-  ) {
-    writeOutput(
-      formatKeyValue([
-        [
-          colors.dim("Errors"),
-          `${core.engineErrorsCount} engine${sep}${core.tickOverrunsCount} overruns${sep}${core.circuitBreakerTripsCount} breaker trips`,
-        ],
-      ]),
-    );
-  }
-
-  // Instances table
-  if (state.instances.length > 0) {
-    const hasQuarantined = state.instances.some((i) => i.isQuarantined);
-
-    writeOutput();
-    writeOutput(`  ${colors.bold("Instances:")}`);
-    const rows = state.instances.map((inst) => ({
-      id: colors.cyan(inst.id),
-      model: inst.model,
-      stage: inst.lifecycleStage,
-      faults:
-        inst.activeFaults.length > 0
-          ? colors.yellow(inst.activeFaults.join(", "))
-          : colors.dim("none"),
-      hours: `${inst.operatingHours.toFixed(0)}h`,
-      ...(hasQuarantined ? { quarantined: inst.isQuarantined ? colors.red("yes") : "" } : {}),
-    }));
-
-    const headers: Record<string, string> = {
-      id: colors.dim("ID"),
-      model: colors.dim("Model"),
-      stage: colors.dim("Stage"),
-      faults: colors.dim("Faults"),
-      hours: colors.dim("Hours"),
-    };
-    if (hasQuarantined) {
-      headers["quarantined"] = colors.dim("Quarantined");
-    }
-
-    writeOutput(formatTable(headers, rows));
-  }
-
-  writeOutput();
-}
-
-// ---------------------------------------------------------------------------
-// Render: instance detail
-// ---------------------------------------------------------------------------
-
-function renderInstanceDetail(
-  metrics: MetricsSnapshot,
-  state: StateSnapshot,
-  instanceId: string,
-): void {
-  const instance = state.instances.find((i) => i.id === instanceId);
-  if (!instance) {
-    const available = state.instances.map((i) => i.id).join(", ");
-    engineLog.error(`Instance "${instanceId}" not found. Available: ${available || "(none)"}`);
-    process.exitCode = 1;
-    return;
-  }
-
-  const { core } = metrics;
-
-  writeOutput();
-  writeOutput(
-    `  ${colors.bold(colors.cyan(`Instance: ${instance.id}`))} ${colors.dim(`(${instance.model})`)}`,
-  );
-  writeOutput();
-
-  writeOutput(
-    formatKeyValue([
-      [colors.dim("UNS Path"), instance.browsePath.join("/")],
-      [
-        colors.dim("Lifecycle"),
-        `${instance.lifecycleStage} (${formatCount(Math.floor(instance.operatingHours))} operating hours)`,
-      ],
-      [
-        colors.dim("Faults"),
-        instance.activeFaults.length > 0
-          ? colors.yellow(instance.activeFaults.join(", "))
-          : colors.green("none"),
-      ],
-      [colors.dim("Quarantined"), instance.isQuarantined ? colors.red("yes") : colors.green("no")],
-      [colors.dim("Engine"), `${core.state} · tick #${formatCount(core.tickCount)}`],
-      ...(state.config.template
-        ? [
-            [
-              colors.dim("Template"),
-              `${state.config.template.name} (${state.config.template.path})`,
-            ] as const,
-          ]
-        : []),
-    ]),
-  );
-
-  writeOutput();
-}

package/src/commands/stop.test.ts

@@ -1,84 +0,0 @@
-import { afterEach, beforeEach, describe, expect, test } from "bun:test";
-import { mkdtemp, rm } from "node:fs/promises";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import type { DaemonRegistryEntry } from "../lib/daemon-registry.ts";
-import { readEntry, writeEntry } from "../lib/daemon-registry.ts";
-import { resetExitCode, runCliCommand } from "./cli-test-setup.ts";
-
-let testHome: string;
-const originalFetch = globalThis.fetch;
-const originalKill = process.kill;
-const forwardKill = originalKill as (pid: number, signal?: number | NodeJS.Signals) => void;
-
-function makeEntry(overrides: Partial<DaemonRegistryEntry> = {}): DaemonRegistryEntry {
-  return {
-    name: "test-sim",
-    pid: 42_424,
-    adminPort: 8080,
-    adminHost: "127.0.0.1",
-    adapters: {},
-    templatePath: "/tmp/test.miravo.yaml",
-    startedAt: "2026-03-18T10:00:00Z",
-    seed: 42,
-    runId: "run-123",
-    ...overrides,
-  };
-}
-
-beforeEach(resetExitCode);
-
-afterEach(async () => {
-  globalThis.fetch = originalFetch;
-  process.kill = originalKill;
-  delete Bun.env["MIRAVO_HOME"];
-  resetExitCode();
-  if (testHome) {
-    await rm(testHome, { recursive: true, force: true });
-  }
-});
-
-describe("miravo stop", () => {
-  test("force-kills a verified daemon after /shutdown makes /readyz disappear", async () => {
-    testHome = await mkdtemp(join(tmpdir(), "miravo-stop-test-"));
-    Bun.env["MIRAVO_HOME"] = testHome;
-
-    let alive = true;
-    process.kill = ((pid: number, signal?: number | NodeJS.Signals) => {
-      if (pid !== 42_424) {
-        return forwardKill(pid, signal);
-      }
-      if (signal === 0 || signal === undefined) {
-        if (!alive) {
-          const error = new Error("ESRCH") as NodeJS.ErrnoException;
-          error.code = "ESRCH";
-          throw error;
-        }
-        return;
-      }
-      if (signal === "SIGKILL") {
-        alive = false;
-      }
-    }) as typeof process.kill;
-
-    globalThis.fetch = (async (input, init) => {
-      const url = String(input);
-      if (url.endsWith("/readyz")) {
-        return Response.json({ status: "paused", runId: "run-123" }, { status: 503 });
-      }
-      if (url.endsWith("/shutdown")) {
-        expect(init?.method).toBe("POST");
-        return Response.json({ status: "shutting_down" }, { status: 200 });
-      }
-      throw new Error(`Unexpected fetch: ${url}`);
-    }) as typeof fetch;
-
-    await writeEntry(makeEntry());
-
-    await runCliCommand(["stop", "test-sim", "--timeout", "0.001"]);
-
-    expect(alive).toBe(false);
-    expect(await readEntry("test-sim")).toBeNull();
-    expect(process.exitCode).toBe(0);
-  });
-});