@fontdata/ai-harness 3.3.1 → 4.0.0

package/.claude-plugin/marketplace.json

@@ -11,7 +11,7 @@
     {
       "name": "fontdata",
       "source": "./",
-      "description": "19 slash commands para conduzir spec, contexto, harness, revisão e manutenção de projetos com Claude Code."
+      "description": "20 slash commands para conduzir spec, contexto, harness, revisão e manutenção de projetos com Claude Code."
     }
   ]
 }

package/.claude-plugin/plugin.json

@@ -1,8 +1,8 @@
 {
   "name": "fontdata",
-  "version": "3.3.1",
+  "version": "4.0.0",
   "mcpServers": {
-    "banco_dados": { "command": "npx", "args": ["-y", "@fontdata/ai-harness@3.3.1", "banco-dados-mcp"] }
+    "banco_dados": { "command": "npx", "args": ["-y", "@fontdata/ai-harness@4.0.0", "banco-dados-mcp"] }
   },
   "description": "Harness de engenharia com IA da Fontdata para Claude Code",
   "author": { "name": "Fontdata" },

package/README.md

@@ -32,7 +32,7 @@ carregado como plugin **só daquela sessão** — nenhum arquivo do harness é e
 # npm / npx
 npx @fontdata/ai-harness harness
 npx @fontdata/ai-harness resolver-bug "login 500 no refresh token"
-npx @fontdata/ai-harness versao minor
+npx @fontdata/ai-harness run versao minor
 
 # yarn
 yarn dlx @fontdata/ai-harness harness
@@ -41,7 +41,7 @@ yarn dlx @fontdata/ai-harness harness
 pnpm dlx @fontdata/ai-harness harness
 ```
 
-Durante a sessão, todos os 19 comandos ficam disponíveis com o prefixo do plugin — `/fontdata:nova-tarefa`,
+Durante a sessão, todos os 20 comandos ficam disponíveis com o prefixo do plugin — `/fontdata:nova-tarefa`,
 `/fontdata:resolver-bug` etc. —, junto com os hooks e os agents do harness.
 É isso que faz o `/harness`, que encadeia 4 comandos, funcionar sem instalação prévia.
 
@@ -167,8 +167,27 @@ projeto, cadastro, limites do filtro, produção, mascaramento e dúvidas freque
 | `banco-dados <subcomando>` | Conexões de banco somente leitura: `adicionar`, `listar`, `testar`, `usar`, `remover` |
 | `banco-dados-mcp` | Servidor MCP de leitura do banco, iniciado pelo Claude Code |
 | `comentarios [caminho]` | Instala o hook do padrão de comentários com a catraca do legado (`--yes`) |
+| `versao detectar\|calcular\|aplicar` | Fontes de versão do projeto, próxima versão e gravação nos arquivos (veja abaixo) |
 | `list` | Lista o catálogo |
 
+### Subcomando `versao`
+
+`npx @fontdata/ai-harness versao detectar|calcular|aplicar` é a parte determinística do `/versao`, para qualquer
+stack. Não faz commit, tag nem push.
+
+- `detectar` lista as fontes da versão (arquivo, extrator, linha e valor), o modelo da tag e as divergências.
+- `calcular` infere o próximo bump pelos commits desde a última tag (nunca major) ou aplica `major|minor|patch|build`.
+- `aplicar <versao>` grava a versão em todas as fontes; com `--dry-run` só mostra o diff.
+- `--json` devolve a saída para máquinas (é o que o `/versao` e o `/publicar-release` leem); `--app <nome>` escolhe
+  o app num monorepo.
+
+Onde a versão mora, o modelo da tag (`v{versao}`, `{app}-v{versao}`…), os segmentos, os changelogs, o que nunca
+tocar e o comando de validação ficam no `.ai-harness/versao.json`, opcional e versionado. Sem ele, a CLI detecta as
+fontes por stack e propõe o arquivo. O formato está em [`docs/contratos/VERSAO.md`](docs/contratos/VERSAO.md).
+
+Para abrir o fluxo `/versao` no Claude Code, use `npx @fontdata/ai-harness run versao minor`: `versao` é subcomando
+do CLI.
+
 ## Modelo de arquivos
 
 | Arquivo | Papel |
@@ -247,6 +266,7 @@ também acionado pelo modelo quando o pedido combina.
 ### Utilitário
 - `/git-commit-push` ⭐ — gera a mensagem (PT-BR, Conventional Commits) e faz add, commit e push
 - `/versao` ⭐ — detecta o versionamento da stack e aplica bump e changelog, com aprovação e sem push
+- `/publicar-release` — depois do `/versao`, cria a tag (exceto com auto-tag), faz o push após confirmação e cria o GitHub Release
 - `/revisar-pr` — revisa um PR ou o diff atual, classifica os achados e, se pedido, organiza as correções num trabalho
 
 ### Setup guiado

package/dist/cli.js

@@ -20,6 +20,7 @@ const RESERVED = new Set([
     'memoria',
     'banco-dados',
     'banco-dados-mcp',
+    'versao',
     'list',
     'run',
     'help',
@@ -66,6 +67,7 @@ Gerenciar:
                     --antes-de <dias> muda o corte; --remover apaga do disco os que o git recupera
   banco-dados <subcomando>  Conexões de banco somente leitura: adicionar, listar, testar, usar, remover
   banco-dados-mcp   Servidor MCP de leitura do banco, usado pelo Claude Code (stdio)
+  versao detectar|calcular|aplicar  Fontes de versão, próxima versão e gravação (--app, --json; aplicar --dry-run)
   list            Lista todos os comandos disponíveis no catálogo
 
 Init sem perguntas (CI):
@@ -177,6 +179,10 @@ async function main() {
         const { runUpdateCommand } = await import('./update/update.js');
         process.exit(runUpdateCommand(argv.slice(1)));
     }
+    if (cmd === 'versao') {
+        const { runVersaoCommand } = await import('./versao/command.js');
+        process.exit(runVersaoCommand(argv.slice(1)));
+    }
     if (cmd === 'run') {
         const id = argv[1];
         if (!id) {

package/dist/doctor/checks.js

@@ -9,6 +9,7 @@ import { CONFIG_PATH, readConfig } from '../config/config.js';
 import { ARCHIVE_DIR_NAME, ARTIFACT_TYPES, listWorkFiles, readArtifact, validateAllWorks, WORKS_DIR } from '../contratos/artefatos.js';
 import { validateEventLog } from '../contratos/eventos.js';
 import { hashContent, LOCK_PATH, LOCK_VERSION } from '../install/lock.js';
+import { itemSources } from '../install/plan.js';
 import { SETTINGS_PATH } from '../install/settings.js';
 import { planArchive } from '../trabalhos/arquivar.js';
 import { ARCHIVE_DEFAULT_DAYS } from '../trabalhos/command.js';
@@ -102,7 +103,9 @@ function checkLock(root) {
 }
 function checkFiles(root, lock) {
     const findings = [];
+    const catalog = loadCatalog();
     for (const item of lock.itens) {
+        const sourceByPath = new Map((itemSources(catalog, item.tipo, item.id) ?? []).map((entry) => [entry.path, entry.source]));
         for (const entry of item.arquivos) {
             const file = join(root, entry.caminho);
             if (!existsSync(file)) {
@@ -120,6 +123,15 @@ function checkFiles(root, lock) {
                     mensagem: `Arquivo alterado localmente desde a instalação: ${entry.caminho}.`,
                     correcao: 'Se a alteração é intencional, mantenha: atualizações não sobrescrevem arquivos alterados sem confirmação.',
                 });
+                const source = sourceByPath.get(entry.caminho);
+                if (source && existsSync(source) && hashContent(readFileSync(source)) !== entry.sha256) {
+                    findings.push({
+                        id: 'comando-customizado-defasado',
+                        severidade: 'aviso',
+                        mensagem: `Arquivo customizado preso numa versão antiga do template, que mudou desde a instalação: ${entry.caminho}.`,
+                        correcao: `Compare ${entry.caminho} com o template atual do pacote; se não houver customização a manter, rode \`npx @fontdata/ai-harness update --forcar\`.`,
+                    });
+                }
             }
         }
     }

