docs/infrastructure/debug/DEBUG_MODE_IMPLEMENTATION.md

DEBUG Mode Implementation

Overview

The Swiss Army Knife extension now respects the DEBUG environment variable setting from .env to control console logging in the browser JavaScript.

How It Works

Backend (Python)

1. Config API Endpoint (nodes/config_api.py):

   • Exposes a /swissarmyknife/config endpoint
   • Reads DEBUG environment variable from .env
   • Returns JSON with debug boolean flag
   • Registered in __init__.py at extension load time

2. Environment Variable Reading:

   debug = os.environ.get("DEBUG", "false").lower() in ("true", "1", "yes")
   

   • Supports: true, 1, yes (case-insensitive) for enabling debug mode
   • Defaults to false if not set

Frontend (JavaScript)

1. Debug Configuration Loading (web/js/swiss-army-knife.js):

   • Fetches debug setting from /swissarmyknife/config on extension load
   • Stores in DEBUG_ENABLED flag
   • Logs debug mode status to console

2. Conditional Logging Wrapper:

   const debugLog = (...args) => {
       if (DEBUG_ENABLED) {
           console.log(...args);
       }
   };
   

3. Log Classification:

   • Debug logs (controlled by DEBUG flag):
     • debugLog() - Implementation details, state tracking, diagnostic info
     • All [DEBUG], [SERIALIZE], [CONFIGURE], [LOADED], [API] tagged messages
   • Always-visible logs (not controlled by DEBUG flag):
     • console.log() - User-facing messages, version info
     • console.warn() - Warnings
     • console.error() - Errors
     • Extension loading message
     • Debug mode status message

Configuration

Enable Debug Mode

In .env:

DEBUG=true

Or any of:

DEBUG=1
DEBUG=yes
DEBUG=True
DEBUG=YES

Disable Debug Mode

In .env:

DEBUG=false

Or simply omit the DEBUG setting entirely (defaults to false).

Testing

1. Verify Config Endpoint:

   curl http://localhost:8188/swissarmyknife/config
   

   Should return: {"debug": true} or {"debug": false}

2. Test Debug Mode Enabled:

   • Set DEBUG=true in .env
   • Restart ComfyUI server
   • Refresh browser
   • Open browser console
   • Should see: "Swiss Army Knife Debug Mode: ENABLED"
   • Should see debug logs with [DEBUG] tags

3. Test Debug Mode Disabled:

   • Set DEBUG=false in .env
   • Restart ComfyUI server
   • Refresh browser
   • Open browser console
   • Should see: "Swiss Army Knife Debug Mode: DISABLED"
   • Should NOT see debug logs with [DEBUG] tags

Implementation Details

Files Modified

1. __init__.py:

   • Added config API route registration
   • Added DEBUG to exports

2. nodes/config_api.py (new file):

   • Created config API endpoint
   • Reads DEBUG from environment

3. web/js/swiss-army-knife.js:

   • Added loadDebugConfig() async function
   • Added debugLog() wrapper function
   • Replaced ~50+ console.log() calls with debugLog() for debug-level messages
   • Kept user-facing logs as console.log()

Logging Categories Changed to debugLog()

• Node registration messages
• Widget state serialization/deserialization
• File upload handlers
• Workflow loading
• API event processing
• Dimensions display updates
• Media widget management
• LoRA info extraction

Logging Categories Kept as console.log()

• Extension version and load timestamp
• Debug mode status (enabled/disabled)
• Development utility functions
• Version update notifications
• Cache control messages
• User-facing warnings and errors

Benefits

1. Cleaner Console: Users can disable debug logs for cleaner console output in production
2. Debugging: Developers can enable detailed logging when troubleshooting
3. Centralized Control: Single environment variable controls all debug logging
4. No Code Changes: Toggle debug mode without modifying code
5. Server Restart: Changes to DEBUG setting require server restart (not just browser refresh)

Future Enhancements

Potential improvements:

• Add different log levels (DEBUG, INFO, WARN, ERROR)
• Add per-node debug control
• Add runtime debug toggle (no server restart needed)
• Add debug log filtering by category
• Add debug log export functionality

Final Statistics

After complete implementation:

• Total debugLog calls: 167 (converted from console.log)
• Remaining console.log calls: 15 (all user-facing or system-required)
  • 1 inside debugLog function itself (required)
  • 2 user-facing status messages (debug mode, extension loading)
  • 2 error/status messages (filename preview error, video preview status)
  • 10 development utility messages (cache busting, localhost only)
• Conversion rate: ~92% of logging now respects DEBUG flag

Log Categories Converted to debugLog

All these message types now respect the DEBUG environment variable:

• [DEBUG] - Implementation details and diagnostics
• [STATE] - Widget state management
• [WIDGET] - Widget operations
• [CONFIGURE] - Configuration and restoration
• [SERIALIZE] - Workflow serialization
• [LOADED] - Workflow loading
• [UPLOAD] - File upload operations
• [API] - API event handling
• [MediaDescribe] - Media description node diagnostics
• Widget discovery and manipulation
• File restoration and state management
• Dimensions display updates

User-Facing Messages (Always Visible)

These messages always appear regardless of DEBUG setting:

• Extension version and load timestamp
• Debug mode status (ENABLED/DISABLED)
• Development utilities info (localhost only)
• Critical error messages
• Cache clearing confirmations

Troubleshooting

"Still seeing debug logs after setting DEBUG=false"

1. Verify .env file:

   cat /Users/samkumar/Development/dev-lab-hq/ai-image-hub/apps/comfyui-swiss-army-knife/.env | grep DEBUG
   

   Should show: DEBUG=false

2. Test config API:

   curl http://127.0.0.1:8188/swissarmyknife/config
   

   Should return: {"debug": false}

   If it returns {"debug": true}, the .env file isn't being read correctly.

3. Clear ALL caches:

   • Stop ComfyUI server completely
   • Clear browser cache (hard refresh: Cmd+Shift+R / Ctrl+Shift+F5)
   • In browser console, run: localStorage.clear(); sessionStorage.clear()
   • Or use the built-in utility: clearSwissArmyKnifeCache()
   • Restart ComfyUI server
   • Reload page

4. Check for cached JavaScript:

   • Browser may have cached the old swiss-army-knife.js
   • Force cache bypass: Disable browser cache in DevTools Network tab
   • Or increment EXTENSION_VERSION in swiss-army-knife.js to force reload

5. Verify server restart:

   • Ensure you fully restarted the ComfyUI server (not just refreshed browser)
   • Environment variables are only read at server startup

"Debug mode status shows DISABLED but still see logs from other extensions"

The DEBUG flag only controls Swiss Army Knife logs. Other extensions (Node Enhancer, Super LoRA Loader, etc.) have their own logging that isn't affected by this setting.

Logs from other extensions will show different formats:

• extension.js:6753 NodeEnhancer: Registering extension...
• extension.js:6891 Super LoRA Loader: Registering extension...

These are separate extensions and not controlled by Swiss Army Knife's DEBUG setting.

Final Statistics

After complete implementation:

• Total debugLog calls: 167 (converted from console.log)
• Remaining console.log calls: 15 (all user-facing or system-required)
• Conversion rate: ~92% of logging now respects DEBUG flag

User-Facing Messages (Always Visible)

These messages always appear regardless of DEBUG setting:

• Extension version and load timestamp
• Debug mode status (ENABLED/DISABLED)
• Development utilities info (localhost only)
• Critical error messages

Troubleshooting

"Still seeing debug logs after setting DEBUG=false"

The logs you're seeing are from other extensions (Node Enhancer, Super LoRA Loader). Swiss Army Knife debug logs will have tags like [DEBUG], [STATE], [WIDGET], etc.

Verification steps:

1. Check browser console shows: "Swiss Army Knife Debug Mode: DISABLED"
2. Verify no messages with [DEBUG], [STATE], [WIDGET] tags appear
3. Other extensions' logs (extension.js:XXXX) are normal and unrelated

If Swiss Army Knife debug logs still appear:

1. Verify .env has DEBUG=false
2. Fully restart ComfyUI server (environment variables load at startup)
3. Hard refresh browser (Cmd+Shift+R / Ctrl+Shift+F5)
4. Clear browser cache: clearSwissArmyKnifeCache() in console