@abinnovision/payloadcms-mcpx 1.1.0-beta.5 → 2.0.0-beta.10

package/dist/tools/find-versions.mjs

@@ -0,0 +1,74 @@
+import { defineMcpxTool } from "../define-tool.mjs";
+import { jsonResult } from "../result.mjs";
+import { draftVersionSlugs, entityShape, idShape, localeOf, localeShape, slugsFor, widen } from "./shared.mjs";
+import { resolveDocument } from "./document.mjs";
+import { queryVersions } from "./versions.mjs";
+import { APIError } from "payload";
+import { hasDraftsEnabled } from "payload/shared";
+import { z } from "zod";
+//#region src/tools/find-versions.ts
+const DESCRIPTION = `Lists the versions of one document or global, newest first, autosaves included. Returns per version "versionId", "createdAt", "updatedAt", "status", "latest", "autosave" and, where set, "publishedLocale", without the content. Read a version with getDocument "versionId", or compare it with "diffFrom".`;
+const statusShape = (scope) => {
+	const { collections, globals } = draftVersionSlugs(scope);
+	if (collections.length + globals.length === 0) return widen({});
+	return widen({ status: z.enum(["published", "draft"]).optional() });
+};
+/**
+* Bodies are left out so a long history stays small; `getDocument` reads one
+* when it is needed. The document's `read` access is checked first, then
+* Payload's `readVersions`. Only entities that keep Payload versions are
+* reachable.
+*/ const findVersions = defineMcpxTool({
+	name: "findVersions",
+	description: DESCRIPTION,
+	annotations: {
+		readOnlyHint: true,
+		openWorldHint: false
+	},
+	isEnabled: (scope) => {
+		const { collections, globals } = slugsFor(scope, "versions");
+		return collections.length + globals.length > 0;
+	},
+	inputSchema: (scope) => ({
+		...entityShape(scope, "versions"),
+		...idShape(scope, "versions"),
+		limit: z.number().int().min(1).max(scope.limits.maxLimit).optional().describe("Default 10."),
+		page: z.number().int().min(1).optional(),
+		...statusShape(scope),
+		...localeShape(scope, {
+			required: false,
+			description: "Locale whose \"status\" is reported. Defaults to the default locale."
+		})
+	}),
+	handler: async ({ args, scope }) => {
+		const target = resolveDocument(scope, args, "versions");
+		if (args.status !== void 0 && !hasDraftsEnabled(target.config)) throw new APIError(`"${target.slug}" has no drafts, so its versions carry no status.`, 400);
+		const result = await queryVersions(scope, {
+			target,
+			depth: 0,
+			locale: localeOf(scope, args.locale)
+		}, {
+			limit: args.limit ?? 10,
+			...args.page === void 0 ? {} : { page: args.page },
+			...args.status === void 0 ? {} : { status: args.status }
+		});
+		const versions = result.docs.map((doc) => ({
+			versionId: doc.id,
+			createdAt: doc["createdAt"],
+			updatedAt: doc["updatedAt"],
+			status: doc.version["_status"] ?? null,
+			latest: doc["latest"] === true,
+			autosave: doc["autosave"] === true,
+			...doc["publishedLocale"] ? { publishedLocale: doc["publishedLocale"] } : {}
+		}));
+		return jsonResult({
+			versions,
+			totalDocs: result.totalDocs,
+			page: result.page,
+			totalPages: result.totalPages,
+			hasNextPage: result.hasNextPage
+		});
+	}
+});
+//#endregion
+export { findVersions };

package/dist/tools/get-document.mjs

@@ -1,80 +1,110 @@
+import { defineMcpxTool } from "../define-tool.mjs";
 import { errorResult, jsonResult } from "../result.mjs";
-import { JSON_POINTER_PATTERN, findRichTextField, splitPath } from "../schema/walk.mjs";
+import { JSON_POINTER_PATTERN, prototypeSegmentProblem, splitPath } from "../schema/path.mjs";
+import { findRichTextField } from "../schema/walk.mjs";
+import { SchemaError } from "../schema/errors.mjs";
 import { lexicalOutline } from "../schema/outline.mjs";
 import { resolveDataPointer } from "../schema/pointer.mjs";
 import "../schema/index.mjs";
