@next-buildr/payload 0.0.0-stage → 2.0.1

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

@@ -0,0 +1 @@
+{"version":3,"file":"options.d.ts","sourceRoot":"","sources":["../../src/plugin/options.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAC3E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAC9C,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAKzD,uDAAuD;AACvD,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,GAAG,EAAE,cAAc,CAAC;CAC9B;AACD,MAAM,MAAM,QAAQ,GAAG,CAAC,IAAI,EAAE,UAAU,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;AAExE,mGAAmG;AACnG,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,UAAU,CAAC,EAAE,mBAAmB,GAAG,SAAS,CAAC;CACvD;AAoBD,eAAO,MAAM,aAAa;;;;;;;;;8CAdT,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAqHjD,CAAC;AAEH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAChE,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,aAAa,CAAC,CAAC;AAE7D,wFAAwF;AACxF,wBAAgB,cAAc,CAAC,KAAK,EAAE,mBAAmB,GAAG,eAAe,CAS1E"}

package/dist/plugin/options.js

@@ -0,0 +1,123 @@
+import { z } from 'zod';
+/** A function the host supplies; Zod only checks that it is one, the plugin never runs it at startup. */
+const fn = () => z.custom((value) => typeof value === 'function', 'must be a function');
+const collectionOptions = z.object({
+    /** The name the collection document is bound under in dynamic values (`page`, `post`, ...). */
+    context: z.string().min(1),
+    /** The public path of a document; drives previews, revalidation and `route` in the context. */
+    path: fn().optional(),
+    /** Templates (`buildr-templates`) can be attached to this collection. */
+    templates: z.boolean().default(false),
+    /** How deep relations are resolved in the context. */
+    depth: z.number().int().min(0).max(5).default(0),
+    /** Whether the a11y rules expect exactly one `h1`. */
+    expectH1: z.boolean().default(false),
+});
+const queryableOptions = z.object({
+    fields: z.array(z.string().min(1)),
+    sort: z.array(z.string().min(1)).default([]),
+});
+export const optionsSchema = z.object({
+    /** Only its metadata and migrations are used, so `{ meta }` is enough (a React registry fits too). */
+    registry: z
+        .custom((value) => typeof value === 'object' &&
+        value !== null &&
+        typeof value.meta === 'object')
+        .optional(),
+    routes: z
+        .object({
+        editor: z.string().startsWith('/').default('/buildr/edit'),
+        canvas: z.string().startsWith('/').default('/buildr/canvas'),
+        preview: z.string().startsWith('/').default('/buildr/preview'),
+    })
+        .default({ editor: '/buildr/edit', canvas: '/buildr/canvas', preview: '/buildr/preview' }),
+    collections: z.record(z.string().min(1), collectionOptions),
+    globals: z.record(z.string().min(1), z.string().min(1)).default({}),
+    queryable: z.record(z.string().min(1), queryableOptions).default({}),
+    media: z.object({ collection: z.string().min(1) }).optional(),
+    forms: z
+        .object({
+        /** Adds `buildr-form-submissions` and the public submission endpoint (needs `registry`). */
+        enabled: z.boolean().default(false),
+        /** Who a notification may go to: exact addresses or domains (`@example.com`). */
+        notifyAllowlist: z.array(z.string()).default([]),
+        /** Notified about every submission; each must match `notifyAllowlist`. */
+        notifyTo: z.array(z.string()).default([]),
+        /** Attempts per visitor and form per window; used by the bundled in-memory limiter. */
+        rateLimit: z
+            .object({
+            limit: z.number().int().positive().default(5),
+            windowMs: z.number().int().positive().default(60_000),
+        })
+            .default({ limit: 5, windowMs: 60_000 }),
+        /** Replaces the in-memory limiter (which does not span serverless instances). */
+        rateLimiter: z
+            .custom((value) => typeof value === 'object' &&
+            value !== null &&
+            typeof value.hit === 'function', 'must be a rate limiter')
+            .optional(),
+    })
+        .default({
+        enabled: false,
+        notifyAllowlist: [],
+        notifyTo: [],
+        rateLimit: { limit: 5, windowMs: 60_000 },
+    }),
+    access: z
+        .object({
+        edit: fn().optional(),
+        publish: fn().optional(),
+        unlockTemplates: fn().optional(),
+    })
+        .default({}),
+    /**
+     * Access for AI agents (docs/mcp.md, ADR-024): Payload API-key requests, document listing and
+     * creation. Off by default; an API-key request is refused by the builder endpoints unless enabled.
+     */
+    mcp: z
+        .object({
+        enabled: z.boolean().default(false),
+        /** Lets an API-key user publish (they still need `access.publish`); off by default. */
+        allowPublish: z.boolean().default(false),
+        /** The collections an agent may list, create in and edit; default: all builder collections. */
+        collections: z.array(z.string().min(1)).optional(),
+        /** Writes per API-key user and window; used by the bundled in-memory limiter. */
+        rateLimit: z
+            .object({
+            limit: z.number().int().positive().default(60),
+            windowMs: z.number().int().positive().default(60_000),
+        })
+            .default({ limit: 60, windowMs: 60_000 }),
+        /** Replaces the in-memory limiter (which does not span serverless instances). */
+        rateLimiter: z
+            .custom((value) => typeof value === 'object' &&
+            value !== null &&
+            typeof value.hit === 'function', 'must be a rate limiter')
+            .optional(),
+    })
+        .default({
+        enabled: false,
+        allowPublish: false,
+        rateLimit: { limit: 60, windowMs: 60_000 },
+    }),
+    limits: z
+        .object({
+        maxNodes: z.number().int().positive().default(5000),
+        maxBytes: z.number().int().positive().default(2_000_000),
+    })
+        .default({ maxNodes: 5000, maxBytes: 2_000_000 }),
+    a11y: z
+        .object({ publish: z.enum(['warn', 'block']).default('warn') })
+        .default({ publish: 'warn' }),
+});
+/** Validates the options (a bad config fails at startup, with every problem listed). */
+export function resolveOptions(input) {
+    const parsed = optionsSchema.safeParse(input);
+    if (!parsed.success) {
+        const problems = parsed.error.issues
+            .map((issue) => `  - ${issue.path.join('.') || '(options)'}: ${issue.message}`)
+            .join('\n');
+        throw new Error(`buildrPlugin: invalid options\n${problems}`);
+    }
+    return parsed.data;
+}

package/dist/plugin/plugin.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=plugin.test.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.test.d.ts","sourceRoot":"","sources":["../../src/plugin/plugin.test.ts"],"names":[],"mappings":""}

package/dist/plugin/plugin.test.js

@@ -0,0 +1,186 @@
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createEmptyDocument } from '@next-buildr/core';
+import { sqliteAdapter } from '@payloadcms/db-sqlite';
+import { buildConfig, getPayload } from 'payload';
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { buildrPlugin } from './index.js';
+import { BUILDR_WRITE } from './write-guard.js';
+const pages = {
+    slug: 'pages',
+    fields: [{ name: 'title', type: 'text' }],
+    versions: { drafts: { autosave: true } },
+};
+const layoutOf = (name) => ({
+    ...createEmptyDocument(),
+    nodes: { root: { id: 'root', type: 'buildr/page', name } },
+});
+let dir;
+const configOf = (options, collections = [pages]) => buildConfig({
+    secret: 'test-secret',
+    collections,
+    db: sqliteAdapter({
+        client: { url: `file:${join(dir, `${Math.random().toString(36).slice(2)}.db`)}` },
+    }),
+    plugins: [buildrPlugin(options)],
+    typescript: { autoGenerate: false },
+});
+// Only the write-guard suite talks to a database: Payload pushes the schema through one shared
+// drizzle-kit state, so a second live instance in the same process would find no tables.
+const boot = async (options) => getPayload({ config: configOf(options), key: 'write-guard' });
+beforeAll(() => {
+    dir = mkdtempSync(join(tmpdir(), 'buildr-payload-'));
+});
+afterAll(() => {
+    try {
+        rmSync(dir, { recursive: true, force: true });
+    }
+    catch {
+        // Windows keeps the database file open a moment longer; the temp dir is cleaned by the OS.
+    }
+});
+describe('buildrPlugin', () => {
+    it('adds the fields to the configured collections only', async () => {
+        const config = await configOf({ collections: { pages: { context: 'page', templates: true } } });
+        const names = (slug) => config.collections
+            .find((collection) => collection.slug === slug)
+            ?.fields.map((field) => field.name);
+        expect(names('pages')).toEqual(expect.arrayContaining(['layout', 'buildrRevision', 'template']));
+        expect(names('buildr-templates')).toEqual(expect.arrayContaining(['title', 'targetCollection', 'isDefault', 'layout']));
+        const layout = config.collections[0]?.fields.find((field) => field.name === 'layout');
+        expect(layout.admin?.components?.Field).toEqual({
+            path: '@next-buildr/payload/admin#LayoutField',
+            clientProps: { editorRoute: '/buildr/edit' },
+        });
+    });
+    it('leaves out the template field unless the collection takes templates', async () => {
+        const config = await configOf({ collections: { pages: { context: 'page' } } });
+        const names = config.collections[0]?.fields.map((field) => field.name);
+        expect(names).not.toContain('template');
+    });
+    it('adds buildr-templates only when a collection takes templates, and never twice', async () => {
+        const without = await configOf({ collections: { pages: { context: 'page' } } });
+        expect(without.collections.map((collection) => collection.slug)).not.toContain('buildr-templates');
+        await expect(configOf({ collections: { pages: { context: 'page', templates: true } } }, [
+            pages,
+            { slug: 'buildr-templates', fields: [] },
+        ])).rejects.toThrow(/added by the plugin/);
+    });
+    it('rejects bad options, listing each problem', () => {
+        expect(() => buildrPlugin({ collections: { pages: { context: '' } }, limits: { maxNodes: -1 } })).toThrow(/collections\.pages\.context[\s\S]*limits\.maxNodes/);
+    });
+    it('requires an existing collection with drafts and free field names', async () => {
+        await expect(configOf({ collections: { nope: { context: 'x' } } })).rejects.toThrow(/"nope" does not exist/);
+        await expect(configOf({ collections: { plain: { context: 'x' } } }, [{ slug: 'plain', fields: [] }])).rejects.toThrow(/versions\.drafts/);
+        await expect(configOf({ collections: { pages: { context: 'x' } } }, [
+            { ...pages, fields: [{ name: 'layout', type: 'text' }] },
+        ])).rejects.toThrow(/already has a "layout" field/);
+    });
+    describe('write-guard', () => {
+        let payload;
+        beforeAll(async () => {
+            payload = await boot({ collections: { pages: { context: 'page' } } });
+        });
+        const create = () => payload.create({
+            collection: 'pages',
+            data: { title: 'One', layout: layoutOf('a'), buildrRevision: 1 },
+            draft: true,
+        });
+        const latest = async (id) => {
+            const found = await payload.findByID({ collection: 'pages', id, draft: true });
+            return found;
+        };
+        it('accepts the layout when the document is created', async () => {
+            const doc = await create();
+            expect((await latest(doc.id)).layout).toEqual(layoutOf('a'));
+        });
+        it('never changes the layout for an update that is not the builder', async () => {
+            const doc = await create();
+            // What the admin form does: it resubmits the layout it loaded, next to the edited title.
+            await payload.update({
+                collection: 'pages',
+                id: doc.id,
+                data: { title: 'Two', layout: layoutOf('stale'), buildrRevision: 99 },
+                draft: true,
+            });
+            const after = await latest(doc.id);
+            expect(after.title).toBe('Two');
+            expect(after.layout).toEqual(layoutOf('a'));
+            expect(after.buildrRevision).toBe(1);
+        });
+        it('keeps the builder edits when the admin saves afterwards (drafts and autosave)', async () => {
+            const doc = await create();
+            await payload.update({
+                collection: 'pages',
+                id: doc.id,
+                data: { layout: layoutOf('built'), buildrRevision: 2 },
+                draft: true,
+                autosave: true,
+                context: { [BUILDR_WRITE]: true },
+            });
+            await payload.update({
+                collection: 'pages',
+                id: doc.id,
+                data: { title: 'Renamed', layout: layoutOf('a'), buildrRevision: 1 },
+                draft: true,
+                autosave: true,
+            });
+            const after = await latest(doc.id);
+            expect(after.title).toBe('Renamed');
+            expect(after.layout).toEqual(layoutOf('built'));
+            expect(after.buildrRevision).toBe(2);
+        });
+        it('protects the layout when the admin publishes too', async () => {
+            const doc = await create();
+            await payload.update({
+                collection: 'pages',
+                id: doc.id,
+                data: { layout: layoutOf('built'), buildrRevision: 2 },
+                draft: true,
+                context: { [BUILDR_WRITE]: true },
+            });
+            await payload.update({
+                collection: 'pages',
+                id: doc.id,
+                data: { title: 'Live', layout: layoutOf('a'), _status: 'published' },
+                draft: false,
+            });
+            const published = (await payload.findByID({
+                collection: 'pages',
+                id: doc.id,
+            }));
+            expect(published.layout).toEqual(layoutOf('built'));
+        });
+    });
+});
+describe('buildrPlugin mcp option', () => {
+    const collections = { pages: { context: 'page' } };
+    const users = (auth) => ({
+        slug: 'users',
+        auth,
+        fields: [],
+    });
+    it('is off by default and needs no API-key collection then', async () => {
+        const config = await configOf({ collections }, [pages]);
+        const page = config.collections.find((c) => c.slug === 'pages');
+        expect(page?.fields.some((f) => 'name' in f && f.name === 'buildrUpdatedBy')).toBe(false);
+    });
+    it('requires an auth collection with useAPIKey when enabled', async () => {
+        await expect(configOf({ collections, mcp: { enabled: true } }, [pages, users(true)])).rejects.toThrow(/useAPIKey/);
+    });
+    it('adds buildrUpdatedBy when enabled', async () => {
+        const config = await configOf({ collections, mcp: { enabled: true } }, [
+            pages,
+            users({ useAPIKey: true }),
+        ]);
+        const page = config.collections.find((c) => c.slug === 'pages');
+        expect(page?.fields.some((f) => 'name' in f && f.name === 'buildrUpdatedBy')).toBe(true);
+    });
+    it('rejects mcp.collections that are not builder collections', async () => {
+        await expect(configOf({ collections, mcp: { enabled: true, collections: ['posts'] } }, [
+            pages,
+            users({ useAPIKey: true }),
+        ])).rejects.toThrow(/mcp\.collections "posts"/);
+    });
+});

