trap-cli 0.0.1__py3-none-any.whl

trap/__init__.py

@@ -0,0 +1,6 @@
+try:
+    from trap._version import __version__
+except ImportError:  # pragma: no cover - only when built without hatch-vcs
+    __version__ = "0.0.0+unknown"
+
+__all__ = ["__version__"]

trap/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.0.1'
+__version_tuple__ = version_tuple = (0, 0, 1)
+
+__commit_id__ = commit_id = None

trap/auth/__init__.py

@@ -0,0 +1,15 @@
+from trap.auth.client import ApiClient, ApiError
+from trap.auth.login import BrowserProvider, TokenProvider
+from trap.auth.oauth import OAuthCallbackServer
+from trap.auth.store import DEFAULT_SERVER, AuthData, AuthStore
+
+__all__ = [
+    "DEFAULT_SERVER",
+    "ApiClient",
+    "ApiError",
+    "AuthData",
+    "AuthStore",
+    "BrowserProvider",
+    "OAuthCallbackServer",
+    "TokenProvider",
+]

trap/auth/client.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+from functools import cached_property
+from pathlib import Path
+from typing import Any
+
+import httpx
+
+
+class ApiError(Exception):
+    """A trapstreet API call failed — bad status, unreachable server, or invalid token.
+    Carries a user-facing message; the CLI maps it to a clean error (no traceback)."""
+
+
+class ApiClient:
+    """Authenticated HTTP client for the trapstreet API."""
+
+    def __init__(self, server: str, api_key: str, timeout: int = 30) -> None:
+        self._server = server.rstrip("/")
+        self._api_key = api_key
+        self._timeout = timeout
+
+    @cached_property
+    def _client(self) -> httpx.Client:
+        return httpx.Client(
+            base_url=self._server,
+            headers={
+                "authorization": f"Bearer {self._api_key}",
+                "content-type": "application/json",
+            },
+            timeout=self._timeout,
+        )
+
+    def get_me(self) -> dict[str, Any]:
+        try:
+            resp = self._client.get("/api/me", timeout=10)
+            resp.raise_for_status()
+            return resp.json()
+        except httpx.HTTPStatusError as e:
+            if e.response.status_code == 401:
+                raise ApiError("token is invalid") from None
+            raise ApiError(f"server error ({e.response.status_code})") from None
+        except httpx.RequestError:
+            raise ApiError("server unreachable") from None
+
+    def submit(self, report_path: Path) -> dict[str, Any]:
+        # Content-addressed ingest: the task identity travels inside the report
+        # (provenance.task.{repo,commit}), not the URL — so no task_id path segment.
+        try:
+            resp = self._client.post("/api/submit", content=report_path.read_bytes())
+            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
+        except httpx.RequestError as e:
+            raise ApiError(f"connection error: {e}") from None

trap/auth/login.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+from trap.auth.oauth import OAuthCallbackServer
+from trap.auth.store import DEFAULT_SERVER, AuthData
+
+
+class TokenProvider:
+    def __init__(self, server: str, token: str) -> None:
+        self._server = server
+        self._token = token
+
+    @property
+    def pre_message(self) -> str:
+        return "authenticating with api_key"
+
+    def acquire(self) -> AuthData:
+        if not self._token:
+            raise ValueError("empty api_key")
+        return AuthData(server=self._server, api_key=self._token)
+
+
+class BrowserProvider:
+    def __init__(self, server: str, timeout: int) -> None:
+        if server != DEFAULT_SERVER:
+            raise ValueError(
+                f"browser login is only supported on {DEFAULT_SERVER}. Use --with-token for custom servers."
+            )
+        self._cb = OAuthCallbackServer(server)
+        self._timeout = timeout
+
+    @property
+    def pre_message(self) -> str:
+        return f"opening [link={self._cb.auth_url}]{self._cb.auth_url}[/link]"
+
+    def acquire(self) -> AuthData:
+        if not self._cb.run(self._timeout):
+            raise TimeoutError(f"timed out after {self._timeout}s waiting for browser approval")
+        assert self._cb.auth_data is not None
+        return self._cb.auth_data

