@wootsup/mcp 0.1.0-rc.9 → 0.3.0

package/dist/modules/apimapper/client.js

@@ -25,8 +25,10 @@
 import { createHttpClient } from "@getimo/mcp-toolkit";
 import { Agent, setGlobalDispatcher } from "undici";
 import { sanitizeSecrets } from "./credential-sanitizer.js";
-import { getCached, setCached, isCacheableRequest, invalidateByPath, } from "./read-cache.js";
-import { WordPressPlatform, JoomlaPlatform } from "../../platform/index.js";
+import { getCached, setCached, isCacheableRequest, invalidateByPath, clearCache, } from "./read-cache.js";
+import { WordPressPlatform, JoomlaPlatform, isPlatformResponseError, isJoomlaUnsupportedPathError } from "../../platform/index.js";
+import { loadSitesRegistry } from "../../sites/loader.js";
+import { resolveSiteBearer } from "../../sites/secret-resolver.js";
 // Perf-#1 (2026-05-19): HTTP keep-alive connection pool.
 //
 // A typical customer flow fires 9-10 sequential tool calls against the same
@@ -58,8 +60,44 @@ if (process.env.APIMAPPER_TOKEN && !process.env.APIMAPPER_WP_APP_PASS) {
 if (process.env.APIMAPPER_SITE_URL && !process.env.APIMAPPER_WP_BASE) {
     process.env.APIMAPPER_WP_BASE = process.env.APIMAPPER_SITE_URL;
 }
-export const WP_BASE = (process.env.APIMAPPER_WP_BASE || "https://dev.wootsup.com/wordpress").replace(/\/$/, "");
-export const WP_USER = process.env.APIMAPPER_WP_USER || "getimo";
+// M-9 (2026-05-28): accept the documented `APIMAPPER_BASE_URL` alias.
+// See src/index.ts for the rationale — both ESM entrypoints bridge the
+// same set of aliases so module-evaluation order doesn't matter.
+if (process.env.APIMAPPER_BASE_URL && !process.env.APIMAPPER_WP_BASE) {
+    process.env.APIMAPPER_WP_BASE = process.env.APIMAPPER_BASE_URL;
+}
+/**
+ * WordPress / Joomla site base URL.
+ *
+ * Env-var precedence: `APIMAPPER_WP_BASE` → `APIMAPPER_SITE_URL` (alias
+ * written by the DXT setup wizard) → empty string.
+ *
+ * The SITE_URL → WP_BASE bridge is handled exactly once, above, via
+ * `process.env.APIMAPPER_WP_BASE = process.env.APIMAPPER_SITE_URL`. This
+ * keeps a single source of truth in `process.env` so any consumer
+ * (including child processes spawned later, R7 verify scripts, and
+ * legacy CustomGraph internal code) sees the same value — not just
+ * this module's exported `WP_BASE` constant.
+ *
+ * Empty default is intentional (F-43, 2026-05-19): a freshly-installed
+ * customer who has not run the setup wizard must NOT silently inherit
+ * the WootsUp dev URL — that leaked the vendor's setup hostname into
+ * customer error logs and confused triage. In production (NODE_ENV
+ * === "production") an empty value causes a fail-fast exit below.
+ *
+ * Trailing slash is normalised away so downstream `${WP_BASE}/...` joins
+ * never produce double-slashes.
+ */
+export const WP_BASE = (process.env.APIMAPPER_WP_BASE || "").replace(/\/$/, "");
+/**
+ * WordPress username for legacy Application-Password Basic auth.
+ *
+ * Empty default is intentional (F-44, 2026-05-19): the previous "getimo"
+ * default leaked a personal username into customer 401 logs. Customers
+ * using the modern Bearer-token flow (`amk_live_...`) don't need this
+ * value at all; legacy users must set `APIMAPPER_WP_USER` explicitly.
+ */
+export const WP_USER = process.env.APIMAPPER_WP_USER || "";
 export const WP_APP_PASS = process.env.APIMAPPER_WP_APP_PASS || "";
 // Auth-shape detection: the credential the customer pastes during setup can
 // be either a WordPress Application Password (legacy / power-user path) or
@@ -73,12 +111,22 @@ const BASIC_TOKEN = !IS_MCP_BEARER && WP_APP_PASS
     ? Buffer.from(`${WP_USER}:${WP_APP_PASS}`, "utf8").toString("base64")
     : "";
 const BEARER_TOKEN = IS_MCP_BEARER ? WP_APP_PASS : "";
-if (!BASIC_TOKEN && !BEARER_TOKEN && process.env.NODE_ENV === "production") {
-    // Fail-fast: prevents silent unauthenticated client → opaque 401s downstream.
-    // In test/dev we keep the client buildable so unit tests don't require a vault.
-    console.error("[apimapper-mcp] ERROR: APIMAPPER_TOKEN is not set. Run `npx -y @wootsup/mcp setup` " +
-        "to generate a key and configure your AI client. Refusing to start in production.");
-    process.exit(2);
+// F-43+F-44 production fail-fast (2026-05-19): two independent guards. The
+// WP_BASE check runs first and short-circuits via process.exit(2) so we
+// never log two errors for one mis-configured install. In test/dev we keep
+// the client buildable so unit tests don't require a vault.
+if (process.env.NODE_ENV === "production") {
+    if (!WP_BASE) {
+        console.error("[apimapper-mcp] ERROR: APIMAPPER_WP_BASE (or APIMAPPER_SITE_URL) is not set. " +
+            "Run `npx -y @wootsup/mcp setup` to configure your AI client. Refusing to start in production.");
+        process.exit(2);
+    }
+    if (!BASIC_TOKEN && !BEARER_TOKEN) {
+        // Fail-fast: prevents silent unauthenticated client → opaque 401s downstream.
+        console.error("[apimapper-mcp] ERROR: APIMAPPER_TOKEN is not set. Run `npx -y @wootsup/mcp setup` " +
+            "to generate a key and configure your AI client. Refusing to start in production.");
+        process.exit(2);
+    }
 }
 const rawApi = createHttpClient({
     baseUrl: `${WP_BASE}/wp-json/api-mapper/v1`,
@@ -113,12 +161,41 @@ function classify(status) {
         return "auth";
     if (status === 404)
         return "not_found";
+    // M1 (MCP-relay audit) — 409 is a distinct, recoverable outcome: the
+    // library-first guard block and optimistic-lock conflicts both use it. Map
+    // it to its own code so callers can branch on "conflict" without re-parsing
+    // the status. hintFor() falls through to HEALTH_HINT for it (no auth/retry
+    // recovery applies to a deliberate guard block — the structured errorBody
+    // carries the actionable next step instead).
+    if (status === 409)
+        return "conflict";
     if (status === 429)
         return "rate_limit";
     if (status >= 500)
         return "server";
     return "unknown";
 }
+/**
+ * Recover the upstream HTTP status carried inside a Joomla com_ajax failure
+ * envelope. com_ajax always returns HTTP 200 and signals the real status in a
+ * `code` field on the `{success:false, error, code}` body (mirrors what the
+ * admin-ui Joomla client reads — `resultObj.code === 409` / `=== 404`). Both a
+ * numeric `code` (`409`) and a stringified numeric `code` (`"409"`) are
+ * accepted; non-numeric / absent values yield `undefined` so the caller keeps
+ * the transport status (or falls through to `"unknown"`). This is the single
+ * point that lets `classify()` restore 409/404/422/429/502 fidelity on Joomla.
+ */
+function numericCodeFromBody(body) {
+    if (!body || typeof body !== "object")
+        return undefined;
+    const raw = body.code;
+    if (typeof raw === "number" && Number.isFinite(raw))
+        return raw;
+    if (typeof raw === "string" && /^\d+$/.test(raw.trim())) {
+        return Number.parseInt(raw, 10);
+    }
+    return undefined;
+}
 const DEFAULT_TIMEOUT_MS = 45_000;
 const MIN_TIMEOUT_MS = 1_000;
 const MAX_TIMEOUT_MS = 300_000;
@@ -126,6 +203,140 @@ function resolveTimeout(opts) {
     const t = opts?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
     return Math.max(MIN_TIMEOUT_MS, Math.min(MAX_TIMEOUT_MS, t));
 }
+async function performFetch(cfg) {
+    const { url, headers, init, opts, parseResponse, preferMessageKey = true, attachErrorBody = false, textSuccessFalseGuard = false, } = cfg;
+    let status;
+    const timeoutMs = resolveTimeout(opts);
+    try {
+        const res = await fetch(url, {
+            ...init,
+            headers,
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        status = res.status;
+        const text = await res.text();
+        if (!res.ok) {
+            let parsed = text;
+            try {
+                parsed = JSON.parse(text);
+            }
+            catch {
+                // keep as text
+            }
+            const errMsg = preferMessageKey && typeof parsed === "object" && parsed && "message" in parsed
+                ? String(parsed.message)
+                : typeof parsed === "object" && parsed && "error" in parsed
+                    ? String(parsed.error)
+                    : `HTTP ${res.status}`;
+            const errorBody = typeof parsed === "object" && parsed !== null
+                ? parsed
+                : undefined;
+            return {
+                success: false,
+                error: sanitizeErrorString(errMsg),
+                status,
+                errorCode: classify(status),
+                // W2-3: the WP path ALWAYS carried an `errorBody` key on a non-2xx
+                // response (the value is `undefined` when the body wasn't JSON). The
+                // Joomla + absolute paths never set it. `attachErrorBody` reproduces
+                // that key-presence difference exactly.
+                ...(attachErrorBody ? { errorBody } : {}),
+            };
+        }
+        if (!text)
+            return { success: true, data: {}, status };
+        let data;
+        try {
+            data = JSON.parse(text);
+        }
+        catch {
+            // Non-JSON body. The absolute path additionally treats a text body that
+            // contains `success:false` as a payload failure under unwrapInnerSuccess.
+            if (textSuccessFalseGuard &&
+                opts.unwrapInnerSuccess &&
+                /success["']?\s*:\s*false/i.test(text)) {
+                return {
+                    success: false,
+                    error: sanitizeErrorString(`text response indicates success:false — ${text.slice(0, 200)}`),
+                    status,
+                    errorCode: "unknown",
+                    payloadFailed: true,
+                };
+            }
+            // Otherwise pass through as text.
+            return { success: true, data: text, status };
+        }
+        // Run the (platform-specific or identity) envelope unwrap. A Joomla
+        // success:false envelope throws a PlatformResponseError carrying the parsed
+        // body; we translate that to a structured failure so callers see a uniform
+        // shape regardless of platform.
+        let unwrapped;
+        try {
+            unwrapped = parseResponse(data, init.method ?? "GET");
+        }
+        catch (e) {
+            // errorCode fidelity (WP↔Joomla parity fix 2026-06-07): a Joomla
+            // com_ajax failure throws a PlatformResponseError carrying the parsed
+            // envelope. com_ajax always returns HTTP 200, so the transport `status`
+            // is 200 — useless for classification. The REAL upstream status lives in
+            // the envelope `code` field. Recover it and run it through the SAME
+            // classify() the WordPress non-2xx path uses, restoring 409("conflict") /
+            // 404 / 422 / 429 / 502 fidelity on Joomla (fixes the live "guard 409
+            // shows as unknown on Joomla" loss). When the envelope carries no numeric
+            // code we keep "unknown" (no regression for handlers that omit it) and
+            // preserve the transport `status`.
+            const errorBody = isPlatformResponseError(e) ? e.body : undefined;
+            const envelopeStatus = numericCodeFromBody(errorBody);
+            return {
+                success: false,
+                error: sanitizeErrorString(e instanceof Error ? e.message : String(e)),
+                status: envelopeStatus ?? status,
+                errorCode: envelopeStatus !== undefined ? classify(envelopeStatus) : "unknown",
+                payloadFailed: true,
+                errorBody,
+            };
+        }
+        // unwrapInnerSuccess: treat 200 + `{success:false}` payload as an error
+        // (WP REST sometimes returns inner-success envelopes for connection_test,
+        // license_activate, etc.).
+        if (opts.unwrapInnerSuccess &&
+            unwrapped &&
+            typeof unwrapped === "object" &&
+            "success" in unwrapped) {
+            const inner = unwrapped.success;
+            if (inner === false) {
+                const innerErr = unwrapped.error !== undefined
+                    ? String(unwrapped.error)
+                    : "operation reported success:false in payload";
+                return {
+                    success: false,
+                    error: sanitizeErrorString(innerErr),
+                    status,
+                    errorCode: "unknown",
+                    payloadFailed: true,
+                };
+            }
+        }
+        const out = opts.sanitize ? sanitizeSecrets(unwrapped) : unwrapped;
+        return { success: true, data: out, status };
+    }
+    catch (e) {
+        // AbortSignal.timeout fires "TimeoutError" or "AbortError" depending on the
+        // Node version — classify both as network/timeout.
+        if (e instanceof Error && (e.name === "AbortError" || e.name === "TimeoutError")) {
+            return {
+                success: false,
+                error: `request timed out after ${Math.round(timeoutMs / 1000)}s`,
+                errorCode: "network",
+            };
+        }
+        return {
+            success: false,
+            error: sanitizeErrorString(e instanceof Error ? e.message : String(e)),
+            errorCode: "network",
+        };
+    }
+}
 /**
  * Create a Platform-aware HTTP client. The Platform handles URL construction,
  * auth header injection, and response envelope unwrap (e.g. Joomla's
@@ -137,109 +348,26 @@ export function createPlatformClient(platform) {
     return {
         platform,
         request: async (action, init = {}, opts = {}) => {
-            let status;
-            const timeoutMs = resolveTimeout(opts);
-            try {
-                const url = platform.buildUrl(action);
-                const res = await fetch(url, {
-                    ...init,
-                    headers: {
-                        Accept: "application/json",
-                        "Content-Type": "application/json",
-                        "X-Requested-With": "XMLHttpRequest",
-                        ...platform.buildAuthHeaders(init.method ?? "GET"),
-                        ...init.headers,
-                    },
-                    signal: AbortSignal.timeout(timeoutMs),
-                });
-                status = res.status;
-                const text = await res.text();
-                if (!res.ok) {
-                    let parsed = text;
-                    try {
-                        parsed = JSON.parse(text);
-                    }
-                    catch {
-                        // keep as text
-                    }
-                    const errMsg = typeof parsed === "object" && parsed && "message" in parsed
-                        ? String(parsed.message)
-                        : typeof parsed === "object" && parsed && "error" in parsed
-                            ? String(parsed.error)
-                            : `HTTP ${res.status}`;
-                    return {
-                        success: false,
-                        error: sanitizeErrorString(errMsg),
-                        status,
-                        errorCode: classify(status),
-                    };
-                }
-                if (!text)
-                    return { success: true, data: {}, status };
-                let data;
-                try {
-                    data = JSON.parse(text);
-                }
-                catch {
-                    // Non-JSON body — pass through as text.
-                    return { success: true, data: text, status };
-                }
-                // Run the platform-specific envelope unwrap. Joomla throws on
-                // success:false; we translate that to a structured failure so
-                // tools see a uniform shape regardless of platform.
-                let unwrapped;
-                try {
-                    unwrapped = platform.parseResponse(data, init.method ?? "GET");
-                }
-                catch (e) {
-                    return {
-                        success: false,
-                        error: sanitizeErrorString(e instanceof Error ? e.message : String(e)),
-                        status,
-                        errorCode: "unknown",
-                        payloadFailed: true,
-                    };
-                }
-                // unwrapInnerSuccess for WordPress: treat 200 + `{success:false}`
-                // payload as error (WP REST sometimes returns inner-success envelopes
-                // for connection_test, license_activate, etc.).
-                if (opts.unwrapInnerSuccess &&
-                    unwrapped &&
-                    typeof unwrapped === "object" &&
-                    "success" in unwrapped) {
-                    const inner = unwrapped.success;
-                    if (inner === false) {
-                        const innerErr = unwrapped.error !== undefined
-                            ? String(unwrapped.error)
-                            : "operation reported success:false in payload";
-                        return {
-                            success: false,
-                            error: sanitizeErrorString(innerErr),
-                            status,
-                            errorCode: "unknown",
-                            payloadFailed: true,
-                        };
-                    }
-                }
-                const out = opts.sanitize ? sanitizeSecrets(unwrapped) : unwrapped;
-                return { success: true, data: out, status };
-            }
-            catch (e) {
-                // AbortSignal.timeout fires "TimeoutError" or "AbortError" depending on
-                // Node version — classify both as network/timeout.
-                if (e instanceof Error && (e.name === "AbortError" || e.name === "TimeoutError")) {
-                    return {
-                        success: false,
-                        error: `request timed out after ${Math.round(timeoutMs / 1000)}s`,
-                        errorCode: "network",
-                    };
-                }
-                return {
-                    success: false,
-                    error: sanitizeErrorString(e instanceof Error ? e.message : String(e)),
-                    errorCode: "network",
-                };
-            }
+            // A3 dedup: the WP path builds its URL + auth headers, then defers the
+            // shared fetch → parse → unwrap → sanitize pipeline to performFetch.
+            // attachErrorBody:true preserves the W2-3 errorBody passthrough; the
+            // parseResponse is the platform's own envelope unwrap (Joomla throws a
+            // PlatformResponseError on success:false, threaded into errorBody by the
+            // shared core).
+            return performFetch({
+                url: platform.buildUrl(action),
+                headers: {
+                    Accept: "application/json",
+                    "Content-Type": "application/json",
+                    "X-Requested-With": "XMLHttpRequest",
+                    ...platform.buildAuthHeaders(init.method ?? "GET"),
+                    ...init.headers,
+                },
+                init,
+                opts,
+                parseResponse: (data, method) => platform.parseResponse(data, method),
+                attachErrorBody: true,
+            });
         },
     };
 }
@@ -271,24 +399,314 @@ class WordPressBasicAuthPlatform extends WordPressPlatform {
         return {};
     }
 }
-const PLATFORM_KIND = (process.env.APIMAPPER_PLATFORM ?? "wordpress");
-const legacyPlatform = PLATFORM_KIND === "joomla"
-    ? new JoomlaPlatform({
-        // Joomla uses the same APIMAPPER_WP_BASE env var (or APIMAPPER_SITE_URL
-        // alias bridged by the DXT bootstrap in src/index.ts). The token is the
-        // raw amk_live_... bearer the setup CLI stored in the keychain. We
-        // accept the WP_USER:WP_APP_PASS pair too — split on the colon and use
-        // the password as the bearer for ergonomic parity with the WP env vars.
-        baseUrl: WP_BASE,
-        token: process.env.APIMAPPER_TOKEN
-            ?? (BASIC_TOKEN ? Buffer.from(BASIC_TOKEN, "base64").toString().split(":")[1] ?? "" : ""),
-    })
-    : new WordPressBasicAuthPlatform({
-        baseUrl: WP_BASE,
-        basicToken: BASIC_TOKEN,
-        bearerToken: BEARER_TOKEN,
-    });
-const legacyClient = createPlatformClient(legacyPlatform);
+// A1-P2 (W1-polish): Narrow the platform-kind selection with a case-strict
+// `=== "joomla"` check instead of an unsafe `as` cast on the raw env value.
+// The cast silently coerced any string ("WORDPRESS", "standalone", typos
+// like "jooma") into the union type, even though the runtime ternary below
+// only branches on the exact literal "joomla". Aligning the type with the
+// actual decision keeps a future widening (.toLowerCase(), trim, etc.) from
+// flipping behaviour silently — anything that isn't the literal "joomla"
+// must continue to default to WordPress.
+//
+// Phase 1 (2026-06-03): PLATFORM_KIND remains the EXPLICIT env→kind mapping
+// (the "hint"). It is read by the build-dxt grep gate (a literal
+// `process.env.APIMAPPER_PLATFORM` consumer must live in src/) and by 6
+// client.test.ts assertions. The NETWORK auto-detect (probePlatform +
+// resolveLegacy below) layers ON TOP of it: it is consulted ONLY when the env
+// var is neither the literal "wordpress" nor "joomla" (i.e. unset or "auto").
+export const PLATFORM_KIND = process.env.APIMAPPER_PLATFORM === "joomla" ? "joomla" : "wordpress";
+/**
+ * The Bearer token the legacy platform clients authenticate with. The setup
+ * CLI stores the raw `amk_live_…` MCP key; legacy App-Password users instead
+ * set WP_USER:WP_APP_PASS, in which case we recover the password half from the
+ * pre-computed BASIC_TOKEN. Computed once — both the identity probe and the
+ * resolved platform reuse it so the wire-level auth is identical.
+ */
+const LEGACY_BEARER = process.env.APIMAPPER_TOKEN
+    ?? (BASIC_TOKEN ? Buffer.from(BASIC_TOKEN, "base64").toString().split(":")[1] ?? "" : "");
+/**
+ * Build the Authorization header the identity probe sends. Prefers the modern
+ * Bearer token (amk_live_… / recovered App-Password) and falls back to the
+ * legacy Basic header so a pure WP_USER:WP_APP_PASS install still probes
+ * authenticated. Empty object when no credential is configured (the probe then
+ * relies on a public identity endpoint, degrading to the WordPress fallback).
+ */
+function probeAuthHeader() {
+    if (LEGACY_BEARER)
+        return { Authorization: `Bearer ${LEGACY_BEARER}` };
+    if (BASIC_TOKEN)
+        return { Authorization: `Basic ${BASIC_TOKEN}` };
+    return {};
+}
+const PROBE_TIMEOUT_MS = 8_000;
+/**
+ * Network platform auto-detect. Concurrently probes the WordPress REST identity
+ * endpoint and the Joomla com_ajax getIdentity task with the same auth header,
+ * and decides which CMS is actually running at WP_BASE:
+ *
+ *   - Joomla wins if its probe is HTTP 200 AND the body parses to
+ *     `{success:true, data:[{success:true, …}]}` (or `data[0].platform` set).
+ *   - WordPress wins if its probe is HTTP 200 AND the body is a JSON object
+ *     that is NOT a `{success:false}` error envelope.
+ *   - If both look OK (shouldn't happen on a single CMS), prefer the one whose
+ *     reported identity `.platform` matches its own kind; else WordPress.
+ *   - If neither answers → return "wordpress" (graceful fallback — no worse
+ *     than the pre-Phase-1 silent default).
+ *
+ * All fetch errors are swallowed → fallback. The token is sent on the wire but
+ * never logged. Short timeout so a blocked probe host can't stall startup.
+ *
+ * Phase 3 (2026-06-03): accepts optional `(baseUrl, token)` overrides so a
+ * per-site probe (sites-file path) can target the entry's own URL + token. The
+ * no-arg call preserves the env-path behaviour exactly (module WP_BASE +
+ * probeAuthHeader()).
+ */
+export async function probePlatform(baseUrl, token) {
+    const base = (baseUrl ?? WP_BASE).replace(/\/$/, "");
+    if (!base)
+        return "wordpress";
+    const headers = {
+        Accept: "application/json",
+        "X-Requested-With": "XMLHttpRequest",
+        ...(token ? { Authorization: `Bearer ${token}` } : probeAuthHeader()),
+    };
+    const wpUrl = `${base}/wp-json/api-mapper/v1/identity`;
+    const joomlaUrl = `${base}/index.php?option=com_ajax&plugin=apimapper&task=getIdentity&format=json`;
+    async function probe(url) {
+        try {
+            const res = await fetch(url, {
+                method: "GET",
+                headers,
+                signal: AbortSignal.timeout(PROBE_TIMEOUT_MS),
+            });
+            if (!res.ok)
+                return { ok: false, body: undefined };
+            const text = await res.text();
+            let body;
+            try {
+                body = JSON.parse(text);
+            }
+            catch {
+                return { ok: false, body: undefined };
+            }
+            return { ok: true, body };
+        }
+        catch {
+            // Network error / timeout / abort → treat as "no answer".
+            return null;
+        }
+    }
+    const [wp, joomla] = await Promise.all([probe(wpUrl), probe(joomlaUrl)]);
+    const joomlaLooksOk = (() => {
+        if (!joomla?.ok)
+            return false;
+        const b = joomla.body;
+        if (!b || typeof b !== "object" || !("success" in b))
+            return false;
+        if (b.success !== true)
+            return false;
+        const data = b.data;
+        if (!Array.isArray(data) || data.length === 0)
+            return false;
+        const first = data[0];
+        if (!first || typeof first !== "object")
+            return false;
+        const f = first;
+        return f.success === true || f.platform !== undefined;
+    })();
+    const wpLooksOk = (() => {
+        if (!wp?.ok)
+            return false;
+        const b = wp.body;
+        if (!b || typeof b !== "object")
+            return false;
+        // A WP identity object is a plain object; explicitly reject an error
+        // envelope ({success:false}) so a Joomla 200 success:false leaking through
+        // a misconfigured route doesn't masquerade as a WordPress identity.
+        if ("success" in b && b.success === false)
+            return false;
+        return true;
+    })();
+    if (joomlaLooksOk && wpLooksOk) {
+        // Both answered (one CMS shouldn't expose both). Disambiguate by the
+        // self-reported platform, else fall back to WordPress.
+        const data = (joomla?.body).data;
+        const jPlatform = data?.[0]?.platform;
+        if (jPlatform === "joomla")
+            return "joomla";
+        return "wordpress";
+    }
+    if (joomlaLooksOk)
+        return "joomla";
+    if (wpLooksOk)
+        return "wordpress";
+    return "wordpress";
+}
+/**
+ * Build the legacy Platform + PlatformClient for a resolved kind. Reproduces
+ * exactly the per-kind construction the old module-eval consts performed.
+ */
+function buildLegacy(kind) {
+    const platform = kind === "joomla"
+        ? new JoomlaPlatform({
+            // Joomla uses the same APIMAPPER_WP_BASE env var (or
+            // APIMAPPER_SITE_URL alias bridged by the DXT bootstrap). The token
+            // is the raw amk_live_… bearer; we also accept the WP_USER:WP_APP_PASS
+            // pair (the password half recovered into LEGACY_BEARER).
+            baseUrl: WP_BASE,
+            token: LEGACY_BEARER,
+        })
+        : new WordPressBasicAuthPlatform({
+            baseUrl: WP_BASE,
+            basicToken: BASIC_TOKEN,
+            bearerToken: BEARER_TOKEN,
+        });
+    return { platform, client: createPlatformClient(platform) };
+}
+// ── Phase 3: sites-file multi-site (active-site routing) ───────────────
+//
+// When APIMAPPER_SITES_FILE points at a non-empty sites.json, resolveLegacy()
+// resolves the ACTIVE site's {baseUrl, token, platform} from the file rather
+// than the env single-site vars. The active selection is an in-memory pointer
+// (`_activeSiteId`) that `setActiveSite()` flips; when unset the file's default
+// entry is used. Switching the pointer resets the resolution memo so the very
+// next `request()` retargets the new site. The keychain ProfileStore path
+// (src/auth/profiles.ts) stays the single-machine default — the two mechanisms
+// coexist; the sites-file wins ONLY when the env var is set + the file loads
+// non-empty.
+/** Memoized sites-file registry. `null` = no usable sites-file (env path). */
+let _sitesRegistry;
+/**
+ * Lazily load + memoize the sites-file registry from APIMAPPER_SITES_FILE.
+ * Returns `null` when the env var is unset/empty, the file is absent, or it has
+ * zero sites — in all those cases the caller falls through to the env path.
+ * A malformed / schema-invalid file throws `SitesFileError` (loud-fail at first
+ * use rather than silently degrading multi-site to single-site).
+ */
+export function getSitesRegistry() {
+    if (_sitesRegistry !== undefined)
+        return _sitesRegistry;
+    _sitesRegistry = loadSitesRegistry(process.env.APIMAPPER_SITES_FILE);
+    return _sitesRegistry;
+}
+/** In-memory active-site pointer. Only meaningful when a sites-file is loaded. */
+let _activeSiteId;
+/**
+ * The currently-active site_id, or `null` when none has been explicitly set
+ * (the file's default entry is then used) or when no sites-file is loaded.
+ */
+export function getActiveSiteId() {
+    return _activeSiteId ?? null;
+}
+/**
+ * Switch the active site. Validates that `id` exists in the loaded sites-file
+ * registry, updates the in-memory pointer, and resets the resolution memo so
+ * the next `request()` re-resolves (URL + token + platform) against the new
+ * site. Throws when no sites-file is loaded or the id is unknown — the pointer
+ * is NOT changed on error.
+ */
+export function setActiveSite(id) {
+    const reg = getSitesRegistry();
+    if (!reg) {
+        throw new Error("setActiveSite: no sites-file loaded (APIMAPPER_SITES_FILE unset or empty). " +
+            "Multi-site switching via a sites-file is unavailable.");
+    }
+    if (!reg.has(id)) {
+        throw new Error(`setActiveSite: unknown site_id "${id}". Known: ${reg.listIds().join(", ") || "(none)"}.`);
+    }
+    _activeSiteId = id;
+    _legacyResolution = undefined;
+    // The read-cache is keyed by path+method, NOT by site — switching the active
+    // backend would otherwise serve the previous site's cached GET responses.
+    // Flush it so reads after a switch hit the newly-targeted site.
+    clearCache();
+}
+/**
+ * Build the legacy Platform + client for a single sites-file entry. The entry's
+ * own url + resolved token + platform hint drive construction; an `auto` hint
+ * triggers a per-entry network probe against the entry's URL.
+ */
+async function buildLegacyForSite(entry) {
+    const { token } = await resolveSiteBearer(entry);
+    const baseUrl = entry.url.replace(/\/$/, "");
+    const kind = entry.platform === "joomla"
+        ? "joomla"
+        : entry.platform === "wordpress"
+            ? "wordpress"
+            : await probePlatform(baseUrl, token);
+    const platform = kind === "joomla"
+        ? new JoomlaPlatform({ baseUrl, token })
+        : // Sites-file always carries a Bearer (amk_…) token — use the Bearer
+            // branch of the WP platform (no legacy Basic App-Password here).
+            new WordPressBasicAuthPlatform({ baseUrl, basicToken: "", bearerToken: token });
+    return { platform, client: createPlatformClient(platform) };
+}
+/**
+ * Lazy, memoized platform resolution for the legacy `request()` path.
+ *
+ * Replaces the former module-eval `legacyPlatform`/`legacyClient` consts so the
+ * network probe (which is async) can run on first use without blocking ESM
+ * evaluation. Resolution order:
+ *
+ *   1. **sites-file** (APIMAPPER_SITES_FILE set + loads non-empty): the active
+ *      entry = the in-memory active-site pointer if set, else the file's default
+ *      entry. Its url/token drive the client; platform = the entry's explicit
+ *      hint or (when `auto`) a per-entry probe of the entry's URL.
+ *   2. explicit env `APIMAPPER_PLATFORM === "joomla"` → Joomla, NO probe.
+ *   3. explicit env `APIMAPPER_PLATFORM === "wordpress"` → WordPress, NO probe.
+ *   4. anything else (unset / "auto") → `await probePlatform()` against WP_BASE.
+ *
+ * The result is memoized for the lifetime of the module instance — a second
+ * `request()` reuses it without re-probing. `setActiveSite()` and
+ * `resetPlatformResolution()` clear the memo. Tests reset via
+ * `__resetPlatformResolutionForTests()` (an alias of resetPlatformResolution).
+ */
+let _legacyResolution;
+function resolveLegacy() {
+    if (_legacyResolution)
+        return _legacyResolution;
+    _legacyResolution = (async () => {
+        const reg = getSitesRegistry();
+        if (reg) {
+            const entry = (_activeSiteId ? reg.get(_activeSiteId) : null) ?? reg.getDefault();
+            return buildLegacyForSite(entry);
+        }
+        const env = process.env.APIMAPPER_PLATFORM;
+        const kind = env === "joomla"
+            ? "joomla"
+            : env === "wordpress"
+                ? "wordpress"
+                : await probePlatform();
+        return buildLegacy(kind);
+    })();
+    return _legacyResolution;
+}
+/**
+ * Drop the memoized platform resolution (and the cached sites-file registry +
+ * active-site pointer) so the next `request()` re-resolves from scratch —
+ * re-reading APIMAPPER_SITES_FILE, re-running the env-check / network probe.
+ *
+ * Production callers: invoke after deliberately changing the active selection
+ * outside `setActiveSite()` (the tool wiring uses `setActiveSite`, which already
+ * resets the memo). Safe to call any time.
+ */
+export function resetPlatformResolution() {
+    _legacyResolution = undefined;
+    _sitesRegistry = undefined;
+    _activeSiteId = undefined;
+    // Drop any cached GET responses too — a full re-resolution may re-target a
+    // different backend (sites-file reload / active-site change), and the
+    // read-cache is not site-aware.
+    clearCache();
+}
+/**
+ * Test-only alias of {@link resetPlatformResolution}, kept for the existing
+ * Phase-1 client tests that reference it by this name. New code should call
+ * `resetPlatformResolution()`.
+ */
+export function __resetPlatformResolutionForTests() {
+    resetPlatformResolution();
+}
 /**
  * Issue a request through the toolkit HTTP client + capture HTTP status.
  *
@@ -310,28 +728,39 @@ export async function request(path, init = {}, opts = {}) {
     const upperMethod = method.toUpperCase();
     const cacheEligible = !opts.noCache && isCacheableRequest(upperMethod, path);
     if (cacheEligible) {
-        const hit = getCached(upperMethod, path);
+        // F-02 (2026-05-19): the sanitize flag participates in the cache key.
+        // Without this, a sanitized response could be served to a raw-mode
+        // caller (or vice versa) on the same URL — Defense-in-Depth gap A5.
+        const hit = getCached(upperMethod, path, { sanitize: opts.sanitize });
         if (hit)
             return hit;
     }
     // Strip the leading "/" — Platform.buildUrl() takes a bare action name.
     // Also tolerate the existing escape-hatch where `path` starts with "http"
     // (absolute URL); fall back to raw fetch in that case.
+    //
+    // Phase 1 (2026-06-03): the legacy platform is now resolved lazily (env-hint
+    // first, network probe when unset/auto) + memoized. resolveLegacy() awaits at
+    // most one probe round-trip on the very first request; subsequent calls reuse
+    // the cached resolution.
     let response;
     if (path.startsWith("http")) {
         response = await rawAbsoluteRequest(path, init, opts);
     }
-    else if (legacyPlatform instanceof JoomlaPlatform) {
-        // Joomla branch — translate REST path → com_ajax task + params.
-        response = await joomlaRequest(legacyPlatform, path, init, opts);
-    }
     else {
-        const action = path.replace(/^\/+/, "");
-        response = await legacyClient.request(action, init, opts);
+        const { platform, client } = await resolveLegacy();
+        if (platform instanceof JoomlaPlatform) {
+            // Joomla branch — translate REST path → com_ajax task + params.
+            response = await joomlaRequest(platform, path, init, opts);
+        }
+        else {
+            const action = path.replace(/^\/+/, "");
+            response = await client.request(action, init, opts);
+        }
     }
     // Cache successful responses; never cache errors so the next call retries.
     if (cacheEligible && response.success) {
-        setCached(upperMethod, path, response);
+        setCached(upperMethod, path, response, { sanitize: opts.sanitize });
     }
     // Mutation invalidation: any non-GET that succeeded clears the read-cache
     // for the touched path-prefix. Conservative — better to over-invalidate
@@ -352,86 +781,51 @@ async function joomlaRequest(platform, path, init, opts) {
         translated = platform.translateRestPath(path, init.method ?? "GET");
     }
     catch (e) {
-        return {
-            success: false,
-            error: sanitizeErrorString(e instanceof Error ? e.message : String(e)),
-            errorCode: "unknown",
-        };
-    }
-    let status;
-    const timeoutMs = resolveTimeout(opts);
-    try {
-        const url = platform.buildUrl(translated.action, translated.params);
-        const res = await fetch(url, {
-            ...init,
-            headers: {
-                Accept: "application/json",
-                "Content-Type": "application/json",
-                "X-Requested-With": "XMLHttpRequest",
-                ...platform.buildAuthHeaders(init.method ?? "GET"),
-                ...init.headers,
-            },
-            signal: AbortSignal.timeout(timeoutMs),
-        });
-        status = res.status;
-        const text = await res.text();
-        if (!res.ok) {
-            let parsed = text;
-            try {
-                parsed = JSON.parse(text);
-            }
-            catch {
-                /* keep as text */
-            }
-            const errMsg = typeof parsed === "object" && parsed && "error" in parsed
-                ? String(parsed.error)
-                : `HTTP ${res.status}`;
+        // HIGH cross-platform finding (Wave-B audit, 2026-06-03): distinguish a
+        // genuinely WordPress-only feature from an unknown/typo path. For WP-only
+        // paths translateRestPath raises `JoomlaUnsupportedPathError`; surface it
+        // as a clean structured result (`errorCode: "not_found"` + `errorBody`
+        // carrying `unsupported: true`) so the tool's errorResult reads as
+        // "feature not available on Joomla" instead of leaking the opaque
+        // "no joomla mapping … (unknown rest path)" internal string.
+        if (isJoomlaUnsupportedPathError(e)) {
             return {
                 success: false,
-                error: sanitizeErrorString(errMsg),
-                status,
-                errorCode: classify(status),
-            };
-        }
-        if (!text)
-            return { success: true, data: {}, status };
-        let data;
-        try {
-            data = JSON.parse(text);
-        }
-        catch {
-            return { success: true, data: text, status };
-        }
-        let unwrapped;
-        try {
-            unwrapped = platform.parseResponse(data, init.method ?? "GET");
-        }
-        catch (e) {
-            return {
-                success: false,
-                error: sanitizeErrorString(e instanceof Error ? e.message : String(e)),
-                status,
-                errorCode: "unknown",
-                payloadFailed: true,
-            };
-        }
-        const out = opts.sanitize ? sanitizeSecrets(unwrapped) : unwrapped;
-        return { success: true, data: out, status };
-    }
-    catch (e) {
-        if (e instanceof Error && (e.name === "AbortError" || e.name === "TimeoutError")) {
-            return {
-                success: false,
-                error: `request timed out after ${Math.round(timeoutMs / 1000)}s`,
-                errorCode: "network",
+                error: sanitizeErrorString(e.message),
+                errorCode: "not_found",
+                errorBody: {
+                    unsupported: true,
+                    platform: "joomla",
+                    path: e.path,
+                },
             };
         }
         return {
             success: false,
             error: sanitizeErrorString(e instanceof Error ? e.message : String(e)),
-            errorCode: "network",
+            errorCode: "unknown",
         };
     }
+    // A3 dedup: Joomla builds its translated com_ajax URL + auth headers, then
+    // defers to the shared core. preferMessageKey:false mirrors the original
+    // Joomla branch that reads only the `error` key; attachErrorBody stays off
+    // (the non-2xx errorBody passthrough is WP-only). The success:false com_ajax
+    // envelope is raised as a PlatformResponseError by parseResponse and threaded
+    // into errorBody by performFetch — identical to the WP path.
+    return performFetch({
+        url: platform.buildUrl(translated.action, translated.params),
+        headers: {
+            Accept: "application/json",
+            "Content-Type": "application/json",
+            "X-Requested-With": "XMLHttpRequest",
+            ...platform.buildAuthHeaders(init.method ?? "GET"),
+            ...init.headers,
+        },
+        init,
+        opts,
+        parseResponse: (data, method) => platform.parseResponse(data, method),
+        preferMessageKey: false,
+    });
 }
 /**
  * Absolute-URL escape hatch: callers occasionally pass a fully-qualified
@@ -440,92 +834,25 @@ async function joomlaRequest(platform, path, init, opts) {
  * to raw fetch but preserve the same auth + sanitisation semantics.
  */
 async function rawAbsoluteRequest(url, init, opts) {
-    let status;
-    const timeoutMs = resolveTimeout(opts);
-    try {
-        const res = await fetch(url, {
-            ...init,
-            headers: {
-                Accept: "application/json",
-                "Content-Type": "application/json",
-                "X-Requested-With": "XMLHttpRequest",
-                ...(BASIC_TOKEN ? { Authorization: `Basic ${BASIC_TOKEN}` } : {}),
-                ...init.headers,
-            },
-            signal: AbortSignal.timeout(timeoutMs),
-        });
-        status = res.status;
-        const text = await res.text();
-        if (!res.ok) {
-            let parsed = text;
-            try {
-                parsed = JSON.parse(text);
-            }
-            catch {
-                /* keep as text */
-            }
-            const errMsg = typeof parsed === "object" && parsed && "message" in parsed
-                ? String(parsed.message)
-                : typeof parsed === "object" && parsed && "error" in parsed
-                    ? String(parsed.error)
-                    : `HTTP ${res.status}`;
-            return {
-                success: false,
-                error: sanitizeErrorString(errMsg),
-                status,
-                errorCode: classify(status),
-            };
-        }
-        if (!text)
-            return { success: true, data: {}, status };
-        let data;
-        try {
-            data = JSON.parse(text);
-        }
-        catch {
-            if (opts.unwrapInnerSuccess && /success["']?\s*:\s*false/i.test(text)) {
-                return {
-                    success: false,
-                    error: sanitizeErrorString(`text response indicates success:false — ${text.slice(0, 200)}`),
-                    status,
-                    errorCode: "unknown",
-                    payloadFailed: true,
-                };
-            }
-            return { success: true, data: text, status };
-        }
-        if (opts.unwrapInnerSuccess && data && typeof data === "object" && "success" in data) {
-            const inner = data.success;
-            if (inner === false) {
-                const innerErr = data.error !== undefined
-                    ? String(data.error)
-                    : "operation reported success:false in payload";
-                return {
-                    success: false,
-                    error: sanitizeErrorString(innerErr),
-                    status,
-                    errorCode: "unknown",
-                    payloadFailed: true,
-                };
-            }
-        }
-        const out = opts.sanitize ? sanitizeSecrets(data) : data;
-        return { success: true, data: out, status };
-    }
-    catch (e) {
-        if (e instanceof Error && (e.name === "AbortError" || e.name === "TimeoutError")) {
-            return {
-                success: false,
-                error: `request timed out after ${Math.round(timeoutMs / 1000)}s`,
-                errorCode: "network",
-            };
-        }
-        return {
-            success: false,
-            error: sanitizeErrorString(e instanceof Error ? e.message : String(e)),
-            errorCode: "network",
-        };
-    }
+    // A3 dedup: the absolute path keeps its own Basic-auth header set (it can't
+    // use a Platform because the host may not match WP_BASE) and an IDENTITY
+    // parseResponse (no envelope to unwrap). textSuccessFalseGuard:true preserves
+    // the path-unique non-JSON `success:false` text guard. The unwrapInnerSuccess
+    // JSON check then runs on the identity-passed data, exactly as before.
+    return performFetch({
+        url,
+        headers: {
+            Accept: "application/json",
+            "Content-Type": "application/json",
+            "X-Requested-With": "XMLHttpRequest",
+            ...(BASIC_TOKEN ? { Authorization: `Basic ${BASIC_TOKEN}` } : {}),
+            ...init.headers,
+        },
+        init,
+        opts,
+        parseResponse: (data) => data,
+        textSuccessFalseGuard: true,
+    });
 }
 /**
  * Map an `errorCode` to a focused hint string for the caller.
@@ -534,7 +861,14 @@ async function rawAbsoluteRequest(url, init, opts) {
 export function hintFor(code) {
     switch (code) {
         case "auth":
-            return "Auth failed. Your MCP key (APIMAPPER_TOKEN) is invalid, revoked, or expired. Generate a new one in API Mapper → ⋮ menu → Settings → MCP Access → New API key, then re-run `npx -y @wootsup/mcp setup` to update your AI client config.";
+            return ("Auth failed (HTTP 401/403). Your MCP key (APIMAPPER_TOKEN) is " +
+                "invalid, revoked, or expired. Recovery steps: " +
+                "(1) Open API Mapper → ⋮ menu → Settings → MCP Access. " +
+                "(2) Revoke the old key if you suspect it was leaked. " +
+                "(3) Click 'New API key' and copy the value. " +
+                "(4) Re-run `npx -y @wootsup/mcp setup` and paste the new key — " +
+                "the wizard rewrites your AI client config in place. " +
+                "(5) Restart your AI client (Claude Desktop / Cursor / etc.).");
         case "not_found":
             return "Resource not found. Use the matching `*_list` tool to find a valid id.";
         case "rate_limit":