domma-cms 0.93.0 → 0.94.0

package/server/services/pluginGuides.js

@@ -0,0 +1,255 @@
+/**
+ * Plugin guides - user documentation a plugin ships for the admin's
+ * Documentation folder.
+ *
+ * A plugin puts Markdown files in `plugins/<name>/docs/*.md`. When the plugin
+ * is loaded (enabled, licensed, not superseded), each file becomes a page under
+ * Documentation > Plugins in the admin sidebar (`#/docs/plugins/<name>`), shown
+ * to users who can use the plugin: the manifest's `docs.permission`, else the
+ * permission on its first `admin.sidebar` entry that names one, else anyone
+ * signed in to the admin.
+ *
+ * Files are plain Markdown with optional frontmatter `title` (the tab label)
+ * and `order` (a number, lowest first; `guide.md` comes first by default).
+ * Shortcodes are NOT run - a guide shows `[collection ...]` examples literally,
+ * which is what a guide wants. The HTML is sanitised like any other page body.
+ *
+ * Pure helpers are exported for tests; the registry is module state filled once
+ * per boot by registerPluginGuides() (plugins load at boot only).
+ */
+import fs from 'fs/promises';
+import path from 'path';
+import matter from 'gray-matter';
+import {marked} from 'marked';
+import sanitizeHtml from 'sanitize-html';
+import {registerSidebarItem} from './hooks.js';
+
+/** The Documentation folder's key in the admin-sidebar menu. */
+export const DOCS_FOLDER_KEY = 'documentation';
+/** Identity (url) of the Plugins sub-folder and its landing page. */
+export const GUIDES_URL = '#/docs/plugins';
+
+const SLUG_RE = /^[a-z0-9][a-z0-9_-]*$/i;
+
+/** name -> {name, displayName, description, icon, version, permission, toolUrl, dir, pages: [{slug, title, order, file}]} */
+let _guides = new Map();
+
+/**
+ * Who may read a plugin's guides: `docs.permission`, else the first sidebar
+ * entry's permission, else null (anyone signed in to the admin).
+ *
+ * @param {object} manifest
+ * @returns {string|null}
+ */
+export function guidePermission(manifest) {
+    const explicit = manifest?.docs?.permission;
+    if (typeof explicit === 'string' && explicit.trim()) return explicit.trim();
+    const entry = (manifest?.admin?.sidebar || []).find(s => typeof s?.permission === 'string' && s.permission);
+    return entry ? entry.permission : null;
+}
+
+/**
+ * Does this permission list cover `resource`? Same rule as the sidebar's canAny:
+ * the bare resource or any of its actions.
+ *
+ * @param {string[]} permissions
+ * @param {string|null} resource
+ * @returns {boolean}
+ */
+export function canUse(permissions, resource) {
+    if (!resource) return true;
+    if (!Array.isArray(permissions) || !permissions.length) return false;
+    if (permissions.includes(resource)) return true;
+    return ['read', 'create', 'update', 'delete'].some(a => permissions.includes(`${resource}.${a}`));
+}
+
+/** "shipping-zones" -> "Shipping zones"; "guide" -> "Guide". */
+export function titleFromSlug(slug) {
+    const words = String(slug || '').replace(/^\d+[-_]/, '').replace(/[-_]+/g, ' ').trim();
+    return words ? words.charAt(0).toUpperCase() + words.slice(1) : 'Guide';
+}
+
+/**
+ * Parse one guide file's source into its page meta.
+ *
+ * @param {string} slug - file name without `.md`
+ * @param {string} source
+ * @returns {{slug: string, title: string, order: number}}
+ */
+export function pageMeta(slug, source) {
+    let data = {};
+    try { data = matter(source).data || {}; } catch { data = {}; }
+    const title = typeof data.title === 'string' && data.title.trim() ? data.title.trim() : titleFromSlug(slug);
+    const order = Number.isFinite(Number(data.order)) && data.order !== null && data.order !== ''
+        ? Number(data.order)
+        : (slug === 'guide' ? 0 : 100);
+    return {slug, title, order};
+}
+
+/** Pages sorted by order, then slug. */
+export function sortPages(pages) {
+    return [...pages].sort((a, b) => (a.order - b.order) || a.slug.localeCompare(b.slug));
+}
+
+const SANITIZE = {
+    allowedTags: [...sanitizeHtml.defaults.allowedTags, 'img', 'h1', 'h2', 'del', 'details', 'summary'],
+    allowedAttributes: {
+        a: ['href', 'title', 'target', 'rel'],
+        img: ['src', 'alt', 'title', 'width', 'height'],
+        code: ['class'],
+        table: ['class'],
+        th: ['align', 'style'],
+        td: ['align', 'style'],
+        ol: ['start']
+    },
+    allowedStyles: {th: {'text-align': [/^(left|right|center)$/]}, td: {'text-align': [/^(left|right|center)$/]}},
+    allowedSchemes: ['http', 'https', 'mailto'],
+    transformTags: {
+        // Links leaving the admin open in a new tab; hash links stay in the SPA.
+        a: (tagName, attribs) => {
+            const href = attribs.href || '';
+            if (/^https?:\/\//i.test(href)) return {tagName, attribs: {...attribs, target: '_blank', rel: 'noopener noreferrer'}};
+            return {tagName, attribs};
+        },
+        table: () => ({tagName: 'table', attribs: {class: 'table table-sm'}})
+    }
+};
+
+/**
+ * Markdown -> sanitised HTML. Frontmatter is dropped; shortcodes are not run.
+ *
+ * @param {string} source
+ * @returns {string}
+ */
+export function renderGuide(source) {
+    let body = source;
+    try { body = matter(source).content; } catch { /* no frontmatter */ }
+    return sanitizeHtml(marked.parse(body, {gfm: true, async: false}), SANITIZE);
+}
+
+/**
+ * Read a plugin's `docs/` folder into page metas. Missing folder = no pages.
+ *
+ * @param {string} pluginDir
+ * @returns {Promise<Array<{slug, title, order, file}>>}
+ */
+export async function readGuidePages(pluginDir) {
+    const dir = path.join(pluginDir, 'docs');
+    let names;
+    try { names = await fs.readdir(dir); } catch { return []; }
+    const pages = [];
+    for (const name of names) {
+        if (!name.toLowerCase().endsWith('.md')) continue;
+        const slug = name.slice(0, -3);
+        if (!SLUG_RE.test(slug)) continue;
+        const file = path.join(dir, name);
+        try {
+            const source = await fs.readFile(file, 'utf8');
+            pages.push({...pageMeta(slug, source), file});
+        } catch { /* unreadable - skip */ }
+    }
+    return sortPages(pages);
+}
+
+/**
+ * The sidebar node for Documentation > Plugins: a folder of one link per
+ * plugin, each gated by that plugin's permission (the renderer drops the ones
+ * a user cannot use).
+ *
+ * @param {Array<object>} guides - registry values
+ * @returns {object|null}
+ */
+export function guidesSidebarItem(guides) {
+    if (!guides.length) return null;
+    return {
+        source: 'Built in',
+        text: 'Plugins',
+        url: GUIDES_URL,
+        icon: 'package',
+        items: [...guides]
+            .sort((a, b) => a.displayName.localeCompare(b.displayName))
+            .map(g => ({
+                text: g.displayName,
+                url: `${GUIDES_URL}/${g.name}`,
+                icon: g.icon || 'package',
+                ...(g.permission && {permission: g.permission})
+            }))
+    };
+}
+
+/**
+ * Collect the guides of the plugins that loaded and add the sidebar folder.
+ * Called once at boot, after registerPlugins() has loaded them.
+ *
+ * @param {object[]} manifests - manifests of LOADED plugins
+ * @param {string} pluginsDir
+ * @param {{register?: Function}} [opts] - sidebar registration (tests pass a stub)
+ * @returns {Promise<number>} how many plugins have guides
+ */
+export async function registerPluginGuides(manifests, pluginsDir, {register = registerSidebarItem} = {}) {
+    const next = new Map();
+    for (const manifest of manifests || []) {
+        if (!manifest?.name) continue;
+        const dir = path.join(pluginsDir, manifest.name);
+        const pages = await readGuidePages(dir);
+        if (!pages.length) continue;
+        next.set(manifest.name, {
+            name: manifest.name,
+            displayName: manifest.displayName || manifest.name,
+            description: manifest.description || '',
+            icon: manifest.icon || 'package',
+            version: manifest.version || '',
+            tier: manifest.tier || '',
+            permission: guidePermission(manifest),
+            toolUrl: (manifest.admin?.sidebar || []).find(s => s?.url)?.url || null,
+            pages
+        });
+    }
+    _guides = next;
+    const item = guidesSidebarItem([...next.values()]);
+    if (item) register({folder: DOCS_FOLDER_KEY, item});
+    return next.size;
+}
+
+/** Public shape of a guide (no file paths). */
+function publicGuide(g) {
+    const {pages, ...rest} = g;
+    return {...rest, pages: pages.map(({slug, title}) => ({slug, title}))};
+}
+
+/**
+ * Every guide this permission list may read.
+ *
+ * @param {string[]} permissions
+ * @returns {object[]}
+ */
+export function listGuides(permissions) {
+    return [...(_guides.values())]
+        .filter(g => canUse(permissions, g.permission))
+        .sort((a, b) => a.displayName.localeCompare(b.displayName))
+        .map(publicGuide);
+}
+
+/**
+ * One guide with one page rendered, or a reason it cannot be shown.
+ *
+ * @param {string} name
+ * @param {string|undefined} pageSlug - defaults to the first page
+ * @param {string[]} permissions
+ * @returns {Promise<{status: 200|403|404, guide?: object}>}
+ */
+export async function getGuide(name, pageSlug, permissions) {
+    const g = _guides.get(name);
+    if (!g) return {status: 404};
+    if (!canUse(permissions, g.permission)) return {status: 403};
+    const page = pageSlug ? g.pages.find(p => p.slug === pageSlug) : g.pages[0];
+    if (!page) return {status: 404};
+    let source;
+    try { source = await fs.readFile(page.file, 'utf8'); } catch { return {status: 404}; }
+    return {status: 200, guide: {...publicGuide(g), page: {slug: page.slug, title: page.title, html: renderGuide(source)}}};
+}
+
+/** Test seam: replace the registry. */
+export function _setGuidesForTest(list) {
+    _guides = new Map((list || []).map(g => [g.name, g]));
+}

package/server/services/plugins.js

@@ -606,6 +606,14 @@ export async function registerPlugins(fastify) {
         }
     }
 
+    // User guides (docs/*.md) of the plugins that loaded, under Documentation > Plugins.
+    try {
+        const {registerPluginGuides} = await import('./pluginGuides.js');
+        await registerPluginGuides(manifests.filter(m => loaded.includes(m.name)), PLUGINS_DIR);
+    } catch (err) {
+        fastify.log.warn(`[plugins] Plugin guides skipped: ${err.message}`);
+    }
+
     if (loaded.length) {
         fastify.log.info(`[plugins] Loaded ${loaded.length} plugin${loaded.length === 1 ? '' : 's'}: ${loaded.join(', ')}`);
     } else {