# Configuração e descoberta

Campos efetivamente lidos de wu.config.json, portas, comandos e metadados de montagem.

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


<span id="archivo-de-proyecto"></span>

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

## Arquivo do projeto

Os comandos procuram `wu.config.json` no diretório de trabalho. Não há uma flag global `--config` nem um comando `wu config`. Os caminhos são interpretados a partir da raiz em que a CLI é executada.

```json
{
  "name": "conocimiento",
  "version": "1.1.0",
  "shell": {
    "dir": "shell",
    "framework": "astro",
    "port": 4321,
    "dev_cmd": "npx astro dev",
    "build_cmd": "npx astro build"
  },
  "apps": [
    {
      "name": "busqueda",
      "dir": "mf-busqueda",
      "framework": "react",
      "port": 5001,
      "dev_cmd": "npx vite",
      "build_cmd": "npx vite build"
    },
    {
      "name": "explorador",
      "dir": "mf-explorador",
      "framework": "vue",
      "port": 5002
    }
  ],
  "proxy": {
    "port": 3000,
    "open_browser": false,
    "/api": {
      "target": "http://127.0.0.1:8080",
      "rewrite": true,
      "cors": false
    }
  },
  "shared": ["react", "react-dom/client"],
  "security": {
    "enabled": true
  }
}
```

`version` é um metadado de configuração. O executável continua usando a versão compilada em `main.zig`; editar esse campo não atualiza a CLI.

<span id="shell-y-aplicaciones"></span>

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

## Shell e aplicações

| Campo | Valor padrão | Uso |
| --- | --- | --- |
| `shell.dir` | `shell` | Diretório do anfitrião |
| `shell.framework` | `vanilla` | Seleciona o tratamento do shell |
| `shell.port` | `4321` | Porta do processo no modo Vite |
| `shell.dev_cmd` | String vazia | Comando do shell no modo Vite |
| `shell.build_cmd` | String vazia | Com fallback para Astro, Next ou Vite conforme o framework |
| `apps[].name` | String vazia | Identificador da app para o catálogo |
| `apps[].dir` | String vazia | Diretório local e chave de overrides |
| `apps[].framework` | `vanilla` | Seleção do compilador/template |
| `apps[].port` | `0` | Porta da app no modo Vite |
| `apps[].dev_cmd` | `npx vite` | Comando legado de desenvolvimento |
| `apps[].build_cmd` | `npx vite build` | Comando de construção |

O parser aceita apenas os campos que consome. Não valida uma topologia completa como faria um schema rigoroso: muitos valores do tipo incorreto mantêm o valor padrão. Declare explicitamente nomes, diretórios e portas e revise o resultado com `wu info`.

<span id="metadatos-que-llegan-al-navegador"></span>

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

## Metadados que chegam ao navegador

| Campo em cada app | Valores / significado |
| --- | --- |
| `fullBleed` ou `full_bleed` | Booleano para que o shell possa conceder a largura completa |
| `domOwnership` ou `dom_ownership` | `wu`, `app` ou `light` |
| `nativeShadow` ou `native_shadow` | Alias legado opcional; convém expressar o ownership explicitamente |
| `grants` | Lista de capacidades que o host concede no máximo |
| `compatibility` | `strict` ou `v2` |

Esses campos acompanham o catálogo de desenvolvimento e o resultado do build. Conceder um grant no host não substitui a solicitação correspondente em `wu.json`. `fullBleed` comunica uma preferência de apresentação; o shell deve consumi-la ao organizar o contêiner.

<span id="proxy-y-puertos"></span>

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

## Proxy e portas

No modo nativo, a prioridade da porta é `wu dev --port`, depois `proxy.port`, depois 3000. A prioridade de abertura é `--open` ou `--no-open`, depois `proxy.open_browser`, cujo padrão é `true`.

Cada chave de `proxy` que começa com `/` define uma regra. Pode ser uma string com a origem de destino ou um objeto com `target`, `rewrite` e `cors`. `rewrite: true` remove o prefixo: `/api/users` é encaminhado como `/users`. `cors` é opcional.

O proxy implementado aceita origens `http://`; rejeita TLS/`https://`, credenciais e destinos ambíguos. Não declare uma URL com caminhos como se fosse uma origem. As portas de `shell` e `apps` pertencem ao modo de processos Vite; não criam listeners separados no servidor nativo.

<span id="opciones-nuevas-de-desarrollo-y-build"></span>

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

## Novas opções de desenvolvimento e build

```json
{
  "dev": { "allowedHosts": ["mi-tunel.example.com"] },
  "build": { "keepPreviousBuilds": 2 },
  "security": { "upgradeInsecureRequests": false }
}
```

`dev.allowedHosts` (`allowed_hosts`) amplia os hosts permitidos para Host, CORS e WebSocket; não altera a interface de escuta. `build.keepPreviousBuilds` (`keep_previous_builds`) preserva arquivos com hash de builds anteriores, com padrão `2`. `security.upgradeInsecureRequests` (`upgrade_insecure_requests`) define explicitamente a diretiva CSP; quando ausente, WU a omite se `hsts` for `off` ou houver origens HTTP configuradas.

Recarregar a configuração preserva grants, modo de manifesto e opções de layout. Apps adicionadas entram no router e no watcher; salvar sem mudanças não força recarga. Diretórios `./mf-a` ou `mf-a/` são normalizados como `mf-a`.

<span id="descubrimiento-automático"></span>

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

## Descoberta automática

Se o arquivo estiver ausente, vários comandos inspecionam os subdiretórios imediatos e reconhecem sinais de projeto e dependências. Apenas o diretório chamado exatamente `shell` se torna o shell. Os demais candidatos são tratados como microapps.

A descoberta reconhece o adaptador importado e nomes exatos de dependências: Preact não é confundido com React e Qwik/Stencil são detectados. Ordena diretórios e atribui portas livres a partir de 5001 sem colidir com o shell; portas explícitas são respeitadas.

A detecção usa heurísticas; não reproduz toda a matriz de templates nem substitui a intenção de um manifesto explícito. Com um JSON malformado, o erro é informado e a descoberta é desativada para evitar operar sobre uma topologia acidental. Corrija o arquivo antes de continuar.

CLI `1.2.0` aceita `manifest: "define"` em cada app e `security.frameOrigins` para iframes remotos. As origens de frames entram apenas em `frame-src`; não habilitam scripts ou conexões do host. O filtro de navegação de catálogos não bloqueia leitura por fetch. Veja [apps remotas](/pt/docs/framework/remote-apps/) e [build](/pt/docs/cli/build/).

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

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

## Referência de implementação

- `wu-cli/src/config/config.zig`
- `wu-cli/src/config/discovery.zig`
- `wu-cli/src/runtime/allowed_hosts.zig`
- `wu-cli/src/runtime/dev/config_reload.zig`
- `wu-cli/src/runtime/handlers/proxy.zig`