pz-cli 5.0.0__py3-none-any.whl

pz_core/authoring/app_versions.py

@@ -0,0 +1,814 @@
+from __future__ import annotations
+
+import base64
+import json
+import os
+import re
+import shutil
+import stat
+import subprocess
+import sys
+import tempfile
+import tomllib
+import uuid
+from dataclasses import dataclass
+from html.parser import HTMLParser
+from pathlib import Path
+from typing import Callable, Iterable, Mapping, MutableMapping, cast
+from urllib.parse import unquote, urljoin, urlsplit, urlunsplit
+from urllib.request import Request, urlopen
+
+import tomlkit  # type: ignore[import-not-found]
+from packaging.requirements import Requirement
+from packaging.specifiers import SpecifierSet
+from packaging.utils import canonicalize_name, parse_sdist_filename, parse_wheel_filename
+from packaging.version import InvalidVersion, Version
+from tomlkit.exceptions import TOMLKitError  # type: ignore[import-not-found]
+
+from pz_core.runtime.errors import PzError
+
+from .project_state import (
+    add_declared_app,
+    ensure_project_state,
+    load_installed_apps,
+    remove_declared_app,
+)
+from .release import install_env, load_install_target
+from .venv_service import ensure_project_virtualenv, resolve_virtualenv_python
+
+
+_OWNER = "pz_core.authoring.app_versions"
+_OpenUrl = Callable[..., object]
+
+
+@dataclass(frozen=True, slots=True)
+class AvailableVersion:
+    version: str
+    prerelease: bool
+    yanked: bool
+    compatible: bool
+
+
+@dataclass(frozen=True, slots=True)
+class AppVersionState:
+    app_id: str
+    distribution: str
+    available: tuple[AvailableVersion, ...]
+    latest: str | None
+    declared: str | None
+    locked: str | None
+    installed: str | None
+
+
+@dataclass(frozen=True, slots=True)
+class AppDeclarationResult:
+    app_id: str
+    distribution: str
+    version: str | None
+    installed_apps: tuple[str, ...]
+    changed: bool
+
+
+@dataclass(frozen=True, slots=True)
+class AppInstallResult:
+    app_id: str
+    distribution: str
+    version: str
+    python: Path
+    lock_path: Path
+
+
+@dataclass(frozen=True, slots=True)
+class _ReleaseFile:
+    version: Version
+    yanked: bool
+    requires_python: str | None
+
+
+class _SimpleLinksParser(HTMLParser):
+    def __init__(self) -> None:
+        super().__init__(convert_charrefs=True)
+        self.files: list[tuple[str, bool, str | None]] = []
+
+    def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
+        if tag.lower() != "a":
+            return
+        values = {key.lower(): value for key, value in attrs}
+        href = values.get("href")
+        if not href:
+            return
+        filename = unquote(urlsplit(href).path.rsplit("/", 1)[-1])
+        self.files.append(
+            (
+                filename,
+                "data-yanked" in values,
+                values.get("data-requires-python"),
+            )
+        )
+
+
+def _error(code: str, message: str, *, action: str, detail: str | None = None) -> PzError:
+    return PzError(
+        code=code,
+        message=message,
+        stage="cli",
+        owner=_OWNER,
+        action=action,
+        detail=detail,
+    )
+
+
+def distribution_name(app_id: str) -> str:
+    return canonicalize_name(app_id.replace("_", "-"))
+
+
+def _redacted_index(url: str) -> str:
+    parsed = urlsplit(url)
+    host = parsed.hostname or ""
+    if parsed.port is not None:
+        host = f"{host}:{parsed.port}"
+    return urlunsplit((parsed.scheme, host, parsed.path, "", ""))
+
+
+def _redact_credentials(text: str) -> str:
+    return re.sub(
+        r"([A-Za-z][A-Za-z0-9+.-]*://)[^/@\s]+@",
+        r"\1<redacted>@",
+        text,
+    )
+
+
+def _index_request(url: str) -> Request:
+    parsed = urlsplit(url)
+    host = parsed.hostname or ""
+    if parsed.port is not None:
+        host = f"{host}:{parsed.port}"
+    clean = urlunsplit((parsed.scheme, host, parsed.path, parsed.query, ""))
+    request = Request(
+        clean,
+        headers={
+            "Accept": "application/vnd.pypi.simple.v1+json, text/html;q=0.9",
+            "User-Agent": "pz/5 app-versions",
+        },
+    )
+    if parsed.username is not None:
+        credentials = f"{unquote(parsed.username)}:{unquote(parsed.password or '')}"
+        encoded = base64.b64encode(credentials.encode("utf-8")).decode("ascii")
+        request.add_header("Authorization", f"Basic {encoded}")
+    return request
+
+
+def _version_from_filename(filename: str, distribution: str) -> Version | None:
+    try:
+        if filename.endswith(".whl"):
+            name, version, _build, _tags = parse_wheel_filename(filename)
+        else:
+            name, version = parse_sdist_filename(filename)
+    except (InvalidVersion, ValueError):
+        return None
+    if canonicalize_name(name) != distribution:
+        return None
+    return version
+
+
+def _release_files_from_json(payload: object, distribution: str) -> tuple[_ReleaseFile, ...]:
+    if not isinstance(payload, Mapping) or not isinstance(payload.get("files"), list):
+        raise ValueError("Simple API JSON payload does not contain files")
+    files: list[_ReleaseFile] = []
+    for raw in cast(list[object], payload["files"]):
+        if not isinstance(raw, Mapping):
+            continue
+        filename = raw.get("filename")
+        if not isinstance(filename, str):
+            continue
+        version = _version_from_filename(filename, distribution)
+        if version is None:
+            continue
+        requires_python = raw.get("requires-python")
+        files.append(
+            _ReleaseFile(
+                version=version,
+                yanked=bool(raw.get("yanked", False)),
+                requires_python=requires_python if isinstance(requires_python, str) else None,
+            )
+        )
+    return tuple(files)
+
+
+def _release_files_from_html(text: str, distribution: str) -> tuple[_ReleaseFile, ...]:
+    parser = _SimpleLinksParser()
+    parser.feed(text)
+    files: list[_ReleaseFile] = []
+    for filename, yanked, requires_python in parser.files:
+        version = _version_from_filename(filename, distribution)
+        if version is not None:
+            files.append(_ReleaseFile(version, yanked, requires_python))
+    return tuple(files)
+
+
+def _python_compatible(specifier: str | None) -> bool:
+    if not specifier:
+        return True
+    current = Version(".".join(str(value) for value in sys.version_info[:3]))
+    try:
+        return current in SpecifierSet(specifier)
+    except Exception:
+        return False
+
+
+def _available_versions(files: Iterable[_ReleaseFile]) -> tuple[AvailableVersion, ...]:
+    grouped: dict[Version, list[_ReleaseFile]] = {}
+    for item in files:
+        grouped.setdefault(item.version, []).append(item)
+    result: list[AvailableVersion] = []
+    for version in sorted(grouped, reverse=True):
+        release_files = grouped[version]
+        compatible_files = [item for item in release_files if _python_compatible(item.requires_python)]
+        result.append(
+            AvailableVersion(
+                version=str(version),
+                prerelease=version.is_prerelease,
+                yanked=all(item.yanked for item in release_files),
+                compatible=any(not item.yanked for item in compatible_files),
+            )
+        )
+    return tuple(result)
+
+
+def _read_declared_version(project_dir: Path, distribution: str) -> str | None:
+    path = project_dir / "pyproject.toml"
+    if not path.is_file():
+        return None
+    try:
+        payload = tomllib.loads(path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeError, tomllib.TOMLDecodeError):
+        return None
+    project = payload.get("project")
+    dependencies = project.get("dependencies") if isinstance(project, Mapping) else None
+    if not isinstance(dependencies, list):
+        return None
+    for raw in dependencies:
+        if not isinstance(raw, str):
+            continue
+        try:
+            requirement = Requirement(raw)
+        except Exception:
+            continue
+        if canonicalize_name(requirement.name) != distribution:
+            continue
+        specs = list(requirement.specifier)
+        if len(specs) == 1 and specs[0].operator == "==" and not specs[0].version.endswith(".*"):
+            return str(Version(specs[0].version))
+    return None
+
+
+def _read_locked_version(project_dir: Path, distribution: str) -> str | None:
+    path = project_dir / "uv.lock"
+    if not path.is_file():
+        return None
+    try:
+        payload = tomllib.loads(path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeError, tomllib.TOMLDecodeError):
+        return None
+    packages = payload.get("package")
+    if not isinstance(packages, list):
+        return None
+    for package in packages:
+        if not isinstance(package, Mapping):
+            continue
+        if canonicalize_name(str(package.get("name") or "")) != distribution:
+            continue
+        version = package.get("version")
+        return str(version) if isinstance(version, str) and version else None
+    return None
+
+
+def _read_installed_version(project_dir: Path, distribution: str, *, action: str) -> str | None:
+    venv = project_dir / ".venv"
+    if not venv.is_dir():
+        return None
+    try:
+        python = resolve_virtualenv_python(venv, action=action)
+    except PzError:
+        return None
+    code = (
+        "import importlib.metadata, sys; "
+        "\ntry: print(importlib.metadata.version(sys.argv[1]))"
+        "\nexcept importlib.metadata.PackageNotFoundError: raise SystemExit(3)"
+    )
+    completed = subprocess.run(
+        (str(python), "-c", code, distribution),
+        check=False,
+        capture_output=True,
+        text=True,
+    )
+    if completed.returncode == 3:
+        return None
+    if completed.returncode != 0:
+        raise _error(
+            "PZ_APP_VERSION_STATE_MISMATCH",
+            f"failed to inspect installed version for {distribution}.",
+            action=action,
+            detail=(completed.stderr or completed.stdout or "metadata inspection failed").strip(),
+        )
+    value = completed.stdout.strip()
+    return value or None
+
+
+def query_app_versions(
+    app_id: str,
+    *,
+    project_dir: Path,
+    action: str,
+    opener: _OpenUrl = urlopen,
+) -> AppVersionState:
+    distribution = distribution_name(app_id)
+    target = load_install_target(app_id, project_dir=project_dir, action=action)
+    env = install_env(target=target, project_dir=project_dir, action=action)
+    base = env.get("UV_DEFAULT_INDEX") or target.index_url or "https://pypi.org/simple/"
+    url = urljoin(base.rstrip("/") + "/", distribution + "/")
+    try:
+        response = opener(_index_request(url), timeout=20)
+        content_type = str(getattr(response, "headers", {}).get("Content-Type", ""))
+        body = cast(bytes, response.read())
+        if "json" in content_type:
+            files = _release_files_from_json(json.loads(body.decode("utf-8")), distribution)
+        else:
+            files = _release_files_from_html(body.decode("utf-8"), distribution)
+    except Exception as exc:
+        raise _error(
+            "PZ_APP_INDEX_QUERY_FAILED",
+            f"failed to query versions for {distribution}.",
+            action=action,
+            detail=f"index={_redacted_index(url)}; error={exc}",
+        ) from exc
+    available = _available_versions(files)
+    latest = next(
+        (item.version for item in available if item.compatible and not item.prerelease and not item.yanked),
+        None,
+    )
+    return AppVersionState(
+        app_id=app_id,
+        distribution=distribution,
+        available=available,
+        latest=latest,
+        declared=_read_declared_version(project_dir, distribution),
+        locked=_read_locked_version(project_dir, distribution),
+        installed=_read_installed_version(project_dir, distribution, action=action),
+    )
+
+
+def _candidate_resolves(
+    state: AppVersionState,
+    version: str,
+    *,
+    project_dir: Path,
+    action: str,
+) -> bool:
+    uv_binary = shutil.which("uv")
+    if uv_binary is None:
+        raise _error(
+            "PZ_ENV_UV_MISSING",
+            "required dependency backend was not found on PATH.",
+            action=action,
+        )
+    source_pyproject = project_dir / "pyproject.toml"
+    if not source_pyproject.is_file():
+        raise _error(
+            "PZ_PROJECT_METADATA_INVALID",
+            "project pyproject.toml is missing.",
+            action=action,
+        )
+    with tempfile.TemporaryDirectory(prefix="pz-app-resolve-") as raw_temp:
+        temp = Path(raw_temp)
+        shutil.copy2(source_pyproject, temp / "pyproject.toml")
+        lock = project_dir / "uv.lock"
+        if lock.is_file():
+            shutil.copy2(lock, temp / "uv.lock")
+        _update_dependency(
+            temp,
+            state.distribution,
+            version,
+            action=action,
+        )
+        _absolutize_temp_source_paths(temp, source_project=project_dir, action=action)
+        target = load_install_target(
+            state.app_id, project_dir=project_dir, action=action
+        )
+        env = install_env(target=target, project_dir=project_dir, action=action)
+        completed = subprocess.run(
+            (
+                uv_binary,
+                "lock",
+                "--dry-run",
+                "--project",
+                str(temp),
+                "--upgrade-package",
+                state.distribution,
+                "--no-sources-package",
+                state.distribution,
+            ),
+            check=False,
+            capture_output=True,
+            text=True,
+            env=env,
+        )
+        return completed.returncode == 0
+
+
+def _absolutize_temp_source_paths(
+    temp_project: Path,
+    *,
+    source_project: Path,
+    action: str,
+) -> None:
+    path = temp_project / "pyproject.toml"
+    try:
+        document = tomlkit.parse(path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeError, TOMLKitError) as exc:
+        raise _error(
+            "PZ_PROJECT_METADATA_INVALID",
+            "temporary project metadata is invalid.",
+            action=action,
+            detail=str(exc),
+        ) from exc
+    tool = document.get("tool")
+    uv = tool.get("uv") if isinstance(tool, MutableMapping) else None
+    sources = uv.get("sources") if isinstance(uv, MutableMapping) else None
+    if not isinstance(sources, MutableMapping):
+        return
+    changed = False
+    for raw_source in sources.values():
+        entries = raw_source if isinstance(raw_source, list) else (raw_source,)
+        for entry in entries:
+            if not isinstance(entry, MutableMapping):
+                continue
+            raw_path = entry.get("path")
+            if not isinstance(raw_path, str) or Path(raw_path).is_absolute():
+                continue
+            entry["path"] = str((source_project / raw_path).resolve(strict=False))
+            changed = True
+    if changed:
+        path.write_text(tomlkit.dumps(document), encoding="utf-8")
+
+
+def resolve_app_version(
+    state: AppVersionState,
+    requested: str | None,
+    *,
+    action: str,
+    project_dir: Path | None = None,
+) -> str:
+    if requested is None:
+        candidates = tuple(
+            item.version
+            for item in state.available
+            if item.compatible and not item.prerelease and not item.yanked
+        )
+        if not candidates:
+            raise _error(
+                "PZ_APP_VERSION_NOT_FOUND",
+                f"no compatible stable version is available for {state.distribution}.",
+                action=action,
+            )
+        if project_dir is None:
+            return candidates[0]
+        for candidate in candidates:
+            if _candidate_resolves(
+                state,
+                candidate,
+                project_dir=project_dir,
+                action=action,
+            ):
+                return candidate
+        raise _error(
+            "PZ_APP_VERSION_INCOMPATIBLE",
+            f"no stable version of {state.distribution} satisfies the project dependency graph.",
+            action=action,
+        )
+    try:
+        version = Version(requested)
+    except InvalidVersion as exc:
+        raise _error(
+            "PZ_APP_VERSION_NOT_FOUND",
+            f"requested version is not an exact PEP 440 version: {requested}",
+            action=action,
+        ) from exc
+    match = next((item for item in state.available if Version(item.version) == version), None)
+    if match is None:
+        raise _error(
+            "PZ_APP_VERSION_NOT_FOUND",
+            f"version {version} is not available for {state.distribution}.",
+            action=action,
+        )
+    if match.yanked or not match.compatible:
+        raise _error(
+            "PZ_APP_VERSION_INCOMPATIBLE",
+            f"version {version} is not installable for {state.distribution}.",
+            action=action,
+        )
+    normalized = str(version)
+    if project_dir is not None and not _candidate_resolves(
+        state,
+        normalized,
+        project_dir=project_dir,
+        action=action,
+    ):
+        raise _error(
+            "PZ_APP_VERSION_INCOMPATIBLE",
+            f"version {normalized} conflicts with the project dependency graph.",
+            action=action,
+        )
+    return normalized
+
+
+def _project_table(document: object, *, action: str) -> MutableMapping[str, object]:
+    if not isinstance(document, MutableMapping):
+        raise _error("PZ_PROJECT_METADATA_INVALID", "pyproject root must be a table.", action=action)
+    project = document.get("project")
+    if not isinstance(project, MutableMapping):
+        raise _error("PZ_PROJECT_METADATA_INVALID", "pyproject project must be a table.", action=action)
+    return cast(MutableMapping[str, object], project)
+
+
+def _write_atomic(path: Path, before: bytes, after: bytes, *, action: str) -> None:
+    if before == after:
+        return
+    mode = stat.S_IMODE(path.stat().st_mode)
+    staged = path.with_name(f".{path.name}.{uuid.uuid4().hex}.tmp")
+    try:
+        descriptor = os.open(staged, os.O_WRONLY | os.O_CREAT | os.O_EXCL, mode)
+        with os.fdopen(descriptor, "wb") as handle:
+            handle.write(after)
+            handle.flush()
+            os.fsync(handle.fileno())
+        if path.read_bytes() != before:
+            raise _error("PZ_PROJECT_METADATA_CHANGED", "pyproject.toml changed concurrently.", action=action)
+        os.replace(staged, path)
+    finally:
+        staged.unlink(missing_ok=True)
+
+
+def _restore_snapshot(
+    path: Path,
+    *,
+    before: bytes,
+    expected_current: bytes,
+    action: str,
+) -> None:
+    try:
+        current = path.read_bytes()
+    except OSError as exc:
+        raise _error(
+            "PZ_PROJECT_METADATA_CHANGED",
+            f"cannot restore missing transaction file: {path.name}",
+            action=action,
+            detail=str(exc),
+        ) from exc
+    if current == before:
+        return
+    if current != expected_current:
+        raise _error(
+            "PZ_PROJECT_METADATA_CHANGED",
+            f"cannot restore concurrently changed transaction file: {path.name}",
+            action=action,
+        )
+    _write_atomic(path, current, before, action=action)
+
+
+def _update_dependency(
+    project_dir: Path,
+    distribution: str,
+    version: str | None,
+    *,
+    action: str,
+) -> bool:
+    path = project_dir / "pyproject.toml"
+    try:
+        before = path.read_bytes()
+        document = tomlkit.parse(before.decode("utf-8"))
+    except (OSError, UnicodeError, TOMLKitError) as exc:
+        raise _error("PZ_PROJECT_METADATA_INVALID", "project pyproject.toml is invalid.", action=action, detail=str(exc)) from exc
+    project = _project_table(document, action=action)
+    dependencies = project.get("dependencies")
+    if dependencies is None:
+        dependencies = tomlkit.array().multiline(True)
+        project["dependencies"] = dependencies
+    if not isinstance(dependencies, list):
+        raise _error("PZ_PROJECT_METADATA_INVALID", "project.dependencies must be an array.", action=action)
+    retained: list[object] = []
+    for raw in dependencies:
+        if isinstance(raw, str):
+            try:
+                if canonicalize_name(Requirement(raw).name) == distribution:
+                    continue
+            except Exception:
+                pass
+        retained.append(raw)
+    if version is not None:
+        retained.append(f"{distribution}=={version}")
+    dependencies.clear()
+    dependencies.extend(retained)
+    if version is not None:
+        tool = document.get("tool")
+        uv = tool.get("uv") if isinstance(tool, MutableMapping) else None
+        sources = uv.get("sources") if isinstance(uv, MutableMapping) else None
+        if isinstance(sources, MutableMapping):
+            for key in tuple(sources):
+                if canonicalize_name(str(key)) == distribution:
+                    sources.pop(key, None)
+    after = tomlkit.dumps(document).encode("utf-8")
+    _write_atomic(path, before, after, action=action)
+    return after != before
+
+
+def declare_app_version(
+    app_id: str,
+    version: str,
+    *,
+    project_dir: Path,
+    action: str,
+) -> AppDeclarationResult:
+    ensure_project_state(project_dir, action=action)
+    normalized = str(Version(version))
+    distribution = distribution_name(app_id)
+    business_source = project_dir / "apps" / app_id
+    if business_source.exists() and not business_source.is_symlink():
+        raise _error(
+            "PZ_APP_SOURCE_OWNERSHIP_CONFLICT",
+            f"{app_id} is already owned as business source under apps/.",
+            action=action,
+            detail=str(business_source),
+        )
+    pyproject = project_dir / "pyproject.toml"
+    config = project_dir / "pz.jsonc"
+    pyproject_before = pyproject.read_bytes()
+    config_before = config.read_bytes()
+    changed = _update_dependency(project_dir, distribution, normalized, action=action)
+    pyproject_after = pyproject.read_bytes()
+    try:
+        installed_apps = tuple(add_declared_app(project_dir, app_id, action=action))
+    except Exception:
+        config_after = config.read_bytes()
+        _restore_snapshot(
+            pyproject,
+            before=pyproject_before,
+            expected_current=pyproject_after,
+            action=action,
+        )
+        _restore_snapshot(
+            config,
+            before=config_before,
+            expected_current=config_after,
+            action=action,
+        )
+        raise
+    return AppDeclarationResult(app_id, distribution, normalized, installed_apps, changed)
+
+
+def undeclare_app_version(
+    app_id: str,
+    *,
+    project_dir: Path,
+    action: str,
+) -> AppDeclarationResult:
+    ensure_project_state(project_dir, action=action)
+    if app_id not in load_installed_apps(project_dir, action=action):
+        raise _error("PZ_SCAFFOLD_APP_NOT_DECLARED", f"{app_id} is not declared.", action=action)
+    distribution = distribution_name(app_id)
+    pyproject = project_dir / "pyproject.toml"
+    config = project_dir / "pz.jsonc"
+    pyproject_before = pyproject.read_bytes()
+    config_before = config.read_bytes()
+    changed = _update_dependency(project_dir, distribution, None, action=action)
+    pyproject_after = pyproject.read_bytes()
+    try:
+        installed_apps = tuple(remove_declared_app(project_dir, app_id, action=action))
+    except Exception:
+        config_after = config.read_bytes()
+        _restore_snapshot(
+            pyproject,
+            before=pyproject_before,
+            expected_current=pyproject_after,
+            action=action,
+        )
+        _restore_snapshot(
+            config,
+            before=config_before,
+            expected_current=config_after,
+            action=action,
+        )
+        raise
+    return AppDeclarationResult(app_id, distribution, None, installed_apps, changed)
+
+
+def install_declared_app(
+    app_id: str,
+    version: str,
+    *,
+    project_dir: Path,
+    action: str,
+) -> AppInstallResult:
+    distribution = distribution_name(app_id)
+    normalized = str(Version(version))
+    declared = _read_declared_version(project_dir, distribution)
+    if declared != normalized:
+        raise _error(
+            "PZ_APP_VERSION_STATE_MISMATCH",
+            f"declared version for {distribution} is {declared!r}, expected {normalized}.",
+            action=action,
+        )
+    locked = _read_locked_version(project_dir, distribution)
+    actual = _read_installed_version(project_dir, distribution, action=action)
+    if locked == normalized and actual == normalized:
+        python = resolve_virtualenv_python(project_dir / ".venv", action=action)
+        return AppInstallResult(
+            app_id,
+            distribution,
+            normalized,
+            python,
+            project_dir / "uv.lock",
+        )
+    venv = ensure_project_virtualenv(project_dir, action=action)
+    python = resolve_virtualenv_python(venv.path, action=action)
+    uv_binary = shutil.which("uv")
+    if uv_binary is None:
+        raise _error("PZ_ENV_UV_MISSING", "required dependency backend was not found on PATH.", action=action)
+    target = load_install_target(app_id, project_dir=project_dir, action=action)
+    env = install_env(target=target, project_dir=project_dir, action=action)
+    env["VIRTUAL_ENV"] = str(venv.path)
+    completed = subprocess.run(
+        (uv_binary, "sync", "--active"),
+        cwd=str(project_dir),
+        check=False,
+        capture_output=True,
+        text=True,
+        env=env,
+    )
+    if completed.returncode != 0:
+        raise _error(
+            "PZ_ENV_SYNC_FAILED",
+            f"failed to install {distribution}=={normalized}.",
+            action=action,
+            detail=_redact_credentials(
+                (completed.stderr or completed.stdout or "dependency sync failed").strip()
+            ),
+        )
+    actual = _read_installed_version(project_dir, distribution, action=action)
+    locked = _read_locked_version(project_dir, distribution)
+    if actual != normalized or locked != normalized:
+        raise _error(
+            "PZ_APP_VERSION_STATE_MISMATCH",
+            f"installed and locked versions for {distribution} did not converge to {normalized}.",
+            action=action,
+            detail=f"locked={locked!r}; installed={actual!r}",
+        )
+    return AppInstallResult(app_id, distribution, normalized, python, project_dir / "uv.lock")
+
+
+def reconcile_project_environment(
+    app_id: str,
+    *,
+    project_dir: Path,
+    action: str,
+) -> Path:
+    venv = ensure_project_virtualenv(project_dir, action=action)
+    uv_binary = shutil.which("uv")
+    if uv_binary is None:
+        raise _error("PZ_ENV_UV_MISSING", "required dependency backend was not found on PATH.", action=action)
+    target = load_install_target(app_id, project_dir=project_dir, action=action)
+    env = install_env(target=target, project_dir=project_dir, action=action)
+    env["VIRTUAL_ENV"] = str(venv.path)
+    completed = subprocess.run(
+        (uv_binary, "sync", "--active"),
+        cwd=str(project_dir),
+        check=False,
+        capture_output=True,
+        text=True,
+        env=env,
+    )
+    if completed.returncode != 0:
+        raise _error(
+            "PZ_ENV_SYNC_FAILED",
+            "failed to reconcile the project environment.",
+            action=action,
+            detail=_redact_credentials(
+                (completed.stderr or completed.stdout or "dependency sync failed").strip()
+            ),
+        )
+    return venv.path
+
+
+__all__ = [
+    "AppDeclarationResult",
+    "AppInstallResult",
+    "AppVersionState",
+    "AvailableVersion",
+    "declare_app_version",
+    "distribution_name",
+    "install_declared_app",
+    "query_app_versions",
+    "reconcile_project_environment",
+    "resolve_app_version",
+    "undeclare_app_version",
+]