trap-cli 0.0.1__py3-none-any.whl

trap/git_ops/rev.py

@@ -0,0 +1,119 @@
+from __future__ import annotations
+
+import re
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from pathlib import Path
+
+import git
+
+from trap.git_ops.base import GitOpsError, ProgressCallback
+
+# Each rev kind owns its full lifecycle — fresh clone and reconcile-existing —
+# so the behaviour for one kind reads top-to-bottom in one place rather than
+# being split across the clone and sync paths.
+
+
+class RevStrategy(ABC):
+    @classmethod
+    def for_rev(cls, rev: str | None) -> RevStrategy:
+        """Pick the strategy for a rev string (knowable without network)."""
+        if rev is None:
+            return DefaultBranch()
+        if re.fullmatch(r"[0-9a-f]{7,40}", rev):
+            return PinnedSha(rev)
+        return NamedRef(rev)
+
+    @abstractmethod
+    def clone(self, repo_url: str, dest: Path) -> None:
+        """Fresh clone of repo_url into dest, positioned at the desired rev."""
+
+    @abstractmethod
+    def reconcile(self, repo: git.Repo, root: Path, progress_func: ProgressCallback) -> bool:
+        """Verify/update an existing clone (remote already validated).
+
+        Returns True if local code changed (caller then auto-runs setup_cmd).
+        """
+
+
+class DefaultBranch(RevStrategy):
+    """No rev pinned — clone default branch; never auto-update an existing clone."""
+
+    def clone(self, repo_url: str, dest: Path) -> None:
+        git.Repo.clone_from(repo_url, dest)
+
+    def reconcile(self, repo: git.Repo, root: Path, progress_func: ProgressCallback) -> bool:
+        return False
+
+
+@dataclass(frozen=True)
+class PinnedSha(RevStrategy):
+    """Immutable SHA — clone then checkout; verify HEAD offline, never fetch."""
+
+    sha: str
+
+    def clone(self, repo_url: str, dest: Path) -> None:
+        repo = git.Repo.clone_from(repo_url, dest)
+        repo.git.checkout(self.sha)
+
+    def reconcile(self, repo: git.Repo, root: Path, progress_func: ProgressCallback) -> bool:
+        head_sha = repo.head.commit.hexsha
+        if not head_sha.startswith(self.sha):
+            raise GitOpsError(
+                f"rev mismatch at {root}:\n  declared: {self.sha}\n  HEAD:     {head_sha[: len(self.sha)]}"
+            )
+        return False
+
+
+@dataclass(frozen=True)
+class NamedRef(RevStrategy):
+    """Tag or branch — distinguished only after fetch: tags are immutable (error
+    on drift), branches fast-forward when behind."""
+
+    ref: str
+
+    def clone(self, repo_url: str, dest: Path) -> None:
+        git.Repo.clone_from(repo_url, dest, branch=self.ref, single_branch=True)
+
+    def reconcile(self, repo: git.Repo, root: Path, progress_func: ProgressCallback) -> bool:
+        head_sha = repo.head.commit.hexsha
+
+        if progress_func:
+            progress_func(f"fetching {root.name}...")
+        try:
+            repo.remotes.origin.fetch()
+        except git.GitCommandError as exc:
+            raise GitOpsError(f"git fetch failed:\n{exc.stderr.strip()}") from exc
+
+        declared_sha = self._resolve_sha(repo)
+        if declared_sha == head_sha:
+            return False  # already up to date
+
+        is_branch = any(r.remote_head == self.ref for r in repo.remotes.origin.refs)
+        if not is_branch:
+            raise GitOpsError(  # pragma: no cover - only a force-moved remote tag reaches here
+                f"rev mismatch at {root}:\n"
+                f"  declared tag: {self.ref} ({declared_sha[:8]})\n"
+                f"  HEAD:         {head_sha[:8]}"
+            )
+
+        if progress_func:
+            progress_func(f"updating {root.name} to {self.ref} ({declared_sha[:8]})...")
+        try:
+            repo.git.pull("--ff-only", "origin", self.ref)
+        except git.GitCommandError as exc:
+            raise GitOpsError(
+                f"cannot fast-forward {root} to origin/{self.ref}:\n"
+                f"{exc.stderr.strip()}\n"
+                f"Local branch has diverged. Delete {root} and re-run."
+            ) from exc
+        return True
+
+    def _resolve_sha(self, repo: git.Repo) -> str:
+        """Resolve the ref to a full commit SHA (call after fetch)."""
+        for candidate in [f"origin/{self.ref}", self.ref]:
+            try:
+                return repo.commit(candidate).hexsha
+            except git.BadName:  # pragma: no cover - defensive: a resolvable ref was just fetched
+                continue
+        raise GitOpsError(f"cannot resolve rev {self.ref!r}")  # pragma: no cover

