@bygghammar/cms-platform 0.20.0 → 0.22.0

package/CHANGELOG.md

@@ -0,0 +1,76 @@
+# Changelog
+
+All notable changes to `@bygghammar/cms-platform`.
+
+The package follows semver with the pre-1.0 convention that a **minor** bump may
+contain breaking changes to shared views, adapters or cores; patch releases are
+always compatible. In addition, `PLATFORM_CONTRACT_VERSION` in
+`platform/contract` is bumped whenever a shared screen starts requiring schema
+or adapter capabilities an older site does not have. Sites assert that constant
+in a test and upgrade deliberately.
+
+## 0.22.0
+
+- Added `docs/NEW-SITE.md`: the supported starter path for a new site (install,
+  contract assertion, migrations, theme, host registration, server cores,
+  backoffice routes, verification).
+- Added this changelog and a written compatibility policy.
+- Added the `cms-platform-migrations` bin, which copies missing canonical
+  migrations into a site's migration directory without overwriting or deleting
+  anything.
+- Removed five Voyara-specific content/data migrations from the canonical set
+  (SEO copy, a homepage block seed, a locale-domain update, a booking-link
+  rewrite and the content seed). Canonical migrations are schema only; site
+  content stays in the site's own migration directory. Existing sites keep
+  those files locally and remain compatible.
+- No runtime source changes; safe upgrade from 0.21.x.
+
+## 0.21.0
+
+- Added `server/forms-core`: host-agnostic forms server rules — effective
+  settings, recipient routing, notification templates, submitter detection,
+  field-removal safety, version snapshots, audit trail and the list/save/delete/
+  restore/purge/duplicate cores plus site defaults, usage and delivery logging.
+
+## 0.20.0
+
+- Added `server/media-usage-core` (usage scan, remote media import, reference
+  rewriting) and completed `server/media-cleanup-core`.
+
+## 0.19.0
+
+- Added `server/guards`, `server/redirects-core` and `server/page-seo-core`.
+
+## 0.18.0
+
+- Extracted `FormEditorView`, `FormsIndexView` and `RedirectsView`.
+
+## 0.17.0
+
+- Extracted the media library UI, including client-side optimisation and usage
+  inspection.
+
+## 0.15.0 – 0.16.0
+
+- Extracted `SectionFormView` and `PageEditorView`.
+
+## 0.14.0
+
+- Expanded the `PlatformData` host contract to every backoffice module and added
+  `assertPlatformData` / `REQUIRED_PLATFORM_DATA`.
+
+## 0.12.0 – 0.13.0
+
+- Extracted `ReviewImageUpload` and `PageSeoPanel`.
+
+## 0.5.0 – 0.11.0
+
+- Phase 1 and 2: pure forms/media/http/i18n helpers, backup core, trips and
+  navigation contracts, and the first host contract.
+- Phase 5 groundwork: canonical migrations shipped under `migrations/` with
+  `SCHEMA_MIGRATIONS` and `PLATFORM_CONTRACT_VERSION`.
+
+## 0.1.0
+
+- First release: blocks, block types, icons, i18n core, UI primitives and the
+  `theme.css` design-token contract.

package/README.md

@@ -18,6 +18,24 @@ future sites). **Code only** — no content, no data, no secrets, no theme.
   active-state helpers. Menu content and visual headers remain per-site.
 - `src/theme.css` — the design-token contract + neutral starter theme
 
+## Starting a new site
+
+`docs/NEW-SITE.md` is the supported starter path: install, assert the contract,
+apply the canonical schema with `bunx cms-platform-migrations`, import
+`theme.css`, register host components / platform data / translations, wrap the
+server cores and mount the shared backoffice views.
+
+## Compatibility policy
+
+- `CHANGELOG.md` records every release; read it before upgrading.
+- Pre-1.0, a **minor** release may break shared views, adapters or cores; patch
+  releases are always compatible.
+- `PLATFORM_CONTRACT_VERSION` (`platform/contract`) is bumped when a shared
+  screen starts requiring schema or adapter capabilities an older site lacks.
+  Sites pin it in a test.
+- `migrations/` is schema only. Site content, SEO copy and seeds never belong
+  there.
+
 ## What must never live here
 
 - colours, fonts or spacing values used by a specific site (see `theme.css`)

