procesio-cli 0.1.1__py3-none-any.whl

procesio_cli/tools/procesio/handlers/environment_admin.py

@@ -0,0 +1,146 @@
+"""Environment-management actions (no HTTP - they only touch the local registry).
+
+A PROCESIO environment is one installation, named `<Client>-<ENV>`, carrying the
+host URLs it lives on (see environments.py). These actions let a user list the
+known environments, add a client-specific one, switch the default (the natural
+"I want to work on PROCESIO Internal-QA" gesture), and remove a user-defined one.
+
+Built-in Internal-PROD/QA/DEV always exist and are shared with every teammate;
+switching to one needs no setup beyond a credential bound to it.
+"""
+from __future__ import annotations
+
+import argparse
+
+from tools.procesio import environments, profiles
+from tools.procesio.actiondef import ActionDef
+
+
+def _creds_by_environment() -> dict[str, list[str]]:
+    """Credential names grouped by the environment they are bound to (unbound ->
+    Internal-PROD), so listings can show which environments are usable."""
+    out: dict[str, list[str]] = {}
+    for name in profiles.profile_names():
+        blob = profiles.get_profile(name)
+        env = blob.get("environment") or environments.DEFAULT_ENV_NAME
+        out.setdefault(env, []).append(name)
+    return out
+
+
+# -- list-environments ------------------------------------------------------
+
+def list_environments(_args) -> dict:
+    default = environments.get_default()
+    by_env = _creds_by_environment()
+    out = []
+    for name in sorted(environments.all_environments()):
+        env = environments.get(name)
+        out.append({
+            "name": name,
+            "client": env.get("client"),
+            "env": env.get("env"),
+            "builtin": bool(env.get("builtin")),
+            "is_default": (name == default),
+            "web_base": env.get("web_base"),
+            "app_base": env.get("app_base"),
+            "forms_base": env.get("forms_base"),
+            "credentials": by_env.get(name, []),
+        })
+    return {
+        "count": len(out),
+        "default_environment": default,
+        "environments": out,
+    }
+
+
+# -- add-environment --------------------------------------------------------
+
+def _add_args(p: argparse.ArgumentParser) -> None:
+    p.add_argument("--name", required=True,
+                   help="environment name, '<Client>-<ENV>' e.g. Acme-PROD")
+    p.add_argument("--web-base", dest="web_base", required=True,
+                   help="Web API host, e.g. https://webapi.acme.example")
+    p.add_argument("--app-base", dest="app_base", required=True,
+                   help="designer / front-end host, e.g. https://acme.example")
+    p.add_argument("--forms-base", dest="forms_base", required=True,
+                   help="public forms host, e.g. https://forms.acme.example")
+    p.add_argument("--auth-base", dest="auth_base",
+                   help="legacy auth host (optional; login uses the web host)")
+    p.add_argument("--client", help="client label (default: derived from the name)")
+    p.add_argument("--env", help="env label e.g. PROD/QA/DEV (default: derived from the name)")
+    p.add_argument("--make-default", dest="make_default", action="store_true",
+                   help="switch the default environment to this one")
+
+
+def add_environment(args) -> dict:
+    entry = environments.add(
+        args.name, web_base=args.web_base, app_base=args.app_base,
+        forms_base=args.forms_base, auth_base=args.auth_base,
+        client=args.client, env=args.env, make_default=args.make_default,
+    )
+    return {
+        "saved": True,
+        "environment": entry,
+        "default_environment": environments.get_default(),
+        "note": "environments are non-secret host URLs; bind a credential with "
+                "add-credential --environment " + entry["name"],
+    }
+
+
+# -- set-environment (switch the default) -----------------------------------
+
+def _name_arg(p: argparse.ArgumentParser) -> None:
+    p.add_argument("--name", required=True, help="environment name to switch to")
+
+
+def set_environment(args) -> dict:
+    canon = environments.set_default(args.name)
+    env = environments.get(canon)
+    creds = _creds_by_environment().get(canon, [])
+    return {
+        "default_environment": canon,
+        "web_base": env.get("web_base"),
+        "app_base": env.get("app_base"),
+        "forms_base": env.get("forms_base"),
+        "credentials": creds,
+        "note": ("no credential is bound to this environment yet — add one with "
+                 f"add-credential --environment {canon}") if not creds else
+                (f"using credential '{creds[0]}'" if len(creds) == 1 else
+                 "multiple credentials bound — pass --profile to pick one"),
+    }
+
+
+def remove_environment(args) -> dict:
+    environments.remove(args.name)
+    return {"removed": args.name, "default_environment": environments.get_default()}
+
+
+def show_environment(args) -> dict:
+    env = environments.get(args.name)
+    creds = _creds_by_environment().get(env["name"], [])
+    return {**env, "is_default": env["name"] == environments.get_default(),
+            "credentials": creds}
+
+
+ACTIONS = {
+    "list-environments": ActionDef(
+        func=list_environments,
+        description="List known PROCESIO environments (URLs, default, bound credentials).",
+    ),
+    "add-environment": ActionDef(
+        func=add_environment, add_args=_add_args,
+        description="Add a client environment (<Client>-<ENV> + its host URLs) to the registry.",
+    ),
+    "set-environment": ActionDef(
+        func=set_environment, add_args=_name_arg,
+        description="Switch the default environment (e.g. to Internal-QA); persists the choice.",
+    ),
+    "remove-environment": ActionDef(
+        func=remove_environment, add_args=_name_arg,
+        description="Remove a user-defined environment (built-in Internal-* cannot be removed).",
+    ),
+    "show-environment": ActionDef(
+        func=show_environment, add_args=_name_arg,
+        description="Show one environment's URLs, default flag, and bound credentials.",
+    ),
+}

