domma-cms 1.6.60 → 1.7.0

package/docs/plans/2026-06-10-core-project-design.md

@@ -0,0 +1,240 @@
+# Core Project - Design Document
+
+**Date:** 2026-06-10
+**Status:** Implemented (2026-06-10)
+**Approach:** Core by exclusion - a seeded, protected `core` project that owns every artefact not claimed by another project. No stamping, no data migration.
+
+---
+
+## Overview
+
+Every site gains a built-in **Core** project representing the core site itself. All
+artefacts that are not attached to another project belong to Core - by **resolution
+fallback**, not by tagging. The Core project record is seeded at boot (create-if-absent),
+cannot be deleted, and its slug/rootUrl are locked.
+
+This completes the Projects model: "untagged" stops being a half-state that means both
+"site-wide" and "the main site". Instead, the main site has a real identity - a sidebar
+entry, an overview page with artefact counts, and per-type filtered lists - exactly like
+any scaffolded project.
+
+### Why fallback, not stamping
+
+The obvious implementation (write `meta.project: 'core'` onto every existing artefact and
+every initial artefact at site generation) was considered and rejected:
+
+1. **Access-control regression.** `canSeeArtefact()` treats untagged artefacts as visible
+   to *everyone*, including scoped users. A recipe-seeded user with
+   `projects: ['onboarding']` currently sees the navbar menu, the site pages, and shared
+   blocks because they are untagged. Stamping them `core` would hide all of it from every
+   scoped user on every site, on upgrade day.
+2. **Migration burden.** Stamping requires rewriting page frontmatter, menu/form/block/
+   collection meta, and a guarded one-shot migration per site - and only fixes the past.
+   Any artefact created later without a tag (plugins, API clients, hand-edited files)
+   becomes a stray again.
+3. **Fallback fixes the invariant.** "Not in another project ⇒ in Core" holds forever,
+   for past and future artefacts, with zero data rewrites. The retrofit to existing sites
+   is simply the CMS update itself.
+
+---
+
+## Data Model
+
+### Seeded record
+
+`content/collections/projects/data.json` gains one seeded entry:
+
+```json
+{
+    "slug":        "core",
+    "name":        "Core",
+    "description": "The core site - everything not assigned to another project.",
+    "icon":        "home",
+    "rootUrl":     "/",
+    "sortOrder":   -1,
+    "protected":   true
+}
+```
+
+- **Locked fields:** `slug` (already immutable), `rootUrl`, `protected`.
+- **Editable fields:** `name`, `description`, `icon`, `sortOrder`.
+- `sortOrder: -1` pins Core first in the sidebar by default; admins may re-order.
+- `rootUrl: '/'` is **descriptive only** - resolution does not depend on it (see below).
+  `validateProject()` currently rejects `rootUrl === '/'`; the rule is relaxed to allow
+  it for the `core` slug only.
+
+### Constant + display flag
+
+Enforcement follows the `BASE_ROLE_NAMES` precedent in `roles.js`:
+
+```js
+// server/services/projects.js
+export const CORE_PROJECT_SLUG = 'core';
+```
+
+The constant is the enforcement mechanism (guards compare against it); the
+`protected: true` field on the record is a display hint so the admin UI never hardcodes
+the slug. The projects preset schema in `presetCollections.js` gains a
+`protected` (boolean, default `false`) field.
+
+---
+
+## Seeding
+
+A new `seedCoreProject()` in `server/services/projects.js`, called from `server.js`
+immediately after `presetCollections.seedAll()`:
+
+1. List projects; if any entry has `slug === 'core'` → **adopt**: ensure
+   `protected: true` is set, leave all other fields untouched (a pre-existing user-created
+   "core" project keeps its name/icon/rootUrl - resolution does not depend on them).
+2. Otherwise → create the seeded record above.
+
+Idempotent and record-level (checks for the slug, **not** for `data.json` existence -
+`seedAll()` already creates an empty `data.json`, and retrofitted sites have existing
+project entries that must be preserved).
+
+This single hook is the entire retrofit: every existing site gets Core on first boot
+after upgrading. No per-site scripts, no `.bak` files. Fleet sites that predate Projects
+entirely (e.g. older deployments) retrofit by upgrading to current - same path.
+
+---
+
+## Resolution Changes (`server/services/projects.js`)
+
+### Pages - `getProjectForPage(urlPath, explicitProject)`
+
+| Rule | Before | After |
+|---|---|---|
+| `project: null` in frontmatter | `null` (untagged opt-out) | `'core'` - opt-out is meaningless once Core owns the floor; treated as core and deprecated in docs |
+| `project: '<slug>'` | use it | unchanged |
+| Missing field, prefix match | longest `rootUrl` prefix wins | unchanged - scaffolded projects keep winning (their rootUrls are longer than nothing) |
+| Missing field, no match | `null` | `'core'` |
+
+Implementation: the matcher loop is untouched; the final return becomes
+`return best ?? CORE_PROJECT_SLUG`. Core deliberately does **not** participate in prefix
+matching - `startsWith(rootUrl + '/')` with `rootUrl: '/'` would test `startsWith('//')`
+and match nothing anyway. Fallback is both simpler and correct.
+
+Safety: if the core record is somehow absent (mid-boot, hand-deleted data file), return
+`null` as before; the next boot re-seeds.
+
+### Non-page artefacts
+
+A small helper, used everywhere a project grouping is displayed or enumerated:
+
+```js
+export function resolveArtefactProject(artefact) {
+    return artefact?.meta?.project || CORE_PROJECT_SLUG;
+}
+```
+
+`getArtefactsForProject(slug)` switches its eight `meta.project === slug` comparisons to
+`resolveArtefactProject(x) === slug`. The pages branch already works unchanged (it calls
+`getProjectForPage`, which now falls back to core). Net effect:
+`getArtefactsForProject('core')` enumerates everything unclaimed - the "Core site"
+overview - and other projects' results are byte-identical to today.
+
+### Access control - explicitly unchanged
+
+`canSeeArtefact()` gains one clause and **no semantic change** for existing data:
+
+```js
+const project = artefact?.meta?.project;
+if (!project || project === CORE_PROJECT_SLUG) return true;
+```
+
+**Core is an organisational bucket, never an access boundary.** Untagged artefacts and
+explicitly-`core`-tagged artefacts are visible to all authenticated users, exactly as
+untagged is today. Scoped users keep their navbar, site pages, and shared blocks.
+"Core-only" user scoping is out of scope for this design; `projects: []` (no restriction)
+remains the way to express it. If Core ever needs to be restrictable, that is a separate
+design with real consequences (every scoped recipe user would lose the public site).
+
+`listProjectsForUser()` always includes Core for any authenticated caller (consistency:
+if `canSeeArtefact` says yes to core artefacts, the project list says yes to the
+project). Consequence: the Projects sidebar section - currently hidden when the list is
+empty - now renders on **every** site, with at least Core in it. This is the desired
+headline behaviour.
+
+---
+
+## Protection (delete / update / untag)
+
+Guards at both layers, following the roles precedent (`Cannot remove built-in role`):
+
+| Operation | Service (`projects.js`) | Route (`routes/api/projects.js`) |
+|---|---|---|
+| `DELETE /projects/core` | `deleteProject()` throws `Cannot delete the core project` | 403 **before** the artefact-count enumeration (don't waste the scan; the existing 409-when-tagged guard does not protect core because untag-all is an escape hatch) |
+| `POST /projects/core/untag-all` | `untagAllForProject()` throws | 403 - meaningless for core: resolution re-claims everything instantly |
+| `PUT /projects/core` | `updateProject()` rejects changes to `rootUrl` and `protected`; accepts `name`, `description`, `icon`, `sortOrder` | 400 with field-specific message |
+
+Note the interaction with **other** projects' untag-all: artefacts untagged from any
+project now land in Core (previously "untagged"). Same data state, new label - the word
+"untagged" disappears from UI language in favour of "Core".
+
+---
+
+## Scaffolder & Site Generation
+
+**No scaffolder changes.** Recipes with a `project` block keep creating their project and
+stamping `meta.project: '<namespace>'` exactly as today; their longer `rootUrl` prefixes
+keep winning page resolution over the core fallback. Recipe-seeded users
+(`projects: ['<namespace>']`) continue to see core artefacts via the access rule above.
+
+**No site-generation changes.** `npx` generation, the Domma CMS Manager, payment-flow
+provisioning, and injection all produce untagged initial artefacts as today - boot
+seeding plus resolution fallback files them under Core automatically. `scripts/setup.js`,
+`scripts/reset.js`, `scripts/fresh.js` are untouched (reset wipes content; the next boot
+re-seeds Core).
+
+---
+
+## Admin UI (`admin/` - upstream-replaced, ships with the CMS release)
+
+| View | Change |
+|---|---|
+| `views/projects.js` (list) | Render a "System" badge on `protected: true` rows; hide the delete button |
+| `views/project-settings.js` | When `protected`: disable the Root URL input, hide the danger zone (untag-all + delete) entirely |
+| `views/project-detail.js` | No change - counts come from `GET /projects/:slug/artefacts`, which now resolves correctly for core |
+| Sidebar Projects section | No code change needed; it now always renders because the list is never empty |
+| Quick-create under Core | Omit the `meta.project` stamp (artefacts stay in the natural default state, which *is* Core); an explicit `'core'` tag is treated identically if one is ever written |
+
+---
+
+## Tests
+
+- **Seeding:** creates core when absent; idempotent on re-boot; adopts a pre-existing
+  `core` slug without clobbering fields; survives alongside existing project entries.
+- **Resolution:** `getProjectForPage('/about', undefined)` → `'core'`;
+  `project: null` → `'core'`; longest-prefix project still beats core;
+  `resolveArtefactProject({})` → `'core'`.
+- **Enumeration:** `getArtefactsForProject('core')` counts untagged artefacts of all nine
+  types; other projects' counts unchanged (regression guard).
+- **Access:** extend `tests/services/projects-scope.test.js` - scoped user sees
+  core-resolved and explicitly-core-tagged artefacts; `listProjectsForUser` includes core
+  for scoped users.
+- **Protection:** service throws on delete/untag-all of core; routes return 403; update
+  rejects `rootUrl`/`protected` changes but accepts `name`/`icon`.
+
+---
+
+## Task Breakdown
+
+| # | Task | Files | Size |
+|---|---|---|---|
+| 1 | `CORE_PROJECT_SLUG`, `resolveArtefactProject()`, `seedCoreProject()`, fallback in `getProjectForPage`, resolution scan in `getArtefactsForProject`, guards in `deleteProject`/`updateProject`/`untagAllForProject`, `canSeeArtefact` clause, `listProjectsForUser` inclusion, relax `validateProject` for core's `/` | `server/services/projects.js` | ~50 lines |
+| 2 | `protected` field on projects preset schema | `server/services/presetCollections.js` | ~2 lines |
+| 3 | Call `seedCoreProject()` at boot after `seedAll()` | `server/server.js` | ~3 lines |
+| 4 | 403 guards on DELETE and untag-all; PUT field rejection passthrough | `server/routes/api/projects.js` | ~15 lines |
+| 5 | System badge, hidden delete, locked settings fields | `admin/js/views/projects.js`, `project-settings.js` | ~25 lines |
+| 6 | Tests per section above | `tests/services/`, `tests/routes/` | ~150 lines |
+| 7 | Docs: CLAUDE.md Projects section, `docs/configuration.md`, `docs/scaffolding.md` - document core-by-exclusion, deprecate `project: null` | docs | - |
+
+---
+
+## Out of Scope / Future
+
+- **Core as an access boundary** - deliberately excluded; see Access control section.
+- **Per-service `untagAllForProject` plumbing for pages/roles/users** - pre-existing
+  deferral, unaffected by this design.
+- **Renaming "untagged" UI strings** beyond the projects views - sweep opportunistically.