verifaied 0.1.0.dev29__tar.gz → 0.2.0.dev31__tar.gz

{verifaied-0.1.0.dev29 → verifaied-0.2.0.dev31}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: verifaied
-Version: 0.1.0.dev29
+Version: 0.2.0.dev31
 Summary: Find what's untested in your Python code — locally, no account required
 Project-URL: Homepage, https://pypi.org/project/verifaied/
 Author: Kyle Richards
@@ -185,6 +185,68 @@ keeps the data around for accidental-deletion recovery.
   uploaded, then exit without contacting the backend. Skips the token
   requirement so you can audit without configuring auth.
 
+## `verifaied check-done` — the "am I done?" gate
+
+`check-done` is the **stop condition** for an agent's test-writing loop.
+It fetches a verdict for a branch — failing tests plus the coverage of the
+functions you changed — and exits accordingly, so a CI job or an agent can
+gate on it:
+
+```bash
+pytest --cov --cov-report=json --junitxml=junit.xml
+verifaied upload            # push the fresh coverage first
+verifaied check-done        # then ask: am I done?
+```
+
+The verdict composes into `{done, status, gaps}`:
+
+- `done` (bool) — `true` only when there are **no gaps at all**. The
+  strict signal to stop.
+- `status` — `done` | `done-with-warnings` | `not-done`.
+  `done-with-warnings` means the only gaps left are ones the repo owner
+  marked non-blocking (per-repo policy, set in the web UI).
+- `gaps[]` — each remaining problem with a `ref`, whether it's `blocking`,
+  and a `next_action` pointing at the free (`get_baseline_prompt`) or paid
+  (`fix_branch`) remedy.
+- `not_checked[]` — signals that couldn't be evaluated (e.g. failing tests
+  when no `junit.xml` was uploaded), surfaced so a green verdict is never
+  silently green.
+
+### Exit codes
+
+- `0` — done (or `done-with-warnings` with `--allow-warnings`)
+- `3` — not done: blocking gaps remain (the CI-gate failure code)
+- `2` — HTTP/API error (auth, 404, network)
+- `1` — usage/config error (no token, bad `--repo`)
+
+### `check-done` flags
+
+- `--repo / -r <UUID|owner/name>` — repository to check (default:
+  auto-detect from the GitHub `origin` remote)
+- `--branch / -b <name>` — branch to judge (default:
+  `git branch --show-current`)
+- `--json` — print the raw verdict JSON instead of the human summary
+- `--allow-warnings` — treat `done-with-warnings` as passing (exit 0);
+  default is strict (only a clean `done` exits 0)
+- `--api-url <url>` — backend base URL (overrides `VERIFAIED_API_URL`)
+- `--token <token>` — API token (overrides `VERIFAIED_API_TOKEN`)
+
+### As an agent stop condition
+
+Drop this loop into your agent's instructions file so it self-corrects
+and knows when to stop:
+
+```text
+Test-coverage loop (run until done):
+  1. Run tests with coverage:  pytest --cov --cov-report=json --junitxml=junit.xml
+  2. Push the results:         verifaied upload
+  3. Ask if you're done:       verifaied check-done
+  4. If exit code is 0, stop — you're done.
+     If exit code is 3, fix each gap in the output (use get_baseline_prompt
+     for a free test prompt, or fix_branch for an LLM-written one), then
+     go back to step 1.
+```
+
 ## Agent loop
 
 We've found the most fruitful way to use verifAIed is to put a short
