feat(cli): expand --uv-compile to all node management commands with conflict attribution (#2682)

* feat(cli): expand --uv-compile to all node management commands with conflict attribution Add --uv-compile flag to reinstall, update, fix, restore-snapshot, restore-dependencies, and install-deps commands. Each skips per-node pip installs and runs batch uv pip compile after all operations. Change CollectedDeps.sources type to dict[str, list[tuple[str, str]]] to store (pack_path, pkg_spec) per requester. On resolution failure, _run_unified_resolve() cross-references conflict packages with sources using word-boundary regex and displays which node packs requested each conflicting package. Update EN/KO user docs and DESIGN/PRD developer docs to cover the expanded commands and conflict attribution output. Strengthen unit tests for sources tuple format and compile failure attribution. Bump version to 4.1b3. * refactor(cli): extract _finalize_resolve helper, add CNR nightly fallback and pydantic guard - Extract `_finalize_resolve()` to eliminate 7x duplicated uv-compile error handling blocks in cm_cli (~-85 lines) - Move conflict attribution regex to `attribute_conflicts()` in unified_dep_resolver.py for direct testability - Update 4 attribution tests to call production function instead of re-implementing regex - Add CNR nightly fallback: when node is absent from nightly manifest, fall back to cnr_map repository URL (glob + legacy) - Add pydantic Union guard: use getattr for is_unknown in uninstall and disable handlers to prevent Union type mismatch - Add E2E test suites for endpoint install/uninstall and uv-compile CLI commands (conflict + success cases) - Add nightly CNR fallback regression tests
2026-05-02 16:27:50 +08:00 · 2026-03-14 07:58:29 +09:00
parent f042d73b72
commit d7a2277017
14 changed files with 1316 additions and 54 deletions
--- a/docs/dev/DESIGN-unified-dependency-resolver.md
+++ b/docs/dev/DESIGN-unified-dependency-resolver.md
@ -149,7 +149,8 @@ class CollectedDeps:
    """All collected dependencies"""
    requirements: list[PackageRequirement]  # Collected deps (duplicates allowed, uv resolves)
    skipped: list[tuple[str, str]]          # (package_name, skip_reason)
-    sources: dict[str, list[str]]           # {package_name: [source_node_packs]}
+    sources: dict[str, list[tuple[str, str]]]  # {package_name: [(pack_path, pkg_spec), ...]}
+    """pkg_name → [(pack_path, pkg_spec), ...] — tracks which node packs request each package."""
    extra_index_urls: list[str]             # Additional index URLs separated from --index-url entries

@dataclass
@ -262,7 +263,7 @@ def collect_requirements(self) -> CollectedDeps:
                source=path,
            )
            requirements.append(req)
