@forumone/throughline 0.0.0-stage → 1.0.0-next.0

package/dist/references/find.js

@@ -0,0 +1,142 @@
+import { couldReference, referencesIn } from './walk.js';
+const LABEL_FIELDS = ['title', 'name', 'slug', 'heading'];
+function labelOf(doc) {
+    for (const key of LABEL_FIELDS) {
+        const value = doc[key];
+        if (typeof value === 'string' && value.trim() !== '')
+            return value;
+    }
+    return `#${String(doc['id'])}`;
+}
+/** The config's block registry plus any extras, by slug. */
+export function blockRegistry(payload, extra = []) {
+    const registry = new Map();
+    const configured = payload.config.blocks ?? [];
+    for (const block of [...configured, ...extra])
+        registry.set(block.slug, block);
+    return registry;
+}
+/** Every row and global that could reference `target`, published and draft. */
+async function eachSource(payload, target, req, visit) {
+    for (const collection of payload.config.collections) {
+        if (!couldReference(collection.fields, target))
+            continue;
+        const passes = collection.versions ? [false, true] : [false];
+        for (const draft of passes) {
+            const result = await payload.find({
+                collection: collection.slug,
+                depth: 0,
+                // Join fields would add a subquery per row, and the walk reads only
+                // stored fields. Typed per collection, hence the cast.
+                joins: false,
+                limit: 0,
+                pagination: false,
+                overrideAccess: true,
+                ...(draft ? { draft: true } : {}),
+                ...(req ? { req } : {}),
+            });
+            for (const doc of result.docs) {
+                visit({
+                    collection: collection.slug,
+                    id: doc['id'],
+                    label: labelOf(doc),
+                    fields: collection.fields,
+                    data: doc,
+                });
+            }
+        }
+    }
+    for (const global of payload.config.globals) {
+        if (!couldReference(global.fields, target))
+            continue;
+        const data = (await payload.findGlobal({
+            slug: global.slug,
+            depth: 0,
+            overrideAccess: true,
+            ...(req ? { req } : {}),
+        }));
+        const label = typeof global.label === 'string' ? global.label : global.slug;
+        visit({
+            collection: global.slug,
+            id: global.slug,
+            label,
+            fields: global.fields,
+            data,
+            global: true,
+        });
+    }
+}
+/**
+ * Every document and global that references `collection`'s document `id`,
+ * merged across the published and draft states.
+ */
+export async function findReferences(payload, target, options = {}) {
+    const blocks = blockRegistry(payload, options.blocks);
+    const found = new Map();
+    await eachSource(payload, target.collection, options.req, (source) => {
+        // The document itself is not a reference to itself.
+        if (!source.global &&
+            source.collection === target.collection &&
+            String(source.id) === String(target.id)) {
+            return;
+        }
+        const references = referencesIn(source.fields, source.data, {
+            collection: target.collection,
+            blocks,
+        }).filter((reference) => String(reference.id) === String(target.id));
+        if (references.length === 0)
+            return;
+        const key = `${source.global ? 'global' : 'collection'}:${source.collection}:${String(source.id)}`;
+        const existing = found.get(key);
+        if (existing) {
+            // Seen as published and as draft: keep the union of paths.
+            const seen = new Set(existing.references.map((r) => r.path));
+            for (const reference of references) {
+                if (!seen.has(reference.path))
+                    existing.references.push(reference);
+            }
+            existing.viaBlock ||= references.some((r) => r.viaBlock);
+            return;
+        }
+        found.set(key, {
+            collection: source.collection,
+            id: source.id,
+            label: source.label,
+            references,
+            viaBlock: references.some((r) => r.viaBlock),
+            ...(source.global ? { global: true } : {}),
+        });
+    });
+    return [...found.values()];
+}
+/**
+ * Every id in `collection` that anything references, from one read of the
+ * whole config. For a caller that needs the answer for a whole library at once
+ * (an "unused media" report) rather than one scan per document. Ids are
+ * strings, since a JSON block and a relationship column disagree on whether an
+ * id is a number.
+ */
+export async function findReferencedIds(payload, collection, options = {}) {
+    const blocks = blockRegistry(payload, options.blocks);
+    const used = new Set();
+    await eachSource(payload, collection, options.req, (source) => {
+        for (const reference of referencesIn(source.fields, source.data, { collection, blocks })) {
+            const id = String(reference.id);
+            // A document naming itself does not make it used.
+            if (!source.global && source.collection === collection && id === String(source.id))
+                continue;
+            used.add(id);
+        }
+    });
+    return used;
+}
+/** One line per document: `pages › Homepage (layout[2] › ImageHero › image)`. */
+export function describeReferences(found, limit = 5) {
+    const lines = found.map((entry) => {
+        const where = entry.references[0]?.path;
+        return `• ${entry.collection} › ${entry.label}${where ? ` (${where})` : ''}`;
+    });
+    const named = lines.slice(0, limit).join('\n');
+    return lines.length > limit ? `${named}\n…and ${lines.length - limit} more.` : named;
+}
+//# sourceMappingURL=find.js.map