@@ -201,7 +263,7 @@ into the matching rules file, tailored to your repo:
 ```markdown
 We've found that adding a short test-coverage loop to your agent's instructions is the most fruitful way to use verifAIed. I want you to write that loop into this repo's agent-instructions file, tailored to how this repo actually runs its tests.
 
-verifAIed is a coverage analysis tool. Its CLI (`verifaied upload`) pushes a local `coverage.json` + `junit.xml` to the server; its MCP server exposes a `fix_branch` tool that returns a single prompt describing every untested function, partial branch, and failing test on the current branch. The agent loop is: run tests → `verifaied upload` → call `fix_branch` → apply the returned prompt → repeat until `fix_branch` returns no findings.
+verifAIed is a coverage analysis tool. Its CLI (`verifaied upload`) pushes a local `coverage.json` + `junit.xml` to the server; its MCP server exposes a `check_done` tool that returns a `{done, status, gaps}` verdict for the branch (the loop's stop condition), and a `fix_branch` tool that returns a single prompt describing every untested function, partial branch, and failing test. The agent loop is: run tests → `verifaied upload` → call `check_done` → if `done` is true stop, otherwise fix the gaps (`get_baseline_prompt` per function, or `fix_branch` for one prompt covering everything) → repeat.
 
 Do the following, in order:
 
@@ -233,8 +295,9 @@ Append (or create) a section titled `## Test coverage loop with verifAIed` conta
 
 - The exact test command(s) you built in step 1 — so future runs of the agent don't have to re-derive them.
 - The exact upload command (`verifaied upload`, plus any flags this repo needs — e.g. `--coverage path/to/coverage.json` if your test command lands the JSON outside the repo root).
-- An instruction to call the `fix_branch` tool on the verifAIed MCP server with `scope: everything`, then apply the returned prompt.
-- An instruction to repeat from step 1 until `fix_branch` returns no findings.
+- An instruction to call the `check_done` tool on the verifAIed MCP server after each upload, and to stop only when it returns `done: true`.
+- An instruction that while `check_done` reports gaps, fix them: call `get_baseline_prompt(function_id)` for a free per-function test prompt, or `fix_branch` with `scope: everything` for a single prompt covering every gap, then apply it.
+- An instruction to repeat from step 1 until `check_done` reports `done: true`.
 - One line: "If `VERIFAIED_API_TOKEN` is unset, stop and ask the user — do not skip this loop."
 
 # 4. Confirm with the user
@@ -246,7 +309,8 @@ Show the user the diff of the file you edited (or created) and the test command
 - Do NOT change the test command's behavior beyond adding coverage / junit flags.
 - Do NOT add new dependencies if pytest-cov and coverage are already transitive deps.
 - Do NOT write a fallback that skips the loop when the token is missing — the agent must stop and ask.
-- Do NOT enumerate functions yourself or write tests; `fix_branch` returns the prompt that does that.
+- Do NOT enumerate functions yourself or write tests; `check_done` lists the gaps and `fix_branch` / `get_baseline_prompt` return the prompts that close them.
+- Do NOT decide "done" yourself; `check_done` is the stop condition.
 - Do NOT replace an existing agent-instructions file — append a new section.
 ```
 
@@ -259,7 +323,7 @@ it differs from the pytest default:
 ```markdown
 ## Test coverage loop with verifAIed
 
-After implementing or modifying any code in this repo, run this loop until verifAIed reports clean:
+After implementing or modifying any code in this repo, run this loop until verifAIed reports done:
 
 1. Run the test suite with branch coverage and per-test contexts:
    ```
@@ -270,9 +334,10 @@ After implementing or modifying any code in this repo, run this loop until verif
    ```
    verifaied upload
    ```
-3. Call the `fix_branch` tool on the verifAIed MCP server with `scope: everything`. It returns a single prompt describing every untested function, partial branch, and failing test on this branch.
-4. Apply the fixes the prompt describes.
-5. Go back to step 1.
+3. Ask if you're done: call the `check_done` tool on the verifAIed MCP server (or run `verifaied check-done`). It returns `{done, status, gaps}` for this branch — failing tests plus untested/partially-covered functions among the ones you changed.
+4. If `done` is true, stop — the branch is covered.
+5. Otherwise fix the gaps it lists: call `get_baseline_prompt(function_id)` for a free test prompt per function, or `fix_branch` with `scope: everything` for a single LLM-written prompt covering every gap on the branch.
+6. Go back to step 1.
 
-Stop when `fix_branch` returns no findings. If `VERIFAIED_API_TOKEN` is not set, stop and ask the user — do not skip this loop.
+Stop only when `check_done` reports `done: true`. If `VERIFAIED_API_TOKEN` is not set, stop and ask the user — do not skip this loop.
 ```

