procesio-cli 0.1.1__py3-none-any.whl

procesio_cli/tools/procesio/handlers/form_update.py

@@ -0,0 +1,270 @@
+"""form-update — apply an arbitrary change to a LIVE form and save it safely.
+
+The canonical GET -> modify -> PUT path for raw form surgery that no narrower
+action covers (change a label, a theme var, a table column header, a select
+option, publish a draft, rename). It fetches the form, deep-merges a caller
+`--data` patch into its `Data`, optionally overrides top-level Name/Status/State,
+and PUTs the accepted PascalCase envelope via `form_code.build_put_body` — the
+only body shape the server accepts (the camelCase GET echo is rejected 403).
+
+Unlike `form-edit`, it does NOT rebuild the form from a desired-state config, so
+existing elements/theme/code/logic survive untouched — only what the patch names
+changes. Like the other surgical actions it is a last-write-wins read-modify-write
+guarded by `guard_unchanged` (--force to override); see form_code.py.
+
+Merge semantics (deep merge, deliberately NOT RFC-7386): nested objects merge
+recursively; arrays, scalars, and null REPLACE the target value (null sets the key
+to null — it does not delete it). To swap an array wholesale (elements, variables,
+theme) pass the whole new array; to flip one scalar deep in Data pass just that
+key, e.g. --data '{"hideBranding": true}'.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+
+from tools.procesio import formlint
+from tools.procesio.actiondef import ActionDef
+from tools.procesio.errors import UsageError
+from tools.procesio.handlers.common import add_force_arg, add_profile_arg, guard_unchanged
+from tools.procesio.dto.form import addelement
+from tools.procesio.dto.form.builder import reconcile_assignees
+from tools.procesio.handlers.form_code import _fetch, build_put_body
+
+
+def _deep_merge(target, patch):
+    """Deep-merge `patch` into `target`. Nested dicts merge; arrays/scalars/null replace."""
+    if not isinstance(patch, dict) or not isinstance(target, dict):
+        return patch
+    out = dict(target)
+    for k, v in patch.items():
+        out[k] = _deep_merge(out.get(k), v) if isinstance(v, dict) else v
+    return out
+
+
+def _load_patch(args) -> dict | None:
+    raw = None
+    if args.data_file:
+        raw = Path(args.data_file).read_text(encoding="utf-8")
+    elif args.data:
+        raw = args.data
+    if raw is None:
+        return None
+    try:
+        patch = json.loads(raw)
+    except json.JSONDecodeError as e:
+        raise UsageError(f"--data must be valid JSON: {e}") from e
+    if not isinstance(patch, dict):
+        raise UsageError("--data must be a JSON object (a merge patch for the form's Data)")
+    return patch
+
+
+def form_update(client, args) -> dict:
+    patch = _load_patch(args)
+    state = None if args.state is None else (args.state == "true")
+    is_private = None if args.is_private is None else (args.is_private == "true")
+    if (patch is None and args.name is None and args.status is None
+            and state is None and is_private is None):
+        raise UsageError(
+            "nothing to update: pass --data/--data-file (a Data merge patch) "
+            "and/or --name/--status/--state/--is-private"
+        )
+
+    form = _fetch(client, args.id)
+    existing = dict(form.get("data") or {})
+    data = existing
+    if patch is not None:
+        data = _deep_merge(existing, patch)
+
+    # Non-blocking safety lints (warnings only — never refuse the save). They catch
+    # traps the server accepts silently: a phantom parentId, duplicate id/name
+    # configs, a multiple-select missing isList, and a patch key that isn't an
+    # existing Data field (the {"Data": {...}} wrapping mistake). See formlint.py.
+    lints = formlint.lint_form_data(data)
+    if patch is not None:
+        lints = formlint.lint_patch_keys(existing, patch) + lints
+
+    body = build_put_body(form, data=data, name=args.name, status=args.status, state=state,
+                          is_private=is_private)
+    result = {
+        "id": form.get("id"),
+        "name": body["Name"],
+        "status": body["Status"],
+        "state": body["State"],
+        "isPrivate": body["IsPrivate"],
+        "patched_keys": sorted(patch) if patch else [],
+        "dry_run": bool(args.dry_run),
+        "applied": False,
+    }
+    if lints:
+        result["lints"] = lints
+    if args.dry_run:
+        result["dto"] = body
+        return result
+    guard = guard_unchanged(lambda: _fetch(client, args.id), form, force=args.force)
+    client.put("/api/FormTemplate", body)
+    result["applied"] = True
+    result["concurrency"] = guard
+    return result
+
+
+def form_add_element(client, args) -> dict:
+    raw = (Path(args.elements_file).read_text(encoding="utf-8") if args.elements_file
+           else args.elements)
+    if not raw:
+        raise UsageError("pass --elements '<json>' or --elements-file <path>")
+    try:
+        specs = json.loads(raw)
+    except json.JSONDecodeError as e:
+        raise UsageError(f"--elements must be valid JSON: {e}") from e
+    if isinstance(specs, dict):
+        specs = [specs]
+    if not isinstance(specs, list):
+        raise UsageError("--elements must be an element object or a list of them")
+
+    form = _fetch(client, args.id)
+    data = addelement.add_elements(form, specs, parent=args.parent)
+
+    lints = formlint.lint_form_data(data)
+    assignees, routing = reconcile_assignees(
+        form.get("assignees") or [], (form.get("data") or {}).get("elements") or [],
+        data.get("elements") or [])
+    body = build_put_body(form, data=data, assignees=assignees if routing else None)
+    added = [e for e in data["elements"] if e not in (form.get("data") or {}).get("elements", [])]
+    result = {
+        "id": form.get("id"), "name": body["Name"],
+        "added": [{"id": e["id"], "type": e.get("type"),
+                   "name": addelement._name_of(e)} for e in added],
+        "element_count": len(data["elements"]),
+        "parent": args.parent,
+        "dry_run": bool(args.dry_run), "applied": False,
+    }
+    warning = addelement.unreachable_in_row(data["elements"], args.parent and
+                                           addelement._resolve_parent(data["elements"], args.parent))
+    if warning:
+        result["warning"] = warning
+    if routing:
+        result["assignees"] = routing
+    if lints:
+        result["lints"] = lints
+    if args.dry_run:
+        return result
+    guard = guard_unchanged(lambda: _fetch(client, args.id), form, force=args.force)
+    client.put("/api/FormTemplate", body)
+    result["applied"] = True
+    result["concurrency"] = guard
+    return result
+
+
+def _add_element_args(p: argparse.ArgumentParser) -> None:
+    add_profile_arg(p)
+    p.add_argument("--id", required=True, help="form template id")
+    p.add_argument("--elements", help="one authoring-config element object, or a JSON list of them")
+    p.add_argument("--elements-file", dest="elements_file",
+                   help="path to a JSON file with the element(s)")
+    p.add_argument("--parent", help="place them inside this container, by element name or id")
+    p.add_argument("--dry-run", dest="dry_run", action="store_true",
+                   help="build the new Data and report what would be added, without saving")
+    add_force_arg(p)
+
+
+def form_delete_element(client, args) -> dict:
+    form = _fetch(client, args.id)
+    data, report = addelement.delete_element(form, args.element, force=bool(args.force_refs))
+
+    lints = formlint.lint_form_data(data)
+    assignees, routing = reconcile_assignees(
+        form.get("assignees") or [], (form.get("data") or {}).get("elements") or [],
+        data.get("elements") or [])
+    body = build_put_body(form, data=data, assignees=assignees if routing else None)
+    result = {"id": form.get("id"), "name": body["Name"], **report,
+              "dry_run": bool(args.dry_run), "applied": False}
+    if routing:
+        result["assignees"] = routing
+    if lints:
+        result["lints"] = lints
+    if args.dry_run:
+        return result
+    guard = guard_unchanged(lambda: _fetch(client, args.id), form, force=args.force)
+    client.put("/api/FormTemplate", body)
+    result["applied"] = True
+    result["concurrency"] = guard
+    return result
+
+
+def _delete_element_args(p: argparse.ArgumentParser) -> None:
+    add_profile_arg(p)
+    p.add_argument("--id", required=True, help="form template id")
+    p.add_argument("--element", required=True,
+                   help="the control to remove, by its `name` config or its id")
+    p.add_argument("--force-refs", dest="force_refs", action="store_true",
+                   help="delete even when the control is still referenced, or still contains "
+                        "other controls, and report what that breaks")
+    p.add_argument("--dry-run", dest="dry_run", action="store_true",
+                   help="report what would be removed, without saving")
+    add_force_arg(p)
+
+
+def _update_args(p: argparse.ArgumentParser) -> None:
+    add_profile_arg(p)
+    p.add_argument("--id", required=True, help="form template id")
+    p.add_argument("--data", help="JSON object deep-merged into the form's Data (a merge patch)")
+    p.add_argument("--data-file", dest="data_file",
+                   help="path to a JSON file with the Data merge patch")
+    p.add_argument("--name", help="rename the form (top-level Name)")
+    p.add_argument("--status", type=int, choices=[0, 1],
+                   help="publication status: 1=published, 0=draft")
+    p.add_argument("--state", choices=["true", "false"], help="enabled flag (true/false)")
+    p.add_argument("--is-private", dest="is_private", choices=["true", "false"],
+                   help="reachability: false + --status 1 makes the form answer an anonymous "
+                        "visitor on its custom URL; true keeps it behind a PROCESIO login")
+    p.add_argument("--dry-run", dest="dry_run", action="store_true",
+                   help="build the PUT DTO and return it without saving (GET only)")
+    add_force_arg(p)
+
+
+ACTIONS = {
+    "form-add-element": ActionDef(
+        func=form_add_element,
+        add_args=_add_element_args,
+        needs_client=True,
+        description=(
+            "Add one or more controls to a LIVE form (authoring-config elements), splicing them "
+            "into Data.elements AND the data model without regenerating what is already there - "
+            "so every existing field path, and every process map that references one, survives. "
+            "--parent places them in a container by name or id; --dry-run previews. A new "
+            "control with an assignee or approver is routed: the form's top-level Assignees is "
+            "re-derived as the designer would, reported under `assignees`."
+        ),
+    ),
+    "form-delete-element": ActionDef(
+        func=form_delete_element,
+        add_args=_delete_element_args,
+        needs_client=True,
+        description=(
+            "Remove one control from a LIVE form: out of Data.elements, out of the form's data "
+            "model, and out of its container's own list - leaving every other element's id and "
+            "field path untouched, the same property that makes form-add-element safe. REFUSES "
+            "by default when the control still contains other controls or is still referenced "
+            "(an event, a RUN_PROCESS input/output map, a visibility condition), because a "
+            "dangling field path is saved without any error and the control that pointed at it "
+            "then silently launches nothing; --force-refs deletes anyway and reports what it "
+            "broke. References are found by element id, so one made by NAME is not detected. "
+            "Removing a control that routes a step (an approval control, an assigned section) "
+            "re-derives the form's top-level Assignees, reported under `assignees`. "
+            "--dry-run previews."
+        ),
+    ),
+    "form-update": ActionDef(
+        func=form_update,
+        add_args=_update_args,
+        needs_client=True,
+        description=(
+            "Safely save an arbitrary change to a LIVE form: GET it, deep-merge a --data "
+            "patch into its Data (and/or override --name/--status/--state/--is-private), then PUT the "
+            "server-accepted PascalCase DTO. Preserves elements/theme/code (never rebuilds "
+            "like form-edit). Last-write-wins guard (--force); --dry-run previews the DTO."
+        ),
+    ),
+}

procesio_cli/tools/procesio/handlers/formprocess.py

@@ -0,0 +1,211 @@
+"""Run a process THROUGH A FORM, the way a browser submission does.
+
+Why this exists (and why it is not the same as `run-process-with-file`): a form and the
+process behind it are assembled separately, and nothing in the process API asserts that the
+two agree. A form whose submit button is wired to nothing, or whose input reaches the engine
+but is never consumed, passes every process-side assertion ever written. Both defects have
+shipped. Exercising the FORM surface is what catches them.
+
+The FormProcess controller is the public front-end route (anonymous, scoped entirely by the
+`formTemplateWorkspaceId` header). The sequence mirrors the process side:
+
+    publish (metadata only) -> upload each file (multipart) -> launch -> read variables
+
+Two mechanics the generated `<method>-<path>` actions cannot reach, which is why this is a
+curated handler: every call needs the `formTemplateWorkspaceId` header, and the file upload
+is `multipart/form-data` with the field name `package`.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import mimetypes
+import os
+import time
+import uuid
+
+from tools._lib.io import log
+from tools.procesio.actiondef import ActionDef
+from tools.procesio.client import parse_json_arg
+from tools.procesio.errors import ProcesioAPIError, UsageError
+from tools.procesio.handlers.common import add_profile_arg
+
+_TERMINAL = {6, 40, 50}
+_LABEL = {1: "starting", 6: "stopped", 40: "finished_with_errors", 50: "finished"}
+
+
+def _json_call(client, method, path, *, query=None, body=None, headers=None):
+    """A JSON request that can carry extra headers. client.request() cannot, and these
+    endpoints are addressed by header, so everything here goes through request_bytes."""
+    status, raw, _ = client.request_bytes(method, path, query=query, body=body, headers=headers)
+    text = (raw or b"").decode("utf-8", "replace").strip()
+    parsed = None
+    if text:
+        try:
+            parsed = json.loads(text)
+        except ValueError:
+            parsed = text
+    if 200 <= status < 300:
+        return parsed
+    raise ProcesioAPIError(status, f"HTTP {status}",
+                           parsed if isinstance(parsed, dict) else {"body": parsed})
+
+
+def _instance_id(resp):
+    """The published instance id, wherever this manager-defined shape puts it."""
+    if isinstance(resp, str) and resp.count("-") == 4:
+        return resp
+    if isinstance(resp, dict):
+        for k in ("id", "instanceId", "instanceID", "flowInstanceId"):
+            v = resp.get(k)
+            if isinstance(v, str) and v:
+                return v
+        flows = resp.get("flows")
+        if isinstance(flows, list) and flows and isinstance(flows[0], dict):
+            v = flows[0].get("id")
+            if v:
+                return v
+        for key in ("result", "value", "data", "instance"):
+            inner = resp.get(key)
+            if isinstance(inner, (dict, str)):
+                got = _instance_id(inner)
+                if got:
+                    return got
+    return None
+
+
+def run_form_with_files(client, args) -> dict:
+    form_id = args.form_id
+    process_id = args.process_id
+    ws = args.workspace_id or (client.profile or {}).get("workspace_id")
+    if not ws:
+        raise UsageError("--workspace-id is required: FormProcess is scoped by the "
+                         "formTemplateWorkspaceId header")
+    hdr = {"formTemplateWorkspaceId": ws}
+
+    payload = parse_json_arg(args.payload, "--payload") if args.payload else {}
+    if not isinstance(payload, dict):
+        raise UsageError("--payload must be a JSON object")
+
+    # File inputs are staged as METADATA ONLY at publish; the bytes follow per file.
+    staged = []
+    for spec in (args.file or []):
+        if "=" not in spec:
+            raise UsageError(f"--file must be VARNAME=PATH, got {spec!r}")
+        var, path = spec.split("=", 1)
+        var, path = var.strip(), path.strip()
+        if not os.path.isfile(path):
+            raise UsageError(f"file not found for {var}: {path}")
+        size = os.path.getsize(path)
+        name = os.path.basename(path)
+        mime = mimetypes.guess_type(name)[0] or "application/octet-stream"
+        fid = str(uuid.uuid4())
+        staged.append({"var": var, "path": path, "name": name, "size": size,
+                       "mime": mime, "file_id": fid})
+        payload[var] = {"path": "", "size": size, "mimeType": mime,
+                        "name": name, "id": fid, "hash": ""}
+
+    log(f"publishing through form {form_id}")
+    pub = _json_call(client, "POST",
+                     f"/api/FormProcess/{form_id}/{process_id}/publish",
+                     body=payload, headers=hdr)
+    inst = _instance_id(pub)
+    if not inst:
+        raise ProcesioAPIError(0, "form publish returned no instance id",
+                               {"response": pub})
+    log(f"instance {inst}")
+
+    for f in staged:
+        with open(f["path"], "rb") as fh:
+            content = fh.read()
+        client.request_multipart(
+            f"/api/FormProcess/{form_id}/{inst}/upload",
+            files={"package": (f["name"], content, f["mime"])},
+            headers={"flowTemplateId": process_id, "variableName": f["var"],
+                     "fileId": f["file_id"], "formTemplateWorkspaceId": ws})
+        log(f"uploaded {f['name']} ({f['size']} bytes) -> {f['var']}")
+
+    # The launch route's second path segment is documented as processTemplateId, but the
+    # body already carries flowTemplateId, so on the process side that slot is the INSTANCE.
+    # Try the instance first and fall back, rather than guessing which the platform means.
+    body = {"connectionId": None, "flowTemplateId": process_id}
+    query = {"runSynchronous": "true" if args.synchronous else "false",
+             "secondsTimeOut": args.timeout}
+    launched, used = None, None
+    for seg in (inst, process_id):
+        try:
+            launched = _json_call(client, "POST",
+                                  f"/api/FormProcess/{form_id}/{seg}/launch",
+                                  query=query, body=body, headers=hdr)
+            used = seg
+            break
+        except ProcesioAPIError as e:
+            if seg == process_id:
+                raise
+            log(f"launch with instance in path failed ({e}); retrying with template")
+    log(f"launched (path segment used: {'instance' if used == inst else 'template'})")
+
+    variables, status = None, None
+    deadline = time.time() + max(int(args.timeout or 60), 5)
+    while time.time() < deadline:
+        try:
+            variables = _json_call(
+                client, "GET",
+                f"/api/FormProcess/{form_id}/{process_id}/{inst}/variables",
+                headers=hdr)
+        except ProcesioAPIError:
+            variables = None
+        status = None
+        if isinstance(variables, dict):
+            for k in ("status", "instanceStatus"):
+                if isinstance(variables.get(k), int):
+                    status = variables[k]
+            inner = variables.get("instance")
+            if isinstance(inner, dict) and isinstance(inner.get("status"), int):
+                status = inner["status"]
+        if status in _TERMINAL or not args.synchronous:
+            break
+        time.sleep(3)
+
+    # The variables endpoint returns flow-variable DEFINITIONS and carries the runtime value
+    # in `defaultValue`, not `value`. Flatten to {name: value} so callers cannot misread an
+    # empty `value` key as "the form produced nothing" -- which is exactly the false negative
+    # this action exists to prevent.
+    flat = {}
+    if isinstance(variables, dict):
+        for item in (variables.get("variables") or []):
+            if isinstance(item, dict) and item.get("name"):
+                flat[item["name"]] = item.get("defaultValue")
+
+    return {"form_id": form_id, "process_id": process_id, "instance_id": inst,
+            "launch_path_segment": "instance" if used == inst else "template",
+            "files": [{"variable": f["var"], "name": f["name"], "size": f["size"]}
+                      for f in staged],
+            "status": status, "status_label": _LABEL.get(status, str(status)),
+            "variable": flat, "variables": variables, "launch": launched}
+
+
+def _args(p: argparse.ArgumentParser) -> None:
+    add_profile_arg(p)
+    p.add_argument("--form-id", dest="form_id", required=True, help="form template id")
+    p.add_argument("--process-id", dest="process_id", required=True,
+                   help="process (flow template) id the form submits to")
+    p.add_argument("--file", action="append",
+                   help="VARNAME=PATH for a File input variable (repeatable)")
+    p.add_argument("--payload", help="non-file input variables as a JSON object")
+    p.add_argument("--synchronous", action="store_true", default=True,
+                   help="wait for the flow to finish (default)")
+    p.add_argument("--no-synchronous", dest="synchronous", action="store_false",
+                   help="fire and forget")
+    p.add_argument("--timeout", type=int, default=120,
+                   help="synchronous wait, seconds (default 120)")
+
+
+ACTIONS = {
+    "run-form-with-files": ActionDef(
+        func=run_form_with_files, add_args=_args, needs_client=True,
+        description="Submit a form the way a browser does: publish -> upload files -> "
+                    "launch -> read variables, through the public FormProcess endpoints. "
+                    "Proves the form's own input/output maps carry values.",
+    ),
+}

