@glw907/cairn-cms 0.1.0

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "@glw907/cairn-cms",
+  "version": "0.1.0",
+  "description": "Embedded, magic-link, GitHub-committing CMS for SvelteKit/Cloudflare sites.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Geoff Wright",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/glw907/cairn-cms.git"
+  },
+  "keywords": ["cms", "sveltekit", "cloudflare", "github", "magic-link", "markdown"],
+  "scripts": {
+    "package": "svelte-package",
+    "package:watch": "svelte-package --watch",
+    "prepublishOnly": "svelte-package",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "exports": {
+    ".": {
+      "types": "./src/lib/index.ts",
+      "svelte": "./src/lib/index.ts",
+      "default": "./src/lib/index.ts"
+    },
+    "./sveltekit": {
+      "types": "./src/lib/sveltekit/index.ts",
+      "svelte": "./src/lib/sveltekit/index.ts",
+      "default": "./src/lib/sveltekit/index.ts"
+    },
+    "./components": {
+      "types": "./src/lib/components/index.ts",
+      "svelte": "./src/lib/components/index.ts",
+      "default": "./src/lib/components/index.ts"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "exports": {
+      ".": {
+        "types": "./dist/index.d.ts",
+        "svelte": "./dist/index.js",
+        "default": "./dist/index.js"
+      },
+      "./sveltekit": {
+        "types": "./dist/sveltekit/index.d.ts",
+        "svelte": "./dist/sveltekit/index.js",
+        "default": "./dist/sveltekit/index.js"
+      },
+      "./components": {
+        "types": "./dist/components/index.d.ts",
+        "svelte": "./dist/components/index.js",
+        "default": "./dist/components/index.js"
+      },
+      "./package.json": "./package.json"
+    }
+  },
+  "files": ["dist", "src/lib"],
+  "peerDependencies": {
+    "@sveltejs/kit": "^2",
+    "carta-md": "^4.11",
+    "svelte": "^5.0.0"
+  },
+  "dependencies": {
+    "gray-matter": "^4"
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "^4.20260405.1",
+    "@sveltejs/kit": "^2",
+    "@sveltejs/package": "^2",
+    "@sveltejs/vite-plugin-svelte": "^7",
+    "carta-md": "^4.11",
+    "svelte": "^5",
+    "svelte-check": "^4",
+    "typescript": "^6.0.3",
+    "unified": "^11.0.5",
+    "vitest": "^4.1.6"
+  }
+}

package/src/lib/adapter.ts

@@ -0,0 +1,110 @@
+// cairn-core: the adapter contract each site implements.
+//
+// This is the single seam that lets one admin surface serve different designs. A site
+// supplies a `CairnAdapter` (see `src/lib/cairn.config.ts`) describing its backend repo,
+// its editable collections (folder + form fields + frontmatter validator), and its preview
+// plugin set. cairn-core never hard-codes a collection, tag, or directive — it reads them
+// from the adapter. Field descriptors are plain data so a load function can hand them to
+// the editor form across the server→client boundary.
+import type { PreviewPlugins } from './carta';
+import type { RepoRef } from './github';
+
+interface FieldBase {
+  /** Frontmatter key and form input name. */
+  name: string;
+  label: string;
+  required?: boolean;
+}
+
+export interface TextField extends FieldBase {
+  type: 'text';
+}
+export interface DateField extends FieldBase {
+  type: 'date';
+}
+export interface TextareaField extends FieldBase {
+  type: 'textarea';
+  rows?: number;
+}
+export interface BooleanField extends FieldBase {
+  type: 'boolean';
+}
+export interface TagsField extends FieldBase {
+  type: 'tags';
+  /** Controlled vocabulary rendered as checkboxes. */
+  options: readonly string[];
+}
+export interface FreeTagsField extends FieldBase {
+  type: 'freetags';
+  /** Free-form tags, edited as one comma-separated text input (no controlled vocabulary). */
+  placeholder?: string;
+}
+
+export type CairnField =
+  | TextField
+  | DateField
+  | TextareaField
+  | BooleanField
+  | TagsField
+  | FreeTagsField;
+
+export interface CairnCollection {
+  /** Route `[type]` segment and list key, e.g. `posts`. */
+  type: string;
+  label: string;
+  /** Repo-relative folder holding the collection's markdown files. */
+  dir: string;
+  /** Editor form fields, rendered in order. */
+  fields: CairnField[];
+  /** Validate raw frontmatter (from the form) into the on-disk object, throwing on error. */
+  validate(data: Record<string, unknown>, source: string): object;
+}
+
+export interface CairnAdapter {
+  /** Branding + magic-link email copy. */
+  siteName: string;
+  /** From: address for magic-link email — a domain-authenticated sender. */
+  sender: string;
+  /** The repository the admin reads content from and commits to. */
+  backend: RepoRef;
+  /** Site plugin set for the Carta preview (parity with the live render). */
+  preview: PreviewPlugins;
+  collections: CairnCollection[];
+}
+
+/** Look up a collection by its route segment, or undefined if the segment is unknown. */
+export function findCollection(adapter: CairnAdapter, type: string): CairnCollection | undefined {
+  return adapter.collections.find((collection) => collection.type === type);
+}
+
+/** Read raw frontmatter from a submitted form, decoding each value per its field type. */
+export function frontmatterFromForm(
+  collection: CairnCollection,
+  form: FormData,
+): Record<string, unknown> {
+  const data: Record<string, unknown> = {};
+  for (const field of collection.fields) {
+    switch (field.type) {
+      case 'boolean':
+        data[field.name] = form.get(field.name) === 'on';
+        break;
+      case 'tags':
+        data[field.name] = form.getAll(field.name).map(String);
+        break;
+      case 'freetags':
+        // One comma-separated input → trimmed, de-duplicated, non-empty tags.
+        data[field.name] = [
+          ...new Set(
+            String(form.get(field.name) ?? '')
+              .split(',')
+              .map((tag) => tag.trim())
+              .filter(Boolean),
+          ),
+        ];
+        break;
+      default:
+        data[field.name] = form.get(field.name);
+    }
+  }
+  return data;
+}

package/src/lib/auth.ts

@@ -0,0 +1,130 @@
+// cairn-core: magic-link auth + signed sessions.
+//
+// Generic across sites — no ecnordic specifics here. Crypto is Web Crypto (HMAC-SHA256)
+// so it runs unchanged on Cloudflare Workers under nodejs_compat. Single-use enforcement
+// for magic links rides on a KV nonce; signature + expiry are self-contained in the token.
+
+import type { KVNamespace } from '@cloudflare/workers-types';
+import { bytesToB64url } from './utils';
+
+export interface Editor {
+  email: string;
+  name: string;
+}
+
+export const SESSION_COOKIE = 'cairn_session';
+
+const MAGIC_TTL_SECONDS = 600; // 10 minutes
+const SESSION_TTL_SECONDS = 60 * 60 * 24 * 7; // 7 days
+
+export const SESSION_MAX_AGE = SESSION_TTL_SECONDS;
+
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+
+function b64urlToBytes(value: string): Uint8Array {
+  const normalized = value.replace(/-/g, '+').replace(/_/g, '/');
+  const padded = normalized + '='.repeat((4 - (normalized.length % 4)) % 4);
+  return Uint8Array.from(atob(padded), (c) => c.charCodeAt(0));
+}
+
+// TextEncoder/atob produce Uint8Arrays whose generic buffer type no longer satisfies
+// Web Crypto's BufferSource under strict lib types; hand the underlying ArrayBuffer over.
+function buf(bytes: Uint8Array): ArrayBuffer {
+  return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength) as ArrayBuffer;
+}
+
+async function hmacKey(secret: string): Promise<CryptoKey> {
+  return crypto.subtle.importKey(
+    'raw',
+    buf(encoder.encode(secret)),
+    { name: 'HMAC', hash: 'SHA-256' },
+    false,
+    ['sign', 'verify'],
+  );
+}
+
+/** Sign an arbitrary JSON payload as `<base64url(payload)>.<base64url(hmac)>`. */
+async function signToken(data: unknown, secret: string): Promise<string> {
+  const payload = bytesToB64url(encoder.encode(JSON.stringify(data)));
+  const key = await hmacKey(secret);
+  const sig = await crypto.subtle.sign('HMAC', key, buf(encoder.encode(payload)));
+  return `${payload}.${bytesToB64url(new Uint8Array(sig))}`;
+}
+
+/** Verify signature (constant-time via subtle.verify) and parse the payload, or null. */
+async function verifyToken<T>(token: string, secret: string): Promise<T | null> {
+  const dot = token.indexOf('.');
+  if (dot < 0) return null;
+  const payload = token.slice(0, dot);
+  const sig = token.slice(dot + 1);
+  const key = await hmacKey(secret);
+  let ok = false;
+  try {
+    ok = await crypto.subtle.verify('HMAC', key, buf(b64urlToBytes(sig)), buf(encoder.encode(payload)));
+  } catch {
+    return null;
+  }
+  if (!ok) return null;
+  try {
+    return JSON.parse(decoder.decode(b64urlToBytes(payload))) as T;
+  } catch {
+    return null;
+  }
+}
+
+interface MagicPayload {
+  email: string;
+  exp: number;
+  nonce: string;
+}
+
+/** Issue a single-use magic-link token and register its nonce in KV with a TTL. */
+export async function createMagicLink(
+  email: string,
+  secret: string,
+  kv: KVNamespace,
+): Promise<string> {
+  const nonce = bytesToB64url(crypto.getRandomValues(new Uint8Array(16)));
+  const exp = Date.now() + MAGIC_TTL_SECONDS * 1000;
+  const token = await signToken({ email, exp, nonce } satisfies MagicPayload, secret);
+  await kv.put(`ml:${nonce}`, email, { expirationTtl: MAGIC_TTL_SECONDS });
+  return token;
+}
+
+/** Redeem a magic-link token: verify, check expiry, then consume the KV nonce (single use). */
+export async function redeemMagicToken(
+  token: string,
+  secret: string,
+  kv: KVNamespace,
+): Promise<string | null> {
+  const payload = await verifyToken<MagicPayload>(token, secret);
+  if (!payload || Date.now() > payload.exp) return null;
+  const stored = await kv.get(`ml:${payload.nonce}`);
+  if (stored !== payload.email) return null;
+  await kv.delete(`ml:${payload.nonce}`); // burn it — single use
+  return payload.email;
+}
+
+interface SessionPayload extends Editor {
+  exp: number;
+}
+
+export async function createSession(editor: Editor, secret: string): Promise<string> {
+  const exp = Date.now() + SESSION_TTL_SECONDS * 1000;
+  return signToken({ ...editor, exp } satisfies SessionPayload, secret);
+}
+
+export async function verifySession(token: string, secret: string): Promise<Editor | null> {
+  const payload = await verifyToken<SessionPayload>(token, secret);
+  if (!payload || Date.now() > payload.exp) return null;
+  return { email: payload.email, name: payload.name };
+}
+
+/** Look up an editor in the KV allowlist (`editor:<email>` → display name). */
+export async function lookupEditor(email: string, kv: KVNamespace): Promise<Editor | null> {
+  const normalized = email.trim().toLowerCase();
+  const name = await kv.get(`editor:${normalized}`);
+  if (name === null) return null;
+  return { email: normalized, name };
+}