package/dist/references/find.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"find.js","sourceRoot":"","sources":["../../src/references/find.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,YAAY,EAAkB,MAAM,WAAW,CAAA;AAuExE,MAAM,YAAY,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,CAAC,CAAA;AAEzD,SAAS,OAAO,CAAC,GAA4B;IAC3C,KAAK,MAAM,GAAG,IAAI,YAAY,EAAE,CAAC;QAC/B,MAAM,KAAK,GAAG,GAAG,CAAC,GAAG,CAAC,CAAA;QACtB,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE;YAAE,OAAO,KAAK,CAAA;IACpE,CAAC;IACD,OAAO,IAAI,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,EAAE,CAAA;AAChC,CAAC;AAED,4DAA4D;AAC5D,MAAM,UAAU,aAAa,CAAC,OAAgB,EAAE,QAA0B,EAAE;IAC1E,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAiB,CAAA;IACzC,MAAM,UAAU,GAAI,OAAO,CAAC,MAAwC,CAAC,MAAM,IAAI,EAAE,CAAA;IACjF,KAAK,MAAM,KAAK,IAAI,CAAC,GAAG,UAAU,EAAE,GAAG,KAAK,CAAC;QAAE,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,CAAA;IAC9E,OAAO,QAAQ,CAAA;AACjB,CAAC;AAWD,+EAA+E;AAC/E,KAAK,UAAU,UAAU,CACvB,OAAgB,EAChB,MAAsB,EACtB,GAA+B,EAC/B,KAA+B;IAE/B,KAAK,MAAM,UAAU,IAAI,OAAO,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC;QACpD,IAAI,CAAC,cAAc,CAAC,UAAU,CAAC,MAAM,EAAE,MAAM,CAAC;YAAE,SAAQ;QAExD,MAAM,MAAM,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAA;QAC5D,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;YAC3B,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC;gBAChC,UAAU,EAAE,UAAU,CAAC,IAAI;gBAC3B,KAAK,EAAE,CAAC;gBACR,oEAAoE;gBACpE,uDAAuD;gBACvD,KAAK,EAAE,KAAc;gBACrB,KAAK,EAAE,CAAC;gBACR,UAAU,EAAE,KAAK;gBACjB,cAAc,EAAE,IAAI;gBACpB,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBACjC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aACxB,CAAC,CAAA;YACF,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAA4C,EAAE,CAAC;gBACtE,KAAK,CAAC;oBACJ,UAAU,EAAE,UAAU,CAAC,IAAI;oBAC3B,EAAE,EAAE,GAAG,CAAC,IAAI,CAAoB;oBAChC,KAAK,EAAE,OAAO,CAAC,GAAG,CAAC;oBACnB,MAAM,EAAE,UAAU,CAAC,MAAM;oBACzB,IAAI,EAAE,GAAG;iBACV,CAAC,CAAA;YACJ,CAAC;QACH,CAAC;IACH,CAAC;IAED,KAAK,MAAM,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QAC5C,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;YAAE,SAAQ;QACpD,MAAM,IAAI,GAAG,CAAC,MAAM,OAAO,CAAC,UAAU,CAAC;YACrC,IAAI,EAAE,MAAM,CAAC,IAAI;YACjB,KAAK,EAAE,CAAC;YACR,cAAc,EAAE,IAAI;YACpB,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACxB,CAAC,CAAuC,CAAA;QACzC,MAAM,KAAK,GAAG,OAAO,MAAM,CAAC,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAA;QAC3E,KAAK,CAAC;YACJ,UAAU,EAAE,MAAM,CAAC,IAAI;YACvB,EAAE,EAAE,MAAM,CAAC,IAAI;YACf,KAAK;YACL,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,IAAI;YACJ,MAAM,EAAE,IAAI;SACb,CAAC,CAAA;IACJ,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,OAAgB,EAChB,MAA2D,EAC3D,UAAiC,EAAE;IAEnC,MAAM,MAAM,GAAG,aAAa,CAAC,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,CAAA;IACrD,MAAM,KAAK,GAAG,IAAI,GAAG,EAA8B,CAAA;IAEnD,MAAM,UAAU,CAAC,OAAO,EAAE,MAAM,CAAC,UAAU,EAAE,OAAO,CAAC,GAAG,EAAE,CAAC,MAAM,EAAE,EAAE;QACnE,oDAAoD;QACpD,IACE,CAAC,MAAM,CAAC,MAAM;YACd,MAAM,CAAC,UAAU,KAAK,MAAM,CAAC,UAAU;YACvC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,EACvC,CAAC;YACD,OAAM;QACR,CAAC;QACD,MAAM,UAAU,GAAG,YAAY,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,IAAI,EAAE;YAC1D,UAAU,EAAE,MAAM,CAAC,UAAU;YAC7B,MAAM;SACP,CAAC,CAAC,MAAM,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAA;QACpE,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC;YAAE,OAAM;QAEnC,MAAM,GAAG,GAAG,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,YAAY,IAAI,MAAM,CAAC,UAAU,IAAI,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,CAAA;QAClG,MAAM,QAAQ,GAAG,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;QAC/B,IAAI,QAAQ,EAAE,CAAC;YACb,2DAA2D;YAC3D,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAA;YAC5D,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;gBACnC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,CAAC;oBAAE,QAAQ,CAAC,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC,CAAA;YACpE,CAAC;YACD,QAAQ,CAAC,QAAQ,KAAK,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAA;YACxD,OAAM;QACR,CAAC;QACD,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE;YACb,UAAU,EAAE,MAAM,CAAC,UAAU;YAC7B,EAAE,EAAE,MAAM,CAAC,EAAE;YACb,KAAK,EAAE,MAAM,CAAC,KAAK;YACnB,UAAU;YACV,QAAQ,EAAE,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC;YAC5C,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC3C,CAAC,CAAA;IACJ,CAAC,CAAC,CAAA;IAEF,OAAO,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,CAAA;AAC5B,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,OAAgB,EAChB,UAA0B,EAC1B,UAAiC,EAAE;IAEnC,MAAM,MAAM,GAAG,aAAa,CAAC,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,CAAA;IACrD,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAA;IAC9B,MAAM,UAAU,CAAC,OAAO,EAAE,UAAU,EAAE,OAAO,CAAC,GAAG,EAAE,CAAC,MAAM,EAAE,EAAE;QAC5D,KAAK,MAAM,SAAS,IAAI,YAAY,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,IAAI,EAAE,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC;YACzF,MAAM,EAAE,GAAG,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC,CAAA;YAC/B,kDAAkD;YAClD,IAAI,CAAC,MAAM,CAAC,MAAM,IAAI,MAAM,CAAC,UAAU,KAAK,UAAU,IAAI,EAAE,KAAK,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC;gBAAE,SAAQ;YAC5F,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAA;QACd,CAAC;IACH,CAAC,CAAC,CAAA;IACF,OAAO,IAAI,CAAA;AACb,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,kBAAkB,CAAC,KAAoC,EAAE,KAAK,GAAG,CAAC;IAChF,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE;QAChC,MAAM,KAAK,GAAG,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,IAAI,CAAA;QACvC,OAAO,KAAK,KAAK,CAAC,UAAU,MAAM,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC,KAAK,KAAK,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAA;IAC9E,CAAC,CAAC,CAAA;IACF,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IAC9C,OAAO,KAAK,CAAC,MAAM,GAAG,KAAK,CAAC,CAAC,CAAC,GAAG,KAAK,UAAU,KAAK,CAAC,MAAM,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAA;AACtF,CAAC"}

