WU Framework 4.0 and CLI 1.2: upgrade and migrate

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.

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 and adapters.

• Security: explicit remote origin, mutual MCP relay authentication, contract ownership, .wuapp validation, AI workflow permissions and per-response CSP nonces. See 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, development and 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.

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.

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.

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.

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.

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 and streaming and 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 and deployment.

3. Validate and roll back when necessary

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.

Something broke? We can help

The WU team provides help diagnosing upgrade problems. Ask for migration support 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.