@coywolf/emdash 0.0.0-stage → 0.35.14

package/src/reviews/pack.ts

@@ -0,0 +1,135 @@
+/**
+ * Reviews module: the Coywolf Review block (rating badge, pros and cons),
+ * its style settings (accent color, custom CSS) on the Reviews admin page,
+ * and Review schema, folded into Schema & Social's graph or printed on its
+ * own. Rendered by src/astro/reviews/CoywolfReview.astro.
+ */
+import { definePluginRoute } from "emdash";
+import { z } from "zod";
+
+import { registerFeatures } from "../core/features.js";
+import type { PackModule } from "../core/module.js";
+import { parseInput } from "../shared.js";
+import {
+	BLOCK_TYPE,
+	DEFAULT_ACCENT,
+	DEFAULT_CONS_HEADING,
+	DEFAULT_PROS_HEADING,
+	ITEM_TYPES,
+	MAX_CUSTOM_CSS,
+	RATING_OPTIONS,
+	STYLE_SETTING,
+	isAccent,
+	normalizeReviewRatings,
+	normalizeStyle,
+	sanitizeCustomCss,
+} from "./lib.js";
+import { reviewsMetadata } from "./schema.js";
+import { invalidateReviewStyle } from "./settings.js";
+
+// biome-ignore lint/suspicious/noEmptyInterface: reserved for future options.
+export interface ReviewsOptions {}
+
+export const F = { main: "reviews", schema: "reviews.schema" } as const;
+
+export const FEATURES = [
+	{ id: F.main, label: "Reviews", description: "The Coywolf Review block: a rating badge with what you liked and what could be better.", default: false },
+	{
+		id: F.schema,
+		label: "Review schema",
+		description: "Review structured data (rating, pros and cons) for each review, in Schema & Social's graph or on its own.",
+		default: false,
+	},
+];
+registerFeatures(FEATURES);
+
+/** Store ratings as the menu's values ("4" → "4.0"), so older reviews show their rating in the editor. */
+async function beforeSave(event: { content: Record<string, unknown> }) {
+	if (!event.content || !JSON.stringify(event.content).includes(`"${BLOCK_TYPE}"`)) return undefined;
+	return normalizeReviewRatings(event.content) ?? undefined;
+}
+
+export function reviewsPack(_options: ReviewsOptions): PackModule {
+	return {
+		id: "reviews",
+		label: "Reviews",
+		features: FEATURES,
+		hooks: { "page:metadata": reviewsMetadata, "content:beforeSave": beforeSave },
+		hookFeature: { "page:metadata": F.schema },
+		adminPages: [{ path: "/reviews", label: "Reviews", icon: "star" }],
+		capabilities: ["content:read"],
+		routes: {
+			"reviews/settings": {
+				permission: "plugins:manage" as const,
+				// biome-ignore lint/suspicious/noExplicitAny: plugin context.
+				handler: async (ctx: any) => ({ ...normalizeStyle(await ctx.settings.get(STYLE_SETTING)), defaultAccent: DEFAULT_ACCENT }),
+			},
+
+			"reviews/save": definePluginRoute({
+				permission: "plugins:manage",
+				methods: ["POST"],
+				request: { body: "json" },
+				handler: async (ctx) => {
+					const input = parseInput(
+						z.object({
+							accent: z.string().max(9).refine(isAccent, "Use a hex color like #2C8452."),
+							css: z.string().max(MAX_CUSTOM_CSS, `Custom CSS is limited to ${MAX_CUSTOM_CSS / 1000} KB.`),
+						}),
+						ctx.input,
+					);
+					const style = { accent: input.accent, css: sanitizeCustomCss(input.css) };
+					await ctx.settings.set(STYLE_SETTING, style);
+					invalidateReviewStyle();
+					ctx.log.info("Review style saved", { accent: style.accent, cssBytes: style.css.length });
+					return style;
+				},
+			}),
+		},
+		portableTextBlocks: [
+			{
+				type: BLOCK_TYPE,
+				label: "Coywolf Review",
+				icon: "star",
+				category: "Content",
+				description: "A rating badge with pros and cons, and Review schema",
+				fields: [
+					{ type: "text_input", action_id: "itemName", label: "Item name (what you're reviewing)" },
+					{
+						type: "select",
+						action_id: "itemType",
+						label: "Item type",
+						options: ITEM_TYPES.map(([value, label]) => ({ value, label })),
+						initial_value: "Product",
+					},
+					{ type: "text_input", action_id: "brand", label: "Brand (optional)" },
+					{ type: "text_input", action_id: "itemUrl", label: "Item URL (optional, https://…)" },
+					{ type: "media_picker", action_id: "image", label: "Item image (optional, for schema)", mime_type_filter: "image/" },
+					{ type: "text_input", action_id: "bookAuthor", label: "Book author (books only, for schema)" },
+					{ type: "text_input", action_id: "isbn", label: "ISBN (books only, for schema)" },
+					{ type: "text_input", action_id: "bookPublisher", label: "Publisher (books only, for schema)" },
+					{ type: "text_input", action_id: "genre", label: "Genre (books only, for schema)" },
+					{ type: "text_input", action_id: "copyrightYear", label: "Copyright year (books only, for schema)" },
+					{ type: "text_input", action_id: "operatingSystem", label: "Operating systems (software only, e.g. macOS, Windows)" },
+					{ type: "text_input", action_id: "applicationCategory", label: "App category (software only, e.g. Utilities)" },
+					{ type: "select", action_id: "rating", label: "Rating (0 to 5, in tenths)", options: RATING_OPTIONS },
+					{ type: "text_input", action_id: "prosHeading", label: "Pros heading", initial_value: DEFAULT_PROS_HEADING },
+					{ type: "text_input", action_id: "pros", label: "Pros (one per line)", multiline: true },
+					{ type: "text_input", action_id: "consHeading", label: "Cons heading", initial_value: DEFAULT_CONS_HEADING },
+					{ type: "text_input", action_id: "cons", label: "Cons (one per line)", multiline: true },
+					{ type: "text_input", action_id: "summary", label: "Summary or verdict (optional)", multiline: true },
+					{
+						type: "select",
+						action_id: "headingLevel",
+						label: "Heading level",
+						options: [
+							{ value: "2", label: "H2" },
+							{ value: "3", label: "H3" },
+							{ value: "4", label: "H4" },
+						],
+						initial_value: "2",
+					},
+				],
+			},
+		],
+	};
+}

