Versioner

CLI que substitui o fluxo manual de release por um único comando.

Antes:

# edita package.json
# edita app.json
git add .
git commit -m "v1.4.273 - Corrige login"
git push

Depois:

versioner build "Corrige login"

Sem dependências externas. Só Node.js e Git.

Instalação

Sem instalar:

npx @kinetnode/versioner init

Global:

npm install -g @kinetnode/versioner

Requer Node.js 18 ou superior.

Início rápido

cd meu-projeto
npx @kinetnode/versioner init
npx versioner build "primeira release"

O init cria dois arquivos, detecta o package.json e o app.json, pergunta a versão inicial, e já atualiza todos os arquivos configurados com essa versão. Se o diretório for um repositório Git, ele pergunta a mensagem do commit inicial — pressione Enter para usar Initial commit como padrão, ou escreva uma mensagem personalizada. Para cancelar o commit, responda n.

Se estiver usando como dependência do projeto, adicione atalhos no package.json:

{
    "scripts": {
        "build": "versioner build",
        "minor": "versioner minor",
        "major": "versioner major"
    }
}

E use:

npm run build -- "Corrige login"

Modelo de versionamento

Formato:

major.minor.build

Exemplo: 2.14.583

Build

Incrementa em toda release e nunca volta para zero. Representa o total de releases já publicadas.

2.14.583 → 2.14.584 → 2.14.585

Minor

Pequenas evoluções dentro de uma mesma versão principal. Zera quando ocorre um Major.

2.14.583 → 2.15.584

Major

Grandes marcos: primeira versão pública, reescrita, nova arquitetura. Definido manualmente.

2.14.583 → 3.0.584

O Build continua incrementando normalmente mesmo em um Major.

Por que não SemVer (padrão)

O SemVer descreve compatibilidade de API. Este modelo descreve o histórico do projeto: quantas grandes versões existiram, quantas evoluções cada uma recebeu e quantas releases foram publicadas desde o início.

O formato continua compatível com x.y.z, então o package.json permanece válido.

Se preferir o comportamento SemVer, ative semver: true no versioner.config.json — veja a seção SemVer.

Comandos

| Comando | O que faz | |---|---| | versioner init | Inicializa o Versioner no projeto | | versioner build "msg" | Incrementa a Build e publica a release | | versioner minor "msg" | Incrementa Minor e Build | | versioner major "msg" | Incrementa Major, zera Minor, incrementa Build | | versioner log | Lista os commits recentes do repositório | | versioner sync | Sincroniza a versão atual para todos os arquivos configurados | | versioner changelog | Gera ou atualiza o CHANGELOG.md com commits desde a última tag | | versioner version | Mostra a versão atual | | versioner status | Mostra versão, arquivos monitorados e estado do Git | | versioner pull | Atualiza o repositório local com as mudanças do remoto | | versioner merge <branch> | Faz merge de um branch no branch atual | | versioner help [comando] | Ajuda |

Aliases: b, m, M, i, lg, sy, cl, v, s, p, h.

Flags de release

| Flag | Efeito | |---|---| | --no-push | Faz commit mas não envia para o remoto | | --force-push | Envia com git push --force (use após um reset manual) | | --no-git | Só versiona os arquivos, não toca no Git | | --no-version | Executa o fluxo Git sem incrementar a versão | | --tag | Cria uma tag Git para a release | | --no-tag | Desativa a tag mesmo se ligada na config | | --dry-run | Simula tudo sem gravar nada | | --changelog | Gera CHANGELOG.md antes do commit (ativa para esta execução) | | --changelog=false | Desativa changelog automático para esta execução | | --addAll=false | Usa somente os arquivos especificados no comando |

Flags têm precedência sobre a configuração (FLAG > CONFIG > DEFAULT) e afetam apenas a execução atual — o versioner.config.json não é alterado.

Flags do init

| Flag | Efeito | |---|---| | --yes, -y | Usa os padrões sem perguntar | | --force, -f | Sobrescreve arquivos existentes |

Flags do pull

| Flag | Efeito | |---|---| | --merge | Usa merge em vez de rebase (padrão é rebase) |

SemVer

Para projetos que seguem o Versionamento Semântico, ative o modo SemVer no versioner.config.json:

{
    "semver": true
}

Com semver: true, o comportamento de cada comando muda:

