@next-buildr/payload 0.0.0-stage → 2.0.0

package/dist/plugin/hooks/layout-hook.test.js

@@ -0,0 +1,191 @@
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createEmptyDocument, createRegistryMeta, p, s, } from '@next-buildr/core';
+import { sqliteAdapter } from '@payloadcms/db-sqlite';
+import { buildConfig, getPayload, handleEndpoints } from 'payload';
+import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest';
+import { buildrPlugin } from '../index.js';
+import { BUILDR_WRITE } from '../write-guard.js';
+import { processLayout } from './process-layout.js';
+const widget = {
+    type: 'buildr/widget',
+    version: 2,
+    label: 'Widget',
+    category: 'content',
+    props: { title: p.text({ label: 'Title', default: 'Hello' }) },
+    contentCategories: ['flow'],
+    styles: { groups: [] },
+    runtime: 'shared',
+    slots: {},
+};
+const page = {
+    ...widget,
+    type: 'buildr/page',
+    version: 1,
+    label: 'Page',
+    props: {},
+    capabilities: { root: true },
+    slots: { default: {} },
+};
+const meta = createRegistryMeta({ components: [page, widget] });
+// The widget renamed `label` to `title` in version 2.
+const migrations = {
+    'buildr/page': { currentVersion: 1, steps: [] },
+    'buildr/widget': {
+        currentVersion: 2,
+        steps: [
+            {
+                from: 1,
+                to: 2,
+                migrate: (props) => {
+                    const { label, ...rest } = props ?? {};
+                    return { ...rest, title: label };
+                },
+            },
+        ],
+    },
+};
+const withWidget = (props, widgetVersion = 2) => ({
+    schemaVersion: 1,
+    root: 'root',
+    nodes: {
+        root: { id: 'root', type: 'buildr/page', slots: { default: ['widget0001'] } },
+        widget0001: { id: 'widget0001', type: 'buildr/widget', props },
+    },
+    components: { 'buildr/page': 1, 'buildr/widget': widgetVersion },
+});
+describe('processLayout', () => {
+    const limits = { maxNodes: 5000, maxBytes: 2_000_000 };
+    const registry = { meta, migrations };
+    it('gives a missing layout the empty document', () => {
+        const result = processLayout(undefined, { limits });
+        expect(result).toEqual({ ok: true, doc: createEmptyDocument(), warnings: [] });
+    });
+    it('rejects what is not a document, with a readable message', () => {
+        for (const value of ['text', [], { nodes: {} }]) {
+            const result = processLayout(value, { limits });
+            expect(result.ok).toBe(false);
+        }
+    });
+    it('applies the limits, tightening the defaults only', () => {
+        const doc = withWidget({ title: s('a') });
+        expect(processLayout(doc, { limits: { maxNodes: 1, maxBytes: 2_000_000 } }).ok).toBe(false);
+        expect(processLayout(doc, { limits: { maxNodes: 10 ** 9, maxBytes: 10 ** 9 } }).ok).toBe(true);
+    });
+    it('migrates components to the current version', () => {
+        const result = processLayout(withWidget({ label: s('Old') }, 1), { limits, registry });
+        expect(result.ok).toBe(true);
+        if (!result.ok)
+            return;
+        expect(result.doc.components['buildr/widget']).toBe(2);
+        expect(result.doc.nodes['widget0001']?.props?.['title']).toEqual(s('Old'));
+    });
+    it('rejects a component written by newer code', () => {
+        const result = processLayout(withWidget({ title: s('a') }, 9), { limits, registry });
+        expect(result.ok).toBe(false);
+    });
+    it('rejects an unknown prop value when a registry is configured', () => {
+        const doc = withWidget({ title: { kind: 'static', value: 42 } });
+        expect(processLayout(doc, { limits }).ok).toBe(true);
+        expect(processLayout(doc, { limits, registry }).ok).toBe(false);
+    });
+});
+let dir;
+let payload;
+const warn = vi.fn();
+beforeAll(async () => {
+    dir = mkdtempSync(join(tmpdir(), 'buildr-payload-hooks-'));
+    const config = buildConfig({
+        secret: 'test-secret',
+        collections: [
+            {
+                slug: 'pages',
+                fields: [{ name: 'title', type: 'text' }],
+                versions: { drafts: { autosave: true } },
+            },
+        ],
+        db: sqliteAdapter({ client: { url: `file:${join(dir, 'db.sqlite')}` } }),
+        plugins: [
+            buildrPlugin({ collections: { pages: { context: 'page' } }, registry: { meta, migrations } }),
+        ],
+        typescript: { autoGenerate: false },
+    });
+    payload = await getPayload({ config, key: 'layout-hook' });
+    payload.logger.warn = warn;
+});
+afterAll(() => {
+    try {
+        rmSync(dir, { recursive: true, force: true });
+    }
+    catch {
+        // Windows keeps the database file open a moment longer.
+    }
+});
+describe('the layout hook', () => {
+    const write = (data, id) => id === undefined
+        ? payload.create({ collection: 'pages', data, draft: true })
+        : payload.update({
+            collection: 'pages',
+            id,
+            data,
+            draft: true,
+            context: { [BUILDR_WRITE]: true },
+        });
+    const layoutOf = async (id) => (await payload.findByID({ collection: 'pages', id, draft: true })).layout;
+    it('creates a document with the empty layout', async () => {
+        const doc = await write({ title: 'New' });
+        expect(await layoutOf(doc.id)).toEqual(createEmptyDocument());
+    });
+    it('rejects an invalid layout through the Local API, naming the field', async () => {
+        await expect(write({ title: 'Bad', layout: { schemaVersion: 1, nodes: {} } })).rejects.toThrow(/layout/i);
+        const doc = await write({ title: 'Ok' });
+        const rejected = await write({ layout: 'nonsense' }, doc.id).catch((error) => error);
+        expect(rejected.data?.errors?.[0]?.message).toMatch(/document object/);
+        expect(await layoutOf(doc.id)).toEqual(createEmptyDocument());
+    });
+    it('migrates on save', async () => {
+        const doc = await write({ title: 'Migrating' });
+        await write({ layout: withWidget({ label: s('Old') }, 1) }, doc.id);
+        const stored = await layoutOf(doc.id);
+        expect(stored.components['buildr/widget']).toBe(2);
+        expect(stored.nodes['widget0001']?.props?.['title']).toEqual(s('Old'));
+    });
+    it('rejects an invalid layout over REST with a readable field error', async () => {
+        await payload.create({
+            collection: 'users',
+            data: { email: 'editor@example.com', password: 'secret-password' },
+        });
+        const login = await payload.login({
+            collection: 'users',
+            data: { email: 'editor@example.com', password: 'secret-password' },
+        });
+        const response = await handleEndpoints({
+            config: payload.config,
+            request: new Request('http://localhost/api/pages', {
+                method: 'POST',
+                headers: { 'content-type': 'application/json', authorization: `JWT ${login.token}` },
+                body: JSON.stringify({
+                    title: 'Rest',
+                    layout: { schemaVersion: 1, root: 'root', nodes: {} },
+                }),
+            }),
+        });
+        expect(response.status).toBeGreaterThanOrEqual(400);
+        expect(response.status).toBeLessThan(500);
+        const body = (await response.json());
+        const field = body.errors[0]?.data?.errors?.[0];
+        expect(field?.path).toBe('layout');
+        expect(field?.message.length).toBeGreaterThan(10);
+    });
+    it('does not validate a layout that the write-guard keeps', async () => {
+        const doc = await write({ title: 'Kept' });
+        await payload.update({
+            collection: 'pages',
+            id: doc.id,
+            data: { title: 'Renamed', layout: 'garbage' },
+            draft: true,
+        });
+        expect(await layoutOf(doc.id)).toEqual(createEmptyDocument());
+    });
+});

