domma-cms 0.75.0 → 0.76.0

package/server/routes/api/notifications.js

@@ -3,7 +3,11 @@
  * POST   /api/system/notifications              - Manager push (requireManager)
  * GET    /api/system/notifications              - List active notifications (admin/manager)
  * GET    /api/system/notifications/unread-count - Unread count for bell badge
+ * GET    /api/system/notifications/_count       - The sidebar badge (unread, with a popover)
  * POST   /api/system/notifications/:id/read     - Mark read (idempotent)
+ * POST   /api/system/notifications/:id/unread   - Mark unread again (idempotent)
+ * POST   /api/system/notifications/dismiss-all  - Dismiss every active one, for this user
+ * POST   /api/system/notifications/read-all     - Mark every active one read, for this user
  * POST   /api/system/notifications/:id/dismiss  - Mark dismissed
  * DELETE /api/system/notifications/:id          - Hard delete (admin only)
  */
@@ -12,6 +16,7 @@ import {
     requirePermission as defaultRequirePermission
 } from '../../middleware/auth.js';
 import { requireManager } from '../../middleware/managerAuth.js';
+import { randomUUID } from 'crypto';
 import { getAdapter } from '../../services/adapterRegistry.js';
 
 const SLUG = 'notifications';
@@ -45,6 +50,18 @@ function notificationData(entry, log) {
     return null;
 }
 
+/**
+ * Write a notification's payload back as a whole entry - `{id, data, meta}`.
+ *
+ * The adapter's update() REPLACES the stored entry with what it is given, and
+ * until 0.76.0 these routes gave it the bare payload: marking a notification
+ * read turned it into a flat record with no id and no `data`, which the list
+ * then skipped as malformed - read once, gone for good.
+ */
+async function saveData(adapter, entry, data) {
+    return adapter.update(SLUG, entry.id, {...entry, data, meta: {...(entry.meta || {}), updatedAt: new Date().toISOString()}});
+}
+
 /**
  * Is this notification live for this user right now: not expired, not dismissed.
  *
@@ -58,6 +75,43 @@ function isActiveFor(data, userId, now) {
     return !(Array.isArray(data.dismissedBy) && data.dismissedBy.includes(userId));
 }
 
+/**
+ * The sidebar badge on Notifications (its countUrl): the unread ones - the same
+ * number the sidebar always showed there - red while any of them is critical.
+ * Plain text throughout: the popover sets it with textContent.
+ *
+ * @param {object[]} active - this user's active entries, each with `unread`
+ * @returns {{count: number, label: string, tone: string, details: object}}
+ */
+export function notificationsBadge(active = []) {
+    const unread = active.filter(e => e.unread)
+        .sort((a, b) => String(b.data.createdAt || '').localeCompare(String(a.data.createdAt || '')));
+    const sev = (e) => e.data?.severity || 'info';
+    const critical = unread.filter(e => sev(e) === 'critical').length;
+    const warning = unread.filter(e => sev(e) === 'warning').length;
+    const n = unread.length;
+    return {
+        count: n,
+        label: n ? `${n} unread notification${n === 1 ? '' : 's'}${critical ? `, ${critical} critical` : ''}` : 'No unread notifications',
+        tone: critical ? 'danger' : 'info',
+        details: {
+            title: 'Notifications',
+            rows: [
+                {label: 'Unread', value: String(n)},
+                {label: 'Critical', value: String(critical), ...(critical && {tone: 'danger'})},
+                {label: 'Warnings', value: String(warning)},
+                {label: 'In the inbox', value: String(active.length)}
+            ],
+            items: unread.slice(0, 6).map(e => ({
+                text: String(e.data.title || '(no title)').slice(0, 80),
+                meta: [sev(e), String(e.data.createdAt || '').slice(0, 10)].filter(Boolean).join(' · '),
+                ...(sev(e) === 'critical' && {tone: 'danger'})
+            })),
+            empty: 'Nothing unread.'
+        }
+    };
+}
+
 export async function notificationsRoutes(fastify, opts = {}) {
     // Injectable so tests can supply no-ops rather than a seeded roles cache -
     // the same DI pattern as menus.js, projects.js and context-menus.js.
@@ -94,17 +148,25 @@ export async function notificationsRoutes(fastify, opts = {}) {
             }
         }
 
