@coywolf/emdash 0.0.0-stage → 0.35.13

package/src/headings/stamp.ts

@@ -0,0 +1,142 @@
+/**
+ * Save-time stamping (content:beforeSave). EmDash's Portable Text renderer
+ * emits headings without ids, and a block component only sees its own node,
+ * so everything the site needs is written into the content when it's saved:
+ *
+ * - each H2–H6 heading block gets an `anchor` field (e.g. "jump-pricing"),
+ *   unique within its field and kept across edits (matched to the previous
+ *   save by block `_key`, then by text), because the editor drops unknown
+ *   fields on heading blocks;
+ * - each `coywolf-toc` block gets `_headings`, the field's heading list.
+ *
+ * (Breadcrumbs blocks are stamped by the Breadcrumb Nav module, src/breadcrumbs/stamp.ts.)
+ *
+ * Pure: returns new objects and never mutates its input. Running it twice
+ * gives the same result (`changed: false` the second time).
+ */
+import { blockText, headingLevel, uniqueSlug, validAnchor } from "./slug.js";
+import type { TocHeading } from "./toc.js";
+
+export const TOC_BLOCK = "coywolf-toc";
+export const ANCHOR_LEVELS = [2, 3, 4, 5, 6];
+
+export interface StampOptions {
+	/** Stamp heading anchors (and TOC heading lists, when `toc`). */
+	anchors: boolean;
+	toc: boolean;
+	prefix: string;
+	/** The entry's stored data before this save, to keep anchors stable. */
+	previous?: Record<string, unknown> | null;
+}
+
+type Block = Record<string, unknown> & { _type: string; _key?: string };
+
+/** An array that looks like Portable Text: every item is an object with a string `_type`. */
+function isPortableText(value: unknown): value is Block[] {
+	return (
+		Array.isArray(value) &&
+		value.length > 0 &&
+		value.every((b) => b && typeof b === "object" && typeof (b as { _type?: unknown })._type === "string")
+	);
+}
+
+function sameJson(a: unknown, b: unknown): boolean {
+	return JSON.stringify(a) === JSON.stringify(b);
+}
+
+/** Previous anchors of one field, by block key and by heading text. */
+function previousAnchors(previous: unknown) {
+	const byKey = new Map<string, string>();
+	const byText = new Map<string, string>();
+	if (isPortableText(previous)) {
+		for (const block of previous) {
+			if (!headingLevel(block) || !validAnchor(block.anchor)) continue;
+			if (typeof block._key === "string") byKey.set(block._key, block.anchor);
+			const text = blockText(block);
+			if (text && !byText.has(text)) byText.set(text, block.anchor);
+		}
+	}
+	return { byKey, byText };
+}
+
+/** Stamp one Portable Text field. Returns the new array, or null when nothing changed. */
+export function stampField(blocks: Block[], options: StampOptions, previousField: unknown): Block[] | null {
+	const out = blocks.slice();
+	let changed = false;
+	const set = (i: number, patch: Record<string, unknown>, remove?: string) => {
+		const next: Block = { ...out[i], ...patch };
+		if (remove) delete next[remove];
+		out[i] = next;
+		changed = true;
+	};
+
+	const headings: TocHeading[] = [];
+	if (options.anchors) {
+		const { byKey, byText } = previousAnchors(previousField);
+		const taken = new Set<string>();
+		const pending: { index: number; level: number; text: string; kept: string | null; byText: string | null }[] = [];
+
+		blocks.forEach((block, index) => {
+			const level = headingLevel(block);
+			if (!level || !ANCHOR_LEVELS.includes(level)) return;
+			const text = blockText(block);
+			if (!text) {
+				if ("anchor" in block) set(index, {}, "anchor");
+				return;
+			}
+			const kept = (validAnchor(block.anchor) ? block.anchor : null) ?? (typeof block._key === "string" ? byKey.get(block._key) : undefined) ?? null;
+			pending.push({ index, level, text, kept, byText: byText.get(text) ?? null });
+		});
+
+		// Claim anchors in priority order (first claim wins): the block's own or its previous
+		// anchor (by _key), then a previous anchor with the same text, then a new slug.
+		const ids = new Map<number, string>();
+		const claim = (pick: (p: (typeof pending)[number]) => string | null) => {
+			for (const p of pending) {
+				const id = ids.has(p.index) ? null : pick(p);
+				if (id && !taken.has(id)) {
+					taken.add(id);
+					ids.set(p.index, id);
+				}
+			}
+		};
+		claim((p) => p.kept);
+		claim((p) => p.byText);
+		for (const p of pending) if (!ids.has(p.index)) ids.set(p.index, uniqueSlug(p.text, taken, options.prefix));
+
+		for (const p of pending) {
+			const id = ids.get(p.index) as string;
+			if (blocks[p.index].anchor !== id) set(p.index, { anchor: id });
+			headings.push({ level: p.level, id, text: p.text });
+		}
+	}
+
+	if (options.toc && options.anchors) {
+		blocks.forEach((block, index) => {
+			if (block._type === TOC_BLOCK && !sameJson(block._headings, headings)) set(index, { _headings: headings });
+		});
+	}
+
+	return changed ? out : null;
+}
+
+/** Stamp every Portable Text field of an entry. Returns the new content, or null when nothing changed. */
+export function stampContent(content: Record<string, unknown>, options: StampOptions): Record<string, unknown> | null {
+	let result: Record<string, unknown> | null = null;
+	for (const [field, value] of Object.entries(content)) {
+		if (!isPortableText(value)) continue;
+		const stamped = stampField(value, options, options.previous?.[field]);
+		if (stamped) {
+			result ??= { ...content };
+			result[field] = stamped;
+		}
+	}
+	return result;
+}
+
+/** Whether any field has a heading without a valid anchor (so the previous version is worth reading). */
+export function needsPrevious(content: Record<string, unknown>): boolean {
+	return Object.values(content).some(
+		(value) => isPortableText(value) && value.some((block) => headingLevel(block) && !validAnchor(block.anchor)),
+	);
+}