| Versão atual | Comando | Resultado | |---|---|---| | 1.2.5 | build | 1.2.6 (patch++) | | 1.2.5 | minor | 1.3.0 (minor++, patch vira 0) | | 1.2.5 | major | 2.0.0 (major++, minor e patch viram 0) |

Comparação com o comportamento padrão (sem SemVer):

| Versão atual | Comando | Padrão | SemVer | |---|---|---|---| | 1.2.5 | minor | 1.3.6 | 1.3.0 | | 1.2.5 | major | 2.0.6 | 2.0.0 |

No padrão, o build é um contador global que nunca zera — ele representa o total de releases já feitas. No SemVer, o patch reinicia a cada minor ou major, seguindo a convenção da comunidade.

Add por arquivo

Por padrão, o Versioner executa git add . antes de cada commit, incluindo todas as mudanças do repositório. Para controlar quais arquivos entram no commit, configure addAll: false:

{
    "git": {
        "addAll": false
    }
}

Com addAll: false, a sintaxe muda: o primeiro argumento é a lista de arquivos (separados por espaço), e o segundo é a mensagem do commit.

versioner build "src/login.js" "Corrige autenticação"
versioner minor "src/auth.js src/session.js" "Adiciona refresh token"

Os arquivos de versão (.versioner.json, package.json etc.) são sempre incluídos automaticamente, independente do que você especificar. Arquivos não listados permanecem no working tree sem serem commitados.

--no-version

Executa o fluxo completo do Git sem incrementar a versão. Útil para commits de documentação, configuração ou qualquer mudança que não justifique uma nova versão:

versioner build --no-version "README.md" "Atualiza documentação"
versioner build --no-version "Corrige CI"

Com --no-version:

• A versão permanece igual em todos os arquivos
• O Git ainda faz add, commit e push normalmente
• O template de commit usa a versão atual (sem incremento)

Comportamento com addAll:

| Config | --no-version | Resultado | |---|---|---| | addAll: true | sim | git add . inclui qualquer arquivo modificado | | addAll: false | sim | Apenas os arquivos especificados são commitados |

Changelog automático

O changelog pode ser gerado automaticamente durante o build, minor ou major, ou executado manualmente a qualquer momento.

Configuração automática

{
    "changelog": true
}

Com changelog: true, o CHANGELOG.md é gerado e incluso no commit de release automaticamente. O padrão é false.

Flag por execução

Sem alterar a config, use a flag para uma execução específica:

versioner build --changelog "Adiciona endpoint de pagamentos"
versioner build --changelog=false "hotfix rápido"

A flag tem prioridade sobre a config (FLAG > CONFIG > DEFAULT) e não modifica o versioner.config.json.

Fonte dos dados

O changelog lê os commits via git log desde a última tag Git — não o working tree. Os commits do histórico aparecem como entradas no CHANGELOG.md.

Posição no fluxo

version → updateFiles → changelog → git add → commit → push

O CHANGELOG.md é gerado antes do git add, portanto é incluso automaticamente no commit da release.

Workspaces / Monorepo

Para projetos com múltiplos pacotes (monorepo), configure workspaces no versioner.config.json:

{
    "workspaces": {
        "core": {
            "versionFile": "core/.versioner.json",
            "files": [
                { "path": "core/Cargo.toml", "field": "package.version" }
            ]
        },
        "api": {
            "versionFile": "api/.versioner.json",
            "files": [
                { "path": "api/package.json", "field": "version" }
            ]
        },
        "mobile": {
            "versionFile": "mobile/.versioner.json",
            "files": [
                { "path": "mobile/package.json", "field": "version" },
                { "path": "mobile/app.json", "field": "expo.version" }
            ]
        }
    }
}

Cada workspace tem sua versão independente no próprio .versioner.json. O template de commit aceita {workspace} para identificar qual pacote foi alterado:

{
    "commit": {
        "template": "{workspace}: v{version} - {message}"
    }
}

Comandos workspace

# Versiona apenas o workspace "api"
versioner build --ws=api "Adiciona endpoint de usuários"

# Versiona todos os workspaces em sequência, com um único push no final
versioner build --ws=all "Release geral"

Suporte a Cargo.toml

O campo package.version em arquivos .toml é atualizado via regex, sem dependências externas:

# Antes
[package]
version = "0.1.0"

# Depois de versioner build --ws=core "..."
[package]
version = "0.1.1"

Log

Lista os commits recentes do repositório com hash, mensagem e tempo relativo:

versioner log
# ou
versioner lg

Por padrão exibe os últimos 20 commits. Para mudar o limite:

versioner log --limit=50

Sync

Atualiza todos os arquivos configurados com a versão atual do .versioner.json, sem incrementar versão nem tocar no Git:

versioner sync
# ou
versioner sy

Útil quando um arquivo novo foi adicionado à configuração ou os arquivos ficaram dessincronizados por edição manual.

Changelog

Gera ou atualiza o CHANGELOG.md com os commits desde a última tag Git:

versioner changelog
# ou
versioner cl

Cria o arquivo se não existir e insere as entradas mais recentes no topo. Se já houver uma entrada para a versão atual, ela é substituída.

Exemplo de saída:

# Changelog

## [0.0.8] - 2026-08-20

- Adiciona suporte a workspaces
- Corrige versioner init não atualizando package.json
- Adiciona versioner changelog

Arquivos gerados

.versioner.json

O contador de versão do projeto.

{
    "major": 1,
    "minor": 4,
    "build": 273
}

versioner.config.json

Define o comportamento e quais arquivos recebem a versão.

{
    "versionFile": ".versioner.json",
    "files": [
        {
            "path": "package.json",
            "field": "version"
        },
        {
            "path": "app.json",
            "field": "expo.version"
        }
    ],
    "commit": {
        "template": "v{version} - {message}",
        "minLength": 3,
        "maxLength": 100
    },
    "git": {
        "enabled": true,
        "add": true,
        "addAll": true,
        "commit": true,
        "push": true,
        "tag": false,
        "tagPrefix": "v",
        "tagMessage": "Release {version}"
    },
    "semver": false,
    "workspaces": null
}

files — qualquer arquivo .json. O campo field aceita caminhos aninhados:

version
expo.version
project.meta.version

commit.template — aceita {version}, {message} e {type}.

git.addAll — true faz git add . (padrão); false exige que os arquivos sejam listados no comando.

semver — false usa o modelo de build global (padrão); true segue o padrão SemVer com resets.

Arquivos de código (app.config.js, app.config.ts) são detectados pelo init mas não são alterados automaticamente. Nesses casos, leia a versão do JSON:

const { version } = require("./package.json");

export default {
    expo: { version },
};

Segurança da release

Se qualquer etapa falhar no meio do caminho, o Versioner reverte o arquivo de versão e todos os arquivos alterados. Nada fica commitado pela metade.

O push é ignorado com um aviso quando não existe remoto configurado, em vez de derrubar a release. Se a branch ainda não tiver upstream, o Versioner usa --set-upstream origin <branch> automaticamente.

Mensagens de commit são passadas por execFile com array de argumentos, então aspas, $ e crases não quebram nem executam nada.

Uso programático

const { ReleaseManager, createContext, version } = require("@kinetnode/versioner");

// Versão do próprio Versioner (ex: "0.1.8")
console.log(version);

const context = createContext({ type: "build", message: "Release automática" });

new ReleaseManager().run(context);

Também são exportados VersionManager, ConfigManager, FileManager, GitManager, WorkspaceManager, CommandRouter, logger e constants.

Arquitetura

bin/versioner.js         Binário da CLI (shebang)
src/cli.js               Bootstrap da CLI e tratamento de erro
src/index.js             Entrada programática (require do pacote)
src/services/            CommandRouter (mapa nome → classe)
src/commands/            Um arquivo por comando
src/managers/            Release, Version, Config, File, Git, Workspace
src/core/Context.js      Objeto compartilhado da execução
src/utils/               file, object, time, args, logger
src/constants/           Valores fixos e metadados de ajuda

Regra central: nenhum Manager conhece outro Manager. Todos leem e escrevem apenas no Context. O ReleaseManager só orquestra a sequência:

validate → loadConfig → version → updateFiles → git → finish

Desenvolvimento

npm test    # 67 asserções em um repositório Git temporário

Para logs completos de erro:

VERSIONER_DEBUG=1 versioner build "teste"

Cores são desativadas automaticamente com NO_COLOR=1 ou fora de um TTY.

Licença

MIT.