domma-cms 0.55.1 → 0.66.0

package/plugins/_lib/mail/vacationRunner.js

@@ -0,0 +1,114 @@
+/**
+ * Sending the away message.
+ *
+ * The decision - and every reason not to - is `_lib/admin/mail/vacation.js`,
+ * which is pure. This is the half that talks to SMTP, and it is deliberately
+ * thin: an auto-responder's bugs are decisions, not transport, and a decision
+ * that lives behind a mail server is a decision nobody can test.
+ *
+ * ## The two halves of not causing a loop
+ *
+ * `shouldAutoReply` refuses to answer anything that announced itself as
+ * automatic. `autoReplyHeaders` makes OUR reply announce itself the same way,
+ * so the responder at the far end refuses it in turn. Either half alone
+ * leaves a loop that only stops when somebody notices.
+ *
+ * @module _lib/mail/vacationRunner
+ */
+import {
+    autoReplyHeaders,
+    isActive,
+    normaliseVacation,
+    replySubject,
+    shouldAutoReply
+} from '../admin/mail/vacation.js';
+import {textToHtml} from '../admin/mail/identity.js';
+import {sendMessage} from './send.js';
+
+/**
+ * How many away messages may go out in one sync pass.
+ *
+ * A ceiling on the blast radius of a mistake. If something has gone wrong -
+ * a guard that does not hold, a folder full of mail that suddenly looks new -
+ * the damage is bounded at ten messages rather than at the size of the
+ * mailbox, and the next pass will do ten more only if it is still right to.
+ */
+const MAX_PER_PASS = 10;
+
+/**
+ * Answer whatever has just arrived and deserves an answer.
+ *
+ * Must be called with NO mailbox lock held - it sends, which opens its own
+ * connections. Failures are collected rather than thrown: one message that
+ * could not be answered must not stop the rest, and it must certainly not
+ * fail the sync pass it is riding on.
+ *
+ * @param   {{pool: object, store: object, account: object, poolKey: string,
+ *            connection: object, smtp: object, messages: object[],
+ *            config: object, addresses: string[], now?: Date}} deps
+ * @returns {Promise<{considered: number, replied: number, skipped: object[], errors: string[]}>}
+ */
+export async function runVacation({
+    pool, store, account, poolKey, connection, smtp, messages, config, addresses, now = new Date()
+}) {
+    const report = {considered: messages?.length ?? 0, replied: 0, skipped: [], errors: []};
+
+    const vacation = normaliseVacation(account);
+    if (!isActive(vacation, now)) return report;
+    // Nothing to send it with. Reported rather than silent: a mailbox with an
+    // away message switched on and no outgoing server is a mailbox whose
+    // owner believes people are being answered.
+    if (!smtp) {
+        report.errors.push('No outgoing server is configured, so nothing could be answered.');
+        return report;
+    }
+
+    for (const message of messages ?? []) {
+        if (report.replied >= MAX_PER_PASS) break;
+
+        const sender = (message.from ?? [])[0]?.address ?? '';
+        const lastRepliedAt = sender ? await store.lastAutoReply(account.id, sender) : null;
+
+        const verdict = shouldAutoReply({message, vacation, addresses, lastRepliedAt, now});
+        if (!verdict.reply) {
+            report.skipped.push({uid: message.uid, reason: verdict.reason});
+            continue;
+        }
+
+        try {
+            await sendMessage({
+                smtp,
+                draft: {
+                    to: [{name: (message.from ?? [])[0]?.name ?? '', address: sender}],
+                    subject: replySubject(vacation, message.subject),
+                    body: vacation.bodyText,
+                    html: vacation.bodyHtml || textToHtml(vacation.bodyText),
+                    // Threaded onto what they sent, so the answer arrives
+                    // under their own message rather than as a new one.
+                    inReplyTo: message.messageId ?? null,
+                    references: message.messageId ? [message.messageId] : []
+                },
+                pool,
+                poolKey,
+                connection,
+                allowInsecureTLS: config.allowInsecureTLS === true,
+                // The half that protects everybody else.
+                headers: autoReplyHeaders(),
+                // Not filed. One holiday produces a hundred of these, and a
+                // Sent folder that is mostly "Out of office" is one nobody can
+                // find anything in - the reply log is the audit trail instead.
+                fileCopy: false
+            });
+
+            // Recorded AFTER it has gone. The other order would mean a send
+            // that failed still counted as "already told", and that person
+            // would never hear anything.
+            await store.noteAutoReply(account.id, sender, now);
+            report.replied += 1;
+        } catch (err) {
+            report.errors.push(`${sender}: ${err.message}`);
+        }
+    }
+
+    return report;
+}

