uvault 0.2.0__py3-none-any.whl

uvault/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.2.0"

uvault/add.py

@@ -0,0 +1,108 @@
+from pathlib import Path
+import urllib.parse
+import tomlkit
+
+from uvault.vcs import guess_repository_url
+
+
+class AddCommand:
+    def __init__(
+        self,
+        package: str,
+        url: str | None = None,
+        pr: str | None = None,
+        branch: str | None = None,
+        tag: str | None = None,
+        rev: str | None = None,
+        subdirectory: str | None = None,
+        pyproject_path: str = "pyproject.toml",
+    ):
+        self.package = package
+        self.url = url
+        self.pr = pr
+        self.branch = branch
+        self.tag = tag
+        self.rev = rev
+        self.subdirectory = subdirectory
+        self.pyproject_path = Path(pyproject_path)
+
+    def _parse_url(self):
+        if not self.url:
+            return
+
+        # Handle git+https://... format
+        if self.url.startswith("git+"):
+            url_no_git = self.url[4:]
+            parsed = urllib.parse.urlparse(url_no_git)
+
+            # Extract rev/branch/tag from @...
+            if "@" in parsed.path:
+                path, ref = parsed.path.split("@", 1)
+                self.url = f"{parsed.scheme}://{parsed.netloc}{path}"
+                self.rev = (
+                    ref  # by default it's a rev, could be branch/tag but uv accepts rev
+                )
+            else:
+                self.url = f"{parsed.scheme}://{parsed.netloc}{parsed.path}"
+
+            # Extract subdirectory from #subdirectory=...
+            if parsed.fragment:
+                fragments = urllib.parse.parse_qs(parsed.fragment)
+                if "subdirectory" in fragments:
+                    self.subdirectory = fragments["subdirectory"][0]
+
+    def run(self):
+        if not self.pyproject_path.exists():
+            print("pyproject.toml not found")
+            return 1
+
+        self._parse_url()
+
+        if not self.url:
+            guessed_url = guess_repository_url(self.package)
+            if not guessed_url:
+                print(f"Could not find or guess repository URL for {self.package}")
+                return 1
+            self.url = guessed_url
+            print(f"Guessed repository URL: {self.url}")
+
+        with open(self.pyproject_path, "r", encoding="utf-8") as f:
+            doc = tomlkit.parse(f.read())
+
+        if "tool" not in doc:
+            doc.add("tool", tomlkit.table())
+        if "uvault" not in doc["tool"]:
+            doc["tool"].add("uvault", tomlkit.table())
+        if "sources" not in doc["tool"]["uvault"]:
+            doc["tool"]["uvault"].add("sources", tomlkit.table())
+
+        uvault_sources = doc["tool"]["uvault"]["sources"]
+
+        new_source = tomlkit.inline_table()
+        new_source["git"] = self.url
+
+        # Priority: pr, rev, branch, tag
+        if self.pr:
+            if "github.com" in self.url:
+                new_source["rev"] = f"refs/pull/{self.pr}/head"
+            else:
+                new_source["rev"] = f"refs/merge-requests/{self.pr}/head"
+        elif self.rev:
+            new_source["rev"] = self.rev
+        elif self.branch:
+            new_source["branch"] = self.branch
+        elif self.tag:
+            new_source["tag"] = self.tag
+
+        if self.subdirectory:
+            new_source["subdirectory"] = self.subdirectory
+
+        uvault_sources[self.package] = new_source
+
+        with open(self.pyproject_path, "w", encoding="utf-8") as f:
+            f.write(tomlkit.dumps(doc))
+
+        print(f"Added {self.package} to [tool.uvault.sources]")
+        print("Run `uvault sync` to lock this dependency in [tool.uv.sources]")
+
+        return 0

uvault/cli.py