{verifaied-0.1.0.dev29 → verifaied-0.2.0.dev31}/README.md

@@ -145,6 +145,68 @@ keeps the data around for accidental-deletion recovery.
   uploaded, then exit without contacting the backend. Skips the token
   requirement so you can audit without configuring auth.
 
+## `verifaied check-done` — the "am I done?" gate
+
+`check-done` is the **stop condition** for an agent's test-writing loop.
+It fetches a verdict for a branch — failing tests plus the coverage of the
+functions you changed — and exits accordingly, so a CI job or an agent can
+gate on it:
+
+```bash
+pytest --cov --cov-report=json --junitxml=junit.xml
+verifaied upload            # push the fresh coverage first
+verifaied check-done        # then ask: am I done?
+```
+
+The verdict composes into `{done, status, gaps}`:
+
+- `done` (bool) — `true` only when there are **no gaps at all**. The
+  strict signal to stop.
+- `status` — `done` | `done-with-warnings` | `not-done`.
+  `done-with-warnings` means the only gaps left are ones the repo owner
+  marked non-blocking (per-repo policy, set in the web UI).
+- `gaps[]` — each remaining problem with a `ref`, whether it's `blocking`,
+  and a `next_action` pointing at the free (`get_baseline_prompt`) or paid
+  (`fix_branch`) remedy.
+- `not_checked[]` — signals that couldn't be evaluated (e.g. failing tests
+  when no `junit.xml` was uploaded), surfaced so a green verdict is never
+  silently green.
+
+### Exit codes
+
+- `0` — done (or `done-with-warnings` with `--allow-warnings`)
+- `3` — not done: blocking gaps remain (the CI-gate failure code)
+- `2` — HTTP/API error (auth, 404, network)
+- `1` — usage/config error (no token, bad `--repo`)
+
+### `check-done` flags
+
+- `--repo / -r <UUID|owner/name>` — repository to check (default:
+  auto-detect from the GitHub `origin` remote)
+- `--branch / -b <name>` — branch to judge (default:
+  `git branch --show-current`)
+- `--json` — print the raw verdict JSON instead of the human summary
+- `--allow-warnings` — treat `done-with-warnings` as passing (exit 0);
+  default is strict (only a clean `done` exits 0)
+- `--api-url <url>` — backend base URL (overrides `VERIFAIED_API_URL`)
+- `--token <token>` — API token (overrides `VERIFAIED_API_TOKEN`)
+
+### As an agent stop condition
+
+Drop this loop into your agent's instructions file so it self-corrects
+and knows when to stop:
+
+```text
+Test-coverage loop (run until done):
+  1. Run tests with coverage:  pytest --cov --cov-report=json --junitxml=junit.xml
+  2. Push the results:         verifaied upload
+  3. Ask if you're done:       verifaied check-done
+  4. If exit code is 0, stop — you're done.
+     If exit code is 3, fix each gap in the output (use get_baseline_prompt
+     for a free test prompt, or fix_branch for an LLM-written one), then
+     go back to step 1.
+```
+
 ## Agent loop
 
 We've found the most fruitful way to use verifAIed is to put a short
@@ -161,7 +223,7 @@ into the matching rules file, tailored to your repo:
 ```markdown
 We've found that adding a short test-coverage loop to your agent's instructions is the most fruitful way to use verifAIed. I want you to write that loop into this repo's agent-instructions file, tailored to how this repo actually runs its tests.
 
-verifAIed is a coverage analysis tool. Its CLI (`verifaied upload`) pushes a local `coverage.json` + `junit.xml` to the server; its MCP server exposes a `fix_branch` tool that returns a single prompt describing every untested function, partial branch, and failing test on the current branch. The agent loop is: run tests → `verifaied upload` → call `fix_branch` → apply the returned prompt → repeat until `fix_branch` returns no findings.
+verifAIed is a coverage analysis tool. Its CLI (`verifaied upload`) pushes a local `coverage.json` + `junit.xml` to the server; its MCP server exposes a `check_done` tool that returns a `{done, status, gaps}` verdict for the branch (the loop's stop condition), and a `fix_branch` tool that returns a single prompt describing every untested function, partial branch, and failing test. The agent loop is: run tests → `verifaied upload` → call `check_done` → if `done` is true stop, otherwise fix the gaps (`get_baseline_prompt` per function, or `fix_branch` for one prompt covering everything) → repeat.
 
 Do the following, in order:
 
@@ -193,8 +255,9 @@ Append (or create) a section titled `## Test coverage loop with verifAIed` conta
 
 - The exact test command(s) you built in step 1 — so future runs of the agent don't have to re-derive them.
 - The exact upload command (`verifaied upload`, plus any flags this repo needs — e.g. `--coverage path/to/coverage.json` if your test command lands the JSON outside the repo root).
