procesio-cli 0.1.1__py3-none-any.whl

procesio_cli/tools/procesio/formlint.py

@@ -0,0 +1,292 @@
+"""Non-blocking safety lints for a form's Data DTO.
+
+These encode form-build traps that the server ACCEPTS silently and that then cost
+a debugging session to find (see PROCESIO-API-NOTES.md and FORM-DEV-GUIDE/08):
+
+* **Phantom parentId** — an element whose `parentId` matches no element id renders
+  on NO pane. Tab/container membership is by `parentId` = a container element's id;
+  a dangling one is invisible, not an error (O6).
+* **Duplicate id/name configs** — two elements sharing the designer `id` or `name`
+  config collide for selectors and process mapping.
+* **Patch wrapping mistake** — a form-update `--data` patch whose top-level key is
+  not an existing Data field is merged in as an inert junk key; the classic case is
+  wrapping the patch as `{"Data": {...}}` (O7).
+* **Multiple-select without isList** — a select with `multiple=true` whose `value`
+  config is not marked `isList` maps a list into a scalar.
+* **IS_TRUE / IS_FALSE on a Boolean variable whose default is the text "false"** — the
+  designer stores a Boolean form variable's default as a STRING ("False" / "false"), and a
+  condition treats any non-empty string as true. Measured live: default "false" or "False"
+  → IS_TRUE passes and IS_FALSE fails; default null → IS_TRUE fails and IS_FALSE passes.
+  A gate like `isConfirmed IS_TRUE` on such a default is always open.
+* **Field names a designer save renames** — a form built through the API keeps its field
+  names as written, but one save in the designer re-keys `ProcesioForm.data.fields`: it
+  splits each name on underscores, lowercases the parts and joins them in camelCase
+  (`orderList` -> `orderlist`, `order_id` -> `orderId`; measured on two names, hyphens and
+  spaces not tested). Form JS reading the original name then gets `undefined`. Only a
+  single lowercase word survives unchanged. One warning per form, naming them all.
+  That re-key happens only to a form whose `dataModelAttributeFormatVersion` is not "1": the
+  designer reads a missing version as the legacy "0" format (user-playground
+  Builder.component.vue; Form.model.ts::generateFormDataModel lower-cases under "0" and keeps
+  the name under "1"). A form at "1" keeps its names through a designer save (measured
+  2026-09-25 and 2026-10-05), so it draws no warning; form-create writes "1" since 2026-10-05.
+
+Pure and side-effect-free: each returns a list of human-readable warning strings.
+Warnings, never blockers — the caller attaches them to its result JSON.
+"""
+from __future__ import annotations
+
+import re
+from typing import Any
+
+
+def _elements(data: Any) -> list:
+    if isinstance(data, dict):
+        els = data.get("elements")
+        if isinstance(els, list):
+            return els
+    return []
+
+
+def _cfg_value(element: dict, key: str):
+    for c in element.get("configs") or []:
+        if isinstance(c, dict) and c.get("key") == key:
+            return c.get("value")
+    return None
+
+
+def _cfg(element: dict, key: str):
+    for c in element.get("configs") or []:
+        if isinstance(c, dict) and c.get("key") == key:
+            return c
+    return None
+
+
+def _label(element: dict) -> str:
+    """Best identifier for a message: the designer name, else the element id."""
+    name = _cfg_value(element, "name")
+    if isinstance(name, str) and name.strip():
+        return f"{name.strip()!r}"
+    return f"id {element.get('id')!r}"
+
+
+def lint_phantom_parent(data: Any) -> list[str]:
+    els = _elements(data)
+    ids = {e.get("id") for e in els if isinstance(e, dict)}
+    out = []
+    for e in els:
+        if not isinstance(e, dict):
+            continue
+        pid = e.get("parentId")
+        if pid not in (None, "") and pid not in ids:
+            out.append(
+                f"element {_label(e)} has parentId {pid!r} matching no element on the "
+                f"form — it renders on NO pane (dangling container reference). Point it "
+                f"at a real container/tab element id, or set parentId to null for a "
+                f"top-level element.")
+    return out
+
+
+def lint_duplicate_configs(data: Any) -> list[str]:
+    els = _elements(data)
+    out = []
+    for cfg_key in ("id", "name"):
+        seen: dict[str, int] = {}
+        for e in els:
+            if not isinstance(e, dict):
+                continue
+            val = _cfg_value(e, cfg_key)
+            if isinstance(val, str) and val.strip():
+                seen[val.strip()] = seen.get(val.strip(), 0) + 1
+        for val, n in seen.items():
+            if n > 1:
+                out.append(
+                    f"{n} elements share the same {cfg_key} config {val!r}; a duplicate "
+                    f"{cfg_key} collides for CSS/JS selectors and process mapping — make "
+                    f"each element's {cfg_key} unique.")
+    return out
+
+
+def lint_multiple_select_islist(data: Any) -> list[str]:
+    els = _elements(data)
+    out = []
+    for e in els:
+        if not isinstance(e, dict):
+            continue
+        multiple = _cfg_value(e, "multiple")
+        if multiple is True or (isinstance(multiple, str) and multiple.lower() == "true"):
+            value_cfg = _cfg(e, "value") or {}
+            is_list = value_cfg.get("isList") if isinstance(value_cfg, dict) else None
+            if not is_list:
+                out.append(
+                    f"element {_label(e)} is a multiple-select (multiple=true) but its "
+                    f"value config is not marked isList — a multi-value selection maps "
+                    f"into a scalar. Set isList on the value config / the mapped "
+                    f"data-model attribute.")
+    return out
+
+
+def lint_patch_keys(existing_data: Any, patch: Any) -> list[str]:
+    """A form-update --data patch whose top-level key is not an existing Data field
+    is added as a (probably inert) junk key. Flags the classic `{"Data": {...}}`
+    wrapping mistake explicitly."""
+    if not isinstance(patch, dict) or not isinstance(existing_data, dict):
+        return []
+    known = set(existing_data.keys())
+    out = []
+    for k in patch:
+        if k in known:
+            continue
+        if k.lower() == "data":
+            out.append(
+                f"patch top-level key {k!r} is not a Data field — this is almost "
+                f"certainly the wrapping mistake: pass the INNER fields directly (e.g. "
+                f'--data \'{{"hideBranding": true}}\'), not wrapped as {{{k!r}: {{...}}}}. '
+                f"As written it creates an inert junk key that changes nothing.")
+        else:
+            sample = ", ".join(sorted(known)[:8]) or "(none)"
+            out.append(
+                f"patch top-level key {k!r} is not an existing Data field — it will be "
+                f"ADDED as a new key (no existing value is changed). Existing fields "
+                f"include: {sample}. Check for a typo/casing mismatch.")
+    return out
+
+
+_BOOLEAN_TESTS = ("IS_TRUE", "IS_FALSE")
+
+
+def string_boolean_conditions(events: Any, variables: Any, where: str) -> list[str]:
+    """Warnings for IS_TRUE / IS_FALSE conditions, in `events`, on a form variable whose
+    default is the TEXT "false" (any case): the condition reads it as true. Shared by the
+    whole-form lint and by form-set-element-chains, which checks only the chains it writes.
+    A "true" text default is left alone - it evaluates the way it reads."""
+    defaults = {v.get("id"): v for v in variables or [] if isinstance(v, dict)}
+    out = []
+    for ev in events or []:
+        conds = ((ev or {}).get("config") or {}).get("conditions") or []
+        for c in conds:
+            op = str(c.get("operator") or "")
+            var = defaults.get((c.get("leftOperator") or {}).get("value"))
+            if op not in _BOOLEAN_TESTS or var is None:
+                continue
+            default = var.get("defaultValue")
+            if not (isinstance(default, str) and default.strip().lower() == "false"):
+                continue
+            effect = ("PASSES although it reads false" if op == "IS_TRUE"
+                      else "never passes although it reads false")
+            out.append(
+                f"{where}: condition `{var.get('name')} {op}` reads a form variable whose "
+                f"default is the TEXT {default!r}; a condition treats any non-empty text as "
+                f"true, so {op} {effect}, until something writes a real boolean (measured "
+                f"live). Set the default to null, or branch with EQUALS on a value that really "
+                f"is text (a select's value, or a field your own flow writes).")
+    return out
+
+
+def lint_string_boolean_conditions(data: Any) -> list[str]:
+    if not isinstance(data, dict):
+        return []
+    variables = data.get("variables") or []
+    out = string_boolean_conditions(data.get("events") or [], variables, "form-level event")
+    for e in _elements(data):
+        if not isinstance(e, dict):
+            continue
+        for c in e.get("configs") or []:
+            if (isinstance(c, dict) and str(c.get("key", "")).startswith("on")
+                    and isinstance(c.get("value"), dict)):
+                out += string_boolean_conditions(c["value"].get("events"), variables,
+                                                 f"element {_label(e)} {c.get('key')}")
+    return out
+
+
+_SINGLE_WORD = re.compile(r"[a-z0-9]+")
+_UNDERSCORED = re.compile(r"[A-Za-z0-9_]+")
+
+
+def designer_key(name: str) -> str | None:
+    """The key a designer save gives a field name, or None where that rule was not
+    measured (a name with hyphens, spaces or other characters)."""
+    if not _UNDERSCORED.fullmatch(name or ""):
+        return None
+    parts = [p.lower() for p in name.split("_") if p]
+    if not parts:
+        return None
+    return parts[0] + "".join(p[:1].upper() + p[1:] for p in parts[1:])
+
+
+def lint_field_names(data: Any) -> list[str]:
+    """One warning naming every element whose name a designer save would re-key.
+
+    None for a form at dataModelAttributeFormatVersion "1": the designer keeps its names."""
+    if isinstance(data, dict) and str(data.get("dataModelAttributeFormatVersion") or "") == "1":
+        return []
+    renamed = []
+    for el in _elements(data):
+        name = _cfg_value(el, "name")
+        if not isinstance(name, str) or not name or _SINGLE_WORD.fullmatch(name):
+            continue
+        key = designer_key(name)
+        renamed.append(f"{name} -> {key}" if key else f"{name} -> (renamed; rule not measured)")
+    if not renamed:
+        return []
+    shown = ", ".join(renamed[:8])
+    if len(renamed) > 8:
+        shown += f", and {len(renamed) - 8} more"
+    return [f"{len(renamed)} field name(s) are not a single lowercase word, and a save in the "
+            f"designer re-keys them in ProcesioForm.data.fields: {shown}. Form JS that reads "
+            f"the original name then gets undefined. Read fields through a lookup that ignores "
+            f"case and underscores, or name them as single lowercase words "
+            f"(FORM-DEV-GUIDE/08-PITFALLS.md)."]
+
+
+# Form custom CSS is scoped to the form container: every selector's last compound gets
+# `:where([data-form-css-scope=<id>], [data-form-css-scope=<id>] *)` appended. UI the JS mounts
+# on document.body, and `:root` / `html` / `body` rules, sit outside that scope and get no style
+# unless the JS copies the attribute onto <html>. See FORM-DEV-GUIDE/02-CODE-INJECTION.md §2.
+_SCOPE_ATTR = "data-form-css-scope"
+_BODY_MOUNT = re.compile(
+    r"document\.body\s*\.\s*(?:appendChild|append|prepend|insertBefore|insertAdjacentHTML|"
+    r"insertAdjacentElement|replaceChildren)\b"
+    r"|document\.body\s*\.\s*innerHTML\s*\+?="
+    r"|\.mount\(\s*(?:document\.body\b|['\"]body['\"])")
+_CSS_COMMENT = re.compile(r"/\*.*?\*/", re.S)
+_CSS_PRELUDE = re.compile(r"([^{}]+)\{")
+_PAGE_SELECTOR = re.compile(r"(:root|html|body)(?![\w-])", re.I)
+
+
+def lint_form_code_scope(css: str | None, js: str | None) -> list[str]:
+    """One warning when the form code relies on styling outside the form's CSS scope.
+
+    Fires when the JS mounts UI on document.body, or the CSS styles :root / html / body, and the
+    JS never mentions the scope attribute (the known fix copies it onto <html>). A form whose UI
+    stays inside the form container triggers neither and gets no warning."""
+    css, js = css or "", js or ""
+    if _SCOPE_ATTR in js:
+        return []
+    reasons = []
+    if _BODY_MOUNT.search(js):
+        reasons.append("the JS renders UI onto document.body")
+    heads = set()
+    for prelude in _CSS_PRELUDE.findall(_CSS_COMMENT.sub("", css)):
+        prelude = prelude.strip()
+        if prelude.startswith("@"):
+            continue
+        for sel in prelude.split(","):
+            m = _PAGE_SELECTOR.match(sel.strip())
+            if m:
+                heads.add(m.group(1).lower())
+    if heads:
+        reasons.append("the CSS styles " + " / ".join(sorted(heads)))
+    if not reasons:
+        return []
+    return [f"form code: {' and '.join(reasons)}, but the form's custom CSS is scoped to the form "
+            f"container ([{_SCOPE_ATTR}]), so those styles will not apply. Before mounting, copy the "
+            f"container's {_SCOPE_ATTR} value onto <html> (FORM-DEV-GUIDE/02-CODE-INJECTION.md §2)."]
+
+
+def lint_form_data(data: Any) -> list[str]:
+    """All structural (element-level) lints for a form's Data."""
+    return (lint_phantom_parent(data)
+            + lint_duplicate_configs(data)
+            + lint_multiple_select_islist(data)
+            + lint_string_boolean_conditions(data)
+            + lint_field_names(data))

