"CLI-Anything: Making ALL Software Agent-Native" -- CLI-Hub: https://clianything.cc/
Python
fix(n8n): send only the fields the workflow API accepts (#413)
richardhxwangd71d4a240b57
diff --git a/n8n/agent-harness/cli_anything/n8n/n8n_cli.py b/n8n/agent-harness/cli_anything/n8n/n8n_cli.pyindex 390ee85e2..b1f2e7ec4 100644--- a/n8n/agent-harness/cli_anything/n8n/n8n_cli.py+++ b/n8n/agent-harness/cli_anything/n8n/n8n_cli.py@@ -45,9 +45,71 @@ def _safe_filename(name: str) -> str:return name[:60] or "workflow"-# Fields to strip when sending workflow data to n8n API+# Server-owned fields, stripped from workflow data kept locally (backups, diffs) so+# instance-specific noise does not drown the actual content._INTERNAL_FIELDS = frozenset({"id", "createdAt", "updatedAt", "versionId", "shared"})+# Fields n8n accepts in a create/update body: the non-readOnly properties of the+# public API workflow schema+# (packages/cli/src/public-api/v1/handlers/workflows/spec/schemas/workflow.yml).+# That schema sets additionalProperties:false and marks `active`, `tags`, `meta`,+# `isArchived`, `triggerCount` and the id/timestamp fields readOnly, so sending any+# of them rejects the entire request with 400. `active` and `tags` are changed+# through their own endpoints (activate/deactivate, PUT /workflows/{id}/tags).+# Checked against the schema on n8n 2.16.1 and 2.33.3; `nodeGroups` and+# `parentFolderId` only exist on the latter, and are listed so an edit made against+# a newer instance does not silently drop node groups or move a workflow to the root.+_API_WRITABLE_FIELDS = frozenset({+ "name", "description", "nodes", "connections", "settings",+ "staticData", "pinData", "nodeGroups", "parentFolderId",+})++# Of those, the ones that are nullable in the schema. For them null is meaningful —+# it clears the stored value, whereas omitting the key leaves it alone — so their+# nulls have to be forwarded. `versions rollback` depends on this: a snapshot taken+# before any pinned data was added carries `pinData: null`, and dropping it would+# leave today's pinned data in place while reporting a successful rollback.+# `parentFolderId` documents null as "move it to the project root".+# The rest are non-nullable (`description` is a plain string), and echoing back the+# null that a GET returned is rejected outright.+_API_NULLABLE_FIELDS = frozenset({"staticData", "pinData", "parentFolderId"})++# Writable, but only present from n8n 2.33.3. An older instance does not define them+# and rejects the request outright, so a file exported from a newer one cannot be+# imported as-is. Rather than probe the target's version, the write is retried+# without them — losing a canvas grouping beats losing the whole import.+_NEWER_SCHEMA_FIELDS = frozenset({"nodeGroups", "parentFolderId"})++# The nested settings object sets additionalProperties:false as well (schemas/+# workflowSettings.yml). n8n's own editor stores keys the public API does not define+# — `binaryMode` is written into every workflow created in the UI — so settings read+# back from the server have to be reduced too, or the whole request is rejected with+# `request/body/settings must NOT have additional properties`.+_API_WRITABLE_SETTINGS = frozenset({+ "saveExecutionProgress", "saveManualExecutions", "saveDataErrorExecution",+ "saveDataSuccessExecution", "executionTimeout", "errorWorkflow", "timezone",+ "executionOrder", "callerPolicy", "callerIds", "timeSavedPerExecution",+ "availableInMCP",+ # Added by 2.33.3. Listed for the same reason as the top-level ones: on a current+ # instance these are writable, and omitting them would silently reset the user's+ # choice. `binaryMode` in particular is written by the editor into every workflow.+ "binaryMode", "credentialResolverId", "customTelemetryTags",+ "redactionPolicy", "timeSavedMode",+})++# The nested counterpart of _NEWER_SCHEMA_FIELDS: settings properties an older+# instance does not define, which its additionalProperties:false rejects.+# The validator's wording for an unexpected property, and the only two error paths+# the compatibility retry knows how to reduce. Anything deeper — an unexpected member+# inside a node or a grouping — is malformed input, not a version difference.+_UNKNOWN_PROPERTY_SUFFIX = " must NOT have additional properties"+_REDUCIBLE_ERROR_PATHS = frozenset({"request/body", "request/body/settings"})++_NEWER_SCHEMA_SETTINGS = frozenset({+ "binaryMode", "credentialResolverId", "customTelemetryTags",+ "redactionPolicy", "timeSavedMode",+})+def _conn(ctx: click.Context) -> dict[str, str]:"""Extract connection kwargs from Click context."""@@ -59,10 +121,168 @@ def _json_flag(ctx: click.Context) -> bool:def _clean_for_api(data: dict[str, Any]) -> dict[str, Any]:- """Remove n8n internal fields before sending to API."""+ """Keep only the fields n8n accepts in a workflow create/update body.++ Nulls are dropped for the non-nullable properties: `description` is a plain+ string in the schema, so echoing back the null a GET returned is rejected with+ `request/body/description must be string`, and omitting the key instead leaves+ the stored value untouched. Nulls for `_API_NULLABLE_FIELDS` are kept, because+ for those null is the only way to clear the value.++ `settings` is required and has its own additionalProperties:false, so it is+ always present and always reduced.+ """+ body = {+ k: v for k, v in data.items()+ if k in _API_WRITABLE_FIELDS and (v is not None or k in _API_NULLABLE_FIELDS)+ }+ settings = body.get("settings")+ if isinstance(settings, dict):+ body["settings"] = {k: v for k, v in settings.items() if k in _API_WRITABLE_SETTINGS}+ elif settings is None:+ body["settings"] = {} # required by the schema; absent in older exports+ # Anything else is left untouched, so the server rejects it by name rather than+ # this quietly replacing what the caller wrote with an empty object.+ return body+++def _strip_server_fields(data: dict[str, Any]) -> dict[str, Any]:+ """Drop server-owned fields from a workflow kept locally.++ Unlike _clean_for_api this preserves state such as `active` and `tags`, which a+ backup has to record and a diff has to compare even though neither can be sent+ back through the workflow endpoint.+ """return {k: v for k, v in data.items() if k not in _INTERNAL_FIELDS}+def _diag(msg: str) -> None:+ """Warn on stderr, so `--json` output stays parseable.++ `warn()` prints to stdout (repl_skin.py), which is fine for the interactive+ commands that use it but would corrupt the documented machine-readable output+ exactly when one of these fallbacks fires. repl_skin.py is a verbatim copy of the+ plugin's and is meant to stay that way, so this goes around it rather than+ changing it.+ """+ click.secho(f" ⚠ {msg}", fg="yellow", err=True)+++def _without_newer_schema_fields(payload: dict[str, Any]) -> tuple[dict[str, Any], set[str]]:+ """Strip properties that only exist in newer n8n schemas, top level and nested.++ `settings` carries its own additionalProperties:false, so an incompatible key in+ there fails the request just as a top-level one does — dropping only the outer+ ones would retry and fail again.+ """+ dropped = set(_NEWER_SCHEMA_FIELDS) & set(payload)+ reduced = {k: v for k, v in payload.items() if k not in _NEWER_SCHEMA_FIELDS}+ settings = reduced.get("settings")+ if isinstance(settings, dict):+ in_settings = _NEWER_SCHEMA_SETTINGS & set(settings)+ if in_settings:+ reduced["settings"] = {+ k: v for k, v in settings.items() if k not in _NEWER_SCHEMA_SETTINGS+ }+ dropped |= {f"settings.{k}" for k in in_settings}+ return reduced, dropped+++def _is_unknown_property_error(exc: requests.exceptions.HTTPError) -> bool:+ """True when a 400 says the payload has a property the target does not define.++ The suffix alone is not enough: the validator reports the same wording for an+ unexpected member nested anywhere, and only the two levels this retry actually+ reduces are safe to act on.++ retryable request/body must NOT have additional properties+ request/body/settings must NOT have additional properties+ not retryable request/body/nodes/0 must NOT have additional properties+ request/body/nodeGroups/0 must NOT have additional properties+ request/body/description must be string+ request/body/settings/executionTimeout must be number++ The third line is the dangerous one: malformed input inside a grouping would+ otherwise be read as a version mismatch, and dropping the whole grouping could+ turn an invalid request into a success that quietly lost data.+ """+ try:+ message = str(exc.response.json().get("message", ""))+ except (ValueError, AttributeError, TypeError):+ return False+ if not message.endswith(_UNKNOWN_PROPERTY_SUFFIX):+ return False+ return message[: -len(_UNKNOWN_PROPERTY_SUFFIX)] in _REDUCIBLE_ERROR_PATHS+++def _send_workflow(send: Any, payload: dict[str, Any]) -> Any:+ """Send a workflow write, retrying once without newer-schema-only properties.++ Importing a file exported from n8n 2.33.3+ into an older instance fails on+ `nodeGroups` / `parentFolderId`, which that schema does not define. The target's+ version is not exposed anywhere cheap to query, so this reacts to the rejection+ instead and says what it dropped.+ """+ try:+ return send(payload)+ except requests.exceptions.HTTPError as exc:+ if getattr(exc.response, "status_code", None) != 400:+ raise+ if not _is_unknown_property_error(exc):+ raise+ reduced, dropped = _without_newer_schema_fields(payload)+ if not dropped:+ raise+ # Say what is known — a 400 with these keys present — rather than asserting+ # they caused it. The retry is a guess; if it fails the real error stands.+ _diag(f"Write rejected with 400 — retrying without {', '.join(sorted(dropped))}")+ return send(reduced)+++def _create_workflow(payload: dict[str, Any], conn: dict[str, str]) -> Any:+ return _send_workflow(lambda body: workflows.create_workflow(body, **conn), payload)+++def _update_workflow(workflow_id: str, payload: dict[str, Any], conn: dict[str, str]) -> Any:+ return _send_workflow(lambda body: workflows.update_workflow(workflow_id, body, **conn), payload)+++def _reapply_tags(workflow_id: str | None, tags: Any, conn: dict[str, str]) -> None:+ """Restore tag assignments through the endpoint that owns them.++ `tags` is readOnly on the workflow body, so anything that recreates or rewinds a+ workflow leaves them behind unless they are set separately. Passing None means+ the source did not record any (an older export, say) and the current assignment+ is left alone; an empty list means the source had none and clears them.++ Tag ids are per-instance, so restoring into a different n8n answers+ `404 Some tags not found`. That is reported rather than raised — the workflow+ itself is already in place, and failing the whole restore over it would be worse.+ """+ if not workflow_id or tags is None:+ return+ if not isinstance(tags, (list, tuple)):+ # A scalar here would raise on the comprehension below — after the workflow+ # has already been created, so the caller would report a failure for+ # something that exists, and a retry of restore-all would duplicate it.+ _diag(f"Tags on {workflow_id} are not a list — left unchanged")+ return+ tag_ids = [{"id": t["id"]} for t in tags if isinstance(t, dict) and t.get("id")]+ if tags and not tag_ids:+ # The source recorded tags but none of them carry an id. Sending the empty+ # list here would clear the assignment, which is the opposite of what an+ # unreadable record should do.+ _diag(f"Tags on {workflow_id} could not be read from the source — left unchanged")+ return+ try:+ workflows.update_workflow_tags(workflow_id, tag_ids, **conn)+ except requests.exceptions.RequestException:+ # Not just HTTPError: a timeout or dropped connection here would otherwise+ # escape and make the caller count an already-created workflow as failed,+ # so a retry would duplicate it.+ _diag(f"Could not restore tags on {workflow_id} — reattach them manually")++def _auto_snapshot(workflow_id: str, conn: dict[str, str], trigger: str) -> None:"""Save a version snapshot before modifying a workflow."""try:@@ -320,8 +540,12 @@ def workflow_get(ctx: click.Context, workflow_id: str) -> None:def workflow_create(ctx: click.Context, json_data: str) -> None:"""Create a workflow from JSON (inline or @file.json). Workflows are created inactive."""payload = _load_json_arg(json_data)- payload.pop("active", None) # Never auto-activate on create- data = workflows.create_workflow(payload, **_conn(ctx))+ tags = payload.get("tags")+ # A file produced by `export` carries state the endpoint refuses; reduce it here+ # so hand-written and exported JSON both work. `active` is readOnly, so workflows+ # are created inactive either way.+ data = _create_workflow(_clean_for_api(payload), _conn(ctx))+ _reapply_tags(data.get("id"), tags, _conn(ctx))output(data, _json_flag(ctx))@@ -333,8 +557,10 @@ def workflow_update(ctx: click.Context, workflow_id: str, json_data: str) -> Non"""Update a workflow. Does not change active status — use activate/deactivate."""_auto_snapshot(workflow_id, _conn(ctx), "update")payload = _load_json_arg(json_data)- payload.pop("active", None) # Don't change active status via update- data = workflows.update_workflow(workflow_id, payload, **_conn(ctx))+ # Same reduction as every other write: a file straight out of `export` has to be+ # usable here. `active` is readOnly, so this cannot change it — use+ # activate/deactivate. Tags likewise have their own command (`set-tags`).+ data = _update_workflow(workflow_id, _clean_for_api(payload), _conn(ctx))output(data, _json_flag(ctx))@@ -411,8 +637,10 @@ def workflow_export(ctx: click.Context, workflow_id: str, out_path: str | None)if not out_path:name = _safe_filename(data.get("name", workflow_id))out_path = f"{name}.json"- # Remove server-specific fields for portability- export_data = _clean_for_api(data)+ # Remove server-specific fields for portability, but keep the state an export is+ # expected to carry (`tags`, `active`). Reducing it to the writable set here would+ # lose the tags, which `import` puts back through their own endpoint.+ export_data = _strip_server_fields(data)out = Path(out_path)if out.exists():warn(f"File {out_path} already exists — overwriting")@@ -431,13 +659,14 @@ def workflow_import(ctx: click.Context, file_path: str, name: str | None) -> Nonif not isinstance(data, dict):error("Invalid workflow format: must be a JSON object, not array or string")return- # Remove fields that would conflict on import- for field in ("id", "createdAt", "updatedAt", "versionId", "shared"):- data.pop(field, None)- data["active"] = False # Never auto-activate imported workflows+ # Keep only what n8n accepts. `active` is readOnly on the workflow endpoint, so+ # it cannot be set here — workflows are created inactive regardless.+ tags = data.get("tags")+ data = _clean_for_api(data)if name:data["name"] = name- result = workflows.create_workflow(data, **_conn(ctx))+ result = _create_workflow(data, _conn(ctx))+ _reapply_tags(result.get("id"), tags, _conn(ctx))success(f"Imported as workflow {result.get('id', '?')} — {result.get('name', '?')}")output(result, _json_flag(ctx))@@ -475,7 +704,7 @@ def workflow_backup_all(ctx: click.Context, out_dir: str, active_only: bool) ->wf_id = w.get("id", "unknown")try:full = workflows.get_workflow(wf_id, **conn)- export_data = _clean_for_api(full)+ export_data = _strip_server_fields(full)name_safe = _safe_filename(full.get("name", wf_id))filename = f"{wf_id}_{name_safe}.json"(out_path / filename).write_text(json.dumps(export_data, indent=2, default=str))@@ -522,10 +751,11 @@ def workflow_restore_all(ctx: click.Context, backup_dir: str, dry_run: bool) ->click.echo(f" Would import: {name}")ok += 1continue- for field in ("id", "createdAt", "updatedAt", "versionId", "shared"):- data.pop(field, None)- data["active"] = False # Never auto-activate restored workflows- result = workflows.create_workflow(data, **conn)+ # A backup keeps state the workflow endpoint refuses (`active`, `tags`);+ # restore reduces it to the writable definition and puts the tags back+ # through their own endpoint.+ result = _create_workflow(_clean_for_api(data), conn)+ _reapply_tags(result.get("id"), data.get("tags"), conn)click.secho(f" {result.get('id', '?')} {name}", fg="green")ok += 1except Exception as exc:@@ -557,7 +787,7 @@ def workflow_diff(ctx: click.Context, source: str, target: str) -> None:return workflows.get_workflow(ref, **conn)def _clean(data: dict) -> dict:- return _clean_for_api(data)+ return _strip_server_fields(data)src = _clean(_load(source))tgt = _clean(_load(target))@@ -1038,16 +1268,16 @@ def template_deploy(ctx: click.Context, template_id: int, name: str | None) -> Nwf_wrapper = data.get("workflow", {})wf_data = wf_wrapper.get("workflow", wf_wrapper) if isinstance(wf_wrapper, dict) else {}- # Clean for import — never auto-activate- for field in ("id", "createdAt", "updatedAt", "versionId", "shared"):- wf_data.pop(field, None)- wf_data["active"] = False+ # Keep only what n8n accepts; `active` is readOnly, so a template always lands+ # inactive. n8n.io templates often omit `settings`, which the API requires —+ # _clean_for_api supplies it.+ wf_data = _clean_for_api(wf_data)if name:wf_data["name"] = nameelif not wf_data.get("name"):wf_data["name"] = f"Template #{template_id}"- result = workflows.create_workflow(wf_data, **conn)+ result = _create_workflow(wf_data, conn)success(f"Deployed as workflow {result.get('id', '?')} — {result.get('name', '?')}")output(result, _json_flag(ctx))@@ -1193,7 +1423,7 @@ def workflow_autofix(ctx: click.Context, source: str, apply: bool, save_path: stelif apply and wf_id:_auto_snapshot(wf_id, conn, "autofix")update_data = _clean_for_api(fixed_wf)- workflows.update_workflow(wf_id, update_data, **conn)+ _update_workflow(wf_id, update_data, conn)success(f"Applied {len(fixes)} fix(es) to workflow {wf_id}")elif apply and not wf_id:error("Cannot apply fixes to a file source. Use --save instead.")@@ -1310,7 +1540,7 @@ def workflow_patch(ctx: click.Context, workflow_id: str, rename: str | None, ena_auto_snapshot(workflow_id, conn, "patch")update_data = _clean_for_api(wf)- result = workflows.update_workflow(workflow_id, update_data, **conn)+ result = _update_workflow(workflow_id, update_data, conn)output(result, _json_flag(ctx))@@ -1455,7 +1685,8 @@ def versions_rollback(ctx: click.Context, workflow_id: str, ver_num: int | None)pass # May already be inactiveupdate_data = _clean_for_api(snapshot)update_data.pop("active", None)- workflows.update_workflow(workflow_id, update_data, **conn)+ _update_workflow(workflow_id, update_data, conn)+ _reapply_tags(workflow_id, snapshot.get("tags"), conn)success(f"Rolled back workflow {workflow_id} to version {ver_num} (deactivated — use activate to enable)")@@ -1493,7 +1724,7 @@ def versions_diff(ctx: click.Context, workflow_id: str, version_a: int, version_returndef _clean(d: dict) -> str:- clean = {k: v for k, v in d.items() if k not in ("id", "createdAt", "updatedAt", "versionId", "shared")}+ clean = _strip_server_fields(d)return json.dumps(clean, indent=2, sort_keys=True, default=str)lines_a = _clean(snap_a).splitlines(keepends=True)@@ -1698,7 +1929,7 @@ def workflow_scaffold(ctx: click.Context, pattern: str, name: str | None, deployreturnif deploy:- result = workflows.create_workflow(wf, **_conn(ctx))+ result = _create_workflow(_clean_for_api(wf), _conn(ctx))success(f"Deployed '{wf['name']}' as workflow {result.get('id', '?')}")output(result, _json_flag(ctx))elif out_path:diff --git a/n8n/agent-harness/cli_anything/n8n/tests/test_api_payload_fields.py b/n8n/agent-harness/cli_anything/n8n/tests/test_api_payload_fields.pynew file mode 100644index 000000000..09f866542--- /dev/null+++ b/n8n/agent-harness/cli_anything/n8n/tests/test_api_payload_fields.py@@ -0,0 +1,461 @@+"""Payload shape for workflow writes.++The n8n public API workflow schema sets `additionalProperties: false` and marks+`active`, `tags`, `meta`, `isArchived`, `triggerCount` and the id/timestamp fields+`readOnly`, so a create/update body carrying any of them is rejected outright with+`400 - request/body must NOT have additional properties`.++Every command that edits an existing workflow builds its payload from a GET+response, so the payload has to be reduced first. These tests pin that reduction and+keep it distinct from the local-only reduction used by backups and diffs, which has+to preserve exactly the state the API refuses.++No n8n instance required.+"""++import json+from unittest.mock import patch++import pytest+import requests++from cli_anything.n8n import n8n_cli+from cli_anything.n8n.n8n_cli import _clean_for_api, _load_json_arg++# Every key a GET /workflows/{id} returns on n8n 2.16.1, plus the two properties the+# schema gained by 2.33.3 (`nodeGroups`, `parentFolderId`).+SERVER_WORKFLOW = {+ "id": "abc123",+ "name": "Test WF",+ "nodes": [{"type": "n8n-nodes-base.manualTrigger"}],+ "connections": {},+ "settings": {},+ "staticData": {"lastId": 1},+ "pinData": {"Test Node": [{"json": {"x": 1}}]},+ "description": "a description",+ "nodeGroups": [{"name": "group A"}],+ "parentFolderId": "fld123",+ "active": False,+ "activeVersion": None,+ "activeVersionId": None,+ "isArchived": False,+ "meta": {},+ "tags": [],+ "triggerCount": 0,+ "versionCounter": 1,+ "versionId": "v1",+ "createdAt": "2026-01-01",+ "updatedAt": "2026-01-02",+ "shared": [{"role": "owner"}],+}++# readOnly in the schema, or absent from it entirely. Each one draws a 400.+REJECTED_BY_API = (+ "active",+ "activeVersion",+ "activeVersionId",+ "isArchived",+ "meta",+ "tags",+ "triggerCount",+ "versionCounter",+ "id",+ "createdAt",+ "updatedAt",+ "versionId",+)++# Writable per the schema, and confirmed to persist by reading the workflow back.+WRITABLE = (+ "name",+ "description",+ "nodes",+ "connections",+ "settings",+ "staticData",+ "pinData",+ "nodeGroups",+ "parentFolderId",+)+++def strip_server_fields(data):+ """`_strip_server_fields` via the module, so upstream builds skip instead of erroring."""+ fn = getattr(n8n_cli, "_strip_server_fields", None)+ if fn is None:+ pytest.skip("_strip_server_fields not present in this build")+ return fn(data)+++# ─── Write payload ──────────────────────────────────────────────────────────++class TestWritePayload:+ def test_drops_every_field_the_api_rejects(self):+ cleaned = _clean_for_api(SERVER_WORKFLOW)+ leaked = [f for f in REJECTED_BY_API if f in cleaned]+ assert not leaked, f"payload would be rejected by n8n, extra fields: {leaked}"++ def test_keeps_writable_fields(self):+ """Narrowing this further would silently discard user data.++ pinData holds pinned sample data, staticData holds stateful-trigger cursors+ and nodeGroups holds the canvas grouping — none of them survive an edit that+ drops them, and none of them fail loudly.+ """+ cleaned = _clean_for_api(SERVER_WORKFLOW)+ for field in WRITABLE:+ assert field in cleaned, f"{field} must survive a workflow edit"++ def test_drops_a_field_the_schema_does_not_define(self):+ """A key from a future n8n release must not reach the API by default.++ This is what a blacklist cannot do: it only removes what it already knows.+ """+ cleaned = _clean_for_api({**SERVER_WORKFLOW, "someFieldAddedLater": "x"})+ assert "someFieldAddedLater" not in cleaned++ def test_drops_nulls_for_non_nullable_properties(self):+ """`description` is a plain string in the schema, so a null round-trip 400s.++ A workflow with no description reads back as `"description": null`, which is+ exactly what a backup or an export then tries to send.+ """+ cleaned = _clean_for_api({**SERVER_WORKFLOW, "description": None})+ assert "description" not in cleaned++ def test_keeps_nulls_for_nullable_properties(self):+ """For these, null is the only way to clear the value — dropping it is a bug.++ `versions rollback` restores a snapshot: one taken before any pinned data was+ added carries `pinData: null`, and omitting that key would leave today's+ pinned data in place while the command reports a successful rollback.+ """+ cleaned = _clean_for_api(+ {**SERVER_WORKFLOW, "pinData": None, "staticData": None, "parentFolderId": None}+ )+ assert cleaned["pinData"] is None+ assert cleaned["staticData"] is None+ assert cleaned["parentFolderId"] is None # documented as "move to the project root"++ def test_always_supplies_the_required_settings_object(self):+ """`settings` is required by the schema; handwritten and older exports omit it."""+ wf = {k: v for k, v in SERVER_WORKFLOW.items() if k != "settings"}+ assert _clean_for_api(wf)["settings"] == {}+ assert _clean_for_api({**SERVER_WORKFLOW, "settings": None})["settings"] == {}++ def test_leaves_a_non_object_settings_for_the_server_to_reject(self):+ """Replacing it with `{}` would drop what the caller wrote without saying so.++ `settings` has to be an object, so a string or a list is invalid input — but+ that is the server's verdict to give, by name.+ """+ for bad in ("nope", [1], 5):+ assert _clean_for_api({**SERVER_WORKFLOW, "settings": bad})["settings"] == bad++ def test_reduces_the_nested_settings_object_too(self):+ """The nested object is additionalProperties:false as well, so an unreduced+ settings block fails the request even when the top level is clean."""+ wf = {**SERVER_WORKFLOW, "settings": {"executionOrder": "v1", "notASetting": 1}}+ assert _clean_for_api(wf)["settings"] == {"executionOrder": "v1"}++ def test_keeps_settings_that_only_newer_schemas_define(self):+ """`binaryMode` is written into every workflow by the editor and became+ writable in 2.33.3, so stripping it here would reset the user's choice on a+ current instance. An older instance rejects it, and the cross-version retry+ is what drops it — at the cost of one failed request, which beats silently+ changing a setting.+ """+ wf = {**SERVER_WORKFLOW, "settings": {"executionOrder": "v1", "binaryMode": "separate"}}+ assert _clean_for_api(wf)["settings"]["binaryMode"] == "separate"++ def test_drops_shared_even_though_the_api_tolerates_it(self):+ """`shared` is ownership data, not part of the definition.++ Unlike the rejected fields it does not draw a 400 — the API answers 200 and+ ignores it (confirmed by reading the workflow back afterwards). That is+ precisely why it needs pinning here: a failing request would not catch it.+ """+ assert "shared" not in _clean_for_api(SERVER_WORKFLOW)++ def test_export_output_can_be_fed_back_to_update(self, tmp_path):+ """Helper-level stand-in for `workflow export` -> `workflow update @file.json`.++ It repeats what those two commands do to the payload rather than invoking+ them, so it pins the reduction, not the click plumbing.+ """+ exported = strip_server_fields(SERVER_WORKFLOW) # what workflow_export writes+ out = tmp_path / "export.json"+ out.write_text(json.dumps(exported, indent=2))++ payload = _clean_for_api(_load_json_arg(f"@{out}")) # what workflow_update sends+ leaked = [f for f in REJECTED_BY_API if f in payload]+ assert not leaked, f"export cannot be fed back into update, extra fields: {leaked}"+++# ─── Local-only payload ─────────────────────────────────────────────────────++class TestLocalPayload:+ def test_backup_keeps_state_the_api_refuses(self):+ """A backup that drops `active`/`tags` cannot restore what it recorded."""+ kept = strip_server_fields(SERVER_WORKFLOW)+ for field in ("active", "tags", "isArchived"):+ assert field in kept, f"{field} must stay in a backup"++ def test_backup_drops_instance_specific_fields(self):+ kept = strip_server_fields(SERVER_WORKFLOW)+ for field in ("id", "createdAt", "updatedAt", "versionId", "shared"):+ assert field not in kept++ def test_diff_can_still_see_a_state_only_change(self):+ """Two workflows differing only in `active` must not compare as identical."""+ a = {**SERVER_WORKFLOW, "active": False}+ b = {**SERVER_WORKFLOW, "active": True}+ assert strip_server_fields(a) != strip_server_fields(b)+++# ─── Tag reassignment ───────────────────────────────────────────────────────++class TestReapplyTags:+ """`tags` is readOnly on the workflow body and has its own endpoint.++ Anything that recreates or rewinds a workflow therefore loses its tags unless+ they are set separately — and loses them *silently*, since the create itself+ succeeds.+ """++ @staticmethod+ def _reapply():+ fn = getattr(n8n_cli, "_reapply_tags", None)+ if fn is None:+ pytest.skip("_reapply_tags not present in this build")+ return fn++ def test_leaves_tags_alone_when_the_source_recorded_none(self):+ """An older export has no `tags` key at all — that is not "clear the tags"."""+ with patch.object(n8n_cli.workflows, "update_workflow_tags") as mock_put:+ self._reapply()("wf1", None, {})+ mock_put.assert_not_called()++ def test_clears_tags_when_the_source_had_an_empty_list(self):+ """Rolling back to a snapshot taken before any tag existed must remove them."""+ with patch.object(n8n_cli.workflows, "update_workflow_tags") as mock_put:+ self._reapply()("wf1", [], {})+ mock_put.assert_called_once_with("wf1", [])++ def test_sends_only_ids(self):+ """A backup records the whole tag object; the endpoint takes ids."""+ tags = [{"id": "t1", "name": "prod", "createdAt": "2026-01-01"}, {"name": "no id"}]+ with patch.object(n8n_cli.workflows, "update_workflow_tags") as mock_put:+ self._reapply()("wf1", tags, {})+ mock_put.assert_called_once_with("wf1", [{"id": "t1"}])++ def test_leaves_tags_alone_when_none_of_them_carry_an_id(self):+ """An unreadable record must not be treated as "the source had no tags".++ Filtering the ids out of a non-empty list yields an empty list, and sending+ that would clear every tag on the workflow.+ """+ with patch.object(n8n_cli.workflows, "update_workflow_tags") as mock_put:+ self._reapply()("wf1", [{"name": "prod"}, {"nope": 1}], {})+ mock_put.assert_not_called()++ def test_survives_a_tags_value_that_is_not_a_list(self):+ """A scalar would raise on iteration — after the workflow already exists.++ The caller would then report a failure for something that was created, and+ a `restore-all` retry would duplicate it.+ """+ for bad in (1, 1.5, True):+ with patch.object(n8n_cli.workflows, "update_workflow_tags") as mock_put:+ self._reapply()("wf1", bad, {}) # must not raise+ mock_put.assert_not_called()++ def test_survives_a_timeout_not_just_an_http_error(self):+ """The workflow is already created; a tag timeout must not fail the caller.++ `restore-all` would otherwise count the file as failed and a retry would+ create a duplicate workflow.+ """+ for err in (requests.exceptions.Timeout(), requests.exceptions.ConnectionError()):+ with patch.object(n8n_cli.workflows, "update_workflow_tags", side_effect=err):+ self._reapply()("wf1", [{"id": "t1"}], {}) # must not raise++ def test_reports_but_does_not_raise_when_the_ids_are_unknown(self):+ """Restoring into a different instance answers 404 Some tags not found.++ The workflow itself is already created at that point, so failing the whole+ restore over its tags would lose more than it protects.+ """+ err = requests.exceptions.HTTPError("404 Some tags not found")+ with patch.object(n8n_cli.workflows, "update_workflow_tags", side_effect=err):+ self._reapply()("wf1", [{"id": "gone"}], {}) # must not raise++ def test_export_keeps_tags_so_import_can_restore_them(self):+ """`export` writes the local form; the tags are what `import` reattaches.++ Reducing the export to the writable set instead would drop them silently —+ the file would still import, just without its tags.+ """+ exported = strip_server_fields({**SERVER_WORKFLOW, "tags": [{"id": "t1", "name": "prod"}]})+ assert exported["tags"] == [{"id": "t1", "name": "prod"}]+++# ─── Cross-version writes ───────────────────────────────────────────────────++class TestNewerSchemaFallback:+ """A file exported from n8n 2.33.3+ has to remain importable into an older one.++ `nodeGroups` and `parentFolderId` do not exist in the older schema, whose+ additionalProperties:false rejects the whole request.+ """++ @staticmethod+ def _send():+ fn = getattr(n8n_cli, "_send_workflow", None)+ if fn is None:+ pytest.skip("_send_workflow not present in this build")+ return fn++ @staticmethod+ def _http_error(status, message="request/body must NOT have additional properties"):+ resp = type("R", (), {"status_code": status, "json": lambda self: {"message": message}})()+ return requests.exceptions.HTTPError(response=resp)++ def test_retries_without_the_newer_properties(self):+ seen = []++ def send(body):+ seen.append(dict(body))+ if "nodeGroups" in body:+ raise self._http_error(400)+ return {"id": "wf1"}++ payload = {"name": "x", "nodes": [], "nodeGroups": [{"name": "g"}], "parentFolderId": "f1"}+ assert self._send()(send, payload) == {"id": "wf1"}+ assert len(seen) == 2+ assert "nodeGroups" not in seen[1] and "parentFolderId" not in seen[1]+ assert seen[1]["name"] == "x" # everything else survives++ def test_also_strips_newer_properties_nested_in_settings(self):+ """`settings` is additionalProperties:false too — dropping only the outer+ ones would retry and fail on the same request."""+ seen = []++ def send(body):+ seen.append({**body, "settings": dict(body.get("settings", {}))})+ if "binaryMode" in body.get("settings", {}):+ raise self._http_error(400)+ return {"id": "wf1"}++ payload = {+ "name": "x",+ "nodes": [],+ "settings": {"executionOrder": "v1", "binaryMode": "separate"},+ }+ assert self._send()(send, payload) == {"id": "wf1"}+ assert len(seen) == 2+ assert seen[1]["settings"] == {"executionOrder": "v1"}++ def test_does_not_retry_when_the_payload_has_none_of_them(self):+ """A 400 about something else must surface, not be masked by a pointless retry."""+ calls = []++ def send(body):+ calls.append(body)+ raise self._http_error(400)++ with pytest.raises(requests.exceptions.HTTPError):+ self._send()(send, {"name": "x", "nodes": []})+ assert len(calls) == 1++ def test_does_not_retry_on_other_status_codes(self):+ def send(body):+ raise self._http_error(401)++ with pytest.raises(requests.exceptions.HTTPError):+ self._send()(send, {"name": "x", "nodeGroups": []})++ def test_does_not_retry_when_the_400_is_about_a_bad_value(self):+ """A rejected *value* must surface, not be silenced by dropping the property.++ n8n answers `must be number` / `must be string` for these, as opposed to+ `must NOT have additional properties`. Retrying without the property would+ drop configuration the caller asked for and then report success — which is+ worse than the original failure, because it looks like it worked.+ """+ calls = []++ def send(body):+ calls.append(body)+ raise self._http_error(400, "request/body/settings/executionTimeout must be number")++ payload = {"name": "x", "nodes": [], "nodeGroups": [{"name": "g"}]}+ with pytest.raises(requests.exceptions.HTTPError):+ self._send()(send, payload)+ assert len(calls) == 1, "a bad value must not trigger the compatibility retry"++ def test_does_not_retry_when_the_offending_property_is_nested_deeper(self):+ """Same wording, different meaning: this is malformed input, not a version gap.++ A grouping whose item carries an unexpected member reports+ `request/body/nodeGroups/0 must NOT have additional properties`. Treating+ that as a compatibility problem would drop the entire grouping and could+ then succeed — turning invalid input into a success that lost data.+ """+ for path in ("request/body/nodeGroups/0", "request/body/nodes/0"):+ calls = []++ def send(body):+ calls.append(body)+ raise self._http_error(400, f"{path} must NOT have additional properties")++ with pytest.raises(requests.exceptions.HTTPError):+ self._send()(send, {"name": "x", "nodeGroups": [{"name": "g", "bogus": 1}]})+ assert len(calls) == 1, f"{path} must not trigger the compatibility retry"++ def test_retries_for_both_reducible_paths(self):+ """The two levels the retry actually reduces."""+ for path in ("request/body", "request/body/settings"):+ calls = []++ def send(body):+ calls.append(body)+ if len(calls) == 1:+ raise self._http_error(400, f"{path} must NOT have additional properties")+ return {"id": "wf1"}++ payload = {"name": "x", "nodeGroups": [], "settings": {"binaryMode": "separate"}}+ assert self._send()(send, payload) == {"id": "wf1"}+ assert len(calls) == 2++ def test_does_not_retry_when_the_error_body_is_unreadable(self):+ """No message to inspect means no evidence for a compatibility problem."""+ resp = type("R", (), {"status_code": 400, "json": lambda self: (_ for _ in ()).throw(ValueError())})()+ calls = []++ def send(body):+ calls.append(body)+ raise requests.exceptions.HTTPError(response=resp)++ with pytest.raises(requests.exceptions.HTTPError):+ self._send()(send, {"name": "x", "nodeGroups": []})+ assert len(calls) == 1++++# ─── Diagnostics ────────────────────────────────────────────────────────────++class TestDiagnosticsStream:+ def test_fallback_diagnostics_go_to_stderr(self, capsys):+ """`--json` output has to stay parseable when a fallback fires.++ `warn()` prints to stdout, so the diagnostics on these paths deliberately+ do not use it.+ """+ diag = getattr(n8n_cli, "_diag", None)+ if diag is None:+ pytest.skip("_diag not present in this build")+ diag("something happened")+ captured = capsys.readouterr()+ assert captured.out == ""+ assert "something happened" in captured.err