diff --git a/CHANGELOG.md b/CHANGELOG.md index 0084d81b5..2fabf2900 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -17,6 +17,20 @@ history. ### Added +- `comfy workflow save` on Comfy Cloud, when the workspace's + `cli_cloud_save_enabled` flag is on, writes an editor-format workflow into a + new folder in the Cloud Workflows sidebar (``, then ` (2)` and so + on; it never replaces a file or adds to an existing workflow) and prints a + link that opens the folder, on Comfy Cloud itself or on the build + `--deployment ` names. The output keeps `workflow_id` and + `latest_version`. An API-format workflow keeps the record-only save. + `comfy workflow delete` still deletes only the record; with the flag on it + warns (`sidebar_file_kept`) when the workflow's sidebar file stays, naming + the file to remove in Comfy Cloud. A file counts as the workflow's only when + no other live workflow has its name and it matches the workflow's latest + version, so a same-named file of another workflow is never named. With the + flag off, or when Cloud's + features cannot be read, save and delete are unchanged. - `comfy knowledge pick` includes authored discovery-only routes in a separate `discovery` list, marks every route `ranking: "unranked"`, and carries the capability's `failure_policy` without promoting or reordering ranked picks. diff --git a/comfy_cli/command/workflow.py b/comfy_cli/command/workflow.py index 4627c4708..7ec5c4a3c 100644 --- a/comfy_cli/command/workflow.py +++ b/comfy_cli/command/workflow.py @@ -21,6 +21,7 @@ from __future__ import annotations import json +import re import shlex import unicodedata from pathlib import Path @@ -1386,6 +1387,383 @@ def _local_delete(renderer, target, workflow_id: str) -> None: renderer.emit(payload, command="workflow delete", where="local", changed=True) +# --------------------------------------------------------------------------- +# Cloud save into a new Workflows-sidebar folder, behind a server flag. +# +# ``POST /api/workflows`` makes a workflow record with no file behind it, and +# the Cloud Workflows sidebar lists ``/userdata`` files, so a record-only save +# never shows there. When Cloud's ``/api/features`` says +# ``cli_cloud_save_enabled`` is true, ``save`` writes the workflow as a +# userdata file in a folder of its own instead (Cloud mirrors that file into +# a workflow record by itself) and prints a link that opens the folder. Any +# other answer, or no answer, keeps the record-only save exactly as before. +# The file is written with ``overwrite=false``, so nothing that exists is +# ever replaced: a name already taken moves on to `` (2)``, ``(3)``, ... +# Only a frontend-format workflow goes into a folder, since the sidebar opens +# files as editor graphs. The CLI never deletes a sidebar file: Cloud's file +# DELETE takes no condition, so it could remove an edit made in the browser +# since the CLI last read the file. With the flag on, ``delete`` removes only +# the record, as before, and warns when a sidebar file shown to be that +# record's stays. The Cloud behavior this rests on, and these rules, are +# recorded in +# docs/adr/SIDEBAR-0009-save-into-a-new-sidebar-folder-and-delete-only-the-record.md. +# --------------------------------------------------------------------------- + +_CLI_CLOUD_SAVE_FLAG = "cli_cloud_save_enabled" + +# How long the flag read may take before ``save`` keeps the record-only path. +_FEATURES_TIMEOUT_S = 10.0 + +# Folder names tried per save: ````, then `` (2)`` up to this. +_MAX_FOLDER_TRIES = 20 + +# Longest folder name ``save`` makes, before any `` (n)`` suffix. +_MAX_FOLDER_NAME = 100 + +# The ``deployment`` link value the Cloud editor reads as Comfy Cloud itself. +_STANDARD_DEPLOYMENT = "standard" + +# Workspace and deployment ids that go into the link as they are. +_LINK_ID_PATTERN = re.compile(r"[A-Za-z0-9_-]+") + +# Pages of ``GET /api/workflows?name=`` read when looking for a record by its +# exact name. The search is a substring match, so a common name can return +# more rows than one page holds. +_MAX_RECORD_PAGES = 10 +_RECORD_PAGE_SIZE = 100 + + +def _request_errors() -> tuple[type[BaseException], ...]: + """Every way one Cloud request can fail before it yields a parsed body. + + ``http.client.HTTPException`` is in the list because urllib does not wrap + it: a body cut off mid-chunk raises ``IncompleteRead`` straight out of + ``response.read``. + """ + import http.client + import urllib.error + + return ( + urllib.error.HTTPError, + urllib.error.URLError, + http.client.HTTPException, + OSError, + ValueError, + _ResponseUnparseable, + _ResponseTooLarge, + ) + + +def _cli_cloud_save_enabled(target) -> bool: + """True only when Cloud's ``/api/features`` answers ``cli_cloud_save_enabled: true``. + + A missing key, any other value, or a request that fails in any way reads + as off, so ``save`` keeps its record-only path and ``delete`` its + record-only delete. + """ + try: + _, body = _http_request(target.url("features"), target, timeout=_FEATURES_TIMEOUT_S) + except _request_errors(): + return False + return isinstance(body, dict) and body.get(_CLI_CLOUD_SAVE_FLAG) is True + + +def _cloud_folder_name(name: str) -> str: + """A one-level folder name for ``--name`` that Cloud and its link both accept. + + The editor opens a folder from a link only when its name is one path + segment with no ``..`` or ``,``; Cloud refuses paths that start with a dot + and hides any segment that does. So slashes and commas become ``-``, runs + of dots become one, and edge dots and spaces go: ``team/flux.json`` → + ``team-flux``. + """ + stem = name.strip() + if stem.lower().endswith(".json"): + stem = stem[: -len(".json")] + stem = _strip_terminal_controls(stem) + stem = re.sub(r"\s+", " ", stem) + stem = re.sub(r"[\\/,]", "-", stem) + stem = re.sub(r"\.{2,}", ".", stem) + stem = stem.strip(" .")[:_MAX_FOLDER_NAME].strip(" .") + return stem or "workflow" + + +def _cloud_folder_is_empty(target, folder: str) -> bool: + """True when Cloud lists no file anywhere under ``workflows//``. Raises request errors. + + ``recurse`` matters: without it Cloud leaves out files in subfolders and + answers 404 for a folder that holds only ``nested/old.json``. + """ + import urllib.error + import urllib.parse + + query = urllib.parse.urlencode({"dir": f"{_WORKFLOWS_DIR}/{folder}", "recurse": "true"}) + try: + _, body = _http_request(target.url("userdata") + "?" + query, target) + except urllib.error.HTTPError as e: + if e.code == 404: + return True + raise + return not body + + +def _cloud_records_named(target, name: str) -> list[dict] | None: + """Live workflow records of this user whose name is exactly ``name``. Raises request errors. + + Cloud mirrors ``workflows/.json`` into the record named ````, + and a file write adds a version to a record of that name that already + exists, so this is what a new file would land on. None means the search + ran past ``_MAX_RECORD_PAGES`` pages without an answer, or Cloud said + more rows follow and sent none. + + The search reads the next page when ``pagination.has_more`` is true or + the page was full, and stops only on a short or empty page that Cloud + does not say is followed by more. A short page with ``has_more`` true + keeps going: Cloud honors ``limit`` up to 100 today, but could send fewer. + A full page with ``has_more`` false keeps going too: Cloud counts the + rows before it reads the page, so a record added in between can sit on + the next page while ``has_more`` says none follow. + The next offset moves by the rows Cloud sent, not by the limit asked for. + """ + import urllib.parse + + matches: list[dict] = [] + offset = 0 + for _ in range(_MAX_RECORD_PAGES): + query = urllib.parse.urlencode( + { + "name": name, + "limit": _RECORD_PAGE_SIZE, + "offset": offset, + "sort": "name", + "order": "asc", + } + ) + _, body = _http_request(target.url("workflows") + "?" + query, target) + rows = body.get("data") if isinstance(body, dict) else None + if not isinstance(rows, list): + raise _ResponseUnparseable() + matches.extend(r for r in rows if isinstance(r, dict) and r.get("name") == name) + pagination = body.get("pagination") + has_more = pagination.get("has_more") if isinstance(pagination, dict) else None + if has_more is not True and len(rows) < _RECORD_PAGE_SIZE: + return matches + if not rows: + return None + offset += len(rows) + return None + + +def _cloud_saved_record(target, name: str) -> dict | None: + """The record Cloud mirrored a new file into, or None when it cannot be told.""" + try: + rows = _cloud_records_named(target, name) + except _request_errors(): + return None + return rows[0] if rows and len(rows) == 1 else None + + +def _cloud_link_id(value: Any) -> str | None: + return value if isinstance(value, str) and _LINK_ID_PATTERN.fullmatch(value) else None + + +def _cloud_workspace_id(target) -> str | None: + """The id of the workspace the save landed in, or None when Cloud does not say.""" + try: + _, body = _http_request(target.url("workspaces", "current"), target) + except _request_errors(): + return None + return _cloud_link_id(body.get("id")) if isinstance(body, dict) else None + + +def _cloud_folder_link(target, *, workspace_id: str | None, folder: str, deployment: str) -> str | None: + """The Cloud editor link that opens ``folder``, or None for an unusable base URL. + + ``deployment`` is a deployment id, or ``standard`` for Comfy Cloud itself. + It goes in only with the workspace, since the editor reads it only then. + """ + import urllib.parse + + origin = urllib.parse.urlsplit(target.base_url) + if origin.username is not None or origin.password is not None or not origin.hostname: + return None + query: dict[str, str] = {} + if workspace_id: + query["workspace"] = workspace_id + query[_WORKFLOWS_DIR] = folder + if workspace_id: + query["deployment"] = deployment + encoded = urllib.parse.urlencode(query, quote_via=urllib.parse.quote) + return urllib.parse.urlunsplit((origin.scheme, origin.netloc, "/", encoded, "")) + + +def _cloud_folder_save( + renderer, + target, + *, + path: Path, + text: str, + name: str, + description: str | None, + deployment: str | None, +) -> None: + """Write the workflow as ``workflows//.json`` and print its link. + + A folder is free only when it holds no file at any depth and no live + record already has the name the file would mirror into + (``/``): Cloud adds a version to a record of that name, so + writing there would change a workflow that already exists. + """ + import urllib.error + + base = _cloud_folder_name(name) + file_name = f"{base}.json" + saved = None + for attempt in range(1, _MAX_FOLDER_TRIES + 1): + folder = base if attempt == 1 else f"{base} ({attempt})" + key = f"{folder}/{file_name}" + try: + if not _cloud_folder_is_empty(target, folder): + continue + if _cloud_records_named(target, key[: -len(".json")]) != []: + continue + _, raw = _userdata_request( + _userdata_file_url(target, key, query={"overwrite": "false"}), + target, + method="POST", + data=text.encode("utf-8"), + content_type="application/json", + ) + except urllib.error.HTTPError as e: + if e.code == 409: + continue + raise _handle_cloud_http_error(renderer, e, operation="save") from e + except _request_errors() as e: + raise _handle_cloud_http_error(renderer, e, operation="save") from e + saved = (folder, key, raw) + break + if saved is None: + renderer.error( + code="workflow_folder_unavailable", + message=f"the Cloud Workflows sidebar already has files or workflows in {base!r} and every " + f"{base!r} (n) folder up to ({_MAX_FOLDER_TRIES}); nothing was saved", + hint="pass a different `--name`", + details={"folder": base, "tries": _MAX_FOLDER_TRIES}, + ) + raise typer.Exit(code=1) + + folder, key, raw = saved + info = None + try: + info = json.loads(raw) + except (ValueError, RecursionError): + pass + record_name = key[: -len(".json")] + record = _cloud_saved_record(target, record_name) + workflow_id = record.get("id") if record and isinstance(record.get("id"), str) else None + latest_version = record.get("latest_version") if record and workflow_id else None + workspace_id = _cloud_workspace_id(target) + url = _cloud_folder_link( + target, workspace_id=workspace_id, folder=folder, deployment=deployment or _STANDARD_DEPLOYMENT + ) + # ``workflow_id``, ``name``, ``latest_version`` and ``source`` keep their + # record-save meaning: the id is the record Cloud mirrored the file into, + # which `workflow get` and `workflow delete` take. + payload: dict[str, Any] = { + "workflow_id": workflow_id, + "name": record_name, + "latest_version": latest_version, + "filename": f"{_WORKFLOWS_DIR}/{key}", + "folder": folder, + "url": url, + "workspace_id": workspace_id, + "deployment": deployment or _STANDARD_DEPLOYMENT, + "source": str(path), + "size": info.get("size") if isinstance(info, dict) else None, + "modified": info.get("modified") if isinstance(info, dict) else None, + } + warnings: list[dict[str, str]] = [] + if description: + warnings.append( + { + "code": "description_ignored", + "message": "--description is ignored: a workflow file in the Cloud Workflows sidebar has no " + "description", + } + ) + if url is not None and workspace_id is None: + warnings.append( + { + "code": "workspace_unknown", + "message": "Cloud did not say which workspace the save went to, so the link opens the folder in " + "the browser's current workspace", + } + ) + if workflow_id is None: + warnings.append( + { + "code": "workflow_record_unknown", + "message": "the file is saved, but Cloud did not show the workflow record it made from it, so " + "workflow_id is null; find it with `comfy --json workflow list --name` and the saved name", + } + ) + if warnings: + payload["warnings"] = warnings + if renderer.is_pretty(): + rprint( + f"[green]✓[/green] saved to the Cloud Workflows sidebar as " + f"[bold]{sanitize_markup(payload['filename'])}[/bold]" + + (f" → [dim]{sanitize_markup(workflow_id)}[/dim]" if workflow_id else "") + ) + if url is not None: + rprint(f"open it: {sanitize_markup(url)}") + for w in warnings: + rprint(f"[yellow]![/yellow] {sanitize_markup(w['message'])}") + renderer.emit(payload, command="workflow save", where="cloud", changed=True) + + +def _cloud_sidebar_file(target, workflow_id: str) -> str | None: + """The Workflows-sidebar file a Cloud record mirrors, as a key under ``workflows/``, or None. + + Cloud makes the record named ```` from ``workflows/.json``, + and deleting the record leaves that file in the sidebar. A name alone does + not prove the file is this record's: ``POST /api/workflows`` makes a + record with no file, and several live records can share a name, so a + record-only workflow ``flux/flux`` can sit beside the file of another + record named ``flux/flux``. So, as Cloud does before it retires a mirror, + the file counts only when this record is the one live record of that + name and the file's JSON equals the record's latest version. A later + record-only save that moved the latest version on answers None, which + leaves out a warning rather than name another workflow's file. + + This only reads: the record's name, the file, the records of that name, + then the record's latest content. It must run before the record DELETE, + which renames the record. A failed or odd read answers None, so + ``delete`` then reports no file. + """ + import urllib.parse + + record_path = urllib.parse.quote(workflow_id, safe="") + try: + _, record = _http_request(target.url("workflows", record_path), target) + name = record.get("name") if isinstance(record, dict) else None + if not isinstance(name, str) or any(p in ("", ".", "..") for p in name.split("/")) or "\\" in name: + return None + key = f"{name}.json" + _, raw = _userdata_request(_userdata_file_url(target, key), target) + same_name = _cloud_records_named(target, name) + if not same_name or len(same_name) != 1 or same_name[0].get("id") != workflow_id: + return None + _, content = _http_request(target.url("workflows", record_path, "content"), target) + if not isinstance(content, dict) or "workflow_json" not in content: + return None + if json.loads(raw) != content["workflow_json"]: + return None + except (*_request_errors(), RecursionError): + return None + return key + + @app.command("list", help="List saved workflows (cloud store, or local ComfyUI /userdata with --where local).") @tracking.track_command("workflow") def list_cmd( @@ -1631,7 +2009,9 @@ def get_cmd( @app.command( "save", - help="Save a workflow JSON to the saved-workflow store (cloud, or local ComfyUI /userdata with --where local).", + help="Save a workflow JSON to the saved-workflow store (cloud, or local ComfyUI /userdata with --where local). " + "On a cloud workspace with `cli_cloud_save_enabled` on, it goes into a new Workflows-sidebar folder and the " + "command prints a link that opens it.", ) @tracking.track_command("workflow") def save_cmd( @@ -1646,6 +2026,15 @@ def save_cmd( str | None, typer.Option("--description", show_default=False, help="Optional description (cloud only; ignored on local)."), ] = None, + deployment: Annotated[ + str | None, + typer.Option( + "--deployment", + show_default=False, + help="Cloud, when the save goes to a sidebar folder: the deployment id the printed link opens the " + "folder on. Default `standard`, Comfy Cloud itself.", + ), + ] = None, where: Annotated[str | None, typer.Option("--where", show_default=False)] = None, ): import urllib.error @@ -1654,6 +2043,13 @@ def save_cmd( target = _resolve_where_target(where) if not target.is_cloud: return _local_save(renderer, target, workflow_file, name, description) + if deployment is not None and _cloud_link_id(deployment) is None: + renderer.error( + code="invalid_argument", + message=f"--deployment {deployment!r} is not a deployment id", + hint="pass the deployment's id (letters, digits, `-` and `_`), or `standard` for Comfy Cloud itself", + ) + raise typer.Exit(code=1) path = Path(workflow_file).expanduser() if not path.is_file(): @@ -1663,8 +2059,9 @@ def save_cmd( hint="check the path", ) raise typer.Exit(code=1) + text = path.read_text(encoding="utf-8") try: - workflow_json = json.loads(path.read_text(encoding="utf-8")) + workflow_json = json.loads(text) except json.JSONDecodeError as e: renderer.error( code="workflow_invalid_json", @@ -1680,6 +2077,16 @@ def save_cmd( ) raise typer.Exit(code=1) + # The sidebar opens a file as an editor graph, which builds nodes only from + # ``nodes[]``; an API-format file there would open empty. So only a + # frontend-format workflow goes into a folder, and an API-format one keeps + # the record-only save with a warning that says why it has no link. + sidebar = _cli_cloud_save_enabled(target) + if sidebar and _is_frontend_format(workflow_json): + return _cloud_folder_save( + renderer, target, path=path, text=text, name=name, description=description, deployment=deployment + ) + body: dict[str, Any] = {"name": name, "workflow_json": workflow_json} if description: body["description"] = description @@ -1702,12 +2109,27 @@ def save_cmd( "latest_version": (resp or {}).get("latest_version") if isinstance(resp, dict) else None, "source": str(path), } + if sidebar: + payload["warnings"] = [ + { + "code": "api_format_saved_as_record", + "message": "this is an API-format workflow, which the Cloud Workflows sidebar cannot open, so it " + "was saved as a workflow record with no sidebar folder or link; save the editor format " + "(`File > Save` in ComfyUI) to get one", + } + ] if renderer.is_pretty(): rprint(f"[green]✓[/green] saved {name!r} → [dim]{workflow_id}[/dim]") + for w in payload.get("warnings", []): + rprint(f"[yellow]![/yellow] {sanitize_markup(w['message'])}") renderer.emit(payload, command="workflow save", where="cloud", changed=True) -@app.command("delete", help="Delete a saved workflow (cloud, or local ComfyUI /userdata with --where local).") +@app.command( + "delete", + help="Delete a saved workflow (cloud, or local ComfyUI /userdata with --where local). On a cloud workspace " + "with `cli_cloud_save_enabled` on, a workflow's Workflows-sidebar file is not deleted; a warning names it.", +) @tracking.track_command("workflow") def delete_cmd( workflow_id: Annotated[ @@ -1725,6 +2147,10 @@ def delete_cmd( import urllib.parse as _up + # Read the sidebar file's name before the DELETE, which renames the record. + # The file itself is never deleted here (see the section comment above). + kept = _cloud_sidebar_file(target, workflow_id) if _cli_cloud_save_enabled(target) else None + url = target.url("workflows", _up.quote(workflow_id, safe="")) try: _, _body = _http_request(url, target, method="DELETE") @@ -1737,9 +2163,21 @@ def delete_cmd( ) as e: raise _handle_cloud_http_error(renderer, e, operation="delete", workflow_id=workflow_id) from e - payload = {"workflow_id": workflow_id, "deleted": True} + payload: dict[str, Any] = {"workflow_id": workflow_id, "deleted": True} + if kept is not None: + filename = f"{_WORKFLOWS_DIR}/{kept}" + payload["warnings"] = [ + { + "code": "sidebar_file_kept", + "message": f"the workflow record is deleted, but its file {filename} stays in the Cloud " + "Workflows sidebar; remove it there in Comfy Cloud", + "filename": filename, + } + ] if renderer.is_pretty(): rprint(f"[green]✓[/green] deleted [dim]{workflow_id}[/dim]") + for w in payload.get("warnings", []): + rprint(f"[yellow]![/yellow] {sanitize_markup(w['message'])}") renderer.emit(payload, command="workflow delete", where="cloud", changed=True) diff --git a/comfy_cli/error_codes.py b/comfy_cli/error_codes.py index d402b1332..bb0c4847b 100644 --- a/comfy_cli/error_codes.py +++ b/comfy_cli/error_codes.py @@ -124,6 +124,14 @@ class ErrorCode: "Loaded JSON isn't API-format and no converter is available.", "use ComfyUI's `File > Export (API)`", ), + ErrorCode( + "workflow_folder_unavailable", + "`comfy workflow save` on Comfy Cloud makes a new Workflows-sidebar folder per save, named after " + "`--name`, then ` (2)` and so on. Every candidate already held files (at any depth) or matched " + "the name of an existing workflow record the file would have been merged into, so nothing was saved " + "and nothing was replaced. `details.folder` is the base name and `details.tries` how many were tried.", + "pass a different `--name`", + ), ErrorCode( "invalid_output_node_ids", "`comfy run --output-node-ids` named no ids, a node id that is not in the submitted " @@ -956,10 +964,45 @@ class ErrorCode: ), ErrorCode( "description_ignored", - "`comfy workflow save --where local --description` was given a description, but the local " - "file-backed `/userdata` store has nowhere to keep it. Surfaced in `data.warnings[]` " - "(not as an error envelope) so the save still succeeds.", - "descriptions are a Comfy Cloud feature; drop `--description` on the local path", + "`comfy workflow save --description` was given a description, but the save went to a " + "file-backed `/userdata` store with nowhere to keep it: local ComfyUI, or a Comfy Cloud " + "Workflows-sidebar folder. Surfaced in `data.warnings[]` (not as an error envelope) so the save " + "still succeeds.", + "drop `--description`; a sidebar file carries only its name and contents", + ), + ErrorCode( + "workspace_unknown", + "`comfy workflow save` wrote to a Comfy Cloud Workflows-sidebar folder, but Cloud did not say which " + "workspace it went to, so `data.url` leaves out the workspace and deployment and opens the folder in " + "whatever workspace the browser is on. Surfaced in `data.warnings[]` (not as an error envelope) " + "because the save itself succeeded.", + "switch the browser to the workspace `comfy cloud whoami` shows before opening the link", + ), + ErrorCode( + "workflow_record_unknown", + "`comfy workflow save` wrote to a Comfy Cloud Workflows-sidebar folder, but Cloud did not show the " + "workflow record it makes from that file, so `data.workflow_id` and `data.latest_version` are null. " + "Surfaced in `data.warnings[]` (not as an error envelope) because the file itself was saved.", + "find the record with `comfy --json workflow list --name `", + ), + ErrorCode( + "api_format_saved_as_record", + "`comfy workflow save` on a Comfy Cloud workspace that saves into Workflows-sidebar folders was given " + "an API-format workflow. The sidebar opens files as editor graphs and would show it empty, so it was " + "saved the record-only way, with no folder and no `data.url`. Surfaced in `data.warnings[]` (not as an " + "error envelope) because the record save succeeded.", + "save the editor format (ComfyUI `File > Save`) to get a sidebar folder and a link", + ), + ErrorCode( + "sidebar_file_kept", + "`comfy workflow delete` on a Comfy Cloud workspace with `cli_cloud_save_enabled` on deleted the " + "workflow record, but the Workflows-sidebar file the record was made from (`filename` in the " + "warning) still exists. The file counts as the record's only when the record is the one live " + "workflow of its name and the file matches the record's latest version; a file that only shares the " + "name may be another workflow's, and gets no warning. The CLI never deletes sidebar files, so it " + "stays in the sidebar. Surfaced in `data.warnings[]` (not as an error envelope) because the record " + "delete succeeded.", + "remove the file from the Workflows sidebar in Comfy Cloud", ), ErrorCode( "cql_query_invalid", diff --git a/comfy_cli/skills/comfy/SKILL.md b/comfy_cli/skills/comfy/SKILL.md index c662be541..22b4f724f 100644 --- a/comfy_cli/skills/comfy/SKILL.md +++ b/comfy_cli/skills/comfy/SKILL.md @@ -715,6 +715,24 @@ comfy --json workflow save my.json --name "X" --description "Y" comfy --json workflow delete ``` +When the cloud workspace has `cli_cloud_save_enabled` on (`GET /api/features`), +`workflow save` of an editor-format workflow (`nodes[]`) instead writes the +file into a new folder in the Cloud Workflows sidebar, named after `--name` +(` (2)` and so on when the folder has files or a workflow of that name +exists; nothing is ever replaced), and `data.url` is a link that opens that +folder. `data.workflow_id` is still the saved workflow's id. The link opens +Comfy Cloud itself unless `--deployment ` names a build. `data.warnings[]` +may carry `description_ignored`, `workspace_unknown` or +`workflow_record_unknown`. An API-format workflow keeps the record-only save, +with an `api_format_saved_as_record` warning. `workflow delete ` only ever +deletes the record; with the flag on, when the workflow's sidebar file still +exists, `data.warnings[]` carries `sidebar_file_kept` with the file's path +(`filename`). The file stays in the sidebar until the person removes it in +Comfy Cloud. The file counts as the workflow's only when no other live +workflow has the same name and the file matches the workflow's latest +version; a same-named file that may be another workflow's gets no warning. With the flag off, or when the features read fails, save is the +record-only `/api/workflows` call above. + ## Cancel a running job ```bash diff --git a/docs/adr/SIDEBAR-0009-save-into-a-new-sidebar-folder-and-delete-only-the-record.md b/docs/adr/SIDEBAR-0009-save-into-a-new-sidebar-folder-and-delete-only-the-record.md new file mode 100644 index 000000000..ed2289535 --- /dev/null +++ b/docs/adr/SIDEBAR-0009-save-into-a-new-sidebar-folder-and-delete-only-the-record.md @@ -0,0 +1,97 @@ +# ADR-SIDEBAR-0009: Save Into a New Sidebar Folder and Delete Only the Record + +Date: 2026-11-05 + +## Status + +Accepted + +Relation: Builds on ADR-AUTOMATION-0003. Save and delete keep the `envelope/1` +output and add only fields and registered warning codes. + +## Context + +A person saves a workflow from a terminal with `comfy workflow save flux.json +--name flux --where cloud`. Before this decision the CLI posted a workflow +record to `POST /api/workflows`. The Comfy Cloud Workflows sidebar lists +`/userdata` files, not records, so the saved workflow never showed there. + +Writing a userdata file puts it in the sidebar. The CLI then depends on three +things Cloud does but does not publish as a contract: + +- Cloud copies `workflows/.json` into a workflow record named ``. +- A file write whose `` matches a live record adds a version to that + record, even a record the person made some other way. +- Cloud deletes a copied record together with its file only when that record is + the one live record of its name and its latest version equals the file. + +Cloud's userdata `DELETE` takes no condition, so the CLI cannot delete a file +only if it still holds what the CLI last read. + +## Decision + +- The server flag `cli_cloud_save_enabled` from `GET /api/features` decides the + path. Only a JSON `true` turns on the folder save. Anything else, including a + failed read, keeps the record save. Turning the flag off moves every + installed CLI back to the record save without a release. +- With the flag on, an editor-format workflow (one with `nodes[]`) is written as + `workflows//.json` with `POST /api/userdata/...?overwrite=false`. + No existing file is ever replaced. An API-format workflow keeps the record + save, since the sidebar opens a file as an editor graph. +- A folder is used only when it holds no file at any depth and no live record + is named `/`. Otherwise the CLI moves on to ` (2)`, up to + 20 folders. A record search with no clear answer counts the folder as taken. +- `comfy workflow delete` deletes only the record, with the flag on or off. + The CLI never deletes a sidebar file. With the flag on it adds the + `sidebar_file_kept` warning only under Cloud's own rule above: this record is + the one live record of the file's name and the file's JSON equals the + record's latest version. Any other case, or any failed read, gives the plain + delete. + +## Alternatives considered + +- Keep the record-only save. Rejected because the saved workflow never shows in + the sidebar and the CLI has no link to give. +- Overwrite a file of the same name. Rejected because it replaces an edit the + person made in the browser. +- Delete the sidebar file on `workflow delete`. Rejected because an + unconditional file delete can remove an edit made in the browser after the + CLI read the file. + +## What we reject + +- Any CLI call that deletes or overwrites a userdata file under `workflows/`. +- A file write whose `/` matches a live record. +- Naming a file in `sidebar_file_kept` on a name match alone. + +## Consequences + +### Positive + +- A workflow saved from a terminal shows in the sidebar, and the CLI prints a + link that opens its folder. +- Neither save nor delete can change or remove an existing workflow. + +### Negative + +- After `workflow delete`, the sidebar file stays until the person removes it + in Comfy Cloud. +- The folder save rests on Cloud behavior that only this record and code + comments describe. + +## Validation + +`tests/comfy_cli/command/test_workflow_saved.py` pins each rule: +`TestSaveFlagOffKeepsTheRecordSave` the flag-off and failed-read paths, +`TestSaveToSidebarFolder` the `overwrite=false` write and the free-folder rule, +and `TestDeleteKeepsTheSidebarFile` the record-only delete and the warning rule. +The fake Cloud in `TestDeleteKeepsTheSidebarFile` fails any userdata `DELETE`. + +## Revisit triggers + +- Cloud publishes how a file becomes a record, or changes it. The flag goes off + until the CLI matches. +- Cloud's userdata `DELETE` gains a condition on the file's content or version. + Then `workflow delete` can remove the file safely. +- Cloud adds a way to write a file without adding a version to an existing + record. Then the record search before each write can go. diff --git a/tests/comfy_cli/command/test_workflow_saved.py b/tests/comfy_cli/command/test_workflow_saved.py index 8b28da40e..34512a184 100644 --- a/tests/comfy_cli/command/test_workflow_saved.py +++ b/tests/comfy_cli/command/test_workflow_saved.py @@ -9,6 +9,7 @@ from __future__ import annotations +import http.client import io import json import urllib.error @@ -687,8 +688,14 @@ def test_non_utf8_body_surfaces_envelope_not_traceback(self, cloud_target, monke def test_every_call_site_routes_oversize_to_envelope(self, verb, cloud_target, tmp_path, monkeypatch, capsys): # Each of the four _http_request call sites must catch _ResponseTooLarge; # an uncaught one would surface as a traceback rather than an envelope. - monkeypatch.setattr(workflow_cmd, "_HTTP_MAX_BYTES", 4) - _patch_urlopen(monkeypatch, {"/api/workflows": (b'{"data": []}', 200)}) + # save and delete read /api/features first. The cap fits its flag-off + # answer exactly, so they take the record path and reach the oversize + # /api/workflows body, rather than reading the flag as off because the + # features body itself was too large. + flag_off = json.dumps(_FLAG_OFF).encode() + monkeypatch.setattr(workflow_cmd, "_HTTP_MAX_BYTES", len(flag_off)) + oversize = json.dumps({"data": [], "pad": "x" * len(flag_off)}).encode() + calls = _patch_urlopen(monkeypatch, {"/api/features": (flag_off, 200), "/api/workflows": (oversize, 200)}) args = { "list": ["list"], "get": ["get", "wf-uuid"], @@ -705,6 +712,9 @@ def test_every_call_site_routes_oversize_to_envelope(self, verb, cloud_target, t # The hint must speak to the operation that actually failed; a single # hardcoded "saved workflow is too large" is wrong for list/save/delete. assert env["error"]["hint"] == workflow_cmd._TOO_LARGE_HINTS[verb] + if verb in ("save", "delete"): + assert calls[0]["url"] == "https://cloud.example.com/api/features" + assert "/api/workflows" in calls[-1]["url"] @pytest.mark.parametrize("verb", ["save", "delete"]) def test_mutating_verbs_do_not_claim_the_write_was_rejected(self, verb): @@ -733,13 +743,13 @@ def test_posts_workflow_payload(self, cloud_target, tmp_path, monkeypatch, capsy "created_at": "2026-05-23T00:00:00Z", "updated_at": "2026-05-23T00:00:00Z", } - calls = _patch_urlopen(monkeypatch, {"/api/workflows": created}) + calls = _patch_urlopen(monkeypatch, {"/api/features": _FLAG_OFF, "/api/workflows": created}) env = _run(["save", str(wf_path), "--name", "my workflow", "--where", "cloud"], capsys) assert env["ok"] is True assert env["data"]["workflow_id"] == "new-uuid" # POSTed JSON carries the workflow_json + name. - assert calls[0]["method"] == "POST" - sent = json.loads(calls[0]["body"]) + assert calls[-1]["method"] == "POST" + sent = json.loads(calls[-1]["body"]) assert sent["name"] == "my workflow" assert sent["workflow_json"] == wf_data @@ -759,6 +769,451 @@ def test_missing_file_surfaces_workflow_not_found(self, cloud_target, tmp_path, assert env["error"]["code"] == "workflow_not_found" +# --------------------------------------------------------------------------- +# save into a Cloud Workflows-sidebar folder (the cli_cloud_save_enabled flag) +# --------------------------------------------------------------------------- + +_FLAG_OFF = {"cli_cloud_save_enabled": False} +_FLAG_ON = {"cli_cloud_save_enabled": True} +# An editor-format workflow: the only kind the sidebar can open. +_UI_DATA = {"nodes": [{"id": 1, "type": "KSampler", "widgets_values": [20]}], "links": [], "version": 0.4} +# An API-format workflow: saved the record-only way even with the flag on. +_WF_DATA = {"1": {"class_type": "KSampler", "inputs": {"steps": 20}}} +_RECORD_CREATED = {"id": "new-uuid", "name": "flux", "latest_version": 1} +_WORKSPACE = {"id": "ws_123", "name": "Personal", "type": "personal", "role": "owner"} + + +def _patch_cloud(monkeypatch: pytest.MonkeyPatch, handler): + """Route every request through ``handler(method, url, body)``. + + It returns a JSON-able payload, ``(bytes, status)``, or an Exception to + raise. Records each call as ``_patch_urlopen`` does. + """ + calls: list[dict] = [] + + def _fake(req, timeout=None): + call = {"url": req.full_url, "method": req.get_method(), "body": req.data, "headers": dict(req.headers)} + calls.append(call) + payload = handler(call["method"], call["url"], call["body"]) + if isinstance(payload, Exception): + raise payload + if isinstance(payload, tuple): + return _fake_resp(*payload) + return _fake_resp(json.dumps(payload).encode()) + + import comfy_cli.http as http_mod + + monkeypatch.setattr(http_mod._AUTHED_OPENER, "open", _fake) + return calls + + +def _sidebar( + features=_FLAG_ON, + *, + taken=(), + nested=(), + conflict=(), + records=(), + workspace=_WORKSPACE, + lookup_after_write=None, +): + """A fake Cloud. + + ``taken`` folders list a file, ``nested`` folders hold only a file in a + subfolder (listed only with ``recurse=true``), a POST into a ``conflict`` + folder gets 409, and ``records`` are the names of live workflow records. + A written file is mirrored into a record named after its path, as Cloud + does. ``lookup_after_write``, when set, answers the record search once a + file has been written. + """ + import urllib.parse + + state = {"records": list(records), "written": False} + + def handler(method, url, body): + parsed = urllib.parse.urlsplit(url) + query = urllib.parse.parse_qs(parsed.query) + if parsed.path == "/api/features": + return features + if parsed.path == "/api/workspaces/current": + return workspace + if parsed.path == "/api/userdata" and method == "GET": + assert query.get("recurse") == ["true"] + folder = query["dir"][0].removeprefix("workflows/") + if folder in taken: + return [{"path": "old.json"}] + if folder in nested: + return [{"path": "nested/old.json"}] + return _http_error(404) + if parsed.path.startswith("/api/userdata/") and method == "POST": + key = urllib.parse.unquote(parsed.path.removeprefix("/api/userdata/")) + assert query == {"overwrite": ["false"]} + folder = key.split("/")[1] + if folder in conflict: + return _http_error(409) + state["written"] = True + state["records"].append(key.removeprefix("workflows/").removesuffix(".json")) + return {"path": key, "size": len(body), "modified": 1700000000000} + if parsed.path == "/api/workflows" and method == "GET": + if state["written"] and lookup_after_write is not None: + return lookup_after_write + needle = query["name"][0].lower() + rows = [{"id": f"rec-{n}", "name": n, "latest_version": 1} for n in state["records"] if needle in n.lower()] + return {"data": rows, "pagination": {"total": len(rows), "limit": 100, "offset": 0}} + if parsed.path == "/api/workflows" and method == "POST": + return _RECORD_CREATED + raise AssertionError(f"unexpected {method} {url}") + + return handler + + +def _posts(calls): + return [c for c in calls if c["method"] == "POST"] + + +class TestSaveToSidebarFolder: + @pytest.fixture + def wf_path(self, tmp_path): + p = tmp_path / "wf.json" + p.write_text(json.dumps(_UI_DATA, indent=2)) + return p + + def test_writes_the_file_into_a_new_folder_and_prints_its_link(self, cloud_target, wf_path, monkeypatch, capsys): + calls = _patch_cloud(monkeypatch, _sidebar()) + env = _run(["save", str(wf_path), "--name", "flux", "--where", "cloud"], capsys) + assert env["ok"] is True + data = env["data"] + assert data["filename"] == "workflows/flux/flux.json" + assert data["folder"] == "flux" + assert data["name"] == "flux/flux" + assert data["workspace_id"] == "ws_123" + assert data["deployment"] == "standard" + assert data["url"] == "https://cloud.example.com/?workspace=ws_123&workflows=flux&deployment=standard" + assert "warnings" not in data + (post,) = _posts(calls) + assert post["url"] == "https://cloud.example.com/api/userdata/workflows%2Fflux%2Fflux.json?overwrite=false" + # The file's bytes go up as they are on disk; no record-only POST is made. + assert post["body"] == wf_path.read_bytes() + + def test_output_keeps_the_record_id_and_version(self, cloud_target, wf_path, monkeypatch, capsys): + # The record-only save returned workflow_id and latest_version, and + # `workflow get` / `workflow delete` take that id. The sidebar save + # still returns them: the id of the record Cloud mirrored the file into. + _patch_cloud(monkeypatch, _sidebar(records={"flux/flux-old"})) + env = _run(["save", str(wf_path), "--name", "flux", "--where", "cloud"], capsys) + assert env["data"]["workflow_id"] == "rec-flux/flux" + assert env["data"]["latest_version"] == 1 + assert env["data"]["source"] == str(wf_path) + + @pytest.mark.parametrize( + "lookup", + [ + pytest.param(_http_error(500), id="http-500"), + pytest.param(http.client.IncompleteRead(b"{"), id="truncated"), + pytest.param({"data": []}, id="not-found"), + ], + ) + def test_an_unknown_record_still_saves_with_a_warning(self, cloud_target, wf_path, monkeypatch, capsys, lookup): + _patch_cloud(monkeypatch, _sidebar(lookup_after_write=lookup)) + env = _run(["save", str(wf_path), "--name", "flux", "--where", "cloud"], capsys) + assert env["ok"] is True + assert env["data"]["filename"] == "workflows/flux/flux.json" + assert env["data"]["workflow_id"] is None + assert env["data"]["latest_version"] is None + assert [w["code"] for w in env["data"]["warnings"]] == ["workflow_record_unknown"] + + def test_deployment_option_goes_into_the_link(self, cloud_target, wf_path, monkeypatch, capsys): + _patch_cloud(monkeypatch, _sidebar()) + env = _run(["save", str(wf_path), "--name", "flux", "--deployment", "dep_9", "--where", "cloud"], capsys) + assert env["data"]["deployment"] == "dep_9" + assert env["data"]["url"].endswith("&deployment=dep_9") + + def test_bad_deployment_id_is_refused_before_any_request(self, cloud_target, wf_path, monkeypatch, capsys): + calls = _patch_cloud(monkeypatch, _sidebar()) + env = _run(["save", str(wf_path), "--name", "flux", "--deployment", "a&b=c", "--where", "cloud"], capsys) + assert env["ok"] is False + assert env["error"]["code"] == "invalid_argument" + assert calls == [] + + def test_a_folder_with_files_moves_on_to_a_numbered_one(self, cloud_target, wf_path, monkeypatch, capsys): + calls = _patch_cloud(monkeypatch, _sidebar(taken={"flux", "flux (2)"})) + env = _run(["save", str(wf_path), "--name", "flux", "--where", "cloud"], capsys) + assert env["data"]["filename"] == "workflows/flux (3)/flux.json" + # Spaces are %20 in the link: the editor reads a '+' as a literal plus. + assert "workflows=flux%20%283%29" in env["data"]["url"] + assert len(_posts(calls)) == 1 + + def test_a_folder_with_only_nested_files_is_taken(self, cloud_target, wf_path, monkeypatch, capsys): + # Without recurse=true Cloud leaves out workflows/flux/nested/old.json + # and answers 404, which read as an empty folder. + _patch_cloud(monkeypatch, _sidebar(nested={"flux"})) + env = _run(["save", str(wf_path), "--name", "flux", "--where", "cloud"], capsys) + assert env["data"]["folder"] == "flux (2)" + + def test_an_existing_record_of_the_mirror_name_is_never_added_to(self, cloud_target, wf_path, monkeypatch, capsys): + # A record named flux/flux with no file behind it: writing + # workflows/flux/flux.json would add a version to it. A record whose + # name only contains it does not count. + calls = _patch_cloud(monkeypatch, _sidebar(records={"flux/flux", "Flux/Flux", "old flux/flux"})) + env = _run(["save", str(wf_path), "--name", "flux", "--where", "cloud"], capsys) + assert env["data"]["folder"] == "flux (2)" + assert env["data"]["workflow_id"] == "rec-flux (2)/flux" + (post,) = _posts(calls) + assert "flux%20%282%29%2Fflux.json" in post["url"] + + def test_a_record_search_past_the_page_cap_counts_as_taken(self, cloud_target, wf_path, monkeypatch, capsys): + import urllib.parse + + base = _sidebar() + full_page = {"data": [{"id": f"r{i}", "name": f"x flux/flux {i}"} for i in range(100)]} + + def handler(method, url, body): + parsed = urllib.parse.urlsplit(url) + name = urllib.parse.parse_qs(parsed.query).get("name", [""])[0] + if parsed.path == "/api/workflows" and method == "GET" and name == "flux/flux": + return full_page + return base(method, url, body) + + _patch_cloud(monkeypatch, handler) + env = _run(["save", str(wf_path), "--name", "flux", "--where", "cloud"], capsys) + assert env["data"]["folder"] == "flux (2)" + + @staticmethod + def _paged_search(pages): + """A fake Cloud whose search for ``flux/flux`` answers ``pages`` by offset; the rest is ``_sidebar()``.""" + import urllib.parse + + base = _sidebar() + + def handler(method, url, body): + parsed = urllib.parse.urlsplit(url) + query = urllib.parse.parse_qs(parsed.query) + if parsed.path == "/api/workflows" and method == "GET" and query.get("name") == ["flux/flux"]: + return pages[int(query["offset"][0])] + return base(method, url, body) + + return handler + + @staticmethod + def _search_offsets(calls): + import urllib.parse + + return [ + urllib.parse.parse_qs(urllib.parse.urlsplit(c["url"]).query)["offset"][0] + for c in calls + if c["method"] == "GET" and "/api/workflows?name=flux%2Fflux&" in c["url"] + ] + + def test_a_short_page_with_more_to_come_keeps_searching(self, cloud_target, wf_path, monkeypatch, capsys): + # Cloud sends 2 rows where 100 were asked for and says more follow. The + # record named flux/flux is on the next page, so flux is taken, and the + # next page starts after the 2 rows sent, not at offset 100. + pages = { + 0: { + "data": [{"id": "r1", "name": "a flux/flux"}, {"id": "r2", "name": "b flux/flux"}], + "pagination": {"total": 3, "limit": 2, "offset": 0, "has_more": True}, + }, + 2: { + "data": [{"id": "r3", "name": "flux/flux"}], + "pagination": {"total": 3, "limit": 2, "offset": 2, "has_more": False}, + }, + } + calls = _patch_cloud(monkeypatch, self._paged_search(pages)) + env = _run(["save", str(wf_path), "--name", "flux", "--where", "cloud"], capsys) + assert env["data"]["folder"] == "flux (2)" + assert self._search_offsets(calls) == ["0", "2"] + + def test_a_full_page_with_nothing_more_still_reads_the_next_page(self, cloud_target, wf_path, monkeypatch, capsys): + # A full page does not end the search even with has_more false; the + # empty page after it does, and flux is free. + full_page = { + "data": [{"id": f"r{i}", "name": f"x flux/flux {i}"} for i in range(100)], + "pagination": {"total": 100, "limit": 100, "offset": 0, "has_more": False}, + } + empty = {"data": [], "pagination": {"total": 100, "limit": 100, "offset": 100, "has_more": False}} + calls = _patch_cloud(monkeypatch, self._paged_search({0: full_page, 100: empty})) + env = _run(["save", str(wf_path), "--name", "flux", "--where", "cloud"], capsys) + assert env["data"]["folder"] == "flux" + # The search before the write and the one after it each read both pages. + assert self._search_offsets(calls) == ["0", "100", "0", "100"] + + def test_a_record_added_after_the_count_is_still_found(self, cloud_target, wf_path, monkeypatch, capsys): + # Cloud counts the rows before it reads the page. A record named + # flux/flux added in between lands on the next page while the full + # first page says has_more false. The search must still find it, so + # flux is taken and nothing is written into it. + full_page = { + "data": [{"id": f"r{i}", "name": f"x flux/flux {i}"} for i in range(100)], + "pagination": {"total": 100, "limit": 100, "offset": 0, "has_more": False}, + } + late = { + "data": [{"id": "r-late", "name": "flux/flux"}], + "pagination": {"total": 101, "limit": 100, "offset": 100, "has_more": False}, + } + calls = _patch_cloud(monkeypatch, self._paged_search({0: full_page, 100: late})) + env = _run(["save", str(wf_path), "--name", "flux", "--where", "cloud"], capsys) + assert env["data"]["folder"] == "flux (2)" + assert self._search_offsets(calls) == ["0", "100"] + (post,) = _posts(calls) + assert "flux%20%282%29%2Fflux.json" in post["url"] + + def test_more_to_come_with_no_rows_counts_as_taken(self, cloud_target, wf_path, monkeypatch, capsys): + # has_more true on an empty page cannot move the offset; asking again + # would get the same page, so the search has no answer. + empty = {"data": [], "pagination": {"total": 5, "limit": 100, "offset": 0, "has_more": True}} + calls = _patch_cloud(monkeypatch, self._paged_search({0: empty})) + env = _run(["save", str(wf_path), "--name", "flux", "--where", "cloud"], capsys) + assert env["data"]["folder"] == "flux (2)" + assert self._search_offsets(calls) == ["0"] + + def test_a_failed_record_search_saves_nothing(self, cloud_target, wf_path, monkeypatch, capsys): + base = _sidebar() + + def handler(method, url, body): + if method == "GET" and "/api/workflows?" in url: + return _http_error(500) + return base(method, url, body) + + calls = _patch_cloud(monkeypatch, handler) + env = _run(["save", str(wf_path), "--name", "flux", "--where", "cloud"], capsys) + assert env["ok"] is False + assert _posts(calls) == [] + + def test_a_409_moves_on_and_nothing_is_overwritten(self, cloud_target, wf_path, monkeypatch, capsys): + calls = _patch_cloud(monkeypatch, _sidebar(conflict={"flux"})) + env = _run(["save", str(wf_path), "--name", "flux", "--where", "cloud"], capsys) + assert env["data"]["folder"] == "flux (2)" + posts = _posts(calls) + assert len(posts) == 2 + assert all(c["url"].endswith("?overwrite=false") for c in posts) + assert not any(c["method"] in ("PUT", "DELETE") for c in calls) + + def test_every_folder_taken_saves_nothing(self, cloud_target, wf_path, monkeypatch, capsys): + taken = {"flux"} | {f"flux ({n})" for n in range(2, workflow_cmd._MAX_FOLDER_TRIES + 1)} + calls = _patch_cloud(monkeypatch, _sidebar(taken=taken)) + env = _run(["save", str(wf_path), "--name", "flux", "--where", "cloud"], capsys) + assert env["ok"] is False + assert env["error"]["code"] == "workflow_folder_unavailable" + assert _posts(calls) == [] + + @pytest.mark.parametrize( + ("name", "folder"), + [ + ("flux.json", "flux"), + ("team/flux", "team-flux"), + ("a,b\\c", "a-b-c"), + ("../..secret", "-.secret"), + (" .hidden. ", "hidden"), + ("two spaces", "two spaces"), + ("...", "workflow"), + ], + ) + def test_folder_names_are_one_safe_segment(self, name, folder): + assert workflow_cmd._cloud_folder_name(name) == folder + + def test_description_is_reported_as_ignored(self, cloud_target, wf_path, monkeypatch, capsys): + _patch_cloud(monkeypatch, _sidebar()) + env = _run(["save", str(wf_path), "--name", "flux", "--description", "d", "--where", "cloud"], capsys) + assert env["ok"] is True + assert [w["code"] for w in env["data"]["warnings"]] == ["description_ignored"] + + @pytest.mark.parametrize( + "workspace", + [ + pytest.param(_http_error(500), id="http-500"), + pytest.param(http.client.IncompleteRead(b"{"), id="truncated"), + pytest.param({"id": "bad id"}, id="bad-id"), + pytest.param({}, id="no-id"), + ], + ) + def test_unknown_workspace_still_saves_and_links_the_folder( + self, cloud_target, wf_path, monkeypatch, capsys, workspace + ): + _patch_cloud(monkeypatch, _sidebar(workspace=workspace)) + env = _run(["save", str(wf_path), "--name", "flux", "--where", "cloud"], capsys) + assert env["ok"] is True + assert env["data"]["workspace_id"] is None + assert env["data"]["url"] == "https://cloud.example.com/?workflows=flux" + assert [w["code"] for w in env["data"]["warnings"]] == ["workspace_unknown"] + + def test_a_failed_write_is_an_error_not_a_retry(self, cloud_target, wf_path, monkeypatch, capsys): + base = _sidebar() + + def handler(method, url, body): + if method == "POST": + return _http_error(500) + return base(method, url, body) + + calls = _patch_cloud(monkeypatch, handler) + env = _run(["save", str(wf_path), "--name", "flux", "--where", "cloud"], capsys) + assert env["ok"] is False + assert len(_posts(calls)) == 1 + + def test_api_format_keeps_the_record_save_with_a_warning(self, cloud_target, tmp_path, monkeypatch, capsys): + # The sidebar opens a file as an editor graph, which builds nodes only + # from nodes[]: an API-format file there would open empty. + wf_path = tmp_path / "api.json" + wf_path.write_text(json.dumps(_WF_DATA)) + calls = _patch_cloud(monkeypatch, _sidebar()) + env = _run(["save", str(wf_path), "--name", "flux", "--where", "cloud"], capsys) + assert env["ok"] is True + assert env["data"]["workflow_id"] == "new-uuid" + assert "url" not in env["data"] + assert [w["code"] for w in env["data"]["warnings"]] == ["api_format_saved_as_record"] + (post,) = _posts(calls) + assert post["url"] == "https://cloud.example.com/api/workflows" + assert json.loads(post["body"]) == {"name": "flux", "workflow_json": _WF_DATA} + assert not any("/api/userdata" in c["url"] for c in calls) + + +class TestSaveFlagOffKeepsTheRecordSave: + """Flag off, missing, or unreadable: the save is the record-only POST, as before the flag.""" + + @pytest.mark.parametrize( + "features", + [ + pytest.param(_FLAG_OFF, id="off"), + pytest.param({}, id="missing"), + pytest.param({"cli_cloud_save_enabled": "true"}, id="not-a-bool"), + pytest.param([], id="not-an-object"), + pytest.param(_http_error(500), id="http-500"), + pytest.param(_http_error(401), id="http-401"), + pytest.param(urllib.error.URLError("down"), id="unreachable"), + pytest.param(TimeoutError("slow"), id="timeout"), + pytest.param((b"", 200), id="unparseable"), + pytest.param(http.client.IncompleteRead(b'{"cli_'), id="truncated"), + pytest.param(http.client.RemoteDisconnected("closed"), id="disconnected"), + ], + ) + def test_record_save_unchanged(self, cloud_target, tmp_path, monkeypatch, capsys, features): + wf_path = tmp_path / "wf.json" + wf_path.write_text(json.dumps(_UI_DATA)) + calls = _patch_cloud(monkeypatch, _sidebar(features=features)) + env = _run(["save", str(wf_path), "--name", "flux", "--description", "d", "--where", "cloud"], capsys) + assert env["ok"] is True + assert env["data"] == { + "workflow_id": "new-uuid", + "name": "flux", + "latest_version": 1, + "source": str(wf_path), + } + assert [c["url"] for c in calls] == [ + "https://cloud.example.com/api/features", + "https://cloud.example.com/api/workflows", + ] + assert calls[0]["method"] == "GET" + assert json.loads(calls[1]["body"]) == {"name": "flux", "workflow_json": _UI_DATA, "description": "d"} + + def test_features_read_sends_the_users_auth(self, cloud_target, tmp_path, monkeypatch, capsys): + wf_path = tmp_path / "wf.json" + wf_path.write_text(json.dumps(_UI_DATA)) + calls = _patch_cloud(monkeypatch, _sidebar(features=_FLAG_OFF)) + _run(["save", str(wf_path), "--name", "flux", "--where", "cloud"], capsys) + # urllib stores header names capitalized: X-API-Key -> X-api-key. + assert calls[0]["url"].endswith("/api/features") + assert calls[0]["headers"].get("X-api-key") == "test-key" + + # --------------------------------------------------------------------------- # delete # --------------------------------------------------------------------------- @@ -766,20 +1221,217 @@ def test_missing_file_surfaces_workflow_not_found(self, cloud_target, tmp_path, class TestDelete: def test_sends_delete_request(self, cloud_target, monkeypatch, capsys): - calls = _patch_urlopen(monkeypatch, {"/api/workflows/wf-uuid": (b"", 204)}) + calls = _patch_urlopen(monkeypatch, {"/api/features": _FLAG_OFF, "/api/workflows/wf-uuid": (b"", 204)}) env = _run(["delete", "wf-uuid", "--where", "cloud"], capsys) assert env["ok"] is True assert env["data"]["deleted"] is True - assert calls[0]["method"] == "DELETE" + assert calls[-1]["method"] == "DELETE" def test_404_surfaces_workflow_not_found(self, cloud_target, monkeypatch, capsys): err = urllib.error.HTTPError("https://x/workflows/g", 404, "Not Found", {}, io.BytesIO(b"{}")) - _patch_urlopen(monkeypatch, {"/api/workflows/ghost": err}) + _patch_urlopen(monkeypatch, {"/api/features": _FLAG_OFF, "/api/workflows/ghost": err}) env = _run(["delete", "ghost", "--where", "cloud"], capsys) assert env["ok"] is False assert env["error"]["code"] == "workflow_not_found" +def _sidebar_delete( + features=_FLAG_ON, + *, + record=None, + file=None, + record_delete=(b"", 204), + others=(), + content=None, + search=None, +): + """A fake Cloud for delete: record ``rec-1`` and, unless ``file`` is None, the sidebar file of its name. + + ``others`` are more live records, each ``(id, name)``, that the name + search lists beside ``rec-1``. ``content`` is ``rec-1``'s latest version + (``_UI_DATA`` unless given). ``search``, when set, answers the name search + in place of the records. It refuses any userdata DELETE: the CLI must + never delete a sidebar file. + """ + import urllib.parse + + record = {"id": "rec-1", "name": "flux/flux", "latest_version": 1} if record is None else record + content = {"version": 1, "workflow_json": _UI_DATA} if content is None else content + + def handler(method, url, body): + parsed = urllib.parse.urlsplit(url) + path = parsed.path + if path == "/api/features": + return features + if path == "/api/workflows/rec-1" and method == "GET": + return record + if path == "/api/workflows/rec-1/content" and method == "GET": + return content + if path == "/api/workflows" and method == "GET": + if search is not None: + return search + needle = urllib.parse.parse_qs(parsed.query)["name"][0].lower() + rows = [{"id": "rec-1", "name": record["name"], "latest_version": 1}] + rows += [{"id": i, "name": n, "latest_version": 1} for i, n in others] + rows = [r for r in rows if needle in r["name"].lower()] + return {"data": rows, "pagination": {"total": len(rows), "limit": 100, "offset": 0}} + if path.startswith("/api/userdata/") and method == "GET": + return _http_error(404) if file is None else file + if path == "/api/workflows/rec-1" and method == "DELETE": + return record_delete + raise AssertionError(f"unexpected {method} {url}") + + return handler + + +class TestDeleteKeepsTheSidebarFile: + """Flag on: delete removes only the record, as with the flag off, and names a sidebar file that stays.""" + + _RECORD_DELETE = {"url": "https://cloud.example.com/api/workflows/rec-1", "method": "DELETE"} + + def _deletes(self, calls): + return [{"url": c["url"], "method": c["method"]} for c in calls if c["method"] != "GET"] + + def test_a_kept_file_is_named_in_a_warning(self, cloud_target, monkeypatch, capsys): + # Cloud's DELETE /api/workflows/ leaves workflows/flux/flux.json, + # which stays in the sidebar. The CLI says so instead of deleting it: + # Cloud's file DELETE takes no condition and could remove a newer edit. + calls = _patch_cloud(monkeypatch, _sidebar_delete(file=(json.dumps(_UI_DATA).encode(), 200))) + env = _run(["delete", "rec-1", "--where", "cloud"], capsys) + assert env["ok"] is True + assert env["data"]["workflow_id"] == "rec-1" + assert env["data"]["deleted"] is True + [warning] = env["data"]["warnings"] + assert warning["code"] == "sidebar_file_kept" + assert warning["filename"] == "workflows/flux/flux.json" + assert "workflows/flux/flux.json" in warning["message"] + assert self._deletes(calls) == [self._RECORD_DELETE] + # The record's name, its file, the records of that name and the + # record's content are all read before the DELETE renames the record. + assert [(c["method"], c["url"]) for c in calls] == [ + ("GET", "https://cloud.example.com/api/features"), + ("GET", "https://cloud.example.com/api/workflows/rec-1"), + ("GET", "https://cloud.example.com/api/userdata/workflows%2Fflux%2Fflux.json"), + ("GET", "https://cloud.example.com/api/workflows?name=flux%2Fflux&limit=100&offset=0&sort=name&order=asc"), + ("GET", "https://cloud.example.com/api/workflows/rec-1/content"), + ("DELETE", "https://cloud.example.com/api/workflows/rec-1"), + ] + + @pytest.mark.parametrize( + "others, content", + [ + # The finding's case: file A at workflows/flux/flux.json mirrors + # record rec-A, and rec-1 is a record-only workflow B of the same + # name with other content. + pytest.param([("rec-A", "flux/flux")], {"workflow_json": _WF_DATA}, id="other-record-other-content"), + # B was posted with A's exact content: the file still cannot be told apart. + pytest.param([("rec-A", "flux/flux")], None, id="other-record-same-content"), + # A's record is gone and B is the only record of the name. + pytest.param([], {"workflow_json": _WF_DATA}, id="only-record-other-content"), + ], + ) + def test_a_same_named_file_of_another_workflow_is_not_named( + self, cloud_target, monkeypatch, capsys, others, content + ): + # Cloud lets several live records share a name, and a record made by + # POST /api/workflows has no file. So deleting rec-1 must not call + # workflows/flux/flux.json rec-1's file, or the person would remove + # another workflow's file. The delete itself is unchanged. + handler = _sidebar_delete(file=(json.dumps(_UI_DATA).encode(), 200), others=others, content=content) + calls = _patch_cloud(monkeypatch, handler) + env = _run(["delete", "rec-1", "--where", "cloud"], capsys) + assert env["data"] == {"workflow_id": "rec-1", "deleted": True} + assert self._deletes(calls) == [self._RECORD_DELETE] + + def test_a_record_with_a_longer_name_still_gives_the_warning(self, cloud_target, monkeypatch, capsys): + # Cloud's name search matches a substring, so it also lists "flux/flux v2"; + # only an exact name counts as a second record of this name. + handler = _sidebar_delete(file=(json.dumps(_UI_DATA).encode(), 200), others=[("rec-C", "flux/flux v2")]) + _patch_cloud(monkeypatch, handler) + env = _run(["delete", "rec-1", "--where", "cloud"], capsys) + [warning] = env["data"]["warnings"] + assert warning["code"] == "sidebar_file_kept" + assert warning["filename"] == "workflows/flux/flux.json" + + @pytest.mark.parametrize( + "kwargs", + [ + pytest.param({"search": _http_error(500)}, id="name-search-fails"), + pytest.param({"search": {"data": "x"}}, id="name-search-odd"), + pytest.param({"content": _http_error(500)}, id="content-read-fails"), + pytest.param({"content": {"version": 1}}, id="content-without-workflow-json"), + pytest.param({"file": (b"", 200)}, id="file-not-json"), + ], + ) + def test_an_unproven_file_gives_the_plain_delete(self, cloud_target, monkeypatch, capsys, kwargs): + handler = _sidebar_delete(**{"file": (json.dumps(_UI_DATA).encode(), 200), **kwargs}) + calls = _patch_cloud(monkeypatch, handler) + env = _run(["delete", "rec-1", "--where", "cloud"], capsys) + assert env["data"] == {"workflow_id": "rec-1", "deleted": True} + assert self._deletes(calls) == [self._RECORD_DELETE] + + def test_a_name_search_past_the_page_cap_gives_the_plain_delete(self, cloud_target, monkeypatch, capsys): + monkeypatch.setattr(workflow_cmd, "_RECORD_PAGE_SIZE", 1) + monkeypatch.setattr(workflow_cmd, "_MAX_RECORD_PAGES", 1) + handler = _sidebar_delete(file=(json.dumps(_UI_DATA).encode(), 200)) + calls = _patch_cloud(monkeypatch, handler) + env = _run(["delete", "rec-1", "--where", "cloud"], capsys) + assert env["data"] == {"workflow_id": "rec-1", "deleted": True} + assert self._deletes(calls) == [self._RECORD_DELETE] + + def test_no_file_gives_the_plain_delete(self, cloud_target, monkeypatch, capsys): + calls = _patch_cloud(monkeypatch, _sidebar_delete(file=None)) + env = _run(["delete", "rec-1", "--where", "cloud"], capsys) + assert env["data"] == {"workflow_id": "rec-1", "deleted": True} + assert self._deletes(calls) == [self._RECORD_DELETE] + + @pytest.mark.parametrize( + "file", + [ + pytest.param(_http_error(500), id="500"), + pytest.param(http.client.IncompleteRead(b"{"), id="truncated"), + pytest.param(urllib.error.URLError("unreachable"), id="unreachable"), + ], + ) + def test_a_failed_file_read_gives_the_plain_delete(self, cloud_target, monkeypatch, capsys, file): + calls = _patch_cloud(monkeypatch, _sidebar_delete(file=file)) + env = _run(["delete", "rec-1", "--where", "cloud"], capsys) + assert env["data"] == {"workflow_id": "rec-1", "deleted": True} + assert self._deletes(calls) == [self._RECORD_DELETE] + + def test_a_failed_record_read_gives_the_plain_delete(self, cloud_target, monkeypatch, capsys): + calls = _patch_cloud(monkeypatch, _sidebar_delete(record=_http_error(500), file=(b"{}", 200))) + env = _run(["delete", "rec-1", "--where", "cloud"], capsys) + assert env["data"] == {"workflow_id": "rec-1", "deleted": True} + assert self._deletes(calls) == [self._RECORD_DELETE] + assert not any("/api/userdata/" in c["url"] for c in calls) + + @pytest.mark.parametrize("name", ["../x", "a//b", "a\\b", "", None]) + def test_a_name_that_is_no_file_path_is_not_looked_up(self, cloud_target, monkeypatch, capsys, name): + record = {"id": "rec-1", "name": name} + calls = _patch_cloud(monkeypatch, _sidebar_delete(record=record, file=(b"{}", 200))) + env = _run(["delete", "rec-1", "--where", "cloud"], capsys) + assert env["data"] == {"workflow_id": "rec-1", "deleted": True} + assert not any("/api/userdata/" in c["url"] for c in calls) + + def test_flag_off_never_looks_for_a_file(self, cloud_target, monkeypatch, capsys): + calls = _patch_cloud(monkeypatch, _sidebar_delete(features=_FLAG_OFF, file=(b"{}", 200))) + env = _run(["delete", "rec-1", "--where", "cloud"], capsys) + assert env["data"] == {"workflow_id": "rec-1", "deleted": True} + assert [c["url"] for c in calls] == [ + "https://cloud.example.com/api/features", + "https://cloud.example.com/api/workflows/rec-1", + ] + + def test_a_failed_record_delete_is_the_same_error_as_before(self, cloud_target, monkeypatch, capsys): + handler = _sidebar_delete(file=(b"{}", 200), record_delete=_http_error(404)) + calls = _patch_cloud(monkeypatch, handler) + env = _run(["delete", "rec-1", "--where", "cloud"], capsys) + assert env["ok"] is False + assert env["error"]["code"] == "workflow_not_found" + assert self._deletes(calls) == [self._RECORD_DELETE] + + # --------------------------------------------------------------------------- # unparseable 200 body — must surface a loud error, not empty/success # --------------------------------------------------------------------------- @@ -817,7 +1469,7 @@ def test_list_surfaces_error_not_empty(self, cloud_target, monkeypatch, capsys, def test_save_surfaces_error_not_null_id(self, cloud_target, tmp_path, monkeypatch, capsys, raw): wf_path = tmp_path / "wf.json" wf_path.write_text(json.dumps({"1": {"class_type": "KSampler", "inputs": {}}})) - _patch_urlopen(monkeypatch, {"/api/workflows": (raw, 200)}) + _patch_urlopen(monkeypatch, {"/api/features": _FLAG_OFF, "/api/workflows": (raw, 200)}) env = _run(["save", str(wf_path), "--name", "x", "--where", "cloud"], capsys) # Must NOT claim success with a null workflow_id. assert env["ok"] is False @@ -835,7 +1487,7 @@ def test_get_surfaces_error_not_missing_content(self, cloud_target, monkeypatch, @pytest.mark.parametrize("raw", _UNPARSEABLE_BODIES) def test_delete_surfaces_error_not_success(self, cloud_target, monkeypatch, capsys, raw): - _patch_urlopen(monkeypatch, {"/api/workflows/wf-uuid": (raw, 200)}) + _patch_urlopen(monkeypatch, {"/api/features": _FLAG_OFF, "/api/workflows/wf-uuid": (raw, 200)}) env = _run(["delete", "wf-uuid", "--where", "cloud"], capsys) # Must NOT claim a successful delete off an unparseable body. assert env["ok"] is False