@glw907/cairn-cms 0.40.0 → 0.50.0

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;

package/dist/doctor/checks-github.js

@@ -0,0 +1,57 @@
+// The doctor's GitHub App check: the full reachability chain (the key parses and signs, the
+// installation token mints, the repository answers a read), built from the engine's own
+// credential and signing path so the doctor proves the exact code the save action runs. The
+// signing chain is Web Crypto plus atob/btoa, all Node 20+ globals, so it runs in a CLI
+// unchanged. One wrinkle the tests mirror: installationToken fetches through the global
+// fetch, so only the repo read routes through ctx.fetch.
+import { appCredentials } from '../github/credentials.js';
+import { installationToken, signingSelfTest } from '../github/signing.js';
+import { fail, pass, skip } from './types.js';
+const API = 'https://api.github.com';
+export const githubApp = {
+    id: 'github.app',
+    conditionId: 'github.app-unreachable',
+    title: 'GitHub App',
+    async run(ctx) {
+        if (!ctx.github) {
+            return skip('set GITHUB_APP_ID, GITHUB_APP_INSTALLATION_ID, and GITHUB_APP_PRIVATE_KEY_B64 to run this check');
+        }
+        if (!ctx.repo) {
+            return skip('pass --repo or set GITHUB_REPO to run this check');
+        }
+        const creds = appCredentials({ appId: ctx.github.appId, installationId: ctx.github.installationId }, { GITHUB_APP_PRIVATE_KEY_B64: ctx.github.privateKeyB64 });
+        // Stage 1: the key parse and sign, through the deploy-time self-test. Its detail is a
+        // fixed classifier, so a bad key can never echo key bytes into the report.
+        const signed = await signingSelfTest(creds.appId, creds.privateKeyB64);
+        if (!signed.ok) {
+            return fail(`the App key failed to parse or sign: ${signed.detail}`);
+        }
+        // Stage 2: the token mint, through the uncached primitive. A one-shot CLI gains nothing
+        // from the Worker-lifecycle cache, and the probe should reach GitHub for real.
+        let token;
+        try {
+            token = await installationToken(creds);
+        }
+        catch (err) {
+            return fail(`App authentication failed: ${String(err)}`);
+        }
+        // Stage 3: the repo read, with the engine's standard GitHub headers.
+        try {
+            const res = await ctx.fetch(`${API}/repos/${ctx.repo}`, {
+                headers: {
+                    Accept: 'application/vnd.github+json',
+                    Authorization: `Bearer ${token}`,
+                    'User-Agent': 'cairn-cms',
+                    'X-GitHub-Api-Version': '2022-11-28',
+                },
+            });
+            if (!res.ok) {
+                return fail(`repo ${ctx.repo} returned ${res.status}`);
+            }
+            return pass(`the App reads ${ctx.repo}`);
+        }
+        catch (err) {
+            return fail(String(err));
+        }
+    },
+};

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

@@ -0,0 +1,5 @@
+import type { DoctorCheck } from './types.js';
+export declare const configBindings: DoctorCheck;
+export declare const configObservability: DoctorCheck;
+export declare const configCsrfDisable: DoctorCheck;
+export declare const configSiteConfig: DoctorCheck;

package/dist/doctor/checks-local.js

