@rapidmx/web-client 0.17.2 → 0.19.0

package/apps/shared/components/admin/diagnostics/logLines.ts

@@ -0,0 +1,125 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+
+/** The levels of the server's logger (Winston's npm levels), most severe first. */
+export const LOG_LEVELS = ["error", "warn", "info", "http", "verbose", "debug", "silly"] as const;
+
+export type LogLevel = (typeof LOG_LEVELS)[number];
+
+/** One line of the server's log stream. */
+export interface LogEntry {
+    /** Counts up from 1 in the order lines arrived; unique for the life of the stream. */
+    id: number;
+    /** When this page received it (`Date.now()`). */
+    receivedAt: number;
+    /** The level as the server wrote it (lower-cased, without colour codes); empty when it wrote none. */
+    level: string;
+    message: string;
+    /** As the server wrote it, when it did. */
+    timestamp?: string;
+    /** Every other field the server logged with the line (`label`, `service`, `stack`, ...). */
+    extra: Record<string, unknown>;
+    /** The frame as one line of JSON: what the `.ndjson` download holds. */
+    json: string;
+    /** Whether the frame was JSON. A frame that was not is shown as it came, with no level. */
+    structured: boolean;
+}
+
+/** What a frame is, when it is the server's own control message and not a log line. */
+export interface ControlFrame {
+    control: true;
+    success: boolean;
+    data: unknown;
+}
+
+/** Colour codes a logger writes around a level (`\u001b[32minfo\u001b[39m`). */
+// eslint-disable-next-line no-control-regex
+const ANSI_PATTERN = /\u001b\[[0-9;]*m/g;
+
+export const stripAnsi = (text: string): string => text.replace(ANSI_PATTERN, "");
+
+/** A field's value as text: a string as it is, nothing as empty, anything else as JSON. */
+function textOf(value: unknown): string {
+    if (typeof value === "string") {
+        return stripAnsi(value);
+    }
+    return value === undefined ? "" : JSON.stringify(value);
+}
+
+/**
+ * Reads one frame of the log stream. It is the control message (`{"id":0,"type":"SUBSCRIBED","success":true,...}`), a Winston
+ * `info` object (the JSON of `level`, `message` and whatever else was logged with them), or - since the server's logger can write
+ * anything - text that is not JSON at all. Whatever it is, the frame is never refused: a missing field is left empty.
+ */
+export function parseLogFrame(raw: string, id: number, receivedAt: number): LogEntry | ControlFrame {
+    let parsed: unknown;
+    try {
+        parsed = JSON.parse(raw);
+    } catch {
+        parsed = undefined;
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        return {
+            id,
+            receivedAt,
+            level: "",
+            message: stripAnsi(raw),
+            extra: {},
+            json: JSON.stringify({ raw }),
+            structured: false,
+        };
+    }
+    const frame = parsed as Record<string, unknown>;
+    if (frame.type === "SUBSCRIBED" && frame.level === undefined) {
+        return { control: true, success: frame.success !== false, data: frame.data };
+    }
+    const { level, message, timestamp, ...extra } = frame;
+    return {
+        id,
+        receivedAt,
+        level: textOf(level).toLowerCase(),
+        message: textOf(message),
+        timestamp: typeof timestamp === "string" ? timestamp : undefined,
+        extra,
+        json: JSON.stringify(frame),
+        structured: true,
+    };
+}
+
+export const isControlFrame = (frame: LogEntry | ControlFrame): frame is ControlFrame => "control" in frame;
+
+/** When a line happened: what the server stamped it with, else when this page received it. */
+export function entryTime(entry: LogEntry): string {
+    return entry.timestamp ?? new Date(entry.receivedAt).toISOString();
+}
+
+/** `<timestamp> <LEVEL> <message>`: the line of a `.log` download. A line with no level has none written. */
+export function formatLogLine(entry: LogEntry): string {
+    return [entryTime(entry), entry.level.toUpperCase(), entry.message].filter((part) => part !== "").join(" ");
+}
+
+/** The text of a `.log` download: one formatted line for each entry. */
+export function entriesToLog(entries: LogEntry[]): string {
+    return entries.map((entry) => formatLogLine(entry).replace(/\r?\n/g, " ↵ ")).join("\n") + "\n";
+}
+
+/** The text of an `.ndjson` download: each frame as one line of JSON. */
+export function entriesToNdjson(entries: LogEntry[]): string {
+    return entries.map((entry) => entry.json).join("\n") + "\n";
+}
+
+/** Whether `entry` is one of `levels`. A line with no known level (text that was not JSON, an unusual level) is always kept. */
+export function levelVisible(entry: LogEntry, levels: ReadonlySet<string>): boolean {
+    return !(LOG_LEVELS as readonly string[]).includes(entry.level) || levels.has(entry.level);
+}
+
+/** Whether `entry` contains `needle` (already lower-cased) in its time, level, message or other fields. */
+export function entryMatches(entry: LogEntry, needle: string): boolean {
+    if (needle === "") {
+        return true;
+    }
+    const extra = Object.keys(entry.extra).length > 0 ? JSON.stringify(entry.extra) : "";
+    return `${formatLogLine(entry)} ${extra}`.toLowerCase().includes(needle);
+}

package/apps/shared/components/admin/diagnostics/metricsHistory.ts

@@ -0,0 +1,28 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import type { DiagnosticsMetrics } from "./diagnosticsApi.js";
+
+/** How often the System tab asks the server for a new sample. */
+export const METRICS_POLL_INTERVAL_MS = 5000;
+
+/** How many samples the System tab keeps: the last five minutes at `METRICS_POLL_INTERVAL_MS`. */
+export const METRICS_HISTORY_SIZE = 60;
+
+/** `history` with `sample` added, the oldest samples dropped beyond `METRICS_HISTORY_SIZE`. */
+export function appendSample(history: DiagnosticsMetrics[], sample: DiagnosticsMetrics): DiagnosticsMetrics[] {
+    return [...history, sample].slice(-METRICS_HISTORY_SIZE);
+}
+
+/** The values `pick` finds in each sample, in order. A sample it finds nothing in (a node with no stats yet, say) is skipped. */
+export function seriesOf(history: DiagnosticsMetrics[], pick: (sample: DiagnosticsMetrics) => number | undefined): number[] {
+    const values: number[] = [];
+    for (const sample of history) {
+        const value = pick(sample);
+        if (typeof value === "number" && Number.isFinite(value)) {
+            values.push(value);
+        }
+    }
+    return values;
+}

package/apps/shared/components/admin/diagnostics/useDiagnosticsResource.ts

@@ -0,0 +1,44 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { useEffect, useState } from "react";
+import { describeError } from "./format.js";
+
+export interface DiagnosticsResource<T> {
+    /** What was last loaded. It stays while a reload is under way, and after a reload that failed. */
+    data: T | undefined;
+    /** Why the last load failed. */
+    error: string | undefined;
+    loading: boolean;
+}
+
+/**
+ * Loads `load()` when the component mounts and again whenever `reloadKey` changes (the Refresh button). It is never polled.
+ * The answer to a load that a newer one (or an unmount) has overtaken is dropped.
+ */
+export function useDiagnosticsResource<T>(load: () => Promise<T>, reloadKey: number, failure: string): DiagnosticsResource<T> {
+    const [state, setState] = useState<DiagnosticsResource<T>>({ data: undefined, error: undefined, loading: true });
+
+    useEffect(() => {
+        let cancelled = false;
+        setState((previous) => ({ ...previous, error: undefined, loading: true }));
+        load().then(
+            (data) => {
+                if (!cancelled) {
+                    setState({ data, error: undefined, loading: false });
+                }
+            },
+            (err: unknown) => {
+                if (!cancelled) {
+                    setState((previous) => ({ ...previous, error: describeError(err, failure), loading: false }));
+                }
+            }
+        );
+        return () => {
+            cancelled = true;
+        };
+    }, [reloadKey]);
+
+    return state;
+}

package/apps/shared/components/admin/diagnostics/useLogStream.ts

@@ -0,0 +1,122 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { useCallback, useEffect, useRef, useState } from "react";
+import { LogClient, LogClientOptions, LogStreamStatus } from "./logClient.js";
+import type { LogEntry } from "./logLines.js";
+import { LogStore } from "./LogStore.js";
+
+/** Lines arrive in bursts; the view is redrawn at most this often, however many came. */
+export const LOG_FLUSH_MS = 100;
+
+/** What a capture has recorded, without the lines (which can be tens of thousands: `LogStream.captureEntries()` has them). */
+export interface CaptureSummary {
+    active: boolean;
+    startedAt: number;
+    stoppedAt: number | undefined;
+    count: number;
+    missed: number;
+}
+
+export interface LogStream {
+    status: LogStreamStatus;
+    /** Why the stream is in the `error` state. */
+    error: string | undefined;
+    /** Whether the stream is on (connecting, live or trying again), as opposed to stopped or refused. */
+    running: boolean;
+    /** The display buffer: the most recent lines, oldest first. */
+    entries: LogEntry[];
+    /** How many older lines the display buffer has dropped. */
+    dropped: number;
+    capture: CaptureSummary | undefined;
+    start: () => void;
+    stop: () => void;
+    /** Empties the display buffer (not a capture). */
+    clear: () => void;
+    startCapture: () => void;
+    stopCapture: () => void;
+    /** Every line of the capture, for a download. */
+    captureEntries: () => LogEntry[];
+}
+
+interface Snapshot {
+    entries: LogEntry[];
+    dropped: number;
+    capture: CaptureSummary | undefined;
+}
+
+function snapshotOf(store: LogStore): Snapshot {
+    const capture = store.capture;
+    return {
+        entries: store.entries.slice(),
+        dropped: store.dropped,
+        capture: capture && {
+            active: capture.active,
+            startedAt: capture.startedAt,
+            stoppedAt: capture.stoppedAt,
+            count: capture.entries.length,
+            missed: capture.missed,
+        },
+    };
+}
+
+/**
+ * The live log stream of the server for the log view: a `LogClient`, and a `LogStore` holding the lines and any capture. Nothing
+ * connects until `start()`. The stream is closed, and the redraw timer cleared, when the component unmounts.
+ */
+export function useLogStream(options: LogClientOptions = {}): LogStream {
+    const [client] = useState(() => new LogClient(options));
+    const [store] = useState(() => new LogStore());
+    const [connection, setConnection] = useState<{ status: LogStreamStatus; error: string | undefined }>({
+        status: client.status,
+        error: undefined,
+    });
+    const [snapshot, setSnapshot] = useState<Snapshot>(() => snapshotOf(store));
+    const timer = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
+
+    const flush = useCallback(() => {
+        clearTimeout(timer.current);
+        timer.current = undefined;
+        setSnapshot(snapshotOf(store));
+    }, [store]);
+
+    useEffect(() => {
+        const stopEntries = client.onEntry((entry) => {
+            store.add(entry);
+            timer.current ??= setTimeout(flush, LOG_FLUSH_MS);
+        });
+        const stopStatus = client.onStatus((status, error) => setConnection({ status, error }));
+        return () => {
+            stopEntries();
+            stopStatus();
+            client.stop();
+            clearTimeout(timer.current);
+            timer.current = undefined;
+        };
+    }, [client, store, flush]);
+
+    return {
+        status: connection.status,
+        error: connection.error,
+        running: connection.status === "connecting" || connection.status === "live" || connection.status === "reconnecting",
+        entries: snapshot.entries,
+        dropped: snapshot.dropped,
+        capture: snapshot.capture,
+        start: () => client.start(),
+        stop: () => client.stop(),
+        clear: () => {
+            store.clear();
+            flush();
+        },
+        startCapture: () => {
+            store.startCapture(Date.now());
+            flush();
+        },
+        stopCapture: () => {
+            store.stopCapture(Date.now());
+            flush();
+        },
+        captureEntries: () => store.capture?.entries ?? [],
+    };
+}

package/apps/shared/components/admin/diagnostics/useMetricsPolling.ts

@@ -0,0 +1,84 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { useEffect, useState } from "react";
+import { DiagnosticsMetrics, getDiagnosticsMetrics } from "./diagnosticsApi.js";
+import { describeError, isPermissionError } from "./format.js";
+import { appendSample, METRICS_POLL_INTERVAL_MS } from "./metricsHistory.js";
+
+export interface MetricsPolling {
+    /** The last `METRICS_HISTORY_SIZE` samples, oldest first. */
+    history: DiagnosticsMetrics[];
+    /** Why the last request failed, until one succeeds. */
+    error: string | undefined;
+    /** Whether nothing has been answered yet. */
+    loading: boolean;
+    /** Whether polling is stopped by the viewer (Pause), or because the server refused the viewer. */
+    paused: boolean;
+    setPaused: (paused: boolean) => void;
+}
+
+/**
+ * Samples `getDiagnosticsMetrics()` every `METRICS_POLL_INTERVAL_MS` while `enabled` and not paused, keeping the last
+ * `METRICS_HISTORY_SIZE`. A request is only ever made when the previous one has answered, none is made while the page is
+ * hidden (one is made at once when it is shown again), and polling stops when the component unmounts. A refusal (401/403)
+ * pauses polling, since asking again would only be refused again; Resume tries once more. Any other failure is shown
+ * and polling carries on, so a blip on the server does not need the viewer to do anything.
+ */
+export function useMetricsPolling(enabled: boolean): MetricsPolling {
+    const [history, setHistory] = useState<DiagnosticsMetrics[]>([]);
+    const [error, setError] = useState<string | undefined>();
+    const [loading, setLoading] = useState(true);
+    const [paused, setPaused] = useState(false);
+
+    useEffect(() => {
+        if (!enabled || paused) {
+            return;
+        }
+        let cancelled = false;
+        let inFlight = false;
+
+        async function sample() {
+            if (inFlight || document.hidden) {
+                return;
+            }
+            inFlight = true;
+            try {
+                const next = await getDiagnosticsMetrics();
+                if (!cancelled) {
+                    setHistory((previous) => appendSample(previous, next));
+                    setError(undefined);
+                }
+            } catch (err) {
+                if (!cancelled) {
+                    setError(describeError(err, "Could not read the server's metrics."));
+                    if (isPermissionError(err)) {
+                        setPaused(true);
+                    }
+                }
+            } finally {
+                inFlight = false;
+                if (!cancelled) {
+                    setLoading(false);
+                }
+            }
+        }
+
+        void sample();
+        const timer = setInterval(() => void sample(), METRICS_POLL_INTERVAL_MS);
+        const onVisibilityChange = () => {
+            if (!document.hidden) {
+                void sample();
+            }
+        };
+        document.addEventListener("visibilitychange", onVisibilityChange);
+        return () => {
+            cancelled = true;
+            clearInterval(timer);
+            document.removeEventListener("visibilitychange", onVisibilityChange);
+        };
+    }, [enabled, paused]);
+
+    return { history, error, loading, paused, setPaused };
+}

package/apps/shared/components/admin/layout/AdminShell.tsx

@@ -8,6 +8,7 @@ import { useRouter } from "@rapidrest/react/client";
 import {
     HiOutlineClipboardDocumentList,
     HiOutlineClock,
+    HiOutlineCpuChip,
     HiOutlineDocumentArrowDown,
     HiOutlineDocumentCheck,
     HiOutlineGlobeAlt,
@@ -61,6 +62,7 @@ export type AdminSection =
     | "setup"
     | "dataRequests"
     | "plugins"
+    | "diagnostics"
     | "branding"
     | "signingCertificates";
 
@@ -144,6 +146,7 @@ const NAV_ITEMS: NavItem[] = [
         icon: HiOutlineDocumentCheck,
     },
     { id: "plugins", href: "/admin/plugins", label: "Plugins", icon: HiOutlinePuzzlePiece },
+    { id: "diagnostics", href: "/admin/diagnostics", label: "Diagnostics", icon: HiOutlineCpuChip },
     { id: "branding", href: "/admin/branding", label: "Branding", icon: HiOutlinePaintBrush },
 ];
 

package/apps/shared/components/admin/settings/PluginsManager.tsx

@@ -15,6 +15,7 @@ import {
     planPluginChange,
     Plugin,
     PluginChangePlan,
+    PluginConfiguredSetting,
     PluginInstanceStatus,
     PluginNamespace,
     PluginPurgeInfo,
@@ -1315,13 +1316,39 @@ function suggestedHost(definition: PluginSettingDefinition, saved: PluginSetting
     return unset ? definition.default.split(HOST_PLACEHOLDER).join(window.location.host) : undefined;
 }
 
-/** A setting's current form value: its saved value, else its default - or, for a required select with neither, its
- * first option. Kept as a string for text inputs. */
-function initialValue(definition: PluginSettingDefinition, saved: PluginSettingValue | undefined): PluginSettingValue | "" {
+/** What the deployment configures for a setting, as a form value: nothing for a secret, whose value the server keeps to itself. */
+function configuredValue(definition: PluginSettingDefinition, configured: PluginConfiguredSetting): PluginSettingValue | "" {
+    if (definition.type === "boolean") {
+        return configured.value === true;
+    }
+    return configured.value === undefined ? "" : String(configured.value);
+}
+
+/** Whether a saved value is absent - nothing, or the empty value a plugin's own "" default is saved as. */
+function isUnsaved(saved: PluginSettingValue | undefined): boolean {
+    return saved === undefined || saved === "";
+}
+
+/** The suggestion for the host, unless the deployment configures the setting, which is offered instead. */
+function hostSuggestion(definition: PluginSettingDefinition, saved: PluginSettingValue | undefined, configured: PluginConfiguredSetting | undefined): string | undefined {
+    return configured ? undefined : suggestedHost(definition, saved);
+}
+
+/** A setting's current form value: its saved value (which wins over the deployment's configuration); else what the
+ * deployment configures; else the setting's own default - or, for a required select with none of those, its first
+ * option. Kept as a string for text inputs. */
+function initialValue(
+    definition: PluginSettingDefinition,
+    saved: PluginSettingValue | undefined,
+    configured?: PluginConfiguredSetting,
+): PluginSettingValue | "" {
+    if (configured && isUnsaved(saved)) {
+        return configuredValue(definition, configured);
+    }
     if (needsSelection(definition, saved)) {
         return definition.options![0].value;
     }
-    const suggestion = suggestedHost(definition, saved);
+    const suggestion = hostSuggestion(definition, saved, configured);
     if (suggestion !== undefined) {
         return suggestion;
     }
@@ -1335,29 +1362,53 @@ function initialValue(definition: PluginSettingDefinition, saved: PluginSettingV
 function SettingsModal({ plugin, onClose, onSaved }: { plugin: Plugin; onClose: () => void; onSaved: (plugin: Plugin) => void }) {
     // Only opened from the Settings button, which is only shown for a plugin that declares settings.
     const definitions: PluginSettingDefinition[] = plugin.manifest.settings!;
-    const initial = useRef(Object.fromEntries(definitions.map((d) => [d.key, initialValue(d, plugin.settings[d.key])])));
+    const initial = useRef(Object.fromEntries(definitions.map((d) => [d.key, initialValue(d, plugin.settings[d.key], plugin.configured?.[d.key])])));
     const [values, setValues] = useState<Record<string, PluginSettingValue | "">>(initial.current);
+    // Set by Reset: saving then drops every saved value, so the deployment's configuration (or the default) applies again.
+    const [resetting, setResetting] = useState(false);
     const [error, setError] = useState<string | null>(null);
     const [busy, setBusy] = useState(false);
 
+    /** Puts every field back to what it shows with nothing saved. Nothing is stored until the form is saved. */
+    function reset() {
+        setValues(Object.fromEntries(definitions.map((d) => [d.key, initialValue(d, undefined, plugin.configured?.[d.key])])));
+        setResetting(true);
+        setError(null);
+    }
+
     async function save(e: FormEvent) {
         e.preventDefault();
         // The server replaces the whole settings object, so every setting is sent. One left alone is sent as it's saved
         // - `null` when nothing is, so it keeps following the plugin's default rather than pinning the default shown.
         // A required select with nothing to fall back on, and a setting offering this console's host, are sent as the
-        // form shows them.
+        // form shows them. What the deployment configures is never saved as a copy, which would outrank it when it changes
+        // - a field that shows it is sent as nothing.
         const settings: Record<string, PluginSettingValue | null> = {};
         let changed = false;
         for (const definition of definitions) {
             const key: string = definition.key;
+            const configured: PluginConfiguredSetting | undefined = plugin.configured?.[key];
+            const saved: PluginSettingValue | undefined = plugin.settings[key];
             const value = values[key];
-            if (value === initial.current[key] && !needsSelection(definition, plugin.settings[key]) && suggestedHost(definition, plugin.settings[key]) === undefined) {
-                settings[key] = plugin.settings[key] ?? null;
+            if (resetting && value === initialValue(definition, undefined, configured)) {
+                // What a fresh install saves: only a default naming this console's host has to be, for the plugin to work.
+                // A saved value that already is the default shown stays, since dropping it changes nothing.
+                settings[key] = !configured && saved !== undefined && String(saved) === String(value) ? saved : (hostSuggestion(definition, undefined, configured) ?? null);
+                changed ||= settings[key] !== (saved ?? null);
+                continue;
+            }
+            if (!resetting && value === initial.current[key] && !needsSelection(definition, saved) && hostSuggestion(definition, saved, configured) === undefined) {
+                settings[key] = saved ?? null;
                 continue;
             }
             changed = true;
             // A number input only ever reports a valid number or an empty string.
-            settings[key] = value === "" ? null : definition.type === "number" ? Number(value) : value;
+            settings[key] =
+                value === "" || (configured && !configured.secret && String(value) === String(configured.value))
+                    ? null
+                    : definition.type === "number"
+                      ? Number(value)
+                      : value;
         }
         if (!changed) {
             onClose();
@@ -1383,14 +1434,22 @@ function SettingsModal({ plugin, onClose, onSaved }: { plugin: Plugin; onClose:
                         key={definition.key}
                         definition={definition}
                         value={values[definition.key]}
+                        configured={plugin.configured?.[definition.key]}
                         onChange={(value) => setValues((prev) => ({ ...prev, [definition.key]: value }))}
                     />
                 ))}
                 {/* Kept in view at the bottom of the dialog while a long list of settings scrolls. The dialog scrolls
                     inside its padding, so the bar reaches past it to the dialog's edges. */}
                 <div className="sticky -bottom-7 -mx-7 -mb-7 px-7 py-4 bg-surface border-t border-border flex flex-col gap-3">
-                    <p className="text-xs text-text-muted">Saving restarts the servers one at a time to apply the new settings.</p>
+                    <p className="text-xs text-text-muted">
+                        {resetting
+                            ? "Every setting is back to what this deployment's configuration or the plugin's default gives. Save to apply that."
+                            : "Saving restarts the servers one at a time to apply the new settings."}
+                    </p>
                     <div className="flex gap-2 justify-end">
+                        <Button type="button" variant="secondary" className="!w-auto mr-auto" onClick={reset} disabled={busy}>
+                            Reset
+                        </Button>
                         <Button type="button" variant="secondary" className="!w-auto" onClick={onClose}>
                             Cancel
                         </Button>
@@ -1407,13 +1466,28 @@ function SettingsModal({ plugin, onClose, onSaved }: { plugin: Plugin; onClose:
 function SettingField({
     definition,
     value,
+    configured,
     onChange,
 }: {
     definition: PluginSettingDefinition;
     value: PluginSettingValue | "";
+    configured?: PluginConfiguredSetting;
     onChange: (value: PluginSettingValue | "") => void;
 }) {
-    const help = definition.help && <span className="text-xs text-text-muted">{definition.help}</span>;
+    // What applies without a saved value; one saved here replaces it, and Reset goes back to it.
+    const note = configured && (
+        <span className="text-xs text-text-muted">
+            This deployment&apos;s configuration provides {configured.secret ? "a value" : "the value shown"} unless one is saved here.
+        </span>
+    );
+    // A secret's value never reaches the browser, so the field only says that it is set.
+    const placeholder: string | undefined = configured?.secret ? "Set by this deployment" : undefined;
+    const help = (
+        <>
+            {definition.help && <span className="text-xs text-text-muted">{definition.help}</span>}
+            {note}
+        </>
+    );
     if (definition.type === "boolean") {
         // Laid out like the admin policy forms' checkboxes: the help sits under the label, beside the box.
         return (
@@ -1445,7 +1519,8 @@ function SettingField({
                     type={definition.type === "number" ? "number" : "text"}
                     min={definition.min}
                     max={definition.max}
-                    required={definition.required}
+                    required={definition.required && !configured}
+                    placeholder={placeholder}
                     value={String(value)}
                     onChange={(e) => onChange(e.target.value)}
                 />

package/dist/apps/admin/diagnostics/index.d.ts

@@ -0,0 +1,3 @@
+import React from "react";
+import { AdminShellProps } from "../../shared/components/admin/layout/AdminShell.js";
+export default function DiagnosticsPage(props: Omit<AdminShellProps, "active">): React.JSX.Element;

package/dist/apps/admin/diagnostics/index.js

@@ -0,0 +1,6 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import AdminShell from "../../shared/components/admin/layout/AdminShell.js";
+import DiagnosticsManager from "../../shared/components/admin/diagnostics/DiagnosticsManager.js";
+export default function DiagnosticsPage(props) {
+    return (_jsx(AdminShell, { ...props, active: "diagnostics", children: _jsx(DiagnosticsManager, {}) }));
+}

package/dist/apps/shared/components/admin/diagnostics/Badge.d.ts

@@ -0,0 +1,10 @@
+import React, { ReactNode } from "react";
+import type { IconType } from "react-icons";
+export type BadgeTone = "success" | "warning" | "danger" | "info" | "neutral";
+export interface BadgeProps {
+    tone?: BadgeTone;
+    icon?: IconType;
+    children: ReactNode;
+}
+/** A small pill: an optional icon, then a word or two. */
+export default function Badge({ tone, icon: Icon, children }: BadgeProps): React.JSX.Element;

package/dist/apps/shared/components/admin/diagnostics/Badge.js

@@ -0,0 +1,15 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/** The tint behind a badge and the colour of its icon. The words stay in the normal text colour, and every tone
+ * that means something (good, warning, bad) is also worded, so a badge never relies on its colour alone. */
+const TONES = {
+    success: { background: "bg-success/15", icon: "text-success" },
+    warning: { background: "bg-warning/25", icon: "text-warning" },
+    danger: { background: "bg-danger/15", icon: "text-danger" },
+    info: { background: "bg-primary/15", icon: "text-primary" },
+    neutral: { background: "bg-surface-alt", icon: "text-text-muted" },
+};
+/** A small pill: an optional icon, then a word or two. */
+export default function Badge({ tone = "neutral", icon: Icon, children }) {
+    const classes = TONES[tone];
+    return (_jsxs("span", { className: `inline-flex items-center gap-1 rounded-pill border border-border px-2 py-0.5 text-xs font-medium text-text whitespace-nowrap ${classes.background}`, children: [Icon && _jsx(Icon, { size: 14, "aria-hidden": "true", className: classes.icon }), children] }));
+}