liberty-code-cli 1.0.0 → 2.0.0

package/src/tools/fs-tools.js

@@ -0,0 +1,242 @@
+'use strict';
+/**
+ * Ferramentas de arquivo. Comparado à v1 (list_directory, read_file,
+ * write_file só), o que muda:
+ *
+ *  - list_directory: agora respeita .gitignore de verdade (ignoreEngine),
+ *    aceita recursive+max_depth, e tem um teto de entradas pra não afogar o
+ *    contexto num repositório grande.
+ *  - read_file: arquivo grande não é mais um "não dá" seco — aceita
+ *    offset/limit (linha inicial/quantidade) igual ao Read do Claude Code,
+ *    então o modelo consegue pedir só o trecho que interessa.
+ *  - write_file: continua criando/sobrescrevendo o arquivo INTEIRO, mas
+ *    passa pela camada de permissão (permissions.js) em vez de um y/N fixo.
+ *  - edit_file (NOVA): troca old_string → new_string com casamento exato,
+ *    tipo find&replace cirúrgico — pra mudanças pequenas isso é mais seguro
+ *    e mais barato que reescrever o arquivo inteiro (menos chance do modelo
+ *    "esquecer" um trecho no meio ao reescrever tudo).
+ *  - glob_files (NOVA): encontra arquivos por padrão (**\/*.test.js etc).
+ *  - grep_search (NOVA): busca por regex dentro do conteúdo dos arquivos.
+ *
+ * safeResolve ganhou um teste de prefixo mais rigoroso: a versão original
+ * comparava com resolved.startsWith(cwd), que TEM UM BUG DE SEGURANÇA sutil
+ * — se o projeto for "/home/user/foo", o caminho "/home/user/foobar/x"
+ * passava no startsWith() mesmo sendo um diretório IRMÃO, não um filho. Corrigido
+ * exigindo o separador de caminho depois do prefixo.
+ */
+const fs = require('fs');
+const path = require('path');
+const { MAX_FILE_READ_BYTES } = require('../constants');
+const { paint, renderEditPreview } = require('../ui');
+
+function safeResolve(cwd, relPath) {
+  const base = path.resolve(cwd);
+  const resolved = path.resolve(base, relPath || '.');
+  if (resolved !== base && !resolved.startsWith(base + path.sep)) {
+    throw new Error('Caminho fora do diretório do projeto não é permitido.');
+  }
+  return resolved;
+}
+
+function isProbablyBinary(buf) {
+  const len = Math.min(buf.length, 8000);
+  for (let i = 0; i < len; i++) if (buf[i] === 0) return true;
+  return false;
+}
+
+// ── list_directory ──────────────────────────────────────────────────────
+function toolListDirectory(args, ctx) {
+  const dir = safeResolve(ctx.cwd, args.path || '.');
+  const recursive = !!args.recursive;
+  const maxDepth = Number.isFinite(args.max_depth) ? args.max_depth : (recursive ? 4 : 1);
+  const MAX_ENTRIES = 400;
+  const out = [];
+
+  function walk(current, depth) {
+    if (out.length >= MAX_ENTRIES || depth > maxDepth) return;
+    let entries;
+    try { entries = fs.readdirSync(current, { withFileTypes: true }); } catch { return; }
+    entries.sort((a, b) => a.name.localeCompare(b.name));
+    for (const e of entries) {
+      if (out.length >= MAX_ENTRIES) { out.push('… (limite de entradas atingido, refine o path)'); return; }
+      const full = path.join(current, e.name);
+      const rel = path.relative(ctx.cwd, full);
+      if (ctx.ignoreEngine.isIgnored(rel)) continue;
+      out.push(`${'  '.repeat(depth - 1)}${rel}${e.isDirectory() ? '/' : ''}`);
+      if (e.isDirectory() && recursive) walk(full, depth + 1);
+    }
+  }
+  walk(dir, 1);
+  return out.join('\n') || '(diretório vazio ou tudo ignorado por .gitignore)';
+}
+
+// ── read_file ────────────────────────────────────────────────────────────
+function toolReadFile(args, ctx) {
+  const filePath = safeResolve(ctx.cwd, args.path);
+  const stat = fs.statSync(filePath);
+  if (stat.isDirectory()) throw new Error('Esse caminho é um diretório, use list_directory.');
+
+  const hasRange = Number.isFinite(args.offset) || Number.isFinite(args.limit);
+  if (stat.size > MAX_FILE_READ_BYTES && !hasRange) {
+    return `[Arquivo grande: ${(stat.size / 1024).toFixed(0)}KB, acima do limite de ${MAX_FILE_READ_BYTES / 1024}KB por leitura. ` +
+      `Use offset/limit pra ler em partes, ex: {"path":"${args.path}","offset":0,"limit":200}.]`;
+  }
+  const content = fs.readFileSync(filePath, 'utf8');
+  if (!hasRange) return content;
+
+  const lines = content.split('\n');
+  const offset = Math.max(0, args.offset || 0);
+  const limit = Number.isFinite(args.limit) ? args.limit : 500;
+  const slice = lines.slice(offset, offset + limit);
+  const numbered = slice.map((l, i) => `${offset + i + 1}\t${l}`).join('\n');
+  const footer = offset + limit < lines.length ? `\n… (${lines.length - offset - limit} linhas restantes — aumente offset pra continuar)` : '';
+  return numbered + footer;
+}
+
+// ── write_file ───────────────────────────────────────────────────────────
+async function toolWriteFile(args, ctx) {
+  const filePath = safeResolve(ctx.cwd, args.path);
+  const rel = path.relative(ctx.cwd, filePath);
+  const exists = fs.existsSync(filePath);
+  console.log(paint('yellow', `\n${exists ? '✏️  Sobrescrever' : '📄 Criar'} arquivo: ${rel}`));
+  console.log(paint('gray', `   (${(args.content || '').length} caracteres)`));
+
+  const hookRes = ctx.hooks.runHooks('PreToolUse', { toolName: 'write_file', args, filePath: rel, cwd: ctx.cwd }, ctx.cwd);
+  hookRes.infoLines.forEach(l => console.log(l));
+  if (hookRes.blocked) return `[Bloqueado por hook: ${hookRes.reason}]`;
+
+  const ok = await ctx.permissions.check('write', rel, '   Permitir?', ctx.rl);
+  if (!ok) return '[Usuário negou a escrita deste arquivo.]';
+
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, args.content, 'utf8');
+  ctx.hooks.runHooks('PostToolUse', { toolName: 'write_file', args: { path: args.path }, filePath: rel, cwd: ctx.cwd }, ctx.cwd)
+    .infoLines.forEach(l => console.log(l));
+  return `Arquivo salvo com sucesso: ${rel}`;
+}
+
+// ── edit_file (NOVA) ─────────────────────────────────────────────────────
+async function toolEditFile(args, ctx) {
+  const { path: relPath, old_string, new_string, replace_all } = args;
+  if (typeof old_string !== 'string' || !old_string.length) throw new Error('old_string é obrigatório e não pode ser vazio.');
+  const filePath = safeResolve(ctx.cwd, relPath);
+  const rel = path.relative(ctx.cwd, filePath);
+  const current = fs.readFileSync(filePath, 'utf8');
+
+  const occurrences = current.split(old_string).length - 1;
+  if (occurrences === 0) {
+    return `[old_string não encontrado em ${rel}. Confira se o texto é EXATAMENTE igual (espaços/indentação incluídos) ao que está no arquivo — releia o arquivo se necessário.]`;
+  }
+  if (occurrences > 1 && !replace_all) {
+    return `[old_string aparece ${occurrences} vezes em ${rel} — inclua mais contexto ao redor pra torná-lo único, ou passe replace_all:true se a intenção é trocar todas.]`;
+  }
+
+  const updated = replace_all ? current.split(old_string).join(new_string) : current.replace(old_string, new_string);
+
+  console.log(paint('yellow', `\n✏️  Editar arquivo: ${rel}`) + paint('gray', replace_all ? `  (${occurrences} ocorrências)` : ''));
+  console.log(renderEditPreview(old_string, new_string));
+
+  const hookRes = ctx.hooks.runHooks('PreToolUse', { toolName: 'edit_file', args: { path: relPath }, filePath: rel, cwd: ctx.cwd }, ctx.cwd);
+  hookRes.infoLines.forEach(l => console.log(l));
+  if (hookRes.blocked) return `[Bloqueado por hook: ${hookRes.reason}]`;
+
+  const ok = await ctx.permissions.check('edit', rel, '   Permitir?', ctx.rl);
+  if (!ok) return '[Usuário negou esta edição.]';
+
+  fs.writeFileSync(filePath, updated, 'utf8');
+  ctx.hooks.runHooks('PostToolUse', { toolName: 'edit_file', args: { path: relPath }, filePath: rel, cwd: ctx.cwd }, ctx.cwd)
+    .infoLines.forEach(l => console.log(l));
+  return `Edição aplicada com sucesso em ${rel} (${occurrences} ocorrência${occurrences > 1 ? 's' : ''} trocada${occurrences > 1 ? 's' : ''}).`;
+}
+
+// ── glob_files (NOVA) ────────────────────────────────────────────────────
+function globToRegExp(pattern) {
+  let re = '';
+  for (let i = 0; i < pattern.length; i++) {
+    const ch = pattern[i];
+    if (ch === '*' && pattern[i + 1] === '*') {
+      i++;
+      if (pattern[i + 1] === '/') { re += '(?:.*/)?'; i++; }
+      else re += '.*';
+    } else if (ch === '*') re += '[^/]*';
+    else if (ch === '?') re += '[^/]';
+    else if ('.+^$()[]{}|\\'.includes(ch)) re += '\\' + ch;
+    else re += ch;
+  }
+  return new RegExp('^' + re + '$');
+}
+
+function toolGlobFiles(args, ctx) {
+  if (!args.pattern) throw new Error('pattern é obrigatório, ex: "**/*.test.js"');
+  const startDir = safeResolve(ctx.cwd, args.path || '.');
+  const regex = globToRegExp(args.pattern);
+  const MAX_RESULTS = 200;
+  const results = [];
+
+  function walk(dir) {
+    if (results.length >= MAX_RESULTS) return;
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      const full = path.join(dir, e.name);
+      const rel = path.relative(ctx.cwd, full);
+      if (ctx.ignoreEngine.isIgnored(rel)) continue;
+      if (e.isDirectory()) { walk(full); continue; }
+      if (regex.test(rel.split(path.sep).join('/'))) results.push(rel);
+      if (results.length >= MAX_RESULTS) return;
+    }
+  }
+  walk(startDir);
+  if (!results.length) return `Nenhum arquivo encontrado para o padrão "${args.pattern}".`;
+  return results.join('\n') + (results.length >= MAX_RESULTS ? '\n… (limite de resultados atingido, refine o padrão)' : '');
+}
+
+// ── grep_search (NOVA) ───────────────────────────────────────────────────
+function toolGrepSearch(args, ctx) {
+  if (!args.pattern) throw new Error('pattern é obrigatório (regex).');
+  const startDir = safeResolve(ctx.cwd, args.path || '.');
+  let regex;
+  try { regex = new RegExp(args.pattern, args.case_insensitive ? 'i' : ''); }
+  catch (e) { throw new Error(`Regex inválida: ${e.message}`); }
+  const globRegex = args.glob ? globToRegExp(args.glob) : null;
+  const MAX_MATCHES = 200, MAX_FILES_SCANNED = 800, MAX_FILE_SIZE = 1.5 * 1024 * 1024;
+
+  const matches = [];
+  let filesScanned = 0;
+
+  function walk(dir) {
+    if (matches.length >= MAX_MATCHES || filesScanned >= MAX_FILES_SCANNED) return;
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      if (matches.length >= MAX_MATCHES || filesScanned >= MAX_FILES_SCANNED) return;
+      const full = path.join(dir, e.name);
+      const rel = path.relative(ctx.cwd, full);
+      if (ctx.ignoreEngine.isIgnored(rel)) continue;
+      if (e.isDirectory()) { walk(full); continue; }
+      const relSlash = rel.split(path.sep).join('/');
+      if (globRegex && !globRegex.test(relSlash)) continue;
+      let stat;
+      try { stat = fs.statSync(full); } catch { continue; }
+      if (stat.size > MAX_FILE_SIZE) continue;
+      filesScanned++;
+      let buf;
+      try { buf = fs.readFileSync(full); } catch { continue; }
+      if (isProbablyBinary(buf)) continue;
+      const lines = buf.toString('utf8').split('\n');
+      for (let i = 0; i < lines.length; i++) {
+        if (regex.test(lines[i])) {
+          matches.push(`${rel}:${i + 1}: ${lines[i].trim().slice(0, 200)}`);
+          if (matches.length >= MAX_MATCHES) break;
+        }
+      }
+    }
+  }
+  walk(startDir);
+  if (!matches.length) return `Nenhuma ocorrência de "${args.pattern}" encontrada (${filesScanned} arquivos verificados).`;
+  return matches.join('\n') + (matches.length >= MAX_MATCHES ? '\n… (limite de resultados atingido, refine a busca)' : '');
+}
+
+module.exports = {
+  safeResolve, toolListDirectory, toolReadFile, toolWriteFile, toolEditFile, toolGlobFiles, toolGrepSearch,
+};

