patchground 0.1.0__py3-none-any.whl

patchground/runner_assets/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "patchground-vitest-runtime",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "dependencies": {
+    "vitest": "5.0.5",
+    "vite": "8.3.5"
+  },
+  "scripts": {
+    "test": "node --check vitest-runner.mjs"
+  }
+}

patchground/runner_assets/vitest-runner.mjs

@@ -0,0 +1,124 @@
+import { spawn } from 'node:child_process';
+import { mkdtemp, readFile, writeFile, rename, rm, lstat, realpath } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const root = '/workspace';
+const final = '/results/junit.xml';
+const self = fileURLToPath(import.meta.url);
+
+async function child(destination, files) {
+  const { startVitest } = await import('vitest/node');
+  let completed;
+  const reporter = {
+    onTestModuleCollected(module) {
+      for (const test of module.children.allTests()) {
+        const retry = test.options.retry;
+        const count = typeof retry === 'number' ? retry : retry?.count ?? 0;
+        if (count > 0 || (test.options.repeats ?? 0) > 0) {
+          throw Error('Retries and repeats are unsupported');
+        }
+      }
+    },
+    onTestRunEnd(modules, errors, reason) {
+      const cases = [];
+      let trustworthy = errors.length === 0 && reason !== 'interrupted';
+      for (const module of modules) {
+        if (module.errors().length) trustworthy = false;
+        for (const suite of module.children.allSuites()) {
+          if (suite.errors().length) trustworthy = false;
+        }
+        for (const test of module.children.allTests()) {
+          const state = test.result().state;
+          if (!['passed', 'failed', 'skipped'].includes(state)) trustworthy = false;
+          cases.push({ file: module.relativeModuleId, name: test.fullName, state });
+        }
+      }
+      completed = { trustworthy, cases };
+    },
+  };
+  const ctx = await startVitest([], {
+    root, config: false, watch: false, run: true,
+    include: files.length ? files : ['**/*.test.ts'], exclude: ['**/node_modules/**', '**/.git/**'],
+    reporters: [reporter], environment: 'node', pool: 'forks', maxWorkers: 1,
+    fileParallelism: false, isolate: true, retry: 0, allowOnly: false, maxConcurrency: 1,
+    passWithNoTests: false, testTimeout: 5000, hookTimeout: 5000,
+    sequence: { shuffle: false },
+  }, {
+    configFile: false, envDir: false, cacheDir: '/tmp/patchground-vite',
+    resolve: { alias: { vitest: '/opt/patchground/node_modules/vitest/dist/index.js' } },
+  });
+  await ctx.close();
+  if (!completed || ctx.state.getUnhandledErrors().length) return;
+  await writeFile(destination, JSON.stringify(completed), { flag: 'wx' });
+}
+
+function escape(value) {
+  return value.replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;').replaceAll("'", '&apos;').replaceAll("\n", "&#10;")
+    .replaceAll("\r", "&#13;").replaceAll("\t", "&#9;");
+}
+
+async function parent() {
+  await rm(final, { force: true });
+  const temporary = await mkdtemp(path.join(tmpdir(), 'patchground-vitest-'));
+  try {
+    const receipt = path.join(temporary, 'receipt.json');
+    const args = process.argv.slice(2);
+    const files = args.length ? args.slice(1) : [];
+    if (args.length && (args[0] !== '--files' || !files.length)) return;
+    for (const file of files) {
+      const parts = file.split('/');
+      if (!file.endsWith('.test.ts') || parts.some(part =>
+        !/^[\p{L}\p{N}_. -]+$/u.test(part) || ['.', '..', '.git', 'node_modules'].includes(part))) return;
+    }
+    if (new Set(files).size !== files.length) return;
+    for (const file of files) {
+      const full = path.join(root, file);
+      if (!(await lstat(full)).isFile() || !(await realpath(full)).startsWith(root + '/')) return;
+    }
+    const code = await new Promise((resolve, reject) => {
+      const process = spawn(globalThis.process.execPath, [self, '--child', receipt, ...files], {
+        stdio: 'ignore', env: { ...globalThis.process.env, CI: 'true' },
+      });
+      process.once('error', reject);
+      process.once('exit', (code, signal) => resolve(signal ? null : code));
+    });
+    const result = JSON.parse(await readFile(receipt, 'utf8'));
+    if (!result.trustworthy || !result.cases.length) return;
+    const failed = result.cases.some(test => test.state === 'failed');
+    if (code !== (failed ? 1 : 0)) return;
+    const seen = new Set();
+    result.cases.sort((a, b) => {
+      const left = `${a.file}::${a.name}`;
+      const right = `${b.file}::${b.name}`;
+      return left < right ? -1 : left > right ? 1 : 0;
+    });
+    const cases = result.cases.map(test => {
+      if (!test.file || path.posix.isAbsolute(test.file) || test.file.split('/').includes('..')
+          || test.file.includes('\\') || !test.file.endsWith('.test.ts') || !test.name
+          || !test.file.isWellFormed() || !test.name.isWellFormed()
+          || /[\u0000-\u0008\u000b\u000c\u000e-\u001f\ufffe\uffff]/u.test(test.file + test.name)) throw Error('unsafe identity');
+      const id = `${test.file}::${test.name}`;
+      if (seen.has(id)) throw Error('duplicate identity');
+      seen.add(id);
+      const status = test.state === 'failed' ? '<failure message="test failed"/>'
+        : test.state === 'skipped' ? '<skipped/>' : '';
+      return `<testcase classname="${escape(test.file)}" name="${escape(test.name)}">${status}</testcase>`;
+    });
+    const staging = '/results/.patchground-junit.xml';
+    await writeFile(staging, `<?xml version="1.0" encoding="UTF-8"?><testsuites><testsuite name="vitest">${cases.join('')}</testsuite></testsuites>`);
+    await rename(staging, final);
+    process.exitCode = failed ? 1 : 0;
+  } finally {
+    await rm(temporary, { recursive: true, force: true });
+  }
+}
+
+try {
+  if (process.argv[2] === '--child') await child(process.argv[3], process.argv.slice(4));
+  else { process.exitCode = 1; await parent(); }
+} catch {
+  process.exitCode = 1;
+}

