v1.0.0

skills/creative/comfyui/scripts/check_deps.py

@@ -0,0 +1,437 @@
+#!/usr/bin/env python3
+"""
+check_deps.py — Verify a ComfyUI workflow's dependencies (custom nodes, models,
+embeddings) against a running server.
+
+Improvements over v1:
+  - Cloud-aware endpoint mapping (handles `/api/experiment/models/{folder}` and
+    `/api/object_info` variants verified against live cloud API)
+  - Distinguishes 200-empty (genuinely no models in folder) vs 404
+    (folder doesn't exist) vs 403 (auth/tier issue) — no silent passes
+  - Outputs concrete remediation commands (e.g. `comfy node install <name>`)
+    when nodes are missing
+  - Detects embedding references inside prompt strings as model deps
+  - Skips check on cloud free tier `/api/object_info` (403) without false alarm
+  - Accepts API key from CLI flag OR $COMFY_CLOUD_API_KEY env var
+
+Usage:
+    python3 check_deps.py workflow_api.json
+    python3 check_deps.py workflow_api.json --host 127.0.0.1 --port 8188
+    python3 check_deps.py workflow_api.json --host https://cloud.comfy.org
+
+Stdlib-only. Python 3.10+.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from _common import (  # noqa: E402
+    DEFAULT_LOCAL_HOST, ENV_API_KEY,
+    emit_json, folder_aliases_for, http_get, is_cloud_host,
+    iter_embedding_refs, iter_model_deps, iter_nodes, parse_model_list,
+    resolve_api_key, resolve_url, unwrap_workflow,
+)
+
+
+# Known node → custom-node-package map. When a workflow needs a node we don't
+# recognize, suggesting the right `comfy node install ...` makes the difference
+# between a working agent and a stuck one.
+NODE_TO_PACKAGE: dict[str, str] = {
+    # rgthree (Reroute is JS-only and doesn't appear in /object_info)
+    "Power Lora Loader (rgthree)": "rgthree-comfy",
+    "Image Comparer (rgthree)": "rgthree-comfy",
+    "Seed (rgthree)": "rgthree-comfy",
+    "Display Any (rgthree)": "rgthree-comfy",
+    "Display Int (rgthree)": "rgthree-comfy",
+    # Impact pack
+    "FaceDetailer": "comfyui-impact-pack",
+    "DetailerForEach": "comfyui-impact-pack",
+    "BboxDetectorSEGS": "comfyui-impact-pack",
+    "SAMLoader": "comfyui-impact-pack",
+    "ImpactWildcardProcessor": "comfyui-impact-pack",
+    # Impact subpack (separate package)
+    "UltralyticsDetectorProvider": "comfyui-impact-subpack",
+    # Was Node Suite
+    "Image Save": "was-node-suite-comfyui",
+    "Number Counter": "was-node-suite-comfyui",
+    "Text String": "was-node-suite-comfyui",
+    # easy-use
+    "easy fullLoader": "comfyui-easy-use",
+    "easy positive": "comfyui-easy-use",
+    "easy negative": "comfyui-easy-use",
+    "easy seed": "comfyui-easy-use",
+    "easy imageSave": "comfyui-easy-use",
+    # Video Helper Suite
+    "VHS_VideoCombine": "comfyui-videohelpersuite",
+    "VHS_LoadVideo": "comfyui-videohelpersuite",
+    "VHS_LoadAudio": "comfyui-videohelpersuite",
+    # AnimateDiff
+    "ADE_AnimateDiffLoaderWithContext": "comfyui-animatediff-evolved",
+    "ADE_AnimateDiffLoaderGen1": "comfyui-animatediff-evolved",
+    "ADE_LoadAnimateDiffModel": "comfyui-animatediff-evolved",
+    # ControlNet aux preprocessors (full class names)
+    "CannyEdgePreprocessor": "comfyui_controlnet_aux",
+    "DWPreprocessor": "comfyui_controlnet_aux",
+    "OpenposePreprocessor": "comfyui_controlnet_aux",
+    "DepthAnythingPreprocessor": "comfyui_controlnet_aux",
+    "Zoe_DepthAnythingPreprocessor": "comfyui_controlnet_aux",
+    "AnimalPosePreprocessor": "comfyui_controlnet_aux",
+    # IPAdapter Plus
+    "IPAdapterAdvanced": "comfyui_ipadapter_plus",
+    "IPAdapterUnifiedLoader": "comfyui_ipadapter_plus",
+    "IPAdapterModelLoader": "comfyui_ipadapter_plus",
+    "IPAdapterInsightFaceLoader": "comfyui_ipadapter_plus",
+    # InstantID
+    "InstantIDModelLoader": "comfyui_instantid",
+    "ApplyInstantID": "comfyui_instantid",
+    # Comfy essentials (note: registry slug uses underscore, not hyphen)
+    "GetImageSize+": "comfyui_essentials",
+    "ImageBatchMultiple+": "comfyui_essentials",
+    # pysssss
+    "ShowText|pysssss": "comfyui-custom-scripts",
+    "PreviewImage|pysssss": "comfyui-custom-scripts",
+    # SUPIR
+    "SUPIR_Upscale": "comfyui-supir",
+    "SUPIR_first_stage": "comfyui-supir",
+    # GGUF (case-sensitive registry slug)
+    "UNETLoaderGGUF": "ComfyUI-GGUF",
+    "DualCLIPLoaderGGUF": "ComfyUI-GGUF",
+    # Florence2
+    "Florence2Run": "comfyui-florence2",
+    # WAS
+    "Image Filter Adjustments": "was-node-suite-comfyui",
+    # Photomaker (case-sensitive)
+    "PhotoMakerLoader": "ComfyUI-PhotoMaker-Plus",
+    # Wan video (case-sensitive)
+    "WanVideoSampler": "ComfyUI-WanVideoWrapper",
+    "WanVideoModelLoader": "ComfyUI-WanVideoWrapper",
+}
+
+# Nodes whose package isn't on the comfy registry — need git-URL install via
+# ComfyUI-Manager. We surface a helpful hint instead of an unrunnable command.
+NODE_TO_GIT_URL: dict[str, str] = {
+    "HunyuanVideoSampler": "https://github.com/kijai/ComfyUI-HunyuanVideoWrapper",
+    "HunyuanVideoModelLoader": "https://github.com/kijai/ComfyUI-HunyuanVideoWrapper",
+}
+
+
+def fetch_object_info(url: str, headers: dict) -> tuple[set[str] | None, dict | None]:
+    """Returns (installed_node_set, error_info). Error info is a dict if we
+    couldn't query (e.g. cloud free tier), else None.
+    """
+    r = http_get(url, headers=headers, retries=2, timeout=30)
+    if r.status == 200:
+        try:
+            data = r.json()
+            if isinstance(data, dict):
+                return set(data.keys()), None
+        except Exception:
+            pass
+        return None, {"http_status": 200, "reason": "non-dict response"}
+    if r.status == 403:
+        try:
+            body = r.json()
+        except Exception:
+            body = {"raw": r.text()[:200]}
+        return None, {"http_status": 403, "reason": "forbidden", "body": body}
+    if r.status == 404:
+        return None, {"http_status": 404, "reason": "endpoint not found"}
+    return None, {"http_status": r.status, "reason": "unexpected", "body": r.text()[:200]}
+
+
+def _fetch_one_folder(
+    base: str, folder: str, headers: dict, *, is_cloud: bool,
+) -> tuple[set[str] | None, dict | None]:
+    """Single-folder fetch, no aliasing. Returns (installed_set, error_info)."""
+    url = resolve_url(base, f"/models/{folder}", is_cloud=is_cloud)
+    r = http_get(url, headers=headers, retries=2, timeout=30)
+    if r.status == 200:
+        try:
+            return parse_model_list(r.json()), None
+        except Exception:
+            return set(), {"http_status": 200, "reason": "non-list response"}
+    if r.status == 404:
+        body_text = r.text()
+        try:
+            body = r.json()
+        except Exception:
+            body = {"raw": body_text[:200]}
+        code = body.get("code") if isinstance(body, dict) else None
+        if code == "folder_not_found":
+            # Folder is genuinely empty/missing on server — not the same as
+            # "endpoint missing". Return empty set with informational error.
+            return set(), {"http_status": 404, "reason": "folder_empty_or_unknown", "body": body}
+        return None, {"http_status": 404, "reason": "endpoint not found", "body": body}
+    if r.status == 403:
+        try:
+            body = r.json()
+        except Exception:
+            body = {}
+        return None, {"http_status": 403, "reason": "forbidden", "body": body}
+    return None, {"http_status": r.status, "reason": "unexpected"}
+
+
+def fetch_models_for_folder(
+    base: str, folder: str, headers: dict, *, is_cloud: bool,
+) -> tuple[set[str] | None, dict | None]:
+    """Fetch installed models for a folder, trying aliases.
+
+    Folder renames over time (e.g. unet → diffusion_models, clip → text_encoders)
+    mean a workflow asking for a model in `unet` may need to look in
+    `diffusion_models`. We union models from every reachable alias.
+
+    Returns (combined_set | None, last_error | None).
+    """
+    aliases = folder_aliases_for(folder)
+    combined: set[str] = set()
+    any_success = False
+    last_err: dict | None = None
+    for alias in aliases:
+        models, err = _fetch_one_folder(base, alias, headers, is_cloud=is_cloud)
+        if models is not None:
+            combined.update(models)
+            any_success = True
+            last_err = None
+        else:
+            last_err = err
+    if not any_success:
+        return None, last_err
+    return combined, None
+
+
+def fetch_embeddings(base: str, headers: dict, *, is_cloud: bool) -> tuple[set[str] | None, dict | None]:
+    """Local ComfyUI exposes /embeddings; cloud uses /experiment/models/embeddings."""
+    if is_cloud:
+        return fetch_models_for_folder(base, "embeddings", headers, is_cloud=True)
+    # Local: dedicated /embeddings returns a flat list of names
+    r = http_get(resolve_url(base, "/embeddings", is_cloud=False), headers=headers, retries=2)
+    if r.status == 200:
+        try:
+            data = r.json()
+            if isinstance(data, list):
+                # Strip extensions from the registered names since prompt syntax
+                # usually omits them ("embedding:goodvibes" vs "goodvibes.pt")
+                names = set()
+                for n in data:
+                    if isinstance(n, str):
+                        names.add(n)
+                        # Also store stem for fuzzy matching
+                        names.add(Path(n).stem)
+                return names, None
+        except Exception:
+            pass
+    return None, {"http_status": r.status, "reason": "unexpected"}
+
+
+def normalize_for_match(name: str) -> set[str]:
+    """Generate matching variants of a model name (with/without extension, slashes, etc.)"""
+    s = {name}
+    s.add(Path(name).stem)
+    s.add(Path(name).name)
+    # ComfyUI sometimes strips/keeps the leading folder
+    if "/" in name or "\\" in name:
+        flat = name.replace("\\", "/").split("/")[-1]
+        s.add(flat)
+        s.add(Path(flat).stem)
+    return {x for x in s if x}
+
+
+def model_present(needed: str, installed: set[str]) -> bool:
+    if not installed:
+        return False
+    needed_variants = normalize_for_match(needed)
+    installed_norm: set[str] = set()
+    for inst in installed:
+        installed_norm.update(normalize_for_match(inst))
+    return bool(needed_variants & installed_norm)
+
+
+def suggest_install_command(node_class: str) -> str | None:
+    pkg = NODE_TO_PACKAGE.get(node_class)
+    if pkg:
+        return f"comfy node install {pkg}"
+    return None
+
+
+def suggest_git_url(node_class: str) -> str | None:
+    """For nodes not on the registry, return a git URL the user can hand to
+    ComfyUI-Manager's `/manager/queue/install` endpoint."""
+    return NODE_TO_GIT_URL.get(node_class)
+
+
+def check_deps(
+    workflow: dict, host: str, *, api_key: str | None = None,
+) -> dict:
+    headers: dict[str, str] = {}
+    if api_key:
+        headers["X-API-Key"] = api_key
+
+    is_cloud = is_cloud_host(host)
+    base = host.rstrip("/")
+
+    # ---- 1. Required nodes ----
+    required_nodes: set[str] = set()
+    for _, node in iter_nodes(workflow):
+        required_nodes.add(node["class_type"])
+
+    object_info_url = resolve_url(base, "/object_info", is_cloud=is_cloud)
+    installed_nodes, obj_err = fetch_object_info(object_info_url, headers)
+
+    missing_nodes: list[dict] = []
+    node_check_skipped = False
+    if installed_nodes is None:
+        # Couldn't query (e.g. cloud free tier). Don't false-alarm; mark skipped.
+        node_check_skipped = True
+    else:
+        for cls in sorted(required_nodes):
+            if cls not in installed_nodes:
+                entry = {"class_type": cls}
+                cmd = suggest_install_command(cls)
+                git_url = suggest_git_url(cls)
+                if cmd:
+                    entry["fix_command"] = cmd
+                elif git_url:
+                    entry["fix_git_url"] = git_url
+                    entry["fix_hint"] = (
+                        f"Not on registry. Install via Manager with this git URL: {git_url}"
+                    )
+                else:
+                    entry["fix_hint"] = (
+                        "Search https://registry.comfy.org or "
+                        "use ComfyUI-Manager UI to find the package providing this node."
+                    )
+                missing_nodes.append(entry)
+
+    # ---- 2. Required models ----
+    model_cache: dict[str, tuple[set[str] | None, dict | None]] = {}
+    missing_models: list[dict] = []
+    folder_errors: dict[str, dict] = {}
+
+    for dep in iter_model_deps(workflow):
+        folder = dep["folder"]
+        if folder not in model_cache:
+            model_cache[folder] = fetch_models_for_folder(
+                base, folder, headers, is_cloud=is_cloud,
+            )
+        installed, err = model_cache[folder]
+        if installed is None:
+            # Couldn't enumerate this folder — record once
+            folder_errors.setdefault(folder, err or {})
+            # Don't flag as missing (we don't know); the folder_errors block surfaces this
+            continue
+        if not model_present(dep["value"], installed):
+            entry = dict(dep)
+            entry["fix_hint"] = (
+                f"comfy model download --url <URL> --relative-path models/{folder} "
+                f"--filename {dep['value']!r}"
+            )
+            missing_models.append(entry)
+
+    # ---- 3. Embedding refs in prompts ----
+    emb_installed, emb_err = fetch_embeddings(base, headers, is_cloud=is_cloud)
+    missing_embeddings: list[dict] = []
+    seen_emb: set[tuple[str, str]] = set()
+    for nid, emb_name in iter_embedding_refs(workflow):
+        if (nid, emb_name) in seen_emb:
+            continue
+        seen_emb.add((nid, emb_name))
+        if emb_installed is None:
+            # Couldn't enumerate — skip silently here, surface the error in the
+            # folder_errors block
+            continue
+        if not model_present(emb_name, emb_installed):
+            missing_embeddings.append({
+                "node_id": nid,
+                "embedding_name": emb_name,
+                "folder": "embeddings",
+                "fix_hint": (
+                    f"Download {emb_name}.pt or .safetensors and place in "
+                    f"models/embeddings/, or `comfy model download --url <URL> "
+                    f"--relative-path models/embeddings`"
+                ),
+            })
+
+    if emb_err and emb_installed is None:
+        folder_errors.setdefault("embeddings", emb_err)
+
+    is_ready = (
+        not node_check_skipped
+        and not missing_nodes
+        and not missing_models
+        and not missing_embeddings
+    )
+
+    return {
+        "is_ready": is_ready,
+        "node_check_skipped": node_check_skipped,
+        "node_check_skip_reason": obj_err if node_check_skipped else None,
+        "missing_nodes": missing_nodes,
+        "missing_models": missing_models,
+        "missing_embeddings": missing_embeddings,
+        "folder_errors": folder_errors,
+        # 0 is a legitimate count (e.g. empty server). Use None only when not queried.
+        "installed_node_count": len(installed_nodes) if installed_nodes is not None else None,
+        "required_node_count": len(required_nodes),
+        "required_nodes": sorted(required_nodes),
+        "host": base,
+        "is_cloud": is_cloud,
+    }
+
+
+def main(argv: list[str] | None = None) -> int:
+    p = argparse.ArgumentParser(description="Check ComfyUI workflow dependencies against a running server")
+    p.add_argument("workflow", help="Path to workflow API JSON file")
+    p.add_argument("--host", default=DEFAULT_LOCAL_HOST, help="ComfyUI server URL")
+    p.add_argument("--port", type=int, help="Server port (overrides --host port)")
+    p.add_argument("--api-key", help=f"API key for cloud (or set ${ENV_API_KEY} env var)")
+    p.add_argument("--strict", action="store_true",
+                   help="Exit non-zero if node check is skipped (e.g. on cloud free tier)")
+    args = p.parse_args(argv)
+
+    host = args.host
+    if args.port is not None:
+        # Strip any port from host and append --port
+        from urllib.parse import urlparse, urlunparse
+        parsed = urlparse(host if "://" in host else f"http://{host}")
+        new_netloc = f"{parsed.hostname}:{args.port}"
+        host = urlunparse(parsed._replace(netloc=new_netloc))
+
+    api_key = resolve_api_key(args.api_key)
+
+    wf_path = Path(args.workflow).expanduser()
+    if not wf_path.exists():
+        emit_json({"error": f"Workflow file not found: {args.workflow}"})
+        return 1
+    try:
+        with wf_path.open() as f:
+            payload = json.load(f)
+        workflow = unwrap_workflow(payload)
+    except ValueError as e:
+        emit_json({"error": str(e)})
+        return 1
+    except json.JSONDecodeError as e:
+        emit_json({"error": f"Invalid JSON: {e}"})
+        return 1
+
+    try:
+        result = check_deps(workflow, host=host, api_key=api_key)
+    except Exception as e:
+        emit_json({"error": f"Dep check failed: {e}", "host": host})
+        return 1
+
+    emit_json(result)
+
+    if not result["is_ready"]:
+        return 1
+    if args.strict and result["node_check_skipped"]:
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())