package/src/lib/carta.ts

@@ -0,0 +1,59 @@
+// cairn-core: pure Carta options/transformer wiring for render-only preview.
+//
+// Plugins are passed in, not imported — that seam is what the Pass D adapter formalises.
+// No `carta-md` import: its index re-exports Svelte components that the node test env
+// can't load. The Svelte component calls `new Carta(previewCartaOptions(...))` directly.
+import type { Pluggable, Processor } from 'unified';
+
+export interface PreviewPlugins {
+  /** remark plugins, injected after gfm and before remark-rehype. */
+  remarkPlugins: Pluggable[];
+  /** rehype plugins, injected after remark-rehype. */
+  rehypePlugins: Pluggable[];
+}
+
+interface PreviewTransformer {
+  execution: 'sync';
+  type: 'remark' | 'rehype';
+  transform: (ctx: { processor: Processor }) => void;
+}
+
+function phase(plugins: Pluggable[], type: PreviewTransformer['type']): PreviewTransformer[] {
+  return plugins.map((plugin) => ({
+    execution: 'sync',
+    type,
+    transform: ({ processor }) => {
+      processor.use([plugin]);
+    },
+  }));
+}
+
+/**
+ * Map the site's plugin set to Carta sync transformers, remark phase before rehype.
+ * Carta's processor is remarkParse → gfm → [remark] → remark-rehype → [rehype] → stringify,
+ * so this ordering reproduces render.ts exactly. Pure (no Carta) so it is unit-testable.
+ */
+export function previewTransformers({ remarkPlugins, rehypePlugins }: PreviewPlugins): PreviewTransformer[] {
+  return [...phase(remarkPlugins, 'remark'), ...phase(rehypePlugins, 'rehype')];
+}
+
+/** Minimal Options subset we populate — avoids importing carta-md (Svelte re-exports). */
+interface PreviewCartaOptions {
+  sanitizer: false;
+  rehypeOptions: { allowDangerousHtml: boolean };
+  extensions: Array<{ transformers: PreviewTransformer[] }>;
+}
+
+/**
+ * Carta options for a render-only preview: site plugins wired in, raw HTML allowed, no
+ * sanitizer. Authors are trusted and the directive pipeline emits intentional raw HTML
+ * (render.ts uses allowDangerousHtml + rehype-raw); sanitizing here would strip EC
+ * primitives. The Svelte component passes this to `new Carta(...)`.
+ */
+export function previewCartaOptions(plugins: PreviewPlugins): PreviewCartaOptions {
+  return {
+    sanitizer: false,
+    rehypeOptions: { allowDangerousHtml: true },
+    extensions: [{ transformers: previewTransformers(plugins) }],
+  };
+}

