@glw907/cairn-cms 0.24.0 → 0.29.0

package/src/lib/content/compose.ts

@@ -3,18 +3,27 @@
 // the same way and contributes the same kinds of things: nav entries, route logic,
 // concepts, components, field types, and save hooks. Shaped now so the extension contract
 // is additive later.
-import type { AdminPanel, CairnAdapter, CairnExtension, CairnRuntime, ConceptConfig, ConceptUrlPolicy, FieldTypeDef } from './types.js';
-import { normalizeConcepts } from './concepts.js';
+import type { AdminPanel, CairnAdapter, CairnExtension, CairnRuntime, ConceptConfig, FieldTypeDef } from './types.js';
+import { resolveConcepts } from './concepts.js';
+import type { SiteConfig } from '../nav/site-config.js';
+
+/** The input to {@link composeRuntime}. `siteConfig` is required so the per-concept URL policy is
+ *  always derived from one source and can never be silently dropped. `extensions` fold in after the
+ *  adapter's concepts. */
+export interface ComposeInput {
+  adapter: CairnAdapter;
+  siteConfig: SiteConfig;
+  extensions?: CairnExtension[];
+}
 
 /**
- * Fold an adapter and any extensions into the composed runtime (seam 2). Extension concepts
- * merge after the adapter's. The asset slot (seam 4) passes through untouched.
+ * Fold an adapter and any extensions into the composed runtime (seam 2). The per-concept URL policy
+ * is derived from the site config, the same source the delivery path uses, so the runtime and
+ * delivery permalinks cannot diverge. Extension concepts merge after the adapter's. The asset slot
+ * (seam 4) passes through untouched.
  */
