@pramen/cms 0.0.50 → 0.0.52

package/README.md

@@ -467,6 +467,61 @@ index is what turns a concurrent duplicate into a visible failure instead of a s
 ambiguous history. For the same reason the delete-and-purge pair is atomic on the DO but not
 on D1.
 
+### Locales
+
+A deployment declares the locales it publishes in, and the editor renders its i18n surface
+off that — the Translations panel, the Locale field, the per-row locale column:
+
+```ts
+const handlers = { ...createCmsHandlers({ locales: ["cs", "en"] }), ... };
+```
+
+One locale (or none declared) means monolingual: no i18n chrome anywhere, and the editor
+stops sending `locale` on a page save at all, so nothing can blind-overwrite a field it no
+longer shows. The FIRST entry is the locale a page is stamped with when created without
+one — derived, not a second `defaultLocale` option, because two settings that can disagree
+about the same fact is how a Czech-only site ends up publishing `en`.
+
+Declared, not inferred from the data: the only way to create a second locale is
+`createTranslation`, which the editor exposes from inside the Translations panel — so a rule
+like "show i18n once a second locale exists" would mean a monolingual site could never
+become multilingual. `listCmsCapabilities` is what the editor reads; `listLocales` remains a
+DATA query (which locales are actually authored), and the two differ while a locale is
+declared but not yet used.
+
+### Which store: D1 or the Durable Object
+
+For a CMS behind a site, **D1 is usually the right store** — and it is the only one that
+lets the CMS live inside an Astro site's own Worker, because D1 is a binding while a
+Durable Object has to be exported from the worker entry.
+
+What you give up, and it is worth knowing before you pick:
+
+- **No atomic multi-statement mutations.** D1 has no interactive transactions, so
+  `transaction(fn)` runs `fn` as-is: a mutation that throws midway keeps what it already
+  wrote. Single-statement writes are still atomic. The Worker logs a specific error naming
+  the handler and how many statements had committed, so a partial write is diagnosable
+  rather than looking like an ordinary 500. Where the CMS does several writes in one
+  mutation — a revision plus the row it belongs to, a delete plus its revision purge — the
+  order is chosen so a failure leaves a benign state, but it is not a rollback.
+- **No live queries.** Those need the Durable Object's socket host. The editor does not use
+  them, so this only matters if your own frontend subscribes.
+- **Scheduled publish needs a Cron trigger.** There is no DO alarm to self-drain the outbox,
+  so a delayed task runs only when a Cron trigger calls `createPramen().scheduled`:
+
+  ```jsonc
+  "triggers": { "crons": ["* * * * *"] }
+  ```
+
+  Forget it and a scheduled publish simply never fires. The Worker now notices — when a
+  request-tail drain leaves a task queued for the future and no Cron drain has ever run, it
+  logs once naming the fix, and stops as soon as a Cron drain is seen.
+- **One shared database, no tenant column.** A non-`main` tenant on D1 is refused unless you
+  set `PRAMEN_D1_ALLOW_MULTITENANT=true`, because the rows would commingle.
+
+Pick the Durable Object store when a mutation must be atomic, when you want live queries, or
+when tenants must be isolated by construction.
+
 ## Limitations
 
 - **Block `fields` are opaque JSON**, so pramen's row/cell-level ACL and relational queries

package/dist/index.d.ts