package/dist/plugin/hooks/process-layout.d.ts

@@ -0,0 +1,32 @@
+import type { LocaleConfig } from '@next-buildr/core';
+import { type BuilderDocument, type Diagnostic, type DocumentLimits } from '@next-buildr/core';
+import type { BuildrRegistry } from '../options.ts';
+export interface ProcessLayoutOptions {
+    readonly registry?: BuildrRegistry | undefined;
+    readonly limits: {
+        readonly maxNodes: number;
+        readonly maxBytes: number;
+    };
+    /** The languages of the site: an `l10n` key outside them is reported (a warning, kept). */
+    readonly locales?: LocaleConfig | undefined;
+}
+export type ProcessedLayout = {
+    readonly ok: true;
+    readonly doc: BuilderDocument;
+    readonly warnings: readonly Diagnostic[];
+} | {
+    readonly ok: false;
+    readonly diagnostics: readonly Diagnostic[];
+};
+/** The limits of the plugin can only tighten the defaults of the model. */
+export declare const documentLimits: (limits: ProcessLayoutOptions['limits']) => DocumentLimits;
+/**
+ * What every write of `layout` goes through, whatever its path (Local API, REST, the builder
+ * endpoints): a missing document becomes an empty one; anything else is migrated to the current
+ * document schema, parsed against the limits, migrated to the current component versions and, when
+ * a registry is configured, validated. Errors reject the write; warnings are handed back to be logged.
+ */
+export declare function processLayout(value: unknown, options: ProcessLayoutOptions): ProcessedLayout;
+/** A readable one-line-per-problem message for the admin UI (`code` and, when known, where). */
+export declare function describeDiagnostics(diagnostics: readonly Diagnostic[]): string;
+//# sourceMappingURL=process-layout.d.ts.map

