procesio-cli 0.1.1__py3-none-any.whl

procesio_cli/tools/procesio/tests/test_edit_dryrun_preview.py

@@ -0,0 +1,96 @@
+"""`<component>-edit --dry-run` must preview the EDIT, not a create.
+
+The bug: the dry-run branch called `build_dto` straight from the loaded config, skipping the
+component's own edit preparation. For a process that preparation is what reuses the live flow's
+VARIABLE IDS by name and its canvas positions — so the preview showed brand-new variable ids while
+the real edit would have kept them.
+
+That is the worst possible direction for a preview to be wrong. A process variable is referenced by
+GUID from outside the process (a form's RUN_PROCESS inputMap/outputMap binds it by id), so "do the
+ids change?" is exactly the question a dry-run is run to answer, and it answered it wrongly in both
+directions: a preserved id shown as changed, and — for a config that renames a variable — a change
+shown as if nothing external would break.
+"""
+from __future__ import annotations
+
+import argparse
+
+from tools.procesio.dto import framework
+from tools.procesio.dto.process import builder as process_builder
+
+
+LIVE_VAR_ID = "11111111-1111-1111-1111-111111111111"
+
+
+class _Client:
+    """Serves one live flow, the way GET /api/Projects/{id} does."""
+
+    def __init__(self):
+        self.gets = []
+
+    def get(self, path, query=None):
+        self.gets.append(path)
+        return {"flow": {"id": "flow-1", "title": "P", "actions": [],
+                         "variables": [{"id": LIVE_VAR_ID, "name": "Row", "isError": False}]}}
+
+
+def _component(calls: list) -> framework.Component:
+    """A minimal component whose build simply reports the ctx it was handed."""
+    def build(config, ctx):
+        calls.append(ctx)
+        return {"Variables": [{"Name": "Row",
+                               "Id": (ctx.get("existing_var_ids") or {}).get("row", "NEW-ID")}]}
+
+    def edit_ctx(client, resource_id, config, ctx):
+        cur = client.get(f"/api/Projects/{resource_id}")
+        flow = cur.get("flow", cur)
+        return {**ctx, "existing_var_ids": {(v["name"] or "").strip().lower(): v["id"]
+                                            for v in flow.get("variables") or []}}
+
+    return framework.Component(
+        # the real process dir, so validate_config finds a schema; the config below satisfies it
+        name="process", description="", dir=process_builder.DIR,
+        build=build, create_endpoint=("POST", "/x"), get_path="/x/{id}",
+        extract_id=lambda r, d: None, edit_ctx=edit_ctx)
+
+
+def _args(**kw):
+    return argparse.Namespace(id="flow-1", config=None, config_file=None,
+                              dry_run=True, force=False, no_types=False, **kw)
+
+
+def test_the_dry_run_preview_reuses_the_live_variable_ids():
+    calls: list = []
+    comp = _component(calls)
+    client = _Client()
+
+    dto = framework.build_edit_dto(comp, client, "flow-1", {"title": "P"}, {})
+
+    assert dto["Variables"][0]["Id"] == LIVE_VAR_ID, (
+        "the preview must show the id the edit would actually write")
+    assert calls and calls[0].get("existing_var_ids") == {"row": LIVE_VAR_ID}
+
+
+def test_a_component_without_an_edit_ctx_hook_is_unaffected():
+    calls: list = []
+    comp = _component(calls)
+    comp.edit_ctx = None
+    client = _Client()
+
+    dto = framework.build_edit_dto(comp, client, "flow-1", {"title": "P"}, {})
+
+    assert dto["Variables"][0]["Id"] == "NEW-ID"
+    assert client.gets == [], "no live read when the component has nothing to preserve"
+
+
+def test_an_unreadable_live_resource_falls_back_to_a_plain_build():
+    """A preview must still be produced when the live flow cannot be read."""
+    calls: list = []
+    comp = _component(calls)
+
+    class Broken(_Client):
+        def get(self, path, query=None):
+            raise RuntimeError("gone")
+
+    dto = framework.build_edit_dto(comp, Broken(), "flow-1", {"title": "P"}, {})
+    assert dto["Variables"][0]["Id"] == "NEW-ID"

