sagex-cli 1.0.0__py3-none-any.whl

sagex/api/resources.py

@@ -0,0 +1,763 @@
+"""Fetch and normalize Autosage resources into display-ready shapes.
+
+All backend-shape knowledge (envelope quirks, field names, pagination) lives here,
+so the UI code just asks for "the list of workflow names" and gets a clean list.
+"""
+
+import httpx
+
+from sagex.api.client import ApiClient, ApiError
+from sagex.api.client import waiting as client_waiting
+from sagex.formatting import relative_time, truncate_name
+
+
+def _as_list(data) -> list:
+    """List endpoints may return a plain list OR a paginated {results: [...]} dict."""
+    if isinstance(data, dict):
+        return data.get("results", [])
+    return data or []
+
+
+def list_workflows(client: ApiClient) -> list[str]:
+    """Return workflow display names (trimmed)."""
+    data = client.get("/api/workflows/")
+    return [truncate_name(w.get("name") or "(unnamed)") for w in _as_list(data)]
+
+
+def list_scripts(client: ApiClient) -> list[str]:
+    """Return script file names (trimmed)."""
+    data = client.get("/api/scripts/")
+    return [truncate_name(s.get("name") or "(unnamed)") for s in _as_list(data)]
+
+
+def list_vault_resources(client: ApiClient) -> list[str]:
+    """Return vault items — servers and credentials — labeled by kind.
+
+    Only the name is trimmed; the '(server)'/'(credential)' kind is kept intact.
+    """
+    servers = _as_list(client.get("/api/vault/servers/"))
+    creds = _as_list(client.get("/api/vault/credentials/"))
+    labels = [f"{truncate_name(s.get('name') or '(unnamed)')} (server)" for s in servers]
+    labels += [f"{truncate_name(c.get('name') or '(unnamed)')} (credential)" for c in creds]
+    return labels
+
+
+def list_triggers(client: ApiClient) -> list[tuple[str, str, bool]]:
+    """Return configured triggers as (workflow_name, detail, is_active).
+
+    From the aggregate /api/triggers/ endpoint (one call); data is
+    {"http_triggers": [...], "schedule_triggers": [...]}. `detail` is just the
+    trigger TYPE — "scheduler" or "http" — kept short on purpose; the cron/URL and
+    full details will come from a command later. The endpoint only returns
+    *configured* triggers, which is what we want.
+    """
+    data = client.get("/api/triggers/") or {}
+    out: list[tuple[str, str, bool]] = []
+    for t in data.get("schedule_triggers", []):
+        name = t.get("workflow_name") or "(workflow)"
+        out.append((name, "scheduler", bool(t.get("is_active"))))
+    for t in data.get("http_triggers", []):
+        name = t.get("workflow_name") or "(workflow)"
+        out.append((name, "http", bool(t.get("is_active"))))
+    return out
+
+
+def list_recent_runs(client: ApiClient, limit: int = 5) -> list[tuple[str, str, str]]:
+    """Return the most recent workflow runs as (status, workflow_name, relative_time)."""
+    runs = _as_list(client.get("/api/execution-engine/workflows/runs/"))
+    runs.sort(key=lambda r: r.get("created_at") or "", reverse=True)   # newest first
+    return [
+        (
+            r.get("status") or "unknown",
+            r.get("workflow_name") or "(workflow)",
+            relative_time(r.get("created_at")),
+        )
+        for r in runs[:limit]
+    ]
+
+
+# ---------------------------------------------------------------------------
+# Single-resource lookup ("show" / "copy"): resolve a name-or-id reference to
+# one record, then fetch its full detail. Shared by the CLI and (later) the TUI.
+# ---------------------------------------------------------------------------
+
+
+class ResourceNotFound(Exception):
+    """No resource matched the given reference."""
+
+    def __init__(self, kind: str, ref: str) -> None:
+        super().__init__(f"No {kind} matching '{ref}'.")
+        self.kind = kind
+        self.ref = ref
+
+
+class AmbiguousResource(Exception):
+    """A name matched more than one resource — the caller must pick by id.
+
+    `matches` is a list of {id, name, hint} dicts for display.
+    """
+
+    def __init__(self, kind: str, ref: str, matches: list[dict]) -> None:
+        super().__init__(f"Multiple {kind}s match '{ref}'.")
+        self.kind = kind
+        self.ref = ref
+        self.matches = matches
+
+
+def _match(items: list[dict], ref: str, *, id_key: str = "id", name_key: str = "name") -> list[dict]:
+    """Find items by EXACT id first (fast, unambiguous), else case-insensitive name.
+
+    Returns every name match so the caller can detect ambiguity (len > 1).
+    """
+    for it in items:                                  # exact id wins outright
+        if str(it.get(id_key)) == ref:
+            return [it]
+    ref_l = ref.strip().lower()
+    return [it for it in items if str(it.get(name_key) or "").lower() == ref_l]
+
+
+def resolve_workflow(client: ApiClient, ref: str) -> dict:
+    """Resolve a workflow name-or-id and return its FULL detail (incl. nodes/edges).
+
+    The list endpoint strips the graph; only the detail endpoint returns it.
+    """
+    items = _as_list(client.get("/api/workflows/"))
+    hits = _match(items, ref)
+    if not hits:
+        raise ResourceNotFound("workflow", ref)
+    if len(hits) > 1:
+        raise AmbiguousResource("workflow", ref, [
+            {"id": w.get("id"), "name": w.get("name") or "(unnamed)",
+             "hint": f"modified {relative_time(w.get('modified_at'))}"}
+            for w in hits
+        ])
+    return client.get(f"/api/workflows/{hits[0]['id']}/")
+
+
+def get_workflow_detail(client: ApiClient, workflow_id) -> dict:
+    """Fetch a workflow's full detail (nodes + edges) by id, skipping name resolution."""
+    return client.get(f"/api/workflows/{workflow_id}/")
+
+
+def create_workflow(client: ApiClient, payload: dict) -> dict:
+    """POST a new workflow; returns the created record (with its new id)."""
+    return client.post("/api/workflows/", json=payload)
+
+
+def update_workflow(client: ApiClient, workflow_id, payload: dict) -> dict:
+    """PUT a full workflow update (own workflows only); returns the updated record."""
+    return client.put(f"/api/workflows/{workflow_id}/", json=payload)
+
+
+def rename_workflow(client: ApiClient, workflow_id, new_name: str) -> dict:
+    """Rename a workflow via a partial PATCH (leaves nodes/edges untouched)."""
+    return client.patch(f"/api/workflows/{workflow_id}/", json={"name": new_name})
+
+
+def pick_script(items: list[dict], ref: str) -> dict:
+    """Match a script by id or name in an already-fetched list (no API call)."""
+    hits = _match(items, ref)
+    if not hits:
+        raise ResourceNotFound("script", ref)
+    if len(hits) > 1:
+        raise AmbiguousResource("script", ref, [
+            {"id": s.get("id"), "name": s.get("name") or "(unnamed)",
+             "hint": f"v{s.get('version')} · updated {relative_time(s.get('updated_at'))}"}
+            for s in hits
+        ])
+    return hits[0]
+
+
+def resolve_script(client: ApiClient, ref: str) -> dict:
+    """Resolve a script name-or-id and return its metadata record (no code body).
+
+    Script ids are ints (unlike workflows' UUIDs); the code lives in a separate
+    content endpoint — see `get_script_content`.
+    """
+    hit = pick_script(_as_list(client.get("/api/scripts/")), ref)
+    return client.get(f"/api/scripts/{hit['id']}/")
+
+
+def get_script_content(client: ApiClient, script_id) -> dict:
+    """Fetch a script's raw code: {id, name, content, content_type, version}."""
+    return client.get(f"/api/scripts/{script_id}/content/")
+
+
+def rename_script(client: ApiClient, script_id, new_name: str) -> dict:
+    """Rename a script via its dedicated endpoint. `new_name` is the bare stem (no
+    extension — the server keeps the original one). Returns the updated record."""
+    return client.post(f"/api/scripts/{script_id}/rename/", json={"new_name": new_name})
+
+
+def find_script_by_name(client: ApiClient, name: str) -> dict | None:
+    """Return the script whose `name` (filename incl. extension) matches, else None.
+
+    Scripts are unique per (owner, pathname) and an API key scopes to one owner, so
+    at most one script can match a given filename. Used by `push script` to decide
+    create-vs-update without an upsert endpoint.
+    """
+    name_l = name.strip().lower()
+    for it in _as_list(client.get("/api/scripts/")):
+        if str(it.get("name") or "").lower() == name_l:
+            return it
+    return None
+
+
+def create_script(client: ApiClient, payload: dict) -> dict:
+    """POST a new script ({name, language, content}); returns the created record."""
+    return client.post("/api/scripts/", json=payload)
+
+
+def update_script(client: ApiClient, script_id, content: str) -> dict:
+    """POST new content to an existing script (bumps its version); returns the record."""
+    return client.post(f"/api/scripts/{script_id}/update/", json={"content": content})
+
+
+def run_script_stream(client: ApiClient, payload: dict):
+    """Start a one-shot script run; yields its live (event, data) SSE frames.
+
+    Payload: {script_details: {script_id, script_name, pathname},
+              vault_details: {vault_id, server_id, credential_id}, inputs: {NAME: value}}.
+    The server applies no stored defaults, so `inputs` must carry every variable.
+    """
+    return client.stream("POST", "/api/execution-engine/run/", json=payload)
+
+
+def stop_script_execution(client: ApiClient, execution_id) -> None:
+    """Signal a script execution to terminate (only valid while it is 'running')."""
+    client.post(f"/api/execution-engine/{execution_id}/stop/")
+
+
+def resolve_run(client: ApiClient, ref: str) -> dict:
+    """Resolve a run by full id, or by an id PREFIX (runs have no names).
+
+    A full UUID is fetched directly; a shorter prefix is matched against the
+    recent-runs list (handy for pasting the first few characters).
+    """
+    ref = ref.strip()
+    if len(ref) == 36 and ref.count("-") == 4:          # looks like a full UUID
+        try:
+            return client.get(f"/api/execution-engine/workflows/runs/{ref}/")
+        except ApiError as exc:
+            if exc.status == 404:
+                raise ResourceNotFound("run", ref)
+            raise
+    runs = _as_list(client.get("/api/execution-engine/workflows/runs/"))
+    hits = [r for r in runs if str(r.get("id", "")).startswith(ref)]
+    if not hits:
+        raise ResourceNotFound("run", ref)
+    if len(hits) > 1:
+        raise AmbiguousResource("run", ref, [
+            {"id": r.get("id"), "name": r.get("workflow_name") or "(workflow)",
+             "hint": f"{r.get('status')} · {relative_time(r.get('created_at'))}"}
+            for r in hits
+        ])
+    return client.get(f"/api/execution-engine/workflows/runs/{hits[0]['id']}/")
+
+
+def get_run_nodes(client: ApiClient, run_id) -> list[dict]:
+    """Per-node results for a run, each with signed log URLs + a `logs_expired` flag."""
+    return _as_list(client.get(f"/api/execution-engine/workflows/runs/{run_id}/nodes/"))
+
+
+def get_workflow_run(client: ApiClient, run_id) -> dict:
+    """A run's record: status, error_message, started_at/finished_at, inputs (masked)."""
+    return client.get(f"/api/execution-engine/workflows/runs/{run_id}/")
+
+
+def trigger_workflow_run(client: ApiClient, workflow_id, payload: dict) -> dict:
+    """Queue an on-demand (manual) run; returns {workflow_run_id, status}.
+
+    Payload: {inputs: {param_id: value}, send_email, user_email}. Parameters left out
+    of `inputs` keep the value saved in the workflow. The server validates the graph
+    and bindings first (400 with a message if they're incomplete).
+    """
+    return client.post(f"/api/execution-engine/workflows/{workflow_id}/run/", json=payload)
+
+
+def stream_workflow_run(client: ApiClient, run_id):
+    """Yield a run's live (event, data) SSE frames.
+
+    Live only: events published before this connects are not replayed, and an
+    already-finished run yields just its final status + done.
+    """
+    return client.stream("GET", f"/api/execution-engine/workflows/runs/{run_id}/stream/")
+
+
+def cancel_workflow_run(client: ApiClient, run_id) -> None:
+    """Cancel a queued/running run. The server publishes no 'done' event for it."""
+    client.post(f"/api/execution-engine/workflows/runs/{run_id}/cancel/")
+
+
+def fetch_log_text(url: str) -> str:
+    """Download a signed GCS log URL directly (no API key / envelope) and return text.
+
+    The `*_signed_url` fields point straight at Google Cloud Storage, so this is a
+    plain GET — not routed through ApiClient.
+    """
+    if not url:
+        return ""
+    # Never put `exc` in the message: httpx embeds the full signed URL in it, and that
+    # URL is a working credential for the log until it expires.
+    try:
+        with client_waiting("GET"):
+            resp = httpx.get(url, timeout=30.0)
+    except httpx.HTTPError:
+        raise ApiError("couldn't download log (network error)")
+    if resp.status_code >= 400:
+        raise ApiError(f"couldn't download log (HTTP {resp.status_code})")
+    return resp.text
+
+
+def resolve_trigger(client: ApiClient, ref: str) -> tuple[str, dict]:
+    """Resolve a trigger by id or workflow name; return (kind, detail).
+
+    `kind` is "http" or "schedule". Detail comes from the richer per-node endpoint
+    (adds rotated_at / last_run_id), merged with the aggregate item so we keep
+    workflow_name. Only ever exposes `secret_last4`, never a full secret.
+    """
+    data = client.get("/api/triggers/") or {}
+    items = [{**t, "_kind": "http"} for t in data.get("http_triggers", [])]
+    items += [{**t, "_kind": "schedule"} for t in data.get("schedule_triggers", [])]
+
+    hits = _match(items, ref, name_key="workflow_name")
+    if not hits:
+        raise ResourceNotFound("trigger", ref)
+    if len(hits) > 1:
+        raise AmbiguousResource("trigger", ref, [
+            {"id": t.get("id"), "name": f"{t.get('workflow_name')} ({t['_kind']})",
+             "hint": f"node {t.get('node_id')}"}
+            for t in hits
+        ])
+
+    t = hits[0]
+    kind = t["_kind"]
+    path = f"/api/workflows/{t.get('workflow_id')}/triggers/{kind}/{t.get('node_id')}/"
+    try:
+        detail = client.get(path) or {}
+    except ApiError:
+        detail = {}                                     # fall back to the aggregate item
+    return kind, {**t, **detail}                        # detail wins; keeps workflow_name
+
+
+# ---------------------------------------------------------------------------
+# Trigger writes. Triggers bind to a workflow's trigger NODE by node id; HTTP
+# create/regenerate return the plaintext secret ONCE. Enable/disable is a global
+# PATCH keyed by the trigger's UUID (not by node).
+# ---------------------------------------------------------------------------
+
+
+def find_trigger_nodes(workflow: dict, dtype: str) -> list[dict]:
+    """Trigger nodes (outer type 'trigger') whose data.type == dtype ('http'/'schedule')."""
+    out = []
+    for n in workflow.get("nodes") or []:
+        if n.get("type") == "trigger":
+            data = n.get("data") if isinstance(n.get("data"), dict) else {}
+            if data.get("type") == dtype:
+                out.append(n)
+    return out
+
+
+def create_http_trigger(client: ApiClient, workflow_id, node_id: str) -> dict:
+    """Create-or-ROTATE an HTTP trigger for a node. Returns data incl. the plaintext
+    `secret` (shown once) and `trigger_url`. Re-running invalidates the old secret."""
+    return client.post(f"/api/workflows/{workflow_id}/triggers/http/", json={"node_id": node_id})
+
+
+def get_http_trigger(client: ApiClient, workflow_id, node_id: str) -> dict:
+    """Fetch an HTTP trigger's detail (no secret, only secret_last4). 404 if none."""
+    return client.get(f"/api/workflows/{workflow_id}/triggers/http/{node_id}/")
+
+
+def regenerate_http_trigger(client: ApiClient, workflow_id, node_id: str) -> dict:
+    """Rotate an HTTP trigger's secret (same URL). Returns the new plaintext `secret` once."""
+    return client.post(f"/api/workflows/{workflow_id}/triggers/http/{node_id}/regenerate/")
+
+
+def upsert_schedule_trigger(client: ApiClient, workflow_id, node_id: str, cron: str) -> dict:
+    """Create-or-update a schedule trigger (5-field cron, UTC). Returns its record."""
+    return client.post(
+        f"/api/workflows/{workflow_id}/triggers/schedule/",
+        json={"node_id": node_id, "cron_expression": cron},
+    )
+
+
+def http_trigger_path(trigger: dict) -> str | None:
+    """The webhook's path (/api/execution-engine/triggers/http/<token>/) from a
+    trigger record's `trigger_url`. The URL's host is whatever the server saw, so
+    callers join this path onto their own base URL instead."""
+    url = str(trigger.get("trigger_url") or "")
+    marker = "/api/execution-engine/triggers/http/"
+    if marker not in url:
+        return None
+    token = url.split(marker, 1)[1].strip("/").split("/")[0]
+    return f"{marker}{token}/" if token else None
+
+
+def fire_http_trigger(client: ApiClient, path: str, secret: str, idempotency_key: str,
+                      inputs: dict) -> dict:
+    """Call an HTTP trigger exactly as an outside caller would: no API key, just the
+    trigger secret + an Idempotency-Key. Returns {workflow_run_id, status,
+    idempotent, polling_url}; a reused key returns the original run (idempotent=True).
+    """
+    caller = ApiClient(client.base_url, None)
+    return caller.post(path, json={"inputs": inputs}, headers={
+        "X-Trigger-Secret": secret,
+        "Idempotency-Key": idempotency_key,
+    })
+
+
+def http_trigger_poll_path(url: str) -> tuple[str, str] | None:
+    """(path, run_id) from a polling URL (…/triggers/http/<token>/runs/<run_id>/), or
+    None. As with firing, only the path is used — the host is whatever Django saw."""
+    marker = "/api/execution-engine/triggers/http/"
+    if marker not in url:
+        return None
+    parts = url.split(marker, 1)[1].split("?")[0].strip("/").split("/")
+    if len(parts) < 3 or parts[1] != "runs" or not parts[0] or not parts[2]:
+        return None
+    return f"{marker}{parts[0]}/runs/{parts[2]}/", parts[2]
+
+
+def resolve_http_trigger_run(client: ApiClient, ref: str, run: str | None = None) -> dict:
+    """One owner-only call: a workflow name, trigger id or run id (or the start of one)
+    → the HTTP trigger run to poll. `ref` alone means: a run → the trigger that started
+    it; a trigger/workflow → its latest webhook run. With `run`, ref names the trigger.
+
+    Returns {trigger, run, polling_path, workflow (graph shape only)}. Raises
+    AmbiguousResource when a name or prefix matches several; other failures raise
+    ApiError whose `errors["code"]` says why (not_webhook_run, no_runs_yet, …).
+    """
+    params = {"ref": ref, **({"run": run} if run else {})}
+    try:
+        return client.get("/api/triggers/http/resolve/", params=params)
+    except ApiError as exc:
+        errors = exc.errors if isinstance(exc.errors, dict) else {}
+        if exc.status == 409 and errors.get("matches"):
+            raise AmbiguousResource(errors.get("kind") or "match", run or ref, errors["matches"])
+        raise
+
+
+def poll_http_trigger_run(client: ApiClient, path: str, secret: str) -> dict:
+    """Read a run through the trigger's public polling endpoint, as a webhook caller
+    would (trigger secret only, no API key). Returns {workflow_run_id, status,
+    error_message, started_at, finished_at, nodes: [...]} — no logs."""
+    return ApiClient(client.base_url, None).get(path, headers={"X-Trigger-Secret": secret})
+
+
+def update_workflow_nodes(client: ApiClient, workflow_id, nodes: list) -> dict:
+    """Replace a workflow's nodes via a partial PATCH (edges and name untouched)."""
+    return client.patch(f"/api/workflows/{workflow_id}/", json={"nodes": nodes})
+
+
+def get_schedule_trigger(client: ApiClient, workflow_id, node_id: str) -> dict:
+    """A schedule's detail: cron, next_runs (the scheduler's own next fire times),
+    last_run_id / last_run_status, last_error."""
+    return client.get(f"/api/workflows/{workflow_id}/triggers/schedule/{node_id}/")
+
+
+def fire_schedule_now(client: ApiClient, workflow_id, node_id: str) -> dict:
+    """Fire a schedule now through the scheduler's own path (overlap rule, no inputs,
+    recorded as a scheduled run). Returns {workflow_run_id, status}; 409 if skipped."""
+    return client.post(f"/api/workflows/{workflow_id}/triggers/schedule/{node_id}/fire/")
+
+
+def set_trigger_active(client: ApiClient, kind: str, trigger_id, is_active: bool) -> dict:
+    """Enable/disable a trigger via the global endpoint. `kind` is 'http' or 'schedule'."""
+    return client.patch(f"/api/triggers/{kind}/{trigger_id}/", json={"is_active": is_active})
+
+
+def delete_trigger(client: ApiClient, workflow_id, kind: str, node_id: str) -> None:
+    """Delete a trigger by its workflow + node. `kind` is 'http' or 'schedule'."""
+    client.delete(f"/api/workflows/{workflow_id}/triggers/{kind}/{node_id}/")
+
+
+def _vault_name(client: ApiClient, vault_id) -> str | None:
+    """Look up a vault's display name from its id (best-effort; None on failure).
+
+    Credentials/servers only carry the vault's UUID; we resolve the friendly name
+    with one targeted call so callers can show it instead of the raw id.
+    """
+    if not vault_id:
+        return None
+    try:
+        return (client.get(f"/api/vault/vaults/{vault_id}/") or {}).get("name")
+    except ApiError:
+        return None
+
+
+def _vault_name_map(client: ApiClient) -> dict:
+    """Map every vault id -> name in one call. Used to label ambiguous matches by vault."""
+    return {str(v.get("id")): v.get("name") for v in _as_list(client.get("/api/vault/vaults/"))}
+
+
+def _dotted(*parts) -> str:
+    """Join non-empty hint parts with ' · ' (e.g. 'ssh · Prod')."""
+    return " · ".join(str(p) for p in parts if p)
+
+
+def resolve_credential(client: ApiClient, ref: str) -> dict:
+    """Resolve a vault credential (key) by id or name; returns the MASKED record.
+
+    Secret fields are write-only server-side, so this never contains plaintext.
+    Use `reveal_credential` (explicitly) to fetch the actual secret values.
+    Enriched with `vault_name` for display.
+    """
+    items = _as_list(client.get("/api/vault/credentials/"))
+    hits = _match(items, ref)
+    if not hits:
+        raise ResourceNotFound("key", ref)
+    if len(hits) > 1:
+        vmap = _vault_name_map(client)
+        raise AmbiguousResource("key", ref, [
+            {"id": c.get("id"), "name": c.get("name") or "(unnamed)",
+             "hint": _dotted(c.get("credential_type"), vmap.get(str(c.get("vault"))))}
+            for c in hits
+        ])
+    cred = client.get(f"/api/vault/credentials/{hits[0]['id']}/")
+    cred["vault_name"] = _vault_name(client, cred.get("vault"))
+    return cred
+
+
+def find_credential_in_vault(vault: dict, ref: str) -> dict | None:
+    """Match a credential by id or name within a vault's nested `credentials` list.
+
+    A vault detail record carries its credentials inline, so this needs no API call.
+    Used to enforce (client-side, with a clear error) that a server's attached key
+    lives in the same vault. Credential names are unique per vault, so no ambiguity.
+    """
+    creds = vault.get("credentials") or []
+    for c in creds:                                   # exact id first
+        if str(c.get("id")) == ref:
+            return c
+    ref_l = ref.strip().lower()
+    for c in creds:
+        if str(c.get("name") or "").lower() == ref_l:
+            return c
+    return None
+
+
+def find_server_in_vault(vault: dict, ref: str) -> dict | None:
+    """Match a server by id or name within a vault's nested `servers` list.
+
+    Server names are unique per vault, so scoping a lookup to one vault is always
+    unambiguous — used by `update server --vault` to disambiguate a shared name.
+    """
+    servers = vault.get("servers") or []
+    for s in servers:                                 # exact id first
+        if str(s.get("id")) == ref:
+            return s
+    ref_l = ref.strip().lower()
+    for s in servers:
+        if str(s.get("name") or "").lower() == ref_l:
+            return s
+    return None
+
+
+def reveal_credential(client: ApiClient, credential_id) -> dict:
+    """Fetch a credential's PLAINTEXT secrets. Only call on explicit user request.
+
+    This hits the single endpoint that decrypts secrets; the caller must confirm
+    with the user first.
+    """
+    return client.get(f"/api/vault/credentials/{credential_id}/reveal/")
+
+
+def create_credential(client: ApiClient, payload: dict) -> dict:
+    """POST a new credential; returns the MASKED record (secrets are write-only).
+
+    Payload: {vault, name, credential_type} plus the secret fields for that type.
+    Secrets travel as plaintext in the body and are encrypted server-side (TLS on the
+    wire). `vault` is a UUID and must be owned by the caller.
+    """
+    return client.post("/api/vault/credentials/", json=payload)
+
+
+def update_credential(client: ApiClient, credential_id, payload: dict) -> dict:
+    """Update a credential (the server treats PUT as partial); returns the masked record.
+
+    Send only the fields being changed; omitted secrets are left untouched. Secrets
+    travel as plaintext in the body (encrypted server-side).
+    """
+    return client.put(f"/api/vault/credentials/{credential_id}/", json=payload)
+
+
+def resolve_server(client: ApiClient, ref: str) -> dict:
+    """Resolve a vault server by id or name; returns its detail (enriched).
+
+    Adds `vault_name`; the linked credential's name is already in
+    `credential_details` (masked — no secrets).
+    """
+    items = _as_list(client.get("/api/vault/servers/"))
+    try:
+        hit = pick_server(items, ref, {})
+    except AmbiguousResource:
+        # Only fetch vault names when they're needed to tell the matches apart.
+        hit = pick_server(items, ref, _vault_name_map(client))
+    server = client.get(f"/api/vault/servers/{hit['id']}/")
+    server["vault_name"] = _vault_name(client, server.get("vault"))
+    return server
+
+
+def pick_server(items: list[dict], ref: str, vault_names: dict) -> dict:
+    """Match a server by id or name in an already-fetched list (no API call).
+
+    `vault_names` maps vault id -> name, used to label matches that share a name.
+    """
+    hits = _match(items, ref)
+    if not hits:
+        raise ResourceNotFound("server", ref)
+    if len(hits) > 1:
+        raise AmbiguousResource("server", ref, [
+            {"id": s.get("id"), "name": s.get("name") or "(unnamed)",
+             "hint": _dotted(s.get("host"), vault_names.get(str(s.get("vault"))))}
+            for s in hits
+        ])
+    return hits[0]
+
+
+def create_server(client: ApiClient, payload: dict) -> dict:
+    """POST a new vault server; returns the created record.
+
+    Payload: {vault, name, host, connection_method, port} plus optional {credential}.
+    `vault` and `credential` are UUID ids; the credential must belong to that vault.
+    """
+    return client.post("/api/vault/servers/", json=payload)
+
+
+def update_server(client: ApiClient, server_id, payload: dict) -> dict:
+    """Update a server (the server treats PUT as partial, so send only changed fields).
+
+    Any of name/host/port/connection_method/credential. Set credential to None to
+    unlink the current key; a credential id must belong to the server's vault.
+    """
+    return client.put(f"/api/vault/servers/{server_id}/", json=payload)
+
+
+def resolve_vault(client: ApiClient, ref: str) -> dict:
+    """Resolve a vault by id or name; returns its detail (nested creds + servers)."""
+    hit = pick_vault(_as_list(client.get("/api/vault/vaults/")), ref)
+    return client.get(f"/api/vault/vaults/{hit['id']}/")
+
+
+def pick_vault(items: list[dict], ref: str) -> dict:
+    """Match a vault by id or name in an already-fetched list (no API call).
+
+    List items already carry the nested servers and credentials.
+    """
+    hits = _match(items, ref)
+    if not hits:
+        raise ResourceNotFound("vault", ref)
+    if len(hits) > 1:
+        raise AmbiguousResource("vault", ref, [
+            {"id": v.get("id"), "name": v.get("name") or "(unnamed)",
+             "hint": f"modified {relative_time(v.get('modified_at'))}"}
+            for v in hits
+        ])
+    return hits[0]
+
+
+def find_vault_by_name(client: ApiClient, name: str) -> dict | None:
+    """Return the vault whose name matches (case-insensitive), or None.
+
+    Vault names are unique per owner and the API key scopes to one owner, so at most
+    one matches. Used by `create/update vault` to check for a name clash first, since
+    the server's duplicate-name error shape isn't guaranteed.
+    """
+    name_l = name.strip().lower()
+    for it in _as_list(client.get("/api/vault/vaults/")):
+        if str(it.get("name") or "").lower() == name_l:
+            return it
+    return None
+
+
+def create_vault(client: ApiClient, payload: dict) -> dict:
+    """POST a new vault ({name, description}); returns the created record."""
+    return client.post("/api/vault/vaults/", json=payload)
+
+
+def update_vault(client: ApiClient, vault_id, payload: dict) -> dict:
+    """Update a vault (the server treats PUT as partial, so send only changed fields)."""
+    return client.put(f"/api/vault/vaults/{vault_id}/", json=payload)
+
+
+# ---------------------------------------------------------------------------
+# Delete helpers. All are owner-scoped server-side (404 if not yours). Deleting a
+# vault CASCADES to its servers and credentials.
+# ---------------------------------------------------------------------------
+
+
+def delete_workflow(client: ApiClient, workflow_id) -> None:
+    client.delete(f"/api/workflows/{workflow_id}/")
+
+
+def delete_script(client: ApiClient, script_id) -> None:
+    client.delete(f"/api/scripts/{script_id}/")
+
+
+def delete_vault(client: ApiClient, vault_id) -> None:
+    """Delete a vault — CASCADES to every server and credential inside it."""
+    client.delete(f"/api/vault/vaults/{vault_id}/")
+
+
+def delete_server(client: ApiClient, server_id) -> None:
+    client.delete(f"/api/vault/servers/{server_id}/")
+
+
+def delete_credential(client: ApiClient, credential_id) -> None:
+    client.delete(f"/api/vault/credentials/{credential_id}/")
+
+
+# ---------------------------------------------------------------------------
+# Full-list helpers for the `sagex list` commands.
+# ---------------------------------------------------------------------------
+
+
+def list_workflows_full(client: ApiClient) -> list[dict]:
+    """All workflows — id, name, modified_at."""
+    return _as_list(client.get("/api/workflows/"))
+
+
+def list_scripts_full(client: ApiClient) -> list[dict]:
+    """All scripts — id, name, content_type, version."""
+    return _as_list(client.get("/api/scripts/"))
+
+
+def list_runs_full(client: ApiClient, limit: int | None = 20) -> list[dict]:
+    """Recent runs sorted newest-first. `limit=None` returns the full history."""
+    runs = _as_list(client.get("/api/execution-engine/workflows/runs/"))
+    runs.sort(key=lambda r: r.get("created_at") or "", reverse=True)
+    return runs if limit is None else runs[:limit]
+
+
+def list_triggers_full(client: ApiClient) -> list[dict]:
+    """All triggers as a flat list; each dict has a 'kind' key ('http' or 'schedule')."""
+    data = client.get("/api/triggers/") or {}
+    out: list[dict] = []
+    for t in data.get("schedule_triggers", []):
+        out.append({**t, "kind": "schedule"})
+    for t in data.get("http_triggers", []):
+        out.append({**t, "kind": "http"})
+    return out
+
+
+def list_credentials_full(client: ApiClient) -> list[dict]:
+    """All credentials enriched with vault_name (2 API calls: creds + vaults list)."""
+    creds = _as_list(client.get("/api/vault/credentials/"))
+    vault_names = {
+        str(v.get("id")): v.get("name")
+        for v in _as_list(client.get("/api/vault/vaults/"))
+    }
+    for c in creds:
+        c["vault_name"] = vault_names.get(str(c.get("vault") or ""))
+    return creds
+
+
+def list_servers_full(client: ApiClient) -> list[dict]:
+    """All servers — name, host, port, connection_method."""
+    return _as_list(client.get("/api/vault/servers/"))
+
+
+def list_vaults_full(client: ApiClient) -> list[dict]:
+    """All vaults (nested credentials + servers included by the serializer)."""
+    return _as_list(client.get("/api/vault/vaults/"))