USAR A CLI5 MIN DE LEITURA · MARKDOWN ↗

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.

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.

{
  "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.

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.

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.

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.

Novas opções de desenvolvimento e build

{
  "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.

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 e build.

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