primocode 1.0.1 → 4.1.0

package/lib/tools.js

@@ -1,503 +1,503 @@
-// Ferramentas que o PrimoCode usa pra fazer as coisas.
-// Cada uma diz se deu certo ou nao.
-
-'use strict';
-
-const fs = require('fs');
-const path = require('path');
-const os = require('os');
-const { spawn, execSync } = require('child_process');
-const { c } = require('./ui');
-const browser = require('./browser');
-
-const MAX_FILE_BYTES = 200 * 1024;
-const IGNORED = new Set(['node_modules', '.git', '.next', '.turbo', 'dist', 'build', 'out', '.venv', '__pycache__', '.cache']);
-
-function safePath(p) { return path.resolve(process.cwd(), p); }
-
-function fmtBytes(n) {
-    if (n < 1024) return `${n} B`;
-    if (n < 1024 * 1024) return `${(n / 1024).toFixed(1)} KB`;
-    return `${(n / 1024 / 1024).toFixed(1)} MB`;
-}
-
-// ---- read_file --------------------------------------------------
-function readFile(rel) {
-    try {
-        const abs = safePath(rel);
-        if (!fs.existsSync(abs)) return { ok: false, error: `arquivo não existe: ${rel}` };
-        const stat = fs.statSync(abs);
-        if (stat.isDirectory()) return { ok: false, error: `${rel} é um diretório` };
-        let content = fs.readFileSync(abs, 'utf8');
-        let truncated = false;
-        if (stat.size > MAX_FILE_BYTES) {
-            content = content.slice(0, MAX_FILE_BYTES) + `\n\n[... truncado em ${MAX_FILE_BYTES} bytes de ${stat.size} totais]`;
-            truncated = true;
-        }
-        return { ok: true, path: rel, bytes: stat.size, truncated, content };
-    } catch (e) {
-        return { ok: false, error: e.message };
-    }
-}
-
-// ---- write_file -------------------------------------------------
-function writeFile(rel, content) {
-    try {
-        const abs = safePath(rel);
-        fs.mkdirSync(path.dirname(abs), { recursive: true });
-        const existed = fs.existsSync(abs);
-        fs.writeFileSync(abs, content, 'utf8');
-        return { ok: true, path: rel, bytes: Buffer.byteLength(content, 'utf8'), created: !existed, abs };
-    } catch (e) {
-        return { ok: false, error: e.message };
-    }
-}
-
-// ---- list_dir ---------------------------------------------------
-// Limites de segurança: profundidade + total de entradas + detecção de "home do usuário"
-const LIST_DIR_MAX_ENTRIES = 120;
-function isHomeDirectory(absPath) {
-    const home = require('os').homedir();
-    const norm = path.resolve(absPath);
-    return norm === path.resolve(home);
-}
-function listDir(rel = '.', depth = 2) {
-    try {
-        const root = safePath(rel);
-        if (!fs.existsSync(root)) return { ok: false, error: `diretório não existe: ${rel}` };
-
-        // Proteção: recusa listar o home do usuário (retorna dezenas de pastas irrelevantes tipo AppData, Documents...)
-        if (isHomeDirectory(root)) {
-            return {
-                ok: false,
-                error: `list_dir do diretório home do usuário é bloqueado (retorna centenas de arquivos irrelevantes). Peça ao usuário para navegar para uma pasta específica com "cd" antes, ou crie os arquivos diretamente com write_file usando o nome do arquivo.`,
-                is_home: true,
-            };
-        }
-
-        const out = [];
-        let truncated = false;
-        function walk(dir, prefix, d) {
-            if (d > depth || truncated) return;
-            let entries;
-            try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
-            entries = entries.filter(e => !IGNORED.has(e.name) && !e.name.startsWith('.'));
-            entries.sort((a, b) => (a.isDirectory() === b.isDirectory()) ? a.name.localeCompare(b.name) : (a.isDirectory() ? -1 : 1));
-            for (let i = 0; i < entries.length; i++) {
-                if (out.length >= LIST_DIR_MAX_ENTRIES) { truncated = true; return; }
-                const e = entries[i];
-                const last = i === entries.length - 1;
-                out.push(prefix + (last ? '└── ' : '├── ') + e.name + (e.isDirectory() ? '/' : ''));
-                if (e.isDirectory()) walk(path.join(dir, e.name), prefix + (last ? '    ' : '│   '), d + 1);
-                if (truncated) return;
-            }
-        }
-        out.push(path.basename(root) || rel);
-        walk(root, '', 1);
-        const entryCount = out.length - 1;
-        const summary = entryCount === 0
-            ? `Diretório '${rel}' está vazio (0 arquivos/pastas visíveis).`
-            : `Diretório '${rel}' contém ${entryCount} entradas${truncated ? ' (TRUNCADO em ' + LIST_DIR_MAX_ENTRIES + ' — dir muito grande)' : ' (arquivos+pastas, ocultos e node_modules excluídos)'}.`;
-        return { ok: true, path: rel, tree: out.join('\n'), summary, entryCount, truncated };
-    } catch (e) {
-        return { ok: false, error: e.message };
-    }
-}
-
-// ---- run_shell (streaming ao vivo para stdout) ------------------
-function runShellStream(command, opts = {}) {
-    return new Promise((resolve) => {
-        const timeout = opts.timeout || 60000;
-        const shell = process.platform === 'win32' ? true : '/bin/bash';
-        const child = spawn(command, {
-            shell,
-            cwd: process.cwd(),
-            env: process.env,
-            stdio: ['ignore', 'pipe', 'pipe'],
-        });
-
-        let stdout = '';
-        let stderr = '';
-        let killed = false;
-
-        const timer = setTimeout(() => {
-            killed = true;
-            try { child.kill('SIGKILL'); } catch {}
-        }, timeout);
-
-        const write = (data, target, color) => {
-            const s = data.toString();
-            if (target === 'stdout') stdout += s; else stderr += s;
-            // stream ao vivo para o terminal do usuário
-            const painted = color ? color(s) : s;
-            process.stdout.write(painted);
-        };
-        child.stdout.on('data', d => write(d, 'stdout', null));
-        child.stderr.on('data', d => write(d, 'stderr', c.err));
-
-        child.on('close', (code) => {
-            clearTimeout(timer);
-            const totalOut = (stdout + stderr).slice(-4000); // limita retorno pro modelo
-            resolve({
-                ok: code === 0 && !killed,
-                code: killed ? -1 : code,
-                killed,
-                stdout, stderr,
-                summary: `exit=${code}${killed ? ' (timeout)' : ''}, output(last 4KB):\n${totalOut}`,
-            });
-        });
-        child.on('error', (err) => {
-            clearTimeout(timer);
-            resolve({ ok: false, error: err.message, summary: `spawn error: ${err.message}` });
-        });
-    });
-}
-
-// versão sync usada pelo slash /run
-function runShellSync(command, opts = {}) {
-    const timeout = opts.timeout || 30000;
-    try {
-        const stdout = execSync(command, { stdio: ['ignore', 'pipe', 'pipe'], timeout, encoding: 'utf8', cwd: process.cwd() });
-        return { ok: true, stdout, code: 0 };
-    } catch (err) {
-        return {
-            ok: false,
-            stdout: err.stdout ? err.stdout.toString() : '',
-            stderr: err.stderr ? err.stderr.toString() : String(err.message),
-            code: err.status ?? 1,
-        };
-    }
-}
-
-// ---- open_in_browser (prefere Chrome) ---------------------------
-function findChrome() {
-    const platform = process.platform;
-    const candidates = platform === 'darwin' ? [
-        '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
-        '/Applications/Chromium.app/Contents/MacOS/Chromium',
-    ] : platform === 'win32' ? [
-        `${process.env['PROGRAMFILES']}\\Google\\Chrome\\Application\\chrome.exe`,
-        `${process.env['PROGRAMFILES(X86)']}\\Google\\Chrome\\Application\\chrome.exe`,
-        `${process.env['LOCALAPPDATA']}\\Google\\Chrome\\Application\\chrome.exe`,
-    ] : [
-        '/usr/bin/google-chrome',
-        '/usr/bin/google-chrome-stable',
-        '/usr/bin/chromium',
-        '/usr/bin/chromium-browser',
-        '/snap/bin/chromium',
-    ];
-    for (const p of candidates) {
-        try { if (p && fs.existsSync(p)) return p; } catch {}
-    }
-    return null;
-}
-
-function openInBrowser(target) {
-    try {
-        let url = target;
-        if (!/^https?:\/\//i.test(target)) {
-            const abs = safePath(target);
-            if (!fs.existsSync(abs)) return { ok: false, error: `arquivo não existe: ${target}` };
-            url = 'file://' + abs.replace(/\\/g, '/');
-        }
-
-        const platform = process.platform;
-        const chrome = findChrome();
-        let cmd, args, opener;
-
-        if (chrome) {
-            cmd = chrome; args = [url]; opener = 'chrome';
-        } else if (platform === 'darwin') {
-            cmd = 'open'; args = [url]; opener = 'open';
-        } else if (platform === 'win32') {
-            cmd = 'cmd'; args = ['/c', 'start', '""', url]; opener = 'cmd start';
-        } else {
-            cmd = process.env.PRIMOCODE_BROWSER_OPENER || 'xdg-open';
-            args = [url];
-            opener = cmd;
-        }
-        const child = spawn(cmd, args, { detached: true, stdio: 'ignore' });
-        child.on('error', () => {}); // não crasha se opener não existir
-        child.unref();
-        return { ok: true, url, opener };
-    } catch (e) {
-        return { ok: false, error: e.message };
-    }
-}
-
-// ---- run_in_new_terminal (abre nova janela) ---------------------
-function findLinuxTerminal() {
-    const list = ['gnome-terminal', 'konsole', 'xfce4-terminal', 'terminator', 'xterm'];
-    for (const t of list) {
-        try {
-            execSync(`command -v ${t}`, { stdio: 'ignore' });
-            return t;
-        } catch {}
-    }
-    return null;
-}
-
-function openInNewTerminal(command, cwd) {
-    try {
-        const workDir = cwd ? safePath(cwd) : process.cwd();
-        if (!fs.existsSync(workDir)) return { ok: false, error: `cwd não existe: ${cwd}` };
-
-        const platform = process.platform;
-
-        // Windows: abrir NOVA janela do cmd.exe (não usa shell:true que travava dentro do processo pai)
-        // Estratégia: 'cmd /c start "Título" cmd /k "…"'  → o start desanexa e cria window nova.
-        // Usamos shell:false para evitar aspas do PowerShell interpretando errado; passamos como array.
-        if (platform === 'win32') {
-            // Escapa aspas duplas para embutir em cmd /k
-            const escaped = command.replace(/"/g, '""');
-            // O truque é: cmd /c start "" cmd /k "cd /d "workdir" && comando"
-            // "" = título vazio (senão o primeiro "..." vira título)
-            const args = [
-                '/c',
-                'start', '""',           // start com título vazio → cria nova janela
-                'cmd', '/k',             // /k mantém aberto após comando terminar
-                `cd /d "${workDir}" && ${escaped}`,
-            ];
-            const child = spawn('cmd.exe', args, {
-                detached: true,
-                stdio: 'ignore',
-                windowsHide: false,
-                windowsVerbatimArguments: true,
-            });
-            child.on('error', () => {});
-            child.unref();
-            return { ok: true, opener: 'cmd (nova janela)', command, cwd: workDir };
-        }
-
-        if (platform === 'darwin') {
-            const cwdEsc = workDir.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
-            const cmdEsc = command.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
-            const script = `tell application "Terminal" to activate
-tell application "Terminal" to do script "cd \\"${cwdEsc}\\" && ${cmdEsc}"`;
-            const child = spawn('osascript', ['-e', script], { detached: true, stdio: 'ignore' });
-            child.on('error', () => {});
-            child.unref();
-            return { ok: true, opener: 'Terminal.app (nova janela)', command, cwd: workDir };
-        }
-
-        // Linux
-        const term = findLinuxTerminal();
-        if (!term) return { ok: false, error: 'nenhum terminal gráfico encontrado (gnome-terminal, konsole, xterm...)' };
-        let args;
-        if (term === 'gnome-terminal') {
-            args = ['--working-directory=' + workDir, '--', 'bash', '-c', `${command}; exec bash`];
-        } else if (term === 'konsole') {
-            args = ['--workdir', workDir, '-e', 'bash', '-c', `${command}; exec bash`];
-        } else if (term === 'xfce4-terminal' || term === 'terminator') {
-            args = ['--working-directory=' + workDir, '-e', `bash -c '${command.replace(/'/g, `'\\''`)}; exec bash'`];
-        } else {
-            args = ['-e', `bash -c 'cd "${workDir}" && ${command.replace(/'/g, `'\\''`)}; exec bash'`];
-        }
-        const child = spawn(term, args, { detached: true, stdio: 'ignore' });
-        child.on('error', () => {});
-        child.unref();
-        return { ok: true, opener: `${term} (nova janela)`, command, cwd: workDir };
-    } catch (e) {
-        return { ok: false, error: e.message };
-    }
-}
-
-// ---- extractCodeBlocks (usado por /apply e /write) --------------
-function extractCodeBlocks(md) {
-    const blocks = [];
-    const re = /```([\w+.-]*)\n([\s\S]*?)```/g;
-    let m;
-    while ((m = re.exec(md)) !== null) {
-        const lang = m[1] || '';
-        let content = m[2];
-        let filename = null;
-        const first = content.split('\n')[0];
-        const hint = first.match(/^(?:\/\/|#|--|<!--)\s*(?:filename|file|path)\s*[:=]\s*(.+?)\s*(?:-->)?$/i);
-        if (hint) {
-            filename = hint[1].trim();
-            content = content.split('\n').slice(1).join('\n');
-        }
-        blocks.push({ lang, filename, content });
-    }
-    return blocks;
-}
-
-// Wrapper para /read e /write "safe" (lançam)
-function readFileSafe(rel) {
-    const r = readFile(rel);
-    if (!r.ok) throw new Error(r.error);
-    return r.content;
-}
-function writeFileSafe(rel, content) {
-    const r = writeFile(rel, content);
-    if (!r.ok) throw new Error(r.error);
-    return r;
-}
-
-// Executa uma tool pedida pelo modelo. Retorna { ok, text_for_model, ui_summary }.
-async function executeTool(name, args, log) {
-    switch (name) {
-        case 'read_file': {
-            const r = readFile(args.path || '');
-            log && log.event('read_file', args.path, r);
-            return r.ok
-                ? { ok: true, text_for_model: JSON.stringify({ ok: true, content: r.content, bytes: r.bytes, truncated: r.truncated }) }
-                : { ok: false, text_for_model: JSON.stringify({ ok: false, error: r.error }) };
-        }
-        case 'write_file': {
-            const r = writeFile(args.path || '', args.content ?? '');
-            log && log.event('write_file', args.path, r);
-            return r.ok
-                ? { ok: true, text_for_model: JSON.stringify({ ok: true, path: r.path, bytes: r.bytes, created: r.created }) }
-                : { ok: false, text_for_model: JSON.stringify({ ok: false, error: r.error }) };
-        }
-        case 'list_dir': {
-            const r = listDir(args.path || '.');
-            log && log.event('list_dir', args.path || '.', r);
-            return r.ok
-                ? { ok: true, text_for_model: JSON.stringify({ ok: true, cwd: process.cwd(), tree: r.tree, summary: r.summary, entry_count: r.entryCount }) }
-                : { ok: false, text_for_model: JSON.stringify({ ok: false, error: r.error, hint: 'use path="." para o diretório atual' }) };
-        }
-        case 'run_shell': {
-            log && log.event('run_shell', args.command, null); // header antes de executar
-            const r = await runShellStream(args.command || '', { timeout: args.timeout_ms || 60000 });
-            log && log.event('run_shell_done', args.command, r);
-            return {
-                ok: r.ok,
-                text_for_model: JSON.stringify({ ok: r.ok, code: r.code, killed: r.killed, output: (r.stdout + r.stderr).slice(-4000) }),
-            };
-        }
-        case 'open_in_browser': {
-            const r = openInBrowser(args.target || '');
-            log && log.event('open_in_browser', args.target, r);
-            return r.ok
-                ? { ok: true, text_for_model: JSON.stringify({ ok: true, url: r.url, opener: r.opener }) }
-                : { ok: false, text_for_model: JSON.stringify({ ok: false, error: r.error }) };
-        }
-        case 'run_in_new_terminal': {
-            const r = openInNewTerminal(args.command || '', args.cwd);
-            log && log.event('run_in_new_terminal', args.command, r);
-            return r.ok
-                ? { ok: true, text_for_model: JSON.stringify({ ok: true, opener: r.opener, command: r.command, cwd: r.cwd }) }
-                : { ok: false, text_for_model: JSON.stringify({ ok: false, error: r.error }) };
-        }
-        case 'browser_open': {
-            try {
-                const r = await browser.open(args.url || 'about:blank');
-                log && log.event('browser_open', args.url, r);
-                return { ok: true, text_for_model: JSON.stringify({ ok: true, url: r.url }) };
-            } catch (e) {
-                log && log.event('browser_open', args.url, { ok: false, error: e.message });
-                return { ok: false, text_for_model: JSON.stringify({ ok: false, error: e.message }) };
-            }
-        }
-        case 'browser_navigate': {
-            try {
-                const r = await browser.navigate(args.url || '');
-                log && log.event('browser_navigate', args.url, r);
-                return { ok: true, text_for_model: JSON.stringify({ ok: true, url: r.url }) };
-            } catch (e) {
-                log && log.event('browser_navigate', args.url, { ok: false, error: e.message });
-                return { ok: false, text_for_model: JSON.stringify({ ok: false, error: e.message }) };
-            }
-        }
-        case 'browser_click': {
-            try {
-                let r;
-                if (args.selector) r = await browser.clickSelector(args.selector);
-                else if (args.text) r = await browser.clickText(args.text);
-                else if (typeof args.x === 'number' && typeof args.y === 'number') r = await browser.click(args.x, args.y);
-                else throw new Error('informe selector, text ou (x,y)');
-                log && log.event('browser_click', args.selector || args.text || `${args.x},${args.y}`, r);
-                return { ok: true, text_for_model: JSON.stringify(r) };
-            } catch (e) {
-                log && log.event('browser_click', args.selector || args.text, { ok: false, error: e.message });
-                return { ok: false, text_for_model: JSON.stringify({ ok: false, error: e.message }) };
-            }
-        }
-        case 'browser_type': {
-            try {
-                let r;
-                if (args.selector) r = await browser.typeInSelector(args.selector, args.text || '', args.clear !== false);
-                else r = await browser.type(args.text || '');
-                log && log.event('browser_type', `${args.selector || ''} · ${(args.text || '').length} chars`, r);
-                return { ok: true, text_for_model: JSON.stringify(r) };
-            } catch (e) {
-                log && log.event('browser_type', args.selector, { ok: false, error: e.message });
-                return { ok: false, text_for_model: JSON.stringify({ ok: false, error: e.message }) };
-            }
-        }
-        case 'browser_key': {
-            try {
-                const r = await browser.key(args.key || 'Enter');
-                log && log.event('browser_key', args.key, r);
-                return { ok: true, text_for_model: JSON.stringify(r) };
-            } catch (e) {
-                return { ok: false, text_for_model: JSON.stringify({ ok: false, error: e.message }) };
-            }
-        }
-        case 'browser_wait_for': {
-            try {
-                const r = await browser.waitFor(args.selector, args.timeout_ms || 15000);
-                log && log.event('browser_wait_for', args.selector, r);
-                return { ok: true, text_for_model: JSON.stringify(r) };
-            } catch (e) {
-                return { ok: false, text_for_model: JSON.stringify({ ok: false, error: e.message }) };
-            }
-        }
-        case 'browser_wait': {
-            const r = await browser.wait(args.ms || 1000);
-            log && log.event('browser_wait', `${r.ms}ms`, r);
-            return { ok: true, text_for_model: JSON.stringify(r) };
-        }
-        case 'browser_screenshot': {
-            try {
-                const r = await browser.screenshot(args.path || null);
-                log && log.event('browser_screenshot', r.path, r);
-                return { ok: true, text_for_model: JSON.stringify(r) };
-            } catch (e) {
-                return { ok: false, text_for_model: JSON.stringify({ ok: false, error: e.message }) };
-            }
-        }
-        case 'browser_eval': {
-            try {
-                const r = await browser.evaluate(args.js || '');
-                log && log.event('browser_eval', (args.js || '').slice(0, 60), { ok: true });
-                return { ok: true, text_for_model: JSON.stringify({ ok: true, value: r }) };
-            } catch (e) {
-                return { ok: false, text_for_model: JSON.stringify({ ok: false, error: e.message }) };
-            }
-        }
-        case 'browser_scroll': {
-            try {
-                const r = await browser.scroll(args.dy || 400);
-                log && log.event('browser_scroll', `${args.dy}`, r);
-                return { ok: true, text_for_model: JSON.stringify(r) };
-            } catch (e) {
-                return { ok: false, text_for_model: JSON.stringify({ ok: false, error: e.message }) };
-            }
-        }
-        case 'browser_url': {
-            try {
-                const u = await browser.currentUrl();
-                return { ok: true, text_for_model: JSON.stringify({ ok: true, url: u }) };
-            } catch (e) {
-                return { ok: false, text_for_model: JSON.stringify({ ok: false, error: e.message }) };
-            }
-        }
-        case 'finish': {
-            log && log.event('finish', args.summary, { ok: true });
-            return { ok: true, text_for_model: JSON.stringify({ ok: true, summary: args.summary }), finish: true };
-        }
-        default:
-            return { ok: false, text_for_model: JSON.stringify({ ok: false, error: `ferramenta desconhecida: ${name}` }) };
-    }
-}
-
-module.exports = {
-    readFile, writeFile, listDir, runShellStream, runShellSync,
-    openInBrowser, openInNewTerminal, findChrome,
-    readFileSafe, writeFileSafe,
-    extractCodeBlocks, executeTool, fmtBytes, safePath,
-    MAX_FILE_BYTES,
-};
+// Ferramentas que o PrimoCode usa pra fazer as coisas.
+// Cada uma diz se deu certo ou nao.
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { spawn, execSync } = require('child_process');
+const { c } = require('./ui');
+const browser = require('./browser');
+
+const MAX_FILE_BYTES = 200 * 1024;
+const IGNORED = new Set(['node_modules', '.git', '.next', '.turbo', 'dist', 'build', 'out', '.venv', '__pycache__', '.cache']);
+
+function safePath(p) { return path.resolve(process.cwd(), p); }
+
+function fmtBytes(n) {
+    if (n < 1024) return `${n} B`;
+    if (n < 1024 * 1024) return `${(n / 1024).toFixed(1)} KB`;
+    return `${(n / 1024 / 1024).toFixed(1)} MB`;
+}
+
+// ---- read_file --------------------------------------------------
+function readFile(rel) {
+    try {
+        const abs = safePath(rel);
+        if (!fs.existsSync(abs)) return { ok: false, error: `arquivo não existe: ${rel}` };
+        const stat = fs.statSync(abs);
+        if (stat.isDirectory()) return { ok: false, error: `${rel} é um diretório` };
+        let content = fs.readFileSync(abs, 'utf8');
+        let truncated = false;
+        if (stat.size > MAX_FILE_BYTES) {
+            content = content.slice(0, MAX_FILE_BYTES) + `\n\n[... truncado em ${MAX_FILE_BYTES} bytes de ${stat.size} totais]`;
+            truncated = true;
+        }
+        return { ok: true, path: rel, bytes: stat.size, truncated, content };
+    } catch (e) {
+        return { ok: false, error: e.message };
+    }
+}
+
+// ---- write_file -------------------------------------------------
+function writeFile(rel, content) {
+    try {
+        const abs = safePath(rel);
+        fs.mkdirSync(path.dirname(abs), { recursive: true });
+        const existed = fs.existsSync(abs);
+        fs.writeFileSync(abs, content, 'utf8');
+        return { ok: true, path: rel, bytes: Buffer.byteLength(content, 'utf8'), created: !existed, abs };
+    } catch (e) {
+        return { ok: false, error: e.message };
+    }
+}
+
+// ---- list_dir ---------------------------------------------------
+// Limites de segurança: profundidade + total de entradas + detecção de "home do usuário"
+const LIST_DIR_MAX_ENTRIES = 120;
+function isHomeDirectory(absPath) {
+    const home = require('os').homedir();
+    const norm = path.resolve(absPath);
+    return norm === path.resolve(home);
+}
+function listDir(rel = '.', depth = 2) {
+    try {
+        const root = safePath(rel);
+        if (!fs.existsSync(root)) return { ok: false, error: `diretório não existe: ${rel}` };
+
+        // Proteção: recusa listar o home do usuário (retorna dezenas de pastas irrelevantes tipo AppData, Documents...)
+        if (isHomeDirectory(root)) {
+            return {
+                ok: false,
+                error: `list_dir do diretório home do usuário é bloqueado (retorna centenas de arquivos irrelevantes). Peça ao usuário para navegar para uma pasta específica com "cd" antes, ou crie os arquivos diretamente com write_file usando o nome do arquivo.`,
+                is_home: true,
+            };
+        }
+
+        const out = [];
+        let truncated = false;
+        function walk(dir, prefix, d) {
+            if (d > depth || truncated) return;
+            let entries;
+            try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+            entries = entries.filter(e => !IGNORED.has(e.name) && !e.name.startsWith('.'));
+            entries.sort((a, b) => (a.isDirectory() === b.isDirectory()) ? a.name.localeCompare(b.name) : (a.isDirectory() ? -1 : 1));
+            for (let i = 0; i < entries.length; i++) {
+                if (out.length >= LIST_DIR_MAX_ENTRIES) { truncated = true; return; }
+                const e = entries[i];
+                const last = i === entries.length - 1;
+                out.push(prefix + (last ? '└── ' : '├── ') + e.name + (e.isDirectory() ? '/' : ''));
+                if (e.isDirectory()) walk(path.join(dir, e.name), prefix + (last ? '    ' : '│   '), d + 1);
+                if (truncated) return;
+            }
+        }
+        out.push(path.basename(root) || rel);
+        walk(root, '', 1);
+        const entryCount = out.length - 1;
+        const summary = entryCount === 0
+            ? `Diretório '${rel}' está vazio (0 arquivos/pastas visíveis).`
+            : `Diretório '${rel}' contém ${entryCount} entradas${truncated ? ' (TRUNCADO em ' + LIST_DIR_MAX_ENTRIES + ' — dir muito grande)' : ' (arquivos+pastas, ocultos e node_modules excluídos)'}.`;
+        return { ok: true, path: rel, tree: out.join('\n'), summary, entryCount, truncated };
+    } catch (e) {
+        return { ok: false, error: e.message };
+    }
+}
+
+// ---- run_shell (streaming ao vivo para stdout) ------------------
+function runShellStream(command, opts = {}) {
+    return new Promise((resolve) => {
+        const timeout = opts.timeout || 60000;
+        const shell = process.platform === 'win32' ? true : '/bin/bash';
+        const child = spawn(command, {
+            shell,
+            cwd: process.cwd(),
+            env: process.env,
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+
+        let stdout = '';
+        let stderr = '';
+        let killed = false;
+
+        const timer = setTimeout(() => {
+            killed = true;
+            try { child.kill('SIGKILL'); } catch {}
+        }, timeout);
+
+        const write = (data, target, color) => {
+            const s = data.toString();
+            if (target === 'stdout') stdout += s; else stderr += s;
+            // stream ao vivo para o terminal do usuário
+            const painted = color ? color(s) : s;
+            process.stdout.write(painted);
+        };
+        child.stdout.on('data', d => write(d, 'stdout', null));
+        child.stderr.on('data', d => write(d, 'stderr', c.err));
+
+        child.on('close', (code) => {
+            clearTimeout(timer);
+            const totalOut = (stdout + stderr).slice(-4000); // limita retorno pro modelo
+            resolve({
+                ok: code === 0 && !killed,
+                code: killed ? -1 : code,
+                killed,
+                stdout, stderr,
+                summary: `exit=${code}${killed ? ' (timeout)' : ''}, output(last 4KB):\n${totalOut}`,
+            });
+        });
+        child.on('error', (err) => {
+            clearTimeout(timer);
+            resolve({ ok: false, error: err.message, summary: `spawn error: ${err.message}` });
+        });
+    });
+}
+
+// versão sync usada pelo slash /run
+function runShellSync(command, opts = {}) {
+    const timeout = opts.timeout || 30000;
+    try {
+        const stdout = execSync(command, { stdio: ['ignore', 'pipe', 'pipe'], timeout, encoding: 'utf8', cwd: process.cwd() });
+        return { ok: true, stdout, code: 0 };
+    } catch (err) {
+        return {
+            ok: false,
+            stdout: err.stdout ? err.stdout.toString() : '',
+            stderr: err.stderr ? err.stderr.toString() : String(err.message),
+            code: err.status ?? 1,
+        };
+    }
+}
+
+// ---- open_in_browser (prefere Chrome) ---------------------------
+function findChrome() {
+    const platform = process.platform;
+    const candidates = platform === 'darwin' ? [
+        '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+        '/Applications/Chromium.app/Contents/MacOS/Chromium',
+    ] : platform === 'win32' ? [
+        `${process.env['PROGRAMFILES']}\\Google\\Chrome\\Application\\chrome.exe`,
+        `${process.env['PROGRAMFILES(X86)']}\\Google\\Chrome\\Application\\chrome.exe`,
+        `${process.env['LOCALAPPDATA']}\\Google\\Chrome\\Application\\chrome.exe`,
+    ] : [
+        '/usr/bin/google-chrome',
+        '/usr/bin/google-chrome-stable',
+        '/usr/bin/chromium',
+        '/usr/bin/chromium-browser',
+        '/snap/bin/chromium',
+    ];
+    for (const p of candidates) {
+        try { if (p && fs.existsSync(p)) return p; } catch {}
+    }
+    return null;
+}
+
+function openInBrowser(target) {
+    try {
+        let url = target;
+        if (!/^https?:\/\//i.test(target)) {
+            const abs = safePath(target);
+            if (!fs.existsSync(abs)) return { ok: false, error: `arquivo não existe: ${target}` };
+            url = 'file://' + abs.replace(/\\/g, '/');
+        }
+
+        const platform = process.platform;
+        const chrome = findChrome();
+        let cmd, args, opener;
+
+        if (chrome) {
+            cmd = chrome; args = [url]; opener = 'chrome';
+        } else if (platform === 'darwin') {
+            cmd = 'open'; args = [url]; opener = 'open';
+        } else if (platform === 'win32') {
+            cmd = 'cmd'; args = ['/c', 'start', '""', url]; opener = 'cmd start';
+        } else {
+            cmd = process.env.PRIMOCODE_BROWSER_OPENER || 'xdg-open';
+            args = [url];
+            opener = cmd;
+        }
+        const child = spawn(cmd, args, { detached: true, stdio: 'ignore' });
+        child.on('error', () => {}); // não crasha se opener não existir
+        child.unref();
+        return { ok: true, url, opener };
+    } catch (e) {
+        return { ok: false, error: e.message };
+    }
+}
+
+// ---- run_in_new_terminal (abre nova janela) ---------------------
+function findLinuxTerminal() {
+    const list = ['gnome-terminal', 'konsole', 'xfce4-terminal', 'terminator', 'xterm'];
+    for (const t of list) {
+        try {
+            execSync(`command -v ${t}`, { stdio: 'ignore' });
+            return t;
+        } catch {}
+    }
+    return null;
+}
+
+function openInNewTerminal(command, cwd) {
+    try {
+        const workDir = cwd ? safePath(cwd) : process.cwd();
+        if (!fs.existsSync(workDir)) return { ok: false, error: `cwd não existe: ${cwd}` };
+
+        const platform = process.platform;
+
+        // Windows: abrir NOVA janela do cmd.exe (não usa shell:true que travava dentro do processo pai)
+        // Estratégia: 'cmd /c start "Título" cmd /k "…"'  → o start desanexa e cria window nova.
+        // Usamos shell:false para evitar aspas do PowerShell interpretando errado; passamos como array.
+        if (platform === 'win32') {
+            // Escapa aspas duplas para embutir em cmd /k
+            const escaped = command.replace(/"/g, '""');
+            // O truque é: cmd /c start "" cmd /k "cd /d "workdir" && comando"
+            // "" = título vazio (senão o primeiro "..." vira título)
+            const args = [
+                '/c',
+                'start', '""',           // start com título vazio → cria nova janela
+                'cmd', '/k',             // /k mantém aberto após comando terminar
+                `cd /d "${workDir}" && ${escaped}`,
+            ];
+            const child = spawn('cmd.exe', args, {
+                detached: true,
+                stdio: 'ignore',
+                windowsHide: false,
+                windowsVerbatimArguments: true,
+            });
+            child.on('error', () => {});
+            child.unref();
+            return { ok: true, opener: 'cmd (nova janela)', command, cwd: workDir };
+        }
+
+        if (platform === 'darwin') {
+            const cwdEsc = workDir.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+            const cmdEsc = command.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+            const script = `tell application "Terminal" to activate
+tell application "Terminal" to do script "cd \\"${cwdEsc}\\" && ${cmdEsc}"`;
+            const child = spawn('osascript', ['-e', script], { detached: true, stdio: 'ignore' });
+            child.on('error', () => {});
+            child.unref();
+            return { ok: true, opener: 'Terminal.app (nova janela)', command, cwd: workDir };
+        }
+
+        // Linux
+        const term = findLinuxTerminal();
+        if (!term) return { ok: false, error: 'nenhum terminal gráfico encontrado (gnome-terminal, konsole, xterm...)' };
+        let args;
+        if (term === 'gnome-terminal') {
+            args = ['--working-directory=' + workDir, '--', 'bash', '-c', `${command}; exec bash`];
+        } else if (term === 'konsole') {
+            args = ['--workdir', workDir, '-e', 'bash', '-c', `${command}; exec bash`];
+        } else if (term === 'xfce4-terminal' || term === 'terminator') {
+            args = ['--working-directory=' + workDir, '-e', `bash -c '${command.replace(/'/g, `'\\''`)}; exec bash'`];
+        } else {
+            args = ['-e', `bash -c 'cd "${workDir}" && ${command.replace(/'/g, `'\\''`)}; exec bash'`];
+        }
+        const child = spawn(term, args, { detached: true, stdio: 'ignore' });
+        child.on('error', () => {});
+        child.unref();
+        return { ok: true, opener: `${term} (nova janela)`, command, cwd: workDir };
+    } catch (e) {
+        return { ok: false, error: e.message };
+    }
+}
+
+// ---- extractCodeBlocks (usado por /apply e /write) --------------
+function extractCodeBlocks(md) {
+    const blocks = [];
+    const re = /```([\w+.-]*)\n([\s\S]*?)```/g;
+    let m;
+    while ((m = re.exec(md)) !== null) {
+        const lang = m[1] || '';
+        let content = m[2];
+        let filename = null;
+        const first = content.split('\n')[0];
+        const hint = first.match(/^(?:\/\/|#|--|<!--)\s*(?:filename|file|path)\s*[:=]\s*(.+?)\s*(?:-->)?$/i);
+        if (hint) {
+            filename = hint[1].trim();
+            content = content.split('\n').slice(1).join('\n');
+        }
+        blocks.push({ lang, filename, content });
+    }
+    return blocks;
+}
+
+// Wrapper para /read e /write "safe" (lançam)
+function readFileSafe(rel) {
+    const r = readFile(rel);
+    if (!r.ok) throw new Error(r.error);
+    return r.content;
+}
+function writeFileSafe(rel, content) {
+    const r = writeFile(rel, content);
+    if (!r.ok) throw new Error(r.error);
+    return r;
+}
+
+// Executa uma tool pedida pelo modelo. Retorna { ok, text_for_model, ui_summary }.
+async function executeTool(name, args, log) {
+    switch (name) {
+        case 'read_file': {
+            const r = readFile(args.path || '');
+            log && log.event('read_file', args.path, r);
+            return r.ok
+                ? { ok: true, text_for_model: JSON.stringify({ ok: true, content: r.content, bytes: r.bytes, truncated: r.truncated }) }
+                : { ok: false, text_for_model: JSON.stringify({ ok: false, error: r.error }) };
+        }
+        case 'write_file': {
+            const r = writeFile(args.path || '', args.content ?? '');
+            log && log.event('write_file', args.path, r);
+            return r.ok
+                ? { ok: true, text_for_model: JSON.stringify({ ok: true, path: r.path, bytes: r.bytes, created: r.created }) }
+                : { ok: false, text_for_model: JSON.stringify({ ok: false, error: r.error }) };
+        }
+        case 'list_dir': {
+            const r = listDir(args.path || '.');
+            log && log.event('list_dir', args.path || '.', r);
+            return r.ok
+                ? { ok: true, text_for_model: JSON.stringify({ ok: true, cwd: process.cwd(), tree: r.tree, summary: r.summary, entry_count: r.entryCount }) }
+                : { ok: false, text_for_model: JSON.stringify({ ok: false, error: r.error, hint: 'use path="." para o diretório atual' }) };
+        }
+        case 'run_shell': {
+            log && log.event('run_shell', args.command, null); // header antes de executar
+            const r = await runShellStream(args.command || '', { timeout: args.timeout_ms || 60000 });
+            log && log.event('run_shell_done', args.command, r);
+            return {
+                ok: r.ok,
+                text_for_model: JSON.stringify({ ok: r.ok, code: r.code, killed: r.killed, output: (r.stdout + r.stderr).slice(-4000) }),
+            };
+        }
+        case 'open_in_browser': {
+            const r = openInBrowser(args.target || '');
+            log && log.event('open_in_browser', args.target, r);
+            return r.ok
+                ? { ok: true, text_for_model: JSON.stringify({ ok: true, url: r.url, opener: r.opener }) }
+                : { ok: false, text_for_model: JSON.stringify({ ok: false, error: r.error }) };
+        }
+        case 'run_in_new_terminal': {
+            const r = openInNewTerminal(args.command || '', args.cwd);
+            log && log.event('run_in_new_terminal', args.command, r);
+            return r.ok
+                ? { ok: true, text_for_model: JSON.stringify({ ok: true, opener: r.opener, command: r.command, cwd: r.cwd }) }
+                : { ok: false, text_for_model: JSON.stringify({ ok: false, error: r.error }) };
+        }
+        case 'browser_open': {
+            try {
+                const r = await browser.open(args.url || 'about:blank');
+                log && log.event('browser_open', args.url, r);
+                return { ok: true, text_for_model: JSON.stringify({ ok: true, url: r.url }) };
+            } catch (e) {
+                log && log.event('browser_open', args.url, { ok: false, error: e.message });
+                return { ok: false, text_for_model: JSON.stringify({ ok: false, error: e.message }) };
+            }
+        }
+        case 'browser_navigate': {
+            try {
+                const r = await browser.navigate(args.url || '');
+                log && log.event('browser_navigate', args.url, r);
+                return { ok: true, text_for_model: JSON.stringify({ ok: true, url: r.url }) };
+            } catch (e) {
+                log && log.event('browser_navigate', args.url, { ok: false, error: e.message });
+                return { ok: false, text_for_model: JSON.stringify({ ok: false, error: e.message }) };
+            }
+        }
+        case 'browser_click': {
+            try {
+                let r;
+                if (args.selector) r = await browser.clickSelector(args.selector);
+                else if (args.text) r = await browser.clickText(args.text);
+                else if (typeof args.x === 'number' && typeof args.y === 'number') r = await browser.click(args.x, args.y);
+                else throw new Error('informe selector, text ou (x,y)');
+                log && log.event('browser_click', args.selector || args.text || `${args.x},${args.y}`, r);
+                return { ok: true, text_for_model: JSON.stringify(r) };
+            } catch (e) {
+                log && log.event('browser_click', args.selector || args.text, { ok: false, error: e.message });
+                return { ok: false, text_for_model: JSON.stringify({ ok: false, error: e.message }) };
+            }
+        }
+        case 'browser_type': {
+            try {
+                let r;
+                if (args.selector) r = await browser.typeInSelector(args.selector, args.text || '', args.clear !== false);
+                else r = await browser.type(args.text || '');
+                log && log.event('browser_type', `${args.selector || ''} · ${(args.text || '').length} chars`, r);
+                return { ok: true, text_for_model: JSON.stringify(r) };
+            } catch (e) {
+                log && log.event('browser_type', args.selector, { ok: false, error: e.message });
+                return { ok: false, text_for_model: JSON.stringify({ ok: false, error: e.message }) };
+            }
+        }
+        case 'browser_key': {
+            try {
+                const r = await browser.key(args.key || 'Enter');
+                log && log.event('browser_key', args.key, r);
+                return { ok: true, text_for_model: JSON.stringify(r) };
+            } catch (e) {
+                return { ok: false, text_for_model: JSON.stringify({ ok: false, error: e.message }) };
+            }
+        }
+        case 'browser_wait_for': {
+            try {
+                const r = await browser.waitFor(args.selector, args.timeout_ms || 15000);
+                log && log.event('browser_wait_for', args.selector, r);
+                return { ok: true, text_for_model: JSON.stringify(r) };
+            } catch (e) {
+                return { ok: false, text_for_model: JSON.stringify({ ok: false, error: e.message }) };
+            }
+        }
+        case 'browser_wait': {
+            const r = await browser.wait(args.ms || 1000);
+            log && log.event('browser_wait', `${r.ms}ms`, r);
+            return { ok: true, text_for_model: JSON.stringify(r) };
+        }
+        case 'browser_screenshot': {
+            try {
+                const r = await browser.screenshot(args.path || null);
+                log && log.event('browser_screenshot', r.path, r);
+                return { ok: true, text_for_model: JSON.stringify(r) };
+            } catch (e) {
+                return { ok: false, text_for_model: JSON.stringify({ ok: false, error: e.message }) };
+            }
+        }
+        case 'browser_eval': {
+            try {
+                const r = await browser.evaluate(args.js || '');
+                log && log.event('browser_eval', (args.js || '').slice(0, 60), { ok: true });
+                return { ok: true, text_for_model: JSON.stringify({ ok: true, value: r }) };
+            } catch (e) {
+                return { ok: false, text_for_model: JSON.stringify({ ok: false, error: e.message }) };
+            }
+        }
+        case 'browser_scroll': {
+            try {
+                const r = await browser.scroll(args.dy || 400);
+                log && log.event('browser_scroll', `${args.dy}`, r);
+                return { ok: true, text_for_model: JSON.stringify(r) };
+            } catch (e) {
+                return { ok: false, text_for_model: JSON.stringify({ ok: false, error: e.message }) };
+            }
+        }
+        case 'browser_url': {
+            try {
+                const u = await browser.currentUrl();
+                return { ok: true, text_for_model: JSON.stringify({ ok: true, url: u }) };
+            } catch (e) {
+                return { ok: false, text_for_model: JSON.stringify({ ok: false, error: e.message }) };
+            }
+        }
+        case 'finish': {
+            log && log.event('finish', args.summary, { ok: true });
+            return { ok: true, text_for_model: JSON.stringify({ ok: true, summary: args.summary }), finish: true };
+        }
+        default:
+            return { ok: false, text_for_model: JSON.stringify({ ok: false, error: `ferramenta desconhecida: ${name}` }) };
+    }
+}
+
+module.exports = {
+    readFile, writeFile, listDir, runShellStream, runShellSync,
+    openInBrowser, openInNewTerminal, findChrome,
+    readFileSafe, writeFileSafe,
+    extractCodeBlocks, executeTool, fmtBytes, safePath,
+    MAX_FILE_BYTES,
+};