procesio_cli/tools/procesio/gen_manifest.py

@@ -0,0 +1,118 @@
+"""Regenerate tool.yaml's `actions:` block from the live dispatcher.
+
+The manifest is the source of truth (CLAUDE.md Hard rule 3) and the sync guard
+(tests/test_manifest_sync.py) demands it match the dispatcher's actions/args
+EXACTLY. With 250+ actions the file is ~200 KB — far too large to hand-edit,
+especially under the Cowork mount's ~15 KB Write/Edit cap. So this script is the
+ONLY supported way to change the action surface:
+
+    1. change handlers / autogen / dto actions,
+    2. run `python -m tools.procesio.gen_manifest` (writes tool.yaml directly via
+       Python — not the capped Write tool),
+    3. `pytest tools/procesio/tests/test_manifest_sync.py` stays green.
+
+It preserves the hand-written header (everything up to and including the
+`actions:` line — name/description/version/routing/secrets + comments) verbatim,
+and regenerates only the actions list, sorted by name for a stable diff. Arg
+type/required/description are introspected from each action's argparse exactly as
+the sync test reads them, so the two can never drift.
+"""
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+import yaml
+
+TOOL_ROOT = Path(__file__).resolve().parent
+MANIFEST = TOOL_ROOT / "tool.yaml"
+
+
+def _arg_type(action: argparse.Action) -> str:
+    if isinstance(action, (argparse._StoreTrueAction, argparse._StoreFalseAction)):
+        return "boolean"
+    if action.type is int:
+        return "integer"
+    if action.type is float:
+        return "number"
+    return "string"
+
+
+def _action_args(defn) -> list[dict]:
+    """The arg specs for one ActionDef, in argparse declaration order — the exact
+    surface the sync test compares against."""
+    parser = argparse.ArgumentParser()
+    defn.add_args(parser)
+    out: list[dict] = []
+    for action in parser._actions:
+        names = [o for o in action.option_strings if o.startswith("--") and o != "--help"]
+        if not names:
+            continue
+        name = names[0][2:]
+        spec = {
+            "name": name,
+            "type": _arg_type(action),
+            "required": bool(getattr(action, "required", False)),
+            "description": (action.help or "").strip(),
+        }
+        # A structured argument publishes its schema too: `help=` can say an arg takes
+        # JSON, never what belongs in it, so without this a manifest reader has to
+        # discover the shape from validation errors one layer at a time.
+        schema = (getattr(defn, "arg_schemas", None) or {}).get(name)
+        if schema:
+            spec["schema"] = schema
+        out.append(spec)
+    return out
+
+
+def build_actions_block() -> list[dict]:
+    from tools.procesio import main
+    actions = []
+    for name in sorted(main.ACTIONS):
+        defn = main.ACTIONS[name]
+        entry = {
+            "name": name,
+            "description": (defn.description or "").strip(),
+            "args": _action_args(defn),
+        }
+        examples = getattr(defn, "examples", None)
+        if examples:
+            entry["examples"] = examples
+        actions.append(entry)
+    return actions
+
+
+def _header_text() -> str:
+    """Everything up to and including the `actions:` line, preserved verbatim so
+    hand-written comments / routing / secrets / the long description are kept."""
+    text = MANIFEST.read_text(encoding="utf-8")
+    lines = text.splitlines(keepends=True)
+    for i, line in enumerate(lines):
+        if line.rstrip("\n") == "actions:":
+            return "".join(lines[: i + 1])
+    raise SystemExit("tool.yaml has no top-level `actions:` line to anchor on")
+
+
+def render() -> str:
+    header = _header_text()
+    body = yaml.safe_dump(
+        build_actions_block(),
+        sort_keys=False, default_flow_style=False, allow_unicode=True,
+        width=10_000,  # never wrap a description onto a second line
+    )
+    return header + body
+
+
+def main() -> int:
+    new_text = render()
+    # newline="\n" is load-bearing: the repo stores this manifest with LF, and a
+    # default Windows write turns every one of its ~9,000 lines into a diff hunk, which
+    # buries the handful that actually changed and makes the manifest unreviewable.
+    MANIFEST.write_text(new_text, encoding="utf-8", newline="\n")  # direct write (not capped)
+    n_actions = new_text.count("\n- name:")
+    print(f"wrote {MANIFEST} ({len(new_text)} bytes, {n_actions} actions)")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