package/dist/plugin/hooks/process-layout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"process-layout.d.ts","sourceRoot":"","sources":["../../../src/plugin/hooks/process-layout.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EACL,KAAK,eAAe,EAGpB,KAAK,UAAU,EACf,KAAK,cAAc,EAMpB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAEpD,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,QAAQ,CAAC,EAAE,cAAc,GAAG,SAAS,CAAC;IAC/C,QAAQ,CAAC,MAAM,EAAE;QAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1E,2FAA2F;IAC3F,QAAQ,CAAC,OAAO,CAAC,EAAE,YAAY,GAAG,SAAS,CAAC;CAC7C;AAED,MAAM,MAAM,eAAe,GACvB;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,eAAe,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,SAAS,UAAU,EAAE,CAAA;CAAE,GAC9F;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,WAAW,EAAE,SAAS,UAAU,EAAE,CAAA;CAAE,CAAC;AAExE,2EAA2E;AAC3E,eAAO,MAAM,cAAc,WAAY,oBAAoB,CAAC,QAAQ,CAAC,KAAG,cAItE,CAAC;AAOH;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,oBAAoB,GAAG,eAAe,CAyC5F;AAED,gGAAgG;AAChG,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,SAAS,UAAU,EAAE,GAAG,MAAM,CAO9E"}

package/dist/plugin/hooks/process-layout.js

@@ -0,0 +1,68 @@
+import { createEmptyDocument, DEFAULT_DOCUMENT_LIMITS, migrateComponents, migrateDocument, parseDocument, validateDocument, } from '@next-buildr/core';
+/** The limits of the plugin can only tighten the defaults of the model. */
+export const documentLimits = (limits) => ({
+    ...DEFAULT_DOCUMENT_LIMITS,
+    maxNodes: Math.min(limits.maxNodes, DEFAULT_DOCUMENT_LIMITS.maxNodes),
+    maxDocumentBytes: Math.min(limits.maxBytes, DEFAULT_DOCUMENT_LIMITS.maxDocumentBytes),
+});
+const failure = (code, message) => ({
+    ok: false,
+    diagnostics: [{ code, message, severity: 'error' }],
+});
+/**
+ * What every write of `layout` goes through, whatever its path (Local API, REST, the builder
+ * endpoints): a missing document becomes an empty one; anything else is migrated to the current
+ * document schema, parsed against the limits, migrated to the current component versions and, when
+ * a registry is configured, validated. Errors reject the write; warnings are handed back to be logged.
+ */
+export function processLayout(value, options) {
+    if (value === undefined || value === null) {
+        return { ok: true, doc: createEmptyDocument(), warnings: [] };
+    }
+    if (typeof value !== 'object' || Array.isArray(value)) {
+        return failure('layout.not-an-object', 'the layout must be a document object');
+    }
+    const raw = value;
+    if (typeof raw.schemaVersion !== 'number') {
+        return failure('layout.no-schema-version', 'the layout has no numeric "schemaVersion"');
+    }
+    const limits = documentLimits(options.limits);
+    const migratedShape = migrateDocument(value);
+    if (!migratedShape.ok)
+        return { ok: false, diagnostics: [migratedShape.error] };
+    const parsed = parseDocument(migratedShape.value.doc, limits);
+    if (!parsed.ok)
+        return { ok: false, diagnostics: parsed.error };
+    let doc = parsed.value;
+    const warnings = [];
+    const registry = options.registry;
+    if (registry?.migrations !== undefined) {
+        const migrated = migrateComponents(doc, registry.migrations);
+        if (migrated.readOnlyReasons.length > 0) {
+            return { ok: false, diagnostics: migrated.readOnlyReasons };
+        }
+        warnings.push(...migrated.diagnostics);
+        doc = migrated.doc;
+    }
+    if (registry !== undefined) {
+        const result = validateDocument(doc, {
+            registry: registry.meta,
+            limits,
+            locales: options.locales,
+        });
+        const errors = result.issues.filter((issue) => issue.severity === 'error');
+        if (!result.ok || errors.length > 0)
+            return { ok: false, diagnostics: errors };
+        warnings.push(...result.issues);
+    }
+    return { ok: true, doc, warnings };
+}
+/** A readable one-line-per-problem message for the admin UI (`code` and, when known, where). */
+export function describeDiagnostics(diagnostics) {
+    return diagnostics
+        .map((diagnostic) => {
+        const where = diagnostic.path === undefined ? '' : ` (${diagnostic.path.join('.')})`;
+        return `${diagnostic.message}${where}`;
+    })
+        .join('; ');
+}