package/src/headings/test-hooks.mjs

@@ -0,0 +1,14 @@
+// Test-only resolve hook: source files import "./x.js" (bundler style); under
+// `node --test` with type stripping, map those to the sibling .ts file.
+import { registerHooks } from "node:module";
+
+registerHooks({
+	resolve(specifier, context, next) {
+		try {
+			return next(specifier, context);
+		} catch (error) {
+			if (specifier.startsWith(".") && specifier.endsWith(".js")) return next(specifier.slice(0, -3) + ".ts", context);
+			throw error;
+		}
+	},
+});

package/src/headings/toc.ts

@@ -0,0 +1,48 @@
+/**
+ * Table of contents tree: the flat heading list stamped into a TOC block,
+ * filtered to the block's levels and nested by level. Tolerant of skipped
+ * levels (an H4 straight after an H2 nests under the H2).
+ */
+
+export interface TocHeading {
+	level: number;
+	id: string;
+	text: string;
+}
+
+export interface TocNode extends TocHeading {
+	children: TocNode[];
+}
+
+export function buildTocTree(headings: readonly TocHeading[], levels: readonly number[]): TocNode[] {
+	const wanted = new Set(levels);
+	const root: TocNode[] = [];
+	const stack: TocNode[] = [];
+	for (const heading of headings) {
+		if (!wanted.has(heading.level)) continue;
+		const node: TocNode = { level: heading.level, id: heading.id, text: heading.text, children: [] };
+		while (stack.length && stack[stack.length - 1].level >= node.level) stack.pop();
+		(stack.length ? stack[stack.length - 1].children : root).push(node);
+		stack.push(node);
+	}
+	return root;
+}
+
+/** Count every node in a tree. */
+export function countToc(nodes: readonly TocNode[]): number {
+	return nodes.reduce((n, node) => n + 1 + countToc(node.children), 0);
+}
+
+/** Clean the heading list stored on a TOC block (it's content data, so treat it as untrusted). */
+export function storedHeadings(value: unknown): TocHeading[] {
+	if (!Array.isArray(value)) return [];
+	const out: TocHeading[] = [];
+	for (const item of value) {
+		if (!item || typeof item !== "object") continue;
+		const { level, id, text } = item as Record<string, unknown>;
+		if (typeof level !== "number" || level < 1 || level > 6) continue;
+		if (typeof id !== "string" || !id || typeof text !== "string" || !text) continue;
+		out.push({ level, id, text });
+	}
+	return out;
+}