package/src/reviews/schema.ts

@@ -0,0 +1,128 @@
+/**
+ * Review schema for a rendered page: the `coywolf-review` blocks in the
+ * entry, plus any reviews the theme passes as `page.coywolf.reviews` (legacy
+ * WordPress markers). Schema & Social folds them into its @graph
+ * (attachPageReviews); with the graph off, the page:metadata hook here prints
+ * standalone JSON-LD instead.
+ */
+import type { PageMetadataContribution, PageMetadataEvent, PluginContext } from "emdash";
+
+import { cachedCtxFeatures, isOn } from "../core/features.js";
+import { noteReadFailure, readFailures } from "../core/read-failures.js";
+import { siteName } from "../core/site.js";
+import { originOf, pageUrl } from "../schema/graph.js";
+import { BLOCK_TYPE, type Node, type Review, attachReviews, findReviewBlocks, normalizeReview, reviewDocuments } from "./lib.js";
+
+/** Text every stored review block contains: entry columns without it can't hold one (and aren't parsed). */
+export const REVIEW_MARKER = `"${BLOCK_TYPE}"`;
+
+type Page = PageMetadataEvent["page"];
+
+const TTL_MS = 5 * 60_000;
+const MAX_CACHED = 300;
+/** Per-isolate cache of each entry's review blocks, keyed by entry and its modified time. */
+const memo = new Map<string, { at: number; stamp: string; reviews: Review[] }>();
+
+function themeReviews(page: Page): Review[] {
+	const themed = (page as Page & { coywolf?: { reviews?: unknown } }).coywolf?.reviews;
+	if (!Array.isArray(themed)) return [];
+	return themed
+		.slice(0, 20)
+		.map(normalizeReview)
+		.filter((r): r is Review => r !== null);
+}
+
+const reviewsIn = (data: unknown): Review[] =>
+	findReviewBlocks(data ?? null)
+		.map(normalizeReview)
+		.filter((r): r is Review => r !== null);
+
+function memoHit(page: Page): Review[] | undefined {
+	if (!page.content) return undefined;
+	const hit = memo.get(`${page.content.collection}:${page.content.id}`);
+	return hit && hit.stamp === (page.articleMeta?.modifiedTime ?? "") && Date.now() - hit.at < TTL_MS ? hit.reviews : undefined;
+}
+
+/** Whether finding the page's review blocks needs the entry's data (no recent copy in this isolate). */
+export function needsEntryData(page: Page): boolean {
+	return Boolean(page.content) && memoHit(page) === undefined;
+}
+
+/**
+ * Where the entry's data comes from: the entry itself (the theme passed it;
+ * nothing is read), or a function that reads it (Schema & Social's batched
+ * read). Without one, it's read through the plugin context.
+ */
+export type EntryDataSource = Record<string, unknown> | (() => Promise<Record<string, unknown> | null | undefined>);
+
+async function blockReviews(ctx: PluginContext, page: Page, source?: EntryDataSource): Promise<Review[]> {
+	if (!page.content) return [];
+	if (source && typeof source === "object") return reviewsIn(source);
+	const hit = memoHit(page);
+	if (hit) return hit;
+	let data: unknown;
+	const failures = readFailures();
+	if (typeof source === "function") data = await source();
+	else if (ctx.content) data = (await ctx.content.get(page.content.collection, page.content.id))?.data;
+	else return [];
+	const reviews = reviewsIn(data);
+	// Entry data that couldn't be read (null, its failure noted) isn't remembered as "no reviews".
+	if (readFailures() !== failures) return reviews;
+	if (memo.size >= MAX_CACHED) memo.delete(memo.keys().next().value as string);
+	memo.set(`${page.content.collection}:${page.content.id}`, { at: Date.now(), stamp: page.articleMeta?.modifiedTime ?? "", reviews });
+	return reviews;
+}
+
+/** The page's reviews: blocks first, then the theme's. */
+export async function pageReviews(ctx: PluginContext, page: Page, source?: EntryDataSource): Promise<Review[]> {
+	const [blocks, themed] = [await blockReviews(ctx, page, source), themeReviews(page)];
+	return [...blocks, ...themed];
+}
+
+/** Fold the page's reviews into Schema & Social's graph. Errors are logged, never fatal. */
+export async function attachPageReviews(ctx: PluginContext, page: Page, graph: { "@graph": Node[] }, origin: string): Promise<void> {
+	(await pageReviewsStep(ctx, page, origin))(graph);
+}
+
+/**
+ * Load the page's reviews now and return the step that folds them into the
+ * graph later, so Schema & Social can load them alongside its other reads.
+ * Errors are logged, never fatal.
+ */
+export async function pageReviewsStep(ctx: PluginContext, page: Page, origin: string, source?: EntryDataSource): Promise<(graph: { "@graph": Node[] }) => void> {
+	const warn = (error: unknown) => ctx.log.warn("reviews: could not attach review schema", { error: String(error) });
+	let reviews: Review[];
+	try {
+		reviews = await pageReviews(ctx, page, source);
+	} catch (error) {
+		warn(error);
+		noteReadFailure("reviews");
+		return () => {};
+	}
+	return (graph) => {
+		try {
+			attachReviews(graph, reviews, { origin });
+		} catch (error) {
+			warn(error);
+		}
+	};
+}
+
+/** page:metadata (reviews.schema): standalone JSON-LD, only when Schema & Social's graph is off. */
+export async function reviewsMetadata(event: PageMetadataEvent, ctx: PluginContext): Promise<PageMetadataContribution[] | null> {
+	if (isOn(await cachedCtxFeatures(ctx), "schema.graph")) return null;
+	const page = event.page;
+	const entry = (page as Page & { coywolf?: { entry?: { data?: unknown } } }).coywolf?.entry;
+	const data = entry?.data && typeof entry.data === "object" ? (entry.data as Record<string, unknown>) : undefined;
+	const reviews = await pageReviews(ctx, page, data && (typeof data.id !== "string" || data.id === page.content?.id) ? data : undefined);
+	if (!reviews.length) return null;
+	const origin = originOf(page.siteUrl || ctx.site.url || page.url);
+	const docs = reviewDocuments(reviews, {
+		pageUrl: pageUrl(page),
+		origin,
+		siteName: page.siteName || (await siteName(ctx)),
+		authorName: page.articleMeta?.author,
+		datePublished: page.articleMeta?.publishedTime,
+	});
+	return docs.map((graph, i) => ({ kind: "jsonld" as const, id: `coywolf-review-${i + 1}`, graph }));
+}

