# 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:

```bash
# 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:

```bash
# 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:

```bash
# 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.**

```bash
# 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

```bash
# 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

```bash
# 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:**

```bash
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:**

```bash
# 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.**

```bash
# 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

```bash
# 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.

```bash
# 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

```bash
# 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

```bash
# 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.**

```bash
# 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)

```bash
# 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.**

```bash
# 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.**

```bash
# 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:

```bash
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:**

```toml
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](https://semver.org/) with a three-digit version number X.Y.Z:

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

**Examples:**

```toml
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:**

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

2. **License Name:**

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

Common licenses: [MIT](https://opensource.org/license/mit), [GPL](https://www.gnu.org/licenses/gpl-3.0.en.html), [Apache](https://www.apache.org/licenses/LICENSE-2.0)

#### description (recommended)

A brief description of what your custom node does.

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

#### repository (required)

Links to the repository:

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

#### urls (recommended)

Links to related resources:

```toml
[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:

```toml
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](https://pypi.org/project/comfyui-frontend-package/).

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

```toml
[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.

```toml
[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:**

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

#### DisplayName (optional)

A user-friendly name for your custom node.

```toml
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

```toml
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

```toml
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:**

```toml
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.

```toml
includes = ['dist']
```

### Complete Example

```toml
[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

```bash
# 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

```bash
# 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.**

```bash
# 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.**

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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