miravo 0.5.0 → 0.6.1

package/src/commands/models.ts

@@ -1,338 +0,0 @@
-import { existsSync } from "node:fs";
-import { relative, resolve } from "node:path";
-import { type DiscoveredModelWithSource, loadTwinModel } from "@miravo/core";
-import type { GeneratorConfig, TwinModel } from "@miravo/shared";
-import { TWIN_FILE_EXTENSION } from "@miravo/shared";
-import type { Command } from "commander";
-import { colors } from "consola/utils";
-import { createCatalog } from "../lib/template-locator.ts";
-import { configLog, handleCommandError, writeOutput } from "../logger.ts";
-import { formatTable } from "../output.ts";
-
-// ---------------------------------------------------------------------------
-// Command registration
-// ---------------------------------------------------------------------------
-
-export function registerModelsCommand(program: Command): void {
-  const models = program.command("models").description("List and inspect asset models");
-
-  models
-    .command("list")
-    .description("Discover and list available models")
-    .option("--dir <path>", "Additional directory to search for models")
-    .addHelpText(
-      "after",
-      `
-Examples:
-  $ miravo models list                     List all discoverable models`,
-    )
-    .action(async (options: { readonly dir?: string }) => {
-      await modelsListAction(options);
-    });
-
-  models
-    .command("inspect <name>")
-    .description("Show detailed information about a model")
-    .option("--raw", "Dump the raw YAML file to stdout")
-    .addHelpText(
-      "after",
-      `
-Examples:
-  $ miravo models inspect centrifugal-pump        Show model details
-  $ miravo models inspect centrifugal-pump --raw  Dump raw YAML`,
-    )
-    .action(async (name: string, options: { readonly raw?: boolean }) => {
-      await modelsInspectAction(name, options);
-    });
-}
-
-// ---------------------------------------------------------------------------
-// models list
-// ---------------------------------------------------------------------------
-
-async function modelsListAction(options: { readonly dir?: string }): Promise<void> {
-  try {
-    const catalog = createCatalog();
-    const allModels = await catalog.listModels();
-
-    const builtinModels: DiscoveredModelWithSource[] = [];
-    const localRegModels: DiscoveredModelWithSource[] = [];
-    const cwdModels: DiscoveredModelWithSource[] = [];
-
-    for (const model of allModels) {
-      switch (model.source.kind) {
-        case "builtin":
-          builtinModels.push(model);
-          break;
-        case "local":
-          localRegModels.push(model);
-          break;
-        case "cwd":
-          cwdModels.push(model);
-          break;
-        default: {
-          const _exhaustive: never = model.source.kind;
-          throw new Error(`Unexpected content source kind: ${String(_exhaustive)}`);
-        }
-      }
-    }
-
-    if (options.dir) {
-      const resolvedDir = resolve(options.dir);
-      if (!existsSync(resolvedDir)) {
-        configLog.error(`Directory not found: ${resolvedDir}`);
-        process.exitCode = 1;
-        return;
-      }
-      const { discoverModels } = await import("@miravo/core");
-      const extraModels = await discoverModels(resolvedDir);
-      const existingPaths = new Set(cwdModels.map((m) => m.path));
-      for (const extra of extraModels) {
-        if (!existingPaths.has(extra.path)) {
-          existingPaths.add(extra.path);
-          cwdModels.push({ ...extra, source: { kind: "cwd", path: resolvedDir } });
-        }
-      }
-    }
-
-    if (builtinModels.length === 0 && cwdModels.length === 0 && localRegModels.length === 0) {
-      configLog.info("No models found.");
-      return;
-    }
-
-    const headers = {
-      name: colors.dim("Name"),
-      members: colors.dim("Members"),
-      methods: colors.dim("Methods"),
-      faults: colors.dim("Faults"),
-      lifecycle: colors.dim("Lifecycle"),
-      source: colors.dim("Source"),
-    };
-
-    const renderSection = (label: string, models: readonly DiscoveredModelWithSource[]): void => {
-      if (models.length === 0) return;
-      writeOutput();
-      writeOutput(`  ${colors.bold(`${label}:`)}`);
-      writeOutput(
-        formatTable(
-          headers,
-          models.map((m) => ({
-            name: colors.cyan(m.name),
-            members: String(m.memberCount),
-            methods: String(m.methodCount),
-            faults: String(m.faultCount),
-            lifecycle:
-              m.lifecycleStageCount > 0 ? `${m.lifecycleStageCount} stages` : colors.dim("none"),
-            source: colors.dim(m.source.kind),
-          })),
-        ),
-      );
-    };
-
-    renderSection("Built-in", builtinModels);
-    renderSection("Local", localRegModels);
-    renderSection("Project", cwdModels);
-    writeOutput();
-  } catch (error) {
-    handleCommandError(error);
-  }
-}
-
-// ---------------------------------------------------------------------------
-// models inspect
-// ---------------------------------------------------------------------------
-
-async function modelsInspectAction(
-  name: string,
-  options: { readonly raw?: boolean },
-): Promise<void> {
-  try {
-    const catalog = createCatalog();
-    const isPath = name.includes("/") || name.endsWith(TWIN_FILE_EXTENSION);
-    const resolvedPath = isPath ? resolve(name) : await catalog.resolveModel(name);
-
-    const sourceLabel = catalog.getSourceLabel(resolvedPath);
-
-    if (options.raw) {
-      const rawText = await Bun.file(resolvedPath).text();
-      process.stdout.write(rawText);
-      return;
-    }
-
-    const model = await loadTwinModel(resolvedPath);
-    const output = formatModelInspect(model, resolvedPath, sourceLabel);
-    writeOutput(output);
-  } catch (error) {
-    handleCommandError(error);
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Formatting helpers (exported for testing)
-// ---------------------------------------------------------------------------
-
-export function formatGeneratorSummary(generator: GeneratorConfig): string {
-  switch (generator.type) {
-    case "sine":
-      return `sine (center: ${generator.center})`;
-    case "noise":
-      return `noise (center: ${generator.center})`;
-    case "correlated":
-      return `correlated (source: ${generator.source})`;
-    case "random-walk":
-      return `random-walk (${generator.min}..${generator.max})`;
-    case "step":
-      return `step (${generator.values.length} values)`;
-    case "state-machine":
-      return `state-machine (${generator.states.length} states)`;
-    case "health-dependent":
-      return `health-dependent (${Object.keys(generator.stages).length} stages)`;
-    case "ramp":
-      return `ramp (rate: ${generator.rate}, duration: ${generator.duration}s)`;
-    case "mean-reverting-noise":
-      return `mean-reverting-noise (mean: ${generator.mean}, tau: ${generator.tau}s)`;
-    case "timetable":
-      return `timetable (${generator.points.length} points)`;
-    case "first-order-lag":
-      return `first-order-lag (tau: ${generator.tau}s)`;
-    case "integrator":
-      return `integrator (gain: ${generator.gain})`;
-    case "transport-delay":
-      return `transport-delay (delay: ${generator.delay}s)`;
-    case "slew-rate-limiter":
-      return `slew-rate-limiter (rate_up: ${generator.rate_up})`;
-    case "second-order":
-      return `second-order (freq: ${generator.natural_freq_hz}Hz, zeta: ${generator.damping_ratio})`;
-    case "hysteresis-relay":
-      return `hysteresis-relay (on: ${generator.on_threshold}, off: ${generator.off_threshold})`;
-    case "weighted-sum":
-      return `weighted-sum (${generator.terms.length} terms)`;
-    case "gate":
-      return `gate (enabled: ${generator.enabled_member})`;
-    case "waveform":
-      return `waveform (shape: ${generator.shape}, period: ${generator.period}s)`;
-    case "chirp":
-      return `chirp (${generator.start_freq_hz}–${generator.end_freq_hz}Hz, ${generator.sweep_duration}s)`;
-    case "impulse":
-      return `impulse (amplitude: ${generator.amplitude}${generator.probability !== undefined ? `, p=${generator.probability}` : ``})`;
-    default: {
-      const _exhaustive: never = generator;
-      return String(_exhaustive);
-    }
-  }
-}
-
-export function formatModelInspect(
-  model: TwinModel,
-  sourcePath: string,
-  sourceLabel: string,
-): string {
-  const lines: string[] = [];
-
-  // Header
-  if (model.model.description) {
-    lines.push(
-      `  ${colors.cyan(colors.bold(model.model.name))} ${colors.dim("\u2014")} ${model.model.description}`,
-    );
-  } else {
-    lines.push(`  ${colors.cyan(colors.bold(model.model.name))}`);
-  }
-  lines.push("");
-
-  // Parameters
-  if (model.parameters && Object.keys(model.parameters).length > 0) {
-    lines.push(`  ${colors.bold("Parameters:")}`);
-    lines.push(
-      formatTable(
-        {
-          name: colors.dim("Name"),
-          type: colors.dim("Type"),
-          defaultVal: colors.dim("Default"),
-          unit: colors.dim("Unit"),
-        },
-        Object.entries(model.parameters).map(([name, param]) => ({
-          name,
-          type: param.type,
-          defaultVal: String(param.default),
-          unit: param.unit ?? "",
-        })),
-      ),
-    );
-    lines.push("");
-  }
-
-  // Members
-  const memberEntries = Object.entries(model.members) as Array<
-    [string, TwinModel["members"][string]]
-  >;
-  lines.push(`  ${colors.bold(`Members (${memberEntries.length}):`)}`);
-  lines.push(
-    formatTable(
-      {
-        name: colors.dim("Name"),
-        kind: colors.dim("Kind"),
-        dataType: colors.dim("Data Type"),
-        unit: colors.dim("Unit"),
-        generator: colors.dim("Generator"),
-      },
-      memberEntries.map(([name, member]) => ({
-        name,
-        kind: member.kind,
-        dataType: member.data_type,
-        unit: member.unit ?? "",
-        generator:
-          member.kind === "variable" && member.generator
-            ? formatGeneratorSummary(member.generator)
-            : colors.dim("none"),
-      })),
-    ),
-  );
-  lines.push("");
-
-  const methodEntries = Object.entries(model.methods ?? {});
-  if (methodEntries.length > 0) {
-    lines.push(`  ${colors.bold(`Methods (${methodEntries.length}):`)}`);
-    lines.push(
-      formatTable(
-        {
-          name: colors.dim("Name"),
-          inputs: colors.dim("Inputs"),
-          outputs: colors.dim("Outputs"),
-          description: colors.dim("Description"),
-        },
-        methodEntries.map(([name, method]) => ({
-          name,
-          inputs: String(Object.keys(method.input_arguments ?? {}).length),
-          outputs: String(Object.keys(method.output_arguments ?? {}).length),
-          description: method.description ?? "",
-        })),
-      ),
-    );
-    lines.push("");
-  } else {
-    lines.push(`  ${colors.bold("Methods:")} ${colors.dim("none")}`);
-    lines.push("");
-  }
-
-  // Lifecycle
-  if (model.lifecycle && model.lifecycle.stages.length > 0) {
-    const stageNames = model.lifecycle.stages.map((s) => s.name).join(` ${colors.dim("\u2192")} `);
-    lines.push(`  ${colors.bold("Lifecycle:")} ${stageNames}`);
-  } else {
-    lines.push(`  ${colors.bold("Lifecycle:")} ${colors.dim("none")}`);
-  }
-
-  // Faults
-  if (model.faults && model.faults.length > 0) {
-    const faultNames = model.faults.map((f) => f.name).join(", ");
-    lines.push(`  ${colors.bold("Faults:")} ${faultNames}`);
-  } else {
-    lines.push(`  ${colors.bold("Faults:")} ${colors.dim("none")}`);
-  }
-
-  // Source
-  const relPath = relative(process.cwd(), sourcePath);
-  lines.push(`  ${colors.bold("Source:")} ${sourceLabel} ${colors.gray(`(${relPath})`)}`);
-
-  return lines.join("\n");
-}

package/src/commands/pause.ts

@@ -1,67 +0,0 @@
-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 PauseResumeOptions {
-  readonly json?: boolean;
-  readonly adminUrl?: string;
-  readonly timeout?: number;
-}
-
-export function registerPauseCommand(program: Command): void {
-  program
-    .command("pause")
-    .description("Pause 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 pause                           Pause the simulation`,
-    )
-    .action(async (options: PauseResumeOptions) => {
-      try {
-        await sendSimpleCommand("pause", options);
-      } catch (error) {
-        handleCommandError(error);
-      }
-    });
-}
-
-export function registerResumeCommand(program: Command): void {
-  program
-    .command("resume")
-    .description("Resume a paused 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 resume                          Resume a paused simulation`,
-    )
-    .action(async (options: PauseResumeOptions) => {
-      try {
-        await sendSimpleCommand("resume", options);
-      } catch (error) {
-        handleCommandError(error);
-      }
-    });
-}
-
-async function sendSimpleCommand(
-  type: "pause" | "resume",
-  options: PauseResumeOptions,
-): Promise<void> {
-  const adminUrl = resolveAdminUrl(options.adminUrl);
-  const timeoutMs = options.timeout ?? CONTROL_CMD_TIMEOUT_MS;
-  const command: EngineCommand = { type };
-  const result = await executeAdminCommand(adminUrl, command, timeoutMs);
-  handleCommandResult(result, options.json);
-}

package/src/commands/ps.ts

@@ -1,116 +0,0 @@
-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

@@ -1,38 +0,0 @@
-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

@@ -1,44 +0,0 @@
-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

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