miravo 0.4.0 → 0.6.0

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

@@ -0,0 +1,156 @@
+/**
+ * LE platform storage paths and environment credentials persistence.
+ *
+ * Layout:
+ * - ~/.miravo/platforms/environments.json (credentials, 0o600)
+ * - ~/.miravo/platforms/operations.jsonl (audit trail, 0o600)
+ */
+
+import { chmod, mkdir } from "node:fs/promises";
+import { resolveMiravoHome } from "@miravo/core";
+import { z } from "zod";
+
+export interface LEEnvironment {
+  readonly id: string;
+  readonly platformId: string;
+  readonly label: string;
+  readonly hostname: string;
+  readonly apiToken: string;
+  readonly sourceHostname: string;
+  readonly lastUsedAt?: number | undefined;
+}
+
+export const DEFAULT_PLATFORM_ID = "litmus-edge";
+
+const LEEnvironmentSchema = z.object({
+  id: z.string(),
+  platformId: z.string().min(1).default(DEFAULT_PLATFORM_ID),
+  label: z.string(),
+  hostname: z.string(),
+  apiToken: z.string(),
+  sourceHostname: z.string(),
+  lastUsedAt: z.number().optional(),
+});
+
+const PlatformsFileSchema = z.object({ environments: z.array(LEEnvironmentSchema) });
+
+const PLATFORMS_DIR_MODE = 0o700;
+const PLATFORMS_FILE_MODE = 0o600;
+
+export function platformsDirPath(): string {
+  return `${resolveMiravoHome()}/platforms`;
+}
+
+export function environmentsFilePath(): string {
+  return `${platformsDirPath()}/environments.json`;
+}
+
+export function operationsFilePath(): string {
+  return `${platformsDirPath()}/operations.jsonl`;
+}
+
+export async function ensurePlatformsDir(): Promise<void> {
+  const dir = platformsDirPath();
+  await mkdir(dir, { recursive: true, mode: PLATFORMS_DIR_MODE });
+  try {
+    await chmod(dir, PLATFORMS_DIR_MODE);
+  } catch {
+    // Best effort hardening; platform may reject chmod.
+  }
+}
+
+export async function loadEnvironments(): Promise<readonly LEEnvironment[]> {
+  try {
+    const raw: unknown = await Bun.file(environmentsFilePath()).json();
+    const result = PlatformsFileSchema.safeParse(raw);
+    if (!result.success) return [];
+    return [...result.data.environments].sort((a, b) => (b.lastUsedAt ?? 0) - (a.lastUsedAt ?? 0));
+  } catch {
+    return [];
+  }
+}
+
+async function writeEnvironments(envs: readonly LEEnvironment[]): Promise<void> {
+  const filePath = environmentsFilePath();
+  await ensurePlatformsDir();
+  await Bun.write(filePath, JSON.stringify({ environments: envs }, null, 2), {
+    mode: PLATFORMS_FILE_MODE,
+  });
+  try {
+    await chmod(filePath, PLATFORMS_FILE_MODE);
+  } catch {
+    // Best effort hardening; platform may reject chmod.
+  }
+}
+
+export async function getEnvironment(id: string): Promise<LEEnvironment | undefined> {
+  const envs = await loadEnvironments();
+  return envs.find((e) => e.id === id);
+}
+
+export async function addEnvironment(env: Omit<LEEnvironment, "id">): Promise<LEEnvironment> {
+  const envs = await loadEnvironments();
+  const created: LEEnvironment = {
+    id: crypto.randomUUID(),
+    ...env,
+    platformId: env.platformId || DEFAULT_PLATFORM_ID,
+  };
+  await writeEnvironments([...envs, created]);
+  return created;
+}
+
+export async function updateEnvironment(
+  id: string,
+  update: {
+    readonly platformId?: string | undefined;
+    readonly label?: string | undefined;
+    readonly hostname?: string | undefined;
+    readonly apiToken?: string | undefined;
+    readonly sourceHostname?: string | undefined;
+    readonly lastUsedAt?: number | undefined;
+  },
+): Promise<LEEnvironment | undefined> {
+  const envs = await loadEnvironments();
+  const existing = envs.find((e) => e.id === id);
+  if (!existing) return undefined;
+  const index = envs.indexOf(existing);
+  const updated: LEEnvironment = {
+    id: existing.id,
+    platformId: update.platformId ?? existing.platformId,
+    label: update.label ?? existing.label,
+    hostname: update.hostname ?? existing.hostname,
+    apiToken: update.apiToken ?? existing.apiToken,
+    sourceHostname: update.sourceHostname ?? existing.sourceHostname,
+    lastUsedAt: update.lastUsedAt ?? existing.lastUsedAt,
+  };
+  const next = [...envs];
+  next[index] = updated;
+  await writeEnvironments(next);
+  return updated;
+}
+
+/** Update only the lastUsedAt timestamp (fire-and-forget safe). */
+export async function touchEnvironment(id: string): Promise<void> {
+  await updateEnvironment(id, { lastUsedAt: Date.now() });
+}
+
+export async function removeEnvironment(id: string): Promise<boolean> {
+  const envs = await loadEnvironments();
+  const filtered = envs.filter((e) => e.id !== id);
+  if (filtered.length === envs.length) return false;
+  await writeEnvironments(filtered);
+  return true;
+}
+
+/** Find an environment by label (case-insensitive). */
+export async function getEnvironmentByLabel(label: string): Promise<LEEnvironment | undefined> {
+  const envs = await loadEnvironments();
+  const lower = label.toLowerCase();
+  return envs.find((e) => e.label.toLowerCase() === lower);
+}
+
+/** Find the first environment (used as CLI default when no flags/env provided). */
+export async function getDefaultEnvironment(): Promise<LEEnvironment | undefined> {
+  const envs = await loadEnvironments();
+  return envs[0];
+}

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

