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

package/README.md

@@ -151,10 +151,21 @@ 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;
-  functions and components are dropped.
+  panel reaches the client. A locale-keyed record is resolved to one string for
+  the request's language, falling back to the deployment's fallback language and
+  then to the record's first entry; functions and components are dropped.
 - Builtin tools reject unknown arguments by name instead of silently ignoring
   them.
 - Every path this plugin accepts or reports is a JSON Pointer. A schema path

package/dist/i18n.d.mts

@@ -0,0 +1 @@
+import { PayloadRequest } from "payload";

package/dist/i18n.mjs

@@ -0,0 +1,40 @@
+//#region src/i18n.ts
+/**
+* A locale-keyed record, once it is known to hold nothing but strings.
+*/ const stringRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value) && Object.values(value).every((entry) => typeof entry === "string") ? value : void 0;
+/**
+* Picks the entry a language addresses, treating an empty value as absent so
+* the chain continues rather than yielding a useless string.
+*/ const pick = (record, language) => {
+	for (const code of Array.isArray(language) ? language : [language]) {
+		const entry = record[code];
+		if (entry !== void 0 && entry.trim() !== "") return entry;
+	}
+};
+/**
+* Resolves a static label or `admin.description` to the one string a client
+* can use: the request's language, then the fallback language configured for
+* the deployment, then whichever entry the record declares first.
+*
+* Anything that is not a string or a string-valued record is dropped. A
+* description written as a function or a React component is an admin-UI
+* construct that may reach client-only i18n, so it is never invoked here.
+*/ const translateStatic = (value, language) => {
+	if (typeof value === "string") return value.trim() === "" ? void 0 : value;
+	const record = stringRecord(value);
+	if (!record) return;
+	return pick(record, language.language) ?? pick(record, language.fallbackLanguage) ?? Object.values(record).find((entry) => entry.trim() !== "");
+};
+/**
+* Binds {@link translateStatic} to a request's language, so a walk that
+* resolves many descriptions carries no request of its own.
+*/ const translatorFor = (i18n) => (value) => translateStatic(value, i18n);
+/**
+* Translator for callers with no request in hand. Both language keys miss, so
+* the chain degrades to the record's first entry.
+*/ const translateAny = translatorFor({
+	fallbackLanguage: "",
+	language: ""
+});
+//#endregion
+export { translateAny, translateStatic, translatorFor };

package/dist/schema/describe.mjs

@@ -1,4 +1,5 @@
 import { lexicalSubSchema, subSchemaNodeTypes } from "./lexical.mjs";