package/dist/plugin/hooks/read-layout.d.ts

@@ -0,0 +1,17 @@
+import { type BuilderDocument, type Diagnostic } from '@next-buildr/core';
+import { type ProcessLayoutOptions } from './process-layout.ts';
+export type ReadLayout = {
+    readonly ok: true;
+    readonly doc: BuilderDocument;
+    readonly readOnly: boolean;
+} | {
+    readonly ok: false;
+    readonly diagnostics: readonly Diagnostic[];
+};
+/**
+ * A stored layout as the editor opens it: migrated in memory (nothing is written), and marked
+ * read-only when a component was written by newer code than this build knows (ADR-014).
+ * Validation is not repeated here: a stored document was validated when it was written.
+ */
+export declare function readLayout(value: unknown, options: ProcessLayoutOptions): ReadLayout;
+//# sourceMappingURL=read-layout.d.ts.map

package/dist/plugin/hooks/read-layout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read-layout.d.ts","sourceRoot":"","sources":["../../../src/plugin/hooks/read-layout.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,eAAe,EAEpB,KAAK,UAAU,EAKhB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAkB,KAAK,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAEhF,MAAM,MAAM,UAAU,GAClB;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,eAAe,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;CAAE,GAChF;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,WAAW,EAAE,SAAS,UAAU,EAAE,CAAA;CAAE,CAAC;AAExE;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,oBAAoB,GAAG,UAAU,CA6BpF"}

package/dist/plugin/hooks/read-layout.js

@@ -0,0 +1,39 @@
+import { createEmptyDocument, migrateComponents, migrateDocument, parseDocument, } from '@next-buildr/core';
+import { documentLimits } from './process-layout.js';
+/**
+ * A stored layout as the editor opens it: migrated in memory (nothing is written), and marked
+ * read-only when a component was written by newer code than this build knows (ADR-014).
+ * Validation is not repeated here: a stored document was validated when it was written.
+ */
+export function readLayout(value, options) {
+    if (value === undefined || value === null) {
+        return { ok: true, doc: createEmptyDocument(), readOnly: false };
+    }
+    if (typeof value !== 'object' || typeof value.schemaVersion !== 'number') {
+        return {
+            ok: false,
+            diagnostics: [
+                {
+                    code: 'layout.not-a-document',
+                    message: 'the stored layout is not a document',
+                    severity: 'error',
+                },
+            ],
+        };
+    }
+    const migrated = migrateDocument(value);
+    if (!migrated.ok)
+        return { ok: false, diagnostics: [migrated.error] };
+    const parsed = parseDocument(migrated.value.doc, documentLimits(options.limits));
+    if (!parsed.ok)
+        return { ok: false, diagnostics: parsed.error };
+    const registry = options.registry;
+    if (registry?.migrations === undefined)
+        return { ok: true, doc: parsed.value, readOnly: false };
+    const components = migrateComponents(parsed.value, registry.migrations);
+    return {
+        ok: true,
+        doc: components.readOnlyReasons.length > 0 ? parsed.value : components.doc,
+        readOnly: components.readOnlyReasons.length > 0,
+    };
+}

