# Ferramentas Recomendadas para Otimização de IAs no Desenvolvimento

Este documento lista ferramentas de linha de comando (CLI) e utilitários que otimizam significativamente o trabalho e a integração de Agentes de IA durante o processo de desenvolvimento. Todas as ferramentas listadas possuem suporte nativo para **Linux** e **macOS**.

## 1. Busca e Navegação de Código

### ripgrep (`rg`)
- **Descrição:** Uma ferramenta de busca orientada a linhas que busca recursivamente no diretório atual por uma expressão regular.
- **Por que ajuda as IAs:** É extremamente rápida para encontrar referências de código, funções e variáveis em repositórios grandes. Ajuda as IAs a varrer bases de código rapidamente sem precisar ler todos os arquivos.
- **Instalação:** 
  - **Mac:** `brew install ripgrep`
  - **Linux (Ubuntu/Debian):** `sudo apt-get install ripgrep`

### fd
- **Descrição:** Uma alternativa simples, rápida e amigável ao comando `find`.
- **Por que ajuda as IAs:** Permite que as IAs listem a estrutura de arquivos e localizem caminhos específicos com uma sintaxe muito mais amigável e saída mais rápida e limpa que o `find` tradicional, respeitando o `.gitignore` nativamente.
- **Instalação:**
  - **Mac:** `brew install fd`
  - **Linux (Ubuntu/Debian):** `sudo apt-get install fd-find`

### ast-grep (`sg`)
- **Descrição:** Uma ferramenta de busca e substituição de código baseada em Árvore de Sintaxe Abstrata (AST).
- **Por que ajuda as IAs:** Diferente do regex padrão, permite que a IA faça buscas estruturais e refatorações complexas compreendendo a semântica da linguagem.
- **Instalação:**
  - **Mac/Linux:** `npm install -g @ast-grep/cli` ou `brew install ast-grep`

## 2. Processamento de Dados

### jq
- **Descrição:** Um processador JSON de linha de comando leve e flexível.
- **Por que ajuda as IAs:** Sistemas baseados em agentes interagem frequentemente por payloads JSON e chamadas de API. O `jq` é a ferramenta perfeita para que a IA filtre, extraia e transforme grandes payloads de dados diretamente no terminal.
- **Instalação:**
  - **Mac:** `brew install jq`
  - **Linux (Ubuntu/Debian):** `sudo apt-get install jq`

### yq
- **Descrição:** Uma extensão leve e portável do `jq` voltada para o processamento de arquivos YAML, JSON e XML.
- **Por que ajuda as IAs:** Útil para a IA inspecionar, modificar e gerar configurações como `docker-compose.yml`, esquemas de CI/CD, e manifestos Kubernetes.
- **Instalação:**
  - **Mac:** `brew install yq`
  - **Linux:** O binário é baixado direto da distribuição oficial no Github ou via snap.

## 3. Qualidade de Código e Formatação

### Biome
- **Descrição:** Ferramenta All-in-One super rápida para formatação e linting de projetos Web (JavaScript, TypeScript, JSX, JSON).
- **Por que ajuda as IAs:** Como exigido pelos padrões do projeto, garante que o código escrito pela IA passe pela validação, sendo auto-focado e sem configurações complexas (`biome check --write`).
- **Instalação:**
  - **Mac/Linux:** `npm install -g @biomejs/biome` ou gerenciamento local (`pnpm add -D @biomejs/biome`).

### ShellCheck
- **Descrição:** Ferramenta de análise estática e linting projetada especificamente para scripts de shell (bash/sh).
- **Por que ajuda as IAs:** Assegura que scripts bash gerados por IAs (seja para deploy ou testes de automação de fluxo) sigam as melhores práticas e não tenham comandos perigosos implícitos.
- **Instalação:**
  - **Mac:** `brew install shellcheck`
  - **Linux (Ubuntu/Debian):** `sudo apt-get install shellcheck`

## 4. Visualização e Visualização de Texto

### bat
- **Descrição:** Um clone do `cat` com suporte nativo a syntax highlighting (destaque de sintaxe) e integração com o Git.
- **Por que ajuda as IAs:** Ao extrair ou ler recortes de arquivos e logs, o conteúdo é formatado de maneira que facilita eventuais inspeções humanas e recortes por linhas (`bat -r <linha_inicio>:<linha_fim>`).
- **Instalação:**
  - **Mac:** `brew install bat`
  - **Linux (Ubuntu/Debian):** `sudo apt-get install bat`

