@respira/wordpress-mcp-server 8.2.3 → 8.2.5

package/CHANGELOG.md

@@ -5,6 +5,25 @@ All notable changes to Respira WordPress MCP Server will be documented in this f
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [8.2.5] - 2026-08-09
+
+### Fixed
+
+- **A partly-edited starter config was accepted as a real one, sending every request to `example.com`.** The first run writes a placeholder config carrying a dummy address AND a dummy key, and `isPlaceholderConfig()` tested only the key. Replace the key and leave the address, which is what people do, and the file stopped looking like a placeholder while still pointing at a site nobody owns. It was then served as a genuine setup: the server started cleanly, exposed every tool, reported no error, and sent all traffic to the wrong place. The reporter described it exactly: "connected, tools loaded, nothing flagged, just consistently the wrong site behind it." A site now counts as a placeholder when EITHER field is still the dummy, normalised for trailing slashes and case. A config mixing one real site with a leftover stub is still kept, and a hostname merely containing `example.com` is still a real site. Reported by R.M.
+- **An API key pasted with the documentation brackets still around it is now rejected at startup.** `<respira_...>` is not a valid key, but it is also not the placeholder key, so it defeated the same check above and pinned the session to the dummy site with no error anywhere. It now throws on load and names the fix, matching how a masked key full of bullet characters is already handled. Both are values no real key can hold. This and the entry above were one mechanism behind two separate incidents a month apart for the same customer. Reported by R.M.
+
+## [8.2.4] - 2026-08-09
+
+### Fixed
+
+- **A PUT request that a host blocks now retries as POST**, closing the gap for Elementor's global-colors and global-typography routes (403 on hosts like OVH that block PUT) and every other route built on the shared REST client in the same fix: Bricks global classes/theme styles/color palette/typography, FSE templates/patterns/navigation, design tokens, and the v1 custom post-type/taxonomy/ACF surface.
+- **The four WooCommerce card tools' `edit_target` values now match the FSE tool family they actually route through** (`approval`/`live`, the same vocabulary `update_site_template` uses), instead of the page-edit tools' `live`/`duplicate`, which described a mode the FSE layer doesn't implement.
+- **`redeem_token` now activates sites in the running session immediately.** A successful redeem wrote a config file and reported success, but the server kept using its boot-time site list until restarted, and under a sandboxed or read-only config source that restart never comes, so the write was silently a no-op. Sites are now merged into the live list on redeem, a first-ever redeem sets the active site so tools work without a follow-up call, and a malformed or masked key is reported with a reason instead of vanishing.
+
+### Added
+
+- **`diagnose_connection` reports the actual running transport**: bundle, npx cache, global npm install, project-local install, or source checkout, plus a flag when a differently-launched sibling Respira process is detected, closing the observability gap behind three separate "my agent is talking to the wrong site" reports that each turned out to have a different root cause.
+
 ## [8.2.3] - 2026-08-04
 
 ### Fixed

package/dist/__tests__/config-bracketed-key.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=config-bracketed-key.test.d.ts.map

package/dist/__tests__/config-bracketed-key.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-bracketed-key.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/config-bracketed-key.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/config-bracketed-key.test.js

@@ -0,0 +1,46 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { validateApiKeyShape } from '../config.js';
+/**
+ * A key pasted with the documentation brackets still around it.
+ *
+ * R.M. found this in his own Claude Desktop config after losing a day to it:
+ * "a misconfigured entry in the config file itself (wrong server name, stray
+ * angle brackets around the API key) that the UI never surfaced. I only found
+ * it by editing the JSON directly."
+ *
+ * It was worse than an invalid key. `<respira_abc…>` does not equal the
+ * placeholder key either, so it defeated isPlaceholderConfig and the session
+ * was pinned to the dummy site while reporting itself perfectly healthy. Two
+ * separate incidents of his turned out to be this one mechanism.
+ *
+ * Throwing matches the masked-bullets case in the same function: both are
+ * values that no real key can hold, so there is nothing to be tentative about.
+ */
+const REAL = 'respira_' + 'a'.repeat(36);
+test('a key wrapped in angle brackets is rejected outright', () => {
+    assert.throws(() => validateApiKeyShape(`<${REAL}>`, 'my site'), /angle brackets/i, 'the brackets are documentation, not part of the key');
+});
+test('the error names the fix rather than just the fault', () => {
+    try {
+        validateApiKeyShape(`<${REAL}>`, 'my site');
+        assert.fail('should have thrown');
+    }
+    catch (err) {
+        const msg = String(err.message);
+        assert.match(msg, /Remove them/i);
+        assert.match(msg, /my site/, 'says which site, since a config can hold many');
+        // The reason this is worth throwing over: it used to end in the wrong site.
+        assert.match(msg, /placeholder site/i);
+    }
+});
+test('a stray bracket on either side is caught, not just a matched pair', () => {
+    assert.throws(() => validateApiKeyShape(`<${REAL}`, 's'), /angle brackets/i);
+    assert.throws(() => validateApiKeyShape(`${REAL}>`, 's'), /angle brackets/i);
+});
+test('a clean key still passes untouched', () => {
+    assert.doesNotThrow(() => validateApiKeyShape(REAL, 's'));
+    assert.doesNotThrow(() => validateApiKeyShape('rsp_at_' + 'b'.repeat(40), 's'));
+    assert.doesNotThrow(() => validateApiKeyShape('respira_site_' + 'c'.repeat(32), 's'));
+});
+//# sourceMappingURL=config-bracketed-key.test.js.map

