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

package/README.md

@@ -151,6 +151,16 @@ Rules the tools enforce and explain in their own descriptions:
   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.
+- Constraints a field declares travel with it: `minRows`/`maxRows` on arrays
+  and blocks fields, `maxLength`/`minLength` on text, `min`/`max` on numbers.
+  An array is described in its own right, so the `*` in `/items/*/title` has
+  something to read; a group or named tab only when it declares a description
+  or a constraint of its own.
+- A `richText` field also reports `nodeOptions`, the node properties its editor
+  narrows. An editor built with `HeadingFeature({ enabledHeadingSizes: ["h4"] })`
+  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.
 - 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;

package/dist/schema/lexical.d.mts

@@ -0,0 +1 @@
+import "payload";

package/dist/schema/lexical.mjs

@@ -69,5 +69,49 @@ const resolveSubSchema = (field, nodeType) => {
 * 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);
+/**
+* Node properties worth reporting and enforcing.
+*
+* 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
+* slugs it accepts.
+*/ const NODE_OPTION_SOURCES = [{
+	defaults: [
+		"h1",
+		"h2",
+		"h3",
+		"h4",
+		"h5",
+		"h6"
+	],
+	featureKey: "heading",
+	featureProp: "enabledHeadingSizes",
+	nodeProp: "tag",
+	nodeType: "heading"
+}];
+/**
+* The props a feature was resolved with.
+*
+* Sanitizing the editor drops every feature's props from `editorConfig.features`
+* but leaves them on `resolvedFeatureMap`. A feature that declares no server
+* props keeps only the client ones, so both are tried.
+*/ const featurePropsOf = (field, featureKey) => {
+	const resolved = field.editor?.editorConfig?.resolvedFeatureMap?.get(featureKey);
+	const props = resolved?.sanitizedServerFeatureProps ?? resolved?.clientFeatureProps;
+	return typeof props === "object" && props !== null ? props : void 0;
+};
+const stringList = (value) => Array.isArray(value) && value.every((entry) => typeof entry === "string") ? value : void 0;
+/**
+* The narrowed node properties of a rich text field, for the node types it
+* actually accepts.
+*/ const nodeOptions = (field, allowed) => {
+	const entries = NODE_OPTION_SOURCES.flatMap((source) => {
+		if (!allowed.includes(source.nodeType)) return [];
+		const values = stringList(featurePropsOf(field, source.featureKey)?.[source.featureProp]) ?? [...source.defaults];
+		return [[source.nodeType, { [source.nodeProp]: values }]];
+	});
+	return entries.length > 0 ? Object.fromEntries(entries) : void 0;
+};
 //#endregion
-export { allowedNodeTypes, lexicalSubSchema, subSchemaNodeTypes };
+export { allowedNodeTypes, lexicalSubSchema, nodeOptions, subSchemaNodeTypes };

package/dist/schema/pointer.mjs

@@ -1,4 +1,4 @@
-import { blockOf, blockSlugsOf, describeFields, findBlocksField, joinPath, splitPath, targetOf } from "./walk.mjs";
+import { blockOf, blockSlugsOf, describeAddressableFields, findBlocksField, joinPath, splitPath, targetOf } from "./walk.mjs";
 //#region src/schema/pointer.ts
 const isIndexSegment = (segment) => segment === "-" || /^\d+$/.test(segment);
 const partMatches = (part, segment) => segment !== void 0 && (part === "*" ? isIndexSegment(segment) : part === segment);
