procesio-cli 0.1.1__py3-none-any.whl

procesio_cli/tools/procesio/environments.py

@@ -0,0 +1,264 @@
+"""PROCESIO environments - named URL sets an installation is reached through.
+
+A PROCESIO *environment* is one installation of the platform: a `<Client>-<ENV>`
+label (e.g. `Internal-PROD`, `Internal-QA`, `Acme-DEVQA`) that carries the four
+host URLs that installation lives on:
+
+    web_base   the Web API host (every REST call)                webapi-*.procesio.app
+    app_base   the designer / front-end host (designer URLs, CORS Origin)   *.procesio.app
+    forms_base the public forms host (rendered-form URLs)        forms-*.procesio.app
+    auth_base  the legacy Proxy/Authentication host (rarely used - login goes to web_base)
+
+Environments are NON-secret (they are just hostnames). Credentials are stored
+separately (Credential Manager, see profiles.py) and each credential is *bound*
+to one environment by name - so switching environment also switches which
+account/key is used. A credential with no binding belongs to the DEFAULT
+environment, which itself defaults to `Internal-PROD`. That is what keeps every
+pre-existing single-credential setup working unchanged as production: no env
+config on disk + an unbound credential == Internal-PROD == the historical
+hard-coded URLs, with nothing to re-enter.
+
+Two layers, merged at read time:
+  * BUILT-IN presets in code (Internal-PROD/QA/DEV) - PROCESIO's own infra, shared
+    with every teammate, available with zero setup.
+  * a USER registry at ``config/procesio/environments.json`` (per-user, wipeable)
+    holding client-specific environments (Acme-*, ...) and the default pointer.
+    A user entry with the same name OVERRIDES a built-in (so a moved Internal host
+    can be corrected without a code change).
+
+Client environment URLs are customer-specific, so they are USER DATA and live in
+the registry file - never baked into the shared framework code (only PROCESIO's
+own Internal-* presets are).
+"""
+from __future__ import annotations
+
+import json
+import re
+
+from tools._lib import userdata
+from tools.procesio.errors import UsageError
+
+COMPONENT = "procesio"
+REGISTRY_FILE = "environments.json"
+
+# The canonical fallback: an unbound credential and an unset default both resolve
+# here, and its URLs equal the historical hard-coded production defaults.
+DEFAULT_ENV_NAME = "Internal-PROD"
+
+# The four hosts every environment defines. Keys are the field names injected into
+# a profile so config.web_base/app_base/forms_base/auth_base pick them up.
+URL_KEYS = ("web_base", "app_base", "forms_base", "auth_base")
+
+# Built-in PROCESIO-internal environments (framework-shared, non-secret infra).
+# Production keeps the bare hostnames; QA/DEV use the -qa/-dev host family. auth_base
+# is only meaningful on PROD (the legacy Proxy host); QA/DEV omit it and fall back to
+# the config default, since login goes to web_base anyway.
+BUILTIN: dict[str, dict] = {
+    "Internal-PROD": {
+        "name": "Internal-PROD", "client": "Internal", "env": "PROD",
+        "web_base": "https://webapi.procesio.app",
+        "app_base": "https://procesio.app",
+        "forms_base": "https://forms.procesio.app",
+        "auth_base": "https://auth.procesio.app",
+        "builtin": True,
+    },
+    "Internal-QA": {
+        "name": "Internal-QA", "client": "Internal", "env": "QA",
+        "web_base": "https://webapi-qa.procesio.app",
+        "app_base": "https://qa.procesio.app",
+        "forms_base": "https://forms-qa.procesio.app",
+        "builtin": True,
+    },
+    "Internal-DEV": {
+        "name": "Internal-DEV", "client": "Internal", "env": "DEV",
+        "web_base": "https://webapi-dev.procesio.app",
+        "app_base": "https://dev.procesio.app",
+        "forms_base": "https://forms-dev.procesio.app",
+        "builtin": True,
+    },
+}
+
+_NAME_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]*$")
+
+
+# -- registry file ----------------------------------------------------------
+
+def _registry_path():
+    return userdata.config_dir(COMPONENT) / REGISTRY_FILE
+
+
+def _load_registry() -> dict:
+    p = _registry_path()
+    if not p.exists():
+        return {"environments": {}, "default": None}
+    try:
+        data = json.loads(p.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        return {"environments": {}, "default": None}
+    if not isinstance(data, dict):
+        return {"environments": {}, "default": None}
+    envs = data.get("environments")
+    data["environments"] = envs if isinstance(envs, dict) else {}
+    if "default" not in data:
+        data["default"] = None
+    return data
+
+
+def _save_registry(data: dict) -> None:
+    p = _registry_path()
+    # Direct bytes write with LF endings - never the (Cowork-mount-capped) Write tool.
+    payload = json.dumps(data, ensure_ascii=False, indent=2) + "\n"
+    p.write_bytes(payload.encode("utf-8"))
+
+
+# -- read -------------------------------------------------------------------
+
+def all_environments() -> dict[str, dict]:
+    """Every known environment: built-ins overlaid by any user entry of the same
+    name, plus purely user-defined ones. Values are copies safe to mutate."""
+    merged: dict[str, dict] = {k: dict(v) for k, v in BUILTIN.items()}
+    for name, env in _load_registry()["environments"].items():
+        if not isinstance(env, dict):
+            continue
+        base = merged.get(name, {})
+        base.update(env)
+        base["name"] = name
+        base["builtin"] = name in BUILTIN
+        merged[name] = base
+    return merged
+
+
+def _find(name: str) -> tuple[str, dict] | None:
+    """Case-insensitive lookup by canonical name. Returns (canonical_name, env)."""
+    if not name:
+        return None
+    envs = all_environments()
+    if name in envs:
+        return name, envs[name]
+    low = name.strip().lower()
+    for canon, env in envs.items():
+        if canon.lower() == low:
+            return canon, env
+    return None
+
+
+def get(name: str) -> dict:
+    hit = _find(name)
+    if not hit:
+        raise UsageError(
+            f"no PROCESIO environment named '{name}'. "
+            f"Known: {', '.join(sorted(all_environments())) or '(none)'}. "
+            f"Add one with: run-tool procesio add-environment ..."
+        )
+    return hit[1]
+
+
+def exists(name: str) -> bool:
+    return _find(name) is not None
+
+
+def canonical_name(name: str) -> str | None:
+    hit = _find(name)
+    return hit[0] if hit else None
+
+
+# -- default pointer --------------------------------------------------------
+
+def get_default() -> str:
+    """The active environment name. The stored pointer if set and still valid,
+    else DEFAULT_ENV_NAME (Internal-PROD) - so a fresh box is production."""
+    stored = _load_registry().get("default")
+    if stored and exists(stored):
+        return canonical_name(stored)
+    return DEFAULT_ENV_NAME
+
+
+def set_default(name: str) -> str:
+    canon = canonical_name(name)
+    if not canon:
+        raise UsageError(
+            f"cannot switch to unknown environment '{name}'. "
+            f"Known: {', '.join(sorted(all_environments()))}. "
+            f"Add it first with: run-tool procesio add-environment ..."
+        )
+    data = _load_registry()
+    data["default"] = canon
+    _save_registry(data)
+    return canon
+
+
+# -- add / remove (user registry only) --------------------------------------
+
+def _derive_client_env(name: str, client: str | None, env: str | None):
+    """Fill client/env from the `<Client>-<ENV>` name when not given explicitly."""
+    if client and env:
+        return client, env
+    if "-" in name:
+        c, _, e = name.rpartition("-")
+        return client or c, env or e
+    return client or name, env or ""
+
+
+def add(name: str, *, web_base: str, app_base: str, forms_base: str,
+        auth_base: str | None = None, client: str | None = None,
+        env: str | None = None, make_default: bool = False) -> dict:
+    name = (name or "").strip()
+    if not _NAME_RE.match(name):
+        raise UsageError(
+            "environment name must look like '<Client>-<ENV>' "
+            "(letters/digits/.-_ , e.g. 'Acme-PROD')"
+        )
+    if not (web_base and app_base and forms_base):
+        raise UsageError("add-environment needs --web-base, --app-base and --forms-base")
+    client, env = _derive_client_env(name, client, env)
+    entry = {
+        "name": name, "client": client, "env": env,
+        "web_base": web_base.rstrip("/"),
+        "app_base": app_base.rstrip("/"),
+        "forms_base": forms_base.rstrip("/"),
+    }
+    if auth_base:
+        entry["auth_base"] = auth_base.rstrip("/")
+    data = _load_registry()
+    data["environments"][name] = entry
+    if make_default:
+        data["default"] = name
+    _save_registry(data)
+    out = dict(entry)
+    out["builtin"] = name in BUILTIN
+    return out
+
+
+def remove(name: str) -> None:
+    data = _load_registry()
+    canon = None
+    for existing in data["environments"]:
+        if existing.lower() == name.strip().lower():
+            canon = existing
+            break
+    if canon is None:
+        if name in BUILTIN or canonical_name(name) in BUILTIN:
+            raise UsageError(f"'{name}' is a built-in environment and cannot be removed")
+        raise UsageError(f"no user-defined environment named '{name}'")
+    del data["environments"][canon]
+    if data.get("default") and data["default"].lower() == canon.lower():
+        data["default"] = None
+    _save_registry(data)
+
+
+# -- resolution -------------------------------------------------------------
+
+def resolve(name: str | None, profile: dict | None = None) -> dict:
+    """The active environment for a call. Precedence, highest first:
+      1. an explicit environment name (the --environment flag),
+      2. the credential's own `environment` binding,
+      3. the stored default environment,
+      4. Internal-PROD.
+    Always returns a full environment dict (never raises for the fallbacks;
+    only an explicit unknown name raises)."""
+    if name:
+        return get(name)
+    bound = (profile or {}).get("environment")
+    if bound and exists(bound):
+        return get(bound)
+    return get(get_default())

procesio_cli/tools/procesio/errors.py

@@ -0,0 +1,166 @@
+"""Map exceptions to the framework error envelope: (code, message, details, exit_code).
+
+PROCESIO's Web API is ASP.NET/Kestrel behind a Kong gateway, so a request can
+fail at three layers: argument validation (UsageError), missing/invalid
+credentials before any HTTP call (AuthError), or a non-2xx HTTP response
+(ProcesioAPIError). classify() turns each into a stable string code so callers
+(and the outreach agent) can branch without parsing prose.
+
+Notable status semantics observed against the live gateway:
+  401  Bearer/api-key rejected by the Web API (Kestrel).
+  403  authenticated but not permitted in this workspace.
+  404  Kong "no Route matched" OR a real not-found from the app.
+  407  the Web API could not complete the upstream Proxy-API auth leg
+       (its own /api/Authentication proxies to the Authentication Service).
+"""
+from __future__ import annotations
+
+from typing import Any
+
+
+class UsageError(Exception):
+    """Bad/invalid arguments. Maps to 'invalid_argument', exit code 2."""
+
+
+class AuthError(Exception):
+    """Missing/invalid credentials before any HTTP call. -> auth_required."""
+
+
+class ProcesioAPIError(Exception):
+    """A non-2xx HTTP response from PROCESIO. Carries status + parsed body."""
+
+    def __init__(self, status: int, message: str, details: dict | None = None):
+        super().__init__(message)
+        self.status = status
+        self.details = details or {}
+
+
+class RemovalBlocked(Exception):
+    """A desired-state save was blocked because it would REMOVE actions or variables
+    that exist on the live resource. Carries what would disappear so the caller can see
+    it before paying for it. Maps to 'removal_blocked', exit code 2. Intentional
+    removals pass --allow-remove.
+
+    Separate from ValidationBlocked on purpose: --force answers "save it even though it
+    is invalid", which is a different question from "yes, delete those". A half-built
+    process is a legitimate thing to force-save WITHOUT wanting to drop anything.
+    """
+
+    def __init__(self, message: str, removed: dict | None = None):
+        super().__init__(message)
+        self.removed = removed or {}
+
+
+class ValidationBlocked(Exception):
+    """A save was blocked because front-end (designer) and/or back-end validation found
+    errors. Carries the full report so the caller can see exactly what to fix. Maps to
+    'validation_failed', exit code 2. Bypassable with --force."""
+
+    def __init__(self, message: str, report: dict | None = None):
+        super().__init__(message)
+        self.report = report or {}
+
+
+class DeadlineExceeded(Exception):
+    """A request exceeded its TOTAL wall-clock deadline (see reliability.py). The
+    old client had no total deadline — a stalled call ran until SIGKILL. This makes
+    the stall a structured, machine-readable failure instead. `outcome` is always
+    'unknown' for a write: the request MAY have applied server-side, so the caller
+    must verify behaviourally, never assume it did or did not land."""
+
+    def __init__(self, path: str, endpoint_class: str, deadline_s: float,
+                 elapsed_s: float):
+        super().__init__(
+            f"request exceeded the {endpoint_class} deadline of "
+            f"{deadline_s:.0f}s (elapsed {elapsed_s:.1f}s): {path}")
+        self.path = path
+        self.endpoint_class = endpoint_class
+        self.deadline_s = deadline_s
+        self.elapsed_s = elapsed_s
+
+
+class NotPersisted(Exception):
+    """A write returned 2xx but a read-back shows the server kept the OLD value. PROCESIO does
+    this silently in places (a FormTemplate write that drops Data: the PUT succeeds, updatedOn
+    moves, the previous content stays). Maps to 'not_persisted', exit code 1. Carries what was
+    sent vs what is stored."""
+
+    def __init__(self, message: str, details: dict | None = None):
+        super().__init__(message)
+        self.details = details or {}
+
+
+_HTTP_CODES = {
+    400: ("invalid_argument", "bad request - check the parameters/body"),
+    401: ("auth_required", "authentication failed - token or api-key rejected"),
+    403: ("permission_denied", "not permitted in this workspace"),
+    404: ("not_found", "not found (or Kong route not matched)"),
+    405: ("invalid_argument", "method not allowed for this path"),
+    407: ("proxy_auth_failed",
+          "the Web API could not authenticate against the Proxy API "
+          "(check the auth_base host and credentials)"),
+    409: ("conflict", "conflict"),
+    422: ("invalid_argument", "unprocessable - validation failed"),
+    429: ("rate_limited", "rate limit exceeded - back off and retry"),
+    500: ("server_error", "PROCESIO server error"),
+    502: ("server_error", "bad gateway"),
+    503: ("server_error", "service unavailable"),
+}
+
+
+def map_http_error(status: int, reason: str = "") -> tuple[str, str, int]:
+    code, default_msg = _HTTP_CODES.get(status, ("procesio_api_error", f"HTTP {status}"))
+    exit_code = 2 if code == "invalid_argument" else 1
+    return code, reason or default_msg, exit_code
+
+
+def _reason_from_body(details: Any) -> str:
+    """PROCESIO error bodies vary: {"message": ...}, {"error": ...},
+    {"errors": {...}}, or an ASP.NET ProblemDetails {"title": ..., "errors": {...}}."""
+    if not isinstance(details, dict):
+        return ""
+    for key in ("message", "error", "error_message", "reason", "title", "detail"):
+        val = details.get(key)
+        if isinstance(val, str) and val:
+            return val
+    errs = details.get("errors")
+    if isinstance(errs, list) and errs:
+        first = errs[0]
+        if isinstance(first, str):
+            return first
+        if isinstance(first, dict):
+            return first.get("message") or first.get("error") or ""
+    if isinstance(errs, dict):
+        for val in errs.values():
+            if isinstance(val, list) and val and isinstance(val[0], str):
+                return val[0]
+            if isinstance(val, str) and val:
+                return val
+    return ""
+
+
+def classify(exc: Exception) -> tuple[str, str, dict, int]:
+    if isinstance(exc, AuthError):
+        return "auth_required", str(exc), {}, 1
+    if isinstance(exc, UsageError):
+        return "invalid_argument", str(exc), {}, 2
+    if isinstance(exc, ValidationBlocked):
+        return "validation_failed", str(exc), exc.report, 2
+    if isinstance(exc, NotPersisted):
+        return "not_persisted", str(exc), exc.details, 1
+    if isinstance(exc, RemovalBlocked):
+        return "removal_blocked", str(exc), exc.removed, 2
+    if isinstance(exc, DeadlineExceeded):
+        return "deadline_exceeded", str(exc), {
+            "kind": "deadline",
+            "endpoint": exc.path,
+            "class": exc.endpoint_class,
+            "deadline_s": exc.deadline_s,
+            "elapsed_s": round(exc.elapsed_s, 2),
+            "outcome": "unknown",
+        }, 1
+    if isinstance(exc, ProcesioAPIError):
+        reason = _reason_from_body(exc.details) or str(exc)
+        code, msg, exit_code = map_http_error(exc.status, reason)
+        return code, msg, {"status": exc.status, "body": exc.details}, exit_code
+    return "error", str(exc) or exc.__class__.__name__, {}, 1

procesio_cli/tools/procesio/flowmodel/README.md

@@ -0,0 +1,37 @@
+# flowmodel — offline flow graph reader
+
+Parses a PROCESIO flow (a `.procesio` export bundle or a live flow DTO) into a canonical,
+JSON-ready node/edge graph model. Pure, offline, case-insensitive (handles PascalCase
+exports and camelCase live DTOs). Never mutates its input.
+
+This is the substrate the canvas layout tool, `inspect-flow`, and audit build on — parse
+once, reuse. The model it produces is documented in `../PROCESIO-RESOURCE-MODEL-NOTES.md` §1.
+
+## Use
+
+```python
+from tools.procesio.flowmodel import read_flow, read_bundle
+
+g = read_flow(bundle_or_flow, flow_id=None)   # -> FlowGraph (nodes, edges, containers,
+                                               #    variables, subprocess_calls, resources,
+                                               #    start_id, stop_ids); g.to_dict() for JSON
+rm = read_bundle(bundle)                       # -> {"flows": {...}, "process_edges": [...]}
+```
+
+CLI (offline, no profile needed):
+
+```
+python -m tools.procesio.main read-flow-graph --in <export.procesio|->  [--flow-id <id>]
+python -m tools.procesio.main read-flow-graph --in <export.procesio> --resource-map
+```
+
+- `--in` accepts a file path, `-` (stdin), or a raw JSON string.
+- `--flow-id` disambiguates a multi-flow bundle.
+- `--resource-map` emits every flow plus the cross-process (process→process) edge list,
+  built from each flow's `Call/Trigger Subprocess` targets.
+
+## Files
+
+- `model.py` — dataclasses: `FlowGraph`, `Node`, `Edge`, `Container`, `VarRef`, `SubprocessCall`.
+- `reader.py` — `read_flow` / `read_bundle` + the case-insensitive getter `_g`.
+- Tests: `../tests/test_flowmodel.py` (synthetic + real exports).

procesio_cli/tools/procesio/flowmodel/__init__.py

@@ -0,0 +1,14 @@
+"""Pure, offline reader: a PROCESIO flow/export → a canonical node/edge graph model.
+
+The substrate the canvas layout tool, inspect-flow, and audit build on. See
+tools/procesio/PROCESIO-RESOURCE-MODEL-NOTES.md §1 for the model it parses.
+"""
+from tools.procesio.flowmodel.model import (
+    Container, Edge, FlowGraph, Node, SubprocessCall, VarRef,
+)
+from tools.procesio.flowmodel.reader import read_bundle, read_flow
+
+__all__ = [
+    "FlowGraph", "Node", "Edge", "Container", "VarRef", "SubprocessCall",
+    "read_flow", "read_bundle",
+]