coho-cli 2026.1.0a21__py3-none-any.whl

coho_cli/__init__.py

@@ -0,0 +1,8 @@
+"""coho_cli — the ``coho`` command. A thin layer over ``coho_management_sdk``."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("coho-cli")
+except PackageNotFoundError:  # pragma: no cover - editable/dev installs
+    __version__ = "0.0.0"

coho_cli/_entry_ids.py

@@ -0,0 +1,164 @@
+"""``@<slug>`` wherever a command takes an entry id: the slug is looked up on the same
+ref, and the command carries on with the id as if it had been typed.
+
+The lookup is the delivery contract's ``entries-by-slug/{slug}`` read, which the BFF
+serves live for a ref under ``preview/`` — one request at depth 0, the entry alone. The
+management API has no slug filter on ``entries``, and paging through every entry to find
+one is not a lookup.
+
+What that read can and cannot answer:
+
+- Slugs are unique per ref among every node's slugs (coho-data D24), so a slug names at
+  most one node. That node may be a content type or an asset rather than an entry, and
+  is refused as one.
+- A deleted entry has no slug on the ref any more: its id still reaches its history.
+- Live reads serve a branch, or an environment on one. A tag is refused as a ref that
+  does not exist, so on a tag the id is the only way in.
+
+Entry ids are UUIDs, so no id starts with ``@`` and the prefix cannot shadow one. A UUID
+is a well-formed slug too, so ``@<uuid>`` is looked up as a slug like any other.
+
+The same goes for the value of a reference field in ``--set``: ``author=@priya-shah``,
+``tags=["@traffic","@drainage"]``, and of an asset field, where the slug is an asset's:
+``image=@culvert``, ``downloads=["@guide"]``. Only reference and asset fields, as the
+entry's content type declares them, are looked up, so a text field may still hold
+``@handle``. The server then checks the ids as it checks any: that each exists and is of
+a type, or a media type, the field allows.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Callable
+from typing import Any
+from uuid import UUID
+
+from coho_management_sdk import NotFound, Ref
+from coho_management_sdk.errors import RefNotFound
+from coho_management_sdk.transport import segment
+
+from ._state import Usage
+
+# A content slug, as `_slugs.content_slug` makes them and the server checks them.
+_CONTENT_SLUG = re.compile(r"^[a-z0-9]+(-[a-z0-9]+)*$")
+
+
+def entry_id(ref: Ref, raw: str) -> str:
+    """The entry id ``raw`` names on ``ref``: itself, or for ``@<slug>`` the id of the
+    entry with that slug. Pass the ``Ref`` the command then acts on, so the slug is
+    looked up where the id will be used."""
+    if not raw.startswith("@"):
+        return raw
+    slug = raw[1:]
+    if not _CONTENT_SLUG.match(slug):
+        raise Usage(
+            f"{raw!r} is not an entry slug: after `@` comes a slug such as @hello-world. "
+            "An entry id is a UUID and is passed without the `@`."
+        )
+    preview = ref.preview()
+    try:
+        # ⚠️ The SDK's Preview has no by-slug read yet; this is the one request it would
+        # make. Move it to `preview.entry_by_slug(slug)` once the SDK has one.
+        body = preview._t.get(f"{preview.path}/entries-by-slug/{segment(slug)}").body or {}
+    except RefNotFound:
+        raise Usage(
+            f"cannot look up {raw} on {ref.name}: slugs resolve on a branch, or an "
+            "environment on one, and this ref is a tag or does not exist. Use the entry id."
+        ) from None
+    except NotFound as exc:
+        # ⚠️ The BFF answers every 404 it relays as ROUTE_NOT_FOUND for now, its own
+        # status page replacing authoring's problem, so a missing slug and a tag both
+        # arrive as that. Read as either until the BFF relays the code it is given.
+        if exc.code not in ("ENTRY_NOT_FOUND", "ROUTE_NOT_FOUND"):
+            raise
+        # A UUID is a well-formed slug too, so `@<id>` is looked up rather than refused.
+        hint = (
+            f"To use {slug} as an entry id, drop the `@`."
+            if _is_uuid(slug)
+            else "`coho entry list` shows the slugs."
+        )
+        if exc.code == "ROUTE_NOT_FOUND":
+            hint += " On a tag, slugs do not resolve: use the entry id."
+        raise NotFound(
+            f"no entry with slug '{slug}' on {ref.name}. {hint}",
+            code="ENTRY_NOT_FOUND",
+            status=404,
+        ) from None
+    roots = body.get("roots") or []
+    if len(roots) != 1:  # pragma: no cover - slugs are unique per ref (D24)
+        raise Usage(f"{raw} names {len(roots)} nodes on {ref.name}. Use the entry id.")
+    node = (body.get("entries") or {}).get(roots[0]) or {}
+    # Only an entry has a content type. A type's or an asset's slug comes back without one.
+    if not node.get("type"):
+        raise Usage(
+            f"{raw} on {ref.name} is a content type or an asset, not an entry. "
+            "Slugs are unique across all three."
+        )
+    return str(roots[0])
+
+
+def reference_ids(
+    ref: Ref, type_of: Callable[[], str], sets: list[tuple[str, Any]]
+) -> list[tuple[str, Any]]:
+    """``--set`` values, each ``@<slug>`` in a reference or asset field replaced by the id
+    of the entry, or the asset, with that slug on ``ref``. ``type_of`` gives the entry's
+    content type, and is only called, and the type only read, when some value names a
+    slug: otherwise nothing is requested."""
+    if not any(_names_slug(value) for _, value in sets):
+        return sets
+    # Effective, so a field the type inherits, or takes from a trait, is found too: a
+    # subtype's `author=@priya-shah` names its parent's reference field.
+    kinds = {
+        f.get("id"): f.get("type")
+        for f in ref.types.get(type_of(), effective=True).fields
+        if isinstance(f, dict) and f.get("type") in ("reference", "asset")
+    }
+    found: dict[str, str] = {}
+    assets: dict[str, str] | None = None
+
+    def asset_id(raw: str) -> str:
+        # Assets are listed once, by the first asset slug named: the management API has
+        # no by-slug read for them, and a page of 1000 covers most projects in one request.
+        nonlocal assets
+        if assets is None:
+            assets = {a.slug: a.id for a in ref.assets.iterate(page_size=1000)}
+        slug = raw[1:]
+        if slug not in assets:
+            raise NotFound(
+                f"no asset with slug '{slug}' on {ref.name}. `coho asset list` shows the slugs.",
+                code="ASSET_NOT_FOUND",
+                status=404,
+            )
+        return assets[slug]
+
+    def resolve(kind: Any, value: Any) -> Any:
+        if not (isinstance(value, str) and value.startswith("@")):
+            return value
+        key = f"{kind}:{value}"
+        if key not in found:
+            found[key] = asset_id(value) if kind == "asset" else entry_id(ref, value)
+        return found[key]
+
+    out: list[tuple[str, Any]] = []
+    for path, value in sets:
+        kind = kinds.get(path.split(".")[0])
+        if kind is not None:
+            if isinstance(value, list):
+                value = [resolve(kind, v) for v in value]
+            else:
+                value = resolve(kind, value)
+        out.append((path, value))
+    return out
+
+
+def _names_slug(value: Any) -> bool:
+    values = value if isinstance(value, list) else [value]
+    return any(isinstance(v, str) and v.startswith("@") for v in values)
+
+
+def _is_uuid(value: str) -> bool:
+    try:
+        UUID(value)
+    except ValueError:
+        return False
+    return True