package/src/tools/index.js

@@ -0,0 +1,192 @@
+'use strict';
+/**
+ * Registro central de ferramentas.
+ *
+ * Duas responsabilidades que ANTES estavam espalhadas (schema vivia no
+ * server.js/services.js, dispatch vivia no bin/liberty.js, sem ligação
+ * explícita entre os dois — fácil os dois lados desalinharem):
+ *
+ *   1. buildToolSchemas(mode, extra) — decide QUAIS ferramentas o modelo
+ *      recebe, de acordo com o modo atual. Em 'plan', as ferramentas de
+ *      escrita simplesmente não entram na lista — o modelo não só "não
+ *      deveria usar", ele NÃO TEM a ferramenta disponível pra chamar.
+ *   2. executeLocalTool(call, ctx) — dispatch único de execução, incluindo
+ *      ferramentas nativas, a ferramenta task (subagente) e ferramentas MCP
+ *      (reconhecidas pelo prefixo mcp__).
+ *
+ * O array de tools construído aqui é enviado pro servidor a cada requisição
+ * (ver api.js) — o server.js precisa aceitar esse override (ver mudança em
+ * server.js) em vez de sempre usar o buildLibertyCodeTools() fixo dele.
+ */
+const { TOOL_RESULT_CHAR_CAP, PERMISSION_MODES } = require('../constants');
+const { safeResolve, toolListDirectory, toolReadFile, toolWriteFile, toolEditFile, toolGlobFiles, toolGrepSearch } = require('./fs-tools');
+const { toolRunCommand } = require('./exec-tools');
+const { toolUpdateTodos } = require('./todo-tool');
+
+const READ_ONLY_TOOL_NAMES = ['list_directory', 'read_file', 'glob_files', 'grep_search', 'update_todos'];
+const WRITE_TOOL_NAMES = ['write_file', 'edit_file', 'run_command'];
+
+const SCHEMAS = {
+  list_directory: {
+    type: 'function',
+    function: {
+      name: 'list_directory',
+      description: 'Lista arquivos e pastas de um diretório do projeto (respeita .gitignore). Use recursive:true pra ver a árvore inteira de uma vez.',
+      parameters: { type: 'object', properties: {
+        path: { type: 'string', description: 'Caminho relativo ao projeto. Padrão: "."' },
+        recursive: { type: 'boolean', description: 'Descer em subpastas. Padrão: false.' },
+        max_depth: { type: 'number', description: 'Profundidade máxima quando recursive:true. Padrão: 4.' },
+      } },
+    },
+  },
+  read_file: {
+    type: 'function',
+    function: {
+      name: 'read_file',
+      description: 'Lê o conteúdo de um arquivo do projeto. Para arquivos grandes, use offset (linha inicial, 0-based) e limit (quantidade de linhas).',
+      parameters: { type: 'object', properties: {
+        path: { type: 'string', description: 'Caminho relativo ao projeto.' },
+        offset: { type: 'number', description: 'Linha inicial (0-based). Opcional.' },
+        limit: { type: 'number', description: 'Quantidade de linhas a partir de offset. Opcional, padrão 500.' },
+      }, required: ['path'] },
+    },
+  },
+  write_file: {
+    type: 'function',
+    function: {
+      name: 'write_file',
+      description: 'Cria um arquivo novo OU sobrescreve um arquivo inteiro com novo conteúdo. Para mudanças pequenas em arquivo existente, prefira edit_file — é mais seguro e mais barato.',
+      parameters: { type: 'object', properties: {
+        path: { type: 'string', description: 'Caminho relativo ao projeto.' },
+        content: { type: 'string', description: 'Conteúdo COMPLETO do arquivo.' },
+      }, required: ['path', 'content'] },
+    },
+  },
+  edit_file: {
+    type: 'function',
+    function: {
+      name: 'edit_file',
+      description: 'Troca um trecho exato (old_string) por outro (new_string) num arquivo existente. old_string deve casar EXATAMENTE (incluindo espaços/indentação) e ser único no arquivo — inclua linhas de contexto ao redor se necessário. Use replace_all:true pra trocar todas as ocorrências de uma vez.',
+      parameters: { type: 'object', properties: {
+        path: { type: 'string', description: 'Caminho relativo ao projeto.' },
+        old_string: { type: 'string', description: 'Trecho exato a ser substituído.' },
+        new_string: { type: 'string', description: 'Novo trecho.' },
+        replace_all: { type: 'boolean', description: 'Trocar todas as ocorrências em vez de exigir que seja única. Padrão: false.' },
+      }, required: ['path', 'old_string', 'new_string'] },
+    },
+  },
+  glob_files: {
+    type: 'function',
+    function: {
+      name: 'glob_files',
+      description: 'Encontra arquivos por padrão glob, ex: "**/*.test.js", "src/**/*.tsx". Suporta * (dentro de uma pasta), ** (várias pastas) e ?.',
+      parameters: { type: 'object', properties: {
+        pattern: { type: 'string', description: 'Padrão glob.' },
+        path: { type: 'string', description: 'Pasta base pra busca. Padrão: raiz do projeto.' },
+      }, required: ['pattern'] },
+    },
+  },
+  grep_search: {
+    type: 'function',
+    function: {
+      name: 'grep_search',
+      description: 'Busca um padrão (regex) dentro do conteúdo dos arquivos do projeto. Devolve arquivo:linha e o trecho que casou.',
+      parameters: { type: 'object', properties: {
+        pattern: { type: 'string', description: 'Expressão regular (sintaxe JavaScript).' },
+        path: { type: 'string', description: 'Pasta base pra busca. Padrão: raiz do projeto.' },
+        glob: { type: 'string', description: 'Filtrar arquivos por padrão glob antes de buscar, ex: "*.js".' },
+        case_insensitive: { type: 'boolean' },
+      }, required: ['pattern'] },
+    },
+  },
+  run_command: {
+    type: 'function',
+    function: {
+      name: 'run_command',
+      description: 'Executa um comando de shell no diretório do projeto. Use run_in_background:true para comandos de longa duração (servidores, watchers) — nesse caso a saída vai pra um arquivo de log em vez de bloquear.',
+      parameters: { type: 'object', properties: {
+        command: { type: 'string', description: 'Comando de shell completo.' },
+        run_in_background: { type: 'boolean', description: 'Rodar em background e devolver controle imediatamente. Padrão: false.' },
+      }, required: ['command'] },
+    },
+  },
+  update_todos: {
+    type: 'function',
+    function: {
+      name: 'update_todos',
+      description: 'Cria/atualiza a lista de tarefas da sessão. Use em tarefas com 3+ passos pra planejar antes de agir e manter o progresso visível. Marque um item como in_progress só quando estiver de fato trabalhando nele (um por vez).',
+      parameters: { type: 'object', properties: {
+        todos: {
+          type: 'array',
+          items: { type: 'object', properties: {
+            content: { type: 'string' },
+            status: { type: 'string', enum: ['pending', 'in_progress', 'completed'] },
+          }, required: ['content', 'status'] },
+        },
+      }, required: ['todos'] },
+    },
+  },
+  task: {
+    type: 'function',
+    function: {
+      name: 'task',
+      description: 'Delega uma sub-tarefa AUTOCONTIDA a um subagente com contexto próprio (não vê o histórico desta conversa, só o prompt que você der). Use pra investigações que gerariam muito ruído no contexto principal (ex: "procure em todo o repo onde X é usado e resuma"). O subagente devolve só um resumo final, não os passos intermediários.',
+      parameters: { type: 'object', properties: {
+        description: { type: 'string', description: 'Resumo curto (3-6 palavras) da tarefa, pra exibir ao usuário.' },
+        prompt: { type: 'string', description: 'Instrução completa e autocontida pro subagente — ele não tem mais contexto além disso.' },
+        subagent_type: { type: 'string', enum: ['general', 'read-only-researcher'], description: '"read-only-researcher" só pode explorar/ler (mais seguro, mais rápido de aprovar); "general" também pode editar arquivos e rodar comandos.' },
+      }, required: ['description', 'prompt'] },
+    },
+  },
+};
+
+function buildToolSchemas({ mode, includeTask = false, mcpTools = [] } = {}) {
+  let names;
+  if (mode === PERMISSION_MODES.PLAN) names = [...READ_ONLY_TOOL_NAMES];
+  else names = [...READ_ONLY_TOOL_NAMES, ...WRITE_TOOL_NAMES];
+  const schemas = names.map(n => SCHEMAS[n]);
+  if (includeTask && mode !== PERMISSION_MODES.PLAN) schemas.push(SCHEMAS.task);
+  return [...schemas, ...mcpTools];
+}
+
+/** Ferramentas do subagente: nunca inclui "task" (profundidade máx. 1) e read-only restringe a leitura. */
+function buildSubagentToolSchemas(subagentType, mcpTools = []) {
+  const names = subagentType === 'read-only-researcher'
+    ? READ_ONLY_TOOL_NAMES
+    : [...READ_ONLY_TOOL_NAMES, ...WRITE_TOOL_NAMES];
+  return [...names.map(n => SCHEMAS[n]), ...mcpTools];
+}
+
+async function executeLocalTool(call, ctx) {
+  try {
+    let result;
+    if (call.name.startsWith('mcp__')) {
+      if (!ctx.mcpManager) return `[MCP não está configurado nesta sessão.]`;
+      result = await ctx.mcpManager.callTool(call.name, call.arguments || {});
+    } else {
+      switch (call.name) {
+        case 'list_directory': result = toolListDirectory(call.arguments || {}, ctx); break;
+        case 'read_file':      result = toolReadFile(call.arguments || {}, ctx); break;
+        case 'write_file':     result = await toolWriteFile(call.arguments || {}, ctx); break;
+        case 'edit_file':      result = await toolEditFile(call.arguments || {}, ctx); break;
+        case 'glob_files':     result = toolGlobFiles(call.arguments || {}, ctx); break;
+        case 'grep_search':    result = toolGrepSearch(call.arguments || {}, ctx); break;
+        case 'run_command':    result = await toolRunCommand(call.arguments || {}, ctx); break;
+        case 'update_todos':   result = toolUpdateTodos(call.arguments || {}, ctx); break;
+        case 'task':
+          if (!ctx.allowSubagents) { result = '[task indisponível: subagentes não podem lançar outros subagentes.]'; break; }
+          result = await ctx.runSubagent(call.arguments || {}, ctx);
+          break;
+        default: result = `Ferramenta desconhecida: ${call.name}`;
+      }
+    }
+    const str = String(result ?? '');
+    return str.length > TOOL_RESULT_CHAR_CAP
+      ? str.slice(0, TOOL_RESULT_CHAR_CAP) + `\n… (resultado cortado em ${TOOL_RESULT_CHAR_CAP} caracteres)`
+      : str;
+  } catch (e) {
+    return `Erro ao executar ${call.name}: ${e.message}`;
+  }
+}
+
+module.exports = { buildToolSchemas, buildSubagentToolSchemas, executeLocalTool, safeResolve, SCHEMAS };

