@respira/wordpress-mcp-server 8.3.4 → 8.3.6

package/dist/wordpress-client.js

@@ -163,24 +163,75 @@ export function isReplaySafeRetry(args) {
  * Reported, root-caused and verified live against a real write by O.Q.
  */
 const PUT_FALLBACK_STATUSES = new Set([403, 404, 405]);
+/**
+ * Header the fallback POST carries so the plugin can dedupe it against the PUT
+ * it is replacing.
+ *
+ * The plugin's idempotency cache key and request fingerprint both include the
+ * HTTP method (`class-respira-mcp-reliability.php`, `cache_key()` /
+ * `request_fingerprint()`). Without this header a PUT that DID reach PHP and
+ * executed, and whose response was then dropped on the way back, would land in
+ * a different dedupe bucket than the fallback POST — and `update_post` is not
+ * idempotent in every branch (the duplicate-first path mints a draft duplicate
+ * on an original post). The plugin keys on the declared original method when
+ * this header is present, so PUT-then-fallback-POST with one Idempotency-Key
+ * dedupes to exactly one execution.
+ */
+export const ORIGINAL_METHOD_HEADER = 'X-Respira-Original-Method';
+/**
+ * Transport failures that mean "the PUT never came back", as opposed to "the
+ * host is not there at all".
+ *
+ * A strict subset of RETRYABLE_CONNECTION_CODES on purpose. ECONNREFUSED,
+ * ENOTFOUND, EHOSTUNREACH and friends say nothing reached a listening socket,
+ * so the HTTP verb cannot be the discriminator and a fallback POST would only
+ * burn a second timeout. These three are the shapes a verb-level drop takes:
+ * the client-side timeout firing (ECONNABORTED, which is what axios raises on
+ * `timeout`), the OS timing the connection out (ETIMEDOUT), or the edge
+ * closing it (ECONNRESET).
+ */
+const PUT_FALLBACK_CONNECTION_CODES = new Set(['ECONNABORTED', 'ETIMEDOUT', 'ECONNRESET']);
 /**
  * Should this failed PUT be retried as a POST?
  *
- * Two shapes have to be recognised, which is what made the first attempt at
- * this fix useless. The response interceptor rewrites a 403 that did not come
- * from WordPress into a friendly coded Error and does NOT carry `response`
- * across, so a plain `error.response?.status === 403` check never fires on the
- * exact case this exists for. Verified live against a host shim returning 403
- * on PUT: the status-only check still failed the write.
+ * Three shapes have to be recognised.
  *
- * `http_403_non_wordpress` is deliberately the only coded name accepted. A 403
- * raised BY WordPress is a real permission decision and retrying it as a POST
- * would just fail again more slowly.
+ * 1. A status in PUT_FALLBACK_STATUSES.
+ *
+ * 2. `http_403_non_wordpress`. The response interceptor rewrites a 403 that did
+ *    not come from WordPress into a friendly coded Error and does NOT carry
+ *    `response` across, so a plain `error.response?.status === 403` check never
+ *    fires on the exact case this exists for — which is what made the first
+ *    attempt at this fix useless. A 403 raised BY WordPress is a real
+ *    permission decision and is deliberately still not retried.
+ *
+ * 3. No response at all, plus a connection code that means the request was
+ *    dropped rather than answered. This is the third way the same host
+ *    behaviour arrives, and it was the one gap left: a host can DROP PUT
+ *    instead of rejecting it, holding the connection until the connector's own
+ *    timeout fires. There is no status, so (1) never matched; the error is
+ *    rebuilt by handleError as `respira_write_outcome_unknown`, so (2) never
+ *    matched either, and the fallback that would have fixed the write was never
+ *    reached. `respira_update_post` then hung forever while `respira_read_post`
+ *    (GET) and `respira_create_post_duplicate` (POST) worked, because the verb
+ *    was the only difference between them. Reported by O.Q. on
+ *    linvestisseurantifragile.com (Apache), 3/3 reproducible on two posts;
+ *    ticket e2d884cb. Same host, one behaviour further on, as ticket 2b3a706b.
+ *
+ * The retry is bounded to exactly one POST at every call site: no loop, no
+ * second PUT. The fallback POST reuses the PUT's Idempotency-Key and declares
+ * ORIGINAL_METHOD_HEADER, so if the dropped PUT had in fact executed
+ * server-side the plugin replays the stored response instead of running the
+ * write a second time.
  */
 export function isRetryableAsPost(error) {
     if (PUT_FALLBACK_STATUSES.has(error?.response?.status))
         return true;
-    return error?.name === 'http_403_non_wordpress';
+    if (error?.name === 'http_403_non_wordpress')
+        return true;
+    if (error?.response)
+        return false;
+    return PUT_FALLBACK_CONNECTION_CODES.has(String(error?.code || '').toUpperCase());
 }
 /**
  * Classify a failed v2 status probe.
@@ -979,6 +1030,52 @@ export class WordPressClient {
     getVersionWarning() {
         return this.versionWarning;
     }
+    /**
+     * Send a Respira write as PUT, falling back to POST once if the PUT is
+     * rejected or dropped by something in front of WordPress.
+     *
+     * Every PUT write in this client goes through here so the three properties
+     * that make the fallback safe hold in one place rather than at seven call
+     * sites:
+     *
+     * - **Exactly one POST attempt, and never a second PUT.** No loop. The
+     *   response interceptor's own retry ladder (`isReplaySafeRetry`) refuses to
+     *   repeat unsafe methods on a connection failure, so this does not stack on
+     *   top of it and a single tool call cannot fan out into many requests.
+     * - **One Idempotency-Key for both attempts.** The key is minted here rather
+     *   than by the request interceptor, which would mint a fresh one per
+     *   request and put the two attempts in different dedupe buckets.
+     * - **The POST declares ORIGINAL_METHOD_HEADER: PUT.** The plugin keys its
+     *   idempotency cache and fingerprint on the declared original method, so a
+     *   PUT that reached PHP and executed before its response was dropped is
+     *   replayed from cache instead of running a second time. That matters
+     *   because `update_post` is not idempotent in every branch: on an original
+     *   post the duplicate-first path mints a draft duplicate.
+     *
+     * `forceWriteMethod: 'post'` on the site config skips the PUT entirely, for
+     * hosts already known to drop it (support can set it without a plugin
+     * change). Ticket e2d884cb.
+     */
+    async putWithPostFallback(client, url, data) {
+        const callId = randomUUID();
+        const firstAttempt = { headers: { 'Idempotency-Key': callId } };
+        const fallbackAttempt = {
+            headers: { 'Idempotency-Key': callId, [ORIGINAL_METHOD_HEADER]: 'PUT' },
+        };
+        if (this.siteConfig.forceWriteMethod === 'post') {
+            // No PUT was sent, so there is no earlier attempt to alias onto: a plain
+            // POST with its own key is the whole request.
+            return client.post(url, data, firstAttempt);
+        }
+        try {
+            return await client.put(url, data, firstAttempt);
+        }
+        catch (error) {
+            if (!isRetryableAsPost(error))
+                throw error;
+            return client.post(url, data, fallbackAttempt);
+        }
+    }
     /**
      * Generic v1 REST caller for endpoints under /wp-json/respira/v1/.
      * Mirror of callRestV2 but for the existing v1 surface — useful for new tools
@@ -991,17 +1088,8 @@ export class WordPressClient {
      */
     async callRestV1(method, path, data) {
         if (method === 'PUT') {
-            try {
-                const response = await this.client.put(path, data);
-                return response.data;
-            }
-            catch (error) {
-                if (isRetryableAsPost(error)) {
-                    const response = await this.client.post(path, data);
-                    return response.data;
-                }
-                throw error;
-            }
+            const response = await this.putWithPostFallback(this.client, path, data);
+            return response.data;
         }
         const response = method === 'GET'
             ? await this.client.get(path, { params: data })
@@ -1041,17 +1129,8 @@ export class WordPressClient {
         await this.ensureV2();
         const url = `/wp-json/respira/v2${path}`;
         if (method === 'PUT') {
-            try {
-                const response = await this.rootClient.put(url, data);
-                return response.data;
-            }
-            catch (error) {
-                if (isRetryableAsPost(error)) {
-                    const response = await this.rootClient.post(url, data);
-                    return response.data;
-                }
-                throw error;
-            }
+            const response = await this.putWithPostFallback(this.rootClient, url, data);
+            return response.data;
         }
         const response = method === 'GET'
             ? await this.rootClient.get(url, { params: data })
@@ -1388,6 +1467,14 @@ export class WordPressClient {
             netError.name = errorName;
             if (isAmbiguousWrite)
                 netError.name = 'respira_write_outcome_unknown';
+            // Carry the transport code across the rewrite. Without this the original
+            // ECONNABORTED/ETIMEDOUT/ECONNRESET is the one thing this branch throws
+            // away, and for a write `errorName` is then overwritten with the generic
+            // `respira_write_outcome_unknown` — so a dropped PUT arrived at the
+            // PUT->POST fallback with no response, no status and no code, and looked
+            // exactly like an unrecoverable failure. Ticket e2d884cb.
+            if (code)
+                netError.code = code;
             return netError;
         }
         return this.codedError(`Unknown error: ${error.message}`, 'unknown_error');
@@ -1721,33 +1808,9 @@ export class WordPressClient {
         }
         const version = await this.getApiVersion();
         // Try PUT first, fall back to POST for compatibility.
-        let response;
-        if (version === 'v2') {
-            try {
-                response = await this.rootClient.put(`/wp-json/respira/v2/pages/${id}`, payload);
-            }
-            catch (error) {
-                if (isRetryableAsPost(error)) {
-                    response = await this.rootClient.post(`/wp-json/respira/v2/pages/${id}`, payload);
-                }
-                else {
-                    throw error;
-                }
-            }
-        }
-        else {
-            try {
-                response = await this.client.put(`/pages/${id}`, payload);
-            }
-            catch (error) {
-                if (isRetryableAsPost(error)) {
-                    response = await this.client.post(`/pages/${id}`, payload);
-                }
-                else {
-                    throw error;
-                }
-            }
-        }
+        const response = version === 'v2'
+            ? await this.putWithPostFallback(this.rootClient, `/wp-json/respira/v2/pages/${id}`, payload)
+            : await this.putWithPostFallback(this.client, `/pages/${id}`, payload);
         // Check if duplicate was created and format message accordingly
         if (response.data.duplicate_created) {
             const duplicateId = response.data.duplicate_id;
@@ -1977,33 +2040,9 @@ export class WordPressClient {
             delete payload.appendTerms;
         }
         const version = await this.getApiVersion();
-        let response;
-        if (version === 'v2') {
-            try {
-                response = await this.rootClient.put(`/wp-json/respira/v2/posts/${id}`, payload);
-            }
-            catch (error) {
-                if (isRetryableAsPost(error)) {
-                    response = await this.rootClient.post(`/wp-json/respira/v2/posts/${id}`, payload);
-                }
-                else {
-                    throw error;
-                }
-            }
-        }
-        else {
-            try {
-                response = await this.client.put(`/posts/${id}`, payload);
-            }
-            catch (error) {
-                if (isRetryableAsPost(error)) {
-                    response = await this.client.post(`/posts/${id}`, payload);
-                }
-                else {
-                    throw error;
-                }
-            }
-        }
+        const response = version === 'v2'
+            ? await this.putWithPostFallback(this.rootClient, `/wp-json/respira/v2/posts/${id}`, payload)
+            : await this.putWithPostFallback(this.client, `/posts/${id}`, payload);
         // Check if duplicate was created and format message accordingly
         if (response.data.duplicate_created) {
             const duplicateId = response.data.duplicate_id;
@@ -3009,6 +3048,19 @@ export class WordPressClient {
         // signal that the edge is intercepting writes. Pretty path first; if the
         // rest_route fallback is in play, the auto-fallback covers writes too.
         await probe('respira_ping_options', 'OPTIONS', `${baseUrl}/wp-json/respira/v1/ping`);
+        // Probe 6 (ticket e2d884cb): the actual verb. OPTIONS alone was never
+        // enough. A host can allow OPTIONS and still drop PUT, and — the reason
+        // this probe exists — a host that drops PUT does not answer it at all, so
+        // there is no status to read and the old `typeof status === 'number'`
+        // guard silently graded the site as fine. That is exactly what
+        // O.Q.'s own diagnose_connection run reported while every
+        // respira_update_post against linvestisseurantifragile.com hung forever.
+        //
+        // Safe to send: /respira/v1/ping registers no EDITABLE handler, so a PUT
+        // that reaches WordPress comes back as a JSON 404 `rest_no_route` without
+        // touching anything. What is being measured is whether the verb reaches
+        // PHP at all, not whether the route exists.
+        await probe('respira_ping_put', 'PUT', `${baseUrl}/wp-json/respira/v1/ping`);
         // Plugin diagnostic — go through the standard client so we share auth and
         // pick up errors via the existing handler if the endpoint isn't routed.
         let pluginDiagnostic = null;
@@ -3074,17 +3126,83 @@ export class WordPressClient {
         const optionsBlocked = !!optionsProbe &&
             typeof optionsProbe.status === 'number' &&
             optionsProbe.status >= 400;
-        const writeMethodBlocked = getOk && optionsBlocked;
-        if (writeMethodBlocked) {
+        // Ticket e2d884cb. A probe that never came back has no `status` field, so
+        // `typeof status === 'number'` is false and the old single boolean reported
+        // write_method_blocked: false — the diagnostic read green precisely when
+        // the site was broken. A dropped request is not a passing request. Three
+        // states now: proven blocked, proven reachable, and unknown.
+        const putProbe = probes.find((p) => p.label === 'respira_ping_put');
+        const probeDropped = (p) => !!p &&
+            typeof p.status !== 'number' &&
+            PUT_FALLBACK_CONNECTION_CODES.has(String(p.code || '').toUpperCase());
+        const putDropped = probeDropped(putProbe);
+        const optionsDropped = probeDropped(optionsProbe);
+        // A JSON answer means the verb reached WordPress, whatever the status:
+        // /ping has no PUT handler, so `rest_no_route` 404 is the healthy result.
+        // An HTML 4xx/5xx is something in front of WordPress answering instead.
+        const putReachedWordPress = !!putProbe && typeof putProbe.status === 'number' && putProbe.looks_like_html === false;
+        const putBlockedAtEdge = !!putProbe && typeof putProbe.status === 'number' && putProbe.status >= 400 && !putReachedWordPress;
+        const writeMethodVerdict = (() => {
+            // If plain GET is not healthy, nothing can be concluded about writes
+            // specifically — the whole connection is the problem.
+            if (!getOk)
+                return 'unknown';
+            if (optionsBlocked || putBlockedAtEdge)
+                return 'blocked';
+            if (putDropped || optionsDropped)
+                return 'unknown';
+            if (putReachedWordPress)
+                return 'not_blocked';
+            return 'unknown';
+        })();
+        // Kept as a tri-state boolean rather than a string so an existing truthiness
+        // check still means "proven blocked" and never accidentally fires on the
+        // unknown case. null = could not tell.
+        const writeMethodBlocked = writeMethodVerdict === 'blocked' ? true : writeMethodVerdict === 'not_blocked' ? false : null;
+        const forceWriteMethodHint = ' Unblock this connection immediately without touching the host: add ' +
+            `"forceWriteMethod": "post" to the site object in ${CONFIG_FILE}. The Respira plugin ` +
+            'registers the same handler on PUT and POST for every updatable resource, so POST does ' +
+            'identical work and the connector stops sending PUT at all. Fixing the host is still the ' +
+            'better end state, this just stops the bleeding.';
+        if (writeMethodVerdict === 'unknown' && (putDropped || optionsDropped)) {
+            const droppedLabel = putDropped ? 'PUT' : 'OPTIONS';
+            const droppedCode = String((putDropped ? putProbe : optionsProbe)?.code || 'no response');
+            recommendations.push(`${droppedLabel} /wp-json/respira/v1/ping was DROPPED (${droppedCode}) while GET returned 2xx. ` +
+                'The request was never answered, not even with an error, so this diagnostic cannot prove the ' +
+                'verb is blocked and will not claim it is fine either. A silent drop of PUT is the known ' +
+                'fingerprint of an Apache `<LimitExcept GET POST>` block, a ModSecurity rule, or a WAF that ' +
+                'discards non-GET methods instead of rejecting them. It is also what a plain overloaded origin ' +
+                'looks like, so check both: retry with a longer probe_timeout_ms, and ask the host whether ' +
+                'PUT/PATCH/DELETE are allowed for /wp-json/respira/*. Symptom to expect meanwhile: reads and ' +
+                'create/duplicate work while every update hangs until it times out, because those are the only ' +
+                'calls that use PUT.' +
+                forceWriteMethodHint);
+        }
+        if (writeMethodVerdict === 'unknown' && !putDropped && !optionsDropped && getOk) {
+            recommendations.push('Write-method state is unknown: the PUT probe did not come back with a readable answer. ' +
+                'Re-run with a larger probe_timeout_ms before drawing any conclusion about writes.');
+        }
+        if (writeMethodVerdict === 'blocked') {
             const status = optionsProbe?.status ?? '4xx';
-            if (edgeLayerDetected === 'cloudflare') {
-                recommendations.push(`OPTIONS /wp-json/respira/v1/ping returned ${status} while GET returned 2xx, and Cloudflare is in front of the site (cf-ray header present). The edge is blocking non-GET methods before the request reaches WordPress — every Respira write (update_page, update_element, inject_builder_content, delete_page) will fail at the edge with no plugin-side trace. Append \`and not (http.request.uri.path contains "/wp-json/respira/")\` to the CF WAF / Custom Rule that matches non-GET methods (commonly named "Bad Bot - Action Block" or similar), or add a Skip rule for /wp-json/respira/* that bypasses the Managed Rules + Custom Rules phases.`);
+            if (putBlockedAtEdge && !optionsBlocked) {
+                recommendations.push(`PUT /wp-json/respira/v1/ping returned ${putProbe?.status} from something that is not WordPress ` +
+                    '(the body was not JSON) while GET returned 2xx and OPTIONS was allowed. The edge blocks the PUT ' +
+                    'verb specifically, so every Respira update fails while reads and create/duplicate succeed. ' +
+                    'Allow PUT/PATCH/DELETE for /wp-json/respira/* on the layer in front of WordPress ' +
+                    '(Apache <LimitExcept>, ModSecurity, CDN or WAF rule).' +
+                    forceWriteMethodHint);
             }
-            else if (edgeLayerDetected === 'wordfence') {
-                recommendations.push(`OPTIONS /wp-json/respira/v1/ping returned ${status} while GET returned 2xx. Wordfence is in front of the site and is blocking non-GET methods to Respira routes. In Wordfence > Firewall > All Firewall Options > Whitelisted URLs, add /wp-json/respira/.* and re-run.`);
+            if (optionsBlocked && edgeLayerDetected === 'cloudflare') {
+                recommendations.push(`OPTIONS /wp-json/respira/v1/ping returned ${status} while GET returned 2xx, and Cloudflare is in front of the site (cf-ray header present). The edge is blocking non-GET methods before the request reaches WordPress — every Respira write (update_page, update_element, inject_builder_content, delete_page) will fail at the edge with no plugin-side trace. Append \`and not (http.request.uri.path contains "/wp-json/respira/")\` to the CF WAF / Custom Rule that matches non-GET methods (commonly named "Bad Bot - Action Block" or similar), or add a Skip rule for /wp-json/respira/* that bypasses the Managed Rules + Custom Rules phases.` +
+                    forceWriteMethodHint);
             }
-            else {
-                recommendations.push(`OPTIONS /wp-json/respira/v1/ping returned ${status} while GET returned 2xx. An edge layer or origin firewall is blocking non-GET methods to Respira routes — every Respira write will fail at the edge with no plugin-side trace. Identify the layer (check CDN, WAF, .htaccess <LimitExcept GET POST>, ModSecurity rules) and allow PUT/PATCH/DELETE/OPTIONS for /wp-json/respira/*.`);
+            else if (optionsBlocked && edgeLayerDetected === 'wordfence') {
+                recommendations.push(`OPTIONS /wp-json/respira/v1/ping returned ${status} while GET returned 2xx. Wordfence is in front of the site and is blocking non-GET methods to Respira routes. In Wordfence > Firewall > All Firewall Options > Whitelisted URLs, add /wp-json/respira/.* and re-run.` +
+                    forceWriteMethodHint);
+            }
+            else if (optionsBlocked) {
+                recommendations.push(`OPTIONS /wp-json/respira/v1/ping returned ${status} while GET returned 2xx. An edge layer or origin firewall is blocking non-GET methods to Respira routes — every Respira write will fail at the edge with no plugin-side trace. Identify the layer (check CDN, WAF, .htaccess <LimitExcept GET POST>, ModSecurity rules) and allow PUT/PATCH/DELETE/OPTIONS for /wp-json/respira/*.` +
+                    forceWriteMethodHint);
             }
         }
         if (restRouteFallbackWorked) {
@@ -3113,7 +3231,21 @@ export class WordPressClient {
             rest_route_fallback_worked: restRouteFallbackWorked,
             rest_route_fallback_active: this.useRestRouteFallback,
             force_rest_route_configured: this.siteConfig.forceRestRoute === true,
+            force_write_method_configured: this.siteConfig.forceWriteMethod ?? null,
+            // true = proven blocked, false = proven reachable, null = could not tell
+            // (the probe was dropped rather than answered). Read
+            // `write_method_verdict` for the named state; never treat null as false.
             write_method_blocked: writeMethodBlocked,
+            write_method_verdict: writeMethodVerdict,
+            write_method_probe: {
+                options_status: optionsProbe?.status ?? null,
+                options_dropped: optionsDropped,
+                put_status: putProbe?.status ?? null,
+                put_dropped: putDropped,
+                put_reached_wordpress: putReachedWordPress,
+                put_error: putProbe?.error ?? null,
+                put_error_code: putProbe?.code ?? null,
+            },
             target_post_id: opts.post_id ?? null,
             recommendations,
         };
@@ -3452,30 +3584,19 @@ export class WordPressClient {
         const version = await this.getApiVersion();
         if (version === 'v2') {
             try {
-                let response;
-                try {
-                    response = await this.rootClient.put(`/wp-json/respira/v2/post-types/${type}/posts/${id}`, payload);
-                }
-                catch (error) {
-                    if (isRetryableAsPost(error)) {
-                        response = await this.rootClient.post(`/wp-json/respira/v2/post-types/${type}/posts/${id}`, payload);
-                    }
-                    else {
-                        throw error;
-                    }
-                }
+                const response = await this.putWithPostFallback(this.rootClient, `/wp-json/respira/v2/post-types/${type}/posts/${id}`, payload);
                 return response.data;
             }
             catch (e) {
                 // Fallback to v1 if v2 returns auth/permission error.
                 if (e.response && (e.response.status === 401 || e.response.status === 403)) {
-                    const response = await this.client.put(`/post-types/${type}/posts/${id}`, payload);
+                    const response = await this.putWithPostFallback(this.client, `/post-types/${type}/posts/${id}`, payload);
                     return response.data;
                 }
                 throw e;
             }
         }
-        const response = await this.client.put(`/post-types/${type}/posts/${id}`, payload);
+        const response = await this.putWithPostFallback(this.client, `/post-types/${type}/posts/${id}`, payload);
         return response.data;
     }
     async deleteCustomPost(type, id, opts) {
@@ -3505,6 +3626,24 @@ export class WordPressClient {
         });
         return response.data;
     }
+    /**
+     * Purge page and object caches.
+     *
+     * post_id purges one page; omitting it purges the whole site. The response
+     * names every caching layer the plugin knows, both the ones it purged and
+     * the ones it looked for and did not find.
+     */
+    async purgeCache(postId, scope) {
+        const body = {};
+        if (typeof postId === 'number' && postId > 0) {
+            body.post_id = postId;
+        }
+        if (scope) {
+            body.scope = scope;
+        }
+        const response = await this.client.post('/cache/purge', body);
+        return response.data;
+    }
     // Media enhancements
     async getMedia(id) {
         const response = await this.client.get(`/media/${id}`);