domma-cms 0.1.0 → 0.2.0

package/server/services/collections.js

@@ -0,0 +1,430 @@
+/**
+ * Collections Service
+ * Schema-first data store — one directory per collection under content/collections/{slug}/.
+ * Each collection has a schema.json (field definitions + API access config) and a data.json
+ * (array of entries with id, data, and meta).
+ */
+import fs from 'fs/promises';
+import path from 'path';
+import { v4 as uuidv4 } from 'uuid';
+import { config } from '../config.js';
+
+const COLLECTIONS_DIR = path.resolve(config.content.collectionsDir);
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+async function ensureDir() {
+    await fs.mkdir(COLLECTIONS_DIR, { recursive: true });
+}
+
+function collectionDir(slug) {
+    return path.join(COLLECTIONS_DIR, slug);
+}
+
+function schemaPath(slug) {
+    return path.join(collectionDir(slug), 'schema.json');
+}
+
+function dataPath(slug) {
+    return path.join(collectionDir(slug), 'data.json');
+}
+
+function slugify(str) {
+    return str.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
+}
+
+async function readSchema(slug) {
+    const raw = await fs.readFile(schemaPath(slug), 'utf8');
+    return JSON.parse(raw);
+}
+
+async function writeSchema(schema) {
+    await fs.writeFile(schemaPath(schema.slug), JSON.stringify(schema, null, 2) + '\n', 'utf8');
+}
+
+async function readData(slug) {
+    try {
+        const raw = await fs.readFile(dataPath(slug), 'utf8');
+        return JSON.parse(raw);
+    } catch {
+        return [];
+    }
+}
+
+async function writeData(slug, entries) {
+    await fs.writeFile(dataPath(slug), JSON.stringify(entries, null, 2) + '\n', 'utf8');
+}
+
+/**
+ * Default API access configuration for a new collection.
+ *
+ * @returns {object}
+ */
+function defaultApiAccess() {
+    return {
+        create: { enabled: false, access: 'admin' },
+        read:   { enabled: true,  access: 'public' },
+        update: { enabled: false, access: 'admin' },
+        delete: { enabled: false, access: 'admin' }
+    };
+}
+
+// ---------------------------------------------------------------------------
+// Schema (collection) operations
+// ---------------------------------------------------------------------------
+
+/**
+ * List all collections — reads all schema.json files and appends entryCount.
+ *
+ * @returns {Promise<object[]>}
+ */
+export async function listCollections() {
+    await ensureDir();
+    let slugs;
+    try {
+        const entries = await fs.readdir(COLLECTIONS_DIR, { withFileTypes: true });
+        slugs = entries.filter(e => e.isDirectory()).map(e => e.name);
+    } catch {
+        return [];
+    }
+
+    const results = await Promise.allSettled(slugs.map(async (slug) => {
+        const schema = await readSchema(slug);
+        const data   = await readData(slug);
+        return { ...schema, entryCount: data.length };
+    }));
+
+    return results
+        .filter(r => r.status === 'fulfilled')
+        .map(r => r.value)
+        .sort((a, b) => a.title.localeCompare(b.title));
+}
+
+/**
+ * Get a single collection schema.
+ *
+ * @param {string} slug
+ * @returns {Promise<object|null>}
+ */
+export async function getCollection(slug) {
+    try {
+        return await readSchema(slug);
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Create a new collection.
+ *
+ * @param {object} opts
+ * @param {string}   opts.title
+ * @param {string}   [opts.slug]       - Auto-generated from title if omitted
+ * @param {string}   [opts.description]
+ * @param {object[]} [opts.fields]
+ * @param {object}   [opts.api]
+ * @returns {Promise<object>} Created schema
+ * @throws {Error} If a collection with that slug already exists
+ */
+export async function createCollection({ title, slug, description = '', fields = [], api = {} }) {
+    await ensureDir();
+    const finalSlug = slug ? slugify(slug) : slugify(title);
+    if (!finalSlug) throw new Error('Could not derive a slug from the title');
+
+    const dir = collectionDir(finalSlug);
+    try {
+        await fs.mkdir(dir, { recursive: false });
+    } catch (err) {
+        if (err.code === 'EEXIST') throw new Error(`A collection with slug "${finalSlug}" already exists`);
+        throw err;
+    }
+
+    const now = new Date().toISOString();
+    const schema = {
+        slug: finalSlug,
+        title: title.trim(),
+        description: description.trim(),
+        fields,
+        api: { ...defaultApiAccess(), ...api },
+        createdAt: now,
+        updatedAt: now
+    };
+
+    await writeSchema(schema);
+    await writeData(finalSlug, []);
+    return schema;
+}
+
+/**
+ * Update a collection schema.
+ *
+ * @param {string} slug
+ * @param {object} updates - Partial schema fields to merge
+ * @returns {Promise<object>} Updated schema
+ * @throws {Error} If collection not found
+ */
+export async function updateCollection(slug, updates) {
+    const schema = await getCollection(slug);
+    if (!schema) throw new Error(`Collection "${slug}" not found`);
+
+    const { slug: _ignore, createdAt, ...rest } = updates;
+    const updated = {
+        ...schema,
+        ...rest,
+        slug,
+        createdAt: schema.createdAt,
+        updatedAt: new Date().toISOString()
+    };
+
+    await writeSchema(updated);
+    return updated;
+}
+
+/**
+ * Delete a collection and all its data.
+ *
+ * @param {string} slug
+ * @returns {Promise<void>}
+ * @throws {Error} If collection not found
+ */
+export async function deleteCollection(slug) {
+    const schema = await getCollection(slug);
+    if (!schema) throw new Error(`Collection "${slug}" not found`);
+    await fs.rm(collectionDir(slug), { recursive: true, force: true });
+}
+
+// ---------------------------------------------------------------------------
+// Entry operations
+// ---------------------------------------------------------------------------
+
+/**
+ * Validate entry data against a collection schema.
+ *
+ * @param {object} schema
+ * @param {object} data
+ * @returns {{ valid: boolean, errors: string[] }}
+ */
+export function validateEntryData(schema, data) {
+    const errors = [];
+    for (const field of (schema.fields || [])) {
+        const val = data[field.name];
+        const isEmpty = val === undefined || val === null || val === '';
+        if (field.required && isEmpty) {
+            errors.push(`"${field.label || field.name}" is required`);
+        }
+    }
+    return { valid: errors.length === 0, errors };
+}
+
+/**
+ * List entries with optional pagination, sorting, and search.
+ *
+ * @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]
+ * @returns {Promise<{ entries: object[], total: number, page: number, limit: number }>}
+ */
+export async function listEntries(slug, { page = 1, limit = 50, sort = 'createdAt', order = 'desc', search } = {}) {
+    const schema = await getCollection(slug);
+    if (!schema) throw new Error(`Collection "${slug}" not found`);
+
+    let entries = await readData(slug);
+
+    if (search) {
+        const term = search.toLowerCase();
+        entries = entries.filter(entry => {
+            return Object.values(entry.data || {}).some(v => String(v).toLowerCase().includes(term));
+        });
+    }
+
+    entries.sort((a, b) => {
+        const aVal = sort === 'createdAt' ? a.meta?.createdAt : (a.data?.[sort] ?? '');
+        const bVal = sort === 'createdAt' ? b.meta?.createdAt : (b.data?.[sort] ?? '');
+        const cmp  = String(aVal).localeCompare(String(bVal));
+        return order === 'desc' ? -cmp : cmp;
+    });
+
+    const total  = entries.length;
+    const offset = (page - 1) * limit;
+    return { entries: entries.slice(offset, offset + limit), total, page, limit };
+}
+
+/**
+ * Get a single entry by ID.
+ *
+ * @param {string} slug
+ * @param {string} entryId
+ * @returns {Promise<object|null>}
+ */
+export async function getEntry(slug, entryId) {
+    const entries = await readData(slug);
+    return entries.find(e => e.id === entryId) || null;
+}
+
+/**
+ * Create a new entry in a collection.
+ *
+ * @param {string} slug
+ * @param {object} data          - Field values keyed by field name
+ * @param {object} [meta]
+ * @param {string} [meta.createdBy]
+ * @param {string} [meta.source]  - 'admin' | 'api' | 'import' | 'form:{slug}'
+ * @returns {Promise<object>} Created entry
+ * @throws {Error} If validation fails or collection not found
+ */
+export async function createEntry(slug, data, { createdBy = null, source = 'admin' } = {}) {
+    const schema = await getCollection(slug);
+    if (!schema) throw new Error(`Collection "${slug}" not found`);
+
+    const { valid, errors } = validateEntryData(schema, data);
+    if (!valid) throw new Error(`Validation failed: ${errors.join('; ')}`);
+
+    const now = new Date().toISOString();
+    const entry = {
+        id: uuidv4(),
+        data,
+        meta: { createdAt: now, updatedAt: now, createdBy, source }
+    };
+
+    const entries = await readData(slug);
+    entries.push(entry);
+    await writeData(slug, entries);
+    return entry;
+}
+
+/**
+ * Update an existing entry.
+ *
+ * @param {string} slug
+ * @param {string} entryId
+ * @param {object} data
+ * @returns {Promise<object>} Updated entry
+ * @throws {Error} If entry not found or validation fails
+ */
+export async function updateEntry(slug, entryId, data) {
+    const schema = await getCollection(slug);
+    if (!schema) throw new Error(`Collection "${slug}" not found`);
+
+    const entries = await readData(slug);
+    const idx     = entries.findIndex(e => e.id === entryId);
+    if (idx === -1) throw new Error('Entry not found');
+
+    const { valid, errors } = validateEntryData(schema, data);
+    if (!valid) throw new Error(`Validation failed: ${errors.join('; ')}`);
+
+    entries[idx] = {
+        ...entries[idx],
+        data,
+        meta: { ...entries[idx].meta, updatedAt: new Date().toISOString() }
+    };
+
+    await writeData(slug, entries);
+    return entries[idx];
+}
+
+/**
+ * Delete a single entry.
+ *
+ * @param {string} slug
+ * @param {string} entryId
+ * @returns {Promise<void>}
+ * @throws {Error} If entry not found
+ */
+export async function deleteEntry(slug, entryId) {
+    const entries = await readData(slug);
+    const idx     = entries.findIndex(e => e.id === entryId);
+    if (idx === -1) throw new Error('Entry not found');
+    entries.splice(idx, 1);
+    await writeData(slug, entries);
+}
+
+/**
+ * Delete all entries from a collection.
+ *
+ * @param {string} slug
+ * @returns {Promise<void>}
+ */
+export async function clearEntries(slug) {
+    const schema = await getCollection(slug);
+    if (!schema) throw new Error(`Collection "${slug}" not found`);
+    await writeData(slug, []);
+}
+
+// ---------------------------------------------------------------------------
+// Import / Export
+// ---------------------------------------------------------------------------
+
+/**
+ * Export collection entries as a JSON or CSV string.
+ *
+ * @param {string} slug
+ * @param {'json'|'csv'} [format='json']
+ * @returns {Promise<string>}
+ */
+export async function exportEntries(slug, format = 'json') {
+    const schema  = await getCollection(slug);
+    if (!schema) throw new Error(`Collection "${slug}" not found`);
+    const entries = await readData(slug);
+
+    if (format === 'csv') {
+        const fields = schema.fields.map(f => f.name);
+        const header = ['id', ...fields, 'createdAt'].join(',');
+        const rows   = entries.map(e => {
+            const cells = ['id', ...fields, 'createdAt'].map(key => {
+                const val = key === 'id' ? e.id : key === 'createdAt' ? (e.meta?.createdAt || '') : (e.data?.[key] ?? '');
+                const str = String(val).replace(/"/g, '""');
+                return `"${str}"`;
+            });
+            return cells.join(',');
+        });
+        return [header, ...rows].join('\n');
+    }
+
+    return JSON.stringify(entries, null, 2);
+}
+
+/**
+ * Bulk-import entries into a collection.
+ *
+ * @param {string}   slug
+ * @param {object[]} incoming   - Array of entries (must have at least a `data` key)
+ * @param {object}   [opts]
+ * @param {string}   [opts.createdBy]
+ * @returns {Promise<{ imported: number, skipped: number, errors: string[] }>}
+ */
+export async function importEntries(slug, incoming, { createdBy = null } = {}) {
+    const schema  = await getCollection(slug);
+    if (!schema) throw new Error(`Collection "${slug}" not found`);
+
+    const existing = await readData(slug);
+    const now = new Date().toISOString();
+
+    let imported = 0;
+    let skipped  = 0;
+    const errors = [];
+
+    for (const item of incoming) {
+        const data = item.data || item;
+        const { valid, errors: valErrors } = validateEntryData(schema, data);
+        if (!valid) {
+            skipped++;
+            errors.push(valErrors.join('; '));
+            continue;
+        }
+        existing.push({
+            id:   uuidv4(),
+            data,
+            meta: { createdAt: now, updatedAt: now, createdBy, source: 'import' }
+        });
+        imported++;
+    }
+
+    await writeData(slug, existing);
+    return { imported, skipped, errors };
+}

package/server/services/content.js

@@ -7,6 +7,7 @@ import fs from 'fs/promises';
 import path from 'path';
 import {parseMarkdown, serialiseMarkdown} from './markdown.js';
 import {config} from '../config.js';
+import {hooks} from './hooks.js';
 
 const CONTENT_DIR = config.content.contentDir;
 const PAGES_DIR = path.join(CONTENT_DIR, 'pages');
@@ -68,12 +69,15 @@ export async function createPage(urlPath, frontmatter, body) {
         showInNav: frontmatter.showInNav ?? false,
         sidebar: frontmatter.sidebar ?? false,
         seo: frontmatter.seo || {},
+        dconfig: frontmatter.dconfig || null,
         createdAt: now,
         updatedAt: now
     };
 
     await fs.writeFile(filePath, serialiseMarkdown(meta, body || ''), 'utf8');
-    return readPageFile(filePath);
+    const page = await readPageFile(filePath);
+    hooks.emit('content:pageCreated', {page, urlPath});
+    return page;
 }
 
 /**
@@ -98,7 +102,9 @@ export async function updatePage(urlPath, frontmatter, body) {
     if (existingMeta.createdAt) meta.createdAt = existingMeta.createdAt;
 
     await fs.writeFile(filePath, serialiseMarkdown(meta, body ?? existingContent), 'utf8');
-    return readPageFile(filePath);
+    const page = await readPageFile(filePath);
+    hooks.emit('content:pageUpdated', {page, urlPath});
+    return page;
 }
 
 /**
@@ -125,6 +131,7 @@ export async function renamePage(oldUrlPath, newUrlPath) {
 export async function deletePage(urlPath) {
     const filePath = await resolveExistingFilePath(urlPath);
     await fs.unlink(filePath);
+    hooks.emit('content:pageDeleted', {urlPath});
 }
 
 // ---------------------------------------------------------------------------
@@ -165,6 +172,7 @@ export async function saveMedia(filename, buffer) {
     await fs.mkdir(MEDIA_DIR, { recursive: true });
     const filePath = path.join(MEDIA_DIR, filename);
     await fs.writeFile(filePath, buffer);
+    hooks.emit('content:mediaUploaded', {filename});
     return { name: filename, url: `/media/${filename}` };
 }
 
@@ -177,6 +185,7 @@ export async function saveMedia(filename, buffer) {
 export async function deleteMedia(filename) {
     const filePath = path.join(MEDIA_DIR, filename);
     await fs.unlink(filePath);
+    hooks.emit('content:mediaDeleted', {filename});
 }
 
 /**

package/server/services/hooks.js

@@ -0,0 +1,109 @@
+/**
+ * Hook System
+ * Provides three extensibility mechanisms for plugins:
+ *   1. EventEmitter — fire-and-forget content lifecycle events
+ *   2. Shortcode registry — register custom [shortcode] handlers at startup
+ *   3. Sanitize rule extensions — expand the HTML whitelist for plugin output
+ *   4. Transform pipeline — modify markdown/render values at named hook points
+ */
+import {EventEmitter} from 'node:events';
+
+// ---------------------------------------------------------------------------
+// 1. Event bus
+// ---------------------------------------------------------------------------
+
+const hooks = new EventEmitter();
+hooks.on('error', (err) => console.error('[hooks]', err));
+
+export {hooks};
+
+// ---------------------------------------------------------------------------
+// 2. Shortcode registry
+// ---------------------------------------------------------------------------
+
+const _shortcodes = new Map(); // name -> { name, handler, priority }
+
+/**
+ * Register a shortcode handler.
+ * Handler signature: (attrStr, body, context) => string
+ *   - body is null for self-closing shortcodes ([name attrs /])
+ *   - context provides { parseShortcodeAttrs, scrubCodeRegions, marked, processCardBlocks, processGridBlocks }
+ *
+ * @param {string} name - Shortcode name (case-insensitive in regex, stored lowercase)
+ * @param {Function} handler
+ * @param {{ priority?: number }} options
+ */
+export function registerShortcode(name, handler, {priority = 10} = {}) {
+  _shortcodes.set(name.toLowerCase(), {name: name.toLowerCase(), handler, priority});
+}
+
+/**
+ * Return all registered shortcode processors sorted by priority (ascending).
+ *
+ * @returns {{ name: string, handler: Function, priority: number }[]}
+ */
+export function getShortcodeProcessors() {
+  return [..._shortcodes.values()].sort((a, b) => a.priority - b.priority);
+}
+
+// ---------------------------------------------------------------------------
+// 3. Sanitize rule extensions
+// ---------------------------------------------------------------------------
+
+const _sanitizeExtensions = {tags: [], attributes: {}};
+
+/**
+ * Extend the HTML sanitizer whitelist with plugin-specific tags and attributes.
+ *
+ * @param {{ tags?: string[], attributes?: object }} rules
+ */
+export function registerSanitizeRules({tags = [], attributes = {}} = {}) {
+  _sanitizeExtensions.tags.push(...tags);
+  Object.assign(_sanitizeExtensions.attributes, attributes);
+}
+
+/**
+ * Return the merged sanitize rule extensions.
+ *
+ * @returns {{ tags: string[], attributes: object }}
+ */
+export function getSanitizeExtensions() {
+  return _sanitizeExtensions;
+}
+
+// ---------------------------------------------------------------------------
+// 4. Transform pipeline
+// ---------------------------------------------------------------------------
+
+const _transforms = new Map(); // hookName -> [{ fn, priority }]
+
+/**
+ * Register a transform function at a named hook point.
+ * Available hook names: 'markdown:beforeParse', 'markdown:afterParse',
+ *                       'render:beforeRender', 'render:afterRender'
+ *
+ * @param {string} hookName
+ * @param {Function} fn - (value, context) => value
+ * @param {{ priority?: number }} options
+ */
+export function registerTransform(hookName, fn, {priority = 10} = {}) {
+  if (!_transforms.has(hookName)) _transforms.set(hookName, []);
+  _transforms.get(hookName).push({fn, priority});
+  _transforms.get(hookName).sort((a, b) => a.priority - b.priority);
+}
+
+/**
+ * Run all transforms registered at hookName against value, passing context.
+ * Returns the final transformed value.
+ *
+ * @param {string} hookName
+ * @param {*} value
+ * @param {object} [context={}]
+ * @returns {*}
+ */
+export function applyTransforms(hookName, value, context = {}) {
+  for (const {fn} of (_transforms.get(hookName) || [])) {
+    value = fn(value, context);
+  }
+  return value;
+}