@abinnovision/payloadcms-mcpx 1.0.0-beta.3

package/dist/tools/patch-document.mjs

@@ -0,0 +1,113 @@
+import { errorResult, jsonResult } from "../endpoint/result.mjs";
+import { collectionEnum, ensureAllowed, idSchema, localeOf, localeShape, readDraft } from "./shared.mjs";
+import { PATCH_OPERATION_SCHEMA, applyPatchToCopy, buildWriteData, findPatchProblems, isElementPointer } from "../write/patch.mjs";
+import { collectPublishBlockers } from "../write/publish-blockers.mjs";
+import { withTransaction } from "../write/transaction.mjs";
+import { z } from "zod";
+import { Pointer } from "rfc6902";
+//#region src/tools/patch-document.ts
+const DESCRIPTION = `Applies RFC 6902 JSON Patch operations to one document.
+
+The write always lands as a draft and is never published, whatever it contains; publishing stays a human action in the admin panel.
+
+Only the fields describeSchema lists can be addressed. A pointer that does not resolve is refused with the fields that are valid at that point, and nothing is applied unless every operation in the batch validates first. Use describeSchema to find a field's path, then turn it into a pointer by replacing "." with "/" and each "[]" with a 0-based index.
+
+Adding a block requires "blockType" on the value. Append with "/-" as the last segment. To clear a field use "replace" with null; an array or blocks field refuses null and is emptied with [] instead. "remove" is only for list elements, because a field left out of a write is kept rather than cleared. Read the document first to learn the indices, and pass its "updatedAt" as expectedUpdatedAt so a concurrent edit is refused rather than overwritten.
+
+A successful write may come back with "publishBlockers": everything still wrong with the draft, such as required fields left empty. Those do not fail the write, because a draft is allowed to be incomplete, but a human cannot publish the document until the list is empty. "notApplied" lists pointers whose value Payload kept unchanged, which happens when field-level access denies the update.`;
+const sameInstant = (left, right) => typeof left === "string" && new Date(left).getTime() === new Date(right).getTime();
+const isPlainObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/**
+* Whether the intended value survived the write. The saved document is
+* allowed to carry more than was sent: Payload assigns fresh row ids and
+* backfills defaults and nulls on save, so `id` keys are ignored and only
+* the keys the client sent are compared. Null and absent count as equal.
+*/ const survives = (expected, actual) => {
+	if (expected === void 0 || expected === null) return actual === void 0 || actual === null;
+	if (Array.isArray(expected)) return Array.isArray(actual) && expected.length === actual.length && expected.every((entry, index) => survives(entry, actual[index]));
+	if (isPlainObject(expected)) return isPlainObject(actual) && Object.entries(expected).every(([key, value]) => key === "id" || survives(value, actual[key]));
+	return isPlainObject(actual) || Array.isArray(actual) ? false : JSON.stringify(expected) === JSON.stringify(actual);
+};
+/**
+* Pointers whose intended value did not survive the write. Element pointers
+* are skipped: an append pointer (`/-`) does not resolve against the saved
+* document.
+*/ const notAppliedPointers = (patches, intended, saved) => patches.flatMap((operation) => {
+	if (operation.op !== "add" && operation.op !== "replace" || isElementPointer(operation.path)) return [];
+	const pointer = Pointer.fromJSON(operation.path);
+	const expected = pointer.get(intended);
+	const actual = pointer.get(saved);
+	return survives(expected, actual) ? [] : [operation.path];
+});
+const patchDocument = {
+	name: "patchDocument",
+	description: DESCRIPTION,
+	annotations: {
+		readOnlyHint: false,
+		destructiveHint: false,
+		idempotentHint: false,
+		openWorldHint: false
+	},
+	isEnabled: (scope) => scope.writable.length > 0,
+	inputSchema: (scope) => ({
+		collection: collectionEnum(scope.writable).describe("Collection holding the document."),
+		id: idSchema,
+		...localeShape(scope, {
+			required: true,
+			description: "Locale the patch applies to. Localized fields write here only."
+		}),
+		patches: z.array(PATCH_OPERATION_SCHEMA).min(1).describe("Operations, applied in order."),
+		expectedUpdatedAt: z.string().optional().describe("The updatedAt read before patching. The write is refused if the document has changed since.")
+	}),
+	handler: async (args, scope) => {
+		const collection = ensureAllowed(scope, args.collection, "write");
+		const { payload } = scope.req;
+		const locale = localeOf(scope, args.locale);
+		return await withTransaction(scope.req, async () => {
+			const doc = await readDraft(scope, {
+				collection: args.collection,
+				id: args.id,
+				locale
+			});
+			if (args.expectedUpdatedAt !== void 0 && !sameInstant(doc["updatedAt"], args.expectedUpdatedAt)) return errorResult("The document changed since you read it. Read it again and re-apply the patch.", { updatedAt: doc["updatedAt"] });
+			const problems = findPatchProblems(payload.config, {
+				collection: args.collection,
+				doc,
+				patches: args.patches
+			});
+			if (problems.length > 0) return errorResult("No operation was applied.", { problems });
+			const applied = applyPatchToCopy(doc, args.patches);
+			if ("problems" in applied) return errorResult("No operation was applied.", { problems: applied.problems });
+			await payload.update({
+				collection: args.collection,
+				id: args.id,
+				data: buildWriteData(payload.config, collection, applied.next),
+				depth: 0,
+				draft: true,
+				overrideAccess: false,
+				req: scope.req,
+				...locale === void 0 ? {} : { locale }
+			});
+			const saved = await readDraft(scope, {
+				collection: args.collection,
+				id: args.id,
+				locale,
+				privileged: true
+			});
+			const notApplied = notAppliedPointers(args.patches, applied.next, saved);
+			const publishBlockers = await collectPublishBlockers(scope.req, {
+				collection,
+				doc: saved
+			});
+			return jsonResult({
+				id: saved["id"],
+				status: saved["_status"],
+				updatedAt: saved["updatedAt"],
+				...publishBlockers.length > 0 ? { publishBlockers } : {},
+				...notApplied.length > 0 ? { notApplied } : {}
+			});
+		});
+	}
+};
+//#endregion
+export { patchDocument };

