CNPJ DB Runner

Executor Docker-first para agendar, orquestrar e monitorar execuções do CNPJ DB Loader.

O Runner não substitui o Loader. Ele apenas decide quando executar, com quais parâmetros, registra logs estruturados, mantém estado local e pode enviar webhooks.

Visão geral

CNPJ DB Runner
  agenda execuções
  executa o binário cnpj-db-loader
  captura stdout/stderr/exitCode
  controla uma execução por vez
  registra logs em json ou pretty
  mantém estado local
  envia webhook opcional

CNPJ DB Loader
  consulta a Receita Federal
  baixa, extrai, valida e sanitiza arquivos
  importa e materializa dados no PostgreSQL

Requisitos

• Node.js >=20
• npm
• PostgreSQL acessível pelo Loader
• Docker e Docker Compose para execução containerizada

O Runner usa o Loader publicado no npm público:

@danielarndt0/cnpj-db-loader

Instalação local

npm install
npm run check
npm run loader:version

Uso local da CLI

Durante o desenvolvimento:

npm run cli -- <command>

Exemplos:

npm run cli -- init
npm run cli -- print-config
npm run cli -- once
npm run cli -- once --pipeline-mode check_only --log-format pretty
npm run cli -- schedule

Após build:

npm run build
node dist/index.js once

Início rápido

npm run cli -- init
npm run cli -- secrets set postgresUrl "postgres://postgres:postgres@localhost:5432/cnpj"
npm run cli -- config set pipelineMode full_sync
npm run cli -- config set output.logFormat pretty
npm run cli -- once

Docker Compose

docker compose up -d --build
docker compose logs -f cnpj-db-runner

Criar configuração inicial dentro do volume Docker:

docker compose run --rm cnpj-db-runner init

Executar uma rodada manual no Docker:

docker compose run --rm cnpj-db-runner once --pipeline-mode check_only --log-format pretty

Documentação

| Documento | Conteúdo | | ------------------------------------------------- | ------------------------------------------------------- | | Primeiros passos | Instalação, configuração inicial e primeira execução. | | Comandos | Lista de comandos, flags e exemplos práticos. | | Configuração | config.json, secrets.json, .env e chaves aceitas. | | Pipelines | Modos de pipeline e estratégia de execução. | | Logs | Formatos json e pretty, cores e exemplos. | | Fluxos recomendados | Fluxo local, Docker, produção e troubleshooting. | | Docker | Dockerfile, Compose, volumes e publicação da imagem. | | Eventos e webhooks | Eventos emitidos, payloads e assinatura HMAC. | | Módulos internos | Organização técnica dos módulos do projeto. | | Desenvolvimento | Scripts, lint, build, testes e release. |

Scripts npm

| Script | Descrição | | -------------------------- | --------------------------------------- | | npm run cli -- <command> | Executa a CLI local em TypeScript. | | npm run build | Compila o projeto para dist. | | npm start | Executa node dist/index.js. | | npm run once | Executa uma rodada única. | | npm run doctor | Executa o doctor do Runner. | | npm run print-config | Mostra a configuração final mascarada. | | npm run typecheck | Executa validação TypeScript. | | npm run lint | Executa ESLint. | | npm test | Executa testes com Vitest. | | npm run check | Executa typecheck, lint e build. | | npm run cli -- --version | Mostra a versão do CNPJ DB Runner. | | npm run loader:version | Mostra a versão do CNPJ DB Loader. | | npm run loader:doctor | Executa diretamente o doctor do Loader. |

Licença

MIT