drupal-mcp-connector 1.5.0 → 1.6.0

package/CHANGELOG.md

@@ -7,6 +7,94 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.6.0] - 2026-06-29
+
+### Added
+- **Audit command suite — 22 new read-only audit tools across four groups**, expanding
+  the connector from content reporting into link/404 integrity and configuration
+  posture. All follow the existing `drupal_report_*` / `drupal_audit_*` convention
+  (auto-classified read-only), degrade with a `gatedReport`/`gated` payload when a
+  required source is absent, and flag `approximate`/`truncated` when sampling-bounded.
+  - **Links & 404 integrity** (`reports-links.js`): `drupal_report_404_log`,
+    `drupal_report_redirect_health`, `drupal_report_broken_links`,
+    `drupal_report_alias_coverage`, `drupal_report_menu_integrity`,
+    `drupal_report_broken_embeds`.
+  - **Config & site-health** (`reports-config.js`): `drupal_report_config_drift`,
+    `drupal_audit_config_best_practices`, `drupal_report_module_audit`,
+    `drupal_report_permission_audit`, `drupal_report_status_report`,
+    `drupal_report_text_format_audit`, `drupal_report_cache_config`.
+  - **Content quality & governance** (`reports-content.js`):
+    `drupal_report_duplicate_content`, `drupal_report_workflow_bottlenecks`,
+    `drupal_report_translation_coverage`, `drupal_report_scheduled_content`,
+    `drupal_report_readability`, `drupal_report_orphan_pages`,
+    `drupal_report_pii_exposure`, `drupal_report_seo_meta_coverage`.
+  - **Composite** (`audit-composite.js`): `drupal_audit_site_health` — a scored
+    dashboard that runs a configurable battery of the above and rolls them into one
+    letter grade, with each section degrading independently.
+- **`drupal-full-audit` MCP prompt** — walks a client through running the composite
+  audit and turning the dashboard into a prioritized action plan.
+- **Opt-in live link checking.** `drupal_report_broken_links` performs no network
+  egress by default; with `checkLive: true` it verifies links via a bounded,
+  SSRF-guarded checker (`src/lib/link-checker.js`) that refuses
+  loopback/private/link-local/metadata addresses, requires a host allowlist for
+  external hosts, and caps concurrency, timeout, and link count. Configurable per site
+  via an optional `audit` block (`linkCheckAllowedHosts`, `linkCheckConcurrency`,
+  `linkCheckTimeoutMs`, `linkCheckMaxLinks`).
+- **Self-sufficient privileged audits.** Log/config/module/permission/requirements
+  audits read their data through the connector's own **drush bridge** (`watchdog:show`,
+  `config:status`/`config:get`, `pm:list`/`pm:security`, `role:list`,
+  `core:requirements`, and a read-only `sql:query` to enumerate `filter.format.*`), so
+  they work against stock Drupal with **no companion module required**. The
+  config-inspection audits additionally prefer the existing governed config server-tool
+  when a site has `serverTools` configured. Each returns a `gated`/`unavailable` payload
+  (never throws) when no source is configured.
+
+### Changed
+- `sshDrush` and `parseDrush` are now exported from `src/tools/drush.js`, and a
+  `toolResultData` helper is exported from `src/lib/server-tools.js`, so the audit tool
+  groups can reuse the hardened drush bridge and the existing governed config transport.
+
+### Security
+- The drush bridge no longer logs secret-bearing flag values (`--password`/`--token`/
+  `--secret`/`--api-key`) in clear text — they are redacted to `***` in the operational
+  stderr log line (`redactSecretArgs`). Clears a `js/clear-text-logging` finding.
+
+## [1.5.1] - 2026-06-29
+
+### Fixed
+- **Node URL aliases set via the connector now actually persist (DEV-116).** Setting an
+  alias with `drupal_update_node` (`fields.path = { alias, pathauto: 0 }`) returned
+  success but silently reverted, causing nav 404s. Root cause: JSON:API deserialized the
+  `path` field without the existing alias's **`pid`**, so Drupal's `PathItem::postSave`
+  *created a duplicate* `path_alias` (the older one stayed canonical) instead of updating
+  in place. The connector now reads the current alias's `pid` (new
+  `backend.getPathInfo`) and round-trips it, so the alias is **updated in place** — one
+  canonical alias, no duplicate. Verified end-to-end over JSON:API on Drupal 11.
+- **Path-less updates no longer create duplicate aliases.** The DEV-114 "preserve" path
+  re-pinned the current alias *without* its `pid`, hitting the same duplicate bug; it now
+  round-trips the `pid` too.
+- **Honest write responses.** `drupal_create_node` / `drupal_update_node` now **re-read**
+  the node after writing and return the *persisted* `url`, instead of echoing the
+  requested value (which masked the revert).
+
+### Added
+- **Automatic rename redirect.** When an explicit alias change replaces a different
+  existing alias, the connector creates a 301 redirect from the old path to the node
+  (`entity:node/<id>`, alias-independent), so the previous URL keeps resolving. Idempotent
+  — skipped when a redirect for that source already exists or the alias is unchanged.
+- **`backend.getPathInfo(ref)`** on the backend interface — exposes the raw `path` field
+  (`alias` / `pid` / `langcode`) and internal id; default returns nulls (read-only/
+  path-less backends are unaffected). `buildRedirectAttributes()` is now exported from the
+  redirects module for reuse.
+
+### Notes
+- Connector-created nodes still rely on Pathauto to generate their alias when no explicit
+  `path` is given. A **separate, server-side** Pathauto pattern misconfiguration (some
+  `pathauto.pattern.*` had `bundles` stored as a sequential array instead of the
+  associative map the `entity_bundle` condition requires) prevented alias generation for
+  affected bundles (e.g. `industry`, `platform`); that fix lives in the Drupal site
+  (webcms), not in the connector.
+
 ## [1.5.0] - 2026-06-29
 
 ### Added

