primocode 8.42.2 → 9.0.0

package/lib/marketplace.js

@@ -0,0 +1,189 @@
+/**
+ * marketplace.js — a tela das skills, navegável pelas setas.
+ *
+ *   "/marketplace abre uma tela navegável no terminal, com navegação pelas
+ *    setas, seções (uma delas é a seção de Skills) e rolagem para baixo. O
+ *    usuário navega, ativa e instala skills ali. Dentro do marketplace existe
+ *    a opção 'New Skill': seleciona com as setas, dá Enter, e o terminal pede
+ *    em sequência o nome e o conteúdo da skill."
+ *
+ * ── O DESENHO É FUNÇÃO PURA, DE NOVO ─────────────────────────────────────
+ * `montar()` recebe um estado e devolve linhas. `andar()` recebe uma tecla e
+ * devolve o estado seguinte. Nenhuma das duas toca no terminal nem no disco.
+ *
+ * É o mesmo desenho do `/effort` e da caixa de digitar, e pelo mesmo motivo:
+ * uma tela de terminal que só existe enquanto alguém aperta seta é uma tela
+ * que ninguém consegue testar. Assim o teste percorre a lista inteira, abre e
+ * fecha seção, rola até o fim e confere o que apareceu — sem nada na tela.
+ *
+ * ── POR QUE A LISTA É PLANA POR DENTRO ───────────────────────────────────
+ * A tela tem seções, mas a navegação é UMA lista: título de seção é item que
+ * não se escolhe, e a seta pula por cima dele. Tentar navegar em árvore (seta
+ * para entrar, outra para sair) é o tipo de coisa que exige explicação — e
+ * uma tela que precisa de manual não serve para quem abriu o terminal para
+ * fazer outra coisa.
+ *
+ * ── O QUE ESTE MARKETPLACE NÃO É ─────────────────────────────────────────
+ * Não há loja na internet. O catálogo é o que vem no produto mais o que
+ * estiver instalado na máquina, e é isso que a tela mostra — sem inventar um
+ * "1.248 skills disponíveis" que não existe. O dia em que existir um índice
+ * remoto, ele entra como mais uma seção.
+ */
+
+'use strict';
+
+const { c, truncate, padRight, visibleWidth } = require('./ui.js');
+
+// ── o estado ─────────────────────────────────────────────────────────────
+
+/**
+ * @param {Array} skills  o que `skills.listar()` devolveu
+ */
+function novo(skills) {
+    // A seleção nasce no primeiro item ESCOLHÍVEL, não no zero — o zero é um
+    // título de seção, e uma tela que abre sem nada marcado parece travada.
+    const base = { skills: skills || [], sel: 0, topo: 0, saiu: null };
+    const lista = itens(base);
+    base.sel = escolhivel(lista[0]) ? 0 : proximo(lista, 0, 1);
+    return base;
+}
+
+/**
+ * A lista plana: cabeçalhos de seção e itens, na ordem em que aparecem.
+ *
+ * Cada item diz o que é e o que fazer com ele. A tela e as teclas leem daqui,
+ * então não existe a chance de uma delas achar que o terceiro item é outro.
+ */
+function itens(estado) {
+    const lista = [];
+    const ligadas = estado.skills.filter((s) => s.ligada);
+    const desligadas = estado.skills.filter((s) => !s.ligada);
+
+    lista.push({ tipo: 'secao', texto: 'Skills ativas', conta: ligadas.length });
+    if (!ligadas.length) lista.push({ tipo: 'vazio', texto: 'nenhuma ativa' });
+    for (const s of ligadas) lista.push({ tipo: 'skill', skill: s });
+
+    lista.push({ tipo: 'secao', texto: 'Desligadas', conta: desligadas.length });
+    if (!desligadas.length) lista.push({ tipo: 'vazio', texto: 'nenhuma desligada' });
+    for (const s of desligadas) lista.push({ tipo: 'skill', skill: s });
+
+    lista.push({ tipo: 'secao', texto: 'Criar' });
+    lista.push({ tipo: 'nova', texto: 'New Skill', detalhe: 'escreva a sua — o nome e o prompt' });
+    lista.push({ tipo: 'instalar', texto: 'Instalar de um arquivo', detalhe: 'um SKILL.md que você tem no disco' });
+
+    return lista;
+}
+
+/** Dá para parar em cima deste item? Título de seção e vazio, não. */
+const escolhivel = (item) => item && item.tipo !== 'secao' && item.tipo !== 'vazio';
+
+/** O primeiro item escolhível a partir de `de`, andando em `passo`. */
+function proximo(lista, de, passo) {
+    let i = de;
+    for (let n = 0; n < lista.length; n++) {
+        i += passo;
+        if (i < 0) i = lista.length - 1;
+        if (i >= lista.length) i = 0;
+        if (escolhivel(lista[i])) return i;
+    }
+    return de;
+}
+
+/**
+ * Uma tecla → o estado seguinte.
+ *
+ * Devolve `{ estado, acao }`. A ação é o que o mundo lá fora precisa fazer —
+ * ligar uma skill, abrir o diálogo de criar, sair. Este módulo não faz nada
+ * disso: ele não sabe gravar arquivo nem perguntar nada.
+ */
+function andar(estado, tecla, { altura = 14 } = {}) {
+    const lista = itens(estado);
+    const e = { ...estado };
+
+    // O primeiro pouso: se a seleção caiu num título, desce até um item.
+    if (!escolhivel(lista[e.sel])) e.sel = proximo(lista, e.sel, 1);
+
+    const nome = (tecla && tecla.name) || '';
+
+    if (nome === 'down' || nome === 'j') e.sel = proximo(lista, e.sel, 1);
+    else if (nome === 'up' || nome === 'k') e.sel = proximo(lista, e.sel, -1);
+    else if (nome === 'pagedown') { for (let i = 0; i < 5; i++) e.sel = proximo(lista, e.sel, 1); }
+    else if (nome === 'pageup') { for (let i = 0; i < 5; i++) e.sel = proximo(lista, e.sel, -1); }
+    else if (nome === 'home') { e.sel = proximo(lista, lista.length - 1, 1); }
+    else if (nome === 'end') { e.sel = proximo(lista, 0, -1); }
+    else if (nome === 'escape' || nome === 'q') return { estado: { ...e, saiu: 'fechar' }, acao: { tipo: 'fechar' } };
+    else if (nome === 'return' || nome === 'enter' || (tecla && tecla.sequence === ' ')) {
+        const item = lista[e.sel];
+        if (!item) return { estado: e, acao: null };
+        if (item.tipo === 'skill') {
+            return { estado: e, acao: { tipo: 'alternar', skill: item.skill } };
+        }
+        if (item.tipo === 'nova') return { estado: { ...e, saiu: 'nova' }, acao: { tipo: 'nova' } };
+        if (item.tipo === 'instalar') return { estado: { ...e, saiu: 'instalar' }, acao: { tipo: 'instalar' } };
+    }
+
+    // A janela acompanha a seleção: sem isto, descer faz o item escolhido
+    // sumir embaixo e a seta parece ter parado de funcionar.
+    const visiveis = Math.max(4, altura);
+    if (e.sel < e.topo) e.topo = e.sel;
+    if (e.sel >= e.topo + visiveis) e.topo = e.sel - visiveis + 1;
+    e.topo = Math.max(0, Math.min(e.topo, Math.max(0, lista.length - visiveis)));
+
+    return { estado: e, acao: null };
+}
+
+// ── o desenho ────────────────────────────────────────────────────────────
+
+function montar(estado, { colunas = 80, altura = 14 } = {}) {
+    const larg = Math.max(40, Math.min(colunas - 1, 110));
+    const lista = itens(estado);
+    const visiveis = Math.max(4, altura);
+    const topo = Math.max(0, Math.min(estado.topo || 0, Math.max(0, lista.length - visiveis)));
+
+    const out = [];
+    out.push('');
+    out.push('  ' + c.bold(c.brand('Marketplace')) + c.dim('  ·  as skills do Primo Code'));
+    out.push('  ' + c.dim('─'.repeat(larg - 4)));
+
+    for (let i = topo; i < Math.min(lista.length, topo + visiveis); i++) {
+        const item = lista[i];
+        const escolhido = i === estado.sel;
+        const seta = escolhido ? c.brand('❯ ') : '  ';
+
+        if (item.tipo === 'secao') {
+            // Linha em branco antes da seção, menos na primeira: é o que
+            // separa os grupos sem precisar de moldura.
+            if (out.length > 3) out.push('');
+            out.push('  ' + c.bold(c.white(item.texto))
+                + (item.conta != null ? c.dim(`  ${item.conta}`) : ''));
+            continue;
+        }
+        if (item.tipo === 'vazio') { out.push('    ' + c.dim(item.texto)); continue; }
+
+        if (item.tipo === 'skill') {
+            const s = item.skill;
+            const marca = s.ligada ? c.ok('●') : c.dim('○');
+            const titulo = escolhido ? c.bold(c.white(s.titulo)) : c.white(s.titulo);
+            const selo = s.doProduto ? c.dim('  do produto') : c.brandDim('  sua');
+            out.push('  ' + seta + marca + ' ' + truncate(titulo + selo, larg - 8));
+            // A descrição só aparece no que está selecionado: com ela em
+            // todas, a lista dobra de altura e ninguém lê nenhuma.
+            if (escolhido && s.descricao) {
+                out.push('      ' + c.dim(truncate(s.descricao, larg - 8)));
+            }
+            continue;
+        }
+
+        const titulo = escolhido ? c.bold(c.brand(item.texto)) : c.brandDim(item.texto);
+        out.push('  ' + seta + titulo);
+        if (escolhido && item.detalhe) out.push('      ' + c.dim(item.detalhe));
+    }
+
+    out.push('');
+    out.push('  ' + c.dim('─'.repeat(larg - 4)));
+    out.push('  ' + c.dim('↑↓ navega · Enter liga e desliga · Esc fecha'));
+    out.push('');
+    return out.join('\n');
+}
+
+module.exports = { novo, itens, andar, montar, escolhivel, proximo };

