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

package/dist/schema/pointer.mjs

@@ -1,39 +1,33 @@
-import { blockOf, blockSlugsOf, describeAddressableFields, findBlocksField, findRichTextField, isIndexSegment, joinPath, splitPath, targetOf } from "./walk.mjs";
+import { isIndexSegment, joinPath, splitPath } from "./path.mjs";
+import { blockOf, blockSlugsOf, describeAddressableFields, findBlocksField, findRichTextField, schemaOf } from "./walk.mjs";
+import { SchemaError } from "./errors.mjs";
 import { resolveLexicalPointer } from "./lexical-pointer.mjs";
 //#region src/schema/pointer.ts
 const partMatches = (part, segment) => segment !== void 0 && (part === "*" ? isIndexSegment(segment) : part === segment);
-/**
-* Longest descriptor whose path is fully consumed by the leading segments.
-*/ const longestMatch = (descriptors, segments) => descriptors.map((descriptor) => ({
+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];
-/** Stopping part-way through a descriptor's path means a subtree, not a field. */ const isSubtreePrefix = (descriptors, segments) => descriptors.some((descriptor) => {
+const isSubtreePrefix = (descriptors, segments) => descriptors.some((descriptor) => {
 	const parts = splitPath(descriptor.path);
 	return parts.length > segments.length && segments.every((segment, offset) => {
 		const part = parts[offset];
 		return part !== void 0 && partMatches(part, segment);
 	});
 });
-/**
-* Unlike a descriptor path, the segments carry real indices, so intervening
-* array fields are descended through rather than skipped.
-*/ const valueAtSegments = (data, segments) => segments.reduce((current, segment) => current === null || typeof current !== "object" ? void 0 : current[segment], data);
-/**
-* The stored row decides which block sits at an index, since a blocks field
-* admits many shapes at the same position. A row the document does not have
-* yet takes its slug from the value being added.
-*/ const stepIntoBlock = (at) => {
+const valueAtSegments = (data, segments) => segments.reduce((current, segment) => current === null || typeof current !== "object" ? void 0 : current[segment], data);
+const stepIntoBlock = (at) => {
 	const { addedValue, config, descriptor, rows } = at;
 	const [index, ...remaining] = at.rest;
-	if (!isIndexSegment(index)) throw new Error(`"${descriptor.path}" is an array; "${index}" is not an index.`);
+	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 existing = Array.isArray(rows) && index !== "-" ? rows[Number(index)] : void 0;
 	const slug = existing?.blockType ?? addedValue?.blockType;
-	if (!field || slug === void 0) throw new Error(`Cannot tell which block "${descriptor.path}/${index}" is. Supply a "blockType" on the value, one of: ${field ? blockSlugsOf(field).join(", ") : ""}`);
+	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 Error(`"${slug}" is not allowed at "${descriptor.path}". Allowed: ${blockSlugsOf(field).join(", ")}`);
+	if (!block) throw new SchemaError(`"${slug}" is not allowed at "${descriptor.path}". Allowed: ${blockSlugsOf(field).join(", ")}`);
 	return {
 		blockType: slug,
 		data: existing,
@@ -42,12 +36,11 @@ const partMatches = (part, segment) => segment !== void 0 && (part === "*" ? isI
 	};
 };
 /**
-* The stored document chooses the branch at every blocks element, and is
-* required rather than optional: `/layout/sections/3/modules/1`
-* can only be resolved by reading `blockType` off `sections[3]`, since a blocks
-* field admits many shapes at the same index.
+* The stored document is required because it chooses the branch at every blocks
+* element: `/layout/sections/3/modules/1` can only be resolved by reading
+* `blockType` off `sections[3]`.
 */ const resolveDataPointer = (config, target) => {
-	let fields = targetOf(config, target.ref).flattenedFields;
+	let fields = schemaOf(config, target.ref).flattenedFields;
 	let data = target.doc;
 	let blockType;
 	let segments = splitPath(target.pointer);
@@ -55,14 +48,14 @@ const partMatches = (part, segment) => segment !== void 0 && (part === "*" ? isI
 	let inLexical;
 	while (segments.length > 0) {
 		const descriptors = describeAddressableFields(fields);
-		const match = longestMatch(descriptors, segments);
+		const match = matchPointerSegments(descriptors, segments);
 		if (!match) {
 			if (isSubtreePrefix(descriptors, segments)) return {
 				...blockType === void 0 ? {} : { blockType },
 				fields,
 				prefix: segments.map((segment) => isIndexSegment(segment) ? "*" : segment)
 			};
-			throw new Error(`"${joinPath(segments)}" is not a field here. Available: ${descriptors.map((descriptor) => descriptor.path).join(", ")}`);
+			throw new SchemaError(`"${joinPath(segments)}" is not a field here. Available: ${descriptors.map((descriptor) => descriptor.path).join(", ")}`);
 		}
 		const rest = segments.slice(match.consumed);
 		if (rest.length === 0) return {
@@ -100,7 +93,7 @@ const partMatches = (part, segment) => segment !== void 0 && (part === "*" ? isI
 			segments = step.rest;
 			continue;
 		}
-		if (match.descriptor.type !== "blocks") throw new Error(`"${match.descriptor.path}" is a ${match.descriptor.type} field and has no "${joinPath(rest)}" beneath it.`);
+		if (match.descriptor.type !== "blocks") throw new SchemaError(`"${match.descriptor.path}" is a ${match.descriptor.type} field and has no "${joinPath(rest)}" beneath it.`);
 		const step = stepIntoBlock({
 			addedValue: target.addedValue,
 			descriptor: match.descriptor,

package/dist/schema/shape.mjs

@@ -1,22 +1,19 @@
+import { isPlainObject, ownValue } from "../guards.mjs";
 import { ROOT_PROPERTIES, constrainsFields, lexicalSubSchema, nodeProblems, propertyProblem, rootProblems } from "./lexical.mjs";
-import { blockOf, blockSlugsOf, describeAddressableFields, findBlocksField, findRichTextField, isPlainObject, splitPath } from "./walk.mjs";
+import { splitPath } from "./path.mjs";
+import { ROW_KEYS, blockOf, blockSlugsOf, descriptorsUnder, findBlocksField, findRichTextField } from "./walk.mjs";
 //#region src/schema/shape.ts
-const TOLERATED_VALUE_KEYS = /* @__PURE__ */ new Set([
-	"blockName",
-	"blockType",
-	"id"
-]);
 /**
-* Lexical refuses to hydrate a state whose root holds nothing: `isEmpty` is a
-* node map of one, and the editor throws on it rather than rendering nothing.
-* An empty field is stored as null instead, so this is only ever reached by
-* emptying one that was there.
+* Lexical throws when it hydrates a state whose root holds nothing. An empty
+* field is stored as null, so this is reached only by emptying one that had
+* content.
 */ const EMPTY_ROOT = "an editor state needs at least one node. Clear the field with null instead.";
 const quoted = (properties) => properties.map((property) => `"${property}"`).join(", ");
-/**
-* A node with nothing to declare, and one whose sub-fields cannot be named at a
-* position, are both left alone.
-*/ const checkNodeFields = (scope, field, node) => {
+const refusedSlug = (slug) => {
+	if (slug === void 0) return `a row needs a "blockType"`;
+	return typeof slug === "string" ? `"${slug}" is not allowed here` : `"blockType" must be a string naming a block`;
+};
+const checkNodeFields = (scope, field, node) => {
 	const sub = lexicalSubSchema(field, node.type);
 	if (!sub) return;
 	const data = node.fields;
@@ -39,7 +36,7 @@ const quoted = (properties) => properties.map((property) => `"${property}"`).joi
 	const slug = data["blockType"];
 	const block = typeof slug === "string" ? blockOf(scope.config, sub.blocksField, slug) : void 0;
 	if (!block) {
-		scope.problems.push(`${scope.pointer}/fields: "${String(slug)}" is not allowed here. Allowed: ${blockSlugsOf(sub.blocksField).join(", ")}`);
+		scope.problems.push(`${scope.pointer}/fields: ${refusedSlug(slug)}. Allowed: ${blockSlugsOf(sub.blocksField).join(", ")}`);
 		return;
 	}
 	checkValue({
@@ -47,28 +44,10 @@ const quoted = (properties) => properties.map((property) => `"${property}"`).joi
 		fields: block.flattenedFields
 	}, data);
 };
-/**
-* An absent property is already reported as missing. Anything else present is
-* checked, not just a string: Lexical stores a heading tag of 3 as readily as
-* one of "h3".
-*/ const checkNarrowedProperty = (scope, at, value) => {
+const checkNarrowedProperty = (scope, at, value) => {
 	if (value !== void 0 && !(typeof value === "string" && at.values.includes(value))) scope.problems.push(`${at.pointer}: ${JSON.stringify(value)} is not available for a "${at.type}" node in this field's editor. Allowed: ${at.values.join(", ")}`);
 };
-/**
-* One node, wherever it came from. `pointer` addresses the node itself, so a
-* node written at a position and a node written inside a whole editor state
-* are held to the same rules and report them the same way.
-*
-* Payload does not check any of this: the Lexical validator runs node
-* validations only for the few node types that register one, so a `heading`
-* inside a field whose editor has no heading feature is stored without
-* complaint and only fails later, at render or when the document is reopened
-* in the admin editor. A key a node's fields do not declare is dropped just as
-* silently. The same holds one level down, for the node properties a feature
-* narrows: an `h3` in an editor restricted to `h4` is stored as readily as an
-* `h4`, and a node written without the properties its class hydrates from is
-* stored and then throws when the editor opens it.
-*/ const checkNode = (scope, editor, node, pointer) => {
+const checkNode = (scope, editor, node, pointer) => {
 	if (!isPlainObject(node) || typeof node["type"] !== "string") {
 		scope.problems.push(`${pointer}: every node needs a "type".`);
 		return;
@@ -81,7 +60,7 @@ const quoted = (properties) => properties.map((property) => `"${property}"`).joi
 	const problems = nodeProblems(node);
 	if (problems.missing.length > 0) scope.problems.push(`${pointer}: a "${type}" node is missing ${quoted(problems.missing)}. Write nodes as Lexical serializes them.`);
 	for (const problem of problems.rejected) scope.problems.push(`${pointer}/${problem.property}: a "${type}" node needs ${problem.needs} here.`);
-	for (const [property, values] of Object.entries(editor.nodeOptions?.[type] ?? {})) checkNarrowedProperty(scope, {
+	for (const [property, values] of Object.entries(ownValue(editor.nodeOptions, type) ?? {})) checkNarrowedProperty(scope, {
 		pointer: `${pointer}/${property}`,
 		type,
 		values
@@ -95,7 +74,7 @@ const quoted = (properties) => properties.map((property) => `"${property}"`).joi
 	});
 	checkNodes(scope, editor, node["children"], `${pointer}/children`);
 };
-/** `pointer` addresses the list. A node holding none is left alone. */ const checkNodes = (scope, editor, nodes, pointer) => {
+const checkNodes = (scope, editor, nodes, pointer) => {
 	if (!Array.isArray(nodes)) return;
 	nodes.forEach((node, index) => {
 		checkNode(scope, editor, node, `${pointer}/${String(index)}`);
@@ -114,34 +93,26 @@ const checkRichText = (scope, editor, value) => {
 	if (Array.isArray(root["children"]) && root["children"].length === 0) scope.problems.push(`${scope.pointer}/root/children: ${EMPTY_ROOT}`);
 	checkNodes(scope, editor, root["children"], `${scope.pointer}/root/children`);
 };
-/**
-* `type` decides how every other property on a node is read, so replacing it
-* alone would leave a heading shaped like a text node. Everything else is held
-* to the constraint the node walk holds it to and nothing more, since a
-* feature may put any property on a node.
-*/ const checkNodeProperty = (scope, editor, position, value) => {
+const checkNodeProperty = (scope, editor, position, value) => {
 	const { nodeType: type, property } = position;
 	if (property === "type") {
 		scope.problems.push(`${scope.pointer}: a node's "type" cannot be replaced on its own. Replace the whole node.`);
 		return;
 	}
-	if (position.isRoot && !(property in ROOT_PROPERTIES)) {
+	if (position.isRoot && !Object.hasOwn(ROOT_PROPERTIES, property)) {
 		scope.problems.push(`${scope.pointer}: no such property on the root node. Available: ${Object.keys(ROOT_PROPERTIES).join(", ")}`);
 		return;
 	}
 	const problem = propertyProblem(type, property, value);
 	if (problem) scope.problems.push(`${scope.pointer}: a "${type}" node needs ${problem.needs} here.`);
-	const values = editor.nodeOptions?.[type]?.[property];
+	const values = ownValue(ownValue(editor.nodeOptions, type), property);
 	if (values) checkNarrowedProperty(scope, {
 		pointer: scope.pointer,
 		type,
 		values
 	}, value);
 };
-/**
-* A value written at a position inside an editor state rather than as the
-* whole state.
-*/ const checkLexicalWrite = (scope, position, value) => {
+const checkLexicalWrite = (scope, position, value) => {
 	const editor = {
 		allowed: position.descriptor.nodes ?? [],
 		field: position.field,
@@ -193,7 +164,7 @@ const checkLeafValue = (scope, descriptor, value) => {
 		const slug = isPlainObject(row) ? row["blockType"] : void 0;
 		const block = typeof slug === "string" ? blockOf(scope.config, field, slug) : void 0;
 		if (!block) {
-			scope.problems.push(`${scope.pointer}/${String(index)}: "${String(slug)}" is not allowed here. Allowed: ${blockSlugsOf(field).join(", ")}`);
+			scope.problems.push(`${scope.pointer}/${String(index)}: ${refusedSlug(slug)}. Allowed: ${blockSlugsOf(field).join(", ")}`);
 			return;
 		}
 		checkValue({
@@ -204,27 +175,12 @@ const checkLeafValue = (scope, descriptor, value) => {
 		}, row);
 	});
 };
-/**
-* Reports every shape problem rather than the first.
-*
-* Shape only: unknown field names, unknown block slugs, read-only fields, and
-* rich text nodes or node properties the field's editor cannot produce.
-* Required-ness, row counts, lengths, enum membership and relationship
-* existence stay with Payload, which already checks them and reports them per
-* field. Without this pass a misspelled field inside a new block would be
-* stripped in silence.
-*/ const checkValue = (scope, value) => {
+const checkValue = (scope, value) => {
 	if (!isPlainObject(value)) return;
 	const prefixParts = scope.prefix;
-	const relative = describeAddressableFields(scope.fields).flatMap((descriptor) => {
-		const parts = splitPath(descriptor.path);
-		return prefixParts.every((part, offset) => part === parts[offset]) ? [{
-			descriptor,
-			parts: parts.slice(prefixParts.length)
-		}] : [];
-	});
+	const relative = descriptorsUnder(scope.fields, prefixParts);
 	for (const [key, entry] of Object.entries(value)) {
-		if (TOLERATED_VALUE_KEYS.has(key)) continue;
+		if (ROW_KEYS.has(key)) continue;
 		const candidates = relative.filter(({ parts }) => parts[0] === key);
 		const pointer = `${scope.pointer}/${key}`;
 		if (candidates.length === 0) {
@@ -264,9 +220,7 @@ const checkLeafValue = (scope, descriptor, value) => {
 		}, entry);
 	}
 };
-/**
-* Shape problems with a value about to be written at a resolved pointer.
-*/ const validateWriteValue = (config, target, value) => {
+const validateWriteValue = (config, target, value) => {
 	const problems = [];
 	const scope = {
 		config,

package/dist/schema/walk.mjs

@@ -1,4 +1,5 @@
 import { allowedNodeTypes, nodeOptions } from "./lexical.mjs";
+import { joinPath, splitPath } from "./path.mjs";
 import { translateAny } from "../i18n.mjs";
 import { fieldIsHiddenOrDisabled, fieldIsVirtual } from "payload/shared";
 //#region src/schema/walk.ts
@@ -9,21 +10,21 @@ const RESERVED_FIELD_NAMES = /* @__PURE__ */ new Set([
 	"id",
 	"updatedAt"
 ]);
-const JSON_POINTER_PATTERN = /^(\/([^~/]|~[01])*)*$/;
-/** No segments is the root pointer, `""`. */ const joinPath = (parts) => parts.map((part) => `/${part.replace(/~/g, "~0").replace(/\//g, "~1")}`).join("");
-/** Unescapes `~1` and `~0`. The root pointer yields no segments. */ const splitPath = (path) => path.split("/").slice(1).map((segment) => segment.replace(/~1/g, "/").replace(/~0/g, "~"));
-/** `-` included, since RFC 6901 reads it as the position after the last. */ const isIndexSegment = (segment) => segment === "-" || /^\d+$/.test(segment);
-const isPlainObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 /**
-* A path Payload reports on a validation error (`layout.0.title`) as a JSON
-* 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(".")) : "";
-/** On a flattened field, whichever of `blockReferences` and `blocks` was declared. */ const blockSlugsOf = (field) => [...new Set((field.blockReferences ?? field.blocks).map((block) => typeof block === "string" ? block : block.slug))];
+* The keys a row carries beside its fields.
+*/ const ROW_KEYS = /* @__PURE__ */ new Set([
+	"blockName",
+	"blockType",
+	"id"
+]);
+/**
+* On a flattened field, whichever of `blockReferences` and `blocks` was
+* declared.
+*/ const blockSlugsOf = (field) => [...new Set((field.blockReferences ?? field.blocks).map((block) => typeof block === "string" ? block : block.slug))];
 /**
 * An inlined definition wins over the registry (`config.blocks`). A block's own
 * fields are identical wherever it appears, but the blocks its children accept
-* are not, so an inline definition has to be read at its position.
+* are not, so an inline definition must be read at its position.
 */ const blockOf = (config, field, slug) => {
 	const declared = field.blockReferences ?? field.blocks;
 	const inline = declared.find((block) => typeof block !== "string" && block.slug === slug);
@@ -32,9 +33,9 @@ const isPlainObject = (value) => typeof value === "object" && value !== null &&
 };
 /**
 * Payload's `fieldIsHiddenOrDisabled` reads `hidden` and `admin.disabled`, not
-* `admin.hidden`, which is what its own upload base fields carry.
+* `admin.hidden`, which its own upload base fields carry.
 */ const isAdminHidden = (field) => "admin" in field && field.admin.hidden === true;
-/** A field kept out of the admin panel is kept out of the MCP surface too. */ const isSkipped = (field) => !("name" in field) || field.type === "join" || RESERVED_FIELD_NAMES.has(field.name) || fieldIsVirtual(field) || isAdminHidden(field) || fieldIsHiddenOrDisabled(field);
+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 describeBase = (field, { path, readOnly, translate }) => {
 	const description = translate("admin" in field ? field.admin.description : void 0);
@@ -68,28 +69,15 @@ const withRows = (descriptor, field) => ({
 	...field.minRows === void 0 ? {} : { minRows: field.minRows },
 	...field.maxRows === void 0 ? {} : { maxRows: field.maxRows }
 });
+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;
 /**
-* A container describes a position rather than a value, so everything resolving
-* a path to something writable skips it. Only {@link nodeDescriber} reports one,
-* to carry what the container itself declares.
-*/ const isContainer = (descriptor) => descriptor.type === "array" || descriptor.type === "group" || descriptor.type === "tab";
-/**
-* Whether a container declares anything a client could not infer from the
-* fields beneath it. A group that exists only to nest is not worth reporting.
-*/ const isInformative = (descriptor) => descriptor.description !== void 0 || descriptor.required === true || descriptor.localized === true;
-/**
-* Flattens a field list into descriptors addressed relative to the node.
-*
-* The input is Payload's own flattened shape, so the admin-only constructs
-* (unnamed tabs and groups, `row`, `collapsible`, `ui`) are already gone. Named
-* tabs, groups and arrays contribute a path segment, and are described in their
-* own right when they declare something of their own: an array always, since
-* its row counts live nowhere else, a group or tab only when it carries a
-* description or a constraint. The walk stops at every blocks field and names
-* the slugs, which keeps a node proportional to the number of blocks it allows
-* rather than to the size of their definitions.
-*
-* Omitting `translate` costs language selection, never the description itself.
+* 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 walk = (current, prefix, parentReadOnly) => current.flatMap((field) => {
 		if (isSkipped(field)) return [];
@@ -114,10 +102,20 @@ const withRows = (descriptor, field) => ({
 	return walk(fields, [], false);
 };
 /**
-* The descriptors that address a value, which is what every walk resolving a
-* path against a document needs. A container describes a position rather than
-* a value, so only {@link nodeDescriber} reports one.
+* 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.
 */ const describeAddressableFields = (fields) => describeFields(fields).filter((descriptor) => !isContainer(descriptor));
+/**
+* The addressable descriptors under `prefix`, with their paths split relative
+* to it.
+*/ const descriptorsUnder = (fields, prefix) => describeAddressableFields(fields).flatMap((descriptor) => {
+	const parts = splitPath(descriptor.path);
+	return prefix.every((part, offset) => part === parts[offset]) ? [{
+		descriptor,
+		parts: parts.slice(prefix.length)
+	}] : [];
+});
 const findFieldAt = (fields, path, type) => {
 	for (const field of fields) {
 		if (!("name" in field) || field.name !== path[0]) continue;
@@ -128,18 +126,18 @@ const findFieldAt = (fields, path, type) => {
 };
 const findBlocksField = (fields, path) => findFieldAt(fields, path, "blocks");
 /**
-* Locates the rich text field that a resolved descriptor path refers to, so
-* its editor can be introspected for the fields its nodes carry.
+* 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");
 /**
-* Looks up the sanitized config for a collection or global, as a
-* {@link SchemaTarget}. Throws on an unknown slug rather than returning
-* undefined, because a reference reaching here has already been checked against
-* the key's capabilities and a miss means the config changed underneath it.
-*/ const targetOf = (config, ref) => {
+* Looks up the sanitized config for a collection or global as an
+* {@link EntitySchema}. Throws on an unknown slug instead of returning
+* undefined: a reference reaching here was already checked against the key's
+* capabilities, so a miss means the config changed underneath it.
+*/ const schemaOf = (config, ref) => {
 	const found = ref.kind === "collection" ? config.collections.find((candidate) => candidate.slug === ref.slug) : config.globals.find((candidate) => candidate.slug === ref.slug);
 	if (!found) throw new Error(`Unknown ${ref.kind} "${ref.slug}".`);
 	return found;
 };
 //#endregion
-export { JSON_POINTER_PATTERN, RESERVED_FIELD_NAMES, blockOf, blockSlugsOf, describeAddressableFields, describeFields, findBlocksField, findRichTextField, isIndexSegment, isPlainObject, joinPath, pointerFromPayloadPath, splitPath, targetOf };
+export { RESERVED_FIELD_NAMES, ROW_KEYS, blockOf, blockSlugsOf, describeAddressableFields, describeFields, descriptorsUnder, findBlocksField, findRichTextField, isAdminHidden, schemaOf };

package/dist/tools/builtin.mjs

@@ -9,10 +9,10 @@ import { publishDocument } from "./publish-document.mjs";
 import { validateDocument } from "./validate-document.mjs";
 //#region src/tools/builtin.ts
 /**
-* The builtin tools, in registration order. Fixed: adding a collection, block
-* or field never changes the surface. They differ from a custom tool only in
-* `isEnabled`, which derives from the key's capabilities rather than a
-* checkbox of their own.
+* The builtin tools, in registration order. The set is fixed, so adding a
+* collection, block or field never changes it. They differ from custom tools
+* only in `isEnabled`, which derives from the key's capabilities instead of a
+* checkbox of its own.
 */ const BUILTIN_TOOLS = [
 	listCapabilities,
 	describeSchema,

package/dist/tools/create-document.mjs

@@ -1,29 +1,32 @@
+import { defineMcpxTool } from "../define-tool.mjs";
 import { errorResult, jsonResult } from "../result.mjs";
 import { validateWriteValue } from "../schema/shape.mjs";
 import "../schema/index.mjs";
-import { draftSentence, localeOf, localeShape, patchOnlySlugs, readTarget, slugEnum, slugsFor } from "./shared.mjs";
-import { resolveTarget } from "./target.mjs";
-import { defineMcpxTool } from "../types.mjs";
-import { stripRowIds } from "../write/patch.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 { stripRowIds } from "../write/row-ids.mjs";
+import { APIError } from "payload";
 import { z } from "zod";
 //#region src/tools/create-document.ts
-/** Names the writable slugs this tool leaves out, so the gap reads as intent. */ const uploadSentence = (scope) => {
+const uploadSentence = (scope) => {
 	const slugs = patchOnlySlugs(scope);
-	return slugs.length === 0 ? "" : `\n\nLeft out of "collection" on purpose: ${slugs.join(", ")}. Those documents are files, and no tool here carries one. Upload the file in the admin panel, then edit its fields with patchDocument.`;
+	return slugs.length === 0 ? "" : ` Documents in ${slugs.join(", ")} are files and cannot be created here. Upload the file in the admin panel, then edit its fields with patchDocument.`;
 };
-const DESCRIPTION = (scope) => `Creates a new document from a minimal seed. Only the fields describeSchema lists may appear in "data"; unknown keys are refused with the valid siblings, and "id" is Payload's to assign. The document may be incomplete: the response lists "publishBlockers", which patchDocument can then work through, and "publishBlockersUnavailable" when that check itself failed. Use this when no document exists yet; prefer patching an existing draft otherwise.
+const DESCRIPTION = (scope) => `Creates a document in a collection. Use it only when the document does not exist yet. Returns "id", "status", "updatedAt" and, if any, "publishBlockers". "publishBlockersUnavailable" means that check failed. "data" may leave required fields empty for patchDocument to fill later, except in a collection whose listCapabilities entry has "draftValidation" true or "drafts" false. A field describeSchema does not list is refused, and "id" is always assigned.
 
-${draftSentence(scope)}${uploadSentence(scope)}`;
+${liveWriteSentence(scope, "create")}${uploadSentence(scope)}`;
 /**
-* Collection-only, because a global always exists, and never reaches an upload
-* collection, because a create there would have to carry the file.
+* 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.
 *
-* The seed is checked against the collection's fields before the create, so an
-* unknown key is refused with its valid siblings rather than dropped. Row ids
-* in the seed are stripped and a top-level `id` is refused outright. The new
-* document is re-read privileged afterwards to collect publish blockers, which
-* is why an incomplete seed still succeeds and comes back with a checklist.
+* The seed is checked against the collection's fields first, so an unknown key
+* is refused along with its valid siblings. Row ids in the seed are stripped
+* and a top-level `id` is refused. The new document is re-read privileged to
+* collect publish blockers, so an incomplete seed still succeeds and returns a
+* checklist.
 */ const createDocument = defineMcpxTool({
 	name: "createDocument",
 	description: DESCRIPTION,
@@ -35,18 +38,23 @@ ${draftSentence(scope)}${uploadSentence(scope)}`;
 	},
 	isEnabled: (scope) => slugsFor(scope, "create").collections.length > 0,
 	inputSchema: (scope) => ({
-		collection: slugEnum(slugsFor(scope, "create").collections).describe("Collection to create the document in."),
+		collection: slugEnum(slugsFor(scope, "create").collections),
 		...localeShape(scope, {
 			required: true,
-			description: "Locale the localized fields of the seed belong to."
+			description: "Locale of the localized fields in \"data\"."
 		}),
-		data: z.record(z.string(), z.unknown()).describe("Initial field values, as describeSchema lists them.")
+		data: z.record(z.string(), z.unknown()).describe("Field values by name, e.g. {\"title\":\"Home\",\"slug\":\"home\"}."),
+		...fileShape(scope, (slugs) => `Required in ${slugs}. The call returns an "upload" for the bytes instead of writing.`)
 	}),
 	handler: async ({ args, scope }) => {
-		const target = resolveTarget(scope, { collection: args.collection }, "create");
+		const target = resolveEntity(scope, { collection: args.collection }, "create");
+		if (target.kind === "global") throw new Error("createDocument resolved a global.");
 		const { payload } = scope.req;
 		const locale = localeOf(scope, args.locale);
-		if ("id" in args.data) return errorResult("Nothing was created.", { problems: ["/id: Payload assigns the id; it cannot be supplied."] });
+		const { file } = args;
+		if (file !== void 0) assertAcceptsFile(scope, target, file);
+		else if (scope.exposure.collections.some((entity) => entity.slug === target.slug && entity.isUpload)) throw new APIError(`"${target.slug}" stores files, so "file" is required.`, 400);
+		if (Object.hasOwn(args.data, "id")) return errorResult("Nothing was created.", { problems: ["/id: Payload assigns the id; it cannot be supplied."] });
 		const problems = validateWriteValue(payload.config, {
 			pointer: "",
 			resolution: {
@@ -55,6 +63,21 @@ ${draftSentence(scope)}${uploadSentence(scope)}`;
 			}
 		}, args.data);
 		if (problems.length > 0) return errorResult("Nothing was created.", { problems });
+		const bytes = uploadedFile(scope.req);
+		if (file !== void 0) {
+			const refusal = await fileWriteRefusal(scope, {
+				entity: target,
+				data: args.data
+			});
+			if (refusal) return refusal;
+			if (!bytes) return await uploadHandoff(scope, {
+				tool: "createDocument",
+				args: {
+					...args,
+					file
+				}
+			});
+		}
 		const created = await payload.create({
 			collection: args.collection,
 			data: stripRowIds(args.data),
@@ -62,11 +85,14 @@ ${draftSentence(scope)}${uploadSentence(scope)}`;
 			draft: true,
 			overrideAccess: false,
 			req: scope.req,
-			...locale === void 0 ? {} : { locale }
+			...locale === void 0 ? {} : { locale },
+			...bytes === void 0 ? {} : { file: bytes }
 		});
-		const saved = await readTarget(scope, {
-			target,
-			id: created["id"],
+		const saved = await readDraft(scope, {
+			target: {
+				...target,
+				id: created["id"]
+			},
 			locale,
 			privileged: true
 		});