kafox-cli 0.2.3 → 0.6.0

package/README.md

@@ -12,7 +12,7 @@ npm install -g kafox-cli
 O comando instalado e `kafox`. Alternativa sem npm:
 
 ```bash
-npm install -g https://kafox.pypag.com/static/downloads/kafox-cli-0.2.3.tgz
+npm install -g https://kafox.pypag.com/static/downloads/kafox-cli-0.3.0.tgz
 ```
 
 Requisito: Node.js 22.5+.
@@ -32,6 +32,7 @@ navegador, entre na sua conta e clique em **Autorizar**. A sessao fica em
 | Comando | O que faz |
 | --- | --- |
 | `kafox` | abre a interface de tela cheia |
+| `kafox --allow-all` | abre ja aprovando tudo (mesmo que `KAFOX_ALLOW_ALL=1`) |
 | `kafox login` / `logout` / `whoami` | sessao da conta |
 | `kafox models` | lista modelos e precos por 1M de tokens |
 | `kafox pricing` | pacotes de recarga |
@@ -43,16 +44,93 @@ navegador, entre na sua conta e clique em **Autorizar**. A sessao fica em
 | `kafox background [url]` | imagem de fundo do terminal |
 | `kafox compact` / `clear` | compacta / limpa o contexto do REPL |
 
-Na interface: digite `/` para o menu (↑/↓ navega, Tab completa, Enter executa
-), `/model` abre o seletor de modelo (↑/↓ + Enter). Demais comandos: `/help`,
-`/models`, `/balance`, `/pricing`, `/key`, `/login`, `/logout`, `/whoami`,
-`/theme`, `/background`, `/clear`, `/compact`, `/status`, `/exit`.
+Na interface: digite `/` para o menu (↑/↓ navega, Tab completa, Enter executa),
+`/model` abre o seletor de modelo e `/theme` o de tema (↑/↓, clique do mouse,
+Enter aplica, Esc cancela). A resposta chega em streaming, com bloco `Thinking`
+quando o modelo manda o raciocinio. PgUp/PgDn ou a roda do mouse rolam a conversa;
+Ctrl+Y copia a ultima resposta e F2 solta o mouse para selecionar texto.
+
+Nao precisa esperar a resposta para escrever de novo: **Enter enfileira** a
+mensagem (a fila aparece acima do input e roda em ordem assim que a atual
+termina). Para parar a IA na hora, **Esc duas vezes** — o primeiro Esc so avisa,
+o segundo interrompe o passo em andamento e guarda na conversa o que ja tinha
+chegado.
+
+Demais comandos: `/help`, `/models`, `/balance`, `/pricing`, `/key`, `/login`,
+`/logout`, `/whoami`, `/mcp`, `/allow`, `/theme`, `/background`, `/clear`,
+`/compact`, `/status`, `/exit`.
+
+O `/theme` traz 29 temas (default, dark, light, brutalist, neon, paper,
+dracula, nord, gruvbox, monokai, tokyo-night, catppuccin, solarized, midnight,
+ocean, forest, sunset, plum, synthwave, cyberpunk, amoled, matrix, terminal,
+solarized-light, rose, mint, sepia, ice e high-contrast).
+
+## Ferramentas do agente
+
+Com o saldo em dia a TUI deixa o modelo ler e mexer no projeto. Cada chamada
+aparece como um card na conversa, com o diff do que foi editado.
+
+| Ferramenta | O que faz |
+| --- | --- |
+| `read_file` | le um arquivo (com `offset`/`limit`) |
+| `list_dir` | lista uma pasta |
+| `write_file` | cria ou reescreve um arquivo |
+| `edit_file` | troca um trecho exato do arquivo |
+| `run_command` | roda um comando no diretorio de trabalho |
+
+`run_command` sai como uma janela de terminal: o comando em `$ ...`, a saida
+dentro da janela (erro em vermelho) e o rodape com `exit` e o tempo; enquanto
+roda, aparece o spinner com o tempo decorrido. Ferramentas de MCP usam a mesma
+janela, com os argumentos e o resultado.
+
+Quem escreve, edita ou executa pede aprovacao num modal com tres opcoes:
+**Permitir uma vez**, **Permitir sempre** (roda tudo nesta sessao, sem perguntar
+de novo — inclusive as proximas ferramentas do mesmo passo) e **Negar**. Navegue
+com ↑/↓ (ou clique) e confirme com Enter; `a` libera sempre, `y` uma vez,
+`n`/Esc nega. Todo caminho fica travado dentro do diretorio de trabalho.
+
+Para ja abrir liberado, use `kafox --allow-all` (ou `KAFOX_ALLOW_ALL=1`), e dentro
+da sessao `/allow` liga e `/allow off` volta a perguntar. Com o modo ligado a
+barra lateral mostra **rodando tudo**.
+
+## Servidores MCP
+
+Ferramentas de servidores MCP entram no mesmo loop, com o prefixo
+`mcp__servidor__ferramenta`. Configure em `~/.kafox/mcp.json` (ou `./mcp.json` do
+projeto, que vence):
+
+```json
+{
+  "mcp": {
+    "playwright": {
+      "type": "local",
+      "command": ["npx", "-y", "@playwright/mcp@latest"]
+    },
+    "remoto": {
+      "type": "remote",
+      "url": "https://exemplo.com/mcp",
+      "headers": { "authorization": "Bearer ..." }
+    }
+  }
+}
+```
+
+O servidor local roda por stdio e o remoto fala HTTP/SSE. Use `enabled: false`
+para desligar um servidor. Na TUI a barra lateral mostra o status de cada um (e o
+motivo do erro quando falha) e `/mcp` lista tudo; `/mcp reload` reconecta.
 
 ## Configuracao
 
 - `KAFOX_API_URL` ou `~/.kafox/config.json` (`api_url`) troca a API.
 - `~/.kafox/config.json` guarda `model`, `theme`, `background` e a API key criada
   automaticamente no primeiro `ask`.
