Skill de Revisão de Build WASM & TinyGo

Verificações de tripla de destino, tamanho de binário e uso indevido de syscall/js para agentes - uma Skill de Agente estilo cookbook para builds WASM Go 1.26 e TinyGo.

O Que Esta Skill Faz

Produz uma checklist de revisão de build WASM: GOOS/GOARCH corretos, syscall/js vs syscall/wasmimport, tags de destino TinyGo, orçamentos de tamanho, compatibilidade do runtime do host (wazero, wasmtime) e importações proibidas - antes do merge.

Quando Invocar

• PR adiciona targets de build GOOS=wasip1 GOARCH=wasm
• Alterações de firmware TinyGo ou módulos WASM restritos
• Agente cria scaffolds WASM de navegador com syscall/js
• Regressão de tamanho de binário em implantação de ponta
• Integração de host com runtime wazero

Entradas

Saídas

• Tabela de validação de tripla de destino
• Achados de uso indevido de importação/syscall
• Comandos de relatório de tamanho (wasm-objdump, twiggy, tinygo size)
• Snippet de teste de fumaça do host para wazero
• Comandos de build de verificação

Guardrails

1. Sem syscall/js em módulos WASI - API exclusiva do navegador.
2. Sem cgo na compilação cruzada WASM padrão, a menos que haja exceção documentada.
3. TinyGo - verifique a placa e o scheduler; o stdlib completo do Go pode não se aplicar.
4. Orçamento de tamanho - bloqueie novas dependências pesadas sem justificativa.
5. Não use os/exec ou sockets brutos em WASM sem documentação de capacidade do host.
6. API wazero - verifique na build; fixe no cabeçalho da skill.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

# Módulo WASI (Go 1.26)
GOOS=wasip1 GOARCH=wasm go build -o app.wasm ./cmd/wasi/
 
# Inspecionar exports e tamanho
wasm-objdump -x app.wasm | head -40
ls -la app.wasm
 
# Build restrita TinyGo (exemplo - verifique a placa)
tinygo build -target=wasi -o tiny.wasm ./cmd/edge/
 
# Smoke test wazero (host)
go test ./internal/wasmhost/... -run TestLoadModule -count=1

Quando usar esta skill:

• Equipe de ponta envia artefatos WASM de KB
• Agente usou fmt.Println e net/http em um rascunho WASM de navegador
• CI adicionou target WASM sem gate de tamanho

Exemplo de Trabalho

Passo 0 - Classificar o target

Veja Go em WebAssembly: Caminhos para Navegador, WASI e Embarcado

Passo 1 - Auditoria de importação

# Padrões proibidos em WASI
grep -rn 'syscall/js\|js\.Value' --include='*.go' ./cmd/wasi/
grep -rn 'cgo\|os/exec\|"net/http"' --include='*.go' ./cmd/wasi/

Passo 2 - Orçamento de tamanho

ls -la app.wasm
# Opcional: twiggy top para hosts vinculados a Rust; wasm-objdump para wasm Go

• Compare com o orçamento no ticket (por exemplo, 500 KB gzip)
• Veja Otimização de Tamanho WASM: TinyGo vs GC WASM

Passo 3 - Smoke test do host (wazero)

func TestLoadWASIModule(t *testing.T) {
    ctx := context.Background()
    r := wazero.NewRuntime(ctx)
    defer r.Close(ctx)
    mod, err := r.InstantiateWithConfig(ctx, wasmBytes,
        wazero.NewModuleConfig().WithStartFunctions("_initialize"))
    if err != nil {
        t.Fatal(err)
    }
    defer mod.Close(ctx)
}

• Verifique a instanciação, _initialize e run/main exportados de acordo com o contrato do módulo
• Veja Runtimes de Host WASI: Wasmtime, wazero e Spin

Passo 4 - Específico do TinyGo

tinygo flash -target=pico -size=short ./cmd/firmware/   # exemplo - verifique a placa

• Scheduler: evite bloqueios eternos sem yield do host
• Verifique as tags //go:build tinygo para caminhos de código divergentes

Análise Profunda

Melhorias no runtime WASM do Go 1.26 podem alterar o comportamento de alocação - reavalie o tamanho após a atualização da toolchain.

Veja Runtime WASM e Melhorias de Memória do Go 1.26

syscall/js requer callbacks DOM e limpeza de js.FuncOf - revise vazamentos em targets de navegador.

WASI preview vs wasip1: tags de build e matriz de capacidade do host devem corresponder ao ambiente de implantação.

Armadilhas

• Um único main para linux e wasm sem tags de build puxa importações erradas.
• Variáveis globais incham seções de inicialização WASM - prefira const e inicialização preguiçosa.
• Reflexão e fmt custam tamanho no TinyGo - audite strings de formato.
• Testando WASM em host macOS - garanta que a CI construa a mesma tripla que a produção.

Alternativas

FAQs

Relacionados

• Noções Básicas de Skills de Agente - estrutura SKILL.md
• Noções Básicas de WebAssembly e TinyGo - introdução WASM
• Compilando com GOOS=wasip1 GOARCH=wasm - build WASI
• syscall/js: Go no Navegador - API do navegador
• TinyGo para Microcontroladores e WASM Restrito - TinyGo
• Runtimes de Host WASI: Wasmtime, wazero e Spin - hosts

Versões da Stack: Esta página foi escrita para Go 1.26.x (padrão Green Tea GC, go fix modernizers - verifique o patch na build), chi (última versão - verifique na build), gin (última versão - verifique na build), echo (última versão - verifique na build), google.golang.org/grpc (última versão - verifique na build), sigs.k8s.io/controller-runtime (última versão - verifique na build), kubebuilder (última versão - verifique na build), tinygo (última versão - verifique os targets da placa na build), wazero (última versão - verifique na build) e golangci-lint (última versão - verifique o conjunto de linters na build).