miravo 0.5.0 → 0.6.0

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

@@ -0,0 +1,340 @@
+/**
+ * Persisted platform operations audit trail.
+ *
+ * Records completed apply/cleanup summaries in:
+ * ~/.miravo/platforms/operations.jsonl
+ */
+
+import { appendFile, chmod } from "node:fs/promises";
+import { z } from "zod";
+import type { ResourceProgress } from "./le-apply.ts";
+import { ensurePlatformsDir, operationsFilePath } from "./le-environments.ts";
+import type { ApplyScope } from "./le-plan.ts";
+
+const MAX_OPERATION_ENTRIES = 10_000;
+const OPERATIONS_FILE_MODE = 0o600;
+
+const PlatformOperationTypeSchema = z.enum(["apply", "cleanup"]);
+const PlatformOperationStatusSchema = z.enum(["success", "partial", "blocked", "noop", "failed"]);
+const PlatformResourceTypeSchema = z.enum(["device", "model", "instance", "param-sync"]);
+const PlatformResourceActionSchema = z.enum(["create", "update", "replace", "delete"]);
+
+const ActionCountsSchema = z.object({
+  create: z.number().int().nonnegative(),
+  update: z.number().int().nonnegative(),
+  replace: z.number().int().nonnegative().default(0),
+  delete: z.number().int().nonnegative(),
+  failed: z.number().int().nonnegative(),
+  total: z.number().int().nonnegative(),
+});
+
+const ResourceCountsSchema = z.object({
+  device: ActionCountsSchema,
+  model: ActionCountsSchema,
+  instance: ActionCountsSchema,
+  "param-sync": ActionCountsSchema,
+});
+
+const PlatformOperationRecordSchema = z.object({
+  schemaVersion: z.literal(1),
+  operationId: z.string().min(1),
+  operationType: PlatformOperationTypeSchema,
+  status: PlatformOperationStatusSchema,
+  templateId: z.string().min(1),
+  environmentId: z.string().min(1),
+  environmentLabel: z.string().min(1),
+  hostname: z.string().min(1),
+  scope: z.array(z.string()),
+  filters: z.object({
+    area: z.string().optional(),
+    line: z.string().optional(),
+    instance: z.string().optional(),
+  }),
+  successCount: z.number().int().nonnegative(),
+  failedCount: z.number().int().nonnegative(),
+  blockedCount: z.number().int().nonnegative(),
+  startedAt: z.number().int().nonnegative(),
+  completedAt: z.number().int().nonnegative(),
+  durationMs: z.number().int().nonnegative(),
+  resourceCounts: ResourceCountsSchema,
+  error: z.string().optional(),
+});
+
+export type PlatformOperationRecord = z.infer<typeof PlatformOperationRecordSchema>;
+
+type PlatformOperationType = z.infer<typeof PlatformOperationTypeSchema>;
+type PlatformResourceType = z.infer<typeof PlatformResourceTypeSchema>;
+type PlatformResourceAction = z.infer<typeof PlatformResourceActionSchema>;
+
+type MutableActionCounts = {
+  create: number;
+  update: number;
+  replace: number;
+  delete: number;
+  failed: number;
+  total: number;
+};
+
+type MutableResourceCounts = Record<PlatformResourceType, MutableActionCounts>;
+
+interface PlatformOperationsQuery {
+  readonly type?: PlatformOperationType | undefined;
+  readonly environmentId?: string | undefined;
+  readonly limit?: number | undefined;
+  readonly offset?: number | undefined;
+}
+
+interface PlatformOperationsPage {
+  readonly operations: readonly PlatformOperationRecord[];
+  readonly total: number;
+  readonly hasMore: boolean;
+}
+
+interface PlatformOperationTrackerInput {
+  readonly operationId: string;
+  readonly operationType: PlatformOperationType;
+  readonly templateId: string;
+  readonly environmentId: string;
+  readonly environmentLabel: string;
+  readonly hostname: string;
+  readonly scope: readonly ApplyScope[];
+  readonly filters: {
+    readonly area?: string | undefined;
+    readonly line?: string | undefined;
+    readonly instance?: string | undefined;
+  };
+  readonly startedAt: number;
+}
+
+interface PlatformOperationFinalizeInput {
+  readonly successCount: number;
+  readonly failedCount: number;
+  readonly blockedCount?: number | undefined;
+  readonly completedAt?: number | undefined;
+  readonly error?: string | undefined;
+}
+
+interface PlatformOperationTracker {
+  onResourceComplete(progress: ResourceProgress): void;
+  finalize(input: PlatformOperationFinalizeInput): PlatformOperationRecord;
+}
+
+let writeQueue: Promise<void> = Promise.resolve();
+
+function nextWrite(task: () => Promise<void>): Promise<void> {
+  writeQueue = writeQueue.then(task, task);
+  return writeQueue;
+}
+
+function createEmptyActionCounts(): MutableActionCounts {
+  return { create: 0, update: 0, replace: 0, delete: 0, failed: 0, total: 0 };
+}
+
+function createEmptyResourceCounts(): MutableResourceCounts {
+  return {
+    device: createEmptyActionCounts(),
+    model: createEmptyActionCounts(),
+    instance: createEmptyActionCounts(),
+    "param-sync": createEmptyActionCounts(),
+  };
+}
+
+function normalizeResourceType(raw: string): PlatformResourceType | null {
+  const normalized = raw.trim().toLowerCase();
+  if (
+    normalized === "device" ||
+    normalized === "model" ||
+    normalized === "instance" ||
+    normalized === "param-sync"
+  ) {
+    return normalized;
+  }
+  return null;
+}
+
+function normalizeResourceAction(raw: string): PlatformResourceAction | null {
+  const normalized = raw.trim().toLowerCase();
+  if (
+    normalized === "create" ||
+    normalized === "update" ||
+    normalized === "replace" ||
+    normalized === "delete"
+  ) {
+    return normalized;
+  }
+  return null;
+}
+
+function toReadonlyCounts(
+  source: MutableResourceCounts,
+): PlatformOperationRecord["resourceCounts"] {
+  return {
+    device: { ...source.device },
+    model: { ...source.model },
+    instance: { ...source.instance },
+    "param-sync": { ...source["param-sync"] },
+  };
+}
+
+function resolveStatus(input: {
+  readonly successCount: number;
+  readonly failedCount: number;
+  readonly blockedCount: number;
+  readonly error?: string | undefined;
+}): PlatformOperationRecord["status"] {
+  if (input.error && input.successCount === 0 && input.failedCount > 0) return "failed";
+  if (input.blockedCount > 0) return "blocked";
+  if (input.successCount === 0 && input.failedCount === 0) return "noop";
+  if (input.failedCount === 0) return "success";
+  return "partial";
+}
+
+export function createPlatformOperationTracker(
+  input: PlatformOperationTrackerInput,
+): PlatformOperationTracker {
+  const resourceCounts = createEmptyResourceCounts();
+
+  return {
+    onResourceComplete(progress: ResourceProgress) {
+      const resourceType = normalizeResourceType(progress.resourceType);
+      if (!resourceType) return;
+
+      const count = progress.count ?? 1;
+      const bucket = resourceCounts[resourceType];
+      bucket.total += count;
+
+      const action = normalizeResourceAction(progress.action);
+      if (action) bucket[action] += count;
+      if (progress.status === "failed") bucket.failed += count;
+    },
+
+    finalize(finalizeInput: PlatformOperationFinalizeInput): PlatformOperationRecord {
+      const completedAt = finalizeInput.completedAt ?? Date.now();
+      const blockedCount = finalizeInput.blockedCount ?? 0;
+      const status = resolveStatus({
+        successCount: finalizeInput.successCount,
+        failedCount: finalizeInput.failedCount,
+        blockedCount,
+        error: finalizeInput.error,
+      });
+
+      const record: PlatformOperationRecord = {
+        schemaVersion: 1,
+        operationId: input.operationId,
+        operationType: input.operationType,
+        status,
+        templateId: input.templateId,
+        environmentId: input.environmentId,
+        environmentLabel: input.environmentLabel,
+        hostname: input.hostname,
+        scope: [...input.scope],
+        filters: {
+          ...(input.filters.area ? { area: input.filters.area } : {}),
+          ...(input.filters.line ? { line: input.filters.line } : {}),
+          ...(input.filters.instance ? { instance: input.filters.instance } : {}),
+        },
+        successCount: finalizeInput.successCount,
+        failedCount: finalizeInput.failedCount,
+        blockedCount,
+        startedAt: input.startedAt,
+        completedAt,
+        durationMs: Math.max(0, completedAt - input.startedAt),
+        resourceCounts: toReadonlyCounts(resourceCounts),
+        ...(finalizeInput.error ? { error: finalizeInput.error } : {}),
+      };
+
+      return PlatformOperationRecordSchema.parse(record);
+    },
+  };
+}
+
+async function trimOperationsFile(maxEntries: number): Promise<void> {
+  const path = operationsFilePath();
+  const text = await Bun.file(path).text();
+  const lines = text
+    .split("\n")
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0);
+
+  if (lines.length <= maxEntries) return;
+
+  const trimmed = `${lines.slice(lines.length - maxEntries).join("\n")}\n`;
+  await Bun.write(path, trimmed, { mode: OPERATIONS_FILE_MODE });
+  try {
+    await chmod(path, OPERATIONS_FILE_MODE);
+  } catch {
+    // Best effort hardening; platform may reject chmod.
+  }
+}
+
+export async function appendPlatformOperation(record: PlatformOperationRecord): Promise<void> {
+  const parsed = PlatformOperationRecordSchema.parse(record);
+  const line = `${JSON.stringify(parsed)}\n`;
+
+  await nextWrite(async () => {
+    await ensurePlatformsDir();
+    const path = operationsFilePath();
+    await appendFile(path, line, { encoding: "utf8", mode: OPERATIONS_FILE_MODE });
+    try {
+      await chmod(path, OPERATIONS_FILE_MODE);
+    } catch {
+      // Best effort hardening; platform may reject chmod.
+    }
+    await trimOperationsFile(MAX_OPERATION_ENTRIES);
+  });
+}
+
+function parseOperationsFile(text: string): PlatformOperationRecord[] {
+  const lines = text
+    .split("\n")
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0);
+
+  const records: PlatformOperationRecord[] = [];
+  for (const line of lines) {
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(line) as unknown;
+    } catch {
+      continue;
+    }
+    const result = PlatformOperationRecordSchema.safeParse(parsed);
+    if (result.success) records.push(result.data);
+  }
+  return records;
+}
+
+function sortNewestFirst(a: PlatformOperationRecord, b: PlatformOperationRecord): number {
+  if (a.completedAt !== b.completedAt) return b.completedAt - a.completedAt;
+  if (a.startedAt !== b.startedAt) return b.startedAt - a.startedAt;
+  return b.operationId.localeCompare(a.operationId);
+}
+
+export async function listPlatformOperations(
+  query: PlatformOperationsQuery = {},
+): Promise<PlatformOperationsPage> {
+  const limit = Math.min(Math.max(query.limit ?? 50, 1), 500);
+  const offsetRaw = query.offset ?? 0;
+  const offset = Number.isFinite(offsetRaw)
+    ? Math.min(Math.max(Math.trunc(offsetRaw), 0), MAX_OPERATION_ENTRIES)
+    : 0;
+
+  let text = "";
+  try {
+    text = await Bun.file(operationsFilePath()).text();
+  } catch {
+    return { operations: [], total: 0, hasMore: false };
+  }
+
+  const allRecords = parseOperationsFile(text).sort(sortNewestFirst);
+  const filtered = allRecords.filter((record) => {
+    if (query.type && record.operationType !== query.type) return false;
+    if (query.environmentId && record.environmentId !== query.environmentId) return false;
+    return true;
+  });
+
+  const total = filtered.length;
+  const operations = filtered.slice(offset, offset + limit);
+  const hasMore = offset + operations.length < total;
+  return { operations, total, hasMore };
+}

