drupal-mcp-connector 2.14.1 → 2.15.0

package/src/tools/revisions.js

@@ -21,8 +21,10 @@
 import { getSiteConfig } from "../lib/config.js";
 import { resolveBackend } from "../lib/backends/index.js";
 import {
-  resolveSecurityConfig, assertReadAllowed, assertWriteAllowed,
+  resolveSecurityConfig, assertReadAllowed, assertWriteAllowed, redactCanonicalEntity,
 } from "../lib/security.js";
+import { assertDraftLangcode, readDraftTranslation, readTranslationInventory } from "../lib/draft-write.js";
+import { omitLiveComputedMetatag } from "../lib/entity-response.js";
 
 // Attributes that describe the entity's identity / revision bookkeeping / paths.
 // These are read-only or server-managed and must NOT be replayed on a revert.
@@ -205,12 +207,41 @@ async function listRevisions({ site: siteName, type, id }) {
  * @returns {Promise<?object>} The revision descriptor, or null if not found.
  * @throws {SecurityError} If reading nodes/bundle is not permitted.
  */
-async function getRevision({ site: siteName, type, id, version }) {
+async function getRevision({ site: siteName, type, id, version, langcode }) {
   const site = getSiteConfig(siteName);
   const sec = resolveSecurityConfig(site);
   assertReadAllowed(sec, "node", type);
   const backend = await resolveBackend(site);
 
+  if (langcode) {
+    const targetLang = assertDraftLangcode(langcode);
+    const inventory = await readTranslationInventory(backend, { entityType: "node", bundle: type, id });
+    const workingRow = (inventory.working?.translations ?? []).find((row) => row.langcode === targetLang);
+    if (!inventory.live?.vid || !inventory.working?.vid || !workingRow || workingRow.status !== false) {
+      throw new Error("No unpublished working translation is addressable for this revision.");
+    }
+    const entity = await readDraftTranslation(backend, {
+      entityType: "node", bundle: type, id, langcode: targetLang,
+      draftRevision: { liveVid: inventory.live.vid, workingVid: inventory.working.vid },
+    });
+    const redacted = omitLiveComputedMetatag(redactCanonicalEntity(entity, sec, "node"));
+    return {
+      entityType: "node",
+      bundle: type,
+      id,
+      vid: inventory.working.vid,
+      langcode: targetLang,
+      status: redacted.status,
+      attributes: {
+        title: redacted.title,
+        langcode: redacted.langcode,
+        status: redacted.status,
+        ...redacted.fields,
+      },
+      relationships: redacted.relationships ?? {},
+    };
+  }
+
   const resource = await fetchRevisionResource(backend, "node", type, id, version);
   if (!resource) return null;
 
@@ -314,13 +345,14 @@ export const definitions = [
   {
     name: "drupal_get_revision",
     description:
-      "Fetch a single revision of a content node by version id or alias. `version` may be a numeric vid (e.g. 42), an explicit 'id:<vid>', or the relative aliases 'rel:latest-version' / 'rel:working-copy'. Read-only; attributes are redacted per security policy.",
+      "Fetch a single revision of a content node by version id or alias. `version` may be a numeric vid (e.g. 42), an explicit 'id:<vid>', or the relative aliases 'rel:latest-version' / 'rel:working-copy'. Pass langcode to read the unpublished working translation of that node (Sentinel). Read-only; attributes are redacted per security policy.",
     inputSchema: {
       type: "object", required: ["type", "id", "version"],
       properties: {
         site:    { type: "string" },
         type:    { type: "string", description: "Content type machine name" },
         id:      { type: "string", description: "Node UUID" },
+        langcode: { type: "string", description: "Target language for the unpublished working translation (e.g. 'es')." },
         version: {
           type: ["string", "number"],
           description: "Numeric vid, 'id:<vid>', 'rel:latest-version', or 'rel:working-copy'.",

package/src/tools/translations.js

@@ -1,57 +1,55 @@
 /**
  * Tool group: Content translations (multilingual / content_translation).
  *
- * Drupal core JSON:API does not model translations as standalone resources —
- * a translatable entity carries a `langcode` attribute and Drupal serves the
- * negotiated/default-language variant of a resource at its canonical path. To
- * surface multilingual handling cleanly we expose:
+ * Core JSON:API does not add a translation by PATCHing `langcode` on the
+ * canonical entity — that mutates the default language. Governed node
+ * translations go through Sentinel's draft-translation surface:
  *
- *   - drupal_list_translations  — read the entity and report its langcode(s).
- *   - drupal_create_translation — governed write: set/replace a translation by
- *     PATCHing the entity with the target `langcode` plus the supplied fields.
+ *   - drupal_list_translations  — inventory of live and working languages
+ *   - drupal_create_translation — add a language as an unpublished forward draft
  *
- * Requirements (server side):
- *   - The Drupal `content_translation` module must be enabled and the target
- *     entity type/bundle configured as translatable, otherwise create attempts
- *     are rejected by Drupal and listing only ever reports the single language.
+ * Continuation of an existing unpublished translation is drupal_update_node
+ * with `langcode`. Reads of that draft are drupal_get_node / drupal_get_revision
+ * with `langcode`.
  *
- * Limitation: core JSON:API exposes the resource in one language at a time and
- * does not enumerate every available translation as a distinct resource. This
- * module therefore reports the langcode(s) it can observe on the returned
- * resource. Enumerating ALL translations of an entity requires either the
- * contrib "JSON:API Translation" module or the Drush bridge, neither of which
- * is assumed here — see the `note` field on the list result.
- *
- * Reads are redacted per the site security policy; the create path is a
- * governed write (asserts the "update" operation — a translation is a facet of
- * an existing entity, not a new entity).
+ * Paragraph field-value translation uses the same surface with
+ * entityType "paragraph" and the pinned paragraph revision. Image alt is a
+ * node relationship (`meta.alt`) with the shared file target unchanged.
  */
 
 import { getSiteConfig } from "../lib/config.js";
 import { resolveBackend } from "../lib/backends/index.js";
 import {
-  resolveSecurityConfig, assertReadAllowed, assertWriteAllowed, redactCanonicalEntity,
+  resolveSecurityConfig, assertReadAllowed, assertWriteAllowed, assertPublishAllowed,
+  redactCanonicalEntity,
 } from "../lib/security.js";
 import { validateUuid, validateMachineName } from "../lib/validate.js";
+import { applySafeDraftDefault } from "../lib/moderation-default.js";
+import { omitLiveComputedMetatag } from "../lib/entity-response.js";
+import { entityRevisionId } from "../lib/write-revision.js";
+import { paragraphRevisionId } from "../lib/err-relationships.js";
+import {
+  assertDraftLangcode,
+  createTranslationDraft,
+  readTranslationInventory,
+  resolveNodeTranslationPair,
+} from "../lib/draft-write.js";
 
 const LIST_NOTE =
-  "Core JSON:API serves one language per resource and does not enumerate every " +
-  "translation. langcodes reflects only the language(s) observable on the fetched " +
-  "resource. Full enumeration requires the JSON:API Translation contrib module or " +
-  "the Drush bridge. Creating translations requires content_translation enabled and " +
-  "the bundle configured as translatable.";
+  "Live languages are those on the default revision. Working languages are the " +
+  "unpublished forward revision when the principal can view it. Core JSON:API " +
+  "alone cannot enumerate translations; this inventory requires Sentinel's " +
+  "mcp-translations endpoint.";
+
+const FALLBACK_NOTE =
+  "Sentinel's translation inventory is unavailable. Core JSON:API served one " +
+  "language for this resource; it does not prove other translations are absent.";
 
 /**
- * List the translation langcode(s) observable for an entity.
- *
- * Reads the entity through the backend's validated rawQuery (so path segments
- * are checked and content_moderation handling is reused) and reports its
- * `langcode`. The entity type defaults to "node"; pass `entityType` for others.
+ * List live and working translation langcodes for an entity.
  *
  * @param {object} args - { site?, entityType?, type, id }.
- *   `type` is the bundle machine name; `entityType` defaults to "node".
  * @returns {Promise<object|null>} A translation summary, or null if not found.
- * @throws {SecurityError} If reading the type/bundle is not permitted.
  */
 async function listTranslations({ site: siteName, entityType = "node", type, id }) {
   validateMachineName(entityType, "entityType");
@@ -63,6 +61,36 @@ async function listTranslations({ site: siteName, entityType = "node", type, id
   assertReadAllowed(sec, entityType, type);
 
   const backend = await resolveBackend(site);
+  if ((entityType === "node" || entityType === "paragraph") && typeof backend.rawQuery === "function") {
+    try {
+      const meta = await readTranslationInventory(backend, { entityType, bundle: type, id });
+      const liveLangs = (meta.live?.translations ?? []).map((row) => row.langcode);
+      const workingLangs = (meta.working?.translations ?? []).map((row) => row.langcode);
+      const langcodes = [...new Set([...liveLangs, ...workingLangs])];
+      return {
+        id,
+        entityType,
+        bundle: type,
+        defaultLangcode: meta.defaultLangcode ?? liveLangs[0] ?? null,
+        langcodes,
+        live: meta.live ?? null,
+        working: meta.working ?? null,
+        translations: (meta.working?.translations ?? meta.live?.translations ?? []).map((row) => ({
+          langcode: row.langcode,
+          default: Boolean(row.default),
+          status: row.status,
+          title: row.title,
+          moderation_state: row.moderation_state,
+        })),
+        note: LIST_NOTE,
+      };
+    } catch (error) {
+      if (!/does not provide Sentinel's governed draft-translation endpoint/.test(String(error?.message))) {
+        throw error;
+      }
+    }
+  }
+
   const res = await backend.rawQuery({ path: `/jsonapi/${entityType}/${type}/${id}` });
   const data = res?.data;
   if (!data) return null;
@@ -78,69 +106,108 @@ async function listTranslations({ site: siteName, entityType = "node", type, id
     defaultLangcode,
     langcodes,
     translations,
-    note: LIST_NOTE,
+    note: FALLBACK_NOTE,
   };
 }
 
 /**
- * Create (or replace) a translation of an entity for a target language.
- *
- * Governed write. Implemented as a PATCH (via the backend's updateEntity) that
- * sets the target `langcode` alongside the supplied attributes. With
- * content_translation enabled and the bundle marked translatable, Drupal stores
- * the supplied fields against the requested language. If the bundle is not
- * translatable, Drupal rejects the write and the error surfaces to the caller.
+ * Create a translation as an unpublished non-default draft revision.
  *
- * The result is redacted per the site policy.
+ * Does not PATCH canonical langcode. Requires Sentinel's translation endpoint.
+ * An existing translation is a conflict. English live fields stay unchanged.
  *
  * @param {object} args - { site?, entityType?, type, id, langcode, attributes? }.
- *   `type` is the bundle; `entityType` defaults to "node"; `langcode` is the
- *   target language (e.g. "de"); `attributes` are the translated field values.
- * @returns {Promise<object>} The updated/redacted entity descriptor.
- * @throws {SecurityError} If writing the type/bundle is not permitted.
- * @throws {Error} If langcode/id/type are invalid, or Drupal rejects the write.
+ * @returns {Promise<object>} The created translation, redacted.
  */
-async function createTranslation({ site: siteName, entityType = "node", type, id, langcode, attributes = {} }) {
+async function createTranslation({
+  site: siteName, entityType = "node", type, id, langcode, attributes = {},
+  relationships, revisionId, dryRun = false,
+}) {
   validateMachineName(entityType, "entityType");
   validateMachineName(type, "type");
   validateUuid(id);
-  // langcode is interpolated into the JSON:API payload and selects the language
-  // variant; validate it as a machine-name-like token (e.g. "en", "pt_br",
-  // "zh_hans") to block injection / malformed values.
-  validateMachineName(langcode, "langcode");
+  const targetLang = assertDraftLangcode(langcode);
 
   const site = getSiteConfig(siteName);
   const sec = resolveSecurityConfig(site);
-  // A translation is a facet of an existing entity → "update", not "create".
   assertWriteAllowed(sec, "update", entityType, type);
 
+  if (entityType !== "node" && entityType !== "paragraph") {
+    throw new Error("Governed translation create is implemented for nodes and paragraphs.");
+  }
+
   const backend = await resolveBackend(site);
-  const updated = await backend.updateEntity({
-    entityType,
-    bundle: type,
-    id,
-    attributes: { ...attributes, langcode },
+  const existing = await backend.getEntity({ entityType, bundle: type, id });
+  if (!existing) {
+    throw new Error("The entity was not found.");
+  }
+
+  let draftRevision;
+  let drafted = { ...attributes };
+  delete drafted.langcode;
+  if (entityType === "paragraph") {
+    const pinned = revisionId ?? paragraphRevisionId(existing);
+    if (pinned === null || pinned === undefined || pinned === "") {
+      throw new Error("Paragraph translation create requires a paragraph revision ID (the host pin).");
+    }
+    draftRevision = { revisionId: pinned };
+    assertPublishAllowed(sec, drafted);
+  } else {
+    draftRevision = await resolveNodeTranslationPair(backend, {
+      entityType, bundle: type, id, existing,
+    });
+    if (drafted.status === undefined && drafted.moderation_state === undefined) {
+      drafted.moderation_state = "draft";
+    }
+    drafted = await applySafeDraftDefault({
+      backend, entityType, bundle: type, id, attributes: drafted, existingEntity: existing,
+    });
+    assertPublishAllowed(sec, drafted);
+  }
+
+  if (dryRun) {
+    await createTranslationDraft(backend, {
+      entityType, bundle: type, id, langcode: targetLang, attributes: drafted, relationships, draftRevision,
+    }, true);
+    return {
+      dryRun: true, operation: "create_translation", entityType, bundle: type, id,
+      langcode: targetLang, attributes: drafted, ...(relationships ? { relationships } : {}),
+    };
+  }
+
+  const created = await createTranslationDraft(backend, {
+    entityType, bundle: type, id, langcode: targetLang, attributes: drafted, relationships, draftRevision,
   });
-  return redactCanonicalEntity(updated, sec, entityType);
+  const redacted = omitLiveComputedMetatag(redactCanonicalEntity(created, sec, entityType));
+  if (entityType !== "node") return redacted;
+  const workingVid = entityRevisionId(created) ?? draftRevision.workingVid;
+  const liveVid = draftRevision.liveVid;
+  if (liveVid === undefined || liveVid === null) {
+    if (workingVid === undefined || workingVid === null) return redacted;
+  }
+  return {
+    ...redacted,
+    _revisions: {
+      ...(liveVid !== undefined && liveVid !== null ? { live: liveVid } : {}),
+      ...(workingVid !== undefined && workingVid !== null ? { working: workingVid } : {}),
+    },
+  };
 }
 
-// ---------------------------------------------------------------------------
-// Tool definitions
-// ---------------------------------------------------------------------------
-
 export const definitions = [
   {
     name: "drupal_list_translations",
     description:
-      "List the translation langcode(s) for a Drupal entity (multilingual / content_translation). " +
-      "Reports the language(s) observable on the resource. Core JSON:API serves one language per " +
-      "resource and does not enumerate all translations — see the returned note. Defaults to node.",
+      "List live and working translation langcodes for a Drupal node or paragraph. Uses Sentinel's " +
+      "translation inventory when available (live default revision vs unpublished working " +
+      "draft). Core JSON:API alone serves one language and cannot prove others are absent. " +
+      "Defaults to node.",
     inputSchema: {
       type: "object", required: ["type", "id"],
       properties: {
         site:       { type: "string", description: "Named site (omit for default)" },
         entityType: { type: "string", description: "Entity type machine name. Default: 'node'." },
-        type:       { type: "string", description: "Bundle machine name, e.g. 'article'" },
+        type:       { type: "string", description: "Bundle machine name, e.g. 'basic_page'" },
         id:         { type: "string", description: "Entity UUID" },
       },
     },
@@ -148,28 +215,35 @@ export const definitions = [
   {
     name: "drupal_create_translation",
     description:
-      "Create or replace a translation of a Drupal entity for a target language (governed write). " +
-      "Sets the given langcode plus the supplied translated field values. Requires the content_translation " +
-      "module enabled and the bundle configured as translatable; otherwise Drupal rejects the write. " +
-      "Defaults to node.",
+      "Create a translation as an unpublished non-default draft (governed write). " +
+      "Adds the target language beside the default language; it does not PATCH langcode on " +
+      "the canonical entity. When an English working draft already exists, both live and " +
+      "working revision IDs are sent (If-Match) so Sentinel will add the language on that " +
+      "draft (#282). English live title, body, status, alias, default revision, and " +
+      "paragraph ERR pins stay unchanged. An existing translation is a conflict, not an overwrite. " +
+      "The response includes `_revisions.live` / `_revisions.working` when known. " +
+      "Computed `metatag` is omitted on the draft body because JSON:API resolves it from the live default (#283); use field_metatags. " +
+      "Continue a node draft with drupal_update_node and langcode; continue a paragraph with " +
+      "drupal_update_paragraph and langcode. Image alt is a relationship (same file UUID, " +
+      "meta.alt). For paragraphs pass revisionId as the host pin. Requires Sentinel's " +
+      "draft-translation endpoint. Publication stays denied for content-tier callers.",
     inputSchema: {
       type: "object", required: ["type", "id", "langcode"],
       properties: {
-        site:       { type: "string" },
-        entityType: { type: "string", description: "Entity type machine name. Default: 'node'." },
-        type:       { type: "string", description: "Bundle machine name, e.g. 'article'" },
-        id:         { type: "string", description: "Entity UUID" },
-        langcode:   { type: "string", description: "Target language code, e.g. 'de', 'fr', 'pt_br'" },
-        attributes: { type: "object", description: "Translated field values keyed by Drupal machine name" },
+        site:          { type: "string" },
+        entityType:    { type: "string", description: "Entity type machine name. Default: 'node'. Use 'paragraph' for paragraph field values." },
+        type:          { type: "string", description: "Bundle machine name, e.g. 'basic_page' or 'p_hero'" },
+        id:            { type: "string", description: "Entity UUID" },
+        langcode:      { type: "string", description: "Target language code, e.g. 'es', 'de', 'pt-br'" },
+        attributes:    { type: "object", description: "Translated field values keyed by Drupal machine name" },
+        relationships: { type: "object", description: "JSON:API relationships. Use for image alt (same file UUID, meta.alt)." },
+        revisionId:    { type: "string", description: "Paragraph revision id the host already pins. Required for Home-shaped non-default pins." },
+        dryRun:        { type: "boolean", description: "Validate without saving" },
       },
     },
   },
 ];
 
-// ---------------------------------------------------------------------------
-// Handler map
-// ---------------------------------------------------------------------------
-
 export const handlers = {
   drupal_list_translations:  listTranslations,
   drupal_create_translation: createTranslation,