compforge-repokit 0.15.0__py3-none-any.whl

repokit/_process.py

@@ -0,0 +1,135 @@
+"""Bounded subprocesses sharing an operation deadline."""
+
+import math
+import os
+import selectors
+import signal
+import subprocess
+import time
+from pathlib import Path
+from threading import Event
+
+
+class Budget:
+    def __init__(self, timeout: float, cancel: Event | None):
+        if not math.isfinite(timeout) or timeout <= 0:
+            raise ValueError("timeout must be positive and finite")
+        self.parent: Budget | None = None
+        self.deadline = time.monotonic() + timeout
+        self.cancel = cancel
+
+    def remaining(self) -> float:
+        if self.parent is not None:
+            self.parent.remaining()
+        if self.cancel is not None and self.cancel.is_set():
+            raise InterruptedError("operation cancelled")
+        remaining = self.deadline - time.monotonic()
+        if remaining <= 0:
+            raise TimeoutError("operation timed out")
+        return remaining
+
+
+def run(
+    root: Path,
+    args: list[str],
+    budget: Budget,
+    *,
+    input: bytes = b"",
+    allow_missing: bool = False,
+    max_output: int = 16 << 20,
+) -> bytes:
+    return run_command(
+        ["git", "-C", str(root), *args],
+        budget,
+        input=input,
+        allow_missing=allow_missing,
+        max_output=max_output,
+    ).stdout
+
+
+def run_command(
+    command: list[str],
+    budget: Budget,
+    *,
+    input: bytes = b"",
+    allow_missing: bool = False,
+    max_output: int = 16 << 20,
+    env: dict[str, str] | None = None,
+    cwd: Path | None = None,
+    process_group: bool = False,
+) -> subprocess.CompletedProcess[bytes]:
+    budget.remaining()
+    process = subprocess.Popen(
+        command,
+        stdin=subprocess.PIPE,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        env=env,
+        cwd=cwd,
+        start_new_session=process_group,
+    )
+    assert process.stdin is not None and process.stdout is not None and process.stderr is not None
+    stdout, stderr = bytearray(), bytearray()
+    pending = memoryview(input)
+    try:
+        # Drain both outputs while feeding a batch. communicate() buffers without a
+        # capacity bound; waiting before draining can deadlock on a full pipe.
+        with selectors.DefaultSelector() as selector:
+            for pipe, target in ((process.stdout, stdout), (process.stderr, stderr)):
+                os.set_blocking(pipe.fileno(), False)
+                selector.register(pipe, selectors.EVENT_READ, target)
+            if pending:
+                os.set_blocking(process.stdin.fileno(), False)
+                selector.register(process.stdin, selectors.EVENT_WRITE)
+            else:
+                process.stdin.close()
+            while selector.get_map():
+                remaining = budget.remaining()
+                for key, event in selector.select(min(remaining, 0.05)):
+                    if event == selectors.EVENT_WRITE:
+                        try:
+                            used = os.write(key.fd, pending[:65536])
+                            pending = pending[used:]
+                        except BrokenPipeError:
+                            pending = memoryview(b"")
+                        if not pending:
+                            selector.unregister(key.fileobj)
+                            process.stdin.close()
+                    else:
+                        chunk = os.read(key.fd, 65536)
+                        if not chunk:
+                            selector.unregister(key.fileobj)
+                            continue
+                        target = key.data
+                        limit = max_output if target is stdout else 65536
+                        if len(target) + len(chunk) > limit:
+                            raise ValueError(f"Process output exceeds {limit} bytes")
+                        target.extend(chunk)
+            while process.poll() is None:
+                remaining = budget.remaining()
+                try:
+                    process.wait(timeout=min(remaining, 0.05))
+                except subprocess.TimeoutExpired:
+                    continue
+        budget.remaining()
+        if process.returncode != 0 and not (allow_missing and process.returncode == 1):
+            raise subprocess.CalledProcessError(
+                process.returncode, command, bytes(stdout), bytes(stderr)
+            )
+        return subprocess.CompletedProcess(
+            command, process.returncode, bytes(stdout), bytes(stderr)
+        )
+    finally:
+        # Timeout, cancellation and output overflow must not leave Git running.
+        if process_group:
+            # Package-manager lifecycle scripts may outlive their parent on cancellation.
+            try:
+                os.killpg(process.pid, signal.SIGKILL)
+            except ProcessLookupError:
+                pass
+        elif process.poll() is None:
+            process.kill()
+        process.wait()
+        process.stdin.close()
+        process.stdout.close()
+        process.stderr.close()

