patchground 0.1.0__py3-none-any.whl

patchground/cli/doctor.py

@@ -0,0 +1,249 @@
+"""`pgnd doctor`: diagnose engine, Git and session-disk readiness with exact fixes.
+
+Probe only: never builds, pulls or runs a challenge, and never prints raw engine errors.
+"""
+
+from __future__ import annotations
+
+import sys
+from dataclasses import dataclass
+from enum import StrEnum
+from typing import Annotated, Any
+
+import typer
+from rich.console import Console
+from rich.text import Text
+
+from patchground.cli.render import EXIT_ERROR, EXIT_INTERRUPTED, EXIT_OK, emit, emit_error
+from patchground.sandbox import EngineProbe, EngineProblem, probe_engine
+from patchground.sessions.diagnostics import (
+    DiskProbe,
+    DiskProblem,
+    GitProbe,
+    GitProblem,
+    probe_disk,
+    probe_git,
+)
+
+
+class CheckStatus(StrEnum):
+    OK = "ok"
+    FAILED = "failed"
+
+
+@dataclass(frozen=True)
+class DoctorCheck:
+    name: str  # "engine" | "git" | "disk"
+    status: CheckStatus
+    detail: str
+    problem: str | None = None
+    fix: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "name": self.name,
+            "status": self.status.value,
+            "detail": self.detail,
+            "problem": self.problem,
+            "fix": self.fix,
+        }
+
+
+@dataclass(frozen=True)
+class DoctorReport:
+    checks: tuple[DoctorCheck, ...]
+
+    @property
+    def healthy(self) -> bool:
+        return all(check.status is CheckStatus.OK for check in self.checks)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"healthy": self.healthy, "checks": [check.to_dict() for check in self.checks]}
+
+
+def _platform() -> str:
+    if sys.platform == "darwin":
+        return "macos"
+    if sys.platform.startswith("win"):
+        return "windows"
+    return "linux"
+
+
+_WINDOWS = (
+    "Patchground runs on Windows through WSL2: install Docker Desktop with the WSL2 backend, "
+    "then run pgnd inside your WSL2 distribution"
+)
+_ENGINE_FIXES: dict[EngineProblem, dict[str, str]] = {
+    EngineProblem.NOT_RUNNING: {
+        "macos": "Install and start Docker Desktop (or run `podman machine start` for Podman)",
+        "linux": "Install Docker Engine and start it: `sudo systemctl start docker` "
+        "(for Podman: `systemctl --user start podman.socket` and set DOCKER_HOST to its socket)",
+        "windows": _WINDOWS,
+    },
+    EngineProblem.PERMISSION: {
+        "macos": "Restart Docker Desktop; if it persists, check the socket's owner in "
+        "Docker Desktop's settings",
+        "linux": "Add yourself to the docker group: `sudo usermod -aG docker $USER`, "
+        "then log out and back in",
+        "windows": _WINDOWS,
+    },
+    EngineProblem.TIMEOUT: {
+        "macos": "The engine is not answering: restart Docker Desktop and retry",
+        "linux": "The engine is not answering: `sudo systemctl restart docker` and retry",
+        "windows": _WINDOWS,
+    },
+    EngineProblem.MISCONFIGURED: {
+        "macos": "Check DOCKER_HOST and `docker context ls`; unset DOCKER_HOST to use the default",
+        "linux": "Check DOCKER_HOST and `docker context ls`; unset DOCKER_HOST to use the default",
+        "windows": _WINDOWS,
+    },
+    EngineProblem.UNHEALTHY: {
+        "macos": "The engine returned an error: restart Docker Desktop and retry",
+        "linux": "The engine returned an error: `sudo systemctl restart docker` and retry",
+        "windows": _WINDOWS,
+    },
+}
+_GIT_FIXES: dict[str, str] = {
+    "macos": "Install Git: `xcode-select --install` (or `brew install git`)",
+    "linux": "Install Git with your package manager, e.g. `sudo apt install git`",
+    "windows": "Install Git inside your WSL2 distribution, e.g. `sudo apt install git`",
+}
+
+
+def _gib(value: int) -> str:
+    return f"{value / 1024**3:.1f} GiB"
+
+
+def engine_check(probe: EngineProbe, platform: str) -> DoctorCheck:
+    if probe.reachable:
+        version = f" {probe.version}" if probe.version else ""
+        api = f" (API {probe.api_version})" if probe.api_version else ""
+        return DoctorCheck("engine", CheckStatus.OK, f"{probe.engine or 'Docker'}{version}{api}")
+    problem = probe.problem or EngineProblem.UNHEALTHY
+    details = {
+        EngineProblem.NOT_RUNNING: "container engine not reachable (not installed or not running)",
+        EngineProblem.PERMISSION: "permission denied on the container engine socket",
+        EngineProblem.TIMEOUT: "container engine did not answer in time",
+        EngineProblem.MISCONFIGURED: "container engine connection is misconfigured",
+        EngineProblem.UNHEALTHY: "container engine answered with an error",
+    }
+    return DoctorCheck(
+        "engine",
+        CheckStatus.FAILED,
+        details[problem],
+        problem.value,
+        _ENGINE_FIXES[problem][platform],
+    )
+
+
+def git_check(probe: GitProbe, platform: str) -> DoctorCheck:
+    if probe.available:
+        return DoctorCheck("git", CheckStatus.OK, f"git {probe.version}")
+    problem = probe.problem or GitProblem.UNUSABLE
+    if problem is GitProblem.MISSING:
+        return DoctorCheck(
+            "git", CheckStatus.FAILED, "git not found on PATH", problem.value, _GIT_FIXES[platform]
+        )
+    return DoctorCheck(
+        "git",
+        CheckStatus.FAILED,
+        "git was found but `git --version` failed",
+        problem.value,
+        "Reinstall Git, then check that `git --version` works in a new terminal",
+    )
+
+
+def disk_check(probe: DiskProbe) -> DoctorCheck:
+    minimum = _gib(probe.minimum_bytes)
+    if probe.ok and probe.free_bytes is not None:
+        return DoctorCheck(
+            "disk",
+            CheckStatus.OK,
+            f"{_gib(probe.free_bytes)} free for sessions at {probe.location} "
+            f"(baseline {minimum}; images may need more)",
+        )
+    problem = probe.problem or DiskProblem.UNREADABLE
+    if problem is DiskProblem.LOW_SPACE and probe.free_bytes is not None:
+        return DoctorCheck(
+            "disk",
+            CheckStatus.FAILED,
+            f"only {_gib(probe.free_bytes)} free at {probe.location}; baseline is {minimum}",
+            problem.value,
+            f"Free at least {minimum} on the disk holding {probe.location}; "
+            "review files before deleting them",
+        )
+    if problem is DiskProblem.INVALID_SETTING:
+        return DoctorCheck(
+            "disk",
+            CheckStatus.FAILED,
+            f"{probe.location} is set but is not an absolute path",
+            problem.value,
+            f"Set {probe.location} to an absolute directory path, or unset it to use "
+            "~/patchground/sessions",
+        )
+    if problem is DiskProblem.NOT_WRITABLE:
+        return DoctorCheck(
+            "disk",
+            CheckStatus.FAILED,
+            f"cannot create sessions at {probe.location}",
+            problem.value,
+            f"Make {probe.location} (or its nearest existing parent) a writable directory",
+        )
+    return DoctorCheck(
+        "disk",
+        CheckStatus.FAILED,
+        f"cannot inspect the disk at {probe.location}",
+        problem.value,
+        f"Check that {probe.location} or a parent directory exists and is readable",
+    )
+
+
+def run_doctor() -> DoctorReport:
+    """Assemble every check; each probe reports its own failure instead of raising."""
+    platform = _platform()
+    return DoctorReport(
+        (
+            engine_check(probe_engine(), platform),
+            git_check(probe_git(), platform),
+            disk_check(probe_disk()),
+        )
+    )
+
+
+_MARKS = {CheckStatus.OK: ("✓", "green"), CheckStatus.FAILED: ("✗", "red")}
+
+
+def _human(console: Console, report: DoctorReport) -> None:
+    width = max(len(check.name) for check in report.checks)
+    for check in report.checks:
+        mark, style = _MARKS[check.status]
+        line = Text()
+        line.append(f"{mark} ", style=style)
+        line.append(check.name.ljust(width), style="bold")
+        line.append(f"  {check.detail}")
+        console.print(line)
+        if check.fix:
+            console.print(Text(f"    fix: {check.fix}"))
+    if report.healthy:
+        console.print(Text("ready", style="bold green"))
+    else:
+        failed = sum(check.status is CheckStatus.FAILED for check in report.checks)
+        console.print(Text(f"not ready: {failed} check(s) failed", style="bold red"))
+
+
+def doctor(
+    json_mode: Annotated[
+        bool, typer.Option("--json", help="Print one JSON document on stdout.")
+    ] = False,
+) -> None:
+    """Check the container engine, Git and disk space, and print the exact fix for each failure."""
+    try:
+        report = run_doctor()
+    except KeyboardInterrupt as exc:
+        emit_error("interrupted", "interrupted", json_mode)
+        raise typer.Exit(EXIT_INTERRUPTED) from exc
+    except Exception as exc:  # never a traceback or raw message; still one JSON document
+        emit_error("internal", f"doctor failed unexpectedly ({type(exc).__name__})", 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.healthy else EXIT_ERROR)

