@abinnovision/payloadcms-mcpx 2.0.0-beta.8 → 2.0.0

package/dist/tools/find-versions.mjs

@@ -1,15 +1,16 @@
 import { defineMcpxTool } from "../define-tool.mjs";
+import { definedProps } from "../guards.mjs";
 import { jsonResult } from "../result.mjs";
-import { draftVersionSlugs, entityShape, idShape, localeOf, localeShape, slugsFor, widen } from "./shared.mjs";
+import { entityShape, idShape, localeOf, localeShape, pageFields, pageShape, reaches, slugsFor, slugsWhere, widen } from "./shared.mjs";
 import { resolveDocument } from "./document.mjs";
 import { queryVersions } from "./versions.mjs";
+import { z } from "zod";
 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);
+	const { collections, globals } = slugsWhere(scope, (entity) => entity.hasDrafts, slugsFor(scope, "versions"));
 	if (collections.length + globals.length === 0) return widen({});
 	return widen({ status: z.enum(["published", "draft"]).optional() });
 };
@@ -25,15 +26,11 @@ const statusShape = (scope) => {
 		readOnlyHint: true,
 		openWorldHint: false
 	},
-	isEnabled: (scope) => {
-		const { collections, globals } = slugsFor(scope, "versions");
-		return collections.length + globals.length > 0;
-	},
+	isEnabled: (scope) => reaches(scope, "versions"),
 	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(),
+		...pageShape(scope),
 		...statusShape(scope),
 		...localeShape(scope, {
 			required: false,
@@ -49,8 +46,10 @@ const statusShape = (scope) => {
 			locale: localeOf(scope, args.locale)
 		}, {
 			limit: args.limit ?? 10,
-			...args.page === void 0 ? {} : { page: args.page },
-			...args.status === void 0 ? {} : { status: args.status }
+			...definedProps({
+				page: args.page,
+				status: args.status
+			})
 		});
 		const versions = result.docs.map((doc) => ({
 			versionId: doc.id,
@@ -63,10 +62,7 @@ const statusShape = (scope) => {
 		}));
 		return jsonResult({
 			versions,
-			totalDocs: result.totalDocs,
-			page: result.page,
-			totalPages: result.totalPages,
-			hasNextPage: result.hasNextPage
+			...pageFields(result)
 		});
 	}
 });

package/dist/tools/get-document.mjs

@@ -1,16 +1,17 @@
 import { defineMcpxTool } from "../define-tool.mjs";
 import { errorResult, jsonResult } from "../result.mjs";
-import { JSON_POINTER_PATTERN, prototypeSegmentProblem, splitPath } from "../schema/path.mjs";
-import { findRichTextField } from "../schema/walk.mjs";
 import { SchemaError } from "../schema/errors.mjs";
+import { JSON_POINTER_PATTERN, prototypeSegmentProblem, splitPath } from "../schema/path.mjs";
+import { findFieldAt } from "../schema/walk.mjs";
 import { lexicalOutline } from "../schema/outline.mjs";
 import { resolveDataPointer } from "../schema/pointer.mjs";
 import "../schema/index.mjs";
-import { READ_LOCALE_DESCRIPTION, depthShape, entityShape, idSchema, idShape, localeOf, localeShape, slugsFor, widen } from "./shared.mjs";
+import { downloadHandoff, downloadSlugs } from "../upload/file.mjs";
+import { READ_LOCALE_DESCRIPTION, depthShape, entityShape, idSchema, idShape, localeOf, localeShape, reaches, 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 { APIError } from "payload";
 import { Pointer } from "rfc6902";
 //#region src/tools/get-document.ts
 const OUTLINE_ERROR = "\"outline\" applies to a rich text field; give \"path\" for one.";
@@ -18,10 +19,6 @@ 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");
@@ -40,24 +37,36 @@ const diffResult = async (scope, read, diff, doc) => {
 	});
 };
 const versionShape = (scope) => {
-	if (!exposesVersions(scope)) return widen({});
+	if (!reaches(scope, "versions")) 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.")
 	});
 };