package/dist/plugin/write-guard.d.ts

@@ -0,0 +1,14 @@
+import type { FieldHook } from 'payload';
+/**
+ * The context flag every write of the builder endpoints sets (docs/payload.md#save-autosave-drafts-publish-versions).
+ * Anything else that saves the document (Payload Admin form, the REST API, a script) is not allowed to change `layout`.
+ */
+export declare const BUILDR_WRITE = "buildrWrite";
+/**
+ * Payload Admin submits every field, including the `layout` it loaded when the form opened; taking
+ * that value would overwrite what the builder saved since. So a write only changes the guarded field
+ * when it comes from the builder (or creates the document); otherwise the stored value is kept.
+ * `originalDoc` is the latest draft when drafts are enabled, which is exactly the value to keep.
+ */
+export declare const writeGuard: (name: string) => FieldHook;
+//# sourceMappingURL=write-guard.d.ts.map

package/dist/plugin/write-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"write-guard.d.ts","sourceRoot":"","sources":["../../src/plugin/write-guard.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAEzC;;;GAGG;AACH,eAAO,MAAM,YAAY,gBAAgB,CAAC;AAE1C;;;;;GAKG;AACH,eAAO,MAAM,UAAU,SACd,MAAM,KAAG,SAKf,CAAC"}