package/plugins/_lib/mail/write.js

@@ -0,0 +1,473 @@
+/**
+ * Changing mail, rather than reading it.
+ *
+ * Everything here needs a read-write mailbox, which is why it is a separate
+ * module rather than more routes beside the read surface: the free edition
+ * registers that surface and must never gain any of this by accident.
+ *
+ * Each operation applies on the server first and updates the mirror second.
+ * The other order is tempting - the UI feels faster - but it means a failed
+ * write leaves the mirror claiming something that is not true, and the next
+ * sync silently reverts it, which reads as the application losing the change.
+ *
+ * @module _lib/mail/write
+ */
+import {ENVELOPE_QUERY, toRecord} from './envelope.js';
+
+/** Flags a caller may set. Anything else is refused rather than passed through. */
+export const WRITABLE_FLAGS = new Set(['\\Seen', '\\Flagged', '\\Answered', '\\Draft']);
+
+/**
+ * Check a requested flag change is something we are willing to make.
+ *
+ * `\Deleted` is deliberately absent: deleting is its own operation with its
+ * own consequences, not a flag a generic endpoint should be able to set.
+ *
+ * @param   {string[]} flags
+ * @returns {{ok: true} | {ok: false, error: string}}
+ */
+export function validateFlags(flags) {
+    if (!Array.isArray(flags)) return {ok: false, error: 'Flags must be an array.'};
+    const bad = flags.filter(flag => !WRITABLE_FLAGS.has(flag));
+    if (bad.length) {
+        return {ok: false, error: `Unsupported flag(s): ${bad.join(', ')}.`};
+    }
+    return {ok: true};
+}
+
+/**
+ * Add or remove flags on one message.
+ *
+ * @param   {{pool: object, store: object|null, account: object, poolKey: string,
+ *            connection: object, folder: string, uid: number,
+ *            add?: string[], remove?: string[]}} options
+ * @returns {Promise<{uid: number, flags: string[]}>}
+ */
+export async function setMessageFlags({
+    pool, store, account, poolKey, connection, folder, uid, add = [], remove = []
+}) {
+    const flags = await pool.withMailbox(poolKey, connection, folder, async (client) => {
+        if (add.length) await client.messageFlagsAdd({uid: String(uid)}, add, {uid: true});
+        if (remove.length) await client.messageFlagsRemove({uid: String(uid)}, remove, {uid: true});
+
+        // Read back rather than assume: another client may have changed
+        // something in between, and the mirror should hold what is true on the
+        // server rather than what we asked for.
+        const fetched = await client.fetchOne(uid, {flags: true}, {uid: true});
+        return [...(fetched?.flags ?? [])];
+    }, {writable: true});
+
+    if (store) {
+        await store.setFlags(account.id, folder, [{uid, flags}]);
+    }
+
+    return {uid, flags};
+}
+
+/**
+ * Put the moved messages into the destination's mirror straight away.
+ *
+ * Without this a move takes a message out of the source mirror and the
+ * destination does not learn of it until its next poll - so it is in neither
+ * folder for up to the poll interval, which reads as having lost it. Worst
+ * where it matters most: "Not spam" is supposed to put mail back in the Inbox,
+ * and the whole point is seeing it arrive.
+ *
+ * Only for a folder the mirror already tracks. An untracked destination is
+ * listed live from IMAP, so it is already correct, and writing rows for it
+ * would seed a mirror nothing asked for.
+ *
+ * Failure here is not failure of the move: the message HAS moved, and the
+ * next sync will pick it up regardless. Reported, never thrown.
+ *
+ * @param   {{pool: object, store: object|null, account: object, poolKey: string,
+ *            connection: object, destination: string, uids: number[]}} options
+ * @returns {Promise<boolean>} whether the destination mirror was updated
+ */
+async function ingestMoved({pool, store, account, poolKey, connection, destination, uids}) {
+    if (!store || !uids.length) return false;
+
+    try {
+        const state = await store.getFolder(account.id, destination);
+        if (!state?.lastSyncAt) return false;
+
+        const set = uids.join(',');
+        const rows = [];
+        await pool.withMailbox(poolKey, connection, destination, async (client) => {
+            for await (const message of client.fetch(set, ENVELOPE_QUERY, {uid: true})) {
+                rows.push(toRecord(message));
+            }
+        });
+
+        if (rows.length) await store.putMessages(account.id, destination, rows);
+        return rows.length > 0;
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * Move one message to another folder.
+ *
+ * The mirror entry is removed rather than rewritten: the message gets a new
+ * UID in the destination, and inventing one would put a record in the store
+ * that matches nothing on the server. The destination picks it up on its next
+ * sync, if it is mirrored at all.
+ *
+ * @param   {{pool: object, store: object|null, account: object, poolKey: string,
+ *            connection: object, folder: string, uid: number, destination: string}} options
+ * @returns {Promise<{moved: boolean, destination: string}>}
+ */
+export async function moveMessage({
+    pool, store, account, poolKey, connection, folder, uid, destination
+}) {
+    const result = await pool.withMailbox(poolKey, connection, folder, async (client) => {
+        return client.messageMove({uid: String(uid)}, destination, {uid: true});
+    }, {writable: true});
+
+    if (store) {
+        await store.removeMessages(account.id, folder, [uid]);
+    }
+
+    // Where the server supports UIDPLUS it tells us the UID the message was
+    // given at its destination, which is the only way back: an undo has to
+    // name the message it is moving, and it is not the one we sent. Without
+    // UIDPLUS there is no new UID to report, and the caller must not offer an
+    // undo it cannot perform.
+    const raw = result?.uidMap?.get?.(uid) ?? result?.uidMap?.get?.(String(uid)) ?? null;
+    const newUid = raw === null ? null : Number(raw);
+
+    // Read-only mailboxes are opened for this, so it cannot mark anything seen.
+    const mirrored = newUid === null
+        ? false
+        : await ingestMoved({pool, store, account, poolKey, connection, destination, uids: [newUid]});
+
+    return {moved: true, destination, newUid, mirrored};
+}
+
+/**
+ * Delete a message.
+ *
+ * Deleting mail means moving it to Trash, not destroying it - that is what
+ * every mail client means by the word, and what a user expects to be able to
+ * undo. Only when the server offers no Trash, or the message is already in it,
+ * does this fall back to the IMAP meaning: flag `\\Deleted` and expunge, which
+ * is irreversible.
+ *
+ * This is deliberately its own operation rather than a flag the generic
+ * endpoint may set. `\\Deleted` through a flags API would let a stray call
+ * destroy mail with no destination, no fallback and no name saying so.
+ *
+ * @param   {{pool: object, store: object|null, account: object, poolKey: string,
+ *            connection: object, folder: string, uid: number, trash?: string|null}} options
+ * @returns {Promise<{deleted: true, movedTo: string|null, expunged: boolean}>}
+ */
+export async function deleteMessage({
+    pool, store, account, poolKey, connection, folder, uid, trash = null
+}) {
+    // Find Trash by SPECIAL-USE rather than by name: it is "Bin" on some
+    // servers and localised on others, and guessing the name is how mail ends
+    // up expunged on a server that had somewhere to put it.
+    let destination = trash;
+    if (destination === null) {
+        const boxes = await pool.withClient(poolKey, connection, client => client.list());
+        destination = boxes.find(box => box.specialUse === '\\Trash')?.path ?? null;
+    }
+
+    if (destination && destination !== folder) {
+        const moved = await moveMessage({
+            pool, store, account, poolKey, connection, folder, uid, destination
+        });
+        return {deleted: true, movedTo: destination, newUid: moved.newUid, expunged: false, mirrored: moved.mirrored};
+    }
+
+    // No Trash, or already there: this is the irreversible path.
+    await pool.withMailbox(poolKey, connection, folder, async (client) => {
+        await client.messageFlagsAdd({uid: String(uid)}, ['\\Deleted'], {uid: true});
+        await client.messageDelete({uid: String(uid)}, {uid: true});
+    }, {writable: true});
+
+    if (store) await store.removeMessages(account.id, folder, [uid]);
+    return {deleted: true, movedTo: null, newUid: null, expunged: true};
+}
+
+/**
+ * Normalise a UID set for an IMAP command.
+ *
+ * IMAP takes a comma-separated set, so a hundred messages are one command
+ * rather than a hundred round trips. Values are coerced and validated here
+ * because they arrive from a request body.
+ *
+ * @param   {unknown} uids
+ * @returns {{ok: true, uids: number[], set: string} | {ok: false, error: string}}
+ */
+export function normaliseUids(uids) {
+    if (!Array.isArray(uids) || !uids.length) {
+        return {ok: false, error: 'No messages were selected.'};
+    }
+    const clean = [...new Set(uids.map(Number))].filter(n => Number.isInteger(n) && n > 0);
+    if (!clean.length) return {ok: false, error: 'No valid message ids were given.'};
+    if (clean.length > 500) return {ok: false, error: 'Too many messages at once - select fewer than 500.'};
+    return {ok: true, uids: clean, set: clean.join(',')};
+}
+
+/**
+ * Add or remove flags across many messages at once.
+ *
+ * @param   {object} options - as setMessageFlags, but with `uids` and `set`
+ * @returns {Promise<{updated: {uid: number, flags: string[]}[]}>}
+ */
+export async function setFlagsBulk({
+    pool, store, account, poolKey, connection, folder, uids, set, add = [], remove = []
+}) {
+    const updated = await pool.withMailbox(poolKey, connection, folder, async (client) => {
+        if (add.length) await client.messageFlagsAdd({uid: set}, add, {uid: true});
+        if (remove.length) await client.messageFlagsRemove({uid: set}, remove, {uid: true});
+
+        // Read back what the server now holds, for the same reason the single
+        // version does: another client may have changed something, and the
+        // mirror should hold what is true rather than what was asked for.
+        const rows = [];
+        for await (const message of client.fetch(set, {uid: true, flags: true}, {uid: true})) {
+            rows.push({uid: message.uid, flags: [...(message.flags ?? [])]});
+        }
+        return rows;
+    }, {writable: true});
+
+    if (store && updated.length) await store.setFlags(account.id, folder, updated);
+    return {updated};
+}
+
+/**
+ * Move many messages at once.
+ *
+ * @param   {object} options
+ * @returns {Promise<{moved: number, destination: string, uidMap: Object.<string, number>}>}
+ */
+export async function moveBulk({
+    pool, store, account, poolKey, connection, folder, uids, set, destination
+}) {
+    const result = await pool.withMailbox(poolKey, connection, folder, async (client) => {
+        return client.messageMove({uid: set}, destination, {uid: true});
+    }, {writable: true});
+
+    if (store) await store.removeMessages(account.id, folder, uids);
+
+    // Carried so a bulk move can be undone the same way a single one is.
+    const uidMap = {};
+    if (result?.uidMap?.forEach) {
+        result.uidMap.forEach((to, from) => { uidMap[String(from)] = Number(to); });
+    }
+
+    const mirrored = await ingestMoved({
+        pool, store, account, poolKey, connection, destination,
+        uids: Object.values(uidMap)
+    });
+
+    return {moved: uids.length, destination, uidMap, mirrored};
+}
+
+/**
+ * Delete many messages at once.
+ *
+ * Same meaning as the single version: move to Trash where there is one, and
+ * only expunge where there is not.
+ *
+ * @param   {object} options
+ * @returns {Promise<{deleted: number, movedTo: string|null, uidMap: object, expunged: boolean}>}
+ */
+export async function deleteBulk({
+    pool, store, account, poolKey, connection, folder, uids, set
+}) {
+    const boxes = await pool.withClient(poolKey, connection, client => client.list());
+    const trash = boxes.find(box => box.specialUse === '\\Trash')?.path ?? null;
+
+    if (trash && trash !== folder) {
+        const moved = await moveBulk({
+            pool, store, account, poolKey, connection, folder, uids, set, destination: trash
+        });
+        return {deleted: uids.length, movedTo: trash, uidMap: moved.uidMap, expunged: false, mirrored: moved.mirrored};
+    }
+
+    await pool.withMailbox(poolKey, connection, folder, async (client) => {
+        await client.messageFlagsAdd({uid: set}, ['\\Deleted'], {uid: true});
+        await client.messageDelete({uid: set}, {uid: true});
+    }, {writable: true});
+
+    if (store) await store.removeMessages(account.id, folder, uids);
+    return {deleted: uids.length, movedTo: null, uidMap: {}, expunged: true};
+}
+
+/**
+ * The keywords a server-side spam learner watches.
+ *
+ * These are IMAP keywords, not system flags, so a server may refuse them
+ * outright - which is why setting them is best-effort below rather than a
+ * precondition for the move.
+ */
+export const JUNK_KEYWORD = '$Junk';
+export const NOT_JUNK_KEYWORD = '$NotJunk';
+
+/**
+ * Decide what marking a message as spam (or not) should actually do.
+ *
+ * Pure, so the interesting part - which is the folder arithmetic, not the
+ * IMAP - can be tested without a server.
+ *
+ * Marking as spam moves to Junk. Marking as NOT spam only moves when the
+ * message is sitting in Junk: saying "this isn't spam" about something already
+ * filed in a project folder is a correction to the learner, not a request to
+ * have it yanked back to the Inbox.
+ *
+ * @param   {{spam: boolean, folder: string, junkFolder: string|null,
+ *            inboxFolder?: string}} options
+ * @returns {{destination: string|null, add: string[], remove: string[]}}
+ */
+export function planSpamMove({spam, folder, junkFolder, inboxFolder = 'INBOX'}) {
+    const inJunk = Boolean(junkFolder) && folder === junkFolder;
+
+    if (spam) {
+        return {
+            destination: junkFolder && !inJunk ? junkFolder : null,
+            add: [JUNK_KEYWORD],
+            remove: [NOT_JUNK_KEYWORD]
+        };
+    }
+
+    return {
+        destination: inJunk && inboxFolder !== folder ? inboxFolder : null,
+        add: [NOT_JUNK_KEYWORD],
+        remove: [JUNK_KEYWORD]
+    };
+}
+
+/**
+ * Where this server keeps junk mail, by SPECIAL-USE.
+ *
+ * Never by name, for the reason Trash is not found by name either: it is
+ * "Spam" on one server, "Junk E-mail" on the next, and localised on the one
+ * after that.
+ *
+ * @param   {object} pool
+ * @param   {string} poolKey
+ * @param   {object} connection
+ * @returns {Promise<string|null>}
+ */
+export async function findJunkFolder(pool, poolKey, connection) {
+    const boxes = await pool.withClient(poolKey, connection, client => client.list());
+    return boxes.find(box => box.specialUse === '\\Junk')?.path ?? null;
+}
+
+/**
+ * Apply the keywords, tolerating a server that will not have them.
+ *
+ * A server without PERMANENTFLAGS for arbitrary keywords rejects these, and
+ * that must not cost the move - the folder is what the person asked for, the
+ * keyword is a hint to the filter. Reported honestly either way.
+ *
+ * @param   {object} options
+ * @returns {Promise<{ok: boolean, rows: {uid: number, flags: string[]}[]}>}
+ */
+async function applyJunkKeywords({pool, poolKey, connection, folder, set, add, remove}) {
+    try {
+        const rows = await pool.withMailbox(poolKey, connection, folder, async (client) => {
+            if (add.length) await client.messageFlagsAdd({uid: set}, add, {uid: true});
+            if (remove.length) await client.messageFlagsRemove({uid: set}, remove, {uid: true});
+
+            // Read back rather than assume, exactly as setMessageFlags does:
+            // a server may have refused the keyword, and the caller has to be
+            // able to tell that from having applied it.
+            const out = [];
+            for await (const message of client.fetch(set, {uid: true, flags: true}, {uid: true})) {
+                out.push({uid: message.uid, flags: [...(message.flags ?? [])]});
+            }
+            return out;
+        }, {writable: true});
+        return {ok: true, rows};
+    } catch {
+        return {ok: false, rows: []};
+    }
+}
+
+/**
+ * Mark one message as spam, or as not spam.
+ *
+ * Keywords first, move second: after the move the message has a new UID in
+ * another folder, and the one held here no longer addresses it.
+ *
+ * @param   {{pool: object, store: object|null, account: object, poolKey: string,
+ *            connection: object, folder: string, uid: number, spam: boolean,
+ *            junkFolder?: string|null, inboxFolder?: string}} options
+ * @returns {Promise<{spam: boolean, movedTo: string|null, newUid: number|null,
+ *                    keywords: boolean}>}
+ */
+export async function setSpam({
+    pool, store, account, poolKey, connection, folder, uid,
+    spam, junkFolder = null, inboxFolder = 'INBOX'
+}) {
+    const junk = junkFolder ?? await findJunkFolder(pool, poolKey, connection);
+    const plan = planSpamMove({spam, folder, junkFolder: junk, inboxFolder});
+
+    const applied = await applyJunkKeywords({
+        pool, poolKey, connection, folder, set: String(uid),
+        add: plan.add, remove: plan.remove
+    });
+    const keywords = applied.ok;
+
+    if (!plan.destination) {
+        // Nothing moves, so the mirror keeps the row - and it has to carry the
+        // new keyword, or the menu goes on offering the action just taken.
+        if (store && applied.rows.length) {
+            await store.setFlags(account.id, folder, applied.rows);
+        }
+        return {
+            spam, movedTo: null, newUid: null, keywords,
+            flags: applied.rows[0]?.flags ?? null, mirrored: false
+        };
+    }
+
+    const moved = await moveMessage({
+        pool, store, account, poolKey, connection, folder, uid,
+        destination: plan.destination
+    });
+    return {spam, movedTo: plan.destination, newUid: moved.newUid, keywords, mirrored: moved.mirrored};
+}
+
+/**
+ * Mark many messages as spam, or as not spam.
+ *
+ * @param   {object} options - as setSpam, but with `uids` and `set`
+ * @returns {Promise<{spam: boolean, count: number, movedTo: string|null,
+ *                    uidMap: object, keywords: boolean}>}
+ */
+export async function setSpamBulk({
+    pool, store, account, poolKey, connection, folder, uids, set,
+    spam, junkFolder = null, inboxFolder = 'INBOX'
+}) {
+    const junk = junkFolder ?? await findJunkFolder(pool, poolKey, connection);
+    const plan = planSpamMove({spam, folder, junkFolder: junk, inboxFolder});
+
+    const applied = await applyJunkKeywords({
+        pool, poolKey, connection, folder, set, add: plan.add, remove: plan.remove
+    });
+    const keywords = applied.ok;
+
+    if (!plan.destination) {
+        if (store && applied.rows.length) {
+            await store.setFlags(account.id, folder, applied.rows);
+        }
+        return {
+            spam, count: uids.length, movedTo: null, uidMap: {}, keywords,
+            updated: applied.rows, mirrored: false
+        };
+    }
+
+    const moved = await moveBulk({
+        pool, store, account, poolKey, connection, folder, uids, set,
+        destination: plan.destination
+    });
+    return {
+        spam, count: uids.length, movedTo: plan.destination,
+        uidMap: moved.uidMap, keywords, mirrored: moved.mirrored
+    };
+}

package/plugins/_lib/schemaSync.js

@@ -0,0 +1,83 @@
+/**
+ * Keeping an installed collection's schema in step with the one a plugin ships.
+ *
+ * `setupPlugin()` creates a plugin's collections on first enable and then never
+ * looks at them again - `if (!existing) createCollection(...)`. So a field added
+ * to a shipped schema reaches a FRESH install and nowhere else: every existing
+ * site keeps the field list it was created with. The values still store and read
+ * back, because entries are plain objects, but nothing that reads the schema -
+ * the collection editor, the entries screen, `required` validation - knows the
+ * field is there.
+ *
+ * This closes that gap, and only ever ADDS. It never removes, renames or
+ * reorders, because a site may have edited its own schema and a plugin update
+ * is no reason to throw that away.
+ *
+ * @module _lib/schemaSync
+ */
+import fs from 'fs/promises';
+
+/**
+ * Add any field the shipped schema declares that the installed one lacks.
+ *
+ * @param   {string} slug              installed collection slug
+ * @param   {string} shippedSchemaPath absolute path to the plugin's schema.json
+ * @param   {object} services          `{getCollection, updateCollection}`
+ * @returns {Promise<string[]>} the names of the fields that were added
+ */
+export async function ensureSchemaFields(slug, shippedSchemaPath, services) {
+    const { getCollection, updateCollection } = services;
+
+    const installed = await getCollection(slug).catch(() => null);
+    if (!installed) return [];            // not installed yet; setupPlugin will create it
+
+    let shipped;
+    try {
+        shipped = JSON.parse(await fs.readFile(shippedSchemaPath, 'utf8'));
+    } catch {
+        return [];                        // no shipped schema to compare against
+    }
+
+    const have = new Set((installed.fields ?? []).map(f => f.name));
+    const missing = (shipped.fields ?? []).filter(f => f.name && !have.has(f.name));
+    if (!missing.length) return [];
+
+    await updateCollection(slug, { fields: [...(installed.fields ?? []), ...missing] });
+    return missing.map(f => f.name);
+}
+
+/**
+ * The same, for every collection a plugin ships.
+ *
+ * @param   {string} collectionsDir  the plugin's `collections/` directory
+ * @param   {object} services        `{getCollection, updateCollection}`
+ * @param   {object} [log]           anything with `.info`; console by default
+ * @returns {Promise<void>}
+ */
+export async function syncPluginSchemas(collectionsDir, services, log = console) {
+    let dirs;
+    try {
+        dirs = await fs.readdir(collectionsDir, { withFileTypes: true });
+    } catch {
+        return;
+    }
+
+    for (const dir of dirs.filter(d => d.isDirectory())) {
+        const schemaPath = `${collectionsDir}/${dir.name}/schema.json`;
+        let slug;
+        try {
+            slug = JSON.parse(await fs.readFile(schemaPath, 'utf8')).slug;
+        } catch {
+            continue;
+        }
+        if (!slug) continue;
+
+        try {
+            const added = await ensureSchemaFields(slug, schemaPath, services);
+            if (added.length) log.info?.(`[schemaSync] ${slug}: added ${added.join(', ')}`);
+        } catch (err) {
+            // A schema that will not update is not a reason to refuse to boot.
+            log.warn?.(`[schemaSync] ${slug}: ${err.message}`);
+        }
+    }
+}

package/plugins/_template/admin/templates/index.html

@@ -1,9 +1,9 @@
-<div class="view-header d-flex justify-content-between align-items-center mb-4">
+<div class="view-header">
     <div>
-        <h1 class="view-title">PLUGIN_DISPLAY_NAME</h1>
-        <p class="view-subtitle text-muted">Manage PLUGIN_DISPLAY_NAME.</p>
+        <h1>PLUGIN_DISPLAY_NAME</h1>
+        <p class="text-muted text-sm mb-0">Manage PLUGIN_DISPLAY_NAME.</p>
     </div>
-    <div class="d-flex gap-2">
+    <div class="view-header-actions">
         <button id="btn-new-item" class="btn btn-primary">
             <span data-icon="plus"></span> New Item
         </button>