@abinnovision/payloadcms-mcpx 1.0.0-beta.5 → 1.0.0-beta.6

package/README.md

@@ -10,7 +10,7 @@ small and static: collection slugs, locales and operations as enums, everything
 else scalars. The field shapes are pulled on demand through `describeSchema`,
 one node at a time, stopping at every blocks boundary. And every write is
 resolved server-side against the real config and the real document, so unknown
-fields, misplaced blocks and unusable rich text nodes are refused with the
+fields, misplaced blocks and unusable rich text nodes or node fields are refused with the
 valid alternatives listed, never silently dropped.
 
 Writes are RFC 6902 patches that always land as drafts; publishing stays a
@@ -142,6 +142,15 @@ Rules the tools enforce and explain in their own descriptions:
   accept; every node carries `next`, the ready-to-use paths for those blocks
   (`/layout/sections/sectionWrapper`), so pass an entry of `next` as a `paths`
   element to descend. A block is described as it exists at that position.
+- Rich text paths continue the same way. A `richText` field 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. Descending returns the real field list, so a link extended through
+  `LinkFeature({ fields })` and a Lexical block are both described rather than
+  guessed. Any feature declaring `getSubFields` is picked up, custom ones
+  included. `upload` nodes are the exception: their fields depend on the
+  collection the node points at, so they are not addressable.
 - Field and collection `admin.description` values are included in
   `describeSchema` and `listCapabilities`, so intent written for the admin
   panel reaches the client. Strings and locale-keyed records pass through;
@@ -302,9 +311,11 @@ key of every user.
 
 ## Non-goals of v1 / roadmap
 
-Deletes, uploads, markdown authoring for rich text, row addressing by id
-instead of index, cross-locale publish blockers, pagination of `describeSchema`
-with `expand`, and a handler-level timeout are all deliberate omissions for now.
+Deletes, uploads, markdown authoring for rich text, addressing a rich text node
+by position in a patch (an editor state is written whole), schemas for `upload`
+node fields, row addressing by id instead of index, cross-locale publish
+blockers, pagination of `describeSchema` with `expand`, and a handler-level
+timeout are all deliberate omissions for now.
 
 ## License
 

package/dist/schema/describe.mjs

@@ -1,32 +1,86 @@
-import { blockOf, blockSlugsOf, describeFields, findBlocksField, joinPath, splitPath, targetOf } from "./walk.mjs";
+import { lexicalSubSchema, subSchemaNodeTypes } from "./lexical.mjs";
+import { blockOf, blockSlugsOf, describeFields, findBlocksField, findRichTextField, joinPath, splitPath, targetOf } from "./walk.mjs";
 //#region src/schema/describe.ts
