Safe Auto Commit

Uma camada de governança para automações Git locais. Em vez de “commitar tudo”, o utilitário transforma mudanças em decisões verificáveis: define o escopo, avalia riscos, registra uma prova da execução e só altera o repositório com uma autorização explícita.

O modo normal é dry-run. Nenhum arquivo é staged, nenhum commit é criado, nenhum push é feito e nenhuma notificação externa é enviada sem -Apply.

Todos os caminhos, nomes e resultados da demonstração são sintéticos. O projeto não contém identidades Git, tokens, repositórios privados, logs ou configurações pessoais.

O problema que ele resolve

Automatizar commits parece simples até o momento em que um script inclui um arquivo errado, mistura trabalho já staged, publica em uma branch protegida ou vaza informações em um log. O Safe Auto Commit reduz esse risco com limites claros e evidências legíveis para revisão humana.

configuração validada
  -> lock exclusivo
  -> branch e índice verificados
  -> allowlist de candidatos
  -> preflight Git e guardas de caminho
  -> dry-run / recibo de revisão
  -> Apply explícito
  -> commit e push opcional por SHA

Demonstração visual

Abra demo/dry-run-demo.html para acompanhar um cenário local e reproduzível. A demonstração usa um repositório temporário sintético e prova que o dry-run encontrou dois candidatos permitidos sem criar commit, alterar o índice ou configurar remotes.

Reproduza sem remotes e sem push:

.\demo\Invoke-SyntheticDryRun.ps1

Proteções implementadas

• allowlist obrigatória e estreita de pathspecs Git;
• rejeição de paths absolutos, .., magia de pathspec e padrões que representam o repositório inteiro;
• arquivos fora da allowlist ou em exclusões nunca entram no stage;
• recusa de alterações staged manualmente;
• branches protegidas bloqueadas por padrão;
• lock exclusivo para evitar duas execuções concorrentes;
• git diff --check opcional e habilitado por padrão como preflight seguro;
• bloqueio opcional, habilitado por padrão, para caminhos que pareçam conter segredos, chaves, certificados ou arquivos .env;
• dry-run por padrão; somente -Apply pode alterar o Git;
• push normal, sem force, do mesmo SHA para origin e mirror opcional;
• logs e mensagens com redação de credenciais;
• Telegram opcional apenas em -Apply, com valores vindos do ambiente.

Fluxo de aprovação em duas etapas

Para repositórios que exigem uma revisão formal, defina runtime.requireApprovalToken como true. O dry-run gera um token ligado ao conteúdo da configuração, branch, HEAD e candidatos atuais. O -Apply só é aceito se receber esse token exato. Qualquer mudança no snapshot invalida a aprovação e exige uma nova revisão.

# 1. Inspecione a decisão e registre o token retornado no JSON.
.\auto-commit.ps1 -ConfigPath .\config.json

# 2. Depois da revisão humana, aplique exatamente o snapshot aprovado.
.\auto-commit.ps1 -ConfigPath .\config.json -Apply -ApprovalToken '<token-do-dry-run>'

O recibo JSON de cada execução registra ID da execução, horário, digest SHA-256 da configuração, contagem de riscos e, para cada repositório, HEAD antes e depois, preflight, candidatos, caminhos bloqueados, commit e destinos de push. Para arquivar o recibo sem depender do scroll do terminal, informe um caminho de saída:

.\auto-commit.ps1 -ConfigPath .\config.json -ScanOnly -ReceiptPath .\state\scan-receipt.json

O arquivo é UTF-8 sem BOM e contém o mesmo objeto JSON exibido pela execução.

Início rápido

1. Copie config.example.json para config.json.

2. Troque o caminho de exemplo e reduza include aos arquivos que a automação realmente pode versionar.

3. Valide a configuração:

   .\auto-commit.ps1 -ConfigPath .\config.json -ValidateOnly

4. Veja candidatos sem mutações:

   .\auto-commit.ps1 -ConfigPath .\config.json -ScanOnly

5. Execute o dry-run e revise o recibo:

   .\auto-commit.ps1 -ConfigPath .\config.json

6. Use -Apply somente após a revisão. Se o token estiver habilitado, informe-o.

Configuração essencial

{
  "version": 1,
  "runtime": {
    "lockFile": ".state/auto-commit.lock",
    "logFile": null,
    "preflightGitDiffCheck": true,
    "blockSensitivePaths": true,
    "requireApprovalToken": true
  },
  "repositories": [
    {
      "name": "meu-projeto",
      "path": "C:\\Projects\\meu-projeto",
      "include": ["src/**", "tests/**", "README.md"],
      "exclude": ["src/generated/**", "**/*.tmp"],
      "allowProtectedBranch": false,
      "push": { "enabled": false, "originRemote": "origin", "mirrorRemote": null }
    }
  ]
}

preflightGitDiffCheck verifica erros de whitespace do Git nas mudanças rastreáveis. blockSensitivePaths bloqueia nomes de caminho de alto risco como .env, credentials, secret, token, id_rsa, .pem, .key, .p12, .pfx e .kdbx. Esse guarda não substitui uma revisão de conteúdo nem uma ferramenta de segurança especializada.

Limites honestos

O utilitário não executa lint, testes ou comandos arbitrários definidos em JSON: isso evitaria trocar a proteção de commits por uma superfície de execução remota ou acidental. Integre CI, hooks revisados ou pipelines externos para essas verificações.

Ele também não cria branches, não abre pull requests e não torna confiáveis hooks, filtros Git, credential helpers, binários Git ou servidores remotos. Use uma conta de menor privilégio, proteção de branch no servidor e revisão periódica da allowlist.

Testes

A suíte usa somente repositórios temporários locais. Ela não configura remotes e não executa push:

powershell -NoProfile -ExecutionPolicy Bypass -File .\tests\Run-Tests.ps1

Ela cobre validação estrita, redação, allowlist, dry-run, apply controlado, token de aprovação, preflight, guarda de caminho sensível, lock e primitivas Git inseguras.

Consulte config.schema.json para a estrutura formal, SECURITY.md para o modelo de ameaça e LICENSE para a licença MIT.