domma-cms 0.17.0 → 0.21.0

package/server/services/projects.js

@@ -0,0 +1,429 @@
+/**
+ * Projects service.
+ *
+ * Projects group related artefacts (Pages, Collections, Forms, Actions,
+ * Menus, Blocks, Views, Roles, Users) under a named slug. Membership is
+ * 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.
+ *
+ * Storage: a preset collection at `content/collections/projects/`.
+ * Access: dedicated `/api/projects/*` routes wrap this service.
+ */
+
+import {createEntry, deleteEntry, listEntries, updateEntry} from './collections.js';
+import {getRoleLevel} from './roles.js';
+
+/** Slug of the preset collection that stores project records. */
+export const PROJECTS_COLLECTION_SLUG = 'projects';
+
+const SLUG_RE = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/;
+
+/**
+ * Validate a project slug (also used for any artefact's `meta.project`
+ * value). Same rules as collection / menu slugs.
+ *
+ * @param {unknown} slug
+ * @returns {boolean}
+ */
+export function validateSlug(slug) {
+    return typeof slug === 'string' && SLUG_RE.test(slug);
+}
+
+/**
+ * List all projects. Returns a flat array of project records, sorted by
+ * sortOrder ascending then name alphabetical.
+ *
+ * @returns {Promise<Array<object>>}
+ * @throws {Error} If the projects collection schema is missing.
+ */
+export async function listProjects() {
+    const {entries} = await listEntries(PROJECTS_COLLECTION_SLUG, {limit: 0});
+    const projects = entries.map(e => normalise(e));
+    return projects.sort((a, b) => {
+        const so = (a.sortOrder ?? 0) - (b.sortOrder ?? 0);
+        if (so !== 0) return so;
+        return (a.name || '').localeCompare(b.name || '');
+    });
+}
+
+/**
+ * Fetch a single project by slug. Returns null if missing or slug invalid.
+ *
+ * @param {string} slug
+ * @returns {Promise<object|null>}
+ * @throws {Error} If the projects collection schema is missing.
+ */
+export async function getProject(slug) {
+    if (!validateSlug(slug)) return null;
+    const {entries} = await listEntries(PROJECTS_COLLECTION_SLUG, {limit: 0});
+    const entry = entries.find(e => e.data?.slug === slug);
+    return entry ? normalise(entry) : null;
+}
+
+/**
+ * Create a new project. Refuses on slug collision or validation failure.
+ *
+ * @param {object} input
+ * @returns {Promise<object>} The persisted project record.
+ * @throws {Error} If validation fails or the slug already exists.
+ */
+export async function createProject(input) {
+    const errors = validateProject(input);
+    if (errors.length) throw new Error('Validation failed: ' + errors.join('; '));
+    if (await getProject(input.slug)) {
+        throw new Error(`Project "${input.slug}" already exists`);
+    }
+    const now = new Date().toISOString();
+    const data = {
+        slug:        input.slug,
+        name:        input.name,
+        description: input.description || '',
+        icon:        input.icon        || 'folder',
+        ...(input.rootUrl != null && {rootUrl: input.rootUrl}),
+        sortOrder:   Number.isFinite(input.sortOrder) ? input.sortOrder : 0,
+        createdAt:   now,
+        updatedAt:   now
+    };
+    await createEntry(PROJECTS_COLLECTION_SLUG, data);
+    return data;
+}
+
+/**
+ * Update a project. Slug is immutable. Preserves createdAt; bumps updatedAt.
+ *
+ * @param {string} slug
+ * @param {object} input
+ * @returns {Promise<object>} The updated project record.
+ * @throws {Error} If the project is missing or validation fails.
+ */
+export async function updateProject(slug, input) {
+    const existing = await getProject(slug);
+    if (!existing) throw new Error(`Project "${slug}" not found`);
+    const merged = {
+        ...existing,
+        ...(input.name        != null && {name:        input.name}),
+        ...(input.description != null && {description: input.description}),
+        ...(input.icon        != null && {icon:        input.icon}),
+        ...(input.rootUrl     != null && {rootUrl:     input.rootUrl}),
+        ...(Number.isFinite(input.sortOrder) && {sortOrder: input.sortOrder}),
+        slug,
+        createdAt: existing.createdAt,
+        updatedAt: new Date().toISOString()
+    };
+    const errors = validateProject(merged);
+    if (errors.length) throw new Error('Validation failed: ' + errors.join('; '));
+    const {entries} = await listEntries(PROJECTS_COLLECTION_SLUG, {limit: 0});
+    const entry = entries.find(e => e.data?.slug === slug);
+    if (!entry) throw new Error(`Project "${slug}" not found`);
+    await updateEntry(PROJECTS_COLLECTION_SLUG, entry.id, merged);
+    return merged;
+}
+
+/**
+ * Delete a project. Returns true if removed, false if not found.
+ * Does NOT check for tagged artefacts — caller (API route) must do that.
+ *
+ * @param {string} slug
+ * @returns {Promise<boolean>}
+ * @throws {Error} If the projects collection schema is missing.
+ */
+export async function deleteProject(slug) {
+    if (!validateSlug(slug)) return false;
+    const {entries} = await listEntries(PROJECTS_COLLECTION_SLUG, {limit: 0});
+    const entry = entries.find(e => e.data?.slug === slug);
+    if (!entry) return false;
+    await deleteEntry(PROJECTS_COLLECTION_SLUG, entry.id);
+    return true;
+}
+
+/**
+ * Validate a project object. Returns an array of error strings (empty = OK).
+ *
+ * @param {object} project
+ * @returns {string[]}
+ */
+export function validateProject(project) {
+    const errors = [];
+    if (!project || typeof project !== 'object') return ['Project must be an object'];
+    if (!validateSlug(project.slug)) {
+        errors.push(`Invalid slug "${project.slug}" — lowercase alphanumeric + hyphen only`);
+    }
+    if (!project.name || typeof project.name !== 'string') {
+        errors.push('name is required');
+    }
+    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)');
+        }
+    }
+    if (project.icon != null && (typeof project.icon !== 'string' || !project.icon.trim())) {
+        errors.push('icon must be a non-empty string when set');
+    }
+    return errors;
+}
+
+function normalise(entry) {
+    return {...(entry.data || {})};
+}
+
+/**
+ * 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.
+ *
+ * @param {object|null} user
+ * @returns {Promise<Array<object>>}
+ */
+export async function listProjectsForUser(user) {
+    const all = await listProjects();
+    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));
+}
+
+/**
+ * Permission gate: can `user` see / edit `artefact` given its project tag
+ * and the user's `projects: []` access scope?
+ *
+ * Rules:
+ *   - Super-admin (role level 0) bypasses everything.
+ *   - Untagged artefacts (no `meta.project`) are visible to all.
+ *   - Users with no scope set (`projects: []` or missing) have no restriction.
+ *   - Otherwise: artefact's project must be in user's scope.
+ *
+ * @param {object} user      - Authenticated user; must have `role`.
+ * @param {object} artefact  - Anything with optional `meta.project`.
+ * @returns {boolean}
+ */
+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 (!Array.isArray(user.projects) || user.projects.length === 0) return true;
+    return user.projects.includes(project);
+}
+
+/**
+ * Resolve the project a page belongs to using the inheritance rules:
+ *   1. Explicit `project: null` in frontmatter → untagged
+ *   2. Explicit `project: '<slug>'` → use it
+ *   3. Missing field → longest matching `rootUrl` prefix wins
+ *   4. No match → untagged
+ *
+ * @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();
+    let best = null;
+    let bestLen = -1;
+    for (const p of projects) {
+        if (!p.rootUrl) continue;
+        if (urlPath === p.rootUrl || urlPath.startsWith(p.rootUrl + '/')) {
+            if (p.rootUrl.length > bestLen) {
+                best = p.slug;
+                bestLen = p.rootUrl.length;
+            } else if (p.rootUrl.length === bestLen && p.slug < best) {
+                best = p.slug;
+            }
+        }
+    }
+    return best;
+}
+
+/**
+ * Enumerate every artefact tagged with 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).
+ *
+ * @param {string} projectSlug
+ * @returns {Promise<{pages:object[], collections:object[], forms:object[], actions:object[], menus:object[], blocks:object[], views:object[], roles:object[], users:object[]}>}
+ */
+export async function getArtefactsForProject(projectSlug) {
+    const out = {
+        pages: [], collections: [], forms: [], actions: [],
+        menus: [], blocks: [], views: [], roles: [], users: []
+    };
+
+    try {
+        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);
+        }
+    } catch { /* service unavailable */ }
+
+    try {
+        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);
+        }
+    } catch { /* skip */ }
+
+    try {
+        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);
+        }
+    } catch { /* skip */ }
+
+    try {
+        const {listActions} = await import('./actions.js');
+        for (const a of await listActions()) {
+            if (a?.meta?.project === projectSlug) out.actions.push(a);
+        }
+    } catch { /* skip */ }
+
+    try {
+        const {listBlocks, readBlock} = await import('./blocks.js');
+        for (const b of await listBlocks()) {
+            const full = (typeof readBlock === 'function') ? await readBlock(b.slug) : b;
+            if (full?.meta?.project === 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);
+        }
+    } catch { /* skip */ }
+
+    try {
+        const {getRoleMap} = await import('./roles.js');
+        for (const role of getRoleMap().values()) {
+            if (role?.meta?.project === 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);
+        }
+    } catch { /* skip */ }
+
+    try {
+        const {listPages} = await import('./content.js');
+        for (const p of await listPages()) {
+            const url = p.url || p.urlPath || '/';
+            const explicit = (p.project === undefined) ? undefined : p.project;
+            const pageProject = await getProjectForPage(url, explicit);
+            if (pageProject === projectSlug) out.pages.push(p);
+        }
+    } catch { /* skip */ }
+
+    return out;
+}
+
+/**
+ * Set `meta.project: null` on every artefact tagged with this project.
+ * Returns a count map of how many of each type were untagged. Used as the
+ * "Untag all" escape hatch before delete.
+ *
+ * Per-service plumbing (Tasks 9–16) is required for non-menu artefacts to
+ * carry meta.project through their update path; without that plumbing, this
+ * function simply returns zero counts for those types.
+ *
+ * @param {string} projectSlug
+ * @returns {Promise<Record<string, number>>}
+ */
+export async function untagAllForProject(projectSlug) {
+    const counts = {
+        pages: 0, collections: 0, forms: 0, actions: 0,
+        menus: 0, blocks: 0, views: 0, roles: 0, users: 0
+    };
+    const grouped = await getArtefactsForProject(projectSlug);
+
+    try {
+        const {getMenu, updateMenu} = await import('./menus.js');
+        for (const m of grouped.menus) {
+            const full = await getMenu(m.slug);
+            if (!full) continue;
+            const meta = {...(full.meta || {})};
+            delete meta.project;
+            await updateMenu(m.slug, {...full, meta});
+            counts.menus++;
+        }
+    } catch { /* skip */ }
+
+    try {
+        const {readForm, writeForm} = await import('./forms.js');
+        for (const f of grouped.forms) {
+            const full = await readForm(f.slug);
+            if (!full) continue;
+            const meta = {...(full.meta || {})};
+            delete meta.project;
+            await writeForm(f.slug, {...full, meta});
+            counts.forms++;
+        }
+    } catch { /* skip */ }
+
+    try {
+        const {getCollection, updateCollection} = await import('./collections.js');
+        for (const c of grouped.collections) {
+            const full = await getCollection(c.slug);
+            if (!full) continue;
+            const meta = {...(full.meta || {})};
+            delete meta.project;
+            await updateCollection(c.slug, {...full, meta});
+            counts.collections++;
+        }
+    } catch { /* skip */ }
+
+    try {
+        const {updateAction} = await import('./actions.js');
+        for (const a of grouped.actions) {
+            const meta = {...(a.meta || {})};
+            delete meta.project;
+            await updateAction(a.slug, {...a, meta});
+            counts.actions++;
+        }
+    } catch { /* skip */ }
+
+    try {
+        const {readBlock, writeBlock} = await import('./blocks.js');
+        for (const b of grouped.blocks) {
+            const full = (typeof readBlock === 'function') ? await readBlock(b.slug) : b;
+            if (!full) continue;
+            const meta = {...(full.meta || {})};
+            delete meta.project;
+            if (typeof writeBlock === 'function') {
+                await writeBlock(b.slug, {...full, meta});
+                counts.blocks++;
+            }
+        }
+    } catch { /* skip */ }
+
+    try {
+        const {readView, writeView} = await import('./views.js');
+        for (const v of grouped.views) {
+            const full = (typeof readView === 'function') ? await readView(v.slug) : v;
+            if (!full) continue;
+            const meta = {...(full.meta || {})};
+            delete meta.project;
+            if (typeof writeView === 'function') {
+                await writeView(v.slug, {...full, meta});
+                counts.views++;
+            }
+        }
+    } catch { /* skip */ }
+
+    // Roles, Users, Pages: deferred. Roles/Users would need the per-service
+    // plumbing to land first; pages need frontmatter rewriting which is a
+    // separate concern. Counts remain 0 for those types in this task; later
+    // tasks may revisit.
+
+    return counts;
+}

