trap-cli 0.0.6__tar.gz → 0.0.8__tar.gz

{trap_cli-0.0.6 → trap_cli-0.0.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: trap-cli
-Version: 0.0.6
+Version: 0.0.8
 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.6 → trap_cli-0.0.8}/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.6'
-__version_tuple__ = version_tuple = (0, 0, 6)
+__version__ = version = '0.0.8'
+__version_tuple__ = version_tuple = (0, 0, 8)
 
 __commit_id__ = commit_id = None

{trap_cli-0.0.6 → trap_cli-0.0.8}/src/trap/cli/__init__.py

@@ -13,13 +13,13 @@ from trap import __version__
 from trap.auth import DEFAULT_SERVER, ApiClient, ApiError, AuthStore
 from trap.cli._auth import auth_app
 from trap.cli._console import _die, _env_truthy, console, err_console
-from trap.display import CaseProgress, render_submit_result
+from trap.display import CaseProgress, OutputFormat, render_submit_result, renderer_factory
 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.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 +46,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;
@@ -103,14 +119,19 @@ def _confirm_unanchored(provenance: Provenance, *, allow: bool) -> None:
 
 @app.command()
 def run(
-    task: Annotated[str | None, typer.Argument()] = None,
     solution: Annotated[
         str | None,
-        typer.Option("--solution", help="Solution to run: a local path or a git+ URL (default: cwd)."),
+        typer.Argument(help="Solution to run: a local path or a git+ URL (default: cwd)."),
     ] = None,
+    task: Annotated[
+        str | None,
+        typer.Option("--task", help="Task alias from trap.yaml (default: the first task)."),
+    ] = None,
+    workspace: Annotated[Path, typer.Option("--workspace", "-w")] = Path(Workspace.DEFAULT_DIRNAME),
+    output: Annotated[OutputFormat, typer.Option("--output", "-o")] = OutputFormat.rich,
     clone_to: Annotated[
         Path | None,
-        typer.Option("--clone-to", help="Where to clone a git+ URL --solution (default: ./<repo>)."),
+        typer.Option("--clone-to", help="Where to clone a git+ URL SOLUTION (default: ./<repo>)."),
     ] = None,
     trust_remote: Annotated[
         bool,
@@ -129,7 +150,6 @@ def run(
         ),
     ] = False,
     tags: Annotated[list[str] | None, typer.Option("--tag", "-t")] = None,
-    output: Annotated[OutputFormat, typer.Option("--output", "-o")] = OutputFormat.rich,
     fail_fast: Annotated[bool, typer.Option("--fail-fast")] = False,
     setup_solution: Annotated[
         bool,
@@ -145,7 +165,6 @@ 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"),
     environment: Annotated[
         bool,
         typer.Option(
@@ -163,11 +182,11 @@ def run(
 ) -> None:
     """Run a task against a solution.
 
-    --solution is the solution to run: a local path, or a git+ URL to clone
-    into ./<repo> (or --clone-to). Omit it to use the trap.yaml in the cwd.
+    SOLUTION is a local path, or a git+ URL to clone into ./<repo> (or
+    --clone-to). Omit it to use the trap.yaml in the cwd.
     """
     # Gate trap's auto-download-and-run of any remote source before it happens — once
-    # for a remote --solution, once for a remote task source (resolved from trap.yaml).
+    # for a remote SOLUTION, once for a remote task source (resolved from trap.yaml).
     trust = trust_remote or _env_truthy("TRAP_TRUST_REMOTE")
     if solution is not None and ParsedGitUrl.looks_remote(solution):
         _confirm_remote(solution, trust=trust)
@@ -184,8 +203,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 +223,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 +252,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 +261,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.
@@ -250,43 +273,47 @@ def run(
 
 @app.command()
 def report(
-    task: Annotated[str | None, typer.Argument()] = None,
-    run: Annotated[str, typer.Argument()] = "latest",
     solution: Annotated[
         str | None,
-        typer.Option("--solution", help="Local solution path holding trap.yaml (default: cwd)."),
+        typer.Argument(help="Local solution path holding trap.yaml (default: cwd)."),
+    ] = None,
+    task: Annotated[
+        str | None,
+        typer.Option("--task", help="Task alias from trap.yaml (default: the first task)."),
     ] = None,
+    run: Annotated[str, typer.Option("--run", "-r", help="Which run to display.")] = "latest",
+    workspace: Annotated[Path, typer.Option("--workspace", "-w")] = Path(Workspace.DEFAULT_DIRNAME),
     output: Annotated[OutputFormat, typer.Option("--output", "-o")] = OutputFormat.rich,
-    workspace: Annotated[Path, typer.Option("--workspace", "-w")] = Path(".trap"),
 ) -> 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)
 
 
 @app.command()
 def submit(
+    solution: Annotated[
+        str | None,
+        typer.Argument(help="Local solution path holding trap.yaml (default: cwd)."),
+    ] = None,
     task: Annotated[
         str | None,
-        typer.Argument(
-            help="Task name (defaults to first task in trap.yaml). "
+        typer.Option(
+            "--task",
+            help="Task alias from trap.yaml (default: the first task). "
             "Used as both the local run dir and the trapstreet task_id.",
         ),
     ] = None,
-    solution: Annotated[
-        str | None,
-        typer.Option("--solution", help="Local solution path holding trap.yaml (default: cwd)."),
-    ] = None,
-    workspace: Annotated[Path, typer.Option("--workspace", "-w")] = Path(".trap"),
     run: Annotated[str, typer.Option("--run", "-r", help="Which run to upload.")] = "latest",
+    workspace: Annotated[Path, typer.Option("--workspace", "-w")] = Path(Workspace.DEFAULT_DIRNAME),
     allow_unanchored: Annotated[
         bool,
         typer.Option(
@@ -298,8 +325,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 +342,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.8/src/trap/display/__init__.py

@@ -0,0 +1,19 @@
+from trap.display.progress import CaseProgress
+from trap.display.report import (
+    BaseRenderer,
+    JsonRenderer,
+    OutputFormat,
+    RichRenderer,
+    renderer_factory,
+)
+from trap.display.submit import render_submit_result
+
+__all__ = [
+    "BaseRenderer",
+    "CaseProgress",
+    "JsonRenderer",
+    "OutputFormat",
+    "RichRenderer",
+    "render_submit_result",
+    "renderer_factory",
+]

trap_cli-0.0.6/src/trap/report/rich.py → trap_cli-0.0.8/src/trap/display/report.py

@@ -1,6 +1,10 @@
+"""Report renderers: turn a ReportData into terminal output (rich table or JSON)."""
+
 from __future__ import annotations
 
+import enum
 import json
+import sys
 
 from rich import box
 from rich.console import Console
@@ -10,7 +14,21 @@ from rich.table import Table
 from rich.text import Text
 
 from trap.models import CaseResult, ReportData
-from trap.report.base import BaseRenderer
+
+
+class OutputFormat(enum.StrEnum):
+    rich = "rich"
+    json = "json"
+
+
+class BaseRenderer:
+    def render(self, data: ReportData) -> None:
+        raise NotImplementedError
+
+
+class JsonRenderer(BaseRenderer):
+    def render(self, data: ReportData) -> None:
+        sys.stdout.write(data.model_dump_json(indent=2) + "\n")
 
 
 class RichRenderer(BaseRenderer):
@@ -114,3 +132,7 @@ class RichRenderer(BaseRenderer):
     def render(self, data: ReportData) -> None:
         self.console.print(self._build_summary(data))
         self.console.print(self._build_table(data))
+
+
+def renderer_factory(fmt: OutputFormat) -> BaseRenderer:
+    return {OutputFormat.rich: RichRenderer, OutputFormat.json: JsonRenderer}[fmt]()

{trap_cli-0.0.6 → trap_cli-0.0.8}/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.6 → trap_cli-0.0.8}/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.6 → trap_cli-0.0.8}/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.6 → trap_cli-0.0.8}/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.8/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.8/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.8/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.6/src/trap/display/__init__.py

@@ -1,4 +0,0 @@
-from trap.display.progress import CaseProgress
-from trap.display.submit import render_submit_result
-
-__all__ = ["CaseProgress", "render_submit_result"]

trap_cli-0.0.6/src/trap/report/__init__.py

@@ -1,19 +0,0 @@
-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"]
-
-
-class OutputFormat(enum.StrEnum):
-    rich = "rich"
-    json = "json"
-
-
-def renderer_factory(fmt: OutputFormat) -> BaseRenderer:
-    return {OutputFormat.rich: RichRenderer, OutputFormat.json: JsonRenderer}[fmt]()

trap_cli-0.0.6/src/trap/report/base.py

@@ -1,8 +0,0 @@
-from __future__ import annotations
-
-from trap.models import ReportData
-
-
-class BaseRenderer:
-    def render(self, data: ReportData) -> None:
-        raise NotImplementedError

trap_cli-0.0.6/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())

trap_cli-0.0.6/src/trap/report/json.py

@@ -1,11 +0,0 @@
-from __future__ import annotations
-
-import sys
-
-from trap.models import ReportData
-from trap.report.base import BaseRenderer
-
-
-class JsonRenderer(BaseRenderer):
-    def render(self, data: ReportData) -> None:
-        sys.stdout.write(data.model_dump_json(indent=2) + "\n")