domma-cms 1.6.59 → 1.7.0

package/docs/plans/2026-02-28-reset-seed-fresh-commands.md

@@ -0,0 +1,520 @@
+# Reset, Seed & Fresh Commands - Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Add three npm scripts - `npm run reset` (full factory reset), `npm run seed` (demo content), and `npm run fresh` (reset → setup → seed in one go) - that let an end user get a working CMS in under two minutes.
+
+**Architecture:** Three standalone ESM scripts in `scripts/`. Each operates directly on files (no server imports). `fresh.js` chains the other three scripts using `node:child_process` `spawnSync` with `stdio: 'inherit'` so all interactive prompts work through. `seed.js` writes markdown files directly as template strings (no gray-matter dependency needed - format is straightforward YAML frontmatter + markdown body).
+
+**Tech Stack:** `node:fs/promises`, `node:readline/promises`, `node:child_process`, `node:path` - zero new dependencies.
+
+---
+
+### Task 1: `scripts/reset.js` - Full Factory Reset
+
+**Files:**
+- Create: `scripts/reset.js`
+- Modify: `package.json`
+
+Wipes all user-created data and resets config to factory defaults. Requires typing `yes` to confirm - protects against accidental runs.
+
+**What it deletes/resets:**
+- `content/users/*.json` - all user accounts
+- `content/pages/**/*.md` - all pages (recursive)
+- `content/media/*` - all uploaded files
+- `config/site.json` - reset to defaults
+- `config/navigation.json` - reset to defaults
+- `.env` - JWT_SECRET reset to placeholder (so `npm run setup` will regenerate it)
+
+**Step 1: Create `scripts/reset.js`**
+
+```javascript
+#!/usr/bin/env node
+/**
+ * Domma CMS - Factory Reset
+ * Wipes all content, users, and resets config to defaults.
+ * Run: npm run reset
+ */
+import { createInterface }                          from 'node:readline/promises';
+import { readFile, writeFile, readdir, rm, mkdir }  from 'node:fs/promises';
+import { existsSync }                               from 'node:fs';
+import path                                         from 'node:path';
+import { fileURLToPath }                            from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const ROOT      = path.resolve(__dirname, '..');
+
+const USERS_DIR  = path.join(ROOT, 'content', 'users');
+const PAGES_DIR  = path.join(ROOT, 'content', 'pages');
+const MEDIA_DIR  = path.join(ROOT, 'content', 'media');
+const SITE_CFG   = path.join(ROOT, 'config', 'site.json');
+const NAV_CFG    = path.join(ROOT, 'config', 'navigation.json');
+const ENV_FILE   = path.join(ROOT, '.env');
+
+const DEFAULT_SITE = {
+    title:   'My Site',
+    tagline: 'Powered by Domma CMS',
+    theme:   'charcoal-dark',
+    seo: {
+        defaultTitle:       'My Site',
+        titleSeparator:     ' | ',
+        defaultDescription: 'A site built with Domma CMS'
+    },
+    footer: {
+        copyright: `© ${new Date().getFullYear()} My Site. All rights reserved.`,
+        links: [
+            { text: 'Privacy Policy', url: '/privacy' },
+            { text: 'Contact',        url: '/contact'  }
+        ]
+    }
+};
+
+const DEFAULT_NAV = {
+    brand: { text: 'My Site', logo: null, url: '/' },
+    items: [
+        { text: 'Home',    url: '/',        icon: 'home' },
+        { text: 'About',   url: '/about',   icon: 'info' },
+        { text: 'Contact', url: '/contact', icon: 'mail' }
+    ],
+    variant:  'dark',
+    position: 'sticky'
+};
+
+// ---------------------------------------------------------------------------
+
+async function deleteDir(dir) {
+    try {
+        await rm(dir, { recursive: true, force: true });
+        await mkdir(dir, { recursive: true });
+    } catch { /* dir may not exist */ }
+}
+
+async function resetEnv() {
+    if (!existsSync(ENV_FILE)) return;
+    const lines = (await readFile(ENV_FILE, 'utf8')).split('\n');
+    const updated = lines.map(l => {
+        if (l.startsWith('JWT_SECRET=')) {
+            return 'JWT_SECRET=change-me-to-a-64-char-random-string-before-deploying-to-production';
+        }
+        return l;
+    });
+    await writeFile(ENV_FILE, updated.join('\n'), 'utf8');
+}
+
+// ---------------------------------------------------------------------------
+
+console.log('');
+console.log('  ┌──────────────────────────────────┐');
+console.log('  │   Domma CMS - Factory Reset      │');
+console.log('  └──────────────────────────────────┘');
+console.log('');
+console.log('  This will permanently delete:');
+console.log('    • All user accounts  (content/users/)');
+console.log('    • All pages          (content/pages/)');
+console.log('    • All media uploads  (content/media/)');
+console.log('    • config/site.json and config/navigation.json');
+console.log('    • JWT_SECRET in .env');
+console.log('');
+
+const rl = createInterface({ input: process.stdin, output: process.stdout });
+const answer = (await rl.question('  Type "yes" to confirm: ')).trim();
+rl.close();
+
+if (answer !== 'yes') {
+    console.log('\n  Reset cancelled.\n');
+    process.exit(0);
+}
+
+console.log('');
+process.stdout.write('  Deleting users…');
+await deleteDir(USERS_DIR);
+console.log(' done.');
+
+process.stdout.write('  Deleting pages…');
+await deleteDir(PAGES_DIR);
+console.log(' done.');
+
+process.stdout.write('  Deleting media…');
+await deleteDir(MEDIA_DIR);
+console.log(' done.');
+
+process.stdout.write('  Resetting config/site.json…');
+await writeFile(SITE_CFG, JSON.stringify(DEFAULT_SITE, null, 4) + '\n', 'utf8');
+console.log(' done.');
+
+process.stdout.write('  Resetting config/navigation.json…');
+await writeFile(NAV_CFG, JSON.stringify(DEFAULT_NAV, null, 4) + '\n', 'utf8');
+console.log(' done.');
+
+process.stdout.write('  Resetting JWT_SECRET in .env…');
+await resetEnv();
+console.log(' done.');
+
+console.log('');
+console.log('  ✓ Factory reset complete.');
+console.log('  Run `npm run setup` to configure a new admin account.');
+console.log('');
+```
+
+**Step 2: Add to `package.json` scripts**
+
+```json
+"reset": "node scripts/reset.js"
+```
+
+**Step 3: Verify**
+
+```bash
+node --check scripts/reset.js
+```
+Expected: no output (syntax OK).
+
+---
+
+### Task 2: `scripts/seed.js` - Demo Content
+
+**Files:**
+- Create: `scripts/seed.js`
+- Modify: `package.json`
+
+Writes five sample pages and updates navigation. Safe to run on a fresh install or alongside existing content (overwrites pages at the same paths). Does **not** touch users or `.env`.
+
+**Pages created:**
+| URL | File |
+|-----|------|
+| `/` | `content/pages/index.md` |
+| `/about` | `content/pages/about.md` |
+| `/contact` | `content/pages/contact.md` |
+| `/blog` | `content/pages/blog/index.md` |
+| `/blog/hello-world` | `content/pages/blog/hello-world.md` |
+
+**Step 1: Create `scripts/seed.js`**
+
+```javascript
+#!/usr/bin/env node
+/**
+ * Domma CMS - Seed Demo Content
+ * Creates sample pages and updates navigation.
+ * Safe to run multiple times - overwrites seed paths only.
+ * Run: npm run seed
+ */
+import { writeFile, mkdir } from 'node:fs/promises';
+import path                 from 'node:path';
+import { fileURLToPath }    from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const ROOT      = path.resolve(__dirname, '..');
+
+const PAGES_DIR = path.join(ROOT, 'content', 'pages');
+const NAV_CFG   = path.join(ROOT, 'config', 'navigation.json');
+
+const now = new Date().toISOString();
+
+// ---------------------------------------------------------------------------
+// Page definitions
+// ---------------------------------------------------------------------------
+
+const pages = [
+    {
+        file: 'index.md',
+        frontmatter: {
+            title: 'Welcome', slug: 'index',
+            description: 'Your new website, powered by Domma CMS',
+            layout: 'default', status: 'published',
+            sortOrder: 1, showInNav: false, sidebar: false,
+            seo: { title: 'Welcome', description: 'Your new website, powered by Domma CMS' },
+            createdAt: now, updatedAt: now
+        },
+        body: `# Welcome
+
+This is your new website, powered by **Domma CMS**.
+
+Edit this page from the [admin panel](/admin/), or modify \`content/pages/index.md\` directly.
+
+## What you can do
+
+- **Write pages** - create and publish content in Markdown
+- **Manage navigation** - build your site's menu from the admin panel
+- **Upload media** - attach images and files to your pages
+- **Choose a theme** - pick from 16 built-in colour schemes
+
+[Sign in to the admin panel →](/admin/)
+`
+    },
+    {
+        file: 'about.md',
+        frontmatter: {
+            title: 'About', slug: 'about',
+            description: 'Learn more about us',
+            layout: 'default', status: 'published',
+            sortOrder: 2, showInNav: true, sidebar: false,
+            seo: { title: 'About', description: 'Learn more about us' },
+            createdAt: now, updatedAt: now
+        },
+        body: `# About
+
+This is the About page - tell your visitors who you are, what you do, and why it matters.
+
+## Our story
+
+Replace this content with your own. You can edit it from the [admin panel](/admin/) at any time.
+
+## What we do
+
+Add your services, mission statement, or team information here.
+`
+    },
+    {
+        file: 'contact.md',
+        frontmatter: {
+            title: 'Contact', slug: 'contact',
+            description: 'Get in touch',
+            layout: 'default', status: 'published',
+            sortOrder: 4, showInNav: true, sidebar: false,
+            seo: { title: 'Contact', description: 'Get in touch with us' },
+            createdAt: now, updatedAt: now
+        },
+        body: `# Contact
+
+Get in touch - we'd love to hear from you.
+
+## How to reach us
+
+Replace this with your own contact details, a contact form, or whatever works best for your site.
+
+You can edit this page from the [admin panel](/admin/).
+`
+    },
+    {
+        file: path.join('blog', 'index.md'),
+        frontmatter: {
+            title: 'Blog', slug: 'blog',
+            description: 'News, updates and articles',
+            layout: 'default', status: 'published',
+            sortOrder: 3, showInNav: true, sidebar: false,
+            seo: { title: 'Blog', description: 'News, updates and articles' },
+            createdAt: now, updatedAt: now
+        },
+        body: `# Blog
+
+Welcome to the blog. Read on for articles, updates and news.
+
+---
+
+- [Hello, World!](/blog/hello-world) - Your first post
+`
+    },
+    {
+        file: path.join('blog', 'hello-world.md'),
+        frontmatter: {
+            title: 'Hello, World!', slug: 'hello-world',
+            description: 'The first post on this site',
+            layout: 'default', status: 'published',
+            sortOrder: 1, showInNav: false, sidebar: false,
+            seo: { title: 'Hello, World!', description: 'The first post on this site' },
+            createdAt: now, updatedAt: now
+        },
+        body: `# Hello, World!
+
+Welcome to your first blog post, created by the Domma CMS seed script.
+
+Edit or delete this from the [admin panel](/admin/), then start writing your own content.
+
+## Writing in Markdown
+
+Domma CMS uses **Markdown** for all page content:
+
+- **Bold** with \`**double asterisks**\`
+- *Italic* with \`*single asterisks*\`
+- \`Inline code\` with backticks
+- [Links](https://example.com) with \`[text](url)\`
+
+> Blockquotes with \`>\`
+
+\`\`\`
+Code blocks with triple backticks
+\`\`\`
+
+Happy writing!
+`
+    }
+];
+
+// ---------------------------------------------------------------------------
+// Seed navigation
+// ---------------------------------------------------------------------------
+
+const seedNav = {
+    brand: { text: 'My Site', logo: null, url: '/' },
+    items: [
+        { text: 'Home',    url: '/',        icon: 'home'      },
+        { text: 'About',   url: '/about',   icon: 'info'      },
+        { text: 'Blog',    url: '/blog',    icon: 'book-open' },
+        { text: 'Contact', url: '/contact', icon: 'mail'      }
+    ],
+    variant: 'dark',
+    position: 'sticky'
+};
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Serialise frontmatter + body to a markdown file string.
+ * Uses the same YAML-frontmatter format gray-matter produces.
+ *
+ * @param {object} fm
+ * @param {string} body
+ * @returns {string}
+ */
+function toMarkdown(fm, body) {
+    const yaml = Object.entries(fm).map(([k, v]) => {
+        if (v !== null && typeof v === 'object' && !Array.isArray(v)) {
+            const nested = Object.entries(v)
+                .map(([nk, nv]) => `  ${nk}: ${JSON.stringify(nv)}`)
+                .join('\n');
+            return `${k}:\n${nested}`;
+        }
+        return `${k}: ${JSON.stringify(v)}`;
+    }).join('\n');
+    return `---\n${yaml}\n---\n\n${body}`;
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+console.log('');
+console.log('  ┌──────────────────────────────────┐');
+console.log('  │   Domma CMS - Seed Demo Content  │');
+console.log('  └──────────────────────────────────┘');
+console.log('');
+
+for (const page of pages) {
+    const filePath = path.join(PAGES_DIR, page.file);
+    await mkdir(path.dirname(filePath), { recursive: true });
+    await writeFile(filePath, toMarkdown(page.frontmatter, page.body), 'utf8');
+    console.log(`  ✓ Created /${page.file.replace(/\\/g, '/').replace('index.md', '').replace('.md', '') || ''}`);
+}
+
+process.stdout.write('  Updating navigation…');
+await writeFile(NAV_CFG, JSON.stringify(seedNav, null, 4) + '\n', 'utf8');
+console.log(' done.');
+
+console.log('');
+console.log('  ✓ Seed complete - 5 pages created, navigation updated.');
+console.log('  Visit your site at http://localhost:4096/');
+console.log('');
+```
+
+**Step 2: Add to `package.json` scripts**
+
+```json
+"seed": "node scripts/seed.js"
+```
+
+**Step 3: Verify**
+
+```bash
+node --check scripts/seed.js
+```
+Expected: no output (syntax OK).
+
+---
+
+### Task 3: `scripts/fresh.js` - Reset → Setup → Seed
+
+**Files:**
+- Create: `scripts/fresh.js`
+- Modify: `package.json`
+
+Chains all three scripts in order with full stdio inheritance so interactive prompts (reset confirmation, setup questions) pass through directly to the terminal. Each sub-script runs in the same working directory with `cwd: ROOT`.
+
+**Step 1: Create `scripts/fresh.js`**
+
+```javascript
+#!/usr/bin/env node
+/**
+ * Domma CMS - Fresh Install
+ * Chains: reset → setup → seed
+ * Gives you a fully configured CMS with demo content in one command.
+ * Run: npm run fresh
+ */
+import { spawnSync }     from 'node:child_process';
+import path              from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const ROOT      = path.resolve(__dirname, '..');
+
+function run(script) {
+    const result = spawnSync(process.execPath, [path.join('scripts', script)], {
+        cwd:   ROOT,
+        stdio: 'inherit'
+    });
+    if (result.status !== 0) {
+        process.exit(result.status ?? 1);
+    }
+}
+
+console.log('');
+console.log('  ╔══════════════════════════════════════╗');
+console.log('  ║   Domma CMS - Fresh Install          ║');
+console.log('  ║   reset → setup → seed               ║');
+console.log('  ╚══════════════════════════════════════╝');
+
+run('reset.js');
+run('setup.js');
+run('seed.js');
+
+console.log('');
+console.log('  ═══════════════════════════════════════════');
+console.log('  Fresh install complete!  Start the server:');
+console.log('  npm start');
+console.log('  ═══════════════════════════════════════════');
+console.log('');
+```
+
+**Step 2: Add to `package.json` scripts**
+
+```json
+"fresh": "node scripts/fresh.js"
+```
+
+**Step 3: Verify all three scripts**
+
+```bash
+node --check scripts/reset.js && node --check scripts/seed.js && node --check scripts/fresh.js && echo "ALL OK"
+```
+Expected: `ALL OK`
+
+---
+
+### Task 4: Final `package.json` - confirm all four scripts together
+
+The scripts block should read:
+
+```json
+"scripts": {
+    "start":       "node server/server.js",
+    "dev":         "node --watch server/server.js",
+    "setup":       "node scripts/setup.js",
+    "reset":       "node scripts/reset.js",
+    "seed":        "node scripts/seed.js",
+    "fresh":       "node scripts/fresh.js",
+    "copy-domma":  "node scripts/copy-domma.js"
+}
+```
+
+---
+
+### Verification Checklist
+
+1. `node --check scripts/reset.js` → no errors
+2. `node --check scripts/seed.js` → no errors
+3. `node --check scripts/fresh.js` → no errors
+4. `npm run seed` on a fresh install - creates 5 pages, check `content/pages/`
+5. `npm run reset` - type "yes", verify `content/users/` and `content/pages/` are empty, `config/site.json` is reset
+6. `npm run fresh` - walks through reset → setup → seed, server starts cleanly after
+7. Public site at `http://localhost:4096/` shows Home, About, Blog, Contact in nav

package/docs/plans/2026-03-02-cookie-consent-design.md

@@ -0,0 +1,86 @@
+# Cookie Consent Plugin Design
+
+**Date:** 2026-03-02
+
+---
+
+## Overview
+
+A CMS plugin that injects Domma's built-in `Domma.components.cookieConsent()` banner into every public page, with all
+wording, appearance, and category settings configurable from the admin panel.
+
+## Decisions
+
+- **Banner only** - no script blocking or GTM/GA integration. Stores consent preferences in localStorage via Domma's
+  component. Site owner hooks into consent themselves if needed.
+- **All four categories** - Necessary (always required), Functional, Analytics, Marketing. Admin can toggle
+  Functional/Analytics/Marketing on or off.
+- **Both layout and position configurable** - `bar` or `modal` layout; `top` or `bottom` position; `light` or `dark`
+  theme.
+- **Uses Domma's component directly** - `inject-body.html` calls `Domma.components.cookieConsent(cfg)`. Domma is already
+  loaded on public pages via `site.js`, so no extra dependencies.
+
+## File Structure
+
+```
+plugins/cookie-consent/
+├── plugin.json
+├── plugin.js            - GET /settings (public), PUT /settings (admin-auth)
+├── config.js            - defaults
+├── admin/
+│   ├── views/cookie-consent-settings.js
+│   └── templates/cookie-consent-settings.html
+└── public/
+    └── inject-body.html - IIFE
+```
+
+## Config Defaults
+
+| Key                   | Default              | Notes                          |
+|-----------------------|----------------------|--------------------------------|
+| `message`             | `'We use cookies…'`  | Main banner text               |
+| `acceptAllText`       | `'Accept All'`       | Accept button label            |
+| `rejectAllText`       | `'Reject All'`       | Reject button label            |
+| `customizeText`       | `'Customize'`        | Customize button label         |
+| `savePreferencesText` | `'Save Preferences'` | Save button in customize panel |
+| `privacyPolicyText`   | `'Privacy Policy'`   | Privacy link label             |
+| `privacyPolicyUrl`    | `'/privacy-policy'`  | Privacy link URL               |
+| `cookiePolicyText`    | `'Cookie Policy'`    | Cookie policy link label       |
+| `cookiePolicyUrl`     | `''`                 | Empty = link not shown         |
+| `position`            | `'bottom'`           | `'bottom'` or `'top'`          |
+| `layout`              | `'bar'`              | `'bar'` or `'modal'`           |
+| `theme`               | `'dark'`             | `'light'` or `'dark'`          |
+| `showFunctional`      | `true`               | Show Functional category       |
+| `showAnalytics`       | `true`               | Show Analytics category        |
+| `showMarketing`       | `true`               | Show Marketing category        |
+| `consentVersion`      | `'1.0'`              | Increment to re-prompt users   |
+
+## Admin Settings Form
+
+**Banner Wording card:**
+
+- Textarea: Main message
+- Text inputs: Accept All, Reject All, Customize, Save Preferences button labels
+- Text input + URL pairs: Privacy Policy, Cookie Policy (empty URL hides the link)
+
+**Appearance & Categories card:**
+
+- Select: Position (Bottom / Top)
+- Select: Layout (Bar / Modal)
+- Select: Theme (Dark / Light)
+- Checkboxes: Show Functional, Show Analytics, Show Marketing categories
+- Text input: Consent version
+
+## inject-body.html
+
+IIFE that:
+
+1. Fetches `/api/plugins/cookie-consent/settings` (unauthenticated)
+2. Maps flat config → Domma `categories` object (only includes enabled categories)
+3. Calls `Domma.components.cookieConsent(cfg)`
+4. Catches errors silently (no banner shown if fetch fails)
+
+## Note on Public GET Endpoint
+
+Same pattern as back-to-top: `GET /settings` is unauthenticated. Returns only display config - no credentials.
+Intentional and safe.