-- An instruction to call the `fix_branch` tool on the verifAIed MCP server with `scope: everything`, then apply the returned prompt.
-- An instruction to repeat from step 1 until `fix_branch` returns no findings.
+- An instruction to call the `check_done` tool on the verifAIed MCP server after each upload, and to stop only when it returns `done: true`.
+- An instruction that while `check_done` reports gaps, fix them: call `get_baseline_prompt(function_id)` for a free per-function test prompt, or `fix_branch` with `scope: everything` for a single prompt covering every gap, then apply it.
+- An instruction to repeat from step 1 until `check_done` reports `done: true`.
 - One line: "If `VERIFAIED_API_TOKEN` is unset, stop and ask the user — do not skip this loop."
 
 # 4. Confirm with the user
@@ -206,7 +269,8 @@ Show the user the diff of the file you edited (or created) and the test command
 - Do NOT change the test command's behavior beyond adding coverage / junit flags.
 - Do NOT add new dependencies if pytest-cov and coverage are already transitive deps.
 - Do NOT write a fallback that skips the loop when the token is missing — the agent must stop and ask.
-- Do NOT enumerate functions yourself or write tests; `fix_branch` returns the prompt that does that.
+- Do NOT enumerate functions yourself or write tests; `check_done` lists the gaps and `fix_branch` / `get_baseline_prompt` return the prompts that close them.
+- Do NOT decide "done" yourself; `check_done` is the stop condition.
 - Do NOT replace an existing agent-instructions file — append a new section.
 ```
 
@@ -219,7 +283,7 @@ it differs from the pytest default:
 ```markdown
 ## Test coverage loop with verifAIed
 
-After implementing or modifying any code in this repo, run this loop until verifAIed reports clean:
+After implementing or modifying any code in this repo, run this loop until verifAIed reports done:
 
 1. Run the test suite with branch coverage and per-test contexts:
    ```
@@ -230,9 +294,10 @@ After implementing or modifying any code in this repo, run this loop until verif
    ```
    verifaied upload
    ```
-3. Call the `fix_branch` tool on the verifAIed MCP server with `scope: everything`. It returns a single prompt describing every untested function, partial branch, and failing test on this branch.
-4. Apply the fixes the prompt describes.
-5. Go back to step 1.
+3. Ask if you're done: call the `check_done` tool on the verifAIed MCP server (or run `verifaied check-done`). It returns `{done, status, gaps}` for this branch — failing tests plus untested/partially-covered functions among the ones you changed.
+4. If `done` is true, stop — the branch is covered.
+5. Otherwise fix the gaps it lists: call `get_baseline_prompt(function_id)` for a free test prompt per function, or `fix_branch` with `scope: everything` for a single LLM-written prompt covering every gap on the branch.
+6. Go back to step 1.
 
-Stop when `fix_branch` returns no findings. If `VERIFAIED_API_TOKEN` is not set, stop and ask the user — do not skip this loop.
+Stop only when `check_done` reports `done: true`. If `VERIFAIED_API_TOKEN` is not set, stop and ask the user — do not skip this loop.
 ```

{verifaied-0.1.0.dev29 → verifaied-0.2.0.dev31}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "verifaied"
-version = "0.1.0.dev29"
+version = "0.2.0.dev31"
 description = "Find what's untested in your Python code — locally, no account required"
 readme = "README.md"
 requires-python = ">=3.10"