-import { depthShape, idShape, localeOf, localeShape, targetShape } from "./shared.mjs";
-import { refOf, requireIdFor, resolveTarget } from "./target.mjs";
-import { defineMcpxTool } from "../types.mjs";
+import { READ_LOCALE_DESCRIPTION, depthShape, entityShape, idSchema, idShape, localeOf, localeShape, slugsFor, widen } from "./shared.mjs";
+import { identityOf, resolveDocument } from "./document.mjs";
+import { diffDocuments, loadPublished, loadVersion, readLive } from "./versions.mjs";
+import { APIError } from "payload";
 import { z } from "zod";
 import { Pointer } from "rfc6902";
 //#region src/tools/get-document.ts
 const OUTLINE_ERROR = "\"outline\" applies to a rich text field; give \"path\" for one.";
+const VERSION_PARAGRAPH = `
+
+"versionId" and "diffFrom" work where findVersions does. To revert, call getDocument with the old version as "versionId", the version findVersions marks "latest" as "diffFrom" and the locale you will write, then apply the returned "patch" with patchDocument.`;
+const DESCRIPTION = `Reads one document or global, or with "path" only the value at that pointer. Returns the latest draft by default, with the "updatedAt" a write takes as "expectedUpdatedAt".`;
+const exposesVersions = (scope) => {
+	const { collections, globals } = slugsFor(scope, "versions");
+	return collections.length + globals.length > 0;
+};
+const assertVersionArgs = (scope, target, args) => {
+	if (args.versionId === void 0 && args.diffFrom === void 0) return;
+	const { collections, globals } = slugsFor(scope, "versions");
+	if (!(target.kind === "collection" ? collections : globals).includes(target.slug)) throw new APIError(`"${target.slug}" does not expose version history.`, 400);
+	if (args.versionId !== void 0 && args.draft !== void 0) throw new APIError("Pass either \"versionId\" or \"draft\", not both.", 400);
+	if (args.diffFrom !== void 0 && args.outline) throw new APIError("\"outline\" cannot be combined with \"diffFrom\".", 400);
+};
+const diffResult = async (scope, read, diff, doc) => {
+	const from = diff.from === "published" ? await loadPublished(scope, read) : await loadVersion(scope, read, diff.from);
+	if (!from) return errorResult(diff.from === "published" ? `"${read.target.slug}" has no published version to diff from.` : `Version "${String(diff.from)}" not found.`);
+	return jsonResult({
+		from: from.id,
+		to: diff.to ?? "current",
+		...diff.pointer === void 0 ? {} : { path: diff.pointer.toString() },
+		patch: diffDocuments(from.version, doc, diff.pointer)
+	});
+};
+const versionShape = (scope) => {
+	if (!exposesVersions(scope)) return widen({});
+	return widen({
+		versionId: idSchema.optional().describe("From findVersions. Not with \"draft\"."),
+		diffFrom: idSchema.optional().describe("Version id, or \"published\" for the newest version published in any locale. Returns {from, to, patch}, the JSON Patch from that version to what is read.")
+	});
+};
 /**
 * With `path` the handler returns the subtree plus the `id`, `_status` and
-* `updatedAt` a client needs to write back, so a caller reading one branch
-* still gets the timestamp `expectedUpdatedAt` wants without a second call.
+* `updatedAt` a client needs to write back, so reading one branch still gives
+* the `expectedUpdatedAt` timestamp without a second call.
 */ const getDocument = defineMcpxTool({
 	name: "getDocument",
-	description: `Reads one document, or one subtree of it when "path" is given as a JSON pointer such as "/layout/sections/2". Returns the latest draft by default. Read before patching: the response carries "updatedAt" for expectedUpdatedAt and the indices pointers need.
-
-Pass exactly one of "collection" and "global". "id" is required with "collection" and must be omitted with "global", because a global is a singleton.
-
-Set "outline" on a rich text "path" to get a compact positional listing of its nodes instead of the raw editor state.`,
+	description: (scope) => exposesVersions(scope) ? DESCRIPTION + VERSION_PARAGRAPH : DESCRIPTION,
 	annotations: {
 		readOnlyHint: true,
 		openWorldHint: false
 	},
-	isEnabled: (scope) => scope.readable.length + scope.readableGlobals.length > 0,
+	isEnabled: (scope) => scope.collections.readable.length + scope.globals.readable.length > 0,
 	inputSchema: (scope) => ({
-		...targetShape(scope, "read", {
-			collection: "Collection holding the document.",
-			global: "Global to read."
-		}),
+		...entityShape(scope, "read"),
 		...idShape(scope, "read"),
-		path: z.string().regex(JSON_POINTER_PATTERN).optional().describe("JSON pointer to return only a subtree, e.g. \"/layout/sections/0\"."),
+		path: z.string().regex(JSON_POINTER_PATTERN).optional().describe("e.g. \"/layout/sections/0\"."),
 		...depthShape(scope),
 		...localeShape(scope, {
 			required: false,
-			description: "Locale to read. Defaults to the default locale."
+			description: READ_LOCALE_DESCRIPTION
 		}),
-		draft: z.boolean().optional().describe("Return the latest draft. Default true."),
-		outline: z.boolean().optional().describe("For a rich text field, return a compact positional outline instead of the editor state. Requires \"path\".")
+		draft: z.boolean().optional().describe("Default true. false reads the published version."),
+		outline: z.boolean().optional().describe("With \"path\" at a rich text field: list each node's pointer, type, \"version\" and text."),
+		...versionShape(scope)
 	}),
 	handler: async ({ args, scope }) => {
-		const target = resolveTarget(scope, args, "read");
-		const id = requireIdFor(target, args.id);
-		const locale = localeOf(scope, args.locale);
-		const shared = {
+		const target = resolveDocument(scope, args, "read");
+		assertVersionArgs(scope, target, args);
+		const prototyped = args.path ? prototypeSegmentProblem(args.path) : void 0;
+		if (prototyped !== void 0) return errorResult(prototyped);
+		let pointer;
+		try {
+			pointer = args.path ? Pointer.fromJSON(args.path) : void 0;
+		} catch {
+			return errorResult(`"${String(args.path)}" is not a valid JSON pointer.`);
+		}
+		const read = {
+			target,
 			depth: args.depth ?? 0,
-			draft: args.draft ?? true,
-			overrideAccess: false,
-			req: scope.req,
-			...locale === void 0 ? {} : { locale }
+			locale: localeOf(scope, args.locale)
 		};
-		const doc = await (target.kind === "collection" ? scope.req.payload.findByID({
-			...shared,
-			collection: target.slug,
-			id
-		}) : scope.req.payload.findGlobal({
-			...shared,
-			slug: target.slug
-		}));
-		if (args.path === void 0 || args.path === "") {
+		const doc = args.versionId === void 0 ? await readLive(scope, read, { draft: args.draft ?? true }) : (await loadVersion(scope, read, args.versionId))?.version;
+		if (!doc) return errorResult(`Version "${String(args.versionId)}" not found.`);
+		if (args.diffFrom !== void 0) return await diffResult(scope, read, {
+			from: args.diffFrom,
+			to: args.versionId,
+			pointer
+		}, doc);
+		if (pointer === void 0) {
 			if (args.outline) return errorResult(OUTLINE_ERROR);
 			return jsonResult(doc);
 		}
-		let value;
-		try {
-			value = Pointer.fromJSON(args.path).get(doc);
-		} catch {
-			return errorResult(`"${args.path}" is not a valid JSON pointer.`);
-		}
+		const path = pointer.toString();
+		const value = pointer.get(doc);
 		const envelope = {
-			...target.kind === "collection" ? { id: doc["id"] } : { global: target.slug },
+			...identityOf(target, args.id),
 			status: doc["_status"],
 			updatedAt: doc["updatedAt"],
-			path: args.path
+			path
 		};
 		if (!args.outline) return jsonResult({
 			...envelope,
@@ -84,17 +114,18 @@ Set "outline" on a rich text "path" to get a compact positional listing of its n
 		try {
 			resolution = resolveDataPointer(scope.req.payload.config, {
 				doc,
-				pointer: args.path,
-				ref: refOf(target)
+				pointer: path,
+				ref: target
 			});
 		} catch (error) {
-			return errorResult(error instanceof Error ? error.message : OUTLINE_ERROR);
+			if (!(error instanceof SchemaError)) throw error;
+			return errorResult(error.message);
 		}
 		const field = resolution.descriptor?.type === "richText" && !resolution.lexical ? findRichTextField(resolution.fields, splitPath(resolution.descriptor.path)) : void 0;
 		if (!field) return errorResult(OUTLINE_ERROR);
 		return jsonResult({
 			...envelope,
-			outline: lexicalOutline(value, args.path, field)
+			outline: lexicalOutline(value, path, field)
 		});
 	}
 });

package/dist/tools/list-capabilities.mjs

@@ -1,20 +1,27 @@
+import { defineMcpxTool } from "../define-tool.mjs";
 import { canCreate } from "../capabilities.mjs";
 import { jsonResult } from "../result.mjs";
-import { translatorFor } from "../i18n.mjs";
-import { translateLabel } from "./shared.mjs";
-import { defineMcpxTool } from "../types.mjs";
+import { translateStatic, translatorFor } from "../i18n.mjs";
 import { hasDraftValidationEnabled } from "payload/shared";
+//#region src/tools/list-capabilities.ts
+const DESCRIPTION = `Lists what this key may do. Call it first. Returns each collection and global the key can read or write, with whether it can create, publish, has drafts and exposes versions to findVersions, and a collection's "idType". Also returns the locales, the "limits" on page size and depth, and the enabled custom tools.`;
+const translateLabel = (scope, label, fallback) => {
+	const { i18n, t } = scope.req;
+	const resolved = typeof label === "function" ? label({
+		i18n,
+		t
+	}) : label;
+	return translateStatic(resolved, i18n) ?? fallback;
+};
 /**
-* Registered for every key, including one with no capabilities ticked, so a
-* client always has something to call and gets an empty surface described
-* rather than an empty tool list. The response is assembled from the request
-* scope and the sanitized config, never from the content model, so it stays the
-* same size as a deployment grows.
+* Registered for every key, even one with no capabilities ticked, so a client
+* always has a tool to call and gets an empty surface described instead of an
+* empty tool list. The response comes from the request scope and the sanitized
+* config, not the content model, so it stays the same size as a deployment
+* grows.
 */ const listCapabilities = defineMcpxTool({
 	name: "listCapabilities",
-	description: `Lists what this key may do: the collections and globals it can read or write, whether a collection can also be created in, their draft behaviour and id type, the configured locales, the limits in force and the custom tools available. Call it first to orient; nothing here changes with the content model.
-
-A global is a singleton: it has no id, is not listed by findDocuments and cannot be created. Address one with the "global" argument where a collection document would take "collection" and "id".`,
+	description: DESCRIPTION,
 	annotations: {
 		readOnlyHint: true,
 		openWorldHint: false
@@ -42,6 +49,7 @@ A global is a singleton: it has no id, is not listed by findDocuments and cannot
 				create: capability.write && canCreate(entry),
 				publish: capability.publish,
 				drafts: entry.hasDrafts,
+				versions: entry.hasVersions,
 				draftValidation: hasDraftValidationEnabled(config),
 				idType: collection.customIDType ?? payload.db.defaultIDType
 			}];
@@ -59,19 +67,20 @@ A global is a singleton: it has no id, is not listed by findDocuments and cannot
 				write: capability.write,
 				publish: capability.publish,
 				drafts: entry.hasDrafts,
+				versions: entry.hasVersions,
 				draftValidation: hasDraftValidationEnabled(config)
 			}];
 		});
-		return Promise.resolve(jsonResult({
+		return jsonResult({
 			collections,
 			...globals.length > 0 ? { globals } : {},
-			locales: scope.locales ? {
-				codes: scope.locales,
-				default: scope.defaultLocale
+			locales: scope.localization ? {
+				codes: scope.localization.locales,
+				default: scope.localization.defaultLocale
 			} : null,
 			limits: scope.limits,
 			tools: Object.entries(scope.capabilities.tools).filter(([, enabled]) => enabled).map(([name]) => name)
-		}));
+		});
 	}
 });
 //#endregion

