domma-cms 0.71.0 → 0.73.0

package/server/services/plugins.js

@@ -20,10 +20,12 @@ import {
     registerMenuLocation,
     registerSanitizeRules,
     registerShortcode,
+    hideSidebarUrl,
     registerSidebarItem,
     registerTransform
 } from './hooks.js';
 import {registerPluginResource, unregisterPluginResourcesByPlugin} from './permissionRegistry.js';
+import {registerThemeProvider} from './themeSettings.js';
 import {classifyEntitlement, mayLoad} from './pluginEntitlement.js';
 import {createCollection, getCollection} from './collections.js';
 import * as defaultRolesService from './roles.js';
@@ -138,6 +140,49 @@ const CORE_PLUGINS = new Set([]);
 /** Is this plugin a built-in feature rather than an optional add-on? */
 export function isCorePlugin(name) { return CORE_PLUGINS.has(name); }
 
+/**
+ * The Tools promoted out of plugins/ in 0.67.0 - core code now, each with its
+ * own `#/<name>` screen and sidebar entry (server/server.js).
+ *
+ * Not plugins, so `supersedes` could never reach them the way it reaches the
+ * free Blog. A plugin that names one in `supersedes` TAKES IT OVER instead:
+ * the core Tool's sidebar entry is hidden and its screen hands over to the
+ * plugin's first admin route. The core Tool's API stays up - other plugins
+ * (Invoices reads contacts) depend on it, and the paid edition works over the
+ * same data - and, like supersession, nothing is written down: a lapsed
+ * licence means the plugin does not load and the core Tool is simply back.
+ */
+export const BUILT_IN_TOOLS = new Set(['notes', 'todo', 'analytics', 'contacts']);
+
+/** Built-in Tool → {plugin, route}, for the plugins that loaded this boot. */
+const _toolTakeovers = {};
+
+/**
+ * Which built-in Tools a loaded plugin has taken over.
+ *
+ * @returns {Object.<string, {plugin: string, route: string|null}>}
+ */
+export function getToolTakeovers() {
+    return {..._toolTakeovers};
+}
+
+/**
+ * The takeovers one manifest claims: every built-in Tool in its `supersedes`
+ * that no earlier plugin has claimed. Pure, for the test.
+ *
+ * @param   {object} manifest
+ * @param   {object} [taken] - claims already made
+ * @returns {Object.<string, {plugin: string, route: string|null}>}
+ */
+export function toolTakeoversOf(manifest, taken = {}) {
+    const out = {};
+    const route = manifest?.admin?.routes?.[0]?.path ?? null;
+    for (const tool of Array.isArray(manifest?.supersedes) ? manifest.supersedes : []) {
+        if (BUILT_IN_TOOLS.has(tool) && !taken[tool] && !out[tool]) out[tool] = {plugin: manifest.name, route};
+    }
+    return out;
+}
+
 /**
  * Scan the plugins/ directory and return all valid manifests.
  * Validates mandatory fields and required files (plugin.js, config.js).
@@ -417,23 +462,37 @@ export async function registerPlugins(fastify) {
           await fastify.register(plugin, {
             prefix,
             auth: {authenticate, requireRole, requireAdmin, requireVisibility, requirePermission},
-              hooks: {registerShortcode, registerSanitizeRules, registerTransform, registerMenuLocation, registerSidebarItem, on: hooks.on.bind(hooks), ...pluginRoleHooks(manifest.name)},
+              hooks: {registerShortcode, registerSanitizeRules, registerTransform, registerMenuLocation,
+                  // Stamped with the plugin's name, so the Menus editor can say where a Tool came from.
+                  registerSidebarItem: (opts) => registerSidebarItem({...opts, item: {source: manifest.displayName || manifest.name, ...opts?.item}}),
+                  // Custom themes the plugin offers (the Theme Roller) - bound to the
+                  // plugin, so one plugin cannot replace another's. See themeSettings.js.
+                  registerThemes: (provider) => registerThemeProvider(manifest.name, provider),
+                  on: hooks.on.bind(hooks), ...pluginRoleHooks(manifest.name)},
               settings,
               config: {}
           });
             loaded.push(manifest.name);
 
+            // A built-in Tool this plugin replaces: hide the core sidebar entry
+            // (the admin sends its screen to the plugin - getAdminPluginConfig).
+            for (const [tool, claim] of Object.entries(toolTakeoversOf(manifest, _toolTakeovers))) {
+                _toolTakeovers[tool] = claim;
+                hideSidebarUrl(`#/${tool}`);
+                fastify.log.info(`[plugins] built-in Tool "${tool}" taken over by "${manifest.name}".`);
+            }
+
             // Bridge plugin.json `admin.sidebar` entries into the sidebar
             // registry so they render in the admin sidebar. The admin renderer
             // reads plugin nav from /api/sidebar/registered-items; plugins
             // declare their nav in the manifest rather than calling
-            // registerSidebarItem, so register it here on their behalf.
-            // Tag each item with the plugin's core status so the admin sidebar
-            // can auto-group it: core plugins → Tools folder, optional → Plugins.
+            // registerSidebarItem, so register it here on their behalf. An
+            // entry's `folder` is its default place (Tools when it names none);
+            // an admin can move it anywhere in the menu.
             const isCore = CORE_PLUGINS.has(manifest.name);
             for (const item of manifest.admin?.sidebar || []) {
                 try {
-                    registerSidebarItem({item: {...item, core: isCore}});
+                    registerSidebarItem({item: {source: manifest.displayName || manifest.name, ...item, core: isCore}});
                 } catch (err) {
                     fastify.log.warn(`[plugins] sidebar item for "${manifest.name}" skipped: ${err.message}`);
                 }
@@ -1113,6 +1172,33 @@ export function pluginExpiry(manifest, given) {
         : null;
 }
 
+
+/**
+ * The sidebar name of the screen a view draws, for its banner - '' when the
+ * plugin has one screen or the view has no sidebar entry of its own.
+ *
+ * A route maps a path to a view and a sidebar entry links to a path, so the
+ * entry whose link is one of the view's routes names it. Sub-entries win over
+ * the top-level one: Site Manager's top entry and its "Sites" entry share a
+ * link, and "Sites" is the screen.
+ *
+ * @param   {object} manifest
+ * @param   {string} viewName
+ * @returns {string}
+ */
+export function viewSection(manifest, viewName) {
+    const admin = manifest.admin || {};
+    const paths = new Set((admin.routes || [])
+        .filter(r => r && r.view === viewName && typeof r.path === 'string')
+        .map(r => `#${r.path}`));
+    if (!paths.size) return '';
+    const top = admin.sidebar || [];
+    const entries = [...top.flatMap(e => (e && e.items) || []), ...top];
+    const hit = entries.find(e => e && paths.has(e.url));
+    const text = hit ? String(hit.text || '').trim() : '';
+    return text && text !== (manifest.displayName || manifest.name) ? text : '';
+}
+
 export async function getAdminPluginConfig() {
     const manifests = await discoverPlugins();
     const states = getPluginStates();
@@ -1160,6 +1246,7 @@ export async function getAdminPluginConfig() {
             meta[viewName] = {
                 plugin:      manifest.name,
                 displayName: manifest.displayName || manifest.name,
+                section:     viewSection(manifest, viewName),
                 version:     manifest.version || '1.0.0',
                 date:        manifest.date || '',
                 author:      manifest.author || '',
@@ -1189,5 +1276,5 @@ export async function getAdminPluginConfig() {
         }
     }
 
-    return { sidebar, routes, views, css, meta };
+    return { sidebar, routes, views, css, meta, takeovers: getToolTakeovers() };
 }

package/server/services/renderer.js

@@ -12,7 +12,7 @@ import {resolveLocation, resolveMenuDecorations, resolveOverlaysForPage} from '.
 import {buildMenuNav} from './menuRender.js';
 import {getProjectForPage} from './projects.js';
 import {resolveContextMenusForPage} from './contextMenus.js';
-import {buildOverrideStyleTag, getThemeTokenMap, listThemeIds, loadThemeConfig} from './themeSettings.js';
+import {buildCustomThemeStyleTag, buildOverrideStyleTag, getThemeTokenMap, listThemeIds, loadThemeConfig, resolveThemeClasses} from './themeSettings.js';
 import {getSearchSettings} from './search.js';
 
 const VALID_LAYOUT_WIDTHS = new Set(['narrow', 'normal', 'wide', 'full']);
@@ -74,7 +74,7 @@ function buildSearchAssets() {
     };
 }
 
