drupal-mcp-connector 2.25.0 → 3.0.0

package/src/lib/operations.js

@@ -4,7 +4,7 @@
  * A tool's operation (read / write / delete / graphql) is inferred from its name
  * prefix rather than trusting per-tool metadata, so a new tool that follows the
  * naming convention is classified automatically. This single definition is shared
- * by the security middleware (src/index.js), the per-tool MCP prompts
+ * by the security middleware (src/lib/dispatch.js), the per-tool MCP prompts
  * (src/lib/tool-prompts.js), and the slash-command generator
  * (scripts/generate-commands.js) so authorization gating and the "destructive"
  * warnings surfaced to users can never drift apart.

package/src/lib/patch-preflight.js

@@ -30,6 +30,8 @@ import {
   readNodeDraftInventory,
   assertInventoryDraftLanguage,
   inferDefaultDraftLangcode,
+  isCarriedPublishedLanguage,
+  carriedPublishedLanguageError,
   MIN_SENTINEL_DEFAULT_LANGUAGE_DRAFT_VERSION,
 } from "./sentinel-draft.js";
 import { PREFLIGHT_NONE, PREFLIGHT_CORE_GUARD, PREFLIGHT_SENTINEL_DRAFT } from "./dry-run-checks.js";
@@ -102,26 +104,24 @@ export class WorkingCopyStaleError extends Error {
 /**
  * Sentinel's save-time stale-default check (McpWritePreconditions) is not
  * exercised by the id-mismatch PATCH probe — that probe fails before
- * entity validation / presave. A published node with no distinct working
- * copy and a changed timestamp later than its own revision_timestamp is
- * the readable fingerprint (`possiblyPatchBlocked`). dryRun and the real
- * write must refuse the same way; reloading and retrying does not help.
- * Do not bypass the draft or publish gate. See connector #273.
+ * entity validation / presave. #273 used the `changed` >
+ * `revision_timestamp` fingerprint (`possiblyPatchBlocked`) as a local
+ * stand-in, but a gap on the default revision itself is not proof of a
+ * hidden row (#405). list_revisions still reports the warning. A draft
+ * write proceeds to the core probe / Sentinel; this message is used only
+ * when Sentinel actually refuses. Do not bypass the draft or publish gate.
  */
 export const STALE_COPY_MESSAGE =
   "This entity cannot be updated: MCP Sentinel refused a stale default-revision " +
-  "write (the content changed after this copy was loaded). dryRun and the real " +
-  "write share this check. rel:latest-version and rel:working-copy report the " +
-  "same vid, but the default revision's changed timestamp is later than its " +
-  "revision_timestamp (possiblyPatchBlocked). Reloading and retrying the same " +
-  "canonical PATCH will not help. Do not bypass the draft or publish gate. " +
-  "See connector #273 / #201.";
+  "write (the content changed after this copy was loaded). Reloading and " +
+  "retrying the same canonical PATCH will not help. Do not bypass the draft " +
+  "or publish gate. See connector #273 / #201 / #405.";
 
 const STALE_COPY_RE = /changed after this copy was loaded/i;
 
 /**
- * Thrown when a canonical write (or its dryRun) would hit Sentinel's
- * stale-default-revision check (#273).
+ * Thrown when Sentinel's save-time stale-default-revision check refuses
+ * a write (#273). Not thrown from the local fingerprint alone (#405).
  */
 export class StaleCopyError extends Error {
   /**
@@ -417,28 +417,28 @@ export async function prepareGuardedPatch(backend, {
     : { resourceVersion: undefined, workingCopy: null, liveVid: null, workingVid: null };
   // Set only after a check has run and passed; a refusal throws first.
   target.preflight = PREFLIGHT_NONE;
-  if (needsPreflight && !target.resourceVersion) {
-    // Canonical path (no distinct working copy). The id-mismatch probe never
-    // reaches Sentinel's save-time stale-default check; refuse here when the
-    // possiblyPatchBlocked fingerprint is already readable (#273).
-    let fingerprint = existing;
-    const fields = fingerprint?.fields && typeof fingerprint.fields === "object" ? fingerprint.fields : {};
-    const hasTimestamps = Boolean(
-      fingerprint?.changed && (fingerprint.revisionTimestamp || fields.revision_timestamp),
-    );
-    if (!hasTimestamps && typeof backend?.getEntity === "function") {
-      const latest = await backend.getEntity({
-        entityType, bundle, id, resourceVersion: "rel:latest-version",
-      }).catch(() => null);
-      if (latest) fingerprint = latest;
-    }
-    if (changedAheadOfRevision(fingerprint)) {
-      throw new StaleCopyError();
-    }
-  }
+  // Canonical path (no distinct working copy): do not treat
+  // possiblyPatchBlocked as local proof of a hidden revision (#405).
+  // A changed/revision_timestamp gap on the default revision is a
+  // warning on list_revisions. Proceed to Sentinel / the core probe;
+  // rewrite an actual Sentinel stale-copy refusal below.
   // An inventory already in hand names the default-language draft for free.
+  // When langcode is set and the working-copy alias skipped discovery, load
+  // inventory so a carried published language is refused locally (#400).
+  if (langcode && !target.inventory) {
+    const inventory = await readNodeDraftInventory(backend, { entityType, bundle, id });
+    if (inventory) target.inventory = inventory;
+  }
   let inferredLangcode = langcode ? undefined : inferDefaultDraftLangcode(target.inventory);
   if (!langcode && !inferredLangcode && target.inventory) {
+    const defaultLang = typeof target.inventory.defaultLangcode === "string"
+      ? target.inventory.defaultLangcode
+      : undefined;
+    const carried = (target.inventory.working?.translations ?? [])
+      .find((row) => defaultLang && row?.langcode === defaultLang);
+    if (isCarriedPublishedLanguage(carried)) {
+      throw carriedPublishedLanguageError(defaultLang);
+    }
     assertInventoryDraftLanguage(target.inventory, langcode);
   }
   if (langcode) {

package/src/lib/principal.js

@@ -39,15 +39,18 @@ export const DIAGNOSTIC_TOOLS = new Set([
   "drupal_governance_status",
 ]);
 
-const CONFIG_TOOLS = new Set([
+const CONFIG_READ_TOOLS = new Set([
   "drupal_config_get",
   "drupal_config_list",
-  "drupal_config_set",
   "drupal_drush_config_export",
-  "drupal_drush_config_import",
   "drupal_drush_config_status",
 ]);
 
+const CONFIG_WRITE_TOOLS = new Set([
+  "drupal_config_set",
+  "drupal_drush_config_import",
+]);
+
 /** inferOperation() leaves these as "read"; they self-gate in-handler. */
 const WRITE_BY_NAME = new Set([
   "drupal_entity_create",
@@ -98,7 +101,8 @@ export function getRequestIdentity() {
 export function requiredScopeForTool(toolName) {
   if (DIAGNOSTIC_TOOLS.has(toolName)) return null;
   if (toolName === "drupal_drush_sql_query") return "mcp_admin";
-  if (CONFIG_TOOLS.has(toolName)) return "mcp_config";
+  if (CONFIG_WRITE_TOOLS.has(toolName)) return "mcp_config";
+  if (CONFIG_READ_TOOLS.has(toolName)) return "mcp_config_read";
   if (WRITE_BY_NAME.has(toolName)) return "mcp_write";
   const op = inferOperation(toolName);
   if (op === "write" || op === "delete") return "mcp_write";
@@ -112,7 +116,11 @@ export function requiredScopeForTool(toolName) {
  */
 export function principalHasScope(identity, scope) {
   if (!scope) return true;
-  return (identity?.scopes ?? []).includes(scope);
+  const scopes = identity?.scopes ?? [];
+  if (scopes.includes(scope)) return true;
+  // Write-capable mcp_config includes the read-only auditor scope (#397).
+  if (scope === "mcp_config_read" && scopes.includes("mcp_config")) return true;
+  return false;
 }
 
 function grantNameList(values) {

package/src/lib/reports-support.js

@@ -2,6 +2,8 @@
  * Shared helpers for the reporting tools — backend-neutral.
  */
 
+import { assertReadAllowed } from "./security.js";
+
 /** Canonical base property names (read directly off the entity, not from `fields`). */
 const BASE_KEYS = new Set(["id", "title", "status", "langcode", "created", "changed", "url"]);
 
@@ -148,3 +150,69 @@ export function requestedFieldNames(fields) {
   const list = typeof fields === "string" ? [fields] : (Array.isArray(fields) ? fields : []);
   return [...new Set(list.filter((f) => typeof f === "string" && f.trim()).map((f) => f.trim()))];
 }
+
+/**
+ * Return the content type a bundle-scoped tool reads, or fail clearly.
+ * Node tools used to default to `article`, which 404s on a site without that
+ * bundle (#403). There is no bundle every site has, so the caller names one.
+ * @param {?string} type Content type machine name from the caller.
+ * @param {string} tool Tool name, for the message.
+ * @param {string} [argName] Argument name, for the message.
+ * @returns {string} The content type.
+ * @throws {Error} When no type was given.
+ */
+export function requireContentType(type, tool, argName = "type") {
+  if (typeof type === "string" && type.trim()) return type;
+  throw new Error(
+    `${tool} reads one content type: pass ${argName} (a node bundle machine name). ` +
+    "Call drupal_list_content_types to see the bundles on this site.",
+  );
+}
+
+/**
+ * Node bundles a tool may read when the caller named none. Bundles that
+ * connector policy denies are left out; they are not the caller's to see.
+ * @param {{listContentTypes: Function}} backend Resolved backend.
+ * @param {object} sec Resolved security config.
+ * @returns {Promise<string[]>} Bundle machine names.
+ */
+export async function readableNodeBundles(backend, sec) {
+  const types = await backend.listContentTypes();
+  return types.map((ct) => ct?.id).filter((id) => {
+    if (!id) return false;
+    try {
+      assertReadAllowed(sec, "node", id);
+      return true;
+    } catch {
+      return false;
+    }
+  });
+}
+
+/**
+ * List nodes from several bundles with one descriptor, merged newest first by
+ * `sortField`. A bundle that fails to load fails the whole call with the
+ * bundle named, so a partial list is never returned as complete (#403).
+ * @param {{listEntities: Function}} backend Resolved backend.
+ * @param {string[]} bundles Node bundles to read.
+ * @param {object} descriptor listEntities descriptor without `bundle`.
+ * @param {number} limit Max nodes returned.
+ * @param {string} [sortField] Canonical date property to merge by.
+ * @returns {Promise<object[]>} Canonical entities.
+ * @throws {Error} When any bundle fails to load.
+ */
+export async function listNodesAcrossBundles(backend, bundles, descriptor, limit, sortField = "changed") {
+  const found = [];
+  for (const bundle of bundles) {
+    let res;
+    try {
+      res = await backend.listEntities({ ...descriptor, entityType: "node", bundle, page: { limit } });
+    } catch (err) {
+      throw new Error(`Could not read content type '${bundle}': ${err?.message || err}. Pass type to read one content type.`, { cause: err });
+    }
+    found.push(...(res.entities ?? []));
+  }
+  const key = (e) => String(new Map(Object.entries(e ?? {})).get(sortField) ?? "");
+  found.sort((x, y) => key(y).localeCompare(key(x)));
+  return found.slice(0, limit);
+}

package/src/lib/security.js

@@ -512,22 +512,53 @@ function isGovernedSetup(site) {
 }
 
 /**
- * Gate the config tools (get/list/set) on the dedicated `mcp_config` OAuth
- * scope, which the governed server requires for every config_* tool. When OAuth
- * scopes are configured but `mcp_config` is absent, fail fast with a clear
- * message instead of dispatching a call the server will deny — keeping the
- * connector's behaviour and its drupal_mcp_whoami report consistent with what
- * the token can actually exercise.
+ * Whether the site's token can read config: `mcp_config` (read+write) or
+ * the read-only `mcp_config_read` auditor scope (#397).
+ * @param {object} site Resolved site config.
+ * @returns {boolean}
+ */
+export function hasConfigReadScope(site) {
+  return hasScope(site, "mcp_config") || hasScope(site, "mcp_config_read");
+}
+
+/**
+ * Inbound / binding scope to send for a config *read* (get/list/reports/codegen).
+ * Prefer `mcp_config` so existing write-capable bindings keep matching; a
+ * read-only token sends `mcp_config_read`.
+ * @param {object} site Resolved site config.
+ * @returns {string}
+ */
+export function configReadBindingScope(site) {
+  return hasScope(site, "mcp_config") ? "mcp_config" : "mcp_config_read";
+}
+
+/**
+ * Gate the config tools on OAuth scope. Writes require `mcp_config`.
+ * Reads accept `mcp_config` or the read-only `mcp_config_read` (#397).
+ * When OAuth scopes are configured and neither is present, fail fast rather
+ * than dispatching a call the server will deny.
  * @param {object} site Resolved site config.
  * @param {string} operationLabel Label used in the error message.
+ * @param {{write?: boolean}} [opts] `write: true` requires `mcp_config`.
  * @returns {void}
- * @throws {SecurityError} if scopes are configured and `mcp_config` is missing.
+ * @throws {SecurityError} if the required config scope is missing.
  */
-export function assertConfigScope(site, operationLabel) {
-  if (!hasScope(site, "mcp_config")) {
+export function assertConfigScope(site, operationLabel, { write = false } = {}) {
+  if (write) {
+    if (!hasScope(site, "mcp_config")) {
+      throw new SecurityError(
+        "Config writes require the 'mcp_config' OAuth scope (config-editor / " +
+        "Developer tier); this token does not carry it. " +
+        `Operation blocked: ${operationLabel}.`
+      );
+    }
+    return;
+  }
+  if (!hasConfigReadScope(site)) {
     throw new SecurityError(
-      "Config tools require the 'mcp_config' OAuth scope (config-editor / " +
-      "Developer tier); this token does not carry it. " +
+      "Config reads require the 'mcp_config' or 'mcp_config_read' OAuth scope " +
+      "(config-editor / Developer tier, or a read-only auditor token); " +
+      "this token does not carry either. " +
       `Operation blocked: ${operationLabel}.`
     );
   }
@@ -922,41 +953,8 @@ export function assertDeleteAllowed(secConfig, entityType, bundle, id) {
 // Field redaction
 // ---------------------------------------------------------------------------
 
-/**
- * Redact sensitive fields from a JSON:API resource object (or array of them),
- * replacing their `attributes` values with "[REDACTED]".
- * @param {?(object|object[])} resource JSON:API resource(s) to redact.
- * @param {object} secConfig Resolved security config (supplies the field lists).
- * @param {string} entityType Entity type, used to pick per-type redacted fields.
- * @returns {?(object|object[])} New resource object(s); originals are not mutated.
- */
-export function redactResource(resource, secConfig, entityType) {
-  if (!resource) return resource;
-
-  // Collect fields to redact for this entity type
-  const entityRules = new Map(Object.entries(secConfig.entityRules)).get(entityType) ?? {};
-  const fieldsToRedact = new Set([
-    ...(secConfig.globalRedactedFields ?? []),
-    ...(entityRules.redactedFields      ?? []),
-  ]);
-
-  if (fieldsToRedact.size === 0) return resource;
-
-  function redactAttrs(obj) {
-    if (!obj?.attributes) return obj;
-    const attrs = Object.fromEntries(
-      Object.entries(obj.attributes).map(([k, v]) => [k, fieldsToRedact.has(k) ? "[REDACTED]" : v])
-    );
-    return { ...obj, attributes: attrs };
-  }
-
-  if (Array.isArray(resource)) return resource.map(redactAttrs);
-  return redactAttrs(resource);
-}
-
 /**
  * Redact sensitive fields from a CANONICAL entity (base props + `fields`).
- * Mirrors redactResource but for the API-neutral canonical shape.
  * @param {?object} entity Canonical entity to redact.
  * @param {object} secConfig Resolved security config (supplies the field lists).
  * @param {string} entityType Entity type, used to pick per-type redacted fields.

package/src/lib/sentinel-draft.js

@@ -419,7 +419,7 @@ export function explainExistingTranslation(error, { revise = false, inventory =
       { cause: current },
     );
   }
-  if (workingDistinct && workingRow && workingRow.status === false) {
+  if (workingDistinct && workingRow && isUnpublishedWorkingDraft(workingRow)) {
     return new Error(
       "An unpublished working translation for this language already exists. " +
       `Continue it with ${continuer} and langcode. ` +
@@ -427,6 +427,9 @@ export function explainExistingTranslation(error, { revise = false, inventory =
       { cause: current },
     );
   }
+  if (workingDistinct && workingRow && isCarriedPublishedLanguage(workingRow)) {
+    return carriedPublishedLanguageError(langcode);
+  }
   return current;
 }
 
@@ -497,6 +500,54 @@ export async function readNodeDraftInventory(backend, ref) {
   return inventory;
 }
 
+/**
+ * Whether an inventory row is an unpublished working draft (#400).
+ *
+ * Decide from `moderation_state` when present: `status: false` alone is not
+ * a draft. Sentinel copies the live published moderation record onto a
+ * carried default language (drupal.org #3626610), so that row is unpublished
+ * in status and still `published` in workflow.
+ * @param {?object} row Inventory translation row.
+ * @returns {boolean}
+ */
+export function isUnpublishedWorkingDraft(row) {
+  if (!row || typeof row !== "object") return false;
+  const state = typeof row.moderation_state === "string" ? row.moderation_state.trim().toLowerCase() : "";
+  if (state) return state !== "published";
+  return row.status === false;
+}
+
+/**
+ * Whether a working-copy row is a carried published language, not a draft.
+ * `status: false` + `moderation_state: published` — Sentinel copied live
+ * workflow onto the language. Neither continue nor revise can open a draft
+ * of it while another translation draft exists (drupal.org #3626919 / #400).
+ * @param {?object} row Inventory translation row.
+ * @returns {boolean}
+ */
+export function isCarriedPublishedLanguage(row) {
+  if (!row || typeof row !== "object") return false;
+  const state = typeof row.moderation_state === "string" ? row.moderation_state.trim().toLowerCase() : "";
+  return row.status === false && state === "published";
+}
+
+/**
+ * Refusal when neither update_node nor revise can draft a carried language.
+ * @param {string} [langcode]
+ * @returns {Error}
+ */
+export function carriedPublishedLanguageError(langcode) {
+  const named = langcode ? ` (${langcode})` : "";
+  return new Error(
+    `This language${named} is on the working copy with published moderation and unpublished status ` +
+    "(Sentinel copied the live moderation record; it is not a working draft). " +
+    "Neither drupal_update_node nor drupal_create_translation revise can open a draft of it " +
+    "while another translation draft exists (drupal.org #3626919). " +
+    "Publish or discard the translation draft first, or edit in the Drupal UI. " +
+    "See connector #400."
+  );
+}
+
 /**
  * The language to name when continuing a multilingual working revision
  * without an explicit langcode (#379).
@@ -505,6 +556,8 @@ export async function readNodeDraftInventory(backend, ref) {
  * more than one language, even for the default language. Infer it only when
  * the default language is the unpublished draft in that revision; a
  * translation-only draft over published default copy stays explicit.
+ * A carried published language (`status: false` + published moderation) is
+ * not a draft (#400).
  * @param {object|null|undefined} inventory Sentinel translation inventory.
  * @returns {string|undefined}
  */
@@ -515,7 +568,7 @@ export function inferDefaultDraftLangcode(inventory) {
   const defaultLang = typeof inventory.defaultLangcode === "string" ? inventory.defaultLangcode : fallback;
   if (typeof defaultLang !== "string" || defaultLang === "") return undefined;
   const row = rows.find((item) => item?.langcode === defaultLang);
-  return row && row.status === false ? defaultLang : undefined;
+  return row && isUnpublishedWorkingDraft(row) ? defaultLang : undefined;
 }
 
 /**
@@ -530,13 +583,16 @@ export function assertInventoryDraftLanguage(inventory, langcode) {
     throw new Error("This working revision contains translations. Pass an explicit langcode for an existing unpublished language; no draft was created.");
   }
   const row = langcode ? rows.find((item) => item.langcode === langcode) : rows[0];
+  if (row && isCarriedPublishedLanguage(row)) {
+    throw carriedPublishedLanguageError(langcode || row.langcode);
+  }
   if (row && row.status === true && langcode && langcode !== inventory.defaultLangcode && row.default !== true) {
     throw new Error(
       "This language is still published on the working copy, so it cannot be continued. " +
       "Open a draft of it with drupal_create_translation and revise: true. Published languages and other drafts were left unchanged.",
     );
   }
-  if (!row || row.status !== false) {
+  if (!row || !isUnpublishedWorkingDraft(row)) {
     throw new Error("The requested language is not an existing unpublished working draft. Published languages and other drafts were left unchanged.");
   }
 }

package/src/lib/server-tools.js

@@ -444,7 +444,7 @@ export async function listServerTools(site, cursor) {
 }
 
 /** Fetch one page of Drupal `McpPromptConfig` prompts. */
-export async function listServerPrompts(site, cursor) {
+async function listServerPrompts(site, cursor) {
   return requestServerTool(site, "prompts/list", cursor === undefined ? {} : { cursor }, {
     maxBytes: SERVER_TOOL_MAX_BYTES, preserveErrors: true,
   });
@@ -454,7 +454,7 @@ export async function listServerPrompts(site, cursor) {
  * Fetch one Drupal prompt body. Pass no arguments so `{{token}}` placeholders
  * stay intact for the connector's workflow renderer.
  */
-export async function getServerPrompt(site, name) {
+async function getServerPrompt(site, name) {
   return requestServerTool(site, "prompts/get", { name, arguments: {} }, {
     maxBytes: SERVER_TOOL_MAX_BYTES, preserveErrors: true,
   });
@@ -466,7 +466,7 @@ export async function getServerPrompt(site, name) {
  * @param {Function} [list] Catalog page reader.
  * @returns {Promise<object[]>} Prompt descriptors.
  */
-export async function advertisedServerPrompts(site, list = listServerPrompts) {
+async function advertisedServerPrompts(site, list = listServerPrompts) {
   const prompts = [];
   const seen = new Set();
   let cursor;

package/src/lib/transports.js

@@ -0,0 +1,153 @@
+/**
+ * Honest MCP transport presets (DEV-763).
+ *
+ * Wizard `--transport` stays `stdio` | `https`. These named presets are the
+ * operator-facing labels so nobody invents a public SaaS URL.
+ */
+
+/** @typedef {"local-stdio" | "tailscale" | "public-https"} TransportPresetId */
+
+/**
+ * @typedef {object} TransportPreset
+ * @property {TransportPresetId} id
+ * @property {string} label
+ * @property {"stdio" | "https"} transport Connector MCP transport.
+ * @property {string} exampleHost Example URL shape.
+ * @property {string} notes Operator-facing constraints. No secrets.
+ * @property {boolean} gated True when this path is not a supported product claim.
+ */
+
+/** Named presets in display order. */
+export const TRANSPORT_PRESETS = {
+  "local-stdio": {
+    id: "local-stdio",
+    label: "Local stdio",
+    transport: "stdio",
+    exampleHost: "https://drupal.ddev.site",
+    notes:
+      "The MCP client launches this connector as a local subprocess. Drupal must " +
+      "be reachable from this machine (localhost, DDEV/Lando, or a routable LAN).",
+    gated: false,
+  },
+  tailscale: {
+    id: "tailscale",
+    label: "Tailscale VPN",
+    transport: "stdio",
+    exampleHost: "https://drupal.tailnet-name.ts.net",
+    notes:
+      "VPN-required. The machine running Cursor / Claude Code must be on the same " +
+      "Tailscale tailnet as Drupal (typical host: https://<machine>.<tailnet>.ts.net). " +
+      "This is not a public internet path and not a hosted SaaS endpoint.",
+    gated: false,
+  },
+  "public-https": {
+    id: "public-https",
+    label: "Public HTTPS",
+    transport: "https",
+    exampleHost: "https://mcp.example.com/mcp",
+    notes:
+      "Gated / later. An operator-run connector with MCP_TRANSPORT=https, TLS, and " +
+      "inbound OAuth (auth.issuer + auth.audience). There is no public hosted " +
+      "Wilkes & Liberty MCP URL. Do not invent a marketplace remote until Path B exists.",
+    gated: true,
+  },
+};
+
+/**
+ * Look up a transport preset by id.
+ * @param {string} id
+ * @returns {TransportPreset|null}
+ */
+export function getTransportPreset(id) {
+  switch (id) {
+    case "local-stdio":
+      return TRANSPORT_PRESETS["local-stdio"];
+    case "tailscale":
+      return TRANSPORT_PRESETS.tailscale;
+    case "public-https":
+      return TRANSPORT_PRESETS["public-https"];
+    default:
+      return null;
+  }
+}
+
+/**
+ * Preset ids in display order.
+ * @returns {TransportPresetId[]}
+ */
+export function listTransportPresetIds() {
+  return ["local-stdio", "tailscale", "public-https"];
+}
+
+/**
+ * Help text for wizard / doctor --help.
+ * @returns {string}
+ */
+export function formatTransportPresetHelp() {
+  return listTransportPresetIds().map((id) => {
+    const preset = getTransportPreset(id);
+    const gate = preset.gated ? " [gated/later]" : "";
+    return `  ${preset.id}${gate}  ${preset.label} — ${preset.exampleHost}\n    ${preset.notes}`;
+  }).join("\n");
+}
+
+/**
+ * Map a wizard `--preset` onto the existing `--transport` pair.
+ * @param {string} id
+ * @returns {{preset: TransportPreset, transport: "stdio"|"https"}}
+ * @throws {Error} when the id is unknown.
+ */
+export function resolveTransportPreset(id) {
+  const preset = getTransportPreset(String(id || "").trim().toLowerCase());
+  if (!preset) {
+    throw new Error("--preset must be local-stdio|tailscale|public-https.");
+  }
+  return { preset, transport: preset.transport };
+}
+
+/**
+ * RFC 2606 / 6761 documentation and reserved names — not a live Drupal.
+ * Shared by the wizard (DEV-758) and doctor (DEV-759).
+ * @param {string} url
+ * @returns {boolean}
+ */
+export function isReservedDocumentationHost(url) {
+  let host;
+  try {
+    host = new URL(url).hostname;
+  } catch {
+    host = url;
+  }
+  host = String(host).toLowerCase();
+  return (
+    host === "example.com"
+    || host === "example.net"
+    || host === "example.org"
+    || host.endsWith(".example.com")
+    || host.endsWith(".example.net")
+    || host.endsWith(".example.org")
+    || host.endsWith(".example.test")
+    || host.endsWith(".invalid")
+    || host.endsWith(".test")
+    || host.endsWith(".example")
+  );
+}
+
+/**
+ * True when the URL hostname is MagicDNS (*.ts.net), not a substring match.
+ * Shared by doctor messaging (DEV-759) so evil.example.com/.ts.net/path is not treated as Tailscale.
+ * @param {string} url
+ * @returns {boolean}
+ */
+export function isTailscaleMagicDnsHost(url) {
+  let host;
+  try {
+    host = new URL(url).hostname;
+  } catch {
+    host = String(url || "");
+    // Strip path/query/port if a bare host-ish string was passed.
+    host = host.split("/")[0].split("?")[0].split(":")[0];
+  }
+  host = String(host).toLowerCase();
+  return host === "ts.net" || host.endsWith(".ts.net");
+}