@abinnovision/payloadcms-mcpx 1.1.0-beta.6 → 2.0.0-beta.12

package/dist/tools/shared.mjs

@@ -1,159 +1,128 @@
-import { canCreate, canPublish, isLiveWrite } from "../capabilities.mjs";
-import { translateStatic } from "../i18n.mjs";
-import { NotFound } from "payload";
+import { canCreate, isLiveWrite } from "../capabilities.mjs";
+import { acceptsFiles } from "../upload/file.mjs";
 import { z } from "zod";
 //#region src/tools/shared.ts
 /**
 * 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.");
+/**
+* Payload's id type follows the adapter, so both forms are handed on as read.
+*/ const idSchema = z.union([z.string(), z.number()]);
+const slugsOf = (scope, key) => ({
+	collections: scope.collections[key],
+	globals: scope.globals[key]
+});
 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
-});
-/**
-* 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.`}`;
+* Collections this key may write but not create in: upload collections whose
+* files MCP does not accept. Nothing creates a global either way.
+*/ const patchOnlySlugs = (scope) => {
+	const creatable = slugsFor(scope, "create").collections;
+	return scope.collections.writable.filter((slug) => !creatable.includes(slug));
 };
-/** 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) => {
+const widen = (branch) => branch;
+/**
+* The one list the shape helpers and {@link resolveEntity} both read.
+*/ const slugsFor = (scope, operation) => {
 	switch (operation) {
 		case "create": return {
-			collections: slugsWhere(scope, canCreate, {
-				collections: scope.writable,
+			collections: slugsWhere(scope, (entity) => canCreate(entity) && (!entity.isUpload || acceptsFiles(scope, entity.slug)), {
+				collections: scope.collections.writable,
 				globals: []
 			}),
 			globals: []
 		};
-		case "publish": return {
-			collections: scope.publishable,
-			globals: scope.publishableGlobals
-		};
-		case "read": return {
-			collections: scope.readable,
-			globals: scope.readableGlobals
-		};
+		case "publish": return slugsOf(scope, "publishable");
+		case "read": return slugsOf(scope, "readable");
 		case "versions": return {
 			collections: slugsWhere(scope, (entity) => entity.hasVersions, {
-				collections: scope.readable,
+				collections: scope.collections.readable,
 				globals: []
 			}),
 			globals: slugsWhere(scope, (entity) => entity.hasVersions, {
 				collections: [],
-				globals: scope.readableGlobals
+				globals: scope.globals.readable
 			})
 		};
-		case "write": return {
-			collections: scope.writable,
-			globals: scope.writableGlobals
-		};
+		case "write": return slugsOf(scope, "writable");
 	}
 };
 /**
+* The slugs of {@link slugsFor} `"versions"` that also have drafts. Only they
+* have `_status` on their versions, so only they can be queried by status.
+*/ const draftVersionSlugs = (scope) => {
+	const { collections, globals } = slugsFor(scope, "versions");
+	return {
+		collections: slugsWhere(scope, (entity) => entity.hasDrafts, {
+			collections,
+			globals: []
+		}),
+		globals: slugsWhere(scope, (entity) => entity.hasDrafts, {
+			collections: [],
+			globals
+		})
+	};
+};
+/**
+* Slugs reachable by `operation` whose writes go live, because they have no
+* draft to write.
+*/ const liveWriteSlugs = (scope, operation) => slugsWhere(scope, isLiveWrite, slugsFor(scope, operation));
+/**
+* Stated on the tools that write, since a client calling them must know before
+* the call which writes are public.
+*/ const liveWriteSentence = (scope, operation) => {
+	const live = liveWriteSlugs(scope, operation);
+	return live.length === 0 ? "Every write is saved as a draft." : `Writes to ${live.join(", ")} go live immediately. Every other write is saved as a draft.`;
+};
+/**
 * With no reachable global, `global` is left out and `collection` stays
-* required, so a deployment without globals sees an unchanged schema. Only the
+* required, so a deployment without globals gets no extra argument. Only the
 * mixed case makes either optional, and the handler enforces exclusivity there.
-*/ const targetShape = (scope, operation, descriptions) => {
+* `globalRule` states that rule on `global` for a tool without an `id`.
+*/ const entityShape = (scope, operation, globalRule) => {
 	const { collections, globals } = slugsFor(scope, operation);
-	if (globals.length === 0) return widen({ collection: slugEnum(collections).describe(descriptions.collection) });
-	if (collections.length === 0) return widen({ global: slugEnum(globals).describe(descriptions.global) });
+	if (globals.length === 0) return widen({ collection: slugEnum(collections) });
+	if (collections.length === 0) return widen({ global: slugEnum(globals) });
+	const global = slugEnum(globals).optional();
 	return widen({
-		collection: slugEnum(collections).optional().describe(descriptions.collection),
-		global: slugEnum(globals).optional().describe(descriptions.global)
+		collection: slugEnum(collections).optional(),
+		global: globalRule === void 0 ? global : global.describe(globalRule)
 	});
 };
 /**
 * Only a collection document has one. Optional in the mixed case, where
-* `requireIdFor` enforces the dependency.
+* `resolveDocument` enforces the dependency and the description states it.
 */ const idShape = (scope, operation) => {
 	const { collections, globals } = slugsFor(scope, operation);
 	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\".") });
+	return widen({ id: idSchema.optional().describe("Required with \"collection\", omitted with \"global\".") });
 };
