drupal-mcp-connector 2.7.0 → 2.7.1

package/src/tools/paragraphs.js

@@ -9,17 +9,24 @@
  * focused way to mint a paragraph and fetch it back, plus the relationship data
  * needed to embed it into a host field.
  *
- * Embedding model — IMPORTANT:
- *   - Over JSON:API (this connector's default backend) a host references a
- *     paragraph from its ERR field by a resource identifier object
- *     `{ type: "paragraph--<bundle>", id: "<paragraph-uuid>" }`. Drupal resolves
- *     the correct target_id + target_revision_id server-side from the UUID. Drop
- *     `relationshipData` (returned by drupal_create_paragraph) into the host's
- *     relationships map and call drupal_entity_update / drupal_update_node.
+ * Embedding model — IMPORTANT (#192):
+ *   - Over JSON:API a host references a paragraph from its ERR field by a
+ *     resource identifier `{ type: "paragraph--<bundle>", id, meta: {
+ *     target_revision_id } }`. Drupal's ERR item is empty unless both
+ *     `target_id` and `target_revision_id` are set; JSON:API only receives the
+ *     revision id from `meta.target_revision_id`. `{ type, id }` alone persists
+ *     an empty field — it is not a no-op, and it is worse than omitting the
+ *     field (which would inherit the previous revision's refs).
+ *   - `relationshipData` from these tools includes that meta key. Host writes
+ *     (`drupal_entity_update` / `drupal_update_node` / bulk update) also resolve
+ *     a missing vid before PATCH and fail the whole write if they cannot.
  *   - The classic entity-API pair `{ target_id, target_revision_id }` (integer
- *     ids) is the REST/Form-API shape, not the JSON:API shape. Those numeric ids
- *     are not surfaced by the canonical entity here; prefer the UUID relationship
- *     form above when writing through this connector.
+ *     ids) is the REST/Form-API shape, not the JSON:API shape.
+ *   - Creating paragraphs and then attaching them is two calls. A content-tier
+ *     agent cannot delete orphans if the host PATCH is then rejected (#201).
+ *     Probe the host first: `drupal_list_revisions` (`possiblyPatchBlocked`)
+ *     and `dryRun` on the host update. Preflight inside `update_node` does not
+ *     un-orphan work that already happened.
  *
  * Both tools are governed: writes assert create permission for the `paragraph`
  * entity type + bundle, reads assert read permission and are redacted per the
@@ -32,33 +39,35 @@ import { resolveBackend } from "../lib/backends/index.js";
 import {
   resolveSecurityConfig, assertWriteAllowed, assertReadAllowed, redactCanonicalEntity,
 } from "../lib/security.js";
-
-/**
- * Build the JSON:API resource type string for a paragraph bundle.
- * @param {string} bundle Paragraph type machine name.
- * @returns {string} e.g. "paragraph--text".
- */
-function resourceType(bundle) {
-  return `paragraph--${bundle}`;
-}
+import {
+  embedParagraphRef, paragraphRevisionId, resolveParagraphRevisionId, missingParagraphRevisionError,
+} from "../lib/err-relationships.js";
 
 /**
  * Build the resource-identifier ref used to embed a paragraph in a host ERR /
- * paragraph reference field over JSON:API.
+ * paragraph reference field over JSON:API. Includes `meta.target_revision_id`
+ * when a vid is known (#192).
  * @param {string} bundle Paragraph type machine name.
  * @param {string} id Paragraph UUID.
- * @returns {{type: string, id: string}}
+ * @param {number|string|null|undefined} [revisionId] Current revision id.
+ * @returns {{type: string, id: string, meta?: {target_revision_id: number}}}
  */
-function embedRef(bundle, id) {
-  return { type: resourceType(bundle), id };
+export function embedRef(bundle, id, revisionId) {
+  return embedParagraphRef(bundle, id, revisionId);
 }
 
 const EMBED_NOTE =
   "Paragraphs are not standalone content: embed this paragraph in a host entity's " +
-  "Entity Reference Revisions (paragraph) field. Over JSON:API, add `relationshipData` " +
-  "to the host field's relationship (e.g. drupal_entity_update / drupal_update_node with " +
-  "relationships: { field_paragraphs: { data: [ relationshipData ] } }). Drupal resolves " +
-  "target_id + target_revision_id from the UUID server-side.";
+  "Entity Reference Revisions (paragraph) field. Over JSON:API the resource identifier " +
+  "MUST include meta.target_revision_id — Drupal's ERR item is empty unless both " +
+  "target_id and target_revision_id are set, and JSON:API only receives the revision " +
+  "id from that meta key. relationshipData from this tool includes it. " +
+  "drupal_entity_update / drupal_update_node also resolve a missing vid before PATCH " +
+  "and fail the write if they cannot. An empty array is an explicit clear. " +
+  "Before creating paragraphs to attach to a published moderated node, call " +
+  "drupal_list_revisions (inspect possiblyPatchBlocked) and dryRun the host update — " +
+  "the host write is rejected after dependents exist, and content-tier cannot delete " +
+  "the orphans (#201).";
 
 /**
  * Create a paragraph entity of the given type and return a ref suitable for
@@ -68,10 +77,11 @@ const EMBED_NOTE =
  *   `attributes` are paragraph field values keyed by Drupal machine name
  *   (e.g. { field_body: { value, format } }). Use drupal_get_entity_schema for
  *   entityType "paragraph" + the bundle to discover available fields.
- * @returns {Promise<{paragraph: object, ref: {id: string, type: string},
- *   relationshipData: {type: string, id: string}, note: string}>}
- *   The created paragraph descriptor plus the embedding ref/relationship data.
+ * @returns {Promise<{paragraph: object, ref: object, relationshipData: object, note: string}>}
+ *   The created paragraph descriptor plus the embedding ref/relationship data
+ *   (including `meta.target_revision_id`).
  * @throws {SecurityError} If creating paragraphs of this bundle is not permitted.
+ * @throws {Error} If the created paragraph has no readable revision id.
  */
 async function createParagraph({ site: siteName, paragraphType, attributes = {} }) {
   const site = getSiteConfig(siteName);
@@ -80,7 +90,9 @@ async function createParagraph({ site: siteName, paragraphType, attributes = {}
   const backend = await resolveBackend(site);
   const paragraph = await backend.createEntity({ entityType: "paragraph", bundle: paragraphType, attributes });
   const bundle = paragraph.bundle || paragraphType;
-  const ref = embedRef(bundle, paragraph.id);
+  const revisionId = await resolveParagraphRevisionId(backend, paragraph, paragraphType);
+  if (revisionId === null) throw missingParagraphRevisionError(paragraph.id);
+  const ref = embedRef(bundle, paragraph.id, revisionId);
   return { paragraph, ref, relationshipData: ref, note: EMBED_NOTE };
 }
 
@@ -94,10 +106,9 @@ async function createParagraph({ site: siteName, paragraphType, attributes = {}
  * @param {object} args - { site?, paragraphType, id, attributes? }.
  *   `attributes` are the paragraph field values to change, keyed by Drupal
  *   machine name (e.g. { field_body: { value, format } }).
- * @returns {Promise<{paragraph: object, ref: {id: string, type: string},
- *   relationshipData: {type: string, id: string}, note: string}>}
- *   The updated paragraph plus the (unchanged) embedding ref.
- * @throws {Error} If id is missing.
+ * @returns {Promise<{paragraph: object, ref: object, relationshipData: object, note: string}>}
+ *   The updated paragraph plus the embedding ref (with current revision id).
+ * @throws {Error} If id is missing or the revision id cannot be read.
  * @throws {SecurityError} If updating paragraphs of this bundle is not permitted.
  */
 async function updateParagraph({ site: siteName, paragraphType, id, attributes = {} }) {
@@ -108,16 +119,18 @@ async function updateParagraph({ site: siteName, paragraphType, id, attributes =
   const backend = await resolveBackend(site);
   const paragraph = await backend.updateEntity({ entityType: "paragraph", bundle: paragraphType, id, attributes });
   const bundle = paragraph.bundle || paragraphType;
-  const ref = embedRef(bundle, paragraph.id);
+  const revisionId = await resolveParagraphRevisionId(backend, paragraph, paragraphType);
+  if (revisionId === null) throw missingParagraphRevisionError(id, "Updated");
+  const ref = embedRef(bundle, paragraph.id, revisionId);
   return { paragraph, ref, relationshipData: ref, note: EMBED_NOTE };
 }
 
 /**
  * Fetch a single paragraph by bundle + UUID, redacted per the site policy, and
- * annotate it with the embedding ref.
+ * annotate it with the embedding ref (including `meta.target_revision_id`).
  *
  * @param {object} args - { site?, paragraphType, id }.
- * @returns {Promise<(object & {ref: {id: string, type: string}})|null>}
+ * @returns {Promise<(object & {ref: object})|null>}
  *   The redacted paragraph with an embedding `ref`, or null if not found.
  * @throws {SecurityError} If reading paragraphs of this bundle is not permitted.
  */
@@ -129,7 +142,8 @@ async function getParagraph({ site: siteName, paragraphType, id }) {
   const entity = await backend.getEntity({ entityType: "paragraph", bundle: paragraphType, id });
   if (!entity) return null;
   const redacted = redactCanonicalEntity(entity, sec, "paragraph");
-  return { ...redacted, ref: embedRef(redacted.bundle || paragraphType, redacted.id) };
+  const revisionId = paragraphRevisionId(entity) ?? paragraphRevisionId(redacted);
+  return { ...redacted, ref: embedRef(redacted.bundle || paragraphType, redacted.id, revisionId) };
 }
 
 // ---------------------------------------------------------------------------
@@ -140,7 +154,7 @@ export const definitions = [
   {
     name: "drupal_create_paragraph",
     description:
-      "Create a Paragraph entity of a given paragraph type (bundle). Paragraphs are content fragments that are NOT standalone — they must be referenced by a host entity's paragraph / Entity Reference Revisions field. Returns the created paragraph plus `relationshipData` ({ type: 'paragraph--<bundle>', id: <uuid> }) to drop into a host field's relationships via drupal_entity_update / drupal_update_node. Use drupal_get_entity_schema (entityType 'paragraph', the bundle) first to discover fields. Governed by the site security policy.",
+      "Create a Paragraph entity of a given paragraph type (bundle). Paragraphs are content fragments that are NOT standalone — they must be referenced by a host entity's paragraph / Entity Reference Revisions field. Returns the created paragraph plus `relationshipData` ({ type: 'paragraph--<bundle>', id, meta: { target_revision_id } }) to drop into a host field's relationships via drupal_entity_update / drupal_update_node. Drupal ERR items are empty without that meta key — do not send {type, id} alone. Before creating paragraphs to attach to a published moderated node, call drupal_list_revisions (possiblyPatchBlocked) and dryRun the host update so a doomed PATCH does not orphan them. Use drupal_get_entity_schema (entityType 'paragraph', the bundle) first to discover fields. Governed by the site security policy.",
     inputSchema: {
       type: "object", required: ["paragraphType"],
       properties: {
@@ -153,7 +167,7 @@ export const definitions = [
   {
     name: "drupal_update_paragraph",
     description:
-      "Update an existing Paragraph entity's field values by paragraph type (bundle) and UUID. Only the attributes you pass are changed (partial update); the host entity's reference to this paragraph is unchanged (same UUID), so this maintains a component paragraph in place without re-embedding. Use drupal_get_entity_schema (entityType 'paragraph', the bundle) to discover fields. Governed by the site security policy.",
+      "Update an existing Paragraph entity's field values by paragraph type (bundle) and UUID. Only the attributes you pass are changed (partial update); the host entity's reference to the paragraph is unchanged (same UUID), so this maintains a component paragraph in place without re-embedding. Returns relationshipData including meta.target_revision_id for a later host attach. Use drupal_get_entity_schema (entityType 'paragraph', the bundle) to discover fields. Governed by the site security policy.",
     inputSchema: {
       type: "object", required: ["paragraphType", "id"],
       properties: {
@@ -167,7 +181,7 @@ export const definitions = [
   {
     name: "drupal_get_paragraph",
     description:
-      "Fetch a single Paragraph entity by paragraph type (bundle) and UUID. Returns the redacted paragraph plus a `ref` ({ type: 'paragraph--<bundle>', id }) you can use to embed it in a host entity's paragraph / ERR field. Note: paragraphs are referenced (by target_id + target_revision_id in the entity API, or by UUID over JSON:API) from a host field rather than queried standalone in production. Governed by the site security policy.",
+      "Fetch a single Paragraph entity by paragraph type (bundle) and UUID. Returns the redacted paragraph (fields include drupal_internal__revision_id) plus a `ref` ({ type: 'paragraph--<bundle>', id, meta: { target_revision_id } }) you can use to embed it in a host entity's paragraph / ERR field. Paragraphs are referenced from a host field rather than queried standalone in production. Governed by the site security policy.",
     inputSchema: {
       type: "object", required: ["paragraphType", "id"],
       properties: {

package/src/tools/revisions.js

@@ -112,6 +112,7 @@ function summarizeRevision(resource) {
   return {
     vid: attrs.get("drupal_internal__vid") ?? null,
     revisionTimestamp: attrs.get("revision_timestamp") ?? null,
+    changed: attrs.get("changed") ?? null,
     revisionLog: attrs.get("revision_log") ?? attrs.get("revision_log_message") ?? null,
     status: attrs.get("status") ?? null,
     title: attrs.get("title") ?? null,
@@ -119,6 +120,39 @@ function summarizeRevision(resource) {
   };
 }
 
+/**
+ * Whether the default revision's `changed` is later than its own
+ * `revision_timestamp` — the readable fingerprint of a #201 node.
+ * @param {?object} summary
+ * @returns {boolean}
+ */
+function changedAheadOfRevision(summary) {
+  if (!summary?.changed || !summary?.revisionTimestamp) return false;
+  const changed = Date.parse(summary.changed);
+  const rev = Date.parse(summary.revisionTimestamp);
+  if (!Number.isFinite(changed) || !Number.isFinite(rev)) return false;
+  return changed > rev;
+}
+
+const LIST_REVISIONS_BASE_NOTE =
+  "JSON:API only addresses revisions by id (id:<vid>) or the rel:latest-version / " +
+  "rel:working-copy aliases; it cannot enumerate the full chronological history. " +
+  "Use drupal_get_revision with a specific vid to inspect a known revision, or the " +
+  "Drush bridge for complete revision-history enumeration. " +
+  "drupal_report_revision_hotspots can surface per-node revision counts.";
+
+const LIST_REVISIONS_NULL_WC_NOTE =
+  " workingCopy: null is not proof the node is PATCH-able. Drupal core rejects " +
+  "PATCH when the stored entity is not the latest revision even when " +
+  "content_moderation exposes no pending revision (connector #201, core #2795279). " +
+  "Inspect possiblyPatchBlocked before creating dependent paragraphs; dryRun on " +
+  "the host update runs the same guard.";
+
+const LIST_REVISIONS_FINGERPRINT_NOTE =
+  " The default revision's changed timestamp is later than its own " +
+  "revision_timestamp — a readable fingerprint that a newer revision row may " +
+  "exist without a content_moderation working copy.";
+
 /**
  * List the addressable revisions of an entity: the latest default revision and
  * the working-copy (forward) revision. Full chronological enumeration is not
@@ -145,19 +179,20 @@ async function listRevisions({ site: siteName, type, id }) {
     .then(summarizeRevision)
     .catch(() => null);
 
+  const possiblyPatchBlocked = Boolean(latestVersion && changedAheadOfRevision(latestVersion));
+  let note = LIST_REVISIONS_BASE_NOTE;
+  if (!workingCopy) note += LIST_REVISIONS_NULL_WC_NOTE;
+  if (possiblyPatchBlocked) note += LIST_REVISIONS_FINGERPRINT_NOTE;
+
   return {
     entityType: "node",
     bundle: type,
     id,
     latestVersion,
     workingCopy,
+    possiblyPatchBlocked,
     fullHistoryAvailable: false,
-    note:
-      "JSON:API only addresses revisions by id (id:<vid>) or the rel:latest-version / " +
-      "rel:working-copy aliases; it cannot enumerate the full chronological history. " +
-      "Use drupal_get_revision with a specific vid to inspect a known revision, or the " +
-      "Drush bridge for complete revision-history enumeration. " +
-      "drupal_report_revision_hotspots can surface per-node revision counts.",
+    note,
   };
 }
 
@@ -266,7 +301,7 @@ export const definitions = [
   {
     name: "drupal_list_revisions",
     description:
-      "Surface the addressable revisions of a content node: the latest default revision and the working-copy (forward) revision, with their version ids and links. NOTE: JSON:API cannot enumerate full chronological revision history — it only addresses revisions by id or the latest/working-copy aliases. Full history enumeration requires the Drush bridge. Use drupal_report_revision_hotspots for per-node revision counts.",
+      "Surface the addressable revisions of a content node: the latest default revision and the working-copy (forward) revision, with their version ids and links. workingCopy: null is not an all-clear — Drupal core can still reject PATCH when a revision row sits above the default without a content_moderation working copy (#201). The payload includes possiblyPatchBlocked (true when default changed is later than its revision_timestamp) plus changed and revisionTimestamp on latestVersion. Probe the host (this flag, then dryRun on the update) before creating dependent paragraphs. NOTE: JSON:API cannot enumerate full chronological revision history. Full history enumeration requires the Drush bridge.",
     inputSchema: {
       type: "object", required: ["type", "id"],
       properties: {