@@ -0,0 +1,87 @@
+/**
+ * Ownership markers for Miravo-managed LE resources.
+ *
+ * DeviceHub devices: metadata items (Key/Value pairs)
+ * DT models/instances: static attributes
+ */
+
+import type { ProtocolName } from "@miravo/shared";
+import type { LEItem, LEItemOutput } from "./le-devicehub.ts";
+
+// --- Device metadata markers ---
+
+export interface DeviceMarkerData {
+  readonly templateId: string;
+  readonly instanceId: string;
+  readonly modelName: string;
+  readonly protocol: ProtocolName;
+  readonly unsPath: string;
+}
+
+export function encodeDeviceMarkers(data: DeviceMarkerData): LEItem[] {
+  return [
+    { Key: "miravo_managed", Value: "true" },
+    { Key: "miravo_template", Value: data.templateId },
+    { Key: "miravo_instance", Value: data.instanceId },
+    { Key: "miravo_model", Value: data.modelName },
+    { Key: "miravo_protocol", Value: data.protocol },
+    { Key: "uns_path", Value: data.unsPath },
+  ];
+}
+
+export function isDeviceManaged(metadata: readonly LEItemOutput[]): boolean {
+  return metadata.some((m) => m.Name === "miravo_managed" && m.Value === "true");
+}
+
+export function parseDeviceMarkers(
+  metadata: readonly LEItemOutput[],
+): DeviceMarkerData | undefined {
+  const map = new Map(metadata.map((m) => [m.Name, m.Value]));
+  if (map.get("miravo_managed") !== "true") return undefined;
+  const templateId = map.get("miravo_template");
+  const instanceId = map.get("miravo_instance");
+  const modelName = map.get("miravo_model");
+  const protocol = map.get("miravo_protocol") as ProtocolName | undefined;
+  if (!templateId || !instanceId || !modelName || !protocol) return undefined;
+  const unsPath = map.get("uns_path") ?? "";
+  return { templateId, instanceId, modelName, protocol, unsPath };
+}
+
+// --- DT static attribute markers ---
+
+interface DTMarkerData {
+  readonly templateId: string;
+  readonly modelName: string;
+  readonly instanceId?: string | undefined;
+}
+
+export function encodeDTInstanceMarkers(data: {
+  templateId: string;
+  modelName: string;
+  instanceId: string;
+  unsPath: string;
+}): { Key: string; Value: string }[] {
+  return [
+    { Key: "miravo_managed", Value: "true" },
+    { Key: "miravo_template", Value: data.templateId },
+    { Key: "miravo_model", Value: data.modelName },
+    { Key: "miravo_instance", Value: data.instanceId },
+    { Key: "uns_path", Value: data.unsPath },
+  ];
+}
+
+export function isDTManaged(attrs: readonly { Key: string; Value: string }[]): boolean {
+  return attrs.some((a) => a.Key === "miravo_managed" && a.Value === "true");
+}
+
+export function parseDTMarkers(
+  attrs: readonly { Key: string; Value: string }[],
+): DTMarkerData | undefined {
+  const map = new Map(attrs.map((a) => [a.Key, a.Value]));
+  if (map.get("miravo_managed") !== "true") return undefined;
+  const templateId = map.get("miravo_template");
+  const modelName = map.get("miravo_model");
+  if (!templateId || !modelName) return undefined;
+  const instanceId = map.get("miravo_instance");
+  return { templateId, modelName, instanceId };
+}

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