@@ -791,8 +791,19 @@ export interface CmsHandlerOpts {
     editorRoles?: readonly string[];
     /** Max accepted media upload size in bytes (enforced at the Worker). Default 25 MB. */
     mediaMaxSize?: number;
-    /** Default locale used when `getPage`/`createPage` omit one. Default `"en"`. */
-    defaultLocale?: string;
+    /** The locales this deployment publishes in, most-preferred first. Default `["en"]`.
+     *
+     * DECLARED, not inferred. The editor renders its i18n surface — the Translations panel,
+     * the Locale field, the per-row locale column — only when there is more than one, and
+     * `listCmsCapabilities` is how it finds out. Inferring "is this site multilingual?" from
+     * the locales PRESENT IN DATA cannot work: the only way to create a second locale is
+     * `createTranslation`, which the editor exposes from inside the very panel that would
+     * stay hidden, so a monolingual site could never become multilingual.
+     *
+     * The first entry is the default stamped on a page created without one, which is why
+     * `defaultLocale` is derived from this rather than configured beside it — two options
+     * that can disagree about the same fact is how a Czech-only site ends up stamping "en". */
+    locales?: readonly string[];
     /** Roles permitted to approve/reject a page in review and publish (the editorial gate).
      * Default `["reviewer", "admin"]`. */
     reviewerRoles?: readonly string[];
@@ -897,6 +908,20 @@ export declare function createCmsHandlers(opts?: CmsHandlerOpts): {
         ok: true;
     }>;
     listContentTypes: import("@pramen/server").Handler<unknown, Record<string, unknown>[]>;
+    /** Content-type slugs + names, PUBLIC. The editor-facing `listContentTypes` above is
+     * viewer-gated, which a BUILD cannot satisfy: `@pramen/cms-astro`'s `collections: "auto"`
+     * runs in `astro:config:setup`, where there is no editor session and shipping a token to
+     * CI just to list type names would be the wrong trade.
+     *
+     * Nothing new is exposed. `cmsPolicies().public` already grants anonymous read of
+     * `cms_content_types` ("slugs/names are structural, not sensitive"), and
+     * `listPublishedPages` already returns the content-type slug of every published page.
+     * The projection is deliberately narrow — slug and name only, never the regions or
+     * field schema, which describe the editing surface rather than the published site. */
+    listPublicContentTypes: import("@pramen/server").Handler<unknown, {
+        slug: string;
+        name: string;
+    }[]>;
     getContentType: import("@pramen/server").Handler<{
         id: string;
     }, Record<string, unknown>>;
@@ -960,7 +985,21 @@ export declare function createCmsHandlers(opts?: CmsHandlerOpts): {
         title: string;
         status: string;
     }[]>;
-    /** Distinct locales present across all pages. */
+    /** What this deployment supports, for an editor to render against — the pages-side
+     * counterpart to `listCollections`' `supports: [...]`.
+     *
+     * The editor asks the SERVER what exists rather than being told by its own /config.js:
+     * a client flag can hide a control but cannot make the data right, and the two drift
+     * the moment someone adds a locale. `multilingual` is the derived answer to the only
+     * question the UI actually asks, so each surface doesn't re-derive it from the list. */
+    listCmsCapabilities: import("@pramen/server").Handler<unknown, {
+        locales: string[];
+        defaultLocale: string;
+        multilingual: boolean;
+    }>;
+    /** Distinct locales present across all pages. NOTE: a DATA query — what is in the
+     * store — not configuration. `listCmsCapabilities().locales` is what the deployment
+     * declares; these two differ while a locale is declared but not yet authored. */
     listLocales: import("@pramen/server").Handler<unknown, string[]>;
     /** Create a block instance and place it into a page region in one call (the common
      * editor action). Validates the fields against the block type's schema and the region
@@ -1237,6 +1276,20 @@ export declare const cmsHandlers: {
         ok: true;
     }>;
     listContentTypes: import("@pramen/server").Handler<unknown, Record<string, unknown>[]>;
+    /** Content-type slugs + names, PUBLIC. The editor-facing `listContentTypes` above is
+     * viewer-gated, which a BUILD cannot satisfy: `@pramen/cms-astro`'s `collections: "auto"`
+     * runs in `astro:config:setup`, where there is no editor session and shipping a token to
+     * CI just to list type names would be the wrong trade.
+     *
+     * Nothing new is exposed. `cmsPolicies().public` already grants anonymous read of
+     * `cms_content_types` ("slugs/names are structural, not sensitive"), and
+     * `listPublishedPages` already returns the content-type slug of every published page.
+     * The projection is deliberately narrow — slug and name only, never the regions or
+     * field schema, which describe the editing surface rather than the published site. */
+    listPublicContentTypes: import("@pramen/server").Handler<unknown, {
+        slug: string;
+        name: string;
+    }[]>;
     getContentType: import("@pramen/server").Handler<{
         id: string;
     }, Record<string, unknown>>;
@@ -1300,7 +1353,21 @@ export declare const cmsHandlers: {
         title: string;
         status: string;
     }[]>;
-    /** Distinct locales present across all pages. */
+    /** What this deployment supports, for an editor to render against — the pages-side
+     * counterpart to `listCollections`' `supports: [...]`.
+     *
+     * The editor asks the SERVER what exists rather than being told by its own /config.js:
+     * a client flag can hide a control but cannot make the data right, and the two drift
+     * the moment someone adds a locale. `multilingual` is the derived answer to the only
+     * question the UI actually asks, so each surface doesn't re-derive it from the list. */
+    listCmsCapabilities: import("@pramen/server").Handler<unknown, {
+        locales: string[];
+        defaultLocale: string;
+        multilingual: boolean;
+    }>;
+    /** Distinct locales present across all pages. NOTE: a DATA query — what is in the
+     * store — not configuration. `listCmsCapabilities().locales` is what the deployment
+     * declares; these two differ while a locale is declared but not yet authored. */
     listLocales: import("@pramen/server").Handler<unknown, string[]>;
     /** Create a block instance and place it into a page region in one call (the common
      * editor action). Validates the fields against the block type's schema and the region

package/dist/index.js

@@ -959,7 +959,8 @@ export function createCmsHandlers(opts = {}) {
     const editorRoles = opts.editorRoles ?? ["editor", "admin"];
     const editor = { auth: editorRoles };
     const mediaMaxSize = opts.mediaMaxSize ?? 25_000_000;
-    const defaultLocale = opts.defaultLocale ?? "en";
+    const locales = opts.locales && opts.locales.length > 0 ? [...opts.locales] : ["en"];
+    const defaultLocale = locales[0];
     const reviewerRoles = opts.reviewerRoles ?? ["reviewer", "admin"];
     const reviewer = { auth: reviewerRoles };
     const previewTtl = opts.previewTtlSeconds ?? DEFAULT_PREVIEW_TTL_SECONDS;
@@ -1272,6 +1273,20 @@ export function createCmsHandlers(opts = {}) {
             return { ok: true };
         }, { ...reviewer, ...mediaIdInput }),
         listContentTypes: query((ctx) => cdb(ctx).find({ from: "cms_content_types", orderBy: { column: "name" } }), viewer),
+        /** Content-type slugs + names, PUBLIC. The editor-facing `listContentTypes` above is
+         * viewer-gated, which a BUILD cannot satisfy: `@pramen/cms-astro`'s `collections: "auto"`
+         * runs in `astro:config:setup`, where there is no editor session and shipping a token to
+         * CI just to list type names would be the wrong trade.
+         *
+         * Nothing new is exposed. `cmsPolicies().public` already grants anonymous read of
+         * `cms_content_types` ("slugs/names are structural, not sensitive"), and
+         * `listPublishedPages` already returns the content-type slug of every published page.
+         * The projection is deliberately narrow — slug and name only, never the regions or
+         * field schema, which describe the editing surface rather than the published site. */
+        listPublicContentTypes: query(async (ctx) => {
+            const rows = await cdb(ctx).find({ from: "cms_content_types", orderBy: { column: "name" } });
+            return rows.map((r) => ({ slug: String(r.slug), name: String(r.name ?? r.slug) }));
+        }),
         getContentType: query(async (ctx, input) => {
             const rows = await cdb(ctx).find({ from: "cms_content_types", where: { id: input.id }, limit: 1 });
             return rows[0] ?? null;
@@ -1499,7 +1514,17 @@ export function createCmsHandlers(opts = {}) {
                 return o;
             },
         }),
-        /** Distinct locales present across all pages. */
+        /** What this deployment supports, for an editor to render against — the pages-side
+         * counterpart to `listCollections`' `supports: [...]`.
+         *
+         * The editor asks the SERVER what exists rather than being told by its own /config.js:
+         * a client flag can hide a control but cannot make the data right, and the two drift
+         * the moment someone adds a locale. `multilingual` is the derived answer to the only
+         * question the UI actually asks, so each surface doesn't re-derive it from the list. */
+        listCmsCapabilities: query(() => ({ locales, defaultLocale, multilingual: locales.length > 1 }), viewer),
+        /** Distinct locales present across all pages. NOTE: a DATA query — what is in the
+         * store — not configuration. `listCmsCapabilities().locales` is what the deployment
+         * declares; these two differ while a locale is declared but not yet authored. */
         listLocales: query(async (ctx) => {
             // Raw exec bypasses the ACL, so the trash filter has to be written out by hand —
             // otherwise the editor's locale switcher offers a locale with zero live pages.
@@ -1872,8 +1897,6 @@ export function createCmsHandlers(opts = {}) {
             // has no notion of `x-pramen-store`. Minting on the D1 store therefore produces a
             // link that 404s forever while the editor reports success — refuse instead of
             // handing out a token that cannot work.
-            if (ctx.store === "d1")
-                throw new PramenError("page preview is not available on the D1 store (redemption requires the Durable Object)", 503, "unavailable");
             const db = cdb(ctx);
             // Read the page through the ACL first: minting a link is granting access to it, so a
             // caller who cannot read the page must not be able to mint a link that can.
@@ -2948,12 +2971,6 @@ export function createCollectionHandlers(collections, opts = {}) {
             const secret = previewSecret(ctx.env);
             if (!secret)
                 throw previewUnconfigured(); // fail closed — never mint a forgeable link
-            // Redemption always reaches a Durable Object (callPrivileged -> PRAMEN.get) and has no
-            // notion of `x-pramen-store`, so a link minted on D1 would 404 forever while the
-            // editor reported success.
-            if (ctx.store === "d1") {
-                throw new PramenError("collection preview is not available on the D1 store (redemption requires the Durable Object)", 503, "unavailable");
-            }
             const row = await loadRow(cdb(ctx), c, input.id);
             const ttl = Math.max(60, Math.min(input.expiresIn ?? previewTtl, 30 * 24 * 3600));
             const exp = Math.floor(Date.now() / 1000) + ttl;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pramen/cms",
-  "version": "0.0.50",
+  "version": "0.0.52",
   "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.50"
+    "@pramen/server": "0.0.52"
   },
   "peerDependencies": {
     "react": ">=18"

package/src/index.ts

@@ -1379,8 +1379,19 @@ export interface CmsHandlerOpts {
   editorRoles?: readonly string[];
   /** Max accepted media upload size in bytes (enforced at the Worker). Default 25 MB. */
   mediaMaxSize?: number;
-  /** Default locale used when `getPage`/`createPage` omit one. Default `"en"`. */
-  defaultLocale?: string;
+  /** The locales this deployment publishes in, most-preferred first. Default `["en"]`.
+   *
+   * DECLARED, not inferred. The editor renders its i18n surface — the Translations panel,
+   * the Locale field, the per-row locale column — only when there is more than one, and
+   * `listCmsCapabilities` is how it finds out. Inferring "is this site multilingual?" from
+   * the locales PRESENT IN DATA cannot work: the only way to create a second locale is
+   * `createTranslation`, which the editor exposes from inside the very panel that would
+   * stay hidden, so a monolingual site could never become multilingual.
+   *
+   * The first entry is the default stamped on a page created without one, which is why
+   * `defaultLocale` is derived from this rather than configured beside it — two options
+   * that can disagree about the same fact is how a Czech-only site ends up stamping "en". */
+  locales?: readonly string[];
   /** Roles permitted to approve/reject a page in review and publish (the editorial gate).
    * Default `["reviewer", "admin"]`. */
   reviewerRoles?: readonly string[];
@@ -1398,7 +1409,8 @@ export function createCmsHandlers(opts: CmsHandlerOpts = {}) {
   const editorRoles = opts.editorRoles ?? ["editor", "admin"];
   const editor = { auth: editorRoles };
   const mediaMaxSize = opts.mediaMaxSize ?? 25_000_000;
-  const defaultLocale = opts.defaultLocale ?? "en";
+  const locales = opts.locales && opts.locales.length > 0 ? [...opts.locales] : ["en"];
+  const defaultLocale = locales[0]!;
   const reviewerRoles = opts.reviewerRoles ?? ["reviewer", "admin"];
   const reviewer = { auth: reviewerRoles };
   const previewTtl = opts.previewTtlSeconds ?? DEFAULT_PREVIEW_TTL_SECONDS;
@@ -1712,6 +1724,21 @@ export function createCmsHandlers(opts: CmsHandlerOpts = {}) {
 
     listContentTypes: query((ctx) => cdb(ctx).find({ from: "cms_content_types", orderBy: { column: "name" } }), viewer),
 
+    /** Content-type slugs + names, PUBLIC. The editor-facing `listContentTypes` above is
+     * viewer-gated, which a BUILD cannot satisfy: `@pramen/cms-astro`'s `collections: "auto"`
+     * runs in `astro:config:setup`, where there is no editor session and shipping a token to
+     * CI just to list type names would be the wrong trade.
+     *
+     * Nothing new is exposed. `cmsPolicies().public` already grants anonymous read of
+     * `cms_content_types` ("slugs/names are structural, not sensitive"), and
+     * `listPublishedPages` already returns the content-type slug of every published page.
+     * The projection is deliberately narrow — slug and name only, never the regions or
+     * field schema, which describe the editing surface rather than the published site. */
+    listPublicContentTypes: query(async (ctx) => {
+      const rows = await cdb(ctx).find({ from: "cms_content_types", orderBy: { column: "name" } });
+      return rows.map((r) => ({ slug: String(r.slug), name: String(r.name ?? r.slug) }));
+    }),
+
     getContentType: query(async (ctx, input: { id: string }) => {
       const rows = await cdb(ctx).find({ from: "cms_content_types", where: { id: input.id }, limit: 1 });
       return rows[0] ?? null;
@@ -1932,7 +1959,18 @@ export function createCmsHandlers(opts: CmsHandlerOpts = {}) {
       },
     }),
 
-    /** Distinct locales present across all pages. */
+    /** What this deployment supports, for an editor to render against — the pages-side
+     * counterpart to `listCollections`' `supports: [...]`.
+     *
+     * The editor asks the SERVER what exists rather than being told by its own /config.js:
+     * a client flag can hide a control but cannot make the data right, and the two drift
+     * the moment someone adds a locale. `multilingual` is the derived answer to the only
+     * question the UI actually asks, so each surface doesn't re-derive it from the list. */
+    listCmsCapabilities: query(() => ({ locales, defaultLocale, multilingual: locales.length > 1 }), viewer),
+
+    /** Distinct locales present across all pages. NOTE: a DATA query — what is in the
+     * store — not configuration. `listCmsCapabilities().locales` is what the deployment
+     * declares; these two differ while a locale is declared but not yet authored. */
     listLocales: query(async (ctx) => {
       // Raw exec bypasses the ACL, so the trash filter has to be written out by hand —
       // otherwise the editor's locale switcher offers a locale with zero live pages.
@@ -2291,7 +2329,7 @@ export function createCmsHandlers(opts: CmsHandlerOpts = {}) {
       // has no notion of `x-pramen-store`. Minting on the D1 store therefore produces a
       // link that 404s forever while the editor reports success — refuse instead of
       // handing out a token that cannot work.
-      if (ctx.store === "d1") throw new PramenError("page preview is not available on the D1 store (redemption requires the Durable Object)", 503, "unavailable");
+
       const db = cdb(ctx);
       // Read the page through the ACL first: minting a link is granting access to it, so a
       // caller who cannot read the page must not be able to mint a link that can.
@@ -3538,12 +3576,6 @@ export function createCollectionHandlers(collections: readonly CollectionDef[],
       needs(c, "preview");
       const secret = previewSecret(ctx.env);
       if (!secret) throw previewUnconfigured(); // fail closed — never mint a forgeable link
-      // Redemption always reaches a Durable Object (callPrivileged -> PRAMEN.get) and has no
-      // notion of `x-pramen-store`, so a link minted on D1 would 404 forever while the
-      // editor reported success.
-      if (ctx.store === "d1") {
-        throw new PramenError("collection preview is not available on the D1 store (redemption requires the Durable Object)", 503, "unavailable");
-      }
       const row = await loadRow(cdb(ctx), c, input.id);
       const ttl = Math.max(60, Math.min(input.expiresIn ?? previewTtl, 30 * 24 * 3600));
       const exp = Math.floor(Date.now() / 1000) + ttl;