@glw907/cairn-cms 0.38.0 → 0.41.0

package/src/lib/components/WebLinkDialog.svelte

@@ -0,0 +1,89 @@
+<!--
+@component
+The Web link control and its modal: the way to link out to an ordinary web address, beside the
+Link to page picker that handles internal targets. Two fields, the address and an optional display
+text; when the editor holds a selection it arrives as the default text, and the insert seam wraps
+that selection either way. Built on a native <dialog>, following the LinkPicker a11y conventions,
+and opened by the host's Ctrl/Cmd+K shortcut through the exported open().
+-->
+<script lang="ts">
+  interface Props {
+    /** Insert an inline link at the editor cursor; the editor's registerInsertLink seam. */
+    insert: (href: string, title: string) => void;
+    /** Read the editor's current selection, for the Text field's default. */
+    selection?: () => string;
+    /** Disable the trigger; the host sets it while Preview shows. */
+    disabled?: boolean;
+    /** Render the built-in Web link trigger. False mounts only the dialog, for a host that
+     *  supplies its own trigger and opens the dialog through the exported open(). */
+    trigger?: boolean;
+  }
+
+  let { insert, selection, disabled = false, trigger = true }: Props = $props();
+
+  let dialog = $state<HTMLDialogElement | null>(null);
+  let hrefInput = $state<HTMLInputElement | null>(null);
+  let href = $state('');
+  let text = $state('');
+
+  /** Open the dialog with fresh fields; the edit page's Ctrl/Cmd+K shortcut calls it too. */
+  export function open() {
+    href = '';
+    text = selection?.() ?? '';
+    dialog?.showModal();
+    // showModal() lands focus on the first focusable element (the header Close button), so move
+    // it to the address input the dialog exists for (WCAG 2.4.3). A microtask defers past the
+    // dialog's own focus handling, the RenameDialog recipe.
+    queueMicrotask(() => hrefInput?.focus());
+  }
+  function close() {
+    dialog?.close();
+  }
+  function submit(e: SubmitEvent) {
+    e.preventDefault();
+    // With no text and no selection the address itself becomes the display text, so the link
+    // never renders as an invisible pair of brackets.
+    insert(href, text.trim() || href);
+    close();
+  }
+</script>
+
+{#if trigger}
+  <button
+    type="button"
+    class="btn btn-sm btn-ghost"
+    aria-haspopup="dialog"
+    aria-label="Web link (Ctrl+K)"
+    title="Web link (Ctrl+K)"
+    {disabled}
+    onclick={open}
+  >
+    Web link
+  </button>
+{/if}
+
+<dialog class="modal" aria-labelledby="cairn-web-link-dialog-title" bind:this={dialog}>
+  <div class="modal-box">
+    <div class="mb-3 flex items-center justify-between">
+      <h2 id="cairn-web-link-dialog-title" class="text-base font-semibold">Add a web link</h2>
+      <button type="button" class="btn btn-ghost btn-sm" aria-label="Close" onclick={close}>✕</button>
+    </div>
+    <form onsubmit={submit} class="flex flex-col gap-3">
+      <label class="flex flex-col gap-1">
+        <span class="text-sm font-medium">Web address</span>
+        <input class="input w-full" type="url" required placeholder="https://…" bind:value={href} bind:this={hrefInput} />
+      </label>
+      <label class="flex flex-col gap-1">
+        <span class="text-sm font-medium">Text</span>
+        <input class="input w-full" placeholder="What the link says" bind:value={text} />
+      </label>
+      <div class="flex justify-end gap-2">
+        <button type="button" class="btn btn-sm" onclick={close}>Cancel</button>
+        <button type="submit" class="btn btn-sm btn-primary">Add link</button>
+      </div>
+    </form>
+  </div>
+  <form method="dialog" class="modal-backdrop">
+    <button tabindex="-1" aria-label="Close">close</button>
+  </form>
+</dialog>

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

@@ -24,18 +24,22 @@
   --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);
