@pramen/cms 0.0.48 → 0.0.50

package/README.md

@@ -124,6 +124,130 @@ Editor flow: `createBlockType` → `createContentType` → `createPage` → `add
 `publishPage`. Public: `getPage({ slug })` returns the published snapshot; editors pass
 `{ slug, preview: true }` to assemble the live draft.
 
+### Preview links
+
+`{ preview: true }` is a **role** check, so it only serves people who have an editor
+account. The person preview actually exists for — the stakeholder reviewing copy before it
+ships — usually has no account at all. For them, mint a signed link:
+
+```ts
+const { url, expiresAt } = await client.call("signPagePreview", { pageId, expiresIn: 3600 });
+// -> { url: "/cms/preview?token=…", expiresAt }
+```
+
+Minting is editor-gated; **redeeming needs no session** — the signature is the
+authorization. Spread `cmsRoutes()` into `app.routes` to serve `GET /cms/preview`, which
+verifies the token in the Worker before any read and returns the live draft with
+`isPreview: true` and `Cache-Control: private, no-store`.
+
+If you pass custom roles to `createCmsHandlers`, hand `cmsRoutes` the **same options
+object** — it derives the route's identity from them, so the two cannot drift:
+
+```ts
+const cms = { editorRoles: ["editor"], reviewerRoles: ["reviewer"] };
+const handlers = { ...createCmsHandlers(cms) };
+const routes = [...cmsRoutes({ handlers: cms })];
+```
+
+That identity must also be granted by your ACL. Preview is **DO-only**: redemption reaches
+the Durable Object, so `signPagePreview` refuses on the D1 store rather than mint a link
+that could never be redeemed.
+
+The grant is scoped to **one page** and carries its own expiry (default 1 hour, clamped to
+30 days), so a leaked link is not "see all drafts" and stops working on its own. Signing
+uses `PREVIEW_SECRET`, falling back to `FILES_SECRET` then `AUTH_SECRET` — the same
+machinery as signed file urls. With no usable secret (≥16 chars) minting and verification
+both **fail closed** rather than hand out forgeable links.
+
+From an Astro site, `createCmsClient(...).getPreview(token)` redeems one.
+
+### Typed block fields
+
+A developer-authored block type gets compile-time typing with no build step —
+`defineBlockType(slug, fields as const)` plus `BlockFieldsOf<typeof def>`.
+
+Webmaster-authored types are **data** (rows in `cms_block_types`, added with no deploy), so
+they can't be typed at compile time. Read them back out of a running instance instead:
+
+```bash
+bunx pramen-cms types --url https://cms.example.workers.dev --tenant acme --out src/cms.gen.ts
+```
+
+Run it with **bun** (`bunx`), like the `pramen` bin — both ship extensionless ESM imports
+that plain Node won't resolve. Its own bin rather than a `pramen` subcommand, because
+`@pramen/cms` is optional and the runtime CLI shouldn't carry a command named after it.
+
+That writes an interface per block-type slug plus a `BlockFieldsBySlug` registry. With no
+`--out` it prints, so it composes with a pipe. Re-run it after a webmaster adds or changes
+a block type.
+
+### Trash (soft delete)
+
+`deletePage` and `deleteMedia` are **soft**: the row stays and `deletedAt` is stamped.
+Filtering lives in the ACL, not in each handler — a read scope is AND-merged into every
+`ctx.db` read, so one policy hides a trashed row from the public content API, the editor,
+`listPublishedPages`/the sitemap, relation traversals and eager-loads at once.
+
+| Handler | Role | Effect |
+| --- | --- | --- |
+| `deletePage` / `deleteMedia` | editor | stamp `deletedAt` — reversible |
+| `listTrash` | editor / reviewer | what is currently trashed — `{ pages, media }` |
+| `restorePage` / `restoreMedia` | editor | clear `deletedAt` |
+| `purgePage` / `purgeMedia` | reviewer | permanent — row, placements, revisions, audit, R2 object |
+
+Two caveats about doing it in the ACL:
+
+- **Policies are OR-unioned.** If your app adds its own `allow()` policy on `cms_pages` or
+  `cms_media` alongside `cmsPolicies().editor`, that grant unions the trash filter away and
+  trashed rows become visible again. Scope your own grants with `deletedAt: { isNull: true }`.
+- **The task context bypasses the ACL entirely** (it runs SYSTEM-scoped), so scheduled
+  publish/unpublish are not protected by the read scope. `deletePage` clears `scheduledAt`
+  and `unpublishAt` for exactly this reason — without that, a page trashed before its
+  scheduled time came back publicly live.
+
+Two things worth knowing:
+
+- **A trashed page keeps its slug.** `(slug, locale)` is a DB unique index, so the
+  alternative was mangling the stored slug on delete. Creating a page over a trashed slug
+  fails with a message saying so; purging frees it.
+- **Trashing media keeps the R2 object.** Dropping the bytes would make `restoreMedia` a
+  lie, and a block still referencing the id would render a dead url. `purgeMedia` removes
+  both.
+
+### Concurrent edits
+
+`cms_pages` and `cms_blocks` carry a `version` that bumps on every edit. Pass the version
+you read back as `expectedVersion` and a stale write is refused with **409 conflict**
+instead of silently overwriting whoever saved first:
+
+```ts
+const { page: current } = await client.call("getPage", { slug, preview: true });
+const { page: saved } = await client.call("updatePage", {
+  pageId: current.id,
+  title,
+  expectedVersion: current.version,
+});
+// 409: "this page was changed by someone else (you have version 3, current is 4)"
+```
+
+The DO is a single writer, so writes already serialize — but *editors* don't. Without this,
+two people on the same page meant last-save-wins with no signal to the loser.
+
+`expectedVersion` is **optional**: omit it and you get the previous last-write-wins
+behaviour. `updatePage` and `updatePageSeo` share the page's version line, so a body edit
+and an SEO edit conflict with each other; blocks version independently.
+
+Structural operations (`addBlock`, `removeBlock`, `reorderRegion`) are not guarded — they
+are additive and already ordered by the single writer.
+
+`version` is returned on `AssembledPage.page` and on every `RenderedBlock`, so the value to
+echo back comes from the same read that loaded the content — including the public
+(snapshot) path, where it is backfilled from the live row rather than the baked snapshot.
+
+On the **D1 store** (`x-pramen-store: d1`) there is no interactive transaction, so two
+requests in the same millisecond can both read the same version and both write. The guard
+still catches the editor race it exists for; it is not a hard mutex there.
+
 ### Rendering (headless)
 
 The backend never dictates markup. `@pramen/cms/react` maps a block's `block_type` slug to
@@ -133,7 +257,7 @@ a component you provide:
 import { RegionRenderer } from "@pramen/cms/react";
 import { useLiveQuery } from "@pramen/react";
 
-const components = { hero: Hero, rich_text: RichText };
+const components = { hero: Hero, rich_text: RichTextBlock };
 function Page({ slug }: { slug: string }) {
   const { data } = useLiveQuery(client, "getPage", { slug });
   if (!data) return null;
@@ -141,6 +265,208 @@ function Page({ slug }: { slug: string }) {
 }
 ```
 
