domma-cms 1.7.0 → 1.7.2

package/server/services/wpImport/store.js

@@ -0,0 +1,242 @@
+/**
+ * WordPress import - what it keeps on disk, all under content/imports/wordpress/:
+ *
+ *   map.json            per WordPress site (sourceKey): what each WordPress id
+ *                       became here, with a fingerprint of what was written -
+ *                       how a second run updates instead of duplicating, and
+ *                       notices a page edited here since
+ *                       {sources: {<key>: {items: {key: {...}}, redirects: {key: {id, from, to}},
+ *                                          query: {p, page_id, attachment_id}, updatedAt}}}
+ *   history.json        the runs, newest first: [{id, at, by, source, siteTitle, file, status, summary}]
+ *   reports/<id>.json   each run's full report
+ *   running.json        the run in progress - a restart finds it and records the run as failed
+ *   staging/<id>/       an upload waiting for its run (export.xml, uploads.zip, meta.json) -
+ *                       removed after the run, when discarded, or a day later
+ * The whole folder is kept out of the site's git repo (allowInGitignore): the history and
+ * reports name who ran each import and the commenters.
+ *
+ * @module services/wpImport/store
+ */
+import fs from 'node:fs/promises';
+import fsSync from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+export const importDir = () => path.resolve('content', 'imports', 'wordpress');
+const stagingRoot = () => path.join(importDir(), 'staging');
+const STAGING_TTL_MS = 24 * 60 * 60 * 1000;
+export const HISTORY_MAX = 50;
+
+const ID_RE = /^[a-z0-9]{6,40}$/;
+export const isId = (id) => ID_RE.test(String(id || ''));
+export const newId = () => `${Date.now().toString(36)}${crypto.randomBytes(5).toString('hex')}`;
+
+async function readJson(file, empty) {
+    try { return JSON.parse(await fs.readFile(file, 'utf8')); } catch { return structuredClone(empty); }
+}
+
+async function writeJson(file, value) {
+    await fs.mkdir(path.dirname(file), {recursive: true});
+    const tmp = `${file}.${process.pid}.tmp`;
+    await fs.writeFile(tmp, JSON.stringify(value, null, 2) + '\n');
+    await fs.rename(tmp, file);
+}
+
+// ---- The mapping ----------------------------------------------------------
+
+let mapCache = null;
+
+export async function readMap() {
+    const m = await readJson(path.join(importDir(), 'map.json'), {sources: {}});
+    if (!m.sources || typeof m.sources !== 'object') m.sources = {};
+    mapCache = m;
+    return m;
+}
+
+/** The mapping for one WordPress site ({} when it was never imported). */
+export async function mappingFor(source) {
+    const m = await readMap();
+    return m.sources[source] || {items: {}, redirects: {}, query: {}};
+}
+
+let mapWrites = Promise.resolve();
+
+/** Save one site's mapping. Writes are queued: the media downloads run side by side and each checkpoints. */
+export function saveMapping(source, mapping) {
+    const snapshot = {...mapping, items: {...mapping.items}, redirects: {...mapping.redirects}, updatedAt: new Date().toISOString()};
+    const write = mapWrites.then(async () => {
+        const m = await readMap();
+        m.sources[source] = snapshot;
+        await writeJson(path.join(importDir(), 'map.json'), m);
+        mapCache = m;
+    });
+    mapWrites = write.catch(() => {});
+    return write;
+}
+
+let mapMtime = -1;
+let mapCheckedAt = 0;
+
+/**
+ * Synchronous, cached - for the request hook that answers ?p=12. The file is
+ * looked at again at most every few seconds, so a mapping written by another
+ * process (or restored from a backup) is picked up without a restart.
+ */
+export function queryTarget(param, id) {
+    const now = Date.now();
+    if (!mapCache || now - mapCheckedAt > 3000) {
+        mapCheckedAt = now;
+        const file = path.join(importDir(), 'map.json');
+        let mtime = 0;
+        try { mtime = fsSync.statSync(file).mtimeMs; } catch { /* no imports yet */ }
+        if (!mapCache || mtime !== mapMtime) {
+            mapMtime = mtime;
+            try { mapCache = mtime ? JSON.parse(fsSync.readFileSync(file, 'utf8')) : {sources: {}}; } catch { mapCache = {sources: {}}; }
+        }
+    }
+    for (const src of Object.values(mapCache.sources || {})) {
+        const t = src?.query?.[param]?.[id];
+        if (typeof t === 'string' && t.startsWith('/') && !t.startsWith('//') && !/[\\\s]/.test(t)) return t;
+    }
+    return null;
+}
+
+export function forgetMapCache() { mapCache = null; }
+
+/**
+ * A page this import made was moved here (renamed in the page editor): follow
+ * it, so the next run updates it where it now is instead of thinking it was
+ * deleted, and ?page_id= keeps finding it.
+ */
+export async function followRename(from, to) {
+    if (!from || !to || from === to) return false;
+    const m = await readMap();
+    let changed = false;
+    for (const src of Object.values(m.sources)) {
+        for (const it of Object.values(src.items || {})) {
+            if (it?.path === from) { it.path = to; changed = true; }
+        }
+        for (const list of Object.values(src.query || {})) {
+            for (const [id, t] of Object.entries(list || {})) if (t === from) { list[id] = to; changed = true; }
+        }
+    }
+    if (changed) await writeJson(path.join(importDir(), 'map.json'), m);
+    return changed;
+}
+
+// ---- A run in progress, on disk - so a restart mid-run is noticed ----
+
+const runningFile = () => path.join(importDir(), 'running.json');
+
+export async function markRunning(run) { await writeJson(runningFile(), run); }
+export async function clearRunning() { await fs.rm(runningFile(), {force: true}); }
+
+/**
+ * A run the site stopped in the middle of (a restart, a crash): recorded in
+ * the history as failed. What it made is already in the mapping (it is saved
+ * as the run goes), so running the same export again finishes the job
+ * without duplicating anything. Called once at boot.
+ */
+export async function recoverInterrupted() {
+    let run;
+    try { run = JSON.parse(await fs.readFile(runningFile(), 'utf8')); } catch { return null; }
+    await clearRunning();
+    if (!isId(run?.id)) return null;
+    await recordFailedRun(run, 'The site restarted while this import was running. What it had already made is kept; upload the export again (or use the one still waiting) and run it to finish - nothing is made twice.');
+    return run;
+}
+
+/** A run that stopped, in the history with the reason. */
+export async function recordFailedRun(run, reason) {
+    const entry = {id: run.id, at: new Date().toISOString(), by: run.by || '', source: run.source || '', siteTitle: run.siteTitle || '',
+        siteUrl: run.siteUrl || '', file: run.file || '', status: 'failed', durationMs: 0,
+        summary: {kinds: {}, comments: 0, redirects: {created: 0, updated: 0, skipped: 0, failed: 0}, failed: 0, rebuild: 0}};
+    await addHistory(entry, {run: entry, options: {}, items: [], redirects: [], notes: [reason], blogBase: ''});
+}
+
+// ---- History --------------------------------------------------------------
+
+export async function listHistory() {
+    const h = await readJson(path.join(importDir(), 'history.json'), {runs: []});
+    return Array.isArray(h.runs) ? h.runs : [];
+}
+
+export async function addHistory(run, report) {
+    await writeJson(path.join(importDir(), 'reports', `${run.id}.json`), report);
+    const runs = [run, ...(await listHistory()).filter(r => r.id !== run.id)];
+    const keep = runs.slice(0, HISTORY_MAX);
+    for (const gone of runs.slice(HISTORY_MAX)) await fs.rm(path.join(importDir(), 'reports', `${gone.id}.json`), {force: true});
+    await writeJson(path.join(importDir(), 'history.json'), {runs: keep});
+}
+
+export async function getReport(id) {
+    if (!isId(id)) return null;
+    try { return JSON.parse(await fs.readFile(path.join(importDir(), 'reports', `${id}.json`), 'utf8')); } catch { return null; }
+}
+
+/** Remove a run from the history (its report too). The imported content stays. */
+export async function removeHistory(id) {
+    if (!isId(id)) return false;
+    const runs = await listHistory();
+    if (!runs.some(r => r.id === id)) return false;
+    await writeJson(path.join(importDir(), 'history.json'), {runs: runs.filter(r => r.id !== id)});
+    await fs.rm(path.join(importDir(), 'reports', `${id}.json`), {force: true});
+    return true;
+}
+
+// ---- Staging --------------------------------------------------------------
+
+export function stagingPath(id, file = '') {
+    if (!isId(id)) throw new Error('Not an import id.');
+    if (file && !/^[a-z0-9.-]+$/.test(file)) throw new Error('Not a staging file.');
+    return path.join(stagingRoot(), id, file);
+}
+
+export async function createStaging(meta) {
+    const id = newId();
+    await fs.mkdir(stagingPath(id), {recursive: true});
+    await writeJson(stagingPath(id, 'meta.json'), {...meta, id, at: new Date().toISOString()});
+    return id;
+}
+
+export async function stagingMeta(id) {
+    if (!isId(id)) return null;
+    try {
+        const meta = JSON.parse(await fs.readFile(stagingPath(id, 'meta.json'), 'utf8'));
+        if (Date.now() - Date.parse(meta.at) > STAGING_TTL_MS) { await dropStaging(id); return null; }
+        return meta;
+    } catch { return null; }
+}
+
+export async function updateStagingMeta(id, patch) {
+    const meta = await stagingMeta(id);
+    if (!meta) return null;
+    const next = {...meta, ...patch};
+    await writeJson(stagingPath(id, 'meta.json'), next);
+    return next;
+}
+
+export async function dropStaging(id) {
+    if (!isId(id)) return;
+    await fs.rm(stagingPath(id), {recursive: true, force: true});
+}
+
+/** Uploads waiting for a run, newest first; anything over a day old is removed. */
+export async function listStaging() {
+    let names = [];
+    try { names = await fs.readdir(stagingRoot()); } catch { return []; }
+    const out = [];
+    for (const n of names) {
+        if (!isId(n)) continue;
+        const meta = await stagingMeta(n);
+        if (meta) out.push(meta);
+    }
+    return out.sort((a, b) => String(b.at).localeCompare(String(a.at)));
+}
+
+/** A fingerprint of what an import wrote - compared on the next run to notice edits made here. */
+export function fingerprint(...parts) {
+    const h = crypto.createHash('sha256');
+    for (const p of parts) h.update(String(p ?? '').replace(/\r\n?/g, '\n').trim()).update('\u0000');
+    return h.digest('hex').slice(0, 32);
+}

