patchground 0.1.0__py3-none-any.whl

patchground/cli/sessions.py

@@ -0,0 +1,195 @@
+"""Thin local-session commands; only structured results, never sandbox output."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from pathlib import Path
+from typing import Annotated, Any
+
+import typer
+from rich.console import Console
+from rich.text import Text
+from typer.core import TyperCommand
+
+from patchground.cli.consent import emit_required, with_consent
+from patchground.cli.render import (
+    EXIT_ERROR,
+    EXIT_FAILED,
+    EXIT_INTERRUPTED,
+    EXIT_OK,
+    emit,
+    emit_error,
+)
+from patchground.packs.models import ConsentRequired
+from patchground.sessions import (
+    CheckResult,
+    ResetResult,
+    SessionError,
+    SessionStatus,
+    StartedSession,
+    check_session,
+    reset_session,
+    session_status,
+    start_session,
+)
+from patchground.sessions.models import SnapshotStatus
+
+Result = StartedSession | CheckResult | SessionStatus | ResetResult
+JsonOption = Annotated[bool, typer.Option("--json", help="Print one JSON document.")]
+SessionOption = Annotated[Path | None, typer.Option("--session", help="Select a session path.")]
+
+
+class SessionCommand(TyperCommand):
+    """Keep argument-parsing failures inside the session JSON output contract."""
+
+    def parse_args(self, ctx: Any, args: list[str]) -> list[str]:
+        json_mode = "--json" in args
+        try:
+            return super().parse_args(ctx, args)
+        except typer.Exit:
+            raise
+        except Exception as exc:
+            if not json_mode:
+                raise
+            emit_error("environment", "invalid session command arguments", True)
+            raise typer.Exit(EXIT_ERROR) from exc
+
+
+def _human(console: Console, result: Result) -> None:
+    if isinstance(result, StartedSession):
+        console.print(Text(f"started {result.challenge_id}"))
+        if result.pack is not None:
+            console.print(Text(f"unofficial pack: {result.pack.name} @ {result.pack.commit}"))
+        console.print(Text(str(result.workspace)))
+        if result.history is not None:
+            _history(console, result.history)
+        console.print(Text(result.ticket))
+        console.print(Text("Next steps:", style="bold"))
+        console.print(Text(f"  cd {result.workspace}"))
+        console.print(Text("  pgnd check     run the checks, including hidden ones"))
+        console.print(Text("  pgnd hint      reveal the next authored hint"))
+        console.print(Text("  pgnd submit    finish with a verified-outcomes report"))
+        console.print(Text("Outside the workspace, add --session " + str(result.session) + "."))
+    elif isinstance(result, ResetResult):
+        console.print(Text(f"reset {result.challenge_id}; timer and history preserved"))
+    elif isinstance(result, SessionStatus):
+        console.print(Text(f"session {result.challenge_id}: {result.state}"))
+        if result.timer:
+            console.print(
+                Text(f"elapsed {int(result.elapsed_seconds)}s / {result.timebox_minutes} minutes")
+            )
+        else:
+            console.print(Text("timer off"))
+        console.print(Text(f"last check: {result.last_outcome or 'not run'}"))
+        if result.last_check is not None:
+            _human(console, result.last_check)
+    else:
+        console.print(Text(f"check: {result.outcome.value}"))
+        for test in result.tests:
+            console.print(Text(f"{test.status.value}  {test.id}"))
+        console.print(Text("  ".join(f"{key}: {value}" for key, value in result.counts.items())))
+        if result.limit is not None:
+            console.print(Text(f"limit exceeded: {result.limit}"))
+        if not result.passed:
+            console.print(
+                Text(
+                    "Test output is not shown. To see visible-test details, run your test command "
+                    "with: pgnd run -- <command>",
+                    style="dim",
+                )
+            )
+        if result.history is not None:
+            _history(console, result.history)
+
+
+def _history(console: Console, history: SnapshotStatus) -> None:
+    console.print(Text(f"history: {history.state}"))
+    if history.detail:
+        console.print(
+            Text(f"{history.detail}; optional checkpoints only, checks are unaffected", style="dim")
+        )
+
+
+def _invoke(call: Callable[[], Result], json_mode: bool) -> None:
+    try:
+        result = call()
+    except ConsentRequired as exc:
+        emit_required(exc, json_mode)
+        raise typer.Exit(EXIT_ERROR) from exc
+    except SessionError as exc:
+        emit_error("environment", str(exc), json_mode)
+        raise typer.Exit(EXIT_ERROR) from exc
+    except KeyboardInterrupt as exc:
+        emit_error("interrupted", "interrupted", json_mode)
+        raise typer.Exit(EXIT_INTERRUPTED) from exc
+    except Exception as exc:
+        # Exception text can itself contain untrusted logs or hidden source.
+        emit_error("internal", "session operation failed unexpectedly", json_mode)
+        raise typer.Exit(EXIT_ERROR) from exc
+    emit(result.model_dump(mode="json"), lambda console: _human(console, result), json_mode)
+    raise typer.Exit(
+        EXIT_FAILED if isinstance(result, CheckResult) and not result.passed else EXIT_OK
+    )
+
+
+def start(
+    path: Annotated[
+        str, typer.Argument(help="Local folder, installed ID or pack-name:challenge-id.")
+    ],
+    yes: Annotated[
+        bool, typer.Option("--yes", help="Approve the exact selected pack revision.")
+    ] = False,
+    no_timer: Annotated[bool, typer.Option("--no-timer")] = False,
+    no_history: Annotated[
+        bool, typer.Option("--no-history", help="Disable checkpoint history.")
+    ] = False,
+    json_mode: JsonOption = False,
+) -> None:
+    """Start a challenge: a built-in ID, a local folder or an approved installed pack ID."""
+
+    def operation(approved: bool, identity: str | None) -> StartedSession:
+        return start_session(
+            path,
+            timer=not no_timer,
+            history=not no_history,
+            yes=approved,
+            expected_identity=identity,
+        )
+
+    _invoke(lambda: with_consent(operation, yes=yes, json_mode=json_mode), json_mode)
+
+
+def check(session: SessionOption = None, json_mode: JsonOption = False) -> None:
+    """Run checks on a temporary copy of the selected workspace."""
+    _invoke(lambda: check_session(session), json_mode)
+
+
+def reset(
+    session: SessionOption = None,
+    yes: Annotated[bool, typer.Option("--yes", help="Confirm destructive reset.")] = False,
+    json_mode: JsonOption = False,
+) -> None:
+    """Restore starting files, preserving Git and credential-pattern entries."""
+    if not yes:
+        if json_mode:
+            emit_error("environment", "reset requires --yes in JSON mode", True)
+            raise typer.Exit(EXIT_ERROR)
+        try:
+            confirmed = typer.confirm(
+                "Discard workspace edits and ordinary added files? "
+                "Git, credential-pattern files, timer and history are preserved. "
+                "Filesystem errors may leave a partial reset",
+                default=False,
+            )
+        except (KeyboardInterrupt, EOFError, typer.Abort) as exc:
+            emit_error("interrupted", "reset cancelled", False)
+            raise typer.Exit(EXIT_INTERRUPTED) from exc
+        if not confirmed:
+            emit_error("interrupted", "reset cancelled", False)
+            raise typer.Exit(EXIT_INTERRUPTED)
+    _invoke(lambda: reset_session(session), json_mode)
+
+
+def status(session: SessionOption = None, json_mode: JsonOption = False) -> None:
+    """Show the selected session without requiring Docker."""
+    _invoke(lambda: session_status(session), json_mode)

patchground/cli/validate.py

@@ -0,0 +1,117 @@
+"""`pgnd validate`: run challenge verification and render the per-step report."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+from rich.console import Console
+from rich.text import Text
+
+from patchground.cli.consent import emit_required, with_consent
+from patchground.cli.render import (
+    EXIT_ERROR,
+    EXIT_FAILED,
+    EXIT_INTERRUPTED,
+    EXIT_OK,
+    emit,
+    emit_error,
+    progress,
+)
+from patchground.packs.builtin import is_builtin_path
+from patchground.packs.execution import resolve_challenge
+from patchground.packs.models import ConsentRequired
+from patchground.verify import (
+    StepStatus,
+    ValidationReport,
+    VerifyEnvironmentError,
+    validate_challenge,
+)
+
+_MARKS = {
+    StepStatus.PASSED: ("✓", "green"),
+    StepStatus.FAILED: ("✗", "red"),
+    StepStatus.NOT_RUN: ("-", "dim"),
+}
+
+
+def validate(
+    path: Annotated[
+        str, typer.Argument(help="Local folder, installed ID or pack-name:challenge-id.")
+    ],
+    json_mode: Annotated[
+        bool, typer.Option("--json", help="Print one JSON document on stdout.")
+    ] = False,
+    yes: Annotated[
+        bool, typer.Option("--yes", help="Approve the exact selected pack revision.")
+    ] = False,
+    no_write: Annotated[
+        bool, typer.Option("--no-write", help="Do not write verification.json on success.")
+    ] = False,
+) -> None:
+    """Verify outcomes, determinism and supported editable-test tampering resistance."""
+    # The bundled catalog is part of the installed distribution and is never written to.
+    write = not no_write and not _is_builtin(path)
+    try:
+        with progress(json_mode) as notify:
+            report = with_consent(
+                lambda approved, identity: validate_challenge(
+                    path,
+                    write=write,
+                    progress=notify,
+                    yes=approved,
+                    expected_identity=identity,
+                ),
+                yes=yes,
+                json_mode=json_mode,
+            )
+    except ConsentRequired as exc:
+        emit_required(exc, json_mode)
+        raise typer.Exit(EXIT_ERROR) from exc
+    except VerifyEnvironmentError as exc:
+        emit_error("environment", str(exc), json_mode)
+        raise typer.Exit(EXIT_ERROR) from exc
+    except KeyboardInterrupt as exc:
+        emit_error("interrupted", "interrupted", json_mode)
+        raise typer.Exit(EXIT_INTERRUPTED) from exc
+    except Exception as exc:  # last resort: never a traceback, never confused with "invalid"
+        emit_error("internal", "validation failed unexpectedly", json_mode)
+        raise typer.Exit(EXIT_ERROR) from exc
+    emit(report.to_dict(), lambda console: _human(console, report), json_mode)
+    raise typer.Exit(EXIT_OK if report.valid else EXIT_FAILED)
+
+
+def _is_builtin(reference: str) -> bool:
+    try:
+        return is_builtin_path(resolve_challenge(reference).path)
+    except Exception:  # resolution problems are reported by validation itself
+        return False
+
+
+def _human(console: Console, report: ValidationReport) -> None:
+    width = max(len(step.name.value) for step in report.steps)
+    for step in report.steps:
+        mark, style = _MARKS[step.status]
+        line = Text()
+        line.append(f"{mark} ", style=style)
+        line.append(step.name.value.ljust(width), style="bold")
+        line.append(f"  {step.detail}")
+        console.print(line)
+        for issue_line in step.issue_lines:
+            console.print(Text(f"    {issue_line}"))
+        for note in step.notes:
+            console.print(Text(f"    {note}", style="dim"))
+        if step.log_tail:
+            for log_line in step.log_tail.splitlines():
+                console.print(Text(f"    | {log_line}", style="dim"))
+    if report.verification_file is not None:
+        console.print(Text(f"wrote {report.verification_file}", style="dim"))
+    if report.removed_verification_file is not None:
+        console.print(Text(f"removed stale {report.removed_verification_file}", style="dim"))
+    failed = report.failed_step
+    if report.valid:
+        console.print(Text("valid", style="bold green"))
+    elif failed is not None:
+        console.print(Text(f"invalid: failed at step {failed.value}", style="bold red"))
+    else:  # pragma: no cover - every report has a passed or failed step
+        console.print(Text("invalid", style="bold red"))

