domma-cms 0.22.6 → 0.23.0

package/server/services/projects.js

@@ -6,7 +6,13 @@
  * a metadata tag (`meta.project: '<slug>'`) on each artefact — no
  * filesystem isolation. Projects also act as a permission boundary:
  * users with `projects: []` set only see their projects' artefacts plus
- * untagged site-wide artefacts.
+ * the core project's artefacts.
+ *
+ * The built-in **core** project owns every artefact not claimed by another
+ * project — by resolution fallback, not by tagging. It is seeded at boot
+ * (`seedCoreProject()`), cannot be deleted, and is never an access
+ * boundary: core-resolved artefacts are visible to all authenticated
+ * users, regardless of their `projects: []` scope.
  *
  * Storage: a preset collection at `content/collections/projects/`.
  * Access: dedicated `/api/projects/*` routes wrap this service.
@@ -18,6 +24,20 @@ import {getRoleLevel} from './roles.js';
 /** Slug of the preset collection that stores project records. */
 export const PROJECTS_COLLECTION_SLUG = 'projects';
 
+/** Slug of the built-in, protected core project. */
+export const CORE_PROJECT_SLUG = 'core';
+
+/** Seed record for the core project (created at boot if absent). */
+const CORE_PROJECT_SEED = {
+    slug:        CORE_PROJECT_SLUG,
+    name:        'Core',
+    description: 'The core site — everything not assigned to another project.',
+    icon:        'home',
+    rootUrl:     '/',
+    sortOrder:   -1,
+    protected:   true
+};
+
 const SLUG_RE = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/;
 
 /**
@@ -92,17 +112,53 @@ export async function createProject(input) {
     return data;
 }
 
+/**
+ * Seed the built-in core project at boot. Create-if-absent by slug — NOT by
+ * data.json existence: preset seeding already creates an empty data file, and
+ * retrofitted sites have project entries that must be preserved. If a project
+ * with the core slug already exists it is adopted: `protected: true` is set
+ * and every other field is left untouched (resolution does not depend on the
+ * core record's rootUrl).
+ *
+ * @returns {Promise<object>} The core project record.
+ */
+export async function seedCoreProject() {
+    const {entries} = await listEntries(PROJECTS_COLLECTION_SLUG, {limit: 0});
+    const existing = entries.find(e => e.data?.slug === CORE_PROJECT_SLUG);
+    if (existing) {
+        if (existing.data.protected === true) return normalise(existing);
+        const adopted = {...existing.data, protected: true, updatedAt: new Date().toISOString()};
+        await updateEntry(PROJECTS_COLLECTION_SLUG, existing.id, adopted);
+        return adopted;
+    }
+    const now = new Date().toISOString();
+    const data = {...CORE_PROJECT_SEED, createdAt: now, updatedAt: now};
+    await createEntry(PROJECTS_COLLECTION_SLUG, data);
+    return data;
+}
+
 /**
  * Update a project. Slug is immutable. Preserves createdAt; bumps updatedAt.
+ * The core project's `rootUrl` and `protected` flag are locked; its name,
+ * description, icon and sortOrder remain editable.
  *
  * @param {string} slug
  * @param {object} input
  * @returns {Promise<object>} The updated project record.
- * @throws {Error} If the project is missing or validation fails.
+ * @throws {Error} If the project is missing, validation fails, or a locked
+ *                 core field is changed.
  */
 export async function updateProject(slug, input) {
     const existing = await getProject(slug);
     if (!existing) throw new Error(`Project "${slug}" not found`);
+    if (slug === CORE_PROJECT_SLUG) {
+        if (input.rootUrl != null && input.rootUrl !== existing.rootUrl) {
+            throw new Error("Cannot change the core project's rootUrl");
+        }
+        if (input.protected != null && input.protected !== existing.protected) {
+            throw new Error("Cannot change the core project's protected flag");
+        }
+    }
     const merged = {
         ...existing,
         ...(input.name        != null && {name:        input.name}),
@@ -126,12 +182,15 @@ export async function updateProject(slug, input) {
 /**
  * Delete a project. Returns true if removed, false if not found.
  * Does NOT check for tagged artefacts — caller (API route) must do that.
+ * The core project can never be deleted.
  *
  * @param {string} slug
  * @returns {Promise<boolean>}
- * @throws {Error} If the projects collection schema is missing.
+ * @throws {Error} If the slug is the core project or the projects collection
+ *                 schema is missing.
  */
 export async function deleteProject(slug) {
+    if (slug === CORE_PROJECT_SLUG) throw new Error('Cannot delete the core project');
     if (!validateSlug(slug)) return false;
     const {entries} = await listEntries(PROJECTS_COLLECTION_SLUG, {limit: 0});
     const entry = entries.find(e => e.data?.slug === slug);
@@ -158,8 +217,8 @@ export function validateProject(project) {
     if (project.rootUrl != null && project.rootUrl !== '') {
         if (typeof project.rootUrl !== 'string' || !project.rootUrl.startsWith('/')) {
             errors.push('rootUrl must start with /');
-        } else if (project.rootUrl === '/') {
-            errors.push('rootUrl cannot be exactly "/" (would auto-claim every page)');
+        } else if (project.rootUrl === '/' && project.slug !== CORE_PROJECT_SLUG) {
+            errors.push('rootUrl cannot be exactly "/" (reserved for the core project)');
         }
     }
     if (project.icon != null && (typeof project.icon !== 'string' || !project.icon.trim())) {
@@ -175,7 +234,8 @@ function normalise(entry) {
 /**
  * List projects the given user is allowed to see. Super-admin sees all;
  * users with empty `projects: []` see all; scoped users see their listed
- * projects only.
+ * projects plus the core project (whose artefacts they can see anyway —
+ * see canSeeArtefact).
  *
  * @param {object|null} user
  * @returns {Promise<Array<object>>}
@@ -185,7 +245,7 @@ export async function listProjectsForUser(user) {
     if (!user) return [];
     if (getRoleLevel(user.role) === 0) return all;
     if (!Array.isArray(user.projects) || user.projects.length === 0) return all;
-    return all.filter(p => user.projects.includes(p.slug));
+    return all.filter(p => p.slug === CORE_PROJECT_SLUG || user.projects.includes(p.slug));
 }
 
 /**
@@ -194,7 +254,8 @@ export async function listProjectsForUser(user) {
  *
  * Rules:
  *   - Super-admin (role level 0) bypasses everything.
- *   - Untagged artefacts (no `meta.project`) are visible to all.
+ *   - Core artefacts (no `meta.project`, or tagged `core`) are visible to
+ *     all — the core project is organisational, never an access boundary.
  *   - Users with no scope set (`projects: []` or missing) have no restriction.
  *   - Otherwise: artefact's project must be in user's scope.
  *
@@ -206,30 +267,49 @@ export function canSeeArtefact(user, artefact) {
     if (!user) return false;
     if (getRoleLevel(user.role) === 0) return true;
     const project = artefact?.meta?.project;
-    if (!project) return true;
+    if (!project || project === CORE_PROJECT_SLUG) return true;
     if (!Array.isArray(user.projects) || user.projects.length === 0) return true;
     return user.projects.includes(project);
 }
 
+/**
+ * Resolve the project a non-page artefact belongs to. Artefacts without a
+ * `meta.project` tag belong to the core project by exclusion. (Pages resolve
+ * via getProjectForPage instead — they carry a frontmatter `project` field
+ * and inherit by rootUrl prefix.)
+ *
+ * @param {object} artefact - Anything with optional `meta.project`.
+ * @returns {string} A project slug; never null.
+ */
+export function resolveArtefactProject(artefact) {
+    return artefact?.meta?.project || CORE_PROJECT_SLUG;
+}
+
 /**
  * Resolve the project a page belongs to using the inheritance rules:
- *   1. Explicit `project: null` in frontmatter → untagged
- *   2. Explicit `project: '<slug>'` → use it
+ *   1. Explicit `project: '<slug>'` → use it
+ *   2. Explicit `project: null` → core (legacy opt-out, deprecated — core
+ *      owns the floor, so "untagged" no longer exists as a state)
  *   3. Missing field → longest matching `rootUrl` prefix wins
- *   4. No match → untagged
+ *   4. No match → core
+ *
+ * The core project does not participate in prefix matching — it is the
+ * fallback when nothing else claims the page. If the core record has not
+ * been seeded yet, falls back to null (pre-seed behaviour).
  *
  * @param {string} urlPath
  * @param {string|null|undefined} explicitProject
  * @returns {Promise<string|null>}
  */
 export async function getProjectForPage(urlPath, explicitProject) {
-    if (explicitProject === null) return null;
     if (typeof explicitProject === 'string' && explicitProject) return explicitProject;
     const projects = await listProjects();
+    const coreFallback = projects.some(p => p.slug === CORE_PROJECT_SLUG) ? CORE_PROJECT_SLUG : null;
+    if (explicitProject === null) return coreFallback;
     let best = null;
     let bestLen = -1;
     for (const p of projects) {
-        if (!p.rootUrl) continue;
+        if (!p.rootUrl || p.slug === CORE_PROJECT_SLUG) continue;
         if (urlPath === p.rootUrl || urlPath.startsWith(p.rootUrl + '/')) {
             if (p.rootUrl.length > bestLen) {
                 best = p.slug;
@@ -239,14 +319,18 @@ export async function getProjectForPage(urlPath, explicitProject) {
             }
         }
     }
-    return best;
+    return best ?? coreFallback;
 }
 
 /**
- * Enumerate every artefact tagged with the given project. Returns a flat
+ * Enumerate every artefact belonging to the given project. Returns a flat
  * grouping by type — each value is an array of artefact summary objects.
  * Used by the project detail page (counts + per-type tabs).
  *
+ * Membership is by resolution, not tag equality: artefacts without a
+ * `meta.project` tag belong to the core project, so
+ * `getArtefactsForProject('core')` enumerates everything unclaimed.
+ *
  * @param {string} projectSlug
  * @returns {Promise<{pages:object[], collections:object[], forms:object[], actions:object[], menus:object[], blocks:object[], views:object[], roles:object[], users:object[]}>}
  */
@@ -260,7 +344,7 @@ export async function getArtefactsForProject(projectSlug) {
         const {listMenus, getMenu} = await import('./menus.js');
         for (const m of await listMenus()) {
             const full = await getMenu(m.slug);
-            if (full?.meta?.project === projectSlug) out.menus.push(m);
+            if (resolveArtefactProject(full) === projectSlug) out.menus.push(m);
         }
     } catch { /* service unavailable */ }
 
@@ -268,7 +352,7 @@ export async function getArtefactsForProject(projectSlug) {
         const {listForms, readForm} = await import('./forms.js');
         for (const f of await listForms()) {
             const full = await readForm(f.slug);
-            if (full?.meta?.project === projectSlug) out.forms.push(f);
+            if (resolveArtefactProject(full) === projectSlug) out.forms.push(f);
         }
     } catch { /* skip */ }
 
@@ -276,14 +360,14 @@ export async function getArtefactsForProject(projectSlug) {
         const {listCollections, getCollection} = await import('./collections.js');
         for (const c of await listCollections()) {
             const full = await getCollection(c.slug);
-            if (full?.meta?.project === projectSlug) out.collections.push(c);
+            if (resolveArtefactProject(full) === projectSlug) out.collections.push(c);
         }
     } catch { /* skip */ }
 
     try {
         const {listActions} = await import('./actions.js');
         for (const a of await listActions()) {
-            if (a?.meta?.project === projectSlug) out.actions.push(a);
+            if (resolveArtefactProject(a) === projectSlug) out.actions.push(a);
         }
     } catch { /* skip */ }
 
@@ -292,28 +376,28 @@ export async function getArtefactsForProject(projectSlug) {
         // per-block read is needed. (Blocks are keyed by `name`, not `slug`.)
         const {listBlocks} = await import('./blocks.js');
         for (const b of await listBlocks()) {
-            if (b?.meta?.project === projectSlug) out.blocks.push(b);
+            if (resolveArtefactProject(b) === projectSlug) out.blocks.push(b);
         }
     } catch { /* skip */ }
 
     try {
         const {listViews} = await import('./views.js');
         for (const v of await listViews()) {
-            if (v?.meta?.project === projectSlug) out.views.push(v);
+            if (resolveArtefactProject(v) === projectSlug) out.views.push(v);
         }
     } catch { /* skip */ }
 
     try {
         const {getRoleMap} = await import('./roles.js');
         for (const role of getRoleMap().values()) {
-            if (role?.meta?.project === projectSlug) out.roles.push(role);
+            if (resolveArtefactProject(role) === projectSlug) out.roles.push(role);
         }
     } catch { /* skip */ }
 
     try {
         const {listUsers} = await import('./users.js');
         for (const u of await listUsers()) {
-            if (u?.meta?.project === projectSlug) out.users.push(u);
+            if (resolveArtefactProject(u) === projectSlug) out.users.push(u);
         }
     } catch { /* skip */ }
 
@@ -339,10 +423,17 @@ export async function getArtefactsForProject(projectSlug) {
  * carry meta.project through their update path; without that plumbing, this
  * function simply returns zero counts for those types.
  *
+ * Refused for the core project — membership there is by resolution, so
+ * untagging would be a no-op that resolution immediately reverses.
+ *
  * @param {string} projectSlug
  * @returns {Promise<Record<string, number>>}
+ * @throws {Error} If projectSlug is the core project.
  */
 export async function untagAllForProject(projectSlug) {
+    if (projectSlug === CORE_PROJECT_SLUG) {
+        throw new Error('Cannot untag the core project — artefacts would immediately resolve back to it');
+    }
     const counts = {
         pages: 0, collections: 0, forms: 0, actions: 0,
         menus: 0, blocks: 0, views: 0, roles: 0, users: 0