domma-cms 0.17.0 → 0.21.0

package/server/services/menus-migration.js

@@ -0,0 +1,107 @@
+/**
+ * Menus auto-migration.
+ *
+ * Runs once on server boot. Idempotent — guarded by the existence of
+ * config/menu-locations.json. Converts:
+ *   - config/navigation.json → config/menus/main.json + locations.navbar
+ *     (brand moves into site.json.brand)
+ *   - site.json.footer.links → config/menus/footer.json + locations.footer-primary
+ *     (footer.copyright preserved)
+ * The originals are renamed to .bak for one release of read-fallback safety.
+ */
+import fs from 'fs/promises';
+import path from 'path';
+import {fileURLToPath} from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const DEFAULT_CONFIG_DIR = path.resolve(path.dirname(__filename), '..', '..', 'config');
+
+async function exists(p) {
+    try { await fs.access(p); return true; } catch { return false; }
+}
+
+async function readJson(p) {
+    const raw = await fs.readFile(p, 'utf8');
+    return JSON.parse(raw);
+}
+
+async function writeJson(p, data) {
+    await fs.writeFile(p, JSON.stringify(data, null, 2) + '\n', 'utf8');
+}
+
+/**
+ * Run the migration. Returns `{migrated: boolean, reason?: string}`.
+ *
+ * @param {{configDir?: string}} [opts]
+ */
+export async function runMigration(opts = {}) {
+    const configDir = opts.configDir || DEFAULT_CONFIG_DIR;
+
+    // 1. Guard
+    if (await exists(path.join(configDir, 'menu-locations.json'))) {
+        return {migrated: false, reason: 'menu-locations.json already present'};
+    }
+
+    const menusDir = path.join(configDir, 'menus');
+    await fs.mkdir(menusDir, {recursive: true});
+    const locations = {};
+    const now = new Date().toISOString();
+
+    // 2. navigation.json
+    const navPath = path.join(configDir, 'navigation.json');
+    if (await exists(navPath)) {
+        const nav = await readJson(navPath);
+        const mainMenu = {
+            slug:        'main',
+            name:        'Main navigation',
+            description: 'Migrated from config/navigation.json',
+            ...(nav.variant  != null && {variant:  nav.variant}),
+            ...(nav.position != null && {position: nav.position}),
+            ...(nav.style    != null && {style:    nav.style}),
+            items: Array.isArray(nav.items) ? nav.items : [],
+            meta:  {createdAt: now, updatedAt: now, bundled: false, presetOwner: null}
+        };
+        await writeJson(path.join(menusDir, 'main.json'), mainMenu);
+        locations.navbar = 'main';
+
+        if (nav.brand) {
+            const sitePath = path.join(configDir, 'site.json');
+            const site = (await exists(sitePath)) ? await readJson(sitePath) : {};
+            site.brand = nav.brand;
+            await writeJson(sitePath, site);
+        }
+
+        await fs.rename(navPath, navPath + '.bak');
+        console.log(`[menus] Migrated navigation.json → menus/main.json + locations.navbar`);
+    }
+
+    // 3. site.json footer.links
+    const sitePath = path.join(configDir, 'site.json');
+    if (await exists(sitePath)) {
+        const site = await readJson(sitePath);
+        const links = site.footer?.links;
+        if (Array.isArray(links) && links.length) {
+            const footerMenu = {
+                slug:        'footer',
+                name:        'Footer',
+                description: 'Migrated from site.json footer.links',
+                items: links.map(l => ({
+                    text: l.text || '',
+                    url:  l.url  || '/',
+                    ...(l.hidden && {hidden: true})
+                })),
+                meta: {createdAt: now, updatedAt: now, bundled: false, presetOwner: null}
+            };
+            await writeJson(path.join(menusDir, 'footer.json'), footerMenu);
+            locations['footer-primary'] = 'footer';
+            site.footer = {...site.footer, links: []};
+            await writeJson(sitePath, site);
+            console.log(`[menus] Migrated footer.links → menus/footer.json + locations.footer-primary`);
+        }
+    }
+
+    // 4. Write the locations map (even if empty — its existence is the migration guard)
+    await writeJson(path.join(configDir, 'menu-locations.json'), locations);
+
+    return {migrated: true};
+}

