@glw907/cairn-cms 0.5.1 → 0.6.0-rc.0

package/src/lib/components/ManageEditors.svelte

@@ -0,0 +1,81 @@
+<!--
+@component
+The owner-gated editor management surface: a table of editors with role-flip and remove actions,
+and an add-editor form. The acting owner's own row disables its destructive controls; the
+last-owner anti-lockout rule itself is enforced server-side (editors-routes). Actions post to the
+named `?/setRole`, `?/remove`, and `?/add` actions.
+-->
+<script lang="ts">
+  import type { Editor } from '../auth/types.js';
+
+  interface Props {
+    /** The editors load's data, plus the site name. */
+    data: { editors: Editor[]; self: string; siteName: string };
+    /** The last action's result (an error message when it failed). */
+    form: { error?: string; ok?: boolean } | null;
+  }
+
+  let { data, form }: Props = $props();
+</script>
+
+<header class="mb-4">
+  <h1 class="text-xl font-semibold">Editors</h1>
+</header>
+
+{#if form?.error}
+  <div role="alert" class="alert alert-error mb-4 text-sm">{form.error}</div>
+{/if}
+
+<div class="overflow-x-auto rounded-box border border-base-300 bg-base-100 mb-6">
+  <table class="table">
+    <thead>
+      <tr><th scope="col">Name</th><th scope="col">Email</th><th scope="col">Role</th><th scope="col"><span class="sr-only">Actions</span></th></tr>
+    </thead>
+    <tbody>
+      {#each data.editors as editor (editor.email)}
+        {@const isSelf = editor.email === data.self}
+        <tr>
+          <td>{editor.displayName}</td>
+          <td>{editor.email}</td>
+          <td>
+            <span class="badge {editor.role === 'owner' ? 'badge-primary' : 'badge-ghost'}">{editor.role}</span>
+          </td>
+          <td class="flex justify-end gap-2">
+            <form method="POST" action="?/setRole">
+              <input type="hidden" name="email" value={editor.email} />
+              <input type="hidden" name="role" value={editor.role === 'owner' ? 'editor' : 'owner'} />
+              <button type="submit" class="btn btn-ghost btn-xs" disabled={isSelf} aria-label={`Toggle role for ${editor.displayName}`}>
+                {editor.role === 'owner' ? 'Make editor' : 'Make owner'}
+              </button>
+            </form>
+            <form method="POST" action="?/remove">
+              <input type="hidden" name="email" value={editor.email} />
+              <button type="submit" class="btn btn-ghost btn-xs text-error" disabled={isSelf} aria-label={`Remove ${editor.displayName}`}>
+                Remove
+              </button>
+            </form>
+          </td>
+        </tr>
+      {/each}
+    </tbody>
+  </table>
+</div>
+
+<form method="POST" action="?/add" class="rounded-box border border-base-300 bg-base-100 grid gap-3 p-4 sm:grid-cols-[1fr_1fr_auto_auto] sm:items-end">
+  <label class="flex flex-col gap-1">
+    <span class="text-sm font-medium">Name</span>
+    <input class="input" name="name" aria-label="Name" required />
+  </label>
+  <label class="flex flex-col gap-1">
+    <span class="text-sm font-medium">Email</span>
+    <input class="input" type="email" name="email" aria-label="Email" autocomplete="off" required />
+  </label>
+  <label class="flex flex-col gap-1">
+    <span class="text-sm font-medium">Role</span>
+    <select class="select" name="role" aria-label="Role">
+      <option value="editor">editor</option>
+      <option value="owner">owner</option>
+    </select>
+  </label>
+  <button type="submit" class="btn btn-primary">Add editor</button>
+</form>

package/src/lib/components/MarkdownEditor.svelte

@@ -0,0 +1,81 @@
+<!--
+@component
+The `MarkdownEditor` seam (spec §6, seam 5): a thin wrapper over Carta exposing a bindable value
+and a cursor-insert callback. Carta and Shiki are client-only, so the editor mounts after the
+component does; until then the hidden field still carries the value so the form submits correctly.
+Swapping Carta for a bare CodeMirror editor stays a one-file change.
+-->
+<script lang="ts">
+  import { onMount } from 'svelte';
+
+  interface Props {
+    /** The markdown source; bindable so the parent reads edits back. */
+    value: string;
+    /** The hidden field name the value is mirrored to for form submit. */
+    name: string;
+    /** Carta extensions from the adapter, for the design-accurate preview. */
+    plugins?: unknown[];
+    /** Receives a `(text) => void` that inserts at the cursor; the palette calls it. */
+    registerInsert?: (insert: (text: string) => void) => void;
+  }
+
+  let { value = $bindable(), name, plugins = [], registerInsert }: Props = $props();
+
+  // Local structural type for the Carta editing surface this seam uses. carta-md re-exports its
+  // Svelte components from the package entry, so its `Carta` class is not reachable as a named
+  // export under NodeNext; a structural type stays compatible without naming it (the shape
+  // legacy/src/lib/editor.ts relied on, verified against carta-md@4.11).
+  interface CartaInput {
+    getSelection(): { start: number };
+    insertAt(position: number, text: string): void;
+    update(): boolean;
+  }
+  interface CartaLike {
+    input?: CartaInput;
+  }
+
+  let mounted = $state(false);
+  // Carta and the MarkdownEditor component load only in the browser, after mount, so the server
+  // bundle never pulls in Carta or Shiki (guarded by the carta-boundary test). The component keeps
+  // its real type, so `value` stays bindable; the Carta constructor is reached through a cast
+  // because the package entry does not surface the class by name.
+  let Editor = $state<(typeof import('carta-md'))['MarkdownEditor'] | null>(null);
+  let carta = $state<CartaLike | null>(null);
+
+  onMount(async () => {
+    const mod = await import('carta-md');
+    const CartaCtor = (
+      mod as unknown as { Carta: new (options: { extensions?: unknown[]; sanitizer: false }) => CartaLike }
+    ).Carta;
+    const instance = new CartaCtor({
+      extensions: plugins,
+      // Sanitization is the site adapter's concern; the seam passes raw markdown through.
+      sanitizer: false,
+    });
+    carta = instance;
+    Editor = mod.MarkdownEditor;
+    // Insert at the current cursor through carta.input once the editor is mounted; fall back to
+    // appending while input is not yet populated (the pre-mount textarea phase).
+    registerInsert?.((text: string) => {
+      const inp = instance.input;
+      if (inp) {
+        const pos = inp.getSelection().start;
+        const prefix = pos > 0 ? '\n\n' : '';
+        inp.insertAt(pos, `${prefix}${text}`);
+        inp.update();
+      } else {
+        value = value ? `${value}\n\n${text}` : text;
+      }
+    });
+    mounted = true;
+  });
+</script>
+
+<input type="hidden" {name} value={value} />
+
+{#if mounted && Editor && carta}
+  {@const EditorComponent = Editor}
+  <EditorComponent carta={carta as never} bind:value theme="default" mode="tabs" />
+{:else}
+  <textarea class="textarea min-h-64 w-full font-mono text-sm" bind:value aria-label="Markdown source"></textarea>
+{/if}

package/src/lib/components/NavTree.svelte

@@ -1,18 +1,30 @@
+<!--
+@component
+The navigation tree editor. It edits a flat working copy of the menu (each row carries an
+explicit depth) and posts the whole tree as JSON to the save action. Vertical order comes from
+svelte-sortable-list (mouse, and keyboard with Space to lift, arrows to move, Space to drop);
+depth comes from the Indent and Outdent buttons, capped at the menu's maxDepth. The engine
+validates on save.
+-->
 <script lang="ts">
-  // The navigation tree editor (Pass L). Edits a local copy of the menu tree and posts the whole
-  // tree as JSON to the `save` action. DaisyUI primitives under the Warm Stone admin theme. Drag a
-  // row up or down to reorder within its level; use Indent/Outdent to nest under the previous
-  // sibling or promote a level (capped at the menu's maxDepth). The engine validates on save.
   import { untrack } from 'svelte';
-  import type { NavLoadData } from '../sveltekit';
-  import type { NavNode } from '../nav';
+  import { SortableList, sortItems } from '@rodrigodagostino/svelte-sortable-list';
+  import type { SortableList as SortableListNS } from '@rodrigodagostino/svelte-sortable-list';
+  import '@rodrigodagostino/svelte-sortable-list/styles.css';
+  import type { NavLoadData } from '../sveltekit/nav-routes.js';
+  import type { NavNode } from '../nav/site-config.js';
 
-  let { data }: { data: NavLoadData } = $props();
+  interface Props {
+    /** The nav load's data: the menu meta, the current tree, page options, and flags. */
+    data: NavLoadData;
+  }
+
+  let { data }: Props = $props();
 
-  // A flat, ordered working model is far simpler to drag-edit than a recursive one: each row
-  // carries an explicit depth, and the tree is rebuilt from (order + depth) only at submit time.
+  // A flat, ordered working model is simpler to reorder than a recursive one: each row carries an
+  // explicit depth, and the nested tree is rebuilt from order plus depth only at submit time.
   interface Row {
-    id: number;
+    id: string;
     depth: number;
     label: string;
     url: string;
@@ -21,14 +33,19 @@
   let nextId = 1;
   function flatten(nodes: NavNode[], depth: number, out: Row[]): Row[] {
     for (const n of nodes) {
-      out.push({ id: nextId++, depth, label: n.label, url: n.url ?? '' });
+      out.push({ id: `row-${nextId++}`, depth, label: n.label, url: n.url ?? '' });
       if (n.children?.length) flatten(n.children, depth + 1, out);
     }
     return out;
   }
 
+  // untrack here is not for runtime behavior -- $state runs its initializer once regardless.
+  // It suppresses the Svelte compiler warning that `data` (a prop) is referenced outside a
+  // reactive context. The component is always remounted on save/error (both redirect), so
+  // a one-time snapshot of the initial tree is correct.
   let rows = $state<Row[]>(untrack(() => flatten(data.tree, 0, [])));
-  const maxDepthIndex = $derived(data.menu.maxDepth - 1); // depth is 0-based here
+  // depth is 0-based internally; maxDepth in the config is 1-based (1 = flat, 2 = one nesting level)
+  const maxDepthIndex = $derived(data.menu.maxDepth - 1);
 
   // Rebuild the nested tree from the flat rows by depth, then serialize for the hidden field.
   function toTree(list: Row[]): NavNode[] {
@@ -48,9 +65,9 @@
   const treeJson = $derived(JSON.stringify(toTree(rows)));
 
   function addRow() {
-    rows = [...rows, { id: nextId++, depth: 0, label: 'New item', url: '' }];
+    rows = [...rows, { id: `row-${nextId++}`, depth: 0, label: 'New item', url: '' }];
   }
-  function removeRow(id: number) {
+  function removeRow(id: string) {
     rows = rows.filter((r) => r.id !== id);
   }
   function indent(i: number) {
@@ -63,66 +80,59 @@
     if (rows[i].depth > 0) rows[i].depth -= 1;
   }
 
-  let dragFrom = $state<number | null>(null);
-  function onDrop(to: number) {
-    if (dragFrom === null || dragFrom === to) return;
-    const next = [...rows];
-    const [moved] = next.splice(dragFrom, 1);
-    next.splice(to, 0, moved);
-    rows = next;
-    dragFrom = null;
+  function handleDragEnd(e: SortableListNS.RootEvents['ondragend']) {
+    const { draggedItemIndex, targetItemIndex, isCanceled } = e;
+    if (!isCanceled && typeof targetItemIndex === 'number' && draggedItemIndex !== targetItemIndex) {
+      rows = sortItems(rows, draggedItemIndex, targetItemIndex);
+    }
   }
 </script>
 
-<div class="cairn-admin">
-  <div class="flex items-center justify-between">
-    <h1 class="text-xl font-semibold">{data.menu.label}</h1>
+<h1 class="mb-4 text-xl font-semibold">{data.menu.label}</h1>
+
+{#if data.saved}
+  <div role="status" class="alert alert-success mb-4 text-sm">Navigation saved.</div>
+{/if}
+{#if data.error}
+  <div role="alert" class="alert alert-error mb-4 text-sm">{data.error}</div>
+{/if}
+
+<form method="POST" action="?/save">
+  <input type="hidden" name="tree" value={treeJson} />
+
+  <div class="mb-2">
     <button type="button" class="btn btn-sm" onclick={addRow}>Add item</button>
   </div>
 
-  {#if data.saved}
-    <div class="alert alert-success mt-3">Navigation saved.</div>
-  {/if}
-  {#if data.error}
-    <div class="alert alert-error mt-3">{data.error}</div>
-  {/if}
-
-  <form method="POST" action="?/save" class="mt-4">
-    <input type="hidden" name="tree" value={treeJson} />
-    <ul class="menu w-full gap-1">
-      {#each rows as row, i (row.id)}
-        <li
-          draggable="true"
-          ondragstart={() => (dragFrom = i)}
-          ondragover={(e) => e.preventDefault()}
-          ondrop={() => onDrop(i)}
-          style={`margin-left:${row.depth * 1.5}rem`}
-        >
-          <div class="flex items-center gap-2 p-2">
-            <span class="cursor-grab opacity-40" aria-hidden="true">&#x283F;</span>
-            <input class="input input-sm input-bordered flex-1" placeholder="Label" bind:value={row.label} />
+  <div class="sortable-list-area" style="min-height:2.5rem">
+    <SortableList.Root ondragend={handleDragEnd} aria-label="Navigation items">
+      {#each rows as row, index (row.id)}
+        <SortableList.Item id={row.id} {index} aria-label={`${row.label || 'Untitled'}, level ${row.depth + 1}`}>
+          <div class="flex items-center gap-2 p-2" style={`margin-left:${row.depth * 1.5}rem`}>
+            <input class="input input-sm flex-1" placeholder="Label" aria-label="Label" bind:value={row.label} />
             <input
-              class="input input-sm input-bordered flex-1"
-              placeholder="/path or https://…"
+              class="input input-sm flex-1"
+              placeholder="/path or https://example.com"
               list="cairn-nav-pages"
+              aria-label="URL"
               bind:value={row.url}
             />
-            <button type="button" class="btn btn-xs btn-ghost" onclick={() => outdent(i)} aria-label="Outdent">&larr;</button>
-            <button type="button" class="btn btn-xs btn-ghost" onclick={() => indent(i)} aria-label="Indent">&rarr;</button>
-            <button type="button" class="btn btn-xs btn-ghost text-error" onclick={() => removeRow(row.id)} aria-label="Remove">&times;</button>
+            <button type="button" class="btn btn-xs btn-ghost" onclick={() => outdent(index)} aria-label="Outdent">&larr;</button>
+            <button type="button" class="btn btn-xs btn-ghost" onclick={() => indent(index)} aria-label="Indent">&rarr;</button>
+            <button type="button" class="btn btn-xs btn-ghost text-error" onclick={() => removeRow(row.id)} aria-label={`Remove ${row.label}`}>&times;</button>
           </div>
-        </li>
+        </SortableList.Item>
       {/each}
-    </ul>
+    </SortableList.Root>
+  </div>
 
-    <datalist id="cairn-nav-pages">
-      {#each data.pages as p (p.url)}
-        <option value={p.url}>{p.label}</option>
-      {/each}
-    </datalist>
+  <datalist id="cairn-nav-pages">
+    {#each data.pages as p (p.url)}
+      <option value={p.url}>{p.label}</option>
+    {/each}
+  </datalist>
 
-    <div class="mt-4">
-      <button type="submit" class="btn btn-primary btn-sm">Save navigation</button>
-    </div>
-  </form>
-</div>
+  <div class="mt-4">
+    <button type="submit" class="btn btn-primary btn-sm">Save navigation</button>
+  </div>
+</form>

package/src/lib/components/cairn-admin.css

@@ -0,0 +1,42 @@
+/* Warm Stone: the cairn admin theme. Self-contained, since DaisyUI v5 reads these vars at point
+   of use, so this fully overrides the host's theme with no @plugin and no host build step. */
+[data-theme='cairn-admin'] {
+  color-scheme: light;
+  font-family: system-ui, -apple-system, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif;
+
+  --color-base-100: oklch(98.5% 0.004 75);
+  --color-base-200: oklch(96% 0.005 75);
+  --color-base-300: oklch(92% 0.008 75);
+  --color-base-content: oklch(28% 0.012 75);
+
+  --color-primary: oklch(52% 0.2 293);
+  --color-primary-content: oklch(98% 0.012 293);
+  --color-secondary: oklch(45% 0.02 75);
+  --color-secondary-content: oklch(98% 0.004 75);
+  --color-accent: oklch(58% 0.16 300);
+  --color-accent-content: oklch(98% 0.012 300);
+  --color-neutral: oklch(32% 0.012 75);
+  --color-neutral-content: oklch(96% 0.004 75);
+
+  --color-info: oklch(60% 0.12 240);
+  --color-info-content: oklch(98% 0.012 240);
+  --color-success: oklch(58% 0.12 150);
+  --color-success-content: oklch(98% 0.012 150);
+  --color-warning: oklch(75% 0.15 70);
+  --color-warning-content: oklch(26% 0.05 70);
+  --color-error: oklch(58% 0.2 25);
+  --color-error-content: oklch(98% 0.012 25);
+
+  /* Accessible muted text tones: >= 4.5:1 contrast on base-100/base-200. */
+  --color-muted: oklch(48% 0.01 75);
+  --color-subtle: oklch(42% 0.01 75);
+
+  --radius-selector: 0.5rem;
+  --radius-field: 0.5rem;
+  --radius-box: 0.75rem;
+  --size-selector: 0.25rem;
+  --size-field: 0.25rem;
+  --border: 1px;
+  --depth: 1;
+  --noise: 0;
+}

package/src/lib/components/index.ts

@@ -1,10 +1,11 @@
-// cairn-cms admin UI shell. Consumers import from 'cairn-cms/components'; each site's
-// admin route `.svelte` files are one-line shims around these.
+// Admin Svelte components (Plan 05). The Warm Stone theme ships as a CSS side effect imported
+// by the components that set `data-theme="cairn-admin"`.
 export { default as AdminLayout } from './AdminLayout.svelte';
-export { default as CollectionList } from './CollectionList.svelte';
 export { default as LoginPage } from './LoginPage.svelte';
 export { default as ConfirmPage } from './ConfirmPage.svelte';
+export { default as ConceptList } from './ConceptList.svelte';
 export { default as EditPage } from './EditPage.svelte';
-export { default as ManageAdmins } from './ManageAdmins.svelte';
+export { default as ManageEditors } from './ManageEditors.svelte';
+export { default as MarkdownEditor } from './MarkdownEditor.svelte';
 export { default as ComponentPalette } from './ComponentPalette.svelte';
 export { default as NavTree } from './NavTree.svelte';

package/src/lib/content/compose.ts

@@ -0,0 +1,39 @@
+// cairn-cms: composition aggregation (seam 2). One place folds the adapter and any
+// extensions into the runtime the engine serves from. A future `CairnExtension` folds in
+// 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, FieldTypeDef } from './types.js';
+import { normalizeConcepts } from './concepts.js';
+
+/**
+ * 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.
+ */
+export function composeRuntime(
+  adapter: CairnAdapter,
+  extensions: CairnExtension[] = [],
+): CairnRuntime {
+  const content: Record<string, ConceptConfig | undefined> = { ...adapter.content };
+  const adminPanels: AdminPanel[] = [];
+  const fieldTypes: FieldTypeDef[] = [];
+  for (const extension of extensions) {
+    // An extension adds concepts; a key that collides with the adapter is last-write-wins.
+    // Reserved seam, unused today, so the collision policy is deliberately left simple.
+    if (extension.content) Object.assign(content, extension.content);
+    if (extension.adminPanels) adminPanels.push(...extension.adminPanels);
+    if (extension.fieldTypes) fieldTypes.push(...extension.fieldTypes);
+  }
+  return {
+    siteName: adapter.siteName,
+    concepts: normalizeConcepts(content),
+    backend: adapter.backend,
+    sender: adapter.sender,
+    renderPreview: adapter.renderPreview,
+    registry: adapter.registry,
+    navMenu: adapter.navMenu,
+    assets: adapter.assets,
+    adminPanels,
+    fieldTypes,
+  };
+}

package/src/lib/content/concepts.ts

@@ -0,0 +1,57 @@
+// cairn-cms: concept normalization (seam 1). The adapter declares concepts as
+// `content: { posts?, pages? }`; this turns each declared key into a uniform descriptor
+// (id, label, directory, concept-fixed routing, fields, validator) the admin reads. A
+// future Fragments concept attaches by adding one key under `content` and one routing
+// entry, with no reshape here.
+import type { ConceptConfig, ConceptDescriptor, RoutingRule } from './types.js';
+
+/**
+ * Concept-fixed routing, keyed by concept id (spec §7.2). Posts are dated feed entries;
+ * pages are plain navigable structure. Not in adapter config. A future Fragments adds one
+ * entry here and one key under `content`.
+ */
+export const CONCEPT_ROUTING: Readonly<Record<string, RoutingRule>> = {
+  posts: { routable: true, dated: true, inFeeds: true },
+  pages: { routable: true, dated: false, inFeeds: false },
+};
+
+/** Routing for a concept with no table entry: a plain, non-feed, routable page. */
+const DEFAULT_ROUTING: RoutingRule = { routable: true, dated: false, inFeeds: false };
+
+/** Title-case a concept id for the default sidebar label, e.g. "posts" to "Posts". */
+function defaultLabel(id: string): string {
+  return id.charAt(0).toUpperCase() + id.slice(1);
+}
+
+/**
+ * Normalize an adapter's declared concepts into uniform descriptors (seam 1). Each declared
+ * key under `content` becomes one descriptor; an undeclared (`undefined`) concept is
+ * skipped. `routing` is injectable so a contract test can prove a new concept attaches
+ * additively; production passes the default `CONCEPT_ROUTING`.
+ */
+export function normalizeConcepts(
+  content: Record<string, ConceptConfig | undefined>,
+  routing: Readonly<Record<string, RoutingRule>> = CONCEPT_ROUTING,
+): ConceptDescriptor[] {
+  const descriptors: ConceptDescriptor[] = [];
+  for (const [id, config] of Object.entries(content)) {
+    if (!config) continue;
+    descriptors.push({
+      id,
+      label: config.label ?? defaultLabel(id),
+      dir: config.dir,
+      routing: routing[id] ?? DEFAULT_ROUTING,
+      fields: config.fields,
+      validate: config.validate,
+    });
+  }
+  return descriptors;
+}
+
+/** Look up a normalized concept by id, or undefined when the site does not enable it. */
+export function findConcept(
+  concepts: ConceptDescriptor[],
+  id: string,
+): ConceptDescriptor | undefined {
+  return concepts.find((concept) => concept.id === id);
+}

package/src/lib/content/frontmatter.ts

@@ -0,0 +1,71 @@
+// cairn-cms: frontmatter form decoding and on-disk serialization. `frontmatterFromForm`
+// is the form-to-data half of the edit loop; `serializeMarkdown`/`parseMarkdown` are the
+// on-disk write/read pair. Kept as one seam so a site owns its serialization contract
+// (quoting, key order) without the save endpoint reaching for gray-matter directly.
+import matter from 'gray-matter';
+import type { FrontmatterField } from './types.js';
+
+/** Decode submitted form data into raw frontmatter, one rule per field type. */
+export function frontmatterFromForm(
+  fields: FrontmatterField[],
+  form: FormData,
+): Record<string, unknown> {
+  const data: Record<string, unknown> = {};
+  for (const field of 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 to 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:
+        // FormData.get returns null for an absent field; normalize to an empty string so
+        // a caller reading a text value never gets null.
+        data[field.name] = form.get(field.name) ?? '';
+    }
+  }
+  return data;
+}
+
+/**
+ * Coerce a frontmatter date value to the `YYYY-MM-DD` an `<input type="date">` wants.
+ * gray-matter parses an unquoted YAML date into a JS Date, so a string-only read would
+ * leave the input empty and drop the date on save. A parsed YAML date is UTC midnight, so
+ * slicing the ISO string avoids a local-timezone shift.
+ */
+export function dateInputValue(value: unknown): string {
+  if (value instanceof Date) {
+    return Number.isNaN(value.getTime()) ? '' : value.toISOString().slice(0, 10);
+  }
+  if (typeof value === 'string') {
+    const match = value.match(/^\d{4}-\d{2}-\d{2}/);
+    return match ? match[0] : '';
+  }
+  return '';
+}
+
+/** Reassemble a markdown file from frontmatter and body for committing. */
+export function serializeMarkdown(frontmatter: object, body: string): string {
+  return matter.stringify(body, frontmatter);
+}
+
+/** Parse a markdown file into its frontmatter and body: the read-side inverse of serialize. */
+export function parseMarkdown(source: string): {
+  frontmatter: Record<string, unknown>;
+  body: string;
+} {
+  const parsed = matter(source);
+  return { frontmatter: parsed.data, body: parsed.content };
+}

package/src/lib/content/ids.ts

@@ -0,0 +1,38 @@
+// cairn-cms: filename-based content ids (spec §7.2). An entry's id is its markdown filename
+// without `.md`, so there is no slug codec. `slugify` derives a filename-safe stem from a
+// title for the create-entry form.
+
+/** Lowercase alphanumerics with single internal hyphens: the on-disk filename stem rule. */
+const ID_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+/** True when `id` is a valid filename stem: lowercase, no slashes, no leading or trailing hyphen. */
+export function isValidId(id: string): boolean {
+  return ID_RE.test(id);
+}
+
+/**
+ * A content entry's id from its filename: the basename without the `.md` suffix. Pass a
+ * basename, not a path; the caller strips any directory prefix first (Plan 03's Git Trees
+ * listing yields basenames directly).
+ */
+export function idFromFilename(filename: string): string {
+  return filename.replace(/\.md$/, '');
+}
+
+/** The on-disk filename for an id: the id plus `.md`. */
+export function filenameFromId(id: string): string {
+  return `${id}.md`;
+}
+
+/**
+ * Lowercase a title into a filename-safe slug stem. Apostrophes are dropped so "Geoff's"
+ * becomes "geoffs" (no spurious hyphen). All other non-alphanumeric runs collapse to a
+ * single hyphen; leading and trailing hyphens are trimmed.
+ */
+export function slugify(title: string): string {
+  return title
+    .toLowerCase()
+    .replace(/'/g, '')
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}