@glw907/cairn-cms 0.14.0 → 0.18.0

package/src/lib/content/manifest.ts

@@ -0,0 +1,138 @@
+// cairn-cms: the content manifest, a committed JSON projection of the corpus (content-graph
+// design). The files in git stay the source of truth; the manifest exists so request-time admin
+// code reads the content graph without an N+1 GitHub crawl. The build regenerates and verifies
+// it; the save path patches one entry and commits it with the content in one commit. Each entry
+// carries its identity and its outbound cairn: edges, so the manifest is the link graph.
+import { idFromFilename, slugFromId } from './ids.js';
+import { parseMarkdown } from './frontmatter.js';
+import { permalink } from './permalink.js';
+import { extractCairnLinks, type CairnRef, type LinkResolve } from './links.js';
+import type { ConceptDescriptor } from './types.js';
+
+/** One entry's projection: its identity, routing, draft flag, and outbound cairn: edges. */
+export interface ManifestEntry {
+  id: string;
+  concept: string;
+  title: string;
+  date?: string;
+  permalink: string;
+  draft: boolean;
+  links: CairnRef[];
+}
+
+/** The whole corpus as one committed file. `version` guards a future shape migration. */
+export interface Manifest {
+  version: 1;
+  entries: ManifestEntry[];
+}
+
+/** The minimal entry view the preview resolver and (later) the picker read. */
+export interface LinkTarget {
+  concept: string;
+  id: string;
+  permalink: string;
+  title: string;
+  date?: string;
+  draft: boolean;
+}
+
+function basename(path: string): string {
+  const slash = path.lastIndexOf('/');
+  return slash >= 0 ? path.slice(slash + 1) : path;
+}
+
+/** Mirror content-index's frontmatter coercion: a present non-empty string, else undefined. */
+function asString(value: unknown): string | undefined {
+  return typeof value === 'string' && value.trim() ? value : undefined;
+}
+
+/** Mirror content-index's date coercion: an unquoted YAML date is a JS Date, a string is sliced. */
+function asDate(value: unknown): string | undefined {
+  if (value instanceof Date) return Number.isNaN(value.getTime()) ? undefined : value.toISOString().slice(0, 10);
+  if (typeof value === 'string') return value.match(/^\d{4}-\d{2}-\d{2}/)?.[0];
+  return undefined;
+}
+
+/** Build one manifest entry from a content file. Drafts are included and flagged. */
+export function manifestEntryFromFile(descriptor: ConceptDescriptor, file: { path: string; raw: string }): ManifestEntry {
+  const id = idFromFilename(basename(file.path));
+  // Use the same slug rule content-index uses, so the manifest's permalink for an entry always
+  // equals content-index's permalink for it. A cairn link must resolve to one URL whether the
+  // admin preview reads the manifest or the public build reads the content index.
+  const slug = slugFromId(id, descriptor.routing.dated ? descriptor.datePrefix : null);
+  const { frontmatter, body } = parseMarkdown(file.raw);
+  const date = asDate(frontmatter.date);
+  return {
+    id,
+    concept: descriptor.id,
+    title: asString(frontmatter.title) ?? id,
+    date,
+    permalink: permalink(descriptor, { id, slug, date }),
+    draft: frontmatter.draft === true,
+    links: extractCairnLinks(body),
+  };
+}
+
+/** An empty manifest, the starting point when no committed file exists yet. */
+export function emptyManifest(): Manifest {
+  return { version: 1, entries: [] };
+}
+
+function compareRef(a: CairnRef, b: CairnRef): number {
+  return a.concept.localeCompare(b.concept) || a.id.localeCompare(b.id);
+}
+
+/** Serialize canonically: entries sorted by concept then id, links sorted and deduped, a fixed key
+ *  order, two-space pretty, and a trailing newline, so the committed file diffs cleanly in a PR. */
+export function serializeManifest(manifest: Manifest): string {
+  const entries = [...manifest.entries].sort(compareRef).map((e) => ({
+    id: e.id,
+    concept: e.concept,
+    title: e.title,
+    ...(e.date ? { date: e.date } : {}),
+    permalink: e.permalink,
+    draft: e.draft,
+    links: [...e.links].sort(compareRef).map((r) => ({ concept: r.concept, id: r.id })),
+  }));
+  return `${JSON.stringify({ version: 1, entries }, null, 2)}\n`;
+}
+
+/** Parse a committed manifest. Throws on malformed JSON or the wrong shape. */
+export function parseManifest(raw: string): Manifest {
+  const data = JSON.parse(raw) as unknown;
+  if (!data || typeof data !== 'object' || !Array.isArray((data as { entries?: unknown }).entries)) {
+    throw new Error('content manifest: malformed file, expected { version, entries: [] }');
+  }
+  return { version: 1, entries: (data as Manifest).entries };
+}
+
+/** Throw if the committed manifest drifts from what the corpus says. Both sides are compared in the
+ *  canonical serialized form, so semantic equality never spuriously fails. The build calls this so a
+ *  raw-git content edit, which leaves the committed manifest stale, fails the build loudly. */
+export function verifyManifest(built: Manifest, committedRaw: string): void {
+  if (committedRaw !== serializeManifest(built)) {
+    throw new Error(
+      'content manifest is stale: the committed file does not match the corpus. Regenerate it (npm run cairn:manifest) and commit the result.',
+    );
+  }
+}
+
+/** Replace the entry with the same concept and id, or add it. Order does not matter, since
+ *  serializeManifest sorts. This is the save path's incremental patch. */
+export function upsertEntry(manifest: Manifest, entry: ManifestEntry): Manifest {
+  const entries = manifest.entries.filter((e) => !(e.concept === entry.concept && e.id === entry.id));
+  entries.push(entry);
+  return { version: 1, entries };
+}
+
+/** Drop the entry with the given concept and id, if present. The delete path's patch. */
+export function removeEntry(manifest: Manifest, concept: string, id: string): Manifest {
+  return { version: 1, entries: manifest.entries.filter((e) => !(e.concept === concept && e.id === id)) };
+}
+
+/** A resolver backed by manifest targets, for the admin preview. A miss returns undefined, so the
+ *  render step marks the link broken rather than throwing. The build resolver throws instead. */
+export function manifestLinkResolver(targets: { concept: string; id: string; permalink: string }[]): LinkResolve {
+  const byKey = new Map(targets.map((t) => [`${t.concept}/${t.id}`, t.permalink]));
+  return (ref) => byKey.get(`${ref.concept}/${ref.id}`);
+}

