E1 · Ver o validador reprovar
3 minRode o bloco do validador.
Pronto quando: node scripts/validar-catalogo.mjs catalogos/ruim.mjs; echo "saída: $?" → CATÁLOGO: 4 ferramentas · 5 erros · 8 avisos e saída: 1; o do kit → 0 erros e saída: 0.
Aula 7 · 18 min
Desenhar o catálogo e migrar um site existente sem quebrar ninguém
Um catálogo bom tem poucas ferramentas, cada uma com uma intenção, nome com verbo, entrada mínima e erro que o agente entende. Num site que já existe, a regra sai da interface para uma função que atende o clique e a ferramenta. Nesta aula você revisa um catálogo ruim com o validador e planeja a migração do seu site.
Começar a aula
Nesta aula você vai
- 1Uma intenção por ferramenta, nome com verbo, entrada mínima
- 2O validador do kit: regras da spec e regras do curso
- 3Erro que o agente entende: devolver { erro } em vez de lançar
- 4Migrar: inventário, regra compartilhada, wrapper fino, fallback
Objetivo: desenhar um catálogo pequeno (uma intenção por ferramenta), revisá-lo com o validador e integrá-lo a um site existente com detecção e fallback.
01Migrar sem quebrar quem não tem a API
Clique em cada etapa.
Clique em cada bloco do diagrama para ver o que ele faz.
Etapas adaptadas dos módulos de integração da formação antiga, agora com a API de 16/10/2026.
02Regras de um bom catálogo
As que o validador confere e as que só você pode conferir.
1. Intenção
Duas ferramentas que respondem ao mesmo pedido obrigam o agente a adivinhar.
Comece pela jornada da pessoa, não pela lista de botões.
Bom
buscar_oficinas · reservar_vaga · minhas_reservas
2. Descrição
Diga o efeito, o que a ferramenta não faz e quando usar.
"Faz coisas" e "gerencia" não ajudam ninguém a escolher.
Kit
Lista as oficinas da agenda por tema. Só lê: não reserva nada.
3. Entrada
Só os campos necessários, enum quando a lista é fechada, additionalProperties: false.
Valide de novo no execute: no Chromium 156, a entrada inválida chegou ao execute (medido no kit).
4. Erro
Se o execute lança, o agente recebe só UnknownError, sem o motivo (Chromium 156).
Erro de regra volta como { erro: 'tema inválido: cobol' }; throw só para o inesperado.
Kit
comErroUtil(fn) em kit/pagina/ferramentas.mjs
03O validador contra um catálogo ruim
validar-catalogo.mjs lê as definições sem abrir navegador nem executar nada. Erro reprova (saída 1); aviso não.
Terminal · catálogo ruim e o do kit
cd ~/projetos/formacao-webmcp-site-v72/kit node scripts/validar-catalogo.mjs catalogos/ruim.mjs; echo "saída: $?" node scripts/validar-catalogo.mjs; echo "saída: $?"
Exemplo do repositório
ERRO fazer tudo
erro: nome fora da regra (1–128: letras, números, _ - .)
aviso: descrição curta: diga o que faz, o que NÃO faz e quando usar
aviso: sem inputSchema
aviso: diga se só lê (readOnlyHint) ou se tem consequência (consequentialHint)
ERRO buscar
erro: anotação readOnlyHint não é true/false
aviso: descrição curta: diga o que faz, o que NÃO faz e quando usar
aviso: inputSchema aceita campo extra (use additionalProperties: false)
aviso: campo "q" sem description
ERRO cancelar_reserva
erro: nome de ação com efeito sem consequentialHint
ERRO ver_agenda
erro: descrição vazia
erro: anotação desconhecida: readOnly
aviso: sem inputSchema
aviso: diga se só lê (readOnlyHint) ou se tem consequência (consequentialHint)
CATÁLOGO: 4 ferramentas · 5 erros · 8 avisos
saída: 1
OK buscar_oficinas
OK listar_comentarios
OK reservar_vaga
OK minhas_reservas
CATÁLOGO: 4 ferramentas · 0 erros · 0 avisos
saída: 0Regras da spec: nome, descrição não vazia, nomes únicos. Regras do curso: schema object fechado e descrito, anotações conhecidas e coerentes, nome de ação com efeito marcado com consequentialHint.
04Em framework: registrar ao montar, abortar ao desmontar
Modelo para adaptar (não roda no kit). Angular tem suporte experimental, segundo a doc do Chrome de 07/10/2026; o padrão abaixo vale para qualquer um.
Modelo · componente React
useEffect(() => {
const mc = document.modelContext;
if (!mc) return; // sem a API: a tela segue igual
const ciclo = new AbortController();
registrar(mc, catalogo(agenda, ui), ciclo.signal).catch(() => {});
return () => ciclo.abort(); // desmontou: as ferramentas saem
}, [agenda]);Modelo · JavaScript sem framework
// entrar na tela const ciclo = new AbortController(); if (document.modelContext) await registrar(document.modelContext, defsDaTela, ciclo.signal); // sair da tela (rota nova, modal fechado) ciclo.abort();
05Prática
Validador e o plano do seu site. Cada exercício termina num pronto quando.
E2 · Consertar o catálogo ruim
15 minCopie catalogos/ruim.mjs para catalogos/meu.mjs e corrija até zerar os erros: nome sem espaço, descrição útil, anotação booleana e conhecida, cancelar_reserva com consequentialHint.
Pronto quando: node scripts/validar-catalogo.mjs catalogos/meu.mjs; echo "saída: $?" → 0 erros e saída: 0.
E3 · Inventário do seu site
20 minPara o seu site, escreva o inventário (formulário → handler → serviço → endpoint) e escolha 3 ferramentas: 2 que só leem e 1 com efeito, com a tela de confirmação.
Pronto quando: Um arquivo catalogo-[seu site].md com as 3 ferramentas (nome, descrição, entrada, anotação) e a regra compartilhada de cada uma.
06Teste da aula
A explicação aparece depois da resposta.
Pergunta 1 de 4
O execute lança Error('sem vaga'). O que o agente recebe no Chromium 156?
Correto
Medido em 19/10/2026: UnknownError genérico. A spec de 16/10 lista OperationError para esse caso; o build mede outra coisa. Erro de regra volta como { erro } para o agente poder corrigir.Não é essa
Medido em 19/10/2026: UnknownError genérico. A spec de 16/10 lista OperationError para esse caso; o build mede outra coisa. Erro de regra volta como { erro } para o agente poder corrigir.Rever: Regras de um bom catálogoPergunta 2 de 4
Onde fica a regra de reservar num site migrado?
Correto
A mesma função atende os dois caminhos: assim não há duas regras para divergir. O execute é um wrapper fino. Validar de novo no servidor continua obrigatório.Não é essa
A mesma função atende os dois caminhos: assim não há duas regras para divergir. O execute é um wrapper fino. Validar de novo no servidor continua obrigatório.Rever: Migrar sem quebrar quem não tem a APIPergunta 3 de 4
Qual destes catálogos tem o problema de intenção duplicada?
Correto
Buscar oficinas e procurar cursos respondem ao mesmo pedido: o agente precisa adivinhar. Os outros pares têm intenções diferentes.Não é essa
Buscar oficinas e procurar cursos respondem ao mesmo pedido: o agente precisa adivinhar. Os outros pares têm intenções diferentes.Rever: Regras de um bom catálogoPergunta 4 de 4
Por que a migração termina no modo Sem?
Correto
Sem data de estável e sem Safari e Firefox, quem não tem a API é a maioria. Se o site quebra para eles, a migração falhou, por mais ferramentas que tenha.Não é essa
Sem data de estável e sem Safari e Firefox, quem não tem a API é a maioria. Se o site quebra para eles, a migração falhou, por mais ferramentas que tenha.Rever: Migrar sem quebrar quem não tem a APITeste concluído
Você acertou {a} de {n}. Acertando todas, a aula é marcada como concluída.Escolha uma alternativa. A explicação aparece depois da sua tentativa.
07Em três frases
CatálogoPoucas ferramentas, uma intenção cada, entrada fechada e erro devolvido como dado.
ValidadorRegras da spec e do curso, sem navegador: rode antes de publicar.
MigraçãoInventário, regra compartilhada, wrapper fino e o site igual no modo Sem.