miravo 0.6.0 → 0.6.1

package/src/lib/le/le-cli-helpers.ts

@@ -1,77 +0,0 @@
-/**
- * Shared CLI helpers for LE apply/cleanup commands.
- */
-
-import { basename } from "node:path";
-import { TEMPLATE_FILE_EXTENSION } from "@miravo/shared";
-import type { ApplyPlan, ApplyScope } from "./le-plan.ts";
-import { renderPlanHuman, renderPlanJSON } from "./le-plan.ts";
-
-const VALID_SCOPE_VALUES = new Set<ApplyScope>(["devices", "models", "instances"]);
-
-export function parseScopeOption(
-  rawScope: string | undefined,
-  defaultScope: readonly ApplyScope[],
-): { readonly scope?: ApplyScope[]; readonly error?: string } {
-  if (!rawScope) {
-    return { scope: [...defaultScope] };
-  }
-
-  const requestedScope = rawScope
-    .split(",")
-    .map((v) => v.trim())
-    .filter((v) => v.length > 0);
-
-  if (requestedScope.length === 0) {
-    return { error: "--scope cannot be empty. Use a comma-separated list." };
-  }
-
-  const invalidScope = requestedScope.filter((v) => !VALID_SCOPE_VALUES.has(v as ApplyScope));
-  if (invalidScope.length > 0) {
-    return {
-      error: `invalid --scope value(s): ${invalidScope.join(", ")}. Valid values: ${[...defaultScope].join(", ")}.`,
-    };
-  }
-
-  const dedupedScope: ApplyScope[] = [];
-  for (const value of requestedScope as ApplyScope[]) {
-    if (!dedupedScope.includes(value)) {
-      dedupedScope.push(value);
-    }
-  }
-  return { scope: dedupedScope };
-}
-
-/** Extract the template ID (filename stem) from a resolved template path. */
-export function extractTemplateId(templatePath: string): string {
-  const fileName = basename(templatePath);
-  return fileName.endsWith(TEMPLATE_FILE_EXTENSION)
-    ? fileName.slice(0, -TEMPLATE_FILE_EXTENSION.length)
-    : fileName;
-}
-
-/** Write status message to stderr (JSON mode) or stdout via writeOutput. */
-export function writeStatusMessage(
-  json: boolean,
-  message: string,
-  writeOutput: (msg: string) => void,
-): void {
-  if (json) {
-    process.stderr.write(`${message}\n`);
-    return;
-  }
-  writeOutput(message);
-}
-
-/** Write a plan to stdout in JSON or human format. */
-export function writePlanOutput(
-  plan: ApplyPlan,
-  json: boolean,
-  writeOutput: (msg: string) => void,
-): void {
-  if (json) {
-    process.stdout.write(`${renderPlanJSON(plan)}\n`);
-  } else {
-    writeOutput(renderPlanHuman(plan));
-  }
-}

package/src/lib/le/le-client.ts

