@abinnovision/payloadcms-mcpx 1.0.0-beta.3

package/dist/capabilities.mjs

@@ -0,0 +1,30 @@
+//#region src/capabilities.ts
+/** Name of the capability group on the key document. */ const CAPABILITIES_FIELD = "capabilities";
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const flag = (group, name) => isRecord(group) && group[name] === true;
+/**
+* Capabilities in force for a key: the plugin config decides what can exist,
+* the key's checkboxes decide what does. A missing checkbox is `false`, so keys
+* issued before a capability existed stay closed.
+*/ const resolveCapabilities = (options, keyCapabilities) => {
+	const collectionsGroup = isRecord(keyCapabilities) ? keyCapabilities["collections"] : void 0;
+	const toolsGroup = isRecord(keyCapabilities) ? keyCapabilities["tools"] : void 0;
+	const collections = {};
+	for (const collection of options.collections) {
+		const group = isRecord(collectionsGroup) ? collectionsGroup[collection.fieldName] : void 0;
+		collections[collection.slug] = {
+			read: collection.read && flag(group, "read"),
+			write: collection.write && flag(group, "write")
+		};
+	}
+	const tools = {};
+	for (const tool of options.tools) tools[tool.name] = flag(toolsGroup, tool.name);
+	return {
+		collections,
+		tools
+	};
+};
+const readableSlugs = (capabilities) => Object.entries(capabilities.collections).filter(([, value]) => value.read).map(([slug]) => slug);
+const writableSlugs = (capabilities) => Object.entries(capabilities.collections).filter(([, value]) => value.write).map(([slug]) => slug);
+//#endregion
+export { CAPABILITIES_FIELD, readableSlugs, resolveCapabilities, writableSlugs };

package/dist/endpoint/handler.mjs

@@ -0,0 +1,84 @@
+import { readableSlugs, resolveCapabilities, writableSlugs } from "../capabilities.mjs";
+import { resolveApiKeyAuth } from "../auth/resolve.mjs";
+import { jsonRpcError } from "./result.mjs";
+import { createMcpServer } from "./server.mjs";
+import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
+//#region src/endpoint/handler.ts
+const buildScope = (req, options, capabilities) => {
+	const { localization } = req.payload.config;
+	return {
+		req,
+		options,
+		capabilities,
+		readable: readableSlugs(capabilities),
+		writable: writableSlugs(capabilities),
+		locales: localization ? localization.localeCodes : null,
+		defaultLocale: localization ? localization.defaultLocale : null
+	};
+};
+/**
+* Answers GET and DELETE on the endpoint path. The server is stateless and
+* never streams, so only POST carries meaning.
+*/ const methodNotAllowed = () => jsonRpcError({
+	status: 405,
+	code: -32e3,
+	message: "Method not allowed. MCP requests must use POST.",
+	headers: { allow: "POST" }
+});
+/**
+* The MCP endpoint. Authenticates the bearer key, sets `req.user` and the
+* request marker, then serves the JSON-RPC body with a fresh server and
+* transport. Any user Payload resolved from cookies or a JWT is ignored: only
+* an API key authenticates here.
+*/ const createMcpxHandler = (options) => async (req) => {
+	const resolveDefault = () => resolveApiKeyAuth(req, options);
+	const auth = options.auth?.resolve ? await options.auth.resolve({
+		req,
+		resolveDefault
+	}) : await resolveDefault();
+	if (!auth) return jsonRpcError({
+		status: 401,
+		code: -32001,
+		message: "Unauthorized: a valid API key is required.",
+		headers: { "www-authenticate": "Bearer" }
+	});
+	const capabilities = resolveCapabilities(options, auth.capabilities);
+	req.user = auth.user;
+	req.context = {
+		...req.context,
+		mcpx: {
+			apiKeyId: auth.apiKeyId,
+			capabilities
+		}
+	};
+	let parsedBody;
+	try {
+		parsedBody = await req.json?.();
+	} catch {
+		return jsonRpcError({
+			status: 400,
+			code: -32700,
+			message: "Parse error: Invalid JSON"
+		});
+	}
+	if (parsedBody === void 0 || req.url === void 0) return jsonRpcError({
+		status: 400,
+		code: -32600,
+		message: "Invalid request: a JSON body is required."
+	});
+	const server = createMcpServer(buildScope(req, options, capabilities));
+	const transport = new WebStandardStreamableHTTPServerTransport({ enableJsonResponse: true });
+	await server.connect(transport);
+	const headers = new Headers(req.headers);
+	headers.set("accept", "application/json, text/event-stream");
+	try {
+		return await transport.handleRequest(new Request(req.url, {
+			method: "POST",
+			headers
+		}), { parsedBody });
+	} finally {
+		await server.close();
+	}
+};
+//#endregion
+export { createMcpxHandler, methodNotAllowed };

