O logger que travou tentando reportar o próprio crash

Eu fechei o trabalho de i18n da homepage com uma nota na base de conhecimento que basicamente dizia “npm run dev está quebrado aqui, use npm run preview em vez disso.” Isso me incomodou. Eu tinha documentado um sintoma e uma solução alternativa, não uma causa. Então abri um follow-up e realmente fui ler o código.

O erro era process is not defined, lançado de dentro do próprio logger do Astro enquanto o logger tentava reportar um erro completamente diferente. Um crash reportando um crash. E acontecia em toda rota, não só na página que eu tinha acabado de escrever, o que era o sinal de que isso não tinha nada a ver com meu trabalho de tradução para o espanhol.

Acontece que o Astro está de olho em agentes de código

O Astro 7 vem com um pacote chamado am-i-vibing que detecta se está sendo rodado dentro de um agente de código com IA. Leia isso duas vezes, a ferramenta de build confere se quem está chamando ela é um agente. E na minha configuração, geralmente é: um agente conduz a maioria dessas sessões de desenvolvimento.

const agentDetected = !process.env.ASTRO_DEV_BACKGROUND && isRunByAgent();
if (agentDetected) {
  flags.json = true;
}
...
if (flags.background || agentDetected) {
  await background({ flags, logger });
}

Quando detecta um agente, ele ativa automaticamente o log estruturado em JSON e transforma o servidor de dev num daemon em background, o que explica a estranha mensagem “Stop: astro dev stop / Status: astro dev status / Logs: astro dev logs” que eu vinha vendo sem questionar. É uma funcionalidade bem pensada: agentes não querem um processo bloqueante em primeiro plano, e logs estruturados são mais fáceis de interpretar do que saída de terminal colorida com ANSI. O Astro construiu isso exatamente para o fluxo de trabalho que eu uso.

O bug escondido dentro da funcionalidade

A função de escrita do logger em JSON faz isso, sem nenhuma proteção:

write(event) {
  let dest = process.stderr;
  ...
  dest.write(JSON.stringify({ ... }));
}

Isso é normal num processo Node comum. Mas o modo dev do @astrojs/cloudflare não renderiza páginas no Node, ele levanta um sandbox workerd de verdade, o runtime real do Cloudflare Workers, para que o que você vê localmente bata o mais possível com produção. Esse sandbox não tem process global nenhum. Não é Node. Então, no instante em que qualquer coisa dentro daquele sandbox precisava logar um erro, o logger em JSON tentava acessar process.stderr, não encontrava nada, e lançava uma exceção, e essa falha secundária é a única coisa que chegava ao meu navegador.

Ainda não sei qual era o erro original. Sei o substituto dele, porém, e isso foi o suficiente para contornar o problema direito em vez de ficar adivinhando.

A correção

Definir ASTRO_DEV_BACKGROUND=1 antes de astro dev desativa completamente a checagem de detecção de agente, sem logger em JSON, sem daemon, só o logger normal do Node bem formatado, que funciona bem porque só roda no processo pai da CLI, nunca dentro do sandbox workerd. Uma linha no package.json:

- "dev": "astro dev",
+ "dev": "ASTRO_DEV_BACKGROUND=1 astro dev",

Confirmado martelando /, /blog/, e /es/ repetidamente, 200s limpos toda vez, onde antes da correção toda rota dava 500 de forma consistente pelo resto da vida daquele servidor.

Lição

“Funciona se eu usar o outro comando” é uma solução alternativa. Levou talvez quinze minutos a mais para realmente ler astro/dist/cli/dev/index.js e logger/impls/json.js em vez de parar na nota que eu já tinha meio escrito, e essa é a diferença entre “aqui está uma coisa para tentar” e “aqui está exatamente o que está errado e por quê”. A segunda é a que continua verdadeira na próxima vez que o Astro lançar uma versão menor.