miravo 0.6.0 → 0.6.1

package/src/lib/admin-platform-routes.ts

@@ -1,1017 +0,0 @@
-/**
- * Admin server platform route handlers.
- *
- * Handles LE environment CRUD and plan/apply/cleanup operations.
- * Credentials are resolved server-side from ~/.miravo/platforms/environments.json.
- */
-
-import type { ContentCatalog, EventLog } from "@miravo/core";
-import { deriveInstancePrefix } from "@miravo/core";
-import type { ModelSchema, ProtocolName, TwinModel } from "@miravo/shared";
-import { MiravoError, ProtocolNameSchema, TwinModelSchema } from "@miravo/shared";
-import { parse as parseYAML } from "yaml";
-import { z } from "zod";
-import { buildLeDtJsonFromSchema } from "../commands/start/catalog-le-dt.ts";
-import {
-  cancelOperation,
-  handleApplyStream,
-  handleCleanupStream,
-} from "./admin-platform-stream.ts";
-import { checkContentType, jsonResponse, plainResponse } from "./admin-responses.ts";
-import type {
-  ApplyDesiredState,
-  DesiredDevice,
-  DesiredInstance,
-  DesiredModel,
-  DesiredTag,
-  ResourceProgress,
-} from "./le/le-apply.ts";
-import { buildApplyPlan, executePlan } from "./le/le-apply.ts";
-import { buildCleanupPlan, executeCleanup } from "./le/le-cleanup.ts";
-import { extractTemplateId } from "./le/le-cli-helpers.ts";
-import { LEClient } from "./le/le-client.ts";
-import { formatThrownError } from "./le/le-concurrency.ts";
-import { assertSupportedEnvironmentPlatform, testLeConnection } from "./le/le-connection-test.ts";
-import { LEDeviceHub } from "./le/le-devicehub.ts";
-import { buildLeDeviceHubDeviceProperties } from "./le/le-devicehub-properties.ts";
-import { LEDigitalTwins } from "./le/le-digital-twins.ts";
-import { resolveProtocolPort } from "./le/le-endpoint.ts";
-import type { LEEnvironment } from "./le/le-environments.ts";
-import {
-  addEnvironment,
-  DEFAULT_PLATFORM_ID,
-  getEnvironment,
-  loadEnvironments,
-  removeEnvironment,
-  updateEnvironment,
-} from "./le/le-environments.ts";
-import type { ApplyScope } from "./le/le-plan.ts";
-import {
-  appendPlatformOperation,
-  createPlatformOperationTracker,
-  listPlatformOperations,
-} from "./le/le-platform-operations.ts";
-import { toModelSchema } from "./le/le-static-model-schema.ts";
-import { buildDesiredStateFromTemplate } from "./le/le-static-planner.ts";
-import { OPCUA_VALUE_TYPE } from "./le/le-value-types.ts";
-import { createCatalog, resolveTemplateIdentifier } from "./template-locator.ts";
-
-// --- Zod schemas ---
-
-const ApplyScopeSchema = z.enum(["devices", "models", "instances"]);
-
-const PlatformApplyBodySchema = z.object({
-  environmentId: z.string().min(1),
-  template: z.string().min(1).optional(),
-  model: z.string().min(1).optional(),
-  protocol: ProtocolNameSchema.optional(),
-  scope: z.array(ApplyScopeSchema).optional(),
-  area: z.string().optional(),
-  line: z.string().optional(),
-  instance: z.string().optional(),
-  ifUnmanaged: z.enum(["fail", "skip"]).optional(),
-  /** Model apply only: Litmus Edge device / instance id (default: `{last-segment}-001`). */
-  deviceName: z.string().optional(),
-});
-
-const PlatformCleanupBodySchema = z.object({
-  environmentId: z.string().min(1),
-  template: z.string().optional(),
-  allManaged: z.boolean().optional(),
-  scope: z.array(ApplyScopeSchema).optional(),
-  area: z.string().optional(),
-  line: z.string().optional(),
-  instance: z.string().optional(),
-});
-
-const CreateEnvironmentSchema = z.object({
-  platformId: z.string().min(1).default(DEFAULT_PLATFORM_ID),
-  label: z.string().min(1),
-  hostname: z.string().min(1),
-  apiToken: z.string().min(1),
-  sourceHostname: z.string().min(1),
-});
-
-const UpdateEnvironmentSchema = z.object({
-  platformId: z.string().min(1).optional(),
-  label: z.string().min(1).optional(),
-  hostname: z.string().min(1).optional(),
-  apiToken: z.string().min(1).optional(),
-  sourceHostname: z.string().min(1).optional(),
-});
-
-const TestLeConnectionSchema = z
-  .object({
-    environmentId: z.string().min(1).optional(),
-    hostname: z.string().min(1),
-    apiToken: z.string().optional(),
-    sourceHostname: z.string().min(1),
-  })
-  .superRefine((data, ctx) => {
-    if (!data.environmentId && !data.apiToken) {
-      ctx.addIssue({
-        code: z.ZodIssueCode.custom,
-        message: "apiToken is required when environmentId is omitted.",
-        path: ["apiToken"],
-      });
-    }
-  });
-
-const DEFAULT_APPLY_SCOPE: ApplyScope[] = ["devices", "models", "instances"];
-const DEFAULT_CLEANUP_SCOPE: ApplyScope[] = ["instances", "models", "devices"];
-
-// --- Route handler ---
-
-export async function handlePlatformRoute(
-  pathname: string,
-  request: Request,
-  checkSession: (request: Request) => Response | null,
-  eventLog?: EventLog | undefined,
-): Promise<Response | null> {
-  if (!pathname.startsWith("/platforms/")) return null;
-
-  const sessionBlock = checkSession(request);
-  if (sessionBlock) return sessionBlock;
-
-  if (pathname === "/platforms/le/operations") {
-    if (request.method !== "GET") return plainResponse("Method Not Allowed", 405, "GET");
-    const url = new URL(request.url);
-    const type = url.searchParams.get("type");
-    const environmentId = url.searchParams.get("environmentId");
-    const limitRaw = url.searchParams.get("limit");
-    const offsetRaw = url.searchParams.get("offset");
-
-    if (type && type !== "apply" && type !== "cleanup") {
-      return jsonResponse(
-        { message: `Invalid operation type "${type}".`, error: "Valid types: apply, cleanup" },
-        400,
-      );
-    }
-    const operationType = type === "apply" || type === "cleanup" ? type : undefined;
-
-    let limit: number | undefined;
-    if (limitRaw !== null) {
-      const parsed = Number.parseInt(limitRaw, 10);
-      if (!Number.isFinite(parsed) || parsed <= 0) {
-        return jsonResponse(
-          { message: `Invalid limit "${limitRaw}".`, error: "limit must be a positive integer." },
-          400,
-        );
-      }
-      limit = parsed;
-    }
-
-    let offset: number | undefined;
-    if (offsetRaw !== null) {
-      const parsed = Number.parseInt(offsetRaw, 10);
-      if (!Number.isFinite(parsed) || parsed < 0) {
-        return jsonResponse(
-          {
-            message: `Invalid offset "${offsetRaw}".`,
-            error: "offset must be a non-negative integer.",
-          },
-          400,
-        );
-      }
-      offset = parsed;
-    }
-
-    const result = await listPlatformOperations({
-      ...(operationType ? { type: operationType } : {}),
-      ...(environmentId ? { environmentId } : {}),
-      ...(typeof limit === "number" ? { limit } : {}),
-      ...(typeof offset === "number" ? { offset } : {}),
-    });
-    return jsonResponse(result, 200);
-  }
-
-  // --- Environment CRUD ---
-
-  if (pathname === "/platforms/le/environments") {
-    if (request.method === "GET") {
-      const envs = await loadEnvironments();
-      const masked = envs.map((e) => ({ ...e, apiToken: "••••••••" }));
-      return jsonResponse({ environments: masked }, 200);
-    }
-    if (request.method === "POST") {
-      const ctBlock = checkContentType(request);
-      if (ctBlock) return ctBlock;
-      const body = await parseJsonBody(request);
-      if (body instanceof Response) return body;
-      const parsed = CreateEnvironmentSchema.safeParse(body);
-      if (!parsed.success) return validationError(parsed.error);
-      const created = await addEnvironment(parsed.data);
-      return jsonResponse(created, 201);
-    }
-    return plainResponse("Method Not Allowed", 405, "GET, POST");
-  }
-
-  if (pathname === "/platforms/le/environments/test") {
-    if (request.method !== "POST") return plainResponse("Method Not Allowed", 405, "POST");
-    const ctBlock = checkContentType(request);
-    if (ctBlock) return ctBlock;
-    const body = await parseJsonBody(request);
-    if (body instanceof Response) return body;
-    return handleTestLeConnection(body);
-  }
-
-  if (pathname.startsWith("/platforms/le/environments/")) {
-    const id = pathname.slice("/platforms/le/environments/".length);
-    if (!id) return jsonResponse({ message: "Missing environment ID." }, 400);
-
-    if (request.method === "GET") {
-      const env = await getEnvironment(id);
-      if (!env) return jsonResponse({ message: "Environment not found." }, 404);
-      return jsonResponse(env, 200);
-    }
-    if (request.method === "PUT") {
-      const ctBlock = checkContentType(request);
-      if (ctBlock) return ctBlock;
-      const body = await parseJsonBody(request);
-      if (body instanceof Response) return body;
-      const parsed = UpdateEnvironmentSchema.safeParse(body);
-      if (!parsed.success) return validationError(parsed.error);
-      const updated = await updateEnvironment(id, parsed.data);
-      if (!updated) return jsonResponse({ message: "Environment not found." }, 404);
-      return jsonResponse(updated, 200);
-    }
-    if (request.method === "DELETE") {
-      const removed = await removeEnvironment(id);
-      if (!removed) return jsonResponse({ message: "Environment not found." }, 404);
-      return jsonResponse({ message: "Deleted." }, 200);
-    }
-    return plainResponse("Method Not Allowed", 405, "GET, PUT, DELETE");
-  }
-
-  // --- Plan / Apply / Cleanup ---
-
-  if (
-    pathname === "/platforms/le/plan" ||
-    pathname === "/platforms/le/apply" ||
-    pathname === "/platforms/le/cleanup" ||
-    pathname === "/platforms/le/cleanup/plan"
-  ) {
-    if (request.method !== "POST") return plainResponse("Method Not Allowed", 405, "POST");
-    const ctBlock = checkContentType(request);
-    if (ctBlock) return ctBlock;
-    const body = await parseJsonBody(request);
-    if (body instanceof Response) return body;
-
-    switch (pathname) {
-      case "/platforms/le/plan":
-        return handlePlan(body);
-      case "/platforms/le/apply":
-        return handleApply(body, eventLog);
-      case "/platforms/le/cleanup/plan":
-        return handleCleanupPlan(body);
-      case "/platforms/le/cleanup":
-        return handleCleanup(body, eventLog);
-    }
-  }
-
-  // --- Cancel endpoint ---
-
-  if (
-    pathname.startsWith("/platforms/le/operations/") &&
-    pathname.endsWith("/cancel") &&
-    pathname.length > "/platforms/le/operations//cancel".length
-  ) {
-    if (request.method !== "POST") return plainResponse("Method Not Allowed", 405, "POST");
-    const operationId = pathname.slice("/platforms/le/operations/".length, -"/cancel".length);
-    const cancelled = cancelOperation(operationId);
-    if (!cancelled) {
-      return jsonResponse({ message: "Operation not found or already complete." }, 404);
-    }
-    return jsonResponse({ cancelled: true }, 200);
-  }
-
-  // --- SSE streaming endpoints ---
-
-  if (pathname === "/platforms/le/apply/stream" || pathname === "/platforms/le/cleanup/stream") {
-    if (request.method !== "POST") return plainResponse("Method Not Allowed", 405, "POST");
-    const ctBlock = checkContentType(request);
-    if (ctBlock) return ctBlock;
-    const body = await parseJsonBody(request);
-    if (body instanceof Response) return body;
-
-    if (pathname === "/platforms/le/apply/stream") {
-      return handleApplyStream(body, eventLog);
-    }
-    return handleCleanupStream(body, eventLog);
-  }
-
-  return null;
-}
-
-// --- Helpers ---
-
-async function parseJsonBody(request: Request): Promise<unknown | Response> {
-  try {
-    return await request.json();
-  } catch {
-    return jsonResponse(
-      { message: "Invalid JSON body.", error: "Request body must be valid JSON." },
-      400,
-    );
-  }
-}
-
-function validationError(error: z.ZodError): Response {
-  return jsonResponse(
-    { message: "Invalid request body.", error: error.issues.map((i) => i.message).join("; ") },
-    400,
-  );
-}
-
-async function handleTestLeConnection(body: unknown): Promise<Response> {
-  const parsed = TestLeConnectionSchema.safeParse(body);
-  if (!parsed.success) return validationError(parsed.error);
-
-  const { environmentId, hostname, apiToken, sourceHostname } = parsed.data;
-
-  try {
-    let resolvedToken: string;
-
-    if (environmentId) {
-      const env = await getEnvironment(environmentId);
-      if (!env) return jsonResponse({ message: "Environment not found." }, 404);
-      assertSupportedEnvironmentPlatform(env);
-      resolvedToken = apiToken || env.apiToken;
-    } else {
-      resolvedToken = apiToken ?? "";
-    }
-
-    return jsonResponse(
-      await testLeConnection({ hostname, apiToken: resolvedToken, sourceHostname }),
-      200,
-    );
-  } catch (err) {
-    const message = formatThrownError(err);
-    return jsonResponse({ connected: false as const, error: message }, 200);
-  }
-}
-
-interface ApplyContext {
-  readonly env: LEEnvironment;
-  readonly hub: LEDeviceHub;
-  readonly dt: LEDigitalTwins;
-  readonly templateId: string;
-  readonly desired: ApplyDesiredState;
-  readonly req: z.infer<typeof PlatformApplyBodySchema>;
-}
-
-async function resolveApplyContext(body: unknown): Promise<ApplyContext | Response> {
-  const parsed = PlatformApplyBodySchema.safeParse(body);
-  if (!parsed.success) return validationError(parsed.error);
-  const req = parsed.data;
-
-  // Validate: exactly one of template or model must be provided
-  if (!req.template && !req.model) {
-    return jsonResponse(
-      { message: "Invalid request body.", error: "Provide either 'template' or 'model'." },
-      400,
-    );
-  }
-  if (req.template && req.model) {
-    return jsonResponse(
-      { message: "Invalid request body.", error: "Provide 'template' or 'model', not both." },
-      400,
-    );
-  }
-
-  const env = await getEnvironment(req.environmentId);
-  if (!env) return jsonResponse({ message: "Environment not found." }, 404);
-  if (env.platformId !== DEFAULT_PLATFORM_ID) {
-    return jsonResponse(
-      {
-        message: `Environment "${env.label}" uses unsupported platform "${env.platformId}".`,
-        error: `Only "${DEFAULT_PLATFORM_ID}" is currently supported for apply.`,
-      },
-      400,
-    );
-  }
-
-  const client = new LEClient({ hostname: env.hostname, apiToken: env.apiToken });
-  const hub = new LEDeviceHub(client);
-  const dt = new LEDigitalTwins(client);
-  await client.checkAuth();
-
-  const catalog = createCatalog();
-
-  if (req.model) {
-    // Model-based apply: protocol is required
-    if (!req.protocol) {
-      return jsonResponse(
-        { message: "Invalid request body.", error: "Protocol is required when applying a model." },
-        400,
-      );
-    }
-
-    const desired = await buildDesiredStateFromModel({
-      modelName: req.model,
-      catalog,
-      sourceHostname: env.sourceHostname,
-      protocol: req.protocol,
-      deviceName: req.deviceName,
-    });
-
-    return { env, hub, dt, templateId: `model:${req.model}`, desired, req };
-  }
-
-  // Template-based apply (original path) — req.template is guaranteed defined here
-  // because we returned early above when both template and model are missing.
-  const template = req.template ?? "";
-  const templatePath = await resolveTemplateIdentifier(template, catalog);
-  const templateId = extractTemplateId(templatePath);
-
-  const staticPlan = await buildDesiredStateFromTemplate({
-    templatePath,
-    catalog,
-    sourceHostname: env.sourceHostname,
-    protocol: req.protocol as ProtocolName | undefined,
-    filters: { area: req.area, line: req.line, instance: req.instance },
-  });
-
-  return { env, hub, dt, templateId, desired: staticPlan.desired, req };
-}
-
-// --- Model-based desired state ---
-
-interface BuildModelDesiredInput {
-  readonly modelName: string;
-  readonly catalog: ContentCatalog;
-  readonly sourceHostname: string;
-  readonly protocol: ProtocolName;
-  readonly deviceName?: string | undefined;
-}
-
-/** Resolve LE device/instance id for model apply (default `{prefix}-001` from `deriveInstancePrefix`). */
-function resolveModelInstanceId(modelName: string, raw: string | undefined): string {
-  const defaultId = `${deriveInstancePrefix(modelName)}-001`;
-  if (raw === undefined) {
-    return defaultId;
-  }
-  const trimmed = raw.trim();
-  if (trimmed === "") {
-    return defaultId;
-  }
-  const s = trimmed.toLowerCase();
-  if (s.length > 120) {
-    throw new MiravoError(
-      `Device name is too long (${s.length} characters).`,
-      "Use at most 120 characters, e.g. motor-001 or my-line-a-motor.",
-    );
-  }
-  if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(s)) {
-    throw new MiravoError(
-      `Invalid device name "${trimmed}".`,
-      "Use lowercase letters, numbers, and hyphens only (e.g. motor-001 or pump-line-1).",
-    );
-  }
-  return s;
-}
-
-async function buildDesiredStateFromModel(
-  input: BuildModelDesiredInput,
-): Promise<ApplyDesiredState> {
-  if (!input.sourceHostname.trim()) {
-    throw new MiravoError(
-      "sourceHostname must not be empty.",
-      "Provide a valid hostname or IP address for the source server.",
-    );
-  }
-
-  const modelPath = await input.catalog.resolveModel(input.modelName);
-  const text = await Bun.file(modelPath).text();
-  let model: TwinModel;
-  try {
-    model = TwinModelSchema.parse(parseYAML(text));
-  } catch (error) {
-    throw new MiravoError(
-      `Failed to parse model "${input.modelName}".`,
-      error instanceof Error ? error.message : "Ensure the model YAML is valid.",
-    );
-  }
-
-  const instanceId = resolveModelInstanceId(input.modelName, input.deviceName);
-  const dtModelName = input.modelName.toUpperCase();
-  const endpointPort = resolveProtocolPort(input.protocol);
-
-  const tags = buildTagsForModel(instanceId, model, input.protocol);
-
-  const devices: DesiredDevice[] = [
-    {
-      instanceId,
-      modelName: input.modelName,
-      protocol: input.protocol,
-      deviceName: instanceId,
-      browsePath: instanceId,
-      endpoint: { host: input.sourceHostname, port: endpointPort },
-      properties: buildLeDeviceHubDeviceProperties(
-        input.protocol,
-        input.sourceHostname,
-        endpointPort,
-      ),
-      tags,
-    },
-  ];
-
-  const modelSchema: ModelSchema = toModelSchema(model);
-  const models: DesiredModel[] = [
-    {
-      name: dtModelName,
-      leDtJson: JSON.parse(buildLeDtJsonFromSchema(modelSchema)) as unknown,
-    },
-  ];
-
-  const instances: DesiredInstance[] = [
-    {
-      instanceId,
-      modelName: input.modelName,
-      dtInstanceName: instanceId,
-      dtModelName,
-      boundDeviceName: instanceId,
-      browsePath: instanceId,
-    },
-  ];
-
-  return { devices, models, instances };
-}
-
-function buildTagsForModel(
-  instanceId: string,
-  model: TwinModel,
-  protocol: ProtocolName,
-): readonly DesiredTag[] {
-  const memberEntries = Object.entries(model.members);
-
-  switch (protocol) {
-    case "opcua":
-      return memberEntries.map(([memberName, memberDef]) => ({
-        name: `ns=1;s=${instanceId}/${memberName}`,
-        tagName: memberName,
-        valueType: OPCUA_VALUE_TYPE[memberDef.data_type] ?? "string",
-        properties: [],
-        unsPath: `${instanceId}/${memberName}`,
-        access: memberDef.access,
-        unit: memberDef.unit,
-        euRange: "eu_range" in memberDef ? memberDef.eu_range : undefined,
-      }));
-    case "mqtt":
-      return memberEntries.map(([memberName, memberDef]) => ({
-        name: `${instanceId}/${memberName}`,
-        tagName: memberName,
-        valueType: "string",
-        properties: [],
-        unsPath: `${instanceId}/${memberName}`,
-        access: memberDef.access,
-        unit: memberDef.unit,
-        euRange: "eu_range" in memberDef ? memberDef.eu_range : undefined,
-      }));
-    case "modbus":
-      // Minimal Modbus support for model apply — single device, sequential addresses
-      return memberEntries.map(([memberName, memberDef]) => ({
-        name: "H",
-        tagName: memberName,
-        valueType: "float32",
-        properties: [
-          { Key: "address", Value: "0" },
-          { Key: "count", Value: "1" },
-          { Key: "polling_interval", Value: "1.0" },
-          { Key: "endianness", Value: "AB CD" },
-        ],
-        unsPath: `${instanceId}/${memberName}`,
-        access: memberDef.access,
-        unit: memberDef.unit,
-        euRange: "eu_range" in memberDef ? memberDef.eu_range : undefined,
-      }));
-    default: {
-      const _never: never = protocol;
-      throw new Error(`Unknown protocol: ${_never}`);
-    }
-  }
-}
-
-// --- Plan handler ---
-
-async function handlePlan(body: unknown): Promise<Response> {
-  try {
-    const ctx = await resolveApplyContext(body);
-    if (ctx instanceof Response) return ctx;
-
-    const scope = ctx.req.scope ?? DEFAULT_APPLY_SCOPE;
-    const { plan } = await buildApplyPlan(ctx.hub, ctx.dt, ctx.desired, {
-      templateId: ctx.templateId,
-      targetHost: ctx.env.hostname,
-      sourceHostname: ctx.env.sourceHostname,
-      scope,
-      filters: { area: ctx.req.area, line: ctx.req.line, instance: ctx.req.instance },
-      ifUnmanaged: ctx.req.ifUnmanaged ?? "fail",
-      dryRun: true,
-    });
-
-    return jsonResponse({ plan }, 200);
-  } catch (err) {
-    return jsonResponse(
-      { message: "Plan failed.", error: err instanceof Error ? err.message : String(err) },
-      500,
-    );
-  }
-}
-
-// --- Apply handler ---
-
-async function handleApply(body: unknown, eventLog?: EventLog | undefined): Promise<Response> {
-  let tracker: ReturnType<typeof createPlatformOperationTracker> | undefined;
-  try {
-    const ctx = await resolveApplyContext(body);
-    if (ctx instanceof Response) return ctx;
-
-    const operationId = crypto.randomUUID();
-    const startTime = performance.now();
-    const startedAt = Date.now();
-    const scope = ctx.req.scope ?? DEFAULT_APPLY_SCOPE;
-    const maxAttempts = 3;
-    let attempt = 0;
-    let finalActivityLogs: Parameters<NonNullable<EventLog>["pushExternal"]>[0][] = [];
-
-    while (attempt < maxAttempts) {
-      attempt++;
-      finalActivityLogs = [];
-
-      tracker = createPlatformOperationTracker({
-        operationId,
-        operationType: "apply",
-        templateId: ctx.templateId,
-        environmentId: ctx.req.environmentId,
-        environmentLabel: ctx.env.label,
-        hostname: ctx.env.hostname,
-        scope,
-        filters: { area: ctx.req.area, line: ctx.req.line, instance: ctx.req.instance },
-        startedAt,
-      });
-
-      const onApplyResource = (progress: ResourceProgress) => {
-        tracker?.onResourceComplete(progress);
-        finalActivityLogs.push({
-          type: "platform:resource",
-          operationId,
-          operationType: "apply",
-          templateId: ctx.templateId,
-          environmentLabel: ctx.env.label,
-          hostname: ctx.env.hostname,
-          phase: progress.phase,
-          resourceType: progress.resourceType,
-          resourceName: progress.name,
-          action: progress.action,
-          status: progress.status,
-          ...(progress.error ? { error: progress.error } : {}),
-        });
-      };
-
-      const applyOpts = {
-        templateId: ctx.templateId,
-        targetHost: ctx.env.hostname,
-        sourceHostname: ctx.env.sourceHostname,
-        scope,
-        filters: { area: ctx.req.area, line: ctx.req.line, instance: ctx.req.instance },
-        ifUnmanaged: ctx.req.ifUnmanaged ?? "fail",
-        dryRun: false,
-        onResourceComplete: onApplyResource,
-      };
-
-      try {
-        const { plan, snapshot } = await buildApplyPlan(ctx.hub, ctx.dt, ctx.desired, applyOpts);
-
-        const blockers = plan.entries.filter((e) => e.action === "blocked");
-        if (blockers.length > 0) {
-          const duration = Math.round(performance.now() - startTime);
-          const completedAt = Date.now();
-          for (const log of finalActivityLogs) {
-            eventLog?.pushExternal(log);
-          }
-          eventLog?.pushExternal({
-            type: "platform:operation",
-            operationId,
-            operationType: "apply",
-            templateId: ctx.templateId,
-            environmentLabel: ctx.env.label,
-            hostname: ctx.env.hostname,
-            applied: 0,
-            failed: blockers.length,
-            duration,
-          });
-          if (tracker) {
-            await appendPlatformOperation(
-              tracker.finalize({
-                successCount: 0,
-                failedCount: blockers.length,
-                blockedCount: blockers.length,
-                completedAt,
-              }),
-            ).catch(() => {});
-          }
-          return jsonResponse(
-            {
-              plan,
-              applied: 0,
-              failed: blockers.length,
-              error: `${blockers.length} blocker(s) found.`,
-            },
-            409,
-          );
-        }
-
-        const result = await executePlan(ctx.hub, ctx.dt, plan, ctx.desired, applyOpts, snapshot);
-
-        if (result.failed > 0 && attempt < maxAttempts) {
-          await Bun.sleep(3000);
-          continue;
-        }
-
-        const duration = Math.round(performance.now() - startTime);
-        const completedAt = Date.now();
-        for (const log of finalActivityLogs) {
-          eventLog?.pushExternal(log);
-        }
-        eventLog?.pushExternal({
-          type: "platform:operation",
-          operationId,
-          operationType: "apply",
-          templateId: ctx.templateId,
-          environmentLabel: ctx.env.label,
-          hostname: ctx.env.hostname,
-          applied: result.applied,
-          failed: result.failed,
-          duration,
-        });
-        if (tracker) {
-          await appendPlatformOperation(
-            tracker.finalize({
-              successCount: result.applied,
-              failedCount: result.failed,
-              completedAt,
-              ...(result.error ? { error: result.error } : {}),
-            }),
-          ).catch(() => {});
-        }
-        return jsonResponse(result, result.failed > 0 ? 207 : 200);
-      } catch (err) {
-        if (attempt < maxAttempts) {
-          await Bun.sleep(3000);
-          continue;
-        }
-        for (const log of finalActivityLogs) {
-          eventLog?.pushExternal(log);
-        }
-        throw err;
-      }
-    }
-    throw new Error("Unreachable");
-  } catch (err) {
-    const message = formatThrownError(err);
-    if (tracker) {
-      await appendPlatformOperation(
-        tracker.finalize({
-          successCount: 0,
-          failedCount: 1,
-          completedAt: Date.now(),
-          error: message,
-        }),
-      ).catch(() => {});
-    }
-    return jsonResponse({ message: "Apply failed.", error: message }, 500);
-  }
-}
-
-// --- Shared cleanup context ---
-
-interface CleanupContext {
-  readonly req: z.infer<typeof PlatformCleanupBodySchema>;
-  readonly env: LEEnvironment;
-  readonly hub: LEDeviceHub;
-  readonly dt: LEDigitalTwins;
-  readonly templateId: string;
-  readonly scope: ApplyScope[];
-  readonly allManaged: boolean;
-}
-
-async function resolveCleanupContext(body: unknown): Promise<CleanupContext | Response> {
-  const parsed = PlatformCleanupBodySchema.safeParse(body);
-  if (!parsed.success) return validationError(parsed.error);
-  const req = parsed.data;
-
-  const env = await getEnvironment(req.environmentId);
-  if (!env) return jsonResponse({ message: "Environment not found." }, 404);
-  if (env.platformId !== DEFAULT_PLATFORM_ID) {
-    return jsonResponse(
-      {
-        message: `Environment "${env.label}" uses unsupported platform "${env.platformId}".`,
-        error: `Only "${DEFAULT_PLATFORM_ID}" is currently supported for cleanup.`,
-      },
-      400,
-    );
-  }
-
-  const allManaged = req.allManaged ?? false;
-  if (!allManaged && !req.template) {
-    return jsonResponse(
-      { message: "Missing template.", error: "Provide 'template' or set 'allManaged: true'." },
-      400,
-    );
-  }
-
-  const client = new LEClient({ hostname: env.hostname, apiToken: env.apiToken });
-  const hub = new LEDeviceHub(client);
-  const dt = new LEDigitalTwins(client);
-  await client.checkAuth();
-
-  let templateId = "all-managed";
-  if (!allManaged && req.template) {
-    const catalog = createCatalog();
-    const templatePath = await resolveTemplateIdentifier(req.template, catalog);
-    templateId = extractTemplateId(templatePath);
-  }
-
-  return { req, env, hub, dt, templateId, scope: req.scope ?? DEFAULT_CLEANUP_SCOPE, allManaged };
-}
-
-// --- Cleanup plan handler (dry-run, no mutations) ---
-
-async function handleCleanupPlan(body: unknown): Promise<Response> {
-  try {
-    const ctx = await resolveCleanupContext(body);
-    if (ctx instanceof Response) return ctx;
-    const { hub, dt, env, templateId, scope, allManaged, req } = ctx;
-
-    const { plan } = await buildCleanupPlan(hub, dt, {
-      templateId,
-      targetHost: env.hostname,
-      scope,
-      filters: { area: req.area, line: req.line, instance: req.instance },
-      allManaged,
-      dryRun: true,
-    });
-    return jsonResponse({ plan }, 200);
-  } catch (err) {
-    return jsonResponse({ message: "Cleanup plan failed.", error: formatThrownError(err) }, 500);
-  }
-}
-
-// --- Cleanup handler ---
-
-async function handleCleanup(body: unknown, eventLog?: EventLog | undefined): Promise<Response> {
-  let tracker: ReturnType<typeof createPlatformOperationTracker> | undefined;
-
-  const ctxOrResponse = await resolveCleanupContext(body);
-  if (ctxOrResponse instanceof Response) return ctxOrResponse;
-  const { req, env, hub, dt, templateId, scope, allManaged } = ctxOrResponse;
-
-  try {
-    const operationId = crypto.randomUUID();
-    const startTime = performance.now();
-    const startedAt = Date.now();
-
-    const maxAttempts = 3;
-    let attempt = 0;
-    let finalActivityLogs: Parameters<NonNullable<EventLog>["pushExternal"]>[0][] = [];
-
-    while (attempt < maxAttempts) {
-      attempt++;
-      finalActivityLogs = [];
-
-      tracker = createPlatformOperationTracker({
-        operationId,
-        operationType: "cleanup",
-        templateId,
-        environmentId: req.environmentId,
-        environmentLabel: env.label,
-        hostname: env.hostname,
-        scope,
-        filters: { area: req.area, line: req.line, instance: req.instance },
-        startedAt,
-      });
-      const onCleanupResource = (progress: ResourceProgress) => {
-        tracker?.onResourceComplete(progress);
-        finalActivityLogs.push({
-          type: "platform:resource",
-          operationId,
-          operationType: "cleanup",
-          templateId,
-          environmentLabel: env.label,
-          hostname: env.hostname,
-          phase: progress.phase,
-          resourceType: progress.resourceType,
-          resourceName: progress.name,
-          action: progress.action,
-          status: progress.status,
-          ...(progress.error ? { error: progress.error } : {}),
-        });
-      };
-      const cleanupOpts = {
-        templateId,
-        targetHost: env.hostname,
-        scope,
-        filters: { area: req.area, line: req.line, instance: req.instance },
-        allManaged,
-        dryRun: false,
-        onResourceComplete: onCleanupResource,
-      };
-
-      try {
-        const planResult = await buildCleanupPlan(hub, dt, cleanupOpts);
-        if (planResult.plan.entries.length === 0) {
-          const duration = Math.round(performance.now() - startTime);
-          const completedAt = Date.now();
-          for (const log of finalActivityLogs) {
-            eventLog?.pushExternal(log);
-          }
-          eventLog?.pushExternal({
-            type: "platform:operation",
-            operationId,
-            operationType: "cleanup",
-            templateId,
-            environmentLabel: env.label,
-            hostname: env.hostname,
-            applied: 0,
-            failed: 0,
-            duration,
-          });
-          if (tracker) {
-            await appendPlatformOperation(
-              tracker.finalize({ successCount: 0, failedCount: 0, completedAt }),
-            ).catch(() => {});
-          }
-          return jsonResponse({ plan: planResult.plan, deleted: 0, failed: 0 }, 200);
-        }
-
-        const result = await executeCleanup(hub, dt, planResult, cleanupOpts);
-
-        if (result.failed > 0 && attempt < maxAttempts) {
-          await Bun.sleep(3000);
-          continue;
-        }
-
-        const duration = Math.round(performance.now() - startTime);
-        const completedAt = Date.now();
-        for (const log of finalActivityLogs) {
-          eventLog?.pushExternal(log);
-        }
-        eventLog?.pushExternal({
-          type: "platform:operation",
-          operationId,
-          operationType: "cleanup",
-          templateId,
-          environmentLabel: env.label,
-          hostname: env.hostname,
-          applied: result.deleted,
-          failed: result.failed,
-          duration,
-        });
-        if (tracker) {
-          await appendPlatformOperation(
-            tracker.finalize({
-              successCount: result.deleted,
-              failedCount: result.failed,
-              completedAt,
-              ...(result.error ? { error: result.error } : {}),
-            }),
-          ).catch(() => {});
-        }
-        return jsonResponse(result, result.failed > 0 ? 207 : 200);
-      } catch (err) {
-        if (attempt < maxAttempts) {
-          await Bun.sleep(3000);
-          continue;
-        }
-        for (const log of finalActivityLogs) {
-          eventLog?.pushExternal(log);
-        }
-        throw err;
-      }
-    }
-    throw new Error("Unreachable");
-  } catch (err) {
-    const message = formatThrownError(err);
-    if (tracker) {
-      await appendPlatformOperation(
-        tracker.finalize({
-          successCount: 0,
-          failedCount: 1,
-          completedAt: Date.now(),
-          error: message,
-        }),
-      ).catch(() => {});
-    }
-    return jsonResponse({ message: "Cleanup failed.", error: message }, 500);
-  }
-}
-
-// --- Exported helpers for streaming module ---
-
-export {
-  DEFAULT_APPLY_SCOPE,
-  DEFAULT_CLEANUP_SCOPE,
-  PlatformCleanupBodySchema,
-  resolveApplyContext,
-};