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

package/dist/write/patch.mjs

@@ -1,49 +1,53 @@
-import { JSON_POINTER_PATTERN, RESERVED_FIELD_NAMES, blockOf, describeAddressableFields, findBlocksField, splitPath } from "../schema/walk.mjs";
-import { validateWriteValue } from "../schema/shape.mjs";
+import { JSON_POINTER_PATTERN, RESERVED_FIELD_NAMES, blockOf, describeAddressableFields, findBlocksField, isIndexSegment, joinPath, splitPath } from "../schema/walk.mjs";
 import { resolveDataPointer } from "../schema/pointer.mjs";
+import { EMPTY_ROOT, validateWriteValue } from "../schema/shape.mjs";
+import "../schema/index.mjs";
 import { z } from "zod";
 import { Pointer, applyPatch } from "rfc6902";
 //#region src/write/patch.ts
-/**
-* One RFC 6902 operation as accepted by `patchDocument`.
-*/ const PATCH_OPERATION_SCHEMA = z.object({
-	from: z.string().regex(JSON_POINTER_PATTERN).optional(),
-	op: z.enum([
-		"add",
-		"copy",
-		"move",
-		"remove",
-		"replace",
-		"test"
-	]),
-	path: z.string().regex(JSON_POINTER_PATTERN),
-	value: z.unknown().optional()
-}).describe("An RFC 6902 operation.");
-/**
-* Whether a pointer touches a field Payload maintains.
-*/ const isReservedPointer = (pointer) => pointer.split("/").slice(1).some((segment) => RESERVED_FIELD_NAMES.has(segment));
-/**
-* The pointer an operation removes a value from, if it removes one at all.
-*/ const droppedPointer = (operation) => {
+const POINTER = z.string().regex(JSON_POINTER_PATTERN);
+/** Discriminated on `op`, so an operation carries only its own members. */ const PATCH_OPERATION_SCHEMA = z.discriminatedUnion("op", [
+	z.strictObject({
+		op: z.literal("add"),
+		path: POINTER,
+		value: z.unknown()
+	}),
+	z.strictObject({
+		op: z.literal("remove"),
+		path: POINTER
+	}),
+	z.strictObject({
+		op: z.literal("replace"),
+		path: POINTER,
+		value: z.unknown()
+	}),
+	z.strictObject({
+		from: POINTER,
+		op: z.literal("move"),
+		path: POINTER
+	}),
+	z.strictObject({
+		from: POINTER,
+		op: z.literal("copy"),
+		path: POINTER
+	}),
+	z.strictObject({
+		op: z.literal("test"),
+		path: POINTER,
+		value: z.unknown()
+	})
+]).describe("An RFC 6902 operation.");
+const isReservedPointer = (pointer) => pointer.split("/").slice(1).some((segment) => RESERVED_FIELD_NAMES.has(segment));
+const droppedPointer = (operation) => {
 	if (operation.op === "remove") return operation.path;
 	return operation.op === "move" ? operation.from : void 0;
 };
-/**
-* Whether a pointer addresses a list element rather than a field.
-*/ const isElementPointer = (pointer) => {
-	const last = pointer.split("/").pop() ?? "";
-	return last === "-" || /^\d+$/.test(last);
+const isElementPointer = (pointer) => {
+	return isIndexSegment(pointer.split("/").pop() ?? "");
 };
 const isPlainObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
-/**
-* A Lexical editor state. Its nodes manage their own ids, so it is never
-* descended into.
-*/ const isRichTextState = (value) => isPlainObject(value["root"]) && Array.isArray(value["root"]["children"]);
-/**
-* Visits every row in a value: a plain object that carries `blockType` or
-* sits directly inside an array. Rich text states manage their own nodes and
-* are never descended into.
-*/ const walkRows = (value, visit, isRow = false) => {
+/** Its nodes manage their own ids, so it is never descended into. */ const isRichTextState = (value) => isPlainObject(value["root"]) && Array.isArray(value["root"]["children"]);
+/** A row is a plain object carrying `blockType`, or one sitting in an array. */ const walkRows = (value, visit, isRow = false) => {
 	if (Array.isArray(value)) {
 		for (const entry of value) walkRows(entry, visit, true);
 		return;
@@ -76,10 +80,7 @@ const isPlainObject = (value) => typeof value === "object" && value !== null &&
 		delete row["id"];
 	});
 };
-/**
-* Drops every row id from a copy of `value`. Used on create, where no stored
-* row exists and any incoming id is client-invented.
-*/ const stripRowIds = (value) => {
+/** For create, where no stored row exists and any incoming id is invented. */ const stripRowIds = (value) => {
 	const next = structuredClone(value);
 	walkRows(next, (row) => {
 		delete row["id"];
@@ -87,71 +88,155 @@ const isPlainObject = (value) => typeof value === "object" && value !== null &&
 	return next;
 };
 /**
-* Applies a patch to a deep copy of the document, so a failing operation
-* leaves the original untouched and nothing partial is ever written.
-*/ const applyPatchToCopy = (doc, patches) => {
-	const next = structuredClone(doc);
-	const prepared = patches.map((operation) => {
-		const cloned = "value" in operation ? {
-			...operation,
-			value: structuredClone(operation.value)
-		} : operation;
-		if (cloned.op === "replace" && !isElementPointer(cloned.path) && Pointer.fromJSON(cloned.path).get(next) === void 0) return {
-			...cloned,
-			op: "add"
-		};
-		return cloned;
-	});
-	const problems = applyPatch(next, prepared).flatMap((error, index) => error ? [`patches[${String(index)}]: ${error.message}`] : []);
-	if (problems.length > 0) return { problems };
-	reconcileRowIds(next, doc);
-	return { next };
+* The operation as it is applied: values are cloned so the written document
+* never shares references with the caller's operations, and a `replace` of a
+* field the target locale has no value for becomes an `add`, which is what
+* RFC 6902 requires when nothing is there to replace.
+*/ const prepare = (operation, doc) => {
+	const cloned = "value" in operation ? {
+		...operation,
+		value: structuredClone(operation.value)
+	} : operation;
+	return cloned.op === "replace" && !isElementPointer(cloned.path) && Pointer.fromJSON(cloned.path).get(doc) === void 0 ? {
+		...cloned,
+		op: "add"
+	} : cloned;
+};
+/** The one it carries, or the one it takes from `from`. `remove` writes nothing. */ const effectiveValue = (operation, doc) => {
+	if ("value" in operation) return operation.value;
+	return "from" in operation ? Pointer.fromJSON(operation.from).get(doc) : void 0;
+};
+/** A pointer stopping short addresses a subtree; the fields beneath decide. */ const resolvesReadOnly = (resolution) => {
+	if (resolution.readOnly) return true;
+	if (resolution.descriptor) return resolution.descriptor.readOnly === true;
+	const below = describeAddressableFields(resolution.fields).filter((descriptor) => resolution.prefix.every((part, offset) => part === splitPath(descriptor.path)[offset]));
+	return below.length > 0 && below.every((descriptor) => descriptor.readOnly);
+};
+/** An element has no descriptor, so its field is read one segment up. */ const isReadOnlyPointer = (config, target) => resolvesReadOnly(resolveDataPointer(config, {
+	doc: target.doc,
+	pointer: isElementPointer(target.pointer) ? joinPath(splitPath(target.pointer).slice(0, -1)) : target.pointer,
+	ref: target.ref
+}));
+/** Unresolvable pointers say nothing here; the caller reports them anyway. */ const resolutionAt = (config, target) => {
+	try {
+		return resolveDataPointer(config, {
+			doc: target.doc,
+			pointer: target.pointer,
+			ref: target.ref
+		});
+	} catch {
+		return;
+	}
 };
 /**
-* Checks every operation against the schema before any is applied.
-*
-* A partially applied batch is worse than a refused one, so this returns all
-* problems and the caller applies nothing unless the list is empty.
-*/ const findPatchProblems = (config, target) => target.patches.flatMap((operation, index) => {
-	const at = `patches[${String(index)}]`;
-	const pointers = [operation.path, ..."from" in operation && operation.from ? [operation.from] : []];
-	if (pointers.includes("")) return [`${at}: an empty pointer addresses the whole document. Address a field instead.`];
+* Removing a field does nothing, but removing part of an editor state does
+* something, and something worse: a node written without the properties its
+* class hydrates from throws when the admin editor opens it. Both are refused,
+* and only the reason differs.
+*/ const droppedFieldProblem = (config, target) => {
+	const resolution = resolutionAt(config, target);
+	const lexical = resolution?.lexical;
+	if (lexical?.kind === "property") return `"${target.pointer}" is a node property, not a list element. A "${lexical.nodeType}" node needs it, so replace it rather than removing it.`;
+	if (lexical ?? resolution?.inLexical) return `"${target.pointer}" sits inside an editor state, which is written whole, so removing it would take effect and leave a node the admin editor cannot open. Replace it instead, or remove the node that holds it.`;
+	return `"${target.pointer}" is a field, not a list element, and removing it would do nothing. The patched document is written whole, and Payload keeps any field absent from a write rather than clearing it. Use "replace" with null to clear a field, or with [] to empty a list.`;
+};
+/**
+* Dropping the only node under a root empties the state, which Lexical refuses
+* to hydrate. Checked here rather than on the written value, because a
+* `remove` carries none.
+*/ const emptiesTheRoot = (config, target) => {
+	const list = joinPath(splitPath(target.pointer).slice(0, -1));
+	const owner = resolutionAt(config, {
+		...target,
+		pointer: list
+	})?.lexical;
+	if (owner?.kind !== "nodes" || owner.isRoot !== true) return false;
+	const nodes = Pointer.fromJSON(list).get(target.doc);
+	return Array.isArray(nodes) && nodes.length === 1;
+};
+/**
+* Checked against the document as it stands when this operation runs: both
+* pointers must resolve, the written value must pass write validation, and what
+* it drops must not sit in a read-only field.
+*/ const findOperationProblems = (config, target) => {
+	const { doc, operation, ref } = target;
+	const pointers = [operation.path, ..."from" in operation ? [operation.from] : []];
+	if (pointers.includes("")) return ["an empty pointer addresses the whole document. Address a field instead."];
 	const reserved = pointers.find(isReservedPointer);
-	if (reserved !== void 0) return [`${at}: "${reserved}" addresses a field Payload maintains. Drafts are the only thing this tool writes, and id, _status, createdAt and updatedAt are not writable.`];
+	if (reserved !== void 0) return [`"${reserved}" addresses a field Payload maintains. This tool only ever writes drafts, and id, _status, createdAt and updatedAt are not writable; use publishDocument to publish.`];
 	const dropped = droppedPointer(operation);
-	if (dropped !== void 0 && !isElementPointer(dropped)) return [`${at}: "${dropped}" is a field, not a list element, and removing it would do nothing. The patched document is written whole, and Payload keeps any field absent from a write rather than clearing it. Use "replace" with null to clear a field, or with [] to empty a list.`];
-	const value = "value" in operation ? operation.value : void 0;
+	if (dropped !== void 0 && !isElementPointer(dropped)) return [droppedFieldProblem(config, {
+		doc,
+		pointer: dropped,
+		ref
+	})];
 	try {
-		const moved = "from" in operation && operation.from ? Pointer.fromJSON(operation.from).get(target.doc) : void 0;
+		const value = effectiveValue(operation, doc);
+		if (value !== void 0 && operation.op !== "test" && isReadOnlyPointer(config, {
+			doc,
+			pointer: operation.path,
+			ref
+		})) return [`"${operation.path}" is read-only and cannot be written.`];
+		if (dropped !== void 0 && isReadOnlyPointer(config, {
+			doc,
+			pointer: dropped,
+			ref
+		})) return [`"${dropped}" sits in a read-only field and cannot be removed.`];
+		if (dropped !== void 0 && emptiesTheRoot(config, {
+			doc,
+			pointer: dropped,
+			ref
+		})) return [`"${dropped}": ${EMPTY_ROOT}`];
 		for (const pointer of pointers) {
 			const resolution = resolveDataPointer(config, {
-				addedValue: value ?? moved,
-				doc: target.doc,
+				addedValue: value,
+				doc,
 				pointer,
-				ref: target.ref
+				ref
 			});
-			if (pointer === operation.path && value !== void 0) return validateWriteValue(config, {
-				pointer,
-				resolution
-			}, value).map((problem) => `${at}: ${problem}`);
+			if (pointer === operation.path && value !== void 0) {
+				const problems = validateWriteValue(config, {
+					pointer,
+					resolution
+				}, value);
+				if (problems.length > 0) return problems;
+			}
 		}
 		return [];
 	} catch (error) {
-		return [`${at}: ${error instanceof Error ? error.message : "invalid"}`];
+		return [error instanceof Error ? error.message : "invalid"];
 	}
-});
+};
 /**
-* Keys Payload manages on a row that travel back into the write unchanged.
-*/ const ROW_KEYS = /* @__PURE__ */ new Set([
+* One evolving copy, so an operation depending on an earlier one resolves
+* against the shape it actually modifies, and a failure leaves the original
+* untouched. The caller writes nothing unless the whole batch came back
+* applied, so a partial batch is never persisted.
+*/ const applyPatchOperations = (config, target) => {
+	const next = structuredClone(target.doc);
+	for (const [index, operation] of target.patches.entries()) {
+		const at = `patches[${String(index)}]`;
+		const problems = findOperationProblems(config, {
+			doc: next,
+			operation,
+			ref: target.ref
+		});
+		if (problems.length > 0) return { problems: problems.map((problem) => `${at}: ${problem}`) };
+		const [error] = applyPatch(next, [prepare(operation, next)]);
+		if (error) return { problems: [`${at}: ${error.message}`] };
+	}
+	reconcileRowIds(next, target.doc);
+	return { next };
+};
+const ROW_KEYS = /* @__PURE__ */ new Set([
 	"blockName",
 	"blockType",
 	"id"
 ]);
 /**
-* Picks the keys the schema walker describes out of `value`, descending into
-* groups, named tabs, arrays and blocks. Everything Payload maintains or
-* derives (`_status`, timestamps, join and virtual fields, upload base fields)
-* is left out, so the write-back carries only what a client could have set.
+* Everything Payload maintains or derives (`_status`, timestamps, join and
+* virtual fields, upload base fields) 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 = describeAddressableFields(fields).flatMap((descriptor) => {
@@ -205,10 +290,7 @@ const isPlainObject = (value) => typeof value === "object" && value !== null &&
 	}
 	return result;
 };
-/**
-* The data handed to `payload.update` after a patch: the patched document
-* reduced to the fields the client may write, plus row identity keys.
-*/ const buildWriteData = (config, target, doc) => {
+/** The patched document reduced to writable fields, plus row identity keys. */ const buildWriteData = (config, target, doc) => {
 	return pickDescribed(config, doc, {
 		fields: target.flattenedFields,
 		prefix: [],
@@ -216,4 +298,4 @@ const isPlainObject = (value) => typeof value === "object" && value !== null &&
 	});
 };
 //#endregion
-export { PATCH_OPERATION_SCHEMA, applyPatchToCopy, buildWriteData, droppedPointer, findPatchProblems, isElementPointer, isReservedPointer, stripRowIds };
+export { PATCH_OPERATION_SCHEMA, applyPatchOperations, buildWriteData, droppedPointer, isElementPointer, isReservedPointer, stripRowIds };

package/dist/write/publish-blockers.mjs

@@ -1,23 +1,21 @@
 import { pointerFromPayloadPath } from "../schema/walk.mjs";
+import "../schema/index.mjs";
 import { beforeChangeTraverseFields, beforeValidateTraverseFields } from "payload";
 //#region src/write/publish-blockers.ts
 /**
 * Runs Payload's own field validation over a draft without saving anything.
 *
-* Draft saves skip validation unless `versions.drafts.validate` is set, so an
-* agent building a document incrementally gets no signal until a human presses
-* Publish. This is the same traversal a real save runs, exported from
-* `payload`, called with `skipValidation: false` so it collects into `errors`
-* instead of throwing. The `beforeValidate` pass runs first because some field
-* hooks (Lexical's) prepare state in `context` that their `beforeChange`
-* counterpart depends on.
+* The same traversal a real save runs, exported from `payload` and called with
+* `skipValidation: false` so it collects into `errors` instead of throwing. The
+* `beforeValidate` pass runs first because some field hooks (Lexical's) prepare
+* state in `context` that their `beforeChange` counterpart depends on.
 *
 * Nothing is written: `data` is a copy, the context is a scratch copy and the
 * locale merge actions are discarded. `overrideAccess` is true because the
 * question is "could this be published", not "may this client write it".
 *
-* Limits: only the locale the doc was read in is checked, and field-level
-* `beforeChange` hooks run again, which is safe only for pure ones.
+* `unavailable` marks a traversal that threw, which is not the same answer as a
+* document with nothing wrong with it.
 */ const collectPublishBlockers = async (req, target) => {
 	const { doc, entity } = target;
 	const id = doc["id"];
@@ -62,13 +60,16 @@ import { beforeChangeTraverseFields, beforeValidateTraverseFields } from "payloa
 		});
 	} catch (error) {
 		req.payload.logger.warn(`[payloadcms-mcpx] Could not validate the ${entity.slug} draft: ${error instanceof Error ? error.message : "unknown error"}`);
-		return [];
+		return {
+			blockers: [],
+			unavailable: true
+		};
 	}
-	return errors.map((error) => ({
+	return { blockers: errors.map((error) => ({
 		message: error.message,
 		path: pointerFromPayloadPath(error.path),
 		...typeof error.label === "string" ? { field: error.label } : {}
-	}));
+	})) };
 };
 //#endregion
 export { collectPublishBlockers };

package/dist/write/publish-intent.mjs

@@ -0,0 +1,17 @@
+import { randomUUID } from "node:crypto";
+//#region src/write/publish-intent.ts
+const PUBLISH_INTENT = "__mcpxPublishIntent";
+const TOKEN = randomUUID();
+const withPublishIntent = (data) => ({
+	...data,
+	[PUBLISH_INTENT]: TOKEN
+});
+const carries = (data) => typeof data === "object" && data !== null && data[PUBLISH_INTENT] === TOKEN;
+const hasPublishIntent = (data) => carries(data);
+/** Asked by the last hook that needs it, so it takes the marker off. */ const takePublishIntent = (data) => {
+	if (!carries(data)) return false;
+	delete data[PUBLISH_INTENT];
+	return true;
+};
+//#endregion
+export { hasPublishIntent, takePublishIntent, withPublishIntent };

package/dist/write/transaction.mjs

@@ -1,9 +1,14 @@
 import { commitTransaction, initTransaction, killTransaction } from "payload";
 //#region src/write/transaction.ts
 /**
-* Runs `fn` inside one database transaction on `req`, so a read followed by a
-* write cannot interleave with another writer. Adapters without transaction
-* support, or a request that already owns one, run `fn` as is.
+* Adapters without transaction support, or a request that already owns one, run
+* `fn` as is.
+*
+* Atomicity, not isolation: neither SQLite nor Postgres at read committed locks
+* the row on the read, so an `expectedUpdatedAt` check remains best effort. Nor
+* is this safe across the tool calls of one JSON-RPC batch, which share a
+* request: the second caller joins the first's transaction, so one tool's
+* rollback takes the other's work with it.
 */ const withTransaction = async (req, fn) => {
 	if (!await initTransaction(req)) return await fn();
 	try {

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@abinnovision/payloadcms-mcpx",
-  "version": "1.0.0-beta.8",
+  "version": "1.0.0",
   "description": "Payload CMS plugin exposing a fixed, schema-aware MCP tool surface with draft-only writes and per-API-key capabilities.",
   "keywords": [
     "payload",
@@ -26,6 +26,10 @@
     ".": {
       "types": "./dist/index.d.mts",
       "default": "./dist/index.mjs"
+    },
+    "./client": {
+      "types": "./dist/client/index.d.mts",
+      "default": "./dist/client/index.mjs"
     }
   },
   "files": [
@@ -35,17 +39,17 @@
   ],
   "scripts": {
     "build": "tsdown",
-    "format:check": "prettier --check 'src/**/*.ts' 'test/**/*.ts' '*.{json{,5},md,y{,a}ml}'",
-    "format:fix": "prettier --write 'src/**/*.ts' 'test/**/*.ts' '*.{json{,5},md,y{,a}ml}'",
-    "lint:check": "eslint 'src/**/*.ts' 'test/**/*.ts'",
-    "lint:fix": "eslint 'src/**/*.ts' 'test/**/*.ts' --fix",
+    "format:check": "prettier --check 'src/**/*.{ts,tsx}' 'test/**/*.ts' '*.{json{,5},md,y{,a}ml}'",
+    "format:fix": "prettier --write 'src/**/*.{ts,tsx}' 'test/**/*.ts' '*.{json{,5},md,y{,a}ml}'",
+    "lint:check": "eslint 'src/**/*.{ts,tsx}' 'test/**/*.ts'",
+    "lint:fix": "eslint 'src/**/*.{ts,tsx}' 'test/**/*.ts' --fix",
     "test-integration": "vitest --run --config test/integration/vitest.config.mts",
     "test-unit": "vitest --run --coverage --config vitest.config.mts",
     "test-unit:watch": "vitest --config vitest.config.mts",
     "typecheck": "tsc --noEmit"
   },
   "lint-staged": {
-    "{src,test}/**/*.ts": [
+    "{src,test}/**/*.{ts,tsx}": [
       "eslint --fix",
       "prettier --write"
     ],
@@ -63,11 +67,12 @@
     "@arethetypeswrong/core": "^0.18.5",
     "@payloadcms/db-sqlite": "3.88.0",
     "@payloadcms/richtext-lexical": "3.88.0",
+    "@payloadcms/ui": "3.88.0",
     "@swc/core": "^1.16.1",
-    "@types/node": "^26.2.0",
+    "@types/node": "^26.3.0",
     "@types/react": "^19.2.18",
     "@vitest/coverage-v8": "^4.1.10",
-    "eslint": "^10.7.0",
+    "eslint": "^10.9.1",
     "payload": "3.88.0",
     "prettier": "^3.9.5",
     "publint": "^0.3.24",
@@ -79,7 +84,17 @@
     "vitest": "^4.1.10"
   },
   "peerDependencies": {
-    "payload": ">=3.88.0 <4"
+    "@payloadcms/ui": ">=3.88.0 <4",
+    "payload": ">=3.88.0 <4",
+    "react": "^19"
+  },
+  "peerDependenciesMeta": {
+    "@payloadcms/ui": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    }
   },
   "publishConfig": {
     "ghpr": true,

package/dist/i18n.d.mts

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

package/dist/options.d.mts

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

package/dist/schema/lexical.d.mts

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

package/dist/schema/walk.d.mts

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

package/dist/tools/target.d.mts

@@ -1,3 +0,0 @@
-import "./types.mjs";
-import "../schema/walk.mjs";
-import "payload";

package/dist/tools/types.d.mts

@@ -1,5 +0,0 @@
-import "../types.mjs";
-import "../options.mjs";
-import { PayloadRequest } from "payload";
-import { z } from "zod";
-import { CallToolResult, ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";

package/dist/write/publish-blockers.d.mts

@@ -1,15 +0,0 @@
-import "../tools/target.mjs";
-import { PayloadRequest } from "payload";
-//#region src/write/publish-blockers.d.ts
-/**
- * One reason a human could not publish the draft as it stands.
- */
-interface PublishBlocker {
-  /** Resolved field label path, e.g. "Layout > Block 2 (Hero) > Title". */
-  field?: string;
-  message: string;
-  /** JSON Pointer to the offending value, e.g. "/layout/2/title". */
-  path: string;
-}
-//#endregion
-export type { PublishBlocker };