domma-cms 0.43.1 → 0.45.0

package/server/routes/api/users.js

@@ -2,9 +2,9 @@
  * Users API
  * GET    /api/users      - list all users (admin, manager)
  * GET    /api/users/:id  - single user (admin, manager, or self)
- * POST   /api/users      - create user (admin, manager — manager cannot create admin)
- * PUT    /api/users/:id  - update user (admin, manager — manager cannot edit admin)
- * DELETE /api/users/:id  - delete user (admin, manager — manager cannot delete admin, no self-delete)
+ * POST   /api/users      - create user (admin, manager - manager cannot create admin)
+ * PUT    /api/users/:id  - update user (admin, manager - manager cannot edit admin)
+ * DELETE /api/users/:id  - delete user (admin, manager - manager cannot delete admin, no self-delete)
  */
 import {authenticate, canManageUser, requirePermission} from '../../middleware/auth.js';
 import {getPermissionsFor} from '../../services/roles.js';
@@ -64,7 +64,7 @@ export async function usersRoutes(fastify) {
         if (!canManageUser(request.user, targetRole)) {
             return reply.code(403).send({ error: 'You cannot create a user with that role' });
         }
-        // Additional-roles privilege guard — actor must be able to manage EVERY role
+        // Additional-roles privilege guard - actor must be able to manage EVERY role
         // they're trying to assign, not just the primary.
         const requestedAdditional = Array.isArray(request.body?.additionalRoles) ? request.body.additionalRoles : [];
         for (const r of requestedAdditional) {
@@ -89,7 +89,7 @@ export async function usersRoutes(fastify) {
         const target = await getUserById(id);
         if (!target) return reply.status(404).send({ error: 'User not found' });
 
-        // Self-edit is always allowed — the hierarchy guard only applies to
+        // Self-edit is always allowed - the hierarchy guard only applies to
         // OTHER users, otherwise nobody can edit a peer-level account (or
         // even their own, since canManageUser is a strict level comparison).
         // Role-escalation guards below still apply to self-edits.

package/server/routes/api/versions.js

@@ -83,7 +83,7 @@ export async function versionsRoutes(fastify) {
         }
     });
 
-    // Prune versions — keep the most recent N (policy decided in pruneVersions)
+    // Prune versions - keep the most recent N (policy decided in pruneVersions)
     fastify.post('/versions/prune/*', canDelete, async (request, reply) => {
         const urlPath = '/' + request.params['*'];
         const keep = Number.parseInt(request.body?.keep, 10);

package/server/routes/api/views.js

@@ -32,7 +32,7 @@ export async function viewsRoutes(fastify) {
         try {
             const {canSeeArtefact} = await import('../../services/projects.js');
             const all = await listViews();
-            // listViews returns full records with meta inline — filter directly
+            // listViews returns full records with meta inline - filter directly
             return all.filter(v => canSeeArtefact(request.user, v));
         } catch (err) {
             return reply.status(503).send({ error: err.message });

package/server/routes/docs-public.js

@@ -1,5 +1,5 @@
 /**
- * Domma Docs — public surface
+ * Domma Docs - public surface
  *
  * Serves the handbook at request time from the admin doc templates:
  *   GET /domma-docs              → home landing
@@ -11,7 +11,7 @@
  *
  * This dedicated /domma-docs(/*) prefix out-prioritises public.js's `/*`
  * catch-all (Fastify ranks static segments above wildcards), exactly as
- * routes/api/endpoints-public.js `/x/*` coexists with it — so no per-path
+ * routes/api/endpoints-public.js `/x/*` coexists with it - so no per-path
  * special-casing is needed in public.js. Registered at app root (not behind a
  * prefixed plugin) so the specificity ranking shares one router scope.
  */
@@ -38,6 +38,6 @@ export async function docsPublicRoutes(fastify) {
         return reply.type('text/html').send(html);
     };
 
-    fastify.get('/domma-docs', handle);    // exact — params['*'] === '' (home landing)
+    fastify.get('/domma-docs', handle);    // exact - params['*'] === '' (home landing)
     fastify.get('/domma-docs/*', handle);  // sections + leaves
 }

package/server/routes/public.js

@@ -18,7 +18,7 @@ import * as cache from '../services/cache/index.js';
  *
  * 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
+ * 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.
@@ -58,7 +58,7 @@ 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
+    // 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) => {
@@ -71,7 +71,7 @@ export async function publicRoutes(fastify) {
         return reply.type('application/xml').send(xml);
     });
 
-    // SEO: robots.txt — cheap to build, no cache wrap needed.
+    // 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)));
     });
@@ -87,7 +87,7 @@ export async function publicRoutes(fastify) {
 
         const urlPath = '/' + (rawPath || '');
 
-        // First-pass page lookup — used only for the visibility decision
+        // 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.
@@ -110,28 +110,28 @@ export async function publicRoutes(fastify) {
         }
 
         // Hard kill-switch: a disabled project takes its pages off the public
-        // site entirely — 404 (no oracle), regardless of page visibility.
+        // site entirely - 404 (no oracle), regardless of page visibility.
         const pageProject = await getProjectForPage(page.urlPath || urlPath, page.project);
         if (!(await isProjectEnabled(pageProject))) {
             reply.status(404);
             return reply.type('text/html').send(await render404(urlPath));
         }
 
-        // Enforce page visibility — role only resolved for gated pages,
+        // 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.
+        // 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
+        // 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.
+        // primary role's tier - fine for the public-site use case.
         let userRole = null;
         let userObj  = null;
         const vis      = page.visibility;
@@ -146,7 +146,7 @@ export async function publicRoutes(fastify) {
                     userRole = decoded.role;
                     userObj  = { role: decoded.role, additionalRoles: decoded.additionalRoles || [] };
                 }
-            } catch { /* no token — treat as unauthenticated */ }
+            } catch { /* no token - treat as unauthenticated */ }
 
             if (!checkVisibility(userObj, vis)) {
                 reply.status(403);
@@ -155,12 +155,12 @@ export async function publicRoutes(fastify) {
         }
 
         const baseUrl = getBaseUrl(request);
-        // mtime in the key: any change to the backing file — editor save,
-        // script, git pull — yields a fresh entry even if no invalidation
+        // mtime in the key: any change to the backing file - editor save,
+        // script, git pull - yields a fresh entry even if no invalidation
         // hook fired. Stale-mtime entries age out via TTL/LRU.
         const pageMtime = await getPageMtime(page.urlPath || urlPath);
         const cacheKey = `page:${urlPath}:m${pageMtime}:role${userRole ?? 'anon'}:o${baseUrl}`;
-        const cacheTags = [`page:${urlPath}`, ...(page.tags || []), 'nav', 'site'];
+        const cacheTags = [`page:${urlPath}`, ...(page.cacheTags || []), 'nav', 'site'];
         const html = await cache.wrap(
             cacheKey,
             async () => {
@@ -179,7 +179,7 @@ export async function publicRoutes(fastify) {
 }
 
 /**
- * Render a 404 response — tries content/pages/404.md first, falls back to
+ * Render a 404 response - tries content/pages/404.md first, falls back to
  * a minimal inline page so the site theme is applied when possible.
  */
 export async function render404(urlPath) {

package/server/server.js

@@ -38,7 +38,7 @@ const DOMMA_DIST = path.join(dommaPackageDir, 'public', 'dist');
 
 const { server: serverConfig, auth: authConfig } = config;
 
-// Validate JWT_SECRET before starting — prevents silent auth failures
+// Validate JWT_SECRET before starting - prevents silent auth failures
 const JWT_SECRET = process.env.JWT_SECRET;
 if (!JWT_SECRET || JWT_SECRET === 'CHANGE_ME' || JWT_SECRET.length < 32) {
     console.error('');
@@ -49,7 +49,7 @@ if (!JWT_SECRET || JWT_SECRET === 'CHANGE_ME' || JWT_SECRET.length < 32) {
     process.exit(1);
 }
 
-// MANAGER_SECRET is optional — only needed when domma-cms-manager pushes notifications.
+// MANAGER_SECRET is optional - only needed when domma-cms-manager pushes notifications.
 // Warn if set but insecure; silently accept if absent (manager push is disabled).
 const MANAGER_SECRET = process.env.MANAGER_SECRET;
 if (MANAGER_SECRET && MANAGER_SECRET.length < 32) {
@@ -92,7 +92,7 @@ await app.register(helmet, {
         }
     },
     crossOriginEmbedderPolicy: false, // allow embedding images/resources
-    hsts: false, // disable HSTS — server runs HTTP only; HSTS would force browser to https
+    hsts: false, // disable HSTS - server runs HTTP only; HSTS would force browser to https
 });
 
 await app.register(jwt, { secret: process.env.JWT_SECRET });
@@ -102,7 +102,7 @@ await app.register(rateLimit, {
     global: true, // apply default limit to all routes; stricter per-route limits override this
     max: 500,
     timeWindow: '1 minute',
-    // Loopback is always exempt — local admin use should never be rate-limited.
+    // Loopback is always exempt - local admin use should never be rate-limited.
     // When behind a reverse proxy (TRUST_PROXY), the proxy's loopback is also exempt.
     allowList: ['127.0.0.1', '::1', '::ffff:127.0.0.1'],
 });
@@ -133,11 +133,11 @@ await app.register(staticPlugin, {
     decorateReply: false
 });
 
-// Serve admin panel assets — no-store on JS/CSS so ESM module URLs are never
+// 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.
+// (images, html) keep no-cache. Local-only impact - admin is not public.
 await app.register(staticPlugin, {
     root: path.join(ROOT, 'admin'),
     prefix: '/admin/',
@@ -162,7 +162,7 @@ await fs.mkdir(pluginsDir,     { recursive: true });
 await fs.mkdir(blocksDir, {recursive: true});
 
 // ---------------------------------------------------------------------------
-// Pro feature — optional MongoDB connections
+// Pro feature - optional MongoDB connections
 // ---------------------------------------------------------------------------
 
 try {
@@ -173,11 +173,11 @@ try {
         app.addHook('onClose', shutdown);
     }
 } catch {
-    // No connections.json or empty — pure file-based mode (free version).
+    // No connections.json or empty - pure file-based mode (free version).
 }
 
 // ---------------------------------------------------------------------------
-// Roles — seed preset collection + load into cache
+// Roles - seed preset collection + load into cache
 // ---------------------------------------------------------------------------
 
 await seedRoles();
@@ -186,13 +186,13 @@ await seedUserProfiles();
 await ensureAllProfiles();
 await seedPresetCollections();
 await seedCoreProject();
-await seedDocsProject();  // built-in Domma Docs project — seeded disabled by default
+await seedDocsProject();  // built-in Domma Docs project - seeded disabled by default
 await seedDefaultBlocks();
 await seedDefaultComponents();
 await refreshComponentTagAllowlist();
 
 // ---------------------------------------------------------------------------
-// Menus — one-shot migration from legacy navigation.json + site footer links
+// Menus - one-shot migration from legacy navigation.json + site footer links
 // ---------------------------------------------------------------------------
 
 try {
@@ -229,7 +229,7 @@ console.log(`[cache] driver=${cache.isEnabled() ? config.cache.driver : 'disable
 // stale pages. No-op on a cold memory cache; matters for the Redis driver.
 await cache.invalidateTags(['docs']);
 
-// Serve uploaded media files — nosniff prevents browsers rendering spoofed content types
+// Serve uploaded media files - nosniff prevents browsers rendering spoofed content types
 await app.register(staticPlugin, {
     root: mediaDir,
     prefix: '/media/',
@@ -239,7 +239,7 @@ await app.register(staticPlugin, {
     }
 });
 
-// Serve plugin admin/ and public/ subdirs only — block plugin.js, config.js, data/, etc.
+// Serve plugin admin/ and public/ subdirs only - block plugin.js, config.js, data/, etc.
 await app.register(async function pluginStaticScope(instance) {
   instance.addHook('onRequest', (request, reply, done) => {
     const relative = request.url.replace(/^\/plugins\//, '').split('?')[0];
@@ -265,7 +265,7 @@ await app.register(async function pluginStaticScope(instance) {
 });
 
 // ---------------------------------------------------------------------------
-// Global error handler — prevents stack trace leaks in production
+// Global error handler - prevents stack trace leaks in production
 // ---------------------------------------------------------------------------
 
 app.setErrorHandler((error, request, reply) => {
@@ -278,6 +278,24 @@ app.setErrorHandler((error, request, reply) => {
     return reply.code(statusCode).send({ error: message });
 });
 
+// ---------------------------------------------------------------------------
+// Admin API responses are never cacheable
+// ---------------------------------------------------------------------------
+// The admin SPA must always see the live state of the site - a stale list is
+// indistinguishable from a missing artefact, and the user is left arguing with
+// their own CMS. Everything under /api is no-store EXCEPT the two externally
+// consumable surfaces, which have their own caching contracts:
+//   /api/v1/*  - collection access by API token
+//   /api/x/*   - API Builder endpoints
+app.addHook('onSend', async (request, reply) => {
+    const url = request.raw.url || '';
+    if (!url.startsWith('/api/')) return;
+    if (url.startsWith('/api/v1/') || url.startsWith('/api/x/')) return;
+    reply.header('Cache-Control', 'no-store, must-revalidate');
+    reply.header('Pragma', 'no-cache');
+    reply.header('Expires', '0');
+});
+
 // ---------------------------------------------------------------------------
 // Auth API Routes (no authentication required on these endpoints themselves)
 // ---------------------------------------------------------------------------
@@ -374,10 +392,10 @@ for (const [name, plugin] of Object.entries(getLoadedPlugins())) {
 }
 
 // ---------------------------------------------------------------------------
-// Public Site (catch-all — must be last)
+// Public Site (catch-all - must be last)
 // ---------------------------------------------------------------------------
 
-// Domma Docs (request-time handbook) — dedicated /domma-docs(/*) prefix that
+// Domma Docs (request-time handbook) - dedicated /domma-docs(/*) prefix that
 // out-prioritises the catch-all; must be registered before it.
 const { docsPublicRoutes } = await import('./routes/docs-public.js');
 await app.register(docsPublicRoutes);

package/server/services/actions.js

@@ -1,17 +1,17 @@
 /**
- * Actions Service (Pro — requires MongoDB)
+ * Actions Service (Pro - requires MongoDB)
  *
  * 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.
  *
  * 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
+ *   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
+ *   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.id}}         → source entry id
@@ -23,7 +23,7 @@
  *   {{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
+ * Note: execution is not transactional - partial results are returned on failure
  * with a `stepsCompleted` count.
  */
 import {v4 as uuidv4} from 'uuid';
@@ -151,16 +151,16 @@ async function executeStep(step, collection, entry, context) {
         }
 
         /*
-         * createInCollection — append an entry to another collection without
+         * 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;
+         *   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> }
@@ -303,7 +303,7 @@ export async function createAction(data, userId = null) {
             confirmMessage: trigger?.confirmMessage || null
         },
         steps,
-        // State-machine transition — when set, the action is gated by the
+        // 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).
@@ -399,12 +399,12 @@ export async function listActionsForCollection(collectionSlug) {
  *   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 —
+ * 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
+ * @param {object} [user]         - { role } - anonymous if missing
  * @returns {Promise<object[]>}
  */
 export async function listTransitionsForEntry(collectionSlug, entry, user = null) {
@@ -414,7 +414,7 @@ export async function listTransitionsForEntry(collectionSlug, entry, user = null
     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
+    // 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);
@@ -446,7 +446,7 @@ export async function listTransitionsForEntry(collectionSlug, entry, user = null
 
 /**
  * Execute an action against a specific collection entry.
- * Steps run sequentially — not transactional.
+ * Steps run sequentially - not transactional.
  * Returns partial results with stepsCompleted count on failure.
  *
  * @param {string} slug             - Action slug
@@ -469,7 +469,7 @@ export async function executeAction(slug, entryId, { user = null } = {}) {
         throw err;
     }
 
-    // State-machine guard — an action with a transition config only runs when
+    // 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
@@ -480,7 +480,7 @@ export async function executeAction(slug, entryId, { user = null } = {}) {
         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(', ')}`);
+            const err = new Error(`Cannot apply "${action.title}" - current ${t.field} is "${currentValue ?? '(none)'}", allowed: ${allowed.join(', ')}`);
             err.statusCode = 409;
             throw err;
         }

package/server/services/adapters/FileAdapter.js

@@ -1,5 +1,5 @@
 /**
- * FileAdapter — file-based storage adapter for Collection entries.
+ * FileAdapter - file-based storage adapter for Collection entries.
  *
  * Stores entries in `data.json` inside the collection directory.
  * This is the default adapter for all collections and the only adapter
@@ -56,7 +56,7 @@ export class FileAdapter {
      *
      * `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;
+     * DSL - see `filterEngine.js` for operator syntax. Both may be combined;
      * search runs first, then filter.
      *
      * @param {string} slug

package/server/services/adapters/MongoAdapter.js

@@ -1,10 +1,10 @@
 /**
- * MongoAdapter — MongoDB storage adapter for Collection entries. (Pro feature)
+ * MongoAdapter - MongoDB storage adapter for Collection entries. (Pro feature)
  *
  * Each CMS collection maps to a MongoDB collection prefixed with `cms_`
  * (e.g. slug "contacts" → MongoDB collection "cms_contacts").
  *
- * Entry format is preserved: { id, data, meta } — identical to FileAdapter output.
+ * Entry format is preserved: { id, data, meta } - identical to FileAdapter output.
  * MongoDB's _id field is stripped from all returned documents.
  *
  * Adapter interface:
@@ -66,7 +66,7 @@ export class MongoAdapter {
      * and structured filtering.
      *
      * `filter` is translated to native MongoDB query operators via
-     * `filterEngine.toMongoQuery()` and pushed down to the database — page
+     * `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
@@ -200,7 +200,7 @@ export class MongoAdapter {
 
     /**
      * Drop the backing MongoDB collection entirely (documents, indexes and
-     * the namespace). Used when the CMS collection itself is deleted —
+     * the namespace). Used when the CMS collection itself is deleted -
      * clear() only removes documents and would leave `cms_<slug>` behind.
      *
      * Deliberately bypasses _col(): that helper ensures the unique index,
@@ -213,7 +213,7 @@ export class MongoAdapter {
         try {
             await this._db.collection(`${PREFIX}${slug}`).drop();
         } catch (err) {
-            // Already absent — nothing to drop.
+            // Already absent - nothing to drop.
             if (err.codeName !== 'NamespaceNotFound') throw err;
         }
         this._ensured.delete(slug);

package/server/services/apiEndpoints.js

@@ -5,12 +5,12 @@
  *
  * Definitions are DATA, never code: entries in the file-based `api-endpoints`
  * preset collection. A definition binds a URL path (with `:param` segments)
- * to a collection query — fixed filters whose values may carry
+ * to a collection query - fixed filters whose values may carry
  * `{{params.<name>}}` / `{{query.<name>}}` placeholders, sort/limit, a read
  * field allowlist, and an auth mode (public / token / role) that reuses the
  * exact machinery of the public collections API.
  *
- * Substituted values only ever feed the filterEngine — there is no eval and
+ * Substituted values only ever feed the filterEngine - there is no eval and
  * no way for a definition to execute code.
  */
 import {createEntry, deleteEntry, getCollection, getEntry, listEntries, updateEntry} from './collections.js';
@@ -42,7 +42,7 @@ function invalidateRegistry() {
     registry = null;
 }
 
-// Generic admin collection endpoints emit these for ALL collections — the
+// Generic admin collection endpoints emit these for ALL collections - the
 // service's own mutations invalidate directly, this catches edits made
 // through the admin entries grid.
 for (const ev of ['collection:entryCreated', 'collection:entryUpdated', 'collection:entryDeleted']) {
@@ -79,7 +79,7 @@ function sanitise(entry) {
 }
 
 /**
- * Normalise a path to its shape for duplicate detection — every `:param`
+ * Normalise a path to its shape for duplicate detection - every `:param`
  * segment collapses to `:` so `/a/:x` and `/a/:y` are the same shape.
  *
  * @param {string} path
@@ -113,12 +113,12 @@ async function validateDefinition(data, {excludeId} = {}) {
     if (schema.systemManaged || schema.preset) {
         throw new Error(`Collection "${data.collection}" is system-managed and cannot be exposed`);
     }
-    // An endpoint may only expose collections from its own project or core —
+    // An endpoint may only expose collections from its own project or core -
     // the URL namespace must match where the data lives, and scoped users
     // must not be able to publish another project's data through their own.
     const collectionProject = resolveArtefactProject(schema);
     if (collectionProject !== data.project && collectionProject !== CORE_PROJECT_SLUG) {
-        throw new Error(`Collection "${data.collection}" belongs to project "${collectionProject}" — an endpoint may only expose collections from its own project or core`);
+        throw new Error(`Collection "${data.collection}" belongs to project "${collectionProject}" - an endpoint may only expose collections from its own project or core`);
     }
 
     if (typeof data.path !== 'string' || !data.path.startsWith('/')) {
@@ -131,13 +131,13 @@ async function validateDefinition(data, {excludeId} = {}) {
         if (PARAM_SEGMENT_RE.test(seg)) {
             paramNames.add(seg.slice(1));
         } else if (!STATIC_SEGMENT_RE.test(seg)) {
-            throw new Error(`Invalid path segment "${seg}" — use lowercase letters, numbers, hyphens, or :param`);
+            throw new Error(`Invalid path segment "${seg}" - use lowercase letters, numbers, hyphens, or :param`);
         }
     }
 
     const auth = data.auth || 'public';
     if (auth !== 'public' && auth !== 'token' && !getRoleMap().has(auth)) {
-        throw new Error(`Unknown auth mode "${auth}" — use public, token, or a role name`);
+        throw new Error(`Unknown auth mode "${auth}" - use public, token, or a role name`);
     }
 
     if (data.mode != null && !MODES.includes(data.mode)) throw new Error('mode must be "list" or "single"');
@@ -170,7 +170,7 @@ async function validateDefinition(data, {excludeId} = {}) {
         }
     }
 
-    // Duplicate shape per project — `/a/:x` and `/a/:y` collide.
+    // Duplicate shape per project - `/a/:x` and `/a/:y` collide.
     const shape = pathShape(data.path);
     const {entries} = await listEntries(API_ENDPOINTS_COLLECTION_SLUG, {limit: 0});
     const clash = entries.find(e =>
@@ -216,7 +216,7 @@ export async function createEndpoint(input) {
 
 /**
  * Update an endpoint. The project binding is immutable (it is the endpoint's
- * URL namespace) — create a new endpoint to move one.
+ * URL namespace) - create a new endpoint to move one.
  *
  * @param {string} id
  * @param {object} patch
@@ -387,14 +387,14 @@ function substituteFilter(filterTemplate, params, query) {
 }
 
 /**
- * Query keys that control the query envelope, not a field to filter on — they
+ * Query keys that control the query envelope, not a field to filter on - they
  * must never be interpreted as ad-hoc filters (otherwise `?limit=5` would
  * filter a field called "limit").
  */
 const RESERVED_QUERY_KEYS = new Set(['page', 'limit', 'sort', 'order', 'search']);
 
 /**
- * The fields an endpoint is allowed to expose — and therefore the only fields
+ * The fields an endpoint is allowed to expose - and therefore the only fields
  * an ad-hoc query filter may touch. A read-field allowlist, when set, is the
  * boundary; otherwise every declared collection field (plus the always-safe
  * `id` / `createdBy` pseudo-fields) is fair game. Restricting ad-hoc filters
@@ -415,7 +415,7 @@ async function exposedFieldSet(def) {
  * Collect ad-hoc filters from the request query, layered UNDER the definition's
  * declared filters: reserved envelope keys are skipped, values must target an
  * exposed field, and a field already constrained by a declared filter is left
- * to the declaration (the curated filter always wins — a caller cannot loosen
+ * to the declaration (the curated filter always wins - a caller cannot loosen
  * or override it).
  *
  * @param {Record<string, unknown>} query
@@ -442,7 +442,7 @@ function collectAdHocFilter(query, exposed, declaredFields) {
  *
  * The final filter is the definition's declared filters (fixed literals,
  * {{params.x}}, {{query.x}}) with ad-hoc query-string filters layered beneath
- * them — declared always wins on any overlap.
+ * them - declared always wins on any overlap.
  *
  * @param {object} def
  * @param {Record<string, string>} params - Decoded path params
@@ -458,7 +458,7 @@ export async function executeEndpoint(def, params, query) {
     const adhoc = collectAdHocFilter(q, exposed, declaredFields);
     const filter = {...adhoc, ...declared}; // declared wins on any key collision
 
-    // Envelope controls — the reserved query keys tune pagination and sort
+    // Envelope controls - the reserved query keys tune pagination and sort
     // rather than filter (list mode only). The definition's own limit is the
     // ceiling: a caller may page/shrink within it but never pull more than the
     // endpoint intends; sort is restricted to exposed fields.