# Instalação e versões

Pacote npm, binários por plataforma, atualização e compilação a partir de Zig.

Veja versões, mudanças e requisitos em [Framework 4.0 e CLI 1.2](/pt/docs/guides/releases/).


<span id="usar-la-distribución-npm"></span>

<span class="section-anchor" id="section-1"></span>

## Usar a distribuição npm

```bash
npm install -g @wu-framework/cli@1.2.0
wu --version
wu --help
```

O pacote publica o comando `wu` por meio de `bin/wu.js` e declara Node `>=20`. O launcher não compila Zig na instalação: procura um binário já empacotado para a plataforma. As dependências das aplicações são instaladas depois, dentro de um projeto, por meio de `wu install`.

Para uma invocação temporária do pacote, pode ser usado o executor do npm:

```bash
npx @wu-framework/cli@1.2.0 --version
```

Essa invocação continua exigindo o ambiente Node/npm e pode consultar o registro. Não equivale a executar o binário diretamente.

<span id="plataformas-seleccionadas-por-el-launcher"></span>

<span class="section-anchor" id="section-2"></span>

## Plataformas selecionadas pelo launcher

| Plataforma de Node | Arquitetura | Arquivo esperado em `bin/` |
| --- | --- | --- |
| `win32` | `x64` | `wu-win32-x64.exe` |
| `linux` | `x64` | `wu-linux-x64` |
| `linux` | `arm64` | `wu-linux-arm64` |
| `darwin` | `x64` | `wu-darwin-x64` |
| `darwin` | `arm64` | `wu-darwin-arm64` |

A release publica seis pacotes: o launcher e cinco pacotes opcionais `@wu-framework/cli-<os>-<cpu>`, fixados exatamente em `1.2.0`. npm seleciona a plataforma; Windows ARM64 usa o binário x64. O launcher verifica a versão e o SHA-256 contra `bin/SHA256SUMS`. Esta release também mantém os cinco binários dentro do pacote raiz como fallback.

No Unix, se o sistema rejeitar o binário com `EACCES`, o launcher tenta corrigir a permissão de execução e tenta novamente uma vez. No Windows, suas invocações internas do npm passam por `npm.cmd` por meio do interpretador do sistema.

Os binários Linux são builds musl estáticos e também executam no Alpine. A release usa ReleaseSafe e exatamente Zig `0.16.0`. Se faltarem pacotes opcionais, reinstale com `npm install -g @wu-framework/cli@1.2.0 --include=optional`; `wu update` já adiciona essa opção. Uma combinação não suportada, versão de pacote incorreta ou checksum diferente termina com diagnóstico e saída `1`.

<span id="actualizar"></span>

<span class="section-anchor" id="section-3"></span>

## Atualizar

```bash
wu update
```

O launcher consulta `@wu-framework/cli@latest`, valida a versão recebida e compara SemVer. Se ela for superior, executa uma instalação global dessa versão exata. Se não puder consultar o npm ou instalar, retorna 1. Não altera as dependências do framework dentro dos projetos.

O aviso passivo de atualização usa um cache de 24 horas, inclusive para consultas malsucedidas. `wu update` consulta novamente sem aguardar esse cache. A variável `WU_DISABLE_UPDATE_CHECK=1` ou um ambiente com `CI` omitem o aviso passivo; não desativam uma atualização solicitada explicitamente.

```powershell
$env:WU_DISABLE_UPDATE_CHECK = '1'
wu --version
```

Executar `wu.exe update` diretamente imprime que a atualização pertence ao launcher e termina com 1. Para atualizar, use o comando instalado pelo npm.

Atualizar a CLI não altera o projeto: continue com `wu upgrade --dry-run`, revise a migração para Framework 4, aplique com `wu upgrade --yes` e execute `wu install`. [Dependências e migração](/pt/docs/cli/dependencies/) explica pins, backups, codemods e códigos para CI.

<span id="construir-desde-el-código"></span>

<span class="section-anchor" id="section-4"></span>

## Construir a partir do código

`build.zig.zon` exige Zig **0.16.0** no mínimo. O pacote Zig não declara dependências externas e constrói um executável vinculado à libc.

```bash
zig build -Doptimize=ReleaseSafe
zig build test --summary all
zig build run -- --version
npm test
```

A etapa `run` transmite os argumentos posteriores a `--`. `npm test` verifica invariantes e testes Node do launcher/compilador; é uma suíte diferente dos blocos de teste Zig. Compilar não substitui os testes de navegador de uma aplicação gerada.

Para mantenedores: `npm run build:binaries` gera as cinco plataformas e seus checksums. `node scripts/publish.mjs` executa verificações e simula a publicação dos seis pacotes; apenas `--yes` publica. Exige árvore limpa, versões coerentes e binários válidos, e publica as plataformas antes do launcher. `npm publish` direto é rejeitado. Este procedimento distribui a CLI, não implanta uma app.

<span id="diagnóstico-de-instalación"></span>

<span class="section-anchor" id="section-5"></span>

## Diagnóstico da instalação

| Sintoma | Verificação |
| --- | --- |
| `wu` não é reconhecido | Verifique a instalação npm e se seu diretório de executáveis está no PATH |
| `no usable executable` | Verifique o binário empacotado ou construa o checkout com Zig |
| Versão inesperada | Execute `wu --version` e verifique qual executável o shell resolve |
| Compilador de Vue/Svelte ausente | Execute `wu install` dentro do projeto e revise as dependências da microapp |
| A atualização não chega ao registro | Revise a conectividade e a configuração npm; o aviso passivo não bloqueia o comando solicitado |

<span id="referencia-de-implementación"></span>

<span class="section-anchor" id="section-6"></span>

## Referência de implementação

- `wu-cli/package.json`
- `wu-cli/bin/wu.js`
- `wu-cli/scripts/build-all.mjs`
- `wu-cli/scripts/publish.mjs`
- `wu-cli/scripts/test-package.mjs`
- `wu-cli/tests/bin-wu.test.cjs`