coelevate-cli 0.2.0__tar.gz → 0.3.0__tar.gz

{coelevate_cli-0.2.0 → coelevate_cli-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: coelevate-cli
-Version: 0.2.0
+Version: 0.3.0
 Summary: Command-line client for the Coelevate Context Repository public API: read, search, stage changes, and inspect releases.
 Project-URL: Documentation, https://docs.coelevate.ai
 License-Expression: Apache-2.0
@@ -20,16 +20,16 @@ Requires Python 3.11 or newer. The only dependency is `httpx`.
 ## Install
 
 The package is published on PyPI as `coelevate-cli`; the command it installs is
-`coelevate`. Pin a version (`0.2.0` below):
+`coelevate`. Pin a version (`0.3.0` below):
 
 ```bash
 # one-off, no install (recommended: pinned, nothing left behind)
-uvx --from coelevate-cli==0.2.0 coelevate --help
+uvx --from coelevate-cli==0.3.0 coelevate --help
 
 # isolated tool install
-uv tool install coelevate-cli==0.2.0
+uv tool install coelevate-cli==0.3.0
 # or
-pipx install coelevate-cli==0.2.0
+pipx install coelevate-cli==0.3.0
 ```
 
 PyPI lists the SHA-256 of every file it serves under the project's **Download files**; compare a
@@ -114,11 +114,24 @@ coelevate asset-types
 coelevate changeset
 coelevate stage --op-file op.json
 coelevate stage --remove-op op_123          # un-stage one op
+coelevate stage --remove-op op_1,op_2      # un-stage several (the flag also repeats)
+coelevate stage --remove-batch-file out.json  # un-stage every op a saved `stage --json` answer minted
 coelevate tag --name stable
 coelevate release --number 3
 coelevate release --limit 10 --offset 0
 ```
 
+### Output shapes
+
+`--json` prints the service's answer with a few keys added, never removed or renamed, so one parser reads every action:
+
+| Action | Added keys |
+|---|---|
+| `search`, `assets`, `kits` | each entry gets `id`, `type`, `title`, `summary` (taken from `asset_id`, `card`, `label` or `description`; `summary` is null when the service sends none) |
+| `changeset` | `changeset_id` and `op_count` at the top level, next to `revision` and `base_release` (the open changeset stays under `changeset`, its ops in `changeset.ops[]`, each op's body under `op`) |
+| `stage` | `staged_op_ids` (the ops this request minted, from `batch_ops`), `changeset_id`, `op_count`, `expected_revision`, `expected_release` |
+| `stage --remove-op` | `removed_op_ids` |
+
 ### Staging
 
 Ops are JSON passed through unchanged; the server validates them and answers 422 for a bad one.

{coelevate_cli-0.2.0 → coelevate_cli-0.3.0}/README.md

@@ -9,16 +9,16 @@ Requires Python 3.11 or newer. The only dependency is `httpx`.
 ## Install
 
 The package is published on PyPI as `coelevate-cli`; the command it installs is
-`coelevate`. Pin a version (`0.2.0` below):
+`coelevate`. Pin a version (`0.3.0` below):
 
 ```bash
 # one-off, no install (recommended: pinned, nothing left behind)
-uvx --from coelevate-cli==0.2.0 coelevate --help
+uvx --from coelevate-cli==0.3.0 coelevate --help
 
 # isolated tool install
-uv tool install coelevate-cli==0.2.0
+uv tool install coelevate-cli==0.3.0
 # or
-pipx install coelevate-cli==0.2.0
+pipx install coelevate-cli==0.3.0
 ```
 
 PyPI lists the SHA-256 of every file it serves under the project's **Download files**; compare a
@@ -103,11 +103,24 @@ coelevate asset-types
 coelevate changeset
 coelevate stage --op-file op.json
 coelevate stage --remove-op op_123          # un-stage one op
+coelevate stage --remove-op op_1,op_2      # un-stage several (the flag also repeats)
+coelevate stage --remove-batch-file out.json  # un-stage every op a saved `stage --json` answer minted
 coelevate tag --name stable
 coelevate release --number 3
 coelevate release --limit 10 --offset 0
 ```
 
+### Output shapes
+
+`--json` prints the service's answer with a few keys added, never removed or renamed, so one parser reads every action:
+
+| Action | Added keys |
+|---|---|
+| `search`, `assets`, `kits` | each entry gets `id`, `type`, `title`, `summary` (taken from `asset_id`, `card`, `label` or `description`; `summary` is null when the service sends none) |
+| `changeset` | `changeset_id` and `op_count` at the top level, next to `revision` and `base_release` (the open changeset stays under `changeset`, its ops in `changeset.ops[]`, each op's body under `op`) |
+| `stage` | `staged_op_ids` (the ops this request minted, from `batch_ops`), `changeset_id`, `op_count`, `expected_revision`, `expected_release` |
+| `stage --remove-op` | `removed_op_ids` |
+
 ### Staging
 
 Ops are JSON passed through unchanged; the server validates them and answers 422 for a bad one.

{coelevate_cli-0.2.0 → coelevate_cli-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "coelevate-cli"
-version = "0.2.0"
+version = "0.3.0"
 description = "Command-line client for the Coelevate Context Repository public API: read, search, stage changes, and inspect releases."
 readme = "README.md"
 requires-python = ">=3.11"

{coelevate_cli-0.2.0 → coelevate_cli-0.3.0}/src/coelevate_cli/__init__.py

@@ -1,3 +1,3 @@
 """Command-line client for the Coelevate Context Repository public API."""
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"

{coelevate_cli-0.2.0 → coelevate_cli-0.3.0}/src/coelevate_cli/cli.py

@@ -22,6 +22,7 @@ from __future__ import annotations
 import argparse
 import json
 import os
+import re
 import sys
 import time
 from contextlib import ExitStack
@@ -266,7 +267,27 @@ def _cmd_search(args: argparse.Namespace, ctx: _Context) -> Any:
     }
     if args.asset_type:
         body["asset_type"] = args.asset_type
-    return ctx.call("search", json_body=body)
+    result = ctx.call("search", json_body=body)
+    if isinstance(result, dict) and isinstance(result.get("results"), list):
+        result["results"] = [_normalise_item(item) for item in result["results"]]
+    return result
+
+
+def _normalise_item(item: Any, kind: str | None = None) -> Any:
+    """Add the four keys every listing shares (``id``, ``type``, ``title``, ``summary``) to one entry.
+
+    ``search``, ``assets`` and ``kits`` answer with different shapes (``asset_id`` and ``label``, a ``card``,
+    ``title`` and ``description``), so a caller would need one parser per action. The keys are added next to
+    the service's own, never in place of them; ``summary`` is null when the service sends none.
+    """
+    if not isinstance(item, dict):
+        return item
+    card = item.get("card") if isinstance(item.get("card"), dict) else {}
+    item.setdefault("id", item.get("asset_id") or card.get("id"))
+    item.setdefault("type", item.get("asset_type") or kind)
+    item.setdefault("title", card.get("title") or item.get("label"))
+    item.setdefault("summary", card.get("summary") or item.get("description"))
+    return item
 
 
 def _cmd_kits(args: argparse.Namespace, ctx: _Context) -> Any:
@@ -275,6 +296,7 @@ def _cmd_kits(args: argparse.Namespace, ctx: _Context) -> Any:
         raise CliError("unexpected response from the service: no 'kits' list")
     if not all(isinstance(kit, dict) for kit in result["kits"]):
         raise CliError("unexpected response from the service: every entry of 'kits' must be an object")
+    result["kits"] = [_normalise_item(kit, "kit") for kit in result["kits"]]
     return result
 
 
@@ -295,6 +317,7 @@ def _cmd_assets(args: argparse.Namespace, ctx: _Context) -> Any:
     result = ctx.call("assets", params=params)
     if not isinstance(result, dict) or not isinstance(result.get("assets"), list):
         raise CliError("unexpected response from the service: no 'assets' list")
+    result["assets"] = [_normalise_item(item) for item in result["assets"]]
     return result
 
 
@@ -363,7 +386,84 @@ def _cmd_asset_types(args: argparse.Namespace, ctx: _Context) -> Any:
 
 
 def _cmd_changeset(args: argparse.Namespace, ctx: _Context) -> Any:
-    return ctx.call("changeset")
+    return _lift_changeset_keys(ctx.call("changeset"))
+
+
+def _lift_changeset_keys(result: Any) -> Any:
+    """Put ``changeset_id`` and ``op_count`` at the top level, where ``stage`` also answers them.
+
+    ``changeset`` wraps the open changeset under ``changeset`` while ``stage`` answers it flat; with the
+    same top-level keys on both, one parser reads either. Nothing the service sent is moved or removed.
+    """
+    if not isinstance(result, dict):
+        return result
+    detail = result.get("changeset") if isinstance(result.get("changeset"), dict) else result
+    if detail.get("changeset_id"):
+        result.setdefault("changeset_id", detail["changeset_id"])
+    if isinstance(detail.get("ops"), list):
+        result.setdefault("op_count", len(detail["ops"]))
+    for key in ("revision", "base_release"):
+        if key in detail:
+            result.setdefault(key, detail[key])
+    return result
+
+
+#: What an op id may hold (the service mints ``csop_<uuid>``); checked before a removal goes over the
+#: wire, so a pasted list or a stray quote fails with a hint instead of a 404 for a malformed id.
+_OP_ID = re.compile(r"[A-Za-z0-9][A-Za-z0-9_-]*")
+
+
+def _batch_op_ids(data: Any) -> list[str]:
+    """The op ids in a saved ``stage --json`` answer (``staged_op_ids`` or ``batch_ops[].op_id``), or a JSON list of ids."""
+    if isinstance(data, list):
+        return [str(op_id) for op_id in data]
+    if isinstance(data, dict):
+        if isinstance(data.get("staged_op_ids"), list):
+            return [str(op_id) for op_id in data["staged_op_ids"]]
+        if isinstance(data.get("batch_ops"), list):
+            return [str(op["op_id"]) for op in data["batch_ops"] if isinstance(op, dict) and op.get("op_id")]
+    raise CliError("--remove-batch-file must hold a saved `stage --json` answer or a JSON list of op ids", code=2)
+
+
+def _remove_op_ids(args: argparse.Namespace) -> list[str]:
+    """Every op id to un-stage, in order and once each: repeated ``--remove-op`` values, lists inside one
+    value (split on commas and whitespace) and the ops of a saved batch."""
+    ids: list[str] = []
+    for value in args.remove_op or []:
+        ids.extend(part for part in re.split(r"[\s,]+", value) if part)
+    if args.remove_batch_file:
+        ids.extend(_batch_op_ids(_load_json_file(args.remove_batch_file, "--remove-batch-file")))
+    if not ids:
+        raise CliError("no op id to un-stage", code=2)
+    bad = [op_id for op_id in ids if not _OP_ID.fullmatch(op_id)]
+    if bad:
+        raise CliError(f"not an op id: {', '.join(repr(op_id) for op_id in bad)} (read the ids with `coelevate changeset --json`)", code=2)
+    return list(dict.fromkeys(ids))
+
+
+def _unstage(args: argparse.Namespace, ctx: _Context) -> Any:
+    """Un-stage each op in turn and stop at the first refusal, saying which were removed and which were not tried.
+
+    The service removes one op per request, so a batch is not atomic: the report is what makes a partial
+    removal safe to finish by hand.
+    """
+    ids = _remove_op_ids(args)
+    removed: list[str] = []
+    result: Any = {}
+    for index, op_id in enumerate(ids):
+        try:
+            result = ctx.call("unstage", op_id=op_id)
+        except CliError as exc:
+            raise CliError(
+                f"{exc}\nun-staged before the refusal: {', '.join(removed) or 'none'}; "
+                f"not attempted: {', '.join(ids[index + 1 :]) or 'none'}",
+                code=exc.code,
+            ) from exc
+        removed.append(op_id)
+    if not isinstance(result, dict):
+        result = {"answer": result}
+    result["removed_op_ids"] = removed
+    return result
 
 
 def _stage_ops(args: argparse.Namespace) -> list[Any]:
@@ -382,9 +482,13 @@ def _stage_ops(args: argparse.Namespace) -> list[Any]:
     return [_load_json(args.op, "--op")]
 
 
+def _removing(args: argparse.Namespace) -> bool:
+    return bool(getattr(args, "remove_op", None) or getattr(args, "remove_batch_file", None))
+
+
 def _cmd_stage(args: argparse.Namespace, ctx: _Context) -> Any:
-    if args.remove_op:
-        return ctx.call("unstage", op_id=args.remove_op)
+    if _removing(args):
+        return _unstage(args, ctx)
     ops = _stage_ops(args)
     provenance = None
     if args.provenance is not None:
@@ -418,6 +522,11 @@ def _cmd_stage(args: argparse.Namespace, ctx: _Context) -> Any:
         # What this request declared, so a retry can pin the same values.
         result["expected_revision"] = expected_revision
         result["expected_release"] = expected_release
+        # The ops this request minted, by id: what `--remove-op` or `--remove-batch-file` takes back.
+        batch = result.get("batch_ops")
+        if isinstance(batch, list):
+            result.setdefault("staged_op_ids", [op["op_id"] for op in batch if isinstance(op, dict) and op.get("op_id")])
+        _lift_changeset_keys(result)
     return result
 
 
@@ -512,7 +621,7 @@ def _cmd_gap(args: argparse.Namespace, ctx: _Context) -> Any:
 def _check_retry_is_pinned(args: argparse.Namespace) -> None:
     """A retry is only the same request when what it declares is pinned, so a key demands
     both expected values. Checked before anything goes over the wire."""
-    if args.action != "stage" or not args.idempotency_key or args.remove_op:
+    if args.action != "stage" or not args.idempotency_key or _removing(args):
         return
     missing = [
         flag
@@ -536,7 +645,7 @@ def _check_retry_is_pinned(args: argparse.Namespace) -> None:
 def _stage_scope(args: argparse.Namespace) -> str:
     """Staging narrows the token to what it needs: write, plus read when it must read the
     changeset first (a write-only token is refused on that read)."""
-    if args.remove_op:
+    if _removing(args):
         return ASSETS_SCOPE
     if args.expected_revision is not None and args.expected_release is not None:
         return ASSETS_SCOPE
@@ -788,7 +897,15 @@ def build_parser() -> argparse.ArgumentParser:
     ops.add_argument("--op", help="one op as a JSON string")
     ops.add_argument("--op-file", help="one op as a JSON file")
     ops.add_argument("--ops-file", help=f"a JSON array of up to {MAX_OPS_PER_REQUEST} ops, staged in one request")
-    ops.add_argument("--remove-op", help="un-stage this op id instead of staging")
+    ops.add_argument(
+        "--remove-op",
+        action="append",
+        help="un-stage this op id instead of staging; repeatable, and one value may list several ids (comma or space)",
+    )
+    ops.add_argument(
+        "--remove-batch-file",
+        help="un-stage every op of a saved `stage --json` answer (its batch_ops), or of a JSON list of op ids",
+    )
     stage_p.add_argument("--provenance", default=None, help="a JSON object recording where the ops came from")
     stage_p.add_argument("--idempotency-key", default=None, help="make a retry of this request safe")
     stage_p.add_argument("--expected-revision", type=int, default=None, help="default: read from the changeset just before staging")