{verifaied-0.1.0.dev29 → verifaied-0.2.0.dev31}/src/verifaied/cli.py

@@ -25,6 +25,7 @@ from verifaied.client import (
     ApiError,
     RepoNotFoundError,
     UploadResult,
+    check_done,
     resolve_repo_id,
     upload,
 )
@@ -36,7 +37,12 @@ from verifaied.config import (
     resolved_api_url,
 )
 from verifaied.prompts import build_prompt, format_line_ranges
-from verifaied.uploader import UploaderError, build_payload, detect_repo_slug
+from verifaied.uploader import (
+    UploaderError,
+    build_payload,
+    detect_branch,
+    detect_repo_slug,
+)
 
 app = typer.Typer(
     add_completion=False,
@@ -293,6 +299,141 @@ def check_command(
             raise typer.Exit(code=3)
 
 
+@app.command("check-done")
+def check_done_command(
+    repo: str | None = typer.Option(
+        None,
+        "--repo",
+        "-r",
+        help=(
+            "Repository to check. Accepts a UUID, an `owner/name` slug, or "
+            "omit to auto-detect from `git remote get-url origin`."
+        ),
+    ),
+    branch: str | None = typer.Option(
+        None,
+        "--branch",
+        "-b",
+        help="Branch to judge. Defaults to `git branch --show-current`.",
+    ),
+    api_url: str | None = typer.Option(
+        None,
+        "--api-url",
+        help=f"Backend base URL. Defaults to ${ENV_API_URL} or {DEFAULT_API_URL}.",
+    ),
+    token: str | None = typer.Option(
+        None,
+        "--token",
+        help=f"API token (vr_live_...). Defaults to ${ENV_API_TOKEN}.",
+    ),
+    as_json: bool = typer.Option(
+        False,
+        "--json",
+        help="Print the raw verdict JSON instead of the human summary.",
+    ),
+    allow_warnings: bool = typer.Option(
+        False,
+        "--allow-warnings",
+        help=(
+            "Treat `done-with-warnings` as passing (exit 0). Default is "
+            "strict: only a clean `done` exits 0."
+        ),
+    ),
+) -> None:
+    """Am I done? The definition-of-done gate for an agent loop.
+
+    Fetches the hosted verdict for a branch — failing tests plus the
+    coverage of the functions you changed — and exits accordingly so a
+    CI job or an agent can stop on it:
+
+      0  done (or `done-with-warnings` with --allow-warnings)
+      3  not done — blocking gaps remain
+      2  HTTP/API error (auth, 404, network)
+      1  usage / config error (no token, bad --repo)
+
+    Upload coverage first (`verifaied upload`), then gate on this.
+    """
+    resolved_url = resolved_api_url(api_url)
+    resolved_token = resolved_api_token(token)
+    if not resolved_token:
+        err_console.print(
+            f"[red]error[/red]: no API token (set ${ENV_API_TOKEN} or pass --token)"
+        )
+        raise typer.Exit(code=1)
+
+    try:
+        repo_id = _resolve_repo(
+            repo_input=repo, api_url=resolved_url, token=resolved_token
+        )
+    except (UploaderError, ApiError, RepoNotFoundError) as e:
+        err_console.print(f"[red]error[/red]: {e}")
+        raise typer.Exit(code=2 if isinstance(e, ApiError) else 1) from e
+
+    resolved_branch = branch or detect_branch()
+    try:
+        verdict = check_done(
+            api_url=resolved_url,
+            token=resolved_token,
+            repo_id=repo_id,
+            branch=resolved_branch,
+        )
+    except ApiError as e:
+        err_console.print(f"[red]error[/red]: {e.message}")
+        raise typer.Exit(code=2) from e
+
+    if as_json:
+        print(json.dumps(verdict, indent=2))
+    else:
+        _render_check_done(verdict)
+
+    status = verdict.get("status")
+    if status == "done":
+        return
+    if status == "done-with-warnings" and allow_warnings:
+        return
+    raise typer.Exit(code=3)
+
+
+def _render_check_done(verdict: dict) -> None:
+    """Status line + a table of the remaining gaps."""
+    status = verdict.get("status", "unknown")
+    style = {
+        "done": "green",
+        "done-with-warnings": "yellow",
+        "not-done": "red",
+    }.get(status, "white")
+    console.print()
+    console.print(
+        f"[bold {style}]{status}[/bold {style}]  "
+        f"[dim]{verdict.get('branch', '?')} · scope: "
+        f"{verdict.get('scope', '?')}[/dim]"
+    )
+
+    for signal in verdict.get("not_checked") or []:
+        console.print(
+            f"[yellow]not checked[/yellow]: {signal.get('signal')} "
+            f"— {signal.get('reason')}"
+        )
+
+    gaps = verdict.get("gaps") or []
+    if not gaps:
+        console.print("\n[green]No gaps — done.[/green]")
+        return
+
+    table = Table(show_header=True, header_style="bold", box=None, pad_edge=False)
+    table.add_column("")
+    table.add_column("kind")
+    table.add_column("ref")
+    for gap in gaps:
+        marker = "[red]●[/red]" if gap.get("blocking") else "[yellow]○[/yellow]"
+        table.add_row(marker, gap.get("kind", "?"), gap.get("ref", "?"))
+    console.print()
+    console.print(table)
+    console.print(
+        "\n[dim]● blocking   ○ warning — fix each gap, re-upload, re-check.[/dim]"
+    )
+
+
 def _render_check(
     summary: CheckSummary, targets: list[FunctionResult], *, limit: int
 ) -> None:

{verifaied-0.1.0.dev29 → verifaied-0.2.0.dev31}/src/verifaied/client.py

@@ -95,6 +95,39 @@ def upload(
     )
 
 
+def check_done(
+    *,
+    api_url: str,
+    token: str,
+    repo_id: UUID,
+    branch: str | None = None,
+    timeout: float = 30.0,
+) -> dict[str, Any]:
+    """GET the ``check-done`` verdict for a (repo, branch).
+
+    Returns the parsed verdict dict (``{done, status, gaps, ...}``).
+    Raises ``ApiError`` on any non-2xx — the CLI maps a 404 to "no
+    analysis / repo not found" the same way the upload path does.
+    """
+    url = f"{api_url.rstrip('/')}/repositories/{repo_id}/check-done"
+    params = {"branch": branch} if branch is not None else None
+    try:
+        response = httpx.get(
+            url,
+            params=params,
+            headers={"Authorization": f"Bearer {token}"},
+            timeout=timeout,
+        )
+    except httpx.HTTPError as e:
+        raise ApiError(0, f"could not reach {url}: {e}") from e
+    if response.status_code >= 400:
+        raise ApiError(response.status_code, _detail(response))
+    data = response.json()
+    if not isinstance(data, dict):
+        raise ApiError(0, f"unexpected response from {url}: not an object")
+    return data
+
+
 def list_installations(
     *, api_url: str, token: str, timeout: float = 15.0
 ) -> list[dict[str, Any]]:
@@ -148,7 +181,14 @@ def resolve_repo_id(*, api_url: str, token: str, owner: str, name: str) -> UUID:
 def _detail(response: httpx.Response) -> str:
     """Pull a human-readable error message out of the response. Falls
     back to status reason if the body isn't JSON or doesn't carry a
-    ``detail`` field."""
+    usable ``detail`` field.
+
+    ``detail`` is usually a plain string, but structured errors return an
+    object instead — a plan-limit 403 carries
+    ``{"code", "message", "limit"}`` so the UI and CLI can branch on the
+    code. We surface its ``message`` so the user sees "Your plan covers 10
+    active branches..." rather than a bare "403 Forbidden".
+    """
     try:
         body = response.json()
     except ValueError:
@@ -156,4 +196,8 @@ def _detail(response: httpx.Response) -> str:
     detail = body.get("detail") if isinstance(body, dict) else None
     if isinstance(detail, str) and detail:
         return detail
+    if isinstance(detail, dict):
+        message = detail.get("message")
+        if isinstance(message, str) and message:
+            return message
     return f"{response.status_code} {response.reason_phrase}".strip()

verifaied-0.2.0.dev31/tests/test_check_done.py

@@ -0,0 +1,196 @@
+"""Tests for `verifaied check-done` — the definition-of-done CI gate.
+
+Invoked through the Typer runner so config resolution, error mapping, and
+the exit-code contract (0 done / 3 not-done / 2 HTTP / 1 config) all run
+the way a CI job or an agent hits them. The HTTP layer is mocked with
+pytest-httpx; ``--repo <UUID>`` is passed so repo resolution never needs
+the ``/installations/me`` round-trip.
+"""
+
+from __future__ import annotations
+
+import json
+from uuid import uuid4
+
+from pytest_httpx import HTTPXMock
+from typer.testing import CliRunner
+
+from verifaied.cli import app
+from verifaied.config import ENV_API_TOKEN
+
+runner = CliRunner()
+
+
+def _verdict(status: str, gaps: list[dict] | None = None, **extra) -> dict:
+    verdict = {
+        "done": status == "done",
+        "status": status,
+        "scope": "changed-functions",
+        "repository_id": "r",
+        "branch": "feature",
+        "analysis_id": "a",
+        "commit_sha": "sha",
+        "origin": "local",
+        "gaps": gaps or [],
+        "checked": ["untested_functions", "partial_functions"],
+        "not_checked": [],
+    }
+    verdict.update(extra)
+    return verdict
+
+
+def _invoke(repo_id, *, branch: str = "feature", extra_args: list[str] | None = None):
+    return runner.invoke(
+        app,
+        [
+            "check-done",
+            "--repo",
+            str(repo_id),
+            "--branch",
+            branch,
+            "--api-url",
+            "http://api.test",
+            *(extra_args or []),
+        ],
+    )
+
+
+def test_check_done_exits_0_when_done(monkeypatch, httpx_mock: HTTPXMock):
+    monkeypatch.setenv(ENV_API_TOKEN, "vr_live_tok")
+    repo_id = uuid4()
+    httpx_mock.add_response(
+        url=f"http://api.test/repositories/{repo_id}/check-done?branch=feature",
+        json=_verdict("done"),
+    )
+
+    result = _invoke(repo_id)
+
+    assert result.exit_code == 0
+    assert "done" in result.stdout
+
+
+def test_check_done_exits_3_when_not_done(monkeypatch, httpx_mock: HTTPXMock):
+    monkeypatch.setenv(ENV_API_TOKEN, "vr_live_tok")
+    repo_id = uuid4()
+    httpx_mock.add_response(
+        url=f"http://api.test/repositories/{repo_id}/check-done?branch=feature",
+        json=_verdict(
+            "not-done",
+            gaps=[
+                {
+                    "kind": "untested_function",
+                    "ref": "app/billing.py::apply_topup",
+                    "blocking": True,
+                }
+            ],
+        ),
+    )
+
+    result = _invoke(repo_id)
+
+    assert result.exit_code == 3
+    assert "not-done" in result.stdout
+    assert "app/billing.py::apply_topup" in result.stdout
+
+
+def test_check_done_with_warnings_exits_3_by_default(
+    monkeypatch, httpx_mock: HTTPXMock
+):
+    monkeypatch.setenv(ENV_API_TOKEN, "vr_live_tok")
+    repo_id = uuid4()
+    httpx_mock.add_response(
+        url=f"http://api.test/repositories/{repo_id}/check-done?branch=feature",
+        json=_verdict(
+            "done-with-warnings",
+            gaps=[{"kind": "partial_function", "ref": "m.py::f", "blocking": False}],
+        ),
+    )
+
+    result = _invoke(repo_id)
+
+    assert result.exit_code == 3
+
+
+def test_check_done_with_warnings_exits_0_when_allowed(
+    monkeypatch, httpx_mock: HTTPXMock
+):
+    monkeypatch.setenv(ENV_API_TOKEN, "vr_live_tok")
+    repo_id = uuid4()
+    httpx_mock.add_response(
+        url=f"http://api.test/repositories/{repo_id}/check-done?branch=feature",
+        json=_verdict(
+            "done-with-warnings",
+            gaps=[{"kind": "partial_function", "ref": "m.py::f", "blocking": False}],
+        ),
+    )
+
+    result = _invoke(repo_id, extra_args=["--allow-warnings"])
+
+    assert result.exit_code == 0
+
+
+def test_check_done_json_output(monkeypatch, httpx_mock: HTTPXMock):
+    monkeypatch.setenv(ENV_API_TOKEN, "vr_live_tok")
+    repo_id = uuid4()
+    verdict = _verdict(
+        "not-done", gaps=[{"kind": "failing_test", "ref": "t", "blocking": True}]
+    )
+    httpx_mock.add_response(
+        url=f"http://api.test/repositories/{repo_id}/check-done?branch=feature",
+        json=verdict,
+    )
+
+    result = _invoke(repo_id, extra_args=["--json"])
+
+    assert result.exit_code == 3
+    # The raw verdict is machine-parseable on stdout.
+    parsed = json.loads(result.stdout)
+    assert parsed["status"] == "not-done"
+    assert parsed["gaps"][0]["kind"] == "failing_test"
+
+
+def test_check_done_not_checked_signal_is_surfaced(monkeypatch, httpx_mock: HTTPXMock):
+    monkeypatch.setenv(ENV_API_TOKEN, "vr_live_tok")
+    repo_id = uuid4()
+    httpx_mock.add_response(
+        url=f"http://api.test/repositories/{repo_id}/check-done?branch=feature",
+        json=_verdict(
+            "done",
+            not_checked=[
+                {
+                    "signal": "failing_tests",
+                    "reason": "no junit.xml uploaded with this analysis",
+                }
+            ],
+        ),
+    )
+
+    result = _invoke(repo_id)
+
+    assert result.exit_code == 0
+    assert "not checked" in result.stdout
+    assert "failing_tests" in result.stdout
+
+
+def test_check_done_exits_2_on_api_error(monkeypatch, httpx_mock: HTTPXMock):
+    monkeypatch.setenv(ENV_API_TOKEN, "vr_live_tok")
+    repo_id = uuid4()
+    httpx_mock.add_response(
+        url=f"http://api.test/repositories/{repo_id}/check-done?branch=feature",
+        status_code=404,
+        json={"detail": "no analysis found for branch 'feature'"},
+    )
+
+    result = _invoke(repo_id)
+
+    assert result.exit_code == 2
+    assert "no analysis found" in result.stderr
+
+
+def test_check_done_exits_1_when_no_token(monkeypatch):
+    monkeypatch.delenv(ENV_API_TOKEN, raising=False)
+
+    result = _invoke(uuid4())
+
+    assert result.exit_code == 1
+    assert "no API token" in result.stderr

{verifaied-0.1.0.dev29 → verifaied-0.2.0.dev31}/tests/test_client.py

@@ -156,6 +156,31 @@ def test_upload_401_raises_api_error_with_detail(httpx_mock: HTTPXMock):
     assert "invalid token" in ei.value.message
 
 
+def test_upload_403_surfaces_plan_limit_message(httpx_mock: HTTPXMock):
+    repo_id = uuid4()
+    httpx_mock.add_response(
+        status_code=403,
+        json={
+            "detail": {
+                "code": "plan_branch_limit",
+                "message": "Your plan covers 10 active branches per repository.",
+                "limit": 10,
+            }
+        },
+    )
+
+    with pytest.raises(ApiError) as ei:
+        upload(
+            api_url="http://api.test",
+            token="t",
+            repo_id=repo_id,
+            payload=_PAYLOAD,
+        )
+
+    assert ei.value.status_code == 403
+    assert ei.value.message == "Your plan covers 10 active branches per repository."
+
+
 def test_upload_413_carries_status_code(httpx_mock: HTTPXMock):
     repo_id = uuid4()
     httpx_mock.add_response(status_code=413, json={"detail": "too large"})