-const blocksDescriptors = (fields) => describeFields(fields).filter((descriptor) => descriptor.type === "blocks");
+/**
+* The longest descriptor path that is a prefix of `remaining`. Blocks and rich
+* text fields are both leaves of the walk, so at most one can match.
+*/ const longestMatch = (descriptors, remaining) => descriptors.map((descriptor) => splitPath(descriptor.path)).filter((parts) => parts.every((part, offset) => part === remaining[offset])).sort((left, right) => right.length - left.length)[0];
+/**
+* Walks one step of a schema path through a blocks field.
+*/ const stepThroughBlocks = ({ config, fields, match, remaining }) => {
+	const field = findBlocksField(fields, match);
+	if (!field) throw new Error(`"${joinPath(match)}" could not be resolved.`);
+	const slug = remaining.at(match.length);
+	if (slug === void 0) throw new Error(`"${joinPath(match)}" is a blocks field; append one of: ${blockSlugsOf(field).join(", ")}`);
+	const block = blockOf(config, field, slug);
+	if (!block) throw new Error(`"${slug}" is not allowed at "${joinPath(match)}". Allowed: ${blockSlugsOf(field).join(", ")}`);
+	return {
+		blockType: slug,
+		fields: block.flattenedFields,
+		rest: remaining.slice(match.length + 1)
+	};
+};
+/**
+* Walks one step of a schema path into a Lexical node's own fields.
+*
+* A node that picks a block by slug takes one segment more, so `/content/block`
+* addresses the choice and `/content/block/callout` the definition. Everything
+* else, a link node being the usual case, resolves in a single segment.
+*/ const stepThroughLexical = ({ config, fields, match, remaining }) => {
+	const field = findRichTextField(fields, match);
+	if (!field) throw new Error(`"${joinPath(match)}" could not be resolved.`);
+	const available = subSchemaNodeTypes(field).join(", ") || "none";
+	const nodeType = remaining.at(match.length);
+	if (nodeType === void 0) throw new Error(`"${joinPath(match)}" is a rich text field; append one of: ${available}`);
+	const sub = lexicalSubSchema(field, nodeType);
+	const reached = joinPath([...match, nodeType]);
+	if (!sub) throw new Error(`"${nodeType}" carries no fields in this field's editor. Node types with fields here: ${available}`);
+	if (sub.kind === "fields") return {
+		fields: sub.fields,
+		rest: remaining.slice(match.length + 1)
+	};
+	const slug = remaining.at(match.length + 1);
+	const slugs = blockSlugsOf(sub.blocksField).join(", ");
+	if (slug === void 0) throw new Error(`"${reached}" selects a block; append one of: ${slugs}`);
+	const block = blockOf(config, sub.blocksField, slug);
+	if (!block) throw new Error(`"${slug}" is not allowed at "${reached}". Allowed: ${slugs}`);
+	return {
+		blockType: slug,
+		fields: block.flattenedFields,
+		rest: remaining.slice(match.length + 2)
+	};
+};
 /**
 * Walks a schema path to the field list it addresses.
 *
 * A schema path alternates a blocks field's own path with the slug of one of
 * the blocks it accepts, so `/layout/sections/sectionWrapper/modules/hero`
 * reaches `hero` as it exists under `pages` specifically. The slug sits where
-* a pointer into a document would carry the element's index.
+* a pointer into a document would carry the element's index. A rich text
+* field's path continues the same way, naming a Lexical node type and, for the
+* block nodes, the slug it holds.
 */ const fieldsAtSchemaPath = (config, target, schemaPath) => {
 	let fields = target.flattenedFields;
 	let blockType;
 	let remaining = splitPath(schemaPath);
 	while (remaining.length > 0) {
+		const descendable = describeFields(fields).filter((descriptor) => descriptor.type === "blocks" || descriptor.type === "richText");
 		/**
-		* A blocks field's own path may span several segments
-		* (`/layout/sections`), so the longest matching one is taken.
-		*/ const match = blocksDescriptors(fields).map((descriptor) => splitPath(descriptor.path)).filter((parts) => parts.every((part, offset) => part === remaining[offset])).sort((left, right) => right.length - left.length)[0];
-		if (!match) throw new Error(`"${joinPath(remaining)}" does not address a blocks field. Blocks fields here: ${blocksDescriptors(fields).map((descriptor) => descriptor.path).join(", ") || "none"}`);
-		const slug = remaining.at(match.length);
-		const field = findBlocksField(fields, match);
-		if (!field) throw new Error(`"${joinPath(match)}" could not be resolved.`);
-		if (slug === void 0) throw new Error(`"${joinPath(match)}" is a blocks field; append one of: ${blockSlugsOf(field).join(", ")}`);
-		const block = blockOf(config, field, slug);
-		if (!block) throw new Error(`"${slug}" is not allowed at "${joinPath(match)}". Allowed: ${blockSlugsOf(field).join(", ")}`);
-		fields = block.flattenedFields;
-		blockType = slug;
-		remaining = remaining.slice(match.length + 1);
+		* A field's own path may span several segments (`/layout/sections`), so
+		* the longest matching one is taken. Blocks and rich text fields are both
+		* leaves of the walk, so no two of these paths overlap.
+		*/ const match = longestMatch(descendable, remaining);
+		if (!match) throw new Error(`"${joinPath(remaining)}" does not address a blocks or rich text field. Available here: ${descendable.map((descriptor) => descriptor.path).join(", ") || "none"}`);
+		const at = {
+			config,
+			fields,
+			match,
+			remaining
+		};
+		const step = findBlocksField(fields, match) === void 0 ? stepThroughLexical(at) : stepThroughBlocks(at);
+		blockType = step.blockType;
+		fields = step.fields;
+		remaining = step.rest;
 	}
 	return {
 		...blockType === void 0 ? {} : { blockType },
@@ -34,12 +88,37 @@ const blocksDescriptors = (fields) => describeFields(fields).filter((descriptor)
 	};
 };
 /**
-* Describes a collection or global root, or one block reached through a schema
-* path.
+* Where a descriptor can be drilled into: one branch per block a blocks field
+* accepts, and one per Lexical node type that carries fields.
+*/ const branchesOf = (fields, descriptor, schemaPath) => {
+	const base = `${schemaPath}${descriptor.path}`;
+	if (descriptor.type === "richText") {
+		const field = findRichTextField(fields, splitPath(descriptor.path));
+		if (!field) return [];
+		return subSchemaNodeTypes(field).flatMap((nodeType) => {
+			const sub = lexicalSubSchema(field, nodeType);
+			if (sub?.kind !== "blocks") return [{
+				path: `${base}/${nodeType}`,
+				token: `lexical:${nodeType}`
+			}];
+			return blockSlugsOf(sub.blocksField).map((slug) => ({
+				path: `${base}/${nodeType}/${slug}`,
+				token: `lexical:${nodeType}:${slug}`
+			}));
+		});
+	}
+	return (descriptor.blocks ?? []).map((slug) => ({
+		path: `${base}/${slug}`,
+		token: slug
+	}));
+};
+/**
+* Describes a collection or global root, one block reached through a schema
+* path, or the fields a Lexical node carries.
 */ const describeNode = (config, ref, schemaPath = "") => {
 	const { blockType, fields } = fieldsAtSchemaPath(config, targetOf(config, ref), schemaPath);
 	const descriptors = describeFields(fields);
-	const next = descriptors.flatMap((descriptor) => (descriptor.blocks ?? []).map((slug) => `${schemaPath}${descriptor.path}/${slug}`));
+	const next = descriptors.flatMap((descriptor) => branchesOf(fields, descriptor, schemaPath).map((branch) => branch.path));
 	return {
 		...blockType === void 0 ? {} : { blockType },
 		...ref.kind === "collection" ? { collection: ref.slug } : { global: ref.slug },
@@ -61,9 +140,10 @@ const blocksDescriptors = (fields) => describeFields(fields).filter((descriptor)
 			return;
 		}
 		seen.push(schemaPath);
-		for (const descriptor of describeNode(config, ref, schemaPath).fields) for (const slug of descriptor.blocks ?? []) {
-			if (visited.includes(slug)) continue;
-			walk(`${schemaPath}${descriptor.path}/${slug}`, [...visited, slug]);
+		const { fields } = fieldsAtSchemaPath(config, targetOf(config, ref), schemaPath);
+		for (const descriptor of describeFields(fields)) for (const branch of branchesOf(fields, descriptor, schemaPath)) {
+			if (visited.includes(branch.token)) continue;
+			walk(branch.path, [...visited, branch.token]);
 		}
 	};
 	walk("", []);

package/dist/schema/lexical.mjs

@@ -1,3 +1,4 @@
+import { flattenAllFields } from "payload";
 //#region src/schema/lexical.ts
 /**
 * Node types Lexical registers itself.
@@ -12,14 +13,61 @@
 	"tab"
 ];
 /**
+* Node types whose sub-fields exist but cannot be addressed by a schema path.
+*
+* Asked without a node, `upload` answers with every enabled collection's
+* upload fields concatenated, so the result describes no single position. It
+* would need addressing by `relationTo` to mean anything.
+*/ const OPAQUE_NODE_TYPES = /* @__PURE__ */ new Set(["upload"]);
+/**
+* Sub-schemas per rich text field, keyed by node type. `null` records a node
+* type that was asked and has nothing to describe, so it is asked only once.
+*
+* Worth caching because the describe and validate paths resolve the same field
+* repeatedly, and because the block features build their answer from scratch on
+* every call. Keyed weakly on the sanitized field, which lives as long as the
+* config does.
+*/ const subSchemaCache = /* @__PURE__ */ new WeakMap();
+const featuresOf = (field) => field.editor?.editorConfig?.features;
+/**
 * Node types a rich text field accepts. Editors other than Lexical report
 * only the core nodes.
 */ const allowedNodeTypes = (field) => {
-	const registered = (field.editor?.editorConfig?.features?.nodes ?? []).flatMap((entry) => {
+	const registered = (featuresOf(field)?.nodes ?? []).flatMap((entry) => {
 		const type = entry.node?.getType?.();
 		return type ? [type] : [];
 	});
 	return [.../* @__PURE__ */ new Set([...LEXICAL_CORE_NODES, ...registered])];
 };
+const resolveSubSchema = (field, nodeType) => {
+	if (OPAQUE_NODE_TYPES.has(nodeType)) return null;
+	const fields = featuresOf(field)?.getSubFields?.get(nodeType)?.({});
+	if (!fields?.length) return null;
+	const flattened = flattenAllFields({ fields });
+	const only = flattened.length === 1 ? flattened[0] : void 0;
+	return only?.type === "blocks" ? {
+		blocksField: only,
+		kind: "blocks"
+	} : {
+		fields: flattened,
+		kind: "fields"
+	};
+};
+/**
+* The sub-schema behind one node type of a rich text field, or `undefined`
+* when that node carries no addressable fields.
+*/ const lexicalSubSchema = (field, nodeType) => {
+	let cached = subSchemaCache.get(field);
+	if (!cached) {
+		cached = /* @__PURE__ */ new Map();
+		subSchemaCache.set(field, cached);
+	}
+	if (!cached.has(nodeType)) cached.set(nodeType, resolveSubSchema(field, nodeType));
+	return cached.get(nodeType) ?? void 0;
+};
+/**
+* Node types of a rich text field that have a sub-schema, in the order their
+* features registered them.
+*/ const subSchemaNodeTypes = (field) => [...featuresOf(field)?.getSubFields?.keys() ?? []].filter((nodeType) => lexicalSubSchema(field, nodeType) !== void 0);
 //#endregion
-export { allowedNodeTypes };
+export { allowedNodeTypes, lexicalSubSchema, subSchemaNodeTypes };

package/dist/schema/shape.mjs

@@ -1,4 +1,5 @@
-import { blockOf, blockSlugsOf, describeFields, findBlocksField, splitPath } from "./walk.mjs";
+import { lexicalSubSchema } from "./lexical.mjs";
+import { blockOf, blockSlugsOf, describeFields, findBlocksField, findRichTextField, splitPath } from "./walk.mjs";
 //#region src/schema/shape.ts
 /**
 * Keys Payload manages on a row that a client may echo back harmlessly.
@@ -9,30 +10,79 @@ import { blockOf, blockSlugsOf, describeFields, findBlocksField, splitPath } fro
 ]);
 const isPlainObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 /**
-* Checks every node type in an editor state against what the field's editor
-* can actually produce.
+* Checks the fields a single Lexical node carries against the schema its
+* feature declares for that node type.
+*
+* 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 sub = lexicalSubSchema(field, node.type);
+	if (!sub) return;
+	const data = node.fields;
+	if (!isPlainObject(data)) {
+		scope.problems.push(`${scope.pointer}: a "${node.type}" node carries a "fields" object.`);
+		return;
+	}
+	const nested = {
+		...scope,
+		pointer: `${scope.pointer}/fields`,
+		prefix: []
+	};
+	if (sub.kind === "fields") {
+		checkValue({
+			...nested,
+			fields: sub.fields
+		}, data);
+		return;
+	}
+	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(", ")}`);
+		return;
+	}
+	checkValue({
+		...nested,
+		fields: block.flattenedFields
+	}, data);
+};
+/**
+* Checks an editor state against what the field's editor can actually
+* produce: every node type, and the fields each node carries.
 *
 * Payload does not: 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.
-*/ const checkRichText = (scope, allowed, value) => {
+* 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.
+*/ 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 walk = (nodes) => {
+	const walk = (nodes, pointer) => {
 		if (!Array.isArray(nodes)) return;
-		for (const node of nodes) {
+		nodes.forEach((node, index) => {
+			const at = `${pointer}/${String(index)}`;
 			if (!isPlainObject(node) || typeof node["type"] !== "string") {
-				scope.problems.push(`${scope.pointer}: every node needs a "type".`);
-				continue;
+				scope.problems.push(`${at}: every node needs a "type".`);
+				return;
 			}
-			if (!allowed.includes(node["type"])) scope.problems.push(`${scope.pointer}: "${node["type"]}" is not available in this field's editor. Allowed: ${allowed.join(", ")}`);
-			walk(node["children"]);
-		}
+			if (!editor.allowed.includes(node["type"])) {
+				scope.problems.push(`${at}: "${node["type"]}" is not available in this field's editor. Allowed: ${editor.allowed.join(", ")}`);
+				return;
+			}
+			if (editor.field) checkNodeFields({
+				...scope,
+				pointer: at
+			}, editor.field, {
+				fields: node["fields"],
+				type: node["type"]
+			});
+			walk(node["children"], `${at}/children`);
+		});
 	};
-	walk(value["root"]["children"]);
+	walk(value["root"]["children"], `${scope.pointer}/root/children`);
 };
 const checkLeafValue = (scope, descriptor, value) => {
 	if (descriptor.readOnly) {
@@ -40,7 +90,10 @@ const checkLeafValue = (scope, descriptor, value) => {
 		return;
 	}
 	if (descriptor.type === "richText") {
-		checkRichText(scope, descriptor.nodes ?? [], value);
+		checkRichText(scope, {
+			allowed: descriptor.nodes ?? [],
+			field: findRichTextField(scope.fields, splitPath(descriptor.path))
+		}, value);
 		return;
 	}
 	if (descriptor.type !== "blocks") return;

package/dist/schema/walk.mjs

@@ -109,10 +109,21 @@ const withRows = (descriptor, field) => ({
 		if (field.type === "array" && path[1] === "*") return findBlocksField(field.flattenedFields, path.slice(2));
 	}
 };
+/**
+* Locates the rich text field that a resolved descriptor path refers to, so
+* its editor can be introspected for the fields its nodes carry.
+*/ const findRichTextField = (fields, path) => {
+	for (const field of fields) {
+		if (!("name" in field) || field.name !== path[0]) continue;
+		if (field.type === "richText" && path.length === 1) return field;
+		if (field.type === "tab" || field.type === "group") return findRichTextField(field.flattenedFields, path.slice(1));
+		if (field.type === "array" && path[1] === "*") return findRichTextField(field.flattenedFields, path.slice(2));
+	}
+};
 const targetOf = (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, describeFields, findBlocksField, joinPath, pointerFromPayloadPath, splitPath, staticDescription, targetOf };
+export { JSON_POINTER_PATTERN, RESERVED_FIELD_NAMES, blockOf, blockSlugsOf, describeFields, findBlocksField, findRichTextField, joinPath, pointerFromPayloadPath, splitPath, staticDescription, targetOf };

package/dist/tools/describe-schema.mjs

@@ -12,6 +12,8 @@ Pass exactly one of "collection" and "global". A global is a singleton: it has n
 
 Call it with no "paths" to get a collection's own fields. Every "blocks" field stops there and lists the block slugs it accepts instead of nesting them; each node's "next" lists the ready-to-use paths for those blocks, so pass any entry of "next" as a "paths" element to descend, e.g. "/layout/sections/sectionWrapper" and then "/layout/sections/sectionWrapper/modules/hero". A block is described as it exists at that position, because the same block can accept different children elsewhere.
 
+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.
+
 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.5",
+  "version": "1.0.0-beta.6",
   "description": "Payload CMS plugin exposing a fixed, schema-aware MCP tool surface with draft-only writes and per-API-key capabilities.",
   "keywords": [
     "payload",