@wootsup/mcp 0.1.0 → 0.3.0

package/dist/cli-hint.js

@@ -0,0 +1,55 @@
+// src/cli-hint.ts — interactive "this is the MCP stdio server" hint.
+//
+// `npx @wootsup/mcp` with no subcommand boots the stdio MCP server, which
+// then sits silently waiting for JSON-RPC on stdin. An AI client pipes stdin
+// (so the server gets its protocol and works) — but a human running it in a
+// terminal sees nothing and assumes it has hung.
+//
+// We disambiguate purely on `process.stdin.isTTY`:
+//   • TTY (interactive human)  → no known subcommand means they almost
+//     certainly meant `setup` / `uninstall` / `help`; print a hint and exit
+//     0 instead of booting a server they can't talk to.
+//   • non-TTY (piped — a real MCP client) → behave EXACTLY as before: boot
+//     the server, no hint, no exit. THIS is the load-bearing invariant.
+//
+// The decision is factored out as a pure function so it can be unit-tested
+// without importing index.ts (which boots the server at module load).
+/**
+ * Decide whether the bare/unknown-invocation interactive hint should be shown.
+ *
+ * Returns true ONLY when the invocation is interactive (a TTY on stdin) AND
+ * the given subcommand is not a recognised CLI subcommand (either absent —
+ * bare `npx @wootsup/mcp` — or an unknown typo).
+ *
+ * When stdin is NOT a TTY (piped, i.e. a real MCP client) this ALWAYS returns
+ * false so the server-boot path is never disturbed.
+ *
+ * @param subcommand The first positional CLI arg (`process.argv[2]`), or undefined.
+ * @param knownSubcommands The set of recognised CLI subcommands.
+ * @param isTTY Whether stdin is an interactive terminal (`process.stdin.isTTY`).
+ */
+export function shouldShowInteractiveHint(subcommand, knownSubcommands, isTTY) {
+    if (!isTTY)
+        return false;
+    if (subcommand !== undefined && knownSubcommands.has(subcommand))
+        return false;
+    return true;
+}
+/**
+ * Build the human-facing hint message printed to stderr in interactive mode.
+ *
+ * When `subcommand` is a non-empty unknown token, the message is prefixed with
+ * an "unknown command" line so a typo is called out explicitly.
+ */
+export function buildInteractiveHint(subcommand) {
+    const lines = [];
+    if (subcommand !== undefined && subcommand.length > 0) {
+        lines.push(`unknown command "${subcommand}".`);
+    }
+    lines.push("This is the API Mapper MCP server (stdio). It's normally launched by your " +
+        "AI client, not run directly — that's why it sits here waiting.");
+    lines.push("Did you mean: `npx -y @wootsup/mcp setup`?");
+    lines.push("See also: `uninstall`, `help`.");
+    return lines.join("\n");
+}
+//# sourceMappingURL=cli-hint.js.map

package/dist/cli-hint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-hint.js","sourceRoot":"","sources":["../src/cli-hint.ts"],"names":[],"mappings":"AAAA,qEAAqE;AACrE,EAAE;AACF,0EAA0E;AAC1E,6EAA6E;AAC7E,4EAA4E;AAC5E,iDAAiD;AACjD,EAAE;AACF,mDAAmD;AACnD,uEAAuE;AACvE,4EAA4E;AAC5E,wDAAwD;AACxD,2EAA2E;AAC3E,wEAAwE;AACxE,EAAE;AACF,2EAA2E;AAC3E,sEAAsE;AAEtE;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,yBAAyB,CACvC,UAA8B,EAC9B,gBAAqC,EACrC,KAAc;IAEd,IAAI,CAAC,KAAK;QAAE,OAAO,KAAK,CAAC;IACzB,IAAI,UAAU,KAAK,SAAS,IAAI,gBAAgB,CAAC,GAAG,CAAC,UAAU,CAAC;QAAE,OAAO,KAAK,CAAC;IAC/E,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAAC,UAA8B;IACjE,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,IAAI,UAAU,KAAK,SAAS,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACtD,KAAK,CAAC,IAAI,CAAC,oBAAoB,UAAU,IAAI,CAAC,CAAC;IACjD,CAAC;IACD,KAAK,CAAC,IAAI,CACR,4EAA4E;QAC1E,gEAAgE,CACnE,CAAC;IACF,KAAK,CAAC,IAAI,CAAC,4CAA4C,CAAC,CAAC;IACzD,KAAK,CAAC,IAAI,CAAC,gCAAgC,CAAC,CAAC;IAC7C,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC"}

