domma-cms 1.6.21 → 1.6.22

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "domma-cms",
-  "version": "1.6.21",
+  "version": "1.6.22",
   "description": "File-based CMS powered by Domma and Fastify. Run npx domma-cms my-site to create a new project.",
   "type": "module",
   "main": "server/server.js",

package/plugins/CLAUDE.md

@@ -0,0 +1,128 @@
+# Plugin Development
+
+Each plugin needs exactly 3 files:
+
+```
+plugins/my-plugin/
+  plugin.json   Required manifest (name, displayName, version, description, author, date, icon)
+  plugin.js     Default export: Fastify plugin function
+  config.js     Default export: plain object of config defaults
+```
+
+See `docs/plugin-development.md` for full plugin API, hooks, and injection points.
+Each plugin directory has its own `CLAUDE.md` with routes, storage, and gotchas.
+
+**User docs ship with the plugin:** `docs/*.md` (Markdown, optional `title`/`order` frontmatter, no H1,
+shortcodes shown literally) appear under Documentation > Plugins for users who can use the plugin
+(`docs.permission`, else the first sidebar permission). Update them in the same change as the feature -
+see "User guides in the Documentation folder" in `docs/plugin-development.md`.
+
+## Contracts every plugin gets wrong
+
+These five faults were each found in more than one shipped plugin, and each one
+is silent - nothing logs, nothing throws where you can see it, and the screen
+just does less than it should. Copy `_template/`, not another plugin.
+
+**Collection schemas.** `createCollection()` destructures `title` and calls
+`.trim()`, and `validateEntryData()` reads `data[field.name]`. So a collection is
+named by `title` (not `label`) and a field by `name` (not `key`). Get either
+wrong and every schema throws; `setupPlugin()` catches that and says nothing, so
+the collections are left as empty directories and every route answers
+`Collection "…" not found`. Delete those directories before retrying - the mkdir
+happens before the validation, so a second attempt reports "already exists"
+instead of the real fault. Note this only bites a FRESH install: on a box where
+the collection already exists, `setupPlugin` skips it and the broken schema is
+invisible.
+
+**Route params.** Domma's router calls `view.onMount($container)` with ONE
+argument and never the params, and `R.current` is a METHOD - so
+`R.current?.params?.id` reads `.params` off the function object and is always
+`undefined`. An editor view that does this opens blank on every edit and Save
+creates a duplicate. Read the hash, as every core editor view does:
+
+```js
+const m = location.hash.match(/^#\/plugins\/my-plugin\/edit\/([^?#]+)/);
+const id = m ? decodeURIComponent(m[1]) : null;
+```
+
+**Class names are Domma's, not Bootstrap's.** `form-control`, `d-flex`,
+`justify-content-between`, `align-items-center`, `h2`, `h3`, `small`, `fw-bold`,
+`font-monospace`, `btn-outline-secondary`, `col-sm-*` and `badge-outline` are
+defined NOWHERE in this admin and style nothing. Domma's are `form-input` /
+`form-textarea` / `form-select` / `form-checkbox`, `flex`, `justify-between`,
+`items-center`, `text-2xl`, `text-sm`, `font-bold`, `font-mono`, `btn-outline`,
+`col-*`, `badge-secondary`. For a stat tile the admin ships `.stat-card` /
+`.stat-icon` / `.stat-value` / `.stat-label`. Put your own rules in
+`admin/css/index.css` and declare it in the manifest's `admin.css` - not inline
+on the element.
+
+**`F.create` takes a schema, not a container.** The signature is
+`F.create(schema, data, options).renderTo(el)`, values come back from
+`form.getData()` and `form.validate()`, and `placeholder` / `hint` live under
+`formConfig`. Passing an element first makes it the schema and the form renders
+nothing at all. `admin/js/views/plugins.js` is the house pattern.
+
+**Reading an H response.** Some routes send a bare array and some send
+`{data: […]}`. `res.data ?? []` silently empties a screen that the API is
+filling correctly. Write `res.data ?? (Array.isArray(res) ? res : [])`.
+
+## The plugin banner is the admin's, and it has a door
+
+The admin wraps every plugin view in `.dm-plugin-shell` at the point views are
+registered (`admin/js/lib/plugin-chrome.js`), so the banner carrying the name,
+the version and the licence is not yours to draw - which is why a template that
+opens with its own `<h1>` shows the same words twice and has one stripped.
+
+The facts read version, release date, licence and - for a paid plugin with an
+entitlement - its expiry: "Expires" for a rental, "Support to" for a perpetual
+licence, whose plugin never stops. That comes from `pluginExpiry()` in
+`server/services/plugins.js`; a plugin does nothing to get it.
+
+A screen-level control belongs IN that banner, and `addBannerAction(container,
+{icon, title, onClick, id})` puts it there, to the LEFT of those facts. Settings
+in particular goes there as a cog on the plugin's main screens - not as a
+sidebar item, a tab, or a button in a pane of your own - so every plugin keeps
+it in the same place. Import it at RUN
+time and survive its absence:
+
+```js
+try {
+    const chrome = await import('/admin/js/lib/plugin-chrome.js');
+    if (!chrome.addBannerAction?.($container, {...})) throw new Error('no banner');
+} catch {
+    // older admin, or no chrome: put the control in your own toolbar
+}
+```
+
+A static import would take the whole view down on a CMS whose `admin/` predates
+the export - and `admin/` is replaced wholesale by the updater, so that is a
+version skew you do not control.
+
+## Smaller ones, same flavour
+
+- `E.slideover().close()` only hides the panel and `destroy()` does not detach
+  its element, so every open leaves another one in the document. Do both, via
+  `onClose`, after the slide-out has run.
+- `requireAdmin` reads `request.user`, which only `authenticate` populates - as a
+  lone preHandler it answers 401 to everyone, admin included. Always
+  `[authenticate, requireAdmin]`.
+- Plugin settings live in `config/plugins.json`; read them from `options.settings`
+  or `getPluginStates()[name].settings` and write them with
+  `savePluginState(name, {settings})`. `getConfig`/`saveConfig` in
+  `server/config.js` take a FILE NAME, not a config object.
+- `authenticate` is Bearer-only, so an `<a href target="_blank">` to any API
+  route arrives with no Authorization header and comes back 401. Fetch through
+  `H` and write the result into a window you opened on the click.
+- An unknown `data-icon` renders an empty span and says nothing. Check the name
+  against the shipped bundle before using it. An icon inside a `data-if` needs
+  scanning AFTER the element comes back, or the span is scanned while detached
+  and stays empty - set the observable, `M.flush()`, then scan.
+- **`type: 'date'` in an `F.create` schema cannot be submitted.** Forma renders
+  `<input type="date">`, which writes a string, and `M.types.date` accepts only
+  a real `Date`, so `validate()` fails with "Expected type date" every time and
+  the save button appears to do nothing. Declare the field with no `type` (the
+  model only type-checks when one is set) and attach **`E.datePicker`** to the
+  rendered input: it is one themed control in every browser, it writes ISO
+  `YYYY-MM-DD` into the input and it fires `input`/`change`, so the model and
+  `form.getData()` hear it exactly as they hear typing. `plugins/invoice` does
+  this in its editor, its list filters and its payment dialog.