package/README.md

@@ -51,7 +51,7 @@ See **[docs/architecture.md](docs/architecture.md)** for the backend abstraction
 
 ## Features
 
-### 93 Tools Across 21 Modules
+### 119 Tools Across 26 Modules
 
 | Module | Tools |
 |--------|-------|
@@ -76,6 +76,10 @@ See **[docs/architecture.md](docs/architecture.md)** for the backend abstraction
 | **Redirects** | Create active URL redirects (301/302) + update/repoint existing redirects (Redirect module) |
 | **Search** | Best-effort content search (title match; Search API/Solr-ready) |
 | **Reports (extra)** | Orphaned references, unpublished content, missing-field audits |
+| **Reports — Links & 404** | 404-log → redirect candidates, redirect-table health (chains/loops/duplicates), body-link inventory with opt-in live checking, URL-alias coverage, menu-link integrity, embedded-entity scan |
+| **Reports — Config & Health** | Config drift, best-practice/security config linter, module audit (dev/debug + security updates), permission audit, Drupal status report, text-format safety, cache posture |
+| **Reports — Content Quality** | Duplicate content, workflow bottlenecks, translation coverage, scheduled content, readability (Flesch), orphan pages, PII exposure (masked), structured-meta SEO coverage |
+| **Audit (composite)** | `drupal_audit_site_health` — scored content/links/config dashboard with a roll-up grade |
 | **Config & Governance** | Governed config get/list/set via the server-tool bridge; `drupal_mcp_whoami` tier/capability report |
 
 **Preview writes with `dryRun`.** The node and entity create/update/delete tools accept an optional `dryRun: true` flag that validates the request and returns a preview of exactly what would be written — without committing anything to Drupal.
@@ -89,6 +93,7 @@ Browsable, always-fresh context the client can read without calling a tool:
 ### MCP Prompts
 Workflow templates usable as slash-commands from any MCP client:
 - `drupal-content-audit` — walk through a full site content audit
