@glw907/cairn-cms 0.6.0-rc.1 → 0.7.0

package/src/lib/delivery/feeds.ts

@@ -0,0 +1,112 @@
+// cairn-cms: RSS and JSON Feed builders (public-delivery design). Pure functions over a
+// channel and a list of items, so they unit-test without a render or a network. The caller
+// (a template +server.ts shim) assembles items from the content index and passes absolute
+// URLs built from PUBLIC_ORIGIN.
+
+/** Feed channel metadata. URLs are absolute. */
+export interface FeedChannel {
+  title: string;
+  description: string;
+  siteUrl: string;
+  feedUrl: string;
+  language?: string;
+  author?: { name: string; email?: string };
+}
+
+/** One feed entry. `contentHtml` carries the rendered body for a full-content feed. */
+export interface FeedItem {
+  title: string;
+  url: string;
+  date: string;
+  updated?: string;
+  summary: string;
+  contentHtml?: string;
+  tags?: string[];
+}
+
+function escapeXml(value: string): string {
+  return value
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
+/** Make a string safe inside a CDATA section by splitting any `]]>` across two sections. */
+function cdataSafe(value: string): string {
+  return value.replace(/]]>/g, ']]]]><![CDATA[>');
+}
+
+/** Format a YYYY-MM-DD (or ISO) string as an RFC-822 date in UTC, as RSS wants. */
+function rfc822(date: string): string {
+  return new Date(`${date.slice(0, 10)}T00:00:00.000Z`).toUTCString();
+}
+
+/** Format a YYYY-MM-DD (or ISO) string as an ISO-8601 instant in UTC. */
+function iso(date: string): string {
+  return new Date(`${date.slice(0, 10)}T00:00:00.000Z`).toISOString();
+}
+
+/** Build an RSS 2.0 document. */
+export function buildRssFeed(channel: FeedChannel, items: FeedItem[]): string {
+  const entries = items
+    .map((item) => {
+      const content = item.contentHtml ?? item.summary;
+      return [
+        '    <item>',
+        `      <title>${escapeXml(item.title)}</title>`,
+        `      <link>${escapeXml(item.url)}</link>`,
+        `      <guid isPermaLink="true">${escapeXml(item.url)}</guid>`,
+        `      <pubDate>${rfc822(item.date)}</pubDate>`,
+        `      <description>${escapeXml(item.summary)}</description>`,
+        // CDATA cannot contain `]]>`, so split that one sequence rather than escape the body.
+        `      <content:encoded><![CDATA[${cdataSafe(content)}]]></content:encoded>`,
+        '    </item>',
+      ].join('\n');
+    })
+    .join('\n');
+
+  return [
+    '<?xml version="1.0" encoding="UTF-8"?>',
+    '<rss version="2.0" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom">',
+    '  <channel>',
+    `    <title>${escapeXml(channel.title)}</title>`,
+    `    <link>${escapeXml(channel.siteUrl)}</link>`,
+    `    <description>${escapeXml(channel.description)}</description>`,
+    channel.language ? `    <language>${escapeXml(channel.language)}</language>` : '',
+    `    <atom:link href="${escapeXml(channel.feedUrl)}" rel="self" type="application/rss+xml" />`,
+    entries,
+    '  </channel>',
+    '</rss>',
+    '',
+  ]
+    .filter((line) => line !== '')
+    .join('\n');
+}
+
+/** Build a JSON Feed 1.1 document. */
+export function buildJsonFeed(channel: FeedChannel, items: FeedItem[]): string {
+  return JSON.stringify(
+    {
+      version: 'https://jsonfeed.org/version/1.1',
+      title: channel.title,
+      description: channel.description,
+      home_page_url: channel.siteUrl,
+      feed_url: channel.feedUrl,
+      ...(channel.language ? { language: channel.language } : {}),
+      ...(channel.author ? { authors: [channel.author] } : {}),
+      items: items.map((item) => ({
+        id: item.url,
+        url: item.url,
+        title: item.title,
+        summary: item.summary,
+        date_published: iso(item.date),
+        ...(item.updated ? { date_modified: iso(item.updated) } : {}),
+        ...(item.contentHtml ? { content_html: item.contentHtml } : { content_text: item.summary }),
+        ...(item.tags && item.tags.length ? { tags: item.tags } : {}),
+      })),
+    },
+    null,
+    2,
+  );
+}

package/src/lib/delivery/paginate.ts

@@ -0,0 +1,32 @@
+// cairn-cms: pagination helper (public-delivery design). Pure slice math; the template renders
+// the controls. An out-of-range page clamps into bounds.
+
+/** A page of items plus its navigation state. */
+export interface Page<T> {
+  items: T[];
+  page: number;
+  perPage: number;
+  total: number;
+  totalPages: number;
+  hasPrev: boolean;
+  hasNext: boolean;
+}
+
+/** Slice `items` into the 1-based `page` of size `perPage`, clamping the page into bounds. */
+export function paginate<T>(items: T[], page: number, perPage: number): Page<T> {
+  const total = items.length;
+  // A non-positive page size would make totalPages Infinity, so clamp it to one.
+  const size = Math.max(1, Math.floor(perPage) || 1);
+  const totalPages = Math.max(1, Math.ceil(total / size));
+  const current = Math.min(Math.max(1, Math.floor(page) || 1), totalPages);
+  const start = (current - 1) * size;
+  return {
+    items: items.slice(start, start + size),
+    page: current,
+    perPage: size,
+    total,
+    totalPages,
+    hasPrev: current > 1,
+    hasNext: current < totalPages,
+  };
+}