+        // A whole entry, {id, data, meta}: the adapter stores what it is given, and
+        // before 0.76.0 this handed it the bare payload - no id, no `data` - so the
+        // list skipped every pushed notification as malformed and none ever showed.
         const adapter = await getAdapter(SLUG);
+        const now = new Date().toISOString();
         const entry = await adapter.insert(SLUG, {
-            title: title.trim(),
-            body: body.trim(),
-            severity,
-            source: 'manager',
-            link: link || null,
-            createdAt: new Date().toISOString(),
-            expiresAt: expiresAt || null,
-            readBy: [],
-            dismissedBy: []
+            id: randomUUID(),
+            data: {
+                title: title.trim(),
+                body: body.trim(),
+                severity,
+                source: 'manager',
+                link: link || null,
+                createdAt: now,
+                expiresAt: expiresAt || null,
+                readBy: [],
+                dismissedBy: []
+            },
+            meta: {createdAt: now, updatedAt: now, source: 'manager'}
         });
 
         return reply.code(201).send(entry);
@@ -147,6 +209,73 @@ export async function notificationsRoutes(fastify, opts = {}) {
         return { count };
     });
 
+    /** This user's active notifications, newest first, each flagged `unread`. */
+    async function activeFor(userId) {
+        const now = new Date().toISOString();
+        const adapter = await getAdapter(SLUG);
+        return (await adapter.all(SLUG))
+            .filter(entry => {
+                const d = notificationData(entry, fastify.log);
+                return !!d && isActiveFor(d, userId, now);
+            })
+            .map(entry => ({...entry, unread: !Array.isArray(entry.data.readBy) || !entry.data.readBy.includes(userId)}));
+    }
+
+    // --- Sidebar badge (static path: GET has no /:id route to shadow) ---
+    fastify.get('/system/notifications/_count', canRead, async (request) => notificationsBadge(await activeFor(request.user.id)));
+
+    // --- Dismiss everything active, for this user ---
+    fastify.post('/system/notifications/dismiss-all', canRead, async (request) => {
+        const userId = request.user.id;
+        const adapter = await getAdapter(SLUG);
+        let dismissed = 0;
+        for (const entry of await activeFor(userId)) {
+            const {unread: _u, ...stored} = entry;
+            const data = stored.data;
+            const dismissedBy = Array.isArray(data.dismissedBy) ? data.dismissedBy : [];
+            const readBy = Array.isArray(data.readBy) ? data.readBy : [];
+            await saveData(adapter, stored, {
+                ...data,
+                dismissedBy: [...dismissedBy, userId],
+                readBy: readBy.includes(userId) ? readBy : [...readBy, userId]
+            });
+            dismissed++;
+        }
+        return {ok: true, dismissed};
+    });
+
+    // --- Mark everything active read, for this user ---
+    // One request, one pass: the screen used to fire a mark-read per notification
+    // at once, and on file storage each read-modify-write overwrote the others -
+    // six marked, one stuck.
+    fastify.post('/system/notifications/read-all', canRead, async (request) => {
+        const userId = request.user.id;
+        const adapter = await getAdapter(SLUG);
+        let marked = 0;
+        for (const entry of await activeFor(userId)) {
+            if (!entry.unread) continue;
+            const {unread: _u, ...stored} = entry;
+            const readBy = Array.isArray(stored.data.readBy) ? stored.data.readBy : [];
+            await saveData(adapter, stored, {...stored.data, readBy: [...readBy, userId]});
+            marked++;
+        }
+        return {ok: true, marked};
+    });
+
+    // --- Mark unread again (idempotent) ---
+    fastify.post('/system/notifications/:id/unread', canRead, async (request, reply) => {
+        const { id } = request.params;
+        const userId = request.user.id;
+        const adapter = await getAdapter(SLUG);
+        const entry = await adapter.get(SLUG, id);
+        const data = notificationData(entry, fastify.log);
+        if (!data) return reply.code(404).send({ error: 'Notification not found.' });
+        const readBy = Array.isArray(data.readBy) ? data.readBy : [];
+        if (!readBy.includes(userId)) return { ok: true };
+        const updated = await saveData(adapter, entry, {...data, readBy: readBy.filter(u => u !== userId)});
+        return { ok: true, entry: updated };
+    });
+
     // --- Mark read (idempotent) ---
     fastify.post('/system/notifications/:id/read', canRead, async (request, reply) => {
         const { id } = request.params;
@@ -161,10 +290,7 @@ export async function notificationsRoutes(fastify, opts = {}) {
         const readBy = Array.isArray(data.readBy) ? data.readBy : [];
         if (readBy.includes(userId)) return { ok: true }; // already read - idempotent
 
-        const updated = await adapter.update(SLUG, id, {
-            ...data,
-            readBy: [...readBy, userId]
-        });
+        const updated = await saveData(adapter, entry, {...data, readBy: [...readBy, userId]});
 
         return { ok: true, entry: updated };
     });
@@ -182,7 +308,7 @@ export async function notificationsRoutes(fastify, opts = {}) {
         const dismissedBy = Array.isArray(data.dismissedBy) ? data.dismissedBy : [];
         const readBy = Array.isArray(data.readBy) ? data.readBy : [];
 
-        const updated = await adapter.update(SLUG, id, {
+        const updated = await saveData(adapter, entry, {
             ...data,
             dismissedBy: dismissedBy.includes(userId) ? dismissedBy : [...dismissedBy, userId],
             readBy: readBy.includes(userId) ? readBy : [...readBy, userId] // dismissing also marks read

package/server/routes/api/plugins.js

@@ -1,6 +1,7 @@
 /**
  * Plugins API
  * GET  /api/plugins              - list all discovered plugins + state (admin only)
+ * GET  /api/plugins/_count       - the sidebar badge (`_` is outside the slug alphabet)
  * POST /api/plugins/scaffold     - create a new plugin from plugins/_template (admin only)
  * PUT  /api/plugins/:name        - enable/disable, update settings (admin only)
  * GET  /api/plugins/admin-config - sidebar/routes/views for enabled plugins (authenticated)
@@ -14,6 +15,7 @@ import {
     getAdminPluginConfig,
     getEntitlementStates,
     getLoadedPlugins,
+    getPluginSettings,
     getPluginStates,
     isCorePlugin,
     pluginLicence,
@@ -26,7 +28,8 @@ import {deletePluginFile, listPluginFiles, readPluginFile, writePluginFile} from
 import {getConfig} from '../../config.js';
 import path from 'path';
 import {existsSync, readFileSync} from 'node:fs';
-import {installPlugin} from '../../services/pluginInstaller.js';
+import {compareVersions, installPlugin} from '../../services/pluginInstaller.js';
+import {fetchCatalogue, isManaged} from '../../services/managerClient.js';
 import {packEnvelope, readEnvelope, readManifestFromTarball, tarDirectory} from '../../services/pluginEnvelope.js';
 
 /**
@@ -95,6 +98,111 @@ function autoRestartEnabled() {
     }
 }
 
+/** Entitlement states that stop a plugin running (the loader refuses them). */
+const BLOCKING = new Set(['expired', 'unlicensed']);
+
+/**
+ * The sidebar badge on Plugins (its countUrl, GET /api/plugins/_count). The
+ * number stays what the sidebar always showed there - how many are installed -
+ * and the tone and popover say what needs doing: red while a licensed plugin
+ * that is switched on is not running, amber for an update or a licence in its
+ * grace period. Plain text throughout; the popover sets it with textContent.
+ *
+ * @param {{name, displayName, version, enabled, core, entitlement}[]} plugins
+ * @param {Map<string, string>} [latest] - slug -> newest catalogue version (managed sites only)
+ * @returns {{count, label, tone, details}}
+ */
+export function pluginsBadge(plugins = [], latest = new Map()) {
+    const name = (p) => String(p.displayName || p.name);
+    const stopped = plugins.filter(p => p.enabled && BLOCKING.has(p.entitlement));
+    const grace = plugins.filter(p => p.entitlement === 'grace');
+    const updates = plugins.filter(p => latest.has(p.name) && compareVersions(latest.get(p.name), p.version) > 0);
+    const on = plugins.filter(p => p.enabled || p.core).length;
+    const n = plugins.length;
+    const extra = [
+        stopped.length && `${stopped.length} not running`,
+        updates.length && `${updates.length} update${updates.length === 1 ? '' : 's'}`
+    ].filter(Boolean).join(', ');
+    return {
+        count: n,
+        label: `${n} plugin${n === 1 ? '' : 's'} installed${extra ? `, ${extra}` : ''}`,
+        tone: stopped.length ? 'danger' : (updates.length || grace.length) ? 'attention' : 'info',
+        details: {
+            title: 'Plugins',
+            rows: [
+                {label: 'Switched on', value: String(on)},
+                {label: 'Switched off', value: String(n - on)},
+                ...(latest.size ? [{label: 'Updates available', value: String(updates.length)}] : []),
+                ...(stopped.length ? [{label: 'Not running (licence)', value: String(stopped.length), tone: 'danger'}] : [])
+            ],
+            items: [
+                ...stopped.map(p => ({text: name(p), meta: `not running - licence ${p.entitlement}`, tone: 'danger'})),
+                ...grace.map(p => ({text: name(p), meta: 'licence ended - running in its grace period, renew'})),
+                ...updates.map(p => ({text: name(p), meta: `update ${p.version} → ${latest.get(p.name)}`}))
+            ].slice(0, 8),
+            empty: 'Everything is running and up to date.'
+        }
+    };
+}
+
+/**
+ * The newest catalogue version of each plugin, for a managed site - kept ten
+ * minutes: the badge is asked for every minute from every admin tab, and each
+ * ask would otherwise be a round trip to the manager.
+ */
+let _latest = {at: 0, value: new Map()};
+async function latestVersions() {
+    if (!isManaged()) return new Map();
+    if (Date.now() - _latest.at < 10 * 60_000) return _latest.value;
+    const catalogue = await fetchCatalogue().catch(() => []);
+    _latest = {at: Date.now(), value: new Map((catalogue || []).map(e => [e.slug, e.version]))};
+    return _latest.value;
+}
+
+/**
+ * Plugin settings reach the admin browser (the Marketplace's Configure form), so
+ * a value whose key looks secret - a DVLA key, an SMTP password, a connection
+ * URI - is sent as SETTING_MASK instead. Saving sends the mask back for any
+ * secret left untouched, and restoreMasked() puts the stored value back; a
+ * mask with nothing stored behind it (a config.js default) is dropped, so the
+ * default still applies. Same rule as isSecretKey() in admin/js/lib/plugins-arrange.js.
+ */
+export const SETTING_MASK = '\u2022\u2022\u2022\u2022\u2022\u2022\u2022\u2022';
+const SECRET_KEY = /pass(word)?|secret|token|api[-_]?key|private|credential|uri$|dsn/i;
+
+/** @param {Set<string>} [secretKeys] - keys a plugin's settingsSchema marks `secret: true` */
+export function maskSettings(value, key = '', secretKeys = new Set()) {
+    // An array's strings are secret when its key is (apiKeys: ['a', 'b']).
+    if (Array.isArray(value)) return value.map(v => maskSettings(v, key, secretKeys));
+    if (value && typeof value === 'object') {
+        return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, maskSettings(v, k, secretKeys)]));
+    }
+    const secret = SECRET_KEY.test(key) || secretKeys.has(key);
+    return secret && typeof value === 'string' && value !== '' ? SETTING_MASK : value;
+}
+
+const schemaSecrets = (manifest) => new Set((Array.isArray(manifest.settingsSchema) ? manifest.settingsSchema : [])
+    .filter(f => f && f.secret === true && typeof f.key === 'string').map(f => f.key));
+
+export function restoreMasked(incoming, stored) {
+    // Arrays by position: maskSettings masks inside them too ({accounts: [{password}]}),
+    // and returning the array as sent stored the mask over the real value.
+    if (Array.isArray(incoming)) {
+        const before = Array.isArray(stored) ? stored : [];
+        return incoming.map((v, i) => (v === SETTING_MASK ? (before[i] ?? '') : restoreMasked(v, before[i])));
+    }
+    if (incoming && typeof incoming === 'object') {
+        const out = {};
+        for (const [k, v] of Object.entries(incoming)) {
+            const before = stored && typeof stored === 'object' ? stored[k] : undefined;
+            if (v === SETTING_MASK) { if (before !== undefined) out[k] = before; continue; }
+            out[k] = restoreMasked(v, before);
+        }
+        return out;
+    }
+    return incoming;
+}
+
 export async function pluginsRoutes(fastify, opts = {}) {
     const authenticate      = opts.authenticate      || defaultAuthenticate;
     const requirePermission = opts.requirePermission || defaultRequirePermission;
@@ -114,7 +222,7 @@ export async function pluginsRoutes(fastify, opts = {}) {
         const loadedPlugins = getLoadedPlugins();
         const entitlementStates = getEntitlementStates();
 
-        return manifests.map(manifest => ({
+        return Promise.all(manifests.map(async manifest => ({
             name: manifest.name,
             displayName: manifest.displayName || manifest.name,
             version: manifest.version || '1.0.0',
@@ -143,8 +251,30 @@ export async function pluginsRoutes(fastify, opts = {}) {
             // Enabled but displaced by another plugin that replaces it. Shown
             // so the screen can explain the inactivity instead of looking broken.
             supersededBy: loadedPlugins[manifest.name]?.supersededBy ?? null,
-            settings: states[manifest.name]?.settings || {}
+            settings: maskSettings(states[manifest.name]?.settings || {}, '', schemaSecrets(manifest)),
+            // What Configure edits: an optional plugin.json `settingsSchema`
+            // ([{key, label, type: text|number|select|boolean, options, min,
+            // max, help}]), else the plugin's config.js defaults merged with the
+            // stored overrides (`effectiveSettings`) - so every plugin with a
+            // config.js can be configured, not only one that declared a schema
+            // (none ever had, so the old Settings button never appeared).
+            settingsSchema: Array.isArray(manifest.settingsSchema) ? manifest.settingsSchema : null,
+            effectiveSettings: maskSettings(await getPluginSettings(manifest.name).catch(() => ({})), '', schemaSecrets(manifest))
+        })));
+    });
+
+    // The sidebar badge. Registered with the other static /plugins/* routes;
+    // `_` is outside the plugin slug alphabet, so no plugin can shadow it.
+    fastify.get('/plugins/_count', canRead, async () => {
+        const manifests = await discoverPlugins();
+        const states = getPluginStates();
+        const ent = getEntitlementStates();
+        const plugins = manifests.map(m => ({
+            name: m.name, displayName: m.displayName || m.name, version: m.version || '1.0.0',
+            core: isCorePlugin(m.name), enabled: isCorePlugin(m.name) || !!states[m.name]?.enabled,
+            entitlement: ent[m.name] ?? null
         }));
+        return pluginsBadge(plugins, await latestVersions());
     });
 
     // Scaffold a new plugin from plugins/_template. The plugin is created
@@ -183,7 +313,8 @@ export async function pluginsRoutes(fastify, opts = {}) {
         const prevState = getPluginStates()[name] || {};
         const update = {};
         if (enabled !== undefined) update.enabled = !!enabled;
-        if (settings !== undefined) update.settings = settings;
+        // A secret sent back as the mask keeps its stored value (see maskSettings).
+        if (settings !== undefined) update.settings = restoreMasked(settings, prevState.settings || {});
         savePluginState(name, update);
 
         if (!prevState.enabled && !!enabled) {

package/server/routes/api/roles.js

@@ -0,0 +1,111 @@
+/**
+ * Roles - the screen's own routes. Role records themselves are the preset
+ * `roles` collection and are read and written through the collections API
+ * (`/api/collections/roles/entries`, with keepRoleSystemFields); these add
+ * what that API cannot say.
+ *
+ * GET /api/roles/_holders  - who holds each role: {counts: {name: n}, orphans: [...]}
+ * GET /api/roles/_count    - the sidebar badge on Roles
+ *
+ * The underscore keeps both clear of any role name (role names are slugs).
+ * Guarded like the list they sit beside: `collections` read.
+ */
+import {
+    authenticate as defaultAuthenticate,
+    requirePermission as defaultRequirePermission
+} from '../../middleware/auth.js';
+import {listEntries} from '../../services/collections.js';
+import {listUsers} from '../../services/users.js';
+
+const plural = (n, one, many = `${one}s`) => `${n} ${n === 1 ? one : many}`;
+
+/**
+ * How many users hold each role - primary or additional - and which users
+ * hold a role that no longer exists (they fall back to the least-privileged
+ * role until an admin fixes them).
+ *
+ * @param {object[]} users
+ * @param {string[]} roleNames - the roles that exist
+ * @returns {{counts: Record<string, number>, orphans: {role: string}[]}} - one orphan per user-role pair
+ */
+export function roleHolders(users = [], roleNames = []) {
+    const known = new Set(roleNames);
+    const counts = Object.fromEntries(roleNames.map(n => [n, 0]));
+    const orphans = [];
+    for (const u of users) {
+        const held = [...new Set([u.role, ...(Array.isArray(u.additionalRoles) ? u.additionalRoles : [])].filter(Boolean))];
+        for (const r of held) {
+            if (known.has(r)) counts[r]++;
+            // The role only - who they are is Users' business (users.read), not
+            // something to hand to anyone who can read the roles list.
+            else orphans.push({role: r});
+        }
+    }
+    return {counts, orphans};
+}
+
+/**
+ * The badge: how many roles (an inventory - the number never alarms), red
+ * while any user holds a role that no longer exists. Plain text throughout;
+ * the sidebar popover sets it with textContent.
+ *
+ * @param {{name: string, label?: string, level: number, plugin?: string}[]} roles
+ * @param {{counts: Record<string, number>, orphans: {user: string, role: string}[]}} holders
+ */
+export function rolesBadge(roles = [], {counts = {}, orphans = []} = {}) {
+    const n = roles.length;
+    const fromPlugins = roles.filter(r => r.plugin).length;
+    const unused = roles.filter(r => r.level !== 0 && !counts[r.name]).length;
+    const sorted = [...roles].sort((a, b) => (a.level ?? 99) - (b.level ?? 99) || String(a.name).localeCompare(String(b.name)));
+    return {
+        count: n,
+        label: orphans.length
+            ? `${plural(orphans.length, 'user')} ${orphans.length === 1 ? 'holds' : 'hold'} a role that no longer exists`
+            : `${plural(n, 'role')}${fromPlugins ? `, ${fromPlugins} from plugins` : ''}`,
+        tone: orphans.length ? 'danger' : 'info',
+        details: {
+            title: 'Roles',
+            rows: [
+                {label: 'Roles', value: String(n)},
+                {label: 'From plugins', value: String(fromPlugins)},
+                {label: 'Held by nobody', value: String(unused)},
+                ...(orphans.length ? [{label: 'Users on a missing role', value: String(orphans.length), tone: 'danger'}] : [])
+            ],
+            items: orphans.length
+                ? Object.entries(orphans.reduce((m, o) => ({...m, [o.role]: (m[o.role] || 0) + 1}), {})).slice(0, 8)
+                    .map(([role, k]) => ({text: `"${role}"`, meta: `no longer exists - ${plural(k, 'user')} still ${k === 1 ? 'holds' : 'hold'} it`, tone: 'danger'}))
+                : sorted.slice(0, 8).map(r => ({
+                    text: String(r.label || r.name),
+                    meta: `level ${r.level} · ${plural(counts[r.name] || 0, 'user')}${r.plugin ? ` · ${r.plugin}` : ''}`
+                })),
+            empty: 'No roles.'
+        }
+    };
+}
+
+/**
+ * @param {import('fastify').FastifyInstance} fastify
+ * @param {{authenticate?: Function, requirePermission?: Function}} [opts]
+ */
+export async function rolesRoutes(fastify, opts = {}) {
+    const authenticate      = opts.authenticate      || defaultAuthenticate;
+    const requirePermission = opts.requirePermission || defaultRequirePermission;
+    // `plugins`: the permission the Roles sidebar entry (and menu item) asks for, so
+    // whoever sees the entry can read its badge - with `collections` it 403'd every minute.
+    const canRead = {preHandler: [authenticate, requirePermission('plugins', 'read')]};
+
+    const current = async () => {
+        // The collection's entries, not the role cache: the cache drops `plugin`.
+        const {entries} = await listEntries('roles', {limit: 0});
+        const roles = entries.map(e => e.data || {}).filter(r => r.name);
+        const holders = roleHolders(await listUsers().catch(() => []), roles.map(r => r.name));
+        return {roles, holders};
+    };
+
+    fastify.get('/roles/_holders', canRead, async () => (await current()).holders);
+
+    fastify.get('/roles/_count', canRead, async () => {
+        const {roles, holders} = await current();
+        return rolesBadge(roles, holders);
+    });
+}

package/server/routes/api/search.js

@@ -4,17 +4,35 @@
  * GET  /api/search?q=…      - public: full-text search across published pages
  * GET  /api/search/settings - public: the search UI's own configuration
  * PUT  /api/search/settings - admin-only: save it
+ * GET  /api/search/preview?q=…&max=… - admin-only: the Search screen's "Try it" -
+ *        the same search, run with the max-results being edited (not yet saved)
+ *        and without the minimum length, so a setting can be tried before Save
+ * GET  /api/search/_count   - admin-only: the sidebar badge (searchBadge)
  *
  * The public settings endpoint is kept for anything already calling it (and
  * for a page served from a cache older than the feature), but it is no longer
  * on the critical path: the renderer embeds the same object in the page as
  * `window.__CMS_SEARCH__`, so the overlay can draw itself without a round trip.
  */
-import {authenticate, requireAdmin} from '../../middleware/auth.js';
+import {authenticate as defaultAuthenticate, requireAdmin as defaultRequireAdmin,
+    requirePermission as defaultRequirePermission} from '../../middleware/auth.js';
 import {listPages} from '../../services/content.js';
-import {getSearchSettings, saveSearchSettings, searchPages} from '../../services/search.js';
+import {getSearchSettings, saveSearchSettings, searchBadge, searchCoverage, searchPages} from '../../services/search.js';
+
+/**
+ * @param {import('fastify').FastifyInstance} fastify
+ * @param {{authenticate?: Function, requireAdmin?: Function}} [opts] - DI for tests
+ */
+export async function searchRoutes(fastify, opts = {}) {
+    const authenticate = opts.authenticate || defaultAuthenticate;
+    const requireAdmin = opts.requireAdmin || defaultRequireAdmin;
+    const adminOnly = {preHandler: [authenticate, requireAdmin]};
+    const requirePermission = opts.requirePermission || defaultRequirePermission;
+    // The badge follows the Search sidebar entry's own permission (settings), so whoever
+    // sees the entry can read it - admin-only, it 403'd every minute for the rest. It
+    // tells nothing a visitor's search does not: public pages only.
+    const canReadBadge = {preHandler: [authenticate, requirePermission('settings', 'read')]};
 
-export async function searchRoutes(fastify) {
     fastify.get('/search', async (request, reply) => {
         const settings = getSearchSettings();
         const q = (request.query.q || '').trim();
@@ -37,7 +55,23 @@ export async function searchRoutes(fastify) {
 
     fastify.get('/search/settings', async () => getSearchSettings());
 
-    fastify.put('/search/settings', {preHandler: [authenticate, requireAdmin]}, async (request) => {
+    fastify.put('/search/settings', adminOnly, async (request) => {
         return {ok: true, settings: saveSearchSettings(request.body || {})};
     });
+
+    fastify.get('/search/preview', adminOnly, async (request, reply) => {
+        const q = String(request.query.q || '').trim().slice(0, 200);
+        if (!q) return reply.status(400).send({error: 'Type something to search for'});
+        const settings = getSearchSettings();
+        const asked = parseInt(request.query.max, 10);
+        const maxResults = Number.isFinite(asked) ? Math.min(50, Math.max(1, asked)) : settings.maxResults;
+        const pages = await listPages();
+        const results = searchPages(pages, q, {
+            maxResults,
+            onError: (err, page) => request.log.warn({err, page: page.urlPath}, '[search] skipped an unreadable page')
+        });
+        return {q, maxResults, results, coverage: searchCoverage(pages)};
+    });
+
+    fastify.get('/search/_count', canReadBadge, async () => searchBadge(getSearchSettings(), await listPages()));
 }

package/server/routes/api/settings.js

@@ -3,6 +3,7 @@
  * GET  /api/settings            - get site settings
  * PUT  /api/settings            - save site settings
  * POST /api/settings/test-email - send a test email using stored SMTP config
+ * GET  /api/settings/_count     - the sidebar badge: what is wrong with the settings
  */
 import {getConfig, saveConfig} from '../../config.js';
 import {authenticate, requirePermission} from '../../middleware/auth.js';
@@ -18,6 +19,50 @@ const CUSTOM_CSS_FILE = path.resolve(__dirname, '../../../content/custom.css');
 const CONNECTIONS_FILE = path.resolve(__dirname, '../../../config/connections.json');
 const CUSTOM_CSS_MAX = 100 * 1024; // 100 KB
 
+/**
+ * The sidebar badge on Site Settings (its countUrl): the settings that are
+ * quietly wrong, worst first - chiefly no SMTP host, where the CMS sends every
+ * mail to a throwaway test inbox that accepts it and reports success, so
+ * nothing else in the admin looks wrong. Nothing wrong = no badge. The same
+ * rules as settingsProblems() in admin/js/lib/site-settings-arrange.js.
+ * Plain text throughout - the popover sets it with textContent.
+ *
+ * @param {object} site - config/site.json
+ * @param {{enabled?: boolean, driver?: string}} [cacheStats]
+ */
+export function settingsBadge(site = {}, cacheStats = {}) {
+    const smtp = site.smtp || {};
+    const cc = site.cookieConsent || {};
+    const problems = [];
+    if (!String(smtp.host || '').trim()) {
+        problems.push({tone: 'danger', text: 'No SMTP host', meta: 'mail goes to a test inbox and reaches no one'});
+    } else if (!String(smtp.fromAddress || '').trim()) {
+        problems.push({tone: 'warn', text: 'No From address', meta: 'mail has no sender; many servers refuse it'});
+    }
+    if (cc.enabled !== false && !String(cc.privacyPolicyUrl || '').trim()) {
+        problems.push({tone: 'warn', text: 'Cookie banner without a privacy policy', meta: 'it links to nothing'});
+    }
+    const danger = problems.some(p => p.tone === 'danger');
+    const n = problems.length;
+    return {
+        count: n,
+        label: n ? `${n} setting${n === 1 ? '' : 's'} need${n === 1 ? 's' : ''} attention` : 'Settings look fine',
+        tone: danger ? 'danger' : 'attention',
+        details: {
+            title: 'Site Settings',
+            rows: [
+                {label: 'Site title', value: String(site.title || '-')},
+                {label: 'Admin home', value: String(site.adminHome || '/')},
+                {label: 'Email', value: smtp.host ? String(smtp.host) : 'not configured', ...(!smtp.host && {tone: 'danger'})},
+                {label: 'Cookie banner', value: cc.enabled !== false ? 'on' : 'off'},
+                {label: 'Cache', value: cacheStats.enabled ? `on (${cacheStats.driver || 'memory'})` : 'off'}
+            ],
+            items: problems.map(p => ({text: p.text, meta: p.meta, ...(p.tone === 'danger' && {tone: 'danger'})})),
+            empty: 'Nothing needs attention.'
+        }
+    };
+}
+
 export async function settingsRoutes(fastify) {
     const canRead = {preHandler: [authenticate, requirePermission('settings', 'read')]};
     const canUpdate = {preHandler: [authenticate, requirePermission('settings', 'update')]};
@@ -112,6 +157,13 @@ export async function settingsRoutes(fastify) {
         }
     });
 
+    // The sidebar badge. `_count` sits beside fixed paths only - nothing can shadow it.
+    fastify.get('/settings/_count', canRead, async () => {
+        let stats = {};
+        try { stats = cache.getStats(); } catch { /* no cache - reported off */ }
+        return settingsBadge(getConfig('site') || {}, stats);
+    });
+
     // GET /api/settings/db-status - returns whether MongoDB connections are configured
     fastify.get('/settings/db-status', canRead, async () => {
         try {