-export function composeRuntime(
-  adapter: CairnAdapter,
-  extensions: CairnExtension[] = [],
-  urlPolicy: Record<string, ConceptUrlPolicy | undefined> = {},
-): CairnRuntime {
+export function composeRuntime({ adapter, siteConfig, extensions = [] }: ComposeInput): CairnRuntime {
+  if (!siteConfig) throw new Error('composeRuntime needs a site config to derive the URL policy');
   const content: Record<string, ConceptConfig | undefined> = { ...adapter.content };
   const adminPanels: AdminPanel[] = [];
   const fieldTypes: FieldTypeDef[] = [];
@@ -27,7 +36,7 @@ export function composeRuntime(
   }
   return {
     siteName: adapter.siteName,
-    concepts: normalizeConcepts(content, urlPolicy),
+    concepts: resolveConcepts(content, siteConfig),
     backend: adapter.backend,
     sender: adapter.sender,
     render: adapter.render,

package/src/lib/content/concepts.ts

@@ -4,6 +4,7 @@
 // future Fragments concept attaches by adding one key under `content` and one routing
 // entry, with no reshape here.
 import type { ConceptConfig, ConceptDescriptor, ConceptUrlPolicy, RoutingRule } from './types.js';
+import { urlPolicyFrom, type SiteConfig } from '../nav/site-config.js';
 
 /**
  * Concept-fixed routing, keyed by concept id (spec §7.2). Posts are dated feed entries;
@@ -28,6 +29,43 @@ function defaultPermalink(id: string): string {
   return id === 'pages' ? '/:slug' : `/${id}/:slug`;
 }
 
+/** Permalink tokens the resolver understands. */
+const KNOWN_TOKENS = new Set(['slug', 'year', 'month', 'day']);
+/** The date-bearing tokens; valid only for a dated concept. */
+const DATE_TOKENS = new Set(['year', 'month', 'day']);
+/** The valid date-prefix granularities. A runtime check, since the YAML is untyped. */
+const DATE_PREFIXES = new Set<string>(['year', 'month', 'day']);
+
+/**
+ * Validate one concept's URL policy at build, so a misconfigured permalink or datePrefix fails loudly
+ * here rather than emitting a wrong or defaulted URL at render. The permalink must be root-relative and
+ * use only known tokens, a date token requires a dated concept, and the datePrefix must be in range.
+ */
+function validateUrlPolicy(id: string, policy: ConceptUrlPolicy, dated: boolean): void {
+  if (policy.permalink !== undefined) {
+    const pattern = policy.permalink;
+    if (!pattern.startsWith('/')) {
+      throw new Error(`cairn: concept "${id}" permalink "${pattern}" must start with "/"`);
+    }
+    for (const match of pattern.matchAll(/:(\w+)/g)) {
+      const token = match[1];
+      if (!KNOWN_TOKENS.has(token)) {
+        throw new Error(`cairn: concept "${id}" permalink "${pattern}" uses unknown token ":${token}"`);
+      }
+      if (DATE_TOKENS.has(token) && !dated) {
+        throw new Error(
+          `cairn: concept "${id}" is not dated, so permalink "${pattern}" cannot use the date token ":${token}"`,
+        );
+      }
+    }
+  }
+  if (policy.datePrefix !== undefined && !DATE_PREFIXES.has(policy.datePrefix)) {
+    throw new Error(
+      `cairn: concept "${id}" datePrefix "${policy.datePrefix}" must be one of year, month, day`,
+    );
+  }
+}
+
 /**
  * Normalize an adapter's declared concepts into uniform descriptors (seam 1). URL policy
  * (`permalink`, `datePrefix`) comes from the YAML site-config, passed here as `urlPolicy` keyed by
@@ -41,6 +79,14 @@ export function normalizeConcepts(
   routing: Readonly<Record<string, RoutingRule>> = CONCEPT_ROUTING,
 ): ConceptDescriptor[] {
   const descriptors: ConceptDescriptor[] = [];
+  const declaredConcepts = new Set(
+    Object.keys(content).filter((key) => content[key] !== undefined),
+  );
+  for (const key of Object.keys(urlPolicy)) {
+    if (!declaredConcepts.has(key)) {
+      throw new Error(`cairn: URL policy names concept "${key}", which is not declared under content`);
+    }
+  }
   for (const [id, config] of Object.entries(content)) {
     if (!config) continue;
     const summaryFields = config.summaryFields ?? [];
@@ -51,12 +97,14 @@ export function normalizeConcepts(
         `cairn: concept "${id}" summaryFields key "${undeclared}" is not a declared field`,
       );
     }
+    const conceptRouting = routing[id] ?? DEFAULT_ROUTING;
     const policy = urlPolicy[id] ?? {};
+    validateUrlPolicy(id, policy, conceptRouting.dated);
     descriptors.push({
       id,
       label: config.label ?? defaultLabel(id),
       dir: config.dir,
-      routing: routing[id] ?? DEFAULT_ROUTING,
+      routing: conceptRouting,
       permalink: policy.permalink ?? defaultPermalink(id),
       datePrefix: policy.datePrefix ?? 'day',
       fields: config.schema.fields,
@@ -67,6 +115,18 @@ export function normalizeConcepts(
   return descriptors;
 }
 
+/**
+ * Resolve a site's concept descriptors from its content map and parsed site config. The admin runtime
+ * (composeRuntime) and the delivery layer (siteDescriptors) both call this, so the per-concept URL
+ * policy is derived once from the YAML and the runtime and delivery permalinks cannot diverge.
+ */
+export function resolveConcepts(
+  content: Record<string, ConceptConfig | undefined>,
+  siteConfig: SiteConfig,
+): ConceptDescriptor[] {
+  return normalizeConcepts(content, urlPolicyFrom(siteConfig));
+}
+
 /** Look up a normalized concept by id, or undefined when the site does not enable it. */
 export function findConcept(
   concepts: ConceptDescriptor[],

package/src/lib/content/identity.ts

@@ -0,0 +1,60 @@
+// cairn-cms: a content entry's URL identity in one place (engine-hardening pass 3). The id, the
+// slug, the date, and the permalink are computed here, so the content index and the manifest cannot
+// drift on what an entry's URL is. A cairn: link resolves through the manifest in the admin preview
+// and through the content index in the public build, so the two must agree by construction.
+import { idFromFilename, slugFromId } from './ids.js';
+import { permalink } from './permalink.js';
+import type { ConceptDescriptor } from './types.js';
+
+/** A content entry's resolved URL identity. */
+export interface EntryIdentity {
+  id: string;
+  slug: string;
+  date?: string;
+  permalink: string;
+}
+
+/** The basename of a glob path: the segment after the last slash, or the whole path. */
+function basename(path: string): string {
+  const slash = path.lastIndexOf('/');
+  return slash >= 0 ? path.slice(slash + 1) : path;
+}
+
+/** A present, non-empty string, else undefined. The read-model string coercion. */
+export function asString(value: unknown): string | undefined {
+  return typeof value === 'string' && value.trim() ? value : undefined;
+}
+
+/** A YYYY-MM-DD date. An unquoted YAML date parses as a JS Date; a string is sliced to its date head. */
+export 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;
+}
+
+/** Tags as an array, empty when the file declares none. */
+export function asTags(value: unknown): string[] {
+  return Array.isArray(value) ? value.map(String) : [];
+}
+
+/** A content entry's id: its filename stem (the date prefix is part of a dated id). */
+export function entryId(path: string): string {
+  return idFromFilename(basename(path));
+}
+
+/**
+ * Resolve a content entry's URL identity from its concept descriptor, its file path, and its parsed
+ * frontmatter. The slug strips the leading date prefix for a dated concept and is the id verbatim for
+ * an undated one. The permalink is the one resolver every reader shares. The caller parses the markdown
+ * once and passes the frontmatter, so there is no second parse here.
+ */
+export function entryIdentity(
+  descriptor: ConceptDescriptor,
+  path: string,
+  frontmatter: Record<string, unknown>,
+): EntryIdentity {
+  const id = entryId(path);
+  const slug = slugFromId(id, descriptor.routing.dated ? descriptor.datePrefix : null);
+  const date = asDate(frontmatter.date);
+  return { id, slug, date, permalink: permalink(descriptor, { id, slug, date }) };
+}

package/src/lib/content/manifest.ts

@@ -3,9 +3,8 @@
 // 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 { entryIdentity, asString } from './identity.js';
 import { extractCairnLinks, type CairnRef, type LinkResolve } from './links.js';
 import type { ConceptDescriptor } from './types.js';
 
@@ -36,38 +35,18 @@ export interface LinkTarget {
   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. */
+/** Build one manifest entry from a content file. Drafts are included and flagged. The id, date, and
+ *  permalink come from entryIdentity, the same source content-index uses, so a cairn: link resolves to
+ *  one URL whether the admin preview reads the manifest or the public build reads the content index. */
 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);
+  const { id, date, permalink } = entryIdentity(descriptor, file.path, frontmatter);
   return {
     id,
     concept: descriptor.id,
     title: asString(frontmatter.title) ?? id,
     date,
-    permalink: permalink(descriptor, { id, slug, date }),
+    permalink,
     draft: frontmatter.draft === true,
     links: extractCairnLinks(body),
   };
@@ -140,15 +119,71 @@ export function parseManifest(raw: string): Manifest {
   return { version: 1, entries: obj.entries as ManifestEntry[] };
 }
 
-/** 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.',
+/** A changed entry and the fields that differ between the built and committed manifests. */
+export interface ManifestEntryDiff {
+  concept: string;
+  id: string;
+  fields: string[];
+}
+
+/** The drift between a freshly built manifest and the committed one, keyed by concept+id. */
+export interface ManifestDiff {
+  added: ManifestEntry[];
+  removed: ManifestEntry[];
+  changed: ManifestEntryDiff[];
+}
+
+const keyOf = (e: ManifestEntry) => `${e.concept}/${e.id}`;
+
+/** Compare a built manifest against a committed one, keyed by concept+id (the same identity
+ *  upsertEntry and removeEntry use). A changed entry names the fields that differ. Pure, so it is
+ *  unit-tested apart from any build. */
+export function diffManifests(built: Manifest, committed: Manifest): ManifestDiff {
+  const builtByKey = new Map(built.entries.map((e) => [keyOf(e), e]));
+  const committedByKey = new Map(committed.entries.map((e) => [keyOf(e), e]));
+  const added = built.entries.filter((e) => !committedByKey.has(keyOf(e)));
+  const removed = committed.entries.filter((e) => !builtByKey.has(keyOf(e)));
+  const changed: ManifestEntryDiff[] = [];
+  for (const b of built.entries) {
+    const c = committedByKey.get(keyOf(b));
+    if (!c) continue;
+    // ManifestEntry has no index signature, so read its keys through an unknown-cast record.
+    const br = b as unknown as Record<string, unknown>;
+    const cr = c as unknown as Record<string, unknown>;
+    const fields = [...new Set([...Object.keys(b), ...Object.keys(c)])].filter(
+      (k) => JSON.stringify(br[k]) !== JSON.stringify(cr[k]),
     );
+    if (fields.length > 0) changed.push({ concept: b.concept, id: b.id, fields });
   }
+  return { added, removed, changed };
+}
+
+/** Format a diff into a short human-readable block for a build error. */
+function formatDiff(d: ManifestDiff): string {
+  const lines: string[] = [];
+  for (const e of d.added) lines.push(`  + ${keyOf(e)}`);
+  for (const e of d.removed) lines.push(`  - ${keyOf(e)}`);
+  for (const e of d.changed) lines.push(`  ~ ${e.concept}/${e.id} (${e.fields.join(', ')})`);
+  return lines.join('\n');
+}
+
+/** Throw if the committed manifest drifts from what the corpus says. The canonical serialized form
+ *  is the fast-path equality guard, so semantic equality never spuriously fails. On a mismatch the
+ *  error names the added, removed, and changed entries, so a raw-git content edit that leaves the
+ *  committed manifest stale fails the build loudly with what drifted. */
+export function verifyManifest(built: Manifest, committedRaw: string): void {
+  const builtRaw = serializeManifest(built);
+  if (committedRaw === builtRaw) return;
+  // Diff the canonical built form, not the raw one. serializeManifest sorts each entry's links, so a
+  // build whose links are in extraction order would otherwise report a false (links) drift for an
+  // entry whose link set is identical and only the order differs. Reuse the serialized form so both
+  // sides are canonical.
+  const diff = diffManifests(parseManifest(builtRaw), parseManifest(committedRaw));
+  throw new Error(
+    'content manifest is stale: the committed file does not match the corpus.\n' +
+      formatDiff(diff) +
+      '\nRegenerate 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

package/src/lib/content/validate.ts

@@ -9,7 +9,10 @@ import { dateInputValue, isCalendarDate } from './frontmatter.js';
  * Validate raw frontmatter against a field list. Required text and date fields must be
  * non-empty; required tag fields must be non-empty lists. A present boolean coerces to `true`
  * and an unchecked one is omitted; a present tag field coerces to a string array and an empty
- * one is omitted; an empty optional text or date field is omitted, so the normalized data
+ * one is omitted, so validated data carries no key for an absent tag field (`tags` or `freetags`).
+ * The delivery read model
+ * (`ContentSummary.tags`) fills that case with an empty array; the two layers differ on purpose.
+ * An empty optional text or date field is omitted, so the normalized data
  * carries only meaningful values and committed frontmatter stays minimal. Returns the
  * normalized data, or field-keyed errors when any required field is empty.
  *

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

@@ -3,8 +3,7 @@
 // returns cheap plain-data summaries plus an on-demand detail lookup. It is concept-generic:
 // every operation reads the descriptor and its routing rule, never a hardcoded concept id.
 import { parseMarkdown } from '../content/frontmatter.js';
-import { idFromFilename, slugFromId } from '../content/ids.js';
-import { permalink } from '../content/permalink.js';
+import { entryId, entryIdentity, asDate, asString, asTags } from '../content/identity.js';
 import { deriveExcerpt, wordCount } from './excerpt.js';
 import type { ConceptDescriptor } from '../content/types.js';
 
@@ -25,6 +24,10 @@ export interface ContentSummary {
   title: string;
   date?: string;
   updated?: string;
+  /** The entry's tags, always present as an array and empty when the file declares none. This is the
+   *  read-model normalization. It differs on purpose from the validated `frontmatter.tags`, which the
+   *  validator omits when empty, so a published file carries no `tags: []` noise. Read `tags` here for
+   *  a list; read `frontmatter.tags` only when you need the validated, possibly-absent value. */
   tags: string[];
   excerpt: string;
   wordCount: number;
@@ -66,25 +69,6 @@ export function fromGlob(record: Record<string, string>): RawFile[] {
   return Object.entries(record).map(([path, raw]) => ({ path, raw }));
 }
 
-function basename(path: string): string {
-  const slash = path.lastIndexOf('/');
-  return slash >= 0 ? path.slice(slash + 1) : path;
-}
-
-function asString(value: unknown): string | undefined {
-  return typeof value === 'string' && value.trim() ? value : undefined;
-}
-
-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;
-}
-
-function asTags(value: unknown): string[] {
-  return Array.isArray(value) ? value.map(String) : [];
-}
-
 /** Build a concept's index from its raw files and normalized descriptor. */
 export function createContentIndex<F = Record<string, unknown>>(
   files: RawFile[],
@@ -93,18 +77,19 @@ export function createContentIndex<F = Record<string, unknown>>(
   const problems: ContentProblem[] = [];
   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 id = entryId(file.path);
     const draft = raw.draft === true;
-    // 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.
+    // Validate before resolving the permalink. A date-token permalink throws on an entry with no
+    // valid date; the validate gate records that as a content problem rather than aborting the whole
+    // index build, so one bad entry degrades to a skip, not a crash. A failure is also excluded from
+    // the typed read, so every readable entry's frontmatter is the validator's normalized output.
     const result = descriptor.validate(raw, body);
     if (!result.ok) {
       problems.push({ id, draft, errors: result.errors });
       continue;
     }
+    const { slug, date, permalink } = entryIdentity(descriptor, file.path, raw);
     const summaryFieldValues: Record<string, unknown> = {};
     for (const key of descriptor.summaryFields) {
       if (key in result.data) summaryFieldValues[key] = result.data[key];
@@ -113,7 +98,7 @@ export function createContentIndex<F = Record<string, unknown>>(
       concept: descriptor.id,
       id,
       slug,
-      permalink: permalink(descriptor, { id, slug, date }),
+      permalink,
       title: asString(raw.title) ?? id,
       date,
       updated: asDate(raw.updated),

package/src/lib/delivery/data.ts

@@ -0,0 +1,26 @@
+// cairn-cms: the node-safe delivery data surface (@glw907/cairn-cms/delivery/data). The pure corpus
+// projections a SvelteKit site or a plain-Node tool reads, with no @sveltejs/kit and no .svelte in
+// the graph. The full ./delivery barrel re-exports this and adds the route loaders.
+export { createContentIndex, fromGlob } from './content-index.js';
+export type { RawFile, ContentSummary, ContentEntry, ContentIndex, ContentProblem } from './content-index.js';
+export { createSiteIndex } from './site-index.js';
+export type { SiteIndex, ConceptIndex } from './site-index.js';
+export { createSiteIndexes } from './site-indexes.js';
+export type { SiteIndexes, SiteGlobs } from './site-indexes.js';
+export { siteDescriptors } from './site-descriptors.js';
+export { deriveExcerpt, wordCount } from './excerpt.js';
+export { buildRssFeed, buildJsonFeed } from './feeds.js';
+export type { FeedChannel, FeedItem } from './feeds.js';
+export { buildSitemap } from './sitemap.js';
+export type { SitemapUrl } from './sitemap.js';
+export { buildRobots } from './robots.js';
+export { buildSeoMeta } from './seo.js';
+export type { SeoInput, SeoMeta } from './seo.js';
+export { readSeoFields, resolveImageUrl } from './seo-fields.js';
+export type { SeoFields } from './seo-fields.js';
+export { paginate } from './paginate.js';
+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';

package/src/lib/delivery/index.ts

@@ -1,31 +1,8 @@
-// cairn-cms: the public delivery entry (@glw907/cairn-cms/delivery). The complete, canonical,
-// backend-free toolkit a SvelteKit site wires its public pages with: the content index and the
-// site resolver, the descriptor helper, the syndication and SEO builders, the endpoint response
-// helpers, the catch-all route loaders, and the head component. It imports nothing from auth,
-// github, or email, so importing it does not pull the server backend into a public bundle.
-export { createContentIndex, fromGlob } from './content-index.js';
-export type { RawFile, ContentSummary, ContentEntry, ContentIndex, ContentProblem } from './content-index.js';
-export { createSiteIndex } from './site-index.js';
-export type { SiteIndex, ConceptIndex } from './site-index.js';
-export { createSiteIndexes } from './site-indexes.js';
-export type { SiteIndexes, SiteGlobs } from './site-indexes.js';
-export { siteDescriptors } from './site-descriptors.js';
-export { deriveExcerpt, wordCount } from './excerpt.js';
-export { buildRssFeed, buildJsonFeed } from './feeds.js';
-export type { FeedChannel, FeedItem } from './feeds.js';
-export { buildSitemap } from './sitemap.js';
-export type { SitemapUrl } from './sitemap.js';
-export { buildRobots } from './robots.js';
-export { buildSeoMeta } from './seo.js';
-export type { SeoInput, SeoMeta } from './seo.js';
-export { readSeoFields, resolveImageUrl } from './seo-fields.js';
-export type { SeoFields } from './seo-fields.js';
-export { paginate } from './paginate.js';
-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';
+// cairn-cms: the public delivery entry (@glw907/cairn-cms/delivery). The node-safe data surface
+// (re-exported from ./delivery/data) plus the SvelteKit catch-all route loaders. The head component
+// lives at ./delivery/head. Importing this pulls @sveltejs/kit through the route loaders, so a
+// plain-Node tool imports from ./delivery/data instead.
+export * from './data.js';
 export { createPublicRoutes } from '../sveltekit/public-routes.js';
 export type {
   PublicRoutesDeps,

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

@@ -1,12 +1,11 @@
-// cairn-cms: the one-call descriptor helper. A delivery site needs the same per-concept
-// descriptors the admin runtime uses; this wraps the two calls that derive them so the
-// pairing is not tribal knowledge. The YAML URL policy stays the single source of truth.
-import { normalizeConcepts } from '../content/concepts.js';
-import { urlPolicyFrom } from '../nav/site-config.js';
+// cairn-cms: the one-call descriptor helper. A delivery site needs the same per-concept descriptors
+// the admin runtime uses; this delegates to the shared resolveConcepts so the pairing is one path, not
+// tribal knowledge. The YAML URL policy stays the single source of truth.
+import { resolveConcepts } from '../content/concepts.js';
 import type { CairnAdapter, ConceptDescriptor } from '../content/types.js';
 import type { SiteConfig } from '../nav/site-config.js';
 
 /** Per-concept descriptors for a site, from its adapter content and its parsed site config. */
 export function siteDescriptors(adapter: CairnAdapter, siteConfig: SiteConfig): ConceptDescriptor[] {
-  return normalizeConcepts(adapter.content, urlPolicyFrom(siteConfig));
+  return resolveConcepts(adapter.content, siteConfig);
 }

package/src/lib/index.ts

@@ -31,6 +31,7 @@ export type {
 } from './content/types.js';
 export { CONCEPT_ROUTING, normalizeConcepts, findConcept } from './content/concepts.js';
 export { composeRuntime } from './content/compose.js';
+export type { ComposeInput } from './content/compose.js';
 export {
   frontmatterFromForm,
   dateInputValue,
@@ -59,13 +60,14 @@ export {
   parseManifest,
   emptyManifest,
   verifyManifest,
+  diffManifests,
   upsertEntry,
   removeEntry,
   manifestEntryFromFile,
   manifestLinkResolver,
   inboundLinks,
 } from './content/manifest.js';
-export type { Manifest, ManifestEntry, LinkTarget, InboundLink } from './content/manifest.js';
+export type { Manifest, ManifestEntry, ManifestDiff, ManifestEntryDiff, LinkTarget, InboundLink } 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 {
@@ -86,15 +88,7 @@ export type { ReferenceOptions } from './render/component-reference.js';
 export { glyph } from './render/glyph.js';
 export type { IconSet } from './render/glyph.js';
 export { remarkDirectiveStamp } from './render/remark-directives.js';
-export {
-  rehypeDispatch,
-  isElement,
-  strProp,
-  iconSpan,
-  cardShell,
-  headRow,
-  markFirstList,
-} from './render/rehype-dispatch.js';
+export { rehypeDispatch, iconSpan, cardShell, headRow } from './render/rehype-dispatch.js';
 export type { MakeIcon } from './render/rehype-dispatch.js';
 export { createRenderer } from './render/pipeline.js';
 export type { RendererOptions } from './render/pipeline.js';
@@ -102,18 +96,6 @@ export type { RendererOptions } from './render/pipeline.js';
 // GitHub read-and-commit backend (Plan 03).
 export type { RepoRef, RepoFile, CommitAuthor, AppCredentials } from './github/types.js';
 export { CommitConflictError } from './github/types.js';
-export { appJwt, installationToken, signingSelfTest } from './github/signing.js';
-export {
-  treeUrl,
-  markdownFilesIn,
-  listMarkdown,
-  contentsUrl,
-  readRaw,
-  fileSha,
-  commitFile,
-} from './github/repo.js';
-export { appCredentials } from './github/credentials.js';
-export type { GithubKeyEnv } from './github/credentials.js';
 
 // Nav tree and site-config helpers (Plan 06).
 export {
@@ -127,38 +109,3 @@ 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,
-  ContentProblem,
-} from './delivery/content-index.js';
-export { createSiteIndex } from './delivery/site-index.js';
-export type { SiteIndex, ConceptIndex } from './delivery/site-index.js';
-export { createSiteIndexes } from './delivery/site-indexes.js';
-export type { SiteIndexes, SiteGlobs } from './delivery/site-indexes.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 { readSeoFields, resolveImageUrl } from './delivery/seo-fields.js';
-export type { SeoFields } from './delivery/seo-fields.js';
-export { paginate } from './delivery/paginate.js';
-export type { Page } from './delivery/paginate.js';
-// Root superset of the delivery route surface: a wrong guess from root for a route loader or a
-// response helper now resolves. The CairnHead component stays out of root so the root barrel stays
-// node-importable for the unit suite; it resolves from @glw907/cairn-cms/delivery/head.
-export { rssResponse, jsonFeedResponse, sitemapResponse, robotsResponse } from './delivery/responses.js';
-export { createPublicRoutes } from './sveltekit/public-routes.js';
-export type { PublicRoutesDeps, ListData, TagData, TagIndexData, EntryData } from './sveltekit/public-routes.js';