feat(ci): testes automatizados (Vitest) e workflow no GitHub Actions

[guimelotto]

Resumo

Este PR adiciona testes automatizados (Vitest + Supertest), scripts locais para validar o mesmo que o CI, e um workflow GitHub Actions que roda em PRs e em push para master e develop.

Base: develop. A branch foi rebaseada em develop após o merge da PR #5, então o diff deste PR contém apenas o trabalho de CI/testes.

---

O que mudou no código

Área	Detalhe
API	Novo src/jobsApiApp.js com createJobsApiApp({ outputDir }); src/server.js só carrega dotenv, instancia o app e faz listen.
Testes	test/config.test.js — contrato de getConfig (paths, keywords, TIME_FILTER). test/jobsApi.test.js — HTTP em memória com diretório temporário (health, 404, leitura de .xlsx).
npm	npm test, npm run test:watch, npm run validate, npm run validate:ci (espelho do CI com npm ci).
CI	.github/workflows/ci.yml: Node 22, npm ci na raiz → testes → npm ci --prefix frontend → lint → build.
Docs	README: seção Testes e CI com comandos e referência ao workflow.

Nenhuma alteração de comportamento das rotas em produção além da extração da fábrica do app.

---

Como validar localmente (antes de aprovar)

Com dependências já instaladas:

npm run validate

Espelho completo do que o runner do GitHub faz (reinstala com lockfile):

npm run validate:ci

---

Configurações no GitHub (para o dono do repositório)

Siga na ordem. Caminhos usam a interface web atual do GitHub (podem mudar levemente de nome).

1. Garantir que o workflow rode ao menos uma vez

• Abra a aba Actions do repositório.
• Se for a primeira vez com workflows, confirme que Actions estão habilitadas em Settings → Actions → General (permissão padrão para workflows de leitura/gravação conforme a política da org).

2. Exigir o check do CI antes do merge (recomendado)

1. Vá em Settings do repositório (aba superior).
2. No menu lateral: Rules → Rulesets (ou Branches → Branch protection rules, em repositórios mais antigos).
3. Crie ou edite uma regra para a branch develop (e repita para master se quiser o mesmo rigor no release).

Se usar Branch protection rules (clássico):

• Branch name pattern: develop
• Ative Require status checks to pass before merging
• Em Status checks that are required, procure e marque o job do workflow:
  • Nome do workflow: CI
  • Nome do job: validate (aparece como CI / validate na lista após o workflow ter rodado pelo menos uma vez nesta branch ou em um PR).
• Opcional: Require branches to be up to date before merging (reduz merges com develop defasado).

Se usar Rulesets:

• Adicione uma ruleset com target em develop (ref: refs/heads/develop).
• Inclua a regra Require status checks to pass.
• Adicione o check validate do workflow CI (só listado após primeira execução).

Importante: os checks só aparecem na lista depois que o arquivo .github/workflows/ci.yml já existir na branch default ou no PR e o workflow tiver completado ao menos uma execução. Se não aparecer, faça merge deste PR (ou rode o workflow manualmente em Actions → CI → Run workflow na branch desejada, se disponível).

3. Permissões do GITHUB_TOKEN (se o CI falhar por permissão)

Em Settings → Actions → General → Workflow permissions:

• Em muitos casos Read and write permissions não é necessário só para npm ci/test/build.
• Se a organização restringir o token, use Read repository contents and packages permissions e confira se checkout + npm funcionam (normalmente sim).

4. Opcional: merge queue / conversas

• Merge queue: útil com muitos PRs; não é obrigatório para começar.
• Require conversation resolution: útil se usarem reviews com threads.

---

Depois do merge

• Novos PRs contra develop (e pushes listados no on: do YAML) disparam o CI automaticamente.
• Contribuidores podem usar npm run validate antes de abrir PR para evitar falhas no runner.

---

Referências rápidas

• Documentação GitHub: About branch protection
• Documentação GitHub: Workflow syntax