cmpnd 0.59.0__tar.gz → 0.61.0__tar.gz

{cmpnd-0.59.0 → cmpnd-0.61.0}/PKG-INFO

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

cmpnd-0.61.0/cmpnd/cli/commands/programs.py

@@ -0,0 +1,599 @@
+"""Programs commands."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+import urllib.parse
+from argparse import ArgumentParser, _SubParsersAction
+from typing import Any
+
+from .. import api_client, pagination
+from . import provider_credentials
+
+
+# `show`, `traces`, `stats` and `usage` take a program name or a p_ id, as the
+# Trash commands do. The `programs optimized` group and `select` take a compiled
+# program hash, the value `programs optimized list` prints as `program_hash`.
+# The routes resolve that hash against optimization runs, so a program
+# signature hash 404s there. A compiled hash and a program name have the same
+# shape, so no command takes both in one slot.
+def register(subparsers: _SubParsersAction[ArgumentParser]) -> None:
+    parser = subparsers.add_parser("programs", help="Create and browse programs")
+    sub = parser.add_subparsers(dest="action")
+
+    create = sub.add_parser(
+        "create",
+        help="Create a program with a name",
+        description=(
+            "Create a program with PROGRAM_NAME in your organization. A program name that already "
+            "has a program is refused. A deploy makes the program the first time it uses the program "
+            "name, so this command is needed only to make the program first. Deploy under the program "
+            "name with `cmpnd deploy SOURCE PROGRAM_NAME`, and declare it in Python with "
+            "cmpnd.Program(PROGRAM_NAME, module=..., lm=...)."
+        ),
+    )
+    create.add_argument(
+        "name", nargs="?", default=None, metavar="PROGRAM_NAME", help="Program name, unique in your organization"
+    )
+    # Deprecated program id input: --name, the display name of an unnamed program, is refused, and goes when the
+    # deprecated inputs are stripped out. It stays declared so that a command that passes it gets an error naming
+    # the program name form.
+    create.add_argument(
+        "--name",
+        dest="display_name",
+        default=None,
+        help=argparse.SUPPRESS,
+    )
+    create.add_argument("--json", action="store_true", help="Emit the created program as JSON instead of its id")
+    create.set_defaults(func=handle_create)
+
+    ls = sub.add_parser(
+        "list",
+        help="List your organization's programs",
+        description=(
+            "List your organization's live programs, newest first, with each program's name and p_ id. A program "
+            "lists from its creation on, before anything runs under it. With --trashed, list the Trash instead."
+        ),
+    )
+    ls.add_argument(
+        "--trashed",
+        action="store_true",
+        help="List the programs in the Trash instead, with when each is purged",
+    )
+    pagination.add_args(ls, with_page_aliases=True, default_limit=50)
+    # The optimized-program filters and sort moved to `programs optimized list`. They stay declared so that a
+    # command that passes one gets an error naming the command that takes it.
+    for flag, dest in [
+        ("--name", "program_name"),
+        ("--model", "model_name"),
+        ("--order-by", "order_by"),
+        ("--order", "order"),
+    ]:
+        ls.add_argument(flag, dest=dest, default=None, help=argparse.SUPPRESS)
+    ls.set_defaults(func=handle_list)
+
+    # The optimized programs are the compiled programs optimization runs produced, grouped by compiled program
+    # hash. They are different records from the org's programs, so they nest, as the registry does.
+    optimized = sub.add_parser("optimized", help="Browse the optimized programs that optimization runs produced")
+    optimized_sub = optimized.add_subparsers(dest="optimized_action")
+    opt_list = optimized_sub.add_parser(
+        "list",
+        help="List optimized programs by compiled program hash",
+        description=(
+            "List the compiled programs your optimization runs produced, one row per compiled program hash, with "
+            "their run counts and scores. `programs optimized show`, `traces`, `stats` and `usage` take the hash "
+            "from the "
+            "program_hash column."
+        ),
+    )
+    opt_list.add_argument("--name", dest="program_name", help="Filter by program name")
+    opt_list.add_argument("--model", dest="model_name", help="Filter by model name")
+    opt_list.add_argument("--order-by", default="run_count", help="Sort field (default: run_count)")
+    opt_list.add_argument("--order", default="desc", choices=["asc", "desc"], help="Sort direction")
+    pagination.add_args(opt_list, with_page_aliases=True, default_limit=50)
+    opt_list.set_defaults(func=handle_optimized_list)
+
+    opt_show = optimized_sub.add_parser("show", help="Show the optimization runs that produced a compiled program")
+    opt_show.add_argument("hash", help=_COMPILED_HASH_HELP)
+    opt_show.set_defaults(func=handle_optimized_show)
+
+    opt_traces = optimized_sub.add_parser("traces", help="List the traces of a compiled program's program")
+    opt_traces.add_argument("hash", help=_COMPILED_HASH_HELP)
+    pagination.add_args(opt_traces, with_page_aliases=False, default_limit=50)
+    opt_traces.set_defaults(func=handle_optimized_traces)
+
+    opt_stats = optimized_sub.add_parser("stats", help="Show the execution statistics of a compiled program's program")
+    opt_stats.add_argument("hash", help=_COMPILED_HASH_HELP)
+    opt_stats.set_defaults(func=handle_optimized_stats)
+
+    opt_usage = optimized_sub.add_parser("usage", help="Show the usage over time of a compiled program's program")
+    opt_usage.add_argument("hash", help=_COMPILED_HASH_HELP)
+    _add_usage_window(opt_usage)
+    opt_usage.set_defaults(func=handle_optimized_usage)
+
+    show = sub.add_parser(
+        "show",
+        help="Show a program",
+        description=(
+            "Show PROGRAM: its name, p_ id, whether it is in the Trash, its trace count and latest trace, and "
+            "the optimized programs its optimization runs produced."
+        ),
+    )
+    show.add_argument("program", metavar="PROGRAM", help="Program name or p_ id")
+    show.set_defaults(func=handle_show)
+
+    tr = sub.add_parser(
+        "traces",
+        help="List a program's traces, newest first, over the widest window trace search reads",
+        description=(
+            "List PROGRAM's traces, newest first, through trace search over its widest window, 365 days. "
+            "`cmpnd traces list --hash ID --since DATE` sets the window itself. --limit is at most 500."
+        ),
+    )
+    tr.add_argument("program", metavar="PROGRAM", help="Program name or p_ id")
+    pagination.add_args(tr, with_page_aliases=False, default_limit=50)
+    tr.set_defaults(func=handle_traces)
+
+    stats = sub.add_parser("stats", help="Show a program's execution statistics over all history")
+    stats.add_argument("program", metavar="PROGRAM", help="Program name or p_ id")
+    stats.set_defaults(func=handle_stats)
+
+    usage = sub.add_parser("usage", help="Show a program's trace volume, tokens and cost over time")
+    usage.add_argument("program", metavar="PROGRAM", help="Program name or p_ id")
+    _add_usage_window(usage)
+    usage.set_defaults(func=handle_usage)
+
+    # The registry is the programs an SDK client registered, as distinct from
+    # the optimized programs `programs list` aggregates out of runs — different
+    # records, so they nest rather than share a flat verb.
+    registry = sub.add_parser("registry", help="Browse the program registry")
+    registry_sub = registry.add_subparsers(dest="registry_action")
+
+    reg_list = registry_sub.add_parser("list", help="List registered programs")
+    pagination.add_args(reg_list, with_page_aliases=False, default_limit=50)
+    reg_list.set_defaults(func=handle_registry_list)
+
+    reg_show = registry_sub.add_parser("show", help="Show a registry entry and its signatures")
+    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=_COMPILED_HASH_HELP)
+    select.add_argument("--run", dest="run_id", required=True, help="Optimization run ID (op_...) to pin")
+    select.set_defaults(func=handle_select)
+
+
+_COMPILED_HASH_HELP = "Compiled program hash, as `programs optimized list` prints it in the program_hash column"
+
+
+def _add_usage_window(parser: ArgumentParser) -> None:
+    parser.add_argument("--hours", type=int, default=24, help="Rolling window in hours (default %(default)s)")
+    # Constrained on purpose: an unrecognised period buckets hourly server-side
+    # rather than failing, so a typo would answer a different question silently.
+    parser.add_argument(
+        "--period",
+        choices=["minute", "5m", "10m", "30m", "hour", "day"],
+        help="Bucket width (default: hour)",
+    )
+
+
+def _usage_params(args: Any) -> dict[str, str]:
+    params = {"hours": str(args.hours)}
+    if args.period:
+        params["period"] = args.period
+    return params
+
+
+def handle_create(client: api_client.ApiClient, args: Any) -> Any:
+    """Create the program named ``args.name``, and refuse a name that already has one.
+
+    Prints the bare id on stdout and says what it made on stderr; ``--json`` returns
+    serve's whole answer instead, printed like the group's reads. The program name is
+    the only form: a create without one, and ``--name``, are refused.
+    """
+    from ... import programs
+    from . import top
+
+    # Deprecated program id input: both refusals go when the deprecated inputs are stripped out.
+    if args.display_name is not None:
+        top.refuse_deprecated_program_id_input("`cmpnd programs create --name`", top.hint_programs_create())
+    if args.name is None:
+        top.refuse_deprecated_program_id_input(
+            "`cmpnd programs create` without a program name", top.hint_programs_create()
+        )
+    try:
+        answer = programs.send_resolve(client, args.name)
+    except ValueError as exc:
+        raise api_client.CliError(str(exc)) from exc
+    if answer is None:
+        raise api_client.CliError(
+            "This server has no program names, so it cannot create a program from a program name. A serve from "
+            "before program names, such as self-host release 2026-001, needs no program first: "
+            f"`{top._hint_program_name('deploy', source='SOURCE', name='PROGRAM_NAME')}` deploys there without "
+            "a program id."
+        )
+    if not answer.get("created"):
+        raise api_client.CliError(
+            f"the program name {args.name!r} already has a program, {answer['program_id']}. "
+            f"Deploy under it with `{top._hint_program_name('deploy', source='SOURCE', name=args.name)}`."
+        )
+    if getattr(args, "json", False):
+        return answer
+    print(answer["program_id"])
+    print(f"created program {answer['program_id']} named {args.name}", file=sys.stderr)
+    return None
+
+
+def handle_list(client: api_client.ApiClient, args: Any) -> Any:
+    """List the org's live programs by name and p_ id, or the Trash with ``--trashed``."""
+    for attr, flag in [
+        ("program_name", "--name"),
+        ("model_name", "--model"),
+        ("order_by", "--order-by"),
+        ("order", "--order"),
+    ]:
+        if getattr(args, attr, None) is not None:
+            from . import top
+
+            raise api_client.CliError(
+                f"{flag} filters the optimized programs, which `{top.hint_programs('optimized', 'list')}` lists. "
+                f"`{top.hint_programs('list')}` lists your organization's programs by name and p_ id."
+            )
+    if getattr(args, "trashed", False):
+        # The Trash is its own short list, unpaged and newest first, so paging does not apply. A flag left at its
+        # default cannot be told apart from one not passed.
+        for attr, flag, default in [
+            ("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 _trash_listing(client)
+    params = pagination.wire(args, "limit_offset", as_str=True)
+    # Read as text: a server from before the program list, such as self-host release 2026-001, redirects this
+    # path to its dispatcher, and the redirect's body is HTML.
+    try:
+        raw = client.get_text("/api/v1/programs", params=params)
+    except api_client.CliError as exc:
+        if exc.status_code not in (404, 405):
+            raise
+        return _list_recorded(client, params)
+    try:
+        listed = json.loads(raw)
+    except ValueError:
+        listed = None
+    if isinstance(listed, dict) and "programs" in listed:
+        return listed
+    return _list_recorded(client, params)
+
+
+# GET /api/v1/modules on a server from before the program list answers at most this many programs
+# (modulesPageCap in self-host release 2026-001), and nothing pages past them.
+_RECORDED_PROGRAMS_CAP = 200
+
+
+def _list_recorded(client: api_client.ApiClient, params: dict[str, str]) -> dict[str, Any]:
+    """List the programs a server from before the program list recorded traces for, paged here.
+
+    GET /api/v1/modules answers them in one array, by name and legacy hash, up to its cap. A program with no
+    traces yet is not in it. A full array may be missing programs past the cap, so the answer then has no total
+    and says it is incomplete.
+    """
+    rows = client.get("/api/v1/modules")
+    if not isinstance(rows, list):
+        raise api_client.CliError(
+            "this cmpnd server answered neither the program list nor the list of recorded programs"
+        )
+    complete = len(rows) < _RECORDED_PROGRAMS_CAP
+    note = "note: this cmpnd server predates the program list, so this lists the programs it recorded traces for."
+    if not complete:
+        note += f" It answers at most {_RECORDED_PROGRAMS_CAP} of them, so programs past those are missing."
+    print(note + " Upgrade the server to list every program by name and p_ id.", file=sys.stderr)
+    limit, offset = int(params["limit"]), int(params["offset"])
+    return {
+        "programs": rows[offset : offset + limit],
+        "total": len(rows) if complete else None,
+        "complete": complete,
+        "limit": limit,
+        "offset": offset,
+        "has_more": offset + limit < len(rows),
+    }
+
+
+def handle_optimized_list(client: api_client.ApiClient, args: Any) -> Any:
+    """List the optimized programs, one row per compiled program hash."""
+    params: dict[str, str] = pagination.wire(args, "per_page", as_str=True)
+    params["order_by"] = args.order_by
+    params["order_direction"] = args.order
+    if args.program_name:
+        params["program_name"] = args.program_name
+    if args.model_name:
+        params["model_name"] = args.model_name
+    return client.get("/api/v1/programs/v2", params=params)
+
+
+# A server from before program names, p_ ids and the Trash API, such as self-host release 2026-001, reads every
+# path under /api/v1/programs/ as a compiled program hash. A GET there answers 404 and a POST answers 405, and its
+# trace search ignores program_id. A current server answers the Trash listing with 200, so that read tells them
+# apart once a command has already failed.
+_OLD_SERVER = "this cmpnd server predates program names, p_ ids and the Trash API, as self-host release 2026-001 does."
+
+
+def _predates_program_ids(client: api_client.ApiClient) -> bool:
+    try:
+        client.get("/api/v1/programs/trash")
+    except api_client.CliError as exc:
+        return exc.status_code == 404
+    return False
+
+
+def _old_server_refusal(remedy: str) -> api_client.CliError:
+    return api_client.CliError(f"{_OLD_SERVER} {remedy}")
+
+
+def _refuse_if_old(client: api_client.ApiClient, exc: api_client.CliError, remedy: str) -> None:
+    """Raise the old-server refusal in place of ``exc`` when the server predates program ids."""
+    if exc.status_code in (404, 405) and _predates_program_ids(client):
+        raise _old_server_refusal(remedy) from exc
+
+
+def _trash_remedy() -> str:
+    return "Manage its Trash in the web app, at /ui/account/trash, or upgrade the server."
+
+
+def _read_remedy(verb: str) -> str:
+    from . import top
+
+    return (
+        f"`{top.hint_programs('optimized', verb, 'HASH')}` reads a compiled program hash there, and "
+        f"`{top.hint_programs('list')}` lists the programs it recorded traces for."
+    )
+
+
+def _resolve_for_read(client: api_client.ApiClient, ref: str, verb: str, *, trashed_ok: bool = False) -> str:
+    """Return the p_ id of the program ``ref`` names, for a read of its activity.
+
+    A program in the Trash has no activity to read, so it is refused unless
+    ``trashed_ok``. An unknown name may be a compiled program hash, which the
+    ``programs optimized`` command of the same verb takes.
+    """
+    from . import top
+
+    program_id, trashed = resolve(
+        client,
+        ref,
+        unknown_hint=f"A compiled program hash goes to `{top.hint_programs('optimized', verb, ref)}`.",
+        old_server_remedy=_read_remedy(verb),
+    )
+    if trashed and not trashed_ok:
+        raise api_client.CliError(
+            f"{ref} is in the Trash, so it has no activity to read. "
+            f"Restore it with `{top.hint_programs('restore', ref)}`."
+        )
+    return program_id
+
+
+def _read(client: api_client.ApiClient, verb: str, path: str, params: dict[str, str] | None = None) -> Any:
+    try:
+        return client.get(path) if params is None else client.get(path, params=params)
+    except api_client.CliError as exc:
+        _refuse_if_old(client, exc, _read_remedy(verb))
+        raise
+
+
+def handle_show(client: api_client.ApiClient, args: Any) -> Any:
+    program_id = _resolve_for_read(client, args.program, "show", trashed_ok=True)
+    return _read(client, "show", f"/api/v1/programs/{program_id}")
+
+
+# Trace search reads a page_size above this as its default of 50, which would answer other rows than the ones asked
+# for.
+_MAX_TRACE_PAGE = 500
+
+
+def handle_traces(client: api_client.ApiClient, args: Any) -> Any:
+    """List the program's traces through trace search, which takes a program id, over its widest window."""
+    if args.limit > _MAX_TRACE_PAGE:
+        raise api_client.CliError(
+            f"--limit is at most {_MAX_TRACE_PAGE}, the largest page trace search returns. Page with --offset."
+        )
+    program_id = _resolve_for_read(client, args.program, "traces")
+    body: dict[str, Any] = {"program_id": program_id, **pagination.wire(args, "page_size"), "max_window": True}
+    answer = client.post("/api/v1/traces/search", json=body)
+    # A server that ignores program_id answers every trace in the org, which must not pass for the program's.
+    if "program_id" in (answer.get("ignored_fields") or []):
+        raise _old_server_refusal(_read_remedy("traces"))
+    return answer
+
+
+def handle_stats(client: api_client.ApiClient, args: Any) -> Any:
+    program_id = _resolve_for_read(client, args.program, "stats")
+    return _read(client, "stats", f"/api/v1/programs/{program_id}/execution-stats")
+
+
+def handle_usage(client: api_client.ApiClient, args: Any) -> Any:
+    program_id = _resolve_for_read(client, args.program, "usage")
+    return _read(client, "usage", f"/api/v1/programs/{program_id}/usage-history", _usage_params(args))
+
+
+def handle_optimized_show(client: api_client.ApiClient, args: Any) -> Any:
+    return client.get(f"/api/v1/programs/{args.hash}")
+
+
+def handle_optimized_traces(client: api_client.ApiClient, args: Any) -> Any:
+    params = pagination.wire(args, "limit_offset", as_str=True)
+    return client.get(f"/api/v1/programs/{args.hash}/traces", params=params)
+
+
+def handle_optimized_stats(client: api_client.ApiClient, args: Any) -> Any:
+    return client.get(f"/api/v1/programs/{args.hash}/execution-stats")
+
+
+def handle_optimized_usage(client: api_client.ApiClient, args: Any) -> Any:
+    return client.get(f"/api/v1/programs/{args.hash}/usage-history", params=_usage_params(args))
+
+
+def handle_registry_list(client: api_client.ApiClient, args: Any) -> Any:
+    # This route reads limit/offset directly, unlike the page-numbered
+    # `programs list`.
+    params = pagination.wire(args, "limit_offset", as_str=True)
+    return client.get("/api/v1/programs/registry", params=params)
+
+
+def handle_registry_show(client: api_client.ApiClient, args: Any) -> Any:
+    return client.get(f"/api/v1/programs/registry/{args.id}")
+
+
+def handle_select(client: api_client.ApiClient, args: Any) -> Any:
+    """Pin one optimization run as the program's chosen version.
+
+    A run-scoped credential is refused by the server: this repoints any program
+    in the organization at any run, so it is a person's decision to make and the
+    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, *, unknown_hint: str = "", old_server_remedy: 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. ``unknown_hint``
+    follows the error for a name no program has. On a server from before program
+    names the lookup fails too, and the error is the old-server refusal with
+    ``old_server_remedy``.
+    """
+    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:
+            _refuse_if_old(client, exc, old_server_remedy)
+            message = f"no program in your organization is named {ref!r}"
+            raise api_client.CliError(f"{message}. {unknown_hint}" if unknown_hint else message) 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, old_server_remedy=_trash_remedy())
+    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 _trash_write(client, 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, old_server_remedy=_trash_remedy())
+    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 _trash_write(client, 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 = _trash_listing(client)
+            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 _trash_write(client, "/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, old_server_remedy=_trash_remedy())
+    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 _trash_write(client, f"/api/v1/programs/{program_id}/purge")
+
+
+def _trash_listing(client: api_client.ApiClient) -> Any:
+    """GET the Trash. On a server from before the Trash API it answers 404, which is the old-server signal."""
+    try:
+        return client.get("/api/v1/programs/trash")
+    except api_client.CliError as exc:
+        if exc.status_code == 404:
+            raise _old_server_refusal(_trash_remedy()) from exc
+        raise
+
+
+def _trash_write(client: api_client.ApiClient, path: str) -> Any:
+    try:
+        return client.post(path)
+    except api_client.CliError as exc:
+        _refuse_if_old(client, exc, _trash_remedy())
+        raise

{cmpnd-0.59.0 → cmpnd-0.61.0}/cmpnd/cli/commands/valsets.py

@@ -8,6 +8,7 @@ inputs and expected outputs of one validation example.
 from __future__ import annotations
 
 import json
+import re
 from argparse import ArgumentParser, _SubParsersAction
 from typing import Any
 
@@ -23,7 +24,7 @@ def register(subparsers: _SubParsersAction[ArgumentParser]) -> None:
     create.add_argument(
         "program_hash",
         metavar="program",
-        help="Owning program: a program id (p_…), or a legacy signature hash "
+        help="Owning program: a program name, a program id (p_…), or a legacy signature hash "
         "(16-hex, as `cmpnd signatures list` shows)",
     )
     create.add_argument(
@@ -33,7 +34,7 @@ def register(subparsers: _SubParsersAction[ArgumentParser]) -> None:
     create.set_defaults(func=handle_create)
 
     ls = sub.add_parser("list", help="List a program's validation sets")
-    ls.add_argument("program", help="Program id (p_…), or a legacy signature hash (16-hex)")
+    ls.add_argument("program", help="Program name, program id (p_…), or a legacy signature hash (16-hex)")
     pagination.add_args(ls, with_page_aliases=False, default_limit=50)
     ls.set_defaults(func=handle_list)
 
@@ -75,15 +76,39 @@ def register(subparsers: _SubParsersAction[ArgumentParser]) -> None:
     edelete.set_defaults(func=handle_entries_delete)
 
 
+# A legacy program signature hash in its display form: 16 hex digits.
+_LEGACY_HASH = re.compile(r"[0-9a-fA-F]{16}")
+
+
+def _program(client: api_client.ApiClient, ref: str) -> str:
+    """The value the valsets routes take for ``ref``.
+
+    A p_ id and a legacy 16-hex hash pass unchanged. Anything else is a program
+    name, which resolves to its p_ id without making a program. A program whose
+    name is 16 hex digits is reached by its p_ id.
+    """
+    from . import programs
+
+    if _LEGACY_HASH.fullmatch(ref):
+        return ref
+    program_id, _ = programs.resolve(
+        client,
+        ref,
+        old_server_remedy="Name the program by its 16-hex signature hash, as `cmpnd signatures list` shows, "
+        "or upgrade the server.",
+    )
+    return program_id
+
+
 def handle_create(client: api_client.ApiClient, args: Any) -> Any:
     # One generator (cmpnd._valsets.default_name) for both the CLI and the
     # Client, so the collision-avoiding suffix can't drift between them.
     name = args.name or _valsets.default_name()
-    return client.post("/api/v1/valsets", json={"program": args.program_hash, "name": name})
+    return client.post("/api/v1/valsets", json={"program": _program(client, args.program_hash), "name": name})
 
 
 def handle_list(client: api_client.ApiClient, args: Any) -> Any:
-    params = {"program": args.program, **pagination.wire(args, "limit_offset", as_str=True)}
+    params = {"program": _program(client, args.program), **pagination.wire(args, "limit_offset", as_str=True)}
     return client.get("/api/v1/valsets", params=params)