package/dist/__tests__/config-bracketed-key.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-bracketed-key.test.js","sourceRoot":"","sources":["../../src/__tests__/config-bracketed-key.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,MAAM,MAAM,oBAAoB,CAAC;AACxC,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAEnD;;;;;;;;;;;;;;;GAeG;AAEH,MAAM,IAAI,GAAG,UAAU,GAAG,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;AAEzC,IAAI,CAAC,sDAAsD,EAAE,GAAG,EAAE;IAChE,MAAM,CAAC,MAAM,CACX,GAAG,EAAE,CAAC,mBAAmB,CAAC,IAAI,IAAI,GAAG,EAAE,SAAS,CAAC,EACjD,iBAAiB,EACjB,qDAAqD,CACtD,CAAC;AACJ,CAAC,CAAC,CAAC;AAEH,IAAI,CAAC,oDAAoD,EAAE,GAAG,EAAE;IAC9D,IAAI,CAAC;QACH,mBAAmB,CAAC,IAAI,IAAI,GAAG,EAAE,SAAS,CAAC,CAAC;QAC5C,MAAM,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC;IACpC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,GAAG,GAAG,MAAM,CAAE,GAAa,CAAC,OAAO,CAAC,CAAC;QAC3C,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,cAAc,CAAC,CAAC;QAClC,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,SAAS,EAAE,+CAA+C,CAAC,CAAC;QAC9E,4EAA4E;QAC5E,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,mBAAmB,CAAC,CAAC;IACzC,CAAC;AACH,CAAC,CAAC,CAAC;AAEH,IAAI,CAAC,mEAAmE,EAAE,GAAG,EAAE;IAC7E,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,mBAAmB,CAAC,IAAI,IAAI,EAAE,EAAE,GAAG,CAAC,EAAE,iBAAiB,CAAC,CAAC;IAC7E,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,mBAAmB,CAAC,GAAG,IAAI,GAAG,EAAE,GAAG,CAAC,EAAE,iBAAiB,CAAC,CAAC;AAC/E,CAAC,CAAC,CAAC;AAEH,IAAI,CAAC,oCAAoC,EAAE,GAAG,EAAE;IAC9C,MAAM,CAAC,YAAY,CAAC,GAAG,EAAE,CAAC,mBAAmB,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC;IAC1D,MAAM,CAAC,YAAY,CAAC,GAAG,EAAE,CAAC,mBAAmB,CAAC,SAAS,GAAG,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC;IAChF,MAAM,CAAC,YAAY,CAAC,GAAG,EAAE,CAAC,mBAAmB,CAAC,eAAe,GAAG,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC;AACxF,CAAC,CAAC,CAAC"}

package/dist/__tests__/config-placeholder.test.js