coho_cli/_io.py

@@ -0,0 +1,55 @@
+"""Reading JSON from files, stdin or inline strings — for --file and --fields."""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+from ._state import Usage
+
+
+def read_json(source: str | None, *, what: str = "JSON") -> Any:
+    """``-`` reads stdin; a path reads a file; anything starting with ``{`` or ``[`` is inline."""
+    if source is None:
+        raise Usage(f"{what} is required")
+    text: str
+    if source == "-":
+        text = sys.stdin.read()
+    elif source.lstrip().startswith(("{", "[")):
+        text = source
+    else:
+        path = Path(source)
+        if not path.exists():
+            raise Usage(f"{what}: no such file: {source}")
+        text = path.read_text()
+    try:
+        return json.loads(text)
+    except ValueError as exc:
+        raise Usage(f"{what} is not valid JSON: {exc}") from exc
+
+
+def set_path(doc: dict[str, Any], dotted: str, value: Any) -> None:
+    """Set ``a.b.c`` in a nested dict, creating levels. Used by ``--set``."""
+    parts = dotted.split(".")
+    cur = doc
+    for p in parts[:-1]:
+        nxt = cur.get(p)
+        if not isinstance(nxt, dict):
+            nxt = {}
+            cur[p] = nxt
+        cur = nxt
+    cur[parts[-1]] = value
+
+
+def parse_set(spec: str) -> tuple[str, Any]:
+    """``path=value``; the value is JSON if it parses, else a string."""
+    if "=" not in spec:
+        raise Usage(f"--set needs path=value, got '{spec}'")
+    path, raw = spec.split("=", 1)
+    try:
+        value: Any = json.loads(raw)
+    except ValueError:
+        value = raw
+    return path.strip(), value