-const THEME_SWITCHER_ASSET_V = '20260922-ts';
+const THEME_SWITCHER_ASSET_V = '20260925-ts';
 const ANALYTICS_ASSET_V = '20260922-analytics';
 
 /**
@@ -397,7 +397,7 @@ export async function renderPage(page, opts = {}) {
         // Theme overrides land BEFORE content/custom.css: the overrides are
         // generated, custom.css is hand-written, and the hand-written one stays
         // the last word.
-        headInjectLate: [injection.headLate, searchAssets.headTag, switcherAssets.headTag, themeView.overrideStyleTag, customCssTag, navbarStyleTag]
+        headInjectLate: [injection.headLate, searchAssets.headTag, switcherAssets.headTag, themeView.customThemeStyleTag, themeView.overrideStyleTag, customCssTag, navbarStyleTag]
             .filter(Boolean).join('\n'),
         bodyEndInject: [
             // Draft banner - first, so it is the topmost fixed element and a
@@ -789,16 +789,28 @@ async function buildThemeView(page = {}) {
 
     // A page pinned to a theme opts out of the automatic pair - otherwise the
     // pin would silently expire at the day/night boundary.
-    const autoTheme = (!page.theme && cfg.autoTheme?.enabled) ? cfg.autoTheme : null;
+    // A copy: `apply` is added below, and the loaded config must not carry it.
+    const autoTheme = (!page.theme && cfg.autoTheme?.enabled) ? {...cfg.autoTheme} : null;
     const activeTheme = page.theme
         || (autoTheme ? autoTheme.dayTheme : cfg.theme)
         || 'charcoal-dark';
 
-    // A custom (Theme Roller) theme is not a theme Domma's engine knows, so it
-    // receives the built-in base and the custom class rides along separately,
-    // added after init so _applyTheme() cannot strip it.
-    const dommaTheme = cfg.baseTheme || activeTheme;
-    const customThemeClass = cfg.baseTheme ? `dm-theme-${activeTheme}` : '';
+    // A custom theme (a plugin's - the Theme Roller) is not one Domma's engine
+    // knows: Domma is given its built-in base, and the custom class rides
+    // beside it. It is `dm-custom-<id>`, not `dm-theme-<id>`, because Domma
+    // strips every dm-theme-* class it did not put there.
+    const {dommaTheme, customClass: customThemeClass} = resolveThemeClasses(activeTheme, cfg);
+
+    // The browser switches between the day and night themes itself, so it is
+    // told how to apply each (base + custom class) rather than just its id.
+    if (autoTheme) {
+        const day = resolveThemeClasses(autoTheme.dayTheme, cfg);
+        const night = resolveThemeClasses(autoTheme.nightTheme, cfg);
+        autoTheme.apply = {
+            [autoTheme.dayTheme]: {theme: day.dommaTheme, custom: day.customClass},
+            [autoTheme.nightTheme]: {theme: night.dommaTheme, custom: night.customClass}
+        };
+    }
 
     const {fontLink, fontOverride} = buildFontVars(cfg.font?.family, cfg.font?.size);
 
@@ -810,6 +822,8 @@ async function buildThemeView(page = {}) {
         customThemeClass,
         fontLink,
         fontStyleTag: fontOverride ? `<style>${fontOverride}</style>` : '',
+        // Only the custom themes this page can show: its own, and day/night's.
+        customThemeStyleTag: buildCustomThemeStyleTag([activeTheme, autoTheme?.dayTheme, autoTheme?.nightTheme]),
         overrideStyleTag: buildOverrideStyleTag(cfg)
     };
 }
@@ -1008,7 +1022,7 @@ export async function renderBlogPage(templatePath, data = {}, seoMeta = {}) {
         // Theme overrides land BEFORE content/custom.css: the overrides are
         // generated, custom.css is hand-written, and the hand-written one stays
         // the last word.
-        headInjectLate: [injection.headLate, searchAssets.headTag, switcherAssets.headTag, themeView.overrideStyleTag, customCssTag, navbarStyleTag]
+        headInjectLate: [injection.headLate, searchAssets.headTag, switcherAssets.headTag, themeView.customThemeStyleTag, themeView.overrideStyleTag, customCssTag, navbarStyleTag]
             .filter(Boolean).join('\n'),
         bodyEndInject: [
             overlayMenus,

package/server/services/roles.js

@@ -337,11 +337,22 @@ const ADMIN_PATH_RE = /^\/[A-Za-z0-9\-_/]*$/;
  * @param {*} raw
  * @returns {{home: string, allow: string[]}|null}
  */