procesio_cli/tools/procesio/handlers/fevalidate.py

@@ -0,0 +1,236 @@
+"""Front-end (designer-layer) process validation — live action + the save gate.
+
+This is the impure (client-facing) layer over flowmodel.fevalidation (pure). It:
+  * gathers the datatype catalog + subprocess-variable resolver from the live API,
+  * runs the pure FE validator (the designer "Process Errors" checks),
+  * exposes `process-fe-validate` (validate a live process by id),
+  * provides `pre_save_validate()` — the gate every process save runs: FE first, then
+    the BE validator (POST /api/Projects/validate), blocking the save on either unless
+    --force is passed.
+
+Why a gate: POST /api/Projects/validate only checks the RUNTIME layer and returns EMPTY
+even when the designer would REFUSE to save. Running the FE checks here means a
+tool-driven save is held to the SAME bar as a human clicking Save in the designer —
+without a conscious decision each time (CLAUDE.md: verify before done).
+"""
+from __future__ import annotations
+
+import argparse
+
+from tools.procesio.actiondef import ActionDef
+from tools.procesio.client import VARIABLES_ONLY
+from tools.procesio.errors import ProcesioAPIError, ValidationBlocked
+from tools.procesio.flowmodel import fevalidation as fv
+from tools.procesio.handlers.common import add_profile_arg
+
+_SUB_TEMPLATES = ("Call Subprocess", "Trigger Subprocess")
+
+
+# -- gather live context for the pure validator -------------------------------
+
+def _load_datatypes(client) -> list[dict]:
+    try:
+        r = client.get("/api/DataTypes", {"pageNumber": 1, "pageItemCount": 1000,
+                                          "includeProcesioEntries": True,
+                                          "includeExternalEntries": True})
+    except Exception:  # noqa: BLE001 - the type layer is best-effort / non-blocking
+        return []
+    items = r.get("pageItems") if isinstance(r, dict) else r
+    return items or []
+
+
+def _subprocess_resolver(client):
+    """target_vars_of(flow_id) -> {var_id: var_dict}, cached, network-tolerant."""
+    cache: dict = {}
+
+    def resolve(fid: str) -> dict:
+        if fid not in cache:
+            try:
+                r = client.get(f"/api/Projects/{fid}", VARIABLES_ONLY)
+                f = r.get("flow", r) if isinstance(r, dict) else r
+                cache[fid] = {v["id"]: v for v in (f.get("variables") or [])}
+            except Exception:  # noqa: BLE001 - unreadable target: can't assert its contract
+                cache[fid] = {}
+        return cache[fid]
+
+    return resolve
+
+
+def run_fe_validation(client, flow: dict, *, include_types: bool = True,
+                      with_datatypes: bool = True) -> dict:
+    """Run the pure FE validator against a flow DTO, gathering live context. Returns a
+    report: {clean, error_count, warning_count, errors, warnings}."""
+    flow = flow.get("flow", flow) if isinstance(flow, dict) else flow
+    datatypes = _load_datatypes(client) if (include_types and with_datatypes) else None
+    resolver = _subprocess_resolver(client)
+    all_w = fv.validate_flow(flow, datatypes=datatypes, target_vars_of=resolver,
+                             include_types=include_types)
+    all_w.extend(_flowlint_extras(client, flow, resolver))
+    errs, warns = fv.split_severity(all_w)
+    return {"clean": not errs, "error_count": len(errs), "warning_count": len(warns),
+            "errors": errs, "warnings": warns}
+
+
+# flow-lint (handlers/flowlint.py) covers three designer save-blockers that are NOT in the
+# FE reference file: a stale subprocess side-pannel id, an Execute-Query with a null/bad
+# Output, and Node code binding an error-scope/undeclared variable. Fold ONLY those unique
+# checks into the gate (the subprocess-mapping ones overlap fevalidation's checkSubprocess,
+# so they're excluded to avoid double-reporting). Best-effort: a flow-lint infra hiccup must
+# never break a legitimate save, so any failure yields no extra findings.
+_FLOWLINT_UNIQUE = {
+    "SIDEPANEL_ID", "EXECQUERY_NO_OUTPUT", "EXECQUERY_OUTPUT_UNDECLARED",
+    "EXECQUERY_OUTPUT_TYPE", "CODE_ERROR_SCOPE", "CODE_UNDECLARED", "missing_error_variable",
+}
+
+
+def _flowlint_extras(client, flow: dict, resolver) -> list[dict]:
+    try:
+        from tools.procesio.handlers import flowlint
+        tmpl_sp = flowlint._template_sidepanel_ids(client)
+        problems = flowlint.lint_flow_dto(flow, tmpl_sp, resolver)
+    except Exception:  # noqa: BLE001 - extras are best-effort; never block a save on them
+        return []
+    out: list[dict] = []
+    for p in problems:
+        if p.get("kind") not in _FLOWLINT_UNIQUE:
+            continue
+        name = p.get("action")
+        out.append({"severity": "error", "code": p["kind"], "text": p.get("detail", ""),
+                    "badges": [name] if name else [], "actionId": None, "action": name})
+    return out
+
+
+def run_be_validation(client, flow: dict) -> dict:
+    """Run PROCESIO's own validator (POST /api/Projects/validate). Empty 200 => valid."""
+    dto = flow.get("flow", flow) if isinstance(flow, dict) and "flow" in flow else flow
+    try:
+        res = client.post("/api/Projects/validate", dto)
+    except ProcesioAPIError as e:
+        det = e.details if isinstance(e.details, dict) else {"body": e.details}
+        return {"valid": False, "errors": det.get("body", det)}
+    empty = (not res) or (isinstance(res, dict)
+                          and list(res.keys()) == ["raw_text"] and not res["raw_text"])
+    if empty:
+        return {"valid": True, "errors": []}
+    errs = (res.get("errors") or res.get("validationErrors")) if isinstance(res, dict) else None
+    valid = res.get("isValid") if isinstance(res, dict) else None
+    return {"valid": valid if valid is not None else (not errs), "errors": errs, "result": res}
+
+
+# -- the save gate ------------------------------------------------------------
+
+def pre_save_validate(client, dto: dict, *, force: bool = False,
+                      include_types: bool = True) -> dict:
+    """Gate a process SAVE: FE (designer) validation first, then BE validation.
+
+    Returns a combined report {fe, be, blocked}. Raises ValidationBlocked when there are
+    blocking errors and force is False — so the caller (create/edit) aborts before the
+    POST/PUT. FE-warning-only (type-mismatch) never blocks. --force bypasses everything.
+    """
+    fe = run_fe_validation(client, dto, include_types=include_types)
+    be = run_be_validation(client, dto)
+    blocked = (not fe["clean"]) or (be.get("valid") is False)
+    report = {"fe": fe, "be": be, "blocked": blocked, "forced": bool(force)}
+    if blocked and not force:
+        n_fe = fe["error_count"]
+        n_be = len(be.get("errors") or []) if be.get("valid") is False else 0
+        raise ValidationBlocked(
+            f"Save blocked by validation: {n_fe} designer (front-end) error(s), "
+            f"{n_be} back-end error(s). Fix them, or pass --force to override.", report)
+    return report
+
+
+# -- the live action ----------------------------------------------------------
+
+def _args(p: argparse.ArgumentParser) -> None:
+    add_profile_arg(p)
+    p.add_argument("--id", required=True, help="process (project) id to validate")
+    p.add_argument("--no-types", dest="no_types", action="store_true",
+                   help="skip the advisory data-type-mismatch (warning) layer")
+    p.add_argument("--include-be", dest="include_be", action="store_true",
+                   help="also run the back-end validator (POST /api/Projects/validate)")
+
+
+def process_fe_validate(client, args) -> dict:
+    resp = client.get(f"/api/Projects/{args.id}")
+    flow = resp.get("flow", resp) if isinstance(resp, dict) else resp
+    fe = run_fe_validation(client, flow, include_types=not args.no_types)
+    out = {"id": args.id, "title": flow.get("title") or flow.get("Title"),
+           "clean": fe["clean"], "error_count": fe["error_count"],
+           "warning_count": fe["warning_count"],
+           "errors": fe["errors"], "warnings": fe["warnings"]}
+    if args.include_be:
+        out["backend"] = run_be_validation(client, flow)
+    return out
+
+
+ACTIONS = {
+    "process-fe-validate": ActionDef(
+        func=process_fe_validate, add_args=_args, needs_client=True,
+        description="Front-end (designer-layer) 'Process Errors' validation on a live "
+                    "process — the client-side check that BLOCKS designer Save but which "
+                    "POST /api/Projects/validate does NOT catch: unconnected actions, "
+                    "missing Start/Stop, empty node names, required-empty fields, leftover "
+                    "placeholders, bad number/integer values, out-of-range limits, "
+                    "duplicate/primitive-named variables, and unmapped required subprocess "
+                    "inputs. clean=true when no blocking errors. Data-type mismatches are "
+                    "reported as (non-blocking) warnings. This same check auto-runs before "
+                    "every process-create / process-edit. Add --include-be for the BE layer."),
+}
+
+
+# -- saving a fetched flow ----------------------------------------------------
+
+def arrange(flow: dict) -> tuple[dict, str]:
+    """The flow laid out with the default arrangement (classic engine + clustering).
+
+    Returns (flow, note). Layout only moves positions and frame sizes; if it fails on an
+    unusual graph the save goes ahead with the canvas as it was, and the note says so."""
+    from tools.procesio.layout import adapter
+    try:
+        res = adapter.layout_flow(flow, cluster=True)
+        return res["bundle"], "arranged"
+    except Exception as e:  # noqa: BLE001 - a layout problem must never block a save
+        return flow, f"not arranged ({type(e).__name__}: {e})"
+
+
+def save_flow(client, flow: dict, *, flow_id: str, valid: bool, layout: bool | None = None) -> dict:
+    """PUT a flow with its validity mark stamped to `valid`, and report what the server KEPT.
+
+    Two measured facts about the platform put this in one place rather than a bare PUT at
+    each call site. Both were established against the live API, not assumed:
+
+    * `isValid` is never computed by the back end. It stores whatever the PUT body
+      carries, and defaults it to TRUE when the body omits the field. So a writer that
+      passes a fetched flow straight through leaves a corrected process marked broken
+      for ever, and one that drops the field marks a broken process valid.
+    * The runtime validator (POST /api/Projects/validate) answers EMPTY - "valid" - for
+      flows the designer refuses to save, so `valid` has to carry the FE+BE verdict the
+      create/edit gate applies, never the runtime answer alone.
+
+    The mark is stamped, never blocked on. Saving a half-built process is deliberate
+    platform behaviour; the point of the mark is to say so truthfully.
+
+    The returned `isValid` is RE-READ after the PUT, because reporting the pre-save
+    measurement describes the flow that was sent rather than the one the platform kept,
+    and those two genuinely differ. A read-back that fails leaves it None with a note:
+    the PUT already landed, so failing the whole call here would misreport a save that
+    succeeded.
+    """
+    if layout is None:   # default: arrange on every save; PROCESIO_KEEP_LAYOUT=1 opts out
+        from tools.procesio.dto.process.builder import keep_layout_requested
+        layout = not keep_layout_requested()
+    note = "kept"
+    if layout:
+        flow, note = arrange(flow)
+    flow["isValid"] = bool(valid)
+    out: dict = {"stamped": bool(valid), "layout": note}
+    client.put("/api/Projects", flow)
+    try:
+        stored = client.get(f"/api/Projects/{flow_id}")
+        f = stored.get("flow", stored) if isinstance(stored, dict) else stored
+        out["isValid"] = f.get("isValid") if isinstance(f, dict) else None
+    except Exception as e:  # noqa: BLE001 - the PUT landed; only the read-back failed
+        out["isValid"] = None
+        out["readback_error"] = str(e)
+    return out