package/dist/references/guards.d.ts

@@ -0,0 +1,32 @@
+import { type Block, type CollectionBeforeChangeHook, type CollectionBeforeDeleteHook, type CollectionSlug } from 'payload';
+import { type DocumentReferences } from './find.js';
+export interface ReferenceGuardOptions {
+    /** What the document is called in the message: "file", "person", "term". Default "document". */
+    noun?: string;
+    /**
+     * What deleting it would do to the documents that use it, appended to the
+     * refusal: "deleting it now would untag them without saying so".
+     */
+    consequence?: string;
+    /** Blocks beyond the config's registry. See `FindReferencesOptions.blocks`. */
+    blocks?: readonly Block[];
+}
+type Verb = 'delete' | 'move to the trash';
+/** The refusal an editor reads. Exported so a host can show the same words elsewhere. */
+export declare function referenceRefusal(found: readonly DocumentReferences[], options?: {
+    noun?: string;
+    verb?: Verb;
+    consequence?: string;
+}): string;
+/** Whether this write puts the document in the trash: `deletedAt` set now and not before. */
+export declare function movesToTrash(data: unknown, originalDoc: unknown): boolean;
+/** `beforeDelete`: refuse while anything references the document. */
+export declare function refuseDeleteWhileReferenced(collection: CollectionSlug, options?: ReferenceGuardOptions): CollectionBeforeDeleteHook;
+/**
+ * `beforeChange`: refuse a write that moves the document to the trash while
+ * anything references it. Every other write passes untouched and costs
+ * nothing, since the scan reads the whole config.
+ */
+export declare function refuseTrashWhileReferenced(collection: CollectionSlug, options?: ReferenceGuardOptions): CollectionBeforeChangeHook;
+export {};
+//# sourceMappingURL=guards.d.ts.map

