Communitygithub.com

JayFarei/opentraces

Corrigir todo bug relacionado ao site no main, implantar opentraces.ai em produção na Vercel, e verificar se funciona em todas as páginas (desktop + mobile) e no fluxo de captura de e-mail, corrigindo e reimplantando até ficar verde. Executa como uma meta: land -> deploy -> verify -> triage -> repeat até seguro. Use quando o usuário disser "implantar site", "deploy na vercel", "publicar site", "enviar o site", "implantar-site" ou "land e verificar o site". Para um lançamento coordenado completo que também incrementa a versão e publica os pacotes Python, use /release-pack.

O que é opentraces?

Esta skill automatiza a implantação do site Next.js de marketing (web/site/) do OpenTraces na Vercel como uma meta de loop fechado, não apenas um comando único. Ela garante que todas as correções relacionadas ao site sejam commitadas e enviadas para o branch main, implantadas em produção, e verificadas exaustivamente em todas as rotas nos viewports desktop e mobile, incluindo o fluxo de captura de e-mail (EarlyAccessForm -> API /api/waitlist). A skill executa em quatro fases: (0) escopo e landing de correções com verificação local e build, (1) implantação na Vercel (evitando a flag --archive=tgz que causa timeouts), (2) verificação em produção usando uma ferramenta determinística Workflow que distribui verificações entre workers de navegador efêmeros, e (3) triagem e iteração se alguma rota falhar, repetindo até que todas estejam verdes. Ela é projetada para as plataformas Claude Code, Cursor e Codex (qualquer agente que suporte o protocolo de habilidades com ferramentas Workflow/ultracode). A skill define condições claras de DONE (todas as rotas retornam 200, sem erros de console/rede, captura de e-mail completada e limpa), NOT DONE (repetir o loop com correções) e BLOCKED (parar e relatar após 3 tentativas falhas ou bloqueio de credencial). Inclui regras rigorosas para não poluir a lista de espera de produção (usando endereços de e-mail taggados e honeypot) e documenta o arquivo .vercelignore correto na raiz do repositório (não em web/site/) para uploads eficientes de ~628 arquivos, em vez de ~3 GB com --archive=tgz.

Funciona com✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/JayFarei/opentraces/tree/HEAD/.claude/skills/deploy-site

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Implantar Site

Implante o site de marketing Next.js (web/site/) em produção na Vercel, mas trate-o como uma meta, não como um comando único: corrija todos os bugs relacionados ao site no main, implante-o, prove que funciona em produção em todas as páginas e no fluxo de captura de e-mail em desktop e mobile, e continue corrigindo + reimplantando até que tudo esteja verde.

Contrato da meta

Execute esta skill como um loop fechado. Não declare sucesso apenas com uma implantação limpa na Vercel; um deploy pode ser bem-sucedido enquanto uma página retorna 500, um layout quebra no mobile, ou a escrita da lista de espera falha silenciosamente.

  • DONE quando: todas as correções relacionadas ao site são commitadas e enviadas para main, o deploy de produção foi bem-sucedido, cada rota abaixo retorna 200 e renderiza corretamente em desktop e mobile sem erros de console/rede, e o fluxo de captura de e-mail aceita um envio e o persiste (comprovado por leitura de admin), sem linhas de teste restantes.
  • NOT DONE (loop novamente) quando: qualquer rota falha ao renderizar, um layout quebra em um viewport, o console mostra erros, ou a captura de e-mail não faz o round-trip. Corrija na fonte, refaça o land, reimplante, reverifique.
  • BLOCKED (pare e relate) quando: uma correção precisa de uma credencial/decisão que você não tem (ex.: KV store inativo, token de admin ausente, autenticação Vercel expirada), ou a mesma falha sobrevive a 3 tentativas de correção. Relate a falha exata + o que você tentou; não faça loop infinitamente.

Mantenha um breve registro contínuo de cada iteração (o que falhou, o que você mudou, resultado da reverificação) para que o loop seja auditável. Se o usuário quiser isso como um /goal persistente, aponte a meta para esta skill e use as mesmas condições DONE/BLOCKED.

O loop

Fase 0  Escopo e land      reunir correções do site -> verificação local -> commit -> push main
Fase 1  Deploy              build -> npx vercel@latest --prod (da raiz do repositório)
Fase 2  Verificar (prod)    Workflow fan-out: rotas x viewports + captura de e-mail
Fase 3  Triagem             algum vermelho? corrija na fonte -> volte para Fase 0
                            tudo verde? -> DONE