package/dist/plugin/index.d.ts

@@ -0,0 +1,18 @@
+import type { Plugin } from 'payload';
+import { type BuildrPluginOptions } from './options.ts';
+export { FORM_SUBMISSIONS_COLLECTION } from './collections/form-submissions.ts';
+export { FORM_TYPE, HONEYPOT_FIELD } from './endpoints/forms.ts';
+export { LAYOUT_FIELD_COMPONENT, TEMPLATES_COLLECTION } from './fields.ts';
+export type { MemoryRateLimiterOptions, RateLimiter, RateLimitResult } from './forms/rate-limit.ts';
+export { createMemoryRateLimiter } from './forms/rate-limit.ts';
+export type { ProcessedLayout, ProcessLayoutOptions } from './hooks/process-layout.ts';
+export { describeDiagnostics, documentLimits, processLayout } from './hooks/process-layout.ts';
+export type { AccessArgs, AccessFn, BuildrPluginOptions, BuildrRegistry, ResolvedOptions, } from './options.ts';
+export { resolveOptions } from './options.ts';
+export { BUILDR_WRITE } from './write-guard.ts';
+/**
+ * The one-line install (docs/payload.md): adds the `layout`, `buildrRevision` and `template` fields
+ * to the configured collections and guards them against writes that do not come from the builder.
+ */
+export declare function buildrPlugin(input: BuildrPluginOptions): Plugin;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/plugin/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAA4B,MAAM,EAAE,MAAM,SAAS,CAAC;AAahE,OAAO,EAAE,KAAK,mBAAmB,EAAkB,MAAM,cAAc,CAAC;AAGxE,OAAO,EAAE,2BAA2B,EAAE,MAAM,mCAAmC,CAAC;AAChF,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACjE,OAAO,EAAE,sBAAsB,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAC3E,YAAY,EAAE,wBAAwB,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACpG,OAAO,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAChE,YAAY,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AACvF,OAAO,EAAE,mBAAmB,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAC/F,YAAY,EACV,UAAU,EACV,QAAQ,EACR,mBAAmB,EACnB,cAAc,EACd,eAAe,GAChB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAOhD;;;GAGG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,mBAAmB,GAAG,MAAM,CAoG/D"}

package/dist/plugin/index.js