coho_cli/_output.py

@@ -0,0 +1,103 @@
+"""Printing: tables for people, JSON for scripts, and the shown-once warnings."""
+
+from __future__ import annotations
+
+import json
+import sys
+from collections.abc import Iterable, Sequence
+from typing import Any
+
+from rich.console import Console
+from rich.table import Table
+
+from ._state import State
+
+console = Console()
+err = Console(stderr=True)
+
+
+def emit_json(data: Any) -> None:
+    """Exactly what the contract describes, on stdout."""
+    sys.stdout.write(json.dumps(data, indent=2, ensure_ascii=False))
+    sys.stdout.write("\n")
+
+
+def table(
+    state: State,
+    raw: Any,
+    columns: Sequence[str],
+    rows: Iterable[Sequence[Any]],
+    *,
+    title: str | None = None,
+    empty: str = "(none)",
+) -> None:
+    """Print ``rows`` as a table, or ``raw`` as JSON when ``--output json``."""
+    if state.output == "json":
+        emit_json(raw)
+        return
+    rows = list(rows)
+    if not rows:
+        console.print(f"[dim]{empty}[/dim]")
+        return
+    t = Table(title=title, show_lines=False, header_style="bold", box=None, pad_edge=False)
+    for c in columns:
+        t.add_column(c)
+    for r in rows:
+        t.add_row(*[_cell(v) for v in r])
+    console.print(t)
+
+
+def record(state: State, raw: Any, pairs: Sequence[tuple[str, Any]]) -> None:
+    """One object as ``key  value`` lines, or JSON."""
+    if state.output == "json":
+        emit_json(raw)
+        return
+    width = max((len(k) for k, _ in pairs), default=0)
+    for k, v in pairs:
+        console.print(f"[bold]{k.ljust(width)}[/bold]  {_cell(v)}", highlight=False, markup=True)
+
+
+def say(state: State, message: str) -> None:
+    """A one-line confirmation for humans; silent under ``--output json`` and ``--quiet``."""
+    if state.output != "json" and not state.quiet:
+        console.print(message, highlight=False)
+
+
+def warn(message: str) -> None:
+    err.print(f"[yellow]warning:[/yellow] {message}", highlight=False)
+
+
+def secret_once(
+    state: State, raw: Any, label: str, value: str, extra: Sequence[tuple[str, Any]] = ()
+) -> None:
+    """Print a value that the server will never show again.
+
+    In JSON mode the whole response is printed (scripts need the field); in table mode
+    the value is printed on its own line, unmarked-up, so it can be copied, with a
+    warning on stderr so the warning is never captured into a file.
+    """
+    if state.output == "json":
+        emit_json(raw)
+    else:
+        for k, v in extra:
+            console.print(f"[bold]{k}[/bold]  {_cell(v)}", highlight=False)
+        console.print(f"[bold]{label}[/bold]")
+        sys.stdout.write(value + "\n")
+        sys.stdout.flush()
+    err.print(f"[yellow]This {label.lower()} is shown once and cannot be retrieved again.[/yellow]")
+
+
+def _cell(value: Any) -> str:
+    if value is None:
+        return "[dim]-[/dim]"
+    if isinstance(value, bool):
+        return "yes" if value else "no"
+    if isinstance(value, list | tuple):
+        return ", ".join(_cell(v) for v in value) if value else "[dim]-[/dim]"
+    if isinstance(value, dict):
+        return json.dumps(value, ensure_ascii=False)
+    return str(value)
+
+
+def short(value: str | None, n: int = 8) -> str:
+    return (value or "")[:n]

coho_cli/_slugs.py