### tree / eza
- **Descrição:** Utilitários para listar o conteúdo de diretórios. O `eza` é um substituto moderno para o `ls` com suporte de árvore.
- **Por que ajuda as IAs:** Permitir que agentes mapeiem mentalmente a árvore de projeto de forma clara. Essencial para IAs auto-localizarem módulos arquiteturais.
- **Instalação:**
  - **Mac:** `brew install eza tree`
  - **Linux (Ubuntu/Debian):** `sudo apt-get install tree eza`

## 5. Integração com APIs e Git

### HTTPie / cURL
- **Descrição:** Ferramenta gráfica ou cli para o teste de endpoints, sendo o HTTPie uma versão "humanizada" do cURL.
- **Por que ajuda as IAs:** Auxilia nas IAs de codificação que necessitam conferir os status e formatos dos endpoints REST antes de gerar lógicas assíncronas no front-end ou back-end.
- **Instalação (HTTPie):**
  - **Mac:** `brew install httpie`
  - **Linux:** `sudo apt-get install httpie`

### GitHub CLI (`gh`)
- **Descrição:** Interface de linha de comando nativa para interagir com repositórios no GitHub.
- **Por que ajuda as IAs:** Permite à IA criar pull requests, listar issues e manipular webhooks diretamente do terminal como parte de fluxos autonomos de entrega contínua.
- **Instalação:**
  - **Mac:** `brew install gh`
  - **Linux:** `sudo apt install gh`

---

## 6. Automação e Testes de Interface (Browser)

### agent-browser
- **Descrição:** CLI de automação de navegadores baseada em Rust, projetada especificamente para Agentes de IA.
- **Por que ajuda as IAs:** Utiliza representação compacta da árvore de acessibilidade com referências determinísticas (`@e1`, `@e2`), consumindo 200–400 tokens (até 90% menos tokens que a leitura do DOM completo). Permite executar testes E2E, interagir com telas, validar fluxos e registrar evidências visuais.
- **Modo Visível Obrigatório:** Para que o operador acompanhe cada teste em tempo real na tela, execute sempre com a flag `--headed` (ex: `agent-browser --session <modulo>_<contexto?> open --headed <url>`) ou defina `export AGENT_BROWSER_HEADED=true`.
- **Isolamento Mandatório de Sessão e Contexto:** Toda execução DEVE acompanhar a flag `--session <modulo>_<contexto?>` (onde `<modulo>` é o `modulo-id` extraído de `memorias-ia/modulo.yml` e `<contexto?>` discrimina acessos como `interno`, `externo`, `cliente`, `anonimo`) ou garantir `export AGENT_BROWSER_SESSION=<modulo>_<contexto?>`. Previne fechamento indevido de processos e contaminação cruzada de cookies e tokens JWT entre diferentes perfis de usuário.
- **Pasta Obrigatória de Evidências (`.evidencias/`):** Todas as evidências geradas pelos testes automatizados (screenshots, capturas anotadas, vídeos, traces, relatórios) devem ser salvas obrigatoriamente na pasta `.evidencias/` na raiz do projeto (`mkdir -p .evidencias`).
- **Instalação:**
  - Com Bun (padrão): `bun i -g agent-browser && agent-browser install`
  - Com NPM: `npm install -g agent-browser && agent-browser install`
- **Documentação:** https://agent-browser.dev/

---

## 7. Utilitários Nativos do Framework .agent

### atualizar-submodulo.sh (`.agent/scripts/atualizar-submodulo.sh`)
- **Descrição:** Script de ciclo de vida acionado automaticamente via hook `PreInvocation` (`.agent/hooks.json`) ou manualmente via CLI.
- **Por que ajuda as IAs e Operadores:** Garante que o submódulo `.agent` esteja sincronizado na branch `master` remota no início de cada sessão de conversa (`1x por sessão`) e verifica automaticamente **uma vez por dia** se o runtime Bun está atualizado na versão estável mais recente executando `bun upgrade --stable` (controlado via trava diária `/tmp/.antigravity_bun_upgrade_date`).
- **Uso:** `bash .agent/scripts/atualizar-submodulo.sh`

