miravo 0.5.0 → 0.6.1

package/src/commands/adapter.ts

@@ -1,76 +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 { parsePositiveInt, parseTimeoutSeconds } from "../lib/parse.ts";
-import { handleCommandError, handleCommandResult } from "../logger.ts";
-
-interface AdapterOptions {
-  readonly port?: number;
-  readonly host?: string;
-  readonly json?: boolean;
-  readonly adminUrl?: string;
-  readonly timeout?: number;
-}
-
-export function registerAdapterCommand(program: Command): void {
-  const adapter = program.command("adapter").description("Manage protocol adapters (MQTT, OPC UA)");
-
-  adapter
-    .command("enable <name>")
-    .description("Enable a protocol adapter (mqtt, opcua)")
-    .option("-p, --port <number>", "Override adapter port", parsePositiveInt)
-    .option("--host <host>", "Override adapter bind host")
-    .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 adapter enable mqtt             Enable MQTT adapter
-  $ miravo adapter enable opcua -p 4841    Enable OPC UA on custom port`,
-    )
-    .action(async (name: string, options: AdapterOptions) => {
-      try {
-        const adminUrl = resolveAdminUrl(options.adminUrl);
-        const timeoutMs = options.timeout ?? CONTROL_CMD_TIMEOUT_MS;
-        const config: Record<string, unknown> = {};
-        if (options.port !== undefined) config["port"] = options.port;
-        if (options.host !== undefined) config["host"] = options.host;
-        const command: EngineCommand = {
-          type: "enableAdapter",
-          adapter: name,
-          ...(Object.keys(config).length > 0 ? { config } : {}),
-        };
-        const result = await executeAdminCommand(adminUrl, command, timeoutMs);
-        handleCommandResult(result, options.json);
-      } catch (error) {
-        handleCommandError(error);
-      }
-    });
-
-  adapter
-    .command("disable <name>")
-    .description("Disable a running protocol adapter (mqtt, opcua)")
-    .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 adapter disable mqtt            Disable MQTT adapter`,
-    )
-    .action(async (name: string, options: AdapterOptions) => {
-      try {
-        const adminUrl = resolveAdminUrl(options.adminUrl);
-        const timeoutMs = options.timeout ?? CONTROL_CMD_TIMEOUT_MS;
-        const command: EngineCommand = { type: "disableAdapter", adapter: name };
-        const result = await executeAdminCommand(adminUrl, command, timeoutMs);
-        handleCommandResult(result, options.json);
-      } catch (error) {
-        handleCommandError(error);
-      }
-    });
-}

package/src/commands/cli-test-setup.ts

@@ -1,91 +0,0 @@
-/**
- * Shared CLI test utilities: suppresses logs and provides command lookup.
- *
- * Every CLI test file should import this module. It:
- * 1. Mutes all consola loggers at import time (level -999 + no-op reporter)
- * 2. Re-mutes before every test (guards against tests that unlock/reconfigure)
- *
- * Note: process.exitCode must be reset in each test file's own beforeEach/afterEach.
- */
-import { beforeEach } from "bun:test";
-import {
-  configLog,
-  configureLogger,
-  controlLog,
-  engineLog,
-  faultLog,
-  lifecycleLog,
-  lockLogger,
-  logger,
-  mqttLog,
-  unlockLogger,
-} from "../logger.ts";
-
-const noopReporter = { log() {} };
-const allLoggers = [logger, engineLog, mqttLog, configLog, lifecycleLog, faultLog, controlLog];
-
-export function muteAllLoggers(): void {
-  unlockLogger();
-  configureLogger({ quiet: true });
-  for (const l of allLoggers) {
-    l.level = -999;
-    l.setReporters([noopReporter]);
-  }
-  lockLogger();
-}
-
-muteAllLoggers();
-
-beforeEach(() => {
-  muteAllLoggers();
-});
-
-/** Resets process.exitCode — pass to beforeEach/afterEach in test files. */
-export const resetExitCode = () => {
-  process.exitCode = 0;
-};
-
-/** Creates a program and finds a command by name. */
-export async function findCliCommand(name: string) {
-  const { createProgram } = await import("../index.ts");
-  const program = createProgram();
-  const cmd = program.commands.find((c) => c.name() === name);
-  return { program, cmd };
-}
-
-/**
- * Creates a CLI program with exitOverride, runs parseAsync with the given args,
- * and swallows any Commander exitOverride errors.
- */
-export async function runCliCommand(args: string[]): Promise<void> {
-  const { createProgram } = await import("../index.ts");
-  const program = createProgram();
-  program.exitOverride();
-
-  try {
-    await program.parseAsync(["node", "miravo", ...args]);
-  } catch {
-    // Commander may throw on exitOverride
-  }
-}
-
-/**
- * Saves an env var, sets it to a new value, runs the callback, then restores it.
- */
-export async function withEnvVar<T>(
-  key: string,
-  value: string,
-  fn: () => T | Promise<T>,
-): Promise<T> {
-  const prev = Bun.env[key];
-  Bun.env[key] = value;
-  try {
-    return await fn();
-  } finally {
-    if (prev === undefined) {
-      delete Bun.env[key];
-    } else {
-      Bun.env[key] = prev;
-    }
-  }
-}

