patchground 0.1.0__py3-none-any.whl

patchground/automation/__main__.py

@@ -0,0 +1,131 @@
+"""Command-line entry for the reusable validation Action.
+
+Run as ``python -I -m patchground.automation``. Only fixed, path-free messages are emitted.
+"""
+
+from __future__ import annotations
+
+import argparse
+import contextlib
+import json
+import os
+import signal
+import sys
+from collections.abc import Callable, Sequence
+from pathlib import Path
+from typing import Any, NoReturn
+
+from patchground.safeio import SafetyError, open_directory
+
+ERROR_FORMAT = "patchground-automation-error"
+USAGE_EXIT = 2
+CANCEL_EXIT = 130
+
+
+class _UsageError(Exception):
+    pass
+
+
+class _Parser(argparse.ArgumentParser):
+    def error(self, message: str) -> NoReturn:
+        raise _UsageError("invalid command-line arguments")
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = _Parser(prog="python -m patchground.automation", add_help=False, exit_on_error=False)
+    parser.add_argument("--source", required=True)
+    parser.add_argument("--directory", default=".")
+    parser.add_argument("--base", default=None)
+    parser.add_argument("--consent", action="store_true")
+    parser.add_argument("--report", required=True)
+    return parser
+
+
+def _error_document(message: str) -> dict[str, Any]:
+    return {"format": ERROR_FORMAT, "version": 1, "exit_code": USAGE_EXIT, "error": message}
+
+
+def _reserve_report(report: str, source: Path) -> int:
+    """Exclusively create the report in a pinned, link-free parent outside the checkout."""
+    path = Path(report).absolute()
+    if ".." in path.parts or path.name in {"", "."}:
+        raise _UsageError("report path must name a file without '..' components")
+    parent = path.parent
+    if parent == source or source in parent.parents:
+        raise _UsageError("report path must be outside the source checkout")
+    flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW
+    try:
+        with open_directory(parent, label="report") as pinned:
+            return os.open(path.name, flags, 0o600, dir_fd=pinned)
+    except FileExistsError:
+        raise _UsageError("report file already exists") from None
+    except (SafetyError, OSError):
+        raise _UsageError("report location is unsafe or unavailable") from None
+
+
+def _write(fd: int, document: dict[str, Any]) -> None:
+    with os.fdopen(fd, "w", encoding="utf-8") as handle:
+        json.dump(document, handle, indent=2, sort_keys=True)
+        handle.write("\n")
+
+
+def _default_validate() -> Callable[..., Any]:
+    from patchground.automation import validate_changes
+
+    return validate_changes
+
+
+def main(
+    argv: Sequence[str] | None = None,
+    *,
+    validate: Callable[..., Any] | None = None,
+) -> int:
+    fd: int | None = None
+    document: dict[str, Any] = _error_document("automation failed unexpectedly")
+    code = USAGE_EXIT
+    try:
+        try:
+            args = _parser().parse_args(argv)
+        except argparse.ArgumentError:
+            raise _UsageError("invalid command-line arguments") from None
+        source = Path(args.source).resolve()
+        if not source.is_dir():
+            raise _UsageError("source is not a directory")
+        fd = _reserve_report(args.report, source)
+        run = validate or _default_validate()
+        result = run(
+            source,
+            directory=args.directory,
+            base=args.base or None,
+            consent=args.consent,
+        )
+        document, code = result.to_dict(), int(result.exit_code)
+        reserved, fd = fd, None
+        _write(reserved, document)
+        print(f"patchground validation finished with exit code {code}; report written")
+        return code
+    except _UsageError as exc:
+        document, code = _error_document(str(exc)), USAGE_EXIT
+    except KeyboardInterrupt:
+        document, code = _error_document("cancelled"), CANCEL_EXIT
+        document["exit_code"] = code
+    except Exception as exc:  # report type only: messages may carry paths or source text
+        document = _error_document(f"automation failed unexpectedly ({type(exc).__name__})")
+        code = USAGE_EXIT
+    finally:
+        # Leaves no open descriptor behind; a repeated interrupt here is safe to ignore.
+        pending, fd = fd, None
+        if pending is not None:
+            with contextlib.suppress(OSError, KeyboardInterrupt):
+                _write(pending, document)
+    print(json.dumps(document, sort_keys=True), file=sys.stderr)
+    return code
+
+
+def _terminate(signum: int, frame: Any) -> NoReturn:
+    raise KeyboardInterrupt
+
+
+if __name__ == "__main__":
+    signal.signal(signal.SIGTERM, _terminate)
+    sys.exit(main())