package/dist/references/guards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guards.d.ts","sourceRoot":"","sources":["../../src/references/guards.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,KAAK,EACV,KAAK,0BAA0B,EAC/B,KAAK,0BAA0B,EAC/B,KAAK,cAAc,EAEpB,MAAM,SAAS,CAAA;AAChB,OAAO,EAAsC,KAAK,kBAAkB,EAAE,MAAM,WAAW,CAAA;AA2BvF,MAAM,WAAW,qBAAqB;IACpC,gGAAgG;IAChG,IAAI,CAAC,EAAE,MAAM,CAAA;IACb;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,+EAA+E;IAC/E,MAAM,CAAC,EAAE,SAAS,KAAK,EAAE,CAAA;CAC1B;AAED,KAAK,IAAI,GAAG,QAAQ,GAAG,mBAAmB,CAAA;AAE1C,yFAAyF;AACzF,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,SAAS,kBAAkB,EAAE,EACpC,OAAO,GAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,IAAI,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAO,GACjE,MAAM,CAmBR;AAsDD,6FAA6F;AAC7F,wBAAgB,YAAY,CAAC,IAAI,EAAE,OAAO,EAAE,WAAW,EAAE,OAAO,GAAG,OAAO,CAIzE;AAED,qEAAqE;AACrE,wBAAgB,2BAA2B,CACzC,UAAU,EAAE,cAAc,EAC1B,OAAO,GAAE,qBAA0B,GAClC,0BAA0B,CAE5B;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CACxC,UAAU,EAAE,cAAc,EAC1B,OAAO,GAAE,qBAA0B,GAClC,0BAA0B,CAQ5B"}

package/dist/references/guards.js

