# WU Framework 4.0 and CLI 1.2: upgrade and migrate

Features, breaking changes, validation and support for upgrading to Framework 4.0.0 and CLI 1.2.0.

This guide covers WU Framework **4.0.0** and WU CLI **1.2.0**. Framework 4 is a major release because it now rejects operations that earlier versions accepted. Updating the CLI does not automatically migrate your application code.

<span id="qué-cambia"></span>

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

## What changes

- **Framework:** hooks with app identity and permissions, SSR with private per-request data, cancellation and concurrency limits; nested-path synchronization; supervision and cooperative replay. See [runtime reliability](/docs/framework/runtime-reliability/) and [adapters](/docs/framework/api-adapters/).

- **Security:** explicit remote origin, mutual MCP relay authentication, contract ownership, `.wuapp` validation, AI workflow permissions and per-response CSP nonces. See [security](/docs/framework/security/).

- **CLI:** dependencies and catalogs, per-app resolution, parallel compilation and configuration-aware cache invalidation; development server restricted to authorized hosts; builds with content hashes and consistent asset deployment. See [dependencies](/docs/cli/dependencies/), [development](/docs/cli/development/) and [build](/docs/cli/build/).

CLI 1.2 aligns `WU_D003` with the catalogue’s Framework version. The diagnostic distinguishes incompatible dependencies from a valid Framework 4 project. It also fixes build command execution with quoted paths on Windows.

<span id="1-preparar-una-actualización-reversible"></span>

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

## 1. Prepare a reversible upgrade

Commit your code, manifests and lockfiles and retain the previous production artifact. Upgrade in a branch and test environment first. Install exact versions and verify which executable you are using.

```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
```

In an existing workspace, inspect `wu upgrade --help`, run `wu upgrade` and review the diff. The tool updates dependencies and integration files; it does not rewrite your grants, hooks or business contracts. Then run `wu install`. In projects without the CLI, update `wu-framework` to `4.0.0` in packages that declare it and use their package manager.

<span id="2-corregir-los-cambios-incompatibles"></span>

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

## 2. Address breaking changes

**Hooks and store.** Hooks inside a microapp no longer inherit host authority. Request permissions in `manifest.wu.permissions` and grant them in the shell’s `grants`. Only their intersection is effective. A denied emit returns `false`; subscriptions or store access may throw `WU_EVENT_SUBSCRIBE_DENIED` or `WU_CAPABILITY_DENIED`. Grant the channels and paths the app actually uses.

```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,
});
```

**Remote apps.** `connect` and `waitForPort` require `hostOrigin`. Use the shell’s exact origin; `"*"` deliberately accepts any origin. The entry must match the registered URL’s origin (`WU_REMOTE_ORIGIN_MISMATCH`). Same-origin remote apps require `iframe.allowSameOrigin: true`; `wu.detach()` rejects remote apps with `WU_WINDOW_REMOTE_UNSUPPORTED`. See [remote apps](/docs/framework/remote-apps/).

**MCP and CSP.** Upgrade the relay with the runtime: the 4.0 bridge uses mutual HMAC v2 authentication and requires a token. Plain `ws://` is refused outside loopback. Insecure mode is explicit and local only. In SSR middleware replace a fixed nonce with `nonce: () => createNonce()` to create one per response. See [MCP](/docs/framework/api-mcp/) and [streaming and security](/docs/framework/streaming-security/).

**Contracts and packages.** Do not overwrite another provider’s capability (`WU_CAPABILITY_OWNED`); revoke it or unmount its provider before handing over. Installing a `.wuapp` over a host-registered app requires `{ replace: true }`. `restore()` validates stored entries. Handle errors by `error.code`, not message text. Wait for asynchronous lifecycles with `await`.

**CLI and deployment.** Add tunnel hosts to `dev.allowedHosts`; only `VITE_*` and `WU_*` keys from `.env` are exposed to clients. These prefixes are unsuitable for secrets. Review `shared` when apps need a single instance. Deploy the complete `dist/`; retain previous hashed assets while old pages remain open and revalidate HTML/manifests. See [configuration](/docs/cli/configuration/) and [deployment](/docs/cli/serve/).

<span id="3-validar-y-volver-atrás-si-es-necesario"></span>

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

## 3. Validate and roll back when necessary

```sh
wu doctor --json
wu contracts check
wu test
wu build
wu serve 4100 --mode static
```

Check mount, update and unmount, denied permissions, direct reloads, SSR/hydration, CSP, RPC and remote reconnection for the features you use. Test `wu build --native` separately if applicable. Also check a tab opened before deployment. If something fails, restore the previous commit, lockfile and artifact together; do not mix a new runtime with an incompatible relay or assets.

<span id="se-rompió-algo-te-ayudamos"></span>

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

## Something broke? We can help

The WU team provides help diagnosing upgrade problems. [Ask for migration support](/support/#migration-help) or open an issue in the product repository. Include old and new versions, `wu --version`, `npm ls wu-framework`, OS/browser, error code and a minimal reproduction without secrets. Explain what worked before and what you expected. Community support does not imply a guaranteed response time.