package/dist/tools/shared.mjs

@@ -0,0 +1,65 @@
+import { Forbidden, NotFound } from "payload";
+import { z } from "zod";
+//#region src/tools/shared.ts
+const collectionEnum = (slugs) => z.enum(slugs);
+const idSchema = z.union([z.string(), z.number()]).describe("Document id.");
+/**
+* The `locale` argument, present only when localization is configured.
+*/ const localeShape = (scope, options) => {
+	if (!scope.locales) return {};
+	const locale = z.enum(scope.locales);
+	return { locale: (options.required ? locale : locale.optional()).describe(options.description) };
+};
+const depthShape = (scope) => ({ depth: z.number().int().min(0).max(scope.options.limits.maxDepth).optional().describe(`Relationship population depth. Default 0, at most ${String(scope.options.limits.maxDepth)}.`) });
+/**
+* Throws unless the key may perform `operation` on `slug`. The input schema
+* already limits the enum, so this only guards against a stale tool list.
+*/ const ensureAllowed = (scope, slug, operation) => {
+	const allowed = operation === "read" ? scope.readable : scope.writable;
+	const collection = scope.req.payload.collections[slug];
+	if (!allowed.includes(slug) || !collection) throw new Forbidden(scope.req.t);
+	return collection.config;
+};
+/**
+* The locale to operate on: the explicit argument, else the request's, else
+* the default. `undefined` when localization is off.
+*/ const localeOf = (scope, locale) => {
+	if (!scope.locales) return;
+	const requested = locale ?? scope.req.locale;
+	return (requested && scope.locales.includes(requested) ? requested : scope.defaultLocale) ?? void 0;
+};
+/**
+* Reads the current draft in a fixed locale with no fallback, which is the
+* shape that may be written back or validated without mixing locales.
+*/ const readDraft = async (scope, args) => {
+	const doc = await scope.req.payload.findByID({
+		collection: args.collection,
+		id: args.id,
+		depth: 0,
+		draft: true,
+		...args.locale === void 0 ? {} : {
+			locale: args.locale,
+			fallbackLocale: false
+		},
+		overrideAccess: args.privileged === true,
+		showHiddenFields: args.privileged === true,
+		disableErrors: true,
+		req: scope.req
+	});
+	if (!doc) throw new NotFound(scope.req.t);
+	return doc;
+};
+/**
+* Resolves a collection label for the request's language.
+*/ const translateLabel = (scope, label, fallback) => {
+	const { i18n, t } = scope.req;
+	const resolved = typeof label === "function" ? label({
+		i18n,
+		t
+	}) : label;
+	if (typeof resolved === "string") return resolved;
+	if (resolved && typeof resolved === "object") return resolved[i18n.language] ?? Object.values(resolved)[0] ?? fallback;
+	return fallback;
+};
+//#endregion
+export { collectionEnum, depthShape, ensureAllowed, idSchema, localeOf, localeShape, readDraft, translateLabel };