procesio_cli/tools/procesio/handlers/generic.py

@@ -0,0 +1,135 @@
+"""Generic, full-coverage actions.
+
+`request` reaches ANY of the ~247 documented Web-API endpoints, so the tool
+covers the whole API surface even where there is no curated wrapper.
+`list-endpoints` browses the bundled Swagger-derived index to discover paths.
+"""
+from __future__ import annotations
+
+import argparse
+
+from tools.procesio import swagger
+from tools.procesio.actiondef import ActionDef
+from tools.procesio.client import parse_json_arg
+from tools.procesio.errors import UsageError
+from tools.procesio.handlers.common import add_profile_arg
+from tools._lib.io import log
+
+_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE"]
+
+
+def _unmangle_path(path: str) -> tuple[str, str | None]:
+    """Recover a shell-mangled `--path` and return (clean_path, warning|None).
+
+    On Windows, Git Bash / MSYS rewrites a leading-slash argument the moment it
+    looks like a POSIX path: `--path /api/FormTemplate/{id}` reaches the tool as
+    `/C:/Program Files/Git/api/FormTemplate/{id}`, so the client builds
+    `…/C:/Program Files/Git/api/…` and the gateway answers 403 on the garbage
+    path. A real Web-API path starts with `/api/`, contains `/api/` exactly once,
+    and never contains a ':' — so when a ':' (a drive) shows up alongside an
+    `/api/`, the intended path is unambiguously the `/api/…` tail. We recover it
+    and warn (the fix is the caller's shell: pass `//api/…` or set
+    MSYS_NO_PATHCONV=1). Clean paths are returned untouched, so callers on
+    PowerShell/cmd are unaffected. A stray leading `//` (the `//api/…` MSYS
+    workaround) is also collapsed to a single slash.
+    """
+    p = path
+    warn = None
+    low = p.lower()
+    if ":" in p and "/api/" in low:
+        tail = p[low.index("/api/"):]
+        warn = (f"--path looked shell-mangled ({path!r}); recovered {tail!r}. "
+                "Your shell (Git Bash/MSYS) rewrote the leading slash — pass "
+                "'//api/...' or set MSYS_NO_PATHCONV=1 to prevent this.")
+        p = tail
+    if p.startswith("//"):
+        p = p[1:]
+    return p, warn
+
+
+def _request_args(p: argparse.ArgumentParser) -> None:
+    add_profile_arg(p)
+    p.add_argument("--method", default="GET",
+                   help="HTTP method (GET/POST/PUT/PATCH/DELETE). Default GET.")
+    p.add_argument("--path", required=True,
+                   help="endpoint path, e.g. /api/Projects or /api/Projects/{id}")
+    p.add_argument("--query", help="query params as a JSON object")
+    p.add_argument("--query-file", dest="query_file",
+                   help="path to a UTF-8 JSON file for the query params "
+                        "(use instead of --query to avoid shell JSON-quoting issues)")
+    p.add_argument("--body", help="request body as JSON (object or array)")
+    p.add_argument("--body-file", dest="body_file",
+                   help="path to a UTF-8 JSON file for the request body "
+                        "(use instead of --body for large payloads like full flow DTOs)")
+
+
+def request(client, args) -> dict:
+    method = (args.method or "GET").upper()
+    if method not in _METHODS:
+        raise UsageError(f"--method must be one of {', '.join(_METHODS)}")
+    query_file = getattr(args, "query_file", None)
+    if query_file:
+        if args.query:
+            raise UsageError("pass either --query or --query-file, not both")
+        import json as _json
+        from pathlib import Path as _Path
+        try:
+            query = _json.loads(_Path(query_file).read_text(encoding="utf-8"))
+        except (OSError, ValueError) as e:
+            raise UsageError(f"--query-file could not be read as JSON: {e}") from e
+    else:
+        query = parse_json_arg(args.query, "query")
+    if query is not None and not isinstance(query, dict):
+        raise UsageError("--query must be a JSON object")
+    body_file = getattr(args, "body_file", None)
+    if body_file:
+        if args.body:
+            raise UsageError("pass either --body or --body-file, not both")
+        import json as _json
+        from pathlib import Path as _Path
+        try:
+            body = _json.loads(_Path(body_file).read_text(encoding="utf-8"))
+        except (OSError, ValueError) as e:
+            raise UsageError(f"--body-file could not be read as JSON: {e}") from e
+    else:
+        body = parse_json_arg(args.body, "body")
+    path, warn = _unmangle_path(args.path)
+    if warn:
+        log(warn)
+    result = client.request(method, path, query=query, body=body)
+    return {"method": method, "path": path, "result": result}
+
+
+def _list_args(p: argparse.ArgumentParser) -> None:
+    p.add_argument("--filter", help="substring match on path/tag/summary")
+    p.add_argument("--tag", help="exact tag filter, e.g. ProcessTemplate")
+    p.add_argument("--method", help="filter by HTTP method")
+    p.add_argument("--tags-only", action="store_true",
+                   help="just list the available tags + counts")
+
+
+def list_endpoints(args) -> dict:
+    if args.tags_only:
+        counts: dict[str, int] = {}
+        for e in swagger.all_endpoints():
+            counts[e["tag"]] = counts.get(e["tag"], 0) + 1
+        return {"meta": swagger.meta(),
+                "tags": [{"tag": t, "count": counts[t]} for t in sorted(counts)]}
+    found = swagger.find(args.filter, args.tag, args.method)
+    return {
+        "meta": swagger.meta(),
+        "count": len(found),
+        "endpoints": found,
+    }
+
+
+ACTIONS = {
+    "request": ActionDef(
+        func=request, add_args=_request_args, needs_client=True,
+        description="Call ANY Web-API endpoint: --method --path [--query JSON] [--body JSON].",
+    ),
+    "list-endpoints": ActionDef(
+        func=list_endpoints, add_args=_list_args,
+        description="Browse the bundled Swagger index of all PROCESIO endpoints.",
+    ),
+}