miravo 0.4.0 → 0.6.0

package/src/commands/apply.ts

@@ -0,0 +1,216 @@
+/**
+ * CLI command: miravo apply le
+ */
+
+import type { ProtocolName } from "@miravo/shared";
+import { ProtocolNameSchema } from "@miravo/shared";
+import type { Command } from "commander";
+import { buildApplyPlan, executePlan } from "../lib/le/le-apply.ts";
+import { resolveLeAuth, resolveSourceHostname } from "../lib/le/le-auth.ts";
+import {
+  extractTemplateId,
+  parseScopeOption,
+  writePlanOutput,
+  writeStatusMessage,
+} from "../lib/le/le-cli-helpers.ts";
+import { LEClient } from "../lib/le/le-client.ts";
+import { LEDeviceHub } from "../lib/le/le-devicehub.ts";
+import { LEDigitalTwins } from "../lib/le/le-digital-twins.ts";
+import type { ApplyScope } from "../lib/le/le-plan.ts";
+import { renderPlanHuman } from "../lib/le/le-plan.ts";
+import { buildDesiredStateFromTemplate } from "../lib/le/le-static-planner.ts";
+import { createCatalog, resolveTemplateIdentifier } from "../lib/template-locator.ts";
+import { handleCommandError, writeOutput } from "../logger.ts";
+
+const DEFAULT_SCOPE: ApplyScope[] = ["devices", "models", "instances"];
+
+function parseIfUnmanagedPolicy(raw: string | undefined): {
+  readonly policy?: "fail" | "skip" | undefined;
+  readonly error?: string | undefined;
+} {
+  const normalized = raw?.trim();
+  if (!normalized) return { policy: "fail" };
+  if (normalized === "fail" || normalized === "skip") return { policy: normalized };
+  return { error: `invalid --if-unmanaged value "${raw}". Valid values: fail, skip.` };
+}
+
+interface ApplyLeOptions {
+  readonly environment?: string;
+  readonly leHostname?: string;
+  readonly leApiToken?: string;
+  readonly template?: string;
+  readonly protocol?: string;
+  readonly scope?: string;
+  readonly area?: string;
+  readonly line?: string;
+  readonly instance?: string;
+  readonly sourceHostname?: string;
+  readonly ifUnmanaged?: string;
+  readonly dryRun?: boolean;
+  readonly json?: boolean;
+}
+
+export function registerApplyCommand(program: Command): void {
+  const applyCmd = program
+    .command("apply")
+    .description("Apply Miravo resources to external platforms");
+
+  applyCmd
+    .command("le")
+    .description("Apply a Miravo template to Litmus Edge (create/update managed resources)")
+    .option(
+      "--environment <label>",
+      "Named LE environment from ~/.miravo/platforms/environments.json",
+    )
+    .option("--le-hostname <host>", "Litmus Edge hostname or IP (env: LITMUS_EDGE_HOSTNAME)")
+    .option("--le-api-token <token>", "Litmus Edge API token (env: LITMUS_EDGE_API_TOKEN)")
+    .requiredOption("--template <path>", "Template name or file path")
+    .option("--protocol <name>", "Protocol: mqtt, opcua, or modbus (default: opcua)")
+    .option("--scope <scope>", `Scope: comma-separated (default: ${DEFAULT_SCOPE.join(",")})`)
+    .option("--area <name>", "Filter by area name")
+    .option("--line <name>", "Filter by line name")
+    .option("--instance <id>", "Filter by instance ID")
+    .option(
+      "--source-hostname <host>",
+      "Hostname LE uses to reach Miravo (env: MIRAVO_SOURCE_HOSTNAME)",
+    )
+    .option("--if-unmanaged <policy>", "Policy for unmanaged collisions: fail or skip", "fail")
+    .option("--dry-run", "Print plan without applying", false)
+    .option("--json", "Output plan as JSON", false)
+    .action(async (options: ApplyLeOptions) => {
+      try {
+        const jsonOutput = options.json ?? false;
+        const writeStatus = (msg: string): void => writeStatusMessage(jsonOutput, msg, writeOutput);
+
+        const leConfig = await resolveLeAuth({
+          environment: options.environment,
+          leHostname: options.leHostname,
+          leApiToken: options.leApiToken,
+        });
+
+        const scopeResult = parseScopeOption(options.scope, DEFAULT_SCOPE);
+        if (!scopeResult.scope) {
+          writeStatus(`Error: ${scopeResult.error}`);
+          process.exitCode = 1;
+          return;
+        }
+        const scope = scopeResult.scope;
+
+        const unmanagedResult = parseIfUnmanagedPolicy(options.ifUnmanaged);
+        if (!unmanagedResult.policy) {
+          writeStatus(`Error: ${unmanagedResult.error}`);
+          process.exitCode = 1;
+          return;
+        }
+
+        const protocolParse =
+          options.protocol !== undefined
+            ? ProtocolNameSchema.safeParse(options.protocol)
+            : undefined;
+        if (protocolParse && !protocolParse.success) {
+          writeStatus(
+            `Error: invalid --protocol value "${options.protocol}". Valid values: mqtt, opcua, modbus.`,
+          );
+          process.exitCode = 1;
+          return;
+        }
+        const protocol: ProtocolName | undefined = protocolParse?.data;
+
+        const client = new LEClient(leConfig);
+        const hub = new LEDeviceHub(client);
+        const dt = new LEDigitalTwins(client);
+
+        writeStatus("Checking LE connectivity...");
+        await client.checkAuth();
+
+        const sourceHostname = await resolveSourceHostname({
+          environment: options.environment,
+          sourceHostname: options.sourceHostname,
+        });
+
+        const catalog = createCatalog();
+        const templatePath = await resolveTemplateIdentifier(options.template as string, catalog);
+
+        let defaultProtocolNotified = false;
+        const staticPlan = await buildDesiredStateFromTemplate({
+          templatePath,
+          catalog,
+          sourceHostname,
+          protocol,
+          filters: { area: options.area, line: options.line, instance: options.instance },
+          onDefaultProtocol: (p) => {
+            if (!defaultProtocolNotified) {
+              writeStatus(
+                `No --protocol specified and template has no protocol config; defaulting to ${p}.`,
+              );
+              defaultProtocolNotified = true;
+            }
+          },
+        });
+
+        const desired = staticPlan.desired;
+
+        if (
+          desired.devices.length === 0 &&
+          desired.models.length === 0 &&
+          desired.instances.length === 0
+        ) {
+          writeStatus("Warning: empty desired state for the chosen protocol/filters.");
+        }
+
+        const applyOpts = {
+          templateId: extractTemplateId(templatePath),
+          targetHost: leConfig.hostname,
+          sourceHostname,
+          scope,
+          filters: { area: options.area, line: options.line, instance: options.instance },
+          ifUnmanaged: unmanagedResult.policy,
+          dryRun: options.dryRun ?? false,
+        };
+
+        const { plan, snapshot } = await buildApplyPlan(hub, dt, desired, applyOpts);
+
+        const blockers = plan.entries.filter((e) => e.action === "blocked");
+        if (blockers.length > 0 && !options.dryRun) {
+          writePlanOutput(plan, jsonOutput, writeOutput);
+          writeStatus(`${blockers.length} blocker(s) found. Fix and retry.`);
+          process.exitCode = 1;
+          return;
+        }
+
+        if (options.dryRun) {
+          writePlanOutput(plan, jsonOutput, writeOutput);
+          return;
+        }
+
+        if (jsonOutput) {
+          writePlanOutput(plan, true, writeOutput);
+        } else {
+          writeOutput(renderPlanHuman(plan));
+          writeOutput("");
+        }
+
+        const result = await executePlan(
+          hub,
+          dt,
+          plan,
+          desired,
+          {
+            ...applyOpts,
+            onProgress: (msg) => writeStatus(msg),
+          },
+          snapshot,
+        );
+
+        if (!jsonOutput) writeOutput("");
+        if (result.failed > 0) {
+          writeStatus(`Done with errors. ${result.applied} applied, ${result.failed} failed.`);
+          process.exitCode = 1;
+        } else {
+          writeStatus(`Done. ${result.applied} resources applied.`);
+        }
+      } catch (error) {
+        handleCommandError(error);
+      }
+    });
+}