package/dist/tools/validate-document.mjs

@@ -0,0 +1,48 @@
+import { jsonResult } from "../endpoint/result.mjs";
+import { collectionEnum, ensureAllowed, idSchema, localeOf, localeShape, readDraft } from "./shared.mjs";
+import { collectPublishBlockers } from "../write/publish-blockers.mjs";
+//#region src/tools/validate-document.ts
+const validateDocument = {
+	name: "validateDocument",
+	description: `Reports what still prevents a human from publishing the draft, without writing anything. The same list patchDocument returns after a write; use it to check work or to answer "is this ready".`,
+	annotations: {
+		readOnlyHint: true,
+		openWorldHint: false
+	},
+	isEnabled: (scope) => scope.writable.length > 0,
+	inputSchema: (scope) => ({
+		collection: collectionEnum(scope.writable).describe("Collection holding the document."),
+		id: idSchema,
+		...localeShape(scope, {
+			required: true,
+			description: "Locale to validate."
+		})
+	}),
+	handler: async (args, scope) => {
+		const collection = ensureAllowed(scope, args.collection, "write");
+		const locale = localeOf(scope, args.locale);
+		await readDraft(scope, {
+			collection: args.collection,
+			id: args.id,
+			locale
+		});
+		const doc = await readDraft(scope, {
+			collection: args.collection,
+			id: args.id,
+			locale,
+			privileged: true
+		});
+		const publishBlockers = await collectPublishBlockers(scope.req, {
+			collection,
+			doc
+		});
+		return jsonResult({
+			id: doc["id"],
+			status: doc["_status"],
+			updatedAt: doc["updatedAt"],
+			publishBlockers
+		});
+	}
+};
+//#endregion
+export { validateDocument };

package/dist/types.d.mts

