drupal-mcp-connector 2.14.0 → 2.14.2

package/.agents/commands/drupal-create-translation.md

@@ -1,22 +1,23 @@
 ---
-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."
-argument-hint: "<type> <id> <langcode> [site] [entityType] [attributes]"
+description: "Create a translation as an unpublished non-default draft revision (governed write). Adds the target language beside the default language; it does not PATCH langcode on the canonical entity. English live title, body, status, alias, and default revision stay unchanged. An existing translation is a conflict, not an overwrite. Continue the draft with drupal_update_node and langcode. Requires Sentinel's draft-translation endpoint and a translatable bundle. Paragraph field values are not translated on this path. Defaults to node. Publication stays denied for content-tier callers."
+argument-hint: "<type> <id> <langcode> [site] [entityType] [attributes] [dryRun]"
 ---
 
 Call the MCP tool `drupal_create_translation`.
 
-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 revision (governed write). Adds the target language beside the default language; it does not PATCH langcode on the canonical entity. English live title, body, status, alias, and default revision stay unchanged. An existing translation is a conflict, not an overwrite. Continue the draft with drupal_update_node and langcode. Requires Sentinel's draft-translation endpoint and a translatable bundle. Paragraph field values are not translated on this path. Defaults to node. Publication stays denied for content-tier callers.
 
 Parse the arguments supplied with this command into this tool's parameters:
 
 **Required:**
-- `type` (string): Bundle machine name, e.g. 'article'
+- `type` (string): Bundle machine name, e.g. 'basic_page'
 - `id` (string): Entity UUID
-- `langcode` (string): Target language code, e.g. 'de', 'fr', 'pt_br'
+- `langcode` (string): Target language code, e.g. 'es', 'de', 'pt-br'
 
 **Optional:**
 - `site` (string): Named site from connector config. Omit only on reads: multi-site configs fall back to defaultSite (often local/dev, not production). Writes require an explicit site when more than one site is configured. Every response includes `_target` { name, baseUrl, source } (`hint` when you passed site, `default` when you did not).
 - `entityType` (string): Entity type machine name. Default: 'node'.
 - `attributes` (object (pass as JSON)): Translated field values keyed by Drupal machine name
+- `dryRun` (boolean (true/false)): Validate without saving
 
 If a required parameter is missing, ask before calling — do not invent values. Coerce each value to its JSON type (booleans → true/false, numbers → numeric, object/array → parse JSON), then make the single tool call and summarize the result.

package/.agents/commands/drupal-entity-update.md

@@ -1,6 +1,6 @@
 ---
 description: "Update an existing entity of any Drupal entity type. Only include attributes/relationships you want to change. Published moderated targets without an explicit attributes.moderation_state default to moderation_state 'draft' (forward revision). Paragraph / ERR identifiers are resolved to include meta.target_revision_id before PATCH; the write fails if any ref cannot be resolved. On moderated targets a non-saving PATCH preflight runs first (including dryRun) against the same URL the write will hit. An addressable node draft uses Sentinel's governed draft endpoint with live/working revision preconditions (#166); a stray revision with no addressable working copy still fails with revision-surgery language (#201). Preflight does not un-orphan paragraphs already created — probe the host before creating dependents."
-argument-hint: "<entityType> <bundle> <id> [site] [attributes] [relationships] [dryRun] [returning]"
+argument-hint: "<entityType> <bundle> <id> [site] [langcode] [attributes] [relationships] [dryRun] [returning]"
 ---
 
 Call the MCP tool `drupal_entity_update`.
@@ -16,6 +16,7 @@ Parse the arguments supplied with this command into this tool's parameters:
 
 **Optional:**
 - `site` (string): Named site from connector config. Omit only on reads: multi-site configs fall back to defaultSite (often local/dev, not production). Writes require an explicit site when more than one site is configured. Every response includes `_target` { name, baseUrl, source } (`hint` when you passed site, `default` when you did not).
+- `langcode` (string): Target language for an unpublished working translation (nodes). Continues that translation via Sentinel.
 - `attributes` (object (pass as JSON))
 - `relationships` (object (pass as JSON))
 - `dryRun` (boolean (true/false)): Validate, resolve ERR identifiers, and (on moderated targets) run the core PATCH-guard probe against Drupal, then return a preview without the real write. An existing node draft uses Sentinel's non-saving draft endpoint with the real payload and revision preconditions. Otherwise an id-mismatch core PATCH probes writability without saving. Any refusal fails the dryRun.

package/.agents/commands/drupal-get-node.md

@@ -1,11 +1,11 @@
 ---
-description: "Fetch a single Drupal content node by UUID and content type. Returns title, body, status, path alias, and all attributes."
-argument-hint: "<type> <id> [site]"
+description: "Fetch a single Drupal content node by UUID and content type. Returns title, body, status, path alias, and all attributes. Pass langcode to read a working translation draft via Sentinel (distinct from published English)."
+argument-hint: "<type> <id> [site] [langcode]"
 ---
 
 Call the MCP tool `drupal_get_node`.
 
-Fetch a single Drupal content node by UUID and content type. Returns title, body, status, path alias, and all attributes.
+Fetch a single Drupal content node by UUID and content type. Returns title, body, status, path alias, and all attributes. Pass langcode to read a working translation draft via Sentinel (distinct from published English).
 
 Parse the arguments supplied with this command into this tool's parameters:
 
@@ -15,5 +15,6 @@ Parse the arguments supplied with this command into this tool's parameters:
 
 **Optional:**
 - `site` (string): Named site from connector config. Omit only on reads: multi-site configs fall back to defaultSite (often local/dev, not production). Writes require an explicit site when more than one site is configured. Every response includes `_target` { name, baseUrl, source } (`hint` when you passed site, `default` when you did not).
+- `langcode` (string): Target language (e.g. 'es') to read the unpublished working translation instead of the default language.
 
 If a required parameter is missing, ask before calling — do not invent values. Coerce each value to its JSON type (booleans → true/false, numbers → numeric, object/array → parse JSON), then make the single tool call and summarize the result.

package/.agents/commands/drupal-get-revision.md

