procesio-cli 0.1.1__py3-none-any.whl

procesio_cli/tools/procesio/layout/report.py

@@ -0,0 +1,187 @@
+"""Engine-agnostic layout verification: measure the readability of a laid-out flow.
+
+Works on ANY flow's stored positions — whichever engine (legacy `engine` or `elk_engine`)
+produced them — because it reads the OUTPUT geometry, not the algorithm. Pure + offline
+(no network, no rendering).
+
+`build_report(obj, flow_id)` returns:
+  { ok, hard_issues, metrics, containers } where
+  - hard_issues  = overlaps + container children rendered outside their frame (real defects)
+  - metrics      = crossings, edge lengths, back-edges, bbox/aspect, vertical rows, fill
+  - containers   = per For-Each: frame size, inner padding L/T/R/B, inner spacing, warnings
+"""
+from __future__ import annotations
+
+# readability thresholds (px) — a long edge and a min sane For-Each frame
+LONG_EDGE_PX = 600
+MIN_FOREACH_W = 320
+MIN_FOREACH_H = 200
+
+
+def _g(d, *ks, default=None):
+    if not isinstance(d, dict):
+        return default
+    low = {str(k).lower(): v for k, v in d.items()}
+    for k in ks:
+        if k.lower() in low:
+            return low[k.lower()]
+    return default
+
+
+def _select_flow(obj: dict, flow_id: str | None) -> dict:
+    flows = _g(obj, "Flows", "flows")
+    if flows is None:
+        return obj
+    if flow_id:
+        f = next((x for x in flows if _g(x, "Id", "id") == flow_id), None)
+        if f is None:
+            raise ValueError(f"flow_id {flow_id} not found")
+        return f
+    if len(flows) == 1:
+        return flows[0]
+    raise ValueError(f"bundle has {len(flows)} flows; pass flow_id")
+
+
+def _extract(flow: dict) -> dict:
+    """Absolute geometry: node centres, edge attach-points (area = frame top-left), edges."""
+    acts = _g(flow, "actions", "Actions", default=[]) or []
+    nodes = {}
+    for a in acts:
+        cd = _g(a, "customData", "CustomData", default={}) or {}
+        pos = _g(cd, "position", default={}) or {}
+        asz = _g(cd, "areaSize", default={}) or {}
+        is_area = _g(cd, "type") == "area"
+        nodes[_g(a, "id", "Id")] = {
+            "x": float(_g(pos, "x", default=0) or 0), "y": float(_g(pos, "y", default=0) or 0),
+            "parent": _g(a, "parentId", "ParentId"), "is_area": is_area,
+            "w": float(_g(asz, "width", default=48) or 48) if is_area else 48.0,
+            "h": float(_g(asz, "height", default=48) or 48) if is_area else 48.0,
+            "name": _g(cd, "name") or _g(a, "actionTemplateName", "ActionTemplateName") or _g(a, "id", "Id"),
+        }
+    cen, att = {}, {}
+    for aid, n in nodes.items():
+        par = n["parent"]
+        if n["is_area"]:
+            base_x = n["x"] if par not in nodes else nodes[par]["x"] + n["x"]
+            base_y = n["y"] if par not in nodes else nodes[par]["y"] + n["y"]
+            cen[aid] = {"x": base_x + n["w"] / 2, "y": base_y + n["h"] / 2}
+            att[aid] = {"x": base_x, "y": base_y}
+        elif par in nodes and nodes[par]["is_area"]:
+            cen[aid] = {"x": nodes[par]["x"] + n["x"], "y": nodes[par]["y"] + n["y"]}
+            att[aid] = cen[aid]
+        else:
+            cen[aid] = {"x": n["x"], "y": n["y"]}
+            att[aid] = cen[aid]
+    edges = []
+    for a in acts:
+        s = _g(a, "id", "Id")
+        for p in _g(a, "ports", "Ports", default=[]) or []:
+            d = _g(p, "destinationId", "DestinationId")
+            src = _g(p, "sourceId", "SourceId") or s
+            t = int(_g(p, "type", "Type", default=0) or 0)
+            if src in nodes and d in nodes and src != d:
+                edges.append((src, d, t))
+    return {"nodes": nodes, "cen": cen, "att": att, "edges": edges}
+
+
+def _seg(a, b, c, d) -> bool:
+    def o(p, q, r):
+        return (q["y"] - p["y"]) * (r["x"] - q["x"]) - (q["x"] - p["x"]) * (r["y"] - q["y"])
+    return (o(a, b, c) > 0) != (o(a, b, d) > 0) and (o(c, d, a) > 0) != (o(c, d, b) > 0)
+
+
+def _hard_issues(geo: dict) -> list[dict]:
+    """Overlaps between leaf nodes + container children rendered outside their frame."""
+    nodes, cen = geo["nodes"], geo["cen"]
+    issues = []
+    for aid, n in nodes.items():
+        par = n["parent"]
+        if par in nodes and nodes[par]["is_area"]:
+            pp, fx, fy = nodes[par], nodes[par]["x"], nodes[par]["y"]
+            cx, cy = cen[aid]["x"], cen[aid]["y"]
+            if not (fx - 1 <= cx - 24 and cx + 24 <= fx + pp["w"] + 1
+                    and fy - 1 <= cy - 24 and cy + 24 <= fy + pp["h"] + 1):
+                issues.append({"type": "child_outside_frame", "child": n["name"], "area": pp["name"]})
+    leaves = [aid for aid, n in nodes.items() if not n["is_area"]]
+    for i in range(len(leaves)):
+        a = cen[leaves[i]]
+        for j in range(i + 1, len(leaves)):
+            b = cen[leaves[j]]
+            if abs(a["x"] - b["x"]) < 46 and abs(a["y"] - b["y"]) < 46:
+                issues.append({"type": "overlap",
+                               "a": nodes[leaves[i]]["name"], "b": nodes[leaves[j]]["name"]})
+    return issues
+
+
+def _metrics(geo: dict) -> dict:
+    att, edges, nodes, cen = geo["att"], geo["edges"], geo["nodes"], geo["cen"]
+    cx = [c["x"] for c in cen.values()] or [0]
+    cy = [c["y"] for c in cen.values()] or [0]
+    W, H = max(cx) - min(cx) + 68, max(cy) - min(cy) + 68
+    E = [(att[s], att[d]) for s, d, _ in edges]
+    cr = 0
+    for i in range(len(E)):
+        s1, d1, _ = edges[i]
+        for j in range(i + 1, len(E)):
+            s2, d2, _ = edges[j]
+            if len({s1, d1, s2, d2}) < 4:
+                continue
+            if _seg(E[i][0], E[i][1], E[j][0], E[j][1]):
+                cr += 1
+    lens = [abs(att[s]["x"] - att[d]["x"]) + abs(att[s]["y"] - att[d]["y"]) for s, d, _ in edges]
+    back = sum(1 for s, d, _ in edges if att[d]["x"] < att[s]["x"] - 24)
+    rows = len({round(c["y"] / 30) for c in cen.values()})
+    fill = (len(nodes) * 68 * 68) / (W * H) if W * H else 0
+    return {
+        "nodes": len(nodes), "edges": len(edges), "crossings": cr, "back_edges": back,
+        "max_edge_px": round(max(lens)) if lens else 0,
+        "mean_edge_px": round(sum(lens) / len(lens)) if lens else 0,
+        "long_edges": sum(1 for L in lens if L > LONG_EDGE_PX),
+        "width": round(W), "height": round(H),
+        "aspect_w_to_h": round(W / H, 2) if H else 0,
+        "vertical_rows": rows, "fill_pct": round(fill * 100, 1),
+    }
+
+
+def _containers(geo: dict) -> list[dict]:
+    nodes = geo["nodes"]
+    out = []
+    for aid, n in nodes.items():
+        if not n["is_area"]:
+            continue
+        kids = [k for k in nodes.values() if k["parent"] == aid]
+        c = {"name": n["name"], "width": round(n["w"]), "height": round(n["h"]),
+             "children": len(kids), "warnings": []}
+        if kids:
+            cxs = [k["x"] for k in kids]
+            cys = [k["y"] for k in kids]
+            pad = {"l": round(min(cxs) - 24), "t": round(min(cys) - 24),
+                   "r": round(n["w"] - (max(cxs) + 24)), "b": round(n["h"] - (max(cys) + 24))}
+            c["padding"] = pad
+            xs = sorted(cxs)
+            c["inner_h_spacing"] = [round(xs[i + 1] - xs[i]) for i in range(len(xs) - 1)]
+            for side, v in pad.items():
+                if v < 0:
+                    c["warnings"].append(f"negative {side} padding ({v}) — child overflows frame")
+        if n["w"] < MIN_FOREACH_W:
+            c["warnings"].append(f"width {round(n['w'])} < min {MIN_FOREACH_W}")
+        if n["h"] < MIN_FOREACH_H:
+            c["warnings"].append(f"height {round(n['h'])} < min {MIN_FOREACH_H}")
+        out.append(c)
+    return out
+
+
+def build_report(obj: dict, flow_id: str | None = None) -> dict:
+    flow = _select_flow(obj, flow_id)
+    geo = _extract(flow)
+    hard = _hard_issues(geo)
+    containers = _containers(geo)
+    container_warnings = [w for c in containers for w in c["warnings"]]
+    return {
+        "ok": not hard and not container_warnings,
+        "flow_id": _g(flow, "Id", "id"),
+        "hard_issue_count": len(hard),
+        "hard_issues": hard[:40],
+        "metrics": _metrics(geo),
+        "containers": containers,
+    }

