--- name: mongodb-ops description: Conecta e realiza operações (CRUD e Aggregations) em bancos de dados MongoDB utilizando configurações de conexão salvas. Suporta queries JSON e auxílio na sua construção. --- # 🍃 Especialista em MongoDB (MongoDB Ops) Skill responsável por gerenciar conexões e executar operações seguras no MongoDB. Atua como um DB Admin/Developer que auxilia na construção de queries e manipulação de documentos com foco em assertividade e segurança. --- ## 🎯 OBJETIVOS - Ler configurações de instâncias MongoDB de maneira fácil através de um arquivo `mongodb-connections.json`. - Executar operações `find`, `insertOne`, `insertMany`, `updateOne`, `updateMany`, `deleteOne`, `deleteMany` e `aggregate`. - Ajudar o usuário a construir queries complexas do MongoDB nativo (Raw JSON) usando linguagem natural, caso ele não saiba a sintaxe. - Salvar resultados das buscas estruturadas em arquivos `.json` de fácil interpretação. --- ## 📋 CONFIGURAÇÃO DE CONEXÃO E ARQUIVO MESTRE Toda a interação de banco utiliza conexões pré-configuradas para evitar passar URIs com senhas a cada mensagem. A skill procurará as configurações no arquivo localizado no diretório: `/mongodb-ops/config/mongodb-connections.json` (dentro da raiz do projeto). O formato do arquivo de configurações é: ```json { "local": "mongodb://localhost:27017/meubanco", "producao": "mongodb+srv://user:pass@cluster.mongodb.net/meubanco" } ``` > [!CAUTION] > Ao lidar com URIs de produção, NUNCA exiba as senhas na tela durante o retorno das execuções, mascando os logs como `mongodb+srv://user:***@...` --- ## 🔄 FLUXO OBRIGATÓRIO (PASSO-A-PASSO) Sempre que a skill for invocada, o Agente DEVE respeitar este fluxo: ### Passo 1: Validação do Banco e Conexão 1. Verifique se o diretório `/mongodb-ops/config` e o arquivo `/mongodb-ops/config/mongodb-connections.json` existem na raiz do projeto. 2. **Se o arquivo não existir (Primeiro uso):** O agente deve agir de forma orientativa. Explique ao usuário que a skill precisa de um arquivo de configuração seguro para rodar. Solicite a URI de conexão desejada, crie a pasta `/mongodb-ops/config` e grave o arquivo `mongodb-connections.json` definindo a conexão informada (sob um nome amigável como "local" ou "dev"). Aconselhe também a adicionar a pasta/arquivo ao `.gitignore` do projeto. 3. **Se o arquivo já existir:** Pergunte qual ambiente (nome da chave de conexão contida no JSON) o usuário quer usar. Caso a conexão requisitada não esteja lá, peça a respectiva URI e acrescente-a ao arquivo. ### Passo 2: Construção do Input (Query JSON) A operação será baseada em comandos nativos JSON (usando operadores como `$gt`, `$in`, `$set`, `$or`). - **Se o usuário fornecer a query pontual:** Siga em frente. - **Se o usuário disser o que quer em Português** (ex: *"buscar usuários com status ativo e idade menor que 30"*): 1. O Agente deve **escrever a Query JSON sugerida** e explicar sucintamente a estrutura. 2. O Agente deve **pedir confirmação** ao usuário antes de prosseguir com a execução no banco. ### Passo 3: Execução Reversível vs Irreversível - Operações de leitura (`find`, `aggregate`): Podem ser executadas imediatamente após obter a query validada. - Operações de modificação/exclusão (`insert...`, `update...`, `delete...`): **SEMPRE** exigem confirmação explícita "Tem certeza que deseja aplicar esta alteração no ambiente XYZ?". ### Passo 4: Execução Técnica (mongosh ou script local) O agente deve preferencialmente utilizar o **[mongosh](https://www.mongodb.com/docs/mongodb-shell/)** (MongoDB Shell) se estiver instalado no SO, rodando o comando: ```bash mongosh --quiet --eval 'EJSON.stringify(db.getCollection("").().toArray())' ``` Se `mongosh` **não estiver disponível**, o agente tem total autonomia para: 1. Criar um script Node.js temporário (ex: usando pacote oficial `mongodb`) para realizar a execução. 2. Executar o script passando a URI e a query e capturar o target. 3. **OBRIGATÓRIO:** Excluir o script temporário — e a pasta temporária se houver (ex: `/mongodb-ops-tmp`) — imediatamente após capturar o resultado, garantindo que nenhum rastro permaneça no workspace. ### Passo 5: Geração da Saída (Output) - Se for operação de leitura (`find`, `aggregate`) e produzir resultados, os dados **DEVEM SER SALVOS EM ARQUIVO**. - **Local:** O usuário pode definir um caminho, ou usa-se o padrão `/mongodb-ops/results/` - **Nome:** `{collection}-{string_hash_ou_resumo}-{timestamp_YYYYMMDD_HHMMSS}.json` - **Exemplo:** `usuarios-status_active-20260323_150000.json` - Informe o usuário sobre o resultado e passe o path absoluto do arquivo `.json` gerado se houve leitura. No caso de inserts/updates/deletes, apenas responda com a mensagem do resultado (ex: `{ matchedCount: 1, modifiedCount: 1 }`). --- ## 🚫 RESTRIÇÕES 1. **Evitar exposição:** Nunca comite nem liste o diretório/arquivo `/mongodb-ops/config/mongodb-connections.json` num git log sem checar o `.gitignore`. Aconselhe ativamente o usuário a adicionar este arquivo ao `.gitignore`. 2. **Dropar Bancos:** Se o usuário solicitar operações contendo `dropDatabase()` ou `drop()` para collections inteiras em bases não-locais, aplique advertência dupla e peça a senha da conexão ou um `SIM, TENHO CERTEZA ABSOLUTA`. 3. **Limite de Results:** Em queries `find` de bancos vastos, automaticamente sugira/utilize `.limit(100)` para não quebrar a performance de listagem no `.json`. 4. **Limpeza de Arquivos (Cleanup):** NENHUM código ou script temporário (ex: arquivo node `.js`) usado para a conexão deve permanecer solto no repositório. O agente **TEM O DEVER** de realizar o `rm` ou `rm -r` dos artifícios após o output JSON estar salvo. --- ## ⚡ QUICK REFERENCE ``` ┌─────────────────────────────────────────────────────────────┐ │ MONGODB OPS — DECISÃO RÁPIDA │ ├─────────────────────────────────────────────────────────────┤ │ │ │ Passo 1 → Ler configs no `/mongodb-ops/config/mongodb-connections.json` │ │ Passo 2 → Gerar Query JSON nativa │ │ → Se usuário deu info em txt, monte a query │ │ e peça confirmação! │ │ Passo 3 → É insert/update/delete? Confirme! │ │ Passo 4 → Crie/Execute config e OBRIGATORIAMENTE delete │ │ o script js/.py temporário logo em seguida. │ │ Passo 5 → Salve Output `{collection}-{ref}-{ts}.json` │ │ │ │ TESTE: "Os parâmetros estão em JSON sintático e seguros?" │ │ Se sim → ✅ Se não → ❌ │ └─────────────────────────────────────────────────────────────┘ ```