domma-cms 0.13.5 → 0.14.0

package/server/services/components.js

@@ -0,0 +1,653 @@
+/**
+ * Components Service
+ * CRUD, compile pipeline, and seeding for .dmc component files
+ * stored in content/components/.
+ */
+import fs from 'fs/promises';
+import path from 'path';
+import {fileURLToPath} from 'url';
+import {getPluginComponents} from './hooks.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const COMPONENTS_DIR = path.resolve(__dirname, '../../content/components');
+
+/** Component names: lowercase alphanumeric + hyphens. Drives the Custom Element tag `dm-<name>`. */
+const NAME_RE = /^[a-z][a-z0-9-]*$/;
+
+function assertValidName(name) {
+    if (!NAME_RE.test(name)) {
+        const err = new Error('Invalid component name. Use a letter followed by lowercase letters, digits, and hyphens.');
+        err.code = 'INVALID_NAME';
+        throw err;
+    }
+}
+
+/**
+ * Absolute filesystem path to a component's .dmc source file.
+ *
+ * @param {string} name - Component name (without extension).
+ * @returns {string}
+ */
+function componentFilePath(name) { return path.join(COMPONENTS_DIR, `${name}.dmc`); }
+
+/**
+ * Absolute filesystem path to a component's companion .meta.json file.
+ *
+ * @param {string} name - Component name (without extension).
+ * @returns {string}
+ */
+function componentMetaPath(name) { return path.join(COMPONENTS_DIR, `${name}.meta.json`); }
+
+/**
+ * Split a .dmc source string into its four SFC blocks.
+ * Missing <template>, <props>, or <script> is a compile error;
+ * <style> is optional (returns '').
+ *
+ * @param {string} source
+ * @returns {{template: string, props: string, script: string, style: string}}
+ * @throws {Error} With code MISSING_BLOCK when a required block is absent.
+ */
+export function parseDmcSource(source) {
+    const extract = (tag) => {
+        const re = new RegExp(`<${tag}>([\\s\\S]*?)</${tag}>`);
+        const m = source.match(re);
+        return m ? m[1].trim() : null;
+    };
+    const template = extract('template');
+    const props    = extract('props');
+    const script   = extract('script');
+    const style    = extract('style') ?? '';
+
+    for (const [name, value] of [['template', template], ['props', props], ['script', script]]) {
+        if (value === null) {
+            const err = new Error(`MISSING_BLOCK: required <${name}> block is absent.`);
+            err.code = 'MISSING_BLOCK';
+            err.block = name;
+            throw err;
+        }
+    }
+    return {template, props, script, style};
+}
+
+const VALID_PROP_TYPES = new Set(['string', 'number', 'boolean', 'array', 'object']);
+
+/**
+ * Parse and validate a <props> block JSON body.
+ *
+ * @param {string} json
+ * @returns {object} Parsed props schema.
+ * @throws {Error} With code INVALID_PROPS_JSON on any problem.
+ */
+export function validatePropsJson(json) {
+    let parsed;
+    try { parsed = JSON.parse(json); }
+    catch (e) {
+        const err = new Error(`INVALID_PROPS_JSON: <props> is not valid JSON: ${e.message}`);
+        err.code = 'INVALID_PROPS_JSON';
+        throw err;
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        const err = new Error('INVALID_PROPS_JSON: <props> must be a JSON object');
+        err.code = 'INVALID_PROPS_JSON';
+        throw err;
+    }
+    for (const [propName, def] of Object.entries(parsed)) {
+        if (!def || typeof def !== 'object' || !VALID_PROP_TYPES.has(def.type)) {
+            const err = new Error(`INVALID_PROPS_JSON: <props>.${propName} must declare a valid type (one of: ${[...VALID_PROP_TYPES].join(', ')})`);
+            err.code = 'INVALID_PROPS_JSON';
+            throw err;
+        }
+    }
+    return parsed;
+}
+
+/**
+ * Transform a <script> body for embedding.
+ * Removes the `export default` prefix and any trailing semicolon,
+ * leaving only the object expression.
+ *
+ * @param {string} body - Raw <script> body.
+ * @returns {string} The bare object expression.
+ * @throws {Error} With code SCRIPT_MISSING_EXPORT when no export default is found.
+ */
+export function stripExportDefault(body) {
+    const m = body.match(/^\s*export\s+default\s+([\s\S]+?)\s*;?\s*$/);
+    if (!m) {
+        const err = new Error('SCRIPT_MISSING_EXPORT: <script> must have an `export default` statement.');
+        err.code = 'SCRIPT_MISSING_EXPORT';
+        throw err;
+    }
+    return m[1];
+}
+
+/**
+ * Escape a string for use inside a JS template literal.
+ * Handles backticks, backslashes, and `${` sequences.
+ *
+ * @param {string} str
+ * @returns {string}
+ */
+function toBacktickLiteral(str) {
+    return '`' + String(str).replace(/\\/g, '\\\\').replace(/`/g, '\\`').replace(/\$\{/g, '\\${') + '`';
+}
+
+/**
+ * Compile a .dmc source into a self-contained JS module that registers
+ * the component on load via Domma.component().
+ *
+ * @param {string} source - Full .dmc file contents.
+ * @param {string} name   - Component name (controls the Custom Element tag).
+ * @returns {{js: string|null, errors: Array<{type: string, message: string, block?: string}>}}
+ */
+export function compileComponent(source, name) {
+    try {
+        assertValidName(name);
+    } catch (e) {
+        return {js: null, errors: [{type: e.code, message: e.message}]};
+    }
+
+    let parts;
+    try { parts = parseDmcSource(source); }
+    catch (e) { return {js: null, errors: [{type: e.code, message: e.message, block: e.block}]}; }
+
+    let propsObj;
+    try { propsObj = validatePropsJson(parts.props); }
+    catch (e) { return {js: null, errors: [{type: e.code, message: e.message}]}; }
+
+    let definitionExpr;
+    try { definitionExpr = stripExportDefault(parts.script); }
+    catch (e) { return {js: null, errors: [{type: e.code, message: e.message}]}; }
+
+    const js = [
+        `// Compiled from ${name}.dmc — do not edit by hand.`,
+        `const template = ${toBacktickLiteral(parts.template)};`,
+        `const style = ${toBacktickLiteral(parts.style)};`,
+        `const props = ${JSON.stringify(propsObj)};`,
+        `const definition = ${definitionExpr};`,
+        `Domma.component('dm-${name}', { template, style, props, ...definition });`
+    ].join('\n');
+
+    return {js, errors: []};
+}
+
+// ─── In-memory compile cache ──────────────────────────────────────────────
+
+const _compileCache = new Map();  // name → {js, errors, mtime}
+
+/**
+ * Drop a cached compiled output for `name`.
+ * Called on component save/delete to force recompilation on next request.
+ *
+ * @param {string} name
+ */
+export function invalidateCache(name) { _compileCache.delete(name); }
+
+/**
+ * Return the compiled JS for `name`, reading and compiling the source file
+ * lazily if the cache entry is missing or stale (mtime changed).
+ *
+ * @param {string} name
+ * @returns {Promise<{js: string|null, errors: Array, mtime: number}>}
+ * @throws {Error} With code INVALID_NAME on a bad name, or ENOENT when the
+ *                 source file does not exist.
+ */
+export async function getCompiledJs(name) {
+    assertValidName(name);
+
+    // Plugin-contributed components come from memory, never disk.
+    const plugin = getPluginComponents().find(pc => pc.name === name);
+    if (plugin) {
+        const cached = _compileCache.get(name);
+        if (cached && cached.origin === 'plugin' && cached.sourceLength === plugin.source.length) return cached;
+        const {js, errors} = compileComponent(plugin.source, name);
+        const entry = {js, errors, mtime: 0, origin: 'plugin', sourceLength: plugin.source.length};
+        _compileCache.set(name, entry);
+        return entry;
+    }
+
+    const fp = componentFilePath(name);
+    const stat = await fs.stat(fp);
+    const cached = _compileCache.get(name);
+    if (cached && cached.origin === 'file' && cached.mtime === stat.mtimeMs) return cached;
+    const source = await fs.readFile(fp, 'utf8');
+    const {js, errors} = compileComponent(source, name);
+    const entry = {js, errors, mtime: stat.mtimeMs, origin: 'file'};
+    _compileCache.set(name, entry);
+    return entry;
+}
+
+// ─── CRUD operations ──────────────────────────────────────────────────────
+
+/**
+ * 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.
+ *
+ * @returns {Promise<Array<{name: string, size: number, updatedAt: string|null, bundled: boolean, props: object}>>}
+ */
+export async function listComponents() {
+    await fs.mkdir(COMPONENTS_DIR, {recursive: true});
+    const files = await fs.readdir(COMPONENTS_DIR);
+    const entries = [];
+    for (const file of files.filter(f => f.endsWith('.dmc'))) {
+        const name = file.slice(0, -4);
+        const stat = await fs.stat(path.join(COMPONENTS_DIR, file)).catch(() => null);
+        let bundled = false;
+        try {
+            const meta = JSON.parse(await fs.readFile(componentMetaPath(name), 'utf8'));
+            bundled = !!meta.bundled;
+        } catch { /* no meta */ }
+        let props = {};
+        try {
+            const src = await fs.readFile(path.join(COMPONENTS_DIR, file), 'utf8');
+            const {props: propsBlock} = parseDmcSource(src);
+            props = validatePropsJson(propsBlock);
+        } catch { /* malformed — list still usable */ }
+        entries.push({
+            name,
+            size: stat?.size ?? 0,
+            updatedAt: stat?.mtime?.toISOString() ?? null,
+            bundled,
+            props,
+            origin: 'file',
+        });
+    }
+
+    // Merge plugin-contributed components (read-only, no disk file).
+    for (const pc of getPluginComponents()) {
+        let props = {};
+        try {
+            const parts = parseDmcSource(pc.source);
+            props = validatePropsJson(parts.props);
+        } catch { /* malformed plugin source — list still usable */ }
+        entries.push({
+            name: pc.name,
+            size: pc.source.length,
+            updatedAt: null,
+            bundled: true,
+            props,
+            origin: 'plugin',
+        });
+    }
+
+    return entries.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/**
+ * Read a component's raw .dmc source plus its parsed props.
+ *
+ * @param {string} name
+ * @returns {Promise<{name: string, source: string, props: object, bundled: boolean}>}
+ * @throws {Error} With code INVALID_NAME or ENOENT.
+ */
+export async function getComponent(name) {
+    assertValidName(name);
+    try {
+        const source = await fs.readFile(componentFilePath(name), 'utf8');
+        let bundled = false;
+        try {
+            const meta = JSON.parse(await fs.readFile(componentMetaPath(name), 'utf8'));
+            bundled = !!meta.bundled;
+        } catch { /* no meta */ }
+        let props = {};
+        try {
+            const parts = parseDmcSource(source);
+            props = validatePropsJson(parts.props);
+        } catch { /* return malformed source for editing; UI flags it */ }
+        return {name, source, props, bundled};
+    } catch (err) {
+        if (err.code === 'ENOENT') {
+            const nf = new Error('Component not found');
+            nf.code = 'ENOENT';
+            throw nf;
+        }
+        throw err;
+    }
+}
+
+/**
+ * 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
+ * @param {string} source
+ * @param {object} [opts]
+ * @param {boolean} [opts.bundled] - Mark as bundled via a .meta.json companion.
+ * @returns {Promise<{success: boolean, name: string, errors: Array}>}
+ */
+export async function saveComponent(name, source, {bundled = false} = {}) {
+    assertValidName(name);
+    if (getPluginComponents().some(pc => pc.name === name)) {
+        const e = new Error('That name is registered by a plugin and cannot be edited from the admin.');
+        e.code = 'PLUGIN_OWNED';
+        throw e;
+    }
+    const {errors} = compileComponent(source, name);
+    if (errors.length) return {success: false, name, errors};
+
+    await fs.mkdir(COMPONENTS_DIR, {recursive: true});
+    await fs.writeFile(componentFilePath(name), source, 'utf8');
+    const metaPath = componentMetaPath(name);
+    if (bundled) await fs.writeFile(metaPath, JSON.stringify({bundled: true}, null, 2) + '\n', 'utf8');
+    else         await fs.unlink(metaPath).catch(() => {});
+    invalidateCache(name);
+    await _refreshSanitiserAllowlist();
+    return {success: true, name, errors: []};
+}
+
+/** 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 */ }
+}
+
+/**
+ * Delete a component's .dmc source and its companion .meta.json.
+ *
+ * @param {string} name
+ * @returns {Promise<void>}
+ * @throws {Error} With code INVALID_NAME or ENOENT.
+ */
+export async function deleteComponent(name) {
+    assertValidName(name);
+    if (getPluginComponents().some(pc => pc.name === name)) {
+        const e = new Error('That name is registered by a plugin and cannot be deleted from the admin.');
+        e.code = 'PLUGIN_OWNED';
+        throw e;
+    }
+    try { await fs.unlink(componentFilePath(name)); }
+    catch (err) {
+        if (err.code === 'ENOENT') {
+            const nf = new Error('Component not found');
+            nf.code = 'ENOENT';
+            throw nf;
+        }
+        throw err;
+    }
+    await fs.unlink(componentMetaPath(name)).catch(() => {});
+    invalidateCache(name);
+    await _refreshSanitiserAllowlist();
+}
+
+// ─── Export / import bundle helpers ───────────────────────────────────────
+
+/** Current .dmcomponent.json bundle schema version. Bump when the shape changes. */
+export const BUNDLE_FORMAT = 1;
+
+/**
+ * Export a component as a downloadable bundle object.
+ *
+ * @param {string} name
+ * @returns {Promise<{format: number, name: string, source: string, bundled: boolean}>}
+ */
+export async function exportBundle(name) {
+    const {source, bundled} = await getComponent(name);
+    return {format: BUNDLE_FORMAT, name, source, bundled};
+}
+
+/**
+ * Import a bundle. Throws with code CONFLICT on name collision unless
+ * `overwrite === true`.
+ *
+ * @param {object} bundle
+ * @param {object} [opts]
+ * @param {boolean} [opts.overwrite]
+ * @returns {Promise<{success: boolean, name: string, errors: Array}>}
+ * @throws {Error} With code INVALID_BUNDLE, INVALID_NAME, or CONFLICT.
+ */
+export async function importBundle(bundle, {overwrite = false} = {}) {
+    if (!bundle || typeof bundle !== 'object') {
+        const e = new Error('Invalid bundle'); e.code = 'INVALID_BUNDLE'; throw e;
+    }
+    if (typeof bundle.format !== 'number' || bundle.format > BUNDLE_FORMAT) {
+        const e = new Error(`Unsupported bundle format (${bundle.format})`);
+        e.code = 'INVALID_BUNDLE';
+        throw e;
+    }
+    if (typeof bundle.name !== 'string' || typeof bundle.source !== 'string') {
+        const e = new Error('Bundle missing name or source');
+        e.code = 'INVALID_BUNDLE';
+        throw e;
+    }
+    if (!overwrite) {
+        try {
+            await getComponent(bundle.name);
+            const e = new Error('Component already exists');
+            e.code = 'CONFLICT';
+            e.name = bundle.name;
+            throw e;
+        } catch (err) {
+            if (err.code !== 'ENOENT') throw err;
+        }
+    }
+    return saveComponent(bundle.name, bundle.source, {bundled: !!bundle.bundled});
+}
+
+// ─── Seeded starter components ────────────────────────────────────────────
+
+const SEED_COMPONENTS = {
+
+    counter: `
+<template>
+<div class="dm-counter">
+  <div class="value">{{count}}</div>
+  <div class="controls">
+    <button data-action="dec">−</button>
+    <button data-action="inc">+</button>
+    {{#if showReset}}<button data-action="reset">Reset</button>{{/if}}
+  </div>
+</div>
+</template>
+<props>
+{
+  "initial":   { "type": "number",  "default": 0,     "label": "Initial value" },
+  "step":      { "type": "number",  "default": 1,     "label": "Step size" },
+  "showReset": { "type": "boolean", "default": false, "label": "Show reset button" }
+}
+</props>
+<script>
+// 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 }; },
+  methods: {
+    inc()   { this.set({ count: this.data.count + this.props.step }); },
+    dec()   { this.set({ count: this.data.count - this.props.step }); },
+    reset() { this.set({ count: this.props.initial }); }
+  },
+  onMount() {
+    this.set({ count: this.props.initial });
+    this.el.shadowRoot.addEventListener('click', (e) => {
+      const action = e.target.dataset.action;
+      if (action && this[action]) this[action]();
+    });
+  }
+};
+</script>
+<style>
+.dm-counter { text-align: center; padding: 1rem; }
+.dm-counter .value { font-size: 2.5rem; font-weight: 700; margin-bottom: .5rem; }
+.dm-counter .controls button { margin: 0 .25rem; padding: .4rem .8rem; }
+</style>
+`,
+
+    'copy-button': `
+<template>
+<button class="dm-copy-btn" data-action="copy">{{label}}</button>
+</template>
+<props>
+{
+  "text":        { "type": "string", "default": "",       "label": "Text to copy" },
+  "label":       { "type": "string", "default": "Copy",   "label": "Button label" },
+  "copiedLabel": { "type": "string", "default": "Copied!","label": "Confirmation label" }
+}
+</props>
+<script>
+export default {
+  data() { return { label: '' }; },
+  methods: {
+    async copy() {
+      try {
+        await navigator.clipboard.writeText(this.props.text);
+        this.set({ label: this.props.copiedLabel });
+        setTimeout(() => this.set({ label: this.props.label }), 1500);
+      } catch {}
+    }
+  },
+  onMount() {
+    this.set({ label: this.props.label });
+    this.el.shadowRoot.addEventListener('click', (e) => {
+      if (e.target.dataset.action === 'copy') this.copy();
+    });
+  }
+};
+</script>
+<style>
+.dm-copy-btn { padding: .5rem 1rem; cursor: pointer; }
+</style>
+`,
+
+    'reveal-panel': `
+<template>
+<div class="dm-reveal">
+  <button class="toggle" data-action="toggle">{{heading}}</button>
+  {{#if open}}<div class="body"><slot></slot></div>{{/if}}
+</div>
+</template>
+<props>
+{
+  "heading":     { "type": "string",  "default": "Show more", "label": "Toggle heading" },
+  "openDefault": { "type": "boolean", "default": false,       "label": "Open on load" }
+}
+</props>
+<script>
+export default {
+  data() { return { open: false }; },
+  methods: { toggle() { this.set({ open: !this.data.open }); } },
+  onMount() {
+    this.set({ open: this.props.openDefault });
+    this.el.shadowRoot.addEventListener('click', (e) => {
+      if (e.target.dataset.action === 'toggle') this.toggle();
+    });
+  }
+};
+</script>
+<style>
+.dm-reveal .toggle { background: none; border: none; font-weight: 600; cursor: pointer; }
+.dm-reveal .body { margin-top: .5rem; padding-top: .5rem; border-top: 1px solid currentColor; }
+</style>
+`,
+
+    'testimonial-card': `
+<template>
+<figure class="dm-testimonial">
+  <blockquote class="quote">"{{quote}}"</blockquote>
+  <figcaption class="author">
+    {{#if avatar}}<img class="avatar" src="{{avatar}}" alt="">{{/if}}
+    <div><div class="name">{{author}}</div><div class="role">{{role}}</div></div>
+  </figcaption>
+</figure>
+</template>
+<props>
+{
+  "quote":  { "type": "string", "default": "", "label": "Quote" },
+  "author": { "type": "string", "default": "", "label": "Author name" },
+  "role":   { "type": "string", "default": "", "label": "Author role or company" },
+  "avatar": { "type": "string", "default": "", "label": "Avatar image URL" }
+}
+</props>
+<script>
+export default {};
+</script>
+<style>
+.dm-testimonial { margin: 0; padding: 1.25rem; border-radius: 8px; background: rgba(0,0,0,.04); }
+.dm-testimonial .quote { font-size: 1.05rem; font-style: italic; margin: 0 0 .75rem; }
+.dm-testimonial .author { display: flex; align-items: center; gap: .75rem; font-size: .85rem; }
+.dm-testimonial .avatar { width: 40px; height: 40px; border-radius: 50%; object-fit: cover; }
+.dm-testimonial .name { font-weight: 600; }
+.dm-testimonial .role { opacity: .7; }
+</style>
+`,
+
+    'countdown-timer': `
+<template>
+<div class="dm-countdown-c">
+  <div class="part"><span class="n">{{days}}</span><span class="l">days</span></div>
+  <div class="part"><span class="n">{{hours}}</span><span class="l">hrs</span></div>
+  <div class="part"><span class="n">{{minutes}}</span><span class="l">min</span></div>
+  <div class="part"><span class="n">{{seconds}}</span><span class="l">sec</span></div>
+</div>
+</template>
+<props>
+{
+  "target": { "type": "string", "default": "", "label": "Target date (ISO 8601)" }
+}
+</props>
+<script>
+export default {
+  data() { return { days: 0, hours: 0, minutes: 0, seconds: 0 }; },
+  _timer: null,
+  methods: {
+    tick() {
+      const t = new Date(this.props.target).getTime() - Date.now();
+      if (isNaN(t) || t <= 0) { this.set({ days: 0, hours: 0, minutes: 0, seconds: 0 }); return; }
+      this.set({
+        days:    Math.floor(t / 86400000),
+        hours:   Math.floor((t % 86400000) / 3600000),
+        minutes: Math.floor((t % 3600000) / 60000),
+        seconds: Math.floor((t % 60000) / 1000)
+      });
+    }
+  },
+  onMount()   { this.tick(); this._timer = setInterval(() => this.tick(), 1000); },
+  onUnmount() { if (this._timer) clearInterval(this._timer); }
+};
+</script>
+<style>
+.dm-countdown-c { display: flex; gap: 1rem; justify-content: center; }
+.dm-countdown-c .part { display: flex; flex-direction: column; align-items: center; }
+.dm-countdown-c .n { font-size: 1.8rem; font-weight: 700; }
+.dm-countdown-c .l { font-size: .7rem; text-transform: uppercase; opacity: .7; }
+</style>
+`
+};
+
+/**
+ * Seed starter components into content/components/.
+ * Never overwrites existing files — user customisations are preserved.
+ * All seeded components are marked `bundled: true` via their .meta.json.
+ */
+export async function seedDefaultComponents() {
+    await fs.mkdir(COMPONENTS_DIR, {recursive: true});
+    const seeded = [];
+    for (const [name, source] of Object.entries(SEED_COMPONENTS)) {
+        const fp = componentFilePath(name);
+        try { await fs.access(fp); }
+        catch {
+            await fs.writeFile(fp, source.trim() + '\n', 'utf8');
+            await fs.writeFile(componentMetaPath(name), JSON.stringify({bundled: true}, null, 2) + '\n', 'utf8');
+            seeded.push(name);
+        }
+    }
+    if (seeded.length) console.log(`[components] Seeded default components: ${seeded.join(', ')}`);
+}
+
+export { COMPONENTS_DIR, assertValidName, componentFilePath, componentMetaPath };
+
+// Allow this module to be executed directly for a quick self-test of assertValidName.
+if (import.meta.url === `file://${process.argv[1]}`) {
+    const cases = [
+        ['counter', true],
+        ['copy-button', true],
+        ['Counter', false],
+        ['1counter', false],
+        ['', false],
+        ['../etc/passwd', false]
+    ];
+    for (const [name, ok] of cases) {
+        try { assertValidName(name); console.log(ok ? '✓' : '✗', name, '→ valid'); }
+        catch { console.log(ok ? '✗' : '✓', name, '→ invalid'); }
+    }
+}