+- `~/.kafox/mcp.json` guarda os servidores MCP.
 
 A CLI so responde se a conta tiver saldo; sem credito ela avisa e nao chama o
 gateway.
+
+## Escopo
+
+O kafox autentica na conta, lista modelos, mostra saldo, conversa pelo gateway e
+roda tarefas no projeto: le e edita arquivos, executa comandos (sempre com
+aprovacao) e chama servidores MCP configurados.

package/bin/kafox.js

@@ -12,6 +12,10 @@ const program = new Command();
 program
   .name("kafox")
   .description("Kafox CLI in opencode style: terminal UI, account login, models, balance, themes")
+  .option(
+    "-y, --allow-all",
+    "abre ja aprovando tudo: ferramentas de arquivo, comando e MCP sem pedir aprovacao"
+  )
   .version(version);
 
 program.command("login").description("Login with your Kafox account (device code SSO)").action(login);
@@ -28,5 +32,5 @@ program.command("compact").description("Compact the current conversation context
 program.command("clear").description("Clear the conversation context").action(clearContext);
 program.command("status").description("Show account, balance and gateway status").action(showStatus);
 
-program.action(runREPL);
+program.action((options) => runREPL({ allowAll: Boolean(options.allowAll) }));
 program.parse();

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "kafox-cli",
-  "version": "0.2.3",
-  "description": "Kafox CLI in opencode style: full-screen terminal UI, device login, models, balance, themes",
+  "version": "0.6.0",
+  "description": "Kafox CLI: TUI com streaming, thinking, edit com diff, agent tools (files/shell), MCP e temas",
   "bin": {
     "kafox": "bin/kafox.js"
   },
@@ -20,6 +20,7 @@
     "inquirer": "8.2.6"
   },
   "scripts": {
-    "test": "node --test \"test/*.test.js\""
+    "test": "node --test \"test/*.test.js\"",
+    "smoke": "node test/e2e/tui.js"
   }
 }

package/src/agent.js

