# WU Framework 4.0 e CLI 1.2: atualização e migração
Novidades, mudanças incompatíveis, validação e suporte para migrar para Framework 4.0.0 e CLI 1.2.0.
Este guia cobre WU Framework **4.0.0** e WU CLI **1.2.0**. Framework 4 é uma versão principal porque agora rejeita operações aceitas em versões anteriores. Atualizar a CLI não migra automaticamente o código das suas aplicações.
## O que muda
- **Framework:** hooks com identidade e permissões da aplicação, SSR com dados privados por requisição, cancelamento e limites de concorrência; sincronização de caminhos aninhados; supervisão e replay cooperativo. Veja [confiabilidade do runtime](/pt/docs/framework/runtime-reliability/) e [adapters](/pt/docs/framework/api-adapters/).
- **Segurança:** origem remota explícita, autenticação mútua do relay MCP, propriedade de contratos, validação de `.wuapp`, permissões de workflows de IA e nonces CSP por resposta. Veja [segurança](/pt/docs/framework/security/).
- **CLI:** dependências e catálogos, resolução por aplicação, compilação paralela e invalidação de cache por configuração; servidor de desenvolvimento restrito a hosts autorizados; builds com hashes de conteúdo e implantação consistente de assets. Veja [dependências](/pt/docs/cli/dependencies/), [desenvolvimento](/pt/docs/cli/development/) e [build](/pt/docs/cli/build/).
A CLI 1.2 alinha `WU_D003` à versão do Framework no catálogo. O diagnóstico distingue dependências incompatíveis de um projeto válido com Framework 4. Também corrige a execução de comandos de build com caminhos entre aspas no Windows.
## 1. Preparar uma atualização reversível
Salve código, manifests e lockfiles em um commit e preserve o artefato de produção anterior. Atualize primeiro em uma branch e ambiente de teste. Instale versões exatas e confira qual executável está usando.
```sh
npm view wu-framework@4.0.0 version
npm view @wu-framework/cli@1.2.0 version
npm install --global @wu-framework/cli@1.2.0 --include=optional
wu --version
```
Em um workspace existente, consulte `wu upgrade --help`, execute `wu upgrade` e revise o diff. A ferramenta atualiza dependências e arquivos de integração; não reescreve grants, hooks nem contratos de negócio. Depois execute `wu install`. Em projetos sem CLI, atualize `wu-framework` para `4.0.0` nos pacotes que o declaram e use seu gerenciador de dependências.
## 2. Corrigir mudanças incompatíveis
**Hooks e store.** Hooks dentro de uma microapp não herdam mais a autoridade do host. Solicite permissões em `manifest.wu.permissions` e conceda-as em `grants` do shell. Só a interseção é efetiva. Um emit negado retorna `false`; assinaturas ou acesso ao store podem lançar `WU_EVENT_SUBSCRIBE_DENIED` ou `WU_CAPABILITY_DENIED`. Conceda os canais e caminhos realmente usados pela aplicação.
```js
const permissions = [
"store.read:cart.*", "store.write:cart.*",
"events.emit:cart:changed", "events.subscribe:cart:changed",
];
await wu.registerApp({
name: "cart", url: "/apps/cart/", sandbox: "module",
manifest: { name: "cart", entry: "index.js", wu: { permissions } },
grants: permissions,
});
```
**Aplicações remotas.** `connect` e `waitForPort` exigem `hostOrigin`. Use a origem exata do shell; `"*"` aceita deliberadamente qualquer origem. A entrada deve corresponder à origem da URL registrada (`WU_REMOTE_ORIGIN_MISMATCH`). Apps remotas na mesma origem exigem `iframe.allowSameOrigin: true`; `wu.detach()` rejeita apps remotas com `WU_WINDOW_REMOTE_UNSUPPORTED`. Veja [apps remotas](/pt/docs/framework/remote-apps/).
**MCP e CSP.** Atualize o relay junto com o runtime: o bridge 4.0 usa autenticação mútua HMAC v2 e exige token. `ws://` é recusado fora de loopback. O modo inseguro é explícito e apenas local. No middleware SSR, substitua nonce fixo por `nonce: () => createNonce()` para gerar um por resposta. Veja [MCP](/pt/docs/framework/api-mcp/) e [streaming e segurança](/pt/docs/framework/streaming-security/).
**Contratos e pacotes.** Não sobrescreva a capability de outro provedor (`WU_CAPABILITY_OWNED`); revogue-a ou desmonte o provedor antes da troca. Instalar `.wuapp` sobre uma aplicação registrada pelo host exige `{ replace: true }`. `restore()` valida entradas salvas. Trate erros por `error.code`, não pelo texto da mensagem. Aguarde lifecycles assíncronos com `await`.
**CLI e implantação.** Adicione hosts de túneis a `dev.allowedHosts`; apenas chaves `VITE_*` e `WU_*` do `.env` são expostas ao cliente. Esses prefixos não servem para segredos. Revise `shared` quando apps precisarem de uma única instância. Publique o `dist/` completo; preserve assets anteriores com hash enquanto páginas antigas estiverem abertas e revalide HTML/manifests. Veja [configuração](/pt/docs/cli/configuration/) e [implantação](/pt/docs/cli/serve/).
## 3. Validar e reverter se necessário
```sh
wu doctor --json
wu contracts check
wu test
wu build
wu serve 4100 --mode static
```
Verifique montagem, atualização e desmontagem, permissões negadas, recarga direta, SSR/hidratação, CSP, RPC e reconexão remota conforme os recursos usados. Teste `wu build --native` separadamente, se aplicável. Verifique também uma aba aberta antes da implantação. Em caso de falha, restaure juntos o commit, lockfile e artefato anteriores; não misture runtime novo com relay ou assets incompatíveis.
## Algo quebrou? Podemos ajudar
A equipe WU ajuda a diagnosticar problemas de atualização. [Solicite suporte de migração](/pt/support/#migration-help) ou abra uma issue no repositório do produto. Inclua versões anterior e nova, `wu --version`, `npm ls wu-framework`, sistema/navegador, código do erro e reprodução mínima sem segredos. Explique o que funcionava antes e o resultado esperado. O suporte comunitário não implica prazo garantido de resposta.