@actuate-media/cms-core 0.26.0 → 0.27.0

package/dist/api/handlers.js

@@ -33,6 +33,7 @@ import { createSSEPresenceAdapter } from '../presence/index.js';
 import { BUILT_IN_TEMPLATES } from '../page-builder/templates.js';
 import { validateTree } from '../page-builder/validate.js';
 import { auditAccessibility, fixAccessibility } from '../page-builder/a11y-fix.js';
+import { SECTION_TYPE_LIST, getSectionType, getSectionTypesForScope, buildSection, coerceSections, coercePostHeader, defaultPostHeader, addSection as addSectionToList, removeSection as removeSectionFromList, reorderSections as reorderSectionList, setSectionVisibility, updateSectionContent as updateSectionContentInList, updateSectionSettings as updateSectionSettingsInList, updateSectionMeta as updateSectionMetaInList, validateSectionContent, } from '../sections/index.js';
 import { getClientIp, isResolvedIp } from '../security/client-ip.js';
 import { safeFetch, SsrfBlockedError } from '../security/safe-fetch.js';
 import { redactSecrets } from '../security/redact.js';
@@ -708,6 +709,41 @@ class ModelNotAvailableError extends Error {
         this.model = model;
     }
 }
+/**
+ * Resolve a collection definition from the runtime config, tolerating both
+ * the array and the record (keyed-by-slug) shapes consumers use.
+ */
+function findCollectionDef(slug) {
+    const collections = getActuateConfig()?.collections;
+    if (Array.isArray(collections)) {
+        return collections.find((c) => c?.slug === slug);
+    }
+    if (collections && typeof collections === 'object') {
+        const rec = collections;
+        return rec[slug] ?? Object.values(rec).find((c) => c?.slug === slug);
+    }
+    return undefined;
+}
+/**
+ * True when `collection` declares a `sections` JSON field — the storage
+ * contract the flat Page Editor + section endpoints rely on. Guards against
+ * silently dropping section writes on a collection that never declared the
+ * field (the field-access layer strips undeclared keys).
+ */
+function collectionSupportsSections(slug) {
+    const def = findCollectionDef(slug);
+    if (!def)
+        return false;
+    const fields = def.fields;
+    if (Array.isArray(fields)) {
+        return fields.some((f) => f?.name === 'sections' && f?.type === 'json');
+    }
+    if (fields && typeof fields === 'object') {
+        const f = fields.sections;
+        return f?.type === 'json';
+    }
+    return false;
+}
 export function registerCMSRoutes(router) {
     const rawDb = () => getDB();
     const db = () => {
@@ -811,6 +847,14 @@ export function registerCMSRoutes(router) {
                 type: def?.type ?? 'page',
                 urlPrefix: def?.urlPrefix ?? slug,
                 hidden: def?.admin?.hidden === true,
+                // Surface the admin metadata the Posts area needs to render
+                // type tabs / cards (description, icon, accent color, group).
+                // None are sensitive — they all already live on the public
+                // collection definition the admin client receives via props.
+                description: def?.admin?.description ?? null,
+                icon: def?.admin?.icon ?? null,
+                color: def?.admin?.color ?? null,
+                group: def?.admin?.group ?? null,
                 fieldCount: fieldSummary.length,
                 fields: fieldSummary,
             };
@@ -1705,6 +1749,337 @@ export function registerCMSRoutes(router) {
         }
     });
     // ---------------------------------------------------------------------------
