patchground 0.1.0__py3-none-any.whl

patchground/sessions/diagnostics.py

@@ -0,0 +1,145 @@
+"""Read-only readiness probes for `doctor`: Git availability and session-disk space.
+
+Never touches an existing workspace or runs a challenge; Git uses a temporary clean directory.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import shutil
+import subprocess
+import tempfile
+from dataclasses import dataclass
+from enum import StrEnum
+from pathlib import Path
+
+from patchground.sessions.models import SessionError
+from patchground.sessions.store import SESSIONS_ENV
+from patchground.sessions.workflow import _root
+
+MINIMUM_FREE_BYTES = 1024**3
+_GIT_TIMEOUT = 10.0
+_VERSION = re.compile(r"git version (\d+(?:\.\d+){1,3})")
+
+
+class GitProblem(StrEnum):
+    MISSING = "missing"  # no git on PATH
+    UNUSABLE = "unusable"  # found, but failed, timed out or printed no recognisable version
+
+
+@dataclass(frozen=True)
+class GitProbe:
+    available: bool
+    problem: GitProblem | None = None
+    version: str | None = None
+
+
+class DiskProblem(StrEnum):
+    LOW_SPACE = "low_space"
+    NOT_WRITABLE = "not_writable"
+    UNREADABLE = "unreadable"  # no existing ancestor could be inspected
+    INVALID_SETTING = "invalid_setting"  # PATCHGROUND_SESSIONS_DIR is not an absolute path
+
+
+@dataclass(frozen=True)
+class DiskProbe:
+    """Space where sessions are created. ``location`` is display-safe (home shown as ``~``)."""
+
+    ok: bool
+    location: str
+    problem: DiskProblem | None = None
+    free_bytes: int | None = None
+    minimum_bytes: int = MINIMUM_FREE_BYTES
+
+
+def probe_git() -> GitProbe:
+    """Run ``git --version`` with no user/system configuration and a bounded wait."""
+    executable = shutil.which("git")
+    if executable is None:
+        return GitProbe(available=False, problem=GitProblem.MISSING)
+    try:
+        resolved = str(Path(executable).resolve(strict=True))
+        with tempfile.TemporaryDirectory(prefix="patchground-doctor-") as home:
+            env = {
+                "PATH": os.defpath,
+                "HOME": home,
+                "XDG_CONFIG_HOME": home,
+                "GIT_CONFIG_NOSYSTEM": "1",
+                "GIT_CONFIG_SYSTEM": os.devnull,
+                "GIT_CONFIG_GLOBAL": os.devnull,
+                "GIT_TERMINAL_PROMPT": "0",
+                "LC_ALL": "C",
+            }
+            completed = subprocess.run(
+                [resolved, "--version"],
+                cwd=home,
+                env=env,
+                check=True,
+                capture_output=True,
+                timeout=_GIT_TIMEOUT,
+            )
+    except (OSError, subprocess.SubprocessError):
+        return GitProbe(available=False, problem=GitProblem.UNUSABLE)
+    match = _VERSION.search(completed.stdout.decode("ascii", errors="replace"))
+    if match is None:
+        return GitProbe(available=False, problem=GitProblem.UNUSABLE)
+    return GitProbe(available=True, version=match.group(1))
+
+
+def probe_disk(root: Path | None = None, *, minimum_bytes: int = MINIMUM_FREE_BYTES) -> DiskProbe:
+    """Check free space and writability at the sessions root, or its nearest existing ancestor."""
+    try:
+        target = _root(root)
+    except SessionError:
+        return DiskProbe(ok=False, location=SESSIONS_ENV, problem=DiskProblem.INVALID_SETTING)
+    location = display_path(target)
+    existing = _nearest_existing(target)
+    if existing is None:
+        return DiskProbe(ok=False, location=location, problem=DiskProblem.UNREADABLE)
+    if not existing.is_dir():  # a file where a directory is needed
+        return DiskProbe(ok=False, location=location, problem=DiskProblem.NOT_WRITABLE)
+    try:
+        free = shutil.disk_usage(existing).free
+    except OSError:
+        return DiskProbe(ok=False, location=location, problem=DiskProblem.UNREADABLE)
+    if not os.access(existing, os.W_OK | os.X_OK):
+        return DiskProbe(
+            ok=False,
+            location=location,
+            problem=DiskProblem.NOT_WRITABLE,
+            free_bytes=free,
+            minimum_bytes=minimum_bytes,
+        )
+    if free < minimum_bytes:
+        return DiskProbe(
+            ok=False,
+            location=location,
+            problem=DiskProblem.LOW_SPACE,
+            free_bytes=free,
+            minimum_bytes=minimum_bytes,
+        )
+    return DiskProbe(ok=True, location=location, free_bytes=free, minimum_bytes=minimum_bytes)
+
+
+def _nearest_existing(path: Path) -> Path | None:
+    for candidate in (path, *path.parents):
+        try:
+            if candidate.exists():
+                return candidate
+        except OSError:
+            return None
+    return None
+
+
+def display_path(path: Path) -> str:
+    """Show paths under the user's home as ``~/...`` so output never reveals the home path."""
+    try:
+        home = Path.home().absolute()
+    except (RuntimeError, KeyError):
+        return str(path)
+    try:
+        relative = path.relative_to(home)
+    except ValueError:
+        return str(path)
+    return "~" if relative == Path() else str(Path("~") / relative)

