barakopress 0.2.0

package/src/config.ts

@@ -0,0 +1,159 @@
+/*
+ * The seam.
+ *
+ * Everything a site differs on lives here, so a consumer configures the engine instead of forking
+ * it. That matters because barakoCMS content types are defined at runtime: a client's posts are as
+ * likely to be `article` with a `Headline` as they are to be the blog blueprint's `post` and
+ * `Title`. An engine that compiles one shape in is one client's blog wearing a package name.
+ *
+ * The defaults are the `blog` blueprint the API ships, so a site that used the blueprint passes
+ * nothing and gets the same behaviour as before this existed.
+ *
+ * Config reaches the screens through factories rather than a global, because a Next route is a
+ * file and a package cannot write files into someone else's app. A consumer's route file calls
+ * `createBlogIndex(config)` and exports the result. One import, one call, full control.
+ */
+
+export interface TypeNames {
+    /** The content type holding posts. */
+    post: string;
+    /** The type an author reference points at. Omit if the model has no authors. */
+    author?: string;
+    /** The type a category reference points at. Omit if the model has no categories. */
+    category?: string;
+}
+
+/**
+ * Which field on the post type holds what.
+ *
+ * Only `title` and `body` are required; everything else is a feature the site does without if the
+ * model has no field for it. An absent name means the engine never asks for that data and never
+ * renders it, rather than rendering an empty slot.
+ */
+export interface FieldMap {
+    title: string;
+    body: string;
+    slug?: string;
+    excerpt?: string;
+    publishedAt?: string;
+    coverImage?: string;
+    coverImageAlt?: string;
+    featured?: string;
+    tags?: string;
+    /** The reference field pointing at the author type. */
+    author?: string;
+    /** The reference field pointing at the category type. */
+    category?: string;
+}
+
+/** Where the consumer mounted each route, so generated links match the app's real shape. */
+export interface RouteMap {
+    /** The post route's prefix, for example "/blog" or "/writing". */
+    post: string;
+    author?: string;
+    category?: string;
+}
+
+export interface PageSizes {
+    index: number;
+    feed: number;
+    sitemap: number;
+    archive: number;
+}
+
+export interface SiteIdentity {
+    name: string;
+    tagline?: string;
+    /** Absolute origin, used for every absolute link in the feed, sitemap and robots. */
+    url: string;
+}
+
+export interface PressConfig {
+    types: TypeNames;
+    fields: FieldMap;
+    routes: RouteMap;
+    site: SiteIdentity;
+    pageSizes: PageSizes;
+    /** The cache tag this site purges. Two sites on one server need two tags. */
+    cacheTag: string;
+    /** How long a cached read may live with no webhook. Zero disables the backstop. */
+    backstopSeconds: number;
+    /** Passed to toLocaleDateString. */
+    locale: string;
+    /** Where the CMS is, from this server. */
+    cmsUrl: string;
+    /** Tenant slug, for a multi-tenant deployment. */
+    tenant?: string;
+}
+
+export type PressConfigInput = {
+    types?: Partial<TypeNames>;
+    fields?: Partial<FieldMap>;
+    routes?: Partial<RouteMap>;
+    site?: Partial<SiteIdentity>;
+    pageSizes?: Partial<PageSizes>;
+} & Partial<Omit<PressConfig, "types" | "fields" | "routes" | "site" | "pageSizes">>;
+
+/** The `blog` blueprint, which is what `POST /api/content-types/blueprints/blog` creates. */
+const BLOG_BLUEPRINT: Pick<PressConfig, "types" | "fields"> = {
+    types: { post: "post", author: "author", category: "category" },
+    fields: {
+        title: "Title",
+        slug: "Slug",
+        excerpt: "Excerpt",
+        body: "Body",
+        coverImage: "CoverImage",
+        coverImageAlt: "CoverImageAlt",
+        publishedAt: "PublishedAt",
+        featured: "Featured",
+        tags: "Tags",
+        author: "Author",
+        category: "Category",
+    },
+};
+
+function trimSlash(path: string): string {
+    return path.replace(/\/+$/, "");
+}
+
+/**
+ * Builds a complete config from a partial one.
+ *
+ * Site name and URL have no sensible default: a fallback of the engine's own name is how a client
+ * site ends up with the vendor's brand in its masthead, so they are required and the type says so.
+ */
+export function defineConfig(input: PressConfigInput & { site: SiteIdentity }): PressConfig {
+    const routes = { post: "/blog", author: "/authors", category: "/categories", ...input.routes };
+
+    return {
+        types: { ...BLOG_BLUEPRINT.types, ...input.types },
+        fields: { ...BLOG_BLUEPRINT.fields, ...input.fields },
+        routes: {
+            post: trimSlash(routes.post),
+            author: routes.author ? trimSlash(routes.author) : undefined,
+            category: routes.category ? trimSlash(routes.category) : undefined,
+        },
+        site: { ...input.site, url: trimSlash(input.site.url) },
+        pageSizes: { index: 20, feed: 50, sitemap: 1000, archive: 50, ...input.pageSizes },
+        cacheTag: input.cacheTag ?? "cms",
+        backstopSeconds: input.backstopSeconds ?? 300,
+        locale: input.locale ?? "en-GB",
+        cmsUrl: trimSlash(input.cmsUrl ?? process.env.CMS_URL ?? "http://localhost:5005"),
+        tenant: input.tenant ?? process.env.CMS_TENANT ?? undefined,
+    };
+}
+
+/**
+ * The reference fields worth resolving in one request, as the API's `include` expects them.
+ *
+ * Only names the site actually has. Sending `include=Author,Category` unconditionally is a 400
+ * from the API for any post type without both fields, which is every model that is not the blog
+ * blueprint.
+ */
+export function includesFor(config: PressConfig): string[] {
+    const wanted: (string | undefined)[] = [
+        config.types.author ? config.fields.author : undefined,
+        config.types.category ? config.fields.category : undefined,
+    ];
+    return wanted.filter((f): f is string => Boolean(f));
+}

