Declare plugin settings in the manifest, resolve them from the environment

examples/plugins/admin/admin-plugin-settings.test.ts

@@ -0,0 +1,55 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import type { PageChrome, PluginSettings } from "@plainpages/plugin-api";
+import { buildPluginSettingsModel } from "./admin-plugin-settings.ts";
+
+const CHROME: PageChrome = { brand: { name: "Test" }, csrfToken: "tok", nav: [], signInHref: "/login", user: { email: "", initials: "T", name: "Tester" } };
+
+const CATALOG: readonly PluginSettings[] = [
+  {
+    pluginId: "scheduling",
+    settings: [
+      { description: "Where shifts come from", envName: "PLUGIN_SETTING_SCHEDULING_UPSTREAM", key: "upstream", required: true, secret: false, source: "env", type: "url", value: "https://shifts.test" },
+      { envName: "PLUGIN_SETTING_SCHEDULING_MODE", key: "mode", required: false, secret: false, source: "default", type: "enum", value: "strict", values: ["strict", "lenient"] },
+      { envName: "PLUGIN_SETTING_SCHEDULING_NOTE", key: "note", required: false, secret: false, source: "unset", type: "string" },
+    ],
+  },
+  { pluginId: "quiet", settings: [] },
+];
+
+test("a row carries the variable to set and where the value came from", () => {
+  const model = buildPluginSettingsModel({ chrome: CHROME, settings: CATALOG });
+  const rows = model.groups[0]?.table.rows ?? [];
+  assert.deepEqual(rows.map((r) => r.name), ["upstream", "mode", "note"]);
+  assert.deepEqual(rows[0]?.cells, [
+    { rowHeader: { text: "upstream" } }, "Where shifts come from", "url", "Yes", "PLUGIN_SETTING_SCHEDULING_UPSTREAM", "Environment", "https://shifts.test",
+  ]);
+  assert.equal(rows[1]?.cells[2], "enum (strict, lenient)"); // the choices are the useful half of the type
+  assert.equal(rows[2]?.cells[5], "Not set");
+});
+
+test("a plugin declaring nothing still gets a section, so it is visibly installed", () => {
+  const model = buildPluginSettingsModel({ chrome: CHROME, settings: CATALOG });
+  assert.deepEqual(model.groups.map((g) => g.pluginId), ["scheduling", "quiet"]);
+  assert.deepEqual(model.groups[1]?.table.rows, []);
+  assert.match(model.groups[1]?.emptyText ?? "", /no settings/i);
+});
+
+test("a secret renders as set-or-not, never as a value, a mask or a length", () => {
+  const settings: readonly PluginSettings[] = [{
+    pluginId: "billing",
+    settings: [
+      { envName: "PLUGIN_SETTING_BILLING_API_KEY", key: "apiKey", required: false, secret: true, source: "env", type: "string" },
+      { envName: "PLUGIN_SETTING_BILLING_WEBHOOK_KEY", key: "webhookKey", required: false, secret: true, source: "unset", type: "string" },
+    ],
+  }];
+  const rows = buildPluginSettingsModel({ chrome: CHROME, settings }).groups[0]?.table.rows ?? [];
+  assert.equal(rows[0]?.cells[6], "Secret — set");
+  assert.equal(rows[1]?.cells[6], "Secret — not set");
+});
+
+test("two tables on one page need distinct row-action id stems", () => {
+  const model = buildPluginSettingsModel({ chrome: CHROME, settings: CATALOG });
+  const stems = model.groups.map((g) => g.table.actionsId);
+  assert.equal(new Set(stems).size, stems.length);
+});

examples/plugins/admin/admin-plugin-settings.ts

