agent-tool-openproject-cli 0.2.1__py3-none-any.whl

opcli/resolve.py

@@ -0,0 +1,183 @@
+"""Resolve human-friendly references to API hrefs / ids.
+
+Agents and humans want to write ``--status "In progress"``, ``--assignee admin``
+or ``--project my-project`` rather than juggle numeric ids. These helpers take a
+loose reference (numeric id, identifier, login, or name) and return the concrete
+resource, raising a clear :class:`NotFoundError` when nothing matches.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable
+
+from .client import Client
+from .errors import NotFoundError, OpError
+from . import hal
+
+Json = dict[str, Any]
+
+
+def _is_id(ref: str | int) -> bool:
+    return isinstance(ref, int) or (isinstance(ref, str) and ref.isdigit())
+
+
+def _match(elements: list[Json], ref: str, fields: list[str]) -> Json | None:
+    ref_l = ref.strip().lower()
+    # exact match, honouring FIELD priority: a login match beats a name match
+    # even if the name-matching element appears earlier in the collection.
+    for f in fields:
+        for el in elements:
+            val = el.get(f)
+            if isinstance(val, str) and val.lower() == ref_l:
+                return el
+    # then a unique substring match across all fields
+    hits = [
+        el
+        for el in elements
+        if any(isinstance(el.get(f), str) and ref_l in el[f].lower() for f in fields)
+    ]
+    if len(hits) == 1:
+        return hits[0]
+    return None
+
+
+def _resolve_collection(
+    client: Client,
+    collection: str,
+    ref: str | int,
+    fields: list[str],
+    *,
+    label: str,
+    params: dict | None = None,
+) -> Json:
+    if _is_id(ref):
+        return client.get(f"{collection}/{ref}")
+    elements = client.collect(collection, params=params, page_size=200)
+    el = _match(elements, str(ref), fields)
+    if el is None:
+        names = ", ".join(sorted(str(e.get(fields[0])) for e in elements)[:25])
+        raise NotFoundError(f"no {label} matching '{ref}'. Available: {names}")
+    return el
+
+
+def project(client: Client, ref: str | int) -> Json:
+    return _resolve_collection(
+        client, "projects", ref, ["identifier", "name"], label="project"
+    )
+
+
+def project_id(client: Client, ref: str | int) -> int:
+    return int(project(client, ref)["id"])
+
+
+def status(client: Client, ref: str | int) -> str:
+    el = _resolve_collection(client, "statuses", ref, ["name"], label="status")
+    return f"/api/v3/statuses/{el['id']}"
+
+
+def wp_type(client: Client, ref: str | int) -> str:
+    el = _resolve_collection(client, "types", ref, ["name"], label="type")
+    return f"/api/v3/types/{el['id']}"
+
+
+def priority(client: Client, ref: str | int) -> str:
+    el = _resolve_collection(client, "priorities", ref, ["name"], label="priority")
+    return f"/api/v3/priorities/{el['id']}"
+
+
+def time_activities(
+    client: Client, *, project_ref: str | int | None = None, wp_id: int | None = None
+) -> list[Json]:
+    """List time-entry activities via the time-entry form's schema.
+
+    This version of OpenProject has no ``time_entries/activities`` *collection*
+    endpoint; allowed activities live in the form schema (per project/WP).
+    """
+    links: dict = {}
+    if wp_id is not None:
+        links["workPackage"] = {"href": f"/api/v3/work_packages/{wp_id}"}
+    elif project_ref is not None:
+        links["project"] = {"href": f"/api/v3/projects/{project_id(client, project_ref)}"}
+    form = client.post("time_entries/form", json={"_links": links})
+    schema = (form.get("_embedded") or {}).get("schema") or {}
+    activity = schema.get("activity") or {}
+    allowed = (activity.get("_embedded") or {}).get("allowedValues") or []
+    out: list[Json] = []
+    for a in allowed:
+        aid = a.get("id")
+        href = ((a.get("_links") or {}).get("self") or {}).get("href") or f"/api/v3/time_entries/activities/{aid}"
+        out.append({"id": aid, "name": a.get("name"), "href": href})
+    return out
+
+
+def time_activity(
+    client: Client, ref: str | int, *, project_ref: str | int | None = None, wp_id: int | None = None
+) -> str:
+    if _is_id(ref):
+        return f"/api/v3/time_entries/activities/{ref}"
+    acts = time_activities(client, project_ref=project_ref, wp_id=wp_id)
+    el = _match(acts, str(ref), ["name"])
+    if el is None:
+        names = ", ".join(str(a.get("name")) for a in acts)
+        raise NotFoundError(f"no time-entry activity matching '{ref}'. Available: {names}")
+    return el["href"]
+
+
+def role(client: Client, ref: str | int) -> str:
+    el = _resolve_collection(client, "roles", ref, ["name"], label="role")
+    return f"/api/v3/roles/{el['id']}"
+
+
+def version(client: Client, ref: str | int, *, project_ref: str | int | None = None) -> Json:
+    """Resolve a version/milestone by id or name (project-scoped when given)."""
+    if _is_id(ref):
+        return client.get(f"versions/{ref}")
+    coll = "versions"
+    if project_ref is not None:
+        coll = f"projects/{project_id(client, project_ref)}/versions"
+    elements = client.collect(coll, page_size=200)
+    el = _match(elements, str(ref), ["name"])
+    if el is None:
+        names = ", ".join(str(e.get("name")) for e in elements)
+        raise NotFoundError(f"no version matching '{ref}'. Available: {names}")
+    return el
+
+
+def category(client: Client, ref: str | int, *, project_ref: str | int) -> Json:
+    if _is_id(ref):
+        return client.get(f"categories/{ref}")
+    elements = client.collect(f"projects/{project_id(client, project_ref)}/categories", page_size=200)
+    el = _match(elements, str(ref), ["name"])
+    if el is None:
+        raise NotFoundError(f"no category matching '{ref}'")
+    return el
+
+
+def user(client: Client, ref: str | int, *, project_ref: str | int | None = None) -> str:
+    """Resolve a user/principal to its href.
+
+    ``me`` resolves to the authenticated user. When ``project_ref`` is given we
+    search that project's assignable principals first (so names local to the
+    project resolve), then fall back to the global users collection.
+    """
+    if isinstance(ref, str) and ref.strip().lower() == "me":
+        return client.me()["_links"]["self"]["href"]
+    if _is_id(ref):
+        return f"/api/v3/users/{ref}"
+
+    ref_s = str(ref)
+    candidates: list[Json] = []
+    if project_ref is not None:
+        pid = project_id(client, project_ref)
+        candidates = client.collect(
+            f"projects/{pid}/available_assignees", page_size=200
+        )
+        el = _match(candidates, ref_s, ["login", "name", "email"])
+        if el is not None:
+            return el["_links"]["self"]["href"]
+    # global fallback
+    users = client.collect("principals", page_size=200)
+    el = _match(users, ref_s, ["login", "name", "email"])
+    if el is None:
+        raise NotFoundError(f"no user/principal matching '{ref}'")
+    return el["_links"]["self"]["href"]

opcli/searchspec.py

@@ -0,0 +1,269 @@
+"""Search ergonomics: a curated field registry, an operator reference, human
+date specs, and a ``--where`` mini-language that compiles to OpenProject filters.
+
+The goal is to make work-package search usable *without* memorising the raw
+JSON filter syntax:
+
+* a **field registry** so ``search fields`` can tell you what you can filter on;
+* an **operator reference** so ``search operators`` explains the codes;
+* **date specs** like ``7d``, ``2w``, ``today``, ``+30d`` -> concrete dates;
+* a **``--where "field op value"``** compiler so you can write
+  ``--where "status = open" --where "updated > 7d"`` instead of JSON.
+"""
+
+from __future__ import annotations
+
+import datetime as _dt
+import re
+from dataclasses import dataclass, field as _dc_field
+from typing import Any
+
+from . import hal, resolve
+from .client import Client
+from .errors import OpError
+
+
+@dataclass
+class Field:
+    key: str
+    label: str
+    kind: str  # status|type|priority|user|project|version|date|datetime|int|text|bool|duration|relation
+    ops: list[str] = _dc_field(default_factory=list)
+    flag: str = ""
+    desc: str = ""
+
+
+# The common, well-supported filters — used for discoverability and value
+# resolution. The live query schema is the source of truth for *which* filters
+# exist on an instance (incl. custom fields); this adds human meaning.
+REGISTRY: dict[str, Field] = {
+    f.key: f
+    for f in [
+        Field("search", "Full text", "text", ["**"], '"<query>" (positional)', "subject + description + comments"),
+        Field("subject", "Subject", "text", ["~", "!~"], "--subject", "title contains text"),
+        Field("id", "ID", "int", ["=", "!"], "--id 1,2,3", "specific work-package ids"),
+        Field("status", "Status", "status", ["=", "!", "o", "c"], "--status/--open/--closed", "open, closed, or a status name"),
+        Field("type", "Type", "type", ["=", "!"], "--type", "Task, Bug, Feature, ..."),
+        Field("priority", "Priority", "priority", ["=", "!"], "--priority", "Low, Normal, High, Immediate"),
+        Field("assignee", "Assignee", "user", ["=", "!", "*", "!*"], "--assignee/--mine/--unassigned", "login/name/id or 'me'"),
+        Field("author", "Author", "user", ["=", "!"], "--author/--created-by", "who created it"),
+        Field("responsible", "Accountable", "user", ["=", "!"], "--responsible", "accountable person"),
+        Field("watcher", "Watcher", "user", ["=", "!"], "--watching", "who watches it ('me')"),
+        Field("project", "Project", "project", ["=", "!"], "--project", "project id/identifier"),
+        Field("version", "Version", "version", ["=", "!"], "--version", "target version/milestone"),
+        Field("parent", "Parent", "int", ["=", "!"], "--parent", "parent work-package id"),
+        Field("dueDate", "Due date", "date", ["<>d", "=d", "t", "w"], "--due-before/--due-after/--overdue", "deadline"),
+        Field("startDate", "Start date", "date", ["<>d", "=d"], "--start-after/--start-before", "start date"),
+        Field("createdAt", "Created", "datetime", ["<>d", "t"], "--created-since/--created-before", "creation time"),
+        Field("updatedAt", "Updated", "datetime", ["<>d", "t"], "--updated-since", "last change time"),
+        Field("percentageDone", "% done", "int", [">=", "<="], '--where "percentageDone>=50"', "progress percent"),
+        Field("estimatedTime", "Estimated", "duration", [">=", "<="], '--where "estimatedTime>=PT2H"', "estimated time"),
+    ]
+}
+
+
+OPERATORS: list[tuple[str, str]] = [
+    ("=", "equals / one of (values are OR-ed)"),
+    ("!", "is none of / not equal"),
+    ("~", "contains (text, LIKE)"),
+    ("!~", "does not contain"),
+    ("o", "open statuses (status filter, no value)"),
+    ("c", "closed statuses (status filter, no value)"),
+    ("*", "has any value / is set"),
+    ("!*", "has no value / is empty (e.g. unassigned)"),
+    (">=", "greater than or equal (numbers)"),
+    ("<=", "less than or equal (numbers)"),
+    ("=d", "on a specific date"),
+    ("<>d", "between two dates (values=[from,to]; '' = open bound)"),
+    ("t", "today (date filter, no value)"),
+    ("w", "this week (date filter, no value)"),
+    ("t-", "exactly N days ago"),
+    ("t+", "exactly N days ahead"),
+    ("<t-", "more than N days ago"),
+    (">t-", "within the last N days"),
+    ("<t+", "within the next N days"),
+    (">t+", "more than N days ahead"),
+]
+
+
+# ------------------------------------------------------------------ dates
+_REL_RE = re.compile(r"^([+-]?)(\d+)\s*([dwmy])$")
+
+
+def to_date(spec: str, *, base: _dt.date | None = None) -> _dt.date:
+    """Human date spec -> concrete date.
+
+    ``today``/``yesterday``/``tomorrow``; ``7d``/``2w``/``1m``/``1y`` (N units
+    ago); ``+7d`` (N units ahead); or an ISO ``YYYY-MM-DD`` date.
+    """
+    base = base or _dt.date.today()
+    s = spec.strip().lower()
+    if s == "today":
+        return base
+    if s == "yesterday":
+        return base - _dt.timedelta(days=1)
+    if s == "tomorrow":
+        return base + _dt.timedelta(days=1)
+    m = _REL_RE.match(s)
+    if m:
+        sign = 1 if m.group(1) == "+" else -1  # default: into the past
+        n = int(m.group(2)) * sign
+        unit = m.group(3)
+        if unit == "d":
+            return base + _dt.timedelta(days=n)
+        if unit == "w":
+            return base + _dt.timedelta(weeks=n)
+        if unit == "m":
+            return _shift_months(base, n)
+        if unit == "y":
+            try:
+                return base.replace(year=base.year + n)
+            except ValueError:
+                return base.replace(year=base.year + n, day=28)
+    try:
+        return _dt.date.fromisoformat(spec)
+    except ValueError as exc:
+        raise OpError(
+            f"invalid date '{spec}' — use YYYY-MM-DD, or relative like 7d, 2w, 1m, +30d, today, yesterday"
+        ) from exc
+
+
+def _shift_months(d: _dt.date, months: int) -> _dt.date:
+    m = d.month - 1 + months
+    year = d.year + m // 12
+    month = m % 12 + 1
+    import calendar
+
+    day = min(d.day, calendar.monthrange(year, month)[1])
+    return _dt.date(year, month, day)
+
+
+# --------------------------------------------------------- value resolution
+def resolve_value(client: Client, kind: str, raw: str, *, project_ref: Any = None) -> str:
+    r = raw.strip()
+    if kind == "user":
+        if r.lower() == "me":
+            return "me"
+        href = resolve.user(client, r, project_ref=project_ref)
+        return str(hal.id_from_href(href))
+    if kind == "status":
+        return str(resolve._resolve_collection(client, "statuses", r, ["name"], label="status")["id"])
+    if kind == "type":
+        return str(resolve._resolve_collection(client, "types", r, ["name"], label="type")["id"])
+    if kind == "priority":
+        return str(resolve._resolve_collection(client, "priorities", r, ["name"], label="priority")["id"])
+    if kind == "project":
+        return str(resolve.project_id(client, r))
+    if kind == "version":
+        return str(resolve.version(client, r, project_ref=project_ref)["id"])
+    if kind in ("date", "datetime"):
+        return to_date(r).isoformat()
+    return r  # int/text/bool/relation/customfield -> as-is
+
+
+# friendly aliases so `--where "updated > 7d"` works, not just "updatedAt"
+ALIASES = {
+    "updated": "updatedAt",
+    "created": "createdAt",
+    "due": "dueDate",
+    "start": "startDate",
+    "done": "percentageDone",
+    "progress": "percentageDone",
+    "estimate": "estimatedTime",
+    "estimated": "estimatedTime",
+    "assigned": "assignee",
+    "milestone": "version",
+}
+
+
+def canonical_field(name: str) -> str:
+    return ALIASES.get(name.strip(), name.strip())
+
+
+# ------------------------------------------------------------- --where lang
+# order matters: match multi-char operators before single-char ones
+_WHERE_OPS = ["!~", ">=", "<=", "!=", "~", "=", ">", "<"]
+
+
+def parse_where(expr: str) -> tuple[str, str, list[str]]:
+    """``"status = open"`` / ``"updated>7d"`` / ``"assignee:none"`` ->
+    (field, symbol, values). ``:kw`` forms use symbols ``:open|:closed|:none|:any``."""
+    e = expr.strip()
+    # bare keyword form:  field:open
+    m = re.match(r"^\s*([A-Za-z0-9_]+)\s*:\s*(open|closed|none|any)\s*$", e, re.I)
+    if m:
+        return m.group(1), ":" + m.group(2).lower(), []
+    for sym in _WHERE_OPS:
+        idx = e.find(sym)
+        if idx > 0:
+            field = e[:idx].strip()
+            value = e[idx + len(sym):].strip()
+            if not field:
+                break
+            values = [v.strip() for v in value.split(",") if v.strip()]
+            return field, sym, values
+    raise OpError(f"could not parse --where '{expr}' (use e.g. \"status = open\", \"updated > 7d\", \"assignee:none\")")
+
+
+def compile_where(client: Client, expr: str, *, project_ref: Any = None) -> dict:
+    field, sym, values = parse_where(expr)
+    field = canonical_field(field)
+    fld = REGISTRY.get(field)
+    kind = fld.kind if fld else ("customfield" if field.startswith("customField") else "text")
+
+    # bare keyword operators
+    if sym == ":open":
+        return {field: {"operator": "o", "values": None}}
+    if sym == ":closed":
+        return {field: {"operator": "c", "values": None}}
+    if sym == ":none":
+        return {field: {"operator": "!*", "values": None}}
+    if sym == ":any":
+        return {field: {"operator": "*", "values": None}}
+
+    if not values:
+        raise OpError(f"--where '{expr}' needs a value")
+
+    resolved = [resolve_value(client, kind, v, project_ref=project_ref) for v in values]
+
+    # dates: >/< become open-ended ranges; = becomes on-date
+    if kind in ("date", "datetime"):
+        if sym in (">", ">="):
+            return {field: {"operator": "<>d", "values": [resolved[0], ""]}}
+        if sym in ("<", "<="):
+            return {field: {"operator": "<>d", "values": ["", resolved[0]]}}
+        if sym == "=":
+            return {field: {"operator": "=d", "values": [resolved[0]]}}
+
+    op_map = {"=": "=", "!=": "!", "!": "!", "~": "~", "!~": "!~", ">=": ">=", "<=": "<=", ">": ">=", "<": "<="}
+    op = op_map.get(sym)
+    if op is None:
+        raise OpError(f"operator '{sym}' not supported in --where")
+    return {field: {"operator": op, "values": resolved}}
+
+
+# ---------------------------------------------------------- live field list
+def live_fields(client: Client, project_ref: Any = None) -> list[dict]:
+    """List the filters available on this instance (from the query schema),
+    enriched with human descriptions from the registry."""
+    path = "queries/filter_instance_schemas"
+    if project_ref is not None:
+        path = f"projects/{resolve.project_id(client, project_ref)}/queries/filter_instance_schemas"
+    out: list[dict] = []
+    for el in client.collect(path, page_size=200):
+        href = ((el.get("_links") or {}).get("self") or {}).get("href", "")
+        key = href.rstrip("/").split("/")[-1]
+        if not key:
+            continue
+        reg = REGISTRY.get(key)
+        out.append(
+            {
+                "field": key,
+                "label": reg.label if reg else key,
+                "kind": reg.kind if reg else ("customField" if key.startswith("customField") else ""),
+                "operators": reg.ops if reg else [],
+                "flag": reg.flag if reg else ("--where / --filters" if not reg else ""),
+                "description": reg.desc if reg else "",
+            }
+        )
+    return out

opcli/serialize.py

@@ -0,0 +1,225 @@
+"""Turn verbose HAL documents into flat, agent-friendly dicts.
+
+Every serializer returns plain JSON-able dicts with relationships resolved to
+``{id, name}`` shapes and custom fields surfaced under a ``customFields`` map.
+The full HAL document is always available via ``--raw`` on the relevant
+commands, so these summaries can stay focused on what's useful.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from . import hal
+
+Json = dict[str, Any]
+
+# Only keys like customField1, customField42 are real custom fields; the bare
+# "customFields" _link is the admin collection and must be ignored.
+_CF_RE = re.compile(r"^customField\d+$")
+
+
+def _link_ref(doc: Json, name: str) -> Json | None:
+    href = hal.link_href(doc, name)
+    if href is None:
+        return None
+    return {"id": hal.id_from_href(href), "name": hal.link_title(doc, name), "href": href}
+
+
+def _formattable(value: Any) -> str | None:
+    if isinstance(value, dict):
+        return value.get("raw")
+    return value
+
+
+def custom_fields(doc: Json) -> Json:
+    """Collect customFieldN values from attributes and _links into one map."""
+    out: Json = {}
+    for key, value in doc.items():
+        if _CF_RE.match(key):
+            out[key] = _formattable(value) if isinstance(value, dict) and "raw" in value else value
+    for key in (doc.get("_links") or {}):
+        if _CF_RE.match(key):
+            node = doc["_links"][key]
+            if isinstance(node, list):
+                out[key] = [n.get("title") for n in node]
+            elif isinstance(node, dict):
+                out[key] = node.get("title")
+    return out
+
+
+def work_package(doc: Json, *, include_description: bool = True) -> Json:
+    out: Json = {
+        "id": doc.get("id"),
+        "subject": doc.get("subject"),
+        "type": hal.link_title(doc, "type"),
+        "status": hal.link_title(doc, "status"),
+        "priority": hal.link_title(doc, "priority"),
+        "project": _link_ref(doc, "project"),
+        "assignee": _link_ref(doc, "assignee"),
+        "responsible": _link_ref(doc, "responsible"),
+        "author": _link_ref(doc, "author"),
+        "parent": _link_ref(doc, "parent"),
+        "startDate": doc.get("startDate"),
+        "dueDate": doc.get("dueDate"),
+        "estimatedTime": doc.get("estimatedTime"),
+        "spentTime": doc.get("spentTime"),
+        "percentageDone": doc.get("percentageDone"),
+        "createdAt": doc.get("createdAt"),
+        "updatedAt": doc.get("updatedAt"),
+        "lockVersion": doc.get("lockVersion"),
+    }
+    if include_description:
+        out["description"] = _formattable(doc.get("description"))
+    cf = custom_fields(doc)
+    if cf:
+        out["customFields"] = cf
+    return out
+
+
+def project(doc: Json) -> Json:
+    out: Json = {
+        "id": doc.get("id"),
+        "name": doc.get("name"),
+        "identifier": doc.get("identifier"),
+        "active": doc.get("active"),
+        "public": doc.get("public"),
+        "parent": _link_ref(doc, "parent"),
+        "status": hal.link_title(doc, "status") or hal.link_id(doc, "status"),
+        "description": _formattable(doc.get("description")),
+        "createdAt": doc.get("createdAt"),
+        "updatedAt": doc.get("updatedAt"),
+    }
+    cf = custom_fields(doc)
+    if cf:
+        out["customFields"] = cf
+    return out
+
+
+def user(doc: Json) -> Json:
+    return {
+        "id": doc.get("id"),
+        "login": doc.get("login"),
+        "name": doc.get("name"),
+        "firstName": doc.get("firstName"),
+        "lastName": doc.get("lastName"),
+        "email": doc.get("email"),
+        "admin": doc.get("admin"),
+        "status": doc.get("status"),
+        "_type": doc.get("_type"),
+    }
+
+
+def principal(doc: Json) -> Json:
+    """A user, group, or placeholder user (used for assignees/members)."""
+    return {
+        "id": doc.get("id"),
+        "name": doc.get("name"),
+        "login": doc.get("login"),
+        "email": doc.get("email"),
+        "type": doc.get("_type"),
+    }
+
+
+def comment(doc: Json) -> Json:
+    """An activity entry; comments have a non-empty ``comment.raw``."""
+    return {
+        "id": doc.get("id"),
+        "comment": _formattable(doc.get("comment")),
+        "user": _link_ref(doc, "user"),
+        "workPackage": _link_ref(doc, "workPackage"),
+        "version": doc.get("version"),
+        "createdAt": doc.get("createdAt"),
+        "updatedAt": doc.get("updatedAt"),
+        "_type": doc.get("_type"),
+    }
+
+
+def time_entry(doc: Json) -> Json:
+    return {
+        "id": doc.get("id"),
+        "hours": doc.get("hours"),
+        "spentOn": doc.get("spentOn"),
+        "comment": _formattable(doc.get("comment")),
+        "user": _link_ref(doc, "user"),
+        "workPackage": _link_ref(doc, "workPackage"),
+        "project": _link_ref(doc, "project"),
+        "activity": hal.link_title(doc, "activity"),
+        "createdAt": doc.get("createdAt"),
+        "updatedAt": doc.get("updatedAt"),
+        "customFields": custom_fields(doc) or None,
+    }
+
+
+def membership(doc: Json) -> Json:
+    roles = [n.get("title") for n in hal.iter_link_list(doc, "roles")]
+    return {
+        "id": doc.get("id"),
+        "principal": _link_ref(doc, "principal"),
+        "project": _link_ref(doc, "project"),
+        "roles": roles,
+        "createdAt": doc.get("createdAt"),
+    }
+
+
+def notification(doc: Json) -> Json:
+    return {
+        "id": doc.get("id"),
+        "subject": doc.get("subject"),
+        "reason": doc.get("reason"),
+        "readIAN": doc.get("readIAN"),
+        "resource": _link_ref(doc, "resource"),
+        "project": _link_ref(doc, "project"),
+        "actor": _link_ref(doc, "actor"),
+        "createdAt": doc.get("createdAt"),
+        "updatedAt": doc.get("updatedAt"),
+    }
+
+
+def attachment(doc: Json) -> Json:
+    return {
+        "id": doc.get("id"),
+        "fileName": doc.get("fileName"),
+        "fileSize": doc.get("fileSize"),
+        "description": _formattable(doc.get("description")),
+        "contentType": doc.get("contentType"),
+        "author": _link_ref(doc, "author"),
+        "downloadLocation": hal.link_href(doc, "downloadLocation"),
+        "createdAt": doc.get("createdAt"),
+    }
+
+
+def file_link(doc: Json) -> Json:
+    origin = doc.get("originData") or {}
+    return {
+        "id": doc.get("id"),
+        "originName": origin.get("name"),
+        "originId": origin.get("id"),
+        "mimeType": origin.get("mimeType"),
+        "storage": hal.link_title(doc, "storage"),
+        "storageUrl": hal.link_href(doc, "storage"),
+        "status": hal.link_title(doc, "status"),
+        "createdAt": doc.get("createdAt"),
+    }
+
+
+def custom_field_schema(name: str, spec: Json) -> Json:
+    """Describe one field from a resource schema (used by `cf` commands)."""
+    out: Json = {
+        "key": name,
+        "name": spec.get("name"),
+        "type": spec.get("type"),
+        "required": spec.get("required"),
+        "writable": spec.get("writable"),
+    }
+    allowed = spec.get("_embedded", {}).get("allowedValues")
+    if isinstance(allowed, list) and allowed:
+        out["allowedValues"] = [
+            {"id": a.get("id"), "name": a.get("name") or a.get("value")} for a in allowed if isinstance(a, dict)
+        ]
+    elif "_links" in spec and isinstance(spec["_links"].get("allowedValues"), list):
+        out["allowedValues"] = [
+            {"href": a.get("href"), "name": a.get("title")} for a in spec["_links"]["allowedValues"]
+        ]
+    return out