procesio_cli/tools/procesio/tests/test_elk_layout.py

@@ -0,0 +1,221 @@
+"""Tests for the opt-in ELK 'layered' layout engine + the LAYOUT_ENGINE dispatch flag.
+
+The ELK-runtime tests need Node + elkjs (tools/procesio/layout/elk/node_modules); they skip
+if that toolchain is absent. The dispatch/flag and graceful-fallback tests are pure Python
+and always run.
+"""
+from __future__ import annotations
+
+import copy
+import math
+
+import pytest
+
+from tools.procesio.layout import dispatch, elk_engine, engine
+
+
+def _elk_available() -> bool:
+    """True iff the REAL ELK runner works here — node on PATH, elkjs installed
+    (tools/procesio/layout/elk/node_modules), runner returns a laid-out graph.
+
+    Probe the runner DIRECTLY, never through elk_engine.layout(): layout() swallows every
+    ELK failure and returns the LEGACY layout, so any "did we get sane positions back"
+    check reports available on a machine with no node_modules. The skip then never fires
+    and the ELK-specific assertions below run against the legacy engine — which is exactly
+    how test_elk_long_straight_run_is_clustered failed on a fresh checkout while the other
+    four @requires_elk tests passed by coincidence.
+    """
+    try:
+        graph = elk_engine._build_elk_graph(
+            [elk_engine._norm({"id": "a"}), elk_engine._norm({"id": "b"})],
+            [{"source": "a", "dest": "b"}])
+        return bool(elk_engine._run_elk(graph))
+    except Exception:  # noqa: BLE001 — any failure means "not available", never a test error
+        return False
+
+
+requires_elk = pytest.mark.skipif(not _elk_available(),
+                                  reason="Node/elkjs runner unavailable")
+
+
+def _assert_all_finite(res, ids):
+    """Every id has a position and no coordinate is NaN / None / non-finite."""
+    p = res["positions"]
+    for i in ids:
+        assert i in p, f"{i} missing a position"
+    for i, q in p.items():
+        assert q["x"] is not None and q["y"] is not None, f"{i} has a None coordinate"
+        assert isinstance(q["x"], float) and isinstance(q["y"], float), f"{i} non-float"
+        assert not math.isnan(q["x"]) and not math.isnan(q["y"]), f"{i} is NaN"
+        assert math.isfinite(q["x"]) and math.isfinite(q["y"]), f"{i} not finite"
+
+
+# --- graph shapes ----------------------------------------------------------
+
+def _linear(n=6):
+    nodes = [{"id": f"n{i}"} for i in range(n)]
+    edges = [{"source": f"n{i}", "dest": f"n{i + 1}"} for i in range(n - 1)]
+    return nodes, edges
+
+
+def _branching():
+    """start -> a -> {b,c} -> d -> stop, with an error edge a->err and a d->a back-edge."""
+    nodes = [{"id": i} for i in ("start", "a", "b", "c", "d", "err", "stop")]
+    edges = [
+        {"source": "start", "dest": "a"}, {"source": "a", "dest": "b"},
+        {"source": "a", "dest": "c"}, {"source": "b", "dest": "d"},
+        {"source": "c", "dest": "d"}, {"source": "d", "dest": "stop"},
+        {"source": "a", "dest": "err", "type": 1},
+        {"source": "d", "dest": "a"},                       # back-edge (loop / retry)
+    ]
+    return nodes, edges
+
+
+def _compound():
+    """A For-Each container 'loop' holding an inner k1->k2 pipeline."""
+    nodes = [{"id": "start"}, {"id": "loop", "kind": "area"},
+             {"id": "k1", "parent_id": "loop"}, {"id": "k2", "parent_id": "loop"},
+             {"id": "stop"}]
+    edges = [{"source": "start", "dest": "loop"}, {"source": "loop", "dest": "k1"},
+             {"source": "k1", "dest": "k2"}, {"source": "loop", "dest": "stop"}]
+    return nodes, edges
+
+
+# --- ELK-runtime tests -----------------------------------------------------
+
+@requires_elk
+def test_elk_flat_linear_all_positioned():
+    nodes, edges = _linear()
+    res = elk_engine.layout(nodes, edges)
+    _assert_all_finite(res, [n["id"] for n in nodes])
+    p = res["positions"]
+    assert res["areas"] == {}                                # no containers in a flat graph
+    # readability config: a linear chain is ONE straight left-to-right row (wrapping OFF,
+    # Brandes-Köpf alignment) — every node on the same y, x strictly increasing.
+    assert len({round(q["y"]) for q in p.values()}) == 1     # single straight row
+    xs = [p[f"n{i}"]["x"] for i in range(len(nodes))]
+    assert xs == sorted(xs) and len(set(xs)) == len(nodes)   # each node right of the previous
+    assert p["n0"]["x"] == min(q["x"] for q in p.values())   # starts at the left
+
+
+@requires_elk
+def test_elk_short_straight_run_not_clustered():
+    # a 6-node chain is NOT longer than CLUSTER_MIN(6) → stays one straight left-to-right row
+    nodes = [{"id": f"n{i}"} for i in range(6)]
+    edges = [{"source": f"n{i}", "dest": f"n{i + 1}"} for i in range(5)]
+    p = elk_engine.layout(nodes, edges)["positions"]
+    assert len({round(v["y"]) for v in p.values()}) == 1     # single row (not folded)
+
+
+@requires_elk
+def test_elk_long_straight_run_is_clustered():
+    # an 8-node straight run (> CLUSTER_MIN) folds into a compact serpentine: fewer columns,
+    # more than one row, every node still placed and finite.
+    n = 8
+    nodes = [{"id": f"n{i}"} for i in range(n)]
+    edges = [{"source": f"n{i}", "dest": f"n{i + 1}"} for i in range(n - 1)]
+    res = elk_engine.layout(nodes, edges)
+    _assert_all_finite(res, [f"n{i}" for i in range(n)])
+    p = res["positions"]
+    assert len({round(v["y"]) for v in p.values()}) > 1      # folded into multiple rows
+    assert len({round(v["x"]) for v in p.values()}) < n      # fewer columns than nodes
+
+
+@requires_elk
+def test_elk_branching_all_positioned():
+    nodes, edges = _branching()
+    res = elk_engine.layout(nodes, edges)
+    _assert_all_finite(res, [n["id"] for n in nodes])        # cycle + error edge don't crash it
+
+
+@requires_elk
+def test_elk_compound_children_inside_frame():
+    nodes, edges = _compound()
+    res = elk_engine.layout(nodes, edges)
+    _assert_all_finite(res, [n["id"] for n in nodes])
+    assert "loop" in res["areas"], "container must produce an area frame"
+    fr = res["areas"]["loop"]
+    for k in ("width", "height", "x", "y"):
+        assert math.isfinite(fr[k])
+    for kid in ("k1", "k2"):                                 # children land inside the frame
+        q = res["positions"][kid]
+        assert fr["x"] <= q["x"] <= fr["x"] + fr["width"]
+        assert fr["y"] <= q["y"] <= fr["y"] + fr["height"]
+
+
+@requires_elk
+def test_elk_deterministic():
+    nodes, edges = _branching()
+    a = elk_engine.layout(nodes, edges)
+    b = elk_engine.layout(copy.deepcopy(nodes), copy.deepcopy(edges))
+    assert a == b                                            # fixed seed → identical output
+
+
+@requires_elk
+def test_elk_missing_endpoint_is_dropped_not_crashed():
+    res = elk_engine.layout([{"id": "x"}, {"id": "y"}],
+                            [{"source": "x", "dest": "GHOST"}, {"source": "x", "dest": "y"}])
+    _assert_all_finite(res, ["x", "y"])                      # ghost edge ignored, nodes placed
+
+
+# --- resilience (engine-agnostic) ------------------------------------------
+
+def test_elk_empty_graph():
+    res = elk_engine.layout([], [])
+    assert res["positions"] == {} and res["areas"] == {}
+    assert res["bbox"] == {"minX": 0, "minY": 0, "maxX": 0, "maxY": 0}
+
+
+def test_elk_subset_delegates_to_legacy():
+    # partial re-tidy is legacy-only; the ELK engine must delegate and match legacy exactly.
+    nodes = [{"id": "a", "position": {"x": 0, "y": 100}},
+             {"id": "b", "position": {"x": 5000, "y": 9000}},
+             {"id": "c", "position": {"x": 520, "y": 100}}]
+    edges = [{"source": "a", "dest": "b"}, {"source": "b", "dest": "c"}]
+    assert elk_engine.layout(nodes, edges, subset=["b"]) == \
+        engine.layout(copy.deepcopy(nodes), copy.deepcopy(edges), subset=["b"])
+
+
+def test_elk_falls_back_to_legacy_on_runner_failure(monkeypatch):
+    # force the ELK invocation to fail; the engine must degrade to a valid legacy layout.
+    def boom(_graph):
+        raise RuntimeError("simulated: node not found")
+    monkeypatch.setattr(elk_engine, "_run_elk", boom)
+    nodes, edges = _linear()
+    res = elk_engine.layout(nodes, edges)
+    assert res == engine.layout(nodes, edges)               # exactly the legacy result
+    _assert_all_finite(res, [n["id"] for n in nodes])
+
+
+# --- dispatch flag ---------------------------------------------------------
+
+def test_dispatch_defaults_to_legacy(monkeypatch):
+    monkeypatch.delenv("LAYOUT_ENGINE", raising=False)
+    assert dispatch.selected_engine() == "legacy"
+    nodes, edges = _linear()
+    assert dispatch.layout(nodes, edges) == engine.layout(nodes, edges)
+
+
+@pytest.mark.parametrize("val", ["", "  ", "bogus", "LEGACY", "ELKZ"])
+def test_dispatch_invalid_or_unset_is_legacy(monkeypatch, val):
+    monkeypatch.setenv("LAYOUT_ENGINE", val)
+    assert dispatch.selected_engine() == "legacy"
+
+
+@pytest.mark.parametrize("val", ["elk", "ELK", "  elk  "])
+def test_dispatch_selects_elk(monkeypatch, val):
+    monkeypatch.setenv("LAYOUT_ENGINE", val)
+    assert dispatch.selected_engine() == "elk"
+
+
+def test_dispatch_routes_to_elk_engine(monkeypatch):
+    monkeypatch.setenv("LAYOUT_ENGINE", "elk")
+    sentinel = {"positions": {"_": {"x": 1.0, "y": 2.0}}, "areas": {}, "bbox": {}}
+    called = {}
+
+    def fake(nodes, edges, opts=None, subset=None):
+        called["hit"] = True
+        return sentinel
+    monkeypatch.setattr(elk_engine, "layout", fake)
+    out = dispatch.layout([{"id": "n0"}], [])
+    assert called.get("hit") and out is sentinel