@@ -0,0 +1,75 @@
+// Plugin settings admin screen: what each installed plugin declares it can be configured with, the
+// variable that sets it, and how each key resolved. Read-only — the host reads settings from the
+// environment at boot, so changing one is a deploy, not a form.
+
+import { type PageChrome, type PluginSettings, type RouteHandler, type SettingSummary, type Translate } from "@plainpages/plugin-api";
+import { ADMIN_EN, requirePermission } from "./admin-shared.ts";
+
+interface SettingsGroup {
+  emptyText: string;
+  pluginId: string;
+  table: {
+    actionsId: string;
+    caption: string;
+    columns: { label: string }[];
+    rows: { cells: (string | { rowHeader: { text: string } })[]; name: string }[];
+  };
+}
+
+// One group per installed plugin, including those declaring nothing — an operator who cannot find
+// their plugin here has not installed it, which is the other half of what this screen answers.
+export function buildPluginSettingsModel(opts: { chrome: PageChrome; settings: readonly PluginSettings[]; t?: Translate }) {
+  const t = opts.t ?? ADMIN_EN;
+  return {
+    breadcrumbs: [{ label: t("admin.pluginSettings.title") }],
+    chrome: opts.chrome,
+    groups: opts.settings.map((plugin): SettingsGroup => ({
+      emptyText: t("admin.pluginSettings.none"),
+      pluginId: plugin.pluginId,
+      table: {
+        actionsId: `settings-${plugin.pluginId}`, // two tables share this page, so the stem must differ
+        caption: t("admin.pluginSettings.caption", { plugin: plugin.pluginId }),
+        columns: [
+          { label: t("admin.pluginSettings.column.key") },
+          { label: t("admin.pluginSettings.column.description") },
+          { label: t("admin.pluginSettings.column.type") },
+          { label: t("admin.pluginSettings.column.required") },
+          { label: t("admin.pluginSettings.column.variable") },
+          { label: t("admin.pluginSettings.column.source") },
+          { label: t("admin.pluginSettings.column.value") },
+        ],
+        rows: plugin.settings.map((setting) => ({
+          cells: [
+            { rowHeader: { text: setting.key } },
+            setting.description ?? "",
+            typeLabel(setting),
+            t(setting.required ? "admin.pluginSettings.yes" : "admin.pluginSettings.no"),
+            setting.envName,
+            t(`admin.pluginSettings.source.${setting.source}`),
+            valueLabel(setting, t),
+          ],
+          name: setting.key,
+        })),
+      },
+    })),
+    title: t("admin.pluginSettings.title"),
+  };
+}
+
+// An enum's choices are the useful half of its type — they are what the operator must pick from.
+function typeLabel(setting: SettingSummary): string {
+  return setting.type === "enum" && setting.values ? `${setting.type} (${setting.values.join(", ")})` : setting.type;
+}
+
+// A secret never renders its value — not the value, not a mask of it, not its length. Whether it
+// resolved and from where is what an operator needs, and the source column already says the rest.
+function valueLabel(setting: SettingSummary, t: Translate): string {
+  if (setting.secret) return t(setting.source === "unset" ? "admin.pluginSettings.secretUnset" : "admin.pluginSettings.secretSet");
+  return setting.value ?? t("admin.pluginSettings.unset");
+}
+
+// GET /admin/plugin-settings
+export const pluginSettingsList: RouteHandler = (ctx) => {
+  requirePermission(ctx, "plugin-settings");
+  return { data: { chrome: ctx.chrome, model: buildPluginSettingsModel({ chrome: ctx.chrome, settings: ctx.declaredSettings, t: ctx.t }) }, view: "plugin-settings" };
+};

examples/plugins/admin/admin-shared.test.ts

