@pramen/cms 0.0.22 → 0.0.24

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import type { HandlerContext, Policy, FileRef } from "@pramen/server";
+import type { HandlerContext, Policy, FileRef, BootstrapFn } from "@pramen/server";
 /** A field in a block type's (or content type's) field schema. Recursive: a `repeater`
  * or `group` nests `fields`. Mirrors WollyCMS's FieldDefinition. */
 export interface FieldDefinition {
@@ -72,6 +72,44 @@ export declare function defineBlockType<S extends string, F extends readonly Fie
 }): BlockTypeDef<S, F>;
 /** The inferred `fields` type of a `defineBlockType` result. */
 export type BlockFieldsOf<D extends BlockTypeDef> = InferBlockFields<D["fieldsSchema"]>;
+/** A developer-authored content type: a page template. Page-level `fields`, named `regions`
+ * (each with an optional block-type allow-list), and optional `defaultBlocks` scaffolded when
+ * a page of this type is created. Mirror of `BlockTypeDef`; feed to `cmsBootstrap`. */
+export interface ContentTypeDef {
+    readonly slug: string;
+    readonly name: string;
+    readonly description?: string;
+    readonly fields?: readonly FieldDefinition[];
+    readonly regions: readonly RegionDefinition[];
+    readonly defaultBlocks?: readonly DefaultBlockDefinition[];
+}
+/** Declare a content type in code. Spread the result into `cmsBootstrap({ contentTypes })`:
+ *
+ *   const article = defineContentType("article", {
+ *     name: "Article",
+ *     fields: [{ name: "perex", type: "textarea" }, { name: "date", type: "date" }],
+ *     regions: [{ name: "content", allowedTypes: ["rich_text", "image"] }],
+ *   }); */
+export declare function defineContentType(slug: string, opts: {
+    name?: string;
+    description?: string;
+    fields?: readonly FieldDefinition[];
+    regions: readonly RegionDefinition[];
+    defaultBlocks?: readonly DefaultBlockDefinition[];
+}): ContentTypeDef;
+/** Build a pramen `bootstrap` reconciler that upserts code-defined block + content types by
+ * `slug` on each boot. Idempotent: inserts a missing type, updates a drifted one, leaves an
+ * identical one untouched. Register it on your app:
+ *
+ *   export const app = { schema, handlers, acl, tasks,
+ *     bootstrap: [ cmsBootstrap({ blockTypes: [...], contentTypes: [...] }) ] };
+ *
+ * Runs with a privileged system Db, so a fresh/reprovisioned database converges to the
+ * code-declared types with no manual createContentType/createBlockType call. */
+export declare function cmsBootstrap(defs: {
+    blockTypes?: readonly BlockTypeDef[];
+    contentTypes?: readonly ContentTypeDef[];
+}): BootstrapFn;
 /** Emit a `.ts` module of per-slug field interfaces + a `BlockFieldsBySlug` registry from
  * DB-stored block types (`{ slug, fieldsSchema }` rows). The runtime counterpart to the
  * compile-time `InferBlockFields`, for webmaster-authored (data-driven) block types. */