@@ -37,7 +37,7 @@ const partMatches = (part, segment) => segment !== void 0 && (part === "*" ? isI
 	let blockType;
 	let segments = splitPath(target.pointer);
 	while (segments.length > 0) {
-		const descriptors = describeFields(fields);
+		const descriptors = describeAddressableFields(fields);
 		const match = longestMatch(descriptors, segments);
 		if (!match) {
 			if (isSubtreePrefix(descriptors, segments)) return {

package/dist/schema/shape.mjs

@@ -1,5 +1,5 @@
 import { lexicalSubSchema } from "./lexical.mjs";
-import { blockOf, blockSlugsOf, describeFields, findBlocksField, findRichTextField, splitPath } from "./walk.mjs";
+import { blockOf, blockSlugsOf, describeAddressableFields, findBlocksField, findRichTextField, splitPath } from "./walk.mjs";
 //#region src/schema/shape.ts
 /**
 * Keys Payload manages on a row that a client may echo back harmlessly.
@@ -54,7 +54,9 @@ const isPlainObject = (value) => typeof value === "object" && value !== null &&
 * 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.
+* 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`.
 */ const checkRichText = (scope, editor, value) => {
 	if (!isPlainObject(value) || !isPlainObject(value["root"])) {
 		scope.problems.push(`${scope.pointer}: expected a Lexical editor state with a "root".`);
@@ -72,6 +74,10 @@ 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;
 			}
+			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 (editor.field) checkNodeFields({
 				...scope,
 				pointer: at
@@ -92,7 +98,8 @@ const checkLeafValue = (scope, descriptor, value) => {
 	if (descriptor.type === "richText") {
 		checkRichText(scope, {
 			allowed: descriptor.nodes ?? [],
-			field: findRichTextField(scope.fields, splitPath(descriptor.path))
+			field: findRichTextField(scope.fields, splitPath(descriptor.path)),
+			nodeOptions: descriptor.nodeOptions
 		}, value);
 		return;
 	}
@@ -122,15 +129,16 @@ const checkLeafValue = (scope, descriptor, value) => {
 * Walks an incoming value against the schema, reporting every shape problem
 * rather than the first.
 *
-* Shape only: unknown field names, unknown block slugs, read-only fields and
-* unusable rich text nodes. Required-ness, row counts, 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.
+* 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) => {
 	if (!isPlainObject(value)) return;
 	const prefixParts = scope.prefix;
-	const relative = describeFields(scope.fields).flatMap((descriptor) => {
+	const relative = describeAddressableFields(scope.fields).flatMap((descriptor) => {
 		const parts = splitPath(descriptor.path);
 		return prefixParts.every((part, offset) => part === parts[offset]) ? [{
 			descriptor,

package/dist/schema/walk.d.mts

@@ -1 +1,2 @@
+import "./lexical.mjs";
 import "payload";

package/dist/schema/walk.mjs

@@ -1,4 +1,4 @@
-import { allowedNodeTypes } from "./lexical.mjs";
+import { allowedNodeTypes, nodeOptions } from "./lexical.mjs";
 import { fieldIsHiddenOrDisabled, fieldIsVirtual } from "payload/shared";
 //#region src/schema/walk.ts
 /**
@@ -70,7 +70,15 @@ const describeLeaf = (field, path, readOnly) => {
 	if (field.type === "select" || field.type === "radio") descriptor.options = field.options.map((option) => typeof option === "string" ? option : option.value);
 	if (field.type === "relationship" || field.type === "upload") descriptor.relationTo = field.relationTo;
 	if ((field.type === "select" || field.type === "relationship" || field.type === "upload") && field.hasMany === true) descriptor.hasMany = true;
-	if (field.type === "richText") descriptor.nodes = allowedNodeTypes(field);
+	if ((field.type === "text" || field.type === "textarea") && field.maxLength !== void 0) descriptor.maxLength = field.maxLength;
+	if ((field.type === "text" || field.type === "textarea") && field.minLength !== void 0) descriptor.minLength = field.minLength;
+	if (field.type === "number" && field.max !== void 0) descriptor.max = field.max;
+	if (field.type === "number" && field.min !== void 0) descriptor.min = field.min;
+	if (field.type === "richText") {
+		descriptor.nodes = allowedNodeTypes(field);
+		const options = nodeOptions(field, descriptor.nodes);
+		if (options) descriptor.nodeOptions = options;
+	}
 	return descriptor;
 };
 const withRows = (descriptor, field) => ({
@@ -79,20 +87,37 @@ const withRows = (descriptor, field) => ({
 	...field.maxRows === void 0 ? {} : { maxRows: field.maxRows }
 });
 /**
+* Whether a descriptor stands for a construct that only holds other fields.
+*
+* These describe a position rather than a value, so everything that resolves a
+* path to something writable skips them; only {@link describeNode} reports
+* them, 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, which has already merged every
 * construct that exists only in the admin UI (unnamed tabs, unnamed groups,
 * `row`, `collapsible`) and dropped `ui` fields. Named tabs, groups and
-* arrays contribute a path segment. The walk stops at every blocks field and
-* names the slugs instead of descending, which keeps a node proportional to
-* the number of blocks it allows rather than to the size of their definitions.
+* 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 instead
+* of descending, which keeps a node proportional to the number of blocks it
+* allows rather than to the size of their definitions.
 */ const describeFields = (fields, prefix = [], parentReadOnly = false) => fields.flatMap((field) => {
 	if (isSkipped(field)) return [];
 	const readOnly = parentReadOnly || isReadOnly(field);
 	const path = [...prefix, field.name];
-	if (field.type === "tab" || field.type === "group") return describeFields(field.flattenedFields, path, readOnly);
-	if (field.type === "array") return describeFields(field.flattenedFields, [...path, "*"], readOnly);
+	if (field.type === "tab" || field.type === "group") {
+		const own = describeBase(field, joinPath(path), readOnly);
+		return [...isInformative(own) ? [own] : [], ...describeFields(field.flattenedFields, path, readOnly)];
+	}
+	if (field.type === "array") return [withRows(describeBase(field, joinPath(path), readOnly), field), ...describeFields(field.flattenedFields, [...path, "*"], readOnly)];
 	if (field.type === "blocks") return [withRows({
 		...describeBase(field, joinPath(path), readOnly),
 		blocks: blockSlugsOf(field)
@@ -100,6 +125,11 @@ const withRows = (descriptor, field) => ({
 	return [describeLeaf(field, joinPath(path), readOnly)];
 });
 /**
+* 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 describeNode} reports one.
+*/ const describeAddressableFields = (fields) => describeFields(fields).filter((descriptor) => !isContainer(descriptor));
+/**
 * Locates the blocks field that a resolved descriptor path refers to.
 */ const findBlocksField = (fields, path) => {
 	for (const field of fields) {
@@ -126,4 +156,4 @@ const targetOf = (config, ref) => {
 	return found;
 };
 //#endregion
-export { JSON_POINTER_PATTERN, RESERVED_FIELD_NAMES, blockOf, blockSlugsOf, describeFields, findBlocksField, findRichTextField, joinPath, pointerFromPayloadPath, splitPath, staticDescription, targetOf };
+export { JSON_POINTER_PATTERN, RESERVED_FIELD_NAMES, blockOf, blockSlugsOf, describeAddressableFields, describeFields, findBlocksField, findRichTextField, joinPath, pointerFromPayloadPath, splitPath, staticDescription, targetOf };

package/dist/write/patch.mjs

@@ -1,4 +1,4 @@
-import { JSON_POINTER_PATTERN, RESERVED_FIELD_NAMES, blockOf, describeFields, findBlocksField, splitPath } from "../schema/walk.mjs";
+import { JSON_POINTER_PATTERN, RESERVED_FIELD_NAMES, blockOf, describeAddressableFields, findBlocksField, splitPath } from "../schema/walk.mjs";
 import { validateWriteValue } from "../schema/shape.mjs";
 import { resolveDataPointer } from "../schema/pointer.mjs";
 import { z } from "zod";
@@ -154,7 +154,7 @@ const isPlainObject = (value) => typeof value === "object" && value !== null &&
 * is left out, so the write-back carries only what a client could have set.
 */ const pickDescribed = (config, value, at) => {
 	const { fields, prefix, isRow } = at;
-	const relative = describeFields(fields).flatMap((descriptor) => {
+	const relative = describeAddressableFields(fields).flatMap((descriptor) => {
 		const parts = splitPath(descriptor.path);
 		return prefix.every((part, offset) => part === parts[offset]) ? [{
 			descriptor,

package/package.json

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