@abinnovision/payloadcms-mcpx 1.0.0-beta.9 → 1.0.0

package/dist/tools/find-documents.mjs

@@ -1,9 +1,16 @@
-import { jsonResult } from "../endpoint/result.mjs";
+import { jsonResult } from "../result.mjs";
 import { depthShape, localeOf, localeShape, slugEnum } from "./shared.mjs";
 import { resolveTarget } from "./target.mjs";
+import { defineMcpxTool } from "../types.mjs";
 import { z } from "zod";
-//#region src/tools/find-documents.ts
-const findDocuments = {
+/**
+* Collection-only: a global is a singleton, so there is nothing to list.
+*
+* The query goes to Payload with `overrideAccess: false`, so the collection's
+* own access control decides what comes back. `limit` and `depth` are bounded
+* by the configured limits in the schema itself, which puts the ceiling in
+* front of the client rather than silently clamping behind it.
+*/ const findDocuments = defineMcpxTool({
 	name: "findDocuments",
 	description: `Finds documents in a collection. "where" is a Payload query object, e.g. {"title":{"contains":"home"}} or {"and":[...]}; "select" picks fields, e.g. {"title":true}. Drafts are included by default so unpublished work is visible. Keep depth at 0 unless populated relationships are needed; ids are enough for writes.`,
 	annotations: {
@@ -15,7 +22,7 @@ const findDocuments = {
 		collection: slugEnum(scope.readable).describe("Collection to search."),
 		where: z.record(z.string(), z.unknown()).optional().describe("Payload where query."),
 		sort: z.string().optional().describe("Sort field, prefix with \"-\" for descending."),
-		limit: z.number().int().min(1).max(scope.options.limits.maxLimit).optional().describe(`Documents per page. Default 10, at most ${String(scope.options.limits.maxLimit)}.`),
+		limit: z.number().int().min(1).max(scope.limits.maxLimit).optional().describe(`Documents per page. Default 10, at most ${String(scope.limits.maxLimit)}.`),
 		page: z.number().int().min(1).optional().describe("Page number, from 1."),
 		...depthShape(scope),
 		select: z.record(z.string(), z.unknown()).optional().describe("Fields to return, e.g. {\"title\":true}."),
@@ -25,7 +32,7 @@ const findDocuments = {
 		}),
 		draft: z.boolean().optional().describe("Include the latest drafts. Default true.")
 	}),
-	handler: async (args, scope) => {
+	handler: async ({ args, scope }) => {
 		resolveTarget(scope, { collection: args.collection }, "read");
 		const locale = localeOf(scope, args.locale);
 		const result = await scope.req.payload.find({
@@ -50,6 +57,6 @@ const findDocuments = {
 			hasNextPage: result.hasNextPage
 		});
 	}
-};
+});
 //#endregion
 export { findDocuments };

package/dist/tools/get-document.mjs

@@ -1,15 +1,26 @@
-import { JSON_POINTER_PATTERN } from "../schema/walk.mjs";
-import { errorResult, jsonResult } from "../endpoint/result.mjs";
+import { errorResult, jsonResult } from "../result.mjs";
+import { JSON_POINTER_PATTERN, findRichTextField, splitPath } from "../schema/walk.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 { requireIdFor, resolveTarget } from "./target.mjs";
+import { refOf, requireIdFor, resolveTarget } from "./target.mjs";
+import { defineMcpxTool } from "../types.mjs";
 import { z } from "zod";
 import { Pointer } from "rfc6902";
 //#region src/tools/get-document.ts
-const getDocument = {
+const OUTLINE_ERROR = "\"outline\" applies to a rich text field; give \"path\" for one.";
+/**
+* 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.
+*/ 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.`,
+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.`,
 	annotations: {
 		readOnlyHint: true,
 		openWorldHint: false
@@ -27,9 +38,10 @@ Pass exactly one of "collection" and "global". "id" is required with "collection
 			required: false,
 			description: "Locale to read. Defaults to the default locale."
 		}),
-		draft: z.boolean().optional().describe("Return the latest draft. Default true.")
+		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\".")
 	}),
