domma-cms 0.17.0 → 0.21.0

package/server/routes/public.js

@@ -6,8 +6,31 @@
  */
 import {getPage} from '../services/content.js';
 import {renderPage} from '../services/renderer.js';
+import {buildRobotsTxt, generate as generateSitemap} from '../services/sitemap.js';
 import {checkVisibility} from '../middleware/auth.js';
 import {hooks} from '../services/hooks.js';
+import {getConfig} from '../config.js';
+import * as cache from '../services/cache/index.js';
+
+/**
+ * Derive the absolute origin for the current request.
+ *
+ * Honours `site.baseUrl` as an explicit override (useful when the CMS sits
+ * behind infrastructure that doesn't forward Host correctly). Otherwise
+ * builds it from `request.protocol` + `request.host` — both of which Fastify
+ * resolves from `X-Forwarded-*` headers when `trustProxy` is on. `request.host`
+ * includes the port for non-default ports (e.g. `localhost:4096` in dev) and
+ * omits it for the standard 80/443.
+ *
+ * @param {import('fastify').FastifyRequest} request
+ * @returns {string} e.g. 'https://example.com' (no trailing slash)
+ */
+function getBaseUrl(request) {
+    const override = (getConfig('site') || {}).baseUrl;
+    if (override) return override.toString().trim().replace(/\/+$/, '');
+    const host = request.host || request.headers.host || request.hostname;
+    return `${request.protocol}://${host}`;
+}
 
 /**
  * Escape user-controlled strings before interpolating into HTML.
@@ -34,6 +57,24 @@ export async function publicRoutes(fastify) {
     // Health check
     fastify.get('/api/health', async () => ({ status: 'ok' }));
 
+    // SEO: sitemap.xml — cached per origin (so a single CMS responding on
+    // multiple domains gets the right absolute URLs); invalidated by page
+    // CRUD via the 'sitemap' tag.
+    fastify.get('/sitemap.xml', async (request, reply) => {
+        const baseUrl = getBaseUrl(request);
+        const xml = await cache.wrap(
+            `sitemap:xml:${baseUrl}`,
+            () => generateSitemap(baseUrl),
+            {tags: ['sitemap']}
+        );
+        return reply.type('application/xml').send(xml);
+    });
+
+    // SEO: robots.txt — cheap to build, no cache wrap needed.
+    fastify.get('/robots.txt', async (request, reply) => {
+        return reply.type('text/plain').send(buildRobotsTxt(getBaseUrl(request)));
+    });
+
     // Public pages catch-all
     fastify.get('/*', async (request, reply) => {
         const rawPath = request.params['*'];
@@ -45,7 +86,10 @@ export async function publicRoutes(fastify) {
 
         const urlPath = '/' + (rawPath || '');
 
-        // Try exact path first, then with /index suffix for directory-style URLs
+        // First-pass page lookup — used only for the visibility decision
+        // (metadata-only is sufficient). We re-fetch below with `user` once
+        // it is resolved so the body's [menu] shortcode renders against the
+        // correct role.
         let page = await getPage(urlPath);
 
         // Try fetching index of a directory path
@@ -64,21 +108,58 @@ export async function publicRoutes(fastify) {
             return reply.type('text/html').send(await render404(urlPath));
         }
 
-        // Enforce page visibility
-        if (page.visibility && page.visibility !== 'public') {
-            let userRole = null;
+        // Enforce page visibility — role only resolved for gated pages,
+        // so public pages share a single cache entry keyed `roleanon`.
+        //
+        // `visibility` may be a string ('public' | 'private' | role name) or
+        // an array of role names — see checkVisibility() for full semantics.
+        // Effectively-public values (missing, 'public', or an array containing
+        // 'public') skip JWT verification entirely so anonymous traffic hits
+        // the shared cache without auth cost.
+        // For per-role cache keying we use the primary role only — multi-role
+        // users still see correctly-gated content (checkVisibility consults
+        // additionalRoles too) but the cache key stays bounded to one entry
+        // per primary role rather than 2^N per role combination. The fallback
+        // is correctness: any user whose access depends on an additional role
+        // is granted, but their served HTML is the variant cached for their
+        // primary role's tier — fine for the public-site use case.
+        let userRole = null;
+        let userObj  = null;
+        const vis      = page.visibility;
+        const isPublic = !vis
+            || vis === 'public'
+            || (Array.isArray(vis) && (vis.length === 0 || vis.includes('public')));
+
+        if (!isPublic) {
             try {
                 const decoded = await request.jwtVerify();
-                if (decoded.type === 'access') userRole = decoded.role;
+                if (decoded.type === 'access') {
+                    userRole = decoded.role;
+                    userObj  = { role: decoded.role, additionalRoles: decoded.additionalRoles || [] };
+                }
             } catch { /* no token — treat as unauthenticated */ }
 
