Implements support for a Node.js integration (#158)

* Implements support for a Node.js integration

* Yields an error when no variants match

* Style

* Adds tests

Author: arcanis

Cargo.lock

@@ -0,0 +1,87 @@
+---
+category: concepts
+slug: concepts/nvm
+title: Node.js versioning
+description: Pin the version of Node.js used in your application
+sidebar:
+  order: 3
+---
+
+One of the subtle causes of "works on my machine" bugs comes from differences in Node.js versions between developers. While tools like nvm, fnm, or Volta help manage local Node.js installations, they require each team member to manually configure their environment. Yarn takes a different approach by letting you declare Node.js as a project dependency, ensuring everyone uses exactly the same version without any extra setup.
+
+## The `@builtin/node` dependency
+
+Yarn provides a special `@builtin/node` package that you can add to your dependencies just like any other package. When installed, Yarn will download the appropriate Node.js binary for your platform directly from [nodejs.org](https://nodejs.org/) and make it available to your project.
+
+```json
+{
+  "name": "my-app",
+  "dependencies": {
+    "@builtin/node": "^22.0.0"
+  }
+}
+```
+
+The range here works similarly to semver ranges - Yarn will resolve it to the highest available Node.js version that satisfies your constraint. Once resolved, this version gets locked in your `yarn.lock` file, guaranteeing that every developer and CI environment uses the exact same Node.js release.
+
+## Why manage Node.js through Yarn?
+
+There are several advantages to managing Node.js as a dependency:
+
+- **Zero configuration** - CI and team members don't need to install nvm or any other version manager. Just `yarn install` and they're ready to go.
+
+- **Version locking** - The exact Node.js version is recorded and cached along with all other dependencies in your project.
+
+- **Per-project versions** - Different projects can use different Node.js versions without any manual switching. Yarn handles it automatically.
+
+- **Per-workspace versions** - You can easily override the Node.js version to use for a single workspace or a set of workspaces through [profiles](/concepts/profiles).
+
+## Using the managed Node.js
+
+Once installed, the managed Node.js binary is available through the `node` binary that Yarn injects into your environment. You can use it in several ways:
+
+### Through Yarn scripts
+
+Package scripts automatically use the project's Node.js version:
+
+```json
+{
+  "scripts": {
+    "start": "node server.js"
+  }
+}
+```
+
+### Through `yarn node` / `yarn exec`
+
+Both commands will run Node.js with the correct environment setup:
+
+```bash
+yarn node --version
+yarn node script.js
+yarn exec node --version
+```
+
+## Monorepo support
+
+In a monorepo, you typically want all workspaces to use the same Node.js version. Rather than adding `@builtin/node` to each workspace's `package.json`, you can use [workspace profiles](/concepts/profiles) to declare it once:
+
+```yaml
+workspaceProfiles:
+  default:
+    devDependencies:
+      "@builtin/node": "builtin:^22.0.0"
+```
+
+Since the `default` profile is automatically applied to all workspaces, every package in your monorepo will use the same Node.js version without any additional configuration. This keeps your Node.js version centralized and easy to update.
+
+## Platform support
+
+The `@builtin/node` package automatically downloads the correct binary for your operating system and architecture. Currently supported platforms include:
+
+- Linux (x64, arm64)
+- macOS (x64, arm64)
+
+When working in a team with mixed platforms, Yarn will store metadata about all required platform variants in the lockfile, but each developer will only downloads the binary they need for their platform (configurable through `supportedArchitectures`).
+
+This ensures the lockfile remains consistent across the entire team while keeping installs as lightweight as possible.

documentation/src/content/docs/concepts/intermediary/nodejs-management.md

@@ -11,16 +11,20 @@ description: A detailed explanation of the breaking changes between two versions
 This document lists the **intended breaking changes**. Yarn 6 being still in development, some features are still missing and will be implemented before we publish the first stable release.
 :::
 
-### Plugins
+### Not implemented
 
-A special note for plugins, which aren't implemented **yet**.
+Reimplementing a codebase comes with challenges, and the two following features haven't been implemented **yet**. We plan to address them before the first stable release:
 
-Various other projects (Biome, Oxc, etc) are experimenting on that topic, and we prefer to wait before focusing on that so we can leverage their researches before building our own solutions.
+- Plugins; various other projects (Biome, Oxc, etc) are experimenting on that topic, and we prefer to let them clear the way before building our own solutions.
+
+- Windows support; we already have a path abstraction to prepare for this task, but no tests haven't been run on Windows yet and various things are likely broken. We recommend WSL as a workaround.
 
 ### Important features
 
 Some new features have been implemented. They are not "breaking changes" per se, but may make some of your existing tooling obsolete, so be sure to take a look at them:
 
+- [Native Node.js version management](/concepts/nvm), which allows Yarn to treat Node.js as any other dependency, removing the need for third-party tools like nvm / fnm / volta / ...
+
 - [Workspace profiles](/concepts/profiles), which let you definite set of dependencies to reuse in your workspaces
 
 ### Lockfile
@@ -56,3 +60,9 @@ Some new features have been implemented. They are not "breaking changes" per se,
 ### Deprecations
 
 - The `.pnp.cjs` file isn't generated with the `+x` flag anymore.
+
+- Behavior inherited from npm, packages are currently allowed to omit listing dependencies on `node-gyp` if the package happens to contain a `binding.gyp` file.
+
+  This behavior is unsafe as the only reasonable thing the package manager can do is to imply a dependency on `*`, meaning there are no guarantees as to the version of `node-gyp` projects would end up using.
+
+  This undocumented behavior is now **deprecated** and will be removed in a future release. Popular packages that already rely on it will get an hardcoded package extension so they keep working, but the implicit `node-gyp` dependency won't be applied to any other package going forward.

documentation/src/content/docs/getting-started/migrating/breaking-changes.md

@@ -125,6 +125,11 @@
         }
       }
     },