patchground/packs/__init__.py

@@ -0,0 +1,23 @@
+"""patchground.packs — see SPEC.md in this folder."""
+
+from patchground.packs.discovery import (
+    ChallengeDetails,
+    ChallengeSummary,
+    DiscoveryError,
+    DiscoveryFilters,
+    DiscoveryResult,
+    InvalidChallenge,
+    discover_challenges,
+    show_challenge,
+)
+
+__all__ = [
+    "ChallengeDetails",
+    "ChallengeSummary",
+    "DiscoveryError",
+    "DiscoveryFilters",
+    "DiscoveryResult",
+    "InvalidChallenge",
+    "discover_challenges",
+    "show_challenge",
+]

patchground/packs/builtin.py

@@ -0,0 +1,53 @@
+"""Curated challenges shipped inside the CLI distribution.
+
+They are first-party content, installed together with the code that runs them, so they keep local
+behaviour: no pack registry, no consent prompt. A bare ID falls back to them only after local
+folders and installed packs.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+import patchground
+from patchground.spec.models import SLUG_PATTERN
+
+_CATALOG = "catalog"
+
+
+def builtin_root() -> Path | None:
+    """The bundled catalog of a wheel, or ``examples/`` when running from a source checkout."""
+    package = Path(patchground.__file__).resolve().parent
+    candidates = [package / _CATALOG]
+    if package.parent.name == "src":
+        candidates.append(package.parent.parent / "examples")
+    for candidate in candidates:
+        if candidate.is_dir() and not candidate.is_symlink():
+            return candidate
+    return None
+
+
+def builtin_challenge(reference: str) -> Path | None:
+    """The bundled folder for a bare challenge ID, if one exists."""
+    if not re.fullmatch(SLUG_PATTERN, reference):
+        return None
+    root = builtin_root()
+    if root is None:
+        return None
+    folder = root / reference
+    if folder.is_symlink() or not (folder / "challenge.yaml").is_file():
+        return None
+    return folder
+
+
+def is_builtin_path(path: Path) -> bool:
+    """Whether ``path`` lies inside the bundled catalog (never written to)."""
+    root = builtin_root()
+    if root is None:
+        return False
+    try:
+        path.resolve().relative_to(root.resolve())
+    except (OSError, ValueError):
+        return False
+    return True

patchground/packs/discovery.py

@@ -0,0 +1,285 @@
+"""Local challenge discovery for ``list`` and ``show``: read-only metadata, never execution.
+
+Discovery looks at a directory the user names (default: the current one) and its *immediate*
+children only. A child is a candidate when it contains a ``challenge.yaml`` entry. Each candidate is
+validated with :func:`patchground.spec.load_challenge`; valid ones become summaries and invalid ones
+are reported with their problems instead of being hidden. Symlinked children are reported but never
+followed. Nothing is built, run, installed, remembered, or granted trust here.
+
+The output never contains the reference solution, hidden checks, hints text, or the test command:
+only manifest metadata and, for ``show``, the ticket the user would see anyway.
+"""
+
+from __future__ import annotations
+
+import os
+import stat
+from collections.abc import Iterable
+from pathlib import Path
+
+from pydantic import BaseModel, ConfigDict
+
+from patchground.spec import (
+    AIPolicy,
+    ChallengeManifest,
+    ChallengeType,
+    Difficulty,
+    ManifestError,
+    load_challenge,
+)
+
+CHALLENGE_MANIFEST = "challenge.yaml"
+TICKET_FILE = "TICKET.md"
+MAX_TICKET_BYTES = 256 * 1024
+"""Tickets are short prose; anything larger is reported instead of read."""
+
+
+class DiscoveryError(Exception):
+    """The requested directory or path cannot be examined at all (an environment problem)."""
+
+
+class _Result(BaseModel):
+    model_config = ConfigDict(frozen=True)
+
+
+class DiscoveryFilters(_Result):
+    """Optional ``list`` filters; all given filters must match (AND). Text matches ignore case."""
+
+    type: ChallengeType | None = None
+    lang: str | None = None
+    difficulty: Difficulty | None = None
+    tag: str | None = None
+
+    def matches(self, manifest: ChallengeManifest) -> bool:
+        if self.type is not None and manifest.type is not self.type:
+            return False
+        if self.difficulty is not None and manifest.difficulty is not self.difficulty:
+            return False
+        if self.lang is not None and not _contains(manifest.languages, self.lang):
+            return False
+        return self.tag is None or _contains(manifest.tags, self.tag)
+
+
+class ChallengeSummary(_Result):
+    """Public metadata of one valid challenge."""
+
+    id: str
+    path: str
+    title: str
+    version: str
+    type: ChallengeType
+    summary: str
+    languages: tuple[str, ...]
+    tags: tuple[str, ...]
+    difficulty: Difficulty
+    timebox_minutes: int
+    ai_policy: AIPolicy
+
+
+class InvalidChallenge(_Result):
+    """A candidate folder that could not be loaded; ``issues`` are file:line problems."""
+
+    name: str
+    path: str
+    issues: tuple[str, ...]
+
+
+class DiscoveryResult(_Result):
+    """Result of ``list``: valid matches plus every invalid candidate (filters never hide them)."""
+
+    directory: str
+    filters: DiscoveryFilters
+    challenges: tuple[ChallengeSummary, ...]
+    invalid: tuple[InvalidChallenge, ...]
+
+
+class ChallengeDetails(_Result):
+    """Result of ``show``: metadata and ticket when valid, problems otherwise."""
+
+    path: str
+    valid: bool
+    challenge: ChallengeSummary | None = None
+    author: str | None = None
+    content_license: str | None = None
+    provenance: str | None = None
+    hint_count: int | None = None
+    services: tuple[str, ...] = ()
+    ticket: str | None = None
+    issues: tuple[str, ...] = ()
+
+
+def _contains(values: Iterable[str], wanted: str) -> bool:
+    folded = wanted.strip().casefold()
+    return any(value.casefold() == folded for value in values)
+
+
+def _summary(manifest: ChallengeManifest, shown: str) -> ChallengeSummary:
+    return ChallengeSummary(
+        id=manifest.id,
+        path=shown,
+        title=manifest.title,
+        version=manifest.version,
+        type=manifest.type,
+        summary=manifest.summary,
+        languages=tuple(manifest.languages),
+        tags=tuple(manifest.tags),
+        difficulty=manifest.difficulty,
+        timebox_minutes=manifest.timebox_minutes,
+        ai_policy=manifest.ai_policy,
+    )
+
+
+def _regular_file_problem(folder: Path, name: str) -> str | None:
+    """Why ``folder/name`` is not a plain regular file (symlinks are not followed)."""
+    try:
+        mode = (folder / name).lstat().st_mode
+    except FileNotFoundError:
+        return f"{name}: not found"
+    except OSError:
+        return f"{name}: cannot be read"
+    if stat.S_ISLNK(mode):
+        return f"{name}: is a symlink; challenge files must be regular files"
+    if not stat.S_ISREG(mode):
+        return f"{name}: must be a regular file"
+    return None
+
+
+def _load(folder: Path) -> tuple[ChallengeManifest | None, tuple[str, ...]]:
+    """Validate ``folder`` without executing anything. Returns the manifest or its problems."""
+    for name in (CHALLENGE_MANIFEST, TICKET_FILE):
+        problem = _regular_file_problem(folder, name)
+        if problem is not None:
+            return None, (problem,)
+    try:
+        challenge = load_challenge(folder)
+    except ManifestError as exc:
+        return None, tuple(
+            f"{issue.file.name}:{issue.line or 1}: invalid challenge manifest or layout"
+            for issue in exc.issues
+        )
+    except OSError:
+        return None, ("challenge folder cannot be read",)
+    return challenge.manifest, ()
+
+
+def _read_ticket(folder: Path) -> tuple[str | None, str | None]:
+    """Read ``TICKET.md`` without following a symlink; returns ``(text, problem)``."""
+    path = folder / TICKET_FILE
+    flags = os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK
+    try:
+        fd = os.open(path, flags)
+    except OSError:
+        return None, f"{TICKET_FILE}: cannot be read safely"
+    try:
+        info = os.fstat(fd)
+        if not stat.S_ISREG(info.st_mode):
+            return None, f"{TICKET_FILE}: must be a regular file"
+        if info.st_size > MAX_TICKET_BYTES:
+            return None, f"{TICKET_FILE}: larger than {MAX_TICKET_BYTES} bytes"
+        with os.fdopen(fd, "rb") as handle:
+            fd = -1
+            data = handle.read(MAX_TICKET_BYTES + 1)
+    except OSError:
+        return None, f"{TICKET_FILE}: cannot be read"
+    finally:
+        if fd >= 0:
+            os.close(fd)
+    if len(data) > MAX_TICKET_BYTES:
+        return None, f"{TICKET_FILE}: larger than {MAX_TICKET_BYTES} bytes"
+    try:
+        return data.decode("utf-8"), None
+    except UnicodeDecodeError:
+        return None, f"{TICKET_FILE}: not valid UTF-8"
+
+
+def _require_directory(path: Path, what: str) -> None:
+    try:
+        is_dir = path.is_dir()
+    except OSError:
+        is_dir = False
+    if not is_dir:
+        raise DiscoveryError(f"{what} '{path}' does not exist or is not a directory")
+
+
+def discover_challenges(
+    directory: Path | None = None, filters: DiscoveryFilters | None = None
+) -> DiscoveryResult:
+    """List challenge folders directly inside ``directory`` (default: the current directory).
+
+    Only immediate children are examined; nothing is followed recursively. A symlinked child is
+    reported as invalid when it points at a folder, and never read through. Raises
+    ``DiscoveryError`` when ``directory`` itself is missing, not a directory, or unreadable.
+    """
+    base = Path(directory) if directory is not None else Path()
+    active = filters or DiscoveryFilters()
+    _require_directory(base, "directory")
+    try:
+        entries = sorted(os.scandir(base), key=lambda entry: entry.name)
+    except OSError as exc:
+        raise DiscoveryError(f"directory '{base}' cannot be read") from exc
+
+    challenges: list[ChallengeSummary] = []
+    invalid: list[InvalidChallenge] = []
+    for entry in entries:
+        child = base / entry.name
+        shown = str(child)
+        try:
+            if entry.is_symlink():
+                if entry.is_dir(follow_symlinks=True):
+                    invalid.append(
+                        InvalidChallenge(
+                            name=entry.name,
+                            path=shown,
+                            issues=("is a symlink; discovery does not follow symlinked folders",),
+                        )
+                    )
+                continue
+            if not entry.is_dir(follow_symlinks=False):
+                continue
+            os.lstat(child / CHALLENGE_MANIFEST)
+        except FileNotFoundError:
+            continue
+        except OSError:
+            invalid.append(
+                InvalidChallenge(name=entry.name, path=shown, issues=("folder cannot be read",))
+            )
+            continue
+        manifest, issues = _load(child)
+        if manifest is None:
+            invalid.append(InvalidChallenge(name=entry.name, path=shown, issues=issues))
+        elif active.matches(manifest):
+            challenges.append(_summary(manifest, shown))
+    return DiscoveryResult(
+        directory=str(base),
+        filters=active,
+        challenges=tuple(challenges),
+        invalid=tuple(invalid),
+    )
+
+
+def show_challenge(path: Path) -> ChallengeDetails:
+    """Describe one local challenge folder: safe metadata and its ticket, never secrets.
+
+    Invalid folders yield ``valid=False`` with their problems. Raises ``DiscoveryError`` when
+    ``path`` is missing or not a directory.
+    """
+    folder = Path(path)
+    _require_directory(folder, "challenge folder")
+    shown = str(folder)
+    manifest, issues = _load(folder)
+    if manifest is None:
+        return ChallengeDetails(path=shown, valid=False, issues=issues)
+    ticket, problem = _read_ticket(folder)
+    if problem is not None:
+        return ChallengeDetails(path=shown, valid=False, issues=(problem,))
+    return ChallengeDetails(
+        path=shown,
+        valid=True,
+        challenge=_summary(manifest, shown),
+        author=manifest.author.name,
+        content_license=manifest.content_license,
+        provenance=manifest.provenance.value,
+        hint_count=len(manifest.hints),
+        services=tuple(manifest.environment.services),
+        ticket=ticket,
+    )