@@ -0,0 +1,112 @@
+// The doctor's local-config checks: the wrangler bindings, the observability sink, the
+// svelte.config CSRF handoff, and the site-config validation. Every read goes through the
+// injected ctx.readFile, so the tests pass fixtures and the bin passes node:fs.
+import { fail, pass, skip } from './types.js';
+import { readWranglerConfig } from './wrangler-config.js';
+import { parseSiteConfig, urlPolicyFrom } from '../nav/site-config.js';
+import { normalizeConcepts } from '../content/concepts.js';
+import { defineFields } from '../content/schema.js';
+const NO_WRANGLER = skip('no wrangler.jsonc or wrangler.toml found');
+export const configBindings = {
+    id: 'config.bindings',
+    conditionId: 'config.bindings-missing',
+    title: 'Wrangler bindings',
+    async run(ctx) {
+        const facts = await readWranglerConfig(ctx.readFile);
+        if (facts === null)
+            return NO_WRANGLER;
+        const missing = [];
+        if (!facts.hasEmailBinding)
+            missing.push('EMAIL (send_email)');
+        if (!facts.hasAuthDb)
+            missing.push('AUTH_DB (d1_databases)');
+        if (missing.length)
+            return fail(`missing ${missing.join(' and ')}`);
+        return pass('EMAIL and AUTH_DB are declared');
+    },
+};
+export const configObservability = {
+    id: 'config.observability',
+    conditionId: 'config.observability-off',
+    title: 'Workers Logs sink',
+    async run(ctx) {
+        const facts = await readWranglerConfig(ctx.readFile);
+        if (facts === null)
+            return NO_WRANGLER;
+        if (!facts.observabilityEnabled) {
+            return fail('observability.enabled is not true');
+        }
+        return pass('observability.enabled is true');
+    },
+};
+// A line whose trimmed start is a comment marker cannot disable anything, so a commented-out
+// checkOrigin: false never green-lights the handoff.
+function hasUncommentedDisable(text) {
+    return text.split('\n').some((line) => {
+        const trimmed = line.trimStart();
+        if (trimmed.startsWith('//') || trimmed.startsWith('*') || trimmed.startsWith('/*')) {
+            return false;
+        }
+        return /checkOrigin\s*:\s*false/.test(trimmed);
+    });
+}
+// The guard-wiring heuristic. The tutorial's hooks file imports createAuthGuard from
+// @glw907/cairn-cms/sveltekit and hands it the exported handle, which the first clause matches
+// directly; a site that wraps the guard in its own module still mentions cairn beside a handle.
+function wiresCairnGuard(text) {
+    if (text.includes('@glw907/cairn-cms'))
+        return true;
+    return /cairn/i.test(text) && /handle/.test(text);
+}
+export const configCsrfDisable = {
+    id: 'config.csrf-disable',
+    conditionId: 'config.csrf-disable-missing',
+    title: 'Framework CSRF handoff',
+    async run(ctx) {
+        const text = await ctx.readFile('svelte.config.js');
+        if (text === null)
+            return skip('svelte.config.js not found');
+        if (!hasUncommentedDisable(text)) {
+            return fail('no checkOrigin: false found (heuristic text read)');
+        }
+        // The disable alone proves nothing: with the framework check off and no cairn guard in
+        // the hooks, the admin form POSTs have no CSRF protection at all. The pair is the check.
+        const hooks = (await ctx.readFile('src/hooks.server.ts')) ?? (await ctx.readFile('src/hooks.server.js'));
+        if (hooks === null || !wiresCairnGuard(hooks)) {
+            return fail('checkOrigin is off but no cairn guard found in src/hooks.server.ts; the site may have no CSRF protection');
+        }
+        return pass('checkOrigin: false found and the hooks file wires the cairn guard (heuristic text read)');
+    },
+};
+// Where sites keep site.config.yaml. The adapter's configPath is TypeScript the CLI cannot
+// evaluate, so the check probes the conventional spots instead (the repo root and the two
+// src locations the production sites use).
+const SITE_CONFIG_PATHS = ['site.config.yaml', 'src/lib/site.config.yaml', 'src/site.config.yaml'];
+export const configSiteConfig = {
+    id: 'config.site-config',
+    conditionId: 'config.site-config-invalid',
+    title: 'Site config',
+    async run(ctx) {
+        let text = null;
+        for (const path of SITE_CONFIG_PATHS) {
+            text = await ctx.readFile(path);
+            if (text !== null)
+                break;
+        }
+        if (text === null)
+            return skip(`no site.config.yaml found (looked in ${SITE_CONFIG_PATHS.join(', ')})`);
+        try {
+            const policy = urlPolicyFrom(parseSiteConfig(text));
+            // Run the engine's own URL-policy validation by declaring a synthetic empty concept
+            // per policy key. Routing is concept-fixed in the engine (CONCEPT_ROUTING, never the
+            // adapter), so the dated rules apply faithfully here. What a CLI cannot check without
+            // evaluating the adapter is whether each policy key names a concept the site declares.
+            const synthetic = Object.fromEntries(Object.keys(policy).map((id) => [id, { dir: '', schema: defineFields([]) }]));
+            normalizeConcepts(synthetic, policy);
+            return pass('parsed and URL policy validated (the adapter concept set is not checkable from the CLI)');
+        }
+        catch (err) {
+            return fail(err instanceof Error ? err.message : String(err));
+        }
+    },
+};

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

@@ -0,0 +1,7 @@
+import type { CheckResult, DoctorContext } from './types.js';
+export declare const CF_API = "https://api.cloudflare.com/client/v4";
+export declare const NO_TOKEN: CheckResult;
+export declare const NO_FROM: CheckResult;
+export declare const NO_ACCOUNT: CheckResult;
+export declare function cfGet(ctx: DoctorContext, path: string): Promise<Response>;
+export declare function cfPost(ctx: DoctorContext, path: string, body: unknown): Promise<Response>;

package/dist/doctor/cloudflare-api.js