+- `drupal-full-audit` — run the composite content/links/config audit and turn the scored dashboard into a prioritized action plan
 - `drupal-create-article` — guided article creation with all fields
 - `drupal-seo-fix` — find and fix SEO gaps
 - `drupal-user-cleanup` — identify and handle inactive accounts
@@ -189,7 +194,7 @@ Governance keys off the authenticated account's role and OAuth scopes — not re
 | [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 93 tools |
+| [Tools Reference](docs/tools-reference.md) | Full reference for all 119 tools |
 | [Security Guide](docs/security.md) | Presets, entity access control, field redaction |
 | [Security Hardening](docs/security-hardening.md) | Optional transport, identity, and secrets controls |
 | [Threat Model](docs/threat-model.md) | Trust boundaries, threats & mitigations, residual risks, and the security-pass results |

package/config/config.example.json

@@ -78,6 +78,13 @@
         "port":            22,
         "allowedCommands": ["config:export", "config:status"]
       },
+      "audit": {
+        "_comment": "Optional. Controls drupal_report_broken_links live checking (off unless checkLive:true is passed). linkCheckAllowedHosts gates external hosts; same-origin links are always allowed when checking live.",
+        "linkCheckAllowedHosts": ["www.drupal.org", "wilkesliberty.com"],
+        "linkCheckConcurrency":  5,
+        "linkCheckTimeoutMs":    5000,
+        "linkCheckMaxLinks":     200
+      },
       "security": { "preset": "config-editor" }
     },
 
@@ -108,7 +115,11 @@
   },
 
   "_server_tools": {
-    "_comment": "serverTools.url is the JSON-RPC endpoint of the Drupal-side governed MCP tools (mcp_server_tool_bridge / mcp_sentinel), resolved against baseUrl. Required for drupal_config_get/list/set. Authenticated with the same OAuth bearer."
+    "_comment": "serverTools.url is the JSON-RPC endpoint of the Drupal-side governed MCP tools (mcp_server_tool_bridge / mcp_sentinel), resolved against baseUrl. Required for drupal_config_get/list/set. The config-inspection audits will also use it (governed path) when present, but fall back to the drush bridge, so it is optional for the audits. Authenticated with the same OAuth bearer."
+  },
+
+  "_audit_tools": {
+    "_comment": "The audit tool groups (drupal_report_* links/config/content, drupal_audit_site_health) are read-only. Privileged audits (404 log, config drift/best-practices, module/permission/status) are self-sufficient via the connector's own drush bridge (drushSsh) — no companion module required; the config-inspection audits additionally prefer the governed config server-tool when serverTools is configured. They report 'unavailable' when no source is configured for the site. drupal_report_broken_links does no outbound HTTP unless called with checkLive:true; see each site's optional 'audit' block for live-check limits."
   },
 
   "_mcp_client_registration": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "drupal-mcp-connector",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "A secure, multi-site Model Context Protocol (MCP) connector for Drupal — dual-protocol JSON:API and GraphQL.",
   "type": "module",
   "main": "src/index.js",

package/src/index.js

@@ -68,6 +68,10 @@ import * as structure    from "./tools/structure.js";
 import * as redirects    from "./tools/redirects.js";
 import * as search       from "./tools/search.js";
 import * as reportsExtra from "./tools/reports-extra.js";
+import * as reportsLinks   from "./tools/reports-links.js";
+import * as reportsConfig  from "./tools/reports-config.js";
+import * as reportsContent from "./tools/reports-content.js";
+import * as auditComposite from "./tools/audit-composite.js";
 import * as config       from "./tools/config.js";
 
 // ---------------------------------------------------------------------------