package/lib/permissao.js

@@ -0,0 +1,137 @@
+/**
+ * permissao.js — o portão do controle do computador.
+ *
+ *   "Implementar controle do computador do usuário. Sempre pedir permissão
+ *    antes: aparece o pedido, o usuário autoriza, e só então o agente age. O
+ *    usuário assiste o agente mexendo na máquina em tempo real."
+ *
+ * ── O QUE FALTAVA ────────────────────────────────────────────────────────
+ * O controle do computador já existia inteiro (lib/desktop.js): mouse,
+ * teclado, janelas, clique em botão pelo nome. O que não existia era o
+ * pedido. O agente decidia mexer e mexia — o ponteiro saía andando sozinho
+ * sem ninguém ter dito que podia.
+ *
+ * E a diferença entre isso e as outras ferramentas é real, não cerimônia:
+ * escrever arquivo acontece DENTRO da pasta do projeto, e o que der errado se
+ * desfaz. Mover o mouse e apertar teclas acontece no computador inteiro, no
+ * programa que estiver na frente — e um `alt+tab` no momento errado digita o
+ * que o agente ia escrever dentro da sua conversa aberta no WhatsApp.
+ *
+ * ── AS TRÊS RESPOSTAS ────────────────────────────────────────────────────
+ * "Sim, agora" · "Sim, esta sessão inteira" · "Não".
+ *
+ * A do meio existe porque uma tarefa de desktop são dez, vinte ações. Pedir
+ * a cada clique transformaria a permissão num botão que a pessoa aperta sem
+ * ler — que é o mesmo que não pedir, com uma etapa a mais. Pedir UMA vez, com
+ * o que ele vai fazer escrito, é a pergunta que ainda é lida.
+ *
+ * A sessão é a sessão: fechar o PrimoCode esquece tudo. Não há arquivo de
+ * "sempre permitir" de propósito — uma autorização permanente é exatamente o
+ * que ninguém lembra de ter dado.
+ *
+ * ── O QUE NÃO PASSA POR AQUI ─────────────────────────────────────────────
+ * Ler a tela (`desktop_screenshot`, `desktop_windows`, `desktop_elements`,
+ * `desktop_size`) não mexe em nada — é o agente ABRINDO O OLHO, e é o que ele
+ * precisa fazer para saber onde clicar. Exigir autorização para olhar
+ * obrigaria a pessoa a responder duas vezes a mesma pergunta: uma para ele
+ * ver, outra para ele agir.
+ *
+ * O print merece uma linha à parte: ele vê a sua tela inteira, e isso é
+ * sério. Mas quem decide se o conteúdo da tela sai da máquina é o modelo, e
+ * modelo de texto não enxerga imagem — o print vira arquivo no disco, para o
+ * agente medir onde as coisas estão. Ler é olhar; o portão é para AGIR.
+ */
+
+'use strict';
+
+// Ferramentas que MEXEM na máquina. Todo o resto do `desktop_*` é olhar.
+const AGEM = new Set([
+    'desktop_click', 'desktop_double_click', 'desktop_click_element',
+    'desktop_move', 'desktop_drag', 'desktop_type', 'desktop_key',
+    'desktop_scroll', 'desktop_open_app',
+]);
+
+/* O que cada uma faz, em português de gente. Vai na pergunta: "autoriza
+   desktop_click_element" não é uma pergunta que alguém consiga responder. */
+const EM_PORTUGUES = {
+    desktop_click: 'clicar na sua tela',
+    desktop_double_click: 'dar um clique duplo na sua tela',
+    desktop_click_element: 'clicar num botão da janela aberta',
+    desktop_move: 'mover o seu mouse',
+    desktop_drag: 'arrastar com o seu mouse',
+    desktop_type: 'digitar no programa que está na frente',
+    desktop_key: 'apertar teclas no programa que está na frente',
+    desktop_scroll: 'rolar a tela',
+    desktop_open_app: 'abrir um programa no seu computador',
+};
+
+function novo() {
+    return { liberado: false, negado: false, pedidos: 0 };
+}
+
+/** Esta ferramenta mexe na máquina? */
+function precisa(nome) { return AGEM.has(nome); }
+
+/** A frase do que ele quer fazer, com o alvo quando há um. */
+function descrever(nome, args) {
+    const a = args || {};
+    const base = EM_PORTUGUES[nome] || nome;
+    const alvo = a.name || a.app || a.window || a.text || a.key
+        || (a.x != null ? `${a.x},${a.y}` : '');
+    const curto = String(alvo || '').replace(/\s+/g, ' ').trim();
+    return curto ? `${base} — ${curto.length > 60 ? curto.slice(0, 59) + '…' : curto}` : base;
+}
+
+/**
+ * O portão.
+ *
+ * @param {object} estado      o estado da sessão (de `novo()`)
+ * @param {string} nome        a ferramenta
+ * @param {object} args        os argumentos dela
+ * @param {function} perguntar async (frase) => 'agora' | 'sessao' | 'nao'
+ * @returns {Promise<{ok: boolean, error?: string, primeira?: boolean}>}
+ */
+async function pedir(estado, nome, args, perguntar) {
+    if (!precisa(nome)) return { ok: true };
+    if (estado.liberado) return { ok: true };
+
+    /* Negar uma vez vale para a sessão. Sem isto, quem disse não leva a mesma
+       pergunta na ação seguinte, e na seguinte — o agente tem vinte ações
+       para tentar, e a pessoa acabaria dizendo sim de cansaço. */
+    if (estado.negado) {
+        return {
+            ok: false,
+            error: 'O usuário NÃO autorizou o controle do computador nesta sessão. '
+                + 'Não tente de novo com outra ferramenta de desktop: a resposta é a mesma. '
+                + 'Resolva por outro caminho (arquivos, terminal, navegador) ou diga a ele '
+                + 'o que precisaria ser feito à mão.',
+        };
+    }
+
+    // Sem quem responda (pipe, CI, subagente), a resposta é NÃO. O padrão
+    // seguro de uma pergunta que ninguém ouviu não é "pode".
+    if (typeof perguntar !== 'function') {
+        return {
+            ok: false,
+            error: 'Controle do computador precisa de autorização, e não há ninguém '
+                + 'para autorizar neste modo. Use outro caminho.',
+        };
+    }
+
+    const primeira = estado.pedidos === 0;
+    estado.pedidos++;
+    const resposta = await perguntar(descrever(nome, args), { primeira });
+
+    if (resposta === 'sessao') { estado.liberado = true; return { ok: true, primeira }; }
+    if (resposta === 'agora') return { ok: true, primeira };
+
+    estado.negado = true;
+    return {
+        ok: false,
+        error: 'O usuário recusou o controle do computador. Não insista com outra '
+            + 'ferramenta de desktop — resolva por outro caminho ou explique a ele '
+            + 'o que precisaria ser feito à mão.',
+    };
+}
+
+module.exports = { novo, precisa, pedir, descrever, AGEM, EM_PORTUGUES };

