@abinnovision/payloadcms-mcpx 1.0.0-beta.16 → 1.0.0-beta.17

package/README.md

@@ -228,6 +228,30 @@ Rules the tools enforce and explain in their own descriptions:
   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.
+- Those requirements are also published, so a node can be built without being
+  corrected into shape first. A `describeSchema` response that reached a
+  `richText` field ends with a `nodeProperties` entry stating what each node
+  type has to carry, in the same words the refusal uses:
+
+  ```json
+  {
+    "text": {
+      "detail": "a number",
+      "format": "a number",
+      "mode": "a string",
+      "style": "a string",
+      "text": "a string",
+      "type": "a string",
+      "version": "a number"
+    }
+  }
+  ```
+
+  It is keyed by node type and stated once for the whole response, because what
+  a node carries does not vary by where it is written; the field's own `nodes`
+  says which of those types it accepts. The listing is read off the same tables
+  the validator checks against, so the two cannot drift apart.
+
 - A rich text field's value is addressable, so a small edit does not have to
   rewrite the whole state. `/content/root/children/2` is a node,
   `/content/root/children/2/tag` one of its properties, and
@@ -266,6 +290,14 @@ Rules the tools enforce and explain in their own descriptions:
   its slug, where a pointer carries a 0-based index. So `/items/*/title` is
   written at `/items/0/title`, and `/layout/sections/hero` at
   `/layout/sections/0`.
+- Inside a rich text field that substitution does not apply, because an editor
+  state is a tree rather than a list per type. A path there names the node type,
+  and a block node its slug; a pointer enters the state at `root` and walks
+  `children` by an index counted over every child at that level, not over the
+  blocks among them, with the node's own fields under `fields`. So the path
+  `/content/block/practice-note/variant` is written at the pointer
+  `/content/root/children/7/fields/variant`, and only the stored state says
+  which index that is. `getDocument` with `outline` answers that.
 - Adding a block requires `blockType` on the value; append with `/-`.
 - Clearing is `replace` with `null`; a list is emptied with `[]` and refuses
   `null`. `remove` is only valid on list elements, because Payload keeps

package/dist/schema/index.mjs

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

package/dist/schema/lexical-pointer.mjs

@@ -45,7 +45,7 @@ import { blockOf, blockSlugsOf, isIndexSegment, isPlainObject, joinPath } from "
 	};
 	if (!isPlainObject(state) || !isPlainObject(state["root"])) throw new Error(`"${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 Error(`"${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".`);
+	if (entry !== "root") throw new Error(`"${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 nodeType = "root";
 	let segments = rest;
@@ -72,7 +72,7 @@ import { blockOf, blockSlugsOf, isIndexSegment, isPlainObject, joinPath } from "
 				}
 			};
 			const [index, ...beyond] = remaining;
-			if (!isIndexSegment(index)) throw new Error(`"${descriptor.path}${joinPath([...walked, "children"])}" is a list; "${index}" is not an index.`);
+			if (!isIndexSegment(index)) throw new Error(`"${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;
@@ -88,7 +88,7 @@ import { blockOf, blockSlugsOf, isIndexSegment, isPlainObject, joinPath } from "
 					...walked,
 					"children",
 					index
-				])}" is. Read the document first, or address an existing position.`);
+				])}" is. Call getDocument with "outline" for the pointer of each node, or address an existing position.`);
 			}
 			node = isPlainObject(child) ? child : void 0;
 			nodeType = type;

package/dist/schema/lexical.mjs

@@ -178,6 +178,27 @@ const ELEMENT_PROPERTIES = {
 * 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] ?? {});