package/src/lib/components/AdminLayout.svelte

@@ -0,0 +1,18 @@
+<script lang="ts">
+  // Neutral admin chrome — robots noindex + a centered container, scoped to /admin. Shared
+  // across sites so the admin tool looks identical everywhere (only siteName, supplied by
+  // pages, varies). Each site's `admin/+layout.svelte` is a one-line shim around this.
+  import type { Snippet } from 'svelte';
+
+  let { children }: { children: Snippet } = $props();
+</script>
+
+<svelte:head>
+  <meta name="robots" content="noindex, nofollow" />
+</svelte:head>
+
+<div class="min-h-screen bg-base-200" data-pagefind-ignore>
+  <div class="mx-auto max-w-3xl px-4 py-8">
+    {@render children()}
+  </div>
+</div>

package/src/lib/components/AdminList.svelte

@@ -0,0 +1,41 @@
+<script lang="ts">
+  // The /admin content list: every collection's files, linking into the editor. Data comes
+  // from `adminListLoad` (collections) merged with `adminLayoutLoad` (editor, siteName).
+  import type { Editor } from '../auth';
+  import type { AdminCollectionList } from '../sveltekit';
+
+  interface Props {
+    data: { siteName: string; editor: Editor | null; collections: AdminCollectionList[] };
+  }
+  let { data }: Props = $props();
+</script>
+
+<div class="flex items-center justify-between">
+  <h1 class="text-2xl font-bold">{data.siteName} CMS</h1>
+  <form method="POST" action="/admin/auth/logout">
+    <button type="submit" class="btn btn-ghost btn-sm">Sign out</button>
+  </form>
+</div>
+
+<p class="mt-2 text-sm opacity-70">
+  Signed in as {data.editor?.name} ({data.editor?.email})
+</p>
+
+{#each data.collections as collection (collection.type)}
+  <section class="mt-8">
+    <h2 class="mb-3 text-lg font-semibold">{collection.label}</h2>
+    {#if collection.error}
+      <div class="alert alert-warning">Couldn't load {collection.label.toLowerCase()}: {collection.error}</div>
+    {:else if collection.files.length === 0}
+      <p class="opacity-60">No content yet.</p>
+    {:else}
+      <ul class="menu rounded-box border border-base-300 bg-base-100 p-2">
+        {#each collection.files as file (file.path)}
+          <li>
+            <a href="/admin/edit/{collection.type}/{file.id}">{file.id}</a>
+          </li>
+        {/each}
+      </ul>
+    {/if}
+  </section>
+{/each}

package/src/lib/components/EditPage.svelte

@@ -0,0 +1,125 @@
+<script lang="ts">
+  // The editor: a per-field frontmatter form (driven by the adapter's `fields`) plus a Carta
+  // markdown editor whose preview runs the site's plugin set (passed as `preview`). Data comes
+  // from `editLoad` merged with `adminLayoutLoad` (siteName); `carta-md` is a peer dependency.
+  import { onMount } from 'svelte';
+  import { Carta, MarkdownEditor } from 'carta-md';
+  import 'carta-md/default.css';
+  import { previewCartaOptions, type PreviewPlugins } from '../carta';
+  import type { CairnField } from '../adapter';
+  import type { EditData } from '../sveltekit';
+
+  let { data, preview }: { data: EditData & { siteName: string }; preview: PreviewPlugins } = $props();
+
+  // Body is editable state; the Carta editor's preview runs the exact site plugin set, so it
+  // matches the live page. A hidden input carries the current value into the form.
+  // svelte-ignore state_referenced_locally — seeding from the initial load is intended.
+  let body = $state(data.body);
+
+  // svelte-ignore state_referenced_locally — the preview plugin set is fixed for the load.
+  const carta = new Carta(previewCartaOptions(preview));
+
+  // Carta's MarkdownEditor must not render on the worker (it pulls Shiki). onMount fires only
+  // in the browser, so SSR renders the plain textarea and the client swaps in the editor —
+  // the kit-free equivalent of the per-site route's `$app/environment` `browser` guard.
+  let mounted = $state(false);
+  onMount(() => {
+    mounted = true;
+  });
+
+  // svelte-ignore state_referenced_locally — form defaults from the initial load.
+  const fm = data.frontmatter as Record<string, unknown>;
+
+  function fmString(key: string): string {
+    return typeof fm[key] === 'string' ? (fm[key] as string) : '';
+  }
+  function fmTags(key: string): Set<string> {
+    return new Set(Array.isArray(fm[key]) ? (fm[key] as unknown[]).map(String) : []);
+  }
+  function fmFreeTags(key: string): string {
+    return Array.isArray(fm[key]) ? (fm[key] as unknown[]).map(String).join(', ') : '';
+  }
+</script>
+
+<svelte:head>
+  <title>Edit {data.title} · {data.siteName} CMS</title>
+</svelte:head>
+
+<div class="flex items-center justify-between gap-4">
+  <div>
+    <a href="/admin" class="text-sm opacity-70 hover:underline">← Back</a>
+    <h1 class="mt-1 text-2xl font-bold">{data.title}</h1>
+    <p class="text-sm opacity-60">{data.label} · {data.path}</p>
+  </div>
+</div>
+
+{#if data.saved}
+  <div class="alert alert-success mt-6"><span>Saved — committed to main; the site will redeploy.</span></div>
+{:else if data.error}
+  <div class="alert alert-error mt-6"><span>{data.error}</span></div>
+{/if}
+
+<form method="POST" action="/admin/save" class="mt-6 flex flex-col gap-5">
+  <input type="hidden" name="type" value={data.type} />
+  <input type="hidden" name="id" value={data.id} />
+
+  <fieldset class="grid gap-4 rounded-box border border-base-300 bg-base-100 p-6">
+    {#each data.fields as field (field.name)}
+      {#if field.type === 'text' || field.type === 'date'}
+        <label class="flex flex-col gap-1">
+          <span class="text-sm font-medium">{field.label}</span>
+          <input
+            type={field.type === 'date' ? 'date' : 'text'}
+            name={field.name}
+            required={field.required}
+            value={fmString(field.name)}
+            class="input input-bordered w-full"
+          />
+        </label>
+      {:else if field.type === 'textarea'}
+        <label class="flex flex-col gap-1">
+          <span class="text-sm font-medium">{field.label}</span>
+          <textarea name={field.name} required={field.required} rows={field.rows ?? 4}
+            class="textarea textarea-bordered w-full">{fmString(field.name)}</textarea>
+        </label>
+      {:else if field.type === 'tags'}
+        <div class="flex flex-col gap-1">
+          <span class="text-sm font-medium">{field.label}</span>
+          <div class="flex flex-wrap gap-3">
+            {#each field.options as option (option)}
+              <label class="flex items-center gap-2 text-sm">
+                <input type="checkbox" name={field.name} value={option}
+                  checked={fmTags(field.name).has(option)} class="checkbox checkbox-sm" />
+                {option}
+              </label>
+            {/each}
+          </div>
+        </div>
+      {:else if field.type === 'freetags'}
+        <label class="flex flex-col gap-1">
+          <span class="text-sm font-medium">{field.label}</span>
+          <input type="text" name={field.name} value={fmFreeTags(field.name)}
+            placeholder={field.placeholder ?? 'comma, separated'} class="input input-bordered w-full" />
+        </label>
+      {:else if field.type === 'boolean'}
+        <label class="flex items-center gap-2 text-sm font-medium">
+          <input type="checkbox" name={field.name} checked={fm[field.name] === true} class="checkbox checkbox-sm" />
+          {field.label}
+        </label>
+      {/if}
+    {/each}
+  </fieldset>
+
+  <div class="rounded-box border border-base-300 bg-base-100 p-2">
+    <input type="hidden" name="body" value={body} />
+    {#if mounted}
+      <MarkdownEditor {carta} bind:value={body} mode="tabs" />
+    {:else}
+      <textarea bind:value={body} rows="20" class="textarea textarea-bordered w-full font-mono"></textarea>
+    {/if}
+  </div>
+
+  <div class="flex justify-end">
+    <button type="submit" class="btn btn-primary">Save &amp; commit</button>
+  </div>
+</form>

package/src/lib/components/LoginPage.svelte

@@ -0,0 +1,47 @@
+<script lang="ts">
+  // The magic-link sign-in page. Posts the email to /admin/auth/request; `sent`/`error` come
+  // from `loginLoad` (querystring) merged with `adminLayoutLoad` (siteName).
+  interface Props {
+    data: { siteName: string; sent: boolean; error: string | null };
+  }
+  let { data }: Props = $props();
+
+  const errorMessages: Record<string, string> = {
+    invalid: 'Please enter a valid email address.',
+    denied: 'That email is not on the editor allowlist.',
+    expired: 'That sign-in link has expired or was already used. Request a new one.',
+    config: 'Sign-in is not configured. Contact the site admin.',
+  };
+</script>
+
+<svelte:head>
+  <title>Sign in · {data.siteName} CMS</title>
+</svelte:head>
+
+<div class="mx-auto mt-16 max-w-md rounded-box border border-base-300 bg-base-100 p-8">
+  <h1 class="text-2xl font-bold">{data.siteName} CMS</h1>
+  <p class="mt-1 text-sm opacity-70">Sign in with your editor email.</p>
+
+  {#if data.sent}
+    <div class="alert alert-success mt-6">
+      <span>Check your inbox — a sign-in link is on its way. It expires in 10 minutes.</span>
+    </div>
+  {:else}
+    {#if data.error}
+      <div class="alert alert-error mt-6">
+        <span>{errorMessages[data.error] ?? 'Something went wrong. Try again.'}</span>
+      </div>
+    {/if}
+    <form method="POST" action="/admin/auth/request" class="mt-6 flex flex-col gap-3">
+      <input
+        type="email"
+        name="email"
+        required
+        autocomplete="email"
+        placeholder="you@example.com"
+        class="input input-bordered w-full"
+      />
+      <button type="submit" class="btn btn-primary">Email me a sign-in link</button>
+    </form>
+  {/if}
+</div>

package/src/lib/components/index.ts

@@ -0,0 +1,6 @@
+// cairn-cms admin UI shell. Consumers import from 'cairn-cms/components'; each site's
+// admin route `.svelte` files are one-line shims around these.
+export { default as AdminLayout } from './AdminLayout.svelte';
+export { default as AdminList } from './AdminList.svelte';
+export { default as LoginPage } from './LoginPage.svelte';
+export { default as EditPage } from './EditPage.svelte';

package/src/lib/content.ts

@@ -0,0 +1,11 @@
+// cairn-core: reassemble a markdown file from frontmatter + body for committing.
+//
+// The inverse of the gray-matter parse the edit loader does on read. Kept as its own seam
+// so a site adapter can own the on-disk serialization contract (quoting, key order)
+// without the save endpoint reaching for gray-matter directly.
+import matter from 'gray-matter';
+
+/** Serialize frontmatter data + markdown body back into a file string. */
+export function serializeMarkdown(frontmatter: object, body: string): string {
+  return matter.stringify(body, frontmatter);
+}

package/src/lib/email.ts

@@ -0,0 +1,35 @@
+// cairn-core: pluggable magic-link email sender.
+//
+// Default adapter is Cloudflare Email Service → Email Sending (transactional, arbitrary
+// recipients) — distinct from Email Routing's recipient-restricted `EmailMessage` flow.
+// It is reached through the same `send_email` binding (configured without a
+// destination_address) but a different call shape: `binding.send({ to, from, ... })`.
+// Resend can slot in behind the same `sendMagicLink` signature if needed.
+
+/** Cloudflare Email Sending binding surface (the object-form `send`, not the MIME form). */
+export interface EmailSender {
+  send(message: {
+    to: string;
+    from: string;
+    subject: string;
+    text?: string;
+    html?: string;
+  }): Promise<{ messageId: string }>;
+}
+
+export async function sendMagicLink(
+  sender: EmailSender,
+  to: string,
+  link: string,
+  siteName: string,
+  from: string,
+): Promise<void> {
+  const expiry = "This link expires in 10 minutes and works only once. If you didn't request it, ignore this email.";
+  await sender.send({
+    to,
+    from,
+    subject: `Your ${siteName} sign-in link`,
+    text: `Sign in to ${siteName}:\n\n${link}\n\n${expiry}`,
+    html: `<p>Sign in to ${siteName}:</p><p><a href="${link}">Sign in</a></p><p style="color:#666;font-size:0.9em">${expiry}</p>`,
+  });
+}