+/**
+* For the reads that fall back to the default locale, unlike the writes.
+*/ const READ_LOCALE_DESCRIPTION = "Default: the default locale. A value missing in this locale is shown from the default locale.";
 const localeShape = (scope, options) => {
-	if (!scope.locales) return widen({});
-	const locale = z.enum(scope.locales);
-	return widen({ locale: (options.required ? locale : locale.optional()).describe(options.description) });
+	if (!scope.localization) return widen({});
+	const enumerated = z.enum(scope.localization.locales);
+	const locale = options.required ? enumerated : enumerated.optional();
+	return widen({ locale: options.description === void 0 ? locale : locale.describe(options.description) });
 };
 /**
 * 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)}.`) });
+*/ const depthShape = (scope) => ({ depth: z.number().int().min(0).max(scope.limits.maxDepth).optional().describe("Default 0. A relationship into a collection this key cannot read stays an id.") });
 /**
 * The locale to operate on: the explicit argument, else the request's, else
 * the default. `undefined` when localization is off.
 */ const localeOf = (scope, locale) => {
-	if (!scope.locales) return;
+	if (!scope.localization) return;
+	const { locales, defaultLocale } = scope.localization;
 	const requested = locale ?? scope.req.locale;
-	return (requested && scope.locales.includes(requested) ? requested : scope.defaultLocale) ?? void 0;
-};
-/**
-* Reads the current draft in a fixed locale with no fallback, which is the
-* shape that may be written back or validated without mixing locales.
-*/ const readTarget = async (scope, args) => {
-	const { payload } = scope.req;
-	const privileged = args.privileged === true;
-	const shared = {
-		depth: 0,
-		draft: true,
-		...args.locale === void 0 ? {} : {
-			locale: args.locale,
-			fallbackLocale: false
-		},
-		overrideAccess: privileged,
-		showHiddenFields: privileged,
-		req: scope.req
-	};
-	if (args.target.kind === "collection") {
-		const doc = await payload.findByID({
-			...shared,
-			collection: args.target.slug,
-			id: args.id,
-			disableErrors: true
-		});
-		if (!doc) throw new NotFound(scope.req.t);
-		return doc;
-	}
-	return await payload.findGlobal({
-		...shared,
-		slug: args.target.slug
-	});
-};
-const translateLabel = (scope, label, fallback) => {
-	const { i18n, t } = scope.req;
-	const resolved = typeof label === "function" ? label({
-		i18n,
-		t
-	}) : label;
-	return translateStatic(resolved, i18n) ?? fallback;
+	return requested && locales.includes(requested) ? requested : defaultLocale;
 };
 //#endregion
-export { depthShape, draftSentence, idSchema, idShape, localeOf, localeShape, patchOnlySlugs, readTarget, sameInstant, slugEnum, slugsFor, targetShape, translateLabel };
+export { READ_LOCALE_DESCRIPTION, depthShape, draftVersionSlugs, entityShape, idSchema, idShape, liveWriteSentence, liveWriteSlugs, localeOf, localeShape, patchOnlySlugs, slugEnum, slugsFor, widen };

package/dist/tools/validate-document.mjs

@@ -1,57 +1,45 @@
+import { defineMcpxTool } from "../define-tool.mjs";
 import { jsonResult } from "../result.mjs";
