@abinnovision/payloadcms-mcpx 1.0.0-beta.10

package/dist/options.d.mts

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

package/dist/options.mjs

@@ -0,0 +1,146 @@
+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.`);
+};
+/**
+* Refuses globals that must never be reachable. Globals cannot be auth or
+* upload entities, so only Payload's own reserved namespace is left to guard.
+*/ const assertGlobalExposable = (global) => {
+	if (global.slug.startsWith("payload-")) fail(`Global "${global.slug}" cannot be exposed.`);
+};
+/**
+* `GlobalConfig` has no `timestamps` option and `sanitizeGlobal` always appends
+* `createdAt`/`updatedAt`, so the concurrency check the collection path guards
+* for is always available here. Drafts are the only requirement left.
+*/ const assertGlobalWritable = (global, options) => {
+	if (!options.hasDrafts && !options.allowLiveWrites) fail(`Global "${global.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 normalizeGlobals = (config, options) => {
+	const globals = config.globals ?? [];
+	const fieldNames = /* @__PURE__ */ new Set();
+	return Object.entries(options.globals ?? {}).flatMap(([slug, raw]) => {
+		if (raw === void 0) return [];
+		const global = globals.find((candidate) => candidate.slug === slug);
+		if (!global) return fail(`Exposed global "${slug}" does not exist.`);
+		assertGlobalExposable(global);
+		const settings = raw === true ? {} : raw;
+		const hasDrafts = hasDraftsEnabled(global);
+		const normalized = {
+			slug,
+			read: settings.read ?? true,
+			write: settings.write ?? false,
+			allowLiveWrites: settings.allowLiveWrites ?? false,
+			hasDrafts,
+			fieldName: toCamelCase(slug)
+		};
+		if (normalized.write) assertGlobalWritable(global, normalized);
+		if (fieldNames.has(normalized.fieldName)) fail(`Global "${slug}" maps to capability field "${normalized.fieldName}", which another exposed global 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),
+		globals: normalizeGlobals(config, options),
+		userCollection,
+		apiKeysSlug,
+		endpointPath: options.endpoint?.path ?? DEFAULT_ENDPOINT_PATH,
+		setupGuide: options.apiKeys?.setupGuide ?? true,
+		limits: normalizeLimits(options.limits),
+		tools,
+		auth: options.auth,
+		serverInfo: {
+			name: options.serverInfo?.name ?? "payloadcms-mcpx",
+			version: options.serverInfo?.version ?? "0.0.0"
+		}
+	};
+};
+//#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 and global.
+ */
+declare const mcpxPlugin: (options: McpxPluginOptions) => import("payload").Plugin;
+//#endregion
+export { mcpxPlugin };

package/dist/plugin.mjs

@@ -0,0 +1,43 @@
+import { createApiKeysCollection } from "./api-keys/collection.mjs";
+import { createMcpxHandler, methodNotAllowed } from "./endpoint/handler.mjs";
+import { normalizeOptions } from "./options.mjs";
+import { installDraftGuards, installGlobalDraftGuards } 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 and global.
+*/ 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]),
+			globals: installGlobalDraftGuards(config.globals ?? []),
+			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,160 @@
+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
+/**
+* The longest descriptor path that is a prefix of `remaining`. Blocks and rich
+* text fields are both leaves of the walk, so at most one can match.
+*/ const longestMatch = (descriptors, remaining) => descriptors.map((descriptor) => splitPath(descriptor.path)).filter((parts) => parts.every((part, offset) => part === remaining[offset])).sort((left, right) => right.length - left.length)[0];
+/**
+* Walks one step of a schema path through a blocks field.
+*/ const stepThroughBlocks = ({ config, fields, match, remaining }) => {
+	const field = findBlocksField(fields, match);
+	if (!field) throw new Error(`"${joinPath(match)}" could not be resolved.`);
+	const slug = remaining.at(match.length);
+	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(", ")}`);
+	return {
+		blockType: slug,
+		fields: block.flattenedFields,
+		rest: remaining.slice(match.length + 1)
+	};
+};
+/**
+* Walks one step of a schema path into a Lexical node's own fields.
+*
+* A node that picks a block by slug takes one segment more, so `/content/block`
+* addresses the choice and `/content/block/callout` the definition. Everything
+* else, a link node being the usual case, resolves in a single segment.
+*/ const stepThroughLexical = ({ config, fields, match, remaining }) => {
+	const field = findRichTextField(fields, match);
+	if (!field) throw new Error(`"${joinPath(match)}" could not be resolved.`);
+	const available = subSchemaNodeTypes(field).join(", ") || "none";
+	const nodeType = remaining.at(match.length);
+	if (nodeType === void 0) throw new Error(`"${joinPath(match)}" is a rich text field; append one of: ${available}`);
+	const sub = lexicalSubSchema(field, nodeType);
+	const reached = joinPath([...match, nodeType]);
+	if (!sub) throw new Error(`"${nodeType}" carries no fields in this field's editor. Node types with fields here: ${available}`);
+	if (sub.kind === "fields") return {
+		fields: sub.fields,
+		rest: remaining.slice(match.length + 1)
+	};
+	const slug = remaining.at(match.length + 1);
+	const slugs = blockSlugsOf(sub.blocksField).join(", ");
+	if (slug === void 0) throw new Error(`"${reached}" selects a block; append one of: ${slugs}`);
+	const block = blockOf(config, sub.blocksField, slug);
+	if (!block) throw new Error(`"${slug}" is not allowed at "${reached}". Allowed: ${slugs}`);
+	return {
+		blockType: slug,
+		fields: block.flattenedFields,
+		rest: remaining.slice(match.length + 2)
+	};
+};
+/**
+* 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. The slug sits where
+* a pointer into a document would carry the element's index. A rich text
+* field's path continues the same way, naming a Lexical node type and, for the
+* block nodes, the slug it holds.
+*/ const fieldsAtSchemaPath = (config, target, schemaPath) => {
+	let fields = target.flattenedFields;
+	let blockType;
+	let remaining = splitPath(schemaPath);
+	while (remaining.length > 0) {
+		const descendable = describeFields(fields).filter((descriptor) => descriptor.type === "blocks" || descriptor.type === "richText");
+		/**
+		* A field's own path may span several segments (`/layout/sections`), so
+		* the longest matching one is taken. Blocks and rich text fields are both
+		* leaves of the walk, so no two of these paths overlap.
+		*/ const match = longestMatch(descendable, remaining);
+		if (!match) throw new Error(`"${joinPath(remaining)}" does not address a blocks or rich text field. Available here: ${descendable.map((descriptor) => descriptor.path).join(", ") || "none"}`);
+		const at = {
+			config,
+			fields,
+			match,
+			remaining
+		};
+		const step = findBlocksField(fields, match) === void 0 ? stepThroughLexical(at) : stepThroughBlocks(at);
+		blockType = step.blockType;
+		fields = step.fields;
+		remaining = step.rest;
+	}
+	return {
+		...blockType === void 0 ? {} : { blockType },
+		fields
+	};
+};
+/**
+* Where a descriptor can be drilled into: one branch per block a blocks field
+* accepts, and one per Lexical node type that carries fields.
+*/ const branchesOf = (fields, descriptor, schemaPath) => {
+	const base = `${schemaPath}${descriptor.path}`;
+	if (descriptor.type === "richText") {
+		const field = findRichTextField(fields, splitPath(descriptor.path));
+		if (!field) return [];
+		return subSchemaNodeTypes(field).flatMap((nodeType) => {
+			const sub = lexicalSubSchema(field, nodeType);
+			if (sub?.kind !== "blocks") return [{
+				path: `${base}/${nodeType}`,
+				token: `lexical:${nodeType}`
+			}];
+			return blockSlugsOf(sub.blocksField).map((slug) => ({
+				path: `${base}/${nodeType}/${slug}`,
+				token: `lexical:${nodeType}:${slug}`
+			}));
+		});
+	}
+	return (descriptor.blocks ?? []).map((slug) => ({
+		path: `${base}/${slug}`,
+		token: slug
+	}));
+};
+/**
+* Describes a collection or global root, one block reached through a schema
+* path, or the fields a Lexical node carries.
+*
+* 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, translate);
+	const next = descriptors.flatMap((descriptor) => branchesOf(fields, descriptor, schemaPath).map((branch) => branch.path));
+	return {
+		...blockType === void 0 ? {} : { blockType },
+		...ref.kind === "collection" ? { collection: ref.slug } : { global: ref.slug },
+		fields: descriptors,
+		...next.length > 0 ? { next } : {},
+		schemaPath
+	};
+};
+/**
+* Every schema path reachable from an entity 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, ref) => {
+	const seen = [];
+	let truncated = false;
+	const walk = (schemaPath, visited) => {
+		if (seen.length >= 400) {
+			truncated = true;
+			return;
+		}
+		seen.push(schemaPath);
+		const { fields } = fieldsAtSchemaPath(config, targetOf(config, ref), schemaPath);
+		for (const descriptor of describeFields(fields)) for (const branch of branchesOf(fields, descriptor, schemaPath)) {
+			if (visited.includes(branch.token)) continue;
+			walk(branch.path, [...visited, branch.token]);
+		}
+	};
+	walk("", []);
+	return {
+		paths: seen,
+		truncated
+	};
+};
+//#endregion
+export { nodeDescriber, reachableSchemaPaths };

package/dist/schema/lexical.d.mts

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

package/dist/schema/lexical.mjs

@@ -0,0 +1,117 @@
+import { flattenAllFields } from "payload";
+//#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 whose sub-fields exist but cannot be addressed by a schema path.
+*
+* Asked without a node, `upload` answers with every enabled collection's
+* upload fields concatenated, so the result describes no single position. It
+* would need addressing by `relationTo` to mean anything.
+*/ const OPAQUE_NODE_TYPES = /* @__PURE__ */ new Set(["upload"]);
+/**
+* Sub-schemas per rich text field, keyed by node type. `null` records a node
+* type that was asked and has nothing to describe, so it is asked only once.
+*
+* Worth caching because the describe and validate paths resolve the same field
+* repeatedly, and because the block features build their answer from scratch on
+* every call. Keyed weakly on the sanitized field, which lives as long as the
+* config does.
+*/ const subSchemaCache = /* @__PURE__ */ new WeakMap();
+const featuresOf = (field) => field.editor?.editorConfig?.features;
+/**
+* Node types a rich text field accepts. Editors other than Lexical report
+* only the core nodes.
+*/ const allowedNodeTypes = (field) => {
+	const registered = (featuresOf(field)?.nodes ?? []).flatMap((entry) => {
+		const type = entry.node?.getType?.();
+		return type ? [type] : [];
+	});
+	return [.../* @__PURE__ */ new Set([...LEXICAL_CORE_NODES, ...registered])];
+};
+const resolveSubSchema = (field, nodeType) => {
+	if (OPAQUE_NODE_TYPES.has(nodeType)) return null;
+	const fields = featuresOf(field)?.getSubFields?.get(nodeType)?.({});
+	if (!fields?.length) return null;
+	const flattened = flattenAllFields({ fields });
+	const only = flattened.length === 1 ? flattened[0] : void 0;
+	return only?.type === "blocks" ? {
+		blocksField: only,
+		kind: "blocks"
+	} : {
+		fields: flattened,
+		kind: "fields"
+	};
+};
+/**
+* The sub-schema behind one node type of a rich text field, or `undefined`
+* when that node carries no addressable fields.
+*/ const lexicalSubSchema = (field, nodeType) => {
+	let cached = subSchemaCache.get(field);
+	if (!cached) {
+		cached = /* @__PURE__ */ new Map();
+		subSchemaCache.set(field, cached);
+	}
+	if (!cached.has(nodeType)) cached.set(nodeType, resolveSubSchema(field, nodeType));
+	return cached.get(nodeType) ?? void 0;
+};
+/**
+* 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, nodeOptions, subSchemaNodeTypes };

package/dist/schema/pointer.mjs

@@ -0,0 +1,80 @@
+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);
+/**
+* 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 = targetOf(config, target.ref).flattenedFields;
+	let data = target.doc;
+	let blockType;
+	let segments = splitPath(target.pointer);
+	while (segments.length > 0) {
+		const descriptors = describeAddressableFields(fields);
+		const match = longestMatch(descriptors, segments);
+		if (!match) {
+			if (isSubtreePrefix(descriptors, segments)) return {
+				...blockType === void 0 ? {} : { blockType },
+				fields,
+				prefix: 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 "${joinPath(rest)}" 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 { resolveDataPointer };