ComfyUI-Manager/docs/internal/CNR_VERSION_MANAGEMENT_DESIGN.md

# CNR Version Management Design

**Version**: 1.1
**Date**: 2025-11-08
**Status**: Official Design Policy

## Overview

This document describes the official design policy for CNR (ComfyUI Node Registry) version management in ComfyUI Manager.

## Core Design Principles

### 1. In-Place Upgrade Policy

**Policy**: CNR upgrades are performed as **in-place replacements** without version history preservation.

**Rationale**:
- **Simplicity**: Single version management is easier for users and maintainers
- **Disk Space**: Prevents accumulation of old package versions
- **Clear State**: Users always know which version is active
- **Consistency**: Same behavior for enabled and disabled states

**Behavior**:
```
Before: custom_nodes/PackageName/ (CNR v1.0.1 with .tracking)
Action: Install CNR v1.0.2
After:  custom_nodes/PackageName/ (CNR v1.0.2 with .tracking)
Result: Old v1.0.1 REMOVED (not preserved)
```

### 2. Single CNR Version Policy

**Policy**: Only **ONE CNR version** exists at any given time (either enabled OR disabled, never both).

**Rationale**:
- **State Clarity**: No ambiguity about which CNR version is current
- **Resource Management**: Minimal disk usage
- **User Experience**: Clear version state without confusion
- **Design Consistency**: Uniform handling across operations

**States**:
- **Enabled**: `custom_nodes/PackageName/` (with `.tracking`)
- **Disabled**: `.disabled/packagename@version/` (with `.tracking`)
- **Never**: Multiple CNR versions coexisting

### 3. CNR vs Nightly Differentiation

**Policy**: Different handling for CNR and Nightly packages based on use cases.

| Aspect | CNR Packages (`.tracking`) | Nightly Packages (`.git`) |
|--------|----------------------------|---------------------------|
| **Purpose** | Stable releases | Development versions |
| **Preservation** | Not preserved (in-place upgrade) | Preserved (multiple versions) |
| **Version Policy** | Single version only | Multiple versions allowed |
| **Use Case** | Production use | Testing and development |

**Rationale**:
- **CNR**: Stable releases don't need version history; users want single stable version
- **Nightly**: Development versions benefit from multiple versions for testing

### 4. API Response Priority Rules

**Policy**: The `/v2/customnode/installed` API applies two priority rules to prevent duplicate package entries and ensure clear state representation.

**Rule 1 (Enabled-Priority)**:
- **Policy**: When both enabled and disabled versions of the same package exist → Return ONLY the enabled version
- **Rationale**: Prevents frontend confusion from duplicate package entries
- **Implementation**: `comfyui_manager/glob/manager_core.py:1801` in `get_installed_nodepacks()`

**Rule 2 (CNR-Priority for Disabled Packages)**:
- **Policy**: When both CNR and Nightly versions are disabled → Return ONLY the CNR version
- **Rationale**: CNR versions are stable releases and should be preferred over development Nightly builds when both are inactive
- **Implementation**: `comfyui_manager/glob/manager_core.py:1801` in `get_installed_nodepacks()`

**Priority Matrix**:

| Scenario | Enabled Versions | Disabled Versions | API Response |
|----------|------------------|-------------------|--------------|
| 1. CNR enabled only | CNR v1.0.1 | None | CNR v1.0.1 (`enabled: true`) |
| 2. CNR enabled + Nightly disabled | CNR v1.0.1 | Nightly | **Only CNR v1.0.1** (`enabled: true`) ← Rule 1 |
| 3. Nightly enabled + CNR disabled | Nightly | CNR v1.0.1 | **Only Nightly** (`enabled: true`) ← Rule 1 |
| 4. CNR disabled + Nightly disabled | None | CNR v1.0.1, Nightly | **Only CNR v1.0.1** (`enabled: false`) ← Rule 2 |
| 5. Different packages disabled | None | PackageA, PackageB | Both packages (`enabled: false`) |

