domma-cms 0.13.5 → 0.14.0

package/server/services/blocks.js

@@ -1,284 +1,387 @@
-/**
- * Blocks Service
- * CRUD operations and seeding for reusable HTML block templates in content/blocks/.
- * Never overwrites existing files during seeding — user customisations are preserved.
- */
-import fs from 'fs/promises';
-import path from 'path';
-import {fileURLToPath} from 'url';
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const BLOCKS_DIR = path.resolve(__dirname, '../../content/blocks');
-
-/**
- * Write a block file only if it does not already exist.
- *
- * @param {string} name    - Block name (without .html extension)
- * @param {string} content - HTML template content
- */
-async function seedBlock(name, content) {
-    const filePath = path.join(BLOCKS_DIR, `${name}.html`);
-    try {
-        await fs.access(filePath);
-        // File exists — leave it alone
-    } catch {
-        await fs.writeFile(filePath, content.trim() + '\n', 'utf8');
-    }
-}
-
-// ---------------------------------------------------------------------------
-// Default block templates
-// ---------------------------------------------------------------------------
-
-const BLOCKS = {
-
-    /**
-     * contact-card — for the Contacts form
-     * Fields: full_name, phone_number, email_address
-     */
-    'contact-card': `
-<div class="card mb-3">
-  <div class="card-body">
-    <div style="display:flex;justify-content:space-between;align-items:flex-start;gap:1rem;flex-wrap:wrap;">
-      <div>
-        <h4 style="margin:0 0 .5rem;font-size:1.05rem;">{{full_name}}</h4>
-        <div style="display:flex;flex-direction:column;gap:.3rem;font-size:.875rem;">
-          <span><strong>Email:</strong> {{email_address}}</span>
-          <span><strong>Phone:</strong> {{phone_number}}</span>
-        </div>
-      </div>
-      <small class="text-muted" style="white-space:nowrap;">{{_createdAt}}</small>
-    </div>
-  </div>
-</div>
-`,
-
-    /**
-     * enquiry-card — for the Enquiries form
-     * Fields: full_name, email, phone, subject, message
-     */
-    'enquiry-card': `
-<div class="card mb-3">
-  <div class="card-header" style="display:flex;justify-content:space-between;align-items:center;gap:.75rem;flex-wrap:wrap;">
-    <div>
-      <strong style="font-size:1rem;">{{subject}}</strong>
-      <span class="text-muted" style="font-size:.8rem;margin-left:.6rem;">from {{full_name}}</span>
-    </div>
-    <small class="text-muted">{{_createdAt}}</small>
-  </div>
-  <div class="card-body">
-    <p style="margin:0 0 1rem;line-height:1.65;">{{message}}</p>
-    <div style="display:flex;gap:1.5rem;font-size:.8rem;color:var(--dm-text-muted,#888);flex-wrap:wrap;">
-      <span><strong>Email:</strong> {{email}}</span>
-      <span><strong>Phone:</strong> {{phone}}</span>
-    </div>
-  </div>
-</div>
-`,
-
-    /**
-     * feedback-card — for the Feedback form
-     * Fields: name, email, rating, category, subject, message, recommend
-     */
-    'feedback-card': `
-<div class="card mb-3">
-  <div class="card-header" style="display:flex;justify-content:space-between;align-items:center;gap:.75rem;flex-wrap:wrap;">
-    <div style="display:flex;align-items:center;gap:.65rem;flex-wrap:wrap;">
-      <strong>{{subject}}</strong>
-      <span class="badge badge-secondary" style="text-transform:capitalize;">{{category}}</span>
-      <span class="badge badge-info" style="text-transform:capitalize;">{{rating}}</span>
-    </div>
-    <small class="text-muted">{{_createdAt}}</small>
-  </div>
-  <div class="card-body">
-    <p style="margin:0 0 1rem;line-height:1.65;">{{message}}</p>
-    <div style="display:flex;justify-content:space-between;align-items:center;flex-wrap:wrap;gap:.5rem;font-size:.8rem;color:var(--dm-text-muted,#888);">
-      <span>{{name}} &mdash; {{email}}</span>
-      <span>Would recommend: <strong>{{recommend}}</strong></span>
-    </div>
-  </div>
-</div>
-`,
-
-    /**
-     * note-card — for the Notes form
-     * Fields: title, content, category, tags
-     */
-    'note-card': `
-<div class="card mb-3">
-  <div class="card-header" style="display:flex;justify-content:space-between;align-items:center;gap:.75rem;flex-wrap:wrap;">
-    <div style="display:flex;align-items:center;gap:.6rem;flex-wrap:wrap;">
-      <strong style="font-size:1rem;">{{title}}</strong>
-      <span class="badge badge-secondary" style="text-transform:capitalize;">{{category}}</span>
-    </div>
-    <small class="text-muted">{{_createdAt}}</small>
-  </div>
-  <div class="card-body">
-    <p style="margin:0 0 .75rem;line-height:1.7;white-space:pre-line;">{{content}}</p>
-    <small class="text-muted">Tags: {{tags}}</small>
-  </div>
-</div>
-`,
-
-    /**
-     * todo-item — for the To-Do form
-     * Fields: title, description, status, priority, due_date, assigned_to
-     */
-    'todo-item': `
-<div class="card mb-2">
-  <div class="card-body" style="display:flex;align-items:flex-start;gap:1rem;flex-wrap:wrap;">
-    <div style="flex:1;min-width:0;">
-      <div style="display:flex;align-items:center;gap:.6rem;flex-wrap:wrap;margin-bottom:.4rem;">
-        <strong style="font-size:.975rem;">{{title}}</strong>
-        <span class="badge badge-warning" style="text-transform:capitalize;">{{priority}}</span>
-        <span class="badge badge-success" style="text-transform:capitalize;">{{status}}</span>
-      </div>
-      <p style="margin:0 0 .5rem;font-size:.875rem;line-height:1.55;color:var(--dm-text-muted,#888);">{{description}}</p>
-      <div style="display:flex;gap:1.5rem;font-size:.8rem;color:var(--dm-text-muted,#888);flex-wrap:wrap;">
-        <span><strong>Due:</strong> {{due_date}}</span>
-        <span><strong>Assigned to:</strong> {{assigned_to}}</span>
-      </div>
-    </div>
-  </div>
-</div>
-`,
-
-};
-
-// ---------------------------------------------------------------------------
-// Validation
-// ---------------------------------------------------------------------------
-
-/** Block names must be lowercase alphanumeric + hyphens, no path traversal. */
-const NAME_RE = /^[a-z0-9][a-z0-9-]*$/;
-
-function assertValidName(name) {
-    if (!NAME_RE.test(name)) {
-        const err = new Error('Invalid block name. Use lowercase letters, digits, and hyphens only.');
-        err.code = 'INVALID_NAME';
-        throw err;
-    }
-}
-
-function blockFilePath(name) {
-    return path.join(BLOCKS_DIR, `${name}.html`);
-}
-
-// ---------------------------------------------------------------------------
-// CRUD service functions
-// ---------------------------------------------------------------------------
-
-/**
- * List all blocks in the blocks directory.
- *
- * @returns {Promise<Array<{name: string, size: number, updatedAt: string|null}>>}
- */
-export async function listBlocks() {
-    await fs.mkdir(BLOCKS_DIR, {recursive: true});
-    const files = await fs.readdir(BLOCKS_DIR);
-    const blocks = [];
-    for (const file of files.filter(f => f.endsWith('.html'))) {
-        const name = file.slice(0, -5);
-        const fileStat = await fs.stat(path.join(BLOCKS_DIR, file)).catch(() => null);
-        let bundled = false;
-        try {
-            const meta = JSON.parse(await fs.readFile(path.join(BLOCKS_DIR, `${name}.meta.json`), 'utf8'));
-            bundled = !!meta.bundled;
-        } catch { /* no meta file */
-        }
-        blocks.push({
-            name,
-            size: fileStat?.size ?? 0,
-            updatedAt: fileStat?.mtime?.toISOString() ?? null,
-            bundled,
-        });
-    }
-    return blocks.sort((a, b) => a.name.localeCompare(b.name));
-}
-
-/**
- * Read a single block's content by name.
- *
- * @param {string} name - Block name (without .html extension)
- * @returns {Promise<{name: string, content: string}>}
- * @throws {Error} With code INVALID_NAME or ENOENT when not found
- */
-export async function getBlock(name) {
-    assertValidName(name);
-    try {
-        const content = await fs.readFile(blockFilePath(name), 'utf8');
-        let bundled = false;
-        try {
-            const meta = JSON.parse(await fs.readFile(path.join(BLOCKS_DIR, `${name}.meta.json`), 'utf8'));
-            bundled = !!meta.bundled;
-        } catch { /* no meta file */
-        }
-        return {name, content, bundled};
-    } catch (err) {
-        if (err.code === 'ENOENT') {
-            const notFound = new Error('Block not found');
-            notFound.code = 'ENOENT';
-            throw notFound;
-        }
-        throw err;
-    }
-}
-
-/**
- * Create or update a block file (upsert).
- *
- * @param {string} name    - Block name (without .html extension)
- * @param {string} content - HTML template content
- * @returns {Promise<{success: boolean, name: string}>}
- * @throws {Error} With code INVALID_NAME on bad name
- */
-export async function saveBlock(name, content, {bundled} = {}) {
-    assertValidName(name);
-    await fs.mkdir(BLOCKS_DIR, {recursive: true});
-    await fs.writeFile(blockFilePath(name), content, 'utf8');
-    const metaPath = path.join(BLOCKS_DIR, `${name}.meta.json`);
-    if (bundled) {
-        await fs.writeFile(metaPath, JSON.stringify({bundled: true}, null, 2) + '\n', 'utf8');
-    } else {
-        await fs.unlink(metaPath).catch(() => {
-        });
-    }
-    return {success: true, name};
-}
-
-/**
- * Delete a block file.
- *
- * @param {string} name - Block name (without .html extension)
- * @returns {Promise<void>}
- * @throws {Error} With code INVALID_NAME or ENOENT when not found
- */
-export async function deleteBlock(name) {
-    assertValidName(name);
-    try {
-        await fs.unlink(blockFilePath(name));
-    } catch (err) {
-        if (err.code === 'ENOENT') {
-            const notFound = new Error('Block not found');
-            notFound.code = 'ENOENT';
-            throw notFound;
-        }
-        throw err;
-    }
-}
-
-// ---------------------------------------------------------------------------
-// Public API
-// ---------------------------------------------------------------------------
-
-/**
- * Seed all default block templates into content/blocks/.
- * Skips any file that already exists to preserve user customisations.
- */
-export async function seedDefaultBlocks() {
-    for (const [name, content] of Object.entries(BLOCKS)) {
-        await seedBlock(name, content);
-    }
-    const names = Object.keys(BLOCKS).join(', ');
-    console.log(`[blocks] Seeded default blocks: ${names}`);
-}
+/**
+ * Blocks Service
+ * CRUD operations and seeding for reusable HTML block templates in content/blocks/.
+ * Never overwrites existing files during seeding — user customisations are preserved.
+ */
+import fs from 'fs/promises';
+import path from 'path';
+import {fileURLToPath} from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const BLOCKS_DIR = path.resolve(__dirname, '../../content/blocks');
+
+/**
+ * Write a block file only if it does not already exist.
+ *
+ * @param {string} name    - Block name (without .html extension)
+ * @param {string} content - HTML template content
+ */
+async function seedBlock(name, content) {
+    const filePath = path.join(BLOCKS_DIR, `${name}.html`);
+    try {
+        await fs.access(filePath);
+        // File exists — leave it alone
+    } catch {
+        await fs.writeFile(filePath, content.trim() + '\n', 'utf8');
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Default block templates
+// ---------------------------------------------------------------------------
+
+const BLOCKS = {
+
+    /**
+     * contact-info — standalone contact details panel for landing pages.
+     * Fields: heading, intro, phone, phoneHref, email, address, hours,
+     *         facebook, facebookLabel, instagram, instagramLabel,
+     *         website, websiteLabel, footnote
+     */
+    'contact-info': `
+<div class="contact-info-card">
+<h3 class="contact-info-heading">{{heading}}</h3>
+<p class="contact-info-intro">{{intro}}</p>
+<ul class="contact-info-list">
+<li class="contact-info-row" data-field="phone">
+<span class="contact-info-icon" data-icon="phone" aria-hidden="true"></span>
+<div class="contact-info-body">
+<span class="contact-info-label">Phone</span>
+<a class="contact-info-value" href="tel:{{phoneHref}}">{{phone}}</a>
+</div>
+</li>
+<li class="contact-info-row" data-field="email">
+<span class="contact-info-icon" data-icon="mail" aria-hidden="true"></span>
+<div class="contact-info-body">
+<span class="contact-info-label">Email</span>
+<a class="contact-info-value" href="mailto:{{email}}">{{email}}</a>
+</div>
+</li>
+<li class="contact-info-row" data-field="address">
+<span class="contact-info-icon" data-icon="map-pin" aria-hidden="true"></span>
+<div class="contact-info-body">
+<span class="contact-info-label">Based in</span>
+<span class="contact-info-value">{{address}}</span>
+</div>
+</li>
+<li class="contact-info-row" data-field="hours">
+<span class="contact-info-icon" data-icon="clock" aria-hidden="true"></span>
+<div class="contact-info-body">
+<span class="contact-info-label">Hours</span>
+<span class="contact-info-value">{{hours}}</span>
+</div>
+</li>
+<li class="contact-info-row" data-field="facebook">
+<span class="contact-info-icon" data-icon="facebook" aria-hidden="true"></span>
+<div class="contact-info-body">
+<span class="contact-info-label">Facebook</span>
+<a class="contact-info-value" href="{{facebook}}" target="_blank" rel="noopener noreferrer">{{facebookLabel}}</a>
+</div>
+</li>
+<li class="contact-info-row" data-field="instagram">
+<span class="contact-info-icon" data-icon="instagram" aria-hidden="true"></span>
+<div class="contact-info-body">
+<span class="contact-info-label">Instagram</span>
+<a class="contact-info-value" href="{{instagram}}" target="_blank" rel="noopener noreferrer">{{instagramLabel}}</a>
+</div>
+</li>
+<li class="contact-info-row" data-field="website">
+<span class="contact-info-icon" data-icon="globe" aria-hidden="true"></span>
+<div class="contact-info-body">
+<span class="contact-info-label">Website</span>
+<a class="contact-info-value" href="{{website}}" target="_blank" rel="noopener noreferrer">{{websiteLabel}}</a>
+</div>
+</li>
+</ul>
+<p class="contact-info-footnote">{{footnote}}</p>
+</div>
+`,
+
+    /**
+     * contact-card — for the Contacts form
+     * Fields: full_name, phone_number, email_address
+     */
+    'contact-card': `
+<div class="card mb-3">
+  <div class="card-body">
+    <div style="display:flex;justify-content:space-between;align-items:flex-start;gap:1rem;flex-wrap:wrap;">
+      <div>
+        <h4 style="margin:0 0 .5rem;font-size:1.05rem;">{{full_name}}</h4>
+        <div style="display:flex;flex-direction:column;gap:.3rem;font-size:.875rem;">
+          <span><strong>Email:</strong> {{email_address}}</span>
+          <span><strong>Phone:</strong> {{phone_number}}</span>
+        </div>
+      </div>
+      <small class="text-muted" style="white-space:nowrap;">{{_createdAt}}</small>
+    </div>
+  </div>
+</div>
+`,
+
+    /**
+     * enquiry-card — for the Enquiries form
+     * Fields: full_name, email, phone, subject, message
+     */
+    'enquiry-card': `
+<div class="card mb-3">
+  <div class="card-header" style="display:flex;justify-content:space-between;align-items:center;gap:.75rem;flex-wrap:wrap;">
+    <div>
+      <strong style="font-size:1rem;">{{subject}}</strong>
+      <span class="text-muted" style="font-size:.8rem;margin-left:.6rem;">from {{full_name}}</span>
+    </div>
+    <small class="text-muted">{{_createdAt}}</small>
+  </div>
+  <div class="card-body">
+    <p style="margin:0 0 1rem;line-height:1.65;">{{message}}</p>
+    <div style="display:flex;gap:1.5rem;font-size:.8rem;color:var(--dm-text-muted,#888);flex-wrap:wrap;">
+      <span><strong>Email:</strong> {{email}}</span>
+      <span><strong>Phone:</strong> {{phone}}</span>
+    </div>
+  </div>
+</div>
+`,
+
+    /**
+     * feedback-card — for the Feedback form
+     * Fields: name, email, rating, category, subject, message, recommend
+     */
+    'feedback-card': `
+<div class="card mb-3">
+  <div class="card-header" style="display:flex;justify-content:space-between;align-items:center;gap:.75rem;flex-wrap:wrap;">
+    <div style="display:flex;align-items:center;gap:.65rem;flex-wrap:wrap;">
+      <strong>{{subject}}</strong>
+      <span class="badge badge-secondary" style="text-transform:capitalize;">{{category}}</span>
+      <span class="badge badge-info" style="text-transform:capitalize;">{{rating}}</span>
+    </div>
+    <small class="text-muted">{{_createdAt}}</small>
+  </div>
+  <div class="card-body">
+    <p style="margin:0 0 1rem;line-height:1.65;">{{message}}</p>
+    <div style="display:flex;justify-content:space-between;align-items:center;flex-wrap:wrap;gap:.5rem;font-size:.8rem;color:var(--dm-text-muted,#888);">
+      <span>{{name}} &mdash; {{email}}</span>
+      <span>Would recommend: <strong>{{recommend}}</strong></span>
+    </div>
+  </div>
+</div>
+`,
+
+    /**
+     * note-card — for the Notes form
+     * Fields: title, content, category, tags
+     */
+    'note-card': `
+<div class="card mb-3">
+  <div class="card-header" style="display:flex;justify-content:space-between;align-items:center;gap:.75rem;flex-wrap:wrap;">
+    <div style="display:flex;align-items:center;gap:.6rem;flex-wrap:wrap;">
+      <strong style="font-size:1rem;">{{title}}</strong>
+      <span class="badge badge-secondary" style="text-transform:capitalize;">{{category}}</span>
+    </div>
+    <small class="text-muted">{{_createdAt}}</small>
+  </div>
+  <div class="card-body">
+    <p style="margin:0 0 .75rem;line-height:1.7;white-space:pre-line;">{{content}}</p>
+    <small class="text-muted">Tags: {{tags}}</small>
+  </div>
+</div>
+`,
+
+    /**
+     * todo-item — for the To-Do form
+     * Fields: title, description, status, priority, due_date, assigned_to
+     */
+    'todo-item': `
+<div class="card mb-2">
+  <div class="card-body" style="display:flex;align-items:flex-start;gap:1rem;flex-wrap:wrap;">
+    <div style="flex:1;min-width:0;">
+      <div style="display:flex;align-items:center;gap:.6rem;flex-wrap:wrap;margin-bottom:.4rem;">
+        <strong style="font-size:.975rem;">{{title}}</strong>
+        <span class="badge badge-warning" style="text-transform:capitalize;">{{priority}}</span>
+        <span class="badge badge-success" style="text-transform:capitalize;">{{status}}</span>
+      </div>
+      <p style="margin:0 0 .5rem;font-size:.875rem;line-height:1.55;color:var(--dm-text-muted,#888);">{{description}}</p>
+      <div style="display:flex;gap:1.5rem;font-size:.8rem;color:var(--dm-text-muted,#888);flex-wrap:wrap;">
+        <span><strong>Due:</strong> {{due_date}}</span>
+        <span><strong>Assigned to:</strong> {{assigned_to}}</span>
+      </div>
+    </div>
+  </div>
+</div>
+`,
+
+};
+
+// ---------------------------------------------------------------------------
+// Validation
+// ---------------------------------------------------------------------------
+
+/** Block names must be lowercase alphanumeric + hyphens, no path traversal. */
+const NAME_RE = /^[a-z0-9][a-z0-9-]*$/;
+
+function assertValidName(name) {
+    if (!NAME_RE.test(name)) {
+        const err = new Error('Invalid block name. Use lowercase letters, digits, and hyphens only.');
+        err.code = 'INVALID_NAME';
+        throw err;
+    }
+}
+
+function blockFilePath(name) {
+    return path.join(BLOCKS_DIR, `${name}.html`);
+}
+
+function blockCssPath(name) {
+    return path.join(BLOCKS_DIR, `${name}.css`);
+}
+
+function blockMetaPath(name) {
+    return path.join(BLOCKS_DIR, `${name}.meta.json`);
+}
+
+/** Per-block CSS size cap — matches the 100 KB site-wide cap, scaled down. */
+const MAX_CSS_SIZE = 50 * 1024;
+
+// ---------------------------------------------------------------------------
+// CRUD service functions
+// ---------------------------------------------------------------------------
+
+/**
+ * List all blocks in the blocks directory.
+ *
+ * @returns {Promise<Array<{name: string, size: number, updatedAt: string|null}>>}
+ */
+export async function listBlocks() {
+    await fs.mkdir(BLOCKS_DIR, {recursive: true});
+    const files = await fs.readdir(BLOCKS_DIR);
+    const blocks = [];
+    for (const file of files.filter(f => f.endsWith('.html'))) {
+        const name = file.slice(0, -5);
+        const fileStat = await fs.stat(path.join(BLOCKS_DIR, file)).catch(() => null);
+        let bundled = false;
+        try {
+            const meta = JSON.parse(await fs.readFile(path.join(BLOCKS_DIR, `${name}.meta.json`), 'utf8'));
+            bundled = !!meta.bundled;
+        } catch { /* no meta file */
+        }
+        blocks.push({
+            name,
+            size: fileStat?.size ?? 0,
+            updatedAt: fileStat?.mtime?.toISOString() ?? null,
+            bundled,
+        });
+    }
+    return blocks.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/**
+ * Read a single block's content by name.
+ *
+ * @param {string} name - Block name (without .html extension)
+ * @returns {Promise<{name: string, content: string, css: string, bundled: boolean}>}
+ * @throws {Error} With code INVALID_NAME or ENOENT when not found
+ */
+export async function getBlock(name) {
+    assertValidName(name);
+    try {
+        const content = await fs.readFile(blockFilePath(name), 'utf8');
+        let bundled = false;
+        try {
+            const meta = JSON.parse(await fs.readFile(blockMetaPath(name), 'utf8'));
+            bundled = !!meta.bundled;
+        } catch { /* no meta file */
+        }
+        let css = '';
+        try {
+            css = await fs.readFile(blockCssPath(name), 'utf8');
+        } catch { /* no CSS file — treat as empty */
+        }
+        return {name, content, css, bundled};
+    } catch (err) {
+        if (err.code === 'ENOENT') {
+            const notFound = new Error('Block not found');
+            notFound.code = 'ENOENT';
+            throw notFound;
+        }
+        throw err;
+    }
+}
+
+/**
+ * Create or update a block file (upsert).
+ *
+ * @param {string} name    - Block name (without .html extension)
+ * @param {string} content - HTML template content
+ * @param {object} [opts]
+ * @param {boolean} [opts.bundled] - Include in fresh-install seed list
+ * @param {string}  [opts.css]     - Companion CSS body; empty string removes the file
+ * @returns {Promise<{success: boolean, name: string}>}
+ * @throws {Error} With code INVALID_NAME on bad name, or CSS_TOO_LARGE when CSS exceeds cap
+ */
+export async function saveBlock(name, content, {bundled, css} = {}) {
+    assertValidName(name);
+    if (typeof css === 'string' && css.length > MAX_CSS_SIZE) {
+        const err = new Error(`CSS exceeds ${MAX_CSS_SIZE} byte limit`);
+        err.code = 'CSS_TOO_LARGE';
+        throw err;
+    }
+    await fs.mkdir(BLOCKS_DIR, {recursive: true});
+    await fs.writeFile(blockFilePath(name), content, 'utf8');
+    const metaPath = blockMetaPath(name);
+    if (bundled) {
+        await fs.writeFile(metaPath, JSON.stringify({bundled: true}, null, 2) + '\n', 'utf8');
+    } else {
+        await fs.unlink(metaPath).catch(() => {
+        });
+    }
+    // CSS is optional — only touch the file when the caller passed the field explicitly.
+    if (typeof css === 'string') {
+        if (css.trim().length > 0) {
+            await fs.writeFile(blockCssPath(name), css, 'utf8');
+        } else {
+            await fs.unlink(blockCssPath(name)).catch(() => {
+            });
+        }
+    }
+    return {success: true, name};
+}
+
+/**
+ * Delete a block and its companion files (.css, .meta.json).
+ * Missing companions are ignored; only the primary .html file triggers ENOENT.
+ *
+ * @param {string} name - Block name (without .html extension)
+ * @returns {Promise<void>}
+ * @throws {Error} With code INVALID_NAME or ENOENT when the block is not found
+ */
+export async function deleteBlock(name) {
+    assertValidName(name);
+    try {
+        await fs.unlink(blockFilePath(name));
+    } catch (err) {
+        if (err.code === 'ENOENT') {
+            const notFound = new Error('Block not found');
+            notFound.code = 'ENOENT';
+            throw notFound;
+        }
+        throw err;
+    }
+    await fs.unlink(blockCssPath(name)).catch(() => {
+    });
+    await fs.unlink(blockMetaPath(name)).catch(() => {
+    });
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Seed all default block templates into content/blocks/.
+ * Skips any file that already exists to preserve user customisations.
+ */
+export async function seedDefaultBlocks() {
+    for (const [name, content] of Object.entries(BLOCKS)) {
+        await seedBlock(name, content);
+    }
+    const names = Object.keys(BLOCKS).join(', ');
+    console.log(`[blocks] Seeded default blocks: ${names}`);
+}