# atomwrite
> Operações atômicas de arquivo para agentes LLM — um CLI, zero corrupção
atomwrite é um CLI Rust que fornece 41 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.30** (2026-07-13) — Fuzzy obrigatório (`auto`/`aggressive`; `--fuzzy off` exit 65); `edit --replace-all` com NDJSON `match_count` e `indent_adjusted`; escape-drift; unicode_normalized; `best_candidate`/`candidates[]` ranqueados; `search --target` + paginação; recipe exclui `*.bak.*` inclusive no hash; `sparse outline` AST real; `backup_method=reflink_or_copy`; config `[fuzzy]` ao vivo; semantic-merge line-based; suíte `cli_v0130_agent_contract`. 41 subcomandos. Veja `CHANGELOG.pt-BR.md`.
**Release anterior: v0.1.28** (2026-07-06) — BREAKING: backup default em `delete`; `BackupOpts` unificado em 15 subcomandos mutantes; `[defaults]` do `.atomwrite.toml` efetivo; guard de stdin-tty no `edit`. 661 testes, 33 subcomandos. Veja `CHANGELOG.pt-BR.md`.
## 41 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; `--fuzzy auto|aggressive` (off rejeitado desde v0.1.30) e `--fuzzy-threshold`; reporta `strategy`/`similarity`/`match_count`/`indent_adjusted`; erros de match podem incluir `best_candidate`
- `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).
### Superfície de agente e workflows (v0.1.29) (8)
- `recipe` — listar/rodar pipelines multi-passo versionados (ex.: search→replace→hash)
- `sparse` — list/read/outline orçamentado em monorepo (`sparse list --max-files N`)
- `semantic-merge` — merge de três vias para conflitos multi-agente
- `agent-surface` — manifesto de tools derivado do clap (só CLI; MCP é PROIBIDO)
- `watch` — eventos de filesystem com debounce/checksum/gitignore (feature `watch`)
- `codemod` — campanha AST multi-regra com summary `by_rule_id`
- `semantic-search` — ranking offline por tokens/índice invertido (feature `semantic`; NÃO embeddings OpenRouter)
- `stat` — alias de `read --stat`
### Durabilidade de write (v0.1.29)
- `write --durability full|fast|auto` — trade-off de fsync; NDJSON `platform.durability`, `platform.rename_method`, `platform.backup_method`
- Linux usa `renameat2` quando disponível, com fallback para rename
- macOS usa `F_FULLFSYNC` sob durability `full`
### Features Cargo (v0.1.29)
- Slim: `cargo build --release --no-default-features --features core`
- Full: `cargo build --release --features full`
- Padrão: `core` + `ast` + `lang-rust` + `lang-ts` + `lang-py`
## 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/danilo-aguiar-br/atomwrite/blob/main/README.pt-BR.md): Documentação completa com todos os 41 subcomandos e exemplos
- [HOW_TO_USE](https://github.com/danilo-aguiar-br/atomwrite/blob/main/docs/HOW_TO_USE.pt-BR.md): Guia de início rápido
- [COOKBOOK](https://github.com/danilo-aguiar-br/atomwrite/blob/main/docs/COOKBOOK.pt-BR.md): Receitas para tarefas comuns
- [AGENTS](https://github.com/danilo-aguiar-br/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/danilo-aguiar-br/atomwrite/blob/main/docs/TESTING.pt-BR.md): 542 testes em 47 suites de teste
- [MIGRATION](https://github.com/danilo-aguiar-br/atomwrite/blob/main/docs/MIGRATION.pt-BR.md): Guia de migração entre versões
- [INSTALL](https://github.com/danilo-aguiar-br/atomwrite/blob/main/docs/INSTALL.pt-BR.md): Instruções de instalação por plataforma
- [CROSS_PLATFORM](https://github.com/danilo-aguiar-br/atomwrite/blob/main/docs/CROSS_PLATFORM.pt-BR.md): Quirks de macOS, Linux, Windows
- [CHANGELOG](https://github.com/danilo-aguiar-br/atomwrite/blob/main/CHANGELOG.pt-BR.md): Histórico de releases
- [SECURITY](https://github.com/danilo-aguiar-br/atomwrite/blob/main/SECURITY.pt-BR.md): Reporte de vulnerabilidades
- [docs/decisions/](https://github.com/danilo-aguiar-br/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/danilo-aguiar-br/atomwrite/blob/main/docs/schemas/): 38 contratos estáveis de JSON Schema
- [Crates.io](https://crates.io/crates/atomwrite): Registro de pacotes
- [Repositório](https://github.com/danilo-aguiar-br/atomwrite): Código-fonte