@coywolf/emdash 0.0.0-stage → 0.35.14

package/src/wpImport/pack.ts

@@ -0,0 +1,451 @@
+/**
+ * WordPress import module: finishes a WordPress → EmDash move. EmDash's own
+ * importer has no plugin hook, so this works around what it drops or misses.
+ *
+ * - While on, every save (including each entry EmDash's WordPress importer
+ *   creates) runs the converter (./convert.ts), so a prepared export
+ *   (./prepare.ts) imports straight into native blocks: heading ids, core
+ *   Details, and blocks from Coywolf's WordPress plugins. It runs before
+ *   Headings & TOC, so imported heading ids become the headings' anchors.
+ * - "Convert imported content" scans every entry (dry run first) and converts
+ *   what's already in the database, draft-aware, never overwriting an entry
+ *   that changed while it ran. Given a URL map (./urls.ts), the same scan
+ *   rewrites old `/wp-content/` URLs to media library files.
+ * - "Find old-site URLs" lists every `/wp-content/` URL of the old site left
+ *   in content, for the WordPress import page to map, import and redirect.
+ * - Video facts from WordPress (name, length, upload date, size) fill the
+ *   Videos module's per-video data where it has none, so players size
+ *   correctly and VideoObject schema has a duration without a Stream token.
+ * - Coywolf plugins: Coywolf Files records and Video Manager library data
+ *   (descriptions, posters, MP4 links) can be imported from WordPress's
+ *   database.
+ */
+import type { PluginContext, StorageCollection } from "emdash";
+import { PluginRouteError, definePluginRoute } from "emdash";
+import { z } from "zod";
+
+import { ctxFeatures, isOn, registerFeatures, requireFeature } from "../core/features.js";
+import type { PackModule } from "../core/module.js";
+import { COLLECTIONS as FILE_COLLECTIONS, type UploadDoc, invalidateSiteCache } from "../files/site.js";
+import { WORDPRESS_FILE_ID } from "../files/format.js";
+import { latestData } from "../links/store.js";
+import { parseInput } from "../shared.js";
+import { type VideoMeta, invalidatePublicConfig, metaStore, SETTINGS as VIDEO_SETTINGS } from "../videos/store.js";
+import { type ConvertOptions, type VideoFact, convertEntryData, mightNeedConversion } from "./convert.js";
+import { type ImportDefaults, defaultsFromWordPress, parseFileRows } from "./sources.js";
+import { findSiteUrls, rewriteSiteUrls, siteUrlPattern } from "./urls.js";
+
+export const F = { main: "wpImport" } as const;
+
+const FEATURES = [
+	{
+		id: F.main,
+		label: "WordPress import",
+		description:
+			"Tools to finish a move from WordPress: keep heading ids, reusable blocks and Details blocks, credit co-authors and guest authors, restore category and page parents, point old /wp-content/ URLs at the media library, and bring over redirects. Blocks from Coywolf's WordPress plugins become Coywolf Pack blocks as content is imported or saved.",
+		default: false,
+	},
+];
+registerFeatures(FEATURES);
+
+export const DEFAULTS_SETTING = "wpImportDefaults";
+
+function normalizeDefaults(value: unknown): ImportDefaults {
+	if (!value || typeof value !== "object") return {};
+	const v = value as ImportDefaults;
+	return { video: v.video && typeof v.video === "object" ? v.video : undefined, files: v.files && typeof v.files === "object" ? v.files : undefined };
+}
+
+async function convertOptions(ctx: PluginContext): Promise<ConvertOptions> {
+	const d = normalizeDefaults(await ctx.settings.get(DEFAULTS_SETTING));
+	const features = await ctxFeatures(ctx);
+	// Custom Blocks that are off aren't converted to: their markers stay HTML until the block is turned on.
+	const customBlocks = {
+		note: isOn(features, "customBlocks.note"),
+		details: isOn(features, "customBlocks.details"),
+		disclosure: isOn(features, "customBlocks.disclosure"),
+		quote: isOn(features, "customBlocks.quote"),
+		testimonial: isOn(features, "customBlocks.testimonial"),
+		podcast: isOn(features, "customBlocks.podcast"),
+	};
+	return { videoDefaults: d.video, fileDefaults: d.files, customBlocks };
+}
+
+// ── Video facts ──────────────────────────────────────────────────
+
+/**
+ * Fill in the Videos module's per-video data from WordPress where it has
+ * none. Stream's own data (library refresh, webhook) replaces it later.
+ * Returns how many videos were added.
+ */
+async function seedVideos(ctx: PluginContext, facts: VideoFact[]): Promise<number> {
+	const store = (ctx.storage as Record<string, StorageCollection<VideoMeta> | undefined>).videosMeta ? metaStore(ctx) : null;
+	if (!store || !facts.length) return 0;
+	const byUid = new Map<string, VideoFact>();
+	for (const f of facts) byUid.set(f.uid, { ...byUid.get(f.uid), ...Object.fromEntries(Object.entries(f).filter(([, v]) => v !== undefined)) } as VideoFact);
+	const uids = [...byUid.keys()].slice(0, 50);
+	const existing = await store.getMany(uids);
+	const add: Array<{ id: string; data: VideoMeta }> = [];
+	let host: string | undefined;
+	for (const uid of uids) {
+		const fact = byUid.get(uid) as VideoFact;
+		host ??= fact.host;
+		if (existing.has(uid)) continue;
+		const doc: VideoMeta = { uid, updatedAt: new Date().toISOString() };
+		if (fact.name) doc.name = fact.name;
+		if (fact.duration) doc.duration = fact.duration;
+		if (fact.created) doc.created = fact.created;
+		if (fact.width && fact.height) {
+			doc.width = fact.width;
+			doc.height = fact.height;
+		}
+		add.push({ id: uid, data: doc });
+	}
+	if (add.length) await store.putMany(add);
+	// The customer subdomain, when the Videos page hasn't learned one yet.
+	if (host && !(await ctx.settings.get<string>(VIDEO_SETTINGS.host))) {
+		await ctx.settings.set(VIDEO_SETTINGS.host, host);
+		invalidatePublicConfig();
+	}
+	return add.length;
+}
+
+// ── Save hook ────────────────────────────────────────────────────
+
+async function beforeSave(event: { content: Record<string, unknown>; collection: string }, ctx: PluginContext) {
+	if (!event.content || !mightNeedConversion(event.content)) return undefined;
+	const result = convertEntryData(event.content, await convertOptions(ctx));
+	if (result.videos.length) {
+		try {
+			await seedVideos(ctx, result.videos);
+		} catch (error) {
+			ctx.log.warn("WordPress import: could not record video details", { error: String(error) });
+		}
+	}
+	if (!result.changed) return undefined;
+	ctx.log.info("WordPress import: converted blocks", { collection: event.collection, changes: result.changes.length });
+	return result.value;
+}
+
+// ── Converting stored content ────────────────────────────────────
+
+interface ScanState {
+	collections: string[];
+	index: number;
+	cursor: string | null;
+}
+
+export interface ScanEntry {
+	collection: string;
+	id: string;
+	title: string;
+	status: string;
+	/** "coywolf-video" → 2, "anchor" → 14, … */
+	changes: Record<string, number>;
+	result?: "updated" | "published" | "draft" | "conflict" | "failed";
+	error?: string;
+}
+
+const stateInput = z.object({ collections: z.array(z.string().max(100)).max(200), index: z.number().int().min(0), cursor: z.string().max(2000).nullable() }).nullish();
+
+const scanInput = z.object({
+	apply: z.boolean(),
+	state: stateInput,
+	/** Old-site URL → media library URL, to rewrite in content (see ./urls.ts). */
+	urlMap: z.record(z.string().max(2000), z.string().max(2000)).optional(),
+});
+
+const findInput = z.object({
+	hosts: z.array(z.string().max(253)).max(50),
+	prefixes: z.array(z.string().max(200).regex(/^(?:\/[\w.~-]+){1,3}$/)).max(5).optional(),
+	state: stateInput,
+});
+
+/** Rewrite mapped URLs in an entry's Portable Text and text fields (media fields are left to EmDash). */
+function rewriteEntryUrls(data: Record<string, unknown>, urlMap: Record<string, string>): { value: Record<string, unknown>; count: number } {
+	let out: Record<string, unknown> | null = null;
+	let count = 0;
+	for (const [field, value] of Object.entries(data)) {
+		if (typeof value !== "string" && !Array.isArray(value)) continue;
+		const r = rewriteSiteUrls(value, urlMap);
+		if (!r.count) continue;
+		out ??= { ...data };
+		out[field] = r.value;
+		count += r.count;
+	}
+	return { value: out ?? data, count };
+}
+
+type Content = NonNullable<PluginContext["content"]>;
+type Writable = Content & Required<Pick<Content, "update">>;
+
+const versionOf = (item: { version?: number; updatedAt?: string; draftRevisionId?: string | null }) =>
+	`${item.version ?? ""}|${item.updatedAt ?? ""}|${item.draftRevisionId ?? ""}`;
+
+const PAGE_MS = 12_000;
+
+async function scan(ctx: PluginContext, apply: boolean, state: ScanState | null, urlMap: Record<string, string> | null = null) {
+	if (!ctx.content || !ctx.schema) throw PluginRouteError.internal("Content access is unavailable.");
+	if (apply && !ctx.content.update) throw PluginRouteError.internal("WordPress import needs the content:write capability.");
+	const content = ctx.content as Writable;
+	const schemas = await ctx.schema.listCollections();
+	const info = new Map(schemas.map((c) => [c.slug, c]));
+	const collections = state?.collections ?? schemas.filter((c) => c.fields.some((f) => f.type === "portableText")).map((c) => c.slug);
+	let index = state?.index ?? 0;
+	let cursor = state?.cursor ?? null;
+	const opts = await convertOptions(ctx);
+	const entries: ScanEntry[] = [];
+	const leftovers: Record<string, number> = {};
+	let scanned = 0;
+	let videosAdded = 0;
+	const started = Date.now();
+
+	while (index < collections.length && Date.now() - started < PAGE_MS) {
+		const collection = collections[index] as string;
+		const page = await content.list(collection, { limit: 25, ...(cursor ? { cursor } : {}) });
+		for (const item of page.items) {
+			scanned++;
+			const data = await latestData(ctx, collection, item as unknown as { id: string; data: Record<string, unknown>; draftRevisionId?: string | null });
+			const convertible = mightNeedConversion(data);
+			const rewritable = urlMap !== null && JSON.stringify(data).includes("/wp-content/");
+			if (!convertible && !rewritable) continue;
+			const result = convertible ? convertEntryData(data, opts) : { value: data, changed: false, changes: [], videos: [], leftovers: {} };
+			for (const [k, v] of Object.entries(result.leftovers)) leftovers[k] = (leftovers[k] ?? 0) + v;
+			const urls = rewritable ? rewriteEntryUrls(result.value, urlMap) : { value: result.value, count: 0 };
+			if (!result.changed && !urls.count) continue;
+			result.value = urls.value;
+			const changes: Record<string, number> = {};
+			for (const c of result.changes) changes[c.to] = (changes[c.to] ?? 0) + 1;
+			if (urls.count) changes["media URL"] = urls.count;
+			const schema = info.get(collection);
+			const titleField = schema?.titleField ?? "title";
+			const title = String(data[titleField] ?? data.title ?? item.slug ?? item.id).slice(0, 200);
+			const entry: ScanEntry = { collection, id: item.id, title, status: String(item.status ?? ""), changes };
+			entries.push(entry);
+			if (!apply) continue;
+			try {
+				const patch: Record<string, unknown> = {};
+				for (const [k, v] of Object.entries(result.value)) if (v !== data[k]) patch[k] = v;
+				const fresh = await content.get(collection, item.id);
+				if (!fresh || versionOf(fresh) !== versionOf(item)) {
+					entry.result = "conflict";
+					entry.error = "Changed while converting. Run it again.";
+					continue;
+				}
+				const hadDraft = Boolean(item.draftRevisionId);
+				await content.update(collection, item.id, patch);
+				entry.result = "updated";
+				if (schema?.supports.includes("revisions") && item.status === "published") {
+					entry.result = "draft";
+					if (!hadDraft && content.getVersioned && content.publish) {
+						const versioned = await content.getVersioned(collection, item.id);
+						// Publish only the draft this update made: exactly one version after the one read.
+						if (versioned && versioned.item.version === (fresh.version ?? 0) + 1) {
+							await content.publish(collection, item.id, { _rev: versioned._rev });
+							entry.result = "published";
+						}
+					}
+				}
+				videosAdded += await seedVideos(ctx, result.videos).catch(() => 0);
+			} catch (error) {
+				entry.result = "failed";
+				entry.error = String(error).slice(0, 300);
+				ctx.log.error("WordPress import: convert failed", { collection, id: item.id, error: String(error) });
+			}
+		}
+		if (page.hasMore && page.cursor) cursor = page.cursor;
+		else {
+			index++;
+			cursor = null;
+		}
+	}
+	const done = index >= collections.length;
+	return {
+		done,
+		scanned,
+		entries,
+		leftovers,
+		videosAdded,
+		state: done ? null : { collections, index, cursor },
+		progress: done ? "Done" : `Collection ${Math.min(index + 1, collections.length)} of ${collections.length}`,
+	};
+}
+
+/** Count the old site's `/wp-content/` URLs in every entry (latest draft included), a page at a time. */
+async function findUrls(ctx: PluginContext, hosts: string[], prefixes: string[], state: ScanState | null) {
+	if (!ctx.content || !ctx.schema) throw PluginRouteError.internal("Content access is unavailable.");
+	const schemas = await ctx.schema.listCollections();
+	const collections = state?.collections ?? schemas.map((c) => c.slug);
+	let index = state?.index ?? 0;
+	let cursor = state?.cursor ?? null;
+	const re = siteUrlPattern(hosts, prefixes);
+	const urls = new Map<string, number>();
+	let scanned = 0;
+	const started = Date.now();
+	while (index < collections.length && Date.now() - started < PAGE_MS) {
+		const collection = collections[index] as string;
+		const page = await ctx.content.list(collection, { limit: 25, ...(cursor ? { cursor } : {}) });
+		for (const item of page.items) {
+			scanned++;
+			const data = await latestData(ctx, collection, item as unknown as { id: string; data: Record<string, unknown>; draftRevisionId?: string | null });
+			if (JSON.stringify(data).includes("/wp-content/")) findSiteUrls(data, re, urls);
+		}
+		if (page.hasMore && page.cursor) cursor = page.cursor;
+		else {
+			index++;
+			cursor = null;
+		}
+	}
+	const done = index >= collections.length;
+	return {
+		done,
+		scanned,
+		urls: Object.fromEntries([...urls].slice(0, 20_000)),
+		state: done ? null : { collections, index, cursor },
+		progress: done ? "Done" : `Collection ${Math.min(index + 1, collections.length)} of ${collections.length}`,
+	};
+}
+
+// ── Coywolf Files records ────────────────────────────────────────
+
+const fileRow = z.object({
+	file_id: z.string().regex(WORDPRESS_FILE_ID, "file_id must be the 20-character Coywolf Files id."),
+	object_key: z
+		.string()
+		.min(1)
+		.max(512)
+		.regex(/^[A-Za-z0-9][A-Za-z0-9._\/-]*$/, "object_key must be a plain bucket key.")
+		.refine((k) => !k.split("/").includes(".."), "object_key must be a plain bucket key."),
+	filename: z.string().min(1).max(255),
+	mime: z.string().max(150).optional().default("application/octet-stream"),
+	size: z.coerce.number().int().min(0),
+	downloads: z.coerce.number().int().min(0).optional().default(0),
+	created: z.string().max(40).optional().default(""),
+});
+
+const wpDate = (value: string) => {
+	const iso = value && !value.startsWith("0000") ? new Date(`${value.replace(" ", "T")}Z`) : null;
+	return iso && !Number.isNaN(iso.getTime()) ? iso.toISOString() : new Date().toISOString();
+};
+
+// ── Video Manager library data ───────────────────────────────────
+
+const videoLibraryInput = z.object({
+	descriptions: z.record(z.string(), z.string().max(5000)).optional(),
+	posters: z.record(z.string(), z.object({ mode: z.string().optional(), time: z.coerce.number().optional(), image_url: z.string().max(2000).optional() }).passthrough()).optional(),
+	downloads: z.record(z.string(), z.string().max(2000)).optional(),
+});
+
+const UID = /^[0-9a-f]{32}$/;
+
+export function wpImportPack(): PackModule {
+	return {
+		id: "wpImport",
+		label: "WordPress import",
+		features: FEATURES,
+		capabilities: ["content:read", "content:write", "schema:read"],
+		adminPages: [{ path: "/wordpress-import", label: "WordPress import", icon: "upload-simple" }],
+		hooks: { "content:beforeSave": beforeSave },
+		routes: {
+			"wpImport/settings": {
+				permission: "plugins:manage" as const,
+				handler: async (ctx: PluginContext) => ({ defaults: normalizeDefaults(await ctx.settings.get(DEFAULTS_SETTING)) }),
+			},
+			"wpImport/settings/save": definePluginRoute({
+				permission: "plugins:manage",
+				methods: ["POST"],
+				request: { body: "json" },
+				handler: async (ctx) => {
+					const input = parseInput(z.object({ cvm: z.unknown().optional(), files: z.unknown().optional() }), ctx.input);
+					const defaults = defaultsFromWordPress(input.cvm, input.files);
+					await ctx.settings.set(DEFAULTS_SETTING, defaults);
+					return { defaults };
+				},
+			}),
+			"wpImport/scan": definePluginRoute({
+				permission: "plugins:manage",
+				methods: ["POST"],
+				request: { body: "json", maxBytes: 6 * 1024 * 1024 },
+				handler: async (ctx) => {
+					await requireFeature(ctx, F.main);
+					const input = parseInput(scanInput, ctx.input ?? {});
+					const urlMap = input.urlMap && Object.keys(input.urlMap).length ? input.urlMap : null;
+					return scan(ctx, input.apply, input.state ?? null, urlMap);
+				},
+			}),
+			"wpImport/urls": definePluginRoute({
+				permission: "plugins:manage",
+				methods: ["POST"],
+				request: { body: "json" },
+				handler: async (ctx) => {
+					await requireFeature(ctx, F.main);
+					const input = parseInput(findInput, ctx.input ?? {});
+					return findUrls(ctx, input.hosts, input.prefixes ?? [], input.state ?? null);
+				},
+			}),
+			"wpImport/files": definePluginRoute({
+				permission: "plugins:manage",
+				methods: ["POST"],
+				request: { body: "json", maxBytes: 1024 * 1024 },
+				handler: async (ctx) => {
+					await requireFeature(ctx, F.main);
+					const { text } = parseInput(z.object({ text: z.string().min(1).max(1_000_000) }), ctx.input);
+					let rows: Array<Record<string, string>>;
+					try {
+						rows = parseFileRows(text);
+					} catch {
+						throw PluginRouteError.badRequest("Paste the tab-separated output of the query, or a JSON array.");
+					}
+					const uploads = (ctx.storage as Record<string, StorageCollection<UploadDoc> | undefined>)[FILE_COLLECTIONS.uploads];
+					const counts = (ctx.storage as Record<string, StorageCollection<{ downloads: number; lastDownload?: string }> | undefined>)[FILE_COLLECTIONS.counts];
+					if (!uploads || !counts) throw PluginRouteError.badRequest("Turn on File Downloads first.");
+					const added: string[] = [];
+					const errors: Array<{ row: number; error: string }> = [];
+					for (const [i, raw] of rows.slice(0, 2000).entries()) {
+						const parsed = fileRow.safeParse(raw);
+						if (!parsed.success) {
+							errors.push({ row: i + 1, error: parsed.error.issues[0]?.message ?? "Invalid row" });
+							continue;
+						}
+						const r = parsed.data;
+						await uploads.put(r.file_id, { id: r.file_id, key: r.object_key, name: r.filename, size: r.size, type: r.mime || "application/octet-stream", uploadedAt: wpDate(r.created), status: "ready" });
+						if (r.downloads > 0 && !(await counts.get(r.file_id))) await counts.put(r.file_id, { downloads: r.downloads });
+						invalidateSiteCache(r.file_id);
+						added.push(r.file_id);
+					}
+					return { added: added.length, ids: added, errors };
+				},
+			}),
+			"wpImport/videos": definePluginRoute({
+				permission: "plugins:manage",
+				methods: ["POST"],
+				request: { body: "json", maxBytes: 1024 * 1024 },
+				handler: async (ctx) => {
+					await requireFeature(ctx, F.main);
+					if (!(ctx.storage as Record<string, unknown>).videosMeta) throw PluginRouteError.badRequest("Turn on Videos first.");
+					const input = parseInput(videoLibraryInput, ctx.input);
+					const store = metaStore(ctx);
+					const uids = new Set([...Object.keys(input.descriptions ?? {}), ...Object.keys(input.posters ?? {}), ...Object.keys(input.downloads ?? {})].filter((u) => UID.test(u)));
+					let updated = 0;
+					for (const uid of uids) {
+						const prev = (await store.get(uid)) ?? { uid };
+						const next: VideoMeta = { ...prev, uid, updatedAt: new Date().toISOString() };
+						const description = input.descriptions?.[uid]?.trim();
+						if (description) next.description = description;
+						const poster = input.posters?.[uid];
+						if (poster?.mode === "image" && poster.image_url && /^https?:\/\//i.test(poster.image_url)) next.posterImage = poster.image_url;
+						else if (poster?.mode === "timestamp" && typeof poster.time === "number" && poster.time > 0) next.posterTime = poster.time;
+						const download = input.downloads?.[uid];
+						if (download && /^https:\/\/\S+\.mp4$/i.test(download)) {
+							next.downloadUrl = download;
+							next.downloadStatus = "ready";
+						}
+						await store.put(uid, next);
+						updated++;
+					}
+					return { updated };
+				},
+			}),
+		},
+	};
+}

package/src/wpImport/parents.ts

@@ -0,0 +1,202 @@
+/**
+ * Category and page parents from a WordPress export (WXR). EmDash's importer
+ * creates every category flat (no parent) and drops pages' parents, so
+ * WordPress's hierarchical URLs (/news/seo/a-post/, /apps/coywolf-seo/) are
+ * lost. The WordPress import page reads them here, then:
+ *
+ * - categories: sets each term's parent through EmDash's own taxonomy API
+ *   (plugins can read terms but not update them), after a dry run
+ *   (planCategoryParents);
+ * - pages: EmDash entries have no parent, so it prints a `pageParents` map
+ *   for coywolfPlugin() (used by the `{pagepath}` URL token).
+ *
+ * In the export, `<wp:category>` holds `<wp:category_nicename>` (slug) and
+ * `<wp:category_parent>` (the parent's slug); `<wp:term>` entries with
+ * `<wp:term_taxonomy>category</wp:term_taxonomy>` use `<wp:term_slug>` and
+ * `<wp:term_parent>`. Pages are `<item>`s with `<wp:post_type>page</wp:post_type>`
+ * and `<wp:post_parent>` (the parent's post id; 0 = none).
+ *
+ * Pure, no imports: runs in the admin (browser), a Node script and tests.
+ */
+
+const CDATA = /<!\[CDATA\[([\s\S]*?)\]\]>/g;
+
+function text(body: string): string {
+	if (!body.includes("<![CDATA[")) return body.replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/&#039;/g, "'").replace(/&amp;/g, "&");
+	let out = "";
+	for (const m of body.matchAll(CDATA)) out += m[1];
+	return out;
+}
+
+function tag(block: string, name: string): string {
+	const m = block.match(new RegExp(`<${name}>([\\s\\S]*?)</${name}>`));
+	return m ? text(m[1] as string).trim() : "";
+}
+
+/** WordPress stores slugs percent-encoded (non-ASCII); EmDash keeps the decoded form. */
+function slugText(raw: string): string {
+	try {
+		return decodeURIComponent(raw);
+	} catch {
+		return raw;
+	}
+}
+
+/** WordPress stores term names HTML-escaped (`Tips &amp; Tricks`). */
+const decodeName = (name: string) => name.replace(/&quot;/g, '"').replace(/&#0?39;/g, "'").replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&amp;/g, "&");
+
+export interface WxrCategory {
+	slug: string;
+	name: string;
+	/** The parent's slug, "" for a top-level category. */
+	parent: string;
+}
+
+/** Every category in an export, with its parent's slug. */
+export function wxrCategories(xml: string): WxrCategory[] {
+	const out = new Map<string, WxrCategory>();
+	for (const m of xml.matchAll(/<wp:category>([\s\S]*?)<\/wp:category>/g)) {
+		const block = m[1] as string;
+		const slug = slugText(tag(block, "wp:category_nicename"));
+		if (slug && !out.has(slug)) out.set(slug, { slug, name: decodeName(tag(block, "wp:cat_name")) || slug, parent: slugText(tag(block, "wp:category_parent")) });
+	}
+	for (const m of xml.matchAll(/<wp:term>([\s\S]*?)<\/wp:term>/g)) {
+		const block = m[1] as string;
+		if (tag(block, "wp:term_taxonomy") !== "category") continue;
+		const slug = slugText(tag(block, "wp:term_slug"));
+		if (slug && !out.has(slug)) out.set(slug, { slug, name: decodeName(tag(block, "wp:term_name")) || slug, parent: slugText(tag(block, "wp:term_parent")) });
+	}
+	return [...out.values()];
+}
+
+export interface WxrPage {
+	id: number;
+	slug: string;
+	title: string;
+	/** The parent page's slug, "" for a top-level page (or a parent not in the export). */
+	parent: string;
+}
+
+/** Pages in an export (not trashed or auto-drafts), with their parent page's slug. */
+export function wxrPages(xml: string): WxrPage[] {
+	const raw: Array<{ id: number; slug: string; title: string; parentId: number }> = [];
+	for (const m of xml.matchAll(/<item>([\s\S]*?)<\/item>/g)) {
+		const item = m[1] as string;
+		if (tag(item, "wp:post_type") !== "page") continue;
+		const status = tag(item, "wp:status");
+		if (status === "trash" || status === "auto-draft" || status === "inherit") continue;
+		const slug = slugText(tag(item, "wp:post_name"));
+		if (!slug) continue;
+		raw.push({ id: Number(tag(item, "wp:post_id")) || 0, slug, title: tag(item, "title"), parentId: Number(tag(item, "wp:post_parent")) || 0 });
+	}
+	const slugById = new Map(raw.filter((p) => p.id).map((p) => [p.id, p.slug]));
+	return raw.map((p) => ({ id: p.id, slug: p.slug, title: p.title, parent: (p.parentId && slugById.get(p.parentId)) || "" }));
+}
+
+/** slug → parent slug, for the entries that have a parent (and aren't their own parent). */
+export function parentsMap(items: Array<{ slug: string; parent: string }>): Record<string, string> {
+	const out: Record<string, string> = {};
+	for (const item of items) if (item.parent && item.parent !== item.slug && !Object.hasOwn(out, item.slug)) out[item.slug] = item.parent;
+	return out;
+}
+
+/** A term as EmDash's taxonomy API lists it (flattened). */
+export interface SiteTerm {
+	id: string;
+	slug: string;
+	label?: string;
+	/** The parent's translation_group (or row id), null at the top level. */
+	parentId: string | null;
+	translationGroup?: string | null;
+	locale?: string;
+	children?: SiteTerm[];
+}
+
+/** EmDash lists hierarchical taxonomies as a tree: flatten it (first row per slug wins). */
+export function flattenTerms(terms: SiteTerm[]): SiteTerm[] {
+	const out = new Map<string, SiteTerm>();
+	const walk = (nodes: SiteTerm[], depth: number) => {
+		if (depth > 64) return;
+		for (const node of nodes) {
+			if (!out.has(node.slug)) out.set(node.slug, node);
+			if (node.children?.length) walk(node.children, depth + 1);
+		}
+	};
+	walk(terms, 0);
+	return [...out.values()];
+}
+
+export interface ParentPlan {
+	slug: string;
+	name: string;
+	/** The parent WordPress had. */
+	parent: string;
+	/** The parent on the site now ("" = none). */
+	current: string;
+	/** The site's term id (to update) and the parent term's id (to set). */
+	termId?: string;
+	parentTermId?: string;
+	/** set: the parent will be set; done: already right; missing: the term or its parent isn't on the site. */
+	action: "set" | "done" | "missing";
+	note?: string;
+	result?: string;
+}
+
+/**
+ * What restoring WordPress's category parents would change, per category
+ * with a parent in WordPress. Categories that are already right are "done",
+ * so running it again changes nothing.
+ */
+export function planCategoryParents(categories: WxrCategory[], siteTerms: SiteTerm[]): ParentPlan[] {
+	const terms = flattenTerms(siteTerms);
+	const bySlug = new Map(terms.map((t) => [t.slug, t]));
+	const slugByRef = new Map<string, string>();
+	for (const t of terms) {
+		slugByRef.set(t.id, t.slug);
+		if (t.translationGroup && !slugByRef.has(t.translationGroup)) slugByRef.set(t.translationGroup, t.slug);
+	}
+	const plans: ParentPlan[] = [];
+	for (const c of categories) {
+		if (!c.parent || c.parent === c.slug) continue;
+		const term = bySlug.get(c.slug);
+		const parent = bySlug.get(c.parent);
+		const current = term?.parentId ? (slugByRef.get(term.parentId) ?? term.parentId) : "";
+		const plan: ParentPlan = { slug: c.slug, name: c.name, parent: c.parent, current, termId: term?.id, parentTermId: parent?.id, action: "set" };
+		if (!term) {
+			plan.action = "missing";
+			plan.note = `No category “${c.slug}” on the site`;
+		} else if (!parent) {
+			plan.action = "missing";
+			plan.note = `The parent “${c.parent}” isn't on the site`;
+		} else if (current === c.parent) {
+			plan.action = "done";
+		}
+		plans.push(plan);
+	}
+	// Parents before children, so each update finds its parent in place.
+	const depth = (slug: string) => {
+		let d = 0;
+		const seen = new Set<string>();
+		let up = categories.find((c) => c.slug === slug)?.parent;
+		while (up && !seen.has(up) && d < 64) {
+			seen.add(up);
+			d++;
+			up = categories.find((c) => c.slug === up)?.parent;
+		}
+		return d;
+	};
+	return plans.sort((a, b) => depth(a.slug) - depth(b.slug) || a.slug.localeCompare(b.slug));
+}
+
+/** A ready-to-paste coywolfPlugin() option, e.g. `pageParents: { "coywolf-seo": "apps" },`. */
+export function optionSnippet(name: string, map: Record<string, string>): string {
+	const entries = Object.entries(map).sort((a, b) => a[1].localeCompare(b[1]) || a[0].localeCompare(b[0]));
+	if (!entries.length) return `${name}: {},`;
+	return `${name}: {\n${entries.map(([k, v]) => `\t${JSON.stringify(k)}: ${JSON.stringify(v)},`).join("\n")}\n},`;
+}
+
+/** The same as a `termParents` option for one taxonomy: `termParents: { category: { … } },`. */
+export function termParentsSnippet(taxonomy: string, map: Record<string, string>): string {
+	const inner = optionSnippet(taxonomy, map).replace(/,$/, "").replace(/\n/g, "\n\t");
+	return `termParents: {\n\t${inner},\n},`;
+}