@@ -1,11 +1,11 @@
 ---
-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."
-argument-hint: "<type> <id> <version> [site]"
+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'. Pass langcode to read the unpublished working translation of that node (Sentinel). Read-only; attributes are redacted per security policy."
+argument-hint: "<type> <id> <version> [site] [langcode]"
 ---
 
 Call the MCP tool `drupal_get_revision`.
 
-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.
 
 Parse the arguments supplied with this command into this tool's parameters:
 
@@ -16,5 +16,6 @@ Parse the arguments supplied with this command into this tool's parameters:
 
 **Optional:**
 - `site` (string): Named site from connector config. Omit only on reads: multi-site configs fall back to defaultSite (often local/dev, not production). Writes require an explicit site when more than one site is configured. Every response includes `_target` { name, baseUrl, source } (`hint` when you passed site, `default` when you did not).
+- `langcode` (string): Target language for the unpublished working translation (e.g. 'es').
 
 If a required parameter is missing, ask before calling — do not invent values. Coerce each value to its JSON type (booleans → true/false, numbers → numeric, object/array → parse JSON), then make the single tool call and summarize the result.

package/.agents/commands/drupal-list-translations.md

@@ -1,16 +1,16 @@
 ---
-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."
+description: "List live and working translation langcodes for a Drupal node. 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."
 argument-hint: "<type> <id> [site] [entityType]"
 ---
 
 Call the MCP tool `drupal_list_translations`.
 
-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. 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.
 
 Parse the arguments supplied with this command into this tool's parameters:
 
 **Required:**
-- `type` (string): Bundle machine name, e.g. 'article'
+- `type` (string): Bundle machine name, e.g. 'basic_page'
 - `id` (string): Entity UUID
 
 **Optional:**

package/.agents/commands/drupal-update-node.md

@@ -1,11 +1,11 @@
 ---
-description: "Update an existing node. Only include fields you want to change. For moderated content types, use moderationState (e.g. 'published') rather than status. When the target is published and moderated and you omit moderationState, the connector defaults the write to moderation_state 'draft' (forward revision) so live default revisions are not mutated by accident. Entity-reference fields go in `relationships`, not `fields`. Paragraph / ERR identifiers are resolved to include meta.target_revision_id before PATCH; the write fails if any ref cannot be resolved (an unresolved identifier persists as an empty field). On moderated targets a non-saving PATCH preflight runs first — including on dryRun — against the same URL the write will hit. An addressable node draft uses Sentinel's governed draft endpoint with live/working revision preconditions (#166); dryRun uses that same target. workingCopy:null from drupal_list_revisions is not proof the node is writable (possiblyPatchBlocked / #201). Preflight here does not un-orphan paragraphs already created; probe the host before creating dependents."
-argument-hint: "<type> <id> [site] [title] [body] [summary] [format] [status] [moderationState] [fields] [relationships] [dryRun] [returning]"
+description: "Update an existing node. Only include fields you want to change. For moderated content types, use moderationState (e.g. 'published') rather than status. When the target is published and moderated and you omit moderationState, the connector defaults the write to moderation_state 'draft' (forward revision) so live default revisions are not mutated by accident. Pass langcode to continue an unpublished working translation (Sentinel X-MCP-Draft-Langcode); this does not PATCH canonical langcode and will not create a missing translation — use drupal_create_translation first. Entity-reference fields go in `relationships`, not `fields`. Paragraph / ERR identifiers are resolved to include meta.target_revision_id before PATCH; the write fails if any ref cannot be resolved (an unresolved identifier persists as an empty field). On moderated targets a non-saving PATCH preflight runs first — including on dryRun — against the same URL the write will hit. An addressable node draft uses Sentinel's governed draft endpoint with live/working revision preconditions (#166); dryRun uses that same target. workingCopy:null from drupal_list_revisions is not proof the node is writable (possiblyPatchBlocked / #201). Preflight here does not un-orphan paragraphs already created; probe the host before creating dependents."
+argument-hint: "<type> <id> [site] [title] [body] [summary] [format] [status] [moderationState] [langcode] [fields] [relationships] [dryRun] [returning]"
 ---
 
 Call the MCP tool `drupal_update_node`.
 
-Update an existing node. Only include fields you want to change. For moderated content types, use moderationState (e.g. 'published') rather than status. When the target is published and moderated and you omit moderationState, the connector defaults the write to moderation_state 'draft' (forward revision) so live default revisions are not mutated by accident. Entity-reference fields go in `relationships`, not `fields`. Paragraph / ERR identifiers are resolved to include meta.target_revision_id before PATCH; the write fails if any ref cannot be resolved (an unresolved identifier persists as an empty field). On moderated targets a non-saving PATCH preflight runs first — including on dryRun — against the same URL the write will hit. An addressable node draft uses Sentinel's governed draft endpoint with live/working revision preconditions (#166); dryRun uses that same target. workingCopy:null from drupal_list_revisions is not proof the node is writable (possiblyPatchBlocked / #201). Preflight here does not un-orphan paragraphs already created; probe the host before creating dependents.
+Update an existing node. Only include fields you want to change. For moderated content types, use moderationState (e.g. 'published') rather than status. When the target is published and moderated and you omit moderationState, the connector defaults the write to moderation_state 'draft' (forward revision) so live default revisions are not mutated by accident. Pass langcode to continue an unpublished working translation (Sentinel X-MCP-Draft-Langcode); this does not PATCH canonical langcode and will not create a missing translation — use drupal_create_translation first. Entity-reference fields go in `relationships`, not `fields`. Paragraph / ERR identifiers are resolved to include meta.target_revision_id before PATCH; the write fails if any ref cannot be resolved (an unresolved identifier persists as an empty field). On moderated targets a non-saving PATCH preflight runs first — including on dryRun — against the same URL the write will hit. An addressable node draft uses Sentinel's governed draft endpoint with live/working revision preconditions (#166); dryRun uses that same target. workingCopy:null from drupal_list_revisions is not proof the node is writable (possiblyPatchBlocked / #201). Preflight here does not un-orphan paragraphs already created; probe the host before creating dependents.
 
 Parse the arguments supplied with this command into this tool's parameters:
 