trap/git_ops/url.py

@@ -0,0 +1,98 @@
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+from trap.git_ops.base import GitOpsError
+
+
+@dataclass(frozen=True)
+class ParsedGitUrl:
+    """A git URL split into its parts, for cloning a task/solution repo.
+
+    A user writes one string (in trap.yaml or `--solution`); this pulls it apart
+    into the URL to clone, an optional pinned rev, and an optional sub-path.
+
+        git+https://github.com/org/repo@v1.0#subdirectory=tasks/a
+        └──────── repo ───────┘ └rev┘ └──── subdirectory ────┘
+    """
+
+    repo: str  # the underlying git URL (git+ prefix stripped, no @rev, no #fragment)
+    rev: str | None  # branch / tag / SHA; None = default branch
+    subdirectory: str | None  # sub-path inside the repo; None = root
+
+    @staticmethod
+    def looks_remote(s: str) -> bool:
+        """True if `s` is a git remote URL (vs a local path).
+
+        A `scheme://…` URL (git+https, https, ssh, git, file) or scp shorthand
+        `user@host:path`. Local paths (./x, ../task, /abs, foo) have neither.
+        """
+        return "://" in s or bool(re.match(r"^[^/@]+@[^/:]+:", s))
+
+    @classmethod
+    def from_full_url(cls, url: str) -> ParsedGitUrl:
+        """Parse a git URL into (repo, rev, subdirectory).
+
+        Accepts any of these base forms — the `git+` prefix is optional:
+
+            git+https://github.com/org/repo
+            https://github.com/org/repo.git
+            ssh://git@github.com/org/repo
+            git@github.com:org/repo.git          (scp shorthand)
+
+        (Any `scheme://` works, so `file:///path/to/repo` also clones a local
+        repo — handy for tests/pinning, distinct from an in-place local path.)
+
+        Two optional suffixes work on every form:
+
+            @<rev>             pin a branch / tag / commit
+            #subdirectory=<p>  sub-path inside the repo holding the trap config
+
+        Example:
+
+            git+https://github.com/org/repo@v1.0#subdirectory=tasks/a
+            → repo="https://github.com/org/repo", rev="v1.0", subdirectory="tasks/a"
+
+        Raises GitOpsError if `url` is not a remote URL (see `looks_remote`).
+        """
+        if not cls.looks_remote(url):
+            raise GitOpsError(f"not a git URL: {url!r}")
+        rest = url[4:] if url.startswith("git+") else url
+
+        subdirectory: str | None = None
+        if "#" in rest:
+            rest, fragment = rest.split("#", 1)
+            for part in fragment.split("&"):
+                if part.startswith("subdirectory="):
+                    subdirectory = part[len("subdirectory=") :]
+
+        rev: str | None = None
+        # only look for @rev in the last path segment to avoid cutting user@host
+        if "@" in rest.split("/", 3)[-1]:
+            idx = rest.rfind("@")
+            rest, rev = rest[:idx], rest[idx + 1 :]
+
+        return cls(repo=rest, rev=rev, subdirectory=subdirectory)
+
+    @property
+    def basename(self) -> str:
+        """https://github.com/org/my-task.git  →  my-task"""
+        name = self.repo.rstrip("/").rsplit("/", 1)[-1]
+        return re.sub(r"\.git$", "", name)
+
+    @property
+    def normalised_url(self) -> str:
+        """`repo` as a canonical clickable https URL.
+
+        git@github.com:user/repo.git   → https://github.com/user/repo
+        ssh://git@gitlab.com/u/r       → https://gitlab.com/u/r
+        https://github.com/u/r.git     → https://github.com/u/r
+        """
+        m = re.match(r"^git@([^:]+):(.+?)(?:\.git)?$", self.repo)  # scp git@host:path
+        if m:
+            return f"https://{m.group(1)}/{m.group(2)}"
+        m = re.match(r"^ssh://git@([^/]+)/(.+?)(?:\.git)?$", self.repo)  # ssh:// form
+        if m:
+            return f"https://{m.group(1)}/{m.group(2)}"
+        return re.sub(r"\.git$", "", self.repo)  # https/http: drop trailing .git