procesio_cli/tools/procesio/tests/test_environments.py

@@ -0,0 +1,214 @@
+"""Environments: registry, default switching, credential binding, URL resolution.
+
+The autouse _isolate_userdata fixture (conftest) pins the registry to a temp dir,
+so every test starts from the built-in presets with the default = Internal-PROD.
+"""
+from __future__ import annotations
+
+import argparse
+
+import pytest
+
+from tools.procesio import config, environments as E
+from tools.procesio.client import ProcesioClient
+from tools.procesio.errors import UsageError
+from tools.procesio.handlers import environment_admin as EA
+from tools.procesio.tests.conftest import FakeResp, FakeSession
+
+
+# -- built-ins & defaults ---------------------------------------------------
+
+def test_builtin_presets_present():
+    names = set(E.all_environments())
+    assert {"Internal-PROD", "Internal-QA", "Internal-DEV"} <= names
+
+
+def test_default_is_prod_on_fresh_registry():
+    assert E.get_default() == "Internal-PROD"
+
+
+def test_prod_urls_match_historical_defaults():
+    prod = E.get("Internal-PROD")
+    assert prod["web_base"] == config.DEFAULT_WEB_BASE
+    assert prod["app_base"] == config.DEFAULT_APP_BASE
+    assert prod["forms_base"] == config.DEFAULT_FORMS_BASE
+
+
+@pytest.mark.parametrize("name,web,app,forms", [
+    ("Internal-QA", "https://webapi-qa.procesio.app",
+     "https://qa.procesio.app", "https://forms-qa.procesio.app"),
+    ("Internal-DEV", "https://webapi-dev.procesio.app",
+     "https://dev.procesio.app", "https://forms-dev.procesio.app"),
+])
+def test_qa_dev_urls(name, web, app, forms):
+    env = E.get(name)
+    assert env["web_base"] == web
+    assert env["app_base"] == app
+    assert env["forms_base"] == forms
+
+
+# -- resolution precedence --------------------------------------------------
+
+def test_resolve_unbound_is_prod():
+    assert E.resolve(None, {"type": "apikey"})["name"] == "Internal-PROD"
+
+
+def test_resolve_uses_credential_binding():
+    assert E.resolve(None, {"environment": "Internal-DEV"})["name"] == "Internal-DEV"
+
+
+def test_explicit_name_beats_binding():
+    got = E.resolve("Internal-QA", {"environment": "Internal-DEV"})
+    assert got["name"] == "Internal-QA"
+
+
+def test_default_pointer_beats_prod_fallback():
+    E.set_default("Internal-QA")
+    assert E.resolve(None, {"type": "apikey"})["name"] == "Internal-QA"
+
+
+def test_case_insensitive_lookup():
+    assert E.canonical_name("internal-qa") == "Internal-QA"
+    assert E.resolve("INTERNAL-DEV", None)["name"] == "Internal-DEV"
+
+
+def test_unknown_environment_raises():
+    with pytest.raises(UsageError):
+        E.get("Nope-PROD")
+
+
+# -- add / set / remove -----------------------------------------------------
+
+def test_add_client_environment_and_switch():
+    entry = E.add("Acme-PROD", web_base="https://webapi.acme.example",
+                  app_base="https://acme.example",
+                  forms_base="https://forms.acme.example")
+    assert entry["client"] == "Acme" and entry["env"] == "PROD"
+    assert entry["builtin"] is False
+    E.set_default("Acme-PROD")
+    assert E.get_default() == "Acme-PROD"
+    assert E.resolve(None, None)["web_base"] == "https://webapi.acme.example"
+
+
+def test_add_trailing_slash_stripped():
+    entry = E.add("X-PROD", web_base="https://a/", app_base="https://b/",
+                  forms_base="https://c/")
+    assert entry["web_base"] == "https://a"
+    assert entry["app_base"] == "https://b"
+
+
+def test_add_requires_all_three_urls():
+    with pytest.raises(UsageError):
+        E.add("Y-PROD", web_base="https://a", app_base="", forms_base="https://c")
+
+
+def test_add_rejects_bad_name():
+    with pytest.raises(UsageError):
+        E.add("has space", web_base="https://a", app_base="https://b",
+              forms_base="https://c")
+
+
+def test_user_entry_overrides_builtin_url():
+    E.add("Internal-QA", web_base="https://moved-qa.example",
+          app_base="https://qa.moved.example",
+          forms_base="https://forms.moved.example")
+    assert E.get("Internal-QA")["web_base"] == "https://moved-qa.example"
+    # still flagged builtin (name is a built-in) but URL is the override
+    assert E.get("Internal-QA")["builtin"] is True
+
+
+def test_remove_builtin_blocked():
+    with pytest.raises(UsageError):
+        E.remove("Internal-DEV")
+
+
+def test_remove_user_env_resets_default():
+    E.add("Z-PROD", web_base="https://a", app_base="https://b", forms_base="https://c",
+          make_default=True)
+    assert E.get_default() == "Z-PROD"
+    E.remove("Z-PROD")
+    assert E.get_default() == "Internal-PROD"  # falls back
+
+
+def test_set_unknown_default_raises():
+    with pytest.raises(UsageError):
+        E.set_default("Ghost-PROD")
+
+
+# -- handler surface --------------------------------------------------------
+
+def test_set_environment_handler_reports_credentials(store):
+    from tools.procesio import profiles
+    profiles.save_profile("qa-key", {"type": "apikey", "key": "N", "value": "V",
+                                     "environment": "Internal-QA"})
+    out = EA.set_environment(argparse.Namespace(name="Internal-QA"))
+    assert out["default_environment"] == "Internal-QA"
+    assert out["credentials"] == ["qa-key"]
+
+
+def test_list_environments_marks_default_and_creds(store):
+    from tools.procesio import profiles
+    profiles.save_profile("dev-key", {"type": "apikey", "key": "N", "value": "V",
+                                      "environment": "Internal-DEV"})
+    out = EA.list_environments(argparse.Namespace())
+    by_name = {e["name"]: e for e in out["environments"]}
+    assert by_name["Internal-PROD"]["is_default"] is True
+    assert by_name["Internal-DEV"]["credentials"] == ["dev-key"]
+
+
+# -- client URL injection ---------------------------------------------------
+
+def _run(profile, session, environment=None):
+    c = ProcesioClient(profile=profile, name="t", session=session,
+                       environment=environment)
+    c.get("/api/Workspaces")
+    return c, session.calls[0]
+
+
+def test_client_injects_bound_environment_url():
+    sess = FakeSession(queue=[FakeResp(200, {})])
+    _, call = _run({"type": "apikey", "key": "N", "value": "V",
+                    "environment": "Internal-QA"}, sess)
+    assert call["url"] == "https://webapi-qa.procesio.app/api/Workspaces"
+
+
+def test_client_explicit_environment_overrides_binding():
+    sess = FakeSession(queue=[FakeResp(200, {})])
+    _, call = _run({"type": "apikey", "key": "N", "value": "V",
+                    "environment": "Internal-QA"}, sess, environment="Internal-DEV")
+    assert call["url"] == "https://webapi-dev.procesio.app/api/Workspaces"
+
+
+def test_client_unbound_is_prod():
+    sess = FakeSession(queue=[FakeResp(200, {})])
+    _, call = _run({"type": "apikey", "key": "N", "value": "V"}, sess)
+    assert call["url"] == "https://webapi.procesio.app/api/Workspaces"
+
+
+def test_explicit_profile_url_override_beats_environment():
+    sess = FakeSession(queue=[FakeResp(200, {})])
+    _, call = _run({"type": "apikey", "key": "N", "value": "V",
+                    "environment": "Internal-QA",
+                    "web_base": "https://custom.example"}, sess)
+    assert call["url"] == "https://custom.example/api/Workspaces"
+
+
+def test_client_does_not_mutate_caller_profile():
+    sess = FakeSession(queue=[FakeResp(200, {})])
+    original = {"type": "apikey", "key": "N", "value": "V",
+                "environment": "Internal-QA"}
+    ProcesioClient(profile=original, name="t", session=sess)
+    assert "web_base" not in original  # injection copied, never mutated the input
+
+
+def test_userpass_login_origin_is_environment_app_host(store):
+    # `store` isolates the token cache to in-memory creds, so login actually runs.
+    login_resp = FakeResp(200, {"message": "ok"},
+                          cookies={"__Host-procesio.access": "a.b.c"},
+                          headers={"x-session-expires-at": "9999999999"})
+    sess = FakeSession(queue=[login_resp, FakeResp(200, {})])
+    _run({"type": "userpass", "username": "u", "password": "p",
+          "environment": "Internal-QA"}, sess)
+    login = sess.calls[0]
+    assert login["url"] == "https://webapi-qa.procesio.app/api/authentication"
+    assert login["headers"]["Origin"] == "https://qa.procesio.app"

