# atomwrite
> Operações atômicas de arquivo para agentes LLM — um CLI, zero corrupção
atomwrite é um CLI Rust que fornece 28 subcomandos para manipulação de arquivos com garantias de escrita atômica. Toda escrita usa tempfile + fsync + rename + fsync do diretório. Toda resposta é NDJSON com checksums BLAKE3. Construído para agentes LLM que precisam de operações de arquivo confiáveis e estruturadas sem risco de corrupção.
**Release mais recente: v0.1.22** (2026-06-17) — 2 novos sub-comandos (`edit-loop` para N pares em 1 invocação via NDJSON; `prune-backups` para limpeza manual de arquivos `.bak.*` legados com `--max-age`, `--max-count`, `--dry-run`), 16+ novos testes de regressão, ADRs 0039 e 0040, 2 novos schemas NDJSON (`edit-loop-output`, `prune-backups-output`), 575+ testes, 32 sub-comandos totais. Destaques anteriores (v0.1.21, 2026-06-17): 3 fechamentos de GAP-2026 (012 drift sequencial via `--allow-sequential-drift`, 013 Problema C paridade `--backup` em 4 sub-comandos, 014 v2 `--keep-backup` deleta-após-sucesso como default), 555+ testes, ADR-0038 (backup cumprido deleta), nova flag `--keep-backup` em 6 sub-comandos (write, edit, replace, rollback, apply, batch), `--allow-sequential-drift` em `edit` para pipelines sequenciais. Destaques anteriores (v0.1.20, 2026-06-15): 11 GAP-2026 fechados, intention guards (`--require-backup`, `--confirm`, `--auto-rotate`, `--risk-threshold`), renomeação `--locale` (era `--lang`), `count --by-size`, `read --mode`, `search --no-begin-end`, `write --preserve-timestamps`, alias `scope --lang`, 542 testes em 47 suites, ADRs 0031-0037. Veja `CHANGELOG.pt-BR.md` para as notas completas e `docs/decisions/` para os ADRs (0019-0040).
**Release anterior: v0.1.19** (2026-06-14) — Helper de resolução de caminho G121 que unifica a resolução do jail em todos os subcomandos de escrita; modo `query` S-expression real via `tree-sitter`; consolidação de 7 derivas de documentação de exit codes para casar com a lista canônica (ADR-0031).
## 28 Subcomandos
### I/O Principal (7)
- `read` — ler arquivos com metadados, checksum, conteúdo opcional. `--mode raw|envelope` seleciona byte-stream vs envelope NDJSON
- `write` — criar ou sobrescrever arquivos atomicamente via stdin. `--preserve-timestamps` preserva o mtime da fonte
- `edit` — editar cirurgicamente por número de linha, marcador de texto ou match exato/fuzzy; multi-par `--old`/`--new` com cascata fuzzy por par, `pair_results` e `--partial` (v0.1.15)
- `delete` — deletar arquivos com backup opcional
- `copy` — copiar arquivos com verificação de checksum
- `move` — mover ou renomear arquivos atomicamente (EXDEV copy-fallback)
- `apply` — aplicar patches do stdin (unified diff, search/replace, full, markdown)
### Busca e substituição (3)
- `search` — buscar conteúdo de arquivos em paralelo (motor ripgrep). `--no-begin-end` desabilita a emissão de âncoras
- `replace` — substituir texto entre arquivos com escritas atômicas
- `transform` — refatoração AST via ast-grep (306 linguagens)
### Inspeção (9)
- `hash` — calcular checksums BLAKE3
- `count` — contar linhas, arquivos por extensão. `--by-size` lista os maiores arquivos
- `diff` — comparar dois arquivos (unified, stat ou mudanças)
- `list` — listar arquivos em uma árvore de diretórios
- `extract` — extrair campos de entrada NDJSON via pipe
- `scope` — scoping gramatical (deletar todos os comentários, etc.). Aceita alias `--lang rust`
- `regex` — gerar regex a partir de exemplos
- `calc` — matemática e conversões de unidades
- `completions` — gerar completions de shell (bash, zsh, fish, elvish, powershell)
### Backup e recuperação (3)
- `backup` — criar backups com timestamp com checksums BLAKE3
- `rollback` — restaurar de um backup anterior
- `batch` — operações em lote dirigidas por NDJSON (transacional)
### Editores estruturados de configuração (v14 Tier 3, v0.1.12) (4)
- `set <PATH> <KEY_PATH> <VALUE>` — escrever um valor em um caminho dotted em um arquivo TOML ou JSON. Preserva comentários e ordem das chaves via `toml_edit`. Auto-coage int/bool/float/string.
- `get <PATH> <KEY_PATH>` — ler um valor em um caminho dotted. NDJSON: `{"type":"get","key_path","value","found","format"}`.
- `del <PATH> <KEY_PATH>` — remover uma chave. Flag `--force-missing` trata chaves ausentes como no-op success.
- `case <PATHS...> --subvert OLD NEW --to <style>` — renomear identificadores em múltiplos arquivos via `heck`. Estilos: `snake`, `camel`, `pascal`, `kebab`, `screaming-snake`.
### Ferramentas AST (v14 Tier 3 + G72, v0.1.12, via tree-sitter-language-pack) (2)
- `query <PATH> [--kinds|--query <KIND>|-Q <KIND>|--tree] [--positions]` — caminhar um AST tree-sitter e emitir nós como NDJSON. 305 linguagens suportadas.
- `outline <PATH> [--kind <KIND>] [--positions]` — extrair estrutura de alto nível (funções, classes, structs, enums, traits, módulos) como NDJSON.
Além da verificação de sintaxe G72 em `write --syntax-check` (24 linguagens, exit 88).
## Destaques Da v0.1.20 — Intention Guards
- **5 flags de intention-guard** formam uma nova camada de segurança que intercepta mutações destrutivas antes de tocarem o disco:
- `--require-backup <N>` — recusa a operação quando menos de `N` backups retidos existem para o alvo
- `--confirm` — emite um prompt de confirmação listando a mutação planejada em NDJSON antes de executar
- `--auto-rotate <N>` — rotaciona automaticamente o anel de backups para `N` entradas após uma escrita bem-sucedida
- `--risk-threshold <LOW|MEDIUM|HIGH>` — bloqueia operações cujo risco classificado atinge ou excede o threshold
- `--locale <en|pt-BR>` — renomeado de `--lang` para evitar conflito com o seletor de linguagem usado por `scope` e `transform` (G121+)
- **`count --by-size`** — lista os maiores arquivos da árvore com tamanhos e contagem de linhas
- **`read --mode raw|envelope`** — seleciona entre saída byte-stream e envelope NDJSON estruturado
- **`search --no-begin-end`** — desabilita a decoração implícita de âncoras `^` e `$` na saída regex
- **`write --preserve-timestamps`** — preserva o mtime do arquivo fonte ao sobrescrever
- **542 testes passando** em 47 suites de integração, 0 falhas, 3 targets de cross-compile Windows verdes
- **19 ADRs** em `docs/decisions/` (0019-0037): v0.1.20 adiciona 0031 (canonização de exit codes), 0032 (intention guards como nova camada), 0033-0037 cobrindo scope/lang alias, renomeação locale, count by-size, read mode, no-begin-end
## Migração De v0.1.19 Para v0.1.20
- `--lang` em comandos globais de configuração é renomeado para `--locale` para desambiguar do `--lang` tree-sitter usado por `scope` e `transform`. Use `sd` ou `ruplacer` para atualizar scripts existentes:
- `rg -l -- '--lang\b' .` e depois `ruplacer --subvert --lang --locale` (ou `fd -e sh -e md -x sd -- '--lang\b' '--locale' {}`)
- Intention guards são OPT-IN. Comportamento padrão inalterado
- `count --by-size` é ADITIVO. Saída padrão de `count` inalterada
- `read --mode raw` é ADITIVO. Saída de envelope padrão inalterada
- Veja `docs/MIGRATION.pt-BR.md` para o guia de upgrade completo
## Documentação Principal
- [README](https://github.com/daniloaguiarbr/atomwrite/blob/main/README.pt-BR.md): Documentação completa com todos os 28 comandos e exemplos
- [HOW_TO_USE](https://github.com/daniloaguiarbr/atomwrite/blob/main/docs/HOW_TO_USE.pt-BR.md): Guia de início rápido
- [COOKBOOK](https://github.com/daniloaguiarbr/atomwrite/blob/main/docs/COOKBOOK.pt-BR.md): Receitas para tarefas comuns
- [AGENTS](https://github.com/daniloaguiarbr/atomwrite/blob/main/docs/AGENTS.pt-BR.md): Arquivo de descoberta de agente com contrato de saída e budget de tokens
- [TESTING](https://github.com/daniloaguiarbr/atomwrite/blob/main/docs/TESTING.pt-BR.md): 542 testes em 47 suites de teste
- [MIGRATION](https://github.com/daniloaguiarbr/atomwrite/blob/main/docs/MIGRATION.pt-BR.md): Guia de migração entre versões
- [INSTALL](https://github.com/daniloaguiarbr/atomwrite/blob/main/docs/INSTALL.pt-BR.md): Instruções de instalação por plataforma
- [CROSS_PLATFORM](https://github.com/daniloaguiarbr/atomwrite/blob/main/docs/CROSS_PLATFORM.pt-BR.md): Quirks de macOS, Linux, Windows
- [CHANGELOG](https://github.com/daniloaguiarbr/atomwrite/blob/main/CHANGELOG.pt-BR.md): Histórico de releases
- [CONTRIBUTING](https://github.com/daniloaguiarbr/atomwrite/blob/main/CONTRIBUTING.pt-BR.md): Setup de desenvolvimento e diretrizes
- [SECURITY](https://github.com/daniloaguiarbr/atomwrite/blob/main/SECURITY.pt-BR.md): Reporte de vulnerabilidades
- [docs/decisions/](https://github.com/daniloaguiarbr/atomwrite/blob/main/docs/decisions/): 22 ADRs (decisões arquiteturais da v0.1.12 + v0.1.19 + v0.1.20 + v0.1.21 + v0.1.22)
- [docs/schemas/](https://github.com/daniloaguiarbr/atomwrite/blob/main/docs/schemas/): 24 contratos estáveis de JSON Schema
- [Crates.io](https://crates.io/crates/atomwrite): Registro de pacotes
- [Repositório](https://github.com/daniloaguiarbr/atomwrite): Código-fonte