pz-cli 5.0.0__py3-none-any.whl

pz_core/authoring/sync_service.py

@@ -0,0 +1,787 @@
+from __future__ import annotations
+
+from contextlib import contextmanager
+import csv
+from fnmatch import fnmatchcase
+import os
+import re
+import shutil
+import subprocess
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path
+
+from pz_core.project_sources import (
+    OFFICIAL_CONTRIB_SOURCE_ROOT,
+    OFFICIAL_TRUTH_SOURCE_REPO_NAMES,
+    resolve_contrib_source_root,
+    resolve_sources_root,
+)
+from pz_core.runtime.errors import PzError
+from pz_core.utils.project_jsonc import PROJECT_JSONC_NAME, load_jsonc_file
+
+from .project_state import load_dev_manifest
+
+
+_OWNER = "pz_core.authoring.env"
+_EDITABLE_IMPORT_RE = re.compile(r"^\s*import\s+([A-Za-z0-9_]+)\s*;")
+_QUOTED_ABS_PATH_RE = re.compile(r"""['"](/[^'"]+)['"]""")
+_PROJECT_ENV_CONFIG_NAMES = (
+    PROJECT_JSONC_NAME,
+    "pz.develop.jsonc",
+    "pz.test.jsonc",
+    "pz.product.jsonc",
+)
+_GENERATED_SOURCE_ARTIFACT_DIR_PATTERNS = (
+    ".venv",
+    ".pytest_cache",
+    "__pycache__",
+    "*.egg-info",
+    "dist",
+)
+
+
+@dataclass(frozen=True, slots=True)
+class SyncTarget:
+    name: str
+    kind: str
+    path: Path
+    virtualenv_path: Path
+    exists: bool
+    has_pyproject: bool
+
+
+def build_sync_target(*, name: str, kind: str, path: Path) -> SyncTarget:
+    raw_path = _absolute_without_symlink_resolution(path)
+    resolved = raw_path.resolve()
+    exists = resolved.exists() and resolved.is_dir()
+    return SyncTarget(
+        name=name,
+        kind=kind,
+        path=resolved,
+        virtualenv_path=raw_path,
+        exists=exists,
+        has_pyproject=exists and (resolved / "pyproject.toml").is_file(),
+    )
+
+
+@dataclass(frozen=True, slots=True)
+class _EditableSourcePath:
+    resolved: Path
+    preferred: Path
+
+
+def _absolute_without_symlink_resolution(path: Path) -> Path:
+    expanded = path.expanduser()
+    if not expanded.is_absolute():
+        expanded = Path.cwd() / expanded
+    return expanded.absolute()
+
+
+def collect_sync_targets(project_dir: Path) -> tuple[SyncTarget, ...]:
+    targets: list[SyncTarget] = []
+    seen_paths: set[str] = set()
+
+    def add_target(*, name: str, kind: str, path: Path) -> None:
+        target = build_sync_target(name=name, kind=kind, path=path)
+        key = str(target.path)
+        if key in seen_paths:
+            return
+        seen_paths.add(key)
+        targets.append(target)
+
+    add_target(name="project", kind="project", path=project_dir)
+    manifest = load_dev_manifest(project_dir)
+    if manifest is None:
+        return tuple(targets)
+    for repo_key, repo in sorted(manifest.repos.items()):
+        add_target(
+            name=repo_key,
+            kind="repo",
+            path=project_dir / Path(*repo.checkout.parts),
+        )
+    for binding_key, binding in sorted(manifest.bindings.items()):
+        if binding.source_kind != "link":
+            continue
+        add_target(
+            name=binding_key,
+            kind=binding.kind,
+            path=Path(binding.source).expanduser(),
+        )
+    return tuple(targets)
+
+
+def sync_project_targets(
+    project_dir: Path,
+    *,
+    action: str,
+    groups: tuple[str, ...] = (),
+    extras: tuple[str, ...] = (),
+    reinstall_packages: tuple[str, ...] = (),
+    project_only: bool = False,
+) -> tuple[SyncTarget, ...]:
+    uv_binary = _require_uv_binary(action=action)
+    sync_targets = collect_sync_targets(project_dir)
+    inferred_extras = _infer_required_extras_for_project(project_dir, action=action)
+    if project_only:
+        sync_targets = tuple(item for item in sync_targets if item.kind == "project")
+    ordered_targets = [
+        *[item for item in sync_targets if item.kind == "project" and item.exists and item.has_pyproject],
+        *[item for item in sync_targets if item.kind != "project" and item.exists and item.has_pyproject],
+    ]
+    synced: list[SyncTarget] = []
+    for item in ordered_targets:
+        _sync_target(
+            item,
+            project_dir=project_dir,
+            uv_binary=uv_binary,
+            action=action,
+            groups=groups,
+            extras=extras,
+            inferred_extras=inferred_extras,
+            reinstall_packages=reinstall_packages,
+        )
+        synced.append(item)
+    return tuple(synced)
+
+
+def _require_uv_binary(*, action: str) -> str:
+    uv_binary = shutil.which("uv")
+    if uv_binary:
+        return uv_binary
+    raise PzError(
+        code="PZ_ENV_UV_MISSING",
+        message="required dependency backend was not found on PATH.",
+        stage="cli",
+        owner=_OWNER,
+        action=action,
+    )
+
+
+def _sync_target(
+    target: SyncTarget,
+    *,
+    project_dir: Path,
+    uv_binary: str,
+    action: str,
+    groups: tuple[str, ...] = (),
+    extras: tuple[str, ...] = (),
+    inferred_extras: tuple[str, ...] = (),
+    reinstall_packages: tuple[str, ...] = (),
+) -> None:
+    venv_path = _target_virtualenv_path(target.virtualenv_path)
+    editable_source_paths = _editable_source_paths_for_target(target.path)
+    allowed_editable_paths = tuple(item.resolved for item in editable_source_paths)
+    _prune_stale_editable_artifacts(venv_path, allowed_editable_paths=allowed_editable_paths)
+    reinstall_queue: list[str] = []
+    for package_name in (*reinstall_packages, *_find_corrupt_installed_distributions(venv_path)):
+        normalized = str(package_name).strip()
+        if normalized and normalized not in reinstall_queue:
+            reinstall_queue.append(normalized)
+    command = [uv_binary, "sync"]
+    for group in groups:
+        command.extend(["--group", group])
+    for extra in _extras_for_target(target, extras=extras, inferred_extras=inferred_extras):
+        command.extend(["--extra", extra])
+    for package_name in reinstall_queue:
+        command.extend(["--reinstall-package", package_name])
+    with _prepare_sync_execution(project_dir=project_dir, target=target, command=command, uv_binary=uv_binary, action=action) as prepared:
+        completed = subprocess.run(
+            prepared.command,
+            cwd=str(prepared.cwd),
+            check=False,
+            capture_output=True,
+            text=True,
+            env=prepared.env,
+        )
+        if completed.returncode == 0:
+            _canonicalize_editable_artifacts(venv_path, editable_source_paths=editable_source_paths)
+            _prune_generated_source_artifacts_for_target(project_dir=project_dir, target=target)
+            return
+        detail = (completed.stderr or completed.stdout or "dependency sync failed").strip()
+        raise PzError(
+            code="PZ_ENV_SYNC_FAILED",
+            message=f"failed to run dependency sync for {target.kind}:{target.name}.",
+            stage="cli",
+            owner=_OWNER,
+            action=action,
+            detail=detail,
+        )
+
+
+def _extras_for_target(
+    target: SyncTarget,
+    *,
+    extras: tuple[str, ...],
+    inferred_extras: tuple[str, ...] = (),
+) -> tuple[str, ...]:
+    if target.kind == "project":
+        return tuple(extra for extra in extras if extra)
+    supported = _declared_optional_dependency_names(target)
+    resolved: list[str] = []
+    for extra in (*extras, *inferred_extras):
+        normalized = str(extra).strip()
+        if normalized and normalized in supported and normalized not in resolved:
+            resolved.append(normalized)
+    if target.kind == "runtime" and _runtime_target_has_contrib_checkout(target) and "contrib" not in resolved:
+        resolved.append("contrib")
+    return tuple(resolved)
+
+
+def _infer_required_extras_for_project(project_dir: Path, *, action: str) -> tuple[str, ...]:
+    required: list[str] = []
+    for config_name in _PROJECT_ENV_CONFIG_NAMES:
+        payload = load_jsonc_file(
+            project_dir / config_name,
+            owner=_OWNER,
+            action=action,
+        )
+        database = _project_database_config(payload)
+        if database is None or not _database_config_is_enabled(database):
+            continue
+        extra = _database_config_required_extra(database)
+        if extra is not None and extra not in required:
+            required.append(extra)
+    return tuple(required)
+
+
+def _project_database_config(payload: dict[str, object]) -> dict[str, object] | None:
+    apps = payload.get("apps")
+    if not isinstance(apps, dict):
+        return None
+    foundation = apps.get("pz_foundation")
+    if not isinstance(foundation, dict):
+        return None
+    database = foundation.get("database")
+    return database if isinstance(database, dict) else None
+
+
+def _database_config_is_enabled(database: dict[str, object]) -> bool:
+    enabled = database.get("enabled")
+    state = str(database.get("state") or "").strip().lower()
+    if enabled is False or state == "disabled":
+        return False
+    if enabled is True or state == "enabled":
+        return True
+    return _database_config_required_extra(database) is not None
+
+
+def _database_config_required_extra(database: dict[str, object]) -> str | None:
+    driver = str(database.get("driver") or "").strip().lower()
+    urls = database.get("urls")
+    url_values = [str(url).strip().lower() for url in urls] if isinstance(urls, list) else []
+    if driver in {"postgres", "postgresql"} or any(
+        url.startswith(("postgres://", "postgresql://")) for url in url_values
+    ):
+        return "db-postgres"
+    if driver in {"mysql", "mariadb"} or any(
+        url.startswith(("mysql://", "mysql+pymysql://", "mariadb://")) for url in url_values
+    ):
+        return "db-mysql"
+    return None
+
+
+def _declared_optional_dependency_names(target: SyncTarget) -> frozenset[str]:
+    pyproject_path = target.path / "pyproject.toml"
+    if not pyproject_path.is_file():
+        return frozenset()
+    try:
+        payload = tomllib.loads(pyproject_path.read_text(encoding="utf-8"))
+    except tomllib.TOMLDecodeError as exc:
+        raise PzError(
+            code="PZ_ENV_INVALID_PYPROJECT",
+            message=f"failed to parse pyproject for {target.kind}:{target.name}.",
+            stage="cli",
+            owner=_OWNER,
+            action="sync",
+            detail=str(exc),
+        ) from exc
+    optional_dependencies = payload.get("project", {}).get("optional-dependencies", {})
+    if not isinstance(optional_dependencies, dict):
+        return frozenset()
+    return frozenset(str(name).strip() for name in optional_dependencies if str(name).strip())
+
+
+def _runtime_target_has_contrib_checkout(target: SyncTarget) -> bool:
+    path = target.path.resolve()
+    candidates = (
+        resolve_contrib_source_root(path),
+        resolve_contrib_source_root(path.parent),
+    )
+    return any(candidate.is_dir() for candidate in candidates)
+
+
+@dataclass(frozen=True, slots=True)
+class _PreparedSyncExecution:
+    command: tuple[str, ...]
+    cwd: Path
+    env: dict[str, str]
+
+
+@contextmanager
+def _prepare_sync_execution(
+    *,
+    project_dir: Path,
+    target: SyncTarget,
+    command: list[str],
+    uv_binary: str,
+    action: str,
+):
+    env = os.environ.copy()
+    prepared_command = list(command)
+    if target.kind != "project" or _project_virtualenv_exists(project_dir, target):
+        venv_path = _ensure_target_virtualenv(target.virtualenv_path, uv_binary=uv_binary, action=action)
+        env["VIRTUAL_ENV"] = str(venv_path)
+        prepared_command.append("--active")
+    yield _PreparedSyncExecution(
+        command=tuple(prepared_command),
+        cwd=target.path,
+        env=env,
+    )
+
+
+def _project_virtualenv_exists(project_dir: Path, target: SyncTarget) -> bool:
+    if target.kind != "project":
+        return False
+    if target.path.resolve() != project_dir.resolve():
+        return False
+    return _is_valid_virtualenv(project_dir / ".venv")
+
+
+def _discover_truth_source_root(target_path: Path) -> Path | None:
+    for candidate in (target_path.resolve(), *target_path.resolve().parents):
+        if candidate.name == ".sources":
+            if all(
+                _resolve_truth_source_repo_root(candidate, repo_name) is not None
+                for repo_name in OFFICIAL_TRUTH_SOURCE_REPO_NAMES
+            ):
+                return candidate
+    return None
+
+
+def _resolve_truth_source_repo_root(sources_root: Path, repo_name: str) -> Path | None:
+    exact = sources_root / repo_name
+    if exact.exists():
+        return exact.resolve()
+    return None
+
+
+def _prune_generated_source_artifacts_for_target(*, project_dir: Path, target: SyncTarget) -> None:
+    cleanup_roots: list[Path] = []
+    direct_sources_root = _discover_truth_source_root(target.path)
+    if direct_sources_root is not None:
+        cleanup_roots.append(target.path.resolve())
+    elif target.kind == "project":
+        host_sources_root = _discover_truth_source_root(resolve_sources_root(project_dir))
+        if host_sources_root is not None:
+            for repo_name in OFFICIAL_TRUTH_SOURCE_REPO_NAMES:
+                repo_root = _resolve_truth_source_repo_root(host_sources_root, repo_name)
+                if repo_root is not None:
+                    cleanup_roots.append(repo_root.resolve())
+    seen: set[Path] = set()
+    for root in cleanup_roots:
+        resolved = root.resolve()
+        if resolved in seen or not resolved.is_dir():
+            continue
+        seen.add(resolved)
+        _prune_generated_source_artifacts(resolved)
+
+
+def _prune_generated_source_artifacts(root: Path) -> tuple[Path, ...]:
+    removed: list[Path] = []
+    seen: set[Path] = set()
+    for pattern in _GENERATED_SOURCE_ARTIFACT_DIR_PATTERNS:
+        for candidate in sorted(root.rglob(pattern)):
+            if not _is_generated_source_artifact_dir(candidate):
+                continue
+            if candidate.is_symlink():
+                link_path = candidate.absolute()
+                if link_path in seen:
+                    continue
+                seen.add(link_path)
+                candidate.unlink(missing_ok=True)
+                removed.append(link_path)
+                continue
+            if not candidate.is_dir():
+                continue
+            resolved = candidate.resolve()
+            if resolved in seen or resolved == root:
+                continue
+            seen.add(resolved)
+            shutil.rmtree(resolved, ignore_errors=True)
+            removed.append(resolved)
+    return tuple(removed)
+
+
+def _is_generated_source_artifact_dir(path: Path) -> bool:
+    if not any(fnmatchcase(path.name, pattern) for pattern in _GENERATED_SOURCE_ARTIFACT_DIR_PATTERNS):
+        return False
+    if path.name == "dist":
+        return (path.parent / "pyproject.toml").is_file()
+    return True
+
+
+def _prune_stale_editable_artifacts(
+    venv_path: Path,
+    *,
+    allowed_editable_paths: tuple[Path, ...] = (),
+) -> tuple[Path, ...]:
+    site_packages_dirs = _iter_site_packages_dirs(venv_path)
+    if not site_packages_dirs:
+        return ()
+    stale: set[Path] = set()
+    stale_finder_modules: set[str] = set()
+    finder_files: dict[str, Path] = {}
+
+    for site_packages in site_packages_dirs:
+        for candidate in site_packages.iterdir():
+            if not candidate.is_file():
+                continue
+            if candidate.suffix not in {".pth", ".py"}:
+                continue
+            text = candidate.read_text(encoding="utf-8", errors="ignore")
+            if candidate.name.endswith("_finder.py"):
+                finder_files[candidate.stem] = candidate
+            if _editable_artifact_is_stale(candidate, text, allowed_editable_paths=allowed_editable_paths):
+                stale.add(candidate)
+                if candidate.name.endswith("_finder.py"):
+                    stale_finder_modules.add(candidate.stem)
+
+    for site_packages in site_packages_dirs:
+        for candidate in site_packages.iterdir():
+            if not candidate.is_file() or candidate.suffix != ".pth":
+                continue
+            if candidate in stale:
+                continue
+            text = candidate.read_text(encoding="utf-8", errors="ignore")
+            imported_finder = _imported_editable_finder_module(text)
+            if imported_finder is None:
+                continue
+            finder_path = finder_files.get(imported_finder)
+            if imported_finder in stale_finder_modules or finder_path is None or not finder_path.exists():
+                stale.add(candidate)
+
+    for candidate in sorted(stale):
+        candidate.unlink(missing_ok=True)
+    return tuple(sorted(stale))
+
+
+def _find_corrupt_installed_distributions(venv_path: Path) -> tuple[str, ...]:
+    broken: list[str] = []
+    for site_packages in _iter_site_packages_dirs(venv_path):
+        for dist_info in sorted(site_packages.glob("*.dist-info")):
+            record_path = dist_info / "RECORD"
+            if not record_path.is_file():
+                continue
+            if not _record_has_missing_site_packages_payload(record_path, site_packages):
+                continue
+            name = _read_distribution_name_from_metadata(dist_info / "METADATA")
+            if not name:
+                name = _distribution_name_from_dist_info_dir(dist_info)
+            if name and name not in broken:
+                broken.append(name)
+    return tuple(broken)
+
+
+def _record_has_missing_site_packages_payload(record_path: Path, site_packages: Path) -> bool:
+    try:
+        rows = csv.reader(record_path.read_text(encoding="utf-8").splitlines())
+    except Exception:
+        return False
+    for row in rows:
+        if not row:
+            continue
+        rel_path = str(row[0]).strip()
+        if not rel_path or rel_path.startswith(".."):
+            continue
+        normalized = rel_path.replace("\\", "/")
+        if normalized.endswith((".pyc", ".pyo")) or "/__pycache__/" in normalized:
+            continue
+        if not (site_packages / rel_path).exists():
+            return True
+    return False
+
+
+def _read_distribution_name_from_metadata(metadata_path: Path) -> str | None:
+    try:
+        for line in metadata_path.read_text(encoding="utf-8").splitlines():
+            if line.startswith("Name: "):
+                value = line.split(":", 1)[1].strip()
+                if value:
+                    return value
+    except Exception:
+        return None
+    return None
+
+
+def _distribution_name_from_dist_info_dir(dist_info_dir: Path) -> str | None:
+    name = dist_info_dir.name
+    if not name.endswith(".dist-info"):
+        return None
+    stem = name[: -len(".dist-info")]
+    if "-" not in stem:
+        return stem.replace("_", "-")
+    distribution, _version = stem.rsplit("-", 1)
+    distribution = distribution.strip().replace("_", "-")
+    return distribution or None
+
+
+def _iter_site_packages_dirs(venv_path: Path) -> tuple[Path, ...]:
+    if not venv_path.is_dir():
+        return ()
+    discovered: list[Path] = []
+    for parent in (venv_path / "lib", venv_path / "Lib"):
+        if not parent.is_dir():
+            continue
+        for candidate in sorted(parent.glob("python*/site-packages")):
+            if candidate.is_dir():
+                discovered.append(candidate)
+    scripts_candidate = venv_path / "Lib" / "site-packages"
+    if scripts_candidate.is_dir():
+        discovered.append(scripts_candidate)
+    seen: set[Path] = set()
+    ordered: list[Path] = []
+    for candidate in discovered:
+        resolved = candidate.resolve()
+        if resolved in seen:
+            continue
+        seen.add(resolved)
+        ordered.append(resolved)
+    return tuple(ordered)
+
+
+def _editable_artifact_is_stale(
+    path: Path,
+    text: str,
+    *,
+    allowed_editable_paths: tuple[Path, ...] = (),
+) -> bool:
+    if ".pz-sync-" in text:
+        return True
+    for raw_path in _quoted_absolute_paths(text):
+        if ".pz-sync-" in raw_path or not Path(raw_path).exists():
+            return True
+        if allowed_editable_paths and _is_editable_artifact(path) and not _path_is_allowed_editable_source(
+            raw_path,
+            allowed_editable_paths,
+        ):
+            return True
+    if path.suffix == ".pth":
+        stripped = text.strip()
+        if stripped.startswith("/") and "\n" not in stripped and not Path(stripped).exists():
+            return True
+        if (
+            stripped.startswith("/")
+            and "\n" not in stripped
+            and allowed_editable_paths
+            and not _path_is_allowed_editable_source(stripped, allowed_editable_paths)
+        ):
+            return True
+    return False
+
+
+def _is_editable_artifact(path: Path) -> bool:
+    return path.suffix == ".pth" or path.name.startswith("__editable__") or path.name.endswith("_finder.py")
+
+
+def _path_is_allowed_editable_source(raw_path: str, allowed_editable_paths: tuple[Path, ...]) -> bool:
+    try:
+        candidate = Path(raw_path).expanduser().resolve()
+    except OSError:
+        candidate = Path(raw_path).expanduser().absolute()
+    for allowed in allowed_editable_paths:
+        try:
+            normalized = allowed.expanduser().resolve()
+        except OSError:
+            normalized = allowed.expanduser().absolute()
+        if candidate == normalized:
+            return True
+        try:
+            if candidate.is_relative_to(normalized):
+                return True
+        except ValueError:
+            continue
+    return False
+
+
+def _canonicalize_editable_artifacts(
+    venv_path: Path,
+    *,
+    editable_source_paths: tuple[_EditableSourcePath, ...],
+) -> tuple[Path, ...]:
+    if not editable_source_paths:
+        return ()
+    changed: list[Path] = []
+    for site_packages in _iter_site_packages_dirs(venv_path):
+        for candidate in site_packages.iterdir():
+            if not candidate.is_file() or candidate.suffix not in {".pth", ".py"}:
+                continue
+            if not _is_editable_artifact(candidate):
+                continue
+            text = candidate.read_text(encoding="utf-8", errors="ignore")
+            rewritten = _canonicalize_editable_artifact_text(candidate, text, editable_source_paths)
+            if rewritten == text:
+                continue
+            candidate.write_text(rewritten, encoding="utf-8")
+            changed.append(candidate)
+    return tuple(changed)
+
+
+def _canonicalize_editable_artifact_text(
+    path: Path,
+    text: str,
+    editable_source_paths: tuple[_EditableSourcePath, ...],
+) -> str:
+    rewritten = text
+    for raw_path in _quoted_absolute_paths(text):
+        preferred = _preferred_editable_path(raw_path, editable_source_paths)
+        if preferred is None:
+            continue
+        rewritten = rewritten.replace(raw_path, preferred.as_posix())
+    if path.suffix == ".pth":
+        stripped = rewritten.strip()
+        if stripped.startswith("/") and "\n" not in stripped:
+            preferred = _preferred_editable_path(stripped, editable_source_paths)
+            if preferred is not None:
+                rewritten = preferred.as_posix()
+                if text.endswith("\n"):
+                    rewritten += "\n"
+    return rewritten
+
+
+def _preferred_editable_path(raw_path: str, editable_source_paths: tuple[_EditableSourcePath, ...]) -> Path | None:
+    try:
+        candidate = Path(raw_path).expanduser().resolve()
+    except OSError:
+        candidate = Path(raw_path).expanduser().absolute()
+    for source in editable_source_paths:
+        try:
+            if candidate == source.resolved:
+                return source.preferred
+            if candidate.is_relative_to(source.resolved):
+                return source.preferred / candidate.relative_to(source.resolved)
+        except ValueError:
+            continue
+    return None
+
+
+def _editable_source_paths_for_target(target_path: Path) -> tuple[_EditableSourcePath, ...]:
+    target_root = target_path.expanduser().absolute()
+    roots: list[Path] = [target_root]
+    roots.extend(_collect_local_path_dependency_preferred_roots(target_root))
+    seen: set[Path] = set()
+    ordered: list[_EditableSourcePath] = []
+    for root in roots:
+        try:
+            resolved = root.resolve()
+        except OSError:
+            resolved = root.absolute()
+        if resolved in seen:
+            continue
+        seen.add(resolved)
+        ordered.append(_EditableSourcePath(resolved=resolved, preferred=root.absolute()))
+    return tuple(ordered)
+
+
+def _quoted_absolute_paths(text: str) -> tuple[str, ...]:
+    return tuple(match.group(1) for match in _QUOTED_ABS_PATH_RE.finditer(text or ""))
+
+
+def _imported_editable_finder_module(text: str) -> str | None:
+    match = _EDITABLE_IMPORT_RE.match(text or "")
+    if match is None:
+        return None
+    return str(match.group(1)).strip() or None
+
+
+def _collect_local_path_dependency_preferred_roots(target_root: Path) -> tuple[Path, ...]:
+    pyproject_path = target_root / "pyproject.toml"
+    if not pyproject_path.is_file():
+        return ()
+    try:
+        document = tomllib.loads(pyproject_path.read_text(encoding="utf-8"))
+    except Exception:
+        return ()
+    tool = document.get("tool")
+    if not isinstance(tool, dict):
+        return ()
+    uv = tool.get("uv")
+    if not isinstance(uv, dict):
+        return ()
+    sources = uv.get("sources")
+    if not isinstance(sources, dict):
+        return ()
+    roots: list[Path] = []
+    for source_meta in sources.values():
+        if not isinstance(source_meta, dict):
+            continue
+        raw_path = str(source_meta.get("path") or "").strip()
+        if not raw_path:
+            continue
+        path = Path(raw_path)
+        if path.is_absolute():
+            preferred = path.absolute()
+        else:
+            preferred = (target_root / path).absolute()
+        if not preferred.exists():
+            continue
+        roots.append(preferred)
+    return tuple(roots)
+
+
+def _source_project_root(target_path: Path) -> Path | None:
+    absolute = target_path.expanduser().absolute()
+    for candidate in (absolute, *absolute.parents):
+        if candidate.name == ".sources" and candidate.parent.name == "apps":
+            return candidate.parent.parent.absolute()
+    return None
+
+
+def _target_virtualenv_path(target_path: Path) -> Path:
+    project_root = _source_project_root(target_path)
+    absolute = target_path.expanduser().absolute()
+    if project_root is None:
+        return absolute.resolve() / ".venv"
+    try:
+        relative = absolute.relative_to(project_root)
+    except ValueError:
+        return absolute.resolve() / ".venv"
+    return project_root / ".runtime" / "source-venvs" / relative / ".venv"
+
+
+def _ensure_target_virtualenv(target_path: Path, *, uv_binary: str, action: str) -> Path:
+    venv_path = _target_virtualenv_path(target_path)
+    if _is_valid_virtualenv(venv_path):
+        return venv_path.resolve()
+    venv_path.parent.mkdir(parents=True, exist_ok=True)
+    completed = subprocess.run(
+        [uv_binary, "venv", str(venv_path)],
+        cwd=str(target_path),
+        check=False,
+        capture_output=True,
+        text=True,
+        env=os.environ.copy(),
+    )
+    if completed.returncode == 0 and _is_valid_virtualenv(venv_path):
+        return venv_path.resolve()
+    detail = (completed.stderr or completed.stdout or "failed to create virtual environment").strip()
+    raise PzError(
+        code="PZ_ENV_SYNC_VENV_FAILED",
+        message=f"failed to prepare virtual environment for {target_path}.",
+        stage="cli",
+        owner=_OWNER,
+        action=action,
+        detail=detail,
+    )
+
+
+def _is_valid_virtualenv(path: Path) -> bool:
+    candidates = (
+        path / "bin" / "python",
+        path / "bin" / "python3",
+        path / "Scripts" / "python.exe",
+    )
+    return any(candidate.is_file() for candidate in candidates)
+
+
+__all__ = ["SyncTarget", "build_sync_target", "collect_sync_targets", "sync_project_targets"]