repokit/_staging.py

@@ -0,0 +1,59 @@
+"""Prepare and validate an index while holding Git's native writer lock."""
+
+import os
+import shutil
+import tempfile
+from collections.abc import Callable
+from pathlib import Path
+
+from .git import GitResult, git
+from .git_index import IndexView, index_view
+from .git_state import git_path
+
+
+def stage_validated(
+    repo: str | Path, paths: list[str], validate: Callable[[IndexView], None]
+) -> GitResult:
+    index = git_path(repo, "index")
+    lock = index.with_name(index.name + ".lock")
+    try:
+        lock_file = lock.open("xb")
+    except OSError as exc:
+        return GitResult(-1, "", f"cannot lock Git index: {exc}")
+    installed = False
+    try:
+        # why: hold the native lock from snapshot through replacement, so another
+        # Git writer cannot have its index update silently overwritten.
+        with (
+            lock_file,
+            tempfile.TemporaryDirectory(prefix="repokit-index-", dir=index.parent) as tmp,
+        ):
+            prepared = Path(tmp) / "index"
+            if index.exists():
+                shutil.copy2(index, prepared)
+            result = GitResult(0, "", "")
+            if paths:
+                result = git(
+                    repo,
+                    "--literal-pathspecs",
+                    "add",
+                    "--",
+                    *paths,
+                    timeout=30,
+                    index_file=prepared,
+                )
+                if not result.ok:
+                    return result
+            validate(index_view(repo, index_file=prepared))
+            if prepared.exists():
+                # Use the lock file as the replacement, following Git's index protocol.
+                with prepared.open("rb") as source:
+                    shutil.copyfileobj(source, lock_file)
+                lock_file.flush()
+                os.fchmod(lock_file.fileno(), prepared.stat().st_mode & 0o777)
+                os.replace(lock, index)
+                installed = True
+            return result
+    finally:
+        if not installed:
+            lock.unlink(missing_ok=True)

repokit/budget.py

@@ -0,0 +1,40 @@
+"""Caller-owned operation scope shared by Git and Forge transport calls."""
+
+from collections.abc import Iterator
+from contextlib import contextmanager
+from contextvars import ContextVar
+from threading import Event
+
+from ._process import Budget
+
+_current: ContextVar[Budget | None] = ContextVar("repokit_operation", default=None)
+
+
+@contextmanager
+def operation(*, timeout: float = 30, cancel: Event | None = None) -> Iterator[None]:
+    """Bound a compound library operation; nested scopes never extend the outer deadline.
+
+    Git cancellation kills and reaps its process. HTTP cancellation is checked between
+    requests/reads; an in-flight socket remains bounded by its request timeout.
+    This is an execution scope, not a transaction or a retry policy.
+    """
+    budget = Budget(timeout, cancel)
+    outer = _current.get()
+    if outer is not None:
+        budget.deadline = min(budget.deadline, outer.deadline)
+        budget.parent = outer
+    token = _current.set(budget)
+    try:
+        budget.remaining()
+        yield
+    finally:
+        _current.reset(token)
+
+
+def current_budget(timeout: float) -> Budget:
+    budget = Budget(timeout, None)
+    outer = _current.get()
+    if outer is not None:
+        budget.deadline = min(budget.deadline, outer.deadline)
+        budget.parent = outer
+    return budget

repokit/dependencies.py

