domma-cms 1.6.60 → 1.7.0

package/docs/scaffolding.md

@@ -0,0 +1,312 @@
+# Scaffolding - One-Click CRUD from a Recipe
+
+The CMS ships with **scaffolder recipes**: JSON templates that create a
+working Collection + Form + Actions in one shot. From the page editor's CRUD
+tutorial slideover, click "Apply template" and a complete subsystem is built,
+wired together, and ready to use - including a copy-pastable shortcode you
+can drop into the current page.
+
+This is the difference between "documentation tells you how to build it" and
+"the platform builds it for you, you change the parts that don't fit".
+
+---
+
+## Bundled recipes
+
+| Recipe | What it builds |
+|---|---|
+| **Employee Onboarding** (`onboarding`) | `onboarding` collection (full-name, email, start-date, role, right-to-work file, references, status), `onboarding-form` collecting the same, and three actions for `Pending → Reviewing → Approved/Rejected` with HR email notifications |
+| **Contact list (CRM-lite)** (`contact-list`) | `contacts` collection (name, email, phone, company, tags, notes, status), `contact-quick-add` form, one transition action for "needs follow-up" |
+
+Recipes live in `server/services/recipes/*.json` - add your own with the
+schema below and they appear in the picker automatically.
+
+---
+
+## How to apply a recipe
+
+1. Edit any page in the admin
+2. In the toolbar, click the **📖 CRUD tutorial** button (between sparkles and help-circle)
+3. In the highlighted "Or skip ahead - scaffold a working system in one click" panel, click a template
+4. Edit the slug fields if you want to rename anything, then click **Apply template**
+5. On success, click **Insert into this page** to paste the ready-made shortcode at your cursor
+
+The slideover stays open so you can apply multiple templates without
+navigating away. Each apply is independent.
+
+---
+
+## Recipe format
+
+A recipe is a JSON file with this shape:
+
+```json
+{
+  "slug":        "onboarding",
+  "name":        "Employee Onboarding",
+  "description": "Short blurb shown in the picker",
+  "icon":        "user-plus",
+
+  "options": [
+    { "name": "collectionSlug", "label": "Collection slug", "default": "onboarding",      "hint": "Where records are stored" },
+    { "name": "formSlug",       "label": "Form slug",       "default": "onboarding-form", "hint": "Embed with [form name=\"…\" /]" },
+    { "name": "actionPrefix",   "label": "Action prefix",   "default": "onboarding",      "hint": "Per-action slugs become <prefix>-review, etc." }
+  ],
+
+  "collection": {
+    "title":       "Onboarding",
+    "description": "New-starter records",
+    "fields": [ /* schema fields - text, number, select, multiselect, date, file, reference, etc. */ ],
+    "api":       { /* api.read/create/update/delete gates */ },
+    "rowAccess": { /* per-op row-level access */ }
+  },
+
+  "form": {
+    "title": "Employee Onboarding",
+    "fields": [ /* form fields - usually mirror the collection */ ],
+    "settings": {
+      "submitText":      "Send to HR",
+      "successMessage":  "Thanks - HR will review your details shortly.",
+      "honeypot":        true,
+      "rateLimitPerMinute": 3,
+      "actionSlug":      ""
+    },
+    "actions": {
+      "collection": { "enabled": true, "slug": "" }
+    }
+  },
+
+  "actions": [
+    {
+      "slug":       "{{actionPrefix}}-review",
+      "title":      "Move to reviewing",
+      "collection": "{{collectionSlug}}",
+      "trigger":    { "label": "Mark as reviewing", "icon": "eye", "style": "primary" },
+      "transition": { "field": "status", "from": ["pending"], "to": "reviewing" },
+      "access":     { "roles": ["admin", "super-admin"] },
+      "steps": [
+        { "type": "updateField", "config": { "field": "status", "value": "reviewing" } }
+      ]
+    }
+    /* … more actions … */
+  ],
+
+  "menus": [
+    {
+      "slug":      "{{menuSlug}}",
+      "name":      "Members nav",
+      "items":     [{"text": "Members", "url": "/members"}],
+      "variant":   "default",
+      "position":  "sticky",
+      "locations": ["sidebar"]
+    }
+  ],
+
+  "wireForm": true,
+  "snippet":  "[form name=\"{{formSlug}}\" /]\n\n[collection slug=\"{{collectionSlug}}\" display=\"cards\" searchable transitions /]"
+}
+```
+
+### Option types
+
+Each option may carry a `type`, which decides what happens to a value the
+user supplies:
+
+| `type` | What happens |
+|---|---|
+| `slug` (default when absent) | slugified - lower case, anything other than letters and digits becomes `-` |
+| `email` | trimmed; refused with 400 unless it looks like an address |
+| `password` | kept exactly as typed; never logged or echoed |
+| `text` | trimmed |
+
+Only `slug` options are slugified. The onboarding recipe types `hrEmail` as
+`email` and `hrPassword` as `password` (a seed user's password must be at least
+8 characters), and the Apply template form shows those as email and password
+fields.
+
+### Token substitution
+
+Tokens of the form `{{optionName}}` are substituted with the resolved option
+values throughout the recipe at apply time. Two important exceptions are
+**not** substituted at scaffold time - they're left intact for action
+execution to resolve later:
+
+- `{{entry.…}}` - entry field values at action runtime
+- `{{user.…}}` - executing user at action runtime
+- `{{now}}` and `{{env.CMS_PUBLIC_*}}` - runtime constants
+
+This means an email step like:
+
+```json
+{ "to": "{{entry.data.email}}", "subject": "Welcome, {{entry.data.fullName}}" }
+```
+
+…is preserved as-is in the created action and resolved when the action fires
+against a real entry. The scaffolder only swaps the option-level tokens
+(`{{collectionSlug}}`, `{{formSlug}}`, `{{actionPrefix}}`, etc.).
+
+### `wireForm` + `snippet`
+
+When `wireForm: true` and the recipe has at least one action created, the
+scaffolder sets the form's `settings.actionSlug` to the first created
+action - so submitting the form fires that action automatically.
+
+`snippet` is a Markdown fragment returned to the caller. The tutorial UI
+offers it as a one-click insert at the editor's cursor. It's typically a
+form embed + a collection block so the new system is immediately visible.
+
+### `menus`
+
+Optional `menus` array seeds one or more menus alongside the collection,
+form, and actions - useful when a recipe installs a feature (e.g. a
+members area) that needs its own nav. Each entry has the same shape as a
+`config/menus/<slug>.json` file plus an optional `locations` array of
+slot names to wire the menu into.
+
+Bundled-from-recipe menus are tagged with `meta.bundled: true` and
+`meta.presetOwner: <recipeSlug>` so the admin can identify them. The
+scaffolder pre-flights menu slug conflicts the same way it pre-flights
+collections, forms, and actions. A `force: true` field on a `menus[]`
+entry lets a recipe overwrite an existing slot-to-menu mapping;
+without it, an already-mapped slot logs a warning and the new menu is
+created but left unmapped.
+
+### Recipe `project` block
+
+A recipe may declare an optional `project` block. When present, the
+scaffolder creates a Project record (see `docs/configuration.md` →
+Projects) before any artefact is written, and every artefact produced
+by the recipe is tagged with `meta.project: <namespace>`.
+
+Block shape:
+
+```json
+"project": {
+  "name":        "Members Area",
+  "description": "Members-only zone",
+  "icon":        "users",
+  "rootUrl":     "/{{namespace}}",
+  "sortOrder":   10
+}
+```
+
+Only `name` is required; the other fields mirror the project record schema.
+
+Behaviour:
+
+- **`tokens.namespace` becomes the project slug.** The same option that
+  already cascades into every artefact slug also identifies the project.
+- **Idempotent.** If a project with that slug already exists, it is left
+  alone - re-applying the recipe does not clobber edits made to the project
+  record. If it doesn't exist, it is created.
+- **Every produced artefact gets `meta.project: <namespace>` stamped** -
+  collections, forms, actions, menus, roles and users. API tokens and API
+  endpoints are bound to the project through their own `project` field.
+  (Recipes cannot create blocks, views or pages; tag those with a project in
+  their own editors.)
+- **Seeded users additionally get `projects: ['<namespace>']`** on their
+  access-scope field, so a recipe-seeded user can immediately log in and
+  see only the project they were created for.
+- **Creation failure aborts the apply.** Validation or write errors in the
+  project block fail the whole recipe before any artefact is written.
+
+Example recipe with a project block:
+
+```json
+{
+  "slug":    "members-area",
+  "name":    "Members Area",
+  "options": [{"name": "namespace", "default": "members"}],
+  "project": {
+    "name":        "Members Area",
+    "description": "Members-only zone",
+    "icon":        "users",
+    "rootUrl":     "/{{namespace}}"
+  },
+  "collection": { ... },
+  "form":       { ... },
+  "menus":      [ ... ]
+}
+```
+
+Recipes without a `project` block still work - they produce untagged
+artefacts, which belong to the built-in **core** project by exclusion
+(see `docs/configuration.md` → Projects → The core project).
+
+---
+
+## Conflict handling
+
+The scaffolder pre-flights every target slug (collection, form, each action,
+each menu) and refuses to apply if any already exists. The response includes
+the full conflict list so the user can rename and retry without partial
+creation. The recipe's project is created only after this check passes, so a
+refused apply writes nothing.
+
+```
+HTTP 409
+{
+  "error":     "Cannot apply recipe - conflicts: …",
+  "conflicts": ["Collection \"onboarding\" already exists"]
+}
+```
+
+---
+
+## Actions require MongoDB (Pro)
+
+Collections and Forms are file-based and work in every install. Actions
+require a configured MongoDB connection (the Pro tier). When no MongoDB is
+available the scaffolder still creates the collection and form, then reports
+each action as skipped with the warning:
+
+```
+MongoDB not configured - action "onboarding-review" skipped (Pro feature)
+```
+
+The pieces that did get created are fully functional; you can either
+configure MongoDB and re-apply (with renamed slugs) to add the actions, or
+manage transitions manually via the admin.
+
+---
+
+## API endpoints
+
+| Method | Path | Auth | Description |
+|---|---|---|---|
+| `GET`  | `/api/scaffold/recipes`           | `collections.create` | List bundled recipes |
+| `GET`  | `/api/scaffold/recipes/:slug`     | `collections.create` | Full recipe document |
+| `POST` | `/api/scaffold/apply`              | `collections.create` + what the recipe creates | Apply a recipe; body: `{recipe, options}` |
+
+Apply checks, before it writes anything, that the caller may create every
+kind of thing the recipe will create, and answers 403 naming each missing
+permission (also in `missing`): a new project `projects.create`; new roles and
+user accounts `users.create`; menus `menus.create` (slot mapping
+`menus.update`); a collection or form `collections.create`; actions
+`actions.create`; API tokens `api-tokens.create`; API endpoints
+`api-endpoints.create`. A role the recipe creates must sit below the caller's
+level and grant only permissions the caller holds, and a seeded user's role
+must sit below the caller's level. The level-0 role passes every check.
+
+Apply response:
+
+```json
+{
+  "created":  { "collection": "onboarding", "form": "onboarding-form", "actions": ["onboarding-review", "onboarding-approve", "onboarding-reject"] },
+  "skipped":  [],
+  "warnings": [],
+  "snippet":  "[form name=\"onboarding-form\" /]\n\n[collection slug=\"onboarding\" …]"
+}
+```
+
+---
+
+## Writing your own recipe
+
+Drop a JSON file into `server/services/recipes/` matching the shape above.
+It's picked up automatically on next admin load - no restart needed.
+
+For complex recipes that produce multiple collections (e.g. jobs + applications +
+companies), the current format supports one collection per recipe. The
+roadmap for multi-collection recipes lives under a `collections: [...]` and
+`forms: [...]` array - happy to land that when there's a use case.