package/docs/NEW-SITE.md

@@ -0,0 +1,103 @@
+# Starting a new site on @bygghammar/cms-platform
+
+This is the supported path from an empty TanStack Start project to a working
+CMS site. Every step is code or configuration in the new site; nothing here
+copies content, media or secrets between sites.
+
+## 0. Prerequisites
+
+- TanStack Start v1 (React 19, Vite 7), Tailwind v4, shadcn/ui.
+- A Supabase-compatible backend for the site (its own project/stack — never
+  shared with another site, never a production database during authoring).
+
+## 1. Install
+
+```bash
+bun add @bygghammar/cms-platform@<exact version>
+```
+
+Pin an exact version and commit the lockfile. Read `CHANGELOG.md` before every
+upgrade.
+
+## 2. Assert the contract
+
+```ts
+import {
+  PLATFORM_CONTRACT_VERSION,
+  SCHEMA_MIGRATIONS,
+  assertPlatformContract,
+  missingMigrations,
+} from "@bygghammar/cms-platform/platform/contract";
+```
+
+Add one test that pins the contract version the site was built against and one
+that asserts `missingMigrations(appliedFilenames)` is empty. See
+`tests/platform-contract.test.ts` in any existing site for the exact shape.
+
+## 3. Apply the canonical schema
+
+The package ships the canonical migrations under `migrations/`, oldest first.
+
+```bash
+bunx cms-platform-migrations ./supabase/migrations
+```
+
+The command copies any migration the target directory is missing and never
+overwrites or deletes a file, so it is safe to re-run after an upgrade. Apply
+the copied files with the site's normal migration tooling. Site-specific
+migrations live alongside them with later timestamps and must stay additive.
+
+## 4. Theme
+
+```css
+/* src/styles.css */
+@import "@bygghammar/cms-platform/theme.css";
+```
+
+Then override the design tokens for the new brand in the site's own layer.
+Never edit colours, fonts or spacing inside the package.
+
+## 5. Register the host
+
+Three registrations, all at startup:
+
+- **Host components** — `registerHostComponents()` from
+  `@bygghammar/cms-platform/host` for the site's link, image, video and rich
+  text primitives.
+- **Platform data adapter** — `registerHostPlatform({ data, site })` from
+  `@bygghammar/cms-platform/platform`. `data` implements every member in
+  `REQUIRED_PLATFORM_DATA` (pages, versions, global sections, media, SEO,
+  redirects, forms); `site` describes name, `backofficeBasePath` and locales.
+  Guard it with a test that calls `assertPlatformData`.
+- **Translations** — the site's own `sv`/`en` maps via the i18n register
+  module. Translation data is content and stays in the site.
+
+## 6. Server functions
+
+Wrap the shared server cores in the site's own `createServerFn` files:
+
+| Package core | Purpose |
+| --- | --- |
+| `server/guards` | `assertStaff`, `assertSuperadmin` |
+| `server/forms-core` | form definitions, versions, settings, delivery log |
+| `server/redirects-core` | path normalisation and redirect writes |
+| `server/page-seo-core` | slug conflicts and slug-change 301s |
+| `server/media-usage-core` | usage scan and remote import |
+| `server/media-cleanup-core` | duplicate/rename planning and apply |
+
+The site supplies clients, storage and page-key → path maps; the package owns
+the rules. Keep privileged clients inside handlers.
+
+## 7. Backoffice routes
+
+Each backoffice route is a thin adapter around the package view
+(`PageEditorView`, `MediaLibraryView`, `FormEditorView`, `FormsIndexView`,
+`RedirectsView`, `SectionFormView`, `PageSeoPanel`). Routes own the path and
+auth gate only.
+
+## 8. Verify
+
+1. Types pass.
+2. Full test suite passes, including the contract tests from step 2.
+3. `/` renders.
+4. The backoffice signs in, and one page, one form and one media asset save.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bygghammar/cms-platform",
-  "version": "0.20.0",
+  "version": "0.22.0",
   "description": "Shared CMS platform: blocks, block types, i18n core, UI primitives and design-token contract used by every Bygghammar/Voyara site.",
   "type": "module",
   "sideEffects": false,
