cmpnd 0.55.0__tar.gz → 0.56.0__tar.gz

{cmpnd-0.55.0 → cmpnd-0.56.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cmpnd
-Version: 0.55.0
+Version: 0.56.0
 Summary: DSPy observability and deployment SDK for cmpnd
 Project-URL: Homepage, https://cmpnd.ai
 Author-email: cmpnd <hello@cmpnd.ai>

{cmpnd-0.55.0 → cmpnd-0.56.0}/cmpnd/cli/commands/programs.py

@@ -4,10 +4,12 @@ from __future__ import annotations
 
 import argparse
 import sys
+import urllib.parse
 from argparse import ArgumentParser, _SubParsersAction
 from typing import Any
 
 from .. import api_client, pagination
+from . import provider_credentials
 
 
 # Every id in this group is the value `programs list` prints as `program_hash`,
@@ -49,6 +51,11 @@ def register(subparsers: _SubParsersAction[ArgumentParser]) -> None:
     ls = sub.add_parser("list", help="List programs")
     ls.add_argument("--name", dest="program_name", help="Filter by program name")
     ls.add_argument("--model", dest="model_name", help="Filter by model name")
+    ls.add_argument(
+        "--trashed",
+        action="store_true",
+        help="List the programs in the Trash instead, with when each is purged",
+    )
     ls.add_argument("--order-by", default="run_count", help="Sort field (default: run_count)")
     ls.add_argument("--order", default="desc", choices=["asc", "desc"], help="Sort direction")
     pagination.add_args(ls, with_page_aliases=True, default_limit=50)
@@ -93,6 +100,37 @@ def register(subparsers: _SubParsersAction[ArgumentParser]) -> None:
     reg_show.add_argument("id", help="Registry ID")
     reg_show.set_defaults(func=handle_registry_show)
 
+    # The Trash. Each command takes a program name or a p_ id. A program in the
+    # Trash leaves every view and frees its place under the plan's program limit,
+    # and stays restorable until it is purged.
+    trash = sub.add_parser(
+        "trash",
+        help="Move a program to the Trash",
+        description=(
+            "Move PROGRAM to the Trash. It leaves every view and no longer counts toward your plan's program "
+            "limit. Restore it with `cmpnd programs restore PROGRAM` before it is purged, 7 days later."
+        ),
+    )
+    trash.add_argument("program", metavar="PROGRAM", help="Program name or p_ id")
+    trash.set_defaults(func=handle_trash)
+
+    restore = sub.add_parser("restore", help="Restore a program from the Trash")
+    restore.add_argument("program", metavar="PROGRAM", help="Program name or p_ id")
+    restore.set_defaults(func=handle_restore)
+
+    purge = sub.add_parser(
+        "purge",
+        help="Delete a program in the Trash for good",
+        description=(
+            "Delete PROGRAM, which must be in the Trash, for good, or every program in the Trash with --all. "
+            "Nothing restores a purged program."
+        ),
+    )
+    purge.add_argument("program", metavar="PROGRAM", nargs="?", default=None, help="Program name or p_ id")
+    purge.add_argument("--all", action="store_true", help="Purge every program in the Trash")
+    purge.add_argument("--force", action="store_true", help="Skip the confirmation (required when not on a terminal)")
+    purge.set_defaults(func=handle_purge)
+
     select = sub.add_parser("select", help="Pin an optimization run as this program's chosen version")
     select.add_argument("id", help="Program hash, as `programs list` prints it in the program_hash column")
     select.add_argument("--run", dest="run_id", required=True, help="Optimization run ID (op_...) to pin")
@@ -140,6 +178,22 @@ def handle_create(client: api_client.ApiClient, args: Any) -> Any:
 
 
 def handle_list(client: api_client.ApiClient, args: Any) -> Any:
+    if getattr(args, "trashed", False):
+        # The Trash is its own short list, unpaged and newest first, so the search filters, sort and paging do
+        # not apply. A flag left at its default cannot be told apart from one not passed.
+        for attr, flag, default in [
+            ("program_name", "--name", None),
+            ("model_name", "--model", None),
+            ("order_by", "--order-by", "run_count"),
+            ("order", "--order", "desc"),
+            ("limit", "--limit", 50),
+            ("offset", "--offset", 0),
+            ("per_page", "--per-page", None),
+            ("page", "--page", None),
+        ]:
+            if getattr(args, attr, default) != default:
+                raise api_client.CliError(f"{flag} does not apply to --trashed, which lists the whole Trash")
+        return client.get("/api/v1/programs/trash")
     params: dict[str, str] = pagination.wire(args, "per_page", as_str=True)
     params["order_by"] = args.order_by
     params["order_direction"] = args.order
@@ -189,3 +243,88 @@ def handle_select(client: api_client.ApiClient, args: Any) -> Any:
     audit trail records who made it.
     """
     return client.post(f"/api/v1/programs/{args.id}/select", json={"optimization_run_id": args.run_id})
+
+
+def _resolve(client: api_client.ApiClient, ref: str) -> tuple[str, bool | None]:
+    """Return the program id ``ref`` names, and whether it is in the Trash when known.
+
+    A ``p_`` id is used as given, because no program name starts with ``p_``, and its
+    Trash state is unknown until the route answers. A name is looked up, which never
+    makes a program, and the answer says whether it is in the Trash.
+    """
+    from ... import programs
+
+    if ref.lower().startswith("p_"):
+        return ref, None
+    try:
+        programs.validate_program_name(ref)
+    except ValueError as exc:
+        raise api_client.CliError(str(exc)) from exc
+    try:
+        answer = client.get("/api/v1/programs/by-name/" + urllib.parse.quote(ref, safe=""))
+    except api_client.CliError as exc:
+        if exc.status_code == 404:
+            raise api_client.CliError(f"no program in your organization is named {ref!r}") from exc
+        if exc.status_code == 410:
+            raise api_client.CliError(f"{ref!r} belongs to a purged program, which nothing restores") from exc
+        raise
+    return answer["program_id"], bool(answer.get("trashed"))
+
+
+def handle_trash(client: api_client.ApiClient, args: Any) -> Any:
+    """Move a program to the Trash, which frees its place under the plan's program limit."""
+    from . import top
+
+    program_id, trashed = _resolve(client, args.program)
+    if trashed:
+        print(
+            f"{args.program} is already in the Trash. Restore it with `{top.hint_programs('restore', args.program)}`.",
+            file=sys.stderr,
+        )
+        return {"program_id": program_id, "trashed": True}
+    return client.post(f"/api/v1/programs/{program_id}/trash")
+
+
+def handle_restore(client: api_client.ApiClient, args: Any) -> Any:
+    """Return a program from the Trash. The server refuses it when the plan's program limit is full."""
+    from . import top
+
+    program_id, trashed = _resolve(client, args.program)
+    if trashed is False:
+        # A name another program took from a Trashed one reaches the new, live program. The Trashed one is
+        # restored by its id.
+        raise api_client.CliError(
+            f"{args.program} is not in the Trash. If its name now belongs to another program, restore the one "
+            f"in the Trash by the p_ id that `{top.hint_programs('list', '--trashed')}` prints."
+        )
+    return client.post(f"/api/v1/programs/{program_id}/restore")
+
+
+def handle_purge(client: api_client.ApiClient, args: Any) -> Any:
+    """Delete one program in the Trash, or the whole Trash with ``--all``, for good."""
+    from . import top
+
+    consequence = "Nothing restores a purged program, and its traces stay hidden."
+    if args.all:
+        if args.program is not None:
+            raise api_client.CliError("name either one PROGRAM or --all, not both")
+        # The count is for the person confirming. --force skips the listing, which needs traces:read, so a key
+        # that may only write can still empty the Trash.
+        if not args.force:
+            listed = client.get("/api/v1/programs/trash")
+            count = len(listed.get("programs") or [])
+            if count == 0:
+                return {"purged": 0, "kept": 0}
+            noun = "program" if count == 1 else "programs"
+            provider_credentials.confirm(args, f"the {count} {noun} in the Trash for good", consequence)
+        return client.post("/api/v1/programs/trash/empty")
+    if args.program is None:
+        raise api_client.CliError("name the PROGRAM to purge, or pass --all to empty the Trash")
+    program_id, trashed = _resolve(client, args.program)
+    if trashed is False:
+        raise api_client.CliError(
+            f"{args.program} is live, and only a program in the Trash can be purged. "
+            f"Move it there first with `{top.hint_programs('trash', args.program)}`."
+        )
+    provider_credentials.confirm(args, f"the program {args.program} for good", consequence)
+    return client.post(f"/api/v1/programs/{program_id}/purge")

{cmpnd-0.55.0 → cmpnd-0.56.0}/cmpnd/cli/commands/top.py

@@ -213,6 +213,11 @@ def hint_programs_create(name: str = "capital-qa") -> str:
     return f"cmpnd programs create {name}"
 
 
+def hint_programs(verb: str, *args: str) -> str:
+    """How to run a ``cmpnd programs`` verb with ARGS. The shell has no programs verb, so this is the CLI form."""
+    return " ".join(("cmpnd programs", verb, *args))
+
+
 def _hint_status(deployment_id: str, follow: bool = False) -> str:
     short = _short_id(deployment_id)
     if _SHELL_MODE:

{cmpnd-0.55.0 → cmpnd-0.56.0}/cmpnd/cli/verbs.py

@@ -160,6 +160,9 @@ DOMAIN_VERBS: dict[str, str] = {
     "deny": "the negative half of allow; the tool stays listed and stops being callable",
     "switch": "moves a local pointer among stored keys; nothing on the server changes",
     "leave": "removes your own membership, which is not deleting the org or anyone else's place in it",
+    "trash": "moves a program to the Trash, where it stays restorable, and delete would read as the permanent purge",
+    "restore": "returns a program from the Trash with its history, which create would not",
+    "purge": "deletes a program in the Trash for good, the irreversible step after trash",
 }
 
 #: Leaves naming a related collection or sub-record rather than an action.

{cmpnd-0.55.0 → cmpnd-0.56.0}/cmpnd/programs.py

@@ -29,7 +29,7 @@ def send_resolve(client: _http.ApiClient, name: str) -> dict[str, Any] | None:
 
     The answer is ``{"program_id", "name", "created"}``. ``created`` is true when this
     request made the program. Returns None when the server has no program names, and
-    raises :class:`cmpnd.ApiError` for any other refusal, such as a purged name.
+    raises :class:`cmpnd.ApiError` for any other refusal, such as the plan's program limit.
 
     The request is idempotent: serve gives one name one program, so a retried request
     that lost its answer finds the program the first request made.

{cmpnd-0.55.0 → cmpnd-0.56.0}/docs/cli.md

@@ -41,6 +41,47 @@ The CLI refuses `--program-id`, `cmpnd programs create` without a program
 name, and its `--name`. These inputs are deprecated, and the error shows the
 program name form.
 
+## The Trash
+
+A program in the Trash leaves every view, and its traces with it, until it is
+restored or purged. The web app's program page moves a program there with Move
+to Trash, and these commands do the same from a terminal. Each takes a program
+name or a `p_` id. The CLI looks a name up with
+`GET /api/v1/programs/by-name/{name}`, which finds a program in the Trash too,
+and sends the id.
+
+- `cmpnd programs trash PROGRAM` moves a live program to the Trash. A program
+  already there is left alone.
+- `cmpnd programs list --trashed` lists the whole Trash, newest first, with
+  when each program is purged. It takes no filter, sort or paging flag.
+- `cmpnd programs restore PROGRAM` returns a program from the Trash.
+- `cmpnd programs purge PROGRAM` deletes a program in the Trash for good, and
+  `cmpnd programs purge --all` empties the Trash. Nothing restores a purged
+  program. Both ask for confirmation at a terminal and need `--force` anywhere
+  else. A live program is never purged.
+  A program created by name cannot be purged yet. It stays in the Trash, where
+  it no longer counts toward a plan's program cap, and `purge --all` answers
+  how many such programs it kept.
+
+A program in the Trash or purged gives up its name. The next
+`cmpnd programs create`, `cmpnd deploy` or SDK run under that name gets a new
+program. Restore the old one by its `p_` id, which `cmpnd programs list
+--trashed` prints, and it comes back without the name.
+
+The purge job purges a program 7 days after it entered the Trash. Listing the
+Trash needs `traces:read`, and the other commands need `traces:write` or
+`optimizations:write`.
+
+A plan may cap an organization's live programs, the ones outside the Trash
+that no optimization produced. At the cap, a new program name in
+`cmpnd programs create`, `cmpnd deploy` or `cmpnd optimize` and
+`cmpnd programs restore` are refused with a message that says how many the
+plan allows and how to free one. A live program's name always resolves. A name
+that only a program in the Trash answers to goes to a new program, which needs
+a free place like any other. Moving a program to the Trash frees its place at
+once. `cmpnd programs list --trashed` reports `live_programs` and
+`program_limit`, which is null when no cap applies.
+
 ## When the server no longer supports your release
 
 Every answer from the platform names the oldest `cmpnd` release it supports.
@@ -276,8 +317,9 @@ The `signatures` and `programs` groups name programs differently.
 hash, which identifies a program's inputs and outputs and everything recorded
 under them: traces, examples, evals and revisions. The CLI passes an id
 through unchanged, and serve tells the two apart by the `p_` prefix.
-`cmpnd programs` takes a compiled program hash, the value in the
-`program_hash` column of `cmpnd programs list`. Its routes resolve the hash
+`cmpnd programs` reads take a compiled program hash, the value in the
+`program_hash` column of `cmpnd programs list`, and its Trash commands take a
+program name or id ("The Trash" above). Its routes resolve the hash
 through optimization runs, so they do not find a signature hash. Each group's
 `--help` names the column its IDs come from.
 

{cmpnd-0.55.0 → cmpnd-0.56.0}/docs/sdk-instrumentation.md

@@ -843,6 +843,9 @@ trace bodies, at the top level and in `started_fact`, before it compares or send
 - **A refusal settles the name with no id.** Serve answers 404 or 405 when it has no
   program names, as self-host release 2026-001 does, and 409, 422 or 403 for a name it
   will not resolve. The traces go without an id, and the exporter warns once per name.
+  An organization with as many live programs as its plan allows gets a 409 for a new
+  name, whose text says how to free one. The name stays settled for the process, so a
+  process started after a program was moved to the Trash resolves it.
 - **An outage leaves the name unsettled.** A 5xx, a 429 or an unreachable server is
   retried with backoff, wider than the data sends' rule because the request is a
   get-or-create that a repeat cannot double. The names in one batch share one retry

{cmpnd-0.55.0 → cmpnd-0.56.0}/pyproject.toml

@@ -5,7 +5,7 @@ name = "cmpnd"
 # it's new) — no git tags. Bump with `uv version --bump {minor,patch}` or by
 # hand. Runtime `cmpnd.__version__` reads installed metadata, so it tracks
 # this automatically. See docs/plans/2026-07-02-sdk-pypi-tag-free-publish.md.
-version = "0.55.0"
+version = "0.56.0"
 description = "DSPy observability and deployment SDK for cmpnd"
 readme = "README.md"
 requires-python = ">=3.11"

cmpnd-0.56.0/tests/test_cli/test_programs.py

@@ -0,0 +1,290 @@
+"""Tests for cmpnd.cli.commands.programs."""
+
+from __future__ import annotations
+
+import argparse
+
+import pytest
+
+from cmpnd.cli.api_client import CliError
+from cmpnd.cli.commands import programs
+from cmpnd.cli.commands.programs import (
+    handle_list,
+    handle_registry_list,
+    handle_registry_show,
+    handle_select,
+    handle_show,
+    handle_stats,
+    handle_traces,
+    handle_usage,
+)
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="cmpnd")
+    sub = parser.add_subparsers(dest="resource")
+    programs.register(sub)
+    return parser
+
+
+class TestProgramsList:
+    def test_default_params(self, mock_client):
+        mock_client.get.return_value = {"programs": []}
+        args = argparse.Namespace(
+            program_name=None, model_name=None, order_by="run_count", order="desc", limit=50, offset=0
+        )
+        result = handle_list(mock_client, args)
+        mock_client.get.assert_called_once_with(
+            "/api/v1/programs/v2",
+            params={"page": "1", "per_page": "50", "order_by": "run_count", "order_direction": "desc"},
+        )
+        assert result == {"programs": []}
+
+    def test_with_filters(self, mock_client):
+        mock_client.get.return_value = {"programs": []}
+        args = argparse.Namespace(
+            program_name="RAG", model_name="gpt-4o", order_by="run_count", order="asc", limit=10, offset=10
+        )
+        handle_list(mock_client, args)
+        params = mock_client.get.call_args[1]["params"]
+        assert params["program_name"] == "RAG"
+        assert params["model_name"] == "gpt-4o"
+        assert params["page"] == "2"
+
+    def test_deprecated_paging_still_works_and_warns(self, mock_client, capsys):
+        parser = _build_parser()
+        args = parser.parse_args(["programs", "list", "--page", "2", "--per-page", "5"])
+        mock_client.get.return_value = {"programs": []}
+        handle_list(mock_client, args)
+        params = mock_client.get.call_args[1]["params"]
+        assert params["page"] == "2"
+        assert params["per_page"] == "5"
+        assert "deprecated" in capsys.readouterr().err
+
+    def test_non_multiple_offset_errors(self, mock_client):
+        parser = _build_parser()
+        args = parser.parse_args(["programs", "list", "--limit", "10", "--offset", "5"])
+        with pytest.raises(CliError):
+            handle_list(mock_client, args)
+
+
+class TestProgramsShow:
+    def test_calls_correct_endpoint(self, mock_client):
+        mock_client.get.return_value = {"program_hash": 123}
+        args = argparse.Namespace(id="123")
+        result = handle_show(mock_client, args)
+        mock_client.get.assert_called_once_with("/api/v1/programs/123")
+        assert result["program_hash"] == 123
+
+
+class TestProgramsTraces:
+    def test_calls_correct_endpoint(self, mock_client):
+        mock_client.get.return_value = {"traces": []}
+        args = argparse.Namespace(id="456", limit=10, offset=5)
+        result = handle_traces(mock_client, args)
+        mock_client.get.assert_called_once_with("/api/v1/programs/456/traces", params={"limit": "10", "offset": "5"})
+        assert result == {"traces": []}
+
+
+class TestProgramsStats:
+    def test_calls_correct_endpoint(self, mock_client):
+        mock_client.get.return_value = {"trace_count": 12}
+        result = handle_stats(mock_client, argparse.Namespace(id="789"))
+        mock_client.get.assert_called_once_with("/api/v1/programs/789/execution-stats")
+        assert result == {"trace_count": 12}
+
+
+class TestProgramsUsage:
+    def test_sends_the_default_window(self, mock_client):
+        mock_client.get.return_value = {"history": []}
+        handle_usage(mock_client, argparse.Namespace(id="789", hours=24, period=None))
+        mock_client.get.assert_called_once_with("/api/v1/programs/789/usage-history", params={"hours": "24"})
+
+    def test_period_is_sent_only_when_given(self, mock_client):
+        mock_client.get.return_value = {"history": []}
+        handle_usage(mock_client, argparse.Namespace(id="789", hours=6, period="minute"))
+        assert mock_client.get.call_args[1]["params"] == {"hours": "6", "period": "minute"}
+
+    def test_parser_rejects_an_unknown_period(self):
+        # An unrecognised period buckets hourly server-side rather than failing,
+        # so a typo would answer a different question than the one asked.
+        parser = _build_parser()
+        with pytest.raises(SystemExit):
+            parser.parse_args(["programs", "usage", "789", "--period", "fortnight"])
+
+
+class TestProgramsRegistry:
+    def test_list_uses_limit_offset(self, mock_client):
+        mock_client.get.return_value = {"programs": [], "total": 0}
+        handle_registry_list(mock_client, argparse.Namespace(limit=25, offset=50))
+        mock_client.get.assert_called_once_with("/api/v1/programs/registry", params={"limit": "25", "offset": "50"})
+
+    def test_show_calls_correct_endpoint(self, mock_client):
+        mock_client.get.return_value = {"registry": {}}
+        handle_registry_show(mock_client, argparse.Namespace(id="reg-1"))
+        mock_client.get.assert_called_once_with("/api/v1/programs/registry/reg-1")
+
+    def test_registry_is_a_nested_group(self):
+        parser = _build_parser()
+        assert parser.parse_args(["programs", "registry", "list"]).func is programs.handle_registry_list
+        assert parser.parse_args(["programs", "registry", "show", "reg-1"]).func is programs.handle_registry_show
+
+
+class TestProgramsSelect:
+    def test_posts_the_key_the_server_reads(self, mock_client):
+        mock_client.post.return_value = {"status": "selected"}
+        result = handle_select(mock_client, argparse.Namespace(id="789", run_id="op_abc"))
+        mock_client.post.assert_called_once_with("/api/v1/programs/789/select", json={"optimization_run_id": "op_abc"})
+        assert result == {"status": "selected"}
+
+    def test_run_id_is_required(self):
+        parser = _build_parser()
+        with pytest.raises(SystemExit):
+            parser.parse_args(["programs", "select", "789"])
+
+
+def _named(program_id: str, name: str, *, trashed: bool) -> dict[str, object]:
+    return {"program_id": program_id, "name": name, "created": False, "trashed": trashed}
+
+
+class TestProgramsTrash:
+    def test_a_name_resolves_then_moves_to_the_trash(self, mock_client):
+        mock_client.get.return_value = _named("p_0123456789Ab", "triage", trashed=False)
+        mock_client.post.return_value = {"program_id": "p_0123456789Ab", "trashed": True}
+        args = _build_parser().parse_args(["programs", "trash", "triage"])
+        result = args.func(mock_client, args)
+        mock_client.get.assert_called_once_with("/api/v1/programs/by-name/triage")
+        mock_client.post.assert_called_once_with("/api/v1/programs/p_0123456789Ab/trash")
+        assert result == {"program_id": "p_0123456789Ab", "trashed": True}
+
+    def test_a_program_id_goes_straight_to_the_route(self, mock_client):
+        mock_client.post.return_value = {"program_id": "p_0123456789Ab", "trashed": True}
+        args = _build_parser().parse_args(["programs", "trash", "p_0123456789Ab"])
+        args.func(mock_client, args)
+        mock_client.get.assert_not_called()
+        mock_client.post.assert_called_once_with("/api/v1/programs/p_0123456789Ab/trash")
+
+    def test_a_name_already_in_the_trash_is_not_moved_again(self, mock_client, capsys):
+        mock_client.get.return_value = _named("p_0123456789Ab", "triage", trashed=True)
+        args = _build_parser().parse_args(["programs", "trash", "triage"])
+        result = args.func(mock_client, args)
+        mock_client.post.assert_not_called()
+        assert result == {"program_id": "p_0123456789Ab", "trashed": True}
+        assert "already in the Trash" in capsys.readouterr().err
+
+    def test_an_unknown_name_says_so(self, mock_client):
+        mock_client.get.side_effect = CliError("no program has this name", status_code=404)
+        args = _build_parser().parse_args(["programs", "trash", "nobody"])
+        with pytest.raises(CliError, match="no program in your organization is named 'nobody'"):
+            args.func(mock_client, args)
+        mock_client.post.assert_not_called()
+
+    def test_a_name_resolves_through_the_by_name_route(self, mock_client):
+        mock_client.get.return_value = _named("p_0123456789Ab", "a.b_c", trashed=False)
+        args = _build_parser().parse_args(["programs", "trash", "a.b_c"])
+        args.func(mock_client, args)
+        mock_client.get.assert_called_once_with("/api/v1/programs/by-name/a.b_c")
+
+    def test_a_bad_name_fails_before_any_request(self, mock_client):
+        args = _build_parser().parse_args(["programs", "trash", "has space"])
+        with pytest.raises(CliError, match="not a valid program name"):
+            args.func(mock_client, args)
+        mock_client.get.assert_not_called()
+
+
+class TestProgramsRestore:
+    def test_restores_a_trashed_name(self, mock_client):
+        mock_client.get.return_value = _named("p_0123456789Ab", "triage", trashed=True)
+        mock_client.post.return_value = {"program_id": "p_0123456789Ab", "trashed": False}
+        args = _build_parser().parse_args(["programs", "restore", "triage"])
+        args.func(mock_client, args)
+        mock_client.post.assert_called_once_with("/api/v1/programs/p_0123456789Ab/restore")
+
+    def test_a_live_name_is_not_in_the_trash(self, mock_client):
+        mock_client.get.return_value = _named("p_0123456789Ab", "triage", trashed=False)
+        args = _build_parser().parse_args(["programs", "restore", "triage"])
+        with pytest.raises(CliError, match="not in the Trash") as refused:
+            args.func(mock_client, args)
+        assert "`cmpnd programs list --trashed`" in str(refused.value)
+        mock_client.post.assert_not_called()
+
+
+class TestProgramsPurge:
+    def test_purge_needs_force_off_a_terminal(self, mock_client, monkeypatch):
+        monkeypatch.setattr("sys.stdin.isatty", lambda: False)
+        mock_client.get.return_value = _named("p_0123456789Ab", "triage", trashed=True)
+        args = _build_parser().parse_args(["programs", "purge", "triage"])
+        with pytest.raises(CliError, match="--force"):
+            args.func(mock_client, args)
+        mock_client.post.assert_not_called()
+
+    def test_purge_with_force_purges(self, mock_client):
+        mock_client.get.return_value = _named("p_0123456789Ab", "triage", trashed=True)
+        mock_client.post.return_value = {"program_id": "p_0123456789Ab", "purged": True}
+        args = _build_parser().parse_args(["programs", "purge", "triage", "--force"])
+        assert args.func(mock_client, args) == {"program_id": "p_0123456789Ab", "purged": True}
+        mock_client.post.assert_called_once_with("/api/v1/programs/p_0123456789Ab/purge")
+
+    def test_a_live_program_is_never_purged(self, mock_client):
+        mock_client.get.return_value = _named("p_0123456789Ab", "triage", trashed=False)
+        args = _build_parser().parse_args(["programs", "purge", "triage", "--force"])
+        with pytest.raises(CliError, match="cmpnd programs trash triage"):
+            args.func(mock_client, args)
+        mock_client.post.assert_not_called()
+
+    def test_all_with_force_empties_the_trash_without_listing_it(self, mock_client):
+        # Listing needs traces:read, so --force skips it and a key that may only write still empties the Trash.
+        mock_client.post.return_value = {"purged": 1, "kept": 0}
+        args = _build_parser().parse_args(["programs", "purge", "--all", "--force"])
+        assert args.func(mock_client, args) == {"purged": 1, "kept": 0}
+        mock_client.get.assert_not_called()
+        mock_client.post.assert_called_once_with("/api/v1/programs/trash/empty")
+
+    def test_all_confirms_with_the_count_at_a_terminal(self, mock_client, monkeypatch):
+        mock_client.get.return_value = {"programs": [{"program_id": "p_0123456789Ab"}] * 2, "retention_days": 7}
+        mock_client.post.return_value = {"purged": 2, "kept": 0}
+        monkeypatch.setattr("sys.stdin.isatty", lambda: True)
+        prompts: list[str] = []
+        monkeypatch.setattr("builtins.input", lambda prompt: prompts.append(prompt) or "yes")
+        args = _build_parser().parse_args(["programs", "purge", "--all"])
+        assert args.func(mock_client, args) == {"purged": 2, "kept": 0}
+        mock_client.get.assert_called_once_with("/api/v1/programs/trash")
+        mock_client.post.assert_called_once_with("/api/v1/programs/trash/empty")
+        assert prompts
+
+    def test_all_with_an_empty_trash_sends_nothing(self, mock_client):
+        mock_client.get.return_value = {"programs": [], "retention_days": 7}
+        args = _build_parser().parse_args(["programs", "purge", "--all"])
+        assert args.func(mock_client, args) == {"purged": 0, "kept": 0}
+        mock_client.post.assert_not_called()
+
+    def test_all_and_a_program_together_are_refused(self, mock_client):
+        args = _build_parser().parse_args(["programs", "purge", "triage", "--all", "--force"])
+        with pytest.raises(CliError, match="either"):
+            args.func(mock_client, args)
+        mock_client.get.assert_not_called()
+        mock_client.post.assert_not_called()
+
+
+class TestProgramsListTrashed:
+    def test_lists_the_trash(self, mock_client):
+        mock_client.get.return_value = {"programs": [], "retention_days": 7}
+        args = _build_parser().parse_args(["programs", "list", "--trashed"])
+        assert args.func(mock_client, args) == {"programs": [], "retention_days": 7}
+        mock_client.get.assert_called_once_with("/api/v1/programs/trash")
+
+    def test_search_filters_do_not_apply(self, mock_client):
+        args = _build_parser().parse_args(["programs", "list", "--trashed", "--name", "x"])
+        with pytest.raises(CliError, match="--name does not apply"):
+            args.func(mock_client, args)
+        mock_client.get.assert_not_called()
+
+    @pytest.mark.parametrize(
+        "flag",
+        [["--order-by", "name"], ["--order", "asc"], ["--limit", "5"], ["--offset", "10"]],
+    )
+    def test_paging_and_sort_do_not_apply(self, mock_client, flag):
+        args = _build_parser().parse_args(["programs", "list", "--trashed", *flag])
+        with pytest.raises(CliError, match=f"{flag[0]} does not apply"):
+            args.func(mock_client, args)
+        mock_client.get.assert_not_called()

{cmpnd-0.55.0 → cmpnd-0.56.0}/uv.lock

@@ -496,7 +496,7 @@ wheels = [
 
 [[package]]
 name = "cmpnd"
-version = "0.55.0"
+version = "0.56.0"
 source = { editable = "." }
 dependencies = [
     { name = "dspy" },