domma-cms 1.6.59 → 1.7.0

package/docs/plans/2026-03-05-custom-css-migrate-to-core.md

@@ -0,0 +1,352 @@
+# Custom CSS - Migrate to Core Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Move the Custom CSS plugin into core, storing CSS at `content/custom.css`, serving it as an inline `<style>` block, and editing it via a new tab in Site Settings.
+
+**Architecture:** The CSS file lives at `content/custom.css`. The renderer reads it at request time and injects it as an inline `<style>` block in `headInjectLate`. Two new routes on the settings router handle admin read/write. The admin UI is a new "Custom CSS" tab in settings.html with its own Save button (separate from the main Save, since it writes a file not JSON config). The plugin directory and plugins.json entry are then removed.
+
+**Tech Stack:** Fastify 5 ESM backend, Domma SPA admin, `fs/promises` for file I/O, `content/custom.css` as storage.
+
+**Reference files:** `server/routes/api/settings.js` (lines 1-59), `server/services/renderer.js` (lines 29-86), `admin/js/views/settings.js` (lines 1-117), `admin/js/templates/settings.html` (lines 1-287), `plugins/custom-css/plugin.js`.
+
+---
+
+### Task 1: Create content/custom.css
+
+**Files:**
+- Create: `content/custom.css`
+
+**Step 1: Create the empty file**
+
+```bash
+touch content/custom.css
+```
+
+**Step 2: Verify it exists**
+
+Run: `ls -la content/custom.css`
+
+Expected: file listed with 0 bytes.
+
+**Step 3: Commit**
+
+```bash
+git add content/custom.css
+git commit -m "feat: add content/custom.css for core custom CSS storage"
+```
+
+---
+
+### Task 2: Add custom-css routes to settings.js
+
+**Files:**
+- Modify: `server/routes/api/settings.js`
+
+**Step 1: Add fs import at the top**
+
+After the existing imports (after line 10), add:
+
+```js
+import fs from 'fs/promises';
+import path from 'path';
+import {fileURLToPath} from 'url';
+
+const __dirname_settings = path.dirname(fileURLToPath(import.meta.url));
+const CUSTOM_CSS_FILE = path.resolve(__dirname_settings, '../../../content/custom.css');
+const CUSTOM_CSS_MAX  = 100 * 1024; // 100 KB
+```
+
+**Step 2: Add the two new routes inside `settingsRoutes`, after the test-email handler**
+
+```js
+    // GET /api/settings/custom-css - return current CSS as JSON
+    fastify.get('/settings/custom-css', guard, async () => {
+        try {
+            const css = await fs.readFile(CUSTOM_CSS_FILE, 'utf8');
+            return { css };
+        } catch {
+            return { css: '' };
+        }
+    });
+
+    // PUT /api/settings/custom-css - save CSS to content/custom.css
+    fastify.put('/settings/custom-css', guard, async (request, reply) => {
+        const { css } = request.body || {};
+        if (typeof css !== 'string') {
+            return reply.status(400).send({ error: 'css must be a string.' });
+        }
+        if (Buffer.byteLength(css, 'utf8') > CUSTOM_CSS_MAX) {
+            return reply.status(400).send({ error: 'CSS exceeds the 100 KB limit.' });
+        }
+        await fs.writeFile(CUSTOM_CSS_FILE, css, 'utf8');
+        return { ok: true };
+    });
+```
+
+**Step 3: Verify the file imports without errors**
+
+Run: `node --input-type=module --eval "import('/home/darryl/src/js/domma-cms/server/routes/api/settings.js').then(()=>console.log('OK')).catch(e=>{console.error(e.message);process.exit(1);})" 2>&1`
+
+Expected: `OK`
+
+**Step 4: Commit**
+
+```bash
+git add server/routes/api/settings.js
+git commit -m "feat: add GET/PUT /api/settings/custom-css routes"
+```
+
+---
+
+### Task 3: Update renderer.js to inject inline custom CSS
+
+**Files:**
+- Modify: `server/services/renderer.js`
+
+**Step 1: Add fs import and CSS_FILE constant**
+
+After the existing imports (after line 10 `import {applyTransforms} from './hooks.js';`), add:
+
+```js
+import fs from 'fs/promises';
+
+const CUSTOM_CSS_PATH = new URL('../../../content/custom.css', import.meta.url).pathname;
+
+async function getCustomCss() {
+    try {
+        return await fs.readFile(CUSTOM_CSS_PATH, 'utf8');
+    } catch {
+        return '';
+    }
+}
+```
+
+**Step 2: Add `getCustomCss()` to the Promise.all in renderPage**
+
+Current line 30:
+```js
+    const [template, site, navigation, presets, injection] = await Promise.all([
+        getTemplate(),
+        Promise.resolve(getConfig('site')),
+        Promise.resolve(getConfig('navigation')),
+        Promise.resolve(getConfig('presets')),
+        getInjectionSnippets()
+    ]);
+```
+
+Replace with:
+```js
+    const [template, site, navigation, presets, injection, customCss] = await Promise.all([
+        getTemplate(),
+        Promise.resolve(getConfig('site')),
+        Promise.resolve(getConfig('navigation')),
+        Promise.resolve(getConfig('presets')),
+        getInjectionSnippets(),
+        getCustomCss()
+    ]);
+```
+
+**Step 3: Build the customCssTag variable and extend headInjectLate**
+
+After the `fontStyleTag` lines (after line 56), add:
+
+```js
+    const customCssTag = customCss.trim()
+        ? `<style>${customCss.replace(/<\/style>/gi, '<\\/style>')}</style>`
+        : '';
+```
+
+Then in the `vars` object, change `headInjectLate`:
+
+Current:
+```js
+        headInjectLate: injection.headLate,
+```
+
+Replace with:
+```js
+        headInjectLate: [injection.headLate, customCssTag].filter(Boolean).join('\n'),
+```
+
+**Step 4: Verify renderer imports without errors**
+
+Run: `node --input-type=module --eval "import('/home/darryl/src/js/domma-cms/server/services/renderer.js').then(()=>console.log('OK')).catch(e=>{console.error(e.message);process.exit(1);})" 2>&1`
+
+Expected: `OK`
+
+**Step 5: Verify inline style tag appears when CSS is non-empty**
+
+Write a test string to the file, curl the page, then clear it:
+
+```bash
+echo "body { outline: 2px solid red; }" > content/custom.css
+curl -s http://localhost:4096/ | grep -o '<style>body.*</style>'
+echo "" > content/custom.css
+```
+
+Expected: `<style>body { outline: 2px solid red; }</style>` (or similar match).
+
+**Step 6: Commit**
+
+```bash
+git add server/services/renderer.js
+git commit -m "feat: renderer injects content/custom.css as inline style block"
+```
+
+---
+
+### Task 4: Add Custom CSS tab to settings.html
+
+**Files:**
+- Modify: `admin/js/templates/settings.html`
+
+**Step 1: Add tab button after the Cookie Consent button**
+
+Current last tab button:
+```html
+    <button class="tab-item">Cookie Consent</button>
+```
+
+Add after it:
+```html
+    <button class="tab-item">Custom CSS</button>
+```
+
+**Step 2: Add the tab panel before the closing `</div></div>`**
+
+Add before the final `  </div>\n</div>`:
+
+```html
+    <!-- Custom CSS -->
+    <div class="tab-panel">
+      <div class="row mb-3">
+        <div class="col">
+          <p class="text-muted" style="font-size:.875rem;margin-bottom:1rem;">
+            CSS entered here is injected as an inline <code>&lt;style&gt;</code> block into the
+            <code>&lt;head&gt;</code> of every public page. Changes take effect immediately on save.
+          </p>
+          <textarea id="field-custom-css" class="form-input" style="font-family:monospace;min-height:420px;resize:vertical;" spellcheck="false" placeholder="/* Add your custom CSS here */"></textarea>
+        </div>
+      </div>
+      <div class="row">
+        <div class="col">
+          <button id="save-css-btn" class="btn btn-primary"><span data-icon="save"></span> Save CSS</button>
+        </div>
+      </div>
+    </div>
+```
+
+**Step 3: Commit**
+
+```bash
+git add admin/js/templates/settings.html
+git commit -m "feat: add Custom CSS tab to Site Settings template"
+```
+
+---
+
+### Task 5: Update settings.js to load/save custom CSS
+
+**Files:**
+- Modify: `admin/js/views/settings.js`
+
+**Step 1: Load CSS in onMount, after the Cookie Consent fields**
+
+After the last `$container.find('#field-cc-version')...` line, add:
+
+```js
+        // Custom CSS
+        try {
+            const { css } = await apiRequest('/settings/custom-css');
+            $container.find('#field-custom-css').val(css || '');
+        } catch {
+            // non-fatal - textarea stays empty
+        }
+```
+
+**Step 2: Add the Save CSS button handler, after the existing send-test-email handler**
+
+After the closing of the `#send-test-email-btn` handler (after line ~115), add:
+
+```js
+        // Save Custom CSS
+        $container.find('#save-css-btn').on('click', async () => {
+            const css = $container.find('#field-custom-css').val();
+            const $btn = $container.find('#save-css-btn');
+            $btn.prop('disabled', true);
+            try {
+                await apiRequest('/settings/custom-css', {
+                    method: 'PUT',
+                    body: JSON.stringify({ css })
+                });
+                E.toast('Custom CSS saved.', { type: 'success' });
+            } catch (err) {
+                E.toast(err.message || 'Failed to save CSS.', { type: 'error' });
+            } finally {
+                $btn.prop('disabled', false);
+            }
+        });
+```
+
+**Step 3: Verify JS syntax**
+
+Run: `node --check admin/js/views/settings.js && echo OK`
+
+Expected: `OK`
+
+**Step 4: Commit**
+
+```bash
+git add admin/js/views/settings.js
+git commit -m "feat: settings view loads and saves custom CSS tab"
+```
+
+---
+
+### Task 6: Migrate existing CSS data and remove plugin
+
+**Files:**
+- Delete: `plugins/custom-css/` (entire directory)
+- Modify: `config/plugins.json`
+
+**Step 1: Copy any existing CSS data to core location**
+
+```bash
+cp plugins/custom-css/data/custom.css content/custom.css 2>/dev/null || true
+```
+
+**Step 2: Remove plugin directory**
+
+```bash
+rm -rf plugins/custom-css
+```
+
+**Step 3: Remove entry from config/plugins.json**
+
+Remove the `"custom-css"` key. The resulting file should contain only: `example-analytics`, `form-builder`, `domma-effects`.
+
+**Step 4: Verify JSON is valid**
+
+Run: `node -e "JSON.parse(require('fs').readFileSync('config/plugins.json','utf8')); console.log('OK')"`
+
+Expected: `OK`
+
+**Step 5: Commit**
+
+```bash
+git add -A
+git commit -m "feat: remove custom-css plugin directory, migrate to core"
+```
+
+---
+
+## Verification
+
+1. **Inline style in page source**: Write some CSS to `content/custom.css`, then
+   `curl -s http://localhost:4096/ | grep '<style>'` - confirm the style block is present.
+2. **Empty file = no style tag**: Clear the file, re-curl, confirm no `<style>` tag appears.
+3. **Admin tab visible**: Open Site Settings in the admin - 7 tabs should be visible including "Custom CSS".
+4. **Save round-trip**: Enter CSS in the tab, click Save CSS, refresh the page - CSS should persist and appear in the public page source.
+5. **Plugin list**: Admin → Plugins - `custom-css` no longer appears.
+6. **Other plugins unaffected**: `domma-effects`, `form-builder`, `example-analytics` still load normally.