domma-cms 0.55.1 → 0.69.3

package/server/services/plugins.js

@@ -24,12 +24,47 @@ import {
     registerTransform
 } from './hooks.js';
 import {registerPluginResource, unregisterPluginResourcesByPlugin} from './permissionRegistry.js';
+import {classifyEntitlement, mayLoad} from './pluginEntitlement.js';
 import {createCollection, getCollection} from './collections.js';
 
 const PLUGINS_DIR = path.resolve('plugins');
 
 const REQUIRED_MANIFEST_FIELDS = ['name', 'displayName', 'version', 'description', 'author', 'date', 'icon'];
 
+/**
+ * Validate a candidate plugin directory the way discoverPlugins() would.
+ *
+ * Exported so an UPGRADE can check what it extracted before swapping it over a
+ * working installation. Validating after the swap would mean discovering the
+ * new version is broken with the old one already gone.
+ *
+ * @param   {string} dir  - absolute directory
+ * @param   {string} slug
+ * @returns {Promise<{ok: boolean, reason?: string, manifest?: object}>}
+ */
+export async function validatePluginDir(dir, slug) {
+    let manifest;
+    try {
+        manifest = JSON.parse(await fs.readFile(path.join(dir, 'plugin.json'), 'utf8'));
+    } catch {
+        return {ok: false, reason: 'no readable plugin.json'};
+    }
+    for (const field of REQUIRED_MANIFEST_FIELDS) {
+        if (!manifest[field]) return {ok: false, reason: `missing required field "${field}"`};
+    }
+    if (manifest.name !== slug) {
+        return {ok: false, reason: `manifest name is "${manifest.name}", not "${slug}"`};
+    }
+    for (const file of ['plugin.js', 'config.js']) {
+        try {
+            await fs.access(path.join(dir, file));
+        } catch {
+            return {ok: false, reason: `missing required file ${file}`};
+        }
+    }
+    return {ok: true, manifest};
+}
+
 const failedLoads = [];
 
 /**
@@ -60,11 +95,45 @@ export function getPluginLoadFailures() {
  */
 const _loadedPlugins = {};
 
+/**
+ * Entitlement state per licensed plugin, as of the last registerPlugins().
+ * Reported by GET /api/plugins so the screen can explain an absence rather than
+ * simply not showing a plugin the operator knows they installed.
+ *
+ * @type {Object.<string, string>}
+ */
+const _entitlementStates = {};
+
+/** Entitlement states that still let a plugin load. Mirrors pluginEntitlement. */
+const ENTITLEMENT_LOADABLE = new Set(['valid', 'grace', 'support-ended', 'not-required']);
+
+/** @returns {Object.<string, string>} */
+export function getEntitlementStates() {
+    return {..._entitlementStates};
+}
+
 /**
  * Core plugins - always loaded regardless of plugins.json enabled state.
- * These are considered first-class CMS features, not optional add-ons.
+ * These are considered first-class CMS features, not optional add-ons: they
+ * ship with the CMS, cannot be switched off, and their sidebar entries file
+ * under Tools rather than Plugins.
+ *
+ * Being in here is the whole mechanism. `enabled` in plugins.json is ignored
+ * for these, so a site that had one switched off still gets it on the next
+ * start - which is the point of promoting one.
+ *
+ * It is also a waiting room rather than a destination, and as of 0.67.0 it is
+ * EMPTY. site-search sat here until search moved into the CMS proper, and
+ * analytics until it did the same - a feature nobody may switch off has no
+ * business being discovered, listed and toggled as though it were an add-on.
+ *
+ * Kept rather than deleted because the mechanism is the right one for the next
+ * promotion: a plugin lands here while its replacement is built, then leaves.
  */
