domma-cms 1.6.60 → 1.7.1

package/docs/superpowers/specs/2026-04-07-blog-plugin-design.md

@@ -0,0 +1,300 @@
+# Blog Plugin - Design Spec
+
+**Date:** 2026-04-07
+**Status:** Approved
+
+---
+
+## Context
+
+Domma CMS ships with a clean plugin architecture where bundled plugins (Todo, Notes, Contacts, Messages) register their collections and roles at enable-time. The Blog plugin extends this pattern in two meaningful ways:
+
+1. It is the first plugin to own **public-facing URLs** - blog posts need proper routes at `/blog/*`, not just admin API endpoints.
+2. It is the first plugin to exercise the **plugin-registered roles** mechanism (`plugins/<name>/roles/*.json`) in a real-world scenario, with `blog-author` and `blog-editor` as distinct contributor tiers below `admin`.
+
+The `posts`, `categories`, and `comments` collections that previously existed as static seeds or demo data are removed from the core. They exist only when the Blog plugin is enabled.
+
+---
+
+## Decisions
+
+| Concern | Decision |
+|---|---|
+| Public routing | `plugin.public.js` convention - new optional file, registered at Fastify root before the catch-all |
+| Comments | Built-in but `commentsEnabled: false` by default |
+| Roles | Plugin-registered: `blog-author`, `blog-editor` |
+| Base path | Configurable (`basePath: '/blog'`); restart required to apply change |
+| Publishing workflow | Draft → Scheduled → Published; lazy scheduled-post check on every request |
+
+---
+
+## Platform Extension: `plugin.public.js`
+
+### Problem
+
+`plugin.js` is always registered under `/api/plugins/<name>`. There is no mechanism for a plugin to own a public URL path such as `/blog/*`.
+
+### Solution
+
+Introduce `plugin.public.js` as an optional convention alongside `plugin.js`:
+
+- `server/services/plugins.js` `setupPlugin` detects `plugin.public.js` and stores its resolved path in the plugin registry entry (`publicEntry`).
+- `server/server.js` iterates enabled plugins after loading them and calls `fastify.register(publicPlugin, { prefix: settings.basePath ?? '/blog', ...opts })` for each that has a `publicEntry`. `settings` is resolved at registration time via `getPluginSettings(name)` (the same function used in `plugin.js` registration) so the value is always current at startup. This registration happens **before** `routes/public.js` is registered, guaranteeing blog routes take precedence over the catch-all.
+- `plugin.public.js` exports a default Fastify plugin function. It receives `{ settings, auth, config }` in `options`, identical to `plugin.js`.
+- `teardownPlugin` marks the public entry as removed; a server restart is required for route changes to take effect (Fastify does not support live route deregistration).
+
+### Benefit
+
+Any future plugin that needs public URL ownership - Jobs board, Events, Portfolio, Shop - drops a `plugin.public.js` and gets it for free. No further platform changes needed.
+
+---
+
+## Data Model
+
+### Collection: `posts`
+
+Registered via `plugins/blog/collections/posts/schema.json`. Managed through `server/services/collections.js`.
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `title` | text | yes | |
+| `slug` | text | yes | URL-safe, unique; auto-derived from title on create; editable |
+| `excerpt` | textarea | no | Falls back to first 160 chars of content for meta description |
+| `content` | markdown | no | Full body; CMS shortcode pipeline applied on render |
+| `featuredImage` | text | no | Media ID from `/api/media` |
+| `categories` | array | no | Array of category IDs |
+| `tags` | array | no | Free-form strings |
+| `authorId` | text | yes | User ID of post author |
+| `status` | select | yes | `draft` \| `scheduled` \| `published` |
+| `publishedAt` | datetime | no | Required when `status: scheduled`; set to now on manual publish |
+| `seo.title` | text | no | Overrides site title pattern in `<title>` |
+| `seo.description` | text | no | Overrides excerpt for `<meta name="description">` |
+
+### Collection: `categories`
+
+| Field | Type | Notes |
+|---|---|---|
+| `name` | text | Required |
+| `slug` | text | Required, URL-safe |
+| `description` | textarea | |
+| `parentId` | text | Optional; enables sub-categories |
+
+### Collection: `comments`
+
+| Field | Type | Notes |
+|---|---|---|
+| `postId` | text | Required; FK to posts entry |
+| `parentId` | text | Optional; FK to parent comment (threaded) |
+| `authorName` | text | Required |
+| `authorEmail` | text | Required |
+| `authorUrl` | text | Optional |
+| `body` | textarea | Required |
+| `status` | select | `pending` \| `approved` \| `rejected` \| `spam` |
+| `createdAt` | datetime | Set server-side on create |
+
+---
+
+## Plugin Roles
+
+Registered via `plugins/blog/roles/`:
+
+### `blog-author`
+```json
+{
+  "name": "blog-author",
+  "label": "Blog Author",
+  "level": 2,
+  "permissions": ["blog-posts"],
+  "badgeClass": "badge-info",
+  "resources": [
+    { "key": "blog-posts", "label": "Blog Posts", "actions": ["read", "create", "update"] }
+  ]
+}
+```
+Authors can create and edit their own draft posts. **They cannot publish.** Status changes to `published` or `scheduled` are blocked server-side for anyone whose role is not `blog-editor`, `admin`, or `super-admin`. The gate uses a **named-role check** (`['blog-editor', 'admin', 'super-admin'].includes(request.user.role)`), not a level comparison - both `blog-author` and `blog-editor` are level 2, so a level-based check would incorrectly grant authors publish access. An author attempting to call `POST /posts/:id/publish` or `POST /posts/:id/schedule` receives 403 regardless of whether the post is their own.
+
+### `blog-editor`
+```json
+{
+  "name": "blog-editor",
+  "label": "Blog Editor",
+  "level": 2,
+  "permissions": ["blog-posts", "blog-categories", "blog-comments"],
+  "badgeClass": "badge-success",
+  "resources": [
+    { "key": "blog-posts",      "label": "Blog Posts",       "actions": ["read", "create", "update", "delete", "publish"] },
+    { "key": "blog-categories", "label": "Blog Categories",  "actions": ["read", "create", "update", "delete"] },
+    { "key": "blog-comments",   "label": "Blog Comments",    "actions": ["read", "update", "delete"] }
+  ]
+}
+```
+
+---
+
+## Public Routes (`plugin.public.js`)
+
+All routes registered at the Fastify root under `basePath` (default `/blog`). Static routes (`/feed.xml`, `/page/:n`, `/category/:slug`, `/tag/:tag`, `/author/:id`) **must be registered before** `/:slug` - Fastify prefers static over parametric routes only when they are registered first for the same prefix depth.
+
+| Method | Path | Purpose |
+|---|---|---|
+| GET | `/` | Blog index - paginated published posts |
+| GET | `/feed.xml` | RSS 2.0 feed (registered before `/:slug`) |
+| GET | `/page/:n` | Pagination |
+| GET | `/category/:slug` | Category archive |
+| GET | `/tag/:tag` | Tag archive |
+| GET | `/author/:id` | Author archive |
+| GET | `/:slug` | Individual post - lazy scheduled check (`publishedAt <= now`) - registered last |
+
+**Scheduled post visibility**: Every `GET /:slug` request checks `status === 'published' || (status === 'scheduled' && new Date(publishedAt) <= new Date())`. No background scheduler - lazy evaluation on each request. A post whose scheduled time arrives between requests becomes visible automatically on the next hit.
+
+**Rendering**: Public blog pages use `server/templates/page.html` (the same shell as CMS pages). The plugin extends `renderer.js` with `renderBlogPage(template, data, postMeta)` which injects post-specific SEO: `<title>`, `<meta name="description">`, Open Graph `og:title`, `og:description`, `og:image` (featured image URL). Plugin-owned HTML templates live in `plugins/blog/templates/` - `index.html`, `post.html`, `category.html`, `tag.html`, `author.html`. These render the body content that slots into the page shell.
+
+**Comment form**: When `commentsEnabled: true`, `post.html` includes a comment submission form that POSTs to `/api/plugins/blog/comments`. When `commentModeration: true` (default), new comments land in `status: pending` and are not shown until approved.
+
+---
+
+## API Routes (`plugin.js`)
+
+All under `/api/plugins/blog`. All routes require `authenticate` **except** `POST /comments`, which is registered separately without the global authenticate hook to allow anonymous comment submission from public visitors.
+
+| Method | Path | Auth | Purpose |
+|---|---|---|---|
+| GET | `/posts` | any | List posts (authors see own; editors/admins see all) |
+| POST | `/posts` | author+ | Create post |
+| GET | `/posts/:id` | any | Get post |
+| PUT | `/posts/:id` | author (own) / editor+ | Update post |
+| DELETE | `/posts/:id` | editor+ | Delete post |
+| POST | `/posts/:id/publish` | editor+ | Set status:published, publishedAt:now |
+| POST | `/posts/:id/schedule` | editor+ | Set status:scheduled + publishedAt |
+| GET | `/categories` | any | List categories |
+| POST | `/categories` | editor+ | Create category |
+| PUT | `/categories/:id` | editor+ | Update category |
+| DELETE | `/categories/:id` | editor+ | Delete category |
+| GET | `/comments` | editor+ | List comments (filterable by status, postId) |
+| POST | `/comments` | public (no auth) | Submit comment (rate-limited, honeypot field) |
+| PUT | `/comments/:id` | editor+ | Moderate (approve/reject/spam) |
+| DELETE | `/comments/:id` | editor+ | Delete comment |
+| GET | `/settings` | admin+ | Get blog plugin settings |
+| PUT | `/settings` | admin+ | Save blog plugin settings to config/plugins.json |
+
+---
+
+## Admin UI
+
+Single "Blog" sidebar entry, with sub-navigation to four views:
+
+### Posts list (`#/plugins/blog/posts`)
+- `T.create()` table: title, status badge, author, categories, publishedAt, edit/delete actions
+- Filter bar: status select, category select, author select, search input
+- "New Post" → navigates to editor with blank state
+
+### Post editor (`#/plugins/blog/posts/new` and `#/plugins/blog/posts/:id`)
+- Two-column layout: main area (title input, slug input with auto-derive toggle, content textarea), sidebar (status/publishedAt picker, categories checklist, tags input, featured image picker via media modal, SEO accordion)
+- Status transitions: Save Draft → always available; Publish Now → sets status:published; Schedule → reveals datetime picker, sets status:scheduled
+- Slug derives from title on first edit; once manually touched it becomes independent with a "⚠ Changing slug breaks existing links" warning on published posts
+
+### Categories (`#/plugins/blog/categories`)
+- Inline-editable table: name, slug, description, parent, post count
+- Create/edit/delete - no separate modal needed for simple fields
+
+### Comments (`#/plugins/blog/comments`)
+- Visible only when `commentsEnabled: true`
+- Three tabs: Pending | Approved | Spam
+- Per-row actions: Approve, Reject, Spam, Delete
+- Post title shown as a link to the admin post editor
+
+### Blog settings (`#/plugins/blog/settings`)
+- `F.create()` form: basePath, postsPerPage, commentsEnabled toggle, commentModeration toggle, feedLength
+- Save POSTs to `PUT /api/plugins/blog/settings`
+- Banner: "Base path and posts-per-page changes require a server restart"
+
+---
+
+## `config.js` Defaults
+
+```js
+export default {
+    basePath:           '/blog',
+    postsPerPage:       10,
+    commentsEnabled:    false,
+    commentModeration:  true,
+    feedLength:         20,
+    storage: { adapter: 'file' }
+};
+```
+
+---
+
+## Removing Innate Collections
+
+`posts`, `categories`, and `comments` were previously demo-seeded or referenced as preset collections. As of the role-collapse cleanup they no longer exist in `content/collections/` or `server/services/presetCollections.js`. This spec confirms they belong exclusively to the Blog plugin. No further removal is needed - the audit step in the build sequence should grep for any lingering hardcoded references to these slugs in non-blog code.
+
+---
+
+## Plugin Layout
+
+```
+plugins/blog/
+  plugin.json
+  plugin.js              API routes
+  plugin.public.js       Public SSR routes
+  config.js
+  CLAUDE.md
+  roles/
+    blog-author.json
+    blog-editor.json
+  collections/
+    posts/schema.json
+    categories/schema.json
+    comments/schema.json
+  templates/             Public SSR HTML (slots into page.html shell)
+    index.html
+    post.html
+    category.html
+    tag.html
+    author.html
+  admin/
+    views/
+      blog.js            Entry view (posts list)
+      post-editor.js     Post editor
+      categories.js
+      comments.js
+      settings.js
+    templates/
+      blog.html
+      post-editor.html
+      categories.html
+      comments.html
+      settings.html
+```
+
+---
+
+## Build Sequence
+
+1. **Platform extension** - extend `plugins.js` to detect and store `publicEntry`; extend `server.js` to register public plugins before `routes/public.js`
+2. **renderer.js** - add `renderBlogPage()` helper
+3. **Collection schemas** - write the three `schema.json` files
+4. **Role files** - write `blog-author.json` and `blog-editor.json`
+5. **`plugin.js`** - API routes (posts CRUD + publish/schedule, categories, comments, settings)
+6. **`plugin.public.js`** - public SSR routes + RSS feed
+7. **Public templates** - `index.html`, `post.html`, `category.html`, `tag.html`, `author.html`
+8. **Admin views** - posts list, post editor, categories, comments, settings
+9. **`plugin.json` + `config.js` + `CLAUDE.md`**
+10. **`config/plugins.json`** - add blog entry (disabled by default; enable to test)
+11. **Audit** - grep codebase for hardcoded `posts`/`categories`/`comments` collection slug references outside `plugins/blog/`
+
+---
+
+## Verification
+
+- **Fresh install**: `npm run fresh` → enable Blog plugin → confirm three collections appear in `content/collections/`, two roles in `content/collections/roles/data.json`, and `/blog` returns a valid (empty) index page
+- **Public routing**: create a published post with slug `hello-world` → `GET /blog/hello-world` returns 200 with correct title in `<title>` tag; a draft post with the same slug returns 404
+- **Scheduled post**: create a post with `status:scheduled`, `publishedAt` 10 seconds in the future → `GET /blog/:slug` returns 404; wait 10 seconds; same URL returns 200
+- **plugin.public.js convention**: disable Blog plugin → restart → `/blog` returns 404 (catch-all serves a CMS 404 page); re-enable → restart → `/blog` returns 200
+- **Role gate**: log in as `blog-author` → can create/edit own draft posts → attempting to publish returns 403; log in as `blog-editor` → publish succeeds
+- **Comments**: enable `commentsEnabled`, submit a comment on a post → lands in Pending tab in admin; approve it → appears below the post on the public page
+- **RSS**: `GET /blog/feed.xml` returns valid XML with `<rss version="2.0">` and correct `<item>` entries for published posts only
+- **Category archive**: assign a post to category `news` → `GET /blog/category/news` lists only posts in that category
+- **SEO injection**: post with custom `seo.title` → `<title>` matches the custom value; post without → title follows the site pattern `{post.title} | {site.title}`
+- **Base path change**: change `basePath` to `/news` in settings → restart → `/news` returns 200, `/blog` falls through to CMS catch-all