trap/loader/__init__.py

@@ -0,0 +1,5 @@
+from .errors import ConfigError
+from .trap_yaml import TrapLoader
+from .traptask_yaml import TraptaskLoader
+
+__all__ = ["ConfigError", "TrapLoader", "TraptaskLoader"]

trap/loader/errors.py

@@ -0,0 +1,7 @@
+from __future__ import annotations
+
+
+class ConfigError(Exception):
+    """A trap.yaml / traptask.yaml that cannot be loaded — missing file, malformed
+    YAML, failed schema validation, an unknown task alias, or no tasks/cases. Carries a
+    user-facing message; the CLI maps it to a clean error (exit 2, no traceback)."""

trap/loader/trap_yaml.py

@@ -0,0 +1,99 @@
+# Loads trap.yaml (solution author's config) into TrapLoader.
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import yaml
+from pydantic import ValidationError
+
+from trap.loader.errors import ConfigError
+from trap.models import TaskBinding
+from trap.models.trap_yaml import TrapConfig
+
+if TYPE_CHECKING:
+    from trap.git_ops.base import ProgressCallback
+
+
+class TrapLoader:
+    """Loads trap.yaml (solution author's config)."""
+
+    def __init__(self, trap_yaml_path: Path) -> None:
+        self.trap_dir: Path = trap_yaml_path.resolve().parent
+        try:
+            text = trap_yaml_path.read_text()
+        except FileNotFoundError:
+            raise ConfigError(f"no trap.yaml at {trap_yaml_path}") from None
+        try:
+            data = yaml.safe_load(text)
+        except yaml.YAMLError as e:
+            raise ConfigError(f"invalid YAML in {trap_yaml_path}: {e}") from e
+        try:
+            self.config: TrapConfig = TrapConfig.model_validate(data)
+        except ValidationError as e:
+            raise ConfigError(f"invalid trap.yaml ({trap_yaml_path}):\n{e}") from e
+        self.tasks: dict[str, TaskBinding] = {
+            alias: task.model_copy(update={"alias": alias}) for alias, task in self.config.tasks.items()
+        }
+
+    def resolve_task(self, alias: str | None) -> TaskBinding:
+        """Return the task for `alias` (the `tasks:` map key), or the first task if None."""
+        if alias is None:
+            if not self.tasks:
+                raise ConfigError(f"trap.yaml in {self.trap_dir} defines no tasks")
+            alias = next(iter(self.tasks))
+        if alias not in self.tasks:
+            available = ", ".join(self.tasks) or "(none)"
+            raise ConfigError(f"task {alias!r} not found in trap.yaml; available: {available}")
+        return self.tasks[alias]
+
+    @classmethod
+    def from_solution(
+        cls,
+        solution: str | None,
+        clone_to: Path | None = None,
+        *,
+        allow_remote: bool = False,
+        setup: bool = False,
+        progress_func: ProgressCallback = None,
+    ) -> TrapLoader:
+        """Resolve a --solution spec to a loaded TrapLoader (relative to cwd).
+
+        None → ./trap.yaml.  Local path → <path>/trap.yaml.  git+ URL
+        (allow_remote only) → clone into ./<repo> (or clone_to) and load its
+        trap.yaml.  Raises GitOpsError on a git failure or a bad spec/flag
+        combo (caller maps it to a CLI error).
+
+        The solution's `setup_cmd` (in its trap.yaml, so it travels with the
+        solution) prepares the checkout. It auto-runs when a remote pull brought
+        new code, and otherwise only when `setup` is set (`tp run --setup-solution`).
+        Mirrors `TraptaskLoader.from_task`.
+        """
+        from trap.git_ops import GitOpsError, ParsedGitUrl, RemoteRepo
+
+        # Each branch only resolves where trap.yaml lives (cloning a remote on the
+        # way); the loader is built once and setup runs once, below.
+        cwd = Path.cwd()
+        is_local_changed = False
+        if solution is None:
+            trap_yaml_path = cwd / "trap.yaml"
+        elif ParsedGitUrl.looks_remote(solution):
+            if not allow_remote:
+                raise GitOpsError("solution must be a local path here, not a remote URL")
+            parsed = ParsedGitUrl.from_full_url(solution)
+            # clone_to given → there; omitted → visible ./<repo>
+            dest = clone_to or Path(parsed.basename)
+            remote_repo = RemoteRepo(parsed, (cwd / dest).resolve())
+            is_local_changed = remote_repo.ensure(progress_func=progress_func)
+            trap_yaml_path = remote_repo.local_dir / "trap.yaml"
+        else:
+            if clone_to is not None:
+                raise GitOpsError("--clone-to only applies to a remote (git URL) solution")
+            trap_yaml_path = cwd / solution / "trap.yaml"
+
+        loader = cls(trap_yaml_path)
+        if (is_local_changed or setup) and loader.config.setup_cmd:
+            # raises subprocess.CalledProcessError on non-zero exit
+            subprocess.run(loader.config.setup_cmd, shell=True, cwd=loader.trap_dir, check=True)
+        return loader