-export function normaliseAdminScope(raw) {
-    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null;
-    const clean = p => (typeof p === 'string' && ADMIN_PATH_RE.test(p.trim()))
+/**
+ * An admin route path (`/portal`, `/plugins/x/dashboard`), cleaned - or null if
+ * it is not one. Trailing slashes go; the root stays `/`.
+ *
+ * @param {unknown} p
+ * @returns {string|null}
+ */
+export function normaliseAdminPath(p) {
+    return (typeof p === 'string' && ADMIN_PATH_RE.test(p.trim()))
         ? (p.trim().replace(/\/+$/, '') || '/')
         : null;
+}
+
+export function normaliseAdminScope(raw) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null;
+    const clean = normaliseAdminPath;
     const allow = [...new Set((Array.isArray(raw.allow) ? raw.allow : []).map(clean).filter(Boolean))];
     const home  = clean(raw.home) || allow[0] || null;
     if (!home) return null;

package/server/services/sidebar-migration.js

@@ -3,8 +3,13 @@
  *
  * Runs once on server boot. Idempotent - guarded by the existence of
  * config/menus/admin-sidebar.json. Seeds the admin sidebar menu with the
- * standard tree (Overview, Projects, Content, Data, System, Documentation)
- * and patches config/menu-locations.json to map the `admin-sidebar` slot.
+ * standard tree (Overview, Projects, Content, Data, Tools, System,
+ * Documentation) and patches config/menu-locations.json to map the
+ * `admin-sidebar` slot.
+ *
+ * Top-level folders carry a stable `key`. A Tool names its default folder by
+ * key, so an admin can rename a folder without the Tools that live in it
+ * falling out of it. ensureFolderKeys() brings menus seeded before keys up.
  */
 import fs from 'fs/promises';
 import path from 'path';
@@ -16,19 +21,19 @@ const DEFAULT_CONFIG_DIR = path.resolve(path.dirname(__filename), '..', '..', 'c
 
 const SEED_ITEMS = [
     {
-        text: 'Overview', icon: 'home',
+        text: 'Overview', key: 'overview', icon: 'home',
         items: [
             {text: 'Dashboard', url: '#/', icon: 'home'}
         ]
     },
     {
-        text: 'Projects', icon: 'folder', permission: 'projects',
+        text: 'Projects', key: 'projects', icon: 'folder', permission: 'projects',
         items: [
             {text: 'Manage projects', url: '#/projects', icon: 'folder', permission: 'projects'}
         ]
     },
     {
-        text: 'Content', icon: 'edit',
+        text: 'Content', key: 'content', icon: 'edit',
         items: [
             {text: 'Pages', url: '#/pages', icon: 'file-text', permission: 'pages'},
             {text: 'Media', url: '#/media', icon: 'image',     permission: 'media'},
@@ -36,7 +41,7 @@ const SEED_ITEMS = [
         ]
     },
     {
-        text: 'Data', icon: 'database',
+        text: 'Data', key: 'data', icon: 'database',
         items: [
             {text: 'Collections', url: '#/collections', icon: 'database',  permission: 'collections'},
             {text: 'Forms',       url: '#/forms',       icon: 'layout',    permission: 'collections'},
@@ -47,8 +52,12 @@ const SEED_ITEMS = [
             {text: 'Components',  url: '#/components',  icon: 'component', permission: 'components'}
         ]
     },
+    // Enabled Tools are placed here at render time (placeTools in
+    // admin/js/lib/sidebar-grouping.js); the folder is persisted so an admin
+    // can rename, move or reorder it like any other.
+    {text: 'Tools', key: 'tools', icon: 'tool', items: []},
     {
-        text: 'System', icon: 'settings',
+        text: 'System', key: 'system', icon: 'settings',
         items: [
             {text: 'Notifications', url: '#/system/notifications', icon: 'bell',     permission: 'notifications'},
             {text: 'Roles',         url: '#/roles',                icon: 'shield',   permission: 'plugins'},
@@ -63,7 +72,7 @@ const SEED_ITEMS = [
         ]
     },
     {
-        text: 'Documentation', icon: 'book',
+        text: 'Documentation', key: 'documentation', icon: 'book',
         items: [
             DOC_USAGE_SUBMENU(),
             DOC_TUTORIALS_SUBMENU(),
@@ -307,3 +316,68 @@ export async function ensureDocumentationSubmenus(opts = {}) {
     console.log('[admin-sidebar] Upgraded Documentation group with per-topic submenus');
     return {updated: true};
 }
+
+/** Keys for the folders the seed has always created, matched by their original name. */
+const SEED_FOLDER_KEYS = {
+    overview: 'overview', projects: 'projects', content: 'content', data: 'data',
+    tools: 'tools', system: 'system', documentation: 'documentation'
+};
+
+/**
+ * Give an existing install's top-level folders their stable `key`, and - once -
+ * a persisted Tools folder for enabled Tools to be placed into.
+ *
+ *  - A folder is keyed only if it has no key yet and still carries one of the
+ *    seed's names; a folder the admin made, or renamed before keys existed, is
+ *    left alone (placement falls back to Tools for it).
+ *  - The Tools folder is added only on the first run (`meta.toolsFolder`), so
+ *    an admin who later deletes it does not get it back on every boot. Until
+ *    then placement synthesises one, exactly as before.
+ *
+ * Returns `{updated: boolean, reason?: string}`.
+ *
+ * @param {{configDir?: string}} [opts]
+ */
+export async function ensureFolderKeys(opts = {}) {
+    const configDir = opts.configDir || DEFAULT_CONFIG_DIR;
+    const menuPath  = path.join(configDir, 'menus', 'admin-sidebar.json');
+
+    if (!await exists(menuPath)) {
+        return {updated: false, reason: 'admin-sidebar.json not present'};
+    }
+
+    const menu  = await readJson(menuPath);
+    const items = Array.isArray(menu.items) ? menu.items : (menu.items = []);
+    const isFolder = (n) => n && typeof n === 'object' && !n.url && n.type !== 'separator' && n.type !== 'spacer';
+
+    let changed = false;
+    const used = new Set(items.filter(n => isFolder(n) && n.key).map(n => n.key));
+    for (const node of items) {
+        if (!isFolder(node) || node.key) continue;
+        const key = SEED_FOLDER_KEYS[String(node.text || '').trim().toLowerCase()];
+        if (!key || used.has(key)) continue;
+        node.key = key;
+        used.add(key);
+        changed = true;
+    }
+
+    // An empty menu is left empty: the renderer's minimal fallback (Dashboard,
+    // Menus) is what an admin needs to repair it, and a lone Tools folder would
+    // stop that fallback from applying.
+    if (!menu.meta?.toolsFolder && items.length) {
+        if (!used.has('tools')) {
+            const idx = items.findIndex(n => isFolder(n) && ['system', 'documentation'].includes(n.key));
+            const tools = {text: 'Tools', key: 'tools', icon: 'tool', items: []};
+            items.splice(idx === -1 ? items.length : idx, 0, tools);
+        }
+        menu.meta = {...(menu.meta || {}), toolsFolder: true};
+        changed = true;
+    }
+
+    if (!changed) return {updated: false, reason: 'already up to date'};
+
+    menu.meta = {...(menu.meta || {}), updatedAt: new Date().toISOString()};
+    await writeJson(menuPath, menu);
+    console.log('[admin-sidebar] Gave the sidebar folders stable keys');
+    return {updated: true};
+}