package/server/services/wpImport/wxr.js

@@ -0,0 +1,167 @@
+/**
+ * A WordPress export (WXR 1.0-1.2) as plain data - what the planner and the
+ * runner work from. Reads the tree from ./xml.js; does no I/O.
+ *
+ *   {site: {title, link, baseSiteUrl, baseBlogUrl, wxrVersion, hosts[]},
+ *    authors[], categories[], tags[], menus[],
+ *    items: [{id, type, title, slug, status, parent, order, date, dateGmt, link, guid,
+ *             creator, content, excerpt, password, attachmentUrl, meta{}, terms[], comments[]}]}
+ *
+ * @module services/wpImport/wxr
+ */
+import {child, children, parseXml, textOf, XmlError} from './xml.js';
+
+/** Item types the importer acts on; everything else is counted and listed as skipped. */
+export const KNOWN_TYPES = new Set(['page', 'post', 'attachment', 'nav_menu_item']);
+
+const int = (v) => {
+    const n = Number.parseInt(String(v ?? '').trim(), 10);
+    return Number.isFinite(n) ? n : 0;
+};
+
+/** The hostname of a URL ('' when it is not one), lower case, without "www.". */
+export function hostOf(url) {
+    try {
+        const u = new URL(String(url || '').trim());
+        if (u.protocol !== 'http:' && u.protocol !== 'https:') return '';
+        return u.hostname.toLowerCase();
+    } catch { return ''; }
+}
+
+const bareHost = (h) => String(h || '').toLowerCase().replace(/^www\./, '');
+
+/**
+ * Read a WXR document.
+ *
+ * @param {string} text - the XML
+ * @returns {Promise<object>} the export as data
+ * @throws {XmlError} when it is not XML, or not a WordPress export
+ */
+export async function readWxr(text) {
+    const root = await parseXml(text);
+    return wxrFromTree(root);
+}
+
+/** @param {object} root - from parseXml() */
+export function wxrFromTree(root) {
+    if (root?.name !== 'rss') throw new XmlError('This is not a WordPress export: it is not an RSS document');
+    const channel = child(root, 'channel');
+    if (!channel) throw new XmlError('This is not a WordPress export: it has no channel');
+    const wxrVersion = textOf(channel, 'wp:wxr_version');
+    if (!wxrVersion) throw new XmlError('This is not a WordPress export: it has no wp:wxr_version (export it from Tools › Export in WordPress)');
+
+    const site = {
+        title: textOf(channel, 'title'),
+        link: textOf(channel, 'link'),
+        description: textOf(channel, 'description'),
+        language: textOf(channel, 'language'),
+        baseSiteUrl: textOf(channel, 'wp:base_site_url'),
+        baseBlogUrl: textOf(channel, 'wp:base_blog_url'),
+        wxrVersion
+    };
+
+    const authors = children(channel, 'wp:author').map(a => ({
+        id: int(textOf(a, 'wp:author_id')),
+        login: textOf(a, 'wp:author_login'),
+        email: textOf(a, 'wp:author_email'),
+        displayName: textOf(a, 'wp:author_display_name') || textOf(a, 'wp:author_login')
+    }));
+
+    const categories = children(channel, 'wp:category').map(c => ({
+        id: int(textOf(c, 'wp:term_id')),
+        slug: textOf(c, 'wp:category_nicename'),
+        parent: textOf(c, 'wp:category_parent'),
+        name: textOf(c, 'wp:cat_name'),
+        description: textOf(c, 'wp:category_description')
+    })).filter(c => c.slug);
+
+    const tags = children(channel, 'wp:tag').map(t => ({
+        id: int(textOf(t, 'wp:term_id')),
+        slug: textOf(t, 'wp:tag_slug'),
+        name: textOf(t, 'wp:tag_name'),
+        description: textOf(t, 'wp:tag_description')
+    })).filter(t => t.slug);
+
+    // nav_menu terms: the menus themselves (their items are nav_menu_item posts).
+    const menus = children(channel, 'wp:term')
+        .filter(t => textOf(t, 'wp:term_taxonomy') === 'nav_menu')
+        .map(t => ({id: int(textOf(t, 'wp:term_id')), slug: textOf(t, 'wp:term_slug'), name: textOf(t, 'wp:term_name')}))
+        .filter(m => m.slug);
+
+    const items = children(channel, 'item').map(readItem);
+
+    // A menu named only on its items (WXR 1.0 has no wp:term for it).
+    for (const it of items) {
+        if (it.type !== 'nav_menu_item') continue;
+        const t = it.terms.find(x => x.domain === 'nav_menu');
+        if (t && !menus.some(m => m.slug === t.slug)) menus.push({id: 0, slug: t.slug, name: t.name || t.slug});
+    }
+    // Categories and tags named only on posts (a partial export). Sets: big exports have thousands of each.
+    const catSlugs = new Set(categories.map(c => c.slug));
+    const tagSlugs = new Set(tags.map(t => t.slug));
+    for (const it of items) {
+        for (const t of it.terms) {
+            if (t.domain === 'category' && !catSlugs.has(t.slug)) { catSlugs.add(t.slug); categories.push({id: 0, slug: t.slug, parent: '', name: t.name || t.slug, description: ''}); }
+            if (t.domain === 'post_tag' && !tagSlugs.has(t.slug)) { tagSlugs.add(t.slug); tags.push({id: 0, slug: t.slug, name: t.name || t.slug, description: ''}); }
+        }
+    }
+
+    const hostSet = new Set();
+    for (const u of [site.baseSiteUrl, site.baseBlogUrl, site.link]) {
+        const h = hostOf(u);
+        if (h) { hostSet.add(h); hostSet.add(bareHost(h)); hostSet.add(`www.${bareHost(h)}`); }
+    }
+    site.hosts = [...hostSet];
+    return {site, authors, categories, tags, menus, items};
+}
+
+function readItem(node) {
+    const meta = {};
+    for (const m of children(node, 'wp:postmeta')) {
+        const k = textOf(m, 'wp:meta_key');
+        if (k && !(k in meta)) meta[k] = textOf(m, 'wp:meta_value', {raw: true});
+    }
+    const terms = children(node, 'category').map(c => ({
+        domain: c.attrs.domain || 'category',
+        slug: c.attrs.nicename || '',
+        name: c.text.trim()
+    })).filter(t => t.slug || t.name);
+    const comments = children(node, 'wp:comment').map(c => ({
+        id: int(textOf(c, 'wp:comment_id')),
+        author: textOf(c, 'wp:comment_author'),
+        email: textOf(c, 'wp:comment_author_email'),
+        url: textOf(c, 'wp:comment_author_url'),
+        date: textOf(c, 'wp:comment_date'),
+        dateGmt: textOf(c, 'wp:comment_date_gmt'),
+        content: textOf(c, 'wp:comment_content', {raw: true}),
+        approved: textOf(c, 'wp:comment_approved'),
+        type: textOf(c, 'wp:comment_type'),
+        parent: int(textOf(c, 'wp:comment_parent'))
+    }));
+    return {
+        id: int(textOf(node, 'wp:post_id')),
+        type: textOf(node, 'wp:post_type') || 'post',
+        title: textOf(node, 'title'),
+        slug: decodeSlug(textOf(node, 'wp:post_name')),
+        status: textOf(node, 'wp:status') || 'publish',
+        parent: int(textOf(node, 'wp:post_parent')),
+        order: int(textOf(node, 'wp:menu_order')),
+        date: textOf(node, 'wp:post_date'),
+        dateGmt: textOf(node, 'wp:post_date_gmt'),
+        link: textOf(node, 'link'),
+        guid: textOf(node, 'guid'),
+        creator: textOf(node, 'dc:creator'),
+        content: textOf(node, 'content:encoded', {raw: true}),
+        excerpt: textOf(node, 'excerpt:encoded', {raw: true}).trim(),
+        password: textOf(node, 'wp:post_password'),
+        attachmentUrl: textOf(node, 'wp:attachment_url'),
+        meta,
+        terms,
+        comments
+    };
+}
+
+/** WordPress stores non-ASCII slugs percent-encoded. */
+function decodeSlug(s) {
+    try { return decodeURIComponent(s); } catch { return s; }
+}