package/src/commands/cleanup.test.ts

@@ -0,0 +1,34 @@
+import { afterEach, beforeEach, expect, test } from "bun:test";
+import { resetExitCode, runCliCommand } from "./cli-test-setup.ts";
+
+beforeEach(resetExitCode);
+afterEach(resetExitCode);
+
+test("cleanup le rejects invalid --scope values", async () => {
+  await runCliCommand([
+    "cleanup",
+    "le",
+    "--all-managed",
+    "--le-hostname",
+    "le.example.local",
+    "--le-api-token",
+    "token",
+    "--scope",
+    "foo,bar",
+  ]);
+
+  expect(process.exitCode).toBe(1);
+});
+
+test("cleanup le requires --template or --all-managed", async () => {
+  await runCliCommand([
+    "cleanup",
+    "le",
+    "--le-hostname",
+    "le.example.local",
+    "--le-api-token",
+    "token",
+  ]);
+
+  expect(process.exitCode).toBe(1);
+});

package/src/commands/cleanup.ts

@@ -0,0 +1,201 @@
+/**
+ * CLI command: miravo cleanup le
+ */
+
+import type { Command } from "commander";
+import { resolveLeAuth } from "../lib/le/le-auth.ts";
+import { buildCleanupPlan, executeCleanup } from "../lib/le/le-cleanup.ts";
+import {
+  extractTemplateId,
+  parseScopeOption,
+  writePlanOutput,
+  writeStatusMessage,
+} from "../lib/le/le-cli-helpers.ts";
+import { LEClient } from "../lib/le/le-client.ts";
+import { LEDeviceHub } from "../lib/le/le-devicehub.ts";
+import { LEDigitalTwins } from "../lib/le/le-digital-twins.ts";
+import type { ApplyScope } from "../lib/le/le-plan.ts";
+import { createCatalog, resolveTemplateIdentifier } from "../lib/template-locator.ts";
+import { handleCommandError, writeOutput } from "../logger.ts";
+
+const DEFAULT_CLEANUP_SCOPE: ApplyScope[] = ["instances", "models", "devices"];
+
+interface CleanupLeOptions {
+  readonly environment?: string;
+  readonly leHostname?: string;
+  readonly leApiToken?: string;
+  readonly template?: string;
+  readonly scope?: string;
+  readonly area?: string;
+  readonly line?: string;
+  readonly instance?: string;
+  readonly allManaged?: boolean;
+  readonly dryRun?: boolean;
+  readonly json?: boolean;
+  readonly yes?: boolean;
+}
+
+export function registerCleanupCommand(program: Command): void {
+  const cleanupCmd = program
+    .command("cleanup")
+    .description("Clean up Miravo-managed resources from external platforms");
+
+  cleanupCmd
+    .command("le")
+    .description("Remove Miravo-managed resources from Litmus Edge")
+    .option(
+      "--environment <label>",
+      "Named LE environment from ~/.miravo/platforms/environments.json",
+    )
+    .option("--le-hostname <host>", "Litmus Edge hostname or IP (env: LITMUS_EDGE_HOSTNAME)")
+    .option("--le-api-token <token>", "Litmus Edge API token (env: LITMUS_EDGE_API_TOKEN)")
+    .option("--template <path>", "Template name or file path (for scoped cleanup)")
+    .option(
+      "--scope <scope>",
+      `Scope: comma-separated (default: ${DEFAULT_CLEANUP_SCOPE.join(",")})`,
+    )
+    .option("--area <name>", "Filter by area name")
+    .option("--line <name>", "Filter by line name")
+    .option("--instance <id>", "Filter by instance ID")
+    .option(
+      "--all-managed",
+      "Remove ALL Miravo-managed resources (ignores template filtering)",
+      false,
+    )
+    .option("--dry-run", "Print plan without deleting", false)
+    .option("--json", "Output plan as JSON", false)
+    .option("--yes", "Skip confirmation prompts", false)
+    .action(async (options: CleanupLeOptions) => {
+      try {
+        const jsonOutput = options.json ?? false;
+        const writeStatus = (msg: string): void => writeStatusMessage(jsonOutput, msg, writeOutput);
+
+        const leConfig = await resolveLeAuth({
+          environment: options.environment,
+          leHostname: options.leHostname,
+          leApiToken: options.leApiToken,
+        });
+
+        const scopeResult = parseScopeOption(options.scope, DEFAULT_CLEANUP_SCOPE);
+        if (!scopeResult.scope) {
+          writeStatus(`Error: ${scopeResult.error}`);
+          process.exitCode = 1;
+          return;
+        }
+        const scope = scopeResult.scope;
+
+        let templateId = "all-managed";
+        if (!options.allManaged) {
+          if (!options.template) {
+            writeStatus("Error: provide --template or use --all-managed to clean all.");
+            process.exitCode = 1;
+            return;
+          }
+          const catalog = createCatalog();
+          const templatePath = await resolveTemplateIdentifier(options.template, catalog);
+          templateId = extractTemplateId(templatePath);
+        }
+
+        const client = new LEClient(leConfig);
+        const hub = new LEDeviceHub(client);
+        const dt = new LEDigitalTwins(client);
+
+        writeStatus("Checking LE connectivity...");
+        await client.checkAuth();
+
+        const cleanupOpts = {
+          templateId,
+          targetHost: leConfig.hostname,
+          scope,
+          filters: { area: options.area, line: options.line, instance: options.instance },
+          allManaged: options.allManaged ?? false,
+          dryRun: options.dryRun ?? false,
+        };
+
+        const maxAttempts = 3;
+        let attempt = 0;
+        let totalDeleted = 0;
+
+        while (attempt < maxAttempts) {
+          attempt++;
+          try {
+            const planResult = await buildCleanupPlan(hub, dt, cleanupOpts);
+
+            if (planResult.plan.entries.length === 0) {
+              if (attempt === 1) {
+                if (jsonOutput) {
+                  writePlanOutput(planResult.plan, true, writeOutput);
+                } else {
+                  writeOutput("No Miravo-managed resources found to clean up.");
+                }
+              } else {
+                if (!jsonOutput) writeOutput("");
+                writeStatus(`Done. ${totalDeleted} resources deleted.`);
+              }
+              return;
+            }
+
+            if (options.dryRun) {
+              writePlanOutput(planResult.plan, jsonOutput, writeOutput);
+              return;
+            }
+
+            if (attempt === 1) {
+              if (jsonOutput) {
+                writePlanOutput(planResult.plan, true, writeOutput);
+              } else {
+                writeOutput(
+                  `Found ${planResult.plan.entries.length} managed resources to delete:\n`,
+                );
+                for (const entry of planResult.plan.entries) {
+                  writeOutput(`  DELETE ${entry.resourceType} ${entry.name}`);
+                }
+                writeOutput("");
+              }
+
+              if (!options.yes) {
+                writeStatus("Use --yes to confirm deletion, or --dry-run to preview.");
+                process.exitCode = 1;
+                return;
+              }
+            }
+
+            const result = await executeCleanup(hub, dt, planResult, {
+              ...cleanupOpts,
+              onProgress: (msg) => writeStatus(msg),
+            });
+
+            totalDeleted += result.deleted;
+
+            if (result.failed > 0 && attempt < maxAttempts) {
+              writeStatus(
+                `Attempt ${attempt} finished with ${result.failed} errors, retrying in 3s...`,
+              );
+              await Bun.sleep(3000);
+              continue;
+            }
+
+            if (!jsonOutput) writeOutput("");
+            if (result.failed > 0) {
+              writeStatus(`Done with errors. ${totalDeleted} deleted, ${result.failed} failed.`);
+              process.exitCode = 1;
+            } else {
+              writeStatus(`Done. ${totalDeleted} resources deleted.`);
+            }
+            return;
+          } catch (err) {
+            if (attempt < maxAttempts && !options.dryRun && options.yes) {
+              writeStatus(
+                `Attempt ${attempt} failed: ${err instanceof Error ? err.message : String(err)}, retrying in 3s...`,
+              );
+              await Bun.sleep(3000);
+              continue;
+            }
+            throw err;
+          }
+        }
+      } catch (error) {
+        handleCommandError(error);
+      }
+    });
+}

