miravo 0.1.4 → 0.2.1

package/src/commands/fork.ts

@@ -0,0 +1,205 @@
+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")
+    .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")
+    .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

@@ -13,7 +13,7 @@ describe("miravo inject", () => {
     const optionNames = injectCmd?.options.map((o) => o.long);
     expect(optionNames).toContain("--clear");
     expect(optionNames).toContain("--name");
-    expect(optionNames).toContain("--template");
+    expect(optionNames).toContain("--admin-url");
   });
 
   test("accepts instanceId and fault as positional arguments", async () => {
@@ -29,26 +29,24 @@ describe("miravo inject", () => {
     expect(args?.[1]?.required).toBe(false);
   });
 
-  test("sets exit code 1 when connecting to non-existent broker", async () => {
+  test("sets exit code 1 with invalid admin URL", async () => {
     const { program } = await findCliCommand("inject");
     program.exitOverride();
 
     try {
-      // Use a port that's very unlikely to have a broker running
       await program.parseAsync([
         "node",
         "miravo",
         "inject",
         "pump-001",
         "cavitation",
-        "--template",
-        "/nonexistent.miravo.yaml",
+        "--admin-url",
+        "not-a-url",
       ]);
     } catch {
-      // Expected: either exitOverride or connection error
+      // Expected
     }
 
-    // Should fail — either the template doesn't exist or the broker isn't running
     expect(process.exitCode).toBe(1);
   });
 
@@ -73,8 +71,7 @@ describe("miravo inject", () => {
         // Expected
       }
 
-      // Should not succeed without a terminal in interactive mode
-      // The exact exit behavior depends on broker connection attempt
+      expect(process.exitCode).toBe(1);
     } finally {
       // Restore
       Object.defineProperty(process.stdout, "isTTY", { value: origStdoutTTY, configurable: true });

package/src/commands/inject.ts

@@ -1,22 +1,21 @@
 import { confirm, intro, isCancel, outro, select } from "@clack/prompts";
-import type { CommandResult, EngineCommand } from "@miravo/shared";
-import { CONTROL_CMD_TIMEOUT_MS, EngineStateSnapshotSchema } from "@miravo/shared";
+import type { EngineCommand } from "@miravo/shared";
+import { CONTROL_CMD_TIMEOUT_MS, MiravoError } from "@miravo/shared";
 import type { Command } from "commander";
-import { connectToBroker, disconnectClient } from "../lib/mqtt-client.ts";
+import { executeAdminCommand, getAdminState, resolveAdminUrl } from "../lib/admin-client.ts";
 import { parseDurationMs } from "../lib/parse.ts";
-import { resolveTargetSimulation, type SimulationTopics } from "../lib/resolve-simulation.ts";
 import { faultLog, handleCommandError } from "../logger.ts";
 
 interface InjectOptions {
   readonly clear?: boolean;
   readonly name?: string;
-  readonly template?: 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 MQTT control plane.
+ * Triggers or clears a fault on a running twin instance via the admin HTTP server.
  */
 export function registerInjectCommand(program: Command): void {
   program
@@ -24,13 +23,10 @@ export function registerInjectCommand(program: Command): void {
     .description("Inject or clear a fault on a running twin instance")
     .option("--clear", "Clear the fault instead of triggering it")
     .option("--name <name>", "Target simulation name")
-    .option(
-      "--template <path>",
-      "Path to .miravo.yaml for broker connection info (env: MIRAVO_TEMPLATE)",
-    )
+    .option("--admin-url <url>", "Miravo admin server URL (env: MIRAVO_ADMIN_URL)")
     .option(
       "--timeout <ms>",
-      "Connection/command timeout in milliseconds (default: 5000)",
+      "Admin request timeout in milliseconds (default: 5000)",
       parseDurationMs,
     )
     .action(
@@ -57,65 +53,44 @@ async function injectAction(
   }
 
   try {
-    const templateOption = options.template ?? Bun.env["MIRAVO_TEMPLATE"];
     const timeoutMs = options.timeout ?? CONTROL_CMD_TIMEOUT_MS;
-    const { client, brokerInfo } = await connectToBroker(templateOption, timeoutMs);
-
-    try {
-      const target = await resolveTargetSimulation(client, {
-        timeoutMs,
-        brokerUrl: brokerInfo.url,
-        ...(options.name !== undefined ? { name: options.name } : {}),
-      });
-
-      let targetInstance = instanceId;
-      let targetFault = fault;
+    const adminUrl = resolveAdminUrl(options.adminUrl);
+    const stateResult = await getTargetState(adminUrl, timeoutMs, options.name);
 
-      // 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;
-        }
+    let targetInstance = instanceId;
+    let targetFault = fault;
 
-        const stateResult = await waitForState(
-          client,
-          brokerInfo.url,
-          timeoutMs,
-          target.topics,
-          target.simulationName,
+    // 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>",
         );
-        if (!stateResult) return;
+        process.exitCode = 1;
+        return;
+      }
 
-        const picked = await pickInstanceAndFault(stateResult, options.clear ?? false);
-        if (!picked) return;
+      const picked = await pickInstanceAndFault(stateResult, options.clear ?? false);
+      if (!picked) return;
 
-        targetInstance = picked.instanceId;
-        targetFault = picked.fault;
-      }
+      targetInstance = picked.instanceId;
+      targetFault = picked.fault;
+    }
 
-      // Build command
-      const command: EngineCommand = options.clear
-        ? { type: "clearFault", instanceId: targetInstance, fault: targetFault }
-        : { type: "triggerFault", instanceId: targetInstance, fault: targetFault };
+    const command: EngineCommand = options.clear
+      ? { type: "clearFault", instanceId: targetInstance, fault: targetFault }
+      : { type: "triggerFault", instanceId: targetInstance, fault: targetFault };
 
-      // Send and wait for result
-      const result = await sendCommand(client, command, timeoutMs, target.topics);
+    const result = await executeAdminCommand(adminUrl, command, timeoutMs);
 
-      if (result.success) {
-        faultLog.success(result.message);
-      } else {
-        faultLog.error(result.message);
-        if (result.error) {
-          faultLog.error(`Fix: ${result.error}`);
-        }
-        process.exitCode = 1;
+    if (result.success) {
+      faultLog.success(result.message);
+    } else {
+      faultLog.error(result.message);
+      if (result.error) {
+        faultLog.error(`Fix: ${result.error}`);
       }
-    } finally {
-      disconnectClient(client);
+      process.exitCode = 1;
     }
   } catch (error) {
     handleCommandError(error, faultLog);
@@ -123,7 +98,7 @@ async function injectAction(
 }
 
 // ---------------------------------------------------------------------------
-// Wait for state snapshot from control plane
+// Read state snapshot from admin server
 // ---------------------------------------------------------------------------
 
 interface StateSnapshot {
@@ -139,47 +114,19 @@ interface StateSnapshot {
   }>;
 }
 
-function waitForState(
-  client: import("mqtt").MqttClient,
-  brokerUrl: string,
+async function getTargetState(
+  adminUrl: string,
   timeoutMs: number,
-  topics: SimulationTopics,
-  simulationName: string,
-): Promise<StateSnapshot | null> {
-  return new Promise((resolve) => {
-    const cleanup = (): void => {
-      clearTimeout(timer);
-      client.off("message", handler);
-      client.unsubscribe(topics.state);
-    };
-
-    const timer = setTimeout(() => {
-      cleanup();
-      faultLog.error(
-        `No running simulation named "${simulationName}" found on ${brokerUrl}. Start one with 'miravo start --name ${simulationName}'.`,
-      );
-      process.exitCode = 1;
-      resolve(null);
-    }, timeoutMs);
-
-    const handler = (topic: string, message: Buffer): void => {
-      if (topic !== topics.state) return;
-      try {
-        const parsed = EngineStateSnapshotSchema.safeParse(JSON.parse(message.toString()));
-        if (!parsed.success) {
-          // Skip malformed payloads — wait for a valid one or timeout.
-          return;
-        }
-        cleanup();
-        resolve(parsed.data as StateSnapshot);
-      } catch {
-        // JSON parse error — skip and wait for valid data.
-      }
-    };
-
-    client.subscribe(topics.state, { qos: 0 });
-    client.on("message", handler);
-  });
+  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;
 }
 
 // ---------------------------------------------------------------------------
@@ -255,60 +202,3 @@ async function pickInstanceAndFault(
 
   return { instanceId: instanceChoice as string, fault: faultChoice as string };
 }
-
-// ---------------------------------------------------------------------------
-// Send command and wait for result
-// ---------------------------------------------------------------------------
-
-function sendCommand(
-  client: import("mqtt").MqttClient,
-  command: EngineCommand,
-  timeoutMs: number,
-  topics: SimulationTopics,
-): Promise<CommandResult> {
-  const commandWithCorrelation: EngineCommand = {
-    ...command,
-    correlationId: crypto.randomUUID(),
-  };
-
-  return new Promise((resolve) => {
-    const cleanup = (): void => {
-      clearTimeout(timer);
-      client.off("message", handler);
-      client.unsubscribe(topics.cmdResult);
-    };
-
-    const timer = setTimeout(() => {
-      cleanup();
-      resolve({
-        success: false,
-        command: command.type,
-        correlationId: commandWithCorrelation.correlationId,
-        message: "Command timed out.",
-        error: `No response within ${timeoutMs}ms. The simulation may not have a control plane enabled.`,
-      });
-    }, timeoutMs);
-
-    const handler = (topic: string, message: Buffer): void => {
-      if (topic !== topics.cmdResult) return;
-      try {
-        const result = JSON.parse(message.toString()) as CommandResult;
-        if (result.correlationId !== commandWithCorrelation.correlationId) return;
-        cleanup();
-        resolve(result);
-      } catch {
-        cleanup();
-        resolve({
-          success: false,
-          command: command.type,
-          correlationId: commandWithCorrelation.correlationId,
-          message: "Received invalid response from simulation.",
-        });
-      }
-    };
-
-    client.subscribe(topics.cmdResult, { qos: 0 });
-    client.on("message", handler);
-    client.publish(topics.cmd, JSON.stringify(commandWithCorrelation), { qos: 0 });
-  });
-}

package/src/commands/models.test.ts

@@ -1,14 +1,14 @@
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 import { resolve } from "node:path";
 import { loadTwinModel } from "@miravo/core";
-import type { GeneratorConfig } from "@miravo/shared";
+import { type GeneratorConfig, TwinModelSchema } from "@miravo/shared";
 import { stripAnsi } from "consola/utils";
 import { configureLogger } from "../logger.ts";
 import { formatGeneratorSummary, formatModelInspect } from "./models.ts";
 
 configureLogger({ silent: true });
 
-const modelsDir = resolve(import.meta.dir, "..", "..", "..", "..", "models");
+const modelsDir = resolve(import.meta.dir, "..", "..", "..", "content", "models");
 
 beforeEach(() => {
   process.exitCode = 0;
@@ -54,6 +54,16 @@ describe("formatGeneratorSummary", () => {
       },
       "health-dependent (2 stages)",
     ],
+    [
+      "gate",
+      {
+        type: "gate",
+        enabled_member: "run_command",
+        input: { member: "speed_command" },
+        disabled_value: 0,
+      },
+      "gate (enabled: run_command)",
+    ],
   ];
 
   test.each(cases)("%s → %s", (_label, config, expected) => {
@@ -78,20 +88,34 @@ describe("formatModelInspect", () => {
     expect(output).toContain("centrifugal-pump");
     expect(output).toContain("Parameters:");
     expect(output).toContain("rated_rpm");
-    expect(output).toContain("Sensors (10):");
+    expect(output).toContain("Members (29):");
+    expect(output).toContain("Methods (5):");
+    expect(output).toContain("availability_state");
     expect(output).toContain("Lifecycle: healthy");
     expect(output).toContain("\u2192");
     expect(output).toContain("Faults:");
     expect(output).toContain("Source: built-in");
   });
 
-  test("model without lifecycle shows 'none'", async () => {
-    const model = await loadTwinModel(resolve(modelsDir, "storage-tank.twin.yaml"));
-    const raw = formatModelInspect(model, resolve(modelsDir, "storage-tank.twin.yaml"), "built-in");
+  test("model without lifecycle shows 'none'", () => {
+    const model = TwinModelSchema.parse({
+      schema_version: "2",
+      model: { name: "test-vessel", description: "Minimal vessel" },
+      members: {
+        level: {
+          kind: "variable",
+          data_type: "Double",
+          access: "read",
+          unit: "%",
+          generator: { type: "noise", center: 65, stddev: 1.5 },
+        },
+      },
+    });
+    const raw = formatModelInspect(model, "/tmp/test-vessel.twin.yaml", "test");
     const output = stripAnsi(raw);
 
-    expect(output).toContain("storage-tank");
-    expect(output).toContain("Parameters:");
+    expect(output).toContain("test-vessel");
+    expect(output).toContain("Methods: none");
     expect(output).toContain("Lifecycle: none");
   });
 });