@abinnovision/payloadcms-mcpx 1.0.0-beta.14 → 1.0.0-beta.15

package/README.md

@@ -222,6 +222,19 @@ Rules the tools enforce and explain in their own descriptions:
   answers `{ "heading": { "tag": ["h4"] } }`, and a write carrying any other
   heading tag is refused. Lexical stores whatever tag it is given, so this is
   the only place the restriction is checked.
+- A Lexical node must be written the way Lexical serializes it, and carry the
+  values Lexical would have written. The admin editor rehydrates nodes through
+  their classes, so a list item whose `indent` is absent, `null` or `"0"` throws
+  when the document is opened, and a heading whose `tag` is `3` comes back
+  untagged, none of which Payload notices on write. A write breaking either is
+  refused, and the message names the property and what belongs there.
+- Where Payload states the shape itself, that statement is what is enforced: its
+  `outputSchema` declares `version` required on every node, and gives the root
+  exactly `children`, `direction`, `format`, `indent`, `type` and `version`, so
+  an unknown property on the root is refused too. Payload declares nothing per
+  node type, so the rest is measured against the node classes
+  `@payloadcms/richtext-lexical` ships. Both halves are pinned by
+  `src/schema/lexical.spec.ts` rather than assumed.
 - Field and collection `admin.description` values are included in
   `describeSchema` and `listCapabilities`, so intent written for the admin
   panel reaches the client. A locale-keyed record is resolved to one string for

package/dist/schema/index.mjs

@@ -1,6 +1,6 @@
-import { allowedNodeTypes, lexicalSubSchema, nodeOptions, subSchemaNodeTypes } from "./lexical.mjs";
+import { REQUIRED_NODE_PROPERTIES, ROOT_PROPERTIES, allowedNodeTypes, constrainsFields, lexicalSubSchema, nodeOptions, nodeProblems, rootProblems, subSchemaNodeTypes } from "./lexical.mjs";
 import { JSON_POINTER_PATTERN, RESERVED_FIELD_NAMES, blockOf, blockSlugsOf, describeAddressableFields, describeFields, findBlocksField, findRichTextField, joinPath, pointerFromPayloadPath, splitPath, targetOf } from "./walk.mjs";
 import { nodeDescriber, reachableSchemaPaths } from "./describe.mjs";
 import { resolveDataPointer } from "./pointer.mjs";
 import { validateWriteValue } from "./shape.mjs";
-export { JSON_POINTER_PATTERN, RESERVED_FIELD_NAMES, allowedNodeTypes, blockOf, blockSlugsOf, describeAddressableFields, describeFields, findBlocksField, findRichTextField, joinPath, lexicalSubSchema, nodeDescriber, nodeOptions, pointerFromPayloadPath, reachableSchemaPaths, resolveDataPointer, splitPath, subSchemaNodeTypes, targetOf, validateWriteValue };
+export { JSON_POINTER_PATTERN, REQUIRED_NODE_PROPERTIES, RESERVED_FIELD_NAMES, ROOT_PROPERTIES, allowedNodeTypes, blockOf, blockSlugsOf, constrainsFields, describeAddressableFields, describeFields, findBlocksField, findRichTextField, joinPath, lexicalSubSchema, nodeDescriber, nodeOptions, nodeProblems, pointerFromPayloadPath, reachableSchemaPaths, resolveDataPointer, rootProblems, splitPath, subSchemaNodeTypes, targetOf, validateWriteValue };

package/dist/schema/lexical.mjs