patchground/automation/workflow.py

@@ -0,0 +1,214 @@
+"""Select committed challenges and aggregate the existing verifier's safe facts."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from contextlib import contextmanager
+from dataclasses import dataclass, field
+from pathlib import Path, PurePosixPath
+from tempfile import TemporaryDirectory
+from typing import Any
+
+from patchground import verify
+from patchground.packs.discovery import discover_challenges
+from patchground.packs.models import PackError, SourceSnapshot
+from patchground.packs.source import fetch_pack
+from patchground.packs.store import capture_tree
+from patchground.spec import ManifestError, load_challenge, load_pack
+
+
+@dataclass
+class AutomationResult:
+    """One JSON-safe outcome, containing no verifier diagnostics or scratch paths."""
+
+    exit_code: int = 0
+    commit: str | None = None
+    base_commit: str | None = None
+    selection_mode: str = "all"
+    selected: list[str] = field(default_factory=list)
+    unchanged: list[str] = field(default_factory=list)
+    removed: list[str] = field(default_factory=list)
+    validations: list[dict[str, Any]] = field(default_factory=list)
+    errors: list[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "format": "patchground-automation",
+            "format_version": 1,
+            "commit": self.commit,
+            "base_commit": self.base_commit,
+            "selection_mode": self.selection_mode,
+            "status": "failed" if self.exit_code else "validated" if self.selected else "skipped",
+            "exit_code": self.exit_code,
+            "selected": list(self.selected),
+            "unchanged": list(self.unchanged),
+            "removed": list(self.removed),
+            "validations": list(self.validations),
+            "errors": list(self.errors),
+        }
+
+
+@contextmanager
+def _snapshot(
+    source: Path, *, ref: str = "HEAD"
+) -> Iterator[tuple[SourceSnapshot, tuple[Path, ...]]]:
+    with fetch_pack(source, ref=ref) as snapshot:
+        if not (snapshot.path / "challenge.yaml").is_file():
+            yield snapshot, (snapshot.path,)
+            return
+        # The verifier requires the root folder name to match the manifest id. Git transport's
+        # scratch name is not the authored checkout name; preserve that identity in our own copy.
+        with TemporaryDirectory(prefix="patchground-automation-") as temporary:
+            target = Path(temporary).resolve() / Path(snapshot.source).name
+            target.mkdir()
+            capture_tree(snapshot.path.resolve(), target, seal=False)
+            yield snapshot.model_copy(update={"path": target}), (snapshot.path, target)
+
+
+def _candidates(root: Path, directory: str) -> list[str]:
+    folder = root / directory
+    if not folder.is_dir():
+        raise ValueError("selected directory is unavailable")
+    if (folder / "pack.yaml").exists():
+        pack = load_pack(folder)
+        paths = [folder / name for name in pack.manifest.challenges]
+    elif (folder / "challenge.yaml").exists():
+        paths = [folder]
+    else:
+        discovered = discover_challenges(folder)
+        paths = [Path(item.path) for item in discovered.challenges]
+        paths.extend(Path(item.path) for item in discovered.invalid)
+    # Preflight every candidate, including unchanged ones, before any build.
+    for path in paths:
+        load_challenge(path)
+    return sorted(path.relative_to(root).as_posix() for path in paths)
+
+
+def _pack_metadata(folder: Path) -> bytes | None:
+    manifest = folder / "pack.yaml"
+    return manifest.read_bytes() if manifest.is_file() else None
+
+
+def _manifest_errors(exc: ManifestError, root: Path) -> list[str]:
+    return [
+        f"{issue.file.relative_to(root).as_posix()}:{issue.line or 1}: "
+        "invalid manifest or challenge layout"
+        for issue in exc.issues
+    ]
+
+
+def validate_changes(
+    source: Path,
+    *,
+    directory: str = ".",
+    base: str | None = None,
+    consent: bool = False,
+    sandbox: verify.Sandbox | None = None,
+) -> AutomationResult:
+    """Validate selected raw committed inputs with explicit build consent and no writes."""
+    result = AutomationResult()
+    relative = PurePosixPath(directory)
+    if (
+        not directory
+        or relative.is_absolute()
+        or ".." in relative.parts
+        or "\\" in directory
+        or ":" in directory
+        or any(ord(char) < 32 for char in directory)
+    ):
+        result.exit_code = 2
+        result.errors.append("directory must be a relative path within the committed source")
+        return result
+    try:
+        with _snapshot(Path(source)) as (current, captured_roots):
+            result.commit = current.commit
+            try:
+                candidates = _candidates(current.path, directory)
+            except ManifestError as exc:
+                result.exit_code = 1
+                result.errors = _manifest_errors(exc, current.path)
+                return result
+            except ValueError:
+                result.exit_code = 1
+                result.errors.append("selected directory has invalid challenge candidates")
+                return result
+            if not candidates:
+                result.exit_code = 1
+                result.errors.append("selected directory has no discoverable challenges")
+                return result
+            result.selected = candidates
+            if base is not None:
+                result.selection_mode = "fallback_all"
+                try:
+                    with _snapshot(Path(source), ref=base) as (previous, _):
+                        old = _candidates(previous.path, directory)
+                        metadata_changed = _pack_metadata(
+                            current.path / directory
+                        ) != _pack_metadata(previous.path / directory)
+                        result.removed = sorted(set(old) - set(candidates))
+                        result.unchanged = [
+                            name
+                            for name in candidates
+                            if name in old
+                            and not metadata_changed
+                            and capture_tree(
+                                (current.path / name).resolve(), None, seal=False
+                            ).digest
+                            == capture_tree(
+                                (previous.path / name).resolve(), None, seal=False
+                            ).digest
+                        ]
+                        result.selected = [
+                            name for name in candidates if name not in result.unchanged
+                        ]
+                        result.base_commit = previous.commit
+                        result.selection_mode = "changed"
+                except (PackError, ManifestError, ValueError, OSError):
+                    # An unusable comparison must never turn into a silent skip.
+                    result.selected = candidates
+                    result.unchanged = []
+                    result.removed = []
+            if result.selected and not consent:
+                result.exit_code = 2
+                result.errors.append("explicit execution consent is required before building")
+                return result
+            for name in result.selected:
+                try:
+                    report = verify.validate_challenge(
+                        current.path / name,
+                        write=False,
+                        sandbox=sandbox,
+                        input_roots=(Path(current.source), *captured_roots),
+                    )
+                except verify.VerifyEnvironmentError:
+                    result.exit_code = 2
+                    result.errors.append(f"{name}: validation infrastructure unavailable")
+                    continue
+                result.validations.append(
+                    {
+                        "path": name,
+                        "valid": report.valid,
+                        "failed_step": report.failed_step.value if report.failed_step else None,
+                        "steps": [
+                            {
+                                "name": step.name.value,
+                                "status": step.status.value,
+                                "runs": [
+                                    {
+                                        "label": run.label,
+                                        "outcome": run.outcome.value,
+                                        "counts": run.to_dict()["counts"],
+                                    }
+                                    for run in step.runs
+                                ],
+                            }
+                            for step in report.steps
+                        ],
+                    }
+                )
+                if not report.valid and result.exit_code == 0:
+                    result.exit_code = 1
+    except (PackError, OSError):
+        result.exit_code = 2
+        result.errors.append("committed source could not be read safely")
+    return result

patchground/catalog/README.md

@@ -0,0 +1,10 @@
+# Examples
+
+Each folder here is a complete, hand-made challenge in the v0.1 format
+(`docs/contracts/challenge-format.md`): a manifest, a ticket, a starting workspace, an image
+definition, visible and hidden checks, and a reference patch. They are small on purpose — they show
+authors what a good challenge looks like and give Patchground a known-good input for its own tests.
+
+Every example must pass `pgnd validate examples/<id>`: the manifest is valid, the image builds, the
+starting workspace fails at least one hidden check, and the reference patch makes every check pass.
+A change that breaks validation of an example is a regression.

patchground/catalog/cache-expiry/TICKET.md

@@ -0,0 +1,49 @@
+# Profiles stay stale, and bad TTLs are accepted silently
+
+**Reported by:** support and on-call (two tickets merged)
+**Component:** `profilecache`
+
+## Symptom
+
+1. Users who keep a dashboard open see an old display name for as long as the dashboard keeps
+   polling. Profiles that nobody is looking at refresh fine. A profile cached with a 30 second
+   lifetime but polled every 10 seconds was still served unchanged after several minutes.
+2. In tests that drive the clock by hand, a profile cached for 30 seconds is still served at exactly
+   30 seconds and only disappears a moment later. Operations tooling that expires entries on a
+   schedule shows the same one-tick delay.
+3. A deploy accidentally configured a cache lifetime of `0`. Nothing complained, and a negative value
+   from a config typo was accepted the same way.
+
+## Reproduction
+
+```python
+from profilecache import TTLCache
+
+now = [0.0]
+cache = TTLCache(default_ttl=10, clock=lambda: now[0])
+
+cache.set("a", 1)
+now[0] = 6
+cache.get("a")           # a read at 6s
+now[0] = 10
+print(cache.get("a"))    # expected: None, actual: 1
+
+cache.set("b", 2, ttl=0)  # accepted without error
+```
+
+## Expected
+
+- An entry lives for exactly its TTL: at the instant the clock reaches its deadline it is expired.
+  This applies to `get`, `in` and `purge_expired` alike.
+- Writing a key starts its lifetime again with the TTL given for that write. Reading a key never
+  changes how long it lives.
+- A TTL of zero or less is invalid, both as the cache default and for an individual write. It must
+  raise `ValueError`, and a rejected write must leave the cache exactly as it was.
+
+## Notes
+
+- Keep the injectable clock; do not sleep or use real time in tests.
+- Run `pgnd check` from the session workspace to check your changes in Docker.
+- Add regression tests for the reported behavior and keep existing behavior intact.
+- You may use your own editor and AI tools. The goal is to explain the cause and verify your fix,
+  not merely make the reported cases pass.

patchground/catalog/cache-expiry/challenge.yaml

@@ -0,0 +1,32 @@
+spec_version: "0.1"
+id: cache-expiry
+version: 1.0.1
+title: Cached profiles never expire while they are being read
+type: debug
+summary: >-
+  A TTL cache keeps entries alive when they are read, expires them one tick late and accepts
+  nonpositive TTLs. Find the causes and fix them without changing write behavior.
+languages: [python]
+tags: [caching, ttl, time]
+difficulty: intermediate
+timebox_minutes: 30
+ai_policy: allowed
+environment:
+  dockerfile: environment/Dockerfile
+  services: []
+  test_command: pytest -q -p no:cacheprovider --junitxml=$PG_RESULTS/junit.xml
+checks:
+  visible: checks/visible
+  hidden: checks/hidden
+solution: solution/reference.patch
+expected_paths: [src/profilecache/, tests/]
+hints:
+  - Write down, for one entry, the clock value at which it should expire, then step through what each method does to that deadline.
+  - Is the deadline moved by anything other than a write?
+debrief:
+  questions: debrief/questions.md
+  focus: [debugging_method, test_quality, scope_judgment]
+author: {name: Patchground contributors}
+content_license: CC-BY-4.0
+provenance: generated
+generated_by: {model: "Claude Code configured default (model unverified)", prompt_version: launch-cache-v1}

patchground/catalog/cache-expiry/checks/hidden/tests/test_cache_hidden.py

@@ -0,0 +1,164 @@
+import pytest
+
+from profilecache import ProfileClient, TTLCache
+
+
+class Clock:
+    def __init__(self, now: float = 500.0) -> None:
+        self.now = now
+
+    def __call__(self) -> float:
+        return self.now
+
+    def advance(self, seconds: float) -> None:
+        self.now += seconds
+
+
+def test_entry_alive_just_before_deadline():
+    clock = Clock()
+    cache = TTLCache(default_ttl=10, clock=clock)
+    cache.set("a", 1)
+    clock.advance(9.5)
+    assert cache.get("a") == 1
+
+
+def test_entry_expires_exactly_at_deadline():
+    clock = Clock()
+    cache = TTLCache(default_ttl=10, clock=clock)
+    cache.set("a", 1)
+    clock.advance(10)
+    assert cache.get("a", "gone") == "gone"
+
+
+def test_contains_is_false_exactly_at_deadline():
+    clock = Clock()
+    cache = TTLCache(default_ttl=10, clock=clock)
+    cache.set("a", 1)
+    clock.advance(10)
+    assert "a" not in cache
+
+
+def test_purge_removes_entry_exactly_at_deadline():
+    clock = Clock()
+    cache = TTLCache(default_ttl=10, clock=clock)
+    cache.set("a", 1)
+    cache.set("b", 2, ttl=20)
+    clock.advance(10)
+    assert cache.purge_expired() == 1
+    assert cache.get("b") == 2
+
+
+def test_read_does_not_extend_lifetime():
+    clock = Clock()
+    cache = TTLCache(default_ttl=10, clock=clock)
+    cache.set("a", 1)
+    clock.advance(6)
+    assert cache.get("a") == 1
+    clock.advance(4)
+    assert cache.get("a", "gone") == "gone"
+
+
+def test_repeated_reads_never_keep_entry_alive():
+    clock = Clock()
+    cache = TTLCache(default_ttl=10, clock=clock)
+    cache.set("a", 1)
+    for _ in range(4):
+        clock.advance(2.5)
+        cache.get("a")
+    assert "a" not in cache
+
+
+def test_write_refreshes_lifetime():
+    clock = Clock()
+    cache = TTLCache(default_ttl=10, clock=clock)
+    cache.set("a", 1)
+    clock.advance(8)
+    cache.set("a", 2)
+    clock.advance(8)
+    assert cache.get("a") == 2
+    clock.advance(2)
+    assert cache.get("a", "gone") == "gone"
+
+
+def test_write_can_shorten_lifetime():
+    clock = Clock()
+    cache = TTLCache(default_ttl=100, clock=clock)
+    cache.set("a", 1)
+    cache.set("a", 2, ttl=5)
+    clock.advance(5)
+    assert cache.get("a", "gone") == "gone"
+
+
+def test_zero_ttl_write_is_rejected():
+    cache = TTLCache(clock=Clock())
+    with pytest.raises(ValueError):
+        cache.set("a", 1, ttl=0)
+
+
+def test_negative_ttl_write_is_rejected():
+    cache = TTLCache(clock=Clock())
+    with pytest.raises(ValueError):
+        cache.set("a", 1, ttl=-3)
+
+
+def test_nonpositive_default_ttl_is_rejected():
+    with pytest.raises(ValueError):
+        TTLCache(default_ttl=0, clock=Clock())
+    with pytest.raises(ValueError):
+        TTLCache(default_ttl=-1, clock=Clock())
+
+
+def test_rejected_write_keeps_existing_entry():
+    clock = Clock()
+    cache = TTLCache(default_ttl=10, clock=clock)
+    cache.set("a", 1)
+    with pytest.raises(ValueError):
+        cache.set("a", 2, ttl=0)
+    assert cache.get("a") == 1
+
+
+def test_rejected_write_does_not_store_new_key():
+    cache = TTLCache(clock=Clock())
+    with pytest.raises(ValueError):
+        cache.set("a", 1, ttl=-1)
+    assert "a" not in cache
+
+
+def test_client_refetches_at_ttl_boundary():
+    clock = Clock()
+    calls = []
+
+    def fetch(user_id):
+        calls.append(user_id)
+        return {"id": user_id, "n": len(calls)}
+
+    client = ProfileClient(fetch, cache=TTLCache(clock=clock), ttl=30)
+    client.get("u1")
+    clock.advance(30)
+    assert client.get("u1")["n"] == 2
+    assert calls == ["u1", "u1"]
+
+
+def test_client_sees_fresh_profile_despite_frequent_reads():
+    clock = Clock()
+    calls = []
+
+    def fetch(user_id):
+        calls.append(user_id)
+        return {"id": user_id, "n": len(calls)}
+
+    client = ProfileClient(fetch, cache=TTLCache(clock=clock), ttl=30)
+    for _ in range(7):
+        client.get("u1")
+        clock.advance(10)
+    assert len(calls) == 3
+
+
+def test_client_update_restarts_lifetime():
+    clock = Clock()
+    client = ProfileClient(lambda uid: {"id": uid, "v": 1}, cache=TTLCache(clock=clock), ttl=30)
+    client.get("u1")
+    clock.advance(25)
+    client.update("u1", {"id": "u1", "v": 2})
+    clock.advance(25)
+    assert client.get("u1")["v"] == 2

patchground/catalog/cache-expiry/checks/visible/tests/test_cache.py

@@ -0,0 +1,56 @@
+from profilecache import ProfileClient, TTLCache
+
+
+class FakeClock:
+    def __init__(self, now: float = 1000.0) -> None:
+        self.now = now
+
+    def __call__(self) -> float:
+        return self.now
+
+    def advance(self, seconds: float) -> None:
+        self.now += seconds
+
+
+def test_get_returns_stored_value():
+    cache = TTLCache(default_ttl=10, clock=FakeClock())
+    cache.set("a", 1)
+    assert cache.get("a") == 1
+
+
+def test_missing_key_returns_default():
+    cache = TTLCache(default_ttl=10, clock=FakeClock())
+    assert cache.get("nope") is None
+    assert cache.get("nope", "fallback") == "fallback"
+
+
+def test_entry_is_gone_well_after_deadline():
+    clock = FakeClock()
+    cache = TTLCache(default_ttl=10, clock=clock)
+    cache.set("a", 1)
+    clock.advance(60)
+    assert cache.get("a") is None
+    assert "a" not in cache
+
+
+def test_per_write_ttl_overrides_default():
+    clock = FakeClock()
+    cache = TTLCache(default_ttl=100, clock=clock)
+    cache.set("short", 1, ttl=5)
+    clock.advance(20)
+    assert cache.get("short") is None
+
+
+def test_client_fetches_once_while_fresh():
+    clock = FakeClock()
+    calls = []
+
+    def fetch(user_id):
+        calls.append(user_id)
+        return {"id": user_id}
+
+    client = ProfileClient(fetch, cache=TTLCache(clock=clock), ttl=30)
+    assert client.get("u1") == {"id": "u1"}
+    clock.advance(5)
+    assert client.get("u1") == {"id": "u1"}
+    assert calls == ["u1"]

patchground/catalog/cache-expiry/debrief/questions.md

@@ -0,0 +1,4 @@
+- Which of the three symptoms shared a root cause, and which did not? How did you decide?
+- How did you check the expiry boundary without sleeping, and why does an injected clock matter here?
+- Which behavior did you want to leave unchanged while fixing reads, and how did you protect it?
+- If an AI assistant proposed a fix, what did you verify yourself before accepting it?

patchground/catalog/cache-expiry/environment/Dockerfile

@@ -0,0 +1,3 @@
+FROM python:3.12-slim
+ENV PYTHONDONTWRITEBYTECODE=1
+RUN pip install --no-cache-dir pytest==8.3.5