# atomwrite
> Operações atômicas de arquivo para agentes LLM — um CLI, zero corrupção
atomwrite é um CLI Rust que fornece 33 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.26** (2026-06-23) — 9 correções de bugs (GAP-135 a GAP-147): consistência de exit codes para replace/transform/scope zero-matches (exit 1), search --sort path ordenação determinística, read --verify-checksum exit 81, get chave ausente exit 4, scope padrões AST duais para generics/return types Rust, verify args posicionais, edit-loop input JSON array. 4 esclarecimentos de documentação (BY-DESIGN). 631+ testes, 33 subcomandos. Veja `CHANGELOG.pt-BR.md` para notas completas.
**Release anterior: v0.1.25** (2026-06-22) — Arquivo de configuração .atomwrite.toml, subcomando verify, fuzzy matching Jaro-Winkler, 49 correções, 631 testes. Veja `CHANGELOG.pt-BR.md`.
## 33 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)
### Helpers de lote (2)
- `edit-loop` — N edições em 1 invocação via JSON array ou NDJSON stdin
- `prune-backups` — limpeza manual de arquivos `.bak.*` legados com `--max-age-secs`, `--max-count`
### Diagnóstico WAL (2)
- `wal-stats` — snapshot do estado dos journals WAL (contagens, idades, tamanhos)
- `wal-heal` — remover journals terminais órfãos mais antigos que o threshold
### Verificação (1)
- `verify <PATH> <HASH>` — verificar checksum BLAKE3 de um arquivo (delega para `hash --verify`)
### 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 33 subcomandos 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/): 29 ADRs (0019-0047, decisões arquiteturais da v0.1.12 até v0.1.24)
- [docs/schemas/](https://github.com/daniloaguiarbr/atomwrite/blob/main/docs/schemas/): 29 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