feat(pm): internalize git dependency resolution into ruborist

Move git clone & resolution logic into `utoo-ruborist` behind a
`native-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.

Key changes
-----------
- Add gix/tempfile as optional deps under `native-git` feature
- Add `resolve_non_registry_dep` with dual cfg (enabled / noop error)
- 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
- Extract `format_save_spec` for clean version-to-write logic
- Extract `resolve_cache_path` / `is_git_url` / `git_cache_lookup`
  so download_to_cache only handles registry tarballs
- PM enables `utoo-ruborist/native-git` instead of depending on gix
- `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 = ["native-git"] }
 
 [target.'cfg(not(target_arch = "wasm32"))'.dependencies]
 tokio = { workspace = true, features = ["full"] }

crates/pm/Cargo.toml

@@ -5,15 +5,16 @@ 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};
 use crate::util::user_config::get_legacy_peer_deps;
-use crate::util::{cloner::clone_package, downloader::download_to_cache};
+use crate::util::{cloner::clone_package, downloader::resolve_cache_path};
 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> {
@@ -238,7 +268,7 @@ pub async fn prepare_global_package_json(npm_spec: &str, prefix: Option<&str>) -
         .ok_or_else(|| anyhow!("Failed to get tarball URL from manifest"))?;
 
     // Download and extract package to cache
-    let cache_path = download_to_cache(&name, &resolved.version, tarball_url)
+    let cache_path = resolve_cache_path(&name, &resolved.version, tarball_url)
         .await
         .ok_or_else(|| anyhow!("Failed to download package {name}"))?;
 

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

@@ -1,7 +1,7 @@
 use std::path::PathBuf;
 
 use crate::util::cloner::{clone_package_once, wait_clone_if_pending};
-use crate::util::downloader::download_to_cache;
+use crate::util::downloader::{download_to_cache, is_git_url};
 
 use super::receiver::PipelineChannels;
 
@@ -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).
+            // Skip the download pipeline — the clone worker will pick up the
+            // pre-resolved cache path via resolve_cache_path.
+            if is_git_url(&tarball_url) {
+                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

@@ -3,7 +3,7 @@ use once_cell::sync::Lazy;
 use std::path::{Path, PathBuf};
 use std::sync::atomic::{AtomicUsize, Ordering};
 
-use super::downloader::download_to_cache;
+use super::downloader::resolve_cache_path;
 use super::json::load_package_json_from_path;
 use super::oncemap::OnceMap;
 use super::retry::create_retry_strategy;
@@ -48,7 +48,7 @@ pub async fn clone_package_once(
 
     CLONE_CACHE
         .get_or_init(key, || async move {
-            let cache_path = download_to_cache(&name, &version, &tarball_url).await?;
+            let cache_path = resolve_cache_path(&name, &version, &tarball_url).await?;
             clone_package(&cache_path, &target_path, &name, &version)
                 .await
                 .inspect_err(|e| {

crates/pm/src/util/cloner.rs

@@ -33,10 +33,49 @@ pub fn download_count() -> usize {
     DOWNLOAD_COUNT.load(Ordering::Relaxed)
 }
 
-/// Download a package tarball to the global cache directory, returning the cache path.
+/// Check whether a tarball URL refers to a git-resolved package.
+pub fn is_git_url(tarball_url: &str) -> bool {
+    tarball_url.starts_with("git+") || tarball_url.starts_with("git://")
+}
+
+/// Look up the cache path for a git-resolved package.
+///
+/// Git packages are cloned during BFS resolution (inside ruborist) and
+/// stored under `_git/<sha_prefix>/package/`.  This function simply
+/// computes that path and verifies it exists on disk.
+pub async fn git_cache_lookup(name: &str, version: &str, tarball_url: &str) -> Option<PathBuf> {
+    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
+    );
+    None
+}
+
+/// Resolve the local cache path for a package, downloading if necessary.
+///
+/// Routes git URLs to [`git_cache_lookup`] and registry tarballs to
+/// [`download_to_cache`].
+pub async fn resolve_cache_path(name: &str, version: &str, tarball_url: &str) -> Option<PathBuf> {
+    if is_git_url(tarball_url) {
+        return git_cache_lookup(name, version, tarball_url).await;
+    }
+    download_to_cache(name, version, tarball_url).await
+}
+
+/// Download a registry tarball to the global cache directory, returning the cache path.
 ///
 /// 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-resolved packages, use [`resolve_cache_path`] instead.
 pub async fn download_to_cache(name: &str, version: &str, tarball_url: &str) -> Option<PathBuf> {
     let key = format!("{}@{}", name, version);
     let cache_dir = get_cache_dir();

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    = []
+native-git = ["gix", "tempfile"]
+
 # Async runtime (works on both native and WASM with forked tokio)
 [dependencies.tokio]
 workspace = true