package/dist/tools/patch-document.mjs

@@ -1,45 +1,69 @@
+import { defineMcpxTool } from "../define-tool.mjs";
+import { isPlainObject } from "../guards.mjs";
 import { errorResult, jsonResult } from "../result.mjs";
-import { draftSentence, idShape, localeOf, localeShape, readTarget, sameInstant, targetShape } from "./shared.mjs";
-import { refOf, requireIdFor, resolveTarget } from "./target.mjs";
-import { defineMcpxTool } from "../types.mjs";
-import { PATCH_OPERATION_SCHEMA, applyPatchOperations, buildWriteData, isElementPointer } from "../write/patch.mjs";
+import { JSON_POINTER_PATTERN } from "../schema/path.mjs";
+import "../schema/index.mjs";
+import { entityShape, idShape, liveWriteSentence, localeOf, localeShape } from "./shared.mjs";
 import { collectPublishBlockers } from "../write/publish-blockers.mjs";
+import { identityOf, readDraft, resolveDocument, staleReadResult } from "./document.mjs";
+import { applyPatchOperations, isElementPointer } from "../write/patch.mjs";
 import { withTransaction } from "../write/transaction.mjs";
+import { buildWriteData } from "../write/write-data.mjs";
+import { Forbidden, NotFound } from "payload";
 import { z } from "zod";
 import { Pointer } from "rfc6902";
 //#region src/tools/patch-document.ts