@@ -13,11 +13,38 @@ test('isPlaceholderConfig flags the first-run default file', () => {
 test('isPlaceholderConfig does NOT flag a real config', () => {
     assert.equal(isPlaceholderConfig({ sites: [realSite], preferences: prefs }), false);
 });
-test('isPlaceholderConfig does NOT flag a real example.com test site (real key)', () => {
-    // url is example.com but the key is real — keying on the dummy api key avoids
-    // wrongly discarding a legitimate example.com test config.
-    const realExample = { sites: [{ ...realSite, url: 'https://example.com' }], preferences: prefs };
-    assert.equal(isPlaceholderConfig(realExample), false);
+test('isPlaceholderConfig DOES flag example.com even when the key is real', () => {
+    // REVERSAL, on purpose. This test previously asserted the opposite, to avoid
+    // discarding "a legitimate example.com test config". That case cannot exist:
+    // example.com is IANA-reserved for documentation, so no customer WordPress
+    // install lives there and no real key authenticates against it.
+    //
+    // Meanwhile the case it permitted happens constantly. The starter file ships
+    // a dummy url AND a dummy key. A user pastes a real key and leaves the
+    // address, or pastes a key with the doc brackets still attached, and the key
+    // test stops matching. The config was then accepted as genuine: the server
+    // started cleanly, listed all 234 tools, reported no errors, and sent every
+    // request to example.com.
+    //
+    // R.M. lost hours to exactly this, twice, and nearly cancelled over it:
+    // "connected, tools loaded, nothing flagged, just consistently the wrong site
+    // behind it." The asymmetry decides it. A false positive here tells a
+    // hypothetical developer to fix a config. A false negative silently points a
+    // paying customer's agent at a site that is not theirs, while every signal
+    // says healthy.
+    const realKeyDummyUrl = { sites: [{ ...realSite, url: 'https://example.com' }], preferences: prefs };
+    assert.equal(isPlaceholderConfig(realKeyDummyUrl), true);
+});
+test('a trailing slash or different case on the dummy url does not defeat the check', () => {
+    for (const url of ['https://example.com/', 'HTTPS://Example.com', 'https://example.com//']) {
+        assert.equal(isPlaceholderConfig({ sites: [{ ...realSite, url }], preferences: prefs }), true, `expected ${url} to be recognised as the placeholder address`);
+    }
+});
+test('a real site is still never flagged, whatever its key looks like', () => {
+    // The guard must not start eating working configs. This is the regression
+    // that would actually break people.
+    assert.equal(isPlaceholderConfig({ sites: [realSite], preferences: prefs }), false);
+    assert.equal(isPlaceholderConfig({ sites: [{ ...realSite, url: 'https://example.com.mysite.dk' }], preferences: prefs }), false, 'a hostname merely CONTAINING example.com is a real site');
 });
 test('isPlaceholderConfig is false for empty / missing sites', () => {
     assert.equal(isPlaceholderConfig({ sites: [], preferences: prefs }), false);

package/dist/__tests__/config-placeholder.test.js.map

@@ -1 +1 @@
-{"version":3,"file":"config-placeholder.test.js","sourceRoot":"","sources":["../../src/__tests__/config-placeholder.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,MAAM,MAAM,oBAAoB,CAAC;AACxC,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAEnD,MAAM,QAAQ,GAAG,EAAE,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,GAAG,EAAE,4BAA4B,EAAE,MAAM,EAAE,qBAAqB,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;AACzH,MAAM,KAAK,GAAG,EAAE,aAAa,EAAE,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,CAAC;AAE5D,IAAI,CAAC,sDAAsD,EAAE,GAAG,EAAE;IAChE,MAAM,WAAW,GAAG;QAClB,KAAK,EAAE,CAAC,EAAE,EAAE,EAAE,cAAc,EAAE,IAAI,EAAE,mBAAmB,EAAE,GAAG,EAAE,qBAAqB,EAAE,MAAM,EAAE,2BAA2B,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;QAC1I,WAAW,EAAE,KAAK;KACnB,CAAC;IACF,MAAM,CAAC,KAAK,CAAC,mBAAmB,CAAC,WAAW,CAAC,EAAE,IAAI,CAAC,CAAC;AACvD,CAAC,CAAC,CAAC;AAEH,IAAI,CAAC,iDAAiD,EAAE,GAAG,EAAE;IAC3D,MAAM,CAAC,KAAK,CAAC,mBAAmB,CAAC,EAAE,KAAK,EAAE,CAAC,QAAQ,CAAC,EAAE,WAAW,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,CAAC,CAAC;AACtF,CAAC,CAAC,CAAC;AAEH,IAAI,CAAC,2EAA2E,EAAE,GAAG,EAAE;IACrF,8EAA8E;IAC9E,2DAA2D;IAC3D,MAAM,WAAW,GAAG,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,QAAQ,EAAE,GAAG,EAAE,qBAAqB,EAAE,CAAC,EAAE,WAAW,EAAE,KAAK,EAAE,CAAC;IACjG,MAAM,CAAC,KAAK,CAAC,mBAAmB,CAAC,WAAW,CAAC,EAAE,KAAK,CAAC,CAAC;AACxD,CAAC,CAAC,CAAC;AAEH,IAAI,CAAC,wDAAwD,EAAE,GAAG,EAAE;IAClE,MAAM,CAAC,KAAK,CAAC,mBAAmB,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,WAAW,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,CAAC,CAAC;IAC5E,MAAM,CAAC,KAAK,CAAC,mBAAmB,CAAC,IAAI,CAAC,EAAE,KAAK,CAAC,CAAC;IAC/C,MAAM,CAAC,KAAK,CAAC,mBAAmB,CAAC,SAAS,CAAC,EAAE,KAAK,CAAC,CAAC;IACpD,MAAM,CAAC,KAAK,CAAC,mBAAmB,CAAC,EAAE,CAAC,EAAE,KAAK,CAAC,CAAC;AAC/C,CAAC,CAAC,CAAC;AAEH,IAAI,CAAC,mFAAmF,EAAE,GAAG,EAAE;IAC7F,MAAM,EAAE,GAAG,EAAE,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,GAAG,EAAE,qBAAqB,EAAE,MAAM,EAAE,2BAA2B,EAAE,CAAC;IACnG,MAAM,CAAC,KAAK,CAAC,mBAAmB,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,WAAW,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC;IACjF,yCAAyC;IACzC,MAAM,CAAC,KAAK,CAAC,mBAAmB,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,QAAQ,CAAC,EAAE,WAAW,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,CAAC,CAAC;AAC1F,CAAC,CAAC,CAAC"}
+{"version":3,"file":"config-placeholder.test.js","sourceRoot":"","sources":["../../src/__tests__/config-placeholder.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,MAAM,MAAM,oBAAoB,CAAC;AACxC,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAEnD,MAAM,QAAQ,GAAG,EAAE,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,GAAG,EAAE,4BAA4B,EAAE,MAAM,EAAE,qBAAqB,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;AACzH,MAAM,KAAK,GAAG,EAAE,aAAa,EAAE,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,CAAC;AAE5D,IAAI,CAAC,sDAAsD,EAAE,GAAG,EAAE;IAChE,MAAM,WAAW,GAAG;QAClB,KAAK,EAAE,CAAC,EAAE,EAAE,EAAE,cAAc,EAAE,IAAI,EAAE,mBAAmB,EAAE,GAAG,EAAE,qBAAqB,EAAE,MAAM,EAAE,2BAA2B,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;QAC1I,WAAW,EAAE,KAAK;KACnB,CAAC;IACF,MAAM,CAAC,KAAK,CAAC,mBAAmB,CAAC,WAAW,CAAC,EAAE,IAAI,CAAC,CAAC;AACvD,CAAC,CAAC,CAAC;AAEH,IAAI,CAAC,iDAAiD,EAAE,GAAG,EAAE;IAC3D,MAAM,CAAC,KAAK,CAAC,mBAAmB,CAAC,EAAE,KAAK,EAAE,CAAC,QAAQ,CAAC,EAAE,WAAW,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,CAAC,CAAC;AACtF,CAAC,CAAC,CAAC;AAEH,IAAI,CAAC,qEAAqE,EAAE,GAAG,EAAE;IAC/E,6EAA6E;IAC7E,6EAA6E;IAC7E,2EAA2E;IAC3E,gEAAgE;IAChE,EAAE;IACF,6EAA6E;IAC7E,uEAAuE;IACvE,6EAA6E;IAC7E,2EAA2E;IAC3E,4EAA4E;IAC5E,0BAA0B;IAC1B,EAAE;IACF,wEAAwE;IACxE,8EAA8E;IAC9E,sEAAsE;IACtE,6EAA6E;IAC7E,2EAA2E;IAC3E,gBAAgB;IAChB,MAAM,eAAe,GAAG,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,QAAQ,EAAE,GAAG,EAAE,qBAAqB,EAAE,CAAC,EAAE,WAAW,EAAE,KAAK,EAAE,CAAC;IACrG,MAAM,CAAC,KAAK,CAAC,mBAAmB,CAAC,eAAe,CAAC,EAAE,IAAI,CAAC,CAAC;AAC3D,CAAC,CAAC,CAAC;AAEH,IAAI,CAAC,+EAA+E,EAAE,GAAG,EAAE;IACzF,KAAK,MAAM,GAAG,IAAI,CAAC,sBAAsB,EAAE,qBAAqB,EAAE,uBAAuB,CAAC,EAAE,CAAC;QAC3F,MAAM,CAAC,KAAK,CACV,mBAAmB,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,QAAQ,EAAE,GAAG,EAAE,CAAC,EAAE,WAAW,EAAE,KAAK,EAAE,CAAC,EAC1E,IAAI,EACJ,YAAY,GAAG,8CAA8C,CAC9D,CAAC;IACJ,CAAC;AACH,CAAC,CAAC,CAAC;AAEH,IAAI,CAAC,iEAAiE,EAAE,GAAG,EAAE;IAC3E,0EAA0E;IAC1E,oCAAoC;IACpC,MAAM,CAAC,KAAK,CAAC,mBAAmB,CAAC,EAAE,KAAK,EAAE,CAAC,QAAQ,CAAC,EAAE,WAAW,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,CAAC,CAAC;IACpF,MAAM,CAAC,KAAK,CACV,mBAAmB,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,QAAQ,EAAE,GAAG,EAAE,+BAA+B,EAAE,CAAC,EAAE,WAAW,EAAE,KAAK,EAAE,CAAC,EAC3G,KAAK,EACL,yDAAyD,CAC1D,CAAC;AACJ,CAAC,CAAC,CAAC;AAEH,IAAI,CAAC,wDAAwD,EAAE,GAAG,EAAE;IAClE,MAAM,CAAC,KAAK,CAAC,mBAAmB,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,WAAW,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,CAAC,CAAC;IAC5E,MAAM,CAAC,KAAK,CAAC,mBAAmB,CAAC,IAAI,CAAC,EAAE,KAAK,CAAC,CAAC;IAC/C,MAAM,CAAC,KAAK,CAAC,mBAAmB,CAAC,SAAS,CAAC,EAAE,KAAK,CAAC,CAAC;IACpD,MAAM,CAAC,KAAK,CAAC,mBAAmB,CAAC,EAAE,CAAC,EAAE,KAAK,CAAC,CAAC;AAC/C,CAAC,CAAC,CAAC;AAEH,IAAI,CAAC,mFAAmF,EAAE,GAAG,EAAE;IAC7F,MAAM,EAAE,GAAG,EAAE,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,GAAG,EAAE,qBAAqB,EAAE,MAAM,EAAE,2BAA2B,EAAE,CAAC;IACnG,MAAM,CAAC,KAAK,CAAC,mBAAmB,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,WAAW,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC;IACjF,yCAAyC;IACzC,MAAM,CAAC,KAAK,CAAC,mBAAmB,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,QAAQ,CAAC,EAAE,WAAW,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,CAAC,CAAC;AAC1F,CAAC,CAAC,CAAC"}

package/dist/__tests__/invoke-ability-required-args.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=invoke-ability-required-args.test.d.ts.map

package/dist/__tests__/invoke-ability-required-args.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"invoke-ability-required-args.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/invoke-ability-required-args.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/invoke-ability-required-args.test.js

@@ -0,0 +1,53 @@
+import { test } from 'node:test';
+import assert from 'node:assert';
+import { requireAbilityName } from '../server.js';
+// wordpress_invoke_ability has never succeeded once: 36 calls, 36 failures.
+// Most of those are the agent naming an ability that does not exist, fixed
+// plugin-side in 8.6.2. Seven are this: the tool was called without `ability`,
+// the dispatcher passed undefined straight through, JSON dropped the key, and
+// the site answered `rest_missing_callback_param` — a message that names
+// neither the parameter nor the tool's word for it.
+//
+// The contract is worth guarding because it is the one an agent has to guess.
+test('a well-formed ability name passes through, trimmed', () => {
+    assert.equal(requireAbilityName({ ability: 'rankmath/get-meta' }), 'rankmath/get-meta');
+    assert.equal(requireAbilityName({ ability: '  woocommerce/get-order  ' }), 'woocommerce/get-order');
+});
+test('a missing ability names the parameter, the shape, and the way out', () => {
+    assert.throws(() => requireAbilityName({ args: { post_id: 1 } }), (err) => {
+        assert.match(err.message, /requires `ability`/, 'names the parameter');
+        assert.match(err.message, /vendor\/ability-name/, 'gives the shape');
+        assert.match(err.message, /wordpress_search_abilities/, 'points at discovery');
+        return true;
+    });
+});
+test('undefined, empty and whitespace-only are all refused', () => {
+    for (const bad of [undefined, {}, { ability: '' }, { ability: '   ' }, { ability: null }, { ability: 42 }]) {
+        assert.throws(() => requireAbilityName(bad), /requires `ability`/, `should refuse ${JSON.stringify(bad)}`);
+    }
+});
+test('a plausible alias is named in the error, not silently accepted', () => {
+    // Silently honouring these would make the tool schema a lie and teach the
+    // next agent the wrong contract from a call that worked.
+    for (const alias of ['name', 'ability_name', 'abilityName', 'tool', 'slug']) {
+        assert.throws(() => requireAbilityName({ [alias]: 'rankmath/get-meta' }), (err) => {
+            assert.match(err.message, new RegExp('`' + alias + '`'), `should name ${alias}`);
+            assert.match(err.message, /rename it to `ability`/, 'should say what to do');
+            return true;
+        });
+    }
+});
+test('several aliases at once are all named', () => {
+    assert.throws(() => requireAbilityName({ name: 'a/b', tool: 'c/d' }), (err) => {
+        assert.match(err.message, /`name`/);
+        assert.match(err.message, /`tool`/);
+        return true;
+    });
+});
+test('an alias holding a non-string is not reported as if it were usable', () => {
+    assert.throws(() => requireAbilityName({ name: 12345 }), (err) => {
+        assert.doesNotMatch(err.message, /You sent/, 'a numeric alias is not a rename suggestion');
+        return true;
+    });
+});
+//# sourceMappingURL=invoke-ability-required-args.test.js.map

package/dist/__tests__/invoke-ability-required-args.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"invoke-ability-required-args.test.js","sourceRoot":"","sources":["../../src/__tests__/invoke-ability-required-args.test.ts"],"names":[],"mappings":"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"}

package/dist/__tests__/oq-put-fallback-callRestV2-integration.test.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Ticket 2b3a706b — the PUT-blocked-host fallback existed (isRetryableAsPost /
+ * PUT_FALLBACK_STATUSES, oq-put-fallback-403.test.ts) but was only wired into
+ * the dedicated updatePost/updatePage methods. Every tool routed through the
+ * shared `callRestV2`/`callRestV1` REST callers — Elementor global colors and
+ * typography (elementor-tools.ts), Bricks global classes/theme styles/color
+ * palette/typography (bricks-tools.ts), FSE templates/patterns/navigation and
+ * design tokens (server.ts) — emitted a bare PUT with no fallback at all, so a
+ * host that blocks PUT (allows only OPTIONS/HEAD/GET/POST, e.g. shared Apache
+ * hosting) still got a misleading "site blocked by firewall" 403 even though
+ * there is no firewall, just a host that rejects the verb.
+ *
+ * Reported, root-caused and verified live by O.Q. against
+ * linvestisseurantifragile.com (OVH shared hosting): POSTing the identical
+ * payloads to the same v2 routes succeeded with 200, proving the server
+ * already accepts POST — only the client's method choice needed the fix.
+ *
+ * These tests run a real HTTP server (no adapter mocking) so the real
+ * interceptor chain runs, including the `.response`-stripping codedError()
+ * step that made a status-only predicate a no-op the first time around
+ * (see oq-put-fallback-403.test.ts).
+ */
+export {};
+//# sourceMappingURL=oq-put-fallback-callRestV2-integration.test.d.ts.map

package/dist/__tests__/oq-put-fallback-callRestV2-integration.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oq-put-fallback-callRestV2-integration.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/oq-put-fallback-callRestV2-integration.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG"}

package/dist/__tests__/oq-put-fallback-callRestV2-integration.test.js

@@ -0,0 +1,135 @@
+/**
+ * Ticket 2b3a706b — the PUT-blocked-host fallback existed (isRetryableAsPost /
+ * PUT_FALLBACK_STATUSES, oq-put-fallback-403.test.ts) but was only wired into
+ * the dedicated updatePost/updatePage methods. Every tool routed through the
+ * shared `callRestV2`/`callRestV1` REST callers — Elementor global colors and
+ * typography (elementor-tools.ts), Bricks global classes/theme styles/color
+ * palette/typography (bricks-tools.ts), FSE templates/patterns/navigation and
+ * design tokens (server.ts) — emitted a bare PUT with no fallback at all, so a
+ * host that blocks PUT (allows only OPTIONS/HEAD/GET/POST, e.g. shared Apache
+ * hosting) still got a misleading "site blocked by firewall" 403 even though
+ * there is no firewall, just a host that rejects the verb.
+ *
+ * Reported, root-caused and verified live by O.Q. against
+ * linvestisseurantifragile.com (OVH shared hosting): POSTing the identical
+ * payloads to the same v2 routes succeeded with 200, proving the server
+ * already accepts POST — only the client's method choice needed the fix.
+ *
+ * These tests run a real HTTP server (no adapter mocking) so the real
+ * interceptor chain runs, including the `.response`-stripping codedError()
+ * step that made a status-only predicate a no-op the first time around
+ * (see oq-put-fallback-403.test.ts).
+ */
+import { test, after } from 'node:test';
+import assert from 'node:assert/strict';
+import http from 'node:http';
+import { WordPressClient } from '../wordpress-client.js';
+const servers = [];
+after(() => {
+    for (const s of servers)
+        s.close();
+});
+// Apache-style "Forbidden" page for a method the host rejects at the edge —
+// HTML, not JSON, which is what makes handleError() treat it as
+// "not WordPress" and stamp error.name = 'http_403_non_wordpress'.
+const APACHE_403_HTML = '<!DOCTYPE html><html><head><title>403 Forbidden</title></head><body><h1>Forbidden</h1></body></html>';
+/**
+ * A fake site: GET /wp-json/respira/v2/status negotiates v2 (200 JSON).
+ * PUT to `blockedPath` is rejected exactly like a host that disallows the
+ * verb: HTML body, 403 status, no WordPress JSON envelope. POST to the same
+ * path succeeds with a JSON body, mirroring O.Q.'s manual proof.
+ */
+async function startBlockedPutSite(blockedPath) {
+    const hits = [];
+    const server = http.createServer((req, res) => {
+        hits.push({ method: req.method || '', url: req.url || '' });
+        const path = (req.url || '').split('?')[0];
+        if (req.method === 'GET' && path === '/wp-json/respira/v2/status') {
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ status: 'ok' }));
+            return;
+        }
+        if (req.method === 'PUT' && path === blockedPath) {
+            res.writeHead(403, { 'Content-Type': 'text/html' });
+            res.end(APACHE_403_HTML);
+            return;
+        }
+        if (req.method === 'POST' && path === blockedPath) {
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: true, via: 'POST' }));
+            return;
+        }
+        res.writeHead(404, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ code: 'rest_no_route', message: 'No route' }));
+    });
+    servers.push(server);
+    await new Promise((resolve) => server.listen(0, resolve));
+    const { port } = server.address();
+    const client = new WordPressClient({
+        id: 'oq-blocked-put',
+        name: 'oq-blocked-put',
+        url: `http://127.0.0.1:${port}`,
+        apiKey: 'respira_test_key',
+    });
+    return { client, hits };
+}
+test('callRestV2 PUT on a host that blocks PUT retries as POST transparently (Elementor global colors)', async () => {
+    const { client, hits } = await startBlockedPutSite('/wp-json/respira/v2/elementor/global-colors');
+    const result = await client.callRestV2('PUT', '/elementor/global-colors', {
+        colors: [{ _id: 'brand_primary', title: 'Brand Primary', color: '#FF5733' }],
+    });
+    assert.deepEqual(result, { success: true, via: 'POST' });
+    const put = hits.filter((h) => h.method === 'PUT' && h.url.includes('/elementor/global-colors'));
+    const post = hits.filter((h) => h.method === 'POST' && h.url.includes('/elementor/global-colors'));
+    assert.equal(put.length, 1, 'PUT was attempted first');
+    assert.equal(post.length, 1, 'POST fallback fired exactly once');
+});
+test('callRestV2 PUT on a host that blocks PUT retries as POST transparently (Elementor global typography)', async () => {
+    const { client, hits } = await startBlockedPutSite('/wp-json/respira/v2/elementor/global-typography');
+    const result = await client.callRestV2('PUT', '/elementor/global-typography', {
+        typography: [{ _id: 'heading_primary', title: 'Heading Primary' }],
+    });
+    assert.deepEqual(result, { success: true, via: 'POST' });
+    // Scoped to the target path: a background, non-blocking checkCompatibility()
+    // POST to /server/compatibility also hits this same fake server and would
+    // otherwise inflate an unscoped count.
+    assert.equal(hits.filter((h) => h.method === 'POST' && h.url.includes('/elementor/global-typography')).length, 1);
+});
+test('callRestV2 PUT on a host that blocks PUT retries as POST transparently (Bricks theme styles, a sibling call site)', async () => {
+    const { client, hits } = await startBlockedPutSite('/wp-json/respira/v2/bricks/theme-styles');
+    const result = await client.callRestV2('PUT', '/bricks/theme-styles', { value: { spacing: 'md' } });
+    assert.deepEqual(result, { success: true, via: 'POST' });
+    assert.equal(hits.filter((h) => h.method === 'POST' && h.url.includes('/bricks/theme-styles')).length, 1);
+});
+test('callRestV2 does NOT retry a real WordPress permission 403 as POST', async () => {
+    const hits = [];
+    const server = http.createServer((req, res) => {
+        hits.push({ method: req.method || '', url: req.url || '' });
+        const path = (req.url || '').split('?')[0];
+        if (req.method === 'GET' && path === '/wp-json/respira/v2/status') {
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ status: 'ok' }));
+            return;
+        }
+        if (req.method === 'PUT' && path === '/wp-json/respira/v2/elementor/global-colors') {
+            // A genuine WordPress permission decision: JSON body, not HTML.
+            res.writeHead(403, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ code: 'rest_cannot_edit', message: 'Sorry, you are not allowed to edit this.' }));
+            return;
+        }
+        res.writeHead(404, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ code: 'rest_no_route' }));
+    });
+    servers.push(server);
+    await new Promise((resolve) => server.listen(0, resolve));
+    const { port } = server.address();
+    const client = new WordPressClient({
+        id: 'oq-real-403',
+        name: 'oq-real-403',
+        url: `http://127.0.0.1:${port}`,
+        apiKey: 'respira_test_key',
+    });
+    await assert.rejects(() => client.callRestV2('PUT', '/elementor/global-colors', { colors: [] }), /not allowed to edit/);
+    assert.equal(hits.filter((h) => h.method === 'POST' && h.url.includes('/elementor/global-colors')).length, 0, 'no POST retry for a real WP permission denial');
+});
+//# sourceMappingURL=oq-put-fallback-callRestV2-integration.test.js.map