@@ -75,7 +79,8 @@ import * as config       from "./tools/config.js";
 // ---------------------------------------------------------------------------
 
 const allModules = [nodes, taxonomy, users, media, graphql, site, entities, reports, drush,
-  revisions, moderation, scheduler, fields, references, bulk, translations, paragraphs, structure, redirects, search, reportsExtra, config];
+  revisions, moderation, scheduler, fields, references, bulk, translations, paragraphs, structure, redirects, search, reportsExtra,
+  reportsLinks, reportsConfig, reportsContent, auditComposite, config];
 
 // Flatten every module's tool definitions into one ListTools payload, and merge
 // their handler maps into a single closed dispatch table keyed by tool name.
@@ -247,6 +252,14 @@ const PROMPTS = [
     description: "Identify inactive, never-logged-in, or overly permissioned user accounts and take action.",
     arguments:   [{ name: "site", description: "Target site", required: false }],
   },
+  {
+    name:        "drupal-full-audit",
+    description: "Run a full site-health audit — content, link/404 integrity, and configuration posture — and turn the scored dashboard into a prioritized action plan.",
+    arguments:   [
+      { name: "site", description: "Named site to audit (omit for default)", required: false },
+      { name: "type", description: "Primary content type to audit",          required: false },
+    ],
+  },
 ];
 
 /**
@@ -310,6 +323,19 @@ function getPromptMessages(name, args) {
         "6. Ask for approval before making any changes."
       }},
     ],
+    "drupal-full-audit": [
+      { role: "user", content: { type: "text", text:
+        `Please run a full site-health audit ${site} and turn it into a prioritized action plan.\n\n` +
+        `1. Call drupal_audit_site_health (type: "${type}") for the scored dashboard and overall grade.\n` +
+        "2. For any section reporting high-severity findings, drill in with the matching tool for detail:\n" +
+        "   - links/404: drupal_report_404_log, drupal_report_redirect_health, drupal_report_broken_links (checkLive only with approval).\n" +
+        "   - config: drupal_audit_config_best_practices, drupal_report_module_audit, drupal_report_permission_audit.\n" +
+        "   - content: drupal_report_pii_exposure, drupal_report_duplicate_content, drupal_report_readability.\n" +
+        "3. For sections reported 'unavailable', note what (server-tool bridge or drush) would enable them — do not treat unavailable as 'passing'.\n" +
+        "4. Synthesize a prioritized plan: (a) high-severity/security fixes first, (b) content-quality improvements, (c) process recommendations.\n" +
+        "5. Present counts, severity, and specific node/config references; propose redirects for the top 404s. Ask before making any changes."
+      }},
+    ],
   };
 
   return new Map(Object.entries(prompts)).get(name) ?? [{ role: "user", content: { type: "text", text: `Run the ${name} workflow ${site}.` } }];

package/src/lib/audit-sources.js

@@ -0,0 +1,66 @@
+/**
+ * Privileged-source resolution for the audit tool groups.
+ *
+ * Single responsibility: run an audit that needs privileged log/config/module
+ * data through the best available source, in priority order — an optional
+ * governed server-tool first (when a callback is supplied), the connector's own
+ * drush SSH bridge otherwise — and report a clean "unavailable" outcome (never
+ * throw) when no source is configured or all fail. The drush bridge makes the
+ * audits self-sufficient against stock Drupal; no companion module is required.
+ */
+
+/**
+ * Whether the governed server-tool bridge is configured for a site.
+ * @param {object} site Resolved site config.
+ * @returns {boolean}
+ */
+export function serverToolsConfigured(site) {
+  return Boolean(site?.serverTools?.url);
+}
+
+/**
+ * Whether the drush SSH bridge is configured for a site.
+ * @param {object} site Resolved site config.
+ * @returns {boolean}
+ */
+export function drushConfigured(site) {
+  return Boolean(site?.drushSsh);
+}
+
+/**
+ * Run a privileged audit through the first source that succeeds.
+ *
+ * Tries the optional governed server-tool (when a `serverTool` callback is given
+ * and `serverTools` is configured), then the connector's own drush bridge (when a
+ * `drush` callback is given and `drushSsh` is configured). Either callback may be
+ * omitted when that source can't serve the audit. Failures are accumulated, not
+ * thrown, so the caller can surface them in a gated payload.
+ *
+ * @param {object} site Resolved site config.
+ * @param {object} sources
+ * @param {(() => Promise<*>)} [sources.serverTool] Server-tool attempt.
+ * @param {(() => Promise<*>)} [sources.drush] Drush attempt.
+ * @returns {Promise<{source: ("server-tool"|"drush"|null), data?: *, attempts: string[]}>}
+ *   On success, `source` names the winning path and `data` is its result. On
+ *   failure, `source` is null and `attempts` explains why each path was skipped
+ *   or failed.
+ */
+export async function runPrivileged(site, { serverTool, drush } = {}) {
+  const attempts = [];
+
+  if (serverTool && serverToolsConfigured(site)) {
+    try { return { source: "server-tool", data: await serverTool(), attempts }; }
+    catch (err) { attempts.push(`server-tool: ${err?.message || err}`); }
+  } else if (serverTool) {
+    attempts.push("server-tool: serverTools.url not configured for this site");
+  }
+
+  if (drush && drushConfigured(site)) {
+    try { return { source: "drush", data: await drush(), attempts }; }
+    catch (err) { attempts.push(`drush: ${err?.message || err}`); }
+  } else if (drush) {
+    attempts.push("drush: drushSsh not configured for this site");
+  }
+
+  return { source: null, attempts };
+}

