@glw907/cairn-cms 0.40.0 → 0.41.0

package/CHANGELOG.md

@@ -2,6 +2,40 @@
 
 All notable changes to this project are recorded here, most recent first.
 
+## 0.41.0
+
+`cairn-doctor` ships as a second bin: a setup preflight that runs nine checks over the local config
+files (the wrangler bindings, observability, the CSRF handoff, the site config), the Cloudflare
+account (the onboarded sending domain, Always Use HTTPS, HSTS, the D1 auth store with its schema
+and an owner row), and the GitHub App's full reachability chain. Every check reports into one
+plain-text report, a failure prints its condition's why and remediation from the diagnostics
+registry, and the exit code is 1 on any failure, so the command slots into a deploy script as a
+gate. A missing credential makes the affected checks skip rather than fail, and
+`--send-test <address>` opts into one real email through the Email Sending API. The new
+[Cloudflare readiness guide](docs/guides/cloudflare-readiness.md) walks the same conditions
+manually, a `check:readiness` gate pins that guide to the condition registry, and
+[the doctor reference](docs/reference/doctor.md) covers the flags, the checks, and the CI wiring.
+
+The admin layout's GitHub degrade gains a signal. When the pending-entries read fails, the layout
+logs a warn-level `github.unreachable` record and the topbar's Publish site button hides instead
+of showing a count it cannot know.
+
+Consumers may: run `npx cairn-doctor --from <address> --repo <owner/name>` as a pre-launch gate,
+work through the readiness guide when standing up a fresh account, and filter Workers Logs on
+`github.unreachable` when the publish button goes missing.
+
+A debt batch rides along. The editor's link autocomplete no longer
+pulls CodeMirror into the server bundle, the edit page's load reads its GitHub probes in parallel,
+concurrent cold-start token mints coalesce into one, publish-all pluralizes its commit message and
+an empty publish-all explains itself instead of redirecting silently, the unsaved-changes warning
+tracks client-side navigation and no longer double-fires on a full page unload, the toolbar's
+keyboard tab stop holds across Preview round trips, the word count ignores markdown and directive
+syntax, and the list's publish flash announces reliably to screen readers.
+
+Consumers must: be on `@sveltejs/kit` 2.12 or later before taking this release. The edit page now
+reads `$app/state`, which shipped in kit 2.12.0, and the peer range says so (`^2.12`); a site on
+an older kit must upgrade kit first.
+
 ## 0.40.0
 
 The edit page is redesigned around the manuscript. A sticky translucent header carries the

package/README.md