patchground/safeio/__init__.py

@@ -0,0 +1,115 @@
+"""Shared descriptor-safe local access and non-executing Git executable selection."""
+
+from __future__ import annotations
+
+import os
+import stat
+from collections.abc import Iterator
+from contextlib import ExitStack, contextmanager
+from pathlib import Path
+
+
+class SafetyError(Exception):
+    """A local resource cannot be accessed safely."""
+
+
+def no_links(
+    path: Path, *, error: type[Exception] = SafetyError, label: str = "filesystem"
+) -> None:
+    """Check ancestors even when the destination does not exist yet."""
+    for entry in (*reversed(path.absolute().parents), path.absolute()):
+        if entry.is_symlink():
+            raise error(f"{label} paths must not contain symlinks")
+
+
+def safe_path(
+    path: Path, *, directory: bool, error: type[Exception] = SafetyError, label: str = "filesystem"
+) -> None:
+    """Reject redirected ancestors as well as redirected leaf entries."""
+    no_links(path, error=error, label=label)
+    mode = path.lstat().st_mode
+    if not (stat.S_ISDIR(mode) if directory else stat.S_ISREG(mode)):
+        raise error(f"{label} path has an invalid file type")
+
+
+@contextmanager
+def open_directory(
+    path: Path, *, error: type[Exception] = SafetyError, label: str = "filesystem"
+) -> Iterator[int]:
+    """Pin every ancestor, not just the leaf, without following any links."""
+    root = os.open(path.absolute().anchor, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW)
+    try:
+        with ExitStack() as ancestors:
+            descriptor = root
+            for part in path.absolute().parts[1:]:
+                descriptor = ancestors.enter_context(
+                    open_entry(
+                        descriptor, part, os.O_RDONLY | os.O_DIRECTORY, error=error, label=label
+                    )
+                )
+            yield descriptor
+    except OSError as exc:
+        raise error(f"{label} directory contains a symlink or is unavailable") from exc
+    finally:
+        os.close(root)
+
+
+@contextmanager
+def open_entry(
+    parent: int,
+    name: str,
+    flags: int = os.O_RDONLY,
+    *,
+    error: type[Exception] = SafetyError,
+    label: str = "filesystem",
+) -> Iterator[int]:
+    """Validate the opened inode; NONBLOCK prevents a raced-in FIFO from hanging."""
+    before = os.stat(name, dir_fd=parent, follow_symlinks=False)
+    if not (stat.S_ISDIR(before.st_mode) or stat.S_ISREG(before.st_mode)):
+        raise error(f"{label} tree contains a symlink or special file")
+    try:
+        descriptor = os.open(name, flags | os.O_NOFOLLOW | os.O_NONBLOCK, dir_fd=parent)
+    except OSError as exc:
+        raise error(f"{label} tree contains a symlink or special file or changed") from exc
+    try:
+        actual = os.fstat(descriptor)
+        if (before.st_dev, before.st_ino) != (actual.st_dev, actual.st_ino) or not (
+            stat.S_ISDIR(actual.st_mode) or stat.S_ISREG(actual.st_mode)
+        ):
+            raise error(f"{label} tree changed during access")
+        yield descriptor
+        after = os.stat(name, dir_fd=parent, follow_symlinks=False)
+        if (actual.st_dev, actual.st_ino) != (after.st_dev, after.st_ino):
+            raise error(f"{label} tree changed during access")
+    finally:
+        os.close(descriptor)
+
+
+def resolve_git(*inputs: Path, error: type[Exception] = SafetyError) -> str:
+    """Trust only absolute PATH candidates outside cwd and all supplied input trees.
+
+    PATH is an installation search policy, not proof of executable provenance. Never
+    probe a candidate by running it. Canonicalize both the search path and target so
+    symlinks cannot disguise challenge input as an installed Git executable.
+    """
+    try:
+        roots: list[Path] = []
+        for path in (Path.cwd(), *inputs):
+            roots.extend((path.absolute(), path.resolve(strict=False)))
+        for directory in os.environ.get("PATH", os.defpath).split(os.pathsep):
+            if not Path(directory).is_absolute():
+                continue
+            candidate = Path(directory) / "git"
+            if any(candidate.is_relative_to(root) for root in roots):
+                continue
+            try:
+                executable = candidate.resolve(strict=True)
+                if any(executable.is_relative_to(root) for root in roots):
+                    continue
+                if stat.S_ISREG(executable.stat().st_mode) and os.access(executable, os.X_OK):
+                    return str(executable)
+            except (OSError, RuntimeError):
+                continue
+    except (OSError, RuntimeError):
+        pass
+    raise error("safe Git executable unavailable")