@@ -0,0 +1,26 @@
+import { describe, expect, test } from "bun:test";
+import { type ApplyPlan, renderPlanHuman } from "./le-plan.ts";
+
+function createPlan(sourceMode: ApplyPlan["sourceMode"]): ApplyPlan {
+  return {
+    sourceMode,
+    targetHost: "le.example.local",
+    sourceHostname: undefined,
+    scope: ["devices"],
+    filters: {},
+    entries: [],
+  };
+}
+
+describe("renderPlanHuman source rendering", () => {
+  test("omits source line for managed cleanup plans", () => {
+    const output = renderPlanHuman(createPlan("managed"));
+    expect(output).not.toContain("Source:");
+    expect(output).toContain("Target LE: le.example.local");
+  });
+
+  test("renders source line for static apply plans", () => {
+    const output = renderPlanHuman(createPlan("static"));
+    expect(output).toContain("Source: static template");
+  });
+});

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

@@ -0,0 +1,109 @@
+/**
+ * LE Apply plan model.
+ *
+ * Each desired resource becomes one of: create, update, blocked.
+ * The plan is built before any mutation and can be rendered as
+ * dry-run output (human or JSON).
+ */
+
+import type { ProtocolName } from "@miravo/shared";
+
+// --- Scope ---
+
+export type ApplyScope = "devices" | "models" | "instances";
+
+// --- Plan actions ---
+
+export type PlanAction = "create" | "update" | "replace" | "delete" | "blocked";
+
+export interface PlanEntry {
+  readonly action: PlanAction;
+  readonly resourceType: "device" | "model" | "instance" | "param-sync";
+  readonly name: string;
+  /** Stable LE resource ID for deterministic execution (cleanup, duplicates). */
+  readonly resourceId?: string | undefined;
+  readonly protocol?: ProtocolName | undefined;
+  readonly endpoint?: string | undefined;
+  readonly detail?: string | undefined;
+  readonly blockReason?: string | undefined;
+}
+
+// --- Plan ---
+
+export interface ApplyPlan {
+  readonly sourceMode: "static" | "managed";
+  readonly targetHost: string;
+  readonly sourceHostname: string | undefined;
+  readonly scope: readonly ApplyScope[];
+  readonly filters: {
+    readonly area?: string | undefined;
+    readonly line?: string | undefined;
+    readonly instance?: string | undefined;
+  };
+  readonly entries: readonly PlanEntry[];
+}
+
+// --- Rendering ---
+
+export function renderPlanHuman(plan: ApplyPlan): string {
+  const lines: string[] = [];
+  switch (plan.sourceMode) {
+    case "static":
+      lines.push("Source: static template");
+      break;
+    case "managed":
+      // Cleanup --all-managed has no source input.
+      break;
+    default: {
+      const _never: never = plan.sourceMode;
+      throw new Error(`Unknown plan source mode: ${_never}`);
+    }
+  }
+  lines.push(`Target LE: ${plan.targetHost}`);
+  if (plan.sourceHostname) {
+    lines.push(`Source hostname: ${plan.sourceHostname}`);
+  }
+  lines.push(`Scope: ${plan.scope.join(",")}`);
+
+  const filterParts: string[] = [];
+  if (plan.filters.area) filterParts.push(`area=${plan.filters.area}`);
+  if (plan.filters.line) filterParts.push(`line=${plan.filters.line}`);
+  if (plan.filters.instance) filterParts.push(`instance=${plan.filters.instance}`);
+  if (filterParts.length > 0) {
+    lines.push(`Selection: ${filterParts.join(" ")}`);
+  }
+
+  lines.push("");
+  lines.push("Actions:");
+
+  const actions = plan.entries.filter((e) => e.action !== "blocked");
+  if (actions.length === 0) {
+    lines.push("  (none)");
+  } else {
+    for (const entry of actions) {
+      const proto = entry.protocol
+        ? ` [${entry.protocol}${entry.endpoint ? ` → ${entry.endpoint}` : ""}]`
+        : "";
+      lines.push(
+        `  ${entry.action.toUpperCase()} ${entry.resourceType} ${entry.name}${proto}${entry.detail ? ` ${entry.detail}` : ""}`,
+      );
+    }
+  }
+
+  const blockers = plan.entries.filter((e) => e.action === "blocked");
+  lines.push("");
+  lines.push("Blockers:");
+  if (blockers.length === 0) {
+    lines.push("  none");
+  } else {
+    for (const entry of blockers) {
+      lines.push(`  BLOCKED ${entry.resourceType} ${entry.name} — ${entry.blockReason}`);
+    }
+  }
+
+  return lines.join("\n");
+}
+
+export function renderPlanJSON(plan: ApplyPlan): string {
+  return JSON.stringify(plan, null, 2);
+}