@@ -21,6 +21,7 @@ Parse the arguments supplied with this command into this tool's parameters:
 - `format` (string): Text format machine name for the body, e.g. 'basic_html'. When the body field's allowed_formats lists exactly one format, that is the default. A caller format outside that list is refused before write. When allowed_formats cannot be resolved, defaults to the site config's `defaultTextFormat`, then 'full_html'.
 - `status` (boolean (true/false)): Published flag for NON-moderated types: true = publish, false = unpublish. Ignored if moderationState is set.
 - `moderationState` (string): Moderation state transition for content_moderation types, e.g. 'draft', 'published', 'archived'. Takes precedence over status. Required to keep or re-publish a live node — omitting it on a published moderated node defaults the write to 'draft'.
+- `langcode` (string): Target language for an unpublished working translation (e.g. 'es'). Continues that translation via Sentinel; does not create a missing translation and does not PATCH canonical langcode.
 - `fields` (object (pass as JSON)): Scalar/attribute field values keyed by machine name. Formatted text: a string or { value, format?, summary? }. format must be in the field's allowed_formats; a single allowed format is used when omitted. Entity-reference fields go in `relationships`, not here.
 - `relationships` (object (pass as JSON)): Entity-reference fields as JSON:API relationships, keyed by field machine name. Single-value uses { data: { type, id } }; multi-value uses { data: [{ type, id }, …] }. Paragraph / ERR items must carry meta.target_revision_id — the connector injects it when missing, and fails the write if it cannot.
 - `dryRun` (boolean (true/false)): Validate, resolve ERR identifiers, and (on moderated targets) run the core PATCH-guard probe against Drupal, then return a preview without the real write. An existing node draft uses Sentinel's non-saving draft endpoint with the real payload and revision preconditions. Otherwise an id-mismatch core PATCH probes writability without saving. Any refusal fails the dryRun.

package/CHANGELOG.md

