@justmpm/mmx-cli 0.1.0

package/dist/utils.js

@@ -0,0 +1,743 @@
+/**
+ * @justmpm/mmx-cli - Utilitários compartilhados
+ *
+ * Helpers para executar comandos do CLI `mmx` via child_process:
+ *   - resolveMmxInvocation(): estratégia em cascata (mmx global → npx)
+ *   - runMmx(): spawn seguro com timeout
+ *   - isAuthError(): detecção de erros de autenticação
+ *   - isQuotaError(): detecção de erro de quota
+ *   - checkMmxVersion(): health check no boot
+ *   - Mensagens de erro padronizadas
+ *   - runMmxVideoWithPolling(): polling async para vídeo com timeout
+ *   - Validação de paths (security: path traversal, realpath, size)
+ *   - Sanitização de erros (redact API keys)
+ *   - Concurrency limiter
+ */
+import { spawn, spawnSync } from "node:child_process";
+import { setTimeout as sleep } from "node:timers/promises";
+import { existsSync, mkdirSync, realpathSync, statSync } from "node:fs";
+import { join, resolve as resolvePath } from "node:path";
+import { MINIMUM_MMX_VERSION } from "./version.js";
+// =============================================================================
+// Resolução do binário (cascata)
+// =============================================================================
+let cachedInvocation = null;
+/**
+ * Procura um comando no PATH. Cross-platform sem dependência externa.
+ * - Windows: usa `where <cmd>` (via shell para resolver .cmd/.bat).
+ * - Unix: usa `command -v <cmd>` (POSIX).
+ *
+ * @returns Path absoluto do executável, ou `null` se não encontrado.
+ */
+export function findInPath(command) {
+    const isWindows = process.platform === "win32";
+    if (isWindows) {
+        const result = spawnSync("where", [command], {
+            shell: true,
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        if (result.status !== 0)
+            return null;
+        // `where` pode retornar múltiplas linhas; pegar a primeira absoluta.
+        const lines = result.stdout.toString().trim().split(/\r?\n/);
+        const first = lines[0]?.trim();
+        return first || null;
+    }
+    const result = spawnSync("command", ["-v", command], {
+        shell: true,
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+    if (result.status !== 0)
+        return null;
+    const out = result.stdout.toString().trim();
+    return out || null;
+}
+/**
+ * Determina como invocar o `mmx`. Estratégia em cascata:
+ * 1. `mmx` no PATH global (caso o cliente MCP tenha npm globals no PATH)
+ * 2. `npx -y mmx-cli` (sempre funciona em qualquer máquina com Node ≥ 18)
+ *
+ * O resultado é cacheado em memória para evitar resolução repetida.
+ */
+export function resolveMmxInvocation() {
+    if (cachedInvocation)
+        return cachedInvocation;
+    const mmxPath = findInPath("mmx");
+    if (mmxPath) {
+        cachedInvocation = { command: "mmx", prefixArgs: [] };
+    }
+    else {
+        cachedInvocation = { command: "npx", prefixArgs: ["-y", "mmx-cli", "mmx"] };
+    }
+    return cachedInvocation;
+}
+/**
+ * Reseta o cache de invocação. Útil para testes.
+ */
+export function _resetMmxInvocationCache() {
+    cachedInvocation = null;
+}
+// =============================================================================
+// Execução do CLI
+// =============================================================================
+/**
+ * Executa um comando do CLI `mmx` e retorna stdout, stderr e exitCode.
+ *
+ * Usa child_process.spawn (NÃO exec) por causa do limite de 1MB do exec.
+ * Suporta AbortSignal para cancelamento cooperativo.
+ * Limitado a 3 execuções simultâneas via `mmxConcurrencyLimiter`.
+ *
+ * @param args - Argumentos para o mmx (ex: ["image", "generate", "--prompt", "..."])
+ * @param options - cwd, env, timeoutMs (default 300_000 = 5min), signal (AbortSignal)
+ */
+export function runMmx(args, options = {}) {
+    return withConcurrency(() => runMmxInner(args, options));
+}
+/**
+ * Implementação interna de `runMmx` (sem concurrency limit).
+ * Usada por `runMmx` (com limit) e por testes.
+ */
+export function runMmxInner(args, options = {}) {
+    const invocation = resolveMmxInvocation();
+    const fullArgs = [...invocation.prefixArgs, ...args];
+    const timeoutMs = options.timeoutMs ?? 300_000;
+    const signal = options.signal;
+    return new Promise((resolve) => {
+        // Se signal já abortado, retornar imediatamente
+        if (signal?.aborted) {
+            resolve({ stdout: "", stderr: "[mmx-cli MCP] Operação cancelada antes de iniciar.", exitCode: 1 });
+            return;
+        }
+        const proc = spawn(invocation.command, fullArgs, {
+            stdio: ["ignore", "pipe", "pipe"],
+            shell: false,
+            cwd: options.cwd,
+            env: { ...process.env, ...options.env },
+            windowsHide: true,
+        });
+        let stdout = "";
+        let stderr = "";
+        let resolved = false;
+        const finish = (payload) => {
+            if (resolved)
+                return;
+            resolved = true;
+            resolve(payload);
+        };
+        proc.stdout.on("data", (chunk) => {
+            stdout += chunk.toString();
+        });
+        proc.stderr.on("data", (chunk) => {
+            stderr += chunk.toString();
+        });
+        proc.on("close", (code) => {
+            finish({ stdout, stderr, exitCode: code ?? 1 });
+        });
+        proc.on("error", (err) => {
+            finish({ stdout: "", stderr: err.message, exitCode: 1 });
+        });
+        // Timeout
+        if (timeoutMs > 0) {
+            const timer = setTimeout(() => {
+                proc.kill("SIGTERM");
+                // Se ainda não morreu em 5s, manda SIGKILL
+                setTimeout(() => proc.kill("SIGKILL"), 5_000).unref();
+                finish({
+                    stdout,
+                    stderr: `${stderr}\n[mmx-cli MCP] Timeout após ${Math.round(timeoutMs / 1000)}s. Processo encerrado.`,
+                    exitCode: 124, // conventional timeout exit code
+                });
+            }, timeoutMs);
+            proc.on("close", () => clearTimeout(timer));
+        }
+        // AbortSignal — cancelamento cooperativo
+        if (signal) {
+            const onAbort = () => {
+                proc.kill("SIGTERM");
+                setTimeout(() => proc.kill("SIGKILL"), 5_000).unref();
+                finish({
+                    stdout,
+                    stderr: `${stderr}\n[mmx-cli MCP] Operação cancelada pelo cliente.`,
+                    exitCode: 1,
+                });
+            };
+            signal.addEventListener("abort", onAbort, { once: true });
+            proc.on("close", () => signal.removeEventListener("abort", onAbort));
+        }
+    });
+}
+// =============================================================================
+// Polling de vídeo (async task com timeout)
+// =============================================================================
+const DEFAULT_MAX_WAIT_MS = 300_000; // 5min
+const DEFAULT_POLL_INTERVAL_MS = 10_000; // 10s (recomendado MiniMax notebook)
+/**
+ * Submete um vídeo para geração async, faz polling até conclusão, e
+ * baixa o vídeo IMEDIATAMENTE (file_id expira em 9h conforme notebook MiniMax).
+ *
+ * Retorna:
+ * - downloadPath: caminho do vídeo baixado em disco.
+ *
+ * Lança erro com mensagem amigável se timeout, fail, expired ou cancelamento.
+ *
+ * @param options.outputDir - Diretório onde salvar o vídeo (obrigatório)
+ * @param options.signal - AbortSignal para cancelamento cooperativo
+ */
+export async function runMmxVideoWithPolling(args, options = {
+    outputDir: "",
+}) {
+    const maxWaitMs = options.maxWaitMs ?? DEFAULT_MAX_WAIT_MS;
+    const pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+    const outputDir = options.outputDir;
+    const signal = options.signal;
+    const checkAbort = () => {
+        if (signal?.aborted) {
+            throw new Error("Operação de vídeo cancelada pelo cliente MCP.");
+        }
+    };
+    // 1) Submit --async para receber task_id
+    checkAbort();
+    const submitArgs = [...args, "--async", "--quiet", "--output", "json"];
+    const { stdout: submitOut, exitCode: submitExit } = await runMmx(submitArgs, { signal });
+    if (submitExit !== 0) {
+        throw new Error(`Falha ao submeter vídeo: ${submitOut.trim()}`);
+    }
+    let taskId;
+    try {
+        const parsed = JSON.parse(submitOut.trim());
+        if (typeof parsed.taskId !== "string") {
+            throw new Error(`taskId ausente na resposta: ${submitOut}`);
+        }
+        taskId = parsed.taskId;
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new Error(`Resposta inesperada ao submeter vídeo: ${submitOut}\n${msg}`);
+    }
+    // 2) Poll até conclusão ou timeout
+    const deadline = Date.now() + maxWaitMs;
+    let taskInfo;
+    while (Date.now() < deadline) {
+        checkAbort();
+        await sleep(pollIntervalMs);
+        checkAbort();
+        const { stdout: pollOut, exitCode: pollExit } = await runMmx(["video", "task", "get", "--task-id", taskId, "--output", "json"], { signal });
+        if (pollExit !== 0) {
+            // Continua tentando — pode ser flakiness transitória da rede.
+            continue;
+        }
+        try {
+            const parsed = JSON.parse(pollOut.trim());
+            taskInfo = parsed;
+            if (parsed.status === "Success") {
+                break;
+            }
+            if (parsed.status === "Fail" || parsed.status === "Expired") {
+                const reason = parsed.status === "Fail"
+                    ? parsed.error_message ?? "falha desconhecida"
+                    : "task expirada antes de ser processada";
+                throw new Error(`Geração de vídeo falhou (${parsed.status}): ${reason}`);
+            }
+        }
+        catch (err) {
+            if (err instanceof Error && err.message.startsWith("Geração de vídeo falhou")) {
+                throw err;
+            }
+            // Erro de parse — ignora e continua polling
+        }
+    }
+    checkAbort();
+    if (!taskInfo || taskInfo.status !== "Success") {
+        throw new Error(`Timeout (${Math.round(maxWaitMs / 1000)}s) aguardando vídeo. Task ${taskId} ainda em ${taskInfo?.status ?? "desconhecido"}. Use a tool mmx_video_task_get para continuar o polling manualmente.`);
+    }
+    if (!taskInfo.file_id) {
+        throw new Error(`Sucesso mas file_id ausente na task ${taskId}.`);
+    }
+    // 3) Download imediato (file_id expira em 9h — notebook MiniMax) no outputDir do user
+    const outPath = join(outputDir, `mmx-video-${taskId}.mp4`);
+    checkAbort();
+    const dlResult = await runMmx(["video", "download", "--file-id", taskInfo.file_id, "--out", outPath], { signal });
+    if (dlResult.exitCode !== 0) {
+        throw new Error(`Falha ao baixar vídeo: ${dlResult.stderr || dlResult.stdout}`);
+    }
+    const downloadPath = dlResult.stdout.trim();
+    return { downloadPath, taskInfo };
+}
+// =============================================================================
+// Detecção de erros
+// =============================================================================
+const AUTH_ERROR_PATTERNS = [
+    "401",
+    "403 forbidden", // algumas APIs retornam 403 quando auth inválida
+    "unauthorized",
+    "authentication",
+    "auth failed",
+    "session expired",
+    "not authenticated",
+    "credenciais",
+    "api key",
+    "invalid key",
+    "key inválida",
+];
+export function isAuthError(message) {
+    if (!message)
+        return false;
+    const lower = message.toLowerCase();
+    return AUTH_ERROR_PATTERNS.some((pattern) => lower.includes(pattern));
+}
+const QUOTA_ERROR_PATTERNS = [
+    "quota",
+    "rate limit",
+    "429",
+    "spending limit", // comum em APIs pay-as-you-go
+    "insufficient balance", // billing
+    "insufficient credits",
+    "credits exhausted",
+    "limit reached",
+    "too many requests",
+    "daily limit",
+    "monthly limit",
+    "exceeded your current quota",
+    "resource_exhausted",
+    "billing",
+];
+export function isQuotaError(message) {
+    if (!message)
+        return false;
+    const lower = message.toLowerCase();
+    return QUOTA_ERROR_PATTERNS.some((pattern) => lower.includes(pattern));
+}
+/**
+ * Detecta se o erro é devido ao CLI mmx não estar instalado.
+ * Útil para transformar `spawn ENOENT` em mensagem acionável.
+ */
+export function isCliNotInstalled(message) {
+    if (!message)
+        return false;
+    const lower = message.toLowerCase();
+    return (lower.includes("enoent") ||
+        lower.includes("command not found") ||
+        lower.includes("not found") && lower.includes("mmx"));
+}
+/**
+ * Detecta timeout (já é um erro conhecido).
+ */
+export function isTimeoutError(message) {
+    if (!message)
+        return false;
+    const lower = message.toLowerCase();
+    return lower.includes("timeout");
+}
+/**
+ * Detecta se o erro é "arquivo não existe" — comum em upload, vision, etc.
+ */
+export function isFileNotFound(message) {
+    if (!message)
+        return false;
+    const lower = message.toLowerCase();
+    return (lower.includes("file not found") ||
+        lower.includes("no such file") ||
+        lower.includes("path not found") ||
+        lower.includes("enoent") && lower.includes(".png") ||
+        lower.includes("enoent") && lower.includes(".jpg"));
+}
+// =============================================================================
+// Mensagens de erro padronizadas
+// =============================================================================
+/**
+ * Mensagem para erros de autenticação. Direciona para mmx_login
+ * e explica a diferença entre Pay-as-you-go e Token Plan.
+ */
+export function authErrorMessage(detail) {
+    return [
+        "Erro de autenticação. A sessão do mmx-cli expirou ou a API key é inválida.",
+        "Para resolver:",
+        "  1. Defina a variável de ambiente MINIMAX_API_KEY com uma chave Pay-as-you-go (sk-...) e reinicie o cliente MCP",
+        "  2. OU chame a tool mmx_login passando apiKey='sk-xxx' como argumento",
+        "Nota: Use Pay-as-you-go (sk-...), NÃO Token Plan (sk-cp-...). O Token Plan foi feito para uso individual e aplica throttling agressivo em batch.",
+        `Detalhes: ${detail}`,
+    ].join("\n");
+}
+/**
+ * Mensagem genérica — fallback usado quando nenhum pattern específico casa.
+ * Agora inclui instrução genérica de correção.
+ */
+export function genericErrorMessage(operation, detail) {
+    return [
+        `Erro ao ${operation}.`,
+        "Verifique os parâmetros e tente novamente. Se persistir, consulte o stderr abaixo para detalhes técnicos.",
+        `Detalhes: ${detail}`,
+    ].join("\n");
+}
+/**
+ * Mensagem específica quando o CLI mmx não está instalado.
+ * Guia o usuário a instalar.
+ */
+export function cliNotInstalledMessage(operation, detail) {
+    return [
+        `Não foi possível executar ${operation}: o CLI 'mmx' não está instalado ou não está no PATH.`,
+        "",
+        "Para corrigir:",
+        "  1. Instale globalmente: npm install -g mmx-cli",
+        "  2. Verifique com: mmx --version   (deve retornar 1.0.0+)",
+        "  3. Configure a API key: export MINIMAX_API_KEY='sk-...'",
+        "  4. Reinicie o cliente MCP (Claude Desktop / Cursor)",
+        "",
+        `Detalhes técnicos: ${detail}`,
+    ].join("\n");
+}
+/**
+ * Mensagem específica para quota excedida — com janela de reset e alternativas.
+ */
+export function quotaErrorMessage(operation, detail) {
+    return [
+        `Quota ou rate limit excedido em ${operation}.`,
+        "Como resolver:",
+        "  - Aguarde a janela de rate limit resetar (geralmente 1 minuto para RPM)",
+        "  - Se for Token Plan (janela 5h), aguarde reset ou faça upgrade",
+        "  - Se for Pay-as-you-go, verifique saldo em platform.minimax.io",
+        "  - Para operações caras, use mmx_quota_show antes de fazer batch",
+        `Detalhes: ${detail}`,
+    ].join("\n");
+}
+/**
+ * Mensagem específica para timeout.
+ */
+export function timeoutErrorMessage(operation, detail) {
+    return [
+        `Timeout em ${operation}.`,
+        "Como resolver:",
+        "  - Reduza o tamanho do input (texto menor, prompt mais simples)",
+        "  - Aumente o timeout se a operação for pesada (ex: vídeo longo)",
+        `Detalhes: ${detail}`,
+    ].join("\n");
+}
+/**
+ * Mensagem específica para arquivo não encontrado.
+ */
+export function fileNotFoundMessage(operation, filePath, detail) {
+    return [
+        `Arquivo não encontrado em ${operation}: "${filePath}".`,
+        "Verifique se:",
+        "  - O path existe e está acessível",
+        "  - Você usou path absoluto (recomendado) ou relativo ao cwd do MCP",
+        "  - O arquivo tem permissão de leitura",
+        `Detalhes: ${detail}`,
+    ].join("\n");
+}
+// =============================================================================
+// Helper unificado para handlers
+// =============================================================================
+/**
+ * Helper central para tratamento de erros em handlers de tool.
+ * Detecta automaticamente:
+ *   - mmx não instalado → cliNotInstalledMessage
+ *   - autenticação → authErrorMessage
+ *   - quota/rate limit → quotaErrorMessage
+ *   - timeout → timeoutErrorMessage
+ *   - arquivo não encontrado → fileNotFoundMessage
+ *   - genérico → genericErrorMessage
+ *
+ * Uso:
+ * ```ts
+ * const result = await runMmx(["image", "generate", "--prompt", prompt]);
+ * if (result.exitCode !== 0) {
+ *   return handleToolError("gerar imagem", result);
+ * }
+ * ```
+ */
+export function handleToolError(operation, result, options = {}) {
+    const errMsg = sanitizeErrorMessage((result.stderr || result.stdout || "").trim());
+    if (!errMsg) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: genericErrorMessage(operation, `Comando saiu com exitCode ${result.exitCode} sem mensagem de erro.`),
+                },
+            ],
+            isError: true,
+        };
+    }
+    if (isCliNotInstalled(errMsg)) {
+        return {
+            content: [{ type: "text", text: cliNotInstalledMessage(operation, errMsg) }],
+            isError: true,
+        };
+    }
+    if (isAuthError(errMsg)) {
+        return {
+            content: [{ type: "text", text: authErrorMessage(errMsg) }],
+            isError: true,
+        };
+    }
+    if (isQuotaError(errMsg)) {
+        return {
+            content: [{ type: "text", text: quotaErrorMessage(operation, errMsg) }],
+            isError: true,
+        };
+    }
+    if (isTimeoutError(errMsg)) {
+        return {
+            content: [{ type: "text", text: timeoutErrorMessage(operation, errMsg) }],
+            isError: true,
+        };
+    }
+    if (options.filePath && isFileNotFound(errMsg)) {
+        return {
+            content: [{ type: "text", text: fileNotFoundMessage(operation, options.filePath, errMsg) }],
+            isError: true,
+        };
+    }
+    return {
+        content: [{ type: "text", text: genericErrorMessage(operation, errMsg) }],
+        isError: true,
+    };
+}
+/**
+ * Compara duas versões semânticas (X.Y.Z). Retorna negativo se a < b.
+ */
+export function compareVersions(a, b) {
+    const pa = a.split(".").map((n) => Number.parseInt(n, 10));
+    const pb = b.split(".").map((n) => Number.parseInt(n, 10));
+    for (let i = 0; i < 3; i++) {
+        const va = pa[i] ?? 0;
+        const vb = pb[i] ?? 0;
+        if (va !== vb)
+            return va - vb;
+    }
+    return 0;
+}
+/**
+ * Roda `mmx --version` e extrai X.Y.Z.
+ * Retorna `installed: null` se mmx não está disponível.
+ */
+export async function checkMmxVersion() {
+    try {
+        const invocation = resolveMmxInvocation();
+        const args = [...invocation.prefixArgs, "--version"];
+        const invocationCommand = invocation.command;
+        const stdout = await new Promise((resolve, reject) => {
+            const proc = spawn(invocationCommand, args, {
+                stdio: ["ignore", "pipe", "pipe"],
+                shell: false,
+                windowsHide: true,
+            });
+            let out = "";
+            proc.stdout.on("data", (chunk) => {
+                out += chunk.toString();
+            });
+            proc.on("error", reject);
+            proc.on("close", (code) => {
+                if (code === 0)
+                    resolve(out.trim());
+                else
+                    reject(new Error(`exit ${code}`));
+            });
+        });
+        const match = stdout.match(/(\d+\.\d+\.\d+)/);
+        if (!match || !match[1]) {
+            return {
+                installed: null,
+                minimum: MINIMUM_MMX_VERSION,
+                ok: false,
+                message: `Não foi possível parsear a versão do mmx: "${stdout}"`,
+            };
+        }
+        const installed = match[1];
+        const ok = compareVersions(installed, MINIMUM_MMX_VERSION) >= 0;
+        return {
+            installed,
+            minimum: MINIMUM_MMX_VERSION,
+            ok,
+            message: ok
+                ? `mmx-cli v${installed} (>= ${MINIMUM_MMX_VERSION}).`
+                : `mmx-cli v${installed} detectado. Recomendado >= ${MINIMUM_MMX_VERSION}. Algumas tools podem falhar.`,
+        };
+    }
+    catch {
+        return {
+            installed: null,
+            minimum: MINIMUM_MMX_VERSION,
+            ok: false,
+            message: "mmx-cli não encontrado no PATH. Instale com: npm install -g mmx-cli (O MCP tentará usar npx mmx-cli como fallback).",
+        };
+    }
+}
+// =============================================================================
+// Path validation (security: path traversal + size + realpath)
+// =============================================================================
+/** Tamanho máximo padrão de arquivo de entrada (10MB). Acima disso, rejeitar. */
+export const MAX_INPUT_FILE_BYTES = 10 * 1024 * 1024;
+/**
+ * Valida um diretório de saída. Cria se não existir. Defesa contra path traversal.
+ *
+ * @param dir - Path do diretório (relativo ou absoluto)
+ * @param create - Se true, cria o diretório se não existir (default: true)
+ * @returns PathValidationResult com resolved path ou error
+ */
+export function validateOutputDir(dir, create = true) {
+    if (!dir || typeof dir !== "string") {
+        return { ok: false, resolved: "", error: "Diretório vazio." };
+    }
+    // Defesa contra path traversal óbvio (defesa em profundidade — IA deveria passar path válido)
+    if (dir.includes("\0")) {
+        return { ok: false, resolved: "", error: "Path contém caractere nulo." };
+    }
+    const resolved = resolvePath(dir);
+    try {
+        if (!existsSync(resolved)) {
+            if (!create) {
+                return { ok: false, resolved, error: `Diretório não existe: "${resolved}"` };
+            }
+            mkdirSync(resolved, { recursive: true });
+        }
+        else {
+            const stat = statSync(resolved);
+            if (!stat.isDirectory()) {
+                return { ok: false, resolved, error: `Path não é um diretório: "${resolved}"` };
+            }
+        }
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { ok: false, resolved, error: `Não foi possível criar/acessar diretório: ${msg}` };
+    }
+    return { ok: true, resolved };
+}
+/**
+ * Valida um arquivo de entrada. Defesa contra:
+ *   - Path traversal (`../../../etc/passwd`)
+ *   - Device files (`/dev/zero`, `\\.\NUL`)
+ *   - Arquivos excessivamente grandes (>MAX_INPUT_FILE_BYTES)
+ *
+ * @param filePath - Path do arquivo
+ * @param maxBytes - Limite custom (default: MAX_INPUT_FILE_BYTES = 10MB)
+ */
+export function validateInputFile(filePath, maxBytes = MAX_INPUT_FILE_BYTES) {
+    if (!filePath || typeof filePath !== "string") {
+        return { ok: false, resolved: "", error: "Path vazio." };
+    }
+    // Null byte injection
+    if (filePath.includes("\0")) {
+        return { ok: false, resolved: "", error: "Path contém caractere nulo." };
+    }
+    const resolved = resolvePath(filePath);
+    let stat;
+    try {
+        stat = statSync(resolved);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { ok: false, resolved, error: `Arquivo não encontrado: "${resolved}". ${msg}` };
+    }
+    if (!stat.isFile()) {
+        return {
+            ok: false,
+            resolved,
+            error: `Path não é um arquivo regular: "${resolved}". Device files e diretórios são rejeitados.`,
+        };
+    }
+    if (stat.size > maxBytes) {
+        const mb = Math.round(stat.size / 1024 / 1024);
+        const limitMb = Math.round(maxBytes / 1024 / 1024);
+        return {
+            ok: false,
+            resolved,
+            size: stat.size,
+            error: `Arquivo muito grande: ${mb}MB (limite: ${limitMb}MB).`,
+        };
+    }
+    // Resolve symlinks para garantir path final conhecido (defesa em profundidade)
+    let realpath = resolved;
+    try {
+        realpath = realpathSync(resolved);
+    }
+    catch {
+        // realpath pode falhar em alguns FS — manter resolved
+    }
+    return { ok: true, resolved: realpath, size: stat.size };
+}
+// =============================================================================
+// Error message sanitization (redact API keys)
+// =============================================================================
+/**
+ * Regex que captura API keys no estilo MiniMax (`sk-...` ou `sk-cp-...`).
+ * Pelo menos 20 chars alfanuméricos após o prefixo.
+ */
+const API_KEY_PATTERN = /sk-[a-zA-Z0-9_-]{20,}/gi;
+/**
+ * Redacta possíveis API keys em uma mensagem de erro antes de retornar pro LLM.
+ * Defesa contra keys vazadas via stderr do CLI.
+ */
+export function sanitizeErrorMessage(message) {
+    if (!message)
+        return message;
+    return message.replace(API_KEY_PATTERN, "sk-***REDACTED***");
+}
+// =============================================================================
+// Concurrency limiter
+// =============================================================================
+/**
+ * Semáforo simples para limitar número de execuções simultâneas do CLI `mmx`.
+ * Evita DoS local (10 tools em paralelo = 10 processos simultâneos).
+ *
+ * IMPORTANTE: `acquire()` rejeita após `queueTimeoutMs` para evitar
+ * tools travando indefinidamente em fila cheia.
+ */
+class ConcurrencyLimiter {
+    active = 0;
+    max;
+    queue = [];
+    queueTimeoutMs;
+    constructor(max, queueTimeoutMs = 60_000) {
+        this.max = max;
+        this.queueTimeoutMs = queueTimeoutMs;
+    }
+    async acquire() {
+        if (this.active < this.max) {
+            this.active++;
+            return;
+        }
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                const idx = this.queue.findIndex((q) => q.resolve === resolve);
+                if (idx !== -1)
+                    this.queue.splice(idx, 1);
+                reject(new Error(`[mmx-cli MCP] Fila de concorrência saturada (${this.active}/${this.max}). ` +
+                    `Timeout de ${Math.round(this.queueTimeoutMs / 1000)}s aguardando slot. ` +
+                    `Reduza o paralelismo ou aguarde tools em andamento.`));
+            }, this.queueTimeoutMs);
+            this.queue.push({ resolve, reject, timer });
+        });
+    }
+    release() {
+        this.active--;
+        const next = this.queue.shift();
+        if (next) {
+            this.active++;
+            clearTimeout(next.timer);
+            next.resolve();
+        }
+    }
+}
+/** Limiter global — max 3 chamadas simultâneas ao CLI `mmx`. */
+export const mmxConcurrencyLimiter = new ConcurrencyLimiter(3);
+/**
+ * Helper: executa uma função sob o limiter de concorrência.
+ * Garante release() mesmo em caso de throw.
+ * Se acquire() for rejeitado por timeout de fila, propaga o erro.
+ */
+export async function withConcurrency(fn) {
+    let acquired = false;
+    try {
+        await mmxConcurrencyLimiter.acquire();
+        acquired = true;
+        return await fn();
+    }
+    finally {
+        if (acquired)
+            mmxConcurrencyLimiter.release();
+    }
+}
+//# sourceMappingURL=utils.js.map