package/src/lib/le/le-platform-operations.test.ts

@@ -0,0 +1,198 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { ResourceProgress } from "./le-apply.ts";
+import {
+  appendPlatformOperation,
+  createPlatformOperationTracker,
+  listPlatformOperations,
+  type PlatformOperationRecord,
+} from "./le-platform-operations.ts";
+
+let testHome = "";
+let prevMiravoHome: string | undefined;
+
+beforeEach(async () => {
+  prevMiravoHome = Bun.env["MIRAVO_HOME"];
+  testHome = await mkdtemp(join(tmpdir(), "miravo-platform-ops-test-"));
+  Bun.env["MIRAVO_HOME"] = testHome;
+});
+
+afterEach(async () => {
+  if (prevMiravoHome === undefined) {
+    delete Bun.env["MIRAVO_HOME"];
+  } else {
+    Bun.env["MIRAVO_HOME"] = prevMiravoHome;
+  }
+  await rm(testHome, { recursive: true, force: true });
+});
+
+function progress(overrides: Partial<ResourceProgress>): ResourceProgress {
+  return {
+    phase: "device",
+    resourceType: "device",
+    name: "pump-001",
+    action: "create",
+    status: "success",
+    index: 1,
+    of: 1,
+    ...overrides,
+  };
+}
+
+describe("le-platform-operations", () => {
+  test("tracker aggregates resource action counts and derives partial status", () => {
+    const tracker = createPlatformOperationTracker({
+      operationId: "op-1",
+      operationType: "apply",
+      templateId: "smart-factory",
+      environmentId: "env-1",
+      environmentLabel: "Prod LE",
+      hostname: "10.0.0.10",
+      scope: ["devices", "models", "instances"],
+      filters: {},
+      startedAt: 1_700_000_000_000,
+    });
+
+    tracker.onResourceComplete(progress({ resourceType: "device", action: "create" }));
+    tracker.onResourceComplete(
+      progress({
+        phase: "model",
+        resourceType: "model",
+        action: "create",
+        status: "failed",
+        error: "import failed",
+      }),
+    );
+
+    const record = tracker.finalize({
+      successCount: 1,
+      failedCount: 1,
+      completedAt: 1_700_000_001_000,
+    });
+
+    expect(record.status).toBe("partial");
+    expect(record.resourceCounts.device.create).toBe(1);
+    expect(record.resourceCounts.model.create).toBe(1);
+    expect(record.resourceCounts.model.failed).toBe(1);
+    expect(record.durationMs).toBe(1000);
+  });
+
+  test("append + list supports ordering, filtering, and offset pagination", async () => {
+    const base = {
+      schemaVersion: 1 as const,
+      environmentId: "env-1",
+      environmentLabel: "Prod LE",
+      hostname: "10.0.0.10",
+      scope: ["devices", "models", "instances"],
+      filters: {},
+      blockedCount: 0,
+      resourceCounts: {
+        device: { create: 1, update: 0, replace: 0, delete: 0, failed: 0, total: 1 },
+        model: { create: 1, update: 0, replace: 0, delete: 0, failed: 0, total: 1 },
+        instance: { create: 1, update: 0, replace: 0, delete: 0, failed: 0, total: 1 },
+        "param-sync": { create: 0, update: 0, replace: 0, delete: 0, failed: 0, total: 0 },
+      },
+    };
+
+    const op1: PlatformOperationRecord = {
+      ...base,
+      operationId: "op-1",
+      operationType: "apply",
+      status: "success",
+      templateId: "smart-factory",
+      successCount: 4,
+      failedCount: 0,
+      startedAt: 1000,
+      completedAt: 2000,
+      durationMs: 1000,
+    };
+    const op2: PlatformOperationRecord = {
+      ...base,
+      operationId: "op-2",
+      operationType: "cleanup",
+      status: "success",
+      templateId: "smart-factory",
+      successCount: 4,
+      failedCount: 0,
+      startedAt: 3000,
+      completedAt: 4000,
+      durationMs: 1000,
+    };
+
+    await appendPlatformOperation(op1);
+    await appendPlatformOperation(op2);
+
+    const page1 = await listPlatformOperations({ limit: 1, offset: 0 });
+    expect(page1.operations).toHaveLength(1);
+    expect(page1.operations[0]?.operationId).toBe("op-2");
+    expect(page1.total).toBe(2);
+    expect(page1.hasMore).toBe(true);
+
+    const page2 = await listPlatformOperations({ limit: 5, offset: 1 });
+    expect(page2.operations).toHaveLength(1);
+    expect(page2.operations[0]?.operationId).toBe("op-1");
+    expect(page2.total).toBe(2);
+    expect(page2.hasMore).toBe(false);
+
+    const applyOnly = await listPlatformOperations({ type: "apply" });
+    expect(applyOnly.operations).toHaveLength(1);
+    expect(applyOnly.total).toBe(1);
+    expect(applyOnly.operations[0]?.operationType).toBe("apply");
+  });
+
+  test("offset pagination does not drop rows when completedAt ties", async () => {
+    const base = {
+      schemaVersion: 1 as const,
+      environmentId: "env-1",
+      environmentLabel: "Prod LE",
+      hostname: "10.0.0.10",
+      scope: ["devices", "models", "instances"],
+      filters: {},
+      blockedCount: 0,
+      resourceCounts: {
+        device: { create: 1, update: 0, replace: 0, delete: 0, failed: 0, total: 1 },
+        model: { create: 1, update: 0, replace: 0, delete: 0, failed: 0, total: 1 },
+        instance: { create: 1, update: 0, replace: 0, delete: 0, failed: 0, total: 1 },
+        "param-sync": { create: 0, update: 0, replace: 0, delete: 0, failed: 0, total: 0 },
+      },
+    };
+
+    const opA: PlatformOperationRecord = {
+      ...base,
+      operationId: "op-a",
+      operationType: "apply",
+      status: "success",
+      templateId: "t1",
+      successCount: 1,
+      failedCount: 0,
+      startedAt: 1000,
+      completedAt: 5000,
+      durationMs: 4000,
+    };
+    const opB: PlatformOperationRecord = {
+      ...base,
+      operationId: "op-b",
+      operationType: "cleanup",
+      status: "success",
+      templateId: "t1",
+      successCount: 1,
+      failedCount: 0,
+      startedAt: 3000,
+      completedAt: 5000,
+      durationMs: 2000,
+    };
+
+    await appendPlatformOperation(opA);
+    await appendPlatformOperation(opB);
+
+    const p1 = await listPlatformOperations({ limit: 1, offset: 0 });
+    const p2 = await listPlatformOperations({ limit: 1, offset: 1 });
+    expect(p1.total).toBe(2);
+    expect(p2.total).toBe(2);
+    expect(new Set([p1.operations[0]?.operationId, p2.operations[0]?.operationId])).toEqual(
+      new Set(["op-a", "op-b"]),
+    );
+  });
+});