elementor-mcp-agent 1.0.0 → 1.2.0

package/dist/server.js

@@ -448,8 +448,8 @@ async function restoreBackup(siteId, postId, data_meta_key, settings_meta_key) {
     const r2 = await sshWpCli(site, `post meta get ${postId} ${settings_meta_key}`, { timeout_ms: 3e4 });
     if (r2.exitCode === 0 && r2.stdout) settings_value = r2.stdout;
   }
-  const writeData = await sshWpCli(site, `post meta update ${postId} _elementor_data ${shellQuote(data_value)}`, { timeout_ms: 3e4 });
-  if (writeData.exitCode !== 0) throw new Error(`Restore write failed: ${writeData.stderr}`);
+  const writeData2 = await sshWpCli(site, `post meta update ${postId} _elementor_data ${shellQuote(data_value)}`, { timeout_ms: 3e4 });
+  if (writeData2.exitCode !== 0) throw new Error(`Restore write failed: ${writeData2.stderr}`);
   if (settings_value !== void 0) {
     await sshWpCli(site, `post meta update ${postId} _elementor_page_settings ${shellQuote(settings_value)}`, { timeout_ms: 3e4 });
   }
@@ -854,6 +854,12 @@ function* walkElements(data, path = [], depth = 0) {
     }
   }
 }
+function findElementById(data, id) {
+  for (const { element } of walkElements(data)) {
+    if (element.id === id) return element;
+  }
+  return null;
+}
 function findReplaceInWidgets(data, find, replace, options = {}) {
   let count = 0;
   const flags = options.caseSensitive ? "g" : "gi";
@@ -2115,6 +2121,851 @@ var checkElementorVersionsTool = defineTool({
   }
 });
 