package/src/delivery.ts

@@ -0,0 +1,134 @@
+import type { PressConfig } from "./config.js";
+
+/*
+ * The delivery layer: typed calls against barakoCMS's public API.
+ *
+ * It should use @baryodev/barako-client and it is written to switch back, but 0.3.0 cannot express
+ * what a blog needs. Its PublicListQuery is `{ page?, pageSize? }` and nothing else, and `bySlug`
+ * takes no options, so `include`, `filter`, `sort` and a preview token are all out of reach even
+ * though the API supports every one of them. Tracked on BaryoDev/barakoCMS#182.
+ *
+ * Caching is the reason to be careful here. Every read is tagged, so a signed webhook can drop it
+ * the moment the CMS says something changed, and carries a backstop so a deployment whose webhook
+ * was never wired up still refreshes on its own.
+ *
+ * Nothing here reads process.env or a module-level constant: every call takes the config, because
+ * two sites served by one build must be able to differ, and because a value read at module scope
+ * is baked into a prerender at build time.
+ */
+
+export interface PublicContent {
+    id: string;
+    slug?: string;
+    contentType?: string;
+    createdAt?: string;
+    updatedAt?: string;
+    data: Record<string, unknown>;
+    seo?: Seo;
+}
+
+export interface Seo {
+    title?: string;
+    description?: string;
+    canonicalUrl?: string;
+    imageUrl?: string;
+    noIndex?: boolean;
+}
+
+export interface Paged<T> {
+    items: T[];
+    page: number;
+    pageSize: number;
+    totalItems: number;
+    totalPages: number;
+    hasNextPage: boolean;
+}
+
+function headers(config: PressConfig): HeadersInit {
+    return config.tenant ? { "X-Tenant": config.tenant } : {};
+}
+
+/** A cached, tagged read. Everything a visitor sees comes through here. */
+async function get<T>(config: PressConfig, path: string): Promise<T> {
+    const res = await fetch(`${config.cmsUrl}${path}`, {
+        headers: headers(config),
+        next: {
+            tags: [config.cacheTag],
+            // Zero means no backstop, which Next spells as false.
+            revalidate: config.backstopSeconds > 0 ? config.backstopSeconds : false,
+        },
+    });
+    if (!res.ok) throw new Error(`${path} answered ${res.status}`);
+    return (await res.json()) as T;
+}
+
+/** An uncached read, for a draft. A cached draft would be served to the next visitor. */
+async function getFresh<T>(config: PressConfig, path: string): Promise<T | null> {
+    const res = await fetch(`${config.cmsUrl}${path}`, {
+        headers: headers(config),
+        cache: "no-store",
+    });
+    if (res.status === 404) return null;
+    if (!res.ok) throw new Error(`${path} answered ${res.status}`);
+    return (await res.json()) as T;
+}
+
+export interface ListOptions {
+    page?: number;
+    pageSize?: number;
+    /** Reference fields to resolve in the same request. The API caps this at five. */
+    include?: string[];
+    /** `[field, op, value]`, for example ["Author", "eq", id]. The API caps this at five. */
+    filter?: [string, string, string][];
+    /** Sent to the API, so ordering covers every row rather than the page that came back. */
+    sort?: string;
+}
+
+export async function list(
+    config: PressConfig,
+    type: string,
+    opts: ListOptions = {},
+): Promise<Paged<PublicContent>> {
+    const q = new URLSearchParams();
+    q.set("page", String(opts.page ?? 1));
+    q.set("pageSize", String(opts.pageSize ?? config.pageSizes.index));
+    if (opts.include?.length) q.set("include", opts.include.join(","));
+    if (opts.sort) q.set("sort", opts.sort);
+    for (const [field, op, value] of opts.filter ?? []) q.set(`filter[${field}][${op}]`, value);
+    return get<Paged<PublicContent>>(config, `/api/public/${encodeURIComponent(type)}?${q}`);
+}
+
+export async function bySlug(
+    config: PressConfig,
+    type: string,
+    slug: string,
+): Promise<PublicContent | null> {
+    try {
+        return await get<PublicContent>(
+            config,
+            `/api/public/${encodeURIComponent(type)}/${encodeURIComponent(slug)}`,
+        );
+    } catch (e) {
+        // A missing entry is a not-found page, not a broken site.
+        if (e instanceof Error && e.message.includes("404")) return null;
+        throw e;
+    }
+}
+
+/**
+ * A draft, read with a preview token an editor minted from `POST /api/preview`.
+ *
+ * An invalid or expired token is not an error: the API falls back to published-only, so this
+ * returns whatever is public, or null. That is the safe direction to fail in.
+ */
+export async function bySlugPreview(
+    config: PressConfig,
+    type: string,
+    slug: string,
+    token: string,
+): Promise<PublicContent | null> {
+    return getFresh<PublicContent>(
+        config,
+        `/api/public/${encodeURIComponent(type)}/${encodeURIComponent(slug)}?preview=${encodeURIComponent(token)}`,
+    );
+}