patchground/sessions/files.py

@@ -0,0 +1,113 @@
+"""Bounded copies: no links, special files, Git metadata or credential files."""
+
+from __future__ import annotations
+
+import os
+import shutil
+import stat
+from contextlib import AbstractContextManager, suppress
+from fnmatch import fnmatch
+from pathlib import Path
+
+from patchground import safeio
+from patchground.sessions.models import SessionError
+
+
+def excluded(name: str) -> bool:
+    return name.lower() == ".git" or any(
+        fnmatch(name.lower(), pattern) for pattern in (".env*", "*.pem", "*.key", "id_*")
+    )
+
+
+def no_links(path: Path) -> None:
+    safeio.no_links(path, error=SessionError, label="session")
+
+
+def safe_path(path: Path, *, directory: bool) -> None:
+    safeio.safe_path(path, directory=directory, error=SessionError, label="session")
+
+
+def open_directory(path: Path) -> AbstractContextManager[int]:
+    return safeio.open_directory(path, error=SessionError, label="session")
+
+
+def open_entry(parent: int, name: str, flags: int = os.O_RDONLY) -> AbstractContextManager[int]:
+    return safeio.open_entry(parent, name, flags, error=SessionError, label="session")
+
+
+def tree(path: Path, *, skip: bool = False) -> list[Path]:
+    entries: list[Path] = []
+
+    def visit(parent: int, base: Path) -> None:
+        for name in sorted(os.listdir(parent)):
+            with open_entry(parent, name) as descriptor:
+                if skip and excluded(name):
+                    continue
+                entry = base / name
+                entries.append(entry)
+                if stat.S_ISDIR(os.fstat(descriptor).st_mode):
+                    visit(descriptor, entry)
+
+    with open_directory(path) as descriptor:
+        visit(descriptor, path)
+    return entries
+
+
+def copy_tree(source: Path, destination: Path) -> None:
+    def copy(parent: int, target: int) -> None:
+        for name in sorted(os.listdir(parent)):
+            with open_entry(parent, name) as descriptor:
+                info = os.fstat(descriptor)
+                if excluded(name):
+                    continue
+                if stat.S_ISDIR(info.st_mode):
+                    with suppress(FileExistsError):
+                        os.mkdir(name, mode=0o700, dir_fd=target)
+                    # Layers may merge directories, but never follow destination links.
+                    with open_entry(target, name) as folder:
+                        if not stat.S_ISDIR(os.fstat(folder).st_mode):
+                            raise SessionError("check layer collision")
+                        copy(descriptor, folder)
+                else:
+                    try:
+                        output = os.open(
+                            name,
+                            os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW,
+                            0o600,
+                            dir_fd=target,
+                        )
+                    except FileExistsError as exc:
+                        raise SessionError("check layer collision") from exc
+                    with os.fdopen(output, "wb") as writer:
+                        # dup owns only the stream lifetime; no pathname is reopened.
+                        with os.fdopen(os.dup(descriptor), "rb") as reader:
+                            shutil.copyfileobj(reader, writer)
+                        os.fchmod(writer.fileno(), stat.S_IMODE(info.st_mode) & 0o777)
+
+    with open_directory(source) as source_fd, open_directory(destination) as destination_fd:
+        copy(source_fd, destination_fd)
+
+
+def readonly(path: Path) -> None:
+    def visit(parent: int) -> None:
+        for name in os.listdir(parent):
+            with open_entry(parent, name) as descriptor:
+                mode = os.fstat(descriptor).st_mode
+                if stat.S_ISDIR(mode):
+                    visit(descriptor)
+                os.fchmod(descriptor, 0o500 if stat.S_ISDIR(mode) or mode & 0o111 else 0o400)
+
+    with open_directory(path) as descriptor:
+        visit(descriptor)
+        os.fchmod(descriptor, 0o500)
+
+
+def remove_partial(path: Path) -> None:
+    # Only called for a newly reserved directory, never an existing attempt.
+    for base, dirs, _files in os.walk(path, followlinks=False):
+        Path(base).chmod(0o700)
+        for name in dirs:
+            entry = Path(base) / name
+            if not entry.is_symlink():
+                entry.chmod(0o700)
+    shutil.rmtree(path)