@@ -0,0 +1,24 @@
+// Shared plumbing for the doctor's Cloudflare API probes: the API base, the bearer-token
+// request helpers, and the skip results for the credentials the checks share. Every request
+// goes through ctx.fetch with the operator's CLOUDFLARE_API_TOKEN, so the tests script the
+// API and the bin passes global fetch.
+import { skip } from './types.js';
+export const CF_API = 'https://api.cloudflare.com/client/v4';
+export const NO_TOKEN = skip('set CLOUDFLARE_API_TOKEN to run this check');
+export const NO_FROM = skip('pass --from or set CAIRN_FROM to run this check');
+export const NO_ACCOUNT = skip('set CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID to run this check');
+export function cfGet(ctx, path) {
+    return ctx.fetch(`${CF_API}${path}`, {
+        headers: { authorization: `Bearer ${ctx.cfToken}` },
+    });
+}
+export function cfPost(ctx, path, body) {
+    return ctx.fetch(`${CF_API}${path}`, {
+        method: 'POST',
+        headers: {
+            authorization: `Bearer ${ctx.cfToken}`,
+            'content-type': 'application/json',
+        },
+        body: JSON.stringify(body),
+    });
+}

package/dist/doctor/index.d.ts

@@ -0,0 +1,23 @@
+import type { DoctorCheck, DoctorContext } from './types.js';
+export { runDoctor } from './run.js';
+export { formatReport } from './report.js';
+export interface DoctorArgs {
+    from?: string;
+    repo?: string;
+    sendTest?: string;
+}
+/** Parse the bin's argv (long flags only). Throws with a usage line on anything unexpected. */
+export declare function parseArgs(argv: string[]): DoctorArgs;
+/**
+ * Build the doctor's context from the environment and the parsed flags. A flag beats its env
+ * variable, and github assembles only when the whole credential trio is present, so the GitHub
+ * check skips with one remediation line instead of failing on a partial setup. fetch and
+ * readFile stay with the bin, which injects the real ones.
+ */
+export declare function contextFromEnv(env: Record<string, string | undefined>, args: DoctorArgs, cwd: string): Omit<DoctorContext, 'fetch' | 'readFile'>;
+/**
+ * The default registry: the four local-config checks, the four Cloudflare checks, and the
+ * GitHub App chain. The live send is opt-in (--send-test) and never sits here; the bin appends
+ * it. A fresh array per call, so that append mutates nothing shared.
+ */
+export declare function defaultChecks(): DoctorCheck[];

package/dist/doctor/index.js

@@ -0,0 +1,68 @@
+import { configBindings, configObservability, configCsrfDisable, configSiteConfig, } from './checks-local.js';
+import { emailSenderOnboarded, edgeHttpsForced, edgeHsts, authStore } from './checks-cloudflare.js';
+import { githubApp } from './checks-github.js';
+export { runDoctor } from './run.js';
+export { formatReport } from './report.js';
+const USAGE = 'Usage: cairn-doctor [--from <address>] [--repo <owner/name>] [--send-test <address>]';
+const FLAGS = {
+    '--from': 'from',
+    '--repo': 'repo',
+    '--send-test': 'sendTest',
+};
+/** Parse the bin's argv (long flags only). Throws with a usage line on anything unexpected. */
+export function parseArgs(argv) {
+    const args = {};
+    for (let i = 0; i < argv.length; i += 2) {
+        const flag = argv[i];
+        const key = FLAGS[flag];
+        if (!key)
+            throw new Error(`unknown argument ${flag}\n${USAGE}`);
+        const value = argv[i + 1];
+        if (value === undefined || value.startsWith('--')) {
+            throw new Error(`${flag} needs a value\n${USAGE}`);
+        }
+        args[key] = value;
+    }
+    return args;
+}
+/**
+ * Build the doctor's context from the environment and the parsed flags. A flag beats its env
+ * variable, and github assembles only when the whole credential trio is present, so the GitHub
+ * check skips with one remediation line instead of failing on a partial setup. fetch and
+ * readFile stay with the bin, which injects the real ones.
+ */
+export function contextFromEnv(env, args, cwd) {
+    const { GITHUB_APP_ID, GITHUB_APP_INSTALLATION_ID, GITHUB_APP_PRIVATE_KEY_B64 } = env;
+    return {
+        cwd,
+        from: args.from ?? env.CAIRN_FROM,
+        repo: args.repo ?? env.GITHUB_REPO,
+        cfToken: env.CLOUDFLARE_API_TOKEN,
+        cfAccountId: env.CLOUDFLARE_ACCOUNT_ID,
+        github: GITHUB_APP_ID && GITHUB_APP_INSTALLATION_ID && GITHUB_APP_PRIVATE_KEY_B64
+            ? {
+                appId: GITHUB_APP_ID,
+                installationId: GITHUB_APP_INSTALLATION_ID,
+                privateKeyB64: GITHUB_APP_PRIVATE_KEY_B64,
+            }
+            : undefined,
+    };
+}
+/**
+ * The default registry: the four local-config checks, the four Cloudflare checks, and the
+ * GitHub App chain. The live send is opt-in (--send-test) and never sits here; the bin appends
+ * it. A fresh array per call, so that append mutates nothing shared.
+ */
+export function defaultChecks() {
+    return [
+        configBindings,
+        configObservability,
+        configCsrfDisable,
+        configSiteConfig,
+        emailSenderOnboarded,
+        edgeHttpsForced,
+        edgeHsts,
+        authStore,
+        githubApp,
+    ];
+}

