drupal-mcp-connector 2.7.3 → 2.8.0

package/scripts/install-commands.js

@@ -0,0 +1,157 @@
+#!/usr/bin/env node
+/**
+ * install-commands.js — copy generated `/drupal-*` stubs into an operator's
+ * client home directories.
+ *
+ * The canonical files live in `.agents/commands/` (in-repo, harness-agnostic).
+ * Claude Code and Grok only auto-load project commands from vendor paths
+ * (`.claude/commands/`, `.grok/commands/`). This script writes the *user-level*
+ * copies so `/drupal-*` works in every project without committing a vendor
+ * folder to this repo or to a consuming application.
+ *
+ * Default targets: `~/.claude/commands` (Claude adapter) and `~/.grok/commands`
+ * (canonical files). Pass `--clients` to subset. Never writes into a project
+ * tree.
+ *
+ * Run: `npm run install:commands -- [--home DIR] [--clients claude,grok,agents]`
+ */
+
+import { mkdirSync, readdirSync, rmSync, writeFileSync, realpathSync } from "fs";
+import { homedir } from "os";
+import { join, resolve } from "path";
+import { pathToFileURL } from "url";
+
+import { allDefinitions } from "../src/tools/index.js";
+import {
+  commandFileName,
+  renderCommandMarkdown,
+  renderClaudeCommandMarkdown,
+} from "./generate-commands.js";
+
+/** Whitelisted install targets. `rel` is under `--home` (default: os.homedir()). */
+export const CLIENTS = {
+  claude: {
+    rel: ".claude/commands",
+    render: renderClaudeCommandMarkdown,
+  },
+  grok: {
+    rel: ".grok/commands",
+    render: renderCommandMarkdown,
+  },
+  agents: {
+    rel: ".agents/commands",
+    render: renderCommandMarkdown,
+  },
+};
+
+const DEFAULT_CLIENTS = ["claude", "grok"];
+
+/**
+ * Parse CLI flags. Unknown flags throw.
+ *
+ * @param {string[]} argv - Arguments after the script name.
+ * @returns {{home?: string, clients: string[], help?: boolean}}
+ */
+export function parseArgs(argv) {
+  const out = { clients: [...DEFAULT_CLIENTS] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--help" || a === "-h") {
+      out.help = true;
+      continue;
+    }
+    if (a === "--home") {
+      out.home = argv[++i];
+      if (!out.home) throw new Error("--home requires a directory");
+      continue;
+    }
+    if (a.startsWith("--home=")) {
+      out.home = a.slice("--home=".length);
+      continue;
+    }
+    if (a === "--clients") {
+      const raw = argv[++i];
+      if (!raw) throw new Error("--clients requires a comma-separated list");
+      out.clients = splitClients(raw);
+      continue;
+    }
+    if (a.startsWith("--clients=")) {
+      out.clients = splitClients(a.slice("--clients=".length));
+      continue;
+    }
+    throw new Error(`Unknown argument: ${a}`);
+  }
+  return out;
+}
+
+function splitClients(raw) {
+  const names = String(raw).split(",").map((s) => s.trim()).filter(Boolean);
+  if (!names.length) throw new Error("--clients requires at least one client");
+  return names;
+}
+
+/**
+ * Write one `drupal-*.md` per tool into each requested client directory,
+ * pruning stale stubs first. Unknown client names fail closed.
+ *
+ * @param {object} [options]
+ * @param {string} [options.home] - Install root (default: os.homedir()).
+ * @param {string[]} [options.clients] - Subset of CLIENTS keys.
+ * @param {Array<object>} [options.definitions]
+ * @returns {Array<{client: string, dir: string, written: string[]}>}
+ */
+export function install(options = {}) {
+  const home = resolve(options.home || homedir());
+  const names = options.clients || DEFAULT_CLIENTS;
+  const definitions = options.definitions || allDefinitions;
+
+  const results = [];
+  for (const name of names) {
+    const client = CLIENTS[name];
+    if (!client) {
+      throw new Error(`Unknown client "${name}". Allowed: ${Object.keys(CLIENTS).join(", ")}`);
+    }
+    const dir = join(home, client.rel);
+    mkdirSync(dir, { recursive: true });
+    for (const f of readdirSync(dir)) {
+      if (/^drupal-.*\.md$/.test(f)) rmSync(join(dir, f));
+    }
+    const written = [];
+    for (const def of definitions) {
+      const file = commandFileName(def);
+      writeFileSync(join(dir, file), client.render(def));
+      written.push(file);
+    }
+    results.push({ client: name, dir, written });
+  }
+  return results;
+}
+
+const HELP = `Usage: node scripts/install-commands.js [--home DIR] [--clients claude,grok,agents]
+
+Copy generated /drupal-* command stubs into operator home directories.
+Does not write into a project tree.
+
+  --home DIR       Install root (default: the current user's home)
+  --clients LIST   Comma-separated subset of: claude, grok, agents
+                   (default: claude,grok)
+`;
+
+const invokedDirectly =
+  process.argv[1] && pathToFileURL(realpathSync(process.argv[1])).href === import.meta.url;
+if (invokedDirectly) {
+  try {
+    const opts = parseArgs(process.argv.slice(2));
+    if (opts.help) {
+      console.error(HELP);
+      process.exit(0);
+    }
+    const results = install(opts);
+    for (const r of results) {
+      console.error(`[install-commands] wrote ${r.written.length} files to ${r.dir} (${r.client})`);
+    }
+  } catch (err) {
+    console.error(`[install-commands] ${err.message}`);
+    process.exit(1);
+  }
+}

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

