flow-cli

English

CLI em Node.js (ESM) para automatizar e padronizar o fluxo Git orientado a Pull Requests (master / developer / test).

Pacote npm: @micaelmf/flow-cli
Comando: flow-cli

A página do pacote no npmjs.com exibe o README.md em inglês. Este arquivo é a documentação equivalente em pt-BR.

Instalação

npm install -g @micaelmf/flow-cli
flow-cli --help

Instalação local (desenvolvimento)

# Na pasta deste repositório
npm install
npm link

# Em qualquer outro repositório Git
flow-cli --help

Para remover o link global:

npm unlink -g @micaelmf/flow-cli

Configuração

A CLI não usa branches ou prefixos hardcoded. Ela lê flow.config.json na raiz do projeto (ou sobe diretórios até encontrá-lo). Se o arquivo não existir, usa os valores padrão.

Crie o arquivo interativamente:

flow-cli init

Exemplo (flow.config.example.json):

{
  "branches": {
    "production": "master",
    "development": "developer",
    "testing": "test"
  },
  "prefixes": ["feature", "bugfix", "hotfix", "perf", "refactor", "chore", "docs", "style", "test"],
  "commit": {
    "types": ["feat", "fix", "perf", "refactor", "chore", "docs", "style", "test"],
    "requireTaskId": true,
    "scopePattern": "[a-z0-9][a-z0-9-]*"
  },
  "changelog": {
    "file": "CHANGELOG.md",
    "sections": {
      "feat": "Funcionalidades",
      "fix": "Correções",
      "perf": "Melhorias de Performance"
    }
  },
  "platform": "azure-devops"
}

Flags globais

| Flag | Uso | |------|-----| | --dry-run | Simula comandos Git (apenas imprime) | | --yes | Confirma prompts automaticamente | | --ci | Modo pipeline: sem prompts, sem cores, sem abrir navegador |

O modo pipeline é explícito (--ci). Por padrão a CLI é interativa e colorida para o dia a dia do desenvolvedor.

Comandos

flow-cli init

Pergunta branches, prefixos, tipos de commit e plataforma; grava flow.config.json.

flow-cli start <tipo> <id> <descricao>

Cria a branch a partir da production:

flow-cli start hotfix 91 "Captura erro de Turmas"
# → hotfix/91-captura-erro-de-turmas

flow-cli start feature 45 "login pelo google"
# → feature/45-login-pelo-google

flow-cli start hotfix "erro pagamento pix" --no-id
# → hotfix/erro-pagamento-pix

Sequência Git: checkout production → pull → checkout -b.

flow-cli publish

Publica a branch de tarefa no origin e mescla em development (nessa ordem). Em conflito no merge não aborta: instrui a resolver visualmente, commitar e dar flow-cli push / git push manual — a branch de tarefa já estará no remoto.

flow-cli push

Envia a branch de tarefa atual para o origin (com -u na primeira vez). Bloqueado em master / developer / test. Não mescla em development.

flow-cli refresh

Atualiza a branch de tarefa local com origin/<branch-atual>. Bloqueado nas branches base. Não puxa production, developer nem test — para trazer production use sync.

flow-cli sync

Único pull a partir da production na branch de tarefa: traz a production (git pull origin master).

flow-cli pr [--target test|master|both] [--no-open] [--no-publish]

Executa publish (origin + development) e abre (ou imprime) as URLs de Pull Request. Útil também após correções no re-teste: um novo flow-cli pr republica e reabre os links. Padrão both: PR para test + PR draft para master. Em --ci nunca abre o navegador. Use --no-publish para só abrir/imprimir as URLs (exige branch já no origin).

flow-cli merge-to-test

Quando há conflito com test, cria tipo/ID-descricao-merge-to-test a partir de testing, faz o merge da tarefa e publica a branch temporária para o PR com review.

flow-cli changelog [--preview] [--write]

flow-cli changelog --preview
flow-cli changelog --write --release 1.2.0

Agrupa commits em Funcionalidades / Correções / Melhorias de Performance (rótulos vêm da config).

flow-cli release-check [--all]

Valida o padrão de commit prefixo(modulo): descrição #ID.

flow-cli release-check
flow-cli release-check --all --ci   # gate de pipeline

flow-cli release

Release completo na production: detecta o bump SemVer pelos commits, atualiza o CHANGELOG.md, cria a tag anotada e faz push.

flow-cli release
flow-cli release --yes --ci
flow-cli release --level minor   # override opcional

Regras de bump (configuráveis no flow.config.json):

| Commits desde a última tag | Bump | |----------------------------|------| | Breaking change (BREAKING CHANGE: ou type!:) | major | | Qualquer feat | minor | | Só fix / perf / chore / … | patch |

flow-cli tag [major|minor|patch]

flow-cli tag patch
flow-cli tag minor --push --yes --ci

Cria tag anotada (vX.Y.Z) a partir da production, com corpo de changelog. Prefira flow-cli release para o fluxo completo.

Fluxo resumido

master ──start──► tipo/ID-descricao
   ▲                     │
   │                     ├── publish ──► origin + developer
   │                     ├── push ─────► origin
   │                     ├── refresh ◄── origin
   │                     ├── pr ───────► publish + test (review)
   │                     └── pr draft ─► master
   └──────── sync ───────┘

Regras de ouro (bloqueadas pela CLI):

• Nunca pull/merge de developer ou test para dentro da branch de tarefa.
• Nunca merge de master em developer/test.
• Comandos de tarefa não rodam nas branches protegidas.
• Working tree precisa estar limpa antes de checkouts.

Pipeline

Exemplos típicos após merge na production (sempre passe --ci):

flow-cli release-check --all --ci
flow-cli release --yes --ci

Convenção de commit

prefixo(modulo): descrição resumida em português #ID_TASK

Exemplos:

feat(login): adiciona validacao de senha no cadastro #123
fix(turmas): corrigir exibicao de mensagem de erro #91
perf(busca): otimiza consulta de produtos #47

Licença

MIT