domma-cms 0.17.0 → 0.21.0

package/server/services/collections.js

@@ -11,6 +11,7 @@ import path from 'path';
 import {v4 as uuidv4} from 'uuid';
 import {config} from '../config.js';
 import {getAdapter, invalidate} from './adapterRegistry.js';
+import * as cache from './cache/index.js';
 
 const COLLECTIONS_DIR = path.resolve(config.content.collectionsDir);
 
@@ -120,7 +121,7 @@ export async function getCollection(slug) {
  * @returns {Promise<object>} Created schema
  * @throws {Error} If a collection with that slug already exists
  */
-export async function createCollection({title, slug, description = '', fields = [], api = {}, storage, bundled, plugin}) {
+export async function createCollection({title, slug, description = '', fields = [], api = {}, storage, bundled, plugin, meta}) {
     await ensureDir();
     const finalSlug = slug ? slugify(slug) : slugify(title);
     if (!finalSlug) throw new Error('Could not derive a slug from the title');
@@ -143,12 +144,14 @@ export async function createCollection({title, slug, description = '', fields =
         storage: storage || {adapter: 'file'},
         ...(bundled ? {bundled: true} : {}),
         ...(plugin ? {plugin} : {}),
+        ...(meta != null && {meta}),
         createdAt: now,
         updatedAt: now
     };
 
     await writeSchema(schema);
     await (await getAdapter(finalSlug)).insertMany(finalSlug, []);
+    await cache.invalidateTags([`collection:${finalSlug}`]);
     return schema;
 }
 
@@ -191,6 +194,7 @@ export async function updateCollection(slug, updates) {
 
     // Invalidate cached adapter in case storage config changed.
     invalidate(slug);
+    await cache.invalidateTags([`collection:${slug}`]);
 
     return updated;
 }
@@ -218,6 +222,7 @@ export async function deleteCollection(slug) {
 
     invalidate(slug);
     await fs.rm(collectionDir(slug), { recursive: true, force: true });
+    await cache.invalidateTags([`collection:${slug}`]);
 }
 
 // ---------------------------------------------------------------------------
@@ -227,6 +232,10 @@ export async function deleteCollection(slug) {
 /**
  * Validate entry data against a collection schema.
  *
+ * Reference-field validation (target id existence) requires async I/O and is
+ * therefore done in `validateReferences()` — called from create/update paths
+ * after this synchronous shape check passes.
+ *
  * @param {object} schema
  * @param {object} data
  * @returns {{ valid: boolean, errors: string[] }}
@@ -243,27 +252,93 @@ export function validateEntryData(schema, data) {
     return { valid: errors.length === 0, errors };
 }
 
+/**
+ * Asynchronously validate that every reference field's value points to an
+ * entry that actually exists in the target collection. Single-valued and
+ * array-valued references are both supported.
+ *
+ * Empty/null references are skipped here — the required check in
+ * `validateEntryData()` handles those.
+ *
+ * @param {object} schema
+ * @param {object} data
+ * @returns {Promise<string[]>} List of error messages (empty if all OK)
+ */
+export async function validateReferences(schema, data) {
+    const errors = [];
+    for (const field of (schema.fields || [])) {
+        if (field.type !== 'reference') continue;
+        const targetSlug = field.reference?.collection;
+        if (!targetSlug) continue;             // misconfigured schema — skip silently
+
+        const raw = data[field.name];
+        if (raw === undefined || raw === null || raw === '') continue;
+
+        // Support arrays (one-to-many references) and single ids
+        const ids = Array.isArray(raw) ? raw.filter(Boolean) : [raw];
+        if (!ids.length) continue;
+
+        const adapter = await getAdapter(targetSlug);
+        for (const id of ids) {
+            const target = await adapter.get(targetSlug, String(id));
+            if (!target) {
+                errors.push(`"${field.label || field.name}" → no entry "${id}" in "${targetSlug}"`);
+            }
+        }
+    }
+    return errors;
+}
+
 // ---------------------------------------------------------------------------
 // Entry operations — delegated to storage adapter
 // ---------------------------------------------------------------------------
 
 /**
- * List entries with optional pagination, sorting, and search.
+ * List entries with optional pagination, sorting, free-text search,
+ * structured filtering, and reference resolution.
+ *
+ * Delegates to the configured adapter (File or Mongo). Both adapters honour
+ * identical option semantics — see `filterEngine.js` for the filter DSL.
+ *
+ * @example
+ *   // Paginated, sorted, simple search
+ *   await listEntries('jobs', { page: 1, limit: 20, sort: 'postedAt', search: 'engineer' });
+ *
+ * @example
+ *   // Structured filter — full-time London roles paying £50k+
+ *   await listEntries('jobs', { filter: { location: 'London', type: 'full-time', salary_gte: 50000 } });
+ *
+ * @example
+ *   // Row-level scoping — applications belonging to one user
+ *   await listEntries('applications', { filter: { createdBy: userId } });
+ *
+ * @example
+ *   // Resolve reference fields — each entry gets `_refs.<field>` with display labels
+ *   await listEntries('applications', { resolveRefs: true });
+ *   // → entries[0]._refs.jobId === { id, display: 'Senior Engineer', missing: false, link: null }
  *
  * @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']  - Field name or 'createdAt'
+ * @param {string}                    [opts.order='desc']      - 'asc' | 'desc'
+ * @param {string}                    [opts.search]            - Substring match across all fields
+ * @param {Record<string, unknown>}   [opts.filter]            - Structured filter; see filterEngine.js
+ * @param {boolean}                   [opts.resolveRefs=false] - Batch-resolve reference fields to display labels
  * @returns {Promise<{ entries: object[], total: number, page: number, limit: number }>}
+ * @throws {Error} If collection slug does not exist
  */
 export async function listEntries(slug, opts = {}) {
     const schema = await getCollection(slug);
     if (!schema) throw new Error(`Collection "${slug}" not found`);
     const adapter = await getAdapter(slug);
-    return adapter.list(slug, opts);
+    const result = await adapter.list(slug, opts);
+    if (opts.resolveRefs) {
+        const {resolveReferences} = await import('./references.js');
+        await resolveReferences(schema, result.entries);
+    }
+    return result;
 }
 
 /**
@@ -296,6 +371,9 @@ export async function createEntry(slug, data, { createdBy = null, source = 'admi
     const { valid, errors } = validateEntryData(schema, data);
     if (!valid) throw new Error(`Validation failed: ${errors.join('; ')}`);
 
+    const refErrors = await validateReferences(schema, data);
+    if (refErrors.length) throw new Error(`Validation failed: ${refErrors.join('; ')}`);
+
     const now   = new Date().toISOString();
     const entry = {
         id:   uuidv4(),
@@ -304,7 +382,9 @@ export async function createEntry(slug, data, { createdBy = null, source = 'admi
     };
 
     const adapter = await getAdapter(slug);
-    return adapter.insert(slug, entry);
+    const created = await adapter.insert(slug, entry);
+    await cache.invalidateTags([`collection:${slug}`]);
+    return created;
 }
 
 /**
@@ -323,6 +403,9 @@ export async function updateEntry(slug, entryId, data) {
     const { valid, errors } = validateEntryData(schema, data);
     if (!valid) throw new Error(`Validation failed: ${errors.join('; ')}`);
 
+    const refErrors = await validateReferences(schema, data);
+    if (refErrors.length) throw new Error(`Validation failed: ${refErrors.join('; ')}`);
+
     const adapter  = await getAdapter(slug);
     const existing = await adapter.get(slug, entryId);
     if (!existing) throw new Error('Entry not found');
@@ -333,7 +416,9 @@ export async function updateEntry(slug, entryId, data) {
         meta: { ...existing.meta, updatedAt: new Date().toISOString() }
     };
 
-    return adapter.update(slug, entryId, updated);
+    const result = await adapter.update(slug, entryId, updated);
+    await cache.invalidateTags([`collection:${slug}`]);
+    return result;
 }
 
 /**
@@ -346,7 +431,9 @@ export async function updateEntry(slug, entryId, data) {
  */
 export async function deleteEntry(slug, entryId) {
     const adapter = await getAdapter(slug);
-    return adapter.remove(slug, entryId);
+    const result = await adapter.remove(slug, entryId);
+    await cache.invalidateTags([`collection:${slug}`]);
+    return result;
 }
 
 /**
@@ -359,7 +446,9 @@ export async function clearEntries(slug) {
     const schema = await getCollection(slug);
     if (!schema) throw new Error(`Collection "${slug}" not found`);
     const adapter = await getAdapter(slug);
-    return adapter.clear(slug);
+    const result = await adapter.clear(slug);
+    await cache.invalidateTags([`collection:${slug}`]);
+    return result;
 }
 
 // ---------------------------------------------------------------------------
@@ -433,6 +522,7 @@ export async function importEntries(slug, incoming, { createdBy = null } = {}) {
     const adapter = await getAdapter(slug);
     if (valid.length > 0) {
         await adapter.insertMany(slug, valid);
+        await cache.invalidateTags([`collection:${slug}`]);
     }
 
     return { imported: valid.length, skipped, errors };

package/server/services/content.js

@@ -9,6 +9,7 @@ import {parseMarkdown, serialiseMarkdown} from './markdown.js';
 import {config} from '../config.js';
 import {hooks} from './hooks.js';
 import {createVersion, deleteAllVersions, renameVersionDir} from './versions.js';
+import * as cache from './cache/index.js';
 
 const CONTENT_DIR = config.content.contentDir;
 const PAGES_DIR = path.join(CONTENT_DIR, 'pages');
@@ -27,7 +28,14 @@ const MEDIA_DIR = config.content.mediaDir;
 export async function listPages() {
     const files = await collectMdFiles(PAGES_DIR);
     const pages = await Promise.all(files.map(filePath => readPageFile(filePath)));
-    return pages.sort((a, b) => (a.sortOrder ?? 99) - (b.sortOrder ?? 99) || a.title.localeCompare(b.title));
+    pages.sort((a, b) => (a.sortOrder ?? 99) - (b.sortOrder ?? 99) || a.title.localeCompare(b.title));
+    const {getProjectForPage} = await import('./projects.js');
+    for (const page of pages) {
+        const url = page.url || page.urlPath || '/';
+        const explicit = (page.project === undefined) ? undefined : page.project;
+        page.resolvedProject = await getProjectForPage(url, explicit);
+    }
+    return pages;
 }
 
 /**
@@ -35,12 +43,15 @@ export async function listPages() {
  * The empty string / '/' resolves to index.md.
  *
  * @param {string} urlPath
+ * @param {object} [opts]
+ * @param {object|null} [opts.user] - Forwarded to parseMarkdown so shortcodes
+ *   that gate output by role (currently `[menu]`) can filter correctly.
  * @returns {Promise<object|null>}
  */
-export async function getPage(urlPath) {
+export async function getPage(urlPath, opts = {}) {
     const filePath = await resolveExistingFilePath(urlPath);
     try {
-        return await readPageFile(filePath);
+        return await readPageFile(filePath, {user: opts.user || null});
     } catch {
         return null;
     }
@@ -77,6 +88,7 @@ export async function createPage(urlPath, frontmatter, body) {
 
     await fs.writeFile(filePath, serialiseMarkdown(meta, body || ''), 'utf8');
     const page = await readPageFile(filePath);
+    await cache.invalidateTags([`page:${urlPath}`, 'sitemap']);
     hooks.emit('content:pageCreated', {page, urlPath});
     return page;
 }
@@ -111,6 +123,7 @@ export async function updatePage(urlPath, frontmatter, body, {author} = {}) {
 
     await fs.writeFile(filePath, serialiseMarkdown(meta, body ?? existingContent), 'utf8');
     const page = await readPageFile(filePath);
+    await cache.invalidateTags([`page:${urlPath}`, 'sitemap']);
     hooks.emit('content:pageUpdated', {page, urlPath});
     return page;
 }
@@ -128,6 +141,7 @@ export async function renamePage(oldUrlPath, newUrlPath) {
     const newFile = urlPathToFilePath(newUrlPath);
     await fs.mkdir(path.dirname(newFile), { recursive: true });
     await fs.rename(oldFile, newFile);
+    await cache.invalidateTags([`page:${oldUrlPath}`, `page:${newUrlPath}`, 'sitemap']);
     try {
         await renameVersionDir(oldUrlPath, newUrlPath);
     } catch {
@@ -144,6 +158,7 @@ export async function renamePage(oldUrlPath, newUrlPath) {
 export async function deletePage(urlPath) {
     const filePath = await resolveExistingFilePath(urlPath);
     await fs.unlink(filePath);
+    await cache.invalidateTags([`page:${urlPath}`, 'sitemap']);
     hooks.emit('content:pageDeleted', {urlPath});
     try {
         await deleteAllVersions(urlPath);
@@ -284,13 +299,17 @@ async function collectMdFiles(dir) {
  * Read and parse a single .md file, injecting the derived urlPath.
  *
  * @param {string} filePath
+ * @param {object} [opts]
+ * @param {object|null} [opts.user] - Forwarded to parseMarkdown so the
+ *   `[menu]` shortcode can filter items by per-user visibility. Defaults to
+ *   anonymous (null) — most callers (listings, admin previews) leave this unset.
  * @returns {Promise<object>}
  */
-async function readPageFile(filePath) {
+async function readPageFile(filePath, opts = {}) {
     const raw = await fs.readFile(filePath, 'utf8');
-    const { data, content, html, usedComponents } = await parseMarkdown(raw);
+    const { data, content, html, usedComponents, tags } = await parseMarkdown(raw, {user: opts.user || null});
     const urlPath = filePathToUrlPath(filePath);
-    return { ...data, urlPath, content, html, usedComponents };
+    return { ...data, urlPath, content, html, usedComponents, tags };
 }
 
 /**

package/server/services/filterEngine.js

@@ -0,0 +1,281 @@
+/**
+ * Filter Engine — Structured Query Translator for Collection Entries
+ *
+ * Defines the structured-filter DSL used by `listEntries` and the `[collection]`
+ * shortcode (via `where_*` attributes). One module, two outputs:
+ *
+ *   - applyFilter(entries, filter)  → in-memory filtering for FileAdapter
+ *   - toMongoQuery(filter)          → MongoDB query for MongoAdapter
+ *
+ * Both adapters share the same operator semantics so a page authored against
+ * the file adapter behaves identically on Mongo.
+ *
+ * ---------------------------------------------------------------------------
+ * Operator suffixes
+ * ---------------------------------------------------------------------------
+ * Filter keys are `<field>` (defaults to _eq) or `<field>_<op>`. Operators:
+ *
+ *   _eq        equal                          → "London"
+ *   _ne        not equal                      → "London"
+ *   _gt        greater than                   → 100
+ *   _gte       greater than or equal          → 100
+ *   _lt        less than                      → 100
+ *   _lte       less than or equal             → 100
+ *   _in        value in comma-separated list  → "remote,hybrid"
+ *   _nin       value not in list              → "remote,hybrid"
+ *   _contains  substring match (case-insens.) → "engineer"
+ *   _starts    starts-with (case-insens.)     → "Lon"
+ *   _ends      ends-with (case-insens.)       → "ish"
+ *   _exists    field is present and non-null  → "true" | "false"
+ *
+ * ---------------------------------------------------------------------------
+ * Value coercion
+ * ---------------------------------------------------------------------------
+ * Filter values arrive as strings (from query params and shortcode attrs).
+ * Numeric operators (_gt/_gte/_lt/_lte) coerce both sides to Number when
+ * possible; all comparisons fall back to string compare on NaN. _in / _nin
+ * split on `,` and trim each value. _exists accepts "true" | "false" | "1" | "0".
+ *
+ * Field paths support dot notation against `entry.data` — e.g.
+ *   { 'address.city_eq': 'London' } → matches entry.data.address.city
+ *
+ * ---------------------------------------------------------------------------
+ * Special pseudo-fields
+ * ---------------------------------------------------------------------------
+ *   createdBy   — matches against entry.meta.createdBy (not entry.data.*)
+ *   id          — matches against entry.id (top-level)
+ *
+ * Anything else maps to a path inside entry.data.
+ */
+
+/** Recognised operator suffixes — order matters for greedy matching (_gte before _gt). */
+export const OPERATORS = [
+    '_eq', '_ne', '_gte', '_lte', '_gt', '_lt',
+    '_in', '_nin', '_contains', '_starts', '_ends', '_exists'
+];
+
+/**
+ * Parse a filter key into `{ field, op }`.
+ *
+ * @example
+ *   parseFilterKey('location')         → { field: 'location', op: '_eq' }
+ *   parseFilterKey('salary_gte')       → { field: 'salary',   op: '_gte' }
+ *   parseFilterKey('address.city_eq')  → { field: 'address.city', op: '_eq' }
+ *
+ * @param {string} key
+ * @returns {{ field: string, op: string }}
+ */
+export function parseFilterKey(key) {
+    for (const op of OPERATORS) {
+        if (key.endsWith(op)) {
+            return { field: key.slice(0, -op.length), op };
+        }
+    }
+    return { field: key, op: '_eq' };
+}
+
+/**
+ * Resolve a dot-path against an entry, with two special-cased pseudo-fields.
+ *
+ * @param {object} entry
+ * @param {string} field
+ * @returns {unknown}
+ */
+function resolveField(entry, field) {
+    if (field === 'createdBy') return entry.meta?.createdBy;
+    if (field === 'id')        return entry.id;
+
+    const path = field.split('.');
+    let val    = entry.data;
+    for (const k of path) {
+        if (val == null) return undefined;
+        val = val[k];
+    }
+    return val;
+}
+
+/**
+ * Coerce a string to a number if it round-trips; otherwise return the original.
+ *
+ * @param {unknown} v
+ * @returns {unknown}
+ */
+function maybeNumber(v) {
+    if (typeof v === 'number') return v;
+    if (typeof v !== 'string') return v;
+    const n = Number(v);
+    return Number.isFinite(n) && String(n) === v.trim() ? n : v;
+}
+
+/**
+ * Coerce a string to a boolean (for _exists).
+ *
+ * @param {unknown} v
+ * @returns {boolean}
+ */
+function toBool(v) {
+    if (typeof v === 'boolean') return v;
+    return v === 'true' || v === '1' || v === 1 || v === true;
+}
+
+/**
+ * Apply one operator to a single entry-side value and filter-side value.
+ *
+ * @param {string}  op
+ * @param {unknown} entryVal
+ * @param {unknown} filterVal
+ * @returns {boolean}
+ */
+function applyOp(op, entryVal, filterVal) {
+    switch (op) {
+        case '_eq': {
+            // Loose equality: number-coerce both sides for numeric fields stored as strings.
+            const a = maybeNumber(entryVal);
+            const b = maybeNumber(filterVal);
+            // Match-in-array: if entry value is an array, treat _eq as "contains".
+            if (Array.isArray(entryVal)) return entryVal.map(maybeNumber).includes(b);
+            return a === b || String(a) === String(b);
+        }
+        case '_ne': {
+            const a = maybeNumber(entryVal);
+            const b = maybeNumber(filterVal);
+            if (Array.isArray(entryVal)) return !entryVal.map(maybeNumber).includes(b);
+            return !(a === b || String(a) === String(b));
+        }
+        case '_gt':  return maybeNumber(entryVal) >  maybeNumber(filterVal);
+        case '_gte': return maybeNumber(entryVal) >= maybeNumber(filterVal);
+        case '_lt':  return maybeNumber(entryVal) <  maybeNumber(filterVal);
+        case '_lte': return maybeNumber(entryVal) <= maybeNumber(filterVal);
+        case '_in': {
+            const list = String(filterVal).split(',').map(s => maybeNumber(s.trim()));
+            if (Array.isArray(entryVal)) {
+                return entryVal.map(maybeNumber).some(v => list.includes(v));
+            }
+            return list.includes(maybeNumber(entryVal));
+        }
+        case '_nin': {
+            const list = String(filterVal).split(',').map(s => maybeNumber(s.trim()));
+            if (Array.isArray(entryVal)) {
+                return !entryVal.map(maybeNumber).some(v => list.includes(v));
+            }
+            return !list.includes(maybeNumber(entryVal));
+        }
+        case '_contains':
+            return String(entryVal ?? '').toLowerCase().includes(String(filterVal).toLowerCase());
+        case '_starts':
+            return String(entryVal ?? '').toLowerCase().startsWith(String(filterVal).toLowerCase());
+        case '_ends':
+            return String(entryVal ?? '').toLowerCase().endsWith(String(filterVal).toLowerCase());
+        case '_exists': {
+            const present = entryVal !== undefined && entryVal !== null && entryVal !== '';
+            return toBool(filterVal) ? present : !present;
+        }
+        default:
+            // Unknown operator → fail open (no match) rather than throw, so a
+            // typo in a page shortcode doesn't 500 the entire page render.
+            return false;
+    }
+}
+
+/**
+ * Apply a filter object to an in-memory list of entries (FileAdapter path).
+ * Combines conditions with AND. Returns matching entries in original order.
+ *
+ * @example
+ *   applyFilter(entries, { location: 'London', salary_gte: '50000' })
+ *
+ * @param {object[]} entries
+ * @param {Record<string, unknown>} filter
+ * @returns {object[]}
+ */
+export function applyFilter(entries, filter) {
+    if (!filter || Object.keys(filter).length === 0) return entries;
+
+    return entries.filter(entry => {
+        for (const [key, filterVal] of Object.entries(filter)) {
+            if (filterVal === undefined || filterVal === null || filterVal === '') continue;
+            const { field, op } = parseFilterKey(key);
+            const entryVal      = resolveField(entry, field);
+            if (!applyOp(op, entryVal, filterVal)) return false;
+        }
+        return true;
+    });
+}
+
+/**
+ * Translate a filter object to a MongoDB query document (MongoAdapter path).
+ * Fields are mapped to the stored shape: `data.<field>`, except for special
+ * pseudo-fields (`createdBy` → `meta.createdBy`, `id` → `id`).
+ *
+ * Conditions are combined with AND. Multiple operators on the same field are
+ * merged into a single sub-document — e.g. `{ salary_gte: 100, salary_lte: 200 }`
+ * becomes `{ 'data.salary': { $gte: 100, $lte: 200 } }`.
+ *
+ * @param {Record<string, unknown>} filter
+ * @returns {object} Mongo query document
+ */
+export function toMongoQuery(filter) {
+    if (!filter || Object.keys(filter).length === 0) return {};
+
+    const opMap = {
+        _eq: '$eq',
+        _ne: '$ne',
+        _gt: '$gt',
+        _gte: '$gte',
+        _lt: '$lt',
+        _lte: '$lte',
+        _in: '$in',
+        _nin: '$nin'
+    };
+
+    const query = {};
+
+    for (const [key, filterVal] of Object.entries(filter)) {
+        if (filterVal === undefined || filterVal === null || filterVal === '') continue;
+        const { field, op } = parseFilterKey(key);
+
+        const path = field === 'createdBy' ? 'meta.createdBy'
+            : field === 'id' ? 'id'
+            : `data.${field}`;
+
+        query[path] = query[path] || {};
+
+        if (opMap[op]) {
+            const value = (op === '_in' || op === '_nin')
+                ? String(filterVal).split(',').map(s => maybeNumber(s.trim()))
+                : maybeNumber(filterVal);
+            query[path][opMap[op]] = value;
+        } else if (op === '_contains') {
+            query[path].$regex   = escapeRegex(String(filterVal));
+            query[path].$options = 'i';
+        } else if (op === '_starts') {
+            query[path].$regex   = '^' + escapeRegex(String(filterVal));
+            query[path].$options = 'i';
+        } else if (op === '_ends') {
+            query[path].$regex   = escapeRegex(String(filterVal)) + '$';
+            query[path].$options = 'i';
+        } else if (op === '_exists') {
+            query[path].$exists = toBool(filterVal);
+            if (toBool(filterVal)) query[path].$ne = null;
+        }
+    }
+
+    // Collapse single-operator sub-docs that only contain $eq back to a flat value.
+    for (const [path, sub] of Object.entries(query)) {
+        if (sub && typeof sub === 'object' && Object.keys(sub).length === 1 && '$eq' in sub) {
+            query[path] = sub.$eq;
+        }
+    }
+
+    return query;
+}
+
+/**
+ * Escape regex metacharacters in a user-supplied substring.
+ *
+ * @param {string} s
+ * @returns {string}
+ */
+function escapeRegex(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/server/services/forms.js

@@ -6,6 +6,7 @@
 import fs from 'fs/promises';
 import path from 'path';
 import {fileURLToPath} from 'url';
+import * as cache from './cache/index.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const ROOT      = path.resolve(__dirname, '..', '..');
@@ -43,6 +44,7 @@ export async function writeForm(slug, data) {
     await ensureFormsDir();
     const file = path.join(FORMS_DIR, `${slug}.json`);
     await fs.writeFile(file, JSON.stringify(data, null, 4) + '\n', 'utf8');
+    await cache.invalidateTags([`form:${slug}`]);
 }
 
 /**
@@ -78,6 +80,7 @@ export async function listForms() {
  */
 export async function deleteForm(slug) {
     await fs.unlink(path.join(FORMS_DIR, `${slug}.json`));
+    await cache.invalidateTags([`form:${slug}`]);
 }
 
 /**

package/server/services/hooks.js

@@ -46,6 +46,54 @@ export function getShortcodeProcessors() {
   return [..._shortcodes.values()].sort((a, b) => a.priority - b.priority);
 }
 
+// ---------------------------------------------------------------------------
+// Menu-location registry — delegated to server/services/menus.js
+// ---------------------------------------------------------------------------
+
+/**
+ * Register a menu-location slot. Plugins call this from their setupPlugin to
+ * declare slots where a curated menu can be rendered (e.g. a sidebar widget).
+ * The slot then appears in the admin Locations editor and can be filled with
+ * any menu the admin chooses.
+ *
+ * @param {string} slot - lower-snake-case slot name (e.g. 'sidebar')
+ * @param {{label?:string, description?:string, maxDepth?:number}} def
+ */
+export async function registerMenuLocation(slot, def) {
+    const {registerLocation} = await import('./menus.js');
+    registerLocation(slot, {...def, source: def?.source || 'plugin'});
+}
+
+// ---------------------------------------------------------------------------
+// Admin sidebar items — plugin-registered runtime injection
+// ---------------------------------------------------------------------------
+
+const _registeredSidebarItems = [];
+
+/**
+ * Register a sidebar item from a plugin. Items are merged into the rendered
+ * admin sidebar at render time — they are NOT persisted into menu JSON.
+ * Plugins re-register on each server boot via their setupPlugin hook.
+ *
+ * @param {{parent?: string, item: {text: string, url: string, icon?: string, permission?: string, items?: object[]}}} opts
+ */
+export function registerSidebarItem(opts) {
+    if (!opts || !opts.item || typeof opts.item.text !== 'string') {
+        throw new Error('registerSidebarItem: opts.item.text is required');
+    }
+    _registeredSidebarItems.push({
+        parent: opts.parent || null,
+        item:   opts.item
+    });
+}
+
+/**
+ * @returns {Array<{parent: string|null, item: object}>}
+ */
+export function getRegisteredSidebarItems() {
+    return _registeredSidebarItems.slice();
+}
+
 // ---------------------------------------------------------------------------
 // 3. Sanitize rule extensions
 // ---------------------------------------------------------------------------