trap/auth/oauth.py

@@ -0,0 +1,82 @@
+from __future__ import annotations
+
+import http.server
+import socketserver
+import threading
+import urllib.parse
+import webbrowser
+from typing import Any
+
+from trap.auth.store import AuthData
+
+
+class _CallbackHandler(http.server.BaseHTTPRequestHandler):
+    _SUCCESS_HTML = (
+        b"<!doctype html><meta charset=utf-8>"
+        b"<title>logged in</title>"
+        b"<style>body{font-family:ui-monospace,monospace;"
+        b"background:#0a0a0a;color:#ededed;padding:3em;}"
+        b"h1{color:#ff5f1f}</style>"
+        b"<h1>logged in</h1>"
+        b"<p>You can close this tab.</p>"
+    )
+
+    def log_message(self, format: str, *args: Any) -> None:
+        return
+
+    def _respond(self, status: int, content_type: str, body: bytes) -> None:
+        self.send_response(status)
+        self.send_header("content-type", content_type)
+        self.end_headers()
+        self.wfile.write(body)
+
+    def do_GET(self) -> None:
+        params = urllib.parse.parse_qs(urllib.parse.urlparse(self.path).query)
+
+        api_key = (params.get("api_key") or [None])[0]
+        if not api_key:
+            self._respond(400, "text/plain", b"missing api_key in query string")
+            return
+
+        solution = (params.get("solution") or [None])[0]
+        srv: OAuthCallbackServer = self.server  # type: ignore[assignment]
+        srv._receive(AuthData(server=srv._server_url, api_key=api_key, solution=solution))
+        self._respond(200, "text/html; charset=utf-8", self._SUCCESS_HTML)
+
+
+class OAuthCallbackServer(socketserver.TCPServer):
+    """Local HTTP server that receives the OAuth callback with api_key."""
+
+    def __init__(self, server_url: str) -> None:
+        super().__init__(("127.0.0.1", 0), _CallbackHandler)
+        self._server_url = server_url.rstrip("/")
+        self._auth_data: AuthData | None = None
+        self._received = threading.Event()
+
+    def _receive(self, data: AuthData) -> None:
+        self._auth_data = data
+        self._received.set()
+
+    @property
+    def auth_data(self) -> AuthData | None:
+        return self._auth_data
+
+    @property
+    def port(self) -> int:
+        return self.server_address[1]
+
+    @property
+    def auth_url(self) -> str:
+        return f"{self._server_url}/cli/authorize?return=http://localhost:{self.port}/callback"
+
+    def run(self, timeout: int) -> bool:
+        """Start server, open browser, wait for callback, shut down. Returns True if api_key received."""
+        threading.Thread(target=self.serve_forever, daemon=True).start()
+        try:
+            webbrowser.open(self.auth_url)
+        except Exception:
+            pass
+        received = self._received.wait(timeout)
+        self.shutdown()
+        self.server_close()
+        return received

trap/auth/store.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+import json as _json
+from pathlib import Path
+
+from pydantic import BaseModel, ValidationError
+
+DEFAULT_SERVER = "https://trapstreet.run"
+
+
+class AuthData(BaseModel):
+    server: str
+    api_key: str
+    solution: str | None = None
+
+
+class AuthStore:
+    PATH = Path.home() / ".config" / "trapstreet" / "auth.json"
+
+    def load(self) -> AuthData | None:
+        if not self.exists:
+            return None
+        try:
+            return AuthData.model_validate(_json.loads(self.PATH.read_text()))
+        except (OSError, _json.JSONDecodeError, ValidationError):
+            return None
+
+    def save(self, data: AuthData) -> Path:
+        self.PATH.parent.mkdir(parents=True, exist_ok=True)
+        self.PATH.write_text(data.model_dump_json(exclude_none=True, indent=2) + "\n")
+        self.PATH.chmod(0o600)
+        return self.PATH
+
+    @property
+    def exists(self) -> bool:
+        return self.PATH.exists()
+
+    def delete(self) -> None:
+        self.PATH.unlink()