package/src/commands/export.test.ts

@@ -0,0 +1,51 @@
+import { describe, expect, test } from "bun:test";
+import { findCliCommand, resetExitCode } from "./cli-test-setup.ts";
+
+describe("miravo export le-tags", () => {
+  test("export command is registered", async () => {
+    resetExitCode();
+    const { cmd } = await findCliCommand("export");
+    expect(cmd).toBeDefined();
+  });
+
+  test("le-tags subcommand is registered", async () => {
+    resetExitCode();
+    const { cmd } = await findCliCommand("export");
+    const leTags = cmd?.commands.find((c) => c.name() === "le-tags");
+    expect(leTags).toBeDefined();
+    expect(leTags?.description()).toContain("Litmus Edge");
+  });
+
+  test("le-tags has required --device option", async () => {
+    resetExitCode();
+    const { cmd } = await findCliCommand("export");
+    const leTags = cmd?.commands.find((c) => c.name() === "le-tags");
+    const deviceOpt = leTags?.options.find((o) => o.long === "--device");
+    expect(deviceOpt).toBeDefined();
+    expect(deviceOpt?.required).toBe(true);
+  });
+
+  test("le-tags has --instance option", async () => {
+    resetExitCode();
+    const { cmd } = await findCliCommand("export");
+    const leTags = cmd?.commands.find((c) => c.name() === "le-tags");
+    const instanceOpt = leTags?.options.find((o) => o.long === "--instance");
+    expect(instanceOpt).toBeDefined();
+  });
+
+  test("le-tags has --output option", async () => {
+    resetExitCode();
+    const { cmd } = await findCliCommand("export");
+    const leTags = cmd?.commands.find((c) => c.name() === "le-tags");
+    const outputOpt = leTags?.options.find((o) => o.long === "--output");
+    expect(outputOpt).toBeDefined();
+  });
+
+  test("le-tags has --protocol option", async () => {
+    resetExitCode();
+    const { cmd } = await findCliCommand("export");
+    const leTags = cmd?.commands.find((c) => c.name() === "le-tags");
+    const protocolOpt = leTags?.options.find((o) => o.long === "--protocol");
+    expect(protocolOpt).toBeDefined();
+  });
+});