package/dist/endpoint/result.mjs

@@ -0,0 +1,59 @@
+import { APIError, ValidationError } from "payload";
+//#region src/endpoint/result.ts
+/**
+* A JSON-RPC error response for failures that happen before the MCP server
+* is involved (auth, method, body parsing).
+*/ const jsonRpcError = (args) => {
+	const headers = new Headers(args.headers);
+	headers.set("content-type", "application/json");
+	return new Response(JSON.stringify({
+		jsonrpc: "2.0",
+		id: null,
+		error: {
+			code: args.code,
+			message: args.message
+		}
+	}), {
+		status: args.status,
+		headers
+	});
+};
+/**
+* A successful tool result carrying `value` as JSON text.
+*/ const jsonResult = (value) => ({ content: [{
+	type: "text",
+	text: JSON.stringify(value)
+}] });
+/**
+* A failed tool result. `extras` travel alongside the message so the client
+* can act on them (problems, validation errors, the current `updatedAt`).
+*/ const errorResult = (message, extras = {}) => ({
+	content: [{
+		type: "text",
+		text: JSON.stringify({
+			error: message,
+			...extras
+		})
+	}],
+	isError: true
+});
+/**
+* Maps an exception thrown by a tool to a result the client can read.
+*
+* Payload's public errors keep their message and status; a `ValidationError`
+* also surfaces its per-field detail. Anything else is logged and reported as
+* an internal error so no stack or driver message leaks to the client.
+*/ const toToolError = (error, logger) => {
+	if (error instanceof ValidationError) return errorResult(error.message, {
+		status: error.status,
+		validationErrors: error.data.errors
+	});
+	if (error instanceof APIError && error.isPublic) return errorResult(error.message, { status: error.status });
+	logger.error({
+		err: error,
+		msg: "[payloadcms-mcpx] Tool call failed."
+	});
+	return errorResult("Internal error");
+};
+//#endregion
+export { errorResult, jsonResult, jsonRpcError, toToolError };

package/dist/endpoint/server.mjs

@@ -0,0 +1,52 @@
+import { toToolError } from "./result.mjs";
+import { BUILTIN_TOOLS } from "../tools/index.mjs";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+//#region src/endpoint/server.ts
+/**
+* Builds a builtin tool's input schema as a strict object, so an unknown
+* argument is rejected with its name instead of being silently stripped and
+* the tool answering as if it had not been passed.
+*/ const builtinInputSchema = (tool, scope) => z.strictObject(tool.inputSchema(scope));
+/**
+* Builds the MCP server for one request. Tools are registered against the
+* key's capabilities, so `tools/list` shows exactly what the key may call and
+* every `collection` enum is limited to what it may touch.
+*/ const createMcpServer = (scope) => {
+	const { req, options, capabilities } = scope;
+	const { logger } = req.payload;
+	const server = new McpServer({
+		name: options.serverInfo.name,
+		version: options.serverInfo.version
+	}, { instructions: "Start with listCapabilities, then describeSchema for the collection you work on. Writes always land as drafts; a human publishes." });
+	const guarded = (run) => async () => {
+		try {
+			return await run();
+		} catch (error) {
+			return toToolError(error, logger);
+		}
+	};
+	for (const tool of BUILTIN_TOOLS) {
+		if (!tool.isEnabled(scope)) continue;
+		server.registerTool(tool.name, {
+			description: tool.description,
+			inputSchema: builtinInputSchema(tool, scope),
+			annotations: tool.annotations
+		}, (args) => guarded(() => tool.handler(args, scope))());
+	}
+	for (const tool of options.tools) {
+		if (capabilities.tools[tool.name] !== true) continue;
+		server.registerTool(tool.name, {
+			description: tool.description,
+			inputSchema: tool.inputSchema ?? {},
+			...tool.annotations ? { annotations: tool.annotations } : {}
+		}, (args, extra) => guarded(() => tool.handler({
+			args,
+			req,
+			extra
+		}))());
+	}
+	return server;
+};
+//#endregion
+export { builtinInputSchema, createMcpServer };

