feat(vcs): add mozart-vcs crate for VCS repository support

Implement VCS driver/downloader infrastructure mirroring Composer's VCS
subsystem. Includes drivers for GitHub, GitLab, Bitbucket, Forgejo, Git,
Hg, and SVN with API-based metadata resolution, plus source downloaders
for Git/Hg/SVN. Integrates into mozart-registry via vcs_bridge module to
scan VCS repositories and feed discovered packages into the SAT resolver.

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

4 files changed, 278 insertions, 0 deletions

diff --git a/crates/mozart-vcs/src/downloader/git.rs b/crates/mozart-vcs/src/downloader/git.rs
new file mode 100644
index 0000000..3bdb9ca
--- /dev/null
+++ b/crates/mozart-vcs/src/downloader/git.rs
@@ -0,0 +1,112 @@
+use std::path::Path;
+
+use anyhow::Result;
+
+use crate::process::ProcessExecutor;
+use crate::util::git::GitUtil;
+
+use super::VcsDownloader;
+
+/// Git downloader using clone/checkout with optional mirror cache.
+///
+/// Corresponds to Composer's `Downloader\GitDownloader`.
+pub struct GitDownloader {
+    git_util: GitUtil,
+}
+
+impl GitDownloader {
+    pub fn new(git_util: GitUtil) -> Self {
+        Self { git_util }
+    }
+}
+
+impl VcsDownloader for GitDownloader {
+    fn download(&self, url: &str, _reference: &str, _target: &Path) -> Result<()> {
+        // Pre-sync the mirror so install can use --reference
+        self.git_util.sync_mirror(url)?;
+        Ok(())
+    }
+
+    fn install(&self, url: &str, reference: &str, target: &Path) -> Result<()> {
+        let target_str = target.to_string_lossy();
+        let mirror_path = self.git_util.mirror_path(url);
+
+        if mirror_path.join("HEAD").exists() {
+            // Clone with mirror reference for efficiency
+            let mirror_str = mirror_path.to_string_lossy().to_string();
+            self.git_util.run_command(
+                &[
+                    "git",
+                    "clone",
+                    "--no-checkout",
+                    "--dissociate",
+                    "--reference",
+                    &mirror_str,
+                    "--",
+                    url,
+                    &target_str,
+                ],
+                url,
+                None,
+            )?;
+        } else {
+            self.git_util.run_command(
+                &["git", "clone", "--no-checkout", "--", url, &target_str],
+                url,
+                None,
+            )?;
+        }
+
+        // Checkout the specific reference
+        let process = ProcessExecutor::new();
+        process.execute_checked(&["git", "checkout", reference, "--force"], Some(target))?;
+
+        Ok(())
+    }
+
+    fn update(&self, url: &str, _old_ref: &str, new_ref: &str, target: &Path) -> Result<()> {
+        let process = ProcessExecutor::new();
+
+        // Update remote URL
+        process.execute_checked(
+            &["git", "remote", "set-url", "origin", "--", url],
+            Some(target),
+        )?;
+
+        // Fetch latest
+        self.git_util
+            .run_command(&["git", "fetch", "origin"], url, Some(target))?;
+
+        // Checkout new reference
+        process.execute_checked(&["git", "checkout", new_ref, "--force"], Some(target))?;
+
+        Ok(())
+    }
+
+    fn remove(&self, target: &Path) -> Result<()> {
+        if target.exists() {
+            std::fs::remove_dir_all(target)?;
+        }
+        Ok(())
+    }
+
+    fn local_changes(&self, target: &Path) -> Result<Option<String>> {
+        let process = ProcessExecutor::new();
+        let output = process.execute(&["git", "status", "--porcelain"], Some(target))?;
+        if output.stdout.trim().is_empty() {
+            Ok(None)
+        } else {
+            Ok(Some(output.stdout))
+        }
+    }
+
+    fn commit_logs(&self, from: &str, to: &str, target: &Path) -> Result<String> {
+        let process = ProcessExecutor::new();
+        let range = format!("{from}..{to}");
+        let output = process.execute(
+            &["git", "log", &range, "--oneline", "--no-decorate"],
+            Some(target),
+        )?;
+        Ok(output.stdout)
+    }
+}
diff --git a/crates/mozart-vcs/src/downloader/hg.rs b/crates/mozart-vcs/src/downloader/hg.rs
new file mode 100644
index 0000000..bfffa07
--- /dev/null
+++ b/crates/mozart-vcs/src/downloader/hg.rs
@@ -0,0 +1,71 @@
+use std::path::Path;
+
+use anyhow::Result;
+
+use crate::util::hg::HgUtil;
+
+use super::VcsDownloader;
+
+/// Mercurial downloader using clone/pull/update.
+pub struct HgDownloader {
+    hg_util: HgUtil,
+}
+
+impl HgDownloader {
+    pub fn new(hg_util: HgUtil) -> Self {
+        Self { hg_util }
+    }
+}
+
+impl VcsDownloader for HgDownloader {
+    fn download(&self, _url: &str, _reference: &str, _target: &Path) -> Result<()> {
+        Ok(())
+    }
+
+    fn install(&self, url: &str, reference: &str, target: &Path) -> Result<()> {
+        let target_str = target.to_string_lossy().to_string();
+        self.hg_util
+            .execute(&["clone", "--", url, &target_str], None)?;
+        self.hg_util
+            .execute(&["update", "-r", reference], Some(target))?;
+        Ok(())
+    }
+
+    fn update(&self, url: &str, _old_ref: &str, new_ref: &str, target: &Path) -> Result<()> {
+        self.hg_util.execute(&["pull", url], Some(target))?;
+        self.hg_util
+            .execute(&["update", "-r", new_ref], Some(target))?;
+        Ok(())
+    }
+
+    fn remove(&self, target: &Path) -> Result<()> {
+        if target.exists() {
+            std::fs::remove_dir_all(target)?;
+        }
+        Ok(())
+    }
+
+    fn local_changes(&self, target: &Path) -> Result<Option<String>> {
+        let output = self.hg_util.execute(&["st"], Some(target))?;
+        if output.stdout.trim().is_empty() {
+            Ok(None)
+        } else {
+            Ok(Some(output.stdout))
+        }
+    }
+
+    fn commit_logs(&self, from: &str, to: &str, target: &Path) -> Result<String> {
+        let range = format!("{from}:{to}");
+        let output = self.hg_util.execute(
+            &[
+                "log",
+                "-r",
+                &range,
+                "--template",
+                "{rev}:{node|short} {desc|firstline}\\n",
+            ],
+            Some(target),
+        )?;
+        Ok(output.stdout)
+    }
+}
diff --git a/crates/mozart-vcs/src/downloader/mod.rs b/crates/mozart-vcs/src/downloader/mod.rs
new file mode 100644
index 0000000..7186348
--- /dev/null
+++ b/crates/mozart-vcs/src/downloader/mod.rs
@@ -0,0 +1,31 @@
+pub mod git;
+pub mod hg;
+pub mod svn;
+
+use std::path::Path;
+
+use anyhow::Result;
+
+/// The VCS downloader interface.
+///
+/// Corresponds to Composer's `VcsDownloader` hierarchy.
+pub trait VcsDownloader {
+    /// Prepare for installation (e.g., sync mirror cache).
+    fn download(&self, url: &str, reference: &str, target: &Path) -> Result<()>;
+
+    /// Install (clone/checkout) the source to the target directory.
+    fn install(&self, url: &str, reference: &str, target: &Path) -> Result<()>;
+
+    /// Update the source at target to a new reference.
+    fn update(&self, url: &str, old_ref: &str, new_ref: &str, target: &Path) -> Result<()>;
+
+    /// Remove the source from the target directory.
+    fn remove(&self, target: &Path) -> Result<()>;
+
+    /// Detect local changes in the working copy.
+    /// Returns `None` if clean, `Some(diff)` if modified.
+    fn local_changes(&self, target: &Path) -> Result<Option<String>>;
+
+    /// Get commit log between two references.
+    fn commit_logs(&self, from: &str, to: &str, target: &Path) -> Result<String>;
+}
diff --git a/crates/mozart-vcs/src/downloader/svn.rs b/crates/mozart-vcs/src/downloader/svn.rs
new file mode 100644
index 0000000..5222b06
--- /dev/null
+++ b/crates/mozart-vcs/src/downloader/svn.rs
@@ -0,0 +1,64 @@
+use std::path::Path;
+
+use anyhow::Result;
+
+use crate::util::svn::SvnUtil;
+
+use super::VcsDownloader;
+
+/// SVN downloader using checkout/switch.
+pub struct SvnDownloader {
+    svn_util: SvnUtil,
+}
+
+impl SvnDownloader {
+    pub fn new(svn_util: SvnUtil) -> Self {
+        Self { svn_util }
+    }
+}
+
+impl VcsDownloader for SvnDownloader {
+    fn download(&self, _url: &str, _reference: &str, _target: &Path) -> Result<()> {
+        // SVN doesn't need a pre-download step
+        Ok(())
+    }
+
+    fn install(&self, url: &str, reference: &str, target: &Path) -> Result<()> {
+        let target_str = target.to_string_lossy().to_string();
+        let svn_url = format!("{url}@{reference}");
+        self.svn_util
+            .execute(&["checkout", &svn_url, &target_str], None)?;
+        Ok(())
+    }
+
+    fn update(&self, url: &str, _old_ref: &str, new_ref: &str, target: &Path) -> Result<()> {
+        let svn_url = format!("{url}@{new_ref}");
+        self.svn_util
+            .execute(&["switch", "--ignore-ancestry", &svn_url], Some(target))?;
+        Ok(())
+    }
+
+    fn remove(&self, target: &Path) -> Result<()> {
+        if target.exists() {
+            std::fs::remove_dir_all(target)?;
+        }
+        Ok(())
+    }
+
+    fn local_changes(&self, target: &Path) -> Result<Option<String>> {
+        let output = self.svn_util.execute(&["status"], Some(target))?;
+        if output.stdout.trim().is_empty() {
+            Ok(None)
+        } else {
+            Ok(Some(output.stdout))
+        }
+    }
+
+    fn commit_logs(&self, from: &str, to: &str, target: &Path) -> Result<String> {
+        let range = format!("{from}:{to}");
+        let output = self
+            .svn_util
+            .execute(&["log", "-r", &range], Some(target))?;
+        Ok(output.stdout)
+    }
+}