domma-cms 0.44.0 → 0.45.1

package/server/services/cache/index.js

@@ -61,7 +61,7 @@ export async function initCache(config = {}) {
  *
  * When turning on, re-initialise with the last config (or sensible defaults)
  * so a previously disabled cache gets a real driver. When turning off, keep
- * the driver in place but short-circuit reads/writes — preserves cached data
+ * the driver in place but short-circuit reads/writes - preserves cached data
  * if the user toggles back on. The persistence of this choice across restarts
  * is the caller's responsibility (the route handler writes to config/cache.json).
  */
@@ -69,12 +69,12 @@ export async function setEnabled(enabled) {
     if (Boolean(enabled) === _enabled) return;
     if (enabled) {
         if (_driver instanceof NoneDriver) {
-            // No usable driver yet — bootstrap one from last-known config.
+            // No usable driver yet - bootstrap one from last-known config.
             const cfg = {...(_lastConfig || {}), enabled: true};
             if (!cfg.driver || cfg.driver === 'none') cfg.driver = 'memory';
             await initCache(cfg);
         } else {
-            // Memory/Redis driver still live — flip the flag and preserve data.
+            // Memory/Redis driver still live - flip the flag and preserve data.
             _enabled = true;
         }
     } else {
@@ -110,7 +110,7 @@ export async function clear() {
 
 /**
  * List the cache's keys with their tags and expiry. Values are deliberately
- * excluded — cached entries can be megabytes of HTML.
+ * excluded - cached entries can be megabytes of HTML.
  * @returns {{key: string, tags: string[], expiresAt: number|null}[]}
  */
 export function listEntries() {
@@ -148,7 +148,7 @@ export function getStats() {
  * Get-or-set with in-flight coalescing.
  *
  * Producer may return either a raw value, or an object with a `_cacheTags`
- * array — those tags are merged into opts.tags before storing, and the
+ * array - those tags are merged into opts.tags before storing, and the
  * `_cacheTags` field is stripped from both the cached and returned value.
  * This lets producers report tags discovered during rendering (e.g. the
  * markdown pipeline noting embedded collection slugs) without the caller

package/server/services/collections.js

@@ -1,6 +1,6 @@
 /**
  * Collections Service
- * Schema-first data store — one directory per collection under content/collections/{slug}/.
+ * Schema-first data store - one directory per collection under content/collections/{slug}/.
  * Each collection has a schema.json (field definitions + API access config).
  *
  * Entry storage is delegated to the active adapter (FileAdapter or MongoAdapter).
@@ -65,11 +65,11 @@ function defaultApiAccess() {
 }
 
 // ---------------------------------------------------------------------------
-// Schema (collection) operations — always file-based
+// Schema (collection) operations - always file-based
 // ---------------------------------------------------------------------------
 
 /**
- * List all collections — reads all schema.json files and appends entryCount.
+ * List all collections - reads all schema.json files and appends entryCount.
  *
  * @returns {Promise<object[]>}
  */
@@ -93,7 +93,7 @@ export async function listCollections() {
     return results
         .filter(r => r.status === 'fulfilled')
         .map(r => r.value)
-        // Hand-rolled schemas can lack `title` — fall back to slug rather
+        // Hand-rolled schemas can lack `title` - fall back to slug rather
         // than crashing the whole listing (seen in the wild: a schema with
         // `name` instead of `title` 500'd /api/collections permanently).
         .sort((a, b) => String(a.title || a.slug || '').localeCompare(String(b.title || b.slug || '')));
@@ -215,7 +215,7 @@ export async function deleteCollection(slug) {
     if (!schema) throw new Error(`Collection "${slug}" not found`);
 
     // Remove adapter-side data first (handles MongoDB collections on
-    // non-file adapters). Prefer drop() — clear() only deletes documents
+    // non-file adapters). Prefer drop() - clear() only deletes documents
     // and leaves the backing Mongo collection + its unique index behind
     // forever.
     try {
@@ -228,7 +228,7 @@ export async function deleteCollection(slug) {
             }
         }
     } catch {
-        // Ignore errors — directory removal handles file-backed data.
+        // Ignore errors - directory removal handles file-backed data.
     }
 
     invalidate(slug);
@@ -244,7 +244,7 @@ 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
+ * therefore done in `validateReferences()` - called from create/update paths
  * after this synchronous shape check passes.
  *
  * @param {object} schema
@@ -268,7 +268,7 @@ export function validateEntryData(schema, data) {
  * 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
+ * Empty/null references are skipped here - the required check in
  * `validateEntryData()` handles those.
  *
  * @param {object} schema
@@ -280,7 +280,7 @@ export async function validateReferences(schema, data) {
     for (const field of (schema.fields || [])) {
         if (field.type !== 'reference') continue;
         const targetSlug = field.reference?.collection;
-        if (!targetSlug) continue;             // misconfigured schema — skip silently
+        if (!targetSlug) continue;             // misconfigured schema - skip silently
 
         const raw = data[field.name];
         if (raw === undefined || raw === null || raw === '') continue;
@@ -301,7 +301,7 @@ export async function validateReferences(schema, data) {
 }
 
 // ---------------------------------------------------------------------------
-// Entry operations — delegated to storage adapter
+// Entry operations - delegated to storage adapter
 // ---------------------------------------------------------------------------
 
 /**
@@ -309,22 +309,22 @@ export async function validateReferences(schema, data) {
  * 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.
+ * 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+
+ *   // 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
+ *   // 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
+ *   // 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 }
  *

package/server/services/components.js

@@ -159,7 +159,7 @@ export function compileComponent(source, name) {
     catch (e) { return {js: null, errors: [{type: e.code, message: e.message}]}; }
 
     const js = [
-        `// Compiled from ${name}.dmc — do not edit by hand.`,
+        `// Compiled from ${name}.dmc - do not edit by hand.`,
         `const template = ${toBacktickLiteral(parts.template)};`,
         `const style = ${toBacktickLiteral(parts.style)};`,
         `const props = ${JSON.stringify(propsObj)};`,
@@ -219,7 +219,7 @@ export async function getCompiledJs(name) {
 // ─── CRUD operations ──────────────────────────────────────────────────────
 
 /**
- * List all components. Lightweight metadata — does NOT compile.
+ * List all components. Lightweight metadata - does NOT compile.
  * The `props` field is parsed from each file's <props> block so the admin
  * list view can show props without a follow-up fetch.
  *
@@ -245,7 +245,7 @@ export async function listComponents() {
             const src = await fs.readFile(path.join(COMPONENTS_DIR, file), 'utf8');
             const {props: propsBlock} = parseDmcSource(src);
             props = validatePropsJson(propsBlock);
-        } catch { /* malformed — list still usable */ }
+        } catch { /* malformed - list still usable */ }
         entries.push({
             name,
             size: stat?.size ?? 0,
@@ -263,7 +263,7 @@ export async function listComponents() {
         try {
             const parts = parseDmcSource(pc.source);
             props = validatePropsJson(parts.props);
-        } catch { /* malformed plugin source — list still usable */ }
+        } catch { /* malformed plugin source - list still usable */ }
         entries.push({
             name: pc.name,
             size: pc.source.length,
@@ -313,7 +313,7 @@ export async function getComponent(name) {
 }
 
 /**
- * Create or update a component. Compiles BEFORE writing — a malformed source
+ * Create or update a component. Compiles BEFORE writing - a malformed source
  * never reaches disk. Returns the compile errors (if any) rather than throwing.
  *
  * @param {string} name
@@ -352,12 +352,12 @@ export async function saveComponent(name, source, {bundled = false, meta} = {})
     return {success: true, name, errors: []};
 }
 
-/** Lazy, circular-safe import — refreshes the markdown sanitiser's dm-* tag allowlist. */
+/** Lazy, circular-safe import - refreshes the markdown sanitiser's dm-* tag allowlist. */
 async function _refreshSanitiserAllowlist() {
     try {
         const {refreshComponentTagAllowlist} = await import('./markdown.js');
         await refreshComponentTagAllowlist();
-    } catch { /* no-op — markdown module not ready at first save */ }
+    } catch { /* no-op - markdown module not ready at first save */ }
 }
 
 /**
@@ -465,7 +465,7 @@ const SEED_COMPONENTS = {
 }
 </props>
 <script>
-// NB: Domma's factory calls data() with no \`this\` binding — props must be
+// NB: Domma's factory calls data() with no \`this\` binding - props must be
 // read from within onMount() / methods, which ARE bound to the component context.
 export default {
   data() { return { count: 0 }; },
@@ -633,7 +633,7 @@ export default {
 
 /**
  * Seed starter components into content/components/.
- * Never overwrites existing files — user customisations are preserved.
+ * Never overwrites existing files - user customisations are preserved.
  * All seeded components are marked `bundled: true` via their .meta.json.
  */
 export async function seedDefaultComponents() {

package/server/services/connectionManager.js

@@ -2,7 +2,7 @@
  * Connection Manager (Pro feature)
  *
  * Manages MongoDB client lifecycle for named database connections.
- * Loaded dynamically via import() — never required in the free version.
+ * Loaded dynamically via import() - never required in the free version.
  *
  * Usage:
  *   await initialise(connectionsConfig)   // on server startup
@@ -15,13 +15,13 @@ const clients = new Map();
 
 /**
  * Initialise all named MongoDB connections from config.
- * Connects lazily — each client is created but connect() is deferred to first use.
+ * Connects lazily - each client is created but connect() is deferred to first use.
  *
  * @param {Record<string, { type: string, uri: string, database: string, options?: object }>} connectionsConfig
  * @returns {Promise<void>}
  */
 export async function initialise(connectionsConfig) {
-    // Dynamic import — mongodb package is optional and not loaded in the free version.
+    // Dynamic import - mongodb package is optional and not loaded in the free version.
     const { MongoClient } = await import('mongodb');
 
     for (const [name, cfg] of Object.entries(connectionsConfig)) {
@@ -43,7 +43,7 @@ export async function initialise(connectionsConfig) {
             console.log(`[connectionManager] Connected: ${name} → ${cfg.database}`);
         } catch (err) {
             console.error(`[connectionManager] Failed to connect "${name}": ${err.message}`);
-            // Don't throw — allow server to start with degraded MongoDB support.
+            // Don't throw - allow server to start with degraded MongoDB support.
         }
     }
 }

package/server/services/content.js

@@ -79,6 +79,17 @@ export async function getPage(urlPath, opts = {}) {
 /**
  * Create a new page. Auto-creates parent directories.
  *
+ * Every frontmatter key the caller sends is written through - the same
+ * contract as updatePage. An earlier version built `meta` from a fixed
+ * whitelist, which silently discarded `project`, `visibility`, `tags`,
+ * `category` and `theme` on the FIRST save of a page: a page created inside
+ * a project landed in core, vanished from that project's list, and yet the
+ * URL was taken, so re-creating it answered "already exists".
+ *
+ * `project: ''` means "inherit by rootUrl" - the key is omitted rather than
+ * written as null (null is the deprecated core opt-out, and it pins the page
+ * to core forever).
+ *
  * @param {string} urlPath
  * @param {object} frontmatter
  * @param {string} body
@@ -91,6 +102,7 @@ export async function createPage(urlPath, frontmatter, body) {
     const defaults = config.content.pageDefaults;
     const now = new Date().toISOString();
     const meta = {
+        ...frontmatter,
         title: frontmatter.title || 'Untitled',
         slug: slugFromPath(urlPath),
         description: frontmatter.description || '',
@@ -104,6 +116,7 @@ export async function createPage(urlPath, frontmatter, body) {
         createdAt: now,
         updatedAt: now
     };
+    if (meta.project === '' || meta.project === undefined) delete meta.project;
 
     await fs.writeFile(filePath, serialiseMarkdown(meta, body || ''), 'utf8');
     const page = await readPageFile(filePath);
@@ -134,6 +147,11 @@ export async function updatePage(urlPath, frontmatter, body, {author} = {}) {
 
     if (existingMeta.createdAt) meta.createdAt = existingMeta.createdAt;
 
+    // '' is the editor's "inherit by rootUrl" choice - drop the key so the
+    // resolver re-derives it. (null stays meaningful: the deprecated explicit
+    // core opt-out.)
+    if (meta.project === '') delete meta.project;
+
     try {
         await createVersion(urlPath, {author, type: 'auto', label: null});
     } catch {
@@ -321,7 +339,7 @@ async function collectMdFiles(dir) {
  * @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.
+ *   anonymous (null) - most callers (listings, admin previews) leave this unset.
  * @returns {Promise<object>}
  */
 async function readPageFile(filePath, opts = {}) {
@@ -331,7 +349,12 @@ async function readPageFile(filePath, opts = {}) {
     // against menus bound to this page or its project, exactly as the navbar does.
     const { data, content, html, usedComponents, tags } =
         await parseMarkdown(raw, {user: opts.user || null, urlPath});
-    return { ...data, urlPath, content, html, usedComponents, tags };
+    // parseMarkdown's `tags` are CACHE tags (`block:x`, `collection:y`), not
+    // the page's editorial tags. Spreading them last used to shadow the
+    // frontmatter's `tags`, so the editor loaded `block:feedback-card` into
+    // the tag pillbox and wrote it back on save, and the pages list showed
+    // cache internals in its Tags column. Keep them apart.
+    return { ...data, urlPath, content, html, usedComponents, cacheTags: tags };
 }
 
 /**

package/server/services/docs.js

@@ -1,10 +1,10 @@
 /**
- * Domma Docs — request-time renderer
+ * Domma Docs - request-time renderer
  *
  * Serves the Domma CMS handbook at /domma-docs/* directly from the admin doc
  * HTML templates (admin/js/templates/docs/*.html) at request time. There is no
  * baked content: a domma-cms version bump ships new templates and the docs
- * update everywhere automatically — no porter, no per-site provisioning, no
+ * update everywhere automatically - no porter, no per-site provisioning, no
  * staleness. (Replaces the one-shot scripts/migrate-docs.js bake.)
  *
  * The publish switch is the `domma-docs` project's enabled flag, enforced by
@@ -33,7 +33,7 @@ const TPL_DIR = resolve(dirname(fileURLToPath(import.meta.url)), '../..', 'admin
 // Functional nav chrome only (breadcrumb + prev/next + section nav). Everything
 // else (hero, cards, tabs, accordion, buttons) is a native Domma component, so
 // it follows the theme. Injected as an inline <style> per docs page at render
-// time — no dependency on content/custom.css.
+// time - no dependency on content/custom.css.
 const DOCS_BODY_CSS = `.doc-breadcrumb { display: flex; flex-wrap: wrap; gap: .5rem; align-items: center; max-width: 80ch; margin: 0 auto 1.25rem; font-size: .85rem; color: var(--dm-text-muted); }
 .doc-breadcrumb a { color: var(--dm-primary); text-decoration: none; }
 .doc-breadcrumb a:hover { text-decoration: underline; }
@@ -76,7 +76,7 @@ const MAP = [
 ];
 
 // Admin-SPA hash routes and stale /resources/… paths don't resolve on the
-// public site — rewrite doc-to-doc links to /domma-docs/…, admin-feature links
+// public site - rewrite doc-to-doc links to /domma-docs/…, admin-feature links
 // to the admin SPA, and unwrap the rest.
 const LINK_MAP = {
     '#/docs/components-walkthrough': '/domma-docs/components/walkthrough',
@@ -97,7 +97,7 @@ const LINK_MAP = {
     '/resources/components':         '/domma-docs/components'
 };
 
-// The four top-level doc sections — rendered as a persistent nav on every page.
+// The four top-level doc sections - rendered as a persistent nav on every page.
 const SECTIONS = [
     {label: 'Usage',         href: '/domma-docs/usage'},
     {label: 'Tutorials',     href: '/domma-docs/tutorials'},
@@ -134,13 +134,13 @@ function rewriteLinks(html) {
     for (const [from, to] of Object.entries(LINK_MAP)) {
         out = out.split(`href="${from}"`).join(`href="${to}"`);
     }
-    // Any remaining /resources/… link has no doc equivalent — unwrap to text.
+    // Any remaining /resources/… link has no doc equivalent - unwrap to text.
     out = out.replace(/<a\b[^>]*\shref="\/resources\/[^"]*"[^>]*>([\s\S]*?)<\/a>/gi, '$1');
     return out;
 }
 
 // Pull every inline <style> block out of the body, returning the cleaned HTML
-// plus the extracted (deduped) CSS — collected PER CALL (no shared module state,
+// plus the extracted (deduped) CSS - collected PER CALL (no shared module state,
 // which would leak across requests in a long-lived server).
 function stripStyleBlocks(html) {
     const styles = new Set();
@@ -182,7 +182,7 @@ function unwrapDocsBody(html) {
 // Plain-text heading title, safe as a shortcode attribute value.
 function headingText(inner) {
     return inner.replace(/<[^>]+>/g, '')
-        .replace(/&amp;/g, '&').replace(/&mdash;/g, '—').replace(/&ndash;/g, '–')
+        .replace(/&amp;/g, '&').replace(/-/g, '-').replace(/-/g, '-')
         .replace(/&quot;/g, "'").replace(/&#39;/g, "'").replace(/&lt;/g, '<').replace(/&gt;/g, '>')
         .replace(/\s+/g, ' ').trim().replace(/"/g, "'");
 }
@@ -200,7 +200,7 @@ function splitSections(inner, level) {
     return {preamble, sections};
 }
 
-// ≥7 sections → accordion; 2–6 → tabs; <2 → a single card.
+// ≥7 sections → accordion; 2-6 → tabs; <2 → a single card.
 function structureBody(body) {
     const inner = unwrapDocsBody(body);
     const level = /<h2\b/i.test(inner) ? 2 : 3;
@@ -265,9 +265,9 @@ function buildSectionLanding(label) {
 function buildHomeLanding() {
     const hero = `[hero title="Domma Docs" tagline="The Domma CMS handbook" variant="gradient" align="center" fullwidth="true"][/hero]`;
     const cards = [
-        {label: 'Usage',         href: '/domma-docs/usage',      icon: 'book-open',     blurb: 'Day-to-day guides for running the CMS — pages, media, navigation, shortcodes and more.'},
+        {label: 'Usage',         href: '/domma-docs/usage',      icon: 'book-open',     blurb: 'Day-to-day guides for running the CMS - pages, media, navigation, shortcodes and more.'},
         {label: 'Tutorials',     href: '/domma-docs/tutorials',  icon: 'academic-cap',  blurb: 'Step-by-step walkthroughs that build something real from start to finish.'},
-        {label: 'Components',    href: '/domma-docs/components', icon: 'puzzle',        blurb: 'The full component reference — shortcodes, how-tos, walkthroughs and rules.'},
+        {label: 'Components',    href: '/domma-docs/components', icon: 'puzzle',        blurb: 'The full component reference - shortcodes, how-tos, walkthroughs and rules.'},
         {label: 'API Reference', href: '/domma-docs/api',        icon: 'code',          blurb: 'Every REST endpoint for headless and external integrations.'}
     ].map(s =>
         `[card icon="${s.icon}" title="${heroAttr(s.label)}"]\n${escText(s.blurb)}\n\n[button label="Browse ${heroAttr(s.label)} →" href="${s.href}" variant="primary" /]\n[/card]`
@@ -278,7 +278,7 @@ function buildHomeLanding() {
 // ── render ───────────────────────────────────────────────────────────────────
 
 // Build the shortcode body for a doc path, or null if the path is unknown.
-// Returns {title, body, styles[]} — `styles` is the inline CSS extracted from a
+// Returns {title, body, styles[]} - `styles` is the inline CSS extracted from a
 // leaf template (empty for synthesized landings).
 async function buildDocBody(docPath) {
     if (docPath in LANDINGS) {
@@ -292,7 +292,7 @@ async function buildDocBody(docPath) {
     try {
         src = await readFile(join(TPL_DIR, `${tpl}.html`), 'utf8');
     } catch {
-        return null; // template missing — treat as a 404
+        return null; // template missing - treat as a 404
     }
     const {html: stripped, styles} = stripStyleBlocks(stripHeader(src));
     const body = escapeCodeBrackets(dedentOutsidePre(rewriteLinks(stripped))).trim();
@@ -308,7 +308,7 @@ async function buildDocBody(docPath) {
 /**
  * Render a Domma Docs page to full HTML, or return null for an unknown path
  * (the route turns that into a 404). Cached per path+origin under the static
- * 'docs' tag — invalidated on boot so a version bump never serves stale HTML.
+ * 'docs' tag - invalidated on boot so a version bump never serves stale HTML.
  *
  * @param {string} docPath  url tail after /domma-docs (e.g. 'usage/pages', '' for home)
  * @param {{user?: object|null, baseUrl?: string}} [opts]