package/dist/update/update.js

@@ -103,7 +103,9 @@ export function checkUpdate(root, catalog = loadCatalog(), legacy, home, { semBa
         for (const { path, source } of sources) {
             if (trackedPaths.has(path))
                 continue;
-            changes.push({ tipo: existsSync(join(root, path)) ? 'conflito' : 'novo', caminho: path, item: key, source });
+            const target = join(root, path);
+            const same = existsSync(target) && hashContent(readFileSync(target)) === hashContent(readFileSync(source));
+            changes.push({ tipo: !existsSync(target) || same ? 'novo' : 'conflito', caminho: path, item: key, source });
         }
     }
     // Itens que o lock não tem. Arquivo igual ao do pacote só entra no lock; `protect` mantém o do projeto mesmo com --forcar.

package/dist/versao/command.js

@@ -0,0 +1,424 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { EOL } from 'node:os';
+import { join } from 'node:path';
+import { suggestFlag } from '../install/flags.js';
+import { acharRaiz } from '../raiz.js';
+import { carregarVersaoConfig } from './config.js';
+import { detectarFontes, extratorParaTexto } from './detectar.js';
+import { diffLinhas } from './diff.js';
+import { criarExtrator } from './extratores/index.js';
+import { formatarVersao, incrementar, parseVersao } from './formato.js';
+import { acharTagBase, classificarBump, listarCommits } from './git.js';
+const SUBCOMANDOS = ['detectar', 'calcular', 'aplicar'];
+const INCREMENTOS = ['major', 'minor', 'patch', 'build'];
+const STATUS_IGNORADA = 'ignorada (naoTocar)';
+const STATUS_CHANGELOG = 'changelog, gravado pelo /versao';
+function parseOpcoes(sub, argv) {
+    const booleanas = sub === 'aplicar' ? ['--json', '--dry-run'] : ['--json'];
+    const opcoes = { json: false, dryRun: false, posicionais: [] };
+    for (let i = 0; i < argv.length; i++) {
+        const token = argv[i];
+        if (token === '--app') {
+            const valor = argv[++i];
+            if (valor === undefined || valor.startsWith('--'))
+                throw new Error('--app precisa do nome do app.');
+            opcoes.app = valor;
+        }
+        else if (booleanas.includes(token)) {
+            if (token === '--json')
+                opcoes.json = true;
+            else
+                opcoes.dryRun = true;
+        }
+        else if (token.startsWith('--')) {
+            const sugestao = suggestFlag(token, ['--app', ...booleanas]);
+            throw new Error(`Flag desconhecida: ${token}.${sugestao ? ` Você quis dizer ${sugestao}?` : ''}`);
+        }
+        else {
+            opcoes.posicionais.push(token);
+        }
+    }
+    const maximo = sub === 'detectar' ? 0 : 1;
+    if (opcoes.posicionais.length > maximo)
+        throw new Error(`Argumento inesperado: ${opcoes.posicionais[maximo]}`);
+    if (sub === 'aplicar' && opcoes.posicionais.length === 0)
+        throw new Error('Informe a versão: versao aplicar <versao> [--dry-run].');
+    return opcoes;
+}
+function normalizarCaminho(caminho) {
+    return caminho.replaceAll('\\', '/').replace(/^\.\//, '').replace(/\/+$/, '');
+}
+/** Entrada de `naoTocar` que é caminho bloqueia o arquivo; nome de campo bloqueia o `json:` que termina nele. */
+function bloqueada(fonte, naoTocar) {
+    const caminho = normalizarCaminho(fonte.caminho);
+    return naoTocar.some((entrada) => {
+        if (normalizarCaminho(entrada) === caminho)
+            return true;
+        if (fonte.extrator.tipo !== 'json')
+            return false;
+        const campo = entrada.split('.');
+        return campo.length <= fonte.extrator.caminho.length && fonte.extrator.caminho.slice(-campo.length).join('\u0000') === campo.join('\u0000');
+    });
+}
+function fonteJson(fonte, naoTocar) {
+    return {
+        caminho: fonte.caminho,
+        extrator: extratorParaTexto(fonte.extrator),
+        formato: fonte.formato ?? null,
+        valores: [...new Set(fonte.ocorrencias.map((o) => o.valor))],
+        ocorrencias: fonte.ocorrencias.map((o) => ({ linha: o.linha, valor: o.valor, grupo: o.grupo ?? null })),
+        somenteLeitura: fonte.extrator.tipo === 'versoes-txt',
+        naoTocar: bloqueada(fonte, naoTocar),
+    };
+}
+function mensagemSemFonte(d) {
+    const apps = Object.keys(d.apps);
+    if (d.app === null && apps.length > 0) {
+        return `nenhuma fonte de versão na raiz; informe --app <nome> (apps: ${apps.join(', ')})`;
+    }
+    return d.origem === 'config'
+        ? 'nenhuma fonte de versão no .ai-harness/versao.json; declare os arquivos em "arquivos" (ou nos apps)'
+        : 'nenhuma fonte de versão detectada; crie o .ai-harness/versao.json declarando os arquivos (docs/contratos/VERSAO.md)';
+}
+function exigirFontes(d) {
+    if (d.fontes.length === 0)
+        throw new Error(mensagemSemFonte(d));
+}
+function tentarParse(texto, formato) {
+    try {
+        return parseVersao(texto, formato);
+    }
+    catch {
+        return null;
+    }
+}
+function segmentosDe(texto, formato) {
+    const comFormato = formato ? tentarParse(texto, formato) : null;
+    if (comFormato)
+        return comFormato;
+    if (/^\d+(?:\.\d+)*$/.test(texto))
+        return parseVersao(texto);
+    throw new Error(`versão inválida: "${texto}"; use números separados por ponto${formato ? ` ou o formato ${formato}` : ''}`);
+}
+function comparar(a, b) {
+    for (let i = 0; i < Math.max(a.length, b.length); i++) {
+        const d = (a[i] ?? 0) - (b[i] ?? 0);
+        if (d !== 0)
+            return d;
+    }
+    return 0;
+}
+function tentarBase(raiz, d) {
+    if (d.tag.includes('{app}') && d.app === null)
+        return null;
+    try {
+        return acharTagBase(raiz, d.tag, d.app ?? undefined);
+    }
+    catch {
+        return null;
+    }
+}
+function baseJson(base) {
+    return base ? { tag: base.tag, versao: base.versao, ref: base.base, primeiroRelease: base.primeiroRelease } : null;
+}
+function montarTag(modelo, versao, app) {
+    if (versao === null || (modelo.includes('{app}') && app === null))
+        return null;
+    return modelo.replaceAll('{versao}', versao).replaceAll('{app}', app ?? '');
+}
+function detectar({ raiz, deteccao: d, config }) {
+    const naoTocar = config?.naoTocar ?? [];
+    const problemas = [...d.problemas];
+    if (d.fontes.length === 0)
+        problemas.unshift(mensagemSemFonte(d));
+    return {
+        ok: true,
+        comando: 'detectar',
+        raiz,
+        origem: d.origem,
+        app: d.app,
+        versaoAtual: d.versaoAtual,
+        tag: d.tag,
+        base: baseJson(tentarBase(raiz, d)),
+        segmentos: d.segmentos,
+        formato: d.formato,
+        fontes: d.fontes.map((f) => fonteJson(f, naoTocar)),
+        divergencias: d.divergencias,
+        apps: Object.fromEntries(Object.entries(d.apps).map(([nome, a]) => [
+            nome,
+            { caminhos: a.caminhos, versaoAtual: a.versaoAtual, tag: a.tag, fontes: a.fontes.map((f) => fonteJson(f, naoTocar)), divergencias: a.divergencias },
+        ])),
+        naoTocar,
+        problemas,
+        versaoJson: d.versaoJson,
+    };
+}
+function calcular({ raiz, deteccao: d, config, opcoes }) {
+    exigirFontes(d);
+    if (d.versaoAtual === null) {
+        throw new Error(`versão atual não encontrada nas fontes${d.problemas.length ? `:${EOL}- ${d.problemas.join(`${EOL}- `)}` : ''}`);
+    }
+    const formato = d.formato ?? undefined;
+    const atual = segmentosDe(d.versaoAtual, formato);
+    const caminhos = d.app !== null ? (d.apps[d.app]?.caminhos ?? null) : null;
+    const avisos = [];
+    let base = null;
+    let commits = [];
+    let erroGit = null;
+    try {
+        base = acharTagBase(raiz, d.tag, d.app ?? undefined);
+        commits = listarCommits(raiz, base.base, caminhos ?? undefined, base.primeiroRelease);
+    }
+    catch (erro) {
+        erroGit = erro.message;
+    }
+    const argumento = opcoes.posicionais[0];
+    let bump = null;
+    let proximos = null;
+    if (argumento !== undefined) {
+        if (INCREMENTOS.includes(argumento))
+            bump = { tipo: argumento, origem: 'argumento' };
+        else {
+            proximos = segmentosDe(argumento, formato);
+            bump = { tipo: 'versao', origem: 'argumento' };
+        }
+    }
+    else if (config && config.bump.padrao !== 'auto') {
+        bump = { tipo: config.bump.padrao, origem: 'config' };
+    }
+    else {
+        if (erroGit !== null)
+            throw new Error(`não foi possível ler os commits para inferir o bump: ${erroGit}`);
+        const inferido = classificarBump(commits);
+        avisos.push(...inferido.avisos);
+        if (inferido.tipo === 'nenhum') {
+            const desde = base?.tag ?? 'o primeiro commit';
+            avisos.push(`nenhum commit com tipo semântico (feat, fix, chore...) desde ${desde}${caminhos ? ` em ${caminhos.join(', ')}` : ''}; ` +
+                'nada a versionar. Informe o bump (major|minor|patch|build) ou a versão.');
+        }
+        else
+            bump = { tipo: inferido.tipo, origem: 'inferido' };
+    }
+    if (erroGit !== null)
+        avisos.push(`commits não lidos: ${erroGit}`);
+    if (bump && bump.tipo !== 'versao') {
+        proximos = incrementar(atual, bump.tipo);
+        while (d.segmentos !== null && proximos.length < d.segmentos)
+            proximos.push(0);
+    }
+    let proxima = null;
+    if (proximos) {
+        proxima = formato ? formatarVersao(proximos, formato) : bump?.tipo === 'versao' ? argumento : formatarVersao(proximos);
+        if (comparar(proximos, atual) <= 0)
+            avisos.push(`a próxima versão ${proxima} não é maior que a atual ${d.versaoAtual}`);
+    }
+    return {
+        ok: true,
+        comando: 'calcular',
+        raiz,
+        app: d.app,
+        versaoAtual: d.versaoAtual,
+        proxima,
+        tag: d.tag,
+        tagProxima: montarTag(d.tag, proxima, d.app),
+        bump,
+        base: baseJson(base),
+        caminhos,
+        commits,
+        divergencias: d.divergencias,
+        avisos,
+        problemas: d.problemas,
+    };
+}
+function textoParaFonte(fonte, segmentos, versao, formatoRaiz) {
+    if (fonte.extrator.tipo === 'dproj')
+        return formatarVersao(segmentos);
+    const formato = fonte.formato ?? fonte.padding?.map((p) => `{${p}}`).join('.') ?? formatoRaiz ?? undefined;
+    return formato ? formatarVersao(segmentos, formato) : versao;
+}
+function statusDoArquivo(fontes, mudou) {
+    if (mudou)
+        return 'alterado';
+    if (fontes.every((f) => f.status === STATUS_IGNORADA))
+        return 'ignorado (naoTocar)';
+    if (fontes.every((f) => f.status === STATUS_CHANGELOG || f.status === STATUS_IGNORADA))
+        return STATUS_CHANGELOG;
+    return 'sem alteração';
+}
+function aplicar({ raiz, deteccao: d, config, opcoes }) {
+    exigirFontes(d);
+    const versao = opcoes.posicionais[0];
+    const segmentos = segmentosDe(versao, d.formato ?? undefined);
+    const naoTocar = config?.naoTocar ?? [];
+    const porArquivo = new Map();
+    for (const f of d.fontes)
+        porArquivo.set(f.caminho, [...(porArquivo.get(f.caminho) ?? []), f]);
+    const erros = [];
+    const planos = [];
+    for (const [caminho, fontes] of porArquivo) {
+        const absoluto = join(raiz, caminho);
+        const original = existsSync(absoluto) ? readFileSync(absoluto) : null;
+        let atual = original;
+        const aplicadas = [];
+        for (const fonte of fontes) {
+            const extrator = extratorParaTexto(fonte.extrator);
+            if (bloqueada(fonte, naoTocar)) {
+                aplicadas.push({ extrator, status: STATUS_IGNORADA });
+                continue;
+            }
+            if (fonte.extrator.tipo === 'versoes-txt') {
+                aplicadas.push({ extrator, status: STATUS_CHANGELOG });
+                continue;
+            }
+            try {
+                if (atual === null)
+                    throw new Error('arquivo não encontrado');
+                const texto = textoParaFonte(fonte, segmentos, versao, d.formato);
+                const novo = criarExtrator(fonte.extrator).gravar(caminho, atual, texto);
+                aplicadas.push({ extrator, status: novo.equals(atual) ? 'sem alteração' : 'alterada', versao: texto });
+                atual = novo;
+            }
+            catch (erro) {
+                const mensagem = erro.message;
+                erros.push(`${caminho} (${extrator}): ${mensagem}`);
+                aplicadas.push({ extrator, status: 'erro', mensagem });
+            }
+        }
+        const mudou = original !== null && atual !== null && !atual.equals(original);
+        planos.push({
+            arquivo: { caminho, status: statusDoArquivo(aplicadas, mudou), gravado: false, fontes: aplicadas, diff: mudou ? diffLinhas(original, atual) : [] },
+            novo: mudou ? atual : null,
+        });
+    }
+    if (erros.length > 0)
+        throw new Error(`nada foi gravado:${EOL}- ${erros.join(`${EOL}- `)}`);
+    if (!opcoes.dryRun) {
+        for (const plano of planos) {
+            if (!plano.novo)
+                continue;
+            writeFileSync(join(raiz, plano.arquivo.caminho), plano.novo);
+            plano.arquivo.gravado = true;
+        }
+    }
+    return {
+        ok: true,
+        comando: 'aplicar',
+        raiz,
+        app: d.app,
+        versao,
+        dryRun: opcoes.dryRun,
+        arquivos: planos.map((p) => p.arquivo),
+        divergencias: d.divergencias,
+        problemas: d.problemas,
+    };
+}
+function linhasDeFonte(f) {
+    const marcas = [f.somenteLeitura ? 'só leitura' : '', f.naoTocar ? 'naoTocar' : ''].filter(Boolean);
+    return `  ${f.caminho} (${f.extrator}): ${f.valores.join(', ') || '—'}${marcas.length ? ` [${marcas.join(', ')}]` : ''}`;
+}
+function linhasDeLista(titulo, itens) {
+    return itens.length ? [`${titulo}:`, ...itens.map((i) => `  - ${i}`)] : [];
+}
+function divergenciasTexto(divergencias) {
+    return linhasDeLista('Divergências', divergencias.map((d) => d.mensagem));
+}
+function textoDetectar(s) {
+    const base = s.base ? ` (base: ${s.base.tag ?? 'nenhuma tag; primeiro release'})` : '';
+    const linhas = [
+        `Raiz: ${s.raiz}`,
+        `Origem: ${s.origem === 'config' ? '.ai-harness/versao.json' : 'detecção por stack (sem .ai-harness/versao.json)'}`,
+        ...(s.app ? [`App: ${s.app}`] : []),
+        `Versão atual: ${s.versaoAtual ?? '—'}`,
+        `Tag: ${s.tag}${base}`,
+    ];
+    if (s.fontes.length)
+        linhas.push('Fontes:', ...s.fontes.map(linhasDeFonte));
+    for (const [nome, a] of Object.entries(s.apps)) {
+        linhas.push(`App ${nome} (${a.caminhos.join(', ')}): versão ${a.versaoAtual ?? '—'}, tag ${a.tag}`, ...a.fontes.map((f) => `  ${linhasDeFonte(f)}`));
+    }
+    linhas.push(...divergenciasTexto(s.divergencias), ...linhasDeLista('Problemas', s.problemas));
+    if (s.versaoJson)
+        linhas.push('versao.json proposto (.ai-harness/versao.json):', JSON.stringify(s.versaoJson, null, 2));
+    return linhas.join(EOL);
+}
+function textoCalcular(s) {
+    const bump = s.bump ? `${s.bump.tipo} (${s.bump.origem})` : 'nenhum';
+    const base = s.base ? (s.base.tag ?? `primeiro release (desde ${s.base.ref.slice(0, 7)})`) : '—';
+    return [
+        ...(s.app ? [`App: ${s.app}`] : []),
+        `Versão atual: ${s.versaoAtual}`,
+        `Base: ${base}`,
+        `Commits considerados (${s.commits.length})${s.caminhos ? ` em ${s.caminhos.join(', ')}` : ''}:`,
+        ...s.commits.map((c) => `  ${c.hash.slice(0, 7)} ${c.titulo}`),
+        `Bump: ${bump}`,
+        `Próxima versão: ${s.proxima ?? '— (nada a versionar)'}${s.tagProxima ? ` (tag ${s.tagProxima})` : ''}`,
+        ...divergenciasTexto(s.divergencias),
+        ...linhasDeLista('Avisos', s.avisos),
+        ...linhasDeLista('Problemas', s.problemas),
+    ].join(EOL);
+}
+function textoAplicar(s) {
+    const linhas = [`Versão ${s.versao}${s.dryRun ? ' (simulação: nada foi gravado)' : ''}`];
+    for (const a of s.arquivos) {
+        linhas.push(`${a.caminho}: ${a.status}${a.gravado ? ', gravado' : ''}`);
+        for (const f of a.fontes)
+            if (f.status === STATUS_IGNORADA && a.status !== 'ignorado (naoTocar)')
+                linhas.push(`  ${f.extrator}: ${f.status}`);
+        for (const d of a.diff) {
+            if (d.antes !== null)
+                linhas.push(`  - ${d.linha}: ${d.antes}`);
+            if (d.depois !== null)
+                linhas.push(`  + ${d.linha}: ${d.depois}`);
+        }
+    }
+    linhas.push(...divergenciasTexto(s.divergencias), ...linhasDeLista('Problemas', s.problemas));
+    return linhas.join(EOL);
+}
+function erroDeUso(argv) {
+    const sub = argv[0];
+    return [
+        sub === undefined ? 'Informe o subcomando do versao.' : `Subcomando desconhecido: versao ${sub}.`,
+        'Uso: versao detectar|calcular|aplicar [--app <nome>] [--json] (aplicar aceita --dry-run).',
+        `Para abrir o /versao no Claude Code, use: npx @fontdata/ai-harness run versao${argv.length ? ` ${argv.join(' ')}` : ''}`,
+    ].join(EOL);
+}
+/** `versao detectar|calcular|aplicar`; devolve o código de saída. Não faz commit, tag nem push. */
+export function runVersaoCommand(argv) {
+    const sub = argv[0];
+    if (!SUBCOMANDOS.includes(sub)) {
+        console.error(erroDeUso(argv));
+        return 1;
+    }
+    const subcomando = sub;
+    const json = argv.includes('--json');
+    try {
+        const opcoes = parseOpcoes(subcomando, argv.slice(1));
+        const raiz = acharRaiz();
+        const config = carregarVersaoConfig(raiz);
+        const contexto = { raiz, config, deteccao: detectarFontes(raiz, config, opcoes.app), opcoes };
+        let saida;
+        let texto;
+        if (subcomando === 'detectar') {
+            const s = detectar(contexto);
+            [saida, texto] = [s, textoDetectar(s)];
+        }
+        else if (subcomando === 'calcular') {
+            const s = calcular(contexto);
+            [saida, texto] = [s, textoCalcular(s)];
+        }
+        else {
+            const s = aplicar(contexto);
+            [saida, texto] = [s, textoAplicar(s)];
+        }
+        console.log(json ? JSON.stringify(saida, null, 2) : texto);
+        return 0;
+    }
+    catch (erro) {
+        const mensagem = erro instanceof Error ? erro.message : String(erro);
+        if (json)
+            console.log(JSON.stringify({ ok: false, comando: subcomando, erro: mensagem }, null, 2));
+        else
+            console.error(mensagem);
+        return 1;
+    }
+}