package/src/lib/audit-support.js

@@ -0,0 +1,170 @@
+/**
+ * Shared helpers for the audit tool groups — HTML link/embed extraction and
+ * link classification, backend-neutral.
+ *
+ * Single responsibility: turn a node's rendered body HTML into structured link
+ * and embed records, and classify a URL as internal/external/other relative to
+ * a site's base URL. The link (`reports-links.js`) and content
+ * (`reports-content.js`) audits share this one parser so link handling stays
+ * consistent across the suite.
+ *
+ * Detection is regex-based on the stored body markup — a heuristic pass, not a
+ * full DOM parse — matching the existing seo/accessibility audits in reports.js.
+ */
+
+import { fieldValue } from "./reports-support.js";
+
+/**
+ * Read a node's body HTML from a canonical entity. Mirrors the body-extraction
+ * idiom in reports.js (the body field may be a `{value}` object or a scalar).
+ * @param {object} entity Canonical entity.
+ * @param {string[]} [candidates] Field names to try, in order.
+ * @returns {string} The body HTML, or "" when absent.
+ */
+export function bodyHtml(entity, candidates = ["body"]) {
+  const raw = fieldValue(entity, candidates);
+  const value = raw && typeof raw === "object" ? raw.value : raw;
+  return typeof value === "string" ? value : "";
+}
+
+/**
+ * Extract all `href` values from `<a>` tags in an HTML string.
+ * @param {string} html Body markup.
+ * @returns {string[]} Raw href values in document order (may include dups).
+ */
+export function extractAnchors(html) {
+  return matchAttr(html, /<a\b[^>]*?\bhref\s*=\s*["']([^"']+)["']/gi);
+}
+
+/**
+ * Extract all `src` values from `<img>` tags in an HTML string.
+ * @param {string} html Body markup.
+ * @returns {string[]} Raw src values in document order (may include dups).
+ */
+export function extractImages(html) {
+  return matchAttr(html, /<img\b[^>]*?\bsrc\s*=\s*["']([^"']+)["']/gi);
+}
+
+/**
+ * Extract entity embeds from body markup. Covers the CKEditor media/entity embed
+ * shapes Drupal emits — `<drupal-media>`, `<drupal-entity>`, and any element
+ * carrying `data-entity-type` + `data-entity-uuid` (entity_embed). Each embed is
+ * returned as a `{ entityType, uuid }` ref so callers can probe the target.
+ * @param {string} html Body markup.
+ * @returns {Array<{entityType: ?string, uuid: string}>} De-duped embed refs.
+ */
+export function extractEmbeds(html) {
+  const out = [];
+  const seen = new Set();
+  // Match any tag that carries a data-entity-uuid attribute; pull the optional
+  // sibling data-entity-type from the same tag.
+  const tagRe = /<([a-z-]+)\b([^>]*\bdata-entity-uuid\s*=\s*["'][^"']+["'][^>]*)>/gi;
+  for (const m of String(html || "").matchAll(tagRe)) {
+    const attrs = m[2];
+    const uuid = readAttr(attrs, /\bdata-entity-uuid\s*=\s*["']([^"']+)["']/i);
+    if (!uuid || seen.has(uuid)) continue;
+    seen.add(uuid);
+    out.push({ entityType: readAttr(attrs, /\bdata-entity-type\s*=\s*["']([^"']+)["']/i), uuid });
+  }
+  return out;
+}
+
+/**
+ * Classify a URL relative to a site base URL.
+ *
+ * @param {string} url Raw href/src value.
+ * @param {string} baseUrl The site's configured base URL (origin).
+ * @returns {{kind: "internal"|"external"|"fragment"|"mailto"|"tel"|"other",
+ *   url: string, path: ?string, host: ?string}} Classification. `path` is set
+ *   for internal links (origin-relative, no query/fragment); `host` for external.
+ */
+export function classifyLink(url, baseUrl) {
+  const raw = (url || "").trim();
+  if (!raw) return { kind: "other", url: raw, path: null, host: null };
+  if (raw.startsWith("#")) return { kind: "fragment", url: raw, path: null, host: null };
+
+  const lower = raw.toLowerCase();
+  if (lower.startsWith("mailto:")) return { kind: "mailto", url: raw, path: null, host: null };
+  if (lower.startsWith("tel:")) return { kind: "tel", url: raw, path: null, host: null };
+  if (/^(javascript|data):/i.test(lower)) return { kind: "other", url: raw, path: null, host: null };
+
+  const baseHost = hostOf(baseUrl);
+
+  // Root- or path-relative internal links.
+  if (raw.startsWith("/") && !raw.startsWith("//")) {
+    return { kind: "internal", url: raw, path: normalizePath(raw), host: baseHost };
+  }
+
+  // Protocol-relative or absolute URLs.
+  let parsed;
+  try {
+    parsed = new URL(raw, baseUrl || undefined);
+  } catch {
+    return { kind: "other", url: raw, path: null, host: null };
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    return { kind: "other", url: raw, path: null, host: null };
+  }
+  if (baseHost && parsed.host.toLowerCase() === baseHost.toLowerCase()) {
+    return { kind: "internal", url: raw, path: normalizePath(parsed.pathname), host: parsed.host };
+  }
+  return { kind: "external", url: raw, path: null, host: parsed.host };
+}
+
+/**
+ * Normalize an internal path for comparison: decode, strip query/fragment, drop
+ * a trailing slash (except root), and ensure a leading slash.
+ * @param {string} path A pathname or root-relative URL.
+ * @returns {string} Normalized path beginning with "/".
+ */
+export function normalizePath(path) {
+  let p = String(path || "/");
+  const fragIdx = p.indexOf("#");
+  if (fragIdx !== -1) p = p.slice(0, fragIdx);
+  const queryIdx = p.indexOf("?");
+  if (queryIdx !== -1) p = p.slice(0, queryIdx);
+  try { p = decodeURI(p); } catch { /* leave as-is on malformed escapes */ }
+  if (!p.startsWith("/")) p = `/${p}`;
+  if (p.length > 1 && p.endsWith("/")) p = p.replace(/\/+$/, "");
+  return p || "/";
+}
+
+/**
+ * Pull the host (`host:port`) out of a base URL string, tolerating a bare host.
+ * @param {string} baseUrl A configured site base URL.
+ * @returns {?string} The host, or null when unparseable/absent.
+ */
+export function hostOf(baseUrl) {
+  if (!baseUrl) return null;
+  try { return new URL(baseUrl).host; }
+  catch {
+    try { return new URL(`https://${baseUrl}`).host; }
+    catch { return null; }
+  }
+}
+
+/**
+ * Run a global attribute-capturing regex over HTML and return capture group 1
+ * for every match.
+ * @param {string} html Source markup.
+ * @param {RegExp} re Global regex whose first group is the attribute value.
+ * @returns {string[]} Captured values in document order.
+ */
+function matchAttr(html, re) {
+  const out = [];
+  if (!html) return out;
+  for (const m of String(html).matchAll(re)) out.push(m[1]);
+  return out;
+}
+
+/**
+ * Read a single attribute value out of a tag's attribute string using a literal
+ * capturing regex.
+ * @param {string} attrs The raw attribute text inside a tag.
+ * @param {RegExp} re A regex whose first group captures the attribute value.
+ * @returns {?string} The value, or null when the attribute is absent.
+ */
+function readAttr(attrs, re) {
+  const m = String(attrs || "").match(re);
+  return m ? m[1] : null;
+}

