miravo 0.6.0 → 0.6.2

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

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

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

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