@glw907/cairn-cms 0.62.2 → 0.76.0

package/src/lib/index.ts

@@ -9,17 +9,10 @@ export { buildMagicLinkMessage, cloudflareSend } from './email.js';
 export type {
   CairnAdapter,
   ConceptConfig,
-  FrontmatterField,
-  TextField,
-  TextareaField,
-  DateField,
-  BooleanField,
-  TagsField,
-  FreeTagsField,
-  ImageField,
+  NamedField,
   ImageValue,
   ValidationResult,
-  BackendConfig,
+  ValidationIssue,
   SenderConfig,
   NavMenuConfig,
   PreviewConfig,
@@ -30,10 +23,11 @@ export type {
   ConceptUrlPolicy,
   CairnExtension,
   CairnRuntime,
+  SiteRender,
   AdminPanel,
   FieldTypeDef,
 } from './content/types.js';
-export { CONCEPT_ROUTING, normalizeConcepts, findConcept } from './content/concepts.js';
+export { normalizeConcepts, findConcept, defineConcept } from './content/concepts.js';
 export { composeRuntime } from './content/compose.js';
 export type { ComposeInput } from './content/compose.js';
 export {
@@ -42,9 +36,30 @@ export {
   serializeMarkdown,
   parseMarkdown,
 } from './content/frontmatter.js';
-export { defineFields } from './content/schema.js';
 export { defineAdapter } from './content/adapter.js';
-export type { ConceptSchema, Infer, InferFields, DefineFieldsOptions, StandardInput, StandardSchemaV1 } from './content/schema.js';
+export type { StandardInput, StandardSchemaV1 } from './content/standard-schema.js';
+// The Contract v2 field vocabulary: the one live field system.
+export { fields } from './content/fields.js';
+export type {
+  FieldDescriptor,
+  TextField,
+  TextareaField,
+  NumberField,
+  SelectField,
+  MultiselectField,
+  UrlField,
+  EmailField,
+  DateField,
+  DatetimeField,
+  BooleanField,
+  IconField,
+  ImageField,
+  ObjectField,
+  ReferenceField,
+  ArrayField,
+} from './content/fields.js';
+export { fieldset, initialValues } from './content/fieldset.js';
+export type { Fieldset, InferFieldset, FieldsetOptions, BehaviorTable, FieldBehavior } from './content/fieldset.js';
 export {
   isValidId,
   idFromFilename,
@@ -64,6 +79,7 @@ export {
   parseManifest,
   emptyManifest,
   verifyManifest,
+  verifyReferences,
   diffManifests,
   upsertEntry,
   removeEntry,
@@ -71,14 +87,17 @@ export {
   manifestLinkResolver,
   inboundLinks,
 } from './content/manifest.js';
-export type { Manifest, ManifestEntry, ManifestDiff, ManifestEntryDiff, LinkTarget, InboundLink } from './content/manifest.js';
+export type { Manifest, ManifestEntry, ManifestDiff, ManifestEntryDiff, LinkTarget, InboundLink, InboundReference } from './content/manifest.js';
+export type { ReferenceEdge } from './content/references.js';
+// The read-model resolution of a reference edge to its target's identity lives at the cross-concept
+// site-resolver layer (a per-concept index cannot reach a different concept's entries). The resolver
+// function ships from the /delivery subpath; this is the type a route reads off the resolved map.
+export type { ResolvedReference } from './delivery/site-resolver.js';
 // Render engine (Plan 04): generic directive pipeline; sites own the component registry.
-export { defineRegistry, emptyValues } from './render/registry.js';
+export { defineRegistry, defineComponent, emptyValues } from './render/registry.js';
 export type {
   ComponentDef,
   ComponentRegistry,
-  FieldType,
-  AttributeField,
   SlotKind,
   SlotDef,
   ComponentValues,
@@ -100,13 +119,16 @@ export { createRenderer } from './render/pipeline.js';
 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 type { RepoFile, CommitAuthor } from './github/types.js';
 export { CommitConflictError } from './github/types.js';
+// The Backend seam (Contract v2 backend phase): the store interface and its default GitHub provider.
+export { githubApp } from './github/backend.js';
+export type { Backend, BackendProvider, GithubAppProvider, BackendEnv } from './github/backend.js';
+export type { FileChange } from './github/repo.js';
 
 // Nav tree and site-config helpers (Plan 06).
 export {
   parseSiteConfig,
-  urlPolicyFrom,
   extractMenu,
   setMenu,
   validateNavTree,

package/src/lib/islands/index.ts

@@ -0,0 +1,84 @@
+// cairn-cms islands (@glw907/cairn-cms/islands): the client runtime that mounts a site's live Svelte
+// components over the static fallbacks the render pipeline emits. cairn is Svelte-only by design, so this
+// mounts with Svelte's own mount()/unmount() directly, with no framework abstraction. A site imports this
+// dynamically, gated on a non-empty registry, so a static site never ships it (zero cost when unused).
+import { mount, unmount, type Component } from 'svelte';
+import type { IslandRegistry } from './types.js';
+
+export type { IslandRegistry } from './types.js';
+
+// The live Svelte instances of the current pass and the observers still waiting to fire, kept module-level
+// so the next pass can tear the previous one down. A layout calls hydrateIslands once per navigation, and
+// the previous mounts must unmount before the next mount over the same DOM.
+let mounted: Record<string, unknown>[] = [];
+let observers: IntersectionObserver[] = [];
+
+// Tear down the previous pass: unmount live instances and disconnect observers that never fired. unmount
+// runs with outro: false so teardown is synchronous and deterministic on navigation; an island declaring an
+// out: transition would otherwise linger and briefly double-render against the next pass's fresh mount.
+function teardown(): void {
+  for (const o of observers) o.disconnect();
+  observers = [];
+  for (const instance of mounted) {
+    try {
+      void unmount(instance, { outro: false });
+    } catch {
+      // a component that throws on teardown must not block the rest
+    }
+  }
+  mounted = [];
+}
+
+// Mount one island over its boundary: parse props (try/catch, a malformed payload leaves the fallback),
+// clear the fallback, mount, and on a mount failure restore the fallback so the reader still sees content.
+// WATCH: props are trusted to equal the directive's declared scalar attributes (serializeIslandProps emits
+// only those). If a directive ever carries an attribute its island does not declare, this forwards it as-is.
+function mountIsland(node: Element, Comp: Component<Record<string, unknown>>): void {
+  let props: Record<string, unknown>;
+  try {
+    props = JSON.parse(node.getAttribute('data-cairn-props') ?? '{}') as Record<string, unknown>;
+  } catch {
+    return;
+  }
+  const fallback = [...node.childNodes];
+  node.replaceChildren();
+  try {
+    mounted.push(mount(Comp, { target: node as HTMLElement, props }));
+  } catch {
+    node.replaceChildren(...fallback);
+  }
+}
+
+// Defer a 'visible' island to first intersection, then mount once and stop observing.
+function observeIsland(node: Element, Comp: Component<Record<string, unknown>>): void {
+  const observer = new IntersectionObserver((entries, self) => {
+    for (const entry of entries) {
+      if (entry.isIntersecting) {
+        self.disconnect();
+        mountIsland(node, Comp);
+      }
+    }
+  });
+  observer.observe(node);
+  observers.push(observer);
+}
+
+/**
+ * Mount each island in `root` (default `document`) over its server-rendered fallback. Call it after each
+ *  client-side navigation, once the new DOM is in place (an `afterNavigate` callback): it tears down the
+ *  previous pass first, so it is idempotent and leak-free. An eager island (`hydrate: true`) mounts at once;
+ *  a `'visible'` island mounts on first intersection. An unknown directive name, a malformed prop payload,
+ *  or a component that throws leaves the static fallback in place, so one bad island never breaks the page.
+ *  Mount-and-replace clears the fallback, so an island whose fallback holds a focusable control should
+ *  restore focus itself; the shipped fallbacks are non-interactive.
+ */
+export function hydrateIslands(islands: IslandRegistry, root: ParentNode = document): void {
+  teardown();
+  for (const node of root.querySelectorAll('[data-cairn-island]')) {
+    const name = node.getAttribute('data-cairn-island');
+    const Comp = name ? islands[name] : undefined;
+    if (!Comp) continue;
+    if (node.getAttribute('data-cairn-hydrate') === 'visible') observeIsland(node, Comp);
+    else mountIsland(node, Comp);
+  }
+}

package/src/lib/islands/types.ts

@@ -0,0 +1,11 @@
+// cairn-cms islands (@glw907/cairn-cms/islands): the type contract shared by the adapter and the client
+// runtime. Kept in its own runtime-free module so the adapter types can import it without pulling
+// Svelte's mount() into the server graph.
+import type { Component } from 'svelte';
+
+/**
+ * A site's island components, keyed by directive name. Each value is the live Svelte component
+ *  {@link hydrateIslands} mounts over the matching `hydrate` directive's static fallback. The props a
+ *  component receives are the directive's declared scalar attributes (see the island boundary contract).
+ */
+export type IslandRegistry = Record<string, Component<Record<string, unknown>>>;

package/src/lib/log/events.ts

@@ -22,6 +22,7 @@ export type CairnLogEvent =
   | 'media.delivery_failed'
   | 'media.orphan_reconcile'
   | 'media.resolve_missing'
+  | 'media.resolver_absent'
   | 'media.deleted'
   | 'media.delete_blocked'
   | 'media.bulk_deleted'

package/src/lib/media/index.ts

@@ -8,6 +8,7 @@
 export { normalizeAssets, type ResolvedAssetConfig } from './config.js';
 export {
   parseMediaManifest,
+  readCommittedManifest,
   findByHash,
   upsertMediaEntry,
   removeMediaEntry,

package/src/lib/media/manifest.ts

@@ -38,6 +38,20 @@ export function parseMediaManifest(json: unknown): MediaManifest {
   return json as MediaManifest;
 }
 
+/**
+ * Read the committed media manifest from an `import.meta.glob` eager result, degrading a missing
+ *  file to an empty manifest. A static import of an absent `media.json` fails the Vite build before
+ *  any runtime degrade can run, so a fresh site with no manifest cannot build. A glob result is the
+ *  build-safe read: `import.meta.glob` returns `{}` when nothing matches rather than throwing, and
+ *  this helper extracts the single matched value and parses it, so a missing file reads a clean `{}`.
+ * @param globResult - The eager glob result for the committed manifest, an empty object when the
+ *  file is absent. The consumer passes
+ *  `import.meta.glob('<path-to-media.json>', { eager: true, import: 'default' })`.
+ */
+export function readCommittedManifest(globResult: Record<string, unknown>): MediaManifest {
+  return parseMediaManifest(Object.values(globResult)[0]);
+}
+
 /**
  * Validate one posted value as a MediaEntry, returning it narrowed or undefined. The trust boundary
  *  for an optimistic record the client re-posts: the upload action server-owned each field at

package/src/lib/media/rewrite-plan.ts

@@ -16,11 +16,10 @@
 // injected, so the planner never imports the editor surface. It is internal, exported from no package
 // subpath, so it carries no reference page.
 import type { ConceptDescriptor } from '../content/types.js';
-import type { RepoRef } from '../github/types.js';
+import type { Backend } from '../github/backend.js';
 import type { Manifest } from '../content/manifest.js';
 import { findConcept } from '../content/concepts.js';
 import { filenameFromId } from '../content/ids.js';
-import { readRaw } from '../github/repo.js';
 import { buildUsageIndex } from './usage.js';
 
 /**
@@ -81,8 +80,7 @@ export interface RewritePlan<P = unknown> {
  * editor surface and node-safe; the only IO is the usage index build and the per-entry reads.
  */
 export async function planMediaRewrite<P = unknown>(args: {
-  backend: RepoRef;
-  token: string;
+  backend: Backend;
   concepts: ConceptDescriptor[];
   contentManifest: Manifest;
   hash: string;
@@ -90,7 +88,7 @@ export async function planMediaRewrite<P = unknown>(args: {
 }): Promise<RewritePlan<P>> {
   // Strict so an unverifiable branch read rejects here rather than degrading to an absent reference.
   // Do NOT wrap this: the throw is the fail-closed contract the apply relies on.
-  const index = await buildUsageIndex(args.backend, args.token, args.concepts, args.contentManifest, {
+  const index = await buildUsageIndex(args.backend, args.concepts, args.contentManifest, {
     strict: true,
   });
   const rows = index.get(args.hash) ?? [];
@@ -104,7 +102,7 @@ export async function planMediaRewrite<P = unknown>(args: {
       const concept = findConcept(args.concepts, row.concept);
       if (!concept) return null;
       const path = `${concept.dir}/${filenameFromId(row.id)}`;
-      const markdown = await readRaw(args.backend, path, args.token);
+      const markdown = await args.backend.readFile(path, args.backend.defaultBranch);
       if (markdown === null) return null;
       const result = args.transform(markdown);
       if (result.placements.length === 0) return null;

package/src/lib/media/usage.ts

@@ -19,10 +19,8 @@
 // is therefore "found in N entries" / "no references found", never a bare "unused": absence of a row
 // means no reference was found, not a proof that none exists.
 import type { ConceptDescriptor } from '../content/types.js';
-import type { RepoRef } from '../github/types.js';
+import type { Backend } from '../github/backend.js';
 import type { Manifest } from '../content/manifest.js';
-import { listBranches } from '../github/branches.js';
-import { readRaw } from '../github/repo.js';
 import { PENDING_PREFIX, parsePendingBranch } from '../content/pending.js';
 import { findConcept } from '../content/concepts.js';
 import { isValidId, filenameFromId } from '../content/ids.js';
@@ -84,8 +82,7 @@ function push(index: UsageIndex, hash: string, entry: UsageEntry): void {
  * (the load path lists once for the media-union) rather than listing them a second time.
  */
 export async function buildUsageIndex(
-  repo: RepoRef,
-  token: string,
+  backend: Backend,
   concepts: ConceptDescriptor[],
   manifest: Manifest,
   opts: BuildUsageOptions = {},
@@ -108,7 +105,7 @@ export async function buildUsageIndex(
 
   // The branch arm: read each open cairn/* branch's one edited file. The path is derivable from the
   // branch name, so no tree-listing is needed. The branch list is reused when the caller passes it.
-  const names = opts.branches ?? (await listBranches(repo, PENDING_PREFIX, token));
+  const names = opts.branches ?? (await backend.listBranches(PENDING_PREFIX));
   // Read the branches in parallel rather than one at a time, so the latency floor is one round trip
   // instead of N. workerd self-throttles to 6 simultaneous outbound connections, so this batch and
   // the load path's media-union batch each stay under the limit; do NOT merge the two into one
@@ -125,7 +122,7 @@ export async function buildUsageIndex(
 
       const path = `${concept.dir}/${filenameFromId(ref.id)}`;
       try {
-        const raw = await readRaw({ ...repo, branch: name }, path, token);
+        const raw = await backend.readFile(path, name);
         if (raw === null) return []; // The file is absent on the branch: nothing to extract.
         const { frontmatter, body } = parseMarkdown(raw);
         const fmTitle = frontmatter.title;

package/src/lib/nav/site-config.ts

@@ -3,7 +3,6 @@
 // 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 {
@@ -75,12 +74,9 @@ export interface SiteConfig {
   siteName: string;
   description?: string;
   author?: string;
-  url?: string;
   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>;
   /**
    * The editor spellcheck settings. The dialect is declared once per site (spec 1.2), so a British
    *  site loads the British word list and "colour" reads as correct. Today only US English ships, so an
@@ -285,6 +281,14 @@ export function parseSiteConfig(raw: string): SiteConfig {
   if (typeof siteName !== 'string' || !siteName.trim()) {
     throw new SiteConfigError('Site config needs a siteName');
   }
+  // Contract v2 moved per-concept URL policy out of the YAML and onto defineConcept. A leftover
+  // `content:` block here would silently do nothing while the concept defaulted its permalink, so a
+  // half-migrated site (one carrying a non-default datePrefix) would rewrite every post URL. Fail loud.
+  if ((parsed as SiteConfig).content !== undefined) {
+    throw new SiteConfigError(
+      'cairn: site config no longer carries per-concept URL policy; move permalink/datePrefix into defineConcept (Contract v2)',
+    );
+  }
   return parsed as SiteConfig;
 }
 
@@ -295,11 +299,6 @@ 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/render/component-grammar.ts

@@ -9,17 +9,17 @@ const COLON = ':';
 
 function attrBlock(def: ComponentDef, values: ComponentValues): string {
   const parts: string[] = [];
-  for (const field of def.attributes ?? []) {
-    const v = values.attributes[field.key];
+  for (const [name, field] of Object.entries(def.attributes ?? {})) {
+    const v = values.attributes[name];
     if (field.type === 'boolean') {
-      if (v === true) parts.push(`${field.key}="true"`);
+      if (v === true) parts.push(`${name}="true"`);
     } else if (typeof v === 'string' && v !== '') {
       // The directive attribute grammar (mdast-util-directive) treats a literal `"` as the value
       // terminator and decodes HTML entities, so a backslash escape does not survive a round-trip.
       // Encode `&` first (so existing entities are not double-decoded) then `"`; the parser decodes
       // both back. A backslash is literal in this grammar and needs no escaping.
       const escaped = v.replace(/&/g, '&').replace(/"/g, '"');
-      parts.push(`${field.key}="${escaped}"`);
+      parts.push(`${name}="${escaped}"`);
     }
   }
   return parts.length ? `{${parts.join(' ')}}` : '';
@@ -103,10 +103,10 @@ function valuesFromRoot(root: (RootContent & DirectiveNode) | undefined, def: Co
   const values = emptyComponentValues(def);
   if (!root) return values;
 
-  for (const field of def.attributes ?? []) {
-    const raw = root.attributes?.[field.key];
-    if (field.type === 'boolean') values.attributes[field.key] = raw === 'true';
-    else if (typeof raw === 'string') values.attributes[field.key] = raw;
+  for (const [name, field] of Object.entries(def.attributes ?? {})) {
+    const raw = root.attributes?.[name];
+    if (field.type === 'boolean') values.attributes[name] = raw === 'true';
+    else if (typeof raw === 'string') values.attributes[name] = raw;
   }
 
   const titleSlot = slotByName(def, 'title');
@@ -181,7 +181,7 @@ export async function componentRoundTripSafety(markdown: string, def: ComponentD
   const root = findComponentRoot(markdown, def);
   if (!root) return { safe: false, reason: 'not-a-component' };
 
-  const declaredKeys = new Set((def.attributes ?? []).map((f) => f.key));
+  const declaredKeys = new Set(Object.keys(def.attributes ?? {}));
   for (const key of parseRawAttributeKeys(markdown, def)) {
     if (!declaredKeys.has(key)) return { safe: false, reason: 'unknown-attribute' };
   }
@@ -220,7 +220,7 @@ export async function parseComponentWithRawKeys(
 // here; the parse must overwrite only the fields actually present in the markdown.
 function emptyComponentValues(def: ComponentDef): ComponentValues {
   const attributes: Record<string, string | boolean> = {};
-  for (const f of def.attributes ?? []) attributes[f.key] = f.type === 'boolean' ? false : '';
+  for (const [name, field] of Object.entries(def.attributes ?? {})) attributes[name] = field.type === 'boolean' ? false : '';
   const slots: Record<string, string | string[]> = {};
   for (const s of def.slots ?? []) slots[s.name] = s.kind === 'repeatable' ? [] : '';
   return { attributes, slots };

package/src/lib/render/component-reference.ts

@@ -27,9 +27,10 @@ function componentSection(def: ComponentDef): string {
 /** Seed example values that show every declared field: an ellipsis for strings, one sample list item. */
 function exampleValues(def: ComponentDef): ComponentValues {
   const values = emptyValues(def);
-  for (const field of def.attributes ?? []) {
-    if (field.type === 'boolean') values.attributes[field.key] = false;
-    else values.attributes[field.key] = field.options?.[0] ?? '…';
+  for (const [name, field] of Object.entries(def.attributes ?? {})) {
+    if (field.type === 'boolean') values.attributes[name] = false;
+    else if (field.type === 'select') values.attributes[name] = field.options[0] ?? '…';
+    else values.attributes[name] = '…';
   }
   for (const slot of def.slots ?? []) {
     if (slot.kind === 'repeatable') values.slots[slot.name] = ['…'];

package/src/lib/render/component-validate.ts

@@ -1,38 +1,25 @@
 import { parseComponentWithRawKeys } from './component-grammar.js';
-import type { ComponentDef, ComponentValues } from './registry.js';
+import { fieldset } from '../content/fieldset.js';
+import type { ComponentDef } from './registry.js';
 
 /** A validation verdict: ok, or field-keyed error messages. */
 export type ComponentValidation = { ok: true } | { ok: false; errors: Record<string, string> };
 
 /**
- *
+ * Validate a serialized component directive against its definition: the attributes through the same
+ *  `fieldset` validator a concept field uses (coercion, constraints, required, select domain, pattern,
+ *  and any per-attribute `behavior.validate`), then the two component-only checks, an unknown attribute
+ *  key and an unfilled required slot.
  */
 export async function validateComponent(markdown: string, def: ComponentDef): Promise<ComponentValidation> {
   const { values, rawKeys } = await parseComponentWithRawKeys(markdown, def);
   const errors: Record<string, string> = {};
-  const declared = new Set((def.attributes ?? []).map((f) => f.key));
 
-  for (const field of def.attributes ?? []) {
-    const v = values.attributes[field.key];
-    const filled = field.type === 'boolean' ? true : typeof v === 'string' && v !== '';
-    if (field.required && !filled) {
-      errors[field.key] = `${field.label} is required.`;
-      continue;
-    }
-    if (field.type === 'select' && typeof v === 'string' && v !== '' && !(field.options ?? []).includes(v)) {
-      errors[field.key] = `${field.label} must be one of: ${(field.options ?? []).join(', ')}.`;
-      continue;
-    }
-    if (field.pattern && typeof v === 'string' && v !== '' && !new RegExp(field.pattern.source).test(v)) {
-      errors[field.key] = field.pattern.message;
-      continue;
-    }
-    if (field.validate) {
-      const message = runFieldValidator(def, field.key, () => field.validate!(v, values));
-      if (typeof message === 'string') errors[field.key] = message;
-    }
-  }
+  const schema = def.attributeSchema ?? fieldset(def.attributes ?? {}, { behavior: def.behavior });
+  const result = schema.validate(values.attributes, '');
+  if (!result.ok) Object.assign(errors, result.errors);
 
+  const declared = new Set(Object.keys(def.attributes ?? {}));
   for (const key of rawKeys) {
     if (!declared.has(key)) errors[key] = `Unknown attribute "${key}".`;
   }
@@ -46,15 +33,3 @@ export async function validateComponent(markdown: string, def: ComponentDef): Pr
 
   return Object.keys(errors).length ? { ok: false, errors } : { ok: true };
 }
-
-// Run a site-supplied attribute validator. The validator is author code, so a throw is contained:
-// the field is treated as valid and a dev-time warning names the component and field so the author
-// can find the bug. A returned string is the field error; anything else (null) is clean.
-function runFieldValidator(def: ComponentDef, key: string, call: () => string | null): string | null {
-  try {
-    return call();
-  } catch (err) {
-    console.warn(`cairn: validate() for component "${def.name}" field "${key}" threw; treating the field as valid.`, err);
-    return null;
-  }
-}