procesio_cli/tools/procesio/tests/test_fevalidate_gate.py

@@ -0,0 +1,104 @@
+"""Save-gate tests: FE (designer) + BE validation must block a process save unless
+--force. Uses a fake client so no network is touched."""
+import pytest
+
+from tools.procesio.errors import ValidationBlocked
+from tools.procesio.handlers import fevalidate
+from tools.procesio.dto.process import builder as pb
+
+
+class _FakeClient:
+    """Minimal client: serves an empty datatype catalog, an empty subprocess flow, and a
+    scripted /api/Projects/validate response."""
+
+    def __init__(self, be_valid=True):
+        self.be_valid = be_valid
+        self.posts = []
+
+    def get(self, path, query=None):
+        if path.startswith("/api/DataTypes"):
+            return {"pageItems": []}
+        if path.startswith("/api/Projects/"):
+            return {"flow": {"variables": []}}
+        return {}
+
+    def post(self, path, body=None, query=None):
+        self.posts.append(path)
+        if path == "/api/Projects/validate":
+            return {"raw_text": ""} if self.be_valid else {"errors": ["bad runtime"]}
+        return {}
+
+
+def _valid_dto():
+    def act(aid, name, tmpl, ports):
+        return {"id": aid, "actionName": name, "actionTemplateName": tmpl,
+                "customData": {"type": "square", "name": name, "configuration": []},
+                "ports": ports}
+    return {"actions": [
+        act("start", "Start", "Start", [{"sourceId": "start", "destinationId": "mid"}]),
+        act("mid", "Mid", "Concatenate", [{"sourceId": "mid", "destinationId": "stop"}]),
+        act("stop", "Stop", "Stop", [])], "variables": []}
+
+
+def _broken_dto():
+    # no Stop, unconnected Start -> FE errors
+    dto = _valid_dto()
+    dto["actions"] = [dto["actions"][0]]  # only Start, no ports target
+    dto["actions"][0]["ports"] = []
+    return dto
+
+
+def test_gate_passes_on_valid_flow():
+    rep = fevalidate.pre_save_validate(_FakeClient(be_valid=True), _valid_dto(), force=False)
+    assert rep["blocked"] is False
+    assert rep["fe"]["clean"] and rep["be"]["valid"]
+
+
+def test_gate_blocks_on_fe_errors():
+    with pytest.raises(ValidationBlocked) as ei:
+        fevalidate.pre_save_validate(_FakeClient(be_valid=True), _broken_dto(), force=False)
+    assert ei.value.report["fe"]["error_count"] > 0
+
+
+def test_gate_blocks_on_be_invalid():
+    with pytest.raises(ValidationBlocked):
+        fevalidate.pre_save_validate(_FakeClient(be_valid=False), _valid_dto(), force=False)
+
+
+def test_force_bypasses_block():
+    rep = fevalidate.pre_save_validate(_FakeClient(be_valid=False), _broken_dto(), force=True)
+    assert rep["blocked"] is True and rep["forced"] is True  # reported, not raised
+
+
+def test_process_component_has_save_gate_wired():
+    # the wiring the create/edit paths depend on
+    assert pb.COMPONENT.save_gate is not None
+
+
+def test_edit_runs_gate_and_blocks(monkeypatch):
+    # _edit builds the DTO then gates before PUT; a broken build must never reach PUT
+    calls = {"put": 0}
+    fake = _FakeClient(be_valid=True)
+
+    def fake_build(config, ctx):
+        return _broken_dto()
+
+    monkeypatch.setattr(pb, "build", fake_build)
+    fake.put = lambda *a, **k: calls.__setitem__("put", calls["put"] + 1)  # noqa: E731
+    with pytest.raises(ValidationBlocked):
+        pb._edit(fake, "some-id", {"title": "t", "actions": []}, {"_force": False})
+    assert calls["put"] == 0  # gate aborted before the PUT
+
+
+def test_flowlint_extras_folded_into_gate():
+    # flow-lint's unique designer save-blockers (here: Node code binding an error-scope
+    # variable) are merged into run_fe_validation as blocking errors.
+    from tools.procesio.handlers.flowlint import CODE_PID
+    flow = {"actions": [{
+        "actionName": "Compose", "actionTemplateName": "Node",
+        "customData": {"name": "Compose", "type": "square", "configuration": []},
+        "parameters": [{"tabPropertyId": CODE_PID, "value": "x",
+                        "variable": [{"id": 0, "variableId": "e1"}]}]}],
+        "variables": [{"id": "e1", "name": "err_x", "type": 20, "isError": True}]}
+    rep = fevalidate.run_fe_validation(_FakeClient(be_valid=True), flow, include_types=False)
+    assert any(e["code"] == "CODE_ERROR_SCOPE" for e in rep["errors"])