-import { idShape, localeOf, localeShape, readTarget, targetShape } from "./shared.mjs";
-import { requireIdFor, resolveTarget } from "./target.mjs";
-import { defineMcpxTool } from "../types.mjs";
 import { collectPublishBlockers } from "../write/publish-blockers.mjs";
+import { entityShape, idShape, localeOf, localeShape } from "./shared.mjs";
+import { collectLocaleBlockers, identityOf, readDraft, resolveDocument } from "./document.mjs";
 /**
-* Gated on write rather than read, because publish blockers only mean
-* something to a caller who can act on them.
+* Gated on write rather than read, because publish blockers only mean something
+* to a caller who can act on them.
 *
 * It reads the document twice on purpose: once under the key's own access to
-* refuse a caller who may not see it, then privileged, so the check runs over
-* every field rather than the subset the user can read. It carries no
-* `readOnlyHint`, because the traversal fires field hooks.
+* refuse a caller who may not see it, then privileged, so the check covers every
+* field and not only those the user can read. It has no `readOnlyHint` because
+* the traversal fires field hooks.
 */ const validateDocument = defineMcpxTool({
 	name: "validateDocument",
-	description: `Reports what still prevents a human from publishing the draft, without writing anything. The same list patchDocument returns after a write; use it to check work or to answer "is this ready".
-
-Pass exactly one of "collection" and "global". "id" is required with "collection" and must be omitted with "global", because a global is a singleton.
-
-Nothing is written, but the check runs the same field-level beforeValidate and beforeChange hooks a save would, so a hook with side effects fires. "publishBlockersUnavailable" means the check itself failed, so the empty list says nothing.`,
+	description: `Lists what still blocks publishing one document or global, without saving. Checks one locale when "locale" is given, otherwise every locale. Returns "publishBlockers", each with a pointer and a message, and a "locale" when every locale was checked. An empty list means it can be published, unless "publishBlockersUnavailable" is true: then the check itself failed. The check runs the field hooks a save runs.`,
 	annotations: { 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 validate."
-		}),
+		...entityShape(scope, "write"),
 		...idShape(scope, "write"),
-		...localeShape(scope, {
-			required: true,
-			description: "Locale to validate."
-		})
+		...localeShape(scope, { required: false })
 	}),
 	handler: async ({ args, scope }) => {
-		const target = resolveTarget(scope, args, "write");
-		const id = requireIdFor(target, args.id);
+		const target = resolveDocument(scope, args, "write");
+		const { localization } = scope;
 		const locale = localeOf(scope, args.locale);
-		await readTarget(scope, {
+		await readDraft(scope, {
 			target,
-			id,
 			locale
 		});
-		const doc = await readTarget(scope, {
+		const doc = await readDraft(scope, {
 			target,
-			id,
 			locale,
 			privileged: true
 		});
-		const validation = await collectPublishBlockers(scope.req, {
+		const validation = localization && args.locale === void 0 ? await collectLocaleBlockers(scope, target, localization.locales) : await collectPublishBlockers(scope.req, {
 			doc,
 			entity: target
 		});
 		return jsonResult({
-			...target.kind === "collection" ? { id: doc["id"] } : { global: target.slug },
+			...identityOf(target, doc["id"]),
 			status: doc["_status"],
 			updatedAt: doc["updatedAt"],
 			publishBlockers: validation.blockers,

package/dist/tools/versions.mjs

@@ -1,35 +1,44 @@
+import { stripAdminHidden } from "../schema/admin-hidden.mjs";
+import "../schema/index.mjs";
+import { mcpxReadRequest } from "./read-request.mjs";
+import { hasDraftsEnabled } from "payload/shared";
 import { Pointer, createPatch } from "rfc6902";
 //#region src/tools/versions.ts
-/** Bookkeeping that differs between saves without saying anything about content. */ const NOISE = [
+const NOISE = [
 	"id",
 	"globalType",
 	"createdAt",
 	"updatedAt",
 	"_status"
 ];
-/** Newest first, with the id breaking ties between saves in the same instant. */ const NEWEST_FIRST = ["-updatedAt", "-id"];
-/** The document or global as the key's user sees it. */ const readLive = async (scope, read, options) => {
+const NEWEST_FIRST = ["-updatedAt", "-id"];
+/**
+* The document or global as the key's user sees it, without `admin.hidden`
+* fields.
+*/ const readLive = async (scope, read, options) => {
 	const shared = {
 		depth: read.depth,
 		draft: options.draft,
 		overrideAccess: false,
-		req: scope.req,
+		req: mcpxReadRequest(scope),
 		...options.select === void 0 ? {} : { select: options.select },
 		...read.locale === void 0 ? {} : { locale: read.locale }
 	};
-	return await (read.target.kind === "collection" ? scope.req.payload.findByID({
+	const doc = await (read.target.kind === "collection" ? scope.req.payload.findByID({
 		...shared,
 		collection: read.target.slug,
-		id: read.id
+		id: read.target.id
 	}) : scope.req.payload.findGlobal({
 		...shared,
 		slug: read.target.slug
 	}));
+	return stripAdminHidden(scope.req.payload.config, read.target, doc);
 };
-/**
-* Payload checks only `readVersions` on a version read, never `read`, so the
-* document itself is read first and throws when the key's user may not see it.
-*/ const assertReadable = async (scope, read) => {
+const withoutHidden = (scope, read, stored) => ({
+	...stored,
+	version: stripAdminHidden(scope.req.payload.config, read.target, stored.version)
+});
+const assertReadable = async (scope, read) => {
 	await readLive(scope, {
 		...read,
 		depth: 0
@@ -38,7 +47,9 @@ import { Pointer, createPatch } from "rfc6902";
 		select: {}
 	});
 };
-/** `parent` comes back as a raw id or, populated, as the document itself. */ const isVersionOf = (version, id) => {
+/**
+* `parent` comes back as a raw id or, populated, as the document itself.
+*/ const isVersionOf = (version, id) => {
 	const parent = version["parent"];
 	const parentId = typeof parent === "object" && parent !== null ? parent["id"] : parent;
 	return (typeof parentId === "string" || typeof parentId === "number") && String(parentId) === String(id);
@@ -56,7 +67,7 @@ import { Pointer, createPatch } from "rfc6902";
 		depth: read.depth,
 		disableErrors: true,
 		overrideAccess: false,
-		req: scope.req,
+		req: mcpxReadRequest(scope),
 		...read.locale === void 0 ? {} : { locale: read.locale }
 	};
 	const version = await (read.target.kind === "collection" ? payload.findVersionByID({
@@ -67,13 +78,15 @@ import { Pointer, createPatch } from "rfc6902";
 		slug: read.target.slug
 	}));
 	if (!version) return null;
-	if (read.id !== void 0 && !isVersionOf(version, read.id)) return null;
-	return version;
+	if (read.target.kind === "collection" && !isVersionOf(version, read.target.id)) return null;
+	return withoutHidden(scope, read, version);
 };
-/** One page of a document's or global's history, newest first. */ const queryVersions = async (scope, read, options) => {
+/**
+* One page of a document's or global's history, newest first.
+*/ const queryVersions = async (scope, read, options) => {
 	await assertReadable(scope, read);
 	const where = {
-		...read.id === void 0 ? {} : { parent: { equals: read.id } },
+		...read.target.kind === "collection" ? { parent: { equals: read.target.id } } : {},
 		...options.status === void 0 ? {} : { "version._status": { equals: options.status } }
 	};
 	const shared = {
@@ -81,7 +94,7 @@ import { Pointer, createPatch } from "rfc6902";
 		limit: options.limit,
 		sort: NEWEST_FIRST,
 		overrideAccess: false,
-		req: scope.req,
+		req: mcpxReadRequest(scope),
 		where,
 		...options.page === void 0 ? {} : { page: options.page },
 		...read.locale === void 0 ? {} : { locale: read.locale }
@@ -94,11 +107,15 @@ import { Pointer, createPatch } from "rfc6902";
 		slug: read.target.slug
 	}));
 };
-/** The newest version whose status is published, or `null` if none is. */ const loadPublished = async (scope, read) => {
-	return (await queryVersions(scope, read, {
+/**
+* The newest version whose status is published, or `null` if none is.
+*/ const loadPublished = async (scope, read) => {
+	if (!hasDraftsEnabled(read.target.config)) return null;
+	const [newest] = (await queryVersions(scope, read, {
 		status: "published",
 		limit: 1
-	})).docs[0] ?? null;
+	})).docs;
+	return newest ? withoutHidden(scope, read, newest) : null;
 };
 const strip = (doc) => Object.fromEntries(Object.entries(doc).filter(([key]) => !NOISE.includes(key)));
 /**