@@ -0,0 +1,76 @@
+import { APIError, } from 'payload';
+import { describeReferences, findReferences } from './find.js';
+/** The refusal an editor reads. Exported so a host can show the same words elsewhere. */
+export function referenceRefusal(found, options = {}) {
+    const noun = options.noun ?? 'document';
+    const verb = options.verb ?? 'delete';
+    const count = found.length;
+    const then = verb === 'delete' ? 'delete it' : 'move it to the trash';
+    const consequence = options.consequence ? ` — ${options.consequence}` : '';
+    /*
+    Block references are called out because they are the half nothing else would
+    have said: a field reference at least shows as an empty control afterwards,
+    where a block reference renders nothing at all.
+    */
+    const blocks = found.filter((entry) => entry.viaBlock).length;
+    const note = blocks > 0
+        ? `\n\n${blocks} of these use it inside a block, where nothing would have warned you and it would simply have stopped appearing.`
+        : '';
+    return `This ${noun} is still used by ${count} document${count === 1 ? '' : 's'}. Remove it there first, then ${then}${consequence}.\n\n${describeReferences(found)}${note}`;
+}
+async function refuseIfReferenced(req, collection, id, verb, options) {
+    const noun = options.noun ?? 'document';
+    let found;
+    try {
+        found = await findReferences(req.payload, { collection, id }, {
+            req,
+            ...(options.blocks ? { blocks: options.blocks } : {}),
+        });
+    }
+    catch (error) {
+        req.payload.logger.error({ event: 'references.scan-failed', collection, id, err: error }, `Could not check whether this ${noun} is in use; refusing to ${verb} it`);
+        throw new APIError(`Could not check whether this ${noun} is still in use, so nothing has changed. Try again; if it keeps happening, this needs a developer.`, 500);
+    }
+    if (found.length === 0)
+        return;
+    req.payload.logger.info({
+        event: 'references.refused',
+        collection,
+        id,
+        verb,
+        documents: found.map((entry) => `${entry.collection}:${String(entry.id)}`),
+    }, `Refused to ${verb} a ${noun} that is still referenced`);
+    // 400: answerable, and the caller can fix it, which is what the list is for.
+    throw new APIError(referenceRefusal(found, {
+        noun,
+        verb,
+        ...(options.consequence ? { consequence: options.consequence } : {}),
+    }), 400);
+}
+/** Whether this write puts the document in the trash: `deletedAt` set now and not before. */
+export function movesToTrash(data, originalDoc) {
+    const next = data?.['deletedAt'];
+    const previous = originalDoc?.['deletedAt'];
+    return next !== null && next !== undefined && (previous === null || previous === undefined);
+}
+/** `beforeDelete`: refuse while anything references the document. */
+export function refuseDeleteWhileReferenced(collection, options = {}) {
+    return async ({ req, id }) => refuseIfReferenced(req, collection, id, 'delete', options);
+}
+/**
+ * `beforeChange`: refuse a write that moves the document to the trash while
+ * anything references it. Every other write passes untouched and costs
+ * nothing, since the scan reads the whole config.
+ */
+export function refuseTrashWhileReferenced(collection, options = {}) {
+    return async ({ data, originalDoc, operation, req }) => {
+        if (operation !== 'update' || !movesToTrash(data, originalDoc))
+            return data;
+        const id = originalDoc?.id;
+        if (id === undefined)
+            return data;
+        await refuseIfReferenced(req, collection, id, 'move to the trash', options);
+        return data;
+    };
+}
+//# sourceMappingURL=guards.js.map

package/dist/references/guards.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guards.js","sourceRoot":"","sources":["../../src/references/guards.ts"],"names":[],"mappings":"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"}

package/dist/references/index.d.ts

@@ -0,0 +1,11 @@
+export { couldReference, pointsAt, referencesIn, referencesTo } from './walk.js';
+export type { Reference, ReferencesInOptions } from './walk.js';
+export { blockRegistry, describeReferences, findReferencedIds, findReferences } from './find.js';
+export type { DocumentReferences, FindReferencesOptions } from './find.js';
+export { movesToTrash, referenceRefusal, refuseDeleteWhileReferenced, refuseTrashWhileReferenced, } from './guards.js';
+export type { ReferenceGuardOptions } from './guards.js';
+export { REFERENCE_TOOLS, REFERENCE_TOOL_DESCRIPTORS, createCanDeleteTool, createFindReferencesTool, } from './tools.js';
+export type { ReferenceToolDeps } from './tools.js';
+export { USED_ON_FIELD, USED_ON_PANEL_PATH, referencesPlugin } from './plugin.js';
+export type { ReferenceCollectionOptions, ReferencesPluginOptions } from './plugin.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/references/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/references/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,WAAW,CAAA;AAChF,YAAY,EAAE,SAAS,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAA;AAE/D,OAAO,EAAE,aAAa,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAChG,YAAY,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,MAAM,WAAW,CAAA;AAE1E,OAAO,EACL,YAAY,EACZ,gBAAgB,EAChB,2BAA2B,EAC3B,0BAA0B,GAC3B,MAAM,aAAa,CAAA;AACpB,YAAY,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAA;AAExD,OAAO,EACL,eAAe,EACf,0BAA0B,EAC1B,mBAAmB,EACnB,wBAAwB,GACzB,MAAM,YAAY,CAAA;AACnB,YAAY,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAEnD,OAAO,EAAE,aAAa,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AACjF,YAAY,EAAE,0BAA0B,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAA"}

package/dist/references/index.js

@@ -0,0 +1,6 @@
+export { couldReference, pointsAt, referencesIn, referencesTo } from './walk.js';
+export { blockRegistry, describeReferences, findReferencedIds, findReferences } from './find.js';
+export { movesToTrash, referenceRefusal, refuseDeleteWhileReferenced, refuseTrashWhileReferenced, } from './guards.js';
+export { REFERENCE_TOOLS, REFERENCE_TOOL_DESCRIPTORS, createCanDeleteTool, createFindReferencesTool, } from './tools.js';
+export { USED_ON_FIELD, USED_ON_PANEL_PATH, referencesPlugin } from './plugin.js';
+//# sourceMappingURL=index.js.map