patchground/sandbox/__init__.py

@@ -0,0 +1,39 @@
+"""patchground.sandbox — see SPEC.md in this folder.
+
+The only module that talks to the container engine. Its API takes plain values (paths, strings,
+limits) and returns plain results; it knows nothing about sessions, packs or reports.
+"""
+
+from patchground.sandbox.build import BuildResult, build_image
+from patchground.sandbox.errors import BuildFailed, EngineUnavailable, JUnitError, SandboxError
+from patchground.sandbox.junit import TestResult, TestStatus, parse_junit
+from patchground.sandbox.probe import EngineProbe, EngineProblem, probe_engine
+from patchground.sandbox.run import (
+    CommandResult,
+    Limits,
+    RunOutcome,
+    RunResult,
+    run_check,
+    run_command,
+)
+
+__all__ = [
+    "BuildFailed",
+    "BuildResult",
+    "CommandResult",
+    "EngineProbe",
+    "EngineProblem",
+    "EngineUnavailable",
+    "JUnitError",
+    "Limits",
+    "RunOutcome",
+    "RunResult",
+    "SandboxError",
+    "TestResult",
+    "TestStatus",
+    "build_image",
+    "parse_junit",
+    "probe_engine",
+    "run_check",
+    "run_command",
+]

patchground/sandbox/_engine.py

