sammykumar-ComfyUI-SwissArmyKnife/CONTRIBUTING.md

Contributing to ComfyUI-SwissArmyKnife

Welcome to ComfyUI-SwissArmyKnife! This document provides guidelines for contributors and the Copilot coding agent.

Development Environment Setup

Dev Container (Recommended)

The easiest way to get started is using the provided dev container with GPU support:

1. Prerequisites:

   • Docker with NVIDIA GPU support
   • VS Code with Dev Containers extension
   • NVIDIA GPU drivers

2. Quick Start:

   # Open in VS Code and use "Reopen in Container"
   # OR run directly with Docker:
   docker run --gpus all -v $(pwd):/workspaces/repo -p 8188:8188 mmartial/comfyui-nvidia-docker:ubuntu24_cuda12.8-latest
   

3. Start ComfyUI:

   ./.devcontainer/run-comfy.sh
   # ComfyUI will be available at http://localhost:8188
   

Manual Setup

If you prefer to set up locally:

1. Install Python dependencies:

   pip install -e .
   pip install ruff black mypy pytest opencv-python pillow
   

2. Install JavaScript tooling:

   cd web
   npm install
   

3. Install FFmpeg:

   # Ubuntu/Debian
   sudo apt-get install ffmpeg
   
   # macOS
   brew install ffmpeg
   

Development Workflow

Python Backend Development

The backend nodes are located in nodes/:

• nodes/nodes.py - Main Gemini AI integration nodes
• nodes/helper_nodes.py - Helper/utility nodes
• nodes/lora_manager/ - LoRA Manager (forked from nd-super-nodes)

Development commands:

# Lint Python code
ruff check .
ruff check --fix .  # Auto-fix issues

# Format Python code
black .

# Type checking
mypy .

# Run tests
pytest

# Test imports work
python -c "from nodes.nodes import NODE_CLASS_MAPPINGS; print('Nodes:', list(NODE_CLASS_MAPPINGS.keys()))"

JavaScript Web Extension Development

The web extension consists of plain JavaScript widgets in web/:

• web/js/gemini_widgets.js - Main widget implementation
• web/css/gemini_widgets.css - Widget styling

No build step required - files are loaded directly by ComfyUI.

Development commands:

cd web

# Lint JavaScript
npm run lint
npm run lint:fix  # Auto-fix issues

# Format code
npm run format

# Test (Playwright tests)
cd tests
npm test

Important: After making changes to JavaScript files, refresh the browser cache in ComfyUI to see changes.

Pre-commit Hooks

This project uses pre-commit hooks to maintain code quality:

# Install hooks
pre-commit install

# Run manually
pre-commit run --all-files

# Skip hooks (for testing)
git commit --no-verify

Testing

Python Testing

pytest  # Run all Python tests

JavaScript Testing

cd web/tests
npm test  # Run Playwright tests against hosted ComfyUI

Note: JavaScript tests require a running ComfyUI server with the custom node installed.

Code Style Guidelines

Python

• Use ruff for linting (configured in pyproject.toml)
• Use black for formatting
• Follow type hints with mypy
• Maximum line length: 140 characters

JavaScript

• Use ESLint for linting
• Use Prettier for formatting
• Follow ComfyUI widget conventions
• No build step - plain JavaScript files

Project Structure

