coelevate-cli 0.2.0__py3-none-any.whl

coelevate_cli/cli.py

@@ -0,0 +1,988 @@
+"""``coelevate``: a command-line client for the Context Repository public API.
+
+Every action calls one of the routes the public API exposes to a customer key. The CLI
+proposes a change to the context's assets (``stage``) and never lands one. A kit is not an
+asset: ``kit`` writes it directly, with no changeset and no review (it needs the
+``context:kits`` scope), and so does ``gap`` (it needs ``context:gaps``).
+
+Exit codes (stable):
+
+* ``0`` - success.
+* ``1`` - the request ran and failed: the service or token endpoint refused it, or it
+  could not be reached.
+* ``2`` - the command could not run: bad usage, required configuration is missing, or the
+  key resolves to a different project than the one pinned.
+
+Secrets come from the environment only, never a flag (a ``./.env`` file in the working
+folder counts as the environment, see ``_load_dotenv``). The CLI never prompts.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+import time
+from contextlib import ExitStack
+from pathlib import Path
+from typing import Any
+from urllib.parse import urlsplit
+
+import httpx
+
+from coelevate_cli import __version__
+from coelevate_cli.auth import (
+    ASSETS_SCOPE,
+    GAPS_SCOPE,
+    KITS_SCOPE,
+    READ_SCOPE,
+    TOKEN_PATH,
+    ClientCredentialsTokenSource,
+    OAuthTokenError,
+)
+
+CLIENT_ID_ENV = "COELEVATE_CLIENT_ID"
+CLIENT_SECRET_ENV = "COELEVATE_CLIENT_SECRET"
+TOKEN_URL_ENV = "COELEVATE_TOKEN_URL"
+API_URL_ENV = "COELEVATE_API_URL"
+HTTP_TIMEOUT_ENV = "COELEVATE_HTTP_TIMEOUT"
+RETRY_BACKOFF_ENV = "COELEVATE_RETRY_BACKOFF"
+PROJECT_ID_ENV = "COELEVATE_PROJECT_ID"
+WORKSPACE_URL_ENV = "COELEVATE_WORKSPACE_URL"
+ENVIRONMENT_ENV = "COELEVATE_ENVIRONMENT"
+
+#: The file read from the working folder before the environment is consulted.
+DOTENV_NAME = ".env"
+#: Only variables with this prefix are taken from it: the file may be a shared project
+#: ``.env`` holding unrelated secrets, and the CLI has no business with those.
+DOTENV_PREFIX = "COELEVATE_"
+
+#: Seconds each phase of a request may take (connect, read, write) before it times out.
+DEFAULT_HTTP_TIMEOUT = 30.0
+#: Seconds to wait before the one retry of a read.
+DEFAULT_RETRY_BACKOFF = 1.0
+
+#: Where the public Context API lives on the API origin.
+CONTEXT_PREFIX = "/context"
+
+#: The server's cap on ops per staging request.
+MAX_OPS_PER_REQUEST = 100
+
+#: Every route the CLI calls, relative to ``<base url>/context``. The project is not in the
+#: path: the key's token names it. A test holds this set against the published API description.
+ROUTES: dict[str, tuple[str, str]] = {
+    "kits": ("GET", "/v1/kits"),
+    "read_kit": ("GET", "/v1/kits/{kit_id}"),
+    "read_asset": ("GET", "/v1/assets/{asset_id}"),
+    "search": ("POST", "/v1/search"),
+    "asset_types": ("GET", "/v1/asset-types"),
+    "changeset": ("GET", "/v1/changeset"),
+    "stage": ("POST", "/v1/changeset/ops"),
+    "unstage": ("DELETE", "/v1/changeset/ops/{op_id}"),
+    "releases": ("GET", "/v1/releases"),
+    "assets": ("GET", "/v1/assets"),
+    "kit_create": ("POST", "/v1/kits"),
+    "kit_patch": ("PATCH", "/v1/kits/{kit_id}"),
+    "kit_add_members": ("POST", "/v1/kits/{kit_id}/members"),
+    "kit_remove_member": ("DELETE", "/v1/kits/{kit_id}/members/{asset_id}"),
+    "kit_revert": ("POST", "/v1/kits/{kit_id}/revert"),
+    "kit_retire": ("DELETE", "/v1/kits/{kit_id}"),
+    "kit_journal": ("GET", "/v1/kits/{kit_id}/journal"),
+    "gaps": ("GET", "/v1/gaps"),
+    "gap_read": ("GET", "/v1/gaps/{gap_id}"),
+    "gap_journal": ("GET", "/v1/gaps/{gap_id}/journal"),
+    "gap_create": ("POST", "/v1/gaps"),
+    "gap_patch": ("PATCH", "/v1/gaps/{gap_id}"),
+    "gap_retire": ("POST", "/v1/gaps/{gap_id}/retire"),
+    "gap_revert": ("POST", "/v1/gaps/{gap_id}/revert"),
+}
+
+#: The routes that only read, so sending one twice changes nothing. ``search`` is a POST
+#: that mutates nothing; ``stage`` and ``unstage`` change the changeset and are not here.
+RETRYABLE_ROUTES = frozenset(
+    {
+        "kits",
+        "read_kit",
+        "read_asset",
+        "search",
+        "asset_types",
+        "changeset",
+        "releases",
+        "assets",
+        "kit_journal",
+        "gaps",
+        "gap_read",
+        "gap_journal",
+    }
+)
+
+
+class CliError(RuntimeError):
+    """A clean, user-facing failure: printed to stderr, never a traceback. ``code`` is
+    the exit code."""
+
+    def __init__(self, message: str, *, code: int = 1) -> None:
+        super().__init__(message)
+        self.code = code
+
+
+class _Context:
+    """What a handler needs: an authenticated client and the API origin."""
+
+    def __init__(
+        self,
+        http_client: httpx.Client,
+        base_url: str,
+        retry_backoff: float = DEFAULT_RETRY_BACKOFF,
+        expected_project: str | None = None,
+    ) -> None:
+        self.http = http_client
+        self.base_url = base_url
+        self.retry_backoff = retry_backoff
+        self.expected_project = expected_project
+
+    @property
+    def project_id(self) -> str | None:
+        """The project the key resolves to; known once a token has been exchanged."""
+        return self.http.auth.project_id
+
+    def token(self) -> str:
+        """The bearer token. The first exchange also enforces the pin: a key that resolves
+        to another project than the one expected refuses every action, before any request
+        carries the token anywhere."""
+        token = self.http.auth.token()
+        expected, actual = self.expected_project, self.project_id
+        if expected is not None and actual != expected:
+            if actual is None:
+                raise CliError(
+                    f"cannot verify the project: {expected!r} is expected but the token response names no project",
+                    code=2,
+                )
+            raise CliError(
+                f"project mismatch: this key resolves to project {actual!r} but {expected!r} is expected "
+                f"(--expect-project or ${PROJECT_ID_ENV}). Nothing was sent.",
+                code=2,
+            )
+        return token
+
+    def _send(self, method: str, url: str, *, retry: bool, **kwargs: Any) -> httpx.Response:
+        """Send once; for a read, send again after a short pause if the first attempt
+        timed out or could not connect (a service that scales to zero answers late while
+        it starts, and the second attempt reaches it warm). Only that, only once: an
+        answer of any status is final, and a write is never sent twice by the client."""
+        try:
+            return self.http.request(method, url, **kwargs)
+        except (httpx.TimeoutException, httpx.ConnectError):
+            if not retry:
+                raise
+        time.sleep(self.retry_backoff)
+        return self.http.request(method, url, **kwargs)
+
+    def call(
+        self,
+        route: str,
+        *,
+        params: dict[str, Any] | None = None,
+        json_body: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+        **path_args: str,
+    ) -> Any:
+        method, template = ROUTES[route]
+        path = f"{CONTEXT_PREFIX}{template.format(**path_args)}"
+        # The token exchange happens here, once and outside any retry; the request then
+        # carries the token itself, so its own auth flow never exchanges (or repeats) one.
+        bearer = {"Authorization": f"Bearer {self.token()}"}
+        try:
+            response = self._send(
+                method,
+                f"{self.base_url}{path}",
+                retry=route in RETRYABLE_ROUTES,
+                params=params,
+                json=json_body,
+                headers={**(headers or {}), **bearer},
+                auth=None,
+            )
+        except httpx.HTTPError as exc:
+            raise CliError(f"{method} {path} failed to connect: {exc}") from exc
+        if response.status_code >= 400:
+            try:
+                detail = response.json()
+            except ValueError:
+                detail = response.text[:400]
+            message = f"{method} {path} refused (HTTP {response.status_code}): {detail}"
+            if response.status_code == 409 and "idempotency_key_reused" in str(detail):
+                message += (
+                    "\nhint: this key already belongs to a different request. To retry safely, "
+                    "reuse the first attempt's values: pass --expected-revision and "
+                    "--expected-release as the first attempt's stage output reported them, "
+                    "together with the same --idempotency-key."
+                )
+            raise CliError(message)
+        if not response.content:
+            return {}
+        try:
+            return response.json()
+        except ValueError as exc:
+            raise CliError(f"{method} {path} answered with a body that is not JSON") from exc
+
+
+def _load_json(raw: str, what: str) -> Any:
+    try:
+        return json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise CliError(f"{what} is not valid JSON: {exc}", code=2) from exc
+
+
+def _load_json_file(path: str, what: str) -> Any:
+    try:
+        with open(path, encoding="utf-8") as handle:
+            text = handle.read()
+    except OSError as exc:
+        raise CliError(f"cannot read {what} {path!r}: {exc.strerror or exc}", code=2) from exc
+    except ValueError as exc:  # UnicodeDecodeError is one
+        raise CliError(f"cannot read {what} {path!r}: not valid UTF-8 text ({exc})", code=2) from exc
+    return _load_json(text, f"{what} {path!r}")
+
+
+# --- actions -----------------------------------------------------------------
+
+
+def _cmd_read(args: argparse.Namespace, ctx: _Context) -> Any:
+    params: dict[str, Any] = {}
+    if args.version is not None:
+        params["version"] = args.version
+    if args.kit_id:
+        return ctx.call("read_kit", params=params or None, kit_id=args.kit_id)
+    if args.links:
+        params["expand"] = "links"
+    return ctx.call("read_asset", params=params, asset_id=args.asset_id)
+
+
+def _cmd_search(args: argparse.Namespace, ctx: _Context) -> Any:
+    body: dict[str, Any] = {
+        "query": args.query,
+        "max_results": args.max_results,
+    }
+    if args.asset_type:
+        body["asset_type"] = args.asset_type
+    return ctx.call("search", json_body=body)
+
+
+def _cmd_kits(args: argparse.Namespace, ctx: _Context) -> Any:
+    result = ctx.call("kits")
+    if not isinstance(result, dict) or not isinstance(result.get("kits"), list):
+        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")
+    return result
+
+
+def _format_kits(result: Any) -> str:
+    """One line per kit (id, title, version) for a human; ``--json`` keeps the raw body."""
+    kits = result["kits"]  # _cmd_kits has already checked this is a list
+    if not kits:
+        return "no kits"
+    return "\n".join(f"{kit.get('id')}\t{kit.get('title')}\tv{kit.get('version')}" for kit in kits)
+
+
+def _cmd_assets(args: argparse.Namespace, ctx: _Context) -> Any:
+    params: dict[str, Any] = {"limit": args.limit, "offset": args.offset}
+    if args.asset_type:
+        params["asset_type"] = args.asset_type  # httpx repeats the key per value
+    if args.label:
+        params["label"] = args.label
+    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")
+    return result
+
+
+def _format_assets(result: Any) -> str:
+    """One line per asset (id, type, label) for a human; ``--json`` keeps the raw body."""
+    assets = [a for a in result["assets"] if isinstance(a, dict)]
+    if not assets:
+        return "no assets"
+    return "\n".join(f"{a.get('asset_id')}\t{a.get('asset_type')}\t{a.get('label')}" for a in assets)
+
+
+def _environment_label(base_url: str) -> str:
+    """staging, production or local, from the API host, unless ``COELEVATE_ENVIRONMENT`` says."""
+    override = os.environ.get(ENVIRONMENT_ENV, "").strip()
+    if override:
+        return override
+    host = urlsplit(base_url).hostname or ""
+    if host in ("localhost", "127.0.0.1", "::1") or host.endswith(".localhost"):
+        return "local"
+    return "staging" if "staging" in host.split(".") else "production"
+
+
+#: The scopes ``whoami`` and ``doctor`` ask the server about, one token each. ``context:review``
+#: is deliberately absent: it is the human reviewer's scope, and a diagnostic never requests it.
+PROBED_SCOPES = (READ_SCOPE, ASSETS_SCOPE, KITS_SCOPE, GAPS_SCOPE)
+
+
+def _probe_permits(source: ClientCredentialsTokenSource) -> dict[str, bool | None]:
+    """For each probed scope, whether the server grants it (``True``), refuses it (``False``)
+    or could not say (``None``)."""
+    return {scope: source.grants_scope(scope) for scope in PROBED_SCOPES}
+
+
+def _cmd_whoami(args: argparse.Namespace, ctx: _Context) -> Any:
+    """Which project, where, and with what rights this key resolves to. Never the secret."""
+    ctx.token()
+    if ctx.project_id is None:
+        raise CliError("the token response names no project, so this key's project cannot be determined")
+    source = ctx.http.auth
+    permits = _probe_permits(source)
+    result = {
+        "project_id": ctx.project_id,
+        "api_host": urlsplit(ctx.base_url).netloc,
+        "environment": _environment_label(ctx.base_url),
+        "scopes": (source.granted_scope or "").split(),
+        "permits": [scope for scope, granted in permits.items() if granted],
+        "client_id": source.client_id,
+    }
+    unknown = [scope for scope, granted in permits.items() if granted is None]
+    if unknown:
+        result["permits_unknown"] = unknown
+    return result
+
+
+_WHOAMI_LABELS = {"scopes": "default token scopes", "permits_unknown": "permits (could not check)"}
+
+
+def _format_whoami(result: Any) -> str:
+    return "\n".join(
+        f"{_WHOAMI_LABELS.get(key, key)}: {' '.join(value) if isinstance(value, list) else value}" for key, value in result.items()
+    )
+
+
+def _cmd_asset_types(args: argparse.Namespace, ctx: _Context) -> Any:
+    return ctx.call("asset_types")
+
+
+def _cmd_changeset(args: argparse.Namespace, ctx: _Context) -> Any:
+    return ctx.call("changeset")
+
+
+def _stage_ops(args: argparse.Namespace) -> list[Any]:
+    if args.ops_file:
+        ops = _load_json_file(args.ops_file, "--ops-file")
+        if not isinstance(ops, list) or not ops:
+            raise CliError("--ops-file must hold a non-empty JSON array of ops", code=2)
+        if len(ops) > MAX_OPS_PER_REQUEST:
+            raise CliError(
+                f"--ops-file holds {len(ops)} ops; one request takes at most {MAX_OPS_PER_REQUEST} - split the file",
+                code=2,
+            )
+        return ops
+    if args.op_file:
+        return [_load_json_file(args.op_file, "--op-file")]
+    return [_load_json(args.op, "--op")]
+
+
+def _cmd_stage(args: argparse.Namespace, ctx: _Context) -> Any:
+    if args.remove_op:
+        return ctx.call("unstage", op_id=args.remove_op)
+    ops = _stage_ops(args)
+    provenance = None
+    if args.provenance is not None:
+        provenance = _load_json(args.provenance, "--provenance")
+        if not isinstance(provenance, dict):
+            raise CliError("--provenance must be a JSON object", code=2)
+
+    expected_revision, expected_release = args.expected_revision, args.expected_release
+    if expected_revision is None or expected_release is None:
+        # Every batch declares exactly what it read, so read the changeset immediately
+        # before staging rather than trusting a value from an earlier call.
+        changeset = ctx.call("changeset")
+        try:
+            if expected_revision is None:
+                expected_revision = changeset["revision"]
+            if expected_release is None:
+                expected_release = changeset["base_release"]
+        except (KeyError, TypeError) as exc:
+            raise CliError("the changeset read did not return a revision and base_release") from exc
+
+    body: dict[str, Any] = {
+        "ops": ops,
+        "expected_revision": expected_revision,
+        "expected_release": expected_release,
+    }
+    if provenance is not None:
+        body["provenance"] = provenance
+    headers = {"Idempotency-Key": args.idempotency_key} if args.idempotency_key else None
+    result = ctx.call("stage", json_body=body, headers=headers)
+    if isinstance(result, dict):
+        # What this request declared, so a retry can pin the same values.
+        result["expected_revision"] = expected_revision
+        result["expected_release"] = expected_release
+    return result
+
+
+def _cmd_tag(args: argparse.Namespace, ctx: _Context) -> Any:
+    return ctx.call("releases", params={"tag": args.name})
+
+
+def _cmd_release(args: argparse.Namespace, ctx: _Context) -> Any:
+    params: dict[str, Any] = {"limit": args.limit, "offset": args.offset}
+    if args.number is not None:
+        params["release"] = args.number
+    if args.tag is not None:
+        params["tag"] = args.tag
+    return ctx.call("releases", params=params)
+
+
+#: The kit verbs whose request model is a JSON body; ``remove-member`` and ``retire`` carry
+#: only the version they read, and ``journal`` only reads.
+_KIT_BODY_VERBS = {"create": "kit_create", "patch": "kit_patch", "add-members": "kit_add_members", "revert": "kit_revert"}
+
+
+def _cmd_kit(args: argparse.Namespace, ctx: _Context) -> Any:
+    """Write a kit directly (a kit is not an asset: no changeset, no release). A write names
+    the kit version it read (``base_version`` in the body, or ``--base-version``); a kit that
+    moved since is refused with 409 ``kit_moved``, never overwritten."""
+    verb = args.verb
+    if verb != "create" and not args.kit_id:
+        raise CliError(f"kit {verb} needs --kit-id", code=2)
+    if verb in _KIT_BODY_VERBS:
+        if args.body_file:
+            body = _load_json_file(args.body_file, "--body-file")
+        elif args.body:
+            body = _load_json(args.body, "--body")
+        else:
+            raise CliError(f"kit {verb} needs --body or --body-file", code=2)
+        if not isinstance(body, dict):
+            raise CliError("the kit request body must be a JSON object", code=2)
+        return ctx.call(_KIT_BODY_VERBS[verb], json_body=body, kit_id=args.kit_id)
+    if verb == "journal":
+        return ctx.call("kit_journal", kit_id=args.kit_id)
+    if args.base_version is None:
+        raise CliError(f"kit {verb} needs --base-version", code=2)
+    params = {"base_version": args.base_version}
+    if verb == "remove-member":
+        if not args.asset_id:
+            raise CliError("kit remove-member needs --asset-id", code=2)
+        return ctx.call("kit_remove_member", params=params, kit_id=args.kit_id, asset_id=args.asset_id)
+    return ctx.call("kit_retire", params=params, kit_id=args.kit_id)
+
+
+#: The gap verbs whose request model is a JSON body. ``list``, ``get`` and ``journal`` only read.
+_GAP_BODY_VERBS = {"create": "gap_create", "patch": "gap_patch", "retire": "gap_retire", "revert": "gap_revert"}
+
+
+def _cmd_gap(args: argparse.Namespace, ctx: _Context) -> Any:
+    """Read or write a gap directly (a gap is not an asset: no changeset, no release, and it
+    names no kit). A write other than ``create`` names the gap version it read
+    (``base_version`` in the body); a gap that moved since is refused with 409 ``gap_moved``,
+    never overwritten. Closing (``retire``) takes an optional ``covered_by`` list of asset ids."""
+    verb = args.verb
+    if verb == "list":
+        params: dict[str, Any] = {"state": args.state}
+        if args.kind:
+            params["kind"] = args.kind
+        if args.opened_release is not None:
+            params["opened_release"] = args.opened_release
+        if args.closed_release is not None:
+            params["closed_release"] = args.closed_release
+        return ctx.call("gaps", params=params)
+    if verb != "create" and not args.gap_id:
+        raise CliError(f"gap {verb} needs --gap-id", code=2)
+    if verb == "get":
+        return ctx.call("gap_read", params={"version": args.version} if args.version is not None else None, gap_id=args.gap_id)
+    if verb == "journal":
+        return ctx.call("gap_journal", gap_id=args.gap_id)
+    if args.body_file:
+        body = _load_json_file(args.body_file, "--body-file")
+    elif args.body:
+        body = _load_json(args.body, "--body")
+    else:
+        raise CliError(f"gap {verb} needs --body or --body-file", code=2)
+    if not isinstance(body, dict):
+        raise CliError("the gap request body must be a JSON object", code=2)
+    if verb == "create" and "kit_ids" in body:
+        raise CliError(
+            "a gap names no kit, so a create body takes no kit_ids: put the gap into a kit with `kit add-members` (needs context:kits)",
+            code=2,
+        )
+    return ctx.call(_GAP_BODY_VERBS[verb], json_body=body, gap_id=args.gap_id)
+
+
+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:
+        return
+    missing = [
+        flag
+        for flag, value in (
+            ("--expected-revision", args.expected_revision),
+            ("--expected-release", args.expected_release),
+        )
+        if value is None
+    ]
+    if missing:
+        raise CliError(
+            f"--idempotency-key requires {' and '.join(missing)}: a retry is only the same "
+            "request when the values it declares are pinned. Read them with "
+            "`coelevate changeset --json`, then pass --expected-revision and "
+            "--expected-release together with the same --idempotency-key (and the same "
+            "values on every retry).",
+            code=2,
+        )
+
+
+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:
+        return ASSETS_SCOPE
+    if args.expected_revision is not None and args.expected_release is not None:
+        return ASSETS_SCOPE
+    return f"{READ_SCOPE} {ASSETS_SCOPE}"
+
+
+_READ = lambda args: READ_SCOPE  # noqa: E731
+
+
+def _kit_scope(args: argparse.Namespace) -> str:
+    """The journal is a read; every kit write needs only the kits scope (the published API
+    description says so), so the token asks for no more than the verb uses."""
+    return READ_SCOPE if args.verb == "journal" else KITS_SCOPE
+
+
+def _gap_scope(args: argparse.Namespace) -> str:
+    """Listing, reading and the journal are reads; every gap write needs only the gaps scope."""
+    return READ_SCOPE if args.verb in ("list", "get", "journal") else GAPS_SCOPE
+
+
+_HANDLERS = {
+    "read": (_cmd_read, _READ),
+    "search": (_cmd_search, _READ),
+    "stage": (_cmd_stage, _stage_scope),
+    "tag": (_cmd_tag, _READ),
+    "release": (_cmd_release, _READ),
+    "kits": (_cmd_kits, _READ),
+    "kit": (_cmd_kit, _kit_scope),
+    "gap": (_cmd_gap, _gap_scope),
+    "asset-types": (_cmd_asset_types, _READ),
+    "changeset": (_cmd_changeset, _READ),
+    "assets": (_cmd_assets, _READ),
+    "whoami": (_cmd_whoami, _READ),
+}
+
+#: Actions whose JSON gains a top-level ``project_id`` (only ever added, never replacing a key).
+_PROJECT_ID_ACTIONS = frozenset({"kits", "kit", "gap", "read", "changeset", "stage", "release", "assets"})
+
+
+# --- configuration -----------------------------------------------------------
+
+
+def _load_dotenv(path: Path) -> list[str]:
+    """Take ``COELEVATE_*`` variables from a ``.env`` file into the process environment and
+    return their names. A variable already in the real environment wins. Minimal on purpose
+    (``KEY=value``, optional ``export``, optional quotes, ``#`` comments): the CLI has no
+    dependency for this and reads no other key. Values are never printed."""
+    if not path.is_file():
+        return []
+    try:
+        text = path.read_text(encoding="utf-8")
+    except (OSError, ValueError) as exc:
+        raise CliError(f"cannot read {str(path)!r}: {getattr(exc, 'strerror', None) or exc}", code=2) from exc
+    values: dict[str, str] = {}
+    for line in text.splitlines():
+        line = line.strip()
+        if not line or line.startswith("#"):
+            continue
+        if line.startswith("export "):
+            line = line[len("export ") :].lstrip()
+        key, sep, value = line.partition("=")
+        key, value = key.strip(), value.strip()
+        if not sep or not key.startswith(DOTENV_PREFIX):
+            continue
+        values[key] = _dotenv_value(value)
+    # A file in an untrusted checkout must not aim the real credentials at its own endpoint:
+    # its endpoint keys count only when the file brings the credentials too and the real
+    # environment brings neither.
+    brings_credentials = CLIENT_ID_ENV in values and CLIENT_SECRET_ENV in values
+    real_credentials = CLIENT_ID_ENV in os.environ or CLIENT_SECRET_ENV in os.environ
+    if not (brings_credentials and not real_credentials):
+        ignored = [key for key in (TOKEN_URL_ENV, API_URL_ENV) if key in values and key not in os.environ]
+        for key in ignored:
+            del values[key]
+        if ignored:
+            print(
+                f"notice: ignored {', '.join(ignored)} from ./{DOTENV_NAME}: an endpoint from the file is used "
+                "only when the file also sets the client id and secret and the environment sets neither",
+                file=sys.stderr,
+            )
+    loaded = []
+    for key, value in values.items():
+        if key not in os.environ:
+            os.environ[key] = value
+            loaded.append(key)
+    return loaded
+
+
+def _dotenv_value(raw: str) -> str:
+    """The value of one ``KEY=value`` line: a quoted value (single or double quotes) up to its
+    closing quote, then optionally whitespace and a ``#`` comment; an unquoted value up to
+    `` #``."""
+    if raw[:1] in ("'", '"'):
+        close = raw.find(raw[0], 1)
+        if close != -1:
+            rest = raw[close + 1 :].strip()
+            if not rest or rest.startswith("#"):
+                return raw[1:close]
+    return raw.split(" #", 1)[0].rstrip()
+
+
+def _workspace_base(base_url: str) -> str | None:
+    """The Workspace origin: ``COELEVATE_WORKSPACE_URL``, else the API origin without its
+    ``api.`` label (``api.staging.coelevate.ai`` -> ``staging.coelevate.ai``). ``None`` when
+    the API host does not follow that shape, rather than a guess that points nowhere."""
+    override = os.environ.get(WORKSPACE_URL_ENV, "").strip().rstrip("/")
+    if override:
+        return override
+    parts = urlsplit(base_url)
+    host = parts.hostname or ""
+    if not host.startswith("api.") or not parts.scheme:
+        return None
+    port = f":{parts.port}" if parts.port else ""
+    return f"{parts.scheme}://{host[len('api.') :]}{port}"
+
+
+def _add_workspace_url(result: Any, ctx: _Context) -> None:
+    """Add where a human reviews the open changeset, unless the server already said."""
+    if not isinstance(result, dict) or "workspace_url" in result:
+        return
+    detail = result.get("changeset")
+    changeset_id = result.get("changeset_id") or (detail.get("changeset_id") if isinstance(detail, dict) else None)
+    base = _workspace_base(ctx.base_url)
+    if changeset_id and base and ctx.project_id:
+        result["workspace_url"] = f"{base}/projects/{ctx.project_id}/context/changes/{changeset_id}"
+
+
+def _positive_seconds_from_env(name: str, default: float) -> float:
+    raw = os.environ.get(name, "").strip()
+    if not raw:
+        return default
+    try:
+        value = float(raw)
+    except ValueError:
+        value = 0.0
+    if not value > 0 or value == float("inf"):
+        raise CliError(f"{name} must be a positive number of seconds, got {raw!r}", code=2)
+    return value
+
+
+def _resolve_config(args: argparse.Namespace) -> dict[str, str]:
+    """Everything the CLI needs, read once. Names every missing variable at once, before
+    anything goes over the wire."""
+    secret = os.environ.get(CLIENT_SECRET_ENV, "").strip()
+    client_id = os.environ.get(CLIENT_ID_ENV, "").strip()
+    base_url = (args.api_url or os.environ.get(API_URL_ENV, "")).strip().rstrip("/")
+    token_url = (args.token_url or os.environ.get(TOKEN_URL_ENV, "")).strip()
+    if not token_url and base_url:
+        token_url = f"{base_url}{TOKEN_PATH}"
+    missing = []
+    if not client_id:
+        missing.append(CLIENT_ID_ENV)
+    if not secret:
+        missing.append(CLIENT_SECRET_ENV)
+    if not base_url:
+        missing.append(f"{API_URL_ENV} (or --api-url)")
+    if missing:
+        raise CliError(
+            f"missing configuration: {', '.join(missing)}. Credentials are read from the environment or from "
+            f"./{DOTENV_NAME}, never from a flag; create an API key in the project's API keys panel in the "
+            f"Workspace and put its values in ./{DOTENV_NAME}.",
+            code=2,
+        )
+    return {
+        "client_id": client_id,
+        "client_secret": secret,
+        "token_url": token_url,
+        "base_url": base_url,
+    }
+
+
+# --- parser ------------------------------------------------------------------
+
+
+class _Parser(argparse.ArgumentParser):
+    """Usage errors follow the ``--json`` contract when ``--json`` was asked for."""
+
+    json_errors = False
+
+    def error(self, message: str):  # type: ignore[override]
+        if not _Parser.json_errors:
+            super().error(message)  # prints usage + message to stderr, exits 2
+        print(json.dumps({"error": f"{self.prog}: {message}", "exit_code": 2}), file=sys.stderr)
+        raise SystemExit(2)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    common = argparse.ArgumentParser(add_help=False, allow_abbrev=False)
+    common.add_argument("--api-url", help=f"the API origin (default: ${API_URL_ENV})")
+    common.add_argument(
+        "--token-url",
+        help=f"the token endpoint (default: ${TOKEN_URL_ENV}, else <API URL>{TOKEN_PATH})",
+    )
+    common.add_argument(
+        "--json",
+        action="store_true",
+        help="print one compact JSON document on stdout; errors become a JSON object on stderr",
+    )
+
+    common.add_argument(
+        "--expect-project",
+        help=f"refuse to act unless the key resolves to this project (default: ${PROJECT_ID_ENV})",
+    )
+
+    parser = _Parser(
+        prog="coelevate",
+        allow_abbrev=False,
+        description=(
+            "Command-line client for the Coelevate Context Repository public API: read, "
+            "search, stage changes to assets and inspect releases. Asset changes are "
+            "stage-only - proposed, never landed - while a kit is written directly with "
+            "`kit`. Credentials come from the environment: "
+            f"{CLIENT_ID_ENV}, {CLIENT_SECRET_ENV}; the API origin from {API_URL_ENV} "
+            "(or --api-url)."
+        ),
+    )
+    parser.add_argument("--version", action="version", version=f"coelevate {__version__}")
+    sub = parser.add_subparsers(dest="action", required=True, metavar="ACTION")
+
+    def add(name: str, help_text: str) -> argparse.ArgumentParser:
+        return sub.add_parser(name, parents=[common], help=help_text, allow_abbrev=False)
+
+    read_p = add("read", "read one kit or one asset by id")
+    target = read_p.add_mutually_exclusive_group(required=True)
+    target.add_argument("--kit-id", help="read this kit")
+    target.add_argument("--asset-id", help="read this asset (any asset type)")
+    read_p.add_argument("--version", type=int, default=None, help="an archived version, else live")
+    read_p.add_argument("--links", action="store_true", help="expand resolved in/out edges (assets only)")
+
+    search_p = add("search", "lexical text search over your key's context")
+    search_p.add_argument("--query", required=True)
+    search_p.add_argument("--asset-type", action="append", help="repeatable; omit for every type")
+    search_p.add_argument("--max-results", type=int, default=20)
+
+    add("whoami", "show which project, API, default-token scopes and permitted scopes this key resolves to (never the secret)")
+    add("doctor", "check configuration, token, project pin, scopes and one read; exit 0/1/2")
+    assets_p = add("assets", "list assets from the index (id, type, label)")
+    assets_p.add_argument("--asset-type", action="append", help="repeatable; omit for every type")
+    assets_p.add_argument("--label", default=None, help="only assets with this label")
+    assets_p.add_argument("--limit", type=int, default=50)
+    assets_p.add_argument("--offset", type=int, default=0)
+
+    add("kits", "list the kits (id, title, version)")
+    add("asset-types", "list the asset types the context accepts")
+    add("changeset", "show the open changeset: revision, base release and staged ops")
+
+    stage_p = add("stage", "stage ops (or un-stage one) in the open changeset")
+    ops = stage_p.add_mutually_exclusive_group(required=True)
+    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")
+    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")
+    stage_p.add_argument("--expected-release", type=int, default=None, help="default: read from the changeset just before staging")
+
+    tag_p = add("tag", "look up the release currently holding a tag (read-only)")
+    tag_p.add_argument("--name", required=True, help="the tag to look up")
+
+    release_p = add("release", "list releases, or read one by number or tag")
+    release_p.add_argument("--number", type=int, default=None, help="read this one release")
+    release_p.add_argument("--tag", default=None, help="the release currently holding this tag")
+    release_p.add_argument("--limit", type=int, default=50)
+    release_p.add_argument("--offset", type=int, default=0)
+
+    kit_p = add(
+        "kit",
+        "write a kit directly (create, patch, add or remove members, revert, retire) or read its journal",
+    )
+    kit_p.add_argument("verb", choices=("create", "patch", "add-members", "remove-member", "revert", "retire", "journal"))
+    kit_p.add_argument("--kit-id", default=None, help="the kit (every verb but create)")
+    kit_p.add_argument("--asset-id", default=None, help="the member to take out (remove-member)")
+    kit_p.add_argument("--base-version", type=int, default=None, help="the kit version you read (remove-member, retire)")
+    kit_p.add_argument("--body", default=None, help="create, patch, add-members, revert: the request as a JSON string")
+    kit_p.add_argument("--body-file", default=None, help="create, patch, add-members, revert: the request as a JSON file")
+
+    gap_p = add(
+        "gap",
+        "list, read, record, edit, close (retire) or revert a gap directly, or read its journal",
+    )
+    gap_p.add_argument("verb", choices=("list", "get", "journal", "create", "patch", "retire", "revert"))
+    gap_p.add_argument("--gap-id", default=None, help="the gap (every verb but list and create)")
+    gap_p.add_argument("--state", choices=("open", "retired", "all"), default="open", help="list: which gaps (default open)")
+    gap_p.add_argument("--kind", default=None, help="list: only gaps of this kind")
+    gap_p.add_argument("--opened-release", type=int, default=None, help="list: only gaps opened in this release")
+    gap_p.add_argument("--closed-release", type=int, default=None, help="list: only gaps closed in this release")
+    gap_p.add_argument("--version", type=int, default=None, help="get: an archived version, else live")
+    gap_p.add_argument("--body", default=None, help="create, patch, retire, revert: the request as a JSON string")
+    gap_p.add_argument("--body-file", default=None, help="create, patch, retire, revert: the request as a JSON file")
+
+    return parser
+
+
+def _fail(exc: Exception, code: int, as_json: bool) -> int:
+    if as_json:
+        print(json.dumps({"error": str(exc), "exit_code": code}), file=sys.stderr)
+    else:
+        print(f"error: {exc}", file=sys.stderr)
+    return code
+
+
+def _expected_project(args: argparse.Namespace) -> str | None:
+    """The project the caller pinned: the flag, else ``COELEVATE_PROJECT_ID``, else none."""
+    return (args.expect_project or os.environ.get(PROJECT_ID_ENV, "")).strip() or None
+
+
+def _open_ctx(stack: ExitStack, args: argparse.Namespace, config: dict[str, str], scope: str, timeout: float, backoff: float) -> _Context:
+    http_client = stack.enter_context(httpx.Client(timeout=httpx.Timeout(timeout)))
+    http_client.auth = ClientCredentialsTokenSource(
+        token_url=config["token_url"],
+        client_id=config["client_id"],
+        client_secret=config["client_secret"],
+        scope=scope,
+        http_client=http_client,
+    )
+    return _Context(http_client, config["base_url"], backoff, _expected_project(args))
+
+
+def _doctor(args: argparse.Namespace, dotenv_keys: list[str]) -> int:
+    """Check each thing a session depends on, in order, and report all of it. Exit 0 when
+    everything holds, 2 when the configuration or pin is wrong, 1 when the service is."""
+    checks: list[dict[str, Any]] = []
+    codes: list[int] = []
+
+    def record(name: str, ok: bool, detail: str, code: int = 1) -> bool:
+        checks.append({"name": name, "ok": ok, "detail": detail})
+        if not ok:
+            codes.append(code)
+        return ok
+
+    record(
+        "dotenv",
+        True,
+        f"{len(dotenv_keys)} {DOTENV_PREFIX}* value(s) loaded from ./{DOTENV_NAME}"
+        if dotenv_keys
+        else f"nothing loaded from ./{DOTENV_NAME}",
+    )
+    try:
+        config = _resolve_config(args)
+        timeout = _positive_seconds_from_env(HTTP_TIMEOUT_ENV, DEFAULT_HTTP_TIMEOUT)
+        backoff = _positive_seconds_from_env(RETRY_BACKOFF_ENV, DEFAULT_RETRY_BACKOFF)
+    except CliError as exc:
+        record("configuration", False, str(exc), exc.code)
+        config = None
+    if config is not None:
+        record("configuration", True, "client id, client secret and API origin are set")
+        base = config["base_url"]
+        record("api", True, f"{urlsplit(base).netloc} ({_environment_label(base)}); workspace {_workspace_base(base) or 'unknown'}")
+        expected = _expected_project(args)
+        with ExitStack() as stack:
+            ctx = _open_ctx(stack, args, config, READ_SCOPE, timeout, backoff)
+            try:
+                ctx.http.auth.token()
+            except (OAuthTokenError, httpx.HTTPError) as exc:
+                record("token", False, str(exc))
+            else:
+                record("token", True, "exchanged for a bearer token")
+                project = ctx.project_id
+                record("project", project is not None, project or "the token response names no project")
+                pin_ok = True
+                if expected is not None:
+                    pin_ok = record(
+                        "pin",
+                        project == expected,
+                        f"{project} matches the pin"
+                        if project == expected
+                        else f"the key resolves to {project!r} but {expected!r} is pinned",
+                        2,
+                    )
+                record(
+                    "scopes",
+                    READ_SCOPE in (ctx.http.auth.granted_scope or "").split(),
+                    f"granted: {ctx.http.auth.granted_scope or 'none reported'}",
+                )
+                permits = _probe_permits(ctx.http.auth)
+                for scope, label, refused in (
+                    (ASSETS_SCOPE, "assets scope", "staging will be refused"),
+                    (KITS_SCOPE, "kits scope", "kit writes will be refused"),
+                    (GAPS_SCOPE, "gaps scope", "gap writes will be refused"),
+                ):
+                    granted = permits[scope]
+                    if granted is None:
+                        detail = "could not be checked (the token endpoint failed for another reason)"
+                    else:
+                        detail = "granted" if granted else f"not granted ({refused})"
+                    record(label, True, detail)
+                if pin_ok:
+                    try:
+                        kits = _cmd_kits(args, ctx)
+                        record("read", True, f"kits: {len(kits['kits'])}")
+                    except CliError as exc:
+                        record("read", False, str(exc), exc.code)
+                    except (OAuthTokenError, httpx.HTTPError) as exc:
+                        record("read", False, str(exc))
+    exit_code = 2 if 2 in codes else (1 if codes else 0)
+    if args.json:
+        print(json.dumps({"ok": exit_code == 0, "checks": checks, "exit_code": exit_code}, sort_keys=True, separators=(",", ":")))
+    else:
+        for check in checks:
+            print(f"{'ok  ' if check['ok'] else 'FAIL'}  {check['name']}: {check['detail']}")
+    return exit_code
+
+
+def main(argv: list[str] | None = None) -> int:
+    _Parser.json_errors = "--json" in (sys.argv[1:] if argv is None else argv)
+    args = build_parser().parse_args(argv)
+    try:
+        dotenv_keys = _load_dotenv(Path.cwd() / DOTENV_NAME)
+    except CliError as exc:
+        return _fail(exc, exc.code, args.json)
+    if args.action == "doctor":
+        return _doctor(args, dotenv_keys)
+    handler, scope_of = _HANDLERS[args.action]
+    try:
+        _check_retry_is_pinned(args)
+        config = _resolve_config(args)
+        timeout = _positive_seconds_from_env(HTTP_TIMEOUT_ENV, DEFAULT_HTTP_TIMEOUT)
+        backoff = _positive_seconds_from_env(RETRY_BACKOFF_ENV, DEFAULT_RETRY_BACKOFF)
+        with ExitStack() as stack:
+            ctx = _open_ctx(stack, args, config, scope_of(args), timeout, backoff)
+            result = handler(args, ctx)
+            if isinstance(result, dict):
+                if args.action in _PROJECT_ID_ACTIONS and ctx.project_id:
+                    result.setdefault("project_id", ctx.project_id)
+                if args.action in ("changeset", "stage"):
+                    _add_workspace_url(result, ctx)
+    except CliError as exc:
+        return _fail(exc, exc.code, args.json)
+    except OAuthTokenError as exc:
+        return _fail(exc, 1, args.json)
+    except httpx.HTTPError as exc:
+        return _fail(CliError(f"could not reach the token endpoint: {exc}"), 1, args.json)
+
+    if args.json:
+        print(json.dumps(result, sort_keys=True, separators=(",", ":")))
+    elif args.action == "kits":
+        print(_format_kits(result))
+    elif args.action == "assets":
+        print(_format_assets(result))
+    elif args.action == "whoami":
+        print(_format_whoami(result))
+    else:
+        print(json.dumps(result, indent=2, sort_keys=True))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())