+  /* 54% holds AA for the editor's directive ink on base-100 (5.28:1) and on its own 8% accent
+     tint (4.75:1); 58% failed the tint at 4.04:1. A locked margin, like the dark nav pair. */
+  --color-accent: oklch(54% 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);
+  /* The info, success, and error tones sit dark enough for >= 4.5:1 white text (WCAG AA) on the
+     badge and alert fills. Measured: info 5.12:1, success 4.94:1, error 4.83:1. */
+  --color-info: oklch(52% 0.12 240);
   --color-info-content: oklch(98% 0.012 240);
-  --color-success: oklch(58% 0.12 150);
+  --color-success: oklch(52% 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: oklch(56% 0.2 25);
   --color-error-content: oklch(98% 0.012 25);
 
   /* Accessible muted text tones: >= 4.5:1 contrast on base-100/base-200. */
@@ -181,6 +185,24 @@
       0 2px 4px color-mix(in oklch, var(--color-primary) 26%, transparent),
       0 10px 24px -5px color-mix(in oklch, var(--color-primary) 48%, transparent);
   }
+
+  /* The hoisted document title is a text-entry surface like the editor: browsers treat a focused
+     text input as keyboard-modal, so the page-wide 2px focus-visible ring above would shout
+     through every typing session. It gets the editor's quiet always-on hairline instead (WCAG
+     2.4.7), at the 70% primary mix that clears the 3:1 non-text contrast floor on both themes
+     (WCAG 1.4.11). The class-plus-pseudo selector outranks the bare :focus-visible rule. */
+  :where([data-theme='cairn-admin'], [data-theme='cairn-admin-dark']) .cairn-doc-title:focus {
+    outline: 1px solid color-mix(in oklab, var(--color-primary) 70%, transparent);
+    outline-offset: -1px;
+  }
+
+  /* The admin topbar plus the edit page's sticky action header stack about 120px of veil over the
+     top of the content column, and a control the browser scrolls into view could land hidden
+     beneath them (WCAG 2.4.11 Focus Not Obscured). The scroll margin keeps any focus or fragment
+     scroll clear of the whole sticky stack. */
+  :where([data-theme='cairn-admin'], [data-theme='cairn-admin-dark']) :is(a, button, input, textarea, select, summary, [tabindex]) {
+    scroll-margin-top: 8.5rem;
+  }
 }
 
 /* Respect a reduced-motion preference inside the admin. DaisyUI's modal, drawer, and the admin's

package/src/lib/components/editor-highlight.ts

@@ -0,0 +1,67 @@
+// The editor's syntax colors and the directive machinery decorations. Colors reference the Warm
+// Stone CSS variables so light and dark themes both resolve, and every token pair must hold WCAG
+// AA against --color-base-100 (checked in the design pass).
+import { HighlightStyle } from '@codemirror/language';
+import { tags } from '@lezer/highlight';
+import { Decoration, ViewPlugin, type DecorationSet, type EditorView, type ViewUpdate } from '@codemirror/view';
+import { RangeSetBuilder } from '@codemirror/state';
+import { directiveLineKind, findInlineDirectives } from './markdown-directives.js';
+
+/** Markdown token colors over the admin theme variables. */
+export function cairnHighlightStyle(): HighlightStyle {
+  return HighlightStyle.define([
+    { tag: tags.heading, color: 'var(--color-primary)', fontWeight: '700' },
+    { tag: tags.strong, fontWeight: '700' },
+    { tag: tags.emphasis, fontStyle: 'italic' },
+    { tag: tags.strikethrough, textDecoration: 'line-through' },
+    { tag: tags.link, color: 'var(--color-info)' },
+    { tag: tags.url, color: 'var(--color-info)' },
+    { tag: tags.quote, color: 'var(--color-muted)', fontStyle: 'italic' },
+    { tag: tags.monospace, color: 'var(--color-accent)' },
+    { tag: tags.processingInstruction, color: 'var(--color-muted)' },
+    { tag: tags.list, color: 'var(--color-muted)' },
+  ]);
+}
+
+// The machinery lines explain themselves on hover, so an editor who has never seen ::: syntax
+// learns what the line is without leaving the page.
+const MACHINERY_HINT = 'Layout marker. Edit the text between these lines and leave this line as it is.';
+
+const fenceLine = Decoration.line({ class: 'cm-cairn-directive-fence', attributes: { title: MACHINERY_HINT } });
+const leafLine = Decoration.line({ class: 'cm-cairn-directive-leaf', attributes: { title: MACHINERY_HINT } });
+const inlineMark = Decoration.mark({ class: 'cm-cairn-directive-inline' });
+
+function buildDirectiveDecorations(view: EditorView): DecorationSet {
+  const builder = new RangeSetBuilder<Decoration>();
+  for (const { from, to } of view.visibleRanges) {
+    for (let pos = from; pos <= to; ) {
+      const line = view.state.doc.lineAt(pos);
+      const kind = directiveLineKind(line.text);
+      if (kind === 'fence') builder.add(line.from, line.from, fenceLine);
+      else if (kind === 'leaf') builder.add(line.from, line.from, leafLine);
+      else {
+        for (const r of findInlineDirectives(line.text)) {
+          builder.add(line.from + r.from, line.from + r.to, inlineMark);
+        }
+      }
+      pos = line.to + 1;
+    }
+  }
+  return builder.finish();
+}
+
+/** Line and mark decorations flagging remark-directive machinery. */
+export function cairnDirectivePlugin() {
+  return ViewPlugin.fromClass(
+    class {
+      decorations: DecorationSet;
+      constructor(view: EditorView) {
+        this.decorations = buildDirectiveDecorations(view);
+      }
+      update(update: ViewUpdate) {
+        if (update.docChanged || update.viewportChanged) this.decorations = buildDirectiveDecorations(update.view);
+      }
+    },
+    { decorations: (v) => v.decorations },
+  );
+}

