@glw907/cairn-cms 0.6.0 → 0.8.0

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/site-index.ts

@@ -0,0 +1,68 @@
+// cairn-cms: the site-level content index (dated-slug design). It unions every concept's
+// per-concept index into one cross-concept resolver: a single byPermalink map a catch-all route
+// matches a request path against, one entries() list the prerenderer walks, and the per-concept
+// indexes for concept-scoped archive, tag, and feed loaders. A duplicate permalink throws at build.
+import type { ConceptDescriptor } from '../content/types.js';
+import type { ContentEntry, ContentIndex, ContentSummary } from './content-index.js';
+
+/** One concept's descriptor paired with its built index. */
+export interface ConceptIndex {
+  descriptor: ConceptDescriptor;
+  index: ContentIndex;
+}
+
+/** The cross-concept query surface a catch-all route and the sitemap read. */
+export interface SiteIndex {
+  /** Resolve a request path (with or without a trailing slash) to its entry, or undefined. */
+  byPermalink(path: string): ContentEntry | undefined;
+  /** Newer/older neighbors within the entry's own concept, for prev/next links. */
+  adjacent(entry: ContentSummary): { newer?: ContentSummary; older?: ContentSummary };
+  /** Every entry's path across concepts, leading slash stripped, for SvelteKit `[...path]` prerender. */
+  entries(): { path: string }[];
+  /** One concept's index, for its archive, tag, and feed loaders. */
+  concept(id: string): ContentIndex | undefined;
+  /** Every non-draft summary across concepts, for the site-wide sitemap. */
+  all(): ContentSummary[];
+}
+
+/** Strip a trailing slash from a path, keeping the root "/" intact. */
+function normalizePath(path: string): string {
+  return path.length > 1 ? path.replace(/\/+$/, '') : path;
+}
+
+/** Union per-concept indexes into a site-level resolver; throw on a duplicate permalink. */
+export function createSiteIndex(concepts: ConceptIndex[]): SiteIndex {
+  const byPath = new Map<string, { index: ContentIndex; id: string }>();
+  const byId = new Map<string, ContentIndex>();
+  for (const { descriptor, index } of concepts) {
+    byId.set(descriptor.id, index);
+    for (const summary of index.all()) {
+      const existing = byPath.get(summary.permalink);
+      if (existing) {
+        throw new Error(
+          `site index: "${existing.id}" and "${summary.id}" both resolve to "${summary.permalink}"`,
+        );
+      }
+      byPath.set(summary.permalink, { index, id: summary.id });
+    }
+  }
+  return {
+    byPermalink(path) {
+      const hit = byPath.get(normalizePath(path));
+      return hit ? hit.index.byId(hit.id) : undefined;
+    },
+    adjacent(entry) {
+      const hit = byPath.get(entry.permalink);
+      return hit ? hit.index.adjacent(entry.id) : {};
+    },
+    entries() {
+      return [...byPath.keys()].map((p) => ({ path: p.replace(/^\//, '') }));
+    },
+    concept(id) {
+      return byId.get(id);
+    },
+    all() {
+      return concepts.flatMap(({ index }) => index.all());
+    },
+  };
+}

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

@@ -23,6 +23,7 @@ export type {
   AssetConfig,
   RoutingRule,
   ConceptDescriptor,
+  ConceptUrlPolicy,
   CairnExtension,
   CairnRuntime,
   AdminPanel,
@@ -37,7 +38,15 @@ export {
   parseMarkdown,
 } from './content/frontmatter.js';
 export { validateFields } from './content/validate.js';
-export { isValidId, idFromFilename, filenameFromId, slugify } from './content/ids.js';
+export {
+  isValidId,
+  idFromFilename,
+  filenameFromId,
+  slugify,
+  slugFromId,
+  composeDatedId,
+} from './content/ids.js';
+export type { DatePrefix } from './content/ids.js';
 // Render engine (Plan 04): generic directive pipeline; sites own the component registry.
 export { defineRegistry } from './render/registry.js';
 export type { ComponentDef, ComponentRegistry } from './render/registry.js';
@@ -76,6 +85,7 @@ export type { GithubKeyEnv } from './github/credentials.js';
 // Nav tree and site-config helpers (Plan 06).
 export {
   parseSiteConfig,
+  urlPolicyFrom,
   extractMenu,
   setMenu,
   validateNavTree,
@@ -84,3 +94,27 @@ 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 { createSiteIndex } from './delivery/site-index.js';
+export type { SiteIndex, ConceptIndex } from './delivery/site-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/nav/site-config.ts

@@ -3,6 +3,7 @@
 // commits the file back through the GitHub-App pipeline. This module is pure: parse, validate, and
 // rewrite only. The engine returns data; each site renders the tree with its own markup.
 import { parse as parseYaml, parseDocument } from 'yaml';
+import type { ConceptUrlPolicy } from '../content/types.js';
 
 /** One navigation node. An omitted or empty `url` is a label-only grouping header; no `children` is a leaf. */
 export interface NavNode {
@@ -78,6 +79,8 @@ export interface SiteConfig {
   locale?: string;
   /** Named navigation menus, each a NavNode[] (normalized by extractMenu). */
   menus?: Record<string, unknown>;
+  /** Per-concept URL policy: the permalink pattern and date-prefix granularity, keyed by concept id. */
+  content?: Record<string, ConceptUrlPolicy>;
   [key: string]: unknown;
 }
 
@@ -108,6 +111,11 @@ export function extractMenu(config: SiteConfig, name: string, maxDepth: number):
   return validateNavTree(menu, maxDepth);
 }
 
+/** The per-concept URL policy from a parsed config, or an empty policy when the `content` key is absent. */
+export function urlPolicyFrom(config: SiteConfig): Record<string, ConceptUrlPolicy> {
+  return config.content ?? {};
+}
+
 /**
  * Replace one named menu in the YAML site-config text and reserialize, preserving every other
  * top-level key (siteName, other menus, settings). Parses into a Document so the rest of the file

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

@@ -5,7 +5,7 @@
 import { redirect, error } from '@sveltejs/kit';
 import { findConcept } from '../content/concepts.js';
 import { frontmatterFromForm, parseMarkdown, dateInputValue, serializeMarkdown } from '../content/frontmatter.js';
-import { isValidId, slugify, filenameFromId } from '../content/ids.js';
+import { isValidId, slugify, filenameFromId, composeDatedId } from '../content/ids.js';
 import { appCredentials, type GithubKeyEnv } from '../github/credentials.js';
 import { listMarkdown, readRaw, commitFile } from '../github/repo.js';
 import { installationToken } from '../github/signing.js';
@@ -153,22 +153,32 @@ export function createContentRoutes(runtime: CairnRuntime, deps: ContentRoutesDe
     }
   }
 
-  /** Create a new entry: validate the slug, refuse to clobber, and redirect to the editor. */
+  /** Create a new entry: validate the slug, compose a dated id when the concept is dated, refuse to clobber. */
   async function createAction(event: ContentEvent): Promise<never> {
     sessionOf(event);
     const concept = conceptOf(runtime, event.params);
     const form = await event.request.formData();
-    const raw = String(form.get('slug') ?? '').trim() || slugify(String(form.get('title') ?? ''));
+    const slug = String(form.get('slug') ?? '').trim() || slugify(String(form.get('title') ?? ''));
+    const date = String(form.get('date') ?? '').trim();
     const bounce = (msg: string): never => {
       throw redirect(303, `/admin/${concept.id}?error=${encodeURIComponent(msg)}`);
     };
-    if (!isValidId(raw)) bounce('Enter a valid slug: lowercase letters, numbers, and hyphens.');
+    if (!isValidId(slug)) return bounce('Enter a valid slug: lowercase letters, numbers, and hyphens.');
+
+    let id = slug;
+    if (concept.routing.dated) {
+      if (!/^\d{4}-\d{2}-\d{2}$/.test(date)) return bounce('Pick a date for this entry.');
+      if (/^\d{4}-/.test(slug)) {
+        return bounce('Leave the date out of the slug; set it in the date field.');
+      }
+      id = composeDatedId(date, slug, concept.datePrefix);
+    }
 
     const token = await mintToken(event.platform?.env ?? {});
-    const existing = await readRaw(runtime.backend, `${concept.dir}/${filenameFromId(raw)}`, token);
-    if (existing !== null) bounce('An entry with that slug already exists.');
+    const existing = await readRaw(runtime.backend, `${concept.dir}/${filenameFromId(id)}`, token);
+    if (existing !== null) return bounce('An entry with that slug already exists.');
 
-    throw redirect(303, `/admin/${concept.id}/${raw}?new=1`);
+    throw redirect(303, `/admin/${concept.id}/${id}?new=1`);
   }
 
   /** Coerce parsed frontmatter to the form-ready values the editor inputs expect. */

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,83 @@
+// cairn-cms: public route loaders (dated-slug design). The factory closes over the site-level
+// index, the runtime render, and the origin. entryLoad and entries are site-wide: one catch-all
+// `[...path]` route resolves any concept by request path through `byPermalink`. The archive, tag,
+// and tag-index loaders stay concept-scoped, keyed by concept id. The index is built in site code
+// from globs, so it stays in the prerender graph and out of the runtime Worker.
+import { error } from '@sveltejs/kit';
+import type { ContentSummary, ContentEntry } from '../delivery/content-index.js';
+import type { SiteIndex } from '../delivery/site-index.js';
+
+/** Injected dependencies for the public loaders. */
+export interface PublicRoutesDeps {
+  site: SiteIndex;
+  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 a site's unified index. */
+export function createPublicRoutes(deps: PublicRoutesDeps) {
+  const { site, render, origin } = deps;
+
+  /** Resolve one concept's index by id, or a 404 (the route names an unconfigured concept). */
+  function indexOf(conceptId: string) {
+    const index = site.concept(conceptId);
+    if (!index) throw error(404, `Unknown content type: ${conceptId}`);
+    return index;
+  }
+
+  /** One entry by request path, rendered through the site renderer, or a 404. */
+  async function entryLoad(event: { url: URL }): Promise<EntryData> {
+    const entry = site.byPermalink(event.url.pathname);
+    if (!entry) throw error(404, `Not found: ${event.url.pathname}`);
+    const { newer, older } = site.adjacent(entry);
+    return { entry, html: await render(entry.body, { stagger: true }), canonicalUrl: origin + entry.permalink, newer, older };
+  }
+
+  /** The chronological archive for one concept: every non-draft summary, newest-first. */
+  function archiveLoad(conceptId: string): ListData {
+    return { entries: indexOf(conceptId).all() };
+  }
+
+  /** All tags with counts for one concept, for a tag index page. */
+  function tagIndexLoad(conceptId: string): TagIndexData {
+    return { tags: indexOf(conceptId).allTags() };
+  }
+
+  /** One tag's entries for one concept, or a 404 when the tag has none. */
+  function tagLoad(conceptId: string, event: { params: { tag: string } }): TagData {
+    const entries = indexOf(conceptId).byTag(event.params.tag);
+    if (entries.length === 0) throw error(404, `No entries tagged "${event.params.tag}"`);
+    return { tag: event.params.tag, entries };
+  }
+
+  /** Prerender enumeration: one `{ path }` per entry across every concept. */
+  function entries(): { path: string }[] {
+    return site.entries();
+  }
+
+  return { entryLoad, archiveLoad, tagIndexLoad, tagLoad, entries };
+}