procesio_cli/tools/procesio/handlers/files.py

@@ -0,0 +1,141 @@
+"""Download a flow-instance file (e.g. a Generate-Document PDF output) to local disk.
+
+`GET /api/File/download` identifies the file by request **HEADERS** (HAR-verified),
+NOT query params — a query-only call returns NRE "Object reference not set":
+
+  uploadFilePath  the file DTO `path`
+                  (flow/flow-<flowId>/flow-instance-<instanceId>/variable-<varId>/<fileId>)
+  variableId      the output variable id
+  instanceId      the flow instance id
+  flowTemplateId  the process (flow template) id
+  workspaceId     the workspace
+
+Query: `?isArchived=false`. Returns raw bytes (`content-disposition: attachment`).
+See `tools/procesio/PROCESIO-API-NOTES.md`. JSON in / JSON out; impure (live client).
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import re
+from pathlib import Path
+from urllib.parse import unquote
+
+from tools.procesio.actiondef import ActionDef
+from tools.procesio.errors import ProcesioAPIError, UsageError
+from tools.procesio.handlers.common import add_profile_arg
+
+# flow/flow-<flowId>/flow-instance-<instanceId>/variable-<varId>/<fileId>
+_PATH_RE = re.compile(
+    r"flow-(?P<flow>[0-9a-fA-F-]{36})/"
+    r"flow-instance-(?P<instance>[0-9a-fA-F-]{36})/"
+    r"variable-(?P<variable>[0-9a-fA-F-]{36})/")
+
+
+def _ids_from_path(path: str) -> dict:
+    m = _PATH_RE.search(path or "")
+    return {"flow": m.group("flow"), "instance": m.group("instance"),
+            "variable": m.group("variable")} if m else {}
+
+
+def _filename_from_disposition(cd: str) -> str | None:
+    if not cd:
+        return None
+    m = re.search(r"filename\*=UTF-8''([^;]+)", cd)          # RFC 5987 form wins
+    if m:
+        return unquote(m.group(1)).strip().strip('"')
+    m = re.search(r'filename="?([^";]+)"?', cd)
+    return m.group(1).strip() if m else None
+
+
+def file_download(client, args) -> dict:
+    """Download one flow-instance file. Identify it either explicitly
+    (--file-path + --variable-id + --instance-id + --flow-template-id) or with
+    --from-run pointing at a run-process result JSON (the ids are derived from the
+    file DTO's `path` and the result's instanceId)."""
+    file_path = args.file_path
+    variable_id = args.variable_id
+    instance_id = args.instance_id
+    flow_template_id = args.flow_template_id
+    name = None
+
+    if args.from_run:
+        try:
+            data = json.loads(Path(args.from_run).read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError) as e:
+            raise UsageError(f"--from-run: cannot read JSON ({e})") from e
+        res = data.get("result", data) if isinstance(data, dict) else {}
+        variables = res.get("variable") or {}
+        if args.var:
+            picked = variables.get(args.var)
+            if not isinstance(picked, dict) or not picked.get("path"):
+                raise UsageError(f"--from-run: variable {args.var!r} is not a file in the run result")
+        else:
+            picked = next((v for v in variables.values()
+                           if isinstance(v, dict) and v.get("path")), None)
+            if picked is None:
+                raise UsageError("--from-run: no file variable (with a 'path') found in the run result")
+        ids = _ids_from_path(picked.get("path") or "")
+        file_path = file_path or picked.get("path")
+        name = picked.get("name")
+        flow_template_id = flow_template_id or ids.get("flow")
+        instance_id = instance_id or res.get("instanceId") or ids.get("instance")
+        variable_id = variable_id or ids.get("variable")
+
+    missing = [n for n, v in (("file-path", file_path), ("variable-id", variable_id),
+                              ("instance-id", instance_id), ("flow-template-id", flow_template_id))
+               if not v]
+    if missing:
+        raise UsageError("missing " + ", ".join("--" + m for m in missing)
+                         + " (or pass --from-run with a run-process result JSON)")
+
+    workspace_id = client.workspace_id or args.workspace_id
+    if not workspace_id:
+        raise UsageError("a workspace id is required: pass --workspace-id")
+
+    headers = {"uploadFilePath": file_path, "variableId": variable_id,
+               "instanceId": instance_id, "flowTemplateId": flow_template_id,
+               "workspaceId": workspace_id}
+    status, content, resp_headers = client.request_bytes(
+        "GET", "/api/File/download",
+        query={"isArchived": "true" if args.is_archived else "false"},
+        headers=headers)
+    if not (200 <= status < 300):
+        body = content[:300].decode("utf-8", "replace") if content else ""
+        raise ProcesioAPIError(int(status or 0), f"HTTP {status} downloading file", {"body": body})
+
+    rh = {str(k).lower(): v for k, v in (resp_headers or {}).items()}
+    out_name = (_filename_from_disposition(rh.get("content-disposition", "")) or name
+                or (file_path.rsplit("/", 1)[-1] if file_path else "download.bin"))
+    out = Path(args.out) if args.out else Path.cwd() / out_name
+    if out.is_dir():
+        out = out / out_name
+    if out.parent and not out.parent.exists():
+        out.parent.mkdir(parents=True, exist_ok=True)
+    out.write_bytes(content)
+    return {"downloaded": True, "path": str(out), "size": len(content),
+            "mimeType": rh.get("content-type"), "name": out.name}
+
+
+def _args(p: argparse.ArgumentParser) -> None:
+    add_profile_arg(p)
+    p.add_argument("--from-run", dest="from_run",
+                   help="path to a run-process result JSON; derive the file + ids from it")
+    p.add_argument("--var", help="with --from-run: the output variable name to download "
+                                 "(default: the first file variable)")
+    p.add_argument("--file-path", dest="file_path",
+                   help="the file DTO 'path' (flow/flow-<id>/flow-instance-<id>/variable-<id>/<fileId>)")
+    p.add_argument("--variable-id", dest="variable_id", help="output variable id")
+    p.add_argument("--instance-id", dest="instance_id", help="flow instance id")
+    p.add_argument("--flow-template-id", dest="flow_template_id", help="process (flow template) id")
+    p.add_argument("--out", help="output file path or directory (default: the filename in the cwd)")
+    p.add_argument("--is-archived", dest="is_archived", action="store_true",
+                   help="fetch from archived storage")
+
+
+ACTIONS = {
+    "file-download": ActionDef(
+        func=file_download, add_args=_args, needs_client=True,
+        description="Download a flow-instance file (Generate-Document output etc.) "
+                    "via the header-based GET /api/File/download."),
+}