package/src/lib/components/link-completion.ts

@@ -3,10 +3,14 @@
 // to CodeMirror's CompletionSource. The editor wires the source through a generic completionSources
 // prop, so this stays the only link-aware piece and the seam itself knows nothing about links.
 import type { Completion, CompletionContext, CompletionResult, CompletionSource } from '@codemirror/autocomplete';
-import { syntaxTree } from '@codemirror/language';
 import type { LinkTarget } from '../content/manifest.js';
 import { formatCairnToken, escapeLinkText } from '../content/links.js';
 
+// EditPage imports this module statically, so a static @codemirror value import here would pull
+// CodeMirror into a consumer's server bundle. syntaxTree resolves lazily inside the source
+// instead (a CompletionSource may return a Promise), cached after the first completion.
+let langMod: typeof import('@codemirror/language') | null = null;
+
 /** The known concepts in display order; an unlisted concept sorts after these under its own name. */
 const CONCEPT_SECTIONS: Record<string, { name: string; rank: number }> = {
   pages: { name: 'Pages', rank: 0 },
@@ -41,14 +45,17 @@ export function linkCompletions(targets: LinkTarget[], query: string): Completio
  *  whole `[[query` with the chosen link, and sets filter:false because linkCompletions already
  *  filtered by the query (CodeMirror would otherwise re-filter against the literal `[[query`). */
 export function cairnLinkCompletionSource(targets: LinkTarget[]): CompletionSource {
-  return (context: CompletionContext): CompletionResult | null => {
+  return async (context: CompletionContext): Promise<CompletionResult | null> => {
     const line = context.state.doc.lineAt(context.pos);
     const before = context.state.sliceDoc(line.from, context.pos);
     const trigger = matchCairnTrigger(before);
     if (!trigger) return null;
     // Skip a [[ inside a fenced or inline code node: a cairn link there would be literal text, and
     // the build resolver does not look inside code. The node name carries "Code" for both forms.
-    const node = syntaxTree(context.state).resolveInner(context.pos, -1);
+    langMod ??= await import('@codemirror/language');
+    // The first completion awaits the import above, so the request may already be stale here.
+    if (context.aborted) return null;
+    const node = langMod.syntaxTree(context.state).resolveInner(context.pos, -1);
     for (let n: typeof node | null = node; n; n = n.parent) {
       if (/Code/.test(n.name)) return null;
     }

package/src/lib/components/markdown-directives.ts

@@ -0,0 +1,23 @@
+// Remark-directive detection for the editor's machinery highlighting (spec: directive syntax is
+// styled distinctly so an editor can tell component scaffolding from prose). Pure functions; the
+// CodeMirror decoration plugin wraps them.
+
+const FENCE = /^\s{0,3}:::+\s*[\w-]*\s*(\{[^}]*\})?\s*$/;
+const LEAF = /^\s{0,3}::[\w-]+(\[[^\]]*\])?(\{[^}]*\})?\s*$/;
+const INLINE = /(?<![:\w]):[\w-]+\[[^\]]*\](\{[^}]*\})?/g;
+
+/** Classify a whole line as a container fence, a leaf directive, or neither. */
+export function directiveLineKind(line: string): 'fence' | 'leaf' | null {
+  if (FENCE.test(line)) return 'fence';
+  if (LEAF.test(line)) return 'leaf';
+  return null;
+}
+
+/** Inline directive ranges (`:name[...]{...}`) within a line of text. */
+export function findInlineDirectives(text: string): { from: number; to: number }[] {
+  const out: { from: number; to: number }[] = [];
+  for (const m of text.matchAll(INLINE)) {
+    out.push({ from: m.index, to: m.index + m[0].length });
+  }
+  return out;
+}

