domma-cms 0.38.2 → 0.39.0

package/CLAUDE.md

@@ -25,32 +25,9 @@ Domma provides built-in solutions. Never use vanilla JS equivalents.
 
 ## Architecture
 
-```
-server/                  Fastify 5 API + SSR (DO NOT modify — upstream-replaced on update)
-  server.js              Entry point; registers routes, plugins, static serving
-  config.js              Config loader: config singleton, getConfig(), saveConfig()
-  middleware/auth.js     JWT authenticate, requireRole, requireAdmin, canManageUser
-  routes/api/            REST API (pages, settings, navigation, media, auth, users, plugins, …)
-  routes/public.js       Catch-all SSR for public pages; enforces page.visibility
-  services/              Core business logic (see Services section below)
-  templates/page.html    Public page HTML shell ({{headInject}}, {{bodyEndInject}} slots)
-admin/                   Domma SPA admin panel (DO NOT modify — upstream-replaced on update)
-public/js/               Public site JS (site.js + component init)
-public/css/              Site stylesheet (site.css is yours to edit)
-bin/                     CLI entry point
-scripts/                 Setup, reset, seed, fresh, pro, build utilities
-content/pages/           Markdown pages (URL → file mapping below)
-content/media/           Uploaded media
-content/users/           User accounts (JSON)
-content/collections/     Collection entries
-content/blocks/          Reusable content blocks
-content/forms/           Form definitions
-content/versions/        Page version history
-content/custom.css       Optional custom CSS (served at /custom.css)
-config/                  All configuration JSON (see Config section)
-plugins/                 CMS plugins (yours to create/modify)
-docs/                    Reference documentation
-```
+**DO NOT modify `server/` or `admin/`** — both are replaced wholesale by the upstream updater.
+Yours to edit: `public/css/site.css`, `content/custom.css`, `plugins/`, and `config/` (see Config
+Reference for which config files the updater merges vs leaves alone).
 
 **URL → file mapping:**
 
@@ -76,38 +53,10 @@ Page content here. Shortcodes work anywhere in the body.
 
 **Page visibility** is enforced server-side in `server/routes/public.js` — unauthenticated users and insufficient role levels receive a 403/redirect.
 
-### Shortcodes (~28 types — full syntax in `docs/markdown-shortcodes.md`)
-
-| Shortcode                               | Purpose                                            |
-|-----------------------------------------|----------------------------------------------------|
-| `[card]`                                | Card container (optional title, collapsible, icon) |
-| `[grid cols="N"]` / `[col]`             | CSS Grid layout (Domma Grid — NOT `.col` class)    |
-| `[row]` / `[col]`                       | Row/column layout                                  |
-| `[slideover trigger="..." title="..."]` | Slide-over panel                                   |
-| `[dconfig]{...}[/dconfig]`              | Declarative page config (JSON)                     |
-| `[tabs]` / `[tab title="..."]`          | Tab panels                                         |
-| `[accordion]` / `[item title="..."]`    | Accordion sections                                 |
-| `[carousel]` / `[slide]`                | Image/content carousel                             |
-| `[hero title="..." tagline="..."]`      | Hero section                                       |
-| `[table]`                               | Data table (Markdown table inside)                 |
-| `[badge variant="..."]`                 | Badge/label                                        |
-| `[countdown to="..." /]`                | Countdown timer                                    |
-| `[timeline]` / `[event]`                | Timeline component                                 |
-| `[spacer /]`                            | Vertical spacer                                    |
-| `[center]`                              | Centre-align content                               |
-| `[icon name="..." /]`                   | Inline icon                                        |
-| `[embed url="..." /]`                   | Video (YouTube/Vimeo/self-hosted) or iframe embed  |
-| `[cta action="..."]`                    | Collection action trigger (admin)                  |
-| `[block name="..."]`                    | Embed a reusable content block                     |
-| `[view slug="..."]`                     | Embed a saved view                                 |
-| `[collection slug="..."]`               | Render a collection inline                         |
-| `[text field="..."]`                    | Output a single text field value                   |
-| `[button label="..." href="..."]`       | Styled button / CTA link                           |
-| `[link href="..."]`                     | Styled anchor                                      |
-| `[listgroup]` / `[item]`                | List group component                               |
-| `[form slug="..."]`                     | Embed a form                                       |
-| `[banner]`                              | Full-width banner strip                            |
-| `[celebrate]`                           | Confetti / effects trigger                         |
+### Shortcodes
+
+~28 shortcode types. **Full list and syntax: `docs/markdown-shortcodes.md`** — read it before writing or
+editing shortcode markup; the nesting rules below are the part the doc does not make obvious.
 
 ### Shortcode Nesting Rules
 