package/src/index.ts

@@ -0,0 +1,69 @@
+/*
+ * The barakoPress engine.
+ *
+ * A site depends on this and re-exports the pieces it wants from its own route files, because
+ * Next decides routes by file path and a package cannot create files in someone else's app.
+ *
+ * Everything that differs between sites is in the config passed to these factories: the content
+ * type names, the field map, where the routes are mounted, page sizes, site identity, the cache
+ * tag and the backstop. barakoCMS content types are defined at runtime, so a client's posts are
+ * as likely to be `article` with a `Headline` as the blueprint's `post` and `Title`. An engine
+ * that compiled one shape in would be one blog wearing a package name.
+ *
+ * A consumer's app/page.tsx:
+ *
+ *     import { createBlogIndex } from "barakopress";
+ *     import { config } from "@/press.config";
+ *     export default createBlogIndex(config);
+ *     export const revalidate = 300;
+ *
+ * Route segment config stays in the consumer's file: Next reads it from the file that owns the
+ * route and does not reliably follow a re-export, and the caching window is their decision.
+ *
+ * The screens live in src/screens rather than src/pages because Next claims both `pages` and
+ * `app` as router directories, and a `src/pages` inside a transpiled package is read as a second
+ * router.
+ */
+
+export { defineConfig, includesFor } from "./config.js";
+export type {
+    PressConfig,
+    PressConfigInput,
+    TypeNames,
+    FieldMap,
+    RouteMap,
+    PageSizes,
+    SiteIdentity,
+} from "./config.js";
+
+export { list, bySlug, bySlugPreview } from "./delivery.js";
+export type { PublicContent, Seo, ListOptions, Paged } from "./delivery.js";
+
+export {
+    listPosts,
+    getPost,
+    getPostPreview,
+    listPostsBy,
+    getTerm,
+    toPost,
+    formatDate,
+} from "./cms.js";
+export type { Post, Ref, Term } from "./cms.js";
+
+export { renderMarkdown, isSafeHref, anchor } from "./markdown.js";
+
+export { createBlogIndex, Card } from "./screens/blog-index.js";
+export {
+    createBlogPost,
+    createBlogPostPreview,
+    createPostMetadata,
+    createPostStaticParams,
+} from "./screens/blog-post.js";
+export { createArchive, createArchiveStaticParams } from "./screens/archive.js";
+export { PostView } from "./screens/post-view.js";
+
+export { createRevalidateRoute } from "./routes/revalidate.js";
+export type { RevalidateOptions } from "./routes/revalidate.js";
+export { createFeed } from "./routes/feed.js";
+export { createSitemap } from "./routes/sitemap.js";
+export { createRobots } from "./routes/robots.js";