package/dist/index.d.mts

@@ -0,0 +1,5 @@
+import { McpxAuthResult, McpxCollectionCapabilities, McpxCollectionOptions, McpxPluginOptions, McpxRequestContext, McpxResolvedCapabilities, McpxTool, McpxToolExtra, defineMcpxTool } from "./types.mjs";
+import { mcpxPlugin } from "./plugin.mjs";
+import { isMcpxRequest } from "./write/draft-guard.mjs";
+import { PublishBlocker } from "./write/publish-blockers.mjs";
+export { type McpxAuthResult, type McpxCollectionCapabilities, type McpxCollectionOptions, type McpxPluginOptions, type McpxRequestContext, type McpxResolvedCapabilities, type McpxTool, type McpxToolExtra, type PublishBlocker, defineMcpxTool, isMcpxRequest, mcpxPlugin };

package/dist/index.mjs

@@ -0,0 +1,4 @@
+import { isMcpxRequest } from "./write/draft-guard.mjs";
+import { mcpxPlugin } from "./plugin.mjs";
+import { defineMcpxTool } from "./types.mjs";
+export { defineMcpxTool, isMcpxRequest, mcpxPlugin };

package/dist/options.mjs

@@ -0,0 +1,107 @@
+import { BUILTIN_TOOL_NAMES } from "./tools/names.mjs";
+import "./version.mjs";
+import { InvalidConfiguration } from "payload";
+import { hasDraftsEnabled } from "payload/shared";
+//#region src/options.ts
+const DEFAULT_API_KEYS_SLUG = "mcpx-api-keys";
+const DEFAULT_ENDPOINT_PATH = "/mcpx";
+const DEFAULT_MAX_LIMIT = 25;
+const DEFAULT_MAX_DEPTH = 1;
+const TOOL_NAME_PATTERN = /^[a-zA-Z][a-zA-Z0-9]*$/;
+const fail = (message) => {
+	throw new InvalidConfiguration(`[payloadcms-mcpx] ${message}`);
+};
+/**
+* Lower camel case of a slug, the same transform the stock MCP plugin applies
+* to derive field names from collection slugs.
+*/ const toCamelCase = (value) => value.replace(/[-_\s]+(.)?/g, (_, char) => char ? char.toUpperCase() : "").replace(/^(.)/, (_, char) => char.toLowerCase());
+/**
+* Refuses collections that must never be reachable through MCP, read included.
+* Auth collections carry credentials: `useAPIKey` stores a key that decrypts on
+* read, and email or lockout state is PII either way.
+*/ const assertExposable = (collection, apiKeysSlug) => {
+	const { slug } = collection;
+	if (slug === apiKeysSlug || slug.startsWith("payload-")) fail(`Collection "${slug}" cannot be exposed.`);
+	if (collection.auth) fail(`Auth collection "${slug}" cannot be exposed. Its documents carry credentials.`);
+};
+const assertWritable = (collection, options) => {
+	const { slug } = collection;
+	if (collection.upload) fail(`Upload collection "${slug}" cannot be exposed for write.`);
+	if (collection.timestamps === false) fail(`Collection "${slug}" has timestamps disabled, which write tools need for concurrency checks.`);
+	if (!options.hasDrafts && !options.allowLiveWrites) fail(`Collection "${slug}" has no drafts. Enable versions.drafts or set allowLiveWrites.`);
+};
+const normalizeCollections = (config, options, apiKeysSlug) => {
+	const collections = config.collections ?? [];
+	const fieldNames = /* @__PURE__ */ new Set();
+	return Object.entries(options.collections).flatMap(([slug, raw]) => {
+		if (raw === void 0) return [];
+		const collection = collections.find((candidate) => candidate.slug === slug);
+		if (!collection) return fail(`Exposed collection "${slug}" does not exist.`);
+		assertExposable(collection, apiKeysSlug);
+		const settings = raw === true ? {} : raw;
+		const hasDrafts = hasDraftsEnabled(collection);
+		const normalized = {
+			slug,
+			read: settings.read ?? true,
+			write: settings.write ?? false,
+			allowLiveWrites: settings.allowLiveWrites ?? false,
+			hasDrafts,
+			fieldName: toCamelCase(slug)
+		};
+		if (normalized.write) assertWritable(collection, normalized);
+		if (fieldNames.has(normalized.fieldName)) fail(`Collection "${slug}" maps to capability field "${normalized.fieldName}", which another exposed collection already uses.`);
+		fieldNames.add(normalized.fieldName);
+		return [normalized];
+	});
+};
+const assertUserCollection = (config, slug) => {
+	const collection = (config.collections ?? []).find((candidate) => candidate.slug === slug);
+	if (!collection) fail(`User collection "${slug}" does not exist.`);
+	else if (!collection.auth) fail(`User collection "${slug}" is not an auth collection.`);
+};
+const assertTools = (tools) => {
+	const names = /* @__PURE__ */ new Set();
+	for (const tool of tools) {
+		if (!TOOL_NAME_PATTERN.test(tool.name)) fail(`Tool name "${tool.name}" must match ${String(TOOL_NAME_PATTERN)}.`);
+		if (BUILTIN_TOOL_NAMES.includes(tool.name)) fail(`Tool name "${tool.name}" is reserved for a builtin tool.`);
+		if (names.has(tool.name)) fail(`Tool name "${tool.name}" is used twice.`);
+		names.add(tool.name);
+	}
+};
+const normalizeLimits = (limits) => {
+	const maxLimit = limits?.maxLimit ?? DEFAULT_MAX_LIMIT;
+	const maxDepth = limits?.maxDepth ?? DEFAULT_MAX_DEPTH;
+	if (!Number.isInteger(maxLimit) || maxLimit < 1) fail("limits.maxLimit must be a positive integer.");
+	if (!Number.isInteger(maxDepth) || maxDepth < 0) fail("limits.maxDepth must be a non-negative integer.");
+	return {
+		maxLimit,
+		maxDepth
+	};
+};
+/**
+* Validates the plugin options against the incoming config and fills in
+* defaults. Every problem is an `InvalidConfiguration` so misconfiguration
+* fails at startup instead of at request time.
+*/ const normalizeOptions = (config, options) => {
+	const apiKeysSlug = options.apiKeys?.slug ?? DEFAULT_API_KEYS_SLUG;
+	const userCollection = options.userCollection ?? config.admin?.user ?? "users";
+	if ((config.collections ?? []).some((c) => c.slug === apiKeysSlug)) fail(`API key collection slug "${apiKeysSlug}" is already taken.`);
+	assertUserCollection(config, userCollection);
+	const tools = options.tools ?? [];
+	assertTools(tools);
+	return {
+		collections: normalizeCollections(config, options, apiKeysSlug),
+		userCollection,
+		apiKeysSlug,
+		endpointPath: options.endpoint?.path ?? DEFAULT_ENDPOINT_PATH,
+		limits: normalizeLimits(options.limits),
+		tools,
+		auth: options.auth,
+		serverInfo: {
+			name: options.serverInfo?.name ?? "payloadcms-mcpx",
+			version: options.serverInfo?.version ?? "1.0.0-beta.3"
+		}
+	};
+};
+//#endregion
+export { normalizeOptions, toCamelCase };