+    // Page section routes (flat Page Editor model)
+    //
+    // These operate on a page document's `data.sections` JSON array — the same
+    // model the visual Page Editor reads/writes — so an AI agent driving the
+    // CMS from Cursor/VS Code via MCP produces real, editable, publishable
+    // sections rather than disposable markup. All mutations go through the
+    // audited `updateDocument` path (versions, hooks, cache invalidation,
+    // live-preview push) and reuse collection scope checks.
+    //
+    // Discovery + validation are deterministic (no LLM) and only need auth.
+    // ---------------------------------------------------------------------------
+    // GET /page-sections/types — discover registered section types + schemas.
+    // Optional `?scope=page|post` filters to types usable on that surface so an
+    // agent only builds sections that have a working renderer in that context.
+    router.get('/page-sections/types', async (request) => {
+        try {
+            const auth = await requireAuth(request);
+            if (auth.error)
+                return auth.error;
+            const scope = new URL(request.url).searchParams.get('scope');
+            const data = scope === 'page' || scope === 'post'
+                ? getSectionTypesForScope(scope)
+                : SECTION_TYPE_LIST;
+            return json({ data });
+        }
+        catch (err) {
+            return internalError(err, 'list section types');
+        }
+    });
+    // POST /page-sections/validate — validate section content against its
+    // type schema. Body: { sectionType, content, settings? }.
+    router.post('/page-sections/validate', async (request) => {
+        try {
+            const auth = await requireAuth(request);
+            if (auth.error)
+                return auth.error;
+            const body = (await request.json().catch(() => null));
+            const sectionType = typeof body?.sectionType === 'string' ? body.sectionType : '';
+            if (!sectionType)
+                return errorResponse('sectionType is required', 400);
+            const content = body?.content && typeof body.content === 'object'
+                ? body.content
+                : {};
+            const settings = body?.settings && typeof body.settings === 'object'
+                ? body.settings
+                : undefined;
+            const result = validateSectionContent(sectionType, content, settings);
+            return json({ data: result });
+        }
+        catch (err) {
+            return internalError(err, 'validate section');
+        }
+    });
+    // Shared: load a page document's sections, or a Response on error.
+    const loadPageSections = async (collection, id, ctx) => {
+        if (!collectionSupportsSections(collection)) {
+            return errorResponse(`Collection "${collection}" does not declare a "sections" JSON field, so it cannot store page sections.`, 400);
+        }
+        const doc = await getDocument(collection, id, ctx);
+        if (!doc)
+            return errorResponse('Page not found', 404);
+        const data = doc.data ?? {};
+        return { sections: coerceSections(data.sections) };
+    };
+    // Shared: persist a mutated section array via the audited update path.
+    const persistPageSections = async (collection, id, sections, ctx, userId) => {
+        const doc = await updateDocument(collection, id, { sections }, ctx);
+        await logEvent({
+            event: 'document_updated',
+            userId,
+            details: { collection, documentId: id, action: 'page_sections_updated' },
+        });
+        notifyPreviewUpdate(collection, id, {
+            values: doc.data,
+            status: doc.status,
+            updatedAt: doc.updatedAt?.toISOString?.(),
+        });
+        const data = doc.data ?? {};
+        return coerceSections(data.sections);
+    };
+    // GET /page-sections/:collection/:id — list a page's sections.
+    router.get('/page-sections/:collection/:id', async (request, params) => {
+        try {
+            const auth = await requireAuth(request);
+            if (auth.error)
+                return auth.error;
+            const scopeErr = requireCollectionScope(auth.session, params.collection, 'read');
+            if (scopeErr)
+                return scopeErr;
+            const ctx = buildActionContext(auth.session, db());
+            const loaded = await loadPageSections(params.collection, params.id, ctx);
+            if (loaded instanceof Response)
+                return loaded;
+            return json({ data: loaded.sections });
+        }
+        catch (err) {
+            return internalError(err, 'list page sections');
+        }
+    });
+    // POST /page-sections/:collection/:id — add a section.
+    // Body: { sectionType, name?, internalLabel?, visible?, content?, settings?, position? }.
+    router.post('/page-sections/:collection/:id', async (request, params) => {
+        try {
+            const auth = await requireAuth(request);
+            if (auth.error)
+                return auth.error;
+            const scopeErr = requireCollectionScope(auth.session, params.collection, 'update');
+            if (scopeErr)
+                return scopeErr;
+            const body = (await request.json().catch(() => null));
+            const sectionType = typeof body?.sectionType === 'string' ? body.sectionType : '';
+            if (!getSectionType(sectionType)) {
+                return errorResponse(`Unknown section type "${sectionType}". Call GET /page-sections/types for valid ids.`, 400);
+            }
+            const ctx = buildActionContext(auth.session, db());
+            const loaded = await loadPageSections(params.collection, params.id, ctx);
+            if (loaded instanceof Response)
+                return loaded;
+            const section = buildSection(sectionType, {
+                name: typeof body?.name === 'string' ? body.name : undefined,
+                internalLabel: typeof body?.internalLabel === 'string' ? body.internalLabel : undefined,
+                visible: body?.visible !== false,
+                content: body?.content && typeof body.content === 'object'
+                    ? body.content
+                    : undefined,
+                settings: body?.settings && typeof body.settings === 'object'
+                    ? body.settings
+                    : undefined,
+            });
+            const position = typeof body?.position === 'number' ? body.position : undefined;
+            const next = addSectionToList(loaded.sections, section, position);
+            const saved = await persistPageSections(params.collection, params.id, next, ctx, auth.session.userId);
+            const validation = validateSectionContent(section.sectionType, section.content, section.settings);
+            return json({ data: { section, sections: saved, validation } }, 201);
+        }
+        catch (err) {
+            return internalError(err, 'add page section');
+        }
+    });
+    // POST /page-sections/:collection/:id/reorder — reorder by id list.
+    // Registered BEFORE the :sectionId routes so "reorder" isn't captured as a
+    // section id (the router matches in registration order).
+    router.post('/page-sections/:collection/:id/reorder', async (request, params) => {
+        try {
+            const auth = await requireAuth(request);
+            if (auth.error)
+                return auth.error;
+            const scopeErr = requireCollectionScope(auth.session, params.collection, 'update');
+            if (scopeErr)
+                return scopeErr;
+            const body = (await request.json().catch(() => null));
+            const orderedIds = Array.isArray(body?.orderedIds)
+                ? body.orderedIds.filter((x) => typeof x === 'string')
+                : null;
+            if (!orderedIds)
+                return errorResponse('orderedIds (string[]) is required', 400);
+            const ctx = buildActionContext(auth.session, db());
+            const loaded = await loadPageSections(params.collection, params.id, ctx);
+            if (loaded instanceof Response)
+                return loaded;
+            const next = reorderSectionList(loaded.sections, orderedIds);
+            const saved = await persistPageSections(params.collection, params.id, next, ctx, auth.session.userId);
+            return json({ data: saved });
+        }
+        catch (err) {
+            return internalError(err, 'reorder page sections');
+        }
+    });
+    // PATCH /page-sections/:collection/:id/:sectionId — update a section.
+    // Body: { content?, settings?, name?, internalLabel?, visible? }.
+    router.patch('/page-sections/:collection/:id/:sectionId', async (request, params) => {
+        try {
+            const auth = await requireAuth(request);
+            if (auth.error)
+                return auth.error;
+            const scopeErr = requireCollectionScope(auth.session, params.collection, 'update');
+            if (scopeErr)
+                return scopeErr;
+            const body = (await request.json().catch(() => null));
+            const ctx = buildActionContext(auth.session, db());
+            const loaded = await loadPageSections(params.collection, params.id, ctx);
+            if (loaded instanceof Response)
+                return loaded;
+            const sectionId = params.sectionId;
+            if (!loaded.sections.some((s) => s.id === sectionId)) {
+                return errorResponse(`Section "${sectionId}" not found on this page.`, 404);
+            }
+            let next = loaded.sections;
+            if (body?.content && typeof body.content === 'object') {
+                next = updateSectionContentInList(next, sectionId, body.content);
+            }
+            if (body?.settings && typeof body.settings === 'object') {
+                next = updateSectionSettingsInList(next, sectionId, body.settings);
+            }
+            const meta = {};
+            if (typeof body?.name === 'string')
+                meta.name = body.name;
+            if (typeof body?.internalLabel === 'string')
+                meta.internalLabel = body.internalLabel;
+            if (Object.keys(meta).length > 0)
+                next = updateSectionMetaInList(next, sectionId, meta);
+            if (typeof body?.visible === 'boolean') {
+                next = setSectionVisibility(next, sectionId, body.visible);
+            }
+            const saved = await persistPageSections(params.collection, params.id, next, ctx, auth.session.userId);
+            const updated = saved.find((s) => s.id === sectionId);
+            const validation = updated
+                ? validateSectionContent(updated.sectionType, updated.content, updated.settings)
+                : undefined;
+            return json({ data: { section: updated, sections: saved, validation } });
+        }
+        catch (err) {
+            return internalError(err, 'update page section');
+        }
+    });
+    // DELETE /page-sections/:collection/:id/:sectionId — remove a section.
+    router.delete('/page-sections/:collection/:id/:sectionId', async (request, params) => {
+        try {
+            const auth = await requireAuth(request);
+            if (auth.error)
+                return auth.error;
+            const scopeErr = requireCollectionScope(auth.session, params.collection, 'update');
+            if (scopeErr)
+                return scopeErr;
+            const ctx = buildActionContext(auth.session, db());
+            const loaded = await loadPageSections(params.collection, params.id, ctx);
+            if (loaded instanceof Response)
+                return loaded;
+            const sectionId = params.sectionId;
+            if (!loaded.sections.some((s) => s.id === sectionId)) {
+                return errorResponse(`Section "${sectionId}" not found on this page.`, 404);
+            }
+            const next = removeSectionFromList(loaded.sections, sectionId);
+            const saved = await persistPageSections(params.collection, params.id, next, ctx, auth.session.userId);
+            return json({ data: { sections: saved } });
+        }
+        catch (err) {
+            return internalError(err, 'remove page section');
+        }
+    });
+    // ---------------------------------------------------------------------------
+    // Post template routes
+    //
+    // A post type's template is a single document in the hidden
+    // `post-templates` collection, matched by `slug` == the post-type slug. It
+    // stores the design-driven header layout (`data.header`) and the default
+    // section list (`data.sections`) new posts inherit. Lets an external AI
+    // agent (Cursor/VS Code) read a type's template and build it from
+    // scope=post section types discovered via `/page-sections/types?scope=post`.
+    // ---------------------------------------------------------------------------
+    const POST_TEMPLATES_COLLECTION = 'post-templates';
+    const findPostTemplateDoc = async (postType, ctx) => {
+        const res = await listDocuments({ collection: POST_TEMPLATES_COLLECTION, pageSize: 200 }, ctx);
+        const docs = res.docs ?? [];
+        return (docs.find((d) => (d.slug ?? d.data?.slug) === postType) ?? null);
+    };
+    const templateResponse = (postType, doc) => {
+        if (!doc) {
+            return { postType, docId: null, header: defaultPostHeader(), sections: [] };
+        }
+        const data = doc.data ?? {};
+        return {
+            postType,
+            docId: doc.id,
+            header: coercePostHeader(data.header),
+            sections: coerceSections(data.sections),
+        };
+    };
+    // GET /post-templates/:type — read a post type's template (header +
+    // default sections). Returns an unsaved default when none exists yet.
+    router.get('/post-templates/:type', async (request, params) => {
+        try {
+            const auth = await requireAuth(request);
+            if (auth.error)
+                return auth.error;
+            const scopeErr = requireCollectionScope(auth.session, POST_TEMPLATES_COLLECTION, 'read');
+            if (scopeErr)
+                return scopeErr;
+            const ctx = buildActionContext(auth.session, db());
+            const doc = await findPostTemplateDoc(params.type, ctx);
+            return json({ data: templateResponse(params.type, doc) });
+        }
+        catch (err) {
+            return internalError(err, 'get post template');
+        }
+    });
+    // PUT /post-templates/:type — create or replace a post type's template.
+    // Body: { header?, sections? }. Header is coerced to a full PostHeaderConfig
+    // and sections are coerced (unknown section types dropped) so the stored
+    // template always renders.
+    router.put('/post-templates/:type', async (request, params) => {
+        try {
+            const auth = await requireAuth(request);
+            if (auth.error)
+                return auth.error;
+            const scopeErr = requireCollectionScope(auth.session, POST_TEMPLATES_COLLECTION, 'update');
+            if (scopeErr)
+                return scopeErr;
+            const body = (await request.json().catch(() => null));
+            const header = coercePostHeader(body?.header);
+            const sections = coerceSections(body?.sections);
+            const ctx = buildActionContext(auth.session, db());
+            const existing = await findPostTemplateDoc(params.type, ctx);
+            const data = {
+                title: `${params.type} template`,
+                slug: params.type,
+                postType: params.type,
+                header,
+                sections,
+                status: 'PUBLISHED',
+            };
+            const doc = existing
+                ? await updateDocument(POST_TEMPLATES_COLLECTION, existing.id, data, ctx)
+                : await createDocument(POST_TEMPLATES_COLLECTION, data, ctx);
+            await logEvent({
+                event: existing ? 'document_updated' : 'document_created',
+                userId: auth.session.userId,
+                details: {
+                    collection: POST_TEMPLATES_COLLECTION,
+                    documentId: doc.id,
+                    action: 'post_template_saved',
+                    postType: params.type,
+                },
+            });
+            return json({ data: templateResponse(params.type, doc) });
+        }
+        catch (err) {
+            return internalError(err, 'save post template');
+        }
+    });
+    // ---------------------------------------------------------------------------
     // Media routes
     // ---------------------------------------------------------------------------
     router.get('/media', async (request) => {
@@ -2578,6 +2953,36 @@ export function registerCMSRoutes(router) {
             score += 25;
         return score;
     }
+    /**
+     * Collection slugs that are written by the benchmark suite and a few
+     * other internal/test fixtures. Documents in these collections are
+     * never editor-facing content and should never appear in the
+     * dashboard's stats, counts, or recent-activity feed.
+     *
+     * This list is the fallback when the consumer ships collection
+     * definitions only to the admin client (e.g. `apps/dev`) and
+     * `getActuateConfig()?.collections` is therefore empty on the
+     * server. Production consumers normally pass `collections` to
+     * `handleActuateAPI({ config })`, in which case the registered
+     * slugs become the allowlist and this denylist is unused.
+     */
+    const INTERNAL_COLLECTION_SLUGS = ['benchmarks', 'bench'];
+    /**
+     * Build the Prisma `where` clause for "user-facing content".
+     *
+     *   - If the CMS config registered collections, restrict to those
+     *     slugs — anything else is orphan/test data.
+     *   - Otherwise fall back to excluding the internal denylist.
+     *
+     * Always excludes soft-deleted rows. Callers can spread additional
+     * filters on top (`status: 'PUBLISHED'`, etc.).
+     */
+    function userContentWhere(extra = {}) {
+        const cfg = getActuateConfig();
+        const registered = Object.keys(cfg?.collections ?? {});
+        const collectionFilter = registered.length > 0 ? { in: registered } : { notIn: [...INTERNAL_COLLECTION_SLUGS] };
+        return { deletedAt: null, collection: collectionFilter, ...extra };
+    }
     router.get('/stats', async (request) => {
         try {
             if (!isSecretMissing()) {
@@ -2592,8 +2997,13 @@ export function registerCMSRoutes(router) {
             catch {
                 return json({ data: EMPTY_STATS });
             }
+            // `userContentWhere()` filters out benchmark / orphan / internal
+            // collections so the dashboard surfaces editor content only. See
+            // the helper above for the allowlist-vs-denylist behaviour.
+            const contentWhere = userContentWhere();
+            const publishedContentWhere = userContentWhere({ status: 'PUBLISHED' });
             const [docResult, mediaResult, userResult, recentResult, collGroupResult, statusGroupResult, formResult, seoDocsResult, webhookTotalResult, webhookActiveResult,] = await Promise.allSettled([
-                safeCount(d.document, { deletedAt: null }),
+                safeCount(d.document, contentWhere),
                 safeCount(d.media),
                 safeCount(d.user),
                 safeFindMany(d.document, {
@@ -2603,7 +3013,7 @@ export function registerCMSRoutes(router) {
                     // -> Prisma Postgres path that saves ~80 ms (one full network
                     // RTT) on every dashboard load.
                     relationLoadStrategy: 'join',
-                    where: { deletedAt: null },
+                    where: contentWhere,
                     orderBy: { updatedAt: 'desc' },
                     take: 20,
                     select: {
@@ -2616,11 +3026,11 @@ export function registerCMSRoutes(router) {
                         createdBy: { select: { name: true, email: true } },
                     },
                 }),
-                safeGroupBy(d.document, ['collection'], { deletedAt: null }),
-                safeGroupBy(d.document, ['status'], { deletedAt: null }),
+                safeGroupBy(d.document, ['collection'], contentWhere),
+                safeGroupBy(d.document, ['status'], contentWhere),
                 safeCount(d.formSubmission),
                 safeFindMany(d.document, {
-                    where: { deletedAt: null, status: 'PUBLISHED' },
+                    where: publishedContentWhere,
                     select: { data: true },
                     take: 200,
                 }),