@silasfmartins/testhub 1.0.0

package/dist/src/utils/McpLocalClient.js

@@ -0,0 +1,871 @@
+/**
+ * MCP Local JSON-RPC Client (v2.7.44-r3 — items 22, 26, 27, 28)
+ *
+ * Permite ao framework chamar tools no MCP local (sidecar/background)
+ * via JSON-RPC sobre STDIO ou HTTP, sem depender de GitHub Copilot Chat.
+ *
+ * Transporte (ordem de prioridade — item 26.2):
+ *  1. STDIO direto (`autocore-hub-mcp`) com Content-Length framing (MCP oficial) — caminho principal
+ *  2. HTTP local (`HUB_MCP_LOCAL_URL`) — bridge HTTP explícita
+ *  3. Backend MCP remoto — fallback/control-plane (backend decide reroute local ou fallback)
+ *
+ * Uso principal: `fix_xpath_in_attributes` para auto-fix de XPaths
+ * nos arquivos Attributes* do projeto local após recovery bem-sucedido.
+ */
+import * as fs from "fs";
+import * as path from "path";
+import { Logger } from "./Logger.js";
+// ---------------------------------------------------------------------------
+// Dedupe tracker (evitar edições repetidas na mesma execução)
+// ---------------------------------------------------------------------------
+const _appliedFixes = new Set();
+function dedupeKey(oldXPath, newXPath, methodName) {
+    return `${oldXPath}||${newXPath}||${methodName || ""}`;
+}
+// ---------------------------------------------------------------------------
+// Configuração (lazy reads — pega da env do Windows a cada chamada)
+// ---------------------------------------------------------------------------
+function getMcpLocalUrl() {
+    return (process.env.HUB_MCP_LOCAL_URL || "").trim();
+}
+function getMcpBackendUrl() {
+    return (process.env.AUTOCORE_HUB_URL ||
+        process.env.AUTOCORE_HUB_IP ||
+        "http://brtlvlty0559pl:3333");
+}
+const MCP_LOCAL_TIMEOUT = 15_000;
+const MCP_LOCAL_MAX_RETRIES = 2;
+/** Lê user_hash das variáveis de ambiente do Windows (lazy, a cada chamada) */
+function getMcpUserHash() {
+    return process.env.HUB_MCP_USER_HASH || process.env.MCP_USER_HASH || "";
+}
+function makeId() {
+    return `autofix-${Date.now()}-${Math.random().toString(36).slice(2, 6)}`;
+}
+function enrichArgsWithUserHash(args) {
+    const userHash = getMcpUserHash();
+    if (!userHash)
+        return { ...args };
+    return {
+        ...args,
+        user_hash: args.user_hash || userHash,
+        userHash: args.userHash || userHash,
+        mcpUserHash: args.mcpUserHash || userHash,
+    };
+}
+// Cache de tools/list por canal para evitar health-check repetido na mesma execução
+const _toolsListCache = new Map();
+// ---------------------------------------------------------------------------
+// 1) STDIO transport com Content-Length framing (MCP oficial — item 27.1/28.2)
+// ---------------------------------------------------------------------------
+let _stdioProcess = null;
+const _stdioPendingRequests = new Map();
+let _stdioAvailable = null; // null = not checked yet
+function splitCommandLine(value) {
+    const normalized = value.trim();
+    if (!normalized)
+        return [];
+    return (normalized
+        .match(/(?:[^\s"]+|"[^"]*")+/g)
+        ?.map((part) => part.replace(/^"|"$/g, "")) || []);
+}
+function getMcpStdioCandidates() {
+    const candidates = [];
+    const custom = String(process.env.HUB_MCP_STDIO_BIN || "").trim();
+    if (custom) {
+        const parts = splitCommandLine(custom);
+        if (parts.length > 0) {
+            const [command, ...rest] = parts;
+            const args = rest.includes("--stdio") ? rest : [...rest, "--stdio"];
+            candidates.push({
+                command,
+                args,
+                label: `custom:${custom}`,
+            });
+        }
+    }
+    candidates.push({
+        command: "autocore-hub-mcp",
+        args: ["--stdio"],
+        label: "global:autocore-hub-mcp",
+    });
+    candidates.push({
+        command: "npx",
+        args: ["-y", "@silasfmartins/testhub-orchestrator-mcp", "--stdio"],
+        label: "npx:@silasfmartins/testhub-orchestrator-mcp",
+    });
+    // remover duplicados mantendo ordem
+    const dedupe = new Set();
+    return candidates.filter((candidate) => {
+        const key = `${candidate.command} ${candidate.args.join(" ")}`;
+        if (dedupe.has(key))
+            return false;
+        dedupe.add(key);
+        return true;
+    });
+}
+function findHeaderEnd(buf) {
+    // Procura \r\n\r\n
+    for (let i = 0; i < buf.length - 3; i++) {
+        if (buf[i] === 0x0d &&
+            buf[i + 1] === 0x0a &&
+            buf[i + 2] === 0x0d &&
+            buf[i + 3] === 0x0a) {
+            return i;
+        }
+    }
+    return -1;
+}
+function attachStdioHandlers(processRef, label) {
+    processRef.on("error", (err) => {
+        Logger.warning(`[McpLocalClient] Falha no processo STDIO (${label}): ${err instanceof Error ? err.message : String(err)}`);
+        _stdioAvailable = false;
+        _stdioProcess = null;
+    });
+    processRef.on("exit", () => {
+        _stdioProcess = null;
+        for (const [id, pending] of _stdioPendingRequests) {
+            clearTimeout(pending.timer);
+            pending.resolve({
+                jsonrpc: "2.0",
+                id,
+                error: { code: -1, message: "STDIO process exited" },
+            });
+        }
+        _stdioPendingRequests.clear();
+    });
+    // Parser Content-Length (MCP/LSP framing — item 27.1/28.2)
+    // Formato: "Content-Length: <n>\r\n\r\n<json-body>"
+    // Também aceita newline-delimited como fallback para compatibilidade.
+    let rawBuffer = Buffer.alloc(0);
+    processRef.stdout?.on("data", (chunk) => {
+        rawBuffer = Buffer.concat([rawBuffer, chunk]);
+        parseStdioBuffer();
+    });
+    function parseStdioBuffer() {
+        // eslint-disable-next-line no-constant-condition
+        while (true) {
+            // Tenta Content-Length framing primeiro
+            const headerEnd = findHeaderEnd(rawBuffer);
+            if (headerEnd !== -1) {
+                const headerStr = rawBuffer.subarray(0, headerEnd).toString("utf-8");
+                const clMatch = headerStr.match(/Content-Length:\s*(\d+)/i);
+                if (clMatch) {
+                    const bodyLen = parseInt(clMatch[1], 10);
+                    const bodyStart = headerEnd + 4; // após \r\n\r\n
+                    if (rawBuffer.length >= bodyStart + bodyLen) {
+                        const bodyStr = rawBuffer
+                            .subarray(bodyStart, bodyStart + bodyLen)
+                            .toString("utf-8");
+                        rawBuffer = rawBuffer.subarray(bodyStart + bodyLen);
+                        dispatchStdioMessage(bodyStr);
+                        continue; // pode haver mais mensagens no buffer
+                    }
+                    break; // aguardar mais dados
+                }
+            }
+            // Fallback: newline-delimited (compatibilidade)
+            const nlIdx = rawBuffer.indexOf(0x0a); // \n
+            if (nlIdx === -1)
+                break;
+            const line = rawBuffer.subarray(0, nlIdx).toString("utf-8").trim();
+            rawBuffer = rawBuffer.subarray(nlIdx + 1);
+            if (line)
+                dispatchStdioMessage(line);
+        }
+    }
+    function dispatchStdioMessage(text) {
+        try {
+            const msg = JSON.parse(text);
+            if (msg.id && _stdioPendingRequests.has(String(msg.id))) {
+                const pending = _stdioPendingRequests.get(String(msg.id));
+                clearTimeout(pending.timer);
+                _stdioPendingRequests.delete(String(msg.id));
+                pending.resolve(msg);
+            }
+        }
+        catch {
+            /* ignore non-JSON */
+        }
+    }
+}
+async function spawnCandidateWithProbe(candidate) {
+    const { spawn } = await import("child_process");
+    // No Windows, executáveis globais do npm são .cmd e precisam de shell: true
+    const isWindows = process.platform === "win32";
+    const processRef = spawn(candidate.command, candidate.args, {
+        stdio: ["pipe", "pipe", "pipe"],
+        env: { ...process.env },
+        windowsHide: true,
+        shell: isWindows,
+    });
+    return await new Promise((resolve) => {
+        let settled = false;
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            processRef.off("error", onError);
+            processRef.off("exit", onExit);
+            clearTimeout(timer);
+            resolve(result);
+        };
+        const onError = () => {
+            try {
+                processRef.kill();
+            }
+            catch { }
+            finish(null);
+        };
+        const onExit = (code) => {
+            if (code === null)
+                return;
+            finish(null);
+        };
+        const timer = setTimeout(() => finish(processRef), 450);
+        processRef.once("error", onError);
+        processRef.once("exit", onExit);
+    });
+}
+/**
+ * Spawna o processo MCP local via STDIO se ainda não ativo.
+ * Protocolo: JSON-RPC sobre Content-Length framing (padrão MCP/LSP).
+ */
+async function ensureStdioProcess() {
+    if (_stdioAvailable === false)
+        return false;
+    if (_stdioProcess && !_stdioProcess.killed)
+        return true;
+    try {
+        const candidates = getMcpStdioCandidates();
+        for (const candidate of candidates) {
+            const processRef = await spawnCandidateWithProbe(candidate);
+            if (!processRef) {
+                Logger.info(`[McpLocalClient] MCP local indisponível via ${candidate.label}, tentando próximo...`);
+                continue;
+            }
+            _stdioProcess = processRef;
+            attachStdioHandlers(processRef, candidate.label);
+            _stdioAvailable = true;
+            Logger.info(`[McpLocalClient] MCP local iniciado via ${candidate.label}`);
+            return true;
+        }
+        _stdioAvailable = false;
+        _stdioProcess = null;
+        return false;
+    }
+    catch {
+        _stdioAvailable = false;
+        _stdioProcess = null;
+        return false;
+    }
+}
+/**
+ * Envia JSON-RPC via STDIO com Content-Length framing e aguarda resposta
+ */
+async function callMcpStdio(method, params) {
+    if (!_stdioProcess?.stdin?.writable) {
+        throw new Error("STDIO process not available");
+    }
+    const id = makeId();
+    const request = { jsonrpc: "2.0", id, method, params };
+    const body = JSON.stringify(request);
+    return new Promise((resolve) => {
+        const timer = setTimeout(() => {
+            _stdioPendingRequests.delete(id);
+            resolve({
+                jsonrpc: "2.0",
+                id,
+                error: { code: -1, message: "STDIO timeout" },
+            });
+        }, MCP_LOCAL_TIMEOUT);
+        _stdioPendingRequests.set(id, { resolve, timer });
+        // Content-Length framing (MCP/LSP padrão)
+        const frame = `Content-Length: ${Buffer.byteLength(body, "utf-8")}\r\n\r\n${body}`;
+        _stdioProcess.stdin.write(frame, "utf-8");
+    });
+}
+// ---------------------------------------------------------------------------
+// 2) HTTP transport (local ou backend remoto)
+// ---------------------------------------------------------------------------
+async function callMcpHttp(toolName, args, baseUrl) {
+    const reqBody = {
+        jsonrpc: "2.0",
+        id: makeId(),
+        method: "tools/call",
+        params: { name: toolName, arguments: args },
+    };
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), MCP_LOCAL_TIMEOUT);
+    try {
+        const userHash = getMcpUserHash();
+        let url = `${baseUrl.replace(/\/$/, "")}/mcp`;
+        if (userHash) {
+            url += `?user_hash=${encodeURIComponent(userHash)}`;
+        }
+        const headers = {
+            "Content-Type": "application/json",
+        };
+        if (userHash) {
+            headers["x-user-hash"] = userHash;
+        }
+        const res = await fetch(url, {
+            method: "POST",
+            headers,
+            body: JSON.stringify(reqBody),
+            signal: controller.signal,
+        });
+        if (!res.ok) {
+            const text = await res.text().catch(() => "");
+            return {
+                jsonrpc: "2.0",
+                id: reqBody.id,
+                error: { code: res.status, message: `HTTP ${res.status}: ${text}` },
+            };
+        }
+        return (await res.json());
+    }
+    finally {
+        clearTimeout(timeoutId);
+    }
+}
+// ---------------------------------------------------------------------------
+// 3) Health-check: tools/list (item 26.3)
+// ---------------------------------------------------------------------------
+/**
+ * Verifica se uma tool existe no canal informado via tools/list.
+ * Resultado é cacheado por canal para a execução inteira.
+ */
+async function hasToolOnChannel(channel, toolName) {
+    if (_toolsListCache.has(channel)) {
+        const cached = _toolsListCache.get(channel);
+        return cached ? cached.has(toolName) : false;
+    }
+    try {
+        let response;
+        if (channel === "stdio") {
+            const ok = await ensureStdioProcess();
+            if (!ok) {
+                _toolsListCache.set(channel, null);
+                return false;
+            }
+            response = await callMcpStdio("tools/list", {});
+        }
+        else {
+            const baseUrl = channel === "http-local" ? getMcpLocalUrl() : getMcpBackendUrl();
+            if (!baseUrl) {
+                _toolsListCache.set(channel, null);
+                return false;
+            }
+            const userHash = getMcpUserHash();
+            // HTTP requer user_hash (item 28.1)
+            if (!userHash) {
+                _toolsListCache.set(channel, null);
+                return false;
+            }
+            const reqBody = {
+                jsonrpc: "2.0",
+                id: makeId(),
+                method: "tools/list",
+                params: {},
+            };
+            const controller = new AbortController();
+            const timeoutId = setTimeout(() => controller.abort(), 8_000);
+            try {
+                let url = `${baseUrl.replace(/\/$/, "")}/mcp`;
+                if (userHash)
+                    url += `?user_hash=${encodeURIComponent(userHash)}`;
+                const headers = {
+                    "Content-Type": "application/json",
+                };
+                if (userHash)
+                    headers["x-user-hash"] = userHash;
+                const res = await fetch(url, {
+                    method: "POST",
+                    headers,
+                    body: JSON.stringify(reqBody),
+                    signal: controller.signal,
+                });
+                if (!res.ok) {
+                    _toolsListCache.set(channel, null);
+                    return false;
+                }
+                response = (await res.json());
+            }
+            finally {
+                clearTimeout(timeoutId);
+            }
+        }
+        if (response.error) {
+            _toolsListCache.set(channel, null);
+            return false;
+        }
+        // Extrair nomes das tools
+        const tools = response.result;
+        const toolSet = new Set();
+        if (tools?.tools && Array.isArray(tools.tools)) {
+            for (const t of tools.tools) {
+                if (t.name)
+                    toolSet.add(t.name);
+            }
+        }
+        _toolsListCache.set(channel, toolSet);
+        return toolSet.has(toolName);
+    }
+    catch {
+        _toolsListCache.set(channel, null);
+        return false;
+    }
+}
+// ---------------------------------------------------------------------------
+// 4) Chamada com fallback por canal (items 26.2, 28.5)
+// ---------------------------------------------------------------------------
+/**
+ * Tenta chamar tool no MCP seguindo ordem de prioridade:
+ *  1. STDIO direto (não requer user_hash — item 28.1)
+ *  2. HTTP local (HUB_MCP_LOCAL_URL) — requer user_hash
+ *  3. Backend MCP remoto — quando habilitado em options.allowBackend
+ *
+ * Faz health-check (tools/list) antes de chamar, para evitar -32601.
+ */
+async function callToolWithFallback(toolName, args, options = {}) {
+    const channels = options.preferBackend && options.allowBackend
+        ? ["http-backend", "stdio", "http-local"]
+        : ["stdio", "http-local"];
+    if (options.allowBackend && !channels.includes("http-backend")) {
+        channels.push("http-backend");
+    }
+    for (const channel of channels) {
+        const available = await hasToolOnChannel(channel, toolName);
+        if (!available) {
+            Logger.info(`[McpLocalClient] Tool '${toolName}' não disponível via ${channel}, tentando próximo...`);
+            continue;
+        }
+        try {
+            let response;
+            if (channel === "stdio") {
+                response = await callMcpStdio("tools/call", {
+                    name: toolName,
+                    arguments: args,
+                });
+            }
+            else {
+                const baseUrl = channel === "http-local" ? getMcpLocalUrl() : getMcpBackendUrl();
+                if (!baseUrl) {
+                    Logger.info(`[McpLocalClient] URL não configurada para canal ${channel}, pulando...`);
+                    continue;
+                }
+                response = await callMcpHttp(toolName, args, baseUrl);
+            }
+            if (response.error?.code === -32601) {
+                Logger.warning(`[McpLocalClient] Tool '${toolName}' retornou -32601 via ${channel}.`);
+                _toolsListCache.delete(channel);
+                continue;
+            }
+            return { response, channel };
+        }
+        catch (err) {
+            Logger.warning(`[McpLocalClient] Erro no canal ${channel}: ${err instanceof Error ? err.message : String(err)}`);
+            continue;
+        }
+    }
+    return {
+        response: {
+            jsonrpc: "2.0",
+            id: makeId(),
+            error: {
+                code: -1,
+                message: "Nenhum canal MCP disponível para a tool solicitada.",
+            },
+        },
+        channel: "http-backend",
+    };
+}
+// ---------------------------------------------------------------------------
+// 5) Parse robusto de resposta (item 27.2/28.3)
+// ---------------------------------------------------------------------------
+/**
+ * Extrai FixXPathInAttributesResult da resposta do MCP.
+ *
+ * Tenta na ordem:
+ *  1. response.result como objeto estruturado (top-level)
+ *  2. response.result.content[].text com JSON serializado
+ *  3. null se nenhum formato reconhecido
+ */
+function parseFixResult(raw) {
+    if (!raw || typeof raw !== "object")
+        return null;
+    const obj = raw;
+    // 0) Alguns retornos vêm encapsulados em payload
+    if (obj.payload && typeof obj.payload === "object") {
+        const payloadResult = parseFixResult(obj.payload);
+        if (payloadResult)
+            return payloadResult;
+    }
+    // 1) Top-level estruturado: { success, filePath, ... }
+    if ("success" in obj || "fileUpdated" in obj || "nextAction" in obj) {
+        return {
+            success: obj.success === true ||
+                obj.fileUpdated === true ||
+                obj.nextAction === "retry",
+            filePath: obj.filePath || undefined,
+            className: obj.className || undefined,
+            methodName: obj.methodName || undefined,
+            fileUpdated: obj.fileUpdated === true,
+            executedOn: obj.executedOn || undefined,
+            localMcpExecuted: obj.localMcpExecuted === true,
+            localMcpRequestId: obj.localMcpRequestId || undefined,
+            nextAction: obj.nextAction || undefined,
+            error: obj.error || undefined,
+            proof: obj.proof && typeof obj.proof === "object"
+                ? obj.proof
+                : undefined,
+        };
+    }
+    // 2) content[].text com JSON serializado
+    const content = obj.content;
+    if (Array.isArray(content)) {
+        for (const item of content) {
+            if (item && typeof item === "object" && typeof item.text === "string") {
+                try {
+                    const parsed = JSON.parse(item.text);
+                    if (parsed && typeof parsed === "object") {
+                        return parseFixResult(parsed); // recurse
+                    }
+                }
+                catch {
+                    /* não é JSON válido, ignorar */
+                }
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Determina se o resultado é válido o suficiente para contabilizar no dedupe (item 28.4).
+ * Só deduplica quando houve processamento real:
+ *  - success=true, ou
+ *  - nextAction=manual_review com payload válido
+ */
+function isValidForDedupe(result) {
+    if (!result)
+        return false;
+    if (result.success)
+        return true;
+    if (result.nextAction === "manual_review" &&
+        (result.filePath || result.className))
+        return true;
+    return false;
+}
+function verifyFixOnDisk(params) {
+    const normalize = (value) => value
+        .replace(/\r\n/g, "\n")
+        .replace(/["']/g, "'")
+        .replace(/\s+/g, " ")
+        .trim();
+    const oldNormalized = normalize(params.oldXPath);
+    const newNormalized = normalize(params.newXPath);
+    if (!newNormalized)
+        return false;
+    try {
+        if (params.filePath && fs.existsSync(params.filePath)) {
+            const content = fs.readFileSync(params.filePath, "utf-8");
+            const normalizedContent = normalize(content);
+            return (normalizedContent.includes(newNormalized) &&
+                (!oldNormalized || !normalizedContent.includes(oldNormalized)));
+        }
+    }
+    catch {
+        // segue para fallback
+    }
+    // fallback: verificar arquivos Attributes dentro do projectRoot
+    try {
+        const queue = [params.projectRoot];
+        let scanned = 0;
+        const maxScanned = 400;
+        while (queue.length > 0 && scanned < maxScanned) {
+            const current = queue.shift();
+            let entries = [];
+            try {
+                entries = fs.readdirSync(current, { withFileTypes: true });
+            }
+            catch {
+                continue;
+            }
+            for (const entry of entries) {
+                if (scanned >= maxScanned)
+                    break;
+                const fullPath = path.join(current, entry.name);
+                if (entry.isDirectory()) {
+                    if (entry.name === "node_modules" ||
+                        entry.name === ".git" ||
+                        entry.name === "dist") {
+                        continue;
+                    }
+                    queue.push(fullPath);
+                    continue;
+                }
+                scanned += 1;
+                const lower = entry.name.toLowerCase();
+                if (!lower.endsWith(".ts"))
+                    continue;
+                if (!lower.includes("attributes"))
+                    continue;
+                let content = "";
+                try {
+                    content = fs.readFileSync(fullPath, "utf-8");
+                }
+                catch {
+                    continue;
+                }
+                const normalizedContent = normalize(content);
+                if (normalizedContent.includes(newNormalized) &&
+                    (!oldNormalized || !normalizedContent.includes(oldNormalized))) {
+                    return true;
+                }
+            }
+        }
+    }
+    catch {
+        // ignore
+    }
+    return false;
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Chama `fix_xpath_in_attributes` no MCP local para corrigir XPath em Attributes*.
+ *
+ * Transporte (item 26.2/28.5):
+ *  1. STDIO direto (Content-Length framing) — não requer user_hash (item 28.1)
+ *  2. HTTP local (HUB_MCP_LOCAL_URL) — requer user_hash
+ *  3. Backend MCP remoto (control-plane para reroute local por user_hash)
+ *
+ * - Faz health-check (tools/list) antes de chamar (item 26.3)
+ * - Parse robusto: top-level → content[].text (item 27.2/28.3)
+ * - Dedupe somente após resultado válido (item 28.4)
+ * - Retry curto (2 tentativas) para erros transitórios
+ * - Não bloqueia o teste em caso de falha
+ * - Pula em execução Azure (sem filesystem local)
+ *
+ * @returns Resultado da correção ou null se ignorado/falhou
+ */
+export async function fixXPathViaLocalMcp(params) {
+    // Não executar em Azure/CI
+    if (process.env.TF_BUILD === "True" ||
+        process.env.AGENT_NAME ||
+        process.env.CI === "true") {
+        return null;
+    }
+    // (item 28.1) user_hash agora é exigido apenas para HTTP, não para STDIO.
+    // A validação ocorre dentro de hasToolOnChannel/callMcpHttp para canais HTTP.
+    // Dedupe
+    const key = dedupeKey(params.oldXPath, params.newXPath, params.methodName);
+    if (_appliedFixes.has(key)) {
+        Logger.info(`[McpLocalClient] Auto-fix já aplicado nesta execução, ignorando: ${params.methodName || params.oldXPath}`);
+        return null;
+    }
+    // Enviar projectRoot exatamente como recebido (Windows/UNC)
+    let projectRoot = params.projectRoot || process.env.AUTOCORE_PROJECT_ROOT || "";
+    if (!projectRoot) {
+        try {
+            projectRoot = process.cwd();
+        }
+        catch { }
+    }
+    if (!projectRoot) {
+        Logger.warning("[McpLocalClient] projectRoot não disponível, auto-fix de arquivo ignorado.");
+        return null;
+    }
+    // Não normalizar nem converter barras; aceitar UNC/Windows
+    const args = {
+        projectRoot,
+        oldXPath: params.oldXPath,
+        newXPath: params.newXPath,
+        confidence: params.confidence ?? 0.8,
+        executionSource: params.executionSource || "Local",
+    };
+    if (params.attributesFile)
+        args.attributesFile = params.attributesFile;
+    if (params.className)
+        args.className = params.className;
+    if (params.methodName)
+        args.methodName = params.methodName;
+    for (let attempt = 1; attempt <= MCP_LOCAL_MAX_RETRIES; attempt++) {
+        try {
+            const { response, channel } = await callToolWithFallback("fix_xpath_in_attributes", args, {
+                allowBackend: true,
+            });
+            // (item 27.3) Log do canal utilizado
+            Logger.info(`[McpLocalClient] Canal utilizado: ${channel}`);
+            if (response.error) {
+                if (response.error.code === -32601 || response.error.code === -1) {
+                    Logger.warning(`[McpLocalClient] fix_xpath_in_attributes indisponível em todos os canais.`);
+                    return null;
+                }
+                throw new Error(response.error.message);
+            }
+            // (item 27.2/28.3) Parse robusto da resposta
+            const result = parseFixResult(response.result);
+            if (!result) {
+                Logger.warning("[McpLocalClient] Auto-fix sem payload estruturado de retorno.");
+                return null;
+            }
+            const diskConfirmed = verifyFixOnDisk({
+                filePath: result.filePath,
+                projectRoot,
+                oldXPath: params.oldXPath,
+                newXPath: params.newXPath,
+            });
+            const effectiveSuccess = result.success === true &&
+                (result.fileUpdated === true || diskConfirmed);
+            const normalizedResult = {
+                ...result,
+                success: effectiveSuccess,
+                fileUpdated: result.fileUpdated === true || diskConfirmed,
+            };
+            if (isValidForDedupe(normalizedResult)) {
+                _appliedFixes.add(key);
+            }
+            if (effectiveSuccess) {
+                Logger.success(`[McpLocalClient] ✅ XPath corrigido via MCP (${channel}): ${normalizedResult.filePath || "arquivo não informado"} (${normalizedResult.className || "?"}.${normalizedResult.methodName || "?"})`);
+            }
+            else {
+                Logger.warning(`[McpLocalClient] Auto-fix não confirmou escrita local (${channel}). Motivo: ${normalizedResult.error || "resultado incompleto"}`);
+            }
+            if (channel === "http-backend" &&
+                normalizedResult.executedOn === "backend-fallback") {
+                Logger.warning("[McpLocalClient] ⚠️ Auto-fix executado no backend-fallback; validação local recomendada.");
+            }
+            return normalizedResult;
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            if (attempt < MCP_LOCAL_MAX_RETRIES) {
+                Logger.warning(`[McpLocalClient] Tentativa ${attempt}/${MCP_LOCAL_MAX_RETRIES} falhou: ${msg}. Retentando...`);
+                await new Promise((r) => setTimeout(r, 500 * attempt));
+            }
+            else {
+                Logger.warning(`[McpLocalClient] fix_xpath_in_attributes falhou após ${MCP_LOCAL_MAX_RETRIES} tentativas: ${msg}`);
+            }
+        }
+    }
+    return null;
+}
+// ---------------------------------------------------------------------------
+// CodeGen local-first reroute (item 27.4)
+// ---------------------------------------------------------------------------
+/**
+ * Chama uma tool MCP (genérica) priorizando MCP local.
+ * Se o backend responder com `requiresLocalMcp=true`, reencaminha automaticamente
+ * para o STDIO local com o mesmo payload.
+ *
+ * Usado para `codegen`/ações Playwright que precisam rodar na máquina do usuário.
+ */
+export async function callMcpToolLocalFirst(toolName, args) {
+    // Não executar em Azure/CI
+    if (process.env.TF_BUILD === "True" ||
+        process.env.AGENT_NAME ||
+        process.env.CI === "true") {
+        return null;
+    }
+    try {
+        const requestArgs = enrichArgsWithUserHash(args);
+        const { response, channel } = await callToolWithFallback(toolName, requestArgs, {
+            allowBackend: true,
+        });
+        if (response.error) {
+            // Verificar se backend indicou que precisa de MCP local
+            const errMsg = response.error.message || "";
+            const errData = response.error.data;
+            if (errData?.requiresLocalMcp === true ||
+                errMsg.includes("requiresLocalMcp")) {
+                Logger.info(`[McpLocalClient] Backend requer MCP local para '${toolName}', reencaminhando via STDIO...`);
+                const ok = await ensureStdioProcess();
+                if (ok) {
+                    const localResponse = await callMcpStdio("tools/call", {
+                        name: toolName,
+                        arguments: requestArgs,
+                    });
+                    if (!localResponse.error) {
+                        return { result: localResponse.result, channel: "stdio" };
+                    }
+                    Logger.warning(`[McpLocalClient] Reroute STDIO falhou: ${localResponse.error.message}`);
+                }
+            }
+            Logger.warning(`[McpLocalClient] ${toolName} falhou: ${response.error.message}`);
+            return null;
+        }
+        return { result: response.result, channel };
+    }
+    catch (err) {
+        Logger.warning(`[McpLocalClient] Erro em ${toolName}: ${err instanceof Error ? err.message : String(err)}`);
+        return null;
+    }
+}
+export async function callMcpToolBackendFirst(toolName, args) {
+    if (process.env.TF_BUILD === "True" ||
+        process.env.AGENT_NAME ||
+        process.env.CI === "true") {
+        return null;
+    }
+    try {
+        const requestArgs = enrichArgsWithUserHash(args);
+        const { response, channel } = await callToolWithFallback(toolName, requestArgs, {
+            allowBackend: true,
+            preferBackend: true,
+        });
+        if (response.error) {
+            Logger.warning(`[McpLocalClient] ${toolName} falhou em modo backend-first: ${response.error.message}`);
+            return null;
+        }
+        return { result: response.result, channel };
+    }
+    catch (err) {
+        Logger.warning(`[McpLocalClient] Erro em ${toolName} (backend-first): ${err instanceof Error ? err.message : String(err)}`);
+        return null;
+    }
+}
+export async function getPortalSavedTests(params = {}) {
+    const response = await callMcpToolBackendFirst("get_portal_saved_tests", params);
+    if (!response?.result || typeof response.result !== "object")
+        return null;
+    const raw = response.result;
+    const portalTests = Array.isArray(raw.portalTests)
+        ? raw.portalTests
+        : [];
+    return {
+        total: typeof raw.total === "number" ? raw.total : portalTests.length,
+        includeCode: raw.includeCode === true,
+        retentionDays: typeof raw.retentionDays === "number" ? raw.retentionDays : undefined,
+        message: typeof raw.message === "string" ? raw.message : undefined,
+        portalTests,
+    };
+}
+export async function runLocalNpmScriptViaMcp(params) {
+    const response = await callMcpToolLocalFirst("run_local_npm_script", params);
+    if (!response?.result || typeof response.result !== "object")
+        return null;
+    const raw = response.result;
+    const payload = raw.payload && typeof raw.payload === "object"
+        ? raw.payload
+        : raw;
+    return {
+        ...payload,
+        success: payload.success === true || payload.exitCode === 0,
+        message: typeof payload.message === "string" ? payload.message : undefined,
+        command: typeof payload.command === "string" ? payload.command : undefined,
+        exitCode: typeof payload.exitCode === "number" ? payload.exitCode : undefined,
+        stdout: typeof payload.stdout === "string" ? payload.stdout : undefined,
+        stderr: typeof payload.stderr === "string" ? payload.stderr : undefined,
+    };
+}
+/** Limpa tracker de dedupe (chamar no início de cada execução, se desejado) */
+export function clearFixDedupeTracker() {
+    _appliedFixes.clear();
+}
+/** Limpa cache de health-check de tools (útil para testes) */
+export function clearToolsListCache() {
+    _toolsListCache.clear();
+}