package/src/markdown.ts

@@ -0,0 +1,96 @@
+import { Marked, type Tokens } from "marked";
+
+/*
+ * Markdown to HTML, treating the markdown as untrusted.
+ *
+ * An editor is authenticated, so this is not the first line of defence. It is the second, and it
+ * matters because the body of a post is the one field on this site that becomes markup. The
+ * threats it closes: an editor account that gets taken over, a contributor who is trusted to write
+ * but not to run script on the domain, and content imported in bulk from somewhere else.
+ *
+ * Three rules:
+ *   1. Raw HTML in the source is escaped, never passed through. That removes script tags, event
+ *      handler attributes and iframes in one move, instead of trying to enumerate them.
+ *   2. A link or image destination must be http, https or mailto. That kills javascript: and
+ *      data: URLs, which are the two that execute.
+ *   3. Text is escaped on the way into every attribute, so an alt or a title cannot close its own
+ *      quote and add another attribute.
+ *
+ * The trade is real and deliberate: an author cannot embed a YouTube iframe or any raw HTML. When
+ * that is wanted, the answer is a content field the frontend renders deliberately, not a hole here.
+ */
+
+const SAFE_SCHEMES = ["http:", "https:", "mailto:"];
+
+export function isSafeHref(href: string): boolean {
+    const trimmed = href.trim();
+    // A relative or anchor link has no scheme and cannot execute.
+    if (trimmed.startsWith("/") || trimmed.startsWith("#")) return true;
+    try {
+        return SAFE_SCHEMES.includes(new URL(trimmed).protocol);
+    } catch {
+        // Unparseable means it is not a URL this should emit.
+        return false;
+    }
+}
+
+function escapeHtml(value: string): string {
+    return value
+        .replace(/&/g, "&")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&#39;");
+}
+
+/** Turns a heading into a stable id, so "On this page" links and deep links work. */
+export function anchor(text: string): string {
+    return text
+        .toLowerCase()
+        .replace(/[^\w\s-]/g, "")
+        .trim()
+        .replace(/\s+/g, "-");
+}
+
+function buildRenderer() {
+    const marked = new Marked({ gfm: true, breaks: false });
+
+    marked.use({
+        renderer: {
+            // Raw HTML blocks and inline HTML are emitted as visible text, not as markup.
+            html({ text }: Tokens.HTML | Tokens.Tag) {
+                return escapeHtml(text);
+            },
+            link({ href, title, tokens }) {
+                const label = this.parser.parseInline(tokens);
+                if (!isSafeHref(href)) {
+                    // Keep the words, drop the destination. A reader still sees what was written.
+                    return label;
+                }
+                const t = title ? ` title="${escapeHtml(title)}"` : "";
+                const external = /^https?:/.test(href.trim());
+                const rel = external ? ' rel="noopener noreferrer"' : "";
+                return `<a href="${escapeHtml(href.trim())}"${t}${rel}>${label}</a>`;
+            },
+            image({ href, title, text }) {
+                if (!isSafeHref(href)) return escapeHtml(text ?? "");
+                const t = title ? ` title="${escapeHtml(title)}"` : "";
+                return `<img src="${escapeHtml(href.trim())}" alt="${escapeHtml(text ?? "")}"${t} loading="lazy">`;
+            },
+            heading({ tokens, depth }) {
+                const label = this.parser.parseInline(tokens);
+                const plain = tokens.map((t) => ("raw" in t ? t.raw : "")).join("");
+                return `<h${depth} id="${escapeHtml(anchor(plain))}">${label}</h${depth}>`;
+            },
+        },
+    });
+
+    return marked;
+}
+
+const renderer = buildRenderer();
+
+export function renderMarkdown(source: string): string {
+    if (!source) return "";
+    return renderer.parse(source, { async: false }) as string;
+}

