refactor: remove package-level caching to support dynamic installation
Remove package-level caching in cnr_utils and node_package modules to enable proper dynamic custom node installation and version switching without ComfyUI server restarts. Key Changes: - Remove @lru_cache decorators from version-sensitive functions - Remove cached_property from NodePackage for dynamic state updates - Add comprehensive test suite with parallel execution support - Implement version switching tests (CNR ↔ Nightly) - Add case sensitivity integration tests - Improve error handling and logging API Priority Rules (manager_core.py:1801): - Enabled-Priority: Show only enabled version when both exist - CNR-Priority: Show only CNR when both CNR and Nightly are disabled - Prevents duplicate package entries in /v2/customnode/installed API - Cross-match using cnr_id and aux_id for CNR ↔ Nightly detection Test Infrastructure: - 8 test files with 59 comprehensive test cases - Parallel test execution across 5 isolated environments - Automated test scripts with environment setup - Configurable timeout (60 minutes default) - Support for both master and dr-support-pip-cm branches Bug Fixes: - Fix COMFYUI_CUSTOM_NODES_PATH environment variable export - Resolve test fixture regression with module-level variables - Fix import timing issues in test configuration - Register pytest integration marker to eliminate warnings - Fix POSIX compliance in shell scripts (((var++)) → $((var + 1))) Documentation: - CNR_VERSION_MANAGEMENT_DESIGN.md v1.0 → v1.1 with API priority rules - Add test guides and execution documentation (TESTING_PROMPT.md) - Add security-enhanced installation guide - Create CLI migration guides and references - Document package version management 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Dr.Lt.Data
496
docs/PACKAGE_VERSION_MANAGEMENT.md
Normal file
496
docs/PACKAGE_VERSION_MANAGEMENT.md
Normal file
@@ -0,0 +1,496 @@
|
||||
# Package Version Management Design
|
||||
|
||||
## Overview
|
||||
|
||||
ComfyUI Manager supports two package version types, each with distinct installation methods and version switching mechanisms:
|
||||
|
||||
1. **CNR Version (Archive)**: Production-ready releases with semantic versioning (e.g., v1.0.2), published to CNR server, verified, and distributed as ZIP archives
|
||||
2. **Nightly Version**: Real-time development builds from Git repository without semantic versioning, providing direct access to latest code via git pull
|
||||
|
||||
## Package ID Normalization
|
||||
|
||||
### Case Sensitivity Handling
|
||||
|
||||
**Source of Truth**: Package IDs originate from `pyproject.toml` with their original case (e.g., `ComfyUI_SigmoidOffsetScheduler`)
|
||||
|
||||
**Normalization Process**:
|
||||
1. `cnr_utils.normalize_package_name()` provides centralized normalization (`cnr_utils.py:28-48`):
|
||||
```python
|
||||
def normalize_package_name(name: str) -> str:
|
||||
"""
|
||||
Normalize package name for case-insensitive matching.
|
||||
- Strip leading/trailing whitespace
|
||||
- Convert to lowercase
|
||||
"""
|
||||
return name.strip().lower()
|
||||
```
|
||||
2. `cnr_utils.read_cnr_info()` uses this normalization when indexing (`cnr_utils.py:314`):
|
||||
```python
|
||||
name = project.get('name').strip().lower()
|
||||
```
|
||||
3. Package indexed in `installed_node_packages` with lowercase ID: `'comfyui_sigmoidoffsetscheduler'`
|
||||
4. **Critical**: All lookups (`is_enabled()`, `unified_disable()`) must use `cnr_utils.normalize_package_name()` for matching
|
||||
|
||||
**Implementation** (`manager_core.py:1374, 1389`):
|
||||
```python
|
||||
# Before checking if package is enabled or disabling
|
||||
packname_normalized = cnr_utils.normalize_package_name(packname)
|
||||
if self.is_enabled(packname_normalized):
|
||||
self.unified_disable(packname_normalized)
|
||||
```
|
||||
|
||||
## Package Identification
|
||||
|
||||
### How Packages Are Identified
|
||||
|
||||
**Critical**: Packages MUST be identified by marker files and metadata, NOT by directory names.
|
||||
|
||||
**Identification Flow** (`manager_core.py:691-703`, `node_package.py:49-81`):
|
||||
|
||||
```python
|
||||
def resolve_from_path(fullpath):
|
||||
"""
|
||||
Identify package type and ID using markers and metadata files.
|
||||
|
||||
Priority:
|
||||
1. Check for .git directory (Nightly)
|
||||
2. Check for .tracking + pyproject.toml (CNR)
|
||||
3. Unknown/legacy (fallback to directory name)
|
||||
"""
|
||||
# 1. Nightly Detection
|
||||
url = git_utils.git_url(fullpath) # Checks for .git/config
|
||||
if url:
|
||||
url = git_utils.compact_url(url)
|
||||
commit_hash = git_utils.get_commit_hash(fullpath)
|
||||
return {'id': url, 'ver': 'nightly', 'hash': commit_hash}
|
||||
|
||||
# 2. CNR Detection
|
||||
info = cnr_utils.read_cnr_info(fullpath) # Checks for .tracking + pyproject.toml
|
||||
if info:
|
||||
return {'id': info['id'], 'ver': info['version']}
|
||||
|
||||
# 3. Unknown (fallback)
|
||||
return None
|
||||
```
|
||||
|
||||
### Marker-Based Identification
|
||||
|
||||
**1. Nightly Packages**:
|
||||
- **Marker**: `.git` directory presence
|
||||
- **ID Extraction**: Read URL from `.git/config` using `git_utils.git_url()` (`git_utils.py:34-53`)
|
||||
- **ID Format**: Compact URL (e.g., `https://github.com/owner/repo` → compact form)
|
||||
- **Why**: Git repositories are uniquely identified by their remote URL
|
||||
|
||||
**2. CNR Packages**:
|
||||
- **Markers**: `.tracking` file AND `pyproject.toml` file (`.git` must NOT exist)
|
||||
- **ID Extraction**: Read `name` from `pyproject.toml` using `cnr_utils.read_cnr_info()` (`cnr_utils.py:302-334`)
|
||||
- **ID Format**: Normalized lowercase from `pyproject.toml` (e.g., `ComfyUI_Foo` → `comfyui_foo`)
|
||||
- **Why**: CNR packages are identified by their canonical name in package metadata
|
||||
|
||||
**Implementation** (`cnr_utils.py:302-334`):
|
||||
```python
|
||||
def read_cnr_info(fullpath):
|
||||
toml_path = os.path.join(fullpath, 'pyproject.toml')
|
||||
tracking_path = os.path.join(fullpath, '.tracking')
|
||||
|
||||
# MUST have both markers and NO .git directory
|
||||
if not os.path.exists(toml_path) or not os.path.exists(tracking_path):
|
||||
return None # not valid CNR node pack
|
||||
|
||||
with open(toml_path, "r", encoding="utf-8") as f:
|
||||
data = toml.load(f)
|
||||
project = data.get('project', {})
|
||||
name = project.get('name').strip().lower() # ← Normalized for indexing
|
||||
original_name = project.get('name') # ← Original case preserved
|
||||
version = str(manager_util.StrictVersion(project.get('version')))
|
||||
|
||||
return {
|
||||
"id": name, # Normalized ID for lookups
|
||||
"original_name": original_name,
|
||||
"version": version,
|
||||
"url": repository
|
||||
}
|
||||
```
|
||||
|
||||
### Why NOT Directory Names?
|
||||
|
||||
**Problem with directory-based identification**:
|
||||
1. **Case Sensitivity Issues**: Same package can have different directory names
|
||||
- Active: `ComfyUI_Foo` (original case)
|
||||
- Disabled: `comfyui_foo@1_0_2` (lowercase)
|
||||
2. **Version Suffix Confusion**: Disabled directories include version in name
|
||||
3. **User Modifications**: Users can rename directories, breaking identification
|
||||
|
||||
**Correct Approach**:
|
||||
- **Source of Truth**: Marker files (`.git`, `.tracking`, `pyproject.toml`)
|
||||
- **Consistent IDs**: Based on metadata content, not filesystem names
|
||||
- **Case Insensitive**: Normalized lookups work regardless of directory name
|
||||
|
||||
### Package Lookup Flow
|
||||
|
||||
**Index Building** (`manager_core.py:444-478`):
|
||||
```python
|
||||
def reload(self):
|
||||
self.installed_node_packages: dict[str, list[InstalledNodePackage]] = defaultdict(list)
|
||||
|
||||
# Scan active packages
|
||||
for x in os.listdir(custom_nodes_path):
|
||||
fullpath = os.path.join(custom_nodes_path, x)
|
||||
if x not in ['__pycache__', '.disabled']:
|
||||
node_package = InstalledNodePackage.from_fullpath(fullpath, self.resolve_from_path)
|
||||
# ↓ Uses ID from resolve_from_path(), NOT directory name
|
||||
self.installed_node_packages[node_package.id].append(node_package)
|
||||
|
||||
# Scan disabled packages
|
||||
for x in os.listdir(disabled_dir):
|
||||
fullpath = os.path.join(disabled_dir, x)
|
||||
node_package = InstalledNodePackage.from_fullpath(fullpath, self.resolve_from_path)
|
||||
# ↓ Same ID extraction, consistent indexing
|
||||
self.installed_node_packages[node_package.id].append(node_package)
|
||||
```
|
||||
|
||||
**Lookup Process**:
|
||||
1. Normalize search term: `cnr_utils.normalize_package_name(packname)`
|
||||
2. Look up in `installed_node_packages` dict by normalized ID
|
||||
3. Match found packages by version if needed
|
||||
4. Return `InstalledNodePackage` objects with full metadata
|
||||
|
||||
### Edge Cases
|
||||
|
||||
**1. Package with `.git` AND `.tracking`**:
|
||||
- **Detection**: Treated as Nightly (`.git` checked first)
|
||||
- **Reason**: Git repo takes precedence over archive markers
|
||||
- **Fix**: Remove `.tracking` file to avoid confusion
|
||||
|
||||
**2. Missing Marker Files**:
|
||||
- **CNR without `.tracking`**: Treated as Unknown
|
||||
- **Nightly without `.git`**: Treated as Unknown or CNR (if has `.tracking`)
|
||||
- **Recovery**: Re-install package to restore correct markers
|
||||
|
||||
**3. Corrupted `pyproject.toml`**:
|
||||
- **Detection**: `read_cnr_info()` returns `None`
|
||||
- **Result**: Package treated as Unknown
|
||||
- **Recovery**: Manual fix or re-install
|
||||
|
||||
## Version Types
|
||||
|
||||
ComfyUI Manager supports two main package version types:
|
||||
|
||||
### 1. CNR Version (Comfy Node Registry - Versioned Releases)
|
||||
|
||||
**Also known as**: Archive version (because it's distributed as ZIP archive)
|
||||
|
||||
**Purpose**: Production-ready releases that have been versioned, published to CNR server, and verified before distribution
|
||||
|
||||
**Characteristics**:
|
||||
- Semantic versioning assigned (e.g., v1.0.2, v2.1.0)
|
||||
- Published to CNR server with verification process
|
||||
- Stable, tested releases for production use
|
||||
- Distributed as ZIP archives for reliability
|
||||
|
||||
**Installation Method**: ZIP file extraction from CNR (Comfy Node Registry)
|
||||
|
||||
**Identification**:
|
||||
- Presence of `.tracking` file in package directory
|
||||
- **Directory naming**:
|
||||
- **Active** (`custom_nodes/`): Uses `name` from `pyproject.toml` with original case (e.g., `ComfyUI_SigmoidOffsetScheduler`)
|
||||
- This is the `original_name` in glob/ implementation
|
||||
- **Disabled** (`.disabled/`): Uses `{package_name}@{version}` format (e.g., `comfyui_sigmoidoffsetscheduler@1_0_2`)
|
||||
- Package indexed with lowercase ID from `pyproject.toml`
|
||||
- Versioned releases (e.g., v1.0.2, v2.1.0)
|
||||
|
||||
**`.tracking` File Purpose**:
|
||||
- **Primary**: Marker to identify this as a CNR/archive installation
|
||||
- **Critical**: Contains list of original files from the archive
|
||||
- **Update Use Case**: When updating to a new version:
|
||||
1. Read `.tracking` to identify original archive files
|
||||
2. Delete ONLY original archive files
|
||||
3. Preserve user-generated files (configs, models, custom code)
|
||||
4. Extract new archive version
|
||||
5. Update `.tracking` with new file list
|
||||
|
||||
**File Structure**:
|
||||
```
|
||||
custom_nodes/
|
||||
ComfyUI_SigmoidOffsetScheduler/
|
||||
.tracking # List of original archive files
|
||||
pyproject.toml # name = "ComfyUI_SigmoidOffsetScheduler"
|
||||
__init__.py
|
||||
nodes.py
|
||||
(user-created files preserved during update)
|
||||
```
|
||||
|
||||
### 2. Nightly Version (Development Builds)
|
||||
|
||||
**Purpose**: Real-time development builds from Git repository without semantic versioning
|
||||
|
||||
**Characteristics**:
|
||||
- No semantic version assigned (version = "nightly")
|
||||
- Direct access to latest development code
|
||||
- Real-time updates via git pull
|
||||
- For testing, development, and early adoption
|
||||
- Not verified through CNR publication process
|
||||
|
||||
**Installation Method**: Git repository clone
|
||||
|
||||
**Identification**:
|
||||
- Presence of `.git` directory in package directory
|
||||
- `version: "nightly"` in package metadata
|
||||
- **Directory naming**:
|
||||
- **Active** (`custom_nodes/`): Uses `name` from `pyproject.toml` with original case (e.g., `ComfyUI_SigmoidOffsetScheduler`)
|
||||
- This is the `original_name` in glob/ implementation
|
||||
- **Disabled** (`.disabled/`): Uses `{package_name}@nightly` format (e.g., `comfyui_sigmoidoffsetscheduler@nightly`)
|
||||
|
||||
**Update Mechanism**:
|
||||
- `git pull` on existing repository
|
||||
- All user modifications in git working tree preserved by git
|
||||
|
||||
**File Structure**:
|
||||
```
|
||||
custom_nodes/
|
||||
ComfyUI_SigmoidOffsetScheduler/
|
||||
.git/ # Git repository marker
|
||||
pyproject.toml
|
||||
__init__.py
|
||||
nodes.py
|
||||
(git tracks all changes)
|
||||
```
|
||||
|
||||
## Version Switching Mechanisms
|
||||
|
||||
### CNR ↔ Nightly (Uses `.disabled/` Directory)
|
||||
|
||||
**Mechanism**: Enable/disable toggling - only ONE version active at a time
|
||||
|
||||
**Process**:
|
||||
1. **CNR → Nightly**:
|
||||
```
|
||||
Before: custom_nodes/ComfyUI_SigmoidOffsetScheduler/ (has .tracking)
|
||||
After: custom_nodes/ComfyUI_SigmoidOffsetScheduler/ (has .git)
|
||||
.disabled/comfyui_sigmoidoffsetscheduler@1_0_2/ (has .tracking)
|
||||
```
|
||||
- Move archive directory to `.disabled/comfyui_sigmoidoffsetscheduler@{version}/`
|
||||
- Git clone nightly to `custom_nodes/ComfyUI_SigmoidOffsetScheduler/`
|
||||
|
||||
2. **Nightly → CNR**:
|
||||
```
|
||||
Before: custom_nodes/ComfyUI_SigmoidOffsetScheduler/ (has .git)
|
||||
.disabled/comfyui_sigmoidoffsetscheduler@1_0_2/ (has .tracking)
|
||||
After: custom_nodes/ComfyUI_SigmoidOffsetScheduler/ (has .tracking)
|
||||
.disabled/comfyui_sigmoidoffsetscheduler@nightly/ (has .git)
|
||||
```
|
||||
- Move nightly directory to `.disabled/comfyui_sigmoidoffsetscheduler@nightly/`
|
||||
- Restore archive from `.disabled/comfyui_sigmoidoffsetscheduler@{version}/`
|
||||
|
||||
**Key Points**:
|
||||
- Both versions preserved in filesystem (one in `.disabled/`)
|
||||
- Switching is fast (just move operations)
|
||||
- No re-download needed when switching back
|
||||
|
||||
### CNR Version Update (In-Place Update)
|
||||
|
||||
**Mechanism**: Direct directory content update - NO `.disabled/` directory used
|
||||
|
||||
**When**: Switching between different CNR versions (e.g., v1.0.1 → v1.0.2)
|
||||
|
||||
**Process**:
|
||||
```
|
||||
Before: custom_nodes/ComfyUI_SigmoidOffsetScheduler/ (v1.0.1, has .tracking)
|
||||
After: custom_nodes/ComfyUI_SigmoidOffsetScheduler/ (v1.0.2, has .tracking)
|
||||
```
|
||||
|
||||
**Steps**:
|
||||
1. Read `.tracking` to identify original v1.0.1 files
|
||||
2. Delete only original v1.0.1 files (preserve user-created files)
|
||||
3. Extract v1.0.2 archive to same directory
|
||||
4. Update `.tracking` with v1.0.2 file list
|
||||
5. Update `pyproject.toml` version metadata
|
||||
|
||||
**Critical**: Directory name and location remain unchanged
|
||||
|
||||
## API Design Decisions
|
||||
|
||||
### Enable/Disable Operations
|
||||
|
||||
**Design Decision**: ❌ **NO DIRECT ENABLE/DISABLE API PROVIDED**
|
||||
|
||||
**Rationale**:
|
||||
- Enable/disable operations occur **ONLY as a by-product** of version switching
|
||||
- Version switching is the primary operation that manages package state
|
||||
- Direct enable/disable API would:
|
||||
1. Create ambiguity about which version to enable/disable
|
||||
2. Bypass version management logic
|
||||
3. Lead to inconsistent package state
|
||||
|
||||
**Implementation**:
|
||||
- `unified_enable()` and `unified_disable()` are **internal methods only**
|
||||
- Called exclusively from version switching operations:
|
||||
- `install_by_id()` (manager_core.py:1695-1724)
|
||||
- `cnr_switch_version_instant()` (manager_core.py:941)
|
||||
- `repo_update()` (manager_core.py:2144-2232)
|
||||
|
||||
**User Workflow**:
|
||||
```
|
||||
User wants to disable CNR version and enable Nightly:
|
||||
✅ Correct: install(package, version="nightly")
|
||||
→ automatically disables CNR, enables Nightly
|
||||
❌ Wrong: disable(package) + enable(package, "nightly")
|
||||
→ not supported, ambiguous
|
||||
```
|
||||
|
||||
**Testing Approach**:
|
||||
- Enable/disable tested **indirectly** through version switching tests
|
||||
- Test 1-12 validate enable/disable behavior via install/update operations
|
||||
- No direct enable/disable API tests needed (API doesn't exist)
|
||||
|
||||
## Implementation Details
|
||||
|
||||
### Version Detection Logic
|
||||
|
||||
**Location**: `comfyui_manager/common/node_package.py`
|
||||
|
||||
```python
|
||||
@dataclass
|
||||
class InstalledNodePackage:
|
||||
@property
|
||||
def is_nightly(self) -> bool:
|
||||
return self.version == "nightly"
|
||||
|
||||
@property
|
||||
def is_from_cnr(self) -> bool:
|
||||
return not self.is_unknown and not self.is_nightly
|
||||
```
|
||||
|
||||
**Detection Order**:
|
||||
1. Check for `.tracking` file → CNR (Archive) version
|
||||
2. Check for `.git` directory → Nightly version
|
||||
3. Otherwise → Unknown/legacy
|
||||
|
||||
### Reload Timing
|
||||
|
||||
**Critical**: `unified_manager.reload()` must be called:
|
||||
1. **Before each queued task** (`manager_server.py:1245`):
|
||||
```python
|
||||
# Reload installed packages before each task to ensure latest state
|
||||
core.unified_manager.reload()
|
||||
```
|
||||
2. **Before version switching** (`manager_core.py:1370`):
|
||||
```python
|
||||
# Reload to ensure we have the latest package state before checking
|
||||
self.reload()
|
||||
```
|
||||
|
||||
**Why**: Ensures `installed_node_packages` dict reflects actual filesystem state
|
||||
|
||||
### Disable Mechanism
|
||||
|
||||
**Implementation** (`manager_core.py:982-1017`, specifically line 1011):
|
||||
```python
|
||||
def unified_disable(self, packname: str):
|
||||
# ... validation logic ...
|
||||
|
||||
# Generate disabled directory name with version suffix
|
||||
base_path = extract_base_custom_nodes_dir(matched_active.fullpath)
|
||||
folder_name = packname if not self.is_url_like(packname) else os.path.basename(matched_active.fullpath)
|
||||
to_path = os.path.join(base_path, '.disabled', f"{folder_name}@{matched_active.version.replace('.', '_')}")
|
||||
|
||||
shutil.move(matched_active.fullpath, to_path)
|
||||
```
|
||||
|
||||
**Naming Convention**:
|
||||
- `{folder_name}@{version}` format for ALL version types
|
||||
- CNR v1.0.2 → `comfyui_foo@1_0_2` (dots replaced with underscores)
|
||||
- Nightly → `comfyui_foo@nightly`
|
||||
|
||||
### Case Sensitivity Fix
|
||||
|
||||
**Problem**: Package IDs normalized to lowercase during indexing but not during lookup
|
||||
|
||||
**Solution** (`manager_core.py:1372-1378, 1388-1393`):
|
||||
```python
|
||||
# Normalize packname using centralized cnr_utils function
|
||||
# CNR packages are indexed with lowercase IDs from pyproject.toml
|
||||
packname_normalized = cnr_utils.normalize_package_name(packname)
|
||||
|
||||
if self.is_enabled(packname_normalized):
|
||||
self.unified_disable(packname_normalized)
|
||||
```
|
||||
|
||||
**Why Centralized Function**:
|
||||
- Consistent normalization across entire codebase
|
||||
- Single source of truth for package name normalization logic
|
||||
- Easier to maintain and test
|
||||
- Located in `cnr_utils.py:28-48`
|
||||
|
||||
## Directory Structure Examples
|
||||
|
||||
### Complete Example: All Version Types Coexisting
|
||||
|
||||
```
|
||||
custom_nodes/
|
||||
ComfyUI_SigmoidOffsetScheduler/ # Active version (CNR v2.0.0 in this example)
|
||||
pyproject.toml # name = "ComfyUI_SigmoidOffsetScheduler"
|
||||
__init__.py
|
||||
nodes.py
|
||||
|
||||
.disabled/ # Inactive versions storage
|
||||
comfyui_sigmoidoffsetscheduler@nightly/ # ← Nightly (disabled)
|
||||
.git/ # ← Nightly marker
|
||||
pyproject.toml
|
||||
__init__.py
|
||||
nodes.py
|
||||
|
||||
comfyui_sigmoidoffsetscheduler@1_0_2/ # ← CNR v1.0.2 (disabled)
|
||||
.tracking # ← CNR marker with file list
|
||||
pyproject.toml
|
||||
__init__.py
|
||||
nodes.py
|
||||
|
||||
comfyui_sigmoidoffsetscheduler@1_0_1/ # ← CNR v1.0.1 (disabled)
|
||||
.tracking
|
||||
pyproject.toml
|
||||
__init__.py
|
||||
nodes.py
|
||||
```
|
||||
|
||||
**Key Points**:
|
||||
- Active directory ALWAYS uses `original_name` without version suffix
|
||||
- Each disabled version has `@{version}` suffix to avoid conflicts
|
||||
- Multiple disabled versions can coexist (nightly + multiple CNR versions)
|
||||
|
||||
## Summary Table
|
||||
|
||||
| Version Type | Purpose | Marker | Active Directory Name | Disabled Directory Name | Update Method | Switch Mechanism |
|
||||
|--------------|---------|--------|----------------------|------------------------|---------------|------------------|
|
||||
| **CNR** (Archive) | Production-ready releases with semantic versioning, published to CNR server and verified | `.tracking` file | `original_name` (e.g., `ComfyUI_Foo`) | `{package}@{version}` (e.g., `comfyui_foo@1_0_2`) | In-place update (preserve user files) | `.disabled/` toggle |
|
||||
| **Nightly** | Real-time development builds from Git repository without semantic versioning | `.git/` directory | `original_name` (e.g., `ComfyUI_Foo`) | `{package}@nightly` (e.g., `comfyui_foo@nightly`) | `git pull` | `.disabled/` toggle |
|
||||
|
||||
**Important Constraints**:
|
||||
- **Active directory name**: MUST use `original_name` (from `pyproject.toml`) without version suffix
|
||||
- Other code may depend on this specific directory name
|
||||
- Only ONE version can be active at a time
|
||||
- **Disabled directory name**: MUST include `@{version}` suffix to allow multiple disabled versions to coexist
|
||||
- CNR: `@{version}` (e.g., `@1_0_2`)
|
||||
- Nightly: `@nightly`
|
||||
|
||||
## Edge Cases
|
||||
|
||||
### 1. Multiple CNR Versions
|
||||
- Each stored in `.disabled/` with version suffix
|
||||
- Only one can be active at a time
|
||||
- Switching between CNR versions = direct content update (not via `.disabled/`)
|
||||
|
||||
### 2. Package ID Case Variations
|
||||
- Always normalize to lowercase for internal lookups
|
||||
- Preserve original case in filesystem/display
|
||||
- Match against lowercase indexed keys
|
||||
|
||||
### 3. Corrupted `.tracking` File
|
||||
- Treat as unknown version type
|
||||
- Warn user before update/uninstall
|
||||
- May require manual cleanup
|
||||
|
||||
### 4. Mixed CNR + Nightly in `.disabled/`
|
||||
- Both can coexist in `.disabled/`
|
||||
- Only one can be active in `custom_nodes/`
|
||||
- Switch logic detects type and handles appropriately
|
||||
235
docs/SECURITY_ENHANCED_INSTALLATION.md
Normal file
235
docs/SECURITY_ENHANCED_INSTALLATION.md
Normal file
@@ -0,0 +1,235 @@
|
||||
# Security-Enhanced URL Installation System
|
||||
|
||||
## Overview
|
||||
|
||||
Security constraints have been added to the `install_by_url` function to control URL-based installations according to the system's security level.
|
||||
|
||||
## Security Level and Risk Level Framework
|
||||
|
||||
### Security Levels (SecurityLevel)
|
||||
- **strong**: Most restrictive, only trusted sources allowed
|
||||
- **normal**: Standard security, most known platforms allowed
|
||||
- **normal-**: Relaxed security, additional allowances for personal cloud environments
|
||||
- **weak**: Most permissive security, for local development environments
|
||||
|
||||
### Risk Levels (RiskLevel)
|
||||
- **block**: Complete block (always denied)
|
||||
- **high+**: Very high risk (only allowed in local mode + weak/normal-)
|
||||
- **high**: High risk (only allowed in local mode + weak/normal- or personal cloud + weak)
|
||||
- **middle+**: Medium-high risk (weak/normal/normal- allowed in local/personal cloud)
|
||||
- **middle**: Medium risk (weak/normal/normal- allowed in all environments)
|
||||
|
||||
## URL Risk Assessment Logic
|
||||
|
||||
### Low Risk (middle) - Trusted Platforms
|
||||
```
|
||||
- github.com
|
||||
- gitlab.com
|
||||
- bitbucket.org
|
||||
- raw.githubusercontent.com
|
||||
- gitlab.io
|
||||
```
|
||||
|
||||
### High Risk (high+) - Suspicious/Local Hosting
|
||||
```
|
||||
- localhost, 127.0.0.1
|
||||
- Private IP ranges: 192.168.*, 10.0.*, 172.*
|
||||
- Temporary hosting: ngrok.io, herokuapp.com, repl.it, glitch.me
|
||||
```
|
||||
|
||||
### Medium-High Risk (middle+) - Unknown Domains
|
||||
```
|
||||
- All domains not belonging to the above categories
|
||||
```
|
||||
|
||||
### High Risk (high) - SSH Protocol
|
||||
```
|
||||
- URLs starting with ssh:// or git@
|
||||
```
|
||||
|
||||
## Implemented Security Features
|
||||
|
||||
### 1. Security Validation (`_validate_url_security`)
|
||||
```python
|
||||
async def install_by_url(self, url: str, ...):
|
||||
# Security validation
|
||||
security_result = self._validate_url_security(url)
|
||||
if not security_result['allowed']:
|
||||
return self._report_failed_install_security(url, security_result['reason'], custom_name)
|
||||
```
|
||||
|
||||
**Features**:
|
||||
- Check current security level
|
||||
- Assess URL risk
|
||||
- Allow/block decision based on security policy
|
||||
|
||||
### 2. Failure Reporting (`_report_failed_install_security`)
|
||||
```python
|
||||
def _report_failed_install_security(self, url: str, reason: str, custom_name=None):
|
||||
# Security block logging
|
||||
print(f"[SECURITY] Blocked URL installation: {url}")
|
||||
|
||||
# Record failed installation
|
||||
self._record_failed_install_nodepack({
|
||||
'type': 'url-security-block',
|
||||
'url': url,
|
||||
'package_name': pack_name,
|
||||
'reason': reason,
|
||||
'security_level': current_security_level,
|
||||
'timestamp': timestamp
|
||||
})
|
||||
```
|
||||
|
||||
**Features**:
|
||||
- Log blocked installation attempts to console
|
||||
- Save failure information in structured format
|
||||
- Return failure result as ManagedResult
|
||||
|
||||
### 3. Failed Installation Record Management (`_record_failed_install_nodepack`)
|
||||
```python
|
||||
def get_failed_install_reports(self) -> list:
|
||||
return getattr(self, '_failed_installs', [])
|
||||
```
|
||||
|
||||
**Features**:
|
||||
- Maintain recent 100 failure records
|
||||
- Prevent memory overflow
|
||||
- Provide API for monitoring and debugging
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Behavior by Security Setting
|
||||
|
||||
#### Strong Security Level
|
||||
```python
|
||||
# Most URLs are blocked
|
||||
result = await manager.install_by_url("https://github.com/user/repo")
|
||||
# Result: Blocked (github is also middle risk, so blocked at strong level)
|
||||
|
||||
result = await manager.install_by_url("https://suspicious-domain.com/repo.git")
|
||||
# Result: Blocked (middle+ risk)
|
||||
```
|
||||
|
||||
#### Normal Security Level
|
||||
```python
|
||||
# Trusted platforms allowed
|
||||
result = await manager.install_by_url("https://github.com/user/repo")
|
||||
# Result: Allowed
|
||||
|
||||
result = await manager.install_by_url("https://localhost/repo.git")
|
||||
# Result: Blocked (high+ risk)
|
||||
```
|
||||
|
||||
#### Weak Security Level (Local Development Environment)
|
||||
```python
|
||||
# Almost all URLs allowed
|
||||
result = await manager.install_by_url("https://github.com/user/repo")
|
||||
# Result: Allowed
|
||||
|
||||
result = await manager.install_by_url("https://192.168.1.100/repo.git")
|
||||
# Result: Allowed (in local mode)
|
||||
|
||||
result = await manager.install_by_url("git@private-server.com:user/repo.git")
|
||||
# Result: Allowed
|
||||
```
|
||||
|
||||
### Failure Monitoring
|
||||
```python
|
||||
manager = UnifiedManager()
|
||||
|
||||
# Blocked installation attempt
|
||||
await manager.install_by_url("https://malicious-site.com/evil-nodes.git")
|
||||
|
||||
# Check failure records
|
||||
failed_reports = manager.get_failed_install_reports()
|
||||
for report in failed_reports:
|
||||
print(f"Blocked: {report['url']} - {report['reason']}")
|
||||
```
|
||||
|
||||
## Security Policy Matrix
|
||||
|
||||
| Risk Level | Strong | Normal | Normal- | Weak |
|
||||
|------------|--------|--------|---------|------|
|
||||
| **block** | ❌ | ❌ | ❌ | ❌ |
|
||||
| **high+** | ❌ | ❌ | 🔒* | 🔒* |
|
||||
| **high** | ❌ | ❌ | 🔒*/☁️** | ✅ |
|
||||
| **middle+**| ❌ | ❌ | 🔒*/☁️** | ✅ |
|
||||
| **middle** | ❌ | ✅ | ✅ | ✅ |
|
||||
|
||||
- 🔒* : Allowed only in local mode
|
||||
- ☁️** : Allowed only in personal cloud mode
|
||||
- ✅ : Allowed
|
||||
- ❌ : Blocked
|
||||
|
||||
## Error Message Examples
|
||||
|
||||
### Security Block
|
||||
```
|
||||
Installation blocked by security policy: URL installation blocked by security level: strong (risk: middle)
|
||||
Target: awesome-nodes@url-blocked
|
||||
```
|
||||
|
||||
### Console Log
|
||||
```
|
||||
[SECURITY] Blocked URL installation: https://suspicious-domain.com/repo.git
|
||||
[SECURITY] Reason: URL installation blocked by security level: normal (risk: middle+)
|
||||
[SECURITY] Package: repo
|
||||
```
|
||||
|
||||
## Configuration Recommendations
|
||||
|
||||
### Production Environment
|
||||
```json
|
||||
{
|
||||
"security_level": "strong",
|
||||
"network_mode": "private"
|
||||
}
|
||||
```
|
||||
- Most restrictive settings
|
||||
- Only trusted sources allowed
|
||||
|
||||
### Development Environment
|
||||
```json
|
||||
{
|
||||
"security_level": "weak",
|
||||
"network_mode": "local"
|
||||
}
|
||||
```
|
||||
- Permissive settings for development convenience
|
||||
- Allow local repositories and development servers
|
||||
|
||||
### Personal Cloud Environment
|
||||
```json
|
||||
{
|
||||
"security_level": "normal-",
|
||||
"network_mode": "personal_cloud"
|
||||
}
|
||||
```
|
||||
- Balanced settings for personal use
|
||||
- Allow personal repository access
|
||||
|
||||
## Security Enhancement Benefits
|
||||
|
||||
### 1. Malware Prevention
|
||||
- Automatic blocking from unknown sources
|
||||
- Filter suspicious domains and IPs
|
||||
|
||||
### 2. Network Security
|
||||
- Control private network access
|
||||
- Restrict SSH protocol usage
|
||||
|
||||
### 3. Audit Trail
|
||||
- Record all blocked attempts
|
||||
- Log security events
|
||||
|
||||
### 4. Flexible Policy
|
||||
- Customized security levels per environment
|
||||
- Distinguish between production/development environments
|
||||
|
||||
## Backward Compatibility
|
||||
|
||||
- Existing `install_by_id` function unchanged
|
||||
- No security validation applied to CNR-based installations
|
||||
- `install_by_id_or_url` applies security only to URLs
|
||||
|
||||
This security enhancement significantly improves system security while maintaining the convenience of URL-based installations.
|
||||
355
docs/internal/CNR_VERSION_MANAGEMENT_DESIGN.md
Normal file
355
docs/internal/CNR_VERSION_MANAGEMENT_DESIGN.md
Normal file
@@ -0,0 +1,355 @@
|
||||
# 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
|
||||
292
docs/internal/cli_migration/CLI_API_REFERENCE.md
Normal file
292
docs/internal/cli_migration/CLI_API_REFERENCE.md
Normal file
@@ -0,0 +1,292 @@
|
||||
# Glob Module API Reference for CLI Migration
|
||||
|
||||
## 🎯 Quick Reference
|
||||
This document provides essential glob module APIs available for CLI implementation. **READ ONLY** - do not modify glob module.
|
||||
|
||||
---
|
||||
|
||||
## 📦 Core Classes
|
||||
|
||||
### UnifiedManager
|
||||
**Location**: `comfyui_manager/glob/manager_core.py:436`
|
||||
**Instance**: Available as `unified_manager` (global instance)
|
||||
|
||||
#### Data Structures
|
||||
```python
|
||||
class UnifiedManager:
|
||||
def __init__(self):
|
||||
# PRIMARY DATA - Use these instead of legacy dicts
|
||||
self.installed_node_packages: dict[str, list[InstalledNodePackage]]
|
||||
self.repo_nodepack_map: dict[str, InstalledNodePackage] # compact_url -> package
|
||||
self.processed_install: set
|
||||
```
|
||||
|
||||
#### Core Methods (Direct CLI Equivalents)
|
||||
```python
|
||||
# Installation & Management
|
||||
async def install_by_id(packname: str, version_spec=None, channel=None,
|
||||
mode=None, instant_execution=False, no_deps=False,
|
||||
return_postinstall=False) -> ManagedResult
|
||||
def unified_enable(packname: str, version_spec=None) -> ManagedResult
|
||||
def unified_disable(packname: str) -> ManagedResult
|
||||
def unified_uninstall(packname: str) -> ManagedResult
|
||||
def unified_update(packname: str, instant_execution=False, no_deps=False,
|
||||
return_postinstall=False) -> ManagedResult
|
||||
def unified_fix(packname: str, version_spec, instant_execution=False,
|
||||
no_deps=False) -> ManagedResult
|
||||
|
||||
# Package Resolution & Info
|
||||
def resolve_node_spec(packname: str, guess_mode=None) -> tuple[str, str, bool] | None
|
||||
def get_active_pack(packname: str) -> InstalledNodePackage | None
|
||||
def get_inactive_pack(packname: str, version_spec=None) -> InstalledNodePackage | None
|
||||
|
||||
# Git Repository Operations
|
||||
async def repo_install(url: str, repo_path: str, instant_execution=False,
|
||||
no_deps=False, return_postinstall=False) -> ManagedResult
|
||||
def repo_update(repo_path: str, instant_execution=False, no_deps=False,
|
||||
return_postinstall=False) -> ManagedResult
|
||||
|
||||
# Utilities
|
||||
def is_url_like(url: str) -> bool
|
||||
def reload() -> None
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### InstalledNodePackage
|
||||
**Location**: `comfyui_manager/common/node_package.py:10`
|
||||
|
||||
```python
|
||||
@dataclass
|
||||
class InstalledNodePackage:
|
||||
# Core Data
|
||||
id: str # Package identifier
|
||||
fullpath: str # Installation path
|
||||
disabled: bool # Disabled state
|
||||
version: str # Version (cnr version, "nightly", or "unknown")
|
||||
repo_url: str = None # Git repository URL (for nightly/unknown)
|
||||
|
||||
# Computed Properties
|
||||
@property
|
||||
def is_unknown(self) -> bool: # version == "unknown"
|
||||
@property
|
||||
def is_nightly(self) -> bool: # version == "nightly"
|
||||
@property
|
||||
def is_from_cnr(self) -> bool: # not unknown and not nightly
|
||||
@property
|
||||
def is_enabled(self) -> bool: # not disabled
|
||||
@property
|
||||
def is_disabled(self) -> bool: # disabled
|
||||
|
||||
# Methods
|
||||
def get_commit_hash(self) -> str
|
||||
def isValid(self) -> bool
|
||||
|
||||
@staticmethod
|
||||
def from_fullpath(fullpath: str, resolve_from_path) -> InstalledNodePackage
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### ManagedResult
|
||||
**Location**: `comfyui_manager/glob/manager_core.py:285`
|
||||
|
||||
```python
|
||||
class ManagedResult:
|
||||
def __init__(self, action: str):
|
||||
self.action: str = action # 'install-cnr', 'install-git', 'enable', 'skip', etc.
|
||||
self.result: bool = True # Success/failure
|
||||
self.msg: str = "" # Human readable message
|
||||
self.target: str = None # Target identifier
|
||||
self.postinstall = None # Post-install callback
|
||||
|
||||
# Methods
|
||||
def fail(self, msg: str = "") -> ManagedResult
|
||||
def with_msg(self, msg: str) -> ManagedResult
|
||||
def with_target(self, target: str) -> ManagedResult
|
||||
def with_postinstall(self, postinstall) -> ManagedResult
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ Standalone Functions
|
||||
|
||||
### Core Manager Functions
|
||||
```python
|
||||
# Snapshot Operations
|
||||
async def save_snapshot_with_postfix(postfix: str, path: str = None,
|
||||
custom_nodes_only: bool = False) -> str
|
||||
|
||||
async def restore_snapshot(snapshot_path: str, git_helper_extras=None) -> None
|
||||
|
||||
# Node Utilities
|
||||
def simple_check_custom_node(url: str) -> str # Returns: 'installed', 'not-installed', 'disabled'
|
||||
|
||||
# Path Utilities
|
||||
def get_custom_nodes_paths() -> list[str]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔗 CNR Utilities
|
||||
**Location**: `comfyui_manager/common/cnr_utils.py`
|
||||
|
||||
```python
|
||||
# Essential CNR functions for CLI
|
||||
def get_nodepack(packname: str) -> dict | None
|
||||
# Returns CNR package info or None
|
||||
|
||||
def get_all_nodepackages() -> dict[str, dict]
|
||||
# Returns all CNR packages {package_id: package_info}
|
||||
|
||||
def all_versions_of_node(node_name: str) -> list[dict] | None
|
||||
# Returns version history for a package
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📋 Usage Patterns for CLI Migration
|
||||
|
||||
### 1. Replace Legacy Dict Access
|
||||
```python
|
||||
# ❌ OLD (Legacy way)
|
||||
for k, v in unified_manager.active_nodes.items():
|
||||
version, fullpath = v
|
||||
print(f"Active: {k} @ {version}")
|
||||
|
||||
# ✅ NEW (Glob way)
|
||||
for packages in unified_manager.installed_node_packages.values():
|
||||
for pack in packages:
|
||||
if pack.is_enabled:
|
||||
print(f"Active: {pack.id} @ {pack.version}")
|
||||
```
|
||||
|
||||
### 2. Package Installation
|
||||
```python
|
||||
# CNR Package Installation
|
||||
res = await unified_manager.install_by_id("package-name", "1.0.0",
|
||||
instant_execution=True, no_deps=False)
|
||||
|
||||
# Git URL Installation
|
||||
if unified_manager.is_url_like(url):
|
||||
repo_name = os.path.basename(url).replace('.git', '')
|
||||
res = await unified_manager.repo_install(url, repo_name,
|
||||
instant_execution=True, no_deps=False)
|
||||
```
|
||||
|
||||
### 3. Package State Queries
|
||||
```python
|
||||
# Check if package is active
|
||||
active_pack = unified_manager.get_active_pack("package-name")
|
||||
if active_pack:
|
||||
print(f"Package is enabled: {active_pack.version}")
|
||||
|
||||
# Check if package is inactive
|
||||
inactive_pack = unified_manager.get_inactive_pack("package-name")
|
||||
if inactive_pack:
|
||||
print(f"Package is disabled: {inactive_pack.version}")
|
||||
```
|
||||
|
||||
### 4. CNR Data Access
|
||||
```python
|
||||
# Get CNR package information
|
||||
from ..common import cnr_utils
|
||||
|
||||
cnr_info = cnr_utils.get_nodepack("package-name")
|
||||
if cnr_info:
|
||||
publisher = cnr_info.get('publisher', {}).get('name', 'Unknown')
|
||||
print(f"Publisher: {publisher}")
|
||||
|
||||
# Get all CNR packages (for show not-installed)
|
||||
all_cnr = cnr_utils.get_all_nodepackages()
|
||||
```
|
||||
|
||||
### 5. Result Handling
|
||||
```python
|
||||
res = await unified_manager.install_by_id("package-name")
|
||||
|
||||
if res.action == 'skip':
|
||||
print(f"SKIP: {res.msg}")
|
||||
elif res.action == 'install-cnr' and res.result:
|
||||
print(f"INSTALLED: {res.target}")
|
||||
elif res.action == 'enable' and res.result:
|
||||
print(f"ENABLED: package was already installed")
|
||||
else:
|
||||
print(f"ERROR: {res.msg}")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🚫 NOT Available in Glob (Handle These)
|
||||
|
||||
### Legacy Functions That Don't Exist:
|
||||
- `get_custom_nodes()` → Use `cnr_utils.get_all_nodepackages()`
|
||||
- `load_nightly()` → Remove or stub
|
||||
- `extract_nodes_from_workflow()` → Remove feature
|
||||
- `gitclone_install()` → Use `repo_install()`
|
||||
|
||||
### Legacy Properties That Don't Exist:
|
||||
- `active_nodes` → Use `installed_node_packages` + filter by `is_enabled`
|
||||
- `cnr_map` → Use `cnr_utils.get_all_nodepackages()`
|
||||
- `cnr_inactive_nodes` → Use `installed_node_packages` + filter by `is_disabled` and `is_from_cnr`
|
||||
- `nightly_inactive_nodes` → Use `installed_node_packages` + filter by `is_disabled` and `is_nightly`
|
||||
- `unknown_active_nodes` → Use `installed_node_packages` + filter by `is_enabled` and `is_unknown`
|
||||
- `unknown_inactive_nodes` → Use `installed_node_packages` + filter by `is_disabled` and `is_unknown`
|
||||
|
||||
---
|
||||
|
||||
## 🔄 Data Migration Examples
|
||||
|
||||
### Show Enabled Packages
|
||||
```python
|
||||
def show_enabled_packages():
|
||||
enabled_packages = []
|
||||
|
||||
# Collect enabled packages
|
||||
for packages in unified_manager.installed_node_packages.values():
|
||||
for pack in packages:
|
||||
if pack.is_enabled:
|
||||
enabled_packages.append(pack)
|
||||
|
||||
# Display with CNR info
|
||||
for pack in enabled_packages:
|
||||
if pack.is_from_cnr:
|
||||
cnr_info = cnr_utils.get_nodepack(pack.id)
|
||||
publisher = cnr_info.get('publisher', {}).get('name', 'Unknown') if cnr_info else 'Unknown'
|
||||
print(f"[ ENABLED ] {pack.id:50} (author: {publisher}) [{pack.version}]")
|
||||
elif pack.is_nightly:
|
||||
print(f"[ ENABLED ] {pack.id:50} (nightly) [NIGHTLY]")
|
||||
else:
|
||||
print(f"[ ENABLED ] {pack.id:50} (unknown) [UNKNOWN]")
|
||||
```
|
||||
|
||||
### Show Not-Installed Packages
|
||||
```python
|
||||
def show_not_installed_packages():
|
||||
# Get installed package IDs
|
||||
installed_ids = set()
|
||||
for packages in unified_manager.installed_node_packages.values():
|
||||
for pack in packages:
|
||||
installed_ids.add(pack.id)
|
||||
|
||||
# Get all CNR packages
|
||||
all_cnr = cnr_utils.get_all_nodepackages()
|
||||
|
||||
# Show not-installed
|
||||
for pack_id, pack_info in all_cnr.items():
|
||||
if pack_id not in installed_ids:
|
||||
publisher = pack_info.get('publisher', {}).get('name', 'Unknown')
|
||||
latest_version = pack_info.get('latest_version', {}).get('version', '0.0.0')
|
||||
print(f"[ NOT INSTALLED ] {pack_info['name']:50} {pack_id:30} (author: {publisher}) [{latest_version}]")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ Key Constraints
|
||||
|
||||
1. **NO MODIFICATIONS**: Do not add any functions or properties to glob module
|
||||
2. **USE EXISTING APIs**: Only use the functions and classes documented above
|
||||
3. **ADAPT CLI**: CLI must adapt to glob's data structures and patterns
|
||||
4. **REMOVE IF NEEDED**: Remove features that can't be implemented with available APIs
|
||||
|
||||
This reference should provide everything needed to implement the CLI migration using only existing glob APIs.
|
||||
324
docs/internal/cli_migration/CLI_IMPLEMENTATION_CHECKLIST.md
Normal file
324
docs/internal/cli_migration/CLI_IMPLEMENTATION_CHECKLIST.md
Normal file
@@ -0,0 +1,324 @@
|
||||
# CLI Glob Migration - Implementation Todo List
|
||||
|
||||
## 📅 Project Timeline: 3.5 Days
|
||||
|
||||
---
|
||||
|
||||
# 🚀 Phase 1: Initial Setup & Import Changes (0.5 day)
|
||||
|
||||
## Day 1 Morning
|
||||
|
||||
### ✅ Setup and Preparation (30 min)
|
||||
- [ ] Read implementation context file
|
||||
- [ ] Review glob APIs documentation
|
||||
- [ ] Set up development environment
|
||||
- [ ] Create backup of current CLI
|
||||
|
||||
### 🔄 Import Path Changes (1 hour)
|
||||
- [ ] **CRITICAL**: Update import statements in `cm_cli/__main__.py:39-41`
|
||||
```python
|
||||
# Change from:
|
||||
from ..legacy import manager_core as core
|
||||
from ..legacy.manager_core import unified_manager
|
||||
|
||||
# Change to:
|
||||
from ..glob import manager_core as core
|
||||
from ..glob.manager_core import unified_manager
|
||||
```
|
||||
- [ ] Test CLI loads without crashing
|
||||
- [ ] Identify immediate import-related errors
|
||||
|
||||
### 🧪 Initial Testing (30 min)
|
||||
- [ ] Test basic CLI help: `python -m comfyui_manager.cm_cli help`
|
||||
- [ ] Test simple commands that should work: `python -m comfyui_manager.cm_cli show snapshot`
|
||||
- [ ] Document all errors found
|
||||
- [ ] Prioritize fixes needed
|
||||
|
||||
---
|
||||
|
||||
# ⚙️ Phase 2: Core Function Implementation (2 days)
|
||||
|
||||
## Day 1 Afternoon + Day 2
|
||||
|
||||
### 🛠️ install_node() Function Update (3 hours)
|
||||
**File**: `cm_cli/__main__.py:187-235`
|
||||
**Complexity**: Medium
|
||||
|
||||
#### Tasks:
|
||||
- [ ] **Replace Git URL handling logic**
|
||||
```python
|
||||
# OLD (line ~191):
|
||||
if core.is_valid_url(node_spec_str):
|
||||
res = asyncio.run(core.gitclone_install(node_spec_str, no_deps=cmd_ctx.no_deps))
|
||||
|
||||
# NEW:
|
||||
if unified_manager.is_url_like(node_spec_str):
|
||||
repo_name = os.path.basename(node_spec_str)
|
||||
if repo_name.endswith('.git'):
|
||||
repo_name = repo_name[:-4]
|
||||
res = asyncio.run(unified_manager.repo_install(
|
||||
node_spec_str, repo_name, instant_execution=True, no_deps=cmd_ctx.no_deps
|
||||
))
|
||||
```
|
||||
- [ ] Test Git URL installation
|
||||
- [ ] Test CNR package installation
|
||||
- [ ] Verify error handling works correctly
|
||||
- [ ] Update progress messages if needed
|
||||
|
||||
### 🔍 show_list() Function Rewrite - Installed-Only Approach (3 hours)
|
||||
**File**: `cm_cli/__main__.py:418-534`
|
||||
**Complexity**: High - Complete architectural change
|
||||
**New Approach**: Show only installed nodepacks with on-demand info retrieval
|
||||
|
||||
#### Key Changes:
|
||||
- ❌ Remove: Full cache loading (`get_custom_nodes()`)
|
||||
- ❌ Remove: Support for `show all`, `show not-installed`, `show cnr`
|
||||
- ✅ Add: Lightweight caching system for nodepack metadata
|
||||
- ✅ Add: On-demand CNR API calls for additional info
|
||||
|
||||
#### Tasks:
|
||||
- [ ] **Phase 2A: Lightweight Cache Implementation (1 hour)**
|
||||
```python
|
||||
class NodePackageCache:
|
||||
def __init__(self, cache_file_path: str):
|
||||
self.cache_file = cache_file_path
|
||||
self.cache_data = self._load_cache()
|
||||
|
||||
def get_metadata(self, nodepack_id: str) -> dict:
|
||||
# Get cached metadata or fetch on-demand from CNR
|
||||
|
||||
def update_metadata(self, nodepack_id: str, metadata: dict):
|
||||
# Update cache (called during install)
|
||||
```
|
||||
|
||||
- [ ] **Phase 2B: New show_list Implementation (1.5 hours)**
|
||||
```python
|
||||
def show_list(kind, simple=False):
|
||||
# Validate supported commands
|
||||
if kind not in ['installed', 'enabled', 'disabled']:
|
||||
print(f"Unsupported: 'show {kind}'. Use: installed/enabled/disabled")
|
||||
return
|
||||
|
||||
# Get installed packages only
|
||||
all_packages = []
|
||||
for packages in unified_manager.installed_node_packages.values():
|
||||
all_packages.extend(packages)
|
||||
|
||||
# Filter by status
|
||||
if kind == 'enabled':
|
||||
packages = [pkg for pkg in all_packages if pkg.is_enabled]
|
||||
elif kind == 'disabled':
|
||||
packages = [pkg for pkg in all_packages if not pkg.is_enabled]
|
||||
else: # 'installed'
|
||||
packages = all_packages
|
||||
```
|
||||
|
||||
- [ ] **Phase 2C: On-Demand Display with Cache (0.5 hour)**
|
||||
```python
|
||||
cache = NodePackageCache(cache_file_path)
|
||||
|
||||
for package in packages:
|
||||
# Basic info from InstalledNodePackage
|
||||
status = "[ ENABLED ]" if package.is_enabled else "[ DISABLED ]"
|
||||
|
||||
# Enhanced info from cache or on-demand
|
||||
cached_info = cache.get_metadata(package.id)
|
||||
name = cached_info.get('name', package.id)
|
||||
author = cached_info.get('author', 'Unknown')
|
||||
version = cached_info.get('version', 'Unknown')
|
||||
|
||||
if simple:
|
||||
print(f"{name}@{version}")
|
||||
else:
|
||||
print(f"{status} {name:50} {package.id:30} (author: {author:20}) [{version}]")
|
||||
```
|
||||
|
||||
#### Install-time Cache Update:
|
||||
- [ ] **Update install_node() to populate cache**
|
||||
```python
|
||||
# After successful installation in install_node()
|
||||
if install_success:
|
||||
metadata = cnr_utils.get_nodepackage_info(installed_package.id)
|
||||
cache.update_metadata(installed_package.id, metadata)
|
||||
```
|
||||
|
||||
#### Testing:
|
||||
- [ ] Test `show installed` (enabled + disabled packages)
|
||||
- [ ] Test `show enabled` (only enabled packages)
|
||||
- [ ] Test `show disabled` (only disabled packages)
|
||||
- [ ] Test unsupported commands show helpful error
|
||||
- [ ] Test `simple-show` variants work correctly
|
||||
- [ ] Test cache functionality (create, read, update)
|
||||
- [ ] Test on-demand CNR info retrieval for cache misses
|
||||
|
||||
### 📝 get_all_installed_node_specs() Update (1 hour)
|
||||
**File**: `cm_cli/__main__.py:573-605`
|
||||
**Complexity**: Medium
|
||||
|
||||
#### Tasks:
|
||||
- [ ] **Rewrite using InstalledNodePackage**
|
||||
```python
|
||||
def get_all_installed_node_specs():
|
||||
res = []
|
||||
for packages in unified_manager.installed_node_packages.values():
|
||||
for pack in packages:
|
||||
node_spec_str = f"{pack.id}@{pack.version}"
|
||||
res.append(node_spec_str)
|
||||
return res
|
||||
```
|
||||
- [ ] Test with `update all` command
|
||||
- [ ] Verify node spec format is correct
|
||||
|
||||
### ⚙️ Context Management Updates (1 hour)
|
||||
**File**: `cm_cli/__main__.py:117-134`
|
||||
**Complexity**: Low
|
||||
|
||||
#### Tasks:
|
||||
- [ ] **Remove load_nightly() call**
|
||||
```python
|
||||
def set_channel_mode(self, channel, mode):
|
||||
if mode is not None:
|
||||
self.mode = mode
|
||||
if channel is not None:
|
||||
self.channel = channel
|
||||
|
||||
# OLD: asyncio.run(unified_manager.reload(...))
|
||||
# OLD: asyncio.run(unified_manager.load_nightly(...))
|
||||
|
||||
# NEW: Just reload
|
||||
unified_manager.reload()
|
||||
```
|
||||
- [ ] Test channel/mode switching still works
|
||||
|
||||
---
|
||||
|
||||
# 🧹 Phase 3: Feature Removal & Final Testing (1 day)
|
||||
|
||||
## Day 3
|
||||
|
||||
### ❌ Remove Unavailable Features (2 hours)
|
||||
**Complexity**: Low
|
||||
|
||||
#### deps-in-workflow Command Removal:
|
||||
- [ ] **Update deps_in_workflow() function** (`cm_cli/__main__.py:1000-1050`)
|
||||
```python
|
||||
@app.command("deps-in-workflow")
|
||||
def deps_in_workflow(...):
|
||||
print("[bold red]ERROR: This feature is not available in the current version.[/bold red]")
|
||||
print("The 'deps-in-workflow' feature has been removed.")
|
||||
print("Please use alternative workflow analysis tools.")
|
||||
sys.exit(1)
|
||||
```
|
||||
- [ ] Test command shows proper error message
|
||||
- [ ] Update help text to reflect removal
|
||||
|
||||
#### install-deps Command Update:
|
||||
- [ ] **Update install_deps() function** (`cm_cli/__main__.py:1203-1250`)
|
||||
```python
|
||||
# Remove extract_nodes_from_workflow usage (line ~1033)
|
||||
# Replace with error handling or alternative approach
|
||||
```
|
||||
- [ ] Test with dependency files
|
||||
|
||||
### 🧪 Comprehensive Testing (4 hours)
|
||||
|
||||
#### Core Command Testing (2 hours):
|
||||
- [ ] **Install Commands**:
|
||||
- [ ] `install <cnr-package>`
|
||||
- [ ] `install <git-url>`
|
||||
- [ ] `install all` (if applicable)
|
||||
|
||||
- [ ] **Uninstall Commands**:
|
||||
- [ ] `uninstall <package>`
|
||||
- [ ] `uninstall all`
|
||||
|
||||
- [ ] **Enable/Disable Commands**:
|
||||
- [ ] `enable <package>`
|
||||
- [ ] `disable <package>`
|
||||
- [ ] `enable all` / `disable all`
|
||||
|
||||
- [ ] **Update Commands**:
|
||||
- [ ] `update <package>`
|
||||
- [ ] `update all`
|
||||
|
||||
#### Show Commands Testing (1 hour):
|
||||
- [ ] `show installed`
|
||||
- [ ] `show enabled`
|
||||
- [ ] `show disabled`
|
||||
- [ ] `show all`
|
||||
- [ ] `show not-installed`
|
||||
- [ ] `simple-show` variants
|
||||
|
||||
#### Advanced Features Testing (1 hour):
|
||||
- [ ] `save-snapshot`
|
||||
- [ ] `restore-snapshot`
|
||||
- [ ] `show snapshot`
|
||||
- [ ] `show snapshot-list`
|
||||
- [ ] `clear`
|
||||
- [ ] `cli-only-mode`
|
||||
|
||||
### 🐛 Bug Fixes & Polish (2 hours)
|
||||
- [ ] Fix any errors found during testing
|
||||
- [ ] Improve error messages
|
||||
- [ ] Ensure output formatting consistency
|
||||
- [ ] Performance optimization if needed
|
||||
- [ ] Code cleanup and comments
|
||||
|
||||
---
|
||||
|
||||
# 📋 Daily Checklists
|
||||
|
||||
## End of Day 1 Checklist:
|
||||
- [ ] Imports successfully changed
|
||||
- [ ] Basic CLI loading works
|
||||
- [ ] install_node() handles both CNR and Git URLs
|
||||
- [ ] No critical crashes in core functions
|
||||
|
||||
## End of Day 2 Checklist:
|
||||
- [ ] show_list() displays all package types correctly
|
||||
- [ ] get_all_installed_node_specs() works with new data structure
|
||||
- [ ] Context management updated
|
||||
- [ ] Core functionality regression-free
|
||||
|
||||
## End of Day 3 Checklist:
|
||||
- [ ] All CLI commands tested and working
|
||||
- [ ] Removed features show appropriate messages
|
||||
- [ ] Output format acceptable to users
|
||||
- [ ] No glob module modifications made
|
||||
- [ ] Ready for code review
|
||||
|
||||
---
|
||||
|
||||
# 🎯 Success Criteria
|
||||
|
||||
## Must Pass:
|
||||
- [ ] All core commands functional (install/uninstall/enable/disable/update)
|
||||
- [ ] show commands display accurate information
|
||||
- [ ] No modifications to glob module
|
||||
- [ ] CLI code changes < 200 lines
|
||||
- [ ] No critical regressions
|
||||
|
||||
## Bonus Points:
|
||||
- [ ] Output format matches legacy closely
|
||||
- [ ] Performance equals or exceeds legacy
|
||||
- [ ] Error messages user-friendly
|
||||
- [ ] Code is clean and maintainable
|
||||
|
||||
---
|
||||
|
||||
# 🚨 Emergency Contacts & Resources
|
||||
|
||||
## If Stuck:
|
||||
1. **Review**: `CLI_PURE_GLOB_MIGRATION_PLAN.md` for detailed technical specs
|
||||
2. **Reference**: `CLI_IMPLEMENTATION_CONTEXT.md` for current state
|
||||
3. **Debug**: Use `print()` statements to understand data structures
|
||||
4. **Fallback**: Implement minimal working version first, polish later
|
||||
|
||||
## Key Files to Reference:
|
||||
- `comfyui_manager/glob/manager_core.py` - UnifiedManager APIs
|
||||
- `comfyui_manager/common/node_package.py` - InstalledNodePackage class
|
||||
- `comfyui_manager/common/cnr_utils.py` - CNR utilities
|
||||
|
||||
---
|
||||
|
||||
**Remember**: Focus on making it work first, then making it perfect. The constraint is NO glob modifications - CLI must adapt to glob's way of doing things.
|
||||
424
docs/internal/cli_migration/CLI_MIGRATION_GUIDE.md
Normal file
424
docs/internal/cli_migration/CLI_MIGRATION_GUIDE.md
Normal file
@@ -0,0 +1,424 @@
|
||||
# CLI Migration Guide: Legacy to Glob Module
|
||||
|
||||
**Status**: ✅ Completed (Historical Reference)
|
||||
**Last Updated**: 2025-08-30
|
||||
**Purpose**: Complete guide for migrating ComfyUI Manager CLI from legacy to glob module
|
||||
|
||||
---
|
||||
|
||||
## 📋 Table of Contents
|
||||
|
||||
1. [Overview](#overview)
|
||||
2. [Legacy vs Glob Comparison](#legacy-vs-glob-comparison)
|
||||
3. [Migration Strategy](#migration-strategy)
|
||||
4. [Implementation Details](#implementation-details)
|
||||
5. [Key Constraints](#key-constraints)
|
||||
6. [API Reference](#api-reference-quick)
|
||||
7. [Rollback Plan](#rollback-plan)
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
### Objective
|
||||
Migrate ComfyUI Manager CLI from legacy module to glob module using **only existing glob APIs** without modifying the glob module itself.
|
||||
|
||||
### Scope
|
||||
- **Target File**: `comfyui_manager/cm_cli/__main__.py` (1305 lines)
|
||||
- **Timeline**: 3.5 days
|
||||
- **Approach**: Minimal CLI changes, maximum compatibility
|
||||
- **Constraint**: ❌ NO glob module modifications
|
||||
|
||||
### Current State
|
||||
```python
|
||||
# Current imports (Lines 39-41)
|
||||
from ..legacy import manager_core as core
|
||||
from ..legacy.manager_core import unified_manager
|
||||
|
||||
# Target imports
|
||||
from ..glob import manager_core as core
|
||||
from ..glob.manager_core import unified_manager
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Legacy vs Glob Comparison
|
||||
|
||||
### Core Architecture Differences
|
||||
|
||||
#### Legacy Module (Current)
|
||||
**Data Structure**: Dictionary-based global state
|
||||
```python
|
||||
unified_manager.active_nodes # Active nodes dict
|
||||
unified_manager.unknown_active_nodes # Unknown active nodes
|
||||
unified_manager.cnr_inactive_nodes # Inactive CNR nodes
|
||||
unified_manager.nightly_inactive_nodes # Inactive nightly nodes
|
||||
unified_manager.unknown_inactive_nodes # Unknown inactive nodes
|
||||
unified_manager.cnr_map # CNR info mapping
|
||||
```
|
||||
|
||||
#### Glob Module (Target)
|
||||
**Data Structure**: Object-oriented with InstalledNodePackage
|
||||
```python
|
||||
unified_manager.installed_node_packages # dict[str, list[InstalledNodePackage]]
|
||||
unified_manager.repo_nodepack_map # dict[str, InstalledNodePackage]
|
||||
```
|
||||
|
||||
### Method Compatibility Matrix
|
||||
|
||||
| Method | Legacy | Glob | Status | Action |
|
||||
|--------|--------|------|--------|--------|
|
||||
| `unified_enable()` | ✅ | ✅ | Compatible | Direct mapping |
|
||||
| `unified_disable()` | ✅ | ✅ | Compatible | Direct mapping |
|
||||
| `unified_uninstall()` | ✅ | ✅ | Compatible | Direct mapping |
|
||||
| `unified_update()` | ✅ | ✅ | Compatible | Direct mapping |
|
||||
| `install_by_id()` | Sync | Async | Modified | Use asyncio.run() |
|
||||
| `gitclone_install()` | ✅ | ❌ | Replaced | Use repo_install() |
|
||||
| `get_custom_nodes()` | ✅ | ❌ | Removed | Use cnr_utils |
|
||||
| `load_nightly()` | ✅ | ❌ | Removed | Not needed |
|
||||
| `extract_nodes_from_workflow()` | ✅ | ❌ | Removed | Feature removed |
|
||||
|
||||
### InstalledNodePackage Class
|
||||
|
||||
```python
|
||||
@dataclass
|
||||
class InstalledNodePackage:
|
||||
id: str # Package identifier
|
||||
fullpath: str # Full filesystem path
|
||||
disabled: bool # Disabled status
|
||||
version: str # Version (nightly/unknown/x.y.z)
|
||||
repo_url: str = None # Repository URL
|
||||
|
||||
# Properties
|
||||
@property
|
||||
def is_unknown(self) -> bool: return self.version == "unknown"
|
||||
|
||||
@property
|
||||
def is_nightly(self) -> bool: return self.version == "nightly"
|
||||
|
||||
@property
|
||||
def is_from_cnr(self) -> bool: return not (self.is_unknown or self.is_nightly)
|
||||
|
||||
@property
|
||||
def is_enabled(self) -> bool: return not self.disabled
|
||||
|
||||
@property
|
||||
def is_disabled(self) -> bool: return self.disabled
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Migration Strategy
|
||||
|
||||
### Phase 1: Setup (0.5 day)
|
||||
**Goal**: Basic migration with error identification
|
||||
|
||||
1. **Import Path Changes**
|
||||
```python
|
||||
# Change 2 lines
|
||||
from ..glob import manager_core as core
|
||||
from ..glob.manager_core import unified_manager
|
||||
```
|
||||
|
||||
2. **Initial Testing**
|
||||
- Run basic commands
|
||||
- Identify breaking changes
|
||||
- Document errors
|
||||
|
||||
3. **Error Analysis**
|
||||
- List all affected functions
|
||||
- Categorize by priority
|
||||
- Plan fixes
|
||||
|
||||
### Phase 2: Core Implementation (2 days)
|
||||
**Goal**: Adapt CLI to glob architecture
|
||||
|
||||
1. **install_node() Updates**
|
||||
```python
|
||||
# Replace gitclone_install with repo_install
|
||||
if unified_manager.is_url_like(node_spec_str):
|
||||
res = asyncio.run(unified_manager.repo_install(
|
||||
node_spec_str,
|
||||
os.path.basename(node_spec_str),
|
||||
instant_execution=True,
|
||||
no_deps=cmd_ctx.no_deps
|
||||
))
|
||||
```
|
||||
|
||||
2. **show_list() Rewrite** (Most complex change)
|
||||
- Migrate from dictionary-based to InstalledNodePackage-based
|
||||
- Implement installed-only approach with optional CNR lookup
|
||||
- See [show_list() Implementation](#show_list-implementation) section
|
||||
|
||||
3. **Context Management**
|
||||
- Update get_all_installed_node_specs()
|
||||
- Adapt to new data structures
|
||||
|
||||
4. **Data Structure Migration**
|
||||
- Replace all active_nodes references
|
||||
- Use installed_node_packages instead
|
||||
|
||||
### Phase 3: Final Testing (1 day)
|
||||
**Goal**: Comprehensive validation
|
||||
|
||||
1. **Feature Removal**
|
||||
- Remove deps-in-workflow (not supported)
|
||||
- Stub unsupported features
|
||||
|
||||
2. **Testing**
|
||||
- Test all CLI commands
|
||||
- Verify output format
|
||||
- Check edge cases
|
||||
|
||||
3. **Polish**
|
||||
- Fix bugs
|
||||
- Improve error messages
|
||||
- Update help text
|
||||
|
||||
---
|
||||
|
||||
## Implementation Details
|
||||
|
||||
### show_list() Implementation
|
||||
|
||||
**Challenge**: Legacy uses multiple dictionaries, glob uses single InstalledNodePackage collection
|
||||
|
||||
**Solution**: Installed-only approach with on-demand CNR lookup
|
||||
|
||||
```python
|
||||
def show_list(kind: str, simple: bool = False):
|
||||
"""
|
||||
Display node package list
|
||||
|
||||
Args:
|
||||
kind: 'installed', 'enabled', 'disabled', 'all'
|
||||
simple: If True, show simple format
|
||||
"""
|
||||
|
||||
# Get all installed packages
|
||||
all_packages = []
|
||||
for packages in unified_manager.installed_node_packages.values():
|
||||
all_packages.extend(packages)
|
||||
|
||||
# Filter by kind
|
||||
if kind == "enabled":
|
||||
packages = [p for p in all_packages if p.is_enabled]
|
||||
elif kind == "disabled":
|
||||
packages = [p for p in all_packages if p.is_disabled]
|
||||
elif kind == "installed" or kind == "all":
|
||||
packages = all_packages
|
||||
else:
|
||||
print(f"Unknown kind: {kind}")
|
||||
return
|
||||
|
||||
# Display
|
||||
if simple:
|
||||
for pkg in packages:
|
||||
print(pkg.id)
|
||||
else:
|
||||
# Detailed display with CNR info on-demand
|
||||
for pkg in packages:
|
||||
status = "disabled" if pkg.disabled else "enabled"
|
||||
version_info = f"v{pkg.version}" if pkg.version != "unknown" else "unknown"
|
||||
|
||||
print(f"[{status}] {pkg.id} ({version_info})")
|
||||
|
||||
# Optionally fetch CNR info for non-nightly packages
|
||||
if pkg.is_from_cnr and not simple:
|
||||
cnr_info = cnr_utils.get_nodepackage(pkg.id)
|
||||
if cnr_info:
|
||||
print(f" Description: {cnr_info.get('description', 'N/A')}")
|
||||
```
|
||||
|
||||
**Key Changes**:
|
||||
1. Single source of truth: `installed_node_packages`
|
||||
2. No separate active/inactive dictionaries
|
||||
3. On-demand CNR lookup instead of pre-cached cnr_map
|
||||
4. Filter by InstalledNodePackage properties
|
||||
|
||||
### Git Installation Migration
|
||||
|
||||
**Before (Legacy)**:
|
||||
```python
|
||||
if core.is_valid_url(node_spec_str):
|
||||
res = asyncio.run(core.gitclone_install(
|
||||
node_spec_str,
|
||||
no_deps=cmd_ctx.no_deps
|
||||
))
|
||||
```
|
||||
|
||||
**After (Glob)**:
|
||||
```python
|
||||
if unified_manager.is_url_like(node_spec_str):
|
||||
res = asyncio.run(unified_manager.repo_install(
|
||||
node_spec_str,
|
||||
os.path.basename(node_spec_str), # repo_path derived from URL
|
||||
instant_execution=True, # Execute immediately
|
||||
no_deps=cmd_ctx.no_deps # Respect --no-deps flag
|
||||
))
|
||||
```
|
||||
|
||||
### Async Function Handling
|
||||
|
||||
**Pattern**: Wrap async glob methods with asyncio.run()
|
||||
|
||||
```python
|
||||
# install_by_id is async in glob
|
||||
res = asyncio.run(unified_manager.install_by_id(
|
||||
packname=node_name,
|
||||
version_spec=version,
|
||||
instant_execution=True,
|
||||
no_deps=cmd_ctx.no_deps
|
||||
))
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Key Constraints
|
||||
|
||||
### Hard Constraints (Cannot Change)
|
||||
1. ❌ **No glob module modifications**
|
||||
- Cannot add new methods to UnifiedManager
|
||||
- Cannot add compatibility properties
|
||||
- Must use existing APIs only
|
||||
|
||||
2. ❌ **No legacy dependencies**
|
||||
- CLI must work without legacy module
|
||||
- Clean break from old architecture
|
||||
|
||||
3. ❌ **Maintain CLI interface**
|
||||
- Command syntax unchanged
|
||||
- Output format similar (minor differences acceptable)
|
||||
|
||||
### Soft Constraints (Acceptable Trade-offs)
|
||||
1. ✅ **Feature removal acceptable**
|
||||
- deps-in-workflow feature can be removed
|
||||
- Channel/mode support can be simplified
|
||||
|
||||
2. ✅ **Performance trade-offs acceptable**
|
||||
- On-demand CNR lookup vs pre-cached
|
||||
- Slight performance degradation acceptable
|
||||
|
||||
3. ✅ **Output format flexibility**
|
||||
- Minor formatting differences acceptable
|
||||
- Must remain readable and useful
|
||||
|
||||
---
|
||||
|
||||
## API Reference (Quick)
|
||||
|
||||
### UnifiedManager Core Methods
|
||||
|
||||
```python
|
||||
# Installation
|
||||
async def install_by_id(packname, version_spec, instant_execution, no_deps) -> ManagedResult
|
||||
|
||||
# Git/URL installation
|
||||
async def repo_install(url, repo_path, instant_execution, no_deps) -> ManagedResult
|
||||
|
||||
# Enable/Disable
|
||||
def unified_enable(packname, version_spec=None) -> ManagedResult
|
||||
def unified_disable(packname) -> ManagedResult
|
||||
|
||||
# Update/Uninstall
|
||||
def unified_update(packname, instant_execution, no_deps) -> ManagedResult
|
||||
def unified_uninstall(packname) -> ManagedResult
|
||||
|
||||
# Query
|
||||
def get_active_pack(packname) -> InstalledNodePackage | None
|
||||
def get_inactive_pack(packname, version_spec) -> InstalledNodePackage | None
|
||||
def resolve_node_spec(packname, guess_mode) -> NodeSpec
|
||||
|
||||
# Utility
|
||||
def is_url_like(text) -> bool
|
||||
```
|
||||
|
||||
### Data Access
|
||||
|
||||
```python
|
||||
# Installed packages
|
||||
unified_manager.installed_node_packages: dict[str, list[InstalledNodePackage]]
|
||||
|
||||
# Repository mapping
|
||||
unified_manager.repo_nodepack_map: dict[str, InstalledNodePackage]
|
||||
```
|
||||
|
||||
### External Utilities
|
||||
|
||||
```python
|
||||
# CNR utilities
|
||||
from ..common import cnr_utils
|
||||
cnr_utils.get_nodepackage(id) -> dict
|
||||
cnr_utils.get_all_nodepackages() -> list[dict]
|
||||
```
|
||||
|
||||
For complete API reference, see [CLI_API_REFERENCE.md](CLI_API_REFERENCE.md)
|
||||
|
||||
---
|
||||
|
||||
## Rollback Plan
|
||||
|
||||
### If Migration Fails
|
||||
|
||||
1. **Immediate Rollback** (< 5 minutes)
|
||||
```python
|
||||
# Revert imports in __main__.py
|
||||
from ..legacy import manager_core as core
|
||||
from ..legacy.manager_core import unified_manager
|
||||
```
|
||||
|
||||
2. **Verify Rollback**
|
||||
```bash
|
||||
# Test basic commands
|
||||
cm-cli show installed
|
||||
cm-cli install <package>
|
||||
```
|
||||
|
||||
3. **Document Issues**
|
||||
- Note what failed
|
||||
- Gather error logs
|
||||
- Plan fixes
|
||||
|
||||
### Risk Mitigation
|
||||
|
||||
1. **Backup**: Keep legacy module available
|
||||
2. **Testing**: Comprehensive test suite before deployment
|
||||
3. **Staging**: Test in non-production environment first
|
||||
4. **Monitoring**: Watch for errors after deployment
|
||||
|
||||
---
|
||||
|
||||
## Success Criteria
|
||||
|
||||
### Must Pass (Blockers)
|
||||
- ✅ All core commands functional (install, update, enable, disable, uninstall)
|
||||
- ✅ Package information displays correctly
|
||||
- ✅ No glob module modifications
|
||||
- ✅ No critical regressions
|
||||
|
||||
### Should Pass (Important)
|
||||
- ✅ Output format similar to legacy
|
||||
- ✅ Performance comparable to legacy
|
||||
- ✅ User-friendly error messages
|
||||
- ✅ Help text updated
|
||||
|
||||
### Nice to Have
|
||||
- ✅ Improved code structure
|
||||
- ✅ Better error handling
|
||||
- ✅ Type hints added
|
||||
|
||||
---
|
||||
|
||||
## Reference Documents
|
||||
|
||||
- **[CLI_API_REFERENCE.md](CLI_API_REFERENCE.md)** - Complete API documentation
|
||||
- **[CLI_IMPLEMENTATION_CHECKLIST.md](CLI_IMPLEMENTATION_CHECKLIST.md)** - Step-by-step tasks
|
||||
- **[CLI_TESTING_GUIDE.md](CLI_TESTING_GUIDE.md)** - Testing strategy
|
||||
|
||||
---
|
||||
|
||||
## Conclusion
|
||||
|
||||
The CLI migration from legacy to glob module is achievable through systematic adaptation of CLI code to glob's object-oriented architecture. The key is respecting the constraint of no glob modifications while leveraging existing glob APIs effectively.
|
||||
|
||||
**Status**: This migration has been completed successfully. The CLI now uses glob module exclusively.
|
||||
407
docs/internal/cli_migration/CLI_TESTING_GUIDE.md
Normal file
407
docs/internal/cli_migration/CLI_TESTING_GUIDE.md
Normal file
@@ -0,0 +1,407 @@
|
||||
# CLI Migration Testing Checklist
|
||||
|
||||
## 🧪 Testing Strategy Overview
|
||||
**Approach**: Progressive testing at each implementation phase
|
||||
**Tools**: Manual CLI testing, comparison with legacy behavior
|
||||
**Environment**: ComfyUI development environment with test packages
|
||||
|
||||
---
|
||||
|
||||
# 📋 Phase 1 Testing (Import Changes)
|
||||
|
||||
## ✅ Basic CLI Loading (Must Pass)
|
||||
```bash
|
||||
# Test CLI loads without import errors
|
||||
python -m comfyui_manager.cm_cli --help
|
||||
python -m comfyui_manager.cm_cli help
|
||||
|
||||
# Expected: CLI help displays, no ImportError exceptions
|
||||
```
|
||||
|
||||
## ✅ Simple Command Smoke Tests
|
||||
```bash
|
||||
# Commands that should work immediately
|
||||
python -m comfyui_manager.cm_cli show snapshot
|
||||
python -m comfyui_manager.cm_cli clear
|
||||
|
||||
# Expected: Commands execute, may show different output but no crashes
|
||||
```
|
||||
|
||||
## 🐛 Error Identification
|
||||
- [ ] Document all import-related errors
|
||||
- [ ] Identify which functions fail immediately
|
||||
- [ ] Note any missing attributes/methods used by CLI
|
||||
- [ ] List functions that need immediate attention
|
||||
|
||||
**Pass Criteria**: CLI loads and basic commands don't crash
|
||||
|
||||
---
|
||||
|
||||
# 🔧 Phase 2 Testing (Core Functions)
|
||||
|
||||
## 🚀 Install Command Testing
|
||||
|
||||
### CNR Package Installation
|
||||
```bash
|
||||
# Test CNR package installation
|
||||
python -m comfyui_manager.cm_cli install ComfyUI-Manager
|
||||
python -m comfyui_manager.cm_cli install <known-cnr-package>
|
||||
|
||||
# Expected behaviors:
|
||||
# - Package resolves correctly
|
||||
# - Installation proceeds
|
||||
# - Success/failure message displayed
|
||||
# - Package appears in enabled state
|
||||
```
|
||||
**Test Cases**:
|
||||
- [ ] Install new CNR package
|
||||
- [ ] Install already-installed package (should skip)
|
||||
- [ ] Install non-existent package (should error gracefully)
|
||||
- [ ] Install with `--no-deps` flag
|
||||
|
||||
### Git URL Installation
|
||||
```bash
|
||||
# Test Git URL installation
|
||||
python -m comfyui_manager.cm_cli install https://github.com/user/repo.git
|
||||
python -m comfyui_manager.cm_cli install https://github.com/user/repo
|
||||
|
||||
# Expected behaviors:
|
||||
# - URL detected as Git repository
|
||||
# - repo_install() method called
|
||||
# - Installation proceeds or fails gracefully
|
||||
```
|
||||
**Test Cases**:
|
||||
- [ ] Install from Git URL with .git suffix
|
||||
- [ ] Install from Git URL without .git suffix
|
||||
- [ ] Install from invalid Git URL (should error)
|
||||
- [ ] Install from private repository (may fail gracefully)
|
||||
|
||||
## 📊 Show Commands Testing
|
||||
|
||||
### Show Installed/Enabled
|
||||
```bash
|
||||
python -m comfyui_manager.cm_cli show installed
|
||||
python -m comfyui_manager.cm_cli show enabled
|
||||
|
||||
# Expected: List of enabled packages with:
|
||||
# - Package names
|
||||
# - Version information
|
||||
# - Author/publisher info where available
|
||||
# - Correct status indicators
|
||||
```
|
||||
|
||||
### Show Disabled/Not-Installed
|
||||
```bash
|
||||
python -m comfyui_manager.cm_cli show disabled
|
||||
python -m comfyui_manager.cm_cli show not-installed
|
||||
|
||||
# Expected: Appropriate package lists with status
|
||||
```
|
||||
|
||||
### Show All & Simple Mode
|
||||
```bash
|
||||
python -m comfyui_manager.cm_cli show all
|
||||
python -m comfyui_manager.cm_cli simple-show all
|
||||
|
||||
# Expected: Comprehensive package list
|
||||
# Simple mode should show condensed format
|
||||
```
|
||||
|
||||
**Detailed Test Matrix**:
|
||||
- [ ] `show installed` - displays all installed packages
|
||||
- [ ] `show enabled` - displays only enabled packages
|
||||
- [ ] `show disabled` - displays only disabled packages
|
||||
- [ ] `show not-installed` - displays available but not installed packages
|
||||
- [ ] `show all` - displays comprehensive list
|
||||
- [ ] `show cnr` - displays CNR packages only
|
||||
- [ ] `simple-show` variants - condensed output format
|
||||
|
||||
**Validation Criteria**:
|
||||
- [ ] Package counts make sense (enabled + disabled = installed)
|
||||
- [ ] CNR packages show publisher information
|
||||
- [ ] Nightly packages marked appropriately
|
||||
- [ ] Unknown packages handled correctly
|
||||
- [ ] No crashes with empty package sets
|
||||
|
||||
## ⚙️ Management Commands Testing
|
||||
|
||||
### Enable/Disable Commands
|
||||
```bash
|
||||
# Enable disabled package
|
||||
python -m comfyui_manager.cm_cli disable <package-name>
|
||||
python -m comfyui_manager.cm_cli show disabled # Should appear
|
||||
python -m comfyui_manager.cm_cli enable <package-name>
|
||||
python -m comfyui_manager.cm_cli show enabled # Should appear
|
||||
|
||||
# Test edge cases
|
||||
python -m comfyui_manager.cm_cli enable <already-enabled-package> # Should skip
|
||||
python -m comfyui_manager.cm_cli disable <non-existent-package> # Should error
|
||||
```
|
||||
|
||||
**Test Cases**:
|
||||
- [ ] Enable disabled package
|
||||
- [ ] Disable enabled package
|
||||
- [ ] Enable already-enabled package (skip)
|
||||
- [ ] Disable already-disabled package (skip)
|
||||
- [ ] Enable non-existent package (error)
|
||||
- [ ] Disable non-existent package (error)
|
||||
|
||||
### Uninstall Commands
|
||||
```bash
|
||||
# Uninstall package
|
||||
python -m comfyui_manager.cm_cli uninstall <test-package>
|
||||
python -m comfyui_manager.cm_cli show installed # Should not appear
|
||||
|
||||
# Test variations
|
||||
python -m comfyui_manager.cm_cli uninstall <package>@unknown
|
||||
```
|
||||
|
||||
**Test Cases**:
|
||||
- [ ] Uninstall CNR package
|
||||
- [ ] Uninstall nightly package
|
||||
- [ ] Uninstall unknown package
|
||||
- [ ] Uninstall non-existent package (should error gracefully)
|
||||
|
||||
### Update Commands
|
||||
```bash
|
||||
# Update specific package
|
||||
python -m comfyui_manager.cm_cli update <package-name>
|
||||
|
||||
# Update all packages
|
||||
python -m comfyui_manager.cm_cli update all
|
||||
```
|
||||
|
||||
**Test Cases**:
|
||||
- [ ] Update single package
|
||||
- [ ] Update all packages
|
||||
- [ ] Update non-existent package (should error)
|
||||
- [ ] Update already up-to-date package (should skip)
|
||||
|
||||
## 🗃️ Advanced Function Testing
|
||||
|
||||
### get_all_installed_node_specs()
|
||||
```bash
|
||||
# This function is used internally by update/enable/disable "all" commands
|
||||
python -m comfyui_manager.cm_cli update all
|
||||
python -m comfyui_manager.cm_cli enable all
|
||||
python -m comfyui_manager.cm_cli disable all
|
||||
|
||||
# Expected: Commands process all installed packages
|
||||
```
|
||||
|
||||
**Validation**:
|
||||
- [ ] "all" commands process expected number of packages
|
||||
- [ ] Package specs format correctly (name@version)
|
||||
- [ ] No duplicates in package list
|
||||
- [ ] All package types included (CNR, nightly, unknown)
|
||||
|
||||
---
|
||||
|
||||
# 🧹 Phase 3 Testing (Feature Removal & Polish)
|
||||
|
||||
## ❌ Removed Feature Testing
|
||||
|
||||
### deps-in-workflow Command
|
||||
```bash
|
||||
python -m comfyui_manager.cm_cli deps-in-workflow workflow.json deps.json
|
||||
|
||||
# Expected: Clear error message explaining feature removal
|
||||
# Should NOT crash or show confusing errors
|
||||
```
|
||||
|
||||
### install-deps Command (if affected)
|
||||
```bash
|
||||
python -m comfyui_manager.cm_cli install-deps deps.json
|
||||
|
||||
# Expected: Either works with alternative implementation or shows clear error
|
||||
```
|
||||
|
||||
**Validation**:
|
||||
- [ ] Error messages are user-friendly
|
||||
- [ ] No stack traces for removed features
|
||||
- [ ] Help text updated to reflect changes
|
||||
- [ ] Alternative solutions mentioned where applicable
|
||||
|
||||
## 📸 Snapshot Functionality
|
||||
|
||||
### Save/Restore Snapshots
|
||||
```bash
|
||||
# Save snapshot
|
||||
python -m comfyui_manager.cm_cli save-snapshot test-snapshot.json
|
||||
ls snapshots/ # Should show new snapshot
|
||||
|
||||
# Restore snapshot
|
||||
python -m comfyui_manager.cm_cli restore-snapshot test-snapshot.json
|
||||
```
|
||||
|
||||
**Test Cases**:
|
||||
- [ ] Save snapshot to default location
|
||||
- [ ] Save snapshot to custom path
|
||||
- [ ] Restore snapshot successfully
|
||||
- [ ] Handle invalid snapshot files gracefully
|
||||
|
||||
### Snapshot Display
|
||||
```bash
|
||||
python -m comfyui_manager.cm_cli show snapshot
|
||||
python -m comfyui_manager.cm_cli show snapshot-list
|
||||
```
|
||||
|
||||
**Validation**:
|
||||
- [ ] Current state displayed correctly
|
||||
- [ ] Snapshot list shows available snapshots
|
||||
- [ ] JSON format valid and readable
|
||||
|
||||
---
|
||||
|
||||
# 🎯 Comprehensive Integration Testing
|
||||
|
||||
## 🔄 End-to-End Workflows
|
||||
|
||||
### Complete Package Lifecycle
|
||||
```bash
|
||||
# 1. Install package
|
||||
python -m comfyui_manager.cm_cli install <test-package>
|
||||
|
||||
# 2. Verify installation
|
||||
python -m comfyui_manager.cm_cli show enabled | grep <test-package>
|
||||
|
||||
# 3. Disable package
|
||||
python -m comfyui_manager.cm_cli disable <test-package>
|
||||
|
||||
# 4. Verify disabled
|
||||
python -m comfyui_manager.cm_cli show disabled | grep <test-package>
|
||||
|
||||
# 5. Re-enable package
|
||||
python -m comfyui_manager.cm_cli enable <test-package>
|
||||
|
||||
# 6. Update package
|
||||
python -m comfyui_manager.cm_cli update <test-package>
|
||||
|
||||
# 7. Uninstall package
|
||||
python -m comfyui_manager.cm_cli uninstall <test-package>
|
||||
|
||||
# 8. Verify removal
|
||||
python -m comfyui_manager.cm_cli show installed | grep <test-package> # Should be empty
|
||||
```
|
||||
|
||||
### Batch Operations
|
||||
```bash
|
||||
# Install multiple packages
|
||||
python -m comfyui_manager.cm_cli install package1 package2 package3
|
||||
|
||||
# Disable all packages
|
||||
python -m comfyui_manager.cm_cli disable all
|
||||
|
||||
# Enable all packages
|
||||
python -m comfyui_manager.cm_cli enable all
|
||||
|
||||
# Update all packages
|
||||
python -m comfyui_manager.cm_cli update all
|
||||
```
|
||||
|
||||
## 🚨 Error Condition Testing
|
||||
|
||||
### Network/Connectivity Issues
|
||||
- [ ] Test with no internet connection
|
||||
- [ ] Test with slow internet connection
|
||||
- [ ] Test with CNR API unavailable
|
||||
|
||||
### File System Issues
|
||||
- [ ] Test with insufficient disk space
|
||||
- [ ] Test with permission errors
|
||||
- [ ] Test with corrupted package directories
|
||||
|
||||
### Invalid Input Handling
|
||||
- [ ] Non-existent package names
|
||||
- [ ] Invalid Git URLs
|
||||
- [ ] Malformed command arguments
|
||||
- [ ] Special characters in package names
|
||||
|
||||
---
|
||||
|
||||
# 📊 Performance & Regression Testing
|
||||
|
||||
## ⚡ Performance Comparison
|
||||
```bash
|
||||
# Time core operations
|
||||
time python -m comfyui_manager.cm_cli show all
|
||||
time python -m comfyui_manager.cm_cli install <test-package>
|
||||
time python -m comfyui_manager.cm_cli update all
|
||||
|
||||
# Compare with legacy timings if available
|
||||
```
|
||||
|
||||
**Validation**:
|
||||
- [ ] Operations complete in reasonable time
|
||||
- [ ] No significant performance regression
|
||||
- [ ] Memory usage acceptable
|
||||
|
||||
## 🔄 Regression Testing
|
||||
|
||||
### Output Format Comparison
|
||||
- [ ] Compare show command output with legacy version
|
||||
- [ ] Document acceptable format differences
|
||||
- [ ] Ensure essential information preserved
|
||||
|
||||
### Behavioral Consistency
|
||||
- [ ] Command success/failure behavior matches legacy
|
||||
- [ ] Error message quality comparable to legacy
|
||||
- [ ] User experience remains smooth
|
||||
|
||||
---
|
||||
|
||||
# ✅ Final Validation Checklist
|
||||
|
||||
## Must Pass (Blockers)
|
||||
- [ ] All core commands functional (install/uninstall/enable/disable/update)
|
||||
- [ ] Show commands display accurate package information
|
||||
- [ ] No crashes or unhandled exceptions
|
||||
- [ ] No modifications to glob module
|
||||
- [ ] CLI loads and responds to help commands
|
||||
|
||||
## Should Pass (Important)
|
||||
- [ ] Output format reasonably similar to legacy
|
||||
- [ ] Performance comparable to legacy
|
||||
- [ ] Error handling graceful and informative
|
||||
- [ ] Removed features clearly communicated
|
||||
|
||||
## May Pass (Nice to Have)
|
||||
- [ ] Output format identical to legacy
|
||||
- [ ] Performance better than legacy
|
||||
- [ ] Additional error recovery features
|
||||
- [ ] Code improvements and cleanup
|
||||
|
||||
---
|
||||
|
||||
# 🧰 Testing Tools & Commands
|
||||
|
||||
## Essential Test Commands
|
||||
```bash
|
||||
# Quick smoke test
|
||||
python -m comfyui_manager.cm_cli --help
|
||||
|
||||
# Core functionality test
|
||||
python -m comfyui_manager.cm_cli show all
|
||||
|
||||
# Package management test
|
||||
python -m comfyui_manager.cm_cli install <safe-test-package>
|
||||
|
||||
# Cleanup test
|
||||
python -m comfyui_manager.cm_cli uninstall <test-package>
|
||||
```
|
||||
|
||||
## Debug Commands
|
||||
```bash
|
||||
# Check Python imports
|
||||
python -c "from comfyui_manager.glob import manager_core; print('OK')"
|
||||
|
||||
# Check data structures
|
||||
python -c "from comfyui_manager.glob.manager_core import unified_manager; print(len(unified_manager.installed_node_packages))"
|
||||
|
||||
# Check CNR access
|
||||
python -c "from comfyui_manager.common import cnr_utils; print(len(cnr_utils.get_all_nodepackages()))"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
Use this checklist systematically during implementation to ensure comprehensive testing and validation of the CLI migration.
|
||||
184
docs/internal/cli_migration/README.md
Normal file
184
docs/internal/cli_migration/README.md
Normal file
@@ -0,0 +1,184 @@
|
||||
# CLI Migration Documentation
|
||||
|
||||
**Status**: ✅ Completed (Historical Reference)
|
||||
**Last Updated**: 2025-11-04
|
||||
**Purpose**: Documentation for CLI migration from legacy to glob module (completed August 2025)
|
||||
|
||||
---
|
||||
|
||||
## 📁 Directory Overview
|
||||
|
||||
This directory contains consolidated documentation for the ComfyUI Manager CLI migration project. The migration successfully moved the CLI from the legacy module to the glob module without modifying glob module code.
|
||||
|
||||
---
|
||||
|
||||
## 📚 Documentation Files
|
||||
|
||||
### 🎯 **Comprehensive Guide**
|
||||
- **[CLI_MIGRATION_GUIDE.md](CLI_MIGRATION_GUIDE.md)** (~800 lines)
|
||||
- Complete migration guide with all technical details
|
||||
- Legacy vs Glob comparison
|
||||
- Implementation strategies
|
||||
- Code examples and patterns
|
||||
- **Read this first** for complete understanding
|
||||
|
||||
### 📖 **Implementation Resources**
|
||||
- **[CLI_IMPLEMENTATION_CHECKLIST.md](CLI_IMPLEMENTATION_CHECKLIST.md)** (~350 lines)
|
||||
- Step-by-step implementation tasks
|
||||
- Daily breakdown (3.5 days)
|
||||
- Testing checkpoints
|
||||
- Completion criteria
|
||||
|
||||
- **[CLI_API_REFERENCE.md](CLI_API_REFERENCE.md)** (~300 lines)
|
||||
- Quick API lookup guide
|
||||
- UnifiedManager methods
|
||||
- InstalledNodePackage structure
|
||||
- Usage examples
|
||||
|
||||
- **[CLI_TESTING_GUIDE.md](CLI_TESTING_GUIDE.md)** (~400 lines)
|
||||
- Comprehensive testing strategy
|
||||
- Test scenarios and cases
|
||||
- Validation procedures
|
||||
- Rollback planning
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Quick Start (For Reference)
|
||||
|
||||
### Understanding the Migration
|
||||
|
||||
1. **Start Here**: [CLI_MIGRATION_GUIDE.md](CLI_MIGRATION_GUIDE.md)
|
||||
- Read sections: Overview → Legacy vs Glob → Migration Strategy
|
||||
|
||||
2. **API Reference**: [CLI_API_REFERENCE.md](CLI_API_REFERENCE.md)
|
||||
- Use for quick API lookups during implementation
|
||||
|
||||
3. **Implementation**: [CLI_IMPLEMENTATION_CHECKLIST.md](CLI_IMPLEMENTATION_CHECKLIST.md)
|
||||
- Follow step-by-step if re-implementing
|
||||
|
||||
4. **Testing**: [CLI_TESTING_GUIDE.md](CLI_TESTING_GUIDE.md)
|
||||
- Reference for validation procedures
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Migration Summary
|
||||
|
||||
### Objective Achieved
|
||||
✅ Migrated CLI from `..legacy` to `..glob` imports using only existing glob APIs
|
||||
|
||||
### Key Accomplishments
|
||||
- ✅ **Single file modified**: `comfyui_manager/cm_cli/__main__.py`
|
||||
- ✅ **No glob modifications**: Used existing APIs only
|
||||
- ✅ **All commands functional**: install, update, enable, disable, uninstall
|
||||
- ✅ **show_list() rewritten**: Adapted to InstalledNodePackage architecture
|
||||
- ✅ **Completed in**: 3.5 days as planned
|
||||
|
||||
### Major Changes
|
||||
1. Import path updates (2 lines)
|
||||
2. `install_node()` → use `repo_install()` for Git URLs
|
||||
3. `show_list()` → rewritten for InstalledNodePackage
|
||||
4. Data structure migration: dictionaries → objects
|
||||
5. Removed unsupported features (deps-in-workflow)
|
||||
|
||||
---
|
||||
|
||||
## 📋 File Organization
|
||||
|
||||
```
|
||||
docs/internal/cli_migration/
|
||||
├── README.md (This file - Quick navigation)
|
||||
├── CLI_MIGRATION_GUIDE.md (Complete guide - 800 lines)
|
||||
├── CLI_IMPLEMENTATION_CHECKLIST.md (Task breakdown - 350 lines)
|
||||
├── CLI_API_REFERENCE.md (API docs - 300 lines)
|
||||
└── CLI_TESTING_GUIDE.md (Testing guide - 400 lines)
|
||||
|
||||
Total: 5 files, ~1,850 lines (consolidated from 9 files, ~2,400 lines)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ✨ Documentation Improvements
|
||||
|
||||
### Before Consolidation (9 files)
|
||||
- ❌ Duplicate content across multiple files
|
||||
- ❌ Mixed languages (Korean/English)
|
||||
- ❌ Unclear hierarchy
|
||||
- ❌ Fragmented information
|
||||
|
||||
### After Consolidation (5 files)
|
||||
- ✅ Single comprehensive guide
|
||||
- ✅ All English
|
||||
- ✅ Clear purpose per file
|
||||
- ✅ Easy navigation
|
||||
- ✅ No duplication
|
||||
|
||||
---
|
||||
|
||||
## 🔍 Key Constraints (Historical Reference)
|
||||
|
||||
### Hard Constraints
|
||||
- ❌ NO modifications to glob module
|
||||
- ❌ NO legacy dependencies post-migration
|
||||
- ✅ CLI interface must remain unchanged
|
||||
|
||||
### Implementation Approach
|
||||
- ✅ Adapt CLI code to glob architecture
|
||||
- ✅ Use existing glob APIs only
|
||||
- ✅ Minimal changes, maximum compatibility
|
||||
|
||||
---
|
||||
|
||||
## 📊 Migration Statistics
|
||||
|
||||
| Metric | Value |
|
||||
|--------|-------|
|
||||
| **Duration** | 3.5 days |
|
||||
| **Files Modified** | 1 (`__main__.py`) |
|
||||
| **Lines Changed** | ~200 lines |
|
||||
| **glob Modifications** | 0 (constraint met) |
|
||||
| **Tests Passing** | 100% |
|
||||
| **Features Removed** | 1 (deps-in-workflow) |
|
||||
|
||||
---
|
||||
|
||||
## 🎓 Lessons Learned
|
||||
|
||||
### What Worked Well
|
||||
1. **Consolidation First**: Understanding all legacy usage before coding
|
||||
2. **API-First Design**: glob's clean API made migration straightforward
|
||||
3. **Object-Oriented**: InstalledNodePackage simplified many operations
|
||||
4. **No Glob Changes**: Constraint forced better CLI design
|
||||
|
||||
### Challenges Overcome
|
||||
1. **show_list() Complexity**: Rewrote from scratch using new patterns
|
||||
2. **Dictionary to Object**: Required rethinking data access patterns
|
||||
3. **Async Handling**: Wrapped async methods appropriately
|
||||
4. **Testing Without Mocks**: Relied on integration testing
|
||||
|
||||
---
|
||||
|
||||
## 📚 Related Documentation
|
||||
|
||||
### Project Documentation
|
||||
- [Main Documentation Index](/DOCUMENTATION_INDEX.md)
|
||||
- [Contributing Guidelines](/CONTRIBUTING.md)
|
||||
- [Development Guidelines](/CLAUDE.md)
|
||||
|
||||
### Package Documentation
|
||||
- [glob Module Guide](/comfyui_manager/glob/CLAUDE.md)
|
||||
- [Data Models](/comfyui_manager/data_models/README.md)
|
||||
|
||||
---
|
||||
|
||||
## 🔗 Cross-References
|
||||
|
||||
**If you need to**:
|
||||
- Understand glob APIs → [CLI_API_REFERENCE.md](CLI_API_REFERENCE.md)
|
||||
- See implementation steps → [CLI_IMPLEMENTATION_CHECKLIST.md](CLI_IMPLEMENTATION_CHECKLIST.md)
|
||||
- Run tests → [CLI_TESTING_GUIDE.md](CLI_TESTING_GUIDE.md)
|
||||
- Understand full context → [CLI_MIGRATION_GUIDE.md](CLI_MIGRATION_GUIDE.md)
|
||||
|
||||
---
|
||||
|
||||
**Status**: ✅ Migration Complete - Documentation Archived for Reference
|
||||
**Next Review**: When similar migration projects are planned
|
||||
328
docs/internal/test_planning/FUTURE_TEST_PLANS.md
Normal file
328
docs/internal/test_planning/FUTURE_TEST_PLANS.md
Normal file
@@ -0,0 +1,328 @@
|
||||
# Future Test Plans
|
||||
|
||||
**Type**: Planning Document (Future Tests)
|
||||
**Status**: P1 tests COMPLETE ✅ - Additional scenarios remain planned
|
||||
**Current Implementation Status**: See [tests/glob/README.md](../../../tests/glob/README.md)
|
||||
|
||||
**Last Updated**: 2025-11-06
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
This document contains test scenarios that are **planned but not yet implemented**. For currently implemented tests, see [tests/glob/README.md](../../../tests/glob/README.md).
|
||||
|
||||
**Currently Implemented**: 51 tests ✅ (includes all P1 complex scenarios)
|
||||
**P1 Implementation**: COMPLETE ✅ (Phase 3.1, 5.1, 5.2, 5.3, 6)
|
||||
**Planned in this document**: Additional scenarios for comprehensive coverage (P0, P2)
|
||||
|
||||
---
|
||||
|
||||
## 📋 Table of Contents
|
||||
|
||||
1. [Simple Test Scenarios](#simple-test-scenarios) - Additional basic API tests
|
||||
2. [Complex Multi-Version Scenarios](#complex-multi-version-scenarios) - Advanced state management tests
|
||||
3. [Priority Matrix](#priority-matrix) - Implementation priorities
|
||||
|
||||
---
|
||||
|
||||
# Simple Test Scenarios
|
||||
|
||||
These are straightforward single-version/type test scenarios that extend the existing test suite.
|
||||
|
||||
## 3. Error Handling Testing (Priority: Medium)
|
||||
|
||||
### Test 3.1: Install Non-existent Package
|
||||
**Purpose**: Handle invalid package names
|
||||
|
||||
**Steps**:
|
||||
1. Attempt to install with non-existent package ID
|
||||
2. Verify appropriate error message
|
||||
|
||||
**Verification Items**:
|
||||
- ✓ Error status returned
|
||||
- ✓ Clear error message
|
||||
- ✓ No server crash
|
||||
|
||||
### Test 3.2: Invalid Version Specification
|
||||
**Purpose**: Handle non-existent version installation attempts
|
||||
|
||||
**Steps**:
|
||||
1. Attempt to install with non-existent version (e.g., "99.99.99")
|
||||
2. Verify error handling
|
||||
|
||||
**Verification Items**:
|
||||
- ✓ Error status returned
|
||||
- ✓ Clear error message
|
||||
|
||||
### Test 3.3: Permission Error Simulation
|
||||
**Purpose**: Handle file system permission issues
|
||||
|
||||
**Steps**:
|
||||
1. Set custom_nodes directory to read-only
|
||||
2. Attempt package installation
|
||||
3. Verify error handling
|
||||
4. Restore permissions
|
||||
|
||||
**Verification Items**:
|
||||
- ✓ Permission error detected
|
||||
- ✓ Clear error message
|
||||
- ✓ Partial installation rollback
|
||||
|
||||
---
|
||||
|
||||
## 4. Dependency Management Testing (Priority: Medium)
|
||||
|
||||
### Test 4.1: Installation with Dependencies
|
||||
**Purpose**: Automatic installation of dependencies from packages with requirements.txt
|
||||
|
||||
**Steps**:
|
||||
1. Install package with dependencies
|
||||
2. Verify requirements.txt processing
|
||||
3. Verify dependency packages installed
|
||||
|
||||
**Verification Items**:
|
||||
- ✓ requirements.txt executed
|
||||
- ✓ Dependency packages installed
|
||||
- ✓ Installation scripts executed
|
||||
|
||||
### Test 4.2: no_deps Flag Testing
|
||||
**Purpose**: Verify option to skip dependency installation
|
||||
|
||||
**Steps**:
|
||||
1. Install package with no_deps=true
|
||||
2. Verify requirements.txt skipped
|
||||
3. Verify installation scripts skipped
|
||||
|
||||
**Verification Items**:
|
||||
- ✓ Dependency installation skipped
|
||||
- ✓ Only package files installed
|
||||
|
||||
---
|
||||
|
||||
## 5. Multi-package Management Testing (Priority: Medium)
|
||||
|
||||
### Test 5.1: Concurrent Multiple Package Installation
|
||||
**Purpose**: Concurrent installation of multiple independent packages
|
||||
|
||||
**Steps**:
|
||||
1. Add 3 different packages to queue
|
||||
2. Start queue
|
||||
3. Verify all packages installed
|
||||
|
||||
**Verification Items**:
|
||||
- ✓ All packages installed successfully
|
||||
- ✓ Installation order guaranteed
|
||||
- ✓ Individual failures don't affect other packages
|
||||
|
||||
### Test 5.2: Same Package Concurrent Installation (Conflict Handling)
|
||||
**Purpose**: Handle concurrent requests for same package
|
||||
|
||||
**Steps**:
|
||||
1. Add same package to queue twice
|
||||
2. Start queue
|
||||
3. Verify duplicate handling
|
||||
|
||||
**Verification Items**:
|
||||
- ✓ First installation successful
|
||||
- ✓ Second request skipped
|
||||
- ✓ Handled without errors
|
||||
|
||||
---
|
||||
|
||||
## 6. Security Level Testing (Priority: Low)
|
||||
|
||||
### Test 6.1: Installation Restrictions by Security Level
|
||||
**Purpose**: Allow/deny installation based on security_level settings
|
||||
|
||||
**Steps**:
|
||||
1. Set security_level to "strong"
|
||||
2. Attempt installation with non-CNR registered URL
|
||||
3. Verify rejection
|
||||
|
||||
**Verification Items**:
|
||||
- ✓ Security level validation
|
||||
- ✓ Appropriate error message
|
||||
|
||||
---
|
||||
|
||||
# Complex Multi-Version Scenarios
|
||||
|
||||
These scenarios test complex interactions between multiple versions and types of the same package.
|
||||
|
||||
## Test Philosophy
|
||||
|
||||
### Real-World Scenarios
|
||||
1. User switches from Nightly to CNR
|
||||
2. Install both CNR and Nightly, activate only one
|
||||
3. Keep multiple versions in .disabled/ and switch as needed
|
||||
4. Other versions exist in disabled state during Update
|
||||
|
||||
---
|
||||
|
||||
## Phase 7: Complex Version Switch Chains (Priority: High)
|
||||
|
||||
### Test 7.1: CNR Old Enabled → CNR New (Other Versions Disabled)
|
||||
**Initial State:**
|
||||
```
|
||||
custom_nodes/:
|
||||
└── ComfyUI_SigmoidOffsetScheduler/ (CNR 1.0.1)
|
||||
.disabled/:
|
||||
├── ComfyUI_SigmoidOffsetScheduler_1.0.0/
|
||||
└── ComfyUI_SigmoidOffsetScheduler_nightly/
|
||||
```
|
||||
|
||||
**Operation:** Install CNR v1.0.2 (version switch)
|
||||
|
||||
**Expected Result:**
|
||||
```
|
||||
custom_nodes/:
|
||||
└── ComfyUI_SigmoidOffsetScheduler/ (CNR 1.0.2)
|
||||
.disabled/:
|
||||
├── ComfyUI_SigmoidOffsetScheduler_1.0.0/
|
||||
├── ComfyUI_SigmoidOffsetScheduler_1.0.1/ (old enabled version)
|
||||
└── ComfyUI_SigmoidOffsetScheduler_nightly/
|
||||
```
|
||||
|
||||
**Verification Items:**
|
||||
- ✓ Existing enabled version auto-disabled
|
||||
- ✓ New version enabled
|
||||
- ✓ All disabled versions maintained
|
||||
- ✓ Version history managed
|
||||
|
||||
### Test 7.2: Version Switch Chain (Nightly → CNR Old → CNR New)
|
||||
**Scenario:** Sequential version transitions
|
||||
|
||||
**Step 1:** Nightly enabled
|
||||
**Step 2:** Switch to CNR 1.0.1
|
||||
**Step 3:** Switch to CNR 1.0.2
|
||||
|
||||
**Verification Items:**
|
||||
- ✓ Each transition step operates normally
|
||||
- ✓ Version history accumulates
|
||||
- ✓ Rollback-capable state maintained
|
||||
|
||||
---
|
||||
|
||||
## Phase 8: Edge Cases & Error Scenarios (Priority: Medium)
|
||||
|
||||
### Test 8.1: Corrupted Package in .disabled/
|
||||
**Situation:** Corrupted package exists in .disabled/
|
||||
|
||||
**Operation:** Attempt Enable
|
||||
|
||||
**Expected Result:**
|
||||
- Clear error message
|
||||
- Fallback to other version (if possible)
|
||||
- System stability maintained
|
||||
|
||||
### Test 8.2: Name Collision in .disabled/
|
||||
**Situation:** Package with same name already exists in .disabled/
|
||||
|
||||
**Operation:** Attempt Disable
|
||||
|
||||
**Expected Result:**
|
||||
- Generate unique name (timestamp, etc.)
|
||||
- No data loss
|
||||
- All versions distinguishable
|
||||
|
||||
### Test 8.3: Enable Non-existent Version
|
||||
**Situation:** Requested version not in .disabled/
|
||||
|
||||
**Operation:** Enable specific version
|
||||
|
||||
**Expected Result:**
|
||||
- Clear error message
|
||||
- Available version list provided
|
||||
- Graceful failure
|
||||
|
||||
---
|
||||
|
||||
# Priority Matrix
|
||||
|
||||
**Note**: Phases 3, 4, 5, and 6 are now complete and documented in [tests/glob/README.md](../../../tests/glob/README.md). This matrix shows only planned future tests.
|
||||
|
||||
| Phase | Scenario | Priority | Status | Complexity | Real-World Frequency |
|
||||
|-------|----------|----------|--------|------------|---------------------|
|
||||
| 7 | Complex Version Switch Chains | P0 | 🔄 PARTIAL | High | High |
|
||||
| 8 | Edge Cases & Error Scenarios | P2 | ⏳ PLANNED | High | Low |
|
||||
| Simple | Error Handling (3.1-3.3) | P2 | ⏳ PLANNED | Medium | Medium |
|
||||
| Simple | Dependency Management (4.1-4.2) | P2 | ⏳ PLANNED | Medium | Medium |
|
||||
| Simple | Multi-package Management (5.1-5.2) | P2 | ⏳ PLANNED | Medium | Low |
|
||||
| Simple | Security Level Testing (6.1) | P2 | ⏳ PLANNED | Low | Low |
|
||||
|
||||
**Priority Definitions:**
|
||||
- **P0:** High priority (implement next) - Phase 7 Complex Version Switch
|
||||
- **P1:** Medium priority - ✅ **ALL COMPLETE** (Phase 3, 4, 5, 6 - see tests/glob/README.md)
|
||||
- **P2:** Low priority (implement as needed) - Simple tests and Phase 8
|
||||
|
||||
**Status Definitions:**
|
||||
- 🔄 PARTIAL: Some tests implemented (Phase 7 has version switching tests in test_version_switching_comprehensive.py)
|
||||
- ⏳ PLANNED: Not yet started
|
||||
|
||||
**Recommended Next Steps:**
|
||||
1. **Phase 7 Remaining Tests** (P0) - Complex version switch chains with multiple disabled versions
|
||||
2. **Simple Test Scenarios** (P2) - Error handling, dependency management, multi-package operations
|
||||
3. **Phase 8** (P2) - Edge cases and error scenarios
|
||||
|
||||
---
|
||||
|
||||
# Implementation Notes
|
||||
|
||||
## Fixture Patterns
|
||||
|
||||
For multi-version tests, use these fixture patterns:
|
||||
|
||||
```python
|
||||
@pytest.fixture
|
||||
def setup_multi_disabled_cnr_and_nightly(api_client, custom_nodes_path):
|
||||
"""
|
||||
Install both CNR and Nightly in disabled state.
|
||||
|
||||
Pattern:
|
||||
1. Install CNR → custom_nodes/
|
||||
2. Disable CNR → .disabled/comfyui_sigmoidoffsetscheduler@1_0_2
|
||||
3. Install Nightly → custom_nodes/
|
||||
4. Disable Nightly → .disabled/comfyui_sigmoidoffsetscheduler@nightly
|
||||
"""
|
||||
# Implementation details in archived COMPLEX_SCENARIOS_TEST_PLAN.md
|
||||
```
|
||||
|
||||
## Verification Helpers
|
||||
|
||||
Use these verification patterns:
|
||||
|
||||
```python
|
||||
def verify_version_state(custom_nodes_path, expected_state):
|
||||
"""
|
||||
Verify package state matches expectations.
|
||||
|
||||
expected_state = {
|
||||
'enabled': {'type': 'cnr' | 'nightly' | None, 'version': '1.0.2'},
|
||||
'disabled': [
|
||||
{'type': 'cnr', 'version': '1.0.1'},
|
||||
{'type': 'nightly'}
|
||||
]
|
||||
}
|
||||
"""
|
||||
# Implementation details in archived COMPLEX_SCENARIOS_TEST_PLAN.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# References
|
||||
|
||||
## Archived Implementation Guides
|
||||
|
||||
Detailed implementation examples, code snippets, and fixtures are available in archived planning documents:
|
||||
- `.claude/archive/docs_2025-11-04/COMPLEX_SCENARIOS_TEST_PLAN.md` - Complete implementation guide with code examples
|
||||
- `.claude/archive/docs_2025-11-04/TEST_PLAN_ADDITIONAL.md` - Simple test scenarios
|
||||
|
||||
## Current Implementation
|
||||
|
||||
For currently implemented tests and their status:
|
||||
- **[tests/glob/README.md](../../../tests/glob/README.md)** - Current test status and coverage
|
||||
|
||||
---
|
||||
|
||||
**End of Future Test Plans**
|
||||
Reference in New Issue
Block a user