package/src/reviews/settings.ts

@@ -0,0 +1,26 @@
+/**
+ * The review box style (accent color + custom CSS), read outside the plugin
+ * context (Astro renderer) from D1 in the feature switches' query, sharing
+ * their per-isolate cache.
+ */
+import { invalidateFeatures, readSiteSetting, registerSiteSetting } from "../core/features.js";
+import { type ReviewStyle, STYLE_SETTING, normalizeStyle } from "./lib.js";
+
+registerSiteSetting(STYLE_SETTING);
+
+/** The last stored value and its normalized style, so a cache hit doesn't normalize again. */
+let memo: { raw: unknown; style: ReviewStyle } | null = null;
+
+export function invalidateReviewStyle(): void {
+	invalidateFeatures();
+}
+
+export async function siteReviewStyle(database = "DB"): Promise<ReviewStyle> {
+	const read = await readSiteSetting(STYLE_SETTING, database);
+	if (!read) console.error("coywolf-pack: could not read the review style");
+	const raw = read?.value ?? null;
+	if (memo && memo.raw === raw) return memo.style;
+	const style = normalizeStyle(raw);
+	memo = { raw, style };
+	return style;
+}

package/src/robots/bots.ts

@@ -0,0 +1,321 @@
+/**
+ * The crawler directory: a bundled baseline (src/robots/data/bots.json, built
+ * from Cloudflare Radar's bot directory with each robots.txt token checked
+ * against the operator's documentation) plus an overlay refreshed weekly
+ * from the Radar API (see ./radar.ts).
+ *
+ * Radar publishes user-agent *patterns*, not robots.txt tokens, so a bot that
+ * first appears through the API gets a token derived from its pattern and is
+ * marked unverified until a person checks it (the baseline is updated by
+ * hand with a source URL).
+ *
+ * No imports, so the tests can run this file under plain Node.
+ */
+
+export type BotStatus = "verified" | "unverified";
+/** What a crawler is for, from the operator's documentation (src/robots/data/verified.json → purposes). */
+export type BotPurpose = "training" | "ai-search" | "ai-assistant" | "search-engine" | "seo" | "other";
+export const PURPOSE_LABELS: Record<BotPurpose, string> = {
+	training: "AI training",
+	"ai-search": "AI search",
+	"ai-assistant": "AI assistant (fetches for a user)",
+	"search-engine": "Search engine",
+	seo: "SEO tool",
+	other: "Other",
+};
+/** How the token was confirmed: operator docs, the bot's published UA string, derived from a pattern, or checked by an admin on this site. */
+export type BotEvidence = "operator-docs" | "user-agent" | "heuristic" | "none" | "manual";
+
+export interface BotEntry {
+	slug: string;
+	name: string;
+	operator: string;
+	/** Radar category, e.g. AI_CRAWLER. */
+	category: string;
+	/** What it's for (set for preset bots and custom bots); presets use this, never the Radar category. */
+	purpose?: BotPurpose;
+	description: string;
+	/** The robots.txt product token (`User-agent:` value). */
+	token: string;
+	aliases?: string[];
+	status: BotStatus;
+	evidence: BotEvidence;
+	sourceUrl?: string;
+	/** ISO date the token was last checked against `sourceUrl`. */
+	verifiedAt?: string;
+	note?: string;
+	/** "radar" (in Cloudflare's directory), "curated" (operator-documented token Radar doesn't list) or "custom" (added on this site). */
+	origin: "radar" | "curated" | "custom";
+	/** Who verified it on this site (admin overrides). */
+	verifiedBy?: string;
+	/** The name before an admin renamed it. */
+	originalName?: string;
+	/** Set when the bot was last seen in, or has left, the Radar directory (from the weekly sync). */
+	radarSeenAt?: string;
+	delisted?: boolean;
+	/** Other Radar slugs that share this token and were merged into this entry. */
+	mergedSlugs?: string[];
+}
+
+/** A record from GET /client/v4/radar/bots. */
+export interface RadarBot {
+	slug: string;
+	name: string;
+	operator?: string;
+	category?: string;
+	description?: string;
+	kind?: string;
+	userAgentPatterns?: string[];
+}
+
+/** What the sync stores per slug (plugin storage), over the baseline. */
+export interface BotOverlay {
+	slug: string;
+	name?: string;
+	operator?: string;
+	category?: string;
+	description?: string;
+	/** Only for bots the baseline doesn't have. */
+	token?: string | null;
+	patterns?: string[];
+	firstSeenAt?: string;
+	radarSeenAt?: string;
+	delisted?: boolean;
+}
+
+export const CATEGORY_LABELS: Record<string, string> = {
+	AI_CRAWLER: "AI crawler",
+	AI_ASSISTANT: "AI assistant",
+	AI_SEARCH: "AI search",
+	SEARCH_ENGINE_CRAWLER: "Search engine",
+	SEARCH_ENGINE_OPTIMIZATION: "SEO tool",
+	MONITORING_AND_ANALYTICS: "Monitoring and analytics",
+	ADVERTISING_AND_MARKETING: "Advertising and marketing",
+	SOCIAL_MEDIA_MARKETING: "Social media marketing",
+	PAGE_PREVIEW: "Link preview",
+	FEED_FETCHER: "Feed reader",
+	ACADEMIC_RESEARCH: "Academic research",
+	SECURITY: "Security",
+	ACCESSIBILITY: "Accessibility",
+	AGGREGATOR: "Aggregator",
+	ARCHIVER: "Archiver",
+	WEBHOOKS: "Webhooks",
+	OTHER: "Other",
+};
+
+export function categoryLabel(category: string): string {
+	return (
+		CATEGORY_LABELS[category] ??
+		category
+			.toLowerCase()
+			.split("_")
+			.map((w, i) => (i === 0 ? w.charAt(0).toUpperCase() + w.slice(1) : w))
+			.join(" ")
+	);
+}
+
+const TOKEN_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
+/**
+ * Best guess at a robots.txt token from Radar's UA patterns ("Barkrowler/",
+ * "meta-externaltest/1\.1") or the bot name. Null when nothing is token-shaped.
+ */
+export function deriveToken(patterns: string[] | undefined, name: string): string | null {
+	for (const p of patterns ?? []) {
+		const t = p.replace(/\\/g, "").replace(/\/.*$/, "").trim();
+		if (TOKEN_RE.test(t) && t.toLowerCase() !== "user_agent") return t;
+	}
+	const n = name.trim();
+	return TOKEN_RE.test(n) ? n : null;
+}
+
+const clip = (s: string | undefined) => {
+	const t = (s ?? "").replace(/\s+/g, " ").trim();
+	return t.length > 240 ? `${t.slice(0, 237).trimEnd()}…` : t;
+};
+
+/** Baseline + overlay → the directory the admin shows. Bots without a token are left out. */
+export function mergeDirectory(baseline: BotEntry[], overlays: BotOverlay[]): BotEntry[] {
+	const bySlug = new Map(baseline.map((b) => [b.slug, { ...b }]));
+	for (const o of overlays) {
+		const base = bySlug.get(o.slug);
+		if (base) {
+			if (o.name) base.name = o.name;
+			if (o.operator) base.operator = o.operator;
+			if (o.category) base.category = o.category;
+			if (o.description) base.description = o.description;
+			if (o.radarSeenAt) base.radarSeenAt = o.radarSeenAt;
+			if (o.delisted) base.delisted = true;
+			continue;
+		}
+		if (!o.token) continue;
+		bySlug.set(o.slug, {
+			slug: o.slug,
+			name: o.name ?? o.slug,
+			operator: o.operator ?? "",
+			category: o.category ?? "OTHER",
+			description: o.description ?? "",
+			token: o.token,
+			status: "unverified",
+			evidence: "heuristic",
+			sourceUrl: `https://radar.cloudflare.com/bots/directory/${encodeURIComponent(o.slug)}`,
+			note: "Added from Cloudflare Radar; the token was derived from its user-agent pattern and hasn't been checked against the operator's documentation.",
+			origin: "radar",
+			radarSeenAt: o.radarSeenAt,
+			delisted: o.delisted,
+		});
+	}
+	return [...bySlug.values()].sort((a, b) => a.name.localeCompare(b.name, "en", { sensitivity: "base" }));
+}
+
+export interface RadarMergeResult {
+	/** Overlay documents to write (only ones that changed). */
+	writes: BotOverlay[];
+	added: number;
+	updated: number;
+	delisted: number;
+	total: number;
+}
+
+const sameOverlay = (a: BotOverlay | undefined, b: BotOverlay) => {
+	if (!a) return false;
+	const { radarSeenAt: _x, ...ra } = a;
+	const { radarSeenAt: _y, ...rb } = b;
+	return JSON.stringify(ra, Object.keys(ra).sort()) === JSON.stringify(rb, Object.keys(rb).sort());
+};
+
+/**
+ * Merge a Radar listing into the stored overlay. Only differences from the
+ * baseline are stored, and a document is rewritten only when its content
+ * changed (radarSeenAt alone doesn't count), so a quiet week costs no writes.
+ */
+export function mergeRadar(baseline: BotEntry[], existing: BotOverlay[], radar: RadarBot[], now: string): RadarMergeResult {
+	const base = new Map(baseline.map((b) => [b.slug, b]));
+	// Radar slugs merged into another entry (same token) count as that entry.
+	const primary = new Map<string, string>();
+	for (const b of baseline) for (const s of b.mergedSlugs ?? []) primary.set(s, b.slug);
+	const prev = new Map(existing.map((o) => [o.slug, o]));
+	const live = new Set<string>();
+	const writes: BotOverlay[] = [];
+	let added = 0;
+	let updated = 0;
+	let delisted = 0;
+
+	for (const bot of radar) {
+		if (!bot?.slug || typeof bot.slug !== "string") continue;
+		const merged = primary.get(bot.slug);
+		if (merged) {
+			live.add(merged);
+			continue;
+		}
+		live.add(bot.slug);
+		const b = base.get(bot.slug);
+		const fields = {
+			name: bot.name?.trim() || undefined,
+			operator: bot.operator?.trim() || undefined,
+			category: bot.category?.trim() || undefined,
+			description: clip(bot.description) || undefined,
+		};
+		let next: BotOverlay;
+		if (b) {
+			next = { slug: bot.slug };
+			if (fields.name && fields.name !== b.name) next.name = fields.name;
+			if (fields.operator && fields.operator !== b.operator) next.operator = fields.operator;
+			if (fields.category && fields.category !== b.category) next.category = fields.category;
+			if (fields.description && fields.description !== b.description) next.description = fields.description;
+			if (Object.keys(next).length === 1 && !prev.has(bot.slug)) continue; // Matches the baseline.
+		} else {
+			const old = prev.get(bot.slug);
+			next = {
+				slug: bot.slug,
+				...fields,
+				token: deriveToken(bot.userAgentPatterns, bot.name ?? ""),
+				patterns: (bot.userAgentPatterns ?? []).slice(0, 10),
+				firstSeenAt: old?.firstSeenAt ?? now,
+			};
+			if (!old && next.token) added++;
+		}
+		next.radarSeenAt = now;
+		const old = prev.get(bot.slug);
+		if (sameOverlay(old, next)) continue;
+		if (b) updated++;
+		writes.push(next);
+	}
+
+	// Radar-sourced bots that left the directory stay usable (robots.txt rules may name them) but are flagged.
+	for (const b of baseline) {
+		if (b.origin !== "radar" || live.has(b.slug)) continue;
+		const old = prev.get(b.slug);
+		if (old?.delisted) continue;
+		writes.push({ ...(old ?? { slug: b.slug }), delisted: true });
+		delisted++;
+	}
+	for (const o of existing) {
+		if (base.has(o.slug) || live.has(o.slug) || o.delisted) continue;
+		writes.push({ ...o, delisted: true });
+		delisted++;
+	}
+
+	return { writes, added, updated, delisted, total: live.size };
+}
+
+/** An admin's change to one directory entry (or a bot they added), kept in plugin storage. */
+export interface BotOverride {
+	/** Directory slug, or "custom-<token>" for bots added on this site. */
+	slug: string;
+	name?: string;
+	verified?: { sourceUrl: string; note?: string; at: string; by?: string };
+	custom?: {
+		token: string;
+		category: string;
+		purpose?: BotPurpose;
+		operator?: string;
+		sourceUrl?: string;
+		notes?: string;
+		createdAt: string;
+		createdBy?: string;
+	};
+}
+
+export const customSlug = (token: string) => `custom-${token.toLowerCase().replace(/[^a-z0-9._-]/g, "-")}`;
+
+/** Directory (bundled + Radar) with this site's overrides and custom bots applied. */
+export function applyOverrides(directory: BotEntry[], overrides: BotOverride[]): BotEntry[] {
+	const bySlug = new Map(directory.map((b) => [b.slug, { ...b }]));
+	for (const o of overrides) {
+		if (o.custom) {
+			bySlug.set(o.slug, {
+				slug: o.slug,
+				name: o.name || o.custom.token,
+				operator: o.custom.operator ?? "",
+				category: o.custom.category || "OTHER",
+				...(o.custom.purpose ? { purpose: o.custom.purpose } : {}),
+				description: o.custom.notes ?? "",
+				token: o.custom.token,
+				status: o.verified ? "verified" : "unverified",
+				evidence: o.verified ? "manual" : "none",
+				sourceUrl: o.verified?.sourceUrl || o.custom.sourceUrl,
+				verifiedAt: o.verified?.at,
+				verifiedBy: o.verified?.by,
+				note: o.verified?.note ?? o.custom.notes,
+				origin: "custom",
+			});
+			continue;
+		}
+		const b = bySlug.get(o.slug);
+		if (!b) continue;
+		if (o.name && o.name !== b.name) {
+			b.originalName = b.name;
+			b.name = o.name;
+		}
+		if (o.verified) {
+			b.status = "verified";
+			b.evidence = "manual";
+			b.sourceUrl = o.verified.sourceUrl;
+			b.verifiedAt = o.verified.at;
+			b.verifiedBy = o.verified.by;
+			if (o.verified.note) b.note = o.verified.note;
+		}
+	}
+	return [...bySlug.values()].sort((a, b) => a.name.localeCompare(b.name, "en", { sensitivity: "base" }));
+}