Merge pull request #7 from OpenElementsLabs/feat/status-capabilities

feat: add capabilities panel to server status page (0.7.0)

Author: hendrikebbers

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-elements/nextjs-app-layer",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Next.js foundation (auth, proxy, admin pages, login/forbidden, layout) for Open Elements applications",
   "packageManager": "pnpm@11.3.0",
   "engines": {
@@ -51,7 +51,7 @@
     "prepublishOnly": "pnpm run build"
   },
   "peerDependencies": {
-    "@open-elements/ui": "^0.8.0",
+    "@open-elements/ui": "^0.9.0",
     "lucide-react": "^0.500.0",
     "next": "^15.3.0",
     "next-auth": "5.0.0-beta.30",
@@ -60,7 +60,7 @@
   },
   "devDependencies": {
     "@eslint/js": "^9.0.0",
-    "@open-elements/ui": "^0.8.0",
+    "@open-elements/ui": "^0.9.0",
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/react": "^16.3.2",
     "@types/react": "^19.0.0",

pnpm-lock.yaml

@@ -7,4 +7,4 @@ allowBuilds:
   sharp: true
 
 minimumReleaseAgeExclude:
-  - '@open-elements/ui@0.8.0'
+  - '@open-elements/ui@0.9.0'

pnpm-workspace.yaml

@@ -31,6 +31,10 @@ export { usersPageMeta } from "./pages/admin/users/meta";
 
 export { createServerStatusPage } from "./pages/admin/status/page";
 export { ServerStatusClient } from "./pages/admin/status/server-status-client";
+export type {
+  StatusCapabilitiesConfig,
+  StatusCapabilityItem,
+} from "./pages/admin/status/server-status-client";
 export { serverStatusPageMeta } from "./pages/admin/status/meta";
 
 export { createBearerTokenPage } from "./pages/admin/token/page";

src/index.ts

@@ -0,0 +1,103 @@
+import { describe, it, expect, afterEach, vi } from "vitest";
+import { cleanup, screen, waitFor } from "@testing-library/react";
+import { ServerStatusClient, type StatusCapabilitiesConfig } from "../server-status-client";
+import { renderWithLibProviders } from "../../../../test/render-with-providers";
+
+const HEIC_CONFIG: StatusCapabilitiesConfig = {
+  endpoint: "/api/admin/capabilities",
+  items: [
+    {
+      id: "heicAvailable",
+      label: "HEIC image decoding",
+      availableText: "Available",
+      unavailableText: "Not available",
+      hint: "HEIC uploads will be rejected with 415 — check Dockerfile",
+    },
+  ],
+};
+
+function jsonResponse(body: unknown): Response {
+  return { ok: true, json: () => Promise.resolve(body) } as unknown as Response;
+}
+
+/** Route fetch responses by URL; an unmapped URL rejects (surfacing test gaps). */
+function stubFetch(handlers: Record<string, () => Promise<Response>>) {
+  vi.stubGlobal(
+    "fetch",
+    vi.fn((input: RequestInfo | URL) => {
+      const url = typeof input === "string" ? input : input.toString();
+      const handler = handlers[url];
+      if (!handler) {
+        return Promise.reject(new Error(`unexpected fetch: ${url}`));
+      }
+      return handler();
+    }),
+  );
+}
+
+afterEach(() => {
+  cleanup();
+  vi.unstubAllGlobals();
+});
+
+describe("ServerStatusClient", () => {
+  it("renders only the backend health row when no capabilities config is given", async () => {
+    stubFetch({
+      "/api/health": () => Promise.resolve(jsonResponse({ status: "UP" })),
+    });
+
+    renderWithLibProviders(<ServerStatusClient />);
+
+    await waitFor(() => expect(screen.getByText("System Status")).toBeInTheDocument());
+    expect(screen.queryByText("HEIC image decoding")).not.toBeInTheDocument();
+  });
+
+  it("renders a green capability row from the fetched capabilities map", async () => {
+    stubFetch({
+      "/api/health": () => Promise.resolve(jsonResponse({ status: "UP" })),
+      "/api/admin/capabilities": () => Promise.resolve(jsonResponse({ heicAvailable: true })),
+    });
+
+    renderWithLibProviders(<ServerStatusClient capabilities={HEIC_CONFIG} />);
+
+    await waitFor(() => expect(screen.getByText("HEIC image decoding")).toBeInTheDocument());
+    expect(screen.getByText("Available")).toBeInTheDocument();
+    // Backend health row is still present.
+    expect(screen.getByText("System Status")).toBeInTheDocument();
+  });
+
+  it("renders the capability as available=false when the endpoint reports it unavailable", async () => {
+    stubFetch({
+      "/api/health": () => Promise.resolve(jsonResponse({ status: "UP" })),
+      "/api/admin/capabilities": () => Promise.resolve(jsonResponse({ heicAvailable: false })),
+    });
+
+    renderWithLibProviders(<ServerStatusClient capabilities={HEIC_CONFIG} />);
+
+    await waitFor(() => expect(screen.getByText("Not available")).toBeInTheDocument());
+  });
+
+  it("fails safe to unavailable when the capabilities fetch rejects", async () => {
+    stubFetch({
+      "/api/health": () => Promise.resolve(jsonResponse({ status: "UP" })),
+      "/api/admin/capabilities": () => Promise.reject(new Error("network down")),
+    });
+
+    renderWithLibProviders(<ServerStatusClient capabilities={HEIC_CONFIG} />);
+
+    await waitFor(() => expect(screen.getByText("Not available")).toBeInTheDocument());
+    expect(screen.queryByText("Available")).not.toBeInTheDocument();
+  });
+
+  it("fails safe to unavailable when the capabilities endpoint returns a non-ok response", async () => {
+    stubFetch({
+      "/api/health": () => Promise.resolve(jsonResponse({ status: "UP" })),
+      "/api/admin/capabilities": () =>
+        Promise.resolve({ ok: false, json: () => Promise.resolve(null) } as unknown as Response),
+    });
+
+    renderWithLibProviders(<ServerStatusClient capabilities={HEIC_CONFIG} />);
+
+    await waitFor(() => expect(screen.getByText("Not available")).toBeInTheDocument());
+  });
+});

src/pages/admin/status/__tests__/server-status-client.test.tsx

@@ -1,22 +1,24 @@
 import type { Session } from "next-auth";
 import { ForbiddenPage } from "../../../components/forbidden-page";
 import { ROLE_IT_ADMIN } from "../../../lib/roles";
-import { ServerStatusClient } from "./server-status-client";
+import { ServerStatusClient, type StatusCapabilitiesConfig } from "./server-status-client";
 
 type AuthFn = () => Promise<Session | null>;
 
 export function createServerStatusPage({
   auth,
   homeRoute,
+  capabilities,
 }: {
   readonly auth: AuthFn;
   readonly homeRoute?: string;
+  readonly capabilities?: StatusCapabilitiesConfig;
 }) {
   return async function ServerStatusPage() {
     const session = await auth();
     if (!session?.roles?.includes(ROLE_IT_ADMIN)) {
       return <ForbiddenPage homeRoute={homeRoute} />;
     }
-    return <ServerStatusClient />;
+    return <ServerStatusClient capabilities={capabilities} />;
   };
 }

src/pages/admin/status/page.tsx

@@ -1,12 +1,35 @@
 "use client";
 
 import { useEffect, useState } from "react";
-import { HealthStatus } from "@open-elements/ui";
+import { CapabilityStatus, HealthStatus } from "@open-elements/ui";
 import { useAppLayerTranslations } from "../../../translations/provider";
 
-export function ServerStatusClient() {
+/** One runtime-capability row configured by the consuming app. */
+export interface StatusCapabilityItem {
+  /** Matches a boolean key returned by the capabilities endpoint. */
+  readonly id: string;
+  readonly label: string;
+  readonly availableText: string;
+  readonly unavailableText: string;
+  readonly hint?: string;
+}
+
+/** Optional "runtime capabilities" panel for the server status page. */
+export interface StatusCapabilitiesConfig {
+  /** App endpoint returning a `{ [id]: boolean }` map (fetched via the Next proxy). */
+  readonly endpoint: string;
+  readonly items: ReadonlyArray<StatusCapabilityItem>;
+}
+
+export function ServerStatusClient({
+  capabilities,
+}: {
+  readonly capabilities?: StatusCapabilitiesConfig;
+}) {
   const t = useAppLayerTranslations();
   const [healthy, setHealthy] = useState<boolean | null>(null);
+  // `null` until the capabilities fetch settles; then a `{ id -> available }` map.
+  const [capabilityState, setCapabilityState] = useState<Record<string, boolean> | null>(null);
 
   useEffect(() => {
     fetch("/api/health")
@@ -15,19 +38,57 @@ export function ServerStatusClient() {
       .catch(() => setHealthy(false));
   }, []);
 
+  useEffect(() => {
+    if (!capabilities) {
+      return;
+    }
+    let cancelled = false;
+    // Fail-safe: any failure resolves to an empty map, so every configured row
+    // renders as unavailable — an operator must never see a false "available".
+    fetch(capabilities.endpoint)
+      .then((res) => (res.ok ? res.json() : null))
+      .then((data: Record<string, boolean> | null) => {
+        if (!cancelled) {
+          setCapabilityState(data ?? {});
+        }
+      })
+      .catch(() => {
+        if (!cancelled) {
+          setCapabilityState({});
+        }
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [capabilities]);
+
   return (
     <div>
       <h1 className="mb-6 font-heading text-2xl font-bold text-oe-dark">{t.nav.serverStatus}</h1>
-      {healthy !== null && (
-        <HealthStatus
-          healthy={healthy}
-          translations={{
-            title: t.health.title,
-            statusUp: t.health.statusUp,
-            statusDown: t.health.statusDown,
-          }}
-        />
-      )}
+      <div className="space-y-4">
+        {healthy !== null && (
+          <HealthStatus
+            healthy={healthy}
+            translations={{
+              title: t.health.title,
+              statusUp: t.health.statusUp,
+              statusDown: t.health.statusDown,
+            }}
+          />
+        )}
+        {capabilities &&
+          capabilityState !== null &&
+          capabilities.items.map((item) => (
+            <CapabilityStatus
+              key={item.id}
+              available={capabilityState[item.id] === true}
+              label={item.label}
+              availableText={item.availableText}
+              unavailableText={item.unavailableText}
+              hint={item.hint}
+            />
+          ))}
+      </div>
     </div>
   );
 }