domma-cms 0.17.0 → 0.21.0

package/server/services/scaffolder.js

@@ -0,0 +1,465 @@
+/**
+ * Scaffolder — one-shot creator for a working CRUD system from a recipe.
+ *
+ * A "recipe" is a JSON file under `server/services/recipes/` that describes:
+ *   - one Collection (schema + initial api access rules)
+ *   - one Form (fields + submit settings)
+ *   - zero or more Actions (with optional transition + access config)
+ *   - an optional Markdown snippet to insert into the calling page
+ *
+ * The recipe declares a set of `options` whose `default` values can be
+ * overridden by the caller (e.g. to change a slug). Token substitution
+ * (`{{collectionSlug}}` style) is applied across the whole recipe AFTER the
+ * options are merged, so a single user choice flows into every slug, title,
+ * and template variable.
+ *
+ * Atomicity: pre-flight check refuses to start if ANY target slug already
+ * exists — keeps the user out of a partial-create state. If pre-flight passes
+ * we apply collection → form → actions in order. Action creation requires
+ * MongoDB (Pro feature); when not configured we still complete the
+ * collection + form and report actions as skipped with a warning.
+ */
+import fs from 'fs/promises';
+import path from 'path';
+import {fileURLToPath} from 'url';
+import {createCollection, getCollection} from './collections.js';
+import {readForm, slugify, writeForm} from './forms.js';
+import {createAction, getAction} from './actions.js';
+import {createRole, getRoleMap} from './roles.js';
+import {createUser, getUserByEmail} from './users.js';
+import {
+    createMenu as createMenuFile,
+    getLocations as getMenuLocations,
+    getMenu as getMenuFile,
+    setLocations as setMenuLocations
+} from './menus.js';
+import {createProject, getProject} from './projects.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const RECIPES_DIR = path.join(path.dirname(__filename), 'recipes');
+
+/**
+ * List all bundled recipes.
+ *
+ * @returns {Promise<Array<{slug:string,name:string,description:string,icon:string,options:object[]}>>}
+ */
+export async function listRecipes() {
+    let entries;
+    try {
+        entries = await fs.readdir(RECIPES_DIR);
+    } catch {
+        return [];
+    }
+
+    const recipes = [];
+    for (const entry of entries.filter(e => e.endsWith('.json'))) {
+        try {
+            const raw = await fs.readFile(path.join(RECIPES_DIR, entry), 'utf8');
+            const r   = JSON.parse(raw);
+            recipes.push({
+                slug:        r.slug,
+                name:        r.name,
+                description: r.description,
+                icon:        r.icon || 'box',
+                options:     r.options || []
+            });
+        } catch {
+            /* skip malformed recipe — don't break the listing */
+        }
+    }
+    return recipes;
+}
+
+/**
+ * Read a single recipe by slug.
+ *
+ * @param {string} slug
+ * @returns {Promise<object|null>}
+ */
+export async function getRecipe(slug) {
+    const safe = String(slug || '').replace(/[^a-z0-9-]/gi, '');
+    if (!safe) return null;
+    try {
+        const raw = await fs.readFile(path.join(RECIPES_DIR, `${safe}.json`), 'utf8');
+        return JSON.parse(raw);
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Recursively walk a value and replace `{{tokenName}}` placeholders inside
+ * any strings with values from `tokens`. Non-string leaves pass through
+ * unchanged. Arrays and plain objects are walked into; other object types
+ * (Date, Buffer, etc.) are returned as-is.
+ *
+ * @param {unknown} value
+ * @param {Record<string,string>} tokens
+ * @returns {unknown}
+ */
+function substituteTokens(value, tokens) {
+    if (typeof value === 'string') {
+        return value.replace(/\{\{\s*([A-Za-z0-9_]+)\s*\}\}/g, (_m, key) => {
+            // Leave action template variables (entry.*, user.*, now, env.*) untouched
+            // — those are resolved at action execution time, not at scaffold time.
+            if (key.includes('.') || key === 'now') return _m;
+            if (key === 'entry' || key === 'user' || key === 'env') return _m;
+            return tokens[key] != null ? String(tokens[key]) : _m;
+        });
+    }
+    if (Array.isArray(value)) return value.map(v => substituteTokens(v, tokens));
+    if (value && typeof value === 'object' && value.constructor === Object) {
+        const out = {};
+        for (const [k, v] of Object.entries(value)) out[k] = substituteTokens(v, tokens);
+        return out;
+    }
+    return value;
+}
+
+/**
+ * Resolve effective options for a recipe — recipe defaults merged with caller
+ * overrides, with non-empty user values winning. Returns a plain `{ name: value }`
+ * map suitable to pass to `substituteTokens`.
+ *
+ * **Default-chaining**: an option's `default` may template-reference earlier
+ * options via `{{otherOption}}`. This is the "namespacing" affordance — set
+ * one `namespace` option and let `collectionSlug`, `formSlug`, `actionPrefix`
+ * default to `{{namespace}}`, `{{namespace}}-form`, `{{namespace}}` etc. The
+ * recipe author chooses which options participate; users can still override
+ * any individual option to break the chain.
+ *
+ * Resolution is left-to-right over the options array — so the option being
+ * referenced MUST appear earlier in the array than the option that references
+ * it. (If forward references become a recurring need we can topologically
+ * sort, but the explicit-order rule keeps recipe files readable.)
+ *
+ * @param {object} recipe
+ * @param {object} userOverrides
+ * @returns {Record<string,string>}
+ */
+function resolveOptions(recipe, userOverrides = {}) {
+    const tokens = {};
+    for (const opt of (recipe.options || [])) {
+        const v = userOverrides?.[opt.name];
+        if (v != null && String(v).trim() !== '') {
+            tokens[opt.name] = slugify(String(v));
+            continue;
+        }
+        const def = String(opt.default ?? '');
+        // Substitute already-resolved tokens inside the default. Unresolved
+        // references (typo, forward ref) pass through unchanged so the author
+        // sees the placeholder text and can fix the recipe.
+        tokens[opt.name] = def.replace(/\{\{\s*([A-Za-z0-9_]+)\s*\}\}/g, (m, key) => {
+            return tokens[key] != null ? String(tokens[key]) : m;
+        });
+    }
+    return tokens;
+}
+
+/**
+ * Check whether anything the recipe wants to create already exists. Returns a
+ * list of human-readable conflict descriptions; empty array means clear.
+ *
+ * Action conflict checks are skipped silently when MongoDB isn't configured —
+ * the apply phase will degrade those into warnings rather than blocking.
+ *
+ * @param {object} resolvedRecipe
+ * @returns {Promise<string[]>}
+ */
+async function preflight(resolvedRecipe) {
+    const conflicts = [];
+
+    const colSlug = resolvedRecipe.collection?.slug || resolvedRecipe._collectionSlug;
+    if (colSlug && await getCollection(colSlug)) {
+        conflicts.push(`Collection "${colSlug}" already exists`);
+    }
+
+    const formSlug = resolvedRecipe._formSlug;
+    if (formSlug) {
+        try {
+            await readForm(formSlug);
+            conflicts.push(`Form "${formSlug}" already exists`);
+        } catch { /* not found = OK */ }
+    }
+
+    for (const action of (resolvedRecipe.actions || [])) {
+        if (!action.slug) continue;
+        try {
+            const existing = await getAction(action.slug);
+            if (existing) conflicts.push(`Action "${action.slug}" already exists`);
+        } catch {
+            // Mongo unavailable — treat as not-conflicting; the apply step
+            // will report actions as skipped instead.
+        }
+    }
+
+    // Roles + users are NOT treated as pre-flight conflicts — they're a
+    // looser kind of resource that frequently already exists (re-running a
+    // recipe, admin-created role, etc.) and where overwriting would lose
+    // data the user cares about (existing role's permissions tweaks, user's
+    // password). The apply step handles them with skip-with-warning instead,
+    // so the rest of the recipe can still land cleanly.
+
+    for (const menu of (resolvedRecipe.menus || [])) {
+        if (!menu.slug) continue;
+        if (await getMenuFile(menu.slug)) {
+            conflicts.push(`Menu "${menu.slug}" already exists`);
+        }
+    }
+
+    return conflicts;
+}
+
+/**
+ * Apply a recipe. Returns a summary describing what got created (or skipped),
+ * plus any non-fatal warnings.
+ *
+ * @param {string} recipeSlug
+ * @param {object} [opts]
+ * @param {object}  [opts.options]   - User overrides for recipe options (slug renames etc.)
+ * @param {string}  [opts.createdBy] - User id stamped onto created action records
+ * @returns {Promise<{created:object, skipped:string[], warnings:string[], snippet:string|null}>}
+ * @throws {Error} If a target slug already exists (pre-flight conflict)
+ */
+export async function applyRecipe(recipeSlug, opts = {}) {
+    const recipe = await getRecipe(recipeSlug);
+    if (!recipe) throw new Error(`Recipe "${recipeSlug}" not found`);
+
+    const tokens = resolveOptions(recipe, opts.options || {});
+    const resolved = substituteTokens(recipe, tokens);
+
+    // Carry the resolved slugs as sidecar fields so preflight + apply don't
+    // have to re-derive them from the (now also substituted) snippet text.
+    resolved._collectionSlug = tokens.collectionSlug;
+    resolved._formSlug       = tokens.formSlug;
+
+    // Wire form → collection so submissions land in the right place
+    if (resolved.form) {
+        resolved.form.slug = tokens.formSlug;
+        if (resolved.form.actions?.collection?.enabled) {
+            resolved.form.actions.collection.slug = tokens.collectionSlug;
+        }
+        // If the recipe wired an actionSlug template into form settings, ensure
+        // it points to a real action slug from this scaffold (no dangling refs).
+        if (resolved.form.settings?.actionSlug) {
+            const targetExists = (resolved.actions || []).some(a => a.slug === resolved.form.settings.actionSlug);
+            if (!targetExists) resolved.form.settings.actionSlug = '';
+        }
+    }
+
+    // Project — auto-create if the recipe declares one and it doesn't exist.
+    // Uses the recipe's `namespace` token as the project slug, so a single user
+    // choice ties together every artefact's `meta.project` tag below.
+    let projectSlug = null;
+    if (resolved.project) {
+        projectSlug = tokens.namespace;
+        if (projectSlug && !(await getProject(projectSlug))) {
+            try {
+                await createProject({
+                    slug:        projectSlug,
+                    name:        resolved.project.name        || projectSlug,
+                    description: resolved.project.description || '',
+                    icon:        resolved.project.icon        || 'folder',
+                    ...(resolved.project.rootUrl != null && {rootUrl: resolved.project.rootUrl}),
+                    ...(Number.isFinite(resolved.project.sortOrder) && {sortOrder: resolved.project.sortOrder})
+                });
+            } catch (err) {
+                const e = new Error(`Cannot create project "${projectSlug}": ${err.message}`);
+                e.statusCode = 400;
+                throw e;
+            }
+        }
+    }
+
+    const conflicts = await preflight(resolved);
+    if (conflicts.length) {
+        const err = new Error(`Cannot apply recipe — conflicts:\n  - ${conflicts.join('\n  - ')}`);
+        err.statusCode = 409;
+        err.conflicts  = conflicts;
+        throw err;
+    }
+
+    const created  = { collection: null, form: null, actions: [], roles: [], users: [], menus: [] };
+    const skipped  = [];
+    const warnings = [];
+
+    // 0. Roles — create FIRST so subsequent actions can reference them by name.
+    // If a role with the same name already exists (re-run, admin-created),
+    // we skip silently rather than failing — the role's existence is what
+    // matters for the actions that reference it, not who created it.
+    const existingRoles = getRoleMap();
+    for (const role of (resolved.roles || [])) {
+        if (!role.name) continue;
+        if (existingRoles.has(role.name)) {
+            skipped.push(`role:${role.name}`);
+            warnings.push(`Role "${role.name}" already exists — using existing definition (recipe-defined permissions not applied)`);
+            continue;
+        }
+        try {
+            await createRole({
+                name:        role.name,
+                label:       role.label || role.name,
+                level:       Number.isFinite(role.level) ? role.level : 5,
+                permissions: Array.isArray(role.permissions) ? role.permissions : [],
+                badgeClass:  role.badgeClass || 'badge-secondary',
+                ...(projectSlug && {meta: {project: projectSlug}})
+            });
+            created.roles.push(role.name);
+        } catch (err) {
+            warnings.push(`Role "${role.name}" failed: ${err.message}`);
+        }
+    }
+
+    // 0b. Menus — write each declared menu and, if requested, map it to a slot.
+    for (const menu of (resolved.menus || [])) {
+        if (!menu.slug) continue;
+        try {
+            await createMenuFile({
+                slug:        menu.slug,
+                name:        menu.name || menu.slug,
+                description: menu.description || '',
+                ...(menu.variant  != null && {variant:  menu.variant}),
+                ...(menu.position != null && {position: menu.position}),
+                ...(menu.style    != null && {style:    menu.style}),
+                items: Array.isArray(menu.items) ? menu.items : [],
+                meta:  {bundled: true, presetOwner: recipeSlug, ...(projectSlug && {project: projectSlug})}
+            });
+            created.menus.push(menu.slug);
+
+            if (Array.isArray(menu.locations) && menu.locations.length) {
+                const map = await getMenuLocations();
+                let touched = false;
+                for (const slot of menu.locations) {
+                    if (map[slot] && map[slot] !== menu.slug && !menu.force) {
+                        warnings.push(`Slot "${slot}" already mapped to "${map[slot]}" — left unchanged (set force:true to overwrite)`);
+                        continue;
+                    }
+                    map[slot] = menu.slug;
+                    touched = true;
+                }
+                if (touched) {
+                    try { await setMenuLocations(map); } catch (err) {
+                        warnings.push(`Locations update failed: ${err.message}`);
+                    }
+                }
+            }
+        } catch (err) {
+            warnings.push(`Menu "${menu.slug}" failed: ${err.message}`);
+        }
+    }
+
+    // 1. Collection
+    if (resolved.collection) {
+        await createCollection({
+            slug:        tokens.collectionSlug,
+            title:       resolved.collection.title,
+            description: resolved.collection.description,
+            fields:      resolved.collection.fields || [],
+            api:         resolved.collection.api,
+            // rowAccess is a top-level schema field; createCollection accepts arbitrary keys via spread,
+            // but to be explicit we set it on the schema after create. Simpler: write it via the schema
+            // file directly — createCollection already writes the schema, so we re-read + patch + write.
+            ...(projectSlug && {meta: {project: projectSlug}})
+        });
+
+        // Patch in rowAccess (if any) — collections.createCollection doesn't take it directly
+        if (resolved.collection.rowAccess) {
+            const {getCollection: get, updateCollection} = await import('./collections.js');
+            const cur = await get(tokens.collectionSlug);
+            if (cur) {
+                await updateCollection(tokens.collectionSlug, {
+                    ...cur,
+                    rowAccess: resolved.collection.rowAccess
+                });
+            }
+        }
+
+        created.collection = tokens.collectionSlug;
+    }
+
+    // 2. Form
+    if (resolved.form) {
+        const formData = projectSlug
+            ? {...resolved.form, meta: {...(resolved.form.meta || {}), project: projectSlug}}
+            : resolved.form;
+        await writeForm(tokens.formSlug, formData);
+        created.form = tokens.formSlug;
+    }
+
+    // 2b. Users — recipe-defined seed accounts. Password is mandatory (the
+    // scaffolder won't invent one); if omitted, the user is reported as
+    // skipped so the admin knows to create them manually. Auto-creating
+    // accounts with a default password would be a meaningful security trap.
+    for (const u of (resolved.users || [])) {
+        if (!u.email) continue;
+        // Existing user with the same email → skip silently. We don't update
+        // existing accounts (would silently change their password / role).
+        try {
+            const existing = await getUserByEmail(u.email);
+            if (existing) {
+                skipped.push(`user:${u.email}`);
+                warnings.push(`User "${u.email}" already exists — left unchanged`);
+                continue;
+            }
+        } catch { /* no-op */ }
+
+        if (!u.password) {
+            skipped.push(`user:${u.email}`);
+            warnings.push(`User "${u.email}" skipped — no password set in recipe. Create the account manually under Users → New.`);
+            continue;
+        }
+        try {
+            const newUser = await createUser({
+                name:            u.name || u.email,
+                email:           u.email,
+                password:        u.password,
+                role:            u.role || 'user',
+                additionalRoles: Array.isArray(u.additionalRoles) ? u.additionalRoles : [],
+                ...(projectSlug && {meta: {project: projectSlug}, projects: [projectSlug]})
+            });
+            created.users.push(newUser.email);
+        } catch (err) {
+            warnings.push(`User "${u.email}" failed: ${err.message}`);
+        }
+    }
+
+    // 3. Actions — best-effort; skip with warning when Mongo isn't available
+    for (const action of (resolved.actions || [])) {
+        if (!action.slug) continue;
+        try {
+            const a = await createAction({
+                slug:        action.slug,
+                title:       action.title,
+                description: action.description,
+                collection:  action.collection,
+                trigger:     action.trigger,
+                steps:       action.steps,
+                transition:  action.transition,
+                access:      action.access,
+                ...(projectSlug && {meta: {project: projectSlug}})
+            }, opts.createdBy || null);
+            created.actions.push(a.slug);
+        } catch (err) {
+            const reason = err.message.includes('MongoDB') || err.message.includes('Mongo')
+                ? `MongoDB not configured — action "${action.slug}" skipped (Pro feature)`
+                : `Action "${action.slug}" failed: ${err.message}`;
+            skipped.push(action.slug);
+            warnings.push(reason);
+        }
+    }
+
+    // Wire the form's actionSlug to the first created action if the recipe
+    // wanted it — convenient for "submit this form, fire that action" patterns.
+    if (created.form && created.actions.length && resolved.form?.settings?.actionSlug === '') {
+        try {
+            const formDef = await readForm(created.form);
+            formDef.settings = formDef.settings || {};
+            formDef.settings.actionSlug = created.actions[0];
+            await writeForm(created.form, formDef);
+        } catch { /* non-fatal — admin can wire it manually */ }
+    }
+
+    const snippet = resolved.snippet || null;
+
+    return { created, skipped, warnings, snippet };
+}

package/server/services/sidebar-migration.js

@@ -0,0 +1,117 @@
+/**
+ * Admin sidebar auto-migration.
+ *
+ * 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.
+ */
+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');
+
+const SEED_ITEMS = [
+    {
+        text: 'Overview', icon: 'home',
+        items: [
+            {text: 'Dashboard', url: '#/', icon: 'home'}
+        ]
+    },
+    {
+        text: 'Projects', icon: 'folder', permission: 'projects',
+        items: [
+            {text: 'Manage projects', url: '#/projects', icon: 'folder', permission: 'projects'}
+        ]
+    },
+    {
+        text: 'Content', icon: 'edit',
+        items: [
+            {text: 'Pages', url: '#/pages', icon: 'file-text', permission: 'pages'},
+            {text: 'Media', url: '#/media', icon: 'image',     permission: 'media'},
+            {text: 'Menus', url: '#/menus', icon: 'menu',      permission: 'menus'}
+        ]
+    },
+    {
+        text: 'Data', icon: 'database',
+        items: [
+            {text: 'Collections', url: '#/collections', icon: 'database',  permission: 'collections'},
+            {text: 'Forms',       url: '#/forms',       icon: 'layout',    permission: 'collections'},
+            {text: 'Views',       url: '#/views',       icon: 'eye',       permission: 'views'},
+            {text: 'Actions',     url: '#/actions',     icon: 'zap',       permission: 'actions'},
+            {text: 'Blocks',      url: '#/blocks',      icon: 'box',       permission: 'pages'},
+            {text: 'Components',  url: '#/components',  icon: 'component', permission: 'components'}
+        ]
+    },
+    {
+        text: 'System', icon: 'settings',
+        items: [
+            {text: 'Notifications', url: '#/system/notifications', icon: 'bell',     permission: 'notifications'},
+            {text: 'Roles',         url: '#/roles',                icon: 'shield',   permission: 'plugins'},
+            {text: 'Users',         url: '#/users',                icon: 'users',    permission: 'users'},
+            {text: 'Site Settings', url: '#/settings',             icon: 'settings', permission: 'settings'},
+            {text: 'Effects',       url: '#/effects',              icon: 'sparkles', permission: 'settings'},
+            {text: 'Layouts',       url: '#/layouts',              icon: 'layout',   permission: 'layouts'},
+            {text: 'Plugins',       url: '#/plugins',              icon: 'package',  permission: 'plugins'},
+            {text: 'My Profile',    url: '#/my-profile',           icon: 'user'}
+        ]
+    },
+    {
+        text: 'Documentation', icon: 'book',
+        items: [
+            {text: 'Usage',         url: '#/documentation',  icon: 'book'},
+            {text: 'Tutorials',     url: '#/tutorials',      icon: 'document'},
+            {text: 'API Reference', url: '#/api-reference',  icon: 'code'}
+        ]
+    }
+];
+
+async function exists(p) {
+    try { await fs.access(p); return true; } catch { return false; }
+}
+
+async function readJson(p) {
+    return JSON.parse(await fs.readFile(p, 'utf8'));
+}
+
+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;
+    const menusDir  = path.join(configDir, 'menus');
+    const menuPath  = path.join(menusDir, 'admin-sidebar.json');
+    const locPath   = path.join(configDir, 'menu-locations.json');
+
+    if (await exists(menuPath)) {
+        return {migrated: false, reason: 'admin-sidebar.json already present'};
+    }
+
+    await fs.mkdir(menusDir, {recursive: true});
+    const now = new Date().toISOString();
+    await writeJson(menuPath, {
+        slug:        'admin-sidebar',
+        name:        'Admin sidebar',
+        description: 'Auto-seeded by sidebar migration on first boot',
+        items:       SEED_ITEMS,
+        meta:        {createdAt: now, updatedAt: now, bundled: false, presetOwner: null}
+    });
+
+    let locations = {};
+    if (await exists(locPath)) {
+        try { locations = await readJson(locPath); } catch { /* malformed — start fresh */ }
+    }
+    locations['admin-sidebar'] = 'admin-sidebar';
+    await writeJson(locPath, locations);
+
+    console.log('[admin-sidebar] Seeded admin-sidebar menu + mapped admin-sidebar slot');
+    return {migrated: true};
+}

package/server/services/sitemap.js

@@ -0,0 +1,112 @@
+/**
+ * Sitemap Service
+ * Builds sitemap.xml from the page list. Filter logic lives in
+ * shouldIncludeInSitemap() — see the TODO below.
+ *
+ * Cache: callers should wrap generate() with the 'sitemap' tag so it
+ * invalidates whenever a page is created, updated, renamed, or deleted.
+ */
+import {listPages} from './content.js';
+import {getConfig} from '../config.js';
+
+/**
+ * Decide whether a page should appear in sitemap.xml.
+ *
+ * Rules:
+ *   - Must be published (drafts never index)
+ *   - Must be publicly visible (role-gated pages never index)
+ *   - Must not be the error page
+ *   - Must not opt out via `seo.noindex`
+ *
+ * @param {object} page - Parsed page from content service
+ * @returns {boolean}
+ */
+function shouldIncludeInSitemap(page) {
+    return page.status === 'published'
+        && page.visibility === 'public'
+        && page.urlPath !== '/404'
+        && !page.seo?.noindex;
+}
+
+/**
+ * Build the full sitemap.xml document as a string.
+ *
+ * @param {string} baseUrl - Absolute origin (e.g. 'https://example.com'),
+ *   typically derived from the incoming request. Trailing slash is stripped.
+ * @returns {Promise<string>}
+ */
+export async function generate(baseUrl) {
+    const normalised = normaliseBaseUrl(baseUrl);
+    const pages = await listPages();
+    const entries = pages
+        .filter(shouldIncludeInSitemap)
+        .map(page => buildUrlEntry(page, normalised));
+
+    return wrapInUrlset(entries);
+}
+
+/**
+ * Build the robots.txt document. Points at /sitemap.xml on the given base URL.
+ *
+ * @param {string} baseUrl - Absolute origin, typically derived from the
+ *   incoming request.
+ * @returns {string}
+ */
+export function buildRobotsTxt(baseUrl) {
+    const site = getConfig('site') || {};
+    const normalised = normaliseBaseUrl(baseUrl);
+    const sitemapUrl = normalised ? `${normalised}/sitemap.xml` : '/sitemap.xml';
+    const extra = (site.seo?.robotsExtra || '').toString().trim();
+
+    const lines = [
+        'User-agent: *',
+        'Allow: /',
+        'Disallow: /admin/',
+        'Disallow: /api/',
+        '',
+        `Sitemap: ${sitemapUrl}`
+    ];
+    if (extra) lines.push('', extra);
+    return lines.join('\n') + '\n';
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function buildUrlEntry(page, baseUrl) {
+    const loc = escapeXml(baseUrl ? `${baseUrl}${page.urlPath}` : page.urlPath);
+    const lastmod = page.updatedAt
+        ? new Date(page.updatedAt).toISOString()
+        : null;
+
+    const parts = [`<loc>${loc}</loc>`];
+    if (lastmod) parts.push(`<lastmod>${lastmod}</lastmod>`);
+    return `  <url>\n    ${parts.join('\n    ')}\n  </url>`;
+}
+
+function wrapInUrlset(entries) {
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+${entries.join('\n')}
+</urlset>
+`;
+}
+
+/**
+ * Strip trailing slash from a base URL so we can concatenate urlPaths
+ * (which always start with /).
+ */
+function normaliseBaseUrl(raw) {
+    if (!raw || typeof raw !== 'string') return '';
+    return raw.trim().replace(/\/+$/, '');
+}
+
+function escapeXml(str) {
+    return String(str)
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&apos;');
+}