@@ -1,184 +0,0 @@
-/**
- * Litmus Edge GraphQL client.
- *
- * Handles HTTP Basic Auth (API key as username, empty password),
- * TLS skip-verify, and 30-second per-call timeout.
- */
-
-import { MiravoError } from "@miravo/shared";
-
-const LE_TIMEOUT_MS = 30_000;
-
-export interface LEClientConfig {
-  readonly hostname: string;
-  readonly apiToken: string;
-}
-
-interface GQLResponse<T = unknown> {
-  readonly data?: T;
-  readonly errors?: readonly { message: string }[];
-}
-
-function buildLEClientFix(endpoint: string, statusCode?: number): string {
-  if (statusCode === 401 || statusCode === 403) {
-    return (
-      "Check --le-api-token (or LITMUS_EDGE_API_TOKEN) and verify the token has permission " +
-      `for ${endpoint}.`
-    );
-  }
-  if (statusCode === 404) {
-    return `LE endpoint "${endpoint}" was not found. Check your Litmus Edge version and hostname.`;
-  }
-  return (
-    "Check --le-hostname / --le-api-token and ensure Litmus Edge is reachable over HTTPS " +
-    "from this machine."
-  );
-}
-
-class LEClientError extends MiravoError {
-  constructor(
-    message: string,
-    fix: string,
-    readonly endpoint: string,
-    readonly statusCode?: number,
-  ) {
-    super(message, fix);
-    this.name = "LEClientError";
-  }
-}
-
-export class LEClient {
-  private readonly baseUrl: string;
-  private readonly authHeader: string;
-
-  constructor(config: LEClientConfig) {
-    const host = config.hostname.includes("://") ? config.hostname : `https://${config.hostname}`;
-    this.baseUrl = host.replace(/\/$/, "");
-    this.authHeader = `Basic ${btoa(`${config.apiToken}:`)}`;
-  }
-
-  async gql<T = unknown>(
-    endpoint: string,
-    query: string,
-    variables?: Record<string, unknown>,
-  ): Promise<T> {
-    const url = `${this.baseUrl}${endpoint}`;
-    const controller = new AbortController();
-    const timeout = setTimeout(() => controller.abort(), LE_TIMEOUT_MS);
-
-    try {
-      const res = await fetch(url, {
-        method: "POST",
-        headers: {
-          "Content-Type": "application/json",
-          Authorization: this.authHeader,
-        },
-        body: JSON.stringify({ query, variables }),
-        signal: controller.signal,
-        tls: { rejectUnauthorized: false },
-      });
-
-      if (!res.ok) {
-        const body = await res.text().catch(() => "");
-        throw new LEClientError(
-          `LE ${endpoint} returned ${res.status}: ${body}`,
-          buildLEClientFix(endpoint, res.status),
-          endpoint,
-          res.status,
-        );
-      }
-
-      const json = (await res.json()) as GQLResponse<T>;
-      if (json.errors?.length) {
-        throw new LEClientError(
-          `LE GraphQL error from ${endpoint}: ${json.errors.map((e) => e.message).join("; ")}`,
-          buildLEClientFix(endpoint),
-          endpoint,
-        );
-      }
-      if (!json.data) {
-        throw new LEClientError(
-          `LE ${endpoint} returned empty data`,
-          buildLEClientFix(endpoint),
-          endpoint,
-        );
-      }
-      return json.data;
-    } catch (err) {
-      if (err instanceof LEClientError) throw err;
-      if (err instanceof DOMException && err.name === "AbortError") {
-        throw new LEClientError(
-          `LE ${endpoint} timed out after ${LE_TIMEOUT_MS}ms`,
-          `Check network connectivity to ${url} and verify Litmus Edge is healthy.`,
-          endpoint,
-        );
-      }
-      throw new LEClientError(
-        `LE ${endpoint} request failed: ${err instanceof Error ? err.message : String(err)}`,
-        buildLEClientFix(endpoint),
-        endpoint,
-      );
-    } finally {
-      clearTimeout(timeout);
-    }
-  }
-
-  /** Verifies credentials via Digital Twins GraphQL (`Healthz`). Prefer `checkSysinfoVersion` for lightweight connectivity checks. */
-  async checkAuth(): Promise<void> {
-    await this.gql<{ Healthz: boolean }>("/digital-twins/v2", "query { Healthz }");
-  }
-
-  /** Verifies reachability + auth via `GET /sysinfo/version` (lighter than `checkAuth`). */
-  async checkSysinfoVersion(): Promise<void> {
-    const path = "/sysinfo/version";
-    const url = `${this.baseUrl}${path}`;
-    const controller = new AbortController();
-    const timeout = setTimeout(() => controller.abort(), LE_TIMEOUT_MS);
-
-    try {
-      const res = await fetch(url, {
-        method: "GET",
-        headers: { Authorization: this.authHeader },
-        signal: controller.signal,
-        tls: { rejectUnauthorized: false },
-      });
-
-      if (!res.ok) {
-        const body = await res.text().catch(() => "");
-        throw new LEClientError(
-          `LE ${path} returned ${res.status}: ${body}`,
-          buildLEClientFix(path, res.status),
-          path,
-          res.status,
-        );
-      }
-
-      const data: unknown = await res.json().catch(() => {
-        throw new LEClientError(`LE ${path} returned non-JSON body`, buildLEClientFix(path), path);
-      });
-      if (data === null || typeof data !== "object") {
-        throw new LEClientError(
-          `LE ${path} returned unexpected JSON`,
-          buildLEClientFix(path),
-          path,
-        );
-      }
-    } catch (err) {
-      if (err instanceof LEClientError) throw err;
-      if (err instanceof DOMException && err.name === "AbortError") {
-        throw new LEClientError(
-          `LE ${path} timed out after ${LE_TIMEOUT_MS}ms`,
-          `Check network connectivity to ${url} and verify Litmus Edge is healthy.`,
-          path,
-        );
-      }
-      throw new LEClientError(
-        `LE ${path} request failed: ${err instanceof Error ? err.message : String(err)}`,
-        buildLEClientFix(path),
-        path,
-      );
-    } finally {
-      clearTimeout(timeout);
-    }
-  }
-}