+// src/tools/widgets.ts
+import { z as z9 } from "zod";
+init_wp_rest();
+
+// src/elementor/widget-ops.ts
+function readWidget(data, widgetId) {
+  return findElementById(data, widgetId);
+}
+function updateWidgetSettings(data, widgetId, patch) {
+  const widget = findElementById(data, widgetId);
+  if (!widget || widget.elType !== "widget") return false;
+  widget.settings = { ...widget.settings, ...patch };
+  return true;
+}
+function deleteWidget(data, widgetId) {
+  function removeFrom(arr) {
+    for (let i = 0; i < arr.length; i++) {
+      if (arr[i].id === widgetId) {
+        arr.splice(i, 1);
+        return true;
+      }
+      if (arr[i].elements && removeFrom(arr[i].elements)) return true;
+    }
+    return false;
+  }
+  return removeFrom(data);
+}
+function findParent(data, widgetId) {
+  for (const { element } of walkElements(data)) {
+    if (element.elements?.some((e) => e.id === widgetId)) return element;
+  }
+  return null;
+}
+function duplicateWidget(data, widgetId) {
+  const parent = findParent(data, widgetId);
+  if (!parent || !parent.elements) return { ok: false };
+  const idx = parent.elements.findIndex((e) => e.id === widgetId);
+  if (idx < 0) return { ok: false };
+  const clone = JSON.parse(JSON.stringify(parent.elements[idx]));
+  clone.id = generateId();
+  parent.elements.splice(idx + 1, 0, clone);
+  return { ok: true, new_widget_id: clone.id };
+}
+function swapWidgetType(data, widgetId, newType, newSettings = {}) {
+  const widget = findElementById(data, widgetId);
+  if (!widget || widget.elType !== "widget") return false;
+  widget.widgetType = newType;
+  widget.settings = newSettings;
+  return true;
+}
+function addWidget(data, parentId, widgetType, settings = {}) {
+  const parent = findElementById(data, parentId);
+  if (!parent) return { ok: false };
+  if (!parent.elements) parent.elements = [];
+  const newWidget = {
+    id: generateId(),
+    elType: "widget",
+    widgetType,
+    settings,
+    elements: [],
+    isInner: false
+  };
+  parent.elements.push(newWidget);
+  return { ok: true, new_widget_id: newWidget.id };
+}
+function moveWidget(data, widgetId, newParentId, position = -1) {
+  const widget = findElementById(data, widgetId);
+  if (!widget) return false;
+  const oldParent = findParent(data, widgetId);
+  if (!oldParent || !oldParent.elements) return false;
+  const newParent = findElementById(data, newParentId);
+  if (!newParent) return false;
+  if (!newParent.elements) newParent.elements = [];
+  const idx = oldParent.elements.findIndex((e) => e.id === widgetId);
+  if (idx < 0) return false;
+  oldParent.elements.splice(idx, 1);
+  if (position < 0 || position >= newParent.elements.length) {
+    newParent.elements.push(widget);
+  } else {
+    newParent.elements.splice(position, 0, widget);
+  }
+  return true;
+}
+function generateId() {
+  return Math.random().toString(16).slice(2, 9).padEnd(7, "0");
+}
+
+// src/tools/widgets.ts
+init_backup();
+init_css_flush();
+init_policies();
+init_confirmation();
+
+// src/elementor/verify.ts
+init_wp_rest();
+import { z as z8 } from "zod";
+var VerificationSchema = z8.object({
+  /** Plain-English description of what we re-read and compared. */
+  method: z8.string(),
+  /** Whether a canonical re-read of the page succeeded. */
+  reread_ok: z8.boolean(),
+  /** Op-specific: did the change we requested actually persist? */
+  matches_requested: z8.boolean(),
+  /** Op-specific extra data (e.g. the actual persisted widget settings). */
+  persisted: z8.record(z8.any()).optional(),
+  /** Free-text notes / explanation when matches_requested is false. */
+  notes: z8.string().optional()
+});
+async function verifyWrite(args) {
+  try {
+    const page = await wpRequest(
+      `/wp/v2/pages/${args.pageId}?context=edit&_fields=meta`,
+      { siteId: args.siteId }
+    );
+    const v = page.meta?._elementor_data;
+    const raw = typeof v === "string" ? v : JSON.stringify(v ?? []);
+    const data = parseElementorData(raw);
+    const result = args.predicate(data);
+    return {
+      method: args.description,
+      reread_ok: true,
+      matches_requested: result.ok,
+      persisted: result.persisted,
+      notes: result.notes
+    };
+  } catch (err) {
+    return {
+      method: args.description,
+      reread_ok: false,
+      matches_requested: false,
+      notes: `Canonical re-read failed: ${err.message}`
+    };
+  }
+}
+function deepEqual(a, b) {
+  if (a === b) return true;
+  if (typeof a !== typeof b) return false;
+  if (a === null || b === null) return a === b;
+  if (Array.isArray(a) || Array.isArray(b)) {
+    if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return false;
+    return a.every((x, i) => deepEqual(x, b[i]));
+  }
+  if (typeof a === "object" && typeof b === "object") {
+    const ka = Object.keys(a);
+    const kb = Object.keys(b);
+    if (ka.length !== kb.length) return false;
+    return ka.every(
+      (k) => deepEqual(a[k], b[k])
+    );
+  }
+  return false;
+}
+
+// src/tools/widgets.ts
+var MutationResponseShape = {
+  mode: z9.enum(["dry_run", "applied"]),
+  page_id: z9.number(),
+  confirmation_token: z9.string().optional(),
+  backup_meta_key: z9.string().optional(),
+  css_flush: z9.string().optional(),
+  mutated: z9.boolean().optional(),
+  warnings: z9.array(z9.string()).optional(),
+  verification: VerificationSchema.optional()
+};
+async function fetchData(siteId, pageId) {
+  const page = await wpRequest(
+    `/wp/v2/pages/${pageId}?context=edit&_fields=meta`,
+    { siteId }
+  );
+  const v = page.meta?._elementor_data;
+  const raw = typeof v === "string" ? v : JSON.stringify(v ?? []);
+  return { raw, data: parseElementorData(raw) };
+}
+async function writeData(siteId, pageId, data) {
+  const ser = serializeElementorData(data);
+  const validation = validateElementorData(ser);
+  if (!validation.valid) {
+    throw new Error("Validation failed after edit: " + validation.errors.join("; "));
+  }
+  await wpRequest(`/wp/v2/pages/${pageId}`, {
+    siteId,
+    method: "PUT",
+    body: { meta: { _elementor_data: ser } }
+  });
+  const flush = await flushCSS(siteId, pageId);
+  return { method: flush.method, serialized: ser };
+}
+var readWidgetTool = defineTool({
+  name: "read_widget",
+  description: "Fetch a single widget's full settings by id. Use list_widgets_in_page to find the id first.",
+  inputSchema: z9.object({
+    site_id: z9.string().optional(),
+    page_id: z9.number().int().positive(),
+    widget_id: z9.string().min(1)
+  }),
+  outputSchema: z9.object({
+    widget_id: z9.string(),
+    widget_type: z9.string().optional(),
+    settings: z9.record(z9.any())
+  }),
+  annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+  async handler(input) {
+    const { data } = await fetchData(input.site_id, input.page_id);
+    const w = readWidget(data, input.widget_id);
+    if (!w) throw new Error(`Widget ${input.widget_id} not found on page ${input.page_id}`);
+    return { widget_id: w.id, widget_type: w.widgetType, settings: w.settings };
+  }
+});
+var updateWidgetSettingsTool = defineTool({
+  name: "update_widget_settings",
+  description: "Shallow-merge a partial settings object into one widget. Backs up the page first, validates the result, auto-flushes CSS, then re-reads the page and verifies the patch persisted (matches_requested in the response). Two-call confirmation.",
+  inputSchema: z9.object({
+    site_id: z9.string().optional(),
+    page_id: z9.number().int().positive(),
+    widget_id: z9.string().min(1),
+    settings_patch: z9.record(z9.any()),
+    confirmation: z9.string().optional()
+  }),
+  outputSchema: z9.object({
+    ...MutationResponseShape,
+    widget_id: z9.string(),
+    keys_changed: z9.array(z9.string())
+  }),
+  annotations: { destructiveHint: true, idempotentHint: false, openWorldHint: true },
+  async handler(input) {
+    if (!input.confirmation) {
+      const token = issueConfirmation("update_widget_settings", input, POLICIES.CONFIRMATION_TTL_SECONDS);
+      return {
+        mode: "dry_run",
+        page_id: input.page_id,
+        widget_id: input.widget_id,
+        keys_changed: Object.keys(input.settings_patch),
+        confirmation_token: token
+      };
+    }
+    const conf = consumeConfirmation(input.confirmation, "update_widget_settings");
+    if (!conf) throw new Error("Invalid or expired confirmation token");
+    const { raw: rawBefore, data } = await fetchData(input.site_id, input.page_id);
+    if (!updateWidgetSettings(data, input.widget_id, input.settings_patch)) {
+      throw new Error(`Widget ${input.widget_id} not found`);
+    }
+    const backup = await fullBackup(input.site_id, input.page_id);
+    const w = await writeData(input.site_id, input.page_id, data);
+    const verification = await verifyWrite({
+      siteId: input.site_id,
+      pageId: input.page_id,
+      description: `Re-read /wp/v2/pages/${input.page_id} and check widget ${input.widget_id} settings include the requested patch`,
+      predicate: (canonical) => {
+        const widget = findElementById(canonical, input.widget_id);
+        if (!widget) return { ok: false, notes: "Widget no longer present after write" };
+        const persisted = widget.settings;
+        const mismatches = [];
+        for (const [k, want] of Object.entries(input.settings_patch)) {
+          if (!deepEqual(persisted[k], want)) mismatches.push(k);
+        }
+        return {
+          ok: mismatches.length === 0,
+          persisted,
+          notes: mismatches.length === 0 ? void 0 : `Persisted state diverges from requested patch on key(s): ${mismatches.join(", ")}`
+        };
+      }
+    });
+    return {
+      mode: "applied",
+      page_id: input.page_id,
+      widget_id: input.widget_id,
+      keys_changed: Object.keys(input.settings_patch),
+      backup_meta_key: backup.meta_key,
+      css_flush: w.method,
+      mutated: rawBefore !== w.serialized,
+      warnings: [],
+      verification
+    };
+  }
+});
+var deleteWidgetTool = defineTool({
+  name: "delete_widget",
+  description: "Remove a widget from a page by id. Two-call confirmation. Backs up before deleting; re-reads to confirm the widget is gone.",
+  inputSchema: z9.object({
+    site_id: z9.string().optional(),
+    page_id: z9.number().int().positive(),
+    widget_id: z9.string().min(1),
+    confirmation: z9.string().optional()
+  }),
+  outputSchema: z9.object({
+    ...MutationResponseShape,
+    widget_id: z9.string()
+  }),
+  annotations: { destructiveHint: true, idempotentHint: false, openWorldHint: true },
+  async handler(input) {
+    if (!input.confirmation) {
+      const token = issueConfirmation("delete_widget", input, POLICIES.CONFIRMATION_TTL_SECONDS);
+      return { mode: "dry_run", page_id: input.page_id, widget_id: input.widget_id, confirmation_token: token };
+    }
+    const conf = consumeConfirmation(input.confirmation, "delete_widget");
+    if (!conf) throw new Error("Invalid or expired confirmation token");
+    const { raw: rawBefore, data } = await fetchData(input.site_id, input.page_id);
+    if (!deleteWidget(data, input.widget_id)) throw new Error(`Widget ${input.widget_id} not found`);
+    const backup = await fullBackup(input.site_id, input.page_id);
+    const w = await writeData(input.site_id, input.page_id, data);
+    const verification = await verifyWrite({
+      siteId: input.site_id,
+      pageId: input.page_id,
+      description: `Re-read /wp/v2/pages/${input.page_id} and assert widget ${input.widget_id} is gone`,
+      predicate: (canonical) => {
+        const found = findElementById(canonical, input.widget_id);
+        return {
+          ok: found === null,
+          notes: found ? "Widget still present in canonical re-read \u2014 delete did not persist" : void 0
+        };
+      }
+    });
+    return {
+      mode: "applied",
+      page_id: input.page_id,
+      widget_id: input.widget_id,
+      backup_meta_key: backup.meta_key,
+      css_flush: w.method,
+      mutated: rawBefore !== w.serialized,
+      warnings: [],
+      verification
+    };
+  }
+});
+var duplicateWidgetTool = defineTool({
+  name: "duplicate_widget",
+  description: "Duplicate a widget in place (right after the original). The clone gets a new id. Re-reads to confirm the clone persisted. Two-call confirmation.",
+  inputSchema: z9.object({
+    site_id: z9.string().optional(),
+    page_id: z9.number().int().positive(),
+    widget_id: z9.string().min(1),
+    confirmation: z9.string().optional()
+  }),
+  outputSchema: z9.object({
+    ...MutationResponseShape,
+    source_widget_id: z9.string(),
+    new_widget_id: z9.string().optional()
+  }),
+  annotations: { destructiveHint: false, idempotentHint: false, openWorldHint: true },
+  async handler(input) {
+    if (!input.confirmation) {
+      const token = issueConfirmation("duplicate_widget", input, POLICIES.CONFIRMATION_TTL_SECONDS);
+      return { mode: "dry_run", page_id: input.page_id, source_widget_id: input.widget_id, confirmation_token: token };
+    }
+    const conf = consumeConfirmation(input.confirmation, "duplicate_widget");
+    if (!conf) throw new Error("Invalid or expired confirmation token");
+    const { raw: rawBefore, data } = await fetchData(input.site_id, input.page_id);
+    const r = duplicateWidget(data, input.widget_id);
+    if (!r.ok || !r.new_widget_id) throw new Error(`Widget ${input.widget_id} not found`);
+    const newId = r.new_widget_id;
+    const backup = await fullBackup(input.site_id, input.page_id);
+    const w = await writeData(input.site_id, input.page_id, data);
+    const verification = await verifyWrite({
+      siteId: input.site_id,
+      pageId: input.page_id,
+      description: `Re-read /wp/v2/pages/${input.page_id} and assert the clone (${newId}) exists alongside the source`,
+      predicate: (canonical) => {
+        const source = findElementById(canonical, input.widget_id);
+        const clone = findElementById(canonical, newId);
+        return {
+          ok: source !== null && clone !== null,
+          notes: !clone ? "Clone not present in canonical re-read" : !source ? "Original is missing after duplicate" : void 0
+        };
+      }
+    });
+    return {
+      mode: "applied",
+      page_id: input.page_id,
+      source_widget_id: input.widget_id,
+      new_widget_id: newId,
+      backup_meta_key: backup.meta_key,
+      css_flush: w.method,
+      mutated: rawBefore !== w.serialized,
+      warnings: [],
+      verification
+    };
+  }
+});
+var swapWidgetTypeTool = defineTool({
+  name: "swap_widget_type",
+  description: "Replace a widget's type (e.g., heading \u2192 button) while preserving its id and position. Provide full new_settings \u2014 the old settings are NOT carried over (different widget types have incompatible schemas). Re-reads to confirm. Two-call confirmation.",
+  inputSchema: z9.object({
+    site_id: z9.string().optional(),
+    page_id: z9.number().int().positive(),
+    widget_id: z9.string().min(1),
+    new_widget_type: z9.string().min(1),
+    new_settings: z9.record(z9.any()).default({}),
+    confirmation: z9.string().optional()
+  }),
+  outputSchema: z9.object({
+    ...MutationResponseShape,
+    widget_id: z9.string(),
+    new_widget_type: z9.string()
+  }),
+  annotations: { destructiveHint: true, idempotentHint: false, openWorldHint: true },
+  async handler(input) {
+    if (!input.confirmation) {
+      const token = issueConfirmation("swap_widget_type", input, POLICIES.CONFIRMATION_TTL_SECONDS);
+      return { mode: "dry_run", page_id: input.page_id, widget_id: input.widget_id, new_widget_type: input.new_widget_type, confirmation_token: token };
+    }
+    const conf = consumeConfirmation(input.confirmation, "swap_widget_type");
+    if (!conf) throw new Error("Invalid or expired confirmation token");
+    const { raw: rawBefore, data } = await fetchData(input.site_id, input.page_id);
+    if (!swapWidgetType(data, input.widget_id, input.new_widget_type, input.new_settings)) {
+      throw new Error(`Widget ${input.widget_id} not found`);
+    }
+    const backup = await fullBackup(input.site_id, input.page_id);
+    const w = await writeData(input.site_id, input.page_id, data);
+    const verification = await verifyWrite({
+      siteId: input.site_id,
+      pageId: input.page_id,
+      description: `Re-read /wp/v2/pages/${input.page_id} and assert widget ${input.widget_id} now has widgetType="${input.new_widget_type}"`,
+      predicate: (canonical) => {
+        const widget = findElementById(canonical, input.widget_id);
+        if (!widget) return { ok: false, notes: "Widget missing after swap" };
+        return {
+          ok: widget.widgetType === input.new_widget_type,
+          persisted: { widgetType: widget.widgetType, settings: widget.settings },
+          notes: widget.widgetType === input.new_widget_type ? void 0 : `Expected widgetType="${input.new_widget_type}", canonical state has "${widget.widgetType}"`
+        };
+      }
+    });
+    return {
+      mode: "applied",
+      page_id: input.page_id,
+      widget_id: input.widget_id,
+      new_widget_type: input.new_widget_type,
+      backup_meta_key: backup.meta_key,
+      css_flush: w.method,
+      mutated: rawBefore !== w.serialized,
+      warnings: [],
+      verification
+    };
+  }
+});
+var addWidgetTool = defineTool({
+  name: "add_widget",
+  description: "Append a new widget to a parent container (section, column, or container) on a page. Re-reads to confirm the new widget exists under the parent. Two-call confirmation.",
+  inputSchema: z9.object({
+    site_id: z9.string().optional(),
+    page_id: z9.number().int().positive(),
+    parent_id: z9.string().min(1).describe("Id of the section/column/container that will receive the widget."),
+    widget_type: z9.string().min(1).describe("e.g., 'heading', 'text-editor', 'button', 'image'."),
+    settings: z9.record(z9.any()).default({}),
+    confirmation: z9.string().optional()
+  }),
+  outputSchema: z9.object({
+    ...MutationResponseShape,
+    parent_id: z9.string(),
+    widget_type: z9.string(),
+    new_widget_id: z9.string().optional()
+  }),
+  annotations: { destructiveHint: false, idempotentHint: false, openWorldHint: true },
+  async handler(input) {
+    if (!input.confirmation) {
+      const token = issueConfirmation("add_widget", input, POLICIES.CONFIRMATION_TTL_SECONDS);
+      return { mode: "dry_run", page_id: input.page_id, parent_id: input.parent_id, widget_type: input.widget_type, confirmation_token: token };
+    }
+    const conf = consumeConfirmation(input.confirmation, "add_widget");
+    if (!conf) throw new Error("Invalid or expired confirmation token");
+    const { raw: rawBefore, data } = await fetchData(input.site_id, input.page_id);
+    const r = addWidget(data, input.parent_id, input.widget_type, input.settings);
+    if (!r.ok || !r.new_widget_id) throw new Error(`Parent ${input.parent_id} not found`);
+    const newId = r.new_widget_id;
+    const backup = await fullBackup(input.site_id, input.page_id);
+    const w = await writeData(input.site_id, input.page_id, data);
+    const verification = await verifyWrite({
+      siteId: input.site_id,
+      pageId: input.page_id,
+      description: `Re-read /wp/v2/pages/${input.page_id} and assert new widget ${newId} exists under parent ${input.parent_id} with widgetType="${input.widget_type}"`,
+      predicate: (canonical) => {
+        const widget = findElementById(canonical, newId);
+        if (!widget) return { ok: false, notes: "New widget not found after add" };
+        const parent = findElementById(canonical, input.parent_id);
+        const isUnderParent = parent?.elements?.some((e) => e.id === newId) === true;
+        return {
+          ok: widget.widgetType === input.widget_type && isUnderParent,
+          notes: !isUnderParent ? `Widget exists but is not under expected parent ${input.parent_id}` : widget.widgetType !== input.widget_type ? `Widget exists with wrong widgetType "${widget.widgetType}"` : void 0
+        };
+      }
+    });
+    return {
+      mode: "applied",
+      page_id: input.page_id,
+      parent_id: input.parent_id,
+      widget_type: input.widget_type,
+      new_widget_id: newId,
+      backup_meta_key: backup.meta_key,
+      css_flush: w.method,
+      mutated: rawBefore !== w.serialized,
+      warnings: [],
+      verification
+    };
+  }
+});
+var moveWidgetTool = defineTool({
+  name: "move_widget",
+  description: "Move a widget to a different parent (or different position in the same parent). Re-reads to confirm new parent. Two-call confirmation.",
+  inputSchema: z9.object({
+    site_id: z9.string().optional(),
+    page_id: z9.number().int().positive(),
+    widget_id: z9.string().min(1),
+    new_parent_id: z9.string().min(1),
+    position: z9.number().int().default(-1).describe("0-based position in the new parent. -1 = append."),
+    confirmation: z9.string().optional()
+  }),
+  outputSchema: z9.object({
+    ...MutationResponseShape,
+    widget_id: z9.string(),
+    new_parent_id: z9.string()
+  }),
+  annotations: { destructiveHint: true, idempotentHint: false, openWorldHint: true },
+  async handler(input) {
+    if (!input.confirmation) {
+      const token = issueConfirmation("move_widget", input, POLICIES.CONFIRMATION_TTL_SECONDS);
+      return { mode: "dry_run", page_id: input.page_id, widget_id: input.widget_id, new_parent_id: input.new_parent_id, confirmation_token: token };
+    }
+    const conf = consumeConfirmation(input.confirmation, "move_widget");
+    if (!conf) throw new Error("Invalid or expired confirmation token");
+    const { raw: rawBefore, data } = await fetchData(input.site_id, input.page_id);
+    if (!moveWidget(data, input.widget_id, input.new_parent_id, input.position)) {
+      throw new Error(`Widget or parent not found`);
+    }
+    const backup = await fullBackup(input.site_id, input.page_id);
+    const w = await writeData(input.site_id, input.page_id, data);
+    const verification = await verifyWrite({
+      siteId: input.site_id,
+      pageId: input.page_id,
+      description: `Re-read /wp/v2/pages/${input.page_id} and assert widget ${input.widget_id} is now a direct child of ${input.new_parent_id}`,
+      predicate: (canonical) => {
+        const parent = findElementById(canonical, input.new_parent_id);
+        const isUnderNewParent = parent?.elements?.some((e) => e.id === input.widget_id) === true;
+        return {
+          ok: isUnderNewParent,
+          notes: isUnderNewParent ? void 0 : `Widget ${input.widget_id} not found under ${input.new_parent_id} after move`
+        };
+      }
+    });
+    return {
+      mode: "applied",
+      page_id: input.page_id,
+      widget_id: input.widget_id,
+      new_parent_id: input.new_parent_id,
+      backup_meta_key: backup.meta_key,
+      css_flush: w.method,
+      mutated: rawBefore !== w.serialized,
+      warnings: [],
+      verification
+    };
+  }
+});
+
+// src/tools/bulk.ts
+import { z as z10 } from "zod";
+init_wp_rest();
+init_config();
+init_backup();
+init_css_flush();
+init_policies();
+init_confirmation();
+async function listElementorPageIds(siteId) {
+  const out = [];
+  let page = 1;
+  for (; ; ) {
+    const items = await wpRequest("/wp/v2/pages", {
+      siteId,
+      query: {
+        meta_key: "_elementor_edit_mode",
+        meta_value: "builder",
+        context: "edit",
+        per_page: 100,
+        page,
+        _fields: "id,title"
+      }
+    });
+    if (items.length === 0) break;
+    out.push(...items.map((p) => ({ id: p.id, title: p.title.rendered })));
+    if (items.length < 100) break;
+    page++;
+    if (page > 50) break;
+  }
+  return out;
+}
+var bulkFindReplaceSiteTool = defineTool({
+  name: "bulk_find_replace_site",
+  description: "Find/replace plain text in every Elementor page on a single site. TWO-CALL FLOW: dry-run returns per-page match_count + total + confirmation_token. Apply iterates each page (auto-backup + validate + flush per page). Slower than wp_search_replace but works without SSH and gives per-page granularity.",
+  inputSchema: z10.object({
+    site_id: z10.string().optional(),
+    find: z10.string().min(1),
+    replace: z10.string(),
+    widget_type: z10.string().optional(),
+    case_sensitive: z10.boolean().default(false),
+    confirmation: z10.string().optional()
+  }),
+  outputSchema: z10.object({
+    mode: z10.enum(["dry_run", "applied"]),
+    site_id: z10.string(),
+    pages_scanned: z10.number(),
+    total_match_count: z10.number(),
+    pages_with_matches: z10.array(z10.object({
+      page_id: z10.number(),
+      title: z10.string(),
+      match_count: z10.number()
+    })),
+    pages_applied: z10.array(z10.object({
+      page_id: z10.number(),
+      backup_meta_key: z10.string().optional(),
+      css_flush: z10.string().optional(),
+      mode: z10.enum(["applied", "rolled_back", "skipped"]),
+      error: z10.string().optional()
+    })).optional(),
+    confirmation_token: z10.string().optional(),
+    expires_in_seconds: z10.number().optional()
+  }),
+  annotations: { destructiveHint: true, idempotentHint: false, openWorldHint: true },
+  async handler(input) {
+    const pages = await listElementorPageIds(input.site_id);
+    const matches = [];
+    for (const p of pages) {
+      try {
+        const page = await wpRequest(`/wp/v2/pages/${p.id}?context=edit&_fields=meta`, { siteId: input.site_id });
+        const v = page.meta?._elementor_data;
+        const raw = typeof v === "string" ? v : JSON.stringify(v ?? []);
+        const data = parseElementorData(raw);
+        const dry = findReplaceInWidgets(JSON.parse(JSON.stringify(data)), input.find, input.replace, {
+          widgetType: input.widget_type,
+          caseSensitive: input.case_sensitive
+        });
+        if (dry.replacementCount > 0) matches.push({ page_id: p.id, title: p.title, match_count: dry.replacementCount });
+      } catch {
+      }
+    }
+    const total = matches.reduce((s, m) => s + m.match_count, 0);
+    if (!input.confirmation) {
+      if (total === 0) {
+        return {
+          mode: "dry_run",
+          site_id: loadConfig().default_site_id ?? "default",
+          pages_scanned: pages.length,
+          total_match_count: 0,
+          pages_with_matches: []
+        };
+      }
+      const token = issueConfirmation("bulk_find_replace_site", { find: input.find, replace: input.replace, page_ids: matches.map((m) => m.page_id) }, POLICIES.CONFIRMATION_TTL_SECONDS);
+      return {
+        mode: "dry_run",
+        site_id: input.site_id ?? loadConfig().default_site_id ?? "default",
+        pages_scanned: pages.length,
+        total_match_count: total,
+        pages_with_matches: matches,
+        confirmation_token: token,
+        expires_in_seconds: POLICIES.CONFIRMATION_TTL_SECONDS
+      };
+    }
+    const conf = consumeConfirmation(input.confirmation, "bulk_find_replace_site");
+    if (!conf) throw new Error("Invalid or expired confirmation token");
+    const applied = [];
+    for (const m of matches) {
+      try {
+        const page = await wpRequest(`/wp/v2/pages/${m.page_id}?context=edit&_fields=meta`, { siteId: input.site_id });
+        const v = page.meta?._elementor_data;
+        const raw = typeof v === "string" ? v : JSON.stringify(v ?? []);
+        const data = parseElementorData(raw);
+        findReplaceInWidgets(data, input.find, input.replace, { widgetType: input.widget_type, caseSensitive: input.case_sensitive });
+        const ser = serializeElementorData(data);
+        const validation = validateElementorData(ser);
+        if (!validation.valid) {
+          applied.push({ page_id: m.page_id, mode: "rolled_back", error: validation.errors.join("; ") });
+          continue;
+        }
+        const backup = await fullBackup(input.site_id, m.page_id);
+        await wpRequest(`/wp/v2/pages/${m.page_id}`, {
+          siteId: input.site_id,
+          method: "PUT",
+          body: { meta: { _elementor_data: ser } }
+        });
+        const flush = await flushCSS(input.site_id, m.page_id);
+        applied.push({ page_id: m.page_id, backup_meta_key: backup.meta_key, css_flush: flush.method, mode: "applied" });
+      } catch (e) {
+        applied.push({ page_id: m.page_id, mode: "skipped", error: e.message });
+      }
+    }
+    return {
+      mode: "applied",
+      site_id: input.site_id ?? loadConfig().default_site_id ?? "default",
+      pages_scanned: pages.length,
+      total_match_count: total,
+      pages_with_matches: matches,
+      pages_applied: applied
+    };
+  }
+});
+var fleetFindReplaceTool = defineTool({
+  name: "fleet_find_replace",
+  description: "Find/replace plain text across every Elementor page of every site in the pool. Same flow as bulk_find_replace_site but iterates across sites. Returns per-site + grand-total summary. Dry-run first; second call applies. Use sparingly \u2014 this is the nuclear option.",
+  inputSchema: z10.object({
+    find: z10.string().min(1),
+    replace: z10.string(),
+    site_ids: z10.array(z10.string()).optional().describe("Subset of sites to hit. Defaults to all."),
+    widget_type: z10.string().optional(),
+    case_sensitive: z10.boolean().default(false),
+    confirmation: z10.string().optional()
+  }),
+  outputSchema: z10.object({
+    mode: z10.enum(["dry_run", "applied"]),
+    sites_scanned: z10.number(),
+    total_match_count: z10.number(),
+    by_site: z10.array(z10.object({
+      site_id: z10.string(),
+      url: z10.string(),
+      pages_scanned: z10.number(),
+      matches: z10.number(),
+      error: z10.string().optional()
+    })),
+    confirmation_token: z10.string().optional(),
+    expires_in_seconds: z10.number().optional()
+  }),
+  annotations: { destructiveHint: true, idempotentHint: false, openWorldHint: true },
+  async handler(input) {
+    const cfg = loadConfig();
+    const targets = input.site_ids ? cfg.sites.filter((s) => input.site_ids?.includes(s.id)) : cfg.sites;
+    const by_site = [];
+    let total = 0;
+    for (const site of targets) {
+      try {
+        const pages = await listElementorPageIds(site.id);
+        let siteMatches = 0;
+        for (const p of pages) {
+          try {
+            const page = await wpRequest(`/wp/v2/pages/${p.id}?context=edit&_fields=meta`, { siteId: site.id });
+            const v = page.meta?._elementor_data;
+            const raw = typeof v === "string" ? v : JSON.stringify(v ?? []);
+            const data = parseElementorData(raw);
+            const dry = findReplaceInWidgets(JSON.parse(JSON.stringify(data)), input.find, input.replace, {
+              widgetType: input.widget_type,
+              caseSensitive: input.case_sensitive
+            });
+            siteMatches += dry.replacementCount;
+          } catch {
+          }
+        }
+        by_site.push({ site_id: site.id, url: site.url, pages_scanned: pages.length, matches: siteMatches });
+        total += siteMatches;
+      } catch (e) {
+        by_site.push({ site_id: site.id, url: site.url, pages_scanned: 0, matches: 0, error: e.message });
+      }
+    }
+    if (!input.confirmation) {
+      if (total === 0) {
+        return {
+          mode: "dry_run",
+          sites_scanned: by_site.length,
+          total_match_count: 0,
+          by_site
+        };
+      }
+      const token = issueConfirmation("fleet_find_replace", { find: input.find, replace: input.replace }, POLICIES.CONFIRMATION_TTL_SECONDS);
+      return {
+        mode: "dry_run",
+        sites_scanned: by_site.length,
+        total_match_count: total,
+        by_site,
+        confirmation_token: token,
+        expires_in_seconds: POLICIES.CONFIRMATION_TTL_SECONDS
+      };
+    }
+    const conf = consumeConfirmation(input.confirmation, "fleet_find_replace");
+    if (!conf) throw new Error("Invalid or expired confirmation token");
+    for (const site of targets) {
+      const pages = await listElementorPageIds(site.id);
+      for (const p of pages) {
+        try {
+          const page = await wpRequest(`/wp/v2/pages/${p.id}?context=edit&_fields=meta`, { siteId: site.id });
+          const v = page.meta?._elementor_data;
+          const raw = typeof v === "string" ? v : JSON.stringify(v ?? []);
+          const data = parseElementorData(raw);
+          const r = findReplaceInWidgets(data, input.find, input.replace, { widgetType: input.widget_type, caseSensitive: input.case_sensitive });
+          if (r.replacementCount === 0) continue;
+          const ser = serializeElementorData(data);
+          const validation = validateElementorData(ser);
+          if (!validation.valid) continue;
+          await fullBackup(site.id, p.id);
+          await wpRequest(`/wp/v2/pages/${p.id}`, {
+            siteId: site.id,
+            method: "PUT",
+            body: { meta: { _elementor_data: ser } }
+          });
+          await flushCSS(site.id, p.id);
+        } catch {
+        }
+      }
+    }
+    return {
+      mode: "applied",
+      sites_scanned: by_site.length,
+      total_match_count: total,
+      by_site
+    };
+  }
+});
+var restoreFromFileTool = defineTool({
+  name: "restore_from_file",
+  description: "Restore a page from a JSON backup file (created by ANY earlier op with backup_to_file=true or by direct fullBackup with to_file). Requires the file_path returned by that backup. Two-call confirmation.",
+  inputSchema: z10.object({
+    site_id: z10.string().optional(),
+    page_id: z10.number().int().positive(),
+    file_path: z10.string().min(1),
+    confirmation: z10.string().optional()
+  }),
+  outputSchema: z10.object({
+    mode: z10.enum(["dry_run", "restored"]),
+    page_id: z10.number(),
+    file_path: z10.string(),
+    method: z10.enum(["wp-cli", "rest"]).optional(),
+    pre_restore_backup_meta_key: z10.string().optional(),
+    css_flush: z10.string().optional(),
+    confirmation_token: z10.string().optional()
+  }),
+  annotations: { destructiveHint: true, idempotentHint: false, openWorldHint: true },
+  async handler(input) {
+    if (!input.confirmation) {
+      const token = issueConfirmation("restore_from_file", input, POLICIES.CONFIRMATION_TTL_SECONDS);
+      return {
+        mode: "dry_run",
+        page_id: input.page_id,
+        file_path: input.file_path,
+        confirmation_token: token
+      };
+    }
+    const conf = consumeConfirmation(input.confirmation, "restore_from_file");
+    if (!conf) throw new Error("Invalid or expired confirmation token");
+    const pre = await fullBackup(input.site_id, input.page_id);
+    const r = await restoreFromFile(input.site_id, input.page_id, input.file_path);
+    const flush = await flushCSS(input.site_id, input.page_id);
+    return {
+      mode: "restored",
+      page_id: input.page_id,
+      file_path: input.file_path,
+      method: r.method,
+      pre_restore_backup_meta_key: pre.meta_key,
+      css_flush: flush.method
+    };
+  }
+});
+
 // src/tools/index.ts
 var tools = [
   // Sites & health
@@ -2131,11 +2982,23 @@ var tools = [
   listElementorBackupsTool,
   restoreElementorBackupTool,
   duplicateElementorPageTool,
+  // Widget-level CRUD (v1.1)
+  readWidgetTool,
+  updateWidgetSettingsTool,
+  deleteWidgetTool,
+  duplicateWidgetTool,
+  swapWidgetTypeTool,
+  addWidgetTool,
+  moveWidgetTool,
   // Templates
   listTemplatesTool,
   exportTemplateTool,
   importTemplateTool,
   applyTemplateToPageTool,
+  // Bulk + fleet (v1.1)
+  bulkFindReplaceSiteTool,
+  fleetFindReplaceTool,
+  restoreFromFileTool,
   // WP-CLI escape
   wpCliRunTool,
   wpSearchReplaceTool,