comfygit-core 0.3.22__tar.gz → 0.4.0__tar.gz

comfygit_core-0.4.0/AGENTS.md

@@ -0,0 +1,122 @@
+<!-- NOTE: packages/core/AGENTS.md and packages/core/CLAUDE.md must stay in sync. -->
+
+# ComfyGit Core Agent Guide
+
+`packages/core` is the UI-agnostic library package. It owns workspace and
+environment state, manifest semantics, sync/materialization behavior, model and
+node metadata, git orchestration, and callback/protocol contracts used by CLI,
+manager, deploy, and future runtime tooling.
+
+## Active Truth Layer
+
+Read root truth-layer docs before changing core behavior:
+
+- `../../docs/contracts/core/CONTRACT.md` - active core contract and invariants.
+- `../../docs/specs/environment-manifest-model.md` - tracked manifest semantics.
+- `../../docs/specs/environment-sync-lifecycle.md` - sync/run/git lifecycle.
+- `../../docs/specs/dependency-criticality.md` - model/node required vs optional behavior.
+- `../../docs/spec-driven-development.md` - clause syntax and validation rules.
+
+Package docs are supporting reference:
+
+- `docs/architecture.md` - core layer overview.
+- `docs/layer-hierarchy.md` - package-local layering reference.
+- `docs/knowledge/` - topic-specific behavior notes.
+- `docs/plans/` - planning docs; verify against truth-layer clauses before treating as current.
+
+## Core Boundaries
+
+- Keep core independent of CLI, manager UI, and ComfyUI panel rendering.
+- Avoid normal-use `print()` and `input()` in core; expose callbacks,
+  strategies, protocols, return values, and exceptions so callers own UX.
+- Prefer `Workspace` and `Environment` as public entry points. Keep direct manager
+  access for internal composition, tests, and package-local advanced behavior.
+- Do not put service-specific deployment policy into core. Core should
+  write/read portable manifest semantics that runtime adapters can consume.
+
+## Source Map
+
+| Path | Purpose |
+| --- | --- |
+| `src/comfygit_core/core/` | Public `Workspace` and `Environment` APIs. |
+| `src/comfygit_core/managers/` | Stateful orchestration for pyproject, uv, git, nodes, workflows, models, overlays, and symlinks. |
+| `src/comfygit_core/models/` | Dataclasses, protocols, exceptions, manifest/workflow/sync types. |
+| `src/comfygit_core/resolvers/` | Node and model resolution logic. |
+| `src/comfygit_core/services/` | Stateless business logic, registry/model lookup, downloads, workflow services. |
+| `src/comfygit_core/repositories/` | SQLite-backed caches and persistent indexes. |
+| `src/comfygit_core/analyzers/` | Workflow, git, config, model, and custom-node analysis. |
+| `src/comfygit_core/integrations/` | External command integrations such as uv. |
+| `src/comfygit_core/utils/` | Low-level filesystem, git, dependency, PyTorch, retry, and parsing helpers. |
+
+Check existing managers/services before adding new abstractions.
+
+## Key Managers
+
+| Manager | File | Main responsibility |
+| --- | --- | --- |
+| `PyprojectManager` | `managers/pyproject_manager.py` | Manifest CRUD and temporary uv/PyTorch injection. |
+| `UVProjectManager` | `managers/uv_project_manager.py` | uv sync/add/remove operations. |
+| `OverlayManager` | `managers/overlay_manager.py` | Overlay loading and legacy `.local-uv-config` migration. |
+| `PyTorchBackendManager` | `managers/pytorch_backend_manager.py` | `.pytorch-backend`, GPU probing, torch source config. |
+| `NodeManager` | `managers/node_manager.py` | Custom node install/remove/update. |
+| `WorkflowManager` | `managers/workflow_manager.py` | Workflow tracking, node/model resolution, contract metadata. |
+| `EnvironmentModelManager` | `managers/environment_model_manager.py` | Environment-level model status and metadata aggregation. |
+| `GitManager` | `managers/git_manager.py` | Environment repo git operations. |
+| `ExportImportManager` | `managers/export_import_manager.py` | Portable environment import/export. |
+
+## Manifest And Local State
+
+Tracked portable truth lives in each environment repo's `pyproject.toml`.
+Runtime/materialized state lives under environment runtime directories such as
+`.cec/`, virtualenvs, ComfyUI checkouts, symlinks, caches, and local SQLite DBs.
+
+Machine-local sync inputs are not portable manifest truth:
+
+- `.pytorch-backend` stores local torch backend choice and generated source pins.
+- Local uv overrides now flow through overlays, with legacy `.local-uv-config`
+  migrated by `OverlayManager`.
+
+`PyprojectManager.uv_injection_context()` temporarily merges local overlays and
+PyTorch backend config into `pyproject.toml` for uv operations, then restores the
+tracked manifest in a `finally` path. Preserve that invariant.
+
+## Dependency Criticality
+
+Current model criticality supports required, flexible, and optional. Required
+unresolved models are reproducibility blockers; optional unresolved models are
+warnings.
+
+Custom node criticality is planned as explicit manifest metadata:
+
+- Supported values should start as `required` and `optional`.
+- Missing criticality reads as `required`.
+- Optional unresolved nodes warn instead of blocking build readiness.
+- Workflow graph usage can inform UI messaging, but must not silently downgrade
+  user-declared custom node criticality.
+
+## Testing
+
+Run tests from the repo root with uv:
+
+```bash
+uv run pytest packages/core/tests/ -v
+uv run pytest packages/core/tests/unit/managers/test_pyproject_manager.py -v
+uv run pytest packages/core/tests/ -k "injection" -v
+```
+
+Core tests should usually exercise core APIs and fixtures rather than subprocess
+CLI calls. See `tests/README.md` for fixture details:
+
+- `test_workspace` creates an isolated workspace.
+- `test_env` creates a minimal environment without cloning ComfyUI.
+- `test_models` creates indexed model stubs.
+- `tests/helpers/` has workflow builders and pyproject assertions.
+
+## Style
+
+- Keep orchestration methods scannable; extract complex decision logic.
+- Prefer guard clauses over nested branches.
+- Avoid state-tracking boolean flags when the actual state can be checked.
+- Keep compatibility/fallback code only when it protects real current behavior.
+- Add focused tests for main paths and important edge cases; avoid large matrices
+  for low-risk changes.