package/dist/index.js

@@ -1,6 +1,10 @@
 #!/usr/bin/env node
 // @customgraph/mcp-adapter-apimapper-rest — API Mapper REST MCP Server
-// Full coverage of /wp-json/api-mapper/v1/* (~65 tools across 12 modules)
+// Full coverage of /wp-json/api-mapper/v1/* — 79 registered tools (15 module
+// essentials + the apimapper_advanced gateway + 60 advanced-registry tools + 3
+// top-level tools registered below). Only 19 are first-class in tools/list; the
+// 60 advanced tools route through apimapper_advanced to stay under Cursor's ~40
+// surface cap. Canonical counts are asserted in gateway/gateway.test.ts (A2).
 //
 // Auth: API Mapper MCP-key (amk_live_...) generated via the API Mapper
 // admin UI → Settings → MCP Access. The legacy WordPress Application
@@ -33,10 +37,12 @@ if (process.env.APIMAPPER_SITE_URL && !process.env.APIMAPPER_WP_BASE) {
 if (process.env.APIMAPPER_BASE_URL && !process.env.APIMAPPER_WP_BASE) {
     process.env.APIMAPPER_WP_BASE = process.env.APIMAPPER_BASE_URL;
 }
-// APIMAPPER_PLATFORM is consumed by the platform factory once wired
-// (Phase 4 abstraction lands per-tool). Surfaced as a no-op read here so
-// the build-dxt grep gate verifies every user_config key has a runtime
-// consumer — see scripts/build-dxt.js.
+// APIMAPPER_PLATFORM is consumed by client.ts (Phase 1, 2026-06-03): the
+// legacy `request()` path reads it as the explicit env→kind HINT
+// (PLATFORM_KIND) and, when it is unset or "auto", layers a network
+// identity probe on top to auto-detect WordPress vs Joomla. Kept as an
+// explicit no-op read here too so the build-dxt grep gate confirms every
+// user_config key has a runtime consumer — see scripts/build-dxt.js.
 void process.env.APIMAPPER_PLATFORM;
 // APIMAPPER_PROFILE (F-49 / W1.27) — optional profile label for multi-site
 // setups. The setup-cli writes it into the MCP client entry env; the
@@ -45,6 +51,13 @@ void process.env.APIMAPPER_PLATFORM;
 // bridge runs inside main() once the ProfileStore is constructed; see
 // `bootstrapActiveProfile` below for the A6-P3-INTEG-02 wiring + tests.
 void process.env.APIMAPPER_PROFILE;
+// APIMAPPER_SITES_FILE (Phase 3, 2026-06-03) — optional path to a multi-site
+// sites.json (the .dxt one-click / agency path). client.ts reads it lazily
+// (getSitesRegistry) to drive the ACTIVE site's URL/token/platform in
+// request(); main() wires the sites-file-backed profile tools when it loads
+// non-empty. Explicit no-op read here too so the build-dxt grep gate confirms
+// every user_config key has a runtime consumer — see scripts/build-dxt.js.
+void process.env.APIMAPPER_SITES_FILE;
 import { createRequire } from "node:module";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { loadModules, formatResult, readOnly } from "@getimo/mcp-toolkit";
@@ -54,6 +67,9 @@ import { connectStdio } from "./transports/stdio.js";
 import { createKeychain } from "./auth/keychain.js";
 import { ProfileStore, resolveConfigDir } from "./auth/profiles.js";
 import { registerUseProfileTool, registerListProfilesTool, } from "./modules/apimapper/use-profile.js";
+import { registerSitesUseProfileTool, registerSitesListProfilesTool, } from "./modules/apimapper/sites-tools.js";
+import { getSitesRegistry, getActiveSiteId, setActiveSite, } from "./modules/apimapper/client.js";
+import { shouldShowInteractiveHint, buildInteractiveHint } from "./cli-hint.js";
 // Single source of truth for the package version (F-41 / W1.23).
 // Reads ../package.json at runtime so we never drift between the manifest
 // version (used by npm + DXT) and what we advertise to MCP clients.
@@ -141,25 +157,73 @@ server.registerTool("apimapper_rest_modules_status", {
 });
 async function main() {
     moduleStatuses = await loadModules(server, [apimapperRestModule]);
-    // Profile + keychain wiring for apimapper_use_profile.
-    // Phase 5 deferred this to the server entrypoint because constructing the
-    // keychain is async (it probes the OS Secret-Service, falling back to a
-    // file impl) and the module-level register() signature is sync.
-    // Best-effort: log + skip if the keychain init throws on a locked-down host
-    // so the rest of the MCP surface still boots.
+    // Profile tools for apimapper_use_profile / apimapper_list_profiles.
+    //
+    // Phase 3 (2026-06-03) — TWO multi-site mechanisms, branched on presence of a
+    // sites-file:
+    //   • APIMAPPER_SITES_FILE set + non-empty → the sites-file IS the profile
+    //     registry. The tools list its entries and switch the active site via the
+    //     client's setActiveSite() (which retargets request()). No keychain.
+    //   • otherwise → the legacy keychain ProfileStore path (the secure
+    //     single-machine wizard default), unchanged.
+    //
+    // Best-effort: log + skip if init throws on a locked-down host so the rest of
+    // the MCP surface still boots.
+    let sitesFileActive = false;
     try {
-        const configDir = resolveConfigDir();
-        const keychain = await createKeychain({ configDir });
-        const profileStore = new ProfileStore(configDir);
-        // A6-P3-INTEG-02: honour APIMAPPER_PROFILE env var. Must run AFTER the
-        // ProfileStore is constructed but BEFORE the tools register so any
-        // subsequent tool call sees the corrected active pointer.
-        await bootstrapActiveProfile(profileStore);
-        registerUseProfileTool(server, { store: profileStore, keychain });
-        registerListProfilesTool(server, { store: profileStore, keychain });
+        const registry = getSitesRegistry();
+        if (registry) {
+            sitesFileActive = true;
+            // A sites-file is present → honour APIMAPPER_PROFILE as the initial
+            // active-site selection (a site_id). Unknown / "default" / unset → leave
+            // the file's default entry active. setActiveSite throws on an unknown id,
+            // so guard with has() to avoid a phantom selection on a stale env var.
+            const desired = process.env.APIMAPPER_PROFILE?.trim();
+            if (desired && desired !== "default" && registry.has(desired)) {
+                setActiveSite(desired);
+            }
+            registerSitesListProfilesTool(server, {
+                getRegistry: () => {
+                    const r = getSitesRegistry();
+                    if (!r)
+                        throw new Error("sites-file unloaded since boot");
+                    return r;
+                },
+                getActiveSiteId,
+            });
+            registerSitesUseProfileTool(server, {
+                getRegistry: () => {
+                    const r = getSitesRegistry();
+                    if (!r)
+                        throw new Error("sites-file unloaded since boot");
+                    return r;
+                },
+                setActiveSite,
+            });
+        }
     }
     catch (err) {
-        console.error("[apimapper-rest] use-profile tool disabled — keychain/profile init failed:", err instanceof Error ? err.message : err);
+        console.error("[apimapper-rest] sites-file profile tools disabled — sites-file init failed:", err instanceof Error ? err.message : err);
+    }
+    if (!sitesFileActive) {
+        // Keychain ProfileStore path (legacy single-machine default). Phase 5
+        // deferred this to the server entrypoint because constructing the keychain
+        // is async (probes the OS Secret-Service, falling back to a file impl) and
+        // the module-level register() signature is sync.
+        try {
+            const configDir = resolveConfigDir();
+            const keychain = await createKeychain({ configDir });
+            const profileStore = new ProfileStore(configDir);
+            // A6-P3-INTEG-02: honour APIMAPPER_PROFILE env var. Must run AFTER the
+            // ProfileStore is constructed but BEFORE the tools register so any
+            // subsequent tool call sees the corrected active pointer.
+            await bootstrapActiveProfile(profileStore);
+            registerUseProfileTool(server, { store: profileStore, keychain });
+            registerListProfilesTool(server, { store: profileStore, keychain });
+        }
+        catch (err) {
+            console.error("[apimapper-rest] use-profile tool disabled — keychain/profile init failed:", err instanceof Error ? err.message : err);
+        }
     }
     process.stdout.on("error", (err) => {
         if (err.code === "EPIPE" || err.code === "ERR_STREAM_DESTROYED")
@@ -180,7 +244,7 @@ async function main() {
 // lazily inside the subcommand branch so the AI-client startup path
 // stays free of clack/prompts side-effects.
 const subcommand = process.argv[2];
-const CLI_SUBCOMMANDS = new Set(["setup", "install-skill", "install", "help", "--help", "-h"]);
+const CLI_SUBCOMMANDS = new Set(["setup", "install-skill", "install", "uninstall", "remove", "help", "--help", "-h"]);
 if (subcommand && CLI_SUBCOMMANDS.has(subcommand)) {
     void (async () => {
         try {
@@ -194,6 +258,17 @@ if (subcommand && CLI_SUBCOMMANDS.has(subcommand)) {
         }
     })();
 }
+else if (shouldShowInteractiveHint(subcommand, CLI_SUBCOMMANDS, !!process.stdin.isTTY)) {
+    // Interactive human ran `npx @wootsup/mcp` (bare) or a typo'd subcommand in
+    // a terminal. Booting the stdio server here would just sit waiting for
+    // JSON-RPC on stdin and LOOK hung. Print a one-screen hint and exit 0.
+    //
+    // Load-bearing invariant: when stdin is NOT a TTY (an MCP client pipes it),
+    // shouldShowInteractiveHint() returns false and we fall through to main()
+    // below — the server-boot path is byte-for-byte unchanged.
+    console.error(buildInteractiveHint(subcommand));
+    process.exit(0);
+}
 else {
     main().catch((error) => {
         console.error("[apimapper-rest] Fatal error:", error);

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/install-skill.js

@@ -18,7 +18,7 @@ const MARKER_BLOCK = `
 ## API Mapper MCP
 
 ${MARKER_LINE}
-The API Mapper skill is installed at \`~/.claude/skills/apimapper/\`. Refer to it for flow, connection, OAuth, YOOtheme, and Joomla guidance. Source: https://github.com/wootsup/api-mapper.
+The API Mapper skill is installed at \`~/.claude/skills/apimapper/\`. Refer to it for flow, connection, OAuth, YOOtheme, and Joomla guidance. Docs: https://wootsup.com/docs/mcp/api-mapper/.
 `;
 function defaultPkgRoot() {
     // <pkg-root>/src/install-skill.ts → up one.

package/dist/modules/apimapper/cache.js

@@ -1,6 +1,7 @@
 import { z } from "zod";
-import { formatResult, statsResult, errorResult, readOnly, destructive, } from "@getimo/mcp-toolkit";
-import { request, hintFor } from "./client.js";
+import { formatResult, statsResult, readOnly, destructive, } from "@getimo/mcp-toolkit";
+import { request } from "./client.js";
+import { restErrorResult } from "./tool-result.js";
 // rc.13 Welle 3 (2026-05-20) — cache_stats migrated to the toolkit's
 // statsResult builder; both tools' error branches upgraded to errorResult.
 // The migration is purely additive (text `content` block preserved, `_meta.ui`
@@ -12,6 +13,16 @@ import { request, hintFor } from "./client.js";
 // F-A6-07: canonical PHP enum from CacheInvalidateController::scopeToEvent.
 // Legacy aliases (`flow`, `connection`, `credential`, `user`) are accepted
 // by Wave 1B PHP but the dotted form is the documented contract.
+//
+// Wave-12 F12 (2026-05-31): `yootheme.schema` is a direct-file flush scope
+// that bypasses the InvalidationBus. PHP invokes
+// `YOOthemeSchemaCacheBuster::flushNow()` directly when this scope arrives,
+// deleting `schema-*.{php,gql,error.gql}` from the active YOOtheme theme
+// cache directory. Pairs with Wave-12 F8 — that fix closes the auto-flush
+// gap on flow publish; this scope is the manual escape hatch when a
+// customer hits a stale schema and wants to recompile without re-publishing
+// every flow. See `skills/apimapper/reference/troubleshooting.md` for
+// triage.
 const CACHE_INVALIDATE_SCOPES = [
     "connection.updated",
     "connection.deleted",
@@ -19,6 +30,7 @@ const CACHE_INVALIDATE_SCOPES = [
     "flow.published",
     "user.refresh",
     "user.fetch_data",
+    "yootheme.schema",
 ];
 // W1.15 (F-27): cap top_keys envelope size — PHP can return arbitrary
 // counts but the MCP response stays bounded for AI-client legibility.
@@ -30,15 +42,21 @@ export function registerCacheTools(server) {
         description: "Publish a cache-invalidation event to the InvalidationBus (Admin-UI BroadcastChannel + render cache). " +
             "Scope is the dotted event id matching the PHP CacheInvalidationEvent subclass. " +
             "Legacy aliases (`flow`, `connection`, `credential`, `user`) are accepted server-side " +
-            "but the canonical scopes are documented here." +
-            "\n\nExample:\n  apimapper_cache_invalidate({ scope: 'connection.updated', payload: { connection_id: 'con_abc' } })",
+            "but the canonical scopes are documented here. " +
+            "`yootheme.schema` is a manual escape hatch that directly flushes the YOOtheme GraphQL schema " +
+            "cache files (`schema-*.{php,gql,error.gql}`) — use it when a newly-published flow is missing " +
+            "from the YOOtheme Builder source list. See troubleshooting topic for triage." +
+            "\n\nExamples:" +
+            "\n  apimapper_cache_invalidate({ scope: 'connection.updated', payload: { connection_id: 'con_abc' } })" +
+            "\n  apimapper_cache_invalidate({ scope: 'yootheme.schema' })  // force-flush the YT schema cache",
         inputSchema: {
             scope: z
                 .enum(CACHE_INVALIDATE_SCOPES)
                 .describe("Cache invalidation scope (dotted event id). " +
                 "Required payload fields: connection.updated→{connection_id, credential_id?}, " +
                 "connection.deleted→{connection_id}, credential.reauth→{credential_id, affected_connection_ids?}, " +
-                "flow.published→{flow_id, connection_ids?}, user.refresh→{}, user.fetch_data→{node_id?, connection_id?}."),
+                "flow.published→{flow_id, connection_ids?}, user.refresh→{}, user.fetch_data→{node_id?, connection_id?}, " +
+                "yootheme.schema→{} (no payload — direct-file flush, bypasses the InvalidationBus)."),
             payload: z
                 .record(z.string(), z.unknown())
                 .optional()
@@ -54,12 +72,7 @@ export function registerCacheTools(server) {
             body.payload = payload;
         const r = await request("/cache/admin/invalidate", { method: "POST", body: JSON.stringify(body) });
         if (!r.success) {
-            return errorResult({
-                message: r.error ?? "cache invalidation failed",
-                code: r.errorCode ?? (r.status ? String(r.status) : undefined),
-                suggestion: hintFor(r.errorCode),
-                details: { scope, payload_keys: payload ? Object.keys(payload) : [] },
-            });
+            return restErrorResult(r, { scope, payload_keys: payload ? Object.keys(payload) : [] }, { message: "cache invalidation failed" });
         }
         const ok = r.data?.ok === true;
         return formatResult({
@@ -83,12 +96,7 @@ export function registerCacheTools(server) {
     }, async () => {
         const r = await request("/cache-stats");
         if (!r.success) {
-            return errorResult({
-                message: r.error ?? "cache stats failed",
-                code: r.errorCode ?? (r.status ? String(r.status) : undefined),
-                suggestion: hintFor(r.errorCode),
-                details: {},
-            });
+            return restErrorResult(r, {}, { message: "cache stats failed" });
         }
         const tiers = r.data?.tiers ?? {};
         const admin = tiers.admin ?? {};

package/dist/modules/apimapper/cache.js.map

@@ -1 +1 @@
-{"version":3,"file":"cache.js","sourceRoot":"","sources":["../../../src/modules/apimapper/cache.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../../../src/modules/apimapper/cache.ts"],"names":[],"mappings":"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"}

package/dist/modules/apimapper/client.d.ts

@@ -1,5 +1,6 @@
 import { type ApiResponse } from "@getimo/mcp-toolkit";
 import { type Platform } from "../../platform/index.js";
+import { type SitesRegistry } from "../../sites/loader.js";
 /**
  * WordPress / Joomla site base URL.
  *
@@ -45,7 +46,7 @@ export declare function sanitizeErrorString(s: string): string;
  * The underlying toolkit `ApiResponse` only carries `{success, data?, error?}`.
  * We wrap each call so we capture the HTTP code via `fetch` and merge.
  */
-export type ApiErrorCode = "auth" | "not_found" | "rate_limit" | "server" | "network" | "unknown";
+export type ApiErrorCode = "auth" | "not_found" | "conflict" | "rate_limit" | "server" | "network" | "unknown";
 export interface ExtApiResponse<T = unknown> extends ApiResponse<T> {
     status?: number;
     errorCode?: ApiErrorCode;
@@ -105,6 +106,66 @@ export interface PlatformClient {
  */
 export declare function createPlatformClient(platform: Platform): PlatformClient;
 export declare const PLATFORM_KIND: "wordpress" | "joomla";
+/**
+ * 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 declare function probePlatform(baseUrl?: string, token?: string): Promise<"wordpress" | "joomla">;
+/**
+ * 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 declare function getSitesRegistry(): SitesRegistry | null;
+/**
+ * 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 declare function getActiveSiteId(): string | 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 declare function setActiveSite(id: string): void;
+/**
+ * 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 declare function resetPlatformResolution(): void;
+/**
+ * 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 declare function __resetPlatformResolutionForTests(): void;
 /**
  * Issue a request through the toolkit HTTP client + capture HTTP status.
  *