@abinnovision/payloadcms-mcpx 2.0.0-beta.18 → 2.0.0-beta.20

package/dist/schema/lexical-pointer.mjs

@@ -1,8 +1,8 @@
-import { isPlainObject } from "../guards.mjs";
-import { lexicalSubSchema, subSchemaNodeTypes } from "./lexical.mjs";
+import { isPlainObject, propOf } from "../guards.mjs";
+import { SchemaError } from "./errors.mjs";
+import { editorRoot, lexicalSubSchema, subSchemaNodeTypes } from "./lexical.mjs";
 import { isIndexSegment, joinPath } from "./path.mjs";
 import { blockOf, blockSlugsOf } from "./walk.mjs";
-import { SchemaError } from "./errors.mjs";
 //#region src/schema/lexical-pointer.ts
 const stepIntoFields = (at) => {
 	const { addedValue, config, field, node, nodeType, rest } = at;
@@ -15,8 +15,7 @@ const stepIntoFields = (at) => {
 		kind: "fields",
 		rest
 	};
-	const added = addedValue?.fields;
-	const slug = (isPlainObject(data) ? data["blockType"] : void 0) ?? (isPlainObject(added) ? added["blockType"] : void 0);
+	const slug = propOf(data, "blockType") ?? propOf(propOf(addedValue, "fields"), "blockType");
 	if (slug === void 0) throw new SchemaError(`Cannot tell which block a "${nodeType}" node holds. Supply a "blockType" on the value, one of: ${blockSlugsOf(sub.blocksField).join(", ")}`);
 	if (typeof slug !== "string") throw new SchemaError(`"blockType" must be a string naming a block in a "${nodeType}" node here. Allowed: ${blockSlugsOf(sub.blocksField).join(", ")}`);
 	const block = blockOf(config, sub.blocksField, slug);
@@ -41,10 +40,11 @@ const stepIntoFields = (at) => {
 		descriptor,
 		field
 	};
-	if (!isPlainObject(state) || !isPlainObject(state["root"])) throw new SchemaError(`"${descriptor.path}" holds no editor state yet. Write the whole field once, then address positions inside it.`);
+	const root = editorRoot(state);
+	if (!root) throw new SchemaError(`"${descriptor.path}" holds no editor state yet. Write the whole field once, then address positions inside it.`);
 	const [entry, ...rest] = at.segments;
 	if (entry !== "root") throw new SchemaError(`"${String(entry)}" is not a position in a rich text field. An editor state is entered at "root", e.g. "${descriptor.path}/root/children/0". getDocument with "outline" lists every position this field holds.`);
-	let node = state["root"];
+	let node = root;
 	let nodeType = "root";
 	let segments = rest;
 	let walked = ["root"];
@@ -73,7 +73,7 @@ const stepIntoFields = (at) => {
 			if (!isIndexSegment(index)) throw new SchemaError(`"${descriptor.path}${joinPath([...walked, "children"])}" is a list; "${index}" is not an index. getDocument with "outline" reports the pointer of each node in it.`);
 			const children = node?.["children"];
 			const child = Array.isArray(children) && index !== "-" ? children[Number(index)] : void 0;
-			const type = isPlainObject(child) ? child["type"] : addedValue?.type;
+			const type = isPlainObject(child) ? child["type"] : propOf(addedValue, "type");
 			if (typeof type !== "string") {
 				if (beyond.length === 0) return {
 					kind: "position",

package/dist/schema/lexical.mjs

@@ -1,4 +1,4 @@
-import { isPlainObject, ownValue } from "../guards.mjs";
+import { isPlainObject, ownValue, propOf } from "../guards.mjs";
 import { flattenAllFields } from "payload";
 //#region src/schema/lexical.ts
 const LEXICAL_CORE_NODES = [
@@ -148,6 +148,16 @@ const UNIVERSAL_PROPERTIES = { version: "number" };
 	}
 };
 /**
+* The `root` node of an editor state, if it has one.
+*/ const editorRoot = (state) => {
+	const root = propOf(state, "root");
+	return isPlainObject(root) ? root : void 0;
+};
+const constraintsFor = (type) => ({
+	...UNIVERSAL_PROPERTIES,
+	...ownValue(REQUIRED_NODE_PROPERTIES, type)
+});
+/**
 * Whether the table already says what a node type's `fields` must be, so the
 * sub-field walk does not report the same problem twice.
 */ const constrainsFields = (type) => "fields" in (ownValue(REQUIRED_NODE_PROPERTIES, type) ?? {});
@@ -159,8 +169,7 @@ const describeConstraints = (constraints) => Object.fromEntries(Object.entries(c
 * {@link UNIVERSAL_PROPERTIES} omits it: the validator finds the entry by
 * `type` and so never reports it missing, but a client must still write one.
 */ const nodePropertiesFor = (types) => Object.fromEntries([...new Set(types)].sort().map((type) => [type, describeConstraints(type === "root" ? ROOT_PROPERTIES : {
-	...ownValue(REQUIRED_NODE_PROPERTIES, type),
-	...UNIVERSAL_PROPERTIES,
+	...constraintsFor(type),
 	type: "string"
 })]));
 const check = (node, constraints) => {
@@ -177,10 +186,7 @@ const check = (node, constraints) => {
 	problems.rejected.sort((left, right) => left.property.localeCompare(right.property));
 	return problems;
 };
-const nodeProblems = (node) => check(node, {
-	...UNIVERSAL_PROPERTIES,
-	...ownValue(REQUIRED_NODE_PROPERTIES, node["type"])
-});
+const nodeProblems = (node) => check(node, constraintsFor(node["type"]));
 /**
 * The root is the one node Payload describes itself, down to refusing an
 * unknown property, so it is checked against that description instead of the
@@ -194,11 +200,7 @@ const nodeProblems = (node) => check(node, {
 * instead of a whole node. Absent where the table says nothing, matching the
 * node walk: a project's own node may carry any property.
 */ const propertyProblem = (nodeType, property, value) => {
-	const constraints = nodeType === "root" ? ROOT_PROPERTIES : {
-		...UNIVERSAL_PROPERTIES,
-		...ownValue(REQUIRED_NODE_PROPERTIES, nodeType)
-	};
-	const constraint = ownValue(constraints, property);
+	const constraint = ownValue(nodeType === "root" ? ROOT_PROPERTIES : constraintsFor(nodeType), property);
 	return constraint === void 0 || accepts(constraint, value) ? void 0 : { needs: needs(constraint) };
 };
 const NODE_OPTION_SOURCES = [{
@@ -233,4 +235,4 @@ const stringList = (value) => Array.isArray(value) && value.every((entry) => typ
 	return entries.length > 0 ? Object.fromEntries(entries) : void 0;
 };
 //#endregion
-export { REQUIRED_NODE_PROPERTIES, ROOT_PROPERTIES, allowedNodeTypes, constrainsFields, lexicalSubSchema, nodeOptions, nodeProblems, nodePropertiesFor, propertyProblem, rootProblems, subSchemaNodeTypes };
+export { REQUIRED_NODE_PROPERTIES, ROOT_PROPERTIES, allowedNodeTypes, constrainsFields, editorRoot, lexicalSubSchema, nodeOptions, nodeProblems, nodePropertiesFor, propertyProblem, rootProblems, subSchemaNodeTypes };

package/dist/schema/outline.mjs

@@ -1,5 +1,5 @@
 import { isPlainObject, ownValue } from "../guards.mjs";
-import { allowedNodeTypes, nodeOptions } from "./lexical.mjs";
+import { allowedNodeTypes, editorRoot, nodeOptions } from "./lexical.mjs";
 //#region src/schema/outline.ts
 const TEXT_PREVIEW_LENGTH = 80;
 const collectText = (node) => {
@@ -43,12 +43,11 @@ const walk = (node, pointer, options, entries) => {
 * entry's `pointer` extends it with "/root" and the node's real indices, which
 * makes it directly usable in a patch operation.
 */ const lexicalOutline = (state, basePointer, field) => {
-	if (!isPlainObject(state)) return [];
-	const root = state["root"];
-	if (!isPlainObject(root) || !Array.isArray(root["children"])) return [];
+	const rootChildren = editorRoot(state)?.["children"];
+	if (!Array.isArray(rootChildren)) return [];
 	const options = nodeOptions(field, allowedNodeTypes(field));
 	const entries = [];
-	root["children"].forEach((child, index) => {
+	rootChildren.forEach((child, index) => {
 		if (isPlainObject(child)) walk(child, `${basePointer}/root/children/${String(index)}`, options, entries);
 	});
 	return entries;

package/dist/schema/path.mjs

@@ -24,5 +24,8 @@ const PROTOTYPE_SEGMENTS = /* @__PURE__ */ new Set([
 * Pointer, so everything handed back addresses documents the same way. The
 * path already carries real indices, so it maps directly.
 */ const pointerFromPayloadPath = (path) => path ? joinPath(path.split(".")) : "";
+/**
+* The pointer one segment up. The root pointer stays the root.
+*/ const parentPointer = (pointer) => joinPath(splitPath(pointer).slice(0, -1));
 //#endregion
-export { JSON_POINTER_PATTERN, isIndexSegment, joinPath, pointerFromPayloadPath, prototypeSegmentProblem, splitPath };
+export { JSON_POINTER_PATTERN, isIndexSegment, joinPath, parentPointer, pointerFromPayloadPath, prototypeSegmentProblem, splitPath };

package/dist/schema/pointer.mjs

@@ -1,14 +1,10 @@
-import { isIndexSegment, joinPath, splitPath } from "./path.mjs";
-import { blockOf, blockSlugsOf, describeAddressableFields, findBlocksField, findRichTextField, schemaOf } from "./walk.mjs";
+import { propOf } from "../guards.mjs";
 import { SchemaError } from "./errors.mjs";
+import { isIndexSegment, joinPath, splitPath } from "./path.mjs";
+import { blockSlugsOf, describeAddressableFields, findFieldAt, longestMatch, requireBlock, schemaOf } from "./walk.mjs";
 import { resolveLexicalPointer } from "./lexical-pointer.mjs";
 //#region src/schema/pointer.ts
 const partMatches = (part, segment) => segment !== void 0 && (part === "*" ? isIndexSegment(segment) : part === segment);
-const matchPointerSegments = (descriptors, segments) => descriptors.map((descriptor) => ({
-	consumed: splitPath(descriptor.path).length,
-	descriptor,
-	parts: splitPath(descriptor.path)
-})).filter(({ parts }) => parts.every((part, offset) => partMatches(part, segments[offset]))).sort((left, right) => right.consumed - left.consumed)[0];
 const isSubtreePrefix = (descriptors, segments) => descriptors.some((descriptor) => {
 	const parts = splitPath(descriptor.path);
 	return parts.length > segments.length && segments.every((segment, offset) => {
@@ -21,17 +17,15 @@ const stepIntoBlock = (at) => {
 	const { addedValue, config, descriptor, rows } = at;
 	const [index, ...remaining] = at.rest;
 	if (!isIndexSegment(index)) throw new SchemaError(`"${descriptor.path}" is an array; "${index}" is not an index.`);
-	const field = findBlocksField(at.fields, splitPath(descriptor.path));
+	const field = findFieldAt(at.fields, splitPath(descriptor.path), "blocks");
 	const existing = Array.isArray(rows) && index !== "-" ? rows[Number(index)] : void 0;
-	const slug = existing?.blockType ?? addedValue?.blockType;
+	const slug = propOf(existing, "blockType") ?? propOf(addedValue, "blockType");
 	if (!field || slug === void 0) throw new SchemaError(`Cannot tell which block "${descriptor.path}/${index}" is. Supply a "blockType" on the value, one of: ${field ? blockSlugsOf(field).join(", ") : ""}`);
 	if (typeof slug !== "string") throw new SchemaError(`"blockType" must be a string naming a block at "${descriptor.path}". Allowed: ${blockSlugsOf(field).join(", ")}`);
-	const block = blockOf(config, field, slug);
-	if (!block) throw new SchemaError(`"${slug}" is not allowed at "${descriptor.path}". Allowed: ${blockSlugsOf(field).join(", ")}`);
 	return {
 		blockType: slug,
 		data: existing,
-		fields: block.flattenedFields,
+		fields: requireBlock(config, field, slug, descriptor.path).flattenedFields,
 		rest: remaining
 	};
 };
@@ -48,7 +42,7 @@ const stepIntoBlock = (at) => {
 	let inLexical;
 	while (segments.length > 0) {
 		const descriptors = describeAddressableFields(fields);
-		const match = matchPointerSegments(descriptors, segments);
+		const match = longestMatch(descriptors, segments, partMatches);
 		if (!match) {
 			if (isSubtreePrefix(descriptors, segments)) return {
 				...blockType === void 0 ? {} : { blockType },
@@ -57,7 +51,7 @@ const stepIntoBlock = (at) => {
 			};
 			throw new SchemaError(`"${joinPath(segments)}" is not a field here. Available: ${descriptors.map((descriptor) => descriptor.path).join(", ")}`);
 		}
-		const rest = segments.slice(match.consumed);
+		const rest = segments.slice(match.parts.length);
 		if (rest.length === 0) return {
 			...blockType === void 0 ? {} : { blockType },
 			descriptor: match.descriptor,
@@ -67,7 +61,7 @@ const stepIntoBlock = (at) => {
 			...readOnly === void 0 ? {} : { readOnly }
 		};
 		if (match.descriptor.type === "richText") {
-			const field = findRichTextField(fields, splitPath(match.descriptor.path));
+			const field = findFieldAt(fields, splitPath(match.descriptor.path), "richText");
 			if (!field) throw new Error(`"${match.descriptor.path}" could not be resolved.`);
 			const step = resolveLexicalPointer({
 				...target.addedValue === void 0 ? {} : { addedValue: target.addedValue },
@@ -75,7 +69,7 @@ const stepIntoBlock = (at) => {
 				descriptor: match.descriptor,
 				field,
 				segments: rest,
-				state: valueAtSegments(data, segments.slice(0, match.consumed))
+				state: valueAtSegments(data, segments.slice(0, match.parts.length))
 			});
 			if (step.kind === "position") return {
 				...blockType === void 0 ? {} : { blockType },
@@ -99,7 +93,7 @@ const stepIntoBlock = (at) => {
 			descriptor: match.descriptor,
 			fields,
 			rest,
-			rows: valueAtSegments(data, segments.slice(0, match.consumed)),
+			rows: valueAtSegments(data, segments.slice(0, match.parts.length)),
 			config
 		});
 		readOnly = match.descriptor.readOnly ?? readOnly;

package/dist/schema/shape.mjs

@@ -1,7 +1,7 @@
-import { isPlainObject, ownValue } from "../guards.mjs";
-import { ROOT_PROPERTIES, constrainsFields, lexicalSubSchema, nodeProblems, propertyProblem, rootProblems } from "./lexical.mjs";
+import { isPlainObject, ownValue, propOf } from "../guards.mjs";
+import { ROOT_PROPERTIES, constrainsFields, editorRoot, lexicalSubSchema, nodeProblems, propertyProblem, rootProblems } from "./lexical.mjs";
 import { splitPath } from "./path.mjs";
-import { ROW_KEYS, blockOf, blockSlugsOf, descriptorsUnder, findBlocksField, findRichTextField } from "./walk.mjs";
+import { ROW_KEYS, blockForRow, blockSlugsOf, classifyKey, descriptorsUnder, findFieldAt } from "./walk.mjs";
 //#region src/schema/shape.ts
 /**
 * Lexical throws when it hydrates a state whose root holds nothing. An empty
@@ -33,10 +33,9 @@ const checkNodeFields = (scope, field, node) => {
 		}, data);
 		return;
 	}
-	const slug = data["blockType"];
-	const block = typeof slug === "string" ? blockOf(scope.config, sub.blocksField, slug) : void 0;
+	const block = blockForRow(scope.config, sub.blocksField, data);
 	if (!block) {
-		scope.problems.push(`${scope.pointer}/fields: ${refusedSlug(slug)}. Allowed: ${blockSlugsOf(sub.blocksField).join(", ")}`);
+		scope.problems.push(`${scope.pointer}/fields: ${refusedSlug(data["blockType"])}. Allowed: ${blockSlugsOf(sub.blocksField).join(", ")}`);
 		return;
 	}
 	checkValue({
@@ -81,11 +80,11 @@ const checkNodes = (scope, editor, nodes, pointer) => {
 	});
 };
 const checkRichText = (scope, editor, value) => {
-	if (!isPlainObject(value) || !isPlainObject(value["root"])) {
+	const root = editorRoot(value);
+	if (!root) {
 		scope.problems.push(`${scope.pointer}: expected a Lexical editor state with a "root".`);
 		return;
 	}
-	const root = value["root"];
 	const { missing, rejected, unexpected } = rootProblems(root);
 	if (missing.length > 0) scope.problems.push(`${scope.pointer}/root: the root node is missing ${quoted(missing)}. Write nodes as Lexical serializes them.`);
 	for (const problem of rejected) scope.problems.push(`${scope.pointer}/root/${problem.property}: the root node needs ${problem.needs} here.`);
@@ -148,7 +147,7 @@ const checkLeafValue = (scope, descriptor, value) => {
 	if (descriptor.type === "richText") {
 		checkRichText(scope, {
 			allowed: descriptor.nodes ?? [],
-			field: findRichTextField(scope.fields, splitPath(descriptor.path)),
+			field: findFieldAt(scope.fields, splitPath(descriptor.path), "richText"),
 			nodeOptions: descriptor.nodeOptions
 		}, value);
 		return;
@@ -158,13 +157,12 @@ const checkLeafValue = (scope, descriptor, value) => {
 		scope.problems.push(`${scope.pointer}: expected an array of blocks.`);
 		return;
 	}
-	const field = findBlocksField(scope.fields, splitPath(descriptor.path));
-	if (!field) return;
+	const field = findFieldAt(scope.fields, splitPath(descriptor.path), "blocks");
 	value.forEach((row, index) => {
-		const slug = isPlainObject(row) ? row["blockType"] : void 0;
-		const block = typeof slug === "string" ? blockOf(scope.config, field, slug) : void 0;
+		const block = field && blockForRow(scope.config, field, row);
+		if (!field) return;
 		if (!block) {
-			scope.problems.push(`${scope.pointer}/${String(index)}: ${refusedSlug(slug)}. Allowed: ${blockSlugsOf(field).join(", ")}`);
+			scope.problems.push(`${scope.pointer}/${String(index)}: ${refusedSlug(propOf(row, "blockType"))}. Allowed: ${blockSlugsOf(field).join(", ")}`);
 			return;
 		}
 		checkValue({
@@ -177,47 +175,37 @@ const checkLeafValue = (scope, descriptor, value) => {
 };
 const checkValue = (scope, value) => {
 	if (!isPlainObject(value)) return;
-	const prefixParts = scope.prefix;
-	const relative = descriptorsUnder(scope.fields, prefixParts);
+	const relative = descriptorsUnder(scope.fields, scope.prefix);
 	for (const [key, entry] of Object.entries(value)) {
 		if (ROW_KEYS.has(key)) continue;
-		const candidates = relative.filter(({ parts }) => parts[0] === key);
 		const pointer = `${scope.pointer}/${key}`;
-		if (candidates.length === 0) {
-			scope.problems.push(`${pointer}: no such field. Available: ${[...new Set(relative.map(({ parts }) => parts[0]))].join(", ")}`);
-			continue;
-		}
-		const exact = candidates.find(({ parts }) => parts.length === 1);
-		if (exact) {
-			checkLeafValue({
-				...scope,
-				pointer
-			}, exact.descriptor, entry);
-			continue;
-		}
-		if (candidates.some(({ parts }) => parts[1] === "*")) {
-			if (!Array.isArray(entry)) {
-				scope.problems.push(`${pointer}: expected an array.`);
-				continue;
-			}
-			entry.forEach((row, index) => {
-				checkValue({
+		const found = classifyKey(relative, scope.prefix, key);
+		switch (found.kind) {
+			case "none":
+				scope.problems.push(`${pointer}: no such field. Available: ${[...new Set(relative.map(({ parts }) => parts[0]))].join(", ")}`);
+				break;
+			case "leaf":
+				checkLeafValue({
 					...scope,
-					pointer: `${pointer}/${String(index)}`,
-					prefix: [
-						...prefixParts,
-						key,
-						"*"
-					]
-				}, row);
-			});
-			continue;
+					pointer
+				}, found.descriptor, entry);
+				break;
+			case "rows":
+				if (Array.isArray(entry)) entry.forEach((row, index) => {
+					checkValue({
+						...scope,
+						pointer: `${pointer}/${String(index)}`,
+						prefix: found.prefix
+					}, row);
+				});
+				else scope.problems.push(`${pointer}: expected an array.`);
+				break;
+			case "group": checkValue({
+				...scope,
+				pointer,
+				prefix: found.prefix
+			}, entry);
 		}
-		checkValue({
-			...scope,
-			pointer,
-			prefix: [...prefixParts, key]
-		}, entry);
 	}
 };
 const validateWriteValue = (config, target, value) => {

package/dist/schema/walk.mjs

@@ -1,3 +1,5 @@
+import { propOf } from "../guards.mjs";
+import { SchemaError } from "./errors.mjs";
 import { allowedNodeTypes, nodeOptions } from "./lexical.mjs";
 import { joinPath, splitPath } from "./path.mjs";
 import { translateAny } from "../i18n.mjs";
@@ -34,9 +36,17 @@ const RESERVED_FIELD_NAMES = /* @__PURE__ */ new Set([
 /**
 * Payload's `fieldIsHiddenOrDisabled` reads `hidden` and `admin.disabled`, not
 * `admin.hidden`, which its own upload base fields carry.
-*/ const isAdminHidden = (field) => "admin" in field && field.admin.hidden === true;
-const isSkipped = (field) => !("name" in field) || field.type === "join" || RESERVED_FIELD_NAMES.has(field.name) || fieldIsVirtual(field) || isAdminHidden(field) || fieldIsHiddenOrDisabled(field);
-const isReadOnly = (field) => "admin" in field && field.admin.readOnly === true;
+*/ const adminFlag = (field, key) => "admin" in field && field.admin[key] === true;
+const blockForRow = (config, field, row) => {
+	const slug = propOf(row, "blockType");
+	return typeof slug === "string" ? blockOf(config, field, slug) : void 0;
+};
+const requireBlock = (config, field, slug, at) => {
+	const block = blockOf(config, field, slug);
+	if (!block) throw new SchemaError(`"${slug}" is not allowed at "${at}". Allowed: ${blockSlugsOf(field).join(", ")}`);
+	return block;
+};
+const isSkipped = (field) => !("name" in field) || field.type === "join" || RESERVED_FIELD_NAMES.has(field.name) || fieldIsVirtual(field) || adminFlag(field, "hidden") || fieldIsHiddenOrDisabled(field);
 const describeBase = (field, { path, readOnly, translate }) => {
 	const description = translate("admin" in field ? field.admin.description : void 0);
 	return {
@@ -71,17 +81,11 @@ const withRows = (descriptor, field) => ({
 });
 const isContainer = (descriptor) => descriptor.type === "array" || descriptor.type === "group" || descriptor.type === "tab";
 const isInformative = (descriptor) => descriptor.description !== void 0 || descriptor.required === true || descriptor.localized === true;
-/**
-* Named tabs, groups and arrays add a path segment and are described
-* themselves only when they declare something of their own: an array always,
-* since its row counts live nowhere else. The walk stops at every blocks field
-* and names the slugs, so a node's size follows the number of blocks it
-* allows, not their definitions. Omitting `translate` costs language
-* selection, never the description itself.
-*/ const describeFields = (fields, translate = translateAny) => {
+const describedByFields = /* @__PURE__ */ new WeakMap();
+const describeWith = (fields, translate) => {
 	const walk = (current, prefix, parentReadOnly) => current.flatMap((field) => {
 		if (isSkipped(field)) return [];
-		const readOnly = parentReadOnly || isReadOnly(field);
+		const readOnly = parentReadOnly || adminFlag(field, "readOnly");
 		const path = [...prefix, field.name];
 		const at = {
 			path: joinPath(path),
@@ -102,6 +106,22 @@ const isInformative = (descriptor) => descriptor.description !== void 0 || descr
 	return walk(fields, [], false);
 };
 /**
+* Named tabs, groups and arrays add a path segment and are described
+* themselves only when they declare something of their own: an array always,
+* since its row counts live nowhere else. The walk stops at every blocks field
+* and names the slugs, so a node's size follows the number of blocks it
+* allows, not their definitions. Omitting `translate` costs language
+* selection, never the description itself.
+*/ const describeFields = (fields, translate = translateAny) => {
+	if (translate !== translateAny) return describeWith(fields, translate);
+	let described = describedByFields.get(fields);
+	if (!described) {
+		described = describeWith(fields, translate);
+		describedByFields.set(fields, described);
+	}
+	return described;
+};
+/**
 * The descriptors that address a value, which every walk resolving a path
 * against a document needs. Containers are left out, since only
 * {@link nodeDescriber} reports one.
@@ -124,11 +144,30 @@ const findFieldAt = (fields, path, type) => {
 		if (field.type === "array" && path[1] === "*") return findFieldAt(field.flattenedFields, path.slice(2), type);
 	}
 };
-const findBlocksField = (fields, path) => findFieldAt(fields, path, "blocks");
-/**
-* Locates the rich text field a resolved descriptor path refers to, so its
-* editor can be introspected for the fields its nodes carry.
-*/ const findRichTextField = (fields, path) => findFieldAt(fields, path, "richText");
+const longestMatch = (descriptors, segments, eq) => descriptors.map((descriptor) => ({
+	descriptor,
+	parts: splitPath(descriptor.path)
+})).filter(({ parts }) => parts.every((part, offset) => eq(part, segments[offset]))).sort((left, right) => right.parts.length - left.parts.length)[0];
+const classifyKey = (relative, prefix, key) => {
+	const candidates = relative.filter(({ parts }) => parts[0] === key);
+	const exact = candidates.find(({ parts }) => parts.length === 1);
+	if (exact) return {
+		descriptor: exact.descriptor,
+		kind: "leaf"
+	};
+	if (candidates.length === 0) return { kind: "none" };
+	return candidates.some(({ parts }) => parts[1] === "*") ? {
+		kind: "rows",
+		prefix: [
+			...prefix,
+			key,
+			"*"
+		]
+	} : {
+		kind: "group",
+		prefix: [...prefix, key]
+	};
+};
 /**
 * Looks up the sanitized config for a collection or global as an
 * {@link EntitySchema}. Throws on an unknown slug instead of returning
@@ -140,4 +179,4 @@ const findBlocksField = (fields, path) => findFieldAt(fields, path, "blocks");
 	return found;
 };
 //#endregion
-export { RESERVED_FIELD_NAMES, ROW_KEYS, blockOf, blockSlugsOf, describeAddressableFields, describeFields, descriptorsUnder, findBlocksField, findRichTextField, isAdminHidden, schemaOf };
+export { RESERVED_FIELD_NAMES, ROW_KEYS, adminFlag, blockForRow, blockOf, blockSlugsOf, classifyKey, describeAddressableFields, describeFields, descriptorsUnder, findFieldAt, longestMatch, requireBlock, schemaOf };

package/dist/tools/create-document.mjs

@@ -1,12 +1,11 @@
 import { defineMcpxTool } from "../define-tool.mjs";
-import { errorResult, jsonResult } from "../result.mjs";
+import { definedProps } from "../guards.mjs";
+import { errorResult } from "../result.mjs";
 import { validateWriteValue } from "../schema/shape.mjs";
 import "../schema/index.mjs";
-import { collectPublishBlockers } from "../write/publish-blockers.mjs";
 import { assertAcceptsFile, fileShape, fileWriteRefusal, uploadHandoff, uploadedFile } from "../upload/file.mjs";
-import { liveWriteSentence, localeOf, localeShape, patchOnlySlugs, slugEnum, slugsFor } from "./shared.mjs";
-import { readDraft, resolveEntity } from "./document.mjs";
-import { documentLinks } from "./links.mjs";
+import { liveWriteSentence, localeOf, localeShape, patchOnlySlugs, slugsFor, stringEnum } from "./shared.mjs";
+import { resolveCollection, writtenResult } from "./document.mjs";
 import { stripRowIds } from "../write/row-ids.mjs";
 import { z } from "zod";
 import { APIError } from "payload";
@@ -19,36 +18,6 @@ const DESCRIPTION = (scope) => `Creates a document in a collection. Use it only
 
 ${liveWriteSentence(scope, "create")}${uploadSentence(scope)}`;
 /**
-* What createDocument and duplicateDocument return: the new document, re-read
-* privileged in `locale`, with its links and publish blockers.
-*/ const createdResult = async (scope, args) => {
-	const { target, locale } = args;
-	const saved = await readDraft(scope, {
-		target: {
-			...target,
-			id: args.id
-		},
-		locale,
-		privileged: true
-	});
-	const validation = await collectPublishBlockers(scope.req, {
-		doc: saved,
-		entity: target
-	});
-	return jsonResult({
-		id: saved["id"],
-		status: saved["_status"],
-		updatedAt: saved["updatedAt"],
-		...await documentLinks(scope.req, {
-			target,
-			doc: saved,
-			locale
-		}),
-		...validation.blockers.length > 0 ? { publishBlockers: validation.blockers } : {},
-		...validation.unavailable ? { publishBlockersUnavailable: true } : {}
-	});
-};
-/**
 * Collection-only, because a global always exists. A create in an upload
 * collection needs `file`: the call then returns an upload grant, and the PUT
 * to it runs the call again with the bytes.
@@ -69,7 +38,7 @@ ${liveWriteSentence(scope, "create")}${uploadSentence(scope)}`;
 	},
 	isEnabled: (scope) => slugsFor(scope, "create").collections.length > 0,
 	inputSchema: (scope) => ({
-		collection: slugEnum(slugsFor(scope, "create").collections),
+		collection: stringEnum(slugsFor(scope, "create").collections),
 		...localeShape(scope, {
 			required: true,
 			description: "Locale of the localized fields in \"data\"."
@@ -78,8 +47,7 @@ ${liveWriteSentence(scope, "create")}${uploadSentence(scope)}`;
 		...fileShape(scope, (slugs) => `Required in ${slugs}. The call returns an "upload" for the bytes instead of writing.`)
 	}),
 	handler: async ({ args, scope }) => {
-		const target = resolveEntity(scope, { collection: args.collection }, "create");
-		if (target.kind === "global") throw new Error("createDocument resolved a global.");
+		const target = resolveCollection(scope, args.collection, "create");
 		const { payload } = scope.req;
 		const locale = localeOf(scope, args.locale);
 		const { file } = args;
@@ -116,15 +84,19 @@ ${liveWriteSentence(scope, "create")}${uploadSentence(scope)}`;
 			draft: true,
 			overrideAccess: false,
 			req: scope.req,
-			...locale === void 0 ? {} : { locale },
-			...bytes === void 0 ? {} : { file: bytes }
+			...definedProps({
+				locale,
+				file: bytes
+			})
 		});
-		return await createdResult(scope, {
-			target,
-			id: created["id"],
+		return await writtenResult(scope, {
+			target: {
+				...target,
+				id: created["id"]
+			},
 			locale
 		});
 	}
 });
 //#endregion
-export { createDocument, createdResult };
+export { createDocument };

package/dist/tools/delete-document.mjs

@@ -1,12 +1,12 @@
 import { defineMcpxTool } from "../define-tool.mjs";
 import { errorResult, jsonResult } from "../result.mjs";
 import { translateStatic } from "../i18n.mjs";
-import { entityShape, idShape, slugsFor } from "./shared.mjs";
-import { resolveDocument, staleReadResult } from "./document.mjs";
+import { expectedUpdatedAtShape, idSchema, slugsFor, stringEnum } from "./shared.mjs";
+import { readDraft, resolveCollection, staleReadResult } from "./document.mjs";
 import { withTrashIntent } from "../write/publish-intent.mjs";
 import { withTransaction } from "../write/transaction.mjs";
 import { z } from "zod";
-import { Forbidden, NotFound, combineQueries, executeAccess } from "payload";
+import { Forbidden, combineQueries, executeAccess } from "payload";
 import { formatAdminURL } from "payload/shared";
 //#region src/tools/delete-document.ts
 const DESCRIPTION = `Asks to delete one document. This call deletes nothing: it returns a "confirmation" with an "id" and a "url". Give the url to the user, who approves or rejects in the admin panel, then pass the id to runConfirmed, which deletes. Refused when the document is unknown, already in trash, changed since "expectedUpdatedAt" or not deletable by the user.`;
@@ -58,9 +58,9 @@ const mayDelete = async (req, target) => {
 	},
 	isEnabled: (scope) => scope.uploads && scope.collections.deletable.length > 0,
 	inputSchema: (scope) => ({
-		...entityShape(scope, "delete"),
-		...idShape(scope, "delete"),
-		expectedUpdatedAt: z.string().optional().describe("\"updatedAt\" from your last read. Refused if the document changed since."),
+		collection: stringEnum(scope.collections.deletable),
+		id: idSchema,
+		...expectedUpdatedAtShape,
 		reason: z.string().max(500).optional().describe("Why, shown to the user who approves.")
 	}),
 	confirm: {
@@ -103,22 +103,19 @@ const mayDelete = async (req, target) => {
 		}
 	},
 	handler: async ({ args, scope, confirmation }) => {
-		const target = resolveDocument(scope, args, "delete");
+		const target = {
+			...resolveCollection(scope, args.collection, "delete"),
+			id: args.id
+		};
 		const { req } = scope;
 		const { payload } = req;
 		const trash = target.config.trash ?? false;
 		return await withTransaction(req, async () => {
-			const doc = await payload.findByID({
-				collection: target.slug,
-				id: target.id,
-				depth: 0,
-				draft: true,
-				trash: true,
-				overrideAccess: false,
-				disableErrors: true,
-				req
+			const doc = await readDraft(scope, {
+				target,
+				locale: void 0,
+				trash: true
 			});
-			if (!doc) throw new NotFound(req.t);
 			if (doc["deletedAt"]) return errorResult("The document is already in the trash. Emptying the trash is not available.");
 			const stale = staleReadResult(doc, args.expectedUpdatedAt, "The document changed since you read it. Read it again before deleting.");
 			if (stale) return stale;