@@ -0,0 +1,105 @@
+import { formSubmissionsCollection } from './collections/form-submissions.js';
+import { templatesCollection } from './collections/templates.js';
+import { buildrEndpoints } from './endpoints/index.js';
+import { buildrFields, RESERVED_FIELDS, RESERVED_MCP_FIELDS, TEMPLATES_COLLECTION, } from './fields.js';
+import { isAllowedRecipient } from './forms/notify.js';
+import { createMemoryRateLimiter } from './forms/rate-limit.js';
+import { layoutHook } from './hooks/layout-hook.js';
+import { resolveOptions } from './options.js';
+import { writeGuard } from './write-guard.js';
+export { FORM_SUBMISSIONS_COLLECTION } from './collections/form-submissions.js';
+export { FORM_TYPE, HONEYPOT_FIELD } from './endpoints/forms.js';
+export { LAYOUT_FIELD_COMPONENT, TEMPLATES_COLLECTION } from './fields.js';
+export { createMemoryRateLimiter } from './forms/rate-limit.js';
+export { describeDiagnostics, documentLimits, processLayout } from './hooks/process-layout.js';
+export { resolveOptions } from './options.js';
+export { BUILDR_WRITE } from './write-guard.js';
+const hasDrafts = (collection) => {
+    const versions = collection.versions;
+    return typeof versions === 'object' && versions !== null && Boolean(versions.drafts);
+};
+/**
+ * The one-line install (docs/payload.md): adds the `layout`, `buildrRevision` and `template` fields
+ * to the configured collections and guards them against writes that do not come from the builder.
+ */
+export function buildrPlugin(input) {
+    const options = resolveOptions(input);
+    const forms = options.forms;
+    if (forms.enabled && options.registry === undefined) {
+        throw new Error('buildrPlugin: forms need the "registry" option (the form schema is derived from it)');
+    }
+    const stray = forms.notifyTo.find((address) => !isAllowedRecipient(address, forms.notifyAllowlist));
+    if (stray !== undefined) {
+        throw new Error(`buildrPlugin: forms.notifyTo "${stray}" is not in forms.notifyAllowlist`);
+    }
+    const rateLimiter = forms.enabled
+        ? (forms.rateLimiter ?? createMemoryRateLimiter(forms.rateLimit))
+        : undefined;
+    const writeLimiter = options.mcp.enabled
+        ? (options.mcp.rateLimiter ?? createMemoryRateLimiter(options.mcp.rateLimit))
+        : undefined;
+    return (config) => {
+        const collections = config.collections ?? [];
+        const authSlugs = collections.filter((c) => Boolean(c.auth)).map((c) => c.slug);
+        if (options.mcp.enabled) {
+            const keyed = collections.some((c) => typeof c.auth === 'object' && Boolean(c.auth.useAPIKey));
+            if (!keyed) {
+                throw new Error('buildrPlugin: mcp.enabled needs an auth collection with `auth: { useAPIKey: true }` (a dedicated, low-privilege agent user; see docs/mcp.md)');
+            }
+            const unknown = (options.mcp.collections ?? []).find((slug) => options.collections[slug] === undefined);
+            if (unknown !== undefined) {
+                throw new Error(`buildrPlugin: mcp.collections "${unknown}" is not a configured builder collection`);
+            }
+        }
+        for (const slug of Object.keys(options.collections)) {
+            const collection = collections.find((candidate) => candidate.slug === slug);
+            if (collection === undefined) {
+                throw new Error(`buildrPlugin: the configured collection "${slug}" does not exist`);
+            }
+            if (!hasDrafts(collection)) {
+                throw new Error(`buildrPlugin: the collection "${slug}" must enable versions.drafts (the builder saves drafts and autosaves)`);
+            }
+            const taken = collection.fields.find((field) => field.name !== undefined &&
+                (RESERVED_FIELDS.includes(field.name) ||
+                    (options.mcp.enabled && RESERVED_MCP_FIELDS.includes(field.name))));
+            if (taken !== undefined) {
+                throw new Error(`buildrPlugin: the collection "${slug}" already has a "${taken.name}" field`);
+            }
+        }
+        const targets = Object.entries(options.collections)
+            .filter(([, own]) => own.templates)
+            .map(([slug]) => slug);
+        if (targets.length > 0 && collections.some((c) => c.slug === TEMPLATES_COLLECTION)) {
+            throw new Error(`buildrPlugin: the collection "${TEMPLATES_COLLECTION}" is added by the plugin and must not be defined`);
+        }
+        return {
+            ...config,
+            endpoints: [
+                ...(config.endpoints ?? []),
+                ...buildrEndpoints({ options, rateLimiter, writeLimiter }),
+            ],
+            collections: [
+                ...collections.map((collection) => {
+                    const own = options.collections[collection.slug];
+                    if (own === undefined)
+                        return collection;
+                    return {
+                        ...collection,
+                        fields: [
+                            ...collection.fields,
+                            ...buildrFields({
+                                templates: own.templates,
+                                editorRoute: options.routes.editor,
+                                guard: writeGuard,
+                                layoutHook: layoutHook(options),
+                                updatedBy: options.mcp.enabled ? authSlugs : undefined,
+                            }),
+                        ],
+                    };
+                }),
+                ...(targets.length === 0 ? [] : [templatesCollection({ resolved: options, targets })]),
+                ...(forms.enabled ? [formSubmissionsCollection()] : []),
+            ],
+        };
+    };
+}

package/dist/plugin/locales.d.ts

