patchground 0.1.0__py3-none-any.whl

patchground/sessions/models.py

@@ -0,0 +1,126 @@
+"""Versioned storage and public, log-free session results."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Literal
+
+from pydantic import AwareDatetime, BaseModel, ConfigDict, Field, computed_field, model_validator
+
+from patchground.packs.models import PackIdentity
+from patchground.sandbox import RunOutcome, TestStatus
+
+
+class SessionError(Exception):
+    """Invalid input, unsafe session storage, or unavailable infrastructure."""
+
+
+class Model(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+
+class SessionRecord(Model):
+    schema_version: Literal[1] = 1
+    challenge_id: str
+    challenge_version: str
+    source: str
+    trust: Literal["local-authored", "unofficial"] = "local-authored"
+    pack: PackIdentity | None = None
+    image_id: str = Field(min_length=1)
+    started_at: AwareDatetime
+    timer: bool
+    history_enabled: bool = False
+
+    @model_validator(mode="after")
+    def consistent_pack(self) -> SessionRecord:
+        if (self.pack is None) != (self.trust == "local-authored"):
+            raise ValueError("inconsistent pack provenance")
+        return self
+
+
+class CheckTest(Model):
+    id: str
+    status: TestStatus
+
+
+class SnapshotStatus(Model):
+    state: Literal["recorded", "unavailable", "disabled"]
+    ref: str | None = None
+    detail: Literal["Checkpoint capture unavailable"] | None = None
+
+
+class HistoryEntry(Model):
+    ref: str
+    commit: str
+    kind: Literal["initial", "check"]
+    ts: AwareDatetime
+    check_outcome: str | None = None
+
+
+class HistoryResult(Model):
+    session: Path
+    enabled: bool
+    availability: Literal["available", "disabled", "unavailable"]
+    snapshots: tuple[HistoryEntry, ...]
+
+
+class CheckResult(Model):
+    outcome: RunOutcome
+    tests: tuple[CheckTest, ...]
+    duration_seconds: float = Field(ge=0, allow_inf_nan=False)
+    limit: Literal["timeout", "memory"] | None = None
+    history: SnapshotStatus | None = None
+
+    @computed_field  # type: ignore[prop-decorator]
+    @property
+    def passed(self) -> bool:
+        return (
+            self.outcome == RunOutcome.PASSED
+            and bool(self.tests)
+            and all(test.status == TestStatus.PASSED for test in self.tests)
+        )
+
+    @computed_field  # type: ignore[prop-decorator]
+    @property
+    def counts(self) -> dict[str, int]:
+        return {status.value: sum(t.status == status for t in self.tests) for status in TestStatus}
+
+
+class Event(Model):
+    ts: AwareDatetime
+    type: str
+    data: dict[str, object]
+
+
+class StartedSession(Model):
+    session: Path
+    workspace: Path
+    challenge_id: str
+    timer: bool
+    ticket: str
+    pack: PackIdentity | None = None
+    history: SnapshotStatus | None = None
+
+
+class ResetResult(Model):
+    session: Path
+    workspace: Path
+    challenge_id: str
+
+
+class SessionStatus(Model):
+    session: Path
+    workspace: Path
+    challenge_id: str
+    timer: bool
+    state: Literal["active", "submitted"] = "active"
+    submitted_at: AwareDatetime | None = None
+    elapsed_seconds: float
+    timebox_minutes: int
+    last_check: CheckResult | None
+    last_outcome: str | None
+
+
+def now() -> datetime:
+    return datetime.now(UTC)

patchground/sessions/practice.py

@@ -0,0 +1,202 @@
+"""Authored hints, local session browsing and metadata-only command orchestration."""
+
+from __future__ import annotations
+
+import os
+import stat
+import tempfile
+import time
+from collections.abc import Sequence
+from pathlib import Path
+from typing import Literal, Protocol
+
+from pydantic import AwareDatetime, Field
+
+from patchground import sandbox as engine
+from patchground.sandbox import CommandResult, SandboxError
+from patchground.sessions import store
+from patchground.sessions.files import copy_tree, no_links, open_directory, safe_path
+from patchground.sessions.models import Model, SessionError
+from patchground.sessions.submission import require_active
+from patchground.sessions.workflow import _root, session_status
+
+
+class HintResult(Model):
+    session: Path
+    challenge_id: str
+    index: int | None
+    hint: str | None
+    remaining: int
+    exhausted: bool
+    total: int = 0
+
+
+class SessionListingItem(Model):
+    session: Path
+    challenge_id: str
+    challenge_version: str
+    started_at: AwareDatetime
+    state: Literal["active", "submitted"]
+    last_outcome: str | None
+    timer: bool
+    elapsed_seconds: float
+    timebox_minutes: int
+
+
+class InvalidSession(Model):
+    session: Path
+    reason: str
+
+
+class SessionsList(Model):
+    sessions: tuple[SessionListingItem, ...]
+    invalid: tuple[InvalidSession, ...]
+    root: Path | None = None
+
+
+class CommandRunResult(Model):
+    exit_code: int | None
+    limit: str | None
+    duration_seconds: float = Field(ge=0, allow_inf_nan=False)
+    output_tail: str
+    output_tail_only: Literal[True] = True
+
+
+class CommandSandbox(Protocol):
+    def run_command(
+        self, image_id: str, layers: Sequence[Path], argv: Sequence[str]
+    ) -> CommandResult: ...
+
+
+def reveal_hint(session: Path | None = None, *, root: Path | None = None) -> HintResult:
+    try:
+        path = store.resolve(session, _root(root))
+        meta = path / ".session"
+        with store.locked(meta):
+            record, manifest, events = store.load(path)
+            require_active(meta)
+            indices = [event.data.get("index") for event in events if event.type == "hint_revealed"]
+            if (
+                any(type(index) is not int for index in indices)
+                or indices != list(range(1, len(indices) + 1))
+                or len(indices) > len(manifest.hints)
+            ):
+                raise SessionError("corrupt hint history")
+            index = len(indices)
+            exhausted = index == len(manifest.hints)
+            if not exhausted:
+                store.append_event(meta, "hint_revealed", {"index": index + 1})
+            return HintResult(
+                session=path,
+                challenge_id=record.challenge_id,
+                index=None if exhausted else index + 1,
+                hint=None if exhausted else manifest.hints[index],
+                remaining=max(0, len(manifest.hints) - index - 1),
+                exhausted=exhausted,
+                total=len(manifest.hints),
+            )
+    except (OSError, UnicodeError) as exc:
+        raise SessionError("hint unavailable: invalid session storage") from exc
+
+
+def list_sessions(*, root: Path | None = None) -> SessionsList:
+    base = _root(root)
+    items: list[SessionListingItem] = []
+    invalid: list[InvalidSession] = []
+    try:
+        no_links(base)
+        if not base.exists():
+            return SessionsList(sessions=(), invalid=(), root=base)
+        safe_path(base, directory=True)
+        with open_directory(base) as parent, os.scandir(parent) as entries:
+            names = sorted(entry.name for entry in entries)
+        for name in names:
+            path = base / name
+            try:
+                mode = path.lstat().st_mode
+                if stat.S_ISLNK(mode):
+                    raise SessionError("unsafe session entry")
+                if not stat.S_ISDIR(mode):
+                    continue
+                with open_directory(path) as parent, os.scandir(parent) as entries:
+                    if not any(entry.name == ".session" for entry in entries):
+                        continue
+                record, _, _ = store.load(path)
+                status = session_status(path, root=base)
+                items.append(
+                    SessionListingItem(
+                        session=path,
+                        challenge_id=record.challenge_id,
+                        challenge_version=record.challenge_version,
+                        started_at=record.started_at,
+                        state=status.state,
+                        last_outcome=status.last_outcome,
+                        timer=status.timer,
+                        elapsed_seconds=status.elapsed_seconds,
+                        timebox_minutes=status.timebox_minutes,
+                    )
+                )
+            except (SessionError, OSError, UnicodeError):
+                invalid.append(InvalidSession(session=path, reason="unsafe or invalid session"))
+    except (OSError, UnicodeError) as exc:
+        raise SessionError("sessions unavailable: session directory cannot be read") from exc
+    items.sort(key=lambda item: (item.started_at, item.session.name), reverse=True)
+    return SessionsList(sessions=tuple(items), invalid=tuple(invalid), root=base)
+
+
+def run_session_command(
+    argv: Sequence[str],
+    session: Path | None = None,
+    *,
+    root: Path | None = None,
+    sandbox: CommandSandbox = engine,
+) -> CommandRunResult:
+    if not argv or not argv[0] or any("\0" in argument for argument in argv):
+        raise SessionError("run requires a nonempty command after --")
+    try:
+        path = store.resolve(session, _root(root))
+        meta = path / ".session"
+        with store.locked(meta):
+            record, _, _ = store.load(path)
+            require_active(meta)
+            started = time.monotonic()
+            try:
+                with tempfile.TemporaryDirectory(
+                    prefix="patchground-command-",
+                    dir=Path(tempfile.gettempdir()).resolve(strict=True),
+                ) as temporary:
+                    captured = Path(temporary)
+                    copy_tree(path / "workspace", captured)
+                    result = sandbox.run_command(record.image_id, [captured], tuple(argv))
+                response = CommandRunResult(
+                    exit_code=result.exit_code,
+                    limit=result.limit,
+                    duration_seconds=time.monotonic() - started,
+                    output_tail=result.output_tail,
+                )
+            except (SandboxError, SessionError, OSError, KeyboardInterrupt) as exc:
+                store.append_event(
+                    meta,
+                    "command_run",
+                    {
+                        "outcome": "interrupted"
+                        if isinstance(exc, KeyboardInterrupt)
+                        else "environment_error",
+                        "duration_seconds": time.monotonic() - started,
+                    },
+                )
+                raise
+            store.append_event(
+                meta,
+                "command_run",
+                {
+                    "exit_code": response.exit_code,
+                    "limit": response.limit,
+                    "duration_seconds": response.duration_seconds,
+                },
+            )
+            return response
+    except (OSError, UnicodeError, SandboxError) as exc:
+        raise SessionError(
+            "command unavailable: session storage or frozen image unavailable"
+        ) from exc

patchground/sessions/reset.py

@@ -0,0 +1,121 @@
+"""Restore ordinary workspace files without invoking Git or following links."""
+
+from __future__ import annotations
+
+import os
+import shutil
+import stat
+import tempfile
+from contextlib import suppress
+from pathlib import Path
+
+from patchground.sessions import store
+from patchground.sessions.files import copy_tree, excluded, open_directory, open_entry
+from patchground.sessions.models import ResetResult, SessionError
+
+
+def _inspect(parent: int) -> dict[str, object]:
+    result: dict[str, object] = {}
+    for name in sorted(os.listdir(parent)):
+        if excluded(name):
+            result[name] = None
+            continue
+        with open_entry(parent, name) as entry:
+            result[name] = _inspect(entry) if stat.S_ISDIR(os.fstat(entry).st_mode) else False
+    return result
+
+
+def _protected(node: object) -> bool:
+    return node is None or (isinstance(node, dict) and any(_protected(v) for v in node.values()))
+
+
+def _preflight(original: dict[str, object], current: dict[str, object]) -> None:
+    for name, node in original.items():
+        if name not in current:
+            continue
+        target = current[name]
+        if isinstance(node, dict) and isinstance(target, dict):
+            _preflight(node, target)
+        elif _protected(target):
+            raise SessionError("reset blocked: starting files conflict with protected entries")
+
+
+def _empty(parent: int) -> bool:
+    return not os.listdir(parent)
+
+
+def _clear(parent: int) -> None:
+    for name in sorted(os.listdir(parent)):
+        if excluded(name):
+            continue
+        directory = False
+        with open_entry(parent, name) as entry:
+            directory = stat.S_ISDIR(os.fstat(entry).st_mode)
+            if directory:
+                _clear(entry)
+                empty = _empty(entry)
+        if directory:
+            if empty:
+                os.rmdir(name, dir_fd=parent)
+        else:
+            os.unlink(name, dir_fd=parent)
+
+
+def _restore(source: int, target: int) -> None:
+    for name in sorted(os.listdir(source)):
+        with open_entry(source, name) as entry:
+            info = os.fstat(entry)
+            if stat.S_ISDIR(info.st_mode):
+                with suppress(FileExistsError):
+                    os.mkdir(name, mode=0o700, dir_fd=target)
+                with open_entry(target, name, os.O_RDONLY | os.O_DIRECTORY) as folder:
+                    _restore(entry, folder)
+            else:
+                output = os.open(
+                    name,
+                    os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW,
+                    0o600,
+                    dir_fd=target,
+                )
+                with os.fdopen(output, "wb") as writer:
+                    with os.fdopen(os.dup(entry), "rb") as reader:
+                        shutil.copyfileobj(reader, writer)
+                    os.fchmod(writer.fileno(), (stat.S_IMODE(info.st_mode) & 0o777) | 0o600)
+
+
+def reset_session(session: Path | None = None, *, root: Path | None = None) -> ResetResult:
+    """Reset a selected session; confirmation belongs to the CLI."""
+    mutated = False
+    try:
+        root = (root if root is not None else store.default_root()).absolute()
+        path = store.resolve(session, root)
+        store.load(path)
+        meta = path / ".session"
+        with store.locked(meta):
+            record, _, _ = store.load(path)
+            from patchground.sessions.submission import require_active
+
+            require_active(meta)
+            with tempfile.TemporaryDirectory(
+                prefix="patchground-reset-", dir=Path(tempfile.gettempdir()).resolve(strict=True)
+            ) as temporary:
+                staged = Path(temporary)
+                copy_tree(meta / "original", staged)
+                with open_directory(staged) as original, open_directory(path / "workspace") as work:
+                    _preflight(_inspect(original), _inspect(work))
+                    mutated = True
+                    _clear(work)
+                    _restore(original, work)
+            store.append_event(meta, "reset", {})
+            return ResetResult(
+                session=path, workspace=path / "workspace", challenge_id=record.challenge_id
+            )
+    except (OSError, UnicodeError, SessionError) as exc:
+        if mutated:
+            raise SessionError(
+                "reset incomplete: workspace may be partially restored; "
+                "fix filesystem access and retry"
+            ) from exc
+        if isinstance(exc, SessionError):
+            raise
+        raise SessionError("reset unavailable: session storage could not be read") from exc

patchground/sessions/store.py

@@ -0,0 +1,203 @@
+"""Fixed session layout, typed reads, append-only events and POSIX check locking."""
+
+from __future__ import annotations
+
+import fcntl
+import json
+import os
+import stat
+from collections.abc import Iterator
+from contextlib import contextmanager
+from datetime import date
+from pathlib import Path
+
+from pydantic import ValidationError
+
+from patchground.sessions.files import no_links, open_directory, safe_path, tree
+from patchground.sessions.models import CheckResult, Event, SessionError, SessionRecord, now
+from patchground.spec import ChallengeManifest
+
+SESSIONS_ENV = "PATCHGROUND_SESSIONS_DIR"
+
+
+def default_root() -> Path:
+    """Where sessions live: ``$PATCHGROUND_SESSIONS_DIR`` if set, else ``~/patchground/sessions``.
+
+    A relative override would select different roots from different working directories, so it is
+    rejected rather than silently anchored to the current one. The explicitly chosen path is
+    canonicalized once (``/tmp`` is a symlink on macOS); sessions below it still refuse links.
+    """
+    configured = os.environ.get(SESSIONS_ENV, "").strip()
+    if not configured:
+        return Path.home() / "patchground" / "sessions"
+    path = Path(configured).expanduser()
+    if not path.is_absolute():
+        raise SessionError(f"{SESSIONS_ENV} must be an absolute path")
+    return path.resolve()
+
+
+def allocate(root: Path, challenge_id: str) -> Path:
+    no_links(root)
+    root.mkdir(mode=0o700, parents=True, exist_ok=True)
+    safe_path(root, directory=True)
+    stem = f"{date.today().isoformat()}-{challenge_id}"
+    suffix = 0
+    while True:
+        candidate = root / (stem if suffix == 0 else f"{stem}-{suffix}")
+        try:
+            candidate.mkdir(mode=0o700)
+            return candidate
+        except FileExistsError:
+            suffix += 1
+
+
+def resolve(session: Path | None, root: Path) -> Path:
+    no_links(root)
+    if not root.exists():
+        raise SessionError("no sessions found: start a challenge, then select it with --session")
+    safe_path(root, directory=True)
+    selected = (session if session is not None else Path.cwd()).absolute()
+    safe_path(selected, directory=True)
+    # Normalize '..' only after rejecting links: lexical ancestors alone can
+    # incorrectly select a session when the requested path actually escapes it.
+    selected = selected.resolve(strict=True)
+    for candidate in (selected, *selected.parents):
+        if candidate.parent == root.resolve(strict=True):
+            return candidate
+    raise SessionError(
+        "select a session with --session or run inside its workspace; "
+        "list your attempts with: pgnd sessions"
+    )
+
+
+def load(path: Path) -> tuple[SessionRecord, ChallengeManifest, list[Event]]:
+    safe_path(path, directory=True)
+    meta = path / ".session"
+    safe_path(meta, directory=True)
+    from patchground.sessions.submission import audit_contents, completed
+
+    saved = completed(meta)
+    if saved is None:
+        safe_path(path / "workspace", directory=True)
+    contents: dict[str, bytes] = {}
+    with open_directory(meta) as parent:
+        for name in ("session.json", "manifest.json", "TICKET.md", "events.jsonl", "lock"):
+            with metadata_file(parent, name) as descriptor:
+                if name in ("session.json", "manifest.json", "events.jsonl"):
+                    with os.fdopen(os.dup(descriptor), "rb") as stream:
+                        contents[name] = stream.read()
+    if saved is None:
+        tree(meta / "hidden")
+        tree(meta / "original")
+    try:
+        record = SessionRecord.model_validate_json(contents["session.json"])
+        manifest = ChallengeManifest.model_validate_json(contents["manifest.json"])
+        raw = contents["events.jsonl"]
+        if saved is not None:
+            raw = audit_contents(raw, saved[1])[0]
+        elif not raw.endswith(b"\n"):
+            raise ValueError("truncated events")
+        events = [Event.model_validate_json(line) for line in raw.splitlines()]
+        if not events or events[0].type != "session_started":
+            raise ValueError("missing start event")
+        if events[0].ts != record.started_at or events[0].data != {
+            "challenge_id": record.challenge_id
+        }:
+            raise ValueError("inconsistent start event")
+        for event in events:
+            if event.type == "check_run":
+                check_from_event(event)
+        if (record.challenge_id, record.challenge_version) != (manifest.id, manifest.version):
+            raise ValueError("inconsistent manifest")
+        if manifest.environment.services:
+            raise ValueError("unsupported services")
+        submitted = [event for event in events if event.type == "submitted"]
+        if saved is not None:
+            receipt = saved[1]
+            if receipt.requested_at < record.started_at:
+                raise ValueError("submission predates session")
+            if submitted and (
+                len(submitted) != 1
+                or submitted[0].data != {"requested_at": receipt.requested_at.isoformat()}
+                or submitted[0] != Event.model_validate_json(receipt.audit.event)
+            ):
+                raise ValueError("inconsistent submitted event")
+        elif submitted:
+            raise ValueError("submission audit has no bundle")
+    except (ValidationError, ValueError, UnicodeError) as exc:
+        raise SessionError("corrupt session metadata or events") from exc
+    return record, manifest, events
+
+
+def check_from_event(event: Event) -> CheckResult | None:
+    if event.data.get("outcome") in ("environment_error", "interrupted"):
+        if set(event.data) != {"outcome", "duration_seconds"}:
+            raise ValueError("invalid check event")
+        duration = event.data["duration_seconds"]
+        if not isinstance(duration, int | float) or not 0 <= duration < float("inf"):
+            raise ValueError("invalid check duration")
+        return None
+    data = dict(event.data)
+    counts = data.pop("counts", None)
+    passed = data.pop("passed", None)
+    result = CheckResult.model_validate(data)
+    if counts != result.counts or passed != result.passed:
+        raise ValueError("inconsistent check result")
+    return result
+
+
+@contextmanager
+def metadata_file(parent: int, name: str, flags: int = os.O_RDONLY) -> Iterator[int]:
+    """Mutable session metadata must be an unshared regular inode, even after a race."""
+    try:
+        descriptor = os.open(name, flags | os.O_NOFOLLOW | os.O_NONBLOCK, dir_fd=parent)
+    except OSError as exc:
+        raise SessionError("session metadata contains a symlink or is unavailable") from exc
+    try:
+        info = os.fstat(descriptor)
+        if not stat.S_ISREG(info.st_mode) or info.st_nlink != 1:
+            raise SessionError("session metadata must be a regular file without hardlinks")
+        yield descriptor
+    finally:
+        os.close(descriptor)
+
+
+def append_event(meta: Path, kind: str, data: dict[str, object]) -> None:
+    serialized = Event(ts=now(), type=kind, data=data).model_dump_json() + "\n"
+    append_bytes(meta, serialized.encode("utf-8"))
+
+
+def append_bytes(meta: Path, serialized: bytes) -> None:
+    """Append exact session-owned event bytes, including deterministic audit recovery suffixes."""
+    # Validate the actual append descriptor after any long-running work.
+    with (
+        open_directory(meta) as parent,
+        metadata_file(parent, "events.jsonl", os.O_WRONLY | os.O_APPEND) as descriptor,
+        os.fdopen(os.dup(descriptor), "ab") as stream,
+    ):
+        stream.write(serialized)
+        stream.flush()
+        os.fsync(stream.fileno())
+
+
+def write_json(path: Path, value: object) -> None:
+    with open_directory(path.parent) as parent:
+        descriptor = os.open(
+            path.name, os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW, 0o600, dir_fd=parent
+        )
+        with os.fdopen(descriptor, "w", encoding="utf-8") as stream:
+            stream.write(json.dumps(value, ensure_ascii=False) + "\n")
+
+
+@contextmanager
+def locked(meta: Path) -> Iterator[None]:
+    with (
+        open_directory(meta) as parent,
+        metadata_file(parent, "lock", os.O_RDWR) as descriptor,
+    ):
+        try:
+            fcntl.flock(descriptor, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        except BlockingIOError as exc:
+            raise SessionError("session busy: another check or reset is running") from exc
+        # Release by closing the pinned descriptor, never by reopening/truncating its path.
+        yield