Edge Function Imports — Política de Specifiers Remotos

Bloqueante: Edge Functions em supabase/functions/ só podem importar de npm:, jsr: ou https://deno.land/std@<v>/.... esm.sh é proibido. O CI falha via scripts/audit/no-esm-sh-imports.ts e o teste Deno sentinela _shared/__tests__/no-esm-sh-imports.test.ts.

Por que

esm.sh é um CDN público atrás de Cloudflare. Quando ele responde 522 "origin unreachable" — coisa que aconteceu em produção em 2026-05-09 — o deno cache aborta com exit 1 e toda a suíte deno-tests cai sem qualquer mudança no nosso código. É um SPOF externo gratuito.

npm: resolve via registry oficial do npmjs.org (cacheado pelo runner) e jsr: via JSR (Deno-managed). Ambos são estáveis em ordens de magnitude superiores ao esm.sh.

Specifiers permitidos

Forma	Status	Exemplo
npm:<pacote>@<versão>	✅ canônico	npm:@supabase/supabase-js@2.49.1
jsr:@scope/<pacote>@<versão>	✅ aceito	jsr:@std/assert@1.0.0
https://deno.land/std@<v>/...	✅ aceito	https://deno.land/std@0.224.0/fs/walk.ts
https://esm.sh/...	❌ proibido	—
https://unpkg.com/..., cdn.skypack.dev	❌ proibido	(mesma classe de SPOF)

Como migrar

// ❌ Antes
import { z } from "https://esm.sh/zod@3.23.8";
import { SupabaseClient } from "https://esm.sh/@supabase/supabase-js@2.49.1";

// ✅ Depois
import { z } from "npm:zod@3.23.8";
import type { SupabaseClient } from "npm:@supabase/supabase-js@2.49.1";

Pegadinha — usado só como tipo? Use import type para eliminar o custo de runtime (e a dependência transitiva, se for o único uso do pacote).

Camadas de defesa no CI

1. Guard estático — scripts/audit/no-esm-sh-imports.ts roda no job lint-and-build antes de qualquer instalação. Falha com annotation ::error file=...,line=...:: direto no PR e sugere o npm: equivalente.
2. Sentinela Deno — _shared/__tests__/no-esm-sh-imports.test.ts roda junto com os outros sentinels (PII, ntfy, diff). Garante consistência com @audit segurança mesmo se o guard estático for desabilitado.
3. Diagnóstico automático — scripts/ci/diagnose-esm-sh-failure.sh roda if: failure() no job deno-tests e escreve no $GITHUB_STEP_SUMMARY a explicação do 522 do esm.sh (causa, ação, links). Não falha o job — só anota.

Comandos úteis

# Local — antes do PR
bun run lint:edge-imports

# Direto via Deno
deno run --allow-read --no-lock scripts/audit/no-esm-sh-imports.ts

# Sentinela Deno
cd supabase/functions && deno test --allow-read --no-lock _shared/__tests__/no-esm-sh-imports.test.ts

Histórico

• 2026-05-09 — incidente: esm.sh retornou 522 ao baixar @supabase/supabase-js@2.49.1 durante deno-tests. Suíte caiu inteira sem regressão de código. Migrado o único import e criado este guard. Ver docs/audits/AUDIT_TEST_BREAKAGE_2026-05-09.md.

Referências

• docs/development/TEST_ERROR_PLAYBOOK.md — caso "522 esm.sh"
• docs/development/NEW_EDGE_FUNCTION.md — checklist de novas functions
• mem://infrastructure/supabase/edge-function-registration-standard