package/src/lib/delivery/robots.ts

@@ -0,0 +1,10 @@
+// cairn-cms: robots.txt builder (public-delivery design). A permissive default that points
+// at the sitemap, with optional disallow rules.
+
+/** Build a robots.txt body. */
+export function buildRobots(opts: { sitemapUrl: string; disallow?: string[] }): string {
+  const lines = ['User-agent: *', 'Allow: /'];
+  for (const path of opts.disallow ?? []) lines.push(`Disallow: ${path}`);
+  lines.push('', `Sitemap: ${opts.sitemapUrl}`, '');
+  return lines.join('\n');
+}

package/src/lib/delivery/seo.ts

@@ -0,0 +1,72 @@
+// cairn-cms: the SEO head builder (public-delivery design, decision 6). Returns plain data so
+// the template renders it inside <svelte:head>. It covers the universal, mechanical tags;
+// og:image art and richer JSON-LD types stay a template or plugin concern.
+
+/** Inputs for the head. All URLs are absolute (built from PUBLIC_ORIGIN). */
+export interface SeoInput {
+  title: string;
+  description: string;
+  canonicalUrl: string;
+  siteName: string;
+  type?: 'website' | 'article';
+  published?: string;
+  modified?: string;
+  feeds?: { rss?: string; json?: string };
+  image?: string;
+}
+
+/** Plain-data head: a title, meta tags, link tags, and one JSON-LD object. */
+export interface SeoMeta {
+  title: string;
+  meta: { name?: string; property?: string; content: string }[];
+  links: { rel: string; type?: string; href: string; title?: string }[];
+  jsonLd: Record<string, unknown>;
+}
+
+/** Build the head data for a page. */
+export function buildSeoMeta(input: SeoInput): SeoMeta {
+  const type = input.type ?? 'website';
+  const meta: SeoMeta['meta'] = [
+    { name: 'description', content: input.description },
+    { property: 'og:title', content: input.title },
+    { property: 'og:description', content: input.description },
+    { property: 'og:type', content: type },
+    { property: 'og:url', content: input.canonicalUrl },
+    { property: 'og:site_name', content: input.siteName },
+    { name: 'twitter:card', content: input.image ? 'summary_large_image' : 'summary' },
+  ];
+  if (input.image) {
+    meta.push({ property: 'og:image', content: input.image });
+    meta.push({ name: 'twitter:image', content: input.image });
+  }
+
+  const links: SeoMeta['links'] = [{ rel: 'canonical', href: input.canonicalUrl }];
+  if (input.feeds?.rss) {
+    links.push({ rel: 'alternate', type: 'application/rss+xml', href: input.feeds.rss, title: input.siteName });
+  }
+  if (input.feeds?.json) {
+    links.push({ rel: 'alternate', type: 'application/feed+json', href: input.feeds.json, title: input.siteName });
+  }
+
+  const jsonLd: Record<string, unknown> =
+    type === 'article'
+      ? {
+          '@context': 'https://schema.org',
+          '@type': 'Article',
+          headline: input.title,
+          description: input.description,
+          url: input.canonicalUrl,
+          ...(input.published ? { datePublished: input.published } : {}),
+          ...(input.modified ? { dateModified: input.modified } : {}),
+          ...(input.image ? { image: input.image } : {}),
+        }
+      : {
+          '@context': 'https://schema.org',
+          '@type': 'WebSite',
+          name: input.siteName,
+          description: input.description,
+          url: input.canonicalUrl,
+        };
+
+  return { title: input.title, meta, links, jsonLd };
+}

package/src/lib/delivery/sitemap.ts