package/src/lib/components/markdown-format.ts

@@ -10,7 +10,21 @@ import { visit } from 'unist-util-visit';
 import type { Link } from 'mdast';
 import { escapeLinkText } from '../content/links.js';
 
-export type FormatKind = 'bold' | 'italic' | 'code' | 'heading' | 'quote' | 'ul' | 'link';
+export type FormatKind =
+  | 'bold'
+  | 'italic'
+  | 'code'
+  | 'strike'
+  | 'h2'
+  | 'h3'
+  | 'quote'
+  | 'ul'
+  | 'ol'
+  | 'task'
+  | 'codeblock'
+  | 'hr'
+  | 'table'
+  | 'link';
 
 export interface FormatResult {
   doc: string;
@@ -18,14 +32,92 @@ export interface FormatResult {
   to: number;
 }
 
-const WRAP: Record<'bold' | 'italic' | 'code', string> = { bold: '**', italic: '_', code: '`' };
-const LINE_PREFIX: Record<'heading' | 'quote' | 'ul', string> = { heading: '# ', quote: '> ', ul: '- ' };
+type WrapKind = 'bold' | 'italic' | 'code' | 'strike';
+type LineKind = 'h2' | 'h3' | 'quote' | 'ul' | 'ol' | 'task';
+
+const WRAP: Record<WrapKind, string> = { bold: '**', italic: '_', code: '`', strike: '~~' };
+
+/**
+ * Per-kind line-prefix behavior. `prefix` builds the marker for the line's 0-based index (only ol
+ * varies by line). `exact` matches a line already carrying this kind's own marker; when every
+ * selected line matches, the format toggles off. `strip` matches a competing marker to replace
+ * before prefixing, so h2 on an h3 line swaps the level instead of stacking. Quote and ul keep
+ * their original add-only behavior, so they carry neither regex.
+ */
+const LINE: Record<LineKind, { prefix: (i: number) => string; exact?: RegExp; strip?: RegExp }> = {
+  h2: { prefix: () => '## ', exact: /^## /, strip: /^#{1,6} / },
+  h3: { prefix: () => '### ', exact: /^### /, strip: /^#{1,6} / },
+  quote: { prefix: () => '> ' },
+  ul: { prefix: () => '- ' },
+  ol: { prefix: (i) => `${i + 1}. `, exact: /^\d+\. /, strip: /^\d+\. / },
+  task: { prefix: () => '- [ ] ', exact: /^- \[[ xX]\] /, strip: /^- \[[ xX]\] / },
+};
+
+const TABLE_GRID =
+  '| Column 1 | Column 2 |\n| -------- | -------- |\n|          |          |\n|          |          |';
+
+/** Wrap the selection in `marker`, or unwrap when the markers are already there (inside or just
+ *  outside the selection). The returned range covers the text without its markers either way. */
+function toggleWrap(doc: string, from: number, to: number, marker: string): FormatResult {
+  const m = marker.length;
+  const sel = doc.slice(from, to);
+  if (sel.length >= 2 * m && sel.startsWith(marker) && sel.endsWith(marker)) {
+    const inner = sel.slice(m, sel.length - m);
+    return { doc: doc.slice(0, from) + inner + doc.slice(to), from, to: to - 2 * m };
+  }
+  if (from >= m && doc.slice(from - m, from) === marker && doc.slice(to, to + m) === marker) {
+    return { doc: doc.slice(0, from - m) + sel + doc.slice(to + m), from: from - m, to: to - m };
+  }
+  const next = doc.slice(0, from) + marker + sel + marker + doc.slice(to);
+  return { doc: next, from: from + m, to: to + m };
+}
+
+/** Apply a line-prefix kind to every selected line. When the kind toggles and every line already
+ *  carries its marker, the markers come off; otherwise competing markers are replaced and each
+ *  line gains the kind's prefix. The selection shifts with the first line's edit and stretches
+ *  by the total length change, the same mechanics the original single-prefix version had. */
+function applyLinePrefix(doc: string, from: number, to: number, kind: LineKind): FormatResult {
+  const { prefix, exact, strip } = LINE[kind];
+  const lineStart = doc.lastIndexOf('\n', from - 1) + 1; // 0 when the selection is on the first line
+  const lines = doc.slice(lineStart, to).split('\n');
+  const next =
+    exact && lines.every((line) => exact.test(line))
+      ? lines.map((line) => line.replace(exact, ''))
+      : lines.map((line, i) => prefix(i) + (strip ? line.replace(strip, '') : line));
+  const region = next.join('\n');
+  const firstDelta = next[0].length - lines[0].length;
+  const totalDelta = region.length - (to - lineStart);
+  return {
+    doc: doc.slice(0, lineStart) + region + doc.slice(to),
+    from: Math.max(lineStart, from + firstDelta),
+    to: to + totalDelta,
+  };
+}
+
+/** Fence the selected lines in triple backticks on their own lines, or remove the fences when the
+ *  lines just above and below the selection already are fences. */
+function toggleCodeFence(doc: string, from: number, to: number): FormatResult {
+  const lineStart = doc.lastIndexOf('\n', from - 1) + 1;
+  const lineEndRaw = doc.indexOf('\n', to);
+  const lineEnd = lineEndRaw === -1 ? doc.length : lineEndRaw;
+  const prevStart = lineStart > 0 ? doc.lastIndexOf('\n', lineStart - 2) + 1 : -1;
+  const prevLine = prevStart >= 0 ? doc.slice(prevStart, lineStart - 1) : null;
+  const nextEndRaw = lineEnd < doc.length ? doc.indexOf('\n', lineEnd + 1) : -1;
+  const nextEnd = nextEndRaw === -1 ? doc.length : nextEndRaw;
+  const nextLine = lineEnd < doc.length ? doc.slice(lineEnd + 1, nextEnd) : null;
+  if (prevLine === '```' && nextLine === '```') {
+    const removedBefore = lineStart - prevStart; // the opening fence line and its newline
+    const next = doc.slice(0, prevStart) + doc.slice(lineStart, lineEnd) + doc.slice(nextEnd);
+    return { doc: next, from: from - removedBefore, to: to - removedBefore };
+  }
+  const open = '```\n';
+  const next = doc.slice(0, lineStart) + open + doc.slice(lineStart, lineEnd) + '\n```' + doc.slice(lineEnd);
+  return { doc: next, from: from + open.length, to: to + open.length };
+}
 
 export function applyMarkdownFormat(doc: string, from: number, to: number, kind: FormatKind): FormatResult {
-  if (kind === 'bold' || kind === 'italic' || kind === 'code') {
-    const marker = WRAP[kind];
-    const next = doc.slice(0, from) + marker + doc.slice(from, to) + marker + doc.slice(to);
-    return { doc: next, from: from + marker.length, to: to + marker.length };
+  if (kind === 'bold' || kind === 'italic' || kind === 'code' || kind === 'strike') {
+    return toggleWrap(doc, from, to, WRAP[kind]);
   }
 
   if (kind === 'link') {
@@ -37,12 +129,25 @@ export function applyMarkdownFormat(doc: string, from: number, to: number, kind:
     return { doc: doc.slice(0, from) + inserted + doc.slice(to), from: urlStart, to: urlStart + placeholder.length };
   }
 
-  const prefix = LINE_PREFIX[kind];
-  const lineStart = doc.lastIndexOf('\n', from - 1) + 1; // 0 when the selection is on the first line
-  const region = doc.slice(lineStart, to);
-  const prefixed = region.replace(/^/gm, prefix);
-  const added = prefixed.length - region.length;
-  return { doc: doc.slice(0, lineStart) + prefixed + doc.slice(to), from: from + prefix.length, to: to + added };
+  if (kind === 'codeblock') return toggleCodeFence(doc, from, to);
+
+  if (kind === 'hr') {
+    const inserted = '\n\n---\n\n';
+    const at = from + inserted.length;
+    return { doc: doc.slice(0, from) + inserted + doc.slice(to), from: at, to: at };
+  }
+
+  if (kind === 'table') {
+    const inserted = `\n\n${TABLE_GRID}\n\n`;
+    const cellStart = from + inserted.indexOf('Column 1');
+    return {
+      doc: doc.slice(0, from) + inserted + doc.slice(to),
+      from: cellStart,
+      to: cellStart + 'Column 1'.length,
+    };
+  }
+
+  return applyLinePrefix(doc, from, to, kind);
 }
 
 /**

package/src/lib/content/pending.ts

@@ -0,0 +1,24 @@
+// The pending-branch codec (publish-workflow spec): a pending entry lives on
+// `cairn/<conceptKey>/<id>`, and the ref's existence is the only pending state. Concept ids and
+// entry ids are slug-safe, so the name needs no escaping; the parser is the codec's inverse.
+
+/** Every pending branch sits under this prefix; one matching-refs call lists them all. */
+export const PENDING_PREFIX = 'cairn/';
+
+/** The branch name holding an entry's pending edits. */
+export function pendingBranch(concept: string, id: string): string {
+  return `${PENDING_PREFIX}${concept}/${id}`;
+}
+
+/** Parse a branch name or fully qualified ref back to its entry, or null for any other ref. */
+export function parsePendingBranch(ref: string): { concept: string; id: string } | null {
+  const name = ref.startsWith('refs/heads/') ? ref.slice('refs/heads/'.length) : ref;
+  if (!name.startsWith(PENDING_PREFIX)) return null;
+  const rest = name.slice(PENDING_PREFIX.length);
+  const slash = rest.indexOf('/');
+  if (slash <= 0) return null;
+  const concept = rest.slice(0, slash);
+  const id = rest.slice(slash + 1);
+  if (!id || id.includes('/')) return null;
+  return { concept, id };
+}

package/src/lib/diagnostics/conditions.ts

@@ -18,19 +18,27 @@ export interface CairnCondition {
 	why: string;
 	/** The fix, often a command. */
 	remediation: string;
-	/** Anchor into the readiness checklist doc, filled in when that doc lands (Pass 3). */
+	/**
+	 * The condition's section in the readiness checklist, written as
+	 * 'cloudflare-readiness.md#<heading-slug>' so a doc can link it relative to docs/guides/.
+	 * The check:readiness gate parses the part after '#' and asserts the heading exists; two
+	 * conditions may share a section. Every entry carries one unless the gate's allowlist
+	 * excuses it.
+	 */
 	docsAnchor?: string;
 	/** The log vocabulary event this condition correlates with, if any. */
 	logEvent?: CairnLogEvent;
 }
 
-const REGISTRY: Record<string, CairnCondition> = {
+// Exported for the freeze test only; resolve entries through condition() everywhere else.
+export const REGISTRY: Record<string, CairnCondition> = {
 	'edge.https-not-forced': {
 		id: 'edge.https-not-forced',
 		severity: 'blocker',
 		title: 'Always Use HTTPS is off',
 		why: 'The JS-free admin sign-in posts a form, and the framework CSRF guard rejects a form POST whose origin scheme does not match, so an admin reached over http hits an opaque 403.',
 		remediation: 'Turn on Always Use HTTPS for the zone under SSL/TLS, Edge Certificates, and keep HSTS on.',
+		docsAnchor: 'cloudflare-readiness.md#force-https-at-the-edge',
 		logEvent: 'guard.rejected',
 	},
 	'auth.csrf-token-invalid': {
@@ -39,6 +47,7 @@ const REGISTRY: Record<string, CairnCondition> = {
 		title: 'Admin CSRF token check failed',
 		why: 'An admin form POST carried no valid __Host-cairn_csrf double-submit token, usually a stale tab or blocked cookies.',
 		remediation: 'Open the sign-in page fresh, allow cookies for the site, and request a new link.',
+		docsAnchor: 'cloudflare-readiness.md#admin-csrf-token-rejected',
 		logEvent: 'guard.rejected',
 	},
 	'auth.csrf-origin-mismatch': {
@@ -47,6 +56,7 @@ const REGISTRY: Record<string, CairnCondition> = {
 		title: 'Non-admin form Origin rejected',
 		why: "A non-admin unsafe form POST carried an Origin that did not match the site, so cairn's restored framework Origin check rejected it.",
 		remediation: 'Post the form from the same origin, or check a proxy that strips or rewrites the Origin header.',
+		docsAnchor: 'cloudflare-readiness.md#non-admin-origin-rejected',
 		logEvent: 'guard.rejected',
 	},
 	'email.sender-not-onboarded': {
@@ -55,6 +65,7 @@ const REGISTRY: Record<string, CairnCondition> = {
 		title: 'Email sending domain is not onboarded',
 		why: 'The from-address domain has no enabled Cloudflare sending subdomain, so env.EMAIL.send has no aligned sender and the magic-link send throws E_SENDER_NOT_VERIFIED. No editor can sign in.',
 		remediation: 'Onboard the sending domain with `wrangler email sending enable <domain>`, then re-deploy. The domain must match branding.from.',
+		docsAnchor: 'cloudflare-readiness.md#onboard-the-sending-domain',
 		logEvent: 'auth.link.send_failed',
 	},
 	'email.send-failed': {
@@ -63,10 +74,72 @@ const REGISTRY: Record<string, CairnCondition> = {
 		title: 'Magic-link email send failed',
 		why: 'The magic-link send threw for a reason other than a missing sender onboarding (a delivery error, a binding misconfiguration, or a custom sender failure), so the editor never received a link.',
 		remediation: 'Read the auth.link.send_failed log record (the code and error fields) in Workers Logs, and check the EMAIL binding and the sender configuration.',
+		docsAnchor: 'cloudflare-readiness.md#onboard-the-sending-domain',
 		logEvent: 'auth.link.send_failed',
 	},
+	'config.bindings-missing': {
+		id: 'config.bindings-missing',
+		severity: 'blocker',
+		title: 'Wrangler bindings are missing',
+		why: 'The wrangler config declares no send_email binding named EMAIL or no D1 binding named AUTH_DB, so the magic-link send or the session store has nothing to call and no editor can sign in.',
+		remediation: 'Declare the send_email binding as EMAIL and the d1_databases binding as AUTH_DB in wrangler.jsonc (or wrangler.toml), then re-deploy.',
+		docsAnchor: 'cloudflare-readiness.md#deploy-the-worker-with-its-bindings',
+	},
+	'config.observability-off': {
+		id: 'config.observability-off',
+		severity: 'warning',
+		title: 'Workers Logs has no sink',
+		why: 'observability.enabled is not true in the wrangler config, so the structured log records go nowhere and a runtime failure leaves nothing to read.',
+		remediation: 'Set observability.enabled to true in wrangler.jsonc, then re-deploy.',
+		docsAnchor: 'cloudflare-readiness.md#turn-on-observability',
+	},
+	'config.csrf-disable-missing': {
+		id: 'config.csrf-disable-missing',
+		severity: 'warning',
+		title: 'Framework CSRF check is not handed off',
+		why: "The CSRF authority is not handed to cairn cleanly. Either svelte.config.js does not carry csrf: { checkOrigin: false }, so SvelteKit's own Origin check runs ahead of cairn's guard and rejects an admin form POST that arrives without an Origin header, or the disable is present with no cairn guard wired in src/hooks.server.ts, which leaves the site with no CSRF protection at all.",
+		remediation: "Set csrf: { checkOrigin: false } in svelte.config.js and wire createAuthGuard into src/hooks.server.ts; cairn's guard owns the Origin and double-submit token checks.",
+		docsAnchor: 'cloudflare-readiness.md#hand-cairn-the-csrf-authority',
+	},
+	'config.site-config-invalid': {
+		id: 'config.site-config-invalid',
+		severity: 'blocker',
+		title: 'Site config does not validate',
+		why: 'site.config.yaml fails to parse or fails the URL-policy validation, so the build and the admin cannot resolve the content concepts.',
+		remediation: 'Correct site.config.yaml; the parse or validation error names the failing field or URL-policy rule.',
+		docsAnchor: 'cloudflare-readiness.md#validate-the-site-config',
+	},
+	'edge.hsts-off': {
+		id: 'edge.hsts-off',
+		severity: 'warning',
+		title: 'HSTS is off',
+		why: 'The zone sends no Strict-Transport-Security header with a meaningful max-age, so browsers do not pin https and a later http visit can still hit the admin guard rejection.',
+		remediation: 'Turn on HSTS for the zone under SSL/TLS, Edge Certificates, with a max-age of at least six months.',
+		docsAnchor: 'cloudflare-readiness.md#turn-on-hsts',
+	},
+	'auth.store-unreachable': {
+		id: 'auth.store-unreachable',
+		severity: 'blocker',
+		title: 'Auth store is unreachable',
+		why: 'The AUTH_DB D1 database is missing, lacks the auth schema, or holds no owner row, so no magic-link token can be minted and nobody can sign in.',
+		remediation: 'Create the database, apply the auth schema with `wrangler d1 execute <db> --remote --file ./migrations/0000_auth.sql`, seed the owner row, and check the AUTH_DB binding id in wrangler.jsonc.',
+		docsAnchor: 'cloudflare-readiness.md#provision-the-auth-store',
+	},
+	'github.app-unreachable': {
+		id: 'github.app-unreachable',
+		severity: 'blocker',
+		title: 'GitHub App is unreachable',
+		why: 'The App key fails to parse, the App fails to authenticate, the installation token fails to mint, or the repository refuses a read, so saves and publishes cannot commit.',
+		remediation: 'Check GITHUB_APP_ID, GITHUB_APP_INSTALLATION_ID, and GITHUB_APP_PRIVATE_KEY_B64 against the App settings, and confirm the App is installed on the repository.',
+		docsAnchor: 'cloudflare-readiness.md#install-the-github-app',
+		logEvent: 'github.unreachable',
+	},
 };
 
+// The registry is shared identity, never working state; freeze every entry and the map itself.
+for (const entry of Object.values(REGISTRY)) Object.freeze(entry);
+Object.freeze(REGISTRY);
+
 /** Resolve a condition by id. Throws on an unknown id, since ids are compile-time constants. */
 export function condition(id: string): CairnCondition {
 	const found = REGISTRY[id];

package/src/lib/doctor/bin.ts

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+// cairn-doctor: the environment preflight. A thin shell over index.ts (where the unit tests
+// reach the logic): parse the flags, assemble the context with the real fetch and filesystem,
+// run the default registry plus the opt-in live send, print the report. Bad flags go to
+// stderr with exit 2; a failed check exits 1; a clean or all-skip run exits 0. The codes go
+// through process.exitCode, never process.exit, so a piped stdout flushes the whole report
+// before the process ends.
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { liveSendCheck } from './check-send.js';
+import { contextFromEnv, defaultChecks, formatReport, parseArgs, runDoctor } from './index.js';
+
+async function main(): Promise<void> {
+	let args: ReturnType<typeof parseArgs>;
+	try {
+		args = parseArgs(process.argv.slice(2));
+	} catch (err) {
+		console.error(err instanceof Error ? err.message : String(err));
+		process.exitCode = 2;
+		return;
+	}
+
+	const cwd = process.cwd();
+	const ctx = {
+		...contextFromEnv(process.env, args, cwd),
+		fetch: globalThis.fetch,
+		readFile: async (relPath: string): Promise<string | null> => {
+			try {
+				return await readFile(resolve(cwd, relPath), 'utf8');
+			} catch (err) {
+				if ((err as NodeJS.ErrnoException).code === 'ENOENT') return null;
+				throw err;
+			}
+		},
+	};
+
+	const checks = defaultChecks();
+	if (args.sendTest) checks.push(liveSendCheck(args.sendTest));
+
+	const { results, failed } = await runDoctor(checks, ctx);
+	console.log(formatReport(results));
+	process.exitCode = failed > 0 ? 1 : 0;
+}
+
+await main();