pz-cli 5.0.0__py3-none-any.whl

pz_core/authoring/dev_git.py

@@ -0,0 +1,1087 @@
+from __future__ import annotations
+
+import os
+import re
+import shutil
+import subprocess
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal, Protocol
+
+from pz_core.runtime.errors import PzError
+
+
+BaseBranch = Literal["develop", "main"]
+
+WORKTREE_DIRTY_CODE = "PZ_DEV_WORKTREE_DIRTY"
+BRANCH_UNSAFE_CODE = "PZ_DEV_BRANCH_UNSAFE"
+BASE_BRANCH_MISSING_CODE = "PZ_DEV_BASE_BRANCH_MISSING"
+GIT_FAILED_CODE = "PZ_DEV_GIT_FAILED"
+PLAN_INVALID_CODE = "PZ_DEV_GIT_PLAN_INVALID"
+ROLLBACK_UNSAFE_CODE = "PZ_DEV_ROLLBACK_UNSAFE"
+SHARED_CHECKOUT_READ_ONLY_CODE = "PZ_DEV_SHARED_CHECKOUT_READ_ONLY"
+
+_OWNER = "pz_core.authoring.dev_git"
+_REPO_KEY = re.compile(r"^[a-z][a-z0-9_]*$")
+_BRANCH = re.compile(r"^[a-z][a-z0-9_]*$")
+_TRANSACTION_ID = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]*$")
+_URL_CREDENTIALS = re.compile(r"(?P<scheme>[A-Za-z][A-Za-z0-9+.-]*://)[^/@\s]+@")
+_URL_SECRET = re.compile(
+    r"(?i)(?P<prefix>[?&](?:access_token|api_key|password|secret|token)=)[^&\s]+"
+)
+_SECRET_ASSIGNMENT = re.compile(
+    r"(?i)\b(?P<key>api[_-]?key|password|passwd|secret|token)\s*[:=]\s*[^\s]+"
+)
+
+
+class GitCommandResult(Protocol):
+    @property
+    def returncode(self) -> int: ...
+
+    @property
+    def stdout(self) -> str | None: ...
+
+    @property
+    def stderr(self) -> str | None: ...
+
+
+class GitBackend(Protocol):
+    def run(
+        self,
+        argv: Sequence[str],
+        *,
+        cwd: Path | None,
+        environment: Mapping[str, str],
+    ) -> GitCommandResult: ...
+
+
+class SubprocessGitBackend:
+    def run(
+        self,
+        argv: Sequence[str],
+        *,
+        cwd: Path | None,
+        environment: Mapping[str, str],
+    ) -> subprocess.CompletedProcess[str]:
+        return subprocess.run(
+            list(argv),
+            cwd=cwd,
+            check=False,
+            capture_output=True,
+            text=True,
+            stdin=subprocess.DEVNULL,
+            env=dict(environment),
+            shell=False,
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class GitInvocation:
+    argv: tuple[str, ...]
+    cwd: Path | None
+
+
+@dataclass(frozen=True, slots=True)
+class GitSnapshot:
+    head: str
+    branch: str | None
+    local_branches: frozenset[str]
+
+
+@dataclass(frozen=True, slots=True)
+class GitCheckoutState:
+    branch: str | None
+    dirty: bool
+
+
+@dataclass(frozen=True, slots=True)
+class GitUpdateResult:
+    checkout: Path
+    branch: str
+    upstream: str | None
+    before_head: str
+    after_head: str
+    updated: bool
+
+
+@dataclass(frozen=True, slots=True)
+class GitDeleteSafety:
+    checkout: Path
+    branch: str
+    upstream: str
+    head: str
+
+
+@dataclass(frozen=True, slots=True)
+class GitBranchPlan:
+    project_dir: Path
+    repo_key: str
+    source: str
+    checkout: Path
+    business_branch: str
+    transaction_id: str
+    base_branch: BaseBranch = "develop"
+
+
+@dataclass(frozen=True, slots=True)
+class PreparedBranch:
+    checkout: Path
+    business_branch: str
+    base_branch: BaseBranch
+    original: GitSnapshot | None
+    created_local_branch: bool
+    new_clone: bool
+    prepared_head: str | None = None
+    project_dir: Path | None = None
+    repo_key: str | None = None
+    transaction_id: str | None = None
+    clone_device: int | None = None
+    clone_inode: int | None = None
+    shared_checkout: bool = False
+
+
+def _error(
+    code: str,
+    message: str,
+    *,
+    action: str,
+    detail: str | None = None,
+) -> PzError:
+    return PzError(
+        code=code,
+        message=message,
+        stage="dev",
+        owner=_OWNER,
+        action=action,
+        detail=detail,
+    )
+
+
+def _sanitize_backend_detail(
+    value: str,
+    *,
+    redactions: Sequence[str] = (),
+) -> str:
+    detail = _URL_CREDENTIALS.sub(r"\g<scheme>***@", value)
+    detail = _URL_SECRET.sub(r"\g<prefix>***", detail)
+    detail = _SECRET_ASSIGNMENT.sub(r"\g<key>=***", detail)
+    for redaction in sorted(
+        (item for item in redactions if item), key=len, reverse=True
+    ):
+        detail = detail.replace(redaction, "<redacted>")
+    detail = " ".join(detail.split())
+    if not detail:
+        return "git backend failed"
+    if len(detail) > 500:
+        return detail[:497] + "..."
+    return detail
+
+
+class DevGitService:
+    def __init__(
+        self,
+        *,
+        backend: GitBackend | None = None,
+        git_binary: str | None = None,
+        environment: Mapping[str, str] | None = None,
+    ) -> None:
+        self._backend = backend or SubprocessGitBackend()
+        self._git_binary = git_binary or shutil.which("git") or "git"
+        process_environment = dict(os.environ)
+        if environment is not None:
+            process_environment.update(environment)
+        process_environment.update(
+            {
+                "GIT_TERMINAL_PROMPT": "0",
+                "GIT_OPTIONAL_LOCKS": "0",
+                "GCM_INTERACTIVE": "Never",
+                "GIT_CONFIG_COUNT": "1",
+                "GIT_CONFIG_KEY_0": "core.hooksPath",
+                "GIT_CONFIG_VALUE_0": os.devnull,
+                "LC_ALL": "C",
+            }
+        )
+        self._environment = process_environment
+        self._invocations: list[GitInvocation] = []
+
+    @property
+    def invocations(self) -> tuple[GitInvocation, ...]:
+        return tuple(self._invocations)
+
+    def inspect(self, checkout: Path) -> GitCheckoutState:
+        action = "inspect_checkout"
+        candidate = checkout.expanduser()
+        if not candidate.is_dir():
+            raise _error(
+                PLAN_INVALID_CODE,
+                "Git checkout must resolve to a directory.",
+                action=action,
+            )
+        resolved = candidate.resolve(strict=True)
+        status = self._output(
+            ("status", "--porcelain=v1", "--untracked-files=all"),
+            cwd=resolved,
+            action=action,
+        )
+        return GitCheckoutState(
+            branch=self._current_branch(resolved, action=action),
+            dirty=bool(status),
+        )
+
+    def inspect_shared(
+        self,
+        checkout: Path,
+        *,
+        expected_source: str,
+    ) -> GitCheckoutState:
+        action = "inspect_shared_checkout"
+        resolved = self._validate_shared_target(
+            checkout,
+            expected_source=expected_source,
+            repo_key="shared",
+            action=action,
+        )
+        status = self._output(
+            ("status", "--porcelain=v1", "--untracked-files=all"),
+            cwd=resolved,
+            action=action,
+        )
+        return GitCheckoutState(
+            branch=self._current_branch(resolved, action=action),
+            dirty=bool(status),
+        )
+
+    def update(self, checkout: Path, *, expected_branch: str) -> GitUpdateResult:
+        action = "update_business_branch"
+        self._reject_shared_mutation(checkout, action=action)
+        resolved = self._managed_checkout(
+            checkout,
+            expected_branch=expected_branch,
+            action=action,
+        )
+        before_head = self._output(
+            ("rev-parse", "--verify", "HEAD"),
+            cwd=resolved,
+            action=action,
+        )
+        upstream = self._upstream(resolved, expected_branch, action=action)
+        remote = "origin" if upstream is None else upstream.split("/", 1)[0]
+        self._output(
+            ("fetch", "--prune", "--no-tags", "--", remote),
+            cwd=resolved,
+            action=action,
+        )
+        if upstream is None:
+            return GitUpdateResult(
+                checkout=resolved,
+                branch=expected_branch,
+                upstream=None,
+                before_head=before_head,
+                after_head=before_head,
+                updated=False,
+            )
+        ancestor = self._execute(
+            ("merge-base", "--is-ancestor", "HEAD", upstream),
+            cwd=resolved,
+            action=action,
+            allowed_returncodes=frozenset({0, 1}),
+        )
+        if ancestor.returncode != 0:
+            raise _error(
+                BRANCH_UNSAFE_CODE,
+                "Business branch cannot be fast-forwarded from its upstream.",
+                action=action,
+                detail=f"upstream={upstream}",
+            )
+        self._output(
+            ("merge", "--ff-only", "--", upstream),
+            cwd=resolved,
+            action=action,
+        )
+        self._require_clean(resolved, action=action)
+        if self._current_branch(resolved, action=action) != expected_branch:
+            raise _error(
+                BRANCH_UNSAFE_CODE,
+                "Business branch changed during update.",
+                action=action,
+            )
+        after_head = self._output(
+            ("rev-parse", "--verify", "HEAD"),
+            cwd=resolved,
+            action=action,
+        )
+        return GitUpdateResult(
+            checkout=resolved,
+            branch=expected_branch,
+            upstream=upstream,
+            before_head=before_head,
+            after_head=after_head,
+            updated=after_head != before_head,
+        )
+
+    def preflight_delete(
+        self,
+        checkout: Path,
+        *,
+        expected_branch: str,
+    ) -> GitDeleteSafety:
+        action = "preflight_delete_checkout"
+        self._reject_shared_mutation(checkout, action=action)
+        resolved = self._managed_checkout(
+            checkout,
+            expected_branch=expected_branch,
+            action=action,
+        )
+        upstream = self._upstream(resolved, expected_branch, action=action)
+        if upstream is None:
+            raise _error(
+                BRANCH_UNSAFE_CODE,
+                "Checkout deletion requires a configured business upstream.",
+                action=action,
+            )
+        ahead = self._output(
+            ("rev-list", "--count", f"{upstream}..HEAD"),
+            cwd=resolved,
+            action=action,
+        )
+        if ahead != "0":
+            raise _error(
+                BRANCH_UNSAFE_CODE,
+                "Checkout deletion would discard commits not present upstream.",
+                action=action,
+                detail=f"upstream={upstream}; ahead={ahead}",
+            )
+        head = self._output(
+            ("rev-parse", "--verify", "HEAD"),
+            cwd=resolved,
+            action=action,
+        )
+        return GitDeleteSafety(
+            checkout=resolved,
+            branch=expected_branch,
+            upstream=upstream,
+            head=head,
+        )
+
+    def prepare(self, plan: GitBranchPlan) -> PreparedBranch:
+        self._validate_plan(plan)
+        if plan.checkout.expanduser().is_symlink():
+            self._validate_shared_checkout(
+                plan,
+                action="prepare_business_branch",
+            )
+            return PreparedBranch(
+                checkout=plan.checkout.expanduser(),
+                business_branch=plan.business_branch,
+                base_branch=plan.base_branch,
+                original=None,
+                created_local_branch=False,
+                new_clone=False,
+                project_dir=plan.project_dir.expanduser().resolve(strict=False),
+                repo_key=plan.repo_key,
+                transaction_id=plan.transaction_id,
+                shared_checkout=True,
+            )
+        checkout = plan.checkout.expanduser().resolve(strict=False)
+        if checkout.exists() or checkout.is_symlink():
+            if checkout.is_symlink() or not checkout.is_dir():
+                raise _error(
+                    PLAN_INVALID_CODE,
+                    "existing Git checkout must be a real directory.",
+                    action="prepare_business_branch",
+                )
+            return self._prepare_existing(plan, checkout)
+        return self._prepare_new_clone(plan)
+
+    def preflight_existing(self, plan: GitBranchPlan) -> None:
+        """Validate existing checkout state without fetching or mutating refs."""
+        self._validate_plan(plan)
+        if plan.checkout.expanduser().is_symlink():
+            self._validate_shared_checkout(
+                plan,
+                action="preflight_business_branch",
+            )
+            return
+        checkout = plan.checkout.expanduser().resolve(strict=False)
+        if not checkout.exists() and not checkout.is_symlink():
+            return
+        if checkout.is_symlink() or not checkout.is_dir():
+            raise _error(
+                PLAN_INVALID_CODE,
+                "existing Git checkout must be a real directory.",
+                action="preflight_business_branch",
+            )
+        self._inspect_existing_checkout(
+            plan, checkout, action="preflight_business_branch"
+        )
+
+    def rollback(self, prepared: PreparedBranch) -> None:
+        if prepared.shared_checkout:
+            return
+        if prepared.new_clone:
+            self._remove_prepared_clone(prepared)
+            return
+        self._rollback_existing(prepared)
+
+    def _execute(
+        self,
+        arguments: Sequence[str],
+        *,
+        cwd: Path | None,
+        action: str,
+        allowed_returncodes: frozenset[int] = frozenset({0}),
+        redactions: Sequence[str] = (),
+    ) -> GitCommandResult:
+        argv = (self._git_binary, *arguments)
+        self._invocations.append(GitInvocation(argv=argv, cwd=cwd))
+        try:
+            result = self._backend.run(
+                argv,
+                cwd=cwd,
+                environment=self._environment,
+            )
+        except OSError as exc:
+            raise _error(
+                GIT_FAILED_CODE,
+                "Git backend could not be executed.",
+                action=action,
+                detail=exc.__class__.__name__,
+            ) from exc
+        if result.returncode not in allowed_returncodes:
+            raw_detail = result.stderr or result.stdout or "git backend failed"
+            automatic_redactions = (*redactions, str(cwd) if cwd is not None else "")
+            raise _error(
+                GIT_FAILED_CODE,
+                "Git command failed.",
+                action=action,
+                detail=_sanitize_backend_detail(
+                    raw_detail,
+                    redactions=automatic_redactions,
+                ),
+            )
+        return result
+
+    def _output(
+        self,
+        arguments: Sequence[str],
+        *,
+        cwd: Path | None,
+        action: str,
+        allowed_returncodes: frozenset[int] = frozenset({0}),
+        redactions: Sequence[str] = (),
+    ) -> str:
+        result = self._execute(
+            arguments,
+            cwd=cwd,
+            action=action,
+            allowed_returncodes=allowed_returncodes,
+            redactions=redactions,
+        )
+        return (result.stdout or "").strip()
+
+    def _validate_plan(self, plan: GitBranchPlan) -> None:
+        action = "prepare_business_branch"
+        if not _REPO_KEY.fullmatch(plan.repo_key):
+            raise _error(
+                PLAN_INVALID_CODE,
+                "Git repo key is invalid.",
+                action=action,
+            )
+        if not _BRANCH.fullmatch(plan.business_branch):
+            raise _error(
+                PLAN_INVALID_CODE,
+                "Business branch is invalid.",
+                action=action,
+            )
+        if plan.base_branch not in {"develop", "main"}:
+            raise _error(
+                PLAN_INVALID_CODE,
+                "Base branch must be develop or main.",
+                action=action,
+            )
+        if not isinstance(plan.source, str) or not plan.source.strip():
+            raise _error(
+                PLAN_INVALID_CODE,
+                "Git source is required.",
+                action=action,
+            )
+        if not _TRANSACTION_ID.fullmatch(plan.transaction_id):
+            raise _error(
+                PLAN_INVALID_CODE,
+                "Transaction id is invalid.",
+                action=action,
+            )
+        project_dir = plan.project_dir.expanduser().resolve(strict=False)
+        apps_root = project_dir / "apps"
+        sources_root = apps_root / ".sources"
+        if apps_root.is_symlink() or sources_root.is_symlink():
+            raise _error(
+                PLAN_INVALID_CODE,
+                "Git checkout parents cannot be symbolic links.",
+                action=action,
+            )
+        expected_checkout = Path(os.path.abspath(sources_root / plan.repo_key))
+        checkout = Path(os.path.abspath(plan.checkout.expanduser()))
+        if checkout != expected_checkout:
+            raise _error(
+                PLAN_INVALID_CODE,
+                "Final checkout must be the repo-key child of apps/.sources.",
+                action=action,
+            )
+
+    def _validate_shared_checkout(self, plan: GitBranchPlan, *, action: str) -> Path:
+        return self._validate_shared_target(
+            plan.checkout,
+            expected_source=plan.source,
+            repo_key=plan.repo_key,
+            action=action,
+        )
+
+    def _validate_shared_target(
+        self,
+        checkout: Path,
+        *,
+        expected_source: str,
+        repo_key: str,
+        action: str,
+    ) -> Path:
+        candidate = checkout.expanduser()
+        if not candidate.is_symlink():
+            raise _error(
+                PLAN_INVALID_CODE,
+                "Shared checkout entry must be a symbolic link.",
+                action=action,
+            )
+        try:
+            resolved = candidate.resolve(strict=True)
+        except OSError as exc:
+            raise _error(
+                PLAN_INVALID_CODE,
+                "Shared checkout target is unavailable.",
+                action=action,
+                detail=exc.__class__.__name__,
+            ) from exc
+        if not resolved.is_dir():
+            raise _error(
+                PLAN_INVALID_CODE,
+                "Shared checkout target must be a directory.",
+                action=action,
+            )
+        inside_worktree = self._output(
+            ("rev-parse", "--is-inside-work-tree"),
+            cwd=resolved,
+            action=action,
+        )
+        if inside_worktree != "true":
+            raise _error(
+                PLAN_INVALID_CODE,
+                "Shared checkout target must be a Git worktree.",
+                action=action,
+            )
+        remote = self._output(
+            ("remote", "get-url", "origin"),
+            cwd=resolved,
+            action=action,
+        )
+        if self._normalized_git_source(remote) != self._normalized_git_source(
+            expected_source
+        ):
+            raise _error(
+                PLAN_INVALID_CODE,
+                "Shared checkout origin does not match the manifest source.",
+                action=action,
+                detail=f"repo={repo_key}",
+            )
+        return resolved
+
+    @staticmethod
+    def _normalized_git_source(value: str) -> str:
+        source = str(value or "").strip().rstrip("/")
+        if source.startswith(("/", "./", "../", "~")):
+            return str(Path(source).expanduser().resolve(strict=False)).removesuffix(
+                ".git"
+            )
+        return source.removesuffix(".git")
+
+    @staticmethod
+    def _reject_shared_mutation(checkout: Path, *, action: str) -> None:
+        if checkout.expanduser().is_symlink():
+            raise _error(
+                SHARED_CHECKOUT_READ_ONLY_CODE,
+                "Shared checkout is externally owned and read-only to PZ authoring commands.",
+                action=action,
+            )
+
+    def _require_clean(self, checkout: Path, *, action: str) -> None:
+        status = self._output(
+            ("status", "--porcelain=v1", "--untracked-files=all"),
+            cwd=checkout,
+            action=action,
+        )
+        if status:
+            raise _error(
+                WORKTREE_DIRTY_CODE,
+                "Git checkout has tracked, staged, or untracked changes.",
+                action=action,
+            )
+
+    def _managed_checkout(
+        self,
+        checkout: Path,
+        *,
+        expected_branch: str,
+        action: str,
+    ) -> Path:
+        self._reject_shared_mutation(checkout, action=action)
+        if not _BRANCH.fullmatch(expected_branch):
+            raise _error(
+                PLAN_INVALID_CODE,
+                "Expected business branch is invalid.",
+                action=action,
+            )
+        candidate = checkout.expanduser()
+        if candidate.is_symlink() or not candidate.is_dir():
+            raise _error(
+                PLAN_INVALID_CODE,
+                "Git checkout must be a real directory.",
+                action=action,
+            )
+        resolved = candidate.resolve(strict=True)
+        self._require_clean(resolved, action=action)
+        current = self._current_branch(resolved, action=action)
+        if current != expected_branch:
+            raise _error(
+                BRANCH_UNSAFE_CODE,
+                "Git checkout is not on the manifest business branch.",
+                action=action,
+                detail=f"expected={expected_branch}; actual={current or 'detached HEAD'}",
+            )
+        return resolved
+
+    def _upstream(
+        self,
+        checkout: Path,
+        branch: str,
+        *,
+        action: str,
+    ) -> str | None:
+        upstream = self._output(
+            (
+                "for-each-ref",
+                "--format=%(upstream:short)",
+                f"refs/heads/{branch}",
+            ),
+            cwd=checkout,
+            action=action,
+        )
+        if not upstream:
+            return None
+        if (
+            upstream.startswith("-")
+            or "/" not in upstream
+            or any(character.isspace() for character in upstream)
+        ):
+            raise _error(
+                BRANCH_UNSAFE_CODE,
+                "Business upstream is not a safe remote branch.",
+                action=action,
+            )
+        return upstream
+
+    def _current_branch(self, checkout: Path, *, action: str) -> str | None:
+        branch = self._output(
+            ("symbolic-ref", "--quiet", "--short", "HEAD"),
+            cwd=checkout,
+            action=action,
+            allowed_returncodes=frozenset({0, 1}),
+        )
+        return branch or None
+
+    def _snapshot(self, checkout: Path, *, action: str) -> GitSnapshot:
+        head = self._output(
+            ("rev-parse", "--verify", "HEAD"),
+            cwd=checkout,
+            action=action,
+        )
+        branch = self._current_branch(checkout, action=action)
+        branches = self._output(
+            (
+                "for-each-ref",
+                "--format=%(refname:short)",
+                "refs/heads",
+            ),
+            cwd=checkout,
+            action=action,
+        )
+        return GitSnapshot(
+            head=head,
+            branch=branch,
+            local_branches=frozenset(value for value in branches.splitlines() if value),
+        )
+
+    def _ref_exists(self, checkout: Path, ref: str, *, action: str) -> bool:
+        result = self._execute(
+            ("show-ref", "--verify", "--quiet", ref),
+            cwd=checkout,
+            action=action,
+            allowed_returncodes=frozenset({0, 1}),
+        )
+        return result.returncode == 0
+
+    def _prepare_existing(
+        self,
+        plan: GitBranchPlan,
+        checkout: Path,
+    ) -> PreparedBranch:
+        action = "prepare_business_branch"
+        original = self._inspect_existing_checkout(plan, checkout, action=action)
+        self._output(
+            ("fetch", "--all", "--prune"),
+            cwd=checkout,
+            action=action,
+        )
+        created_local_branch = self._checkout_business_branch(
+            checkout,
+            plan,
+            current_branch=original.branch,
+            action=action,
+        )
+        prepared_head = self._output(
+            ("rev-parse", "--verify", "HEAD"),
+            cwd=checkout,
+            action=action,
+        )
+        return PreparedBranch(
+            checkout=checkout,
+            business_branch=plan.business_branch,
+            base_branch=plan.base_branch,
+            original=original,
+            created_local_branch=created_local_branch,
+            new_clone=False,
+            prepared_head=prepared_head,
+            project_dir=plan.project_dir.expanduser().resolve(strict=False),
+            repo_key=plan.repo_key,
+            transaction_id=plan.transaction_id,
+        )
+
+    def _inspect_existing_checkout(
+        self,
+        plan: GitBranchPlan,
+        checkout: Path,
+        *,
+        action: str,
+    ) -> GitSnapshot:
+        self._require_clean(checkout, action=action)
+        original = self._snapshot(checkout, action=action)
+        if original.branch not in {
+            plan.business_branch,
+            "develop",
+            "main",
+        }:
+            current = original.branch or "detached HEAD"
+            raise _error(
+                BRANCH_UNSAFE_CODE,
+                "Git checkout is not on an allowed branch.",
+                action=action,
+                detail=f"current={current}",
+            )
+        return original
+
+    def _prepare_new_clone(self, plan: GitBranchPlan) -> PreparedBranch:
+        action = "prepare_business_branch"
+        project_dir = plan.project_dir.expanduser().resolve(strict=False)
+        transaction_root = (
+            project_dir / "apps" / ".sources" / ".transactions" / plan.transaction_id
+        )
+        transactions_root = transaction_root.parent
+        if transactions_root.is_symlink() or transaction_root.is_symlink():
+            raise _error(
+                PLAN_INVALID_CODE,
+                "Git transaction parents cannot be symbolic links.",
+                action=action,
+            )
+        staged_checkout = transaction_root / plan.repo_key
+        if staged_checkout.exists() or staged_checkout.is_symlink():
+            raise _error(
+                PLAN_INVALID_CODE,
+                "Staged Git checkout already exists.",
+                action=action,
+            )
+        transaction_root.mkdir(parents=True, exist_ok=True)
+        owns_staged_checkout = True
+        clone_stat: os.stat_result | None = None
+        try:
+            self._output(
+                (
+                    "clone",
+                    "--origin",
+                    "origin",
+                    "--no-hardlinks",
+                    "--",
+                    plan.source,
+                    str(staged_checkout),
+                ),
+                cwd=None,
+                action=action,
+                redactions=(plan.source, str(staged_checkout)),
+            )
+            clone_stat = staged_checkout.stat(follow_symlinks=False)
+            self._require_clean(staged_checkout, action=action)
+            current_branch = self._current_branch(staged_checkout, action=action)
+            created_local_branch = self._checkout_business_branch(
+                staged_checkout,
+                plan,
+                current_branch=current_branch,
+                action=action,
+            )
+            prepared_head = self._output(
+                ("rev-parse", "--verify", "HEAD"),
+                cwd=staged_checkout,
+                action=action,
+            )
+            return PreparedBranch(
+                checkout=staged_checkout,
+                business_branch=plan.business_branch,
+                base_branch=plan.base_branch,
+                original=None,
+                created_local_branch=created_local_branch,
+                new_clone=True,
+                prepared_head=prepared_head,
+                project_dir=project_dir,
+                repo_key=plan.repo_key,
+                transaction_id=plan.transaction_id,
+                clone_device=clone_stat.st_dev,
+                clone_inode=clone_stat.st_ino,
+            )
+        except Exception:
+            if owns_staged_checkout and (
+                staged_checkout.exists() or staged_checkout.is_symlink()
+            ):
+                cleanup_stat = clone_stat or staged_checkout.stat(follow_symlinks=False)
+                failed_clone = PreparedBranch(
+                    checkout=staged_checkout,
+                    business_branch=plan.business_branch,
+                    base_branch=plan.base_branch,
+                    original=None,
+                    created_local_branch=False,
+                    new_clone=True,
+                    project_dir=project_dir,
+                    repo_key=plan.repo_key,
+                    transaction_id=plan.transaction_id,
+                    clone_device=cleanup_stat.st_dev,
+                    clone_inode=cleanup_stat.st_ino,
+                )
+                self._remove_prepared_clone(failed_clone)
+            raise
+
+    def _checkout_business_branch(
+        self,
+        checkout: Path,
+        plan: GitBranchPlan,
+        *,
+        current_branch: str | None,
+        action: str,
+    ) -> bool:
+        local_ref = f"refs/heads/{plan.business_branch}"
+        remote_ref = f"refs/remotes/origin/{plan.business_branch}"
+        if self._ref_exists(checkout, local_ref, action=action):
+            if current_branch != plan.business_branch:
+                self._output(
+                    ("switch", "--no-guess", "--", plan.business_branch),
+                    cwd=checkout,
+                    action=action,
+                )
+            return False
+        if self._ref_exists(checkout, remote_ref, action=action):
+            self._output(
+                (
+                    "switch",
+                    "--no-guess",
+                    "--track",
+                    "-c",
+                    plan.business_branch,
+                    f"origin/{plan.business_branch}",
+                ),
+                cwd=checkout,
+                action=action,
+            )
+            return True
+        base_ref = f"refs/remotes/origin/{plan.base_branch}"
+        if not self._ref_exists(checkout, base_ref, action=action):
+            raise _error(
+                BASE_BRANCH_MISSING_CODE,
+                "Selected remote base branch does not exist.",
+                action=action,
+                detail=f"base=origin/{plan.base_branch}",
+            )
+        self._output(
+            (
+                "switch",
+                "--no-guess",
+                "--no-track",
+                "-c",
+                plan.business_branch,
+                f"origin/{plan.base_branch}",
+            ),
+            cwd=checkout,
+            action=action,
+        )
+        return True
+
+    def _rollback_existing(self, prepared: PreparedBranch) -> None:
+        action = "rollback_business_branch"
+        if prepared.original is None:
+            raise _error(
+                ROLLBACK_UNSAFE_CODE,
+                "Existing checkout rollback is missing its original snapshot.",
+                action=action,
+            )
+        raw_checkout = prepared.checkout.expanduser()
+        if raw_checkout.is_symlink():
+            raise _error(
+                ROLLBACK_UNSAFE_CODE,
+                "Existing checkout rollback path is unsafe.",
+                action=action,
+            )
+        checkout = raw_checkout.resolve(strict=False)
+        if not checkout.is_dir():
+            raise _error(
+                ROLLBACK_UNSAFE_CODE,
+                "Existing checkout rollback path is unsafe.",
+                action=action,
+            )
+        self._require_clean(checkout, action=action)
+        original = prepared.original
+        if original.branch is None:
+            self._output(
+                ("switch", "--detach", original.head),
+                cwd=checkout,
+                action=action,
+            )
+        else:
+            self._output(
+                ("switch", "--no-guess", "--", original.branch),
+                cwd=checkout,
+                action=action,
+            )
+        restored_head = self._output(
+            ("rev-parse", "--verify", "HEAD"),
+            cwd=checkout,
+            action=action,
+        )
+        if restored_head != original.head:
+            raise _error(
+                ROLLBACK_UNSAFE_CODE,
+                "Original Git ref no longer points to the recorded commit.",
+                action=action,
+            )
+        if (
+            not prepared.created_local_branch
+            or prepared.business_branch in original.local_branches
+            or prepared.prepared_head is None
+        ):
+            return
+        business_ref = f"refs/heads/{prepared.business_branch}"
+        if not self._ref_exists(checkout, business_ref, action=action):
+            return
+        current_business_head = self._output(
+            ("rev-parse", "--verify", business_ref),
+            cwd=checkout,
+            action=action,
+        )
+        if current_business_head != prepared.prepared_head:
+            return
+        self._output(
+            (
+                "update-ref",
+                "-d",
+                business_ref,
+                prepared.prepared_head,
+            ),
+            cwd=checkout,
+            action=action,
+        )
+
+    def _remove_prepared_clone(self, prepared: PreparedBranch) -> None:
+        action = "rollback_business_branch"
+        if (
+            prepared.project_dir is None
+            or prepared.repo_key is None
+            or prepared.transaction_id is None
+            or not _REPO_KEY.fullmatch(prepared.repo_key)
+            or not _TRANSACTION_ID.fullmatch(prepared.transaction_id)
+        ):
+            raise _error(
+                ROLLBACK_UNSAFE_CODE,
+                "Staged clone rollback proof is incomplete.",
+                action=action,
+            )
+        project_dir = prepared.project_dir.expanduser().resolve(strict=False)
+        components = (
+            project_dir / "apps",
+            project_dir / "apps" / ".sources",
+            project_dir / "apps" / ".sources" / ".transactions",
+            project_dir
+            / "apps"
+            / ".sources"
+            / ".transactions"
+            / prepared.transaction_id,
+        )
+        if any(component.is_symlink() for component in components):
+            raise _error(
+                ROLLBACK_UNSAFE_CODE,
+                "Staged clone rollback path contains a symbolic link.",
+                action=action,
+            )
+        transaction_root = components[-1]
+        expected_checkout = transaction_root / prepared.repo_key
+        checkout = prepared.checkout.expanduser()
+        if not checkout.is_absolute():
+            checkout = Path.cwd() / checkout
+        if checkout != expected_checkout or checkout.parent != transaction_root:
+            raise _error(
+                ROLLBACK_UNSAFE_CODE,
+                "Staged clone is not the proved transaction child.",
+                action=action,
+            )
+        if not checkout.exists() and not checkout.is_symlink():
+            return
+        if checkout.is_symlink() or not checkout.is_dir():
+            raise _error(
+                ROLLBACK_UNSAFE_CODE,
+                "Staged clone rollback target is not a real directory.",
+                action=action,
+            )
+        if prepared.clone_device is None or prepared.clone_inode is None:
+            raise _error(
+                ROLLBACK_UNSAFE_CODE,
+                "Staged clone rollback is missing directory identity proof.",
+                action=action,
+            )
+        clone_stat = checkout.stat(follow_symlinks=False)
+        if (
+            clone_stat.st_dev != prepared.clone_device
+            or clone_stat.st_ino != prepared.clone_inode
+        ):
+            raise _error(
+                ROLLBACK_UNSAFE_CODE,
+                "Staged clone directory identity changed after preparation.",
+                action=action,
+            )
+        shutil.rmtree(checkout)
+
+
+__all__ = [
+    "BaseBranch",
+    "DevGitService",
+    "GitBackend",
+    "GitBranchPlan",
+    "GitCheckoutState",
+    "GitDeleteSafety",
+    "GitInvocation",
+    "GitSnapshot",
+    "GitUpdateResult",
+    "PreparedBranch",
+    "SubprocessGitBackend",
+]