domma-cms 0.55.1 → 0.66.0

package/server/services/themeSettings.js

@@ -0,0 +1,541 @@
+/**
+ * Theme settings - config/theme.json.
+ *
+ * Everything that decides how the site and the admin LOOK: the front-end
+ * theme, the admin theme, the automatic day/night pair, the font, and the
+ * per-element overrides. It used to live scattered through config/site.json
+ * next to SMTP credentials and cookie-banner copy; migrateThemeConfig() lifts
+ * it out on first boot.
+ *
+ * site.json keeps a MIRROR of the plain keys (theme, adminTheme, fontFamily,
+ * fontSize, autoTheme, baseTheme), rewritten on every save. Nothing in the CMS
+ * reads it any more, but plugins, the fleet manager and the Theme Roller all
+ * do, and silently changing what they read is not worth the tidiness. theme.json
+ * is the authoritative copy; the mirror is one-way and never read back except
+ * by the migration.
+ *
+ * ---------------------------------------------------------------------------
+ * Overrides
+ * ---------------------------------------------------------------------------
+ * A Domma theme is nothing but a class-scoped block of custom properties:
+ *
+ *     .dm-theme-ocean-dark { --dm-primary: #00b4d8; --dm-surface: #1e293b; ... }
+ *
+ * So re-theming one region is not a CSS-authoring problem, it is a scoping
+ * problem: declare the same properties on a selector and everything inside it
+ * follows, including components rendered long afterwards. That is why an
+ * override is expressed as a selector plus either a theme to adopt or a set of
+ * token values - NOT as hand-written rules fighting the cascade, which is how
+ * the navbar hover bug happened.
+ *
+ * Each override compiles to one rule:
+ *
+ *     {scope: '#site-navbar', theme: 'ocean-light', tokens: {'--dm-primary': '#09c'}}
+ *       -> #site-navbar { <every token of ocean-light>; --dm-primary: #09c; }
+ *
+ * `css` is the escape hatch for the rare thing tokens cannot say. It is
+ * appended verbatim after the generated rule, so the author owns its selectors.
+ *
+ * KNOWN LIMIT: a handful of Domma rules key off an ANCESTOR mode rather than
+ * tokens (`[data-mode="dark"] .alert-info`, the syntax-highlight palette).
+ * Scoping a light theme into a dark page re-colours everything token-driven,
+ * but those few rules still follow the page. Documented in docs/theming.md
+ * rather than papered over with generated counter-rules.
+ */
+
+import fs from 'fs/promises';
+import fsSync from 'fs';
+import path from 'path';
+import {fileURLToPath} from 'url';
+import {getConfig, saveConfig} from '../config.js';
+import * as cache from './cache/index.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.resolve(__dirname, '..', '..');
+const CONFIG_DIR = path.join(ROOT, 'config');
+const THEME_FILE = path.join(CONFIG_DIR, 'theme.json');
+
+/**
+ * The shipped theme stylesheet - the single source of truth for which themes
+ * exist and which tokens they declare. Read from the installed domma-js
+ * package so it can never drift from the CSS the browser actually loads.
+ */
+const THEME_CSS_CANDIDATES = [
+    path.join(ROOT, 'node_modules', 'domma-js', 'public', 'dist', 'themes', 'domma-themes.css'),
+    path.join(ROOT, 'public', 'dist', 'domma', 'themes', 'domma-themes.css')
+];
+
+const TOKEN_RE = /^--dm-[a-z0-9-]+$/;
+const DEFAULT_THEME = 'charcoal-dark';
+
+/** Selectors that would swallow the whole document rather than scope anything. */
+const FORBIDDEN_SCOPES = new Set(['*', ':root', 'html', 'html *', '*, *::before, *::after']);
+
+export function defaultThemeConfig() {
+    return {
+        version: 1,
+        theme: DEFAULT_THEME,
+        adminTheme: DEFAULT_THEME,
+        baseTheme: null,
+        autoTheme: {
+            enabled: false,
+            dayTheme: 'charcoal-light',
+            nightTheme: 'charcoal-dark',
+            dayStart: '07:00',
+            nightStart: '19:00'
+        },
+        font: {family: 'Roboto', size: 16},
+        overrides: []
+    };
+}
+
+// ---------------------------------------------------------------------------
+// Theme stylesheet introspection
+// ---------------------------------------------------------------------------
+
+let _cssCache = null;
+
+function readThemeStylesheet() {
+    if (_cssCache !== null) return _cssCache;
+    for (const file of THEME_CSS_CANDIDATES) {
+        try {
+            _cssCache = fsSync.readFileSync(file, 'utf8');
+            return _cssCache;
+        } catch { /* try the next candidate */ }
+    }
+    _cssCache = '';
+    return _cssCache;
+}
+
+/** Drop the memoised stylesheet - after an upgrade, or in tests. */
+export function invalidateThemeStylesheet() {
+    _cssCache = null;
+    _themeIdCache = null;
+    _tokenNameCache = null;
+}
+
+let _themeIdCache = null;
+
+/**
+ * Every theme id the shipped stylesheet defines, e.g. 'ocean-dark'.
+ *
+ * @returns {string[]}
+ */
+export function listThemeIds() {
+    if (_themeIdCache) return _themeIdCache;
+    const css = readThemeStylesheet();
+    const ids = new Set();
+    for (const m of css.matchAll(/^\.dm-theme-([a-z0-9-]+)\s*\{/gm)) ids.add(m[1]);
+    _themeIdCache = [...ids];
+    return _themeIdCache;
+}
+
+let _tokenNameCache = null;
+
+/**
+ * Every `--dm-*` token the stylesheet declares. The admin picker builds itself
+ * from this, so an override can only name a token that actually exists - an
+ * invented one resolves to nothing and produces the blank-popup class of bug.
+ *
+ * @returns {string[]}
+ */
+export function listThemeTokens() {
+    if (_tokenNameCache) return _tokenNameCache;
+    const css = readThemeStylesheet();
+    const names = new Set();
+    for (const m of css.matchAll(/(--dm-[a-z0-9-]+)\s*:/g)) names.add(m[1]);
+    _tokenNameCache = [...names].sort();
+    return _tokenNameCache;
+}
+
+/**
+ * The declaration body of one theme's class block, ready to be re-scoped.
+ *
+ * Returns the raw text between the braces (`--dm-primary: #...; ...`), or null
+ * when the theme is unknown - a renamed or removed theme must not take the
+ * whole stylesheet down with it.
+ *
+ * @param {string} themeId
+ * @returns {string|null}
+ */
+export function getThemeDeclarations(themeId) {
+    if (!themeId || !/^[a-z0-9-]+$/.test(themeId)) return null;
+    const css = readThemeStylesheet();
+    // Anchored so `.dm-theme-x .child {}` descendant rules cannot be mistaken
+    // for the theme's own block, and tolerant of the whitespace a rebuild or a
+    // minifier might change.
+    const re = new RegExp(`^\\.dm-theme-${themeId}\\s*\\{([^}]*)\\}`, 'm');
+    const m = css.match(re);
+    if (!m) return null;
+    // The source block is heavily commented for humans reading the stylesheet.
+    // Copying those comments into every page would add kilobytes per override
+    // for nobody's benefit.
+    return m[1]
+        .replace(/\/\*[\s\S]*?\*\//g, '')
+        .split('\n')
+        .map((line) => line.trim())
+        .filter(Boolean)
+        .join('\n')
+        .trim();
+}
+
+/**
+ * One theme's tokens as a map, for comparing two themes.
+ *
+ * The admin uses this to answer the question that "adopt a theme here" quietly
+ * raises: WHICH tokens does this actually change? Two light themes commonly
+ * share a white surface, so adopting one onto a region can legitimately leave
+ * the thing you were looking at - the fill - exactly as it was.
+ *
+ * @param {string} themeId
+ * @returns {Object<string,string>|null}
+ */
+export function getThemeTokenMap(themeId) {
+    const decls = getThemeDeclarations(themeId);
+    if (decls === null) return null;
+    const tokens = {};
+    for (const m of decls.matchAll(/(--dm-[a-z0-9-]+)\s*:\s*([^;]+);/g)) {
+        tokens[m[1]] = m[2].trim();
+    }
+    return tokens;
+}
+
+// ---------------------------------------------------------------------------
+// Load / save / migrate
+// ---------------------------------------------------------------------------
+
+/**
+ * Spreading a partial over defaults is not enough: a key present with the value
+ * `undefined` wins the spread and erases the default, which is exactly what a
+ * site.json missing `theme` produces on its way through themeConfigFromSite.
+ *
+ * @param {object} obj
+ * @returns {object}
+ */
+function definedOnly(obj) {
+    const out = {};
+    for (const [k, v] of Object.entries(obj || {})) if (v !== undefined) out[k] = v;
+    return out;
+}
+
+function mergeDefaults(raw) {
+    const d = defaultThemeConfig();
+    const cfg = {...d, ...definedOnly(raw)};
+    cfg.autoTheme = {...d.autoTheme, ...definedOnly(raw?.autoTheme)};
+    cfg.font = {...d.font, ...definedOnly(raw?.font)};
+    cfg.overrides = Array.isArray(raw?.overrides) ? raw.overrides : [];
+    return cfg;
+}
+
+/**
+ * Build a theme config from the legacy site.json keys. Used by the migration
+ * and as the fallback when config/theme.json has not been written yet.
+ *
+ * @param {object} site
+ * @returns {object}
+ */
+export function themeConfigFromSite(site = {}) {
+    return mergeDefaults({
+        theme: site.theme,
+        adminTheme: site.adminTheme,
+        baseTheme: site.baseTheme || null,
+        autoTheme: site.autoTheme,
+        font: {family: site.fontFamily, size: site.fontSize},
+        overrides: []
+    });
+}
+
+/**
+ * Read the theme config. Falls back to the legacy site.json keys when
+ * config/theme.json is absent, so a site that has not run the migration (or an
+ * unpacked archive that predates it) still renders with the right theme.
+ *
+ * @returns {Promise<object>}
+ */
+export async function loadThemeConfig() {
+    try {
+        return mergeDefaults(JSON.parse(await fs.readFile(THEME_FILE, 'utf8')));
+    } catch {
+        try {
+            return themeConfigFromSite(getConfig('site'));
+        } catch {
+            return defaultThemeConfig();
+        }
+    }
+}
+
+/** Synchronous twin of loadThemeConfig, for the render path. */
+export function loadThemeConfigSync() {
+    try {
+        return mergeDefaults(JSON.parse(fsSync.readFileSync(THEME_FILE, 'utf8')));
+    } catch {
+        try {
+            return themeConfigFromSite(getConfig('site'));
+        } catch {
+            return defaultThemeConfig();
+        }
+    }
+}
+
+/**
+ * Validate and persist. Throws on the mistakes that look like breakage rather
+ * than typos; unknown keys are dropped rather than stored.
+ *
+ * @param {object} input
+ * @returns {Promise<object>} The stored config.
+ */
+export async function saveThemeConfig(input) {
+    const errors = validateThemeConfig(input);
+    if (errors.length) {
+        const err = new Error(errors.join('; '));
+        err.validation = errors;
+        throw err;
+    }
+
+    const current = await loadThemeConfig();
+    const cfg = mergeDefaults({
+        ...current,
+        ...input,
+        autoTheme: {...current.autoTheme, ...(input.autoTheme || {})},
+        font: {...current.font, ...(input.font || {})},
+        overrides: Array.isArray(input.overrides) ? input.overrides.map(normaliseOverride) : current.overrides
+    });
+    cfg.version = 1;
+
+    await fs.mkdir(CONFIG_DIR, {recursive: true});
+    await fs.writeFile(THEME_FILE, JSON.stringify(cfg, null, 2) + '\n', 'utf8');
+    mirrorToSite(cfg);
+    await invalidateThemeCache();
+    return cfg;
+}
+
+/**
+ * Rewrite the legacy site.json keys so third parties that still read them see
+ * the current values. One-way: nothing reads these back.
+ *
+ * @param {object} cfg
+ * @returns {void}
+ */
+function mirrorToSite(cfg) {
+    try {
+        const site = getConfig('site');
+        site.theme = cfg.theme;
+        site.adminTheme = cfg.adminTheme;
+        site.fontFamily = cfg.font.family;
+        site.fontSize = cfg.font.size;
+        site.autoTheme = cfg.autoTheme;
+        if (cfg.baseTheme) site.baseTheme = cfg.baseTheme;
+        else delete site.baseTheme;
+        saveConfig('site', site);
+    } catch {
+        // site.json being unwritable must not fail a theme save - theme.json is
+        // the authoritative copy and has already landed.
+    }
+}
+
+async function invalidateThemeCache() {
+    try {
+        // `site` only: routes/public.js tags every page with it. There is no
+        // 'pages' tag - passing one looks like belt and braces and is a no-op.
+        await cache.invalidateTags(['site']);
+    } catch (err) {
+        console.warn(`[theme] Page cache not invalidated: ${err.message}`);
+    }
+}
+
+/**
+ * One-time lift of the theme keys out of config/site.json. No-op once
+ * config/theme.json exists, so it is safe to call on every boot.
+ *
+ * @returns {Promise<boolean>} True when a file was written.
+ */
+export async function migrateThemeConfig() {
+    try {
+        await fs.access(THEME_FILE);
+        return false;
+    } catch { /* not migrated yet */ }
+
+    let site = {};
+    try {
+        site = getConfig('site');
+    } catch { /* no site.json - defaults it is */ }
+
+    const cfg = themeConfigFromSite(site);
+    await fs.mkdir(CONFIG_DIR, {recursive: true});
+    await fs.writeFile(THEME_FILE, JSON.stringify(cfg, null, 2) + '\n', 'utf8');
+    return true;
+}
+
+// ---------------------------------------------------------------------------
+// Validation
+// ---------------------------------------------------------------------------
+
+function normaliseOverride(o) {
+    const out = {
+        id: typeof o?.id === 'string' && o.id ? o.id : `ov-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+        label: String(o?.label || '').slice(0, 120),
+        enabled: o?.enabled !== false,
+        scope: String(o?.scope || '').trim(),
+        theme: typeof o?.theme === 'string' && o.theme ? o.theme : null,
+        tokens: {},
+        css: typeof o?.css === 'string' ? o.css : ''
+    };
+    for (const [k, v] of Object.entries(o?.tokens || {})) {
+        if (TOKEN_RE.test(k) && typeof v === 'string' && v.trim()) out.tokens[k] = v.trim();
+    }
+    return out;
+}
+
+/**
+ * A CSS value that cannot break out of its declaration. Braces and semicolons
+ * would end the rule; `<` would end the style element; url()/@import would
+ * fetch. Refused rather than escaped, because every legitimate token value is
+ * a colour, a length or a short keyword list.
+ *
+ * @param {string} value
+ * @returns {boolean}
+ */
+function isSafeTokenValue(value) {
+    if (value.length > 200) return false;
+    if (/[{}<>;]/.test(value)) return false;
+    return !/@import|javascript:|expression\s*\(|url\s*\(/i.test(value);
+}
+
+/**
+ * Validate a whole theme config. Returns a list of human-readable problems -
+ * empty means valid.
+ *
+ * @param {object} input
+ * @returns {string[]}
+ */
+export function validateThemeConfig(input) {
+    const errors = [];
+    if (!input || typeof input !== 'object') return ['Theme config must be an object'];
+
+    const known = listThemeIds();
+    const checkTheme = (value, label) => {
+        if (value === undefined || value === null || value === '') return;
+        if (typeof value !== 'string' || !/^[a-z0-9-]+$/.test(value)) {
+            errors.push(`${label} is not a valid theme id`);
+        } else if (known.length && !known.includes(value)) {
+            errors.push(`${label}: unknown theme "${value}"`);
+        }
+    };
+
+    checkTheme(input.theme, 'Front-end theme');
+    checkTheme(input.adminTheme, 'Admin theme');
+    if (input.baseTheme) checkTheme(input.baseTheme, 'Base theme');
+    if (input.autoTheme) {
+        checkTheme(input.autoTheme.dayTheme, 'Day theme');
+        checkTheme(input.autoTheme.nightTheme, 'Night theme');
+        for (const key of ['dayStart', 'nightStart']) {
+            const v = input.autoTheme[key];
+            if (v !== undefined && !/^\d{2}:\d{2}$/.test(String(v))) {
+                errors.push(`autoTheme.${key} must be HH:MM`);
+            }
+        }
+    }
+    if (input.font) {
+        const size = input.font.size;
+        if (size !== undefined && (!Number.isFinite(Number(size)) || Number(size) < 8 || Number(size) > 48)) {
+            errors.push('Font size must be between 8 and 48');
+        }
+        if (input.font.family !== undefined && !/^[\w \-',]{0,80}$/.test(String(input.font.family))) {
+            errors.push('Font family contains unexpected characters');
+        }
+    }
+
+    if (input.overrides !== undefined) {
+        if (!Array.isArray(input.overrides)) return errors.concat('overrides must be an array');
+        if (input.overrides.length > 100) errors.push('At most 100 overrides');
+        input.overrides.forEach((raw, i) => {
+            const name = raw?.label || `Override ${i + 1}`;
+            const scope = String(raw?.scope || '').trim();
+            if (!scope) {
+                errors.push(`${name}: a target selector is required`);
+            } else if (FORBIDDEN_SCOPES.has(scope.toLowerCase())) {
+                errors.push(`${name}: "${scope}" would re-theme the whole document - set the site theme instead`);
+            } else if (scope.length > 300) {
+                errors.push(`${name}: selector is too long`);
+            } else if (/[{}<>]/.test(scope)) {
+                errors.push(`${name}: selector contains invalid characters`);
+            }
+            if (raw?.theme) checkTheme(raw.theme, `${name}: theme`);
+            for (const [k, v] of Object.entries(raw?.tokens || {})) {
+                if (!TOKEN_RE.test(k)) {
+                    errors.push(`${name}: "${k}" is not a --dm-* token`);
+                } else if (typeof v !== 'string' || !isSafeTokenValue(v)) {
+                    errors.push(`${name}: value for ${k} is not a plain CSS value`);
+                }
+            }
+            if (raw?.css) {
+                if (typeof raw.css !== 'string' || raw.css.length > 20000) {
+                    errors.push(`${name}: custom CSS is too long (20 KB max)`);
+                } else if (/@import|javascript:|expression\s*\(/i.test(raw.css)) {
+                    errors.push(`${name}: custom CSS may not use @import, javascript: or expression()`);
+                }
+            }
+            if (!raw?.theme && !Object.keys(raw?.tokens || {}).length && !raw?.css) {
+                errors.push(`${name}: nothing to apply - pick a theme, set a token, or add CSS`);
+            }
+        });
+    }
+    return errors;
+}
+
+// ---------------------------------------------------------------------------
+// Compilation
+// ---------------------------------------------------------------------------
+
+/**
+ * Compile the enabled overrides into one stylesheet.
+ *
+ * Emitted BEFORE content/custom.css so custom CSS stays the last word, and
+ * injected without a media query so it applies to print as well - a re-themed
+ * region that reverts on paper is a bug report waiting to happen.
+ *
+ * @param {object} cfg - A loaded theme config.
+ * @returns {string} CSS, or '' when there is nothing to emit.
+ */
+export function compileOverrideCss(cfg) {
+    const overrides = (cfg?.overrides || []).filter((o) => o && o.enabled !== false && o.scope);
+    if (!overrides.length) return '';
+
+    const blocks = [];
+    for (const o of overrides) {
+        const decls = [];
+
+        if (o.theme) {
+            const themeDecls = getThemeDeclarations(o.theme);
+            if (themeDecls) decls.push(themeDecls);
+        }
+        for (const [k, v] of Object.entries(o.tokens || {})) {
+            if (TOKEN_RE.test(k) && typeof v === 'string' && isSafeTokenValue(v)) {
+                decls.push(`${k}: ${v};`);
+            }
+        }
+
+        if (decls.length) {
+            const label = o.label ? `/* ${String(o.label).replace(/[*/]/g, '')} */\n` : '';
+            blocks.push(`${label}${o.scope} {\n${decls.join('\n')}\n}`);
+        }
+        if (o.css && typeof o.css === 'string') {
+            blocks.push(o.css.replace(/<\/style>/gi, '<\\/style>'));
+        }
+    }
+    return blocks.join('\n\n');
+}
+
+/**
+ * The `<style>` tag for the page head, or '' when there are no overrides.
+ *
+ * @param {object} cfg
+ * @returns {string}
+ */
+export function buildOverrideStyleTag(cfg) {
+    const css = compileOverrideCss(cfg);
+    if (!css.trim()) return '';
+    return `<style id="dm-theme-overrides">\n${css.replace(/<\/style>/gi, '<\\/style>')}\n</style>`;
+}
+
+export {THEME_FILE};

package/server/services/users.js

@@ -10,6 +10,7 @@ import {v4 as uuidv4} from 'uuid';
 import {config} from '../config.js';
 import {deleteProfile, ensureProfile} from './userProfiles.js';
 import * as cache from './cache/index.js';
+import {hooks} from './hooks.js';
 
 const USERS_DIR = path.resolve(config.content.usersDir);
 
@@ -210,6 +211,13 @@ export async function deleteUser(id) {
     } catch {
         // Profile deletion is best-effort - never block user deletion
     }
+
+    // Plugins holding per-user data need to know, or it outlives the account.
+    // The Mail Reader is the pressing case: its records are stored mailbox
+    // credentials, and leaving those behind for a user who no longer exists is
+    // exactly the sort of thing an audit asks about. Fire-and-forget, after the
+    // deletion has actually happened, so a listener can never block it.
+    hooks.emit('user:deleted', {id});
 }
 
 /**

package/server/templates/page.html

@@ -24,7 +24,7 @@
     <link rel="stylesheet" href="/dist/domma/themes/domma-themes.css">
 
     <!-- Site CSS -->
-    <link rel="stylesheet" href="/public/css/site.css?v=20260905-menu-highlight">
+    <link rel="stylesheet" href="/public/css/site.css?v=20260919-nav-hover-2">
     <link rel="stylesheet" href="/public/css/forms.css?v=20260821-wizard-steps">
     <!-- Menu item hover / current-page effects. Loaded after site.css so a
          menu's own highlight wins over the blanket link styling there. -->
@@ -114,6 +114,7 @@
         window.__CMS_NAV__ = {{navJson}};
         window.__CMS_SITE__ = {{siteJson}};
         {{footerScript}}
+        {{ctxMenusScript}}
       (function () {
           var c = window.__CMS_SITE__ && window.__CMS_SITE__.autoTheme;
           if (!c || !c.enabled) return;
@@ -127,7 +128,8 @@
 
     <!-- Site initialisation -->
     <script src="/public/js/site.js?v=20260829-motion-toggle" type="module"></script>
-    <script src="/public/js/collection-context.js?v=20260819-export" type="module"></script>
+    <script src="/public/js/collection-context.js?v=20260919-ctx-tokens" type="module"></script>
+    {{ctxMenusModule}}
 
     <!-- Floating menu panels: collapse to a hamburger, drag to move, resize.
          Loaded here rather than from site.js so server-rendered overlays and

package/plugins/contacts/data/contacts.json

@@ -1,20 +0,0 @@
-{
-  "contacts": [
-    {
-      "id": "97bbf711-84ce-41cc-898f-811936e051bc",
-      "name": "Darryl Waterhouse",
-      "email": "",
-      "phone": "+447835449292",
-      "groups": [
-        "Coders"
-      ],
-      "notes": "Ledge",
-      "favourite": true,
-      "userId": "2421ad8e-060d-4548-8878-af7011d5e08b",
-      "createdAt": "2026-03-24T16:43:39.907Z"
-    }
-  ],
-  "groups": [
-    "Coders"
-  ]
-}

package/plugins/notes/data/notes.json

@@ -1 +0,0 @@
-[]