patchground/sessions/git.py

@@ -0,0 +1,70 @@
+"""Initialize fresh workspace Git before handoff; private checkpoints live in history."""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import tempfile
+from pathlib import Path
+
+from patchground import safeio
+from patchground.sessions.models import SessionError
+
+
+def resolve_executable(*inputs: Path) -> str:
+    return safeio.resolve_git(*inputs, error=SessionError)
+
+
+def initialize(
+    workspace: Path, *, source: Path | None = None, inputs: tuple[Path, ...] = ()
+) -> None:
+    if (workspace / ".git").exists():
+        raise SessionError("refusing to reuse an existing repository")
+    executable = resolve_executable(workspace, *inputs, *((source,) if source is not None else ()))
+    with tempfile.TemporaryDirectory(prefix="patchground-git-") as home:
+        # Allowlist, not a GIT_* denylist: config, index, object stores, hooks and
+        # process injection settings must not be inherited from the caller.
+        env = {
+            "PATH": os.defpath,
+            "HOME": home,
+            "XDG_CONFIG_HOME": home,
+            "GIT_CONFIG_NOSYSTEM": "1",
+            "GIT_CONFIG_SYSTEM": os.devnull,
+            "GIT_CONFIG_GLOBAL": os.devnull,
+            "GIT_ATTR_NOSYSTEM": "1",
+            "GIT_TERMINAL_PROMPT": "0",
+            "LC_ALL": "C",
+        }
+        command = [
+            executable,
+            "-c",
+            "core.hooksPath=" + os.devnull,
+            "-c",
+            "core.fsmonitor=false",
+            "-c",
+            "core.attributesFile=" + os.devnull,
+            "-c",
+            "core.autocrlf=false",
+            "-c",
+            "commit.gpgSign=false",
+            "-c",
+            "user.name=Patchground",
+            "-c",
+            "user.email=0+patchground@users.noreply.github.com",
+        ]
+        for args in (
+            ["init", "--template=", "--initial-branch=main"],
+            ["add", "--all", "--", "."],
+            ["commit", "--allow-empty", "-m", "Initial challenge workspace"],
+        ):
+            try:
+                subprocess.run(
+                    [*command, *args],
+                    cwd=workspace,
+                    env=env,
+                    check=True,
+                    capture_output=True,
+                    timeout=60,
+                )
+            except (OSError, subprocess.SubprocessError) as exc:
+                raise SessionError("could not initialize the fresh Git baseline") from exc