package/src/lib/content/types.ts

@@ -11,6 +11,7 @@ import type { ComponentRegistry } from '../render/registry.js';
 import type { IconSet } from '../render/glyph.js';
 import type { DatePrefix } from './ids.js';
 import type { ConceptSchema } from './schema.js';
+import type { LinkResolve } from './links.js';
 
 /** Common to every frontmatter field: the frontmatter key, the form label, and whether it is required. */
 interface FieldBase {
@@ -171,8 +172,13 @@ export interface CairnAdapter {
   };
   backend: BackendConfig;
   sender: SenderConfig;
-  /** The site's one renderer: the editor preview and every public page call it (design decision 4). */
-  render(md: string, opts?: { stagger?: boolean }): string | Promise<string>;
+  /** The site's one renderer: the editor preview and every public page call it (design decision 4).
+   *  `resolve` rewrites cairn: links to live permalinks; the build passes a site-index resolver, the
+   *  preview a manifest one. */
+  render(md: string, opts?: { stagger?: boolean; resolve?: LinkResolve }): string | Promise<string>;
+  /** Repo-relative path to the committed content manifest. Defaults to src/content/.cairn/index.json
+   *  in composeRuntime. It sits outside any concept directory, so content enumeration never globs it. */
+  manifestPath?: string;
   /** Directive component registry; the renderer and the future palette derive from it (seam 3). */
   registry?: ComponentRegistry;
   /** The site's glyph name to SVG path-data map, for the admin icon picker and the renderer. */
@@ -267,7 +273,8 @@ export interface CairnRuntime {
   backend: BackendConfig;
   sender: SenderConfig;
   /** The site's one renderer: the editor preview and every public page call it (design decision 4). */
-  render(md: string, opts?: { stagger?: boolean }): string | Promise<string>;
+  render(md: string, opts?: { stagger?: boolean; resolve?: LinkResolve }): string | Promise<string>;
+  manifestPath: string;
   registry?: ComponentRegistry;
   /** The site's glyph name to SVG path-data map, for the admin icon picker and the renderer. */
   icons?: IconSet;

package/src/lib/delivery/content-index.ts

@@ -84,18 +84,21 @@ export function createContentIndex<F = Record<string, unknown>>(
   descriptor: ConceptDescriptor,
 ): ContentIndex<F> {
   const problems: ContentProblem[] = [];
-  const entries: ContentEntry<F>[] = files.map((file) => {
+  const entries: ContentEntry<F>[] = [];
+  for (const file of files) {
     const id = idFromFilename(basename(file.path));
     const slug = slugFromId(id, descriptor.routing.dated ? descriptor.datePrefix : null);
     const { frontmatter: raw, body } = parseMarkdown(file.raw);
     const date = asDate(raw.date);
     const draft = raw.draft === true;
-    // Validate once at build. The cheap summary stays raw-derived and robust; the typed detail
-    // frontmatter carries the normalized data on success, the raw frontmatter on failure. A
-    // failure is recorded, not thrown, so the query surface does not explode on construction.
+    // Validate once at build. A failure is recorded for the site gate and excluded from the typed
+    // read, so every readable entry's frontmatter is the validator's normalized output, never raw.
     const result = descriptor.validate(raw, body);
-    if (!result.ok) problems.push({ id, draft, errors: result.errors });
-    return {
+    if (!result.ok) {
+      problems.push({ id, draft, errors: result.errors });
+      continue;
+    }
+    entries.push({
       id,
       slug,
       permalink: permalink(descriptor, { id, slug, date }),
@@ -106,10 +109,10 @@ export function createContentIndex<F = Record<string, unknown>>(
       excerpt: deriveExcerpt(body, { description: asString(raw.description) }),
       wordCount: wordCount(body),
       draft,
-      frontmatter: (result.ok ? result.data : raw) as F,
+      frontmatter: result.data as F,
       body,
-    };
-  });
+    });
+  }
 
   // Dated concepts sort newest-first; undated concepts (Pages) sort by title.
   const sorted = [...entries].sort((a, b) =>

package/src/lib/delivery/feeds.ts

@@ -17,7 +17,7 @@ export interface FeedChannel {
 export interface FeedItem {
   title: string;
   url: string;
-  date: string;
+  date?: string;
   updated?: string;
   summary: string;
   contentHtml?: string;
@@ -37,14 +37,22 @@ 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();
+/** Parse a YYYY-MM-DD (or ISO) string as a UTC instant. Returns undefined for an absent or
+ *  unparseable date, so a feed omits the date field rather than emit Invalid Date or throw. */
+function parseFeedDate(date?: string): Date | undefined {
+  if (!date) return undefined;
+  const at = new Date(`${date.slice(0, 10)}T00:00:00.000Z`);
+  return Number.isNaN(at.getTime()) ? undefined : at;
 }
 
-/** 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();
+/** Format a date as an RFC-822 string in UTC, as RSS wants, or undefined when it cannot parse. */
+function rfc822(date?: string): string | undefined {
+  return parseFeedDate(date)?.toUTCString();
+}
+
+/** Format a date as an ISO-8601 instant in UTC, or undefined when it cannot parse. */
+function iso(date?: string): string | undefined {
+  return parseFeedDate(date)?.toISOString();
 }
 
 /** Build an RSS 2.0 document. */
@@ -52,17 +60,20 @@ export function buildRssFeed(channel: FeedChannel, items: FeedItem[]): string {
   const entries = items
     .map((item) => {
       const content = item.contentHtml ?? item.summary;
+      const pubDate = rfc822(item.date);
       return [
         '    <item>',
         `      <title>${escapeXml(item.title)}</title>`,
         `      <link>${escapeXml(item.url)}</link>`,
         `      <guid isPermaLink="true">${escapeXml(item.url)}</guid>`,
-        `      <pubDate>${rfc822(item.date)}</pubDate>`,
+        pubDate ? `      <pubDate>${pubDate}</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');
+      ]
+        .filter((line) => line !== '')
+        .join('\n');
     })
     .join('\n');
 
@@ -95,16 +106,20 @@ export function buildJsonFeed(channel: FeedChannel, items: FeedItem[]): string {
       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 } : {}),
-      })),
+      items: items.map((item) => {
+        const datePublished = iso(item.date);
+        const dateModified = iso(item.updated);
+        return {
+          id: item.url,
+          url: item.url,
+          title: item.title,
+          summary: item.summary,
+          ...(datePublished ? { date_published: datePublished } : {}),
+          ...(dateModified ? { date_modified: dateModified } : {}),
+          ...(item.contentHtml ? { content_html: item.contentHtml } : { content_text: item.summary }),
+          ...(item.tags && item.tags.length ? { tags: item.tags } : {}),
+        };
+      }),
     },
     null,
     2,

package/src/lib/delivery/index.ts

@@ -25,6 +25,7 @@ export type { Page } from './paginate.js';
 export { rssResponse, jsonFeedResponse, sitemapResponse, robotsResponse } from './responses.js';
 export { jsonLdScript } from './json-ld.js';
 export { permalink } from '../content/permalink.js';
+export { buildSiteManifest, buildLinkResolver } from './manifest.js';
 export { createPublicRoutes } from '../sveltekit/public-routes.js';
 export type {
   PublicRoutesDeps,

package/src/lib/delivery/manifest.ts

@@ -0,0 +1,38 @@
+// cairn-cms: the build-side manifest builder and the build link resolver (content-graph design).
+// buildSiteManifest mirrors createSiteIndexes: it maps the site descriptors over the per-concept
+// globs and projects each file to a manifest row. buildLinkResolver reads the site index, which is
+// fresh from the files at build, and throws on a missing target so a dangling cairn: token fails
+// the build (the backstop). The admin preview uses manifestLinkResolver instead.
+import { siteDescriptors } from './site-descriptors.js';
+import { fromGlob } from './content-index.js';
+import { emptyManifest, manifestEntryFromFile } from '../content/manifest.js';
+import type { Manifest } from '../content/manifest.js';
+import type { LinkResolve } from '../content/links.js';
+import type { SiteIndex } from './site-index.js';
+import type { SiteConfig } from '../nav/site-config.js';
+import type { CairnAdapter } from '../content/types.js';
+import type { SiteGlobs } from './site-indexes.js';
+
+/** Build the whole-corpus manifest from a site's adapter, config, and per-concept globs. Drafts are
+ *  included and flagged, so the admin picker and the guards see the full graph. */
+export function buildSiteManifest<A extends CairnAdapter>(adapter: A, config: SiteConfig, globs: SiteGlobs<A>): Manifest {
+  const globRecord = globs as Record<string, Record<string, string> | undefined>;
+  const manifest = emptyManifest();
+  for (const descriptor of siteDescriptors(adapter, config)) {
+    const record = globRecord[descriptor.id] ?? {};
+    for (const file of fromGlob(record)) {
+      manifest.entries.push(manifestEntryFromFile(descriptor, file));
+    }
+  }
+  return manifest;
+}
+
+/** A resolver backed by the site index, for the build. A miss throws, so a dangling cairn: token
+ *  fails the prerender (the build backstop). The preview uses manifestLinkResolver, which marks. */
+export function buildLinkResolver(site: SiteIndex): LinkResolve {
+  return (ref) => {
+    const url = site.concept(ref.concept)?.byId(ref.id)?.permalink;
+    if (!url) throw new Error(`cairn link target not found: cairn:${ref.concept}/${ref.id}`);
+    return url;
+  };
+}

package/src/lib/delivery/site-indexes.ts

@@ -39,10 +39,22 @@ export function createSiteIndexes<const A extends CairnAdapter>(
   opts: { validate?: boolean } = {},
 ): SiteIndexes<A> {
   const descriptors = siteDescriptors(adapter, config);
+  const globRecord = globs as Record<string, Record<string, string> | undefined>;
   const byConcept: Record<string, ContentIndex> = {};
   const conceptIndexes: ConceptIndex[] = [];
   for (const descriptor of descriptors) {
-    const record = (globs as Record<string, Record<string, string> | undefined>)[descriptor.id] ?? {};
+    if (descriptor.id === 'site') {
+      throw new Error(
+        'createSiteIndexes: a concept cannot be named "site", which is the reserved cross-concept resolver key',
+      );
+    }
+    if (!Object.prototype.hasOwnProperty.call(globRecord, descriptor.id)) {
+      const passed = Object.keys(globRecord);
+      throw new Error(
+        `createSiteIndexes: no glob passed for concept "${descriptor.id}"; pass its import.meta.glob (an empty {} for an intentionally empty concept). Globs passed: ${passed.length ? passed.join(', ') : '(none)'}`,
+      );
+    }
+    const record = globRecord[descriptor.id] ?? {};
     const index = createContentIndex(fromGlob(record), descriptor);
     byConcept[descriptor.id] = index;
     conceptIndexes.push({ descriptor, index });

package/src/lib/env.ts

@@ -13,6 +13,19 @@ export function requireOrigin(env: { PUBLIC_ORIGIN?: string }): string {
   if (!origin) {
     throw new Error('PUBLIC_ORIGIN is not configured');
   }
+  let hostname: string;
+  try {
+    hostname = new URL(origin).hostname;
+  } catch {
+    throw new Error(`PUBLIC_ORIGIN is not a valid URL, got ${origin}`);
+  }
+  // The magic-link origin must be https in production so the link and the __Host- cookie are
+  // origin-bound. http is allowed only for local dev on localhost or 127.0.0.1, matched exactly so
+  // a lookalike host like localhost.example.com cannot skip the https requirement.
+  const isLocal = hostname === 'localhost' || hostname === '127.0.0.1';
+  if (!origin.startsWith('https://') && !isLocal) {
+    throw new Error(`PUBLIC_ORIGIN must be https in production, got ${origin}`);
+  }
   return origin;
 }
 

package/src/lib/github/repo.ts

@@ -136,3 +136,106 @@ export async function commitFile(
   if (!res.ok) throw new Error(`GitHub commit ${path} failed: ${res.status} ${await res.text()}`);
   return ((await res.json()) as { commit: { sha: string } }).commit.sha;
 }
+
+/** A path change for an atomic commit: write `content`, or delete the path when `content` is null. */
+export interface FileChange {
+  path: string;
+  content: string | null;
+}
+
+/** A Git Trees API change entry: a blob written from raw content, or a `sha: null` delete. */
+interface TreeChange {
+  path: string;
+  mode: '100644';
+  type: 'blob';
+  content?: string;
+  sha?: null;
+}
+
+/** A Git Data API URL under the repo's `git/` namespace. */
+function gitUrl(repo: RepoRef, suffix: string): string {
+  return `${API}/repos/${repo.owner}/${repo.repo}/git/${suffix}`;
+}
+
+/** The branch head commit sha, through the Git Data API single-ref read. */
+async function headCommitSha(repo: RepoRef, token: string): Promise<string> {
+  const res = await fetch(gitUrl(repo, `ref/heads/${encodeURIComponent(repo.branch)}`), {
+    headers: ghHeaders('application/vnd.github+json', token),
+  });
+  if (!res.ok) throw new Error(`GitHub ref ${repo.branch} failed: ${res.status}`);
+  return ((await res.json()) as { object: { sha: string } }).object.sha;
+}
+
+/** The base tree sha of a commit. */
+async function commitTreeSha(repo: RepoRef, commitSha: string, token: string): Promise<string> {
+  const res = await fetch(gitUrl(repo, `commits/${commitSha}`), {
+    headers: ghHeaders('application/vnd.github+json', token),
+  });
+  if (!res.ok) throw new Error(`GitHub commit ${commitSha} failed: ${res.status}`);
+  return ((await res.json()) as { tree: { sha: string } }).tree.sha;
+}
+
+/** Map file changes to Git Trees API entries, encoding a null content as a delete. */
+function treeChanges(changes: FileChange[]): TreeChange[] {
+  return changes.map((c) =>
+    c.content === null
+      ? { path: c.path, mode: '100644', type: 'blob', sha: null }
+      : { path: c.path, mode: '100644', type: 'blob', content: c.content },
+  );
+}
+
+/** Retries after the initial attempt when the branch moves under an atomic commit. */
+const COMMIT_RETRIES = 3;
+
+/**
+ * Commit several path changes in one commit over the Git Data API. The author is the editor; the
+ * committer is omitted, so GitHub attributes the commit to the App. Returns the new commit sha.
+ * Builds the new tree on the current head's tree, so paths not named here are preserved.
+ *
+ * Caller preconditions this layer cannot enforce (the save and lifecycle paths must): every
+ * `path` is confined to the site's content directories (the App token can write anywhere in the
+ * repo), and `author` is derived from the verified server-side session, never request input.
+ *
+ * An empty change set is rejected, since it would otherwise push an empty commit that triggers a
+ * site redeploy for no content change.
+ */
+export async function commitFiles(
+  repo: RepoRef,
+  changes: FileChange[],
+  opts: { message: string; author: CommitAuthor },
+  token: string,
+): Promise<string> {
+  if (changes.length === 0) throw new Error('commitFiles: no changes to commit');
+  const tree = treeChanges(changes);
+  for (let attempt = 0; attempt <= COMMIT_RETRIES; attempt++) {
+    const parent = await headCommitSha(repo, token);
+    const baseTree = await commitTreeSha(repo, parent, token);
+
+    const treeRes = await fetch(gitUrl(repo, 'trees'), {
+      method: 'POST',
+      headers: { ...ghHeaders('application/vnd.github+json', token), 'Content-Type': 'application/json' },
+      body: JSON.stringify({ base_tree: baseTree, tree }),
+    });
+    if (!treeRes.ok) throw new Error(`GitHub tree create failed: ${treeRes.status} ${await treeRes.text()}`);
+    const newTree = ((await treeRes.json()) as { sha: string }).sha;
+
+    const commitRes = await fetch(gitUrl(repo, 'commits'), {
+      method: 'POST',
+      headers: { ...ghHeaders('application/vnd.github+json', token), 'Content-Type': 'application/json' },
+      body: JSON.stringify({ message: opts.message, tree: newTree, parents: [parent], author: opts.author }),
+    });
+    if (!commitRes.ok) throw new Error(`GitHub commit create failed: ${commitRes.status} ${await commitRes.text()}`);
+    const newCommit = ((await commitRes.json()) as { sha: string }).sha;
+
+    const refRes = await fetch(gitUrl(repo, `refs/heads/${encodeURIComponent(repo.branch)}`), {
+      method: 'PATCH',
+      headers: { ...ghHeaders('application/vnd.github+json', token), 'Content-Type': 'application/json' },
+      body: JSON.stringify({ sha: newCommit, force: false }),
+    });
+    if (refRes.ok) return newCommit;
+    // A non-fast-forward means the branch moved; retry on the new head so a concurrent commit
+    // is preserved. Any other failure is not a race, so surface it.
+    if (refRes.status !== 422) throw new Error(`GitHub ref update failed: ${refRes.status} ${await refRes.text()}`);
+  }
+  throw new CommitConflictError(`${repo.branch} (atomic commit)`);
+}

package/src/lib/github/signing.ts

@@ -79,6 +79,38 @@ export async function installationToken(creds: AppCredentials): Promise<string>
   return ((await res.json()) as { token: string }).token;
 }
 
+interface CachedToken {
+  token: string;
+  expiresAt: number;
+}
+
+/**
+ * Build an installation-token cache. A module-global instance memoizes the minted token per
+ * installation for most of its one-hour life, so a warm Worker isolate reuses it across requests
+ * instead of re-signing and re-calling GitHub on every list and commit. A cold isolate re-mints,
+ * which is always safe. This mirrors the default of @octokit/auth-app, which caches installation
+ * tokens in memory and returns them until expiry. The TTL stays under GitHub's documented one-hour
+ * lifetime, so a fixed margin avoids parsing the API expiry. `mint` and `now` are injected so the
+ * cache is testable with no network call and no real clock.
+ */
+export function createInstallationTokenCache(
+  mint: (creds: AppCredentials) => Promise<string> = installationToken,
+  now: () => number = () => Date.now(),
+  ttlMs = 55 * 60 * 1000,
+): (creds: AppCredentials) => Promise<string> {
+  const cache = new Map<string, CachedToken>();
+  return async function get(creds: AppCredentials): Promise<string> {
+    const hit = cache.get(creds.installationId);
+    if (hit && hit.expiresAt > now()) return hit.token;
+    const token = await mint(creds);
+    cache.set(creds.installationId, { token, expiresAt: now() + ttlMs });
+    return token;
+  };
+}
+
+/** The shared installation-token cache, one instance per Worker isolate. */
+export const cachedInstallationToken = createInstallationTokenCache();
+
 /**
  * Deploy-time self-test for the App signer: sign a dummy JWT with the configured key. It
  * exercises the brittle PKCS#1-to-PKCS#8 conversion and the Web Crypto import and sign with

package/src/lib/index.ts

@@ -49,6 +49,22 @@ export {
   composeDatedId,
 } from './content/ids.js';
 export type { DatePrefix } from './content/ids.js';
+// Internal-link token and the committed content manifest (content-graph design). The corpus
+// builder and the request-time resolver ship from the delivery entry; this surface is the
+// grammar, the manifest operations, and their types a migrating site adopts.
+export { parseCairnToken, extractCairnLinks } from './content/links.js';
+export type { CairnRef, LinkResolve } from './content/links.js';
+export {
+  serializeManifest,
+  parseManifest,
+  emptyManifest,
+  verifyManifest,
+  upsertEntry,
+  removeEntry,
+  manifestEntryFromFile,
+  manifestLinkResolver,
+} from './content/manifest.js';
+export type { Manifest, ManifestEntry, LinkTarget } from './content/manifest.js';
 // Render engine (Plan 04): generic directive pipeline; sites own the component registry.
 export { defineRegistry, emptyValues } from './render/registry.js';
 export type {

package/src/lib/render/pipeline.ts

@@ -6,23 +6,50 @@ import remarkRehype from 'remark-rehype';
 import rehypeRaw from 'rehype-raw';
 import rehypeSlug from 'rehype-slug';
 import rehypeStringify from 'rehype-stringify';
+import rehypeSanitize from 'rehype-sanitize';
+import type { Schema } from 'hast-util-sanitize';
+import { VFile } from 'vfile';
+import { buildSanitizeSchema, rehypeAnchorRel } from './sanitize-schema.js';
 import { remarkDirectiveStamp } from './remark-directives.js';
+import { remarkResolveCairnLinks, CAIRN_RESOLVE } from './resolve-links.js';
 import { rehypeDispatch } from './rehype-dispatch.js';
 import type { ComponentRegistry } from './registry.js';
+import type { LinkResolve } from '../content/links.js';
 
 export interface RendererOptions {
   /** Stamp a `data-rise` ordinal (0, 1, 2, …) on each top-level component so a site's
    *  CSS can drive an entrance-cascade delay off it. Omit for no stagger. The ordinal
    *  is inert, so a consumer's sanitize floor can keep `data-rise` and drop `style`. */
   stagger?: boolean;
+  /** Extend the sanitize allowlist. Receives cairn's default schema (defaultSchema plus the
+   *  directive markers and the common benign tags) and returns the schema to use. Add to the
+   *  allowlist for the benign HTML a site's content needs; start from the argument so the
+   *  dangerous strip is preserved. */
+  sanitizeSchema?: (defaults: Schema) => Schema;
+  /** Developer-only escape hatch: disable the sanitize floor entirely. This reintroduces the XSS
+   *  vector the floor closes, so it is only for a site whose content is fully developer-controlled.
+   *  It is a code-level adapter decision, never an editor-facing setting. */
+  unsafeDisableSanitize?: boolean;
 }
 
 /** Compose a site's render pipeline from its component registry: directive syntax to
  *  stamped markers to registry-built hast. Returns `renderMarkdown` plus the remark/
  *  rehype plugin arrays (so the admin editor preview can reuse the exact same set). */
 export function createRenderer(registry: ComponentRegistry, options: RendererOptions = {}) {
-  const remarkPlugins: PluggableList = [remarkDirective, [remarkDirectiveStamp, registry]];
-  const rehypePlugins: PluggableList = [rehypeRaw, [rehypeDispatch, registry, options.stagger], rehypeSlug];
+  const remarkPlugins: PluggableList = [remarkDirective, [remarkDirectiveStamp, registry], remarkResolveCairnLinks];
+  // The sanitize floor runs after rehype-raw (so author raw HTML is parsed, then cleaned) and
+  // before the dispatch (so the site's trusted build() output and its inline SVG icons are never
+  // sanitized). The anchor-rel hardening runs last so it also covers component-built anchors.
+  const floor: PluggableList = options.unsafeDisableSanitize
+    ? []
+    : [[rehypeSanitize, buildSanitizeSchema(registry, options.sanitizeSchema)]];
+  const rehypePlugins: PluggableList = [
+    rehypeRaw,
+    ...floor,
+    [rehypeDispatch, registry, options.stagger],
+    rehypeSlug,
+    rehypeAnchorRel,
+  ];
   const processor = unified()
     .use(remarkParse)
     .use(remarkGfm)
@@ -33,6 +60,9 @@ export function createRenderer(registry: ComponentRegistry, options: RendererOpt
   return {
     remarkPlugins,
     rehypePlugins,
-    renderMarkdown: async (content: string): Promise<string> => String(await processor.process(content)),
+    renderMarkdown: async (content: string, opts: { resolve?: LinkResolve } = {}): Promise<string> => {
+      const file = new VFile({ value: content, data: { [CAIRN_RESOLVE]: opts.resolve } });
+      return String(await processor.process(file));
+    },
   };
 }