-const CORE_PLUGINS = new Set(['analytics']);
+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); }
 
 /**
  * Scan the plugins/ directory and return all valid manifests.
@@ -187,6 +256,94 @@ export function savePluginState(name, state) {
     saveConfig('plugins', states);
 }
 
+/**
+ * Work out which plugins are pushed aside by others that are loading.
+ *
+ * A plugin declares `"supersedes": ["other-plugin"]` in its manifest when it
+ * replaces another outright - the Pro edition of something that also ships
+ * free, for instance. The superseded plugin then registers nothing at all: no
+ * routes, no sidebar item, no collections, so the admin shows one of the pair
+ * rather than two that do the same job.
+ *
+ * The claim lives on the REPLACEMENT, never on the plugin being replaced, so
+ * a bundled plugin needs no knowledge of the paid one that may one day
+ * displace it.
+ *
+ * ## This is computed every boot and never written to config/plugins.json
+ *
+ * Persisting it would be a trap. Licences are withdrawn by disabling a plugin
+ * and leaving its files in place, so if superseding had written the free
+ * plugin off as disabled, a customer whose licence lapsed would lose the
+ * replacement AND the thing it replaced, ending up worse off than someone who
+ * never paid. Deriving it at load time means the superseded plugin simply
+ * comes back on the next restart.
+ *
+ * @param   {object[]} manifests - every discovered manifest
+ * @param   {Set<string>} activeNames - names that would otherwise load
+ * @param   {{isCore?: (name: string) => boolean, warn?: (message: string) => void}} [options]
+ * @returns {Map<string, string>} superseded plugin name → the plugin displacing it
+ */
+export function resolveSupersessions(manifests, activeNames, options = {}) {
+    const {isCore = () => false, warn = () => {}} = options;
+    const byName = new Map(manifests.map(m => [m.name, m]));
+
+    // Collect the claims worth honouring, dropping the nonsensical ones loudly
+    // rather than silently - a manifest that claims the wrong thing is a
+    // packaging mistake, and a silent no-op makes it very hard to find.
+    const claims = new Map();
+    for (const manifest of manifests) {
+        if (!activeNames.has(manifest.name)) continue;
+        const targets = Array.isArray(manifest.supersedes) ? manifest.supersedes : [];
+        const kept = [];
+
+        for (const target of targets) {
+            if (target === manifest.name) {
+                warn(`"${manifest.name}" lists itself in supersedes - ignored.`);
+                continue;
+            }
+            if (!byName.has(target) || !activeNames.has(target)) continue;
+            if (isCore(target)) {
+                warn(`"${manifest.name}" cannot supersede core plugin "${target}" - ignored.`);
+                continue;
+            }
+            const rival = byName.get(target);
+            if (Array.isArray(rival.supersedes) && rival.supersedes.includes(manifest.name)) {
+                warn(`"${manifest.name}" and "${target}" each claim to supersede the other - neither is applied.`);
+                continue;
+            }
+            kept.push(target);
+        }
+
+        if (kept.length) claims.set(manifest.name, kept);
+    }
+
+    if (!claims.size) return new Map();
+
+    // A superseded plugin's own claims must stop counting, or A>B>C would
+    // leave C displaced by a B that is not itself loading. Recompute from
+    // scratch each pass until the answer stops changing.
+    let superseded = new Map();
+    for (let pass = 0; pass <= manifests.length; pass++) {
+        const next = new Map();
+        for (const [claimant, targets] of claims) {
+            if (superseded.has(claimant)) continue;
+            for (const target of targets) {
+                if (!next.has(target)) next.set(target, claimant);
+            }
+        }
+
+        const settled = next.size === superseded.size
+            && [...next].every(([name, by]) => superseded.get(name) === by);
+        superseded = next;
+        if (settled) return superseded;
+    }
+
+    // Only reachable via a supersede cycle longer than a mutual pair. Refusing
+    // to apply any of it keeps the outcome deterministic and visible.
+    warn('supersedes declarations form a cycle - none are applied.');
+    return new Map();
+}
+
 /**
  * Register server-side Fastify plugins for all enabled plugins.
  * Always loads plugin.js as the entry point.
@@ -198,11 +355,57 @@ export async function registerPlugins(fastify) {
     const manifests = await discoverPlugins();
     const states = getPluginStates();
 
+    // Entitlement is settled BEFORE supersession, not after, and the ordering is
+    // load-bearing. `email-pro` supersedes `mail-reader`; if an unentitled
+    // email-pro still counted as active it would displace mail-reader and then
+    // fail to load itself, leaving a customer whose licence lapsed with NEITHER -
+    // worse off than someone who never paid at all.
+    for (const manifest of manifests) {
+        if (manifest.closedSource !== true) continue;
+        const verdict = mayLoad(manifest);
+        _entitlementStates[manifest.name] = verdict.state;
+        if (!verdict.allowed) {
+            fastify.log.warn(`[plugins] "${manifest.name}" not loaded: ${verdict.state} (${verdict.reason})`);
+        } else if (verdict.state !== 'valid') {
+            fastify.log.info(`[plugins] "${manifest.name}": ${verdict.state} (${verdict.reason})`);
+        }
+    }
+    const entitled = (name) => _entitlementStates[name] === undefined
+        || ENTITLEMENT_LOADABLE.has(_entitlementStates[name]);
+
+    // Which plugins would load on their own account, before anything displaces
+    // one another.
+    const activeNames = new Set(
+        manifests
+            .filter(m => (states[m.name]?.enabled || CORE_PLUGINS.has(m.name)) && entitled(m.name))
+            .map(m => m.name)
+    );
+    const superseded = resolveSupersessions(manifests, activeNames, {
+        isCore: name => CORE_PLUGINS.has(name),
+        warn: message => fastify.log.warn(`[plugins] ${message}`)
+    });
+
     const loaded = [];
     for (const manifest of manifests) {
         const state = states[manifest.name] || {};
         if (!state.enabled && !CORE_PLUGINS.has(manifest.name)) continue;
 
+        const displacedBy = superseded.get(manifest.name);
+        if (displacedBy) {
+            // Recorded rather than merely skipped: the admin Plugins screen
+            // needs to say WHY this one is inactive, or the first thing anyone
+            // does is toggle it back on and watch nothing happen.
+            _loadedPlugins[manifest.name] = {enabled: false, publicEntry: null, supersededBy: displacedBy};
+            fastify.log.info(`[plugins] "${manifest.name}" superseded by "${displacedBy}" - not loaded.`);
+            continue;
+        }
+
+        // Already classified above, before supersession was resolved. A refusal
+        // is NOT written into plugins.json: a lapse recorded as stored state
+        // would mean a renewal could not simply restore it, the same reasoning
+        // resolveSupersessions() uses for a superseded plugin.
+        if (!entitled(manifest.name)) continue;
+
         const entryPath = path.join(PLUGINS_DIR, manifest.name, 'plugin.js');
         try {
             const { default: plugin } = await import(entryPath);
@@ -613,6 +816,98 @@ export async function runLifecycleHook(name, hook, fastify) {
  *
  * @returns {Promise<{ sidebar: object[], routes: object[], views: object, css: object[] }>}
  */
