primocode 9.8.0-beta.2 → 9.8.0-beta.21

package/lib/claude-engine.js

@@ -61,6 +61,28 @@ function argsDoModelo() {
     return MODELO_CLAUDE ? ['--model', MODELO_CLAUDE] : [];
 }
 
+/* O Claude Code ENXUTO, como motor. Sem isto cada passo do agente abria o
+ * Claude Code da pessoa inteiro: hooks, plugins, skills, CLAUDE.md dela e as
+ * ferramentas nativas — 36 mil tokens e ~6 s por chamada, e a resposta
+ * chegava com recado de hook pessoal ("context-sync pendente"). Medido em
+ * 25/09: com estes argumentos, a mesma chamada leva 473 tokens e ~3,5 s. Um
+ * pedido de 100 passos pagava aquilo 100 vezes — é a demora de 20 minutos.
+ *
+ * Nada disto tira o que o motor precisa: o protocolo vai inteiro no prompt
+ * (corpoDoProtocolo), e as ferramentas que valem são as do PrimoCode, não as
+ * do Claude Code. */
+const ARGS_ENXUTOS = [
+    '--setting-sources', 'project',
+    '--strict-mcp-config',
+    '--disable-slash-commands',
+    '--tools', '',
+    '--no-session-persistence',
+    '--system-prompt', 'Você é o motor de decisão do PrimoCode. Siga à risca o protocolo que vem na mensagem e responda só com o bloco pedido.',
+];
+function argsDoMotor() {
+    return [...ARGS_ENXUTOS, ...argsDoModelo()];
+}
+
 /**
  * Acha o ÚLTIMO bloco marcado no texto (pode vir ruído de terminal — prompt
  * ANSI, texto solto — antes e depois) e devolve o JSON de dentro dele.
@@ -567,7 +589,7 @@ async function requestActViaHeadless(payload, onEvent) {
         '-p',
         '--output-format', 'json',
         '--dangerously-skip-permissions',
-        ...argsDoModelo(),
+        ...argsDoMotor(),
     ], { encoding: 'utf-8', timeout: 180000, input: prompt, maxBuffer: 32 * 1024 * 1024,
         env: process.env, ...SEM_APARECER });
     const r = JSON.parse(saida);
@@ -577,7 +599,7 @@ async function requestActViaHeadless(payload, onEvent) {
     const pedirCorrecao = (aviso) => {
         const s = execFileSync('claude', [
             '-p', '--output-format', 'json', '--dangerously-skip-permissions',
-            ...argsDoModelo(),
+            ...argsDoMotor(),
         ], {
             encoding: 'utf-8', timeout: 120000, maxBuffer: 32 * 1024 * 1024,
             env: process.env,
@@ -622,7 +644,7 @@ module.exports = {
     // o que veio torto. Reimplementar aquilo no outro motor seria manter dois
     // protocolos que divergem na primeira correção de um deles.
     linhaDoHistorico, nomesDasTools, promptDoProtocolo, promptDeCorrecao,
-    MODELO_CLAUDE, argsDoModelo,
+    MODELO_CLAUDE, argsDoModelo, argsDoMotor,
     SKILL_DIR, SKILL_PATH, garantirSkill,
     temClaudeCode, temOrca, orcaAlcancavel, escolherCaminho,
     garantirEngine, requestAct, emitirDecisao,

package/lib/comandos-extra.js

@@ -0,0 +1,481 @@
+/**
+ * comandos-extra.js — a lógica dos comandos pequenos do terminal.
+ *
+ *   "Mais mascotes, mais comandos." (dono, 24/09/2026)
+ *
+ * /novo, /projetos, /abrir, /doctor, /custo, /copiar, /historico e /atalhos.
+ * Cada um é pequeno e serve a quem nunca programou: saber onde estão os
+ * projetos, abrir o que foi feito, descobrir por que algo não funciona, copiar
+ * a resposta sem selecionar com o mouse.
+ *
+ * O desenho na tela mora no bin/primocode.js; aqui fica o que dá para medir
+ * sem terminal. Por isso quase tudo recebe as dependências de fora (quem
+ * roda comando, quem sonda porta, quem fala com o servidor): o teste troca
+ * por falsos e confere a regra sem abrir navegador nem tocar a rede.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const http = require('http');
+const { spawnSync, execFileSync } = require('child_process');
+
+// ── tamanho e tempo, do jeito que se fala ────────────────────────────────
+
+function fmtTamanho(bytes) {
+    const b = Number(bytes) || 0;
+    if (b < 1024) return `${b} B`;
+    if (b < 1024 * 1024) return `${(b / 1024).toFixed(0)} KB`;
+    if (b < 1024 ** 3) return `${(b / 1024 / 1024).toFixed(1)} MB`;
+    return `${(b / 1024 ** 3).toFixed(1)} GB`;
+}
+
+/* "há 3 h" diz mais que "24/09/2026 14:02" para quem procura o projeto de
+   ontem. Passou de uma semana, a data volta: "há 23 dias" obriga a fazer
+   conta. */
+function quandoFoi(ms, agora = Date.now()) {
+    const s = Math.max(0, Math.round((agora - ms) / 1000));
+    if (s < 60) return 'agora';
+    if (s < 3600) return `há ${Math.floor(s / 60)} min`;
+    if (s < 86400) return `há ${Math.floor(s / 3600)} h`;
+    const dias = Math.floor(s / 86400);
+    if (dias === 1) return 'ontem';
+    if (dias < 7) return `há ${dias} dias`;
+    return new Date(ms).toLocaleDateString('pt-BR');
+}
+
+// ── /projetos ────────────────────────────────────────────────────────────
+
+/* O que não é do projeto: dependência baixada e histórico do git. Entrar em
+   node_modules para somar tamanho custa segundos numa pasta grande, e o
+   número que a pessoa quer é o do que ELA (ou o agente) escreveu. */
+const PULAR = new Set(['node_modules', '.git', '.next', 'dist', 'build', '.cache', '__pycache__', '.venv', 'venv']);
+const TETO_ENTRADAS = 4000;
+
+/** Tamanho e última mudança de uma pasta, olhando os arquivos de dentro. */
+function medirPasta(dir) {
+    let bytes = 0, arquivos = 0, modificado = 0, vistos = 0, cortado = false;
+    const fila = [dir];
+    try { modificado = fs.statSync(dir).mtimeMs; } catch { /* sumiu */ }
+    while (fila.length) {
+        const atual = fila.pop();
+        let itens;
+        try { itens = fs.readdirSync(atual, { withFileTypes: true }); } catch { continue; }
+        for (const it of itens) {
+            // Teto: uma pasta com cem mil arquivos não pode segurar o /projetos.
+            if (++vistos > TETO_ENTRADAS) { cortado = true; fila.length = 0; break; }
+            if (PULAR.has(it.name)) continue;
+            const p = path.join(atual, it.name);
+            if (it.isDirectory()) { fila.push(p); continue; }
+            if (!it.isFile()) continue;
+            try {
+                const st = fs.statSync(p);
+                bytes += st.size;
+                arquivos++;
+                if (st.mtimeMs > modificado) modificado = st.mtimeMs;
+            } catch { /* arquivo que sumiu no meio */ }
+        }
+    }
+    return { bytes, arquivos, modificado, cortado };
+}
+
+/**
+ * Os projetos de ~/primocode, do mais recente para o mais antigo.
+ * "Mais recente" é o último ARQUIVO mexido lá dentro — a data da pasta só
+ * muda quando nasce ou some um item, e editar o index.html não conta.
+ */
+function listarProjetos(raiz) {
+    let nomes = [];
+    try {
+        nomes = fs.readdirSync(raiz, { withFileTypes: true })
+            .filter((d) => d.isDirectory() && !d.name.startsWith('.'))
+            .map((d) => d.name);
+    } catch { return []; }
+    return nomes
+        .map((nome) => ({ nome, dir: path.join(raiz, nome), ...medirPasta(path.join(raiz, nome)) }))
+        .sort((a, b) => b.modificado - a.modificado);
+}
+
+// ── /novo ────────────────────────────────────────────────────────────────
+
+/**
+ * O nome da pasta do /novo. O do modelo (lib/nome-projeto.js) quando veio; o
+ * `deriveProjectName` quando não veio. Nunca o de uma pasta que já existe —
+ * /novo é justamente "não continue aquele": cair dentro de outro projeto
+ * por coincidência de nome é o defeito que ele existe para evitar.
+ */
+function nomeDoNovo({ descricao, nomes, sugerido, derivar, slugify, semColisao }) {
+    const base = slugify(sugerido || (derivar ? derivar(descricao) : '') || 'projeto') || 'projeto';
+    return semColisao(base, nomes || []);
+}
+
+/** O pedido que vai ao agente: a descrição, com a ordem de começar do zero. */
+function pedidoDoNovo(descricao, nome) {
+    return `Projeto NOVO, do zero, na pasta ${nome} (acabou de ser criada e está vazia). `
+        + `Não reaproveite nem abra outros projetos. O pedido: ${descricao}`;
+}
+
+// ── /abrir ───────────────────────────────────────────────────────────────
+
+/* As portas que o projeto diz usar. Script com --port/-p/PORT= manda; sem
+   isso, a porta padrão do framework que ele instala. */
+const PORTA_PADRAO = [
+    ['vite', 5173], ['next', 3000], ['react-scripts', 3000], ['astro', 4321],
+    ['@angular/core', 4200], ['nuxt', 3000], ['@sveltejs/kit', 5173], ['express', 3000],
+    ['parcel', 1234], ['gatsby', 8000], ['@remix-run/dev', 3000],
+];
+/* Sem framework conhecido, as portas de sempre — mas SÓ se o projeto tem cara
+   de servidor (script dev/start, app.py…). Sondar 8000 às cegas abria o
+   servidor de OUTRO programa que estivesse de pé na máquina: medido aqui,
+   um projeto só com memory.md abriu um localhost:8000 que não era dele. */
+const PORTAS_NODE = [3000, 5173, 8080];
+const PORTAS_PYTHON = [5000, 8000];
+const SERVIDOR_PYTHON = ['app.py', 'main.py', 'server.py', 'manage.py'];
+
+function portasDoProjeto(dir) {
+    let pkg;
+    try { pkg = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8')); } catch { pkg = null; }
+    if (!pkg) return SERVIDOR_PYTHON.some((f) => fs.existsSync(path.join(dir, f))) ? PORTAS_PYTHON.slice() : [];
+    const portas = [];
+    const scripts = Object.values(pkg.scripts || {}).join(' ');
+    for (const m of scripts.matchAll(/(?:--port[= ]|-p |PORT=)(\d{2,5})\b/g)) portas.push(Number(m[1]));
+    const deps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+    for (const [dep, porta] of PORTA_PADRAO) if (deps[dep]) portas.push(porta);
+    if (!portas.length && pkg.scripts && (pkg.scripts.dev || pkg.scripts.start)) portas.push(...PORTAS_NODE);
+    return [...new Set(portas)];
+}
+
+/** A porta responde HTTP? Um GET curto em 127.0.0.1, sem esperar o corpo. */
+function sondarPorta(porta, ms = 600) {
+    return new Promise((ok) => {
+        const req = http.get({ host: '127.0.0.1', port: porta, path: '/', timeout: ms }, (res) => {
+            res.resume();
+            ok(true);
+        });
+        req.on('timeout', () => { req.destroy(); ok(false); });
+        req.on('error', () => ok(false));
+    });
+}
+
+/* Onde procurar a página pronta: a raiz, e as pastas em que o build costuma
+   deixar o resultado. */
+const PAGINAS = ['index.html', 'public/index.html', 'dist/index.html', 'build/index.html', 'src/index.html', 'docs/index.html'];
+
+/**
+ * O que o /abrir deve abrir.
+ *   1. um servidor do projeto que esteja de pé (a porta que ele diz usar);
+ *   2. a index.html, se houver.
+ * Nessa ordem porque a página servida é a de verdade (com rota, API, build);
+ * o arquivo aberto direto às vezes nem carrega o JavaScript.
+ */
+async function acharAlvoAbrir(dir, { sondar = sondarPorta } = {}) {
+    for (const porta of portasDoProjeto(dir)) {
+        if (await sondar(porta)) return { tipo: 'url', url: `http://localhost:${porta}`, porque: 'o servidor do projeto está de pé' };
+    }
+    for (const rel of PAGINAS) {
+        const p = path.join(dir, rel);
+        if (fs.existsSync(p)) return { tipo: 'arquivo', caminho: p, porque: rel };
+    }
+    return null;
+}
+
+// ── /doctor ──────────────────────────────────────────────────────────────
+
+function versaoMinima(atual, minima) {
+    const a = String(atual).replace(/^v/, '').split('.').map(Number);
+    const m = String(minima).replace(/^[^\d]*/, '').split('.').map(Number);
+    for (let i = 0; i < 3; i++) {
+        if ((a[i] || 0) > (m[i] || 0)) return true;
+        if ((a[i] || 0) < (m[i] || 0)) return false;
+    }
+    return true;
+}
+
+/* O Python com Quartz/AppKit é o cursor do Primo (lib/cursor.js). A mesma
+   pergunta que ele faz, sem instalar nada: o doctor só olha. */
+function pythonComQuartz() {
+    let py = null;
+    try { py = require('./voz.js').python(); } catch { /* sem voz.js */ }
+    if (!py) return { py: null, tem: false };
+    try {
+        execFileSync(py, ['-c', 'import Quartz, AppKit'], { stdio: 'ignore', timeout: 20000 });
+        return { py, tem: true };
+    } catch { return { py, tem: false }; }
+}
+
+function espacoLivre(dir) {
+    // statfs é do Node 18.15+; o engines pede 18.17, mas sem ele não quebra.
+    if (typeof fs.statfsSync !== 'function') return null;
+    try { const s = fs.statfsSync(dir); return s.bavail * s.bsize; } catch { return null; }
+}
+
+function comPrazo(promessa, ms) {
+    let t;
+    return Promise.race([
+        promessa,
+        new Promise((_, nao) => { t = setTimeout(() => nao(new Error(`não respondeu em ${Math.round(ms / 1000)}s`)), ms); }),
+    ]).finally(() => clearTimeout(t));
+}
+
+const UM_GB = 1024 ** 3;
+
+/**
+ * A lista do /doctor. Cada linha: `ok` true (✓), false (✗) ou null (·, não se
+ * aplica aqui), o que foi olhado, o detalhe, e — quando ✗ — como consertar em
+ * uma linha. Consertar é a parte que importa: "✗ Chrome" sozinho manda a
+ * pessoa pesquisar; "instale em google.com/chrome" resolve.
+ *
+ * Tudo injetável (`dep`), para o teste passar os casos sem rede nem Chrome.
+ */
+async function diagnosticar(dep = {}) {
+    const d = {
+        versaoNode: process.version,
+        minimaNode: '18.17.0',
+        plataforma: process.platform,
+        saude: null,                 // async () => objeto do /health
+        prazoServidor: 15000,
+        provedor: () => null,        // provedor do /api, ou null
+        conferirChave: null,         // async (id, chave) => { ok, error }
+        cliInstalado: () => false,   // (id) => bool
+        acharChrome: () => null,
+        pythonQuartz: pythonComQuartz,
+        raiz: null,
+        espaco: espacoLivre,
+        arquivoConfig: null,
+        ...dep,
+    };
+    const linhas = [];
+    const poe = (ok, item, detalhe, conserto) => linhas.push({ ok, item, detalhe, conserto: ok === false ? conserto : undefined });
+
+    // Node
+    const nodeOk = versaoMinima(d.versaoNode, d.minimaNode);
+    poe(nodeOk, 'Node', d.versaoNode, `atualize para ${d.minimaNode} ou mais em nodejs.org`);
+
+    // Servidor
+    if (d.saude) {
+        try {
+            const h = await comPrazo(d.saude(), d.prazoServidor);
+            poe(true, 'Servidor', `${h && h.status || 'ok'}${h && h.version ? ' · v' + h.version : ''}`);
+        } catch (e) {
+            poe(false, 'Servidor', e.message, 'confira a internet; se acabou de ligar, ele acorda em até 1 min — rode /doctor de novo');
+        }
+    }
+
+    // /api
+    const p = d.provedor();
+    if (!p) {
+        poe(null, '/api', 'não configurado — os pedidos vão pelo servidor (normal)');
+    } else if (p.cli) {
+        const ok = !!d.cliInstalado(p.id);
+        poe(ok, '/api', p.nome, `o ${p.nome} não está instalado ou logado — instale e faça login, ou /api off`);
+    } else if (d.conferirChave) {
+        let r;
+        try { r = await comPrazo(d.conferirChave(p.id, p.chave), d.prazoServidor); } catch (e) { r = { ok: false, error: e.message }; }
+        poe(!!r.ok, '/api', `${p.nome} · ${p.modelo}${r.ok ? '' : ' · ' + r.error}`, `cole a chave de novo com /api, ou /api off para voltar ao servidor`);
+    } else {
+        poe(true, '/api', `${p.nome} · ${p.modelo}`);
+    }
+
+    // Chrome
+    let chrome = null;
+    try { chrome = d.acharChrome(); } catch { /* sem módulo */ }
+    poe(!!chrome, 'Navegador', chrome || 'nenhum Chrome/Edge/Brave encontrado',
+        'instale o Google Chrome (google.com/chrome), ou aponte PRIMOCODE_CHROME para o seu');
+
+    // Cursor (Python + PyObjC) — só existe no macOS
+    if (d.plataforma !== 'darwin') {
+        poe(null, 'Cursor do Primo', 'só no macOS');
+    } else {
+        const q = d.pythonQuartz();
+        if (!q.py) poe(false, 'Cursor do Primo', 'sem Python 3', 'instale o Python 3 em python.org e abra o terminal de novo');
+        else poe(!!q.tem, 'Cursor do Primo', q.tem ? `${q.py} com PyObjC` : `${q.py} sem PyObjC`,
+            `ele tenta instalar sozinho no primeiro uso; se falhar: ${q.py} -m pip install pyobjc-framework-Quartz pyobjc-framework-Cocoa`);
+    }
+
+    // Disco
+    if (d.raiz) {
+        const livre = d.espaco(d.raiz);
+        if (livre == null) poe(null, 'Disco', 'não consegui medir aqui');
+        else poe(livre >= UM_GB, 'Disco', `${fmtTamanho(livre)} livres`, 'menos de 1 GB livre: apague projetos velhos em ~/primocode ou esvazie a lixeira');
+    }
+
+    // Config
+    if (d.arquivoConfig) {
+        if (!fs.existsSync(d.arquivoConfig)) poe(true, 'Config', 'ainda não existe (usa o padrão)');
+        else {
+            try { JSON.parse(fs.readFileSync(d.arquivoConfig, 'utf8')); poe(true, 'Config', d.arquivoConfig); }
+            catch (e) { poe(false, 'Config', `não consegui ler: ${e.message}`, `apague ${d.arquivoConfig} — ele nasce de novo no padrão`); }
+        }
+    }
+    return linhas;
+}
+
+// ── /custo ───────────────────────────────────────────────────────────────
+
+/* O contador da sessão. Cada pedido ao modelo passa por lib/api.js; em vez
+   de mexer lá dentro, as funções exportadas são embrulhadas uma vez na
+   abertura. O act.js chama `motor.requestAct` com `motor = api` (o próprio
+   objeto do módulo), então o embrulho pega o agente, o chat, o resumo e o
+   plano — todo mundo que conversa com o modelo.
+
+   Token exato só quando o provedor manda `usage`. Sem isso, a conta é a de
+   bolso: 4 caracteres ≈ 1 token. O /custo diz qual das duas está mostrando. */
+function novoContador() { return { porProvedor: {}, desde: Date.now() }; }
+
+const tam = (x) => { try { return typeof x === 'string' ? x.length : JSON.stringify(x || '').length; } catch { return 0; } };
+
+function registrar(cont, provedor) {
+    const b = cont.porProvedor[provedor] || (cont.porProvedor[provedor] = {
+        pedidos: 0, charsEnviados: 0, charsRecebidos: 0, tokEnviados: 0, tokRecebidos: 0, exatos: 0,
+    });
+    b.pedidos++;
+    return b;
+}
+
+function medirEnvio(b, payload) {
+    // O token da conta e o sinal de abortar não são conteúdo: não vão pro modelo.
+    const { token, sinal, ...corpo } = payload || {};
+    b.charsEnviados += tam(corpo);
+}
+
+function medirEvento(b, evt) {
+    if (!evt) return;
+    if (evt.delta) b.charsRecebidos += String(evt.delta).length;
+    if (evt.tool_call) b.charsRecebidos += tam(evt.tool_call);
+    const u = evt.usage;
+    if (u && (u.prompt_tokens || u.completion_tokens || u.input_tokens || u.output_tokens)) {
+        b.tokEnviados += Number(u.prompt_tokens || u.input_tokens || 0);
+        b.tokRecebidos += Number(u.completion_tokens || u.output_tokens || 0);
+        b.exatos++;
+    }
+}
+
+function instalarContador(api, cont, quemAtende) {
+    if (!api || api.__contador) return;
+    api.__contador = cont;
+    for (const nome of ['requestAct', 'requestChat']) {
+        const original = api[nome];
+        if (typeof original !== 'function') continue;
+        api[nome] = function (servidor, payload, onEvent) {
+            const b = registrar(cont, quemAtende());
+            medirEnvio(b, payload);
+            return original.call(this, servidor, payload, (evt) => {
+                medirEvento(b, evt);
+                return onEvent ? onEvent(evt) : undefined;
+            });
+        };
+    }
+    for (const nome of ['requestResumo', 'requestPlano', 'requestRefino']) {
+        const original = api[nome];
+        if (typeof original !== 'function') continue;
+        api[nome] = function (servidor, payload) {
+            const b = registrar(cont, quemAtende());
+            medirEnvio(b, payload);
+            return Promise.resolve(original.call(this, servidor, payload)).then((r) => {
+                b.charsRecebidos += tam(r);
+                if (r && r.usage) medirEvento(b, { usage: r.usage });
+                return r;
+            });
+        };
+    }
+}
+
+/** As linhas do /custo: por provedor, e o total. */
+function resumoCusto(cont) {
+    const linhas = [];
+    let total = { pedidos: 0, enviados: 0, recebidos: 0 };
+    for (const [provedor, b] of Object.entries(cont.porProvedor)) {
+        // Com `usage` em todos os pedidos, vale o número do provedor; senão a
+        // estimativa inteira, para não somar exato com chute.
+        const exato = b.exatos > 0 && b.exatos === b.pedidos;
+        const enviados = exato ? b.tokEnviados : Math.ceil(b.charsEnviados / 4);
+        const recebidos = exato ? b.tokRecebidos : Math.ceil(b.charsRecebidos / 4);
+        linhas.push({ provedor, pedidos: b.pedidos, enviados, recebidos, exato });
+        total.pedidos += b.pedidos; total.enviados += enviados; total.recebidos += recebidos;
+    }
+    return { linhas, total };
+}
+
+function fmtNumero(n) { return Number(n || 0).toLocaleString('pt-BR'); }
+
+// ── /copiar ──────────────────────────────────────────────────────────────
+
+/* Quem copia em cada sistema. No Linux há dois mundos (Wayland e X11) e três
+   programas; tenta na ordem e diz qual instalar se nenhum existir. */
+function copiadores(plataforma) {
+    if (plataforma === 'darwin') return [['pbcopy', []]];
+    if (plataforma === 'win32') return [['clip', []]];
+    return [['wl-copy', []], ['xclip', ['-selection', 'clipboard']], ['xsel', ['--clipboard', '--input']]];
+}
+
+function copiar(texto, { plataforma = process.platform, rodar = spawnSync } = {}) {
+    if (!texto) return { ok: false, error: 'ainda não há resposta para copiar' };
+    for (const [cmd, args] of copiadores(plataforma)) {
+        let r;
+        // O clip do Windows lê UTF-16 com BOM; em UTF-8 os acentos viram lixo.
+        const entrada = plataforma === 'win32' ? Buffer.concat([Buffer.from([0xff, 0xfe]), Buffer.from(texto, 'utf16le')]) : texto;
+        try { r = rodar(cmd, args, { input: entrada, timeout: 5000 }); } catch { continue; }
+        if (r && !r.error && r.status === 0) return { ok: true, via: cmd };
+    }
+    return {
+        ok: false,
+        error: plataforma === 'linux'
+            ? 'não achei wl-copy, xclip nem xsel — instale um (ex.: sudo apt install xclip)'
+            : 'a área de transferência não respondeu neste computador',
+    };
+}
+
+// ── /historico ───────────────────────────────────────────────────────────
+
+/* A busca é sem acento e sem caixa: quem procura "botao" quer achar "Botão". */
+const sem = (x) => String(x || '').normalize('NFD').replace(/[̀-ͯ]/g, '').toLowerCase();
+
+function buscarHistorico(arquivo, termo, limite = 20) {
+    let texto = '';
+    try { texto = fs.readFileSync(arquivo, 'utf8'); } catch { return []; }
+    const palavras = sem(termo).split(/\s+/).filter(Boolean);
+    const achados = [];
+    const linhas = texto.split('\n');
+    // Do fim para o começo: o mais recente é o que a pessoa quase sempre quer.
+    for (let i = linhas.length - 1; i >= 0 && achados.length < limite; i--) {
+        if (!linhas[i].trim()) continue;
+        let e;
+        try { e = JSON.parse(linhas[i]); } catch { continue; }
+        if (!e || !e.prompt) continue;
+        const alvo = sem(`${e.prompt} ${e.project || ''}`);
+        if (palavras.every((p) => alvo.includes(p))) achados.push(e);
+    }
+    return achados;
+}
+
+// ── /atalhos ─────────────────────────────────────────────────────────────
+
+/* Tirado do lib/entrada.js (a caixa de digitar) e do main() do CLI — não de
+   memória. Se uma tecla mudar lá, é aqui que tem de mudar também. */
+const ATALHOS = [
+    ['Enter', 'manda o pedido'],
+    ['Alt+Enter · Ctrl+J', 'quebra a linha sem mandar (ou \\ no fim da linha)'],
+    ['Esc Esc', 'para o agente no meio do trabalho'],
+    ['Esc', 'fecha o menu de comandos'],
+    ['!comando', 'roda direto no shell, sem passar pelo agente'],
+    ['@arquivo', 'anexa um arquivo do projeto só a este pedido'],
+    ['/', 'abre o menu de comandos'],
+    ['Tab · →', 'completa o comando sugerido'],
+    ['↑ ↓', 'pedidos anteriores (ou anda no menu, se aberto)'],
+    ['Ctrl+C', 'limpa o que foi digitado; com a caixa vazia, sai'],
+    ['Ctrl+D', 'sai (com a caixa vazia)'],
+    ['Ctrl+L', 'limpa a tela'],
+    ['Ctrl+A · Ctrl+E', 'vai para o começo · o fim da linha'],
+    ['Ctrl+U · Ctrl+K', 'apaga antes · depois do cursor'],
+    ['Ctrl+W', 'apaga a palavra antes do cursor'],
+];
+
+module.exports = {
+    fmtTamanho, quandoFoi, medirPasta, listarProjetos,
+    nomeDoNovo, pedidoDoNovo,
+    portasDoProjeto, sondarPorta, acharAlvoAbrir,
+    diagnosticar, versaoMinima, espacoLivre,
+    novoContador, instalarContador, resumoCusto, fmtNumero,
+    copiar, copiadores, buscarHistorico, ATALHOS,
+};

package/lib/comandos.js

@@ -0,0 +1,104 @@
+/**
+ * comandos.js — o pedido que a pessoa repete vira um comando dela.
+ *
+ * Quem pede "revisa o projeto e me explica os bugs sem jargão" toda semana
+ * não deveria digitar isso toda semana. Um arquivo `revisar.md` com o pedido
+ * dentro vira `/revisar`, e `/revisar o login` troca `$ARGUMENTOS` por
+ * "o login". É o mesmo desenho dos comandos do Claude Code.
+ *
+ * ── POR QUE NÃO É UMA SKILL ──────────────────────────────────────────────
+ * Skill entra sozinha quando o pedido casa com o `quando:` dela. Comando só
+ * entra quando a pessoa chama pelo nome. Um é conhecimento de fundo, o outro
+ * é um atalho de digitação — e misturar os dois faria um atalho disparar
+ * sem ninguém ter pedido.
+ *
+ * ── ONDE MORAM, E QUEM GANHA ─────────────────────────────────────────────
+ *   1. `comandos/` do pacote       — os três que vêm de fábrica ("primocode")
+ *   2. `~/.primocode/comandos/`    — os da pessoa, em qualquer projeto ("global")
+ *   3. `<projeto>/.primocode/comandos/` — os daquele projeto ("projeto")
+ * O mais perto do trabalho ganha: o do projeto sabe coisas do projeto que o
+ * global não sabe. E o de fábrica perde para qualquer um, para a pessoa poder
+ * reescrever o `/revisar` do jeito dela sem mexer no pacote.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { separar } = require('./skills.js');
+
+const PASTA_DO_PACOTE = path.join(__dirname, '..', 'comandos');
+// O nome vira `/nome` na caixa de digitar: sem espaço, sem acento estranho,
+// sem barra — senão o comando existe no disco e não há como digitá-lo.
+const NOME_VALIDO = /^[a-z0-9][a-z0-9_-]*$/;
+
+/** Um arquivo .md → { nome, descricao, corpo, arquivo }. */
+function ler(arquivo) {
+    const { cabecalho, corpo } = separar(fs.readFileSync(arquivo, 'utf-8'));
+    return {
+        nome: path.basename(arquivo, '.md').toLowerCase(),
+        descricao: cabecalho.descricao || cabecalho.description || '',
+        corpo,
+        arquivo,
+    };
+}
+
+function daPasta(pasta, origem) {
+    let nomes = [];
+    try { nomes = fs.readdirSync(pasta); } catch { return []; }   // pasta que não existe é lista vazia
+    const fora = [];
+    for (const n of nomes.filter((x) => x.endsWith('.md')).sort()) {
+        try {
+            const c = ler(path.join(pasta, n));
+            if (NOME_VALIDO.test(c.nome) && c.corpo) fora.push({ ...c, origem });
+        } catch { /* um arquivo ilegível não derruba os outros */ }
+    }
+    return fora;
+}
+
+/** A lista final, um por nome, já com a precedência aplicada. */
+function carregar({ projectDir, home = os.homedir(), pastaDoPacote = PASTA_DO_PACOTE } = {}) {
+    const porNome = new Map();
+    // Em ordem crescente de prioridade: quem vem depois sobrescreve.
+    const camadas = [
+        [pastaDoPacote, 'primocode'],
+        [path.join(home, '.primocode', 'comandos'), 'global'],
+    ];
+    if (projectDir) camadas.push([path.join(projectDir, '.primocode', 'comandos'), 'projeto']);
+    for (const [pasta, origem] of camadas) {
+        for (const c of daPasta(pasta, origem)) porNome.set(c.nome, c);
+    }
+    return [...porNome.values()].sort((a, b) => a.nome.localeCompare(b.nome));
+}
+
+/** O prompt que vai ao agente. */
+function expandir(comando, argumentos) {
+    const args = String(argumentos || '').trim();
+    const corpo = comando.corpo;
+    if (corpo.includes('$ARGUMENTOS')) return corpo.split('$ARGUMENTOS').join(args).trim();
+    // Sem a marca, o que foi digitado não pode sumir: vai no fim.
+    return args ? `${corpo}\n\n${args}` : corpo;
+}
+
+/** Cria ~/.primocode/comandos/<nome>.md com um esqueleto. Devolve o caminho. */
+function criar(nome, { home = os.homedir() } = {}) {
+    const n = String(nome || '').trim().toLowerCase().replace(/^\//, '');
+    if (!NOME_VALIDO.test(n)) return { ok: false, error: 'Nome só com letras minúsculas, números, - e _.' };
+    const pasta = path.join(home, '.primocode', 'comandos');
+    const arquivo = path.join(pasta, n + '.md');
+    if (fs.existsSync(arquivo)) return { ok: false, error: `Já existe: ${arquivo}`, arquivo };
+    fs.mkdirSync(pasta, { recursive: true });
+    fs.writeFileSync(arquivo, [
+        '---',
+        `descricao: o que o /${n} faz, numa linha`,
+        '---',
+        'Escreva aqui o pedido, do jeito que você digitaria.',
+        '',
+        'O que vier depois do comando entra no lugar desta palavra: $ARGUMENTOS',
+        '',
+    ].join('\n'));
+    return { ok: true, arquivo };
+}
+
+module.exports = { PASTA_DO_PACOTE, NOME_VALIDO, ler, carregar, expandir, criar };