-const DESCRIPTION = (scope) => `Applies RFC 6902 JSON Patch operations to one document.
+const DESCRIPTION = (scope) => `Applies JSON Patch operations to one document or global, e.g. {"op":"replace","path":"/title","value":"Home"}. If any operation fails, nothing is written and the response lists the problems.
 
-Pass exactly one of "collection" and "global". "id" is required with "collection" and must be omitted with "global", because a global is a singleton.
+${liveWriteSentence(scope, "write")}
 
-${draftSentence(scope)}
+Read the document with getDocument right before patching. Append to a list with "/-". A new block needs "blockType". To clear a field, "replace" it with null, or with [] for an array or blocks field. "remove" only removes list elements. Indices shift with every add or remove, so remove from the last index to the first.
 
-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. describeSchema reports field paths in this same pointer syntax; a path becomes a pointer into a document by replacing each "*" and each block slug with its 0-based index. Inside a rich text field that substitution does not apply: a path there names the node type, and a block node its slug, where a pointer enters the stored state at "root" and walks "children" by an index counted over every child at that level, not over the blocks among them, with the node's own fields under "fields". So "/content/block/practice-note/variant" is written at "/content/root/children/7/fields/variant".
+In a rich text field a pointer continues into the rich text state: "/content/root/children/2" is a node, "/content/root/children/2/tag" one of its properties and "/content/root/children/3/fields/tone" a field of a block node. getDocument "outline" lists each node's pointer and "version". Build nodes from describeSchema "nodeProperties". Check a position before writing to it, e.g. {"op":"test","path":"/content/root/children/2/type","value":"heading"}.
 