**Test Coverage**:
- `tests/glob/test_installed_api_enabled_priority.py`
  - `test_installed_api_shows_only_enabled_when_both_exist` - Verifies Rule 1
  - `test_installed_api_cnr_priority_when_both_disabled` - Verifies Rule 2

## Detailed Behavior Specifications

### CNR Upgrade (Enabled → Enabled)

**Scenario**: Upgrading from CNR v1.0.1 to v1.0.2 when v1.0.1 is enabled

```
Initial State:
  custom_nodes/PackageName/  (CNR v1.0.1 with .tracking)

Action:
  Install CNR v1.0.2

Process:
  1. Download CNR v1.0.2
  2. Remove existing custom_nodes/PackageName/
  3. Install CNR v1.0.2 to custom_nodes/PackageName/
  4. Create .tracking file

Final State:
  custom_nodes/PackageName/  (CNR v1.0.2 with .tracking)

Result:
  ✓ v1.0.2 installed and enabled
  ✓ v1.0.1 completely removed
  ✓ No version history preserved
```

### CNR Switch from Disabled

**Scenario**: Switching from disabled CNR v1.0.1 to CNR v1.0.2

```
Initial State:
  custom_nodes/PackageName/  (Nightly with .git)
  .disabled/packagename@1_0_1/  (CNR v1.0.1 with .tracking)

User Action:
  Install CNR v1.0.2

Process:
  Step 1: Enable disabled CNR v1.0.1
    - Move .disabled/packagename@1_0_1/ → custom_nodes/PackageName/
    - Move custom_nodes/PackageName/ → .disabled/packagename@nightly/

  Step 2: Upgrade CNR v1.0.1 → v1.0.2 (in-place)
    - Download CNR v1.0.2
    - Remove custom_nodes/PackageName/
    - Install CNR v1.0.2 to custom_nodes/PackageName/

Final State:
  custom_nodes/PackageName/  (CNR v1.0.2 with .tracking)
  .disabled/packagename@nightly/  (Nightly preserved)

Result:
  ✓ CNR v1.0.2 installed and enabled
  ✓ CNR v1.0.1 removed (not preserved in .disabled/)
  ✓ Nightly preserved in .disabled/
```

### CNR Disable

**Scenario**: Disabling CNR v1.0.1 when Nightly exists

```
Initial State:
  custom_nodes/PackageName/  (CNR v1.0.1 with .tracking)

Action:
  Disable CNR v1.0.1

Final State:
  .disabled/packagename@1_0_1/  (CNR v1.0.1 with .tracking)

Note:
  - Only ONE disabled CNR version exists
  - If another CNR is already disabled, it is replaced
```

### Nightly Installation (with CNR Disabled)

**Scenario**: Installing Nightly when CNR v1.0.1 is disabled

```
Initial State:
  .disabled/packagename@1_0_1/  (CNR v1.0.1 with .tracking)

Action:
  Install Nightly

Final State:
  custom_nodes/PackageName/  (Nightly with .git)
  .disabled/packagename@1_0_1/  (CNR v1.0.1 preserved)

Result:
  ✓ Nightly installed and enabled
  ✓ Disabled CNR v1.0.1 preserved (not removed)
  ✓ Different handling for Nightly vs CNR
```

## Implementation Requirements

### CNR Install/Upgrade Operation

1. **Check for existing CNR versions**:
   - Enabled: `custom_nodes/PackageName/` with `.tracking`
   - Disabled: `.disabled/*` with `.tracking`

2. **Remove old CNR versions**:
   - If enabled CNR exists: Remove it
   - If disabled CNR exists: Remove it
   - Ensure only ONE CNR version will exist after operation

3. **Install new CNR version**:
   - Download and extract to target location
   - Create `.tracking` file
   - Register in package database

4. **Preserve Nightly packages**:
   - Do NOT remove packages with `.git` directory
   - Nightly packages should be preserved in `.disabled/`

### CNR Disable Operation

1. **Move enabled CNR to disabled**:
   - Move `custom_nodes/PackageName/` → `.disabled/packagename@version/`
   - Use **installed version** for directory name (not registry latest)