@@ -93,7 +93,10 @@ export class Backend {
 
   /**
    * Update an entity.
-   * @param {{entityType: string, bundle: string, id: string, attributes?: object, relationships?: object}} _input
+   * @param {{entityType: string, bundle: string, id: string, attributes?: object, relationships?: object, resourceVersion?: string}} _input
+   *   `resourceVersion` is a JSON:API revision selector (`rel:working-copy`,
+   *   `rel:latest-version`, `id:<vid>`). Backends that cannot address revisions
+   *   ignore it.
    * @returns {Promise<import("../canonical.js").CanonicalEntity>}
    */
   async updateEntity(_input) { return notImplemented("updateEntity"); }
@@ -139,6 +142,22 @@ export class Backend {
    */
   async getEntitySchema(_entityType, _bundle) { return notImplemented("getEntitySchema"); }
 
+  /**
+   * Resolve Field API metadata for one field (internal introspection).
+   *
+   * `getEntitySchema` is sampling-only and does NOT expose `allowed_formats`.
+   * The JSON:API adapter reads `field_config` via an internal fetch — not via
+   * agent entity tools (`field_config` is on the agent deny list). Returns
+   * null when the definition cannot be resolved. Callers must not invent
+   * `allowed_formats` from `defaultTextFormat` or `full_html`.
+   *
+   * Default: unknown. GraphQL is read-only for writes; write sites use JSON:API.
+   *
+   * @param {{entityType: string, bundle: string, fieldName: string}} _ref
+   * @returns {Promise<?{fieldName: string, fieldType: ?string, allowedFormats: string[]}>}
+   */
+  async getFieldDefinition(_ref) { return null; }
+
   /**
    * List user roles.
    * @returns {Promise<Array<{id: string, machineName: string, label: string, weight: number}>>}

package/src/lib/backends/jsonapi.js

@@ -9,6 +9,7 @@
 
 import { drupalFetch, drupalUploadFile } from "../drupal-fetch.js";
 import { validateUuid, validateMachineName } from "../validate.js";
+import { parseFieldConfigObject } from "../field-definition.js";
 import { Backend } from "./backend-interface.js";
 import {
   makeCanonicalEntity,
@@ -208,8 +209,10 @@ export class JsonApiBackend extends Backend {
         if (BASE_ATTRIBUTE_FIELDS.includes(k)) return false;
         if (INTERNAL_ATTR_RE.test(k)) {
           // Paragraph ERR attach needs the current revision id (#192).
+          // Node / revisionable writes need the working vs live vid (#166).
           // Other drupal_internal__* attributes stay stripped.
-          return entityType === "paragraph" && k === "drupal_internal__revision_id";
+          return k === "drupal_internal__vid"
+            || (entityType === "paragraph" && k === "drupal_internal__revision_id");
         }
         return true;
       })
@@ -339,17 +342,24 @@ export class JsonApiBackend extends Backend {
   /**
    * Update an entity via JSON:API PATCH. Retries without `status` on moderated
    * bundles — see writeWithModerationFallback.
-   * @param {{entityType: string, bundle: string, id: string, attributes?: object, relationships?: object}} input
+   * @param {{entityType: string, bundle: string, id: string, attributes?: object, relationships?: object, resourceVersion?: string}} input
+   *   `resourceVersion` is a JSON:API revision selector (e.g. `rel:working-copy`).
+   *   When set, it is appended so a forward revision is PATCHed instead of the
+   *   canonical default (#166 / Drupal #2795279).
    * @returns {Promise<import("../canonical.js").CanonicalEntity>} The updated entity.
    */
-  async updateEntity({ entityType, bundle, id, attributes = {}, relationships }) {
+  async updateEntity({ entityType, bundle, id, attributes = {}, relationships, resourceVersion }) {
     validateUuid(id);
     const buildPayload = (attrs) => {
       const payload = { data: { type: `${entityType}--${bundle}`, id, attributes: attrs } };
       if (relationships) payload.data.relationships = relationships;
       return payload;
     };
-    const data = await this.writeWithModerationFallback(`${this.resourcePath(entityType, bundle)}/${encodeURIComponent(id)}`, "PATCH", buildPayload, attributes);
+    let path = `${this.resourcePath(entityType, bundle)}/${encodeURIComponent(id)}`;
+    if (resourceVersion) {
+      path += `?resourceVersion=${encodeURIComponent(resourceVersion)}`;
+    }
+    const data = await this.writeWithModerationFallback(path, "PATCH", buildPayload, attributes);
     return this.toCanonical(data.data);
   }
 
@@ -512,6 +522,39 @@ export class JsonApiBackend extends Backend {
       });
   }
 
+  /**
+   * Read Field API metadata from JSON:API `field_config` (chain step 1).
+   *
+   * This is an internal introspection call, not an agent entity-tool read:
+   * `field_config` is on the connector deny list. Do not invent
+   * `allowed_formats` from `this.site.defaultTextFormat` or `full_html`.
+   * Empty / unreadable `field_config` returns null so the caller can try
+   * Drush `config:get field.field.{entityType}.{bundle}.{field}` and, if
+   * that also fails, keep the historical default chain only while the list
+   * is unknown.
+   *
+   * @param {{entityType: string, bundle: string, fieldName: string}} ref
+   * @returns {Promise<?{fieldName: string, fieldType: ?string, allowedFormats: string[]}>}
+   */
+  async getFieldDefinition({ entityType, bundle, fieldName }) {
+    validateMachineName(entityType, "entityType");
+    validateMachineName(bundle, "bundle");
+    validateMachineName(fieldName, "fieldName");
+    const params = new URLSearchParams();
+    params.set("filter[entity_type]", entityType);
+    params.set("filter[bundle]", bundle);
+    params.set("filter[field_name]", fieldName);
+    params.set("page[limit]", "1");
+    let data;
+    try {
+      data = await drupalFetch(this.site, `/jsonapi/field_config/field_config?${params}`);
+    } catch {
+      return null;
+    }
+    const row = Array.isArray(data?.data) ? data.data[0] : data?.data;
+    return parseFieldConfigObject(row?.attributes, fieldName);
+  }
+
   /**
    * Describe a bundle's fields by sampling one entity and inferring attribute
    * types from its values. JSON:API has no schema endpoint, so an empty bundle

package/src/lib/body-summary.js

@@ -0,0 +1,60 @@
+/**
+ * Decide whether the `summary` argument may be written onto `body`.
+ *
+ * Core `text_with_summary` stores a `summary` property. `text_long` and
+ * sampled `text_formatted` do not — Drupal drops an unknown property, so a
+ * silent write would lose the teaser. Fail closed when the sampled schema
+ * cannot confirm the property exists (#163).
+ */
+
+/** Warning attached when `summary` is written onto a text_with_summary body. */
+export const SUMMARY_DEPRECATED_WARNING = {
+  code: "summary_parameter_deprecated",
+  message:
+    "The `summary` argument writes body.summary on core text_with_summary. " +
+    "Prefer setting the site's dedicated deck/summary field via `fields`.",
+};
+
+/**
+ * @param {object} backend Backend with `getEntitySchema`.
+ * @param {string} bundle Node bundle machine name.
+ * @param {string|undefined} summary Caller-supplied summary; undefined = omitted.
+ * @returns {Promise<{deprecated: boolean}>} Whether a deprecation notice applies.
+ * @throws {Error} When `summary` was supplied and the body field has no
+ *   summary property, or the schema cannot be determined.
+ */
+export async function assertBodySummaryWritable(backend, bundle, summary) {
+  if (summary === undefined) return { deprecated: false };
+
+  let schema;
+  try {
+    schema = await backend.getEntitySchema("node", bundle);
+  } catch (err) {
+    const detail = err instanceof Error ? err.message : String(err);
+    throw new Error(
+      `Cannot write \`summary\`: the body field schema for node.${bundle} could not be determined (${detail}). Set the site's dedicated deck field via \`fields\` instead.`,
+    );
+  }
+
+  const bodyType = schema?.attributes?.body;
+  if (bodyType === "text_with_summary") {
+    return { deprecated: true };
+  }
+
+  const sampled = bodyType ? ` (sampled as ${bodyType})` : "";
+  throw new Error(
+    `This site's body field has no summary property${sampled}; set the site's deck field via \`fields\`. The \`summary\` argument is only valid for core text_with_summary body fields.`,
+  );
+}
+
+/**
+ * Attach the `summary` deprecation notice to a write (or dryRun) result.
+ *
+ * @param {object|null|undefined} result Tool response.
+ * @returns {object|null|undefined} Result with `_warnings` when result is an object.
+ */
+export function attachSummaryDeprecation(result) {
+  if (!result || typeof result !== "object") return result;
+  const existing = Array.isArray(result._warnings) ? result._warnings : [];
+  return { ...result, _warnings: [...existing, SUMMARY_DEPRECATED_WARNING] };
+}