trap-cli 0.0.5__tar.gz → 0.0.7__tar.gz

{trap_cli-0.0.5 → trap_cli-0.0.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: trap-cli
-Version: 0.0.5
+Version: 0.0.7
 Summary: tp — non-invasive CLI testing framework for AI workflows. Submits results to trapstreet.run.
 Project-URL: Homepage, https://trapstreet.run
 Project-URL: Repository, https://github.com/trapstreet/trap

{trap_cli-0.0.5 → trap_cli-0.0.7}/src/trap/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.0.5'
-__version_tuple__ = version_tuple = (0, 0, 5)
+__version__ = version = '0.0.7'
+__version_tuple__ = version_tuple = (0, 0, 7)
 
 __commit_id__ = commit_id = None

{trap_cli-0.0.5 → trap_cli-0.0.7}/src/trap/auth/client.py

@@ -52,6 +52,15 @@ class ApiClient:
             resp.raise_for_status()
             return resp.json()
         except httpx.HTTPStatusError as e:
-            raise ApiError(f"http {e.response.status_code}: {e.response.text}") from None
+            raise ApiError(f"http {e.response.status_code}: {_error_detail(e.response)}") from None
         except httpx.RequestError as e:
             raise ApiError(f"connection error: {e}") from None
+
+
+def _error_detail(resp: httpx.Response) -> str:
+    """The server's JSON {error} message when present, else the raw body text."""
+    try:
+        error = resp.json().get("error")
+    except (ValueError, AttributeError):
+        return resp.text
+    return str(error) if error else resp.text

{trap_cli-0.0.5 → trap_cli-0.0.7}/src/trap/cli/__init__.py

@@ -17,9 +17,10 @@ from trap.display import CaseProgress, render_submit_result
 from trap.environment import EnvironmentDetector
 from trap.git_ops import GitOpsError, LocalRepo, ParsedGitUrl
 from trap.loader import ConfigError, TrapLoader, TraptaskLoader
-from trap.models import Provenance
-from trap.report import OutputFormat, ReportHandle, renderer_factory
+from trap.models import Provenance, ReportData
+from trap.report import OutputFormat, renderer_factory
 from trap.runner import TaskRunner
+from trap.workspace import SolutionIdentity, Workspace
 
 app = typer.Typer(help="AI prompt / agent / workflow / testing framework.")
 app.add_typer(auth_app, name="auth")
@@ -46,6 +47,22 @@ def _main(
     """AI prompt / agent / workflow / testing framework."""
 
 
+def _no_report(workspace: Workspace, error: FileNotFoundError) -> typer.Exit:
+    """Exit for a report miss, with advice matching the likely cause: an empty
+    workspace means the user never ran; existing runs under *other* solution keys
+    mean a cwd / --solution mismatch, where re-running would just miss again."""
+    msg = str(error)
+    if keys := workspace.solution_keys():
+        msg += (
+            "\nsolutions with runs in this workspace: "
+            + ", ".join(keys)
+            + "\ncheck that --solution (and the cwd) match the ones used for [bold]tp run[/bold]"
+        )
+    else:
+        msg += ". Run [bold]tp run[/bold] first."
+    return _die(msg)
+
+
 def _confirm_remote(url: str, *, trust: bool) -> None:
     """Gate trap's auto-download-and-run of a remote (git+ URL) source — the one place
     trap fetches and executes code the user may not have seen. Returns to proceed;
@@ -145,7 +162,7 @@ def run(
             help="Force-run the task's setup_cmd even when no remote pull brought new code.",
         ),
     ] = False,
-    workspace: Annotated[Path, typer.Option("--workspace", "-w")] = Path(".trap"),
+    workspace: Annotated[Path, typer.Option("--workspace", "-w")] = Path(Workspace.DEFAULT_DIRNAME),
     environment: Annotated[
         bool,
         typer.Option(
@@ -184,8 +201,8 @@ def run(
         task_binding = trap_yaml_loader.resolve_task(task)
         if ParsedGitUrl.looks_remote(task_binding.source):
             _confirm_remote(task_binding.source, trust=trust)
-        traptask_yaml_loader = TraptaskLoader.from_task(
-            task_binding, trap_yaml_loader.trap_dir, setup=setup_task
+        traptask_yaml_loader = TraptaskLoader.from_task_binding(
+            task_binding, trap_yaml_loader.trap_dir, setup=setup_task, workspace_root=workspace.resolve()
         )
     except (GitOpsError, ConfigError, subprocess.CalledProcessError) as e:
         raise _die(e) from None
@@ -204,14 +221,14 @@ def run(
 
     started_at_local = datetime.now()
     ts = started_at_local.isoformat(timespec="seconds")
-    report_handle = ReportHandle(workspace.resolve(), task_binding.alias, ts)
+    ws = Workspace(workspace.resolve(), SolutionIdentity.from_spec(solution).dirname, task_binding.alias)
 
     runner = TaskRunner(
         trap_config=trap_yaml_loader.config,
         trap_dir=trap_yaml_loader.trap_dir,
         traptask_config=traptask_yaml_loader.traptask,
         traptask_dir=traptask_yaml_loader.traptask_dir,
-        run_dir=report_handle.run_dir,
+        run_dir=ws.run_dir(ts),
         cost_enabled=cost,
     )
     prog_console = console if output == OutputFormat.rich else None
@@ -233,8 +250,8 @@ def run(
         except Exception:
             environment_info = None
 
-    report_data = report_handle.save(
-        case_results=case_results,
+    report_data = ReportData.from_run(
+        cases_results=case_results,
         trap_config=trap_yaml_loader.config,
         started_at_utc=started_at_local.astimezone(UTC),
         finished_at_utc=finished_at_utc,
@@ -242,7 +259,11 @@ def run(
         provenance=provenance,
         environment=environment_info,
     )
+    ws.save_as_report(ts, report_data)
     renderer_factory(output).render(report_data)
+    if output == OutputFormat.rich:
+        # Where the artifacts landed — the run id doubles as the `--run` handle.
+        console.print(f"[dim]run {ts} → {ws.report_json_path(ts)}[/dim]")
     # trap reports facts, not a verdict: a completed run exits 0 regardless of per-case
     # exit codes or scores (read the grader / report.json to gate CI). trap-level
     # failures (bad config, git errors) still exit non-zero via _die.
@@ -257,18 +278,18 @@ def report(
         typer.Option("--solution", help="Local solution path holding trap.yaml (default: cwd)."),
     ] = None,
     output: Annotated[OutputFormat, typer.Option("--output", "-o")] = OutputFormat.rich,
-    workspace: Annotated[Path, typer.Option("--workspace", "-w")] = Path(".trap"),
+    workspace: Annotated[Path, typer.Option("--workspace", "-w")] = Path(Workspace.DEFAULT_DIRNAME),
 ) -> None:
     """Display a report for a task (defaults to latest run)."""
     try:
         task_alias = TrapLoader.from_solution(solution).resolve_task(task).alias
     except (GitOpsError, ConfigError) as e:
         raise _die(e) from None
-    handle = ReportHandle(workspace.resolve(), task_alias, run)
+    ws = Workspace(workspace.resolve(), SolutionIdentity.from_spec(solution).dirname, task_alias)
     try:
-        report_data = handle.load()
-    except FileNotFoundError:
-        raise _die(f"no report at {handle.report_json_path}; run `tp run` first") from None
+        report_data = ws.load(run)
+    except FileNotFoundError as e:
+        raise _no_report(ws, e) from None
     renderer_factory(output).render(report_data)
 
 
@@ -285,7 +306,7 @@ def submit(
         str | None,
         typer.Option("--solution", help="Local solution path holding trap.yaml (default: cwd)."),
     ] = None,
-    workspace: Annotated[Path, typer.Option("--workspace", "-w")] = Path(".trap"),
+    workspace: Annotated[Path, typer.Option("--workspace", "-w")] = Path(Workspace.DEFAULT_DIRNAME),
     run: Annotated[str, typer.Option("--run", "-r", help="Which run to upload.")] = "latest",
     allow_unanchored: Annotated[
         bool,
@@ -298,8 +319,8 @@ def submit(
 ) -> None:
     """Upload a report.json to trapstreet.
 
-    Reads from the .trap/<task>/<run>/report.json workspace that `tp run`
-    populated.
+    Reads from the .trap/runs/<solution>/<task>/<run>/report.json workspace
+    that `tp run` populated.
     """
     stored = AuthStore().load()
     # priority: TRAPSTREET_URL env > stored > default
@@ -315,17 +336,17 @@ def submit(
         task_alias = TrapLoader.from_solution(solution).resolve_task(task).alias
     except (GitOpsError, ConfigError) as e:
         raise _die(e) from None
-    report_handle = ReportHandle(workspace.resolve(), task_alias, run)
+    ws = Workspace(workspace.resolve(), SolutionIdentity.from_spec(solution).dirname, task_alias)
     try:
-        report_data = report_handle.load()
-    except FileNotFoundError:
-        raise _die(f"no report at {report_handle.report_json_path}. Run [bold]tp run[/bold] first.") from None
+        report_data = ws.load(run)
+    except FileNotFoundError as e:
+        raise _no_report(ws, e) from None
     # Repeat the unanchored-provenance gate at upload time — the report records
     # what `tp run` saw, so the checkouts aren't re-probed here.
     _confirm_unanchored(
         report_data.provenance, allow=allow_unanchored or _env_truthy("TRAP_ALLOW_UNANCHORED")
     )
-    report_path = report_handle.report_json_path
+    report_path = ws.report_json_path(run)
 
     client = ApiClient(resolved_server, resolved_key)
     try:

{trap_cli-0.0.5 → trap_cli-0.0.7}/src/trap/display/submit.py

@@ -7,14 +7,17 @@ console = Console()
 
 
 def render_submit_result(resp_data: dict) -> None:
+    """Render a successful POST /api/submit response: {run: {id}, view_url}.
+
+    Success is decided by the HTTP status alone (ApiClient.submit raises on
+    non-2xx), so this only confirms the upload and points at the run page —
+    scores and case detail live there, not in the response."""
     run_obj = resp_data.get("run") or {}
-    passed = run_obj.get("passed")
+    console.print("[green]✓ submitted[/green]")
     table = Table.grid(padding=(0, 2))
     table.add_column(style="dim")
     table.add_column()
-    table.add_row("status", "[green]✓ passed[/green]" if passed else "[red]✗ failed[/red]")
-    table.add_row("run", f"[bold]{run_obj.get('id', '?')}[/bold]")
-    table.add_row("score", f"[cyan]{run_obj.get('total_score')}[/cyan]")
+    table.add_row("run_id", f"[bold]{run_obj.get('id', '?')}[/bold]")
     if view_url := resp_data.get("view_url"):
         table.add_row("url", f"[link={view_url}]{view_url}[/link]")
     console.print(table)

{trap_cli-0.0.5 → trap_cli-0.0.7}/src/trap/git_ops/url.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import re
 from dataclasses import dataclass
+from pathlib import PurePosixPath
 
 from trap.git_ops.base import GitOpsError
 
@@ -96,3 +97,17 @@ class ParsedGitUrl:
         if m:
             return f"https://{m.group(1)}/{m.group(2)}"
         return re.sub(r"\.git$", "", self.repo)  # https/http: drop trailing .git
+
+    @property
+    def dir_basename(self) -> str:
+        """Basename of the directory the URL addresses: the subdirectory when one
+        is set, else the repo."""
+        return PurePosixPath(self.subdirectory).name if self.subdirectory else self.basename
+
+    @property
+    def normalised_dir_url(self) -> str:
+        """Canonical, rev-independent address of the directory the URL points at:
+        ``normalised_url`` plus ``#<subdirectory>`` when one is set. The rev is
+        excluded on purpose — it can float without changing *which* directory
+        this is."""
+        return self.normalised_url + (f"#{self.subdirectory}" if self.subdirectory else "")

{trap_cli-0.0.5 → trap_cli-0.0.7}/src/trap/loader/trap_yaml.py

@@ -68,7 +68,7 @@ class TrapLoader:
         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`.
+        Mirrors `TraptaskLoader.from_task_binding`.
         """
         from trap.git_ops import GitOpsError, ParsedGitUrl, RemoteRepo
 

{trap_cli-0.0.5 → trap_cli-0.0.7}/src/trap/loader/traptask_yaml.py

@@ -10,6 +10,7 @@ from pydantic import ValidationError
 
 from trap.loader.errors import ConfigError
 from trap.models import TaskBinding, TraptaskCase, TraptaskConfig
+from trap.workspace import Workspace
 
 
 class TraptaskLoader:
@@ -41,13 +42,21 @@ class TraptaskLoader:
         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:
+    def from_task_binding(
+        cls,
+        task_binding: TaskBinding,
+        trap_dir: Path,
+        setup: bool = False,
+        workspace_root: Path = Path(Workspace.DEFAULT_DIRNAME),
+    ) -> 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).
+        A URL clones into `clone_to` (resolved against `trap_dir`, since it is the
+        solution author's config) or, when omitted, the workspace's hidden
+        `<workspace_root>/repos/<repo>` cache — the same root that holds run
+        artifacts; 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
@@ -56,17 +65,20 @@ class TraptaskLoader:
         """
         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())
+        if ParsedGitUrl.looks_remote(task_binding.source):
+            parsed = ParsedGitUrl.from_full_url(task_binding.source)
+            if task_binding.clone_to is not None:
+                dest = trap_dir / task_binding.clone_to
+            else:
+                dest = Workspace.clone_cache_dir(workspace_root, parsed.basename)
+            remote_repo = RemoteRepo(parsed, dest.resolve())
             is_local_changed = remote_repo.ensure()
             traptask_dir = remote_repo.local_dir
         else:
-            if task.clone_to is not None:
+            if task_binding.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()
+            traptask_dir = (trap_dir / task_binding.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

{trap_cli-0.0.5 → trap_cli-0.0.7}/src/trap/report/__init__.py

@@ -3,11 +3,10 @@ from __future__ import annotations
 import enum
 
 from trap.report.base import BaseRenderer
-from trap.report.handle import ReportHandle
 from trap.report.json import JsonRenderer
 from trap.report.rich import RichRenderer
 
-__all__ = ["BaseRenderer", "JsonRenderer", "OutputFormat", "ReportHandle", "RichRenderer", "renderer_factory"]
+__all__ = ["BaseRenderer", "JsonRenderer", "OutputFormat", "RichRenderer", "renderer_factory"]
 
 
 class OutputFormat(enum.StrEnum):

{trap_cli-0.0.5 → trap_cli-0.0.7}/src/trap/runner/task.py

@@ -1,7 +1,6 @@
 from __future__ import annotations
 
 from collections.abc import Callable, Iterable, Iterator
-from datetime import datetime
 from functools import cached_property
 from pathlib import Path
 from typing import Any
@@ -40,18 +39,6 @@ class TaskRunner:
         """The task's expected/ dir (traptask_dir / dirs.expected), resolved once on first use."""
         return (self.traptask_dir / self.traptask_config.dirs.expected).resolve()
 
-    def _update_latest(self) -> None:
-        latest = self.run_dir.parent / "latest"
-        if latest.is_symlink():
-            latest.unlink()
-        elif latest.exists():
-            # Path exists but isn't a symlink — likely an interrupted prior run
-            # or a sync tool that materialized the symlink as a real directory.
-            # Move it aside (non-destructive) so subsequent runs self-heal.
-            suffix = datetime.now().isoformat(timespec="microseconds")
-            latest.rename(latest.with_name(f"latest.broken.{suffix}"))
-        latest.symlink_to(self.run_dir.name)
-
     def _iter_cases(
         self,
         cases: Iterable[TraptaskCase],
@@ -98,5 +85,4 @@ class TaskRunner:
             # still completes and the report still saves).
             grader_metrics = GraderRunner(self, case_results).run()
 
-        self._update_latest()
         return case_results, grader_metrics

trap_cli-0.0.7/src/trap/workspace/__init__.py

@@ -0,0 +1,23 @@
+"""Workspace addressing: where a solution's runs live inside `.trap/`.
+
+Layout: ``<workspace>/runs/<solution-key>/<task_alias>/<run>/``.
+
+Two objects own this package's concerns: :class:`SolutionIdentity`
+(``identity.py``) derives which solution a run belongs to and projects it to a
+directory name (its ``dirname`` is the solution key), and :class:`Workspace`
+(``store.py``) answers queries and does report IO against one `.trap/` store,
+scoped to one (solution, task) pair fixed at construction. The key
+carries the
+run's *identity* inside the store, so ``latest`` is scoped per (solution, task)
+by construction — a cwd mismatch between ``tp run`` and ``tp submit`` degrades
+to a loud "not found" instead of silently reading another solution's report.
+Runs live under the ``runs/`` namespace so run storage never collides with
+sibling namespaces like ``repos/`` (the clone cache).
+"""
+
+from __future__ import annotations
+
+from trap.workspace.identity import SolutionIdentity
+from trap.workspace.store import Workspace
+
+__all__ = ["SolutionIdentity", "Workspace"]

trap_cli-0.0.7/src/trap/workspace/identity.py

@@ -0,0 +1,58 @@
+"""SolutionIdentity — the identity a solution's runs are stored under."""
+
+from __future__ import annotations
+
+import hashlib
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+from trap.git_ops import ParsedGitUrl
+
+_UNSAFE = re.compile(r"[^A-Za-z0-9._-]+")
+
+
+@dataclass(frozen=True)
+class SolutionIdentity:
+    """The identity a solution's runs are stored under: ``<readable>-<hash8>``.
+
+    ``readable`` is the solution's basename (never encodes path separators,
+    never leaks ``..``); ``ident`` is the full identity the hash disambiguates
+    same-named solutions by — the resolved absolute path, or the normalised
+    URL + subdirectory for a remote. Aliases of one solution (``./x``, ``x``,
+    an absolute path, a symlinked path) all derive the same key."""
+
+    readable: str
+    ident: str
+
+    @classmethod
+    def from_spec(cls, solution: str | None) -> SolutionIdentity:
+        """Derive the key from a ``--solution`` spec (local path or git+ URL)."""
+        if solution is not None and ParsedGitUrl.looks_remote(solution):
+            return cls._from_remote(ParsedGitUrl.from_full_url(solution))
+        return cls._from_local(solution)
+
+    @classmethod
+    def _from_remote(cls, parsed: ParsedGitUrl) -> SolutionIdentity:
+        # The URL is the stable identity — the clone dir can be moved (--clone-to)
+        # without changing which solution this is.
+        return cls(readable=parsed.dir_basename, ident=parsed.normalised_dir_url)
+
+    @classmethod
+    def _from_local(cls, solution: str | None) -> SolutionIdentity:
+        resolved = (Path.cwd() / (solution or ".")).resolve()
+        return cls(readable=resolved.name, ident=str(resolved))
+
+    @property
+    def dirname(self) -> str:
+        """The key as it appears on disk: the directory name under ``runs/``."""
+        return f"{self._safe_readable}-{self._digest}"
+
+    @property
+    def _safe_readable(self) -> str:
+        """`readable` reduced to dirname-safe characters, with a non-empty fallback."""
+        return _UNSAFE.sub("-", self.readable).strip("-.") or "solution"
+
+    @property
+    def _digest(self) -> str:
+        return hashlib.sha256(self.ident.encode()).hexdigest()[:8]

trap_cli-0.0.7/src/trap/workspace/store.py

@@ -0,0 +1,113 @@
+"""Workspace — one `.trap/` store and the queries it answers.
+
+``latest`` is a *derived* value — the newest timestamp-named run directory that
+holds a report, detected at every use. Nothing on disk records which run is
+latest, so there is no pointer to go stale.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from pathlib import Path
+
+from trap.models import ReportData
+
+
+class Workspace:
+    """One `.trap/` store, scoped to one (solution, task) pair.
+
+    A CLI invocation resolves its solution key and task alias once, so both are
+    fixed at construction time — they address one run *series*. Which run inside
+    the series to touch is a per-call choice, so ``run`` stays a parameter."""
+
+    DEFAULT_DIRNAME = ".trap"
+    RUNS_DIR = "runs"
+    REPOS_DIR = "repos"
+    REPORT_FILENAME = "report.json"
+
+    def __init__(self, root: Path, solution_key: str, task_alias: str) -> None:
+        self.root = root
+        self.solution_key = solution_key
+        self.task_alias = task_alias
+
+    @classmethod
+    def clone_cache_dir(cls, root: Path, repo_basename: str) -> Path:
+        """Where a remote task clones when no ``clone_to`` is given: the hidden
+        ``repos/`` cache inside the workspace at ``root`` — the same root that
+        holds ``runs/``, so the whole store lives in one place."""
+        return root / cls.REPOS_DIR / repo_basename
+
+    @property
+    def runs_root(self) -> Path:
+        return self.root / self.RUNS_DIR
+
+    @property
+    def solution_dir(self) -> Path:
+        """This solution's namespace inside the store."""
+        return self.runs_root / self.solution_key
+
+    @property
+    def solution_task_alias_dir(self) -> Path:
+        """Where this (solution, task) pair's runs live."""
+        return self.solution_dir / self.task_alias
+
+    def latest_run(self) -> str | None:
+        """The newest completed run for this (solution, task), or None when there is none.
+
+        Derived from the directory names at every call — stray symlinks and
+        non-run entries are ignored."""
+        task_dir = self.solution_task_alias_dir
+        if not task_dir.is_dir():
+            return None
+        runs = (path.name for path in task_dir.iterdir() if self._is_completed_run(path))
+        return max(runs, default=None)
+
+    def resolved_run(self, run: str) -> str:
+        """``"latest"`` resolves to the newest completed run; anything else names
+        a run directly (whether its report exists is ``assert_exists``'s concern).
+        Raises FileNotFoundError when there is no completed run to resolve
+        ``"latest"`` to."""
+        if run != "latest":
+            return run
+        latest = self.latest_run()
+        if latest is None:
+            raise FileNotFoundError(f"no completed runs in {self.solution_task_alias_dir}")
+        return latest
+
+    def run_dir(self, run: str) -> Path:
+        """One run's directory; ``run="latest"`` is resolved at every use."""
+        return self.solution_task_alias_dir / self.resolved_run(run)
+
+    def report_json_path(self, run: str) -> Path:
+        return self.run_dir(run) / self.REPORT_FILENAME
+
+    @classmethod
+    def _is_completed_run(cls, path: Path) -> bool:
+        """A run counts when its directory is named by an ISO timestamp and holds
+        a report — half-written directories from a crashed run never win."""
+        if path.is_symlink() or not path.is_dir():
+            return False
+        try:
+            datetime.fromisoformat(path.name)
+        except ValueError:
+            return False
+        return (path / cls.REPORT_FILENAME).is_file()
+
+    def solution_keys(self) -> list[str]:
+        """Solution keys with runs in this workspace — the self-help list for a miss."""
+        if not self.runs_root.is_dir():
+            return []
+        return sorted(path.name for path in self.runs_root.iterdir() if path.is_dir())
+
+    def save_as_report(self, run: str, data: ReportData) -> None:
+        """Write ``run``'s report; ``run`` must name a concrete run, never ``"latest"``."""
+        self.run_dir(run).mkdir(parents=True, exist_ok=True)
+        self.report_json_path(run).write_text(data.model_dump_json(indent=2))
+
+    def assert_exists(self, run: str) -> None:
+        if not self.report_json_path(run).exists():
+            raise FileNotFoundError(f"no report found in {self.run_dir(run)}")
+
+    def load(self, run: str) -> ReportData:
+        self.assert_exists(run)
+        return ReportData.model_validate_json(self.report_json_path(run).read_text())

trap_cli-0.0.5/src/trap/report/handle.py

@@ -1,54 +0,0 @@
-from __future__ import annotations
-
-from datetime import datetime
-from pathlib import Path
-from typing import Any
-
-from trap.models import CaseResult, Environment, Provenance, ReportData, TrapConfig
-
-_REPORT_FILENAME = "report.json"
-
-
-class ReportHandle:
-    def __init__(self, workspace: Path, task_alias: str, run: str) -> None:
-        self._workspace = workspace
-        self._task_alias = task_alias
-        self._run = run
-
-    @property
-    def run_dir(self) -> Path:
-        return self._workspace / self._task_alias / self._run
-
-    @property
-    def report_json_path(self) -> Path:
-        return self.run_dir / _REPORT_FILENAME
-
-    def save(
-        self,
-        trap_config: TrapConfig,
-        case_results: tuple[CaseResult, ...],
-        started_at_utc: datetime,
-        finished_at_utc: datetime,
-        provenance: Provenance,
-        grader_metrics: Any = None,
-        environment: Environment | None = None,
-    ) -> ReportData:
-        data = ReportData.from_run(
-            trap_config=trap_config,
-            provenance=provenance,
-            cases_results=case_results,
-            started_at_utc=started_at_utc,
-            finished_at_utc=finished_at_utc,
-            grader_metrics=grader_metrics,
-            environment=environment,
-        )
-        self.report_json_path.write_text(data.model_dump_json(indent=2))
-        return data
-
-    def assert_exists(self) -> None:
-        if not self.report_json_path.exists():
-            raise FileNotFoundError(f"no report found in {self.run_dir}")
-
-    def load(self) -> ReportData:
-        self.assert_exists()
-        return ReportData.model_validate_json(self.report_json_path.read_text())