@respira/wordpress-mcp-server 7.6.1 → 8.0.0

package/dist/wordpress-client.js

@@ -13,6 +13,63 @@ import { randomUUID } from 'node:crypto';
 import { getRespiraAgentHeaders } from './agent-signature.js';
 import { CONFIG_FILE, isTlsInsecureEnv } from './config.js';
 import { makeHttpsAgent } from './system-ca.js';
+/** `C:\...` or `C:/...`. Windows drive-letter absolute path. */
+const WINDOWS_DRIVE_PATH_RE = /^[a-zA-Z]:[\\/]/;
+/**
+ * Does this string name a file on the caller's own disk, as opposed to a URL,
+ * a data: URI, or a bare base64 blob?
+ *
+ * Matches POSIX absolute (`/home/...`), relative (`./`, `../`), home-relative
+ * (`~/...`), Windows drive-letter (`C:\...`, `C:/...`), and `file://` URIs
+ * (`file:///C:/Users/...` on Windows, `file:///home/...` on Unix). The caller
+ * converts `file://` to a real path with `resolveLocalFilePath()` below.
+ *
+ * The Windows and `file://` arms are why this is a named helper rather than an
+ * inline condition. Without them those inputs fall through to the base64
+ * branch, where they do not error: they decode to garbage and upload as a
+ * corrupt file. Silent, not loud.
+ *
+ * Not handled: Windows UNC paths (`\\server\share\file.jpg`). They do not
+ * reproduce the same way, since backslashes are not valid base64 characters,
+ * but they are not read as a local file either. Out of scope until a UNC
+ * report comes in.
+ */
+export function isLocalFilePath(file) {
+    return (file.startsWith('/') ||
+        file.startsWith('./') ||
+        file.startsWith('../') ||
+        file.startsWith('~') ||
+        WINDOWS_DRIVE_PATH_RE.test(file) ||
+        file.startsWith('file://'));
+}
+/**
+ * Turns an `isLocalFilePath()`-matched string into a real filesystem path.
+ * Handles `file://` URIs (unwrapping via `fileURLToPath`, forcing Windows
+ * semantics when the URI's own path looks like a drive letter, so the
+ * conversion is correct even when the MCP server process itself is running on
+ * a non-Windows host), `~` home-dir expansion, and relative-path resolution
+ * against cwd.
+ *
+ * Windows drive-letter absolute paths are returned as-is rather than run
+ * through `resolve()`: they are already absolute, and POSIX `resolve()` does
+ * not recognise a drive letter as an absolute-path marker, so calling it on a
+ * non-Windows host would wrongly prefix the string with cwd. On the Windows
+ * machine where such a path is real, `fs` accepts it verbatim.
+ */
+export function resolveLocalFilePath(file) {
+    let input = file;
+    if (file.startsWith('file://')) {
+        const looksWindows = WINDOWS_DRIVE_PATH_RE.test(new URL(file).pathname.replace(/^\//, ''));
+        input = looksWindows ? fileURLToPath(file, { windows: true }) : fileURLToPath(file);
+    }
+    if (input.startsWith('~')) {
+        return input.replace(/^~/, process.env.HOME || '');
+    }
+    if (WINDOWS_DRIVE_PATH_RE.test(input)) {
+        return input;
+    }
+    return resolve(input);
+}
 const MCP_CLIENT_VERSION = (() => {
     try {
         const currentDir = dirname(fileURLToPath(import.meta.url));
@@ -60,67 +117,6 @@ export function isReplaySafeRetry(args) {
     }
     return safe && !!args.connectionCode && RETRYABLE_CONNECTION_CODES.has(args.connectionCode);
 }
-// Windows drive-letter absolute path, e.g. `C:\Users\bob\photo.jpg` or `C:/Users/bob/photo.jpg`.
-const WINDOWS_DRIVE_PATH_RE = /^[A-Za-z]:[\\/]/;
-/**
- * True when `file` (the `file` argument to `uploadMedia`) looks like a local
- * filesystem path rather than a base64 blob or a `data:`/`http(s):` URL.
- *
- * Historically this only matched POSIX-style paths (`/`, `./`, `../`, `~`),
- * so a Windows absolute path like `C:/Users/bob/photo.jpg` — which starts
- * with none of those — fell through to the base64 branch. `Buffer.from(file,
- * 'base64')` doesn't throw on non-base64 input; it silently decodes whatever
- * valid base64 characters happen to appear (mostly none, for a path like
- * that) and produces a few garbage bytes instead of an error, so the upload
- * "succeeds" with a corrupt file. See ticket 5a19d816.
- *
- * Also matches `file://` URIs (`file:///C:/Users/...` on Windows,
- * `file:///home/...` on Unix); the caller converts these to a real path with
- * `fileURLToPath` before reuse of the existing local-file-read logic below.
- *
- * Not handled: Windows UNC paths (`\\server\share\file.jpg`). They don't
- * reproduce this bug — backslashes aren't valid base64 characters, so they'd
- * still fall into the base64 branch but wouldn't "succeed" quietly the same
- * way — but they also aren't read as a local file today. Out of scope for
- * this fix; revisit if a UNC-specific report comes in.
- */
-export function isLocalFilePath(file) {
-    return (file.startsWith('/') ||
-        file.startsWith('./') ||
-        file.startsWith('../') ||
-        file.startsWith('~') ||
-        WINDOWS_DRIVE_PATH_RE.test(file) ||
-        file.startsWith('file://'));
-}
-/**
- * Turns an `isLocalFilePath()`-matched string into a real filesystem path.
- * Handles `file://` URIs (unwrapping via `fileURLToPath`, forcing Windows
- * semantics when the URI's own path looks like a drive letter so this
- * converts correctly even when the MCP server process itself is running on
- * a non-Windows host), `~` home-dir expansion, and relative-path resolution
- * against cwd.
- *
- * Windows drive-letter absolute paths (`C:\...`, `C:/...`) are returned
- * as-is rather than run through `resolve()`: they're already absolute, and
- * POSIX `resolve()` does not recognize a drive letter as an absolute-path
- * marker, so calling it on a non-Windows host (e.g. this test suite) would
- * wrongly prefix the string with `cwd`. On the Windows machine where such a
- * path is actually real, `fs` calls accept it verbatim.
- */
-export function resolveLocalFilePath(file) {
-    let input = file;
-    if (file.startsWith('file://')) {
-        const looksWindows = WINDOWS_DRIVE_PATH_RE.test(new URL(file).pathname.replace(/^\//, ''));
-        input = looksWindows ? fileURLToPath(file, { windows: true }) : fileURLToPath(file);
-    }
-    if (input.startsWith('~')) {
-        return input.replace(/^~/, process.env.HOME || '');
-    }
-    if (WINDOWS_DRIVE_PATH_RE.test(input)) {
-        return input;
-    }
-    return resolve(input);
-}
 export class WordPressClient {
     client;
     rootClient;
@@ -872,10 +868,10 @@ export class WordPressClient {
                         : 'The site returned an HTML error page instead of a WordPress REST API response. ' +
                             'A firewall, CDN, or maintenance mode may be blocking API access. ' +
                             'Verify that ' + this.siteConfig.url + '/wp-json/respira/v1/context/site-info is accessible in your browser.';
-                    return new Error(`Site not reachable: ${this.siteConfig.url} returned a ${status} response from the web server (not WordPress).\n\n${hint}`);
+                    return this.codedError(`Site not reachable: ${this.siteConfig.url} returned a ${status} response from the web server (not WordPress).\n\n${hint}`, 'http_401_non_wordpress');
                 }
                 const reason = data?.message || data?.code || 'Invalid API key';
-                const authError = new Error(`Authentication failed: ${reason}`);
+                const authError = this.codedError(`Authentication failed: ${reason}`, typeof data?.code === 'string' && data.code ? data.code : 'http_401', data);
                 // Same rationale as in formatErrorWithInstructions / the generic
                 // catch-all below: stamp the WP_Error code (respira_invalid_site_token,
                 // respira_token_stale, license_inactive, ...) onto error.name so
@@ -887,56 +883,47 @@ export class WordPressClient {
                 // its machine-readable code the moment it crossed into the npm
                 // server — telemetry only recorded the tool name, not why it failed.
                 // Ticket fc4fa49e.
-                if (typeof data?.code === 'string' && data.code) {
-                    authError.name = data.code.slice(0, 80);
-                }
                 return authError;
             }
             else if (status === 429) {
-                return new Error(`Rate limit exceeded. Please wait before making more requests.`);
+                return this.codedError('Rate limit exceeded. Please wait before making more requests.', typeof data?.code === 'string' && data.code ? data.code : 'http_429', data);
             }
             else if (status === 403) {
                 if (isNonWordPressResponse) {
-                    return new Error(`Site blocked: ${this.siteConfig.url} returned a 403 Forbidden from the web server (not WordPress).\n\n` +
+                    return this.codedError(`Site blocked: ${this.siteConfig.url} returned a 403 Forbidden from the web server (not WordPress).\n\n` +
                         'A firewall, security plugin (e.g. Wordfence, Sucuri), or CDN rule is blocking REST API requests. ' +
-                        'Whitelist the /wp-json/respira/* path or the MCP server\'s User-Agent in your security settings.');
+                        'Whitelist the /wp-json/respira/* path or the MCP server\'s User-Agent in your security settings.', 'http_403_non_wordpress');
                 }
                 // Format error with instructions if available
                 return this.formatErrorWithInstructions(data);
             }
             else if (status >= 500) {
                 if (isNonWordPressResponse) {
-                    return new Error(`Server error: ${this.siteConfig.url} returned a ${status} error from the web server (not WordPress).\n\n` +
+                    return this.codedError(`Server error: ${this.siteConfig.url} returned a ${status} error from the web server (not WordPress).\n\n` +
                         'The site may be down, misconfigured, or behind a proxy that is failing. ' +
-                        'Check that the site loads normally in a browser first.');
+                        'Check that the site loads normally in a browser first.', `http_${status}_non_wordpress`);
                 }
                 const serverDetails = this.extractServerErrorDetails(data);
                 const message = data?.message || 'Internal server error';
                 const detailsSuffix = serverDetails ? `\n\nDebug details: ${serverDetails}` : '';
-                return new Error(`WordPress server error (${status}): ${message}${detailsSuffix}`);
+                return this.codedError(`WordPress server error (${status}): ${message}${detailsSuffix}`, typeof data?.code === 'string' && data.code ? data.code : `http_${status}`, data);
             }
             // Check if error has instructions data
             if (data?.data && (data.data.instructions || data.data.links)) {
                 return this.formatErrorWithInstructions(data);
             }
             if (isNonWordPressResponse) {
-                return new Error(`Unexpected response: ${this.siteConfig.url} returned HTTP ${status} with an HTML page instead of a WordPress REST API response.\n\n` +
+                return this.codedError(`Unexpected response: ${this.siteConfig.url} returned HTTP ${status} with an HTML page instead of a WordPress REST API response.\n\n` +
                     'The Respira plugin may not be active, the REST API may be disabled, or a proxy/firewall is intercepting requests. ' +
-                    'Verify that ' + this.siteConfig.url + '/wp-json/respira/v1/context/site-info is accessible in your browser.');
+                    'Verify that ' + this.siteConfig.url + '/wp-json/respira/v1/context/site-info is accessible in your browser.', `http_${status}_non_wordpress`);
             }
-            const apiError = new Error(`API error (${status}): ${data?.message || error.message}`);
+            const apiError = this.codedError(`API error (${status}): ${data?.message || error.message}`, typeof data?.code === 'string' && data.code ? data.code : `http_${status}`, data);
             // Promote the WP_Error code (e.g. 'respira_no_builder',
             // 'respira_element_not_found') to error.name so the MCP usage emitter
             // records something diagnostic instead of the literal 'Error'. Without
             // this, every WP-side failure collapses to error_code='Error' in
             // mcp_tool_events and the admin/mcp-quality dashboard cannot tell
             // 'wrong target' from 'no builder detected' from 'permission denied'.
-            if (typeof data?.code === 'string' && data.code) {
-                apiError.name = data.code.slice(0, 80);
-            }
-            else {
-                apiError.name = `http_${status}`;
-            }
             // v6.21.2: preserve the structured WP_Error envelope so the agent sees
             // the rich fields (missing_args, required_path_keys, hint, instructions,
             // registered_abilities_sample, destructive_tools, available_types, ...).
@@ -948,26 +935,6 @@ export class WordPressClient {
             // Attach the WP wire envelope as a non-enumerable property on the
             // Error so server.ts can surface it in the tool result without
             // accidentally duplicating fields the message already carries.
-            const errorEnvelope = {};
-            if (typeof data?.code === 'string')
-                errorEnvelope.code = data.code;
-            if (data?.data && typeof data.data === 'object') {
-                // Spread the structured fields. `status` would duplicate the HTTP code,
-                // skip it.
-                for (const [k, v] of Object.entries(data.data)) {
-                    if (k === 'status')
-                        continue;
-                    errorEnvelope[k] = v;
-                }
-            }
-            if (Object.keys(errorEnvelope).length > 0) {
-                Object.defineProperty(apiError, 'respiraErrorEnvelope', {
-                    value: errorEnvelope,
-                    enumerable: false,
-                    configurable: false,
-                    writable: false,
-                });
-            }
             // v6.19.2: when WordPress reports rest_no_route, enrich the message
             // with the attempted HTTP method and request path. Without this,
             // the /mcp-quality dashboard sees the generic WP string "No route
@@ -1061,7 +1028,39 @@ export class WordPressClient {
                 netError.name = 'respira_write_outcome_unknown';
             return netError;
         }
-        return new Error(`Unknown error: ${error.message}`);
+        return this.codedError(`Unknown error: ${error.message}`, 'unknown_error');
+    }
+    /**
+     * Create a telemetry-safe Error while preserving the structured WP_Error
+     * envelope. Every HTTP/proxy/upstream branch must use this helper so useful
+     * PageSpeed and hosting failures never collapse into `<tool>_unclassified`.
+     */
+    codedError(message, code, data) {
+        const coded = new Error(message);
+        const safeCode = String(code || 'unknown_error')
+            .toLowerCase()
+            .replace(/[^a-z0-9_:-]/g, '_')
+            .slice(0, 80);
+        coded.name = safeCode || 'unknown_error';
+        const errorEnvelope = {};
+        if (typeof data?.code === 'string' && data.code) {
+            errorEnvelope.code = data.code;
+        }
+        if (data?.data && typeof data.data === 'object') {
+            for (const [key, value] of Object.entries(data.data)) {
+                if (key !== 'status')
+                    errorEnvelope[key] = value;
+            }
+        }
+        if (Object.keys(errorEnvelope).length > 0) {
+            Object.defineProperty(coded, 'respiraErrorEnvelope', {
+                value: errorEnvelope,
+                enumerable: false,
+                configurable: false,
+                writable: false,
+            });
+        }
+        return coded;
     }
     /**
      * Extract concise server-side diagnostics from a failed WP response.
@@ -1279,6 +1278,10 @@ export class WordPressClient {
         const response = await this.client.get('/abilities/gap-report');
         return response.data;
     }
+    async searchAbilities(params) {
+        const response = await this.client.get('/abilities/search', { params: params || {} });
+        return response.data;
+    }
     /**
      * Invoke an inhaled ability via the Respira safety proxy.
      *
@@ -1550,8 +1553,22 @@ export class WordPressClient {
     /**
      * Replace the content of an existing Divi Theme Builder layout.
      */
+    /**
+     * `confirm_live_edit` is required by the plugin on the first call: a global
+     * layout rewrites every page that uses it and goes live with no staging step,
+     * so the first attempt is refused with `respira_tb_live_edit_confirmation_required`
+     * and the caller has to come back having acknowledged the blast radius.
+     *
+     * Threaded through only when the caller actually set it. Sending `false`
+     * explicitly is not the same as not answering, and the plugin reads both.
+     */
     async updateThemeBuilderTemplate(args) {
-        const response = await this.client.post(`/divi/theme-builder/template/${args.layout_id}`, { structure: args.structure });
+        const response = await this.client.post(`/divi/theme-builder/template/${args.layout_id}`, {
+            structure: args.structure,
+            ...(args.confirm_live_edit === undefined
+                ? {}
+                : { confirm_live_edit: args.confirm_live_edit }),
+        });
         return response.data;
     }
     /**
@@ -2690,32 +2707,11 @@ export class WordPressClient {
         }
         if (restRouteFallbackWorked) {
             this.lastRestRouteFallbackWorked = true;
-            // Ticket 73b64e82: these probes run over a bare `axios.request()` (see
-            // the `probe()` helper above), not through `this.client`/`this.rootClient`,
-            // so they never pass through the response interceptor that normally
-            // trips the sticky `useRestRouteFallback` flag on a real tool call
-            // (see the success interceptor installed in the constructor, a few
-            // hundred lines up). Without this, diagnoseConnection would *report*
-            // `rest_route_fallback_worked: true` while every subsequent normal tool
-            // call (get_builder_info, list_pages, ...) kept retrying the doomed
-            // pretty path from scratch on this client instance — forcing the user
-            // to hand-set `forceRestRoute: true` even though the diagnostic had
-            // already proven the fallback works. Flip the same flag a real
-            // tool-call fallback would, so the diagnostic's finding actually
-            // sticks for the rest of the session instead of just being reported.
-            if (!this.useRestRouteFallback) {
-                this.useRestRouteFallback = true;
-                if (!this.restRouteFallbackWarned) {
-                    this.restRouteFallbackWarned = true;
-                    process.stderr.write(`[respira-mcp] Site ${this.siteConfig.name} has REST rewrite shadowing; ` +
-                        `falling back to ?rest_route= for this session (confirmed by wordpress_diagnose_connection).\n`);
-                }
-            }
             recommendations.push('Pretty `/wp-json/respira/...` path returned HTML but `?rest_route=/respira/...` returned JSON. ' +
                 'A plugin or theme rewrite rule is shadowing `/wp-json/[anything]` and triggering ' +
                 'WordPress `redirect_canonical()` (look for `x-redirect-by: WordPress` on the 301). ' +
-                'This session has switched to `?rest_route=` automatically — set ' +
-                '`forceRestRoute: true` in the site config to make that permanent and skip this probe on future connects.');
+                'The MCP server will auto-fall-back to `?rest_route=` for this session — set ' +
+                '`forceRestRoute: true` in the site config to skip the pretty-permalink probe entirely.');
         }
         return {
             success: true,
@@ -2847,8 +2843,12 @@ export class WordPressClient {
      * Activate a plugin (EXPERIMENTAL). Approval-gated; echo approval_token
      * back on the second call with the same slug to complete.
      */
-    async activatePlugin(slug, approvalToken) {
-        const body = approvalToken ? { approval_token: approvalToken } : undefined;
+    async activatePlugin(slug, approvalToken, forceWithoutProbe) {
+        const body = {};
+        if (approvalToken)
+            body.approval_token = approvalToken;
+        if (forceWithoutProbe)
+            body.force_without_probe = true;
         const response = await this.client.post(`/plugins/${slug}/activate`, body);
         return response.data;
     }
@@ -3106,13 +3106,14 @@ export class WordPressClient {
         return response.data;
     }
     /**
-     * Delete a media attachment. Approval-gated since v7.1.0-beta.1: the
-     * first call comes back with `code: respira_approval_required` and a
-     * fresh `approval_token`; the caller re-sends the same id with that
-     * token to confirm. Ticket 927aa7ed — this method used to only forward
-     * `id`, silently dropping `force` and `approvalToken`, so the WP side
-     * never saw a token on the "confirm" call and looped forever minting
-     * new ones. Mirrors `deletePage`'s params shape (see comment above it).
+     * `force` skips the trash and deletes permanently. `approvalToken` carries a
+     * governance approval back to the plugin on the retry after a first call was
+     * refused.
+     *
+     * Both are optional and, as of 8.0, no caller in server.ts passes either:
+     * the delete_media tool schema does not expose them. The parameters are kept
+     * because they are the shipped signature and the plugin route accepts them.
+     * Wiring the tool schema is a separate change, not a release-eve one.
      */
     async deleteMedia(id, force, approvalToken) {
         const params = {};
@@ -3348,6 +3349,15 @@ export class WordPressClient {
         const response = await this.client.post('/woocommerce/storefront/update-checkout-layout', data);
         return response.data;
     }
+    // WooCommerce Add-on 8.0: product-card field addressing
+    async woocommerceAnalyzeStorefrontCard(params) {
+        const response = await this.client.get('/woocommerce/storefront/analyze-card', { params: params || {} });
+        return response.data;
+    }
+    async woocommerceUpdateStorefrontCardField(data) {
+        const response = await this.client.post('/woocommerce/storefront/update-card-field', data);
+        return response.data;
+    }
     // WooCommerce Add-on v3.0 — variations and attributes
     async woocommerceSetProductAttributes(id, data) {
         const response = await this.client.post(`/woocommerce/products/${id}/attributes`, data);
@@ -3524,6 +3534,10 @@ export class WordPressClient {
         const response = await this.client.get('/woocommerce/feeds/status');
         return response.data;
     }
+    async woocommerceRepairFeedScheduler(data) {
+        const response = await this.client.post('/woocommerce/feeds/repair', data || {});
+        return response.data;
+    }
     async woocommerceValidateFeed(params) {
         const response = await this.client.get('/woocommerce/feeds/validate', { params: params || {} });
         return response.data;