miravo 0.6.0 → 0.6.2

package/src/commands/export.ts

@@ -1,404 +0,0 @@
-import type { ProtocolName } from "@miravo/shared";
-import { CONTROL_CMD_TIMEOUT_MS } from "@miravo/shared";
-import type { Command } from "commander";
-import { getLeDtJson, getManifest, resolveAdminUrl } from "../lib/admin-client.ts";
-import { LE_DRIVER_NAMES } from "../lib/le/le-drivers.ts";
-import { buildDesiredStateFromTemplate } from "../lib/le/le-static-planner.ts";
-import { buildLeExport } from "../lib/le/le-template-exporter.ts";
-import { MODBUS_VALUE_TYPE, OPCUA_VALUE_TYPE } from "../lib/le/le-value-types.ts";
-import { parseTimeoutSeconds } from "../lib/parse.ts";
-import { createCatalog, resolveTemplateIdentifier } from "../lib/template-locator.ts";
-import { handleCommandError, writeOutput } from "../logger.ts";
-
-const VALID_PROTOCOLS = ["opcua", "modbus", "mqtt"] as const;
-
-/** LE DeviceHub CSV header — matches real LE export format. */
-const LE_CSV_HEADER =
-  "deviceId,deviceName,driverName,name,tagName,description,valueType,registerId,publishCoV,tagFormula,metaData,Retain,Qos,address,count,pollingInterval,endianness";
-
-// ---------------------------------------------------------------------------
-// Command
-// ---------------------------------------------------------------------------
-
-interface ExportLeTagsOptions {
-  readonly device: string;
-  readonly protocol: string;
-  readonly instance?: string;
-  readonly output?: string;
-  readonly adminUrl?: string;
-  readonly timeout?: number;
-}
-
-export function registerExportCommand(program: Command): void {
-  const exportCmd = program
-    .command("export")
-    .description("Export simulation data in platform-specific formats");
-
-  // -------------------------------------------------------------------------
-  // miravo export le-template — offline full LE template (JSON + tags CSV)
-  // -------------------------------------------------------------------------
-
-  interface ExportLeOptions {
-    readonly template: string;
-    readonly host: string;
-    readonly protocol?: string;
-    readonly output?: string;
-    readonly modelsDir?: string;
-  }
-
-  exportCmd
-    .command("le-template")
-    .description(
-      "Export a full Litmus Edge template (devices + DT) and tags CSV — no running instance needed",
-    )
-    .requiredOption("-t, --template <id>", "Template ID, name, or path (required)")
-    .option("--host <hostname>", "Source hostname embedded in device endpoints", "localhost")
-    .option("--protocol <name>", "Protocol override: opcua, modbus, or mqtt")
-    .option("-o, --output <prefix>", "Output file prefix (default: <template-id>)")
-    .option("--models-dir <path>", "Extra directory to search for .twin.yaml model files")
-    .addHelpText(
-      "after",
-      `
-Examples:
-  $ miravo export le-template -t smart-factory
-  $ miravo export le-template -t smart-factory --host 192.168.1.100 --protocol opcua
-  $ miravo export le-template -t ./my.miravo.yaml --models-dir ./models
-  $ miravo export le-template -t smart-factory -o ./out/sf`,
-    )
-    .action(async (options: ExportLeOptions) => {
-      try {
-        if (
-          options.protocol &&
-          !VALID_PROTOCOLS.includes(options.protocol as (typeof VALID_PROTOCOLS)[number])
-        ) {
-          writeOutput(`Unknown protocol "${options.protocol}". Valid options: opcua, modbus, mqtt`);
-          process.exitCode = 1;
-          return;
-        }
-
-        const catalog = options.modelsDir
-          ? createCatalog({ extraModelsDir: options.modelsDir })
-          : createCatalog();
-        const templatePath = await resolveTemplateIdentifier(options.template, catalog);
-        const { templateId, desired } = await buildDesiredStateFromTemplate({
-          templatePath,
-          catalog,
-          sourceHostname: options.host,
-          protocol: options.protocol as ProtocolName | undefined,
-        });
-
-        const { templateJson, tagsCSV } = buildLeExport(desired, templateId);
-
-        const prefix = options.output ?? templateId;
-        const jsonPath = `${prefix}.le-template.json`;
-        const csvPath = `${prefix}-tags.csv`;
-
-        await Bun.write(jsonPath, templateJson);
-        await Bun.write(csvPath, tagsCSV);
-
-        writeOutput(`LE template → ${jsonPath}`);
-        writeOutput(`Tags CSV   → ${csvPath}`);
-      } catch (error) {
-        handleCommandError(error);
-      }
-    });
-
-  exportCmd
-    .command("le-tags")
-    .description("Export tags as Litmus Edge DeviceHub CSV for bulk import")
-    .requiredOption("--device <name>", "LE device name (required)")
-    .requiredOption("--protocol <name>", "Protocol to export: opcua, modbus, or mqtt (required)")
-    .option("--instance <id>", "Export only tags for a specific instance")
-    .option("-o, --output <file>", "Write CSV to file instead of stdout")
-    .option("--admin-url <url>", "Admin API URL (env: MIRAVO_ADMIN_URL)")
-    .option("--timeout <seconds>", "Timeout in seconds (default: 5)", parseTimeoutSeconds)
-    .addHelpText(
-      "after",
-      `
-Examples:
-  $ miravo export le-tags --device DTW-FAB-PLC --protocol opcua
-  $ miravo export le-tags --device DTW-FAB-PLC --protocol modbus --instance pump-001
-  $ miravo export le-tags --device DTW-FAB-PLC --protocol mqtt -o tags.csv`,
-    )
-    .action(async (options: ExportLeTagsOptions) => {
-      try {
-        if (!VALID_PROTOCOLS.includes(options.protocol as (typeof VALID_PROTOCOLS)[number])) {
-          writeOutput(
-            `Unknown protocol "${options.protocol}". Valid options: ${VALID_PROTOCOLS.join(", ")}`,
-          );
-          process.exitCode = 1;
-          return;
-        }
-
-        const adminUrl = resolveAdminUrl(options.adminUrl);
-        const timeoutMs = options.timeout ?? CONTROL_CMD_TIMEOUT_MS;
-        const manifest = await getManifest(adminUrl, timeoutMs);
-
-        const allTags = manifest["tags"] as Array<Record<string, unknown>> | undefined;
-
-        if (!allTags || allTags.length === 0) {
-          writeOutput("No tags found in manifest.");
-          return;
-        }
-
-        // Filter by instance if specified
-        const filteredTags = options.instance
-          ? allTags.filter((s) => s["instance"] === options.instance)
-          : allTags;
-
-        if (filteredTags.length === 0) {
-          writeOutput(
-            options.instance
-              ? `No tags found for instance "${options.instance}".`
-              : "No tags found in manifest.",
-          );
-          return;
-        }
-
-        const protocol = options.protocol;
-        const driverName = LE_DRIVER_NAMES[protocol as keyof typeof LE_DRIVER_NAMES] ?? protocol;
-        const deviceName = options.device;
-
-        const csvRows = [LE_CSV_HEADER];
-        let totalRows = 0;
-
-        for (const tag of filteredTags) {
-          const protocols = tag["protocols"] as Record<string, Record<string, unknown>> | undefined;
-          const memberName = String(tag["member"] ?? "");
-          const browsePath = String(tag["browsePath"] ?? "");
-          const dataType = String(tag["dataType"] ?? "");
-          const unit = typeof tag["unit"] === "string" ? tag["unit"] : undefined;
-          const euRangeRaw = tag["euRange"];
-          const euRange =
-            Array.isArray(euRangeRaw) &&
-            euRangeRaw.length === 2 &&
-            typeof euRangeRaw[0] === "number" &&
-            typeof euRangeRaw[1] === "number"
-              ? ([euRangeRaw[0], euRangeRaw[1]] as [number, number])
-              : undefined;
-          const model = String(tag["model"] ?? "");
-          const instance = String(tag["instance"] ?? "");
-          const access = String(tag["access"] ?? "");
-          const protocolData = protocols?.[protocol];
-          if (!protocolData) continue; // tag not exposed on this protocol (e.g. String on Modbus, property on MQTT)
-
-          csvRows.push(
-            buildRow(protocol, {
-              deviceName,
-              driverName,
-              memberName,
-              browsePath,
-              dataType,
-              protocolData,
-              model,
-              instance,
-              access,
-              ...(unit !== undefined && { unit }),
-              ...(euRange !== undefined && { euRange }),
-            }),
-          );
-          totalRows++;
-        }
-
-        const csv = `${csvRows.join("\n")}\n`;
-
-        if (options.output) {
-          await Bun.write(options.output, csv);
-          writeOutput(`Wrote ${totalRows} tags to ${options.output}`);
-        } else {
-          writeOutput(csv);
-        }
-      } catch (error) {
-        handleCommandError(error);
-      }
-    });
-
-  // -------------------------------------------------------------------------
-  // miravo export le-dt — export a model as Litmus Edge Digital Twin JSON
-  // -------------------------------------------------------------------------
-
-  exportCmd
-    .command("le-dt")
-    .description("Export a model as Litmus Edge Digital Twin JSON for import into LE")
-    .requiredOption("--model <name>", "Model name to export (required)")
-    .option("-o, --output <file>", "Write JSON to file instead of stdout")
-    .option("--admin-url <url>", "Admin API URL (env: MIRAVO_ADMIN_URL)")
-    .option("--timeout <seconds>", "Timeout in seconds (default: 5)", parseTimeoutSeconds)
-    .addHelpText(
-      "after",
-      `
-Examples:
-  $ miravo export le-dt --model centrifugal-pump
-  $ miravo export le-dt --model centrifugal-pump -o pump.le-dt.json`,
-    )
-    .action(
-      async (options: {
-        readonly model: string;
-        readonly output?: string;
-        readonly adminUrl?: string;
-        readonly timeout?: number;
-      }) => {
-        try {
-          const adminUrl = resolveAdminUrl(options.adminUrl);
-          const timeoutMs = options.timeout ?? CONTROL_CMD_TIMEOUT_MS;
-          const leDt = await getLeDtJson(adminUrl, options.model, timeoutMs);
-          const json = JSON.stringify(leDt, null, 2);
-
-          if (options.output) {
-            await Bun.write(options.output, json);
-            writeOutput(`Wrote LE Digital Twin JSON to ${options.output}`);
-          } else {
-            writeOutput(json);
-          }
-        } catch (error) {
-          handleCommandError(error);
-        }
-      },
-    );
-}
-
-// ---------------------------------------------------------------------------
-// Row builder
-// ---------------------------------------------------------------------------
-
-interface RowInput {
-  readonly deviceName: string;
-  readonly driverName: string;
-  readonly memberName: string;
-  readonly browsePath: string;
-  readonly dataType: string;
-  readonly protocolData: Record<string, unknown> | undefined;
-  readonly unit?: string;
-  readonly euRange?: readonly [number, number];
-  readonly model: string;
-  readonly instance: string;
-  readonly access: string;
-}
-
-function buildRow(protocol: string, input: RowInput): string {
-  switch (protocol) {
-    case "mqtt":
-      return buildMqttRow(input);
-    case "opcua":
-      return buildOpcuaRow(input);
-    case "modbus":
-      return buildModbusRow(input);
-    default: {
-      const _exhaustive: never = protocol as never;
-      throw new Error(`Unsupported LE export protocol: "${_exhaustive}"`);
-    }
-  }
-}
-
-function buildMqttRow(input: RowInput): string {
-  const topic =
-    typeof input.protocolData?.["topic"] === "string"
-      ? input.protocolData["topic"]
-      : `${input.browsePath}/${input.memberName}`;
-
-  return [
-    "", // deviceId
-    esc(input.deviceName),
-    esc(input.driverName),
-    esc(topic), // name = MQTT topic
-    esc(input.memberName), // tagName
-    "", // description
-    "string", // valueType — MQTT is always string
-    "", // registerId
-    "false", // publishCoV
-    "", // tagFormula
-    buildMetaData(input), // metaData
-    "Disable", // Retain
-    "0", // Qos
-    "", // address
-    "", // count
-    "", // pollingInterval
-    "", // endianness
-  ].join(",");
-}
-
-function buildOpcuaRow(input: RowInput): string {
-  const nodeId =
-    typeof input.protocolData?.["nodeId"] === "string"
-      ? input.protocolData["nodeId"]
-      : `ns=1;s=${input.browsePath}/${input.memberName}`;
-  const valueType = OPCUA_VALUE_TYPE[input.dataType] ?? "string";
-
-  return [
-    "", // deviceId
-    esc(input.deviceName),
-    esc(input.driverName),
-    esc(nodeId), // name = OPC UA NodeId
-    esc(input.memberName), // tagName
-    "", // description
-    valueType,
-    "", // registerId
-    "false", // publishCoV
-    "", // tagFormula
-    buildMetaData(input), // metaData
-    "", // Retain
-    "", // Qos
-    "", // address
-    "", // count
-    "", // pollingInterval
-    "", // endianness
-  ].join(",");
-}
-
-function buildModbusRow(input: RowInput): string {
-  const registerType = String(input.protocolData?.["registerType"] ?? "");
-  const valueType = MODBUS_VALUE_TYPE[registerType] ?? "float32";
-  const address = input.protocolData?.["address"];
-
-  return [
-    "", // deviceId
-    esc(input.deviceName),
-    esc(input.driverName),
-    "H", // name = Holding register
-    esc(input.memberName), // tagName
-    "", // description
-    valueType,
-    "", // registerId
-    "false", // publishCoV
-    "", // tagFormula
-    buildMetaData(input), // metaData
-    "", // Retain
-    "", // Qos
-    typeof address === "number" ? String(address) : "0", // address
-    "1", // count — always 1 scalar value; LE derives register width from valueType
-    "1.0000000000", // pollingInterval
-    "AB CD", // endianness (big-endian — matches Miravo Modbus)
-  ].join(",");
-}
-
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-
-/** Escape a comma-delimited CSV field: quote if it contains delimiters, quotes, or newlines. */
-function esc(value: string): string {
-  if (value.includes(",") || value.includes('"') || value.includes("\n")) {
-    return `"${value.replace(/"/g, '""')}"`;
-  }
-  return value;
-}
-
-/** Build the LE metaData JSON cell from Miravo tag metadata. */
-function buildMetaData(input: RowInput): string {
-  const unsPath = input.browsePath ? `${input.browsePath}/${input.memberName}` : input.memberName;
-
-  const meta: Record<string, unknown> = {
-    uns_path: unsPath,
-    model: input.model,
-    instance: input.instance,
-    access: input.access,
-  };
-
-  if (input.unit != null) meta["unit"] = input.unit;
-  if (input.euRange != null) {
-    meta["eu_range_min"] = String(input.euRange[0]);
-    meta["eu_range_max"] = String(input.euRange[1]);
-  }
-
-  return esc(JSON.stringify(meta));
-}

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("Copy a built-in model to local registry for customization")
-    .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("Copy a template and its referenced models to local registry")
-    .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 });
-    }
-  });
-});