feat(pm): internalize git dependency resolution into ruborist

Move git clone & resolution logic into `utoo-ruborist` behind a `git`
Cargo feature flag. Git specs (git+https://, github:, etc.) are now
resolved on-the-fly during BFS traversal via `resolve_non_registry_dep`,
so transitive git dependencies work correctly.

- Add `gix`/`tempfile` as optional deps in ruborist under `git` feature
- Add `resolve_non_registry_dep` with dual cfg (git-enabled / no-op)
- Route `is_non_registry_spec` edges through git resolver in BFS
- Add `PackageSpec` enum and `parse_cli_spec` for typed spec parsing
- Add shared `git_cache_path` helper to deduplicate SHA-prefix cache logic
- Extract `format_save_spec` for clean version-to-write logic in lock.rs
- PM enables `utoo-ruborist/git` instead of depending on `gix` directly
- `BuildDepsOptions<G, R>` stays at 2 generics; no git types leak to PM

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

Author: killagu-claw

Cargo.lock

@@ -52,7 +52,7 @@ toml = { workspace = true }
 tracing = { workspace = true }
 tracing-appender = "0.2"
 tracing-subscriber = { workspace = true }
-utoo-ruborist = { path = "../ruborist" }
+utoo-ruborist = { path = "../ruborist", features = ["git"] }
 
 [target.'cfg(not(target_arch = "wasm32"))'.dependencies]
 tokio = { workspace = true, features = ["full"] }

crates/pm/Cargo.toml

@@ -5,6 +5,7 @@ use std::path::{Path, PathBuf};
 
 use super::ruborist_context::Context;
 use crate::helper::workspace::find_workspaces;
+use crate::util::git_resolver::{resolve_git_spec, resolve_github_spec};
 use crate::util::json::{load_package_json_from_path, load_package_lock_json_from_path};
 use crate::util::logger::{finish_progress_bar, start_progress_bar};
 use crate::util::save_type::{PackageAction, SaveType};
@@ -13,7 +14,7 @@ use crate::util::{cloner::clone_package, downloader::download_to_cache};
 use utoo_ruborist::lock::{LockPackage, PackageLock};
 use utoo_ruborist::manifest::PackageJson;
 use utoo_ruborist::registry::resolve_package;
-use utoo_ruborist::util::parse_package_spec;
+use utoo_ruborist::spec::{PackageSpec, parse_cli_spec};
 
 use super::workspace::find_workspace_path;
 
@@ -168,13 +169,10 @@ pub async fn update_package_json(
         for (name, version, version_spec) in package_specs {
             match action {
                 PackageAction::Add => {
-                    let version_to_write = match version_spec {
-                        spec if spec.is_empty() || spec == "*" || spec == "latest" => {
-                            format!("^{version}")
-                        }
-                        spec => spec.to_string(),
-                    };
-                    deps_obj.insert(name, Value::String(version_to_write));
+                    deps_obj.insert(
+                        name,
+                        Value::String(format_save_spec(&version_spec, &version)),
+                    );
                 }
                 PackageAction::Remove => {
                     deps_obj.remove(&name);
@@ -193,12 +191,44 @@ pub async fn update_package_json(
     Ok(())
 }
 
+/// Format a version spec for writing into package.json.
+///
+/// Git/non-registry specs are written as-is (e.g. the resolved URL with pinned commit).
+/// Wildcard specs (`*`, `latest`, empty) are pinned to `^<resolved_version>`.
+/// Everything else (semver ranges, exact versions) passes through unchanged.
+fn format_save_spec(version_spec: &str, resolved_version: &str) -> String {
+    if version_spec.starts_with("git+") || version_spec.starts_with("git://") {
+        return version_spec.to_string();
+    }
+    match version_spec {
+        "" | "*" | "latest" => format!("^{resolved_version}"),
+        _ => version_spec.to_string(),
+    }
+}
+
 pub async fn resolve_package_spec(spec: &str) -> Result<(String, String, String)> {
-    let (name, version_spec) = parse_package_spec(spec);
-    let resolved = resolve_package(&Context::registry(), name, version_spec)
-        .await
-        .map_err(|e| anyhow!("{}", e))?;
-    Ok((name.to_string(), resolved.version, version_spec.to_string()))
+    let parsed = parse_cli_spec(spec);
+    match parsed {
+        PackageSpec::Registry { name, version_spec } => {
+            let resolved = resolve_package(&Context::registry(), &name, &version_spec)
+                .await
+                .map_err(|e| anyhow!("{}", e))?;
+            Ok((name, resolved.version, version_spec))
+        }
+        PackageSpec::Git { url, commit_ish } => {
+            let resolved = resolve_git_spec(&url, commit_ish.as_deref()).await?;
+            Ok((resolved.name, resolved.version, resolved.resolved_url))
+        }
+        PackageSpec::GitHub {
+            owner,
+            repo,
+            commit_ish,
+        } => {
+            let resolved = resolve_github_spec(&owner, &repo, commit_ish.as_deref()).await?;
+            Ok((resolved.name, resolved.version, resolved.resolved_url))
+        }
+        _ => Err(anyhow!("Unsupported package spec type: {}", spec)),
+    }
 }
 
 pub async fn prepare_global_package_json(npm_spec: &str, prefix: Option<&str>) -> Result<PathBuf> {

crates/pm/src/helper/lock.rs

@@ -30,6 +30,7 @@ impl Glob for TokioGlob {
 // Type aliases to hide concrete Glob type
 pub(crate) type GlobImpl = TokioGlob;
 pub(crate) type Registry = UnifiedRegistry;
+
 /// Context for ruborist operations.
 /// Centralizes Glob and configuration to avoid spreading concrete types.
 pub(crate) struct Context;

crates/pm/src/helper/ruborist_context.rs

@@ -27,6 +27,17 @@ pub fn start_workers(channels: PipelineChannels, cwd: PathBuf) -> PipelineHandle
             let Some(tarball_url) = info.tarball_url else {
                 continue;
             };
+            // Git packages are cloned & cached during BFS resolution (inside ruborist).
+            // The resolver still emits a PackageResolved event with a git tarball URL,
+            // so we intentionally skip the download here to avoid a redundant fetch.
+            if tarball_url.starts_with("git+") || tarball_url.starts_with("git://") {
+                tracing::debug!(
+                    "Skipping download for git package: {}@{}",
+                    info.name,
+                    info.version
+                );
+                continue;
+            }
             let name = info.name;
             let version = info.version;
             tokio::spawn(async move {

crates/pm/src/service/pipeline/worker.rs

@@ -37,7 +37,27 @@ pub fn download_count() -> usize {
 ///
 /// Uses `OnceMap` to deduplicate: the same `name@version` is only downloaded once,
 /// even when called concurrently from multiple tasks (pipeline workers, install phase, etc.).
+///
+/// For git URLs (starting with `git+` or `git://`), the package should already be
+/// in cache from pre-resolution. Returns the cache path directly without downloading.
 pub async fn download_to_cache(name: &str, version: &str, tarball_url: &str) -> Option<PathBuf> {
+    // Git packages are already cached during resolution.
+    if tarball_url.starts_with("git+") || tarball_url.starts_with("git://") {
+        let cache_dir = get_cache_dir();
+        if let Some(cache_path) = utoo_ruborist::git::git_cache_path(&cache_dir, tarball_url)
+            && crate::fs::try_exists(&cache_path).await.unwrap_or(false)
+        {
+            tracing::debug!("Git package cache hit: {}@{}", name, version);
+            return Some(cache_path);
+        }
+        tracing::warn!(
+            "Git package {}@{} not found in cache, expected pre-resolution",
+            name,
+            version
+        );
+        return None;
+    }
+
     let key = format!("{}@{}", name, version);
     let cache_dir = get_cache_dir();
     let name = name.to_string();

crates/pm/src/util/downloader.rs

@@ -0,0 +1,57 @@
+//! Git package resolver.
+//!
+//! Thin wrappers around ruborist's git clone functionality,
+//! injecting the PM cache directory.
+
+use anyhow::Result;
+
+pub use utoo_ruborist::git::GitCloneResult;
+
+use super::cache::get_cache_dir;
+
+/// Resolve a git package spec by cloning the repo, checking out the ref,
+/// reading package.json, and caching the result.
+///
+/// # Arguments
+/// * `url` - Git URL, e.g. `git+https://github.com/user/repo.git`
+/// * `commit_ish` - Optional branch, tag, or commit to check out
+pub async fn resolve_git_spec(url: &str, commit_ish: Option<&str>) -> Result<GitCloneResult> {
+    let cache_dir = get_cache_dir();
+    utoo_ruborist::git::clone_repo(&cache_dir, url, commit_ish).await
+}
+
+/// Convert a `github:owner/repo` shorthand to a git+ URL and resolve.
+pub async fn resolve_github_spec(
+    owner: &str,
+    repo: &str,
+    commit_ish: Option<&str>,
+) -> Result<GitCloneResult> {
+    let url = format!("git+https://github.com/{}/{}.git", owner, repo);
+    resolve_git_spec(&url, commit_ish).await
+}
+
+/// Check if a resolved URL is a git URL.
+#[allow(dead_code)]
+pub fn is_git_resolved(resolved: &str) -> bool {
+    resolved.starts_with("git+") || resolved.starts_with("git://")
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_is_git_resolved() {
+        assert!(is_git_resolved(
+            "git+https://github.com/user/repo.git#abc123"
+        ));
+        assert!(is_git_resolved(
+            "git+ssh://git@github.com/user/repo.git#abc123"
+        ));
+        assert!(is_git_resolved("git://github.com/user/repo.git"));
+        assert!(!is_git_resolved(
+            "https://registry.npmjs.org/lodash/-/lodash-4.17.21.tgz"
+        ));
+        assert!(!is_git_resolved(""));
+    }
+}

crates/pm/src/util/git_resolver.rs

@@ -5,6 +5,7 @@ pub mod config_file;
 pub mod downloader;
 pub mod extractor;
 pub mod format_print;
+pub mod git_resolver;
 pub mod json;
 pub mod linker;
 pub mod logger;

crates/pm/src/util/mod.rs

@@ -19,6 +19,17 @@ tracing      = { workspace = true }
 # HTTP client - works on both native and WASM
 reqwest = { version = "0.12", default-features = false, features = ["json"] }
 
+# Git clone (optional, native-only)
+gix = { version = "0.72", default-features = false, features = [
+  "blocking-http-transport-reqwest-rust-tls",
+  "blocking-network-client",
+], optional = true }
+tempfile = { version = "3", optional = true }
+
+[features]
+default = []
+git     = ["gix", "tempfile"]
+
 # Async runtime (works on both native and WASM with forked tokio)
 [dependencies.tokio]
 workspace = true

crates/ruborist/Cargo.toml

@@ -76,6 +76,22 @@ 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, is_http_tarball_spec, parse_cli_spec};
+}
+
+/// Git clone and resolution helpers.
+pub mod git {
+    pub use crate::traits::git::GitCloneResult;
+
+    /// Clone a git repository, cache the result, and return metadata.
+    ///
+    /// Only available when the `git` feature is enabled.
+    #[cfg(feature = "git")]
+    pub use crate::resolver::git::{clone_repo, git_cache_path};
+}
+
 /// Utility functions.
 pub mod util {
     pub use crate::model::util::{parse_package_spec, read_package_json};