@@ -65,7 +65,7 @@ formal contribution process yet, so this is not an open call for pull requests.
 npm install @glw907/cairn-cms
 ```
 
-Peer dependencies: `svelte@^5` and `@sveltejs/kit@^2`. A consumer site implements a
+Peer dependencies: `svelte@^5` and `@sveltejs/kit@^2.12`. A consumer site implements a
 `CairnAdapter` and mounts thin `/admin` route shims around the package subpaths:
 
 - `@glw907/cairn-cms`: the core engine and adapter contract.

package/dist/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/dist/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/dist/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/dist/components/link-completion.js

@@ -1,5 +1,8 @@
-import { syntaxTree } from '@codemirror/language';
 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 = null;
 /** The known concepts in display order; an unlisted concept sorts after these under its own name. */
 const CONCEPT_SECTIONS = {
     pages: { name: 'Pages', rank: 0 },
@@ -30,7 +33,7 @@ export function linkCompletions(targets, query) {
  *  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) {
-    return (context) => {
+    return async (context) => {
         const line = context.state.doc.lineAt(context.pos);
         const before = context.state.sliceDoc(line.from, context.pos);
         const trigger = matchCairnTrigger(before);
@@ -38,7 +41,11 @@ export function cairnLinkCompletionSource(targets) {
             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 = node; n; n = n.parent) {
             if (/Code/.test(n.name))
                 return null;

package/dist/diagnostics/conditions.d.ts

@@ -10,11 +10,18 @@ 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;
 }
+export declare const REGISTRY: Record<string, CairnCondition>;
 /** Resolve a condition by id. Throws on an unknown id, since ids are compile-time constants. */
 export declare function condition(id: string): CairnCondition;
 /** Every registered condition, for the checklist generator and coverage tests. */

package/dist/diagnostics/conditions.js

@@ -1,10 +1,12 @@
-const REGISTRY = {
+// Exported for the freeze test only; resolve entries through condition() everywhere else.
+export const REGISTRY = {
     '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': {
@@ -13,6 +15,7 @@ const REGISTRY = {
         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': {
@@ -21,6 +24,7 @@ const REGISTRY = {
         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': {
@@ -29,6 +33,7 @@ const REGISTRY = {
         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': {
@@ -37,9 +42,71 @@ const REGISTRY = {
         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) {
     const found = REGISTRY[id];

package/dist/doctor/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/doctor/bin.js

@@ -0,0 +1,44 @@
+#!/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() {
+    let args;
+    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) => {
+            try {
+                return await readFile(resolve(cwd, relPath), 'utf8');
+            }
+            catch (err) {
+                if (err.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/dist/doctor/check-send.d.ts

@@ -0,0 +1,3 @@
+import type { DoctorCheck } from './types.js';
+/** Build the live-send check for one recipient address. */
+export declare function liveSendCheck(to: string): DoctorCheck;

package/dist/doctor/check-send.js

@@ -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 { 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) {
+    return {
+        id: 'email.live-send',
+        conditionId: 'email.send-failed',
+        title: 'Live test send',
+        async run(ctx) {
+            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));
+            }
+        },
+    };
+}

package/dist/doctor/checks-cloudflare.d.ts

@@ -0,0 +1,5 @@
+import type { DoctorCheck } from './types.js';
+export declare const emailSenderOnboarded: DoctorCheck;
+export declare const edgeHttpsForced: DoctorCheck;
+export declare const edgeHsts: DoctorCheck;
+export declare const authStore: DoctorCheck;

package/dist/doctor/checks-cloudflare.js

@@ -0,0 +1,200 @@
+// The doctor's Cloudflare API checks: the onboarded sending domain, the zone HTTPS posture,
+// and the D1 auth store, over the shared cloudflare-api plumbing.
+//
+// Endpoints verified against the Cloudflare API reference, 2026-06-11:
+// - Email Sending subdomains (zone-scoped; this is the namespace `wrangler email sending
+//   enable` feeds, and the listing carries `{ result: [{ name, enabled, tag }] }`):
+//   GET /zones/{zone_id}/email/sending/subdomains
+//   https://developers.cloudflare.com/api/resources/email_sending/
+// - Zone lookup, `{ result: [{ id }] }`: GET /zones?name=<domain>
+//   https://developers.cloudflare.com/api/resources/zones/
+// - Zone settings, `{ result: { value } }` where always_use_https carries 'on' | 'off' and
+//   security_header nests `value.strict_transport_security.{enabled,max_age}`:
+//   GET /zones/{zone_id}/settings/{setting_id}
+//   https://developers.cloudflare.com/api/resources/zones/subresources/settings/
+// - D1 query, `{ sql }` in, `{ result: [{ results: [...] }] }` out:
+//   POST /accounts/{account_id}/d1/database/{database_id}/query
+//   https://developers.cloudflare.com/api/resources/d1/subresources/database/
+import { fail, pass, skip } from './types.js';
+import { cfGet, cfPost, NO_ACCOUNT, NO_FROM, NO_TOKEN } from './cloudflare-api.js';
+import { readWranglerConfig } from './wrangler-config.js';
+// 30 days. The production zones run two years; anything under a month is a trivial pin.
+const MIN_HSTS_MAX_AGE = 2592000;
+function fromDomain(from) {
+    return from.slice(from.indexOf('@') + 1);
+}
+// The registrable domain is taken as the last two labels of the from-domain. A deliberate
+// simplification: correct for the single-label public suffixes cairn targets (.ski, .life),
+// wrong for multi-part suffixes like .co.uk, which would need a public-suffix list the
+// doctor does not carry.
+function registrableDomain(domain) {
+    return domain.split('.').slice(-2).join('.');
+}
+// A 401/403 means the token cannot make this read at all, so the product condition's
+// remediation (onboard the domain, fix the binding) would point the operator at the wrong fix.
+// The conditionId stays; the detail carries the scope truth.
+function permissionFail(status, scope) {
+    if (status !== 401 && status !== 403)
+        return null;
+    return fail(`the API token lacks permission for this read (HTTP ${status}); grant the token ${scope} access`);
+}
+async function resolveZoneId(ctx, domain) {
+    // The from-domain may be its own Cloudflare zone (mail.example.com registered directly), so
+    // the exact name is tried first and the registrable domain is the fallback.
+    const apex = registrableDomain(domain);
+    const names = domain === apex ? [domain] : [domain, apex];
+    for (const name of names) {
+        const res = await cfGet(ctx, `/zones?name=${encodeURIComponent(name)}`);
+        if (!res.ok) {
+            return { fail: fail(`zone lookup for ${name} returned ${res.status}`) };
+        }
+        const body = (await res.json());
+        const id = body.result?.[0]?.id;
+        if (typeof id === 'string')
+            return { zoneId: id };
+    }
+    return { fail: fail(`no zone named ${names.join(' or ')} is visible to this token`) };
+}
+/** Resolve the domain's zone and read one of its settings, returning `result.value`. */
+async function readZoneSetting(ctx, domain, settingId) {
+    const zone = await resolveZoneId(ctx, domain);
+    if ('fail' in zone)
+        return zone;
+    const res = await cfGet(ctx, `/zones/${zone.zoneId}/settings/${settingId}`);
+    if (!res.ok) {
+        return { fail: fail(`${settingId} read returned ${res.status}`) };
+    }
+    const body = (await res.json());
+    return { value: body.result?.value };
+}
+export const emailSenderOnboarded = {
+    id: 'email.sender-onboarded',
+    conditionId: 'email.sender-not-onboarded',
+    title: 'Email sending domain',
+    async run(ctx) {
+        if (!ctx.cfToken)
+            return NO_TOKEN;
+        if (!ctx.from)
+            return NO_FROM;
+        const domain = fromDomain(ctx.from);
+        try {
+            const zone = await resolveZoneId(ctx, domain);
+            if ('fail' in zone)
+                return zone.fail;
+            const res = await cfGet(ctx, `/zones/${zone.zoneId}/email/sending/subdomains`);
+            if (!res.ok) {
+                return (permissionFail(res.status, 'Email Sending: Read') ??
+                    fail(`sending subdomain list returned ${res.status}`));
+            }
+            const body = (await res.json());
+            const entry = body.result?.find((s) => s.name === domain);
+            if (entry?.enabled === true) {
+                return pass(`${domain} has an enabled sending subdomain`);
+            }
+            if (entry) {
+                return fail(`${domain} is onboarded but sending is disabled`);
+            }
+            return fail(`${domain} has no sending subdomain on the zone`);
+        }
+        catch (err) {
+            return fail(String(err));
+        }
+    },
+};
+export const edgeHttpsForced = {
+    id: 'edge.https-forced',
+    conditionId: 'edge.https-not-forced',
+    title: 'Always Use HTTPS',
+    async run(ctx) {
+        if (!ctx.cfToken)
+            return NO_TOKEN;
+        if (!ctx.from)
+            return NO_FROM;
+        try {
+            const setting = await readZoneSetting(ctx, fromDomain(ctx.from), 'always_use_https');
+            if ('fail' in setting)
+                return setting.fail;
+            if (setting.value === 'on') {
+                return pass('Always Use HTTPS is on');
+            }
+            return fail(`always_use_https is ${setting.value ?? 'unreadable'}`);
+        }
+        catch (err) {
+            return fail(String(err));
+        }
+    },
+};
+export const edgeHsts = {
+    id: 'edge.hsts',
+    conditionId: 'edge.hsts-off',
+    title: 'HSTS',
+    async run(ctx) {
+        if (!ctx.cfToken)
+            return NO_TOKEN;
+        if (!ctx.from)
+            return NO_FROM;
+        try {
+            const setting = await readZoneSetting(ctx, fromDomain(ctx.from), 'security_header');
+            if ('fail' in setting)
+                return setting.fail;
+            const sts = setting.value?.strict_transport_security;
+            if (sts?.enabled !== true) {
+                return fail('HSTS is disabled on the zone');
+            }
+            const maxAge = sts.max_age ?? 0;
+            if (maxAge < MIN_HSTS_MAX_AGE) {
+                return fail(`HSTS max-age ${maxAge} is under the ${MIN_HSTS_MAX_AGE} (30 day) floor`);
+            }
+            return pass(`HSTS enabled with max-age ${maxAge}`);
+        }
+        catch (err) {
+            return fail(String(err));
+        }
+    },
+};
+const AUTH_TABLES = ['editor', 'magic_token', 'session'];
+async function d1Query(ctx, databaseId, sql) {
+    const res = await cfPost(ctx, `/accounts/${ctx.cfAccountId}/d1/database/${encodeURIComponent(databaseId)}/query`, { sql });
+    if (!res.ok) {
+        return {
+            fail: permissionFail(res.status, 'D1: Read') ??
+                fail(`AUTH_DB is unreachable: the query returned ${res.status}`),
+        };
+    }
+    const body = (await res.json());
+    return { rows: body.result?.[0]?.results ?? [] };
+}
+export const authStore = {
+    id: 'auth.store',
+    conditionId: 'auth.store-unreachable',
+    title: 'Auth store (D1)',
+    async run(ctx) {
+        if (!ctx.cfToken || !ctx.cfAccountId)
+            return NO_ACCOUNT;
+        const facts = await readWranglerConfig(ctx.readFile);
+        if (typeof facts?.authDbId !== 'string') {
+            return skip('no AUTH_DB database_id in wrangler.jsonc or wrangler.toml');
+        }
+        try {
+            const tables = await d1Query(ctx, facts.authDbId, "SELECT name FROM sqlite_master WHERE type='table'");
+            if ('fail' in tables)
+                return tables.fail;
+            const names = new Set(tables.rows.map((row) => row.name));
+            const missing = AUTH_TABLES.filter((table) => !names.has(table));
+            if (missing.length) {
+                return fail(`auth schema is missing: ${missing.join(', ')}`);
+            }
+            const owners = await d1Query(ctx, facts.authDbId, "SELECT count(*) AS n FROM editor WHERE role='owner'");
+            if ('fail' in owners)
+                return owners.fail;
+            const n = owners.rows[0]?.n;
+            if (typeof n === 'number' && n >= 1) {
+                return pass(`auth schema present with ${n} owner row(s)`);
+            }
+            return fail('the editor table holds no owner row');
+        }
+        catch (err) {
+            return fail(String(err));
+        }
+    },
+};

package/dist/doctor/checks-github.d.ts

@@ -0,0 +1,2 @@
+import type { DoctorCheck } from './types.js';
+export declare const githubApp: DoctorCheck;