package/lib/registro.js

@@ -0,0 +1,229 @@
+/**
+ * registro.js — o que este pedido fez, para dizer no fim.
+ *
+ *   "Precisa existir um pipeline visível de execução: o que está fazendo, o
+ *    que já fez, o que falhou. Exibir sempre: arquivos alterados, arquivos
+ *    criados, links abertos, comandos rodados, resultados dos testes."
+ *
+ * ── O QUE FALTAVA ────────────────────────────────────────────────────────
+ * Tudo isso JÁ aparecia — uma linha por vez, conforme acontecia. O problema é
+ * que uma tarefa de verdade são trinta ações, e no fim delas a primeira já
+ * saiu da tela. Quem acompanhou viu tudo; quem voltou do café viu o fim de um
+ * rolo de texto e não sabe se o agente criou três arquivos ou trinta, nem se
+ * o teste que ele rodou passou.
+ *
+ * Então, além de narrar, ele ANOTA. No fim sai um balanço do pedido inteiro:
+ * o que nasceu, o que mudou, o que rodou, o que abriu, o que falhou.
+ *
+ * ── POR QUE ANOTAR AQUI E NÃO OLHAR O DISCO ──────────────────────────────
+ * A tentação é perguntar ao git no fim. Não serve: a pasta pode não ser um
+ * repositório, pode ter mudanças anteriores ao pedido, e o `git status` não
+ * sabe qual comando o agente rodou nem qual link ele abriu. O que interessa é
+ * o que o AGENTE fez neste pedido, e quem sabe isso é quem executou.
+ *
+ * ── O QUE CONTA COMO TESTE ───────────────────────────────────────────────
+ * Um `run_shell` cujo comando parece rodar teste. A distinção importa porque
+ * "rodei o teste" é a frase que mais se diz sem prova: com o registro, o que
+ * sai na tela é o comando REAL e o código de saída REAL dele. Quando a saída
+ * traz contagem reconhecível ("12 passed, 1 failed"), ela entra também — mas
+ * o código de saída é o que decide, porque é o que não dá para escrever por
+ * engano.
+ */
+
+'use strict';
+
+const { c, truncate, padRight } = require('./ui.js');
+
+/* Comando que é teste. Deliberadamente restrito: `npm run build` não é
+   teste, e chamar de teste o que não é seria pior que não contar nada. */
+const EH_TESTE = /(^|\s|&&|\|\|)(npm\s+(run\s+)?tests?\b|npm\s+t\b|yarn\s+tests?\b|pnpm\s+tests?\b|pytest\b|python\s+-m\s+pytest\b|jest\b|vitest\b|mocha\b|go\s+test\b|cargo\s+test\b|mvn\s+test\b|rspec\b|phpunit\b)/i;
+
+/* As contagens que os corredores de teste escrevem. Nenhuma é obrigatória:
+   quando nada casa, vale o código de saída, que é o que não mente. */
+const CONTAGENS = [
+    /(\d+)\s+pass(?:ed|ing)\b/i,
+    /(\d+)\s+fail(?:ed|ing|ures?)\b/i,
+];
+
+function novo() {
+    return {
+        criados: [],      // caminhos que nasceram neste pedido
+        alterados: [],    // caminhos que já existiam e mudaram
+        comandos: [],     // { comando, ok, code }
+        testes: [],       // { comando, ok, code, resumo }
+        links: [],        // URLs e arquivos abertos no navegador
+        falhas: [],       // { acao, motivo }
+        pesquisas: [],    // consultas que ele foi olhar antes de escrever
+    };
+}
+
+const jaTem = (lista, valor) => lista.includes(valor);
+
+/** Guarda sem repetir, e sem deixar a lista crescer sem fim. */
+function guardar(lista, valor, teto = 60) {
+    if (!valor || jaTem(lista, valor)) return;
+    if (lista.length < teto) lista.push(valor);
+}
+
+/** A linha de resumo de um teste, quando dá para ler a contagem da saída. */
+function resumoDeTeste(saida) {
+    const texto = String(saida || '');
+    const passou = (texto.match(CONTAGENS[0]) || [])[1];
+    const falhou = (texto.match(CONTAGENS[1]) || [])[1];
+    if (!passou && !falhou) return '';
+    const partes = [];
+    if (passou) partes.push(`${passou} passaram`);
+    if (falhou && Number(falhou) > 0) partes.push(`${falhou} falharam`);
+    return partes.join(', ');
+}
+
+/**
+ * Anota uma ação que acabou de acontecer.
+ *
+ * @param {object} reg     o registro deste pedido
+ * @param {string} nome    o nome da tool
+ * @param {object} args    os argumentos com que ela foi chamada
+ * @param {object} r       o resultado que ela devolveu
+ */
+function anotar(reg, nome, args, r) {
+    if (!reg || !r) return reg;
+    const a = args || {};
+
+    // Ação que falhou entra sempre, seja qual for a tool: é justamente o que
+    // a pessoa precisa ver, e o que some mais rápido do rolo de texto.
+    if (r.ok === false) {
+        const motivo = String(r.error || `saiu com ${r.code}`).replace(/\s+/g, ' ').trim();
+        /* QUAL arquivo, QUAL comando. Sem isso a linha vira
+           "run_shell: saiu com 1" — que diz que algo falhou e não diz o quê,
+           que é o mesmo que não dizer nada. */
+        const alvo = String(a.path || a.command || a.target || a.url || a.consulta || '')
+            .replace(/\s+/g, ' ').trim();
+        if (reg.falhas.length < 20) reg.falhas.push({ acao: nome, alvo, motivo });
+        // Uma tool que falhou não criou nem alterou nada. Continuar daqui
+        // faria um write_file recusado aparecer na lista de criados.
+        return reg;
+    }
+
+    switch (nome) {
+        case 'write_file':
+            // `created` vem do próprio tools.js: ele sabe se o arquivo existia.
+            guardar(r.created ? reg.criados : reg.alterados, r.path || a.path);
+            return reg;
+
+        case 'edit_file':
+        case 'multi_edit':
+            guardar(reg.alterados, r.path || a.path);
+            return reg;
+
+        case 'run_shell': {
+            const comando = String(a.command || '').replace(/\s+/g, ' ').trim();
+            if (!comando) return reg;
+            const item = { comando, ok: r.ok !== false, code: r.code ?? 0 };
+            if (EH_TESTE.test(comando)) {
+                item.resumo = resumoDeTeste(r.stdout || r.saida || r.output || '');
+                if (reg.testes.length < 20) reg.testes.push(item);
+            } else if (reg.comandos.length < 40) {
+                reg.comandos.push(item);
+            }
+            return reg;
+        }
+
+        case 'run_in_new_terminal':
+            if (reg.comandos.length < 40) {
+                reg.comandos.push({ comando: String(a.command || '').trim(), ok: true, code: 0, solto: true });
+            }
+            return reg;
+
+        case 'open_in_browser':
+        case 'browser_open':
+            guardar(reg.links, r.url || a.target || a.url);
+            return reg;
+
+        case 'pesquisar_referencia':
+            guardar(reg.pesquisas, a.consulta || a.query, 12);
+            return reg;
+
+        default:
+            return reg;
+    }
+}
+
+/**
+ * Junta o livro de um subagente no de quem o chamou.
+ *
+ * Sem isto o balanço mentiria por omissão: o especialista de frontend
+ * escreveria cinco arquivos e a tela diria "nenhum arquivo". As conversas
+ * seguem separadas — o que se junta é o que aconteceu no disco.
+ */
+function juntar(destino, outro) {
+    if (!destino || !outro) return destino;
+    for (const campo of ['criados', 'alterados', 'links', 'pesquisas']) {
+        for (const v of outro[campo] || []) guardar(destino[campo], v);
+    }
+    for (const campo of ['comandos', 'testes', 'falhas']) {
+        for (const v of outro[campo] || []) {
+            if (destino[campo].length < 40) destino[campo].push(v);
+        }
+    }
+    return destino;
+}
+
+/** Alguma coisa aconteceu? Um pedido de conversa pura não tem balanço. */
+function vazio(reg) {
+    if (!reg) return true;
+    return !reg.criados.length && !reg.alterados.length && !reg.comandos.length
+        && !reg.testes.length && !reg.links.length && !reg.falhas.length;
+}
+
+/**
+ * O balanço, em texto pronto para a tela.
+ *
+ * Ordem deliberada: primeiro o que mudou no computador da pessoa (arquivos),
+ * depois o que ele rodou, depois a prova (testes), e por último o que falhou
+ * — que é o que ela precisa ler ANTES de ir embora, então fica onde o olho
+ * para, no fim.
+ */
+function resumo(reg, { colunas = 80 } = {}) {
+    if (vazio(reg)) return '';
+    const larg = Math.max(40, Math.min(colunas, 120));
+    const out = [];
+
+    const secao = (rotulo, itens, pinta) => {
+        if (!itens.length) return;
+        out.push('  ' + c.dim(padRight(rotulo, 12)) + pinta(itens[0]));
+        for (const item of itens.slice(1)) out.push('  ' + ' '.repeat(12) + pinta(item));
+    };
+
+    out.push('');
+    out.push('  ' + c.dim('─'.repeat(larg - 4)));
+
+    secao('criados', reg.criados, (f) => c.ok('+ ') + c.white(f));
+    secao('alterados', reg.alterados, (f) => c.brandDim('~ ') + c.white(f));
+    secao('comandos', reg.comandos.map((x) => x), (x) => {
+        const marca = x.solto ? c.dim('▸ ') : x.ok ? c.dim('$ ') : c.err('$ ');
+        return marca + truncate(x.ok ? c.muted(x.comando) : c.warn(x.comando), larg - 18);
+    });
+    secao('links', reg.links, (u) => c.dim('↗ ') + c.brandDim(truncate(u, larg - 18)));
+
+    // Os testes ganham seção própria porque são a PROVA. "Rodei os testes" é
+    // a frase que mais se diz sem prova; aqui sai o comando real e o código
+    // de saída real, que é o que não dá para escrever por engano.
+    if (reg.testes.length) {
+        secao('testes', reg.testes, (t) => {
+            const marca = t.ok ? c.ok('✔ ') : c.err('✗ ');
+            const cauda = t.resumo ? c.muted('  ' + t.resumo)
+                : t.ok ? c.dim('  passou') : c.warn(`  saiu com ${t.code}`);
+            return marca + c.white(truncate(t.comando, larg - 30)) + cauda;
+        });
+    }
+
+    if (reg.falhas.length) {
+        secao('falhou', reg.falhas, (f) => c.warn('! ')
+            + c.muted(truncate(`${f.alvo || f.acao}${f.alvo ? '' : ''} — ${f.motivo}`, larg - 18)));
+    }
+
+    out.push('');
+    return out.join('\n');
+}
+
+module.exports = { novo, anotar, juntar, resumo, vazio, resumoDeTeste, EH_TESTE };