### notificar.sh (`.agent/notificar.sh`)
- **Descrição:** Utilitário unificado de notificação para o Sistema Operacional, compatível nativamente com **Linux** e **macOS**.
- **Por que ajuda as IAs e Operadores:** Permite que comandos de longa duração (como `/plano.executar todos` e loops `/goal`) avisem o operador imediatamente no momento da conclusão, emitindo popup no desktop (KDE `kdialog`, FreeDesktop `notify-send` / `gdbus`, macOS Notification Center via `osascript`), som de alerta discreto (PipeWire, PulseAudio ou macOS `afplay`) e campainha no terminal (`\a`). Totalmente assíncrono, não-bloqueante e seguro para ambientes headless.
- **Uso:** `sh .agent/notificar.sh "<Título>" "<Mensagem>" [sucesso|aviso|erro]`

### upload-paiol-wiki.sh (`.agent/scripts/upload-paiol-wiki.sh`)
- **Descrição:** Utilitário de linha de comando para upload de arquivos e mídias da Wiki para o bucket público `wiki` no MinIO Paiol (`https://paiol.idz.one/wiki/...`).
- **Por que ajuda as IAs e Operadores:** Previne o inchaço (*bloat*) do Git da Wiki desacoplando binários pesados (PDFs, imagens em alta resolução, vídeos, capturas de tela e anexos), gerando links e snippets Markdown prontos para inclusão imediata na documentação.
- **Uso:** `sh .agent/scripts/upload-paiol-wiki.sh <caminho-do-arquivo> <slug-funcionalidade-ou-pagina> [modulo-override]`

### graphify.sh (`.agent/scripts/graphify.sh`)
- **Descrição:** Utilitário canônico de Grafo de Conhecimento (*Knowledge Graph*) do código-fonte baseado em `@sentropic/graphify`.
- **Por que ajuda as IAs:** Permite que o comando `/plano` e os agentes localizem símbolos, mapeiem dependências entre pacotes e calculem o raio de impacto em cascata (*Blast Radius*) em segundos sem varreduras cegas. Instala automaticamente o binário via Bun (`bun i -g @sentropic/graphify`) caso não exista na máquina, atualiza o `.gitignore` (`.graphify/`, `.engram/`, `graphify-out/`) e gera o grafo sob demanda (`ensure`).
- **Uso:**
  - `bash .agent/scripts/graphify.sh update` (reconstrói/atualiza o grafo AST)
  - `bash .agent/scripts/graphify.sh ensure` (garante instalação, `.gitignore` e grafo existente)
  - `bash .agent/scripts/graphify.sh query "<termo>" [budget]` (busca nós e arquivos no grafo)
  - `bash .agent/scripts/graphify.sh explain "<simbolo-ou-arquivo>"` (detalha conexões e imports)
  - `bash .agent/scripts/graphify.sh impact <arq1> [arq2...]` (calcula raio de impacto e lacunas de testes via `review-delta`)
  - `bash .agent/scripts/graphify.sh summary` (exibe principais hubs e comunidades do projeto)

---

## 8. Instalação Rápida (Copia e Cola)

Para instalar as ferramentas base de forma ágil e em lote, copie os blocos de comando abaixo e os rode inteiramente em seu terminal (requer `npm`, `bun` e `snap` já configurados).

### Linux (Debian / Ubuntu)

```bash
# 1. Atualizar e instalar ferramentas base do sistema
sudo apt-get update
sudo apt-get install -y ripgrep fd-find jq shellcheck bat tree eza httpie gh

# 2. Instalar ferramentas em Node
npm install -g @ast-grep/cli @biomejs/biome

# 3. Instalar automação de navegador e Grafo de Conhecimento para IA via Bun
bun i -g agent-browser @sentropic/graphify && agent-browser install

# 4. Instalar yq via snap 
sudo snap install yq
```

### macOS (via Homebrew)

```bash
# Instalar utilitários essenciais
brew install ripgrep fd ast-grep jq yq shellcheck bat tree eza httpie gh
npm install -g @biomejs/biome
bun i -g agent-browser @sentropic/graphify && agent-browser install
```