package/src/lib/le/le-static-model-schema.ts

@@ -0,0 +1,78 @@
+import type { ModelSchema, TwinModel } from "@miravo/shared";
+
+export function toModelSchema(model: TwinModel): ModelSchema {
+  const parameters: Record<
+    string,
+    { type: string; default: number | string | boolean; unit?: string }
+  > = {};
+
+  if (model.parameters) {
+    for (const [name, def] of Object.entries(model.parameters)) {
+      parameters[name] = {
+        type: def.type,
+        default: def.default,
+        ...(def.unit ? { unit: def.unit } : {}),
+      };
+    }
+  }
+
+  const members: Record<string, ModelSchema["members"][string]> = {};
+  for (const [name, def] of Object.entries(model.members)) {
+    const rawDefault = def.default;
+
+    members[name] = {
+      kind: def.kind,
+      dataType: def.data_type,
+      access: def.access,
+      unit: def.unit ?? null,
+      euRange: "eu_range" in def ? (def.eu_range ?? null) : null,
+      default:
+        typeof rawDefault === "number" ||
+        typeof rawDefault === "string" ||
+        typeof rawDefault === "boolean"
+          ? rawDefault
+          : null,
+    };
+  }
+
+  const methods: Record<string, ModelSchema["methods"][string]> = {};
+  if (model.methods) {
+    for (const [name, def] of Object.entries(model.methods)) {
+      methods[name] = {
+        description: def.description ?? null,
+        inputArguments: def.input_arguments
+          ? Object.entries(def.input_arguments).map(([argName, arg]) => ({
+              name: argName,
+              dataType: arg.data_type,
+              description: arg.description ?? null,
+            }))
+          : [],
+        outputArguments: def.output_arguments
+          ? Object.entries(def.output_arguments).map(([argName, arg]) => ({
+              name: argName,
+              dataType: arg.data_type,
+              description: arg.description ?? null,
+            }))
+          : [],
+      };
+    }
+  }
+
+  return {
+    name: model.model.name,
+    description: model.model.description ?? null,
+    parameters,
+    members,
+    methods,
+    faults: model.faults?.map((fault) => fault.name) ?? [],
+    lifecycle: model.lifecycle
+      ? {
+          stages: model.lifecycle.stages.map((stage) => stage.name),
+          totalHours: model.lifecycle.stages.reduce(
+            (sum, stage) => sum + stage.duration_hours[1],
+            0,
+          ),
+        }
+      : null,
+  };
+}