@@ -494,6 +532,9 @@ export interface AssembledPage {
         slug: string;
         status: string;
         locale: string;
+        /** The page's content-type slug (e.g. "article", "page") — lets a frontend route/render
+         * by type. `null` if the type row is missing. */
+        contentType: string | null;
         translationGroupId: string | null;
         /** Published sibling locales of this page (for hreflang alternates). */
         translations: PageTranslation[];
@@ -627,6 +668,7 @@ export declare function createCmsHandlers(opts?: CmsHandlerOpts): {
     listPublishedPages: import("@pramen/server").Handler<unknown, {
         slug: string;
         locale: string;
+        contentType: string | null;
         updatedAt: string;
     }[]>;
     /** Update a page's SEO fields (meta/canonical/robots/OpenGraph/JSON-LD). Editor-gated. */
@@ -880,6 +922,7 @@ export declare const cmsHandlers: {
     listPublishedPages: import("@pramen/server").Handler<unknown, {
         slug: string;
         locale: string;
+        contentType: string | null;
         updatedAt: string;
     }[]>;
     /** Update a page's SEO fields (meta/canonical/robots/OpenGraph/JSON-LD). Editor-gated. */

package/dist/index.js

@@ -40,6 +40,69 @@ import { filterXSS } from "xss";
 export function defineBlockType(slug, fields, opts = {}) {
     return { slug, name: opts.name ?? slug, fieldsSchema: fields, description: opts.description, icon: opts.icon, category: opts.category };
 }
+/** Declare a content type in code. Spread the result into `cmsBootstrap({ contentTypes })`:
+ *
+ *   const article = defineContentType("article", {
+ *     name: "Article",
+ *     fields: [{ name: "perex", type: "textarea" }, { name: "date", type: "date" }],
+ *     regions: [{ name: "content", allowedTypes: ["rich_text", "image"] }],
+ *   }); */
+export function defineContentType(slug, opts) {
+    return { slug, name: opts.name ?? slug, description: opts.description, fields: opts.fields, regions: opts.regions, defaultBlocks: opts.defaultBlocks };
+}
+const sameJson = (a, b) => JSON.stringify(a ?? null) === JSON.stringify(b ?? null);
+/** Insert `values` if no row has this `slug`, else patch only the columns that drifted
+ * (never `id`/`slug`/`createdAt`). Idempotent — an identical definition is a no-op. */
+async function upsertBySlug(db, table, slug, values) {
+    const existing = (await db.find({ from: table, where: { slug }, limit: 1 }))[0];
+    if (!existing) {
+        await db.insert(table, values);
+        return;
+    }
+    const patch = {};
+    for (const [k, v] of Object.entries(values)) {
+        if (k === "slug")
+            continue;
+        if (!sameJson(existing[k], v))
+            patch[k] = v;
+    }
+    if (Object.keys(patch).length)
+        await db.update(table, String(existing.id), patch);
+}
+/** Build a pramen `bootstrap` reconciler that upserts code-defined block + content types by
+ * `slug` on each boot. Idempotent: inserts a missing type, updates a drifted one, leaves an
+ * identical one untouched. Register it on your app:
+ *
+ *   export const app = { schema, handlers, acl, tasks,
+ *     bootstrap: [ cmsBootstrap({ blockTypes: [...], contentTypes: [...] }) ] };
+ *
+ * Runs with a privileged system Db, so a fresh/reprovisioned database converges to the
+ * code-declared types with no manual createContentType/createBlockType call. */
+export function cmsBootstrap(defs) {
+    return async ({ db }) => {
+        const sys = db;
+        for (const bt of defs.blockTypes ?? []) {
+            await upsertBySlug(sys, "cms_block_types", bt.slug, {
+                name: bt.name,
+                slug: bt.slug,
+                description: bt.description ?? null,
+                fieldsSchema: bt.fieldsSchema ?? [],
+                icon: bt.icon ?? null,
+                category: bt.category ?? null,
+            });
+        }
+        for (const ct of defs.contentTypes ?? []) {
+            await upsertBySlug(sys, "cms_content_types", ct.slug, {
+                name: ct.name,
+                slug: ct.slug,
+                description: ct.description ?? null,
+                fieldsSchema: ct.fields ?? [],
+                regions: ct.regions ?? [],
+                defaultBlocks: ct.defaultBlocks ?? [],
+            });
+        }
+    };
+}
 // --- codegen: emit .ts field interfaces from DB-stored block schemas ------------------
 //
 // The data-driven half (webmaster-created block types) has no static type. This is the
@@ -402,6 +465,13 @@ const isEditor = (ctx, roles) => {
 };
 /** Assemble a page LIVE from its placements/blocks/types, grouped by region and ordered
  * by position, merging each shared placement's `overrides` over its block's fields. */
+/** Resolve a page's content-type slug from its `typeId` (null when the type row is gone). */
+async function contentTypeSlug(db, typeId) {
+    if (typeof typeId !== "string" || !typeId)
+        return null;
+    const rows = await db.find({ from: "cms_content_types", where: { id: typeId }, limit: 1 });
+    return rows[0] ? String(rows[0].slug) : null;
+}
 async function assembleLive(db, page) {
     const placements = await db.find({
         from: "cms_page_blocks",
@@ -449,8 +519,8 @@ async function assembleLive(db, page) {
             is_shared: Boolean(m.p.isShared),
         });
     }
-    const [translations, ogImage] = await Promise.all([siblingTranslations(db, page), resolveMediaId(db, page.ogImage)]);
-    return { page: pageMeta(page, translations, ogImage), regions };
+    const [translations, ogImage, contentType] = await Promise.all([siblingTranslations(db, page), resolveMediaId(db, page.ogImage), contentTypeSlug(db, page.typeId)]);
+    return { page: pageMeta(page, translations, ogImage, contentType), regions };
 }
 /** Resolve a single media id to a ResolvedMedia (for og:image etc.), or null. */
 async function resolveMediaId(db, id) {
@@ -496,7 +566,7 @@ async function siblingTranslations(db, page) {
         .map((r) => ({ locale: String(r.locale ?? "en"), slug: String(r.slug) }));
 }
 /** Project a page row to the public AssembledPage.page shape. */
-function pageMeta(page, translations = [], ogImage = null) {
+function pageMeta(page, translations = [], ogImage = null, contentType = null) {
     const metaTitle = page.metaTitle ?? null;
     const metaDescription = page.metaDescription ?? null;
     return {
@@ -505,6 +575,7 @@ function pageMeta(page, translations = [], ogImage = null) {
         slug: String(page.slug),
         status: String(page.status),
         locale: String(page.locale ?? "en"),
+        contentType,
         translationGroupId: page.translationGroupId ?? null,
         translations,
         fields: page.fields ?? null,
@@ -777,8 +848,14 @@ export function createCmsHandlers(opts = {}) {
         /** Public: list published pages (slug, locale, updatedAt) for sitemap generation. The
          * anonymous ACL scopes cms_pages reads to status=published, so this is safe to expose. */
         listPublishedPages: query(async (ctx) => {
-            const rows = await cdb(ctx).find({ from: "cms_pages", where: { status: "published" }, orderBy: { column: "updatedAt", dir: "desc" }, limit: 5000 });
-            return rows.map((r) => ({ slug: String(r.slug), locale: String(r.locale ?? "en"), updatedAt: String(r.updatedAt ?? r.createdAt ?? "") }));
+            const db = cdb(ctx);
+            const rows = await db.find({ from: "cms_pages", where: { status: "published" }, orderBy: { column: "updatedAt", dir: "desc" }, limit: 5000 });
+            // Join typeId → content-type slug so a frontend can route/filter by type (e.g. articles
+            // vs pages) without a second round-trip.
+            const typeIds = [...new Set(rows.map((r) => r.typeId).filter((v) => typeof v === "string"))];
+            const types = typeIds.length ? await db.find({ from: "cms_content_types", where: { id: { in: typeIds } } }) : [];
+            const slugById = new Map(types.map((t) => [String(t.id), String(t.slug)]));
+            return rows.map((r) => ({ slug: String(r.slug), locale: String(r.locale ?? "en"), contentType: slugById.get(String(r.typeId)) ?? null, updatedAt: String(r.updatedAt ?? r.createdAt ?? "") }));
         }),
         /** Update a page's SEO fields (meta/canonical/robots/OpenGraph/JSON-LD). Editor-gated. */
         updatePageSeo: mutation(async (ctx, input) => {
@@ -1346,6 +1423,10 @@ export function cmsPolicies(opts = {}) {
     }
     return {
         public: [
+            // Content-type metadata (slug/name) is public: the content API returns each published
+            // page's content-type slug (via listPublishedPages' live typeId→slug join) so a frontend
+            // can route/render by type. Slugs/names are structural, not sensitive.
+            policy(`${p}:public:content-types:read`, "cms_content_types", "read", allow()),
             // Only published pages are readable; the snapshot carries the content.
             policy(`${p}:public:pages:read`, "cms_pages", "read", { where: { status: "published" } }),
             // getPage reads the latest revision snapshot. Scope the grant by the revision's

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pramen/cms",
-  "version": "0.0.22",
+  "version": "0.0.24",
   "description": "Optional block/page builder for pramen — Drupal-Paragraphs-style typed blocks in named regions, reusable blocks, scheduled publishing, built entirely from pramen primitives.",
   "license": "MIT",
   "repository": {
@@ -41,7 +41,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@pramen/server": "0.0.22",
+    "@pramen/server": "0.0.24",
     "xss": "^1.0.15"
   },
   "peerDependencies": {

package/src/index.ts

@@ -42,7 +42,7 @@ import {
   Forbidden,
   PramenError,
 } from "@pramen/server";
-import type { HandlerContext, Policy, FileRef } from "@pramen/server";
+import type { HandlerContext, Policy, FileRef, BootstrapFn } from "@pramen/server";
 import { filterXSS } from "xss";
 
 // --- field schema DSL (the block-editor field language) ---------------------
@@ -159,6 +159,109 @@ export function defineBlockType<S extends string, F extends readonly FieldDefini
 /** The inferred `fields` type of a `defineBlockType` result. */
 export type BlockFieldsOf<D extends BlockTypeDef> = InferBlockFields<D["fieldsSchema"]>;
 
+// --- code-defined content types + bootstrap reconcile ---------------------------------
+//
+// Block/content types are runtime rows (a webmaster can add one with no deploy), but a repo
+// that hard-depends on a fixed shape (e.g. an Astro site whose build fails unless an
+// `article` type with certain fields exists) wants them CODE-DEFINED and auto-applied. These
+// helpers let you declare types in code and converge them into the store on boot via pramen's
+// `app.bootstrap` — so a fresh / reprovisioned database has them without a manual
+// createContentType/createBlockType call.
+
+/** A developer-authored content type: a page template. Page-level `fields`, named `regions`
+ * (each with an optional block-type allow-list), and optional `defaultBlocks` scaffolded when
+ * a page of this type is created. Mirror of `BlockTypeDef`; feed to `cmsBootstrap`. */
+export interface ContentTypeDef {
+  readonly slug: string;
+  readonly name: string;
+  readonly description?: string;
+  readonly fields?: readonly FieldDefinition[];
+  readonly regions: readonly RegionDefinition[];
+  readonly defaultBlocks?: readonly DefaultBlockDefinition[];
+}
+
+/** Declare a content type in code. Spread the result into `cmsBootstrap({ contentTypes })`:
+ *
+ *   const article = defineContentType("article", {
+ *     name: "Article",
+ *     fields: [{ name: "perex", type: "textarea" }, { name: "date", type: "date" }],
+ *     regions: [{ name: "content", allowedTypes: ["rich_text", "image"] }],
+ *   }); */
+export function defineContentType(
+  slug: string,
+  opts: {
+    name?: string;
+    description?: string;
+    fields?: readonly FieldDefinition[];
+    regions: readonly RegionDefinition[];
+    defaultBlocks?: readonly DefaultBlockDefinition[];
+  },
+): ContentTypeDef {
+  return { slug, name: opts.name ?? slug, description: opts.description, fields: opts.fields, regions: opts.regions, defaultBlocks: opts.defaultBlocks };
+}
+
+/** The narrow slice of the system Db a reconcile needs. `cmsBootstrap` runs with a SYSTEM
+ * Db (ACL bypassed), so these calls are unrestricted; kept loose to avoid threading the
+ * host app's schema generic through a library helper. */
+interface ReconcileDb {
+  find(q: { from: string; where?: Record<string, unknown>; limit?: number }): Promise<Record<string, unknown>[]>;
+  insert(table: string, values: Record<string, unknown>): Promise<unknown>;
+  update(table: string, id: string, patch: Record<string, unknown>): Promise<unknown>;
+}
+
+const sameJson = (a: unknown, b: unknown): boolean => JSON.stringify(a ?? null) === JSON.stringify(b ?? null);
+
+/** Insert `values` if no row has this `slug`, else patch only the columns that drifted
+ * (never `id`/`slug`/`createdAt`). Idempotent — an identical definition is a no-op. */
+async function upsertBySlug(db: ReconcileDb, table: string, slug: string, values: Record<string, unknown>): Promise<void> {
+  const existing = (await db.find({ from: table, where: { slug }, limit: 1 }))[0];
+  if (!existing) {
+    await db.insert(table, values);
+    return;
+  }
+  const patch: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(values)) {
+    if (k === "slug") continue;
+    if (!sameJson(existing[k], v)) patch[k] = v;
+  }
+  if (Object.keys(patch).length) await db.update(table, String(existing.id), patch);
+}
+
+/** Build a pramen `bootstrap` reconciler that upserts code-defined block + content types by
+ * `slug` on each boot. Idempotent: inserts a missing type, updates a drifted one, leaves an
+ * identical one untouched. Register it on your app:
+ *
+ *   export const app = { schema, handlers, acl, tasks,
+ *     bootstrap: [ cmsBootstrap({ blockTypes: [...], contentTypes: [...] }) ] };
+ *
+ * Runs with a privileged system Db, so a fresh/reprovisioned database converges to the
+ * code-declared types with no manual createContentType/createBlockType call. */
+export function cmsBootstrap(defs: { blockTypes?: readonly BlockTypeDef[]; contentTypes?: readonly ContentTypeDef[] }): BootstrapFn {
+  return async ({ db }) => {
+    const sys = db as unknown as ReconcileDb;
+    for (const bt of defs.blockTypes ?? []) {
+      await upsertBySlug(sys, "cms_block_types", bt.slug, {
+        name: bt.name,
+        slug: bt.slug,
+        description: bt.description ?? null,
+        fieldsSchema: bt.fieldsSchema ?? [],
+        icon: bt.icon ?? null,
+        category: bt.category ?? null,
+      });
+    }
+    for (const ct of defs.contentTypes ?? []) {
+      await upsertBySlug(sys, "cms_content_types", ct.slug, {
+        name: ct.name,
+        slug: ct.slug,
+        description: ct.description ?? null,
+        fieldsSchema: ct.fields ?? [],
+        regions: ct.regions ?? [],
+        defaultBlocks: ct.defaultBlocks ?? [],
+      });
+    }
+  };
+}
+
 // --- codegen: emit .ts field interfaces from DB-stored block schemas ------------------
 //
 // The data-driven half (webmaster-created block types) has no static type. This is the
@@ -502,6 +605,9 @@ export interface AssembledPage {
     slug: string;
     status: string;
     locale: string;
+    /** The page's content-type slug (e.g. "article", "page") — lets a frontend route/render
+     * by type. `null` if the type row is missing. */
+    contentType: string | null;
     translationGroupId: string | null;
     /** Published sibling locales of this page (for hreflang alternates). */
     translations: PageTranslation[];
@@ -628,6 +734,13 @@ const isEditor = (ctx: HandlerContext, roles: readonly string[]): boolean => {
 
 /** Assemble a page LIVE from its placements/blocks/types, grouped by region and ordered
  * by position, merging each shared placement's `overrides` over its block's fields. */
+/** Resolve a page's content-type slug from its `typeId` (null when the type row is gone). */
+async function contentTypeSlug(db: CmsDb, typeId: unknown): Promise<string | null> {
+  if (typeof typeId !== "string" || !typeId) return null;
+  const rows = await db.find({ from: "cms_content_types", where: { id: typeId }, limit: 1 });
+  return rows[0] ? String(rows[0].slug) : null;
+}
+
 async function assembleLive(db: CmsDb, page: Record<string, unknown>): Promise<AssembledPage> {
   const placements = await db.find({
     from: "cms_page_blocks",
@@ -676,8 +789,8 @@ async function assembleLive(db: CmsDb, page: Record<string, unknown>): Promise<A
       is_shared: Boolean(m.p.isShared),
     });
   }
-  const [translations, ogImage] = await Promise.all([siblingTranslations(db, page), resolveMediaId(db, page.ogImage)]);
-  return { page: pageMeta(page, translations, ogImage), regions };
+  const [translations, ogImage, contentType] = await Promise.all([siblingTranslations(db, page), resolveMediaId(db, page.ogImage), contentTypeSlug(db, page.typeId)]);
+  return { page: pageMeta(page, translations, ogImage, contentType), regions };
 }
 
 /** Resolve a single media id to a ResolvedMedia (for og:image etc.), or null. */
@@ -723,7 +836,7 @@ async function siblingTranslations(db: CmsDb, page: Record<string, unknown>): Pr
 }
 
 /** Project a page row to the public AssembledPage.page shape. */
-function pageMeta(page: Record<string, unknown>, translations: PageTranslation[] = [], ogImage: ResolvedMedia | null = null): AssembledPage["page"] {
+function pageMeta(page: Record<string, unknown>, translations: PageTranslation[] = [], ogImage: ResolvedMedia | null = null, contentType: string | null = null): AssembledPage["page"] {
   const metaTitle = (page.metaTitle as string | null) ?? null;
   const metaDescription = (page.metaDescription as string | null) ?? null;
   return {
@@ -732,6 +845,7 @@ function pageMeta(page: Record<string, unknown>, translations: PageTranslation[]
     slug: String(page.slug),
     status: String(page.status),
     locale: String(page.locale ?? "en"),
+    contentType,
     translationGroupId: (page.translationGroupId as string | null) ?? null,
     translations,
     fields: (page.fields as Record<string, unknown> | null) ?? null,
@@ -1027,8 +1141,14 @@ export function createCmsHandlers(opts: CmsHandlerOpts = {}) {
     /** Public: list published pages (slug, locale, updatedAt) for sitemap generation. The
      * anonymous ACL scopes cms_pages reads to status=published, so this is safe to expose. */
     listPublishedPages: query(async (ctx) => {
-      const rows = await cdb(ctx).find({ from: "cms_pages", where: { status: "published" }, orderBy: { column: "updatedAt", dir: "desc" }, limit: 5000 });
-      return rows.map((r) => ({ slug: String(r.slug), locale: String(r.locale ?? "en"), updatedAt: String(r.updatedAt ?? r.createdAt ?? "") }));
+      const db = cdb(ctx);
+      const rows = await db.find({ from: "cms_pages", where: { status: "published" }, orderBy: { column: "updatedAt", dir: "desc" }, limit: 5000 });
+      // Join typeId → content-type slug so a frontend can route/filter by type (e.g. articles
+      // vs pages) without a second round-trip.
+      const typeIds = [...new Set(rows.map((r) => r.typeId).filter((v): v is string => typeof v === "string"))];
+      const types = typeIds.length ? await db.find({ from: "cms_content_types", where: { id: { in: typeIds } } }) : [];
+      const slugById = new Map(types.map((t) => [String(t.id), String(t.slug)]));
+      return rows.map((r) => ({ slug: String(r.slug), locale: String(r.locale ?? "en"), contentType: slugById.get(String(r.typeId)) ?? null, updatedAt: String(r.updatedAt ?? r.createdAt ?? "") }));
     }),
 
     /** Update a page's SEO fields (meta/canonical/robots/OpenGraph/JSON-LD). Editor-gated. */
@@ -1578,6 +1698,10 @@ export function cmsPolicies(opts: CmsPolicyOpts = {}): { public: Policy[]; edito
   }
   return {
     public: [
+      // Content-type metadata (slug/name) is public: the content API returns each published
+      // page's content-type slug (via listPublishedPages' live typeId→slug join) so a frontend
+      // can route/render by type. Slugs/names are structural, not sensitive.
+      policy(`${p}:public:content-types:read`, "cms_content_types", "read", allow()),
       // Only published pages are readable; the snapshot carries the content.
       policy(`${p}:public:pages:read`, "cms_pages", "read", { where: { status: "published" } }),
       // getPage reads the latest revision snapshot. Scope the grant by the revision's