package/src/images/cloudflare.ts

@@ -0,0 +1,329 @@
+/**
+ * Media host setup and checks through the Cloudflare API, plus the live check
+ * of a media host. The API token is only ever sent to api.cloudflare.com: it
+ * is never logged, returned, or included in error messages.
+ */
+import { type CustomDomain, type RulesetRule, type SetupPlan, type SetupState, hostnameOf, planMediaHostSetup, zoneCandidates } from "./setup.js";
+
+export const CLOUDFLARE_API_HOST = "api.cloudflare.com";
+const API = `https://${CLOUDFLARE_API_HOST}/client/v4`;
+
+type Fetch = (url: string, init?: RequestInit) => Promise<Response>;
+
+export interface CloudflareConfig {
+	token: string;
+	accountId: string;
+	fetch?: Fetch;
+}
+
+export class CloudflareApiError extends Error {
+	readonly status: number;
+	constructor(message: string, status: number) {
+		super(message);
+		this.status = status;
+	}
+}
+
+/** What each step of the setup needs, for error messages when the token lacks it. */
+const PERMISSION_HINT: Record<string, string> = {
+	zone: "Zone → Zone → Read",
+	transformations: "Zone → Zone Settings → Edit",
+	domain: "Account → Workers R2 Storage → Edit and Zone → DNS → Edit",
+	rules: "Zone → Transform Rules → Edit (and Account → Account Rulesets → Read)",
+	purge: "Zone → Cache Purge → Purge",
+	cacheRules: "Zone → Cache Rules → Edit",
+	tieredCache: "Zone → Zone Settings → Edit",
+};
+
+async function cf<T>(config: CloudflareConfig, path: string, init: RequestInit = {}, step?: string): Promise<{ status: number; result: T | null }> {
+	const doFetch = config.fetch ?? fetch;
+	const res = await doFetch(`${API}${path}`, {
+		...init,
+		headers: { Authorization: `Bearer ${config.token}`, "Content-Type": "application/json", ...(init.headers ?? {}) },
+	});
+	const body = (await res.json().catch(() => ({}))) as { success?: boolean; result?: T; errors?: Array<{ code?: number; message?: string }> };
+	if (!res.ok || body.success === false) {
+		const detail = body.errors?.map((e) => e.message).filter(Boolean).join("; ") || res.statusText;
+		const hint = (res.status === 401 || res.status === 403) && step ? ` The API token needs ${PERMISSION_HINT[step]}.` : "";
+		throw new CloudflareApiError(`Cloudflare API ${res.status}: ${detail}.${hint}`, res.status);
+	}
+	return { status: res.status, result: body.result ?? null };
+}
+
+/**
+ * Clear everything Cloudflare's zone cache holds for one host name (the media
+ * host: originals and resized copies). Purge by hostname works on every plan.
+ */
+export async function purgeHost(config: CloudflareConfig, hostname: string): Promise<void> {
+	const zone = await findZone(config, hostname);
+	await cf(config, `/zones/${zone.id}/purge_cache`, { method: "POST", body: JSON.stringify({ hosts: [hostname] }) }, "purge");
+}
+
+/** Description that marks the media host's cache rule as the pack's own. */
+export const MEDIA_CACHE_RULE = "Coywolf Pack: media host";
+const YEAR = 31536000;
+
+interface CacheRule {
+	id?: string;
+	description?: string;
+	expression?: string;
+	action?: string;
+	action_parameters?: { cache?: boolean; edge_ttl?: { default?: number }; browser_ttl?: { default?: number } };
+	enabled?: boolean;
+}
+
+function mediaCacheRule(hostname: string): CacheRule {
+	return {
+		description: `${MEDIA_CACHE_RULE} (file names never change)`,
+		expression: `(http.host eq "${hostname}")`,
+		action: "set_cache_settings",
+		action_parameters: { cache: true, edge_ttl: { mode: "override_origin", default: YEAR }, browser_ttl: { mode: "override_origin", default: YEAR } } as CacheRule["action_parameters"],
+		enabled: true,
+	};
+}
+
+/**
+ * The media host's Cache Rule, if any: a zone cache rule for exactly this host
+ * name that caches it (made by the pack or by hand).
+ */
+export async function readMediaCacheRule(config: CloudflareConfig, hostname: string): Promise<{ zone: string; rule: { edgeTtl?: number; browserTtl?: number; enabled: boolean } | null }> {
+	const zone = await findZone(config, hostname);
+	let rules: CacheRule[] = [];
+	try {
+		const { result } = await cf<{ rules?: CacheRule[] }>(config, `/zones/${zone.id}/rulesets/phases/http_request_cache_settings/entrypoint`, {}, "cacheRules");
+		rules = result?.rules ?? [];
+	} catch (error) {
+		if (!(error instanceof CloudflareApiError && error.status === 404)) throw error;
+	}
+	const rule = rules.find((r) => r.action === "set_cache_settings" && r.action_parameters?.cache === true && r.expression?.includes(`"${hostname}"`));
+	return {
+		zone: zone.name,
+		rule: rule ? { edgeTtl: rule.action_parameters?.edge_ttl?.default, browserTtl: rule.action_parameters?.browser_ttl?.default, enabled: rule.enabled !== false } : null,
+	};
+}
+
+/**
+ * Cache the media host at the edge and in browsers for a year (its file names
+ * are unique, so a changed file always has a new name). Adds the rule to the
+ * zone's cache rules, or updates the pack's earlier one; other rules are kept.
+ */
+export async function applyMediaCacheRule(config: CloudflareConfig, hostname: string): Promise<string> {
+	const zone = await findZone(config, hostname);
+	const phase = `/zones/${zone.id}/rulesets/phases/http_request_cache_settings/entrypoint`;
+	let ruleset: { id: string; rules?: CacheRule[] } | null = null;
+	try {
+		ruleset = (await cf<{ id: string; rules?: CacheRule[] }>(config, phase, {}, "cacheRules")).result;
+	} catch (error) {
+		if (!(error instanceof CloudflareApiError && error.status === 404)) throw error;
+	}
+	const rule = mediaCacheRule(hostname);
+	if (!ruleset) {
+		await cf(config, phase, { method: "PUT", body: JSON.stringify({ rules: [rule] }) }, "cacheRules");
+		return zone.name;
+	}
+	const existing = ruleset.rules?.find((r) => r.description?.startsWith(MEDIA_CACHE_RULE) && r.expression?.includes(`"${hostname}"`));
+	if (existing?.id) {
+		await cf(config, `/zones/${zone.id}/rulesets/${ruleset.id}/rules/${existing.id}`, { method: "PATCH", body: JSON.stringify(rule) }, "cacheRules");
+	} else {
+		await cf(config, `/zones/${zone.id}/rulesets/${ruleset.id}/rules`, { method: "POST", body: JSON.stringify(rule) }, "cacheRules");
+	}
+	return zone.name;
+}
+
+/** The zone that holds a host name, looked up in the account (most specific name first). */
+export async function findZone(config: CloudflareConfig, hostname: string): Promise<{ id: string; name: string; plan?: string }> {
+	for (const name of zoneCandidates(hostname)) {
+		const { result } = await cf<Array<{ id: string; name: string; plan?: { name?: string } }>>(
+			config,
+			`/zones?name=${encodeURIComponent(name)}&account.id=${encodeURIComponent(config.accountId)}`,
+			{},
+			"zone",
+		);
+		const zone = result?.find((z) => z.name === name);
+		if (zone) return { id: zone.id, name: zone.name, plan: zone.plan?.name };
+	}
+	throw new CloudflareApiError(
+		`No zone for ${hostname} in this Cloudflare account. Add the site's domain to the account, or check the account ID. The API token needs ${PERMISSION_HINT.zone}.`,
+		404,
+	);
+}
+
+async function readRules(config: CloudflareConfig, zoneId: string): Promise<RulesetRule[] | null> {
+	try {
+		const { result } = await cf<{ rules?: RulesetRule[] }>(config, `/zones/${zoneId}/rulesets/phases/http_request_transform/entrypoint`, {}, "rules");
+		return result?.rules ?? [];
+	} catch (error) {
+		if (error instanceof CloudflareApiError && error.status === 404) return null;
+		throw error;
+	}
+}
+
+export interface SetupTarget {
+	host: string;
+	bucket: string;
+}
+
+export interface SetupContext {
+	zone: { id: string; name: string; plan?: string };
+	state: SetupState;
+	plan: SetupPlan;
+}
+
+/** Read the current state and plan the setup (changes nothing). */
+export async function planSetup(config: CloudflareConfig, target: SetupTarget): Promise<SetupContext> {
+	const hostname = hostnameOf(target.host);
+	const zone = await findZone(config, hostname);
+	const [transformations, domains, rules, tieredCache] = await Promise.all([
+		cf<{ value?: string }>(config, `/zones/${zone.id}/settings/transformations`, {}, "transformations").then((r) => r.result?.value ?? null),
+		cf<{ domains?: CustomDomain[] }>(config, `/accounts/${config.accountId}/r2/buckets/${encodeURIComponent(target.bucket)}/domains/custom`, {}, "domain").then(
+			(r) => r.result?.domains ?? [],
+		),
+		readRules(config, zone.id),
+		// Read only to show the step; a token without the permission still gets the rest of the setup.
+		cf<{ value?: string }>(config, `/zones/${zone.id}/cache/tiered_cache_smart_topology_enable`, {}, "tieredCache")
+			.then((r) => r.result?.value ?? null)
+			.catch(() => null),
+	]);
+	const state: SetupState = { transformations, domains, rules, tieredCache };
+	return { zone, state, plan: planMediaHostSetup(state, { host: hostname, zoneName: zone.name, bucket: target.bucket }) };
+}
+
+export interface StepResult {
+	id: string;
+	ok: boolean;
+	message: string;
+}
+
+/** Apply the steps that need it, in order; stops at the first failure. */
+export async function applySetup(config: CloudflareConfig, target: SetupTarget): Promise<{ zone: string; results: StepResult[] }> {
+	const { zone, plan } = await planSetup(config, target);
+	const bucket = encodeURIComponent(target.bucket);
+	const results: StepResult[] = [];
+	for (const step of plan.steps) {
+		if (step.action === "none") {
+			results.push({ id: step.id, ok: true, message: step.label });
+			continue;
+		}
+		try {
+			if (step.id === "transformations") {
+				await cf(config, `/zones/${zone.id}/settings/transformations`, { method: "PATCH", body: JSON.stringify({ value: "on" }) }, "transformations");
+				results.push({ id: step.id, ok: true, message: `Turned on Image Transformations for ${zone.name}.` });
+			} else if (step.id === "domain" && step.action === "add") {
+				await cf(
+					config,
+					`/accounts/${config.accountId}/r2/buckets/${bucket}/domains/custom`,
+					{ method: "POST", body: JSON.stringify({ domain: plan.host, zoneId: zone.id, enabled: true, minTLS: "1.2" }) },
+					"domain",
+				);
+				results.push({ id: step.id, ok: true, message: `Connected ${plan.host} to ${target.bucket}. Its certificate can take a few minutes.` });
+			} else if (step.id === "domain") {
+				await cf(
+					config,
+					`/accounts/${config.accountId}/r2/buckets/${bucket}/domains/custom/${encodeURIComponent(plan.host)}`,
+					{ method: "PUT", body: JSON.stringify({ enabled: true, minTLS: "1.2" }) },
+					"domain",
+				);
+				results.push({ id: step.id, ok: true, message: `Turned on ${plan.host} for ${target.bucket}.` });
+			} else if (step.id === "rules") {
+				await cf(
+					config,
+					`/zones/${zone.id}/rulesets/phases/http_request_transform/entrypoint`,
+					{ method: "PUT", body: JSON.stringify({ rules: plan.rules }) },
+					"rules",
+				);
+				results.push({ id: step.id, ok: true, message: `Saved the URL rewrite rules for ${plan.host}.` });
+			} else if (step.id === "tieredCache") {
+				await cf(config, `/zones/${zone.id}/cache/tiered_cache_smart_topology_enable`, { method: "PATCH", body: JSON.stringify({ value: "on" }) }, "tieredCache");
+				results.push({ id: step.id, ok: true, message: `Turned on Smart Tiered Cache for ${zone.name}.` });
+			}
+		} catch (error) {
+			results.push({ id: step.id, ok: false, message: error instanceof Error ? error.message : "Failed." });
+			break;
+		}
+	}
+	return { zone: zone.name, results };
+}
+
+// ── Live check of a media host ───────────────────────────────────
+
+export interface CheckItem {
+	id: "reachable" | "original" | "resize" | "cached";
+	ok: boolean;
+	label: string;
+	detail: string;
+}
+
+/** Pure: turn the two fetches' outcomes into check items (exported for tests). */
+export function checkItems(input: {
+	file: string;
+	original: { status: number; type: string } | { error: string };
+	resized: { status: number; type: string; cfResized: string | null; cache: string | null } | { error: string };
+}): CheckItem[] {
+	const items: CheckItem[] = [];
+	const o = input.original;
+	const r = input.resized;
+	const reached = !("error" in o) || !("error" in r);
+	items.push({
+		id: "reachable",
+		ok: reached,
+		label: "Host reachable",
+		detail: reached ? "The media host answered." : `Couldn't connect: ${"error" in o ? o.error : ""}. Check the custom domain on the bucket and its DNS.`,
+	});
+	const originalOk = !("error" in o) && o.status === 200 && o.type.startsWith("image/");
+	items.push({
+		id: "original",
+		ok: originalOk,
+		label: "Original served",
+		detail:
+			"error" in o
+				? "No answer."
+				: originalOk
+					? `${input.file} (${o.type}).`
+					: o.status === 404
+						? `${input.file} wasn't found (404). Is the custom domain on the bucket bound as MEDIA?`
+						: `Answered ${o.status}${o.type ? ` (${o.type})` : ""}.`,
+	});
+	const resizeOk = !("error" in r) && r.status === 200 && (Boolean(r.cfResized) || r.type.startsWith("image/"));
+	items.push({
+		id: "resize",
+		ok: resizeOk,
+		label: "Resize works",
+		detail:
+			"error" in r
+				? "No answer."
+				: resizeOk
+					? `/s/64x64/ answered ${r.type || "an image"}${r.cfResized ? " (resized by Cloudflare)" : ""}.`
+					: r.status === 404
+						? originalOk
+							? "/s/64x64/ wasn't found (404) from inside the Worker. A check from the Worker isn't conclusive for a media host on the site's own zone, so this alone doesn't mean the URL rewrite rules are missing: the Clean Image URLs page checks again from your browser."
+							: "/s/64x64/ wasn't found (404): the URL rewrite rules are missing, or don't match this host."
+						: `/s/64x64/ answered ${r.status}. Are Image Transformations on for the zone?`,
+	});
+	const cache = "error" in r ? null : (r.cache ?? "").toUpperCase();
+	const cached = cache === "HIT" || cache === "REVALIDATED" || cache === "STALE" || cache === "UPDATING";
+	items.push({
+		id: "cached",
+		ok: cached,
+		label: "Cached at the edge",
+		detail: cache ? `Second request: cf-cache-status ${cache}.` : "No cf-cache-status header (normal for the first few requests after setup).",
+	});
+	return items;
+}
+
+/** Fetch a file and a 64×64 copy from the media host (the copy twice, to see the cache). */
+export async function checkMediaHost(host: string, file: string, doFetch: Fetch = fetch): Promise<CheckItem[]> {
+	const accept = "image/avif,image/webp,image/*,*/*;q=0.8";
+	const get = async (url: string) => {
+		try {
+			const res = await doFetch(url, { headers: { Accept: accept }, redirect: "follow" });
+			await res.body?.cancel().catch(() => undefined);
+			return { status: res.status, type: (res.headers.get("content-type") ?? "").split(";")[0].trim(), cfResized: res.headers.get("cf-resized"), cache: res.headers.get("cf-cache-status") };
+		} catch (error) {
+			return { error: error instanceof Error ? error.message : "network error" };
+		}
+	};
+	const original = await get(`${host}/${file}`);
+	const first = await get(`${host}/s/64x64/${file}`);
+	const resized = "error" in first || first.status !== 200 ? first : await get(`${host}/s/64x64/${file}`);
+	return checkItems({ file, original, resized });
+}