patchground/cli/packs.py

@@ -0,0 +1,142 @@
+"""Pinned-pack management; all source/consent/storage decisions belong to packs."""
+
+from collections.abc import Callable
+from typing import Annotated
+
+import typer
+from rich.console import Console
+from rich.text import Text
+
+from patchground.cli.consent import emit_required, literal, with_consent
+from patchground.cli.render import EXIT_ERROR, EXIT_FAILED, EXIT_INTERRUPTED, emit, emit_error
+from patchground.cli.sessions import JsonOption, SessionCommand
+from patchground.packs.models import (
+    ConsentRequired,
+    PackError,
+    PackInfo,
+    PackListing,
+    PackRemoval,
+    PackUpdateResult,
+)
+from patchground.packs.registry import add_pack, list_packs, remove_pack, update_pack
+
+app = typer.Typer(
+    no_args_is_help=True, help="Manage pinned challenge packs without automatic execution."
+)
+YesOption = Annotated[bool, typer.Option("--yes", help="Explicitly approve this operation.")]
+Result = PackInfo | PackListing | PackRemoval | PackUpdateResult
+
+
+def _info(console: Console, info: PackInfo) -> None:
+    pack = info.pack
+    console.print(
+        Text(
+            f"{pack.name} {pack.version} @ {pack.commit}  "
+            f"{'active' if info.active else 'cached'}  unofficial  "
+            f"{'consented' if info.consented else 'consent required before execution'}"
+        )
+    )
+    console.print(Text(f"source: {literal(pack.source)}"))
+
+
+def _human(console: Console, result: Result) -> None:
+    if isinstance(result, PackInfo):
+        _info(console, result)
+    elif isinstance(result, PackListing):
+        if not result.packs and not result.invalid:
+            console.print(Text("No packs installed."))
+        for info in result.packs:
+            _info(console, info)
+        for problem in result.invalid:
+            console.print(Text(f"invalid: {literal(problem.name)}: {literal(problem.reason)}"))
+    elif isinstance(result, PackRemoval):
+        console.print(
+            Text(
+                f"removed {result.name}: {result.removed_versions} cached versions; "
+                "sessions preserved"
+            )
+        )
+    else:
+        console.print(Text("updated" if result.changed else "unchanged"))
+        _info(console, result.current)
+
+
+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 PackError as exc:
+        emit_error("environment", str(exc), json_mode)
+        raise typer.Exit(EXIT_ERROR) from exc
+    except (KeyboardInterrupt, EOFError, typer.Abort) as exc:
+        emit_error("interrupted", "pack operation interrupted; inspect current state", json_mode)
+        raise typer.Exit(EXIT_INTERRUPTED) from exc
+    except Exception as exc:
+        emit_error("internal", "pack 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)
+    if isinstance(result, PackListing) and result.invalid:
+        raise typer.Exit(EXIT_FAILED)
+
+
+@app.command("add", cls=SessionCommand)
+def add(
+    source: Annotated[str, typer.Argument(help="Public HTTPS URL or local Git repository.")],
+    ref: Annotated[str, typer.Option("--ref", help="Branch, tag or commit to pin.")] = "HEAD",
+    json_mode: JsonOption = False,
+) -> None:
+    """Install committed files; never build or run the pack."""
+    _invoke(lambda: add_pack(source, ref=ref), json_mode)
+
+
+@app.command("list", cls=SessionCommand)
+def list_installed_packs(json_mode: JsonOption = False) -> None:
+    """Show installed revisions and their consent state without execution."""
+    _invoke(list_packs, json_mode)
+
+
+@app.command("update", cls=SessionCommand)
+def update(
+    name: str,
+    ref: Annotated[str | None, typer.Option("--ref", help="Replace the tracked revision.")] = None,
+    yes: YesOption = False,
+    json_mode: JsonOption = False,
+) -> None:
+    """Review changes before activating a new immutable revision."""
+    _invoke(
+        lambda: with_consent(
+            lambda approved, identity: update_pack(
+                name, ref=ref, yes=approved, expected_identity=identity
+            ),
+            yes=yes,
+            json_mode=json_mode,
+        ),
+        json_mode,
+    )
+
+
+@app.command("remove", cls=SessionCommand)
+def remove(name: str, yes: YesOption = False, json_mode: JsonOption = False) -> None:
+    """Remove cached revisions and future-start consent, never existing sessions."""
+
+    def operation() -> PackRemoval:
+        if yes:
+            return remove_pack(name, yes=True)
+        if json_mode:
+            raise PackError("pack remove requires --yes in JSON mode")
+        info = next(
+            (item for item in list_packs().packs if item.pack.name == name and item.active), None
+        )
+        if info is None:
+            raise PackError("pack is not installed")
+        if not typer.confirm(
+            f"Remove {info.pack.name}, its cached revisions and future-start consent? "
+            "Existing sessions are preserved",
+            default=False,
+        ):
+            raise KeyboardInterrupt
+        return remove_pack(name, yes=True, expected_identity=info.pack.identity)
+
+    _invoke(operation, json_mode)

patchground/cli/practice.py

@@ -0,0 +1,141 @@
+"""Practice commands: bounded diagnostics, authored hints and read-only local browsing."""
+
+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.render import EXIT_ERROR, EXIT_FAILED, EXIT_INTERRUPTED, emit, emit_error
+from patchground.cli.sessions import JsonOption, SessionOption
+from patchground.sessions import SessionError
+from patchground.sessions.history import history_for_session
+from patchground.sessions.models import HistoryResult
+from patchground.sessions.practice import (
+    CommandRunResult,
+    HintResult,
+    SessionsList,
+    list_sessions,
+    reveal_hint,
+    run_session_command,
+)
+
+Result = HintResult | SessionsList | CommandRunResult | HistoryResult
+
+
+class RunCommand(TyperCommand):
+    """Keep flags after -- literal and never echo command arguments in parse errors."""
+
+    def parse_args(self, ctx: Any, args: list[str]) -> list[str]:
+        options = args[: args.index("--")] if "--" in args else args
+        try:
+            if "--" not in args and "--help" not in options:
+                raise ValueError("missing separator")
+            return super().parse_args(ctx, args)
+        except typer.Exit:
+            raise
+        except Exception as exc:
+            emit_error(
+                "environment", "use run [options] -- <command> [arguments]", "--json" in options
+            )
+            raise typer.Exit(EXIT_ERROR) from exc
+
+
+def _display_path(path: Path) -> str:
+    try:
+        return "~/" + path.relative_to(Path.home()).as_posix()
+    except ValueError:
+        return str(path)
+
+
+def _human(console: Console, result: Result) -> None:
+    if isinstance(result, HintResult):
+        if result.exhausted and result.total == 0:
+            console.print(Text("This challenge has no authored hints."))
+        elif result.exhausted:
+            console.print(Text(f"No more authored hints (all {result.total} revealed)."))
+        else:
+            console.print(Text(f"Hint {result.index}: {result.hint}"))
+            console.print(Text(f"{result.remaining} remaining"))
+    elif isinstance(result, SessionsList):
+        if result.root is not None:
+            console.print(
+                Text(
+                    f"Every attempt in {_display_path(result.root)} "
+                    "(set PATCHGROUND_SESSIONS_DIR to keep a separate set)",
+                    style="dim",
+                )
+            )
+        if not result.sessions:
+            console.print(Text("No sessions found."))
+        for item in result.sessions:
+            console.print(
+                Text(
+                    f"{item.challenge_id}  {item.state}  {item.last_outcome or 'not checked'}  "
+                    f"{_display_path(item.session)}"
+                )
+            )
+        for invalid in result.invalid:
+            console.print(Text(f"invalid: {_display_path(invalid.session)}"))
+    elif isinstance(result, CommandRunResult):
+        console.print(Text("Command output tail (up to 64 KiB; container edits are discarded):"))
+        console.print(Text(result.output_tail))
+        console.print(Text(f"exit: {result.exit_code}; limit: {result.limit or 'none'}"))
+    else:
+        console.print(Text(f"history: {result.availability}"))
+        for snapshot in result.snapshots:
+            console.print(
+                Text(
+                    f"{snapshot.ts.isoformat()}  {snapshot.kind}  {snapshot.commit[:12]}  "
+                    f"{snapshot.check_outcome or ''}"
+                )
+            )
+
+
+def _invoke(call: Callable[[], Result], json_mode: bool) -> None:
+    try:
+        result = call()
+    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", "practice operation interrupted", json_mode)
+        raise typer.Exit(EXIT_INTERRUPTED) from exc
+    except Exception as exc:
+        emit_error("internal", "practice 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)
+    failed = (isinstance(result, SessionsList) and bool(result.invalid)) or (
+        isinstance(result, CommandRunResult) and (result.exit_code != 0 or result.limit is not None)
+    )
+    if failed:
+        raise typer.Exit(EXIT_FAILED)
+
+
+def hint(session: SessionOption = None, json_mode: JsonOption = False) -> None:
+    """Reveal the next authored hint without running code."""
+    _invoke(lambda: reveal_hint(session), json_mode)
+
+
+def sessions(json_mode: JsonOption = False) -> None:
+    """List local attempts without selecting one or running Docker."""
+    _invoke(list_sessions, json_mode)
+
+
+def history(session: SessionOption = None, json_mode: JsonOption = False) -> None:
+    """Read privacy-filtered private checkpoint history; never restore files."""
+    _invoke(lambda: history_for_session(session), json_mode)
+
+
+def run(
+    argv: Annotated[list[str], typer.Argument(help="Container command arguments after --.")],
+    session: SessionOption = None,
+    json_mode: JsonOption = False,
+) -> None:
+    """Run a diagnostic command in a disposable container, without hidden checks."""
+    _invoke(lambda: run_session_command(argv, session), json_mode)

patchground/cli/render.py

@@ -0,0 +1,58 @@
+"""Shared output: every command renders one result either as Rich text or as one JSON document."""
+
+from __future__ import annotations
+
+import json
+import sys
+from collections.abc import Callable, Iterator
+from contextlib import contextmanager
+from typing import Any
+
+from rich.console import Console
+from rich.text import Text
+
+EXIT_OK = 0
+EXIT_FAILED = 1
+EXIT_ERROR = 2
+EXIT_INTERRUPTED = 130
+
+
+def stdout_console() -> Console:
+    return Console(soft_wrap=True, highlight=False)
+
+
+def stderr_console() -> Console:
+    return Console(stderr=True, soft_wrap=True, highlight=False)
+
+
+def emit(
+    result_for_json: dict[str, Any], human: Callable[[Console], None], json_mode: bool
+) -> None:
+    """Write ``result_for_json`` as the single JSON document on stdout, or call ``human``."""
+    if json_mode:
+        sys.stdout.write(json.dumps(result_for_json, indent=2, ensure_ascii=True) + "\n")
+        sys.stdout.flush()
+    else:
+        human(stdout_console())
+
+
+def emit_error(kind: str, message: str, json_mode: bool) -> None:
+    """Report an error that stopped the command (JSON on stdout, or text on stderr)."""
+    if json_mode:
+        emit({"error": {"kind": kind, "message": message}}, lambda _console: None, True)
+    else:
+        stderr_console().print(Text(f"error: {message}", style="bold red"))
+
+
+@contextmanager
+def progress(json_mode: bool) -> Iterator[Callable[[str], None]]:
+    """Yield a callback that shows progress on stderr in human mode (and does nothing in JSON)."""
+    if json_mode:
+        yield lambda _message: None
+        return
+    console = stderr_console()
+    if not console.is_terminal:
+        yield lambda message: console.print(Text(f"{message}…", style="dim"))
+        return
+    with console.status("starting…") as status:
+        yield lambda message: status.update(f"{message}…")

patchground/cli/reports.py

@@ -0,0 +1,53 @@
+"""Submit and read immutable local outcomes, never AI judgments."""
+
+from collections.abc import Callable
+
+import typer
+from rich.console import Console
+from rich.text import Text
+
+from patchground.cli.render import EXIT_ERROR, EXIT_FAILED, EXIT_INTERRUPTED, emit, emit_error
+from patchground.cli.sessions import JsonOption, SessionOption
+from patchground.report.models import VerifiedReport
+from patchground.report.render import render_markdown
+from patchground.report.workflow import saved_report, submit_session
+from patchground.sessions import SessionError
+
+
+def _invoke(call: Callable[[], VerifiedReport], json_mode: bool, *, submitting: bool) -> None:
+    try:
+        result = call()
+    except SessionError as exc:
+        emit_error("environment", str(exc), json_mode)
+        raise typer.Exit(EXIT_ERROR) from exc
+    except KeyboardInterrupt as exc:
+        message = (
+            "submission interrupted; retry submit to inspect its state"
+            if submitting
+            else "report read interrupted"
+        )
+        emit_error("interrupted", message, json_mode)
+        raise typer.Exit(EXIT_INTERRUPTED) from exc
+    except Exception as exc:
+        emit_error("internal", "report operation failed unexpectedly", json_mode)
+        raise typer.Exit(EXIT_ERROR) from exc
+
+    def human(console: Console) -> None:
+        console.print(Text(render_markdown(result, terminal=True)))
+        if submitting:
+            console.print(Text("Attempt complete. Read this report again with: pgnd report"))
+            console.print(Text("Try another challenge: pgnd list --builtin"))
+
+    emit(result.model_dump(mode="json"), human, json_mode)
+    if submitting and not result.checks.passed:
+        raise typer.Exit(EXIT_FAILED)
+
+
+def submit(session: SessionOption = None, json_mode: JsonOption = False) -> None:
+    """Finalize this attempt with fresh checks and an immutable verified-outcomes report."""
+    _invoke(lambda: submit_session(session), json_mode, submitting=True)
+
+
+def report(session: SessionOption = None, json_mode: JsonOption = False) -> None:
+    """Read the saved final report without Docker or rerunning checks."""
+    _invoke(lambda: saved_report(session), json_mode, submitting=False)