@@ -10,7 +10,10 @@
   },
   "files": [
     "README.md",
+    "CHANGELOG.md",
+    "docs",
     "migrations",
+    "scripts",
     "src"
   ],
   "repository": {
@@ -108,7 +111,8 @@
     "./server/redirects-core": "./src/server/redirects-core.ts",
     "./server/page-seo-core": "./src/server/page-seo-core.ts",
     "./server/media-cleanup-core": "./src/server/media-cleanup-core.ts",
-    "./server/media-usage-core": "./src/server/media-usage-core.ts"
+    "./server/media-usage-core": "./src/server/media-usage-core.ts",
+    "./server/forms-core": "./src/server/forms-core.ts"
   },
   "dependencies": {
     "fflate": "^0.8.3"
@@ -180,5 +184,8 @@
     "@tiptap/extension-table": {
       "optional": true
     }
+  },
+  "bin": {
+    "cms-platform-migrations": "scripts/sync-migrations.mjs"
   }
-}
+}

package/scripts/sync-migrations.mjs

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+/**
+ * Copy canonical platform migrations into a site's migration directory.
+ *
+ * Additive only: a file that already exists in the target is left untouched and
+ * nothing is ever deleted or overwritten, so this is safe to re-run after an
+ * upgrade.
+ *
+ * Usage: cms-platform-migrations [targetDir] [--check]
+ *   targetDir defaults to ./supabase/migrations
+ *   --check exits non-zero when files are missing instead of copying them
+ */
+import { copyFileSync, existsSync, mkdirSync, readdirSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const source = resolve(here, "..", "migrations");
+
+const args = process.argv.slice(2);
+const checkOnly = args.includes("--check");
+const target = resolve(args.find((a) => !a.startsWith("--")) ?? "supabase/migrations");
+
+if (!existsSync(source)) {
+  console.error(`No migrations directory in the package at ${source}`);
+  process.exit(1);
+}
+
+const canonical = readdirSync(source)
+  .filter((f) => f.endsWith(".sql"))
+  .sort();
+
+const present = new Set(existsSync(target) ? readdirSync(target) : []);
+const missing = canonical.filter((f) => !present.has(f));
+
+if (missing.length === 0) {
+  console.log(`Up to date: ${canonical.length} canonical migrations already present.`);
+  process.exit(0);
+}
+
+if (checkOnly) {
+  console.error(`Missing ${missing.length} canonical migrations:`);
+  for (const f of missing) console.error(`  ${f}`);
+  process.exit(1);
+}
+
+mkdirSync(target, { recursive: true });
+for (const f of missing) copyFileSync(join(source, f), join(target, f));
+console.log(`Copied ${missing.length} migration(s) into ${target}. Apply them with your migration tooling.`);

package/src/platform/contract.ts

@@ -67,12 +67,7 @@ export const SCHEMA_MIGRATIONS: readonly string[] = [
   "20260803201518_6e8a6028-b70f-4a7d-8bc9-95c86304e7ae.sql",
   "20260803201535_32a9a213-cb92-4035-b8cd-8211ca34af68.sql",
   "20260811103505_29df753d-14fa-4a05-8fea-f4207785fba3.sql",
-  "20260811112455_217c4028-f587-4c98-9e4f-9e6c452ab761.sql",
-  "20260811114438_6687d67d-bad3-4803-9638-8b7670d2e5d4.sql",
   "20260811130318_7cb95e95-9baa-40af-8f3f-de1d4e09cec4.sql",
-  "20260811220548_80d99ec2-bd4b-475d-a627-9408bb60ce56.sql",
-  "20260811222519_6b040f56-4de3-49e0-92e4-d9deec5ead6a.sql",
-  "20260812000000_seed_voyara_content.sql",
   "20260818040722_1bdf1b8f-7fb0-4ae8-8ecf-73f1fadff3c2.sql",
   "20260818040808_69a5e832-57e8-4aa7-aff8-7fd7777faa7c.sql",
   "20260818040839_e6523163-bbf5-4a39-9233-91759059569a.sql",