package/dist/plugin.d.mts

@@ -0,0 +1,9 @@
+import { McpxPluginOptions } from "./types.mjs";
+//#region src/plugin.d.ts
+/**
+ * Mounts the MCP endpoint, adds the API key collection and installs the
+ * draft guard on every collection.
+ */
+declare const mcpxPlugin: (options: McpxPluginOptions) => import("payload").Plugin;
+//#endregion
+export { mcpxPlugin };

package/dist/plugin.mjs

@@ -0,0 +1,42 @@
+import { createApiKeysCollection } from "./api-keys/collection.mjs";
+import { createMcpxHandler, methodNotAllowed } from "./endpoint/handler.mjs";
+import { normalizeOptions } from "./options.mjs";
+import { installDraftGuards } from "./write/draft-guard.mjs";
+import { definePlugin } from "payload";
+//#region src/plugin.ts
+/**
+* Mounts the MCP endpoint, adds the API key collection and installs the
+* draft guard on every collection.
+*/ const mcpxPlugin = definePlugin({
+	slug: "@abinnovision/payloadcms-mcpx",
+	order: 100,
+	plugin: ({ config, plugins: _plugins, ...options }) => {
+		const normalized = normalizeOptions(config, options);
+		const apiKeys = createApiKeysCollection(normalized);
+		const apiKeysCollection = options.apiKeys?.overrideCollection?.(apiKeys) ?? apiKeys;
+		return {
+			...config,
+			collections: installDraftGuards([...config.collections ?? [], apiKeysCollection]),
+			endpoints: [
+				...config.endpoints ?? [],
+				{
+					path: normalized.endpointPath,
+					method: "post",
+					handler: createMcpxHandler(normalized)
+				},
+				{
+					path: normalized.endpointPath,
+					method: "get",
+					handler: methodNotAllowed
+				},
+				{
+					path: normalized.endpointPath,
+					method: "delete",
+					handler: methodNotAllowed
+				}
+			]
+		};
+	}
+});
+//#endregion
+export { mcpxPlugin };

