Havia dois runbooks sobrepostos, escritos para o piloto, e nenhum documento do
ambiente de homologação.
- `20-homologacao-runbook.md` consolida os dois e cobre DNS, TLS, Nginx,
Supabase de homologação, banco com a decisão do shim, bucket privado,
containers, worker, observabilidade, flag, rollback, diagnóstico e smoke.
Os dois runbooks antigos ficam no repositório marcados como histórico,
preservando o registro das decisões.
- Rollback de imagem com comandos: identificar o que está no ar, listar tags,
desligar a flag antes de trocar, subir só web e worker com `--no-deps`,
conferir saúde, religar a flag. As migrations de segurança — RLS e auditoria
append-only — estão declaradas sem caminho de volta: desfazê-las afrouxa o
isolamento entre workspaces, então um rollback que precise disso está errado
por definição.
- `21-checklist-validacao.md` separa o que foi executado do que depende de
infraestrutura, com a evidência de cada item e a tabela dos quatro defeitos
encontrados. Nada está marcado PASS por inspeção de código.
- ADR 0007 registra o ambiente lógico e a autenticação de homologação, com as
alternativas descartadas e o motivo.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
O CI rodava lint, typecheck, testes e build, e nada mais: os drivers de
Postgres e Redis nunca eram exercitados, e não havia build de imagem nem
pipeline de deploy.
- Job `services`: Postgres e Redis efêmeros. Roda a suíte de serviços, aplica
as quatro migrations, confere idempotência, confere que `--dry-run` não
altera nada e que o shim é pulado com ADAPTER_APPLY_IDENTITY_SHIM=0.
- Job `image`: build da imagem Linux e validação do artefato. Conteúdo de
runtime, usuário não-root, ausência de .env, docs, testes e vitest na
imagem, os oito scripts operacionais transformando e executando, entrypoint
recusando subcomando desconhecido, fail-fast com código diferente de zero
na web e no worker, liveness com cabeçalhos de segurança, compose completo
até `ready`, heartbeat do worker, jornada assíncrona entre processos e
desligamento gracioso exigindo `SIGTERM recebido` em menos de 25s.
- `.github/scripts/async-journey.sh` percorre web → Redis → worker → download
dos três formatos, atravessando a fronteira de processo que a suíte de
testes não cobre.
- Deploy com gatilho único `workflow_dispatch`: não há deploy automático em
push, tag ou merge. Migration, deploy e liberação da feature flag são jobs
separados, cada um com seu ambiente de aprovação manual.
- Nenhum segredo entra em comando de shell. Um input de workflow interpolado
em `run:` é injeção, então `workspace_id` passa por variável de ambiente e
é validado como UUID antes de qualquer escrita. O deploy usa heredoc citado
e `permissions: contents: read` no topo.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Os 34 testes existentes batiam só na camada de serviço: as rotas, o proxy e o
loop do worker não tinham cobertura alguma. A suíte vai de 34 para 102.
- `tests/http/`: rotas reais com o caminho real de autenticação, sem subir
servidor. Cobre 401 sem sessão, módulo desligado, papel sem permissão, 403
ao tentar gravar workspace de terceiro, e 429 com Retry-After.
- `tests/http/proxy.test.ts`: o proxy não propaga query da requisição para o
login, o que impediria um returnTo forjado.
- `tests/integration/worker.test.ts`: jornada assíncrona pelo loop real. A web
enfileira e devolve `queued`, o download falha antes do tick, o tick conclui
e os três formatos saem. Também: job sobrevive à perda da fila do Redis,
worker relê o contexto e não processa com a flag desligada, TTL expira
temporários sem tocar o modelo, e desligamento gracioso.
- `tests/unit/dev-auth-guard.test.ts`: matriz de ambientes das três barreiras
do login local. Um token de dev válido é recusado quando o ambiente é
staging. Espaço em volta de um valor de ADAPTER_ENV é tolerado de propósito,
e isso está declarado no teste; valor desconhecido nunca vira development.
- `tests/services/`: Postgres e Redis reais. Confere `app_user` sem
BYPASSRLS, FORCE RLS em todas as tabelas, isolamento entre workspaces,
auditoria não alterável pelo papel da aplicação, e lock entre conexões
diferentes. Sem as variáveis de serviço os casos são IGNORADOS, nunca
aprovados, e ficam fora de `npm test` para a suíte padrão passar em
qualquer máquina.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Não existia nenhum artefato de deploy: sem Dockerfile, sem compose, sem pin de
Node. O runbook pedia `npm run start` e `npm run worker` à mão, o que não é um
ambiente reproduzível, e o worker dependia de `tsx`, uma devDependency, que
`npm ci --omit=dev` removeria.
- Dockerfile multistage. Web e worker saem da mesma imagem: mesmo código,
mesmas dependências, só o subcomando difere.
- `tsx` foi para `dependencies`. Conferido em diretório limpo: os 13 pacotes
externos que src e scripts usam existem no install de produção.
- A sobreposição das duas árvores de node_modules é segura e foi medida: 318
pacotes em produção contra 153 traçados, zero divergência de versão entre os
compartilhados, e 3 que existem só na traçada, que o COPY mescla sem
remover. O package.json do standalone não é sobrescrito.
- Entrypoint com subcomandos, que garante `node --import tsx` em todos os
scripts. Usar `node` direto convidaria de volta o defeito do SIGTERM.
- Healthcheck de liveness na web e de heartbeat no worker.
- Compose local reproduz a topologia com Postgres e Redis de verdade. Compose
de homologação não declara Postgres (é o banco gerenciado), usa Redis
isolado com senha e volume próprios, publica porta só em 127.0.0.1 e tem
nome de projeto, rede e volume exclusivos. Nenhum serviço de outro
aplicativo do ecossistema é declarado, tocado ou reiniciado.
- `.env.staging.example` sem segredo, `.nvmrc`, `engines` e `packageManager`.
- `config/staging-seed.json` e `.env.staging` no gitignore.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Os quatro apareceram ao exercitar o layout de runtime da imagem — apenas
node_modules de produção, src, scripts e migrations — e nenhum aparecia na
suíte de testes nem no build. Os dois primeiros formavam uma armadilha mútua.
1. O CLI do `tsx` cria processo filho (PIDs medidos: 20840 contra 21096).
O SIGTERM do `docker stop` pararia no pai, o worker nunca rodaria o
handler, o lock esperaria o TTL de 120s e o `stop_grace_period` só
atrasaria um SIGKILL. Passa a ser `node --import tsx`, mesmo processo.
2. Top-level await nos scripts falha com `--import tsx`, porque sem
`"type": "module"` o esbuild gera CJS. `migrate`, `worker`, `seed-staging`,
`flag`, `cleanup` e `check-bucket` não executariam: a migração não rodaria
e o worker não subiria. `runScript`/`runWithDb` resolvem sem mudar o
module type do projeto.
3. `import "server-only"` em `worker-loop.ts`: o pacote lança fora do bundler
do Next, e o worker morria no start.
4. `@react-pdf/renderer` carregado no import de `process-job.ts` falha com
ERR_PACKAGE_PATH_NOT_EXPORTED ao resolver a hifenização fora do bundler,
derrubando worker e cleanup. O PDF sai sob demanda no download, então o
import passou a ser tardio, dentro do ramo que o usa.
Além disso:
- O loop do worker saiu do script para `worker-loop.ts`, testável sem subir
processo. O script cuida só de sinais, cadência e bootstrap.
- Desligamento gracioso espera o tick corrente para o `finally` liberar o
lock. Um job que ainda não começou fica `queued`: nada pela metade.
- Heartbeat por tick, lido pelo healthcheck do contêiner. Processo vivo mas
travado passa em qualquer verificação de PID.
- O worker recusa iniciar com migration pendente, e relê o contexto do dono a
cada job: papel e feature flag podem ter mudado desde o enfileiramento.
- `verify-config`, `check-bucket`, `seed-staging` e `smoke-staging` novos. O
smoke tem fase autenticada que só roda com credencial fornecida pela
operação e, sem ela, reporta PENDENTE em vez de aprovado.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
- `/api/health/live` não toca dependência: distingue processo vivo de
dependência fora do ar. `/api/health/ready` passou a tocar banco, migrations
pendentes, Redis com PING, bucket com listagem, configuração e modo de job,
e reporta em `reasons` só o nome do erro — nunca connection string.
- Configuração inválida encerra o processo. Antes o servidor ficava no ar
respondendo 500 em todas as rotas, inclusive no liveness, enganando o
orquestrador: pior que não subir.
- CSP, HSTS, Permissions-Policy e COOP, além dos três cabeçalhos que já
existiam. `unsafe-inline` em script-src é exigência do bootstrap do App
Router sem nonce; o resto é fechado e connect-src só aceita o próprio host,
o Supabase do ambiente e o Sentry.
- `onRequestError` registrado: sem esse export os erros de rota e de render
do servidor não chegavam ao Sentry. O ambiente do evento deriva de
ADAPTER_ENV, então homologação e produção não se misturam.
- `withSentryConfig` só atua quando organização, projeto e token existem no
build, para não quebrar build local nem CI.
- `output: "standalone"` para a imagem de runtime.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Duas lacunas impediam qualquer uso de homologação. Primeira: sem SSO do Elo
Pro e sem o login local, não havia como entrar. Segunda, mais grave: nada no
repositório gravava o cookie `elo_pro_workspace_id`, que era lido como origem
do workspace ativo — mesmo com sessão válida a resposta era sempre "sem
workspace".
- `identity-provider.ts` define o contrato de identidade. Trocar o Supabase de
homologação pelo SSO do Elo Pro passa a ser acrescentar uma implementação;
nenhum outro arquivo conhece o mecanismo.
- `/api/auth/staging/session` autentica com `signInWithPassword` no projeto
Supabase de homologação. Há senha, emitida e validada pelo Supabase, e o
Adaptador continua sem tabela de usuário, senha ou sessão própria.
- O login local sem senha existe apenas em `ADAPTER_ENV=development`, e não
por configuração: fora de development o provedor nem entra na lista.
- `workspace.ts` resolve o workspace por associação real lida sob RLS. O
cookie passa a ser preferência, não prova: aceitá-lo como autorização
transformava um valor editável pelo cliente em credencial.
- `/api/auth/workspace` grava a preferência só depois de confirmar a
associação, e `/selecionar-workspace` existe para quem participa de mais de
um workspace.
- Rate limiting por usuário e bucket nas rotas do módulo, com Retry-After.
Upload e processamento custam muito mais que leitura.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
`next start` força NODE_ENV=production, então homologação não tinha como se
distinguir de produção: o login local ficava desligado (correto) e o módulo
exigia o SSO do Elo Pro, que ainda não existe. Não havia terceiro caminho.
- `ADAPTER_ENV` com development, staging e production, independente de
NODE_ENV. Toda política passa a derivar dele.
- Fail-fast de configuração em `fail-fast.ts`, separado de `env.ts` porque
`process.exit` não existe no Edge Runtime.
- `requireDatabaseUrl` elimina o fallback silencioso para PGlite: um segredo
ausente em staging migrava um arquivo local e parecia sucesso.
- Shim de identidade passa a ser decisão explícita via
`ADAPTER_APPLY_IDENTITY_SHIM`; aplicá-lo sobre o schema real do Elo Pro é
destrutivo em potencial.
- `migration-manifest.ts` responde o estado do schema consultando só o banco.
Ler o diretório numa rota fazia o Next tracear o projeto inteiro para a
saída standalone, levando docs, testes e fontes para a imagem.
- Redis e Supabase viram singleton por processo. Criar um ioredis por
requisição vazava conexão: o cliente é lazy, abre no primeiro uso e nunca
fecha.
- Namespace de chaves deriva de ADAPTER_NAMESPACE e do ambiente lógico, não
de SENTRY_ENVIRONMENT. Observabilidade e isolamento de dados são decisões
diferentes, e a variável única fazia homologação e produção colidirem.
- Listagem do bucket passa a paginar e descer em subpastas. Parando em 1000
entradas, a limpeza por TTL deixava de ver arquivos e temporários venciam
sem nunca ser removidos.
- `ping` e `hit` no coordenador, e `healthcheck` no armazenamento, para o
health check tocar as dependências de verdade.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
O módulo usa a identidade Supabase, isola cada workspace e registra storage, TTL, runner e biblioteca XLSX como decisões ainda abertas.
Co-authored-by: Cursor <cursoragent@cursor.com>