@@ -0,0 +1,23 @@
+"""Connection to the container engine (Docker, or Podman via its Docker-compatible socket)."""
+
+from __future__ import annotations
+
+import docker
+import docker.errors
+import requests
+
+from patchground.sandbox.errors import EngineUnavailable
+
+
+def connect() -> docker.DockerClient:
+    """Return a client for the engine configured in the environment, or raise EngineUnavailable."""
+    try:
+        client = docker.from_env()
+    except docker.errors.DockerException as exc:
+        raise EngineUnavailable(f"container engine not reachable: {exc}") from exc
+    try:
+        client.ping()
+    except (docker.errors.DockerException, requests.exceptions.RequestException) as exc:
+        client.close()
+        raise EngineUnavailable(f"container engine not reachable: {exc}") from exc
+    return client

patchground/sandbox/build.py

@@ -0,0 +1,202 @@
+"""Build phase: build a challenge image from its environment directory.
+
+The build has network access (dependencies install here, never at run time). Consent for untrusted
+sources is the caller's job and must happen before :func:`build_image` is called.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import math
+import os
+import re
+import stat
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import docker.errors
+import requests
+import urllib3.exceptions
+
+from patchground.sandbox._engine import connect
+from patchground.sandbox.errors import BuildFailed, SandboxError
+
+#: Limits applied to every intermediate build container.
+BUILD_MEMORY_BYTES = 4 * 1024**3
+
+#: Default wall-clock budget for one image build.
+DEFAULT_BUILD_TIMEOUT_SECONDS = 1800.0
+#: A connection error this close to the deadline counts as the deadline being hit.
+TIMEOUT_TOLERANCE_SECONDS = 1.0
+
+_NAME_RE = re.compile(r"[a-z0-9]+(?:[._-][a-z0-9]+)*")
+_BUILT_RE = re.compile(r"^Successfully built ([0-9a-f]+)$")
+
+
+@dataclass(frozen=True)
+class BuildResult:
+    """A built image: ``image_id`` is the engine's opaque id, ``tag`` the cache tag."""
+
+    image_id: str
+    tag: str
+    log: str
+
+
+def context_hash(context: Path) -> str:
+    """Return a deterministic sha256 hex digest of a build context directory.
+
+    Covers every entry's relative path, kind, permission bits and content (symlinks by their
+    target text), in sorted path order, so the same tree always yields the same hash.
+    """
+    entries: list[tuple[str, Path]] = []
+    for dirpath, dirnames, filenames in os.walk(context):
+        dirnames.sort()
+        base = Path(dirpath)
+        for name in [*dirnames, *filenames]:
+            path = base / name
+            entries.append((path.relative_to(context).as_posix(), path))
+    digest = hashlib.sha256()
+    for rel, path in sorted(entries):
+        st = path.lstat()
+        mode = stat.S_IMODE(st.st_mode)
+        digest.update(rel.encode("utf-8", "surrogateescape") + b"\0")
+        if stat.S_ISLNK(st.st_mode):
+            digest.update(b"L\0" + str(path.readlink()).encode("utf-8", "surrogateescape"))
+        elif stat.S_ISDIR(st.st_mode):
+            digest.update(b"D\0" + f"{mode:o}".encode())
+        elif stat.S_ISREG(st.st_mode):
+            content = path.read_bytes()
+            digest.update(b"F\0" + f"{mode:o}\0{len(content)}\0".encode() + content)
+        else:
+            digest.update(b"O\0")
+        digest.update(b"\0")
+    return digest.hexdigest()
+
+
+def _log_text(chunks: Any) -> str:
+    parts: list[str] = []
+    for chunk in chunks:
+        if not isinstance(chunk, dict):
+            parts.append(f"{chunk}\n")
+            continue
+        for key in ("stream", "error"):
+            value = chunk.get(key)
+            if isinstance(value, str):
+                parts.append(value if key == "stream" else f"{value}\n")
+    return "".join(parts)
+
+
+def _note(log: str, note: str) -> str:
+    if log and not log.endswith("\n"):
+        log += "\n"
+    return f"{log}[patchground] {note}\n"
+
+
+def build_image(
+    dockerfile: Path, *, name: str, timeout_seconds: float = DEFAULT_BUILD_TIMEOUT_SECONDS
+) -> BuildResult:
+    """Build ``dockerfile`` with its parent directory as the context.
+
+    The image is tagged ``patchground/<name>:<hash12>`` where ``hash12`` is the start of
+    :func:`context_hash` over the context directory.
+
+    Uses the Docker Engine API's classic (legacy, non-BuildKit) builder, which is what the
+    Docker SDK drives. No host mounts and no engine socket are exposed to the build; each build
+    container is capped at :data:`BUILD_MEMORY_BYTES` without swap.
+
+    ``timeout_seconds`` is the build's wall-clock budget. It is checked every time the builder
+    emits output, and the HTTP read timeout of the build request is set to the same value, so a
+    silent step (e.g. ``RUN sleep``) aborts the build once it has been quiet that long; a build
+    that goes quiet just before the deadline can therefore overrun it by up to one more
+    ``timeout_seconds``. Aborting closes the build connection, which makes the engine cancel the
+    build and remove its intermediate container.
+
+    Raises :class:`BuildFailed` (with the build log) if the build fails or exceeds
+    ``timeout_seconds``, :class:`EngineUnavailable` if the engine cannot be reached,
+    :class:`SandboxError` for engine-side failures (5xx, lost connection), and
+    :class:`ValueError` for an invalid ``name``, path or timeout.
+    """
+    if not _NAME_RE.fullmatch(name):
+        raise ValueError(
+            f"invalid image name {name!r}: use lowercase letters, digits, '.', '_', '-'"
+        )
+    if timeout_seconds <= 0:
+        raise ValueError(f"timeout_seconds must be positive: {timeout_seconds}")
+    if not dockerfile.is_file():
+        raise ValueError(f"Dockerfile not found: {dockerfile}")
+    context = dockerfile.parent.resolve()
+    tag = f"patchground/{name}:{context_hash(context)[:12]}"
+    exceeded = f"image build exceeded {timeout_seconds:g} s"
+    chunks: list[Any] = []
+    client = connect()
+    started = time.monotonic()
+    try:
+        stream = client.api.build(
+            path=str(context),
+            dockerfile=dockerfile.name,
+            tag=tag,
+            rm=True,
+            forcerm=True,
+            pull=False,
+            container_limits={"memory": BUILD_MEMORY_BYTES, "memswap": BUILD_MEMORY_BYTES},
+            labels={"patchground": "1"},
+            decode=True,
+            timeout=math.ceil(timeout_seconds),
+        )
+        image_id: str | None = None
+        for chunk in stream:
+            chunks.append(chunk)
+            if time.monotonic() - started > timeout_seconds:
+                raise BuildFailed(_note(_log_text(chunks), exceeded), message=exceeded)
+            if not isinstance(chunk, dict):
+                continue
+            if "error" in chunk:
+                raise BuildFailed(_log_text(chunks))
+            image_id = _image_id(chunk) or image_id
+        log = _log_text(chunks)
+        if image_id is None:
+            raise BuildFailed(_note(log, "the builder reported no image id"))
+        image = client.images.get(image_id)
+    except (
+        requests.exceptions.ReadTimeout,
+        requests.exceptions.ConnectionError,
+        urllib3.exceptions.ReadTimeoutError,
+        urllib3.exceptions.ProtocolError,
+    ) as exc:
+        # A silent build step outlasting the read timeout surfaces as ReadTimeout/ConnectionError
+        # (docker/docker-py#1966) or, while the log streams, as urllib3's ReadTimeoutError.
+        # Well before the deadline it is a lost engine instead.
+        if time.monotonic() - started >= timeout_seconds - TIMEOUT_TOLERANCE_SECONDS:
+            raise BuildFailed(_note(_log_text(chunks), exceeded), message=exceeded) from exc
+        raise SandboxError(f"engine connection lost during build: {exc}") from exc
+    except docker.errors.APIError as exc:
+        status = exc.status_code
+        if status is not None and 400 <= status < 500:
+            raise BuildFailed(_note(_log_text(chunks), str(exc))) from exc
+        raise SandboxError(f"image build did not complete: {exc}") from exc
+    except (
+        docker.errors.DockerException,
+        requests.exceptions.RequestException,
+        urllib3.exceptions.HTTPError,
+    ) as exc:
+        raise SandboxError(f"image build did not complete: {exc}") from exc
+    finally:
+        client.close()
+    if image.id is None:
+        raise SandboxError("engine returned an image without an id")
+    return BuildResult(image_id=image.id, tag=tag, log=log)
+
+
+def _image_id(chunk: dict[str, Any]) -> str | None:
+    """The image id announced by a build chunk (``aux.ID`` or "Successfully built <id>")."""
+    aux = chunk.get("aux")
+    if isinstance(aux, dict) and isinstance(aux.get("ID"), str):
+        return str(aux["ID"])
+    stream = chunk.get("stream")
+    if isinstance(stream, str):
+        match = _BUILT_RE.search(stream.strip())
+        if match:
+            return match.group(1)
+    return None

