@glw907/cairn-cms 0.40.0 → 0.41.0

package/dist/sveltekit/content-routes.js

@@ -72,8 +72,9 @@ export function createContentRoutes(runtime, deps = {}) {
                 return entry ? [{ concept: entry.concept.id, id: entry.id }] : [];
             });
         }
-        catch {
+        catch (err) {
             pendingEntries = null;
+            log.warn('github.unreachable', { scope: 'layout', error: String(err) });
         }
         return {
             siteName: runtime.siteName,
@@ -216,18 +217,22 @@ export function createContentRoutes(runtime, deps = {}) {
         const datePrefix = concept.routing.dated ? concept.datePrefix : null;
         const path = `${concept.dir}/${filenameFromId(id)}`;
         // A pending entry reads branch-first: the editor shows the unpublished edits. The manifest
-        // (link targets and the inbound-link guard) always reads main, the authoritative copy, and a
-        // pending entry adds a main read of its own path to derive its published state.
+        // (link targets and the inbound-link guard) always reads main, the authoritative copy.
+        // Stage 1 runs the branch probe, the main-path read, and the manifest read concurrently,
+        // so the probe does not serialize ahead of the other two; stage 2 adds the branch read
+        // only when the probe found a branch, with the stage-1 main read serving as the published
+        // signal either way.
         const branch = pendingBranch(concept.id, id);
-        const pending = (await branchHeadSha(runtime.backend, branch, token)) !== null;
-        const [raw, manifestRaw, mainRaw] = await Promise.all([
-            readRaw(pending ? { ...runtime.backend, branch } : runtime.backend, path, token),
+        const [headSha, mainRaw, manifestRaw] = await Promise.all([
+            branchHeadSha(runtime.backend, branch, token),
+            readRaw(runtime.backend, path, token),
             readRaw(runtime.backend, runtime.manifestPath, token),
-            pending ? readRaw(runtime.backend, path, token) : Promise.resolve(null),
         ]);
+        const pending = headSha !== null;
+        const raw = pending ? await readRaw({ ...runtime.backend, branch }, path, token) : mainRaw;
         if (raw === null && !isNew)
             throw error(404, 'Entry not found');
-        const published = pending ? mainRaw !== null : raw !== null;
+        const published = mainRaw !== null;
         const parsed = raw === null ? { frontmatter: {}, body: '' } : parseMarkdown(raw);
         const title = typeof parsed.frontmatter.title === 'string' && parsed.frontmatter.title.trim() ? parsed.frontmatter.title : id;
         let linkTargets = [];
@@ -450,11 +455,14 @@ export function createContentRoutes(runtime, deps = {}) {
             next = upsertEntry(next, manifestEntryFromFile(entry.concept, { path: entry.path, raw: entry.raw }));
             published.push({ concept: entry.concept.id, id: entry.id, branch: entry.branch, sha: entry.sha });
         }
-        if (published.length === 0)
-            throw redirect(303, listPage);
+        if (published.length === 0) {
+            const message = 'Nothing to publish. Every entry is already live.';
+            throw redirect(303, `${listPage}?error=${encodeURIComponent(message)}`);
+        }
         changes.push({ path: runtime.manifestPath, content: serializeManifest(next) });
+        const noun = published.length === 1 ? 'entry' : 'entries';
         try {
-            await commitFiles(runtime.backend, changes, { message: `Publish ${published.length} entries`, author: { name: editor.displayName, email: editor.email } }, token);
+            await commitFiles(runtime.backend, changes, { message: `Publish ${published.length} ${noun}`, author: { name: editor.displayName, email: editor.email } }, token);
             for (const entry of published) {
                 log.info('entry.published', { concept: entry.concept, id: entry.id, editor: editor.email, batch: true });
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glw907/cairn-cms",
-  "version": "0.40.0",
+  "version": "0.41.0",
   "description": "Embedded, magic-link, GitHub-committing CMS for SvelteKit/Cloudflare sites.",
   "type": "module",
   "sideEffects": [
@@ -26,9 +26,10 @@
     "markdown"
   ],
   "scripts": {
-    "package": "svelte-package && node scripts/build-admin-css.mjs && chmod +x dist/vite/bin.js",
+    "package": "svelte-package && node scripts/build-admin-css.mjs && chmod +x dist/vite/bin.js dist/doctor/bin.js",
     "check:package": "npm run package && publint --strict && attw --pack . --ignore-rules no-resolution cjs-resolves-to-esm internal-resolution-error",
     "check:reference": "npm run package && node scripts/reference-coverage.mjs",
+    "check:readiness": "npm run package && node scripts/check-readiness.mjs",
     "check:docs": "node scripts/docs-links.mjs",
     "check:prose": "node scripts/check-admin-prose.mjs",
     "prepare": "npm run package",
@@ -82,7 +83,8 @@
     "./package.json": "./package.json"
   },
   "bin": {
-    "cairn-manifest": "./dist/vite/bin.js"
+    "cairn-manifest": "./dist/vite/bin.js",
+    "cairn-doctor": "./dist/doctor/bin.js"
   },
   "files": [
     "dist",
@@ -90,7 +92,7 @@
     "CHANGELOG.md"
   ],
   "peerDependencies": {
-    "@sveltejs/kit": "^2",
+    "@sveltejs/kit": "^2.12",
     "svelte": "^5.0.0"
   },
   "dependencies": {

package/src/lib/components/ConceptList.svelte

@@ -107,6 +107,14 @@ content sizes. The header New button opens a dialog holding the create form.
   // flex layout and a hover affordance on top of this.
   const headerLabel = 'text-[0.6875rem] font-semibold uppercase tracking-[0.08em] text-[var(--color-muted)]';
   const sortButton = `inline-flex items-center gap-1 ${headerLabel} hover:text-base-content`;
+
+  // The publish-all flash. A racing second admin can publish first, leaving this redirect
+  // counting zero; say nothing then.
+  const publishedAllMessage = $derived(
+    data.publishedAll !== null && data.publishedAll > 0
+      ? `Published ${data.publishedAll} ${data.publishedAll === 1 ? 'entry' : 'entries'}.`
+      : '',
+  );
 </script>
 
 <header class="mb-6 flex flex-col gap-3 sm:flex-row sm:flex-wrap sm:items-center sm:justify-between">
@@ -122,11 +130,12 @@ content sizes. The header New button opens a dialog holding the create form.
   </div>
 </header>
 
-<!-- A racing second admin can publish first, leaving this redirect counting zero; say nothing then. -->
-{#if data.publishedAll !== null && data.publishedAll > 0}
-  <div role="status" class="alert alert-success mb-4 text-sm">
-    Published {data.publishedAll} {data.publishedAll === 1 ? 'entry' : 'entries'}.
-  </div>
+<!-- One persistent live region announces the publish-all flash (the EditPage pattern): a
+     {#if}-gated role element inserted fresh is announced inconsistently, so the visible alert
+     below keeps its styling without a role and the message is announced once. -->
+<div class="sr-only" aria-live="polite">{publishedAllMessage}</div>
+{#if publishedAllMessage}
+  <div class="alert alert-success mb-4 text-sm">{publishedAllMessage}</div>
 {/if}
 {#if data.formError}
   <div role="alert" class="alert alert-error mb-4 text-sm">{data.formError}</div>

package/src/lib/components/EditPage.svelte

@@ -14,6 +14,7 @@ transient flashes, and the editor card's footer holds the word count and the Mar
 <script lang="ts">
   import { untrack } from 'svelte';
   import { beforeNavigate } from '$app/navigation';
+  import { page } from '$app/state';
   import CsrfField from './CsrfField.svelte';
   import MarkdownEditor from './MarkdownEditor.svelte';
   import EditorToolbar from './EditorToolbar.svelte';
@@ -25,7 +26,7 @@ transient flashes, and the editor card's footer holds the word count and the Mar
   import MarkdownHelpDialog from './MarkdownHelpDialog.svelte';
   import { cairnLinkCompletionSource } from './link-completion.js';
   import { unwrapCairnLink, type FormatKind } from './markdown-format.js';
-  import { directiveLineKind } from './markdown-directives.js';
+  import { directiveLineKind, findInlineDirectives } from './markdown-directives.js';
   import type { ComponentRegistry } from '../render/registry.js';
   import type { IconSet } from '../render/glyph.js';
   import type { EditData } from '../sveltekit/content-routes.js';
@@ -101,6 +102,14 @@ transient flashes, and the editor card's footer holds the word count and the Mar
   // navigation passes through because busy flips before it starts, and a non-edit POST's because
   // leaving does.
   beforeNavigate((navigation) => {
+    // A full-page unload (refresh, tab close, external link): per SvelteKit semantics, cancel()
+    // on a leave navigation is what asks the browser for its native dialog, so no confirm()
+    // here or two prompts would stack. The beforeunload listener below is deliberate
+    // belt-and-braces, not the dialog's source.
+    if (navigation.willUnload) {
+      if (dirty && !busy && !leaving) navigation.cancel();
+      return;
+    }
     if (dirty && !busy && !leaving && !confirm('You have unsaved changes. Leave anyway?'))
       navigation.cancel();
   });
@@ -240,14 +249,12 @@ transient flashes, and the editor card's footer holds the word count and the Mar
     });
   });
 
-  // After a save that links to a draft target, the redirect carries ?drafts=<tokens>. Re-read on
-  // an entry change too, since a client-side navigation swaps the search string under this effect.
-  let draftWarning = $state('');
-  $effect(() => {
-    void entryKey;
-    const search = typeof location === 'undefined' ? '' : location.search;
-    const drafts = new URLSearchParams(search).get('drafts');
-    draftWarning = drafts ? drafts.split(',').filter(Boolean).join(', ') : '';
+  // After a save that links to a draft target, the redirect carries ?drafts=<tokens>. page.url
+  // is reactive kit state, so a client-side navigation that swaps the search string re-derives
+  // this, and the read is SSR-safe.
+  const draftWarning = $derived.by(() => {
+    const drafts = page.url.searchParams.get('drafts');
+    return drafts ? drafts.split(',').filter(Boolean).join(', ') : '';
   });
 
   // The one transient feedback strip under the sticky header. The redirect flags are mutually
@@ -284,12 +291,29 @@ transient flashes, and the editor card's footer holds the word count and the Mar
     return '';
   });
 
+  // One line of body text reduced to its prose: inline directives drop wholesale, then the
+  // markdown marker characters become spaces. Spacing rather than deleting keeps "[text](url)"
+  // as two words instead of mashing the link text into its destination, so a link counts its
+  // text plus its URL and the count never undercounts prose.
+  function proseOnly(line: string): string {
+    let out = '';
+    let cursor = 0;
+    for (const { from, to } of findInlineDirectives(line)) {
+      out += line.slice(cursor, from);
+      cursor = to;
+    }
+    out += line.slice(cursor);
+    return out.replace(/[*_~`[\]()#]/g, ' ');
+  }
+
   // The editor footer's word count, over the local body so it tracks every keystroke. Directive
-  // machinery lines and table rows are dropped first, so the count reads as the author's prose.
+  // machinery lines and table rows are dropped first and the inline syntax stripped, so the
+  // count reads as the author's prose.
   const countedBody = $derived(
     body
       .split('\n')
       .filter((line) => directiveLineKind(line) === null && !/^\s*\|/.test(line))
+      .map(proseOnly)
       .join('\n'),
   );
   const wordCount = $derived(countedBody.trim() ? countedBody.trim().split(/\s+/).length : 0);

package/src/lib/components/EditorToolbar.svelte

@@ -113,6 +113,10 @@ are stroke SVG icons in the admin's house style (24x24 viewBox, `currentColor`,
     const items = rovingControls();
     if (items.length === 0) return;
     const stop = Math.min(roving, items.length - 1);
+    // Write the clamp back so the stored stop never drifts from the displayed one across a
+    // Preview round trip. The effect reads roving, so the guarded write re-runs it once and
+    // converges (the second pass computes the same stop and writes nothing).
+    if (stop !== roving) roving = stop;
     for (const [i, el] of items.entries()) el.setAttribute('tabindex', i === stop ? '0' : '-1');
   });
 

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/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();

package/src/lib/doctor/check-send.ts

@@ -0,0 +1,43 @@
+// The doctor's opt-in live send (--send-test): one real message through the Email Sending
+// REST API, since the Worker EMAIL binding is unreachable from a CLI. A factory rather than
+// a check constant, so the check exists only when the bin receives an address; no default
+// registry carries it.
+//
+// Endpoint and payload verified against the Cloudflare API reference, 2026-06-11:
+//   POST /accounts/{account_id}/email/sending/send with { from, to, subject, text },
+//   where from and to take a plain address string.
+//   https://developers.cloudflare.com/api/resources/email_sending/
+import { fail, pass } from './types.js';
+import type { CheckResult, DoctorCheck, DoctorContext } from './types.js';
+import { cfPost, NO_ACCOUNT, NO_FROM } from './cloudflare-api.js';
+
+// Enough of an error body to act on without flooding the one-line report.
+const EXCERPT_MAX = 200;
+
+/** Build the live-send check for one recipient address. */
+export function liveSendCheck(to: string): DoctorCheck {
+	return {
+		id: 'email.live-send',
+		conditionId: 'email.send-failed',
+		title: 'Live test send',
+		async run(ctx: DoctorContext): Promise<CheckResult> {
+			if (!ctx.cfToken || !ctx.cfAccountId) return NO_ACCOUNT;
+			if (!ctx.from) return NO_FROM;
+			try {
+				const res = await cfPost(ctx, `/accounts/${ctx.cfAccountId}/email/sending/send`, {
+					from: ctx.from,
+					to,
+					subject: 'cairn doctor test send',
+					text: 'This is a cairn doctor test send. Receiving it proves the sending path.',
+				});
+				if (!res.ok) {
+					const excerpt = (await res.text()).slice(0, EXCERPT_MAX);
+					return fail(`send returned ${res.status}: ${excerpt}`);
+				}
+				return pass(`sent to ${to}; check the inbox`);
+			} catch (err) {
+				return fail(String(err));
+			}
+		},
+	};
+}