feat(pm): implement catalog protocol for dependency resolution

Add support for the `catalog:` dependency protocol, which allows
defining shared version specs in `.utoo.toml` and referencing them
from package.json via `catalog:` or `catalog:<name>`.

Key changes:
- Parse `catalog:` as `PackageSpec::Local { protocol: Catalog }` in spec parser
- Resolve catalog specs inline in `process_dependency` (same pattern as workspace/git)
- Add `Catalogs` type and `resolve_catalog_spec` to ruborist spec module
- Normalize default catalog keys ("" / "default") at config build time
- Add catalog-aware lock freshness check in `deps_match` closure
- Add `catalogs` field to `BuildDepsConfig` and `BuildDepsOptions`
- Add e2e test fixture and test cases for catalog resolution

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: elrrrrrrr

crates/pm/src/helper/lock.rs

@@ -6,7 +6,7 @@ use serde_json::Value;
 use utoo_ruborist::lock::{LockPackage, PackageLock};
 use utoo_ruborist::manifest::{DepsView, EnginesView, PackageJson};
 use utoo_ruborist::registry::resolve_package;
-use utoo_ruborist::spec::{PackageSpec, Protocol};
+use utoo_ruborist::spec::{PackageSpec, Protocol, resolve_catalog_spec};
 use utoo_ruborist::util::PackageNameStr;
 
 use super::ruborist_context::Context;
@@ -19,7 +19,7 @@ use crate::util::git_resolver::{resolve_git_spec, resolve_github_spec};
 use crate::util::json::{load_package_json, load_package_lock_json_from_path, read_json_file};
 use crate::util::logger::{finish_progress_bar, start_progress_bar};
 use crate::util::save_type::{PackageAction, SaveType};
-use crate::util::user_config::{get_legacy_peer_deps, set_package_json};
+use crate::util::user_config::{get_catalogs, get_legacy_peer_deps, set_package_json};
 
 // Platform-specific line endings
 #[cfg(target_os = "windows")]
@@ -53,18 +53,6 @@ pub fn extract_package_name(path: &str) -> String {
     }
 }
 