package/docs/structure/user-types.md

@@ -0,0 +1,107 @@
+# Roles - Structure Documentation
+
+Roles are the CMS's user types. They control what each user can access and are stored as a **preset Collection**
+(`roles`) so they can be managed from the admin UI without editing config files.
+
+> This page used to describe a `user-types` collection and `server/services/userTypes.js`. Neither exists any more:
+> roles live in the `roles` collection and are served by `server/services/roles.js`. The old Manager, Editor and
+> Subscriber roles were retired - on startup any user still holding one is moved to `user`.
+
+---
+
+## Storage
+
+```
+content/collections/roles/
+├── schema.json   - field definitions (preset - rewritten on every start, do not edit)
+└── data.json     - role entries (edit via System > Roles)
+```
+
+### Schema Fields
+
+| Field | Type | Description |
+|---|---|---|
+| `name` | text | Slug-style role key used in code (e.g. `blog-editor`) |
+| `label` | text | Human-readable display name (e.g. `Blog Editor`) |
+| `level` | number | Seniority - lower = more senior. The Super Admin role is level 0 |
+| `permissions` | multi-select | Resources (`pages`) or single actions (`pages.read`) this role holds |
+| `badgeClass` | select | CSS badge class for UI display |
+| `plugin` | text | Set on roles contributed by a plugin |
+
+Roles may also carry an `admin: {home, allow: [...]}` block that confines holders to certain admin screens (set in the
+role editor's **Admin area**).
+
+### Permissions
+
+Permissions come from the permission registry (`server/services/permissionRegistry.js`, also served at
+`GET /api/auth/permissions-registry`). Each resource has actions - normally `read`, `create`, `update` and `delete`
+(a few differ, for example `theme` is read/update and `seo` is read/manage). A role can hold:
+
+- a bare resource, e.g. `pages` - every action on that resource, or
+- a single action, e.g. `pages.read`.
+
+Core resources are grouped as:
+
+- **Content**: pages, media, blocks, components
+- **Structure**: navigation, menus, context-menus, projects, layouts
+- **Data**: collections, views, actions
+- **Configuration**: users, theme, settings, plugins, notifications, api-tokens, api-endpoints
+- **Tools**: contacts, analytics, seo, notes, todo
+
+Enabled plugins add their own resources on top (declared in `plugin.json` `permissions[]`).
+
+---
+
+## Auth Integration
+
+At server startup `server/services/roles.js` seeds the collection if needed, then reads `data.json` and builds
+in-memory caches:
+
+- **`roleMap`** - `{ roleName: { label, level, badgeClass, admin? } }` - used to validate role claims and compare
+  seniority
+- **`permissionsMap`** - `{ 'resource' | 'resource.action': [roleName, ...] }` - used by `requirePermission()`
+  route preHandlers
+
+A user has one primary `role` plus optional `additionalRoles`. A permission check passes if any of their roles grants
+it; level checks use their most senior role. A level-0 role always holds every permission, including those added
+later by plugins.
+
+### Cache Invalidation
+
+The cache is rebuilt whenever a role entry is created, updated or deleted through the admin (role records are
+read and written through the collections API, `/api/collections/roles/entries`). Changes take effect
+immediately - no server restart required.
+
+---
+
+## Base Roles
+
+Three base roles are seeded on first start and cannot be deleted:
+
+| Name | Label | Level | Permissions |
+|---|---|---|---|
+| `super-admin` | Super Admin | 0 | Everything, including permissions added by plugins |
+| `admin` | Admin | 1 | pages, media, blocks, components, navigation, menus, projects, layouts, collections, views, actions, users, settings, notifications, plugins, api-tokens, api-endpoints, context-menus, theme |
+| `user` | User | 2 | notifications |
+
+On every start, permission families newly shipped in an update are added to the base roles. This is append-only:
+permissions an admin added are kept (and a seeded permission removed from a base role comes back - use a custom role
+to run with less). Custom roles are never touched.
+
+The first account (created by `npm run setup` or the browser setup screen) is a Super Admin.
+
+---
+
+## Adding a New Role
+
+1. Go to **System > Roles**
+2. Click **New role**
+3. Fill in the name (slug), label and level, and tick the permissions this role should have in the permission
+   matrix
+4. Save - the change takes effect immediately
+
+To assign the role, go to **System > Users**, edit the user, and pick it as the primary role or add it as an
+additional role. You can only manage users whose role is less senior (a higher level number) than your own.
+
+Plugins can also ship roles (`roles/*.json` in the plugin, or `hooks.registerRole()`). A plugin role is created once
+and then belongs to the admin: disabling the plugin keeps it, uninstalling removes it.