package/dist/schema/describe.mjs

@@ -0,0 +1,82 @@
+import { blockOf, blockSlugsOf, collectionOf, describeFields, findBlocksField, joinPath, splitPath } from "./walk.mjs";
+//#region src/schema/describe.ts
+const blocksDescriptors = (fields) => describeFields(fields).filter((descriptor) => descriptor.type === "blocks");
+/**
+* Walks a schema path to the field list it addresses.
+*
+* A schema path alternates a blocks field's own path with the slug of one of
+* the blocks it accepts, so `layout.sections.sectionWrapper.modules.hero`
+* reaches `hero` as it exists under `pages` specifically.
+*/ const fieldsAtSchemaPath = (config, collection, schemaPath) => {
+	let fields = collection.flattenedFields;
+	let blockType;
+	let remaining = splitPath(schemaPath).filter(Boolean);
+	while (remaining.length > 0) {
+		/**
+		* A blocks field's own path may span several segments
+		* (`layout.sections`), so the longest matching one is taken.
+		*/ const match = blocksDescriptors(fields).map((descriptor) => splitPath(descriptor.path)).filter((parts) => parts.every((part, offset) => part === remaining[offset])).sort((left, right) => right.length - left.length)[0];
+		if (!match) throw new Error(`"${joinPath(remaining)}" does not address a blocks field. Blocks fields here: ${blocksDescriptors(fields).map((descriptor) => descriptor.path).join(", ") || "none"}`);
+		const slug = remaining.at(match.length);
+		const field = findBlocksField(fields, match);
+		if (!field) throw new Error(`"${match.join(".")}" could not be resolved.`);
+		if (slug === void 0) throw new Error(`"${joinPath(match)}" is a blocks field; append one of: ${blockSlugsOf(field).join(", ")}`);
+		const block = blockOf(config, field, slug);
+		if (!block) throw new Error(`"${slug}" is not allowed at "${joinPath(match)}". Allowed: ${blockSlugsOf(field).join(", ")}`);
+		fields = block.flattenedFields;
+		blockType = slug;
+		remaining = remaining.slice(match.length + 1);
+	}
+	return {
+		...blockType === void 0 ? {} : { blockType },
+		fields
+	};
+};
+/**
+* Describes a collection root, or one block reached through a schema path.
+*/ const describeNode = (config, collection, schemaPath = "") => {
+	const { blockType, fields } = fieldsAtSchemaPath(config, collectionOf(config, collection), schemaPath);
+	const descriptors = describeFields(fields);
+	const next = descriptors.flatMap((descriptor) => (descriptor.blocks ?? []).map((slug) => [
+		schemaPath,
+		descriptor.path,
+		slug
+	].filter(Boolean).join(".")));
+	return {
+		...blockType === void 0 ? {} : { blockType },
+		collection,
+		fields: descriptors,
+		...next.length > 0 ? { next } : {},
+		schemaPath
+	};
+};
+/**
+* Every schema path reachable from a collection root, capped at
+* {@link REACHABLE_PATHS_LIMIT}. `truncated` tells the caller the cap was hit
+* and explicit paths are the way to go deeper.
+*/ const reachableSchemaPaths = (config, collection) => {
+	const seen = [];
+	let truncated = false;
+	const walk = (schemaPath, visited) => {
+		if (seen.length >= 400) {
+			truncated = true;
+			return;
+		}
+		seen.push(schemaPath);
+		for (const descriptor of describeNode(config, collection, schemaPath).fields) for (const slug of descriptor.blocks ?? []) {
+			if (visited.includes(slug)) continue;
+			walk([
+				schemaPath,
+				descriptor.path,
+				slug
+			].filter(Boolean).join("."), [...visited, slug]);
+		}
+	};
+	walk("", []);
+	return {
+		paths: seen,
+		truncated
+	};
+};
+//#endregion
+export { describeNode, reachableSchemaPaths };