+A `richtext` field is a **document tree**, not an HTML string — render it with
+`RichTextRenderer`, which walks the tree into real elements (no `dangerouslySetInnerHTML`,
+nothing to sanitize at render time):
+
+```tsx
+import { RichTextRenderer } from "@pramen/cms/react";
+
+const RichTextBlock = ({ fields }) => <RichTextRenderer value={fields.body} />;
+```
+
+Pass `components` to override any node type (`paragraph`, `heading`, `link`, …) with your
+own element. `richTextToPlainText(doc)` flattens a document for excerpts and meta
+descriptions.
+
+Writes are checked against a structural allow-list (`normalizeRichText`): an unknown node
+or mark type is dropped, only declared attributes survive, and a `link` href must pass a
+scheme check — so a hand-crafted payload can't smuggle markup past the editor. Widen or
+narrow the vocabulary with `createCmsHandlers({ richTextSchema })` (also accepted by
+`createCollectionHandlers`) when your editor adds TipTap extensions.
+
+Opening a page in the editor **migrates** any legacy HTML rich text on it: each field
+converts to a document on mount and the ordinary autosave persists it. That conversion is
+lossy for anything the editor's extension set doesn't model (an `h4` clamps to `h3`;
+`sub`/`sup`/`ins` flatten), so convert deliberately if that matters.
+
+Heading levels are 1–3 by default, matching the shipped editor's StarterKit config — raise
+`richTextSchema.maxHeadingLevel` if your editor is configured for more. Out-of-range levels
+are **clamped**, not dropped: a level-less heading would render as `h1` in the editor and
+`h2` on the site — TipTap silently
+demotes an unknown level on parse, so permitting more meant an imported `h4` opened as `h1`
+and the next autosave persisted that.
+
+Both renderers re-check a link's href rather than trusting the stored document: the write
+path normalizes, but a row written by your own mutation, a bootstrap seed or an import
+script never passed through it, and the renderer is what puts it on a page.
+
+### Collection workflow (`supports`)
+
+A **collection** points the editor at one of your own pramen entities. By default it is
+plain CRUD — no notion of published. `supports` opts it into the page-style workflow:
+
+```ts
+const talks = collection("talks", {
+  entity: "talks",
+  label: "Talk",
+  supports: ["drafts", "scheduling", "revisions", "preview"],
+  fields: [
+    { name: "title", type: "text", required: true },
+    { name: "speaker", type: "text" },
+  ],
+});
+```
+
+Each feature is backed by **managed columns on your entity** — you declare the columns, the
+CMS owns their values:
+
+| Feature | Columns you add | Handlers you get |
+| --- | --- | --- |
+| `drafts` | `status` | `collectionPublish` / `collectionUnpublish` |
+| `scheduling` | `publishedAt`, `scheduledAt`, `unpublishAt` | `collectionSchedule` (needs `drafts`) |
+| `revisions` | — (uses `cms_collection_revisions`) | `collectionListRevisions` / `collectionRestoreRevision` |
+| `preview` | — | `signCollectionPreview` (needs `drafts`) |
+
+The editor renders the matching controls on a collection row — Publish / Unpublish, a
+schedule picker, a preview link, and a restorable revision list — driven entirely by
+`supports`, so a plain CRUD collection shows none of them.
+
+```ts
+talks: Entity((t) => ({
+  id: primaryKey(generated(t.uuid())),
+  title: t.text(),
+  status: defaultTo(t.text(), "draft"),   // managed
+  publishedAt: t.text(),                  // managed
+  scheduledAt: t.text(),                  // managed
+  unpublishAt: t.text(),                  // managed
+  createdAt: defaultTo(t.text(), expr.now()),
+})),
+```
+
+Wire all three pieces — the handlers need your `schema`, and **scheduling silently never
+fires without the tasks**:
+
+```ts
+const handlers = { ...cmsHandlers, ...createCollectionHandlers(collections, { schema }) };
+const tasks    = { ...cmsTasks,    ...createCollectionTasks(collections) };
+const acl = [
+  role("anonymous", [...cmsPolicies().public, ...collectionPublicPolicies(collections)]),
+  role("editor",    [...cmsPolicies().editor, ...collectionPolicies(collections)]),
+  // a reviewer previews collection rows, so it needs the collection grants too —
+  // `getCollectionPreview` is gated with editorRoles ∪ reviewerRoles:
+  role("reviewer",  [...cmsPolicies({ prefix: "cms-rev" }).editor,
+                     ...collectionPolicies(collections, { prefix: "cms-rev" })]),
+  // …and EVERY other role that should see published content:
+  role("user",      [...cmsPolicies({ prefix: "cms-user" }).public,
+                     ...collectionPublicPolicies(collections, { prefix: "cms-user" })]),
+];
+```
+
+> **`anonymous` is not "everyone".** pramen assigns that role only to callers with **no
+> verified token**, so granting public reads there alone means a **logged-in** user is
+> denied content a logged-**out** visitor can read — a public list handler returns rows to a
+> guest and 403s for a member. There is no implicit everyone-role: spread the public grants
+> into each role that should have them (distinct `prefix` per role keeps the policy names
+> unique).
+
+**A managed column is never in the write whitelist.** `fields` is the whitelist, so a
+`status` entry there would let any editor send `values: { status: "published" }` through
+`collectionUpdate` and skip the publish gate entirely. Declaring one is a **boot error**.
+
+`createCollectionHandlers` **requires your `schema`** and validates the whole registry
+against it at startup, naming the collection and the column, rather than failing on the
+first call months later. It refuses:
+
+- a managed column that is missing, `notNull()`, `hidden()`, not `t.text()`, or also
+  declared as an editable field — a name check alone left "the CMS owns these values"
+  resting on a convention, and every wrong declaration failed *silently* (a `t.json()`
+  `status` stores `"\"published\""`, so the row is invisible forever while Publish reports
+  success);
+- a declared field that is not a column on the entity, or whose type cannot live in that
+  column (`richtext`/`group`/`repeater` need `t.json()`) — otherwise the first write fails
+  with a raw driver message and no HTTP status;
+- an `idField` that is not the entity's primary key, an `orderBy` over a missing column
+  (SQLite resolves the quoted name to a *constant* and sorts every row equal — no error),
+  an entity outside the default partition (every handler dispatches there), an unknown
+  feature, and `scheduling`/`preview` without `drafts`;
+- **two collections over the same entity.** The ACL keys policies by `(role, entity,
+  action)` and OR-merges them, so a second collection does not add a second view — it
+  *widens* the first one's read scope.
+
+All of this now applies to a collection with no `supports` too: it is column-mapped just
+the same.
+
+`collectionPublicPolicies` is the **actual access boundary**, not a UI filter — it is
+AND-merged into every `ctx.db` read of the entity, so an unpublished row is invisible to
+your public queries, relation traversals and eager-loads alike. With `scheduling` it scopes
+to:
+
+```
+status = 'published'
+  AND (publishedAt IS NULL OR publishedAt <= $now())
+  AND (unpublishAt IS NULL OR unpublishAt > $now())
+```
+
+Both time clauses matter. `{ publishedAt: { isNull: false } }` matches a *future* timestamp,
+so a row scheduled for next week would be public the moment it was saved. And the
+`unpublishAt` clause means a scheduled **takedown** is enforced by the read itself, not only
+by the task — if `createCollectionTasks` was never wired or the outbox drain is stuck, the
+row still stops being readable at its instant. That is the direction where failing open is
+worst.
+
+`publishedAt IS NULL` counts as published: a row seeded by `cmsBootstrap`, imported, or
+published while the collection was still `supports: ["drafts"]` has no stamp, and
+`NULL <= '2026-…'` is NULL — so requiring the comparison alone emptied a whole public site
+the moment `scheduling` was added to an existing collection. NULL cannot mean "scheduled for
+later": `publishedAt` is managed (never client-writable) and only ever takes *now* or null,
+while a row awaiting a scheduled publish is `status: 'draft'` with the instant in
+`scheduledAt`.
+
+The grant is restricted to **the declared fields, the id, `status`, and (with `scheduling`)
+`publishedAt`**. An entity column that is not in `fields` — an `internalNote`, a
+`reviewerEmail` — stays private even on a published row, so adding one later doesn't quietly
+publish it. `publishedAt` is in because a caller may not `orderBy` a column it cannot read,
+and "newest published first" is the public query: excluding it 403'd anonymous while working
+for an editor. The forward-looking `scheduledAt` / `unpublishAt` stay out — "this comes down
+on Friday" is not public.
+
+Your public read then stays an ordinary list — see `publicLectures` in `example/app.ts`.
+
+Managed timestamps are minted as ISO-8601 UTC (`2026-08-20T12:00:00.000Z`) in exactly one
+place, because the scope compares against `$now()` **lexicographically**. This is what
+closes the trap the old `publish` field type carried, where `publish` and `datetime` wrote
+different formats into the same TEXT column and sorted against each other as if hours apart.
+
+Revisions snapshot the row's state **before** each content write — an edit, and a restore
+itself — so a restore is a plain reversal that replays through the same whitelist rather
+than resurrecting a column the collection no longer owns.
+
+The snapshot is taken through the raw path, so **history does not depend on who made the
+edit**: an editor whose read policy withholds a column would otherwise have silently dropped
+it from the snapshot, and every later "restore to before that edit" would restore an
+incomplete row. Reading history is projected the other way — `collectionListRevisions`
+narrows each snapshot to the fields *that* caller may read on the entity, and
+`collectionRestoreRevision` writes back exactly that set. Field-level read policies hold
+through history; what you can see is what you can put back.
+Publish and unpublish write **no** revision: they change no content, so the entry would be
+identical to the edit before it and restoring it would do nothing visible.
+
+Ordering is by a monotonic per-row `revision` counter, never a timestamp — a revision is
+written on every edit, and two writes land in the same millisecond often enough that
+"restore the previous version" would otherwise be a coin flip.
+
+`collectionDelete` **purges** the row's revisions. A collection PK can be a caller-chosen
+`textId`, so an id can come back; inherited history would let an editor restore a deleted
+row's content over the new one.
+
+Ordering is backed by a composite `unique` on `(collection, rowId, revision)`. The
+read-then-increment is serialized by the DO's single writer, but **on the D1 store it is
+not** — `D1Driver.transaction` is a no-op, since D1 has no interactive transactions — so the
+index is what turns a concurrent duplicate into a visible failure instead of a silently
+ambiguous history. For the same reason the delete-and-purge pair is atomic on the DO but not
+on D1.
+
 ## Limitations
 
 - **Block `fields` are opaque JSON**, so pramen's row/cell-level ACL and relational queries