package/src/lib/le/le-static-planner.test.ts

@@ -0,0 +1,255 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { resolve } from "node:path";
+import { ContentCatalog } from "@miravo/core";
+import { createTmpFileUtils } from "@miravo/core/test-tmp-utils";
+import { MiravoError } from "@miravo/shared";
+import { buildDesiredStateFromTemplate } from "./le-static-planner.ts";
+
+const { tmpDir, writeTmpFile, cleanupTmpDir } = createTmpFileUtils(
+  resolve(import.meta.dir, ".tmp-test-le-static-planner"),
+);
+
+afterEach(async () => {
+  await cleanupTmpDir();
+});
+
+function createCatalog(): ContentCatalog {
+  return new ContentCatalog({
+    cwd: tmpDir,
+    miravoHome: resolve(tmpDir, ".miravo-home"),
+    builtinModelsDir: resolve(tmpDir, ".builtin-models"),
+    builtinTemplatesDir: resolve(tmpDir, ".builtin-templates"),
+  });
+}
+
+const PUMP_MODEL = `schema_version: "2"
+model:
+  name: pump
+members:
+  rpm:
+    kind: variable
+    data_type: Float
+    access: read
+  running:
+    kind: variable
+    data_type: Boolean
+    access: read
+  label:
+    kind: property
+    data_type: String
+    access: read
+    default: "pump-a"
+`;
+
+const TANK_MODEL = `schema_version: "2"
+model:
+  name: tank
+members:
+  level:
+    kind: variable
+    data_type: Float
+    access: read
+  active:
+    kind: variable
+    data_type: Boolean
+    access: read
+  pulses:
+    kind: variable
+    data_type: UInt16
+    access: read
+  note:
+    kind: property
+    data_type: String
+    access: read
+    default: "tank-a"
+`;
+
+describe("buildDesiredStateFromTemplate", () => {
+  test("builds desired devices/tags/models/instances with per-instance protocol scope", async () => {
+    const templatePath = await writeTmpFile(
+      "scope-template.miravo.yaml",
+      `kind: MiravoTemplate
+version: "1"
+name: scope-template
+protocols:
+  mqtt: {}
+  opcua: {}
+  modbus:
+    port: 1502
+areas:
+  - name: area_a
+    protocol_scope: [mqtt]
+    lines:
+      - name: line_a
+        twins:
+          - model: pump
+            count: 2
+  - name: area_b
+    lines:
+      - name: line_b
+        protocol_scope: [modbus]
+        twins:
+          - model: tank
+            count: 1
+          - model: pump
+            count: 1
+            protocol_scope: [opcua]
+`,
+    );
+
+    await writeTmpFile("pump.twin.yaml", PUMP_MODEL);
+    await writeTmpFile("tank.twin.yaml", TANK_MODEL);
+
+    const result = await buildDesiredStateFromTemplate({
+      templatePath,
+      catalog: createCatalog(),
+      sourceHostname: "source.example.local",
+    });
+
+    expect(result.templateId).toBe("scope-template");
+    expect(result.desired.devices).toHaveLength(4);
+    expect(result.desired.instances).toHaveLength(4);
+    expect(result.desired.models.map((model) => model.name).sort()).toEqual(["PUMP", "TANK"]);
+
+    const protocolByInstance = new Map(
+      result.desired.devices.map((device) => [device.instanceId, device.protocol]),
+    );
+    expect(protocolByInstance.get("pump-001")).toBe("mqtt");
+    expect(protocolByInstance.get("pump-002")).toBe("mqtt");
+    expect(protocolByInstance.get("tank-001")).toBe("modbus");
+    expect(protocolByInstance.get("pump-003")).toBe("opcua");
+
+    const mqttDevice = result.desired.devices.find((device) => device.instanceId === "pump-001");
+    expect(mqttDevice?.endpoint).toEqual({ host: "source.example.local", port: 1883 });
+    expect(mqttDevice?.browsePath).toBe("area_a/line_a/pump-001");
+    expect(mqttDevice?.tags[0]?.name).toBe("area_a/line_a/pump-001/rpm");
+    expect(mqttDevice?.tags[0]?.unsPath).toBe("area_a/line_a/pump-001/rpm");
+    expect(mqttDevice?.tags[0]?.access).toBe("read");
+    expect(mqttDevice?.properties).toEqual([
+      { Key: "BrokerAddress", Value: "source.example.local" },
+      { Key: "Port", Value: "1883" },
+    ]);
+
+    const modbusDevice = result.desired.devices.find((device) => device.instanceId === "tank-001");
+    expect(modbusDevice?.endpoint).toEqual({ host: "source.example.local", port: 1502 });
+    expect(modbusDevice?.browsePath).toBe("area_b/line_b/tank-001");
+    expect(modbusDevice?.tags.map((tag) => tag.tagName)).toEqual(["level", "active", "pulses"]);
+    expect(modbusDevice?.tags[0]?.unsPath).toBe("area_b/line_b/tank-001/level");
+    expect(modbusDevice?.tags[0]?.access).toBe("read");
+    expect(
+      modbusDevice?.tags.map(
+        (tag) => tag.properties.find((property) => property.Key === "address")?.Value,
+      ),
+    ).toEqual(["0", "2", "3"]);
+    expect(modbusDevice?.properties).toEqual([
+      { Key: "networkAddress", Value: "source.example.local" },
+      { Key: "networkPort", Value: "1502" },
+      { Key: "stationId", Value: "1" },
+    ]);
+
+    const opcuaDevice = result.desired.devices.find((device) => device.instanceId === "pump-003");
+    expect(opcuaDevice?.endpoint).toEqual({ host: "source.example.local", port: 4840 });
+    expect(opcuaDevice?.browsePath).toBe("area_b/line_b/pump-003");
+    expect(opcuaDevice?.tags[0]?.name).toBe("ns=1;s=area_b/line_b/pump-003/rpm");
+    expect(opcuaDevice?.tags[0]?.unsPath).toBe("area_b/line_b/pump-003/rpm");
+    expect(opcuaDevice?.tags[0]?.access).toBe("read");
+    expect(opcuaDevice?.properties).toEqual([
+      { Key: "ServerURL", Value: "opc.tcp://source.example.local:4840" },
+      { Key: "SecurityPolicy", Value: "0" },
+      { Key: "SecurityMode", Value: "0" },
+    ]);
+
+    const mqttInstance = result.desired.instances.find((i) => i.instanceId === "pump-001");
+    expect(mqttInstance?.browsePath).toBe("area_a/line_a/pump-001");
+    const opcuaInstance = result.desired.instances.find((i) => i.instanceId === "pump-003");
+    expect(opcuaInstance?.browsePath).toBe("area_b/line_b/pump-003");
+
+    const tankModel = result.desired.models.find((model) => model.name === "TANK");
+    expect(Array.isArray(tankModel?.leDtJson)).toBe(true);
+  });
+
+  test("fails when an instance resolves to multiple protocols", async () => {
+    const templatePath = await writeTmpFile(
+      "ambiguous-scope.miravo.yaml",
+      `kind: MiravoTemplate
+version: "1"
+name: ambiguous-scope
+protocols:
+  mqtt: {}
+  opcua: {}
+areas:
+  - name: area_a
+    lines:
+      - name: line_a
+        twins:
+          - model: pump
+            count: 1
+`,
+    );
+
+    await writeTmpFile("pump.twin.yaml", PUMP_MODEL);
+
+    await expect(
+      buildDesiredStateFromTemplate({
+        templatePath,
+        catalog: createCatalog(),
+        sourceHostname: "source.example.local",
+      }),
+    ).rejects.toThrow("resolved to multiple protocols");
+  });
+
+  test("rejects empty sourceHostname before touching the filesystem", async () => {
+    // nonexistent path proves the guard fires before any FS access
+    const templatePath = `${tmpDir}/nonexistent.miravo.yaml`;
+
+    await expect(
+      buildDesiredStateFromTemplate({
+        templatePath,
+        catalog: createCatalog(),
+        sourceHostname: "  ",
+      }),
+    ).rejects.toThrow("sourceHostname must not be empty");
+
+    await expect(
+      buildDesiredStateFromTemplate({
+        templatePath,
+        catalog: createCatalog(),
+        sourceHostname: "",
+      }),
+    ).rejects.toThrow("sourceHostname must not be empty");
+  });
+
+  test("fails with actionable error when a referenced model is missing", async () => {
+    const templatePath = await writeTmpFile(
+      "missing-model.miravo.yaml",
+      `kind: MiravoTemplate
+version: "1"
+name: missing-model
+protocols:
+  mqtt: {}
+areas:
+  - name: area_a
+    lines:
+      - name: line_a
+        twins:
+          - model: missing-pump
+            count: 1
+`,
+    );
+
+    try {
+      await buildDesiredStateFromTemplate({
+        templatePath,
+        catalog: createCatalog(),
+        sourceHostname: "source.example.local",
+      });
+      throw new Error("expected planner to throw for missing model");
+    } catch (error) {
+      expect(error).toBeInstanceOf(MiravoError);
+      if (error instanceof MiravoError) {
+        expect(error.message).toContain('Model "missing-pump" not found');
+        expect(error.fix).toContain("missing-pump.twin.yaml");
+      }
+    }
+  });
+});