-            sources[pkg_name].append(path)
+            sources[pkg_name].append((path, pkg_spec))

    return CollectedDeps(
        requirements=requirements,
@ -449,7 +450,7 @@ if os.path.exists(requirements_path) and not _unified_resolver_succeeded:

 ### 4.1.6 CLI Integration

-Two entry points expose the unified resolver in `cm_cli`:
+Multiple entry points expose the unified resolver in `cm_cli`:

 #### 4.1.6.1 Standalone Command: `cm_cli uv-compile`

@ -478,19 +479,53 @@ When `--uv-compile` is set:
 This differs from per-node pip install: instead of resolving each node pack's
 `requirements.txt` independently, all deps are compiled together to avoid conflicts.

+#### 4.1.6.3 Additional `--uv-compile` Commands
+
+The following commands follow the same `no_deps` + batch-resolve pattern as `install --uv-compile`:
+`cmd_ctx.set_no_deps(True)` is set before node operations, then `_run_unified_resolve()`
+runs at the end via `try/finally` with `PIPFixer.fix_broken()`.
+
+| Command | Operation |
+|---------|-----------|
+| `cm_cli reinstall --uv-compile` | Reinstall nodes then batch-resolve |
+| `cm_cli update --uv-compile` | Update nodes then batch-resolve |
+| `cm_cli fix --uv-compile` | Fix node dependencies then batch-resolve |
+| `cm_cli restore-snapshot --uv-compile` | Restore snapshot then batch-resolve |
+| `cm_cli restore-dependencies --uv-compile` | Restore all node deps then batch-resolve |
+| `cm_cli install-deps <deps.json> --uv-compile` | Install from deps spec file then batch-resolve |
+
+> **`reinstall` only**: Has `--uv-compile` / `--no-deps` mutual exclusion check.
+> Both skip per-node pip, but `--no-deps` skips permanently while `--uv-compile` also
+> triggers batch resolution after all nodes are processed.
+>
+> **`restore-snapshot` only**: Has an additional pre-resolution exception guard — if the
+> snapshot restore itself fails (before `_run_unified_resolve()` is reached),
+> `PIPFixer.fix_broken()` runs in the exception handler before exit. The `try/finally`
+> applies to the `_run_unified_resolve()` call. See dec_7 for rationale.
+
 #### Shared Design Decisions

 - **Uses real `cm_global` values**: Unlike the startup path (4.1.3) which passes empty
  blacklist/overrides, CLI commands pass `cm_global.pip_blacklist`,
  `cm_global.pip_overrides`, and `cm_global.pip_downgrade_blacklist` — already
-  initialized at `cm_cli/__main__.py` module scope (lines 45-60).
+  initialized at `cm_cli/__main__.py` module scope.
 - **No `_unified_resolver_succeeded` flag**: Not needed — these are one-shot commands,
  not startup gates.
- **Shared helper**: Both entry points delegate to `_run_unified_resolve()` which
+- **Shared helper**: All entry points delegate to `_run_unified_resolve()` which
  handles resolver instantiation, execution, and result reporting.
 - **Error handling**: `UvNotAvailableError` / `ImportError` → exit 1 with message.
-  Both entry points use `try/finally` to guarantee `PIPFixer.fix_broken()` runs
-  regardless of resolution outcome.
+  All entry points guarantee `PIPFixer.fix_broken()` runs regardless of outcome —
+  via `try/finally` around `_run_unified_resolve()`. `restore-snapshot` additionally
+  calls `fix_broken()` in the snapshot restore exception handler (before
+  `_run_unified_resolve()` is reached), per dec_7.
+- **Conflict attribution output**: When resolution fails and `result.lockfile.conflicts`
+  is non-empty, `_run_unified_resolve()` cross-references conflict package names with
+  `CollectedDeps.sources` to identify which node packs requested each conflicting package:
+  - Normalization: both sources keys and conflict text apply `.lower().replace("-", "_")`
+  - Word-boundary regex `(?<![a-z0-9_])pkg(?![a-z0-9_])` prevents false-positive prefix
+    matches (e.g., `torch` does NOT match `torch_audio` or `torchvision`)
+  - Output format: sorted by package name, each entry lists `pack_basename → pkg_spec`
+    per requester (using `CollectedDeps.sources` tuple values `(pack_path, pkg_spec)`)

 **Node pack discovery**: Uses `cmd_ctx.get_custom_nodes_paths()` → `collect_node_pack_paths()`,
 which is the CLI-native path resolution (respects `--user-directory` and `folder_paths`).
--- a/docs/dev/PRD-unified-dependency-resolver.md
+++ b/docs/dev/PRD-unified-dependency-resolver.md
@ -329,7 +329,7 @@ User requests installation of node packs A and B nearly simultaneously from UI

 ## 7. Future Extensions

- ~~**`cm_global` integration** [DONE]: `cm_cli uv-compile` and `cm_cli install --uv-compile` pass real `cm_global` values. Startup path (`prestartup_script.py`) still passes empty by design~~
+- ~~**`cm_global` integration** [DONE]: All `--uv-compile` CLI commands (`uv-compile`, `install`, `reinstall`, `update`, `fix`, `restore-snapshot`, `restore-dependencies`, `install-deps`) pass real `cm_global` values. Startup path (`prestartup_script.py`) still passes empty by design~~
 - Lockfile caching: Reuse for identical node pack configurations
 - Pre-install dependency conflict validation API: Check compatibility before installation
 - Dependency tree visualization: Display dependency relationships to users
@ -355,3 +355,9 @@ User requests installation of node packs A and B nearly simultaneously from UI
 | Legacy `execute_install_script()` (2 locations) | `legacy/manager_core.py` | ❌ No | Legacy paths |
 | `cm_cli uv-compile` | `cm_cli/__main__.py` | ✅ Yes | Standalone CLI batch resolution (with `cm_global` values) |
 | `cm_cli install --uv-compile` | `cm_cli/__main__.py` | ✅ Yes | Per-node pip skipped, batch resolution after all installs |
+| `cm_cli reinstall --uv-compile` | `cm_cli/__main__.py` | ✅ Yes | Per-node pip skipped, batch resolution after all reinstalls; mutually exclusive with `--no-deps` |
+| `cm_cli update --uv-compile` | `cm_cli/__main__.py` | ✅ Yes | Per-node pip skipped during updates, batch resolution after |
+| `cm_cli fix --uv-compile` | `cm_cli/__main__.py` | ✅ Yes | Per-node pip skipped during dep fix, batch resolution after |
+| `cm_cli restore-snapshot --uv-compile` | `cm_cli/__main__.py` | ✅ Yes | Per-node pip skipped during restore, batch resolution after |
+| `cm_cli restore-dependencies --uv-compile` | `cm_cli/__main__.py` | ✅ Yes | Per-node pip skipped, batch resolution after all node deps restored |
+| `cm_cli install-deps --uv-compile` | `cm_cli/__main__.py` | ✅ Yes | Per-node pip skipped, batch resolution after deps-spec install |
--- a/docs/en/cm-cli.md
+++ b/docs/en/cm-cli.md
@ -11,11 +11,15 @@ cm-cli [OPTIONS]

 OPTIONS:
    [install|reinstall|uninstall|update|disable|enable|fix] node_name ... ?[--channel <channel name>] ?[--mode [remote|local|cache]]
+    [install|reinstall|update|fix] node_name ... ?[--uv-compile]
    [update|disable|enable|fix] all ?[--channel <channel name>] ?[--mode [remote|local|cache]]
+    [update|fix] all ?[--uv-compile]
    [simple-show|show] [installed|enabled|not-installed|disabled|all|snapshot|snapshot-list] ?[--channel <channel name>] ?[--mode [remote|local|cache]]
    save-snapshot ?[--output <snapshot .json/.yaml>]
-    restore-snapshot <snapshot .json/.yaml> ?[--pip-non-url] ?[--pip-non-local-url] ?[--pip-local-url]
-    restore-dependencies
+    restore-snapshot <snapshot .json/.yaml> ?[--pip-non-url] ?[--pip-non-local-url] ?[--pip-local-url] ?[--uv-compile]
+    restore-dependencies ?[--uv-compile]
+    install-deps <deps.json> ?[--channel <channel name>] ?[--mode [remote|local|cache]] ?[--uv-compile]
+    uv-compile
    clear
 ```

@ -107,6 +111,22 @@ ComfyUI-Loopchain
    * `enable`: Enables the specified custom nodes.
    * `fix`: Attempts to fix dependencies for the specified custom nodes.

+#### `--uv-compile` flag (`install`, `reinstall`, `update`, `fix`)
+
+When `--uv-compile` is specified, per-node pip installs are skipped during node operations.
+After all operations complete, `uv pip compile` resolves the full dependency graph in one batch.
+
+* Requires `uv` to be installed.
+* Prevents dependency conflicts between multiple node packs.
+* On resolution failure, displays conflicting packages and which node packs requested them.
+* `reinstall --uv-compile` is mutually exclusive with `--no-deps`.
+
+```bash
+cm-cli install ComfyUI-Impact-Pack ComfyUI-Inspire-Pack --uv-compile
+cm-cli update all --uv-compile
+cm-cli fix ComfyUI-Impact-Pack --uv-compile
+```
+

 ### 4. Snapshot Management
 * `cm-cli save-snapshot [--output <snapshot .json/.yaml>]`: Saves the current snapshot.
@ -122,12 +142,33 @@ ComfyUI-Loopchain

 ### 5. Dependency Restoration

-`restore-dependencies`
+`restore-dependencies ?[--uv-compile]`

 * This command can be used if custom nodes are installed under the `ComfyUI/custom_nodes` path but their dependencies are not installed.
 * It is useful when starting a new cloud instance, like Colab, where dependencies need to be reinstalled and installation scripts re-executed.
 * It can also be utilized if ComfyUI is reinstalled and only the custom_nodes path has been backed up and restored.
+* Use `--uv-compile` to skip per-node pip installs and resolve all dependencies in one batch instead.

-### 6. Clear
+### 6. Install from Dependency File
+
+`install-deps <deps.json> ?[--channel <channel name>] ?[--mode [remote|local|cache]] ?[--uv-compile]`
+
+* Installs custom nodes specified in a dependency spec file (`.json`) or workflow file (`.png`/`.json`).
+* Use `--uv-compile` to batch-resolve all dependencies after installation instead of per-node pip.
+
+### 7. uv-compile
+
+`uv-compile ?[--user-directory <path>]`
+
+* Batch-resolves and installs all custom node pack dependencies using `uv pip compile`.
+* Useful for environment recovery or initial setup without starting ComfyUI.
+* Requires `uv` to be installed.
+
+```bash
+cm-cli uv-compile
+cm-cli uv-compile --user-directory /path/to/comfyui
+```
+
+### 8. Clear

 In the GUI, installations, updates, or snapshot restorations are scheduled to execute the next time ComfyUI is launched. The `clear` command clears this scheduled state, ensuring no pre-execution actions are applied.
--- a/docs/ko/cm-cli.md
+++ b/docs/ko/cm-cli.md
@ -11,11 +11,15 @@ cm-cli [OPTIONS]

 OPTIONS:
    [install|reinstall|uninstall|update|disable|enable|fix] node_name ... ?[--channel <channel name>] ?[--mode [remote|local|cache]]
+    [install|reinstall|update|fix] node_name ... ?[--uv-compile]
    [update|disable|enable|fix] all ?[--channel <channel name>] ?[--mode [remote|local|cache]]
+    [update|fix] all ?[--uv-compile]
    [simple-show|show] [installed|enabled|not-installed|disabled|all|snapshot|snapshot-list] ?[--channel <channel name>] ?[--mode [remote|local|cache]]
    save-snapshot ?[--output <snapshot .json/.yaml>]
-    restore-snapshot <snapshot .json/.yaml> ?[--pip-non-url] ?[--pip-non-local-url] ?[--pip-local-url]
-    restore-dependencies
+    restore-snapshot <snapshot .json/.yaml> ?[--pip-non-url] ?[--pip-non-local-url] ?[--pip-local-url] ?[--uv-compile]
+    restore-dependencies ?[--uv-compile]
+    install-deps <deps.json> ?[--channel <channel name>] ?[--mode [remote|local|cache]] ?[--uv-compile]
+    uv-compile
    clear
 ```

@ -108,6 +112,21 @@ ComfyUI-Loopchain
    * `enable`: 지정된 커스텀 노드들을 활성화합니다.
    * `fix`: 지정된 커스텀 노드의 의존성을 고치기 위한 시도를 합니다.

+#### `--uv-compile` 플래그 (`install`, `reinstall`, `update`, `fix`)
+
+`--uv-compile` 플래그를 사용하면 노드별 pip 설치를 건너뛰고, 모든 작업이 완료된 후 `uv pip compile`로 전체 의존성을 한 번에 일괄 해결합니다.
+
+* `uv`가 설치된 환경에서만 동작합니다.
+* 여러 노드 팩 간의 의존성 충돌을 방지합니다.
+* 해결 실패 시 충돌 패키지와 해당 패키지를 요청한 노드 팩 목록을 표시합니다.
+* `reinstall --uv-compile`은 `--no-deps`와 동시에 사용할 수 없습니다.
+
+```bash
+cm-cli install ComfyUI-Impact-Pack ComfyUI-Inspire-Pack --uv-compile
+cm-cli update all --uv-compile
+cm-cli fix ComfyUI-Impact-Pack --uv-compile
+```
+

 ### 4. 스냅샷 관리 기능
 * `cm-cli save-snapshot ?[--output <snapshot .json/.yaml>]`: 현재의 snapshot을 저장합니다.
@ -123,13 +142,33 @@ ComfyUI-Loopchain

 ### 5. 의존성 설치

-`restore-dependencies`
+`restore-dependencies ?[--uv-compile]`

 * `ComfyUI/custom_nodes` 하위 경로에 커스텀 노드들이 설치되어 있긴 하지만, 의존성이 설치되지 않은 경우 사용할 수 있습니다.
 * Colab과 같이 cloud instance를 새로 시작하는 경우 의존성 재설치 및 설치 스크립트가 재실행되어야 하는 경우 사용합니다.
 * ComfyUI를 재설치할 경우, custom_nodes 경로만 백업했다가 재설치할 경우 활용 가능합니다.
+* `--uv-compile` 플래그를 사용하면 노드별 pip 설치를 건너뛰고 일괄 해결합니다.

+### 6. 의존성 파일로 설치

-### 6. clear
+`install-deps <deps.json> ?[--channel <channel name>] ?[--mode [remote|local|cache]] ?[--uv-compile]`
+
+* 의존성 spec 파일(`.json`) 또는 워크플로우 파일(`.png`/`.json`)에 명시된 커스텀 노드를 설치합니다.
+* `--uv-compile` 플래그를 사용하면 모든 노드 설치 후 일괄 의존성 해결을 수행합니다.
+
+### 7. uv-compile
+
+`uv-compile ?[--user-directory <path>]`
+
+* 설치된 모든 커스텀 노드 팩의 의존성을 `uv pip compile`로 일괄 해결하고 설치합니다.
+* ComfyUI를 재시작하지 않고 의존성 환경을 복구하거나 초기 설정 시 활용할 수 있습니다.
+* `uv`가 설치된 환경에서만 동작합니다.
+
+```bash
+cm-cli uv-compile
+cm-cli uv-compile --user-directory /path/to/comfyui
+```
+
+### 8. clear

 GUI에서 install, update를 하거나 snapshot을 restore하는 경우 예약을 통해서 다음번 ComfyUI를 실행할 경우 실행되는 구조입니다. `clear` 는 이런 예약 상태를 clear해서, 아무런 사전 실행이 적용되지 않도록 합니다.