package/dist/references/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/references/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,WAAW,CAAA;AAGhF,OAAO,EAAE,aAAa,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAGhG,OAAO,EACL,YAAY,EACZ,gBAAgB,EAChB,2BAA2B,EAC3B,0BAA0B,GAC3B,MAAM,aAAa,CAAA;AAGpB,OAAO,EACL,eAAe,EACf,0BAA0B,EAC1B,mBAAmB,EACnB,wBAAwB,GACzB,MAAM,YAAY,CAAA;AAGnB,OAAO,EAAE,aAAa,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA"}

package/dist/references/plugin.d.ts

@@ -0,0 +1,51 @@
+import type { Block, Plugin } from 'payload';
+import type { McpToolContext } from '../plugin-contract/index.js';
+import type { McpToolCollector } from '../mcp/collector.js';
+export interface ReferenceCollectionOptions {
+    /** The collection to guard: deletes and trashing are refused while anything references a document. */
+    slug: string;
+    /** What a document is called in the refusal: "file", "person", "term". */
+    noun?: string;
+    /** What deleting would do to the documents that use it, appended to the refusal. */
+    consequence?: string;
+    /** Add the "Used on" sidebar panel. Default `true`. */
+    panel?: boolean;
+}
+export interface ReferencesPluginOptions {
+    enabled?: boolean;
+    /** The collections to guard, and whether each gets the panel. */
+    collections: readonly ReferenceCollectionOptions[];
+    /**
+     * Blocks to resolve by slug beyond the config's `blocks` registry. A
+     * `blocks` field's own blocks are always used, so this is rarely needed.
+     */
+    blocks?: readonly Block[];
+    /** Where `find_references` and `can_delete` go. Omit for no MCP tools. Must come before `mcpPlugin`. */
+    mcpTools?: McpToolCollector;
+    /** Who may call the tools. Default: a user with the `admin` or `editor` role. */
+    canUse?: (ctx: McpToolContext) => boolean;
+}
+/** The panel's import-map path. */
+export declare const USED_ON_PANEL_PATH = "@forumone/throughline/rsc#UsedOnPanel";
+/** The name of the panel's `ui` field. */
+export declare const USED_ON_FIELD = "usedOn";
+/**
+ * Reference tracking: what uses a document, refusing to delete or trash it
+ * while anything does, a "Used on" panel, and the `find_references` and
+ * `can_delete` MCP tools.
+ *
+ * Works with blocks stored as JSON, which Payload cannot query: see
+ * `references/find.ts` for how, and for what it costs.
+ *
+ * ```ts
+ * referencesPlugin({
+ *   collections: [
+ *     { slug: 'media', noun: 'file' },
+ *     { slug: 'people', noun: 'person', panel: false },
+ *   ],
+ *   mcpTools,
+ * })
+ * ```
+ */
+export declare function referencesPlugin(options: ReferencesPluginOptions): Plugin;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/references/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../../src/references/plugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAmC,MAAM,EAAE,MAAM,SAAS,CAAA;AAC7E,OAAO,KAAK,EAAE,cAAc,EAAqB,MAAM,6BAA6B,CAAA;AACpF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAA;AAQ3D,MAAM,WAAW,0BAA0B;IACzC,sGAAsG;IACtG,IAAI,EAAE,MAAM,CAAA;IACZ,0EAA0E;IAC1E,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,oFAAoF;IACpF,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,uDAAuD;IACvD,KAAK,CAAC,EAAE,OAAO,CAAA;CAChB;AAED,MAAM,WAAW,uBAAuB;IACtC,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,iEAAiE;IACjE,WAAW,EAAE,SAAS,0BAA0B,EAAE,CAAA;IAClD;;;OAGG;IACH,MAAM,CAAC,EAAE,SAAS,KAAK,EAAE,CAAA;IACzB,wGAAwG;IACxG,QAAQ,CAAC,EAAE,gBAAgB,CAAA;IAC3B,iFAAiF;IACjF,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,cAAc,KAAK,OAAO,CAAA;CAC1C;AAED,mCAAmC;AACnC,eAAO,MAAM,kBAAkB,0CAA0C,CAAA;AAEzE,0CAA0C;AAC1C,eAAO,MAAM,aAAa,WAAW,CAAA;AAErC;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,uBAAuB,GAAG,MAAM,CAkGzE"}