package/plugins/_template/CLAUDE.md

@@ -0,0 +1,23 @@
+# PLUGIN_DISPLAY_NAME - AI Assistant Guide
+
+## Purpose
+TODO: Describe what this plugin does.
+
+## Files
+- `plugin.json`, `plugin.js`, `config.js`
+- `admin/views/index.js` - main admin view (`indexView`)
+- `admin/templates/index.html` - view template
+- `admin/css/index.css` - admin styles (auto-injected via plugin.json `admin.css`)
+
+## Routes
+All API routes are under `/api/plugins/PLUGIN_SLUG` and require authentication.
+
+| Method | Path | Purpose | Location |
+|---|---|---|---|
+
+## Gotchas
+- Use `S.get/set` not `localStorage`
+- Use `H.get/post/put/delete` not `fetch()`
+- Use `F.create()` for forms, `T.create()` for tables
+- For HTML with inline styles or data-* attrs: `import { safeSetHTML } from '../../admin/js/lib/safe-html.js'`
+- For interactive elements (buttons) inside dynamic HTML: build via DOM (`createElement`/`appendChild`)

package/plugins/_template/docs/guide.md

@@ -0,0 +1,37 @@
+---
+title: Guide
+---
+One or two sentences on what this plugin does for a site owner. This file appears under
+Documentation > Plugins in the admin while the plugin is enabled (see "User guides in the
+Documentation folder" in docs/plugin-development.md). Do not start with a top-level heading -
+the page header already shows the plugin's name.
+
+## Getting started
+
+1. Open **Tools > PLUGIN_DISPLAY_NAME**.
+2. Click **New** and fill in the form.
+3. Click **Save**.
+
+## Screens
+
+### PLUGIN_DISPLAY_NAME
+
+What the list shows, what clicking a row does, and what the right-click menu offers.
+
+## Settings
+
+Click the cog on the plugin banner. List each setting and what it changes.
+
+## Shortcodes
+
+```text
+[PLUGIN_SLUG limit="5"]
+```
+
+## Permissions and roles
+
+Which permissions in **System > Roles** open the screen, and who holds them by default.
+
+## Limitations
+
+What it does not do, so nobody looks for it.

package/plugins/_template/plugin.js

@@ -4,11 +4,12 @@
 
 export default async function plugin(fastify, options) {
     const { authenticate, requireAdmin } = options.auth;
-    const BASE = `/api/plugins/PLUGIN_SLUG`;
 
-    // Add your API routes here.
+    // Add your API routes here. Paths are RELATIVE: the CMS mounts every route
+    // in this file under /api/plugins/PLUGIN_SLUG, so '/items' answers at
+    // /api/plugins/PLUGIN_SLUG/items. A full path here would end up doubled.
     // Example:
-    // fastify.get(`${BASE}/items`, { preHandler: [authenticate] }, async (request, reply) => {
+    // fastify.get('/items', { preHandler: [authenticate] }, async (request, reply) => {
     //     return { items: [] };
     // });
 }

package/scripts/build.js

@@ -93,6 +93,14 @@ const PLUGIN_AS_IS_PATTERNS = [
   'plugins/*/blocks/**/*.css',
   // Images a plugin serves from public/ (blog's sample-post covers).
   'plugins/*/public/**/*.svg',
+  // The scaffold template's Markdown: its CLAUDE.md and the docs/guide.md a new
+  // Tool starts its Documentation page from. The free-tier plugins ship whole
+  // from their lock, but _template goes through these patterns, which carried no
+  // .md - so every Tool scaffolded on an installed site lacked both, while the
+  // New plugin panel promised the CLAUDE.md.
+  'plugins/_template/**/*.md',
+  // The plugin-authoring guide the CMS's own CLAUDE.md points Tool authors to.
+  'plugins/CLAUDE.md',
 ];
 
 /**

package/server/services/plugins.js

@@ -11,6 +11,7 @@
  *   plugins/{name}/data/         - optional plugin-specific data store
  */
 import fs from 'fs/promises';
+import {readFileSync} from 'fs';
 import path from 'path';
 import matter from 'gray-matter';
 import {getConfig, saveConfig} from '../config.js';
@@ -1253,6 +1254,25 @@ async function newestAdminMtime(root) {
     return newest;
 }
 
+/**
+ * The plugins the engine ships with (the free tier): the names in
+ * plugins/free-tier.lock.json. Read once; an install without the lock ships none.
+ *
+ * @returns {Set<string>}
+ */
+let shippedNames = null;
+export function shippedPluginNames() {
+    if (!shippedNames) {
+        try {
+            const lock = JSON.parse(readFileSync(path.join(PLUGINS_DIR, 'free-tier.lock.json'), 'utf8'));
+            shippedNames = new Set(Object.keys(lock.plugins || {}));
+        } catch {
+            shippedNames = new Set();
+        }
+    }
+    return shippedNames;
+}
+
 /**
  * The licence line shown on a plugin's admin banner.
  *
@@ -1266,12 +1286,16 @@ async function newestAdminMtime(root) {
  * @param   {object} manifest
  * @returns {string}
  */
-export function pluginLicence(manifest) {
+export function pluginLicence(manifest, shipped = shippedPluginNames()) {
     const stated = manifest.licence || manifest.license;
     if (typeof stated === 'string' && stated.trim()) return stated.trim();
     if (CORE_PLUGINS.has(manifest.name)) return 'Built in';
     if (manifest.closedSource) return 'Commercial licence';
-    return 'Included with Domma CMS';
+    // Only the plugins the engine ships (the free tier, listed in its lock) came with
+    // the CMS. Anything else that is neither bought nor licensed is one the site made:
+    // a Tool scaffolded from the Marketplace used to be labelled as part of the CMS.
+    if (shipped.has(manifest.name)) return 'Included with Domma CMS';
+    return 'Your own Tool';
 }
 
 /**