@@ -7,6 +7,37 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.14.2] - 2026-09-10
+
+### Fixed
+- **`langcode` reads target only an unpublished working translation.**
+  After a Spanish draft exists, English on that working revision is still
+  the published copy. `drupal_get_node` / `drupal_get_revision` with
+  `langcode` now read the working translation only when that language is
+  unpublished, so they do not treat published English as a draft.
+- **Spanish (and other) draft translations beside published English (#276).**
+  `drupal_create_translation` no longer PATCHes `langcode` on the canonical
+  entity. It POSTs Sentinel's `/mcp-draft/translations` endpoint so Drupal
+  calls `addTranslation()` on an unpublished forward revision. The live
+  default language, revision id, title, body, status, and alias stay
+  unchanged. An existing translation is a conflict. Continue the draft with
+  `drupal_update_node` + `langcode`; read it with `drupal_get_node` /
+  `drupal_list_translations` / `drupal_get_revision` + `langcode`. Requires
+  MCP Sentinel with the draft-translation contract. Paragraph field-value
+  translation and media photo-alt translation remain pending. A content-tier
+  caller still cannot publish through this path.
+
+## [2.14.1] - 2026-09-09
+
+### Changed
+- README, CONTRIBUTING, and the package.json author URL now link
+  Jeremy Michael Cerda to the drupal.org profile
+  (`https://www.drupal.org/u/jmcerda`).
+- README and docs now report 120 tools and 125 prompts (one per tool
+  plus 5 workflow prompts), matching the shipped surface. The tools
+  reference documents `drupal_create_redirect`,
+  `drupal_update_redirect`, and `drupal_update_menu_link`.
+
 ## [2.14.0] - 2026-09-06
 
 ### Added
@@ -1470,6 +1501,8 @@ The connector is now **dual-protocol**: every tool runs against an abstract back
 - User tools gained explicit PII-access assertions.
 - Whole tree lint-clean (`npm run lint`) with object-injection sinks rewritten to safe lookups.
 
+[2.14.2]: https://github.com/Wilkes-Liberty/drupal-mcp-connector/releases/tag/v2.14.2
+[2.14.1]: https://github.com/Wilkes-Liberty/drupal-mcp-connector/releases/tag/v2.14.1
 [2.14.0]: https://github.com/Wilkes-Liberty/drupal-mcp-connector/releases/tag/v2.14.0
 [2.13.1]: https://github.com/Wilkes-Liberty/drupal-mcp-connector/releases/tag/v2.13.1
 [2.13.0]: https://github.com/Wilkes-Liberty/drupal-mcp-connector/releases/tag/v2.13.0

package/README.md

@@ -7,7 +7,7 @@
 [![Drupal](https://img.shields.io/badge/drupal-10%20%7C%2011-blue)](https://drupal.org)
 [![MCP](https://img.shields.io/badge/MCP-2026--07--28-purple)](https://modelcontextprotocol.io)
 
-Built by **Jeremy Michael Cerda** (opensource@wilkesliberty.com). Maintained by [Wilkes & Liberty, LLC](https://github.com/Wilkes-Liberty).
+Built by **[Jeremy Michael Cerda](https://www.drupal.org/u/jmcerda)** (opensource@wilkesliberty.com). Maintained by [Wilkes & Liberty, LLC](https://github.com/Wilkes-Liberty).
 
 **If the client only shows `drupal_list_sites` and `drupal_governance_status`**, the secret env vars named in `config.json` are unset. Upgrade to the current release (2.6.1 first fixed this), or stay on 2.6.0 and launch via `bin/drupal-mcp-launch.sh` with a `config/secrets.map` (`ENV_VAR=keychain-item`). Then restart the MCP server. See [#199](https://github.com/Wilkes-Liberty/drupal-mcp-connector/issues/199).
 
@@ -63,7 +63,7 @@ See **[docs/architecture.md](docs/architecture.md)** for the backend abstraction
 
 ## Features
 
-### 119 Tools Across 26 Modules
+### 120 Tools Across 26 Modules
 
 | Module | Tools |
 |--------|-------|
@@ -301,7 +301,7 @@ an operator channel: keep the agent's credentials off it, and pin
 | [OAuth client_credentials](docs/oauth-client-credentials.md) | Production OAuth deploy: scope→role mapping, JSON:API writes, config persistence, secret handling, troubleshooting |
 | [Architecture](docs/architecture.md) | Backend abstraction, canonical model, and how to extend it |
 | [GraphQL Setup](docs/graphql-local-setup.md) | GraphQL Compose backend + local TLS notes |
-| [Tools Reference](docs/tools-reference.md) | Full reference for all 119 tools |
+| [Tools Reference](docs/tools-reference.md) | Full reference for all 120 tools |
 | [Security Guide](docs/security.md) | Presets, entity access control, field redaction |
 | [Security Hardening](docs/security-hardening.md) | Optional transport, identity, and secrets controls |
 | [Verification](docs/verification.md) | Prove a secure install: static + live checks, negative probes, evidence artefact, managed residuals |
@@ -324,4 +324,4 @@ Found a vulnerability? See [SECURITY.md](SECURITY.md). Please do not open a publ
 
 ## License
 
-[MIT](LICENSE) © 2026 Jeremy Michael Cerda and [Wilkes & Liberty, LLC](https://github.com/Wilkes-Liberty)
+[MIT](LICENSE) © 2026 [Jeremy Michael Cerda](https://www.drupal.org/u/jmcerda) and [Wilkes & Liberty, LLC](https://github.com/Wilkes-Liberty)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "drupal-mcp-connector",
-  "version": "2.14.0",
+  "version": "2.14.2",
   "description": "A secure, multi-site Model Context Protocol (MCP) connector for Drupal — dual-protocol JSON:API and GraphQL.",
   "type": "module",
   "main": "src/index.js",
@@ -42,7 +42,7 @@
     "url": "https://github.com/Wilkes-Liberty/drupal-mcp-connector/issues"
   },
   "license": "MIT",
-  "author": "Jeremy Michael Cerda <opensource@wilkesliberty.com> (https://wilkesliberty.com)",
+  "author": "Jeremy Michael Cerda <opensource@wilkesliberty.com> (https://www.drupal.org/u/jmcerda)",
   "contributors": [
     "Wilkes & Liberty, LLC <opensource@wilkesliberty.com> (https://wilkesliberty.com)"
   ],
@@ -79,7 +79,7 @@
     "eslint-plugin-n": "^18.1.0",
     "eslint-plugin-security": "^4.0.0",
     "globals": "^17.6.0",
-    "vitest": "^4.1.8"
+    "vitest": "^5.0.0"
   },
   "overrides": {
     "@hono/node-server": "^2.0.5",

package/src/lib/draft-write.js

@@ -1,8 +1,71 @@
 /**
- * Sentinel's governed draft-continuation contract (d.o #3621022).
+ * Sentinel's governed draft-continuation contract (d.o #3621022 / GitHub #176).
  * Core JSON:API revision selectors support reads, not PATCH requests.
+ * Translation create/update uses the same surface with X-MCP-Draft-Langcode.
  */
 
+const LANGCODE_RE = /^[a-z][a-z0-9_-]{0,11}$/;
+const MISSING_DRAFT_ENDPOINT =
+  "The site does not provide Sentinel's governed draft endpoint (d.o #3621022). " +
+  "Update the server-side module; the draft was not discarded and no canonical fallback was attempted.";
+const MISSING_TRANSLATION_ENDPOINT =
+  "The site does not provide Sentinel's governed draft-translation endpoint. " +
+  "Update MCP Sentinel; no canonical langcode PATCH was attempted.";
+
+/**
+ * @param {unknown} error
+ * @param {string} message
+ * @returns {Error}
+ */
+function missingEndpointError(error, message) {
+  if (/Drupal (404|405)\b/.test(String(error?.message))) {
+    return new Error(message, { cause: error });
+  }
+  return error instanceof Error ? error : new Error(String(error));
+}
+
+/**
+ * @param {string} langcode
+ * @returns {string}
+ */
+export function assertDraftLangcode(langcode) {
+  const value = String(langcode || "").trim();
+  if (!LANGCODE_RE.test(value)) {
+    throw new Error("A valid target langcode is required (for example 'es' or 'pt-br').");
+  }
+  return value;
+}
+
+/**
+ * @param {object} [draftRevision]
+ * @returns {{live: string, working: string}}
+ */
+function requireWorkingPair(draftRevision) {
+  const live = String(draftRevision?.liveVid ?? "");
+  const working = String(draftRevision?.workingVid ?? "");
+  if (!/^[1-9]\d*$/.test(live) || !/^[1-9]\d*$/.test(working) || live === working) {
+    throw new Error("Draft continuation requires distinct, verified live and working node revision IDs.");
+  }
+  return { live, working };
+}
+
+/**
+ * @param {object} backend
+ * @param {string} entityType
+ * @param {string} bundle
+ * @param {string} id
+ * @returns {string}
+ */
+function nodeResource(backend, entityType, bundle, id) {
+  if (entityType !== "node") {
+    throw new Error("Governed draft translation is implemented for nodes.");
+  }
+  if (typeof backend.rawQuery !== "function" || typeof backend.resourcePath !== "function") {
+    throw new Error("This backend does not support governed draft continuation.");
+  }
+  return `${backend.resourcePath(entityType, bundle)}/${encodeURIComponent(id)}`;
+}
+
 /**
  * Validate or continue a draft, using the same payload and revision precondition.
  * No canonical fallback: an absent endpoint or refused precondition stops work.
@@ -12,46 +75,147 @@
  * @returns {Promise<object>} Preflight metadata or the written canonical entity.
  */
 export async function writeDraft(backend, input, preflight = false) {
+  const { entityType, bundle, id, attributes = {}, relationships, draftRevision, langcode } = input;
+  const { live, working } = requireWorkingPair(draftRevision);
+  const base = nodeResource(backend, entityType, bundle, id);
+  const data = { type: `${entityType}--${bundle}`, id, attributes };
+  if (relationships) data.relationships = relationships;
+  const headers = {
+    "If-Match": `"${live}:${working}"`,
+    "X-MCP-Draft-Preflight": preflight ? "1" : "0",
+  };
+  const targetLang = langcode ? assertDraftLangcode(langcode) : null;
+  if (targetLang) headers["X-MCP-Draft-Langcode"] = targetLang;
+  let result;
+  try {
+    result = await backend.rawQuery({
+      path: `${base}/mcp-draft`,
+      options: { method: "PATCH", headers, body: JSON.stringify({ data }) },
+    });
+  } catch (error) {
+    throw missingEndpointError(error, MISSING_DRAFT_ENDPOINT);
+  }
+  if (preflight) {
+    if (result?.meta?.draft_preflight !== true
+      || String(result.meta.live) !== live || String(result.meta.working) !== working) {
+      throw new Error("The site did not confirm a non-saving draft preflight. Refusing to continue.");
+    }
+    if (targetLang && result.meta.langcode && String(result.meta.langcode) !== targetLang) {
+      throw new Error("The site did not confirm the requested translation language. Refusing to continue.");
+    }
+    return result;
+  }
+  if (!result?.data || result.data.id !== id || result.data.type !== data.type) {
+    throw new Error("Draft write response did not identify the requested entity. The write outcome is uncertain; re-read before retrying.");
+  }
+  return backend.toCanonical(result.data);
+}
+
+/**
+ * Create a target-language translation as an unpublished forward revision.
+ * If-Match is `"live"` when there is no working copy, or `"live:working"` when
+ * adding the language onto an existing unpublished English draft.
+ * @param {object} backend
+ * @param {object} input
+ * @param {boolean} [preflight]
+ * @returns {Promise<object>}
+ */
+export async function createTranslationDraft(backend, input, preflight = false) {
   const { entityType, bundle, id, attributes = {}, relationships, draftRevision } = input;
+  const langcode = assertDraftLangcode(input.langcode);
   const live = String(draftRevision?.liveVid ?? "");
-  const working = String(draftRevision?.workingVid ?? "");
-  if (entityType !== "node" || !/^[1-9]\d*$/.test(live)
-    || !/^[1-9]\d*$/.test(working) || live === working) {
-    throw new Error("Draft continuation requires distinct, verified live and working node revision IDs.");
+  const workingRaw = draftRevision?.workingVid;
+  const working = workingRaw === undefined || workingRaw === null || workingRaw === ""
+    ? ""
+    : String(workingRaw);
+  if (entityType !== "node" || !/^[1-9]\d*$/.test(live)) {
+    throw new Error("Translation create requires a verified live node revision ID.");
   }
-  if (typeof backend.rawQuery !== "function" || typeof backend.resourcePath !== "function") {
-    throw new Error("This backend does not support governed draft continuation.");
+  if (working && (!/^[1-9]\d*$/.test(working) || working === live)) {
+    throw new Error("Translation create requires distinct live and working revision IDs when a working copy exists.");
   }
-  const data = { type: `${entityType}--${bundle}`, id, attributes };
+  const base = nodeResource(backend, entityType, bundle, id);
+  const safeAttributes = { ...attributes };
+  delete safeAttributes.langcode;
+  const data = { type: `${entityType}--${bundle}`, id, attributes: safeAttributes };
   if (relationships) data.relationships = relationships;
+  const ifMatch = working ? `"${live}:${working}"` : `"${live}"`;
   let result;
   try {
     result = await backend.rawQuery({
-      path: `${backend.resourcePath(entityType, bundle)}/${encodeURIComponent(id)}/mcp-draft`,
+      path: `${base}/mcp-draft/translations`,
       options: {
-        method: "PATCH",
+        method: "POST",
         headers: {
-          "If-Match": `"${live}:${working}"`,
+          "If-Match": ifMatch,
           "X-MCP-Draft-Preflight": preflight ? "1" : "0",
+          "X-MCP-Draft-Langcode": langcode,
         },
         body: JSON.stringify({ data }),
       },
     });
   } catch (error) {
-    if (/Drupal (404|405)\b/.test(String(error?.message))) {
-      throw new Error("The site does not provide Sentinel's governed draft endpoint (d.o #3621022). Update the server-side module; the draft was not discarded and no canonical fallback was attempted.", { cause: error });
-    }
-    throw error;
+    throw missingEndpointError(error, MISSING_TRANSLATION_ENDPOINT);
   }
   if (preflight) {
-    if (result?.meta?.draft_preflight !== true
-      || String(result.meta.live) !== live || String(result.meta.working) !== working) {
-      throw new Error("The site did not confirm a non-saving draft preflight. Refusing to continue.");
+    if (result?.meta?.draft_preflight !== true || String(result.meta.live) !== live) {
+      throw new Error("The site did not confirm a non-saving translation preflight. Refusing to continue.");
     }
     return result;
   }
   if (!result?.data || result.data.id !== id || result.data.type !== data.type) {
-    throw new Error("Draft write response did not identify the requested entity. The write outcome is uncertain; re-read before retrying.");
+    throw new Error("Translation create response did not identify the requested entity. The write outcome is uncertain; re-read before retrying.");
+  }
+  return backend.toCanonical(result.data);
+}
+
+/**
+ * Read live/working translation inventory from Sentinel.
+ * @param {object} backend
+ * @param {{entityType: string, bundle: string, id: string}} ref
+ * @returns {Promise<object>}
+ */
+export async function readTranslationInventory(backend, { entityType, bundle, id }) {
+  const base = nodeResource(backend, entityType, bundle, id);
+  try {
+    const result = await backend.rawQuery({ path: `${base}/mcp-translations` });
+    if (!result?.meta?.live) {
+      throw new Error("The site did not return a translation inventory.");
+    }
+    return result.meta;
+  } catch (error) {
+    throw missingEndpointError(error, MISSING_TRANSLATION_ENDPOINT);
+  }
+}
+
+/**
+ * Read one unpublished working translation.
+ * @param {object} backend
+ * @param {object} input
+ * @returns {Promise<object>}
+ */
+export async function readDraftTranslation(backend, input) {
+  const { entityType, bundle, id, draftRevision } = input;
+  const langcode = assertDraftLangcode(input.langcode);
+  const { live, working } = requireWorkingPair(draftRevision);
+  const base = nodeResource(backend, entityType, bundle, id);
+  let result;
+  try {
+    result = await backend.rawQuery({
+      path: `${base}/mcp-draft`,
+      options: {
+        method: "GET",
+        headers: {
+          "If-Match": `"${live}:${working}"`,
+          "X-MCP-Draft-Langcode": langcode,
+        },
+      },
+    });
+  } catch (error) {
+    throw missingEndpointError(error, MISSING_TRANSLATION_ENDPOINT);
+  }
+  if (!result?.data || result.data.id !== id) {
+    throw new Error("Draft translation read did not identify the requested entity.");
   }
   return backend.toCanonical(result.data);
 }

package/src/lib/patch-preflight.js

@@ -300,11 +300,25 @@ export async function preflightPatchWritable({
  * @returns {Promise<{resourceVersion: ?string, workingCopy: ?object, liveVid: ?number|string, workingVid: ?number|string}>}
  */
 export async function prepareGuardedPatch(backend, {
-  entityType, bundle, id, existing, attributes, relationships,
+  entityType, bundle, id, existing, attributes, relationships, langcode,
 }) {
   const target = shouldPreflightPatch({ existing, attributes })
     ? await resolveWorkingCopyPatchTarget(backend, { entityType, bundle, id, existing })
     : { resourceVersion: undefined, workingCopy: null, liveVid: null, workingVid: null };
+  if (langcode) {
+    if (!target.workingVid || !target.liveVid || String(target.workingVid) === String(target.liveVid)) {
+      throw new Error(
+        "No unpublished working translation for this language. " +
+        "Create it with drupal_create_translation first; a canonical langcode PATCH is not attempted."
+      );
+    }
+    target.draftRevision = { liveVid: target.liveVid, workingVid: target.workingVid };
+    await writeDraft(backend, {
+      entityType, bundle, id, attributes, relationships, langcode,
+      draftRevision: target.draftRevision,
+    }, true);
+    return target;
+  }
   if (target.resourceVersion) {
     target.draftRevision = { liveVid: target.liveVid, workingVid: target.workingVid };
     await writeDraft(backend, {

package/src/tools/entities.js

@@ -96,7 +96,7 @@ async function createEntity({ site: siteName, entityType, bundle, attributes = {
  * @returns {Promise<object>} The updated entity descriptor.
  * @throws {SecurityError} If updating the type/bundle is not permitted.
  */
-async function updateEntity({ site: siteName, entityType, bundle, id, attributes = {}, relationships = {}, dryRun = false, returning = "full" }) {
+async function updateEntity({ site: siteName, entityType, bundle, id, attributes = {}, relationships = {}, langcode, dryRun = false, returning = "full" }) {
   const site = getSiteConfig(siteName);
   const sec = resolveSecurityConfig(site);
   assertWriteAllowed(sec, "update", entityType, bundle);
@@ -119,6 +119,7 @@ async function updateEntity({ site: siteName, entityType, bundle, id, attributes
   const resolvedRelationships = await resolveErrRelationships(backend, relationships);
   const patchTarget = await prepareGuardedPatch(backend, {
     entityType, bundle, id, existing, attributes: safeAttributes, relationships: resolvedRelationships,
+    langcode,
   });
   if (dryRun) {
     return {
@@ -128,6 +129,7 @@ async function updateEntity({ site: siteName, entityType, bundle, id, attributes
   }
   const result = await updateEntityGuarded(backend, {
     entityType, bundle, id, attributes: safeAttributes, relationships: resolvedRelationships,
+    ...(langcode ? { langcode } : {}),
     ...(patchTarget.resourceVersion ? { resourceVersion: patchTarget.resourceVersion } : {}),
     ...(patchTarget.draftRevision ? { draftRevision: patchTarget.draftRevision } : {}),
   });
@@ -289,6 +291,7 @@ export const definitions = [
         entityType:    { type: "string" },
         bundle:        { type: "string" },
         id:            { type: "string" },
+        langcode:      { type: "string", description: "Target language for an unpublished working translation (nodes). Continues that translation via Sentinel." },
         attributes:    { type: "object" },
         relationships: { type: "object" },
         dryRun:        { type: "boolean", default: false, description: "Validate, resolve ERR identifiers, and (on moderated targets) run the core PATCH-guard probe against Drupal, then return a preview without the real write. An existing node draft uses Sentinel's non-saving draft endpoint with the real payload and revision preconditions. Otherwise an id-mismatch core PATCH probes writability without saving. Any refusal fails the dryRun." },

package/src/tools/nodes.js

@@ -18,6 +18,7 @@ import { shapeWriteResponse, flagUnrequestedStatusChange, RETURNING_SCHEMA } fro
 import { resolveErrRelationships, relationshipsWereSent } from "../lib/err-relationships.js";
 import { attachWrittenRevisionPair, readWrittenRevision } from "../lib/write-revision.js";
 import { prepareGuardedPatch, updateEntityGuarded } from "../lib/patch-preflight.js";
+import { assertDraftLangcode, readDraftTranslation, readTranslationInventory } from "../lib/draft-write.js";
 import { assertBodySummaryWritable, attachSummaryDeprecation } from "../lib/body-summary.js";
 import { buildRedirectAttributes, REDIRECT_ENTITY_TYPE } from "./redirects.js";
 import { applyAllowedFormatsToAttributes } from "../lib/field-definition.js";
@@ -176,12 +177,39 @@ function pageOf({ limit = 20, offset = 0 }) {
  * @param {object} args - { site?, type, id }.
  * @returns {Promise<object|null>} The redacted node, or null if not found.
  */
-async function getNode({ site: siteName, type, id }) {
+async function getNode({ site: siteName, type, id, langcode, resourceVersion }) {
   const site = getSiteConfig(siteName);
   const sec = resolveSecurityConfig(site);
   assertReadAllowed(sec, "node", type);
   const backend = await resolveBackend(site);
-  const entity = await backend.getEntity({ entityType: "node", bundle: type, id });
+  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 (workingRow && workingRow.status === false && inventory.live?.vid && inventory.working?.vid) {
+      const entity = await readDraftTranslation(backend, {
+        entityType: "node", bundle: type, id, langcode: targetLang,
+        draftRevision: { liveVid: inventory.live.vid, workingVid: inventory.working.vid },
+      });
+      return redactCanonicalEntity(entity, sec, "node");
+    }
+    const liveHas = (inventory.live?.translations ?? []).some((row) => row.langcode === targetLang);
+    if (!liveHas) {
+      return null;
+    }
+    if (targetLang !== inventory.defaultLangcode) {
+      const liveRow = (inventory.live.translations ?? []).find((row) => row.langcode === targetLang);
+      return {
+        id, entityType: "node", bundle: type, langcode: targetLang,
+        title: liveRow?.title ?? null,
+        status: liveRow?.status ?? null,
+        fields: { moderation_state: liveRow?.moderation_state },
+        _revisions: { live: inventory.live.vid, working: inventory.working?.vid ?? null },
+        note: "Published non-default translations are listed on the live revision; full field reads of an unpublished working translation use langcode against the working draft.",
+      };
+    }
+  }
+  const entity = await backend.getEntity({ entityType: "node", bundle: type, id, resourceVersion });
   return entity ? redactCanonicalEntity(entity, sec, "node") : null;
 }
 
@@ -310,13 +338,14 @@ async function createNode({ site: siteName, type, title, body, summary, format,
  * @param {object} args - { site?, type, id, title?, body?, summary?, format?, status?, moderationState?, fields?, relationships? }.
  * @returns {Promise<object>} The updated node descriptor.
  */
-async function updateNode({ site: siteName, type, id, title, body, summary, format, status, moderationState, fields = {}, relationships = {}, dryRun = false, returning = "full" }) {
+async function updateNode({ site: siteName, type, id, title, body, summary, format, status, moderationState, langcode, fields = {}, relationships = {}, dryRun = false, returning = "full" }) {
   const site = getSiteConfig(siteName);
   const sec = resolveSecurityConfig(site);
   assertWriteAllowed(sec, "update", "node", type);
   const backend = await resolveBackend(site);
   const summaryWrite = await assertBodySummaryWritable(backend, type, summary);
   let attributes = { ...fields };
+  delete attributes.langcode;
   if (title !== undefined) attributes.title = title;
   if (moderationState !== undefined) attributes.moderation_state = moderationState;
   else if (status !== undefined) attributes.status = status;
@@ -348,6 +377,7 @@ async function updateNode({ site: siteName, type, id, title, body, summary, form
   // governed continuation endpoint; stray revisions still fail the probe.
   const patchTarget = await prepareGuardedPatch(backend, {
     entityType: "node", bundle: type, id, existing, attributes, relationships: resolvedRelationships,
+    langcode,
   });
   if (dryRun) {
     const preview = {
@@ -365,6 +395,7 @@ async function updateNode({ site: siteName, type, id, title, body, summary, form
   else attributes.path = pathAttr;
   const patched = await updateEntityGuarded(backend, {
     entityType: "node", bundle: type, id, attributes, relationships: resolvedRelationships,
+    ...(langcode ? { langcode } : {}),
     ...(patchTarget.resourceVersion ? { resourceVersion: patchTarget.resourceVersion } : {}),
     ...(patchTarget.draftRevision ? { draftRevision: patchTarget.draftRevision } : {}),
   });
@@ -414,13 +445,14 @@ async function deleteNode({ site: siteName, type, id, dryRun = false }) {
 export const definitions = [
   {
     name: "drupal_get_node",
-    description: "Fetch a single Drupal content node by UUID and content type. Returns title, body, status, path alias, and all attributes.",
+    description: "Fetch a single Drupal content node by UUID and content type. Returns title, body, status, path alias, and all attributes. Pass langcode to read a working translation draft via Sentinel (distinct from published English).",
     inputSchema: {
       type: "object", required: ["type", "id"],
       properties: {
         site: { type: "string", description: "Named site (omit for default)" },
         type: { type: "string", description: "Content type machine name, e.g. 'article'" },
         id:   { type: "string", description: "Node UUID" },
+        langcode: { type: "string", description: "Target language (e.g. 'es') to read the unpublished working translation instead of the default language." },
       },
     },
   },
@@ -477,7 +509,7 @@ export const definitions = [
   },
   {
     name: "drupal_update_node",
-    description: "Update an existing node. Only include fields you want to change. For moderated content types, use moderationState (e.g. 'published') rather than status. When the target is published and moderated and you omit moderationState, the connector defaults the write to moderation_state 'draft' (forward revision) so live default revisions are not mutated by accident. Entity-reference fields go in `relationships`, not `fields`. Paragraph / ERR identifiers are resolved to include meta.target_revision_id before PATCH; the write fails if any ref cannot be resolved (an unresolved identifier persists as an empty field). On moderated targets a non-saving PATCH preflight runs first — including on dryRun — against the same URL the write will hit. An addressable node draft uses Sentinel's governed draft endpoint with live/working revision preconditions (#166); dryRun uses that same target. workingCopy:null from drupal_list_revisions is not proof the node is writable (possiblyPatchBlocked / #201). Preflight here does not un-orphan paragraphs already created; probe the host before creating dependents.",
+    description: "Update an existing node. Only include fields you want to change. For moderated content types, use moderationState (e.g. 'published') rather than status. When the target is published and moderated and you omit moderationState, the connector defaults the write to moderation_state 'draft' (forward revision) so live default revisions are not mutated by accident. Pass langcode to continue an unpublished working translation (Sentinel X-MCP-Draft-Langcode); this does not PATCH canonical langcode and will not create a missing translation — use drupal_create_translation first. Entity-reference fields go in `relationships`, not `fields`. Paragraph / ERR identifiers are resolved to include meta.target_revision_id before PATCH; the write fails if any ref cannot be resolved (an unresolved identifier persists as an empty field). On moderated targets a non-saving PATCH preflight runs first — including on dryRun — against the same URL the write will hit. An addressable node draft uses Sentinel's governed draft endpoint with live/working revision preconditions (#166); dryRun uses that same target. workingCopy:null from drupal_list_revisions is not proof the node is writable (possiblyPatchBlocked / #201). Preflight here does not un-orphan paragraphs already created; probe the host before creating dependents.",
     inputSchema: {
       type: "object", required: ["type", "id"],
       properties: {
@@ -490,6 +522,7 @@ export const definitions = [
         format:  { type: "string", description: "Text format machine name for the body, e.g. 'basic_html'. When the body field's allowed_formats lists exactly one format, that is the default. A caller format outside that list is refused before write. When allowed_formats cannot be resolved, defaults to the site config's `defaultTextFormat`, then 'full_html'." },
         status:  { type: "boolean", description: "Published flag for NON-moderated types: true = publish, false = unpublish. Ignored if moderationState is set." },
         moderationState: { type: "string", description: "Moderation state transition for content_moderation types, e.g. 'draft', 'published', 'archived'. Takes precedence over status. Required to keep or re-publish a live node — omitting it on a published moderated node defaults the write to 'draft'." },
+        langcode: { type: "string", description: "Target language for an unpublished working translation (e.g. 'es'). Continues that translation via Sentinel; does not create a missing translation and does not PATCH canonical langcode." },
         fields:  { type: "object", description: "Scalar/attribute field values keyed by machine name. Formatted text: a string or { value, format?, summary? }. format must be in the field's allowed_formats; a single allowed format is used when omitted. Entity-reference fields go in `relationships`, not here." },
         relationships: { type: "object", description: "Entity-reference fields as JSON:API relationships, keyed by field machine name. Single-value uses { data: { type, id } }; multi-value uses { data: [{ type, id }, …] }. Paragraph / ERR items must carry meta.target_revision_id — the connector injects it when missing, and fails the write if it cannot." },
         dryRun:  { type: "boolean", default: false, description: "Validate, resolve ERR identifiers, and (on moderated targets) run the core PATCH-guard probe against Drupal, then return a preview without the real write. An existing node draft uses Sentinel's non-saving draft endpoint with the real payload and revision preconditions. Otherwise an id-mismatch core PATCH probes writability without saving. Any refusal fails the dryRun." },

package/src/tools/revisions.js

@@ -21,8 +21,9 @@
 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";
 
 // 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 +206,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 = 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 +344,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,52 @@
 /**
  * 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 is not supported on this path. Shared
+ * structure (references, files, aliases) stays on the source language.
  */
 
 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 { loadWorkingCopy } from "../lib/patch-preflight.js";
+import { entityRevisionId } from "../lib/write-revision.js";
+import {
+  assertDraftLangcode,
+  createTranslationDraft,
+  readTranslationInventory,
+} 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 +58,36 @@ async function listTranslations({ site: siteName, entityType = "node", type, id
   assertReadAllowed(sec, entityType, type);
 
   const backend = await resolveBackend(site);
+  if (entityType === "node" && 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 +103,89 @@ 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.
+ * Create a translation as an unpublished non-default draft revision.
  *
- * 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.
- *
- * 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 = {}, 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") {
+    throw new Error("Governed translation create is implemented for nodes. Other entity types are not addressed by the draft-translation contract.");
+  }
+
   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.");
+  }
+  const liveVid = entityRevisionId(existing);
+  const workingCopy = await loadWorkingCopy(backend, { entityType, bundle: type, id });
+  const workingVid = entityRevisionId(workingCopy);
+  const sameWorking = workingVid !== null && liveVid !== null && String(workingVid) === String(liveVid);
+  const draftRevision = {
+    liveVid,
+    workingVid: workingCopy && !sameWorking ? workingVid : undefined,
+  };
+
+  const safeAttributes = { ...attributes };
+  delete safeAttributes.langcode;
+  if (safeAttributes.status === undefined && safeAttributes.moderation_state === undefined) {
+    safeAttributes.moderation_state = "draft";
+  }
+  const drafted = await applySafeDraftDefault({
+    backend, entityType, bundle: type, id, attributes: safeAttributes, existingEntity: existing,
   });
-  return redactCanonicalEntity(updated, sec, entityType);
-}
+  assertPublishAllowed(sec, drafted);
 
-// ---------------------------------------------------------------------------
-// Tool definitions
-// ---------------------------------------------------------------------------
+  if (dryRun) {
+    await createTranslationDraft(backend, {
+      entityType, bundle: type, id, langcode: targetLang, attributes: drafted, draftRevision,
+    }, true);
+    return {
+      dryRun: true, operation: "create_translation", entityType, bundle: type, id,
+      langcode: targetLang, attributes: drafted,
+    };
+  }
+
+  const created = await createTranslationDraft(backend, {
+    entityType, bundle: type, id, langcode: targetLang, attributes: drafted, draftRevision,
+  });
+  return redactCanonicalEntity(created, sec, entityType);
+}
 
 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. 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 +193,28 @@ 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 revision (governed write). " +
+      "Adds the target language beside the default language; it does not PATCH langcode on " +
+      "the canonical entity. English live title, body, status, alias, and default revision " +
+      "stay unchanged. An existing translation is a conflict, not an overwrite. Continue the " +
+      "draft with drupal_update_node and langcode. Requires Sentinel's draft-translation " +
+      "endpoint and a translatable bundle. Paragraph field values are not translated on this " +
+      "path. Defaults to node. 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'" },
+        type:       { type: "string", description: "Bundle machine name, e.g. 'basic_page'" },
         id:         { type: "string", description: "Entity UUID" },
-        langcode:   { type: "string", description: "Target language code, e.g. 'de', 'fr', 'pt_br'" },
+        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" },
+        dryRun:     { type: "boolean", description: "Validate without saving" },
       },
     },
   },
 ];
 
-// ---------------------------------------------------------------------------
-// Handler map
-// ---------------------------------------------------------------------------
-
 export const handlers = {
   drupal_list_translations:  listTranslations,
   drupal_create_translation: createTranslation,