procesio_cli/tools/procesio/main.py

@@ -0,0 +1,179 @@
+"""procesio tool entrypoint - action dispatch over the PROCESIO Web API.
+
+Dual auth (API key OR username/password -> Bearer) with a multi-credential
+profile store; a generic `request` action covering every documented endpoint;
+curated read/run actions for the common surface.
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+TOOL_ROOT = Path(__file__).resolve().parent
+FRAMEWORK_ROOT = TOOL_ROOT.parents[1]
+# .venv layout is per-OS: Scripts/python.exe on Windows, bin/python everywhere else.
+_VENV_PY = (FRAMEWORK_ROOT / ".venv" / "Scripts" / "python.exe" if sys.platform == "win32"
+            else FRAMEWORK_ROOT / ".venv" / "bin" / "python")
+if _VENV_PY.exists() and Path(sys.executable).resolve() != _VENV_PY.resolve():
+    import subprocess
+    sys.exit(subprocess.run([str(_VENV_PY), __file__, *sys.argv[1:]]).returncode)
+
+import argparse  # noqa: E402
+
+if str(FRAMEWORK_ROOT) not in sys.path:
+    sys.path.insert(0, str(FRAMEWORK_ROOT))
+
+from tools._lib.io import emit, fail  # noqa: E402
+from tools.procesio import errors  # noqa: E402
+from tools.procesio.actiondef import ActionDef  # noqa: E402
+from tools.procesio.client import ProcesioClient  # noqa: E402
+
+
+class _Parser(argparse.ArgumentParser):
+    def error(self, message: str):
+        raise errors.UsageError(message)
+
+
+# Known footguns on raw/autogenerated endpoints: the call SUCCEEDS but leaves the
+# workspace in a state the caller rarely intends. Attached to the emitted JSON as
+# `warning` so it is visible without changing the action's contract. One line per
+# action; keep the text actionable.
+ADVISORIES = {
+    "post-projects-by-id-instances-publish": (
+        "publish CREATES an instance in status 1 ('starting') with 0 action runs and "
+        "does NOT run it — publish and launch are a pair (run-process does both). A "
+        "WEBHOOK-triggered process needs no publish at all: the webhook launch "
+        "publishes+launches itself. Calling publish 'to activate' just accumulates "
+        "instances stuck at 'starting' (they cannot be stopped via the API — only in "
+        "the UI). Launch it with post-projects-instances-by-id-launch, or use "
+        "run-process, or simply don't publish."
+    ),
+}
+
+
+def _advise(action: str, result):
+    """Attach a known-footgun advisory to a successful result (non-destructive)."""
+    note = ADVISORIES.get(action)
+    if note and isinstance(result, dict):
+        result.setdefault("warning", note)
+    return result
+
+
+def collect_actions() -> dict[str, ActionDef]:
+    from tools.procesio import autogen
+    from tools.procesio.handlers import (
+        auth_actions, catalog, customaction_ops, datastore_ops, datatype_ops,
+        dto_actions, environment_admin, files,
+        flowgraph, form_chains, form_code, form_element, form_events, form_update, formprocess, generic,
+        layout, usageguide,
+        process_layout, process_naming, processes, profile_admin,
+        flowlint, fevalidate, nodeparams, resource_ops, schedules, sqlactions, transport,
+    )
+    # Curated / management actions: ergonomic, hand-written, well-tested.
+    curated: dict[str, ActionDef] = {}
+    curated.update(profile_admin.ACTIONS)
+    # Environment registry: list/add/set/remove/show PROCESIO environments (URLs).
+    curated.update(environment_admin.ACTIONS)
+    curated.update(auth_actions.ACTIONS)
+    curated.update(generic.ACTIONS)
+    curated.update(processes.ACTIONS)
+    # Submit a form the way a browser does (proves the form's own maps carry values).
+    curated.update(formprocess.ACTIONS)
+    curated.update(catalog.ACTIONS)
+    curated.update(transport.ACTIONS)
+    curated.update(schedules.ACTIONS)
+    # Data Store: user-defined dynamic tables — metadata + row CRUD + CSV jobs.
+    curated.update(datastore_ops.ACTIONS)
+    # DTO sub-tools: <component>-create / <component>-edit (deterministic builders).
+    curated.update(dto_actions.ACTIONS)
+    # Full data-model lifecycle: attribute add/edit/delete, get/delete, changeToPublic, clone.
+    curated.update(datatype_ops.ACTIONS)
+    # File ops: download a flow-instance file (Generate-Document output etc.).
+    curated.update(files.ACTIONS)
+    # Custom-action (connector) lifecycle: upload .nupkg / delete / list.
+    curated.update(customaction_ops.ACTIONS)
+    # Offline structural reader: parse a flow/export into a node/edge graph model.
+    curated.update(flowgraph.ACTIONS)
+    curated.update(usageguide.ACTIONS)
+    # Offline deterministic canvas auto-layout (re-lay-out a flow; resource map).
+    curated.update(layout.ACTIONS)
+    # Live process ops that pair with layout: duplicate a process; re-lay-out in place.
+    curated.update(process_layout.ACTIONS)
+    # Bulk-rename a live process's canvas actions (default "Node"/"Call API" labels).
+    curated.update(process_naming.ACTIONS)
+    # CRUD-parity + verification oracles: get/delete/list, validate, credential/action test, import.
+    curated.update(resource_ops.ACTIONS)
+    # In-place read/write of a form's global CSS + JS (Data.code), without the
+    # desired-state rebuild form-edit performs.
+    curated.update(form_code.ACTIONS)
+    # Same surgical shape, for one element's event handlers (RUN_PROCESS wiring).
+    curated.update(form_events.ACTIONS)
+    # Whole ordered chains (JS / MAP / process) of several elements in one save; MAP blocks and
+    # their conditions are built from names, existing events are kept by id.
+    curated.update(form_chains.ACTIONS)
+    # Same surgical shape again, for one element's PLAIN configs — label/required/
+    # regex/visible. Content and per-field rules belong in the DTO, not in the
+    # form-level JS layer where the designer cannot see them.
+    curated.update(form_element.ACTIONS)
+    # Arbitrary safe save: GET a live form, deep-merge a Data patch (and/or override
+    # name/status/state), PUT the accepted DTO — the general form-save form-edit isn't.
+    curated.update(form_update.ACTIONS)
+    # SQL Server action hardening: scan + convert inline <%N%> SQL to parameterized (@param) binding.
+    curated.update(sqlactions.ACTIONS)
+    # Surgical single-parameter edits on a live designer-built flow (endpoint/timeout/SQL/script):
+    # read the parameter surface, patch one literal, regenerate the designer layer, validate, PUT.
+    curated.update(nodeparams.ACTIONS)
+    curated.update(flowlint.ACTIONS)
+    # Front-end (designer-layer) validation: process-fe-validate + the pre-save gate that
+    # auto-runs (FE then BE) before every process-create / process-edit.
+    curated.update(fevalidate.ACTIONS)
+    # Generated actions: full 1:1 coverage of every Web-API endpoint. Curated
+    # names win on the (non-colliding) name space.
+    actions = autogen.build_actions(reserved=set(curated))
+    actions.update(curated)
+    return actions
+
+
+ACTIONS = collect_actions()
+
+
+def dispatch(action: str, argv: list[str], *, client_builder=None) -> dict:
+    if action not in ACTIONS:
+        raise errors.UsageError(
+            f"unknown action: {action}. Known: {', '.join(sorted(ACTIONS))}"
+        )
+    defn = ACTIONS[action]
+    parser = _Parser(prog=f"procesio {action}", description=defn.description)
+    defn.add_args(parser)
+    parsed = parser.parse_args(argv)
+    if defn.needs_client:
+        profile = getattr(parsed, "profile", None)
+        environment = getattr(parsed, "environment", None)
+        builder = client_builder or (
+            lambda prof: ProcesioClient(prof, environment=environment))
+        client = builder(profile)
+        wsid = getattr(parsed, "workspace_id", None)
+        if wsid:
+            client.workspace_id = wsid   # per-call active-workspace override
+        return defn.func(client, parsed)
+    return defn.func(parsed)
+
+
+def main(argv=None) -> None:
+    argv = list(sys.argv[1:] if argv is None else argv)
+    if not argv or argv[0] in ("-h", "--help"):
+        print("Actions:", file=sys.stderr)
+        for name in sorted(ACTIONS):
+            print(f"  {name:<22} {ACTIONS[name].description}", file=sys.stderr)
+        sys.exit(0)
+    action, rest = argv[0], argv[1:]
+    try:
+        result = dispatch(action, rest)
+    except Exception as exc:  # noqa: BLE001
+        code, message, details, exit_code = errors.classify(exc)
+        fail(code, message, details, exit_code)
+    emit(_advise(action, result))
+
+
+if __name__ == "__main__":
+    main()

procesio_cli/tools/procesio/profiles.py

@@ -0,0 +1,193 @@
+"""Multi-credential profile store for PROCESIO.
+
+The user explicitly wants "a system that allows multiple credentials so that I
+can have multiple accounts, multiple api keys, etc." A *profile* is one named
+credential: either an API key (workspace-scoped) or a username/password account
+(full UI access). All profiles live in the OS credential store via
+tools._lib.creds - NEVER on disk.
+
+Credential-store layout (all under target agents-and-tools:procesio:<secret>):
+  credentials        -> JSON index: [{"name","type","workspace"}, ...]   (NO secrets)
+  default-profile    -> the name used when --profile is omitted
+  cred-<name>        -> JSON blob for one profile (CONTAINS secret values)
+  token-<name>       -> JSON cached Bearer token for a userpass profile
+
+A profile blob:
+  apikey:   {"type":"apikey","key":..,"value":..,"workspace_id":<guid?>,
+             "workspace":<label?>,"web_base":<override?>,"auth_base":<override?>}
+  userpass: {"type":"userpass","username":..,"password":..,"realm":<override?>,
+             "client_id":<override?>,"web_base":<override?>,"auth_base":<override?>}
+
+The index lets `list-credentials` enumerate profiles WITHOUT reading any secret
+(keyring can't list keys, so the index is the source of truth for membership).
+"""
+from __future__ import annotations
+
+import json
+
+from tools._lib import creds
+from tools.procesio.errors import AuthError, UsageError
+
+TOOL = "procesio"
+INDEX_SECRET = "credentials"
+DEFAULT_SECRET = "default-profile"
+
+# Fields that must never appear in a non-secret view (list-credentials, logs).
+_SECRET_FIELDS = {"key", "value", "password"}
+
+
+# -- index ------------------------------------------------------------------
+
+def _load_index() -> list[dict]:
+    raw = creds.get_optional(TOOL, INDEX_SECRET)
+    if not raw:
+        return []
+    try:
+        data = json.loads(raw)
+        return data if isinstance(data, list) else []
+    except json.JSONDecodeError:
+        return []
+
+
+def _save_index(index: list[dict]) -> None:
+    creds.set_secret(TOOL, INDEX_SECRET, json.dumps(index, ensure_ascii=False))
+
+
+def _index_meta(blob: dict, name: str) -> dict:
+    meta = {"name": name, "type": blob.get("type")}
+    if blob.get("workspace"):
+        meta["workspace"] = blob["workspace"]
+    return meta
+
+
+# -- profile CRUD -----------------------------------------------------------
+
+def profile_names() -> list[str]:
+    return [e["name"] for e in _load_index() if e.get("name")]
+
+
+def get_profile(name: str) -> dict:
+    raw = creds.get_optional(TOOL, f"cred-{name}")
+    if not raw:
+        raise AuthError(
+            f"no PROCESIO credential profile named '{name}'. "
+            f"Known: {', '.join(profile_names()) or '(none)'}. "
+            f"Add one with: run-tool procesio add-credential ..."
+        )
+    try:
+        blob = json.loads(raw)
+    except json.JSONDecodeError as e:
+        raise AuthError(f"profile '{name}' is corrupted: {e}") from e
+    if not isinstance(blob, dict) or "type" not in blob:
+        raise AuthError(f"profile '{name}' is malformed (no type)")
+    return blob
+
+
+def save_profile(name: str, blob: dict) -> None:
+    if blob.get("type") not in ("apikey", "userpass"):
+        raise UsageError("profile type must be 'apikey' or 'userpass'")
+    creds.set_secret(TOOL, f"cred-{name}", json.dumps(blob, ensure_ascii=False))
+    index = [e for e in _load_index() if e.get("name") != name]
+    index.append(_index_meta(blob, name))
+    index.sort(key=lambda e: e["name"])
+    _save_index(index)
+    if not get_default():
+        set_default(name)
+
+
+def remove_profile(name: str) -> None:
+    if name not in profile_names():
+        raise UsageError(f"no profile named '{name}'")
+    creds.delete(TOOL, f"cred-{name}")
+    creds.delete(TOOL, f"token-{name}")
+    creds.delete(TOOL, f"refresh-{name}")
+    _save_index([e for e in _load_index() if e.get("name") != name])
+    if get_default() == name:
+        remaining = profile_names()
+        if remaining:
+            set_default(remaining[0])
+        else:
+            creds.delete(TOOL, DEFAULT_SECRET)
+
+
+def public_view(blob: dict, name: str) -> dict:
+    """A profile dict safe to return/log: secret fields removed, presence noted."""
+    out = {"name": name}
+    for k, v in blob.items():
+        if k in _SECRET_FIELDS:
+            out[f"has_{k}"] = bool(v)
+        else:
+            out[k] = v
+    out["has_cached_token"] = creds.has_for_report(TOOL, f"token-{name}")
+    return out
+
+
+# -- default ----------------------------------------------------------------
+
+def get_default() -> str | None:
+    return creds.get_optional(TOOL, DEFAULT_SECRET)
+
+
+def set_default(name: str) -> None:
+    if name not in profile_names():
+        raise UsageError(f"cannot default to unknown profile '{name}'")
+    creds.set_secret(TOOL, DEFAULT_SECRET, name)
+
+
+def resolve(name: str | None) -> tuple[str, dict]:
+    """Return (name, blob) for an explicit name, else the default, else - if
+    exactly one profile exists - that one. Raises a clear UsageError otherwise."""
+    if name:
+        return name, get_profile(name)
+    default = get_default()
+    if default:
+        return default, get_profile(default)
+    names = profile_names()
+    if len(names) == 1:
+        return names[0], get_profile(names[0])
+    raise UsageError(
+        "no --profile given and no default set. "
+        f"Profiles: {', '.join(names) or '(none)'}. "
+        "Set one with: run-tool procesio set-default --name <name>"
+    )
+
+
+# -- token cache (userpass) -------------------------------------------------
+
+def get_token_cache(name: str) -> dict | None:
+    raw = creds.get_optional(TOOL, f"token-{name}")
+    if not raw:
+        return None
+    try:
+        return json.loads(raw)
+    except json.JSONDecodeError:
+        return None
+
+
+def set_token_cache(name: str, token: dict) -> None:
+    creds.set_secret(TOOL, f"token-{name}", json.dumps(token, ensure_ascii=False))
+
+
+def clear_token_cache(name: str) -> None:
+    creds.delete(TOOL, f"token-{name}")
+    clear_refresh_cookie(name)
+
+
+# The refresh cookie lives in its OWN entry, not alongside the access cookie.
+# Windows Credential Manager caps a blob at 2560 BYTES (the tightest of the OS
+# stores, so it sets the budget everywhere), and keyring stores the
+# value as UTF-16LE — so the real ceiling is ~1280 CHARACTERS (measured on this
+# machine). The two JWT cookies total ~1700 chars and blow past it together;
+# each one alone (~961 and ~733) fits comfortably. Splitting them is what lets a
+# session be renewed without re-sending the password.
+
+def get_refresh_cookie(name: str) -> str | None:
+    return creds.get_optional(TOOL, f"refresh-{name}") or None
+
+
+def set_refresh_cookie(name: str, value: str) -> None:
+    creds.set_secret(TOOL, f"refresh-{name}", value)
+
+
+def clear_refresh_cookie(name: str) -> None:
+    creds.delete(TOOL, f"refresh-{name}")