procesio_cli/tools/procesio/handlers/__init__.py

@@ -0,0 +1 @@
+"""PROCESIO action handlers."""

procesio_cli/tools/procesio/handlers/auth_actions.py

@@ -0,0 +1,103 @@
+"""Auth lifecycle actions: login, check-auth, logout.
+
+These are client-backed (they need a profile + session) but deliberately never
+return a token value - only whether authentication works and how it was done.
+"""
+from __future__ import annotations
+
+from tools.procesio import auth, config, profiles
+from tools.procesio.actiondef import ActionDef
+from tools.procesio.errors import ProcesioAPIError
+from tools.procesio.handlers.common import add_profile_arg
+
+# A cheap, side-effect-free GET used to confirm a credential actually works.
+# /api/Workspaces lists the caller's workspaces; it requires only valid auth.
+_PROBE_PATH = "/api/Workspaces"
+
+
+def login(client, _args) -> dict:
+    """Force-acquire (userpass) or confirm (apikey) authentication."""
+    kind = client.profile.get("type")
+    if kind == "userpass":
+        session = auth.force_login(client.name, client.profile, client._session)
+        cookies = session.get("cookies", {})
+        return {
+            "authenticated": True,
+            "mode": "userpass",
+            "profile": client.name,
+            "environment": client.env.get("name"),
+            "session_cached": True,
+            "cookie_names": sorted(cookies.keys()),   # names only, never values
+            "expires_at": session.get("expires_at"),
+            "web_base": config.web_base(client.profile),
+            "login_path": auth.LOGIN_PATH,
+        }
+    # apikey: nothing to fetch - just confirm the headers are well-formed.
+    headers = auth.auth_headers(client.name, client.profile, client._session)
+    return {
+        "authenticated": True,
+        "mode": "apikey",
+        "profile": client.name,
+        "environment": client.env.get("name"),
+        "sends_workspaceid": "workspaceid" in headers,
+        "web_base": config.web_base(client.profile),
+        "note": ("apikey auth is validated per-request; run check-auth to hit a "
+                 "live endpoint"),
+    }
+
+
+def check_auth(client, _args) -> dict:
+    """Hit a live read endpoint to confirm the credential is accepted."""
+    try:
+        body = client.get(_PROBE_PATH)
+    except ProcesioAPIError as e:
+        return {
+            "authenticated": False,
+            "profile": client.name,
+            "environment": client.env.get("name"),
+            "mode": client.profile.get("type"),
+            "probe": _PROBE_PATH,
+            "status": e.status,
+            "detail": e.details,
+            "web_base": config.web_base(client.profile),
+            "auth_base": config.auth_base(client.profile),
+        }
+    n = len(body) if isinstance(body, list) else None
+    return {
+        "authenticated": True,
+        "profile": client.name,
+        "environment": client.env.get("name"),
+        "web_base": config.web_base(client.profile),
+        "mode": client.profile.get("type"),
+        "probe": _PROBE_PATH,
+        "workspaces_visible": n,
+    }
+
+
+def logout(client, _args) -> dict:
+    """Clear the cached session (in-process + persistent), best-effort server logOut."""
+    name = client.name
+    had = (name in auth._MEM_COOKIES) or (profiles.get_token_cache(name) is not None)
+    if client.profile.get("type") == "userpass" and had:
+        try:
+            client.post("/api/Authentication/logOut")
+        except ProcesioAPIError:
+            pass
+    auth.clear_cookies(name)
+    return {"profile": name, "cleared_cached_token": had}
+
+
+ACTIONS = {
+    "login": ActionDef(
+        func=login, add_args=add_profile_arg, needs_client=True,
+        description="Acquire (userpass) or confirm (apikey) authentication; caches the token.",
+    ),
+    "check-auth": ActionDef(
+        func=check_auth, add_args=add_profile_arg, needs_client=True,
+        description="Hit a live read endpoint to verify the profile authenticates.",
+    ),
+    "logout": ActionDef(
+        func=logout, add_args=add_profile_arg, needs_client=True,
+        description="Clear the cached Bearer token for a userpass profile.",
+    ),
+}

