git-paoding 0.1.0__py3-none-any.whl

git_paoding/gitio/plumbing.py

@@ -0,0 +1,170 @@
+"""Typed helpers for Git object and reference plumbing."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal, Sequence, cast
+
+from git_paoding.gitio.runner import run_git
+
+ObjectType = Literal["blob", "tree", "commit", "tag"]
+TreeObjectType = Literal["blob", "tree", "commit"]
+
+
+@dataclass(frozen=True, slots=True)
+class TreeEntry:
+    """One direct child returned by ``git ls-tree``."""
+
+    mode: str
+    object_type: TreeObjectType
+    oid: str
+    path: str
+
+
+@dataclass(frozen=True, slots=True)
+class GitIdentity:
+    """Identity and optional timestamp used by ``git commit-tree``."""
+
+    name: str
+    email: str
+    date: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class RemoteRef:
+    """One ref advertised by ``git ls-remote``."""
+
+    oid: str
+    ref: str
+
+
+def rev_parse(repo: Path, revision: str) -> str:
+    """Resolve and verify a revision or object expression."""
+
+    result = run_git(("rev-parse", "--verify", "--end-of-options", revision), cwd=repo)
+    return result.stdout_text().strip()
+
+
+def cat_file(repo: Path, oid: str, *, object_type: ObjectType = "blob") -> bytes:
+    """Read an object while requiring its expected Git type."""
+
+    return run_git(("cat-file", object_type, oid), cwd=repo).stdout
+
+
+def hash_object(repo: Path, data: bytes, *, object_type: ObjectType = "blob") -> str:
+    """Write an object to the repository object database and return its OID."""
+
+    result = run_git(
+        ("hash-object", "-w", "--stdin", "-t", object_type),
+        cwd=repo,
+        input_data=data,
+    )
+    return result.stdout_text().strip()
+
+
+def ls_tree(repo: Path, treeish: str) -> tuple[TreeEntry, ...]:
+    """List the direct entries of a tree without consulting the index."""
+
+    output = run_git(("ls-tree", "-z", treeish), cwd=repo).stdout
+    entries: list[TreeEntry] = []
+    for raw_entry in output.split(b"\0"):
+        if not raw_entry:
+            continue
+        metadata, raw_path = raw_entry.split(b"\t", maxsplit=1)
+        raw_mode, raw_type, raw_oid = metadata.split(b" ", maxsplit=2)
+        object_type = raw_type.decode("ascii")
+        if object_type not in {"blob", "tree", "commit"}:
+            raise ValueError(f"Unexpected ls-tree object type: {object_type}")
+        entries.append(
+            TreeEntry(
+                mode=raw_mode.decode("ascii"),
+                object_type=cast(TreeObjectType, object_type),
+                oid=raw_oid.decode("ascii"),
+                path=raw_path.decode("utf-8", errors="surrogateescape"),
+            )
+        )
+    return tuple(entries)
+
+
+def mktree(repo: Path, entries: Sequence[TreeEntry]) -> str:
+    """Write a tree from direct entries and return its OID."""
+
+    records: list[bytes] = []
+    for entry in entries:
+        path = entry.path.encode("utf-8", errors="surrogateescape")
+        metadata = f"{entry.mode} {entry.object_type} {entry.oid}\t".encode()
+        records.append(metadata + path + b"\0")
+    result = run_git(("mktree", "-z"), cwd=repo, input_data=b"".join(records))
+    return result.stdout_text().strip()
+
+
+def commit_tree(
+    repo: Path,
+    tree_oid: str,
+    message: str,
+    *,
+    parents: Sequence[str] = (),
+    author: GitIdentity | None = None,
+    committer: GitIdentity | None = None,
+) -> str:
+    """Create a commit object without changing HEAD, a worktree, or the index."""
+
+    args = ["commit-tree", tree_oid]
+    for parent in parents:
+        args.extend(("-p", parent))
+
+    command_env: dict[str, str] = {}
+    if author is not None:
+        command_env["GIT_AUTHOR_NAME"] = author.name
+        command_env["GIT_AUTHOR_EMAIL"] = author.email
+        if author.date is not None:
+            command_env["GIT_AUTHOR_DATE"] = author.date
+    if committer is not None:
+        command_env["GIT_COMMITTER_NAME"] = committer.name
+        command_env["GIT_COMMITTER_EMAIL"] = committer.email
+        if committer.date is not None:
+            command_env["GIT_COMMITTER_DATE"] = committer.date
+
+    result = run_git(
+        args,
+        cwd=repo,
+        input_data=message.encode("utf-8", errors="surrogateescape"),
+        env=command_env,
+    )
+    return result.stdout_text().strip()
+
+
+def commit_committer_date(repo: Path, commit_oid: str) -> str:
+    """Return a commit's strict ISO committer date for deterministic synthesis."""
+
+    result = run_git(("show", "--no-patch", "--format=%cI", commit_oid), cwd=repo)
+    date = result.stdout_text().strip()
+    if not date:
+        raise ValueError(f"Commit {commit_oid!r} did not expose a committer date")
+    return date
+
+
+def update_ref(repo: Path, ref: str, new_oid: str | None, *, old_oid: str | None = None) -> None:
+    """Create, compare-and-swap, or delete a ref."""
+
+    if new_oid is None:
+        args = ["update-ref", "-d", ref]
+        if old_oid is not None:
+            args.append(old_oid)
+    else:
+        args = ["update-ref", ref, new_oid]
+        if old_oid is not None:
+            args.append(old_oid)
+    run_git(args, cwd=repo)
+
+
+def ls_remote(repo: Path, remote: str, *patterns: str) -> tuple[RemoteRef, ...]:
+    """Read refs advertised by a remote without fetching or updating local refs."""
+
+    output = run_git(("ls-remote", remote, *patterns), cwd=repo).stdout
+    refs: list[RemoteRef] = []
+    for line in output.splitlines():
+        raw_oid, raw_ref = line.split(b"\t", maxsplit=1)
+        refs.append(RemoteRef(oid=raw_oid.decode("ascii"), ref=raw_ref.decode("utf-8")))
+    return tuple(refs)