package/dist/doctor/report.d.ts

@@ -0,0 +1,5 @@
+import type { CheckResult, DoctorCheck } from './types.js';
+export declare function formatReport(results: {
+    check: DoctorCheck;
+    result: CheckResult;
+}[]): string;

package/dist/doctor/report.js

@@ -0,0 +1,21 @@
+// The doctor's report: one aligned line per check, then a why/remediation block per failure
+// resolved from the condition registry, then a count summary. Plain text, no ANSI color, so the
+// output reads the same in a terminal and a CI log. An unknown conditionId is a programming
+// error; condition() throws and the report does not paper over it.
+import { condition } from '../diagnostics/index.js';
+const TAG = {
+    pass: 'PASS',
+    fail: 'FAIL',
+    skip: 'SKIP',
+};
+export function formatReport(results) {
+    const lines = results.map(({ check, result }) => `${TAG[result.status]}  ${check.title}: ${result.detail}`);
+    const failures = results.filter(({ result }) => result.status === 'fail');
+    for (const { check } of failures) {
+        const entry = condition(check.conditionId);
+        lines.push('', `${check.title} failed.`, `  Why: ${entry.why}`, `  Fix: ${entry.remediation}`);
+    }
+    const count = (status) => results.filter(({ result }) => result.status === status).length;
+    lines.push('', `${count('pass')} passed, ${count('fail')} failed, ${count('skip')} skipped`);
+    return lines.join('\n');
+}

package/dist/doctor/run.d.ts

@@ -0,0 +1,8 @@
+import type { CheckResult, DoctorCheck, DoctorContext } from './types.js';
+export declare function runDoctor(checks: DoctorCheck[], ctx: DoctorContext): Promise<{
+    results: {
+        check: DoctorCheck;
+        result: CheckResult;
+    }[];
+    failed: number;
+}>;

package/dist/doctor/run.js

@@ -0,0 +1,20 @@
+// The doctor's runner: every check executes, every result lands in the table. A throwing check
+// records a fail and the run continues, so one broken probe never hides the rest of the picture.
+import { fail } from './types.js';
+export async function runDoctor(checks, ctx) {
+    const results = [];
+    let failed = 0;
+    for (const check of checks) {
+        let result;
+        try {
+            result = await check.run(ctx);
+        }
+        catch (err) {
+            result = fail(String(err));
+        }
+        if (result.status === 'fail')
+            failed += 1;
+        results.push({ check, result });
+    }
+    return { results, failed };
+}

package/dist/doctor/types.d.ts

@@ -0,0 +1,41 @@
+export type CheckStatus = 'pass' | 'fail' | 'skip';
+export interface CheckResult {
+    status: CheckStatus;
+    /** One line of evidence ("sending subdomain enabled", "wrangler.jsonc not found"). */
+    detail: string;
+}
+/** Result constructors, so a check body reads one outcome per line instead of object literals. */
+export declare function pass(detail: string): CheckResult;
+export declare function fail(detail: string): CheckResult;
+export declare function skip(detail: string): CheckResult;
+export interface DoctorCheck {
+    /** Stable id, e.g. 'email.sender-onboarded'. */
+    id: string;
+    /** The registry condition this check probes; the report prints its remediation on failure. */
+    conditionId: string;
+    title: string;
+    run: (ctx: DoctorContext) => Promise<CheckResult>;
+}
+/** Everything a check may read, resolved once by the bin. Absent fields make checks skip. */
+export interface DoctorContext {
+    /** The site directory the doctor runs in. */
+    cwd: string;
+    /** The from-address (--from / CAIRN_FROM). */
+    from?: string;
+    /** owner/name (--repo / GITHUB_REPO). */
+    repo?: string;
+    /** CLOUDFLARE_API_TOKEN. */
+    cfToken?: string;
+    /** CLOUDFLARE_ACCOUNT_ID. */
+    cfAccountId?: string;
+    /** GITHUB_APP_ID / GITHUB_APP_INSTALLATION_ID / GITHUB_APP_PRIVATE_KEY_B64. */
+    github?: {
+        appId: string;
+        installationId: string;
+        privateKeyB64: string;
+    };
+    /** Injected fetch for tests; defaults to global fetch. */
+    fetch: typeof fetch;
+    /** Read a file under cwd, or null when absent. Injected for tests. */
+    readFile: (relPath: string) => Promise<string | null>;
+}