procesio_cli/tools/procesio/handlers/catalog.py

@@ -0,0 +1,147 @@
+"""Curated read actions for workspaces, data types, the action catalog, stored
+connection credentials, and API keys. All are safe GETs over exact v1.19 paths.
+"""
+from __future__ import annotations
+
+import argparse
+
+from tools.procesio.actiondef import ActionDef
+from tools.procesio.flowmodel import families
+from tools.procesio.handlers.common import add_paging_args, add_profile_arg
+
+
+def list_workspaces(client, _args) -> dict:
+    return {"result": client.get("/api/Workspaces")}
+
+
+def _subworkspaces_args(p: argparse.ArgumentParser) -> None:
+    add_profile_arg(p)
+    add_paging_args(p)
+    p.add_argument("--parent-id", dest="parent_id", required=True,
+                   help="master workspace GUID whose sub-workspaces to list")
+    p.add_argument("--include-removed", dest="include_removed", action="store_true",
+                   help="include soft-deleted (workspaceState='removed') workspaces")
+
+
+def list_subworkspaces(client, args) -> dict:
+    """Sub-workspaces of a master. ACTIVE-ONLY by default — the raw endpoint also
+    returns soft-deleted ones (workspaceState='removed'), which the UI hides.
+    Needs owner/admin context (use the userpass `account` profile)."""
+    q = {"pageNumber": args.page, "pageItemCount": args.page_size}
+    res = client.get(f"/api/Workspace/{args.parent_id}/subworkspaces", q)
+    rows = res.get("pageItems") if isinstance(res, dict) else res
+    rows = rows if isinstance(rows, list) else []
+    if not args.include_removed:
+        rows = [w for w in rows if str(w.get("workspaceState", "")).lower() != "removed"]
+    return {"parent_id": args.parent_id, "count": len(rows),
+            "include_removed": bool(args.include_removed), "workspaces": rows}
+
+
+def _ws_users_args(p: argparse.ArgumentParser) -> None:
+    add_profile_arg(p)
+    add_paging_args(p)
+    p.add_argument("--target-workspace", dest="target_workspace",
+                   help="targetWorkspace id (sub-workspace)")
+
+
+def list_workspace_users(client, args) -> dict:
+    q = {"pageNumber": args.page, "pageItemCount": args.page_size,
+         "targetWorkspace": args.target_workspace}
+    return {"result": client.get("/api/Workspace/users", q)}
+
+
+def _search_args(p: argparse.ArgumentParser) -> None:
+    add_profile_arg(p)
+    add_paging_args(p)
+    p.add_argument("--search", help="searchName filter")
+
+
+def list_datatypes(client, args) -> dict:
+    q = {"pageNumber": args.page, "pageItemCount": args.page_size,
+         "searchName": args.search}
+    return {"result": client.get("/api/DataTypes", q)}
+
+
+def _actions_args(p: argparse.ArgumentParser) -> None:
+    add_profile_arg(p)
+    p.add_argument("--filter", dest="action_filter", help="actionFilter value")
+    p.add_argument("--full", action="store_true",
+                   help="the FULL raw catalog (getFullAction=true) - ~280KB, opt-in")
+    p.add_argument("--raw", action="store_true",
+                   help="the raw /api/Actions list (large) instead of the compact view")
+    p.add_argument("--by-family", dest="by_family", action="store_true",
+                   help="(default already groups by family; kept for back-compat)")
+    p.add_argument("--family", help="return only one family's actions")
+
+
+def list_actions_catalog(client, args) -> dict:
+    q = {"actionFilter": args.action_filter,
+         "getFullAction": "true" if args.full else None}
+    res = client.get("/api/Actions", q)
+    # Default is a COMPACT family-grouped listing (name + desc per action). The full raw
+    # catalog is ~280KB - big enough to strain a small context window on its own - so it
+    # is opt-in via --full / --raw. --family filters the compact view to one family.
+    if args.full or getattr(args, "raw", False):
+        return {"result": res}
+    items = res.get("actions") if isinstance(res, dict) else res
+    items = items if isinstance(items, list) else []
+    buckets: dict[str, list] = {}
+    for a in items:
+        name = a.get("name") or a.get("Name")
+        buckets.setdefault(families.classify(name), []).append(
+            {"name": name, "icon": a.get("icon"), "shape": a.get("shape"),
+             "desc": families.describe(name)})
+    if args.family:
+        return {"result": {args.family: buckets.get(args.family, [])}}
+    return {"result": {"families": buckets}}
+
+
+def list_connections(client, args) -> dict:
+    """PROCESIO's stored connection credentials (GET /api/Credentials)."""
+    q = {"pageNumber": args.page, "pageItemCount": args.page_size,
+         "searchName": args.search}
+    return {"result": client.get("/api/Credentials", q)}
+
+
+def list_connection_types(client, _args) -> dict:
+    return {"result": client.get("/api/Credentials/types")}
+
+
+def list_api_keys(client, _args) -> dict:
+    return {"result": client.get("/api/ApiKey")}
+
+
+ACTIONS = {
+    "list-workspaces": ActionDef(
+        func=list_workspaces, add_args=add_profile_arg, needs_client=True,
+        description="List the caller's workspaces (GET /api/Workspaces, active-only).",
+    ),
+    "list-subworkspaces": ActionDef(
+        func=list_subworkspaces, add_args=_subworkspaces_args, needs_client=True,
+        description="List a master's sub-workspaces, active-only by default (--include-removed for soft-deleted).",
+    ),
+    "list-workspace-users": ActionDef(
+        func=list_workspace_users, add_args=_ws_users_args, needs_client=True,
+        description="List users in a workspace (GET /api/Workspace/users).",
+    ),
+    "list-datatypes": ActionDef(
+        func=list_datatypes, add_args=_search_args, needs_client=True,
+        description="List data types (GET /api/DataTypes).",
+    ),
+    "list-actions-catalog": ActionDef(
+        func=list_actions_catalog, add_args=_actions_args, needs_client=True,
+        description="List the action/connector catalog (GET /api/Actions).",
+    ),
+    "list-connections": ActionDef(
+        func=list_connections, add_args=_search_args, needs_client=True,
+        description="List stored connection credentials (GET /api/Credentials).",
+    ),
+    "list-connection-types": ActionDef(
+        func=list_connection_types, add_args=add_profile_arg, needs_client=True,
+        description="List supported connection types (GET /api/Credentials/types).",
+    ),
+    "list-api-keys": ActionDef(
+        func=list_api_keys, add_args=add_profile_arg, needs_client=True,
+        description="List API keys in the workspace (GET /api/ApiKey).",
+    ),
+}