@@ -0,0 +1,32 @@
+import type { LocaleConfig } from '@next-buildr/core';
+import type { PayloadRequest, SanitizedConfig } from 'payload';
+/**
+ * The languages of the site as Payload's `localization` configures them, or `undefined` when it is
+ * not configured (docs/i18n.md#payload). `intl` carries the display names for the language switcher.
+ */
+export declare function configuredLocales(config: SanitizedConfig): LocaleConfig | undefined;
+/** `configuredLocales`, or the single-locale configuration when localization is off. */
+export declare const localeConfigOf: (config: SanitizedConfig) => LocaleConfig;
+/** The options of a Local API read in a language (`locale`, `fallbackLocale`); empty when localization is off. */
+export interface LocaleArgs {
+    readonly locale?: string;
+    readonly fallbackLocale?: false;
+}
+export type LocaleChoice = {
+    readonly ok: true;
+    /** The language asked for, or the default one; `undefined` without localization. */
+    readonly locale: string | undefined;
+    /** Spread into a Local API call. */
+    readonly args: LocaleArgs;
+} | {
+    readonly ok: false;
+    readonly response: Response;
+};
+/**
+ * The language of a request (`requested`: the `locale` parameter or body field). Without Payload
+ * localization it is ignored, so an installation that has none behaves as it did. With it, no
+ * value means the default language and one that is not configured is a `400`; when the
+ * configuration turns `fallback` off, reads do not fall back to the default language either.
+ */
+export declare function chooseLocale(req: Pick<PayloadRequest, 'payload'>, requested: string | null | undefined): LocaleChoice;
+//# sourceMappingURL=locales.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"locales.d.ts","sourceRoot":"","sources":["../../src/plugin/locales.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAW/D;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,eAAe,GAAG,YAAY,GAAG,SAAS,CAkBnF;AAED,wFAAwF;AACxF,eAAO,MAAM,cAAc,WAAY,eAAe,KAAG,YACb,CAAC;AAE7C,kHAAkH;AAClH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,cAAc,CAAC,EAAE,KAAK,CAAC;CACjC;AAED,MAAM,MAAM,YAAY,GACpB;IACE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAClB,oFAAoF;IACpF,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,oCAAoC;IACpC,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;CAC3B,GACD;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAA;CAAE,CAAC;AAExD;;;;;GAKG;AACH,wBAAgB,YAAY,CAC1B,GAAG,EAAE,IAAI,CAAC,cAAc,EAAE,SAAS,CAAC,EACpC,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GACnC,YAAY,CAed"}

package/dist/plugin/locales.js

@@ -0,0 +1,56 @@
+import { fail } from './endpoints/respond.js';
+/** The locale of an installation without Payload localization: one language, no fallback. */
+const SINGLE_LOCALE = {
+    locales: ['en'],
+    default: 'en',
+    fallback: false,
+    intl: { en: 'English' },
+};
+/**
+ * The languages of the site as Payload's `localization` configures them, or `undefined` when it is
+ * not configured (docs/i18n.md#payload). `intl` carries the display names for the language switcher.
+ */
+export function configuredLocales(config) {
+    const localization = config.localization;
+    if (localization === false || localization === undefined)
+        return undefined;
+    const intl = {};
+    for (const locale of localization.locales) {
+        const label = locale.label;
+        intl[locale.code] =
+            typeof label === 'string'
+                ? label
+                : (label?.[localization.defaultLocale] ??
+                    locale.code);
+    }
+    return {
+        locales: localization.localeCodes,
+        default: localization.defaultLocale,
+        fallback: localization.fallback !== false,
+        intl,
+    };
+}
+/** `configuredLocales`, or the single-locale configuration when localization is off. */
+export const localeConfigOf = (config) => configuredLocales(config) ?? SINGLE_LOCALE;
+/**
+ * The language of a request (`requested`: the `locale` parameter or body field). Without Payload
+ * localization it is ignored, so an installation that has none behaves as it did. With it, no
+ * value means the default language and one that is not configured is a `400`; when the
+ * configuration turns `fallback` off, reads do not fall back to the default language either.
+ */
+export function chooseLocale(req, requested) {
+    const configured = configuredLocales(req.payload.config);
+    if (configured === undefined)
+        return { ok: true, locale: undefined, args: {} };
+    const locale = requested === undefined || requested === null || requested === ''
+        ? configured.default
+        : requested;
+    if (!configured.locales.includes(locale)) {
+        return { ok: false, response: fail(400, `The locale "${locale}" is not configured.`) };
+    }
+    return {
+        ok: true,
+        locale,
+        args: { locale, ...(configured.fallback ? {} : { fallbackLocale: false }) },
+    };
+}