comfygit_core-0.4.0/CLAUDE.md

@@ -0,0 +1,122 @@
+<!-- NOTE: packages/core/AGENTS.md and packages/core/CLAUDE.md must stay in sync. -->
+
+# ComfyGit Core Agent Guide
+
+`packages/core` is the UI-agnostic library package. It owns workspace and
+environment state, manifest semantics, sync/materialization behavior, model and
+node metadata, git orchestration, and callback/protocol contracts used by CLI,
+manager, deploy, and future runtime tooling.
+
+## Active Truth Layer
+
+Read root truth-layer docs before changing core behavior:
+
+- `../../docs/contracts/core/CONTRACT.md` - active core contract and invariants.
+- `../../docs/specs/environment-manifest-model.md` - tracked manifest semantics.
+- `../../docs/specs/environment-sync-lifecycle.md` - sync/run/git lifecycle.
+- `../../docs/specs/dependency-criticality.md` - model/node required vs optional behavior.
+- `../../docs/spec-driven-development.md` - clause syntax and validation rules.
+
+Package docs are supporting reference:
+
+- `docs/architecture.md` - core layer overview.
+- `docs/layer-hierarchy.md` - package-local layering reference.
+- `docs/knowledge/` - topic-specific behavior notes.
+- `docs/plans/` - planning docs; verify against truth-layer clauses before treating as current.
+
+## Core Boundaries
+
+- Keep core independent of CLI, manager UI, and ComfyUI panel rendering.
+- Avoid normal-use `print()` and `input()` in core; expose callbacks,
+  strategies, protocols, return values, and exceptions so callers own UX.
+- Prefer `Workspace` and `Environment` as public entry points. Keep direct manager
+  access for internal composition, tests, and package-local advanced behavior.
+- Do not put service-specific deployment policy into core. Core should
+  write/read portable manifest semantics that runtime adapters can consume.
+
+## Source Map
+
+| Path | Purpose |
+| --- | --- |
+| `src/comfygit_core/core/` | Public `Workspace` and `Environment` APIs. |
+| `src/comfygit_core/managers/` | Stateful orchestration for pyproject, uv, git, nodes, workflows, models, overlays, and symlinks. |
+| `src/comfygit_core/models/` | Dataclasses, protocols, exceptions, manifest/workflow/sync types. |
+| `src/comfygit_core/resolvers/` | Node and model resolution logic. |
+| `src/comfygit_core/services/` | Stateless business logic, registry/model lookup, downloads, workflow services. |
+| `src/comfygit_core/repositories/` | SQLite-backed caches and persistent indexes. |
+| `src/comfygit_core/analyzers/` | Workflow, git, config, model, and custom-node analysis. |
+| `src/comfygit_core/integrations/` | External command integrations such as uv. |
+| `src/comfygit_core/utils/` | Low-level filesystem, git, dependency, PyTorch, retry, and parsing helpers. |
+
+Check existing managers/services before adding new abstractions.
+
+## Key Managers
+
+| Manager | File | Main responsibility |
+| --- | --- | --- |
+| `PyprojectManager` | `managers/pyproject_manager.py` | Manifest CRUD and temporary uv/PyTorch injection. |
+| `UVProjectManager` | `managers/uv_project_manager.py` | uv sync/add/remove operations. |
+| `OverlayManager` | `managers/overlay_manager.py` | Overlay loading and legacy `.local-uv-config` migration. |
+| `PyTorchBackendManager` | `managers/pytorch_backend_manager.py` | `.pytorch-backend`, GPU probing, torch source config. |
+| `NodeManager` | `managers/node_manager.py` | Custom node install/remove/update. |
+| `WorkflowManager` | `managers/workflow_manager.py` | Workflow tracking, node/model resolution, contract metadata. |
+| `EnvironmentModelManager` | `managers/environment_model_manager.py` | Environment-level model status and metadata aggregation. |
+| `GitManager` | `managers/git_manager.py` | Environment repo git operations. |
+| `ExportImportManager` | `managers/export_import_manager.py` | Portable environment import/export. |
+
+## Manifest And Local State
+
+Tracked portable truth lives in each environment repo's `pyproject.toml`.
+Runtime/materialized state lives under environment runtime directories such as
+`.cec/`, virtualenvs, ComfyUI checkouts, symlinks, caches, and local SQLite DBs.
+
+Machine-local sync inputs are not portable manifest truth:
+
+- `.pytorch-backend` stores local torch backend choice and generated source pins.
+- Local uv overrides now flow through overlays, with legacy `.local-uv-config`
+  migrated by `OverlayManager`.
+
+`PyprojectManager.uv_injection_context()` temporarily merges local overlays and
+PyTorch backend config into `pyproject.toml` for uv operations, then restores the
+tracked manifest in a `finally` path. Preserve that invariant.
+
+## Dependency Criticality
+
+Current model criticality supports required, flexible, and optional. Required
+unresolved models are reproducibility blockers; optional unresolved models are
+warnings.
+
+Custom node criticality is planned as explicit manifest metadata:
+
+- Supported values should start as `required` and `optional`.
+- Missing criticality reads as `required`.
+- Optional unresolved nodes warn instead of blocking build readiness.
+- Workflow graph usage can inform UI messaging, but must not silently downgrade
+  user-declared custom node criticality.
+
+## Testing
+
+Run tests from the repo root with uv:
+
+```bash
+uv run pytest packages/core/tests/ -v
+uv run pytest packages/core/tests/unit/managers/test_pyproject_manager.py -v
+uv run pytest packages/core/tests/ -k "injection" -v
+```
+
+Core tests should usually exercise core APIs and fixtures rather than subprocess
+CLI calls. See `tests/README.md` for fixture details:
+
+- `test_workspace` creates an isolated workspace.
+- `test_env` creates a minimal environment without cloning ComfyUI.
+- `test_models` creates indexed model stubs.
+- `tests/helpers/` has workflow builders and pyproject assertions.
+
+## Style
+
+- Keep orchestration methods scannable; extract complex decision logic.
+- Prefer guard clauses over nested branches.
+- Avoid state-tracking boolean flags when the actual state can be checked.
+- Keep compatibility/fallback code only when it protects real current behavior.
+- Add focused tests for main paths and important edge cases; avoid large matrices
+  for low-risk changes.