-            if (!checkVisibility(userRole, page.visibility)) {
+            if (!checkVisibility(userObj, vis)) {
                 reply.status(403);
                 return reply.type('text/html').send(accessDeniedHtml(urlPath));
             }
         }
 
-        const html = await renderPage(page);
+        const baseUrl = getBaseUrl(request);
+        const cacheKey = `page:${urlPath}:role${userRole ?? 'anon'}:o${baseUrl}`;
+        const cacheTags = [`page:${urlPath}`, ...(page.tags || []), 'nav', 'site'];
+        const html = await cache.wrap(
+            cacheKey,
+            async () => {
+                // Re-parse with user context so the body's [menu] shortcode
+                // sees the visitor's role for visibility filtering. The first
+                // getPage() above was anonymous because we hadn't decoded the
+                // JWT yet; this second pass uses the resolved userObj.
+                const pageForRole = await getPage(page.urlPath, {user: userObj}) || page;
+                return renderPage(pageForRole, {baseUrl, user: userObj});
+            },
+            {tags: cacheTags}
+        );
         hooks.emit('content:pageViewed', {urlPath, title: page.title || ''});
         return reply.type('text/html').send(html);
     });

package/server/server.js

@@ -12,6 +12,7 @@ import cors from '@fastify/cors';
 import multipart from '@fastify/multipart';
 import rateLimit from '@fastify/rate-limit';
 import helmet from '@fastify/helmet';
+import compress from '@fastify/compress';
 import path from 'path';
 import fs from 'fs/promises';
 import {fileURLToPath} from 'url';
@@ -24,6 +25,7 @@ import {seedAll as seedPresetCollections} from './services/presetCollections.js'
 import {seedDefaultBlocks} from './services/blocks.js';
 import {seedDefaultComponents} from './services/components.js';
 import {refreshComponentTagAllowlist} from './services/markdown.js';
+import * as cache from './services/cache/index.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const ROOT = path.resolve(__dirname, '..');
@@ -104,6 +106,14 @@ await app.register(rateLimit, {
     allowList: ['127.0.0.1', '::1', '::ffff:127.0.0.1'],
 });
 
+// Negotiates brotli/gzip/deflate per Accept-Encoding. Skips already-compressed
+// content types (images, fonts, video) and responses under threshold.
+await app.register(compress, {
+    global: true,
+    threshold: 1024,
+    encodings: ['br', 'gzip', 'deflate']
+});
+
 // ---------------------------------------------------------------------------
 // Static Assets
 // ---------------------------------------------------------------------------
@@ -122,13 +132,19 @@ await app.register(staticPlugin, {
     decorateReply: false
 });
 