@@ -165,4 +491,41 @@ function Page({ slug }: { slug: string }) {
   matches (so a reschedule, a manual publish/unpublish, or a duplicate delivery makes a
   stale task a no-op). The `cms:publish` task is not transactional (the interactive
   `publishPage` is), so a crash mid-task self-heals on the next at-least-once redelivery.
+- **Collections have no trash.** `supports` covers drafts/scheduling/revisions/preview;
+  `collectionDelete` is a hard delete and also purges the row's revisions. Soft delete is
+  `cms_pages`-only.
+- **Listing revisions is gated by the row's read scope**, so a *deleted* row's history is
+  unreachable through `collectionListRevisions` (it is purged on delete anyway).
+- **`drafts` gates VISIBILITY, not content.** A collection is column-mapped: the public
+  reads the entity's own columns, so there is nowhere to stage an unpublished *version* of a
+  live row. An edit to a published row — and a `collectionRestoreRevision` on one — goes
+  live immediately, and `preview` on a published row shows what the public already sees.
+  This is the one place collections do NOT reach page parity: `getPage` serves a baked
+  revision snapshot, which is what lets a page hold unreviewed edits back. Unpublish first
+  if an edit needs review. (Staging content would mean the public read stopped being a query
+  over your entity, which is the entire point of a collection.)
+- **`collectionSchedule` patches the takedown, it doesn't reset it.** Omitting `unpublishAt`
+  leaves an existing one standing (so moving a publish date doesn't silently revoke a
+  scheduled removal); pass `unpublishAt: null` to cancel one deliberately. The new publish
+  instant is checked against the takedown *already stored*, not just one sent in the same
+  call — a reschedule cannot slide the publish past a pending takedown (which would fire
+  first, cancel itself, and leave the row public forever).
+- **A schedule converges, in any drain order.** The tasks are at-least-once and can drain
+  arbitrarily late. The publish task therefore resolves to the state the schedule implies at
+  drain time: if the takedown instant has also passed by then, the row lands **down**, with
+  both tokens spent — it does not publish and discard the takedown. The takedown task
+  likewise clears the pending publish token, so a retried or late publish cannot resurrect
+  the row.
+- **An interactive publish is different from the scheduled one**: `collectionPublish` clears
+  a takedown instant that has already passed and puts the row live, because a person with
+  publish rights is saying "live, now" about a takedown that has already been served. A
+  *future* takedown always stands.
+- **Scheduling a future publish does not take a live row down.** `collectionSchedule` sets
+  `scheduledAt` and leaves `status`/`publishedAt` alone (parity with `schedulePage`), so
+  scheduling a *published* row means it stays public until the task re-stamps it. Unpublish
+  first if you meant "not live until then". Doing this implicitly would be a takedown the
+  editor never asked for, which is why it isn't automatic — but the editor UI should make
+  the current state obvious.
+- **A collection's `supports` features are per-row, not per-locale** — there is no
+  translation-group equivalent for collections.
 - **Duplicate slugs surface as 500, not 409** (a framework-wide limitation, not CMS-specific).

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+export {};

package/dist/cli.js

@@ -0,0 +1,138 @@
+#!/usr/bin/env bun
+// @pramen/cms CLI — ships as the `pramen-cms` bin.
+//
+//   pramen-cms help
+//   pramen-cms types [--tenant t] [--url u] [--token jwt] [--out path]
+//
+// A separate bin from `pramen` on purpose: @pramen/cms is optional, so the runtime CLI
+// should not carry a command named after it. `pramen` knows about schemas, tokens and
+// scaffolding; this knows about content types. Both mint their dev token with the same
+// `signDevToken` from @pramen/server, so there is one signer, not two.
+//
+// Bun shebang, matching the `pramen` bin: the built dist/ uses extensionless ESM imports.
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { signDevToken } from "@pramen/server/dev";
+import { generateBlockTypes } from "./index";
+const argv = process.argv.slice(2);
+const KNOWN_FLAGS = ["url", "tenant", "token", "out"];
+/** Read `--name value` or `--name=value`.
+ *
+ * Both forms, because `--out=path` silently printed to stdout and exited 0 — a green
+ * regenerate-and-diff CI with no file written. And a value is required, because `--out`
+ * with an empty $OUT did the same, while `--tenant --out x` set the tenant to "--out". */
+function flag(name) {
+    const eq = argv.find((a) => a.startsWith(`--${name}=`));
+    if (eq !== undefined) {
+        const v = eq.slice(name.length + 3);
+        if (v === "")
+            fail(`--${name} needs a value`);
+        return v;
+    }
+    const i = argv.indexOf(`--${name}`);
+    if (i < 0)
+        return undefined;
+    const v = argv[i + 1];
+    if (v === undefined || v.startsWith("--"))
+        fail(`--${name} needs a value`);
+    return v;
+}
+/** Reject a misspelled flag rather than silently ignoring it and using the default. */
+function assertKnownFlags() {
+    for (const a of argv) {
+        if (!a.startsWith("--"))
+            continue;
+        const name = a.slice(2).split("=")[0];
+        if (!KNOWN_FLAGS.includes(name)) {
+            fail(`unknown flag --${name} (expected ${KNOWN_FLAGS.map((f) => `--${f}`).join(", ")})`);
+        }
+    }
+}
+function fail(msg) {
+    console.error(`pramen-cms: ${msg}`);
+    process.exit(1);
+    throw new Error(msg); // unreachable — process.exit is typed as returning
+}
+const HELP = `pramen-cms — CLI for @pramen/cms
+
+Usage: pramen-cms <command>
+
+  help                      show this help
+  types                     generate TS interfaces for a tenant's block types
+                            [--tenant t] [--url u] [--token jwt] [--out path]
+
+Block types are DATA — rows a webmaster adds with no deploy — so their shape is only
+knowable from a running instance. \`types\` reads them from one and emits an interface per
+slug plus a BlockFieldsBySlug registry. With no --out it prints.`;
+async function typesCmd() {
+    assertKnownFlags();
+    // Read every flag BEFORE the network call, so a malformed invocation fails on the
+    // invocation rather than on whatever the fetch happens to do first.
+    const url = flag("url") ?? "http://localhost:8787";
+    const tenant = flag("tenant") ?? "main";
+    const dest = flag("out");
+    const token = flag("token") ?? (await signDevToken({ sub: "cli", roles: ["admin"] }));
+    let res;
+    try {
+        res = await fetch(`${url}/rpc/listBlockTypes`, {
+            method: "POST",
+            headers: { "content-type": "application/json", "x-pramen-tenant": tenant, authorization: `Bearer ${token}` },
+            body: "{}",
+        });
+    }
+    catch (e) {
+        // A wrong --url is the common mistake; surface it as a CLI error, not a stack trace.
+        fail(`types: cannot reach ${url} (${e instanceof Error ? e.message : String(e)})`);
+    }
+    const body = (await res.json().catch(() => ({})));
+    if (!res.ok || body.ok !== true || !Array.isArray(body.result)) {
+        fail(`types: listBlockTypes failed (${body.error ?? res.status})`);
+    }
+    const rows = body.result;
+    // Refuse rather than write an empty module. A --tenant typo routes to a fresh Durable
+    // Object whose cms_block_types is legitimately empty, so this is the likely cause — and
+    // exiting 0 after clobbering src/cms.gen.ts would sail through a regenerate-and-diff CI.
+    if (rows.length === 0) {
+        fail(`types: tenant '${tenant}' has no block types — refusing to write an empty module (check --tenant/--url)`);
+    }
+    let out;
+    try {
+        out = generateBlockTypes(rows);
+    }
+    catch (e) {
+        // It throws for a slug that is not a distinct valid identifier — a data problem the
+        // user must fix in the CMS, so name it rather than print a stack trace.
+        fail(`types: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    if (!dest) {
+        process.stdout.write(out); // composes with a pipe, like `pramen schema sql`
+        return;
+    }
+    const path = resolve(process.cwd(), dest);
+    try {
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, out);
+    }
+    catch (e) {
+        // Same treatment as the fetch above — an unwritable --out is a CLI error, not a stack.
+        fail(`types: cannot write ${dest} (${e instanceof Error ? e.message : String(e)})`);
+    }
+    console.log(`  + ${dest}  (${rows.length} block type${rows.length === 1 ? "" : "s"} from tenant '${tenant}')`);
+}
+async function main() {
+    switch (argv[0]) {
+        case undefined:
+        case "help":
+        case "-h":
+        case "--help":
+            console.log(HELP);
+            return;
+        case "types":
+            return typesCmd();
+        default:
+            console.error(`pramen-cms: unknown command "${argv[0]}"\n`);
+            console.log(HELP);
+            process.exit(1);
+    }
+}
+await main();

package/dist/href.d.ts

@@ -0,0 +1,14 @@
+/** Strip the characters the WHATWG URL parser ignores before parsing (ASCII tab/CR/LF),
+ * then trim. Store and render THIS form, so what was validated is what a browser resolves. */
+export declare function normalizeHref(raw: string): string;
+/** Allow-list for a link href: http(s), mailto, tel, or a relative/anchor path.
+ *
+ * Whitespace is stripped FIRST, because the URL parser does the same — `/\r\n/evil.example/x`
+ * otherwise passes a prefix test and still resolves to `https://evil.example/x`. Then a
+ * single leading slash only, whose next character may be neither `/` nor `\` (the parser
+ * folds `\` to `/` at path-start for special schemes). The scheme allow-list inherently
+ * rejects `javascript:`, `data:` and `vbscript:`.
+ *
+ * This is the security boundary — the write-path normalizer and BOTH renderers call it —
+ * not the UI hint that @podoba/react's `safeLinkUrl` is. */
+export declare function isSafeHref(raw: unknown): boolean;

package/dist/href.js

@@ -0,0 +1,22 @@
+// Link-href safety. A LEAF module on purpose: `@pramen/cms/react` needs these at runtime,
+// and importing them from `./index` pulled the whole server SDK into every browser bundle
+// that renders rich text (`index.ts` evaluates `Entity(...)` calls at module scope for
+// `cmsSchema`, which no bundler can tree-shake — measured 785 B -> 56 kB).
+/** Strip the characters the WHATWG URL parser ignores before parsing (ASCII tab/CR/LF),
+ * then trim. Store and render THIS form, so what was validated is what a browser resolves. */
+export function normalizeHref(raw) {
+    return raw.replace(/[\t\n\r]/g, "").trim();
+}
+/** Allow-list for a link href: http(s), mailto, tel, or a relative/anchor path.
+ *
+ * Whitespace is stripped FIRST, because the URL parser does the same — `/\r\n/evil.example/x`
+ * otherwise passes a prefix test and still resolves to `https://evil.example/x`. Then a
+ * single leading slash only, whose next character may be neither `/` nor `\` (the parser
+ * folds `\` to `/` at path-start for special schemes). The scheme allow-list inherently
+ * rejects `javascript:`, `data:` and `vbscript:`.
+ *
+ * This is the security boundary — the write-path normalizer and BOTH renderers call it —
+ * not the UI hint that @podoba/react's `safeLinkUrl` is. */
+export function isSafeHref(raw) {
+    return typeof raw === "string" && /^(https?:\/\/|mailto:|tel:|\/(?![/\\])|#)/i.test(normalizeHref(raw));
+}