package/src/routes/feed.ts

@@ -0,0 +1,79 @@
+import type { PressConfig } from "../config.js";
+import { listPosts } from "../cms.js";
+
+/*
+ * RSS, built here rather than proxied from the CMS.
+ *
+ * barakoCMS serves /api/public/{type}/feed.xml and it is correct, but its item links come from a
+ * server-side config template that has to be kept in step with the site's routes by hand. Built
+ * here, the routes have one owner: config.routes. It also costs nothing, because it is the same
+ * cached, tagged read the index uses.
+ */
+
+/** XML text escaping. Every value below is content someone typed, so none of it is trusted. */
+function xml(value: string): string {
+    return value
+        .replace(/&/g, "&")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&apos;");
+}
+
+export function createFeed(config: PressConfig) {
+    return async function GET() {
+        let posts: Awaited<ReturnType<typeof listPosts>>["posts"] = [];
+        try {
+            ({ posts } = await listPosts(config, { pageSize: config.pageSizes.feed }));
+        } catch {
+            // An unreachable CMS yields an empty channel, not a failure. This route is prerendered
+            // when the consumer gives it a revalidate window, so a throw fails their build, and at
+            // runtime it would hand a feed reader a 500.
+            posts = [];
+        }
+
+        const items = posts
+            .map((p) => {
+                const url = `${config.site.url}${config.routes.post}/${p.slug}`;
+                const date = p.publishedAt ? new Date(p.publishedAt) : null;
+                const pubDate =
+                    date && !Number.isNaN(date.getTime())
+                        ? `      <pubDate>${date.toUTCString()}</pubDate>`
+                        : "";
+                return [
+                    "    <item>",
+                    `      <title>${xml(p.title)}</title>`,
+                    `      <link>${xml(url)}</link>`,
+                    `      <guid isPermaLink="true">${xml(url)}</guid>`,
+                    // Plain text, not rendered HTML: a feed reader that trusts markup is not this
+                    // site's problem to create.
+                    p.excerpt ? `      <description>${xml(p.excerpt)}</description>` : "",
+                    pubDate,
+                    p.category ? `      <category>${xml(p.category.name)}</category>` : "",
+                    "    </item>",
+                ]
+                    .filter(Boolean)
+                    .join("\n");
+            })
+            .join("\n");
+
+        const body = `<?xml version="1.0" encoding="UTF-8"?>
+<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
+  <channel>
+    <title>${xml(config.site.name)}</title>
+    <link>${xml(config.site.url)}</link>
+    <description>${xml(config.site.tagline ?? config.site.name)}</description>
+    <atom:link href="${xml(`${config.site.url}/feed.xml`)}" rel="self" type="application/rss+xml"/>
+${items}
+  </channel>
+</rss>
+`;
+
+        return new Response(body, {
+            headers: {
+                "content-type": "application/rss+xml; charset=utf-8",
+                "cache-control": "public, max-age=300",
+            },
+        });
+    };
+}