+const downloadShape = (scope) => {
+	const slugs = downloadSlugs(scope);
+	return widen(slugs.length === 0 ? {} : { download: z.literal(true).optional().describe(`Only for ${slugs.join(", ")}. Adds "download": GET its "url" with its "headers" once, within 5 minutes, for the file. Not with "path", "versionId" or "diffFrom".`) });
+};
+const assertDownloadArgs = (scope, target, args) => {
+	if (target.kind === "global" || !downloadSlugs(scope).includes(target.slug)) throw new APIError(`"${target.slug}" has no file to download.`, 400);
+	if (args.path !== void 0 || args.versionId !== void 0 || args.diffFrom !== void 0) throw new APIError("\"download\" cannot be combined with \"path\", \"versionId\" or \"diffFrom\".", 400);
+};
+const withDownload = async (scope, doc, target) => typeof doc["filename"] === "string" ? jsonResult({
+	...doc,
+	download: await downloadHandoff(scope, target)
+}) : errorResult("This document has no file to download.");
 /**
 * With `path` the handler returns the subtree plus the `id`, `_status` and
 * `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: (scope) => exposesVersions(scope) ? DESCRIPTION + VERSION_PARAGRAPH : DESCRIPTION,
+	description: (scope) => reaches(scope, "versions") ? DESCRIPTION + VERSION_PARAGRAPH : DESCRIPTION,
 	annotations: {
 		readOnlyHint: true,
 		openWorldHint: false
 	},
-	isEnabled: (scope) => scope.collections.readable.length + scope.globals.readable.length > 0,
+	isEnabled: (scope) => reaches(scope, "read"),
 	inputSchema: (scope) => ({
 		...entityShape(scope, "read"),
 		...idShape(scope, "read"),
@@ -69,11 +78,13 @@ const versionShape = (scope) => {
 		}),
 		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)
+		...versionShape(scope),
+		...downloadShape(scope)
 	}),
 	handler: async ({ args, scope }) => {
 		const target = resolveDocument(scope, args, "read");
 		assertVersionArgs(scope, target, args);
+		if (args.download) assertDownloadArgs(scope, target, args);
 		const prototyped = args.path ? prototypeSegmentProblem(args.path) : void 0;
 		if (prototyped !== void 0) return errorResult(prototyped);
 		let pointer;
@@ -96,12 +107,17 @@ const versionShape = (scope) => {
 		}, doc);
 		if (pointer === void 0) {
 			if (args.outline) return errorResult(OUTLINE_ERROR);
-			return jsonResult(doc);
+			return args.download && args.id !== void 0 ? await withDownload(scope, doc, {
+				collection: target.slug,
+				id: args.id,
+				draft: args.draft ?? true,
+				locale: read.locale ?? null
+			}) : jsonResult(doc);
 		}
 		const path = pointer.toString();
 		const value = pointer.get(doc);
 		const envelope = {
-			...identityOf(target, args.id),
+			...identityOf(target),
 			status: doc["_status"],
 			updatedAt: doc["updatedAt"],
 			path
@@ -121,7 +137,7 @@ const versionShape = (scope) => {
 			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;
+		const field = resolution.descriptor?.type === "richText" && !resolution.lexical ? findFieldAt(resolution.fields, splitPath(resolution.descriptor.path), "richText") : void 0;
 		if (!field) return errorResult(OUTLINE_ERROR);
 		return jsonResult({
 			...envelope,

package/dist/tools/links.mjs

@@ -0,0 +1,53 @@
+import { publicOrigin } from "../request.mjs";
+import { formatAdminURL } from "payload/shared";
+//#region src/tools/links.ts
+const livePreviewOf = (req, target) => {
+	if (target.config.admin.livePreview) return target.config.admin.livePreview;
+	const root = req.payload.config.admin.livePreview;
+	return (target.kind === "collection" ? root?.collections : root?.globals)?.includes(target.slug) ? root : void 0;
+};
+const previewOf = async (req, args) => {
+	const { target, doc, locale } = args;
+	const { preview } = target.config.admin;
+	if (preview) return await preview(doc, {
+		locale: locale ?? "",
+		req,
+		token: null
+	});
+	const url = livePreviewOf(req, target)?.url;
+	if (typeof url !== "function") return url;
+	const { localization } = req.payload.config;
+	const entry = localization ? localization.locales.find((item) => item.code === locale) : void 0;
+	return await url({
+		...target.kind === "collection" ? { collectionConfig: target.config } : { globalConfig: target.config },
+		data: doc,
+		locale: entry ?? {
+			code: locale ?? "",
+			label: locale ?? ""
+		},
+		payload: req.payload,
+		req
+	});
+};
+/**
+* The admin panel URL of a written document, and its preview URL where the
+* entity configures one. Both sit at the origin of `serverURL` when set, else
+* of the MCP request. A preview that fails is left out: the write has landed.
+*/ const documentLinks = async (req, args) => {
+	const { target, doc, locale } = args;
+	const { config } = req.payload;
+	const origin = publicOrigin(req);
+	const path = target.kind === "collection" ? `/collections/${target.slug}/${String(doc["id"])}` : `/globals/${target.slug}`;
+	const adminUrl = formatAdminURL({
+		adminRoute: config.routes.admin,
+		path,
+		serverURL: origin
+	});
+	const preview = await previewOf(req, args).catch(() => void 0);
+	return {
+		adminUrl: locale ? `${adminUrl}?locale=${encodeURIComponent(locale)}` : adminUrl,
+		...preview ? { previewUrl: new URL(preview, origin).toString() } : {}
+	};
+};
+//#endregion
+export { documentLinks };