@@ -0,0 +1,59 @@
+"""Build slugs from names. The API checks them; this is the one place they are made.
+
+A type slug is camelCase (``Blog post`` -> ``blogPost``) because it appears in code:
+``coho entry create -t blogPost`` and ``of: ["teamMember"]``. A content slug is
+kebab-case (``Hello, World!`` -> ``hello-world``) because it appears in URLs.
+
+These rules mirror ``coho.model.Slugs`` on the server, which stays the authority: a
+generated slug that the server would refuse is refused here first, with a message
+that says what to pass instead.
+"""
+
+from __future__ import annotations
+
+import re
+import unicodedata
+
+from ._state import Usage
+
+_TYPE_SLUG = re.compile(r"^[a-z][a-zA-Z0-9]*$")
+_CONTENT_SLUG = re.compile(r"^[a-z0-9]+(-[a-z0-9]+)*$")
+
+
+def _words(name: str) -> list[str]:
+    # Accents fold to their base letter (Über -> Uber). Anything else that is not
+    # ASCII letter or digit is a separator, so punctuation and spacing both break words.
+    folded = unicodedata.normalize("NFKD", name).encode("ascii", "ignore").decode("ascii")
+    return re.findall(r"[A-Za-z0-9]+", folded)
+
+
+def type_slug(name: str) -> str:
+    """camelCase from a name: the first word lowercased, each later word capitalised."""
+    words = _words(name)
+    if not words:
+        raise Usage(
+            f"cannot build a type slug from {name!r}: it has no letters or digits. "
+            "Pass the slug explicitly."
+        )
+    head, *tail = words
+    slug = head.lower() + "".join(w[:1].upper() + w[1:].lower() for w in tail)
+    if not _TYPE_SLUG.match(slug):
+        raise Usage(
+            f"cannot build a type slug from {name!r}: it must start with a letter. "
+            "Pass the slug explicitly."
+        )
+    return slug
+
+
+def content_slug(name: str) -> str:
+    """kebab-case from a name: every word lowercased and joined with hyphens."""
+    words = _words(name)
+    if not words:
+        raise Usage(
+            f"cannot build a content slug from {name!r}: it has no letters or digits. "
+            "Pass --slug explicitly."
+        )
+    slug = "-".join(w.lower() for w in words)
+    if not _CONTENT_SLUG.match(slug):  # pragma: no cover - the rule holds by construction
+        raise Usage(f"cannot build a content slug from {name!r}. Pass --slug explicitly.")
+    return slug

coho_cli/_state.py

