SQL Terminal Agent

Neste desafio, você irá construir uma aplicação de terminal em Node.js capaz de processar um arquivo de logs potencialmente grande, armazenar esses dados em um banco SQLite e responder perguntas em linguagem natural usando IA para criar consultas SQL.

O objetivo é praticar fundamentos do runtime do Node.js em um projeto que combina entrada e saída via terminal, leitura eficiente de arquivos grandes com streams, banco de dados nativo, variáveis de ambiente, testes e integração com um modelo de linguagem.

Contexto

Times de tecnologia costumam lidar com grandes volumes de logs para entender comportamento de usuários, acessos, falhas, padrões de uso e métricas operacionais.

Neste projeto, você irá simular esse cenário a partir de um arquivo de logs de acesso. A aplicação deve ler esse arquivo de forma eficiente, ingerir os dados em um banco SQLite e disponibilizar um agente de terminal que permite fazer perguntas como:

Quantos acessos existem no banco?
Quais empresas aparecem nos logs?
Quais cargos acessaram o sistema recentemente?
Qual cidade teve mais acessos?

A geração de um arquivo de logs falso pode ser usada apenas como apoio para desenvolvimento e testes. O propósito central do desafio é lidar com a leitura e o processamento de um arquivo grande sem carregá-lo inteiro em memória.

Depois da ingestão, a aplicação deve transformar a pergunta em uma consulta SQL, mostrar a query sugerida, pedir confirmação antes de executar e então gerar uma resposta textual baseada nos dados retornados.

Propósito Didático

Este desafio foi pensado para reforçar conceitos importantes do runtime do Node.js:

• Execução de scripts com Node.js.
• Uso de módulos nativos como node:fs, node:readline, node:sqlite, node:util e node:test.
• Leitura e processamento de arquivos grandes com streams.
• Processamento linha a linha sem carregar todo o arquivo em memória.
• Leitura linha a linha de arquivos .log.
• Persistência de dados com SQLite.
• Criação de uma interface interativa no terminal.
• Uso de variáveis de ambiente com --env-file.
• Integração com uma API de IA.
• Validação e segurança básica antes da execução de SQL.
• Escrita de testes usando o test runner nativo do Node.js.

Funcionalidades Esperadas

Ao final do desafio, a aplicação deve oferecer os seguintes recursos:

• Ler um arquivo access.log com registros de acesso.
• Processar o arquivo linha a linha usando streams.
• Ignorar linhas vazias ou inválidas durante o processamento.
• Inserir os registros em um banco SQLite e sua respectiva tabela.
• Abrir uma interface interativa no terminal para receber perguntas do usuário.
• Enviar a pergunta para um modelo de IA e obter uma sugestão de SQL.
• Exibir a SQL sugerida e uma explicação antes da execução.
• Pedir confirmação do usuário antes de executar a query.
• Executar apenas consultas seguras de leitura.
• Gerar uma resposta em português com base nas linhas retornadas pelo banco.
• Encerrar a aplicação corretamente ao pressionar CTRL+C.

Especificações Técnicas

Banco de Dados

Use SQLite por meio do módulo nativo node:sqlite.

A aplicação deve criar uma tabela chamada access_logs com os seguintes campos:

CREATE TABLE IF NOT EXISTS access_logs (
  ip TEXT NOT NULL,
  username TEXT NOT NULL,
  first_name TEXT NOT NULL,
  last_name TEXT NOT NULL,
  email TEXT NOT NULL,
  location TEXT NOT NULL,
  job_area TEXT NOT NULL,
  company TEXT NOT NULL,
  job_title TEXT NOT NULL,

Arquivo de Logs

O projeto trabalha com um arquivo access.log contendo registros de acesso.

Cada linha do arquivo deve conter um objeto JSON independente, seguindo o formato JSON Lines:

{"ip":"192.168.0.1","username":"johndoe","first_name":"John","last_name":"Doe","email":"john@example.com","location":"Sao Paulo","job_area":"Engineering","company":"Rocketseat","job_title":"Developer","id":"uuid","timestamp":"2026-06-15T10:00:00.000Z"}

Para facilitar o desenvolvimento, você pode ter um script auxiliar de seed responsável por gerar registros falsos nesse formato. Esse script também deve seguir como forma de praticar a escrita de arquivos usando streams.

Ingestão dos Dados

O script de ingestão é uma das partes centrais do desafio. Ele deve:

• Abrir o arquivo access.log como stream de leitura.
• Ler o conteúdo linha a linha.
• Ignorar linhas vazias.
• Ignorar linhas que não sejam JSON válido.
• Inserir cada registro válido na tabela access_logs.
• Exibir progresso a cada intervalo definido no projeto.
• Fechar a conexão com o banco ao final.

Agente de Terminal

O script principal deve iniciar uma interface interativa no terminal.

Fluxo esperado:

1. O usuário digita uma pergunta em linguagem natural.
2. A aplicação envia a pergunta para o modelo de IA.
3. O modelo retorna um objeto contendo sql e explanation.
4. A aplicação valida a SQL gerada.
5. A aplicação exibe a SQL sugerida e sua explicação.
6. O usuário confirma se deseja executar a consulta.
7. A aplicação executa a query no SQLite.
8. A aplicação envia os dados retornados para o modelo gerar uma resposta textual.
9. A resposta final é exibida no terminal.

Segurança da SQL

A aplicação deve executar apenas consultas de leitura.

Bloqueie comandos como:

INSERT, UPDATE, DELETE, DROP, ALTER, CREATE, REPLACE, PRAGMA, ATTACH, DETACH, VACUUM

Também é recomendável orientar o modelo a:

• Gerar apenas SELECT.
• Não gerar múltiplas queries.
• Não incluir comentários SQL.

Exemplos de Perguntas

Use perguntas como estas para testar a aplicação:

• Quantos registros existem no banco?
• Quais são os 10 acessos mais recentes?
• Quais cidades aparecem nos logs?
• Qual empresa possui mais acessos?
• Quantos acessos existem por cargo?
• Quais usuários acessaram mais recentemente?
• Quais áreas de trabalho aparecem com maior frequência?

Dicas

• @faker-js/faker](https://github.com/faker-js/faker): pode ser usada no script auxiliar de seed para gerar dados falsos de usuários, empresas, cargos, cidades, IPs, e-mails, UUIDs e timestamps.
• ai](https://github.com/vercel/ai): pode ser usada para integrar a aplicação com modelos de linguagem e gerar respostas a partir das perguntas feitas no terminal.
• @ai-sdk/openai](https://github.com/vercel/ai): provider da OpenAI para o AI SDK, útil para conectar o projeto aos modelos da OpenAI usando a variável OPENAI_API_KEY.
• zod](https://github.com/colinhacks/zod): pode ser usada para definir o formato esperado da resposta da IA, validando objetos como { sql, explanation } antes de executar qualquer consulta.

Regras Importantes

• Não execute SQL destrutivo gerado pela IA.
• Não armazene chaves de API no repositório.
• Não versionar arquivos gerados como access.log, logs.db ou .env.local.
• A aplicação deve continuar funcionando mesmo quando encontrar linhas inválidas no arquivo de log.
• O encerramento com CTRL+C deve fechar recursos abertos, como a conexão com o banco.