trap/cli/__init__.py

@@ -0,0 +1,274 @@
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from rich.console import Console
+
+from trap.auth import DEFAULT_SERVER, ApiClient, ApiError, AuthStore
+from trap.cli._auth import auth_app
+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.runner import TaskRunner
+
+app = typer.Typer(help="AI prompt / agent / workflow / testing framework.")
+app.add_typer(auth_app, name="auth")
+console = Console()
+
+
+def _die(msg: object) -> typer.Exit:
+    """Print an error and return an Exit(2) to raise."""
+    console.print(f"[red]error[/red]: {msg}")
+    return typer.Exit(code=2)
+
+
+def _env_truthy(name: str) -> bool:
+    return os.environ.get(name, "").strip().lower() in ("1", "true", "yes", "on")
+
+
+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;
+    raises to abort. Bypassed by --trust-remote / TRAP_TRUST_REMOTE (for CI / repeated
+    runs); refuses (rather than running silently) when there's no TTY to confirm at."""
+    if trust:
+        return
+    console.print(
+        "[yellow]⚠  about to download and RUN code from a remote source:[/yellow]\n"
+        f"     [bold]{url}[/bold]\n"
+        "   trap will execute its setup command, the solution, and any judge/grader\n"
+        "   scripts — arbitrary code from this repo runs on your machine."
+    )
+    if not sys.stdin.isatty():
+        raise _die(
+            "remote source needs confirmation; pass --trust-remote "
+            "(or set TRAP_TRUST_REMOTE=1) to run it non-interactively"
+        )
+    if not typer.confirm("Continue?", default=False):
+        raise typer.Exit(code=1)
+
+
+@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)."),
+    ] = None,
+    clone_to: Annotated[
+        Path | None,
+        typer.Option("--clone-to", help="Where to clone a git+ URL --solution (default: ./<repo>)."),
+    ] = None,
+    trust_remote: Annotated[
+        bool,
+        typer.Option(
+            "--trust-remote",
+            help="Skip the confirmation before downloading and running a remote "
+            "(git+ URL) solution/task. Also settable via TRAP_TRUST_REMOTE=1.",
+        ),
+    ] = 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,
+        typer.Option(
+            "--setup-solution",
+            help="Force-run the solution's setup_cmd even when no remote pull brought new code.",
+        ),
+    ] = False,
+    setup_task: Annotated[
+        bool,
+        typer.Option(
+            "--setup-task",
+            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(
+            "--environment/--no-environment",
+            help="Collect host machine environment info (CPU/RAM/OS/Python) into the report.",
+        ),
+    ] = True,
+    cost: Annotated[
+        bool,
+        typer.Option(
+            "--cost/--no-cost",
+            help="Track LLM token usage and spend via the proxy (auto-detects providers from env).",
+        ),
+    ] = True,
+) -> 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.
+    """
+    # 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).
+    trust = trust_remote or _env_truthy("TRAP_TRUST_REMOTE")
+    if solution is not None and ParsedGitUrl.looks_remote(solution):
+        _confirm_remote(solution, trust=trust)
+    try:
+        trap_yaml_loader = TrapLoader.from_solution(
+            solution,
+            clone_to,
+            allow_remote=True,
+            setup=setup_solution,
+            progress_func=(
+                (lambda m: console.print(f"[dim]{m}[/dim]")) if output == OutputFormat.rich else None
+            ),
+        )
+        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
+        )
+    except (GitOpsError, ConfigError, subprocess.CalledProcessError) as e:
+        raise _die(e) from None
+
+    active_cases = traptask_yaml_loader.cases_with_tags(tags or [])
+
+    started_at_local = datetime.now()
+    ts = started_at_local.isoformat(timespec="seconds")
+    report_handle = ReportHandle(workspace.resolve(), task_binding.alias, ts)
+
+    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,
+        cost_enabled=cost,
+    )
+    prog_console = console if output == OutputFormat.rich else None
+    with CaseProgress(active_cases, console=prog_console) as prog:
+        case_results, grader_metrics = runner.run(
+            active_cases,
+            fail_fast=fail_fast,
+            on_case_start=prog.on_case_start,
+            on_case_done=prog.on_case_done,
+        )
+    finished_at_utc = datetime.now(UTC)
+
+    # Record git provenance (repo + commit) of both checkouts — solution and task —
+    # so the run is reproducible. Each side is empty for a dirty/remote-less/local tree.
+    provenance = Provenance(
+        solution=LocalRepo.provenance_of(trap_yaml_loader.trap_dir),
+        task=LocalRepo.provenance_of(traptask_yaml_loader.traptask_dir),
+    )
+
+    # Capture the host machine environment (CPU/RAM/OS/Python) unless disabled.
+    # Detection is best-effort and must never abort a completed run.
+    environment_info = None
+    if environment:
+        try:
+            environment_info = EnvironmentDetector().detect()
+        except Exception:
+            environment_info = None
+
+    report_data = report_handle.save(
+        case_results=case_results,
+        trap_config=trap_yaml_loader.config,
+        started_at_utc=started_at_local.astimezone(UTC),
+        finished_at_utc=finished_at_utc,
+        grader_metrics=grader_metrics,
+        provenance=provenance,
+        environment=environment_info,
+    )
+    renderer_factory(output).render(report_data)
+    # 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.
+
+
+@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)."),
+    ] = None,
+    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)
+    try:
+        report_data = handle.load()
+    except FileNotFoundError:
+        raise _die(f"no report at {handle.report_json_path}; run `tp run` first") from None
+    renderer_factory(output).render(report_data)
+
+
+@app.command()
+def submit(
+    task: Annotated[
+        str | None,
+        typer.Argument(
+            help="Task name (defaults to first task in trap.yaml). "
+            "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",
+) -> None:
+    """Upload a report.json to trapstreet.
+
+    Reads from the .trap/<task>/<run>/report.json workspace that `tp run`
+    populated.
+    """
+    stored = AuthStore().load()
+    # priority: TRAPSTREET_URL env > stored > default
+    resolved_server = (
+        os.environ.get("TRAPSTREET_URL") or (stored.server if stored else None) or DEFAULT_SERVER
+    )
+    # priority: TRAPSTREET_API_KEY env > stored
+    resolved_key = os.environ.get("TRAPSTREET_API_KEY") or (stored.api_key if stored else None)
+    if not resolved_key:
+        raise _die("not logged in. Run [bold]tp auth login[/bold] or set [bold]TRAPSTREET_API_KEY[/bold].")
+
+    try:
+        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)
+    try:
+        report_handle.assert_exists()
+    except FileNotFoundError:
+        raise _die(f"no report at {report_handle.report_json_path}. Run [bold]tp run[/bold] first.") from None
+    report_path = report_handle.report_json_path
+
+    client = ApiClient(resolved_server, resolved_key)
+    try:
+        resp_data = client.submit(report_path)
+    except ApiError as e:
+        raise _die(e) from None
+    render_submit_result(resp_data)
+
+
+# Hidden until the scaffold is implemented — registered but not advertised in `--help`.
+@app.command(hidden=True)
+def init() -> None:
+    """Generate annotated trap.yaml + traptask.yaml scaffold."""
+    console.print("not yet")

trap/cli/_auth.py

@@ -0,0 +1,103 @@
+from __future__ import annotations
+
+import sys
+from typing import Annotated
+
+import typer
+from rich.console import Console
+
+from trap.auth import DEFAULT_SERVER, ApiClient, ApiError, AuthStore, BrowserProvider, TokenProvider
+
+auth_app = typer.Typer(help="Manage authentication.")
+console = Console()
+
+
+@auth_app.command("login")
+def auth_login(
+    server: Annotated[
+        str | None,
+        typer.Option("--server", envvar="TRAPSTREET_URL", help="Trapstreet server URL."),
+    ] = None,
+    timeout: Annotated[int, typer.Option("--timeout", help="Seconds to wait for browser approval.")] = 300,
+    with_token: Annotated[
+        bool,
+        typer.Option("--with-token", help="Read api_key from stdin instead of opening a browser."),
+    ] = False,
+) -> None:
+    """Authenticate this machine with Trapstreet.
+
+    By default opens a browser to complete OAuth. Pass --with-token to supply
+    an api_key directly (useful for CI or headless environments).
+
+    The token is saved to ~/.config/trapstreet/auth.json (mode 600).
+    """
+    stored = AuthStore().load()
+    # priority: --server / TRAPSTREET_URL > stored > default
+    resolved_server = server or (stored.server if stored else None) or DEFAULT_SERVER
+
+    # BrowserProvider raises ValueError for a non-default server (the same check the
+    # CLI used to duplicate), so provider construction sits inside the try alongside
+    # acquire() — one error path for both.
+    try:
+        if with_token:
+            if sys.stdin.isatty():  # pragma: no cover - interactive prompt, no TTY under tests
+                token = typer.prompt("API key", hide_input=True)
+            else:
+                token = sys.stdin.read().strip()
+            provider = TokenProvider(resolved_server, token)
+        else:
+            provider = BrowserProvider(resolved_server, timeout)
+        console.print(provider.pre_message)
+        auth_data = provider.acquire()
+    except (ValueError, TimeoutError) as e:
+        console.print(f"[red]error[/red]: {e}")
+        raise typer.Exit(code=2) from None
+
+    path = AuthStore().save(auth_data)
+    console.print(
+        "[green]✓ logged in[/green]"
+        + (f" · solution [bold]{auth_data.solution}[/bold]" if auth_data.solution else "")
+        + f" · token saved to {path}"
+    )
+
+
+@auth_app.command("logout")
+def auth_logout() -> None:
+    """Delete the locally-stored api_key."""
+    auth_store = AuthStore()
+    if not auth_store.exists:
+        console.print(f"already logged out — no file at {auth_store.PATH}")
+        return
+    auth_store.delete()
+    console.print(f"[green]✓[/green] removed {auth_store.PATH}")
+
+
+@auth_app.command("status")
+def auth_status(
+    verify: Annotated[
+        bool,
+        typer.Option("--verify/--no-verify", help="Ping server to verify token validity."),
+    ] = True,
+) -> None:
+    """Show current authentication state."""
+    stored = AuthStore().load()
+    if not stored:
+        console.print("[red]not logged in[/red]. Run [bold]tp auth login[/bold].")
+        raise typer.Exit(code=1)
+
+    console.print(f"  server    {stored.server}")
+    if stored.solution:
+        console.print(f"  solution  [bold]{stored.solution}[/bold]")
+
+    if not verify:
+        return
+
+    client = ApiClient(stored.server, stored.api_key)
+    try:
+        me = client.get_me()
+    except ApiError as e:
+        console.print(f"[red]error[/red]: {e}")
+        raise typer.Exit(code=1) from None
+    user = me.get("user") or {}
+    identity = user.get("name") or user.get("email") or "(unknown)"
+    console.print(f"  user      {identity}\n[green]✓ token is valid[/green]")

trap/cost/__init__.py

@@ -0,0 +1,3 @@
+from .proxy import CostProxy
+
+__all__ = ["CostProxy"]