git_paoding/gitio/refs.py

@@ -0,0 +1,145 @@
+"""Generated projection-ref naming and idempotent remote synchronization."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from git_paoding.gitio.plumbing import ls_remote, update_ref
+from git_paoding.gitio.runner import run_git
+
+
+@dataclass(frozen=True, slots=True)
+class GeneratedRefs:
+    """The two branch refs backing one slice pull request."""
+
+    base: str
+    head: str
+
+
+@dataclass(frozen=True, slots=True)
+class RefSyncResult:
+    """Which generated refs required a remote repair or refresh."""
+
+    refs: GeneratedRefs
+    base_pushed: bool
+    head_pushed: bool
+
+    @property
+    def is_no_op(self) -> bool:
+        """Return whether the remote already advertised both desired OIDs."""
+
+        return not self.base_pushed and not self.head_pushed
+
+
+@dataclass(frozen=True, slots=True)
+class RefDeleteResult:
+    """Which generated refs existed remotely and were deleted."""
+
+    refs: GeneratedRefs
+    base_deleted: bool
+    head_deleted: bool
+
+    @property
+    def is_no_op(self) -> bool:
+        """Return whether the remote already lacked both generated refs."""
+
+        return not self.base_deleted and not self.head_deleted
+
+
+def generated_refs(branch_key: str, slice_id: str) -> GeneratedRefs:
+    """Return generated base and head ref names for one branch and review slice."""
+
+    if not branch_key or "/" in branch_key:
+        raise ValueError("branch_key must be a non-empty single ref component")
+    if not slice_id or "/" in slice_id:
+        raise ValueError("slice_id must be a non-empty single ref component")
+    prefix = f"refs/heads/paoding/{branch_key}/{slice_id}"
+    return GeneratedRefs(base=f"{prefix}/base", head=f"{prefix}/head")
+
+
+def update_local_projection_refs(
+    repo: Path,
+    refs: GeneratedRefs,
+    *,
+    base_oid: str,
+    head_oid: str,
+) -> None:
+    """Point both local generated refs at deterministic projection commits."""
+
+    update_ref(repo, refs.base, base_oid)
+    update_ref(repo, refs.head, head_oid)
+
+
+def _force_push(repo: Path, remote: str, ref: str) -> None:
+    run_git(("push", "--force", remote, f"{ref}:{ref}"), cwd=repo)
+
+
+def _delete_remote_ref(repo: Path, remote: str, ref: str) -> None:
+    run_git(("push", remote, "--delete", ref), cwd=repo)
+
+
+def sync_projection_refs(
+    repo: Path,
+    remote: str,
+    refs: GeneratedRefs,
+    *,
+    base_oid: str,
+    head_oid: str,
+) -> RefSyncResult:
+    """Repair remote projection refs using one authoritative ``ls-remote``.
+
+    Local refs are updated from the deterministic desired OIDs, but each remote
+    push occurs only when the batched advertisement differs.  Base is always
+    pushed before head so an interrupted publication is safely repairable by a
+    later call without any session-side OID cache.
+    """
+
+    update_local_projection_refs(
+        repo,
+        refs,
+        base_oid=base_oid,
+        head_oid=head_oid,
+    )
+    advertised = {item.ref: item.oid for item in ls_remote(repo, remote, refs.base, refs.head)}
+    base_pushed = advertised.get(refs.base) != base_oid
+    head_pushed = advertised.get(refs.head) != head_oid
+
+    if base_pushed:
+        _force_push(repo, remote, refs.base)
+    if head_pushed:
+        _force_push(repo, remote, refs.head)
+
+    return RefSyncResult(
+        refs=refs,
+        base_pushed=base_pushed,
+        head_pushed=head_pushed,
+    )
+
+
+def delete_projection_refs(repo: Path, remote: str, refs: GeneratedRefs) -> RefDeleteResult:
+    """Delete one archived slice's generated refs locally and remotely.
+
+    Remote existence is read in one batch so retries skip refs that an earlier
+    attempt already removed. The head disappears before the base, reversing
+    publication order and avoiding an intermediate advertised head whose
+    generated base has already gone away. Local derived refs are removed only
+    after remote cleanup succeeds.
+    """
+
+    advertised = {item.ref: item.oid for item in ls_remote(repo, remote, refs.base, refs.head)}
+    base_deleted = refs.base in advertised
+    head_deleted = refs.head in advertised
+
+    if head_deleted:
+        _delete_remote_ref(repo, remote, refs.head)
+    if base_deleted:
+        _delete_remote_ref(repo, remote, refs.base)
+
+    update_ref(repo, refs.head, None)
+    update_ref(repo, refs.base, None)
+    return RefDeleteResult(
+        refs=refs,
+        base_deleted=base_deleted,
+        head_deleted=head_deleted,
+    )

git_paoding/gitio/runner.py

@@ -0,0 +1,133 @@
+"""The single process boundary for invoking Git."""
+
+from __future__ import annotations
+
+import os
+import subprocess
+from dataclasses import dataclass
+from enum import Enum
+from pathlib import Path
+from typing import Mapping, Sequence
+
+
+class GitFailureKind(str, Enum):
+    """Stable categories for failures reported by Git."""
+
+    NOT_REPOSITORY = "not-repository"
+    UNKNOWN_REVISION = "unknown-revision"
+    MISSING_OBJECT = "missing-object"
+    INVALID_INPUT = "invalid-input"
+    REMOTE = "remote"
+    OTHER = "other"
+
+
+@dataclass(frozen=True, slots=True)
+class GitResult:
+    """Successful Git command output."""
+
+    stdout: bytes
+    stderr: str
+
+    def stdout_text(self) -> str:
+        """Decode standard output without losing unusual path bytes."""
+
+        return self.stdout.decode("utf-8", errors="surrogateescape")
+
+
+class GitError(RuntimeError):
+    """Base class for failures at the Git process boundary."""
+
+
+class GitUnavailableError(GitError):
+    """Raised when the Git executable cannot be found."""
+
+
+class GitCommandError(GitError):
+    """A non-zero Git command result with a mapped failure category."""
+
+    def __init__(
+        self,
+        *,
+        args: tuple[str, ...],
+        cwd: Path,
+        returncode: int,
+        stderr: str,
+        kind: GitFailureKind,
+    ) -> None:
+        self.args_list = args
+        self.cwd = cwd
+        self.returncode = returncode
+        self.stderr = stderr
+        self.kind = kind
+        detail = stderr.strip() or "Git exited without an error message"
+        super().__init__(f"git {' '.join(args)} failed in {cwd}: {detail}")
+
+
+def _classify_failure(stderr: str) -> GitFailureKind:
+    normalized = stderr.casefold()
+    if "not a git repository" in normalized:
+        return GitFailureKind.NOT_REPOSITORY
+    if any(
+        marker in normalized
+        for marker in (
+            "unknown revision",
+            "ambiguous argument",
+            "needed a single revision",
+            "not a valid object name",
+        )
+    ):
+        return GitFailureKind.UNKNOWN_REVISION
+    if any(marker in normalized for marker in ("missing blob", "missing tree", "bad object")):
+        return GitFailureKind.MISSING_OBJECT
+    if any(marker in normalized for marker in ("malformed", "invalid path", "invalid object")):
+        return GitFailureKind.INVALID_INPUT
+    if any(
+        marker in normalized
+        for marker in (
+            "could not read from remote",
+            "could not resolve host",
+            "authentication failed",
+        )
+    ):
+        return GitFailureKind.REMOTE
+    return GitFailureKind.OTHER
+
+
+def run_git(
+    args: Sequence[str],
+    *,
+    cwd: Path,
+    input_data: bytes | None = None,
+    env: Mapping[str, str] | None = None,
+) -> GitResult:
+    """Run Git in an explicit repository directory and return byte-preserving output."""
+
+    command_args = tuple(args)
+    process_env = os.environ.copy()
+    process_env["LC_ALL"] = "C"
+    if env is not None:
+        process_env.update(env)
+
+    try:
+        completed = subprocess.run(
+            ("git", *command_args),
+            cwd=cwd,
+            env=process_env,
+            input=input_data,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            check=False,
+        )
+    except FileNotFoundError as error:
+        raise GitUnavailableError("Git executable was not found on PATH") from error
+
+    stderr = completed.stderr.decode("utf-8", errors="surrogateescape")
+    if completed.returncode != 0:
+        raise GitCommandError(
+            args=command_args,
+            cwd=cwd,
+            returncode=completed.returncode,
+            stderr=stderr,
+            kind=_classify_failure(stderr),
+        )
+    return GitResult(stdout=completed.stdout, stderr=stderr)

git_paoding/py.typed

@@ -0,0 +1 @@
+

git_paoding/store/__init__.py

@@ -0,0 +1,6 @@
+"""Local session storage package."""
+
+from git_paoding.store.jsonstore import JsonSessionStore, branch_key, common_git_dir
+from git_paoding.store.lock import SessionLock
+
+__all__ = ["JsonSessionStore", "SessionLock", "branch_key", "common_git_dir"]

git_paoding/store/jsonstore.py

@@ -0,0 +1,142 @@
+"""Versioned JSON session persistence in the repository's common Git directory."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import re
+import tempfile
+from pathlib import Path
+from typing import Any
+
+from pydantic import ValidationError
+
+from git_paoding.core.model import (
+    SCHEMA_VERSION,
+    Session,
+    SessionNotFoundError,
+    SessionValidationError,
+    UnsupportedSchemaVersionError,
+)
+from git_paoding.gitio.runner import run_git
+
+_UNSAFE_BRANCH_CHARACTERS = re.compile(r"[^A-Za-z0-9._-]+")
+_REPEATED_DASHES = re.compile(r"-{2,}")
+_BRANCH_STEM_LIMIT = 64
+
+
+def branch_key(canonical_branch: str) -> str:
+    """Return a filesystem- and ref-safe stable key for a canonical branch."""
+
+    if not canonical_branch:
+        raise ValueError("canonical branch must not be empty")
+    sanitized = _UNSAFE_BRANCH_CHARACTERS.sub("-", canonical_branch)
+    sanitized = _REPEATED_DASHES.sub("-", sanitized).strip("-._")
+    stem = sanitized[:_BRANCH_STEM_LIMIT].rstrip("-._") or "branch"
+    digest = hashlib.sha256(canonical_branch.encode("utf-8")).hexdigest()[:8]
+    return f"{stem}-{digest}"
+
+
+def common_git_dir(repo: Path) -> Path:
+    """Resolve Git's common directory, shared by the main and linked worktrees."""
+
+    repository = repo.resolve()
+    raw_path = run_git(("rev-parse", "--git-common-dir"), cwd=repository).stdout_text().strip()
+    path = Path(raw_path)
+    if not path.is_absolute():
+        path = repository / path
+    return path.resolve()
+
+
+def paoding_dir(repo: Path) -> Path:
+    """Return the local metadata root without creating it."""
+
+    return common_git_dir(repo) / "paoding"
+
+
+class JsonSessionStore:
+    """Load and atomically save one JSON session per canonical branch."""
+
+    def __init__(self, repo: Path) -> None:
+        self.repo = repo.resolve()
+        self.root = paoding_dir(self.repo)
+        self.sessions_dir = self.root / "sessions"
+
+    def session_path(self, canonical_branch: str) -> Path:
+        """Return the canonical path for a branch's session JSON."""
+
+        return self.sessions_dir / f"{branch_key(canonical_branch)}.json"
+
+    def exists(self, canonical_branch: str) -> bool:
+        """Return whether a session exists without creating metadata directories."""
+
+        return self.session_path(canonical_branch).is_file()
+
+    def load(self, canonical_branch: str) -> Session:
+        """Load and validate a session, rejecting unsupported schemas explicitly."""
+
+        path = self.session_path(canonical_branch)
+        try:
+            raw = path.read_text(encoding="utf-8")
+        except FileNotFoundError as error:
+            raise SessionNotFoundError(
+                f"No git-paoding session exists for branch {canonical_branch!r}"
+            ) from error
+        except OSError as error:
+            raise SessionValidationError(f"Could not read session file {path}: {error}") from error
+
+        try:
+            payload: Any = json.loads(raw)
+        except json.JSONDecodeError as error:
+            raise SessionValidationError(
+                f"Session file {path} is not valid JSON: {error.msg}"
+            ) from error
+        if not isinstance(payload, dict):
+            raise SessionValidationError(f"Session file {path} must contain a JSON object")
+
+        version = payload.get("schema_version")
+        if version != SCHEMA_VERSION:
+            rendered = "missing" if version is None else repr(version)
+            raise UnsupportedSchemaVersionError(
+                f"Session file {path} has unsupported schema_version {rendered}; "
+                f"this git-paoding version supports only {SCHEMA_VERSION}. "
+                "Automatic migration is intentionally disabled."
+            )
+
+        try:
+            session = Session.model_validate(payload)
+        except ValidationError as error:
+            raise SessionValidationError(f"Session file {path} is invalid: {error}") from error
+        if session.canonical_branch != canonical_branch:
+            raise SessionValidationError(
+                f"Session file {path} belongs to branch {session.canonical_branch!r}, "
+                f"not {canonical_branch!r}"
+            )
+        return session
+
+    def save(self, session: Session) -> Path:
+        """Atomically persist a validated session and return its path."""
+
+        path = self.session_path(session.canonical_branch)
+        self.sessions_dir.mkdir(parents=True, exist_ok=True)
+        serialized = session.model_dump_json(indent=2) + "\n"
+
+        temporary_path: Path | None = None
+        try:
+            descriptor, temporary_name = tempfile.mkstemp(
+                dir=self.sessions_dir,
+                prefix=f".{path.name}.",
+                suffix=".tmp",
+            )
+            temporary_path = Path(temporary_name)
+            with os.fdopen(descriptor, "w", encoding="utf-8") as stream:
+                stream.write(serialized)
+                stream.flush()
+                os.fsync(stream.fileno())
+            os.replace(temporary_path, path)
+        except OSError as error:
+            if temporary_path is not None:
+                temporary_path.unlink(missing_ok=True)
+            raise SessionValidationError(f"Could not write session file {path}: {error}") from error
+        return path