-	handler: async (args, scope) => {
+	handler: async ({ args, scope }) => {
 		const target = resolveTarget(scope, args, "read");
 		const id = requireIdFor(target, args.id);
 		const locale = localeOf(scope, args.locale);
@@ -48,21 +60,43 @@ Pass exactly one of "collection" and "global". "id" is required with "collection
 			...shared,
 			slug: target.slug
 		}));
-		if (args.path === void 0 || args.path === "") return jsonResult(doc);
+		if (args.path === void 0 || args.path === "") {
+			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.`);
 		}
-		return jsonResult({
+		const envelope = {
 			...target.kind === "collection" ? { id: doc["id"] } : { global: target.slug },
 			status: doc["_status"],
 			updatedAt: doc["updatedAt"],
-			path: args.path,
+			path: args.path
+		};
+		if (!args.outline) return jsonResult({
+			...envelope,
 			value
 		});
+		let resolution;
+		try {
+			resolution = resolveDataPointer(scope.req.payload.config, {
+				doc,
+				pointer: args.path,
+				ref: refOf(target)
+			});
+		} catch (error) {
+			return errorResult(error instanceof Error ? error.message : OUTLINE_ERROR);
+		}
+		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)
+		});
 	}
-};
+});
 //#endregion
 export { getDocument };

package/dist/tools/list-capabilities.mjs

@@ -1,11 +1,18 @@
+import { canCreate } from "../capabilities.mjs";
+import { jsonResult } from "../result.mjs";
 import { translatorFor } from "../i18n.mjs";
-import { jsonResult } from "../endpoint/result.mjs";
 import { translateLabel } from "./shared.mjs";
+import { defineMcpxTool } from "../types.mjs";
 import { hasDraftValidationEnabled } from "payload/shared";
-//#region src/tools/list-capabilities.ts
-const listCapabilities = {
+/**
+* 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.
+*/ const listCapabilities = defineMcpxTool({
 	name: "listCapabilities",
-	description: `Lists what this key may do: the collections and globals it can read or write, 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.
+	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".`,
 	annotations: {
@@ -14,10 +21,10 @@ A global is a singleton: it has no id, is not listed by findDocuments and cannot
 	},
 	isEnabled: () => true,
 	inputSchema: () => ({}),
-	handler: (_args, scope) => {
+	handler: ({ scope }) => {
 		const { payload } = scope.req;
 		const translate = translatorFor(scope.req.i18n);
-		const collections = scope.options.collections.flatMap((entry) => {
+		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 [];
@@ -32,12 +39,14 @@ A global is a singleton: it has no id, is not listed by findDocuments and cannot
 				...description === void 0 ? {} : { description },
 				read: capability.read,
 				write: capability.write,
+				create: capability.write && canCreate(entry),
+				publish: capability.publish,
 				drafts: entry.hasDrafts,
 				draftValidation: hasDraftValidationEnabled(config),
 				idType: collection.customIDType ?? payload.db.defaultIDType
 			}];
 		});
-		const globals = scope.options.globals.flatMap((entry) => {
+		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 [];
@@ -48,6 +57,7 @@ A global is a singleton: it has no id, is not listed by findDocuments and cannot
 				...description === void 0 ? {} : { description },
 				read: capability.read,
 				write: capability.write,
+				publish: capability.publish,
 				drafts: entry.hasDrafts,
 				draftValidation: hasDraftValidationEnabled(config)
 			}];
@@ -59,10 +69,10 @@ A global is a singleton: it has no id, is not listed by findDocuments and cannot
 				codes: scope.locales,
 				default: scope.defaultLocale
 			} : null,