package/server/services/wpImport/xml.js

@@ -0,0 +1,261 @@
+/**
+ * A small, strict XML reader for WordPress exports (WXR) - written for safety
+ * rather than generality.
+ *
+ *  - No DTDs at all. A `<!DOCTYPE` is refused outright, and so is `<!ENTITY`
+ *    anywhere: WordPress never writes either, and they are how XXE (external
+ *    entities reading files or URLs) and "billion laughs" (entities that expand
+ *    exponentially) get in. Only the five predefined entities and numeric
+ *    character references are decoded; any other `&name;` is left as text.
+ *  - Bounded: element depth, attributes per element, name length and the
+ *    number of nodes all have ceilings, so a hostile file fails fast.
+ *  - Chunked: `parseXml()` hands the event loop back every few thousand
+ *    tokens, so a 50 MB export does not freeze the site while it is read.
+ *  - Namespaces are resolved by URI, not by the prefix a file happens to use:
+ *    `wp:`, `content:`, `excerpt:` and `dc:` come out under those names
+ *    whatever the file called them (WXR 1.0, 1.1 and 1.2 differ only in the
+ *    wp: namespace's version number).
+ *
+ * The result is a plain tree: {name, attrs, children, text}. Text is the
+ * concatenated character data (CDATA included) of the element itself.
+ *
+ * @module services/wpImport/xml
+ */
+
+/** Namespace URIs -> the prefix the rest of the importer uses. */
+export function canonicalPrefix(uri) {
+    const u = String(uri || '').trim().replace(/\/+$/, '');
+    if (/^https?:\/\/wordpress\.org\/export\/1\.\d+\/excerpt$/i.test(u)) return 'excerpt';
+    if (/^https?:\/\/wordpress\.org\/export\/1\.\d+$/i.test(u)) return 'wp';
+    if (/^https?:\/\/purl\.org\/rss\/1\.0\/modules\/content$/i.test(u)) return 'content';
+    if (/^https?:\/\/purl\.org\/dc\/elements\/1\.1$/i.test(u)) return 'dc';
+    if (/^https?:\/\/wellformedweb\.org\/CommentAPI$/i.test(u)) return 'wfw';
+    return null;
+}
+
+export const LIMITS = Object.freeze({
+    maxDepth: 64,
+    maxAttributes: 64,
+    maxNameLength: 256,
+    maxNodes: 1_000_000,
+    sliceTokens: 4000
+});
+
+export class XmlError extends Error {
+    constructor(message, at = -1) {
+        super(at >= 0 ? `${message} (at character ${at})` : message);
+        this.code = 'EXML';
+    }
+}
+
+const PREDEFINED = {lt: '<', gt: '>', amp: '&', quot: '"', apos: "'"};
+
+/** Decode the predefined entities and numeric references - nothing else. */
+export function decodeEntities(s) {
+    if (!s || s.indexOf('&') === -1) return s;
+    return s.replace(/&(#x[0-9a-f]{1,6}|#[0-9]{1,7}|[a-z]{2,4});/gi, (m, ref) => {
+        if (ref[0] === '#') {
+            const code = ref[1] === 'x' || ref[1] === 'X' ? parseInt(ref.slice(2), 16) : parseInt(ref.slice(1), 10);
+            if (!Number.isFinite(code) || code < 1 || code > 0x10ffff || (code >= 0xd800 && code <= 0xdfff)) return '';
+            return String.fromCodePoint(code);
+        }
+        return Object.prototype.hasOwnProperty.call(PREDEFINED, ref) ? PREDEFINED[ref] : m;
+    });
+}
+
+const NAME_RE = /^[A-Za-z_][\w.\-]*(:[A-Za-z_][\w.\-]*)?$/;
+const ATTR_RE = /([^\s=/>]+)\s*=\s*("([^"]*)"|'([^']*)')/g;
+
+/**
+ * Parse an XML document into a tree, yielding to the event loop as it goes.
+ *
+ * @param {string} text
+ * @param {Partial<typeof LIMITS>} [limits]
+ * @returns {Promise<{name: string, attrs: object, children: object[], text: string}>} the root element
+ * @throws {XmlError}
+ */
+export async function parseXml(text, limits = {}) {
+    const parser = createParser(String(text ?? ''), {...LIMITS, ...limits});
+    while (!parser.done) {
+        parser.step();
+        if (!parser.done) await new Promise(r => setImmediate(r));
+    }
+    return parser.root;
+}
+
+/** Synchronous form, for small inputs and tests. */
+export function parseXmlSync(text, limits = {}) {
+    const parser = createParser(String(text ?? ''), {...LIMITS, ...limits, sliceTokens: Infinity});
+    while (!parser.done) parser.step();
+    return parser.root;
+}
+
+function createParser(src, lim) {
+    let i = 0;
+    let nodes = 0;
+    let root = null;
+    // Each frame: {node, ns: Map(prefix -> canonical|null), textParts: []}
+    const stack = [];
+    const state = {done: false, root: null, step};
+    // A leading byte-order mark.
+    if (src.charCodeAt(0) === 0xfeff) i = 1;
+
+    function fail(msg) { throw new XmlError(msg, i); }
+
+    function canonicalName(raw, ns) {
+        const colon = raw.indexOf(':');
+        if (colon === -1) return raw;
+        const prefix = raw.slice(0, colon);
+        const mapped = ns.get(prefix);
+        return `${mapped || prefix}:${raw.slice(colon + 1)}`;
+    }
+
+    function addText(t) {
+        if (!stack.length) {
+            if (/\S/.test(t)) fail('Text outside the document element');
+            return;
+        }
+        stack[stack.length - 1].textParts.push(t);
+    }
+
+    function openTag(body, selfClosing) {
+        const m = /^([^\s/>]+)/.exec(body);
+        if (!m) fail('An element without a name');
+        const rawName = m[1];
+        if (rawName.length > lim.maxNameLength || !NAME_RE.test(rawName)) fail(`Not an element name: "${rawName.slice(0, 40)}"`);
+        if (stack.length >= lim.maxDepth) fail('Elements are nested too deeply');
+        if (root && !stack.length) fail('More than one document element');
+        if (++nodes > lim.maxNodes) fail('Too many elements');
+        const rest = body.slice(rawName.length);
+        const rawAttrs = {};
+        let count = 0;
+        ATTR_RE.lastIndex = 0;
+        let a;
+        while ((a = ATTR_RE.exec(rest))) {
+            if (++count > lim.maxAttributes) fail('Too many attributes on one element');
+            const value = a[3] !== undefined ? a[3] : a[4];
+            if (value.indexOf('<') !== -1) fail('A "<" inside an attribute value');
+            rawAttrs[a[1]] = decodeEntities(value);
+        }
+        const parentNs = stack.length ? stack[stack.length - 1].ns : new Map();
+        let ns = parentNs;
+        for (const [k, v] of Object.entries(rawAttrs)) {
+            if (k.startsWith('xmlns:')) {
+                if (ns === parentNs) ns = new Map(parentNs);
+                ns.set(k.slice(6), canonicalPrefix(v));
+            }
+        }
+        const attrs = {};
+        for (const [k, v] of Object.entries(rawAttrs)) {
+            if (k === 'xmlns' || k.startsWith('xmlns:')) continue;
+            attrs[canonicalName(k, ns)] = v;
+        }
+        const node = {name: canonicalName(rawName, ns), attrs, children: [], text: ''};
+        if (stack.length) stack[stack.length - 1].node.children.push(node);
+        else root = node;
+        if (selfClosing) return;
+        stack.push({node, ns, rawName, textParts: []});
+    }
+
+    function closeTag(rawName) {
+        const top = stack.pop();
+        if (!top) fail(`A closing </${rawName}> with nothing open`);
+        if (top.rawName !== rawName) fail(`</${rawName}> closes <${top.rawName}>`);
+        top.node.text = top.textParts.join('');
+    }
+
+    function step() {
+        let tokens = 0;
+        const n = src.length;
+        while (i < n && tokens < lim.sliceTokens) {
+            tokens++;
+            const lt = src.indexOf('<', i);
+            if (lt === -1) {
+                addText(decodeEntities(src.slice(i)));
+                i = n;
+                break;
+            }
+            if (lt > i) {
+                addText(decodeEntities(src.slice(i, lt)));
+                i = lt;
+                continue;
+            }
+            // At a '<'.
+            if (src.startsWith('<![CDATA[', i)) {
+                const end = src.indexOf(']]>', i + 9);
+                if (end === -1) fail('A CDATA section that never ends');
+                addText(src.slice(i + 9, end));
+                i = end + 3;
+            } else if (src.startsWith('<!--', i)) {
+                const end = src.indexOf('-->', i + 4);
+                if (end === -1) fail('A comment that never ends');
+                i = end + 3;
+            } else if (src.startsWith('<?', i)) {
+                const end = src.indexOf('?>', i + 2);
+                if (end === -1) fail('A processing instruction that never ends');
+                i = end + 2;
+            } else if (/^<!DOCTYPE/i.test(src.slice(i, i + 9))) {
+                fail('The file declares a DOCTYPE. WordPress exports never do, and a DOCTYPE is how entity attacks get in - refused');
+            } else if (/^<!ENTITY/i.test(src.slice(i, i + 8))) {
+                fail('The file declares an entity - refused');
+            } else if (src[i + 1] === '!') {
+                fail('An unexpected "<!" declaration');
+            } else if (src[i + 1] === '/') {
+                const end = src.indexOf('>', i + 2);
+                if (end === -1) fail('A closing tag that never ends');
+                closeTag(src.slice(i + 2, end).trim());
+                i = end + 1;
+            } else {
+                const end = findTagEnd(i + 1);
+                if (end === -1) fail('A tag that never ends');
+                let body = src.slice(i + 1, end);
+                const selfClosing = body.endsWith('/');
+                if (selfClosing) body = body.slice(0, -1);
+                openTag(body, selfClosing);
+                i = end + 1;
+            }
+        }
+        if (i >= n) {
+            if (stack.length) fail(`<${stack[stack.length - 1].rawName}> is never closed`);
+            if (!root) fail('No document element');
+            state.done = true;
+            state.root = root;
+        }
+    }
+
+    /** The '>' that ends a start tag, skipping any inside quoted attribute values. */
+    function findTagEnd(from) {
+        let q = '';
+        for (let j = from; j < src.length; j++) {
+            const c = src[j];
+            if (q) { if (c === q) q = ''; continue; }
+            if (c === '"' || c === "'") q = c;
+            else if (c === '>') return j;
+            else if (c === '<') fail('A "<" inside a tag');
+        }
+        return -1;
+    }
+
+    return state;
+}
+
+// ---- Reading the tree ----------------------------------------------------
+
+/** The first child element called `name`, or null. */
+export function child(node, name) {
+    if (!node) return null;
+    for (const c of node.children) if (c.name === name) return c;
+    return null;
+}
+
+/** Every child element called `name`. */
+export function children(node, name) {
+    return node ? node.children.filter(c => c.name === name) : [];
+}
+
+/** The text of the first child called `name` ('' when absent), trimmed unless `raw`. */
+export function textOf(node, name, {raw = false} = {}) {
+    const c = child(node, name);
+    if (!c) return '';
+    return raw ? c.text : c.text.trim();
+}