package/src/lib/le/le-concurrency.test.ts

@@ -1,157 +0,0 @@
-import { describe, expect, test } from "bun:test";
-import { formatThrownError, pMap } from "./le-concurrency.ts";
-
-describe("pMap", () => {
-  test("returns empty array for empty input", async () => {
-    const results = await pMap([], async (x) => x, { concurrency: 5 });
-    expect(results).toEqual([]);
-  });
-
-  test("returns results in original order", async () => {
-    const items = [3, 1, 2];
-    const results = await pMap(
-      items,
-      async (x) => {
-        await Bun.sleep(x * 10);
-        return x * 10;
-      },
-      { concurrency: 3 },
-    );
-    expect(results).toEqual([30, 10, 20]);
-  });
-
-  test("respects concurrency limit", async () => {
-    let active = 0;
-    let peak = 0;
-    const items = Array.from({ length: 10 }, (_, i) => i);
-
-    await pMap(
-      items,
-      async () => {
-        active++;
-        peak = Math.max(peak, active);
-        await Bun.sleep(20);
-        active--;
-      },
-      { concurrency: 3 },
-    );
-
-    expect(peak).toBe(3);
-  });
-
-  test("concurrency=1 runs sequentially", async () => {
-    const order: number[] = [];
-    const items = [1, 2, 3];
-
-    await pMap(
-      items,
-      async (x) => {
-        order.push(x);
-        await Bun.sleep(5);
-      },
-      { concurrency: 1 },
-    );
-
-    expect(order).toEqual([1, 2, 3]);
-  });
-
-  test("stopOnError: true stops launching after first error", async () => {
-    let launched = 0;
-    const items = Array.from({ length: 10 }, (_, i) => i);
-
-    await expect(
-      pMap(
-        items,
-        async (x) => {
-          launched++;
-          await Bun.sleep(5);
-          if (x === 1) throw new Error("fail at 1");
-        },
-        { concurrency: 2, stopOnError: true },
-      ),
-    ).rejects.toThrow("fail at 1");
-
-    // With concurrency 2, at most ~4 launched (2 initial + a couple pulled before error propagates)
-    expect(launched).toBeLessThanOrEqual(6);
-  });
-
-  test("stopOnError: true rejects with the first error chronologically", async () => {
-    const items = [0, 1, 2];
-
-    await expect(
-      pMap(
-        items,
-        async (x) => {
-          await Bun.sleep(x * 10);
-          throw new Error(`fail-${x}`);
-        },
-        { concurrency: 3, stopOnError: true },
-      ),
-    ).rejects.toThrow("fail-0");
-  });
-
-  test("default (best-effort) continues all items and rejects with AggregateError", async () => {
-    const completed: number[] = [];
-    const items = [0, 1, 2, 3, 4];
-
-    await expect(
-      pMap(
-        items,
-        async (x) => {
-          await Bun.sleep(5);
-          if (x === 1 || x === 3) throw new Error(`fail-${x}`);
-          completed.push(x);
-        },
-        { concurrency: 2 },
-      ),
-    ).rejects.toThrow("2 item(s) failed");
-
-    // All non-failing items should have completed
-    expect(completed.sort()).toEqual([0, 2, 4]);
-  });
-
-  test("default (best-effort) AggregateError contains all individual errors", async () => {
-    const items = [0, 1, 2];
-
-    try {
-      await pMap(
-        items,
-        async (x) => {
-          await Bun.sleep(5);
-          if (x === 0 || x === 2) throw new Error(`fail-${x}`);
-        },
-        { concurrency: 3 },
-      );
-      expect.unreachable("should have thrown");
-    } catch (err) {
-      expect(err).toBeInstanceOf(AggregateError);
-      const agg = err as AggregateError;
-      expect(agg.errors).toHaveLength(2);
-      const messages = agg.errors.map((e: Error) => e.message).sort();
-      expect(messages).toEqual(["fail-0", "fail-2"]);
-    }
-  });
-
-  test("passes index to callback", async () => {
-    const indices: number[] = [];
-    await pMap(["a", "b", "c"], async (_, i) => indices.push(i), { concurrency: 2 });
-    expect(indices.sort()).toEqual([0, 1, 2]);
-  });
-});
-
-describe("formatThrownError", () => {
-  test("expands AggregateError to underlying messages", () => {
-    const agg = new AggregateError(
-      [new Error("LE GraphQL: PKI"), new Error("timeout")],
-      "2 item(s) failed",
-    );
-    const out = formatThrownError(agg);
-    expect(out).toContain("LE GraphQL: PKI");
-    expect(out).toContain("timeout");
-    expect(out).not.toBe("2 item(s) failed");
-  });
-
-  test("passes through normal Error", () => {
-    expect(formatThrownError(new Error("plain"))).toBe("plain");
-  });
-});