package/dist/references/plugin.js

@@ -0,0 +1,111 @@
+import { refuseDeleteWhileReferenced, refuseTrashWhileReferenced } from './guards.js';
+import { REFERENCE_TOOL_DESCRIPTORS, createCanDeleteTool, createFindReferencesTool, } from './tools.js';
+/** The panel's import-map path. */
+export const USED_ON_PANEL_PATH = '@forumone/throughline/rsc#UsedOnPanel';
+/** The name of the panel's `ui` field. */
+export const USED_ON_FIELD = 'usedOn';
+/**
+ * Reference tracking: what uses a document, refusing to delete or trash it
+ * while anything does, a "Used on" panel, and the `find_references` and
+ * `can_delete` MCP tools.
+ *
+ * Works with blocks stored as JSON, which Payload cannot query: see
+ * `references/find.ts` for how, and for what it costs.
+ *
+ * ```ts
+ * referencesPlugin({
+ *   collections: [
+ *     { slug: 'media', noun: 'file' },
+ *     { slug: 'people', noun: 'person', panel: false },
+ *   ],
+ *   mcpTools,
+ * })
+ * ```
+ */
+export function referencesPlugin(options) {
+    return (incoming) => {
+        if (options.enabled === false)
+            return incoming;
+        const bySlug = new Map(options.collections.map((entry) => [entry.slug, entry]));
+        const known = new Set((incoming.collections ?? []).map((collection) => collection.slug));
+        const missing = [...bySlug.keys()].filter((slug) => !known.has(slug));
+        if (missing.length > 0) {
+            throw new Error(`referencesPlugin: no collection ${missing.map((slug) => `"${slug}"`).join(', ')} in the config. ` +
+                `Register this plugin after the plugins that add collections it guards.`);
+        }
+        const collections = (incoming.collections ?? []).map((collection) => {
+            const entry = bySlug.get(collection.slug);
+            if (!entry)
+                return collection;
+            const guard = {
+                ...(entry.noun ? { noun: entry.noun } : {}),
+                ...(entry.consequence ? { consequence: entry.consequence } : {}),
+                ...(options.blocks ? { blocks: options.blocks } : {}),
+            };
+            let fields = collection.fields;
+            if (entry.panel !== false) {
+                if (fields.some((field) => 'name' in field && field.name === USED_ON_FIELD)) {
+                    throw new Error(`referencesPlugin: "${collection.slug}" already has a field named "${USED_ON_FIELD}". ` +
+                        `Remove it, or pass panel: false.`);
+                }
+                /*
+                A `ui` field stores nothing. First, so it sits at the top of the
+                sidebar: an editor about to change an image needs to know it is on five
+                pages before they change it.
+                */
+                const panel = {
+                    name: USED_ON_FIELD,
+                    type: 'ui',
+                    admin: { position: 'sidebar', components: { Field: USED_ON_PANEL_PATH } },
+                    ...(options.blocks ? { custom: { references: { blocks: options.blocks } } } : {}),
+                };
+                fields = [panel, ...fields];
+            }
+            return {
+                ...collection,
+                fields,
+                hooks: {
+                    ...collection.hooks,
+                    // First in each list, so a refusal happens before any other hook acts.
+                    beforeChange: [
+                        refuseTrashWhileReferenced(collection.slug, guard),
+                        ...(collection.hooks?.beforeChange ?? []),
+                    ],
+                    beforeDelete: [
+                        refuseDeleteWhileReferenced(collection.slug, guard),
+                        ...(collection.hooks?.beforeDelete ?? []),
+                    ],
+                },
+            };
+        });
+        // Declared at config time so `mcpPlugin` makes a checkbox per tool; bound at `onInit`.
+        options.mcpTools?.declare(REFERENCE_TOOL_DESCRIPTORS, { serverName: 'references' });
+        return {
+            ...incoming,
+            collections,
+            onInit: async (payload) => {
+                if (incoming.onInit)
+                    await incoming.onInit(payload);
+                if (!options.mcpTools)
+                    return;
+                const deps = {
+                    payload,
+                    guarded: new Map(options.collections.map((entry) => [
+                        entry.slug,
+                        {
+                            ...(entry.noun ? { noun: entry.noun } : {}),
+                            ...(entry.consequence ? { consequence: entry.consequence } : {}),
+                        },
+                    ])),
+                    ...(options.blocks ? { blocks: options.blocks } : {}),
+                    ...(options.canUse ? { canUse: options.canUse } : {}),
+                };
+                options.mcpTools.add([
+                    createFindReferencesTool(deps),
+                    createCanDeleteTool(deps),
+                ], { serverName: 'references' });
+            },
+        };
+    };
+}
+//# sourceMappingURL=plugin.js.map