-// Serve admin panel assets — no-cache so JS/CSS changes are always picked up
+// Serve admin panel assets — no-store on JS/CSS so ESM module URLs are never
+// cached. `no-cache` revalidates but browsers may keep the parsed ESM module
+// keyed by URL across reloads, which means a hard refresh can still load the
+// stale code path. `no-store` skips the cache entirely. Other admin assets
+// (images, html) keep no-cache. Local-only impact — admin is not public.
 await app.register(staticPlugin, {
     root: path.join(ROOT, 'admin'),
     prefix: '/admin/',
     decorateReply: false,
-    setHeaders: (res) => {
-        res.setHeader('Cache-Control', 'no-cache');
+    cacheControl: false,
+    setHeaders: (res, filePath) => {
+        const noStore = /\.(?:js|mjs|css)$/i.test(filePath);
+        res.setHeader('Cache-Control', noStore ? 'no-store' : 'no-cache');
     }
 });
 
@@ -172,6 +188,28 @@ await seedDefaultBlocks();
 await seedDefaultComponents();
 await refreshComponentTagAllowlist();
 
+// ---------------------------------------------------------------------------
+// Menus — one-shot migration from legacy navigation.json + site footer links
+// ---------------------------------------------------------------------------
+
+try {
+    const {runMigration: runMenusMigration} = await import('./services/menus-migration.js');
+    await runMenusMigration();
+} catch (err) {
+    app.log.warn(`[menus] Migration skipped: ${err.message}`);
+}
+
+try {
+    const {runMigration: runSidebarMigration} = await import('./services/sidebar-migration.js');
+    await runSidebarMigration();
+} catch (err) {
+    app.log.warn(`[admin-sidebar] Migration skipped: ${err.message}`);
+}
+
+// Initialise response cache (Memory/None/Redis driver per config.cache).
+await cache.initCache(config.cache);
+console.log(`[cache] driver=${cache.isEnabled() ? config.cache.driver : 'disabled'}`);
+
 // Serve uploaded media files — nosniff prevents browsers rendering spoofed content types
 await app.register(staticPlugin, {
     root: mediaDir,
@@ -236,6 +274,10 @@ const { pagesRoutes }      = await import('./routes/api/pages.js');
 const { settingsRoutes }   = await import('./routes/api/settings.js');
 const { layoutsRoutes }    = await import('./routes/api/layouts.js');
 const { navigationRoutes } = await import('./routes/api/navigation.js');
+const {menusRoutes}         = await import('./routes/api/menus.js');
+const {menuLocationsRoutes} = await import('./routes/api/menu-locations.js');
+const {projectsRoutes}      = await import('./routes/api/projects.js');
+const {sidebarRoutes}       = await import('./routes/api/sidebar.js');
 const { mediaRoutes }      = await import('./routes/api/media.js');
 const { usersRoutes }      = await import('./routes/api/users.js');
 const { pluginsRoutes }            = await import('./routes/api/plugins.js');
@@ -250,11 +292,17 @@ const {versionsRoutes} = await import('./routes/api/versions.js');
 const {effectsRoutes} = await import('./routes/api/effects.js');
 const {notificationsRoutes} = await import('./routes/api/notifications.js');
 const {dashboardRoutes} = await import('./routes/api/dashboard.js');
+const {cacheRoutes} = await import('./routes/api/cache.js');
+const {scaffoldRoutes} = await import('./routes/api/scaffold.js');
 
 await app.register(pagesRoutes,       { prefix: '/api' });
 await app.register(settingsRoutes,    { prefix: '/api' });
 await app.register(layoutsRoutes,     { prefix: '/api' });
 await app.register(navigationRoutes,  { prefix: '/api' });
+await app.register(menusRoutes,         {prefix: '/api'});
+await app.register(menuLocationsRoutes, {prefix: '/api'});
+await app.register(projectsRoutes,      {prefix: '/api'});
+await app.register(sidebarRoutes,       {prefix: '/api'});
 await app.register(mediaRoutes,       { prefix: '/api' });
 await app.register(usersRoutes,       { prefix: '/api' });
 await app.register(pluginsRoutes,            { prefix: '/api' });
@@ -269,6 +317,8 @@ await app.register(versionsRoutes, {prefix: '/api'});
 await app.register(effectsRoutes, {prefix: '/api'});
 await app.register(notificationsRoutes, {prefix: '/api'});
 await app.register(dashboardRoutes, {prefix: '/api'});
+await app.register(cacheRoutes, {prefix: '/api'});
+await app.register(scaffoldRoutes, {prefix: '/api'});
 
 // ---------------------------------------------------------------------------
 // CMS Plugins (server-side Fastify plugins from plugins/ directory)
@@ -325,3 +375,4 @@ try {
     app.log.error(err);
     process.exit(1);
 }
+// scaffold-restart 1779615684

package/server/services/actions.js

@@ -4,13 +4,23 @@
  * Action configs are stored in MongoDB `cms__actions` on the 'default' connection.
  * Executing an action runs a sequence of steps against a target collection entry.
  *
- * Phase 1 step types:
- *   updateField, deleteEntry, moveToCollection, webhook, email
+ * Supported step types:
+ *   updateField         — overwrite one field on the source entry
+ *   deleteEntry         — remove the source entry
+ *   moveToCollection    — copy source entry into target collection AND delete source
+ *   createInCollection  — create a new entry in another collection; source untouched
+ *                         (used for apply/follow/bookmark/upvote-style relations)
+ *   webhook             — POST/PUT/GET to an external URL with interpolated body
+ *   email               — send a transactional email via configured SMTP
  *
  * Template interpolation in step configs:
- *   {{entry.data.field}} → entry field value
+ *   {{entry.id}}         → source entry id
+ *   {{entry.data.field}} → source entry field value
  *   {{now}}              → current ISO timestamp
+ *   {{user.id}}          → executing user's id
  *   {{user.name}}        → executing user's name
+ *   {{user.email}}       → executing user's email
+ *   {{user.role}}        → executing user's role
  *   {{env.CMS_PUBLIC_*}} → environment variables with CMS_PUBLIC_ prefix only
  *
  * Note: execution is not transactional — partial results are returned on failure
@@ -140,6 +150,35 @@ async function executeStep(step, collection, entry, context) {
             return { moved: entry.id, to: target };
         }
 
+        /*
+         * createInCollection — append an entry to another collection without
+         * touching the source. Designed for relational patterns like:
+         *   - Apply for job  → create entry in `applications` { jobId, candidateId, status }
+         *   - Bookmark page  → create entry in `bookmarks`    { pageId, userId }
+         *   - Upvote item    → create entry in `votes`        { itemId, userId, value: 1 }
+         *
+         * Config:
+         *   targetCollection {string} required — slug of the collection to append to
+         *   data             {object} required — field map; values are template-interpolated
+         *   createdBy        {string} optional — '{{user.id}}' is the conventional value;
+         *                                       enables row-level "mine" filtering downstream
+         *
+         * Returns: { created: <new entry id>, in: <targetCollection> }
+         */
+        case 'createInCollection': {
+            const target = cfg.targetCollection;
+            if (!target) throw new Error('createInCollection: targetCollection is required');
+            if (!cfg.data || typeof cfg.data !== 'object') {
+                throw new Error('createInCollection: data object is required');
+            }
+            const data       = interpolateValue(cfg.data, context);
+            const createdBy  = cfg.createdBy
+                ? interpolate(String(cfg.createdBy), context)
+                : (context.user?.id || null);
+            const created    = await createEntry(target, data, { createdBy, source: 'action' });
+            return { created: created.id, in: target };
+        }
+
         case 'webhook': {
             const url     = interpolate(cfg.url || '', context);
             const method  = (cfg.method || 'POST').toUpperCase();
@@ -239,7 +278,7 @@ export async function getAction(slug) {
  */
 export async function createAction(data, userId = null) {
     const db = await getMetaDb();
-    const { title, description = '', collection, trigger, steps = [], access } = data;
+    const { title, description = '', collection, trigger, steps = [], access, transition, meta: inputMeta } = data;
 
     if (!title)      throw new Error('title is required');
     if (!collection) throw new Error('collection is required');
@@ -264,11 +303,25 @@ export async function createAction(data, userId = null) {
             confirmMessage: trigger?.confirmMessage || null
         },
         steps,
+        // State-machine transition — when set, the action is gated by the
+        // entry's current value of `field` matching one of the `from` values,
+        // and is advertised as an "available transition" for that state.
+        // Optional `to` is informational only (steps still do the actual write).
+        transition: transition ? {
+            field: transition.field,
+            from:  Array.isArray(transition.from) ? transition.from : [transition.from].filter(Boolean),
+            to:    transition.to
+        } : null,
         access: {
             roles: access?.roles || ['admin', 'super-admin'],
             rowLevel: access?.rowLevel || null
         },
-        meta: { createdAt: now, updatedAt: now, createdBy: userId }
+        meta: {
+            createdAt: now,
+            updatedAt: now,
+            createdBy: userId,
+            ...(inputMeta?.project != null && {project: inputMeta.project})
+        }
     };
 
     await db.collection(ACTIONS_COLLECTION).insertOne({ ...action });
@@ -288,12 +341,18 @@ export async function updateAction(slug, data) {
     const existing = await db.collection(ACTIONS_COLLECTION).findOne({ slug });
     if (!existing) throw new Error(`Action "${slug}" not found`);
 
-    const { _id, id, meta, ...rest } = data;
+    const { _id, id, meta: inputMeta, ...rest } = data;
     const updated = {
         ...existing,
         ...rest,
         slug,
-        meta: { ...existing.meta, updatedAt: new Date().toISOString() }
+        meta: {
+            ...existing.meta,
+            ...(inputMeta && typeof inputMeta === 'object'
+                ? ('project' in inputMeta ? {project: inputMeta.project} : {})
+                : {}),
+            updatedAt: new Date().toISOString()
+        }
     };
 
     await db.collection(ACTIONS_COLLECTION).replaceOne({ slug }, { ...updated });
@@ -328,6 +387,59 @@ export async function listActionsForCollection(collectionSlug) {
         .toArray();
 }
 
+/**
+ * List the actions that represent valid next-state transitions for a given
+ * entry as seen by a given user. Used by the per-row transitions UI in the
+ * Collection Browser and the `[transitions]` shortcode.
+ *
+ * Criteria for inclusion:
+ *   1. action.collection matches the entry's collection
+ *   2. action.transition is set and action.transition.from includes the
+ *      entry's current value of action.transition.field
+ *   3. action.access.roles allows the user (compared by role level so
+ *      higher-privileged roles inherit access automatically)
+ *
+ * Returns a stripped projection — slug, title, trigger config, transition —
+ * so the client can render buttons without leaking step internals.
+ *
+ * @param {string} collectionSlug
+ * @param {object} entry          - The entry being inspected (needed for field-value match)
+ * @param {object} [user]         - { role } — anonymous if missing
+ * @returns {Promise<object[]>}
+ */
+export async function listTransitionsForEntry(collectionSlug, entry, user = null) {
+    const all = await listActionsForCollection(collectionSlug);
+    if (!Array.isArray(all) || !all.length) return [];
+
+    const { getRoleLevel } = await import('./roles.js');
+    const { getEffectiveLevel } = await import('./userRoles.js');
+    // Use effective level so multi-role users see transitions any of their
+    // roles permit — e.g. a user who's primarily a candidate but also an
+    // admin sees BOTH the candidate-only "withdraw" AND the admin-only
+    // "approve" transitions on the same entry.
+    const userLevel = getEffectiveLevel(user);
+
+    return all
+        .filter(a => {
+            if (!a.transition) return false;
+            const allowedFrom = Array.isArray(a.transition.from) ? a.transition.from : [a.transition.from].filter(Boolean);
+            if (allowedFrom.length) {
+                const current = entry.data?.[a.transition.field];
+                if (!allowedFrom.includes(current)) return false;
+            }
+            const roles    = a.access?.roles || ['admin', 'super-admin'];
+            const minLevel = Math.min(...roles.map(r => getRoleLevel(r)));
+            if (!(userLevel <= minLevel)) return false;
+            return true;
+        })
+        .map(a => ({
+            slug:       a.slug,
+            title:      a.title,
+            trigger:    a.trigger,
+            transition: a.transition
+        }));
+}
+
 // ---------------------------------------------------------------------------
 // Execution
 // ---------------------------------------------------------------------------
@@ -351,12 +463,29 @@ export async function executeAction(slug, entryId, { user = null } = {}) {
     const entry = await getEntry(action.collection, entryId);
     if (!entry) throw new Error(`Entry "${entryId}" not found in collection "${action.collection}"`);
 
-    if (!checkEntryAccess(entry, user, action.access?.rowLevel)) {
+    if (!(await checkEntryAccess(entry, user, action.access?.rowLevel))) {
         const err = new Error('Row-level access denied');
         err.statusCode = 403;
         throw err;
     }
 
+    // State-machine guard — an action with a transition config only runs when
+    // the entry's current value of `field` is in `from`. Stops illegal moves
+    // like "withdraw" on an already-rejected application; the API returns 409
+    // so the client can present a meaningful "no longer available" message
+    // (we use 409 = Conflict rather than 403 because the request itself was
+    // authorised, just inconsistent with current state).
+    if (action.transition) {
+        const t            = action.transition;
+        const currentValue = entry.data?.[t.field];
+        const allowed      = Array.isArray(t.from) ? t.from : (t.from ? [t.from] : []);
+        if (allowed.length && !allowed.includes(currentValue)) {
+            const err = new Error(`Cannot apply "${action.title}" — current ${t.field} is "${currentValue ?? '(none)'}", allowed: ${allowed.join(', ')}`);
+            err.statusCode = 409;
+            throw err;
+        }
+    }
+
     const context = {
         entry,
         now:  new Date().toISOString(),

package/server/services/adapters/FileAdapter.js

@@ -19,6 +19,7 @@
 import fs from 'fs/promises';
 import path from 'path';
 import { config } from '../../config.js';
+import { applyFilter } from '../filterEngine.js';
 
 const COLLECTIONS_DIR = path.resolve(config.content.collectionsDir);
 
@@ -50,18 +51,25 @@ async function write(slug, entries) {
 export class FileAdapter {
 
     /**
-     * List entries with optional pagination, sorting, and search.
+     * List entries with optional pagination, sorting, free-text search,
+     * and structured filtering.
+     *
+     * `search` is a simple substring match across all field values (legacy
+     * behaviour, kept for the admin search box). `filter` is the structured
+     * DSL — see `filterEngine.js` for operator syntax. Both may be combined;
+     * search runs first, then filter.
      *
      * @param {string} slug
      * @param {object} [opts]
-     * @param {number}  [opts.page=1]
-     * @param {number}  [opts.limit=50]
-     * @param {string}  [opts.sort='createdAt']
-     * @param {string}  [opts.order='desc']
-     * @param {string}  [opts.search]
+     * @param {number}                    [opts.page=1]
+     * @param {number}                    [opts.limit=50]      - Use 0 for "no limit" (returns all)
+     * @param {string}                    [opts.sort='createdAt']
+     * @param {string}                    [opts.order='desc']  - 'asc' | 'desc'
+     * @param {string}                    [opts.search]        - Free-text substring across all fields
+     * @param {Record<string, unknown>}   [opts.filter]        - Structured filter; see filterEngine.js
      * @returns {Promise<{ entries: object[], total: number, page: number, limit: number }>}
      */
-    async list(slug, { page = 1, limit = 50, sort = 'createdAt', order = 'desc', search } = {}) {
+    async list(slug, { page = 1, limit = 50, sort = 'createdAt', order = 'desc', search, filter } = {}) {
         let entries = await read(slug);
 
         if (search) {
@@ -71,6 +79,10 @@ export class FileAdapter {
             );
         }
 
+        if (filter) {
+            entries = applyFilter(entries, filter);
+        }
+
         entries.sort((a, b) => {
             const aVal = sort === 'createdAt' ? a.meta?.createdAt : (a.data?.[sort] ?? '');
             const bVal = sort === 'createdAt' ? b.meta?.createdAt : (b.data?.[sort] ?? '');
@@ -78,7 +90,10 @@ export class FileAdapter {
             return order === 'desc' ? -cmp : cmp;
         });
 
-        const total  = entries.length;
+        const total = entries.length;
+        if (limit === 0 || limit == null) {
+            return { entries, total, page: 1, limit: total };
+        }
         const offset = (page - 1) * limit;
         return { entries: entries.slice(offset, offset + limit), total, page, limit };
     }

package/server/services/adapters/MongoAdapter.js

@@ -18,6 +18,7 @@
  *   insertMany(slug, entries) → { imported, skipped, errors }
  *   count(slug)               → number
  */
+import { toMongoQuery } from '../filterEngine.js';
 
 /** Prefix applied to all CMS collection names in MongoDB to avoid collisions. */
 const PREFIX = 'cms_';
@@ -61,32 +62,39 @@ export class MongoAdapter {
     }
 
     /**
-     * List entries with optional pagination, sorting, and search.
+     * List entries with optional pagination, sorting, free-text search,
+     * and structured filtering.
      *
-     * When no search term is provided, pagination and sorting are pushed to MongoDB
-     * for efficiency. When a search term is provided, all documents are fetched and
-     * filtered in memory — identical behaviour to FileAdapter. For large collections
-     * requiring efficient full-text search, configure a MongoDB Atlas Search index.
+     * `filter` is translated to native MongoDB query operators via
+     * `filterEngine.toMongoQuery()` and pushed down to the database — page
+     * authors writing `[collection where_salary_gte="50000"]` get index-aware
+     * queries automatically. When `search` is present, all documents are
+     * fetched and filtered in memory (same behaviour as FileAdapter, kept
+     * for parity); combine with `filter` to keep the in-memory set small.
      *
      * @param {string} slug
      * @param {object} [opts]
-     * @param {number}  [opts.page=1]
-     * @param {number}  [opts.limit=50]
-     * @param {string}  [opts.sort='createdAt']
-     * @param {string}  [opts.order='desc']
-     * @param {string}  [opts.search]
+     * @param {number}                    [opts.page=1]
+     * @param {number}                    [opts.limit=50]      - Use 0 for "no limit"
+     * @param {string}                    [opts.sort='createdAt']
+     * @param {string}                    [opts.order='desc']  - 'asc' | 'desc'
+     * @param {string}                    [opts.search]        - Free-text substring across all fields
+     * @param {Record<string, unknown>}   [opts.filter]        - Structured filter; see filterEngine.js
      * @returns {Promise<{ entries: object[], total: number, page: number, limit: number }>}
      */
-    async list(slug, { page = 1, limit = 50, sort = 'createdAt', order = 'desc', search } = {}) {
+    async list(slug, { page = 1, limit = 50, sort = 'createdAt', order = 'desc', search, filter } = {}) {
         const col = await this._col(slug);
 
         const sortField = sort === 'createdAt' ? 'meta.createdAt' : `data.${sort}`;
         const sortDir   = order === 'desc' ? -1 : 1;
+        const query     = filter ? toMongoQuery(filter) : {};
 
         if (search) {
-            // Fetch all and filter in memory to avoid $where (often disabled in Atlas).
+            // Fetch matching (by filter) docs and substring-match in memory.
+            // Atlas Search is the right tool for large datasets; this is the
+            // portable fallback that matches FileAdapter semantics exactly.
             const all = await col
-                .find({}, { projection: { _id: 0 } })
+                .find(query, { projection: { _id: 0 } })
                 .sort({ [sortField]: sortDir })
                 .toArray();
 
@@ -95,16 +103,26 @@ export class MongoAdapter {
                 Object.values(entry.data || {}).some(v => String(v).toLowerCase().includes(term))
             );
 
-            const total  = matched.length;
+            const total = matched.length;
+            if (limit === 0 || limit == null) {
+                return { entries: matched, total, page: 1, limit: total };
+            }
             const offset = (page - 1) * limit;
             return { entries: matched.slice(offset, offset + limit), total, page, limit };
         }
 
-        const total  = await col.countDocuments({});
-        const offset = (page - 1) * limit;
+        const total = await col.countDocuments(query);
+        if (limit === 0 || limit == null) {
+            const docs = await col
+                .find(query, { projection: { _id: 0 } })
+                .sort({ [sortField]: sortDir })
+                .toArray();
+            return { entries: docs, total, page: 1, limit: total };
+        }
 
-        const docs = await col
-            .find({}, { projection: { _id: 0 } })
+        const offset = (page - 1) * limit;
+        const docs   = await col
+            .find(query, { projection: { _id: 0 } })
             .sort({ [sortField]: sortDir })
             .skip(offset)
             .limit(limit)