+    "nodeDistUrl": {
+      "type": "string",
+      "description": "The URL to use for downloading Node.js distributions",
+      "default": "https://nodejs.org/dist"
+    },
     "nodeLinker": {
       "type": "crate::NodeLinker",
       "description": "The linker to use for node_modules",
@@ -299,21 +304,21 @@
           "type": "array",
           "description": "List of CPU architectures to cover.",
           "items": {
-            "type": "crate::Cpu"
+            "type": "zpm_utils::Cpu"
           }
         },
         "libc": {
           "type": "array",
           "description": "The list of standard C libraries to cover.",
           "items": {
-            "type": "crate::Libc"
+            "type": "zpm_utils::Libc"
           }
         },
         "os": {
           "type": "array",
           "description": "The list of operating systems to cover.",
           "items": {
-            "type": "crate::Os"
+            "type": "zpm_utils::Os"
           }
         }
       }

packages/zpm-config/schema.json

@@ -1,7 +1,7 @@
 use std::{collections::BTreeMap, fmt::Display, ops::Deref, sync::Arc};
 
 use serde::{Deserialize, Deserializer, Serialize, Serializer, de};
-use zpm_utils::{AbstractValue, Container, DataType, FromFileString, IoResultExt, Path, RawString, Serialized, ToFileString, ToHumanString, tree};
+use zpm_utils::{AbstractValue, Container, Cpu, DataType, FromFileString, IoResultExt, Libc, Os, Path, RawString, Serialized, System, ToFileString, ToHumanString, tree};
 
 #[derive(Debug, Clone)]
 pub struct ConfigurationContext {
@@ -698,6 +698,66 @@ macro_rules! merge_settings {
 
 include!(concat!(env!("OUT_DIR"), "/schema.rs"));
 
+impl SupportedArchitectures {
+    pub fn to_systems(&self) -> Vec<System> {
+        let mut systems
+            = Vec::new();
+
+        let current
+            = System::from_current();
+
+        let cpus = if self.cpu.is_empty() {
+            vec![&Cpu::Current]
+        } else {
+            self.cpu.iter().map(|c| &c.value).collect()
+        };
+
+        let os = if self.os.is_empty() {
+            vec![&Os::Current]
+        } else {
+            self.os.iter().map(|o| &o.value).collect()
+        };
+
+        let libc = if self.libc.is_empty() {
+            vec![&Libc::Current]
+        } else {
+            self.libc.iter().map(|l| &l.value).collect()
+        };
+
+        for &cpu in &cpus {
+            for &os in &os {
+                for &libc in &libc {
+                    let arch = if cpu == &Cpu::Current {
+                        current.arch.clone()
+                    } else {
+                        Some(cpu.clone())
+                    };
+
+                    let os = if os == &Os::Current {
+                        current.os.clone()
+                    } else {
+                        Some(os.clone())
+                    };
+
+                    let libc = if libc == &Libc::Current {
+                        current.libc.clone()
+                    } else {
+                        Some(libc.clone())
+                    };
+
+                    systems.push(System {
+                        arch,
+                        os,
+                        libc,
+                    });
+                }
+            }
+        }
+
+        systems
+    }
+}
+
 pub struct Configuration {
     pub settings: Settings,
     pub user_config_path: Option<Path>,
@@ -846,11 +906,11 @@ merge_settings!(zpm_primitives::Reference, |s: &str| FromFileString::from_file_s
 
 merge_settings!(zpm_semver::RangeKind, |s: &str| FromFileString::from_file_string(s).unwrap());
 
-merge_settings!(zpm_utils::Secret<String>, |s: &str| FromFileString::from_file_string(s).unwrap());
+merge_settings!(zpm_utils::Cpu, |s: &str| FromFileString::from_file_string(s).unwrap());
 merge_settings!(zpm_utils::Glob, |s: &str| FromFileString::from_file_string(s).unwrap());
+merge_settings!(zpm_utils::Libc, |s: &str| FromFileString::from_file_string(s).unwrap());
+merge_settings!(zpm_utils::Os, |s: &str| FromFileString::from_file_string(s).unwrap());
+merge_settings!(zpm_utils::Secret<String>, |s: &str| FromFileString::from_file_string(s).unwrap());
 
 merge_settings!(crate::types::NodeLinker, |s: &str| FromFileString::from_file_string(s).unwrap());
 merge_settings!(crate::types::PnpFallbackMode, |s: &str| FromFileString::from_file_string(s).unwrap());
-merge_settings!(crate::types::Cpu, |s: &str| FromFileString::from_file_string(s).unwrap());
-merge_settings!(crate::types::Libc, |s: &str| FromFileString::from_file_string(s).unwrap());
-merge_settings!(crate::types::Os, |s: &str| FromFileString::from_file_string(s).unwrap());

packages/zpm-config/src/lib.rs

@@ -28,57 +28,3 @@ pub enum PnpFallbackMode {
     #[literal("all")]
     All,
 }
-
-#[zpm_enum(error = ConfigurationError, or_else = |s| Err(ConfigurationError::EnumError(s.to_string())))]
-#[derive(Debug, Clone, Encode, Decode, PartialEq, Eq)]
-pub enum Cpu {
-    #[literal("current")]
-    Current,
-
-    #[literal("ia32")]
-    I386,
-
-    #[literal("x64")]
-    X86_64,
-
-    #[literal("arm64")]
-    Aarch64,
-
-    #[fallback]
-    Other(String),
-}
-
-#[zpm_enum(error = ConfigurationError, or_else = |s| Err(ConfigurationError::EnumError(s.to_string())))]
-#[derive(Debug, Clone, Encode, Decode, PartialEq, Eq)]
-pub enum Libc {
-    #[literal("current")]
-    Current,
-
-    #[literal("glibc")]
-    Glibc,
-
-    #[literal("musl")]
-    Musl,
-
-    #[fallback]
-    Other(String),
-}
-
-#[zpm_enum(error = ConfigurationError, or_else = |s| Err(ConfigurationError::EnumError(s.to_string())))]
-#[derive(Debug, Clone, Encode, Decode, PartialEq, Eq)]
-pub enum Os {
-    #[literal("current")]
-    Current,
-
-    #[literal("darwin")]
-    MacOS,
-
-    #[literal("linux")]
-    Linux,
-
-    #[literal("win32")]
-    Windows,
-
-    #[fallback]
-    Other(String),
-}

packages/zpm-config/src/types.rs

@@ -87,6 +87,16 @@ impl<'a> Entry<'a> {
             compression: None,
         }
     }
+
+    pub fn new_file(name: Path, data: Cow<'a, [u8]>) -> Self {
+        Entry {
+            name,
+            mode: 0o644,
+            crc: 0,
+            data,
+            compression: None,
+        }
+    }
 }
 
 pub fn entries_to_disk<'a>(entries: &[Entry<'a>], base: &Path) -> Result<(), Error> {

packages/zpm-formats/src/lib.rs

@@ -1,4 +1,4 @@
-use std::{collections::BTreeMap, ops::Range};
+use std::{collections::BTreeMap, ops::Range, str::FromStr};
 
 use itertools::Itertools;
 use serde::{Deserialize, Serialize, de::DeserializeOwned};
@@ -14,6 +14,19 @@ pub use sonic_rs as json_provider;
 pub type RawJsonDeserializer<R> = json_provider::Deserializer<R>;
 pub type RawJsonValue = json_provider::Value;
 
+#[derive(Debug)]
+pub struct JsonSource<T> {
+    pub value: T,
+}
+
+impl<T: DeserializeOwned> FromStr for JsonSource<T> {
+    type Err = Error;
+
+    fn from_str(s: &str) -> Result<Self, Self::Err> {
+        Ok(Self { value: JsonDocument::hydrate_from_str(s)? })
+    }
+}
+
 pub struct JsonDocument {
     pub input: Vec<u8>,
     pub paths: BTreeMap<Path, usize>,