@@ -0,0 +1,113 @@
+import { CollectionConfig, CollectionSlug, PayloadRequest, TypedUser } from "payload";
+import { z } from "zod";
+import { RequestHandlerExtra } from "@modelcontextprotocol/sdk/shared/protocol.js";
+import { CallToolResult, ServerNotification, ServerRequest, ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";
+//#region src/types.d.ts
+declare module "payload" {
+  interface RequestContext {
+    mcpx?: McpxRequestContext;
+  }
+  interface RegisteredPlugins {
+    "@abinnovision/payloadcms-mcpx": McpxPluginOptions;
+  }
+}
+/**
+ * What an exposed collection offers to MCP clients. A key can only enable
+ * what the config exposes here.
+ */
+interface McpxCollectionOptions {
+  /** Expose `describeSchema`, `findDocuments` and `getDocument`. Default `true`. */
+  read?: boolean;
+  /**
+   * Expose `patchDocument`, `createDocument` and `validateDocument`. Default
+   * `false`. Requires `versions.drafts` unless `allowLiveWrites` is set.
+   */
+  write?: boolean;
+  /**
+   * Permit writes to a collection without drafts. Such writes land on the live
+   * document because there is no draft to land on. Default `false`.
+   */
+  allowLiveWrites?: boolean;
+}
+type McpxToolExtra = RequestHandlerExtra<ServerRequest, ServerNotification>;
+/**
+ * A custom tool. It is gated by its own checkbox on every API key and runs
+ * with `req.user` resolved from the key and `req.context.mcpx` set.
+ */
+interface McpxTool<Shape extends z.ZodRawShape = z.ZodRawShape> {
+  /** camelCase, unique, not one of the builtin tool names. */
+  name: string;
+  description: string;
+  inputSchema?: Shape;
+  annotations?: ToolAnnotations;
+  handler(ctx: {
+    args: z.infer<z.ZodObject<Shape>>;
+    req: PayloadRequest;
+    extra: McpxToolExtra;
+  }): CallToolResult | Promise<CallToolResult>;
+}
+/**
+ * Identity helper that infers the argument type of a custom tool's handler
+ * from its input schema.
+ */
+declare const defineMcpxTool: <Shape extends z.ZodRawShape>(tool: McpxTool<Shape>) => McpxTool<Shape>;
+/**
+ * Outcome of resolving an API key. `user` must carry `collection`.
+ */
+interface McpxAuthResult {
+  user: TypedUser;
+  apiKeyId: number | string;
+  /** The `capabilities` group as stored on the key document. */
+  capabilities: unknown;
+}
+type McpxPluginOptions = {
+  /** Allow-list of collections. `true` is shorthand for `{ read: true }`. */
+  collections: Partial<Record<CollectionSlug, McpxCollectionOptions | true>>;
+  /** Collection the keys act as. Default `config.admin.user`, then `users`. */
+  userCollection?: CollectionSlug;
+  apiKeys?: {
+    /** Slug of the generated API key collection. Default `mcpx-api-keys`. */
+    slug?: string;
+    /** Final override applied to the generated collection. */
+    overrideCollection?: (collection: CollectionConfig) => CollectionConfig;
+  };
+  endpoint?: {
+    /** Endpoint path below the API route. Default `/mcpx`. */
+    path?: string;
+  };
+  limits?: {
+    /** Upper bound for `findDocuments.limit`. Default 25. */
+    maxLimit?: number;
+    /** Upper bound for `depth` on reads. Default 1. */
+    maxDepth?: number;
+  };
+  tools?: McpxTool[];
+  auth?: {
+    /** Replace or wrap the default key resolution. Return `null` for 401. */
+    resolve?: (args: {
+      req: PayloadRequest;
+      resolveDefault: () => Promise<McpxAuthResult | null>;
+    }) => Promise<McpxAuthResult | null>;
+  };
+  serverInfo?: {
+    name?: string;
+    version?: string;
+  };
+};
+interface McpxCollectionCapabilities {
+  read: boolean;
+  write: boolean;
+}
+/**
+ * Capabilities in force for one request: plugin config AND key checkboxes.
+ */
+interface McpxResolvedCapabilities {
+  collections: Record<string, McpxCollectionCapabilities>;
+  tools: Record<string, boolean>;
+}
+interface McpxRequestContext {
+  apiKeyId: number | string;
+  capabilities: McpxResolvedCapabilities;
+}
+//#endregion
+export { McpxAuthResult, McpxCollectionCapabilities, McpxCollectionOptions, McpxPluginOptions, McpxRequestContext, McpxResolvedCapabilities, McpxTool, McpxToolExtra, defineMcpxTool };

package/dist/types.mjs

@@ -0,0 +1,7 @@
+//#region src/types.ts
+/**
+* Identity helper that infers the argument type of a custom tool's handler
+* from its input schema.
+*/ const defineMcpxTool = (tool) => tool;
+//#endregion
+export { defineMcpxTool };

package/dist/version.mjs

@@ -0,0 +1,6 @@
+//#region src/version.ts
+/**
+* Package version injected at build time; sources under Vitest report "dev".
+*/ const MCPX_VERSION = "1.0.0-beta.3";
+//#endregion
+export { MCPX_VERSION };

package/dist/write/draft-guard.d.mts

@@ -0,0 +1,10 @@
+import { CollectionConfig, PayloadRequest } from "payload";
+//#region src/write/draft-guard.d.ts
+/**
+ * Whether a request originated from the MCP endpoint. The endpoint stamps
+ * `req.context.mcpx`, which travels into every local API call made with the
+ * same `req`, including those made by custom tools.
+ */
+declare const isMcpxRequest: (req: PayloadRequest) => boolean;
+//#endregion
+export { isMcpxRequest };

package/dist/write/draft-guard.mjs

@@ -0,0 +1,70 @@
+import { APIError } from "payload";
+import { hasDraftsEnabled } from "payload/shared";
+//#region src/write/draft-guard.ts
+/**
+* Operation arguments that widen or redirect a write. Cleared on every MCP
+* create and update so a tool cannot smuggle them in.
+*/ const STRIPPED_ARGS = /* @__PURE__ */ new Set([
+	"where",
+	"publishAllLocales",
+	"publishSpecificLocale",
+	"unpublishAllLocales",
+	"duplicateFromID",
+	"selectedLocales",
+	"overwriteExistingFiles"
+]);
+/**
+* Whether a request originated from the MCP endpoint. The endpoint stamps
+* `req.context.mcpx`, which travels into every local API call made with the
+* same `req`, including those made by custom tools.
+*/ const isMcpxRequest = (req) => req.context.mcpx !== void 0;
+/**
+* Forces every MCP write into a draft save.
+*
+* `draft` alone is not enough: Payload's update path only saves a draft when
+* `data._status !== "published"`, so `_status` is dropped and left to Payload.
+* This runs as `beforeOperation`, before Payload reads any of these arguments,
+* so it holds for every create and update on an MCP request, not only the
+* builtin tools. Deletes are not guarded in v1; custom tools that delete are
+* the integrator's responsibility.
+*/ const forceDraftWrite = (hookArgs) => {
+	const { args, operation, req } = hookArgs;
+	if (!isMcpxRequest(req) || operation !== "create" && operation !== "update") return args;
+	const next = Object.fromEntries(Object.entries(args).filter(([key]) => !STRIPPED_ARGS.has(key)));
+	if (next["data"] && typeof next["data"] === "object") {
+		const { _status: _ignoredStatus, deletedAt: _ignoredDeletedAt, ...data } = next["data"];
+		next["data"] = data;
+	}
+	next["draft"] = true;
+	next["autosave"] = false;
+	next["overrideLock"] = false;
+	next["trash"] = false;
+	return next;
+};
+/**
+* Refuses an MCP write that would still not land as a draft. An alarm rather
+* than the guarantee: `forceDraftWrite` should make it unreachable. It throws
+* instead of correcting `_status` because Payload has already chosen the write
+* branch by the time a `beforeChange` hook runs.
+*/ const refusePublish = ({ collection, data, req }) => {
+	if (!isMcpxRequest(req)) return data;
+	const status = data._status;
+	if (status === "draft") return data;
+	req.payload.logger.warn(`[payloadcms-mcpx] Refused a write to ${collection.slug} that would not have been a draft (_status: ${String(status)}).`);
+	throw new APIError("MCP clients may only write drafts. This write was refused because it would not have been saved as one.", 403);
+};
+/**
+* Attaches the draft guard to every collection: `forceDraftWrite` everywhere
+* (it is a no-op outside MCP requests) and `refusePublish` wherever drafts
+* exist. Applied to the built collection list so nothing can join later
+* without being covered.
+*/ const installDraftGuards = (collections) => collections.map((collection) => ({
+	...collection,
+	hooks: {
+		...collection.hooks,
+		beforeOperation: [...collection.hooks?.beforeOperation ?? [], forceDraftWrite],
+		...hasDraftsEnabled(collection) ? { beforeChange: [...collection.hooks?.beforeChange ?? [], refusePublish] } : {}
+	}
+}));
+//#endregion
+export { forceDraftWrite, installDraftGuards, isMcpxRequest, refusePublish };

package/dist/write/patch.mjs

@@ -0,0 +1,220 @@
+import { RESERVED_FIELD_NAMES, blockOf, describeFields, findBlocksField, splitPath } from "../schema/walk.mjs";
+import { validateWriteValue } from "../schema/shape.mjs";
+import { resolveDataPointer } from "../schema/pointer.mjs";
+import { z } from "zod";
+import { Pointer, applyPatch } from "rfc6902";
+//#region src/write/patch.ts
+/**
+* One RFC 6902 operation as accepted by `patchDocument`.
+*/ const JSON_POINTER_PATTERN = /^(\/([^~/]|~[01])*)*$/;
+const PATCH_OPERATION_SCHEMA = z.object({
+	from: z.string().regex(JSON_POINTER_PATTERN).optional(),
+	op: z.enum([
+		"add",
+		"copy",
+		"move",
+		"remove",
+		"replace",
+		"test"
+	]),
+	path: z.string().regex(JSON_POINTER_PATTERN),
+	value: z.unknown().optional()
+}).describe("An RFC 6902 operation.");
+/**
+* Whether a pointer touches a field Payload maintains.
+*/ const isReservedPointer = (pointer) => pointer.split("/").slice(1).some((segment) => RESERVED_FIELD_NAMES.has(segment));
+/**
+* The pointer an operation removes a value from, if it removes one at all.
+*/ const droppedPointer = (operation) => {
+	if (operation.op === "remove") return operation.path;
+	return operation.op === "move" ? operation.from : void 0;
+};
+/**
+* Whether a pointer addresses a list element rather than a field.
+*/ const isElementPointer = (pointer) => {
+	const last = pointer.split("/").pop() ?? "";
+	return last === "-" || /^\d+$/.test(last);
+};
+const isPlainObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/**
+* A Lexical editor state. Its nodes manage their own ids, so it is never
+* descended into.
+*/ const isRichTextState = (value) => isPlainObject(value["root"]) && Array.isArray(value["root"]["children"]);
+/**
+* Visits every row in a value: a plain object that carries `blockType` or
+* sits directly inside an array. Rich text states manage their own nodes and
+* are never descended into.
+*/ const walkRows = (value, visit, isRow = false) => {
+	if (Array.isArray(value)) {
+		for (const entry of value) walkRows(entry, visit, true);
+		return;
+	}
+	if (!isPlainObject(value) || isRichTextState(value)) return;
+	if (isRow || typeof value["blockType"] === "string") visit(value);
+	for (const entry of Object.values(value)) walkRows(entry, visit);
+};
+/**
+* Keeps a row id only when the stored document already has it and no earlier
+* row in the write claimed it; every other id is dropped so Payload assigns a
+* fresh one.
+*
+* A kept id makes Payload update the row in place, which preserves the other
+* locales of any localized field inside it. A duplicated id (a copied row) or
+* an id from elsewhere would violate a SQL primary key, so those never pass.
+*/ const reconcileRowIds = (next, stored) => {
+	const known = /* @__PURE__ */ new Set();
+	walkRows(stored, (row) => {
+		if (row["id"] !== void 0) known.add(row["id"]);
+	});
+	const seen = /* @__PURE__ */ new Set();
+	walkRows(next, (row) => {
+		const id = row["id"];
+		if (id === void 0) return;
+		if (known.has(id) && !seen.has(id)) {
+			seen.add(id);
+			return;
+		}
+		delete row["id"];
+	});
+};
+/**
+* Drops every row id from a copy of `value`. Used on create, where no stored
+* row exists and any incoming id is client-invented.
+*/ const stripRowIds = (value) => {
+	const next = structuredClone(value);
+	walkRows(next, (row) => {
+		delete row["id"];
+	});
+	return next;
+};
+/**
+* Applies a patch to a deep copy of the document, so a failing operation
+* leaves the original untouched and nothing partial is ever written.
+*/ const applyPatchToCopy = (doc, patches) => {
+	const next = structuredClone(doc);
+	const prepared = patches.map((operation) => {
+		const cloned = "value" in operation ? {
+			...operation,
+			value: structuredClone(operation.value)
+		} : operation;
+		if (cloned.op === "replace" && !isElementPointer(cloned.path) && Pointer.fromJSON(cloned.path).get(next) === void 0) return {
+			...cloned,
+			op: "add"
+		};
+		return cloned;
+	});
+	const problems = applyPatch(next, prepared).flatMap((error, index) => error ? [`patches[${String(index)}]: ${error.message}`] : []);
+	if (problems.length > 0) return { problems };
+	reconcileRowIds(next, doc);
+	return { next };
+};
+/**
+* Checks every operation against the schema before any is applied.
+*
+* A partially applied batch is worse than a refused one, so this returns all
+* problems and the caller applies nothing unless the list is empty.
+*/ const findPatchProblems = (config, target) => target.patches.flatMap((operation, index) => {
+	const at = `patches[${String(index)}]`;
+	const pointers = [operation.path, ..."from" in operation && operation.from ? [operation.from] : []];
+	if (pointers.includes("")) return [`${at}: an empty pointer addresses the whole document. Address a field instead.`];
+	const reserved = pointers.find(isReservedPointer);
+	if (reserved !== void 0) return [`${at}: "${reserved}" addresses a field Payload maintains. Drafts are the only thing this tool writes, and id, _status, createdAt and updatedAt are not writable.`];
+	const dropped = droppedPointer(operation);
+	if (dropped !== void 0 && !isElementPointer(dropped)) return [`${at}: "${dropped}" is a field, not a list element, and removing it would do nothing. The patched document is written whole, and Payload keeps any field absent from a write rather than clearing it. Use "replace" with null to clear a field, or with [] to empty a list.`];
+	const value = "value" in operation ? operation.value : void 0;
+	try {
+		const moved = "from" in operation && operation.from ? Pointer.fromJSON(operation.from).get(target.doc) : void 0;
+		for (const pointer of pointers) {
+			const resolution = resolveDataPointer(config, {
+				addedValue: value ?? moved,
+				collection: target.collection,
+				doc: target.doc,
+				pointer
+			});
+			if (pointer === operation.path && value !== void 0) return validateWriteValue(config, {
+				pointer,
+				resolution
+			}, value).map((problem) => `${at}: ${problem}`);
+		}
+		return [];
+	} catch (error) {
+		return [`${at}: ${error instanceof Error ? error.message : "invalid"}`];
+	}
+});
+/**
+* Keys Payload manages on a row that travel back into the write unchanged.
+*/ const ROW_KEYS = /* @__PURE__ */ new Set([
+	"blockName",
+	"blockType",
+	"id"
+]);
+/**
+* Picks the keys the schema walker describes out of `value`, descending into
+* groups, named tabs, arrays and blocks. Everything Payload maintains or
+* derives (`_status`, timestamps, join and virtual fields, upload base fields)
+* is left out, so the write-back carries only what a client could have set.
+*/ const pickDescribed = (config, value, at) => {
+	const { fields, prefix, isRow } = at;
+	const relative = describeFields(fields).flatMap((descriptor) => {
+		const parts = splitPath(descriptor.path);
+		return prefix.every((part, offset) => part === parts[offset]) ? [{
+			descriptor,
+			parts: parts.slice(prefix.length)
+		}] : [];
+	});
+	const result = {};
+	if (isRow) {
+		for (const key of ROW_KEYS) if (key in value) result[key] = value[key];
+	}
+	for (const [key, entry] of Object.entries(value)) {
+		const candidates = relative.filter(({ parts }) => parts[0] === key);
+		if (candidates.length === 0) continue;
+		const exact = candidates.find(({ parts }) => parts.length === 1);
+		if (exact?.descriptor.type === "blocks" && Array.isArray(entry)) {
+			const field = findBlocksField(fields, splitPath(exact.descriptor.path));
+			result[key] = entry.map((row) => {
+				const block = field && isPlainObject(row) && typeof row["blockType"] === "string" ? blockOf(config, field, row["blockType"]) : void 0;
+				return block && isPlainObject(row) ? pickDescribed(config, row, {
+					fields: block.flattenedFields,
+					prefix: [],
+					isRow: true
+				}) : row;
+			});
+			continue;
+		}
+		if (exact) {
+			result[key] = entry;
+			continue;
+		}
+		if (candidates.some(({ parts }) => parts[1] === "[]")) {
+			result[key] = Array.isArray(entry) ? entry.map((row) => isPlainObject(row) ? pickDescribed(config, row, {
+				fields,
+				prefix: [
+					...prefix,
+					key,
+					"[]"
+				],
+				isRow: true
+			}) : row) : entry;
+			continue;
+		}
+		result[key] = isPlainObject(entry) ? pickDescribed(config, entry, {
+			fields,
+			prefix: [...prefix, key],
+			isRow: false
+		}) : entry;
+	}
+	return result;
+};
+/**
+* The data handed to `payload.update` after a patch: the patched document
+* reduced to the fields the client may write, plus row identity keys.
+*/ const buildWriteData = (config, collection, doc) => {
+	return pickDescribed(config, doc, {
+		fields: collection.flattenedFields,
+		prefix: [],
+		isRow: false
+	});
+};
+//#endregion
+export { PATCH_OPERATION_SCHEMA, applyPatchToCopy, buildWriteData, droppedPointer, findPatchProblems, isElementPointer, isReservedPointer, stripRowIds };

package/dist/write/publish-blockers.d.mts

@@ -0,0 +1,13 @@
+import { PayloadRequest } from "payload";
+//#region src/write/publish-blockers.d.ts
+/**
+ * One reason a human could not publish the draft as it stands.
+ */
+interface PublishBlocker {
+  /** Resolved field label path, e.g. "Layout > Block 2 (Hero) > Title". */
+  field?: string;
+  message: string;
+  path: string;
+}
+//#endregion
+export type { PublishBlocker };