@abinnovision/payloadcms-mcpx 1.1.0-beta.6 → 2.0.0-beta.10

package/dist/write/patch.mjs

@@ -1,98 +1,21 @@
-import { JSON_POINTER_PATTERN, RESERVED_FIELD_NAMES, blockOf, describeAddressableFields, findBlocksField, isIndexSegment, joinPath, splitPath } from "../schema/walk.mjs";
+import { isIndexSegment, joinPath, prototypeSegmentProblem, splitPath } from "../schema/path.mjs";
+import { RESERVED_FIELD_NAMES, descriptorsUnder } from "../schema/walk.mjs";
+import { SchemaError } from "../schema/errors.mjs";
 import { resolveDataPointer } from "../schema/pointer.mjs";
 import { EMPTY_ROOT, validateWriteValue } from "../schema/shape.mjs";
 import "../schema/index.mjs";
-import { z } from "zod";
+import { reconcileRowIds } from "./row-ids.mjs";
 import { Pointer, applyPatch } from "rfc6902";
 //#region src/write/patch.ts
-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 isReservedPointer = (pointer) => splitPath(pointer).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;
 };
 const isElementPointer = (pointer) => {
-	return isIndexSegment(pointer.split("/").pop() ?? "");
+	return isIndexSegment(splitPath(pointer).at(-1) ?? "");
 };