@@ -53,6 +53,158 @@ const lexicalSubSchema = (field, nodeType) => {
 };
 /** In the order their features registered them. */ const subSchemaNodeTypes = (field) => [...featuresOf(field)?.getSubFields?.keys() ?? []].filter((nodeType) => lexicalSubSchema(field, nodeType) !== void 0);
 /**
+* `direction` carries Payload's own declaration for it, `oneOf` the two
+* directions or null, rather than a looser "string or null".
+*/ const KINDS = {
+	array: {
+		accepts: (value) => Array.isArray(value),
+		needs: "an array"
+	},
+	direction: {
+		accepts: (value) => value === null || value === "ltr" || value === "rtl",
+		needs: "\"ltr\", \"rtl\" or null"
+	},
+	number: {
+		accepts: (value) => typeof value === "number",
+		needs: "a number"
+	},
+	object: {
+		accepts: (value) => typeof value === "object" && value !== null && !Array.isArray(value),
+		needs: "an object"
+	},
+	optionalObject: {
+		accepts: (value) => value === null || typeof value === "object" && !Array.isArray(value),
+		needs: "an object or null"
+	},
+	string: {
+		accepts: (value) => typeof value === "string",
+		needs: "a string"
+	}
+};
+const accepts = (constraint, value) => typeof constraint === "string" ? KINDS[constraint].accepts(value) : value === constraint.is;
+const needs = (constraint) => typeof constraint === "string" ? KINDS[constraint].needs : JSON.stringify(constraint.is);
+const ELEMENT_PROPERTIES = {
+	children: "array",
+	direction: "direction",
+	indent: "number"
+};
+/** A text node and everything built on one. */ const TEXT_PROPERTIES = {
+	detail: "number",
+	format: "number",
+	mode: "string",
+	style: "string",
+	text: "string"
+};
+/**
+* Carried by every node, whatever its type.
+*
+* Aligned with Payload rather than measured: its `outputSchema` declares `type`
+* and `version` required for every node in the tree, and that declaration is
+* what types the field in `payload-types.ts`. Lexical itself hydrates a node
+* without a `version`, or with the wrong kind of one, unchanged - but a
+* consumer reading the document through the generated types has been promised
+* an integer, and `BlockNode.importJSON` migrates on it.
+*/ const UNIVERSAL_PROPERTIES = { version: "number" };
+/**
+* The root, as Payload declares it and as an editor exports it: these six
+* properties, these kinds, and nothing else.
+*/ const ROOT_PROPERTIES = {
+	children: "array",
+	direction: "direction",
+	format: "string",
+	indent: "number",
+	type: "string",
+	version: "number"
+};
+/**
+* What a serialized node must carry beyond {@link UNIVERSAL_PROPERTIES}, keyed
+* by node type.
+*
+* Payload stores an editor state without hydrating it, so a node written
+* without these, or with the wrong kind of value, is accepted and only fails
+* later, in the admin editor. Payload declares nothing per node type, so this
+* table is measured instead: an entry belongs here only if breaking it makes
+* Lexical throw, or changes what the editor reads back. An element's `format`
+* and a paragraph's text defaults are absent for that reason.
+* `lexical.spec.ts` holds every entry to the rule against the node classes
+* `@payloadcms/richtext-lexical` ships, so extend that test first.
+*
+* A node type with no entry is checked for the universal properties only.
+* Guessing at the requirements of a project's own nodes would reject content
+* that works.
+*/ const REQUIRED_NODE_PROPERTIES = {
+	autolink: {
+		...ELEMENT_PROPERTIES,
+		fields: "object"
+	},
+	block: { fields: "object" },
+	heading: {
+		...ELEMENT_PROPERTIES,
+		tag: "string"
+	},
+	inlineBlock: { fields: "object" },
+	link: {
+		...ELEMENT_PROPERTIES,
+		fields: "object"
+	},
+	list: {
+		...ELEMENT_PROPERTIES,
+		listType: "string",
+		start: "number"
+	},
+	listitem: {
+		...ELEMENT_PROPERTIES,
+		value: "number"
+	},
+	paragraph: ELEMENT_PROPERTIES,
+	quote: ELEMENT_PROPERTIES,
+	relationship: {
+		relationTo: "string",
+		value: "number"
+	},
+	tab: {
+		...TEXT_PROPERTIES,
+		detail: { is: 2 },
+		text: { is: "	" }
+	},
+	text: TEXT_PROPERTIES,
+	upload: {
+		fields: "optionalObject",
+		relationTo: "string",
+		value: "number"
+	}
+};
+/**
+* Whether the table already says what a node type's `fields` has to be, so the
+* sub-field walk does not report the same problem a second time.
+*/ const constrainsFields = (type) => "fields" in (REQUIRED_NODE_PROPERTIES[type] ?? {});
+/** Present but `null` counts as present: `direction` is serialized that way. */ const check = (node, constraints) => {
+	const problems = {
+		missing: [],
+		rejected: []
+	};
+	for (const [property, constraint] of Object.entries(constraints)) if (!(property in node)) problems.missing.push(property);
+	else if (!accepts(constraint, node[property])) problems.rejected.push({
+		needs: needs(constraint),
+		property
+	});
+	problems.missing.sort();
+	problems.rejected.sort((left, right) => left.property.localeCompare(right.property));
+	return problems;
+};
+const nodeProblems = (node) => check(node, {
+	...UNIVERSAL_PROPERTIES,
+	...REQUIRED_NODE_PROPERTIES[node["type"]] ?? {}
+});
+/**
+* The root is the one node Payload describes itself, down to refusing an
+* unknown property, so it is checked against that description rather than
+* against the walk's table.
+*/ const rootProblems = (root) => ({
+	...check(root, ROOT_PROPERTIES),
+	unexpected: Object.keys(root).filter((property) => !(property in ROOT_PROPERTIES))
+});
+/**
 * Only properties a feature narrows and Lexical does not check on its own
 * belong here. Everything else a feature restricts is already visible: a
 * link's targets through its sub-schema, a block node's choices through the
@@ -95,4 +247,4 @@ const stringList = (value) => Array.isArray(value) && value.every((entry) => typ
 	return entries.length > 0 ? Object.fromEntries(entries) : void 0;
 };
 //#endregion
-export { allowedNodeTypes, lexicalSubSchema, nodeOptions, subSchemaNodeTypes };
+export { REQUIRED_NODE_PROPERTIES, ROOT_PROPERTIES, allowedNodeTypes, constrainsFields, lexicalSubSchema, nodeOptions, nodeProblems, rootProblems, subSchemaNodeTypes };

package/dist/schema/shape.mjs

@@ -1,4 +1,4 @@
-import { lexicalSubSchema } from "./lexical.mjs";
+import { ROOT_PROPERTIES, constrainsFields, lexicalSubSchema, nodeProblems, rootProblems } from "./lexical.mjs";
 import { blockOf, blockSlugsOf, describeAddressableFields, findBlocksField, findRichTextField, splitPath } from "./walk.mjs";
 //#region src/schema/shape.ts
 const TOLERATED_VALUE_KEYS = /* @__PURE__ */ new Set([
@@ -7,6 +7,7 @@ const TOLERATED_VALUE_KEYS = /* @__PURE__ */ new Set([
 	"id"
 ]);
 const isPlainObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+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.
@@ -15,7 +16,7 @@ const isPlainObject = (value) => typeof value === "object" && value !== null &&
 	if (!sub) return;
 	const data = node.fields;
 	if (!isPlainObject(data)) {
-		scope.problems.push(`${scope.pointer}: a "${node.type}" node carries a "fields" object.`);
+		if (!constrainsFields(node.type)) scope.problems.push(`${scope.pointer}: a "${node.type}" node carries a "fields" object.`);
 		return;
 	}
 	const nested = {
@@ -48,12 +49,19 @@ const isPlainObject = (value) => typeof value === "object" && value !== null &&
 * 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`.
+* 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 checkRichText = (scope, editor, value) => {
 	if (!isPlainObject(value) || !isPlainObject(value["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.`);
+	for (const property of unexpected) scope.problems.push(`${scope.pointer}/root/${property}: no such property on the root node. Available: ${Object.keys(ROOT_PROPERTIES).join(", ")}`);
 	const walk = (nodes, pointer) => {
 		if (!Array.isArray(nodes)) return;
 		nodes.forEach((node, index) => {
@@ -66,9 +74,12 @@ const isPlainObject = (value) => typeof value === "object" && value !== null &&
 				scope.problems.push(`${at}: "${node["type"]}" is not available in this field's editor. Allowed: ${editor.allowed.join(", ")}`);
 				return;
 			}
+			const problems = nodeProblems(node);
+			if (problems.missing.length > 0) scope.problems.push(`${at}: a "${node["type"]}" node is missing ${quoted(problems.missing)}. Write nodes as Lexical serializes them.`);
+			for (const problem of problems.rejected) scope.problems.push(`${at}/${problem.property}: a "${node["type"]}" node needs ${problem.needs} here.`);
 			for (const [property, values] of Object.entries(editor.nodeOptions?.[node["type"]] ?? {})) {
 				const value = node[property];
-				if (typeof value === "string" && !values.includes(value)) scope.problems.push(`${at}/${property}: "${value}" is not available for a "${node["type"]}" node in this field's editor. Allowed: ${values.join(", ")}`);
+				if (value !== void 0 && !(typeof value === "string" && values.includes(value))) scope.problems.push(`${at}/${property}: ${JSON.stringify(value)} is not available for a "${node["type"]}" node in this field's editor. Allowed: ${values.join(", ")}`);
 			}
 			if (editor.field) checkNodeFields({
 				...scope,
@@ -80,7 +91,7 @@ const isPlainObject = (value) => typeof value === "object" && value !== null &&
 			walk(node["children"], `${at}/children`);
 		});
 	};
-	walk(value["root"]["children"], `${scope.pointer}/root/children`);
+	walk(root["children"], `${scope.pointer}/root/children`);
 };
 const checkLeafValue = (scope, descriptor, value) => {
 	if (descriptor.readOnly) {

package/dist/tools/describe-schema.mjs

@@ -22,6 +22,8 @@ Call it with no "paths" to get a collection's own fields. Every "blocks" field s
 
 A "richText" field stops there too. It lists the Lexical node types it accepts in "nodes", and "next" carries a path for every node type that holds fields of its own: "/content/link" for a link node, "/content/block/callout" and "/content/inlineBlock/badge" for the block nodes. Descend to get the real field list instead of guessing what a node carries. Upload nodes are not addressable, because their fields depend on the collection the node points at.
 
+Write each Lexical node the way Lexical serializes it, with every property its type carries rather than a trimmed subset, and with the value Lexical would have written there. Every node needs a "version"; the root takes exactly "children", "direction", "format", "indent", "type" and "version" and refuses anything else; each node type adds its own on top. The admin editor rehydrates nodes through their classes, so a list item whose "indent" is missing, null or a string is stored and then throws on open, and a heading whose "tag" is a number is stored untagged. A write naming a property means exactly that.
+
 Paths here use the same JSON Pointer syntax as getDocument and patchDocument, and are already resolved through anything that does not nest in the stored document. The difference is only what stands in an element position: a path names an array element "*" and a block by its slug, where a pointer into a document carries a 0-based index. So "/items/*/title" is written at "/items/0/title", and "/layout/sections/hero" at "/layout/sections/0".
 
 Fields Payload maintains (id, _status, createdAt, updatedAt) are never listed and cannot be written. Fields marked readOnly are listed but refused on write.`,

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@abinnovision/payloadcms-mcpx",
-  "version": "1.0.0-beta.14",
+  "version": "1.0.0-beta.15",
   "description": "Payload CMS plugin exposing a fixed, schema-aware MCP tool surface with draft-only writes and per-API-key capabilities.",
   "keywords": [
     "payload",