+/**
+ * The newest mtime anywhere under a directory of browser code.
+ *
+ * Browser code that is imported rather than routed has no version of its own
+ * - it is fetched under whatever token the importing entry carried. Folding
+ * the newest mtime of the whole tree into that token is what makes a change
+ * to an imported file actually reach a browser. It applies to the shared
+ * plugins/_lib/admin as much as to a plugin's own admin/lib, and missing
+ * either presents the same way: a fix that is on disk and not in the tab.
+ *
+ * @param   {string} root absolute path; a missing directory is not an error
+ * @returns {Promise<number>} epoch milliseconds, or 0 if there is nothing there
+ */
+async function newestAdminMtime(root) {
+    let newest = 0;
+
+    /**
+     * @param   {string} dir
+     * @returns {Promise<void>}
+     */
+    async function walk(dir) {
+        let entries;
+        try {
+            entries = await fs.readdir(dir, {withFileTypes: true});
+        } catch {
+            return;
+        }
+        for (const entry of entries) {
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                await walk(full);
+            } else {
+                try {
+                    newest = Math.max(newest, Math.floor((await fs.stat(full)).mtimeMs));
+                } catch { /* unreadable - ignore */ }
+            }
+        }
+    }
+
+    await walk(root);
+    return newest;
+}
+
+/**
+ * The licence line shown on a plugin's admin banner.
+ *
+ * A manifest may state it outright; otherwise it is derived, because every
+ * plugin needs a truthful answer here and almost none of them will ever carry
+ * the field. Closed source means it was bought, and the paid plugins are the
+ * ones already marked that way for the source-code guard - so the flag that
+ * protects the source also names the licence, rather than a second list
+ * someone has to remember to add to.
+ *
+ * @param   {object} manifest
+ * @returns {string}
+ */
+export function pluginLicence(manifest) {
+    const stated = manifest.licence || manifest.license;
+    if (typeof stated === 'string' && stated.trim()) return stated.trim();
+    if (CORE_PLUGINS.has(manifest.name)) return 'Built in';
+    if (manifest.closedSource) return 'Commercial licence';
+    return 'Included with Domma CMS';
+}
+
+/**
+ * The expiry shown beside the licence on a plugin's admin banner, or null.
+ *
+ * Only a licensed plugin has one, and what "expires" means depends on how it
+ * was bought (see pluginEntitlement.js): a rental STOPS at its end date, a
+ * perpetual licence never does and only its support lapses. The banner says
+ * which, because "Expires" on something bought outright would frighten a
+ * customer about a thing that is not going to happen.
+ *
+ * An owner wildcard, or a perpetual licence with no support date, has nothing
+ * to show and returns null rather than a chip with no date in it.
+ *
+ * @param   {object} manifest
+ * @param   {object|null} [given] - injectable for testing; read from disk when omitted
+ * @returns {{kind: 'rental'|'support', date: string, state: string}|null}
+ */
+export function pluginExpiry(manifest, given) {
+    if (manifest?.closedSource !== true) return null;
+    const {state, entitlement} = classifyEntitlement(manifest.name, given);
+    if (!entitlement || state === 'unlicensed') return null;
+    if (entitlement.model === 'rental') {
+        return entitlement.expiresAt ? {kind: 'rental', date: entitlement.expiresAt, state} : null;
+    }
+    return entitlement.supportExpiresAt
+        ? {kind: 'support', date: entitlement.supportExpiresAt, state}
+        : null;
+}
+
 export async function getAdminPluginConfig() {
     const manifests = await discoverPlugins();
     const states = getPluginStates();
@@ -621,6 +916,10 @@ export async function getAdminPluginConfig() {
     const routes = [];
     const views = {};
     const css = [];
+    // Per-view plugin identity, so the admin can put the same banner above
+    // every plugin screen without each plugin having to render one (and each
+    // rendering it differently, which is what it did before).
+    const meta = {};
 
     for (const manifest of manifests) {
         const state = states[manifest.name] || {};
@@ -629,27 +928,61 @@ export async function getAdminPluginConfig() {
         if (manifest.admin.sidebar) sidebar.push(...manifest.admin.sidebar);
         if (manifest.admin.routes) routes.push(...manifest.admin.routes);
 
-        // Auto-stamp view entries with mtime-based version (replaces manual ?v=N)
+        // Auto-stamp view entries with an mtime-based version.
+        //
+        // The stamp is the NEWEST mtime of the entry, the plugin's own admin
+        // tree and the shared admin library - not the entry alone. A view is
+        // usually a thin wrapper that rarely changes, while the code it
+        // imports changes constantly, so stamping only the entry left the
+        // browser fetching the same URL and serving the previous build of
+        // everything behind it. That presents as a feature that worked
+        // yesterday and does not today, on one machine.
+        // Once per plugin, not per view: it verifies a signature.
+        const expiry = pluginExpiry(manifest);
+        const sharedStamp = Math.max(
+            await newestAdminMtime(path.join(PLUGINS_DIR, '_lib', 'admin')),
+            await newestAdminMtime(path.join(PLUGINS_DIR, manifest.name, 'admin'))
+        );
         for (const [viewName, viewDef] of Object.entries(manifest.admin.views || {})) {
             const entryBase = viewDef.entry.split('?')[0];
             let stamped = viewDef.entry;
             try {
                 const filePath = path.join(PLUGINS_DIR, entryBase);
                 const s = await fs.stat(filePath);
-                stamped = `${entryBase}?v=${Math.floor(s.mtimeMs)}`;
+                stamped = `${entryBase}?v=${Math.max(Math.floor(s.mtimeMs), sharedStamp)}`;
             } catch { /* keep original entry as-is */ }
             views[viewName] = { ...viewDef, entry: stamped };
+            meta[viewName] = {
+                plugin:      manifest.name,
+                displayName: manifest.displayName || manifest.name,
+                version:     manifest.version || '1.0.0',
+                date:        manifest.date || '',
+                author:      manifest.author || '',
+                icon:        manifest.icon || 'package',
+                core:        CORE_PLUGINS.has(manifest.name),
+                licence:     pluginLicence(manifest),
+                expiry
+            };
         }
 
-        // Collect admin CSS links declared in plugin.json admin.css[]
+        // Collect admin CSS links declared in plugin.json admin.css[], stamped
+        // with the file's mtime for the same reason view entries are: a browser
+        // keys its cache on the full URL, so an unstamped stylesheet keeps
+        // serving the old rules after an update and the plugin looks broken in
+        // a way that only a hard refresh explains.
         for (let i = 0; i < (manifest.admin.css || []).length; i++) {
             const cssPath = manifest.admin.css[i];
+            let href = `/plugins/${manifest.name}/${cssPath}`;
+            try {
+                const stat = await fs.stat(path.join(PLUGINS_DIR, manifest.name, cssPath));
+                href += `?v=${Math.max(Math.floor(stat.mtimeMs), sharedStamp)}`;
+            } catch { /* unreadable - link it unstamped rather than not at all */ }
             css.push({
                 id: `plugin-${manifest.name}-css${i > 0 ? `-${i}` : ''}`,
-                href: `/plugins/${manifest.name}/${cssPath}`
+                href
             });
         }
     }
 
-    return { sidebar, routes, views, css };
+    return { sidebar, routes, views, css, meta };
 }