Contexto

  • Projeto: opentraces na Vercel (escopo jayfareis-projects)
  • Framework: Next.js 16 (App Router)
  • Diretório raiz: Vercel configurado com raiz em web/site/
  • Domínio: opentraces.ai (produção: https://opentraces.ai)
  • Build: next build (executa de web/site/)
  • Versão: Leitura automática de src/opentraces/__init__.py no build via next.config.ts
  • Captura de e-mail: EarlyAccessForm envia para /api/waitlist (Upstash/KV em prod). Renderiza em / (via HubTeaser) e /hub. Veja a seção de Referência para seletores + leitura de admin.

Fase 0 — Escopo e land das correções do site

  1. Encontre o que é relacionado ao site e não foi enviado. A árvore de trabalho geralmente contém uma mistura de alterações de site + não-site. Faça land apenas das correções do site aqui (o resto é uma preocupação separada).

    git status --short web/site/
    git status --short -- ':!web/site/'   # alterações não-site, geralmente deixe-as
    git log --oneline origin/main..HEAD -- web/site/   # commits do site ainda não enviados
    
  2. Verificação local antes do land (portão). Execute o site contra o servidor de desenvolvimento já em execução e verifique a superfície alterada com agent-browser: claro + escuro, desktop + mobile, a interação específica que você mudou, mais console/rede limpos. Este é o portão pré-land; não cometa uma regressão visual (Se nenhum servidor de desenvolvimento estiver ativo, cd web/site && npm run dev em uma porta sobressalente, verifique e depois pare-o.)

  3. Build local (captura erros de tipo/build que o servidor de desenvolvimento esconde):

    cd web/site && npm run build
    

    Corrija qualquer falha de build antes de continuar.

  4. Commit no main e push. Por convenção do projeto, faça commit diretamente no main (não crie automaticamente um branch de recurso a menos que solicitado). Mantenha o commit escopo para a correção do site; co-autor do commit de acordo com a regra de rodapé do repositório.

    git add web/site/   # stage apenas as correções do site que você verificou
    git commit -m "fix(site): <o que mudou>"
    git push origin main
    

Fase 1 — Build & deploy

Implante da raiz do repositório (não web/site/), porque a Vercel resolve o diretório raiz das configurações do projeto (rootDirectory=web/site). Executar de dentro de web/site/ aninha o caminho duas vezes. Sempre fixe na versão mais recente da CLI (npx vercel@latest).

cd /caminho/para/raiz/do/repo
rm -rf web/site/.next kb/app/.next   # saída de build obsoleta; incha o upload
npx vercel@latest --prod --yes

NÃO use --archive=tgz (medido em 2026-06-26, CLI 54.x). --archive=tgz compacta toda a árvore de trabalho e ignora .vercelignore, então carrega .git-menos-nada-mais além de kb/, .otbox/, web/site/.next-test/, etc. — um upload de ~3 GB / 1998 arquivos que leva minutos e uma vez travou por ~20 min em "Extracting deployment files" na máquina de build (uma parada real de produção que encontramos). O caminho padrão arquivo por arquivo em vercel@latest ao invés disso:

  • respeita .vercelignore → ~628 arquivos / ~40 MB,
  • envia em ~2 s e atinge READY em ~60 s ponta a ponta,
  • não atinge o Error: Upload aborted que --archive=tgz foi originalmente adicionado para evitar (isso foi um bug de endpoint brew 41.x; vercel@latest o corrigiu, então a solução alternativa agora é líquido negativo).

Se uma CLI futura regredir o caminho arquivo por arquivo e você precisar recorrer a --archive=tgz, espere o arquivo de ~3 GB e uma extração de vários minutos (ocasionalmente travando) — repita o deploy se ele travar na extração.

Capture a URL/id do deployment da saída; você fará referência a ela no relatório de verificação.

Dica: você pode verificar um deploy preview da Vercel primeiro (omitindo --prod) e executar a Fase 2 contra a URL de preview antes de promover. Isso mantém os testes de captura de e-mail completamente fora da lista de produção.


Fase 2 — Verificar em produção (JIT harness via Workflow / ultracode)

Comprove que o site ativo funciona. Esta fase é um just-in-time harness: você (o planejador) escopo a execução para este deploy, a ferramenta Workflow (o runtime determinístico) a executa, e workers de navegador efêmeros cada um retorna contra um schema tipado. O estado intermediário vive nas variáveis do harness, não no seu contexto, então a matriz completa é executada sem preencher sua janela. Esta skill opta explicitamente pela orquestração do Workflow (ultracode).

O harness é empacotado e congelado ao lado desta skill: verify-site-deploy.workflow.js. Não cole o script inline; execute o arquivo.

O que verificar

  • Rotas (cada uma deve 200 + renderizar, sem erros de console/rede): /, /explorer, /hub, /schema, /docs, mais uma verificação spot de páginas profundas: /schema/0.6.0, /docs/getting-started/installation, /docs/cli/commands, /docs/schema/trace-record.
  • Viewports: desktop 1440x900 e mobile 390x844 (classe iPhone). Onde uma correção mexeu com theming, verifique também claro + escuro.
  • Por página: HTTP 200, conteúdo primário visível, sem overflow/clipping de layout no viewport, console limpo, sem requisições de rede falhas, navegação funciona.
  • Captura de e-mail (seu próprio agente, veja abaixo).

Verificação de captura de e-mail (não polua a lista de produção)

/api/waitlist escreve em um armazenamento ativo e não tem endpoint DELETE, então seja deliberado:

  • Round-trip real (uma vez, desktop): envie um endereço taggado como deploy-verify-<timestamp>@opentraces.ai. Espere HTTP 200 {ok:true} e o botão mudando para o estado de sucesso. Confirme que foi persistido com a leitura de admin (GET /api/waitlist + Authorization: Bearer $WAITLIST_ADMIN_TOKEN), anotando a contagem antes/depois. Em seguida, limpe-o removendo essa linha do armazenamento (Upstash ZREM), e releia para confirmar que a contagem voltou. Deixe a lista imaculada.
  • Caminho de dedup: envie o mesmo endereço duas vezes, espere "você já está na lista" com a contagem inalterada.
  • Mobile + verificações repetidas de UI sem escrever: preencha o honeypot oculto (input[name=company]) no envio. O endpoint retorna um falso-sucesso silencioso e nunca armazena a linha, então você pode confirmar a UI de sucesso no mobile sem adicionar lixo. (Se você vir "sucesso" mas a contagem não se moveu, isso é o honeypot funcionando, não um bug.)
  • Se o endpoint retornar 503 ("waitlist is not configured"), o KV store não está conectado nesse deployment: isso é BLOCKED (problema de env/store), não uma correção de código. Relate.

Execute o harness

Invoque o artefato empacotado com a ferramenta Workflow. Escopo por deploy com args (este é o passo de "planejamento" JIT):

Workflow({
  scriptPath: ".claude/skills/deploy-site/verify-site-deploy.workflow.js",
  args: {
    baseUrl: "https://www.opentraces.ai",  // host canônico; ou uma URL de preview para manter e-mail fora de produção
    changed: ["/hub", "/"],             // rotas que este deploy mexeu -> verificação profunda; o resto é fumado
    pagesOnly: false                    // true = pular a escrita de e-mail (validação somente leitura executa)
  }
})

Isso retorna { base, scoped, failures, allGreen }. allGreen: true significa que a Fase 2 passou; caso contrário failures lista exatamente o que corrigir na Fase 3.

Como o harness aplica os primitivos JIT (veja kb/docs/concept-jit-harnesses-generic.md):

  • Classificar e rotear: se você passar changed, essas rotas recebem uma verificação completa do navegador (console, overflow, screenshot); toda outra rota é apenas um status curl barato. Fluxo de controle JS puro que o runtime possui, nenhum modelo no meio, então um deploy escopo permanece barato.
  • Um worker de varredura determinístico por viewport (2 workers, não ~18): cada um executa um único lote bash fixo (curl + um conjunto limitado de chamadas agent-browser por rota) em um modelo barato (haiku) e retorna o JSON analisado. Sem prompt aberto "verificar tudo", então o modelo não pode fazer loop; cada lote abre uma sessão de navegador e close --all nela, para que processos Chrome não se acumulem. (Validado em 2026-06-09: ~16s para uma varredura completa de viewport, 1 processo residual, vs. o design original por célula de 54 processos / 15+ min.)
  • Confirmação adversária independente: qualquer rota que uma varredura sinalizar como falha é re-verificada por um worker separado com uma sessão limpa (modelo padrão) que tenta reproduzi-la; uma falha sobrevive apenas se a confirmação também falhar, então um fumble do agent-browser não se mascara como um bug do site.
  • Contratos tipados: todo worker retorna contra PAGE_VERDICT / EMAIL_VERDICT, então os resultados se mesclam mecanicamente.
  • Captura de e-mail tem seu próprio worker que prova a escrita via uma leitura de admin independente e limpa a linha de teste (veja as regras de não poluição acima).

Para alterar a matriz, a política de profundidade ou o schema de veredito, edite o arquivo .js, ele é a única fonte da verdade. Se a mudança for uma página e você não quiser orquestração, você ainda pode executar a verificação dessa página sequencialmente com a skill agent-browser na sessão principal.


Fase 3 — Triagem & iterar

Leia os failures do workflow:

  • Vazio -> a meta foi alcançada. Relate: id/URL do deployment, rotas verificadas, viewports, round-trip de e-mail comprovado e limpo. DONE.
  • Não vazio -> para cada falha, encontre a causa raiz no código fonte de web/site/, corrija-a e volte para Fase 0 (verificação local -> commit -> push -> deploy -> reverificar). Re-execute a verificação escopo nas rotas que falharam primeiro, depois uma passagem completa quando estiverem verdes.
  • Após 3 tentativas malsucedidas na mesma falha, ou em um bloqueio de credencial/store/auth, pare e relate como BLOCKED com o erro exato e o que você tentou.

Registre cada iteração no log contínuo para que o loop seja auditável.


.vercelignore

Localização importa: o arquivo efetivo é o .vercelignore da raiz do repositório. Mesmo que o Root Directory do projeto seja web/site, todo o repositório é enviado (o build lê ../../src/opentraces/__init__.py e ../../skill/SKILL.md), e o único .vercelignore que o upload arquivo por arquivo honra é o da raiz do repositório — os padrões são correspondidos relativos à raiz do repositório. Um web/site/.vercelignore é ignorado; não adicione um (verificado em 2026-06-26 via npx vercel@latest --debug).

É uma lista de ignore positiva (diretórios enumerados explicitamente, não um catch-all * com negações ! — negações são frágeis e quebram entre versões da CLI). Sem ele, o upload inclui as árvores pesadas do repositório. As grandes que ele deve excluir (cada uma foi um vazamento real que corrigimos):

  • kb/ (~2.4 G), .claude/ (~1.5 G), tests/ (~1.4 G), .venv*/ (~0.8 G)
  • .otbox/ (~613 M de tarballs de snapshots)
  • web/site/.next-test/ (~98 M / 1000+ arquivos — note que **/.next/ não corresponde ao sufixo -test, então .next-test/ precisa de sua própria regra)
  • web/viewer/, web/coming-soon/, web/metrics-worker/

Caveat: .vercelignore apenas filtra o caminho de upload arquivo por arquivo. A flag --archive=tgz o ignora (veja Fase 1 — outra razão para não usá-lo).

Para verificar sanidade do que seria enviado após editar .vercelignore, execute npx vercel@latest --debug da raiz do repositório e leia a linha Found N files … M required to upload, depois Ctrl-C — nenhum deploy completo necessário. Um deploy de site saudável é ~628 arquivos, não ~2000.

Arquivos que NÃO devem ser ignorados (o build os lê no momento do build):

ArquivoLido porPropósito
src/opentraces/__init__.pynext.config.tsDetecção de versão para version.json
skill/SKILL.mdlib/docs.ts (getSkillContent())Conteúdo de visualização da máquina nas páginas de documentação

Se você adicionar um novo arquivo que o site lê no momento do build via um caminho relativo como ../../foo, garanta que ele não seja excluído por .vercelignore.

Referência

Rotas (matriz da Fase 2): /, /explorer, /hub, /schema, /schema/[version], /docs, /docs/[[...slug]] (~36 slugs de docs de lib/doc-nav.ts). API: /api/waitlist (POST add, GET admin read), /api/stars.

Seletores do formulário de e-mail (EarlyAccessForm.tsx): input de e-mail input[type=email] / aria-label="email address" / .ea-input; submit button.ea-btn ("get early access" -> loading -> success); honeypot oculto input[name=company] (preenchê-lo -> falso-sucesso silencioso, nunca armazenado).

Leitura de admin da lista de espera: GET /api/waitlist com Authorization: Bearer $WAITLIST_ADMIN_TOKEN. Retorna um array JSON de inscrições ordenado por score (ts). O token está em WAITLIST_ADMIN_TOKEN (no ambiente Vercel jayfareis-projects, ou no arquivo local .env.local). Se falhar com 401/403, verifique se o token ainda é válido.

Viewports: Desktop = 1440x900 (ou 1280x800 se a tela física for limitada). Mobile = 390x844 (iPhone 14 Pro). Onde uma correção muda layout/padding/margins, adicione uma verificação tablet 768x1024 — a maioria dos quebras de layout do site aparece nesse viewport antes do desktop.


SKILL.md corresponde ao arquivo de habilidade implantável. Para alterações, edite skill/deploy-site/SKILL.md na fonte.

Habilidades Relacionadas