-			limits: scope.options.limits,
+			limits: scope.limits,
 			tools: Object.entries(scope.capabilities.tools).filter(([, enabled]) => enabled).map(([name]) => name)
 		}));
 	}
-};
+});
 //#endregion
 export { listCapabilities };

package/dist/tools/names.mjs

@@ -8,7 +8,8 @@
 	"getDocument",
 	"patchDocument",
 	"createDocument",
-	"validateDocument"
+	"validateDocument",
+	"publishDocument"
 ];
 //#endregion
 export { BUILTIN_TOOL_NAMES };

package/dist/tools/patch-document.mjs

@@ -1,24 +1,28 @@
-import { errorResult, jsonResult } from "../endpoint/result.mjs";
-import { idShape, localeOf, localeShape, readTarget, targetShape } from "./shared.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 { PATCH_OPERATION_SCHEMA, applyPatchToCopy, buildWriteData, findPatchProblems, isElementPointer } from "../write/patch.mjs";
+import { defineMcpxTool } from "../types.mjs";
+import { PATCH_OPERATION_SCHEMA, applyPatchOperations, buildWriteData, 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.
+const DESCRIPTION = (scope) => `Applies RFC 6902 JSON Patch operations to one document.
 
 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 write always lands as a draft and is never published, whatever it contains; publishing stays a human action in the admin panel.
+${draftSentence(scope)}
 
-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.
+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".
 
-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.
+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.
 
-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();
+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);
 /**
 * Whether the intended value survived the write. The saved document is
@@ -42,12 +46,18 @@ const isPlainObject = (value) => typeof value === "object" && value !== null &&
 	const actual = pointer.get(saved);
 	return survives(expected, actual) ? [] : [operation.path];
 });
-const patchDocument = {
+/**
+* The handler validates the whole batch against the schema and the current
+* document before it writes 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.
+*/ const patchDocument = defineMcpxTool({
 	name: "patchDocument",
 	description: DESCRIPTION,
 	annotations: {
 		readOnlyHint: false,
-		destructiveHint: false,
+		destructiveHint: true,
 		idempotentHint: false,
 		openWorldHint: false
 	},
@@ -63,13 +73,14 @@ const patchDocument = {
 			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.")
+		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.")
 	}),
-	handler: async (args, scope) => {
+	handler: async ({ args, scope }) => {
 		const target = resolveTarget(scope, args, "write");
 		const id = requireIdFor(target, args.id);
 		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, {
 				target,
@@ -77,13 +88,11 @@ const patchDocument = {
 				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, {
+			const applied = applyPatchOperations(payload.config, {
 				doc,
-				patches: args.patches,
+				patches,
 				ref: refOf(target)
 			});
-			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 });
 			const write = {
 				data: buildWriteData(payload.config, target.config, applied.next),
@@ -100,6 +109,7 @@ const patchDocument = {
 			});
 			else await payload.updateGlobal({
 				...write,
+				fallbackLocale: false,
 				slug: target.slug
 			});
 			const saved = await readTarget(scope, {
@@ -108,8 +118,8 @@ const patchDocument = {
 				locale,
 				privileged: true
 			});
-			const notApplied = notAppliedPointers(args.patches, applied.next, saved);
-			const publishBlockers = await collectPublishBlockers(scope.req, {
+			const notApplied = notAppliedPointers(patches, applied.next, saved);
+			const validation = await collectPublishBlockers(scope.req, {
 				doc: saved,
 				entity: target
 			});
@@ -117,11 +127,12 @@ const patchDocument = {
 				...target.kind === "collection" ? { id: saved["id"] } : { global: target.slug },
 				status: saved["_status"],
 				updatedAt: saved["updatedAt"],
-				...publishBlockers.length > 0 ? { publishBlockers } : {},
+				...validation.blockers.length > 0 ? { publishBlockers: validation.blockers } : {},
+				...validation.unavailable ? { publishBlockersUnavailable: true } : {},
 				...notApplied.length > 0 ? { notApplied } : {}
 			});
 		});
 	}
-};
+});
 //#endregion
 export { patchDocument };

package/dist/tools/publish-document.mjs

@@ -0,0 +1,79 @@
+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 { 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.
+*/ 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.`,
+	annotations: {
+		destructiveHint: true,
+		openWorldHint: false
+	},
+	isEnabled: (scope) => scope.publishable.length + scope.publishableGlobals.length > 0,
+	inputSchema: (scope) => ({
+		...targetShape(scope, "publish", {
+			collection: "Collection holding the document.",
+			global: "Global to 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.")
+	}),
+	handler: async ({ args, scope }) => {
+		const target = resolveTarget(scope, args, "publish");
+		const id = requireIdFor(target, args.id);
+		const { payload } = scope.req;
+		const locale = localeOf(scope, void 0);
+		return await withTransaction(scope.req, async () => {
+			const doc = await readTarget(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 write = {
+				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
+			});
+			else await payload.updateGlobal({
+				...write,
+				slug: target.slug
+			});
+			const saved = await readTarget(scope, {
+				target,
+				id,
+				locale,
+				privileged: true
+			});
+			return jsonResult({
+				...target.kind === "collection" ? { id: saved["id"] } : { global: target.slug },
+				status: saved["_status"],
+				updatedAt: saved["updatedAt"]
+			});
+		});
+	}
+});
+//#endregion
+export { publishDocument };

