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 é:

{
  "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 (MongoDB Shell) se estiver instalado no SO, rodando o comando:

mongosh <URI> --quiet --eval 'EJSON.stringify(db.getCollection("<NOME_COLLECTION>").<OPERACAO>(<JSON_QUERY>).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 <RAIZ_DO_PROJETO>/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 → ❌                            │
└─────────────────────────────────────────────────────────────┘