package/src/commands/fork.ts

@@ -1,219 +0,0 @@
-import { mkdir, rename, unlink } from "node:fs/promises";
-import { basename, dirname, join, resolve } from "node:path";
-import { loadTemplate, resolveModelPath } from "@miravo/core";
-import { MiravoError } from "@miravo/shared";
-import type { Command } from "commander";
-import { colors } from "consola/utils";
-import { createCatalog, resolveTemplateIdentifier } from "../lib/template-locator.ts";
-import { collectReferencedModels } from "../lib/template-utils.ts";
-import { configLog, handleCommandError, writeOutput } from "../logger.ts";
-
-export function registerForkCommand(program: Command): void {
-  const fork = program
-    .command("fork")
-    .description("Copy a model or template to your local registry for customization");
-
-  fork
-    .command("model <name>")
-    .description("Fork a model to ~/.miravo/registry/local/models/")
-    .option("--force", "Overwrite if already exists in local")
-    .addHelpText(
-      "after",
-      `
-Examples:
-  $ miravo fork model centrifugal-pump     Fork a model for customization
-  $ miravo fork model centrifugal-pump --force  Overwrite existing fork`,
-    )
-    .action(async (name: string, options: { readonly force?: boolean }) => {
-      await forkModelAction(name, options);
-    });
-
-  fork
-    .command("template <idNameOrPath>")
-    .description("Fork a template and its referenced models to ~/.miravo/registry/local/")
-    .option("--force", "Overwrite if already exists in local")
-    .option("--models-only", "Only fork referenced models, skip the template itself")
-    .addHelpText(
-      "after",
-      `
-Examples:
-  $ miravo fork template water-treatment   Fork template + referenced models
-  $ miravo fork template water-treatment --models-only  Fork only models`,
-    )
-    .action(
-      async (
-        idNameOrPath: string,
-        options: { readonly force?: boolean; readonly modelsOnly?: boolean },
-      ) => {
-        await forkTemplateAction(idNameOrPath, options);
-      },
-    );
-}
-
-// ---------------------------------------------------------------------------
-// Fork model
-// ---------------------------------------------------------------------------
-
-async function forkModelAction(name: string, options: { readonly force?: boolean }): Promise<void> {
-  try {
-    const catalog = createCatalog();
-    const resolvedPath = await catalog.resolveModel(name);
-    const localModelsDir = join(catalog.getLocalRegistryDir(), "models");
-    await mkdir(localModelsDir, { recursive: true });
-
-    const targetPath = join(localModelsDir, basename(resolvedPath));
-    const copied = await atomicCopyFile({
-      sourcePath: resolvedPath,
-      targetPath,
-      label: `model "${name}"`,
-      force: options.force ?? false,
-    });
-
-    writeOutput();
-    if (copied) {
-      writeOutput(`  ${colors.bold("Forked to local:")}`);
-      writeOutput(`    models/${basename(resolvedPath)}`);
-    }
-    writeOutput();
-  } catch (error) {
-    handleCommandError(error);
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Fork template
-// ---------------------------------------------------------------------------
-
-async function forkTemplateAction(
-  idNameOrPath: string,
-  options: { readonly force?: boolean; readonly modelsOnly?: boolean },
-): Promise<void> {
-  try {
-    const catalog = createCatalog();
-    const resolvedPath = await resolveTemplateIdentifier(idNameOrPath, catalog);
-
-    const localDir = catalog.getLocalRegistryDir();
-    const localModelsDir = join(localDir, "models");
-    const localTemplatesDir = join(localDir, "templates");
-    await mkdir(localModelsDir, { recursive: true });
-    await mkdir(localTemplatesDir, { recursive: true });
-
-    const forked: string[] = [];
-    const skipped: string[] = [];
-
-    // Fork the template itself (unless --models-only)
-    if (!options.modelsOnly) {
-      const targetPath = join(localTemplatesDir, basename(resolvedPath));
-      const copied = await atomicCopyFile({
-        sourcePath: resolvedPath,
-        targetPath,
-        label: `template "${idNameOrPath}"`,
-        force: options.force ?? false,
-      });
-      if (copied) {
-        forked.push(`templates/${basename(resolvedPath)}`);
-      } else {
-        skipped.push(`templates/${basename(resolvedPath)}`);
-      }
-    }
-
-    // Fork referenced models
-    const template = await loadTemplate(resolvedPath);
-    const inlineModels = new Set((template.models ?? []).map((m) => m.model.name));
-    const referencedModels = collectReferencedModels(template);
-    const searchPaths = catalog.getTemplateValidationSearchPaths(resolvedPath);
-
-    for (const modelName of referencedModels) {
-      if (inlineModels.has(modelName)) continue;
-
-      let sourceModelPath: string;
-      try {
-        sourceModelPath = await resolveModelPath(modelName, searchPaths);
-      } catch {
-        configLog.warn(`Skipped model "${modelName}": not found.`);
-        continue;
-      }
-
-      const targetModelPath = join(localModelsDir, basename(sourceModelPath));
-      const copied = await atomicCopyFile({
-        sourcePath: sourceModelPath,
-        targetPath: targetModelPath,
-        label: `model "${modelName}"`,
-        force: options.force ?? false,
-      });
-      if (copied) {
-        forked.push(`models/${basename(sourceModelPath)}`);
-      } else {
-        skipped.push(`models/${basename(sourceModelPath)}`);
-      }
-    }
-
-    writeOutput();
-    if (forked.length > 0) {
-      writeOutput(`  ${colors.bold("Forked to local:")}`);
-      for (const f of forked) {
-        writeOutput(`    ${f}`);
-      }
-    }
-    if (skipped.length > 0) {
-      for (const s of skipped) {
-        writeOutput(`    ${s} ${colors.dim("(skipped — already in local)")}`);
-      }
-    }
-    if (forked.length === 0 && skipped.length === 0) {
-      writeOutput("  Nothing to fork.");
-    }
-    writeOutput();
-  } catch (error) {
-    handleCommandError(error);
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-
-/**
- * Copy a file using stage-to-temp-and-rename for atomic writes.
- * Returns true if the file was copied, false if skipped (already exists and no --force).
- */
-async function atomicCopyFile(options: {
-  readonly sourcePath: string;
-  readonly targetPath: string;
-  readonly label: string;
-  readonly force: boolean;
-}): Promise<boolean> {
-  const { sourcePath, targetPath, label, force } = options;
-
-  if (resolve(sourcePath) === resolve(targetPath)) {
-    configLog.warn(`Skipped ${label}: source and destination are the same.`);
-    return false;
-  }
-
-  const targetExists = await Bun.file(targetPath).exists();
-  if (targetExists && !force) {
-    configLog.info(`Skipped ${label}: already exists in local. Use --force to overwrite.`);
-    return false;
-  }
-
-  const contents = await Bun.file(sourcePath).text();
-  const tmpPath = join(dirname(targetPath), `.${basename(targetPath)}.tmp`);
-
-  try {
-    await Bun.write(tmpPath, contents);
-    await rename(tmpPath, targetPath);
-  } catch {
-    // Clean up temp file on failure
-    try {
-      await unlink(tmpPath);
-    } catch {
-      // Ignore cleanup errors
-    }
-    throw new MiravoError(
-      `Failed to write ${label} to "${targetPath}".`,
-      `Ensure "${dirname(targetPath)}" is writable by the current user.`,
-    );
-  }
-
-  return true;
-}

package/src/commands/inject.test.ts

@@ -1,57 +0,0 @@
-import { afterEach, beforeEach, describe, expect, test } from "bun:test";
-import { findCliCommand, resetExitCode } from "./cli-test-setup.ts";
-
-beforeEach(resetExitCode);
-afterEach(resetExitCode);
-
-describe("miravo inject", () => {
-  test("sets exit code 1 with invalid admin URL", async () => {
-    const { program } = await findCliCommand("inject");
-    program.exitOverride();
-
-    try {
-      await program.parseAsync([
-        "node",
-        "miravo",
-        "inject",
-        "pump-001",
-        "cavitation",
-        "--admin-url",
-        "not-a-url",
-      ]);
-    } catch {
-      // Expected
-    }
-
-    expect(process.exitCode).toBe(1);
-  });
-
-  test("requires terminal for interactive mode", async () => {
-    // Save originals
-    const origStdoutTTY = process.stdout.isTTY;
-    const origStdinTTY = process.stdin.isTTY;
-
-    try {
-      // Simulate non-TTY
-      Object.defineProperty(process.stdout, "isTTY", { value: false, configurable: true });
-      Object.defineProperty(process.stdin, "isTTY", { value: false, configurable: true });
-
-      // Import inject action indirectly via program
-      const { program } = await findCliCommand("inject");
-      program.exitOverride();
-
-      try {
-        // No positional args → interactive mode needed → should fail in non-TTY
-        await program.parseAsync(["node", "miravo", "inject"]);
-      } catch {
-        // Expected
-      }
-
-      expect(process.exitCode).toBe(1);
-    } finally {
-      // Restore
-      Object.defineProperty(process.stdout, "isTTY", { value: origStdoutTTY, configurable: true });
-      Object.defineProperty(process.stdin, "isTTY", { value: origStdinTTY, configurable: true });
-    }
-  });
-});

package/src/commands/inject.ts

@@ -1,212 +0,0 @@
-import { confirm, intro, isCancel, outro, select } from "@clack/prompts";
-import type { EngineCommand } from "@miravo/shared";
-import { CONTROL_CMD_TIMEOUT_MS, MiravoError } from "@miravo/shared";
-import type { Command } from "commander";
-import { executeAdminCommand, getAdminState, resolveAdminUrl } from "../lib/admin-client.ts";
-import { parseTimeoutSeconds } from "../lib/parse.ts";
-import { faultLog, handleCommandError } from "../logger.ts";
-
-interface InjectOptions {
-  readonly clear?: boolean;
-  readonly json?: boolean;
-  readonly name?: string;
-  readonly adminUrl?: string;
-  readonly timeout?: number;
-}
-
-/**
- * Register the `miravo inject` command with the root Commander program.
- * Triggers or clears a fault on a running twin instance via the admin HTTP server.
- */
-export function registerInjectCommand(program: Command): void {
-  program
-    .command("inject [instanceId] [fault]")
-    .description("Trigger or clear a fault on a running instance")
-    .option("--clear", "Clear the fault instead of triggering it")
-    .option("--json", "Machine-readable JSON output")
-    .option("--name <name>", "Target simulation name")
-    .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 inject                          Interactive mode (pick instance + fault)
-  $ miravo inject pump-001 cavitation      Trigger fault directly
-  $ miravo inject pump-001 cavitation --clear  Clear an active fault`,
-    )
-    .action(
-      async (instanceId: string | undefined, fault: string | undefined, options: InjectOptions) => {
-        await injectAction(instanceId, fault, options);
-      },
-    );
-}
-
-// ---------------------------------------------------------------------------
-// Action
-// ---------------------------------------------------------------------------
-
-async function injectAction(
-  instanceId: string | undefined,
-  fault: string | undefined,
-  options: InjectOptions,
-): Promise<void> {
-  // Fail fast before broker connect when interactive prompts would be required.
-  if ((!instanceId || !fault) && (!process.stdout.isTTY || !process.stdin.isTTY)) {
-    faultLog.error("Interactive mode requires a terminal. Usage: miravo inject <instance> <fault>");
-    process.exitCode = 1;
-    return;
-  }
-
-  try {
-    const timeoutMs = options.timeout ?? CONTROL_CMD_TIMEOUT_MS;
-    const adminUrl = resolveAdminUrl(options.adminUrl);
-    const stateResult = await getTargetState(adminUrl, timeoutMs, options.name);
-
-    let targetInstance = instanceId;
-    let targetFault = fault;
-
-    // Interactive mode: pick instance and fault via prompts
-    if (!targetInstance || !targetFault) {
-      if (!process.stdout.isTTY || !process.stdin.isTTY) {
-        faultLog.error(
-          "Interactive mode requires a terminal. Usage: miravo inject <instance> <fault>",
-        );
-        process.exitCode = 1;
-        return;
-      }
-
-      const picked = await pickInstanceAndFault(stateResult, options.clear ?? false);
-      if (!picked) return;
-
-      targetInstance = picked.instanceId;
-      targetFault = picked.fault;
-    }
-
-    const command: EngineCommand = options.clear
-      ? { type: "clearFault", instanceId: targetInstance, fault: targetFault }
-      : { type: "triggerFault", instanceId: targetInstance, fault: targetFault };
-
-    const result = await executeAdminCommand(adminUrl, command, timeoutMs);
-
-    if (options.json) {
-      console.log(JSON.stringify(result, null, 2));
-    } else if (result.success) {
-      faultLog.success(result.message);
-    } else {
-      faultLog.error(result.message);
-      if (result.error) {
-        faultLog.error(`Fix: ${result.error}`);
-      }
-    }
-    if (!result.success) process.exitCode = 1;
-  } catch (error) {
-    handleCommandError(error, faultLog);
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Read state snapshot from admin server
-// ---------------------------------------------------------------------------
-
-interface StateSnapshot {
-  readonly models: ReadonlyArray<{
-    readonly name: string;
-    readonly faultNames: readonly string[];
-  }>;
-  readonly instances: ReadonlyArray<{
-    readonly id: string;
-    readonly model: string;
-    readonly lifecycleStage: string;
-    readonly activeFaults: readonly string[];
-  }>;
-}
-
-async function getTargetState(
-  adminUrl: string,
-  timeoutMs: number,
-  expectedName?: string,
-): Promise<StateSnapshot> {
-  const state = await getAdminState(adminUrl, timeoutMs);
-  if (expectedName && state.simulationName !== expectedName) {
-    throw new MiravoError(
-      `Connected to simulation "${state.simulationName}" instead of "${expectedName}".`,
-      "Pass --admin-url for the correct Miravo process, or omit --name to target the connected simulation.",
-    );
-  }
-  return state as StateSnapshot;
-}
-
-// ---------------------------------------------------------------------------
-// Interactive: pick instance and fault
-// ---------------------------------------------------------------------------
-
-async function pickInstanceAndFault(
-  state: StateSnapshot,
-  clearing: boolean,
-): Promise<{ instanceId: string; fault: string } | null> {
-  if (state.instances.length === 0) {
-    faultLog.error("No instances running. Spawn instances first with 'miravo start'.");
-    process.exitCode = 1;
-    return null;
-  }
-
-  intro(clearing ? "Clear a fault" : "Inject a fault");
-
-  // Pick instance
-  const instanceChoice = await select({
-    message: "Which instance?",
-    options: state.instances.map((inst) => ({
-      value: inst.id,
-      label: inst.id,
-      hint: `${inst.model} · ${inst.lifecycleStage}${inst.activeFaults.length > 0 ? ` · faults: ${inst.activeFaults.join(", ")}` : ""}`,
-    })),
-  });
-
-  if (isCancel(instanceChoice)) {
-    outro("Cancelled.");
-    return null;
-  }
-
-  const selectedInstance = state.instances.find((i) => i.id === instanceChoice);
-  if (!selectedInstance) return null;
-
-  // Get available faults for this instance's model
-  const model = state.models.find((m) => m.name === selectedInstance.model);
-  const availableFaults = clearing ? selectedInstance.activeFaults : (model?.faultNames ?? []);
-
-  if (availableFaults.length === 0) {
-    const reason = clearing
-      ? `No active faults on ${selectedInstance.id}.`
-      : `Model "${selectedInstance.model}" has no defined faults.`;
-    outro(reason);
-    return null;
-  }
-
-  // Pick fault
-  const faultChoice = await select({
-    message: clearing ? "Which fault to clear?" : "Which fault to trigger?",
-    options: availableFaults.map((f) => ({
-      value: f,
-      label: f,
-    })),
-  });
-
-  if (isCancel(faultChoice)) {
-    outro("Cancelled.");
-    return null;
-  }
-
-  // Confirm
-  const action = clearing ? "Clear" : "Trigger";
-  const confirmed = await confirm({
-    message: `${action} ${faultChoice as string} on ${instanceChoice as string}?`,
-  });
-
-  if (isCancel(confirmed) || !confirmed) {
-    outro("Cancelled.");
-    return null;
-  }
-
-  return { instanceId: instanceChoice as string, fault: faultChoice as string };
-}