@@ -0,0 +1,378 @@
+"""Observe checkout-local dependencies and explicitly materialize locked installations."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import stat
+import subprocess
+import threading
+import tomllib
+from dataclasses import dataclass, replace
+from pathlib import Path
+from typing import Literal
+
+import yaml
+
+from . import _process
+from ._inspect import inspect
+from .budget import current_budget
+from .model import InspectReport, owner
+
+Status = Literal["ready", "present", "missing", "stale", "unsupported"]
+_RECEIPT = ".repokit-dependencies.json"
+_NODE_LOCKS = {
+    "npm": ("npm-shrinkwrap.json", "package-lock.json"),
+    "pnpm": ("pnpm-lock.yaml",),
+    "yarn": ("yarn.lock",),
+    "bun": ("bun.lock", "bun.lockb"),
+}
+_LOCKS: dict[Path, threading.Lock] = {}
+_LOCKS_GUARD = threading.Lock()
+
+
+@dataclass(frozen=True, slots=True)
+class DependencyEnvironment:
+    """An installation belongs to a checkout and may serve multiple workspace Components.
+
+    present means local dependencies exist without a matching preparation receipt;
+    it is not proof that a user-managed environment matches the lockfile.
+    missing describes an absent directory, independently of whether command provides
+    a supported locked installation. unsupported describes an unusable local layout.
+    """
+
+    component: Path
+    checkout: Path
+    root: Path
+    manager: str
+    directory: Path
+    command: tuple[str, ...]
+    inputs: tuple[Path, ...]
+    fingerprint: str
+    status: Status
+    reason: str = ""
+
+
+@dataclass(frozen=True, slots=True)
+class DependencyPreparation:
+    environment: DependencyEnvironment
+    status: Literal["ready", "unsupported", "failed", "uncertain"]
+    executed: bool = False
+    exit_code: int | None = None
+    stdout: str = ""
+    stderr: str = ""
+    reason: str = ""
+
+
+def _json(path: Path) -> dict[str, object]:
+    value = json.loads(path.read_text())
+    if not isinstance(value, dict):
+        raise ValueError(f"Expected an object: {path}")
+    return value
+
+
+def _patterns(root: Path, python: bool) -> tuple[str, ...]:
+    values: object
+    if python:
+        manifest = root / "pyproject.toml"
+        if not manifest.is_file():
+            return ()
+        workspace = (
+            tomllib.loads(manifest.read_text()).get("tool", {}).get("uv", {}).get("workspace", {})
+        )
+        values = [*workspace.get("members", []), *("!" + p for p in workspace.get("exclude", []))]
+    elif (root / "pnpm-workspace.yaml").is_file():
+        value = yaml.safe_load((root / "pnpm-workspace.yaml").read_text())
+        values = value.get("packages", []) if isinstance(value, dict) else []
+    elif (root / "package.json").is_file():
+        value = _json(root / "package.json").get("workspaces", [])
+        values = value.get("packages", []) if isinstance(value, dict) else value
+    else:
+        return ()
+    if not isinstance(values, list) or any(not isinstance(p, str) for p in values):
+        raise ValueError(f"Invalid workspace members: {root}")
+    return tuple(values)
+
+
+def _members(root: Path, python: bool) -> tuple[Path, ...]:
+    included: set[Path] = set()
+    excluded: set[Path] = set()
+    manifest = "pyproject.toml" if python else "package.json"
+    for pattern in _patterns(root, python):
+        negative = pattern.startswith("!")
+        glob = pattern[1:] if negative else pattern
+        if Path(glob).is_absolute() or ".." in Path(glob).parts:
+            raise ValueError("Workspace members must remain inside their installation root")
+        # Do not silently interpret unsupported shell/YAML glob syntax as a different workspace.
+        if any(char in glob for char in "{}()"):
+            raise ValueError(f"Unsupported workspace glob: {glob}")
+        for path in root.glob(glob):
+            if not (path / manifest).is_file():
+                continue
+            if not path.resolve().is_relative_to(root):
+                raise ValueError("Workspace member resolves outside its installation root")
+            (excluded if negative else included).add(path.resolve())
+            if len(included) + len(excluded) > 4096:
+                raise ValueError("Workspace exceeds 4096 dependency manifests")
+    return tuple(sorted(included - excluded))
+
+
+def _root(component: Path, checkout: Path, python: bool) -> Path:
+    selected = component
+    for parent in component.parents:
+        if not parent.is_relative_to(checkout):
+            break
+        if selected in _members(parent, python):
+            selected = parent
+    return selected
+
+
+def _fingerprint(root: Path, inputs: tuple[Path, ...]) -> str:
+    digest = hashlib.sha256(str(root).encode())
+    for path in inputs:
+        digest.update(str(path.relative_to(root)).encode())
+        digest.update(b"\0")
+        digest.update(path.read_bytes())
+        digest.update(b"\0")
+    return digest.hexdigest()
+
+
+def _observe(environment: DependencyEnvironment) -> DependencyEnvironment:
+    directory = environment.directory
+    # Observe the entry itself: a dangling symlink is an unsupported installation,
+    # while absence says nothing about whether a locked installer is available.
+    # Permission and other observation errors propagate instead of claiming missing.
+    try:
+        mode = directory.lstat().st_mode
+    except FileNotFoundError:
+        return replace(environment, status="missing", reason="Local dependencies are missing")
+    if stat.S_ISLNK(mode):
+        return replace(
+            environment,
+            status="unsupported",
+            reason="Dependency directory is a symlink; refusing to reuse another installation",
+        )
+    if not stat.S_ISDIR(mode):
+        return replace(
+            environment,
+            status="unsupported",
+            reason="Dependency path is not a directory",
+        )
+    receipt = directory / _RECEIPT
+    if not receipt.exists():
+        return replace(
+            environment,
+            status="present",
+            reason="Local dependencies exist without a receipt; consistency is unverified",
+        )
+    try:
+        prepared = _json(receipt)
+    except (ValueError, OSError):
+        return replace(
+            environment, status="stale", reason="Dependency preparation receipt is unreadable"
+        )
+    if prepared.get("fingerprint") != environment.fingerprint:
+        return replace(
+            environment,
+            status="stale",
+            reason="Dependency manifests, lockfile or installation path changed",
+        )
+    return replace(environment, status="ready", reason="")
+
+
+def inspect_dependencies(
+    path: str | Path, *, inspection: InspectReport | None = None
+) -> tuple[DependencyEnvironment, ...]:
+    """Read-only dependency observations; never install during inspect or worktree creation.
+
+    An optional complete working-tree inspection avoids repeating repository discovery.
+    Installation roots are resolved only within that checkout, never through its parent.
+    """
+    component = Path(path).resolve(strict=True)
+    report = inspection or inspect(component)
+    if not report.complete or report.input != "working_tree":
+        raise ValueError("Dependency preparation requires complete working-tree inspection")
+    checkout = Path(report.checkout).resolve()
+    binding = owner(report, component.relative_to(checkout).as_posix())
+    if binding is None:
+        raise ValueError("No Component owns the requested dependency path")
+    component = checkout / binding.root
+    environments: list[DependencyEnvironment] = []
+    kinds = []
+    if (component / "package.json").is_file():
+        kinds.append(False)
+    if (component / "pyproject.toml").is_file():
+        kinds.append(True)
+    for python in kinds:
+        root = _root(component, checkout, python)
+        manifest = root / ("pyproject.toml" if python else "package.json")
+        members = _members(root, python)
+        inputs = {manifest, *(member / manifest.name for member in members)}
+        command: tuple[str, ...] = ()
+        if python:
+            manager = "uv"
+            lock = root / "uv.lock"
+            if not lock.is_file():
+                # Legacy/unmanaged Python projects do not imply a uv environment.
+                continue
+            command = (
+                ("uv", "sync", "--locked", "--all-packages")
+                if members
+                else ("uv", "sync", "--locked")
+            )
+            inputs.add(lock)
+            directory = root / ".venv"
+        else:
+            declared = _json(manifest).get("packageManager", "")
+            if not isinstance(declared, str):
+                raise ValueError("packageManager must be a string")
+            manager = declared.partition("@")[0]
+            if not manager:
+                candidates = [
+                    name
+                    for name, locks in _NODE_LOCKS.items()
+                    if any((root / lock).is_file() for lock in locks)
+                ]
+                if len(candidates) > 1:
+                    raise ValueError(
+                        "Ambiguous package manager; declare packageManager in package.json"
+                    )
+                manager = candidates[0] if candidates else "node"
+            locks = _NODE_LOCKS.get(manager, ())
+            node_lock = next((root / name for name in locks if (root / name).is_file()), None)
+            if node_lock:
+                inputs.add(node_lock)
+                if manager == "npm":
+                    command = ("npm", "ci", "--prefer-offline")
+                elif manager in {"bun", "pnpm"}:
+                    command = (manager, "install", "--frozen-lockfile")
+                elif manager == "yarn":
+                    classic = declared.startswith("yarn@1.") or node_lock.read_text().startswith(
+                        "# yarn lockfile v1"
+                    )
+                    command = ("yarn", "install", "--frozen-lockfile" if classic else "--immutable")
+            directory = root / "node_modules"
+            if manager == "yarn" and (root / ".pnp.cjs").exists():
+                # A PnP installation is not a missing node_modules installation.
+                # No receipt directory or repair strategy is claimed for this mode yet.
+                raise ValueError("Yarn PnP dependency preparation is not supported")
+        for config in ("pnpm-workspace.yaml", ".npmrc", ".yarnrc.yml", "bunfig.toml", "uv.toml"):
+            if (root / config).is_file():
+                inputs.add(root / config)
+        files = tuple(sorted(inputs))
+        environment = DependencyEnvironment(
+            component,
+            checkout,
+            root,
+            manager,
+            directory,
+            command,
+            files,
+            _fingerprint(root, files),
+            "missing",
+        )
+        environments.append(_observe(environment))
+    return tuple(environments)
+
+
+def prepare_dependencies(
+    environment: DependencyEnvironment, *, timeout: float = 600
+) -> DependencyPreparation:
+    """Explicit locked installation, serialized per installation root within this process.
+
+    Does not install runtimes, upgrade dependencies, edit locks, or own validation policy.
+    Failures retain process evidence; interruption after launch is uncertain, never ready.
+    """
+    budget = current_budget(timeout)
+    with _LOCKS_GUARD:
+        lock = _LOCKS.setdefault(environment.root, threading.Lock())
+    try:
+        while not lock.acquire(timeout=min(0.05, budget.remaining())):
+            pass
+    except (TimeoutError, InterruptedError) as error:
+        return DependencyPreparation(environment, "failed", reason=str(error))
+    try:
+        current = next(
+            (
+                item
+                for item in inspect_dependencies(environment.component)
+                if item.manager == environment.manager and item.root == environment.root
+            ),
+            None,
+        )
+        if current is None or current.fingerprint != environment.fingerprint:
+            return DependencyPreparation(
+                environment,
+                "failed",
+                reason="Dependency inputs changed; inspect again before preparation",
+            )
+        if current.status == "ready":
+            return DependencyPreparation(current, "ready")
+        if not current.command or current.status == "unsupported":
+            return DependencyPreparation(
+                current, "unsupported", reason=current.reason or "No supported locked installation"
+            )
+        # uv must not inherit a path that redirects this checkout's editable installation.
+        env = dict(os.environ)
+        if current.manager == "uv":
+            env.pop("VIRTUAL_ENV", None)
+            env.pop("UV_PROJECT_ENVIRONMENT", None)
+        try:
+            budget.remaining()
+        except (TimeoutError, InterruptedError) as error:
+            return DependencyPreparation(current, "failed", reason=str(error))
+        try:
+            result = _process.run_command(
+                list(current.command), budget, cwd=current.root, env=env, process_group=True
+            )
+        except subprocess.CalledProcessError as error:
+            return DependencyPreparation(
+                current,
+                "failed",
+                True,
+                error.returncode,
+                os.fsdecode(error.output or b""),
+                os.fsdecode(error.stderr or b""),
+                "Locked dependency installation failed",
+            )
+        except (TimeoutError, InterruptedError, ValueError) as error:
+            return DependencyPreparation(current, "uncertain", True, reason=str(error))
+        except OSError as error:
+            return DependencyPreparation(current, "failed", reason=str(error))
+        refreshed = next(
+            (
+                item
+                for item in inspect_dependencies(current.component)
+                if item.manager == current.manager and item.root == current.root
+            ),
+            None,
+        )
+        if refreshed is None or refreshed.fingerprint != current.fingerprint:
+            return DependencyPreparation(
+                current,
+                "failed",
+                True,
+                reason="Dependency inputs changed during installation; no ready receipt written",
+            )
+        if not current.directory.is_dir() or current.directory.is_symlink():
+            return DependencyPreparation(
+                current,
+                "failed",
+                True,
+                reason="Installer did not materialize checkout-local dependencies",
+            )
+        receipt = current.directory / _RECEIPT
+        receipt.write_text(
+            json.dumps({"fingerprint": current.fingerprint, "manager": current.manager}) + "\n"
+        )
+        return DependencyPreparation(
+            _observe(current),
+            "ready",
+            True,
+            result.returncode,
+            os.fsdecode(result.stdout),
+            os.fsdecode(result.stderr),
+        )
+    finally:
+        lock.release()

repokit/forge/__init__.py

@@ -0,0 +1,13 @@
+"""Forge clients accept explicit endpoint and credentials; no application configuration."""
+
+from .creation import PullRequestCreation as PullRequestCreation
+from .creation import ensure_pull_request as ensure_pull_request
+from .github import GitHubForge as GitHubForge
+from .gitlab import GitLabForge as GitLabForge
+from .model import Page as Page
+from .observation import BranchPullRequests as BranchPullRequests
+from .observation import PullRequestContext as PullRequestContext
+from .observation import PullRequestKey as PullRequestKey
+from .observation import PullRequestObserver as PullRequestObserver
+from .observation import PullRequestStatus as PullRequestStatus
+from .observation import PullRequestStatusUnavailable as PullRequestStatusUnavailable