@@ -0,0 +1,205 @@
+"""What every command needs: the config, the profile, a client, and the context.
+
+Resolution order for the three context values (account, project, ref):
+``--account/--project/--ref`` flags → ``COHO_ACCOUNT/COHO_PROJECT/COHO_REF`` →
+the profile's saved context (``coho use``). A missing value is a usage error that
+names the flag and the ``use`` command, not a stack trace.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from functools import cached_property
+from uuid import UUID
+
+import typer
+from coho_management_sdk import Account, Coho, Config, Profile, Project, Ref
+from coho_management_sdk.models import Membership
+from coho_management_sdk.profiles import Context
+
+EXIT_ERROR = 1
+EXIT_USAGE = 2
+EXIT_AUTH = 3
+EXIT_CONFLICT = 4
+EXIT_NOT_FOUND = 5
+
+
+class Usage(Exception):
+    """A usage error: printed as one line by ``main()``, exit code 2, no traceback."""
+
+    exit_code = EXIT_USAGE
+
+    def __init__(self, message: str) -> None:
+        super().__init__(message)
+        self.message = message
+
+
+@dataclass
+class State:
+    profile_name: str | None = None
+    output: str = "table"
+    url: str | None = None
+    overrides: Context = field(default_factory=Context)
+    quiet: bool = False
+    yes: bool = False
+    # Set when the account came from the saved context rather than `--account`, so an
+    # ACCOUNT_NOT_FOUND can say the saved one may be gone: deleted, or a reset environment.
+    used_saved_account: bool = field(default=False, init=False)
+    # What to say after a 403, when the command knows better than the server's message
+    # what the person can do instead.
+    forbidden_hint: str | None = field(default=None, init=False)
+
+    @cached_property
+    def config(self) -> Config:
+        return Config.load()
+
+    @cached_property
+    def profile(self) -> Profile:
+        try:
+            return self.config.profile(self.profile_name)
+        except KeyError as exc:
+            name = exc.args[0]
+            raise Usage(
+                f"no profile named '{name}'. Create it: coho configure --profile {name} --url https://…"
+            ) from exc
+
+    @property
+    def context(self) -> Context:
+        saved = self.profile.context.with_env()
+        return Context(
+            account=self.overrides.account or saved.account,
+            project=self.overrides.project or saved.project,
+            ref=self.overrides.ref or saved.ref,
+        )
+
+    @cached_property
+    def coho(self) -> Coho:
+        url = self.url or self.config.effective_url(self.profile)
+        if not url:
+            raise Usage(
+                f"profile '{self.profile.name}' has no url. Set one: "
+                f"coho configure --profile {self.profile.name} --url https://…"
+            )
+        return Coho(url, profile=self.profile)
+
+    # -- context resolution ----------------------------------------------------
+
+    def account(self) -> Account:
+        # Named on the command line or in COHO_ACCOUNT: used as given, never second-guessed.
+        if self.overrides.account:
+            return self.coho.account(self.overrides.account)
+        name = self.context.account
+        # ⚠️ A saved account can outlive the account: deleted, or an environment reset. Checked
+        # against `/me` (one request, cached for the command) so a person with one account is
+        # not stuck on one they no longer have. Not with a project token: it has no `/me`.
+        if name and not self.coho.uses_project_token:
+            memberships = self.coho.accounts()
+            if not any(name in (m.account_id, m.account_name) for m in memberships):
+                return self._instead_of_gone(name, memberships)
+        if name:
+            self.used_saved_account = True
+            return self.coho.account(name)
+        # No account chosen. Someone in exactly one account has nothing to choose,
+        # so that one is used; with several, guessing would act on the wrong one.
+        memberships = self.coho.accounts()
+        if len(memberships) == 1:
+            return self.coho.account(memberships[0].account_id)
+        if not memberships:
+            raise Usage(
+                "you are not in any account yet. Create one with `coho signup`, "
+                "or ask an account admin to invite you."
+            )
+        names = ", ".join(sorted(m.account_name for m in memberships))
+        raise Usage(
+            f"you are in {len(memberships)} accounts ({names}). "
+            "Choose one with `coho use <account>` or pass --account."
+        )
+
+    def _instead_of_gone(self, gone: str, memberships: list[Membership]) -> Account:
+        """The saved account is not one of the caller's: their only one if they have one,
+        saved in its place, or a usage error that says what to choose."""
+        from ._output import warn
+
+        # Only ever the profile's: `--account` and COHO_ACCOUNT (its envvar) are used as given.
+        p = self.profile.name
+        if not memberships:
+            raise Usage(
+                "you are not in any account yet. Create one with `coho signup`, "
+                "or ask an account admin to invite you."
+            )
+        if len(memberships) > 1:
+            names = ", ".join(sorted(m.account_name for m in memberships))
+            raise Usage(
+                f"the account saved for profile '{p}' is not one of yours; it may have been "
+                f"deleted. You are in {len(memberships)} accounts ({names}): choose one with "
+                "`coho use <account>`."
+            )
+        only = memberships[0]
+        # As `coho use` does when the account changes: the project and ref were the gone account's.
+        self.profile.context.account = only.account_id
+        self.profile.context.project = None
+        self.profile.context.ref = None
+        self.save()
+        warn(
+            f"the account saved for profile '{p}' is not one of yours; it may have been "
+            f"deleted. Using {only.account_name}, your only account, from now on."
+        )
+        return self.coho.account(only.account_id)
+
+    def project(self) -> Project:
+        account = self.account()
+        raw = self.context.project
+        if not raw:
+            raise Usage(
+                "no project in context. Run `coho use <account> <project>` or pass --project."
+            )
+        return account.project(self.resolve_project_id(account, raw))
+
+    def resolve_project_id(self, account: Account, raw: str) -> str:
+        """A project id from an id, a locally remembered name, or a name on the server.
+
+        The local registry answers first and without a request; an id passes
+        through; anything else is matched by name against the projects the server
+        lists for you. Two projects with the same name are refused rather than
+        guessed between.
+        """
+        known = self.profile.resolve_project(account.id, raw)
+        if known != raw or _is_uuid(raw):
+            return known
+        matches = [p for p in account.projects.list() if p.name.casefold() == raw.casefold()]
+        if len(matches) == 1:
+            return matches[0].id
+        if not matches:
+            raise Usage(f"no project named '{raw}' that you can open. See `coho project list`.")
+        ids = ", ".join(p.id for p in matches)
+        raise Usage(f"{len(matches)} projects are named '{raw}' ({ids}). Use the id.")
+
+    def ref(self) -> Ref:
+        project = self.project()
+        name = self.context.ref
+        if not name:
+            raise Usage("no ref in context. Run `coho ref switch <ref>` or pass --ref.")
+        return project.ref(name)
+
+    def save(self) -> None:
+        self.config.save()
+
+
+# The running command's state, for `main` to read once an error has escaped the command.
+current: State | None = None
+
+
+def get_state(ctx: typer.Context) -> State:
+    state = ctx.find_root().obj
+    if not isinstance(state, State):  # pragma: no cover - typer wiring
+        state = State()
+        ctx.find_root().obj = state
+    return state
+
+
+def _is_uuid(value: str) -> bool:
+    try:
+        UUID(value)
+    except ValueError:
+        return False
+    return True