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

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

    ```javascript
    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`:

```bash
DEBUG=true
```

Or any of:

```bash
DEBUG=1
DEBUG=yes
DEBUG=True
DEBUG=YES
```

### Disable Debug Mode

In `.env`:

```bash
DEBUG=false
```

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

## Testing

1. **Verify Config Endpoint**:

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

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

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