package/dist/plugin/options.d.ts

@@ -0,0 +1,77 @@
+import type { ComponentMigrations, RegistryMeta } from '@next-buildr/core';
+import type { PayloadRequest } from 'payload';
+import { z } from 'zod';
+import type { RateLimiter } from './forms/rate-limit.ts';
+/** What the access functions get (`req.user`, ...). */
+export interface AccessArgs {
+    readonly req: PayloadRequest;
+}
+export type AccessFn = (args: AccessArgs) => boolean | Promise<boolean>;
+/** What the plugin needs of a registry: its metadata and, optionally, the component migrations. */
+export interface BuildrRegistry {
+    readonly meta: RegistryMeta;
+    readonly migrations?: ComponentMigrations | undefined;
+}
+export declare const optionsSchema: z.ZodObject<{
+    registry: z.ZodOptional<z.ZodCustom<BuildrRegistry, BuildrRegistry>>;
+    routes: z.ZodDefault<z.ZodObject<{
+        editor: z.ZodDefault<z.ZodString>;
+        canvas: z.ZodDefault<z.ZodString>;
+        preview: z.ZodDefault<z.ZodString>;
+    }, z.core.$strip>>;
+    collections: z.ZodRecord<z.ZodString, z.ZodObject<{
+        context: z.ZodString;
+        path: z.ZodOptional<z.ZodCustom<(doc: Record<string, unknown>) => string, (doc: Record<string, unknown>) => string>>;
+        templates: z.ZodDefault<z.ZodBoolean>;
+        depth: z.ZodDefault<z.ZodNumber>;
+        expectH1: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    globals: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+    queryable: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+        fields: z.ZodArray<z.ZodString>;
+        sort: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>>;
+    media: z.ZodOptional<z.ZodObject<{
+        collection: z.ZodString;
+    }, z.core.$strip>>;
+    forms: z.ZodDefault<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        notifyAllowlist: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        notifyTo: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        rateLimit: z.ZodDefault<z.ZodObject<{
+            limit: z.ZodDefault<z.ZodNumber>;
+            windowMs: z.ZodDefault<z.ZodNumber>;
+        }, z.core.$strip>>;
+        rateLimiter: z.ZodOptional<z.ZodCustom<RateLimiter, RateLimiter>>;
+    }, z.core.$strip>>;
+    access: z.ZodDefault<z.ZodObject<{
+        edit: z.ZodOptional<z.ZodCustom<AccessFn, AccessFn>>;
+        publish: z.ZodOptional<z.ZodCustom<AccessFn, AccessFn>>;
+        unlockTemplates: z.ZodOptional<z.ZodCustom<AccessFn, AccessFn>>;
+    }, z.core.$strip>>;
+    mcp: z.ZodDefault<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        allowPublish: z.ZodDefault<z.ZodBoolean>;
+        collections: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        rateLimit: z.ZodDefault<z.ZodObject<{
+            limit: z.ZodDefault<z.ZodNumber>;
+            windowMs: z.ZodDefault<z.ZodNumber>;
+        }, z.core.$strip>>;
+        rateLimiter: z.ZodOptional<z.ZodCustom<RateLimiter, RateLimiter>>;
+    }, z.core.$strip>>;
+    limits: z.ZodDefault<z.ZodObject<{
+        maxNodes: z.ZodDefault<z.ZodNumber>;
+        maxBytes: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
+    a11y: z.ZodDefault<z.ZodObject<{
+        publish: z.ZodDefault<z.ZodEnum<{
+            block: "block";
+            warn: "warn";
+        }>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type BuildrPluginOptions = z.input<typeof optionsSchema>;
+export type ResolvedOptions = z.output<typeof optionsSchema>;
+/** Validates the options (a bad config fails at startup, with every problem listed). */
+export declare function resolveOptions(input: BuildrPluginOptions): ResolvedOptions;
+//# sourceMappingURL=options.d.ts.map