@@ -19,7 +19,7 @@ function fakeCtx(opts: { body?: string; method?: string; user?: User | null; ver
   const req = Readable.from(opts.body != null ? [Buffer.from(opts.body)] : []) as unknown as IncomingMessage;
   req.method = opts.method ?? "GET";
   return {
-    chrome: CHROME, declaredPermissions: [], user: opts.user ?? null, locale: "en-US", localeHref: (href) => href, locales: ["en-US"], log: {} as Log, params: {},
+    chrome: CHROME, declaredPermissions: [], declaredSettings: [], user: opts.user ?? null, locale: "en-US", localeHref: (href) => href, locales: ["en-US"], log: {} as Log, params: {},
     query: url.searchParams, req, res: {} as ServerResponse, permissions: opts.user?.permissions ?? [], t: ADMIN_EN, url,
     verifyCsrf: opts.verifyCsrf ?? (() => true),
   };
@@ -27,21 +27,21 @@ function fakeCtx(opts: { body?: string; method?: string; user?: User | null; ver
 
 // ---- nav fragment ----
 
-test("ADMIN_NAV: an ungated Admin header whose three screens each gate on their own read permission", () => {
+test("ADMIN_NAV: an ungated Admin header whose screens each gate on their own read permission", () => {
   assert.equal(ADMIN_NAV.id, "admin");
   // No gate on the header: a user may hold one screen's permission and not another's. composeNav
-  // drops a header left with no visible children, so holding none of the three hides the section.
+  // drops a header left with no visible children, so holding none of them hides the section.
   // Both halves matter — give the header an `href` and it survives the filter as a visible leaf,
   // ungated, for anonymous visitors included.
   assert.equal(ADMIN_NAV.permission, undefined);
   assert.equal(ADMIN_NAV.href, undefined);
   assert.equal(ADMIN_NAV.open, undefined); // the host current-marks + opens; the fragment stays static
-  assert.deepEqual(ADMIN_NAV.children?.map((c) => c.href), ["/admin/users", "/admin/groups", "/admin/clients"]);
-  assert.deepEqual(ADMIN_NAV.children?.map((c) => c.permission), ["users:read", "groups:read", "oauth2-clients:read"]);
+  assert.deepEqual(ADMIN_NAV.children?.map((c) => c.href), ["/admin/users", "/admin/groups", "/admin/clients", "/admin/plugin-settings"]);
+  assert.deepEqual(ADMIN_NAV.children?.map((c) => c.permission), ["users:read", "groups:read", "oauth2-clients:read", "plugin-settings:read"]);
   // Labels are catalog keys; the host translates them with this plugin's catalog when it composes
   // the menu, so what a visitor sees is the en-US (or sv-SE …) wording behind these keys.
-  assert.deepEqual(ADMIN_NAV.children?.map((c) => c.label), ["admin.nav.users", "admin.nav.groups", "admin.nav.clients"]);
-  assert.deepEqual(ADMIN_NAV.children?.map((c) => ADMIN_EN(c.label)), ["Users", "Groups", "OAuth2 clients"]);
+  assert.deepEqual(ADMIN_NAV.children?.map((c) => c.label), ["admin.nav.users", "admin.nav.groups", "admin.nav.clients", "admin.nav.pluginSettings"]);
+  assert.deepEqual(ADMIN_NAV.children?.map((c) => ADMIN_EN(c.label)), ["Users", "Groups", "OAuth2 clients", "Plugin settings"]);
   assert.ok(ADMIN_NAV.children?.every((c) => c.current === undefined));
 });
 

examples/plugins/admin/admin-shared.ts

@@ -12,12 +12,13 @@ export const ADMIN_EN: Translate = englishTranslator(enUS);
 export const ADMIN_USERS_BASE = "/admin/users";
 export const ADMIN_GROUPS_BASE = "/admin/groups";
 export const ADMIN_CLIENTS_BASE = "/admin/clients";
+export const ADMIN_PLUGIN_SETTINGS_BASE = "/admin/plugin-settings";
 
 // One resource per screen — the `<resource>` half of every permission this plugin gates on.
 // `oauth2-clients` rather than `clients` because permission names are one global namespace.
 // There is no `permissions` resource: permissions are declared in plugin code, not created here, so
 // holding a grant is a property of a user or a group and is edited on those two screens.
-export type AdminResource = "groups" | "oauth2-clients" | "users";
+export type AdminResource = "groups" | "oauth2-clients" | "plugin-settings" | "users";
 
 export type AdminAction = "read" | "write";
 
@@ -43,6 +44,7 @@ export const ADMIN_NAV: NavNode = {
     { href: ADMIN_USERS_BASE, icon: "i-users", id: "users", label: "admin.nav.users", permission: permissionName("users", "read") },
     { href: ADMIN_GROUPS_BASE, icon: "i-layers", id: "groups", label: "admin.nav.groups", permission: permissionName("groups", "read") },
     { href: ADMIN_CLIENTS_BASE, icon: "i-globe", id: "clients", label: "admin.nav.clients", permission: permissionName("oauth2-clients", "read") },
+    { href: ADMIN_PLUGIN_SETTINGS_BASE, icon: "i-sliders", id: "plugin-settings", label: "admin.nav.pluginSettings", permission: permissionName("plugin-settings", "read") },
   ],
   icon: "i-shield",
   id: "admin",

examples/plugins/admin/i18n/en-US.ts

@@ -83,9 +83,29 @@ const messages = {
 
   "admin.nav.clients": "OAuth2 clients",
   "admin.nav.groups": "Groups",
+  "admin.nav.pluginSettings": "Plugin settings",
   "admin.nav.section": "Admin",
   "admin.nav.users": "Users",
 
+  "admin.pluginSettings.caption": "Settings declared by {{plugin}}",
+  "admin.pluginSettings.column.description": "Description",
+  "admin.pluginSettings.column.key": "Key",
+  "admin.pluginSettings.column.required": "Required",
+  "admin.pluginSettings.column.source": "Source",
+  "admin.pluginSettings.column.type": "Type",
+  "admin.pluginSettings.column.value": "Value",
+  "admin.pluginSettings.column.variable": "Variable",
+  "admin.pluginSettings.no": "No",
+  "admin.pluginSettings.none": "This plugin declares no settings.",
+  "admin.pluginSettings.secretSet": "Secret — set",
+  "admin.pluginSettings.secretUnset": "Secret — not set",
+  "admin.pluginSettings.source.default": "Default",
+  "admin.pluginSettings.source.env": "Environment",
+  "admin.pluginSettings.source.unset": "Not set",
+  "admin.pluginSettings.title": "Plugin settings",
+  "admin.pluginSettings.unset": "—",
+  "admin.pluginSettings.yes": "Yes",
+
   "admin.notFound.message": "That item doesn't exist.",
   "admin.notFound.title": "Not found",
 

examples/plugins/admin/i18n/sv-SE.ts

@@ -83,9 +83,29 @@ const messages: AdminMessages = {
 
   "admin.nav.clients": "OAuth2-klienter",
   "admin.nav.groups": "Grupper",
+  "admin.nav.pluginSettings": "Tilläggsinställningar",
   "admin.nav.section": "Administration",
   "admin.nav.users": "Användare",
 
+  "admin.pluginSettings.caption": "Inställningar som {{plugin}} deklarerar",
+  "admin.pluginSettings.column.description": "Beskrivning",
+  "admin.pluginSettings.column.key": "Nyckel",
+  "admin.pluginSettings.column.required": "Obligatorisk",
+  "admin.pluginSettings.column.source": "Källa",
+  "admin.pluginSettings.column.type": "Typ",
+  "admin.pluginSettings.column.value": "Värde",
+  "admin.pluginSettings.column.variable": "Variabel",
+  "admin.pluginSettings.no": "Nej",
+  "admin.pluginSettings.none": "Det här tillägget deklarerar inga inställningar.",
+  "admin.pluginSettings.secretSet": "Hemlighet — satt",
+  "admin.pluginSettings.secretUnset": "Hemlighet — inte satt",
+  "admin.pluginSettings.source.default": "Standardvärde",
+  "admin.pluginSettings.source.env": "Miljövariabel",
+  "admin.pluginSettings.source.unset": "Inte satt",
+  "admin.pluginSettings.title": "Tilläggsinställningar",
+  "admin.pluginSettings.unset": "—",
+  "admin.pluginSettings.yes": "Ja",
+
   "admin.notFound.message": "Objektet finns inte.",
   "admin.notFound.title": "Hittades inte",
 

examples/plugins/admin/plugin.test.ts

@@ -35,17 +35,20 @@ test("every nav permission is one the manifest declares", () => {
     }
   };
   walk(manifest.nav);
-  assert.equal(navPermissions.length, 3);
+  assert.equal(navPermissions.length, 4);
   for (const name of navPermissions) assert.ok(declared.includes(name), `nav gates on undeclared ${name}`);
 });
 
 test("every declared permission is <resource>:<action>, and reads and writes are split per resource", () => {
   for (const name of declared) assert.ok(isValidPermissionName(name), name); // the host's rule, not a copy of it
-  // Three screens × read/write. There is deliberately no `permissions:` pair: permissions are
-  // declared in plugin code, so holding one is edited on the user or group that holds it.
+  // Three CRUD screens × read/write, plus read-only plugin settings — a screen that never writes
+  // declares no `:write`, since a permission nothing gates on is one an operator can only mis-grant.
+  // There is deliberately no `permissions:` pair either: permissions are declared in plugin code, so
+  // holding one is edited on the user or group that holds it.
   assert.deepEqual([...declared].sort(), [
     "groups:read", "groups:write",
     "oauth2-clients:read", "oauth2-clients:write",
+    "plugin-settings:read",
     "users:read", "users:write",
   ]);
 });
@@ -58,5 +61,5 @@ test("GET routes gate on read and mutations on write, so a reader can open a scr
     const action = route.method === "GET" && !writeIntent(route.path) ? "read" : "write";
     assert.ok(route.permission?.endsWith(`:${action}`), `${route.method} ${route.path} → ${route.permission}`);
   }
-  assert.equal(routes.filter((r) => r.method === "GET" && writeIntent(r.path)).length, 6); // 2 per screen
+  assert.equal(routes.filter((r) => r.method === "GET" && writeIntent(r.path)).length, 6); // 2 per CRUD screen; plugin settings has none
 });

examples/plugins/admin/plugin.ts

@@ -7,6 +7,7 @@
 import { definePlugin, type HttpMethod, type Route, type RouteHandler } from "@plainpages/plugin-api";
 import { clientsCreate, clientsDeleteConfirm, clientsDelete, clientsDetail, clientsList, clientsNewForm } from "./admin-clients.ts";
 import { groupsAddMember, groupsCreate, groupsDelete, groupsDeleteConfirm, groupsDetail, groupsList, groupsNewForm, groupsPermissions, groupsRemoveMember } from "./admin-groups.ts";
+import { pluginSettingsList } from "./admin-plugin-settings.ts";
 import { usersCreate, usersDeleteConfirm, usersDelete, usersEditForm, usersList, usersNewForm, usersPermissions, usersRecovery, usersState, usersUpdate } from "./admin-users.ts";
 import { ADMIN_NAV, actionForMethod, type AdminAction, type AdminResource, permissionName } from "./admin-shared.ts";
 
@@ -24,9 +25,10 @@ const on = (resource: AdminResource) => (method: HttpMethod, path: string, handl
 const users = on("users");
 const groups = on("groups");
 const clients = on("oauth2-clients");
+const pluginSettings = on("plugin-settings");
 
 export default definePlugin({
-  apiVersion: "0.1.0", // the host contract this was built against — a literal, never HOST_API_VERSION
+  apiVersion: "0.2.0", // the host contract this was built against — a literal, never HOST_API_VERSION
 
   nav: [ADMIN_NAV],
 
@@ -37,6 +39,7 @@ export default definePlugin({
     { description: "Create and delete groups, and change their members and permissions", name: "groups:write" },
     { description: "View OAuth2 clients", name: "oauth2-clients:read" },
     { description: "Register and delete OAuth2 clients", name: "oauth2-clients:write" },
+    { description: "View the settings each installed plugin declares, and how they resolved", name: "plugin-settings:read" },
   ],
 
   routes: [
@@ -68,5 +71,7 @@ export default definePlugin({
     clients("GET", "/clients/:id", clientsDetail),
     clients("GET", "/clients/:id/delete", clientsDeleteConfirm, "write"),
     clients("POST", "/clients/:id/delete", clientsDelete),
+    // Plugin settings — read-only, so no :write route and no write-intent GET.
+    pluginSettings("GET", "/plugin-settings", pluginSettingsList),
   ],
 });

examples/plugins/admin/views/plugin-settings.ejs

@@ -0,0 +1,24 @@
+<%#
+  Plugin settings admin list: one section per installed plugin, each a table of what it declares
+  and how each key resolved (admin-plugin-settings.ts). Read-only — no actions, no forms.
+%><%
+  const nav = include("partials/nav-tree", { nodes: chrome.nav });
+  let body = "";
+  for (const group of model.groups) {
+    // A plugin id is the folder name, which discovery constrains to [a-z0-9-] — no escaping needed.
+    body += '<h2 class="h2">' + group.pluginId + "</h2>";
+    body += group.table.rows.length === 0
+      ? '<p class="muted">' + group.emptyText + "</p>"
+      : include("partials/data-table", group.table);
+  }
+-%>
+<%- include("partials/shell", {
+  body,
+  brand: chrome.brand,
+  breadcrumbs: model.breadcrumbs,
+  csrfToken: chrome.csrfToken,
+  nav,
+  theme: chrome.theme,
+  title: model.title,
+  user: chrome.user,
+}) %>