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

package/README.md

@@ -163,8 +163,9 @@ Rules the tools enforce and explain in their own descriptions:
   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/walk.d.mts

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

package/dist/schema/walk.mjs

@@ -1,4 +1,5 @@
 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,8 +58,8 @@ 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;
@@ -109,21 +102,34 @@ const withRows = (descriptor, field) => ({
 * 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") {
-		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)
-	}, field)];
-	return [describeLeaf(field, joinPath(path), readOnly)];
-});
+*
+* `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
@@ -156,4 +162,4 @@ const targetOf = (config, ref) => {
 	return found;
 };
 //#endregion
-export { JSON_POINTER_PATTERN, RESERVED_FIELD_NAMES, blockOf, blockSlugsOf, describeAddressableFields, 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/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@abinnovision/payloadcms-mcpx",
-  "version": "1.0.0-beta.7",
+  "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",