@respira/wordpress-mcp-server 7.5.1 → 7.5.3

package/dist/wordpress-client.js

@@ -9,6 +9,7 @@ import { readFileSync, existsSync, statSync } from 'node:fs';
 import { dirname, resolve, extname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { Agent as HttpAgent } from 'node:http';
+import { randomUUID } from 'node:crypto';
 import { getRespiraAgentHeaders } from './agent-signature.js';
 import { CONFIG_FILE, isTlsInsecureEnv } from './config.js';
 import { makeHttpsAgent } from './system-ca.js';
@@ -26,6 +27,100 @@ const MCP_CLIENT_VERSION = (() => {
     }
     return 'unknown';
 })();
+const SAFE_HTTP_METHODS = new Set(['GET', 'HEAD', 'OPTIONS']);
+const RETRYABLE_CONNECTION_CODES = new Set([
+    'ECONNRESET', 'ETIMEDOUT', 'ECONNABORTED', 'ENETUNREACH',
+    'EHOSTUNREACH', 'EAI_AGAIN', 'EPIPE', 'ECONNREFUSED',
+]);
+/** Attach one stable idempotency key to a mutation config. Retries reuse it. */
+export function ensureWriteIdempotencyKey(config, makeId = randomUUID) {
+    const method = String(config?.method || 'get').toUpperCase();
+    if (SAFE_HTTP_METHODS.has(method))
+        return;
+    config.headers = config.headers || {};
+    const headers = config.headers;
+    const existing = typeof headers.get === 'function'
+        ? headers.get('Idempotency-Key')
+        : headers['Idempotency-Key'] || headers['idempotency-key'];
+    if (existing)
+        return;
+    if (typeof headers.set === 'function')
+        headers.set('Idempotency-Key', makeId());
+    else
+        headers['Idempotency-Key'] = makeId();
+}
+/** Whether a failed request is safe for the connector to repeat automatically. */
+export function isReplaySafeRetry(args) {
+    const method = String(args.method || 'GET').toUpperCase();
+    const safe = SAFE_HTTP_METHODS.has(method);
+    if (typeof args.status === 'number') {
+        if (safe)
+            return args.status >= 500 && args.status <= 599;
+        return args.idempotencySupported === true && [502, 503, 504].includes(args.status);
+    }
+    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;
@@ -133,6 +228,7 @@ export class WordPressClient {
         // (`_restRouteFallback: true` on the request config).
         const requestInterceptor = (config) => {
             try {
+                ensureWriteIdempotencyKey(config);
                 if (this.useRestRouteFallback &&
                     config &&
                     !config._restRouteFallback &&
@@ -159,17 +255,22 @@ export class WordPressClient {
         const RETRY_MAX_ATTEMPTS = 3;
         const RETRY_BASE_MS = 200;
         const RETRY_FACTOR = 3;
-        const RETRYABLE_CONN_CODES = new Set([
-            'ECONNRESET', 'ETIMEDOUT', 'ECONNABORTED', 'ENETUNREACH',
-            'EHOSTUNREACH', 'EAI_AGAIN', 'EPIPE', 'ECONNREFUSED',
-        ]);
         const errorInterceptor = async (error) => {
             const config = error.config || {};
             const attempt = typeof config._respiraRetryAttempt === 'number' ? config._respiraRetryAttempt : 0;
             const status = error.response?.status;
-            const isRetryableStatus = status !== undefined && status >= 500 && status <= 599;
-            const isRetryableConnError = error.response === undefined && error.code !== undefined && RETRYABLE_CONN_CODES.has(error.code);
-            if (attempt < RETRY_MAX_ATTEMPTS && (isRetryableStatus || isRetryableConnError) && config.url !== undefined) {
+            const method = String(config.method || 'get').toUpperCase();
+            const idempotencySupported = String(error.response?.headers?.['x-respira-idempotency-supported'] || '') === '1';
+            // Connection failures have an ambiguous commit state for writes. Only
+            // repeat safe reads, or gateway failures that explicitly advertise the
+            // plugin's response-replay contract.
+            const retryable = isReplaySafeRetry({
+                method,
+                status,
+                idempotencySupported,
+                connectionCode: error.response === undefined ? error.code : undefined,
+            });
+            if (attempt < RETRY_MAX_ATTEMPTS && retryable && config.url !== undefined) {
                 const backoffMs = RETRY_BASE_MS * Math.pow(RETRY_FACTOR, attempt);
                 await new Promise((resolve) => setTimeout(resolve, backoffMs));
                 config._respiraRetryAttempt = attempt + 1;
@@ -934,6 +1035,11 @@ export class WordPressClient {
             // hint AND set a dedicated error.name so the admin/mcp-quality dashboard
             // surfaces this distinct from generic network errors.
             let errorName = code ? `network_${String(code).toLowerCase()}` : 'network_error';
+            const requestMethod = String(error.config?.method || 'get').toUpperCase();
+            const isAmbiguousWrite = !SAFE_HTTP_METHODS.has(requestMethod);
+            const requestHeaders = error.config?.headers || {};
+            const callId = String((typeof requestHeaders.get === 'function' ? requestHeaders.get('Idempotency-Key') : null) ||
+                requestHeaders['Idempotency-Key'] || requestHeaders['idempotency-key'] || '');
             const siteUrl = String(this.siteConfig?.url || '').toLowerCase();
             const isLocalDevUrl = siteUrl.includes('.local/') || siteUrl.endsWith('.local') ||
                 siteUrl.includes('localhost') ||
@@ -944,10 +1050,15 @@ export class WordPressClient {
                 errorName = 'respira_local_url_unreachable';
             }
             const netError = new Error(`Could not connect to ${this.siteConfig.url} — no response received.${hint}\n\n` +
+                (isAmbiguousWrite
+                    ? `The write may have completed after the connection dropped. Do not issue a new write blindly. Verify the target first; if retrying, preserve call id ${callId || '(missing)'}.\n\n`
+                    : '') +
                 'Before checking the API key, verify that the site is accessible: open ' + this.siteConfig.url + ' in a browser. ' +
                 'If the site requires a login or password prompt to access, add "httpAuth" to your site config:\n' +
                 '  "httpAuth": { "username": "your-user", "password": "your-pass" }');
             netError.name = errorName;
+            if (isAmbiguousWrite)
+                netError.name = 'respira_write_outcome_unknown';
             return netError;
         }
         return new Error(`Unknown error: ${error.message}`);
@@ -1543,11 +1654,9 @@ export class WordPressClient {
                     clearTimeout(killer);
                 }
             }
-            else if (file.startsWith('/') || file.startsWith('./') || file.startsWith('../') || file.startsWith('~')) {
+            else if (isLocalFilePath(file)) {
                 // Local file path — preflight size before reading the whole file into memory
-                const resolvedPath = file.startsWith('~')
-                    ? file.replace(/^~/, process.env.HOME || '')
-                    : resolve(file);
+                const resolvedPath = resolveLocalFilePath(file);
                 if (!existsSync(resolvedPath)) {
                     throw new Error(`File not found: ${resolvedPath}`);
                 }
@@ -2275,6 +2384,21 @@ export class WordPressClient {
     getSiteUrl() {
         return this.siteConfig.url;
     }
+    /**
+     * Fetch a site-scoped telemetry bearer from the plugin. The request is
+     * authenticated locally; the local respira_* API key is never sent to the
+     * central ingest.
+     */
+    async getTelemetryToken() {
+        try {
+            const response = await this.client.post('/mcp/telemetry-token', {}, { timeout: 15000 });
+            const token = typeof response.data?.token === 'string' ? response.data.token.trim() : '';
+            return token.startsWith('rp_mcp_') ? token : null;
+        }
+        catch {
+            return null;
+        }
+    }
     /**
      * Get approvals URL in WordPress admin.
      *
@@ -2887,8 +3011,24 @@ export class WordPressClient {
         const response = await this.client.put('/media/batch', { items });
         return response.data;
     }
-    async deleteMedia(id) {
-        const response = await this.client.delete(`/media/${id}`);
+    /**
+     * 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).
+     */
+    async deleteMedia(id, force, approvalToken) {
+        const params = {};
+        if (force) {
+            params.force = true;
+        }
+        if (approvalToken) {
+            params.approval_token = approvalToken;
+        }
+        const response = await this.client.delete(`/media/${id}`, { params });
         return response.data;
     }
     // Menu Management