@@ -140,37 +89,12 @@ Add custom public-site JS to `public/js/site.js` or new files loaded from `publi
 
 ## Core Services (`server/services/`)
 
-| File                    | Purpose                                                         |
-|-------------------------|-----------------------------------------------------------------|
-| `content.js`            | File CRUD for pages and media; reads `config.content.*`         |
-| `markdown.js`           | gray-matter + marked + shortcode pipeline                       |
-| `renderer.js`           | Server-side HTML assembly; injects globals into page shell      |
-| `users.js`              | File-based user CRUD (`content/users/{id}.json`)                |
-| `userTypes.js`          | Role seed, load, invalidate, `getRoleLevel()`, `getPermissionsFor()` |
-| `roles.js`              | Role helpers and hierarchy                                      |
-| `userProfiles.js`       | User profile CRUD                                               |
-| `permissionRegistry.js` | Central permission map; route guards read this at request time  |
-| `rowAccess.js`          | Row-level access control for collections                        |
-| `collections.js`        | Collection entry CRUD; delegates I/O to storage adapter         |
-| `apiTokens.js`          | Project-scoped API tokens (`api-tokens` preset) for the external `/api/v1` surface; SHA-256 hash stored, plaintext shown once |
-| `apiEndpoints.js`       | Custom endpoint definitions (`api-endpoints` preset) — registry/matcher/executor for `/api/x/<project><path>` |
-| `adapterRegistry.js`    | `getAdapter(slug)` — resolves + caches adapter per collection; `invalidate(slug)` on schema change |
-| `adapters/FileAdapter.js`   | Default adapter — plain JSON files                          |
-| `adapters/MongoAdapter.js`  | Optional Pro adapter — native MongoDB driver; `cms_` prefix |
-| `connectionManager.js`  | `initialise(cfg)`, `getDb(name)`, `shutdown()` — Mongo connections |
-| `blocks.js`             | Reusable block CRUD (`content/blocks/`)                        |
-| `forms.js`              | Form definition CRUD (`content/forms/`)                        |
-| `views.js`              | Saved view CRUD                                                 |
-| `versions.js`           | Page version history (`content/versions/`)                     |
-| `actions.js`            | Collection action handlers                                      |
-| `hooks.js`              | Plugin hook registry (`registerShortcode`, `registerSanitizeRules`, etc.) |
-| `presetCollections.js`  | Preset schema seeding and management                            |
-| `email.js`              | SMTP mail sending (uses `config/site.json` SMTP settings)       |
-| `images.js`             | Image processing / thumbnail generation                         |
-| `plugins.js`            | Plugin discovery, validation, registration, injection snippets  |
-| `pluginScaffold.js`     | Scaffold new plugins from `plugins/_template` (`POST /api/plugins/scaffold`, pre-enabled, restart to activate) |
-| `pluginFiles.js`        | In-admin plugin code editor I/O — list/read/write/delete files confined to `plugins/<name>/`, gated by `plugins.develop` |
-| `cache/index.js`        | Pluggable response cache (Memory/None/Redis drivers) with tag-based invalidation. See `docs/cache.md`. |
+Business logic lives in `server/services/` — `ls` it and read the file you need; names are literal
+(`collections.js`, `users.js`, `markdown.js`, `plugins.js`, …). Non-obvious ones:
+
+- `permissionRegistry.js` — central permission map; route guards read the **cache at request time**
+- `hooks.js` — plugin hook registry (`registerShortcode`, `registerSanitizeRules`, `registerMenuLocation`, …)
+- `cache/index.js` — pluggable response cache with tag-based invalidation; see `docs/cache.md`
 
 ## Storage Adapters
 
@@ -198,17 +122,8 @@ Seeded on first run with: `admin`, `manager`, `editor`, `subscriber`.
 
 ## 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.
+Plugins live in `plugins/<name>/` — see `plugins/CLAUDE.md` (loaded when working there) for the required
+file structure, and `docs/plugin-development.md` for the full API, hooks, and injection points.
 
 ## Config Reference
 
@@ -290,14 +205,9 @@ The single source of truth is `getProjectForPage(urlPath, frontmatterProject)` i
 
 **Filtering on list endpoints.** Every artefact list path runs `list.filter(item => canSeeArtefact(user, item))`. Get/write endpoints return 403 when the artefact's project isn't in the user's scope. The Projects section in the admin sidebar always renders — `listProjectsForUser(user)` always includes core, so every site shows at least the Core project.
 
-## External API & API tokens
-
-Collections are externally consumable at `/api/v1/:slug[/:id]` — a stable alias of `/api/collections/:slug/public[...]` (same handlers). Per-verb access via `schema.api.<verb>.access`: `'public'`, a role name (JWT), or `'token'`. Token mode is **strict** — only a valid `dcms_<64 hex>` Bearer token is accepted (never a JWT), and a token never satisfies a role mode. `schema.api.read.fields` optionally allowlists which `data` fields public/external reads return (admin endpoints unaffected).
-
-Tokens live in the `api-tokens` **preset collection** (always file-based and undeletable — both derived automatically from `PRESETS`). Each token is bound to one project (`data.project`, immutable) and only works on collections whose `resolveArtefactProject(schema)` matches; optional `scopes: [{collection, verbs[]}]` narrow it further. Service: `server/services/apiTokens.js` — SHA-256 hash stored, plaintext returned once by `createToken()`, in-memory validate cache invalidated via the `collection:entry*` hooks. Admin routes: `server/routes/api/api-tokens.js` (projects.js DI pattern). Admin UI: System → API Tokens (`admin/js/views/api-tokens.js`). Scaffolder recipes may declare `apiTokens: [{name, scopes?}]` — generated at apply time under the recipe's project, idempotent on re-apply, plaintext surfaced once in `created.apiTokens`.
-
-Permission family `api-tokens.{read,create,update,delete}`: custom roles are **not back-filled** (same gotcha as Menus/Projects), but `roles.js seed()` self-heals every BASE role against its seed definition at boot (append-only; root's seed = the full registry, and the base `admin` seed includes `api-tokens` + `api-endpoints` since 0.25.1). A seeded permission removed from a base role is re-added at boot — use a custom role to run with less. `ensureSidebarItem()` in `sidebar-migration.js` appends the System → API Tokens entry on existing installs (no-op when the item's URL already exists anywhere in the persisted menu). Note: `admin/js/views/collection-editor.js` was de-minified (identifiers still mangled) so the API-access tab could gain the Token mode + read-fields input.
-
-## Custom API endpoints (API Builder)
+## External API & API tokens, custom API endpoints
 
-Named endpoints over collection data at `/api/x/<project><path>` — e.g. `/api/x/world-cup/fixtures-day/:date`. Definitions are **data, never code**: entries in the `api-endpoints` preset collection binding a path (with `:param` segments) to a collection query — filter clauses whose values may embed `{{params.x}}` (required → 400 when missing) or `{{query.x}}` (optional → clause dropped), sort/limit, a read field allowlist, `mode: list|single`, and `auth: public|token|<role>`. One catch-all route (`server/routes/api/endpoints-public.js`, `fastify.get('/x/*')`) matches at runtime via the compiled registry in `server/services/apiEndpoints.js` (static segments beat `:param`; registry invalidated via the `collection:entry*` hooks + own mutations). Auth reuses `checkPublicAccess` from `routes/api/collections.js` (now exported) with a synthesized schema, so token project binding/scopes and the field allowlist are the same battle-tested path as `/api/v1`. Public-auth responses are cached with tags `collection:<data collection>` + `collection:api-endpoints` — both invalidated automatically by the service layer on entry/definition writes. Endpoints are the 10th project artefact type (`apis` in `getArtefactsForProject`; skipped by untag-all since the project IS the URL namespace; a project with endpoints refuses deletion). Admin: **Data → API Builder** (`admin/js/views/api-endpoints.js` list, `api-endpoint-editor.js` builder with try-it console — raw `fetch`, tests the SAVED definition only). Validation refuses system-managed collections (would leak `api-tokens` hashes), duplicate path shapes per project (`/a/:x` ≡ `/a/:y` → 409), and unknown roles/ops. Scaffolder block: `apiEndpoints: [{path, collection, filter, ...}]`, idempotent by path shape. Permission family `api-endpoints.*` — in the base super-admin/admin seeds (boot self-heal); custom roles need a manual grant. Since 0.25.1 an endpoint may only expose collections resolving to **its own project or core** (server 400s cross-project bindings; routes 403 collections outside the caller's scope; the builder's picker filters to match).
+The external surface — `/api/v1/:slug` collection access, project-scoped API tokens, and API Builder
+endpoints at `/api/x/<project><path>` — has its own contracts (strict token auth, project binding,
+read-field allowlists, cross-project refusals). Full detail in the **`domma-api-surface` skill**
+(`.claude/skills/domma-api-surface/SKILL.md`) — load it before touching any of that.

package/admin/dist/domma/domma-tools.css

@@ -1,9 +1,9 @@
 /*!
- * Domma Tools CSS v0.29.3
+ * Domma Tools CSS v0.39.0
  * Dynamic Object Manipulation & Modeling API
  * (c) 2026 Darryl Waterhouse & DCBW-IT
- * Built: 2026-07-01T10:03:02.866Z
- * Commit: 63e2f20
+ * Built: 2026-08-09T13:58:02.916Z
+ * Commit: 757ca75
  */
 
 /*!
@@ -1260,7 +1260,7 @@
     display: flex;
     flex-direction: column;
     height: 100%;
-    background: var(--dm-bg);
+    background: var(--dm-background);
     color: var(--dm-text);
     font-family: var(--dm-font-sans);
     border: 1px solid var(--dm-border);
@@ -1274,7 +1274,7 @@
     justify-content: space-between;
     align-items: center;
     padding: 1rem;
-    background: var(--dm-bg-secondary);
+    background: var(--dm-surface-secondary);
     border-bottom: 1px solid var(--dm-border);
     gap: 1rem;
 }
@@ -1301,7 +1301,7 @@
     padding: 0.5rem;
     border: 1px solid var(--dm-border);
     border-radius: var(--dm-radius-sm);
-    background: var(--dm-bg);
+    background: var(--dm-background);
     color: var(--dm-text);
     font-size: 0.875rem;
     width: 200px;
@@ -1498,7 +1498,7 @@
 
 /* Field Cards */
 .sb-field-card {
-    background: var(--dm-bg-secondary);
+    background: var(--dm-surface-secondary);
     border: 2px solid var(--dm-border);
     border-radius: var(--dm-radius-md);
     padding: 1rem;
@@ -1546,7 +1546,7 @@
 .sb-field-type {
     font-size: 0.75rem;
     color: var(--dm-text-secondary);
-    background: var(--dm-bg);
+    background: var(--dm-background);
     padding: 0.25rem 0.5rem;
     border-radius: var(--dm-radius-sm);
 }
@@ -1583,7 +1583,7 @@
 .sb-field-controls button {
     flex: 1;
     padding: 0.25rem 0.5rem;
-    background: var(--dm-bg);
+    background: var(--dm-background);
     border: 1px solid var(--dm-border);
     border-radius: var(--dm-radius-sm);
     color: var(--dm-text);
@@ -1930,7 +1930,7 @@
     border-left: 1px solid var(--dm-border);
     overflow-y: auto;
     padding: 1rem;
-    background: var(--dm-bg);
+    background: var(--dm-background);
 }
 
 .sb-state-title {
@@ -1946,7 +1946,7 @@
     font-family: var(--dm-font-mono);
     font-size: 0.75rem;
     color: var(--dm-text);
-    background: var(--dm-bg-secondary);
+    background: var(--dm-surface-secondary);
     padding: 0.75rem;
     border-radius: var(--dm-radius-sm);
     overflow-x: auto;
@@ -1970,7 +1970,7 @@
     padding: 0.5rem 1rem;
     border: 1px solid var(--dm-border);
     border-radius: var(--dm-radius-sm);
-    background: var(--dm-bg);
+    background: var(--dm-background);
     color: var(--dm-text);
     cursor: pointer;
     font-size: 0.875rem;
@@ -2180,7 +2180,7 @@
 }
 
 .sb-export-output {
-    background: var(--dm-bg-secondary);
+    background: var(--dm-surface-secondary);
     border: 1px solid var(--dm-border);
     border-radius: var(--dm-radius-md);
     padding: 1rem;
@@ -2203,7 +2203,7 @@
     padding: 1rem;
     border: 1px solid var(--dm-border);
     border-radius: var(--dm-radius-md);
-    background: var(--dm-bg-secondary);
+    background: var(--dm-surface-secondary);
     color: var(--dm-text);
     font-family: var(--dm-font-mono);
     font-size: 0.875rem;
@@ -2228,7 +2228,7 @@
     justify-content: space-between;
     align-items: center;
     padding: 1rem;
-    background: var(--dm-bg-secondary);
+    background: var(--dm-surface-secondary);
     border: 1px solid var(--dm-border);
     border-radius: var(--dm-radius-md);
 }
@@ -2248,7 +2248,7 @@
     padding: 0.75rem;
     border: 1px solid var(--dm-border);
     border-radius: var(--dm-radius-sm);
-    background: var(--dm-bg);
+    background: var(--dm-background);
     color: var(--dm-text);
     font-size: 1rem;
 }