comfyui_swissarmyknife/
├── .devcontainer/          # Dev container configuration
│   ├── devcontainer.json   # Main dev container config
│   ├── postCreate.sh       # Setup script
│   └── run-comfy.sh        # ComfyUI start script
├── nodes/                  # Python backend nodes
│   ├── nodes.py           # Main Gemini AI nodes
│   ├── helper_nodes.py    # Helper nodes
│   └── lora_manager/      # LoRA Manager (forked from nd-super-nodes)
│       ├── __init__.py
│       ├── nd_super_lora_node.py
│       ├── lora_utils.py
│       ├── civitai_service.py
│       ├── template_manager.py
│       ├── web_api.py
│       ├── file_api.py
│       └── version_utils.py
├── web/                   # JavaScript web extension
│   ├── js/                # Widget JavaScript files
│   │   └── lora_manager/  # LoRA Manager web extension
│   ├── css/               # Widget CSS files
│   │   └── lora_manager/  # LoRA Manager styles
│   ├── tests/             # Playwright tests
│   └── package.json       # Node.js dependencies
├── docs/                  # Project documentation
│   └── LORA_MANAGER_INTEGRATION.md  # LoRA Manager docs
├── __init__.py            # ComfyUI entry point
├── pyproject.toml         # Python project configuration
└── README.md              # Project documentation

ComfyUI Integration

Backend Nodes

• Exported via NODE_CLASS_MAPPINGS and NODE_DISPLAY_NAME_MAPPINGS in __init__.py
• Require ComfyUI server restart after changes

Web Extension

• Loaded via WEB_DIRECTORY = "./web" in __init__.py
• Changes require browser cache refresh only

CI/CD

Continuous Integration

• Automated linting and testing via GitHub Actions
• No GPU required for CI - only static analysis
• Runs on Python and JavaScript code changes

Publishing

• Automatic publishing to ComfyUI Registry via GitHub Actions
• Triggered by pyproject.toml version updates
• Requires REGISTRY_ACCESS_TOKEN secret

Common Tasks

Adding a New Python Node

1. Add node class to nodes/nodes.py or nodes/helper_nodes.py
2. Export in NODE_CLASS_MAPPINGS
3. Add tests in tests/ directory
4. Update documentation

Adding JavaScript Widgets

1. Add widget code to web/js/
2. Add styling to web/css/
3. Register with ComfyUI using app.registerExtension()
4. Test with browser refresh

Working with LoRA Manager

The LoRA Manager is a forked sub-module from nd-super-nodes. See docs/LORA_MANAGER_INTEGRATION.md for detailed information.

Key files:

• Backend: nodes/lora_manager/*.py
• Frontend: web/js/lora_manager/extension.js
• Styles: web/css/lora_manager/style.css

Testing lora_manager:

# Test imports
python -c "from nodes.lora_manager import NODE_CLASS_MAPPINGS; print('LoRA Manager nodes:', list(NODE_CLASS_MAPPINGS.keys()))"

# With ComfyUI running, check console for:
# "Swiss Army Knife LoRA Manager: API routes registered"

Running Local Tests

# Python
python -c "from nodes.nodes import NODE_CLASS_MAPPINGS; print('Available nodes:', list(NODE_CLASS_MAPPINGS.keys()))"
ruff check .
pytest

# JavaScript
cd web
npm run lint
cd tests && npm test  # Requires running ComfyUI server

Copilot Coding Agent Guidelines

For the GitHub Copilot coding agent working on this repository:

Safe Commands to Run

# Linting (fast, safe)
ruff check .
ruff check --fix .

# Testing imports (fast)
python -c "from nodes.nodes import NODE_CLASS_MAPPINGS; print(list(NODE_CLASS_MAPPINGS.keys()))"

# JavaScript linting
cd web && npm run lint

# Run tests
pytest
cd web/tests && npm test

Expected Timeouts

• ruff check .: < 1 second
• pip install -e .: ~12 seconds
• pip install opencv-python: 2-3 minutes (large downloads)
• npm install: ~40 seconds
• pytest: < 30 seconds

Key Development Points

• Backend changes require ComfyUI server restart
• Web extension changes require browser cache refresh only
• JavaScript widgets are plain JS files (no build step)
• Focus on minimal, surgical changes
• Use pre-commit hooks to maintain quality

Getting Help

• Check existing issues on GitHub
• Review ComfyUI custom node documentation: https://docs.comfy.org/custom-nodes/overview
• Check the project's implementation status in IMPLEMENTATION_STATUS.md

License

This project is licensed under the GNU General Public License v3. See LICENSE for details.