+import { translateAny } from "../i18n.mjs";
 import { blockOf, blockSlugsOf, describeFields, findBlocksField, findRichTextField, joinPath, splitPath, targetOf } from "./walk.mjs";
 //#region src/schema/describe.ts
 /**
@@ -115,9 +116,12 @@ import { blockOf, blockSlugsOf, describeFields, findBlocksField, findRichTextFie
 /**
 * 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 = "") => {
+*
+* Curried on the translator that resolves each `admin.description`, so a
+* request binds its language once and the walk itself stays request-free.
+*/ const nodeDescriber = (translate = translateAny) => (config, ref, schemaPath = "") => {
 	const { blockType, fields } = fieldsAtSchemaPath(config, targetOf(config, ref), schemaPath);
-	const descriptors = describeFields(fields);
+	const descriptors = describeFields(fields, translate);
 	const next = descriptors.flatMap((descriptor) => branchesOf(fields, descriptor, schemaPath).map((branch) => branch.path));
 	return {
 		...blockType === void 0 ? {} : { blockType },
@@ -153,4 +157,4 @@ import { blockOf, blockSlugsOf, describeFields, findBlocksField, findRichTextFie
 	};
 };
 //#endregion
-export { describeNode, reachableSchemaPaths };
+export { nodeDescriber, reachableSchemaPaths };

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,3 @@
+import "./lexical.mjs";
+import "../i18n.mjs";
 import "payload";

package/dist/schema/walk.mjs

@@ -1,4 +1,5 @@
-import { allowedNodeTypes } from "./lexical.mjs";
+import { allowedNodeTypes, nodeOptions } from "./lexical.mjs";
+import { translateAny } from "../i18n.mjs";
 import { fieldIsHiddenOrDisabled, fieldIsVirtual } from "payload/shared";
 //#region src/schema/walk.ts
 /**
@@ -46,16 +47,8 @@ import { fieldIsHiddenOrDisabled, fieldIsVirtual } from "payload/shared";
 };
 const isSkipped = (field) => !("name" in field) || field.type === "join" || RESERVED_FIELD_NAMES.has(field.name) || fieldIsVirtual(field) || fieldIsHiddenOrDisabled(field);
 const isReadOnly = (field) => "admin" in field && field.admin.readOnly === true;
-/**
-* The `admin.description` of a field or collection, when it is serializable:
-* a string or a locale-keyed record. Functions and components are admin-UI
-* constructs and are dropped.
-*/ const staticDescription = (description) => {
-	if (typeof description === "string") return description;
-	return typeof description === "object" && description !== null && Object.values(description).every((entry) => typeof entry === "string") ? description : void 0;
-};
-const describeBase = (field, path, readOnly) => {
-	const description = staticDescription("admin" in field ? field.admin.description : void 0);
+const describeBase = (field, { path, readOnly, translate }) => {
+	const description = translate("admin" in field ? field.admin.description : void 0);
 	return {
 		path,
 		type: field.type,
@@ -65,12 +58,20 @@ const describeBase = (field, path, readOnly) => {
 		...readOnly ? { readOnly: true } : {}
 	};
 };
-const describeLeaf = (field, path, readOnly) => {
-	const descriptor = describeBase(field, path, readOnly);
+const describeLeaf = (field, at) => {
+	const descriptor = describeBase(field, at);
 	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,26 +80,61 @@ 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.
-*/ 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 === "blocks") return [withRows({
-		...describeBase(field, joinPath(path), readOnly),
-		blocks: blockSlugsOf(field)
-	}, field)];
-	return [describeLeaf(field, joinPath(path), readOnly)];
-});
+* 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.
+*
+* `translate` resolves each `admin.description` to the request's language.
+* Callers that walk for paths alone leave it out and get the language-agnostic
+* default, so a missing argument costs language selection, never the
+* description itself.
+*/ const describeFields = (fields, translate = translateAny) => {
+	const walk = (current, prefix, parentReadOnly) => current.flatMap((field) => {
+		if (isSkipped(field)) return [];
+		const readOnly = parentReadOnly || isReadOnly(field);
+		const path = [...prefix, field.name];
+		const at = {
+			path: joinPath(path),
+			readOnly,
+			translate
+		};
+		if (field.type === "tab" || field.type === "group") {
+			const own = describeBase(field, at);
+			return [...isInformative(own) ? [own] : [], ...walk(field.flattenedFields, path, readOnly)];
+		}
+		if (field.type === "array") return [withRows(describeBase(field, at), field), ...walk(field.flattenedFields, [...path, "*"], readOnly)];
+		if (field.type === "blocks") return [withRows({
+			...describeBase(field, at),
+			blocks: blockSlugsOf(field)
+		}, field)];
+		return [describeLeaf(field, at)];
+	});
+	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 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) => {
@@ -126,4 +162,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, targetOf };

package/dist/tools/describe-schema.mjs

@@ -1,7 +1,8 @@
+import { translatorFor } from "../i18n.mjs";
 import { jsonResult } from "../endpoint/result.mjs";
 import { targetShape } from "./shared.mjs";
 import { refOf, resolveTarget } from "./target.mjs";
-import { describeNode, reachableSchemaPaths } from "../schema/describe.mjs";
+import { nodeDescriber, reachableSchemaPaths } from "../schema/describe.mjs";
 import { z } from "zod";
 //#region src/tools/describe-schema.ts
 const describeSchema = {
@@ -33,6 +34,7 @@ Fields Payload maintains (id, _status, createdAt, updatedAt) are never listed an
 	handler: (args, scope) => {
 		const ref = refOf(resolveTarget(scope, args, "read"));
 		const { config } = scope.req.payload;
+		const describeNode = nodeDescriber(translatorFor(scope.req.i18n));
 		const expanded = args.expand === true ? reachableSchemaPaths(config, ref) : void 0;
 		const nodes = (expanded?.paths ?? (args.paths && args.paths.length > 0 ? args.paths : [""])).map((schemaPath) => {
 			try {

package/dist/tools/list-capabilities.mjs

@@ -1,4 +1,4 @@
-import { staticDescription } from "../schema/walk.mjs";
+import { translatorFor } from "../i18n.mjs";
 import { jsonResult } from "../endpoint/result.mjs";
 import { translateLabel } from "./shared.mjs";
 import { hasDraftValidationEnabled } from "payload/shared";
@@ -16,12 +16,13 @@ A global is a singleton: it has no id, is not listed by findDocuments and cannot
 	inputSchema: () => ({}),
 	handler: (_args, scope) => {
 		const { payload } = scope.req;
+		const translate = translatorFor(scope.req.i18n);
 		const collections = scope.options.collections.flatMap((entry) => {
 			const capability = scope.capabilities.collections[entry.slug];
 			const collection = payload.collections[entry.slug];
 			if (!capability || !collection || !(capability.read || capability.write)) return [];
 			const { config } = collection;
-			const description = staticDescription(config.admin.description);
+			const description = translate(config.admin.description);
 			return [{
 				slug: entry.slug,
 				labels: {
@@ -40,7 +41,7 @@ A global is a singleton: it has no id, is not listed by findDocuments and cannot
 			const capability = scope.capabilities.globals[entry.slug];
 			const config = payload.globals.config.find((candidate) => candidate.slug === entry.slug);
 			if (!capability || !config || !(capability.read || capability.write)) return [];
-			const description = staticDescription(config.admin.description);
+			const description = translate(config.admin.description);
 			return [{
 				slug: entry.slug,
 				label: translateLabel(scope, config.label, entry.slug),

package/dist/tools/shared.mjs

@@ -1,3 +1,4 @@
+import { translateStatic } from "../i18n.mjs";
 import { NotFound } from "payload";
 import { z } from "zod";
 //#region src/tools/shared.ts
@@ -90,9 +91,7 @@ const depthShape = (scope) => ({ depth: z.number().int().min(0).max(scope.option
 		i18n,
 		t
 	}) : label;
-	if (typeof resolved === "string") return resolved;
-	if (resolved && typeof resolved === "object") return resolved[i18n.language] ?? Object.values(resolved)[0] ?? fallback;
-	return fallback;
+	return translateStatic(resolved, i18n) ?? fallback;
 };
 //#endregion
 export { depthShape, idSchema, idShape, localeOf, localeShape, readTarget, slugEnum, targetShape, translateLabel };

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.8",
   "description": "Payload CMS plugin exposing a fixed, schema-aware MCP tool surface with draft-only writes and per-API-key capabilities.",
   "keywords": [
     "payload",