@wootsup/mcp 0.1.0 → 0.4.0

package/dist/modules/apimapper/client.js

@@ -25,8 +25,11 @@
 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 { getMcpClient } from "./mcp-client-identity.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
@@ -159,12 +162,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;
@@ -172,6 +204,149 @@ 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);
+    // Q1 (2026-06-14): performFetch is the ONE outbound chokepoint shared by the
+    // WP, Joomla, and absolute request paths. Attaching X-MCP-Client here means
+    // every REST call carries the connected AI client's identity (set once
+    // post-handshake in index.ts) without touching three caller header builders.
+    // Null when no client info → header omitted entirely.
+    const mcpClient = getMcpClient();
+    try {
+        const res = await fetch(url, {
+            ...init,
+            headers: {
+                ...headers,
+                ...(mcpClient ? { "X-MCP-Client": mcpClient } : {}),
+            },
+            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
@@ -183,115 +358,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}`;
-                    // W2-3: preserve the parsed JSON error body when present so callers
-                    // can branch on domain-specific fields (e.g. compiler_error_code).
-                    const errorBody = typeof parsed === "object" && parsed !== null
-                        ? parsed
-                        : undefined;
-                    return {
-                        success: false,
-                        error: sanitizeErrorString(errMsg),
-                        status,
-                        errorCode: classify(status),
-                        errorBody,
-                    };
-                }
-                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,
+            });
         },
     };
 }
@@ -331,24 +417,306 @@ class WordPressBasicAuthPlatform extends WordPressPlatform {
 // 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";
-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);
+/**
+ * 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.
  *
@@ -380,17 +748,25 @@ export async function request(path, init = {}, opts = {}) {
     // 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) {
@@ -415,86 +791,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}`;
-            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")) {
+        // 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: `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
@@ -503,121 +844,175 @@ 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.
- * Falls back to the generic health-tool hint.
+ * F83 (2026-06-10, C3 cold-agent): the JMESPath depth-limit failure surfaced
+ * on the flow-write path. The PHP backend emits it as a 422 with one of two
+ * frozen wordings:
+ *   - FlowHandler::validateJmesPathDepth → "N JMESPath expression(s) exceeded
+ *     the depth limit of M"
+ *   - TransformException → "JMESPath expression too deeply nested (N levels).
+ *     Maximum: M"
+ * Neither carries a body-level `error_code`/`suggestion`, so `classify(422)`
+ * lands on "unknown" and the bare-code hint is HEALTH_HINT — the WRONG remedy
+ * (a cold agent literally got "Use apimapper_health to check connectivity").
+ * The actual cure is the two-transform split: a pipe `|` resets the depth
+ * counter. We detect the depth-limit message text (not the coarse code) so the
+ * remedy fires regardless of how the wire status classifies. This is the
+ * canonical depth remedy — the PHP `TransformException::expressionTooDeepWithRemedy`
+ * superset emits the same intent; the MCP-side detection here covers the
+ * write-path 422s that arrive without a body-level error_code.
+ */
+const DEPTH_LIMIT_MESSAGE_RE = /depth limit|too deeply nested/i;
+export const DEPTH_SPLIT_HINT = "JMESPath depth limit hit. This is NOT a connectivity problem — do not run " +
+    "apimapper_health. Multi-stage reshape? Pass `transform` as an ARRAY of stages " +
+    "— each stage gets its own depth budget. SPLIT the over-nested expression into " +
+    "TWO Transform nodes piped together: a pipe `|` resets the depth counter, so " +
+    "each half stays under the cap of 10. Move the inner projection/merge into a " +
+    "first Transform, then do the per-row shaping in a second Transform reading its " +
+    "output. Iterate each half risk-free with apimapper_jmespath_test before " +
+    "wiring, and read the copy-paste recipes via " +
+    "apimapper_get_skill({ topic: 'jmespath-cookbook' }) → \"Two-Transform split\".";
+/**
+ * Map an `errorCode` (and optional {@link HintContext}) to a focused hint
+ * string for the caller. Falls back to the generic health-tool hint only for
+ * genuinely connectivity-shaped failures.
+ *
+ * The second argument is a UNION: a bare `string` is treated as
+ * `{ message }` so the ~12 legacy call sites that pass the upstream error
+ * string verbatim (`hintFor(code, r.error)`) keep working unchanged, while
+ * the richer `{ message, origin }` form drives F112/F113 routing. Omit it to
+ * keep the legacy code-only behaviour byte-for-byte.
  */
-export function hintFor(code) {
+export function hintFor(code, context) {
+    // Normalise the union: a bare string IS the upstream message.
+    const ctx = typeof context === "string" ? { message: context } : context;
+    // F83: message-driven depth-limit detection wins over the coarse code, so a
+    // 422 that classify()s to "unknown" still gets the split remedy.
+    if (ctx?.message && DEPTH_LIMIT_MESSAGE_RE.test(ctx.message)) {
+        return DEPTH_SPLIT_HINT;
+    }
     switch (code) {
         case "auth":
-            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.).");
+            // F113: separate upstream-credential auth from MCP-transport auth.
+            // A 401/403 carried back from a connection/credential fetch is an
+            // EXPIRED UPSTREAM token — re-authorise it in place; do NOT send the
+            // agent to rotate the (valid) MCP key + re-run the setup wizard.
+            if (ctx?.origin === "connection" || ctx?.origin === "credential") {
+                return CREDENTIAL_EXPIRED_HINT;
+            }
+            return MCP_KEY_AUTH_HINT;
         case "not_found":
             return "Resource not found. Use the matching `*_list` tool to find a valid id.";
         case "rate_limit":
-            return "Rate-limited. Retry after a few seconds; consider apimapper_cache_invalidate to reduce churn.";
+            // F59 (2026-06-10): a 429 is often recoverable WITHOUT waiting — many
+            // providers have a same-schema MIRROR connection (same template, a
+            // different upstream serving identical data). Point the agent there.
+            return ("Rate-limited (HTTP 429). Retry after a few seconds, and raise " +
+                "cache_ttl / use apimapper_cache_invalidate to reduce churn. If the " +
+                "throttle persists, run apimapper_connection_list and look for a " +
+                "same-schema / mirror connection (same library template or a " +
+                "duplicate pointing at an alternative upstream) that serves the same " +
+                "data — bind the flow to that mirror instead of the throttled source.");
+        case "credential_expired":
+            // A11: re-authorize the EXISTING credential in place; never delete +
+            // recreate (that drops the OAuth refresh token).
+            return ("An OAuth credential expired. Re-authorize it IN PLACE with " +
+                "apimapper_oauth_authorize_begin({ credential_id }), open the returned " +
+                "authorize_url, complete consent, then retry. Keep the same credential " +
+                "— recreating it from scratch drops the refresh token. Use " +
+                "apimapper_credential_list to find the credential_id.");
+        case "tier_limit_reached":
+            // A12: the plan's connection / auth-method limit is hit.
+            return ("Your plan's limit was reached (connections or auth methods). " +
+                "Upgrade the license to raise the limit, or free a slot by deleting an " +
+                "unused connection (apimapper_connection_list to review). Check the " +
+                "current tier + limits with apimapper_license_status.");
         case "server":
             return "Upstream server error. Try again, then run apimapper_health and check WP error logs.";
         case "network":
             return "Network/timeout error. Verify APIMAPPER_WP_BASE is reachable from this host.";
         default:
-            return HEALTH_HINT;
+            // F112: an `unknown`/config error must NOT blanket-route to the
+            // connectivity probe. Route on the message shape when we have one.
+            return routeUnknownHint(ctx?.message);
     }
 }
+/**
+ * F112 — message-pattern router for the `unknown` (config/validation) branch.
+ * Returns a hint that points at the ACTUAL fix (fill a field, repair the flow
+ * shape, detect a schema) instead of the catch-all HEALTH_HINT. Only a
+ * genuinely connectivity-shaped message (or no message at all) keeps the
+ * health hint.
+ */
+function routeUnknownHint(message) {
+    if (!message)
+        return HEALTH_HINT;
+    const m = message.toLowerCase();
+    // Connectivity-shaped failures keep pointing at apimapper_health.
+    if (/econnrefused|enotfound|etimedout|fetch failed|network|timeout|unreachable|connection refused/.test(m)) {
+        return HEALTH_HINT;
+    }
+    // Empty/stale schema → detect the schema.
+    if (/schema (is )?empty|no schema|empty schema|run detect|detect[- ]schema/.test(m)) {
+        return "The source schema is empty — run apimapper_flow_detect_schema (or apimapper_flow_full_recompile_publish) to populate it before binding fields.";
+    }
+    // Flow-SHAPE errors (wiring / nodes / edges) → inspect the flow graph.
+    if (/no (target|source|output) node|target node|source node|\bedges?\b|\bnode\b|connect|wiring|no nodes/.test(m)) {
+        return "The flow shape is incomplete (missing node, edge, or target). Run apimapper_flow_get to inspect the graph, then fix the node/edge wiring with apimapper_flow_update.";
+    }
+    // Missing-field / configure errors → supply the field.
+    if (/missing required field|missing field|please configure|required field|is required|required:/.test(m)) {
+        return "A required argument is missing — supply the named field(s) and call the tool again. Check the tool's input schema for the exact key(s).";
+    }
+    // Default: still a config error, not a connectivity one — keep the agent
+    // out of the health probe and tell it to recheck its arguments.
+    return "Check the tool arguments against its input schema and retry; this is a request/config error, not a connectivity problem.";
+}
 export const HEALTH_HINT = "Use apimapper_health to check connectivity and auth.";
+/**
+ * Recovery hint for an auth failure on the MCP transport itself (the bearer
+ * key is wrong/revoked/expired). Kept verbatim for the legacy `hintFor('auth')`
+ * contract.
+ */
+export const MCP_KEY_AUTH_HINT = "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.).";
+/**
+ * F113 — recovery hint for an EXPIRED UPSTREAM credential surfaced as a
+ * connection/credential 401/403. The fix is to re-authorise the credential in
+ * place (preserving the refresh_token), NOT to rotate the MCP key.
+ */
+export const CREDENTIAL_EXPIRED_HINT = "The upstream API rejected the request (HTTP 401/403) because the " +
+    "connection's credential has expired or was revoked — this is the " +
+    "external service's token, NOT your MCP key. Re-authorise it: call " +
+    "apimapper_oauth_authorize_begin with the connection's credential_id to " +
+    "get a fresh consent URL (this preserves the refresh_token). Do NOT " +
+    "rotate your MCP key for this error.";
 export function authConfigured() {
     // Bearer token (amk_live_…) is sufficient on its own; legacy App-Password
     // auth still requires both user + password.