package/server/services/menus.js

@@ -0,0 +1,422 @@
+/**
+ * Menus service.
+ *
+ * Multi-menu storage backing the public navbar, footer, plugin-registered
+ * slots, and the `[menu]` shortcode. Each menu lives in its own JSON file
+ * under `config/menus/<slug>.json`. A slot → menu-slug map lives in
+ * `config/menu-locations.json`. The list of registered slots (a separate
+ * concept from the map) is held in process memory and seeded by core +
+ * plugin hooks at startup.
+ */
+import fs from 'fs/promises';
+import path from 'path';
+import {fileURLToPath} from 'url';
+import {checkVisibility} from '../middleware/auth.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname  = path.dirname(__filename);
+
+/** Project root config directory. */
+const CONFIG_DIR = path.resolve(__dirname, '..', '..', 'config');
+
+/** Per-menu files live here. */
+export const MENUS_DIR = path.join(CONFIG_DIR, 'menus');
+
+/** Slot → menu-slug map. */
+export const LOCATIONS_FILE = path.join(CONFIG_DIR, 'menu-locations.json');
+
+const SLUG_RE = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/;
+
+/**
+ * Validate a slug (used for both menu slugs and location slot names).
+ *
+ * @param {unknown} slug
+ * @returns {boolean}
+ */
+export function validateSlug(slug) {
+    return typeof slug === 'string' && SLUG_RE.test(slug);
+}
+
+/**
+ * Ensure MENUS_DIR exists. Safe to call repeatedly.
+ *
+ * @returns {Promise<void>}
+ */
+export async function ensureMenusDir() {
+    await fs.mkdir(MENUS_DIR, {recursive: true});
+}
+
+function menuPath(slug) {
+    return path.join(MENUS_DIR, `${slug}.json`);
+}
+
+async function readMenuFile(slug) {
+    const raw = await fs.readFile(menuPath(slug), 'utf8');
+    return JSON.parse(raw);
+}
+
+async function writeMenuFile(menu) {
+    await ensureMenusDir();
+    await fs.writeFile(menuPath(menu.slug), JSON.stringify(menu, null, 2) + '\n', 'utf8');
+}
+
+/**
+ * List all menus. Returns metadata only (no items) — use getMenu(slug) for
+ * the full payload. Sorted alphabetically by slug.
+ *
+ * @returns {Promise<Array<{slug:string,name:string,description:string,itemsCount:number,meta:object}>>}
+ * @throws  {Error} if the menus directory cannot be read for reasons other than ENOENT
+ */
+export async function listMenus() {
+    await ensureMenusDir();
+    const entries = await fs.readdir(MENUS_DIR);
+    const out = [];
+    for (const file of entries) {
+        if (!file.endsWith('.json')) continue;
+        const slug = file.slice(0, -5);
+        if (!validateSlug(slug)) continue;
+        try {
+            const menu = await readMenuFile(slug);
+            out.push({
+                slug:        menu.slug || slug,
+                name:        menu.name || '',
+                description: menu.description || '',
+                itemsCount:  Array.isArray(menu.items) ? menu.items.length : 0,
+                meta:        menu.meta || {}
+            });
+        } catch (err) {
+            console.warn(`[menus] Skipping malformed menu "${slug}": ${err.message}`);
+        }
+    }
+    return out.sort((a, b) => a.slug.localeCompare(b.slug));
+}
+
+/**
+ * Read a full menu by slug. Returns null if missing or slug is invalid.
+ *
+ * @param   {string} slug
+ * @returns {Promise<object|null>}
+ * @throws  {Error} if the file exists but cannot be read for reasons other than ENOENT
+ */
+export async function getMenu(slug) {
+    if (!validateSlug(slug)) return null;
+    try {
+        return await readMenuFile(slug);
+    } catch (err) {
+        if (err.code === 'ENOENT') return null;
+        throw err;
+    }
+}
+
+/**
+ * Create a new menu. Refuses on slug collision.
+ *
+ * @param   {object} input - { slug, name, description?, variant?, position?, style?, items, meta? }
+ * @returns {Promise<object>} the persisted menu
+ * @throws  {Error} if the slug is invalid or already exists
+ */
+export async function createMenu(input) {
+    if (!validateSlug(input?.slug)) {
+        throw new Error(`Invalid menu slug: ${input?.slug}`);
+    }
+    if (await getMenu(input.slug)) {
+        throw new Error(`Menu "${input.slug}" already exists`);
+    }
+    const errors = validateMenu(input);
+    if (errors.length) {
+        throw new Error('Validation failed: ' + errors.join('; '));
+    }
+    const now = new Date().toISOString();
+    const menu = {
+        slug:        input.slug,
+        name:        input.name || input.slug,
+        description: input.description || '',
+        ...(input.variant  != null && {variant:  input.variant}),
+        ...(input.position != null && {position: input.position}),
+        ...(input.style    != null && {style:    input.style}),
+        items: Array.isArray(input.items) ? input.items : [],
+        meta: {
+            createdAt:   now,
+            updatedAt:   now,
+            bundled:     Boolean(input.meta?.bundled),
+            presetOwner: input.meta?.presetOwner || null,
+            ...(input.meta?.project != null && {project: input.meta.project})
+        }
+    };
+    await writeMenuFile(menu);
+    return menu;
+}
+
+/**
+ * Replace an existing menu. Preserves meta.createdAt; updates meta.updatedAt.
+ * The slug in the path wins over any slug in the body.
+ *
+ * @param   {string} slug
+ * @param   {object} input
+ * @returns {Promise<object>} the persisted menu
+ * @throws  {Error} if the menu does not exist
+ */
+export async function updateMenu(slug, input) {
+    const existing = await getMenu(slug);
+    if (!existing) throw new Error(`Menu "${slug}" not found`);
+    const errors = validateMenu({...input, slug});
+    if (errors.length) {
+        throw new Error('Validation failed: ' + errors.join('; '));
+    }
+    const now = new Date().toISOString();
+    const merged = {
+        slug,
+        name:        input.name        || existing.name,
+        description: input.description || '',
+        ...(input.variant  != null && {variant:  input.variant}),
+        ...(input.position != null && {position: input.position}),
+        ...(input.style    != null && {style:    input.style}),
+        items: Array.isArray(input.items) ? input.items : [],
+        meta: {
+            ...existing.meta,
+            ...(input.meta || {}),
+            createdAt: existing.meta?.createdAt || now,
+            updatedAt: now
+        }
+    };
+    await writeMenuFile(merged);
+    return merged;
+}
+
+/**
+ * Delete a menu file. Returns true if removed, false if it didn't exist.
+ * Callers must check the locations map first — service does not.
+ *
+ * @param   {string} slug
+ * @returns {Promise<boolean>}
+ * @throws  {Error} if the file exists but cannot be removed for reasons other than ENOENT
+ */
+export async function deleteMenu(slug) {
+    if (!validateSlug(slug)) return false;
+    try {
+        await fs.unlink(menuPath(slug));
+        return true;
+    } catch (err) {
+        if (err.code === 'ENOENT') return false;
+        throw err;
+    }
+}
+
+/**
+ * Duplicate a menu as <slug>-copy, falling back to -copy-2, -copy-3, … if
+ * needed. The duplicate's name is suffixed with " (copy)" for clarity.
+ *
+ * @param   {string} slug
+ * @returns {Promise<object>} the new menu
+ * @throws  {Error} if the source menu does not exist
+ */
+export async function duplicateMenu(slug) {
+    const source = await getMenu(slug);
+    if (!source) throw new Error(`Menu "${slug}" not found`);
+    let candidate = slug + '-copy';
+    let n = 2;
+    while (await getMenu(candidate)) {
+        candidate = slug + '-copy-' + n++;
+    }
+    return createMenu({
+        ...source,
+        slug: candidate,
+        name: source.name + ' (copy)',
+        meta: {bundled: false, presetOwner: null}
+    });
+}
+
+const POSITIONS = new Set(['sticky', 'fixed', 'static', 'floating']);
+const URL_PREFIX_RE = /^(\/|#|https?:\/\/|mailto:)/;
+
+/**
+ * Validate a menu object. Returns an array of human-readable error strings
+ * (empty on success). Performs structural + per-item recursive checks; does
+ * NOT validate visibility role names (those are checked at render time).
+ *
+ * @param {object} menu
+ * @returns {string[]}
+ */
+export function validateMenu(menu) {
+    const errors = [];
+    if (!menu || typeof menu !== 'object') return ['Menu must be an object'];
+    if (!validateSlug(menu.slug)) {
+        errors.push(`Invalid slug "${menu.slug}" — lowercase alphanumeric + hyphen only`);
+    }
+    if (!menu.name || typeof menu.name !== 'string') {
+        errors.push('name is required');
+    }
+    if (menu.position != null && !POSITIONS.has(menu.position)) {
+        errors.push(`Invalid position "${menu.position}" — expected one of: ${[...POSITIONS].join(', ')}`);
+    }
+    if (!Array.isArray(menu.items)) {
+        errors.push('items must be an array');
+    } else {
+        walkItems(menu.items, (item, path) => {
+            if (!item.text || typeof item.text !== 'string') {
+                errors.push(`Item ${path}: text is required`);
+            }
+            // url is only required for LEAF items (no children). Folder items
+            // — those with their own `items` array — are pure groupings and
+            // don't need a navigation target. The admin sidebar uses this
+            // shape extensively (Content / Data / System headings etc.).
+            const hasChildren = Array.isArray(item.items) && item.items.length > 0;
+            if (!hasChildren) {
+                if (!item.url || typeof item.url !== 'string' || !URL_PREFIX_RE.test(item.url)) {
+                    errors.push(`Item ${path}: url must start with /, #, http(s)://, or mailto:`);
+                }
+            } else if (item.url != null && item.url !== '' && (typeof item.url !== 'string' || !URL_PREFIX_RE.test(item.url))) {
+                // Folder items MAY have a URL (clickable parent); if present it must still be well-formed.
+                errors.push(`Item ${path}: url must start with /, #, http(s)://, or mailto:`);
+            }
+            if (item.items != null && !Array.isArray(item.items)) {
+                errors.push(`Item ${path}: items must be an array if present`);
+            }
+        });
+    }
+    return errors;
+}
+
+function walkItems(items, fn, parentPath = '') {
+    items.forEach((item, idx) => {
+        const itemPath = parentPath ? `${parentPath}.${idx}` : String(idx);
+        if (item == null || typeof item !== 'object') {
+            // Surface a structural error rather than crashing on a malformed entry.
+            fn({}, itemPath);
+            return;
+        }
+        fn(item, itemPath);
+        if (Array.isArray(item.items)) walkItems(item.items, fn, itemPath);
+    });
+}
+
+// ---------------------------------------------------------------------------
+// Locations registry — module-level Map, seeded by core, extended by plugins
+// ---------------------------------------------------------------------------
+
+const _locationRegistry = new Map(); // slot -> { label, description, maxDepth, source }
+
+/**
+ * Register a slot where a menu can be rendered. Re-registering an existing
+ * slot logs a warning and the second registration wins (last-write).
+ *
+ * @param  {string} slot
+ * @param  {{label:string, description?:string, maxDepth?:number, source?:string}} def
+ * @throws {Error} if the slot name fails validateSlug
+ */
+export function registerLocation(slot, def) {
+    if (!validateSlug(slot)) throw new Error(`Invalid slot name: ${slot}`);
+    if (_locationRegistry.has(slot)) {
+        console.warn(`[menus] Slot "${slot}" re-registered — last write wins`);
+    }
+    _locationRegistry.set(slot, {
+        label:       def?.label       || slot,
+        description: def?.description || '',
+        maxDepth:    Number.isFinite(def?.maxDepth) ? def.maxDepth : null,
+        source:      def?.source      || 'core'
+    });
+}
+
+/**
+ * @returns {Array<{slot:string, label:string, description:string, maxDepth:number|null, source:string}>}
+ */
+export function getLocationRegistry() {
+    return [..._locationRegistry.entries()].map(([slot, def]) => ({slot, ...def}));
+}
+
+// Core slots — registered at module load. Plugins register theirs from
+// their plugin.js setup function via the registerMenuLocation hook (Task 7).
+registerLocation('navbar',         {label: 'Navbar',         description: 'Site navbar', source: 'core'});
+registerLocation('footer-primary', {label: 'Footer primary', description: 'Primary footer column', source: 'core', maxDepth: 1});
+registerLocation('footer-legal',   {label: 'Footer legal',   description: 'Legal/secondary footer column', source: 'core', maxDepth: 1});
+registerLocation('admin-sidebar',  {label: 'Admin sidebar',  description: 'The left-side navigation in the admin panel', source: 'core', maxDepth: null});
+
+// ---------------------------------------------------------------------------
+// Slot → menu-slug map
+// ---------------------------------------------------------------------------
+
+/**
+ * Read the slot → menu-slug map from disk. Returns an empty object when the
+ * file doesn't exist or is malformed (logged as a warning).
+ *
+ * @returns {Promise<Record<string,string>>}
+ */
+export async function getLocations() {
+    try {
+        const raw = await fs.readFile(LOCATIONS_FILE, 'utf8');
+        return JSON.parse(raw);
+    } catch (err) {
+        if (err.code === 'ENOENT') return {};
+        console.warn(`[menus] menu-locations.json unreadable: ${err.message}`);
+        return {};
+    }
+}
+
+/**
+ * Replace the slot map. Validates that every slot is registered and every
+ * menu slug resolves to a real menu file.
+ *
+ * @param  {Record<string,string>} map
+ * @throws {Error} if the map is not a plain object, contains an unregistered slot, or references a missing menu
+ */
+export async function setLocations(map) {
+    if (!map || typeof map !== 'object' || Array.isArray(map)) {
+        throw new Error('Locations map must be a plain object');
+    }
+    for (const slot of Object.keys(map)) {
+        if (!_locationRegistry.has(slot)) {
+            throw new Error(`Slot "${slot}" is not registered`);
+        }
+        const slug = map[slot];
+        if (slug != null && slug !== '' && !(await getMenu(slug))) {
+            throw new Error(`Menu "${slug}" not found for slot "${slot}"`);
+        }
+    }
+    await fs.writeFile(LOCATIONS_FILE, JSON.stringify(map, null, 2) + '\n', 'utf8');
+}
+
+// ---------------------------------------------------------------------------
+// Render-time resolution
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve the menu mapped to `slot` for `user`, with items filtered by
+ * `hidden` (always dropped) and `visibility` (per-user role gating).
+ * Returns null if the slot is unmapped or the mapped menu is missing.
+ *
+ * Note: `user` may be null (anonymous). `user.role` and
+ * `user.additionalRoles` are honoured via `checkVisibility`.
+ *
+ * @param {string} slot
+ * @param {object|null} user
+ * @returns {Promise<object|null>}
+ */
+export async function resolveLocation(slot, user) {
+    const map = await getLocations();
+    const slug = map[slot];
+    if (!slug) return null;
+    const menu = await getMenu(slug);
+    if (!menu) {
+        console.warn(`[menus] Slot "${slot}" maps to "${slug}" which doesn't exist`);
+        return null;
+    }
+    return {
+        ...menu,
+        items: filterItemsForUser(menu.items || [], user)
+    };
+}
+
+function filterItemsForUser(items, user) {
+    const out = [];
+    for (const item of items) {
+        if (item.hidden) continue;
+        if (item.visibility != null) {
+            if (!checkVisibility(user, item.visibility)) continue;
+        }
+        const children = Array.isArray(item.items)
+            ? filterItemsForUser(item.items, user)
+            : [];
+        out.push({...item, items: children});
+    }
+    return out;
+}

package/server/services/permissionRegistry.js

@@ -74,6 +74,32 @@ export const REGISTRY = [
             {key: 'delete', label: 'Delete', description: 'Remove menu items'}
         ]
     },
