primocode 11.0.0 → 11.2.0

package/lib/desktop.js

@@ -1,756 +0,0 @@
-/**
- * desktop.js — Controle nativo do computador: mouse, teclado, janelas e tela.
- * Zero dependências npm. Usa ferramentas nativas do SO:
- *   Linux:   xdotool (mouse/teclado/janelas) + scrot/maim/… (tela)
- *   macOS:   cliclick (brew install cliclick) e osascript/System Events
- *   Windows: powershell (user32 + UI Automation) — nada a instalar
- *
- * A regra do módulo: o agente NÃO enxerga pixels (os modelos são só-texto),
- * então ele enxerga por NOMES — as janelas abertas (listWindows), os botões e
- * ícones de cada janela (uiElements) e o clique pelo nome (clickElement).
- * Coordenada continua existindo, mas é o último recurso, não o primeiro.
- */
-
-'use strict';
-
-const { execSync } = require('child_process');
-const os = require('os');
-const { stripAccents } = require('./config');
-
-const PLATFORM = os.platform();
-
-function hasCmd(cmd) {
-    // cmd pode vir de texto do usuário (desktop_open_app com nome sem alias
-    // conhecido) — sem aspas aqui, um ";"/"&&" no meio vira comando extra.
-    try { execSync(`which ${sh1(cmd)} || where ${sh1(cmd)}`, { stdio: 'ignore' }); return true; } catch { return false; }
-}
-
-// Detectar ferramenta disponível
-const TOOLS = {
-    xdotool: PLATFORM === 'linux' && hasCmd('xdotool'),
-    cliclick: PLATFORM === 'darwin' && hasCmd('cliclick'),
-    nircmd: PLATFORM === 'win32' && (() => { try { execSync('where nircmd', {stdio:'ignore'}); return true; } catch { return false; } })(),
-};
-
-function run(cmd, opts = {}) {
-    try {
-        execSync(cmd, {
-            stdio: 'ignore',
-            timeout: opts.timeout || 15000,
-            env: opts.env ? { ...process.env, ...opts.env } : undefined,
-        });
-        return { ok: true };
-    } catch (e) { return { ok: false, error: e.message }; }
-}
-
-// Igual ao run(), mas devolve o stdout — para os comandos que PERGUNTAM algo
-// (listar janelas, ler elementos) em vez de só agir.
-function runOut(cmd, opts = {}) {
-    try {
-        const out = execSync(cmd, {
-            encoding: 'utf-8',
-            stdio: ['ignore', 'pipe', 'ignore'],
-            timeout: opts.timeout || 15000,
-            env: opts.env ? { ...process.env, ...opts.env } : undefined,
-        });
-        return { ok: true, out: String(out || '') };
-    } catch (e) { return { ok: false, error: e.message, out: String((e && e.stdout) || '') }; }
-}
-
-// Argumento de shell entre aspas simples, à prova de apóstrofo. O truque
-// POSIX é fechar a aspa, escapar o apóstrofo e reabrir: 'don'\''t'.
-function sh1(s) {
-    return `'${String(s).replace(/'/g, `'\\''`)}'`;
-}
-
-// PowerShell via -EncodedCommand: o script vai em base64 (UTF-16LE), então
-// aspas, cifrão e acento do texto do usuário NUNCA passam pelo cmd.exe cru.
-// A versão antiga escapava aspas à mão dentro de -Command "..." e quebrava
-// com qualquer texto que tivesse caractere especial — era um dos motivos de
-// "clica mas não digita" no Windows.
-function pwshCmd(script) {
-    const b64 = Buffer.from(script, 'utf16le').toString('base64');
-    return `powershell -NoProfile -NonInteractive -EncodedCommand ${b64}`;
-}
-function pwshRun(script, opts = {}) { return run(pwshCmd(script), opts); }
-function pwshOut(script, opts = {}) { return runOut(pwshCmd(script), opts); }
-
-// Clique/scroll de verdade no Windows precisam de mouse_event (user32).
-// A abordagem antiga só posicionava o cursor — nunca clicava.
-const WIN_USER32 = `Add-Type -Name U -Namespace W -MemberDefinition '[DllImport("user32.dll")] public static extern bool SetCursorPos(int X,int Y); [DllImport("user32.dll")] public static extern void mouse_event(uint f,uint dx,uint dy,uint d,int e);';`;
-
-// Primeira ferramenta cujo comando existe no PATH.
-function firstCmd(list) {
-    for (const c of list) if (hasCmd(c)) return c;
-    return null;
-}
-
-// Coordenada tem de ser número. Validar aqui vale para as três plataformas —
-// sem isso um x="abc" virava comando de shell quebrado, não erro legível.
-function coord(v) {
-    const n = Math.round(Number(v));
-    return Number.isFinite(n) ? n : null;
-}
-
-// ── Teclas: um dialeto por SO, uma tradução só ───────────────────────────
-// O modelo fala "ctrl+shift+t", "Enter", "alt+tab" — e cada SO tem a própria
-// gramática. Estas funções são puras (testáveis sem SO nenhum).
-
-/** "ctrl+shift+t" → { mods: ['ctrl','shift'], key: 't' } */
-function parseCombo(name) {
-    const parts = String(name || '').trim().split('+').map((s) => s.trim()).filter(Boolean);
-    const key = parts.pop() || '';
-    const mods = [];
-    for (const p of parts) {
-        const m = p.toLowerCase();
-        if (m === 'ctrl' || m === 'control') mods.push('ctrl');
-        else if (m === 'shift') mods.push('shift');
-        else if (m === 'alt' || m === 'option' || m === 'opt') mods.push('alt');
-        else if (m === 'cmd' || m === 'command' || m === 'win' || m === 'windows' || m === 'super' || m === 'meta') mods.push('super');
-    }
-    return { mods, key };
-}
-
-const F_RE = /^f([1-9]|1[0-2])$/i;
-
-// xdotool: nomes de keysym.
-const XKEYS = {
-    enter: 'Return', return: 'Return', tab: 'Tab', escape: 'Escape', esc: 'Escape',
-    backspace: 'BackSpace', delete: 'Delete', del: 'Delete', space: 'space',
-    arrowup: 'Up', up: 'Up', arrowdown: 'Down', down: 'Down',
-    arrowleft: 'Left', left: 'Left', arrowright: 'Right', right: 'Right',
-    home: 'Home', end: 'End', pageup: 'Prior', pagedown: 'Next',
-    insert: 'Insert', printscreen: 'Print',
-    win: 'Super_L', windows: 'Super_L', super: 'Super_L', cmd: 'Super_L', meta: 'Super_L',
-};
-
-/** "ctrl+shift+ArrowLeft" → "ctrl+shift+Left" (gramática do xdotool). */
-function xdoKey(name) {
-    const { mods, key } = parseCombo(name);
-    const k = key.toLowerCase();
-    const traduzida = XKEYS[k] || (F_RE.test(k) ? k.toUpperCase() : key);
-    return [...mods, traduzida].join('+');
-}
-
-// Windows SendKeys: ^=ctrl +=shift %=alt, especiais entre chaves.
-const WINKEYS = {
-    enter: '{ENTER}', return: '{ENTER}', tab: '{TAB}', escape: '{ESC}', esc: '{ESC}',
-    backspace: '{BACKSPACE}', delete: '{DEL}', del: '{DEL}', space: ' ',
-    arrowup: '{UP}', up: '{UP}', arrowdown: '{DOWN}', down: '{DOWN}',
-    arrowleft: '{LEFT}', left: '{LEFT}', arrowright: '{RIGHT}', right: '{RIGHT}',
-    home: '{HOME}', end: '{END}', pageup: '{PGUP}', pagedown: '{PGDN}',
-    insert: '{INS}', printscreen: '{PRTSC}',
-};
-
-/** Texto literal para SendKeys: +^%~(){}[] têm significado — vão entre chaves. */
-function escapeSendKeys(text) {
-    return String(text).replace(/[+^%~(){}[\]]/g, '{$&}');
-}
-
-/**
- * "ctrl+shift+t" → "^+t" (SendKeys). Devolve null quando o atalho usa a tecla
- * Windows, que o SendKeys não alcança — o chamador explica a alternativa.
- * "win" sozinho vira ^{ESC}, que abre o menu Iniciar desde sempre.
- */
-function winSendKeys(name) {
-    const { mods, key } = parseCombo(name);
-    const k = key.toLowerCase();
-    if (!mods.length && (k === 'win' || k === 'windows' || k === 'super' || k === 'meta' || k === 'cmd')) return '^{ESC}';
-    if (mods.includes('super')) return null;
-    const prefix = mods.map((m) => (m === 'ctrl' ? '^' : m === 'shift' ? '+' : '%')).join('');
-    let token = WINKEYS[k] || (F_RE.test(k) ? `{${k.toUpperCase()}}` : escapeSendKeys(key.length === 1 ? key.toLowerCase() : key));
-    // Modificador se aplica à PRÓXIMA tecla; um token de várias teclas precisa
-    // de parênteses para o modificador cobrir todas.
-    if (prefix && token.length > 1 && !/^\{[^}]+\}$/.test(token)) token = `(${token})`;
-    return prefix + token;
-}
-
-// macOS: tecla especial é key code NUMÉRICO; letra é keystroke.
-const MACCODES = {
-    enter: 36, return: 36, tab: 48, escape: 53, esc: 53, backspace: 51, delete: 117, del: 117,
-    space: 49, arrowleft: 123, left: 123, arrowright: 124, right: 124,
-    arrowdown: 125, down: 125, arrowup: 126, up: 126,
-    home: 115, end: 119, pageup: 116, pagedown: 121,
-    f1: 122, f2: 120, f3: 99, f4: 118, f5: 96, f6: 97, f7: 98, f8: 100, f9: 101, f10: 109, f11: 103, f12: 111,
-};
-
-/** A linha de System Events para uma tecla/atalho: `key code 36 using {...}`. */
-function macKeyScript(name) {
-    const { mods, key } = parseCombo(name);
-    const using = mods.map((m) => (m === 'ctrl' ? 'control down' : m === 'shift' ? 'shift down' : m === 'alt' ? 'option down' : 'command down')).join(', ');
-    const sufixo = using ? ` using {${using}}` : '';
-    const k = key.toLowerCase();
-    if (MACCODES[k] != null) return `key code ${MACCODES[k]}${sufixo}`;
-    const safe = String(key).replace(/\\/g, '\\\\').replace(/"/g, '\\"');
-    return `keystroke "${safe}"${sufixo}`;
-}
-
-function osascript(linhas, opts = {}) {
-    const script = Array.isArray(linhas) ? linhas.join('\n') : String(linhas);
-    return run(`osascript -e ${sh1(script)}`, opts);
-}
-function osascriptOut(linhas, opts = {}) {
-    const script = Array.isArray(linhas) ? linhas.join('\n') : String(linhas);
-    return runOut(`osascript -e ${sh1(script)}`, opts);
-}
-
-// ── Mouse ─────────────────────────────────────────────
-function click(x, y, button = 'left') {
-    const [xi, yi] = [coord(x), coord(y)];
-    if (xi == null || yi == null) return { ok: false, error: `Coordenada inválida: x=${x}, y=${y}` };
-    if (TOOLS.xdotool) return run(`xdotool mousemove ${xi} ${yi} click ${button === 'right' ? 3 : 1}`);
-    if (TOOLS.cliclick) return run(`cliclick ${button === 'right' ? 'rc' : 'c'}:${xi},${yi}`);
-    if (PLATFORM === 'win32') {
-        const down = button === 'right' ? '0x0008' : '0x0002';
-        const up = button === 'right' ? '0x0010' : '0x0004';
-        return pwshRun(`${WIN_USER32} [W.U]::SetCursorPos(${xi},${yi}); Start-Sleep -Milliseconds 40; [W.U]::mouse_event(${down},0,0,0,0); [W.U]::mouse_event(${up},0,0,0,0)`);
-    }
-    return { ok: false, error: 'Nenhuma ferramenta de automação encontrada. Instale xdotool (Linux) ou cliclick (macOS), ou use as tools browser_*.' };
-}
-
-// Clique duplo é o que ABRE as coisas fora do navegador: ícone da área de
-// trabalho, arquivo no Explorer, célula de planilha. Sem ele o agente "clicava
-// mas nada abria".
-function doubleClick(x, y) {
-    const [xi, yi] = [coord(x), coord(y)];
-    if (xi == null || yi == null) return { ok: false, error: `Coordenada inválida: x=${x}, y=${y}` };
-    if (TOOLS.xdotool) return run(`xdotool mousemove ${xi} ${yi} click --repeat 2 --delay 120 1`);
-    if (TOOLS.cliclick) return run(`cliclick dc:${xi},${yi}`);
-    if (PLATFORM === 'win32') {
-        const clique = '[W.U]::mouse_event(0x0002,0,0,0,0); [W.U]::mouse_event(0x0004,0,0,0,0)';
-        return pwshRun(`${WIN_USER32} [W.U]::SetCursorPos(${xi},${yi}); Start-Sleep -Milliseconds 40; ${clique}; Start-Sleep -Milliseconds 90; ${clique}`);
-    }
-    return { ok: false, error: 'Clique duplo não disponível: instale xdotool (Linux) ou cliclick (macOS).' };
-}
-
-function move(x, y) {
-    const [xi, yi] = [coord(x), coord(y)];
-    if (xi == null || yi == null) return { ok: false, error: `Coordenada inválida: x=${x}, y=${y}` };
-    if (TOOLS.xdotool) return run(`xdotool mousemove ${xi} ${yi}`);
-    if (TOOLS.cliclick) return run(`cliclick m:${xi},${yi}`);
-    if (PLATFORM === 'win32') {
-        return pwshRun(`${WIN_USER32} [W.U]::SetCursorPos(${xi},${yi})`);
-    }
-    return { ok: false, error: 'Automação não disponível' };
-}
-
-function drag(fromX, fromY, toX, toY) {
-    const [fx, fy, tx, ty] = [coord(fromX), coord(fromY), coord(toX), coord(toY)];
-    if ([fx, fy, tx, ty].some((v) => v == null)) return { ok: false, error: 'Coordenada inválida no drag' };
-    if (TOOLS.xdotool) {
-        return run(`xdotool mousemove ${fx} ${fy} mousedown 1 mousemove ${tx} ${ty} mouseup 1`);
-    }
-    if (TOOLS.cliclick) {
-        return run(`cliclick dd:${fx},${fy} du:${tx},${ty}`);
-    }
-    if (PLATFORM === 'win32') {
-        // Arrastar de verdade exige passos intermediários: soltar o botão no
-        // destino sem passar pelo caminho não conta como drag para o Windows.
-        const passos = [];
-        const N = 8;
-        for (let i = 1; i <= N; i++) {
-            const px = Math.round(fx + ((tx - fx) * i) / N);
-            const py = Math.round(fy + ((ty - fy) * i) / N);
-            passos.push(`[W.U]::SetCursorPos(${px},${py}); Start-Sleep -Milliseconds 25`);
-        }
-        return pwshRun(`${WIN_USER32} [W.U]::SetCursorPos(${fx},${fy}); Start-Sleep -Milliseconds 60; [W.U]::mouse_event(0x0002,0,0,0,0); Start-Sleep -Milliseconds 120; ${passos.join('; ')}; [W.U]::mouse_event(0x0004,0,0,0,0)`);
-    }
-    return { ok: false, error: 'Drag não suportado nesta plataforma sem xdotool/cliclick' };
-}
-
-function scroll(dy) {
-    const d = Number(dy);
-    const passo = Number.isFinite(d) ? d : 300;
-    if (TOOLS.xdotool) return run(`xdotool click --repeat ${Math.max(1, Math.abs(Math.round(passo / 50)))} ${passo > 0 ? 5 : 4}`);
-    if (TOOLS.cliclick) return run(`cliclick scroll:${Math.round(passo / 50)}`);
-    if (PLATFORM === 'win32') {
-        // Roda do mouse: 120 = um "clique". dy>0 rola para baixo (delta negativo).
-        const delta = -Math.round(passo / 50) * 120;
-        return pwshRun(`${WIN_USER32} [W.U]::mouse_event(0x0800,0,0,${delta},0)`);
-    }
-    return { ok: false, error: 'Scroll não suportado nesta plataforma' };
-}
-
-// ── Teclado ───────────────────────────────────────────
-function type(text) {
-    const t = String(text ?? '');
-    if (!t) return { ok: true, digitado: 0 };
-    if (TOOLS.xdotool) return run(`xdotool type --delay 12 -- ${sh1(t)}`);
-    if (PLATFORM === 'darwin') {
-        // Uma keystroke por linha; entre elas, Return de verdade (key code 36) —
-        // keystroke com "\n" no meio não quebra linha em app nenhum.
-        const linhas = t.split(/\r?\n/);
-        const corpo = [];
-        linhas.forEach((l, i) => {
-            if (i > 0) corpo.push('key code 36');
-            if (l) corpo.push(`keystroke "${l.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`);
-        });
-        return osascript(['tell application "System Events"', ...corpo, 'end tell']);
-    }
-    if (PLATFORM === 'win32') {
-        // SendKeys trata +^%~(){}[] como comando — escapar TUDO, senão digitar
-        // "olá (teste)" dispara atalho em vez de texto. Depois do escape, o Enter
-        // literal vira {ENTER}.
-        const seq = escapeSendKeys(t).replace(/\r?\n/g, '{ENTER}');
-        return pwshRun(`Add-Type -AssemblyName System.Windows.Forms; [System.Windows.Forms.SendKeys]::SendWait($env:PRIMO_KEYS)`, { env: { PRIMO_KEYS: seq } });
-    }
-    return { ok: false, error: 'Automação de teclado não disponível' };
-}
-
-function key(name) {
-    if (!name) return { ok: false, error: 'Diga a tecla: "Enter", "ctrl+c", "alt+tab"…' };
-    if (TOOLS.xdotool) return run(`xdotool key --clearmodifiers ${xdoKey(name)}`);
-
-    if (PLATFORM === 'darwin') {
-        return osascript(`tell application "System Events" to ${macKeyScript(name)}`);
-    }
-    if (PLATFORM === 'win32') {
-        const seq = winSendKeys(name);
-        if (seq === null) {
-            return { ok: false, error: 'Atalho com a tecla Windows não é alcançável por SendKeys. Alternativas: desktop_key("win") abre o menu Iniciar; desktop_open_app abre programas direto.' };
-        }
-        return pwshRun(`Add-Type -AssemblyName System.Windows.Forms; [System.Windows.Forms.SendKeys]::SendWait($env:PRIMO_KEYS)`, { env: { PRIMO_KEYS: seq } });
-    }
-    return { ok: false, error: 'Key não suportado nesta plataforma' };
-}
-
-// ── Programas e janelas ───────────────────────────────
-// Abrir app o agente já conseguia pelo shell; o que faltava era o resto da
-// conversa: saber QUAIS janelas existem, trazer uma para a frente e enxergar
-// o que há dentro dela. É isso que transforma "abre mas não interage" em
-// interação de verdade.
-
-// Nomes em português do dia a dia → executável/app real. Pequena de propósito:
-// só o que tem tradução óbvia. O resto passa direto como o usuário falou.
-const APP_ALIASES = {
-    win32: {
-        'bloco de notas': 'notepad', 'notepad': 'notepad', 'calculadora': 'calc',
-        'paint': 'mspaint', 'explorador de arquivos': 'explorer', 'arquivos': 'explorer',
-        'explorer': 'explorer', 'prompt de comando': 'cmd', 'terminal': 'wt',
-        'gerenciador de tarefas': 'taskmgr', 'configuracoes': 'ms-settings:',
-        'painel de controle': 'control', 'edge': 'msedge', 'word': 'winword',
-        'excel': 'excel', 'powerpoint': 'powerpnt',
-    },
-    darwin: {
-        'calculadora': 'Calculator', 'bloco de notas': 'TextEdit', 'notas': 'Notes',
-        'arquivos': 'Finder', 'finder': 'Finder', 'terminal': 'Terminal',
-        'chrome': 'Google Chrome', 'safari': 'Safari', 'musica': 'Music',
-        'fotos': 'Photos', 'configuracoes': 'System Settings', 'ajustes': 'System Settings',
-    },
-    linux: {
-        'calculadora': 'gnome-calculator', 'arquivos': 'nautilus',
-        'bloco de notas': 'gedit', 'editor de texto': 'gedit',
-        'terminal': 'gnome-terminal', 'chrome': 'google-chrome',
-    },
-};
-
-function normaliza(s) {
-    return stripAccents(s).toLowerCase().trim();
-}
-
-function aliasDoApp(nome, platform = PLATFORM) {
-    const mapa = APP_ALIASES[platform] || {};
-    return mapa[normaliza(nome)] || String(nome || '').trim();
-}
-
-function openApp(nome) {
-    const pedido = String(nome || '').trim();
-    if (!pedido) return { ok: false, error: 'Diga o nome do programa (ex: "chrome", "bloco de notas").' };
-    const app = aliasDoApp(pedido);
-
-    let r;
-    if (PLATFORM === 'win32') {
-        // Start-Process resolve PATH e App Paths (chrome, winword…); o start do
-        // cmd cobre o resto (URIs tipo ms-settings:, associações).
-        r = pwshOut(`$ErrorActionPreference='Stop'; $a=$env:PRIMO_APP; try { Start-Process $a; Write-Output 'OK' } catch { try { Start-Process -FilePath 'cmd.exe' -ArgumentList @('/c','start','',$a) -WindowStyle Hidden; Write-Output 'OK' } catch { Write-Output ('ERRO ' + $_.Exception.Message) } }`, { env: { PRIMO_APP: app } });
-        if (r.ok && !/^ERRO/m.test(r.out)) r = { ok: true };
-        else r = { ok: false, error: (r.out || r.error || '').trim() || `não consegui abrir "${app}"` };
-    } else if (PLATFORM === 'darwin') {
-        r = run(`open -a ${sh1(app)}`);
-        if (!r.ok && app !== pedido) r = run(`open -a ${sh1(pedido)}`);
-        if (!r.ok) r = { ok: false, error: `Não achei o app "${pedido}". Use o nome exato como aparece em /Applications.` };
-    } else {
-        const bin = app.split(/\s+/)[0];
-        if (hasCmd('gtk-launch') && run(`gtk-launch ${sh1(bin)}`).ok) r = { ok: true };
-        else if (hasCmd(bin)) {
-            // sh1() aqui só protegia o script INTEIRO como um argumento pro
-            // `bash -c` — dentro do script, bash reparsa o texto, e "app" cru
-            // continuava vulnerável a injeção (achado de segurança: um app tipo
-            // "a;touch /tmp/pwned;" executava o comando extra). Cada palavra de
-            // "app" agora entra entre aspas simples individualmente — preserva
-            // "programa --flag" como dois argumentos, mas nenhuma delas deixa
-            // metacaractere de shell passar como sintaxe.
-            const appEscapado = app.split(/\s+/).map(sh1).join(' ');
-            r = run(`bash -c ${sh1(`setsid ${appEscapado} >/dev/null 2>&1 < /dev/null &`)}`);
-        }
-        else r = { ok: false, error: `Não achei o programa "${pedido}" no PATH.` };
-    }
-
-    if (!r.ok) return r;
-    return { ok: true, app, dica: 'A janela pode levar 1–2s para abrir. Confirme com desktop_windows e traga para a frente com desktop_focus.' };
-}
-
-function listWindows() {
-    let linhas = [];
-    if (PLATFORM === 'win32') {
-        const r = pwshOut(`Get-Process | Where-Object { $_.MainWindowTitle } | ForEach-Object { $t = $_.MainWindowTitle -replace "[\\r\\n|]", " "; Write-Output ("$($_.ProcessName)|$t") }`, { timeout: 20000 });
-        if (!r.ok && !r.out) return { ok: false, error: r.error || 'não consegui listar as janelas' };
-        linhas = r.out.split('\n');
-    } else if (PLATFORM === 'darwin') {
-        const r = osascriptOut([
-            'set saida to ""',
-            'tell application "System Events"',
-            '  repeat with p in (application processes whose visible is true)',
-            '    repeat with w in windows of p',
-            '      try',
-            '        set saida to saida & (name of p) & "|" & (name of w) & linefeed',
-            '      end try',
-            '    end repeat',
-            '  end repeat',
-            'end tell',
-            'return saida',
-        ], { timeout: 20000 });
-        if (!r.ok) return { ok: false, error: 'Não consegui listar as janelas. Conceda permissão de Acessibilidade ao Terminal em Ajustes → Privacidade e Segurança.' };
-        linhas = r.out.split('\n');
-    } else {
-        if (hasCmd('wmctrl')) {
-            const r = runOut('wmctrl -l');
-            if (r.ok) linhas = r.out.split('\n').map((l) => {
-                const m = l.match(/^\S+\s+-?\d+\s+\S+\s+(.*)$/);
-                return m ? `|${m[1]}` : '';
-            });
-        } else if (TOOLS.xdotool) {
-            // O xdotool sai com código ≠ 0 se UMA janela da lista não tiver nome
-            // — mas o stdout com as outras continua valendo. Jogar a saída fora
-            // por causa do código fazia o total dar 0 com janelas na cara.
-            const r = runOut(`xdotool search --onlyvisible --name '.*' getwindowname %@ 2>/dev/null`);
-            if (r.out) linhas = r.out.split('\n').map((t) => (t.trim() ? `|${t.trim()}` : ''));
-        } else {
-            return { ok: false, error: 'Instale wmctrl ou xdotool para listar janelas no Linux.' };
-        }
-    }
-
-    const janelas = [];
-    for (const l of linhas) {
-        const linha = l.replace(/\r/g, '').trim();
-        if (!linha) continue;
-        const sep = linha.indexOf('|');
-        const app = sep >= 0 ? linha.slice(0, sep).trim() : '';
-        const titulo = (sep >= 0 ? linha.slice(sep + 1) : linha).trim();
-        if (titulo) janelas.push({ app, titulo });
-    }
-    return { ok: true, total: janelas.length, janelas: janelas.slice(0, 60) };
-}
-
-function focusWindow(titulo) {
-    const t = String(titulo || '').trim();
-    if (!t) return { ok: false, error: 'Diga o título (ou parte dele) da janela.' };
-
-    if (PLATFORM === 'win32') {
-        const r = pwshOut(
-            `$ErrorActionPreference='SilentlyContinue'
-Add-Type -Name W -Namespace P -MemberDefinition '[DllImport("user32.dll")] public static extern bool SetForegroundWindow(IntPtr h); [DllImport("user32.dll")] public static extern bool ShowWindow(IntPtr h, int n); [DllImport("user32.dll")] public static extern bool IsIconic(IntPtr h);'
-$t = $env:PRIMO_TITLE
-$p = Get-Process | Where-Object { $_.MainWindowTitle -and ($_.MainWindowTitle -match [regex]::Escape($t) -or $_.ProcessName -match [regex]::Escape($t)) } | Select-Object -First 1
-if (-not $p) { Write-Output 'NOTFOUND'; exit 0 }
-if ([P.W]::IsIconic($p.MainWindowHandle)) { [P.W]::ShowWindow($p.MainWindowHandle, 9) | Out-Null }
-[P.W]::SetForegroundWindow($p.MainWindowHandle) | Out-Null
-Write-Output $p.MainWindowTitle`,
-            { env: { PRIMO_TITLE: t }, timeout: 20000 },
-        );
-        const saida = (r.out || '').trim();
-        if (!r.ok && !saida) return { ok: false, error: r.error || 'falhou ao focar' };
-        if (/^NOTFOUND/m.test(saida)) return naoAchouJanela(t);
-        return { ok: true, janela: saida.split('\n')[0] };
-    }
-
-    if (PLATFORM === 'darwin') {
-        const safe = t.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
-        const r = osascript([
-            'tell application "System Events"',
-            `  set alvo to first application process whose visible is true and (name contains "${safe}" or displayed name contains "${safe}")`,
-            '  set frontmost of alvo to true',
-            'end tell',
-        ]);
-        if (!r.ok) return naoAchouJanela(t);
-        return { ok: true, janela: t };
-    }
-
-    if (TOOLS.xdotool) {
-        const busca = runOut(`xdotool search --onlyvisible --name ${sh1(t)} 2>/dev/null`);
-        const id = (busca.out || '').trim().split('\n')[0];
-        if (!id) return naoAchouJanela(t);
-        // windowactivate depende do window manager (EWMH). Sem ele — ou com um
-        // WM teimoso — raise+focus fazem o mesmo serviço.
-        const r = run(`xdotool windowactivate --sync ${id}`);
-        if (r.ok) return { ok: true, janela: t };
-        const raise = run(`xdotool windowraise ${id}`);
-        const foco = run(`xdotool windowfocus ${id}`);
-        return (raise.ok || foco.ok) ? { ok: true, janela: t } : r;
-    }
-    return { ok: false, error: 'Focar janela não disponível: instale xdotool (Linux).' };
-}
-
-// Erro que sabe o que EXISTE leva a informação junto — mesma ideia dos
-// "trechosParecidos" do edit_file. Erro seco faz o modelo chutar de novo.
-function naoAchouJanela(titulo) {
-    const w = listWindows();
-    return {
-        ok: false,
-        error: `Nenhuma janela combinou com "${titulo}".`,
-        janelasAbertas: w.ok ? w.janelas.map((j) => j.titulo).slice(0, 30) : undefined,
-        comoCorrigir: 'Use um título de "janelasAbertas", copiado literalmente (ou um pedaço único dele). Se o programa nem abriu, chame desktop_open_app antes.',
-    };
-}
-
-// ── Elementos da janela — os "olhos" do agente ────────────────────────────
-// Os modelos do servidor são só-texto: mandar um PNG não adianta nada. O que
-// funciona é ler a árvore de acessibilidade — a mesma que o leitor de tela usa
-// — e devolver NOME + POSIÇÃO de cada botão, campo e ícone. Aí "clique em
-// Salvar" vira coordenada exata, sem chute.
-
-const MAX_ELEMENTOS = 120;
-
-const PS_ELEMENTOS = `$ErrorActionPreference='SilentlyContinue'
-Add-Type -AssemblyName UIAutomationClient
-Add-Type -AssemblyName UIAutomationTypes
-Add-Type -Name W -Namespace P -MemberDefinition '[DllImport("user32.dll")] public static extern IntPtr GetForegroundWindow();'
-$titulo = $env:PRIMO_TITLE
-$root = [System.Windows.Automation.AutomationElement]::RootElement
-$win = $null
-if ($titulo) {
-  foreach ($w in $root.FindAll([System.Windows.Automation.TreeScope]::Children, [System.Windows.Automation.Condition]::TrueCondition)) {
-    if ($w.Current.Name -like ('*' + $titulo + '*')) { $win = $w; break }
-  }
-}
-if (-not $win) {
-  $h = [P.W]::GetForegroundWindow()
-  if ($h -ne [IntPtr]::Zero) { $win = [System.Windows.Automation.AutomationElement]::FromHandle($h) }
-}
-if (-not $win) { Write-Output 'SEMJANELA'; exit 0 }
-Write-Output ('JANELA|' + ($win.Current.Name -replace "[\\r\\n|]", ' '))
-$todos = $win.FindAll([System.Windows.Automation.TreeScope]::Descendants, [System.Windows.Automation.Condition]::TrueCondition)
-$n = 0
-foreach ($e in $todos) {
-  if ($n -ge ${MAX_ELEMENTOS}) { break }
-  $c = $e.Current
-  $nome = $c.Name
-  if (-not $nome) { continue }
-  if ($c.IsOffscreen) { continue }
-  $r = $c.BoundingRectangle
-  if ($r.Width -le 0 -or $r.Height -le 0) { continue }
-  $tipo = $c.ControlType.ProgrammaticName -replace 'ControlType\\.', ''
-  $cx = [int]($r.X + $r.Width / 2); $cy = [int]($r.Y + $r.Height / 2)
-  $nome = $nome -replace "[\\r\\n|]", ' '
-  Write-Output ("$tipo|$cx|$cy|$nome")
-  $n++
-}`;
-
-function uiElements(janela) {
-    const titulo = String(janela || '').trim();
-
-    if (PLATFORM === 'win32') {
-        const r = pwshOut(PS_ELEMENTOS, { env: { PRIMO_TITLE: titulo }, timeout: 45000 });
-        if (!r.ok && !r.out) return { ok: false, error: r.error || 'não consegui ler os elementos' };
-        if (/^SEMJANELA/m.test(r.out)) return { ok: false, error: 'Nenhuma janela em foco. Abra o programa (desktop_open_app) ou foque a janela (desktop_focus) primeiro.' };
-        return parseElementos(r.out);
-    }
-
-    if (PLATFORM === 'darwin') {
-        // `entire contents` lê a janela toda de uma vez; elemento sem nome ou
-        // sem posição só é pulado (o try engole).
-        const r = osascriptOut([
-            'set saida to ""',
-            'set n to 0',
-            'tell application "System Events"',
-            '  set p to first application process whose frontmost is true',
-            '  set saida to "JANELA|" & (name of p) & linefeed',
-            '  try',
-            '    set els to entire contents of front window of p',
-            '    repeat with e in els',
-            `      if n ≥ ${MAX_ELEMENTOS} then exit repeat`,
-            '      try',
-            '        set nm to name of e',
-            '        if nm is not missing value and nm is not "" then',
-            '          set {ex, ey} to position of e',
-            '          set {ew, eh} to size of e',
-            '          set saida to saida & (role of e) & "|" & (ex + ew div 2) & "|" & (ey + eh div 2) & "|" & nm & linefeed',
-            '          set n to n + 1',
-            '        end if',
-            '      end try',
-            '    end repeat',
-            '  end try',
-            'end tell',
-            'return saida',
-        ], { timeout: 45000 });
-        if (!r.ok) return { ok: false, error: 'Não consegui ler a janela. Conceda permissão de Acessibilidade ao Terminal em Ajustes → Privacidade e Segurança → Acessibilidade.' };
-        return parseElementos(r.out);
-    }
-
-    return { ok: false, error: 'Leitura de elementos não disponível no Linux. Caminho alternativo: desktop_screenshot para o usuário ver, e desktop_click com coordenadas (xdotool).' };
-}
-
-function parseElementos(saida) {
-    const elementos = [];
-    let janela = '';
-    const vistos = new Set();
-    for (const linha of String(saida || '').split('\n')) {
-        const l = linha.replace(/\r/g, '').trim();
-        if (!l) continue;
-        if (l.startsWith('JANELA|')) { janela = l.slice(7).trim(); continue; }
-        const partes = l.split('|');
-        if (partes.length < 4) continue;
-        const [tipo, xs, ys] = partes;
-        const nome = partes.slice(3).join('|').trim();
-        const x = Math.round(Number(xs)), y = Math.round(Number(ys));
-        if (!nome || !Number.isFinite(x) || !Number.isFinite(y)) continue;
-        const chave = `${tipo}|${x}|${y}|${nome}`;
-        if (vistos.has(chave)) continue;
-        vistos.add(chave);
-        elementos.push({ tipo: tipo.trim(), x, y, nome: nome.slice(0, 120) });
-        if (elementos.length >= MAX_ELEMENTOS) break;
-    }
-    if (!elementos.length) {
-        return { ok: false, error: 'A janela não expôs elementos nomeados (alguns apps escondem a árvore de acessibilidade). Use desktop_screenshot + desktop_click por coordenada.' , janela };
-    }
-    return { ok: true, janela, total: elementos.length, elementos };
-}
-
-/**
- * Melhor elemento para um nome pedido — sem acento, sem caixa, aceitando
- * pedaço ("salvar" acha "Salvar como…"). Pura, para o teste bater sem SO.
- */
-function escolherElemento(elementos, consulta) {
-    const q = normaliza(consulta);
-    if (!q) return null;
-    let melhor = null;
-    let nota = 0;
-    for (const e of elementos || []) {
-        const n = normaliza(e.nome);
-        if (!n) continue;
-        let s = 0;
-        // O nome que ESTENDE a consulta ("salvar como" → "Salvar como…") vale
-        // mais que a consulta estender o nome: quem pediu a frase maior quis o
-        // elemento maior, não o irmão de nome curto.
-        if (n === q) s = 100;
-        else if (n.startsWith(q)) s = 85;
-        else if (q.startsWith(n)) s = 75;
-        else if (n.includes(q)) s = 65;
-        else if (q.includes(n)) s = 55;
-        else {
-            const termos = q.split(/\s+/).filter((t) => t.length > 1);
-            const acertos = termos.filter((t) => n.includes(t)).length;
-            if (acertos) s = Math.round((40 * acertos) / termos.length);
-        }
-        if (!s) continue;
-        // Empate: nome mais curto costuma ser o botão em si, não a frase que o contém.
-        if (s > nota || (s === nota && melhor && e.nome.length < melhor.nome.length)) { nota = s; melhor = e; }
-    }
-    return nota >= 40 ? melhor : null;
-}
-
-function clickElement(nome, opts = {}) {
-    const pedido = String(nome || '').trim();
-    if (!pedido) return { ok: false, error: 'Diga o nome do elemento (o texto do botão, ícone ou campo).' };
-
-    const lidos = uiElements(opts.window);
-    if (!lidos.ok) return lidos;
-
-    const alvo = escolherElemento(lidos.elementos, pedido);
-    if (!alvo) {
-        return {
-            ok: false,
-            error: `Nenhum elemento parecido com "${pedido}" na janela "${lidos.janela}".`,
-            elementosDisponiveis: lidos.elementos.slice(0, 40).map((e) => e.nome),
-            comoCorrigir: 'Chame de novo com um nome de "elementosDisponiveis", copiado literalmente.',
-        };
-    }
-
-    const r = opts.double ? doubleClick(alvo.x, alvo.y) : click(alvo.x, alvo.y, opts.button || 'left');
-    if (!r.ok) return r;
-    return { ok: true, clicado: alvo.nome, tipo: alvo.tipo, x: alvo.x, y: alvo.y, duplo: !!opts.double };
-}
-
-// ── Screenshot ────────────────────────────────────────
-// A ferramenta do Linux é resolvida UMA vez: um `which` a cada screenshot
-// seria desperdício.
-let LINUX_SHOT;
-function linuxShot() {
-    if (LINUX_SHOT === undefined) LINUX_SHOT = firstCmd(['scrot', 'maim', 'gnome-screenshot', 'spectacle', 'import']);
-    return LINUX_SHOT;
-}
-
-/**
- * O comando de shell que fotografa a tela para `filename` — ou null quando a
- * plataforma não tem como. Existe separado do screenshot() para quem precisa
- * capturar de forma assíncrona, sem travar o processo.
- */
-function screenshotCommand(filename) {
-    if (PLATFORM === 'darwin') return `screencapture -x "${filename}"`;
-    if (PLATFORM === 'win32') {
-        const ps = `Add-Type -AssemblyName System.Drawing; Add-Type -AssemblyName System.Windows.Forms; $b=[System.Windows.Forms.Screen]::PrimaryScreen.Bounds; $bmp=New-Object System.Drawing.Bitmap($b.Width,$b.Height); $g=[System.Drawing.Graphics]::FromImage($bmp); $g.CopyFromScreen($b.Location,[System.Drawing.Point]::Empty,$bmp.Size); $bmp.Save('${filename.replace(/'/g, "''")}'); $g.Dispose(); $bmp.Dispose()`;
-        return pwshCmd(ps);
-    }
-    const tool = linuxShot();
-    if (tool === 'scrot') return `scrot -o "${filename}"`;
-    if (tool === 'maim') return `maim "${filename}"`;
-    if (tool === 'gnome-screenshot') return `gnome-screenshot -f "${filename}"`;
-    if (tool === 'spectacle') return `spectacle -b -n -o "${filename}"`;
-    if (tool === 'import') return `import -window root "${filename}"`; // ImageMagick
-    return null;
-}
-
-function screenshot(saveTo) {
-    const filename = saveTo || `desktop-${Date.now()}.png`;
-    const cmd = screenshotCommand(filename);
-    if (!cmd) return { ok: false, error: 'Screenshot indisponível no Linux. Instale scrot, maim, gnome-screenshot, spectacle ou ImageMagick (import).' };
-    const r = run(cmd);
-    return r.ok ? { ok: true, path: filename, bytes: sizeOf(filename) } : r;
-}
-
-function sizeOf(f) {
-    try { return require('fs').statSync(f).size; } catch { return 0; }
-}
-
-function getScreenSize() {
-    if (PLATFORM === 'win32') {
-        try {
-            const out = execSync(`powershell -Command "Add-Type -AssemblyName System.Windows.Forms; [System.Windows.Forms.Screen]::PrimaryScreen.Bounds.Size.Width.ToString() + ',' + [System.Windows.Forms.Screen]::PrimaryScreen.Bounds.Size.Height.ToString()"`).toString().trim();
-            const [w, h] = out.split(',').map(Number);
-            return { ok: true, width: w, height: h };
-        } catch { }
-    }
-    if (PLATFORM === 'darwin') {
-        try {
-            const out = execSync(`system_profiler SPDisplaysDataType | grep Resolution`).toString();
-            const m = out.match(/(\d+)\s*x\s*(\d+)/);
-            if (m) return { ok: true, width: parseInt(m[1]), height: parseInt(m[2]) };
-        } catch { }
-    }
-    if (TOOLS.xdotool) {
-        try {
-            const wh = execSync(`xdotool getdisplaygeometry`).toString().trim().split(' ');
-            return { ok: true, width: parseInt(wh[0]), height: parseInt(wh[1]) };
-        } catch { }
-    }
-    if (PLATFORM === 'linux') {
-        try {
-            const out = execSync(`xrandr --current 2>/dev/null | grep '\\*' | head -1`).toString();
-            const m = out.match(/(\d+)\s*x\s*(\d+)/);
-            if (m) return { ok: true, width: parseInt(m[1]), height: parseInt(m[2]) };
-        } catch { }
-    }
-    return { ok: false, error: 'Não foi possível detectar resolução', width: 1920, height: 1080 };
-}
-
-module.exports = {
-    click, doubleClick, move, drag, scroll,
-    type, key,
-    openApp, listWindows, focusWindow, uiElements, clickElement,
-    screenshot, screenshotCommand, getScreenSize,
-    TOOLS,
-    // Puras, exportadas para o test/desktop.test.js provar a tradução de teclas
-    // e a escolha de elemento sem depender do SO da máquina de teste.
-    parseCombo, xdoKey, winSendKeys, macKeyScript, escapeSendKeys,
-    escolherElemento, aliasDoApp,
-};