trap/loader/traptask_yaml.py

@@ -0,0 +1,85 @@
+# Loads traptask.yaml (task author's config) into TraptaskLoader.
+from __future__ import annotations
+
+import subprocess
+from collections.abc import Iterable
+from pathlib import Path
+
+import yaml
+from pydantic import ValidationError
+
+from trap.loader.errors import ConfigError
+from trap.models import TaskBinding, TraptaskCase, TraptaskConfig
+
+
+class TraptaskLoader:
+    """Loads traptask.yaml (task author's config) and resolves runtime paths."""
+
+    def __init__(self, traptask_yaml_path: Path) -> None:
+        self.traptask_dir: Path = traptask_yaml_path.resolve().parent
+        if traptask_yaml_path.exists():
+            try:
+                data = yaml.safe_load(traptask_yaml_path.read_text())
+            except yaml.YAMLError as e:
+                raise ConfigError(f"invalid YAML in {traptask_yaml_path}: {e}") from e
+            try:
+                self.traptask = TraptaskConfig.model_validate(data)
+            except ValidationError as e:
+                raise ConfigError(f"invalid traptask.yaml ({traptask_yaml_path}):\n{e}") from e
+        else:
+            self.traptask = self._discover(self.traptask_dir)
+
+    @staticmethod
+    def _discover(traptask_dir: Path) -> TraptaskConfig:
+        """Auto-build TraptaskConfig by scanning inputs/ when traptask.yaml is absent."""
+        inputs_dir = traptask_dir / "inputs"
+        if not inputs_dir.is_dir():
+            raise ConfigError(f"no traptask.yaml and no inputs/ directory in {traptask_dir}")
+        case_ids = sorted(p.name for p in inputs_dir.iterdir() if p.is_dir())
+        if not case_ids:
+            raise ConfigError(f"inputs/ in {traptask_dir} has no case subdirectories")
+        return TraptaskConfig(cases=tuple(TraptaskCase(id=case_id) for case_id in case_ids))
+
+    @classmethod
+    def from_task(cls, task: TaskBinding, trap_dir: Path, setup: bool = False) -> TraptaskLoader:
+        """Resolve traptask.yaml from a TaskBinding's source and the trap.yaml directory.
+
+        Mirrors `TrapLoader.from_solution`: `source` is a local path or a git+ URL.
+        A URL clones into `clone_to` (omitted → hidden cache .trap/repos/<repo>,
+        since the task is a dependency); a local path uses it in place and rejects
+        `clone_to`. Raises GitOpsError on a bad spec (caller maps it to a CLI error).
+
+        The task's `setup_cmd` (declared in its traptask.yaml, so it travels with the
+        task version) prepares the checkout. It auto-runs when a remote pull brought
+        new code, and otherwise only when `setup` is set (the `tp run --setup-task`
+        escape hatch covering pinned/up-to-date clones and local sources).
+        """
+        from trap.git_ops import GitOpsError, ParsedGitUrl, RemoteRepo
+
+        if ParsedGitUrl.looks_remote(task.source):
+            parsed = ParsedGitUrl.from_full_url(task.source)
+            dest = task.clone_to or Path(".trap") / "repos" / parsed.basename
+            remote_repo = RemoteRepo(parsed, (trap_dir / dest).resolve())
+            is_local_changed = remote_repo.ensure()
+            traptask_dir = remote_repo.local_dir
+        else:
+            if task.clone_to is not None:
+                raise GitOpsError("clone_to only applies to a remote (git URL) source")
+            is_local_changed = False
+            traptask_dir = (trap_dir / task.source).resolve()
+        loader = cls(traptask_dir / "traptask.yaml")
+        if (is_local_changed or setup) and loader.traptask.setup_cmd:
+            # raises subprocess.CalledProcessError on non-zero exit
+            subprocess.run(loader.traptask.setup_cmd, shell=True, cwd=loader.traptask_dir, check=True)
+        return loader
+
+    @property
+    def cases(self) -> tuple[TraptaskCase, ...]:
+        """Return all non-skipped cases."""
+        return tuple(c for c in self.traptask.cases if not c.skip)
+
+    def cases_with_tags(self, tags: Iterable[str] | None = None) -> tuple[TraptaskCase, ...]:
+        """Return non-skipped cases matching any of the specified tags, or all cases if tags is empty/None."""
+        if not (tag_set := set(tags or ())):
+            return self.cases
+        return tuple(c for c in self.cases if not tag_set.isdisjoint(c.tags))