-/// Compare a PackageJson dependency map with a lock file dependency map.
-/// Treats empty maps and None/empty objects as equal.
-fn deps_map_equals_lock(
-    pkg_deps: &HashMap<String, String>,
-    lock_deps: Option<&HashMap<String, String>>,
-) -> bool {
-    match lock_deps {
-        Some(ld) => *pkg_deps == *ld,
-        None => pkg_deps.is_empty(),
-    }
-}
-
 pub async fn ensure_package_lock(root_path: &Path) -> Result<PackageLock> {
     // Check package.json exists in project directory
     if fs::metadata(root_path.join("package.json")).await.is_err() {
@@ -362,6 +350,22 @@ pub async fn is_pkg_lock_outdated(root_path: &Path) -> Result<bool> {
     let pkg: DepsView = load_package_json(root_path).await?;
     let lock_file: PackageLock = read_json_file(&root_path.join("package-lock.json")).await?;
 
+    let catalogs = get_catalogs().await;
+    let deps_match = |pkg_deps: &HashMap<String, String>,
+                      lock_deps: Option<&HashMap<String, String>>|
+     -> bool {
+        match lock_deps {
+            None => pkg_deps.is_empty(),
+            Some(ld) => {
+                pkg_deps.len() == ld.len()
+                    && pkg_deps.iter().all(|(name, spec)| {
+                        let resolved = resolve_catalog_spec(name, spec, &catalogs).unwrap_or(spec);
+                        ld.get(name).is_some_and(|v| v == resolved)
+                    })
+            }
+        }
+    };
+
     let packages = &lock_file.packages;
 
     // prepare packages to check: (relative_path, deps)
@@ -394,26 +398,25 @@ pub async fn is_pkg_lock_outdated(root_path: &Path) -> Result<bool> {
         let name = if path.is_empty() { "root" } else { path };
 
         // check dependencies whether changed
-        if !deps_map_equals_lock(&pkg.dependencies, lock.dependencies.as_ref()) {
+        if !deps_match(&pkg.dependencies, lock.dependencies.as_ref()) {
             tracing::warn!("package-lock.json is outdated, {name} dependencies changed");
             return Ok(true);
         }
 
-        if !deps_map_equals_lock(
+        if !deps_match(
             &pkg.optional_dependencies,
             lock.optional_dependencies.as_ref(),
         ) {
             tracing::warn!("package-lock.json is outdated, {name} optionalDependencies changed");
             return Ok(true);
         }
 
-        if !deps_map_equals_lock(&pkg.dev_dependencies, lock.dev_dependencies.as_ref()) {
+        if !deps_match(&pkg.dev_dependencies, lock.dev_dependencies.as_ref()) {
             tracing::warn!("package-lock.json is outdated, {name} devDependencies changed");
             return Ok(true);
         }
 
-        if !legacy_peer_deps
-            && !deps_map_equals_lock(&pkg.peer_dependencies, lock.peer_dependencies.as_ref())
+        if !legacy_peer_deps && !deps_match(&pkg.peer_dependencies, lock.peer_dependencies.as_ref())
         {
             tracing::warn!("package-lock.json is outdated, {name} peerDependencies changed");
             return Ok(true);

crates/pm/src/helper/ruborist_context.rs

@@ -7,7 +7,8 @@ use crate::service::pipeline::{PipelineChannels, PipelineReceiver};
 use crate::util::cache::get_cache_dir;
 use crate::util::logger::ProgressReceiver;
 use crate::util::user_config::{
-    get_legacy_peer_deps, get_manifests_concurrency_limit, get_registry, get_supports_semver,
+    get_catalogs, get_legacy_peer_deps, get_manifests_concurrency_limit, get_registry,
+    get_supports_semver,
 };
 
 /// Tokio-based glob implementation.
@@ -40,6 +41,7 @@ impl Context {
         cwd: PathBuf,
         receiver: R,
     ) -> BuildDepsOptions<GlobImpl, R> {
+        let catalogs = get_catalogs().await;
         BuildDepsOptions {
             cwd,
             registry_url: get_registry(),
@@ -49,6 +51,7 @@ impl Context {
             glob: TokioGlob,
             receiver,
             supports_semver: get_supports_semver(),
+            catalogs,
         }
     }
 

crates/pm/src/util/config_file.rs

@@ -5,6 +5,7 @@ use std::fmt::Debug;
 use std::fs;
 use std::path::{Path, PathBuf};
 use std::sync::OnceLock;
+use utoo_ruborist::spec::Catalogs;
 
 pub type ConfigResult<T> = Result<T>;
 
@@ -84,12 +85,18 @@ impl Config {
     }
 
     /// Build a `Catalogs` map from the parsed `[catalog]` and `[catalogs.*]` sections.
-    #[allow(dead_code)] // used by catalog protocol (upcoming)
-    pub fn catalogs(&self) -> HashMap<String, HashMap<String, String>> {
+    ///
+    /// The default catalog (`[catalog]`) is stored under both `""` and `"default"`
+    /// so that `catalog:` and `catalog:default` both resolve without extra normalization.
+    pub fn catalogs(&self) -> Catalogs {
         let mut result = self.catalogs.clone();
         if !self.catalog.is_empty() {
             result.insert(String::new(), self.catalog.clone());
         }
+        // Duplicate default catalog under "default" key for direct lookup
+        if let Some(default) = result.get("").cloned() {
+            result.entry("default".to_string()).or_insert(default);
+        }
         result
     }
 

crates/pm/src/util/user_config.rs

@@ -5,6 +5,7 @@ use std::sync::{LazyLock, OnceLock};
 use anyhow::Result;
 use dashmap::DashMap;
 use utoo_ruborist::manifest::PackageJson;
+use utoo_ruborist::spec::Catalogs;
 
 use super::config_file::{Config, ConfigValue};
 use super::http::client_builder;
@@ -64,13 +65,18 @@ pub fn get_registry() -> String {
     REGISTRY.get_sync()
 }
 
-#[allow(dead_code)] // used by catalog protocol (upcoming)
-pub async fn get_catalogs()
--> std::collections::HashMap<String, std::collections::HashMap<String, String>> {
-    Config::load(false)
+static CATALOGS: tokio::sync::OnceCell<Catalogs> = tokio::sync::OnceCell::const_new();
+
+pub async fn get_catalogs() -> Catalogs {
+    CATALOGS
+        .get_or_init(|| async {
+            Config::load(false)
+                .await
+                .map(|c| c.catalogs())
+                .unwrap_or_default()
+        })
         .await
-        .map(|c| c.catalogs())
-        .unwrap_or_default()
+        .clone()
 }
 
 pub fn set_legacy_peer_deps(value: Option<bool>) {

crates/ruborist/src/lib.rs

@@ -25,6 +25,7 @@
 pub mod model;
 pub mod resolver;
 pub mod service;
+pub mod spec;
 pub mod traits;
 
 // ============================================================================
@@ -79,9 +80,9 @@ pub mod compat {
     pub use crate::model::compatibility::{is_cpu_compatible, is_os_compatible};
 }
 
-/// Package specification types.
-pub mod spec {
-    pub use crate::model::spec::{PackageSpec, Protocol, SpecStr};
+/// Node types for the dependency graph.
+pub mod node {
+    pub use crate::model::node::NodeType;
 }
 
 /// Git clone and resolution helpers.

crates/ruborist/src/model/graph.rs

@@ -306,6 +306,13 @@ impl DependencyGraph {
         }
     }
 
+    /// Update the spec on a dependency edge (e.g. after resolving `catalog:` protocol).
+    pub fn update_dependency_spec(&mut self, edge_id: EdgeIndex, spec: String) {
+        if let Some(GraphEdge::Dependency(dep)) = self.graph.edge_weight_mut(edge_id) {
+            dep.spec = spec;
+        }
+    }
+
     /// Get node by index.
     pub fn get_node(&self, index: NodeIndex) -> Option<&PackageNode> {
         self.graph.node_weight(index)

crates/ruborist/src/model/mod.rs

@@ -125,7 +125,6 @@ pub mod node;
 pub mod override_rule;
 pub mod package_json;
 pub mod package_lock;
-pub mod spec;
 pub mod tarball_info;
 pub(crate) mod util;
 

crates/ruborist/src/model/node.rs

@@ -14,7 +14,7 @@ pub enum EdgeType {
 }
 
 /// Node type representing the kind of package in the graph.
-#[derive(Debug, Clone, PartialEq, Eq)]
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum NodeType {
     /// Root project package
     Root,

crates/ruborist/src/model/package_lock.rs

@@ -293,19 +293,21 @@ fn create_root_lock_package(graph: &DependencyGraph, node_index: NodeIndex) -> L
     let node = graph.get_node(node_index).expect("Node must exist");
     let manifest = &node.manifest;
 
-    LockPackage {
+    let mut pkg = LockPackage {
         name: Some(node.name.clone()),
         version: Some(node.version.clone()),
         engines: manifest.engines().cloned(),
         workspaces: manifest
             .workspaces()
             .and_then(|v| serde_json::from_value(v).ok()),
-        dependencies: manifest.dependencies().cloned(),
-        dev_dependencies: manifest.dev_dependencies().cloned(),
-        peer_dependencies: manifest.peer_dependencies().cloned(),
-        optional_dependencies: manifest.optional_dependencies().cloned(),
         ..LockPackage::default()
-    }
+    };
+
+    // Read deps from graph edges (not manifest) so that resolved `catalog:` specs
+    // are written to the lockfile instead of the raw protocol references.
+    collect_edge_deps(graph, node_index, &mut pkg);
+
+    pkg
 }
 
 /// Create LockPackage for non-root nodes.

crates/ruborist/src/resolver/builder.rs

@@ -27,9 +27,9 @@ use crate::model::graph::{DependencyGraph, FindResult, PackageNode};
 use crate::model::manifest::NodeManifest;
 use crate::model::node::EdgeType;
 use crate::model::package_json::PackageJson;
-use crate::model::spec::{PackageSpec, Protocol};
 use crate::resolver::preload::{PreloadConfig, preload_manifests};
 use crate::resolver::registry::{ResolveError, resolve_registry_dep};
+use crate::spec::{Catalogs, PackageSpec, Protocol, resolve_catalog_spec};
 use crate::traits::progress::{BuildEvent, EventReceiver, NoopReceiver};
 use crate::traits::registry::{RegistryClient, ResolvedPackage};
 
@@ -83,6 +83,9 @@ pub struct BuildDepsConfig {
     pub cache_dir: Option<PathBuf>,
     /// Shared dedup cache for concurrent git clone operations
     pub git_clone_cache: Arc<GitCloneCache>,
+    /// Catalog definitions for the `catalog:` dependency protocol.
+    /// Key `""` = default catalog, other keys = named catalogs.
+    pub catalogs: Catalogs,
 }
 
 impl Default for BuildDepsConfig {
@@ -93,6 +96,7 @@ impl Default for BuildDepsConfig {
             skip_preload: false,
             cache_dir: dirs::home_dir().map(|d| d.join(".cache/nm")),
             git_clone_cache: Arc::new(tokio::sync::Mutex::new(HashMap::new())),
+            catalogs: HashMap::new(),
         }
     }
 }
@@ -121,6 +125,12 @@ impl BuildDepsConfig {
         self.cache_dir = Some(cache_dir);
         self
     }
+
+    /// Set catalog definitions for `catalog:` protocol resolution.
+    pub fn with_catalogs(mut self, catalogs: Catalogs) -> Self {
+        self.catalogs = catalogs;
+        self
+    }
 }
 
 /// Snapshot of node dependency flags to avoid borrowing conflicts.
@@ -135,7 +145,7 @@ struct NodeFlags {
 
 /// Gather all unresolved deps from root and workspace nodes for preloading.
 fn gather_preload_deps(graph: &DependencyGraph, legacy_peer_deps: bool) -> Vec<(String, String)> {
-    use crate::model::spec::SpecStr;
+    use crate::spec::SpecStr;
     use std::collections::HashSet;
 
     let mut deps = HashSet::new();
@@ -412,6 +422,38 @@ pub async fn process_dependency<R: RegistryClient>(
                     );
                     return Ok(ProcessResult::Skipped);
                 }
+                PackageSpec::Local {
+                    protocol: Protocol::Catalog,
+                    ..
+                } => {
+                    let resolved_spec =
+                        resolve_catalog_spec(&edge_info.name, &edge_info.spec, &config.catalogs)
+                            .ok_or_else(|| ResolveError::Unsupported {
+                                spec: edge_info.spec.clone(),
+                                reason: "catalog entry not found",
+                            })?;
+                    // Update the edge spec so the lockfile writes the resolved
+                    // version range instead of the raw `catalog:` reference.
+                    graph.update_dependency_spec(edge_info.edge_id, resolved_spec.to_string());
+                    match resolve_registry_dep(
+                        registry,
+                        &edge_info.name,
+                        resolved_spec,
+                        &edge_info.edge_type,
+                    )
+                    .await?
+                    {
+                        Some(resolved) => resolved,
+                        None => {
+                            tracing::debug!(
+                                "Skipped optional catalog dependency {}@{}",
+                                edge_info.name,
+                                edge_info.spec
+                            );
+                            return Ok(ProcessResult::Skipped);
+                        }
+                    }
+                }
                 PackageSpec::Local { .. } => {
                     return Err(ResolveError::Unsupported {
                         spec: edge_info.spec.clone(),