+const describeConstraints = (constraints) => Object.fromEntries(Object.entries(constraints).map(([property, constraint]) => [property, needs(constraint)]).sort((left, right) => left[0].localeCompare(right[0])));
+/**
+* What each of the given node types has to carry, phrased the way the write
+* side phrases it when it refuses one, so the listing and the error message
+* never disagree. Read straight off the tables above, which is what keeps it
+* true: nothing here is stated a second time.
+*
+* Keyed by node type rather than reported per field, because that is what it
+* depends on. A field says which types it allows, in its `nodes`; what a `text`
+* node has to carry is the same wherever one is written, so a response that
+* describes twenty rich text fields still states it once.
+*
+* `type` is listed although {@link UNIVERSAL_PROPERTIES} omits it. The
+* validator never reports it missing, because a node's `type` is how it finds
+* the entry to check against, but a client assembling a node from this listing
+* still has to write one.
+*/ const nodePropertiesFor = (types) => Object.fromEntries([...new Set(types)].sort().map((type) => [type, describeConstraints(type === "root" ? ROOT_PROPERTIES : {
+	...REQUIRED_NODE_PROPERTIES[type],
+	...UNIVERSAL_PROPERTIES,
+	type: "string"
+})]));
 /** Present but `null` counts as present: `direction` is serialized that way. */ const check = (node, constraints) => {
 	const problems = {
 		missing: [],
@@ -261,4 +282,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, propertyProblem, rootProblems, subSchemaNodeTypes };
+export { REQUIRED_NODE_PROPERTIES, ROOT_PROPERTIES, allowedNodeTypes, constrainsFields, lexicalSubSchema, nodeOptions, nodeProblems, nodePropertiesFor, propertyProblem, rootProblems, subSchemaNodeTypes };

package/dist/tools/describe-schema.mjs

@@ -1,4 +1,5 @@
 import { jsonResult } from "../result.mjs";
+import { nodePropertiesFor } from "../schema/lexical.mjs";
 import { translatorFor } from "../i18n.mjs";
 import { nodeDescriber, reachableSchemaPaths } from "../schema/describe.mjs";
 import "../schema/index.mjs";
@@ -22,11 +23,11 @@ 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. A state whose root holds no children is refused however it is written, because Lexical reads it as empty and throws; clear a field with null instead.
+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. Those requirements are stated rather than left to be discovered: the response carries one final "nodeProperties" entry keyed by node type, naming each property and what belongs there in the same words a refused write uses, so a node can be built from this response alone. A field's own "nodes" says which of those types it accepts. The root takes exactly "children", "direction", "format", "indent", "type" and "version" and refuses anything else. 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. A state whose root holds no children is refused however it is written, because Lexical reads it as empty and throws; clear a field with null instead.
 
-A rich text field's value is addressable too, so an edit does not have to rewrite the whole state: "/content/root/children/0" is the first top-level node, "/content/root/children/0/children/1" a node inside it, "/content/root/children/0/tag" one property of a node, and "/content/root/children/0/fields/url" a field of a node, described at the "next" path for that node type. Append a node with "/-". Read the document first: which node sits at an index is only knowable from what is stored.
+A rich text field's value is addressable too, so an edit does not have to rewrite the whole state: "/content/root/children/0" is the first top-level node, "/content/root/children/0/children/1" a node inside it, "/content/root/children/0/tag" one property of a node, and "/content/root/children/0/fields/url" a field of a node, described at the "next" path for that node type. Append a node with "/-". Which node sits at an index is only knowable from what is stored, so read it first: getDocument with "outline" answers with the pointer, type, "version" and a text excerpt for every node, which is far cheaper than reading the whole state.
 
-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".
+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". Inside a rich text field that substitution does not apply: a path there names the node type, and a block node its slug, where a pointer enters the stored state at "root" and walks "children" by an index counted over every child at that level, not over the blocks among them, with the node's own fields under "fields". So "/content/block/practice-note/variant" is written at "/content/root/children/7/fields/variant".
 
 Fields Payload maintains (id, _status, createdAt, updatedAt) are never listed and cannot be written. Fields marked readOnly are listed but refused on write.`,
 	annotations: {
@@ -57,6 +58,8 @@ Fields Payload maintains (id, _status, createdAt, updatedAt) are never listed an
 				};
 			}
 		});
+		const nodeTypes = nodes.flatMap((node) => (node.fields ?? []).flatMap((field) => field.nodes ?? []));
+		if (nodeTypes.length > 0) nodes.push({ nodeProperties: nodePropertiesFor(nodeTypes) });
 		if (expanded?.truncated) nodes.push({ error: `Result truncated after ${String(400)} nodes. Request explicit paths instead.` });
 		return Promise.resolve(jsonResult(nodes));
 	}

package/dist/tools/patch-document.mjs

@@ -14,7 +14,7 @@ Pass exactly one of "collection" and "global". "id" is required with "collection
 
 ${draftSentence(scope)}
 
-Only the fields describeSchema lists can be addressed. A pointer that does not resolve is refused with the fields that are valid at that point, and nothing is applied unless every operation in the batch validates first. describeSchema reports field paths in this same pointer syntax; a path becomes a pointer into a document by replacing each "*" and each block slug with its 0-based index.
+Only the fields describeSchema lists can be addressed. A pointer that does not resolve is refused with the fields that are valid at that point, and nothing is applied unless every operation in the batch validates first. describeSchema reports field paths in this same pointer syntax; a path becomes a pointer into a document by replacing each "*" and each block slug with its 0-based index. Inside a rich text field that substitution does not apply: a path there names the node type, and a block node its slug, where a pointer enters the stored state at "root" and walks "children" by an index counted over every child at that level, not over the blocks among them, with the node's own fields under "fields". So "/content/block/practice-note/variant" is written at "/content/root/children/7/fields/variant".
 
 Adding a block requires "blockType" on the value. Append with "/-" as the last segment. To clear a field use "replace" with null; an array or blocks field refuses null and is emptied with [] instead. "remove" is only for list elements, because a field left out of a write is kept rather than cleared. Read the document first to learn the indices, and pass its "updatedAt" as expectedUpdatedAt so an edit made since that read is refused rather than overwritten.
 

package/package.json

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