trap/models/__init__.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+from .cost import CaseCost, ModelCost
+from .environment import Cpu, Environment
+from .provenance import GitProvenance, Provenance
+from .report import ReportData
+from .results import CaseResult
+from .trap_yaml import Profile, TaskBinding, TrapConfig
+from .traptask_yaml import (
+    DirsConfig,
+    GraderConfig,
+    JudgeConfig,
+    SubprocessConfig,
+    TraptaskCase,
+    TraptaskConfig,
+)
+
+__all__ = [
+    "CaseCost",
+    "CaseResult",
+    "Cpu",
+    "DirsConfig",
+    "Environment",
+    "GitProvenance",
+    "GraderConfig",
+    "JudgeConfig",
+    "ModelCost",
+    "Profile",
+    "Provenance",
+    "ReportData",
+    "SubprocessConfig",
+    "TaskBinding",
+    "TrapConfig",
+    "TraptaskCase",
+    "TraptaskConfig",
+]

trap/models/cost.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+from pydantic import BaseModel, computed_field
+
+
+class ModelCost(BaseModel):
+    provider: str
+    model: str | None = None
+    prompt_tokens: int = 0
+    completion_tokens: int = 0
+    cost_usd: float = 0.0
+    calls: int = 0
+
+
+class CaseCost(BaseModel):
+    by_model: list[ModelCost] = []
+
+    @computed_field
+    @property
+    def prompt_tokens(self) -> int:
+        return sum(u.prompt_tokens for u in self.by_model)
+
+    @computed_field
+    @property
+    def completion_tokens(self) -> int:
+        return sum(u.completion_tokens for u in self.by_model)
+
+    @computed_field
+    @property
+    def cost_usd(self) -> float:
+        return sum(u.cost_usd for u in self.by_model)
+
+    @computed_field
+    @property
+    def calls(self) -> int:
+        return sum(u.calls for u in self.by_model)