package/server/services/recipes/contact-list.json

@@ -0,0 +1,78 @@
+{
+  "slug":         "contact-list",
+  "name":         "Contact list (CRM-lite)",
+  "description":  "A simple address book — contacts collection with email/phone/company/tags, a quick-add form, and a single status transition for follow-ups.",
+  "icon":         "users",
+  "options": [
+    { "name": "collectionSlug", "label": "Collection slug", "default": "contacts",         "hint": "Where contact records are stored" },
+    { "name": "formSlug",       "label": "Form slug",       "default": "contact-quick-add", "hint": "Embedded via [form name=\"...\" /]" },
+    { "name": "actionPrefix",   "label": "Action slug prefix", "default": "contact",       "hint": "Per-action slug: <prefix>-followup" }
+  ],
+  "collection": {
+    "title":       "Contacts",
+    "description": "Address-book entries",
+    "fields": [
+      { "name": "fullName", "label": "Full name",   "type": "text",  "required": true },
+      { "name": "email",    "label": "Email",       "type": "email" },
+      { "name": "phone",    "label": "Phone",       "type": "text" },
+      { "name": "company",  "label": "Company",     "type": "text" },
+      {
+        "name": "tags", "label": "Tags", "type": "multiselect",
+        "options": [
+          { "value": "lead",     "label": "Lead" },
+          { "value": "customer", "label": "Customer" },
+          { "value": "partner",  "label": "Partner" },
+          { "value": "vendor",   "label": "Vendor" }
+        ]
+      },
+      { "name": "notes",    "label": "Notes",       "type": "textarea" },
+      {
+        "name": "status", "label": "Status", "type": "select",
+        "options": [
+          { "value": "active",   "label": "Active" },
+          { "value": "followup", "label": "Needs follow-up" },
+          { "value": "archived", "label": "Archived" }
+        ]
+      }
+    ],
+    "api": {
+      "read":   { "enabled": false },
+      "create": { "enabled": false },
+      "update": { "enabled": false },
+      "delete": { "enabled": false }
+    }
+  },
+  "form": {
+    "title":       "Add a contact",
+    "fields": [
+      { "name": "fullName", "label": "Full name", "type": "text",  "required": true },
+      { "name": "email",    "label": "Email",     "type": "email" },
+      { "name": "phone",    "label": "Phone",     "type": "text" },
+      { "name": "company",  "label": "Company",   "type": "text" },
+      { "name": "notes",    "label": "Notes",     "type": "textarea" }
+    ],
+    "settings": {
+      "submitText":     "Add contact",
+      "successMessage": "Contact added.",
+      "honeypot":       true,
+      "rateLimitPerMinute": 10
+    },
+    "actions": { "collection": { "enabled": true, "slug": "" } }
+  },
+  "actions": [
+    {
+      "slug":        "{{actionPrefix}}-followup",
+      "title":       "Mark for follow-up",
+      "description": "Flag this contact as needing follow-up.",
+      "collection":  "{{collectionSlug}}",
+      "trigger":     { "label": "Flag follow-up", "icon": "flag", "style": "warning" },
+      "transition":  { "field": "status", "from": ["active"], "to": "followup" },
+      "access":      { "roles": ["admin", "super-admin"] },
+      "steps": [
+        { "type": "updateField", "config": { "field": "status", "value": "followup" } }
+      ]
+    }
+  ],
+  "wireForm": true,
+  "snippet":  "[form name=\"{{formSlug}}\" /]\n\n## Contacts\n\n[collection slug=\"{{collectionSlug}}\" display=\"table\" searchable filterable=\"status,tags\" sortable transitions /]"
+}