utoo

The @utoo/web package provides a high-performance bundling environment directly in the browser using WebAssembly and Turbopack. Key capabilities include:

• Real File System: Utilizes Origin Private File System (OPFS) to simulate a Node.js-like file system.
• Browser Dependency Resolution: Resolves dependencies from package.json without requiring a lock file. Supports npm, npmmirror, and private registries.
• Browser-based Bundling: Executes the Utoo bundler within the browser environment.
• Project Lifecycle Management: Provides a dispose() method to cancel active installs or builds and safely switch projects.
• Hot Module Replacement (HMR): Supports full HMR via MessagePort communication with preview iframes.
• Webpack Compatibility: Supports a subset of Webpack configurations and standard loaders like css-loader and style-loader.
• CSS Processing: Built-in support for PostCSS and Tailwind CSS.

The Arborist E2E suite tracks features that the utoo Package Manager (PM) does not yet fully support. If you are debugging or extending the PM, be aware of these current limitations:

• file: protocol dependencies: Some complex scenarios like dependency cycles (link-dep-cycle), lifecycle scripts in file dependencies (link-dep-lifecycle-scripts), and self-referencing dependencies (external-link-dep) are currently skipped.
• file: resolver semantics: utoo cannot currently recover origin directories for transitive file: dependencies inside registry-published packages, and certain spec-parser behaviors (like GitHub shorthand parsing) are limited.
• Optional dependency failure tolerance: Unlike standard behavior where missing transitive optional dependencies are silently skipped, utoo currently hard-fails the entire installation if an optional dependency's transitive dependency is unreachable.
• Peer dependency validation: utoo does not currently validate if peer-dependency constraints are mutually satisfiable or emit ERESOLVE errors for conflicts.
• Platform mismatch rejection: utoo does not check os, cpu, or libc fields against the current platform for non-optional dependencies.
• Workspace validation: utoo does not detect duplicate workspace names (which should trigger EDUPLICATEWORKSPACE).
• Dependency cycles: Deep recursive cycles (e.g., A→B→A→B) can cause a recursive fetch loop leading to OOM/SIGTERM.
• Mock-registry-only packages: Packages that exist only in npm's mock registry (and not the real npm registry) are not supported.

This package models a specific dependency resolution scenario where a dependency must have its own sub-dependencies duplicated to satisfy a peer dependency requirement from another of its own dependencies. This behavior mimics gatsby@2.24.53.

The Conflict Scenario

1. Initially, a package like @pmmmwh/react-refresh-webpack-plugin@0.4.1 is installed alongside gatsby and react-refresh@0.7.2 at the root.
2. A peer dependency requirement (e.g., @pmmmwh/react-refresh-webpack-plugin@0.4.1 requiring react-refresh@0.7.2) is evaluated.
3. If the required version cannot be placed at the root without colliding with an existing version, the package manager may attempt to move the existing version under the parent (e.g., under gatsby) or duplicate it.

Resolution with --force

When a collision occurs (e.g., override -> (a@2, v@1) where v@1 requires a@1), the installation will fail by default. Using the --force flag allows the package manager to override the peer dependency with the direct root dependency, resulting in a structure where the root maintains its version while the sub-dependency uses its own.

The override package is a test case designed to model specific dependency resolution behaviors, such as those seen in gatsby@2.24.53. It simulates a scenario where a dependency must have its own version of a package dupe to accommodate a peer dependency requirement from another of its own dependencies.

The Conflict Model

In the override model:

• override depends on a@2 and v@1.
• v@1 has a peer dependency on a@1.

Initially, this fails to install by default because the a dependency collides (the root wants a@2 but the peer requirement wants a@1).

Resolution via --force

Using the --force flag allows the installer to override the peer dependency with the direct root dependency. This results in a structure where the root maintains its version, even if it is invalid for the peer-dependent module:

override
+-- v@1
+-- a@2 (valid for root, invalid for v)
+-- b@2, c@2, ...

Compliant Resolution

When override is installed as a dependency of another package (e.g., push-dep), a compliant resolution is achieved where every module receives the specific version of the dependency it declares:

push-dep
+-- v@1
+-- a@1
+-- b@1, c@1, ...
+-- override
    +-- a@2
    +-- b@2, c@2, ...