trap/models/environment.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+
+class Cpu(BaseModel):
+    """CPU identity. `model` is the human brand string (py-cpuinfo `brand_raw`),
+    which psutil does not expose."""
+
+    model: str | None = None
+    cores_physical: int | None = None
+    cores_logical: int | None = None
+
+
+class Environment(BaseModel):
+    """Machine runtime environment captured at `tp run` — a fastfetch-like subset
+    relevant to comparing runs across hosts. Every field is optional so a failed
+    probe degrades to None rather than aborting the run."""
+
+    os: str | None = None
+    kernel: str | None = None
+    arch: str | None = None
+    cpu: Cpu = Field(default_factory=Cpu)
+    memory_total_bytes: int | None = None

trap/models/provenance.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+
+class GitProvenance(BaseModel):
+    """Git origin of one checkout: {repo, commit}. Both None when the tree isn't a
+    clean, remote-backed git repo (see LocalRepo.provenance)."""
+
+    repo: str | None = None
+    commit: str | None = None
+
+
+class Provenance(BaseModel):
+    """The two checkouts that fully reproduce a run: the solution under test and the
+    task it ran against. Re-clone both at their commit and everything else (cmd,
+    judge, fixtures, ...) is recovered from the checkouts."""
+
+    solution: GitProvenance = Field(default_factory=GitProvenance)
+    task: GitProvenance = Field(default_factory=GitProvenance)

trap/models/report.py

@@ -0,0 +1,61 @@
+# Wire format for what `tp` writes to .trap/<task>/<ts>/report.json
+# and POSTs to the trapstreet `/api/submit` endpoint.
+#
+# Reference: trapstreet/docs/scoring-and-metrics.md "Upload protocol".
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from trap import __version__
+from trap.models.environment import Environment
+from trap.models.provenance import Provenance
+from trap.models.results import CaseResult
+from trap.models.trap_yaml import Profile, TrapConfig
+
+
+class ReportData(BaseModel):
+    """Top-level upload protocol envelope."""
+
+    # The (repo, commit) of both checkouts — the minimal seed to reproduce the run.
+    provenance: Provenance = Field(default_factory=Provenance)
+
+    cases_results: tuple[CaseResult, ...]
+    # Raw run-level grader output; None when no grader is configured.
+    grader_metrics: Any
+    started_at_utc: str
+    finished_at_utc: str
+
+    # Engine identity (model/framework). Self-reported from trap.yaml today, but the
+    # website consumes it from the report — never from trap.yaml directly — precisely
+    # because the source may change: a future version is expected to derive this by
+    # observing actual usage (e.g. the cost proxy) rather than trusting self-report.
+    # Routing it through the report keeps that swap invisible to downstream consumers.
+    profile: Profile = Field(default_factory=Profile)
+    # The trap build that produced this report (hatch-vcs version).
+    trap_version: str = __version__
+    # Host machine environment captured at run time; None when --no-environment.
+    environment: Environment | None = None
+
+    @classmethod
+    def from_run(
+        cls,
+        trap_config: TrapConfig,
+        cases_results: tuple[CaseResult, ...],
+        grader_metrics: Any,
+        started_at_utc: datetime,
+        finished_at_utc: datetime,
+        provenance: Provenance,
+        environment: Environment | None = None,
+    ) -> ReportData:
+        return cls(
+            provenance=provenance,
+            cases_results=cases_results,
+            grader_metrics=grader_metrics,
+            started_at_utc=started_at_utc.isoformat(timespec="seconds"),
+            finished_at_utc=finished_at_utc.isoformat(timespec="seconds"),
+            profile=trap_config.profile,
+            environment=environment,
+        )

trap/models/results.py

@@ -0,0 +1,17 @@
+# Runtime result models produced by judge and grader subprocesses.
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel
+
+from trap.models.cost import CaseCost
+
+
+class CaseResult(BaseModel):
+    case_id: str
+    exit_code: int = 0
+    duration: float = 0.0  # seconds
+    # any JSON-serializable value; trap does not interpret this, grader does
+    metrics: Any
+    cost: CaseCost | None = None