miravo 0.6.0 → 0.6.2

package/src/commands/apply.ts

@@ -1,216 +0,0 @@
-/**
- * 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

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

@@ -1,201 +0,0 @@
-/**
- * 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/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/export.test.ts

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