package/dist/schema/lexical.mjs

@@ -0,0 +1,25 @@
+//#region src/schema/lexical.ts
+/**
+* Node types Lexical registers itself.
+*
+* `editorConfig.features.nodes` lists only what a feature contributed, so a
+* field whose editor enables nothing but text formatting reports none at all.
+*/ const LEXICAL_CORE_NODES = [
+	"root",
+	"paragraph",
+	"text",
+	"linebreak",
+	"tab"
+];
+/**
+* Node types a rich text field accepts. Editors other than Lexical report
+* only the core nodes.
+*/ const allowedNodeTypes = (field) => {
+	const registered = (field.editor?.editorConfig?.features?.nodes ?? []).flatMap((entry) => {
+		const type = entry.node?.getType?.();
+		return type ? [type] : [];
+	});
+	return [.../* @__PURE__ */ new Set([...LEXICAL_CORE_NODES, ...registered])];
+};
+//#endregion
+export { allowedNodeTypes };

package/dist/schema/pointer.mjs

@@ -0,0 +1,83 @@
+import { blockOf, blockSlugsOf, collectionOf, describeFields, findBlocksField, joinPath, splitPath } from "./walk.mjs";
+//#region src/schema/pointer.ts
+const isIndexSegment = (segment) => segment === "-" || /^\d+$/.test(segment);
+/**
+* Decodes a JSON Pointer into its segments, unescaping `~1` and `~0`.
+*/ const pointerSegments = (pointer) => pointer.split("/").slice(1).map((segment) => segment.replace(/~1/g, "/").replace(/~0/g, "~"));
+const partMatches = (part, segment) => segment !== void 0 && (part === "[]" ? isIndexSegment(segment) : part === segment);
+/**
+* Longest descriptor whose path is fully consumed by the leading segments.
+*/ const longestMatch = (descriptors, segments) => descriptors.map((descriptor) => ({
+	consumed: splitPath(descriptor.path).length,
+	descriptor,
+	parts: splitPath(descriptor.path)
+})).filter(({ parts }) => parts.every((part, offset) => partMatches(part, segments[offset]))).sort((left, right) => right.consumed - left.consumed)[0];
+/**
+* Whether the segments stop part-way through some descriptor's path, which
+* means they address a subtree rather than a field.
+*/ const isSubtreePrefix = (descriptors, segments) => descriptors.some((descriptor) => {
+	const parts = splitPath(descriptor.path);
+	return parts.length > segments.length && segments.every((segment, offset) => {
+		const part = parts[offset];
+		return part !== void 0 && partMatches(part, segment);
+	});
+});
+/**
+* Reads the value the given pointer segments address. Unlike a descriptor
+* path, the segments carry real indices, so intervening array fields are
+* descended through rather than skipped.
+*/ const valueAtSegments = (data, segments) => segments.reduce((current, segment) => current === null || typeof current !== "object" ? void 0 : current[segment], data);
+/**
+* Resolves a JSON Pointer against the schema, using the stored document to
+* choose a branch at every blocks element.
+*
+* The document is required rather than optional: `/layout/sections/3/modules/1`
+* can only be resolved by reading `blockType` off `sections[3]`, since a blocks
+* field admits many shapes at the same index.
+*/ const resolveDataPointer = (config, target) => {
+	let fields = collectionOf(config, target.collection).flattenedFields;
+	let data = target.doc;
+	let blockType;
+	let segments = pointerSegments(target.pointer);
+	while (segments.length > 0) {
+		const descriptors = describeFields(fields);
+		const match = longestMatch(descriptors, segments);
+		if (!match) {
+			if (isSubtreePrefix(descriptors, segments)) return {
+				...blockType === void 0 ? {} : { blockType },
+				fields,
+				prefix: joinPath(segments)
+			};
+			throw new Error(`"${joinPath(segments)}" is not a field here. Available: ${descriptors.map((descriptor) => descriptor.path).join(", ")}`);
+		}
+		const rest = segments.slice(match.consumed);
+		if (rest.length === 0) return {
+			...blockType === void 0 ? {} : { blockType },
+			descriptor: match.descriptor,
+			fields,
+			prefix: ""
+		};
+		if (match.descriptor.type !== "blocks") throw new Error(`"${match.descriptor.path}" is a ${match.descriptor.type} field and has no "${rest.join("/")}" beneath it.`);
+		const [index, ...remaining] = rest;
+		if (!isIndexSegment(index)) throw new Error(`"${match.descriptor.path}" is an array; "${index}" is not an index.`);
+		const parts = splitPath(match.descriptor.path);
+		const field = findBlocksField(fields, parts);
+		const rows = valueAtSegments(data, segments.slice(0, match.consumed));
+		const existing = Array.isArray(rows) && index !== "-" ? rows[Number(index)] : void 0;
+		const slug = existing?.blockType ?? target.addedValue?.blockType;
+		if (!field || slug === void 0) throw new Error(`Cannot tell which block "${match.descriptor.path}/${index}" is. Supply a "blockType" on the value, one of: ${field ? blockSlugsOf(field).join(", ") : ""}`);
+		const block = blockOf(config, field, slug);
+		if (!block) throw new Error(`"${slug}" is not allowed at "${match.descriptor.path}". Allowed: ${blockSlugsOf(field).join(", ")}`);
+		blockType = slug;
+		fields = block.flattenedFields;
+		data = existing;
+		segments = remaining;
+	}
+	return {
+		...blockType === void 0 ? {} : { blockType },
+		fields,
+		prefix: ""
+	};
+};
+//#endregion
+export { pointerSegments, resolveDataPointer };