miravo 0.6.0 → 0.6.2

package/src/lib/admin-server.ts

@@ -1,797 +0,0 @@
-import { existsSync } from "node:fs";
-import { resolve } from "node:path";
-import type {
-  EngineCoreMetrics,
-  EngineStateSnapshot,
-  EventLogQuery,
-  EventLogResult,
-  InstanceDetail,
-  Manifest,
-  ModelSchema,
-  TemplateRun,
-} from "@miravo/core";
-import type {
-  CatalogModel,
-  CatalogTemplate,
-  CatalogTemplateDetail,
-  CommandResult,
-  ConsoleBootstrapResponse,
-  EngineCommand,
-  LoggedEvent,
-  RuntimeSnapshot,
-} from "@miravo/shared";
-import { handleAuthStatus, handleLogin, handleLogout, handlePasswordChange } from "./admin-auth.ts";
-import { handlePlatformRoute } from "./admin-platform-routes.ts";
-import type { HealthResponseBody } from "./admin-responses.ts";
-import {
-  buildHealthBody,
-  checkContentType,
-  jsonResponse,
-  livenessStatus,
-  parseCommandRequest,
-  plainResponse,
-  readinessStatus,
-  yamlResponse,
-} from "./admin-responses.ts";
-import type { SessionStore } from "./session-store.ts";
-import { extractSessionId } from "./session-store.ts";
-import type { WSClientData } from "./ws-hub.ts";
-import { ALL_CHANNELS, WSHub } from "./ws-hub.ts";
-
-/** Valid event types for the /events endpoint, derived from LoggedEvent discriminant. */
-const VALID_EVENT_TYPES: ReadonlySet<string> = new Set<LoggedEvent["type"]>([
-  "fault:triggered",
-  "fault:cleared",
-  "lifecycle:changed",
-  "instance:created",
-  "instance:removed",
-  "engine:state-changed",
-  "platform:resource",
-  "platform:operation",
-]);
-
-interface AdminEngine {
-  getMetrics(): {
-    readonly core: EngineCoreMetrics;
-    readonly adapters: ReadonlyArray<{
-      readonly name: string;
-      readonly metrics: { readonly connected: boolean };
-    }>;
-  };
-  getAvailableAdapters(): ReadonlyArray<{
-    readonly name: string;
-    readonly enabled: boolean;
-  }>;
-  getState(): EngineStateSnapshot;
-  execute(command: EngineCommand): Promise<CommandResult>;
-  getInstanceDetail(id: string): InstanceDetail | undefined;
-  getModelSchema(name: string): ModelSchema | undefined;
-  getEventLog(query?: EventLogQuery): EventLogResult;
-  getRunningTemplates(): readonly TemplateRun[];
-  getManifest(): Manifest;
-}
-
-/** Network binding configuration. */
-interface AdminServerNetworkOptions {
-  readonly host: string;
-  readonly port: number;
-  readonly tickIntervalMs: number;
-}
-
-/** Protocol adapter status configuration. */
-interface AdminServerProtocolOptions {
-  readonly getLastTickProgressAt: () => number;
-}
-
-/** WebSocket streaming configuration. When provided, enables the /ws endpoint. */
-interface AdminServerWSOptions {
-  readonly bus: import("@miravo/core").EventBus;
-}
-
-/** Authentication configuration for the admin server. */
-interface AdminServerAuth {
-  /** Verify a plaintext password against the stored hash. */
-  readonly verifyPassword: (password: string) => Promise<boolean>;
-  /** True when the effective password is the literal default "admin". */
-  readonly isDefaultPassword: boolean;
-  /** Server-side session store. */
-  readonly sessionStore: SessionStore;
-  /** Change the admin password (verifies old, hashes + persists new). */
-  readonly changePassword: (oldPassword: string, newPassword: string) => Promise<void>;
-  /** When true, all requests are treated as authenticated. No session required. */
-  readonly anonymousMode?: boolean;
-}
-
-interface AdminServerOptions {
-  readonly engine: AdminEngine;
-  readonly network: AdminServerNetworkOptions;
-  readonly protocols: AdminServerProtocolOptions;
-  /** WebSocket streaming. When provided, enables /ws endpoint. */
-  readonly ws?: AdminServerWSOptions | undefined;
-  /** Authentication configuration. */
-  readonly auth: AdminServerAuth;
-  /** Event log for platform operation tracking. */
-  readonly eventLog?: import("@miravo/core").EventLog | undefined;
-  /** Path to console static assets directory. When set, serves the SPA at non-API routes. */
-  readonly consoleDir?: string | undefined;
-  /** Template catalog provider for GET /catalog/templates. */
-  readonly getCatalog?: (() => readonly CatalogTemplate[]) | undefined;
-  /** Model catalog provider for GET /catalog/models. */
-  readonly getCatalogModels?: (() => Promise<readonly CatalogModel[]>) | undefined;
-  /** Model schema from YAML for GET /catalog/models/:name. */
-  readonly getCatalogModelSchema?: ((name: string) => Promise<ModelSchema | null>) | undefined;
-  /** Raw YAML text for GET /catalog/models/:name/yaml. */
-  readonly getModelYaml?: ((name: string) => Promise<string | null>) | undefined;
-  /** LE Digital Twin JSON for GET /catalog/models/:name/le-dt.json. */
-  readonly getLeDtJson?: ((name: string) => Promise<string | null>) | undefined;
-  /** Template detail with topology for GET /catalog/templates/:id. */
-  readonly getTemplateDetail?: ((id: string) => Promise<CatalogTemplateDetail | null>) | undefined;
-  /** Full LE export (JSON + CSV) for GET /catalog/templates/:id/le-template.json and /le-tags.csv. */
-  readonly getLeExport?:
-    | ((
-        id: string,
-        opts: { host: string; protocol: import("@miravo/shared").ProtocolName | undefined },
-      ) => Promise<{ templateJson: string; tagsCSV: string } | null>)
-    | undefined;
-  /** Raw YAML text for GET /catalog/templates/:id/yaml. */
-  readonly getTemplateYaml?: ((id: string) => Promise<string | null>) | undefined;
-  /** Simulation name for daemon identity verification via /readyz. */
-  readonly simulationName?: string | undefined;
-  /** Run ID for daemon identity verification via /readyz. */
-  readonly runId?: string | undefined;
-  /** Callback to request graceful shutdown. Used by POST /shutdown. */
-  readonly requestShutdown?: ((reason: string) => void) | undefined;
-}
-
-interface AdminServerHandle {
-  readonly endpoint: string;
-  readonly wsHub: WSHub | null;
-  stop(): void;
-}
-
-/**
- * Start the Miravo admin HTTP server.
- *
- * - `/healthz`: liveness (process/tick loop health)
- * - `/readyz`: readiness (engine running + adapters connected when enabled)
- * - `/metrics`: engine metrics snapshot
- * - `/state`: engine state snapshot
- * - `/commands`: command execution endpoint using EngineCommandSchema
- */
-function startAdminServer(options: AdminServerOptions): AdminServerHandle {
-  const { engine } = options;
-  const { host, port } = options.network;
-  const { getLastTickProgressAt } = options.protocols;
-
-  const { auth } = options;
-
-  function getSession(request: Request) {
-    const sessionId = extractSessionId(request);
-    return sessionId ? auth.sessionStore.validate(sessionId) : null;
-  }
-
-  /** Validate session cookie. Returns error Response or null if OK. */
-  function checkSession(request: Request): Response | null {
-    if (options.auth.anonymousMode) return null;
-    const session = getSession(request);
-    if (!session) {
-      const sessionId = extractSessionId(request);
-      if (!sessionId) {
-        return jsonResponse(
-          { message: "Unauthorized.", error: "Valid session required. Log in at /auth/login." },
-          401,
-        );
-      }
-      return jsonResponse(
-        { message: "Session expired.", error: "Log in again at /auth/login." },
-        401,
-      );
-    }
-    return null;
-  }
-
-  // Create WebSocket hub if ws config is provided
-  const wsHub = options.ws
-    ? new WSHub({
-        bus: options.ws.bus,
-        snapshotSource: {
-          getState: () => engine.getState(),
-          getMetrics: () => engine.getMetrics(),
-          getRunningTemplates: () => engine.getRunningTemplates(),
-        },
-      })
-    : null;
-
-  // Pre-resolve console dir and index.html once at startup (avoids per-request exists() check).
-  // Verify the file exists so we don't silently serve a missing build as a 200.
-  const consoleDir = options.consoleDir ? resolve(options.consoleDir) : null;
-  const consoleIndexPath = consoleDir ? `${consoleDir}/index.html` : null;
-  const consoleIndexFile =
-    consoleIndexPath && existsSync(consoleIndexPath) ? Bun.file(consoleIndexPath) : null;
-
-  const server = Bun.serve({
-    hostname: host,
-    port,
-    async fetch(request, server) {
-      const url = new URL(request.url);
-      const pathname = url.pathname;
-
-      // WebSocket upgrade for /ws
-      if (pathname === "/ws") {
-        if (!wsHub) {
-          return plainResponse("WebSocket not available", 503);
-        }
-        const sessionBlock = checkSession(request);
-        if (sessionBlock) return sessionBlock;
-        const upgraded = server.upgrade(request, {
-          // WSClientData — Bun's untyped websocket generic requires the cast
-          data: { channels: new Set(ALL_CHANNELS) } as unknown as undefined,
-        });
-        if (!upgraded) {
-          return plainResponse("WebSocket upgrade failed", 400);
-        }
-        // Bun requires a Response return, but upgrade() consumes the request
-        return undefined as unknown as Response;
-      }
-
-      // Health/metrics routes — compute expensive metrics only when needed
-      if (pathname === "/healthz" || pathname === "/readyz" || pathname === "/metrics") {
-        if (pathname === "/metrics" && request.method !== "GET") {
-          return plainResponse("Method Not Allowed", 405, "GET");
-        }
-
-        const metrics = engine.getMetrics();
-
-        if (pathname === "/metrics") {
-          const metricsAuth = checkSession(request);
-          if (metricsAuth) return metricsAuth;
-          return jsonResponse(metrics, 200);
-        }
-
-        const now = performance.now();
-        const stallThresholdMs = Math.max(100, options.network.tickIntervalMs * 3);
-        const lastTickProgressAt = getLastTickProgressAt();
-        const stalled =
-          metrics.core.state === "running" &&
-          Number.isFinite(lastTickProgressAt) &&
-          now - lastTickProgressAt > stallThresholdMs;
-
-        const availableAdapters = engine.getAvailableAdapters();
-        const mqttEnabled = availableAdapters.some(
-          (adapter) => adapter.name === "mqtt" && adapter.enabled,
-        );
-        const opcuaEnabled = availableAdapters.some(
-          (adapter) => adapter.name === "opcua" && adapter.enabled,
-        );
-
-        const mqttConnected = mqttEnabled
-          ? (metrics.adapters.find((a) => a.name === "mqtt")?.metrics.connected ?? false)
-          : false;
-        const opcuaConnected = opcuaEnabled
-          ? (metrics.adapters.find((a) => a.name === "opcua")?.metrics.connected ?? false)
-          : false;
-        const healthBody = buildHealthBody({
-          metrics,
-          stalled,
-          mqttEnabled,
-          mqttConnected,
-          opcuaEnabled,
-          opcuaConnected,
-        });
-
-        if (pathname === "/healthz") {
-          const status = livenessStatus({ core: metrics.core, stalled });
-          return jsonResponse(
-            {
-              status: status.status,
-              ...healthBody,
-              ...(status.reason ? { reason: status.reason } : {}),
-            } satisfies HealthResponseBody,
-            status.status === "ok" ? 200 : 503,
-          );
-        }
-
-        // /readyz
-        const status = readinessStatus({
-          core: metrics.core,
-          stalled,
-          mqttEnabled,
-          mqttConnected,
-          opcuaEnabled,
-          opcuaConnected,
-        });
-        return jsonResponse(
-          {
-            status: status.status,
-            ...healthBody,
-            ...(status.reason ? { reason: status.reason } : {}),
-            ...(options.simulationName ? { simulationName: options.simulationName } : {}),
-            ...(options.runId ? { runId: options.runId } : {}),
-          } satisfies HealthResponseBody,
-          status.status === "ok" ? 200 : 503,
-        );
-      }
-
-      if (pathname === "/state") {
-        if (request.method !== "GET") {
-          return plainResponse("Method Not Allowed", 405, "GET");
-        }
-        const stateAuth = checkSession(request);
-        if (stateAuth) return stateAuth;
-        return jsonResponse(engine.getState(), 200);
-      }
-
-      if (pathname === "/bootstrap") {
-        if (request.method !== "GET") {
-          return plainResponse("Method Not Allowed", 405, "GET");
-        }
-        if (options.auth.anonymousMode) {
-          const runtime: RuntimeSnapshot = wsHub
-            ? wsHub.buildRuntimeSnapshot()
-            : (JSON.parse(
-                JSON.stringify({
-                  state: engine.getState(),
-                  metrics: engine.getMetrics(),
-                  runningTemplates: engine.getRunningTemplates(),
-                  revision: 0,
-                }),
-              ) as RuntimeSnapshot);
-          return jsonResponse(
-            {
-              authenticated: true,
-              username: "anonymous",
-              runtime,
-            } satisfies ConsoleBootstrapResponse,
-            200,
-          );
-        }
-        const session = getSession(request);
-        if (!session) {
-          return jsonResponse({ authenticated: false } satisfies ConsoleBootstrapResponse, 200);
-        }
-        const runtime: RuntimeSnapshot = wsHub
-          ? wsHub.buildRuntimeSnapshot()
-          : (JSON.parse(
-              JSON.stringify({
-                state: engine.getState(),
-                metrics: engine.getMetrics(),
-                runningTemplates: engine.getRunningTemplates(),
-                revision: 0,
-              }),
-            ) as RuntimeSnapshot);
-        const body: ConsoleBootstrapResponse = {
-          authenticated: true,
-          username: session.username,
-          runtime,
-        };
-        return jsonResponse(body, 200);
-      }
-
-      if (pathname === "/commands") {
-        if (request.method !== "POST") {
-          return plainResponse("Method Not Allowed", 405, "POST");
-        }
-        const cmdAuth = checkSession(request);
-        if (cmdAuth) return cmdAuth;
-        const ctBlock = checkContentType(request);
-        if (ctBlock) return ctBlock;
-        const commandOrError = await parseCommandRequest(request);
-        if (commandOrError instanceof Response) {
-          return commandOrError;
-        }
-        return jsonResponse(await engine.execute(commandOrError), 200);
-      }
-
-      // POST /shutdown — graceful shutdown for daemon mode
-      if (pathname === "/shutdown") {
-        if (request.method !== "POST") {
-          return plainResponse("Method Not Allowed", 405, "POST");
-        }
-        if (!options.requestShutdown) {
-          return jsonResponse(
-            {
-              message: "Shutdown not available.",
-              error: "This server does not support remote shutdown.",
-            },
-            501,
-          );
-        }
-        const shutdownAuth = checkSession(request);
-        if (shutdownAuth) return shutdownAuth;
-        const shutdownCtBlock = checkContentType(request);
-        if (shutdownCtBlock) return shutdownCtBlock;
-
-        let reason = "remote shutdown request";
-        try {
-          const body = (await request.json()) as unknown;
-          if (typeof body === "object" && body !== null && "reason" in body) {
-            const maybeReason = (body as Record<string, unknown>)["reason"];
-            if (typeof maybeReason === "string" && maybeReason.length > 0) {
-              reason = maybeReason;
-            }
-          }
-        } catch {
-          // No body or invalid JSON — use default reason
-        }
-
-        options.requestShutdown(reason);
-        return jsonResponse({ status: "shutting_down" }, 200);
-      }
-
-      // --- New REST endpoints (Phase 1c) ---
-
-      // GET /instances/:id
-      if (pathname.startsWith("/instances/")) {
-        if (request.method !== "GET") {
-          return plainResponse("Method Not Allowed", 405, "GET");
-        }
-        const instanceAuth = checkSession(request);
-        if (instanceAuth) return instanceAuth;
-        const instanceId = pathname.slice("/instances/".length);
-        if (!instanceId) {
-          return jsonResponse(
-            { message: "Missing instance ID.", error: "Use /instances/{id}" },
-            400,
-          );
-        }
-        const detail = engine.getInstanceDetail(instanceId);
-        if (!detail) {
-          return jsonResponse(
-            { message: `Instance "${instanceId}" not found.`, error: "Check the instance ID." },
-            404,
-          );
-        }
-        return jsonResponse(detail, 200);
-      }
-
-      // GET /models/:name
-      if (pathname.startsWith("/models/")) {
-        if (request.method !== "GET") {
-          return plainResponse("Method Not Allowed", 405, "GET");
-        }
-        const modelAuth = checkSession(request);
-        if (modelAuth) return modelAuth;
-        const modelName = pathname.slice("/models/".length);
-        if (!modelName) {
-          return jsonResponse({ message: "Missing model name.", error: "Use /models/{name}" }, 400);
-        }
-        const schema = engine.getModelSchema(modelName);
-        if (!schema) {
-          return jsonResponse(
-            { message: `Model "${modelName}" not found.`, error: "Check the model name." },
-            404,
-          );
-        }
-        return jsonResponse(schema, 200);
-      }
-
-      // GET /events
-      if (pathname === "/events") {
-        if (request.method !== "GET") {
-          return plainResponse("Method Not Allowed", 405, "GET");
-        }
-        const eventsAuth = checkSession(request);
-        if (eventsAuth) return eventsAuth;
-        const typeParam = url.searchParams.get("type");
-        if (typeParam && !VALID_EVENT_TYPES.has(typeParam)) {
-          return jsonResponse(
-            {
-              message: `Invalid event type "${typeParam}".`,
-              error: `Valid types: ${[...VALID_EVENT_TYPES].join(", ")}`,
-            },
-            400,
-          );
-        }
-        const instanceIdParam = url.searchParams.get("instanceId");
-        const limitRaw = url.searchParams.get("limit");
-        const cursorRaw = url.searchParams.get("cursor");
-        const query: EventLogQuery = {};
-        if (typeParam)
-          (query as { type: EventLogQuery["type"] }).type = typeParam as EventLogQuery["type"];
-        if (instanceIdParam) (query as { instanceId: string }).instanceId = instanceIdParam;
-        const parsedLimit = limitRaw ? Number.parseInt(limitRaw, 10) : 0;
-        if (parsedLimit > 0 && Number.isFinite(parsedLimit))
-          (query as { limit: number }).limit = parsedLimit;
-        const parsedCursor = cursorRaw ? Number.parseInt(cursorRaw, 10) : Number.NaN;
-        if (Number.isFinite(parsedCursor)) (query as { cursor: number }).cursor = parsedCursor;
-        return jsonResponse(engine.getEventLog(query), 200);
-      }
-
-      // GET /catalog/models
-      if (pathname === "/catalog/models") {
-        if (request.method !== "GET") return plainResponse("Method Not Allowed", 405, "GET");
-        const auth = checkSession(request);
-        if (auth) return auth;
-        const models = options.getCatalogModels ? await options.getCatalogModels() : [];
-        return jsonResponse(models, 200);
-      }
-
-      // GET /catalog/models/:name/le-dt.json
-      if (pathname.startsWith("/catalog/models/") && pathname.endsWith("/le-dt.json")) {
-        if (request.method !== "GET") return plainResponse("Method Not Allowed", 405, "GET");
-        const auth = checkSession(request);
-        if (auth) return auth;
-        const name = decodeURIComponent(
-          pathname.slice("/catalog/models/".length, -"/le-dt.json".length),
-        );
-        if (
-          !name ||
-          name.includes("/") ||
-          name.includes("\\") ||
-          name.includes("..") ||
-          !options.getLeDtJson
-        )
-          return jsonResponse({ message: "Not found.", error: "Model not found." }, 404);
-        const leDtJson = await options.getLeDtJson(name);
-        if (!leDtJson)
-          return jsonResponse(
-            { message: `Model "${name}" not found.`, error: "Check the model name." },
-            404,
-          );
-        return jsonResponse(JSON.parse(leDtJson), 200);
-      }
-
-      // GET /catalog/models/:name/yaml
-      if (pathname.startsWith("/catalog/models/") && pathname.endsWith("/yaml")) {
-        if (request.method !== "GET") return plainResponse("Method Not Allowed", 405, "GET");
-        const auth = checkSession(request);
-        if (auth) return auth;
-        const name = decodeURIComponent(pathname.slice("/catalog/models/".length, -"/yaml".length));
-        if (
-          !name ||
-          name.includes("/") ||
-          name.includes("\\") ||
-          name.includes("..") ||
-          !options.getModelYaml
-        )
-          return jsonResponse({ message: "Not found.", error: "Model not found." }, 404);
-        const yaml = await options.getModelYaml(name);
-        if (!yaml)
-          return jsonResponse(
-            { message: `Model "${name}" not found.`, error: "Check the model name." },
-            404,
-          );
-        return yamlResponse(yaml, 200);
-      }
-
-      // GET /catalog/models/:name (schema)
-      if (pathname.startsWith("/catalog/models/")) {
-        if (request.method !== "GET") return plainResponse("Method Not Allowed", 405, "GET");
-        const auth = checkSession(request);
-        if (auth) return auth;
-        const name = decodeURIComponent(pathname.slice("/catalog/models/".length));
-        if (
-          !name ||
-          name.includes("/") ||
-          name.includes("\\") ||
-          name.includes("..") ||
-          !options.getCatalogModelSchema
-        )
-          return jsonResponse({ message: "Not found.", error: "Model not found." }, 404);
-        const schema = await options.getCatalogModelSchema(name);
-        if (!schema)
-          return jsonResponse(
-            { message: `Model "${name}" not found.`, error: "Check the model name." },
-            404,
-          );
-        return jsonResponse(schema, 200);
-      }
-
-      // GET /catalog/templates/:id/le-template.json and /le-tags.csv
-      if (
-        pathname.startsWith("/catalog/templates/") &&
-        (pathname.endsWith("/le-template.json") || pathname.endsWith("/le-tags.csv"))
-      ) {
-        if (request.method !== "GET") return plainResponse("Method Not Allowed", 405, "GET");
-        const auth = checkSession(request);
-        if (auth) return auth;
-        const isJson = pathname.endsWith("/le-template.json");
-        const suffix = isJson ? "/le-template.json" : "/le-tags.csv";
-        const id = decodeURIComponent(pathname.slice("/catalog/templates/".length, -suffix.length));
-        const host = url.searchParams.get("host")?.trim() ?? "";
-        const protocolParam = url.searchParams.get("protocol") ?? undefined;
-        if (
-          !id ||
-          id.includes("/") ||
-          id.includes("\\") ||
-          id.includes("..") ||
-          !options.getLeExport
-        )
-          return jsonResponse({ message: "Not found.", error: "Template not found." }, 404);
-        if (!host) {
-          return jsonResponse(
-            {
-              message: "Missing host query parameter.",
-              error: "Provide ?host=<hostname-or-ip> reachable from Litmus Edge.",
-            },
-            400,
-          );
-        }
-        const result = await options.getLeExport(id, {
-          host,
-          protocol: protocolParam as import("@miravo/shared").ProtocolName | undefined,
-        });
-        if (!result)
-          return jsonResponse(
-            { message: `Template "${id}" not found.`, error: "Check the template ID." },
-            404,
-          );
-        return isJson
-          ? new Response(result.templateJson, {
-              status: 200,
-              headers: {
-                "content-type": "application/json",
-                "content-disposition": `attachment; filename="${id}.le-template.json"`,
-              },
-            })
-          : new Response(result.tagsCSV, {
-              status: 200,
-              headers: {
-                "content-type": "text/csv",
-                "content-disposition": `attachment; filename="${id}-tags.csv"`,
-              },
-            });
-      }
-
-      // GET /catalog/templates/:id/yaml
-      if (pathname.startsWith("/catalog/templates/") && pathname.endsWith("/yaml")) {
-        if (request.method !== "GET") return plainResponse("Method Not Allowed", 405, "GET");
-        const auth = checkSession(request);
-        if (auth) return auth;
-        const id = decodeURIComponent(
-          pathname.slice("/catalog/templates/".length, -"/yaml".length),
-        );
-        if (
-          !id ||
-          id.includes("/") ||
-          id.includes("\\") ||
-          id.includes("..") ||
-          !options.getTemplateYaml
-        )
-          return jsonResponse({ message: "Not found.", error: "Template not found." }, 404);
-        const yaml = await options.getTemplateYaml(id);
-        if (!yaml)
-          return jsonResponse(
-            { message: `Template "${id}" not found.`, error: "Check the template ID." },
-            404,
-          );
-        return yamlResponse(yaml, 200);
-      }
-
-      // GET /catalog/templates/:id (detail with topology)
-      if (pathname.startsWith("/catalog/templates/") && pathname !== "/catalog/templates") {
-        if (request.method !== "GET") return plainResponse("Method Not Allowed", 405, "GET");
-        const auth = checkSession(request);
-        if (auth) return auth;
-        const id = decodeURIComponent(pathname.slice("/catalog/templates/".length));
-        if (
-          !id ||
-          id.includes("/") ||
-          id.includes("\\") ||
-          id.includes("..") ||
-          !options.getTemplateDetail
-        )
-          return jsonResponse({ message: "Not found.", error: "Template not found." }, 404);
-        const detail = await options.getTemplateDetail(id);
-        if (!detail)
-          return jsonResponse(
-            { message: `Template "${id}" not found.`, error: "Check the template ID." },
-            404,
-          );
-        return jsonResponse(detail, 200);
-      }
-
-      // GET /catalog/templates
-      if (pathname === "/catalog/templates") {
-        if (request.method !== "GET") {
-          return plainResponse("Method Not Allowed", 405, "GET");
-        }
-        const catalogAuth = checkSession(request);
-        if (catalogAuth) return catalogAuth;
-        const catalog = options.getCatalog ? options.getCatalog() : [];
-        return jsonResponse(catalog, 200);
-      }
-
-      // GET /running-templates
-      if (pathname === "/running-templates") {
-        if (request.method !== "GET") {
-          return plainResponse("Method Not Allowed", 405, "GET");
-        }
-        const rtAuth = checkSession(request);
-        if (rtAuth) return rtAuth;
-        return jsonResponse(engine.getRunningTemplates(), 200);
-      }
-
-      // GET /manifest
-      if (pathname === "/manifest") {
-        if (request.method !== "GET") {
-          return plainResponse("Method Not Allowed", 405, "GET");
-        }
-        const manifestAuth = checkSession(request);
-        if (manifestAuth) return manifestAuth;
-        return jsonResponse(engine.getManifest(), 200);
-      }
-
-      // --- Auth routes ---
-
-      if (pathname === "/auth/login" && request.method === "POST") {
-        return handleLogin(request, auth);
-      }
-
-      if (pathname === "/auth/logout" && request.method === "POST") {
-        return handleLogout(request, auth);
-      }
-
-      if (pathname === "/auth/password" && request.method === "PUT") {
-        const pwAuth = checkSession(request);
-        if (pwAuth) return pwAuth;
-        return handlePasswordChange(request, auth);
-      }
-
-      if (pathname === "/auth/status") {
-        if (request.method !== "GET") {
-          return plainResponse("Method Not Allowed", 405, "GET");
-        }
-        return handleAuthStatus(request, auth);
-      }
-
-      // --- Platform routes (LE apply/cleanup) ---
-      if (pathname.startsWith("/platforms/")) {
-        const platformResponse = await handlePlatformRoute(
-          pathname,
-          request,
-          checkSession,
-          options.eventLog,
-        );
-        if (platformResponse) return platformResponse;
-      }
-
-      // --- Console static file serving ---
-      if (consoleIndexFile && consoleDir) {
-        if (pathname !== "/") {
-          // Resolve and verify the path stays within consoleDir to prevent traversal.
-          const resolvedFile = resolve(consoleDir, `.${pathname}`);
-          if (resolvedFile.startsWith(`${consoleDir}/`)) {
-            const file = Bun.file(resolvedFile);
-            if (await file.exists()) {
-              return new Response(file);
-            }
-          }
-        }
-        // SPA fallback: serve pre-verified index.html
-        return new Response(consoleIndexFile);
-      }
-
-      return plainResponse("Not Found", 404);
-    },
-    websocket: wsHub
-      ? {
-          open(ws: import("bun").ServerWebSocket<unknown>) {
-            wsHub.onOpen(ws as import("bun").ServerWebSocket<WSClientData>);
-          },
-          message(ws: import("bun").ServerWebSocket<unknown>, message: string | Buffer) {
-            wsHub.onMessage(ws as import("bun").ServerWebSocket<WSClientData>, message);
-          },
-          close(ws: import("bun").ServerWebSocket<unknown>) {
-            wsHub.onClose(ws as import("bun").ServerWebSocket<WSClientData>);
-          },
-        }
-      : {
-          open() {},
-          message() {},
-          close() {},
-        },
-  });
-
-  return {
-    endpoint: `http://${host}:${server.port}`,
-    wsHub,
-    stop() {
-      auth.sessionStore.clear();
-      wsHub?.close();
-      server.stop(true);
-    },
-  };
-}
-
-export { startAdminServer };