package/dist/references/plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.js","sourceRoot":"","sources":["../../src/references/plugin.ts"],"names":[],"mappings":"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"}

package/dist/references/tools.d.ts

@@ -0,0 +1,54 @@
+import { z } from 'zod';
+import type { Block, Payload } from 'payload';
+import type { McpToolContext, McpToolDefinition } from '../plugin-contract/index.js';
+import type { McpToolDescriptor } from '../mcp/collector.js';
+export declare const REFERENCE_TOOLS: {
+    readonly findReferences: {
+        readonly name: "find_references";
+        readonly description: "Lists every document and global that references a document: an image, a person, a taxonomy term, or anything else that can be linked or embedded. Covers references inside blocks and rich text, which Payload itself cannot query, and both the published and draft state of each document. Use before replacing or deleting something shared, or to answer \"where is this used?\".";
+    };
+    readonly canDelete: {
+        readonly name: "can_delete";
+        readonly description: "Whether a document can be deleted or moved to the trash without breaking another document that uses it. Returns canDelete, and when false, the documents that still reference it and the message an editor would see. Deleting is refused while anything references a guarded document, so ask this first and remove the references before trying.";
+    };
+};
+export declare const REFERENCE_TOOL_DESCRIPTORS: readonly McpToolDescriptor[];
+export interface ReferenceToolDeps {
+    payload: Payload;
+    /** Collections whose deletes are refused while referenced, with their nouns. */
+    guarded: ReadonlyMap<string, {
+        noun?: string;
+        consequence?: string;
+    }>;
+    blocks?: readonly Block[];
+    /** Who may ask. Default: a user with the `admin` or `editor` role. */
+    canUse?: (ctx: McpToolContext) => boolean;
+}
+declare const inputSchema: z.ZodObject<{
+    collection: z.ZodString;
+    id: z.ZodUnion<[z.ZodString, z.ZodNumber]>;
+}, "strip", z.ZodTypeAny, {
+    collection: string;
+    id: string | number;
+}, {
+    collection: string;
+    id: string | number;
+}>;
+declare const findInputSchema: z.ZodObject<{
+    collection: z.ZodString;
+    id: z.ZodUnion<[z.ZodString, z.ZodNumber]>;
+} & {
+    limit: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    collection: string;
+    id: string | number;
+    limit?: number | undefined;
+}, {
+    collection: string;
+    id: string | number;
+    limit?: number | undefined;
+}>;
+export declare function createFindReferencesTool(deps: ReferenceToolDeps): McpToolDefinition<typeof findInputSchema>;
+export declare function createCanDeleteTool(deps: ReferenceToolDeps): McpToolDefinition<typeof inputSchema>;
+export {};
+//# sourceMappingURL=tools.d.ts.map

package/dist/references/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../src/references/tools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,KAAK,EAAE,KAAK,EAAkB,OAAO,EAAE,MAAM,SAAS,CAAA;AAC7D,OAAO,KAAK,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAA;AACpF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AAe5D,eAAO,MAAM,eAAe;;;;;;;;;CAW0B,CAAA;AAEtD,eAAO,MAAM,0BAA0B,EAAE,SAAS,iBAAiB,EACnC,CAAA;AAEhC,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,OAAO,CAAA;IAChB,gFAAgF;IAChF,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IACrE,MAAM,CAAC,EAAE,SAAS,KAAK,EAAE,CAAA;IACzB,sEAAsE;IACtE,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,cAAc,KAAK,OAAO,CAAA;CAC1C;AAED,QAAA,MAAM,WAAW;;;;;;;;;EAGf,CAAA;AAEF,QAAA,MAAM,eAAe;;;;;;;;;;;;;EAQnB,CAAA;AAgCF,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,iBAAiB,GACtB,iBAAiB,CAAC,OAAO,eAAe,CAAC,CAuB3C;AAED,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,iBAAiB,GACtB,iBAAiB,CAAC,OAAO,WAAW,CAAC,CAyCvC"}