package/dist/__tests__/oq-put-fallback-callRestV2-integration.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"oq-put-fallback-callRestV2-integration.test.js","sourceRoot":"","sources":["../../src/__tests__/oq-put-fallback-callRestV2-integration.test.ts"],"names":[],"mappings":"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"}

package/dist/__tests__/transport-mode-observability.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=transport-mode-observability.test.d.ts.map

package/dist/__tests__/transport-mode-observability.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport-mode-observability.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/transport-mode-observability.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/transport-mode-observability.test.js

@@ -0,0 +1,201 @@
+/**
+ * describeEffectiveConfig answers "which config won". This is the other half:
+ * which INSTALL won, and is a second one running.
+ *
+ * Desmond (c9a95152) installed the .mcpb desktop bundle while an older npx
+ * entry stayed in his client config. Both were real Respira servers. The
+ * client kept talking to the old one for three weeks and nothing anywhere
+ * said which install was answering.
+ *
+ * These tests pin four things:
+ *   1. each install shape is recognised from its launch path alone, because a
+ *      sibling process only ever gives us a command line, never an env;
+ *   2. the bundle is recognised even though its command line does not contain
+ *      the string 'wordpress-mcp-server' — the exact blind spot that made
+ *      Desmond's second server invisible to the old sibling scan;
+ *   3. two different launch modes running at once reads as a duplicate client
+ *      entry, while two identical ones stays honestly ambiguous (orphans from
+ *      a reconnect look the same from here);
+ *   4. nothing token-shaped reaches the output, which gets pasted into
+ *      support threads.
+ */
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { classifyLaunchMode, collapseLauncherProcesses, describeDuplicateEntries, describeTransportMode, redactSecrets, } from '../config.js';
+const MCPB_PATH = '/Users/d/Library/Application Support/Claude/Claude Extensions/local.mcpb.respira-wordpress/server/index.js';
+const NPX_PATH = '/Users/d/.npm/_npx/8f3a21/node_modules/@respira/wordpress-mcp-server/dist/index.js';
+describe('classifyLaunchMode', () => {
+    it('recognises the desktop bundle from its path, with no env to help', () => {
+        assert.equal(classifyLaunchMode(MCPB_PATH).mode, 'mcpb_bundle');
+    });
+    it('trusts the connection source the bundle manifest sets', () => {
+        const { mode, evidence } = classifyLaunchMode('/wherever/index.js', {
+            RESPIRA_CONNECTION_SOURCE: 'claude_desktop_mcpb',
+        });
+        assert.equal(mode, 'mcpb_bundle');
+        assert.match(evidence.join(' '), /claude_desktop_mcpb/);
+    });
+    it('recognises an npx one-off run', () => {
+        assert.equal(classifyLaunchMode(NPX_PATH).mode, 'npx_cache');
+    });
+    it('recognises a global install (homebrew and nvm)', () => {
+        assert.equal(classifyLaunchMode('/opt/homebrew/lib/node_modules/@respira/wordpress-mcp-server/dist/index.js').mode, 'global_npm_install');
+        assert.equal(classifyLaunchMode('/Users/d/.nvm/versions/node/v22.3.0/lib/node_modules/@respira/wordpress-mcp-server/dist/index.js').mode, 'global_npm_install');
+    });
+    it('recognises a project-local install and a source checkout', () => {
+        assert.equal(classifyLaunchMode('/Users/d/app/node_modules/@respira/wordpress-mcp-server/dist/index.js').mode, 'project_local_install');
+        assert.equal(classifyLaunchMode('/Users/d/code/respira-wordpress/mcp-server/dist/index.js').mode, 'source_checkout');
+    });
+    it('says unknown rather than guessing', () => {
+        assert.equal(classifyLaunchMode('/opt/custom-wrapper/run.js').mode, 'unknown');
+    });
+});
+/**
+ * Captured from a real Claude Desktop machine. ONE npx entry, three processes.
+ * If these count as three servers, the duplicate warning fires on every
+ * healthy install and everyone learns to ignore it.
+ */
+const NPX_LAUNCHER_CHAIN = [
+    {
+        pid: 72496,
+        ppid: 1,
+        command: '/Applications/Claude.app/Contents/Helpers/disclaimer /Users/d/.nvm/versions/node/v20.19.5/bin/npx -y @respira/wordpress-mcp-server@latest',
+    },
+    { pid: 72497, ppid: 72496, command: 'npm exec @respira/wordpress-mcp-server@latest' },
+    {
+        pid: 73159,
+        ppid: 72497,
+        command: 'node /Users/d/.npm/_npx/9fa6fea18a2d317a/node_modules/.bin/wordpress-mcp-server',
+    },
+];
+describe('collapseLauncherProcesses', () => {
+    it("keeps only the leaf of one npx entry's three-process chain", () => {
+        const kept = collapseLauncherProcesses(999, 1, NPX_LAUNCHER_CHAIN);
+        assert.deepEqual(kept.map((s) => s.pid), [73159]);
+    });
+    it('drops this process\'s own launchers when we are the leaf', () => {
+        const kept = collapseLauncherProcesses(73159, 72497, NPX_LAUNCHER_CHAIN.slice(0, 2));
+        assert.deepEqual(kept, []);
+    });
+    it('keeps two genuinely unrelated servers', () => {
+        const kept = collapseLauncherProcesses(1, 0, [
+            { pid: 10, ppid: 1, command: `node ${NPX_PATH}` },
+            { pid: 20, ppid: 1, command: `node ${MCPB_PATH}` },
+        ]);
+        assert.equal(kept.length, 2);
+    });
+    it('does not hang on a ppid cycle', () => {
+        const kept = collapseLauncherProcesses(1, 0, [
+            { pid: 10, ppid: 20, command: 'node a/wordpress-mcp-server/dist/index.js' },
+            { pid: 20, ppid: 10, command: 'node b/wordpress-mcp-server/dist/index.js' },
+        ]);
+        assert.ok(Array.isArray(kept));
+    });
+});
+describe('describeDuplicateEntries', () => {
+    it("flags Desmond's case: a bundle and an npx entry running at once", () => {
+        const d = describeDuplicateEntries('mcpb_bundle', [{ pid: 4242, ppid: 1, command: `node ${NPX_PATH}` }], true);
+        assert.equal(d.suspected, true);
+        assert.equal(d.confidence, 'high');
+        assert.match(String(d.message), /lists Respira twice/);
+        assert.equal(d.siblings[0].launch_mode, 'npx_cache');
+    });
+    it('stays ambiguous when the siblings were launched the same way', () => {
+        const d = describeDuplicateEntries('npx_cache', [{ pid: 1, ppid: 1, command: `node ${NPX_PATH}` }], true);
+        assert.equal(d.suspected, false);
+        assert.equal(d.confidence, 'low');
+        assert.match(String(d.message), /orphans/);
+    });
+    it('reports a clean single server when nothing else is running', () => {
+        const d = describeDuplicateEntries('mcpb_bundle', [], true);
+        assert.equal(d.suspected, false);
+        assert.equal(d.sibling_count, 0);
+    });
+    it('admits it knows nothing when the process scan could not run', () => {
+        const d = describeDuplicateEntries('unknown', [], false);
+        assert.equal(d.server_detectable, false);
+        assert.equal(d.suspected, null);
+        assert.match(String(d.message), /Check your client config by hand/);
+    });
+    it('always states the limit that a non-running duplicate is invisible', () => {
+        for (const scanned of [true, false]) {
+            const d = describeDuplicateEntries('npx_cache', [], scanned);
+            assert.match(d.limits.join(' '), /not currently running cannot be seen/);
+            assert.match(d.limits.join(' '), /deliberately does not read it/);
+        }
+    });
+});
+describe('describeTransportMode', () => {
+    it('names the protocol as stdio and rules out the remote connector', () => {
+        const t = describeTransportMode({ binaryPath: NPX_PATH, env: {} });
+        assert.equal(t.protocol, 'stdio');
+        assert.match(t.notes.join(' '), /remote HTTP connector runs inside the WordPress plugin/);
+    });
+    it('promotes a single readable mode string', () => {
+        const t = describeTransportMode({ binaryPath: MCPB_PATH, env: {} });
+        assert.equal(t.transport_mode, 'mcpb_bundle');
+        assert.equal(t.label, 'Claude Desktop .mcpb bundle');
+    });
+    it('reports the connection source verbatim, or says it is unset', () => {
+        assert.equal(describeTransportMode({ binaryPath: NPX_PATH, env: { RESPIRA_CONNECTION_SOURCE: 'dashboard_export' } }).connection_source, 'dashboard_export');
+        assert.equal(describeTransportMode({ binaryPath: NPX_PATH, env: {} }).connection_source, 'unset');
+    });
+    it('warns when a global install is quietly outranking a pinned @latest', () => {
+        const t = describeTransportMode({
+            binaryPath: '/opt/homebrew/lib/node_modules/@respira/wordpress-mcp-server/dist/index.js',
+            env: {},
+        });
+        assert.equal(t.is_global_install, true);
+        assert.match(t.notes.join(' '), /npm exec prefers the global binary/);
+    });
+    it('notices a bundle running without the setup code the bundle normally passes', () => {
+        const t = describeTransportMode({ binaryPath: MCPB_PATH, env: {} });
+        assert.match(t.notes.join(' '), /setup code may not have been saved/);
+    });
+    it('carries the duplicate signal through', () => {
+        const t = describeTransportMode({
+            binaryPath: MCPB_PATH,
+            env: {},
+            siblings: [{ pid: 9, ppid: 1, command: `node ${NPX_PATH}` }],
+            selfPid: 1000,
+            selfPpid: 1,
+        });
+        assert.equal(t.duplicate_entries.suspected, true);
+    });
+    it('does not cry wolf on a healthy npx install seen from its own leaf', () => {
+        const t = describeTransportMode({
+            binaryPath: NPX_PATH,
+            env: {},
+            siblings: NPX_LAUNCHER_CHAIN.slice(0, 2),
+            selfPid: 73159,
+            selfPpid: 72497,
+        });
+        assert.equal(t.duplicate_entries.suspected, false);
+        assert.equal(t.duplicate_entries.sibling_count, 0);
+    });
+    it('never emits a token — this output gets pasted into support threads', () => {
+        const serialised = JSON.stringify(describeTransportMode({
+            binaryPath: NPX_PATH,
+            env: {},
+            siblings: [
+                { pid: 7, ppid: 1, command: 'node /x/wordpress-mcp-server/dist/index.js --token respira_site_ABCDEF123456' },
+            ],
+            selfPid: 1000,
+            selfPpid: 1,
+        }));
+        assert.doesNotMatch(serialised, /ABCDEF123456/);
+    });
+});
+describe('redactSecrets', () => {
+    it('masks site tokens, oauth tokens and base64 config blobs', () => {
+        assert.equal(redactSecrets('key respira_site_abc123def'), 'key respira_site_***');
+        assert.equal(redactSecrets('key rsp_at_abc123def'), 'key rsp_at_***');
+        assert.match(redactSecrets('RESPIRA_CONFIG_B64=eyJzaXRlcyI6W3sidXJsIjoiaHR0cHM6Ly9hIn1dfQ=='), /\*\*\*/);
+        assert.match(redactSecrets('node run eyJzaXRlcyI6W3sidXJsIjoiaHR0cHM6Ly9hIn1dfQ=='), /<base64-config-redacted>/);
+    });
+    it('leaves an ordinary command line alone', () => {
+        const plain = 'node /usr/local/lib/node_modules/@respira/wordpress-mcp-server/dist/index.js';
+        assert.equal(redactSecrets(plain), plain);
+    });
+});
+//# sourceMappingURL=transport-mode-observability.test.js.map