-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 an edit made since that read is refused rather than overwritten.
-
-Inside a rich text field a pointer keeps going: "/content/root/children/2" is a node, "/content/root/children/2/tag" one of its properties, and "/content/root/children/2/fields/url" a field it carries. A node written at a position must carry everything Lexical serializes, "version" included, exactly as one written inside a whole state must; getDocument with "outline" returns each node's pointer and version, which is the cheapest way to get both right. A node's "type" cannot be replaced on its own, and neither can the root.
-
-Node positions shift as soon as anything is added or removed, so read immediately before patching, order removals from the last index to the first, and use a "test" operation on "/content/root/children/2/type" to assert a position is what you think it is before writing to it.
-
-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 the document cannot be published until the list is empty. "notApplied" lists pointers whose value Payload kept unchanged, which happens when field-level access denies the update. "publishBlockersUnavailable" means the check itself failed, so the empty list says nothing about whether the document is publishable.`;
-const isPlainObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+The response carries "updatedAt" and, if any, "publishBlockers": what must be fixed before publishing. "publishBlockersUnavailable" means that check failed. The write stands either way. "notApplied" lists pointers whose value did not change or cannot be read back, for example where field access denies the update.`;
+const POINTER = z.string().regex(JSON_POINTER_PATTERN);
+const PATCHES_LIMIT = 500;
 /**
-* 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) => {
+* Discriminated on `op`, so an operation carries only its own members.
+*/ const PATCH_OPERATION_SCHEMA = z.discriminatedUnion("op", [
+	z.strictObject({
+		op: z.literal("add"),
+		path: POINTER,
+		value: z.unknown()
+	}),
+	z.strictObject({
+		op: z.literal("remove"),
+		path: POINTER
+	}),
+	z.strictObject({
+		op: z.literal("replace"),
+		path: POINTER,
+		value: z.unknown()
+	}),
+	z.strictObject({
+		from: POINTER,
+		op: z.literal("move"),
+		path: POINTER
+	}),
+	z.strictObject({
+		from: POINTER,
+		op: z.literal("copy"),
+		path: POINTER
+	}),
+	z.strictObject({
+		op: z.literal("test"),
+		path: POINTER,
+		value: z.unknown()
+	})
+]);
+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) => {
+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);
@@ -48,10 +72,10 @@ const isPlainObject = (value) => typeof value === "object" && value !== null &&
 });
 /**
 * The handler validates the whole batch against the schema and the current
-* document before it writes anything, runs the write in a transaction, then
+* document before writing anything, runs the write in a transaction, then
 * re-reads the saved document to report which pointers survived and what still
-* blocks publishing. Nothing here decides where the write lands: the draft
-* guard does that on the Payload operation.
+* blocks publishing. The draft guard, not this tool, decides where the write
+* lands.
 */ const patchDocument = defineMcpxTool({
 	name: "patchDocument",
 	description: DESCRIPTION,
@@ -61,37 +85,33 @@ const isPlainObject = (value) => typeof value === "object" && value !== null &&
 		idempotentHint: false,
 		openWorldHint: false
 	},
-	isEnabled: (scope) => scope.writable.length + scope.writableGlobals.length > 0,
+	isEnabled: (scope) => scope.collections.writable.length + scope.globals.writable.length > 0,
 	inputSchema: (scope) => ({
-		...targetShape(scope, "write", {
-			collection: "Collection holding the document.",
-			global: "Global to patch."
-		}),
+		...entityShape(scope, "write"),
 		...idShape(scope, "write"),
 		...localeShape(scope, {
 			required: true,
-			description: "Locale the patch applies to. Localized fields write here only."
+			description: "Localized fields are written in this locale only."
 		}),
-		patches: z.array(PATCH_OPERATION_SCHEMA).min(1).describe("Operations, applied in order."),
-		expectedUpdatedAt: z.string().optional().describe("The updatedAt read before patching. Best effort: the write is refused if the document changed before the check, but not if it changes between the check and the write.")
+		patches: z.array(PATCH_OPERATION_SCHEMA).min(1).max(PATCHES_LIMIT),
+		expectedUpdatedAt: z.string().optional().describe("\"updatedAt\" from your last read. Refused if the document changed since.")
 	}),
 	handler: async ({ args, scope }) => {
-		const target = resolveTarget(scope, args, "write");
-		const id = requireIdFor(target, args.id);
+		const target = resolveDocument(scope, args, "write");
 		const { payload } = scope.req;
 		const locale = localeOf(scope, args.locale);
 		const patches = args.patches;
 		return await withTransaction(scope.req, async () => {
-			const doc = await readTarget(scope, {
+			const doc = await readDraft(scope, {
 				target,
-				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 stale = staleReadResult(doc, args.expectedUpdatedAt, "The document changed since you read it. Read it again and re-apply the patch.");
+			if (stale) return stale;
 			const applied = applyPatchOperations(payload.config, {
 				doc,
 				patches,
-				ref: refOf(target)
+				ref: target
 			});
 			if ("problems" in applied) return errorResult("No operation was applied.", { problems: applied.problems });
 			const write = {
@@ -105,26 +125,32 @@ const isPlainObject = (value) => typeof value === "object" && value !== null &&
 			if (target.kind === "collection") await payload.update({
 				...write,
 				collection: target.slug,
-				id
+				id: target.id
 			});
 			else await payload.updateGlobal({
 				...write,
 				fallbackLocale: false,
 				slug: target.slug
 			});
-			const saved = await readTarget(scope, {
+			const saved = await readDraft(scope, {
 				target,
-				id,
 				locale,
 				privileged: true
 			});
-			const notApplied = notAppliedPointers(patches, applied.next, saved);
+			const readable = await readDraft(scope, {
+				target,
+				locale
+			}).catch((error) => {
+				if (error instanceof NotFound || error instanceof Forbidden) return;
+				throw error;
+			});
+			const notApplied = readable ? notAppliedPointers(patches, applied.next, readable) : [];
 			const validation = await collectPublishBlockers(scope.req, {
 				doc: saved,
 				entity: target
 			});
 			return jsonResult({
-				...target.kind === "collection" ? { id: saved["id"] } : { global: target.slug },
+				...identityOf(target, saved["id"]),
 				status: saved["_status"],
 				updatedAt: saved["updatedAt"],
 				...validation.blockers.length > 0 ? { publishBlockers: validation.blockers } : {},
@@ -135,4 +161,4 @@ const isPlainObject = (value) => typeof value === "object" && value !== null &&
 	}
 });
 //#endregion
-export { patchDocument };
+export { PATCH_OPERATION_SCHEMA, patchDocument };

package/dist/tools/publish-document.mjs

@@ -1,48 +1,39 @@
-import { errorResult, jsonResult } from "../result.mjs";
-import { idShape, localeOf, readTarget, sameInstant, targetShape } from "./shared.mjs";
-import { requireIdFor, resolveTarget } from "./target.mjs";
-import { defineMcpxTool } from "../types.mjs";
+import { defineMcpxTool } from "../define-tool.mjs";
+import { jsonResult } from "../result.mjs";
+import { entityShape, idShape, localeOf, localeShape } from "./shared.mjs";
+import { collectLocaleBlockers, identityOf, readDraft, resolveDocument, staleReadResult } from "./document.mjs";
 import { withTransaction } from "../write/transaction.mjs";
 import { withPublishIntent } from "../write/publish-intent.mjs";
 import { z } from "zod";
 /**
-* The only tool that changes live content, available where the config sets
-* `write: "live"` on a versioned entity and the key has both the `write` and
-* `publish` checkboxes.
+* Publishes a draft. Available where the config exposes `publish` on an entity
+* with drafts and the key has both the `write` and `publish` checkboxes.
 */ const publishDocument = defineMcpxTool({
 	name: "publishDocument",
-	description: `Publishes the current draft, which changes what the public sees. This is the only tool that does; every other write lands as a draft. Call validateDocument first: a document that still has publish blockers is refused, and nothing is written.
-
-Pass exactly one of "collection" and "global". "id" is required with "collection" and must be omitted with "global", because a global is a singleton.
-
-The whole document is published, but Payload only validates the locale the publish runs in, so a required field left empty in another locale goes live empty. That is how the admin panel behaves too. Publishing is refused while a human holds the document open in the admin panel, and republishing an unchanged document is accepted but writes another version.
-
-There is no unpublish: reverting to a draft stays a human action in the admin panel.`,
+	description: `Makes the current draft of one document or global public, in every locale or only in "locale". A scoped publish keeps the other locales of localized fields as last published, and a never-published document goes live in full. A draft with publish blockers is refused, so call validateDocument first. Payload checks only the published locale, so "otherLocaleBlockers" lists what other locales still lack. There is no unpublish.`,
 	annotations: {
 		destructiveHint: true,
 		openWorldHint: false
 	},
-	isEnabled: (scope) => scope.publishable.length + scope.publishableGlobals.length > 0,
+	isEnabled: (scope) => scope.collections.publishable.length + scope.globals.publishable.length > 0,
 	inputSchema: (scope) => ({
-		...targetShape(scope, "publish", {
-			collection: "Collection holding the document.",
-			global: "Global to publish."
-		}),
+		...entityShape(scope, "publish"),
 		...idShape(scope, "publish"),
-		expectedUpdatedAt: z.string().optional().describe("The updatedAt read before publishing. Best effort: the publish is refused if the document has changed since, but a write landing between the check and the publish is not.")
+		...localeShape(scope, { required: false }),
+		expectedUpdatedAt: z.string().optional().describe("\"updatedAt\" from your last read. Refused if the document changed since.")
 	}),
 	handler: async ({ args, scope }) => {
-		const target = resolveTarget(scope, args, "publish");
-		const id = requireIdFor(target, args.id);
+		const target = resolveDocument(scope, args, "publish");
 		const { payload } = scope.req;
-		const locale = localeOf(scope, void 0);
+		const locale = localeOf(scope, args.locale);
+		const { localization } = scope;
 		return await withTransaction(scope.req, async () => {
-			const doc = await readTarget(scope, {
+			const doc = await readDraft(scope, {
 				target,
-				id,
 				locale
 			});
-			if (args.expectedUpdatedAt !== void 0 && !sameInstant(doc["updatedAt"], args.expectedUpdatedAt)) return errorResult("The document changed since you read it. Read it again before publishing.", { updatedAt: doc["updatedAt"] });
+			const stale = staleReadResult(doc, args.expectedUpdatedAt, "The document changed since you read it. Read it again before publishing.");
+			if (stale) return stale;
 			const write = {
 				data: withPublishIntent({}),
 				depth: 0,
@@ -50,27 +41,30 @@ There is no unpublish: reverting to a draft stays a human action in the admin pa
 				fallbackLocale: false,
 				overrideAccess: false,
 				req: scope.req,
-				...locale === void 0 ? {} : { locale }
+				...locale === void 0 ? {} : { locale },
+				...args.locale === void 0 ? {} : { publishSpecificLocale: args.locale }
 			};
 			if (target.kind === "collection") await payload.update({
 				...write,
 				collection: target.slug,
-				id
+				id: target.id
 			});
 			else await payload.updateGlobal({
 				...write,
 				slug: target.slug
 			});
-			const saved = await readTarget(scope, {
+			const saved = await readDraft(scope, {
 				target,
-				id,
 				locale,
 				privileged: true
 			});
+			const others = await collectLocaleBlockers(scope, target, localization?.locales.filter((entry) => entry !== locale) ?? []);
 			return jsonResult({
-				...target.kind === "collection" ? { id: saved["id"] } : { global: target.slug },
+				...identityOf(target, saved["id"]),
 				status: saved["_status"],
-				updatedAt: saved["updatedAt"]
+				updatedAt: saved["updatedAt"],
+				...others.blockers.length > 0 ? { otherLocaleBlockers: others.blockers } : {},
+				...others.unavailable ? { otherLocaleBlockersUnavailable: true } : {}
 			});
 		});
 	}