-const isPlainObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
-/** 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;
-	}
-	if (!isPlainObject(value) || isRichTextState(value)) return;
-	if (isRow || typeof value["blockType"] === "string") visit(value);
-	for (const entry of Object.values(value)) walkRows(entry, visit);
-};
-/**
-* Keeps a row id only when the stored document already has it and no earlier
-* row in the write claimed it; every other id is dropped so Payload assigns a
-* fresh one.
-*
-* A kept id makes Payload update the row in place, which preserves the other
-* locales of any localized field inside it. A duplicated id (a copied row) or
-* an id from elsewhere would violate a SQL primary key, so those never pass.
-*/ const reconcileRowIds = (next, stored) => {
-	const known = /* @__PURE__ */ new Set();
-	walkRows(stored, (row) => {
-		if (row["id"] !== void 0) known.add(row["id"]);
-	});
-	const seen = /* @__PURE__ */ new Set();
-	walkRows(next, (row) => {
-		const id = row["id"];
-		if (id === void 0) return;
-		if (known.has(id) && !seen.has(id)) {
-			seen.add(id);
-			return;
-		}
-		delete row["id"];
-	});
-};
-/** 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"];
-	});
-	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 prepare = (operation, doc) => {
 	const cloned = "value" in operation ? {
 		...operation,
 		value: structuredClone(operation.value)
@@ -102,49 +25,41 @@ const isPlainObject = (value) => typeof value === "object" && value !== null &&
 		op: "add"
 	} : cloned;
 };
-/** The one it carries, or the one it takes from `from`. `remove` writes nothing. */ const effectiveValue = (operation, doc) => {
+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) => {
+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);
+	const below = descriptorsUnder(resolution.fields, resolution.prefix);
+	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, {
+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) => {
+const resolutionAt = (config, target) => {
 	try {
 		return resolveDataPointer(config, {
 			doc: target.doc,
 			pointer: target.pointer,
 			ref: target.ref
 		});
-	} catch {
+	} catch (error) {
+		if (!(error instanceof SchemaError)) throw error;
 		return;
 	}
 };
-/**
-* 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 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 emptiesTheRoot = (config, target) => {
 	const list = joinPath(splitPath(target.pointer).slice(0, -1));
 	const owner = resolutionAt(config, {
 		...target,
@@ -154,16 +69,14 @@ const isPlainObject = (value) => typeof value === "object" && value !== null &&
 	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 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 prototyped = pointers.map(prototypeSegmentProblem).find((problem) => problem !== void 0);
+	if (prototyped !== void 0) return [prototyped];
 	const reserved = pointers.find(isReservedPointer);
-	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.`];
+	if (reserved !== void 0) return [`"${reserved}" addresses a field Payload maintains. id, _status, createdAt and updatedAt are not writable, and "_status" changes only when a draft is published.`];
 	const dropped = droppedPointer(operation);
 	if (dropped !== void 0 && !isElementPointer(dropped)) return [droppedFieldProblem(config, {
 		doc,
@@ -204,14 +117,14 @@ const isPlainObject = (value) => typeof value === "object" && value !== null &&
 		}
 		return [];
 	} catch (error) {
-		return [error instanceof Error ? error.message : "invalid"];
+		if (!(error instanceof SchemaError)) throw error;
+		return [error.message];
 	}
 };
 /**
-* 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.
+* Works on one evolving copy, so each operation resolves against the result of
+* the earlier ones and a failure leaves the original untouched. The caller
+* writes only when the whole batch applied, so a partial batch is never saved.
 */ const applyPatchOperations = (config, target) => {
 	const next = structuredClone(target.doc);
 	for (const [index, operation] of target.patches.entries()) {
@@ -228,74 +141,5 @@ const isPlainObject = (value) => typeof value === "object" && value !== null &&
 	reconcileRowIds(next, target.doc);
 	return { next };
 };
-const ROW_KEYS = /* @__PURE__ */ new Set([
-	"blockName",
-	"blockType",
-	"id"
-]);
-/**
-* 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) => {
-		const parts = splitPath(descriptor.path);
-		return prefix.every((part, offset) => part === parts[offset]) ? [{
-			descriptor,
-			parts: parts.slice(prefix.length)
-		}] : [];
-	});
-	const result = {};
-	if (isRow) {
-		for (const key of ROW_KEYS) if (key in value) result[key] = value[key];
-	}
-	for (const [key, entry] of Object.entries(value)) {
-		const candidates = relative.filter(({ parts }) => parts[0] === key);
-		if (candidates.length === 0) continue;
-		const exact = candidates.find(({ parts }) => parts.length === 1);
-		if (exact?.descriptor.type === "blocks" && Array.isArray(entry)) {
-			const field = findBlocksField(fields, splitPath(exact.descriptor.path));
-			result[key] = entry.map((row) => {
-				const block = field && isPlainObject(row) && typeof row["blockType"] === "string" ? blockOf(config, field, row["blockType"]) : void 0;
-				return block && isPlainObject(row) ? pickDescribed(config, row, {
-					fields: block.flattenedFields,
-					prefix: [],
-					isRow: true
-				}) : row;
-			});
-			continue;
-		}
-		if (exact) {
-			result[key] = entry;
-			continue;
-		}
-		if (candidates.some(({ parts }) => parts[1] === "*")) {
-			result[key] = Array.isArray(entry) ? entry.map((row) => isPlainObject(row) ? pickDescribed(config, row, {
-				fields,
-				prefix: [
-					...prefix,
-					key,
-					"*"
-				],
-				isRow: true
-			}) : row) : entry;
-			continue;
-		}
-		result[key] = isPlainObject(entry) ? pickDescribed(config, entry, {
-			fields,
-			prefix: [...prefix, key],
-			isRow: false
-		}) : entry;
-	}
-	return result;
-};
-/** The patched document reduced to writable fields, plus row identity keys. */ const buildWriteData = (config, target, doc) => {
-	return pickDescribed(config, doc, {
-		fields: target.flattenedFields,
-		prefix: [],
-		isRow: false
-	});
-};
 //#endregion
-export { PATCH_OPERATION_SCHEMA, applyPatchOperations, buildWriteData, droppedPointer, isElementPointer, isReservedPointer, stripRowIds };
+export { applyPatchOperations, droppedPointer, isElementPointer, isReservedPointer };

package/dist/write/publish-blockers.mjs

@@ -1,21 +1,14 @@
-import { pointerFromPayloadPath } from "../schema/walk.mjs";
+import { pointerFromPayloadPath } from "../schema/path.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.
-*
-* 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".
-*
-* `unavailable` marks a traversal that threw, which is not the same answer as a
-* document with nothing wrong with it.
+* Payload's field validation over a draft, without saving: `data` and the
+* context are copies. `beforeValidate` runs first because some field hooks
+* (Lexical's) prepare `context` state that `beforeChange` needs. Access is
+* overridden because the question is whether the draft could be published, not
+* whether this client may write it. `unavailable` means the traversal threw,
+* which is not the same as a clean document.
 */ const collectPublishBlockers = async (req, target) => {
 	const { doc, entity } = target;
 	const id = doc["id"];

package/dist/write/publish-intent.mjs

@@ -1,3 +1,4 @@
+import { isPlainObject } from "../guards.mjs";
 import { randomUUID } from "node:crypto";
 //#region src/write/publish-intent.ts
 const PUBLISH_INTENT = "__mcpxPublishIntent";
@@ -6,10 +7,11 @@ 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;
+const hasPublishIntent = (data) => isPlainObject(data) && data[PUBLISH_INTENT] === TOKEN;
+/**
+* Called by the last hook that needs the marker, which removes it.
+*/ const takePublishIntent = (data) => {
+	if (!hasPublishIntent(data)) return false;
 	delete data[PUBLISH_INTENT];
 	return true;
 };

package/dist/write/row-ids.mjs

@@ -0,0 +1,46 @@
+import { isPlainObject } from "../guards.mjs";
+//#region src/write/row-ids.ts
+const isRichTextState = (value) => isPlainObject(value["root"]) && Array.isArray(value["root"]["children"]);
+const walkRows = (value, visit, isRow = false) => {
+	if (Array.isArray(value)) {
+		for (const entry of value) walkRows(entry, visit, true);
+		return;
+	}
+	if (!isPlainObject(value) || isRichTextState(value)) return;
+	if (isRow || typeof value["blockType"] === "string") visit(value);
+	for (const entry of Object.values(value)) walkRows(entry, visit);
+};
+/**
+* Keeps a row id only when the stored document has it and no earlier row in the
+* write claimed it. Other ids are dropped so Payload assigns a fresh one.
+*
+* A kept id makes Payload update the row in place, which preserves the other
+* locales of localized fields inside it. A duplicated id (a copied row) or a
+* foreign id would violate a SQL primary key.
+*/ const reconcileRowIds = (next, stored) => {
+	const known = /* @__PURE__ */ new Set();
+	walkRows(stored, (row) => {
+		if (row["id"] !== void 0) known.add(row["id"]);
+	});
+	const seen = /* @__PURE__ */ new Set();
+	walkRows(next, (row) => {
+		const id = row["id"];
+		if (id === void 0) return;
+		if (known.has(id) && !seen.has(id)) {
+			seen.add(id);
+			return;
+		}
+		delete row["id"];
+	});
+};
+/**
+* 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"];
+	});
+	return next;
+};
+//#endregion
+export { reconcileRowIds, stripRowIds };

package/dist/write/transaction.mjs

@@ -1,14 +1,11 @@
 import { commitTransaction, initTransaction, killTransaction } from "payload";
 //#region src/write/transaction.ts
 /**
-* 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.
+* Adapters without transaction support, or a request that already owns one,
+* run `fn` as is. This gives atomicity, not isolation: SQLite and Postgres at
+* read committed do not lock the row on read, so an `expectedUpdatedAt` check
+* stays best effort. Tool calls in one JSON-RPC batch run one after another, so
+* each owns its transaction and a rollback never undoes another call.
 */ const withTransaction = async (req, fn) => {
 	if (!await initTransaction(req)) return await fn();
 	try {

package/dist/write/write-data.mjs

@@ -0,0 +1,64 @@
+import { isPlainObject } from "../guards.mjs";
+import { splitPath } from "../schema/path.mjs";
+import { ROW_KEYS, blockOf, descriptorsUnder, findBlocksField } from "../schema/walk.mjs";
+import "../schema/index.mjs";
+//#region src/write/write-data.ts
+const pickDescribed = (config, value, at) => {
+	const { fields, prefix, isRow } = at;
+	const relative = descriptorsUnder(fields, prefix);
+	const result = {};
+	if (isRow) {
+		for (const key of ROW_KEYS) if (Object.hasOwn(value, key)) result[key] = value[key];
+	}
+	for (const [key, entry] of Object.entries(value)) {
+		const candidates = relative.filter(({ parts }) => parts[0] === key);
+		if (candidates.length === 0) continue;
+		const exact = candidates.find(({ parts }) => parts.length === 1);
+		if (exact?.descriptor.type === "blocks" && Array.isArray(entry)) {
+			const field = findBlocksField(fields, splitPath(exact.descriptor.path));
+			result[key] = entry.map((row) => {
+				const block = field && isPlainObject(row) && typeof row["blockType"] === "string" ? blockOf(config, field, row["blockType"]) : void 0;
+				return block && isPlainObject(row) ? pickDescribed(config, row, {
+					fields: block.flattenedFields,
+					prefix: [],
+					isRow: true
+				}) : row;
+			});
+			continue;
+		}
+		if (exact) {
+			result[key] = entry;
+			continue;
+		}
+		if (candidates.some(({ parts }) => parts[1] === "*")) {
+			result[key] = Array.isArray(entry) ? entry.map((row) => isPlainObject(row) ? pickDescribed(config, row, {
+				fields,
+				prefix: [
+					...prefix,
+					key,
+					"*"
+				],
+				isRow: true
+			}) : row) : entry;
+			continue;
+		}
+		result[key] = isPlainObject(entry) ? pickDescribed(config, entry, {
+			fields,
+			prefix: [...prefix, key],
+			isRow: false
+		}) : entry;
+	}
+	return result;
+};
+/**
+* The patched document reduced to writable fields, plus row identity keys.
+* `target` is a sanitized collection or global alike.
+*/ const buildWriteData = (config, target, doc) => {
+	return pickDescribed(config, doc, {
+		fields: target.flattenedFields,
+		prefix: [],
+		isRow: false
+	});
+};
+//#endregion
+export { buildWriteData };

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@abinnovision/payloadcms-mcpx",
-  "version": "1.1.0-beta.6",
+  "version": "2.0.0-beta.10",
   "description": "Payload CMS plugin exposing a fixed, schema-aware MCP tool surface with draft-only writes and per-API-key capabilities.",
   "keywords": [
     "payload",
@@ -27,9 +27,9 @@
       "types": "./dist/index.d.mts",
       "default": "./dist/index.mjs"
     },
-    "./client": {
-      "types": "./dist/client/index.d.mts",
-      "default": "./dist/client/index.mjs"
+    "./admin": {
+      "types": "./dist/admin/index.d.mts",
+      "default": "./dist/admin/index.mjs"
     }
   },
   "files": [
@@ -65,6 +65,7 @@
     "@abinnovision/eslint-config-base": "^3.4.2",
     "@abinnovision/prettier-config": "^2.2.0",
     "@arethetypeswrong/core": "^0.18.5",
+    "@internal/test-utils": "0.0.0",
     "@payloadcms/db-sqlite": "3.89.0",
     "@payloadcms/richtext-lexical": "3.89.0",
     "@payloadcms/ui": "3.89.0",
@@ -101,4 +102,4 @@
     "npm": true,
     "npmAccess": "public"
   }
-}
+}

package/dist/client/capability-matrix.d.mts

@@ -1,26 +0,0 @@
-import { CapabilityMatrix } from "../api-keys/capability-matrix.mjs";
-import React from "react";
-//#region src/client/capability-matrix.d.ts
-interface McpxCapabilityMatrixProps {
-  /** Built from the plugin options at config time. */
-  matrix: CapabilityMatrix;
-  /** The group's own config, supplied by Payload. Carries the description. */
-  field?: {
-    admin?: {
-      description?: unknown;
-    };
-  };
-  /** The `capabilities` group's own path, supplied by Payload. */
-  path?: string;
-  readOnly?: boolean;
-  /** Whether the key form is split into tabs, from the plugin options. */
-  withinTab?: boolean;
-}
-/**
- * What an API key may do, as one table per namespace: a row per entity, a
- * column per operation, and a bulk toggle in each column header. The nested
- * checkbox fields this replaces still back every cell, so the stored document
- * is unchanged; only the rendering is.
- */
-export declare const McpxCapabilityMatrix: React.FC<McpxCapabilityMatrixProps>;
-//#endregion