@@ -0,0 +1,190 @@
+const { chat } = require("./gateway");
+const {
+  TOOL_SPECS,
+  APPROVAL_REQUIRED,
+  executeTool,
+  describeToolCall,
+  previewToolChange,
+  summarizeOutput,
+} = require("./tools");
+
+const MAX_STEPS = 10;
+
+function parseArgs(raw) {
+  if (!raw) return {};
+  try {
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === "object" ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+function systemPrompt(cwd, model) {
+  return [
+    "Voce e o kafox, uma CLI de terminal que conversa e executa tarefas no projeto do usuario.",
+    `Diretorio de trabalho: ${cwd}`,
+    `Modelo: ${model || "auto"}`,
+    "Ferramentas locais: read_file, list_dir, write_file, edit_file, run_command.",
+    "Para mudar um arquivo existente use edit_file (troca de trecho exato); write_file e para arquivo novo ou reescrita completa.",
+    "Ferramentas com nome mcp__<servidor>__<ferramenta> vem de servidores MCP conectados: use quando ajudarem.",
+    "Nunca invente conteudo de arquivo: leia antes de editar. Prefira caminhos relativos.",
+    "Quem escreve ou executa passa por aprovacao do usuario, entao explique em uma frase o que vai fazer.",
+    "Responda no idioma do usuario, de forma direta, com Markdown.",
+  ].join("\n");
+}
+
+/**
+ * Roda o loop: modelo -> tool calls -> resultados -> modelo, ate a resposta final.
+ * Ferramenta que escreve, edita, executa ou vem de MCP passa por `approve`
+ * (async, true/false), a menos que `autoApprove` esteja ligado ("rodar tudo").
+ */
+async function runAgent({
+  messages = [],
+  model,
+  cwd = process.cwd(),
+  approve,
+  autoApprove = false,
+  extraTools = [],
+  mcp = null,
+  signal,
+  maxSteps = MAX_STEPS,
+  onText,
+  onReasoning,
+  onToolStart,
+  onToolResult,
+} = {}) {
+  const conversation = messages.map((message) => ({ ...message }));
+  if (!conversation.length || conversation[0].role !== "system") {
+    conversation.unshift({ role: "system", content: systemPrompt(cwd, model) });
+  }
+
+  const tools = extraTools.length ? [...TOOL_SPECS, ...extraTools] : TOOL_SPECS;
+  // `autoApprove` pode ser um valor ou uma funcao: o "Permitir sempre" da TUI
+  // liga o modo no meio do loop, e o resto da execucao ja nao pergunta mais.
+  const autoAllowed = typeof autoApprove === "function" ? autoApprove : () => Boolean(autoApprove);
+  let last = { text: "", reasoning: "", ms: 0, usage: null };
+
+  for (let step = 0; step < maxSteps; step += 1) {
+    // Esc duas vezes na TUI aborta o signal: nao comeca outro passo.
+    if (signal?.aborted) {
+      return { ok: true, aborted: true, text: last.text, messages: conversation, steps: step };
+    }
+
+    const started = Date.now();
+    const result = await chat({
+      messages: conversation,
+      model,
+      tools,
+      signal,
+      onDelta: onText,
+      onReasoning,
+    });
+
+    if (!result.ok) {
+      return { ...result, aborted: result.code === "aborted", messages: conversation, text: last.text };
+    }
+
+    // Stream cortado no meio: guarda o que ja chegou e encerra o loop.
+    if (result.aborted) {
+      return {
+        ok: true,
+        aborted: true,
+        text: result.text || "",
+        reasoning: result.reasoning || "",
+        ms: result.ms,
+        messages: conversation,
+        steps: step + 1,
+      };
+    }
+
+    last = {
+      text: result.text,
+      reasoning: result.reasoning,
+      ms: result.ms,
+      usage: result.usage,
+      thoughtMs: Date.now() - started,
+    };
+    const assistant = { role: "assistant", content: result.text || "" };
+    if (result.toolCalls.length) assistant.tool_calls = result.toolCalls;
+    conversation.push(assistant);
+
+    if (!result.toolCalls.length) {
+      return {
+        ok: true,
+        ...last,
+        keyCreated: result.keyCreated,
+        messages: conversation,
+        steps: step + 1,
+      };
+    }
+
+    for (const call of result.toolCalls) {
+      const name = call?.function?.name || "";
+      const args = parseArgs(call?.function?.arguments);
+      const fromMcp = Boolean(mcp?.has?.(name));
+      const needsApproval = APPROVAL_REQUIRED.has(name) || fromMcp;
+
+      let change = null;
+      try {
+        change = previewToolChange(name, args, { cwd });
+      } catch {
+        change = null;
+      }
+
+      onToolStart?.({
+        name,
+        args,
+        label: describeToolCall(name, args),
+        change,
+        fromMcp,
+        needsApproval,
+      });
+
+      const gate = needsApproval && !autoAllowed();
+      let allowed = true;
+      if (gate) {
+        allowed = approve ? Boolean(await approve(name, args, { change, fromMcp })) : false;
+      }
+
+      const toolStarted = Date.now();
+      let output;
+      if (!allowed) {
+        output = "O usuario negou a execucao desta ferramenta. Peca instrucoes se precisar.";
+      } else {
+        try {
+          output = await executeTool(name, args, { cwd, mcp });
+        } catch (error) {
+          output = `Erro: ${error.message}`;
+        }
+      }
+
+      onToolResult?.({
+        name,
+        args,
+        output,
+        change,
+        ok: allowed && !String(output).startsWith("Erro:"),
+        skipped: !allowed,
+        fromMcp,
+        ms: Date.now() - toolStarted,
+        summary: summarizeOutput(output),
+      });
+
+      conversation.push({
+        role: "tool",
+        tool_call_id: call.id || `call_${step}`,
+        content: String(output),
+      });
+    }
+  }
+
+  return {
+    ok: false,
+    error: `Limite de ${maxSteps} passos do agente atingido. Tente dividir o pedido.`,
+    ...last,
+    messages: conversation,
+  };
+}
+
+module.exports = { runAgent, MAX_STEPS, systemPrompt };

package/src/cli.js

@@ -1,12 +1,16 @@
 const readline = require("readline");
+const os = require("os");
+const path = require("path");
 const inquirer = require("inquirer");
 const chalk = require("chalk");
 const storage = require("./storage");
 const { ensureSession, fetchApi } = require("./auth");
 const { ask } = require("./gateway");
 const { runTUI } = require("./tui");
-const { runTheme, setContentBackground, paint } = require("./theme");
-const { mascot } = require("./mascot");
+const { runTheme, setContentBackground } = require("./theme");
+const { logoText, logoLines } = require("./logo");
+
+const mascot = logoText();
 
 const { version: VERSION } = require("../package.json");
 
@@ -21,6 +25,8 @@ const COMMANDS = {
   "/logout": "end the session",
   "/whoami": "show the linked account",
   "/theme": "open theme selector",
+  "/mcp": "list MCP servers and tools (/mcp reload reconecta)",
+  "/allow": "aprovacao automatica nesta sessao (/allow off volta a perguntar)",
   "/background": "set background image (modal asks for URL)",
   "/clear": "clear conversation context",
   "/compact": "compact conversation context",
@@ -45,6 +51,13 @@ async function handleCommand(line) {
       for (const [key, value] of Object.entries(COMMANDS)) {
         console.log(`  ${chalk.bold(key)}  ${chalk.dim(value)}`);
       }
+      console.log(chalk.cyan("\nKeys:\n"));
+      console.log(`  ${chalk.bold("Enter")}  ${chalk.dim("manda a mensagem; durante a resposta ela entra na fila")}`);
+      console.log(`  ${chalk.bold("Esc Esc")}  ${chalk.dim("para a IA na hora (o primeiro Esc avisa)")}`);
+      console.log(`  ${chalk.bold("PgUp/PgDn")}  ${chalk.dim("ou a roda do mouse rola a conversa")}`);
+      console.log(`  ${chalk.bold("Ctrl+Y")}  ${chalk.dim("copia a ultima resposta para a area de transferencia")}`);
+      console.log(`  ${chalk.bold("F2")}  ${chalk.dim("solta o mouse para selecionar texto com o terminal")}`);
+      console.log(`  ${chalk.bold("Ctrl+C")}  ${chalk.dim("sai")}`);
       console.log("");
       return true;
     case "/models": {
@@ -94,6 +107,34 @@ async function handleCommand(line) {
     case "/theme":
       await runTheme();
       return true;
+    case "/allow": {
+      console.log(
+        chalk.dim(
+          "Na interface, /allow liga e /allow off desliga a aprovacao automatica.\n" +
+            "Para ja abrir assim: kafox --allow-all (ou KAFOX_ALLOW_ALL=1)."
+        )
+      );
+      return true;
+    }
+    case "/mcp": {
+      const { McpHub } = require("./mcp");
+      const hub = new McpHub({ cwd: process.cwd() });
+      const statuses = hub.statuses();
+      hub.close();
+      if (!statuses.length) {
+        console.log(chalk.dim("\nNenhum servidor MCP configurado."));
+        const file = path.join(os.homedir(), ".kafox", "mcp.json");
+        console.log(chalk.dim(`Crie ${file} com:`));
+        console.log(chalk.dim('{ "mcp": { "playwright": { "type": "local", "command": ["npx","-y","@playwright/mcp@latest"] } } }'));
+        return true;
+      }
+      console.log(chalk.cyan("\nServidores MCP:\n"));
+      for (const status of statuses) {
+        console.log(`  ${chalk.bold(status.name)}  ${chalk.dim(status.kind)}`);
+      }
+      console.log(chalk.dim("\nAbra a TUI (kafox) e use /mcp para conectar e ver as ferramentas."));
+      return true;
+    }
     case "/background":
       await setContentBackground(arg || null);
       return true;
@@ -168,8 +209,8 @@ async function runPlainREPL() {
   const cfg = storage.getConfig();
   const theme = cfg.theme || "default";
 
-  console.log(paint(theme, mascot));
-  console.log(paint(theme, `\n  Kafox CLI  v${VERSION}  -  opencode style`));
+  console.log(logoLines(theme).join("\n"));
+  console.log(chalk.bold(`\n  Kafox CLI  v${VERSION}`));
   console.log(chalk.dim("  Type /help for commands. Ctrl+C to exit.\n"));
 
   const token = await ensureSession().catch(() => null);
@@ -224,7 +265,7 @@ async function runPlainREPL() {
   });
 }
 
-async function runREPL() {
+async function runREPL(options = {}) {
   // Sem TTY (pipe/CI), mantem o REPL linha a linha.
   if (!process.stdin.isTTY || !process.stdout.isTTY) return runPlainREPL();
 
@@ -232,8 +273,8 @@ async function runREPL() {
   const token = await ensureSession().catch(() => null);
 
   if (!token) {
-    console.log(paint(cfg.theme || "default", mascot));
-    console.log(paint(cfg.theme || "default", `\n  Kafox CLI  v${VERSION}`));
+    console.log(logoLines(cfg.theme || "default").join("\n"));
+    console.log(chalk.bold(`\n  Kafox CLI  v${VERSION}`));
     console.log(chalk.yellow("  You are not logged in."));
     const { doLogin } = await inquirer.prompt([
       { type: "confirm", name: "doLogin", message: "Login now?", default: true },
@@ -246,7 +287,9 @@ async function runREPL() {
   return runTUI({
     commands: COMMANDS,
     onCommand: handleCommand,
-    interactiveCommands: new Set(["/login", "/theme", "/key", "/background"]),
+    // /theme roda dentro da TUI (modal com preview); os demais abrem prompt no terminal.
+    interactiveCommands: new Set(["/login", "/key", "/background"]),
+    autoApprove: Boolean(options?.allowAll),
   });
 }
 

package/src/diff.js

@@ -0,0 +1,193 @@
+/**
+ * Diff de linhas para o preview de edicao (estilo `git diff`, enxuto).
+ *
+ * Usa LCS quando os trechos sao pequenos e cai para um resumo grosseiro em
+ * arquivos grandes, para nao travar a TUI.
+ */
+const MAX_LCS_LINES = 700;
+
+function splitLines(text) {
+  return String(text ?? "").replace(/\r\n?/g, "\n").split("\n");
+}
+
+function commonPrefix(a, b) {
+  const limit = Math.min(a.length, b.length);
+  let index = 0;
+  while (index < limit && a[index] === b[index]) index += 1;
+  return index;
+}
+
+function commonSuffix(a, b, prefix) {
+  const limit = Math.min(a.length, b.length) - prefix;
+  let count = 0;
+  while (count < limit && a[a.length - 1 - count] === b[b.length - 1 - count]) count += 1;
+  return count;
+}
+
+/** LCS classico: devolve as operacoes (del/add) do trecho que mudou. */
+function lcsOps(left, right) {
+  const rows = left.length;
+  const cols = right.length;
+  const table = new Uint16Array((rows + 1) * (cols + 1));
+  const width = cols + 1;
+
+  for (let i = rows - 1; i >= 0; i -= 1) {
+    for (let j = cols - 1; j >= 0; j -= 1) {
+      table[i * width + j] =
+        left[i] === right[j]
+          ? table[(i + 1) * width + j + 1] + 1
+          : Math.max(table[(i + 1) * width + j], table[i * width + j + 1]);
+    }
+  }
+
+  const ops = [];
+  let i = 0;
+  let j = 0;
+  while (i < rows && j < cols) {
+    if (left[i] === right[j]) {
+      ops.push({ type: "ctx", text: left[i] });
+      i += 1;
+      j += 1;
+    } else if (table[(i + 1) * width + j] >= table[i * width + j + 1]) {
+      ops.push({ type: "del", text: left[i] });
+      i += 1;
+    } else {
+      ops.push({ type: "add", text: right[j] });
+      j += 1;
+    }
+  }
+  while (i < rows) ops.push({ type: "del", text: left[i++] });
+  while (j < cols) ops.push({ type: "add", text: right[j++] });
+  return ops;
+}
+
+function coarseOps(left, right) {
+  return [
+    ...left.map((text) => ({ type: "del", text })),
+    ...right.map((text) => ({ type: "add", text })),
+  ];
+}
+
+/**
+ * Todas as operacoes, com numero de linha nos dois lados.
+ * `truncated` avisa que o miolo foi tratado de forma grosseira.
+ */
+function buildOps(before, after) {
+  const left = splitLines(before);
+  const right = splitLines(after);
+  const prefix = commonPrefix(left, right);
+  const suffix = commonSuffix(left, right, prefix);
+
+  const leftMiddle = left.slice(prefix, left.length - suffix);
+  const rightMiddle = right.slice(prefix, right.length - suffix);
+  const truncated = leftMiddle.length > MAX_LCS_LINES || rightMiddle.length > MAX_LCS_LINES;
+  const middle = truncated ? coarseOps(leftMiddle, rightMiddle) : lcsOps(leftMiddle, rightMiddle);
+
+  const ops = [];
+  for (let index = 0; index < prefix; index += 1) {
+    ops.push({ type: "ctx", text: left[index], beforeNo: index + 1, afterNo: index + 1 });
+  }
+
+  let beforeNo = prefix + 1;
+  let afterNo = prefix + 1;
+  let changed = false;
+  for (const op of middle) {
+    if (op.type === "ctx") {
+      ops.push({ ...op, beforeNo, afterNo });
+      beforeNo += 1;
+      afterNo += 1;
+    } else if (op.type === "del") {
+      ops.push({ ...op, beforeNo });
+      beforeNo += 1;
+      changed = true;
+    } else {
+      ops.push({ ...op, afterNo });
+      afterNo += 1;
+      changed = true;
+    }
+  }
+
+  for (let index = 0; index < suffix; index += 1) {
+    const line = left.length - suffix + index;
+    ops.push({
+      type: "ctx",
+      text: left[line],
+      beforeNo: line + 1,
+      afterNo: right.length - suffix + index + 1,
+    });
+  }
+
+  return { ops, truncated, changed };
+}
+
+function count(lines) {
+  return {
+    added: lines.filter((line) => line.type === "add").length,
+    removed: lines.filter((line) => line.type === "del").length,
+  };
+}
+
+/** Mantem so as mudancas e `context` linhas em volta (com o indice original). */
+function keptWithContext(ops, context) {
+  const keep = new Set();
+  ops.forEach((op, index) => {
+    if (op.type === "ctx") return;
+    for (let cursor = index - context; cursor <= index + context; cursor += 1) {
+      if (cursor >= 0 && cursor < ops.length) keep.add(cursor);
+    }
+  });
+  return ops.map((op, index) => ({ op, index })).filter((entry) => keep.has(entry.index));
+}
+
+/**
+ * Diff enxuto, com numeros de linha e `context` linhas de contexto.
+ * Arquivo identico devolve lista vazia.
+ */
+function diffLines(before, after, { context = 2 } = {}) {
+  const { ops, truncated, changed } = buildOps(before, after);
+  if (!changed) return { lines: [], added: 0, removed: 0, truncated: false };
+  const lines = keptWithContext(ops, context).map((entry) => entry.op);
+  return { lines, ...count(lines), truncated };
+}
+
+/**
+ * Diff agrupado em blocos separados (cada regiao que mudou vira um bloco),
+ * limitado a `maxLines` linhas para caber no preview.
+ */
+function diffBlocks(before, after, { context = 2, maxLines = 60 } = {}) {
+  const { ops, truncated, changed } = buildOps(before, after);
+  if (!changed) return { blocks: [], added: 0, removed: 0, truncated: false, total: 0 };
+
+  const kept = keptWithContext(ops, context);
+  const blocks = [];
+  let current = null;
+  let previousIndex = null;
+
+  for (const entry of kept) {
+    if (previousIndex == null || entry.index !== previousIndex + 1) {
+      current = [];
+      blocks.push(current);
+    }
+    current.push(entry.op);
+    previousIndex = entry.index;
+  }
+
+  let budget = maxLines;
+  const limited = [];
+  for (const block of blocks) {
+    if (budget <= 0) break;
+    const slice = block.slice(0, budget);
+    limited.push(slice);
+    budget -= slice.length;
+    if (slice.length < block.length) limited.push([{ type: "gap", text: "..." }]);
+  }
+
+  return {
+    blocks: limited,
+    ...count(kept.map((entry) => entry.op)),
+    truncated,
+    total: blocks.length,
+  };
+}
+
+module.exports = { diffLines, diffBlocks, splitLines, lcsOps, buildOps };