domma-cms 1.7.0 → 1.7.2

package/server/services/wpImport/plan.js

@@ -0,0 +1,549 @@
+/**
+ * What an import will do - decided before anything is written, so the
+ * preview shows exactly what the run does. PURE: the site's state comes in as
+ * data (see `planImport`), nothing is read or written here.
+ *
+ * Every item gets one action:
+ *   create  - new here
+ *   rename  - new, but its address is taken by something the site already has
+ *   update  - made by an earlier run of this import, unchanged here since: refreshed
+ *   keep    - made by an earlier run, but edited here since: left alone unless
+ *             the person chooses "overwrite"
+ *   skip    - not imported, with the reason
+ *
+ * Addresses: a page keeps its WordPress address where the permalink is known
+ * (/about/team), else its parent chain of slugs. Posts go to the Blog's base
+ * (/blog/<slug>), as Blog posts or - without the Blog - as pages there.
+ *
+ * @module services/wpImport/plan
+ */
+import {detectBuilder, findShortcodes} from './convert.js';
+import {hostOf} from './wxr.js';
+import {FETCH_PORTS, portOf} from './fetch.js';
+
+export const MEDIA_EXTENSIONS = new Set(['jpg', 'jpeg', 'png', 'gif', 'webp', 'avif', 'bmp', 'ico', 'tif', 'tiff',
+    'pdf', 'txt', 'csv', 'doc', 'docx', 'xls', 'xlsx', 'mp4', 'webm', 'ogv', 'mp3', 'ogg', 'wav']);
+
+/** WordPress statuses -> page status (pages have published / draft). */
+const PAGE_STATUS = {publish: 'published', draft: 'draft', pending: 'draft', private: 'draft', future: 'draft'};
+/** WordPress statuses -> Blog post status. */
+const POST_STATUS = {publish: 'published', draft: 'draft', pending: 'draft', private: 'draft', future: 'scheduled'};
+
+/** "Über uns!" -> "uber-uns"; '' when nothing usable is left. */
+export function slugify(s) {
+    return String(s ?? '').normalize('NFKD').replace(/[̀-ͯ]/g, '').toLowerCase()
+        .replace(/['’]/g, '').replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 80);
+}
+
+/** "/About/Team/" -> "/about/team"; "" -> "/". */
+export function normalisePath(p) {
+    let s = String(p ?? '').split('#')[0].split('?')[0];
+    try { s = decodeURI(s); } catch { /* keep */ }
+    s = `/${s}`.replace(/\/{2,}/g, '/');
+    if (s.length > 1) s = s.replace(/\/+$/, '');
+    return s.toLowerCase();
+}
+
+/** The site's own path prefix (WordPress in a sub-folder: https://x.com/wp -> "/wp"). */
+export function basePathOf(site) {
+    try {
+        const u = new URL(site.baseBlogUrl || site.baseSiteUrl || site.link);
+        const p = normalisePath(u.pathname);
+        return p === '/' ? '' : p;
+    } catch { return ''; }
+}
+
+/**
+ * The path part of an address on the old site, relative to it - or null when
+ * the address is elsewhere, or is only a query (?p=12).
+ */
+export function oldPathOf(url, site) {
+    const raw = String(url || '').trim();
+    if (!raw) return null;
+    let u;
+    try { u = new URL(raw, site.baseSiteUrl || site.link || 'https://wordpress.invalid'); } catch { return null; }
+    if (!site.hosts.includes(u.hostname.toLowerCase())) return null;
+    if (u.search && /[?&](p|page_id|attachment_id|cat|tag)=/.test(u.search)) return null;
+    return normalisePath(u.pathname);
+}
+
+/** Strip the WordPress folder: "/wp/about" -> "/about" when WordPress lived in /wp. */
+function relative(path, base) {
+    if (base && (path === base || path.startsWith(`${base}/`))) return path.slice(base.length) || '/';
+    return path;
+}
+
+/** Each segment slug-safe; '' segments dropped. */
+function cleanPath(path) {
+    const segs = String(path).split('/').map(slugify).filter(Boolean);
+    return segs.length ? `/${segs.join('/')}` : '/';
+}
+
+/** The uploads-relative path of a media address: ".../wp-content/uploads/2019/05/a.jpg" -> "2019/05/a.jpg". */
+export function uploadsPath(url) {
+    const m = /\/wp-content\/uploads\/(.+)$/i.exec(String(url || '').split(/[?#]/)[0]);
+    if (!m) return '';
+    try { return decodeURIComponent(m[1]); } catch { return m[1]; }
+}
+
+/** "2019/05/a-300x200.jpg" -> "2019/05/a.jpg"; "-scaled" and "-rotated" (WordPress 5.3+) too. */
+export function originalUploadsPath(rel) {
+    return String(rel || '').replace(/-(\d+x\d+|scaled|rotated|e\d{10,13})(?=\.[a-z0-9]+$)/i, '');
+}
+
+/** A media file name: safe characters only. */
+export function mediaName(fromPath, id) {
+    const base = String(fromPath || '').split('/').pop() || '';
+    const dot = base.lastIndexOf('.');
+    const ext = dot > 0 ? base.slice(dot + 1).toLowerCase().replace(/[^a-z0-9]/g, '') : '';
+    let stem = (dot > 0 ? base.slice(0, dot) : base).normalize('NFKD').replace(/[̀-ͯ]/g, '')
+        .replace(/[^a-zA-Z0-9._-]+/g, '-').replace(/^[-.]+|[-.]+$/g, '').slice(0, 100);
+    if (!stem) stem = `wp-media-${id}`;
+    return ext ? `${stem}.${ext}` : stem;
+}
+
+/** name.jpg, name-2.jpg, name-3.jpg… - the first not in `taken`. */
+export function freeName(name, taken) {
+    const lower = (s) => s.toLowerCase();
+    if (!taken.has(lower(name))) return name;
+    const dot = name.lastIndexOf('.');
+    const stem = dot > 0 ? name.slice(0, dot) : name;
+    const ext = dot > 0 ? name.slice(dot) : '';
+    for (let n = 2; n < 10_000; n++) {
+        const next = `${stem}-${n}${ext}`;
+        if (!taken.has(lower(next))) return next;
+    }
+    return `${stem}-${Date.now()}${ext}`;
+}
+
+/** /about, /about-2, /about-3… - the first address not in `taken`. */
+export function freePath(path, taken) {
+    if (!taken.has(path)) return path;
+    for (let n = 2; n < 10_000; n++) {
+        const next = `${path}-${n}`;
+        if (!taken.has(next)) return next;
+    }
+    return `${path}-${Date.now()}`;
+}
+
+/** Yoast / Rank Math title with its %%variables%% filled or dropped; '' when only the defaults are left. */
+export function seoTitle(raw, title) {
+    let s = String(raw || '').trim();
+    if (!s) return '';
+    s = s.replace(/%%title%%|%title%/gi, title).replace(/%%[a-z_]+%%|%[a-z_]+%/gi, '')
+        .replace(/\s+([|\-–—·:])\s*$/g, '').replace(/^\s*[|\-–—·:]\s+/g, '').replace(/\s{2,}/g, ' ').trim();
+    return s === title ? '' : s.slice(0, 200);
+}
+
+/** The SEO fields WordPress SEO plugins left, as Domma's page `seo:` block. */
+export function seoFields(item) {
+    const m = item.meta || {};
+    const title = seoTitle(m._yoast_wpseo_title || m.rank_math_title, item.title);
+    const description = String(m._yoast_wpseo_metadesc || m.rank_math_description || '').replace(/%%[a-z_]+%%|%[a-z_]+%/gi, '').replace(/\s+/g, ' ').trim().slice(0, 400);
+    const noindex = m['_yoast_wpseo_meta-robots-noindex'] === '1' || /\bnoindex\b/.test(String(m.rank_math_robots || ''));
+    const focus = String(m._yoast_wpseo_focuskw || m.rank_math_focus_keyword || '').split(',')[0].trim().slice(0, 100);
+    return {
+        ...(title && {title}),
+        ...(description && {description}),
+        ...(noindex && {noindex: true}),
+        ...(focus && {focus})
+    };
+}
+
+/** A WordPress date ("2019-05-06 10:00:00", GMT) as ISO, or ''. */
+export function isoDate(gmt, local) {
+    for (const v of [gmt, local]) {
+        const s = String(v || '').trim();
+        if (!s || s.startsWith('0000')) continue;
+        const t = Date.parse(`${s.replace(' ', 'T')}${v === gmt ? 'Z' : ''}`);
+        if (Number.isFinite(t)) return new Date(t).toISOString();
+    }
+    return '';
+}
+
+/**
+ * The plan.
+ *
+ * @param {object} wxr - from readWxr()
+ * @param {object} site - this site, now:
+ * @param {Set<string>} site.pagePaths       - every page's address, lower case
+ * @param {Object<string,string>} site.pageHashes - address -> fingerprint of its title and body now
+ * @param {Set<string>} site.mediaNames      - files in the media folder, lower case
+ * @param {Set<string>} site.menuSlugs
+ * @param {{available: boolean, basePath: string, posts: Map<string,{slug, hash}>, postSlugs: Set<string>, categories: Map<string,string>}} site.blog
+ * @param {boolean} site.redirectsAvailable  - SEO is running (its redirects take the old addresses)
+ * @param {Set<string>} site.redirectFroms   - addresses that already redirect
+ * @param {object} [mapping] - what earlier runs of this import made ({items: {key: {...}}})
+ * @param {object} [options]
+ * @param {'blog'|'pages'|'skip'} [options.posts]
+ * @param {'download'|'zip'|'skip'} [options.media]
+ * @param {boolean} [options.comments=true]
+ * @param {boolean} [options.menus=true]
+ * @param {boolean} [options.redirects=true]
+ * @param {boolean} [options.drafts=true] - import drafts, pending and private items (as drafts)
+ * @param {Object<string,'skip'|'overwrite'|'import'>} [options.choices] - per item key
+ * @param {Set<string>|null} [options.zipPaths] - uploads-relative paths in the uploaded zip
+ * @returns {object}
+ */
+export function planImport(wxr, site, mapping = {}, options = {}) {
+    const opt = {
+        posts: site.blog?.available ? 'blog' : 'pages',
+        media: 'download', comments: true, menus: true, redirects: true, drafts: true, choices: {}, zipPaths: null,
+        ...options
+    };
+    if (opt.posts === 'blog' && !site.blog?.available) opt.posts = 'pages';
+    const choices = opt.choices || {};
+    const mapped = mapping.items || {};
+    const base = basePathOf(wxr.site);
+    const blogBase = cleanPath(site.blog?.basePath || '/blog');
+    // Posts as pages: under the Blog's address - unless a Blog is on, which answers there itself.
+    const pagesBase = site.blog?.available ? '/posts' : blogBase;
+    const items = [];
+    const notes = [];
+    const byId = new Map(wxr.items.map(it => [it.id, it]));
+
+    const takenPaths = new Set(site.pagePaths);
+    const takenMedia = new Set(site.mediaNames);
+    const takenMenus = new Set(site.menuSlugs);
+    const takenSlugs = new Set(site.blog?.postSlugs || []);
+    // Addresses this import already holds (from an earlier run) are its own, not a clash.
+    const ownPaths = new Set(Object.values(mapped).filter(m => m.path).map(m => m.path));
+
+    const counts = {};
+    const count = (kind, action) => {
+        counts[kind] ||= {total: 0, create: 0, rename: 0, update: 0, keep: 0, skip: 0};
+        counts[kind].total++;
+        counts[kind][action]++;
+    };
+    const push = (row) => { items.push(row); count(row.kind, row.action); return row; };
+
+    // ---- Media first: content refers to it ----
+    const mediaByRel = {};
+    for (const it of wxr.items.filter(i => i.type === 'attachment')) {
+        const key = `media:${it.id}`;
+        const rel = uploadsPath(it.attachmentUrl) || '';
+        const ext = (rel || it.attachmentUrl).split('?')[0].split('.').pop().toLowerCase();
+        const was = mapped[key];
+        const row = {key, kind: 'media', wpId: it.id, title: it.title || rel.split('/').pop() || `Attachment ${it.id}`, oldUrl: it.attachmentUrl, rel};
+        if (choices[key] === 'skip') push({...row, action: 'skip', reason: 'You chose to skip it.'});
+        else if (was?.name && site.mediaNames.has(was.name.toLowerCase())) push({...row, action: 'keep', target: `/media/${was.name}`, name: was.name, reason: 'Imported before - the file is already here.'});
+        else if (opt.media === 'skip') push({...row, action: 'skip', reason: 'Media is not being imported.'});
+        else if (ext === 'svg' || ext === 'svgz') push({...row, action: 'skip', reason: 'SVG files can carry scripts - upload it by hand if you trust it.'});
+        else if (!MEDIA_EXTENSIONS.has(ext)) push({...row, action: 'skip', reason: `.${ext || '?'} files are not accepted in Media.`});
+        else if (!/^https?:\/\//i.test(it.attachmentUrl)) push({...row, action: 'skip', reason: 'It has no file address.'});
+        else if (opt.media === 'download' && !wxr.site.hosts.includes(hostOf(it.attachmentUrl))) push({...row, action: 'skip', reason: `It is on another site (${hostOf(it.attachmentUrl) || '?'}) - only the WordPress site's own files are downloaded.`});
+        else if (opt.media === 'download' && !opt.anyPort && !FETCH_PORTS.includes(portOf(it.attachmentUrl))) push({...row, action: 'skip', reason: `It is on port ${portOf(it.attachmentUrl)} - files are only downloaded over the web ports (80 and 443). Upload the uploads folder as a zip instead.`});
+        else if (opt.media === 'zip' && opt.zipPaths && !opt.zipPaths.has(rel.toLowerCase())) push({...row, action: 'skip', reason: 'It is not in the uploaded zip.'});
+        else {
+            const name = freeName(was?.name || mediaName(rel || it.attachmentUrl, it.id), takenMedia);
+            takenMedia.add(name.toLowerCase());
+            push({...row, action: was ? 'update' : 'create', target: `/media/${name}`, name, reason: was ? 'Imported before but the file is gone - fetched again.' : ''});
+        }
+        const last = items[items.length - 1];
+        if (last.target && rel) mediaByRel[rel.toLowerCase()] = last.target;
+    }
+
+    // ---- Pages ----
+    const pages = wxr.items.filter(i => i.type === 'page');
+    const pageTarget = new Map();
+    // Parents before children, so a child's address can follow its parent's.
+    const depthOf = (it, seen = new Set()) => (it.parent && byId.has(it.parent) && !seen.has(it.id) ? 1 + depthOf(byId.get(it.parent), seen.add(it.id)) : 0);
+    const orderedPages = [...pages].sort((a, b) => depthOf(a) - depthOf(b) || a.order - b.order || a.id - b.id);
+    for (const it of orderedPages) {
+        const key = `page:${it.id}`;
+        const oldPath = oldPathOf(it.link, wxr.site);
+        let wanted = oldPath ? cleanPath(relative(oldPath, base)) : '';
+        if (!wanted || wanted === '/' && oldPath !== null && relative(oldPath, base) !== '/') wanted = '';
+        if (!wanted) {
+            const parentPath = it.parent && pageTarget.get(it.parent);
+            const slug = slugify(it.slug) || slugify(it.title) || `page-${it.id}`;
+            wanted = `${parentPath && parentPath !== '/' ? parentPath : ''}/${slug}`;
+        }
+        const row = planDocument({it, key, kind: 'page', wanted, oldPath, statusMap: PAGE_STATUS});
+        if (row.target) pageTarget.set(it.id, row.target);
+    }
+
+    // ---- Posts ----
+    const posts = wxr.items.filter(i => i.type === 'post');
+    for (const it of posts) {
+        const key = `post:${it.id}`;
+        const oldPath = oldPathOf(it.link, wxr.site);
+        const slug = slugify(it.slug) || slugify(it.title) || `post-${it.id}`;
+        if (opt.posts === 'skip') {
+            push({...docRow(it, key, 'post', oldPath), action: 'skip', reason: 'Posts are not being imported.'});
+            continue;
+        }
+        if (opt.posts === 'blog') planBlogPost({it, key, slug, oldPath});
+        else planDocument({it, key, kind: 'post', wanted: `${pagesBase === '/' ? '' : pagesBase}/${slug}`, oldPath, statusMap: PAGE_STATUS});
+    }
+
+    // Everything else WordPress exports, counted so nothing vanishes silently.
+    const others = {};
+    for (const it of wxr.items) {
+        if (['page', 'post', 'attachment', 'nav_menu_item'].includes(it.type)) continue;
+        others[it.type] = (others[it.type] || 0) + 1;
+    }
+    for (const [type, n] of Object.entries(others)) {
+        notes.push(`${n} "${type}" item${n === 1 ? '' : 's'} (a theme or plugin's own content type) ${n === 1 ? 'is' : 'are'} not imported.`);
+    }
+
+    // ---- Categories (Blog only) ----
+    if (opt.posts === 'blog') {
+        for (const c of wxr.categories) {
+            if (c.slug === 'uncategorized' && !posts.some(p => p.terms.some(t => t.domain === 'category' && t.slug === 'uncategorized'))) continue;
+            const key = `category:${c.slug}`;
+            const slug = slugify(c.slug) || slugify(c.name);
+            const existing = site.blog.categories.get(slug);
+            const row = {key, kind: 'category', wpId: c.id, title: c.name || c.slug, target: `${blogBase}/category/${slug}`, slug};
+            if (choices[key] === 'skip') push({...row, action: 'skip', reason: 'You chose to skip it.'});
+            else if (mapped[key] && existing) push({...row, action: 'keep', reason: 'Imported before - the Blog has it.'});
+            else if (existing) push({...row, action: 'keep', reason: 'The Blog has this category already - posts are filed under it.'});
+            else push({...row, action: 'create', reason: ''});
+        }
+    }
+
+    // ---- Menus ----
+    const menuRows = [];
+    if (opt.menus) {
+        for (const m of wxr.menus) {
+            const key = `menu:${m.slug}`;
+            const navItems = wxr.items.filter(i => i.type === 'nav_menu_item' && i.terms.some(t => t.domain === 'nav_menu' && t.slug === m.slug));
+            const was = mapped[key];
+            const row = {key, kind: 'menu', wpId: m.id, title: m.name || m.slug, count: navItems.length};
+            if (choices[key] === 'skip') { menuRows.push(push({...row, action: 'skip', reason: 'You chose to skip it.'})); continue; }
+            if (!navItems.length) { menuRows.push(push({...row, action: 'skip', reason: 'It has no items.'})); continue; }
+            if (was?.slug && site.menuSlugs.has(was.slug)) {
+                const edited = was.hash && site.menuHashes?.[was.slug] && site.menuHashes[was.slug] !== was.hash;
+                if (edited && choices[key] !== 'overwrite') menuRows.push(push({...row, action: 'keep', slug: was.slug, target: was.slug, reason: 'Edited on this site since it was imported - left as it is.'}));
+                else menuRows.push(push({...row, action: 'update', slug: was.slug, target: was.slug, reason: edited ? 'Edited here since - you chose to overwrite it.' : ''}));
+                continue;
+            }
+            const wantedSlug = `wp-${slugify(m.slug) || m.id}`.slice(0, 60);
+            const slugNow = freePath(wantedSlug, takenMenus);
+            takenMenus.add(slugNow);
+            menuRows.push(push({...row, action: slugNow === wantedSlug ? 'create' : 'rename', slug: slugNow, target: slugNow,
+                reason: slugNow === wantedSlug ? '' : `A menu called ${wantedSlug} exists - this one is ${slugNow}.`}));
+        }
+    }
+
+    // ---- Comments (with the Blog) ----
+    let comments = 0;
+    if (opt.posts === 'blog' && opt.comments && site.blog?.comments !== false) {
+        for (const r of items) {
+            if (r.kind !== 'post' || r.action === 'skip' || r.action === 'keep') continue;
+            const it = byId.get(r.wpId);
+            r.comments = it.comments.filter(c => c.approved === '1' && (!c.type || c.type === 'comment')).length;
+            comments += r.comments;
+        }
+    }
+
+    // ---- Redirects ----
+    const redirects = [];
+    const query = {p: {}, page_id: {}, attachment_id: {}};
+    const live = (r) => r.target && r.action !== 'skip';
+    for (const r of items) {
+        if (!live(r)) continue;
+        if (r.kind === 'page' || r.kind === 'post') {
+            query[r.kind === 'page' ? 'page_id' : 'p'][r.wpId] = r.target;
+            if (r.kind === 'page') query.p[r.wpId] = r.target;
+            if (r.oldPath && r.oldPath !== r.target) redirects.push({from: r.oldPath, to: r.target, key: r.key});
+        } else if (r.kind === 'media') {
+            query.attachment_id[r.wpId] = r.target;
+        }
+    }
+    if (opt.posts === 'blog') {
+        for (const r of items.filter(x => x.kind === 'category' && x.action !== 'skip')) {
+            redirects.push({from: `${base}/category/${r.slug}`, to: r.target, key: r.key});
+        }
+        const taggedSlugs = new Set(posts.flatMap(p => p.terms.filter(t => t.domain === 'post_tag').map(t => t.slug)));
+        for (const t of wxr.tags.filter(x => taggedSlugs.has(x.slug))) {
+            const s = slugify(t.slug);
+            // The Blog files a post under its tag's name, as written; an address can only carry a plain one.
+            const name = String(t.name || t.slug);
+            if (s) redirects.push({from: `${base}/tag/${s}`, to: /^[a-z0-9-]+$/.test(name) ? `${blogBase}/tag/${name}` : blogBase, key: `tag:${s}`});
+        }
+        // Date archives, when the permalinks were dated (/2019/05/hello/).
+        const years = new Set();
+        for (const r of items.filter(x => x.kind === 'post' && x.oldPath)) {
+            const m = /^\/(\d{4})(\/|$)/.exec(relative(r.oldPath, base));
+            if (m) years.add(m[1]);
+        }
+        for (const y of years) {
+            redirects.push({from: `${base}/${y}`, to: blogBase, key: `date:${y}`});
+            redirects.push({from: `${base}/${y}/*`, to: blogBase, key: `date:${y}/*`});
+        }
+        if (posts.length) redirects.push({from: `${base}/feed`, to: `${blogBase}/feed.xml`, key: 'feed'});
+    }
+    const liveTargets = new Set(items.filter(live).map(x => x.target));
+    const redirectPlan = [];
+    const ownRedirects = new Set(Object.values(mapping.redirects || {}).map(r => r.from));
+    const seen = new Set();
+    for (const r of redirects) {
+        const from = r.from.endsWith('/*') ? r.from : normalisePath(r.from);
+        const to = r.to;
+        if (seen.has(from)) continue;
+        seen.add(from);
+        let action = 'create';
+        let reason = '';
+        if (!opt.redirects) { action = 'skip'; reason = 'Redirects are not being added.'; }
+        else if (!site.redirectsAvailable) { action = 'skip'; reason = 'SEO is switched off on this site, so redirects cannot be added.'; }
+        else if (from === normalisePath(to)) { action = 'skip'; reason = 'Same address.'; }
+        else if (from === '/' || from === '/*') { action = 'skip'; reason = 'That would redirect the home page.'; }
+        else if (liveTargets.has(from)) { action = 'skip'; reason = 'An imported item takes that address.'; }
+        else if (site.pagePaths.has(from) && !ownPaths.has(from)) { action = 'skip'; reason = 'A page on this site has that address - it is not redirected.'; }
+        else if (site.redirectFroms.has(from) && !ownRedirects.has(from)) { action = 'skip'; reason = 'This site already redirects it.'; }
+        else if (ownRedirects.has(from)) action = 'update';
+        redirectPlan.push({from, to, key: r.key, action, reason});
+    }
+
+    for (const r of items) if (r.builder) notes.push(`"${r.title}" was built with ${r.builder} - its layout will need rebuilding.`);
+    const shortcodeCount = items.reduce((n, r) => n + (r.shortcodes?.length || 0), 0);
+
+    const summary = {
+        counts,
+        comments,
+        redirects: redirectPlan.filter(r => r.action !== 'skip').length,
+        shortcodes: shortcodeCount,
+        builders: items.filter(r => r.builder).length
+    };
+    return {
+        source: sourceKey(wxr.site),
+        site: {title: wxr.site.title, url: wxr.site.baseSiteUrl || wxr.site.link, wxrVersion: wxr.site.wxrVersion, hosts: wxr.site.hosts},
+        options: {...opt, zipPaths: undefined, anyPort: undefined, choices},
+        blogBase,
+        items,
+        redirects: redirectPlan,
+        query,
+        mediaByRel,
+        notes: [...new Set(notes)],
+        summary
+    };
+
+    // ---- helpers sharing the plan's state ----
+    function docRow(it, key, kind, oldPath) {
+        return {
+            key, kind, wpId: it.id, title: it.title || `(untitled ${kind} ${it.id})`, oldUrl: it.link, oldPath,
+            wpStatus: it.status, shortcodes: findShortcodes(it.content), builder: detectBuilder(it)
+        };
+    }
+    function excluded(it) {
+        if (it.status === 'trash' || it.status === 'auto-draft' || it.status === 'inherit') return `It is ${it.status === 'trash' ? 'in the WordPress bin' : 'an automatic draft'}.`;
+        if (!opt.drafts && it.status !== 'publish') return 'Drafts and private items are not being imported.';
+        return '';
+    }
+    function planDocument({it, key, kind, wanted, oldPath, statusMap}) {
+        const row = docRow(it, key, kind, oldPath);
+        row.status = statusMap[it.status] || 'draft';
+        if (it.password) row.status = 'draft';
+        const was = mapped[key];
+        const why = excluded(it);
+        if (choices[key] === 'skip') return push({...row, action: 'skip', reason: 'You chose to skip it.'});
+        if (why) return push({...row, action: 'skip', reason: why});
+        if (was?.path) {
+            if (!site.pagePaths.has(was.path)) {
+                if (choices[key] !== 'import') return push({...row, action: 'skip', target: was.path, reason: 'Deleted on this site since it was imported - choose "Import again" to bring it back.'});
+                takenPaths.add(was.path);
+                return push({...row, action: 'create', target: was.path, reason: 'Imported again after being deleted here.'});
+            }
+            const edited = site.pageHashes[was.path] && site.pageHashes[was.path] !== was.hash;
+            if (edited && choices[key] !== 'overwrite') return push({...row, action: 'keep', target: was.path, reason: 'Edited on this site since it was imported - left as it is.'});
+            return push({...row, action: 'update', target: was.path, reason: edited ? 'Edited here since - you chose to overwrite it.' : ''});
+        }
+        if (it.password) row.reason = 'It was password-protected in WordPress - imported as a draft.';
+        // An address an earlier run gave another item is taken too: only an item's own (was.path, above) is not a clash.
+        const clash = takenPaths.has(wanted);
+        if (clash && choices[key] === 'overwrite') {
+            takenPaths.add(wanted);
+            return push({...row, action: 'update', target: wanted, replaces: true, reason: 'Replaces the page this site has at that address (you chose this).'});
+        }
+        const target = clash ? freePath(wanted === '/' ? `/${slugify(it.slug) || 'home'}` : wanted, takenPaths) : wanted;
+        takenPaths.add(target);
+        if (clash) return push({...row, action: 'rename', target, wanted, reason: `${wanted} is taken on this site - imported as ${target}.`});
+        return push({...row, action: 'create', target});
+    }
+    function planBlogPost({it, key, slug, oldPath}) {
+        const row = docRow(it, key, 'post', oldPath);
+        row.status = it.password ? 'draft' : (POST_STATUS[it.status] || 'draft');
+        const was = mapped[key];
+        const why = excluded(it);
+        if (choices[key] === 'skip') return push({...row, action: 'skip', reason: 'You chose to skip it.'});
+        if (why) return push({...row, action: 'skip', reason: why});
+        if (was?.entryId) {
+            const now = site.blog.posts.get(was.entryId);
+            if (!now) {
+                if (choices[key] !== 'import') return push({...row, action: 'skip', target: `${blogBase}/${was.slug}`, reason: 'Deleted from the Blog since it was imported - choose "Import again" to bring it back.'});
+            } else {
+                const edited = now.hash !== was.hash;
+                const target = `${blogBase}/${now.slug}`;
+                if (edited && choices[key] !== 'overwrite') return push({...row, action: 'keep', target, slug: now.slug, entryId: was.entryId, reason: 'Edited in the Blog since it was imported - left as it is.'});
+                return push({...row, action: 'update', target, slug: now.slug, entryId: was.entryId, reason: edited ? 'Edited here since - you chose to overwrite it.' : ''});
+            }
+        }
+        const free = freePath(slug, takenSlugs);
+        takenSlugs.add(free);
+        if (it.password) row.reason = 'It was password-protected in WordPress - imported as a draft.';
+        if (free !== slug) return push({...row, action: 'rename', target: `${blogBase}/${free}`, slug: free, wanted: `${blogBase}/${slug}`, reason: `The Blog has a post at ${blogBase}/${slug} - imported as ${free}.`});
+        return push({...row, action: 'create', target: `${blogBase}/${free}`, slug: free});
+    }
+}
+
+/** One key per WordPress site, so two different sites imported here never share a mapping. */
+export function sourceKey(site) {
+    const u = site.baseSiteUrl || site.baseBlogUrl || site.link || site.title || 'wordpress';
+    try {
+        const url = new URL(u);
+        return `${url.hostname.toLowerCase().replace(/^www\./, '')}${normalisePath(url.pathname) === '/' ? '' : normalisePath(url.pathname)}`;
+    } catch {
+        return slugify(u) || 'wordpress';
+    }
+}
+
+/**
+ * Menu items for a Domma menu, from the WordPress nav_menu_item posts.
+ *
+ * @param {object} wxr
+ * @param {string} menuSlug - the WordPress menu's slug
+ * @param {(item: object) => string|null} addressFor - a WordPress item's id -> its new address
+ * @param {(url: string) => string|null} linkFor - a custom link -> the new address, or null to keep it
+ * @param {Map<string,string>} [categoryAddress] - category slug -> its Blog address
+ * @returns {{text: string, url: string, target?: string, items?: object[]}[]}
+ */
+export function menuItems(wxr, menuSlug, addressFor, linkFor, categoryAddress = new Map()) {
+    const nav = wxr.items.filter(i => i.type === 'nav_menu_item' && i.terms.some(t => t.domain === 'nav_menu' && t.slug === menuSlug));
+    const byId = new Map(wxr.items.map(i => [i.id, i]));
+    const nodes = new Map();
+    for (const it of nav) {
+        const m = it.meta;
+        const objectId = Number.parseInt(m._menu_item_object_id, 10);
+        let url = null;
+        let text = it.title;
+        if (m._menu_item_type === 'post_type') {
+            url = addressFor(objectId);
+            if (!text) text = byId.get(objectId)?.title || '';
+        } else if (m._menu_item_type === 'taxonomy') {
+            const term = wxr.categories.find(c => c.id === objectId) || wxr.tags.find(t => t.id === objectId);
+            if (term) {
+                url = categoryAddress.get(term.slug) || null;
+                if (!text) text = term.name;
+            }
+        } else if (m._menu_item_type === 'post_type_archive') {
+            url = addressFor('archive');
+        } else {
+            const raw = String(m._menu_item_url || '').trim();
+            url = linkFor(raw) || (/^(https?:|mailto:|tel:|\/|#)/i.test(raw) ? raw : null);
+        }
+        if (!url || !String(text).trim()) continue;
+        const node = {text: String(text).replace(/<[^>]+>/g, '').trim().slice(0, 120), url, ...(m._menu_item_target === '_blank' && {target: '_blank'})};
+        nodes.set(it.id, {node, parent: Number.parseInt(m._menu_item_menu_item_parent, 10) || 0, order: it.order});
+    }
+    const roots = [];
+    const sorted = [...nodes.entries()].sort((a, b) => a[1].order - b[1].order);
+    for (const [, n] of sorted) {
+        const parent = n.parent && nodes.get(n.parent);
+        if (parent && depth(parent) < 3) (parent.node.items ||= []).push(n.node);
+        else roots.push(n.node);
+    }
+    return roots;
+
+    function depth(n, d = 0) { return n.parent && nodes.get(n.parent) && d < 5 ? depth(nodes.get(n.parent), d + 1) + 1 : 0; }
+}