package/src/lib/le/le-concurrency.ts

@@ -1,78 +0,0 @@
-/**
- * Bounded-concurrency async map for LE API calls.
- *
- * By default (`stopOnError: false`), all items run to completion and
- * failures are collected into an `AggregateError`.
- *
- * With `stopOnError: true`, workers stop launching new tasks on first
- * rejection, await all in-flight, then reject with the earliest error.
- *
- * `formatThrownError` expands `AggregateError` (count-only `.message`) into underlying messages.
- */
-export function formatThrownError(err: unknown): string {
-  if (err instanceof AggregateError) {
-    const inner = err.errors.map((e) => (e instanceof Error ? e.message : String(e)));
-    const unique = [...new Set(inner.filter((m) => m.length > 0))];
-    if (unique.length === 0) return err.message;
-    if (unique.length === 1) return unique[0] ?? err.message;
-    return `${unique.slice(0, 8).join("\n")}${unique.length > 8 ? `\n… +${unique.length - 8} more` : ""}`;
-  }
-  if (err instanceof Error) return err.message;
-  return String(err);
-}
-
-export async function pMap<T, R>(
-  items: readonly T[],
-  fn: (item: T, index: number) => Promise<R>,
-  opts: {
-    readonly concurrency: number;
-    readonly stopOnError?: boolean;
-    readonly signal?: AbortSignal;
-  },
-): Promise<R[]> {
-  if (items.length === 0) return [];
-
-  const stopOnError = opts.stopOnError ?? false;
-  const concurrency = Math.max(1, Math.min(opts.concurrency, items.length));
-  const results = new Array<R>(items.length);
-  let nextIndex = 0;
-  let firstError: unknown;
-  let hasError = false;
-  const errors: { index: number; error: unknown }[] = [];
-
-  async function worker(): Promise<void> {
-    while (nextIndex < items.length) {
-      if (stopOnError && hasError) break;
-      if (opts.signal?.aborted) break;
-      const idx = nextIndex++;
-      // idx could exceed bounds if multiple workers read nextIndex in the same
-      // microtask (not possible in single-threaded JS, but defensive).
-      if (idx >= items.length) break;
-      try {
-        results[idx] = await fn(items[idx] as T, idx);
-      } catch (err) {
-        if (!hasError) {
-          hasError = true;
-          firstError = err;
-        }
-        if (stopOnError) break;
-        errors.push({ index: idx, error: err });
-      }
-    }
-  }
-
-  const workers: Promise<void>[] = [];
-  for (let i = 0; i < concurrency; i++) {
-    workers.push(worker());
-  }
-  await Promise.all(workers);
-
-  if (stopOnError && hasError) throw firstError;
-  if (errors.length > 0) {
-    throw new AggregateError(
-      errors.map((e) => e.error),
-      `${errors.length} item(s) failed`,
-    );
-  }
-  return results;
-}

package/src/lib/le/le-connection-test.ts

@@ -1,42 +0,0 @@
-import { MiravoError } from "@miravo/shared";
-import { LEClient } from "./le-client.ts";
-import { formatThrownError } from "./le-concurrency.ts";
-import type { LEEnvironment } from "./le-environments.ts";
-import { DEFAULT_PLATFORM_ID } from "./le-environments.ts";
-
-type TestLeConnectionResult =
-  | { readonly connected: true; readonly hostname: string; readonly sourceHostname: string }
-  | { readonly connected: false; readonly error: string };
-
-export async function testLeConnection(input: {
-  readonly hostname: string;
-  readonly apiToken: string;
-  readonly sourceHostname: string;
-}): Promise<TestLeConnectionResult> {
-  try {
-    const client = new LEClient({
-      hostname: input.hostname,
-      apiToken: input.apiToken,
-    });
-    await client.checkSysinfoVersion();
-    return {
-      connected: true,
-      hostname: input.hostname,
-      sourceHostname: input.sourceHostname,
-    };
-  } catch (error) {
-    return {
-      connected: false,
-      error: formatThrownError(error),
-    };
-  }
-}
-
-export function assertSupportedEnvironmentPlatform(env: LEEnvironment): void {
-  if (env.platformId !== DEFAULT_PLATFORM_ID) {
-    throw new MiravoError(
-      `Environment "${env.label}" uses unsupported platform "${env.platformId}".`,
-      `Use an environment with platform "${DEFAULT_PLATFORM_ID}" for connection tests.`,
-    );
-  }
-}

