sammykumar-ComfyUI-SwissArmyKnife/AGENTS.md

ComfyUI-SwissArmyKnife - ComfyUI Extension Development Guide

ALWAYS reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here.

Official ComfyUI Documentation

For technical implementation details, reference these official ComfyUI custom node development guides:

• Backend (Python) Development: https://docs.comfy.org/custom-nodes/backend/server_overview
• Web Extension (JavaScript) Development: https://docs.comfy.org/custom-nodes/js/javascript_overview
• Lite Graph (ComfyUi is built on top of Lite Graph):https://github.com/jagenjo/litegraph.js/tree/master

Note: These are the official JavaScript widget docs, not React-based extensions.

Project Overview

ComfyUI-SwissArmyKnife is a ComfyUI extension that consists of two essential components that work together:

Backend (Python Custom Nodes)

• Python custom nodes in nodes/*.py for Gemini AI video analysis and processing
• Core business logic and AI integration
• Requires ComfyUI server restart when modified

CRITICAL: Auto-Restart Development Server After Python Changes

After modifying ANY Python files in this repository (.py files in nodes/, __init__.py, etc.), you MUST automatically restart the development ComfyUI server:

# Run this command after ANY Python file modification
cd /mnt/nfs_share/gen-ai-image/comfyui-containers && docker compose restart dev-comfyui

When to restart:

• After editing Python node files in nodes/
• After modifying __init__.py or any Python configuration
• After installing new Python packages with pip
• After any Python code change that needs to take effect

Example workflow:

1. Edit Python file (e.g., nodes/media_describe/llm_studio_structured.py)
2. Verify syntax with ruff check .
3. Immediately restart server: cd /mnt/nfs_share/gen-ai-image/comfyui-containers && docker compose restart dev-comfyui
4. Wait for server to restart (~5-10 seconds)
5. Test changes in ComfyUI web interface

Web Extension (JavaScript Widgets)

• Plain JavaScript widgets in ./web/js/ for enhanced ComfyUI interaction
• UI components and client-side functionality
• Requires browser cache refresh when modified
• Chrome DevTools MCP Tool (Required for UI changes): Whenever you work on anything that touches the ComfyUI browser experience or files under web/, spin up the Chrome DevTools MCP tool and inspect DOM/layout changes through it instead of guessing from memory. Use it to capture screenshots, review network logs, and confirm widget wiring before writing or modifying code. Treat any UI-oriented task (CSS tweaks, widget bugs, layout fixes) as blocked until you have gathered evidence via the dev tools call.

Additional Components

• React/TypeScript UI extension with internationalization DISABLED FOR NOW
• GitHub Actions for automated building and publishing
• Playwright tests in ./web/tests/ for testing against hosted ComfyUI server
• Documentation in dev-docs/ directory - organized into categorized folders (see Documentation Organization section)

IMPORTANT: Both backend and web extension components are required for the custom node to function properly. Changes to backend Python files require restarting the ComfyUI server, while changes to web JavaScript files require refreshing the browser cache.

DOCUMENTATION REQUIREMENT: The project maintains TWO distinct documentation systems with different audiences:

1. Developer Documentation (dev-docs/) - Technical implementation details for contributors
2. User Help Pages (web/docs/) - End-user reference displayed in ComfyUI UI

Never document directly in code comments when a separate documentation file would be more appropriate. Always attempt to update documentation for existing markdown files before creating new ones.

Note: The React UI component (ui-react_backup/) is currently disabled and not in active development.

Documentation Organization

The project maintains TWO distinct documentation layers with different audiences:

1. Developer Documentation (dev-docs/)

Audience: Internal developers and contributors
Purpose: Technical implementation details, architecture decisions, troubleshooting guides

dev-docs/
├── README.md                    # Developer documentation index
│
├── nodes/                       # Node-specific documentation (ONE file per node)
│   ├── lm-studio-describe/     # LM Studio structured describe nodes
│   ├── reddit-media/           # Reddit Media Extraction
│   ├── media-selection/        # Media Selection node
│   └── control-panel/          # Control Panel Display
│
├── infrastructure/              # Infrastructure & system components
│   ├── caching/                # Caching system
│   ├── debug/                  # Debug & logging
│   ├── docker/                 # Docker setup
│   └── build-deploy/           # Build & deployment
│
├── integrations/                # External service integrations
│   ├── civitai/                # CivitAI API integration
│   └── reddit/                 # Reddit API integration
│
├── web-js/                      # Web JavaScript widget documentation
├── examples/                    # Example workflows
└── comfyui/                     # ComfyUI-specific documentation
    └── custom-nodes_documentation_guidelines.md

2. User-Facing Help Pages (web/docs/)

Audience: End users who install and use your nodes in ComfyUI workflows
Purpose: In-UI reference documentation displayed in ComfyUI's help panel

For complete ComfyUI help page guidelines, see: dev-docs/comfyui/custom-nodes_documentation_guidelines.md

web/
└── docs/
    ├── NodeName.md        # Default help page (required for each registered node)
    └── NodeName/          # Optional: Multi-language support
        ├── en.md
        └── zh.md

Documentation Rules

Two-tier documentation system:

Layer 1: Developer Documentation (dev-docs/) - Technical implementation details

1. Node-specific docs → dev-docs/nodes/[node-name]/ - ONE comprehensive file per node
2. Infrastructure docs → dev-docs/infrastructure/[category]/
3. Integration docs → dev-docs/integrations/[service]/
4. Web JavaScript widget docs → dev-docs/web-js/
5. Examples → dev-docs/examples/

Layer 2: User Help Pages (web/docs/) - MANDATORY for all registered nodes 6. ComfyUI help pages → every registered node must have a matching help markdown file inside web/docs/. The filename must match the node key from NODE_CLASS_MAPPINGS (e.g., web/docs/VACEScribbleAnnotator.md). Use the help page template described at https://docs.comfy.org/custom-nodes/help_page and keep its content in sync with the canonical node doc under dev-docs/nodes/....

ComfyUI Help Page Structure

web/
└── docs/
    ├── NodeName.md        # Default help page loaded in ComfyUI
    ├── NodeName/en.md     # (Optional) locale-specific overrides
    └── NodeName/zh.md

• At minimum provide headings for Summary, Inputs, Outputs, Usage Tips, and link back to the full documentation under dev-docs/.
• If you update a node’s behavior, update both the canonical doc (dev-docs/nodes/...) and the corresponding web/docs/NodeName.md help file in the same PR.

Finding Documentation

For Developers:

• Start here: dev-docs/README.md - Technical documentation index
• Category indexes: Each folder has a README.md listing all files
• By node: dev-docs/nodes/[node-name]/README.md for quick reference
• Complete node docs: dev-docs/nodes/[node-name]/[NODE_NAME].md for comprehensive documentation
• By topic: Browse appropriate category folder

For End Users:

• In ComfyUI: Right-click node → View Help (displays web/docs/NodeName.md)
• Fallback: Browse web/docs/NodeName.md files for concise user documentation

Working Effectively

Virtual Environment Activation

CRITICAL: Always activate the virtual environment before running any Python commands:

# Activate virtual environment (REQUIRED for all Python operations)
source /Users/samkumar/Development/dev-lab-hq/ai-image-hub/apps/comfyui-swiss-army-knife/.venv/bin/activate

# Or use relative path if in project root:
source .venv/bin/activate

# Verify activation (you should see (.venv) in your prompt)
which python3  # Should show path inside .venv directory

IMPORTANT: Run the activation command before:

• Installing Python packages (pip3 install)
• Running Python scripts or commands
• Running tests (pytest)
• Linting Python code (ruff check)
• Any other Python-related terminal operations

Essential System Dependencies

Install these system dependencies first:

# FFmpeg is REQUIRED for video processing functionality
sudo apt-get update && sudo apt-get install -y ffmpeg

# Verify installation
ffmpeg -version  # Should show version 6.1.1 or newer

Bootstrap React UI Development (DISABLED)

⚠️ The React UI component is currently disabled and not in active development.

# THESE COMMANDS ARE CURRENTLY DISABLED
# Navigate to React UI directory
# cd ui-react_backup/ui

# Install Node.js dependencies - takes ~40 seconds
# npm install  # NEVER CANCEL: Takes 40 seconds. Set timeout to 60+ seconds.

# Build React extension - takes ~5 seconds
# npm run build  # NEVER CANCEL: Takes 5 seconds. Set timeout to 30+ seconds.

Bootstrap Python Development

# ALWAYS activate virtual environment first
source .venv/bin/activate

# Install Python package and dependencies
pip3 install -e .  # Takes ~12 seconds for basic dependencies

# Install essential Python dependencies for full functionality
# NEVER CANCEL: Takes 2-3 minutes for torch/opencv. Set timeout to 300+ seconds.
pip3 install torch opencv-python

# Install development tools
pip3 install pytest mypy coverage ruff pre-commit

# Verify Python modules work
python3 -c "from nodes.nodes import NODE_CLASS_MAPPINGS; print('Available nodes:', list(NODE_CLASS_MAPPINGS.keys()))"
# Should output: Available nodes: ['GeminiUtilVideoDescribe']

Development Workflows

Documentation Workflow

When modifying a node, you MUST update BOTH documentation layers:

1. Technical documentation (dev-docs/) - Implementation details, architecture
2. User help page (web/docs/) - User-facing parameters, usage

# Example workflow for modifying a node
vim nodes/media_selection/media_selection.py    # Edit node implementation

# Update technical documentation
vim dev-docs/nodes/media-selection/MEDIA_SELECTION.md

# Update user help page
vim web/docs/MediaSelection.md

# Commit both together
git add nodes/media_selection/ dev-docs/nodes/media-selection/ web/docs/MediaSelection.md
git commit -m "feat: Add duration_threshold parameter to MediaSelection

- Added duration_threshold parameter
- Updated technical docs with implementation details
- Updated help page with user-facing parameter description"

Developer documentation structure:

dev-docs/
├── README.md                    # Developer documentation index
├── nodes/                       # Node-specific documentation (ONE file per node)
│   ├── lm-studio-describe/     # LM Studio structured describe docs
│   ├── reddit-media/           # Reddit Media Extraction docs
│   ├── media-selection/        # Media Selection node docs
│   └── control-panel/          # Control Panel Display docs
├── infrastructure/              # Infrastructure components
│   ├── caching/                # Caching system docs
│   ├── debug/                  # Debug & logging docs
│   ├── docker/                 # Docker setup docs
│   └── build-deploy/           # Build & deployment docs
├── integrations/                # External service integrations
│   ├── civitai/                # CivitAI API integration docs
│   └── reddit/                 # Reddit API integration docs
├── web-js/                      # Web JavaScript widget documentation
└── examples/                    # Example workflows

Adding New Documentation:

# For new nodes - create BOTH documentation layers
# 1. Technical documentation (developer-focused)
mkdir -p dev-docs/nodes/[node-name]
touch dev-docs/nodes/[node-name]/README.md
touch dev-docs/nodes/[node-name]/[NODE_NAME].md

# 2. User help page (MANDATORY - must match NODE_CLASS_MAPPINGS key)
touch web/docs/NodeName.md

# Update existing node documentation
vim dev-docs/nodes/[node-name]/[NODE_NAME].md
vim web/docs/NodeName.md

# For infrastructure documentation
touch dev-docs/infrastructure/[category]/NEW_SYSTEM.md

# For web JavaScript widgets
touch dev-docs/web-js/NEW_WIDGET.md

# For integrations
touch dev-docs/integrations/[service]/NEW_INTEGRATION.md

Documentation file naming convention:

Developer docs (dev-docs/):

• Nodes: Use descriptive all-caps names: MEDIA_SELECTION.md, MEDIA_DESCRIBE.md
• ONE file per node: Consolidate all information about a node into a single comprehensive file
• Node docs go in dev-docs/nodes/[node-name]/
• Infrastructure docs go in dev-docs/infrastructure/[category]/
• Web JavaScript widget docs go in dev-docs/web-js/

User help pages (web/docs/):

• MUST match NODE_CLASS_MAPPINGS key exactly (case-sensitive)
• Example: NODE_CLASS_MAPPINGS = {"MediaSelection": ...} → web/docs/MediaSelection.md

CRITICAL: Whenever you implement a new feature, fix a bug, or solve a technical problem:

1. Identify the correct documentation layer(s):

   • Node changes → Update BOTH layers:
     • dev-docs/nodes/[node-name]/[NODE_NAME].md (technical)
     • web/docs/NodeName.md (user help - see dev-docs/comfyui/custom-nodes_documentation_guidelines.md for guidelines)
   • System changes → dev-docs/infrastructure/[category]/
   • Widget changes → dev-docs/web-js/
   • Integration work → dev-docs/integrations/[service]/

2. For nodes:

   • Update the existing comprehensive file in dev-docs/ or create one if it doesn't exist
   • Update or create the matching help page in web/docs/ (refer to dev-docs/comfyui/custom-nodes_documentation_guidelines.md)
   • Ensure filename in web/docs/ matches NODE_CLASS_MAPPINGS key exactly

3. For other components: Create or update documentation with descriptive names

4. Include implementation details, gotchas, and future considerations in dev-docs/

5. Update the folder's README.md index if needed

6. Reference both documentation files in commit messages

7. Cross-reference:

   • Link from help page to technical docs: See ../../dev-docs/nodes/...
   • Link related documentation in other folders

React UI Development (DISABLED)

⚠️ The React UI component is currently disabled and not in active development.

# THESE COMMANDS ARE CURRENTLY DISABLED
# cd ui-react_backup/ui

# Development with auto-reload (watches for changes)
# npm run watch

# Build for production
# npm run build  # NEVER CANCEL: Takes 5 seconds. Set timeout to 30+ seconds.

# TypeScript type checking
# npm run typecheck

Backend (Python) Development

# ALWAYS activate virtual environment first
source .venv/bin/activate

# Import and test Python nodes
python3 -c "from nodes.nodes import NODE_CLASS_MAPPINGS; print(list(NODE_CLASS_MAPPINGS.keys()))"

# Run Python linting (fast, < 1 second)
ruff check .

# Fix auto-fixable linting issues
ruff check --fix .

# CRITICAL: After ANY Python file modification, restart the dev server
cd /mnt/nfs_share/gen-ai-image/comfyui-containers && docker compose restart dev-comfyui

Web Extension (JavaScript) Development

Chrome DevTools MCP requirement: UI bugs or enhancements must start with a Chrome DevTools MCP call. Launch the tool, capture screenshots/DOM details, and confirm widget behavior before editing anything under web/. Repeat after code changes to validate the actual ComfyUI UI instead of guessing.

# JavaScript widgets are located in ./web/js/
# No build step required - plain JavaScript files

# Verify web extension files exist
ls -la web/js/gemini_widgets.js
ls -la web/css/gemini_widgets.css

# After making changes to JavaScript widgets:
# 1. No compilation needed (plain JS)
# 2. Browser cache refresh required for changes to take effect

Testing

Backend (Python) Testing

# ALWAYS activate virtual environment first
source .venv/bin/activate

# Run pytest (currently no tests exist)
pytest  # NEVER CANCEL: Takes < 30 seconds. Set timeout to 60+ seconds.
# Expected: "no tests ran" - this is normal, no tests exist yet

# When adding tests, create them in a tests/ directory

Web Extension Testing

# Playwright tests for testing against hosted ComfyUI server
cd web/tests/

# Install Playwright dependencies (if not already installed)
npm install

# Run Playwright tests against hosted ComfyUI server
npm test

# Note: Tests require a running ComfyUI server with the custom node installed

React UI Testing (DISABLED)

⚠️ The React UI component is currently disabled and not in active development.

# THESE COMMANDS ARE CURRENTLY DISABLED
# cd ui-react_backup/ui

# This command WILL FAIL with ES module errors
# npm test
# Error: "Jest encountered an unexpected token" - this is a known issue

# To add working tests, fix jest.config.js ES module configuration first

Linting and Code Quality

Python Linting (Works)

# ALWAYS activate virtual environment first
source .venv/bin/activate

# Fast linting check (< 1 second)
ruff check .

# Fix automatically fixable issues
ruff check --fix .

# Note: Some unused import warnings are expected and can be ignored
# The code functions correctly despite these warnings

React UI Linting (DISABLED)

⚠️ The React UI component is currently disabled and not in active development.

# THESE COMMANDS ARE CURRENTLY DISABLED
# cd ui-react_backup/ui

# This will show configuration errors but runs
# npm run lint  # Shows ESLint TypeScript project configuration issues

# Auto-fix formatting issues
# npm run lint:fix

# Format code
# npm run format

Build and Publish Workflow

Local Build Process (DISABLED)

⚠️ The React UI component is currently disabled and not in active development.

# THESE COMMANDS ARE CURRENTLY DISABLED
# Complete build from scratch
# cd ui-react_backup/ui
# npm install  # 40 seconds
# npm run build  # 5 seconds

# Verify built files exist
# ls -la ../dist/example_ext/  # Should show main.js, main.css, etc.

GitHub Actions Publishing

The repository includes automated publishing via .github/workflows/react-build.yml:

• Triggers on pyproject.toml changes pushed to main branch
• Requires REGISTRY_ACCESS_TOKEN secret in repository settings
• Automatically builds React UI and publishes to ComfyUI Registry

pyproject.toml Specifications

Reference: https://docs.comfy.org/registry/specifications

The pyproject.toml file contains two main sections for ComfyUI custom nodes: [project] and [tool.comfy].

[project] Section

name (required)

The node id uniquely identifies the custom node and will be used in URLs from the registry. Users can install the node by referencing this name:

comfy node install <node-id>

Requirements:

• Must be less than 100 characters
• Can only contain alphanumeric characters, hyphens, underscores, and periods
• Cannot have consecutive special characters
• Cannot start with a number or special character
• Case-insensitive comparison

Best Practices:

• Use a short, descriptive name
• Don't include "ComfyUI" in the name
• Make it memorable and easy to type

Examples:

name = "image-processor"      # ✅ Good: Simple and clear
name = "super-resolution"     # ✅ Good: Describes functionality
name = "ComfyUI-enhancer"    # ❌ Bad: Includes ComfyUI
name = "123-tool"            # ❌ Bad: Starts with number

version (required)

Uses semantic versioning with a three-digit version number X.Y.Z:

• X (MAJOR): Breaking changes
• Y (MINOR): New features (backwards compatible)
• Z (PATCH): Bug fixes

Examples:

version = "1.0.0"    # Initial release
version = "1.1.0"    # Added new features
version = "1.1.1"    # Bug fix
version = "2.0.0"    # Breaking changes

license (optional)

Specifies the license for your custom node. Can be specified in two ways:

1. File Reference:

license = { file = "LICENSE" }     # ✅ Points to LICENSE file
license = { file = "LICENSE.txt" } # ✅ Points to LICENSE.txt
license = "LICENSE"                # ❌ Incorrect format

2. License Name:

license = { text = "MIT License" }  # ✅ Correct format
license = { text = "Apache-2.0" }   # ✅ Correct format
license = "MIT LICENSE"             # ❌ Incorrect format

Common licenses: MIT, GPL, Apache

description (recommended)

A brief description of what your custom node does.

description = "A super resolution node for enhancing image quality"

repository (required)

Links to the repository:

[project.urls]
Repository = "https://github.com/username/repository"

urls (recommended)

Links to related resources:

[project.urls]
Documentation = "https://github.com/username/repository/wiki"
"Bug Tracker" = "https://github.com/username/repository/issues"

requires-python (recommended)

Specifies the Python versions that your node supports:

requires-python = ">=3.8"        # Python 3.8 or higher
requires-python = ">=3.8,<3.11"  # Python 3.8 up to (but not including) 3.11

Frontend Version Compatibility (optional)

If your node has specific requirements for which ComfyUI frontend versions it supports, you can specify this using the comfyui-frontend-package dependency. This package is published on PyPI.

Use this field when:

• Your custom node uses frontend APIs that were introduced in a specific version
• You've identified incompatibilities between your node and certain frontend versions
• Your node requires specific UI features only available in newer frontend versions

[project]
dependencies = [
    "comfyui-frontend-package>=1.20.0"       # Requires frontend 1.20.0 or newer
    "comfyui-frontend-package<=1.21.6"       # Restricts to frontend versions up to 1.21.6
    "comfyui-frontend-package>=1.19,<1.22"   # Works with frontend 1.19 to 1.21.x
    "comfyui-frontend-package~=1.20.0"       # Compatible with 1.20.x but not 1.21.0
    "comfyui-frontend-package!=1.21.3"       # Works with any version except 1.21.3
]

classifiers (recommended)

Use classifiers to specify operating system compatibility and GPU accelerators. This information is used to help users find the right node for their system.

[project]
classifiers = [
    # For OS-independent nodes (works on all operating systems)
    "Operating System :: OS Independent",

    # OR for OS-specific nodes, specify the supported systems:
    "Operating System :: Microsoft :: Windows",  # Windows specific
    "Operating System :: POSIX :: Linux",        # Linux specific
    "Operating System :: MacOS",                 # macOS specific

    # GPU Accelerator support
    "Environment :: GPU :: NVIDIA CUDA",    # NVIDIA CUDA support
    "Environment :: GPU :: AMD ROCm",       # AMD ROCm support
    "Environment :: GPU :: Intel Arc",      # Intel Arc support
    "Environment :: NPU :: Huawei Ascend",  # Huawei Ascend support
    "Environment :: GPU :: Apple Metal",    # Apple Metal support
]

[tool.comfy] Section

PublisherId (required)

Your unique publisher identifier, typically matching your GitHub username.

Examples:

PublisherId = "john-doe"        # ✅ Matches GitHub username
PublisherId = "image-wizard"    # ✅ Unique identifier

DisplayName (optional)

A user-friendly name for your custom node.

DisplayName = "Super Resolution Node"

Icon (optional)

URL to your custom node's icon that will be displayed on the ComfyUI Registry and ComfyUI-Manager.

Requirements:

• File types: SVG, PNG, JPG, or GIF
• Maximum resolution: 400px × 400px
• Aspect ratio should be square

Icon = "https://raw.githubusercontent.com/username/repo/main/icon.png"

Banner (optional)

URL to a larger banner image that will be displayed on the ComfyUI Registry and ComfyUI-Manager.

Requirements:

• File types: SVG, PNG, JPG, or GIF
• Aspect ratio: 21:9

Banner = "https://raw.githubusercontent.com/username/repo/main/banner.png"

requires-comfyui (optional)

Specifies which version of ComfyUI your node is compatible with. This helps users ensure they have the correct version of ComfyUI installed.

Supported operators: <, >, <=, >=, ~=, <>, != and ranges

Examples:

requires-comfyui = ">=1.0.0"        # ComfyUI 1.0.0 or higher
requires-comfyui = ">=1.0.0,<2.0.0"  # ComfyUI 1.0.0 up to (but not including) 2.0.0
requires-comfyui = "~=1.0.0"         # Compatible release: version 1.0.0 or newer, but not version 2.0.0
requires-comfyui = "!=1.2.3"         # Any version except 1.2.3
requires-comfyui = ">0.1.3,<1.0.0"   # Greater than 0.1.3 and less than 1.0.0

includes (optional)

Specifies whether to force include certain specific folders. For some situations, such as custom nodes in frontend projects, the final packaged output folder might be included in .gitignore. In such cases, we need to force include it for registry use.

includes = ['dist']

Complete Example

[project]
name = "super-resolution-node"
version = "1.0.0"
description = "Enhance image quality using advanced super resolution techniques"
license = { file = "LICENSE" }
requires-python = ">=3.8"
dependencies = [
    "comfyui-frontend-package<=1.21.6"  # Frontend version compatibility
]
classifiers = [
    "Operating System :: OS Independent"  # Works on all operating systems
]
dynamic = ["dependencies"]

[tool.setuptools.dynamic]
dependencies = {file = ["requirements.txt"]}

[project.urls]
Repository = "https://github.com/username/super-resolution-node"
Documentation = "https://github.com/username/super-resolution-node/wiki"
"Bug Tracker" = "https://github.com/username/super-resolution-node/issues"

[tool.comfy]
PublisherId = "image-wizard"
DisplayName = "Super Resolution Node"
Icon = "https://raw.githubusercontent.com/username/super-resolution-node/main/icon.png"
Banner = "https://raw.githubusercontent.com/username/super-resolution-node/main/banner.png"
requires-comfyui = ">=1.0.0"  # ComfyUI version compatibility

Validation Scenarios

Always validate changes by running these verification steps:

Documentation Validation

# 1. Verify all changes are documented (both layers)
ls -la dev-docs/  # Check for relevant technical documentation
ls -la web/docs/  # Check for user help pages

# 2. Ensure documentation is up-to-date
grep -r "TODO\|FIXME\|OUTDATED" dev-docs/  # Should return no results

# 3. Validate markdown formatting
# (Optional: install markdownlint if available)
# markdownlint dev-docs/*.md web/docs/*.md

# 4. CRITICAL: Verify all registered nodes have help pages
python3 -c "
from nodes.nodes import NODE_CLASS_MAPPINGS
import os

print('\n=== Checking Help Pages for All Registered Nodes ===\n')

missing = []
found = []

for node_name in sorted(NODE_CLASS_MAPPINGS.keys()):
    help_file = f'web/docs/{node_name}.md'
    if not os.path.exists(help_file):
        missing.append(f'❌ Missing: {help_file}')
    else:
        found.append(f'✅ Found: {help_file}')

for item in found:
    print(item)

if missing:
    print('\n=== MISSING HELP PAGES ===\n')
    for item in missing:
        print(item)
    print(f'\n⚠️  {len(missing)} help page(s) missing out of {len(NODE_CLASS_MAPPINGS)} registered nodes')
    exit(1)
else:
    print(f'\n✅ All {len(NODE_CLASS_MAPPINGS)} registered nodes have help pages!')
"

# Example output:
# ✅ Found: web/docs/MediaSelection.md
# ❌ Missing: web/docs/GeminiUtilVideoDescribe.md

Python Node Validation

# ALWAYS activate virtual environment first
source .venv/bin/activate

# 1. Import test
python3 -c "from nodes.nodes import NODE_CLASS_MAPPINGS; print('✓ Python imports work')"

# 2. Linting
ruff check .  # Accept unused import warnings as normal

# 3. Verify system dependencies
ffmpeg -version | head -1  # Should show FFmpeg version

# 4. CRITICAL: Restart dev server after Python modifications
cd /mnt/nfs_share/gen-ai-image/comfyui-containers && docker compose restart dev-comfyui

React UI Validation (DISABLED)

⚠️ The React UI component is currently disabled and not in active development.

# THESE COMMANDS ARE CURRENTLY DISABLED
# cd ui-react_backup/ui

# 1. Build test
# npm run build  # Should complete in ~5 seconds

# 2. Verify outputs
# ls -la ../dist/example_ext/main.js  # Should exist
# ls -la ../dist/locales/  # Should contain en/ and zh/ directories

# 3. TypeScript check
# npm run typecheck  # Should pass without errors

Full Integration Test (PARTIALLY DISABLED)

⚠️ React UI components are disabled, but JavaScript widgets remain active.

# 1. Clean build (DISABLED - React components only)
# cd ui-react_backup/ui
# rm -rf ../dist/
# npm run build

# 2. Verify ComfyUI integration files
# ls -la ../dist/example_ext/  # React build outputs (DISABLED)
ls -la ../../web/js/  # JavaScript widgets (ACTIVE)
ls -la ../../__init__.py  # Python entry point (ACTIVE)

Known Issues and Limitations

Jest Testing Configuration

• Jest tests fail due to ES module configuration issues
• Example test exists in src/__tests__/dummy.test.tsx but won't run
• Fix requires updating jest.config.js and jest.setup.js for ESM support

ESLint Configuration

• ESLint shows TypeScript project configuration warnings
• Code builds and runs correctly despite these warnings
• Focus on functional validation rather than linting perfection

Python Import Warnings

• Ruff reports unused imports in __init__.py files
• These imports are intentional for ComfyUI integration
• The warnings can be safely ignored

System Dependencies

• FFmpeg is required for video processing features
• Without FFmpeg, video-related functionality will fail at runtime
• Always verify FFmpeg is installed in your environment

Common Tasks

Documentation Tasks

# Update node documentation - BOTH layers required
vim dev-docs/nodes/[node-name]/[NODE_NAME].md   # Technical docs
vim web/docs/NodeName.md                         # User help page

# Create new node documentation - BOTH layers
mkdir -p dev-docs/nodes/[node-name]
touch dev-docs/nodes/[node-name]/README.md
touch dev-docs/nodes/[node-name]/[NODE_NAME].md
touch web/docs/NodeName.md                       # MUST match NODE_CLASS_MAPPINGS key

# Document infrastructure changes
touch dev-docs/infrastructure/[category]/SYSTEM_NAME.md

# Document web JavaScript widget
touch dev-docs/web-js/WIDGET_NAME.md

# Search for documentation gaps
grep -r "TODO\|FIXME\|INCOMPLETE" dev-docs/

# Browse documentation by category
ls -la dev-docs/nodes/           # Node-specific docs (ONE file per node)
ls -la dev-docs/infrastructure/  # System/infrastructure docs
ls -la dev-docs/integrations/    # External service integrations
ls -la dev-docs/web-js/          # Web JavaScript widget documentation
ls -la dev-docs/examples/        # Example workflows
ls -la web/docs/                 # User help pages (MANDATORY for all nodes)

# View node documentation
cat dev-docs/nodes/media-selection/MEDIA_SELECTION.md   # Complete technical docs
cat web/docs/MediaSelection.md                         # User help page

# Common documentation patterns:
# Developer docs (dev-docs/):
# - dev-docs/nodes/[node-name]/[NODE_NAME].md - Single comprehensive node documentation
# - dev-docs/nodes/[node-name]/README.md - Quick reference for the node
# - dev-docs/infrastructure/[category]/SYSTEM_NAME.md - Infrastructure documentation
# - dev-docs/integrations/[service]/INTEGRATION_GUIDE.md - Integration guides
# - dev-docs/web-js/WIDGET_NAME.md - Web JavaScript widget documentation
# - dev-docs/comfyui/custom-nodes_documentation_guidelines.md - Help page guidelines
#
# User help pages (web/docs/):
# - web/docs/NodeName.md - User-facing help (MUST match NODE_CLASS_MAPPINGS)

File Structure Overview

comfyui_swissarmyknife/
├── .github/workflows/react-build.yml  # CI/CD automation
├── __init__.py                         # Python entry point
├── pyproject.toml                      # Project metadata & publishing config
│
├── dev-docs/                          # DEVELOPER DOCUMENTATION (Technical)
│   ├── README.md                      # Developer documentation index
│   ├── nodes/                         # Node-specific documentation (ONE file per node)
│   │   ├── lm-studio-describe/       # LM Studio structured describe docs
│   │   ├── reddit-media/             # Reddit Media Extraction docs
│   │   ├── media-selection/          # Media Selection node docs
│   │   └── control-panel/            # Control Panel Display docs
│   ├── infrastructure/                # Infrastructure components
│   │   ├── caching/                  # Caching system docs
│   │   ├── debug/                    # Debug & logging docs
│   │   ├── docker/                   # Docker setup docs
│   │   └── build-deploy/             # Build & deployment docs
│   ├── integrations/                  # External service integrations
│   │   ├── civitai/                  # CivitAI API integration docs
│   │   └── reddit/                   # Reddit API integration docs
│   ├── web-js/                        # Web JavaScript widget documentation
│   ├── examples/                      # Example workflows
│   └── comfyui/                       # ComfyUI-specific documentation
│       └── custom-nodes_documentation_guidelines.md
│
├── nodes/nodes.py                      # Main Python custom nodes
│
├── web/                               # Web extension components
│   ├── js/                            # JavaScript widgets
│   │   ├── gemini_widgets.js         # Gemini widgets
│   │   └── ...
│   ├── css/                           # Stylesheets
│   └── docs/                          # USER HELP PAGES (In-UI reference)
│       ├── MediaSelection.md         # Help page for MediaSelection node
│       ├── ControlPanelPromptBreakdown.md   # Help page for Control Panel output node
│       └── ...                       # (MUST match NODE_CLASS_MAPPINGS keys)
│
└── ui-react_backup/                   # React UI extension (DISABLED)
    ├── ui/src/                        # React source code
    ├── ui/package.json                # Node.js dependencies
    └── dist/                          # Built React outputs

Package Management

# React dependencies
cd ui-react_backup/ui
npm install  # Install from package.json

# Python dependencies (ALWAYS activate venv first)
source .venv/bin/activate
pip3 install -e .  # Install from pyproject.toml
pip3 install torch opencv-python  # Additional ML dependencies

Environment Verification

# Verify tool versions
node --version    # Should be v20.19.4+
npm --version     # Should be 10.8.2+
python3 --version # Should be 3.12.3+
ffmpeg -version   # Should be 6.1.1+

# Verify Python dependencies (activate venv first)
source .venv/bin/activate
which python3     # Should point to .venv/bin/python3
pip3 list | grep -E "(torch|opencv|google-genai)"  # Show Python ML deps

# Verify Node dependencies
npm list --prefix ui-react_backup/ui  # Show React dependencies

Timing Expectations

NEVER CANCEL these operations - they may appear to hang but are working:

• npm install: 40 seconds (normal)
• npm run build: 5 seconds (very fast)
• pip3 install torch opencv-python: 2-3 minutes (downloads large binaries)
• npm run watch: Runs continuously until stopped
• ruff check: < 1 second (very fast)
• pytest: < 30 seconds (but no tests exist currently)

Set appropriate timeouts: 60+ seconds for npm install, 300+ seconds for Python ML dependencies.

Development Tips

• Backend changes: Restart ComfyUI server after modifying Python files in nodes/ using: cd /mnt/nfs_share/gen-ai-image/comfyui-containers && docker compose restart dev-comfyui
• Web extension changes: Refresh browser cache after modifying JavaScript files in web/js/
• JavaScript widgets require no build step (plain JS files)
• Use Playwright tests in web/tests/ to validate functionality against hosted ComfyUI server
• Focus on functional testing since automated tests have configuration issues
• FFmpeg must be available in PATH for video processing features to work