Dependências e versões por app

Instalar a partir das declarações de cada parte

wu install

wu i é um alias. O comando agrega as declarações do shell e das apps, edita o manifesto raiz e chama npm. Adiciona wu-framework e esbuild do catálogo se ninguém os declarar. wu add e o assistente de wu create usam o mesmo instalador.

Adicione dependências à microapp que precisa delas ou ao shell que as consome e execute wu install novamente. Executar apenas npm install na raiz não recalcula o agregado nem .wu-deps.json.

Resolução de bibliotecas

Intervalos compatíveis são intersectados: ^19.0.0 e ^19.3.0 produzem ^19.3.0. Grupos incompatíveis usam aliases; o grupo mais novo mantém o nome principal. O resolvedor distingue linhas 0.x (zone.js--0.15) e versões fixas incompatíveis no mesmo major (lodash--4.17.20). Cada pacote aparece em uma única seção raiz; dependencies prevalece se alguma app o declarar ali.

{
  "dependencies": {
    "react": "^19.0.0",
    "react--17": "npm:react@^17.0.0"
  }
}

O mapa de overrides vincula cada import original ao alias correto:

{
  "mf-legacy": {
    "react": "react--17"
  }
}

As chaves são diretórios, como mf-legacy, e não nomes de catálogo, como legacy. O desenvolvimento e o build carregam esse mapa. Isso não significa que todos os consumidores de React compartilhem uma única instância: cada conjunto compatível deve resolver a identidade correta.

A resolução aceita ^, ~, comparadores, versões exatas, curingas, versões parciais, intervalos com hífen e até 32 alternativas ||. Não aplica a regra adicional do npm que limita pré-lançamentos à mesma tripla do comparador: confira a versão instalada ao usar pré-lançamentos. Valores não SemVer, como dist-tags ou URLs Git, são mantidos como pins explícitos e declarações diferentes geram um aviso.

Identidade dos módulos em desenvolvimento

Cada import é resolvido a partir do arquivo que o declara, respeitando node_modules locais e aninhados, pnpm, links e .wu-deps.json. As URLs identificam versão e localização. Pacotes em shared, e sempre wu-framework, são resolvidos na raiz como uma só instância; uma cópia local incompatível gera um aviso. Não coloque em shared uma biblioteca que precise coexistir em versões diferentes.

Toolchains diferentes

Vite, plugins e outras ferramentas de compilação precisam de uma estratégia diferente. O algoritmo escolhe a versão major com mais declarações entre as apps que ainda compartilham a raiz; os empates favorecem a maior. As aplicações incompatíveis passam para a instalação local. A decisão se repete porque remover os votos de uma app pode mudar outra maioria.

{
  "mf-vite-antiguo": {
    "_toolchain": "local"
  }
}

A CLI instala dentro dessa app, e o build usa seu node_modules/vite. O mapa é regravado a cada instalação ou excluído se não restarem overrides. As árvores locais gerenciadas pelo WU carregam informações de procedência para que possam ser removidas quando deixarem de ser necessárias.

Dependências locais

Uma declaração file: é preservada e reexpressa a partir da raiz. Por exemplo, file:../ui dentro de mf-panel/package.json se torna um caminho para ui/ a partir do manifesto agregado. As declarações link: e workspace: são omitidas pelo coletor atual; esse mecanismo não implementa um gerenciador completo de workspaces npm.

Regravação do manifesto da raiz

Um manifesto raiz sem _wu é rejeitado com saída 1. --force autoriza seu gerenciamento preservando campos e dependências; se o JSON estiver inválido, substitui o arquivo e mantém o original em package.json.bak.

wu install --force

--force ou -f pertencem ao WU: habilitam a regravação, não são um repasse geral de opções do npm. Não há opções públicas --frozen-lockfile, --offline, --no-install nem seletor de gerenciador de pacotes.

_wu.managed registra dependências escritas pelo WU para remover apenas as que nenhuma app declara mais. Scripts próprios, workspaces, overrides, engines e dependências adicionadas manualmente são preservados. dev e build só são criados quando ausentes. A escrita JSON é atômica com cópia .bak; uma marca _wu antiga é migrada na primeira instalação.

Migrar um projeto para CLI 1.2

wu update atualiza a ferramenta global. wu upgrade compara o shell e as apps com o catálogo da CLI instalada, que na 1.2.0 propõe WU Framework ^4.0.0. Revise primeiro a migração do framework: atualizar intervalos não migra automaticamente todas as APIs.

wu upgrade --dry-run
wu upgrade --json
wu upgrade --yes
wu install
wu doctor --json
wu build

Sem flags, upgrade mostra o plano e pede confirmação. --dry-run não escreve; --json só aplica com --yes; --check retorna 2 quando há mudanças pendentes. Nunca reduz versões: preserva intervalos mais novos ou abertos e protocolos não SemVer. Versões exatas exigem --force, que também não permite reduzi-las. Dependências ausentes são informadas sem serem adicionadas. Um erro ou confirmação sem terminal retorna 1.

As migrações reconhecem templates antigos e salvam <file>.bak: tags Stencil únicas, remoção de @stencil/core sem uso, shell Astro com APIs DOM, seletores com CSS.escape, regras ausentes de .gitignore e runtimes Qwik/Svelte em shared. As mudanças são idempotentes; fontes personalizadas que não correspondem são mantidas com um aviso. O comando não instala dependências: finalize com wu install.

Exemplo de intervalos: wu-framework: ^3.2.1 declarado passa a ^4.0.0; react: ^19.4.0 é preservado porque supera o ^19.3.0 do catálogo; react: 19.2.0 mantém seu pin salvo com --force. Não adicione _wu.managed manualmente: wu install o mantém.

Saídas e erros

JSON inválido na configuração ou no manifesto de uma app interrompe a instalação antes da escrita, com linha, coluna e saída 1. Falhas de escrita, manifesto raiz externo sem --force e falhas do npm na raiz ou em toolchains locais também retornam 1. Com conflitos de bibliotecas, a chamada raiz inclui --legacy-peer-deps.

Referência de implementação

• wu-cli/src/commands/install.zig
• wu-cli/src/commands/upgrade.zig
• wu-cli/src/commands/codemods.zig
• wu-cli/src/config/semver.zig
• wu-cli/src/config/json_doc.zig
• wu-cli/src/runtime/module_graph.zig
• wu-cli/tests/install-preserva.test.cjs
• wu-cli/tests/upgrade.test.cjs
• wu-cli/tests/dev-module-resolution.test.cjs