+    {
+        key: 'menus',
+        label: 'Menus',
+        description: 'Manage menus and the slots they render into.',
+        icon: 'menu',
+        group: 'Structure',
+        actions: [
+            {key: 'read',   label: 'View',   description: 'View menus and locations'},
+            {key: 'create', label: 'Create', description: 'Create new menus'},
+            {key: 'update', label: 'Edit',   description: 'Edit menus and the slot map'},
+            {key: 'delete', label: 'Delete', description: 'Delete menus'}
+        ]
+    },
+    {
+        key: 'projects',
+        label: 'Projects',
+        description: 'Group related artefacts under named projects.',
+        icon: 'folder',
+        group: 'Structure',
+        actions: [
+            {key: 'read',   label: 'View',   description: 'View projects and their artefacts'},
+            {key: 'create', label: 'Create', description: 'Create new projects'},
+            {key: 'update', label: 'Edit',   description: 'Edit projects and tag/untag artefacts'},
+            {key: 'delete', label: 'Delete', description: 'Delete projects (refused if any artefacts tagged)'}
+        ]
+    },
     {
         key: 'layouts',
         label: 'Layouts',

package/server/services/plugins.js

@@ -15,7 +15,14 @@ import path from 'path';
 import matter from 'gray-matter';
 import {getConfig, saveConfig} from '../config.js';
 import {authenticate, requireAdmin, requireRole, requireVisibility} from '../middleware/auth.js';
-import {hooks, registerSanitizeRules, registerShortcode, registerTransform} from './hooks.js';
+import {
+    hooks,
+    registerMenuLocation,
+    registerSanitizeRules,
+    registerShortcode,
+    registerSidebarItem,
+    registerTransform
+} from './hooks.js';
 import {registerPluginResource, unregisterPluginResourcesByPlugin} from './permissionRegistry.js';
 import {createCollection, getCollection} from './collections.js';
 
@@ -204,7 +211,7 @@ export async function registerPlugins(fastify) {
           await fastify.register(plugin, {
             prefix,
             auth: {authenticate, requireRole, requireAdmin, requireVisibility},
-              hooks: {registerShortcode, registerSanitizeRules, registerTransform, on: hooks.on.bind(hooks)},
+              hooks: {registerShortcode, registerSanitizeRules, registerTransform, registerMenuLocation, registerSidebarItem, on: hooks.on.bind(hooks)},
               settings,
               config: {}
           });

package/server/services/presetCollections.js

@@ -37,6 +37,28 @@ const PRESETS = [
             delete: {enabled: false, access: 'admin'}
         }
     }
+    ,
+    {
+        slug: 'projects',
+        title: 'Projects',
+        description: 'Named groupings of related artefacts.',
+        preset: true,
+        systemManaged: true,
+        fields: [
+            {name: 'slug',        label: 'Slug',        type: 'text',     required: true},
+            {name: 'name',        label: 'Name',        type: 'text',     required: true},
+            {name: 'description', label: 'Description', type: 'textarea'},
+            {name: 'icon',        label: 'Icon',        type: 'text',     default: 'folder'},
+            {name: 'rootUrl',     label: 'Root URL',    type: 'text'},
+            {name: 'sortOrder',   label: 'Sort Order',  type: 'number',   default: 0}
+        ],
+        api: {
+            create: {enabled: false, access: 'admin'},
+            read:   {enabled: false, access: 'admin'},
+            update: {enabled: false, access: 'admin'},
+            delete: {enabled: false, access: 'admin'}
+        }
+    }
 ];
 
 /** Slugs exported for use in adapterRegistry and the delete guard. */