patchground/sandbox/errors.py

@@ -0,0 +1,23 @@
+"""Exceptions raised by the sandbox module."""
+
+from __future__ import annotations
+
+
+class SandboxError(Exception):
+    """Base class for every sandbox failure that is not a test outcome."""
+
+
+class EngineUnavailable(SandboxError):
+    """The container engine cannot be reached (not running, no socket, no permission)."""
+
+
+class BuildFailed(SandboxError):
+    """The image build failed; ``log`` holds the builder output up to the failure."""
+
+    def __init__(self, log: str, *, message: str = "image build failed") -> None:
+        super().__init__(message)
+        self.log = log
+
+
+class JUnitError(SandboxError):
+    """A JUnit XML document could not be parsed (malformed, unsafe or wrong root)."""

patchground/sandbox/junit.py

@@ -0,0 +1,76 @@
+"""JUnit XML parsing into per-test results.
+
+The XML comes from inside a challenge container and is therefore untrusted: it is always parsed
+with ``defusedxml`` (DTDs forbidden outright, which also rules out entity-expansion and XXE
+payloads) and only then handed to ``junitparser`` for the JUnit structure.
+"""
+
+from __future__ import annotations
+
+import io
+from dataclasses import dataclass
+from enum import StrEnum
+from typing import IO
+from xml.etree.ElementTree import ElementTree, ParseError
+
+import defusedxml
+import defusedxml.ElementTree
+from junitparser import Error, Failure, JUnitXml, JUnitXmlError, Skipped
+
+from patchground.sandbox.errors import JUnitError
+
+
+class TestStatus(StrEnum):
+    """Outcome of a single test case."""
+
+    __test__ = False  # not a pytest test class
+
+    PASSED = "passed"
+    FAILED = "failed"
+    ERRORED = "errored"
+    SKIPPED = "skipped"
+
+
+@dataclass(frozen=True)
+class TestResult:
+    """One ``<testcase>``; ``id`` is ``classname::name`` (or ``name`` without a classname)."""
+
+    __test__ = False  # not a pytest test class
+
+    id: str
+    name: str
+    classname: str
+    status: TestStatus
+
+
+def _safe_parse(source: IO[bytes]) -> ElementTree:
+    return defusedxml.ElementTree.parse(source, forbid_dtd=True)
+
+
+def parse_junit(data: bytes) -> tuple[TestResult, ...]:
+    """Parse a JUnit XML document (``<testsuites>`` or ``<testsuite>`` root).
+
+    Status precedence inside one test case: error > failure > skipped > passed.
+    Raises :class:`JUnitError` if the document is malformed, unsafe or not JUnit.
+    """
+    try:
+        xml = JUnitXml.fromfile(io.BytesIO(data), parse_func=_safe_parse)
+        results: list[TestResult] = []
+        for suite in xml:
+            for case in suite:
+                name = str(case.name or "")
+                classname = str(case.classname or "")
+                outcomes = case.result
+                if any(isinstance(r, Error) for r in outcomes):
+                    status = TestStatus.ERRORED
+                elif any(isinstance(r, Failure) for r in outcomes):
+                    status = TestStatus.FAILED
+                elif any(isinstance(r, Skipped) for r in outcomes):
+                    status = TestStatus.SKIPPED
+                else:
+                    status = TestStatus.PASSED
+                test_id = f"{classname}::{name}" if classname else name
+                results.append(TestResult(test_id, name, classname, status))
+    except (ParseError, defusedxml.DefusedXmlException, JUnitXmlError) as exc:
+        raise JUnitError(f"invalid JUnit XML: {exc}") from exc
+    return tuple(results)