package/src/tools/todo-tool.js

@@ -0,0 +1,38 @@
+'use strict';
+/**
+ * update_todos — equivalente ao TodoWrite do Claude Code.
+ *
+ * Não mexe no disco, é só estado da sessão (por isso entra na sessão salva
+ * em session.js, pra sobreviver a um /resume). Serve dois propósitos: (1)
+ * força o modelo a quebrar tarefas grandes em passos explícitos em vez de
+ * tentar tudo de uma vez, (2) dá pro usuário visibilidade do progresso sem
+ * precisar ler cada mensagem.
+ */
+const { paint } = require('../ui');
+
+const ICONS = { pending: '☐', in_progress: '◐', completed: '☑' };
+
+function toolUpdateTodos(args, ctx) {
+  const todos = Array.isArray(args.todos) ? args.todos : [];
+  for (const t of todos) {
+    if (!t.content || !['pending', 'in_progress', 'completed'].includes(t.status)) {
+      throw new Error('Cada todo precisa de {content, status: pending|in_progress|completed}.');
+    }
+  }
+  ctx.todos.length = 0;
+  ctx.todos.push(...todos);
+  renderTodos(ctx.todos);
+  const done = todos.filter(t => t.status === 'completed').length;
+  return `Lista de tarefas atualizada (${done}/${todos.length} concluídas).`;
+}
+
+function renderTodos(todos) {
+  if (!todos.length) return;
+  console.log(paint('cyan', '\n📋 Tarefas:'));
+  todos.forEach(t => {
+    const color = t.status === 'completed' ? 'green' : t.status === 'in_progress' ? 'yellow' : 'gray';
+    console.log(paint(color, `   ${ICONS[t.status]} ${t.content}`));
+  });
+}
+
+module.exports = { toolUpdateTodos, renderTodos };