package/src/lib/le/le-devicehub-properties.test.ts

@@ -1,53 +0,0 @@
-import { describe, expect, test } from "bun:test";
-import { buildLeDeviceHubDeviceProperties } from "./le-devicehub-properties.ts";
-
-describe("buildLeDeviceHubDeviceProperties", () => {
-  test("modbus uses networkAddress, networkPort, and stationId", () => {
-    const props = buildLeDeviceHubDeviceProperties("modbus", "10.0.0.50", 502);
-    expect(props.map((p) => [p.Key, p.Value])).toEqual([
-      ["networkAddress", "10.0.0.50"],
-      ["networkPort", "502"],
-      ["stationId", "1"],
-    ]);
-  });
-
-  test("opcua uses LE PascalCase keys and numeric security enum values", () => {
-    expect(buildLeDeviceHubDeviceProperties("opcua", "miravo.host", 4840)).toEqual([
-      { Key: "ServerURL", Value: "opc.tcp://miravo.host:4840" },
-      { Key: "SecurityPolicy", Value: "0" },
-      { Key: "SecurityMode", Value: "0" },
-    ]);
-  });
-
-  test("mqtt uses LE PascalCase keys: BrokerAddress and Port", () => {
-    expect(buildLeDeviceHubDeviceProperties("mqtt", "miravo.host", 1883)).toEqual([
-      { Key: "BrokerAddress", Value: "miravo.host" },
-      { Key: "Port", Value: "1883" },
-    ]);
-  });
-
-  test("opcua ServerURL encodes non-default port", () => {
-    const props = buildLeDeviceHubDeviceProperties("opcua", "plc.local", 48400);
-    const urlProp = props.find((p) => p.Key === "ServerURL");
-    expect(urlProp?.Value).toBe("opc.tcp://plc.local:48400");
-  });
-
-  test("no key uses legacy names rejected or ignored by LE", () => {
-    const banned = new Set([
-      "serverUrl",
-      "securityPolicy",
-      "securityMode",
-      "brokerAddress",
-      "brokerPort",
-      "endpoint",
-      "host",
-      "url",
-    ]);
-    for (const protocol of ["opcua", "modbus", "mqtt"] as const) {
-      const props = buildLeDeviceHubDeviceProperties(protocol, "h", 1);
-      for (const { Key } of props) {
-        expect(banned.has(Key)).toBe(false);
-      }
-    }
-  });
-});

package/src/lib/le/le-devicehub-properties.ts

@@ -1,33 +0,0 @@
-/** Key/value pairs for Litmus Edge device `settings` (apply + offline template export). */
-
-import type { ProtocolName } from "@miravo/shared";
-
-export function buildLeDeviceHubDeviceProperties(
-  protocol: ProtocolName,
-  sourceHostname: string,
-  endpointPort: number,
-): readonly { Key: string; Value: string }[] {
-  switch (protocol) {
-    case "opcua":
-      return [
-        { Key: "ServerURL", Value: `opc.tcp://${sourceHostname}:${endpointPort}` },
-        { Key: "SecurityPolicy", Value: "0" },
-        { Key: "SecurityMode", Value: "0" },
-      ];
-    case "modbus":
-      return [
-        { Key: "networkAddress", Value: sourceHostname },
-        { Key: "networkPort", Value: String(endpointPort) },
-        { Key: "stationId", Value: "1" },
-      ];
-    case "mqtt":
-      return [
-        { Key: "BrokerAddress", Value: sourceHostname },
-        { Key: "Port", Value: String(endpointPort) },
-      ];
-    default: {
-      const _never: never = protocol;
-      throw new Error(`Unknown protocol: ${_never}`);
-    }
-  }
-}