@pramen/cms 0.0.49 → 0.0.50

package/dist/react.d.ts

@@ -1,5 +1,5 @@
-import type { ComponentType, ReactElement } from "react";
-import type { RenderedBlock, BlockTypeDef, BlockFieldsOf } from "./index";
+import type { ComponentType, ReactElement, ReactNode } from "react";
+import type { RenderedBlock, BlockTypeDef, BlockFieldsOf, RichTextDoc, RichTextNode } from "./index";
 /** Props a component for a specific typed block type receives — `fields` is inferred from
  * the block type's schema via `BlockFieldsOf` (see `defineBlockType`). */
 export interface TypedBlockProps<D extends BlockTypeDef> {
@@ -39,3 +39,16 @@ export interface RegionRendererProps {
 }
 /** Render a single named region from an AssembledPage's `regions` map. */
 export declare function RegionRenderer({ regions, name, components, fallback }: RegionRendererProps): ReactElement;
+/** Props a rich-text node component receives. `children` is the already-rendered subtree. */
+export interface RichTextNodeProps {
+    node: RichTextNode;
+    children: ReactNode;
+}
+/** Per-node-type component overrides, keyed by node type (`"paragraph"`, `"heading"`, …). */
+export type RichTextNodeComponents = Record<string, ComponentType<RichTextNodeProps>>;
+export interface RichTextRendererProps {
+    value: RichTextDoc | null | undefined;
+    components?: RichTextNodeComponents;
+}
+/** Render a rich-text document as React elements. */
+export declare function RichTextRenderer({ value, components }: RichTextRendererProps): ReactElement;

package/dist/react.js

@@ -12,10 +12,13 @@
 // config and stays on the same tsconfig as the rest of pramen. In a JSX codebase you'd
 // normally write `<BlockRenderer .../>` — it's an ordinary component either way.
 import { createElement, Fragment } from "react";
+import { isSafeHref, normalizeHref } from "./href";
 /** Render an ordered list of blocks, each via its registered component. */
 export function BlockRenderer({ blocks, region, components, fallback }) {
     return createElement(Fragment, null, blocks.map((block, index) => {
-        const Component = components[block.block_type];
+        // hasOwn: a block type slugged `constructor`/`valueOf` would otherwise resolve off
+        // the prototype and crash the whole page render (createBlockType accepts any string).
+        const Component = Object.hasOwn(components, block.block_type) ? components[block.block_type] : undefined;
         if (!Component) {
             return fallback
                 ? createElement(fallback, { key: block.id, block })
@@ -28,3 +31,95 @@ export function BlockRenderer({ blocks, region, components, fallback }) {
 export function RegionRenderer({ regions, name, components, fallback }) {
     return BlockRenderer({ blocks: regions[name] ?? [], region: name, components, fallback });
 }
+const MARK_TAGS = {
+    bold: "strong",
+    italic: "em",
+    underline: "u",
+    strike: "s",
+    code: "code",
+    highlight: "mark",
+};
+/** Wrap a text leaf in its marks, innermost-first. A `link` is the only mark carrying
+ * attributes we pass through; `target="_blank"` gets `rel` forced, since the renderer owns
+ * the markup and a bare `_blank` hands the opened page a `window.opener` handle. */
+function renderMarks(text, marks) {
+    let out = text;
+    // Innermost-first, so `marks[0]` ends up OUTERMOST — matching ProseMirror's own
+    // serializer and RichTextMarks.astro. Folding forwards put marks[0] innermost, so the
+    // same document rendered `<code><a>x</a></code>` here and `<a><code>x</code></a>` in
+    // Astro: different clickable area, different CSS selectors, same content.
+    for (let i = (marks?.length ?? 0) - 1; i >= 0; i--) {
+        const mark = marks[i];
+        if (mark.type === "link") {
+            const attrs = mark.attrs ?? {};
+            // The href is the one attribute that can execute script, and this renderer declares
+            // itself a rescue for content that never passed through normalizeRichText (an app
+            // writing rows via its own mutation, a bootstrap seed, an import). So check it here
+            // too: an unsafe href drops the anchor and renders the text, never a live link.
+            if (!isSafeHref(attrs.href))
+                continue;
+            const target = typeof attrs.target === "string" ? attrs.target : undefined;
+            out = createElement("a", {
+                href: normalizeHref(String(attrs.href ?? "")),
+                title: typeof attrs.title === "string" ? attrs.title : undefined,
+                target,
+                // Any named target opens a window holding a live `window.opener`, not just
+                // `_blank` — browsers imply noopener for `_blank` alone.
+                rel: target ? "noopener noreferrer" : undefined,
+            }, out);
+        }
+        else {
+            // hasOwn: a plain index would resolve `constructor`/`toString` off the prototype.
+            out = createElement(Object.hasOwn(MARK_TAGS, mark.type) ? MARK_TAGS[mark.type] : "span", null, out);
+        }
+    }
+    return out;
+}
+function renderRichTextNode(node, key, components) {
+    if (node.type === "text")
+        return createElement(Fragment, { key }, renderMarks(node.text ?? "", node.marks));
+    const children = (node.content ?? []).map((child, i) => renderRichTextNode(child, i, components));
+    const Override = components && Object.hasOwn(components, node.type) ? components[node.type] : undefined;
+    if (Override)
+        return createElement(Override, { key, node, children });
+    const attrs = node.attrs ?? {};
+    switch (node.type) {
+        case "paragraph":
+            return createElement("p", { key }, children);
+        case "heading": {
+            // Range-checked, matching RichText.astro. Both renderers declare themselves a rescue
+            // for hand-written content that never passed through normalizeRichText, so neither
+            // may trust the attribute — an out-of-range level would emit <h0>/<h99>.
+            // Integer too: `h2.5` throws InvalidCharacterError in document.createElement.
+            const raw = attrs.level;
+            const level = typeof raw === "number" && Number.isInteger(raw) && raw >= 1 && raw <= 6 ? raw : 2;
+            return createElement(`h${level}`, { key }, children);
+        }
+        case "blockquote":
+            return createElement("blockquote", { key }, children);
+        case "codeBlock":
+            return createElement("pre", { key }, createElement("code", { className: typeof attrs.language === "string" ? `language-${attrs.language}` : undefined }, children));
+        case "bulletList":
+            return createElement("ul", { key }, children);
+        case "orderedList":
+            return createElement("ol", { key, start: typeof attrs.start === "number" ? attrs.start : undefined }, children);
+        case "listItem":
+            return createElement("li", { key }, children);
+        case "taskList":
+            return createElement("ul", { key, "data-type": "taskList" }, children);
+        case "taskItem":
+            return createElement("li", { key, "data-type": "taskItem", "data-checked": attrs.checked === true ? "true" : "false" }, children);
+        case "hardBreak":
+            return createElement("br", { key });
+        case "horizontalRule":
+            return createElement("hr", { key });
+        default:
+            // Unreachable through the write path (normalizeRichText drops unknown types), so
+            // rendering the subtree is a rescue for hand-written content, not a policy.
+            return createElement(Fragment, { key }, children);
+    }
+}
+/** Render a rich-text document as React elements. */
+export function RichTextRenderer({ value, components }) {
+    return createElement(Fragment, null, (value?.content ?? []).map((node, i) => renderRichTextNode(node, i, components)));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pramen/cms",
-  "version": "0.0.49",
+  "version": "0.0.50",
   "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,8 +41,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@pramen/server": "0.0.49",
-    "xss": "^1.0.15"
+    "@pramen/server": "0.0.50"
   },
   "peerDependencies": {
     "react": ">=18"
@@ -51,5 +50,11 @@
     "react": {
       "optional": true
     }
+  },
+  "bin": {
+    "pramen-cms": "./dist/cli.js"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0"
   }
 }

package/src/cli.ts

@@ -0,0 +1,148 @@
+#!/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, type FieldDefinition } from "./index";
+
+const argv = process.argv.slice(2);
+
+const KNOWN_FLAGS = ["url", "tenant", "token", "out"] as const;
+
+/** 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: string): string | undefined {
+  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(): void {
+  for (const a of argv) {
+    if (!a.startsWith("--")) continue;
+    const name = a.slice(2).split("=")[0]!;
+    if (!KNOWN_FLAGS.includes(name as (typeof KNOWN_FLAGS)[number])) {
+      fail(`unknown flag --${name} (expected ${KNOWN_FLAGS.map((f) => `--${f}`).join(", ")})`);
+    }
+  }
+}
+function fail(msg: string): never {
+  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.`;
+
+/** A block-type row as the content API returns it. */
+interface BlockTypeRow {
+  slug: string;
+  fieldsSchema?: FieldDefinition[] | null;
+}
+
+async function typesCmd(): Promise<void> {
+  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: Response;
+  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(() => ({}))) as { ok?: boolean; result?: BlockTypeRow[]; error?: string };
+  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: string;
+  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(): Promise<void> {
+  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/src/href.ts

@@ -0,0 +1,24 @@
+// 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: string): string {
+  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: unknown): boolean {
+  return typeof raw === "string" && /^(https?:\/\/|mailto:|tel:|\/(?![/\\])|#)/i.test(normalizeHref(raw));
+}