@glw907/cairn-cms 0.40.0 → 0.41.0

package/src/lib/doctor/checks-cloudflare.ts

@@ -0,0 +1,222 @@
+// 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 type { CheckResult, DoctorCheck, DoctorContext } 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: string): string {
+	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: string): string {
+	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: number, scope: string): CheckResult | null {
+	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: DoctorContext,
+	domain: string
+): Promise<{ zoneId: string } | { fail: CheckResult }> {
+	// 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()) as { result?: { id?: string }[] };
+		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<T>(
+	ctx: DoctorContext,
+	domain: string,
+	settingId: string
+): Promise<{ value: T | undefined } | { fail: CheckResult }> {
+	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()) as { result?: { value?: T } };
+	return { value: body.result?.value };
+}
+
+export const emailSenderOnboarded: DoctorCheck = {
+	id: 'email.sender-onboarded',
+	conditionId: 'email.sender-not-onboarded',
+	title: 'Email sending domain',
+	async run(ctx: DoctorContext): Promise<CheckResult> {
+		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()) as { result?: { name?: string; enabled?: boolean }[] };
+			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: DoctorCheck = {
+	id: 'edge.https-forced',
+	conditionId: 'edge.https-not-forced',
+	title: 'Always Use HTTPS',
+	async run(ctx: DoctorContext): Promise<CheckResult> {
+		if (!ctx.cfToken) return NO_TOKEN;
+		if (!ctx.from) return NO_FROM;
+		try {
+			const setting = await readZoneSetting<string>(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));
+		}
+	},
+};
+
+interface SecurityHeaderValue {
+	strict_transport_security?: { enabled?: boolean; max_age?: number };
+}
+
+export const edgeHsts: DoctorCheck = {
+	id: 'edge.hsts',
+	conditionId: 'edge.hsts-off',
+	title: 'HSTS',
+	async run(ctx: DoctorContext): Promise<CheckResult> {
+		if (!ctx.cfToken) return NO_TOKEN;
+		if (!ctx.from) return NO_FROM;
+		try {
+			const setting = await readZoneSetting<SecurityHeaderValue>(
+				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: DoctorContext,
+	databaseId: string,
+	sql: string
+): Promise<{ rows: Record<string, unknown>[] } | { fail: CheckResult }> {
+	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()) as { result?: { results?: Record<string, unknown>[] }[] };
+	return { rows: body.result?.[0]?.results ?? [] };
+}
+
+export const authStore: DoctorCheck = {
+	id: 'auth.store',
+	conditionId: 'auth.store-unreachable',
+	title: 'Auth store (D1)',
+	async run(ctx: DoctorContext): Promise<CheckResult> {
+		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/src/lib/doctor/checks-github.ts

@@ -0,0 +1,63 @@
+// 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';
+import type { CheckResult, DoctorCheck, DoctorContext } from './types.js';
+
+const API = 'https://api.github.com';
+
+export const githubApp: DoctorCheck = {
+	id: 'github.app',
+	conditionId: 'github.app-unreachable',
+	title: 'GitHub App',
+	async run(ctx: DoctorContext): Promise<CheckResult> {
+		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: string;
+		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/src/lib/doctor/checks-local.ts

@@ -0,0 +1,119 @@
+// 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 type { CheckResult, DoctorCheck, DoctorContext } 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';
+import type { ConceptConfig } from '../content/types.js';
+
+const NO_WRANGLER: CheckResult = skip('no wrangler.jsonc or wrangler.toml found');
+
+export const configBindings: DoctorCheck = {
+	id: 'config.bindings',
+	conditionId: 'config.bindings-missing',
+	title: 'Wrangler bindings',
+	async run(ctx: DoctorContext): Promise<CheckResult> {
+		const facts = await readWranglerConfig(ctx.readFile);
+		if (facts === null) return NO_WRANGLER;
+		const missing: string[] = [];
+		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: DoctorCheck = {
+	id: 'config.observability',
+	conditionId: 'config.observability-off',
+	title: 'Workers Logs sink',
+	async run(ctx: DoctorContext): Promise<CheckResult> {
+		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: string): boolean {
+	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: string): boolean {
+	if (text.includes('@glw907/cairn-cms')) return true;
+	return /cairn/i.test(text) && /handle/.test(text);
+}
+
+export const configCsrfDisable: DoctorCheck = {
+	id: 'config.csrf-disable',
+	conditionId: 'config.csrf-disable-missing',
+	title: 'Framework CSRF handoff',
+	async run(ctx: DoctorContext): Promise<CheckResult> {
+		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: DoctorCheck = {
+	id: 'config.site-config',
+	conditionId: 'config.site-config-invalid',
+	title: 'Site config',
+	async run(ctx: DoctorContext): Promise<CheckResult> {
+		let text: string | null = 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): [string, ConceptConfig] => [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/src/lib/doctor/cloudflare-api.ts

@@ -0,0 +1,33 @@
+// 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';
+import type { CheckResult, DoctorContext } from './types.js';
+
+export const CF_API = 'https://api.cloudflare.com/client/v4';
+
+export const NO_TOKEN: CheckResult = skip('set CLOUDFLARE_API_TOKEN to run this check');
+
+export const NO_FROM: CheckResult = skip('pass --from or set CAIRN_FROM to run this check');
+
+export const NO_ACCOUNT: CheckResult = skip(
+	'set CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID to run this check'
+);
+
+export function cfGet(ctx: DoctorContext, path: string): Promise<Response> {
+	return ctx.fetch(`${CF_API}${path}`, {
+		headers: { authorization: `Bearer ${ctx.cfToken}` },
+	});
+}
+
+export function cfPost(ctx: DoctorContext, path: string, body: unknown): Promise<Response> {
+	return ctx.fetch(`${CF_API}${path}`, {
+		method: 'POST',
+		headers: {
+			authorization: `Bearer ${ctx.cfToken}`,
+			'content-type': 'application/json',
+		},
+		body: JSON.stringify(body),
+	});
+}

package/src/lib/doctor/index.ts

@@ -0,0 +1,93 @@
+// cairn-doctor's assembly: the flag parser, the context builder, and the default check
+// registry, all pure functions so the bin shell stays a thin wrapper like cairn-manifest's.
+// The module is internal; no public subpath exports it, and the bin is its only consumer.
+import type { DoctorCheck, DoctorContext } from './types.js';
+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>]';
+
+export interface DoctorArgs {
+	from?: string;
+	repo?: string;
+	sendTest?: string;
+}
+
+const FLAGS: Record<string, keyof DoctorArgs> = {
+	'--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: string[]): DoctorArgs {
+	const args: DoctorArgs = {};
+	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: Record<string, string | undefined>,
+	args: DoctorArgs,
+	cwd: string
+): Omit<DoctorContext, 'fetch' | 'readFile'> {
+	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(): DoctorCheck[] {
+	return [
+		configBindings,
+		configObservability,
+		configCsrfDisable,
+		configSiteConfig,
+		emailSenderOnboarded,
+		edgeHttpsForced,
+		edgeHsts,
+		authStore,
+		githubApp,
+	];
+}

package/src/lib/doctor/report.ts

@@ -0,0 +1,30 @@
+// 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';
+import type { CheckResult, DoctorCheck } from './types.js';
+
+const TAG: Record<CheckResult['status'], string> = {
+	pass: 'PASS',
+	fail: 'FAIL',
+	skip: 'SKIP',
+};
+
+export function formatReport(results: { check: DoctorCheck; result: CheckResult }[]): string {
+	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: CheckResult['status']) =>
+		results.filter(({ result }) => result.status === status).length;
+	lines.push('', `${count('pass')} passed, ${count('fail')} failed, ${count('skip')} skipped`);
+
+	return lines.join('\n');
+}

package/src/lib/doctor/run.ts

@@ -0,0 +1,23 @@
+// 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';
+import type { CheckResult, DoctorCheck, DoctorContext } from './types.js';
+
+export async function runDoctor(
+	checks: DoctorCheck[],
+	ctx: DoctorContext
+): Promise<{ results: { check: DoctorCheck; result: CheckResult }[]; failed: number }> {
+	const results: { check: DoctorCheck; result: CheckResult }[] = [];
+	let failed = 0;
+	for (const check of checks) {
+		let result: CheckResult;
+		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/src/lib/doctor/types.ts

@@ -0,0 +1,52 @@
+// The doctor's check model (diagnostics spec, Arm B). Each check is isolated: no check reads
+// another's result. The conditionId ties the check to the registry entry whose why/remediation
+// the report prints, keeping the doctor, the runtime errors, and the checklist on one identity.
+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 function pass(detail: string): CheckResult {
+	return { status: 'pass', detail };
+}
+
+export function fail(detail: string): CheckResult {
+	return { status: 'fail', detail };
+}
+
+export function skip(detail: string): CheckResult {
+	return { status: 'skip', detail };
+}
+
+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>;
+}