package/src/lib/backends/backend-interface.js

@@ -71,6 +71,16 @@ export class Backend {
    */
   async getEntity(_ref) { return notImplemented("getEntity"); }
 
+  /**
+   * Read the raw `path` field (alias/pid/langcode) and internal id of an entity,
+   * for callers that must round-trip the alias `pid` on an in-place update (the
+   * canonical entity only exposes `path.alias` as `url`). Optional capability:
+   * the default returns nulls so read-only/path-less backends are safe. See DEV-116.
+   * @param {{entityType: string, bundle: string, id: string}} _ref
+   * @returns {Promise<{alias: ?string, pid: ?(number|string), langcode: ?string, drupalId: ?(number|string)}>}
+   */
+  async getPathInfo(_ref) { return { alias: null, pid: null, langcode: null, drupalId: null }; }
+
   /**
    * Create an entity.
    * @param {{entityType: string, bundle: string, attributes?: object, relationships?: object}} _input

package/src/lib/backends/jsonapi.js

@@ -253,6 +253,29 @@ export class JsonApiBackend extends Backend {
     return data?.data ? this.toCanonical(data.data) : null;
   }
 
+  /**
+   * Read the raw `path` field (alias + pid + langcode) and internal id of an
+   * entity. The canonical entity only surfaces `path.alias` as `url`, but a
+   * correct in-place alias *update* must round-trip the existing alias's `pid`
+   * (Drupal `PathItem::postSave` creates a duplicate alias when `pid` is absent)
+   * — so this method exposes it. Returns nulls for entities/backends without a
+   * path field. See DEV-116.
+   * @param {{entityType: string, bundle: string, id: string}} ref
+   * @returns {Promise<{alias: ?string, pid: ?(number|string), langcode: ?string, drupalId: ?(number|string)}>}
+   */
+  async getPathInfo({ entityType, bundle, id }) {
+    validateUuid(id);
+    const data = await drupalFetch(this.site, `${this.resourcePath(entityType, bundle)}/${encodeURIComponent(id)}`);
+    const attrs = data?.data?.attributes ?? {};
+    const path = attrs.path ?? null;
+    return {
+      alias: path?.alias ?? null,
+      pid: path?.pid ?? null,
+      langcode: path?.langcode ?? attrs.langcode ?? null,
+      drupalId: attrs.drupal_internal__nid ?? attrs.drupal_internal__id ?? null,
+    };
+  }
+
   /**
    * Issue a JSON:API write, transparently retrying once without the `status`
    * attribute if the target bundle is under a content_moderation workflow.