package/dist/tools/list-capabilities.mjs

@@ -1,10 +1,13 @@
 import { defineMcpxTool } from "../define-tool.mjs";
-import { canCreate } from "../capabilities.mjs";
 import { jsonResult } from "../result.mjs";
 import { translateStatic, translatorFor } from "../i18n.mjs";
+import { slugsFor } from "./shared.mjs";
+import { globalConfig } from "./document.mjs";
+import { MCPX_ISSUES_URL, MCPX_REPOSITORY_URL } from "../version.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 DIAGNOSTICS = ` Its "server" block holds the server version with repository and issue links, for a bug report.`;
 const translateLabel = (scope, label, fallback) => {
 	const { i18n, t } = scope.req;
 	const resolved = typeof label === "function" ? label({
@@ -21,7 +24,7 @@ const translateLabel = (scope, label, fallback) => {
 * grows.
 */ const listCapabilities = defineMcpxTool({
 	name: "listCapabilities",
-	description: DESCRIPTION,
+	description: (scope) => scope.diagnostics ? `${DESCRIPTION}${DIAGNOSTICS}` : DESCRIPTION,
 	annotations: {
 		readOnlyHint: true,
 		openWorldHint: false
@@ -31,10 +34,11 @@ const translateLabel = (scope, label, fallback) => {
 	handler: ({ scope }) => {
 		const { payload } = scope.req;
 		const translate = translatorFor(scope.req.i18n);
+		const creatable = slugsFor(scope, "create").collections;
 		const collections = scope.exposure.collections.flatMap((entry) => {
 			const capability = scope.capabilities.collections[entry.slug];
 			const collection = payload.collections[entry.slug];
-			if (!capability || !collection || !(capability.read || capability.write)) return [];
+			if (!capability || !collection || !capability.read) return [];
 			const { config } = collection;
 			const description = translate(config.admin.description);
 			return [{
@@ -46,7 +50,7 @@ const translateLabel = (scope, label, fallback) => {
 				...description === void 0 ? {} : { description },
 				read: capability.read,
 				write: capability.write,
-				create: capability.write && canCreate(entry),
+				create: creatable.includes(entry.slug),
 				publish: capability.publish,
 				drafts: entry.hasDrafts,
 				versions: entry.hasVersions,
@@ -56,8 +60,8 @@ const translateLabel = (scope, label, fallback) => {
 		});
 		const globals = scope.exposure.globals.flatMap((entry) => {
 			const capability = scope.capabilities.globals[entry.slug];
-			const config = payload.globals.config.find((candidate) => candidate.slug === entry.slug);
-			if (!capability || !config || !(capability.read || capability.write)) return [];
+			const config = globalConfig(payload, entry.slug);
+			if (!capability || !config || !capability.read) return [];
 			const description = translate(config.admin.description);
 			return [{
 				slug: entry.slug,
@@ -79,7 +83,13 @@ const translateLabel = (scope, label, fallback) => {
 				default: scope.localization.defaultLocale
 			} : null,
 			limits: scope.limits,
-			tools: Object.entries(scope.capabilities.tools).filter(([, enabled]) => enabled).map(([name]) => name)
+			tools: Object.entries(scope.capabilities.tools).filter(([, enabled]) => enabled).map(([name]) => name),
+			...scope.diagnostics ? { server: {
+				name: scope.diagnostics.name,
+				version: scope.diagnostics.version,
+				repository: MCPX_REPOSITORY_URL,
+				issues: MCPX_ISSUES_URL
+			} } : {}
 		});
 	}
 });

package/dist/tools/patch-document.mjs

@@ -1,16 +1,16 @@
 import { defineMcpxTool } from "../define-tool.mjs";
 import { isPlainObject } from "../guards.mjs";
-import { errorResult, jsonResult } from "../result.mjs";
+import { errorResult } from "../result.mjs";
 import { JSON_POINTER_PATTERN } from "../schema/path.mjs";
 import "../schema/index.mjs";
-import { entityShape, idShape, liveWriteSentence, localeOf, localeShape } from "./shared.mjs";
-import { identityOf, readDraft, resolveDocument, staleReadResult } from "./document.mjs";
-import { collectPublishBlockers } from "../write/publish-blockers.mjs";
-import { applyPatchOperations, isElementPointer } from "../write/patch.mjs";
+import { assertAcceptsFile, fileShape, fileSlugs, fileWriteRefusal, uploadHandoff, uploadedFile } from "../upload/file.mjs";
+import { entityShape, expectedUpdatedAtShape, idShape, liveWriteSentence, localeOf, localeShape, reaches } from "./shared.mjs";
+import { readDraft, resolveDocument, staleReadResult, updateTarget, writtenResult } from "./document.mjs";
 import { withTransaction } from "../write/transaction.mjs";
+import { applyPatchOperations, isElementPointer } from "../write/patch.mjs";
 import { buildWriteData } from "../write/write-data.mjs";
-import { Forbidden, NotFound } from "payload";
 import { z } from "zod";
+import { APIError, Forbidden, NotFound } from "payload";
 import { Pointer } from "rfc6902";
 //#region src/tools/patch-document.ts
 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.
@@ -21,10 +21,12 @@ Read the document with getDocument right before patching. Append to a list with
 
 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"}.
 
-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.`;
+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. The response links the document with "adminUrl" and "previewUrl".`;
 const POINTER = z.string().regex(JSON_POINTER_PATTERN);
 const PATCHES_LIMIT = 500;
-/** Discriminated on `op`, so an operation carries only its own members. */ const PATCH_OPERATION_SCHEMA = z.discriminatedUnion("op", [
+/**
+* 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,
@@ -73,7 +75,8 @@ const notAppliedPointers = (patches, intended, saved) => patches.flatMap((operat
 * 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. The draft guard, not this tool, decides where the write
-* lands.
+* lands. With `file`, the patches and the file land as one update, and the
+* transaction commits right after it because Payload has moved files by then.
 */ const patchDocument = defineMcpxTool({
 	name: "patchDocument",
 	description: DESCRIPTION,
@@ -83,7 +86,7 @@ const notAppliedPointers = (patches, intended, saved) => patches.flatMap((operat
 		idempotentHint: false,
 		openWorldHint: false
 	},
-	isEnabled: (scope) => scope.collections.writable.length + scope.globals.writable.length > 0,
+	isEnabled: (scope) => reaches(scope, "write"),
 	inputSchema: (scope) => ({
 		...entityShape(scope, "write"),
 		...idShape(scope, "write"),
@@ -91,71 +94,74 @@ const notAppliedPointers = (patches, intended, saved) => patches.flatMap((operat
 			required: true,
 			description: "Localized fields are written in this locale only."
 		}),
-		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.")
+		patches: fileSlugs(scope).length === 0 ? z.array(PATCH_OPERATION_SCHEMA).min(1).max(PATCHES_LIMIT) : z.array(PATCH_OPERATION_SCHEMA).max(PATCHES_LIMIT).describe("May be empty when \"file\" is given."),
+		...expectedUpdatedAtShape,
+		...fileShape(scope, (slugs) => `Replaces the file of a document in ${slugs}. The call returns an "upload" for the bytes instead of writing.`)
 	}),
 	handler: async ({ args, scope }) => {
 		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 { file } = args;
+		const bytes = uploadedFile(scope.req);
+		if (file !== void 0) assertAcceptsFile(scope, target, file);
+		if (patches.length === 0 && file === void 0) throw new APIError("\"patches\" may be empty only when \"file\" is given.", 400);
+		const report = async (next) => {
+			const readable = await readDraft(scope, {
+				target,
+				locale
+			}).catch((error) => {
+				if (error instanceof NotFound || error instanceof Forbidden) return;
+				throw error;
+			});
+			const notApplied = readable ? notAppliedPointers(patches, next, readable) : [];
+			return await writtenResult(scope, {
+				target,
+				locale,
+				extra: notApplied.length > 0 ? { notApplied } : {}
+			});
+		};
+		const outcome = await withTransaction(scope.req, async () => {
 			const doc = await readDraft(scope, {
 				target,
 				locale
 			});
 			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;
+			if (stale) return { done: stale };
 			const applied = applyPatchOperations(payload.config, {
 				doc,
 				patches,
 				ref: target
 			});
-			if ("problems" in applied) return errorResult("No operation was applied.", { problems: applied.problems });
-			const write = {
+			if ("problems" in applied) return { done: errorResult("No operation was applied.", { problems: applied.problems }) };
+			if (file !== void 0 && target.kind === "collection") {
+				const refusal = await fileWriteRefusal(scope, {
+					entity: target,
+					id: target.id,
+					data: applied.next
+				});
+				if (refusal) return { done: refusal };
+				if (!bytes) return { handoff: {
+					...args,
+					file,
+					expectedUpdatedAt: doc["updatedAt"]
+				} };
+			}
+			await updateTarget(scope, target, {
 				data: buildWriteData(payload.config, target.config, applied.next),
-				depth: 0,
 				draft: true,
-				overrideAccess: false,
-				req: scope.req,
-				...locale === void 0 ? {} : { locale }
-			};
-			if (target.kind === "collection") await payload.update({
-				...write,
-				collection: target.slug,
-				id: target.id
-			});
-			else await payload.updateGlobal({
-				...write,
-				fallbackLocale: false,
-				slug: target.slug
-			});
-			const saved = await readDraft(scope, {
-				target,
 				locale,
-				privileged: true
-			});
-			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({
-				...identityOf(target, saved["id"]),
-				status: saved["_status"],
-				updatedAt: saved["updatedAt"],
-				...validation.blockers.length > 0 ? { publishBlockers: validation.blockers } : {},
-				...validation.unavailable ? { publishBlockersUnavailable: true } : {},
-				...notApplied.length > 0 ? { notApplied } : {}
+				file: bytes
 			});
+			return bytes === void 0 ? { done: await report(applied.next) } : { written: applied.next };
+		});
+		if ("done" in outcome) return outcome.done;
+		if ("handoff" in outcome) return await uploadHandoff(scope, {
+			tool: "patchDocument",
+			args: outcome.handoff
 		});
+		return await report(outcome.written);
 	}
 });
 //#endregion

package/dist/tools/publish-document.mjs

@@ -1,31 +1,31 @@
 import { defineMcpxTool } from "../define-tool.mjs";
 import { jsonResult } from "../result.mjs";
-import { entityShape, idShape, localeOf } from "./shared.mjs";
-import { identityOf, readDraft, resolveDocument, staleReadResult } from "./document.mjs";
-import { withTransaction } from "../write/transaction.mjs";
+import { documentLinks } from "./links.mjs";
+import { entityShape, expectedUpdatedAtShape, idShape, localeOf, localeShape, reaches } from "./shared.mjs";
+import { blockerFields, collectLocaleBlockers, documentSummary, readDraft, resolveDocument, staleReadResult, updateTarget } from "./document.mjs";
 import { withPublishIntent } from "../write/publish-intent.mjs";
-import { z } from "zod";
+import { withTransaction } from "../write/transaction.mjs";
 /**
-* Publishes a draft. Available where the config exposes
-* `publish` on an entity with drafts 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: `Makes the current draft of one document or global public. A draft with publish blockers is refused, so call validateDocument first. Publishing validates one locale only, normally the default, so a required field left empty in another locale goes live empty. Run validateDocument for each locale. There is no unpublish. A person takes content offline 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. The response links the document with "adminUrl" and "previewUrl".`,
 	annotations: {
 		destructiveHint: true,
 		openWorldHint: false
 	},
-	isEnabled: (scope) => scope.collections.publishable.length + scope.globals.publishable.length > 0,
+	isEnabled: (scope) => reaches(scope, "publish"),
 	inputSchema: (scope) => ({
 		...entityShape(scope, "publish"),
 		...idShape(scope, "publish"),
-		expectedUpdatedAt: z.string().optional().describe("\"updatedAt\" from your last read. Refused if the document changed since.")
+		...localeShape(scope, { required: false }),
+		...expectedUpdatedAtShape
 	}),
 	handler: async ({ args, scope }) => {
 		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 readDraft(scope, {
 				target,
@@ -33,33 +33,26 @@ import { z } from "zod";
 			});
 			const stale = staleReadResult(doc, args.expectedUpdatedAt, "The document changed since you read it. Read it again before publishing.");
 			if (stale) return stale;
-			const write = {
+			await updateTarget(scope, target, {
 				data: withPublishIntent({}),
-				depth: 0,
 				draft: false,
-				fallbackLocale: false,
-				overrideAccess: false,
-				req: scope.req,
-				...locale === void 0 ? {} : { locale }
-			};
-			if (target.kind === "collection") await payload.update({
-				...write,
-				collection: target.slug,
-				id: target.id
-			});
-			else await payload.updateGlobal({
-				...write,
-				slug: target.slug
+				locale,
+				publishSpecificLocale: args.locale
 			});
 			const saved = await readDraft(scope, {
 				target,
 				locale,
 				privileged: true
 			});
+			const others = await collectLocaleBlockers(scope, target, localization?.locales.filter((entry) => entry !== locale) ?? []);
 			return jsonResult({
-				...identityOf(target, saved["id"]),
-				status: saved["_status"],
-				updatedAt: saved["updatedAt"]
+				...documentSummary(target, saved),
+				...await documentLinks(scope.req, {
+					target,
+					doc: saved,
+					locale
+				}),
+				...blockerFields(others, "otherLocaleBlockers")
 			});
 		});
 	}

package/dist/tools/query-paths.mjs

@@ -8,7 +8,9 @@ import { APIError, getLocalizedPaths } from "payload";
 * them: `and` and `or` (any case) hold arrays of clauses, every other key is a
 * path.
 */ const wherePaths = (where) => isPlainObject(where) ? Object.entries(where).flatMap(([key, clause]) => ["and", "or"].includes(key.toLowerCase()) && Array.isArray(clause) ? clause.flatMap(wherePaths) : [key]) : [];
-/** The paths of a `sort`: a field name, `-` for descending, comma separated. */ const sortPaths = (sort) => (sort ?? "").split(",").map((entry) => entry.trim().replace(/^-/, "")).filter(Boolean);
+/**
+* The paths of a `sort`: a field name, `-` for descending, comma separated.
+*/ const sortPaths = (sort) => (sort ?? "").split(",").map((entry) => entry.trim().replace(/^-/, "")).filter(Boolean);
 const normalise = (path) => path === "_id" ? "id" : path.replaceAll("__", ".");
 const isRefusedPath = (scope, args, seen = /* @__PURE__ */ new Set()) => {
 	const key = `${args.collection}:${args.path}`;
@@ -46,7 +48,7 @@ const isRefusedPath = (scope, args, seen = /* @__PURE__ */ new Set()) => {
 	const reaches = (path) => isRefusedPath(scope, {
 		collection: args.collection,
 		path: normalise(path),
-		locale: args.locale ?? void 0
+		locale: args.locale
 	});
 	for (const path of wherePaths(args.where)) if (reaches(path)) throw new APIError(`This key cannot query through "${path}".`, 400);
 	for (const path of sortPaths(args.sort)) if (reaches(path) || normalise(path).split(".").some(reaches)) throw new APIError(`This key cannot query through "${path}".`, 400);