@@ -0,0 +1,87 @@
+import argparse
+import sys
+from uvault.sync import SyncCommand
+from uvault.develop import DevelopCommand
+from uvault.add import AddCommand
+
+
+def main(argv=None):
+    if argv is None:
+        argv = sys.argv[1:]  # pragma: no cover
+
+    parser = argparse.ArgumentParser(
+        description="Development and vaulting workflow for uv VCS dependencies."
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    # Sync command
+    sync_parser = subparsers.add_parser("sync", help="Sync and vault VCS dependencies.")
+    sync_parser.add_argument(
+        "-U",
+        "--update",
+        action="store_true",
+        help="Force update the vaulted reference.",
+    )
+    sync_parser.add_argument(
+        "-P",
+        "--package",
+        action="append",
+        help="Specific package to sync. Can be used multiple times.",
+    )
+
+    sync_parser.add_argument(
+        "--delete-extra",
+        action="store_true",
+        help="Delete references in uv.sources that are not in uvault.sources.",
+    )
+    sync_parser.add_argument(
+        "--keep-develop",
+        action="store_true",
+        help="Keep packages that are in local develop mode instead of restoring them.",
+    )
+
+    # Add command
+    add_parser = subparsers.add_parser("add", help="Add a new vaulting intention.")
+    add_parser.add_argument("package", help="The package to add")
+    add_parser.add_argument("url", nargs="?", help="The VCS URL or PEP 508 string")
+    add_parser.add_argument("--pr", help="Pull request number")
+    add_parser.add_argument("--branch", help="Branch name")
+    add_parser.add_argument("--tag", help="Tag name")
+    add_parser.add_argument("--rev", help="Revision SHA")
+    add_parser.add_argument("--subdirectory", help="Subdirectory in the repository")
+
+    # Develop command
+    dev_parser = subparsers.add_parser("develop", help="Develop a package locally.")
+    dev_parser.add_argument("package", help="The package to develop")
+    dev_parser.add_argument("branch", help="Branch name to checkout or create")
+
+    args = parser.parse_args(argv)
+
+    if args.command == "sync":
+        cmd = SyncCommand(
+            packages=args.package,
+            update=args.update,
+            delete_extra=args.delete_extra,
+            keep_develop=args.keep_develop,
+        )
+        return cmd.run()
+    elif args.command == "develop":
+        cmd = DevelopCommand(package=args.package, branch=args.branch)
+        return cmd.run()
+    elif args.command == "add":
+        cmd = AddCommand(
+            package=args.package,
+            url=args.url,
+            pr=args.pr,
+            branch=args.branch,
+            tag=args.tag,
+            rev=args.rev,
+            subdirectory=args.subdirectory,
+        )
+        return cmd.run()
+
+    return 0  # pragma: no cover
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

uvault/develop.py

@@ -0,0 +1,124 @@
+from pathlib import Path
+import tomlkit
+
+from uvault.vcs import GitVcs, GitReference, get_repo_name, compute_vault_urls
+
+
+class DevelopCommand:
+    def __init__(
+        self,
+        package: str,
+        branch: str,
+        pyproject_path: str = "pyproject.toml",
+    ):
+        self.package = package
+        self.branch = branch
+        self.pyproject_path = Path(pyproject_path)
+        self.vcs = GitVcs()
+
+    def _read_user_config(self) -> dict:
+        config_path = Path("~/.config/uvault/config.toml").expanduser()
+        if config_path.exists():
+            with open(config_path, "r", encoding="utf-8") as f:
+                try:
+                    return tomlkit.parse(f.read())
+                except Exception:
+                    pass
+        return {}
+
+    def run(self):
+        if not self.pyproject_path.exists():
+            print("pyproject.toml not found")
+            return 1
+
+        with open(self.pyproject_path, "r", encoding="utf-8") as f:
+            doc = tomlkit.parse(f.read())
+
+        tool_uvault = doc.get("tool", {}).get("uvault", {})
+        sources = tool_uvault.get("sources", {})
+
+        origin_url = None
+        git_ref = None
+        subdirectory = None
+
+        if self.package in sources and "git" in sources[self.package]:
+            source_cfg = sources[self.package]
+            origin_url = source_cfg["git"]
+            git_ref = GitReference.from_config(source_cfg)
+            subdirectory = source_cfg.get("subdirectory")
+        else:
+            print(
+                f"Could not find configuration for {self.package} in [tool.uvault.sources]."
+            )
+            print("Please run `uvault add` first to declare it.")
+            return 1
+
+        dev_directory = tool_uvault.get("dev_directory", ".src")
+        dest_dir = self.pyproject_path.parent / dev_directory / self.package
+
+        repo_name = get_repo_name(origin_url)
+
+        vaults = tool_uvault.get("vcs_vaults", [])
+        if vaults:
+            vault_config = next((v for v in vaults if v.get("default")), vaults[0])
+            _, vault_push_url = compute_vault_urls(repo_name, vault_config)
+        else:
+            vault_push_url = None
+
+        if dest_dir.exists():
+            print(f"Directory {dest_dir} already exists. Checking status...")
+            # Check if clean
+            if not self.vcs.check_clean_state(dest_dir):
+                print(f"Error: {dest_dir} has uncommitted changes. Aborting.")
+                return 1
+        else:
+            print(f"Cloning {origin_url} into {dest_dir}...")
+            dest_dir.parent.mkdir(parents=True, exist_ok=True)
+            self.vcs.clone(origin_url, dest_dir)
+
+        # Configure remotes
+        self.vcs.set_remote(dest_dir, "origin", origin_url)
+
+        if vault_push_url:
+            self.vcs.set_remote(dest_dir, "vault", vault_push_url)
+
+        user_config = self._read_user_config()
+        remotes = user_config.get("remotes", {})
+        for remote_name, remote_prefix in remotes.items():
+            if remote_name in ("origin", "vault"):
+                continue
+            remote_url = f"{remote_prefix.rstrip('/')}/{repo_name}.git"
+            # just add the remote without fetching
+            self.vcs.set_remote(dest_dir, remote_name, remote_url)
+
+        # Checkout requested branch or ref
+        if not self.vcs.checkout_reference(dest_dir, origin_url, git_ref, self.branch):
+            print(
+                f"Could not resolve reference {git_ref.value if git_ref else 'None'} at {origin_url}"
+            )
+            return 1
+
+        if "uv" not in doc["tool"]:
+            doc["tool"].add("uv", tomlkit.table())
+        if "sources" not in doc["tool"]["uv"]:
+            doc["tool"]["uv"].add("sources", tomlkit.table())
+
+        uv_sources = doc["tool"]["uv"]["sources"]
+
+        new_source = tomlkit.inline_table()
+        # Compute relative path
+        rel_path = f"./{dev_directory.rstrip('/')}/{self.package}"
+        if subdirectory:
+            rel_path = f"{rel_path}/{subdirectory}"
+        new_source["path"] = rel_path
+        new_source["editable"] = True
+
+        uv_sources[self.package] = new_source
+
+        with open(self.pyproject_path, "w", encoding="utf-8") as f:
+            f.write(tomlkit.dumps(doc))
+
+        print(f"Updated pyproject.toml to use local editable path for {self.package}")
+        print("Please run `uv sync` or `uv lock` to update your uv.lock file.")
+
+        return 0

uvault/sync.py

@@ -0,0 +1,228 @@
+from pathlib import Path
+import tomlkit
+import re
+from uvault.vcs import (
+    GitVcs,
+    VcsProvider,
+    GitReference,
+    get_repo_name,
+    compute_vault_urls,
+)
+
+
+def normalize_pkg_name(name: str) -> str:
+    """Normalize a Python package name for comparison."""
+    return re.sub(r"[-_.]+", "-", name).lower()
+
+
+class PackageSyncer:
+    def __init__(
+        self,
+        pkg: str,
+        source_cfg: dict,
+        vcs: VcsProvider,
+        cache_dir: Path,
+        vault_config: dict,
+        tag_prefix: str,
+        force_update: bool,
+        project_version: str | None = None,
+        include_project_version: bool = True,
+    ):
+        self.pkg = pkg
+        self.source_cfg = source_cfg
+        self.vcs = vcs
+        self.cache_dir = cache_dir
+        self.vault_config = vault_config
+        self.tag_prefix = tag_prefix
+        self.force_update = force_update
+        self.project_version = project_version
+        self.include_project_version = include_project_version
+
+    def process(self) -> dict | None:
+        origin_git = self.source_cfg.get("git")
+        git_ref = GitReference.from_config(self.source_cfg)
+
+        if not origin_git or not git_ref:
+            print(
+                f"Package {self.pkg} is missing 'git' or a valid reference ('rev', 'tag', 'branch') in [tool.uvault.sources]"
+            )
+            return None
+
+        print(f"Syncing {self.pkg}...")
+
+        sha = self.vcs.get_remote_sha(origin_git, git_ref)
+        if not sha:
+            print(f"Failed to resolve {git_ref.value} in {origin_git}")
+            return None
+
+        tag_name = self.tag_prefix
+        if self.include_project_version and self.project_version:
+            tag_name += f"{self.project_version}+"
+        tag_name += sha
+        repo_name = get_repo_name(origin_git)
+        vault_fetch_url, vault_push_url = compute_vault_urls(
+            repo_name, self.vault_config
+        )
+
+        if not self.force_update and self.vcs.remote_tag_exists(
+            vault_push_url, tag_name
+        ):
+            print(
+                f"Tag {tag_name} already exists in vault {vault_push_url}. Skipping vaulting."
+            )
+        else:
+            print(f"Vaulting to {vault_push_url} with tag {tag_name}...")
+            self.cache_dir.mkdir(parents=True, exist_ok=True)
+            repo_dir = self.cache_dir / repo_name
+            self.vcs.vault_reference(
+                origin_git, sha, vault_push_url, tag_name, repo_dir
+            )
+
+        new_source = tomlkit.inline_table()
+        new_source["git"] = vault_fetch_url
+        new_source["tag"] = tag_name
+        if "subdirectory" in self.source_cfg:
+            new_source["subdirectory"] = self.source_cfg["subdirectory"]
+
+        return new_source
+
+
+class SyncCommand:
+    def __init__(
+        self,
+        packages: str | list[str] | None = None,
+        update: bool = False,
+        delete_extra: bool = False,
+        keep_develop: bool = False,
+        pyproject_path: str = "pyproject.toml",
+        cache_dir: str = "~/.cache/uvault",
+        vcs: VcsProvider | None = None,
+    ):
+        if isinstance(packages, str):
+            self.packages = [packages]
+        else:
+            self.packages = packages or []
+        self.update = update
+        self.delete_extra = delete_extra
+        self.keep_develop = keep_develop
+        self.pyproject_path = Path(pyproject_path)
+        self.cache_dir = Path(cache_dir).expanduser()
+        self.vcs = vcs or GitVcs()
+
+    def run(self):
+        if not self.pyproject_path.exists():
+            print("pyproject.toml not found")
+            return 1
+
+        with open(self.pyproject_path, "r", encoding="utf-8") as f:
+            doc = tomlkit.parse(f.read())
+
+        tool_uvault = doc.get("tool", {}).get("uvault", {})
+        if not tool_uvault:
+            print("No [tool.uvault] section in pyproject.toml")
+            return 1
+
+        tag_prefix = tool_uvault.get("tag_prefix", "")
+        vaults = tool_uvault.get("vcs_vaults", [])
+        if not vaults:
+            print("No [[tool.uvault.vcs_vaults]] configured.")
+            return 1
+
+        vault_config = next((v for v in vaults if v.get("default")), vaults[0])
+
+        project_version = doc.get("project", {}).get("version")
+        include_project_version = tool_uvault.get("include_project_version", True)
+
+        sources = tool_uvault.get("sources", {})
+
+        if "uv" not in doc["tool"]:
+            doc["tool"].add("uv", tomlkit.table())
+
+        if "sources" not in doc["tool"]["uv"]:
+            doc["tool"]["uv"].add("sources", tomlkit.table())
+
+        uv_sources = doc["tool"]["uv"]["sources"]
+
+        packages_to_sync = self.packages if self.packages else list(sources.keys())
+
+        has_changes = False
+
+        normalized_sources = {normalize_pkg_name(k): k for k in sources.keys()}
+        normalized_uv_sources = {normalize_pkg_name(k): k for k in uv_sources.keys()}
+        normalized_packages = {normalize_pkg_name(p) for p in self.packages}
+
+        for pkg in packages_to_sync:
+            norm_pkg = normalize_pkg_name(pkg)
+            if norm_pkg not in normalized_sources:
+                print(f"Package {pkg} not found in [tool.uvault.sources]")
+                continue
+
+            actual_source_key = normalized_sources[norm_pkg]
+            force_update = self.update or norm_pkg in normalized_packages
+
+            is_develop = False
+            if norm_pkg in normalized_uv_sources:
+                uv_pkg_key = normalized_uv_sources[norm_pkg]
+                uv_pkg_cfg = uv_sources.get(uv_pkg_key)
+                if isinstance(uv_pkg_cfg, dict):
+                    is_develop = (
+                        uv_pkg_cfg.get("editable") is True or "path" in uv_pkg_cfg
+                    )
+
+            if is_develop:
+                if self.keep_develop:
+                    print(
+                        f"Package {pkg} is in develop mode. Skipping (--keep-develop is set)."
+                    )
+                    continue
+                else:
+                    force_update = True
+                    print(
+                        f"Package {pkg} is in develop mode. Restoring to vaulted state."
+                    )
+
+            if norm_pkg in normalized_uv_sources and not force_update:
+                print(
+                    f"Package {pkg} is already in [tool.uv.sources]. Skipping (use --update to force)."
+                )
+                continue
+
+            syncer = PackageSyncer(
+                pkg=actual_source_key,
+                source_cfg=sources[actual_source_key],
+                vcs=self.vcs,
+                cache_dir=self.cache_dir,
+                vault_config=vault_config,
+                tag_prefix=tag_prefix,
+                force_update=force_update,
+                project_version=project_version,
+                include_project_version=include_project_version,
+            )
+
+            new_source = syncer.process()
+            if new_source is not None:
+                # Remove the old unnormalized key from uv_sources if it exists
+                if (
+                    norm_pkg in normalized_uv_sources
+                    and normalized_uv_sources[norm_pkg] != actual_source_key
+                ):
+                    del uv_sources[normalized_uv_sources[norm_pkg]]
+
+                uv_sources[actual_source_key] = new_source
+                normalized_uv_sources[norm_pkg] = actual_source_key
+                has_changes = True
+
+        if self.delete_extra:
+            for uv_pkg in list(uv_sources.keys()):
+                if normalize_pkg_name(uv_pkg) not in normalized_sources:
+                    del uv_sources[uv_pkg]
+                    print(f"Removed extra package {uv_pkg} from [tool.uv.sources].")
+                    has_changes = True
+
+        if has_changes:
+            with open(self.pyproject_path, "w", encoding="utf-8") as f:
+                f.write(tomlkit.dumps(doc))
+            print("Updated pyproject.toml")
+            print("Please run `uv sync` or `uv lock` to update your uv.lock file.")
+
+        return 0

uvault/vcs.py

@@ -0,0 +1,281 @@
+import abc
+import subprocess
+import re
+from pathlib import Path
+from dataclasses import dataclass
+from urllib.parse import urlparse
+from importlib.metadata import metadata, PackageNotFoundError
+
+
+def guess_repository_url(package_name: str) -> str | None:
+    try:
+        meta = metadata(package_name)
+    except PackageNotFoundError:
+        return None
+
+    urls = []
+    homepage = meta.get("Home-page")
+    if homepage:
+        urls.append(("Home-page", homepage))
+
+    project_urls = meta.get_all("Project-URL") or []
+    for purl in project_urls:
+        if "," in purl:
+            name, url = purl.split(",", 1)
+            urls.append((name.strip(), url.strip()))
+
+    best_score = -1
+    best_url = None
+
+    for name, url in urls:
+        score = 0
+        name_lower = name.lower()
+        if "source" in name_lower or "repository" in name_lower:
+            score += 20
+        elif "home" in name_lower:
+            score += 10
+
+        url_lower = url.lower()
+        if "github.com" in url_lower:
+            score += 5
+        elif "gitlab.com" in url_lower:
+            score += 5
+        elif "git" in url_lower:
+            score += 2
+
+        if score > best_score:
+            best_score = score
+            best_url = url
+
+    return best_url
+
+
+def get_repo_name(git_url: str) -> str:
+    if git_url.startswith("git@"):
+        path = git_url.split(":")[-1]
+    elif git_url.startswith("ssh://"):
+        parsed = urlparse(git_url)
+        path = parsed.path
+    else:
+        parsed = urlparse(git_url)
+        path = parsed.path
+
+    repo_name = path.split("/")[-1]
+    if repo_name.endswith(".git"):
+        repo_name = repo_name[:-4]
+    return repo_name
+
+
+def compute_vault_urls(repo_name: str, vault_config: dict) -> tuple[str, str]:
+    provider = vault_config.get("provider", "github.com")
+    owner = vault_config.get("owner", "")
+    fetch_ssh = vault_config.get("fetch_ssh", False)
+    push_ssh = vault_config.get("push_ssh", True)
+
+    path = f"{owner}/{repo_name}.git" if owner else f"{repo_name}.git"
+
+    fetch_url = (
+        f"ssh://git@{provider}/{path}" if fetch_ssh else f"https://{provider}/{path}"
+    )
+    push_url = (
+        f"ssh://git@{provider}/{path}" if push_ssh else f"https://{provider}/{path}"
+    )
+
+    return fetch_url, push_url
+
+
+@dataclass
+class GitReference:
+    ref_type: str
+    value: str
+
+    @classmethod
+    def from_config(cls, source_cfg: dict) -> "GitReference | None":
+        for key in ["rev", "tag", "branch"]:
+            if key in source_cfg:
+                return cls(key, source_cfg[key])
+        return None
+
+    def get_ls_remote_args(self) -> list[str]:
+        if self.ref_type == "tag":
+            return ["--tags", self.value]
+        elif self.ref_type == "branch":
+            return ["--heads", self.value]
+        else:
+            return [self.value]
+
+
+class VcsProvider(abc.ABC):
+    @abc.abstractmethod
+    def get_remote_sha(self, origin_url: str, ref: GitReference) -> str | None:
+        pass  # pragma: no cover
+
+    @abc.abstractmethod
+    def remote_tag_exists(self, vault_url: str, tag_name: str) -> bool:
+        pass  # pragma: no cover
+
+    @abc.abstractmethod
+    def vault_reference(
+        self, origin_url: str, sha: str, vault_url: str, tag_name: str, repo_dir: Path
+    ) -> None:
+        pass  # pragma: no cover
+
+    @abc.abstractmethod
+    def check_clean_state(self, repo_dir: Path) -> bool:
+        pass  # pragma: no cover
+
+    @abc.abstractmethod
+    def fetch_remote(
+        self, repo_dir: Path, remote: str = "origin", ref: str | None = None
+    ) -> None:
+        pass  # pragma: no cover
+
+    @abc.abstractmethod
+    def checkout_reference(
+        self, repo_dir: Path, origin_url: str, ref: GitReference | None, branch: str
+    ) -> bool:
+        pass  # pragma: no cover
+
+    @abc.abstractmethod
+    def clone(self, url: str, dest: Path) -> None:
+        pass  # pragma: no cover
+
+    @abc.abstractmethod
+    def set_remote(self, repo_dir: Path, name: str, url: str) -> None:
+        pass  # pragma: no cover
+
+
+class GitVcs(VcsProvider):
+    def get_remote_sha(self, origin_url: str, ref: GitReference) -> str | None:
+        args = ["git", "ls-remote", origin_url] + ref.get_ls_remote_args()
+        try:
+            result = subprocess.run(
+                args,
+                capture_output=True,
+                text=True,
+                check=True,
+            )
+            output = result.stdout.strip()
+            if output:
+                return output.split()[0]
+        except subprocess.CalledProcessError:
+            pass
+
+        if ref.ref_type == "rev" and re.match(r"^[0-9a-f]{40}$", ref.value):
+            return ref.value
+        return None
+
+    def remote_tag_exists(self, vault_url: str, tag_name: str) -> bool:
+        try:
+            result = subprocess.run(
+                ["git", "ls-remote", "--tags", vault_url, tag_name],
+                capture_output=True,
+                text=True,
+                check=True,
+            )
+            output = result.stdout.strip()
+            if output:
+                return True
+        except subprocess.CalledProcessError:
+            pass
+        return False
+
+    def fetch_commit_from_reference(
+        self, repo_dir: Path, origin_url: str, ref: GitReference | str
+    ) -> str | None:
+        if isinstance(ref, GitReference):
+            sha = self.get_remote_sha(origin_url, ref)
+        else:
+            sha = ref
+
+        if not sha:
+            return None
+
+        print(f"fetching {sha} in {repo_dir}")
+        self.fetch_remote(repo_dir, "origin", sha)
+        return sha
+
+    def vault_reference(
+        self, origin_url: str, sha: str, vault_url: str, tag_name: str, repo_dir: Path
+    ) -> None:
+        if not repo_dir.exists():
+            subprocess.run(
+                ["git", "clone", "--bare", origin_url, str(repo_dir)], check=True
+            )
+        self.fetch_commit_from_reference(repo_dir, origin_url, sha)
+        subprocess.run(
+            [
+                "git",
+                "-C",
+                str(repo_dir),
+                "push",
+                vault_url,
+                f"{sha}:refs/tags/{tag_name}",
+            ],
+            check=True,
+        )
+
+    def check_clean_state(self, repo_dir: Path) -> bool:
+        res = subprocess.run(
+            ["git", "-C", str(repo_dir), "status", "--porcelain"],
+            capture_output=True,
+            text=True,
+        )
+        return not bool(res.stdout.strip())
+
+    def fetch_remote(
+        self, repo_dir: Path, remote: str = "origin", ref: str | None = None
+    ) -> None:
+        args = ["git", "-C", str(repo_dir), "fetch", remote]
+        if ref:
+            args.append(ref)
+        subprocess.run(args, check=True)
+
+    def checkout_reference(
+        self, repo_dir: Path, origin_url: str, ref: GitReference | None, branch: str
+    ) -> bool:
+        if not ref:
+            print("Error: No VCS reference provided.")
+            return False
+
+        sha = self.fetch_commit_from_reference(repo_dir, origin_url, ref)
+        if not sha:
+            return False
+
+        res = subprocess.run(
+            [
+                "git",
+                "-C",
+                str(repo_dir),
+                "show-ref",
+                "--verify",
+                "--quiet",
+                f"refs/heads/{branch}",
+            ]
+        )
+        if res.returncode == 0:
+            print(f"Switching to existing branch '{branch}'")
+            subprocess.run(["git", "-C", str(repo_dir), "checkout", branch], check=True)
+        else:
+            print(f"Creating and switching to new branch '{branch}' from {sha}")
+            subprocess.run(
+                ["git", "-C", str(repo_dir), "checkout", "-b", branch, sha], check=True
+            )
+        return True
+
+    def clone(self, url: str, dest: Path) -> None:
+        subprocess.run(
+            ["git", "clone", "--filter=blob:none", url, str(dest)], check=True
+        )
+
+    def set_remote(self, repo_dir: Path, name: str, url: str) -> None:
+        subprocess.run(
+            ["git", "-C", str(repo_dir), "remote", "add", name, url],
+            check=False,
+            capture_output=True,
+        )
+        subprocess.run(
+            ["git", "-C", str(repo_dir), "remote", "set-url", name, url],
+            check=False,
+            capture_output=True,
+        )

uvault-0.2.0.dist-info/METADATA

@@ -0,0 +1,23 @@
+Metadata-Version: 2.4
+Name: uvault
+Version: 0.2.0
+Summary: Development and vaulting workflow for uv VCS dependencies.
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: diskcache>=5.6.3
+Requires-Dist: tomlkit>=0.15.0
+Description-Content-Type: text/markdown
+
+# uvault
+
+Development and vaulting workflow for [uv](https://github.com/astral-sh/uv) VCS dependencies.
+
+Secure your Python projects against deleted or force-pushed upstream commits. `uvault` automatically vaults transient VCS references (like GitHub PRs) into your organization's own repositories, while allowing developers to instantly switch dependencies into local editable mode—fully integrated with `pyproject.toml` and `uv`.
+
+## Documentation
+
+The complete documentation is available in the `docs/` folder:
+
+* [Quickstart & Key Features](docs/index.md) - Learn what `uvault` is and how to get started quickly.
+* [How-To Guides](docs/how-to.md) - Step-by-step guides for installing and using `uvault` in your day-to-day workflow.
+* [CLI & Configuration Reference](docs/reference.md) - Detailed information on `pyproject.toml` configuration (`[tool.uvault]`) and all CLI commands (`sync`, `add`, `develop`).

uvault-0.2.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+uvault/__init__.py,sha256=Zn1KFblwuFHiDRdRAiRnDBRkbPttWh44jKa5zG2ov0E,22
+uvault/add.py,sha256=D04t4vQetyWyjtShSZy1LKPu59oOpBAq0k9aWXw-UwM,3529
+uvault/cli.py,sha256=-yFaA90lO5E-XG3LCoU9RIP-Vb0XlQ07PhENLKY4Ig8,2862
+uvault/develop.py,sha256=jYE8OGyv8h_c-cJbYDPSbE5EHaDQtvgJywj7qh9dFTs,4447
+uvault/sync.py,sha256=UaHnc2946CjrGyMn_VikGUEg-okfi0FO8S00Iv0M5dA,8066
+uvault/vcs.py,sha256=Tw3GlEZuSxOnenays6Y8Ls44iD5rvF7pp-rCdYTfYuo,8350
+uvault-0.2.0.dist-info/METADATA,sha256=FI--RcIYZLLlNarj5ZDFZSojfxH86zn0_Oi0b4y8bRc,1183
+uvault-0.2.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+uvault-0.2.0.dist-info/entry_points.txt,sha256=YoWE87yJANUf16f7uxcCQrzvaEXuXsjmGatNUPrhgNs,43
+uvault-0.2.0.dist-info/licenses/LICENSE,sha256=64_pHIGyduDj8AOXZhRSQc282c68pR4xAHu5Q7JmttQ,1071
+uvault-0.2.0.dist-info/RECORD,,

uvault-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

uvault-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+uvault = uvault.cli:main

uvault-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pierre Verkest
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.