procesio-cli 0.1.1__py3-none-any.whl

procesio_cli/tools/procesio/dto/__init__.py

@@ -0,0 +1,13 @@
+"""PROCESIO DTO sub-tools.
+
+Deterministic, reusable builders that turn a small validated `config` into a full
+PROCESIO DTO by merging it onto a captured golden template, then create/edit the
+resource over the Web API. See DTO-SUBTOOLS-NOTE.md for the design.
+
+Layout per component: tools/procesio/dto/<component>/
+  description.md       - what it is / when to use / gotchas
+  config.schema.json   - the JSON Schema the (LLM-produced) config must satisfy
+  template.dto.json    - a real captured golden DTO with placeholders
+  builder.py           - PURE config -> DTO (no I/O); + a Component spec
+  fixtures/            - golden config->DTO pairs (regression) + drift captures
+"""

procesio_cli/tools/procesio/dto/credential/builder.py

@@ -0,0 +1,179 @@
+"""Credential builder — PURE config -> CredentialsDto.
+
+A credential instance is a saved set of property values for a credential template
+(connection type). The builder resolves the template (gtid/gtpid + property ids,
+fetched live in prepare_ctx) and maps config `properties: {label: value}` to
+`properties: [{id, value}]`. Select/radio option *names* are resolved to their
+option value (guid) automatically.
+
+API (verified live 2026-06-24):
+  - Create: POST /api/Credentials {gtid, gtpid, name, properties[]} -> {id}
+  - Get:    GET  /api/Credentials/{id}
+  - Edit:   PUT  /api/Credentials {gid: id, ...}
+  - Validate@source: POST /api/Credentials/test (live connection probe)
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+from tools.procesio.dto.framework import Component
+from tools.procesio.errors import UsageError
+
+DIR = Path(__file__).resolve().parent
+
+
+def _property_index(template: dict) -> dict:
+    out: dict[str, dict] = {}
+    for p in template.get("properties") or []:
+        if p.get("label"):
+            out.setdefault(p["label"].strip().lower(), p)
+        if p.get("id"):
+            out[p["id"]] = p
+    return out
+
+
+_GUIDISH = 32          # a guid without dashes is 32 hex chars; with dashes, 36
+
+
+def _looks_guid(v) -> bool:
+    s = str(v or "").strip()
+    return len(s) >= _GUIDISH and s.count("-") >= 4
+
+
+def _resolve_option(prop: dict, value):
+    """Map an option property's value to the option **guid** the engine expects.
+
+    Accepts the option `name` ("GET"), its `be_value` ("Get"), or the guid itself.
+
+    RAISES on an unmatched value when the property's options are guid-valued. This
+    is deliberate: PROCESIO stores whatever string you send, the credential saves
+    fine, and then EVERY Call API run using it dies at runtime with
+    ``Error while building input model: Unrecognized Guid format.`` — blamed on the
+    Call API action, not the credential, which sends you hunting in the wrong place.
+    (Cost hours on 2026-07-30 with ``"Method": "POST"``; POST is not even an option —
+    the credential Method is only used by the /test probe, Call API carries its own
+    Verb.) Non-guid option sets (checkbox-style "true"/"false") still pass through,
+    so nothing that worked before breaks.
+    """
+    opts = prop.get("options")
+    if not (isinstance(opts, list) and opts) or not isinstance(value, str):
+        return value
+    want = value.strip().lower()
+    for key in ("name", "be_value", "value"):
+        for o in opts:
+            if str(o.get(key, "")).strip().lower() == want:
+                return o.get("value")
+    if any(_looks_guid(o.get("value")) for o in opts):
+        allowed = [o.get("name") for o in opts if o.get("name")]
+        raise UsageError(
+            f"credential property {prop.get('label')!r}: {value!r} is not one of its "
+            f"options {allowed}. This property is an option list valued by GUID — "
+            f"sending a raw string saves fine but makes every Call API run using this "
+            f"credential fail at runtime with 'Unrecognized Guid format'. Pass an "
+            f"option name (or its guid). Note: a REST credential's 'Method' is only "
+            f"used by the connection test; the Call API action carries its own 'Verb'."
+        )
+    return value
+
+
+def build(config: dict, ctx: dict) -> dict:
+    template = ctx.get("template")
+    if not template:
+        raise UsageError("credential build needs the resolved template in ctx "
+                         "(prepare_ctx fetches /api/Credentials/types)")
+    pidx = _property_index(template)
+    props = []
+    for label, value in (config.get("properties") or {}).items():
+        prop = pidx.get(str(label).strip().lower()) or pidx.get(label)
+        if not prop:
+            known = sorted({p["label"] for p in template.get("properties") or [] if p.get("label")})
+            raise UsageError(f"credential template {template.get('name')!r} has no "
+                             f"property {label!r}; known: {known}")
+        props.append({"id": prop["id"], "value": _resolve_option(prop, value)})
+    dto = {
+        "gid": config.get("id"),
+        "gtid": template.get("gid"),
+        "gtpid": template.get("pid"),
+        "name": config["name"],
+        "tname": template.get("name"),
+        "type": template.get("type"),
+        # status is the "validated" flag in the manager list. prepare_ctx runs the
+        # /test probe and sets ctx["validated"] so a passing credential persists as
+        # validated (functionally identical to not-validated, but cleaner).
+        "status": bool(ctx.get("validated", False)),
+        "description": config.get("description", ""),
+        "properties": props,
+    }
+    return dto
+
+
+def _test_ok(res) -> bool:
+    """Did POST /api/Credentials/test succeed? Response: {isSuccess, statusCode, ...}."""
+    if not isinstance(res, dict):
+        return False
+    if str(res.get("isSuccess")).strip().lower() == "true":
+        return True
+    try:
+        return 200 <= int(res.get("statusCode")) < 300
+    except (TypeError, ValueError):
+        return False
+
+
+def prepare_ctx(client, config: dict) -> dict:
+    """Resolve the named credential template to its full definition (gid/pid +
+    property ids/options) and run the /test probe so a passing credential is saved
+    as **validated** (set ctx["validated"]; build maps it to the status flag). The
+    test uses the credential's own `Test endpoint` / test-parameters — those are for
+    validation only and do NOT flow to the action, so the action still needs its own
+    request params."""
+    want = (config.get("template") or "").strip().lower()
+    if not want:
+        raise UsageError("config.template is required (a credential type name, e.g. 'REST API')")
+    types = client.get("/api/Credentials/types")
+    for t in types or []:
+        if (t.get("name") or "").strip().lower() == want:
+            validated = False
+            try:                                  # probe so it can persist as validated
+                res = client.post("/api/Credentials/test", build(config, {"template": t}))
+                validated = _test_ok(res)
+            except Exception:  # noqa: BLE001 - never block a create on the probe
+                validated = False
+            return {"template": t, "validated": validated}
+    names = sorted((t.get("name") or "") for t in (types or []))
+    raise UsageError(f"unknown credential template {config.get('template')!r}; known: {names}")
+
+
+def _extract_id(resp, dto):
+    if isinstance(resp, dict):
+        return resp.get("id") or resp.get("Id") or resp.get("gid")
+    return None
+
+
+def _validate(client, dto, ctx):
+    """POST /api/Credentials/test — a live connection probe. Returns the raw
+    result; shape is server-defined."""
+    try:
+        res = client.post("/api/Credentials/test", dto)
+        return {"tested": True, "result": res}
+    except Exception as e:  # noqa: BLE001 - report, don't abort the create
+        return {"tested": False, "error": str(e)[:300]}
+
+
+def _edit(client, resource_id, config, ctx):
+    dto = build({**config, "id": resource_id}, ctx)
+    client.put("/api/Credentials", dto)
+    return client.get(f"/api/Credentials/{resource_id}")
+
+
+COMPONENT = Component(
+    name="credential",
+    description="PROCESIO credential instance: saved values for a connection template.",
+    dir=DIR,
+    build=build,
+    create_endpoint=("POST", "/api/Credentials"),
+    get_path="/api/Credentials/{id}",
+    extract_id=_extract_id,
+    prepare_ctx=prepare_ctx,
+    validate=_validate,
+    edit=_edit,
+)

procesio_cli/tools/procesio/dto/credential/config.schema.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "PROCESIO Credential config",
+  "description": "Create/edit a credential instance for a connection template. 'template' is the type name (e.g. 'REST API', 'Outbound e-mail (SMTP)', 'SQL'); 'properties' maps property labels to values (select/radio option NAMES are accepted and resolved to their value).",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["template", "name", "properties"],
+  "properties": {
+    "template": {"type": "string", "minLength": 1, "description": "credential template/type name"},
+    "name": {"type": "string", "minLength": 1, "description": "instance name"},
+    "description": {"type": "string"},
+    "properties": {
+      "type": "object",
+      "description": "property label (or id) -> value (secrets included here). A value may be an array (e.g. an OAuth2 'Scopes' pills list) or object for structured properties.",
+      "minProperties": 1,
+      "additionalProperties": {"type": ["string", "number", "boolean", "null", "array", "object"]}
+    }
+  }
+}

procesio_cli/tools/procesio/dto/credential/description.md

@@ -0,0 +1,193 @@
+# Credential sub-tool
+
+Create/edit a PROCESIO **credential instance** — saved values for a connection
+template (REST API, SMTP, SQL, SFTP, OAuth2 services, …). Actions reference a
+credential by its instance id.
+
+## Config
+
+```json
+{
+  "template": "REST API",
+  "name": "GitHub public",
+  "description": "no-auth REST",
+  "properties": {
+    "URL": "https://api.github.com",
+    "Authentication method": "No authentication",
+    "Method": "GET",
+    "Test endpoint": "/zen"
+  }
+}
+```
+
+- **template** — the connection type **name** (from `GET /api/Credentials/types`;
+  e.g. `REST API`, `Outbound e-mail (SMTP)`, `SQL`, `SFTP`).
+- **properties** — property **label** (or id) → value. Secret values (passwords,
+  keys) go here. For `select`/`radio` properties you may pass the option **name**
+  (e.g. `"No authentication"`, `"GET"`) — it is resolved to the option's value.
+
+## Database credentials — SQL Server, MySQL, and Redis
+
+The DB credential type (named **`SQL`** in the live catalog) is now multi-engine: the
+platform added `DbClientType.MYSQL = 2` alongside `MSSQL = 1` (Web-Api / Process-Execution
+`CustomMySQLClient`, PRC-3696), so the SAME credential template creates a **MySQL**
+connection by choosing the **"Server Type"** option `MySQL` (live-confirmed option value
+`40404040-0001-0001-0002-cccccccccccc`; MSSQL is `…-0001-…`). No new tool code — the builder
+resolves the option name to its guid like any other select property. The DB actions
+(**Execute Query** / **Execute Command**, GUIDs `76470756-…` / `a1625da6-…`; the newer V2 variants add a Timeout + Parameters tab) then run against it
+unchanged, and the credential's Test button opens a real `MySqlConnection`. Live property
+labels on the `SQL` type: Server Type, Protocol Type, Server Name, Port Number, Database
+Name, Encrypt, Pooling, Trust Server Certificate, Authentication Type, Username, Password.
+
+```json
+{
+  "template": "SQL",
+  "name": "reporting-mysql",
+  "properties": {
+    "Server Type": "MySQL",
+    "Server Name": "db.internal",
+    "Port Number": "3306",
+    "Database Name": "reporting",
+    "Username": "svc_report",
+    "Password": "<secret>"
+  }
+}
+```
+
+**Redis** is its own standalone credential type — `CredentialsType.REDIS = 9`, NOT a
+`DbClientType`/SQL sub-type (Web-Api #1452 / Action-Core #130 / Process-Execution #250).
+Set `template` to `Redis` and pass its properties: **Host** (req; bare host/IP), **Port**
+(6379), **Username**, **Password**, **Database** (0), **UseTls** (false),
+**ValidateCertificate** (true), **ConnectTimeoutSeconds** (5), **CommandTimeoutSeconds** (5;
+both >0, ≤300). Its process action is **"Redis Connector"** (pick Operation family →
+Operation; 19 typed ops across Key/String, Expiration, Hash, List, Set/SortedSet, Pub/Sub;
+outputs Response / Found / AffectedCount; no raw-command execution). Template GUID referenced
+by the connector: `80808080-0001-0000-0000-aaaaaaaaaaaa`.
+
+> ⚠ **Redis shipped to prod but is not yet activated** — its credential template is not
+> seeded in DataBase-Update, so `Redis` does not yet appear in `GET /api/Credentials/types`
+> (only 34 types today; MySQL via `SQL` is live). The contract above is stable and will
+> work as-is once activated; until then a Redis credential cannot be created. Verify with
+> the property/option names before relying on the literals above. Still not activated at
+> the v3.0.0 release (2026-10-21). (Outbound DB hosts are
+> also SSRF-guarded by a host blacklist — `DbHostBlacklistChecker` — so a blacklisted /
+> private host is rejected at connect time.)
+
+**Prelude** ships as a REST-derived credential - `template: "REST API/ Prelude"`, Bearer
+token, base `https://platform.prelude.so`, driving the Prelude connector (phone
+verification + lookup). It IS live in `GET /api/Credentials/types` (verified 2026-09-21,
+35 types). See `PROCESIO-CONNECTORS-NOTES.md`.
+
+**Azure Storage Account** is a standalone ROOT credential type since v3.0.0 (2026-10):
+`CredentialsType.AZURE_STORAGE = 10`, template name `Azure Storage Account`, live in
+`GET /api/Credentials/types`. It drives the **Azure Storage** connector (id
+`83838383-0000-0000-0000-aaaaaaaaaaaa`). Fields (`be_id`):
+
+| be_id | Notes |
+| --- | --- |
+| `AuthenticationType` | radio; the option values are GUIDs, their `be_value`s are `SharedKey` / `ServicePrincipal` |
+| `AccountName` | |
+| `AccountKey` | secret |
+| `TenantId` | |
+| `ClientId` | |
+| `ClientSecret` | secret |
+| `BlobEndpoint` | |
+
+Resolve the `AuthenticationType` option from the live template rather than hardcoding its
+GUID, and send only the fields the chosen method needs (see the conditional-property gotcha
+below). Do not confuse it with the older derived template **"OAuth2 (REST API) / Azure
+Storage"** (`REST_API_OAUTH_PREDEFINED`), which is an OAuth2 REST credential, not this root type.
+
+> ⚠ **A credential read returns its secrets in plaintext (PRC-5556):** `credential-get`
+> and the read API hand back stored secret values, not a masked placeholder. Never log,
+> print, or echo a fetched credential, and never write one to a file the secret scanner
+> then flags. Treat the whole object as sensitive.
+
+## API contract (verified live 2026-06-24)
+
+- **Validate@source:** `POST /api/Credentials/test` — a **live connection probe**
+  (e.g. a real GET for REST). Run via `--dry-run` (returns the built DTO + test
+  result) or automatically on create.
+- **Create:** `POST /api/Credentials` (`CredentialsDto {gtid, gtpid, name, properties[]}`)
+  → `{ "id": "<gid>" }`.
+- **Get:** `GET /api/Credentials/{id}`.
+- **Edit:** `PUT /api/Credentials` with `gid = id`.
+- **Delete:** `DELETE /api/Credentials/{id}`.
+
+## Validated status (auto)
+
+The credential list shows **validated** / **not validated** (the DTO `status` flag).
+On create/edit the builder runs `POST /api/Credentials/test`; if it returns
+`isSuccess`/2xx, the credential is saved as **validated** (`status:true`). A
+not-validated credential is functionally identical — this is cosmetic. To make a
+credential validate, give it whatever its connection type needs to probe: for REST,
+set `Method` and a `Test endpoint` (e.g. `"?cx=...&q=..."`); for SMTP the connection
+probe alone suffices. **These test parameters are for validation only — they do NOT
+flow into the action**, so the action still needs its own request params (e.g. Call
+API's `Request Parameters` queryParams).
+
+## Using a credential in a process
+
+A credentials-type action property (e.g. Call API's "Select REST API credentials")
+is bound by passing the credential **id** as the param value:
+`"Select REST API credentials": "<credential id>"`.
+
+## Gotchas
+
+- `gtid`/`gtpid` are stable per template; the builder reads them from the live
+  template so it never hardcodes ids.
+- A credential type resolves to its ROOT template (changed in v3.0.0, 2026-10). Before, a
+  derived template that kept its parent's `Type` (the `REST API/ Prelude` template, for one)
+  made every custom-action upload whose action had a `Credentials_Rest` property fail with
+  `TEMPLATE_ERROR`. A derived template and its root now report the same root type.
+- Some required properties are *conditional* (depend on a radio choice, e.g.
+  Basic-auth fields only matter when Basic auth is selected) — send only what your
+  chosen path needs.
+
+## Editing an existing credential — what a partial `--config` silently costs
+
+`credential-edit` builds a **whole** DTO from the config you pass; it does not
+merge with what is on the server. Everything you leave out is re-derived or
+sent empty, so an edit meant to change one field can quietly move several.
+
+- **Unconditionally-required properties must be re-sent even when you are not
+  changing them.** Omitting one fails the PUT with
+  `{"statusCode": 113, "value": "Required credentials fields should not be
+  empty.", "target": "<Property Label>"}`. The 400 names the property, so read
+  `target` rather than guessing. For REST API that is at least `Method`; a
+  credential that carries a test probe also needs its `Test endpoint`.
+- **Re-send the current value of every property you want left alone**, read
+  from `credential-get` — not typed from a console display. A value copied out
+  of terminal output is truncated at the terminal width, and the edit then
+  shortens the stored field to whatever fitted on screen. A description silently
+  went from 183 characters to 88 this way. Read the field, pass the field.
+- **`status` cannot be pinned.** The config schema refuses the key outright
+  (`Additional properties are not allowed ('status' was unexpected)`), because
+  it is not a setting: it is the manager list's *validated* flag, recomputed on
+  every create/edit from the `POST /api/Credentials/test` probe. Expect it to
+  move on any edit and report it rather than claiming the field held still.
+- **The validated flag proves only what the test endpoint proves.** If the
+  credential's `Test endpoint` points at an unauthenticated route, the probe
+  passes with no credentials at all and *validated* says nothing about whether
+  the auth material works. Only a real call through the action does.
+- **Collapsable properties come back with different scaffolding after an edit.**
+  The server starts emitting a `be_id` per sub-field and stops emitting
+  `configurations`/`pill`, and it drops blank placeholder rows from table
+  properties. None of that is a value change. When diffing a before/after
+  export, reduce each property to its `{sub-field id -> value}` leaves — do not
+  compare the raw blobs (five phantom differences) and do not skip the
+  properties (a real change would hide).
+- **⚠ The tool's response echoes secret-bearing property values back**, in both
+  the dry-run DTO and the edit result. Never log, capture or persist that
+  stdout. Build the config in-process from the credential store and parse the
+  response rather than printing it.
+
+## No Bearer option in the REST API template
+
+The authentication selector offers `NoAuth`, `BasicAuth`, `ApiKey`, `OAuth2`
+and `Certificate` — there is **no Bearer**. To send `Authorization: Bearer
+<token>`, choose API key authentication and set `Key` = `Authorization`,
+`Value` = `Bearer <token>`, with the `Header` checkbox true (it routes the pair
+to a header rather than a query parameter). The auth method must be given as the
+option **name** (`"API key authentication"`), not its `be_value`; a raw string
+saves but fails at runtime with `Unrecognized Guid format`.

procesio_cli/tools/procesio/dto/credential/fixtures/rest.config.json

@@ -0,0 +1,11 @@
+{
+  "template": "REST API",
+  "name": "GitHub",
+  "description": "public",
+  "properties": {
+    "URL": "https://api.github.com",
+    "Authentication method": "No authentication",
+    "Method": "GET",
+    "Test endpoint": "/zen"
+  }
+}

procesio_cli/tools/procesio/dto/credential/fixtures/rest.dto.json

@@ -0,0 +1,28 @@
+{
+  "gid": null,
+  "gtid": "10101010-0001-0000-0000-aaaaaaaaaaaa",
+  "gtpid": "10101010-0001-0000-0000-aaaaaaaaaaaa",
+  "name": "GitHub",
+  "tname": "REST API",
+  "type": "rest",
+  "status": false,
+  "description": "public",
+  "properties": [
+    {
+      "id": "p-url",
+      "value": "https://api.github.com"
+    },
+    {
+      "id": "p-auth",
+      "value": "opt-noauth"
+    },
+    {
+      "id": "p-method",
+      "value": "opt-get"
+    },
+    {
+      "id": "p-test",
+      "value": "/zen"
+    }
+  ]
+}

procesio_cli/tools/procesio/dto/credential/fixtures/rest.template.json

@@ -0,0 +1,44 @@
+{
+  "name": "REST API",
+  "gid": "10101010-0001-0000-0000-aaaaaaaaaaaa",
+  "pid": "10101010-0001-0000-0000-aaaaaaaaaaaa",
+  "type": "rest",
+  "properties": [
+    {
+      "id": "p-url",
+      "label": "URL",
+      "type": "text"
+    },
+    {
+      "id": "p-auth",
+      "label": "Authentication method",
+      "type": "radio",
+      "options": [
+        {
+          "name": "No authentication",
+          "value": "opt-noauth"
+        },
+        {
+          "name": "Basic authentication",
+          "value": "opt-basic"
+        }
+      ]
+    },
+    {
+      "id": "p-method",
+      "label": "Method",
+      "type": "select",
+      "options": [
+        {
+          "name": "GET",
+          "value": "opt-get"
+        }
+      ]
+    },
+    {
+      "id": "p-test",
+      "label": "Test endpoint",
+      "type": "text"
+    }
+  ]
+}

procesio_cli/tools/procesio/dto/credential/template.dto.json

@@ -0,0 +1,16 @@
+{
+  "_note": "Golden CredentialsDto (POST /api/Credentials body). gtid=template gid, gtpid=template pid (both stable per connection type, from GET /api/Credentials/types). properties[] = {id, value} where id is a template property id and value is the entered value (secrets live here; select/radio values are the option's guid). gid is null on create (server assigns) / the instance id on edit. Verified live 2026-06-24: created a REST API credential, POST /api/Credentials/test returned a live 200.",
+  "gid": null,
+  "gtid": "10101010-0001-0000-0000-aaaaaaaaaaaa",
+  "gtpid": "10101010-0001-0000-0000-aaaaaaaaaaaa",
+  "name": "<name>",
+  "tname": "REST API",
+  "type": null,
+  "status": false,
+  "description": "",
+  "properties": [
+    {"id": "10101010-0001-0001-0000-bbbbbbbbbbbb", "value": "<URL>"},
+    {"id": "10101010-0001-0004-0000-bbbbbbbbbbbb", "value": "<auth method option guid>"},
+    {"id": "10101010-0001-0002-0000-bbbbbbbbbbbb", "value": "<method option guid>"}
+  ]
+}

procesio_cli/tools/procesio/dto/data/_refresh.py

@@ -0,0 +1,147 @@
+"""Refresh `action_catalog.json` from a live PROCESIO workspace.
+
+The bundle is the process builder's OFFLINE default: `prepare_ctx` tries the live
+workspace catalog first and falls back here when that fetch is slow or fails. A
+stale bundle therefore does not fail loudly - it fails as
+`unknown action '<name>' - not in the action catalog` for any action the platform
+has gained since the bundle was taken, and only when the live fetch also misses
+its deadline. That is a confusing pair of symptoms for one cause, which is why
+this script exists rather than the bundle being hand-edited.
+
+`action_catalog.json`'s own note has referred to this file since 24/06/2026; it
+was not actually present until a build needed the `Data Store` action and found
+the bundle 1 action behind.
+
+    python _refresh.py --profile <name> --workspace-id <guid>          # report
+    python _refresh.py --profile <name> --workspace-id <guid> --write  # apply
+
+ADDITIVE BY DEFAULT. `--write` adds actions the bundle is missing and leaves
+existing entries alone, because an in-place replacement of an action whose shape
+has changed would silently alter every process the builder emits. Pass
+`--replace-existing` to take the live definition for actions that are already
+present, and diff the result before committing it.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+HERE = Path(__file__).resolve().parent
+BUNDLE = HERE / "action_catalog.json"
+AAT = HERE.parents[3]
+
+
+def fetch_live(profile: str, workspace_id: str, timeout: int = 300) -> list:
+    """`GET /api/Actions?getFullAction=true` through the registered tool.
+
+    That endpoint serialises every action's full configuration tree and is
+    occasionally very slow while the rest of the API stays sub-second, so this
+    runs with a generous timeout - it is a maintenance script, not a hot path."""
+    cmd = [sys.executable, str(AAT / "scripts" / "run-tool.py"), "procesio",
+           "request", "--method", "GET", "--path", "/api/Actions?getFullAction=true",
+           "--profile", profile, "--workspace-id", workspace_id]
+    proc = subprocess.run(cmd, capture_output=True, text=True, encoding="utf-8",
+                          cwd=str(AAT), timeout=timeout)
+    body = json.loads(proc.stdout.strip() or "{}")
+    if "error" in body:
+        raise SystemExit(f"fetch failed: {json.dumps(body['error'])}")
+    res = body.get("result") or body
+    acts = res.get("actions") if isinstance(res, dict) else res
+    if not acts:
+        raise SystemExit("live catalog returned no actions")
+    return acts
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__.split("\n")[0])
+    ap.add_argument("--profile", required=True)
+    ap.add_argument("--workspace-id", required=True)
+    ap.add_argument("--write", action="store_true",
+                    help="apply the change; without it, only report")
+    ap.add_argument("--replace-existing", action="store_true",
+                    help="also take the live definition for actions already "
+                         "bundled (diff the result before committing)")
+    ap.add_argument("--procesio-only", action="store_true",
+                    help="keep only platform actions (isProcesioAction=true) "
+                         "from the live catalog, so a workspace's own custom / "
+                         "connector actions never leak into the offline bundle. "
+                         "Use this whenever the refresh runs against a real "
+                         "workspace, which the bundle is not meant to mirror.")
+    a = ap.parse_args()
+
+    bundle = json.loads(BUNDLE.read_text(encoding="utf-8"))
+    live = fetch_live(a.profile, a.workspace_id)
+    if a.procesio_only:
+        live = [x for x in live if x.get("isProcesioAction")]
+
+    # Project every live action to the bundle's canonical key set (the union of keys
+    # already in the bundle) BEFORE comparing or storing. The live API attaches volatile,
+    # workspace-specific fields (workspaceId, createdBy/updatedBy, *On timestamps, etc.)
+    # that must never enter a portable, checked-in snapshot; stripping them also makes
+    # `--replace-existing` flag only REAL config changes instead of timestamp churn.
+    from collections import Counter
+    _kc = Counter(k for x in bundle["actions"] for k in x.keys())
+    _n = len(bundle["actions"])
+    # Canonical keys appear in most actions; a volatile field (or one a few polluted
+    # entries carry) appears in a minority, so a majority threshold keeps the portable
+    # shape without hardcoding a blacklist that a new volatile field could slip past.
+    keep = {k for k, c in _kc.items() if c > _n / 2} if _n else None
+
+    def canon(act):
+        return {k: v for k, v in act.items() if k in keep} if keep else act
+
+    # First position per name — the bundle may carry duplicate names, so replace by
+    # recorded index (identity-based .index() blew up on a duplicated action).
+    pos = {}
+    for i, x in enumerate(bundle["actions"]):
+        nm = x.get("name")
+        if nm and nm not in pos:
+            pos[nm] = i
+    name_counts = Counter(x.get("name") for x in bundle["actions"])
+    by_name = {x.get("name"): x for x in bundle["actions"] if x.get("name")}
+    added, replaced, skipped_ambiguous = [], [], []
+    for act in live:
+        name = act.get("name")
+        if not name:
+            continue
+        act = canon(act)
+        if name not in by_name:
+            added.append(name)
+            pos[name] = len(bundle["actions"])
+            bundle["actions"].append(act)
+            by_name[name] = act
+        elif a.replace_existing and by_name[name] != act:
+            # A name that occurs more than once (e.g. an action shipped in two versions
+            # under one display name) cannot be targeted safely by name — replacing would
+            # collapse both onto one live definition. Skip and report it; fix those by id.
+            if name_counts[name] > 1:
+                if name not in skipped_ambiguous:
+                    skipped_ambiguous.append(name)
+                continue
+            replaced.append(name)
+            bundle["actions"][pos[name]] = act
+            by_name[name] = act
+
+    missing_live = sorted(n for n in by_name if n not in {x.get("name") for x in live})
+
+    report = {"bundled_before": len(by_name), "live": len(live),
+              "added": sorted(added), "replaced": sorted(replaced),
+              "skipped_ambiguous_names": sorted(skipped_ambiguous),
+              "in_bundle_but_not_live": missing_live,
+              "written": False}
+    if a.write and (added or replaced):
+        # LF on purpose: the tree is LF (.gitattributes), and a bare write_text on Windows
+        # would turn every line into CRLF and bury the real change in EOL churn.
+        BUNDLE.write_text(json.dumps(bundle, indent=1, ensure_ascii=False),
+                          encoding="utf-8", newline="\n")
+        report["written"] = True
+        report["bundled_after"] = len(bundle["actions"])
+    print(json.dumps(report, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())