package/dist/tools/shared.mjs

@@ -1,48 +1,102 @@
+import { canCreate, canPublish, isLiveWrite } from "../capabilities.mjs";
 import { translateStatic } from "../i18n.mjs";
 import { NotFound } from "payload";
 import { z } from "zod";
 //#region src/tools/shared.ts
-const slugEnum = (slugs) => z.enum(slugs);
-const idSchema = z.union([z.string(), z.number()]).describe("Document id.");
-const slugsFor = (scope, operation) => ({
-	collections: operation === "read" ? scope.readable : scope.writable,
-	globals: operation === "read" ? scope.readableGlobals : scope.writableGlobals
+/**
+* An out-of-scope slug fails schema validation before a handler runs, so a
+* client only ever sees what its key may touch.
+*/ const slugEnum = (slugs) => z.enum(slugs);
+/** Payload's id type follows the adapter, so both forms are handed on as read. */ const idSchema = z.union([z.string(), z.number()]).describe("Document id.");
+const slugsWhere = (scope, predicate, allowed) => {
+	const pick = (entities, slugs) => entities.filter((entity) => slugs.includes(entity.slug) && predicate(entity)).map((entity) => entity.slug);
+	return [...pick(scope.exposure.collections, allowed.collections), ...pick(scope.exposure.globals, allowed.globals)];
+};
+/**
+* Slugs this key may write whose writes land live rather than as a draft. An
+* entity without versions has no draft to land on, so `write: "live"` there
+* makes every write a live one. Empty for every key that can only write drafts.
+*/ const liveWriteSlugs = (scope) => slugsWhere(scope, isLiveWrite, {
+	collections: scope.writable,
+	globals: scope.writableGlobals
+});
+/**
+* Slugs this key may write but never create in, because their documents are
+* files. Collection-only, since nothing creates a global either way.
+*/ const patchOnlySlugs = (scope) => slugsWhere(scope, (entity) => !canCreate(entity), {
+	collections: scope.writable,
+	globals: []
+});
+/** Slugs this key may write and, separately, publish. */ const publishableWriteSlugs = (scope) => slugsWhere(scope, canPublish, {
+	collections: scope.publishable,
+	globals: scope.publishableGlobals
 });
 /**
-* The `collection` and `global` arguments.
-*
-* When the key can reach no global, `global` is left out of the shape entirely
-* and `collection` stays required, mirroring how {@link localeShape} omits
-* `locale` when localization is off. A deployment without globals therefore
-* sees exactly the schema it saw before. Only the mixed case makes either
-* argument optional, and the handler enforces the exclusivity there.
+* What a write actually does for this key, and what it takes to make it public.
+* A live-write slug has no draft and no publish step; a publishable one has
+* both. Stated per key so a client is never told its writes are drafts while
+* they are not, nor that publishing is out of reach when it is not.
+*/ const draftSentence = (scope) => {
+	const live = liveWriteSlugs(scope);
+	const publishable = publishableWriteSlugs(scope);
+	return `${live.length === 0 ? "Every write lands as a draft." : `Writes land as drafts, except for ${live.join(", ")}, which have no drafts: a write there changes the live document immediately.`} ${publishable.length === 0 ? "Nothing this key writes is ever published; publishing stays a human action in the admin panel." : `Publish a draft with publishDocument, which this key may do for ${publishable.join(", ")}. Publishing anything else stays a human action in the admin panel.`}`;
+};
+/** The value a client read back is a string; what it meets may be a Date. */ const sameInstant = (left, right) => typeof left === "string" && new Date(left).getTime() === new Date(right).getTime();
+/** Unchecked, because the runtime shape really does vary; `Branch` guards it. */ const widen = (branch) => branch;
+/** The one list the shape helpers and {@link resolveTarget} both read. */ const slugsFor = (scope, operation) => {
+	switch (operation) {
+		case "create": return {
+			collections: slugsWhere(scope, canCreate, {
+				collections: scope.writable,
+				globals: []
+			}),
+			globals: []
+		};
+		case "publish": return {
+			collections: scope.publishable,
+			globals: scope.publishableGlobals
+		};
+		case "read": return {
+			collections: scope.readable,
+			globals: scope.readableGlobals
+		};
+		case "write": return {
+			collections: scope.writable,
+			globals: scope.writableGlobals
+		};
+	}
+};
+/**
+* With no reachable global, `global` is left out and `collection` stays
+* required, so a deployment without globals sees an unchanged schema. Only the
+* mixed case makes either optional, and the handler enforces exclusivity there.
 */ const targetShape = (scope, operation, descriptions) => {
 	const { collections, globals } = slugsFor(scope, operation);
-	if (globals.length === 0) return { collection: slugEnum(collections).describe(descriptions.collection) };
-	if (collections.length === 0) return { global: slugEnum(globals).describe(descriptions.global) };
-	return {
+	if (globals.length === 0) return widen({ collection: slugEnum(collections).describe(descriptions.collection) });
+	if (collections.length === 0) return widen({ global: slugEnum(globals).describe(descriptions.global) });
+	return widen({
 		collection: slugEnum(collections).optional().describe(descriptions.collection),
 		global: slugEnum(globals).optional().describe(descriptions.global)
-	};
+	});
 };
 /**
-* The `id` argument, which only a collection document has. Omitted when the key
-* can reach no collection, required when it can reach no global, and optional
-* in between, where `requireIdFor` enforces the dependency.
+* Only a collection document has one. Optional in the mixed case, where
+* `requireIdFor` enforces the dependency.
 */ const idShape = (scope, operation) => {
 	const { collections, globals } = slugsFor(scope, operation);
-	if (collections.length === 0) return {};
-	if (globals.length === 0) return { id: idSchema };
-	return { id: idSchema.optional().describe("Document id. Required with \"collection\"; must be omitted with \"global\".") };
+	if (collections.length === 0) return widen({});
+	if (globals.length === 0) return widen({ id: idSchema });
+	return widen({ id: idSchema.optional().describe("Document id. Required with \"collection\"; must be omitted with \"global\".") });
 };
-/**
-* The `locale` argument, present only when localization is configured.
-*/ const localeShape = (scope, options) => {
-	if (!scope.locales) return {};
+const localeShape = (scope, options) => {
+	if (!scope.locales) return widen({});
 	const locale = z.enum(scope.locales);
-	return { locale: (options.required ? locale : locale.optional()).describe(options.description) };
+	return widen({ 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)}.`) });
+/**
+* Defaults to 0 rather than Payload's own default: a client usually wants ids
+* it can write back, and populating a relation costs a query.
+*/ const depthShape = (scope) => ({ depth: z.number().int().min(0).max(scope.limits.maxDepth).optional().describe(`Relationship population depth. Default 0, at most ${String(scope.limits.maxDepth)}.`) });
 /**
 * The locale to operate on: the explicit argument, else the request's, else
 * the default. `undefined` when localization is off.
@@ -83,9 +137,7 @@ const depthShape = (scope) => ({ depth: z.number().int().min(0).max(scope.option
 		slug: args.target.slug
 	});
 };
-/**
-* Resolves a collection label for the request's language.
-*/ const translateLabel = (scope, label, fallback) => {
+const translateLabel = (scope, label, fallback) => {
 	const { i18n, t } = scope.req;
 	const resolved = typeof label === "function" ? label({
 		i18n,
@@ -94,4 +146,4 @@ const depthShape = (scope) => ({ depth: z.number().int().min(0).max(scope.option
 	return translateStatic(resolved, i18n) ?? fallback;
 };
 //#endregion
-export { depthShape, idSchema, idShape, localeOf, localeShape, readTarget, slugEnum, targetShape, translateLabel };
+export { depthShape, draftSentence, idSchema, idShape, localeOf, localeShape, patchOnlySlugs, readTarget, sameInstant, slugEnum, slugsFor, targetShape, translateLabel };

package/dist/tools/target.mjs

@@ -1,3 +1,4 @@
+import { slugsFor } from "./shared.mjs";
 import { APIError, Forbidden } from "payload";
 //#region src/tools/target.ts
 const refOf = (target) => ({
@@ -5,21 +6,17 @@ const refOf = (target) => ({
 	slug: target.slug
 });
 /**
-* Resolves the `collection`/`global` arguments to one entity and checks the key
-* may perform `operation` on it.
-*
-* A tool's `inputSchema` returns a raw shape, which leaves no top-level
-* `.refine` to express "exactly one of collection and global". The rule is
-* enforced here instead, with a message naming the offending arguments so one
-* failed call teaches it.
+* A raw input shape leaves no top-level `.refine` to express "exactly one of
+* collection and global", so the rule is enforced here, with a message naming
+* the offending arguments.
 */ const resolveTarget = (scope, args, operation) => {
 	const { collection, global } = args;
+	const allowedSlugs = slugsFor(scope, operation);
 	if (collection !== void 0 && global !== void 0) throw new APIError("Pass either \"collection\" or \"global\", not both.", 400);
 	if (collection === void 0 && global === void 0) throw new APIError("One of \"collection\" or \"global\" is required. Call listCapabilities to see which slugs are available.", 400);
 	if (collection !== void 0) {
-		const allowed = operation === "read" ? scope.readable : scope.writable;
 		const found = scope.req.payload.collections[collection];
-		if (!allowed.includes(collection) || !found) throw new Forbidden(scope.req.t);
+		if (!allowedSlugs.collections.includes(collection) || !found) throw new Forbidden(scope.req.t);
 		return {
 			kind: "collection",
 			slug: collection,
@@ -27,9 +24,8 @@ const refOf = (target) => ({
 		};
 	}
 	const slug = global;
-	const allowed = operation === "read" ? scope.readableGlobals : scope.writableGlobals;
 	const found = scope.req.payload.globals.config.find((candidate) => candidate.slug === slug);
-	if (!allowed.includes(slug) || !found) throw new Forbidden(scope.req.t);
+	if (!allowedSlugs.globals.includes(slug) || !found) throw new Forbidden(scope.req.t);
 	return {
 		kind: "global",
 		slug,