package/src/ui.js

@@ -0,0 +1,71 @@
+'use strict';
+/**
+ * UI de terminal — sem dependências externas, de propósito (mesma filosofia
+ * do liberty.js original: um CLI de agente não precisa de chalk/ora só pra
+ * pintar texto e mostrar "carregando").
+ */
+
+const c = {
+  reset: '\x1b[0m', bold: '\x1b[1m', dim: '\x1b[2m', italic: '\x1b[3m',
+  red: '\x1b[31m', green: '\x1b[32m', yellow: '\x1b[33m',
+  blue: '\x1b[34m', magenta: '\x1b[35m', cyan: '\x1b[36m', gray: '\x1b[90m',
+  bgRed: '\x1b[41m', bgGreen: '\x1b[42m',
+};
+const paint = (color, text) => `${c[color]}${text}${c.reset}`;
+
+// ── Spinner simples (sem setInterval "vazando" — sempre limpo no fim) ──────
+function spinner(label) {
+  const frames = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+  let i = 0;
+  const isTTY = process.stdout.isTTY;
+  if (!isTTY) {
+    process.stdout.write(paint('gray', `${label}...\n`));
+    return { stop() {} };
+  }
+  const timer = setInterval(() => {
+    process.stdout.write(`\r${paint('cyan', frames[i = (i + 1) % frames.length])} ${paint('gray', label)}   `);
+  }, 80);
+  return {
+    stop(clearLine = true) {
+      clearInterval(timer);
+      if (clearLine) process.stdout.write(`\r${' '.repeat(label.length + 4)}\r`);
+    },
+  };
+}
+
+// ── Diff colorido simples (linha a linha, sem lib de diff — old vs new) ────
+// Não é um diff mínimo tipo Myers; é propositalmente simples: mostra o
+// old_string todo em vermelho e o new_string todo em verde, prefixados com
+// - / +. Suficiente pro caso de uso (confirmar uma edição antes de aplicar)
+// sem puxar uma dependência de diff só pra isso.
+function renderEditPreview(oldStr, newStr, contextLabel) {
+  const lines = [];
+  if (contextLabel) lines.push(paint('gray', contextLabel));
+  const oldLines = oldStr.split('\n');
+  const newLines = newStr.split('\n');
+  const MAX_LINES = 40;
+  oldLines.slice(0, MAX_LINES).forEach(l => lines.push(paint('red', `  - ${l}`)));
+  if (oldLines.length > MAX_LINES) lines.push(paint('gray', `  … (+${oldLines.length - MAX_LINES} linhas removidas)`));
+  newLines.slice(0, MAX_LINES).forEach(l => lines.push(paint('green', `  + ${l}`)));
+  if (newLines.length > MAX_LINES) lines.push(paint('gray', `  … (+${newLines.length - MAX_LINES} linhas adicionadas)`));
+  return lines.join('\n');
+}
+
+function truncateForDisplay(str, max = 240) {
+  const s = String(str ?? '');
+  return s.length > max ? s.slice(0, max) + paint('gray', `… (+${s.length - max} chars)`) : s;
+}
+
+function banner(version, cwd, extras) {
+  const lines = [];
+  lines.push(paint('bold', '\n🦅 Liberty Code') + paint('gray', ` v${version}`));
+  lines.push(paint('gray', `   ${cwd}`));
+  (extras || []).forEach(e => lines.push(paint('gray', `   ${e}`)));
+  return lines.join('\n');
+}
+
+function toolLine(icon, label) {
+  return paint('yellow', `\n${icon} ${label}`);
+}
+
+module.exports = { c, paint, spinner, renderEditPreview, truncateForDisplay, banner, toolLine };