package/dist/plugin/write-guard.js

@@ -0,0 +1,18 @@
+/**
+ * The context flag every write of the builder endpoints sets (docs/payload.md#save-autosave-drafts-publish-versions).
+ * Anything else that saves the document (Payload Admin form, the REST API, a script) is not allowed to change `layout`.
+ */
+export const BUILDR_WRITE = 'buildrWrite';
+/**
+ * Payload Admin submits every field, including the `layout` it loaded when the form opened; taking
+ * that value would overwrite what the builder saved since. So a write only changes the guarded field
+ * when it comes from the builder (or creates the document); otherwise the stored value is kept.
+ * `originalDoc` is the latest draft when drafts are enabled, which is exactly the value to keep.
+ */
+export const writeGuard = (name) => ({ value, originalDoc, operation, req }) => {
+    if (operation === 'create')
+        return value;
+    if (req.context[BUILDR_WRITE] === true)
+        return value;
+    return originalDoc?.[name];
+};

package/package.json

@@ -1,6 +1,111 @@
 {
   "name": "@next-buildr/payload",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "2.0.1",
+  "private": false,
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    "./plugin": {
+      "types": "./dist/plugin/index.d.ts",
+      "default": "./dist/plugin/index.js"
+    },
+    "./data": {
+      "types": "./dist/data/index.d.ts",
+      "default": "./dist/data/index.js"
+    },
+    "./admin": {
+      "types": "./dist/admin/index.d.ts",
+      "default": "./dist/admin/index.js"
+    },
+    "./adapter": {
+      "types": "./dist/adapter/index.d.ts",
+      "default": "./dist/adapter/index.js"
+    },
+    "./next": {
+      "types": "./dist/next/index.d.ts",
+      "default": "./dist/next/index.js"
+    },
+    "./mcp": {
+      "types": "./dist/mcp/index.d.ts",
+      "default": "./dist/mcp/index.js"
+    },
+    "./package.json": "./package.json",
+    "./mcp/route": {
+      "types": "./dist/mcp/route.d.ts",
+      "default": "./dist/mcp/route.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@next-buildr/core": "2.0.1",
+    "zod": "^4.6.5"
+  },
+  "peerDependencies": {
+    "@next-buildr/editor": "2.0.1",
+    "@next-buildr/mcp": "2.0.1",
+    "@next-buildr/next": "2.0.1",
+    "@modelcontextprotocol/sdk": "^1.30.1",
+    "@payloadcms/ui": "^3.0.0",
+    "next": "^15.0.0 || ^16.0.0",
+    "payload": "^3.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@next-buildr/editor": {
+      "optional": true
+    },
+    "@next-buildr/mcp": {
+      "optional": true
+    },
+    "@next-buildr/next": {
+      "optional": true
+    },
+    "@modelcontextprotocol/sdk": {
+      "optional": true
+    },
+    "@payloadcms/ui": {
+      "optional": true
+    },
+    "next": {
+      "optional": true
+    },
+    "payload": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@next-buildr/editor": "2.0.1",
+    "@next-buildr/mcp": "2.0.1",
+    "@next-buildr/next": "2.0.1",
+    "@next-buildr/test-utils": "2.0.1",
+    "@next-buildr/tsconfig": "2.0.1",
+    "@modelcontextprotocol/sdk": "^1.30.1",
+    "@payloadcms/db-sqlite": "3.90.1",
+    "@payloadcms/ui": "3.90.1",
+    "@types/node": "^22.0.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "jsdom": "^30.1.1",
+    "next": "16.3.5",
+    "payload": "3.90.1",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "typescript": "7.0.2",
+    "vitest": "5.0.1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/czekanskyy/buildr.git",
+    "directory": "packages/payload"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
 }