{comfygit_core-0.3.22 → comfygit_core-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: comfygit-core
-Version: 0.3.22
+Version: 0.4.0
 Summary: ComfyGit Core - Git-based ComfyUI environment manager
 Project-URL: Documentation, https://docs.comfygit.org/
 Project-URL: Repository, https://github.com/comfygit-ai/comfygit
@@ -10,10 +10,10 @@ Requires-Python: >=3.10
 Requires-Dist: blake3>=0.3.3
 Requires-Dist: huggingface-hub>=0.11.0
 Requires-Dist: packaging>=16.2
-Requires-Dist: requests>=2.28.0
+Requires-Dist: requests>=2.33.0
 Requires-Dist: requirements-parser>=0.11.0
 Requires-Dist: tomlkit>=0.11.0
-Requires-Dist: uv>=0.7
+Requires-Dist: uv>=0.11.8
 Requires-Dist: xxhash>=2.0.0
 Description-Content-Type: text/markdown
 

{comfygit_core-0.3.22 → comfygit_core-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "comfygit-core"
-version = "0.3.22"
+version = "0.4.0"
 description = "ComfyGit Core - Git-based ComfyUI environment manager"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -8,10 +8,10 @@ dependencies = [
     "blake3>=0.3.3",
     "huggingface_hub>=0.11.0",
     "packaging>=16.2",
-    "requests>=2.28.0",
+    "requests>=2.33.0",
     "requirements-parser>=0.11.0",
     "tomlkit>=0.11.0",
-    "uv>=0.7",
+    "uv>=0.11.8",
     "xxhash>=2.0.0",
 ]
 
@@ -30,5 +30,5 @@ packages = ["src/comfygit_core"]
 
 [dependency-groups]
 dev = [
-    "pytest>=8.4.1",
+    "pytest>=9.0.3",
 ]

{comfygit_core-0.3.22 → comfygit_core-0.4.0}/src/comfygit_core/analyzers/node_classifier.py

@@ -38,7 +38,8 @@ class NodeClassifier:
     def __init__(
         self,
         cec_path: Path | None = None,
-        builtin_versions_repository: ComfyUIBuiltinVersionsRepository | None = None
+        builtin_versions_repository: ComfyUIBuiltinVersionsRepository | None = None,
+        version_agnostic: bool = False,
     ):
         """
         Initialize node classifier with environment-specific or global builtins.
@@ -48,11 +49,28 @@ class NodeClassifier:
                       If provided, loads from .cec/comfyui_builtins.json.
                       If None or file missing, falls back to global config.
             builtin_versions_repository: Optional repository for version-indexed builtins.
+            version_agnostic: If True, treat ALL known builtins as present regardless
+                              of version. Used for standalone/web analysis where we're
+                              not tied to a specific ComfyUI installation.
         """
         self.builtin_versions_repository = builtin_versions_repository
+        self.version_agnostic = version_agnostic
         self.builtin_nodes, detected_version = self._load_builtin_nodes(cec_path)
         self.comfyui_version = detected_version or self._load_comfyui_version_from_pyproject(cec_path)
 
+        # In version-agnostic mode, expand builtin_nodes to include ALL known builtins
+        # so they classify as "builtin" rather than "version_gated"
+        if self.version_agnostic and self.builtin_versions_repository:
+            db = self.builtin_versions_repository.database
+            if db:
+                extra = set(db.builtins.keys()) - self.builtin_nodes
+                if extra:
+                    logger.debug(
+                        "Version-agnostic mode: adding %d version-indexed builtins to known set",
+                        len(extra),
+                    )
+                    self.builtin_nodes = self.builtin_nodes | extra
+
     def _load_builtin_nodes(self, cec_path: Path | None) -> tuple[set[str], str | None]:
         """Load builtin nodes from environment or global fallback."""
         if cec_path:

{comfygit_core-0.3.22 → comfygit_core-0.4.0}/src/comfygit_core/analyzers/status_scanner.py

@@ -5,6 +5,8 @@ import subprocess
 from pathlib import Path
 from typing import TYPE_CHECKING
 
+from packaging.version import InvalidVersion, Version
+
 from comfygit_core.constants import CUSTOM_NODES_BLACKLIST
 
 from ..logging.logging_config import get_logger
@@ -25,6 +27,20 @@ if TYPE_CHECKING:
 logger = get_logger(__name__)
 
 
+def _versions_match(actual: str | None, expected: str | None) -> bool:
+    """Compare node versions using package-version semantics when possible."""
+    if actual == expected:
+        return True
+
+    if not actual or not expected:
+        return False
+
+    try:
+        return Version(actual) == Version(expected)
+    except InvalidVersion:
+        return False
+
+
 class StatusScanner:
     """Scans environment to get current state."""
 
@@ -359,12 +375,16 @@ class StatusScanner:
             if expected_node.source == 'development':
                 continue
 
-            if expected_node.version and current_node.version != expected_node.version:
+            actual_version = current_node.version
+            if expected_node.source == "git" and current_node.git_commit:
+                actual_version = current_node.git_commit
+
+            if expected_node.version and not _versions_match(actual_version, expected_node.version):
                 comparison.version_mismatches.append(
                     {
                         "name": name,
                         "expected": expected_node.version,
-                        "actual": current_node.version,
+                        "actual": actual_version,
                     }
                 )
 

{comfygit_core-0.3.22 → comfygit_core-0.4.0}/src/comfygit_core/analyzers/workflow_dependency_parser.py

@@ -34,11 +34,13 @@ class WorkflowDependencyParser:
         workflow_name: str | None = None,
         model_config: ModelConfig | None = None,
         cec_path: Path | None = None,
-        builtin_versions_repository: ComfyUIBuiltinVersionsRepository | None = None
+        builtin_versions_repository: ComfyUIBuiltinVersionsRepository | None = None,
+        version_agnostic: bool = False,
     ):
         self.model_config = model_config or ModelConfig.load()
         self.cec_path = cec_path
         self.builtin_versions_repository = builtin_versions_repository
+        self.version_agnostic = version_agnostic
 
         # Accept either Workflow object or Path
         if isinstance(workflow, Path):
@@ -67,7 +69,8 @@ class WorkflowDependencyParser:
             # Create classifier with environment-specific builtins
             classifier = NodeClassifier(
                 self.cec_path,
-                builtin_versions_repository=self.builtin_versions_repository
+                builtin_versions_repository=self.builtin_versions_repository,
+                version_agnostic=self.version_agnostic,
             )
 
             # Analyze and resolve models and nodes

{comfygit_core-0.3.22 → comfygit_core-0.4.0}/src/comfygit_core/caching/workflow_cache.py

@@ -88,6 +88,20 @@ class WorkflowCacheRepository:
         # Ensure schema exists
         self._ensure_schema()
 
+    def _get_current_models_sync_time(self) -> str | None:
+        """Return the model-index sync timestamp that affects resolution caches."""
+        if not self.workspace_config_manager:
+            return None
+
+        try:
+            config = self.workspace_config_manager.load()
+            if config.global_model_directory and config.global_model_directory.last_sync:
+                return config.global_model_directory.last_sync
+        except Exception as e:
+            logger.warning(f"Failed to check current model sync time: {e}")
+
+        return None
+
     def _ensure_schema(self) -> None:
         """Create database schema if needed."""
         # Create schema info table
@@ -209,10 +223,22 @@ class WorkflowCacheRepository:
             logger.warning(f"Failed to stat workflow file {workflow_path}: {e}")
             return None
 
-        # Phase 1: Check session cache (with mtime in key for auto-invalidation)
-        # This ensures session cache automatically invalidates when file changes,
-        # critical for long-running services where Environment instances persist
-        session_key = f"{env_name}:{workflow_name}:{mtime}"
+        pyproject_mtime_for_session = 0.0
+        if pyproject_path and pyproject_path.exists():
+            try:
+                pyproject_mtime_for_session = pyproject_path.stat().st_mtime
+            except OSError as e:
+                logger.debug(f"Could not stat pyproject for session cache key; using default mtime: {e}")
+        current_models_sync_time = self._get_current_models_sync_time()
+
+        # Phase 1: Check session cache. Include every external state value that
+        # can change resolution while workflow bytes stay the same. Long-running
+        # Manager/serve processes otherwise keep stale model resolutions after
+        # pyproject writes or model-index syncs.
+        session_key = (
+            f"{env_name}:{workflow_name}:{mtime}:{size}:"
+            f"{pyproject_mtime_for_session}:{current_models_sync_time}"
+        )
 
         if session_key in self._session_cache:
             elapsed = (time.perf_counter() - start_time) * 1000
@@ -297,15 +323,7 @@ class WorkflowCacheRepository:
             if pyproject_mtime == cached_pyproject_mtime:
                 # Check if model index has changed since cache was created
                 cached_sync_time = cached_row.get('models_sync_time')
-                current_sync_time = None
-
-                if self.workspace_config_manager:
-                    try:
-                        config = self.workspace_config_manager.load()
-                        if config.global_model_directory and config.global_model_directory.last_sync:
-                            current_sync_time = config.global_model_directory.last_sync
-                    except Exception as e:
-                        logger.warning(f"Failed to check current model sync time: {e}")
+                current_sync_time = current_models_sync_time
 
                 # Compare sync times (both might be None, which is fine)
                 if cached_sync_time != current_sync_time:
@@ -418,8 +436,8 @@ class WorkflowCacheRepository:
         if pyproject_path and pyproject_path.exists():
             try:
                 pyproject_mtime = pyproject_path.stat().st_mtime
-            except OSError:
-                pass
+            except OSError as e:
+                logger.debug(f"Could not stat pyproject for persistent cache metadata; using default mtime: {e}")
 
         # Compute resolution context hash
         resolution_context_hash = ""
@@ -430,14 +448,7 @@ class WorkflowCacheRepository:
             )
 
         # Get models_sync_time for cache invalidation check
-        models_sync_time = None
-        if self.workspace_config_manager:
-            try:
-                config = self.workspace_config_manager.load()
-                if config.global_model_directory and config.global_model_directory.last_sync:
-                    models_sync_time = config.global_model_directory.last_sync
-            except Exception:
-                pass
+        models_sync_time = self._get_current_models_sync_time()
 
         # Serialize data
         dependencies_json = self._serialize_dependencies(dependencies)
@@ -460,8 +471,11 @@ class WorkflowCacheRepository:
              dependencies_json, resolution_json, cached_at)
         )
 
-        # Update session cache (with mtime in key for auto-invalidation)
-        session_key = f"{env_name}:{workflow_name}:{workflow_mtime}"
+        # Update session cache with all state that can affect resolution.
+        session_key = (
+            f"{env_name}:{workflow_name}:{workflow_mtime}:{workflow_size}:"
+            f"{pyproject_mtime}:{models_sync_time}"
+        )
         self._session_cache[session_key] = CachedWorkflowAnalysis(
             dependencies=dependencies,
             resolution=resolution,