2. **Remove any existing disabled CNR**:
   - Only ONE disabled CNR version allowed
   - If another CNR already in `.disabled/`, remove it first

3. **Preserve disabled Nightly**:
   - Do NOT remove disabled Nightly packages
   - Multiple Nightly versions can coexist in `.disabled/`

### CNR Enable Operation

1. **Check for enabled package**:
   - If another package enabled, disable it first

2. **Move disabled CNR to enabled**:
   - Move `.disabled/packagename@version/` → `custom_nodes/PackageName/`

3. **Maintain single CNR policy**:
   - After enable, no CNR should remain in `.disabled/`
   - Only Nightly packages should remain in `.disabled/`

## Test Coverage

### Phase 7: Version Management Behavior Tests

**Test 7.1: `test_cnr_version_upgrade_removes_old`**
- ✅ Verifies in-place upgrade removes old CNR version
- ✅ Confirms only one CNR version exists after upgrade
- ✅ Documents single version policy

**Test 7.2: `test_cnr_nightly_switching_preserves_nightly_only`**
- ✅ Verifies Nightly preservation across CNR upgrades
- ✅ Confirms old CNR versions removed (not preserved)
- ✅ Documents different handling for CNR vs Nightly

### Other Relevant Tests

**Phase 1-6 Tests**:
- ✅ All tests comply with single CNR version policy
- ✅ No tests assume multiple CNR versions coexist
- ✅ Fixtures properly handle CNR vs Nightly differences

## Known Behaviors

### Correct Behaviors (By Design)

1. **CNR Upgrades Remove Old Versions**
   - Status: ✅ Intentional design
   - Reason: In-place upgrade policy
   - Test: Phase 7.1 verifies this

2. **Only One CNR Version Exists**
   - Status: ✅ Intentional design
   - Reason: Single version policy
   - Test: Phase 7.2 verifies this

3. **Nightly Preserved, CNR Not**
   - Status: ✅ Intentional design
   - Reason: Different use cases
   - Test: Phase 7.2 verifies this

### Known Issues

1. **Disable API Version Mismatch**
   - Status: ⚠️ Bug to be fixed
   - Issue: Disabled directory name uses registry latest instead of installed version
   - Impact: Incorrect directory naming
   - Priority: Medium

## Design Rationale

### Why In-Place Upgrade?

**Benefits**:
- Simple mental model for users
- No disk space accumulation
- Clear version state
- Easier maintenance

**Trade-offs**:
- No automatic rollback capability
- Users must reinstall old versions from registry
- Network required for version downgrades

**Decision**: Benefits outweigh trade-offs for stable release management.

### Why Different CNR vs Nightly Handling?

**CNR (Stable Releases)**:
- Users want single stable version
- Production use case
- Rollback via registry if needed

**Nightly (Development Builds)**:
- Developers test multiple versions
- Development use case
- Local version testing important

**Decision**: Different use cases justify different policies.

## Future Considerations

### Potential Enhancements (Not Currently Planned)

1. **Optional Version History**
   - Configurable preservation of last N versions
   - Opt-in via configuration flag
   - Separate history directory

2. **CNR Rollback API**
   - Dedicated rollback endpoint
   - Re-download from registry
   - Preserve current version before downgrade

3. **Version Pinning**
   - Pin specific CNR version
   - Prevent automatic upgrades
   - Per-package configuration

**Note**: These are potential future enhancements, not current requirements.

## Version History

| Version | Date | Changes |
|---------|------|---------|
| 1.1 | 2025-11-08 | Added API Response Priority Rules (Rule 1: Enabled-Priority, Rule 2: CNR-Priority) |
| 1.0 | 2025-11-06 | Initial design document based on user clarification |

## References

- Phase 7 Test Implementation: `tests/glob/test_complex_scenarios.py`
- Policy Clarification: `.claude/livecontext/cnr_version_policy_clarification.md`
- Bug Report: `.claude/livecontext/bugs_to_file.md`

---

**Approved By**: User feedback 2025-11-06
**Status**: Official Policy
**Compliance**: All tests verified against this policy