Add ComfyUI node compatibility checker

.env.example

@@ -1,7 +1,11 @@
-# Local ComfyUI checkout used by maintenance scripts (e.g. API node model scanner).
-# Scripts append /comfy_api_nodes automatically — point this at the ComfyUI repo root.
+# Local ComfyUI checkout used by maintenance scripts (e.g. API node model scanner,
+# static node-compat scan). For live local checks, start ComfyUI and run
+# npm run validate:comfyui-nodes (uses http://127.0.0.1:8188/object_info).
 COMFYUI_REPO_PATH=/path/to/ComfyUI
 
+# Optional override for live local /object_info checks:
+# COMFYUI_OBJECT_INFO_URL=http://127.0.0.1:8188/object_info
+
 # =============================================================================
 # MCP AI enhancement (Step 2: enhance_models_registry.py, enhance_descriptions.py)
 # =============================================================================

.github/workflows/README.md

@@ -54,3 +54,33 @@ Validates template JSON structure, thumbnails, and checks for third-party nodes.
 ### 4. Publish (`publish.yml`)
 
 Publishes approved templates to the registry.
+
+### 5. ComfyUI Node Compatibility Report (`report-comfyui-node-compat.yml`)
+
+Informational check — **never blocks PR merges**. Compares changed `templates/*.json` against ComfyUI `master` via static source scan (no torch, no running server).
+
+**What it checks (static mode):**
+- Deprecated nodes (display name contains `DEPRECATED`)
+
+**When it runs:**
+- On pull requests that change files under `templates/` only
+- Manual dispatch
+
+**How it works:**
+1. Sparse-checkout template JSON + compat scripts only
+2. Shallow-clone `Comfy-Org/ComfyUI` and run `scripts/comfyui_node_compat/check.py --static-scan --clone-comfyui`
+3. Post or update a single PR comment with the Markdown report
+4. Upload `compat_report.md` / `.json` as a workflow artifact
+
+**Local testing (full coverage — needs running ComfyUI):**
+```bash
+npm run validate:comfyui-nodes
+# Reports: comfyui-node-compat.latest.log, comfyui-node-compat.log (gitignored)
+```
+
+**Local testing (CI-style static scan):**
+```bash
+python3 scripts/comfyui_node_compat/check.py --static-scan --clone-comfyui --no-fail
+```
+
+See [`scripts/README.md`](../scripts/README.md#comfyui-node-compatibility-check) for issue types, log tiers, and flags.

.github/workflows/report-comfyui-node-compat.yml

@@ -0,0 +1,145 @@
+name: ComfyUI Node Compatibility Report
+
+# Informational report only — never blocks PR merges.
+# Statically scans ComfyUI master source + templates/*.json (no torch, no running server).
+
+on:
+  pull_request:
+    types: [opened, synchronize]
+    paths:
+      - 'templates/**'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pull-requests: write
+
+env:
+  COMFYUI_GITHUB_REPO: Comfy-Org/ComfyUI
+  COMFYUI_REF: master
+
+jobs:
+  report:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout workflow templates (JSON only)
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.pull_request.head.sha || github.sha }}
+          sparse-checkout: |
+            templates/*.json
+            scripts/comfyui_node_compat/
+            scripts/lib/paths.py
+            scripts/lib/locale_index_files.py
+          sparse-checkout-cone-mode: false
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Run static ComfyUI node compatibility check
+        id: compat_check
+        continue-on-error: true
+        run: |
+          python3 scripts/comfyui_node_compat/check.py \
+            --static-scan \
+            --clone-comfyui \
+            --templates-dir templates \
+            --markdown-output compat_report.md \
+            --json-output compat_report.json \
+            --no-log-file \
+            --no-fail | tee compat_check.log
+
+      - name: Write workflow failure report
+        if: steps.compat_check.outcome != 'success'
+        run: |
+          cat > compat_report.md <<EOF
+          ## ComfyUI Node Compatibility Report
+
+          **Status: check could not complete** — no template compatibility results were produced.
+
+          _Informational only — this check does not block merging._
+
+          ### Setup failure
+          - Static compatibility script exited with an error (see workflow logs).
+          - Expected mode: \`--static-scan --clone-comfyui\` against \`${COMFYUI_GITHUB_REPO}\` (\`${COMFYUI_REF}\`).
+
+          ### Next steps
+          - Open the workflow run logs for details.
+          - Re-run locally after starting ComfyUI: \`npm run validate:comfyui-nodes\`
+          - Or run CI-style static scan locally:
+            \`python3 scripts/comfyui_node_compat/check.py --static-scan --clone-comfyui\`
+          EOF
+
+      - name: Comment compatibility report on PR
+        if: always() && github.event_name == 'pull_request'
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          script: |
+            const fs = require('fs');
+
+            const readFile = (path) => {
+              try {
+                return fs.readFileSync(path, 'utf8');
+              } catch {
+                return '';
+              }
+            };
+
+            let report = readFile('compat_report.md').trim();
+            if (!report) {
+              report = [
+                '## ComfyUI Node Compatibility Report',
+                '',
+                '**Status: no report generated.**',
+                '',
+                '_Informational only — this check does not block merging._',
+                '',
+                readFile('compat_check.log').trim() || 'See workflow logs for details.',
+              ].join('\n');
+            }
+
+            const marker = '<!-- comfyui-node-compat-report -->';
+            const maxLength = 60000;
+            if (report.length > maxLength) {
+              report = report.slice(0, maxLength) + '\n\n...(Report truncated due to length. Download the workflow artifact for the full report.)';
+            }
+
+            const body = `${marker}\n${report}\n\n---\n*This comment is automatically updated by the ComfyUI Node Compatibility Report workflow.*`;
+
+            const { data: comments } = await github.rest.issues.listComments({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+            });
+
+            const existing = comments.find((comment) => comment.body.includes(marker));
+            if (existing) {
+              await github.rest.issues.updateComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                comment_id: existing.id,
+                body,
+              });
+            } else {
+              await github.rest.issues.createComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: context.issue.number,
+                body,
+              });
+            }
+
+      - name: Upload compatibility report artifact
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: comfyui-node-compat-report
+          path: |
+            compat_report.md
+            compat_report.json
+            compat_check.log
+          if-no-files-found: ignore
+          retention-days: 14

.gitignore

@@ -87,6 +87,10 @@ LINK_CHECKER_REPORT.md
 asset_validation_report.md
 model_analysis_report.md
 
+# ComfyUI node compatibility check logs (npm run validate:comfyui-nodes)
+comfyui-node-compat.log
+comfyui-node-compat.latest.log
+
 # Python cache
 *.pyc
 *.pyo

AGENTS.md

@@ -10,8 +10,10 @@
 - `npm run mcp:models` — AI model profiles in `models_registry.json`
 - `npm run validate:templates` — Validate template JSON files
 - `npm run validate:manifests` — Validate package manifests
+- `npm run validate:comfyui-nodes` — Compare templates to ComfyUI node baseline (local: live `/object_info`)
 - `python scripts/sync/sync_bundles.py` — Same as `npm run sync:bundles`
 - `python scripts/validate/validate_templates.py` — Same as `npm run validate:templates`
+- `python scripts/comfyui_node_compat/check.py --static-scan --clone-comfyui --no-fail` — CI-style static compat scan
 
 **MCP index pipeline:** see skill `.claude/skills/managing-mcp-index/SKILL.md` and `scripts/mcp/docs/MCP_AI_ENHANCEMENT.md`. Do not confuse with hub i18n (`i18n`) or site AI (`site/scripts/generate-ai.ts`).
 
@@ -33,6 +35,7 @@ Root `scripts/` is organized by role:
 | `scripts/sync/` | Sync / generate data | `sync_data.py`, `sync_bundles.py` |
 | `scripts/mcp/` | MCP index pipeline | `sync_index.py`, `enhance_descriptions.py` |
 | `scripts/validate/` | Validation & analysis (CI) | `validate_templates.py`, `check_links.py`, `analyze_models.py` |
+| `scripts/comfyui_node_compat/` | ComfyUI node baseline vs templates | `check.py` |
 | `scripts/blueprints/` | Blueprint-specific import | `import_blueprints.py` |
 | `scripts/ci/` | Release pipeline only | `ci_version_manager.py`, `check_pypi_quota.py` |
 | `scripts/data/` | Static config JSON | `i18n.json`, `whitelist.json`, `mcp/models_registry.json`, `mcp/template_cache.json` |

README.md

@@ -67,6 +67,7 @@ PR opened/updated
 | Add a workflow template | Edit `templates/`, `bundles.json`, then `python scripts/sync/sync_bundles.py` |
 | Add a subgraph blueprint | Edit `blueprints/`, `blueprints_bundles.json`, then `python scripts/sync/sync_blueprints.py` |
 | Import external blueprints | Copy JSONs to `blueprints/`, then `python scripts/blueprints/import_blueprints.py` |
+| Check node compatibility | `npm run validate:comfyui-nodes` (local ComfyUI) or see [`scripts/README.md`](scripts/README.md#comfyui-node-compatibility-check) |
 
 ---
 
@@ -580,9 +581,13 @@ CI automatically validates:
 | Bundle consistency | ✅ | ✅ |
 | Manifest sync | ✅ | ✅ |
 | Thumbnails | ✅ | ❌ (optional) |
+| ComfyUI node compatibility | ✅ (informational PR comment) | ❌ |
 
 Run locally before committing:
 ```bash
 python scripts/sync/sync_bundles.py      # Templates
 python scripts/sync/sync_blueprints.py   # Blueprints
+npm run validate:comfyui-nodes           # Optional: node baseline vs templates (needs running ComfyUI)
 ```
+
+See [`scripts/README.md`](scripts/README.md#comfyui-node-compatibility-check) for local vs static scan modes and log output.

package.json

@@ -16,6 +16,7 @@
     "mcp:models": "python scripts/mcp/enhance_models_registry.py",
     "validate:templates": "python scripts/validate/validate_templates.py",
     "validate:manifests": "python scripts/validate/validate_manifests.py",
+    "validate:comfyui-nodes": "python3 scripts/comfyui_node_compat/check.py",
     "build:all": "NX_ADD_PLUGINS=false NX_DAEMON=false npx nx run-many --target build --skip-nx-cache",
     "site:install": "cd site && pnpm install",
     "site:dev": "cd site && pnpm run dev",

scripts/README.md

@@ -11,6 +11,7 @@ Python maintenance scripts for ComfyUI workflow templates (packages, CI, i18n).
 | Sync blueprints | `python scripts/sync/sync_blueprints.py` |
 | Validate templates | `python scripts/validate/validate_templates.py` |
 | Validate manifests | `python scripts/validate/validate_manifests.py` |
+| ComfyUI node compatibility | `npm run validate:comfyui-nodes` |
 | Maintainer smoke check | `./scripts/maintenance/check_templates.sh` |
 
 ## Directory layout
@@ -20,6 +21,7 @@ Python maintenance scripts for ComfyUI workflow templates (packages, CI, i18n).
 | [`sync/`](sync/) | Data synchronization and generation |
 | [`mcp/`](mcp/) | MCP index pipeline (`index.mcp.json`) |
 | [`validate/`](validate/) | Validation and analysis (most run in CI) |
+| [`comfyui_node_compat/`](comfyui_node_compat/) | ComfyUI node baseline vs template workflows (informational) |
 | [`blueprints/`](blueprints/) | Subgraph blueprint import |
 | [`ci/`](ci/) | Release pipeline helpers (version, PyPI quota) |
 | [`maintenance/`](maintenance/) | Local-only tools (archive, one-off fixes) |
@@ -51,6 +53,7 @@ Also runs workflow I/O extraction via `generate_workflow_io.py` before locale sy
 | `validate-blueprints.yml` | `validate/validate_blueprints.py`, `blueprints/import_blueprints.py`, `sync/sync_blueprints.py` |
 | `link-checker.yml` | `validate/check_links.py`, `data/whitelist.json` |
 | `model-analysis.yml` | `validate/analyze_models.py`, `data/whitelist.json` |
+| `report-comfyui-node-compat.yml` | `comfyui_node_compat/check.py` (static scan; PR comment only) |
 | `check_input_assets.yml`, `generate-upload-json.yml` | `validate/check_input_assets.py` |
 | `sync-custom-nodes.yml` | `sync/sync_custom_nodes.py` |
 | `version-check.yml`, `publish.yml` | `ci/ci_version_manager.py`, `sync/sync_bundles.py`, `ci/*` |
@@ -84,4 +87,94 @@ npm run mcp:models   # AI model registry
 - **`data/mcp/template_cache.json`** — Per-template AI copy, versioned by workflow JSON hash.
 - **`data/krea_registry_aliases.json`**, **`data/krea_*_models.json`** — Temporary Krea snapshots for one-off registry seeding (delete when seeding is complete).
 
-Generated output goes to `scripts/.output/` (gitignored) or repo root (`model_analysis_report.md`, `asset_validation_report.md`).
+Generated output goes to `scripts/.output/` (gitignored) or repo root (`model_analysis_report.md`, `asset_validation_report.md`, `comfyui-node-compat.log`, `comfyui-node-compat.latest.log`).
+
+## ComfyUI node compatibility check
+
+Compares `templates/*.json` workflows against a ComfyUI node baseline. **Informational only** — does not block PR merges. On PRs that change `templates/`, [`report-comfyui-node-compat.yml`](../.github/workflows/report-comfyui-node-compat.yml) posts/updates a comment with findings.
+
+### Local (recommended for full coverage)
+
+Requires a running ComfyUI instance. Reads live `/object_info` (full combo lists, API nodes, inputs):
+
+```bash
+npm run validate:comfyui-nodes
+# same as:
+python3 scripts/comfyui_node_compat/check.py
+```
+
+If ComfyUI is not reachable, the script exits with a hint to start the server or use `--static-scan`.
+
+Reports are written to repo root (gitignored):
+
+- `comfyui-node-compat.latest.log` — latest run (overwrite)
+- `comfyui-node-compat.log` — append-only history
+
+### CI / static scan (no server, no torch)
+
+Clones `Comfy-Org/ComfyUI` and AST-scans Python sources. Faster and dependency-free, but only reports **deprecated nodes** (skips missing-node / combo noise from incomplete static parsing):
+
+```bash
+python3 scripts/comfyui_node_compat/check.py --static-scan --clone-comfyui --no-fail
+```
+
+Use an existing checkout instead of cloning:
+
+```bash
+export COMFYUI_REPO_PATH=/path/to/ComfyUI
+python3 scripts/comfyui_node_compat/check.py --static-scan --no-fail
+```
+
+### What it detects
+
+| Issue kind | Severity | Local | Static |
+|------------|----------|-------|--------|
+| `invalid_api_model` | error | ✅ | — |
+| `widget_slot_mismatch` | error | ✅ (API nodes) | — |
+| `invalid_widget_value` | error | ✅ (API nodes) | — |
+| `missing_node` | error | ✅ | — |
+| `invalid_combo_value` | error | ✅ | — |
+| `missing_input` | error | ✅ | — |
+| `deprecated_node` | warning | ✅ | ✅ |
+
+Runtime checks map save-format `widgets_values[]` to field names via `/object_info` `input_order` (skipping linked sockets and non-widget types like IMAGE/AUDIO, while preserving linked rows that are still widget-backed). Filesystem-backed dropdowns such as model, upload, and 3D asset pickers are treated as local-install dependent. This catches API workflows whose widget slots drifted after a node schema change (e.g. a new `resolution` field inserted mid-list) without turning every local missing model into a template error.
+
+Log and PR reports group findings by priority:
+
+1. **Critical** — workflow will likely fail or run with wrong inputs (`invalid_api_model`, `widget_slot_mismatch`)
+2. **Errors** — removed nodes, invalid inputs, stale combo values
+3. **Warnings** — deprecated nodes and other review items
+
+### Useful flags
+
+| Flag | Purpose |
+|------|---------|
+| `--static-scan` | Source scan without running ComfyUI |
+| `--clone-comfyui` | Shallow-clone ComfyUI master for static scan |
+| `--comfyui-dir PATH` | ComfyUI checkout for static scan |
+| `--object-info-url URL` | Override live endpoint (default `http://127.0.0.1:8188/object_info`) |
+| `--object-info-json PATH` | Debug with a saved `/object_info` JSON |
+| `--strict-unknown` | Warn on unknown non-core custom nodes |
+| `--no-log-file` | Skip writing log files (CI default) |
+| `--no-fail` | Exit 0 even when errors are found |
+| `--markdown-output PATH` | Write Markdown report (PR comments) |
+| `--json-output PATH` | Write machine-readable JSON report |
+
+### Environment variables
+
+- `COMFYUI_REPO_PATH` — local ComfyUI checkout for `--static-scan`
+- `COMFYUI_OBJECT_INFO_URL` — override live `/object_info` URL
+
+See [`.env.example`](../.env.example).
+
+### Layout
+
+| File | Role |
+|------|------|
+| `comfyui_node_compat/check.py` | CLI entry point |
+| `comfyui_node_compat/models.py` | Issue types, priority tiers |
+| `comfyui_node_compat/registry.py` | Parse live `/object_info` |
+| `comfyui_node_compat/static_registry.py` | AST scan of ComfyUI `.py` sources |
+| `comfyui_node_compat/workflow.py` | Scan template JSON + subgraphs |
+| `comfyui_node_compat/report.py` | Log/Markdown formatting |
+| `comfyui_node_compat/clone.py` | Clone/resolve ComfyUI checkout |

scripts/comfyui_node_compat/__init__.py

@@ -0,0 +1 @@
+"""ComfyUI workflow template node compatibility checks."""