@@ -0,0 +1,29 @@
+// cairn-cms: sitemap builder (public-delivery design). Pure over a URL list; the caller
+// derives the list from the content index and the routable concepts.
+
+/** One sitemap URL. `lastmod` is a YYYY-MM-DD date. */
+export interface SitemapUrl {
+  loc: string;
+  lastmod?: string;
+}
+
+function escapeXml(value: string): string {
+  return value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+
+/** Build a sitemap XML document from a list of URLs. */
+export function buildSitemap(urls: SitemapUrl[]): string {
+  const entries = urls
+    .map((url) => {
+      const lastmod = url.lastmod ? `\n    <lastmod>${escapeXml(url.lastmod)}</lastmod>` : '';
+      return `  <url>\n    <loc>${escapeXml(url.loc)}</loc>${lastmod}\n  </url>`;
+    })
+    .join('\n');
+  return [
+    '<?xml version="1.0" encoding="UTF-8"?>',
+    '<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">',
+    entries,
+    '</urlset>',
+    '',
+  ].join('\n');
+}

package/src/lib/index.ts

@@ -84,3 +84,25 @@ export {
   SiteConfigError,
 } from './nav/site-config.js';
 export type { NavNode, SiteConfig } from './nav/site-config.js';
+
+// Public content delivery (public-delivery design): the query index, syndication, and
+// discovery surface that sites read. Pure builders plus the one permalink resolver; the
+// SvelteKit loaders live under the /sveltekit subpath.
+export { permalink } from './content/permalink.js';
+export { createContentIndex, fromGlob } from './delivery/content-index.js';
+export type {
+  RawFile,
+  ContentSummary,
+  ContentEntry,
+  ContentIndex,
+} from './delivery/content-index.js';
+export { deriveExcerpt, wordCount } from './delivery/excerpt.js';
+export { buildRssFeed, buildJsonFeed } from './delivery/feeds.js';
+export type { FeedChannel, FeedItem } from './delivery/feeds.js';
+export { buildSitemap } from './delivery/sitemap.js';
+export type { SitemapUrl } from './delivery/sitemap.js';
+export { buildRobots } from './delivery/robots.js';
+export { buildSeoMeta } from './delivery/seo.js';
+export type { SeoInput, SeoMeta } from './delivery/seo.js';
+export { paginate } from './delivery/paginate.js';
+export type { Page } from './delivery/paginate.js';

package/src/lib/sveltekit/index.ts

@@ -17,3 +17,11 @@ export { createNavRoutes } from './nav-routes.js';
 export type { NavLoadData, NavPageOption, NavRoutesDeps } from './nav-routes.js';
 export { healthLoad, type HealthData } from './health.js';
 export type { RequestContext, CookieJar, HandleInput } from './types.js';
+export { createPublicRoutes } from './public-routes.js';
+export type {
+  PublicRoutesDeps,
+  ListData as PublicListData,
+  TagData,
+  TagIndexData,
+  EntryData,
+} from './public-routes.js';

package/src/lib/sveltekit/public-routes.ts

@@ -0,0 +1,81 @@
+// cairn-cms: public route loaders (public-delivery design, decision 6). A factory closes over
+// a concept's index, the runtime render, and the origin, and returns thin load functions plus
+// entries() for prerender. A site route file stays a one-line shim. The index is built in site
+// code from a glob, so it stays in the prerender graph and out of the runtime Worker.
+import { error } from '@sveltejs/kit';
+import type { ContentIndex, ContentSummary, ContentEntry } from '../delivery/content-index.js';
+
+/** Injected dependencies for the public loaders. */
+export interface PublicRoutesDeps {
+  index: ContentIndex;
+  render: (md: string, opts?: { stagger?: boolean }) => string | Promise<string>;
+  origin: string;
+}
+
+/** The archive and tag list data: summaries the template renders. */
+export interface ListData {
+  entries: ContentSummary[];
+}
+
+/** A single tag's data plus the tag it filtered on. */
+export interface TagData extends ListData {
+  tag: string;
+}
+
+/** The tag-index data: every tag with its count. */
+export interface TagIndexData {
+  tags: { tag: string; count: number }[];
+}
+
+/** One entry's data: the detail entry, its rendered html, and its canonical URL. */
+export interface EntryData {
+  entry: ContentEntry;
+  html: string;
+  canonicalUrl: string;
+  newer?: ContentSummary;
+  older?: ContentSummary;
+}
+
+/** Build the public loaders for one concept's index. */
+export function createPublicRoutes(deps: PublicRoutesDeps) {
+  const { index, render, origin } = deps;
+
+  /** The chronological archive: every non-draft summary, newest-first. */
+  function archiveLoad(): ListData {
+    return { entries: index.all() };
+  }
+
+  /** All tags with counts, for a tag index page. */
+  function tagIndexLoad(): TagIndexData {
+    return { tags: index.allTags() };
+  }
+
+  /** One tag's entries, or a 404 when the tag has none. */
+  function tagLoad(event: { params: { tag: string } }): TagData {
+    const tag = event.params.tag;
+    const entries = index.byTag(tag);
+    if (entries.length === 0) throw error(404, `No entries tagged "${tag}"`);
+    return { tag, entries };
+  }
+
+  /** One entry by slug, rendered through the site renderer, or a 404. */
+  async function entryLoad(event: { params: { slug: string } }): Promise<EntryData> {
+    const entry = index.byId(event.params.slug);
+    if (!entry) throw error(404, `Not found: ${event.params.slug}`);
+    const { newer, older } = index.adjacent(entry.id);
+    return {
+      entry,
+      html: await render(entry.body, { stagger: true }),
+      canonicalUrl: origin + entry.permalink,
+      newer,
+      older,
+    };
+  }
+
+  /** Prerender enumeration: one `{ slug }` per non-draft entry. */
+  function entries(): { slug: string }[] {
+    return index.all().map((entry) => ({ slug: entry.id }));
+  }
+
+  return { archiveLoad, tagIndexLoad, tagLoad, entryLoad, entries };
+}